feat(release,www,ui,docs): stable 0.41.0 preparation — freeze scope, migration guide, content truths

- adapter-vite: prune 10 internal subpaths from exports at the freeze
  (app-vite, build-context, head-injection, i18n-plugin, plugin,
  generated-data-resolver, plugin-mdx, route-manifest, cli/build-client,
  cli/build-ssg); PACKAGE_SURFACE records the prune and the ADR-0119
  defineApp freeze boundary; snapshot + export-files regenerated
- migration: aggregate alpha-line -> 0.41.0 guide in
  docs/release/v0.41.0-migration.md plus a bilingual /guide/migration page
  (ui radius geometry breaking noted); history-surface exemption in the
  www-truth gate for version-dense migration content
- ui consumers evidence: deno-desktop-reader (open-button/card/input +
  tokens) and deno-desktop-mastodon (open-theme-toggle + tokens) recorded
  in packages/ui README for the v0.46 decision
- www: zh homepage content (locale-aware home), new dispatch
  'Three audits later, the stable line' featured on /blog (index now sorts
  by date desc), stale #390 remnants in roadmap artifact panel already
  corrected
- design: retire the broken indigo mockup pipeline (generate.mjs, v2/v3,
  old SVGs); v4 is the mockup set of record; CJK serif decision recorded
- #37 gate text refreshed (0.41.0 subset, RC-soak -> seven-day P0 watch)

Author: DevBot

docs/current/PACKAGE_SURFACE.md

@@ -56,7 +56,7 @@ promise and are not application-authoring surface.
   },
   "@openelement/adapter-vite": {
     "supported": [".", "nitro-mount", "cli/build", "sitemap"],
-    "internal": ["app-vite", "build-context", "head-injection", "i18n-plugin", "plugin", "generated-data-resolver", "plugin-mdx", "route-manifest", "cli/build-client", "cli/build-ssg"]
+    "internal": []
   },
   "@openelement/create": {
     "supported": ["."],
@@ -94,9 +94,25 @@ promise and are not application-authoring surface.
   `SpaAppInstance` / `SpaAppOptions`.
 - `@openelement/adapter-vite` internal subpaths (`app-vite`, `build-context`,
   `head-injection`, `i18n-plugin`, `plugin`, `generated-data-resolver`,
-  `plugin-mdx`, `route-manifest`, `cli/build-client`, `cli/build-ssg`) serve
-  the build pipeline and generated code; they may be pruned at the v0.41
-  freeze.
+  `plugin-mdx`, `route-manifest`, `cli/build-client`, `cli/build-ssg`) were
+  pruned at the 0.41.0 freeze (ADR-0119): they had zero consumer specifiers —
+  the build pipeline and generated code import only relatively or through the
+  supported root, `nitro-mount`, `cli/build` and `sitemap` subpaths. The module
+  files remain inside the package for internal relative imports only.
+
+## 0.41.0 interface freeze boundary (ADR-0119)
+
+Frozen at 0.41.0: `defineElement`, `definePage`, `buildApp`, the five-package
+graph, the supported subpaths above, and the static/SPA semantics of
+`defineApp` as shipped — file routes, `tagName` route elements, island
+configuration (`ssr`/`dsd`/`hydrate`), DSD output, and the SPA-mode
+loader/action chain.
+
+Explicitly not frozen: request-time data, forms, sessions and cache
+semantics (0.42 WC Application Loop and 0.44 Production Runtime scope), the
+`@openelement/ui` stable scope (decided at v0.46), and everything marked
+internal in the map above. Post-freeze changes to the frozen surface require
+a major-version ADR.
 - `@openelement/ui` supported subpaths: `open-badge`, `open-button`,
   `open-callout`, `open-card`, `open-code-block`, `open-dialog`,
   `open-dropdown`, `open-input`, `open-props-tokens`, `open-tabs`,

docs/release/v0.41.0-interface-snapshot.json

@@ -114,18 +114,8 @@
       "name": "@openelement/adapter-vite",
       "exports": {
         ".": "./src/index.ts",
-        "./app-vite": "./src/app-vite.ts",
-        "./build-context": "./src/build-context.ts",
         "./cli/build": "./src/cli/build.ts",
-        "./cli/build-client": "./src/cli/build-client.ts",
-        "./cli/build-ssg": "./src/cli/build-ssg.ts",
-        "./generated-data-resolver": "./src/generated-data-resolver.ts",
-        "./head-injection": "./src/head-injection.ts",
-        "./i18n-plugin": "./src/i18n-plugin.ts",
         "./nitro-mount": "./src/nitro-mount.ts",
-        "./plugin": "./src/plugin.ts",
-        "./plugin-mdx": "./src/plugin-mdx.ts",
-        "./route-manifest": "./src/route-manifest.ts",
         "./sitemap": "./src/sitemap.ts"
       },
       "declarations": {
@@ -141,64 +131,10 @@
             "export type { OpenMdxPluginOptions } from './plugin-mdx.ts';"
           ]
         },
-        "./app-vite": {
-          "sha256": "fbc9bbfd9964bfab9465a1f572ee12ee430b99fa0c216aa2937a8e7a2cfc5ad2",
-          "publicDeclarations": [
-            "export interface OpenElementOptions extends FrameworkOptions {",
-            "export function openElement(options: OpenElementOptions = {}): Plugin[] {"
-          ]
-        },
-        "./build-context": {
-          "sha256": "a77770942f8fd2e1ea5acf4b5e66545e9cf54373a2c312193f317dbe274c3bcf",
-          "publicDeclarations": [
-            "export type Phase = 1 | 2 | 3;",
-            "export class Phase1Meta {",
-            "export class Phase3Meta {",
-            "export class OpenElementBuildContext {"
-          ]
-        },
         "./cli/build": {
           "sha256": "19b817d8d114f0b107b7708675754de3fdc12c76c85c4dd3333814b6643894bd",
           "publicDeclarations": []
         },
-        "./cli/build-client": {
-          "sha256": "e4ec975531f3d39eef603901e5a034b89e86436ae042f6a40b8d3a344583d175",
-          "publicDeclarations": []
-        },
-        "./cli/build-ssg": {
-          "sha256": "10fdc527b3a19974af767a71516d5957475be84f551a57c635488cdbe16b937f",
-          "publicDeclarations": [
-            "export interface SsgEntryDescriptorInputs {",
-            "export function buildSsgEntryDescriptor("
-          ]
-        },
-        "./generated-data-resolver": {
-          "sha256": "d18395cfa3eca7cd72f2e5481b24a0e76d49284d717a9c08274c085adf80788c",
-          "publicDeclarations": [
-            "export const GENERATED_NAV_ID = '@openelement/generated/nav';",
-            "export const GENERATED_BLOG_DATA_ID = '@openelement/generated/blog-data';",
-            "export const GENERATED_I18N_ID = '@openelement/generated/i18n';",
-            "export type GeneratedDataResolverOptions = {",
-            "export function generatedDataPath(",
-            "export function createGeneratedDataResolverPlugin("
-          ]
-        },
-        "./head-injection": {
-          "sha256": "28dab8f1b72b612847e1a158869ad8afc8fe89a242684ffffb44997c022a66e0",
-          "publicDeclarations": [
-            "export function assertNoScriptTags(html: string, context: string): void {",
-            "export function validateSafeUrl(url: string, context: string): string {",
-            "export interface HeadExtrasResult {",
-            "export function buildHeadExtras(options: FrameworkOptions): HeadExtrasResult {"
-          ]
-        },
-        "./i18n-plugin": {
-          "sha256": "b24544efcdc71ff563a6a5ad4745bbfa3c3152a4694d42bdae2ec929a5f47cb3",
-          "publicDeclarations": [
-            "export function writeI18nDataModule(locales: string[], defaultLocale: string): string {",
-            "export function openI18n("
-          ]
-        },
         "./nitro-mount": {
           "sha256": "33056a4b4e9c291ea90532ad68268aaa9ad7be1a7f4897986847bd4e54926c47",
           "publicDeclarations": [
@@ -208,28 +144,6 @@
             "export function createOpenElementNitroHandler<"
           ]
         },
-        "./plugin": {
-          "sha256": "ce53992a9feb7490df8cf62a22cb97d53ffcf2842176010f79a1a3b2092e907a",
-          "publicDeclarations": [
-            "export function optionalPackageStubsPlugin(): Plugin {",
-            "export function createOpenPlugin("
-          ]
-        },
-        "./plugin-mdx": {
-          "sha256": "d935ba8f764d12bb95cacbe38e1d88ddb3c647560af5d293f0cccb84ecd85601",
-          "publicDeclarations": [
-            "export interface OpenMdxPluginOptions {",
-            "export function mdxPlugin(options: OpenMdxPluginOptions = {}): Plugin {"
-          ]
-        },
-        "./route-manifest": {
-          "sha256": "383a1fdf94c5df10b62fbbdcc3e9d021dfbab222e7c232c3358718d8a866a8f8",
-          "publicDeclarations": [
-            "export interface GenerateRouteManifestOptions {",
-            "export const routeManifest = {} as const;",
-            "export const routeManifest = {"
-          ]
-        },
         "./sitemap": {
           "sha256": "2c24151329624e9adde127f4762580ff3ac75fff4a66818fc83d7100d91a9135",
           "publicDeclarations": [

docs/release/v0.41.0-migration.md

@@ -0,0 +1,79 @@
+# Migrating to 0.41.0 from the 0.41 alpha line (and 0.40.x)
+
+This is the aggregate migration guide for the 0.41.0 stable release. It covers
+every breaking change since `0.40.x`, grouped by the version that shipped it.
+Versions not listed are non-breaking.
+
+## From 0.40.x (the eleven-package era)
+
+- The consumer graph is five packages: `@openelement/element`, `/app`,
+  `/adapter-vite`, `/create`, `/ui`. The retired packages (`@openelement/core`,
+  `signal`, `router`, `protocol`, `content`, `ssg`) are not supported imports;
+  their functionality moved into the five packages.
+- Author with `defineElement`, `definePage`, `defineApp` and build with
+  `buildApp()` (adapter-vite root). The plugin-style build entries are gone.
+- `defineLayout` was removed; layouts use `defineElement` with the same
+  definition object.
+- Distribution is npm-first (JSR is no longer a release channel).
+
+## alpha.17
+
+- Build-time helpers moved from the `@openelement/element` root to
+  `@openelement/element/build-utils` (`transformIslandSource`,
+  `createIsrCacheKey`, `formatJson`, `pathToTagName`, `normalizeSeparators`,
+  `SsrRenderError`, `createRuntimeAdapter`, runtime handler types). Update
+  imports: `from '@openelement/element'` → `from '@openelement/element/build-utils'`.
+- App root no longer exports router types (`RouteConfig`, `RouterInstance`,
+  `RouterMode`). Derive them from `SpaAppInstance` / `SpaAppOptions`.
+- Adapter-vite's `ExternalManifest` type and `SsgPageOutput.hydrationHints`
+  were removed.
+
+## alpha.18
+
+- Dead exports, fields and scripts were removed (element root build helpers,
+  island-manifest types, `openMdx` alias, unused ui `*TagName` re-exports).
+- `renderIntent.streaming` and `PageStreamingMode` were removed; delete the
+  option from page definitions (it was never implemented).
+- Dynamic-route render failures now fail the build by default. Opt out with
+  `SsgBehaviorOptions.dynamicRouteFailure: 'warn'` if a route is allowed to
+  fail loudly without stopping the build.
+
+## alpha.19
+
+- The element root no longer carries `export type *` seams; the public type
+  surface is an explicit export list. `SafeHtml`, `UnsafeHtml` and
+  `StyleSheetRule` are no longer exported from the root (their alpha.18
+  removal claim is now true).
+- Element internal subpaths `open-element-render` and `open-element-hydration`
+  were removed from exports. Tooling must not import them.
+- `renderDsdStream`/`createRenderDsdStreamMetrics`, `bindHydrateEvents` and
+  `generateHonoEntryCode` were removed as unused internals.
+- ui: the remaining `openDialogTagName`/`openDropdownTagName`/`openTabsTagName`
+  re-exports were removed; ui controls are squared
+  (`--btn-radius`/`--badge-radius`/`--ui-control-radius` changed from
+  `--radius-round` to `--radius-1`, 6px). If your CSS or screenshots assumed
+  pill-shaped buttons/badges, update them.
+
+## 0.41.0
+
+- Adapter-vite internal subpaths were pruned from exports: `app-vite`,
+  `build-context`, `head-injection`, `i18n-plugin`, `plugin`,
+  `generated-data-resolver`, `plugin-mdx`, `route-manifest`, `cli/build-client`,
+  `cli/build-ssg`. They had no consumer specifiers; the build pipeline imports
+  them relatively. Migrate to the supported entries: adapter-vite root
+  (`openElement`, `buildApp`), `nitro-mount`, `cli/build`, `sitemap`.
+- The interface freeze (ADR-0119): `defineElement`, `definePage`, `buildApp`,
+  the five-package graph, the supported subpaths and the static/SPA semantics
+  of `defineApp` are frozen. Post-freeze changes to that surface require a
+  major-version ADR — pin with confidence.
+
+## Verify after upgrading
+
+1. `deno install --frozen` and re-run your build; static output must render
+   identically (dynamic 500s now fail builds by default, see alpha.18).
+2. Grep for removed imports: `renderIntent.streaming`, `open-element-render`,
+   `open-element-hydration`, `app-vite`, `build-context`, `head-injection`,
+   `plugin-mdx`, `route-manifest`, `SafeHtml`, `UnsafeHtml`, `StyleSheetRule`,
+   `*TagName`.
+3. If you snapshot visual output, re-record baselines after the ui control
+   geometry change (alpha.19).

packages/adapter-vite/deno.json

@@ -3,19 +3,9 @@
   "version": "0.41.0-alpha.19",
   "exports": {
     ".": "./src/index.ts",
-    "./app-vite": "./src/app-vite.ts",
-    "./build-context": "./src/build-context.ts",
-    "./head-injection": "./src/head-injection.ts",
-    "./i18n-plugin": "./src/i18n-plugin.ts",
     "./nitro-mount": "./src/nitro-mount.ts",
-    "./plugin": "./src/plugin.ts",
-    "./generated-data-resolver": "./src/generated-data-resolver.ts",
-    "./plugin-mdx": "./src/plugin-mdx.ts",
-    "./route-manifest": "./src/route-manifest.ts",
     "./sitemap": "./src/sitemap.ts",
-    "./cli/build": "./src/cli/build.ts",
-    "./cli/build-client": "./src/cli/build-client.ts",
-    "./cli/build-ssg": "./src/cli/build-ssg.ts"
+    "./cli/build": "./src/cli/build.ts"
   },
   "imports": {
     "@mdx-js/rollup": "npm:@mdx-js/rollup@^3.1.1",

packages/adapter-vite/src/generated-export-files.ts

@@ -4,18 +4,8 @@
 export const OPENELEMENT_EXPORT_FILES: Record<string, Record<string, string>> = {
   'adapter-vite': {
     '.': 'src/index.ts',
-    'app-vite': 'src/app-vite.ts',
-    'build-context': 'src/build-context.ts',
     'cli/build': 'src/cli/build.ts',
-    'cli/build-client': 'src/cli/build-client.ts',
-    'cli/build-ssg': 'src/cli/build-ssg.ts',
-    'generated-data-resolver': 'src/generated-data-resolver.ts',
-    'head-injection': 'src/head-injection.ts',
-    'i18n-plugin': 'src/i18n-plugin.ts',
     'nitro-mount': 'src/nitro-mount.ts',
-    'plugin': 'src/plugin.ts',
-    'plugin-mdx': 'src/plugin-mdx.ts',
-    'route-manifest': 'src/route-manifest.ts',
     'sitemap': 'src/sitemap.ts',
   },
   'app': {

tools/check-www-current-truth.ts

@@ -66,7 +66,11 @@ if (await exists('www/content/guide')) {
 
 async function checkFile(file: string): Promise<void> {
   const text = await Deno.readTextFile(file);
+  // Version-dense history surfaces (the migration guide, changelog) may name
+  // retired prereleases without it being a stale current claim.
+  const isHistorySurface = /(?:routes\/guide\/migration\.tsx|CHANGELOG\.md)$/.test(file);
   for (const { name, re } of forbidden) {
+    if (isHistorySurface && name === 'retired prerelease current claim') continue;
     if (re.test(text)) issues.push({ file, text: name });
   }
   if (
@@ -120,9 +124,16 @@ await checkFile('www/vite.config.ts');
 if (Deno.args.includes('--artifacts')) {
   for await (const file of walk('www/dist', { skip: ['blog'] })) {
     // The root-level history indexes (blog.html, changelog.html or their
-    // /blog//changelog route index.html) hold historical copy that is
-    // intentionally outside the current-surface rule.
-    if (/(?:^|\/)(?:blog|changelog)(?:\.html|\/index\.html)$/.test(file)) continue;
+    // /blog//changelog route index.html) and the version-dense migration
+    // guide hold historical copy that is intentionally outside the
+    // current-surface rule.
+    if (
+      /(?:^|\/)(?:(?:blog|changelog)(?:\.html|\/index\.html)|guide\/migration\/index\.html)$/.test(
+        file,
+      )
+    ) {
+      continue;
+    }
     if (/\.html$/.test(file)) await checkFile(file);
   }
 }

www/app/data/_generated-nav.ts

@@ -170,6 +170,11 @@ export const navSections = [
         "label": "Configuration",
         "order": 70
       },
+      {
+        "path": "/guide/migration",
+        "label": "Migration",
+        "order": 75
+      },
       {
         "path": "/guide/error-handling",
         "label": "Error Handling",

www/app/routes/blog/index.tsx

@@ -220,7 +220,11 @@ routeSheet.replaceSync(`
   }
 `);
 
-const visiblePosts = posts.filter((post) => post.frontmatter.type !== 'adr');
+// The dispatch index leads with the newest story: sort by frontmatter date
+// descending before picking featured and rows.
+const visiblePosts = posts
+  .filter((post) => post.frontmatter.type !== 'adr')
+  .sort((a, b) => b.frontmatter.date.localeCompare(a.frontmatter.date));
 
 function postTags(post: typeof posts[number]): string[] {
   return post.frontmatter.tags ?? [];

www/app/routes/guide/configuration.tsx

@@ -27,7 +27,7 @@ const content: Record<'en' | 'zh', GuideContent> = {
       { id: 'package-config', label: 'Package config', level: 3 },
     ],
     previous: { href: '/guide/api', label: 'API Routes' },
-    next: { href: '/guide/error-handling', label: 'Error Handling' },
+    next: { href: '/guide/migration', label: 'Migration' },
     cards: [
       {
         id: 'route-config',
@@ -56,7 +56,7 @@ const content: Record<'en' | 'zh', GuideContent> = {
       { id: 'package-config', label: 'Package 配置', level: 3 },
     ],
     previous: { href: '/guide/api', label: 'API 路由' },
-    next: { href: '/guide/error-handling', label: '错误处理' },
+    next: { href: '/guide/migration', label: '迁移' },
     cards: [
       {
         id: 'route-config',

www/app/routes/guide/error-handling.tsx

@@ -26,7 +26,7 @@ const content: Record<'en' | 'zh', GuideContent> = {
       { id: 'component-errors', label: 'Component errors', level: 3 },
       { id: 'build-errors', label: 'Build errors', level: 3 },
     ],
-    previous: { href: '/guide/configuration', label: 'Configuration' },
+    previous: { href: '/guide/migration', label: 'Migration' },
     next: { href: '/guide/islands-and-ssr', label: 'Islands and SSR' },
     cards: [
       {
@@ -55,7 +55,7 @@ const content: Record<'en' | 'zh', GuideContent> = {
       { id: 'component-errors', label: '组件错误', level: 3 },
       { id: 'build-errors', label: '构建错误', level: 3 },
     ],
-    previous: { href: '/guide/configuration', label: '配置' },
+    previous: { href: '/guide/migration', label: '迁移' },
     next: { href: '/guide/islands-and-ssr', label: 'Islands 与 SSR' },
     cards: [
       {