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

* test(tools): gate www public-import boundary against published export maps (#1177, B2.3)

The website is an npm-first consumer of the five retained packages. Prove
mechanically that every @openelement/* specifier in the shipped site surface
(www/app plus vite.config/content-collections/build-pagefind) resolves to a
published export subpath — never a private source path — so in-repo workspace
resolution is identical to the packed npm artifact boundary. Negative control:
a temporary private-source import fails the gate.

* docs(www): retire present-tense 0.43 product claims from current-truth pages (#1177, B2.3)

The architecture collection described the WC SSR classification, corpus and
the Supabase x Cloudflare composition path as 'the 0.43 line' in present
tense while the current line is the compiled v0.44 line; the machinery is
CI-gated on dev (third-party-wc:smoke, fullstack qualification), so the
claims now name the current line and record the 0.43 origin as history.
comparison.md scopes its adoption caution to the stable 0.43 line explicitly.
The 0.41 migration guide gains a historical-record banner: the current line
is consumed fresh via @openelement/create, with no supported 0.43 -> 0.44
in-place upgrade (B2.5 ruling).

---------

Co-authored-by: DevBot <devbot@openelement.dev>

Author: SisyphusZheng

tools/autoflow/policy.ts

@@ -37,7 +37,15 @@ const GATES: readonly GateDefinition[] = [
     name: 'package-surface:check',
     command: ['deno', 'task', 'package-surface:check'],
     tiers: ['push', 'ci', 'release'],
-    triggers: [/^packages\//, /^deno\.json$/, /^tools\/lib\/package-graph\.ts$/],
+    triggers: [
+      /^packages\//,
+      /^deno\.json$/,
+      /^tools\/lib\/package-graph\.ts$/,
+      // #1177 (B2.3): the gate also asserts the www public-import boundary.
+      /^www\//,
+      /^tools\/check-package-surface\.ts$/,
+      /^tools\/lib\/typescript-ast\.ts$/,
+    ],
   },
   {
     name: 'interface:snapshot',

tools/check-package-surface.test.ts

@@ -3,6 +3,8 @@ import {
   EXPORT_STABILITY_CLASSES,
   exportClassDrift,
   extractExportClassMap,
+  extractWwwPackageSpecifiers,
+  wwwImportBoundaryDrift,
 } from './check-package-surface.ts';
 
 const DOC = `# Package Surface Inventory
@@ -82,3 +84,75 @@ Deno.test('exportClassDrift rejects unknown stability classes and missing entrie
   const missing = exportClassDrift(map, '@openelement/element', 'sanitize', []);
   assertStringIncludes(missing.join('\n'), 'sanitize');
 });
+
+// ─── www public-import boundary (#1177, B2.3) ─────────────
+// The website must consume @openelement/* exactly as an external npm consumer
+// would: every specifier resolves to a published export subpath of one of the
+// five retained packages, never to a private source path. www-local import-map
+// aliases declared in www/deno.json are the only permitted non-package
+// @openelement specifiers.
+
+const WWW_EXPORTS = new Map([
+  ['@openelement/element', new Set(['.', 'jsx-runtime', 'jsx-dev-runtime', 'sanitize'])],
+  ['@openelement/ui', new Set(['.', 'open-theme-toggle'])],
+]);
+const WWW_LOCAL_ALIASES = ['@openelement/site-ui/', '@openelement/generated/'];
+
+Deno.test('wwwImportBoundaryDrift accepts published root and subpath specifiers', () => {
+  assertEquals(
+    wwwImportBoundaryDrift(
+      [
+        '@openelement/element',
+        '@openelement/ui/open-theme-toggle',
+        '@openelement/element/sanitize',
+      ],
+      WWW_EXPORTS,
+      WWW_LOCAL_ALIASES,
+    ),
+    [],
+  );
+});
+
+Deno.test('wwwImportBoundaryDrift accepts www-local aliases declared in www/deno.json', () => {
+  assertEquals(
+    wwwImportBoundaryDrift(
+      ['@openelement/site-ui/locale.ts', '@openelement/generated/nav'],
+      WWW_EXPORTS,
+      WWW_LOCAL_ALIASES,
+    ),
+    [],
+  );
+});
+
+Deno.test('wwwImportBoundaryDrift rejects unpublished subpaths and unknown packages', () => {
+  const drift = wwwImportBoundaryDrift(
+    ['@openelement/element/src/protocol/data.ts', '@openelement/content'],
+    WWW_EXPORTS,
+    WWW_LOCAL_ALIASES,
+  );
+  assertEquals(drift.length, 2);
+  assertStringIncludes(drift[0], '@openelement/content');
+  assertStringIncludes(drift[1], 'src/protocol/data.ts');
+});
+
+Deno.test('wwwImportBoundaryDrift ignores non-openelement specifiers', () => {
+  assertEquals(
+    wwwImportBoundaryDrift(['vite', './local.ts', 'npm:marked@15'], WWW_EXPORTS, []),
+    [],
+  );
+});
+
+Deno.test('extractWwwPackageSpecifiers collects imports, exports and jsxImportSource', () => {
+  const source = `/** @jsxImportSource @openelement/element */
+import { OpenElement } from '@openelement/element';
+import '@openelement/ui/open-theme-toggle';
+export { signal } from '@openelement/element';
+const lazy = import('@openelement/element/sanitize');
+import './relative.ts';
+`;
+  assertEquals(extractWwwPackageSpecifiers(source).sort(), [
+    '@openelement/element',
+    '@openelement/element/sanitize',
+    '@openelement/ui/open-theme-toggle',
+  ]);
+});

tools/check-package-surface.ts

@@ -4,8 +4,11 @@ import {
   RETAINED_PACKAGE_NAMES,
 } from './project-constants.ts';
 import { readPackages, releasePublishOrder } from './lib/package-graph.ts';
+import { extractStaticModuleSpecifiers } from './lib/typescript-ast.ts';
 import { OPENELEMENT_EXPORT_FILES } from '../packages/adapter-vite/src/generated-export-files.ts';
 import { resolve } from '@std/path';
+import { exists } from '@std/fs';
+import { walk } from '@std/fs/walk';
 
 const retainedPackages = [...RETAINED_PACKAGE_NAMES].sort();
 const removedPackages = [...REMOVED_PACKAGE_NAMES].sort();
@@ -167,6 +170,53 @@ const APILIST_REQUIRED_PACKAGES = [
   '@openelement/adapter-vite',
 ];
 
+// ─── www public-import boundary (#1177, B2.3) ─────────────
+// The website must consume @openelement/* exactly as an external npm consumer
+// would: every specifier in the shipped site surface (www/app plus the build
+// entry points) resolves to a published export subpath of one of the five
+// retained packages — never a private source path. The only permitted
+// non-package @openelement specifiers are the www-local import-map aliases
+// declared in www/deno.json. www/e2e is deliberately out of scope: its probe
+// harness (browser-bundle.ts) bundles package sources in memory and ships
+// nothing.
+
+export function extractWwwPackageSpecifiers(source: string, path = 'source.ts'): string[] {
+  const specifiers = new Set<string>();
+  for (const { value } of extractStaticModuleSpecifiers(source, path)) {
+    if (value.startsWith('@openelement/')) specifiers.add(value);
+  }
+  for (
+    const match of source.matchAll(/\/\*\*?\s*@jsxImportSource\s+(@openelement\/[^\s*]+)/g)
+  ) {
+    specifiers.add(match[1]);
+  }
+  return [...specifiers];
+}
+
+export function wwwImportBoundaryDrift(
+  specifiers: readonly string[],
+  publishedSubpaths: ReadonlyMap<string, ReadonlySet<string>>,
+  localAliasPrefixes: readonly string[],
+): string[] {
+  const drift: string[] = [];
+  for (const specifier of specifiers) {
+    if (!specifier.startsWith('@openelement/')) continue;
+    if (localAliasPrefixes.some((prefix) => specifier.startsWith(prefix))) continue;
+    const segments = specifier.split('/');
+    const pkgName = segments.slice(0, 2).join('/');
+    const subpath = segments.slice(2).join('/') || '.';
+    const published = publishedSubpaths.get(pkgName);
+    if (!published) {
+      drift.push(`${specifier} does not resolve to a retained published package.`);
+      continue;
+    }
+    if (!published.has(subpath)) {
+      drift.push(`${specifier} is not a published export subpath of ${pkgName}.`);
+    }
+  }
+  return drift.sort();
+}
+
 async function main(): Promise<void> {
   for (const dir of ['packages', 'examples', 'www/app', 'tools/third-party-wc-smoke']) {
     await rejectRetiredImports(dir);
@@ -391,6 +441,56 @@ async function main(): Promise<void> {
     }
   }
 
+  // ─── www public-import boundary (#1177, B2.3) ─────────────
+  // Prove the shipped site surface (www/app + its build entry points) imports
+  // only published export subpaths, so workspace resolution during in-repo
+  // development is byte-identical to the packed npm artifacts.
+
+  const publishedSubpaths = new Map(
+    packages.map((pkg) => [
+      pkg.name,
+      new Set(Object.keys(normalizeExports(pkg.exports))),
+    ]),
+  );
+  const wwwConfig = JSON.parse(await Deno.readTextFile('www/deno.json'));
+  const localAliasPrefixes = Object.keys(wwwConfig.imports ?? {})
+    .filter((key) => key.startsWith('@openelement/'));
+
+  const wwwSurfaceFiles = [
+    'www/vite.config.ts',
+    'www/content-collections.ts',
+    'www/build-pagefind.ts',
+  ];
+  for await (
+    const { path: file } of walk('www/app', {
+      includeDirs: false,
+      skip: [/(^|\/)dist(\/|$)/],
+    })
+  ) {
+    if (/\.(?:ts|tsx)$/.test(file)) wwwSurfaceFiles.push(file);
+  }
+  const specifierOrigins = new Map<string, string[]>();
+  for (const file of wwwSurfaceFiles.sort()) {
+    if (!await exists(file)) continue;
+    const text = await Deno.readTextFile(file);
+    for (const specifier of extractWwwPackageSpecifiers(text, file)) {
+      const origins = specifierOrigins.get(specifier) ?? [];
+      origins.push(file);
+      specifierOrigins.set(specifier, origins);
+    }
+  }
+  for (
+    const item of wwwImportBoundaryDrift(
+      [...specifierOrigins.keys()],
+      publishedSubpaths,
+      localAliasPrefixes,
+    )
+  ) {
+    const specifier = item.split(' ')[0];
+    const origins = specifierOrigins.get(specifier) ?? [];
+    failures.push(`www import boundary: ${item} (imported by ${origins.join(', ')})`);
+  }
+
   if (failures.length > 0) {
     console.error('Package surface check failed:');
     for (const failure of failures) console.error(`- ${failure}`);

www/content/architecture/architecture.md

@@ -37,7 +37,7 @@ The roadmap earns WC fullstack leadership through compatibility evidence, comple
 
 ### WC SSR
 
-The 0.43 line classifies admitted standard, Lit, FAST and Stencil elements for DSD, light DOM or client-only rendering with actionable diagnostics and corpus evidence.
+The current line classifies admitted standard, Lit, FAST and Stencil elements for DSD, light DOM or client-only rendering with actionable diagnostics and corpus evidence — a contract first shipped on the 0.43 line and kept green by CI on the compiled line.
 
 ### Application loop
 

www/content/architecture/architecture.zh.md

@@ -35,7 +35,7 @@ order: 10
 
 ### WC SSR
 
-0.43 版本线会把已准入的标准、Lit、FAST 与 Stencil 元素分类为 DSD、light DOM 或仅客户端渲染，并提供可操作的诊断与语料证据。
+当前版本线会把已准入的标准、Lit、FAST 与 Stencil 元素分类为 DSD、light DOM 或仅客户端渲染，并提供可操作的诊断与语料证据——该契约最初随 0.43 线交付，并在编译型版本线上由 CI 持续验证。
 
 ### 应用闭环
 

www/content/architecture/comparison.md

@@ -47,13 +47,13 @@ order: 20
 - Choose **Astro / Enhance / Lit / Stencil** when a standards-first Web Components story matters and you want to avoid a heavy application runtime.
 - Choose **Next.js / Nuxt / SvelteKit** when your product is intentionally built around a React, Vue, or Svelte application model.
 - Choose **Fresh** when you want a Deno-native, near-zero-build Preact island experience.
-- Do not choose **openElement** when a mature ecosystem, a framework-specific UI runtime, or a ready-made enterprise design system is the main requirement. Teams adopting 0.43.x should validate the documented starter and deployment path against their own production environment.
+- Do not choose **openElement** when a mature ecosystem, a framework-specific UI runtime, or a ready-made enterprise design system is the main requirement. Teams adopting the stable 0.43 line should validate the documented starter and deployment path against their own production environment.
 
 ## The official composition path
 
 OpenElement × Supabase × Cloudflare is the verified fullstack delivery path, with explicit ownership boundaries: OpenElement owns the application UX; Supabase owns data, Auth, RLS, Storage and Realtime; Cloudflare owns edge delivery, security, cache and async execution. Supabase and Cloudflare are composed providers — never built-in framework features — and a tier-1 boundary gate keeps provider code out of the framework packages.
 
-Delivered in the 0.43 line together with Universal WC SSR. Framework-owned
+First shipped on the 0.43 line together with Universal WC SSR and carried by the current compiled line. Framework-owned
 production-runtime recovery and cache semantics remain outside the current
 contract and have no assigned release version.
 

www/content/architecture/comparison.zh.md

@@ -47,13 +47,13 @@ order: 20
 - 选择 **Astro / Enhance / Lit / Stencil** 当标准优先的 Web Components 方案很重要，且想避开沉重的应用运行时时。
 - 选择 **Next.js / Nuxt / SvelteKit** 当你的产品明确围绕 React、Vue 或 Svelte 应用模型构建时。
 - 选择 **Fresh** 当你想要 Deno 原生、近乎零构建的 Preact island 体验时。
-- 不要选择 **openElement** 当主要诉求是成熟生态、框架专属 UI 运行时或现成的企业级设计系统时。采用 0.43.x 的团队仍应在自己的生产环境中验证文档里的 starter 与部署路径。
+- 不要选择 **openElement** 当主要诉求是成熟生态、框架专属 UI 运行时或现成的企业级设计系统时。采用稳定 0.43 线的团队仍应在自己的生产环境中验证文档里的 starter 与部署路径。
 
 ## 官方组合路径
 
 OpenElement × Supabase × Cloudflare 是经过验证的全栈交付路径，所有权边界明确：OpenElement 负责应用 UX；Supabase 负责数据、Auth、RLS、Storage 与 Realtime；Cloudflare 负责边缘交付、安全、缓存与异步执行。Supabase 与 Cloudflare 是被组合的服务提供方——绝不是框架内建功能——tier-1 边界门禁保证服务提供方代码不进入框架包。
 
-随 0.43 线与 Universal WC SSR 一同交付。框架自有的生产运行时恢复与缓存语义仍在当前契约之外，尚未分配发布版本。
+最初随 0.43 线与 Universal WC SSR 一同交付，并由当前编译型版本线继承。框架自有的生产运行时恢复与缓存语义仍在当前契约之外，尚未分配发布版本。
 
 - [Supabase 配方](https://github.com/open-element/openelement/blob/main/docs/integrations/supabase.md)
 - [已验证的参考应用](https://github.com/open-element/openelement/tree/main/examples/supabase-cloudflare-starter)

www/content/architecture/package-compatibility.md

@@ -14,7 +14,8 @@ Known packages can be configured as package islands and use available CEM metada
 
 ## Current diagnostics
 
-The 0.43 line ships Universal DSD/light/client-only classification,
-hydration-mismatch diagnostics and the tracked third-party WC SSR corpus.
+The current line ships Universal DSD/light/client-only classification,
+hydration-mismatch diagnostics and the tracked third-party WC SSR corpus —
+first shipped on the 0.43 line and kept green by CI on the compiled line.
 Admission still depends on explicit package-island configuration and observed
 metadata; it is not a blanket certification of every third-party component.

www/content/architecture/package-compatibility.zh.md

@@ -14,4 +14,4 @@ order: 90
 
 ## 当前诊断
 
-0.43 版本线已经交付通用 DSD/light/client-only 分类、hydration 不匹配诊断与已跟踪的第三方 WC SSR 语料库。准入仍依赖显式 package-island 配置与已观测 metadata，并不意味着对所有第三方组件作笼统认证。
+当前版本线交付通用 DSD/light/client-only 分类、hydration 不匹配诊断与已跟踪的第三方 WC SSR 语料库——最初随 0.43 线交付，并在编译型版本线上由 CI 持续验证。准入仍依赖显式 package-island 配置与已观测 metadata，并不意味着对所有第三方组件作笼统认证。

www/content/guide/migration.md

@@ -4,6 +4,8 @@ lede: 'Every breaking change since 0.40.x, grouped by the version that shipped i
 order: 75
 ---
 
+> Historical record: this page archives the 0.40.x → 0.41/0.42 migrations, written for the retired runtime-authoring line. The current line ({{OPENELEMENT_VERSION}}) is consumed fresh through `@openelement/create` — there is no supported 0.43 → 0.44 in-place upgrade. New projects start from the current starter and the [getting-started guide](/guide/getting-started).
+
 ## 0.41.x → 0.42
 
 The stable 0.42 line added request-time surfaces — loaders, actions, progressive-enhancement forms, redirects and Nitro server output. Static-first sites upgraded without a breaking change to the frozen 0.41 surface. ADR-0122 records the accepted 0.42.0 contract.