wiki-formant 0.39.0 → 0.40.0

package/README.md

@@ -724,8 +724,8 @@ export const POST = gate.route;
 // src/app/stats/page.tsx
 if (!(await gate.signedIn((await cookies()).get(gate.cookie)?.value)))
   return <PasskeyButton endpoint="/api/passkey" invite={invite} create={await gate.open()} />;
-const days = statsDays((await searchParams).days); // 1, 7, 30, 90, 365 or Infinity (?days=all), else 30
-return <Stats digest={await digest(sql, { days })} days={days} />;
+const q = statsQuery(await searchParams); // ?days= (1, 7, 30, 90, 365 or all, else 30) and the filters
+return <Stats digest={await digest(sql, q)} {...q} />;
 ```
 
 `PasskeyButton` (`wiki-formant/passkey-button`) is the browser half and has its
@@ -738,7 +738,17 @@ length, visitors with agents and clicks to X. `digest`'s `by_day` carries every
 one of those per UTC day, a visit on the day it began, so the days add up to the
 totals. A day with no visits has no bounce rate or visit length and is left out
 of those charts rather than drawn as zero. Everything but the figures and the
-chart is server-rendered. The chart is `TimeChart` with a count
+chart is server-rendered.
+
+Every row in a list is a link that narrows the page to it, and the narrowings
+stack: `?page=`, `?entry=`, `?source=`, `?country=` and `?device=`, each shown as
+a chip that drops it. A narrowing keeps the visits that pass – that saw the
+page, began on it, came from the source, or were made from the country or
+device – and recounts every figure, list and day from those visits alone, with
+events only from their visitors. Agent tool calls and missed searches are
+events no visit reaches, so their rows are not links. `ViewDay` keeps totals,
+not visits, so a narrowed page starts at `counted_from`, the first day the site
+counted itself, says so, and drops the comparison with the window before. The chart is `TimeChart` with a count
 axis from zero, so `lightweight-charts` is an optional peer that a stats page
 needs installed.
 

package/dist/analytics.d.ts

@@ -65,6 +65,9 @@ export interface Gap {
 }
 /** Searches in a wiki's own search box that found nothing (`searchQueryProps` events). */
 export declare const SEARCH_GAPS: Gap;
+/** What a stats page can be narrowed to: one value each, every one applied. */
+export declare const STATS_FILTERS: readonly ["page", "entry", "source", "country", "device"];
+export type StatsFilter = Partial<Record<(typeof STATS_FILTERS)[number], string>>;
 export interface DigestOptions {
     site?: string;
     /** How far back, in whole days from now; `Infinity` for all time. */
@@ -79,6 +82,12 @@ export interface DigestOptions {
      * The default is the conformance suites (`<repo>-mcp-test`) and the studio's own tools.
      */
     ownAgents?: string[];
+    /**
+     * Narrows every figure to the visits that pass, and the events to their
+     * visitors. `ViewDay` keeps no visits, so a narrowed digest leaves it out
+     * and starts at `counted_from`, and has no `previous_visitors`.
+     */
+    filter?: StatsFilter;
 }
 type Ranked<K extends string, M extends string> = Array<Record<K, string> & Record<M, number>>;
 /** One UTC day of the figures a digest totals; a visit falls on the day it began. */
@@ -104,8 +113,10 @@ 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. */
-    previous_visitors: number;
+    /** Visitors in the same number of days before; null when filtered. */
+    previous_visitors: 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'>;
     top_pages: Ranked<'page', 'visitors'>;
     entry_pages: Ranked<'page', 'visitors'>;
@@ -130,7 +141,7 @@ export interface Digest {
  * 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.
  */
-export declare function digest(sql: Sql, { site, days, handle, siblings, gaps, ownAgents }: DigestOptions): Promise<Digest>;
+export declare function digest(sql: Sql, { site, days, handle, siblings, gaps, ownAgents, filter }: DigestOptions): Promise<Digest>;
 /**
  * Props for an "MCP Call" event, read out of the JSON-RPC envelope.
  *

package/dist/analytics.js

@@ -188,6 +188,19 @@ export async function collect(request, { sql, defer, site, rateLimit: limit = BE
 }
 /** Searches in a wiki's own search box that found nothing (`searchQueryProps` events). */
 export const SEARCH_GAPS = { event: 'Search Query', prop: 'q', where: { results: '0', surface: 'wiki' } };
+/** What a stats page can be narrowed to: one value each, every one applied. */
+export const STATS_FILTERS = ['page', 'entry', 'source', 'country', 'device'];
+/**
+ * Each filter as a test on one visit. A page, country or device is any of the
+ * visit's views; an entry page or a source is its first. `(none)` is no source.
+ */
+const VISIT_TEST = {
+    page: v => `bool_or(path = ${v})`,
+    entry: v => `(array_agg(path ORDER BY at, id))[1] = ${v}`,
+    source: v => `coalesce((array_agg(source ORDER BY at, id))[1], '(none)') = ${v}`,
+    country: v => `bool_or(country = ${v})`,
+    device: v => `bool_or(device = ${v})`,
+};
 /**
  * Everything a report needs about one site's last `days` days, in one query.
  * Visitor figures count distinct visitors, so a person who comes back on
@@ -195,7 +208,7 @@ export const SEARCH_GAPS = { event: 'Search Query', prop: 'q', where: { results:
  * 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.
  */
-export async function digest(sql, { site = '', days, handle, siblings = [], gaps = [SEARCH_GAPS], ownAgents = ['-mcp-test', 'radix-studio'] }) {
+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.
     // All time is a century: further back than any row, and still an int to Postgres.
     const values = [site, Number.isFinite(days) ? Math.max(1, Math.round(days)) : 36_500];
@@ -205,6 +218,7 @@ export async function digest(sql, { site = '', days, handle, siblings = [], gaps
     const merged = (label, column, live) => `SELECT k AS ${label}, sum(n) AS visitors FROM (${live} UNION ALL SELECT key, value::int FROM a, jsonb_each_text(a."${column}")) t(k, n) GROUP BY 1`;
     /** Clicks on links to the site's own X account, among `e`. */
     const follows = handle && `name = 'Outbound Link: Click' AND props->>'url' ILIKE ANY(${$([`%x.com/${handle}%`, `%twitter.com/${handle}%`])}::text[])`;
+    const tests = STATS_FILTERS.flatMap(k => (filter[k] ? [VISIT_TEST[k]($(filter[k]))] : []));
     const day = (at) => `to_char(${at} AT TIME ZONE 'UTC', 'YYYY-MM-DD')`;
     const gapSelects = gaps.map(g => {
         const prop = $(g.prop);
@@ -212,21 +226,24 @@ 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 v AS (
+    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 v
+      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 (
-      SELECT visitor, min(at) AS at, count(*) AS views, extract(epoch FROM max(at) - min(at)) AS seconds,
+      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
+      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
+      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 (
       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
@@ -244,11 +261,14 @@ export async function digest(sql, { site = '', days, handle, siblings = [], gaps
       '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', (SELECT count(DISTINCT visitor) FROM "View"
+      '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),
+          AND day < (now() AT TIME ZONE 'UTC' - make_interval(days => $2::int))::date)`},
+      '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)},
       'entry_pages', ${list(merged('page', 'entryPages', 'SELECT entry, count(DISTINCT visitor) FROM visits GROUP BY 1'), 6)},

package/dist/base.css

@@ -242,4 +242,12 @@ pre:hover > .code-copy-btn,
   pointer-events: none;
 }
 .stats-list li > span:first-child { min-width: 0; overflow-wrap: anywhere; }
+/* A row narrows the page to itself; the whole row is the link. */
+.stats-list a { color: inherit; text-decoration: none; }
+.stats-list a::after { content: ''; position: absolute; inset: 0; }
+.stats-list a:is(:hover, :focus-visible) { text-decoration: underline; text-underline-offset: 0.2em; }
+.stats-filters { display: grid; gap: 0.5rem; }
+.stats-filters ul { display: flex; flex-wrap: wrap; gap: 0.5rem; margin: 0; padding: 0; list-style: none; }
+.stats-filters a { display: inline-block; padding: 0.25em 0.75em; border: 1px solid; border-radius: 9999px; text-decoration: none; }
+.stats-filters p { margin: 0; opacity: 0.7; }
 .stats-count { font-variant-numeric: tabular-nums; }

package/dist/stats.d.ts

@@ -1,20 +1,32 @@
-import type { Digest } from './analytics.js';
+import { type Digest, type StatsFilter } from './analytics.js';
 export interface StatsProps {
     /** One window's figures, from `digest` in `wiki-formant/analytics`. */
     digest: Digest;
     /** The window the digest covers, in days; `Infinity` for all time. */
     days: number;
+    /** What the digest was narrowed to, as `digest` was given it. */
+    filter?: StatsFilter;
     /** The windows offered as `?days=` links on the same page. */
     ranges?: readonly number[];
 }
 /** The windows the stats page offers, in days; `Infinity` is all time. */
 export declare const STATS_RANGES: readonly [1, 7, 30, 90, 365, number];
-/** A `?days=` value as one of `ranges`, else `fallback`: the page's only input. */
+/** A `?days=` value as one of `ranges`, else `fallback`. */
 export declare const statsDays: (param: unknown, ranges?: readonly number[], fallback?: number) => number;
+/**
+ * A stats page's query as the window and the filter, both ready for `digest`
+ * and `Stats`: `const q = statsQuery(await searchParams)`. A repeated or empty
+ * parameter is ignored.
+ */
+export declare function statsQuery(params: Record<string, string | string[] | undefined>, ranges?: readonly number[]): {
+    days: number;
+    filter: Partial<Record<"page" | "entry" | "source" | "country" | "device", string>>;
+};
 /**
  * A site's own analytics on one page: the headline figures against the window
  * before, whichever of them is chosen per day, and every ranked list the
- * digest carries. Lists with nothing in them are left out. The chart and the
- * bars are `currentColor` until the importing stylesheet gives them a colour.
+ * digest carries, each row a link that narrows the page to it. Lists with
+ * nothing in them are left out. The chart and the bars are `currentColor`
+ * until the importing stylesheet gives them a colour.
  */
-export declare function Stats({ digest: d, days, ranges }: StatsProps): import("react").JSX.Element;
+export declare function Stats({ digest: d, days, filter, ranges }: StatsProps): import("react").JSX.Element;

package/dist/stats.js

@@ -1,11 +1,34 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { STATS_FILTERS } from './analytics.js';
 import { StatsFigures } from './stats-figures.js';
 /** The windows the stats page offers, in days; `Infinity` is all time. */
 export const STATS_RANGES = [1, 7, 30, 90, 365, Infinity];
 /** A window as its `?days=` value. */
 const daysParam = (n) => (Number.isFinite(n) ? String(n) : 'all');
-/** A `?days=` value as one of `ranges`, else `fallback`: the page's only input. */
+/** A `?days=` value as one of `ranges`, else `fallback`. */
 export const statsDays = (param, ranges = STATS_RANGES, fallback = 30) => ranges.find(n => daysParam(n) === param) ?? fallback;
+/**
+ * A stats page's query as the window and the filter, both ready for `digest`
+ * and `Stats`: `const q = statsQuery(await searchParams)`. A repeated or empty
+ * parameter is ignored.
+ */
+export function statsQuery(params, ranges = STATS_RANGES) {
+    const filter = {};
+    for (const k of STATS_FILTERS) {
+        const v = params[k];
+        if (typeof v === 'string' && v)
+            filter[k] = v.slice(0, 500);
+    }
+    return { days: statsDays(params.days, ranges), filter };
+}
+/** The page at a window and a filter, as a query string. */
+const href = (days, filter) => {
+    const q = new URLSearchParams({ days: daysParam(days) });
+    for (const k of STATS_FILTERS)
+        if (filter[k])
+            q.set(k, filter[k]);
+    return `?${q}`;
+};
 const count = (n) => n.toLocaleString('en');
 const regions = new Intl.DisplayNames(['en'], { type: 'region' });
 const country = (code) => {
@@ -16,23 +39,33 @@ const country = (code) => {
         return code;
     }
 };
-function StatsList({ title, rows, label = v => v }) {
+const NAMES = { page: 'Page', entry: 'Entry page', source: 'Source', country: 'Country', device: 'Device' };
+const DAY_MS = 86_400_000;
+function StatsList({ title, rows, label = v => v, to, }) {
     if (!rows.length)
         return null;
     const max = Math.max(...rows.map(([, n]) => n));
-    return (_jsxs("section", { className: "stats-list", children: [_jsx("h2", { children: title }), _jsx("ol", { children: rows.map(([v, n]) => (_jsxs("li", { style: { '--share': n / max }, children: [_jsx("span", { children: label(v) }), _jsx("span", { className: "stats-count", children: count(n) })] }, v))) })] }));
+    return (_jsxs("section", { className: "stats-list", children: [_jsx("h2", { children: title }), _jsx("ol", { children: rows.map(([v, n]) => (_jsxs("li", { style: { '--share': n / max }, children: [_jsx("span", { children: to ? _jsx("a", { href: to(v), children: label(v) }) : label(v) }), _jsx("span", { className: "stats-count", children: count(n) })] }, v))) })] }));
 }
 /**
  * A site's own analytics on one page: the headline figures against the window
  * before, whichever of them is chosen per day, and every ranked list the
- * digest carries. Lists with nothing in them are left out. The chart and the
- * bars are `currentColor` until the importing stylesheet gives them a colour.
+ * digest carries, each row a link that narrows the page to it. Lists with
+ * nothing in them are left out. The chart and the bars are `currentColor`
+ * until the importing stylesheet gives them a colour.
  */
-export function Stats({ digest: d, days, ranges = STATS_RANGES }) {
+export function Stats({ digest: d, days, filter = {}, ranges = STATS_RANGES }) {
+    const today = Math.floor(Date.now() / DAY_MS);
+    const counted = d.counted_from ? Date.parse(d.counted_from) / DAY_MS : today;
+    const narrowed = STATS_FILTERS.filter(k => filter[k]);
     // A rolling window of n days touches n + 1 UTC dates, the first of them in
-    // part. All time starts at the first day anything was counted.
-    const today = Math.floor(Date.now() / 86_400_000);
-    const first = Number.isFinite(days) ? today - days : Math.min(today, ...d.by_day.map(r => Date.parse(r.date) / 86_400_000));
+    // part. All time starts at the first day anything was counted, and a
+    // narrowed window at the first day the site counted itself.
+    const start = Number.isFinite(days) ? today - days : -Infinity;
+    const first = narrowed.length
+        ? Math.max(start, counted)
+        : Number.isFinite(start) ? start : Math.min(today, ...d.by_day.map(r => Date.parse(r.date) / DAY_MS));
     const rows = (list, k, m) => list.map(r => [r[k], r[m]]);
-    return (_jsxs("div", { className: "stats", children: [_jsx("nav", { className: "stats-ranges", "aria-label": "Window", children: ranges.map(n => (_jsx("a", { href: `?days=${daysParam(n)}`, "aria-current": n === days ? 'page' : undefined, children: n === 1 ? '24 hours' : Number.isFinite(n) ? `${n} days` : 'All time' }, n))) }), _jsx(StatsFigures, { digest: d, first: first }), _jsxs("div", { className: "stats-lists", children: [_jsx(StatsList, { title: "Pages", rows: rows(d.top_pages, 'page', 'visitors') }), _jsx(StatsList, { title: "Entry pages", rows: rows(d.entry_pages, 'page', 'visitors') }), _jsx(StatsList, { title: "Sources", rows: rows(d.top_sources, 'source', 'visitors') }), _jsx(StatsList, { title: "From X posts", rows: rows(d.from_posts, 'page', 'visitors') }), _jsx(StatsList, { title: "Sibling sites", rows: rows(d.sibling_referrals, 'source', 'visitors') }), _jsx(StatsList, { title: "Countries", rows: rows(d.countries, 'country', 'visitors'), label: country }), _jsx(StatsList, { title: "Devices", rows: rows(d.devices, 'device', 'visitors') }), _jsx(StatsList, { title: "Agent tool calls", rows: rows(d.agent_tool_calls, 'tool', 'events') }), _jsx(StatsList, { title: "Searches that found nothing", rows: rows(d.gaps, 'query', 'events') })] })] }));
+    const to = (k) => (v) => href(days, { ...filter, [k]: v });
+    return (_jsxs("div", { className: "stats", children: [_jsx("nav", { className: "stats-ranges", "aria-label": "Window", children: ranges.map(n => (_jsx("a", { href: href(n, filter), "aria-current": n === days ? 'page' : undefined, children: n === 1 ? '24 hours' : Number.isFinite(n) ? `${n} days` : 'All time' }, n))) }), narrowed.length > 0 && (_jsxs("div", { className: "stats-filters", children: [_jsx("ul", { "aria-label": "Narrowed to", children: narrowed.map(k => (_jsx("li", { children: _jsxs("a", { href: href(days, { ...filter, [k]: undefined }), title: "Remove", children: [NAMES[k], ": ", k === 'country' ? country(filter[k]) : filter[k], " \u00D7"] }) }, k))) }), start < counted && d.counted_from && (_jsxs("p", { children: ["Narrowed figures start on ", d.counted_from, ", the first day this site counted its own visits."] }))] })), _jsx(StatsFigures, { digest: d, first: first }), _jsxs("div", { className: "stats-lists", children: [_jsx(StatsList, { title: "Pages", rows: rows(d.top_pages, 'page', 'visitors'), to: to('page') }), _jsx(StatsList, { title: "Entry pages", rows: rows(d.entry_pages, 'page', 'visitors'), to: to('entry') }), _jsx(StatsList, { title: "Sources", rows: rows(d.top_sources, 'source', 'visitors'), to: to('source') }), _jsx(StatsList, { title: "From X posts", rows: rows(d.from_posts, 'page', 'visitors'), to: v => href(days, { ...filter, source: 'x', entry: v }) }), _jsx(StatsList, { title: "Sibling sites", rows: rows(d.sibling_referrals, 'source', 'visitors'), to: to('source') }), _jsx(StatsList, { title: "Countries", rows: rows(d.countries, 'country', 'visitors'), label: country, to: to('country') }), _jsx(StatsList, { title: "Devices", rows: rows(d.devices, 'device', 'visitors'), to: to('device') }), _jsx(StatsList, { title: "Agent tool calls", rows: rows(d.agent_tool_calls, 'tool', 'events') }), _jsx(StatsList, { title: "Searches that found nothing", rows: rows(d.gaps, 'query', 'events') })] })] }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.39.0",
+  "version": "0.40.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",