From fd42675d3db31f062d0f47ab4f00a33e3d4b7d41 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 5 Aug 2026 15:33:55 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=94=97=20docs:=20link=20the=20live=20site?=
 =?UTF-8?q?,=20now=20that=20Pages=20is=20confirmed?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Pages serves docs/ from main, so the page rebuilt in #6 is live at
avalon-vanguard.github.io/cereale. The README pointed at the local file
because the URL could not be verified from here; it now links the site and
keeps the local instructions as the fallback. package.json homepage moves
there too — npm renders it as the package's headline link, and a live
playground is a better landing spot than an anchor inside the README.

Adds canonical and Open Graph tags. No og:image: a preview card with a
broken image is worse than one without, and there is no artwork yet.

check-docs.mjs flagged the canonical link as a remote subresource, which it
is not — the browser never fetches it. Rather than exempt the URL, the
check now looks at rel and only flags the relations that actually fetch or
connect. Verified it still catches a CDN stylesheet, a preconnect and a
script src; a check that cannot tell a declaration from a request is one
that gets switched off the first time it is wrong.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SAcqrz3FcadkYr3xG32CjK
---
 README.md              |  7 ++++---
 docs/index.html        | 12 ++++++++++++
 package.json           |  2 +-
 scripts/check-docs.mjs | 22 +++++++++++++++++++++-
 4 files changed, 38 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index a2f8902..b308c8d 100644
--- a/README.md
+++ b/README.md
@@ -25,9 +25,10 @@ const user = fromJsonSync(User, body);   // a real User
 user.greet();                            // your methods are still there
 ```
 
-`docs/index.html` is a self-contained page with an interactive playground that runs this
-library in the browser. Build its assets with `npm run build:docs` and open the file — it
-loads nothing from the network.
+**[avalon-vanguard.github.io/cereale](https://avalon-vanguard.github.io/cereale/)** — an
+interactive playground that runs this library in your browser, the full decorator reference,
+and the toolchain matrix. The page is self-contained and loads nothing from the network; it is
+served from `docs/` on `main`, and `npm run build:docs` rebuilds its assets to open locally.
 
 ## Where it fits
 
diff --git a/docs/index.html b/docs/index.html
index a8b8ca1..adc51bf 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -6,8 +6,20 @@
 <title>cereale — validated domain objects, not validated data</title>
 <meta name="description" content="Zero-dependency JSON mapping and validation for TypeScript classes. Maps JSON onto your own classes and checks the validation rules against the fields they are attached to, at compile time.">
 <meta name="color-scheme" content="light dark">
+<link rel="canonical" href="https://avalon-vanguard.github.io/cereale/">
 <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>🌾</text></svg>">
 
+<!-- Link previews. No og:image: a preview card with a broken image is worse than one
+     without, and there is no artwork to point at yet. -->
+<meta property="og:type" content="website">
+<meta property="og:url" content="https://avalon-vanguard.github.io/cereale/">
+<meta property="og:site_name" content="cereale">
+<meta property="og:title" content="cereale — validated domain objects, not validated data">
+<meta property="og:description" content="Zero-dependency JSON mapping and validation for TypeScript classes. Maps JSON onto your own classes and checks every rule against the field it is attached to, at compile time.">
+<meta name="twitter:card" content="summary">
+<meta name="twitter:title" content="cereale — validated domain objects, not validated data">
+<meta name="twitter:description" content="Zero-dependency JSON mapping and validation for TypeScript classes. Rules are checked against fields at compile time.">
+
 <style>
 /* ---------------------------------------------------------------- tokens */
 :root {
diff --git a/package.json b/package.json
index c935374..6fb0ce8 100644
--- a/package.json
+++ b/package.json
@@ -68,7 +68,7 @@
   "bugs": {
     "url": "https://github.com/avalon-vanguard/cereale/issues"
   },
-  "homepage": "https://github.com/avalon-vanguard/cereale#readme",
+  "homepage": "https://avalon-vanguard.github.io/cereale/",
   "devDependencies": {
     "@babel/standalone": "^8.0.4",
     "@eslint/js": "^10.0.1",
diff --git a/scripts/check-docs.mjs b/scripts/check-docs.mjs
index 56c03f5..87512c1 100644
--- a/scripts/check-docs.mjs
+++ b/scripts/check-docs.mjs
@@ -22,12 +22,23 @@ const failures = [];
 /** Subresource references — the things a browser fetches without being clicked. */
 const SUBRESOURCES = [
   [/<script\b[^>]*\bsrc\s*=\s*["']([^"']+)["']/gi, 'script src'],
-  [/<link\b[^>]*\bhref\s*=\s*["']([^"']+)["']/gi, 'link href'],
   [/<(?:img|iframe|video|audio|source|embed)\b[^>]*\bsrc\s*=\s*["']([^"']+)["']/gi, 'media src'],
   [/@import\s+(?:url\()?["']([^"']+)["']/gi, 'css @import'],
   [/url\(\s*["']?(https?:\/\/[^)"']+)/gi, 'css url()'],
 ];
 
+/**
+ * `<link>` relations the browser actually fetches or connects to.
+ *
+ * Checked against `rel` rather than flagging every `<link href>`, because the metadata
+ * relations — `canonical` above all — are declarations about the document, not requests. A
+ * check that cannot tell the difference gets switched off the first time it is wrong.
+ */
+const FETCHING_REL = new Set([
+  'stylesheet', 'icon', 'shortcut icon', 'apple-touch-icon', 'apple-touch-icon-precomposed',
+  'manifest', 'preload', 'modulepreload', 'prefetch', 'prerender', 'preconnect', 'dns-prefetch',
+]);
+
 const isRemote = (url) => /^(?:https?:)?\/\//i.test(url);
 
 const html = (await readdir(docs)).filter((name) => name.endsWith('.html'));
@@ -40,6 +51,15 @@ for (const name of html) {
       if (isRemote(match[1])) failures.push(`docs/${name}: remote ${kind} — ${match[1]}`);
     }
   }
+
+  for (const match of source.matchAll(/<link\b([^>]*)>/gi)) {
+    const attrs = match[1];
+    const rel = (/\brel\s*=\s*["']([^"']+)["']/i.exec(attrs)?.[1] ?? '').trim().toLowerCase();
+    const href = /\bhref\s*=\s*["']([^"']+)["']/i.exec(attrs)?.[1];
+    if (href && isRemote(href) && FETCHING_REL.has(rel)) {
+      failures.push(`docs/${name}: remote link rel="${rel}" — ${href}`);
+    }
+  }
   // A fetch to a CDN would not be caught by the markup scan.
   for (const match of source.matchAll(/\b(?:fetch|importScripts)\(\s*["'`](https?:\/\/[^"'`]+)/gi)) {
     failures.push(`docs/${name}: remote fetch — ${match[1]}`);