From ffa5772791c4ee769b14783bb00c02e7138ec1c8 Mon Sep 17 00:00:00 2001
From: Warren <warreng@ecropolis.com>
Date: Sat, 26 Sep 2026 11:27:43 -0500
Subject: [PATCH 1/3] video-gallery: posters and play buttons in a grid,
 nothing from YouTube until a click

A grid of YouTube, Vimeo or self-hosted videos behind the site's own posters,
with optional category chips (<button aria-pressed>, "All" first, a polite
count). mode="lightbox" plays in one <dialog> per gallery (Escape, backdrop,
focus return, scroll lock, autoplay on open); mode="inline" turns the tile
into the player and puts the previous one back. Without JavaScript each tile
links to the video's own page and every video is listed.

The URL parser is a verbatim copy of video-player's block; the new
scripts/check-media-and-links.mjs fails if the copies drift, greps every built
page for anything fetched from Google, YouTube or Vimeo at load, pins the
no-JS render and the ARIA contract, and runs each check against broken copies
of its input (15 mutations) so a check that cannot fail is caught.

Search: "video gallery" 590/mo, difficulty 20 (SE Ranking US, 2026-09-26).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 package.json                                 |   2 +-
 scripts/check-media-and-links.mjs            | 274 +++++++
 src/components/demos/VideoGalleryDemo.astro  |  97 +++
 src/components/demos/index.ts                |   2 +
 src/data/catalog.ts                          |  78 ++
 src/library/video-gallery/VideoGallery.astro | 771 +++++++++++++++++++
 6 files changed, 1223 insertions(+), 1 deletion(-)
 create mode 100644 scripts/check-media-and-links.mjs
 create mode 100644 src/components/demos/VideoGalleryDemo.astro
 create mode 100644 src/library/video-gallery/VideoGallery.astro

diff --git a/package.json b/package.json
index f1514df..115a361 100644
--- a/package.json
+++ b/package.json
@@ -12,7 +12,7 @@
     "preview": "astro preview",
     "astro": "astro",
     "build:icon-data": "node scripts/build-icon-data.mjs",
-    "check": "node --experimental-strip-types --disable-warning=ExperimentalWarning scripts/check-catalog.mjs && node --disable-warning=ExperimentalWarning scripts/check-business-hours.mjs && node scripts/check-news-ticker.mjs && node --disable-warning=ExperimentalWarning scripts/check-flip-box.mjs && node scripts/check-social-grid.mjs && node --experimental-strip-types --disable-warning=ExperimentalWarning scripts/check-four.mjs && node --disable-warning=ExperimentalWarning scripts/check-video-player.mjs && node scripts/check-cookie-consent.mjs && node --experimental-strip-types --disable-warning=ExperimentalWarning scripts/check-icon.mjs && node --experimental-strip-types --disable-warning=ExperimentalWarning scripts/check-animated-background.mjs && node --disable-warning=ExperimentalWarning scripts/check-modal-and-bar.mjs"
+    "check": "node --experimental-strip-types --disable-warning=ExperimentalWarning scripts/check-catalog.mjs && node --disable-warning=ExperimentalWarning scripts/check-business-hours.mjs && node scripts/check-news-ticker.mjs && node --disable-warning=ExperimentalWarning scripts/check-flip-box.mjs && node scripts/check-social-grid.mjs && node --experimental-strip-types --disable-warning=ExperimentalWarning scripts/check-four.mjs && node --disable-warning=ExperimentalWarning scripts/check-video-player.mjs && node scripts/check-cookie-consent.mjs && node --experimental-strip-types --disable-warning=ExperimentalWarning scripts/check-icon.mjs && node --experimental-strip-types --disable-warning=ExperimentalWarning scripts/check-animated-background.mjs && node --disable-warning=ExperimentalWarning scripts/check-modal-and-bar.mjs && node --disable-warning=ExperimentalWarning scripts/check-media-and-links.mjs"
   },
   "dependencies": {
     "astro": "^7.2.1"
diff --git a/scripts/check-media-and-links.mjs b/scripts/check-media-and-links.mjs
new file mode 100644
index 0000000..49e855e
--- /dev/null
+++ b/scripts/check-media-and-links.mjs
@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+/**
+ * npm run check (after check-catalog.mjs, which builds dist/) — pins video-gallery, map and
+ * link-effects on the built pages, i.e. what a visitor without JavaScript gets.
+ *
+ * 0. Every built page: nothing is fetched from Google, YouTube or Vimeo at load. No iframe,
+ *    script, link, img, source, video poster, embed or object points at google.com,
+ *    googleapis.com, gstatic.com, youtube(-nocookie).com, youtu.be, ytimg.com, vimeo.com or
+ *    vimeocdn.com. <noscript> is NOT exempt: its markup loads for a visitor without JavaScript.
+ *    Links (<a href>) fetch nothing and are allowed; they are the no-JavaScript render.
+ *
+ * video-gallery
+ * 1. Its URL parser is byte-for-byte video-player's (the two `*-parse` blocks); a handful of
+ *    golden cases run against the copy.
+ * 2. Each gallery on the demo page and the index: every tile is a link to the video's own
+ *    page named "Watch “<title>”…", plus a hidden <button type="button"> named
+ *    "Play: <title>" whose data matches the tile, with a youtube-nocookie / vimeo dnt=1 embed
+ *    or file sources with a captions track that exists; no <iframe> or <video> at load; chips
+ *    (if any) are a named, hidden group of <button aria-pressed>, "All" first and pressed, with
+ *    a polite live region; a lightbox gallery has one closed, named <dialog> with a named close
+ *    button, an inline one none; the one-line mount script comes straight after the gallery;
+ *    the runtime is on the page once.
+ * 3. Motion (animation, transition, scale on hover) sits only inside
+ *    `@media (prefers-reduced-motion: no-preference)`.
+ *
+ * Mutation tests: each element's checks are also run against deliberately broken copies of its
+ * input (an iframe injected, a name removed, a colour darkened, …). A mutation the checks do
+ * not catch fails the run: a check that cannot fail is not a check.
+ *
+ * Exits 1 with one line per failure.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { stripTypeScriptTypes } from 'node:module';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+const failures = [];
+const fail = (msg) => failures.push(msg);
+const finish = (stage) => {
+  if (!failures.length) return;
+  console.error(`check-media-and-links failed (${stage}):`);
+  for (const f of failures) console.error(`  - ${f}`);
+  process.exit(1);
+};
+const attr = (tag, name) => {
+  const m = tag.match(new RegExp(`\\s${name}(?:="([^"]*)"|(?=[\\s>/]))`));
+  return m ? (m[1] ?? '') : undefined;
+};
+const decode = (s) => s?.replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&');
+const text = (html) => decode(html.replace(/<[^>]+>/g, '')).replace(/\s+/g, ' ').trim();
+const src = (rel) => readFileSync(join(root, rel), 'utf8');
+const built = (rel) => {
+  const path = join(root, rel);
+  if (!existsSync(path)) {
+    fail(`${rel} is missing; run astro build (check-catalog.mjs does).`);
+    return '';
+  }
+  return readFileSync(path, 'utf8');
+};
+/** Runs `check(input, fail)` and returns what it reported. */
+const run = (check, input) => {
+  const got = [];
+  check(input, (m) => got.push(m));
+  return got;
+};
+let mutations = 0;
+/** Each mutation must make `check` report at least one failure. */
+const mutate = (label, check, input, change) => {
+  mutations++;
+  const broken = change(structuredClone(input));
+  if (JSON.stringify(broken) === JSON.stringify(input)) fail(`mutation "${label}" changed nothing; its pattern no longer matches the input.`);
+  else if (!run(check, broken).length) fail(`mutation "${label}" was not caught: the check passes a broken input.`);
+};
+/** `css` with every `@media (prefers-reduced-motion: no-preference) { … }` block removed. */
+const outsideNoPreference = (css) => {
+  let out = '';
+  let i = 0;
+  const open = /@media\s*\(prefers-reduced-motion:\s*no-preference\)\s*\{/g;
+  for (let m; (m = open.exec(css)); ) {
+    out += css.slice(i, m.index);
+    let depth = 1;
+    let j = open.lastIndex;
+    for (; j < css.length && depth; j++) depth += css[j] === '{' ? 1 : css[j] === '}' ? -1 : 0;
+    i = open.lastIndex = j;
+  }
+  return out + css.slice(i);
+};
+const styleOf = (component) => (component.match(/<style>([\s\S]*?)<\/style>/) || [])[1] ?? '';
+
+// ------------------------------------------------- 0. no third party at load
+const THIRD = /(?:^|\/\/|\.)(?:google\.com|googleapis\.com|gstatic\.com|youtube\.com|youtube-nocookie\.com|youtu\.be|ytimg\.com|vimeo\.com|vimeocdn\.com)(?=[/:?#]|$)/i;
+const checkNoThirdParty = ({ rel, html }, fail) => {
+  for (const t of html.match(/<(?:iframe|frame|script|link|img|source|video|audio|embed|object|track)\b[^>]*>/gi) || []) {
+    const refs = ['src', 'href', 'srcset', 'data', 'poster'].map((n) => decode(attr(t, n))).filter(Boolean);
+    const urls = refs.flatMap((r) => r.split(',').map((u) => u.trim().split(/\s+/)[0]));
+    if (urls.some((u) => THIRD.test(u))) fail(`${rel}: fetches from Google, YouTube or Vimeo at load: ${t.slice(0, 160)}`);
+  }
+  if (/url\(\s*['"]?https?:\/\/[^)]*(?:google|gstatic|youtube|ytimg|vimeo)/i.test(html)) fail(`${rel}: a CSS url() from Google, YouTube or Vimeo.`);
+};
+const pages = [];
+const walk = (dir) => {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) walk(p);
+    else if (e.name.endsWith('.html')) pages.push(relative(root, p));
+  }
+};
+if (existsSync(join(root, 'dist'))) walk(join(root, 'dist'));
+if (!pages.length) fail('dist/ has no HTML; run astro build (check-catalog.mjs does).');
+for (const rel of pages) for (const m of run(checkNoThirdParty, { rel, html: built(rel) })) fail(m);
+{
+  const input = { rel: 'dist/video-gallery/index.html', html: built('dist/video-gallery/index.html') };
+  mutate('a YouTube iframe at load', checkNoThirdParty, input, (x) => ({ ...x, html: x.html.replace('</body>', '<iframe src="https://www.youtube-nocookie.com/embed/aqz-KE-bpKQ"></iframe></body>') }));
+  mutate('a Google Maps iframe inside <noscript>', checkNoThirdParty, input, (x) => ({ ...x, html: x.html.replace('</body>', '<noscript><iframe src="https://www.google.com/maps?q=x&amp;output=embed"></iframe></noscript></body>') }));
+  mutate('a YouTube thumbnail', checkNoThirdParty, input, (x) => ({ ...x, html: x.html.replace('</body>', '<img src="https://i.ytimg.com/vi/x/hqdefault.jpg" alt=""></body>') }));
+  mutate('a preconnect to Vimeo', checkNoThirdParty, input, (x) => ({ ...x, html: x.html.replace('</head>', '<link rel="preconnect" href="https://player.vimeo.com"></head>') }));
+}
+finish('third parties at load');
+
+// ------------------------------------------------------------ video-gallery
+const VG = 'src/library/video-gallery/VideoGallery.astro';
+const block = (s, name) => (s.match(new RegExp(`\\/\\/ <${name}>\\n([\\s\\S]*?)\\/\\/ <\\/${name}>`)) || [])[1];
+const checkParserCopy = ({ gallery, player }, fail) => {
+  const g = block(gallery, 'video-gallery-parse');
+  const p = block(player, 'video-player-parse');
+  if (!g) fail(`${VG} has no \`// <video-gallery-parse>\` … \`// </video-gallery-parse>\` block.`);
+  else if (!p) fail('VideoPlayer.astro has no `// <video-player-parse>` block to compare with.');
+  else if (g !== p) fail(`${VG}: its parser is no longer a copy of video-player's. Change both, identically, or neither.`);
+};
+const vgSources = { gallery: src(VG), player: src('src/library/video-player/VideoPlayer.astro') };
+for (const m of run(checkParserCopy, vgSources)) fail(m);
+mutate('the parser copy drifts', checkParserCopy, vgSources, (x) => ({ ...x, gallery: x.gallery.replace("'youtube.com' || host", "'youtube.com' ||host") }));
+finish('video-gallery parser copy');
+
+const parse = block(vgSources.gallery, 'video-gallery-parse');
+const { parseVideoSrc, embedUrl, watchUrl } = await import(
+  `data:text/javascript;base64,${Buffer.from(`${stripTypeScriptTypes(parse, { mode: 'strip' })}\nexport { parseVideoSrc, embedUrl, watchUrl };`).toString('base64')}`
+);
+const cases = [
+  ['https://youtu.be/eRsGyueVLvQ', { kind: 'youtube', id: 'eRsGyueVLvQ' }],
+  ['https://vimeo.com/1084537', { kind: 'vimeo', id: '1084537' }],
+  ['/demo/drift.mp4', { kind: 'file', sources: [{ src: '/demo/drift.mp4', type: 'video/mp4' }] }],
+  ['https://example.com/watch?v=aqz-KE-bpKQ', null],
+];
+for (const [s, want] of cases) if (JSON.stringify(parseVideoSrc(s)) !== JSON.stringify(want)) fail(`parseVideoSrc(${JSON.stringify(s)}) = ${JSON.stringify(parseVideoSrc(s))}, expected ${JSON.stringify(want)}.`);
+if (embedUrl({ kind: 'vimeo', id: '1084537' }) !== 'https://player.vimeo.com/video/1084537?dnt=1&autoplay=1') fail('embedUrl for Vimeo lost dnt=1 or autoplay.');
+if (watchUrl({ kind: 'youtube', id: 'eRsGyueVLvQ' }) !== 'https://www.youtube.com/watch?v=eRsGyueVLvQ') fail('watchUrl for YouTube changed.');
+finish('video-gallery parser');
+
+const MOUNT_VG = '<script>window.__superheroVideoGallery.mount(document.currentScript.previousElementSibling);</script>';
+const checkGalleryPage = ({ rel, html, demo }, fail) => {
+  const roots = [...html.matchAll(/<div\b[^>]*\sdata-vg="(lightbox|inline)"[^>]*>/g)];
+  if (demo && roots.length !== 2) fail(`${rel}: expected the demo's 2 galleries, found ${roots.length}.`);
+  const kinds = new Set();
+  let filtered = 0;
+  roots.forEach((r, gi) => {
+    const mode = r[1];
+    const where = `${rel}, gallery ${gi + 1} (${mode})`;
+    const end = html.indexOf(MOUNT_VG, r.index);
+    if (end < 0) {
+      fail(`${where}: no mount script after it.`);
+      return;
+    }
+    const chunk = html.slice(r.index, end);
+    if (!/<\/div>\s*$/.test(chunk) || (roots[gi + 1] && roots[gi + 1].index < end)) fail(`${where}: the mount script must come straight after the gallery, or links turn into buttons after the first paint.`);
+    if (/<iframe\b/i.test(chunk)) fail(`${where}: an <iframe> at load; the player is created on a click.`);
+    if (/<video\b/i.test(chunk)) fail(`${where}: a <video> at load; the player is created on a click.`);
+
+    const items = chunk.split(/(?=<li\b[^>]*\sdata-vg-item)/).slice(1);
+    if (!items.length) fail(`${where}: no tiles.`);
+    items.forEach((li, i) => {
+      const titleEl = li.match(/<(h2|h3|h4|p)\b[^>]*class="vg__title"[^>]*>([\s\S]*?)<\/\1>/);
+      const title = titleEl ? text(titleEl[2]) : '';
+      const w = `${where}, tile ${i + 1} ("${title}")`;
+      if (!title) fail(`${w}: no title under the tile.`);
+      const link = li.match(/<a\b[^>]*\sdata-vg-link[^>]*>([\s\S]*?)<\/a>/);
+      if (!link) fail(`${w}: no link; without JavaScript the tile must link to the video.`);
+      else {
+        const href = decode(attr(link[0], 'href')) || '';
+        if (!href) fail(`${w}: the link has no href.`);
+        if (!text(link[1]).startsWith(`Watch “${title}”`)) fail(`${w}: the link is named "${text(link[1])}", expected "Watch “${title}”…".`);
+      }
+      const btn = li.match(/<button\b[^>]*\sdata-vg-play=[^>]*>/);
+      if (!btn) {
+        fail(`${w}: no play button.`);
+        return;
+      }
+      if (attr(btn[0], 'type') !== 'button') fail(`${w}: the play button needs type="button".`);
+      if (attr(btn[0], 'hidden') === undefined) fail(`${w}: the play button must be hidden until the script can make it work.`);
+      if (decode(attr(btn[0], 'aria-label')) !== `Play: ${title}`) fail(`${w}: the play button is named "${decode(attr(btn[0], 'aria-label'))}", expected "Play: ${title}".`);
+      if (mode === 'lightbox' && attr(btn[0], 'aria-haspopup') !== 'dialog') fail(`${w}: a lightbox button needs aria-haspopup="dialog".`);
+      let d = {};
+      try {
+        d = JSON.parse(decode(attr(btn[0], 'data-vg-play')));
+      } catch {
+        fail(`${w}: data-vg-play is not JSON.`);
+      }
+      kinds.add(d.k);
+      if (d.t !== title) fail(`${w}: the player would be titled "${d.t}", not "${title}".`);
+      if (d.k === 'youtube' && !String(d.e).startsWith('https://www.youtube-nocookie.com/embed/')) fail(`${w}: embed ${d.e} is not youtube-nocookie.com.`);
+      if (d.k === 'vimeo' && !(String(d.e).startsWith('https://player.vimeo.com/video/') && /[?&]dnt=1/.test(d.e))) fail(`${w}: embed ${d.e} is not player.vimeo.com with dnt=1.`);
+      if (d.k === 'file') {
+        if (!d.s?.length) fail(`${w}: a file with no sources.`);
+        const cap = (d.tr || []).find((t) => t.kind === 'captions');
+        if (!cap) fail(`${w}: a self-hosted video without a captions track.`);
+        else if (!cap.src.startsWith('/demo/') || !existsSync(join(root, 'public', cap.src))) fail(`${w}: captions track ${cap.src} is not in public/demo/.`);
+      }
+      const img = li.match(/<img\b[^>]*class="vg__poster"[^>]*>/);
+      if (img && attr(img[0], 'alt') !== '') fail(`${w}: the poster sits inside a named control and repeats the title; it must be alt="".`);
+    });
+
+    const bar = chunk.match(/<div\b[^>]*\sdata-vg-filters[^>]*>([\s\S]*?)<\/div>/);
+    if (bar) {
+      filtered++;
+      if (attr(bar[0], 'role') !== 'group' || !attr(bar[0], 'aria-label')) fail(`${where}: the chips must be a role="group" with an aria-label.`);
+      if (attr(bar[0], 'hidden') === undefined) fail(`${where}: the chips must be hidden until the script can make them work.`);
+      const chips = [...bar[1].matchAll(/<button\b[^>]*>/g)].map((c) => c[0]);
+      if (chips.length < 3) fail(`${where}: fewer than "All" and two categories.`);
+      chips.forEach((c, i) => {
+        if (attr(c, 'type') !== 'button') fail(`${where}, chip ${i + 1}: needs type="button".`);
+        const pressed = attr(c, 'aria-pressed');
+        if (pressed !== (i === 0 ? 'true' : 'false')) fail(`${where}, chip ${i + 1}: aria-pressed="${pressed}", expected "${i === 0}" ("All" first and pressed).`);
+      });
+      if (chips[0] && attr(chips[0], 'data-vg-filter') !== '') fail(`${where}: the first chip must be "All" (data-vg-filter="").`);
+      if (!/<p\b[^>]*aria-live="polite"[^>]*data-vg-status/.test(chunk)) fail(`${where}: no polite live region to say how many are shown.`);
+    }
+
+    const dialogs = [...chunk.matchAll(/<dialog\b[^>]*>/g)].map((m) => m[0]);
+    if (mode === 'lightbox') {
+      if (dialogs.length !== 1) fail(`${where}: a lightbox gallery needs exactly one <dialog>, found ${dialogs.length}.`);
+      for (const dl of dialogs) {
+        if (attr(dl, 'open') !== undefined) fail(`${where}: the <dialog> is rendered open.`);
+        if (!attr(dl, 'aria-label')) fail(`${where}: the <dialog> has no name.`);
+      }
+      const close = chunk.match(/<button\b[^>]*\sdata-vg-close[^>]*>/);
+      if (!close || attr(close[0], 'type') !== 'button' || !attr(close[0], 'aria-label')) fail(`${where}: the lightbox needs a named close <button type="button">.`);
+    } else if (dialogs.length) fail(`${where}: an inline gallery has a <dialog>.`);
+  });
+  if (demo) {
+    for (const k of ['youtube', 'vimeo', 'file']) if (!kinds.has(k)) fail(`${rel}: the demo needs a ${k} tile.`);
+    if (!filtered) fail(`${rel}: the demo needs a gallery with filter chips.`);
+  }
+  const runtimes = (html.match(/window\.__superheroVideoGallery = \{/g) || []).length;
+  if (roots.length && runtimes !== 1) fail(`${rel}: the gallery runtime is on the page ${runtimes} times; it must be once.`);
+};
+const vgPages = [
+  { rel: 'dist/video-gallery/index.html', html: built('dist/video-gallery/index.html'), demo: true },
+  { rel: 'dist/index.html', html: built('dist/index.html'), demo: false },
+];
+for (const p of vgPages) for (const m of run(checkGalleryPage, p)) fail(m);
+const checkGalleryMotion = (component, fail) => {
+  const rest = outsideNoPreference(styleOf(component));
+  if (/\b(?:animation|transition)\s*:/.test(rest)) fail(`${VG}: an animation or transition outside @media (prefers-reduced-motion: no-preference).`);
+  if (/(?<![-\w])scale\s*:/.test(rest)) fail(`${VG}: the hover growth must sit inside @media (prefers-reduced-motion: no-preference).`);
+};
+for (const m of run(checkGalleryMotion, vgSources.gallery)) fail(m);
+{
+  const demo = vgPages[0];
+  const re = (a, b) => (x) => ({ ...x, html: x.html.replace(a, b) });
+  mutate('a play button loses its name', checkGalleryPage, demo, re(/aria-label="Play: Sintel"/, 'aria-label="Play"'));
+  mutate('a play button shows without JavaScript', checkGalleryPage, demo, re(/(<button class="vg__hit[^"]*" type="button") hidden/, '$1'));
+  mutate('a tile loses its no-JavaScript link', checkGalleryPage, demo, re(/<a class="vg__hit"[^>]*data-vg-link[^>]*>[\s\S]*?<\/a>/, ''));
+  mutate('a chip loses aria-pressed', checkGalleryPage, demo, re(/(data-vg-filter="loops"[^>]*?) ?aria-pressed="false"|aria-pressed="false"( [^>]*data-vg-filter="loops")/, '$1$2'));
+  mutate('"All" is not pressed', checkGalleryPage, demo, re('aria-pressed="true" data-vg-filter=""', 'aria-pressed="false" data-vg-filter=""'));
+  mutate('the dialog renders open', checkGalleryPage, demo, re('<dialog class="vg__dialog"', '<dialog open class="vg__dialog"'));
+  mutate('a YouTube embed off nocookie', checkGalleryPage, demo, re('youtube-nocookie.com/embed/', 'youtube.com/embed/'));
+  mutate('the mount script moves away', checkGalleryPage, demo, re(MOUNT_VG, '<p></p>' + MOUNT_VG));
+  mutate('the runtime twice', checkGalleryPage, demo, re('</body>', '<script>window.__superheroVideoGallery = {};</script></body>'));
+  mutate('a fade outside reduced motion', checkGalleryMotion, vgSources.gallery, (s) => s.replace('.vg__item {\n    min-width: 0;', '.vg__item {\n    animation: vg-in 1s;\n    min-width: 0;'));
+}
+finish('video-gallery');
+
+console.log(`check-media-and-links ok: ${pages.length} built pages load nothing from Google, YouTube or Vimeo; video-gallery parser is video-player's, its no-JS render and ARIA hold on 2 pages; ${mutations} mutations caught.`);
diff --git a/src/components/demos/VideoGalleryDemo.astro b/src/components/demos/VideoGalleryDemo.astro
new file mode 100644
index 0000000..792b592
--- /dev/null
+++ b/src/components/demos/VideoGalleryDemo.astro
@@ -0,0 +1,97 @@
+---
+/**
+ * Demo for `video-gallery`. The website renders this too (see README, "Consumed by
+ * superherotech.ai"), so assets go through `asset()` and every host token has a fallback.
+ *
+ * The same public videos video-player's demo uses and names: the Blender Foundation's open
+ * films Big Buck Bunny (2008) and Sintel (2010), CC BY 3.0 (the credit is in each caption, as
+ * the licence asks), on Blender's YouTube channel, plus Big Buck Bunny's copy on Vimeo to show
+ * a Vimeo tile, and the neutral three-second "drift" loop served from public/demo/ with its
+ * captions file. The posters are our own neutral SVGs, not frames from the films. Nothing is
+ * fetched from YouTube or Vimeo until a tile is pressed.
+ */
+import VideoGallery from '../../library/video-gallery/VideoGallery.astro';
+interface Props {
+  /** Where public/demo/ is served. The gallery uses /demo/; the website passes /elements-demo/. */
+  assetBase?: string;
+}
+const { assetBase = '/demo/' } = Astro.props;
+const asset = (name: string) => assetBase + name;
+const drift = {
+  url: [
+    { src: asset('drift.webm'), type: 'video/webm' },
+    { src: asset('drift.mp4'), type: 'video/mp4' },
+  ],
+  title: 'Drift, a three-second loop',
+  poster: asset('drift-poster.jpg'),
+  tracks: [{ src: asset('drift.vtt'), srclang: 'en', label: 'English' }],
+};
+---
+<div class="demo-vg">
+  <p class="demo-vg__label">Lightbox, filtered by category, with counts</p>
+  <VideoGallery
+    columns={2}
+    counts
+    videos={[
+      {
+        url: 'https://www.youtube.com/watch?v=aqz-KE-bpKQ',
+        title: 'Big Buck Bunny',
+        poster: asset('film-poster.svg'),
+        caption: '© Blender Foundation, peach.blender.org, CC BY 3.0. On YouTube.',
+        category: 'Open films',
+      },
+      {
+        url: 'https://youtu.be/eRsGyueVLvQ',
+        title: 'Sintel',
+        poster: asset('film-poster-dusk.svg'),
+        caption: '© Blender Foundation, durian.blender.org, CC BY 3.0. On YouTube.',
+        category: 'Open films',
+      },
+      {
+        url: 'https://vimeo.com/1084537',
+        title: 'Big Buck Bunny, on Vimeo',
+        poster: asset('hills.svg'),
+        caption: 'The same film, CC BY 3.0, played from Vimeo with Do Not Track on.',
+        category: ['Open films', 'Vimeo'],
+      },
+      { ...drift, caption: 'Self-hosted, with a captions track.', category: 'Loops' },
+    ]}
+  />
+
+  <p class="demo-vg__label">Inline: the tile becomes the player</p>
+  <VideoGallery
+    mode="inline"
+    columns={2}
+    titleTag="p"
+    videos={[
+      {
+        url: 'aqz-KE-bpKQ',
+        title: 'Big Buck Bunny, without a poster',
+        caption: 'No poster given: a neutral panel, never YouTube’s thumbnail.',
+      },
+      { ...drift, caption: 'Pressing the other tile puts this one back.' },
+    ]}
+  />
+</div>
+<style>
+  .demo-vg {
+    --vg-radius: var(--radius, 14px);
+    --vg-play-bg: var(--purple, #5933d8);
+    --vg-play-fg: var(--white, #fff);
+    --vg-bg: var(--navy, #1e283c);
+    --vg-focus: var(--purple, #5933d8);
+    --vg-chip-on-bg: var(--purple, #5933d8);
+    --vg-chip-fg: var(--ink, #1e283c);
+    --vg-chip-border: var(--line, #c9cedb);
+    --vg-title: var(--ink, #1e283c);
+    display: grid;
+    gap: 0.75rem;
+  }
+  .demo-vg__label {
+    margin: 0.5rem 0 0;
+    font-weight: 700;
+  }
+  .demo-vg__label:not(:first-child) {
+    margin-top: 2rem;
+  }
+</style>
diff --git a/src/components/demos/index.ts b/src/components/demos/index.ts
index bfbd3f8..c194713 100644
--- a/src/components/demos/index.ts
+++ b/src/components/demos/index.ts
@@ -30,6 +30,7 @@ import IconDemo from './IconDemo.astro';
 import AnimatedBackgroundDemo from './AnimatedBackgroundDemo.astro';
 import ModalDemo from './ModalDemo.astro';
 import AnnouncementBarDemo from './AnnouncementBarDemo.astro';
+import VideoGalleryDemo from './VideoGalleryDemo.astro';
 
 // Astro components have no exported public type; this is the shape both callers need.
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -58,4 +59,5 @@ export const demos: Record<string, AstroComponent> = {
   'animated-background': AnimatedBackgroundDemo,
   modal: ModalDemo,
   'announcement-bar': AnnouncementBarDemo,
+  'video-gallery': VideoGalleryDemo,
 };
diff --git a/src/data/catalog.ts b/src/data/catalog.ts
index 0df4e17..e26cab4 100644
--- a/src/data/catalog.ts
+++ b/src/data/catalog.ts
@@ -1428,6 +1428,84 @@ import { analytics } from '../data/site';
     file: 'src/library/announcement-bar/AnnouncementBar.astro',
     added: '2026-09-24',
   },
+  {
+    id: 'video-gallery',
+    name: 'Video gallery',
+    aka: ['UABB Video Gallery', 'PowerPack Video Gallery', 'Elementor Video Playlist', 'YouTube gallery', 'Vimeo gallery', 'video grid', 'filterable video gallery'],
+    summary:
+      'A grid of YouTube, Vimeo or self-hosted videos, each behind your own poster and a play button, with optional category filter chips. A click plays the video in one lightbox dialog or in the tile itself. Nothing is requested from YouTube or Vimeo until a tile is pressed.',
+    pitch: 'All your videos on one page, sorted by topic, with your own thumbnails, and nothing loads from YouTube until someone picks one.',
+    // SE Ranking US, 2026-09-26: video gallery 590/mo, difficulty 20; youtube gallery 210/8;
+    // video gallery wordpress 50/28; video gallery website 40/13 (the round-3 note's first
+    // guess, which "video gallery" beats on volume at a similar difficulty). video grid 390/34
+    // is a stock-footage and editing query, left unclaimed.
+    search: { query: 'video gallery', alsoRanks: ['youtube gallery', 'video gallery website', 'video gallery wordpress'] },
+    replaces: ['UABB / PowerPack “Video Gallery” modules (Beaver Builder)', 'Elementor Pro Video Playlist', 'YouTube gallery plugins', 'a page of pasted YouTube iframes'],
+    goodFor: 'A page of several videos: testimonials, a how-to library, event recordings, a portfolio of films. Categories when there are enough to be worth sorting.',
+    notFor:
+      'One video on its own (that is video-player), an ambient loop behind a hero (video-background), and a whole channel kept in sync by itself: the list is written into the page, so a new upload means an edit. Galleries of photos are not this either.',
+    props: [
+      { name: 'videos', type: '{ url, title, caption?, poster?, category?, tracks? }[]', note: 'Required. `url` takes what video-player’s `src` takes: a YouTube URL or id (watch, youtu.be, shorts, embed), a Vimeo URL or id, a .mp4/.webm URL, or [{ src, type }]. Anything else fails the build. `title` is required. `category` is one string or several.' },
+      { name: 'mode', type: "'lightbox' | 'inline'", default: "'lightbox'", note: 'Lightbox plays in one <dialog> over the page. Inline replaces the tile’s poster with the player; pressing another tile puts it back.' },
+      { name: 'columns', type: 'number (1–6)', default: '3', note: 'The most tiles per row. Fewer when a tile would be narrower than --vg-min; one on a phone. Set --vg-template instead for the host’s own grid.' },
+      { name: 'filter', type: 'boolean', default: 'two or more categories', note: 'Category chips above the grid, “All” first.' },
+      { name: 'counts', type: 'boolean', default: 'false', note: 'Show how many videos each chip holds.' },
+      { name: 'allLabel / filterLabel', type: 'string', default: '“All” / “Filter videos”', note: 'The first chip, and the accessible name of the chip group.' },
+      { name: 'aspect', type: 'number | string', default: '16/9', note: 'Frame ratio of every tile and of the lightbox: 1.7778, "16/9", "4 / 3".' },
+      { name: 'autoplay', type: 'boolean', default: 'true', note: 'Start playing on the click. False shows the player and waits for a second press.' },
+      { name: 'titleTag', type: "'h2' | 'h3' | 'h4' | 'p'", default: "'h3'", note: 'Element for each tile’s title, to fit the page’s heading outline.' },
+      { name: 'playLabel / closeLabel', type: 'string', default: '“Play” / “Close video”', note: 'Words, for a non-English site. playLabel prefixes each title in the button’s name.' },
+      { name: 'playIcon', type: 'string', note: 'Inline SVG markup for the play icon. Use currentColor and 1em.' },
+      { name: 'class', type: 'string', note: 'Class on the wrapper, for the host to theme it.' },
+    ],
+    theming: [
+      { name: '--vg-min', fallback: '14rem', note: 'No tile narrower than this; below it the row drops a column.' },
+      { name: '--vg-gap', fallback: '1.25rem', note: 'Gap between tiles.' },
+      { name: '--vg-template', fallback: '(unset)', note: 'The whole grid-template-columns, when the host wants its own grid: `repeat(4, 1fr)`.' },
+      { name: '--vg-radius', fallback: '0.5rem', note: 'Corner radius of each frame.' },
+      { name: '--vg-bg', fallback: '#000', note: 'Frame colour behind the poster and the player.' },
+      { name: '--vg-panel', fallback: 'linear-gradient(135deg, #2c3656, #1e283c)', note: 'A tile without a poster.' },
+      { name: '--vg-overlay', fallback: 'rgb(0 0 0 / 0.12)', note: 'Tint over the poster.' },
+      { name: '--vg-play-bg', fallback: 'rgb(0 0 0 / 0.7)', note: 'Play button circle. Keep 3:1 against the posters.' },
+      { name: '--vg-play-fg', fallback: '#fff', note: 'Play icon.' },
+      { name: '--vg-play-size', fallback: '3.5rem', note: 'Diameter of the circle.' },
+      { name: '--vg-focus', fallback: '#5933d8', note: 'Focus ring on tiles and chips.' },
+      { name: '--vg-title', fallback: 'inherit', note: 'Tile title colour.' },
+      { name: '--vg-caption', fallback: 'inherit', note: 'Caption colour.' },
+      { name: '--vg-chip-bg', fallback: '#fff', note: 'Chip fill.' },
+      { name: '--vg-chip-fg', fallback: '#1e283c', note: 'Chip text (14.75:1 on the fallback fill).' },
+      { name: '--vg-chip-border', fallback: '#c9cedb', note: 'Chip outline.' },
+      { name: '--vg-chip-on-bg', fallback: '#1e283c', note: 'The pressed chip’s fill.' },
+      { name: '--vg-chip-on-fg', fallback: '#fff', note: 'The pressed chip’s text.' },
+      { name: '--vg-backdrop', fallback: 'rgb(0 0 0 / 0.88)', note: 'Lightbox backdrop.' },
+      { name: '--vg-close-bg', fallback: 'rgb(255 255 255 / 0.15)', note: 'Lightbox close button fill.' },
+      { name: '--vg-close-fg', fallback: '#fff', note: 'Lightbox close icon and title.' },
+    ],
+    a11y: [
+      'Each tile’s play control is a real <button> named “Play: <title>”, over the whole poster, with a visible focus ring. The title is also printed under the tile as a heading (titleTag).',
+      'Filter chips are a labelled group of <button aria-pressed>, “All” first and pressed. Choosing one hides the other tiles and a polite live region says how many are shown (“Open films: 3 videos.”).',
+      'Lightbox: one native modal <dialog>, named by the video’s title: focus trapped, Escape and a backdrop click close it, the close button is labelled. On open the video starts and focus goes to the close button, because a YouTube or Vimeo iframe keeps every key, Escape included; Tab moves on into the player. Closing empties the dialog so the sound stops, returns focus to the tile and releases the scroll lock.',
+      'Inline: focus moves into the player (the titled iframe, or the <video>). One tile plays at a time.',
+      'Self-hosted files keep the browser’s native controls with a captions menu. A captions track is expected (WCAG 1.2.2); the build warns without one.',
+      'prefers-reduced-motion: tiles shown by a filter appear at once instead of fading in, and the play button does not grow on hover. Nothing plays until asked.',
+      'Without JavaScript every tile is a link to the video’s own page (“Watch “<title>” on YouTube”), or to the file, and every video is listed: the chips are not shown.',
+    ],
+    usage: `<VideoGallery
+  videos={[
+    { url: 'https://www.youtube.com/watch?v=VIDEO_ID', title: 'Planting garlic', poster: '/images/garlic.webp', category: 'How-to' },
+    { url: 'https://vimeo.com/123456789', title: 'Spring open day', poster: '/images/open-day.webp', category: 'Events' },
+    { url: '/video/tour.mp4', title: 'A tour of the farm', poster: '/video/tour.webp',
+      tracks: [{ src: '/video/tour.en.vtt', srclang: 'en', label: 'English' }], category: 'Events' },
+  ]}
+  counts
+/>
+<!-- .videos { --vg-play-bg: var(--brand); --vg-radius: var(--radius); --vg-chip-on-bg: var(--brand); } -->`,
+    license:
+      'The videos stay yours, or their owners’: the gallery plays them from YouTube, Vimeo or your own site, under those services’ terms, and adds nothing of its own. The films in our demo are the Blender Foundation’s open films Big Buck Bunny and Sintel, CC BY 3.0, credited under each one as that licence asks.',
+    usedOn: [{ site: 'superherotech.ai', where: '/elements/video-gallery/ (demo)' }],
+    file: 'src/library/video-gallery/VideoGallery.astro',
+    added: '2026-09-26',
+  },
 ];
 
 export const byId = (id: string) => catalog.find((e) => e.id === id);
diff --git a/src/library/video-gallery/VideoGallery.astro b/src/library/video-gallery/VideoGallery.astro
new file mode 100644
index 0000000..de6827f
--- /dev/null
+++ b/src/library/video-gallery/VideoGallery.astro
@@ -0,0 +1,771 @@
+---
+/**
+ * VideoGallery — a grid of videos from YouTube, Vimeo or your own files, each behind your own
+ * poster and play button, with optional category filter chips. A click plays the video in one
+ * lightbox <dialog> (`mode="lightbox"`, the default) or in the tile itself (`mode="inline"`).
+ * WordPress calls it UABB's or PowerPack's "Video Gallery", Elementor's Video Playlist, or a
+ * YouTube gallery plugin. One video on its own is video-player; this is several at once.
+ *
+ * The facade contract, the same as video-player's (the URL parser below is a COPY of its
+ * `<video-player-parse>` block; elements never import each other, and
+ * scripts/check-media-and-links.mjs fails if the two copies drift apart). At load the page
+ * has the posters, a play control per tile and nothing from YouTube or Vimeo: no iframe, no
+ * script, no preconnect, no thumbnail. A tile without `poster` shows a neutral panel, never
+ * YouTube's thumbnail. On a click the iframe is created on youtube-nocookie.com or
+ * player.vimeo.com with dnt=1 and autoplay; a file gets a <video> with native controls, its
+ * poster and its caption tracks. So no YouTube cookie exists before someone presses play.
+ *
+ * The play control is a real <button type="button"> named "Play: <title>". Without JavaScript
+ * each tile is instead a link to the video's own page (YouTube, Vimeo, or the file itself),
+ * named "Watch “<title>” on YouTube", and the filter chips are not shown: every video is. The
+ * script that turns links into buttons runs straight after the gallery, before the first
+ * paint, so nothing flickers or shifts.
+ *
+ * Filter chips (when videos carry a `category` and there are two or more): a group of
+ * <button aria-pressed>, "All" first and pressed. Choosing one hides the other tiles and says
+ * how many are shown in a polite live region. Tiles fade in when shown, except under
+ * prefers-reduced-motion.
+ *
+ * Lightbox: ONE native <dialog> per gallery, filled on open. showModal() traps focus, Escape
+ * and a backdrop click close it, the close button is labelled, the page does not scroll
+ * underneath (the scrollbar's width is kept), and focus returns to the tile that opened it.
+ * On open a YouTube or Vimeo video starts and focus goes to the close button, not into the
+ * iframe: a cross-origin player keeps every key, Escape included. Tab moves on into it. A file
+ * gets focus itself. Closing empties the dialog, so the sound stops.
+ *
+ * Inline: the tile's poster and button are replaced by the player, and focus moves into it.
+ * Pressing another tile puts the first one back to its poster (which stops it), so one video
+ * plays at a time. A filter that hides a playing tile stops it too.
+ *
+ * Self-hosted files: pass `tracks` with a captions track (WCAG 1.2.2); the build warns
+ * without one. Track files must be same-origin.
+ *
+ * Theming, from the host's tokens (each has a fallback):
+ *   --vg-min / --vg-gap   no tile narrower than min (`columns` is the most per row)        (14rem / 1.25rem)
+ *   --vg-template       the whole grid-template-columns, when the host wants its own grid    (unset)
+ *   --vg-radius         corner radius of each frame                                          (0.5rem)
+ *   --vg-bg             frame colour behind poster and player                                (#000)
+ *   --vg-panel          the tile's background when it has no poster                          (linear-gradient(135deg, #2c3656, #1e283c))
+ *   --vg-overlay        tint over the poster                                                 (rgb(0 0 0 / 0.12))
+ *   --vg-play-bg / --vg-play-fg / --vg-play-size   the play button                         (rgb(0 0 0 / 0.7) / #fff / 3.5rem)
+ *   --vg-focus          focus ring on tiles, chips and the close button                     (#5933d8)
+ *   --vg-title / --vg-caption   title and caption text                                       (inherit / inherit)
+ *   --vg-chip-bg / --vg-chip-fg / --vg-chip-border                                           (#fff / #1e283c / #c9cedb)
+ *   --vg-chip-on-bg / --vg-chip-on-fg   the pressed chip                                     (#1e283c / #fff)
+ *   --vg-backdrop       lightbox backdrop                                                    (rgb(0 0 0 / 0.88))
+ *   --vg-close-bg / --vg-close-fg   lightbox close button and title                          (rgb(255 255 255 / 0.15) / #fff)
+ */
+interface Source {
+  src: string;
+  /** MIME type. Inferred from .mp4 / .m4v / .webm / .ogv when left out. */
+  type?: string;
+}
+interface Track {
+  src: string;
+  srclang: string;
+  label: string;
+  kind?: 'captions' | 'subtitles' | 'descriptions' | 'chapters';
+  default?: boolean;
+}
+export interface GalleryVideo {
+  /** A YouTube URL or id, a Vimeo URL or id, a .mp4/.webm URL, or [{ src, type }] sources. */
+  url: string | Source[];
+  /** Shown under the tile; names the play button ("Play: …"), the iframe and the lightbox. */
+  title: string;
+  caption?: string;
+  /** Your thumbnail, served by your site. Without one the tile is a neutral panel. */
+  poster?: string;
+  /** One category, or several; the filter chips are made from these. */
+  category?: string | string[];
+  /** Text tracks for a self-hosted file. */
+  tracks?: Track[];
+}
+interface Props {
+  videos: GalleryVideo[];
+  /** 'lightbox' plays in one dialog over the page; 'inline' plays in the tile. Default 'lightbox'. */
+  mode?: 'lightbox' | 'inline';
+  /** At most this many columns (1–6). Default 3. Tiles never go narrower than --vg-min. */
+  columns?: number;
+  /** Show the category chips. Default: when the videos carry two or more categories. */
+  filter?: boolean;
+  /** Show how many videos each chip holds. Default false. */
+  counts?: boolean;
+  /** The first chip. Default "All". */
+  allLabel?: string;
+  /** Accessible name of the chip group. Default "Filter videos". */
+  filterLabel?: string;
+  /** Width / height of every frame. Default 16/9. */
+  aspect?: number | string;
+  /** Start playing on the click. Default true. */
+  autoplay?: boolean;
+  /** Element for each tile's title. Default 'h3'. */
+  titleTag?: 'h2' | 'h3' | 'h4' | 'p';
+  /** Prefix of each button's name. Default "Play". */
+  playLabel?: string;
+  /** Name of the lightbox close button. Default "Close video". */
+  closeLabel?: string;
+  /** Inline SVG markup for the play icon. Default: a triangle. */
+  playIcon?: string;
+  class?: string;
+}
+
+// A copy of video-player’s <video-player-parse> block. Keep the two identical: the check compares them.
+// <video-gallery-parse>
+type Parsed =
+  | { kind: 'youtube'; id: string }
+  | { kind: 'vimeo'; id: string; hash?: string }
+  | { kind: 'file'; sources: { src: string; type?: string }[] };
+
+function mimeOf(url: string): string | undefined {
+  const ext = (url.split(/[?#]/)[0].match(/\.([a-z0-9]+)$/i) || [])[1]?.toLowerCase();
+  return ext === 'mp4' || ext === 'm4v' ? 'video/mp4' : ext === 'webm' ? 'video/webm' : ext === 'ogv' ? 'video/ogg' : undefined;
+}
+
+function parseVideoSrc(src: string | { src: string; type?: string }[]): Parsed | null {
+  if (Array.isArray(src)) {
+    if (!src.length) return null;
+    return { kind: 'file', sources: src.map((s) => ({ src: s.src, type: s.type ?? mimeOf(s.src) })) };
+  }
+  const s = String(src ?? '').trim();
+  if (!s) return null;
+  if (/\.(mp4|m4v|webm|ogv)(?:[?#].*)?$/i.test(s)) return { kind: 'file', sources: [{ src: s, type: mimeOf(s) }] };
+  if (/^[\w-]{11}$/.test(s) && !/^\d+$/.test(s)) return { kind: 'youtube', id: s };
+  if (/^\d+$/.test(s)) return { kind: 'vimeo', id: s };
+  let url: URL;
+  try {
+    url = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(s) ? s : 'https://' + s.replace(/^\/\//, ''));
+  } catch {
+    return null;
+  }
+  const host = url.hostname.replace(/^(www|m|music)\./, '');
+  const parts = url.pathname.split('/').filter(Boolean);
+  const ytId = (v: string | null | undefined) => (v && /^[\w-]{11}$/.test(v) ? v : null);
+  if (host === 'youtu.be') {
+    const id = ytId(parts[0]);
+    return id ? { kind: 'youtube', id } : null;
+  }
+  if (host === 'youtube.com' || host === 'youtube-nocookie.com') {
+    const id = ytId(url.searchParams.get('v')) ?? (['embed', 'shorts', 'live', 'v'].includes(parts[0]) ? ytId(parts[1]) : null);
+    return id ? { kind: 'youtube', id } : null;
+  }
+  if (host === 'vimeo.com' || host === 'player.vimeo.com') {
+    const i = parts.findIndex((p) => /^\d+$/.test(p));
+    if (i < 0) return null;
+    const next = parts[i + 1];
+    const hash = url.searchParams.get('h') ?? (next && /^[0-9a-f]{6,}$/i.test(next) ? next : undefined);
+    return hash ? { kind: 'vimeo', id: parts[i], hash } : { kind: 'vimeo', id: parts[i] };
+  }
+  return null;
+}
+
+/** The iframe's URL. Built at render time; the iframe itself is only created on play. */
+function embedUrl(p: Parsed, o: { autoplay?: boolean; muted?: boolean; loop?: boolean; start?: number } = {}): string | null {
+  const start = Math.max(0, Math.floor(o.start ?? 0));
+  if (p.kind === 'youtube') {
+    const q = new URLSearchParams({ autoplay: o.autoplay === false ? '0' : '1', rel: '0', playsinline: '1' });
+    if (o.muted) q.set('mute', '1');
+    if (o.loop) {
+      q.set('loop', '1');
+      q.set('playlist', p.id); // YouTube loops a single video only as a one-item playlist.
+    }
+    if (start) q.set('start', String(start));
+    return `https://www.youtube-nocookie.com/embed/${p.id}?${q}`;
+  }
+  if (p.kind === 'vimeo') {
+    const q = new URLSearchParams({ dnt: '1', autoplay: o.autoplay === false ? '0' : '1' });
+    if (p.hash) q.set('h', p.hash);
+    if (o.muted) q.set('muted', '1');
+    if (o.loop) q.set('loop', '1');
+    return `https://player.vimeo.com/video/${p.id}?${q}${start ? `#t=${start}s` : ''}`;
+  }
+  return null;
+}
+
+/** Where the video lives, for the no-JavaScript link. */
+function watchUrl(p: Parsed): string {
+  if (p.kind === 'youtube') return `https://www.youtube.com/watch?v=${p.id}`;
+  if (p.kind === 'vimeo') return `https://vimeo.com/${p.id}${p.hash ? '/' + p.hash : ''}`;
+  return p.sources[0].src;
+}
+
+function aspectRatio(a: number | string | undefined): number {
+  if (typeof a === 'number' && a > 0) return a;
+  const m = String(a ?? '').match(/^\s*([\d.]+)\s*(?:[/:]\s*([\d.]+))?\s*$/);
+  const r = m ? Number(m[1]) / Number(m[2] ?? 1) : NaN;
+  return Number.isFinite(r) && r > 0 ? r : 16 / 9;
+}
+// </video-gallery-parse>
+
+const {
+  videos,
+  mode = 'lightbox',
+  columns = 3,
+  filter,
+  counts = false,
+  allLabel = 'All',
+  filterLabel = 'Filter videos',
+  aspect = 16 / 9,
+  autoplay = true,
+  titleTag = 'h3',
+  playLabel = 'Play',
+  closeLabel = 'Close video',
+  playIcon,
+  class: className,
+} = Astro.props;
+
+if (!Array.isArray(videos) || !videos.length) throw new Error('VideoGallery: `videos` needs at least one { url, title }.');
+if (mode !== 'lightbox' && mode !== 'inline') throw new Error(`VideoGallery: mode "${mode}" is not 'lightbox' or 'inline'.`);
+if (!(Number.isInteger(columns) && columns >= 1 && columns <= 6)) throw new Error(`VideoGallery: columns must be a whole number from 1 to 6, not ${JSON.stringify(columns)}.`);
+
+const slug = (s: string) =>
+  s
+    .toLowerCase()
+    .normalize('NFKD')
+    .replace(/[̀-ͯ]/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '') || 'category';
+const HOST: Record<string, string> = { youtube: 'YouTube', vimeo: 'Vimeo' };
+
+const categories: { key: string; label: string; count: number }[] = [];
+const items = videos.map((v, i) => {
+  const title = String(v?.title ?? '').trim();
+  if (!title) throw new Error(`VideoGallery: video ${i + 1} has no \`title\`; it names the play button and the iframe.`);
+  const parsed = parseVideoSrc(v.url);
+  if (!parsed) throw new Error(`VideoGallery "${title}": cannot tell what \`url\` is (${JSON.stringify(v.url)}). Use a YouTube or Vimeo URL or id, a .mp4/.webm URL, or [{ src, type }].`);
+  const tracks = v.tracks ?? [];
+  if (parsed.kind === 'file' && !tracks.some((t) => (t.kind ?? 'captions') === 'captions')) {
+    console.warn(`VideoGallery "${title}": self-hosted video without a captions track. If it has speech, add tracks: [{ src, srclang, label }].`);
+  }
+  const cats = (Array.isArray(v.category) ? v.category : v.category ? [v.category] : []).map((c) => String(c).trim()).filter(Boolean);
+  const keys: string[] = [];
+  for (const label of cats) {
+    const key = slug(label);
+    const known = categories.find((c) => c.key === key);
+    if (known) known.count++;
+    else categories.push({ key, label, count: 1 });
+    if (!keys.includes(key)) keys.push(key);
+  }
+  const host = HOST[parsed.kind];
+  // What the script needs on a click: kept short, as one JSON attribute on the button.
+  const play = {
+    k: parsed.kind,
+    t: title,
+    c: v.caption || undefined,
+    e: embedUrl(parsed, { autoplay }) || undefined,
+    s: parsed.kind === 'file' ? parsed.sources : undefined,
+    tr: parsed.kind === 'file' && tracks.length ? tracks.map((t) => ({ ...t, kind: t.kind ?? 'captions' })) : undefined,
+    p: parsed.kind === 'file' ? v.poster : undefined,
+  };
+  return {
+    title,
+    caption: v.caption,
+    poster: v.poster,
+    keys,
+    watch: watchUrl(parsed),
+    watchText: host ? `Watch “${title}” on ${host}` : `Watch “${title}”`,
+    play: JSON.stringify(play),
+  };
+});
+const showFilter = filter ?? categories.length >= 2;
+if (showFilter && !categories.length) throw new Error('VideoGallery: `filter` is on but no video has a `category`.');
+
+const lightbox = mode === 'lightbox';
+const ratio = Math.round(aspectRatio(aspect) * 1e4) / 1e4;
+const Title = titleTag;
+const icon =
+  playIcon ??
+  '<svg viewBox="0 0 24 24" width="1em" height="1em" fill="currentColor" aria-hidden="true" focusable="false"><path d="M8 5.14v13.72a1 1 0 0 0 1.5.86l11.04-6.86a1 1 0 0 0 0-1.72L9.5 4.28A1 1 0 0 0 8 5.14z"/></svg>';
+
+// The runtime goes out once per page; each gallery is mounted by the one-line script after it.
+const locals = Astro.locals as Record<string, unknown>;
+const firstOnPage = !locals.__videoGalleryScript;
+locals.__videoGalleryScript = true;
+const n = ((locals.__videoGalleryCount as number) ?? 0) + 1;
+locals.__videoGalleryCount = n;
+const uid = `vg-${n}`;
+---
+
+{
+  firstOnPage && (
+    <script is:inline>
+      (() => {
+        if (window.__superheroVideoGallery) return;
+
+        // Scroll lock for the lightbox, as in video-player: keep the scrollbar's width.
+        let locked = 0;
+        let saved = null;
+        const lock = (on) => {
+          const html = document.documentElement;
+          if (on) {
+            if (locked++) return;
+            saved = [html.style.overflow, html.style.paddingRight];
+            const bar = window.innerWidth - html.clientWidth;
+            html.style.overflow = 'hidden';
+            if (bar > 0) html.style.paddingRight = bar + 'px';
+          } else if (locked && !--locked) {
+            [html.style.overflow, html.style.paddingRight] = saved;
+          }
+        };
+
+        const frameFor = (d) => {
+          const f = document.createElement('iframe');
+          f.src = d.e;
+          f.title = d.t;
+          f.allow = 'autoplay; encrypted-media; picture-in-picture; fullscreen; web-share';
+          f.allowFullscreen = true;
+          // YouTube refuses to play embeds that send no referrer (error 153).
+          f.referrerPolicy = 'strict-origin-when-cross-origin';
+          return f;
+        };
+        const videoFor = (d) => {
+          const v = document.createElement('video');
+          v.controls = true;
+          v.playsInline = true;
+          v.preload = 'metadata';
+          if (d.p) v.poster = d.p;
+          v.setAttribute('aria-label', d.t);
+          for (const s of d.s || []) {
+            const el = document.createElement('source');
+            el.src = s.src;
+            if (s.type) el.type = s.type;
+            v.append(el);
+          }
+          for (const t of d.tr || []) {
+            const el = document.createElement('track');
+            el.kind = t.kind;
+            el.src = t.src;
+            el.srclang = t.srclang;
+            el.label = t.label;
+            if (t.default) el.default = true;
+            v.append(el);
+          }
+          return v;
+        };
+        const playerFor = (d) => (d.k === 'file' ? videoFor(d) : frameFor(d));
+        const start = (el, root) => {
+          if (el.tagName !== 'VIDEO' || root.dataset.vgAutoplay === 'false') return;
+          const p = el.play();
+          if (p) p.catch(() => {}); // Refused (e.g. Low Power Mode): the native controls remain.
+        };
+
+        const mount = (root) => {
+          if (!root || root.dataset.vgReady) return;
+          root.dataset.vgReady = '1';
+
+          // Links (the no-JavaScript render) become the buttons.
+          root.querySelectorAll('[data-vg-link]').forEach((a) => a.remove());
+          root.querySelectorAll('[data-vg-play]').forEach((b) => (b.hidden = false));
+
+          // Inline: one tile plays at a time; the others keep (or get back) their poster.
+          let current = null;
+          const restore = () => {
+            if (!current) return;
+            current.frame.replaceChildren(...current.nodes);
+            delete current.frame.dataset.vgPlaying;
+            current = null;
+          };
+
+          const bar = root.querySelector('[data-vg-filters]');
+          if (bar) {
+            bar.hidden = false;
+            const chips = [...bar.querySelectorAll('[data-vg-filter]')];
+            const tiles = [...root.querySelectorAll('[data-vg-item]')];
+            const status = root.querySelector('[data-vg-status]');
+            bar.addEventListener('click', (e) => {
+              const chip = e.target.closest('[data-vg-filter]');
+              if (!chip || chip.getAttribute('aria-pressed') === 'true') return;
+              const key = chip.dataset.vgFilter;
+              chips.forEach((c) => c.setAttribute('aria-pressed', String(c === chip)));
+              let shown = 0;
+              tiles.forEach((li) => {
+                const on = !key || li.dataset.vgCats.split(' ').includes(key);
+                li.hidden = !on;
+                if (on) shown++;
+                else if (current && li.contains(current.frame)) restore();
+              });
+              if (status) status.textContent = `${chip.dataset.vgName}: ${shown} ${shown === 1 ? 'video' : 'videos'}.`;
+            });
+          }
+
+          const dialog = root.querySelector('[data-vg-dialog]');
+          const stage = dialog && dialog.querySelector('[data-vg-stage]');
+          const dTitle = dialog && dialog.querySelector('[data-vg-dtitle]');
+          const dCaption = dialog && dialog.querySelector('[data-vg-dcaption]');
+          const closeBtn = dialog && dialog.querySelector('[data-vg-close]');
+          let opener = null;
+
+          root.addEventListener('click', (e) => {
+            const btn = e.target.closest('[data-vg-play]');
+            if (!btn) return;
+            let d;
+            try {
+              d = JSON.parse(btn.dataset.vgPlay);
+            } catch {
+              return;
+            }
+            const el = playerFor(d);
+            if (dialog) {
+              opener = btn;
+              dialog.setAttribute('aria-label', d.t);
+              dTitle.textContent = d.t;
+              dCaption.textContent = d.c || '';
+              dCaption.hidden = !d.c;
+              stage.replaceChildren(el);
+              dialog.showModal();
+              lock(true);
+              // Not into a cross-origin iframe: it would keep Escape. Tab moves on into it.
+              (d.k === 'file' ? el : closeBtn).focus();
+            } else {
+              restore();
+              const frame = btn.closest('[data-vg-frame]');
+              current = { frame, nodes: [...frame.childNodes] };
+              frame.replaceChildren(el);
+              frame.dataset.vgPlaying = '';
+              el.focus();
+            }
+            start(el, root);
+          });
+
+          if (dialog) {
+            closeBtn.addEventListener('click', () => dialog.close());
+            // The dialog fills the viewport; a press and release on it outside the box is the backdrop.
+            let downOnBackdrop = false;
+            dialog.addEventListener('pointerdown', (e) => (downOnBackdrop = e.target === dialog));
+            dialog.addEventListener('click', (e) => {
+              if (e.target === dialog && downOnBackdrop) dialog.close();
+              downOnBackdrop = false;
+            });
+            dialog.addEventListener('close', () => {
+              stage.replaceChildren(); // Unload: the only way to be sure the sound stops.
+              lock(false);
+              if (opener && opener.isConnected) opener.focus();
+              opener = null;
+            });
+          }
+        };
+
+        window.__superheroVideoGallery = { mount };
+      })();
+    </script>
+  )
+}
+<div
+  id={uid}
+  class:list={['vg', `vg--${mode}`, className]}
+  style={`--vg-ratio:${ratio};--vg-cols:${columns}`}
+  data-vg={mode}
+  data-vg-autoplay={autoplay ? undefined : 'false'}
+>
+  {
+    showFilter && (
+      <div class="vg__filters" role="group" aria-label={filterLabel} hidden data-vg-filters>
+        <button class="vg__chip" type="button" aria-pressed="true" data-vg-filter="" data-vg-name={allLabel}>
+          {allLabel}
+          {counts && <span class="vg__count">{` (${items.length})`}</span>}
+        </button>
+        {categories.map((c) => (
+          <button class="vg__chip" type="button" aria-pressed="false" data-vg-filter={c.key} data-vg-name={c.label}>
+            {c.label}
+            {counts && <span class="vg__count">{` (${c.count})`}</span>}
+          </button>
+        ))}
+      </div>
+    )
+  }
+  {showFilter && <p class="vg__sr" aria-live="polite" data-vg-status />}
+  <ul class="vg__grid" role="list">
+    {
+      items.map((v) => (
+        <li class="vg__item" data-vg-item data-vg-cats={v.keys.join(' ')}>
+          <div class="vg__frame" data-vg-frame>
+            {v.poster ? <img class="vg__poster" src={v.poster} alt="" loading="lazy" decoding="async" /> : <span class="vg__panel" aria-hidden="true" />}
+            <a class="vg__hit" href={v.watch} data-vg-link>
+              <span class="vg__icon" aria-hidden="true" set:html={icon} />
+              <span class="vg__sr">{v.watchText}</span>
+            </a>
+            <button
+              class="vg__hit"
+              type="button"
+              hidden
+              aria-label={`${playLabel}: ${v.title}`}
+              aria-haspopup={lightbox ? 'dialog' : undefined}
+              data-vg-play={v.play}
+            >
+              <span class="vg__icon" aria-hidden="true" set:html={icon} />
+            </button>
+          </div>
+          <Title class="vg__title">{v.title}</Title>
+          {v.caption && <p class="vg__caption">{v.caption}</p>}
+        </li>
+      ))
+    }
+  </ul>
+  {
+    lightbox && (
+      <dialog class="vg__dialog" aria-label="Video" data-vg-dialog>
+        <div class="vg__box">
+          <div class="vg__bar">
+            <p class="vg__dtitle" data-vg-dtitle />
+            <button class="vg__close" type="button" aria-label={closeLabel} data-vg-close>
+              <svg viewBox="0 0 24 24" width="1.25em" height="1.25em" aria-hidden="true" focusable="false"><path d="M6 6l12 12M18 6L6 18" stroke="currentColor" stroke-width="2.25" stroke-linecap="round" /></svg>
+            </button>
+          </div>
+          <div class="vg__stage" data-vg-stage />
+          <p class="vg__dcaption" hidden data-vg-dcaption />
+        </div>
+      </dialog>
+    )
+  }
+</div>
+<script is:inline>window.__superheroVideoGallery.mount(document.currentScript.previousElementSibling);</script>
+
+<style>
+  .vg {
+    --vg-g: var(--vg-gap, 1.25rem);
+  }
+  .vg__filters {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+    margin: 0 0 1rem;
+  }
+  .vg__filters[hidden] {
+    display: none;
+  }
+  .vg__chip {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.35em;
+    min-height: 2.75rem;
+    padding: 0.4rem 1rem;
+    border: 1px solid var(--vg-chip-border, #c9cedb);
+    border-radius: 999px;
+    background: var(--vg-chip-bg, #fff);
+    color: var(--vg-chip-fg, #1e283c);
+    font: inherit;
+    font-size: 0.95em;
+    cursor: pointer;
+  }
+  .vg__chip[aria-pressed='true'] {
+    border-color: var(--vg-chip-on-bg, #1e283c);
+    background: var(--vg-chip-on-bg, #1e283c);
+    color: var(--vg-chip-on-fg, #fff);
+  }
+  .vg__chip:focus-visible,
+  .vg__close:focus-visible {
+    outline: 3px solid var(--vg-focus, #5933d8);
+    outline-offset: 2px;
+  }
+  .vg__count {
+    opacity: 0.8;
+    font-variant-numeric: tabular-nums;
+  }
+  .vg__grid {
+    display: grid;
+    /* At most `columns` per row, none narrower than --vg-min, one column when even that does not fit. */
+    grid-template-columns: var(
+      --vg-template,
+      repeat(auto-fill, minmax(min(100%, max(var(--vg-min, 14rem), (100% - (var(--vg-cols) - 1) * var(--vg-g)) / var(--vg-cols))), 1fr))
+    );
+    gap: var(--vg-g);
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+  .vg__item {
+    min-width: 0;
+    margin: 0;
+  }
+  .vg__item[hidden] {
+    display: none;
+  }
+  @media (prefers-reduced-motion: no-preference) {
+    /* Runs whenever a tile is shown again by a filter. */
+    .vg__item {
+      animation: vg-in 0.25s ease-out;
+    }
+    .vg__icon {
+      transition: scale 0.18s ease;
+    }
+    .vg__hit:hover .vg__icon,
+    .vg__hit:focus-visible .vg__icon {
+      scale: 1.08;
+    }
+  }
+  @keyframes vg-in {
+    from {
+      opacity: 0;
+      translate: 0 0.4rem;
+    }
+  }
+  .vg__frame {
+    position: relative;
+    aspect-ratio: var(--vg-ratio, 16 / 9);
+    overflow: hidden;
+    border-radius: var(--vg-radius, 0.5rem);
+    background: var(--vg-bg, #000);
+  }
+  .vg__poster,
+  .vg__panel,
+  .vg__frame > :global(iframe),
+  .vg__frame > :global(video) {
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+    border: 0;
+  }
+  .vg__poster {
+    object-fit: cover;
+  }
+  .vg__panel {
+    background: var(--vg-panel, linear-gradient(135deg, #2c3656, #1e283c));
+  }
+  .vg__frame > :global(video) {
+    display: block;
+    object-fit: contain;
+    background: var(--vg-bg, #000);
+  }
+  .vg__hit {
+    position: absolute;
+    inset: 0;
+    display: grid;
+    place-items: center;
+    width: 100%;
+    height: 100%;
+    padding: 0;
+    border: 0;
+    background: var(--vg-overlay, rgb(0 0 0 / 0.12));
+    color: var(--vg-play-fg, #fff);
+    text-decoration: none;
+    cursor: pointer;
+  }
+  .vg__hit[hidden] {
+    display: none;
+  }
+  .vg__hit:focus-visible {
+    outline: 3px solid var(--vg-focus, #5933d8);
+    outline-offset: -3px;
+  }
+  .vg__icon {
+    display: grid;
+    place-items: center;
+    width: var(--vg-play-size, 3.5rem);
+    height: var(--vg-play-size, 3.5rem);
+    border-radius: 50%;
+    background: var(--vg-play-bg, rgb(0 0 0 / 0.7));
+    font-size: calc(var(--vg-play-size, 3.5rem) * 0.45);
+    line-height: 0;
+    box-shadow: 0 0.25rem 1rem rgb(0 0 0 / 0.3);
+  }
+  .vg__icon :global(svg) {
+    translate: 6% 0;
+  }
+  .vg__hit:focus-visible .vg__icon {
+    box-shadow:
+      0 0 0 3px #fff,
+      0 0 0 6px var(--vg-focus, #5933d8);
+  }
+  .vg__title {
+    margin: 0.6rem 0 0;
+    color: var(--vg-title, inherit);
+    font-size: 1.05rem;
+    font-weight: 600;
+    line-height: 1.3;
+  }
+  .vg__caption {
+    margin: 0.25rem 0 0;
+    color: var(--vg-caption, inherit);
+    font-size: 0.9em;
+  }
+  .vg__sr {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    margin: -1px;
+    padding: 0;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    border: 0;
+  }
+
+  /* Lightbox: the dialog is the backdrop and fills the viewport; the box is centred in it. */
+  .vg__dialog {
+    box-sizing: border-box;
+    width: 100%;
+    height: 100%;
+    max-width: none;
+    max-height: none;
+    margin: 0;
+    padding: clamp(0.75rem, 3vw, 2rem);
+    border: 0;
+    background: var(--vg-backdrop, rgb(0 0 0 / 0.88));
+    color: var(--vg-close-fg, #fff);
+    overscroll-behavior: contain;
+  }
+  .vg__dialog[open] {
+    display: grid;
+    place-items: center;
+  }
+  .vg__dialog::backdrop {
+    background: transparent;
+  }
+  .vg__box {
+    display: grid;
+    gap: 0.5rem;
+    /* As wide as fits, and no taller than the viewport minus the title row and caption. */
+    width: min(100%, calc((100dvh - 2 * clamp(0.75rem, 3vw, 2rem) - 5.5rem) * var(--vg-ratio, 1.7778)));
+  }
+  .vg__bar {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 1rem;
+  }
+  .vg__dtitle {
+    margin: 0;
+    font-weight: 600;
+    overflow-wrap: anywhere;
+  }
+  .vg__close {
+    flex: none;
+    display: grid;
+    place-items: center;
+    width: 2.75rem;
+    height: 2.75rem;
+    padding: 0;
+    border: 0;
+    border-radius: 50%;
+    background: var(--vg-close-bg, rgb(255 255 255 / 0.15));
+    color: var(--vg-close-fg, #fff);
+    cursor: pointer;
+  }
+  .vg__close:focus-visible {
+    outline-color: #fff;
+  }
+  .vg__stage {
+    position: relative;
+    width: 100%;
+    aspect-ratio: var(--vg-ratio, 16 / 9);
+    background: var(--vg-bg, #000);
+  }
+  .vg__stage > :global(iframe),
+  .vg__stage > :global(video) {
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+    border: 0;
+  }
+  .vg__dcaption {
+    margin: 0;
+    font-size: 0.9em;
+    opacity: 0.85;
+  }
+  @media print {
+    .vg__dialog {
+      display: none !important;
+    }
+  }
+</style>

From 905be4d2f14a926dc1110ef4ac4b5c295c6367e7 Mon Sep 17 00:00:00 2001
From: Warren <warreng@ecropolis.com>
Date: Sat, 26 Sep 2026 11:34:05 -0500
Subject: [PATCH 2/3] map: location cards with Google Maps links, and a map
 only on request
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

One card per location: the address in an <address>, a tel: link, an
optional hours line, and "Open in Google Maps" / "Directions" links to
Google's keyless Maps URLs, named with the place. `embed` adds a facade (the
location's photo, or a neutral panel with Font Awesome Free's pin) that is a
<button> named "Show the map of <name>" and described by "Loads a map from
Google."; pressed, it becomes a lazy google.com/maps?…&output=embed iframe
titled "Map of <name>". Nothing is fetched from Google before that. Without
JavaScript: the cards and links, no facade.

Not the Maps JavaScript API: it needs a key and billing, loads Google's script
on every visit, and adds Google's origins to every client CSP and consent
policy. That is the notFor case. LocalBusiness JSON-LD stays with
business-hours. The file is LocationMap.astro so an import cannot shadow
JavaScript's Map.

check-media-and-links pins the URL builders, the no-JS render, the ARIA, the
FA Free pin and the fallback contrast, with 10 more mutations.

Search: "google map embed code for website" 170/mo, difficulty 35 (SE
Ranking US, 2026-09-26); "map embed without api key" has no data.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 scripts/check-media-and-links.mjs  | 197 ++++++++++++-
 src/components/demos/MapDemo.astro |  80 ++++++
 src/components/demos/index.ts      |   2 +
 src/data/catalog.ts                |  72 +++++
 src/library/map/LocationMap.astro  | 435 +++++++++++++++++++++++++++++
 5 files changed, 785 insertions(+), 1 deletion(-)
 create mode 100644 src/components/demos/MapDemo.astro
 create mode 100644 src/library/map/LocationMap.astro

diff --git a/scripts/check-media-and-links.mjs b/scripts/check-media-and-links.mjs
index 49e855e..a2b2d0f 100644
--- a/scripts/check-media-and-links.mjs
+++ b/scripts/check-media-and-links.mjs
@@ -23,6 +23,19 @@
  * 3. Motion (animation, transition, scale on hover) sits only inside
  *    `@media (prefers-reduced-motion: no-preference)`.
  *
+ * map
+ * 4. The URL builders (`<map-urls>` block): search, directions and embed URLs with the query
+ *    encoded, zoom rounded, tel: digits.
+ * 5. On the demo page and the index: every card has an <address>, an "Open in Google Maps" and a
+ *    "Directions" link to Google's keyless Maps URLs, named with the place; a facade, when
+ *    there is one, is hidden until the script runs, is a <button type="button"> named
+ *    "Show the map of <name>" and described by a notice that names Google, and carries a
+ *    www.google.com/maps?…&output=embed URL; no iframe at load; the runtime creates the iframe
+ *    with loading="lazy" and the title; the mount script is straight after each map; the pin
+ *    is Font Awesome Free's location-dot, path for path.
+ * 6. The fallback colours pass 4.5:1 (text, links, notice on the card; the button's text on
+ *    its fill); motion only under no-preference.
+ *
  * Mutation tests: each element's checks are also run against deliberately broken copies of its
  * input (an iframe injected, a name removed, a colour darkened, …). A mutation the checks do
  * not catch fails the run: a check that cannot fail is not a check.
@@ -271,4 +284,186 @@ for (const m of run(checkGalleryMotion, vgSources.gallery)) fail(m);
 }
 finish('video-gallery');
 
-console.log(`check-media-and-links ok: ${pages.length} built pages load nothing from Google, YouTube or Vimeo; video-gallery parser is video-player's, its no-JS render and ARIA hold on 2 pages; ${mutations} mutations caught.`);
+// ---------------------------------------------------------------- contrast
+const hexOf = (c) => {
+  let h = c.replace('#', '');
+  if (h.length === 3) h = [...h].map((x) => x + x).join('');
+  return h;
+};
+const lum = (c) =>
+  [0, 2, 4]
+    .map((i) => parseInt(hexOf(c).slice(i, i + 2), 16) / 255)
+    .map((v) => (v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4))
+    .reduce((a, v, i) => a + v * [0.2126, 0.7152, 0.0722][i], 0);
+const contrast = (a, b) => {
+  const [x, y] = [lum(a), lum(b)].sort((m, n) => n - m);
+  return (x + 0.05) / (y + 0.05);
+};
+/** Every `var(--name, #hex)` fallback in `css`, which must agree wherever the token is used. */
+const fallbacks = (css, file, fail) => {
+  const seen = {};
+  for (const [, name, value] of css.matchAll(/var\((--[\w-]+),\s*(#[0-9a-f]{3,6})\s*\)/gi)) {
+    if (seen[name] && seen[name] !== value.toLowerCase()) fail(`${file}: ${name} falls back to ${seen[name]} in one place and ${value} in another.`);
+    seen[name] = value.toLowerCase();
+  }
+  return seen;
+};
+const pairs = (tokens, list, file, fail, report) => {
+  for (const [fg, bg, min, what] of list) {
+    if (!tokens[fg] || !tokens[bg]) {
+      fail(`${file}: no hex fallback for ${!tokens[fg] ? fg : bg}, so ${what} cannot be measured.`);
+      continue;
+    }
+    const r = contrast(tokens[fg], tokens[bg]);
+    report?.push(`${what} ${r.toFixed(2)}:1`);
+    if (r < min) fail(`${file}: ${what} is ${tokens[fg]} on ${tokens[bg]}, ${r.toFixed(2)}:1, under ${min}:1.`);
+  }
+};
+
+// ---------------------------------------------------------------------- map
+const MAP = 'src/library/map/LocationMap.astro';
+const mapSrc = src(MAP);
+const mapBlock = block(mapSrc, 'map-urls');
+if (!mapBlock) {
+  fail(`${MAP} has no \`// <map-urls>\` … \`// </map-urls>\` block.`);
+  finish('map urls');
+}
+const { mapUrls, telHref } = await import(
+  `data:text/javascript;base64,${Buffer.from(`${stripTypeScriptTypes(mapBlock, { mode: 'strip' })}\nexport { mapUrls, telHref };`).toString('base64')}`
+);
+{
+  const u = mapUrls('Joe’s Café & Bar, 1 Main St,  Springfield, IL', 15.4);
+  const q = 'Joe%E2%80%99s%20Caf%C3%A9%20%26%20Bar%2C%201%20Main%20St%2C%20Springfield%2C%20IL';
+  const want = {
+    open: `https://www.google.com/maps/search/?api=1&query=${q}`,
+    directions: `https://www.google.com/maps/dir/?api=1&destination=${q}`,
+    embed: `https://www.google.com/maps?q=${q}&z=15&output=embed`,
+  };
+  for (const k of Object.keys(want)) if (u[k] !== want[k]) fail(`mapUrls ${k}: ${u[k]}, expected ${want[k]}.`);
+  if (mapUrls('x').embed !== 'https://www.google.com/maps?q=x&output=embed') fail('mapUrls without zoom must not add &z=.');
+  for (const [p, want] of [['(312) 555-0142', 'tel:3125550142'], ['+44 20 7946 0958', 'tel:+442079460958'], ['+1-312-555-0142 ext', 'tel:+13125550142']]) {
+    if (telHref(p) !== want) fail(`telHref("${p}") = ${telHref(p)}, expected ${want}.`);
+  }
+}
+finish('map urls');
+
+const MOUNT_MAP = '<script>window.__superheroMap.mount(document.currentScript.previousElementSibling);</script>';
+const faPin = readFileSync(join(root, 'node_modules/@fortawesome/fontawesome-free/svgs/solid/location-dot.svg'), 'utf8').match(/<path[^>]*\sd="([^"]+)"/)[1];
+const checkMapPage = ({ rel, html, demo }, fail) => {
+  const roots = [...html.matchAll(/<div\b[^>]*\sdata-map(?=[\s>])[^>]*>/g)];
+  if (demo && roots.length !== 2) fail(`${rel}: expected the demo's 2 maps, found ${roots.length}.`);
+  let facades = 0;
+  let photos = 0;
+  let panels = 0;
+  roots.forEach((r, mi) => {
+    const where = `${rel}, map ${mi + 1}`;
+    const end = html.indexOf(MOUNT_MAP, r.index);
+    if (end < 0) {
+      fail(`${where}: no mount script after it.`);
+      return;
+    }
+    const chunk = html.slice(r.index, end);
+    if (!/<\/div>\s*$/.test(chunk) || (roots[mi + 1] && roots[mi + 1].index < end)) fail(`${where}: the mount script must come straight after the map, or the facades appear after the first paint.`);
+    if (/<iframe\b/i.test(chunk)) fail(`${where}: an <iframe> at load; the map loads on a click.`);
+    const cards = chunk.split(/(?=<(?:li|div)\b[^>]*class="map__card)/).slice(1);
+    if (!cards.length) fail(`${where}: no cards.`);
+    cards.forEach((card, ci) => {
+      const nameEl = card.match(/<(h2|h3|h4)\b[^>]*class="map__name"[^>]*>([\s\S]*?)<\/\1>/);
+      const name = nameEl ? text(nameEl[2]) : '';
+      const w = `${where}, card ${ci + 1} ("${name}")`;
+      if (!name) fail(`${w}: no heading with the place's name.`);
+      const addr = card.match(/<address\b[^>]*>([\s\S]*?)<\/address>/);
+      if (!addr || !text(addr[1])) fail(`${w}: no <address>.`);
+      const tel = addr && addr[1].match(/<a\b[^>]*href="([^"]*)"/);
+      if (tel && !/^tel:\+?\d{7,}$/.test(tel[1])) fail(`${w}: the phone link ${tel[1]} is not tel:<digits>.`);
+      const open = card.match(/<a\b[^>]*\sdata-map-open[^>]*>([\s\S]*?)<\/a>/);
+      const dir = card.match(/<a\b[^>]*\sdata-map-directions[^>]*>([\s\S]*?)<\/a>/);
+      for (const [a, base, label] of [
+        [open, 'https://www.google.com/maps/search/?api=1&query=', 'Open in Google Maps'],
+        [dir, 'https://www.google.com/maps/dir/?api=1&destination=', 'Directions'],
+      ]) {
+        if (!a) {
+          fail(`${w}: no "${label}" link.`);
+          continue;
+        }
+        const href = decode(attr(a[0], 'href')) || '';
+        if (!href.startsWith(base) || href.length === base.length) fail(`${w}: "${label}" goes to ${href}, not ${base}<query>.`);
+        if (/[?&]key=/.test(href)) fail(`${w}: "${label}" carries an API key.`);
+        const nameAttr = decode(attr(a[0], 'aria-label')) || '';
+        if (!nameAttr.startsWith(text(a[1])) || !nameAttr.includes(name)) fail(`${w}: "${label}" is named "${nameAttr}"; it must start with its visible words and name the place.`);
+      }
+      const media = card.match(/<div\b[^>]*\sdata-map-media[^>]*>/);
+      if (!media) return;
+      facades++;
+      if (attr(media[0], 'hidden') === undefined) fail(`${w}: the facade must be hidden until the script can make it work.`);
+      const btn = card.match(/<button\b[^>]*\sdata-map-load=[^>]*>/);
+      if (!btn) {
+        fail(`${w}: a facade without its button.`);
+        return;
+      }
+      if (attr(btn[0], 'type') !== 'button') fail(`${w}: the facade button needs type="button".`);
+      if (decode(attr(btn[0], 'aria-label')) !== `Show the map of ${name}`) fail(`${w}: the facade button is named "${decode(attr(btn[0], 'aria-label'))}", expected "Show the map of ${name}".`);
+      const desc = attr(btn[0], 'aria-describedby');
+      const note = desc && card.match(new RegExp(`<p\\b[^>]*\\sid="${desc}"[^>]*>([\\s\\S]*?)</p>`));
+      if (!note || !/Google/.test(text(note[1]))) fail(`${w}: the facade button must be described by a visible notice that the map loads from Google.`);
+      const load = decode(attr(btn[0], 'data-map-load')) || '';
+      if (!/^https:\/\/www\.google\.com\/maps\?q=[^&]+(?:&z=\d+)?&output=embed$/.test(load)) fail(`${w}: the embed URL ${load} is not www.google.com/maps?q=…&output=embed.`);
+      if (decode(attr(btn[0], 'data-map-title')) !== `Map of ${name}`) fail(`${w}: the map would be titled "${decode(attr(btn[0], 'data-map-title'))}", expected "Map of ${name}".`);
+      if (/<img\b[^>]*class="map__photo"/.test(card)) {
+        photos++;
+        const img = card.match(/<img\b[^>]*class="map__photo"[^>]*>/)[0];
+        if (attr(img, 'alt') !== '') fail(`${w}: the facade photo sits inside a named button; it must be alt="".`);
+      } else {
+        panels++;
+        const d = (card.match(/<svg\b[^>]*class="map__pin"[\s\S]*?<path\b[^>]*\sd="([^"]+)"/) || [])[1];
+        if (d !== faPin) fail(`${w}: the pin is not Font Awesome Free's location-dot.`);
+      }
+    });
+  });
+  if (demo && !(photos && panels)) fail(`${rel}: the demo needs a photo facade and a neutral one.`);
+  if (demo && !facades) fail(`${rel}: the demo has no facade.`);
+  const runtimes = (html.match(/window\.__superheroMap = \{/g) || []).length;
+  if (roots.length && runtimes !== 1) fail(`${rel}: the map runtime is on the page ${runtimes} times; it must be once.`);
+  if (roots.length && !(/f\.loading = 'lazy'/.test(html) && /f\.title = btn\.dataset\.mapTitle/.test(html))) fail(`${rel}: the runtime must create the iframe with loading="lazy" and its title.`);
+};
+const mapPages = [
+  { rel: 'dist/map/index.html', html: built('dist/map/index.html'), demo: true },
+  { rel: 'dist/index.html', html: built('dist/index.html'), demo: false },
+];
+for (const p of mapPages) for (const m of run(checkMapPage, p)) fail(m);
+const mapContrast = [];
+const checkMapStyle = (component, fail, report) => {
+  const css = styleOf(component);
+  const t = fallbacks(css, MAP, fail);
+  pairs(
+    t,
+    [
+      ['--map-text', '--map-surface', 4.5, 'card text'],
+      ['--map-link', '--map-surface', 4.5, 'links'],
+      ['--map-notice', '--map-surface', 4.5, 'notice'],
+      ['--map-on-accent', '--map-accent', 4.5, 'button text'],
+    ],
+    MAP,
+    fail,
+    report,
+  );
+  if (/\b(?:animation|transition)\s*:/.test(outsideNoPreference(css))) fail(`${MAP}: an animation or transition outside @media (prefers-reduced-motion: no-preference).`);
+};
+checkMapStyle(mapSrc, fail, mapContrast);
+{
+  const demo = mapPages[0];
+  const re = (a, b) => (x) => ({ ...x, html: x.html.replace(a, b) });
+  mutate('a facade shows without JavaScript', checkMapPage, demo, re(/(class="map__media") hidden/, '$1'));
+  mutate('the facade button loses its name', checkMapPage, demo, re(/aria-label="Show the map of Navy Pier"/, ''));
+  mutate('the Google notice is gone', checkMapPage, demo, re(/Loads a map from Google\./, 'Loads a map.'));
+  mutate('a map iframe at load', checkMapPage, demo, re('<address', '<iframe src="https://www.google.com/maps?q=x&amp;output=embed"></iframe><address'));
+  mutate('the JavaScript API instead of the embed URL', checkMapPage, demo, re(/data-map-load="https:\/\/www\.google\.com\/maps\?q=/, 'data-map-load="https://www.google.com/maps/embed/v1/place?key=K&amp;q='));
+  mutate('"Directions" loses the place in its name', checkMapPage, demo, re(/aria-label="Directions to Navy Pier"/, 'aria-label="Directions"'));
+  mutate('a card without <address>', checkMapPage, demo, re(/<address\b([^>]*)>([\s\S]*?)<\/address>/, '<div$1>$2</div>'));
+  mutate('a pin that is not Font Awesome Free', checkMapPage, demo, re(/(class="map__pin"[\s\S]*?<path\b[^>]*\sd=")M0/, '$1M1'));
+  mutate('the lazy iframe dropped from the runtime', checkMapPage, demo, re("f.loading = 'lazy';", ''));
+  mutate('a pale button fill', (s, f) => checkMapStyle(s, f), mapSrc, (s) => s.replaceAll('var(--map-accent, #5933d8)', 'var(--map-accent, #a894f0)'));
+}
+finish('map');
+
+console.log(`check-media-and-links ok: ${pages.length} built pages load nothing from Google, YouTube or Vimeo; video-gallery parser is video-player's, its no-JS render and ARIA hold on 2 pages; map URLs, facades and links hold on 2 pages, contrast ${mapContrast.join(', ')}; ${mutations} mutations caught.`);
diff --git a/src/components/demos/MapDemo.astro b/src/components/demos/MapDemo.astro
new file mode 100644
index 0000000..393d1ff
--- /dev/null
+++ b/src/components/demos/MapDemo.astro
@@ -0,0 +1,80 @@
+---
+/**
+ * Demo for `map`. The website renders this too (see README, "Consumed by superherotech.ai"),
+ * so assets go through `asset()` and every host token has a fallback.
+ *
+ * The places are public landmarks in Chicago, not anyone's business, so the map has something
+ * real to show. The one phone number is a 555-01xx number, a range reserved for fiction; the
+ * hours are the park's own. Nothing is fetched from Google until a "Show the map" button is
+ * pressed; the links only navigate.
+ */
+import LocationMap from '../../library/map/LocationMap.astro';
+interface Props {
+  /** Where public/demo/ is served. The gallery uses /demo/; the website passes /elements-demo/. */
+  assetBase?: string;
+}
+const { assetBase = '/demo/' } = Astro.props;
+const asset = (name: string) => assetBase + name;
+---
+<div class="demo-map">
+  <p class="demo-map__label">One location, map beside the details</p>
+  <LocationMap
+    layout="split"
+    embed
+    zoom={15}
+    locations={[
+      {
+        name: 'Millennium Park',
+        address: ['201 E Randolph St', 'Chicago, IL 60602'],
+        hours: 'Open daily, 6 AM to 11 PM',
+        query: 'Millennium Park, 201 E Randolph St, Chicago, IL 60602',
+      },
+    ]}
+  />
+
+  <p class="demo-map__label">Several locations, one card each</p>
+  <LocationMap
+    embed
+    locations={[
+      {
+        name: 'Navy Pier',
+        address: ['600 E Grand Ave', 'Chicago, IL 60611'],
+        phone: '(312) 555-0142',
+        photo: asset('hills.svg'),
+      },
+      {
+        name: 'Garfield Park Conservatory',
+        address: ['300 N Central Park Ave', 'Chicago, IL 60624'],
+        embed: false,
+      },
+    ]}
+  />
+  <p class="demo-map__note">
+    The second card has no map, just the links. The phone number is a 555 number, reserved for
+    fiction.
+  </p>
+</div>
+<style>
+  .demo-map {
+    --map-accent: var(--purple, #5933d8);
+    --map-focus: var(--purple, #5933d8);
+    --map-pin: var(--purple, #5933d8);
+    --map-link: var(--purple-dark, #4a2bb8);
+    --map-text: var(--ink, #1e283c);
+    --map-border: var(--line, #d5dae6);
+    --map-radius: var(--radius, 14px);
+    display: grid;
+    gap: 0.75rem;
+  }
+  .demo-map__label {
+    margin: 0.5rem 0 0;
+    font-weight: 700;
+  }
+  .demo-map__label:not(:first-child) {
+    margin-top: 2rem;
+  }
+  .demo-map__note {
+    margin: 0;
+    font-size: 0.9em;
+  }
+</style>
diff --git a/src/components/demos/index.ts b/src/components/demos/index.ts
index c194713..092a9fa 100644
--- a/src/components/demos/index.ts
+++ b/src/components/demos/index.ts
@@ -31,6 +31,7 @@ import AnimatedBackgroundDemo from './AnimatedBackgroundDemo.astro';
 import ModalDemo from './ModalDemo.astro';
 import AnnouncementBarDemo from './AnnouncementBarDemo.astro';
 import VideoGalleryDemo from './VideoGalleryDemo.astro';
+import MapDemo from './MapDemo.astro';
 
 // Astro components have no exported public type; this is the shape both callers need.
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -60,4 +61,5 @@ export const demos: Record<string, AstroComponent> = {
   modal: ModalDemo,
   'announcement-bar': AnnouncementBarDemo,
   'video-gallery': VideoGalleryDemo,
+  map: MapDemo,
 };
diff --git a/src/data/catalog.ts b/src/data/catalog.ts
index e26cab4..dc309df 100644
--- a/src/data/catalog.ts
+++ b/src/data/catalog.ts
@@ -1506,6 +1506,78 @@ import { analytics } from '../data/site';
     file: 'src/library/video-gallery/VideoGallery.astro',
     added: '2026-09-26',
   },
+  {
+    id: 'map',
+    name: 'Map and directions',
+    aka: ['UABB Google Map', 'PowerPack Google Map', 'Elementor Google Maps', 'WP Google Maps', 'Google Maps embed', 'store locator', 'location card', 'get directions button'],
+    summary:
+      'A card per location with the address, phone and an optional hours line, “Open in Google Maps” and “Directions” links, and an optional map that loads from Google only when someone presses “Show the map”. No API key, and nothing from Google at page load.',
+    pitch: 'Show people where you are and get them there in one tap, without a Google script on every page.',
+    // SE Ranking US, 2026-09-26: google map embed code for website 170/mo, difficulty 35;
+    // google maps embed 590/41; google maps directions link 390/34; google maps link 320/20.
+    // The round-3 note's "map embed without api key" (and "google map embed without api key")
+    // have no data. "store locator" 2,400/65 is a different product (search by distance) and
+    // stays an aka.
+    search: { query: 'google map embed code for website', alsoRanks: ['google maps embed', 'google maps directions link', 'google maps link'] },
+    replaces: ['UABB / PowerPack “Google Map” modules (Beaver Builder)', 'Elementor’s Google Maps widget', 'WP Google Maps and similar plugins', 'a Google Maps <iframe> pasted into the footer'],
+    goodFor: 'A contact or visit page, a footer with the address, several branches each with its own card. Anywhere the question is “where is it and how do I get there”.',
+    notFor:
+      'A styled, branded or interactive map: custom colours, your own markers, clustering, a store locator that searches by distance. That needs the Google Maps JavaScript API, which needs an API key and a billing account, loads Google’s script on every visit, and adds Google’s map origins to the site’s CSP and consent policy; quote it as its own piece of work. Full opening hours are business-hours, which also owns the LocalBusiness structured data.',
+    props: [
+      { name: 'locations', type: '{ name, address, phone?, hours?, query?, photo?, embed? }[]', note: 'Required. `address` is its lines, as on an envelope. `query` is what Google searches for, by default the address; give “Business name, address” when Google knows the business, so its place card opens. `photo` is the facade image for the embed. `embed` overrides the element’s for this card.' },
+      { name: 'embed', type: 'boolean', default: 'false', note: 'Offer the click-to-load map on each card. Off, the cards are links only.' },
+      { name: 'zoom', type: 'number (1–21)', default: 'Google’s choice', note: 'Zoom of the embedded map: 15 is a neighbourhood, 18 a street.' },
+      { name: 'layout', type: "'stack' | 'split'", default: "'stack'", note: 'Stack: the map above the details, cards in a grid. Split: the map beside the details when there is room, one card per row.' },
+      { name: 'titleTag', type: "'h2' | 'h3' | 'h4'", default: "'h3'", note: 'Element for each card’s name.' },
+      { name: 'openLabel / directionsLabel / showLabel / notice', type: 'string', default: '“Open in Google Maps” / “Directions” / “Show the map” / “Loads a map from Google.”', note: 'Words, for a non-English site.' },
+      { name: 'class', type: 'string', note: 'Class on the wrapper, for the host to theme it.' },
+    ],
+    theming: [
+      { name: '--map-min', fallback: '18rem', note: 'Narrowest card before the list drops a column.' },
+      { name: '--map-gap', fallback: '1.25rem', note: 'Gap between cards.' },
+      { name: '--map-surface', fallback: '#fff', note: 'Card background, and the “Show the map” pill.' },
+      { name: '--map-text', fallback: '#1e283c', note: 'Card text (14.75:1 on the fallback surface).' },
+      { name: '--map-border', fallback: '#d5dae6', note: 'Card outline.' },
+      { name: '--map-radius', fallback: '0.75rem', note: 'Corners of cards and buttons.' },
+      { name: '--map-accent', fallback: '#5933d8', note: '“Open in Google Maps” button fill.' },
+      { name: '--map-on-accent', fallback: '#fff', note: 'Its text. Keep 4.5:1 against --map-accent (the fallbacks are 7.27:1; `npm run check` computes them).' },
+      { name: '--map-link', fallback: '#4a2bb8', note: '“Directions” and the phone number.' },
+      { name: '--map-aspect', fallback: '16 / 10', note: 'The map’s width / height.' },
+      { name: '--map-panel', fallback: '#e9ecf3', note: 'The neutral facade (no photo).' },
+      { name: '--map-panel-line', fallback: '#d3d8e4', note: 'Its street lines.' },
+      { name: '--map-pin', fallback: '#5933d8', note: 'The pin on the neutral facade.' },
+      { name: '--map-focus', fallback: '#5933d8', note: 'Focus rings.' },
+      { name: '--map-notice', fallback: '#4b5468', note: 'The “Loads a map from Google.” line.' },
+    ],
+    a11y: [
+      'Each address is an <address> under the location’s heading; the phone number is a tel: link.',
+      'The links name their place for a screen reader (“Open in Google Maps: Navy Pier”, “Directions to Navy Pier”), so a list of links still makes sense. Both are at least 44px tall.',
+      'The facade is a real <button> named “Show the map of <name>”, described by the visible notice “Loads a map from Google.”, so nobody loads a third party without being told. Pressed, it becomes an <iframe> titled “Map of <name>” and focus moves into it.',
+      'Nothing moves except the button’s pill growing slightly on hover, which prefers-reduced-motion removes.',
+      'Without JavaScript the cards and their links are all there, and the facade is not shown: a button that could not work is not rendered.',
+    ],
+    usage: `---
+import LocationMap from '../components/LocationMap.astro';   // not "Map": that would shadow JavaScript's Map
+---
+<LocationMap
+  embed
+  locations={[{
+    name: 'The Garden Shop',
+    address: ['123 Main St', 'Springfield, IL 62701'],
+    phone: '(217) 555-0100',
+    hours: 'Open daily, 8 AM to 6 PM',
+    query: 'The Garden Shop, 123 Main St, Springfield, IL 62701',
+    photo: '/images/storefront.webp',
+  }]}
+  layout="split"
+/>
+<!-- _headers: the embed needs frame-src https://www.google.com in the site's CSP; the links need nothing. -->`,
+    license:
+      'No API key and no Google account are involved. The links are Google’s public Maps URLs, and the map you choose to load is Google’s own embed, shown under Google’s terms with its attribution inside the frame. The pin on the plain facade is Font Awesome Free (CC BY 4.0).',
+    usedOn: [{ site: 'superherotech.ai', where: '/elements/map/ (demo)' }],
+    file: 'src/library/map/LocationMap.astro',
+    added: '2026-09-26',
+  },
 ];
 
 export const byId = (id: string) => catalog.find((e) => e.id === id);
diff --git a/src/library/map/LocationMap.astro b/src/library/map/LocationMap.astro
new file mode 100644
index 0000000..57d9298
--- /dev/null
+++ b/src/library/map/LocationMap.astro
@@ -0,0 +1,435 @@
+---
+/**
+ * LocationMap (the `map` element) — where to find you: one card per location with the address, phone, an optional hours
+ * line, and "Open in Google Maps" and "Directions" links, plus an optional map that loads only
+ * when someone asks for it. WordPress calls it UABB's or PowerPack's "Google Map" module,
+ * Elementor's Google Maps widget, WP Google Maps or a pasted Google Maps <iframe>.
+ *
+ * Why this is NOT the Google Maps JavaScript API: the API needs a key (a billing account, and a
+ * secret to restrict per domain), loads Google's script on every visit whether or not anyone
+ * looks at the map, and adds maps.googleapis.com and maps.gstatic.com to every client's CSP and
+ * consent policy. A styled, branded, interactive map needs exactly that, and is the one thing
+ * this element does not do (see the catalogue's notFor). Everything else people use a map for
+ * — "where is it" and "how do I get there" — is two links, which open the Maps app on a phone.
+ *
+ * The links (Google's documented Maps URLs, no key):
+ *   Open in Google Maps   https://www.google.com/maps/search/?api=1&query=<query>
+ *   Directions            https://www.google.com/maps/dir/?api=1&destination=<query>
+ * `query` is what to search for; by default the address lines joined with commas. Give the
+ * business name plus address when Google knows the business, so its place card opens.
+ *
+ * The click-to-load embed (`embed`): a facade — the location's `photo`, or a neutral panel with
+ * Font Awesome Free's map pin — that is a real <button> named "Show the map of <name>" and
+ * described by the one-line notice under it, "Loads a map from Google." Nothing is requested
+ * from Google until it is pressed. Then the button is replaced by
+ *   <iframe src="https://www.google.com/maps?q=<query>&output=embed" loading="lazy" title="Map of <name>">
+ * (no key needed for this URL), and focus moves into the map. A client's CSP needs
+ * `frame-src https://www.google.com` for it; nothing else.
+ *
+ * Without JavaScript: the cards and their links, no facade (a button that could not work is
+ * not rendered visible). The one-line script after the element shows the facades before the
+ * first paint, so nothing shifts.
+ *
+ * Out of scope on purpose: LocalBusiness JSON-LD. business-hours owns it (its `jsonLd` prop),
+ * and two elements emitting it for one business would contradict each other.
+ *
+ * The pin is read at build from `@fortawesome/fontawesome-free` (a devDependency, as for the
+ * icon element), only when a card has an embed without a photo. A site that copies this file
+ * without that package can set PIN below to the one `d` from svgs/solid/location-dot.svg.
+ *
+ * Theming, from the host's tokens (each has a fallback):
+ *   --map-min           narrowest card before the list drops a column  (18rem)
+ *   --map-gap           gap between cards                              (1.25rem)
+ *   --map-surface / --map-text / --map-border   the card               (#fff / #1e283c / #d5dae6)
+ *   --map-radius        corners of cards, media and buttons            (0.75rem)
+ *   --map-accent / --map-on-accent   "Open in Google Maps" button      (#5933d8 / #fff)
+ *   --map-link          "Directions" and the phone link                (#4a2bb8)
+ *   --map-aspect        the map's width / height                       (16 / 10)
+ *   --map-panel / --map-panel-line   the neutral facade and its streets (#e9ecf3 / #d3d8e4)
+ *   --map-pin           the pin on the neutral facade                  (#5933d8)
+ *   --map-focus         focus rings                                    (#5933d8)
+ *   --map-notice        the "Loads a map from Google." line            (#4b5468)
+ */
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export interface MapLocation {
+  /** The place's name: the card's heading, and the map's title. */
+  name: string;
+  /** Address lines, as on an envelope. */
+  address: string[];
+  /** Shown as a tel: link. */
+  phone?: string;
+  /** One line, e.g. "Open daily, 8 AM to 6 PM". For full opening hours use business-hours. */
+  hours?: string;
+  /** What Google should search for. Default: the address lines joined with commas. */
+  query?: string;
+  /** The facade image for the embed, served by your site. Default: a neutral panel with a pin. */
+  photo?: string;
+  /** Override the element's `embed` for this card. */
+  embed?: boolean;
+}
+interface Props {
+  locations: MapLocation[];
+  /** Offer the click-to-load Google map on each card. Default false: links only. */
+  embed?: boolean;
+  /** Zoom of the embedded map, 1 (world) to 21 (building). Default: Google's choice. */
+  zoom?: number;
+  /** 'stack' puts the map above the details; 'split' puts them side by side when there is room. */
+  layout?: 'stack' | 'split';
+  /** Element for each card's name. Default 'h3'. */
+  titleTag?: 'h2' | 'h3' | 'h4';
+  /** Words, for a non-English site. */
+  openLabel?: string;
+  directionsLabel?: string;
+  showLabel?: string;
+  notice?: string;
+  class?: string;
+}
+
+// <map-urls>
+/** Google's documented Maps URLs. None needs an API key. */
+function mapUrls(query: string, zoom?: number) {
+  const q = encodeURIComponent(query.trim().replace(/\s+/g, ' '));
+  return {
+    open: `https://www.google.com/maps/search/?api=1&query=${q}`,
+    directions: `https://www.google.com/maps/dir/?api=1&destination=${q}`,
+    embed: `https://www.google.com/maps?q=${q}${zoom ? `&z=${Math.round(zoom)}` : ''}&output=embed`,
+  };
+}
+/** A phone number as a tel: URL: the digits, and a leading + if there is one. */
+function telHref(phone: string): string {
+  const p = phone.trim();
+  return `tel:${p.startsWith('+') ? '+' : ''}${p.replace(/\D/g, '')}`;
+}
+// </map-urls>
+
+const {
+  locations,
+  embed = false,
+  zoom,
+  layout = 'stack',
+  titleTag = 'h3',
+  openLabel = 'Open in Google Maps',
+  directionsLabel = 'Directions',
+  showLabel = 'Show the map',
+  notice = 'Loads a map from Google.',
+  class: className,
+} = Astro.props;
+
+if (!Array.isArray(locations) || !locations.length) throw new Error('Map: `locations` needs at least one { name, address }.');
+if (layout !== 'stack' && layout !== 'split') throw new Error(`Map: layout "${layout}" is not 'stack' or 'split'.`);
+if (zoom !== undefined && !(Number.isFinite(zoom) && zoom >= 1 && zoom <= 21)) throw new Error(`Map: zoom must be 1 to 21, not ${zoom}.`);
+
+const locals = Astro.locals as Record<string, unknown>;
+const firstOnPage = !locals.__mapScript;
+locals.__mapScript = true;
+const n = ((locals.__mapCount as number) ?? 0) + 1;
+locals.__mapCount = n;
+
+const cards = locations.map((l, i) => {
+  const name = String(l?.name ?? '').trim();
+  if (!name) throw new Error(`Map: location ${i + 1} has no \`name\`.`);
+  const lines = (Array.isArray(l.address) ? l.address : [l.address]).map((s) => String(s ?? '').trim()).filter(Boolean);
+  if (!lines.length) throw new Error(`Map "${name}": \`address\` needs at least one line.`);
+  const query = (l.query ?? lines.join(', ')).trim();
+  const phone = l.phone?.trim();
+  if (phone && telHref(phone).replace(/\D/g, '').length < 7) throw new Error(`Map "${name}": phone "${phone}" has too few digits for a tel: link.`);
+  return {
+    name,
+    lines,
+    phone,
+    tel: phone ? telHref(phone) : undefined,
+    hours: l.hours,
+    photo: l.photo,
+    embed: l.embed ?? embed,
+    urls: mapUrls(query, zoom),
+    id: `map-${n}-${i + 1}`,
+  };
+});
+
+// Font Awesome Free's location-dot, read at build like the icon element does, and only when a
+// neutral facade needs it.
+let PIN: { viewBox: string; d: string } | null = null;
+if (cards.some((c) => c.embed && !c.photo)) {
+  const require = createRequire(import.meta.url);
+  const fa = dirname(require.resolve('@fortawesome/fontawesome-free/package.json'));
+  const svg = readFileSync(join(fa, 'svgs/solid/location-dot.svg'), 'utf8');
+  PIN = { viewBox: (svg.match(/\sviewBox="([^"]+)"/) || [])[1] ?? '0 0 384 512', d: (svg.match(/<path[^>]*\sd="([^"]+)"/) || [])[1] ?? '' };
+}
+
+const Title = titleTag;
+const List = cards.length > 1 ? 'ul' : 'div';
+const Item = cards.length > 1 ? 'li' : 'div';
+---
+
+{
+  firstOnPage && (
+    <script is:inline>
+      (() => {
+        if (window.__superheroMap) return;
+        const mount = (root) => {
+          if (!root || root.dataset.mapReady) return;
+          root.dataset.mapReady = '1';
+          // The facades are ours only once this runs; without it the links do the job.
+          root.querySelectorAll('[data-map-media]').forEach((m) => (m.hidden = false));
+          root.addEventListener('click', (e) => {
+            const btn = e.target.closest('[data-map-load]');
+            if (!btn) return;
+            const f = document.createElement('iframe');
+            f.src = btn.dataset.mapLoad;
+            f.title = btn.dataset.mapTitle;
+            f.loading = 'lazy';
+            f.allowFullscreen = true;
+            // Google's own embed code sends the referrer this way.
+            f.referrerPolicy = 'no-referrer-when-downgrade';
+            const media = btn.closest('[data-map-media]');
+            btn.replaceWith(f);
+            media.dataset.mapLoaded = '';
+            f.focus();
+          });
+        };
+        window.__superheroMap = { mount };
+      })();
+    </script>
+  )
+}
+<div class:list={['map', `map--${layout}`, className]} data-map>
+  <List class="map__list" role={List === 'ul' ? 'list' : undefined}>
+    {
+      cards.map((c) => (
+        <Item class="map__card">
+          {c.embed && (
+            <div class="map__media" hidden data-map-media>
+              <button
+                class="map__load"
+                type="button"
+                aria-label={`${showLabel} of ${c.name}`}
+                aria-describedby={`${c.id}-notice`}
+                data-map-load={c.urls.embed}
+                data-map-title={`Map of ${c.name}`}
+              >
+                {c.photo ? (
+                  <img class="map__photo" src={c.photo} alt="" loading="lazy" decoding="async" />
+                ) : (
+                  <span class="map__panel" aria-hidden="true">
+                    <svg class="map__pin" viewBox={PIN!.viewBox} width="1em" height="1em" focusable="false">
+                      <path fill="currentColor" d={PIN!.d} />
+                    </svg>
+                  </span>
+                )}
+                <span class="map__cta">{showLabel}</span>
+              </button>
+              <p class="map__notice" id={`${c.id}-notice`}>{notice}</p>
+            </div>
+          )}
+          <div class="map__body">
+            <Title class="map__name">{c.name}</Title>
+            <address class="map__address">
+              {c.lines.map((line, i) => (
+                <>
+                  {line}
+                  {i < c.lines.length - 1 && <br />}
+                </>
+              ))}
+              {c.phone && (
+                <>
+                  <br />
+                  <a class="map__tel" href={c.tel}>{c.phone}</a>
+                </>
+              )}
+            </address>
+            {c.hours && <p class="map__hours">{c.hours}</p>}
+            <p class="map__actions">
+              {/* Named with the place, starting with the visible words (WCAG 2.5.3), so a list of links still makes sense. */}
+              <a class="map__btn map__btn--primary" href={c.urls.open} aria-label={`${openLabel}: ${c.name}`} data-map-open>
+                {openLabel}
+              </a>
+              <a class="map__btn" href={c.urls.directions} aria-label={`${directionsLabel} to ${c.name}`} data-map-directions>
+                {directionsLabel}
+              </a>
+            </p>
+          </div>
+        </Item>
+      ))
+    }
+  </List>
+</div>
+<script is:inline>window.__superheroMap.mount(document.currentScript.previousElementSibling);</script>
+
+<style>
+  .map__list {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(min(100%, var(--map-min, 18rem)), 1fr));
+    gap: var(--map-gap, 1.25rem);
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+  .map--split .map__list {
+    grid-template-columns: minmax(0, 1fr);
+  }
+  .map__card {
+    display: grid;
+    align-content: start;
+    min-width: 0;
+    margin: 0;
+    overflow: hidden;
+    border: 1px solid var(--map-border, #d5dae6);
+    border-radius: var(--map-radius, 0.75rem);
+    background: var(--map-surface, #fff);
+    color: var(--map-text, #1e283c);
+  }
+  /* Split: the map and the details side by side once each has 18rem; stacked below that. */
+  .map--split .map__card {
+    grid-template-columns: repeat(auto-fit, minmax(min(100%, 18rem), 1fr));
+  }
+  .map__media {
+    display: grid;
+    grid-template-rows: 1fr auto;
+    min-width: 0;
+  }
+  .map__media[hidden] {
+    display: none;
+  }
+  .map__load,
+  .map__media > :global(iframe) {
+    display: block;
+    width: 100%;
+    aspect-ratio: var(--map-aspect, 16 / 10);
+    height: auto;
+    border: 0;
+  }
+  .map--split .map__load,
+  .map--split .map__media > :global(iframe) {
+    height: 100%;
+    min-height: 14rem;
+  }
+  .map__load {
+    position: relative;
+    display: grid;
+    place-items: center;
+    padding: 0;
+    overflow: hidden;
+    background: var(--map-panel, #e9ecf3);
+    color: inherit;
+    font: inherit;
+    cursor: pointer;
+  }
+  .map__load:focus-visible {
+    outline: 3px solid var(--map-focus, #5933d8);
+    outline-offset: -3px;
+  }
+  .map__photo,
+  .map__panel {
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+  }
+  .map__photo {
+    object-fit: cover;
+  }
+  /* A neutral street grid, drawn in CSS: never a Google static map, which needs a key too. */
+  .map__panel {
+    display: grid;
+    place-items: center;
+    background:
+      linear-gradient(115deg, transparent 47%, var(--map-panel-line, #d3d8e4) 47% 53%, transparent 53%),
+      repeating-linear-gradient(0deg, transparent 0 2.2rem, var(--map-panel-line, #d3d8e4) 2.2rem 2.5rem),
+      repeating-linear-gradient(90deg, transparent 0 3.1rem, var(--map-panel-line, #d3d8e4) 3.1rem 3.4rem),
+      var(--map-panel, #e9ecf3);
+  }
+  .map__pin {
+    translate: 0 -40%;
+    color: var(--map-pin, #5933d8);
+    font-size: 2.75rem;
+    filter: drop-shadow(0 0.2rem 0.3rem rgb(0 0 0 / 0.25));
+  }
+  .map__cta {
+    position: absolute;
+    bottom: 0.75rem;
+    left: 50%;
+    translate: -50% 0;
+    padding: 0.5rem 1rem;
+    border-radius: 999px;
+    background: var(--map-surface, #fff);
+    color: var(--map-text, #1e283c);
+    font-weight: 600;
+    white-space: nowrap;
+    box-shadow: 0 0.25rem 1rem rgb(0 0 0 / 0.2);
+  }
+  @media (prefers-reduced-motion: no-preference) {
+    .map__cta {
+      transition: scale 0.18s ease;
+    }
+    .map__load:hover .map__cta,
+    .map__load:focus-visible .map__cta {
+      scale: 1.05;
+    }
+  }
+  .map__notice {
+    margin: 0;
+    padding: 0.4rem 1rem;
+    color: var(--map-notice, #4b5468);
+    font-size: 0.85em;
+  }
+  .map__body {
+    min-width: 0;
+    padding: 1rem 1.25rem 1.25rem;
+  }
+  .map__name {
+    margin: 0 0 0.5rem;
+    font-size: 1.15rem;
+    line-height: 1.3;
+  }
+  .map__address {
+    margin: 0;
+    font-style: normal;
+    line-height: 1.5;
+    overflow-wrap: anywhere;
+  }
+  .map__hours {
+    margin: 0.5rem 0 0;
+  }
+  .map__tel {
+    color: var(--map-link, #4a2bb8);
+  }
+  .map__actions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+    margin: 1rem 0 0;
+  }
+  .map__btn {
+    display: inline-block;
+    box-sizing: border-box;
+    min-height: 2.75rem;
+    padding: 0.55rem 1rem;
+    line-height: 1.4;
+    border: 1.5px solid currentColor;
+    border-radius: var(--map-radius, 0.75rem);
+    color: var(--map-link, #4a2bb8);
+    font-weight: 600;
+    text-decoration: none;
+  }
+  .map__btn--primary {
+    border-color: var(--map-accent, #5933d8);
+    background: var(--map-accent, #5933d8);
+    color: var(--map-on-accent, #fff);
+  }
+  .map__btn:hover {
+    text-decoration: underline;
+  }
+  .map__btn:focus-visible,
+  .map__tel:focus-visible {
+    outline: 3px solid var(--map-focus, #5933d8);
+    outline-offset: 2px;
+  }
+  @media print {
+    .map__media {
+      display: none !important;
+    }
+  }
+</style>

From b0f3a7596c23861b0b29ecd1f03b633413fb3e69 Mon Sep 17 00:00:00 2001
From: Warren <warreng@ecropolis.com>
Date: Sat, 26 Sep 2026 11:39:25 -0500
Subject: [PATCH 3/3] link-effects: eleven hover-and-focus styles for links,
 CSS only

underline-slide, underline-grow, brackets, highlight, box,
strike-to-underline, arrow, circle, and three of ours: peek (the link's
data-peek words slide in, width kept so nothing shifts), swash (an inline SVG
underline drawn by stroke-dashoffset) and tag (a pill that fills, the text
turning with it). Classes on any <a> (lk-<effect>), or this same file as a
<Link effect> wrapper; <LinkEffects /> emits the stylesheet once per page
through an Astro.locals guard.

Every effect is one `:is(:hover, :focus-visible)` rule, keeps the focus ring,
and has its transitions only under prefers-reduced-motion: no-preference.
Text colour is never transitioned: highlight pins --lk-ink, and tag paints
text and fill as two layers of one background moved by one
background-position, so each pixel of text is a passing pair mid-sweep.

check-media-and-links computes the fallback pairs (14.75, 11.68, 7.27 and
7.27 to 1), pins the rules above and the demo page, with 13 more mutations.

Search: "underline animation css" 590/mo, difficulty 20 (SE Ranking US,
2026-09-26); "link hover effects" is 90/30.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 scripts/check-media-and-links.mjs          | 120 ++++++-
 src/components/demos/LinkEffectsDemo.astro |  98 +++++
 src/components/demos/index.ts              |   2 +
 src/data/catalog.ts                        |  60 ++++
 src/library/link-effects/LinkEffects.astro | 399 +++++++++++++++++++++
 5 files changed, 678 insertions(+), 1 deletion(-)
 create mode 100644 src/components/demos/LinkEffectsDemo.astro
 create mode 100644 src/library/link-effects/LinkEffects.astro

diff --git a/scripts/check-media-and-links.mjs b/scripts/check-media-and-links.mjs
index a2b2d0f..d3a25c3 100644
--- a/scripts/check-media-and-links.mjs
+++ b/scripts/check-media-and-links.mjs
@@ -36,6 +36,19 @@
  * 6. The fallback colours pass 4.5:1 (text, links, notice on the card; the button's text on
  *    its fill); motion only under no-preference.
  *
+ * link-effects
+ * 7. The stylesheet (the `<style is:inline data-lk>` in the component): every one of the eleven
+ *    effects has an `a.lk-<effect>:is(:hover, :focus-visible)` rule and no `:hover` stands
+ *    without `:focus-visible`; no transition or animation outside no-preference; no
+ *    transition of `color` or `-webkit-text-fill-color`; the focus ring is never removed;
+ *    decorative `content` has an empty alternative (`/ ''`); highlight pins its text colour;
+ *    tag paints text and fill as two layers of one background (the sweep that keeps contrast).
+ * 8. Contrast, from the fallbacks: ink on the page and on the marker, on-accent on the accent,
+ *    the accent on the page (the arrow and peek words are text). All 4.5:1 or more.
+ * 9. Built pages: the stylesheet once per page; the demo shows all eleven with their class
+ *    names; swash's SVG is aria-hidden with pathLength="1"; peek has data-peek and its label
+ *    span; no script anywhere in the demo (CSS only, so the no-JS render is the render).
+ *
  * Mutation tests: each element's checks are also run against deliberately broken copies of its
  * input (an iframe injected, a name removed, a colour darkened, …). A mutation the checks do
  * not catch fails the run: a check that cannot fail is not a check.
@@ -466,4 +479,109 @@ checkMapStyle(mapSrc, fail, mapContrast);
 }
 finish('map');
 
-console.log(`check-media-and-links ok: ${pages.length} built pages load nothing from Google, YouTube or Vimeo; video-gallery parser is video-player's, its no-JS render and ARIA hold on 2 pages; map URLs, facades and links hold on 2 pages, contrast ${mapContrast.join(', ')}; ${mutations} mutations caught.`);
+// ------------------------------------------------------------- link-effects
+const LK = 'src/library/link-effects/LinkEffects.astro';
+const lkSrc = src(LK);
+const lkList = block(lkSrc, 'link-effects-list');
+const EFFECTS = lkList ? [...lkList.matchAll(/'([a-z-]+)'/g)].map((m) => m[1]) : [];
+if (EFFECTS.length !== 11) fail(`${LK}: expected the eleven effects in the \`<link-effects-list>\` block, found ${EFFECTS.length}.`);
+finish('link-effects list');
+const lkContrast = [];
+const checkLinkCss = (component, fail, report) => {
+  const css = (component.match(/<style is:inline data-lk>([\s\S]*?)<\/style>/) || [])[1]?.replace(/\/\*[\s\S]*?\*\//g, '');
+  if (!css) {
+    fail(`${LK}: no \`<style is:inline data-lk>\` stylesheet.`);
+    return;
+  }
+  const sel = (e) => `a.lk-${e}:is(:hover, :focus-visible)`;
+  for (const e of EFFECTS) if (!css.includes(sel(e))) fail(`${LK}: no \`${sel(e)}\` rule; every effect must fire on focus exactly as on hover.`);
+  const bare = css.replace(/:is\(:hover, :focus-visible\)/g, '');
+  if (/:hover/.test(bare)) fail(`${LK}: a :hover without :focus-visible; keyboard users would not see it.`);
+  if (/outline(?:-style)?\s*:\s*(?:none|0)\b/.test(css)) fail(`${LK}: removes the focus ring.`);
+  const rest = outsideNoPreference(css);
+  if (/\b(?:animation|transition)(?:-[a-z]+)?\s*:/.test(rest.replace(/transition-delay\s*:[^;]*;/g, ''))) fail(`${LK}: a transition or animation outside @media (prefers-reduced-motion: no-preference); reduced motion must show the end state at once.`);
+  for (const [, v] of css.matchAll(/transition(?:-property)?\s*:([^;]*);/g)) {
+    if (/(?<![-\w])color\b|text-fill-color/.test(v)) fail(`${LK}: transitions a text colour (${v.trim().slice(0, 60)}); animate decorations, not the text.`);
+  }
+  for (const m of css.matchAll(/content:\s*'([^']+)';(?!\s*content:\s*'\1'\s*\/\s*'')/g)) fail(`${LK}: decorative content '${m[1]}' has no empty alternative (\`content: '${m[1]}' / ''\`), so a screen reader reads it.`);
+  if (!/a\.lk-highlight \{\s*color: var\(--lk-ink, #[0-9a-f]+\);/i.test(css) || !/a\.lk-highlight:is\(:hover, :focus-visible\) \{\s*color: var\(--lk-ink, #[0-9a-f]+\);/i.test(css)) {
+    fail(`${LK}: highlight must pin its text colour to --lk-ink at rest and when active (a host's a:hover must not recolour it over the marker).`);
+  }
+  const tag = css.match(/@supports \(\(background-clip: text\)[^{]*\{\s*a\.lk-tag \{([\s\S]*?)\}\s*a\.lk-tag:is\(:hover, :focus-visible\) \{([\s\S]*?)\}/);
+  if (!tag) fail(`${LK}: the tag sweep (text and fill as two layers of one background) is missing.`);
+  else {
+    const [, base, hover] = tag;
+    const grads = [...base.matchAll(/linear-gradient\(90deg, var\((--lk-[\w-]+), #[0-9a-f]+\) 50%, var\((--lk-[\w-]+), #[0-9a-f]+\) 50%\)/gi)];
+    if (grads.length !== 2 || grads[0][1] !== '--lk-on-accent' || grads[0][2] !== '--lk-ink' || grads[1][1] !== '--lk-accent' || grads[1][2] !== '--lk-bg') fail(`${LK}: tag must layer (on-accent | ink) over (accent | bg), split at 50% in both.`);
+    if (!/background-clip: text, padding-box;/.test(base)) fail(`${LK}: tag's text layer must be clipped to the text and the fill to the padding box.`);
+    if (hover.replace(/\s/g, '') !== 'background-position:00;') fail(`${LK}: tag's hover may move only background-position, so text and fill stay in step.`);
+  }
+  const t = fallbacks(css, LK, fail);
+  pairs(
+    t,
+    [
+      ['--lk-ink', '--lk-bg', 4.5, 'ink on page'],
+      ['--lk-ink', '--lk-mark', 4.5, 'ink on marker'],
+      ['--lk-on-accent', '--lk-accent', 4.5, 'tag text on fill'],
+      ['--lk-accent', '--lk-bg', 4.5, 'accent text on page'],
+    ],
+    LK,
+    fail,
+    report,
+  );
+};
+checkLinkCss(lkSrc, fail, lkContrast);
+const checkLinkPage = ({ rel, html, demo }, fail) => {
+  const sheets = (html.match(/<style\b[^>]*\sdata-lk[\s>]/g) || []).length;
+  const links = [...html.matchAll(/<a\b[^>]*class="lk-([a-z-]+)[^"]*"[^>]*>([\s\S]*?)<\/a>/g)];
+  if (links.length && sheets !== 1) fail(`${rel}: the link-effects stylesheet is on the page ${sheets} times; it must be once.`);
+  for (const [tag, effect, inner] of links) {
+    if (!EFFECTS.includes(effect)) fail(`${rel}: a link with unknown effect lk-${effect}.`);
+    if (!attr(tag, 'href')) fail(`${rel}: an lk-${effect} link without href.`);
+    if (effect === 'peek') {
+      if (!decode(attr(tag, 'data-peek'))) fail(`${rel}: an lk-peek link without data-peek.`);
+      if (!/<span class="lk__label"/.test(inner)) fail(`${rel}: an lk-peek link without its <span class="lk__label">.`);
+    }
+    if (effect === 'swash') {
+      const svg = inner.match(/<svg\b[^>]*class="lk__swash"[^>]*>/);
+      if (!svg || attr(svg[0], 'aria-hidden') !== 'true' || attr(svg[0], 'focusable') !== 'false') fail(`${rel}: the swash SVG must be aria-hidden="true" focusable="false".`);
+      if (!/<path\b[^>]*pathLength="1"/.test(inner)) fail(`${rel}: the swash path needs pathLength="1" for its dash offset to draw it.`);
+    }
+  }
+  if (demo) {
+    const start = html.indexOf('id="link-effects-demo"');
+    const region = html.slice(start, html.indexOf('</div>', html.indexOf('demo-lk__prose', start)));
+    for (const e of EFFECTS) {
+      if (!new RegExp(`<a\\b[^>]*class="lk-${e}[" ]`).test(region)) fail(`${rel}: the demo does not show lk-${e}.`);
+      if (!new RegExp(`<code\\b[^>]*>lk-${e}</code>`).test(region)) fail(`${rel}: the demo does not show the class name lk-${e}.`);
+    }
+    if (/<script\b/.test(region)) fail(`${rel}: a script in the link-effects demo; the element is CSS only.`);
+  }
+};
+const lkPages = [
+  { rel: 'dist/link-effects/index.html', html: built('dist/link-effects/index.html'), demo: true },
+  { rel: 'dist/index.html', html: built('dist/index.html'), demo: false },
+];
+for (const p of lkPages) for (const m of run(checkLinkPage, p)) fail(m);
+{
+  const css = (f) => (x) => f(x);
+  const check = (s, f) => checkLinkCss(s, f);
+  mutate('circle loses :focus-visible', check, lkSrc, css((s) => s.replace('a.lk-circle:is(:hover, :focus-visible)::after', 'a.lk-circle:hover::after')));
+  mutate('a dark marker', check, lkSrc, css((s) => s.replaceAll('var(--lk-mark, #ffe38f)', 'var(--lk-mark, #6b5a1e)')));
+  mutate('a pale accent', check, lkSrc, css((s) => s.replaceAll('var(--lk-accent, #5933d8)', 'var(--lk-accent, #b7a6f2)')));
+  mutate('the text colour transitions', check, lkSrc, css((s) => s.replace('a.lk-tag {\n          transition: background-position', 'a.lk-tag {\n          transition: color 0.3s, background-position')));
+  mutate('a transition outside reduced motion', check, lkSrc, css((s) => s.replace('a.lk-circle {\n        padding: 0 0.15em;', 'a.lk-circle {\n        transition: scale 0.3s;\n        padding: 0 0.15em;')));
+  mutate('the focus ring removed', check, lkSrc, css((s) => s.replace('outline-offset: 0.3em;', 'outline: none;')));
+  mutate('the arrow is read aloud', check, lkSrc, css((s) => s.replace("content: '→' / '';", '')));
+  mutate('tag hover changes the text colour', check, lkSrc, css((s) => s.replace('a.lk-tag:is(:hover, :focus-visible) {\n          background-position: 0 0;', 'a.lk-tag:is(:hover, :focus-visible) {\n          background-position: 0 0;\n          color: #fff;')));
+  mutate('highlight lets a host recolour it on hover', check, lkSrc, css((s) => s.replace('a.lk-highlight:is(:hover, :focus-visible) {\n        color: var(--lk-ink, #1e283c);', 'a.lk-highlight:is(:hover, :focus-visible) {')));
+  const demo = lkPages[0];
+  const re = (a, b) => (x) => ({ ...x, html: x.html.replace(a, b) });
+  mutate('the swash SVG is announced', checkLinkPage, demo, re(/(class="lk__swash"[^>]*) aria-hidden="true"/, '$1'));
+  mutate('the stylesheet twice', checkLinkPage, demo, re('</body>', '<style data-lk>a{}</style></body>'));
+  mutate('the demo drops an effect', checkLinkPage, demo, re(/<code\b([^>]*)>lk-tag<\/code>/, '<code$1>tag</code>'));
+  mutate('peek without its words', checkLinkPage, demo, re(/ data-peek="[^"]*"/, ''));
+}
+finish('link-effects');
+
+console.log(`check-media-and-links ok: ${pages.length} built pages load nothing from Google, YouTube or Vimeo; video-gallery parser is video-player's, its no-JS render and ARIA hold on 2 pages; map URLs, facades and links hold on 2 pages, contrast ${mapContrast.join(', ')}; link-effects: ${EFFECTS.length} effects on hover and focus, contrast ${lkContrast.join(', ')}; ${mutations} mutations caught.`);
diff --git a/src/components/demos/LinkEffectsDemo.astro b/src/components/demos/LinkEffectsDemo.astro
new file mode 100644
index 0000000..b803259
--- /dev/null
+++ b/src/components/demos/LinkEffectsDemo.astro
@@ -0,0 +1,98 @@
+---
+/**
+ * Demo for `link-effects`. The website renders this too (see README, "Consumed by
+ * superherotech.ai"); it has no assets, and every host token has a fallback.
+ *
+ * All eleven effects, each with its class name, through the `<Link>` wrapper (the same file as
+ * `<LinkEffects>`). Hover one, or Tab to it: focus shows the same effect. The links point at
+ * this demo, so following one goes nowhere.
+ */
+import LinkEffects from '../../library/link-effects/LinkEffects.astro';
+import Link from '../../library/link-effects/LinkEffects.astro';
+interface Props {
+  /** Where public/demo/ is served. The gallery uses /demo/; the website passes /elements-demo/. */
+  assetBase?: string;
+}
+const href = '#link-effects-demo';
+const effects = [
+  { effect: 'underline-slide', label: 'About us', note: 'In from the left, out to the right.' },
+  { effect: 'underline-grow', label: 'Read the guide', note: 'Underlined at rest, so it works in a paragraph.' },
+  { effect: 'brackets', label: 'Services', note: 'Brackets close in.' },
+  { effect: 'highlight', label: 'Book a visit', note: 'A marker sweeps behind the words.' },
+  { effect: 'box', label: 'Contact', note: 'A frame draws itself.' },
+  { effect: 'strike-to-underline', label: 'Old menu', note: 'Strikes through, then drops to an underline.' },
+  { effect: 'arrow', label: 'Next step', note: 'The arrow’s room is kept, so nothing moves.' },
+  { effect: 'circle', label: 'Sale', note: 'Ringed by hand.' },
+  { effect: 'peek', label: 'Pricing', peek: '$49/mo', note: 'Ours: the answer peeks in. data-peek="$49/mo".' },
+  { effect: 'swash', label: 'Our story', note: 'Ours: a hand-drawn line draws itself.' },
+  { effect: 'tag', label: 'New season', note: 'Ours: a pill fills, the text turning with it.' },
+] as const;
+---
+<LinkEffects />
+<div class="demo-lk" id="link-effects-demo">
+  <ul class="demo-lk__grid" role="list">
+    {
+      effects.map((e) => (
+        <li class="demo-lk__cell">
+          <p class="demo-lk__link">
+            {e.effect === 'peek' ? (
+              <Link effect="peek" peek={e.peek} href={href}>
+                {e.label}
+              </Link>
+            ) : (
+              <Link effect={e.effect} href={href}>
+                {e.label}
+              </Link>
+            )}
+          </p>
+          <code class="demo-lk__class">lk-{e.effect}</code>
+          <p class="demo-lk__note">{e.note}</p>
+        </li>
+      ))
+    }
+  </ul>
+  <p class="demo-lk__prose">
+    In running text, keep an underline at rest: this sentence links to <Link effect="underline-grow" href={href}>the
+    planting guide</Link>, which thickens on hover and on focus and wraps across lines like any other link.
+  </p>
+</div>
+<style>
+  .demo-lk {
+    --lk-accent: var(--purple, #5933d8);
+    --lk-ink: var(--ink, #1e283c);
+    --lk-bg: var(--white, #fff);
+  }
+  .demo-lk__grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(min(100%, 14rem), 1fr));
+    gap: 1rem;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+  .demo-lk__cell {
+    min-width: 0;
+    padding: 1.4rem 1.25rem 1rem;
+    border: 1px solid var(--line, #d5dae6);
+    border-radius: var(--radius, 14px);
+    background: var(--white, #fff);
+  }
+  .demo-lk__link {
+    margin: 0 0 1rem;
+    color: var(--ink, #1e283c);
+    font-size: 1.25rem;
+    font-weight: 600;
+  }
+  .demo-lk__class {
+    font-size: 0.85rem;
+  }
+  .demo-lk__note {
+    margin: 0.4rem 0 0;
+    font-size: 0.9rem;
+  }
+  .demo-lk__prose {
+    max-width: 38rem;
+    margin: 1.5rem 0 0;
+    color: var(--ink, #1e283c);
+  }
+</style>
diff --git a/src/components/demos/index.ts b/src/components/demos/index.ts
index 092a9fa..c258add 100644
--- a/src/components/demos/index.ts
+++ b/src/components/demos/index.ts
@@ -32,6 +32,7 @@ import ModalDemo from './ModalDemo.astro';
 import AnnouncementBarDemo from './AnnouncementBarDemo.astro';
 import VideoGalleryDemo from './VideoGalleryDemo.astro';
 import MapDemo from './MapDemo.astro';
+import LinkEffectsDemo from './LinkEffectsDemo.astro';
 
 // Astro components have no exported public type; this is the shape both callers need.
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -62,4 +63,5 @@ export const demos: Record<string, AstroComponent> = {
   'announcement-bar': AnnouncementBarDemo,
   'video-gallery': VideoGalleryDemo,
   map: MapDemo,
+  'link-effects': LinkEffectsDemo,
 };
diff --git a/src/data/catalog.ts b/src/data/catalog.ts
index dc309df..04ae021 100644
--- a/src/data/catalog.ts
+++ b/src/data/catalog.ts
@@ -1578,6 +1578,66 @@ import LocationMap from '../components/LocationMap.astro';   // not "Map": that
     file: 'src/library/map/LocationMap.astro',
     added: '2026-09-26',
   },
+  {
+    id: 'link-effects',
+    name: 'Link effects',
+    aka: ['UABB Creative Link', 'PowerPack Link Effects', 'creative link', 'underline animation', 'link hover effects', 'animated underline', 'text hover effects'],
+    summary:
+      'Eleven hover-and-focus styles for links, CSS only: underline-slide, underline-grow, brackets, highlight, box, strike-to-underline, arrow, circle, and three of ours, peek, swash and tag. A class on any <a>, or the <Link effect> wrapper. Focus shows what hover shows, reduced motion shows the end state at once, and the text never drops below 4.5:1 mid-animation.',
+    pitch: 'Links that answer back when you point at them, and never leave a keyboard user or a slow eye behind.',
+    // SE Ranking US, 2026-09-26: underline animation css 590/mo, difficulty 20; css link hover
+    // effects 110/26; link hover effects 90/30; css text hover effects 90/27. The round-3 note's
+    // "link hover effects" is the closest name but a sixth of the volume at a higher difficulty;
+    // five of the eleven effects are underlines, so the page leads with them. "css hover
+    // effects" 480/31 covers buttons and images too and stays unclaimed.
+    search: { query: 'underline animation css', alsoRanks: ['css link hover effects', 'link hover effects', 'css text hover effects'] },
+    replaces: ['UABB “Creative Link” (Beaver Builder)', 'PowerPack “Link Effects”', 'hover.css and underline snippets pasted into a theme'],
+    goodFor:
+      'Navigation, a card’s call to action, footer links, a “Read more”: short links that should feel alive. underline-grow also suits links in running text, because it is underlined at rest. peek suits a link whose destination has a one-word answer: “Pricing” → “$49/mo”, “Hours” → “Open now”.',
+    notFor:
+      'Links in a paragraph with any effect that has no underline at rest (all but underline-grow and peek): a link must look like a link before anyone points at it, and colour alone does not say so. Buttons, which are not links. More than one or two effects on a site: pick one for navigation and one for calls to action, and keep them.',
+    props: [
+      { name: 'effect', type: "'underline-slide' | 'underline-grow' | 'brackets' | 'highlight' | 'box' | 'strike-to-underline' | 'arrow' | 'circle' | 'peek' | 'swash' | 'tag'", note: 'With `href`, renders <a class="lk-<effect>">. Leave both out (<LinkEffects />) to emit only the stylesheet, once, e.g. in the layout.' },
+      { name: 'href', type: 'string', note: 'The link. Required with `effect`.' },
+      { name: 'peek', type: 'string', note: 'For effect="peek": the words that slide in, set as data-peek. Part of the link’s accessible name.' },
+      { name: 'class', type: 'string', note: 'More classes on the <a>.' },
+      { name: '…rest', type: '<a> attributes', note: 'Passed through: target, rel, aria-current, download.' },
+    ],
+    theming: [
+      { name: '--lk-accent', fallback: '#5933d8', note: 'Lines, brackets, frame, ring, swash, arrow and peek words, tag fill. Keep 4.5:1 against --lk-bg, since the arrow and peek words are text (the fallbacks are 7.27:1).' },
+      { name: '--lk-ink', fallback: '#1e283c', note: 'The text colour highlight and tag pin: 14.75:1 on --lk-bg and 11.68:1 on --lk-mark.' },
+      { name: '--lk-on-accent', fallback: '#fff', note: 'Tag text over its fill: 7.27:1 on --lk-accent.' },
+      { name: '--lk-mark', fallback: '#ffe38f', note: 'The highlight marker.' },
+      { name: '--lk-bg', fallback: '#fff', note: 'The page behind the links, and the tag’s resting fill. Set it to the section’s background so the check’s arithmetic matches.' },
+      { name: '--lk-thickness', fallback: '2px', note: 'Line weight.' },
+      { name: '--lk-duration', fallback: '0.3s', note: 'Length of each effect (swash takes 1.8×).' },
+      { name: '--lk-ease', fallback: 'cubic-bezier(0.2, 0.7, 0.2, 1)', note: 'Easing.' },
+    ],
+    a11y: [
+      'Every effect fires on :focus-visible exactly as on :hover (one selector, `:is(:hover, :focus-visible)`), and the browser’s own focus ring stays.',
+      'prefers-reduced-motion: every transition sits inside `(prefers-reduced-motion: no-preference)`, so otherwise the end state appears at once. Nothing plays by itself.',
+      'The text never drops below 4.5:1 mid-animation. Effects move decorations, not the text colour; highlight pins the text to --lk-ink, which passes on the page and on the marker; tag paints its text and fill as two layers of one background moving together, so each pixel of text is one passing pair or the other. `npm run check` computes the fallback pairs.',
+      'Decorative glyphs (the brackets, the arrow) are silent to screen readers, and the swash SVG is aria-hidden. The peek words are read as part of the link’s name (“Pricing $49/mo”).',
+      'Windows High Contrast (forced colours): system link colours, and the underline-based effects keep a real underline.',
+      'No JavaScript at all, so the render without it is the same.',
+    ],
+    usage: `---
+import LinkEffects from '../components/LinkEffects.astro';
+import Link from '../components/LinkEffects.astro';   // the same file, as a wrapper
+---
+<head> … <LinkEffects /> </head>                    <!-- the stylesheet, once -->
+
+<nav>
+  <Link effect="underline-slide" href="/about/" aria-current="page">About</Link>
+  <Link effect="peek" peek="$49/mo" href="/pricing/">Pricing</Link>
+</nav>
+<a class="lk-arrow" href="/book/">Book a visit</a>   <!-- or just the class -->
+<!-- .site { --lk-accent: var(--brand); --lk-bg: var(--page); } -->`,
+    license: 'Our own CSS and our own drawings (the swash and the ring). Nothing licensed from anyone else: no font, no icon set, no script.',
+    usedOn: [{ site: 'superherotech.ai', where: '/elements/link-effects/ (demo)' }],
+    file: 'src/library/link-effects/LinkEffects.astro',
+    added: '2026-09-26',
+  },
 ];
 
 export const byId = (id: string) => catalog.find((e) => e.id === id);
diff --git a/src/library/link-effects/LinkEffects.astro b/src/library/link-effects/LinkEffects.astro
new file mode 100644
index 0000000..774450c
--- /dev/null
+++ b/src/library/link-effects/LinkEffects.astro
@@ -0,0 +1,399 @@
+---
+/**
+ * LinkEffects — eleven hover-and-focus styles for links, in CSS only. UABB's "Creative Link",
+ * PowerPack's "Link Effects" and the underline-animation snippets people paste into a theme.
+ * Eight are the familiar ones; `peek`, `swash` and `tag` are ours.
+ *
+ *   lk-underline-slide    a line slides in under the text from the left and out to the right
+ *   lk-underline-grow     a thin underline at rest that thickens (the one for running text)
+ *   lk-brackets           [ brackets ] close in around the text
+ *   lk-highlight          a marker sweeps behind the text
+ *   lk-box                a frame draws itself around the text: top and bottom, then the sides
+ *   lk-strike-to-underline   a line strikes through the middle, then drops to become the underline
+ *   lk-arrow              → slides in after the text, into space kept for it
+ *   lk-circle             a hand-drawn ellipse rings the text
+ *   lk-peek               the link's `data-peek` words slide up in its place ("Pricing" → "$49/mo");
+ *                         both share one cell, so the link is as wide as the longer and nothing shifts
+ *   lk-swash              a hand-drawn underline (an inline SVG) draws itself, stroke-dashoffset 1 → 0
+ *   lk-tag                a pill that fills from the left, the text turning with the fill
+ *
+ * Use: put `<LinkEffects />` once in the layout (it emits the stylesheet), then either put the
+ * class on any <a> or use this same file as a wrapper, `import Link from './LinkEffects.astro'`:
+ *   <Link effect="underline-slide" href="/about/">About</Link>
+ *   <Link effect="peek" peek="$49/mo" href="/pricing/">Pricing</Link>
+ * The wrapper also emits the stylesheet (once per page, guarded through Astro.locals as the
+ * modal's runtime is), and adds the markup two effects need: `peek` wraps the words in
+ * <span class="lk__label">, `swash` appends its SVG. Without the wrapper, write those yourself:
+ *   <a class="lk-peek" data-peek="$49/mo" href="/pricing/"><span class="lk__label">Pricing</span></a>
+ *   <a class="lk-swash" href="/story/">Our story<svg class="lk__swash" …>…</svg></a>  (copy SWASH below)
+ *
+ * The rules every effect keeps:
+ *   - Hover and :focus-visible are one selector, `:is(:hover, :focus-visible)`, so a keyboard
+ *     user sees exactly what a mouse user sees. The browser's own focus ring is never removed.
+ *   - prefers-reduced-motion (or a browser that does not say): every transition lives inside
+ *     `@media (prefers-reduced-motion: no-preference)`, so otherwise the end state appears at
+ *     once. Nothing loops or plays by itself.
+ *   - Contrast never dips mid-animation: effects move decorations (lines, brackets, fills), not
+ *     the text colour. Two pin the text colour instead: `highlight` keeps --lk-ink over the page
+ *     and over the marker, at rest and when active (so a host's own hover colour cannot land on it), and `tag` paints its text and its fill as two layers of ONE
+ *     background that move together, so every pixel of text is --lk-ink over the page or
+ *     --lk-on-accent over the fill, never in between. No `color` is ever transitioned.
+ *     `npm run check` computes the fallback pairs: ink on page, ink on marker, on-accent on
+ *     accent, accent on page (the arrow and the peek words are accent-coloured text).
+ *   - Decorative glyphs are silent to screen readers (`content: "→" / ""`); the swash SVG is
+ *     aria-hidden. The peek words are part of the link's name ("Pricing $49/mo"), which is
+ *     the point of them.
+ *   - Without JavaScript: identical. There is none.
+ *
+ * `underline-slide`, `underline-grow` and `highlight` wrap across lines; the rest are
+ * inline-block and suit short links: navigation, a card's call to action, a footer.
+ *
+ * Theming, from the host's tokens (each has a fallback):
+ *   --lk-accent       lines, brackets, frame, arrow, peek words, tag fill      (#5933d8)
+ *   --lk-ink          text colour where an effect pins it (highlight, tag)     (#1e283c)
+ *   --lk-on-accent    tag text over its fill                                   (#fff)
+ *   --lk-mark         the highlight marker                                     (#ffe38f)
+ *   --lk-bg           the page behind the link; tag's resting fill             (#fff)
+ *   --lk-thickness    line weight                                              (2px)
+ *   --lk-duration / --lk-ease   timing                                        (0.3s / cubic-bezier(0.2, 0.7, 0.2, 1))
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+// <link-effects-list>
+const EFFECTS = ['underline-slide', 'underline-grow', 'brackets', 'highlight', 'box', 'strike-to-underline', 'arrow', 'circle', 'peek', 'swash', 'tag'] as const;
+// </link-effects-list>
+export type LinkEffect = (typeof EFFECTS)[number];
+
+interface Props extends Omit<HTMLAttributes<'a'>, 'class'> {
+  /** With `href`, render an <a class="lk-<effect>">. Without either, only emit the stylesheet. */
+  effect?: LinkEffect;
+  href?: string;
+  /** For effect="peek": the words that slide in. */
+  peek?: string;
+  class?: string;
+}
+
+const { effect, href, peek, class: className, ...rest } = Astro.props;
+if (effect !== undefined && !EFFECTS.includes(effect)) throw new Error(`LinkEffects: effect "${effect}" is not one of ${EFFECTS.join(', ')}.`);
+if (effect && !href) throw new Error(`LinkEffects: effect="${effect}" needs an \`href\`; the effects are for links.`);
+if (href && !effect) throw new Error('LinkEffects: an `href` needs an `effect`.');
+if (effect === 'peek' && !peek?.trim()) throw new Error('LinkEffects: effect="peek" needs `peek`, the words that slide in.');
+
+// The hand-drawn line for `swash`: a slightly rising stroke with a flick at the end.
+const SWASH =
+  '<svg class="lk__swash" viewBox="0 0 200 16" preserveAspectRatio="none" aria-hidden="true" focusable="false"><path d="M3 11.5C38 6.2 82 4.4 126 5.6c24 .6 47 2.4 71 .2" pathLength="1"/></svg>';
+
+const locals = Astro.locals as Record<string, unknown>;
+const firstOnPage = !locals.__linkEffectsStyle;
+locals.__linkEffectsStyle = true;
+---
+
+{
+  firstOnPage && (
+    <style is:inline data-lk>
+      a.lk-underline-slide, a.lk-underline-grow, a.lk-brackets, a.lk-highlight, a.lk-box, a.lk-strike-to-underline,
+      a.lk-arrow, a.lk-circle, a.lk-peek, a.lk-swash, a.lk-tag {
+        text-decoration: none;
+        outline-offset: 0.3em;
+      }
+      a.lk-brackets, a.lk-box, a.lk-strike-to-underline, a.lk-arrow, a.lk-circle, a.lk-swash, a.lk-tag {
+        position: relative;
+        display: inline-block;
+      }
+
+      /* underline-slide: in from the left, out to the right (the position jumps, the size moves). */
+      a.lk-underline-slide {
+        background: linear-gradient(var(--lk-accent, #5933d8), var(--lk-accent, #5933d8)) 100% 100% / 0% var(--lk-thickness, 2px) no-repeat;
+        padding-bottom: 0.12em;
+        -webkit-box-decoration-break: clone;
+        box-decoration-break: clone;
+      }
+      a.lk-underline-slide:is(:hover, :focus-visible) {
+        background-position: 0 100%;
+        background-size: 100% var(--lk-thickness, 2px);
+      }
+
+      /* underline-grow: always underlined, so it reads as a link in running text; thickens. */
+      a.lk-underline-grow {
+        background: linear-gradient(var(--lk-accent, #5933d8), var(--lk-accent, #5933d8)) 0 100% / 100% 1px no-repeat;
+        padding-bottom: 0.12em;
+        -webkit-box-decoration-break: clone;
+        box-decoration-break: clone;
+      }
+      a.lk-underline-grow:is(:hover, :focus-visible) {
+        background-size: 100% calc(var(--lk-thickness, 2px) + 2px);
+      }
+
+      /* brackets: outside the text box, so nothing moves. Silent to screen readers. */
+      a.lk-brackets::before,
+      a.lk-brackets::after {
+        position: absolute;
+        top: 0;
+        color: var(--lk-accent, #5933d8);
+        opacity: 0;
+      }
+      a.lk-brackets::before {
+        content: '[';
+        content: '[' / '';
+        right: 100%;
+        margin-right: 0.15em;
+        translate: -0.3em 0;
+      }
+      a.lk-brackets::after {
+        content: ']';
+        content: ']' / '';
+        left: 100%;
+        margin-left: 0.15em;
+        translate: 0.3em 0;
+      }
+      a.lk-brackets:is(:hover, :focus-visible)::before,
+      a.lk-brackets:is(:hover, :focus-visible)::after {
+        opacity: 1;
+        translate: 0 0;
+      }
+
+      /* highlight: the text colour is pinned (--lk-ink) and passes over the page and the marker. */
+      a.lk-highlight {
+        color: var(--lk-ink, #1e283c);
+        background: linear-gradient(var(--lk-mark, #ffe38f), var(--lk-mark, #ffe38f)) 0 88% / 0% 0.6em no-repeat;
+        padding: 0 0.1em;
+        -webkit-box-decoration-break: clone;
+        box-decoration-break: clone;
+      }
+      /* Pinned in the active state too, or a host's a:hover colour (same specificity, later
+         in the page) would put an unmeasured colour on the marker. */
+      a.lk-highlight:is(:hover, :focus-visible) {
+        color: var(--lk-ink, #1e283c);
+        background-size: 100% 0.6em;
+      }
+
+      /* box: top and bottom rules sweep out, then the sides rise. */
+      a.lk-box::before,
+      a.lk-box::after {
+        content: '';
+        position: absolute;
+        inset: -0.3em -0.5em;
+        pointer-events: none;
+      }
+      a.lk-box::before {
+        border-block: var(--lk-thickness, 2px) solid var(--lk-accent, #5933d8);
+        scale: 0 1;
+      }
+      a.lk-box::after {
+        border-inline: var(--lk-thickness, 2px) solid var(--lk-accent, #5933d8);
+        scale: 1 0;
+      }
+      a.lk-box:is(:hover, :focus-visible)::before,
+      a.lk-box:is(:hover, :focus-visible)::after {
+        scale: 1 1;
+      }
+
+      /* strike-to-underline: through the middle first, then down to the baseline. */
+      a.lk-strike-to-underline::after {
+        content: '';
+        position: absolute;
+        left: 0;
+        right: 0;
+        bottom: -0.05em;
+        height: var(--lk-thickness, 2px);
+        background: var(--lk-accent, #5933d8);
+        translate: 0 -0.5em;
+        scale: 0 1;
+      }
+      a.lk-strike-to-underline:is(:hover, :focus-visible)::after {
+        translate: 0 0;
+        scale: 1 1;
+      }
+
+      /* arrow: its room is kept at rest (padding), so the text never shifts. Silent to screen readers. */
+      a.lk-arrow {
+        padding-inline-end: 1.3em;
+      }
+      a.lk-arrow::after {
+        content: '→';
+        content: '→' / '';
+        position: absolute;
+        right: 0;
+        color: var(--lk-accent, #5933d8);
+        opacity: 0;
+        translate: -0.5em 0;
+      }
+      a.lk-arrow:is(:hover, :focus-visible)::after {
+        opacity: 1;
+        translate: 0 0;
+      }
+
+      /* circle: a slightly uneven ellipse, tilted, as if drawn with a pen. */
+      a.lk-circle {
+        padding: 0 0.15em;
+      }
+      a.lk-circle::after {
+        content: '';
+        position: absolute;
+        inset: -0.35em -0.55em;
+        border: var(--lk-thickness, 2px) solid var(--lk-accent, #5933d8);
+        border-radius: 55% 45% 52% 48% / 58% 48% 52% 42%;
+        rotate: -4deg;
+        opacity: 0;
+        scale: 0.75;
+        pointer-events: none;
+      }
+      a.lk-circle:is(:hover, :focus-visible)::after {
+        opacity: 1;
+        scale: 1;
+      }
+
+      /* peek: the words and the data-peek text share one grid cell, so the link keeps the wider width. */
+      a.lk-peek {
+        display: inline-grid;
+        overflow: hidden;
+        vertical-align: bottom;
+        background: linear-gradient(currentColor, currentColor) 0 100% / 100% 1px no-repeat;
+      }
+      a.lk-peek > .lk__label,
+      a.lk-peek::after {
+        grid-area: 1 / 1;
+      }
+      a.lk-peek::after {
+        content: attr(data-peek);
+        color: var(--lk-accent, #5933d8);
+        font-weight: 600;
+        opacity: 0;
+        translate: 0 100%;
+      }
+      a.lk-peek:is(:hover, :focus-visible) > .lk__label {
+        opacity: 0;
+        translate: 0 -100%;
+      }
+      a.lk-peek:is(:hover, :focus-visible)::after {
+        opacity: 1;
+        translate: 0 0;
+      }
+
+      /* swash: the stroke is drawn by its dash offset, 1 (hidden) to 0 (whole). */
+      a.lk-swash {
+        padding-bottom: 0.3em;
+      }
+      a.lk-swash .lk__swash {
+        position: absolute;
+        left: -3%;
+        bottom: -0.1em;
+        width: 106%;
+        height: 0.5em;
+        overflow: visible;
+        fill: none;
+        stroke: var(--lk-accent, #5933d8);
+        stroke-width: 3.5;
+        stroke-linecap: round;
+        pointer-events: none;
+      }
+      a.lk-swash .lk__swash path {
+        stroke-dasharray: 1;
+        stroke-dashoffset: 1;
+      }
+      a.lk-swash:is(:hover, :focus-visible) .lk__swash path {
+        stroke-dashoffset: 0;
+      }
+
+      /* tag: text colour and fill are two layers of one background, moved by one background-position,
+         so each pixel of text is --lk-ink on the page or --lk-on-accent on the fill, never between. */
+      a.lk-tag {
+        padding: 0.2em 0.85em;
+        border: 1.5px solid var(--lk-accent, #5933d8);
+        border-radius: 999px;
+        color: var(--lk-ink, #1e283c);
+        background-color: var(--lk-bg, #fff);
+      }
+      @supports ((background-clip: text) or (-webkit-background-clip: text)) {
+        a.lk-tag {
+          background:
+            linear-gradient(90deg, var(--lk-on-accent, #fff) 50%, var(--lk-ink, #1e283c) 50%),
+            linear-gradient(90deg, var(--lk-accent, #5933d8) 50%, var(--lk-bg, #fff) 50%);
+          background-size: 200% 100%;
+          background-position: 100% 0;
+          background-repeat: no-repeat;
+          -webkit-background-clip: text, padding-box;
+          background-clip: text, padding-box;
+          -webkit-text-fill-color: transparent;
+        }
+        a.lk-tag:is(:hover, :focus-visible) {
+          background-position: 0 0;
+        }
+      }
+      @supports not ((background-clip: text) or (-webkit-background-clip: text)) {
+        a.lk-tag:is(:hover, :focus-visible) {
+          background-color: var(--lk-accent, #5933d8);
+          color: var(--lk-on-accent, #fff);
+        }
+      }
+
+      @media (prefers-reduced-motion: no-preference) {
+        a.lk-underline-slide, a.lk-underline-grow, a.lk-highlight {
+          transition: background-size var(--lk-duration, 0.3s) var(--lk-ease, cubic-bezier(0.2, 0.7, 0.2, 1));
+        }
+        a.lk-brackets::before, a.lk-brackets::after, a.lk-arrow::after, a.lk-circle::after,
+        a.lk-peek > .lk__label, a.lk-peek::after {
+          transition:
+            opacity var(--lk-duration, 0.3s) var(--lk-ease, cubic-bezier(0.2, 0.7, 0.2, 1)),
+            translate var(--lk-duration, 0.3s) var(--lk-ease, cubic-bezier(0.2, 0.7, 0.2, 1)),
+            scale var(--lk-duration, 0.3s) var(--lk-ease, cubic-bezier(0.2, 0.7, 0.2, 1));
+        }
+        a.lk-box::before {
+          transition: scale calc(var(--lk-duration, 0.3s) * 0.6) ease-out calc(var(--lk-duration, 0.3s) * 0.5);
+        }
+        a.lk-box::after {
+          transition: scale calc(var(--lk-duration, 0.3s) * 0.6) ease-out;
+        }
+        a.lk-box:is(:hover, :focus-visible)::before {
+          transition-delay: 0s;
+        }
+        a.lk-box:is(:hover, :focus-visible)::after {
+          transition-delay: calc(var(--lk-duration, 0.3s) * 0.5);
+        }
+        /* Out: rise to the middle, then shrink. In: grow in the middle, then drop. */
+        a.lk-strike-to-underline::after {
+          transition:
+            translate calc(var(--lk-duration, 0.3s) * 0.7) ease,
+            scale calc(var(--lk-duration, 0.3s) * 0.7) ease calc(var(--lk-duration, 0.3s) * 0.7);
+        }
+        a.lk-strike-to-underline:is(:hover, :focus-visible)::after {
+          transition:
+            scale calc(var(--lk-duration, 0.3s) * 0.7) ease,
+            translate calc(var(--lk-duration, 0.3s) * 0.7) ease calc(var(--lk-duration, 0.3s) * 0.7);
+        }
+        a.lk-swash .lk__swash path {
+          transition: stroke-dashoffset calc(var(--lk-duration, 0.3s) * 1.8) ease-in-out;
+        }
+        a.lk-tag {
+          transition: background-position var(--lk-duration, 0.3s) var(--lk-ease, cubic-bezier(0.2, 0.7, 0.2, 1));
+        }
+      }
+
+      /* Windows High Contrast and the like: system colours, no painted text. */
+      @media (forced-colors: active) {
+        a.lk-tag {
+          background: none;
+          -webkit-text-fill-color: currentColor;
+          color: LinkText;
+        }
+        a.lk-underline-slide, a.lk-underline-grow, a.lk-highlight, a.lk-peek {
+          text-decoration: underline;
+        }
+      }
+    </style>
+  )
+}
+{
+  href && (
+    <a class:list={[`lk-${effect}`, className]} href={href} data-peek={effect === 'peek' ? peek : undefined} {...rest}>
+      {effect === 'peek' ? (
+        <span class="lk__label">
+          <slot />
+        </span>
+      ) : (
+        <slot />
+      )}
+      {effect === 'swash' && <Fragment set:html={SWASH} />}
+    </a>
+  )
+}