[Web chore] Reconcile 0.43.2 truth and rebuild i18n, generated API reference, docs, SEO, IA, and visual quality

[SisyphusZheng]

Summary

A repository and rendered-output audit of www against the published v0.43.2 line found that the site successfully dogfoods the static-first path (SSG, DSD, content collections, islands, i18n expansion, UI primitives, Pagefind, dark/light themes), but it does not yet present one complete and mechanically current public product truth.

This is an umbrella web chore. It may land through multiple focused PRs, but the issue should close only when every work package and acceptance gate below is complete.

Current contract anchors:

• package and npm line: v0.43.2;
• product graph: element, app, adapter-vite, create, optional ui;
• maintenance mode under ADR-0140;
• no 0.44 feature train or next minor is scheduled;
• framework session/flash, active cache/ISR, streaming SSR, and framework-owned production recovery remain outside the current contract.

A static documentation site does not need to turn itself into a dynamic Supabase/Nitro application merely to dogfood every runtime feature. The required standard is:

1. www genuinely consumes the capabilities appropriate to a static documentation site.
2. Every other public capability is accurately documented and proven through copyable examples or dedicated fixtures/demos.
3. All public truth derives from repository evidence rather than parallel handwritten copies.

Audit evidence

The audit reproduced the following current output:

• deno task www:check-current-truth: pass;
• deno task www:check-theme-tokens: pass;
• deno task docs:check-version-anchors: pass;
• 56 www Deno tests: pass;
• deno task build: pass;
• 9 theme Playwright cases: pass;
• build: 33 route modules, 147 sitemap URLs, 148 HTML files;
• generated HTML: 12.24 MiB total;
• generated island JS: 152,072 raw bytes across 17 chunks;
• 12 broken internal links, all from English/Chinese changelog rendering;
• all 148 HTML files currently share one title, one description, one OG title, and homepage og:url;
• canonical links: 0;
• hreflang links: 0;
• light-theme sidebar text measured at approximately 2.07:1 contrast on white;
• public root symbols reported by deno doc --json: element 95, app 35, adapter-vite 44, ui 14 — 188 root symbols before supported-subpath expansion;
• /apilist currently renders package/subpath chips rather than those symbols.

Non-goals and invariants

• Do not schedule or imply a 0.44 train.
• Do not claim session, cache/ISR, streaming SSR, or generic production recovery as shipped.
• Do not add a package or change the five-package boundary.
• Do not expose internal package subpaths or internal symbols in API docs.
• Do not introduce a dynamic backend into www only for marketing dogfood.
• Do not duplicate package, release, or API truth in new handwritten data.
• Preserve canonical unprefixed English routes.
• Preserve static/no-JS usability and reduced-motion behavior.
• Keep the work compatible with the frozen 0.41/0.42/0.43 contracts.

Work packages

1. P0 — repair locale ownership and bilingual route behavior

Current cause:

• www/app/islands/open-layout.tsx derives _defaultLocale from the current page's locale attribute.
• On /zh/*, zh is therefore treated as the default locale.
• Header/footer links remain /docs, /blog, etc.
• The visible “English” switch resolves to /zh instead of the equivalent English route.
• Existing E2E covers English -> Chinese but not Chinese -> English or localized chrome links.

Implementation:

• Separate defaultLocale, declared/current locale, and URL-derived locale.
• Derive defaultLocale from the configured locale list (locales[0], currently en), never from the current page locale.
• During SSR, use the route-provided locale attribute as the current locale.
• In the browser, normalize location.pathname against the stable default locale.
• Localize header, sidebar, footer, CTA, pager, and language-switch hrefs during SSR so correctness does not depend on island activation.
• Preserve the current path when switching both directions: /guide/configuration -> /zh/guide/configuration; /zh/guide/configuration -> /guide/configuration.
• Correct the stale locale scope note that says only Guide is translated.
• Define and enforce a locale availability matrix:
  • fully bilingual surfaces receive canonical en/zh pairs;
  • shared English historical content must not be emitted as a fake Chinese duplicate;
  • a blog post gets a /zh/ route only when a localized source exists;
  • fallback pages use the actual content language and do not emit false hreflang alternates.
• Translate the blog index chrome if /zh/blog remains a real localized route.

Required tests:

• Unit tests for default/current locale separation.
• Build-output assertions that every internal data-nav/chrome href on /zh/* stays in /zh/*, except the deliberate English locale switch.
• Playwright tests for forward and reverse switching while preserving the path.
• Playwright assertions for Chinese header/footer/sidebar links.
• Tests that untranslated blog content is not duplicated under a false lang="zh" route.

2. Reconcile release, roadmap, package, and homepage truth

Current drift:

• www/app/routes/roadmap.tsx marks shipped v0.42 as planned.
• It presents v0.43-v0.46 as a future direction despite maintenance mode and no scheduled minor.
• The visual package graph renders Elements / UI / Framework / Protocols, omits create and adapter-vite, and reintroduces retired product language.
• The footer also exposes Protocols.
• Homepage and Docs promise a “next product boundary” that does not exist.
• Homepage labels 0.43.2 the “cumulative maintenance baseline”; 0.43.1 is the cumulative baseline and 0.43.2 is the stabilization patch.
• “Framework deps: zero” and “ZERO RUNTIME” are insufficiently qualified.
• The changelog's current card does not describe the actual 0.43.2 runtime/failure-containment work.
• The public changelog injects root CHANGELOG.md, even though that file explicitly says it is an unsynchronized historical aggregate.

Implementation:

• Represent 0.41, 0.42, and 0.43 as shipped lines.
• Represent 0.43.2 as current maintenance; show “next minor: not scheduled”.
• Remove the planned v0.42, future v0.43-v0.46, and ambiguous “audit round 2” timeline rows.
• Generate the package graph from the machine-readable package surface rather than maintaining product labels in open-standards-visual.tsx.
• Render all five current packages and their actual responsibilities.
• Remove Protocols from current footer/product language.
• Replace “next product boundary” copy with maintenance/current-evidence language.
• Describe 0.43.1 as the cumulative maintenance baseline and 0.43.2 as its compatible runtime stabilization patch.
• Replace “zero runtime/deps” with a precise claim such as “no mandatory page runtime for static DSD” and “no VDOM/UI-framework runtime requirement”; do not hide the private @preact/signals-core engine or optional Preact bridge.
• Stop treating root CHANGELOG.md as the current release feed.
• Build the current release registry from authoritative docs/release/v*.md records; filter out *-plan.md.
• Put 0.43.2, 0.43.1, and 0.43.0 first, with exact release summaries and upgrade posture.
• Keep root CHANGELOG.md available only as an explicitly labeled historical archive.
• Convert repository-relative evidence links to valid GitHub URLs or real site routes.
• Split current releases from the long historical archive so the page is navigable.

3. Required architecture — automatically generate a real API Reference

/apilist must remain an actual API Reference. Renaming it to “Package Surface” is not the chosen implementation.

3.1 Single-source inputs

• Extract the existing normalizeExports and package-surface-map parser into a shared tools/lib/package-surface.ts.
• Reuse that helper from tools/check-package-surface.ts, tools/check-public-docs-integrity.ts, and the new API generator.
• Use docs/current/PACKAGE_SURFACE.md's <!-- package-surface-map --> as the supported-vs-internal policy source.
• Use each package's deno.json exports as the physical module source.
• Fail if the policy map and package exports disagree before generating docs.
• Include only supported entries. Exclude internal entries such as @openelement/app/i18n from author-facing API pages.

3.2 Deterministic generator

Add tools/generate-www-api-reference.ts with generate and --check modes.

For every supported library module:

1. Resolve the export target from the package's deno.json.
2. Run the repository Deno executable with deno doc --json <target>.
3. Fail on a non-zero process result or an unresolved supported entry.
4. Read the root node's documented symbols.
5. Normalize symbols into a deterministic schema, sorted by package, subpath, kind, and name.
6. Preserve symbol name/kind, import specifier, declaration/signature, type parameters, parameters, optional/default state, return type, class/interface properties and methods, JSDoc, examples, deprecation markers, source location, and re-export ownership.
7. Resolve cross-references between public symbols where possible.
8. Never copy internal/unexported declarations into the public index merely because they are reachable in the declaration graph.

UI augmentation:

• Merge packages/ui/src/generated-manifest.json into the Deno symbol model.
• For each custom element show tag/class, import path, attributes and defaults, events, slots, CSS parts, DSD/SSR layer, and hydration strategy.
• Keep tools/generate-ui-manifest.ts as the component metadata source; do not rescan UI with a second ad-hoc parser.

Create package:

• Render @openelement/create as a CLI reference rather than pretending CLI internals are a library API.
• Generate its version, invocation, commands/options, and help text from packages/create/deno.json plus the real CLI --help path.
• Fail the check if the documented CLI surface drifts from generated help.

Output:

• Emit a deterministic generated module such as www/app/data/_generated-api-reference.ts (or equivalently typed JSON plus a checked TS facade).
• Do not include timestamps that make identical source produce different output.
• Include a source fingerprint/version so the site can display the package line and the gate can diagnose drift.
• Add deno task generate:www-api and deno task www:api:check.
• Run generation before build, test, and typecheck; run --check in truth/CI gates.
• Replace the handwritten packages/exports arrays in www/app/routes/apilist.tsx.

3.3 API information architecture

• Keep /apilist as the package/API landing page.
• Generate SSG detail pages using getStaticPaths, for example /apilist/element, /apilist/element/sanitize, plus stable symbol anchors or routes beneath the owning module.
• Each package/module page must include install/import example, supported subpaths, symbol count, kind filters, symbol index, and complete signatures/documentation.
• Each symbol must have a stable deep link and GitHub source link.
• Add package/subpath/symbol entries to Pagefind.
• Generate per-page title, description, canonical URL, OG metadata, and locale alternates.
• Keep the separate “API Routes” guide unambiguously labeled; footer/header API must point to /apilist.
• For English-only generated reference prose, localize UI labels without fabricating translated symbol documentation. Source-authored JSDoc remains canonical.

3.4 API drift gates

• www:api:check fails when fresh generation differs from the generated artifact.
• A supported new export cannot merge without appearing in the API Reference.
• A removed export cannot remain documented.
• An internal subpath/symbol cannot appear.
• Every generated symbol route builds and has a unique anchor.
• Test re-exports, overloads, generics, optional parameters, deprecated symbols, classes/interfaces, and UI CEM augmentation.
• Update tools/check-package-surface.ts to validate generated API data instead of regex-parsing handwritten chips.

4. Complete the user documentation

Strong existing pages (configuration, routing-and-data, error-handling, security, deployment) should be preserved and integrated into a coherent learning path.

• Expand Getting Started into a complete first application: prerequisites/install, generated tree, first element/page/island, dev, build/preview, Node/Workers deployment, next steps.
• Expand Core Concepts with the actual component, page, application, DSD, island, loader/action, and build ownership model.
• Add a component/reactivity guide covering props/attributes/reflection, JSX/events, signals/computed/effect, keyed For, context, errors, safe HTML, light vs shadow DOM, and lifecycle.
• Expand Islands and SSR with defineIsland, static metadata, load/idle/visible/only, DSD/client-only behavior, package islands, mismatch diagnostics, and failure modes.
• Replace the placeholder MDX page with real configuration, syntax, component use, sanitization/trust boundaries, and a buildable example.
• Replace the placeholder Testing page with exact commands, unit/e2e/visual strategy, fixture guidance, and release-relevant gates.
• Rename and expand Migration to cover 0.40 -> 0.41 -> 0.42 -> 0.43, including current 0.43 admission/diagnostic and package-ownership changes.
• Add a first-class Integrations landing page and sidebar group.
• Promote the verified Supabase x Cloudflare path, Better Auth, Drizzle, validation, rate limiting, and storage recipes without presenting providers as framework-owned features.
• Add a complete Universal WC SSR/third-party compatibility guide: explicit package admission, CEM input, deterministic DSD/light/client-only classification, unknown behavior, mismatch diagnostics, corpus evidence, and copyable Lit/FAST/Stencil examples.
• Maintain English/Chinese parity for all authored guide content.
• Compile or type-check code snippets/fixtures so examples cannot silently rot.
• Clearly mark session/cache/ISR/streaming/recovery as out of scope and unscheduled.

5. Generate truthful per-route SEO and locale metadata

Current www/vite.config.ts injects one static title/description/OG URL into every page.

• Introduce a site-owned SEO record keyed by generated route and locale, derived from route metadata, content frontmatter, blog/release records, and generated API data.
• Apply SEO during the SSG build, not client-side.
• Prefer a site-only post-render/build integration over adding a new public framework API during maintenance mode.
• Generate unique title, description, og:title, og:description, og:url, suitable og:type, and canonical URL.
• Generate hreflang="en", hreflang="zh", and x-default only when equivalent content actually exists.
• Do not emit fake Chinese alternates for untranslated historical content.
• Ensure sitemap locale expansion follows the same availability matrix.
• Add a generated-output SEO checker covering all HTML files.
• Add representative share-card/browser-title E2E assertions.

6. Reorganize navigation and long-form surfaces

• Change primary navigation to user tasks: Docs/Get Started, Guide, API, Architecture, GitHub.
• Move Roadmap, Blog, Changelog, and Contributing to secondary/project navigation and footer.
• Regroup the sidebar: Start; Build; Core; Routing/Data/Forms; Production; Integrations; Reference; Architecture; Project/History.
• Ensure Getting Started is visible before historical/reference material.
• Make header, sidebar, mobile menu, footer, breadcrumbs, pager, and search results use one route-label source.
• Point every generic “API” label to /apilist; reserve “API Routes” for /guide/api.
• Give Blog a complete archive rather than featured + four rows: all public posts, pagination/progressive archive, tag/date filters, search entry, clear historical labels.
• Separate current changelog, stable release archive, withdrawn artifacts, and deep historical content.
• Keep long pages readable and avoid a four-item TOC for hundreds of historical sections.

7. Accessibility and visual polish

• Raise sidebar, breadcrumb, muted metadata, and right-rail text contrast to WCAG AA: normal text >= 4.5:1; large text >= 3:1.
• Add automated axe coverage for desktop/mobile and light/dark representative pages.
• Add a direct contrast regression assertion for --text-muted uses on white/light surfaces.
• Protect the homepage composed. headline from low-contrast overlap with the cream dragon.
• Raise hero lede, stamp, and scroll-cue contrast where they carry readable content.
• Avoid hiding meaningful first-viewport text behind 0.45-1.1s opacity delays; enhance an already visible SSR composition.
• Preserve the current reduced-motion fallback.
• Eliminate the mobile TOC first-paint expansion/collapse using separate desktop/mobile SSR markup or an equivalent no-mutation approach.
• Verify keyboard focus, 200% zoom, touch targets, screen reader labels, and no horizontal overflow at 390px.
• Keep the dragon identity, but place concrete technical proof immediately after the hero.

8. Restore selective island delivery and reduce repeated HTML cost

Package islands:

• Stop loading every configured @openelement/ui manifest entry on every page.
• Prefer generating client strategy buckets from tags actually admitted in rendered page output.
• At minimum, replace blanket packageIslands: ['@openelement/ui'] in www with explicitly required client components.
• Preserve SSR-only UI primitives without sending their client modules.
• Ensure filtering does not break late morphs or the existing open:ready strategy contract.
• Add tests proving pages without dropdown/tabs/dialog do not request those chunks.
• Record before/after raw and compressed client sizes.

Shared head styles:

• Move the shared Open Props/token sheet and Prism theme out of repeated per-page <style> fragments into hashed same-origin stylesheets.
• Keep only genuinely critical, small first-paint CSS inline.
• Remove repeated unsafe-head-fragment build warnings.
• Preserve theme initialization without flash and without third-party blocking resources.
• Record before/after total HTML, representative compressed page, head, and client-JS bytes.

9. Replace the placeholder benchmark with generated evidence

Current www/content/architecture/benchmark.md says 30 route modules / 205 sitemap URLs; the current build emits 33 / 147. Other rows say only “Measured by CI performance evidence.”

• Generate route, sitemap, HTML, head, client-JS, and build metrics from the actual build manifest/output.
• Remove unmeasured placeholder rows or attach real values, environment, commit, command, and evidence artifact.
• Distinguish product performance contracts from one-machine benchmarks.
• Make stale hard-coded route/sitemap counts fail a gate.
• Keep the benchmark page honest about what is and is not measured.

10. Reconcile internal www/design documentation with implementation

• Mark superseded mockups/specs explicitly archival.
• Update the current design contract to the implemented v5 visual system and current product line.
• Document the controlled letter-spacing scale and homepage palette exception rather than claiming universal zero tracking/no local palette.
• Either adopt shared components required by a spec or rewrite/remove the stale spec; do not keep both.
• Remove unused open-page-hero if the current reading-shell/section-frame system is the chosen contract.
• Update the Docs landing spec to the task-oriented implementation and real UI primitive dogfood.
• Derive visual baseline counts from the route/locale/theme/viewport matrix rather than hard-coding 240.
• Keep design documentation and visual tests in the same PR as material design changes.

11. Expand truth, link, SEO, i18n, and artifact gates

Current www:check-current-truth scans www/app/routes, www/app/site-ui, and www/vite.config.ts, but not authored www/content or active design documents.

• Include current www/content and non-archival www/design sources in website truth scans.
• Make history-aware exclusions explicit and narrow.
• Add a build-output internal link and fragment checker; require zero failures.
• Add per-route SEO uniqueness/canonical/hreflang checks.
• Add reverse-i18n and localized-chrome checks.
• Add generated API drift/route/anchor checks.
• Generate package graph and release registry truth rather than regex-checking another handwritten copy.
• Reject delivered versions labeled planned and unscheduled minors presented as assigned work.
• Include measured benchmark/artifact truth.
• Run the new gates from root test/build/CI paths.

Suggested implementation order

1. Locale ownership and reverse-switch E2E.
2. Changelog broken links and current 0.43.2 truth.
3. Roadmap/package graph/homepage/footer truth.
4. Shared package-surface helper and generated API data pipeline.
5. API routes/UI/Pagefind and API drift gates.
6. Per-route SEO and locale availability matrix.
7. Documentation expansion and IA/navigation.
8. Accessibility/mobile TOC/hero motion.
9. Package-island and shared-head performance work.
10. Benchmark generation, design-contract cleanup, and final gate consolidation.

Final acceptance

• /zh/* navigation remains localized and locale switching works both directions with path preservation.
• No false localized historical route is emitted.
• Roadmap, homepage, footer, package graph, changelog, status, and release records agree on 0.43.2 maintenance truth.
• No shipped version is labeled planned; no next minor is implied.
• /apilist is generated from the real supported public surface and contains complete symbol-level reference pages.
• Every supported export is documented; no internal/removed export is documented.
• UI components include generated attributes/events/slots/CSS parts/SSR/hydration metadata.
• Getting Started and core 0.43 guides are complete, bilingual, and example-verified.
• All generated pages have correct title, description, canonical, OG URL, and truthful hreflang.
• Zero broken internal links or fragments.
• Representative text contrast passes WCAG AA.
• Mobile TOC causes no hydration-driven first-paint collapse.
• Unused UI island chunks are not requested.
• Shared head CSS is no longer repeated in every HTML document except a minimal critical subset.
• Benchmark values come from current build evidence.
• Non-archival design docs describe the implementation that actually ships.
• Existing theme, visual, browser, package-surface, release-truth, and framework contract gates remain green.
• The worktree is reproducible from a clean clone with no manual generated-file edits.

Required verification

At minimum run and report:

deno fmt --check
deno lint
deno task typecheck
deno task generate:www-api
deno task www:api:check
deno task package-surface:check
deno task www:check-current-truth
deno task www:check-theme-tokens
deno task docs:check-version-anchors
deno task docs:truth
deno task build
deno task test

Also run targeted package-surface/API tests, i18n/API Playwright suites, generated-output SEO/link checks, axe in both themes/viewports, Chromium visual baselines, required Firefox/WebKit functional coverage, and before/after output-size evidence.

Completion evidence to attach

• final route/sitemap/API-symbol counts;
• zero-link-failure report;
• SEO uniqueness/canonical/hreflang report;
• generated API check output;
• screenshots for home, Docs, API package/symbol pages, roadmap, changelog, blog archive, and a long guide across relevant viewport/theme/locale states;
• contrast/axe report;
• before/after HTML/head/client-JS size table;
• exact commands and commit SHA used for verification.

[SisyphusZheng]

Superseded by the 0.44 Content Graph task group:

• [0.44 beta.2] Build the typed Content Graph for website and API truth #1157 — unified typed Content Graph
• [B2] Make documentation and API reference derive from repository truth #1158 — generated JSDoc/API/CEM reference
• [0.44 beta.2] Drive website navigation, releases, i18n, SEO, and links from owned truth #1159 — generated navigation/releases/roadmap/i18n/SEO/links
• [0.44 internal alpha.7] Establish compiler, runtime, claim, and delivery performance budgets #1176 — generated performance evidence

ADR-0145 changes the implementation model: factual docs are generated from owned sources and consumed through Content Collections instead of expanding this old 0.43.2 maintenance umbrella. Accessibility and visual-polish findings remain valid input to #1159 or a focused follow-up, but this umbrella is no longer the execution authority.