@hhkaos/webmentions-widget 0.1.0 → 0.2.0

package/README.md

@@ -101,6 +101,39 @@ export default function SiteWebmentions() {
 without the markup. It returns `{status, groups, error}` where `status` is
 `idle | loading | success | error`.
 
+## Build-time snapshot (recommended)
+
+By default the widget fetches in the browser, which costs webmention.io one
+request per visitor per page view — and leaves the section empty whenever their
+API is down. A snapshot inverts that: fetch once per day in CI, commit the
+result, and serve it as data.
+
+```sh
+npx webmentions-snapshot --domain example.com --out src/data/webmentions.json
+```
+
+Domain-wide queries need an API token (webmention.io → Settings → API Key),
+read from `WEBMENTION_IO_TOKEN`. The command fetches only what is new since the
+last run (`since_id`), waits between pages, and leaves the existing file
+untouched if the API errors — a bad fetch never replaces good data.
+
+Then hand the snapshot to the component:
+
+```jsx
+import snapshot from '@site/src/data/webmentions.json';
+
+<Webmentions targets={targets} snapshot={snapshot} />
+```
+
+The component narrows the whole-site snapshot to the current page locally and
+renders with **no network request at all**. Pass `revalidate` to opt back into
+a live fetch on top (the snapshot renders first either way, and a failed
+revalidation never blanks a section the snapshot could fill).
+
+Two things this buys beyond politeness: the section survives a webmention.io
+outage, and the committed JSON is a durable copy of your mentions if the
+service ever disappears.
+
 ## API
 
 ### `fetchWebmentions(options)`

package/bin/snapshot.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+
+/**
+ * Refresh a build-time webmentions snapshot.
+ *
+ * Queries webmention.io once for the whole domain instead of once per page,
+ * and only for what is new since the last run (`since_id`). A site that runs
+ * this daily costs webmention.io one or two requests a day, versus one request
+ * per visitor per page view when the widget fetches in the browser.
+ *
+ * Usage:
+ *   webmentions-snapshot --domain example.com --out src/data/webmentions.json
+ *
+ * The API token (webmention.io → Settings → API Key) is read from
+ * WEBMENTION_IO_TOKEN, or --token. Domain queries require it.
+ */
+
+import {readFile, writeFile, mkdir} from 'node:fs/promises';
+import {dirname} from 'node:path';
+
+import {getSnapshotMentions, mergeSnapshot} from '../src/core.js';
+
+const DEFAULT_API = 'https://webmention.io/api/mentions.jf2';
+const PER_PAGE = 100;
+const PAGE_DELAY_MS = 500;
+
+function parseArgs(argv) {
+  const args = {};
+
+  argv.forEach((arg, index) => {
+    if (!arg.startsWith('--')) {
+      return;
+    }
+
+    const [flag, inline] = arg.slice(2).split('=');
+    args[flag] = inline ?? (argv[index + 1]?.startsWith('--') ? true : argv[index + 1]);
+  });
+
+  return args;
+}
+
+async function readExisting(path) {
+  try {
+    return JSON.parse(await readFile(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const domain = args.domain;
+  const out = args.out;
+  const token = args.token || process.env.WEBMENTION_IO_TOKEN;
+  const apiUrl = args.api || DEFAULT_API;
+
+  if (!domain || !out) {
+    console.error('Usage: webmentions-snapshot --domain <domain> --out <file.json> [--token <token>]');
+    process.exit(2);
+  }
+
+  if (!token) {
+    console.error('Missing API token: set WEBMENTION_IO_TOKEN or pass --token.');
+    process.exit(2);
+  }
+
+  const existing = await readExisting(out);
+  const sinceId = args.full ? null : existing?.lastId ?? null;
+  const collected = [];
+
+  for (let page = 0; ; page += 1) {
+    const params = new URLSearchParams({
+      domain,
+      token,
+      'per-page': String(PER_PAGE),
+      page: String(page),
+      'sort-by': 'created',
+      'sort-dir': 'up',
+    });
+
+    if (sinceId) {
+      params.set('since_id', String(sinceId));
+    }
+
+    const response = await fetch(`${apiUrl}?${params}`);
+
+    if (!response.ok) {
+      // Leave the existing snapshot alone rather than replacing good data with
+      // a partial fetch; the next scheduled run picks up where this stopped.
+      console.error(`webmention.io responded with ${response.status}; keeping the current snapshot.`);
+      process.exit(1);
+    }
+
+    const batch = (await response.json())?.children || [];
+    collected.push(...batch);
+
+    if (batch.length < PER_PAGE) {
+      break;
+    }
+
+    await wait(PAGE_DELAY_MS);
+  }
+
+  const before = getSnapshotMentions(existing).length;
+
+  if (!collected.length && existing) {
+    console.log(`No new mentions since #${sinceId}. Snapshot unchanged (${before}).`);
+    return;
+  }
+
+  const snapshot = mergeSnapshot(existing, collected);
+
+  if (snapshot.count === before) {
+    console.log(`Snapshot unchanged (${before} mentions).`);
+    return;
+  }
+
+  await mkdir(dirname(out), {recursive: true});
+  await writeFile(out, `${JSON.stringify(snapshot, null, 2)}\n`);
+
+  console.log(`Snapshot updated: ${before} → ${snapshot.count} mentions (lastId ${snapshot.lastId}).`);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hhkaos/webmentions-widget",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Framework-agnostic, dependency-free widget to fetch and render webmention.io mentions for the current page.",
   "type": "module",
   "license": "MIT",
@@ -30,6 +30,7 @@
   },
   "files": [
     "src",
+    "bin",
     "README.md",
     "LICENSE"
   ],
@@ -49,5 +50,12 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "bin": {
+    "webmentions-snapshot": "./bin/snapshot.js"
   }
 }

package/src/core.js

@@ -391,6 +391,76 @@ export function groupWebmentions(mentions, {facepileProperties = FACEPILE_PROPER
   };
 }
 
+/**
+ * Match a mention's stored target against the variants we query for a page.
+ * Comparison ignores the trailing slash and the fragment, so a snapshot taken
+ * against one variant still matches a page queried under another.
+ */
+function targetMatches(mention, normalizedTargets) {
+  const target = normalizeUrl(mention?.['wm-target']);
+
+  return Boolean(target) && normalizedTargets.has(target);
+}
+
+/**
+ * Narrow a whole-domain snapshot down to one page.
+ *
+ * A build-time snapshot is fetched once for the entire site (webmention.io's
+ * `domain=` query), so each page has to pick out its own mentions locally
+ * rather than asking the API again.
+ */
+export function filterMentionsByTargets(mentions, targets = []) {
+  const normalizedTargets = new Set(
+    targets.map((target) => normalizeUrl(target)).filter(Boolean),
+  );
+
+  if (!normalizedTargets.size) {
+    return [];
+  }
+
+  return (mentions || []).filter((mention) => targetMatches(mention, normalizedTargets));
+}
+
+/**
+ * Read a snapshot in either accepted shape: a bare array of entries, or the
+ * `{mentions, generatedAt, lastId}` envelope that the refresh job writes.
+ */
+export function getSnapshotMentions(snapshot) {
+  if (Array.isArray(snapshot)) {
+    return snapshot;
+  }
+
+  return snapshot?.mentions || snapshot?.children || [];
+}
+
+/**
+ * Merge a fresh page of mentions into a snapshot, newest first, deduped by
+ * `wm-id`. Used by the refresh job so an incremental `since_id` fetch does not
+ * have to re-download everything.
+ */
+export function mergeSnapshot(existing, incoming) {
+  const byId = new Map();
+
+  [...getSnapshotMentions(existing), ...(incoming || [])].forEach((mention) => {
+    const key = mention?.['wm-id'] ?? mention?.['wm-source'];
+
+    if (key != null) {
+      byId.set(key, mention);
+    }
+  });
+
+  const mentions = [...byId.values()].sort((a, b) => (
+    (b['wm-id'] ?? 0) - (a['wm-id'] ?? 0)
+  ));
+
+  return {
+    generatedAt: new Date().toISOString(),
+    lastId: mentions.reduce((max, mention) => Math.max(max, mention['wm-id'] ?? 0), 0) || null,
+    count: mentions.length,
+    mentions,
+  };
+}
+
 export class WebmentionFetchError extends Error {
   constructor(message, {status, attempts, cause} = {}) {
     super(message, {cause});

package/src/react.js

@@ -5,14 +5,16 @@
  * buildless — consumers import the source directly.
  */
 
-import {createElement as h, useEffect, useMemo, useRef, useState} from 'react';
+import {createElement as h, useEffect, useMemo, useState} from 'react';
 import {
   FACEPILE_PROPERTIES,
   fetchWebmentions,
+  filterMentionsByTargets,
   formatMentionDate,
   getMentionContent,
   getMentionSourceUrl,
   getMentionType,
+  getSnapshotMentions,
   groupWebmentions,
 } from './core.js';
 
@@ -39,25 +41,42 @@ export function useWebmentions(targets, options = {}) {
     retryDelayMs,
     fallbackToJson,
     initialMentions,
+    // A whole-site snapshot, narrowed to these targets locally.
+    snapshot,
+    // With mentions already in hand, skip the network by default: the point of
+    // a snapshot is that a page view costs webmention.io nothing.
+    revalidate,
   } = options;
-  const [state, setState] = useState(() => ({
-    status: initialMentions ? 'success' : 'idle',
-    groups: initialMentions ? groupWebmentions(initialMentions) : EMPTY_GROUPS,
-    error: null,
-  }));
   const targetsKey = targets.join('\n');
-  const optionsRef = useRef(options);
-  optionsRef.current = options;
+
+  // Derived, not stored: on a client-side route change the targets change, and
+  // state seeded once in a useState initializer would go stale.
+  const seededGroups = useMemo(() => {
+    if (initialMentions) {
+      return groupWebmentions(initialMentions);
+    }
+
+    if (!snapshot) {
+      return null;
+    }
+
+    return groupWebmentions(
+      filterMentionsByTargets(getSnapshotMentions(snapshot), targetsKey ? targetsKey.split('\n') : []),
+    );
+  }, [initialMentions, snapshot, targetsKey]);
+
+  const shouldFetch = (revalidate ?? !seededGroups) && Boolean(targetsKey);
+  const [fetched, setFetched] = useState({status: 'idle', groups: null, error: null});
 
   useEffect(() => {
-    if (!targetsKey) {
+    if (!shouldFetch) {
       return undefined;
     }
 
     const controller = new AbortController();
     let active = true;
 
-    setState((previous) => ({...previous, status: 'loading'}));
+    setFetched({status: 'loading', groups: null, error: null});
 
     fetchWebmentions({
       targets: targetsKey.split('\n'),
@@ -70,12 +89,12 @@ export function useWebmentions(targets, options = {}) {
     })
       .then((mentions) => {
         if (active) {
-          setState({status: 'success', groups: groupWebmentions(mentions), error: null});
+          setFetched({status: 'success', groups: groupWebmentions(mentions), error: null});
         }
       })
       .catch((error) => {
         if (active && error?.name !== 'AbortError') {
-          setState({status: 'error', groups: EMPTY_GROUPS, error});
+          setFetched({status: 'error', groups: null, error});
         }
       });
 
@@ -83,9 +102,19 @@ export function useWebmentions(targets, options = {}) {
       active = false;
       controller.abort();
     };
-  }, [targetsKey, apiUrl, perPage, retries, retryDelayMs, fallbackToJson]);
+  }, [targetsKey, shouldFetch, apiUrl, perPage, retries, retryDelayMs, fallbackToJson]);
+
+  // A live result wins once it lands; until then the snapshot renders. A failed
+  // revalidation never blanks a section the snapshot could still fill.
+  if (fetched.groups) {
+    return fetched;
+  }
 
-  return state;
+  if (seededGroups) {
+    return {status: 'success', groups: seededGroups, error: fetched.error};
+  }
+
+  return {status: fetched.status, groups: EMPTY_GROUPS, error: fetched.error};
 }
 
 function Face({mention, classNames}) {
@@ -197,6 +226,9 @@ export function Webmentions({
   locale,
   maxLength,
   classNames: classNameOverrides = {},
+  // Optional wrapper inside the <aside>, for hosts whose layout CSS keys off a
+  // width-constraining element (Docusaurus's `.container`, for example).
+  innerClassName = null,
   renderEmpty = null,
   renderError = null,
   ...options
@@ -216,14 +248,12 @@ export function Webmentions({
     return renderEmpty ? renderEmpty() : null;
   }
 
-  return h(
-    'aside',
-    {className: classNames.root, 'aria-labelledby': `${classNames.title}-heading`},
-    h('h2', {id: `${classNames.title}-heading`, className: classNames.title}, title),
+  const children = [
+    h('h2', {key: 'title', id: `${classNames.title}-heading`, className: classNames.title}, title),
     groups.interactions.length
       ? h(
         'ol',
-        {className: classNames.facepile, 'aria-label': 'Reactions'},
+        {key: 'facepile', className: classNames.facepile, 'aria-label': 'Reactions'},
         groups.interactions.map((mention) => h(Face, {
           key: mention['wm-id'] || mention.url || mention['wm-source'],
           mention,
@@ -234,7 +264,7 @@ export function Webmentions({
     groups.threads.length
       ? h(
         'ol',
-        {className: classNames.threadList},
+        {key: 'threads', className: classNames.threadList},
         groups.threads.map((mention) => h(Thread, {
           key: mention['wm-id'] || mention.url || mention['wm-source'],
           mention,
@@ -245,6 +275,12 @@ export function Webmentions({
         })),
       )
       : null,
+  ];
+
+  return h(
+    'aside',
+    {className: classNames.root, 'aria-labelledby': `${classNames.title}-heading`},
+    innerClassName ? h('div', {className: innerClassName}, children) : children,
   );
 }