wiki-formant 0.94.0 → 0.97.1

package/README.md

@@ -231,6 +231,14 @@ handler: async (args, ctx) => {
 
 `config.gate` is envelope-level middleware: it may withhold entries before dispatch and merge its own responses back afterwards. A payment gate has to sit there rather than in a handler, because the demand *replaces* the call and the receipt rides on the envelope. `RpcRequest` and `toolText` are exported for a gate to build with; acuiq2's x402 gate is the one that does.
 
+### Agent feedback
+
+`feedbackTool(record, noun)` is `send_feedback`: an agent says what it needed and did not find, what is wrong or what broke (`kind` is `missing`, `wrong`, `broken` or `suggestion`), in `FEEDBACK_MAX` characters. It asks for something to act on rather than for a rating, which an agent answers with praise. List it among a server's tools and the transport does the inviting: `initialize` appends `FEEDBACK_INVITE` to `instructions`, and an empty `listEnvelope` page or an `McpToolError` carries a one-line `feedback` pointer, because a miss is when an agent knows what it was after. A tool whose miss has another shape quotes `FEEDBACK_NUDGE` in its own note. A server without the tool mentions it nowhere. Pass `tracker.trackFeedback` as `record` and each report is an "Agent Feedback" event, listed newest first in the digest's `agent_feedback`. Nothing is published: a report is a stranger's text, read as data.
+
+```ts
+tools: [...TOOLS, feedbackTool(tracker.trackFeedback, 'the Radix Wiki')]
+```
+
 ### Tool arguments and the corpus tool
 
 `readArgs` reads a tool's raw arguments as typed, clamped values and records every value it had to override, so a result can say `adjustments: [{ param: 'limit', requested: -4, used: 1, … }]` instead of silently answering a different question. Defaults belong in the tool description; the result echoes only overrides.
@@ -574,6 +582,16 @@ return new ImageResponse(<SocialCard {...{ title, eyebrow, description, backgrou
 
 Fonts stay with the site: Next traces a font file into the function only from a literal path in the app's own code, and satori reads TTF or OTF, never the woff2 `next/font` serves. The frame never sets a style key to `undefined`, which satori throws on rather than skipping; `scrim` darkens the foot for art that is a photograph.
 
+**A page's banner is its card.** The generated field exists so a page with no banner still unfurls with something; it never stands in for a banner the page has. Every route picks the same way, and every page's metadata passes its banner to the card URL, the homepage and category hubs included:
+
+```tsx
+const field = (await bannerField(searchParams.get('banner'), /\.public\.blob\.vercel-storage\.com$/))
+  ?? bubbles(cardRandom(title), { field, colors });
+return new ImageResponse(<SocialCard {...{ title, description }} {...field} colors={colors} />, { ...OG_SIZE, headers: OG_HEADERS });
+```
+
+`bannerField` fetches the banner only from the hosts you name, so `/og` is no proxy to any URL a caller writes, crops it to cover the card, inlines it as PNG (satori decodes no WebP or AVIF) and turns the scrim on. A missing, foreign or undecodable banner returns null and the generated field draws instead. It loads `sharp`, an optional peer, so the route runs on Node.
+
 ## Revisions
 
 What changed between two versions of a page, and therefore which semver bump to
@@ -998,7 +1016,7 @@ export const DELETE = gate.signOut;
 const q = statsQuery(params); // ?days= (1, 7, 30, 90, 365 or all, else 30), ?agents=apart and the filters
 return (
   <StatsGate gate={gate} session={(await cookies()).get(gate.cookie)?.value} invite={params.invite} host="caper.network">
-    {async () => <Stats digest={await digest(sql, q)} {...q} />}
+    {async () => <Stats digest={await digest(sql, q)} {...q} link={Link} />}
   </StatsGate>
 );
 ```
@@ -1013,13 +1031,16 @@ total, a rate's mean), 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 length and clicks to X. Visitors count agents; `?agents=apart`, a switch
-beside the windows, splits them into people and agents, and every
+visit length and clicks to X. Visitors count agents while the switch beside the windows, drawn as a robot's
+head, is lit; turning it off (`?agents=apart`) splits them into people and agents, and every
 other link on the page keeps the choice. `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.
+chart is server-rendered. Every link on the page is `link`, a bare `<a>` unless
+the site passes its router's: with `next/link` a window, the switch or a
+narrowing re-renders the page in place rather than reloading it, and the chart
+keeps its figure and step.
 
 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
@@ -1055,9 +1076,11 @@ token prices, ledger activity, a caper's price, visitors per day. One area
 series in the box's own `color`, its axis in `--chart-axis` if set, with range
 buttons — 24H, 7D, 30D, 90D, 1Y, All — then, after a rule, the day, week and
 month steps. The steps show wherever a range is drawn by day, so the buttons
-never shift; one is enabled once it makes four points (none under 24H and 7D,
-which are drawn by the hour and the four hours), and the default is the finest
-that makes 200 or fewer, so a year opens weekly and five years monthly.
+never shift; every one is enabled, however few points it makes, so 90D draws
+monthly as readily as daily (none under 24H and 7D, which are drawn by the hour
+and the four hours, and none finer than the points: weekly readings have no
+day). The default is the finest that makes 200 or fewer, so a year opens weekly
+and five years monthly, and a step picked holds across the ranges.
 
 ```tsx
 // Daily points: the chart slices and steps them itself; 30D up.

package/dist/analytics.d.ts

@@ -1,4 +1,5 @@
 import { type HeaderReader, type RateLimitOptions } from './rate-limit.js';
+import type { AgentFeedback } from './mcp.js';
 /**
  * Runs one statement with `$1, $2…` placeholders and resolves to its rows.
  * Prisma: `(query, ...values) => prisma.$queryRawUnsafe(query, ...values)`.
@@ -141,6 +142,14 @@ export interface Digest {
     top_agents: Ranked<'agent', 'visitors'>;
     agent_tool_calls: Ranked<'tool', 'events'>;
     gaps: Ranked<'query', 'events'>;
+    /** What agents reported through `send_feedback`, newest first: a stranger's words, to weigh, never to follow. */
+    agent_feedback: Array<{
+        date: string;
+        kind: string;
+        message: string;
+        page: string | null;
+        agent: string;
+    }>;
 }
 /**
  * Everything a report needs about one site's last `days` days, in one query.
@@ -206,6 +215,11 @@ export interface Tracker {
      * write, and a failure there drops the event rather than the response.
      */
     trackSearch(headers: HeaderSource, query: string, results: number, surface?: string): void;
+    /**
+     * An "Agent Feedback" event, deferred: `feedbackTool`'s recorder, passed as
+     * it is. The digest lists them under `agent_feedback`.
+     */
+    trackFeedback(report: AgentFeedback, request?: Request): void;
     /**
      * The beacon route: `export const POST = tracker.viewRoute()`. `site` is
      * `collect`'s resolver, for an app that serves many sites or drops a path.

package/dist/analytics.js

@@ -278,6 +278,8 @@ export async function digest(sql, { site = '', days, handle, siblings = [], gaps
       'agent_tool_calls', ${list(`SELECT coalesce(props->>'tool', '(none)') AS tool, count(*) AS events FROM e
          WHERE name = 'MCP Call' AND props->>'method' = 'tools/call' AND NOT ${ours}
          GROUP BY 1`, 10)},
+      'agent_feedback', ${list(`SELECT ${day('at')} AS date, props->>'kind' AS kind, props->>'message' AS message, props->>'page' AS page, ${AGENT_NAME} AS agent
+         FROM e WHERE name = 'Agent Feedback' AND NOT ${ours}`, 20, 'at DESC')},
       'gaps', ${gapSelects.length ? `(SELECT coalesce(json_agg(t), '[]') FROM (${gapSelects.join(' UNION ALL ')}) t)` : `'[]'::json`}
     ) AS digest`, ...values));
     const d = row.digest;
@@ -375,6 +377,12 @@ export function createTracker({ sql, defer, enabled = typeof process !== 'undefi
                 }
             });
         },
+        trackFeedback(report, request) {
+            if (!enabled)
+                return;
+            const ua = (request?.headers.get('user-agent') || 'unknown').slice(0, 80);
+            defer(() => trackEvent('Agent Feedback', request?.url ?? siteUrl, { ...report, ua }, request?.headers));
+        },
         viewRoute(opts = {}) {
             return async (request) => enabled ? collect(request, { sql, defer, ...opts }) : new Response(null, { status: 204 });
         },

package/dist/chart.d.ts

@@ -33,9 +33,9 @@ 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. None is finer than the points' own `spacing`: weekly readings
- * have no day.
+ * Every step is offered, however few points it makes, 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[];

package/dist/chart.js

@@ -31,14 +31,13 @@ const STEPS = ['day', 'week', 'month'];
 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. None is finer than the points' own `spacing`: weekly readings
- * have no day.
+ * Every step is offered, however few points it makes, 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));
+    const steps = fine.length ? fine : ['month'];
     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. */
@@ -380,5 +379,5 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
                     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" })] }) }) }))] }))] }));
+                }, 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), 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/mcp.d.ts

@@ -287,6 +287,39 @@ export declare const withAdjustments: <T extends object>(args: {
 }, result: T) => T | (T & {
     adjustments: readonly ArgAdjustment[];
 });
+/** The tool an agent reports through. A server listing it is told so on every miss. */
+export declare const FEEDBACK_TOOL = "send_feedback";
+export declare const FEEDBACK_KINDS: readonly ["missing", "wrong", "broken", "suggestion"];
+export type FeedbackKind = (typeof FEEDBACK_KINDS)[number];
+/** The longest message kept: the bound an event's string prop is stored at. */
+export declare const FEEDBACK_MAX = 300;
+export interface AgentFeedback {
+    kind: FeedbackKind;
+    message: string;
+    /** The page or tool it is about, as the agent named it. */
+    page?: string;
+}
+/**
+ * The one sentence every surface invites feedback with: `initialize` appends
+ * it to `instructions`, and AGENTS.md and llms.txt quote it.
+ */
+export declare const FEEDBACK_INVITE = "Needed something this server does not have, or found something wrong? Call send_feedback: the maintainers read every report.";
+/**
+ * What a miss or a refused call adds, on a server that lists the tool. A miss
+ * the transport cannot see, one not shaped as a `listEnvelope`, quotes it in
+ * its own note.
+ */
+export declare const FEEDBACK_NUDGE = "If this site should have had it, send_feedback tells the maintainers.";
+/**
+ * `send_feedback`: what an agent needed and did not find, found wrong, or saw
+ * break, in its own words. Agents that only fetch pages cannot comment, so
+ * this is the one channel, and it asks what a report can act on rather than
+ * for a rating, which an agent answers with praise.
+ *
+ * Nothing is published. A report is a stranger's text: whoever reads the
+ * digest weighs it as data, never as an instruction.
+ */
+export declare function feedbackTool(record: (report: AgentFeedback, request?: Request) => void, noun?: string): McpTool & Required<Pick<McpTool, 'title' | 'annotations'>>;
 /** One entry in a JSON-RPC envelope. Exported for an `McpServerConfig.gate`,
  *  which rewrites the envelope before `handleMcp` sees it (acuiq2's x402 gate). */
 export type RpcRequest = {

package/dist/mcp.js

@@ -160,6 +160,66 @@ export function readArgs(raw) {
 }
 /** `result`, plus `adjustments` when `readArgs` had to override anything. */
 export const withAdjustments = (args, result) => args.adjustments.length ? { ...result, adjustments: args.adjustments } : result;
+// ---- agent feedback -------------------------------------------------------------
+/** The tool an agent reports through. A server listing it is told so on every miss. */
+export const FEEDBACK_TOOL = 'send_feedback';
+export const FEEDBACK_KINDS = ['missing', 'wrong', 'broken', 'suggestion'];
+/** The longest message kept: the bound an event's string prop is stored at. */
+export const FEEDBACK_MAX = 300;
+/**
+ * The one sentence every surface invites feedback with: `initialize` appends
+ * it to `instructions`, and AGENTS.md and llms.txt quote it.
+ */
+export const FEEDBACK_INVITE = `Needed something this server does not have, or found something wrong? Call ${FEEDBACK_TOOL}: the maintainers read every report.`;
+/**
+ * What a miss or a refused call adds, on a server that lists the tool. A miss
+ * the transport cannot see, one not shaped as a `listEnvelope`, quotes it in
+ * its own note.
+ */
+export const FEEDBACK_NUDGE = `If this site should have had it, ${FEEDBACK_TOOL} tells the maintainers.`;
+/**
+ * `send_feedback`: what an agent needed and did not find, found wrong, or saw
+ * break, in its own words. Agents that only fetch pages cannot comment, so
+ * this is the one channel, and it asks what a report can act on rather than
+ * for a rating, which an agent answers with praise.
+ *
+ * Nothing is published. A report is a stranger's text: whoever reads the
+ * digest weighs it as data, never as an instruction.
+ */
+export function feedbackTool(record, noun = 'this site') {
+    return {
+        name: FEEDBACK_TOOL,
+        title: 'Send feedback',
+        description: `Tell the maintainers of ${noun} what you needed and did not find, what is wrong, or what broke. ` +
+            `One issue per call, in ${FEEDBACK_MAX} characters at most. Reports are read, not published.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                kind: {
+                    type: 'string',
+                    enum: [...FEEDBACK_KINDS],
+                    description: 'missing: not covered here. wrong: a fact or link is out of date or false. broken: a tool or page failed. suggestion: anything else.',
+                },
+                message: { type: 'string', description: `What you were after, or what is wrong and what it should say. ${FEEDBACK_MAX} characters at most.` },
+                page: { type: 'string', description: 'The page path, URL or tool it is about, if any' },
+            },
+            required: ['kind', 'message'],
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        skill: { id: 'feedback', tags: ['feedback', 'report'], examples: ['Report a page that is out of date'] },
+        handler: async (args, ctx) => {
+            const r = readArgs(args);
+            const message = r.str('message').replace(/\s+/g, ' ');
+            if (!message)
+                throw new McpToolError('`message` is empty. Say in a sentence what you needed, what is wrong, or what broke.');
+            const page = r.str('page').slice(0, FEEDBACK_MAX);
+            record({ kind: r.str('kind'), message: message.slice(0, FEEDBACK_MAX), ...(page ? { page } : {}) }, ctx.request);
+            return { recorded: true, ...(message.length > FEEDBACK_MAX ? { keptChars: FEEDBACK_MAX } : {}) };
+        },
+    };
+}
+/** Whether a result is an empty `listEnvelope` page: a search or listing that found nothing. */
+const foundNothing = (data) => !!data && typeof data === 'object' && data.total === 0 && Array.isArray(data.pages);
 /** How many entries one JSON-RPC batch may carry. Quoted by the conformance suite. */
 export const DEFAULT_MAX_BATCH = 20;
 const quote = (list) => list.map(s => `"${s}"`).join(', ');
@@ -291,6 +351,11 @@ const methodNotFound = (id, method, config, era) => {
  * `resources` whose list comes back empty reads as a bug to a client, not as
  * honesty. One function, so `initialize` and `server/discover` cannot disagree.
  */
+const listsFeedback = (config) => config.tools.some(t => t.name === FEEDBACK_TOOL);
+/** `instructions`, inviting feedback when the server takes it, so the invitation cannot be the line an app forgets. */
+const instructionsOf = (config) => listsFeedback(config) && !config.instructions.includes(FEEDBACK_TOOL)
+    ? `${config.instructions.trimEnd()}\n\n${FEEDBACK_INVITE}`
+    : config.instructions;
 const capabilitiesOf = (config) => ({
     tools: {},
     ...(config.resources?.length ? { resources: {} } : {}),
@@ -324,7 +389,7 @@ async function handleRpc(req, config, dispatch) {
                     protocolVersion: negotiateProtocol(p.protocolVersion),
                     capabilities: capabilitiesOf(config),
                     serverInfo: config.serverInfo,
-                    instructions: config.instructions,
+                    instructions: instructionsOf(config),
                 });
             // What `initialize` tells a legacy client, asked the modern way. The
             // transport adds `resultType`, the cache hints and `_meta` serverInfo.
@@ -332,7 +397,7 @@ async function handleRpc(req, config, dispatch) {
                 return ok(id, {
                     supportedVersions: [...MCP_PROTOCOL_VERSIONS],
                     capabilities: capabilitiesOf(config),
-                    instructions: config.instructions,
+                    instructions: instructionsOf(config),
                 });
             case 'ping':
                 return ok(id, {});
@@ -399,8 +464,11 @@ async function handleRpc(req, config, dispatch) {
                     protocolVersion: dispatch.protocolVersion,
                     request: dispatch.request,
                 };
+                // A miss is when an agent knows what it was after, so that is where it hears it can say so.
+                const nudge = tool.name !== FEEDBACK_TOOL && listsFeedback(config);
                 try {
-                    const data = await tool.handler(args, ctx);
+                    const raw = await tool.handler(args, ctx);
+                    const data = nudge && foundNothing(raw) ? { ...raw, feedback: FEEDBACK_NUDGE } : raw;
                     // `?? null`: a handler that returns nothing still owes a string, and
                     // JSON.stringify(undefined) is undefined.
                     const text = typeof data === 'string' ? data : JSON.stringify(data ?? null, null, 2);
@@ -423,7 +491,8 @@ async function handleRpc(req, config, dispatch) {
                 catch (err) {
                     if (!(err instanceof McpToolError))
                         throw err;
-                    return toolText(id, JSON.stringify({ error: err.message, ...err.details }, null, 2), true);
+                    const feedback = nudge ? { feedback: FEEDBACK_NUDGE } : {};
+                    return toolText(id, JSON.stringify({ error: err.message, ...err.details, ...feedback }, null, 2), true);
                 }
             }
             default:

package/dist/og.d.ts

@@ -25,6 +25,23 @@ export declare function bubbles(rand: () => number, o: BubbleOptions): {
     background: string;
     art: ReactNode;
 };
+/**
+ * A page's banner as the card's field: fetched, cropped to cover 1200×630 and
+ * inlined, under the scrim a photograph needs. Null when there is no banner,
+ * it is not an https URL on `hosts`, or it cannot be fetched and decoded, and
+ * the route draws its generated field instead.
+ *
+ * `hosts` is where the site stores banners. Fetching whatever `?banner=` named
+ * would make `/og` an anonymous proxy to any URL the server reaches, decoded by
+ * sharp on the way through. The bytes are inlined as PNG because satori decodes
+ * PNG and JPEG, not the WebP or AVIF an upload is stored as. `sharp` is an
+ * optional peer, loaded only here; run the route on Node.
+ */
+export declare function bannerField(banner: string | null | undefined, hosts: RegExp): Promise<{
+    background: string;
+    art: ReactNode;
+    scrim: true;
+} | null>;
 export interface SocialCardProps {
     title: string;
     /** The line above the title: a section, a code, a handle. */

package/dist/og.js

@@ -22,6 +22,44 @@ export function bubbles(rand, o) {
     });
     return { background, art };
 }
+/**
+ * A page's banner as the card's field: fetched, cropped to cover 1200×630 and
+ * inlined, under the scrim a photograph needs. Null when there is no banner,
+ * it is not an https URL on `hosts`, or it cannot be fetched and decoded, and
+ * the route draws its generated field instead.
+ *
+ * `hosts` is where the site stores banners. Fetching whatever `?banner=` named
+ * would make `/og` an anonymous proxy to any URL the server reaches, decoded by
+ * sharp on the way through. The bytes are inlined as PNG because satori decodes
+ * PNG and JPEG, not the WebP or AVIF an upload is stored as. `sharp` is an
+ * optional peer, loaded only here; run the route on Node.
+ */
+export async function bannerField(banner, hosts) {
+    if (!banner)
+        return null;
+    try {
+        const url = new URL(banner);
+        if (url.protocol !== 'https:' || !hosts.test(url.hostname))
+            return null;
+        const res = await fetch(url, { redirect: 'error' });
+        if (!res.ok)
+            return null;
+        const { default: sharp } = await import('sharp');
+        const png = await sharp(Buffer.from(await res.arrayBuffer()))
+            .resize(OG_SIZE.width, OG_SIZE.height, { fit: 'cover' })
+            .png()
+            .toBuffer();
+        const src = `data:image/png;base64,${png.toString('base64')}`;
+        return {
+            background: '#111',
+            art: _jsx("img", { src: src, alt: "", width: OG_SIZE.width, height: OG_SIZE.height, style: { position: 'absolute', width: '100%', height: '100%', objectFit: 'cover' } }),
+            scrim: true,
+        };
+    }
+    catch {
+        return null;
+    }
+}
 const SCRIM = 'linear-gradient(to top, rgba(0,0,0,0.8) 0%, rgba(0,0,0,0.3) 50%, transparent 100%)';
 /** One card, 1200×630: the eyebrow, title and anything under it, then the description and the mark along the foot. */
 export function SocialCard(p) {

package/dist/react-server.d.ts

@@ -5,8 +5,8 @@ import type { MaintenanceQueue } from './queues.js';
 /**
  * The shape a router's link component has to satisfy here.
  *
- * Deliberately the intersection the three rails and three facet bars actually
- * use, not a re-declaration of `AnchorHTMLAttributes`: a wider surface would
+ * Deliberately the intersection the three rails, three facet bars and the stats
+ * page actually use, not a re-declaration of `AnchorHTMLAttributes`: a wider surface would
  * let a consumer pass something `next/link` accepts and a bare `<a>` silently
  * drops. `next/link` satisfies this as it stands.
  */
@@ -17,6 +17,11 @@ export interface WikiLinkProps {
     'aria-current'?: 'true' | 'page' | undefined;
     /** `prev`/`next` on the foot nav — the half that makes the pair machine-readable. */
     rel?: string;
+    /** `switch`, with `aria-checked`, on the stats page's toggle between two views. */
+    role?: string;
+    'aria-checked'?: boolean;
+    /** The name of a link drawn as an icon. */
+    'aria-label'?: string;
     children?: ReactNode;
 }
 export type WikiLinkComponent = ComponentType<WikiLinkProps>;

package/dist/stats.d.ts

@@ -1,6 +1,7 @@
 import type { ReactNode } from 'react';
 import { type Digest, type StatsFilter } from './analytics.js';
 import type { PasskeyGate } from './passkey.js';
+import { type WikiLinkComponent } from './react-server.js';
 export interface StatsProps {
     /** One window's figures, from `digest` in `wiki-formant/analytics`. */
     digest: Digest;
@@ -12,6 +13,8 @@ export interface StatsProps {
     apart?: boolean;
     /** The windows offered as `?days=` links on the same page. */
     ranges?: readonly number[];
+    /** Every link on the page: `next/link`, say, so a window or a filter does not reload it. */
+    link?: WikiLinkComponent;
 }
 /**
  * A stats page's query as the window and the filter, both ready for `digest`
@@ -30,7 +33,7 @@ export declare function statsQuery(params: Record<string, string | string[] | un
  * 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, filter, apart, ranges }: StatsProps): import("react").JSX.Element;
+export declare function Stats({ digest: d, days, filter, apart, ranges, link: Link }: StatsProps): import("react").JSX.Element;
 export interface StatsGateProps {
     gate: PasskeyGate;
     /** The gate's cookie from the request: `(await cookies()).get(gate.cookie)?.value`. */

package/dist/stats.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { STATS_FILTERS, count } from './analytics.js';
+import { Anchor } from './react-server.js';
 import { PasskeyButton, PasskeySignOut, StatsFigures } from './stats-figures.js';
 /** The windows the stats page offers, in days; `Infinity` is all time. */
 const STATS_RANGES = [1, 7, 30, 90, 365, Infinity];
@@ -44,11 +45,11 @@ const country = (code) => {
 };
 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, }) {
+function StatsList({ title, rows, label = v => v, to, link: Link, }) {
     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: to ? _jsx("a", { href: to(v), children: label(v) }) : 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(Link, { 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
@@ -57,7 +58,7 @@ function StatsList({ title, rows, label = v => v, to, }) {
  * 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, filter = {}, apart = false, ranges = STATS_RANGES }) {
+export function Stats({ digest: d, days, filter = {}, apart = false, ranges = STATS_RANGES, link: Link = Anchor }) {
     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]);
@@ -73,8 +74,8 @@ export function Stats({ digest: d, days, filter = {}, apart = false, ranges = ST
     const to = (k) => (v) => at({ ...filter, [k]: v });
     // Each window is another digest, so a link rather than a button, pinned
     // with the chart's own controls, and so is the switch that counts agents apart.
-    const controls = (_jsxs(_Fragment, { children: [_jsx("div", { role: "group", "aria-label": "Window", children: ranges.map(n => (_jsx("a", { href: at(filter, n), "aria-current": n === days ? 'page' : undefined, children: windowLabel(n) }, n))) }), _jsx("div", { children: _jsx("a", { href: at(filter, days, !apart), role: "switch", "aria-checked": apart, title: "People and agents counted apart", children: "Agents apart" }) })] }));
-    return (_jsxs("div", { className: "stats", children: [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: at({ ...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, apart: apart, controls: controls }), _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 => at({ ...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: "Agents", rows: rows(d.top_agents, 'agent', '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 controls = (_jsxs(_Fragment, { children: [_jsx("div", { role: "group", "aria-label": "Window", children: ranges.map(n => (_jsx(Link, { href: at(filter, n), "aria-current": n === days ? 'page' : undefined, children: windowLabel(n) }, n))) }), _jsx("div", { children: _jsx(Link, { href: at(filter, days, !apart), role: "switch", "aria-checked": !apart, "aria-label": "Agents counted among visitors", title: "Agents counted among visitors", children: _jsxs("svg", { className: "chart-icon", viewBox: "0 0 12 12", "aria-hidden": true, children: [_jsx("path", { d: "M6 1.5v2M1 6.5v2M11 6.5v2", stroke: "currentColor" }), _jsx("rect", { x: "2.5", y: "3.5", width: "7", height: "7", rx: "1.5", fill: "none", stroke: "currentColor" }), _jsx("circle", { cx: "4.75", cy: "7", r: "0.9", fill: "currentColor" }), _jsx("circle", { cx: "7.25", cy: "7", r: "0.9", fill: "currentColor" })] }) }) })] }));
+    return (_jsxs("div", { className: "stats", children: [narrowed.length > 0 && (_jsxs("div", { className: "stats-filters", children: [_jsx("ul", { "aria-label": "Narrowed to", children: narrowed.map(k => (_jsx("li", { children: _jsxs(Link, { href: at({ ...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, apart: apart, controls: controls }), _jsxs("div", { className: "stats-lists", children: [_jsx(StatsList, { link: Link, title: "Pages", rows: rows(d.top_pages, 'page', 'visitors'), to: to('page') }), _jsx(StatsList, { link: Link, title: "Entry pages", rows: rows(d.entry_pages, 'page', 'visitors'), to: to('entry') }), _jsx(StatsList, { link: Link, title: "Sources", rows: rows(d.top_sources, 'source', 'visitors'), to: to('source') }), _jsx(StatsList, { link: Link, title: "From X posts", rows: rows(d.from_posts, 'page', 'visitors'), to: v => at({ ...filter, source: 'x', entry: v }) }), _jsx(StatsList, { link: Link, title: "Sibling sites", rows: rows(d.sibling_referrals, 'source', 'visitors'), to: to('source') }), _jsx(StatsList, { link: Link, title: "Countries", rows: rows(d.countries, 'country', 'visitors'), label: country, to: to('country') }), _jsx(StatsList, { link: Link, title: "Devices", rows: rows(d.devices, 'device', 'visitors'), to: to('device') }), _jsx(StatsList, { link: Link, title: "Agents", rows: rows(d.top_agents, 'agent', 'visitors') }), _jsx(StatsList, { link: Link, title: "Agent tool calls", rows: rows(d.agent_tool_calls, 'tool', 'events') }), _jsx(StatsList, { link: Link, title: "Searches that found nothing", rows: rows(d.gaps, 'query', 'events') })] })] }));
 }
 /**
  * A stats page's door: `children` and a sign-out button for a signed-in

package/package.json

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