wiki-formant 0.92.0 → 0.94.0

package/README.md

@@ -957,7 +957,10 @@ An agent is counted as a visitor is, one address and user agent a day, from its
 `AI Bot Visit` and `MCP Call` events; it runs no page script, so it is never
 among the visitors, and `visitors_incl_agents` counts the two at once.
 `ownAgents` leaves the site's own out of both. A visit is a run of one
-visitor's views with no gap over 30 minutes. A multi-tenant app passes a `site`
+visitor's views with no gap over 30 minutes, and a bounce is a visit of one view
+with no event of the reader's inside it: a search that keeps the path, a click
+out or a share makes the visit count. A browser under automation
+(`navigator.webdriver`) sends no beacon at all. A multi-tenant app passes a `site`
 key to every call and a `site` resolver to `collect`.
 
 Instrumenting the agent lane and not the human one is the easy mistake: it
@@ -1081,7 +1084,8 @@ which no total makes sense of. A stepped range starts on a whole week or month,
 so its first point is not a few days of one; the week in progress is its total
 so far. `fromZero` starts a count's axis at zero and stops it there, with
 no negative ticks under it. A single range draws no range buttons and shows every point.
-`chartSteps` is exported for a chart drawn elsewhere.
+No step is finer than the points' own spacing, so weekly readings offer W and M
+and draw on the days they were taken. `chartSteps` is exported for a chart drawn elsewhere.
 
 `format` writes the axis and the crosshair label. An axis tick also gets the
 spacing between ticks as a second argument, so a formatter can write every tick
@@ -1090,13 +1094,15 @@ decimal places that takes, and `formatChartValue`, the default, uses it.
 
 `markers` are events, `{ time, label }`, each drawn as an arrow on the last
 point at or before it, so one mid-week lands on its week and two on one point
-share it. `step` opens on a step where the
-range can make it, and `onView` hears the range and step on mount and on every
-change, for a page that keeps them in its URL:
+share it. No words go on the plot: the label is a tooltip (`.chart-tip`) while
+the crosshair is on the point, one line an event, so it can be the event's full
+name. `step` opens on a step where the range can make it, and `onView` hears the
+range, and the step the reader picked (null while the chart picks its own), once
+the points are in and on every change, for a page that keeps them in its URL:
 
 ```tsx
 <TimeChart series={days} label="Transactions" aggregate="sum" fromZero
-  markers={[{ time: haltAt, label: 'Halt' }]} step="month" onView={v => keep(v)} />
+  markers={[{ time: haltAt, label: 'Network halt' }]} step="month" onView={v => keep(v)} />
 ```
 `base.css` pins the buttons (`.chart-controls button[aria-pressed]`) to the
 canvas's top-left corner, rules a line between groups and dims a disabled step;

package/dist/analytics.d.ts

@@ -89,7 +89,7 @@ export interface DigestDay {
     visitors: number;
     pageviews: number;
     visits: number;
-    /** Visits that saw one page. */
+    /** Visits that saw one page and did nothing else: a search, a click out or any reader event makes it a visit. */
     bounces: number;
     /** Seconds from each visit's first view to its last, summed. */
     seconds: number;
@@ -101,7 +101,7 @@ export interface DigestDay {
 export interface Digest {
     visitors: number;
     pageviews: number;
-    /** Percent of visits that saw one page; null with no visits. */
+    /** Percent of visits that are bounces (`DigestDay.bounces`); null with no visits. */
     bounce_rate: number | null;
     /** Mean seconds from a visit's first view to its last; null with no visits. */
     visit_duration: number | null;

package/dist/analytics.js

@@ -223,6 +223,10 @@ export async function digest(sql, { site = '', days, handle, siblings = [], gaps
     ), 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})` : ''}
+    ), bounced${s} AS (
+      SELECT * FROM visits${s} b WHERE views = 1 AND NOT EXISTS (
+        SELECT 1 FROM e${s} x WHERE x.visitor = b.visitor AND x.name NOT IN ('AI Bot Visit', 'MCP Call')
+        AND x.at >= b.at AND x.at < b.at + interval '30 minutes')
     ), ag${s} AS (
       SELECT visitor, at, ${AGENT_NAME} AS agent FROM e${s}
       WHERE name IN ('AI Bot Visit', 'MCP Call') AND visitor IS NOT NULL AND NOT ${ours}
@@ -230,7 +234,7 @@ export async function digest(sql, { site = '', days, handle, siblings = [], gaps
       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${s}
+        SELECT (SELECT count(*) FROM bounced${s}), 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 (
@@ -262,7 +266,8 @@ export async function digest(sql, { site = '', days, handle, siblings = [], gaps
       'by_day', ${list(`SELECT date, sum(visitors) AS visitors, sum(pageviews) AS pageviews, sum(visits) AS visits, sum(bounces) AS bounces,
           sum(seconds) AS seconds, sum(agents) AS agents, sum(everyone) AS visitors_incl_agents, sum(follows) AS follow_clicks FROM (
           SELECT ${day('at')}, count(DISTINCT visitor), count(*), 0, 0, 0, 0, 0, 0 FROM v GROUP BY 1
-          UNION ALL SELECT ${day('at')}, 0, 0, count(*), count(*) FILTER (WHERE views = 1), coalesce(sum(seconds), 0), 0, 0, 0 FROM visits GROUP BY 1
+          UNION ALL SELECT ${day('at')}, 0, 0, count(*), 0, coalesce(sum(seconds), 0), 0, 0, 0 FROM visits GROUP BY 1
+          UNION ALL SELECT ${day('at')}, 0, 0, 0, count(*), 0, 0, 0, 0 FROM bounced GROUP BY 1
           UNION ALL SELECT ${day('at')}, 0, 0, 0, 0, 0, count(DISTINCT visitor), 0, 0 FROM ag GROUP BY 1
           UNION ALL SELECT ${day('at')}, 0, 0, 0, 0, 0, 0, count(DISTINCT visitor), 0 FROM (SELECT at, visitor FROM v UNION ALL SELECT at, visitor FROM ag) u GROUP BY 1
           ${follows ? `UNION ALL SELECT ${day('at')}, 0, 0, 0, 0, 0, 0, 0, count(*) FROM e WHERE ${follows} GROUP BY 1` : ''}

package/dist/base.css

@@ -614,6 +614,20 @@ pre:hover > .code-copy-btn,
    cut the axis to half its labels. */
 .chart-canvas table { table-layout: auto; }
 .chart-status { position: absolute; inset: 0; display: grid; place-items: center; margin: 0; }
+/* An event's name, over the mark the crosshair is on, in the colours of the axis labels. */
+.chart-tip {
+  position: absolute;
+  z-index: 2;
+  max-width: 50%;
+  padding: 0.25rem 0.5rem;
+  font-size: 0.6875rem;
+  line-height: 1.4;
+  white-space: pre-line;
+  color: var(--ui-on-accent);
+  background: var(--ui-accent);
+  border-radius: calc(var(--ui-radius) / 2);
+  pointer-events: none;
+}
 .chart-controls {
   position: absolute;
   top: 0.5rem;

package/dist/chart.d.ts

@@ -18,12 +18,12 @@ export type ChartResolution = 'hour' | '4h' | 'day';
 export type ChartStep = 'day' | 'week' | 'month';
 /** Points by resolution, from `from` (Unix seconds, 0 for all time), oldest first. */
 export type ChartLoader = (resolution: ChartResolution, from: number) => Promise<readonly ChartPoint[]>;
-/** Something that happened at a time, in Unix seconds, drawn on the point that holds it. */
+/** Something that happened at a time, in Unix seconds, marked on the point that holds it; `label` is its tooltip. */
 export type ChartMarker = {
     time: number;
     label: string;
 };
-/** The range and step a reader has picked, for a page that keeps them in its URL. */
+/** The range and step a reader has picked, for a page that keeps them in its URL; `step` is null while the chart picks its own. */
 export type ChartView = {
     range: ChartRange;
     step: ChartStep | null;
@@ -32,8 +32,12 @@ export type ChartView = {
 export type ChartAggregate = 'last' | 'sum' | 'mean';
 /** Every range, shortest first. A chart fed daily points offers the ones from 30D up. */
 export declare const CHART_RANGES: readonly ChartRange[];
-/** A step is offered once it makes four points, and the default is the finest that makes 200 or fewer. */
-export declare function chartSteps(span: number): {
+/**
+ * A step is offered once it makes four points, and the default is the finest that
+ * makes 200 or fewer. None is finer than the points' own `spacing`: weekly readings
+ * have no day.
+ */
+export declare function chartSteps(span: number, spacing?: number): {
     steps: ChartStep[];
     fallback: ChartStep;
 };
@@ -71,7 +75,7 @@ export interface TimeChartProps {
      * window links, which load another digest rather than slice this one.
      */
     controls?: ReactNode;
-    /** Events drawn on the points that hold them. */
+    /** Events marked on the points that hold them, each named in a tooltip. */
     markers?: readonly ChartMarker[];
     /** The step shown first, where the range can make it. */
     step?: ChartStep;

package/dist/chart.js

@@ -8,8 +8,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // loaded on mount, so the page paints without it. Every colour is the canvas
 // box's own `color`, its axis `--chart-axis`, and a candle `--chart-up` or
 // `--chart-down`, each if set. A count's line is curved; a price's is straight,
-// since a curve between two closes draws prices nobody paid. Events are markers
-// on the point they fall in, so a spike carries the reason for it.
+// since a curve between two closes draws prices nobody paid. Events are marks
+// on the point they fall in, named in a tooltip over it, so a spike carries the
+// reason for it without words across the plot.
 import { useEffect, useMemo, useRef, useState } from 'react';
 const DAY = 86_400;
 const RANGE = {
@@ -29,11 +30,22 @@ const STEPS = ['day', 'week', 'month'];
 /** Every range, shortest first. A chart fed daily points offers the ones from 30D up. */
 export const CHART_RANGES = ['24h', '7d', '30d', '90d', '1y', 'all'];
 const DAILY_RANGES = ['30d', '90d', '1y', 'all'];
-/** A step is offered once it makes four points, and the default is the finest that makes 200 or fewer. */
-export function chartSteps(span) {
-    const steps = STEPS.filter(s => s === 'day' || span / STEP[s].span >= 4);
+/**
+ * A step is offered once it makes four points, and the default is the finest that
+ * makes 200 or fewer. None is finer than the points' own `spacing`: weekly readings
+ * have no day.
+ */
+export function chartSteps(span, spacing = DAY) {
+    const fine = STEPS.filter(s => STEP[s].span >= spacing * 0.9);
+    const finest = fine[0] ?? 'month';
+    const steps = STEPS.filter(s => s === finest || (fine.includes(s) && span / STEP[s].span >= 4));
     return { steps, fallback: steps.find(s => span / STEP[s].span <= 200) ?? steps.at(-1) };
 }
+/** The points' own spacing: the median gap, so a missing day or a skipped week does not change it. */
+function spacing(points) {
+    const gaps = points.slice(1).map((p, i) => p.time - points[i].time).sort((a, b) => a - b);
+    return gaps[Math.floor(gaps.length / 2)] ?? DAY;
+}
 /** The UTC day, Monday or first of the month a time falls in. */
 function bucketStart(time, step) {
     const day = Math.floor(time / DAY);
@@ -81,7 +93,7 @@ export function bucketChart(points, step, aggregate) {
 }
 /**
  * Markers on the points drawn: each on the last point at or before it, so one
- * mid-week sits on its week. Markers on one point share it, labels joined; one
+ * mid-week sits on its week. Markers on one point share it, a label a line; one
  * before the first point or after the last point's step is left off.
  *
  * @internal
@@ -102,7 +114,7 @@ export function placeMarkers(markers, shown, step) {
         const time = shown[i].time;
         placed.set(time, [...(placed.get(time) ?? []), m.label]);
     }
-    return [...placed].map(([time, labels]) => ({ time, label: labels.join(' · ') }));
+    return [...placed].map(([time, labels]) => ({ time, label: labels.join('\n') }));
 }
 const isCandle = (p) => p.open !== undefined && p.high !== undefined && p.low !== undefined;
 /** The decimal places that write every multiple of `step` exactly: two for 0.25, none for 5000. */
@@ -163,6 +175,9 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
     const [step, setStep] = useState(initialStep ?? null);
     const [candles, setCandles] = useState(initialCandles);
     const [loaded, setLoaded] = useState(null);
+    // The marker under the crosshair, at the cursor, in the box's pixels.
+    const [tip, setTip] = useState(null);
+    const placed = useRef(new Map());
     const resolution = RANGE[range].resolution;
     useEffect(() => {
         const el = box.current;
@@ -227,6 +242,10 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
                 wickDownColor: down,
                 priceFormat,
             });
+            api.subscribeCrosshairMove(({ time, point }) => {
+                const label = time === undefined || !point ? undefined : placed.current.get(time);
+                setTip(label ? { x: point.x, y: point.y, label } : null);
+            });
             // The chart cannot be scrolled or zoomed, so every size it takes shows every point,
             // the first included: data drawn before autoSize has measured the box fits nothing.
             api.timeScale().subscribeSizeChange(() => api.timeScale().fitContent());
@@ -298,9 +317,10 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
         });
         if (resolution !== 'day' || !windowed.length)
             return drawn(windowed, [], null);
-        const { steps, fallback } = chartSteps(end - windowed[0].time);
+        const { steps, fallback } = chartSteps(end - windowed[0].time, spacing(points));
         const chosen = step && steps.includes(step) ? step : fallback;
-        if (chosen === 'day')
+        // The points' own step draws them as they are: a Sunday's reading stays on its Sunday.
+        if (chosen === steps[0])
             return drawn(windowed, steps, chosen);
         // A stepped range starts on a whole week or month, so its first total is not a few days of one.
         const from = bucketStart(windowed[0].time, chosen);
@@ -336,24 +356,29 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
             const rising = p.value >= (p.open ?? shown[i - 1]?.value ?? p.value);
             return { time: time(p), value: p.volume ?? 0, color: (rising ? c.up : c.down).replace(/[\d.]+\)$/, '0.5)') };
         }));
-        const drawn = placeMarkers(markers ?? [], shown, view?.step ?? null).map(m => ({
-            time: time(m),
-            position: 'aboveBar',
-            shape: 'arrowDown',
-            color: c.ink,
-            text: m.label,
-        }));
+        const marks = placeMarkers(markers ?? [], shown, view?.step ?? null);
+        placed.current = new Map(marks.map(m => [m.time, m.label]));
+        const drawn = marks.map(m => ({ time: time(m), position: 'aboveBar', shape: 'arrowDown', color: c.ink }));
         c.areaMarkers.setMarkers(asCandles ? [] : drawn);
         c.candleMarkers.setMarkers(asCandles ? drawn : []);
         c.api.timeScale().fitContent();
     }, [ready, source, view, candles, markers]);
-    const shownStep = view?.step ?? null;
+    // Reported once there are points to step, so a step read from a URL is not cleared while they load.
+    const shown = !!view;
+    const picked = step && step === view?.step ? step : null;
     useEffect(() => {
-        onViewRef.current?.({ range, step: shownStep });
-    }, [range, shownStep]);
+        if (shown)
+            onViewRef.current?.({ range, step: picked });
+    }, [shown, range, picked]);
     // The steps always show where a range is drawn by day, so the buttons do not jump about; one
     // the range cannot make (any, under 24H and 7D) is disabled.
     const daily = ranges.some(r => RANGE[r].resolution === 'day');
     const status = source && 'error' in source ? source.error : points && !view?.shown.length ? 'No data in this range' : null;
-    return (_jsxs("figure", { className: className ? `chart ${className}` : 'chart', children: [_jsx("div", { ref: box, className: "chart-canvas", role: "img", "aria-label": label, style: height ? { height } : undefined }), (!ready || (!points && !status)) && _jsx("div", { className: "chart-status skeleton", "aria-hidden": true }), status && _jsx("p", { className: "chart-status", children: status }), (controls || ranges.length > 1 || daily || view?.ohlc) && (_jsxs("div", { className: "chart-controls", children: [controls, ranges.length > 1 && (_jsx("div", { role: "group", "aria-label": "Range", children: ranges.map(r => (_jsx("button", { type: "button", "aria-pressed": r === range, onClick: () => { setRange(r); setStep(null); }, children: RANGE[r].label }, r))) })), daily && (_jsx("div", { role: "group", "aria-label": "Step", children: STEPS.map(s => (_jsx("button", { type: "button", "aria-pressed": s === view?.step, disabled: !view?.steps.includes(s), onClick: () => setStep(s), title: `One point per ${s}`, children: STEP[s].label }, s))) })), view?.ohlc && (_jsx("div", { children: _jsx("button", { type: "button", "aria-pressed": candles, "aria-label": "Candles", title: "Candles", onClick: () => setCandles(c => !c), children: _jsxs("svg", { className: "chart-icon", viewBox: "0 0 12 12", "aria-hidden": true, children: [_jsx("path", { d: "M3.5 1v2M3.5 9v2M8.5 2v3M8.5 9v1", stroke: "currentColor" }), _jsx("rect", { x: "2", y: "3", width: "3", height: "6", rx: "0.5", fill: "currentColor" }), _jsx("rect", { x: "7", y: "5", width: "3", height: "4", rx: "0.5", fill: "currentColor" })] }) }) }))] }))] }));
+    return (_jsxs("figure", { className: className ? `chart ${className}` : 'chart', children: [_jsx("div", { ref: box, className: "chart-canvas", role: "img", "aria-label": label, style: height ? { height } : undefined }), tip && box.current && (
+            // Over the cursor, or under it near the top; growing away from the nearer side.
+            _jsx("span", { className: "chart-tip", role: "tooltip", style: {
+                    top: box.current.offsetTop + tip.y,
+                    ...(tip.x < box.current.clientWidth / 2 ? { left: tip.x } : { right: box.current.clientWidth - tip.x }),
+                    translate: tip.y < 48 ? '0 1rem' : '0 calc(-100% - 0.75rem)',
+                }, children: tip.label })), (!ready || (!points && !status)) && _jsx("div", { className: "chart-status skeleton", "aria-hidden": true }), status && _jsx("p", { className: "chart-status", children: status }), (controls || ranges.length > 1 || daily || view?.ohlc) && (_jsxs("div", { className: "chart-controls", children: [controls, ranges.length > 1 && (_jsx("div", { role: "group", "aria-label": "Range", children: ranges.map(r => (_jsx("button", { type: "button", "aria-pressed": r === range, onClick: () => { setRange(r); setStep(null); }, children: RANGE[r].label }, r))) })), daily && (_jsx("div", { role: "group", "aria-label": "Step", children: STEPS.map(s => (_jsx("button", { type: "button", "aria-pressed": s === view?.step, disabled: !view?.steps.includes(s), onClick: () => setStep(s), title: `One point per ${s}`, children: STEP[s].label }, s))) })), view?.ohlc && (_jsx("div", { children: _jsx("button", { type: "button", "aria-pressed": candles, "aria-label": "Candles", title: "Candles", onClick: () => setCandles(c => !c), children: _jsxs("svg", { className: "chart-icon", viewBox: "0 0 12 12", "aria-hidden": true, children: [_jsx("path", { d: "M3.5 1v2M3.5 9v2M8.5 2v3M8.5 9v1", stroke: "currentColor" }), _jsx("rect", { x: "2", y: "3", width: "3", height: "6", rx: "0.5", fill: "currentColor" }), _jsx("rect", { x: "7", y: "5", width: "3", height: "4", rx: "0.5", fill: "currentColor" })] }) }) }))] }))] }));
 }

package/dist/dom.js

@@ -330,7 +330,10 @@ export function scrollTables(html) {
 // ---- analytics beacon -------------------------------------------------------
 let beaconEndpoint = '/api/view';
 let beaconStarted = false;
-const sendBeacon = (body) => navigator.sendBeacon?.(beaconEndpoint, JSON.stringify(body));
+// A browser under automation (Puppeteer, Playwright, Selenium) sets
+// `navigator.webdriver`: a crawler that runs scripts, whose user agent the bot
+// pattern cannot tell from a reader's, so it sends nothing at all.
+const sendBeacon = (body) => navigator.webdriver || navigator.sendBeacon?.(beaconEndpoint, JSON.stringify(body));
 /**
  * Report each page view to the site's own `endpoint`, whose route hands it to
  * `collect` (`wiki-formant/analytics`). Same-origin, so no third-party script

package/package.json

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