@koehler8/cms 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # Changelog
 
+## 1.4.0
+
+### Changed
+
+- **The bundled Pinia is now 4.x (was 3.x).** `createPinia()` runs Pinia 4.0.3
+  and that is the instance handed to every extension through
+  `runExtensionSetups({ app, router, pinia, ... })`.
+
+  **If you maintain an extension that declares `peerDependencies.pinia`, widen
+  it to admit `^4`** — for example `"pinia": "^3.0.0 || ^4.0.0"`. An extension
+  pinned to `^3` will fail to install alongside this release.
+  (`@koehler8/cms-ext-crypto` 1.0.0-beta.4 is in exactly that position; it is
+  not installed on any site in the fleet.)
+
+  Nothing else about extensions changes: the instance is still a single Pinia
+  per site — this package deliberately excludes `vue`, `vue-router` and `pinia`
+  from Vite's dependency pre-bundling so a linked extension cannot end up with
+  a second copy — and `vue-router` 5.3.1 already accepts `pinia@4`
+  (`^3.0.4 || ^4.0.2`).
+
+  Two consequences worth knowing, neither of which needs action in a site:
+
+  - Pinia 4 makes `@vue/devtools-api` a **required peer** at `^8.1.5`, where
+    Pinia 3 carried it as a dependency. npm installs it automatically; on a
+    consumer site the resolved version moves 7.x → 8.x, which also lets
+    `vue-router`'s own nested copies collapse into the hoisted one. In this
+    repo that made the lockfile *smaller* (318 → 307 entries).
+  - Pinia 4 is ESM-only and depends on `nostics`. That package was already
+    present in this tree, so no new package enters a site's dependency graph.
+
+  No framework source change was needed: this package defines no store of its
+  own and uses none of the APIs Pinia changed.
+
+### Internal (not shipped)
+
+- Dev dependency `vitest` 4.1.11 → 5.0.1 (with `@vitest/coverage-v8`). This
+  restores the repo's ability to regenerate its own `package-lock.json` under
+  npm 10: on `vitest` 4.1.x a fresh `npm install` died in arborist with
+  `Cannot read properties of null (reading 'edgesOut')`, and only the existing
+  lockfile kept the repo installable. Neither package ships.
+
+## 1.3.1
+
+### Fixed
+
+- **`<html lang>` now follows the language actually on screen (WCAG 2.2
+  SC 3.1.1, Level A).** On a multi-locale site, a returning visitor's saved
+  locale is restored onto the unprefixed base URL: visit `/de`, then `/`, and
+  the content swaps to German while the URL stays `/`. `usePageMeta` derived
+  `lang` from the *route* — which has no locale at `/` — so the page declared
+  `lang="en"` over German text, and a screen reader read it with English
+  pronunciation rules. `og:locale`, the canonical and the breadcrumb JSON-LD
+  described the English page too, while `<title>` was already German.
+
+  `usePageConfig` now exposes `contentLocale` — the locale whose content is
+  currently applied — and `Home.vue` keys `usePageMeta` off that instead of the
+  route param, so the whole head describes the rendered page (`lang="de"`,
+  `og:locale=de`, canonical `/de`). The new `resolveContentLocale()` in
+  `loadConfig.js` shares its "explicit, else saved" rule with `loadConfigData`
+  so the two can't drift; a saved locale with no content on disk loads the base
+  tree and therefore resolves to the base locale.
+
+  No SSG or hydration change: the server has no storage, and the first client
+  render still reproduces the route's locale from the primed cache —
+  `contentLocale` only moves once different-locale content has been applied,
+  after mount. `diff-ssg-dist` on a 15-locale site (62 pages): identical.
+  Pre-existing since the saved-locale restore shipped; reproduced on 1.1.0.
+
+- **Engagement events report the rendered locale.** `Home.vue` passed the
+  route's locale param to `useEngagementTracking`, and an event-level `locale`
+  overrides the tracking context's own (read from `<html lang>`). So scroll-
+  depth and section-view events carried `locale: ''` for every base-locale page
+  — and for saved-locale content restored onto an unprefixed URL — while every
+  other event on the same page said `en` / `de`. They now use `contentLocale`
+  too. **Reporting note:** in GA, the `locale` dimension on these two event
+  families changes from empty to the real code (`en`, …) from the release a
+  site picks this up; earlier rows stay empty.
+
 ## 1.3.0
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koehler8/cms",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Vertex CMS — lightweight, config-driven Vue 3 framework with theming, extensions, and SSG support",
   "license": "MIT",
   "type": "module",
@@ -25,7 +25,8 @@
   "scripts": {
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "check:lockfile-version": "node scripts/check-lockfile-version.mjs"
   },
   "exports": {
     "./vite": "./vite-plugin.js",
@@ -79,7 +80,7 @@
     "@unhead/vue": "^2.1.15",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
-    "pinia": "^3.0.1",
+    "pinia": "^4.0.3",
     "sharp": "^0.35.3"
   },
   "optionalDependencies": {
@@ -89,13 +90,13 @@
   },
   "devDependencies": {
     "@vitejs/plugin-vue": "^6.0.8",
-    "@vitest/coverage-v8": "^4.1.10",
-    "@vue/test-utils": "^2.4.10",
+    "@vitest/coverage-v8": "^5.0.1",
+    "@vue/test-utils": "^2.5.1",
     "happy-dom": "^20.9.0",
-    "vite": "^8.2.1",
-    "vitest": "^4.1.6",
-    "vue": "^3.5.39",
-    "vue-router": "^5.0.7"
+    "vite": "^8.3.0",
+    "vitest": "^5.0.1",
+    "vue": "^3.5.43",
+    "vue-router": "^5.3.1"
   },
   "engines": {
     "node": ">=20.19.0",

package/scripts/check-lockfile-followup-done.mjs

@@ -0,0 +1,218 @@
+/**
+ * check-lockfile-followup-done — acceptance check for the "lockfile-version
+ * follow-up isn't tracked" defect.
+ *
+ * PR #6 shipped scripts/check-lockfile-version.mjs (the drift detector) but
+ * never touched package-lock.json itself, so the drift it detects
+ * (root ".version" and .packages[""].version" still "1.1.0" against
+ * package.json's "1.2.0") was left unfixed with nothing tracking it as open
+ * work. package-lock.json is floored (never-touch) for every automated
+ * pipeline stage in this repo, so the buildable fix here is a GitHub issue
+ * that captures the drift and the documented hand-fix procedure — not a
+ * code change.
+ *
+ * This is intentionally NOT a Vitest spec under tests/ and is not wired into
+ * `npm test` or builder/verify.json, for the same reason
+ * check-lockfile-version.mjs itself is kept standalone: it depends on state
+ * (the git history of this branch, and live GitHub issue content) that a
+ * hermetic, offline `npm ci && npm test` run should not depend on, and that
+ * only a human/operator action (opening the issue) can satisfy — wiring it
+ * into the gate would hold every future PR hostage to that action.
+ *
+ * Checks two things:
+ *   1. Scope: this work item's commits (relative to `main`) AND its working
+ *      tree (staged or unstaged) must not modify package-lock.json,
+ *      package.json, CLAUDE.md, or scripts/check-lockfile-version.mjs.
+ *   2. Tracking: an open GitHub issue on koehler8/cms exists whose body
+ *      documents the drift (1.1.0 -> 1.2.0), references PR #6, states PR #6
+ *      shipped the detector but not the fix, documents the hand-fix
+ *      procedure (nvm use first, edit only the two "version" string
+ *      literals, no npm install/npm version/regen), and explains that
+ *      package-lock.json is floored/never-touch for pipeline stages.
+ *
+ * Run manually: node scripts/check-lockfile-followup-done.mjs
+ * Requires `gh` authenticated against github.com for the tracking check.
+ * Exits 1 and prints exactly what's missing if either check fails; exits 0
+ * once both are satisfied.
+ */
+
+import { execFileSync } from 'node:child_process';
+
+const REPO = 'koehler8/cms';
+const SCOPED_PATHS = [
+  'package-lock.json',
+  'package.json',
+  'CLAUDE.md',
+  'scripts/check-lockfile-version.mjs',
+];
+
+function run(cmd, args) {
+  return execFileSync(cmd, args, { encoding: 'utf-8' }).trim();
+}
+
+// `git status --porcelain` is fixed-width (2-char status code + space before
+// the filename); a blanket .trim() would eat that leading space on the first
+// line and misalign the slice(3) below, so this skips run()'s trim.
+function runPorcelainLines(cmd, args) {
+  return execFileSync(cmd, args, { encoding: 'utf-8' })
+    .split('\n')
+    .filter((line) => line.length > 0);
+}
+
+function checkScope() {
+  let baseRef;
+  for (const candidate of ['origin/main', 'main']) {
+    try {
+      run('git', ['rev-parse', '--verify', candidate]);
+      baseRef = candidate;
+      break;
+    } catch {
+      // try next candidate
+    }
+  }
+
+  if (!baseRef) {
+    return {
+      ok: false,
+      messages: ['  could not resolve a `main` ref (tried origin/main, main) to diff against'],
+    };
+  }
+
+  let mergeBase;
+  try {
+    mergeBase = run('git', ['merge-base', 'HEAD', baseRef]);
+  } catch (err) {
+    return { ok: false, messages: [`  git merge-base HEAD ${baseRef} failed: ${err.message}`] };
+  }
+
+  const committed = run('git', ['diff', '--name-only', `${mergeBase}...HEAD`])
+    .split('\n')
+    .filter(Boolean);
+
+  const workingTree = runPorcelainLines('git', ['status', '--porcelain', '--', ...SCOPED_PATHS]).map(
+    (line) => line.slice(3)
+  );
+
+  const touchedCommitted = SCOPED_PATHS.filter((p) => committed.includes(p));
+  const touchedWorkingTree = SCOPED_PATHS.filter((p) => workingTree.includes(p));
+  const touched = [...new Set([...touchedCommitted, ...touchedWorkingTree])];
+
+  if (touched.length > 0) {
+    return {
+      ok: false,
+      messages: touched.map((p) => `  ${p} was modified by this work item but must stay untouched`),
+    };
+  }
+
+  return { ok: true, messages: [] };
+}
+
+function findTrackingIssue() {
+  const raw = run('gh', [
+    'issue',
+    'list',
+    '-R',
+    REPO,
+    '--state',
+    'open',
+    '--limit',
+    '100',
+    '--json',
+    'number,title,body,url',
+  ]);
+  const issues = JSON.parse(raw);
+
+  const requirements = [
+    { label: 'mentions the current stale value "1.1.0"', test: (b) => b.includes('1.1.0') },
+    { label: 'mentions the expected value "1.2.0"', test: (b) => b.includes('1.2.0') },
+    { label: 'references PR #6', test: (b) => /#6\b/.test(b) },
+    {
+      label: 'states PR #6 shipped the detector but not the fix',
+      test: (b) => /check[-:]lockfile-version/.test(b) && /(did not|didn't|never|not).{0,40}(touch|fix|update)/i.test(b),
+    },
+    { label: 'documents `nvm use` as a required first step', test: (b) => /nvm use/.test(b) },
+    {
+      label: 'documents that npm install/npm version/regen must not be used to fix it',
+      test: (b) => /npm (install|version)/.test(b) && /(never|not|don't|do not)/i.test(b),
+    },
+    {
+      label: 'explains package-lock.json is floored/never-touch for the pipeline',
+      test: (b) => /package-lock\.json/.test(b) && /(floor|never.touch)/i.test(b),
+    },
+  ];
+
+  for (const issue of issues) {
+    const body = issue.body || '';
+    const misses = requirements.filter((r) => !r.test(body)).map((r) => r.label);
+    if (misses.length === 0) {
+      return { ok: true, issue };
+    }
+  }
+
+  return { ok: false, issues, requirements };
+}
+
+function checkTracking() {
+  let result;
+  try {
+    result = findTrackingIssue();
+  } catch (err) {
+    return {
+      ok: false,
+      messages: [`  could not query GitHub issues via \`gh\` (${err.message})`],
+    };
+  }
+
+  if (result.ok) {
+    return { ok: true, messages: [`  found: ${result.issue.url}`] };
+  }
+
+  if (result.issues.length === 0) {
+    return {
+      ok: false,
+      messages: [`  no open issues found on ${REPO} at all — none can be the tracking issue`],
+    };
+  }
+
+  const messages = [`  no open issue on ${REPO} covers every required element:`];
+  for (const issue of result.issues) {
+    const body = issue.body || '';
+    const misses = result.requirements.filter((r) => !r.test(body)).map((r) => r.label);
+    if (misses.length < result.requirements.length) {
+      messages.push(`    #${issue.number} "${issue.title}" is missing: ${misses.join('; ')}`);
+    }
+  }
+  if (messages.length === 1) {
+    messages.push('    (no candidate issue matched any required element)');
+  }
+  return { ok: false, messages };
+}
+
+async function main() {
+  const scope = checkScope();
+  const tracking = checkTracking();
+
+  let ok = true;
+
+  if (!scope.ok) {
+    ok = false;
+    console.error('Scope check failed — this work item must not modify these files:');
+    console.error(scope.messages.join('\n'));
+  } else {
+    console.log('Scope check passed: package-lock.json, package.json, CLAUDE.md, and ' +
+      'scripts/check-lockfile-version.mjs are untouched by this work item.');
+  }
+
+  if (!tracking.ok) {
+    ok = false;
+    console.error('Tracking check failed — no qualifying GitHub issue found:');
+    console.error(tracking.messages.join('\n'));
+  } else {
+    console.log('Tracking check passed:');
+    console.log(tracking.messages.join('\n'));
+  }
+
+  process.exitCode = ok ? 0 : 1;
+}
+
+await main();

package/scripts/check-lockfile-version.mjs

@@ -0,0 +1,61 @@
+/**
+ * check-lockfile-version — detect drift between package.json's version and
+ * package-lock.json's two self-reported version fields (root `.version` and
+ * `.packages[""].version`).
+ *
+ * This is intentionally NOT a Vitest spec under tests/, and is not wired
+ * into `npm test`. package-lock.json is a floored, never-touch file for
+ * every automated pipeline stage in this repo (see CLAUDE.md "Lockfile and
+ * npm version" and the product skill's "Never touch" list) — a full lockfile
+ * regen on the wrong npm version is the documented #1 cause of consumer-site
+ * deploy failures, so no stage here is permitted to edit it, not even for a
+ * narrow two-field metadata correction. A Vitest spec asserting these fields
+ * match would therefore stay red until a human fixes the file by hand, which
+ * would permanently fail the mandatory `npm ci && npm test` verify gate for
+ * every future PR. Keeping this check standalone lets it detect and report
+ * the drift without holding CI hostage to a fix only a human can apply.
+ *
+ * Run manually: node scripts/check-lockfile-version.mjs
+ * Exits 1 and prints the stale fields if package-lock.json's version fields
+ * don't match package.json's version; exits 0 otherwise.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT_DIR = dirname(dirname(fileURLToPath(import.meta.url)));
+
+async function main() {
+  const packageJson = JSON.parse(await readFile(join(ROOT_DIR, 'package.json'), 'utf-8'));
+  const lockJson = JSON.parse(await readFile(join(ROOT_DIR, 'package-lock.json'), 'utf-8'));
+
+  const expected = packageJson.version;
+  const stale = [];
+  if (lockJson.version !== expected) {
+    stale.push(`  package-lock.json ".version" is "${lockJson.version}", expected "${expected}"`);
+  }
+  if (lockJson.packages?.['']?.version !== expected) {
+    stale.push(
+      `  package-lock.json ".packages[\\"\\"].version" is "${lockJson.packages?.['']?.version}", expected "${expected}"`
+    );
+  }
+
+  if (stale.length > 0) {
+    console.error(`package-lock.json version drift detected (package.json is at "${expected}"):`);
+    console.error(stale.join('\n'));
+    console.error(
+      '\npackage-lock.json is floored (never-touch) for every pipeline stage in this repo — ' +
+        'this must be corrected by hand, outside the pipeline, and pushed directly ' +
+        '(same as any dependency-version change; see CLAUDE.md "Lockfile and npm version"). ' +
+        'Edit only the two "version" string literals above; do not run `npm install`, ' +
+        '`npm version`, or any lockfile regen.'
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(`package-lock.json version fields match package.json ("${expected}").`);
+}
+
+await main();

package/scripts/check-site-lockfile.mjs

@@ -0,0 +1,128 @@
+/**
+ * check-site-lockfile — verify a consumer site's package-lock.json is safe to
+ * push to AWS Amplify after a dependency bump.
+ *
+ * The documented #1 cause of consumer-site deploy failures (CLAUDE.md
+ * "Lockfile and npm version") is a lockfile regenerated on the wrong npm
+ * major: it looks fine on a Mac and then Amplify's Linux build dies with
+ * `Cannot find module '@rolldown/binding-linux-x64-gnu'`, because the optional
+ * platform-binary entries were stripped. Nothing local fails, so the only
+ * defence is to inspect the lockfile before it ships.
+ *
+ * The invariant is NOT a count. rolldown 1.2.9 dropped its wasm32-wasi binding
+ * and added an android one, so a healthy bump moved a site from 42 native
+ * entries to 41 — a count check would have failed a good lockfile and could
+ * pass a bad one. What must hold instead: every name a locked package lists
+ * under `optionalDependencies` resolves to an entry in the same lockfile. The
+ * parent's list survives a bad regen; the children are what go missing. That
+ * needs no network and no knowledge of which packages happen to be native.
+ *
+ * Like check-lockfile-version this is a standalone detector, deliberately not
+ * wired into `npm test` or builder/verify.json: it inspects a SITE's lockfile,
+ * not this repo's.
+ *
+ * Run: node scripts/check-site-lockfile.mjs [siteDir]   (default: cwd)
+ * Exits 1 and lists every problem; exits 0 when the lockfile is clean.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// A second copy of any of these means two module instances at runtime — the
+// reason the framework excludes them from Vite's dep pre-bundling.
+const SINGLETONS = ['vue', 'vue-router', 'pinia', '@unhead/vue'];
+
+// The two binaries whose absence has actually taken Amplify builds down.
+// Checked by name on top of the general rule so the failure message is direct.
+const AMPLIFY_BINARIES = [
+  { parent: 'rolldown', binary: '@rolldown/binding-linux-x64-gnu' },
+  { parent: 'sharp', binary: '@img/sharp-linux-x64' },
+];
+
+const REGISTRY = 'https://registry.npmjs.org/';
+
+/** npm's resolution walk: nearest node_modules first, then each ancestor's. */
+function resolveFrom(packages, parentKey, name) {
+  let base = parentKey;
+  for (;;) {
+    const candidate = base ? `${base}/node_modules/${name}` : `node_modules/${name}`;
+    if (packages[candidate]) return candidate;
+    if (!base) return null;
+    const cut = base.lastIndexOf('/node_modules/');
+    base = cut === -1 ? '' : base.slice(0, cut);
+  }
+}
+
+export function checkLockfile(lock) {
+  const problems = [];
+  const packages = lock?.packages ?? {};
+
+  if (lock?.lockfileVersion !== 3) {
+    problems.push(`lockfileVersion is ${lock?.lockfileVersion}, expected 3`);
+  }
+
+  for (const [key, entry] of Object.entries(packages)) {
+    for (const name of Object.keys(entry.optionalDependencies ?? {})) {
+      if (!resolveFrom(packages, key, name)) {
+        problems.push(
+          `${key || '(root)'} lists optional dependency "${name}" but the lockfile has no entry for it`
+        );
+      }
+    }
+  }
+
+  for (const { parent, binary } of AMPLIFY_BINARIES) {
+    if (!packages[`node_modules/${parent}`]) continue;
+    const entry = packages[`node_modules/${binary}`];
+    if (!entry) {
+      problems.push(`${parent} is locked but ${binary} is missing — Amplify's Linux build will fail`);
+    } else if (!entry.resolved || !entry.integrity) {
+      problems.push(`${binary} has no resolved/integrity — npm cannot install it on Amplify`);
+    }
+  }
+
+  for (const name of SINGLETONS) {
+    const copies = Object.keys(packages).filter(
+      (key) => key === `node_modules/${name}` || key.endsWith(`/node_modules/${name}`)
+    );
+    if (copies.length > 1) {
+      problems.push(`${copies.length} copies of ${name} (${copies.join(', ')}) — must be exactly one`);
+    }
+  }
+
+  for (const [key, entry] of Object.entries(packages)) {
+    if (!entry.resolved || entry.link) continue;
+    const isLocal = !/^[a-z][a-z0-9+.-]*:/i.test(entry.resolved);
+    if (!isLocal && !entry.resolved.startsWith(REGISTRY)) {
+      problems.push(`${key} resolves outside the npm registry: ${entry.resolved}`);
+    }
+  }
+
+  return problems;
+}
+
+async function main() {
+  const siteDir = resolve(process.argv[2] ?? process.cwd());
+  const lock = JSON.parse(await readFile(join(siteDir, 'package-lock.json'), 'utf-8'));
+  const problems = checkLockfile(lock);
+
+  if (problems.length > 0) {
+    console.error(`package-lock.json in ${siteDir} is NOT safe to push:`);
+    console.error(problems.map((problem) => `  - ${problem}`).join('\n'));
+    console.error(
+      '\nIf optional-dependency entries are missing, the lockfile was almost certainly written by ' +
+        'the wrong npm major. Revert it (`git checkout HEAD -- package-lock.json`), run `nvm use`, ' +
+        'and redo the bump with a targeted `npm install <pkg>@<ver>`.'
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const count = Object.keys(lock.packages ?? {}).length;
+  console.log(`package-lock.json in ${siteDir} is clean (${count} entries, all optional dependencies present).`);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  await main();
+}

package/scripts/diff-ssg-dist.mjs

@@ -0,0 +1,194 @@
+/**
+ * diff-ssg-dist — compare two SSG `dist/` trees page by page on everything a
+ * dependency bump must NOT change: the route list, each page's SEO head, and
+ * the rendered structure and text.
+ *
+ * Consumer sites have no test suite; a green `build:ssg` is their only gate,
+ * and it cannot see the failures that matter. A component whose content block
+ * stopped resolving renders nothing, silently. A head-management regression
+ * drops canonicals or hreflang without a warning. Both build clean. So build
+ * once before the bump, once after, and diff what the crawler and the visitor
+ * would actually receive.
+ *
+ * It also compares the theme's fingerprint — the set of CSS custom-property
+ * declarations across dist/assets/*.css — because the page diff never opens a
+ * stylesheet and would not see a palette or type regression.
+ *
+ * Hashed asset filenames and bundled JS are expected to differ and are ignored.
+ * HTML comments and inline <style> are stripped first: a comment can mention a
+ * tag ("<title> is emitted by usePageMeta…") and inline CSS is
+ * minifier-dependent — neither is content, and both produced false diffs.
+ *
+ * Run: node scripts/diff-ssg-dist.mjs <dist-before> <dist-after>
+ * Exits 1 on any difference; exits 0 when every page matches.
+ */
+
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const all = (html, re) => [...html.matchAll(re)].map((match) => match[1] ?? match[0]);
+const attr = (tag, name) => (tag.match(new RegExp(`\\b${name}="([^"]*)"`)) || [])[1] ?? null;
+const count = (html, re) => (html.match(re) || []).length;
+
+export function extractSignals(rawHtml) {
+  const html = rawHtml.replace(/<!--[\s\S]*?-->/g, '').replace(/<style\b[\s\S]*?<\/style>/g, '');
+  const head = (html.match(/<head[^>]*>([\s\S]*?)<\/head>/) || [])[1] ?? '';
+  const links = all(head, /<link\b[^>]*>/g);
+  const metas = all(head, /<meta\b[^>]*>/g);
+  const meta = (key, value) =>
+    metas.filter((tag) => attr(tag, key) === value).map((tag) => attr(tag, 'content')).sort();
+  const body = ((html.match(/<body[^>]*>([\s\S]*?)<\/body>/) || [])[1] ?? '').replace(
+    /<script[\s\S]*?<\/script>/g,
+    ''
+  );
+
+  return {
+    lang: attr((html.match(/<html\b[^>]*>/) || [''])[0], 'lang'),
+    title: (head.match(/<title>([\s\S]*?)<\/title>/) || [])[1] ?? null,
+    description: meta('name', 'description'),
+    robots: meta('name', 'robots'),
+    canonical: links.filter((tag) => attr(tag, 'rel') === 'canonical').map((tag) => attr(tag, 'href')),
+    hreflang: links
+      .filter((tag) => attr(tag, 'rel') === 'alternate' && attr(tag, 'hreflang'))
+      .map((tag) => `${attr(tag, 'hreflang')}=${attr(tag, 'href')}`)
+      .sort(),
+    ogUrl: meta('property', 'og:url'),
+    ogTitle: meta('property', 'og:title'),
+    ogImage: meta('property', 'og:image'),
+    jsonLd: all(html, /<script[^>]*type="application\/ld\+json"[^>]*>([\s\S]*?)<\/script>/g).sort(),
+    // Structure counts are what catch a silently-vanished component.
+    sections: count(body, /<section\b/g),
+    headings: count(body, /<h[1-6]\b/g),
+    links: count(body, /<a\b/g),
+    images: count(body, /<img\b/g),
+    text: body.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim(),
+  };
+}
+
+export function initialStateBytes(rawHtml) {
+  return ((rawHtml.match(/__INITIAL_STATE__\s*=\s*([\s\S]*?)<\/script>/) || [])[1] ?? '').length;
+}
+
+function htmlFiles(root, dir = root, out = new Map()) {
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) htmlFiles(root, path, out);
+    else if (name.endsWith('.html')) out.set(relative(root, path), path);
+  }
+  return out;
+}
+
+// The theme's fingerprint: every CSS custom-property declaration in the built
+// stylesheets, whitespace-normalised and de-duplicated. The page diff above
+// strips inline <style> and never opens a CSS asset, so a palette or type
+// regression — the kind a published theme package or a CSS-minifier bump could
+// introduce — is invisible to it. Hashed filenames and rule order are
+// minifier-dependent; the set of `--name:value` pairs is not (it held identical
+// on three sites through lightningcss 1.32 -> 1.33).
+export function themeFingerprint(distDir) {
+  const assets = join(distDir, 'assets');
+  let files;
+  try {
+    files = readdirSync(assets).filter((name) => name.endsWith('.css'));
+  } catch {
+    return [];
+  }
+  const declarations = new Set();
+  for (const name of files) {
+    const css = readFileSync(join(assets, name), 'utf-8');
+    for (const match of css.matchAll(/(--[A-Za-z0-9_-]+)\s*:\s*([^;}]+)/g)) {
+      declarations.add(`${match[1]}:${match[2].replace(/\s+/g, '')}`);
+    }
+  }
+  return [...declarations].sort();
+}
+
+export function diffDist(beforeDir, afterDir) {
+  const before = htmlFiles(beforeDir);
+  const after = htmlFiles(afterDir);
+  const differences = [];
+
+  const removed = [...before.keys()].filter((page) => !after.has(page));
+  const added = [...after.keys()].filter((page) => !before.has(page));
+  for (const page of removed) differences.push({ page, signal: 'route', before: 'present', after: 'MISSING' });
+  for (const page of added) differences.push({ page, signal: 'route', before: 'absent', after: 'NEW' });
+
+  let stateBefore = 0;
+  let stateAfter = 0;
+  for (const [page, beforePath] of before) {
+    if (!after.has(page)) continue;
+    const beforeHtml = readFileSync(beforePath, 'utf-8');
+    const afterHtml = readFileSync(after.get(page), 'utf-8');
+    stateBefore += initialStateBytes(beforeHtml);
+    stateAfter += initialStateBytes(afterHtml);
+
+    const a = extractSignals(beforeHtml);
+    const b = extractSignals(afterHtml);
+    for (const signal of Object.keys(a)) {
+      const left = JSON.stringify(a[signal]);
+      const right = JSON.stringify(b[signal]);
+      if (left !== right) differences.push({ page, signal, before: left, after: right });
+    }
+  }
+
+  for (const file of ['sitemap.xml', 'robots.txt']) {
+    const read = (dir) => {
+      try {
+        return readFileSync(join(dir, file), 'utf-8');
+      } catch {
+        return null;
+      }
+    };
+    if (read(beforeDir) !== read(afterDir)) {
+      differences.push({ page: file, signal: 'bytes', before: 'baseline', after: 'CHANGED' });
+    }
+  }
+
+  const themeBefore = themeFingerprint(beforeDir);
+  const themeAfter = themeFingerprint(afterDir);
+  const afterSet = new Set(themeAfter);
+  const beforeSet = new Set(themeBefore);
+  const lost = themeBefore.filter((declaration) => !afterSet.has(declaration));
+  const gained = themeAfter.filter((declaration) => !beforeSet.has(declaration));
+  if (lost.length || gained.length) {
+    differences.push({
+      page: 'assets/*.css',
+      signal: 'theme',
+      before: `${lost.length} declaration(s) gone: ${lost.slice(0, 6).join(' | ')}`,
+      after: `${gained.length} declaration(s) new: ${gained.slice(0, 6).join(' | ')}`,
+    });
+  }
+
+  return { pages: before.size, stateBefore, stateAfter, themeDeclarations: themeAfter.length, differences };
+}
+
+function main() {
+  const [beforeDir, afterDir] = process.argv.slice(2);
+  if (!beforeDir || !afterDir) {
+    console.error('Usage: node scripts/diff-ssg-dist.mjs <dist-before> <dist-after>');
+    process.exitCode = 2;
+    return;
+  }
+
+  const { pages, stateBefore, stateAfter, themeDeclarations, differences } = diffDist(beforeDir, afterDir);
+  const clip = (value) => (value.length > 160 ? `${value.slice(0, 160)}… (${value.length} chars)` : value);
+  for (const { page, signal, before, after } of differences) {
+    console.log(`DIFF ${page} [${signal}]\n   before: ${clip(before)}\n   after:  ${clip(after)}`);
+  }
+
+  const drift = stateBefore ? (((stateAfter - stateBefore) / stateBefore) * 100).toFixed(2) : '0.00';
+  console.log(`pages compared: ${pages}`);
+  console.log(`__INITIAL_STATE__ total: ${stateBefore} -> ${stateAfter} bytes (${drift}%)`);
+  console.log(`theme fingerprint: ${themeDeclarations} CSS custom-property declarations`);
+  if (differences.length > 0) {
+    console.log(`FAIL: ${differences.length} difference(s)`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log('PASS: every page identical on route list, SEO head, structure and text; theme unchanged');
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  main();
+}

package/src/components/Home.vue

@@ -65,6 +65,7 @@ const {
   pageContent,
   currentPage,
   componentKeys,
+  contentLocale,
   isLoading,
   loadError,
 } = usePageConfig({
@@ -90,7 +91,10 @@ const {
   attemptUnlock,
 } = useDraftGate({ siteData, currentPage });
 
-usePageMeta({ siteData, currentPage, locale: () => props.locale });
+// Keyed off the locale of the content actually rendered, not the route param:
+// on an unprefixed route a returning visitor's saved locale is restored, and
+// <html lang> / og:locale / canonical must describe that content (WCAG 3.1.1).
+usePageMeta({ siteData, currentPage, locale: () => contentLocale.value });
 
 const {
   isComingSoonVisible,
@@ -102,7 +106,11 @@ const {
 const { refreshVisibilityTargets, resetEngagementTracking } = useEngagementTracking({
   getContext: () => ({
     page_id: currentPage.value.id || '',
-    locale: props.locale || '',
+    // The rendered locale, for the same reason as usePageMeta above. An event-
+    // level `locale` overrides the tracking context's own (read from <html
+    // lang>), so the route param here reported '' for every base-locale page
+    // and for saved-locale content restored onto an unprefixed URL.
+    locale: contentLocale.value,
   }),
 });
 

package/src/composables/usePageConfig.js

@@ -1,5 +1,11 @@
 import { onServerPrefetch, ref, watch } from 'vue';
-import { loadConfigData, mergeConfigTrees, peekConfigSync } from '../utils/loadConfig.js';
+import {
+  baseLocale as configBaseLocale,
+  loadConfigData,
+  mergeConfigTrees,
+  peekConfigSync,
+  resolveContentLocale,
+} from '../utils/loadConfig.js';
 import { readStoredLocale } from '../utils/webStorage.js';
 import { isNotFoundPage, NOT_FOUND_PAGE_ID } from '../utils/notFound.js';
 
@@ -46,8 +52,22 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
   const componentKeys = ref([]);
   const isLoading = ref(false);
   const loadError = ref(null);
+  // The locale of the content currently applied — NOT necessarily the route's.
+  // An unprefixed route (`/`) carries no locale, yet a returning visitor's
+  // saved locale is restored onto it, so German can be on screen at a URL that
+  // implies English. usePageMeta keys <html lang> off this so the declared
+  // language always matches the rendered one (WCAG 3.1.1). It starts as the
+  // route locale — which is what the server rendered — and only moves when
+  // different-locale content is actually applied, after mount, so hydration
+  // still matches the on-disk HTML.
+  const contentLocale = ref(
+    ((typeof locale === 'function' ? locale() : locale) || '').toString().toLowerCase()
+      || configBaseLocale
+      || '',
+  );
 
   let cachedConfig = null;
+  let cachedContentLocale = contentLocale.value;
   let lastLocaleKey = null;
   let activeRequest = 0;
   // Cancels a pending idle-scheduled background reload (see hydrateFromSyncCache).
@@ -189,13 +209,18 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
 
     try {
       if (shouldReload) {
+        // Resolved before the await so it names the same stored preference the
+        // loader is about to read.
+        const resolvedLocale = resolveContentLocale(localeForConfig);
         cachedConfig = await loadConfigData({ locale: localeForConfig });
+        cachedContentLocale = resolvedLocale;
         lastLocaleKey = localeKey;
       }
 
       if (requestId !== activeRequest) return;
 
       applyConfig(cachedConfig);
+      contentLocale.value = cachedContentLocale;
     } catch (error) {
       if (requestId !== activeRequest) return;
       if (import.meta.env.SSR) {
@@ -242,6 +267,10 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
       return false;
     }
     cachedConfig = primed;
+    // The primed config is what the server rendered for this route, and the
+    // server never sees a saved locale — so it is the route's locale, or base.
+    cachedContentLocale = localeForConfig || configBaseLocale || '';
+    contentLocale.value = cachedContentLocale;
     lastLocaleKey = localeKey;
 
     // Decide whether a soft (no blank-out) background reload of the FULL config
@@ -326,6 +355,7 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
     pageContent,
     currentPage,
     componentKeys,
+    contentLocale,
     isLoading,
     loadError,
     syncPage,

package/src/composables/usePageMeta.js

@@ -236,7 +236,10 @@ export function usePageMeta({ siteData, currentPage, locale }) {
       // Reflect the page's locale on <html lang> during SSR/prerender so the
       // on-disk HTML for /{locale}/... ships the right language (the router
       // guard only sets this client-side, after hydration). Base-locale pages
-      // fall back to the configured base locale.
+      // fall back to the configured base locale. `locale` here is the locale of
+      // the RENDERED content (usePageConfig's contentLocale), which after
+      // hydration can differ from the route's when a saved locale is restored
+      // onto an unprefixed URL — lang must follow the text (WCAG 3.1.1).
       htmlAttrs: { lang: localeValue.value || configBaseLocale || 'en' },
       title: pageMetaTitle.value,
       meta,

package/src/utils/loadConfig.js

@@ -22,6 +22,17 @@ function normalizeLocaleInput(value) {
     return trimmed.length ? trimmed : undefined;
 }
 
+// Which locale a load asks for: the explicit (route) locale when there is one,
+// otherwise the visitor's saved preference. Shared by loadConfigData and
+// resolveContentLocale so "what gets loaded" and "what we say got loaded"
+// can't drift apart. The server has no storage, so SSG always gets `undefined`
+// (base locale) for an unprefixed route.
+function pickRequestedLocale(explicitLocale) {
+    return normalizeLocaleInput(explicitLocale)
+        || normalizeLocaleInput(readStoredLocale())
+        || undefined;
+}
+
 export function cloneConfig(value) {
     if (Array.isArray(value)) {
         return value.map(cloneConfig);
@@ -282,11 +293,7 @@ export function createConfigLoader(allModules) {
             explicitLocale = normalizeLocaleInput(options.locale);
         }
 
-        let locale = explicitLocale;
-
-        if (!locale) {
-            locale = normalizeLocaleInput(readStoredLocale()) || undefined;
-        }
+        const locale = pickRequestedLocale(explicitLocale);
 
         const normalizedLocale = typeof locale === 'string' ? locale.toLowerCase() : undefined;
 
@@ -406,6 +413,23 @@ export function peekConfigSync(locale) {
   return _syncConfigCache.get(normalizeConfigCacheKey(locale)) || null;
 }
 
+// The locale whose content `loadConfigData({ locale: explicitLocale })` will
+// actually return. An unprefixed route passes no locale, and loadConfigData
+// then restores the visitor's saved locale — so the language on screen can
+// differ from the one the URL implies. Anything that describes the rendered
+// page (<html lang>, og:locale) must follow THIS, not the route param
+// (WCAG 3.1.1). A saved locale with no content on disk loads the base tree,
+// so it resolves to the base locale here too.
+export function resolveContentLocale(explicitLocale) {
+  const explicit = normalizeLocaleInput(explicitLocale);
+  if (explicit) return explicit.toLowerCase();
+  const requested = (pickRequestedLocale() || '').toLowerCase();
+  if (requested && requested !== _baseLocale && _availableLocales.includes(requested)) {
+    return requested;
+  }
+  return _baseLocale || '';
+}
+
 export { _availableLocales as availableLocales };
 export { _baseLocale as baseLocale };
 

package/templates/scaffolds/site/.nvmrc

@@ -1 +1 @@
-20.19.0
+22.23.2

package/templates/scaffolds/site/CLAUDE.md

@@ -89,14 +89,14 @@ Edit `themes/<slug>/theme.config.js`. The CMS regenerates `virtual:cms-theme-var
 
 ## Lockfile and npm version — read before bumping any dep
 
-This project pins **Node 20.19 / npm 10.8** to match AWS Amplify exactly. Local installs with a different npm version produce subtly different lockfiles that look fine locally but break CI.
+This project pins **Node 22.23.2 / npm 10.9** to match AWS Amplify exactly (never 24 — it ships npm 11). Local installs with a different npm version produce subtly different lockfiles that look fine locally but break CI.
 
 Two failure modes seen on sister sites:
 1. `Cannot find module '@rolldown/binding-linux-x64-gnu'` — npm 11 regen stripped optional-dep entries Amplify needs.
 2. `npm ci ... Missing: @types/react@..., @noble/hashes@... from lock file` — npm 11 omitted entries npm 10 expects.
 
 Rules:
-- **Always run `nvm use` before `npm install`**. `.nvmrc` pins 20.19.0 (which ships npm 10.8.x).
+- **Always run `nvm use` before `npm install`**. `.nvmrc` pins 22.23.2 (which ships npm 10.9.x).
 - **Prefer targeted bumps**: `npm install <pkg>@<ver> --no-audit --no-fund`. **Never** `rm package-lock.json && npm install` unless you're on the pinned npm version.
 - **The build uses `npm install`**, not `npm ci` (see `amplify.yml`) for drift tolerance.
 

package/templates/scaffolds/site/README.md

@@ -7,7 +7,7 @@ For architecture, conventions, and a navigation guide for "where things go" (con
 ## Local development
 
 ```bash
-nvm use                    # Node 20.19.0 per .nvmrc
+nvm use                    # Node 22.23.2 per .nvmrc
 cp .env.example .env
 npm install
 npm run dev

package/templates/scaffolds/site/amplify.yml

@@ -3,7 +3,7 @@ frontend:
   phases:
     preBuild:
       commands:
-        - nvm install 20.19.0 && nvm use 20.19.0
+        - nvm install 22.23.2 && nvm use 22.23.2
         # Use `npm install` (not `npm ci`) so the build tolerates
         # lockfile/npm-version drift. See CLAUDE.md → "Lockfile and
         # npm version" for the rationale.