@profullstack/footer 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Profullstack, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# @profullstack/footer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One footer for every Profullstack site: your links, the copyright line, and the
+`<<  Profullstack  >>  ⚄` webring nav (previous, ring, next, random).
+
+**Publish once, every site updates.** The markup and CSS ship as data
+(`template.json`). At render time each site fetches
+`https://cdn.jsdelivr.net/npm/@profullstack/footer@latest/template.json`
+(1 h cache, 1.5 s timeout, the bundled copy as the fallback), so a release reaches
+every site within the hour with no bump, rebuild or redeploy. Install it as
+`"@profullstack/footer": "latest"` too, so the render code follows on the next install.
+
+It renders on the server: the ring's verifier reads your HTML and never runs
+script, so a client-only footer would never count as a ring member.
+
+## Install
+
+```sh
+pnpm add @profullstack/footer@latest   # or npm i / bun add
+```
+
+## Next.js (App Router)
+
+```jsx
+// app/layout.jsx (a server component)
+import { Footer } from '@profullstack/footer/react';
+
+<Footer site="https://example.com/" links={[{ label: 'Docs', href: '/docs' }]} since={2025} />
+```
+
+and the ring descriptor:
+
+```js
+// app/.well-known/openwebring.json/route.js
+import { descriptorResponse } from '@profullstack/footer';
+export const GET = () => descriptorResponse({ site: 'https://example.com/', name: 'Example' });
+```
+
+## Hono / Express / Bun / SvelteKit
+
+```js
+import { footerHtml } from '@profullstack/footer';
+const footer = await footerHtml({ site: 'https://example.com/', links: [{ label: 'Docs', href: '/docs' }] });
+// Svelte: {@html footer}   Hono: c.html(`...${footer}`)
+```
+
+## Static HTML (no server)
+
+Print the footer once and keep it in the page (that is what the verifier sees),
+then let the embed swap in the @latest one in the browser:
+
+```sh
+npx @profullstack/footer html --site https://example.com/ --link Docs=/docs
+```
+
+```html
+<footer data-profullstack-footer data-site="https://example.com/" data-links='[{"label":"Docs","href":"/docs"}]'>
+  …output of the command above…
+</footer>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@profullstack/footer@latest/src/embed.js"></script>
+```
+
+## Options
+
+| option | default | |
+|---|---|---|
+| `site` | required | your homepage; `from=` on every hop |
+| `links` | `[]` | `{ label, href, rel? }[]`, shown before house links |
+| `since` | | first year: `© 2024–2026` |
+| `owner` | `Profullstack, Inc.` → profullstack.com | `{ name, url }` |
+| `tagline` | | after the copyright, e.g. `MIT licensed` |
+| `ring` | `{ slug: 'profullstack', name: 'Profullstack', host: 'https://rssamplifier.com' }` | |
+| `css` | `true` | `false` drops the `<style>`; style `.pfs-footer*` yourself |
+| `houseLinks` | `true` | `false` hides links the template adds for every site |
+
+Theme it with `--pfs-footer-muted`, `--pfs-footer-gap` and `--pfs-footer-size` on
+`.pfs-footer`; colors otherwise inherit from the page.
+
+## CLI
+
+```sh
+profullstack-footer html --site https://example.com/ [--link Docs=/docs] [--since 2024] [--offline] [--no-css]
+profullstack-footer json --site https://example.com/          # the four ring URLs
+profullstack-footer descriptor --site https://example.com/    # /.well-known/openwebring.json
+profullstack-footer template                                  # the @latest template
+profullstack-footer check https://example.com/                # does the live page link the ring?
+```
+
+## Changing the footer for every site
+
+Edit `src/template.js`, bump the version in it and in package.json, `npm run build`,
+open a PR, merge, and publish a GitHub release `vX.Y.Z`. The publish workflow puts it
+on npm and purges jsDelivr's `@latest` so sites pick it up on their next cache refresh.
+Bump `renderer` (and `RENDERER` in render.js) only when the template needs a
+placeholder older installs cannot fill; they keep their bundled template until
+reinstalled.
+
+**Safety:** remote templates are sanitized before use (no `<script>`, `<iframe>`,
+event handlers or `javascript:` URLs; CSS cannot close its `<style>` or `@import`),
+and option values are always escaped.
+
+Env: `PROFULLSTACK_FOOTER_OFFLINE=1` never fetches; `PROFULLSTACK_FOOTER_TEMPLATE_URL` overrides the CDN URL.
+
+MIT © Profullstack, Inc.

package/bin/profullstack-footer.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// profullstack-footer: print the footer or the ring descriptor for a site.
+//
+//   profullstack-footer html --site https://example.com/ [--name Example] [--link Docs=/docs]... [--since 2024] [--no-css]
+//   profullstack-footer json --site https://example.com/      the ring URLs
+//   profullstack-footer descriptor --site https://example.com/ [--slug example-com] [--name Example]
+//   profullstack-footer template                               the @latest template this install would use
+//   profullstack-footer check https://example.com/             does the live page carry prev/next/random?
+
+import { parseArgs } from 'node:util';
+import { footerHtml, footerHtmlSync, ringLinks, descriptor, latestTemplate, canonicalSite } from '../src/index.js';
+
+const HELP = `usage: profullstack-footer <html|json|descriptor|template|check> [options]
+
+  --site <url>        the site's homepage (required except for template)
+  --name <name>       site name (descriptor, data attribute)
+  --link Label=href   a footer link; repeat for more
+  --since <year>      first copyright year
+  --tagline <text>    short line after the copyright
+  --slug <slug>       ring member slug (descriptor; default host with dashes)
+  --offline           use the bundled template, do not fetch @latest
+  --no-css            leave the <style> out
+`;
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    site: { type: 'string' },
+    name: { type: 'string' },
+    link: { type: 'string', multiple: true },
+    since: { type: 'string' },
+    tagline: { type: 'string' },
+    slug: { type: 'string' },
+    offline: { type: 'boolean' },
+    'no-css': { type: 'boolean' },
+    help: { type: 'boolean', short: 'h' },
+  },
+});
+
+const [cmd, arg] = positionals;
+if (values.help || !cmd) {
+  process.stdout.write(HELP);
+  process.exit(cmd || values.help ? 0 : 2);
+}
+
+const site = values.site ?? arg;
+const need = () => {
+  if (!site) {
+    process.stderr.write('profullstack-footer: --site is required\n');
+    process.exit(2);
+  }
+  return site;
+};
+const links = (values.link ?? []).map((s) => {
+  const i = s.indexOf('=');
+  return { label: s.slice(0, i), href: s.slice(i + 1) };
+});
+const opts = () => ({
+  site: need(),
+  name: values.name,
+  links,
+  since: values.since ? Number(values.since) : undefined,
+  tagline: values.tagline,
+  css: !values['no-css'],
+});
+
+switch (cmd) {
+  case 'html':
+    process.stdout.write((values.offline ? footerHtmlSync(opts()) : await footerHtml(opts())) + '\n');
+    break;
+  case 'json':
+    process.stdout.write(JSON.stringify(ringLinks(need()), null, 2) + '\n');
+    break;
+  case 'descriptor':
+    process.stdout.write(JSON.stringify(descriptor({ site: need(), name: values.name, slug: values.slug }), null, 2) + '\n');
+    break;
+  case 'template':
+    process.stdout.write(JSON.stringify(await latestTemplate(), null, 2) + '\n');
+    break;
+  case 'check': {
+    const home = canonicalSite(need());
+    const res = await fetch(home, { redirect: 'follow', headers: { 'user-agent': 'profullstack-footer-check' } });
+    const html = (await res.text()).replace(/&amp;/g, '&');
+    const want = ringLinks(home);
+    let ok = res.ok;
+    for (const k of /** @type {const} */ (['previous', 'next', 'random'])) {
+      const has = html.includes(want[k]);
+      ok &&= has;
+      process.stdout.write(`${has ? 'ok  ' : 'MISS'} ${k} ${want[k]}\n`);
+    }
+    process.stdout.write(`${home} ${res.status} ${ok ? 'links the ring' : 'does NOT link the ring'}\n`);
+    process.exit(ok ? 0 : 1);
+  }
+  default:
+    process.stderr.write(`profullstack-footer: unknown command ${cmd}\n${HELP}`);
+    process.exit(2);
+}

package/index.d.ts

@@ -0,0 +1,67 @@
+export interface FooterLink { label: string; href: string; rel?: string }
+export interface RingOptions { slug?: string; name?: string; host?: string }
+export interface FooterOptions {
+  /** The site's homepage; hops are measured from it. */
+  site: string;
+  name?: string;
+  /** The site's own links, shown before any house links. */
+  links?: FooterLink[];
+  /** Defaults to Profullstack, Inc. / https://profullstack.com/ */
+  owner?: { name?: string; url?: string };
+  /** First copyright year: renders "since–year". */
+  since?: number;
+  /** Override the copyright year (defaults to the current UTC year). */
+  year?: number;
+  tagline?: string;
+  ring?: RingOptions;
+  /** false leaves the <style> out (bring your own CSS). */
+  css?: boolean;
+  /** false hides the template's house links. */
+  houseLinks?: boolean;
+}
+export interface FooterTemplate {
+  version: string;
+  renderer: number;
+  css: string;
+  link: string;
+  footer: string;
+  houseLinks?: FooterLink[];
+}
+export interface RingLinks { ring: string; previous: string; next: string; random: string }
+export interface Descriptor {
+  openwebring: '0.1';
+  site: { url: string; name: string };
+  made_by: 'human' | 'ai' | 'both';
+  rings: { ring: string; slug: string }[];
+}
+export interface DescriptorOptions {
+  site: string;
+  name?: string;
+  slug?: string;
+  madeBy?: 'human' | 'ai' | 'both';
+  ring?: RingOptions;
+}
+
+export declare const RENDERER: number;
+export declare const TEMPLATE_URL: string;
+export declare const DEFAULT_RING: Required<RingOptions>;
+export declare const DEFAULT_OWNER: { name: string; url: string };
+export declare const bundledTemplate: FooterTemplate;
+
+export declare function footerHtml(opts: FooterOptions & { template?: FooterTemplate }): Promise<string>;
+export declare function footerHtmlSync(opts: FooterOptions): string;
+export declare function renderFooter(template: FooterTemplate, opts: FooterOptions): string;
+export declare function latestTemplate(opts?: {
+  url?: string;
+  ttlMs?: number;
+  timeoutMs?: number;
+  fetch?: typeof fetch;
+  now?: () => number;
+}): Promise<FooterTemplate>;
+export declare function resetTemplateCache(): void;
+export declare function ringLinks(site: string, ring?: RingOptions): RingLinks;
+export declare function canonicalSite(site: string): string;
+export declare function descriptor(opts: DescriptorOptions): Descriptor;
+export declare function descriptorResponse(opts: DescriptorOptions): Response;
+export declare function escapeHtml(value: unknown): string;
+export declare function sanitizeTemplate(html: string): string;

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@profullstack/footer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "type": "module",
+  "description": "One footer for every Profullstack site: links, copyright and the << Profullstack >> webring nav with Random. Sites render the @latest template from the CDN at runtime, so a release updates every site without a redeploy.",
+  "keywords": ["footer", "webring", "openwebring", "copyright", "react", "nextjs", "hono", "ssr"],
+  "repository": { "type": "git", "url": "git+https://github.com/profullstack/footer.git" },
+  "homepage": "https://github.com/profullstack/footer#readme",
+  "bugs": { "url": "https://github.com/profullstack/footer/issues" },
+  "license": "MIT",
+  "author": "Profullstack, Inc.",
+  "exports": {
+    ".": { "types": "./index.d.ts", "import": "./src/index.js" },
+    "./react": { "types": "./react.d.ts", "import": "./src/react.js" },
+    "./render": { "types": "./index.d.ts", "import": "./src/render.js" },
+    "./embed": "./src/embed.js",
+    "./template.json": "./template.json",
+    "./package.json": "./package.json"
+  },
+  "bin": { "profullstack-footer": "bin/profullstack-footer.js" },
+  "files": ["src", "bin", "index.d.ts", "react.d.ts", "template.json", "README.md", "LICENSE"],
+  "sideEffects": ["./src/embed.js"],
+  "peerDependencies": { "react": ">=18" },
+  "peerDependenciesMeta": { "react": { "optional": true } },
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "node scripts/build-json.js",
+    "test": "node --test",
+    "prepack": "node scripts/build-json.js"
+  }
+}

package/react.d.ts

@@ -0,0 +1,6 @@
+import type { FooterOptions } from './index.js';
+/** Async React server component (Next App Router, React 19 SSR). */
+export declare function Footer(props: FooterOptions): Promise<any>;
+/** Synchronous, bundled template; for client components or React 18 renderToString. */
+export declare function FooterSync(props: FooterOptions): any;
+export default Footer;

package/src/embed.js

@@ -0,0 +1,45 @@
+// For static HTML sites with no server to render on. Load from the CDN:
+//
+//   <footer data-profullstack-footer data-site="https://example.com/"
+//           data-links='[{"label":"Docs","href":"/docs"}]'>
+//     ...the ring links, server-rendered, as the fallback crawlers see...
+//   </footer>
+//   <script type="module" src="https://cdn.jsdelivr.net/npm/@profullstack/footer@latest/src/embed.js"></script>
+//
+// Keep real ring links inside the element: the ring's verifier reads the HTML
+// and never runs this script. `profullstack-footer html --site ...` prints them.
+
+import { footerHtml } from './index.js';
+
+/** @param {string | undefined} raw */
+function parse(raw) {
+  try {
+    return raw ? JSON.parse(raw) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function mount(root = document) {
+  const nodes = root.querySelectorAll('[data-profullstack-footer]');
+  for (const el of nodes) {
+    const d = /** @type {HTMLElement} */ (el).dataset;
+    const site = d.site || location.origin + '/';
+    const html = await footerHtml({
+      site,
+      name: d.name,
+      tagline: d.tagline,
+      since: d.since ? Number(d.since) : undefined,
+      links: parse(d.links),
+      owner: parse(d.owner),
+    });
+    const tpl = document.createElement('template');
+    tpl.innerHTML = html;
+    el.replaceWith(tpl.content);
+  }
+}
+
+if (typeof document !== 'undefined') {
+  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', () => mount());
+  else mount();
+}

package/src/index.js

@@ -0,0 +1,125 @@
+// @profullstack/footer: one footer for every Profullstack site.
+//
+// The markup lives in template.js and ships as template.json. `footerHtml`
+// fetches the @latest template from the CDN at render time (cached, with the
+// bundled copy as the fallback), so publishing a release is the whole
+// rollout: no site has to bump, rebuild or redeploy.
+
+import bundled from './template.js';
+import { RENDERER, renderFooter, descriptor } from './render.js';
+
+export {
+  RENDERER,
+  DEFAULT_OWNER,
+  DEFAULT_RING,
+  canonicalSite,
+  descriptor,
+  escapeHtml,
+  renderFooter,
+  ringLinks,
+  sanitizeTemplate,
+} from './render.js';
+export { bundled as bundledTemplate };
+
+export const TEMPLATE_URL = 'https://cdn.jsdelivr.net/npm/@profullstack/footer@latest/template.json';
+
+const DEFAULT_TTL_MS = 60 * 60 * 1000;
+const FAILURE_TTL_MS = 5 * 60 * 1000;
+
+/** @type {{ template: any, until: number, pending: Promise<any> | null }} */
+const cache = { template: null, until: 0, pending: null };
+
+/** @param {any} t */
+function usable(t) {
+  return (
+    t &&
+    typeof t === 'object' &&
+    typeof t.footer === 'string' &&
+    typeof t.link === 'string' &&
+    typeof t.css === 'string' &&
+    Number(t.renderer ?? 1) <= RENDERER
+  );
+}
+
+/**
+ * The newest template this install can render. Never throws and never waits
+ * longer than `timeoutMs`: a slow or broken CDN gives the bundled template.
+ *
+ * @param {{ url?: string, ttlMs?: number, timeoutMs?: number, fetch?: typeof fetch, now?: () => number }} [opts]
+ */
+export async function latestTemplate(opts = {}) {
+  const env = typeof process !== 'undefined' ? process.env ?? {} : {};
+  if (env.PROFULLSTACK_FOOTER_OFFLINE === '1') return bundled;
+  const now = (opts.now ?? Date.now)();
+  if (cache.template && now < cache.until) return cache.template;
+  // Stale while revalidating: hand back what we have, refresh once.
+  if (cache.template && cache.pending) return cache.template;
+
+  const doFetch = opts.fetch ?? globalThis.fetch;
+  if (typeof doFetch !== 'function') return bundled;
+  const url = opts.url ?? env.PROFULLSTACK_FOOTER_TEMPLATE_URL ?? TEMPLATE_URL;
+  const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
+
+  cache.pending = (async () => {
+    try {
+      const ctrl = typeof AbortController === 'function' ? new AbortController() : null;
+      const timer = ctrl ? setTimeout(() => ctrl.abort(), opts.timeoutMs ?? 1500) : null;
+      /** @type {RequestInit & { next?: { revalidate: number } }} */
+      const init = { signal: ctrl?.signal, headers: { accept: 'application/json' }, next: { revalidate: Math.round(ttl / 1000) } };
+      const res = await doFetch(url, init).finally(() => timer && clearTimeout(timer));
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const t = await res.json();
+      if (!usable(t)) throw new Error('template not usable by this renderer');
+      cache.template = t;
+      cache.until = (opts.now ?? Date.now)() + ttl;
+    } catch {
+      cache.template = cache.template ?? bundled;
+      cache.until = (opts.now ?? Date.now)() + FAILURE_TTL_MS;
+    } finally {
+      cache.pending = null;
+    }
+    return cache.template;
+  })();
+
+  return cache.template ?? cache.pending;
+}
+
+/** Forget the cached template (tests, or a manual refresh hook). */
+export function resetTemplateCache() {
+  cache.template = null;
+  cache.until = 0;
+  cache.pending = null;
+}
+
+/**
+ * The footer HTML using the @latest template. Use this on the server.
+ * @param {import('./render.js').FooterOptions & { template?: import('./render.js').FooterTemplate }} opts
+ */
+export async function footerHtml(opts) {
+  const template = opts.template ?? (await latestTemplate());
+  return renderFooter(template, opts);
+}
+
+/**
+ * The footer HTML from the template bundled in this install, with no network.
+ * For build-time rendering and places that cannot await.
+ * @param {import('./render.js').FooterOptions} opts
+ */
+export function footerHtmlSync(opts) {
+  return renderFooter(bundled, opts);
+}
+
+/**
+ * A ready Response for a /.well-known/openwebring.json route (Next route
+ * handlers, Hono, Bun.serve, Workers).
+ * @param {Parameters<typeof descriptor>[0]} opts
+ */
+export function descriptorResponse(opts) {
+  return new Response(JSON.stringify(descriptor(opts), null, 2) + '\n', {
+    headers: {
+      'content-type': 'application/json; charset=utf-8',
+      'cache-control': 'public, max-age=3600',
+      'access-control-allow-origin': '*',
+    },
+  });
+}

package/src/react.js

@@ -0,0 +1,19 @@
+// React server component. No hooks and no JSX, so it renders on the server in
+// Next's App Router (and any React 18+ SSR) and needs no build step here.
+// Async: the template is the CDN's @latest, fetched and cached by index.js.
+
+import { createElement } from 'react';
+import { footerHtml, footerHtmlSync } from './index.js';
+
+/** @param {import('./render.js').FooterOptions} props */
+export async function Footer(props) {
+  const html = await footerHtml(props);
+  return createElement('div', { style: { display: 'contents' }, dangerouslySetInnerHTML: { __html: html } });
+}
+
+/** Synchronous variant from the bundled template, for client components or old React. */
+export function FooterSync(props) {
+  return createElement('div', { style: { display: 'contents' }, dangerouslySetInnerHTML: { __html: footerHtmlSync(props) } });
+}
+
+export default Footer;

package/src/render.js

@@ -0,0 +1,160 @@
+// Pure rendering: no I/O, safe in any runtime (Node, Bun, edge, browser).
+
+export const RENDERER = 1;
+
+export const DEFAULT_RING = {
+  slug: 'profullstack',
+  name: 'Profullstack',
+  host: 'https://rssamplifier.com',
+};
+
+export const DEFAULT_OWNER = { name: 'Profullstack, Inc.', url: 'https://profullstack.com/' };
+
+const ESC = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+
+/** @param {unknown} value */
+export function escapeHtml(value) {
+  return String(value ?? '').replace(/[&<>"']/g, (c) => ESC[c]);
+}
+
+/**
+ * The canonical homepage a ring hop is measured from: scheme, host and a
+ * trailing slash. `example.com` and `https://example.com/blog?x=1` both give
+ * `https://example.com/`.
+ * @param {string} site
+ */
+export function canonicalSite(site) {
+  const raw = String(site ?? '').trim();
+  if (!raw) throw new TypeError('@profullstack/footer: `site` is required (e.g. "https://example.com/")');
+  const url = new URL(/^https?:\/\//i.test(raw) ? raw : `https://${raw}`);
+  return `${url.protocol}//${url.host}/`;
+}
+
+/**
+ * The four ring URLs for a site. Hops are server-side redirects on the ring
+ * host, so the order of the ring never lives in a site's code.
+ * @param {string} site
+ * @param {{ slug?: string, host?: string }} [ring]
+ */
+export function ringLinks(site, ring = {}) {
+  const host = String(ring.host ?? DEFAULT_RING.host).replace(/\/+$/, '');
+  const base = `${host}/ring/${encodeURIComponent(ring.slug ?? DEFAULT_RING.slug)}`;
+  const from = encodeURIComponent(canonicalSite(site));
+  return {
+    ring: base,
+    previous: `${base}/previous?from=${from}`,
+    next: `${base}/next?from=${from}`,
+    random: `${base}/random?from=${from}`,
+  };
+}
+
+/** @param {number} since @param {number} year */
+export function years(since, year) {
+  return since && since < year ? `${since}–${year}` : String(year);
+}
+
+/**
+ * Strip what a template must never carry. Templates arrive over the network
+ * from the CDN and land in every site's HTML, so a bad publish must not be
+ * able to run script there.
+ * @param {string} html
+ */
+export function sanitizeTemplate(html) {
+  return String(html ?? '')
+    .replace(/<\s*(script|iframe|object|embed|form|noscript|template|svg|math)\b[\s\S]*?<\s*\/\s*\1\s*>/gi, '')
+    .replace(/<\s*\/?\s*(script|iframe|object|embed|link|meta|base|form|noscript|template|svg|math)\b[^>]*>/gi, '')
+    .replace(/\son[a-z]+\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, '')
+    .replace(/(href|src|action)\s*=\s*("|')\s*(javascript|data|vbscript):[^"']*\2/gi, '$1=$2#$2');
+}
+
+/** @param {string} css */
+export function sanitizeCss(css) {
+  return String(css ?? '')
+    .replace(/<\/?\s*style/gi, '')
+    .replace(/@import[^;]*;?/gi, '')
+    .replace(/expression\s*\(/gi, '(')
+    .replace(/url\s*\(\s*(['"]?)\s*javascript:[^)]*\)/gi, 'none');
+}
+
+/**
+ * Fill `{{x}}`, `{{{x}}}` and `{{#x}}...{{/x}}`. Unknown names render empty.
+ * @param {string} tpl
+ * @param {Record<string, unknown>} vars
+ */
+export function fill(tpl, vars) {
+  const sections = /\{\{#(\w+)\}\}([\s\S]*?)\{\{\/\1\}\}/g;
+  let out = String(tpl);
+  // Sections first (twice handles one level of nesting).
+  for (let i = 0; i < 2; i++) {
+    out = out.replace(sections, (_, name, body) => {
+      const v = vars[name];
+      return v === undefined || v === null || v === false || v === '' || (Array.isArray(v) && !v.length) ? '' : body;
+    });
+  }
+  return out
+    .replace(/\{\{\{(\w+)\}\}\}/g, (_, name) => String(vars[name] ?? ''))
+    .replace(/\{\{(\w+)\}\}/g, (_, name) => escapeHtml(vars[name]));
+}
+
+/**
+ * @typedef {{ label: string, href: string, rel?: string }} FooterLink
+ * @typedef {{
+ *   site: string,
+ *   name?: string,
+ *   links?: FooterLink[],
+ *   owner?: { name?: string, url?: string },
+ *   since?: number,
+ *   year?: number,
+ *   tagline?: string,
+ *   ring?: { slug?: string, name?: string, host?: string },
+ *   css?: boolean,
+ *   houseLinks?: boolean,
+ * }} FooterOptions
+ * @typedef {{ version: string, renderer: number, css: string, link: string, footer: string, houseLinks?: FooterLink[] }} FooterTemplate
+ */
+
+/**
+ * Render the footer from a template. Synchronous and pure.
+ * @param {FooterTemplate} template
+ * @param {FooterOptions} opts
+ */
+export function renderFooter(template, opts) {
+  const ring = { ...DEFAULT_RING, ...(opts.ring ?? {}) };
+  const owner = { ...DEFAULT_OWNER, ...(opts.owner ?? {}) };
+  const hops = ringLinks(opts.site, ring);
+  const year = opts.year ?? new Date().getUTCFullYear();
+  const linkTpl = sanitizeTemplate(template.link);
+  const all = [...(opts.links ?? []), ...(opts.houseLinks === false ? [] : (template.houseLinks ?? []))];
+  const links = all
+    .filter((l) => l && l.href && l.label && !/^\s*(javascript|data|vbscript):/i.test(l.href))
+    .map((l) => fill(linkTpl, { href: l.href, label: l.label, rel: l.rel ?? '' }))
+    .join('');
+  return fill(sanitizeTemplate(template.footer), {
+    version: template.version,
+    css: opts.css === false ? '' : sanitizeCss(template.css),
+    links,
+    ...hops,
+    ring_name: ring.name,
+    years: years(opts.since ?? 0, year),
+    owner_name: owner.name,
+    owner_url: owner.url,
+    tagline: opts.tagline ?? '',
+    site: canonicalSite(opts.site),
+    name: opts.name ?? '',
+  });
+}
+
+/**
+ * The /.well-known/openwebring.json body that states the site's membership.
+ * @param {{ site: string, name?: string, slug?: string, madeBy?: 'human'|'ai'|'both', ring?: { slug?: string, host?: string } }} opts
+ */
+export function descriptor(opts) {
+  const site = canonicalSite(opts.site);
+  const { ring } = ringLinks(site, opts.ring);
+  return {
+    openwebring: '0.1',
+    site: { url: site, name: opts.name ?? new URL(site).host },
+    made_by: opts.madeBy ?? 'both',
+    rings: [{ ring, slug: opts.slug ?? new URL(site).host.replace(/^www\./, '').replace(/\./g, '-') }],
+  };
+}

package/src/template.js

@@ -0,0 +1,64 @@
+// The footer itself, as data. This object is what changes between releases:
+// it is published as template.json and every installed copy fetches the
+// @latest one at render time (see index.js), so a release reaches every site
+// without a redeploy. Placeholders: {{name}} is escaped, {{{name}}} is raw
+// (only for values this package builds itself), {{#name}}...{{/name}} keeps
+// the block when the value is non-empty.
+//
+// Bump `renderer` only when the template needs placeholders an older
+// render.js does not fill; older installs then keep their bundled template.
+
+// OpenIcon line glyphs (github.com/profullstack/openicon, keys `random` and
+// `vote`) as CSS masks. A template may not carry <svg> (sanitizeTemplate strips
+// it), and a mask over currentColor keeps the icon the colour of the link.
+const glyph = (body) =>
+  `url("data:image/svg+xml,${encodeURIComponent(
+    `<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'>${body}</svg>`,
+  )}")`;
+const RANDOM = glyph(
+  "<rect x='3' y='3' width='18' height='18' rx='3'/><circle cx='8' cy='8' r='1'/><circle cx='16' cy='8' r='1'/><circle cx='12' cy='12' r='1'/><circle cx='8' cy='16' r='1'/><circle cx='16' cy='16' r='1'/>",
+);
+const VOTE = glyph("<path d='M12 4 21 19H3z'/>");
+
+export default {
+  version: '0.2.0',
+  renderer: 1,
+  css: [
+    '.pfs-footer{--pfs-footer-muted:color-mix(in srgb,currentColor 62%,transparent);--pfs-footer-gap:.5rem 1.25rem;--pfs-footer-size:.875rem;',
+    'border-top:1px solid color-mix(in srgb,currentColor 14%,transparent);font-size:var(--pfs-footer-size);line-height:1.5;color:inherit}',
+    '.pfs-footer__inner{max-width:72rem;margin:0 auto;padding:1.5rem 1rem;display:flex;flex-direction:column;align-items:center;gap:.75rem;text-align:center}',
+    '.pfs-footer a{color:var(--pfs-footer-muted);text-decoration:none}',
+    '.pfs-footer a:hover,.pfs-footer a:focus-visible{color:inherit;text-decoration:underline}',
+    '.pfs-footer__links{display:flex;flex-wrap:wrap;justify-content:center;gap:var(--pfs-footer-gap)}',
+    '.pfs-footer__ring{display:flex;flex-wrap:wrap;justify-content:center;align-items:center;gap:.6rem}',
+    '.pfs-footer__icon{display:inline-block;width:1em;height:1em;vertical-align:-.125em;background-color:currentColor;',
+    '-webkit-mask:var(--pfs-footer-glyph) center/contain no-repeat;mask:var(--pfs-footer-glyph) center/contain no-repeat}',
+    `.pfs-footer__icon--random{--pfs-footer-glyph:${RANDOM}}`,
+    `.pfs-footer__icon--vote{--pfs-footer-glyph:${VOTE}}`,
+    '.pfs-footer__copy{margin:0;color:var(--pfs-footer-muted)}',
+    '.pfs-footer__copy a{color:inherit}',
+  ].join(''),
+  link: '<a href="{{href}}"{{#rel}} rel="{{rel}}"{{/rel}}>{{label}}</a>',
+  footer: [
+    '<footer class="pfs-footer" data-pfs-footer="{{version}}">',
+    '{{#css}}<style>{{{css}}}</style>{{/css}}',
+    '<div class="pfs-footer__inner">',
+    '{{#links}}<nav class="pfs-footer__links" aria-label="Footer">{{{links}}}</nav>{{/links}}',
+    '<nav class="webring pfs-footer__ring" aria-label="{{ring_name}} webring">',
+    '<a href="{{previous}}" rel="prev" title="Previous site">&lt;&lt;</a>',
+    '<a href="{{ring}}">{{ring_name}}</a>',
+    '<a href="{{next}}" rel="next" title="Next site">&gt;&gt;</a>',
+    '<a href="{{random}}" title="Random site" aria-label="Random site"><span class="pfs-footer__icon pfs-footer__icon--random" aria-hidden="true"></span></a>',
+    // Anonymous, throttled vote for this site. A bare URL because a new
+    // placeholder would need a renderer bump; the ring host finds the site
+    // from the Referer, and referrerpolicy keeps the origin on sites whose
+    // own policy is no-referrer.
+    '<a href="{{ring}}/vote" referrerpolicy="origin" title="Vote for this site" aria-label="Vote for this site"><span class="pfs-footer__icon pfs-footer__icon--vote" aria-hidden="true"></span></a>',
+    '</nav>',
+    '<p class="pfs-footer__copy">&copy; {{years}} <a href="{{owner_url}}">{{owner_name}}</a>{{#tagline}} &middot; {{tagline}}{{/tagline}}</p>',
+    '</div>',
+    '</footer>',
+  ].join(''),
+  // Links every site shows after its own, e.g. a house status page.
+  houseLinks: [],
+};

package/template.json

@@ -0,0 +1,8 @@
+{
+  "version": "0.2.0",
+  "renderer": 1,
+  "css": ".pfs-footer{--pfs-footer-muted:color-mix(in srgb,currentColor 62%,transparent);--pfs-footer-gap:.5rem 1.25rem;--pfs-footer-size:.875rem;border-top:1px solid color-mix(in srgb,currentColor 14%,transparent);font-size:var(--pfs-footer-size);line-height:1.5;color:inherit}.pfs-footer__inner{max-width:72rem;margin:0 auto;padding:1.5rem 1rem;display:flex;flex-direction:column;align-items:center;gap:.75rem;text-align:center}.pfs-footer a{color:var(--pfs-footer-muted);text-decoration:none}.pfs-footer a:hover,.pfs-footer a:focus-visible{color:inherit;text-decoration:underline}.pfs-footer__links{display:flex;flex-wrap:wrap;justify-content:center;gap:var(--pfs-footer-gap)}.pfs-footer__ring{display:flex;flex-wrap:wrap;justify-content:center;align-items:center;gap:.6rem}.pfs-footer__icon{display:inline-block;width:1em;height:1em;vertical-align:-.125em;background-color:currentColor;-webkit-mask:var(--pfs-footer-glyph) center/contain no-repeat;mask:var(--pfs-footer-glyph) center/contain no-repeat}.pfs-footer__icon--random{--pfs-footer-glyph:url(\"data:image/svg+xml,%3Csvg%20xmlns%3D'http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg'%20viewBox%3D'0%200%2024%2024'%20fill%3D'none'%20stroke%3D'black'%20stroke-width%3D'2'%20stroke-linecap%3D'round'%20stroke-linejoin%3D'round'%3E%3Crect%20x%3D'3'%20y%3D'3'%20width%3D'18'%20height%3D'18'%20rx%3D'3'%2F%3E%3Ccircle%20cx%3D'8'%20cy%3D'8'%20r%3D'1'%2F%3E%3Ccircle%20cx%3D'16'%20cy%3D'8'%20r%3D'1'%2F%3E%3Ccircle%20cx%3D'12'%20cy%3D'12'%20r%3D'1'%2F%3E%3Ccircle%20cx%3D'8'%20cy%3D'16'%20r%3D'1'%2F%3E%3Ccircle%20cx%3D'16'%20cy%3D'16'%20r%3D'1'%2F%3E%3C%2Fsvg%3E\")}.pfs-footer__icon--vote{--pfs-footer-glyph:url(\"data:image/svg+xml,%3Csvg%20xmlns%3D'http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg'%20viewBox%3D'0%200%2024%2024'%20fill%3D'none'%20stroke%3D'black'%20stroke-width%3D'2'%20stroke-linecap%3D'round'%20stroke-linejoin%3D'round'%3E%3Cpath%20d%3D'M12%204%2021%2019H3z'%2F%3E%3C%2Fsvg%3E\")}.pfs-footer__copy{margin:0;color:var(--pfs-footer-muted)}.pfs-footer__copy a{color:inherit}",
+  "link": "<a href=\"{{href}}\"{{#rel}} rel=\"{{rel}}\"{{/rel}}>{{label}}</a>",
+  "footer": "<footer class=\"pfs-footer\" data-pfs-footer=\"{{version}}\">{{#css}}<style>{{{css}}}</style>{{/css}}<div class=\"pfs-footer__inner\">{{#links}}<nav class=\"pfs-footer__links\" aria-label=\"Footer\">{{{links}}}</nav>{{/links}}<nav class=\"webring pfs-footer__ring\" aria-label=\"{{ring_name}} webring\"><a href=\"{{previous}}\" rel=\"prev\" title=\"Previous site\">&lt;&lt;</a><a href=\"{{ring}}\">{{ring_name}}</a><a href=\"{{next}}\" rel=\"next\" title=\"Next site\">&gt;&gt;</a><a href=\"{{random}}\" title=\"Random site\" aria-label=\"Random site\"><span class=\"pfs-footer__icon pfs-footer__icon--random\" aria-hidden=\"true\"></span></a><a href=\"{{ring}}/vote\" referrerpolicy=\"origin\" title=\"Vote for this site\" aria-label=\"Vote for this site\"><span class=\"pfs-footer__icon pfs-footer__icon--vote\" aria-hidden=\"true\"></span></a></nav><p class=\"pfs-footer__copy\">&copy; {{years}} <a href=\"{{owner_url}}\">{{owner_name}}</a>{{#tagline}} &middot; {{tagline}}{{/tagline}}</p></div></footer>",
+  "houseLinks": []
+}