Framework-level docs site contract for routing, events, theme, i18n, and search

[SisyphusZheng]

Summary

The docs site currently has several user-facing failures that should be fixed as framework contract issues rather than one-off www patches.

Observed failures from the current dev checkout:

• Theme toggle renders but clicking it does not change document.documentElement.dataset.theme.
• i18n / locale switching can update the URL without updating html[lang], nested less-layout[locale], title/head state, or switch-label state.
• Direct localized pages can disagree with their nested layout locale, e.g. /zh/ can be html lang=zh while the inner layout remains locale=en.
• Search opens and can return results, but the index contains stale paths such as /guide/routing, /guide/ssg, /guide/dsd, /guide/islands, /ui, and /community.
• Search SSR can render [object Object] because innerHTML={computedSignal} is stringified before signal unwrapping.
• guide/getting-started can lose its intended content grid because .content-grid depends on a local pageStyles import.
• Island metadata scanning can silently skip local islands when top-level customElements access throws during Deno-side metadata import.

Proposed SOP

I drafted the detailed remediation SOP at:

docs/sop/v0.27.0/SOP-006-www-framework-contract.md

The target contract is:

• zero manual route wiring in www: no route lists, header nav arrays, current-path strings, locale-prefix logic, or hand-maintained search index entries in page components.
• zero manual event wiring in www: docs components use normal JSX event props such as onClick and onInput; @lessjs/core owns SSR markers and client hydration.
• zero hardcoded layout CSS in www: shared docs layout primitives, content grids, TOC columns, theme tokens, and page containers come from @lessjs/ui primitives or generated theme assets.

Framework-level remediation plan

1. Generate a route manifest from @lessjs/content / @lessjs/adapter-vite.

   • Route pages export metadata only.
   • navSections, headerNav, localized paths, and route labels derive from the manifest.

2. Make @lessjs/i18n and @lessjs/router canonical for locale paths.

   • Parse locales only from configured locales.
   • SPA navigation must update URL, html[lang], title/head state, layout attributes, switch href/text, and active nav together.

3. Replace function-name event hydration in @lessjs/core.

   • Do not serialize Function.name into data-on-* as the primary contract.
   • Use framework-generated event IDs plus a VNode event table so inline JSX handlers hydrate correctly.

4. Unwrap signal-like innerHTML values in SSR.

   • innerHTML={computedSignal} must render the computed value, not [object Object].

5. Generate search index from the route manifest.

   • Remove manually maintained stale www/public/search-index.json entries.
   • Fail build if a generated search path does not exist in SSG output.

6. Move docs page layout styles into @lessjs/ui.

   • www should use a docs layout primitive or exported stylesheet preset, not local hardcoded grid CSS.

7. Stop executing browser-only islands during metadata scan.

   • Static metadata extraction should not require customElements to exist in Deno.

8. Update E2E coverage.

   • Theme click state.
   • Direct and SPA i18n state.
   • Search result path validity.
   • Docs layout grid structure.
   • No island metadata import failure in build logs.

Acceptance criteria

• www has no manual route list, search index, header nav, locale switch URL, or current-path wiring in route render methods.
• www route components can use normal JSX events without authoring data-on-* or method-name strings.
• www docs pages use framework-provided docs page styles or wrapper components.
• Search index generation fails fast on stale paths.
• Theme, i18n, search, and layout E2E tests pass against www/dist.
• Build logs do not hide island metadata failures.
• docs/status/STATUS.md and root README version/package-count claims are updated to match the validated package graph before release.

Baseline commands

These were used for the audit baseline:

deno task typecheck
deno task graph:check
deno task docs:check-current
deno task build
deno task dsd:check-report
deno run -A npm:@playwright/test@1.59.1 test --config www/e2e/playwright.config.ts --workers=1

The first five completed successfully in the baseline audit. Full Playwright timed out, but captured failures included stale /decisions.html and /en/decisions/ expectations plus theme-selector fragility caused by shallow less-layout lookup.