wiki-formant 0.41.0 → 0.42.0

package/README.md

@@ -731,7 +731,9 @@ return <Stats digest={await digest(sql, q)} {...q} />;
 `PasskeyButton` (`wiki-formant/passkey-button`) is the browser half and has its
 own subpath, because it imports the optional peer `@simplewebauthn/browser`.
 `Stats` (`wiki-formant/stats`) renders a `digest` as one page: the
-headline figures against the window before, one of them per day, every non-empty
+headline figures, each with its change from the window before
+(`.stats-delta[data-better]`, a share or for the bounce rate points, for the
+site's stylesheet to colour), one of them per day, every non-empty
 ranked list, and `?days=` links between windows, all time among them, pinned in
 the chart's frame as its own buttons are (`TimeChart`'s `controls`). Each
 figure is a button that charts it: visitors, page views, bounce rate, visit

package/dist/analytics.d.ts

@@ -113,8 +113,13 @@ export interface Digest {
     visit_duration: number | null;
     /** Visitors plus every agent that sent an event, such as an MCP call. */
     visitors_incl_agents: number;
-    /** Visitors in the same number of days before; null when filtered. */
-    previous_visitors: number | null;
+    /**
+     * The headline figures over the same number of days before, narrowed alike.
+     * A figure is null where that window reaches back past `counted_from` and
+     * the archive cannot stand in for it: event figures always, all of them
+     * when filtered.
+     */
+    previous: Record<'visitors' | 'pageviews' | 'bounce_rate' | 'visit_duration' | 'visitors_incl_agents' | 'follow_clicks', number | null>;
     /** The first UTC day this site counted itself, before which only `ViewDay` speaks; null with no views. */
     counted_from: string | null;
     top_sources: Ranked<'source', 'visitors'>;
@@ -140,6 +145,8 @@ export interface Digest {
  * another day counts once for each day. Days in `ViewDay` add to the visitor,
  * page, visit, source, country, device and per-day figures; events have no
  * history, so an archived day's visitors are its visitors with agents too.
+ * The window before is the same chain of views, visits and events a second
+ * time, `_p` on every name, so its figures are the headline's to the letter.
  */
 export declare function digest(sql: Sql, { site, days, handle, siblings, gaps, ownAgents, filter }: DigestOptions): Promise<Digest>;
 /**

package/dist/analytics.js

@@ -207,6 +207,8 @@ const VISIT_TEST = {
  * another day counts once for each day. Days in `ViewDay` add to the visitor,
  * page, visit, source, country, device and per-day figures; events have no
  * history, so an archived day's visitors are its visitors with agents too.
+ * The window before is the same chain of views, visits and events a second
+ * time, `_p` on every name, so its figures are the headline's to the letter.
  */
 export async function digest(sql, { site = '', days, handle, siblings = [], gaps = [SEARCH_GAPS], ownAgents = ['-mcp-test', 'radix-studio'], filter = {} }) {
     // The window is the database's clock, which stamped the rows; the app's can run behind it.
@@ -226,48 +228,53 @@ export async function digest(sql, { site = '', days, handle, siblings = [], gaps
       WHERE name = ${$(g.event)} AND props @> ${$(JSON.stringify(g.where ?? {}))}::jsonb AND props->>${prop} IS NOT NULL
       GROUP BY 1 ORDER BY 2 DESC, 1 LIMIT 15)`;
     });
-    const [row] = (await sql(`WITH viewed AS (
-      SELECT id, path, source, country, device, visitor, "createdAt" AS at FROM "View"
-      WHERE "siteId" = $1 AND "createdAt" >= now() - make_interval(days => $2::int)
-    ), marked AS (
-      SELECT *, CASE WHEN at - lag(at) OVER (PARTITION BY visitor ORDER BY at, id) <= interval '30 minutes' THEN 0 ELSE 1 END AS starts FROM viewed
-    ), numbered AS (
-      SELECT *, sum(starts) OVER (PARTITION BY visitor ORDER BY at, id) AS visit FROM marked
-    ), visits AS (
+    /**
+     * One window's views, visits, events and archived days as CTEs whose names
+     * end in `s`: this window with `back` 0, the one before it with 1.
+     */
+    const chain = (s, back) => {
+        const ago = (k) => `now() - make_interval(days => ${k} * $2::int)`;
+        const dayAgo = (k) => `(now() AT TIME ZONE 'UTC' - make_interval(days => ${k} * $2::int))::date`;
+        const at = `"createdAt" >= ${ago(back + 1)}${back ? ` AND "createdAt" < ${ago(back)}` : ''}`;
+        return `viewed${s} AS (
+      SELECT id, path, source, country, device, visitor, "createdAt" AS at FROM "View" WHERE "siteId" = $1 AND ${at}
+    ), marked${s} AS (
+      SELECT *, CASE WHEN at - lag(at) OVER (PARTITION BY visitor ORDER BY at, id) <= interval '30 minutes' THEN 0 ELSE 1 END AS starts FROM viewed${s}
+    ), numbered${s} AS (
+      SELECT *, sum(starts) OVER (PARTITION BY visitor ORDER BY at, id) AS visit FROM marked${s}
+    ), visits${s} AS (
       SELECT visitor, visit, min(at) AS at, count(*) AS views, extract(epoch FROM max(at) - min(at)) AS seconds,
         (array_agg(path ORDER BY at, id))[1] AS entry, (array_agg(source ORDER BY at, id))[1] AS source
-      FROM numbered GROUP BY visitor, visit${tests.length ? ` HAVING ${tests.join(' AND ')}` : ''}
-    ), v AS (
-      ${tests.length ? 'SELECT n.id, n.path, n.source, n.country, n.device, n.visitor, n.at FROM numbered n JOIN visits USING (visitor, visit)' : 'SELECT * FROM viewed'}
-    ), e AS (
-      SELECT name, props, visitor, "createdAt" AS at FROM "Event" WHERE "siteId" = $1 AND "createdAt" >= now() - make_interval(days => $2::int)
-      ${tests.length ? 'AND visitor IN (SELECT visitor FROM v)' : ''}
-    ), a AS (
-      SELECT * FROM "ViewDay" WHERE "siteId" = $1 AND day >= (now() AT TIME ZONE 'UTC' - make_interval(days => $2::int))::date${tests.length ? ' AND false' : ''}
-    ), sessions AS (
+      FROM numbered${s} GROUP BY visitor, visit${tests.length ? ` HAVING ${tests.join(' AND ')}` : ''}
+    ), v${s} AS (
+      ${tests.length ? `SELECT n.id, n.path, n.source, n.country, n.device, n.visitor, n.at FROM numbered${s} n JOIN visits${s} USING (visitor, visit)` : `SELECT * FROM viewed${s}`}
+    ), e${s} AS (
+      SELECT name, props, visitor, "createdAt" AS at FROM "Event" WHERE "siteId" = $1 AND ${at}
+      ${tests.length ? `AND visitor IN (SELECT visitor FROM v${s})` : ''}
+    ), a${s} AS (
+      SELECT * FROM "ViewDay" WHERE "siteId" = $1 AND day >= ${dayAgo(back + 1)}${back ? ` AND day < ${dayAgo(back)}` : ''}${tests.length ? ' AND false' : ''}
+    ), sessions${s} AS (
       SELECT sum(bounces) AS bounces, sum(visits) AS visits, sum(seconds) AS seconds FROM (
-        SELECT count(*) FILTER (WHERE views = 1), count(*), coalesce(sum(seconds), 0) FROM visits
-        UNION ALL SELECT coalesce(sum(bounces), 0), coalesce(sum(visits), 0), coalesce(sum(seconds), 0) FROM a
-      ) s(bounces, visits, seconds)
-    ), src AS (
+        SELECT count(*) FILTER (WHERE views = 1), count(*), coalesce(sum(seconds), 0) FROM visits${s}
+        UNION ALL SELECT coalesce(sum(bounces), 0), coalesce(sum(visits), 0), coalesce(sum(seconds), 0) FROM a${s}
+      ) t(bounces, visits, seconds)
+    ), archived${s} AS (
+      SELECT coalesce(sum(visitors), 0) AS visitors, coalesce(sum(pageviews), 0) AS pageviews FROM a${s}
+    )`;
+    };
+    /** One window's headline figures, as `json_build_object` arguments. */
+    const headline = (s) => `'visitors', (SELECT count(DISTINCT visitor) FROM v${s}) + (SELECT visitors FROM archived${s}),
+      'pageviews', (SELECT count(*) FROM v${s}) + (SELECT pageviews FROM archived${s}),
+      'bounce_rate', (SELECT round(100.0 * bounces / nullif(visits, 0)) FROM sessions${s}),
+      'visit_duration', (SELECT round(seconds / nullif(visits, 0)) FROM sessions${s}),
+      'visitors_incl_agents', (SELECT count(DISTINCT visitor) FROM (SELECT visitor FROM v${s} UNION SELECT visitor FROM e${s}) u) + (SELECT visitors FROM archived${s})`;
+    const [row] = (await sql(`WITH ${chain('', 0)}, ${chain('_p', 1)}, src AS (
       SELECT coalesce(source, '(none)') AS source, count(DISTINCT visitor) AS visitors FROM visits GROUP BY 1
       UNION ALL SELECT key, value::int FROM a, jsonb_each_text(a.sources)
-    ), archived AS (
-      SELECT coalesce(sum(visitors), 0) AS visitors, coalesce(sum(pageviews), 0) AS pageviews FROM a
     )
     SELECT json_build_object(
-      'visitors', (SELECT count(DISTINCT visitor) FROM v) + (SELECT visitors FROM archived),
-      'pageviews', (SELECT count(*) FROM v) + (SELECT pageviews FROM archived),
-      'bounce_rate', (SELECT round(100.0 * bounces / nullif(visits, 0)) FROM sessions),
-      'visit_duration', (SELECT round(seconds / nullif(visits, 0)) FROM sessions),
-      'visitors_incl_agents', (SELECT count(DISTINCT visitor) FROM (SELECT visitor FROM v UNION SELECT visitor FROM e) u) + (SELECT visitors FROM archived),
-      'previous_visitors', ${tests.length
-        ? 'NULL'
-        : `(SELECT count(DISTINCT visitor) FROM "View"
-        WHERE "siteId" = $1 AND "createdAt" >= now() - make_interval(days => 2 * $2::int) AND "createdAt" < now() - make_interval(days => $2::int))
-        + (SELECT coalesce(sum(visitors), 0) FROM "ViewDay" WHERE "siteId" = $1
-          AND day >= (now() AT TIME ZONE 'UTC' - make_interval(days => 2 * $2::int))::date
-          AND day < (now() AT TIME ZONE 'UTC' - make_interval(days => $2::int))::date)`},
+      ${headline('')},
+      'previous', json_build_object(${headline('_p')}, 'follow_clicks', ${follows ? `(SELECT count(*) FROM e_p WHERE ${follows})` : 'NULL'}),
       'counted_from', (SELECT ${day('min("createdAt")')} FROM "View" WHERE "siteId" = $1),
       'top_sources', ${list('SELECT source, sum(visitors) AS visitors FROM src GROUP BY 1', 6)},
       'top_pages', ${list(merged('page', 'pages', 'SELECT path, count(DISTINCT visitor) FROM v GROUP BY 1'), 6)},
@@ -291,7 +298,19 @@ export async function digest(sql, { site = '', days, handle, siblings = [], gaps
          GROUP BY 1`, 10)},
       'gaps', ${gapSelects.length ? `(SELECT coalesce(json_agg(t), '[]') FROM (${gapSelects.join(' UNION ALL ')}) t)` : `'[]'::json`}
     ) AS digest`, ...values));
-    return row.digest;
+    const d = row.digest;
+    // Before the site counted itself only ViewDay speaks, and it holds no
+    // events and no visits a filter could pick out.
+    const before = new Date(Date.now() - 2 * values[1] * 86_400_000).toISOString().slice(0, 10);
+    if (d.counted_from && before < d.counted_from) {
+        const p = d.previous;
+        if (tests.length)
+            for (const k of Object.keys(p))
+                p[k] = null;
+        else
+            p.visitors_incl_agents = p.follow_clicks = null;
+    }
+    return d;
 }
 /**
  * Props for an "MCP Call" event, read out of the JSON-RPC envelope.

package/dist/base.css

@@ -218,6 +218,7 @@ pre:hover > .code-copy-btn,
 }
 .stats-figures button[aria-pressed='true'] { opacity: 1; }
 .stats-figures strong { font-variant-numeric: tabular-nums; }
+.stats-delta { margin-inline-start: 0.4em; }
 .stats-lists {
   display: grid;
   grid-template-columns: repeat(auto-fit, minmax(min(100%, 18rem), 1fr));

package/dist/stats-figures.d.ts

@@ -1,7 +1,8 @@
 import { type ReactNode } from 'react';
 import type { Digest } from './analytics.js';
 /**
- * The figures as `.stats-figures button[aria-pressed]` and the pressed one per
+ * The figures as `.stats-figures button[aria-pressed]`, each with its change
+ * as `.stats-delta[data-better]` for a stylesheet to colour, and the pressed one per
  * day from `first` (a UTC day number) to today. A count's empty day is a zero;
  * a rate's is left out, since no visits is not a bounce rate of nothing.
  */

package/dist/stats-figures.js

@@ -9,35 +9,58 @@ import { TimeChart } from './chart.js';
 const count = (n) => n.toLocaleString('en');
 const duration = (s) => (s < 60 ? `${Math.round(s)}s` : `${Math.floor(s / 60)}m ${Math.round(s % 60)}s`);
 const percent = (n) => `${Math.round(n)}%`;
-/** Unsigned at zero, so no change never reads as growth. */
-const change = (now, before) => {
-    if (!before)
+/**
+ * The change from the window before: a share of the figure before, or for a
+ * rate its difference in points, since a bounce rate up 10% of itself reads
+ * as ten points. Unsigned and unmarked at zero, so no change never reads as
+ * growth. A lower bounce rate is the better one; every other figure, higher.
+ */
+function change(now, before, { points = false, lowerIsBetter = false } = {}) {
+    if (now == null || before == null || (!points && !before))
         return null;
-    const pct = Math.round((100 * (now - before)) / before);
-    return pct > 0 ? `+${pct}%` : `${pct}%`;
-};
-const figuresOf = (d) => [
-    { label: 'Visitors', value: count(d.visitors), delta: change(d.visitors, d.previous_visitors), day: r => r.visitors },
-    { label: 'Page views', value: count(d.pageviews), day: r => r.pageviews },
+    const n = Math.round(points ? now - before : (100 * (now - before)) / before);
+    const text = `${n > 0 ? '+' : ''}${n}${points ? ' pp' : '%'}`;
+    return n ? { text, better: n > 0 !== lowerIsBetter } : { text };
+}
+const figuresOf = ({ previous: p, ...d }) => [
+    { label: 'Visitors', value: count(d.visitors), delta: change(d.visitors, p.visitors), day: r => r.visitors },
+    { label: 'Page views', value: count(d.pageviews), delta: change(d.pageviews, p.pageviews), day: r => r.pageviews },
     {
         label: 'Bounce rate',
         value: d.bounce_rate == null ? '–' : percent(d.bounce_rate),
+        delta: change(d.bounce_rate, p.bounce_rate, { points: true, lowerIsBetter: true }),
         day: r => (r.visits ? (100 * r.bounces) / r.visits : null),
         format: percent,
     },
     {
         label: 'Visit length',
         value: d.visit_duration == null ? '–' : duration(d.visit_duration),
+        delta: change(d.visit_duration, p.visit_duration),
         day: r => (r.visits ? r.seconds / r.visits : null),
         format: duration,
     },
-    { label: 'With agents', value: count(d.visitors_incl_agents), day: r => r.visitors_incl_agents },
-    ...(d.follow_clicks ? [{ label: 'Clicks to X', value: count(d.follow_clicks.events), day: (r) => r.follow_clicks }] : []),
+    {
+        label: 'With agents',
+        value: count(d.visitors_incl_agents),
+        delta: change(d.visitors_incl_agents, p.visitors_incl_agents),
+        day: r => r.visitors_incl_agents,
+    },
+    ...(d.follow_clicks
+        ? [
+            {
+                label: 'Clicks to X',
+                value: count(d.follow_clicks.events),
+                delta: change(d.follow_clicks.events, p.follow_clicks),
+                day: (r) => r.follow_clicks,
+            },
+        ]
+        : []),
 ];
 const DAY = 86_400;
 const EMPTY = { date: '', visitors: 0, pageviews: 0, visits: 0, bounces: 0, seconds: 0, visitors_incl_agents: 0, follow_clicks: 0 };
 /**
- * The figures as `.stats-figures button[aria-pressed]` and the pressed one per
+ * The figures as `.stats-figures button[aria-pressed]`, each with its change
+ * as `.stats-delta[data-better]` for a stylesheet to colour, and the pressed one per
  * day from `first` (a UTC day number) to today. A count's empty day is a zero;
  * a rate's is left out, since no visits is not a bounce rate of nothing.
  */
@@ -54,5 +77,5 @@ export function StatsFigures({ digest, first, windows }) {
             return value == null ? null : { time, value };
         }).filter(p => p !== null);
     }, [byDay, first, figure]);
-    return (_jsxs(_Fragment, { children: [_jsx("div", { className: "stats-figures", role: "group", "aria-label": "Chart", children: figures.map((f, i) => (_jsxs("button", { type: "button", "aria-pressed": i === chosen, onClick: () => choose(i), children: [_jsx("span", { children: f.label }), _jsxs("strong", { children: [f.value, f.delta && _jsx("small", { children: ` ${f.delta}` })] })] }, f.label))) }), _jsx(TimeChart, { series: series, label: `${figure.label} per day`, ranges: ['all'], aggregate: "mean", fromZero: true, format: figure.format, controls: windows, className: "stats-chart" })] }));
+    return (_jsxs(_Fragment, { children: [_jsx("div", { className: "stats-figures", role: "group", "aria-label": "Chart", children: figures.map((f, i) => (_jsxs("button", { type: "button", "aria-pressed": i === chosen, onClick: () => choose(i), children: [_jsx("span", { children: f.label }), _jsxs("strong", { children: [f.value, f.delta && (_jsx("small", { className: "stats-delta", "data-better": f.delta.better, children: f.delta.text }))] })] }, f.label))) }), _jsx(TimeChart, { series: series, label: `${figure.label} per day`, ranges: ['all'], aggregate: "mean", fromZero: true, format: figure.format, controls: windows, className: "stats-chart" })] }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, conditional-GET plumbing, and the headers and CSP every origin sends.",
   "type": "module",
   "license": "MIT",