From c61fba2fceb1c5874b334fd3907d479e7278e1ae Mon Sep 17 00:00:00 2001
From: Tom Chen <tomchen.org@gmail.com>
Date: Tue, 22 Sep 2026 12:29:57 +0200
Subject: [PATCH 1/3] Complete SEO metadata and fix keyboard accessibility

---
 .github/workflows/ci.yml             |   3 +-
 astro.config.mjs                     |   4 ++
 docs/dev/deploy.md                   |  18 +++--
 lighthouserc.json                    |   8 +--
 scripts/check-dist-links.mjs         |  22 ++++--
 scripts/sitemap-metadata.ts          |  38 ++++++++++
 src/components/Nav.astro             |  18 +++++
 src/components/Seo.astro             |   7 +-
 src/islands/DailyKata.tsx            |  13 ++--
 src/islands/Flashcards.tsx           |   8 ++-
 src/islands/Palette.tsx              |   4 +-
 src/islands/Playground.tsx           |   2 +-
 src/layouts/Base.astro               |   2 +
 src/lib/og.ts                        |   6 +-
 src/lib/seo.ts                       |  28 +++++++-
 src/pages-shared/GlossaryTerm.astro  |   2 +-
 src/pages-shared/Kata.astro          |   9 +--
 src/pages-shared/PracticeTrack.astro |   2 -
 src/pages-shared/Topic.astro         |   4 +-
 src/styles/global.css                |  14 ++++
 tests/e2e/a11y.spec.ts               | 100 ++++++++++++++++++++-------
 tests/e2e/keyboard.spec.ts           |  71 +++++++++++++++++++
 tests/e2e/practice-hub.spec.ts       |   2 +-
 tests/e2e/seo.spec.ts                |  45 +++++++++++-
 tests/unit/seo.test.ts               |  41 +++++++++++
 tests/unit/sitemap.test.ts           |  39 +++++++++++
 26 files changed, 443 insertions(+), 67 deletions(-)
 create mode 100644 scripts/sitemap-metadata.ts
 create mode 100644 tests/e2e/keyboard.spec.ts
 create mode 100644 tests/unit/sitemap.test.ts

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 98f8329..c344a5c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -66,7 +66,8 @@ jobs:
             exit 1
           fi
           npx --yes wrangler@4.135.0 pages deploy dist --project-name codewiki --branch main --commit-hash "$GITHUB_SHA" --force
-      - if: failure()
+      - name: Upload validation reports
+        if: always()
         uses: actions/upload-artifact@v4
         with:
           name: test-artifacts
diff --git a/astro.config.mjs b/astro.config.mjs
index 403cae2..73b4ed7 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -6,6 +6,7 @@ import preact from '@astrojs/preact';
 import tailwindcss from '@tailwindcss/vite';
 
 import pwa from './scripts/build-sw.mjs';
+import { contentModificationDates, sitemapMetadata } from './scripts/sitemap-metadata.ts';
 
 import { LEGACY_REDIRECTS } from './src/data/redirects.ts';
 import { rehypeCodebox } from './src/markdown/rehype-codebox.ts';
@@ -16,6 +17,8 @@ import { remarkDepth } from './src/markdown/remark-depth.ts';
 import { rehypeSectionActions } from './src/markdown/rehype-section-actions.ts';
 import { shikiMetaTransformer } from './src/markdown/shiki-meta.ts';
 
+let sitemapDates;
+
 export default defineConfig({
   site: 'https://codewiki.com',
   output: 'static',
@@ -61,6 +64,7 @@ export default defineConfig({
     preact(),
     sitemap({
       i18n: { defaultLocale: 'en', locales: { en: 'en', zh: 'zh-Hans' } },
+      serialize: (item) => sitemapMetadata(item, (sitemapDates ??= contentModificationDates())),
       // Settings is `noindex`, search is a query interface and the offline notice only ever
       // renders without a network: none belongs in the sitemap, and listing an unindexable URL is
       // a Search Console warning. A 301 is not a document either.
diff --git a/docs/dev/deploy.md b/docs/dev/deploy.md
index 5739b7b..c7f200c 100644
--- a/docs/dev/deploy.md
+++ b/docs/dev/deploy.md
@@ -117,11 +117,20 @@ other static host, serves for a directory request.
 
 ## Performance budgets
 
+Page metadata is built in `src/lib/seo.ts`: canonical URLs, language alternates, Open Graph and
+Twitter cards, and page-specific JSON-LD. Topics expose their reviewed date, section and tags to
+Open Graph and their generated image to JSON-LD. Publication dates and author profiles are omitted
+when the content has no reliable source for them. Reused sharing images describe the source card.
+`scripts/sitemap-metadata.ts` uses content review/verification dates for topic and cheatsheet
+`lastmod` values; it never substitutes the build date. Undated index pages remain undated.
+The link checker also validates destinations in structured data.
+
 `lighthouserc.json` drives `pnpm exec lhci autorun`, which builds nothing itself: it serves the
-existing `dist` and audits ten URLs. The four P1 surfaces are the English home page, a track hub,
+existing `dist` and audits eleven URLs. The four P1 surfaces are the English home page, a track hub,
 and the topic page in both languages. The P2 surfaces are Practice, Python from zero, Flashcards,
-the Python cheatsheet, Prompt Builder and Playground. Lighthouse uses its default mobile
-emulation. All four category scores are gated at 0.95. The transferred-script ceilings are 60 KiB
+the Python cheatsheet, Prompt Builder and Playground, plus the JavaScript practice catalogue. Lighthouse uses its default mobile
+emulation, with three runs per URL and median assertions. Performance is gated at 0.95; accessibility,
+best practices and SEO must score 1.00. The transferred-script ceilings are 66 KiB
 for P1, 100 KiB for Practice, paths, Flashcards, cheatsheets and Prompt Builder, and 300 KiB for
 Playground.
 
@@ -136,7 +145,8 @@ Three notes on that file, since JSON cannot carry comments:
   and 0.99 respectively, so the 0.95 performance gate remains unchanged.
 - **Accessibility is release-gated.** `color-contrast` and `label-content-name-mismatch` are
   Lighthouse errors, and the Playwright accessibility coverage checks the contrast-sensitive UI
-  directly. The earlier set of ten open contrast pairs has been corrected.
+  directly. Playwright checks all reported WCAG 2.2 AA and best-practice violations across both
+  languages and themes, plus keyboard focus, mobile menus and the open search dialog.
 - **`network-dependency-tree-insight` is `off`.** It scores zero for any critical request chain
   deeper than one hop, which the HTML → stylesheet → webfont chain of a self-hosted static site
   always has.
diff --git a/lighthouserc.json b/lighthouserc.json
index c9ed0d1..5b8519e 100644
--- a/lighthouserc.json
+++ b/lighthouserc.json
@@ -34,25 +34,25 @@
             "categories:accessibility": [
               "error",
               {
-                "minScore": 0.95
+                "minScore": 1
               }
             ],
             "categories:best-practices": [
               "error",
               {
-                "minScore": 0.95
+                "minScore": 1
               }
             ],
             "categories:seo": [
               "error",
               {
-                "minScore": 0.95
+                "minScore": 1
               }
             ],
             "color-contrast": "error",
             "forced-reflow-insight": ["warn", {}],
             "unused-css-rules": ["warn", {}],
-            "label-content-name-mismatch": "warn",
+            "label-content-name-mismatch": "error",
             "network-dependency-tree-insight": "off"
           }
         },
diff --git a/scripts/check-dist-links.mjs b/scripts/check-dist-links.mjs
index 77dc2cd..9f67d80 100644
--- a/scripts/check-dist-links.mjs
+++ b/scripts/check-dist-links.mjs
@@ -2,7 +2,8 @@
  * Dead-link check over the built site.
  *
  * Walks `dist/**\/*.html`, collects every same-origin `href` and `src` plus the URL-valued head
- * metadata (`og:image`, `twitter:image`, canonical and hreflang alternates), and resolves each one
+ * metadata (`og:image`, `twitter:image`, canonical and hreflang alternates), JSON-LD destinations,
+ * and resolves each one
  * against `dist/` the way the deployed site does. `trailingSlash: 'always'` in astro.config.mjs
  * means a directory URL `/x/` is the file `dist/x/index.html`; a path that carries an extension
  * is the file itself.
@@ -20,8 +21,6 @@ import { fileURLToPath } from 'node:url';
 const ROOT = path.resolve(fileURLToPath(new URL('..', import.meta.url)));
 const DIST = path.join(ROOT, 'dist');
 
-const KNOWN_LATER = ['/java/type-erasure/', '/java/wildcards-pecs/'];
-
 /** The canonical origin, read from src/data/site.ts so the two never drift. */
 async function siteOrigin() {
   const source = await readFile(path.join(ROOT, 'src/data/site.ts'), 'utf8');
@@ -81,6 +80,21 @@ function metadataUrls(html) {
       if (href !== undefined) values.push(href);
     }
   }
+  // Structured breadcrumbs and article images must resolve just like visible links. Schema
+  // identifiers and search URL templates are not page destinations and are left alone.
+  const urlKeys = new Set(['url', 'item', 'image', 'mainEntityOfPage']);
+  function visit(value, key = '') {
+    if (typeof value === 'string' && urlKeys.has(key)) values.push(value);
+    else if (Array.isArray(value)) value.forEach((item) => visit(item, key));
+    else if (value && typeof value === 'object') {
+      for (const [key, item] of Object.entries(value)) visit(item, key);
+    }
+  }
+  for (const match of html.matchAll(
+    /<script\b[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi,
+  )) {
+    visit(JSON.parse(match[1]));
+  }
   return values;
 }
 
@@ -189,7 +203,7 @@ for (const page of pages) {
     if (!pathname || seen.has(pathname)) continue;
     seen.add(pathname);
     checked += 1;
-    if (!resolveTarget(pathname) && !KNOWN_LATER.includes(pathname)) {
+    if (!resolveTarget(pathname)) {
       failures.push({ page: `/${page}`, target: pathname });
     }
   }
diff --git a/scripts/sitemap-metadata.ts b/scripts/sitemap-metadata.ts
new file mode 100644
index 0000000..f010c43
--- /dev/null
+++ b/scripts/sitemap-metadata.ts
@@ -0,0 +1,38 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import type { SitemapItem } from '@astrojs/sitemap';
+
+/** Content dates, never the build time: rebuilding an unchanged page is not a content update. */
+export function contentModificationDates(root = process.cwd()): Map<string, string> {
+  const dates = new Map<string, string>();
+  for (const collection of ['topics', 'cheatsheets']) {
+    const directory = path.join(root, 'src/content', collection);
+    for (const file of readdirSync(directory, { recursive: true, encoding: 'utf8' })) {
+      const match = file.replaceAll(path.sep, '/').match(/^(.*)\.(en|zh)\.mdx$/);
+      if (!match) continue;
+      const { data } = matter(readFileSync(path.join(directory, file), 'utf8'));
+      if (data.status !== 'reviewed') continue;
+      const modified = data.reviewed ?? data.verified?.date;
+      if (!modified) continue;
+      const date = new Date(modified);
+      if (Number.isNaN(date.getTime())) throw new Error(`Invalid sitemap date: ${file}`);
+      const prefix = match[2] === 'zh' ? '/zh' : '';
+      const section = collection === 'cheatsheets' ? '/cheatsheets' : '';
+      dates.set(`${prefix}${section}/${match[1]}/`, date.toISOString().slice(0, 10));
+    }
+  }
+  return dates;
+}
+
+export function sitemapMetadata(item: SitemapItem, dates: Map<string, string>): SitemapItem {
+  const lastmod = dates.get(new URL(item.url).pathname);
+  const english = item.links?.find((link) => link.lang === 'en');
+  return {
+    ...item,
+    ...(lastmod ? { lastmod } : {}),
+    ...(english && !item.links?.some((link) => link.lang === 'x-default')
+      ? { links: [...(item.links ?? []), { lang: 'x-default', url: english.url }] }
+      : {}),
+  };
+}
diff --git a/src/components/Nav.astro b/src/components/Nav.astro
index 7cfac66..c8cc034 100644
--- a/src/components/Nav.astro
+++ b/src/components/Nav.astro
@@ -148,6 +148,24 @@ const homeHref = localizePath('/', locale);
   </div>
 </header>
 
+<script>
+  document.querySelectorAll<HTMLDetailsElement>('.nav-menu').forEach((menu) => {
+    const trigger = menu.querySelector<HTMLElement>('summary')!;
+    menu.addEventListener('keydown', (event) => {
+      if (event.key !== 'Escape' || !menu.open) return;
+      event.preventDefault();
+      menu.open = false;
+      trigger.focus();
+    });
+    menu.addEventListener('focusout', (event) => {
+      if (event.relatedTarget && !menu.contains(event.relatedTarget as Node)) menu.open = false;
+    });
+    document.addEventListener('click', (event) => {
+      if (!menu.contains(event.target as Node)) menu.open = false;
+    });
+  });
+</script>
+
 <style>
   .nav-outer {
     position: relative;
diff --git a/src/components/Seo.astro b/src/components/Seo.astro
index 763e4c8..cd56bee 100644
--- a/src/components/Seo.astro
+++ b/src/components/Seo.astro
@@ -21,13 +21,16 @@ function ldJson(block: object): string {
 }
 ---
 
-<meta charset="utf-8" />
 <meta name="viewport" content="width=device-width, initial-scale=1" />
 <title>{head.title}</title>
 <meta name="description" content={head.description} />
 <link rel="canonical" href={head.canonical} />
 {head.alternates.map((alt) => <link rel="alternate" hreflang={alt.hreflang} href={alt.href} />)}
-{Object.entries(head.og).map(([property, content]) => <meta property={property} content={content} />)}
+{
+  Object.entries(head.og).flatMap(([property, value]) =>
+    (Array.isArray(value) ? value : [value]).map((content) => <meta property={property} content={content} />),
+  )
+}
 {Object.entries(head.twitter).map(([name, content]) => <meta name={name} content={content} />)}
 {head.robots && <meta name="robots" content={head.robots} />}
 {head.jsonLd.map((block) => <script type="application/ld+json" is:inline set:html={ldJson(block)} />)}
diff --git a/src/islands/DailyKata.tsx b/src/islands/DailyKata.tsx
index 8ebe1d4..fc0e1ec 100644
--- a/src/islands/DailyKata.tsx
+++ b/src/islands/DailyKata.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useState } from 'preact/hooks';
+import { useEffect, useId, useState } from 'preact/hooks';
 
 import type { DailyKataEntry, DailyKataLabels } from '@/lib/daily-kata';
 import { EMPTY_PROGRESS, KEYS, readStore, type QuizProgress } from '@/lib/prefs';
@@ -50,6 +50,7 @@ export default function DailyKata({
   labels,
 }: DailyKataProps) {
   const [offset, setOffset] = useState(0);
+  const peekDescriptionId = useId();
   const [done, setDone] = useState<QuizProgress | undefined>(undefined);
 
   useEffect(() => {
@@ -115,12 +116,10 @@ export default function DailyKata({
         {hero && <span class="lbl daily-every">{labels.everyDay}</span>}
       </div>
 
-      <a
-        class="peek"
-        href={entry.kataUrl}
-        aria-label={fill(labels.peek, { title: entry.title })}
-        data-daily-peek
-      >
+      <span id={peekDescriptionId} hidden>
+        {fill(labels.peek, { title: entry.title })}
+      </span>
+      <a class="peek" href={entry.kataUrl} aria-describedby={peekDescriptionId} data-daily-peek>
         <div class="peek-body">
           <div dangerouslySetInnerHTML={{ __html: entry.peekHtml }} />
           {entry.peekMoreSmall > 0 && (
diff --git a/src/islands/Flashcards.tsx b/src/islands/Flashcards.tsx
index 30be989..cd69748 100644
--- a/src/islands/Flashcards.tsx
+++ b/src/islands/Flashcards.tsx
@@ -220,7 +220,7 @@ function DeckRail(props: {
           </div>
         </div>
         <span class="lbl">{labels.nextSeven}</span>
-        <div class="histogram" aria-label={labels.nextSeven}>
+        <div class="histogram" role="img" aria-label={`${labels.nextSeven}: ${histogram.join(', ')}`}>
           {histogram.map((count, index) => (
             <span
               key={index}
@@ -522,6 +522,7 @@ export default function Flashcards({ locale, labels, practiceUrl, pythonUrl, set
       <div
         class="flashcards-progress"
         role="progressbar"
+        aria-label={locale === 'zh' ? '复习进度' : 'Review progress'}
         aria-valuemin={0}
         aria-valuemax={Math.max(1, total)}
         aria-valuenow={done}
@@ -548,11 +549,14 @@ export default function Flashcards({ locale, labels, practiceUrl, pythonUrl, set
           <span class="lbl">{fill(labels.cardCount, { i: done + 1, n: total })}</span>
         </header>
 
+        <span id="flashcard-flip-hint" hidden>
+          {labels.flip}
+        </span>
         {face ? (
           <button
             type="button"
             class="flashcard-front"
-            aria-label={labels.flip}
+            aria-describedby="flashcard-flip-hint"
             aria-pressed={flipped}
             onClick={() => setFlipped((value) => !value)}
           >
diff --git a/src/islands/Palette.tsx b/src/islands/Palette.tsx
index 278049d..b143ce0 100644
--- a/src/islands/Palette.tsx
+++ b/src/islands/Palette.tsx
@@ -451,7 +451,7 @@ export default function Palette({ locale, mode = 'overlay', searchUrl, labels }:
   // `/search/` has no roving cursor to describe — its rows are ordinary links, and marking one
   // of them selected would claim a keyboard state the page does not have.
   const list = (
-    <div class="palette-list" id={listId} role={inline ? undefined : 'listbox'} aria-label={labels.results}>
+    <div class="palette-list" id={listId} role={inline ? 'region' : 'listbox'} aria-label={labels.results}>
       {rows.map((row, index) => (
         <Fragment key={row.url}>
           {headings.has(index) ? <span class="lbl palette-group">{headings.get(index)}</span> : null}
@@ -548,7 +548,7 @@ export default function Palette({ locale, mode = 'overlay', searchUrl, labels }:
             onInput={(event) => setQuery(event.currentTarget.value)}
           />
           {langToggle}
-          <button type="button" class="kbd palette-esc" onClick={close} aria-label={labels.close}>
+          <button type="button" class="kbd palette-esc" onClick={close} aria-label={`${labels.close} (Esc)`}>
             esc
           </button>
         </div>
diff --git a/src/islands/Playground.tsx b/src/islands/Playground.tsx
index c98cc71..ffc3a45 100644
--- a/src/islands/Playground.tsx
+++ b/src/islands/Playground.tsx
@@ -635,7 +635,7 @@ export default function Playground({ locale, labels }: Props) {
       </div>
 
       {examples.length > 0 && (
-        <div class="playground-example-cards" aria-label={labels.loadExample}>
+        <div class="playground-example-cards" role="group" aria-label={labels.loadExample}>
           {examples.slice(0, 4).map((example) => (
             <button
               type="button"
diff --git a/src/layouts/Base.astro b/src/layouts/Base.astro
index 8c868f5..c9038de 100644
--- a/src/layouts/Base.astro
+++ b/src/layouts/Base.astro
@@ -102,6 +102,7 @@ const uiStrings = {
 
 <html lang={lang}>
   <head>
+    <meta charset="utf-8" />
     <ThemeScript />
     <script is:inline>
       // Task 17: the stored font size, applied before paint for the same reason the theme is —
@@ -132,6 +133,7 @@ const uiStrings = {
     <Nav locale={locale} currentPath={currentPath} />
     <main
       id="main"
+      tabindex="-1"
       data-pagefind-body={body ? '' : undefined}
       data-pagefind-filter={refs('filter', body?.filter)}
       data-pagefind-meta={refs('meta', body?.meta)}
diff --git a/src/lib/og.ts b/src/lib/og.ts
index abb7e84..83e7b9d 100644
--- a/src/lib/og.ts
+++ b/src/lib/og.ts
@@ -576,5 +576,9 @@ function cardSvg(input: OgCard, faces: OgFont[]): Promise<string> | string {
 export async function renderOg(input: OgCard, options: RenderOptions = {}): Promise<Buffer> {
   const faces = options.fonts ?? (await ensureFonts());
   const svg = await cardSvg(input, faces);
-  return new Resvg(svg, { fitTo: { mode: 'width', value: WIDTH } }).render().asPng();
+  // Satori embeds glyphs as paths. Scanning the host's fonts for every PNG adds hundreds of
+  // milliseconds per card and cannot affect these already outlined glyphs.
+  return new Resvg(svg, { fitTo: { mode: 'width', value: WIDTH }, font: { loadSystemFonts: false } })
+    .render()
+    .asPng();
 }
diff --git a/src/lib/seo.ts b/src/lib/seo.ts
index bbf49c9..8f116d2 100644
--- a/src/lib/seo.ts
+++ b/src/lib/seo.ts
@@ -19,6 +19,14 @@ export interface HeadInput {
   trackName?: string;
   /** Overrides the generated OG image. Site-absolute path or an absolute URL. */
   ogImagePath?: string;
+  /** Describe the actual card when reusing another page's image. */
+  ogImageAlt?: string;
+  article?: {
+    publishedTime?: string;
+    modifiedTime?: string;
+    section?: string;
+    tags?: string[];
+  };
   noindex?: boolean;
   /** Page-specific JSON-LD blocks, appended after the automatic ones. */
   jsonLd?: object[];
@@ -29,7 +37,7 @@ export interface HeadModel {
   description: string;
   canonical: string;
   alternates: { hreflang: string; href: string }[];
-  og: Record<string, string>;
+  og: Record<string, string | string[]>;
   twitter: Record<string, string>;
   jsonLd: object[];
   /** Only set when the page opts out of indexing. Such a page also has no `alternates`. */
@@ -68,29 +76,41 @@ export function ogImageUrl(locale: Locale, path: string): string {
 
 /** Everything `<head>` needs for one page, ready to render without further logic. */
 export function buildHead(input: HeadInput): HeadModel {
-  const { locale, path, description, kind, ogImagePath, noindex, jsonLd = [] } = input;
+  const { locale, path, description, kind, ogImagePath, article, noindex, jsonLd = [] } = input;
   const title = formatTitle(input);
   const canonical = absolute(path);
   const alt = alternates(path);
   const image = ogImagePath ? absolute(ogImagePath) : ogImageUrl(locale, path);
+  const imageTitle = /\/og\/(zh\/)?home\.png$/.test(image) ? `${SITE.name} · ${SITE.tagline[locale]}` : title;
+  const imageAlt = input.ogImageAlt ?? imageTitle;
 
-  const og: Record<string, string> = {
+  const og: HeadModel['og'] = {
     'og:type': kind === 'topic' ? 'article' : 'website',
     'og:site_name': SITE.name,
     'og:locale': OG_LOCALE[locale],
+    ...(!noindex ? { 'og:locale:alternate': OG_LOCALE[locale === 'en' ? 'zh' : 'en'] } : {}),
     'og:title': title,
     'og:description': description,
     'og:url': canonical,
     'og:image': image,
+    'og:image:type': 'image/png',
     'og:image:width': '1200',
     'og:image:height': '630',
+    'og:image:alt': imageAlt,
   };
+  if (kind === 'topic' && article) {
+    if (article.publishedTime) og['article:published_time'] = article.publishedTime;
+    if (article.modifiedTime) og['article:modified_time'] = article.modifiedTime;
+    if (article.section) og['article:section'] = article.section;
+    if (article.tags?.length) og['article:tag'] = article.tags;
+  }
 
   const twitter: Record<string, string> = {
     'twitter:card': 'summary_large_image',
     'twitter:title': title,
     'twitter:description': description,
     'twitter:image': image,
+    'twitter:image:alt': imageAlt,
   };
 
   const model: HeadModel = {
@@ -155,6 +175,7 @@ export interface TechArticleInput {
   inLanguage: string;
   keywords?: string[];
   section?: string;
+  image?: string;
 }
 
 /** Topic pages. Optional fields are dropped rather than emitted empty. */
@@ -167,6 +188,7 @@ export function techArticleLd(input: TechArticleInput): object {
     description,
     url,
     mainEntityOfPage: url,
+    ...(input.image ? { image: input.image } : {}),
     ...(datePublished ? { datePublished } : {}),
     dateModified,
     inLanguage,
diff --git a/src/pages-shared/GlossaryTerm.astro b/src/pages-shared/GlossaryTerm.astro
index e32d55e..5882e7d 100644
--- a/src/pages-shared/GlossaryTerm.astro
+++ b/src/pages-shared/GlossaryTerm.astro
@@ -148,7 +148,7 @@ const head = buildHead({
       )
     }
 
-    <nav class="pager" aria-label={t(locale, 'glossary.title')}>
+    <nav class="pager" aria-label={locale === 'zh' ? '相邻术语' : 'Adjacent terms'}>
       {
         neighbours.map((link) => (
           <a class="panel pager-link" href={localizePath(`/glossary/${link.entry.id}/`, locale)}>
diff --git a/src/pages-shared/Kata.astro b/src/pages-shared/Kata.astro
index d150d92..be533cf 100644
--- a/src/pages-shared/Kata.astro
+++ b/src/pages-shared/Kata.astro
@@ -148,7 +148,7 @@ const aiLabels = {
 const visualTrail = [
   { label: t(locale, 'practice.title') },
   { label: typeLabel, variant: item.type === 'review' ? ('acc2' as const) : ('default' as const) },
-  { label: trackName, href: trackUrl(catalogueItem.track, locale) },
+  { label: trackName, href: localizePath(`/practice/${catalogueItem.track}/`, locale) },
   { label: sourceTitle, current: true },
 ];
 
@@ -163,14 +163,11 @@ const head = buildHead({
   ogImagePath: topic
     ? `/og/${locale === 'zh' ? 'zh/' : ''}${catalogueItem.track}/${catalogueItem.slug}.png`
     : `/og/${locale === 'zh' ? 'zh/' : ''}home.png`,
+  ogImageAlt: topic ? `${topic.data.title} · ${trackName} · ${SITE.name}` : undefined,
   jsonLd: [
     breadcrumbLd([
       { name: t(locale, 'practice.title'), url: `${SITE.url}${localizePath('/practice/', locale)}` },
-      {
-        name: typeLabel,
-        url: `${SITE.url}${localizePath(`/practice/${item.type}/`, locale)}`,
-      },
-      { name: trackName, url: `${SITE.url}${trackUrl(catalogueItem.track, locale)}` },
+      { name: trackName, url: `${SITE.url}${localizePath(`/practice/${catalogueItem.track}/`, locale)}` },
       { name: sourceTitle, url },
     ]),
   ],
diff --git a/src/pages-shared/PracticeTrack.astro b/src/pages-shared/PracticeTrack.astro
index 43e4c29..f4cc2ef 100644
--- a/src/pages-shared/PracticeTrack.astro
+++ b/src/pages-shared/PracticeTrack.astro
@@ -63,8 +63,6 @@ const trackLinks = [
     label: `${candidate.name[locale]} ${totals.get(candidate.slug) ?? 0}`,
     value: candidate.slug,
     on: candidate.slug === track.slug,
-    // "Go" is a whole accessible name on its own; the chip says what following it does.
-    ariaLabel: t(locale, 'practice.filterBy', { track: candidate.name[locale] }),
     href: localizePath(`/practice/${candidate.slug}/`, locale),
   })),
 ];
diff --git a/src/pages-shared/Topic.astro b/src/pages-shared/Topic.astro
index dee3343..8f3a2c0 100644
--- a/src/pages-shared/Topic.astro
+++ b/src/pages-shared/Topic.astro
@@ -35,7 +35,7 @@ import { formatCount, t } from '@/i18n';
 import { P2_NAV, SITE } from '@/data/site';
 import { getSection, getTrack } from '@/data/tracks';
 import { getTopic, isPublic, topicMeta, type Topic } from '@/lib/content';
-import { breadcrumbLd, buildHead, techArticleLd } from '@/lib/seo';
+import { breadcrumbLd, buildHead, ogImageUrl, techArticleLd } from '@/lib/seo';
 import { readVerification } from '@/lib/verify';
 import { localizePath, topicUrl, trackUrl, type Locale } from '@/lib/urls';
 
@@ -192,11 +192,13 @@ const head = buildHead({
   description: topic.data.description,
   kind: 'topic',
   trackName,
+  article: { modifiedTime: modified, section: section?.name[locale], tags: topic.data.tags },
   jsonLd: [
     techArticleLd({
       headline: topic.data.title,
       description: topic.data.description,
       url,
+      image: ogImageUrl(locale, currentPath),
       dateModified: modified,
       inLanguage,
       keywords: topic.data.tags,
diff --git a/src/styles/global.css b/src/styles/global.css
index 81dc7f6..a39702a 100644
--- a/src/styles/global.css
+++ b/src/styles/global.css
@@ -1789,6 +1789,11 @@ a.today-card:hover {
 
 /* ---- prose ---- */
 
+.prose p a:not(.term) {
+  text-decoration: underline;
+  text-underline-offset: 0.16em;
+}
+
 .prose p {
   margin: 0;
   /* The reader's font-size preference; see the settings block at the end of this file. */
@@ -2591,6 +2596,10 @@ html[data-font='l'] .prose {
   text-align: right;
 }
 
+.palette-list .row:is(.on, :hover, :focus-visible) .palette-meta {
+  color: var(--ink2);
+}
+
 .palette-meta mark {
   background: none;
   color: var(--ink2);
@@ -2604,6 +2613,11 @@ html[data-font='l'] .prose {
   color: var(--ink2);
 }
 
+.palette-note a {
+  text-decoration: underline;
+  text-underline-offset: 0.16em;
+}
+
 .palette-hints {
   display: flex;
   align-items: center;
diff --git a/tests/e2e/a11y.spec.ts b/tests/e2e/a11y.spec.ts
index 6062c17..bee4627 100644
--- a/tests/e2e/a11y.spec.ts
+++ b/tests/e2e/a11y.spec.ts
@@ -2,10 +2,8 @@ import AxeBuilder from '@axe-core/playwright';
 import { test, expect, type Page } from '@playwright/test';
 
 /**
- * Automated accessibility checks. axe catches roughly a third of real barriers, so passing here
- * is a floor rather than a certificate — but a `serious` or `critical` violation is a defect, and
- * this suite fails on one. Both palettes are checked, because the two theme token sets are
- * separate and a fix in one is not a fix in the other.
+ * Automated WCAG 2.2 AA and best-practice checks, including contrast. Every reported violation
+ * fails the check; keyboard workflows are covered separately. Exercise both languages and themes.
  */
 
 const PAGES = [
@@ -23,10 +21,19 @@ const PAGES = [
   '/playground/',
   '/ai/prompt-builder/',
   '/settings/',
+  '/tracks/',
+  '/practice/python/',
+  '/glossary/',
+  '/glossary/closure/',
+  '/about/',
+  '/contribute/',
+  '/rules/python/',
+  '/search/?q=closure',
+  '/offline/',
 ];
 const THEMES = ['light', 'dark'] as const;
 
-const TAGS = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'best-practice'];
+const TAGS = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa', 'best-practice'];
 
 type Theme = (typeof THEMES)[number];
 type Violations = Awaited<ReturnType<typeof scan>>['violations'];
@@ -38,14 +45,13 @@ async function usingTheme(page: Page, theme: Theme): Promise<void> {
   }, theme);
 }
 
-function scan(page: Page, only?: string[]) {
-  const builder = new AxeBuilder({ page }).withTags(TAGS);
-  return (only ? builder.withRules(only) : builder.disableRules(['color-contrast'])).analyze();
+function scan(page: Page) {
+  return new AxeBuilder({ page })
+    .withTags(TAGS)
+    .options({ rules: { 'label-content-name-mismatch': { enabled: true } } })
+    .analyze();
 }
 
-const serious = (violations: Violations) =>
-  violations.filter((v) => v.impact === 'serious' || v.impact === 'critical');
-
 /** Readable failure output: the rule, what it is, and the first element that broke it. */
 function describe(found: Violations): string {
   return found
@@ -53,33 +59,75 @@ function describe(found: Violations): string {
     .join('\n  ');
 }
 
-for (const path of PAGES) {
+for (const path of PAGES.flatMap((path) => [path, `/zh${path}`])) {
   for (const theme of THEMES) {
-    test(`${path} has no serious axe violations in the ${theme} palette`, async ({ page }) => {
+    test(`${path} has no axe violations in the ${theme} palette`, async ({ page }) => {
       await usingTheme(page, theme);
       await page.goto(path);
       await expect(page.locator('html')).toHaveAttribute('data-theme', theme);
 
       // The islands add roles and labels of their own, so let the page settle before scanning.
       await expect(page.locator('[data-palette-ready="true"]')).toBeAttached();
+      if (path.includes('/playground/')) {
+        await expect(page.locator('.playground-example-card').first()).toBeVisible();
+      }
 
       const { violations } = await scan(page);
-      const found = serious(violations);
-      expect(found, `\n  ${describe(found)}`).toEqual([]);
+      expect(violations, `\n  ${describe(violations)}`).toEqual([]);
     });
   }
 }
 
-/* Colour contrast is scanned separately so failures name the affected page and palette. */
-for (const theme of THEMES) {
-  test(`every surface meets the WCAG AA contrast floor in the ${theme} palette`, async ({ page }) => {
-    await usingTheme(page, theme);
-    for (const path of PAGES) {
-      await page.goto(path);
-      const { violations } = await scan(page, ['color-contrast']);
-      expect(violations, `${path} in ${theme}:\n  ${describe(violations)}`).toEqual([]);
+test.describe('search load failures', () => {
+  // A service worker can satisfy an import before Playwright's route interception sees it.
+  test.use({ serviceWorkers: 'block' });
+  for (const path of ['/search/?q=closure', '/zh/search/?q=closure']) {
+    for (const theme of THEMES) {
+      test(`${path} search failure remains accessible in ${theme}`, async ({ page }) => {
+        await usingTheme(page, theme);
+        await page.route('**/pagefind/**', (route) => route.abort());
+        await page.goto(path);
+        await expect(page.locator('.search-results .palette-note a')).toBeVisible();
+        const { violations } = await scan(page);
+        expect(violations, `\n  ${describe(violations)}`).toEqual([]);
+      });
     }
-  });
+  }
+});
+
+for (const path of ['/practice/flashcards/', '/zh/practice/flashcards/']) {
+  for (const theme of THEMES) {
+    test(`${path} active flashcards remain accessible in ${theme}`, async ({ page }) => {
+      await usingTheme(page, theme);
+      await page.addInitScript(() => {
+        localStorage.setItem(
+          'cw:v1:flashcards',
+          JSON.stringify({
+            cards: [
+              {
+                id: 'glossary:closure',
+                kind: 'term',
+                ref: 'glossary:closure',
+                source: 'terms',
+                due: '2000-01-01T00:00:00.000Z',
+                interval: 0,
+                ease: 2.2,
+                reps: 0,
+              },
+            ],
+          }),
+        );
+      });
+      await page.goto(path);
+      const front = page.locator('.flashcard-front');
+      await expect(front).toHaveAccessibleName(/Closure/);
+      for (const flipped of [false, true]) {
+        if (flipped) await front.click();
+        const { violations } = await scan(page);
+        expect(violations, `\n  ${describe(violations)}`).toEqual([]);
+      }
+    });
+  }
 }
 
 test('the article is reachable from the keyboard without walking the whole nav', async ({ page }) => {
@@ -90,6 +138,10 @@ test('the article is reachable from the keyboard without walking the whole nav',
   await expect(skip).toBeFocused();
   await expect(skip).toHaveAttribute('href', '#main');
   await expect(skip).toBeVisible();
+  await page.keyboard.press('Enter');
+  await expect(page.locator('main')).toBeFocused();
+  await page.keyboard.press('Tab');
+  await expect(page.locator('main :focus')).toHaveCount(1);
 });
 
 test('the depth dial is a labelled radio group', async ({ page }) => {
diff --git a/tests/e2e/keyboard.spec.ts b/tests/e2e/keyboard.spec.ts
new file mode 100644
index 0000000..41fa4a9
--- /dev/null
+++ b/tests/e2e/keyboard.spec.ts
@@ -0,0 +1,71 @@
+import AxeBuilder from '@axe-core/playwright';
+import { test, expect } from '@playwright/test';
+
+for (const locale of ['en', 'zh']) {
+  for (const { mobile, theme } of [false, true].flatMap((mobile) =>
+    ['light', 'dark'].map((theme) => ({ mobile, theme })),
+  )) {
+    test(`${locale} ${mobile ? 'mobile' : 'desktop'} ${theme} keyboard search traps and restores focus`, async ({
+      page,
+    }) => {
+      await page.setViewportSize({ width: mobile ? 390 : 1440, height: 844 });
+      await page.addInitScript((theme) => {
+        localStorage.setItem('cw:v1:prefs', JSON.stringify({ theme }));
+      }, theme);
+      await page.goto(locale === 'zh' ? '/zh/' : '/');
+      await expect(page.locator('[data-palette-ready="true"]')).toBeAttached();
+      const opener = page.locator('header [data-palette-open]:visible');
+      // Walk from the start with real Tab presses, including the desktop language dropdown.
+      for (let i = 0; i < 20 && !(await opener.evaluate((el) => el === document.activeElement)); i++) {
+        await page.keyboard.press('Tab');
+      }
+      await expect(opener).toBeFocused();
+      await expect(opener).toHaveCSS('outline-style', 'solid');
+      await page.keyboard.press('Enter');
+      const dialog = page.getByRole('dialog');
+      const input = dialog.getByRole('combobox');
+      await expect(input).toBeFocused();
+      await input.fill(locale === 'zh' ? '闭包' : 'closure');
+      await expect(dialog.getByRole('option').first()).toBeVisible();
+      await page.keyboard.press('Shift+Tab');
+      await expect(dialog.getByRole('option').last()).toBeFocused();
+      await page.keyboard.press('Tab');
+      await expect(input).toBeFocused();
+      const { violations } = await new AxeBuilder({ page })
+        .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa', 'best-practice'])
+        .options({ rules: { 'label-content-name-mismatch': { enabled: true } } })
+        .analyze();
+      expect(violations).toEqual([]);
+      await page.keyboard.press('Escape');
+      await expect(dialog).toHaveCount(0);
+      await expect(opener).toBeFocused();
+    });
+  }
+
+  test(`${locale} mobile navigation closes with Escape and when focus leaves`, async ({ page }) => {
+    await page.setViewportSize({ width: 390, height: 844 });
+    await page.goto(locale === 'zh' ? '/zh/' : '/');
+    const menu = page.locator('.nav-menu');
+    const trigger = menu.locator('summary');
+    for (let i = 0; i < 10 && !(await trigger.evaluate((el) => el === document.activeElement)); i++)
+      await page.keyboard.press('Tab');
+    await expect(trigger).toBeFocused();
+    await page.keyboard.press('Enter');
+    await expect(menu).toHaveAttribute('open', '');
+    await page.keyboard.press('Tab');
+    await expect(menu.locator('.menu-links a').first()).toBeFocused();
+    const { violations } = await new AxeBuilder({ page })
+      .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa', 'best-practice'])
+      .options({ rules: { 'label-content-name-mismatch': { enabled: true } } })
+      .analyze();
+    expect(violations).toEqual([]);
+    await page.keyboard.press('Escape');
+    await expect(menu).not.toHaveAttribute('open');
+    await expect(trigger).toBeFocused();
+    await page.keyboard.press('Enter');
+    for (let i = 0; i < 20 && (await menu.evaluate((el) => el.hasAttribute('open'))); i++)
+      await page.keyboard.press('Tab');
+    await expect(menu).not.toHaveAttribute('open');
+    await expect(page.locator('main :focus')).toHaveCount(1);
+  });
+}
diff --git a/tests/e2e/practice-hub.spec.ts b/tests/e2e/practice-hub.spec.ts
index 4b84dfa..798e202 100644
--- a/tests/e2e/practice-hub.spec.ts
+++ b/tests/e2e/practice-hub.spec.ts
@@ -194,7 +194,7 @@ test('the track chips wrap on desktop, scroll on mobile and navigate between tra
   expect(containment.control).toBeLessThanOrEqual(containment.column);
 
   const rust = chips.locator('a[data-value="rust"]');
-  await expect(rust).toHaveAttribute('aria-label', 'Filter by Rust');
+  await expect(rust).toHaveAccessibleName(/^Rust \d+$/);
   await rust.click();
   await expect(page).toHaveURL('/practice/rust/');
 
diff --git a/tests/e2e/seo.spec.ts b/tests/e2e/seo.spec.ts
index 8f1f2c6..25db6ce 100644
--- a/tests/e2e/seo.spec.ts
+++ b/tests/e2e/seo.spec.ts
@@ -1,4 +1,5 @@
 import { test, expect } from '@playwright/test';
+import { topicFacts } from './fixtures/content';
 
 /**
  * What a crawler sees: the sitemap pair and the head of every page archetype. These run against
@@ -19,8 +20,14 @@ const SAMPLES: { path: string; ld: string }[] = [
   { path: '/zh/python/closures/', ld: 'TechArticle' },
   { path: '/glossary/', ld: 'DefinedTermSet' },
   { path: '/glossary/closure/', ld: 'DefinedTerm' },
+  { path: '/practice/predict/python/closures/predict-loop-binding/', ld: 'BreadcrumbList' },
 ];
 
+test('UTF-8 is declared within the first 1024 bytes', async ({ request }) => {
+  const response = await request.get('/');
+  expect((await response.body()).subarray(0, 1024).toString()).toContain('<meta charset="utf-8">');
+});
+
 test('the sitemap index points at a child sitemap', async ({ request }) => {
   const res = await request.get('/sitemap-index.xml');
   expect(res.status()).toBe(200);
@@ -56,6 +63,13 @@ test('the child sitemap carries both locales and their alternates', async ({ req
   expect(body).toContain(
     '<xhtml:link rel="alternate" hreflang="en" href="https://codewiki.com/python/closures/"/>',
   );
+  expect(body).toContain(
+    '<xhtml:link rel="alternate" hreflang="x-default" href="https://codewiki.com/python/closures/"/>',
+  );
+  const article = body.match(
+    /<url><loc>https:\/\/codewiki\.com\/python\/closures\/<\/loc>[\s\S]*?<\/url>/,
+  )?.[0];
+  expect(article).toContain(`<lastmod>${topicFacts('python', 'closures').modified}`);
 });
 
 test('both About pages carry alternates and are linked from their footer', async ({ page }) => {
@@ -101,7 +115,7 @@ test('the sitemap leaves out the pages that must not be indexed', async ({ reque
 });
 
 for (const { path, ld } of SAMPLES) {
-  test(`${path} carries one canonical, three hreflang links and ${ld}`, async ({ page }) => {
+  test(`${path} carries one canonical, three hreflang links and ${ld}`, async ({ page, request }) => {
     await page.goto(path);
 
     const canonical = page.locator('link[rel="canonical"]');
@@ -118,10 +132,39 @@ for (const { path, ld } of SAMPLES) {
     const blocks = await page.locator('script[type="application/ld+json"]').allTextContents();
     const types = blocks.map((block) => JSON.parse(block)['@type']);
     expect(types).toContain(ld);
+    for (const block of blocks.map((block) => JSON.parse(block))) {
+      if (block['@type'] !== 'BreadcrumbList') continue;
+      for (const item of block.itemListElement) {
+        const response = await request.get(new URL(item.item).pathname);
+        expect(response.status(), `Breadcrumb destination: ${item.item}`).toBe(200);
+      }
+    }
 
     // Every page states a title and a description, and never opts out of indexing by accident.
     await expect(page.locator('meta[name="description"]')).toHaveAttribute('content', /.+/);
     await expect(page.locator('meta[name="robots"]')).toHaveCount(0);
+    await expect(page.locator('meta[property="og:locale:alternate"]')).toHaveAttribute(
+      'content',
+      path.startsWith('/zh/') ? 'en_US' : 'zh_CN',
+    );
+    await expect(page.locator('meta[property="og:image:type"]')).toHaveAttribute('content', 'image/png');
+    await expect(page.locator('meta[property="og:image:alt"]')).toHaveAttribute('content', /.+/);
+    await expect(page.locator('meta[name="twitter:image:alt"]')).toHaveAttribute('content', /.+/);
+    if (ld === 'TechArticle') {
+      const article = blocks
+        .map((block) => JSON.parse(block))
+        .find((block) => block['@type'] === 'TechArticle');
+      await expect(page.locator('meta[property="article:modified_time"]')).toHaveAttribute(
+        'content',
+        article.dateModified,
+      );
+      expect(article.image).toBe(await page.locator('meta[property="og:image"]').getAttribute('content'));
+      expect(
+        await page
+          .locator('meta[property="article:tag"]')
+          .evaluateAll((tags) => tags.map((tag) => tag.getAttribute('content'))),
+      ).toEqual(article.keywords);
+    }
   });
 }
 
diff --git a/tests/unit/seo.test.ts b/tests/unit/seo.test.ts
index 156ed5d..b362994 100644
--- a/tests/unit/seo.test.ts
+++ b/tests/unit/seo.test.ts
@@ -11,6 +11,47 @@ import {
 import { stripMarkdown } from '@/lib/md';
 
 describe('buildHead', () => {
+  it('describes the image and other locale on social cards', () => {
+    const head = buildHead({
+      locale: 'zh',
+      path: '/zh/python/',
+      title: 'Python',
+      description: 'd',
+      kind: 'track',
+    });
+    expect(head.og['og:locale:alternate']).toBe('en_US');
+    expect(head.og['og:image:type']).toBe('image/png');
+    expect(head.og['og:image:alt']).toBe('Python｜CodeWiki');
+    expect(head.twitter['twitter:image:alt']).toBe(head.og['og:image:alt']);
+  });
+
+  it('describes a reused home card without claiming it contains the practice title', () => {
+    const head = buildHead({
+      locale: 'en',
+      path: '/practice/',
+      title: 'Practice',
+      description: 'd',
+      kind: 'page',
+      ogImagePath: '/og/home.png',
+    });
+    expect(head.og['og:image:alt']).toBe('CodeWiki · Master code in the AI era');
+  });
+
+  it('publishes article metadata without inventing a publication date', () => {
+    const head = buildHead({
+      locale: 'en',
+      path: '/python/closures/',
+      title: 'Closures',
+      description: 'd',
+      kind: 'topic',
+      article: { modifiedTime: '2026-09-04', section: 'Functions', tags: ['closures', 'scope'] },
+    });
+    expect(head.og['article:modified_time']).toBe('2026-09-04');
+    expect(head.og['article:section']).toBe('Functions');
+    expect(head.og['article:tag']).toEqual(['closures', 'scope']);
+    expect(head.og).not.toHaveProperty('article:published_time');
+  });
+
   it('formats titles per locale', () => {
     expect(
       buildHead({
diff --git a/tests/unit/sitemap.test.ts b/tests/unit/sitemap.test.ts
new file mode 100644
index 0000000..b271544
--- /dev/null
+++ b/tests/unit/sitemap.test.ts
@@ -0,0 +1,39 @@
+import { contentModificationDates, sitemapMetadata } from '../../scripts/sitemap-metadata';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+describe('sitemap content metadata', () => {
+  it('uses reviewed content dates for localized topics and cheatsheets', () => {
+    const root = mkdtempSync(path.join(tmpdir(), 'codewiki-sitemap-'));
+    try {
+      mkdirSync(path.join(root, 'src/content/topics/python'), { recursive: true });
+      mkdirSync(path.join(root, 'src/content/cheatsheets'), { recursive: true });
+      for (const [file, frontmatter] of Object.entries({
+        'topics/python/closures.en.mdx': 'status: reviewed\nreviewed: 2026-09-04',
+        'topics/python/closures.zh.mdx': 'status: reviewed\nreviewed: 2026-09-05',
+        'topics/python/draft.en.mdx': 'status: draft\nreviewed: 2026-09-04',
+        'cheatsheets/python.en.mdx': 'status: reviewed\nverified: { date: 2026-09-03 }',
+      }))
+        writeFileSync(path.join(root, 'src/content', file), `---\n${frontmatter}\n---\n`);
+      expect([...contentModificationDates(root)]).toEqual([
+        ['/python/closures/', '2026-09-04'],
+        ['/zh/python/closures/', '2026-09-05'],
+        ['/cheatsheets/python/', '2026-09-03'],
+      ]);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('adds the real modification date and the English default alternate', () => {
+    const english = { lang: 'en', url: 'https://codewiki.com/python/closures/' };
+    const chinese = { lang: 'zh-Hans', url: 'https://codewiki.com/zh/python/closures/' };
+    const item = { url: chinese.url, links: [english, chinese] };
+    const result = sitemapMetadata(item, new Map([['/zh/python/closures/', '2026-09-04']]));
+    expect(result.lastmod).toBe('2026-09-04');
+    expect(result.links).toEqual([english, chinese, { lang: 'x-default', url: english.url }]);
+    expect(sitemapMetadata(result, new Map()).links).toHaveLength(3);
+    expect(sitemapMetadata({ url: 'https://codewiki.com/' }, new Map())).not.toHaveProperty('lastmod');
+  });
+});

From b75d11413a3f3cf1cddd40c7d62f9082d15f62a4 Mon Sep 17 00:00:00 2001
From: Tom Chen <tomchen.org@gmail.com>
Date: Tue, 22 Sep 2026 12:29:57 +0200
Subject: [PATCH 2/3] Use English for developer guidance and record validation

---
 docs/dev/seo-a11y-validation-2026-09-22.md     | 18 ++++++++++++++++++
 docs/superpowers/ROADMAP.md                    |  6 +++---
 docs/superpowers/STATUS.md                     |  2 +-
 .../specs/2026-09-03-codewiki-design.md        |  2 +-
 prompts/editorial-standard.md                  |  2 +-
 prompts/translate-topic.md                     |  2 +-
 scripts/content/lib/links.ts                   |  4 ++--
 tests/e2e/fixtures/identifiers.ts              |  4 ++--
 tests/e2e/search.spec.ts                       |  6 +++---
 9 files changed, 32 insertions(+), 14 deletions(-)
 create mode 100644 docs/dev/seo-a11y-validation-2026-09-22.md

diff --git a/docs/dev/seo-a11y-validation-2026-09-22.md b/docs/dev/seo-a11y-validation-2026-09-22.md
new file mode 100644
index 0000000..a548a0f
--- /dev/null
+++ b/docs/dev/seo-a11y-validation-2026-09-22.md
@@ -0,0 +1,18 @@
+# CodeWiki local validation report — 2026-09-22
+
+The fixes are implemented and have not been deployed. At the user's request, the remaining local Lighthouse measurements were stopped and the Chromium processes started for this audit were closed. The local Lighthouse gate covering 11 pages did not finish; GitHub CI will complete the gate on the pull request.
+
+- Lint, formatting and type checks passed; the build succeeded.
+- All 2,427 unit tests and 364 Chromium browser tests passed.
+- Accessibility checks cover 23 page types in English and Chinese, light and dark themes, search dialogs, failure states, both sides of review cards, and keyboard interactions.
+- All 155,274 internal links and structured-data destinations resolve.
+- SEO metadata checks passed for 5,909 pages; all 2,349 OG images exist and measure 1200×630.
+- The sitemap contains 5,902 URLs, all with x-default alternates; 598 URLs with reliable content dates include lastmod.
+- robots.txt, llms.txt and llms-full.txt exist; missing applicable OG/Twitter tags, article metadata and JSON-LD fields have been added.
+
+The table includes only completed Lighthouse measurements from this audit. Scores are medians of the completed runs; pages with incomplete measurements are not claimed to have passed.
+
+| Page | Completed runs | Performance | Accessibility | Best practices | SEO |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| /index.html | 3 | 99 | 100 | 100 | 100 |
+| /python/index.html | 1 | 88 | 100 | 100 | 100 |
diff --git a/docs/superpowers/ROADMAP.md b/docs/superpowers/ROADMAP.md
index bb86535..50a4fc7 100644
--- a/docs/superpowers/ROADMAP.md
+++ b/docs/superpowers/ROADMAP.md
@@ -10,7 +10,7 @@ Legend: **[user]** = needs a decision or action from the owner · **[design]** =
 
 Small changes with the largest effect on first impressions and credibility.
 
-- [x] **A1. Home page leads with a review kata.** [design → Opus] Move the daily kata (每日一练) card to the first screen as the hero ("Review this generated code before you would ship it"), with the search palette mock and the article entry points below it. Navigation order: Practice before Tracks. Keep the palette mock capped at four rows.
+- [x] **A1. Home page leads with a review kata.** [design → Opus] Move the daily kata card to the first screen as the hero ("Review this generated code before you would ship it"), with the search palette mock and the article entry points below it. Navigation order: Practice before Tracks. Keep the palette mock capped at four rows.
 - [x] **A2. Honest framing.** [Codex] Home tagline copy, About page and `home.sub`: replace "most first drafts are written by AI / the skill has become…" with "AI increasingly writes code; developers still have to understand implementations, state constraints and verify results." About page gains a section "How this content is made": AI-assisted drafts, every example executed, editorial standard, human spot checks, open corrections.
 - [x] **A3. Visible verification on every topic.** [design → Opus] A small verification panel near the title: target environment with the exact patch version used (e.g. Python 3.14.2), the date the examples last ran, "N of N outputs matched", and a link to the checker log. Data comes from `content:check` writing a per-topic sidecar (`reports/verify/{track}/{slug}.json`) that the build reads. Distinguish **target environment** (what the article pins) from **the in-browser runner** (Pyodide's Python version, esbuild for TS, sql.js): label runnable blocks with the runner and its version; mark blocks whose output was recorded only on the target environment.
 - [x] **A4. Report an error.** [Codex] A "Report an error" link on every topic, kata and interview page that opens a prefilled GitHub issue (title, URL, section). Requires the repository URL to be real (see A7).
@@ -36,7 +36,7 @@ Deepens the training side. Each item is a small design + implementation task; B1
 
 ## Phase C — later
 
-- [ ] **C1. Distribution.** [user] Chinese channels (掘金, 知乎, V2EX) for the Chinese edition; measure mainland access speed and decide on a mirror if needed.
+- [ ] **C1. Distribution.** [user] Chinese channels (Juejin, Zhihu, V2EX) for the Chinese edition; measure mainland access speed and decide on a mirror if needed.
 - [ ] **C2. Tier 2 polish (423 topics), flagship tracks first.** Deferred by the user on 2026-09-04. Estimate at 10-way parallelism: ~6 h wall, ~79 M Codex tokens. Command: `pnpm content:polish --tier 2 --n 10 --max 100` per batch from `.worktrees/p0-content-pipeline`. Before running it, solve the Cloudflare Pages 20,000-file ceiling (Pagefind fragment size, OG images) or change hosts.
 - [ ] **C3. Tier 3 polish (238 topics).** After C2.
 - [ ] **C4. Visualizer tools and compare pages.** Deferred until after launch (2026-09-05); decide from which topics readers actually use. The cheatsheet footer still shows "compared with other languages · soon".
@@ -51,4 +51,4 @@ Deepens the training side. Each item is a small design + implementation task; B1
 
 ## Done (for orientation)
 
-P0 content pipeline · P1 site foundation · P2 learning layer · tier-1 content wave (287 topics, 6 paths, 12 cheatsheets, 1,146 interview items, 1,733 practice items) · real-content UI fixes · content taxonomy pass · whole-site review and its fix round · daily kata (每日一练) · PWA offline · About page · full gate green on `main` (2026-09-05). Codex usage to date ≈ 60 M tokens.
+P0 content pipeline · P1 site foundation · P2 learning layer · tier-1 content wave (287 topics, 6 paths, 12 cheatsheets, 1,146 interview items, 1,733 practice items) · real-content UI fixes · content taxonomy pass · whole-site review and its fix round · daily kata · PWA offline · About page · full gate green on `main` (2026-09-05). Codex usage to date ≈ 60 M tokens.
diff --git a/docs/superpowers/STATUS.md b/docs/superpowers/STATUS.md
index 0be735d..bb930f5 100644
--- a/docs/superpowers/STATUS.md
+++ b/docs/superpowers/STATUS.md
@@ -18,7 +18,7 @@ Read this first in any new session. Update it at every milestone and before star
 - 2026-09-03 AI-era integration added to spec §6.1 (content: "In the AI era" block per topic, ai-era track, rules packs, review katas; form: prompt-ready pages, JSON API, MCP server later).
 - 2026-09-03 Execution mode: subagent-driven development, one Opus subagent per plan task, Fable reviews between tasks. P1 first (Tasks 0–8), then P0 in parallel once P1 Task 6 (schemas) exists.
 - 2026-09-04 P2 learning-layer mockups drafted by Fable (practice hub, review-the-AI's-code kata, flashcards, interview bank, cheatsheet, bilingual topic, prompt builder; light + dark). Sources `docs/design/mockups/p2/`, canvas: https://claude.ai/code/artifact/23900b82-1533-43f2-b3fc-eeb05070c137 — awaiting user review before the P2 plan.
-- 2026-09-04 P2 sub-spec `docs/superpowers/specs/2026-09-04-p2-learning-layer-design.md` approved (user: “你自己决策，选最佳的”); decisions: 4 flashcard ratings, 2-column print, paired bilingual default, kata with line comments, CodeMirror 6 lazy. Next: P2 plan.
+- 2026-09-04 P2 sub-spec `docs/superpowers/specs/2026-09-04-p2-learning-layer-design.md` approved (user instruction, translated: “Use your judgment and choose the best option”); decisions: 4 flashcard ratings, 2-column print, paired bilingual default, kata with line comments, CodeMirror 6 lazy. Next: P2 plan.
 - 2026-09-03 Spec approved by user: `docs/superpowers/specs/2026-09-03-codewiki-design.md` (including §6.1 AI-era integration).
 
 ## Earlier milestones (2026-09-05 09:30 local; current state below)
diff --git a/docs/superpowers/specs/2026-09-03-codewiki-design.md b/docs/superpowers/specs/2026-09-03-codewiki-design.md
index 7ad4e89..5ec200a 100644
--- a/docs/superpowers/specs/2026-09-03-codewiki-design.md
+++ b/docs/superpowers/specs/2026-09-03-codewiki-design.md
@@ -334,7 +334,7 @@ Shell: `Nav`, `Footer`, `Search` (island: palette), `ThemeToggle` (island), `Lan
 - Structure: **TL;DR** (3 cells) → **What it is / why it exists** → **How it works** (mechanics, one diagram if it helps) → **Examples** (runnable, realistic, with outputs produced by running them) → **Pitfalls** (merged with "best practices"; each pitfall states the fix) → **In the AI era** (what generated code gets wrong here, what to ask your AI to check, a 3-item review checklist, prompt vocabulary) → **Deep dive** (marked `deep`; internals, edge cases, performance with numbers or nothing) → **Checkpoint** (3–8 items, YAML sidecar, at least one `predict` and, where the topic allows, one `review` item) → **Further reading** (only links verified by fetching; official docs first). Interview questions go to the interview sidecar, not the article.
 - Length 400–900 lines including code. No "In this article", "comprehensive guide", "By mastering…". No rule-of-three padding. Prose written for a smart colleague.
 - Currency: verified against a named version as of 2026 (e.g. Python 3.14, Node 24, TypeScript 6, Go 1.27, Rust 1.98, React 19, Java 25 LTS, LangChain 1.x, current Claude/OpenAI SDKs); flag deprecated APIs explicitly.
-- English: native, direct, present tense. Chinese: 地道的技术写作，术语一致（以术语表为准），中西文之间加空格，全角标点，不使用翻译腔句式。
+- English: native, direct, present tense. Chinese: natural technical writing, consistent terminology from the glossary, a space between Chinese characters and adjacent Latin text, Chinese punctuation, and no translationese.
 - Bilingual: the canonical language is chosen per topic (the better draft); the other language is a faithful paragraph-aligned translation; code identical; headings 1:1.
 - Diagrams: Mermaid where a structure/flow helps (rendered to SVG at build); no decorative images.
 - Every claim about behaviour must be backed by a runnable example or a cited primary source.
diff --git a/prompts/editorial-standard.md b/prompts/editorial-standard.md
index e63e474..1ac0a80 100644
--- a/prompts/editorial-standard.md
+++ b/prompts/editorial-standard.md
@@ -32,7 +32,7 @@ Sections 3–6 are `standard` depth by default. Mark the first example and the T
 ## 4. Voice
 
 - English: native, direct, present tense, second person where natural. Contractions are fine. Prefer short sentences. Technical terms are used precisely and consistently with the glossary.
-- Chinese: 地道的中文技术写作，不是翻译腔。段落同样以两到五句为一段，围绕一个意思展开；不要一句一段。用短句，主谓宾清楚。术语以术语表为准；首次出现的术语给出英文原文，例如「闭包（closure）」。中西文之间加一个空格（「Python 3.14 的 `asyncio`」），全角标点（，。；：？！「」），代码、数字、英文单词之间不用全角标点。不用「本文将」「让我们」「值得注意的是」。
+- Chinese: write natural technical Chinese, without translationese. Use two to five sentences per paragraph to develop one idea; do not put every sentence in its own paragraph. Prefer short sentences with a clear subject, verb and object. Follow the glossary and include the English term on first mention, for example 「闭包（closure）」. Put one space between Chinese characters and adjacent Latin text, as in 「Python 3.14 的 `asyncio`」. Use Chinese punctuation (，。；：？！「」) in Chinese prose, but not between code tokens, numbers or English words. Avoid 「本文将」「让我们」「值得注意的是」.
 - Both: no emoji, no exclamation marks, no marketing adjectives.
 - MDX: raw `<` or `>` in prose must be escaped as an HTML entity or placed in inline code.
 
diff --git a/prompts/translate-topic.md b/prompts/translate-topic.md
index 9817598..f282daf 100644
--- a/prompts/translate-topic.md
+++ b/prompts/translate-topic.md
@@ -14,7 +14,7 @@ Use this brief when a topic already has one language at `status: reviewed` and t
 
 1. Read the source fully. Note every heading, paragraph, list, code block, callout, component and their order. The target must have the same sequence of blocks.
 2. Write the target file. Translate prose faithfully and natively. Keep identifiers, commands, file names, URLs, error messages and code verbatim; translate code comments only. Keep `<TLDR>`, `<Depth>`, `<Term id>`, `<Checkpoint>` and fence meta exactly as in the source. Translate only `title` and `description` in the frontmatter; copy every other frontmatter field unchanged.
-3. Chinese targets: 中西文之间加空格，全角标点，术语首次出现附英文原文，不用翻译腔句式。English targets: native, direct, present tense.
+3. Chinese targets: put a space between Chinese characters and adjacent Latin text, use Chinese punctuation, include the English term on first mention, and avoid translationese. English targets: native, direct, present tense.
 4. Run `pnpm content:align {{TOPIC_ID}}` and `pnpm content:check {{TOPIC_ID}}`; fix until both print `OK`.
 5. Print `TRANSLATE DONE {{TOPIC_ID}}` as the last line, or `TRANSLATE FAILED {{TOPIC_ID}}: {reason}`.
 
diff --git a/scripts/content/lib/links.ts b/scripts/content/lib/links.ts
index 7b78212..756f95a 100644
--- a/scripts/content/lib/links.ts
+++ b/scripts/content/lib/links.ts
@@ -229,7 +229,7 @@ function count(text: string, char: string): number {
 
 /**
  * Headings that open a further-reading section, in both languages. Anchored on purpose:
- * a substring match turns every `Rvalue References` or `快速参考表` section — 241 of the
+ * a substring match turns every `Rvalue References` or Chinese quick-reference section — 241 of the
  * 1436 candidates in the staging corpus — into a wall of false book titles.
  */
 const READING_HEADING = /^(further reading|延伸阅读|references|参考(资源|资料|文献|链接)?)$/i;
@@ -246,7 +246,7 @@ const LIST_MARKER = /^\s*(?:[-*+]|\d+[.)])\s+/;
 /**
  * Book titles named in a further-reading section without being linked.
  *
- * The corpus cites books as `《书名》`, `_Title_` or `*Title*`, and sometimes as plain
+ * The corpus cites books as `《Title》`, `_Title_` or `*Title*`, and sometimes as plain
  * text followed by an author (`Clean Code by Robert C. Martin`). None of those can be
  * verified automatically, so every match is reported for a human to confirm. Entries that
  * carry a link or a URL are left alone — {@link checkLinks} already vouches for those.
diff --git a/tests/e2e/fixtures/identifiers.ts b/tests/e2e/fixtures/identifiers.ts
index 0980771..6e2c24d 100644
--- a/tests/e2e/fixtures/identifiers.ts
+++ b/tests/e2e/fixtures/identifiers.ts
@@ -2,8 +2,8 @@
  * Technical identifiers that stay in English on a Chinese page.
  *
  * `prompts/editorial-standard.md` §3 requires a library, framework, protocol or keyword to keep
- * its own name: a reader looking for `asyncio` in the docs will not find 「异步IO」. Most such
- * names are recognisable by shape — a digit, a dot, a `+`, a `#`, or a capital inside the word —
+ * its own name: a reader looking for `asyncio` will not find a translated label for asynchronous I/O.
+ * Most such names are recognisable by shape — a digit, a dot, a `+`, a `#`, or a capital inside the word —
  * and `localization.spec.ts` accepts those without a list. This file is for the rest: names that
  * are ordinary lower-case or capitalised words and would otherwise read as untranslated UI text.
  *
diff --git a/tests/e2e/search.spec.ts b/tests/e2e/search.spec.ts
index e6c81b6..354f36e 100644
--- a/tests/e2e/search.spec.ts
+++ b/tests/e2e/search.spec.ts
@@ -35,7 +35,7 @@ test('the palette searches the Chinese index on the Chinese home page', async ({
   const dialog = await openPalette(page);
   await dialog.getByRole('combobox').fill('闭包');
 
-  // Ranking between the five "闭包" topics is a Pagefind judgement, not a contract; that the
+  // Ranking between the five Chinese closure topics is a Pagefind judgement, not a contract; that the
   // Chinese index answers a Chinese query with Chinese routes is the behaviour under test.
   await expect(dialog.locator('[role="option"][href="/zh/python/closures/"]')).toHaveCount(1);
   const hrefs = await dialog
@@ -84,7 +84,7 @@ test('Enter belongs to whichever control has focus', async ({ page }) => {
   await dialog.getByRole('combobox').fill('closure');
   await expect(dialog.locator('[role="option"][href="/python/closures/"]')).toHaveCount(1);
 
-  // Past the field, past the EN half, onto 中文.
+  // Past the field, past the English language button, onto the Chinese language button.
   await page.keyboard.press('Tab');
   await page.keyboard.press('Tab');
   const zh = dialog.getByRole('button', { name: 'Chinese' });
@@ -104,7 +104,7 @@ test('Tab focus makes a palette result the active option', async ({ page }) => {
   // Retrying locator assertion: the query is debounced, so a bare count can read zero.
   await expect(dialog.getByRole('option').nth(1)).toBeVisible();
 
-  // input → EN → 中文 → esc → first result → second result
+  // input → English → Chinese → close → first result → second result
   for (let index = 0; index < 5; index += 1) await page.keyboard.press('Tab');
   const second = dialog.getByRole('option').nth(1);
   const secondId = await second.getAttribute('id');

From f817e703962652ed112744df79ff451c0d8c39ab Mon Sep 17 00:00:00 2001
From: Tom Chen <tomchen.org@gmail.com>
Date: Tue, 22 Sep 2026 12:31:29 +0200
Subject: [PATCH 3/3] Link the validation record to pull request checks

---
 docs/dev/seo-a11y-validation-2026-09-22.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/dev/seo-a11y-validation-2026-09-22.md b/docs/dev/seo-a11y-validation-2026-09-22.md
index a548a0f..df3dbed 100644
--- a/docs/dev/seo-a11y-validation-2026-09-22.md
+++ b/docs/dev/seo-a11y-validation-2026-09-22.md
@@ -1,6 +1,6 @@
 # CodeWiki local validation report — 2026-09-22
 
-The fixes are implemented and have not been deployed. At the user's request, the remaining local Lighthouse measurements were stopped and the Chromium processes started for this audit were closed. The local Lighthouse gate covering 11 pages did not finish; GitHub CI will complete the gate on the pull request.
+This report records local validation before deployment. At the user's request, the remaining local Lighthouse measurements were stopped and the Chromium processes started for this audit were closed. The local Lighthouse gate covering 11 pages did not finish. The complete gate runs in [PR #1's GitHub CI checks](https://github.com/codewiki-com/codewiki/pull/1/checks), with reports retained in the `test-artifacts` artifact for seven days. The local measurements below are historical evidence, not the final CI result.
 
 - Lint, formatting and type checks passed; the build succeeded.
 - All 2,427 unit tests and 364 Chromium browser tests passed.