feat(www,tools): remediate hostile-audit content-truth findings (#1307)

Major:
- /apilist renders the generated API + custom-element reference: 167
  per-export entries and 10 per-element detail rows with the generated
  anchors; the built-output link gate now asserts every generated
  searchRecord anchor exists in both locales (pagefind skip documented).
- /zh/contributing ships a real zh translation instead of hard-coded
  English; the www:check-truth locale gate now covers route-level
  content records (en without zh fails closed) and requires every blog
  post to declare its original language via frontmatter lang. Blog
  routes mark locale-mismatched renders with an explicit notice and a
  truthful lang attribute instead of masquerading.

Minor:
- Per-route, locale-appropriate title/description/og/canonical/hreflang
  derived from the content graph (content routes) + an authored
  bilingual route map (www/app/seo.ts), applied to the built shell by
  tools/apply-www-seo.ts (fail-closed) before Pagefind indexing;
  findSeoFailures strengthened beyond presence-only (boilerplate-title
  rejection, canonical/hreflang presence, per-locale title uniqueness,
  no English boilerplate description on zh pages).
- Sitemap generator excludes locale-prefixed 404 pages symmetrically
  (/zh/404 leak fixed).
- Changelog copy now names the withdrawn npm beta.1-beta.3 artifacts as
  the 0.41.0-era line; CHANGELOG.md gains reconciling 0.43.x and
  0.44.0-beta.1 entries deferring to docs/release/.
- content-examples gate: typescript/js fence aliases are type-checked,
  TS2304 suppression no longer covers documented framework exports
  (caught a real import-elided openElement() call in the configuration
  guide), blog exclusion documented with rationale.

Also fixes the content-graph blog adapter to derive slugs/routes through
the blog plugin's own collection options (date-prefix transform), so
graph routes match the served routes.

Author: DevBot

CHANGELOG.md

@@ -16,6 +16,25 @@ Current truth lives in:
 Historical changelog details remain available through git history and release
 evidence.
 
+## 0.44.0-beta.1
+
+**First public v0.44 prerelease (dist-tag `beta`; npm `latest` stays on the
+stable 0.43 line).** Framework qualification under a frozen governance
+envelope (ADR-0151): the TSX-to-Part Program compiler, page-route SSR bound
+to the compiled program, and the delivery gates. The authoritative note is
+[`docs/release/v0.44.0-beta.1.md`](./docs/release/v0.44.0-beta.1.md); the
+0.41.0-era npm `beta.1`–`beta.3` artifacts remain withdrawn partial
+publishes, unrelated to this line.
+
+## 0.43.3 / 0.43.2 / 0.43.1 / 0.43.0
+
+**Stable maintenance line (npm `latest`).** Compatible bug, security,
+runtime, documentation and release-truth patches under ADR-0140 — no 0.44
+feature train. Per-release notes:
+[`docs/release/v0.43.0.md`](./docs/release/v0.43.0.md),
+[`v0.43.1`](./docs/release/v0.43.1.md), [`v0.43.2`](./docs/release/v0.43.2.md),
+[`v0.43.3`](./docs/release/v0.43.3.md).
+
 ## 0.42.0
 
 **WC light fullstack, stable.** The stable cut of the 0.42 alpha line — the

deno.json

@@ -38,7 +38,8 @@
   "tasks": {
     "dev": "cd www && deno run --allow-read --allow-write --allow-net --allow-env --allow-ffi --allow-sys npm:vite --config vite.config.ts",
     "www:dev-smoke": "deno run --allow-net --allow-run tools/smoke-www-dev.ts",
-    "build": "deno task generate:ui-manifest && (cd www && deno run --config ../deno.json --allow-read --allow-write --allow-net --allow-env --allow-ffi --allow-sys --allow-run ../packages/adapter-vite/src/cli/build.ts) && deno task www:pagefind && deno task www:check-artifact-truth && deno task www:check-links",
+    "build": "deno task generate:ui-manifest && (cd www && deno run --config ../deno.json --allow-read --allow-write --allow-net --allow-env --allow-ffi --allow-sys --allow-run ../packages/adapter-vite/src/cli/build.ts) && deno task www:apply-seo && deno task www:pagefind && deno task www:check-artifact-truth && deno task www:check-links",
+    "www:apply-seo": "deno run --allow-read --allow-write tools/apply-www-seo.ts",
     "www:pagefind": "cd www && deno run --config ../deno.json --allow-read --allow-write --allow-run --allow-env --allow-net --allow-ffi --allow-sys build-pagefind.ts",
     "preview": "cd www && deno run --allow-read --allow-write --allow-net --allow-env --allow-ffi npm:vite preview --config vite.config.ts",
     "workflow:check": "deno run --allow-read --allow-run=git tools/check-project-workflow.ts && deno task v044:orchestration:check",

packages/adapter-vite/__tests__/sitemap-generator.test.ts

@@ -37,6 +37,23 @@ Deno.test('generateSitemap creates deploy outputs with web-readable permissions'
   }
 });
 
+Deno.test('generateSitemap never lists 404 pages, including locale-prefixed ones (#1307)', async () => {
+  const root = await Deno.makeTempDir();
+  try {
+    await Deno.mkdir(join(root, 'zh', '404'), { recursive: true });
+    await Deno.mkdir(join(root, 'zh'), { recursive: true });
+    await Deno.writeTextFile(join(root, 'index.html'), 'home');
+    await Deno.writeTextFile(join(root, '404.html'), 'not found'); // default-locale flat artifact
+    await Deno.writeTextFile(join(root, 'zh', 'index.html'), 'zh home');
+    await Deno.writeTextFile(join(root, 'zh', '404', 'index.html'), 'zh not found');
+    generateSitemap(root, { hostname: 'https://example.com' });
+    const xml = await Deno.readTextFile(join(root, 'sitemap.xml'));
+    assert(!xml.includes('/404</loc>'), 'sitemap must not list any 404 page');
+    assert(xml.includes('<loc>https://example.com/zh</loc>'));
+  } finally {
+    await Deno.remove(root, { recursive: true });
+  }
+});
 Deno.test('generateSitemap exclude matches path boundaries, not bare prefixes (#1039)', async () => {
   const root = await Deno.makeTempDir();
   try {

packages/adapter-vite/src/internal/content/blog/blog-data.ts

@@ -30,6 +30,7 @@ export function writeBlogDataModule(posts: BlogPost[]): string {
     '    tags?: string[];',
     '    excerpt?: string;',
     '    type?: string;',
+    '    lang?: string;',
     '  };',
     '  content: string;',
     '  html: string;',

packages/adapter-vite/src/internal/content/blog/plugin.ts

@@ -21,11 +21,17 @@ function toBlogPost(entry: CollectionEntry): BlogPost {
       tags: Array.isArray(frontmatter.tags) ? frontmatter.tags.map(String) : [],
       ...(typeof frontmatter.excerpt === 'string' ? { excerpt: frontmatter.excerpt } : {}),
       ...(typeof frontmatter.type === 'string' ? { type: frontmatter.type } : {}),
+      ...(typeof frontmatter.lang === 'string' ? { lang: frontmatter.lang } : {}),
     },
   };
 }
 
-function blogCollectionOptions(options: OpenElementBlogOptions): CollectionOptions {
+/**
+ * The blog collection options (date-prefix slug transform + frontmatter
+ * schema) — exported so the repo's content-graph adapter derives blog
+ * slugs/routes through the same truth as the built site (#1307).
+ */
+export function blogCollectionOptions(options: OpenElementBlogOptions): CollectionOptions {
   return {
     contentDir: options.contentDir ?? 'posts',
     basePath: options.basePath ?? '/blog',
@@ -38,6 +44,7 @@ function blogCollectionOptions(options: OpenElementBlogOptions): CollectionOptio
         tags: 'string[]',
         excerpt: 'string',
         type: 'string',
+        lang: 'string',
       },
       transform(frontmatter, context) {
         const datePrefix = context.fileName.match(/^(\d{4}-\d{2}-\d{2})-/)?.[1];
@@ -51,6 +58,7 @@ function blogCollectionOptions(options: OpenElementBlogOptions): CollectionOptio
             tags: frontmatter.tags ?? [],
             ...(frontmatter.excerpt === undefined ? {} : { excerpt: frontmatter.excerpt }),
             ...(frontmatter.type === undefined ? {} : { type: frontmatter.type }),
+            ...(frontmatter.lang === undefined ? {} : { lang: frontmatter.lang }),
           },
         };
       },

packages/adapter-vite/src/internal/content/blog/types.ts

@@ -12,6 +12,12 @@ export interface BlogPostFrontmatter {
   excerpt?: string;
   /** Post type discriminator (e.g. 'adr', 'post') */
   type?: string;
+  /**
+   * Original language of the post body (e.g. 'en', 'zh'). Dispatches are
+   * single-language originals: sites serving multiple locales use this to
+   * mark locale-mismatched renders honestly instead of masquerading.
+   */
+  lang?: string;
 }
 
 /** A fully parsed blog post */

packages/adapter-vite/src/internal/content/sitemap/generator.ts

@@ -94,9 +94,15 @@ export function generateSitemap(distDir: string, options: SitemapOptions): strin
   // Scan for index.html files
   const htmlPaths = scanHtmlFiles(resolvedDist);
 
+  // 404 pages are never sitemap entries. The default-locale 404 is renamed to
+  // a flat 404.html by the SSG post-processor (so the scan never sees it);
+  // locale-prefixed 404s stay <locale>/404/index.html and would leak without
+  // this symmetric exclusion (#1307).
+  const without404 = htmlPaths.filter((path) => path !== '/404' && !path.endsWith('/404'));
+
   // Filter excluded paths. A pattern matches the path itself or a path
   // below it — excluding `/blog` must not also exclude `/blogroll` (#1039).
-  const includedPaths = htmlPaths.filter((path) => {
+  const includedPaths = without404.filter((path) => {
     return !exclude.some((pattern) =>
       path === pattern || path.startsWith(pattern.endsWith('/') ? pattern : `${pattern}/`)
     );

tools/apply-www-seo.ts

@@ -0,0 +1,71 @@
+/**
+ * Apply the per-route SEO plan to the built www output (#1307).
+ *
+ * Runs in `deno task build` after the adapter build and before Pagefind
+ * indexing: rewrites each built page's title/description/og metadata and
+ * injects canonical + hreflang links, derived from the committed content
+ * graph (content routes) and www/app/seo.ts (route-level pages). Fails
+ * closed — a built page without an SEO entry, an entry without a built
+ * page, or a page whose boilerplate anchors drifted all fail the build.
+ */
+import { walk } from '@std/fs/walk';
+import { join } from '@std/path';
+import type { ContentGraph } from './lib/content-graph.ts';
+import { applySeoToHtml, buildSeoPlan } from './lib/www-seo.ts';
+import { routeSeo } from '../www/app/seo.ts';
+
+export const WWW_DIST = 'www/dist';
+const CONTENT_GRAPH = 'www/app/data/_generated-content-graph.json';
+const SITE_LOCALES = ['en', 'zh'] as const;
+
+export async function applyWwwSeo(dist = WWW_DIST): Promise<string[]> {
+  const graph = JSON.parse(await Deno.readTextFile(CONTENT_GRAPH)) as ContentGraph;
+  const builtHtmlFiles: string[] = [];
+  for await (
+    const entry of walk(dist, {
+      includeDirs: false,
+      exts: ['.html'],
+      skip: [/(^|\/)pagefind(\/|$)/],
+    })
+  ) {
+    builtHtmlFiles.push(entry.path.slice(dist.length + 1));
+  }
+  builtHtmlFiles.sort();
+
+  const { plan, failures } = buildSeoPlan({
+    graph,
+    routeSeo,
+    locales: SITE_LOCALES,
+    builtHtmlFiles,
+  });
+  const rewritten: string[] = [];
+  if (failures.length === 0) {
+    for (const entry of plan) {
+      const path = join(dist, entry.file);
+      const html = await Deno.readTextFile(path);
+      const applied = applySeoToHtml(html, entry);
+      if (applied === null) {
+        failures.push({
+          file: entry.file,
+          message: 'expected boilerplate head anchors not found — template drift',
+        });
+        continue;
+      }
+      if (applied !== html) {
+        await Deno.writeTextFile(path, applied);
+        rewritten.push(entry.file);
+      }
+    }
+  }
+  if (failures.length > 0) {
+    console.error('www SEO application failed:');
+    for (const failure of failures) console.error(`- ${failure.file}: ${failure.message}`);
+    Deno.exit(1);
+  }
+  return rewritten;
+}
+
+if (import.meta.main) {
+  const rewritten = await applyWwwSeo();
+  console.log(`www SEO applied to ${rewritten.length} page(s).`);
+}

tools/autoflow/policy.ts

@@ -253,7 +253,9 @@ const GATES: readonly GateDefinition[] = [
     // owned truth — generated nav freshness (byte-identical regeneration of
     // route meta + headerNav), headerNav hrefs resolve to real routes,
     // bilingual locale availability (no orphan/missing/duplicated-untranslated
-    // zh), and the CURRENT roadmap entry names the package version tag.
+    // zh — extended #1307 to route-level content records and the blog
+    // single-language `lang` declaration), and the CURRENT roadmap entry
+    // names the package version tag.
     name: 'www:check-truth',
     command: ['deno', 'task', 'www:check-truth'],
     tiers: ['ci', 'release'],
@@ -266,11 +268,14 @@ const GATES: readonly GateDefinition[] = [
   {
     // #1159 (B2.4): guide/architecture code examples that import
     // @openelement/* must type-check against the real framework sources.
+    // #1307: the TS2304 suppression boundary reads the documented export
+    // names from the generated API reference.
     name: 'content:examples-check',
     command: ['deno', 'task', 'content:examples-check'],
     tiers: ['ci', 'release'],
     triggers: [
       /^www\/content\//,
+      /^www\/app\/data\/_generated-api-reference\.ts$/,
       /^packages\//,
       /^tools\/check-content-examples/,
       /^deno\.json$/,
@@ -434,10 +439,13 @@ const GATES: readonly GateDefinition[] = [
     tiers: ['ci', 'release'],
     // #1159: the build task ends with the built-output internal
     // link/fragment + SEO gate (www:check-links), so checker edits rebuild.
+    // #1307: the build also applies the derived per-route SEO plan
+    // (www:apply-seo) and the link gate asserts the generated reference
+    // anchors against the built apilist pages.
     triggers: [
       /^(packages|www)\//,
       /^deno\.json$/,
-      /^tools\/(?:check-www-links|lib\/www-links)/,
+      /^tools\/(?:check-www-links|lib\/www-links|apply-www-seo|lib\/www-seo)/,
     ],
   },
   {

tools/check-content-examples.test.ts

@@ -7,7 +7,7 @@ import {
 } from './check-content-examples.ts';
 import ts from 'typescript';
 
-Deno.test('extractExamples: only fenced ts/tsx blocks importing @openelement', () => {
+Deno.test('extractExamples: ts/tsx plus the typescript/js aliases, importing @openelement', () => {
   const markdown = [
     '```ts',
     "import { signal } from '@openelement/element';",
@@ -23,11 +23,18 @@ Deno.test('extractExamples: only fenced ts/tsx blocks importing @openelement', (
     "import { OpenElement } from '@openelement/element';",
     'export class X extends OpenElement {}',
     '```',
+    '```typescript',
+    "import { signal } from '@openelement/element';",
+    'const other = signal(1);',
+    '```',
+    '```js',
+    "import { signal } from '@openelement/element';",
+    'const plain = signal(2);',
+    '```',
   ].join('\n');
   const examples = extractExamples('guide/x.md', markdown);
-  assertEquals(examples.length, 2);
-  assertEquals(examples[0].lang, 'ts');
-  assertEquals(examples[1].lang, 'tsx');
+  assertEquals(examples.length, 4);
+  assertEquals(examples.map((example) => example.lang), ['ts', 'tsx', 'ts', 'ts']);
 });
 
 Deno.test('typeCheckExamples: framework-surface errors fail closed (RED proof)', async () => {
@@ -95,6 +102,17 @@ Deno.test('suppressElidedDiagnostic: suppression boundary is exact', () => {
     false,
   );
   assertEquals(suppressElidedDiagnostic(make(2304, "Cannot find name 'listEntries'.")), true);
+  // #1307: an undefined name that IS a documented framework export must not be
+  // suppressed — the snippet has to import it so its calls are type-checked.
+  assertEquals(suppressElidedDiagnostic(make(2304, "Cannot find name 'definePage'.")), false);
+  assertEquals(suppressElidedDiagnostic(make(2304, "Cannot find name 'signal'.")), false);
+  assertEquals(
+    suppressElidedDiagnostic(
+      make(2304, "Cannot find name 'listEntries'."),
+      new Set(['definePage']),
+    ),
+    true,
+  );
   assertEquals(
     suppressElidedDiagnostic(make(2339, "Property 'entries' does not exist on type '{}'.")),
     true,