docs(www,tools): B2.3 website qualification on the v0.44 product surface (#1177)

[SisyphusZheng]

Problem

#1177 (B2.3, stage #1288): rebuild/qualify the public website on the qualified v0.44 product surface as an external product would. The site was already migrated to the compiled element model during Beta.1 (#1261/#1262); this PR performs the Beta.2 acceptance pass: stale-0.43 content hunt, mechanical proof of the public import boundary, packed-artifact consumption evidence, and the full browser battery — and it surfaced one genuine pre-RC artifact defect (below).

Owner

B2.3 executor (.agents/v044-kimi-implementer.md profile; dispatch authorizes branch + PR, no merge).

Before

• www/content/architecture/{architecture,package-compatibility,comparison}.md (+zh) described the WC SSR classification/corpus and the Supabase × Cloudflare composition path as "the 0.43 line" in present tense on current-product pages, while the current line is the compiled v0.44 line.
• www/content/guide/migration.md (+zh) (historical 0.41 guide naming retired defineElement authoring) carried no scope marker for a 0.44 reader.
• No mechanical proof that www's @openelement/* imports stay inside the published export maps — the "published boundary is identical" allowance for in-repo workspace resolution was unverified.

After

• Current-truth pages attribute the WC SSR classification/corpus and composition path to the current line (CI-gated on dev via third-party-wc:smoke and fullstack qualification), recording the 0.43 origin as history; comparison scopes its adoption caution to the stable 0.43 line explicitly.
• The 0.41 migration guide carries a historical-record banner: the current line is consumed fresh via @openelement/create; no supported 0.43 → 0.44 in-place upgrade (B2.5 ruling).
• tools/check-package-surface.ts now asserts the www public-import boundary: every @openelement/* specifier in the shipped site surface (www/app + vite.config.ts/content-collections.ts/build-pagefind.ts, incl. @jsxImportSource) must resolve to a published export subpath of the five retained packages; www-local import-map aliases from www/deno.json are the only exceptions. Wired into the existing CI-gated package-surface:check (AutoFlow triggers extended to www/ + the tool) — no new governance surface.

Why-not-second-owner

The import-boundary assertion extends an existing gated checker instead of adding a new tool/task/CI job, per the B2.6/B2.7 net-reduction rule for governance surface. Content edits are www-local; no framework/UI public-surface change is made or hidden in website glue.

Evidence

Local gates (branch tip b039456d):

Gate	Result
deno task package-surface:check (extended)	PASS; negative control: temporary www/app/__boundary-probe.ts importing @openelement/element/src/protocol/data.ts fails the gate with www import boundary: ... is not a published export subpath (exit 1), passes after removal
deno test --allow-read --allow-env tools/check-package-surface.test.ts	11 passed / 0 failed (RED first: type-check failure before implementation)
deno task build (incl. www:pagefind, www:check-artifact-truth)	PASS; 150 pages indexed
deno task test (full repo suite)	exit 0
deno task test:e2e:browsers (Chromium+Firefox+WebKit, 519 tests)	491 passed, 2 flaky→passed on retry (webkit blog-index links, webkit OG description timing), 16 skipped, 4 failed — all chromium mobile visual baselines, sole diff route architecture-islands-deep (zh/en × dark/light mobile)
deno task www:check-current-truth / docs:truth / www:check-theme-tokens / export-files:check / freeze:semantics:check / typecheck / www:dev-smoke / fmt / lint	all PASS
deno task pack:dry-run	PASS, five 0.44.0-beta.1 tarballs

Visual-baseline adjudication (carried risk #2 in #1288): the 4 mobile failures show only CJK font-rasterization ghosting on /architecture/islands-deep — a route this PR does not touch (git diff --name-only confirms); the diff images show glyph-level offset, not layout change. Pixel baselines are skipped on CI by design (test.skip(!!CI …)). Pre-existing local macOS drift; NOT normalized here. The 5 edited pages render correctly and their baselines still match.

Beta.2 scorecard

• Browser flows: 491/519 green across Chromium/Firefox/WebKit on the real built site — SSR/DSD layers, claim/hydration behavior, delayed island delivery (hydrate: 'idle' islands), SPA action chain + shadow-piercing form submit (forms), nested CE, search (pagefind overlay + keyboard), i18n locale routing (en/zh), navigation/router guards, theme system, view transitions/speculation.
• Accessibility: WCAG AA color-pair and heading-level e2e green (accessibility-performance.spec.ts).
• Output chunks: client islands open-layout 50 KB, cinematic-scroll 92 KB, hero-polish 5.1 KB, dragon-live-gaze 17 KB, page-rail 8.6 KB, light-probe 6.0 KB, entry client.js 7.3 KB; total 223 KB. Budget warnings (>50 KB island, >200 KB total) are pre-existing and unchanged by this PR.
• Links: navigation-routing + blog-index e2e green; header nav hand-maintained in www/vite.config.ts (B2.4 input).
• SEO: og/twitter/description/lang/viewport/favicon/sitemap.xml/robots.txt e2e green (seo-meta.spec.ts).
• Deployment: Cloudflare Pages PR check — see this PR's checks.
• Artifact consumption: pack:dry-run green; in-repo boundary proven identical by the new gate. Packed-artifact-alone build: FAILS — see finding below.

Finding (pre-RC integration defect, surfaced by the packed-artifact exercise)

Building www against the packed 0.44.0-beta.1 tarballs with no workspace (scratch: .tmp/www-packed-consumer.sh, temp dir outside the repo so the adapter's workspace-alias generator stays null and resolution is node_modules-only) gets through Phase 1/2 and SSG-admission, then fails:

[openElement] admitted nested component <open-theme-toggle> is not registered
with a compiled Part Program.  code: OE_PROGRAM_MISSING, phase: ssr
→ SSG failed: dynamic route /blog/... could not be rendered

Root cause: deno pack erases the compile-time-only @element/@property decorator intrinsics (ADR-0143: inert no-ops at runtime, recognized by binding provenance in source) when compiling @openelement/ui to npm .js (applyDecs2203R lowering; verified in both the local dry-run tarball and the published registry artifact ui-0.44.0-beta.1.tgz). The packed UI package therefore cannot be SSR-admitted via the documented packageIslands: ['@openelement/ui'] path (packages/ui/README.md documents exactly this npm consumption). B2.1/B2.2 qualified UI through the ui-dogfood fixture, which resolves workspace source — the packed-artifact path was never exercised.

Per the B2.3 ruling ("if you NEED a surface change, STOP and report it as a finding instead of working around it locally"), no website-local workaround was applied; fixing the pack pipeline / artifact shape is a release-surface decision for the stage (candidate owners: B2.5 consumer paths or a new Beta.2 defect issue).

Scope

In: www content truth (stale-0.43 hunt), www import-boundary gate, evidence battery. Out: generated-truth machinery for nav/releases/i18n/SEO (#1159 → B2.4, consumed/anticipated only); public-route E2E expansion (#1232 → B2.10; routes remain E2E-addressable, no selector changes); Starter external-consumer matrix (B2.5); the packed-ui artifact defect (finding above); visual-baseline re-record (carried risk #2, stage closure).

Risk

Low: 8 markdown files + 1 gated checker + AutoFlow triggers. No frozen-semantics paths touched (freeze:semantics:check OK). The extended gate fails closed on any future private-source import from www.

Refs #1177. Acceptance-bar status: IA coherent + truth-consistent claims + v0.44 consumer surface + green browser flows are met; the strict "builds from public candidate artifacts alone" item is blocked by the ui npm-artifact finding above, so this PR does not close #1177 by itself.

[github-actions]

APIError: Insufficient Balance

opencode session  |  github run