wiki-formant 0.27.1 → 0.29.0

package/dist/analytics.js

@@ -1,49 +1,235 @@
-// analytics.ts — server-side Plausible events for a wiki's agent and human lanes.
+// analytics.ts – page views and events, counted in the site's own Postgres.
 //
-// The proxy counts an "AI Bot Visit" by matching user agents, which cannot see
-// inside a JSON-RPC envelope. So an MCP call is only countable by tool name at
-// the route, and that extraction — from a body that is untrusted and may be a
-// batch — is the part worth sharing. Every wiki in the workspace had its own
-// copy of it, differing only in the default hostname.
+// It replaces a hosted analytics service. A page reports its own view to the
+// site's own address (`startBeacon` in `dom.ts`, `<Beacon>` in `react.tsx`), a
+// route hands the beacon to `collect`, and server code records events with
+// `recordEvent`. `digest` reads it all back as one JSON object, and the
+// `analytics-digest` bin prints that object for scripts outside the app.
 //
-// `searchQueryProps` is the human-side twin: the same shape problem, from the
-// other direction. A search box is untrusted free text on every wiki, and the
-// normalisation that makes it aggregatable — and keeps an empty field from
-// firing an event — is the part worth sharing rather than re-deriving.
+// No cookie is set and no address is kept. A visitor is a hash of the address
+// and the browser under a salt that changes every UTC day, and the old salt is
+// deleted when the new one is made, so a visitor can be told apart within a day
+// and never followed into the next. A visit is a run of one visitor's views
+// with no gap over 30 minutes.
 //
-// Deferral stays with the caller: `after()` in a route handler,
-// `event.waitUntil` in a proxy. Both are framework calls, and importing one
-// here would cost this package its zero-dependency guarantee.
-const DEFAULT_ENDPOINT = 'https://plausible.io/api/event';
+// The package owns the SQL; the app owns the connection. `Sql` is one function
+// that runs a parameterised statement, which Prisma, `pg` and postgres.js can
+// all supply in a line. The app declares the three tables in its own schema,
+// so `prisma db push` keeps them:
+//
+//   model View {
+//     id        BigInt   @id @default(autoincrement())
+//     siteId    String   @default("")
+//     path      String
+//     source    String?
+//     country   String?
+//     device    String
+//     visitor   String
+//     createdAt DateTime @default(now()) @db.Timestamptz(3)
+//     @@index([siteId, createdAt])
+//   }
+//
+//   model Event {
+//     id        BigInt   @id @default(autoincrement())
+//     siteId    String   @default("")
+//     name      String
+//     path      String?
+//     props     Json     @default("{}")
+//     visitor   String?
+//     createdAt DateTime @default(now()) @db.Timestamptz(3)
+//     @@index([siteId, name, createdAt])
+//   }
+//
+//   model Salt {
+//     day   String @id
+//     value String
+//   }
+//
+// `siteId` is "" in an app that serves one site. A multi-tenant app passes its
+// own site key to every call.
+//
+// Deferral stays with the caller: `after()` in a route, `event.waitUntil` in a
+// proxy. Both are framework calls, and importing one here would cost this
+// package its zero-dependency guarantee. Hashing is Web Crypto, so the module
+// runs anywhere Node 20, a browser or an edge runtime does.
+import { clientIp, clientKey, rateLimit } from './rate-limit.js';
+/** Long enough to compare a month with the same month a year before. */
+const KEEP_DAYS = 400;
+const DAY_MS = 86_400_000;
+/** A script that runs a page's JavaScript and says what it is. */
+const BOT = /bot|crawl|spider|slurp|headless|lighthouse|prerender|preview/i;
+/** iPadOS reports itself as a Mac, so its views count as a computer's. */
+export const deviceOf = (ua) => /iPad|Tablet|Android(?!.*Mobile)/i.test(ua) ? 'tablet' : /Mobi|iPhone|Android/i.test(ua) ? 'phone' : 'computer';
+const bareHost = (host) => host.toLowerCase().replace(/:\d+$/, '').replace(/^www\./, '');
 /**
- * The exact request shape Plausible's events API expects.
- *
- * Never rejects: analytics must not be able to fail a response the reader is
- * waiting on.
+ * Where a visit came from: its `utm_source` when the link carried one, else the
+ * referring host, and null for a referrer that is this site or none.
  */
-export function plausibleEvent(config, name, url, props, headers, extra = {}) {
-    return fetch(config.endpoint ?? DEFAULT_ENDPOINT, {
-        method: 'POST',
-        headers: {
-            'Content-Type': 'application/json',
-            'User-Agent': extra.userAgent || 'Mozilla/5.0 (compatible; BotTracker/1.0)',
-            'X-Forwarded-For': headers.get('x-forwarded-for') || headers.get('x-real-ip') || '127.0.0.1',
-        },
-        body: JSON.stringify({
-            name,
-            url,
-            domain: config.domain,
-            props: JSON.stringify(props),
-            ...(extra.revenue ? { revenue: extra.revenue } : {}),
-        }),
-    }).catch(() => undefined);
+export function sourceOf(referrer, utm, host) {
+    if (typeof utm === 'string' && utm.trim())
+        return utm.trim().toLowerCase().slice(0, 100);
+    if (typeof referrer !== 'string' || !referrer)
+        return null;
+    try {
+        const from = bareHost(new URL(referrer).hostname);
+        return from && from !== bareHost(host) ? from.slice(0, 200) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A browser path as stored: decoded, one leading slash, no trailing one. Null when it will not decode. */
+export function normalisePath(path) {
+    try {
+        const p = decodeURIComponent(path.split(/[?#]/)[0].slice(0, 500));
+        return `/${p.replace(/^\/+|\/+$/g, '')}`;
+    }
+    catch {
+        return null;
+    }
+}
+const hex = (bytes) => Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
+const salts = new WeakMap();
+/** Today's salt. Whoever makes it also deletes yesterday's, and rows past keeping. */
+async function todaysSalt(sql) {
+    const day = new Date().toISOString().slice(0, 10);
+    const cached = salts.get(sql);
+    if (cached?.day === day)
+        return cached.value;
+    const made = (await sql('INSERT INTO "Salt" (day, value) VALUES ($1, $2) ON CONFLICT (day) DO NOTHING RETURNING day', day, hex(crypto.getRandomValues(new Uint8Array(32)))));
+    if (made.length) {
+        const cutoff = new Date(Date.now() - KEEP_DAYS * DAY_MS);
+        await sql('DELETE FROM "Salt" WHERE day < $1', day);
+        await sql('DELETE FROM "View" WHERE "createdAt" < $1', cutoff);
+        await sql('DELETE FROM "Event" WHERE "createdAt" < $1', cutoff);
+    }
+    const [row] = (await sql('SELECT value FROM "Salt" WHERE day = $1', day));
+    salts.set(sql, { day, value: row.value });
+    return row.value;
+}
+async function visitorOf(sql, site, headers) {
+    const text = [await todaysSalt(sql), site, clientIp(headers), headers.get('user-agent') ?? ''].join('\n');
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
+    return hex(new Uint8Array(digest)).slice(0, 32);
+}
+/** Analytics must not be able to fail a response, so a failed write is logged and dropped. */
+const quietly = (task) => task().then(() => undefined, (e) => console.error(`analytics: ${e.message}`));
+/** Count one page view, unless a bot sent it. Never rejects. */
+export function recordView(sql, { headers, path, referrer, utm, site = '' }) {
+    const ua = headers.get('user-agent') ?? '';
+    const page = normalisePath(path);
+    if (!ua || BOT.test(ua) || page === null)
+        return Promise.resolve();
+    return quietly(async () => sql('INSERT INTO "View" ("siteId", path, source, country, device, visitor) VALUES ($1, $2, $3, $4, $5, $6)', site, page, sourceOf(referrer, utm, headers.get('host') ?? ''), headers.get('x-vercel-ip-country')?.slice(0, 2) || null, deviceOf(ua), await visitorOf(sql, site, headers)));
+}
+/** Record one named event. Never rejects. */
+export function recordEvent(sql, { name, props = {}, url, headers, site = '' }) {
+    return quietly(async () => {
+        let path = null;
+        if (url)
+            path = normalisePath(new URL(url, 'http://x').pathname);
+        return sql('INSERT INTO "Event" ("siteId", name, path, props, visitor) VALUES ($1, $2, $3, $4::jsonb, $5)', site, name.slice(0, 64), path, JSON.stringify(props), headers?.get('user-agent') ? await visitorOf(sql, site, headers) : null);
+    });
+}
+/** A browser-sent event's props: eight at most, each value a short string or a number. */
+function beaconProps(props) {
+    if (!props || typeof props !== 'object' || Array.isArray(props))
+        return {};
+    return Object.fromEntries(Object.entries(props)
+        .filter(([, v]) => typeof v === 'string' || (typeof v === 'number' && Number.isFinite(v)))
+        .slice(0, 8)
+        .map(([k, v]) => [k.slice(0, 40), typeof v === 'string' ? v.slice(0, 300) : v]));
+}
+// A person reads a few pages a minute. This leaves room for a fast reader and
+// stops one address filling a site's figures.
+const BEACONS = { capacity: 30, refillPerSec: 0.5 };
+/**
+ * The whole beacon route: `export const POST = (r: Request) => collect(r, { sql, defer: after })`.
+ * Answers 204 whatever happens, before anything is written, so a reader never waits on it.
+ */
+export async function collect(request, { sql, defer, site, rateLimit: limit = BEACONS }) {
+    const done = new Response(null, { status: 204 });
+    const { headers } = request;
+    if (BOT.test(headers.get('user-agent') ?? '') || !rateLimit(clientKey('beacon', headers), limit).ok)
+        return done;
+    const body = (await request.json().catch(() => null));
+    const path = typeof body?.path === 'string' ? normalisePath(body.path) : null;
+    if (!body || !path)
+        return done;
+    const key = site ? await site(request, path) : '';
+    if (key === null)
+        return done;
+    defer(() => typeof body.name === 'string' && body.name
+        ? recordEvent(sql, { name: body.name, props: beaconProps(body.props), url: path, headers, site: key })
+        : recordView(sql, { headers, path, referrer: body.referrer, utm: body.utm, site: key }));
+    return done;
+}
+/** 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' } };
+/**
+ * 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
+ * another day counts once for each day.
+ */
+export async function digest(sql, { site = '', days, handle, siblings = [], gaps = [SEARCH_GAPS], ownAgents = ['-mcp-test', 'radix-studio'] }) {
+    // The window is the database's clock, which stamped the rows; the app's can run behind it.
+    const values = [site, Math.max(1, Math.round(days))];
+    const $ = (v) => `$${values.push(v)}`;
+    const list = (select, limit, order = '2 DESC, 1') => `(SELECT coalesce(json_agg(t), '[]') FROM (${select} ORDER BY ${order}${limit ? ` LIMIT ${limit}` : ''}) t)`;
+    const gapSelects = gaps.map(g => {
+        const prop = $(g.prop);
+        return `(SELECT props->>${prop} AS query, count(*) AS events FROM e
+      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 (
+      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
+    ), numbered AS (
+      SELECT *, sum(starts) OVER (PARTITION BY visitor ORDER BY at, id) AS visit FROM marked
+    ), visits AS (
+      SELECT visitor, 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
+    ), e AS (
+      SELECT name, props, visitor FROM "Event" WHERE "siteId" = $1 AND "createdAt" >= now() - make_interval(days => $2::int)
+    )
+    SELECT json_build_object(
+      'visitors', (SELECT count(DISTINCT visitor) FROM v),
+      'pageviews', (SELECT count(*) FROM v),
+      'bounce_rate', (SELECT round(100.0 * count(*) FILTER (WHERE views = 1) / nullif(count(*), 0)) FROM visits),
+      'visit_duration', (SELECT round(avg(seconds)) FROM visits),
+      'visitors_incl_agents', (SELECT count(DISTINCT visitor) FROM (SELECT visitor FROM v UNION SELECT visitor FROM e) a),
+      'previous_visitors', (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)),
+      'top_sources', ${list(`SELECT coalesce(source, '(none)') AS source, count(DISTINCT visitor) AS visitors FROM visits GROUP BY 1`, 6)},
+      'top_pages', ${list('SELECT path AS page, count(DISTINCT visitor) AS visitors FROM v GROUP BY 1', 6)},
+      'entry_pages', ${list('SELECT entry AS page, count(DISTINCT visitor) AS visitors FROM visits GROUP BY 1', 6)},
+      'from_posts', ${list(`SELECT entry AS page, count(DISTINCT visitor) AS visitors FROM visits WHERE source = 'x' GROUP BY 1`, 15)},
+      'sibling_referrals', ${list(`SELECT source, count(DISTINCT visitor) AS visitors FROM visits WHERE source = ANY(${$(siblings)}::text[]) GROUP BY 1`, 6)},
+      'countries', ${list('SELECT country, count(DISTINCT visitor) AS visitors FROM v WHERE country IS NOT NULL GROUP BY 1', 10)},
+      'devices', ${list('SELECT device, count(DISTINCT visitor) AS visitors FROM v GROUP BY 1')},
+      'by_day', ${list(`SELECT to_char(at AT TIME ZONE 'UTC', 'YYYY-MM-DD') AS date, count(DISTINCT visitor) AS visitors FROM v GROUP BY 1`, undefined, '1')},
+      'follow_clicks', ${handle
+        ? `(SELECT json_build_object('events', count(*), 'visitors', count(DISTINCT visitor)) FROM e
+              WHERE name = 'Outbound Link: Click' AND props->>'url' ILIKE ANY(${$([`%x.com/${handle}%`, `%twitter.com/${handle}%`])}::text[]))`
+        : 'NULL'},
+      '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 coalesce(props->>'ua', '') ILIKE ANY(${$(ownAgents.map(a => `%${a}%`))}::text[])
+         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;
 }
 /**
  * Props for an "MCP Call" event, read out of the JSON-RPC envelope.
  *
  * The body is untrusted and may be a batch, a notification, or malformed
  * entirely, so every extraction is defensive and the result is always a
- * complete props object. A batch is attributed to its first member — the
+ * complete props object. A batch is attributed to its first member – the
  * alternative is one event per member, which would make a fan-out look like
  * traffic it is not.
  */
@@ -55,7 +241,7 @@ export function mcpCallProps(request, body, server) {
     return { ...(server ? { server } : {}), method, ...(tool ? { tool } : {}), ua };
 }
 /**
- * Props for a "Search Query" event — the human-side twin of `mcpCallProps`.
+ * Props for a "Search Query" event – the human-side twin of `mcpCallProps`.
  *
  * A wiki instruments its agent surface and then counts every question an agent
  * asks while recording none of the questions a person asks. The queries that
@@ -64,7 +250,7 @@ export function mcpCallProps(request, body, server) {
  *
  * Returns `null` for a query with no content, so an empty field cannot fire an
  * event. The text is untrusted, so it is collapsed, lowercased for aggregation
- * and truncated — the same 64-character bound search itself applies, which
+ * and truncated – the same 64-character bound search itself applies, which
  * keeps the prop and the query that produced it the same string.
  */
 export function searchQueryProps({ query, results, surface, }) {
@@ -73,18 +259,52 @@ export function searchQueryProps({ query, results, surface, }) {
         return null;
     return {
         q,
-        // A string because Plausible props are strings; `results == "0"` is the
-        // filter that yields the gap list.
+        // A string, so `{ results: '0' }` is the filter that yields the gap list.
         results: String(Math.max(0, Math.trunc(results) || 0)),
         ...(surface ? { surface } : {}),
     };
 }
-/** The hostname of a site URL, for the `domain` a Plausible property is filed under. */
-export function plausibleDomain(siteUrl, fallback) {
-    try {
-        return new URL(siteUrl || fallback).hostname;
-    }
-    catch {
-        return fallback.replace(/^https?:\/\//, '').replace(/\/.*$/, '');
-    }
+/**
+ * Everything an app's `track.ts` had written around the functions above: the
+ * production gate, the deferral and the three named events. Four apps carried
+ * it, two with a search signature of their own.
+ *
+ * The tracker holds `sql`, so the module that builds it imports the app's
+ * database client. A proxy must keep reaching it through a dynamic import
+ * inside `waitUntil`, never a static one, or every request the proxy sees
+ * loads Prisma:
+ *
+ *   event.waitUntil(import('@/lib/track').then(m => m.trackEvent('AI Bot Visit', url, { bot }, request.headers)));
+ */
+export function createTracker({ sql, defer, enabled = typeof process !== 'undefined' && process.env.VERCEL_ENV === 'production', siteUrl = '/', }) {
+    const trackEvent = (name, url, props, headers) => enabled ? recordEvent(sql, { name, url, props, headers }) : Promise.resolve();
+    return {
+        trackEvent,
+        trackMcpCall(request, body, server) {
+            if (!enabled)
+                return;
+            const props = mcpCallProps(request, body, server);
+            const { url, headers } = request;
+            defer(() => trackEvent('MCP Call', url, props, headers));
+        },
+        trackSearch(source, query, results, surface) {
+            if (!enabled)
+                return;
+            const props = searchQueryProps({ query, results, surface });
+            if (!props)
+                return;
+            defer(async () => {
+                try {
+                    const headers = typeof source === 'function' ? await source() : source;
+                    await trackEvent('Search Query', headers.get('referer') || siteUrl, props, headers);
+                }
+                catch {
+                    // A context with no readable headers loses the event, never the response.
+                }
+            });
+        },
+        viewRoute(opts = {}) {
+            return async (request) => enabled ? collect(request, { sql, defer, ...opts }) : new Response(null, { status: 204 });
+        },
+    };
 }

package/dist/blocks.d.ts

@@ -147,3 +147,142 @@ export declare function statsToMarkdown(items: readonly StatItem[]): string;
 export declare function linkGridToMarkdown(groups: readonly LinkGridGroup[], intro?: string | null): string;
 /** A flat bullet list of links — resolved page lists, feed items, link rails. */
 export declare function linkList(items: readonly LinkGridLink[]): string;
+/**
+ * The core leaves as the helpers below read them: the shape every wiki here
+ * stores, built from the leaf types above. `P` is what a resolved page list
+ * carries, because radix-wiki's lists hold its own page rows and the other two
+ * hold `ResolvedPageRef`s.
+ *
+ * Structural on purpose. A repo's own switch narrows its block to one of these
+ * cases and hands it over — `case 'stats': case 'linkGrid': … return
+ * coreAtomicText(block)` — so the switch stays exhaustive over the repo's union
+ * and the case bodies stop being written three times.
+ */
+export type CoreAtomicBlock<P = ResolvedPageRef> = {
+    type: 'content';
+    text: string;
+} | {
+    type: 'codeTabs';
+    tabs: readonly CodeTab[];
+} | {
+    type: 'banner';
+    variant: string;
+    text?: string | null;
+} | {
+    type: 'references';
+    title?: string | null;
+    items: readonly ReferenceItem[];
+} | {
+    type: 'stats';
+    items: readonly StatItem[];
+} | {
+    type: 'linkGrid';
+    intro?: string | null;
+    groups: readonly LinkGridGroup[];
+} | {
+    type: 'recentPages' | 'pageList';
+    resolvedPages?: readonly P[] | null;
+};
+/**
+ * One core leaf as prose, for the LLM and MCP exports. A page list reads only
+ * after the server has resolved it; unresolved, it extracts to nothing.
+ */
+export declare function coreAtomicText(block: CoreAtomicBlock<{
+    title: string;
+}>): string;
+export interface CoreMarkdownOptions {
+    /**
+     * The origin a resolved page's site-relative `href` is joined to. A twin is
+     * read off-site, where a bare `/wiki/…` resolves to nothing.
+     */
+    siteUrl: string;
+    /** A references block's heading when it stores none. Default `References`. */
+    referencesTitle?: string;
+}
+/** One core leaf as markdown, for a page's `.md` twin. */
+export declare function coreAtomicToMarkdown(block: CoreAtomicBlock, opts: CoreMarkdownOptions): string;
+export interface CoreBlockDefaultsOptions {
+    /** Ids for the nested rows a new block starts with. Default `crypto.randomUUID`. */
+    newId?: () => string;
+    /** A new references block's title. Default `References`. */
+    referencesTitle?: string;
+    /** A new code-tabs block's tabs, each empty. Default Rust and TypeScript. */
+    codeTabs?: ReadonlyArray<{
+        label: string;
+        language: string;
+    }>;
+    /** A new stats block's three placeholder cards. */
+    stats?: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+}
+/** What inserting each core type makes, without its `id`. */
+export interface CoreBlockDefaults {
+    content: () => {
+        type: 'content';
+        text: string;
+    };
+    recentPages: () => {
+        type: 'recentPages';
+        limit: number;
+    };
+    pageList: () => {
+        type: 'pageList';
+        pageIds: string[];
+    };
+    columns: () => {
+        type: 'columns';
+        columns: {
+            id: string;
+            blocks: never[];
+        }[];
+        gap: 'md';
+        align: 'start';
+    };
+    infobox: () => {
+        type: 'infobox';
+        blocks: never[];
+    };
+    codeTabs: () => {
+        type: 'codeTabs';
+        tabs: {
+            label: string;
+            language: string;
+            code: string;
+        }[];
+    };
+    stats: () => {
+        type: 'stats';
+        items: {
+            id: string;
+            value: string;
+            label: string;
+        }[];
+        columns: 3;
+    };
+    linkGrid: () => {
+        type: 'linkGrid';
+        groups: {
+            id: string;
+            heading: string;
+            links: never[];
+        }[];
+    };
+    references: () => {
+        type: 'references';
+        title: string;
+        items: never[];
+    };
+    banner: () => {
+        type: 'banner';
+        variant: 'stub';
+    };
+}
+/**
+ * The new-block factories for the core types, which all three wikis had typed
+ * out identically but for a few labels. Spread into a repo's own record beside
+ * its native types, so that record stays keyed by the repo's union:
+ * `{ ...coreBlockDefaults({ stats }), daoTimeline: () => … }`.
+ */
+export declare function coreBlockDefaults(opts?: CoreBlockDefaultsOptions): CoreBlockDefaults;

package/dist/blocks.js

@@ -12,6 +12,7 @@
 // keeps this file free of any one repo's type union.
 import { htmlToMarkdown, inlineToMarkdown } from './markdown.js';
 import { relativeTime } from './freshness.js';
+import { BANNER_LABELS, bannerToText, codeTabsToText, linkGridToText, pageListToText, referencesToText, statsToText, stripHtml, } from './text.js';
 export function pageRef(page, now, style = 'long') {
     return {
         title: page.title,
@@ -194,3 +195,70 @@ export function linkGridToMarkdown(groups, intro) {
 export function linkList(items) {
     return items.map(l => `- [${l.label}](${l.href})`).join('\n');
 }
+const bannerLabel = (variant) => BANNER_LABELS[variant] ?? variant;
+/**
+ * One core leaf as prose, for the LLM and MCP exports. A page list reads only
+ * after the server has resolved it; unresolved, it extracts to nothing.
+ */
+export function coreAtomicText(block) {
+    switch (block.type) {
+        case 'content': return stripHtml(block.text);
+        case 'codeTabs': return codeTabsToText(block.tabs);
+        case 'banner': return bannerToText(bannerLabel(block.variant), block.text);
+        case 'references': return referencesToText(block.items);
+        case 'stats': return statsToText(block.items);
+        case 'linkGrid': return linkGridToText(block.groups, block.intro);
+        case 'recentPages':
+        case 'pageList': return pageListToText(block.resolvedPages ?? []);
+    }
+}
+/** One core leaf as markdown, for a page's `.md` twin. */
+export function coreAtomicToMarkdown(block, opts) {
+    switch (block.type) {
+        case 'content': return htmlToMarkdown(block.text);
+        case 'codeTabs': return codeTabsToMarkdown(block.tabs);
+        case 'banner': return bannerToMarkdown(bannerLabel(block.variant), block.text);
+        case 'references': return referencesToMarkdown(block.items, block.title || opts.referencesTitle || 'References');
+        case 'stats': return statsToMarkdown(block.items);
+        case 'linkGrid': return linkGridToMarkdown(block.groups, block.intro);
+        case 'recentPages':
+        case 'pageList':
+            return linkList((block.resolvedPages ?? []).map(p => ({
+                label: p.title,
+                href: p.href.startsWith('/') ? `${opts.siteUrl}${p.href}` : p.href,
+            })));
+    }
+}
+/**
+ * The new-block factories for the core types, which all three wikis had typed
+ * out identically but for a few labels. Spread into a repo's own record beside
+ * its native types, so that record stays keyed by the repo's union:
+ * `{ ...coreBlockDefaults({ stats }), daoTimeline: () => … }`.
+ */
+export function coreBlockDefaults(opts = {}) {
+    const { newId = () => crypto.randomUUID(), referencesTitle = 'References', codeTabs = [
+        { label: 'Rust', language: 'rust' },
+        { label: 'TypeScript', language: 'typescript' },
+    ], stats = [
+        { value: '100+', label: 'Customers' },
+        { value: '$1M', label: 'Revenue' },
+        { value: '99%', label: 'Uptime' },
+    ], } = opts;
+    return {
+        content: () => ({ type: 'content', text: '' }),
+        recentPages: () => ({ type: 'recentPages', limit: 5 }),
+        pageList: () => ({ type: 'pageList', pageIds: [] }),
+        columns: () => ({
+            type: 'columns',
+            columns: [{ id: newId(), blocks: [] }, { id: newId(), blocks: [] }],
+            gap: 'md',
+            align: 'start',
+        }),
+        infobox: () => ({ type: 'infobox', blocks: [] }),
+        codeTabs: () => ({ type: 'codeTabs', tabs: codeTabs.map(t => ({ ...t, code: '' })) }),
+        stats: () => ({ type: 'stats', items: stats.map(s => ({ id: newId(), ...s })), columns: 3 }),
+        linkGrid: () => ({ type: 'linkGrid', groups: [{ id: newId(), heading: 'Group', links: [] }] }),
+        references: () => ({ type: 'references', title: referencesTitle, items: [] }),
+        banner: () => ({ type: 'banner', variant: 'stub' }),
+    };
+}

package/dist/db.d.ts

@@ -0,0 +1,21 @@
+/** The options `new pg.Pool()` takes, for the fields set here. */
+export interface PgPoolConfig {
+    connectionString: string | undefined;
+    max: number;
+    idleTimeoutMillis: number;
+    connectionTimeoutMillis: number;
+}
+/**
+ * Pool options sized by which Supabase pooler the URL names, because the
+ * ceiling belongs to the pooler and not to the app. Port 6543 is the
+ * TRANSACTION pooler, which exists to hold many short-lived clients; anything
+ * else is treated as the SESSION pooler on 5432, capped at 15 clients per
+ * project and shared with a build's workers, so three each is what fits.
+ *
+ * `pg` reports an exhausted pool as "timeout exceeded when trying to connect",
+ * which reads as a network fault and is not one: connecting takes well under a
+ * second, while an acquire queued behind busy clients waits the full
+ * `connectionTimeoutMillis`. `max: 1` was serial, and three everywhere rendered
+ * a page that fans out more than three queries in thirty seconds.
+ */
+export declare function pgPoolConfig(url: string | undefined): PgPoolConfig;

package/dist/db.js

@@ -0,0 +1,27 @@
+// db.ts — the pool settings every app here hands to `pg`.
+//
+// Four Prisma client modules carried the same block, comment and all. It is a
+// value, not a client: the app still owns `new pg.Pool(...)`, the adapter and
+// the globalThis cache, so this imports nothing.
+/**
+ * Pool options sized by which Supabase pooler the URL names, because the
+ * ceiling belongs to the pooler and not to the app. Port 6543 is the
+ * TRANSACTION pooler, which exists to hold many short-lived clients; anything
+ * else is treated as the SESSION pooler on 5432, capped at 15 clients per
+ * project and shared with a build's workers, so three each is what fits.
+ *
+ * `pg` reports an exhausted pool as "timeout exceeded when trying to connect",
+ * which reads as a network fault and is not one: connecting takes well under a
+ * second, while an acquire queued behind busy clients waits the full
+ * `connectionTimeoutMillis`. `max: 1` was serial, and three everywhere rendered
+ * a page that fans out more than three queries in thirty seconds.
+ */
+export function pgPoolConfig(url) {
+    return {
+        connectionString: url,
+        max: (url ?? '').includes(':6543') ? 10 : 3,
+        idleTimeoutMillis: 20_000,
+        // The acquire timeout, despite the message it fails with.
+        connectionTimeoutMillis: 30_000,
+    };
+}

package/dist/dom.d.ts

@@ -103,3 +103,18 @@ export declare function sortTables(root: ParentNode, options?: SortTablesOptions
  * A table already in a box keeps it, so a second pass changes nothing.
  */
 export declare function scrollTables(html: string): string;
+/**
+ * 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
+ * runs and no blocklist names the request.
+ *
+ * A client-side router moves between pages with `history.pushState`, which no
+ * load event marks, so both history writes are wrapped and a view is sent
+ * whenever the path changes; a change to the query or hash alone is not a page.
+ * A click on a link to another host is sent as an "Outbound Link: Click" event
+ * carrying its `url`. Starts once per page load however often it is called, so
+ * React's doubled effects in development send one view, not two.
+ */
+export declare function startBeacon(endpoint?: string): void;
+/** Record a named event from the browser, on the endpoint `startBeacon` was given. */
+export declare function track(name: string, props?: Record<string, string | number>): void;