feat(seo): source-level SEO overhaul (canonical, hreflang, JSON-LD, per-page OG, sitemap) (#480)

* docs(seo): add SEO overhaul design spec

Design doc for the source-level SEO overhaul: canonical + hreflang via
the existing head-rewrite middleware fed by a baked route->locales map,
meta-description fallback, JSON-LD, sitemap lastmod/alternates, per-page
OG images, and head polish. Deployment/migration explicitly out of scope.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(seo): add SEO overhaul implementation plan

11 TDD tasks: pure seo/ url+hreflang+jsonld helpers, baked route-map.gen.ts,
head-middleware injection, sitemap lastmod/alternates, content descriptions,
blog dates, per-page OG images, and head polish.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(seo): add pure canonical/locale URL helpers

* docs(seo): fix plan neutralPath to match splitLocale (en not stripped)

* feat(seo): generate committed route->locales + blog-date map

* feat(seo): add hreflang alternate link builder

* feat(seo): add JSON-LD builder (WebSite/Org/TechArticle/BlogPosting)

* docs(seo): fix plan JSON-LD breadcrumb existsByPage to per-locale Record

* feat(seo): inject canonical, hreflang, JSON-LD, desc fallback in head middleware

* feat(seo): sitemap git lastmod + xhtml:link hreflang alternates

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(seo): add meta descriptions to concept + function + module-init docs

* docs(seo): Task 8 guard - maintain blog dates in pages/, never run convert-content

* feat(seo): add blog dates + descriptions (fixes RSS + BlogPosting date)

* feat(seo): generate per-page OG images at build (satori + resvg)

Docs + blog routes get a branded 1200x630 title card at
dist/client/og/<route>.png via satori (React node -> SVG) + resvg
(SVG -> PNG). Islands keep the static og-v2.png. Fonts come from the
static TTFs shipped by @expo-google-fonts (Manrope 700 title, Inter 600
wordmark, Noto Sans SC 700 as CJK fallback so cn titles render).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(seo): move OG build deps to devDependencies; lazy-load OG fonts

satori + @resvg/resvg-js are build-only (imported only by
scripts/generate-og-images.mjs via vite.config.ts); move them from
dependencies to devDependencies so all five build-only packages (incl the
three @expo-google-fonts/*) live together.

Read the three font TTFs (~11 MB) lazily + memoized in a getFonts()
accessor instead of at module top level, so importing the module (dev
server, vp test) no longer reads them; only renderOg does. Output PNGs
are byte-identical.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(seo): per-page og:image + twitter card; drop static image duplicates

* fix(seo): use en OG image on i18n-fallback pages (avoid 404 cn/pt-BR og:image)

* feat(seo): localized h1s, PWA manifest, theme-color, apple-touch-icon, img alt

* fix(seo): escape head/JSON-LD, argv git, fallback JSON-LD locale, trailing-slash canonical

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(seo): decode pre-encoded head values before re-escaping (no double-encode)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(seo): normalize /en prefix in og:image path (avoid /og/en/*.png 404)

The deploy prerenderer dispatches pages by their internal `/en/docs|blog/…`
route, bypassing the edge `/en/* -> /:splat` redirect, so a non-fallback en
page reaches ogImageUrl with a raw `en/` prefix. og-image.ts derived the
served path from the raw publicPath, emitting `https://napi.rs/og/en/docs/….png`
— a PNG the generator never writes (en cards are unprefixed), so crawlers of
the baked HTML got a 404 og:image. canonical/og:url were already correct
(selfCanonical normalizes en -> root); only og:image leaked the prefix.

Rebuild `served` from (locale + neutral) to mirror fileToRoute's shape: default
locale drops its prefix, cn/pt-BR keep theirs. Adds regression tests for the
/en/ (+ trailing slash) and pt-BR cases.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Brooooooklyn

components/landing/features/optimized-performance.tsx

@@ -143,7 +143,7 @@ export const OptimizedPerformanceCard: React.FC = ({
           </svg>
 
           <span className="brand-text">
-            <img src={logo} width={20} height={20} /> NAPI-RS
+            <img src={logo} alt="NAPI-RS logo" width={20} height={20} /> NAPI-RS
           </span>
 
           <div className="checkmark-container">

components/link-preview.tsx

@@ -66,6 +66,7 @@ export function LinkPreview({ href, data }: { href: string; data?: string }) {
   const logo = href.includes('mozilla') ? (
     <img
       src={mdnLogo}
+      alt="MDN"
       style={{ verticalAlign: 'text-bottom', marginRight: '4px' }}
       width={16}
       height={16}

components/title.pt-BR.jsx

@@ -1,8 +1,12 @@
 import { NodeJS, Rust } from './lang'
 
+// Root is an `<h1>` (was a `<p>`) so the localized landing has exactly one
+// top-level heading, matching the en hero. `.page-landing-locale h1` in
+// landing.css resets the browser-default h1 sizing/margins back to the prose
+// `p` values, so this stays visually identical to the previous paragraph.
 export const TitlePTBR = () => (
-  <p>
+  <h1>
     <span style={{ fontSize: '36px', fontWeight: 'bold' }}>NAPI-RS</span> é um
     framework para construir addons pré-compilados para <NodeJS /> em <Rust />.
-  </p>
+  </h1>
 )

components/title.zh.jsx

@@ -1,8 +1,12 @@
 import { NodeJS, Rust } from './lang'
 
+// Root is an `<h1>` (was a `<p>`) so the localized landing has exactly one
+// top-level heading, matching the en hero. `.page-landing-locale h1` in
+// landing.css resets the browser-default h1 sizing/margins back to the prose
+// `p` values, so this stays visually identical to the previous paragraph.
 export const TitleZH = () => (
-  <p>
+  <h1>
     <span style={{ fontSize: '36px', fontWeight: 'bold' }}>NAPI-RS</span>{' '}
     是一个使用 <Rust /> 构建预编译 <NodeJS /> 原生扩展的框架
-  </p>
+  </h1>
 )

content/docs/concepts/class.cn.mdx

@@ -1,5 +1,6 @@
 ---
 title: '类'
+description: 使用 NAPI-RS 将 Rust 结构体定义并导出为 JavaScript 类。
 ---
 
 # 类

content/docs/concepts/class.en.mdx

@@ -1,5 +1,6 @@
 ---
 title: 'Class'
+description: Define and export Rust structs as JavaScript classes with NAPI-RS.
 ---
 
 # Class

content/docs/concepts/class.pt-BR.mdx

@@ -1,5 +1,6 @@
 ---
 title: 'Class'
+description: Defina e exporte structs de Rust como classes JavaScript com NAPI-RS.
 ---
 
 # Classe

content/docs/concepts/enum.cn.mdx

@@ -1,5 +1,6 @@
 ---
 title: '枚举'
+description: 使用 NAPI-RS 将 Rust 枚举映射为 JavaScript 字符串联合类型和数字枚举。
 ---
 
 # 枚举

content/docs/concepts/enum.en.mdx

@@ -1,5 +1,6 @@
 ---
 title: 'Enum'
+description: Map Rust enums to JavaScript string unions and numeric enums in NAPI-RS.
 ---
 
 # Enum

content/docs/concepts/enum.pt-BR.mdx

@@ -1,5 +1,6 @@
 ---
 title: 'Enum'
+description: Mapeie enums de Rust para uniões de strings e enums numéricos em JavaScript com NAPI-RS.
 ---
 
 # Enum