chore(release): v1.0.0-alpha.3 version bump, state-machine admission, changelog (#1428)

* chore(release): v1.0.0-alpha.3 version bump, state-machine admission, changelog

Four packages move to 1.0.0-alpha.3 in lockstep through the W6 knob rather
than by hand — the tool this train added because hand-editing the six points
burned two alpha.2 release rounds.

Six points, all moved by the knob (#1415):
- 4x package deno.json version
- packages/create/src/version.ts CREATE_VERSION
- the 4 fixture deno.lock workspace links, regenerated by fixtures:locks:update

The knob's own task registration went missing: W6 registered
`version-bump` in tools/repo/deno.json, and the alpha3 consolidation merge
that carried version-bump.ts and version-bump.test.ts into dev dropped the
task entry (verified: git diff b133f3e origin/dev -- tools/repo/deno.json
removes exactly that line; the 39-task set of b133f3e has 39 keys and the
merged file has 38). `deno task --cwd tools/repo version-bump` exited 1 with
"Task not found" on dev. Restored verbatim from b133f3e — the script the
suite already tests is now reachable as the task its usage text advertises.

State-machine admission (the sanctioned act, not a quiet JSON edit):
ADMITTED_ACTIVE_TARGET advances to 'v1.0.0-alpha.3', and the pinned
ReleaseStateV3 fixture in check-release-state-machine.test.ts follows
(sourceVersion/activeTarget/packages map). release-state.json advances
sourceVersion + activeTarget only — the registry block, verifiedAt and
latestPrerelease keep recording registry truth (1.0.0-alpha.2 complete under
@Alpha), because publication is a separate gated step and the post-publish
sync owns that block.

Also synced to the source line: README.md / README.zh.md ("the source tree
is 1.0.0-alpha.3"), www/app/data/version.ts OPENELEMENT_VERSION, and the
registry-truth constants there (LATEST_PRERELEASE_VERSION and
PUBLISHED_PACKAGE_VERSIONS) to alpha.2, which is what @Alpha actually
resolves to. packages/ui/src/generated-manifest.json, regenerated by
generate:all, carries the new version.

CHANGELOG gains the 1.0.0-alpha.3 section: W1 config + starter facade, W2
npm facade, W3 error experience, W4 docs pipeline, W6 legacy cleanup, W7
bundle and update cost. Two entries record what did NOT land, with the
measurements, rather than restating the goals: swap1k is not single-digit
(the afterframe protocol floor measures ~13-15 ms against a ~2.3-2.7 ms
moveEntries walk, and moveEntries stays byte-identical by ruling), and the
packed-starter browser matrix runs behind OPEN_ELEMENT_SKIP_BROWSER_MATRIX=1
while #1425 is open.

Verified in .work/alpha3/version:
- deno task --cwd tools/repo version-bump 1.0.0-alpha.3        -> dry run:
  5 files + 4 locks, exit 0
- deno task --cwd tools/repo version-bump 1.0.0-alpha.3 --write -> "six
  points consistent at 1.0.0-alpha.3", exit 0
- deno task --cwd tools/repo fixtures:locks:check             -> pass (6)
- deno task --cwd tools/repo release:state-machine:check      -> pass
  (offline); release:registry-check (live npm) -> pass
- deno task check                                             -> gate ok, 4 steps
- deno task --cwd tools/release graph:check                   -> pass, 4
  packages at 1.0.0-alpha.3
- deno test tools/repo/                                       -> 201 passed,
  0 failed (after the CHANGELOG broad-flag line was reworded: the
  no-allow-all tripwire scans tracked prose and initially caught it)
- deno test packages/element/__tests__/                       -> 366 passed
- deno test packages/router/__tests__/                        -> 779 passed
- deno test packages/create/__tests__/cli.test.ts             -> 22 passed
- deno task --cwd tests/e2e/starter-smoke gate                -> 36 passed
  (chromium/firefox/webkit), gate ok 2 steps
- deno task --cwd tools/repo generate:all                     -> 9 generators ok
- www#check:content-data, check:errors, check:error-codes,
  check:install-command, check:api-reference, check:content,
  retired-api:check, interface:snapshot, deno-api:check        -> pass

Not run / not passing here: www#check:content-dates fails by design before
the content commit exists — the manifest records per-article git dates, so
it is regenerated in the commit that follows this one. deno test
www/__tests__/v0.27.0-regression.test.ts fails 8/12 in this worktree and
identically on a pristine e7c405f checkout (missing www/dist, which the
file's own header names as a prerequisite); it is not related to this change.

* chore(www): regenerate the stale content-dates manifest (#1414)

The manifest records each article's last-commit date (`git log --follow
--format=%cs` per source file), so it must be written after the content
change exists — writing it earlier records `uncommitted` or a stale date
(the #1405 ordering trap).

It was already stale on `dev`, not only behind this train: the alpha3
consolidation merge (de8c9c2, 2026-09-22) touched six guide and
architecture articles, while the tracked manifest still recorded 2026-09-21
for them. So `deno task --cwd tools/repo gate:source` fails at
`www#check:content-dates` on an unmodified dev checkout, and this commit is
what repairs it.

Six articles move to 2026-09-22 (comparison, core-concepts, error-handling,
getting-started, routing-and-data, tutorial); every untouched date is
unchanged.

Verified: `deno task --cwd www write:content-dates` then
`deno task --cwd www check:content-dates` -> passed (22 articles).

Author: SisyphusZheng

CHANGELOG.md

@@ -9,6 +9,120 @@ lives in:
 - [`docs/release/release-state.json`](./docs/release/release-state.json)
 - [`docs/release/public-interface-snapshot.json`](./docs/release/public-interface-snapshot.json)
 
+## 1.0.0-alpha.3
+
+**Door-handle train: the surfaces a consumer actually touches — the config
+file, the packed npm facade, the error vocabulary, the documentation
+pipeline, and the shipped bundle — are converged and gated.** The source
+line is `1.0.0-alpha.3`; npm publication is a separate, gated step, so
+`docs/release/release-state.json` keeps its registry block at the alpha.2
+truth until the post-publish sync. **No migration steps**: the config file is
+an optional overlay and nothing here is a breaking change, so an alpha.2
+consumer upgrades with no action.
+
+- **Element, Router — framework options get one home (#1411)**:
+  `openelement.config.ts` is optional and near-empty; with an empty object
+  every option comes from a file convention — design tokens from
+  `app/styles/tokens.css`, the application shell from
+  `app/islands/app-shell.tsx`, site title from `package.json`. A non-empty
+  config file next to inline `openElement(...)` options is a hard error
+  ("framework options have two homes"), and an unknown or wrong-typed key
+  throws with the accepted-key list; there is no silent merging. The starter
+  template's `vite.config.ts` is now `plugins: [...openElement()]` with zero
+  CSS strings, `<app-shell>` is registered by convention and stays
+  deletable, favicon and og tags reach the built document, and the first
+  `deno task dev` run no longer prints the production CORS advisory. The
+  documented consumer scaffold command is the short all-permissions form the
+  owner ruled on 2026-09-21 (the full command, with its concrete dist-tag,
+  lives in the create README and the getting-started guide), admitted as an
+  exact path-and-line exemption in the `check-no-allow-all` tripwire while
+  every first-party invocation stays scoped.
+- **Release — packed npm facade (#1412)**: per-package `keywords`, `engines`
+  (node `>=24`; deno `>=2.9` on the two Deno-driven toolchains) and
+  `sideEffects` (`false` for element/router/ui, `['./src/cli.js']` for
+  create) are written from one source and re-read from the real tarball
+  bytes by the new `pack-surface:check` gate, which also fails closed on a
+  repository path or ADR citation in shipped text, on an export subpath the
+  shipped README never names, and on a module-scope global write in a
+  package declared `sideEffects: false`. Every Element facade subpath is
+  documented in the package README — the eight that existed when this landed,
+  plus `client-only` below; 54 shipped files lost their
+  repository-internal references; the create README states the current "do
+  not run the bin under npx" limitation (the Node entry is tracked by
+  #1387).
+- **Element, Router — error experience (#1413)**: the compiler hands the
+  build a structured diagnostic (`{id, loc, frame, message, diagnostics}`)
+  instead of a pre-joined display string, so an overlay can underline the
+  authored line and a consumer can read the location without parsing the
+  message apart. The three user-facing runtime failures name the compiled
+  module, the tag and the authored `this.<property>` instead of an index the
+  author cannot map back; router authoring throws carry stable codes with
+  phase and severity plus the remediation sentence they were missing; the
+  `start` CLI prints one actionable line built from the message and cause
+  chain, with `--debug` expanding the full stack. `/errors` is a derived
+  artifact — every `fail(…, 'OEC9xxx', …)` literal plus the element error
+  protocol and router code maps — and **38 codes** render per locale from
+  the source that raises them; a hand-written list fails `check:errors`.
+- **Docs — pipeline before content (#1414)**: five pipeline pieces landed
+  first, so the facts are rendered rather than retyped. The API reference
+  renders each export's declared signature and its option-bag members; an
+  undocumented public export is red, and all **51 empty summaries are now
+  documented at their declarations**; the config option table is generated
+  from the application options type; `/errors` is generated from the
+  definitions; and the install command has one owner
+  (`packages/create/src/install-command.ts`) which the site interpolates and
+  `starter-smoke` asserts against the packed CLI's own output. Content
+  followed the pipeline: the routing-and-data Metadata and Data boundary
+  sections are written out, `delegatesFocus`/`formAssociated`/`converter`
+  are documented on core-concepts, and getting-started's Build section is
+  user-facing.
+- **Repo — legacy cleanup (#1415)**: `deno task version-bump <version>` owns
+  all six version points — 4× package `deno.json`, `CREATE_VERSION`, and the
+  four fixture `deno.lock` files — with a dry run by default and `--write`
+  applying the edits, regenerating the locks, and then failing closed unless
+  all six agree; hand-editing them burned two alpha.2 release rounds. A
+  `workflow_run` companion re-runs the FAILED jobs of AutoFlow CI exactly
+  once (attempt 1 only), because webkit fails deterministically per runner
+  and only a fresh machine can change the outcome (#1409). A
+  workspace-alias-hijack guard refuses to alias `@openelement/*` onto a
+  checkout's sources when an app is scaffolded inside a framework clone — a
+  build that would otherwise report success while resolving a different
+  framework version (#1371 family). The `evidence/` directory (0.43.3
+  tarballs) is gone and its ignore rule is documented as staying; the
+  per-fixture Nitro rules collapsed to `**/.output*|.wrangler|.nitro`; and
+  the ten fixture and e2e directories that had no README have one.
+- **Element — bundle and update cost (#1416)**: `@openelement/element/client-only`
+  is a fresh-DOM entry without the existing-DOM claim executor, and the
+  Router selects it only when no island on a page can hydrate server DOM
+  (an island that says nothing keeps the full entry, because guessing the
+  other way breaks hydration). Measured on the JFB keyed-table harness:
+  **77,557 B → 68,630 B, −8,927 B (−11.5%)**, with the claim diagnostic
+  strings at grep count 0 in the final bundle. Keyed updates also skip the
+  slot walk when an entry's item reference is unchanged, turn the
+  created-entry lookup into a Set, and resolve the fallback insertion
+  reference on demand: instrumented on `05_swap1k`, `updateItemValues`
+  calls drop from **1000 to 0** per swap and the synchronous segment from
+  3.0 ms to 2.7 ms median (−10%, 480 samples).
+- **Honest measurement — the swap1k target was not met**: swap1k did **not**
+  reach single digits, and this section records why rather than restating the
+  goal. On the same runs the afterframe protocol floor (one
+  `requestAnimationFrame` plus one `MessageChannel` task with no DOM work at
+  all) measured **~13–15 ms** — 15.2 ms baseline against 14.5 ms with the
+  change, and ~12.8 ms median in the separately documented floor
+  measurement — while `moveEntries`' 997 real `insertBefore` calls cost
+  ~2.3–2.7 ms. `moveEntries` is unchanged byte for byte (Svelte's algorithm,
+  ruled out of scope for this train), so the reported total contains the
+  protocol floor plus that walk. The reactive boundary this exposes is
+  documented in both locales on core-concepts: mutating an item in place is
+  outside the contract — the same reference comparison a `signal()` holding
+  an object draws — and the supported shape is a new item or a new array.
+- **Tracked, not fixed**: the packed-starter browser matrix runs behind
+  `OPEN_ELEMENT_SKIP_BROWSER_MATRIX=1` (#1425). It fails 3/3 browsers with a
+  `waitForFunction` timeout in the consumer harness while the identical
+  probe against a manually scaffolded packed starter passes all three
+  browsers. The rest of packed qualification stays required; the guard is to
+  be deleted when the investigation closes, not carried forward.
+
 ## 1.0.0-alpha.2
 
 **Constitutional-enforcement train: the alpha.1 review's fail-closed and

README.md

@@ -5,7 +5,7 @@ English | [简体中文](./README.zh.md)
 OpenElement is a Web Platform-first core for two products: **Element** and **Router**.
 Element compiles JSX-authored Custom Elements into a Part Program used by server serialization, fresh DOM, and existing-DOM claim. Router owns route selection, HTTP semantics, navigation, loaders, actions, and the shared Native/Lit Framework Mode application contract.
 
-The source tree is `1.0.0-alpha.1`, a new public baseline for Element and Router. It is not a compatibility migration from historic 0.x snapshots. npm `latest` is per package: element, create, and ui remain on the 0.43 stable line, while Router's `latest` is the 0.41.0-alpha.6 prerelease. No single version is published for all four packages until a separately admitted release.
+The source tree is `1.0.0-alpha.3`, a new public baseline for Element and Router. It is not a compatibility migration from historic 0.x snapshots. npm `latest` is per package: element, create, and ui remain on the 0.43 stable line, while Router's `latest` is the 0.41.0-alpha.6 prerelease. No single version is published for all four packages until a separately admitted release.
 
 ## Quick Start
 

README.zh.md

@@ -5,7 +5,7 @@
 OpenElement 是一个 Web Platform 优先、只围绕两个核心产品构建的仓库：**Element** 与 **Router**。
 Element 将 JSX 编写的 Custom Element 编译为 Part Program，并统一用于服务端序列化、创建新 DOM 与复用现有 DOM。Router 负责路由选择、HTTP 语义、导航、loader/action，以及 Native 与 Lit Framework Mode 共享的应用协议。
 
-源码目前是 Element 与 Router 的全新公开基线 `1.0.0-alpha.1`。它不是从历史 0.x API 到 1.x 的兼容迁移。npm `latest` 是按包独立的：element、create、ui 继续指向 0.43 稳定线，而 Router 的 `latest` 是 0.41.0-alpha.6 预发布。在单独准入发布之前，没有任何单一版本同时覆盖全部四个包。
+源码目前是 Element 与 Router 的全新公开基线 `1.0.0-alpha.3`。它不是从历史 0.x API 到 1.x 的兼容迁移。npm `latest` 是按包独立的：element、create、ui 继续指向 0.43 稳定线，而 Router 的 `latest` 是 0.41.0-alpha.6 预发布。在单独准入发布之前，没有任何单一版本同时覆盖全部四个包。
 
 ## 快速开始
 

docs/release/release-state.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 3,
-  "sourceVersion": "1.0.0-alpha.2",
-  "activeTarget": "v1.0.0-alpha.2",
+  "sourceVersion": "1.0.0-alpha.3",
+  "activeTarget": "v1.0.0-alpha.3",
   "nextPlannedTrain": "not scheduled",
   "maturity": "alpha",
   "registry": {

packages/create/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@openelement/create",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.3",
   "exports": {
     ".": "./src/cli.ts",
     "./install-command": "./src/install-command.ts"

packages/create/src/version.ts

@@ -1,5 +1,5 @@
 /** The published CLI version, embedded so packed npm installs are self-contained. */
-export const CREATE_VERSION = '1.0.0-alpha.2';
+export const CREATE_VERSION = '1.0.0-alpha.3';
 
 /**
  * The Vite dev release stamped into the generated starter's import map and

packages/element/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@openelement/element",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.3",
   "exports": {
     ".": "./src/index.ts",
     "./jsx-runtime": "./src/jsx-runtime.ts",

packages/router/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@openelement/router",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.3",
   "exports": {
     ".": "./src/index.ts",
     "./http": "./src/http.ts",

packages/ui/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@openelement/ui",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.3",
   "exports": {
     ".": "./src/index.ts",
     "./open-button": "./src/open-button.tsx",

packages/ui/src/generated-manifest.json

@@ -2,7 +2,7 @@
   "$comment": "GENERATED FILE - do not edit. Regenerate with: deno task generate:ui-manifest (drift gate: ui-manifest:check).",
   "schemaVersion": "1.0.0",
   "packageName": "@openelement/ui",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.3",
   "description": "Open Props Web Component library for openElement",
   "author": "openElement",
   "license": "MIT",