Merge pull request #508 from open-element/dev

release: v0.41.0-alpha.19 (ADR-0118 third audit cleanup sweep)

Author: SisyphusZheng

.gitignore

@@ -3,8 +3,6 @@ node_modules/
 
 # Deno
 .deno/
-.deno-cache/
-.deno_cache/
 vendor/*
 # Keep vendored dependency attribution tracked for license compliance
 !vendor/jsr.io/
@@ -23,13 +21,10 @@ dist/
 custom-dist/
 dist-test-*/
 www/dist/
-npm/
 packages/adapter-vite/__fixtures__/nitro-proof/.output-*/
 packages/adapter-vite/__fixtures__/nitro-proof/.wrangler/
 packages/adapter-vite/__fixtures__/nitro-proof/.nitro/
 packages/adapter-vite/__fixtures__/nitro-proof/node_modules/
-*.tsbuildinfo
-.tsbuildinfo
 www/app/data/_generated-blog-data.ts
 .openElement/
 www/.openElement/
@@ -73,7 +68,6 @@ test-results/
 .gstack/
 .qoder/
 .codebuddy/settings.local.json
-docs/autoflow/cells/*/state.json
 
 # Vite cache
 .vite/
@@ -82,27 +76,9 @@ docs/autoflow/cells/*/state.json
 # Generated www data modules and the UI manifest are intentionally tracked.
 # repo:hygiene fails if a tracked file also matches .gitignore.
 
-# Test / build / lint / coverage output files
-test-*.txt
-cov-*.txt
-ui-test*.txt
-lint-*.txt
-coverage-*.txt
-coverage-output.txt
-.git-commit-msg.txt
-docs/vite-build-*.txt
-
 # Root-level logo source files (design originals, keep local)
 /open-logo*.svg
 /open-favicon.svg
 
-debug.log
 hub-index/
 hub-submission.json
-lighthouse-result*.json
-
-# Root-level audit artifact
-/audit-ast.json
-
-# Vite virtual assets
-assets/_virtual_*

CHANGELOG.md

@@ -28,9 +28,9 @@ evidence.
 - Adds WebKit smoke to CI, gates examples checks, single-sources the
   guide with real Chinese rendering, and covers the SPA action chain in a
   real browser.
-- Removes dead exports, fields and scripts (breaking; see the release
-  note for migration), removes `renderIntent.streaming`, converges
-  fmt/lint exclusions, and retires stale files and config entries.
+- Removes dead exports, fields and scripts (breaking; see the GitHub
+  prerelease notes for migration), removes `renderIntent.streaming`,
+  converges fmt/lint exclusions, and retires stale files and config entries.
 
 ## 0.41.0-alpha.17
 

README.md

@@ -7,7 +7,7 @@ Elements are the durable application contract; JSX and Basic Element are the
 authoring layer; Declarative Shadow DOM is the default server representation;
 interactive regions upgrade selectively.
 
-Published package line: `0.41.0-alpha.18` (`v0.41.0-alpha.18`). This release
+Published package line: `0.41.0-alpha.19` (`v0.41.0-alpha.19`). This release
 keeps the project in alpha while the five-package product and external adoption
 evidence continue to mature; the abandoned beta naming is not an active line.
 
@@ -51,11 +51,11 @@ external adoption. It is not presented as an already-achieved market claim.
 
 ## Current release state
 
-The five-package convergence is published as `0.41.0-alpha.18`. npm beta.1
+The five-package convergence is published as `0.41.0-alpha.19`. npm beta.1
 through beta.3 remain withdrawn partial artifacts and are not compatibility
 baselines. External adopter pilot #390 remains the primary repository-external
-condition before the project can make a stability commitment. Alpha.18 is the
-active second audit sweep (see
+condition before the project can make a stability commitment. Alpha.18
+completed the second audit sweep (see
 [ADR-0117](./docs/adr/ADR-0117-second-audit-round-alpha18-sweep.md)).
 
 Stable `0.41.0` is released only when alpha releases need no more architecture,

README.zh.md

@@ -6,7 +6,7 @@
 Elements 是可长期保存的应用组件模型；JSX 与 Basic Element 是作者层；
 Declarative Shadow DOM 是默认服务端表示；交互区域按需升级。
 
-已发布包线为 `0.41.0-alpha.18`（`v0.41.0-alpha.18`）。项目继续使用 alpha
+已发布包线为 `0.41.0-alpha.19`（`v0.41.0-alpha.19`）。项目继续使用 alpha
 命名，直到五包产品与外部采用证据充分成熟；已放弃的 beta 命名不再是当前版本线。
 
 ## 当前产品
@@ -41,9 +41,9 @@ official build path = Vite + Nitro
 
 ## 当前发布状态
 
-五包收敛已作为 `0.41.0-alpha.18` 发布。npm beta.1 至 beta.3 仍是已撤回的
+五包收敛已作为 `0.41.0-alpha.19` 发布。npm beta.1 至 beta.3 仍是已撤回的
 不完整历史产物，不构成兼容基线。外部 adopter pilot #390 仍是作出稳定性承诺前
-最重要的仓库外条件。Alpha.18 是当前第二轮审计清扫版本（ADR-0117）。
+最重要的仓库外条件。Alpha.18 已完成第二轮审计清扫（ADR-0117）。
 
 只有后续 alpha 不再需要架构、公开接口或采用工作时，才发布 stable `0.41.0`。
 request-time data、forms、sessions 与 cache 仍是后续产品工作；当前承诺是具有

SECURITY.md

@@ -9,7 +9,7 @@ update within ten business days. Please include affected package and version,
 reproduction steps, impact, and any proposed mitigation. We coordinate a fix,
 credit reporters when requested, and publish an advisory when users need to act.
 
-Only the latest published `0.41.x` line is supported while alpha.7 is active.
+Only the latest published release on the current alpha line is supported.
 Pre-release packages may change before stable release; security fixes are made
 on the active release line whenever practical.
 

deno.json

@@ -37,7 +37,6 @@
     "dev": "cd www && deno run --allow-read --allow-write --allow-net --allow-env --allow-ffi --allow-sys npm:vite --config vite.config.ts",
     "build": "deno task generate:ui-manifest && (cd www && deno run --config ../deno.json --allow-read --allow-write --allow-net --allow-env --allow-ffi --allow-sys --allow-run ../packages/adapter-vite/src/cli/build.ts) && deno task www:check-artifact-truth",
     "preview": "cd www && deno run --allow-read --allow-write --allow-net --allow-env --allow-ffi npm:vite preview --config vite.config.ts",
-    "build:docs": "deno task build",
     "workflow:check": "deno run --allow-read --allow-run=git tools/check-project-workflow.ts",
     "workflow:check-slimming": "deno run --allow-read tools/check-workflow-slimming.ts",
     "actions:check-pins": "deno run --allow-read --allow-env tools/check-action-pins.ts",
@@ -64,7 +63,6 @@
     "consumer:local": "deno run --allow-read --allow-write --allow-run --allow-env --allow-net tools/consumer-local.ts",
     "consumer:packaged": "deno task pack:dry-run && deno run --allow-read --allow-write --allow-run --allow-env --allow-net tools/consumer-packaged-starter.ts && deno run --allow-read --allow-write --allow-run --allow-env --allow-net tools/consumer-local.ts --packaged-import-map-check",
     "third-party-wc:smoke": "deno run --allow-read --allow-write --allow-run --allow-env --allow-net --allow-sys tools/third-party-wc-smoke.ts",
-    "desktop-reader:smoke": "cd examples/deno-desktop-reader && deno test -A app/__tests__/",
     "examples:check": "cd examples/deno-desktop-reader && deno task check && deno task smoke && cd ../deno-desktop-mastodon && deno task check && deno task smoke",
     "stress:dogfood": "deno run --allow-read --allow-run --allow-env tools/run-dogfood-stress.ts",
     "dogfood:evidence": "deno run --allow-read --allow-write --allow-run tools/run-dogfood-evidence.ts",
@@ -84,8 +82,8 @@
     "test:visual-baselines": "OPEN_VISUAL_REGRESSION=1 deno run -A npm:@playwright/test@1.59.1 test www/e2e/visual-baselines.spec.ts --config www/e2e/playwright.config.ts --project=chromium",
     "test:e2e:browsers": "deno run -A npm:@playwright/test@1.59.1 test --config www/e2e/playwright.config.ts",
     "test:e2e:install": "deno run -A npm:playwright@1.59.1 install chromium",
-    "test:e2e:firefox-smoke": "deno run -A npm:@playwright/test@1.59.1 test --config www/e2e/playwright.config.ts --project=firefox --grep \"DSD Layers|Layout Island Shell|Island Script Loading|Theme Toggle|Theme initialization|data-signal bindings|SSR/hydration mismatch degradation|router guards on browser history traversal\"",
-    "test:e2e:webkit-smoke": "deno run -A npm:@playwright/test@1.59.1 test --config www/e2e/playwright.config.ts --project=webkit --grep \"DSD Layers|Layout Island Shell|Island Script Loading|Theme Toggle|Theme initialization|data-signal bindings|SSR/hydration mismatch degradation|router guards on browser history traversal\"",
+    "test:e2e:firefox-smoke": "deno run -A npm:@playwright/test@1.59.1 test --config www/e2e/playwright.config.ts --project=firefox --grep \"DSD Layers|Layout Island Shell|Island Script Loading|Theme Toggle|Theme initialization|data-signal bindings|SSR/hydration mismatch degradation|router guards on browser history traversal|reflect: true static props\"",
+    "test:e2e:webkit-smoke": "deno run -A npm:@playwright/test@1.59.1 test --config www/e2e/playwright.config.ts --project=webkit --grep \"DSD Layers|Layout Island Shell|Island Script Loading|Theme Toggle|Theme initialization|data-signal bindings|SSR/hydration mismatch degradation|router guards on browser history traversal|reflect: true static props\"",
     "test:e2e:browsers:install": "deno run -A npm:playwright@1.59.1 install chromium firefox webkit",
     "nitro:proof:node": "deno run --allow-read --allow-write --allow-run --allow-env --allow-net tools/nitro-proof.ts node",
     "nitro:proof:workers": "deno run --allow-read --allow-write --allow-run --allow-env --allow-net tools/nitro-proof.ts workers",
@@ -96,14 +94,13 @@
     "lint": "deno lint",
     "fmt": "deno fmt",
     "fmt:check": "deno fmt --check",
-    "clean": "rm -rf packages/*/dist www/dist packages/*/*.tgz",
+    "clean": "rm -rf packages/*/dist www/dist packages/*/*.tgz dist custom-dist dist-test-* playwright-report test-results .openElement www/.openElement",
     "hooks:install": "git config core.hooksPath .githooks",
     "hooks:uninstall": "git config core.hooksPath",
     "autoflow:dev": "deno run --allow-read --allow-run --allow-env tools/autoflow/mod3.ts dev",
     "autoflow:push": "deno run --allow-read --allow-run --allow-env tools/autoflow/mod3.ts push",
     "autoflow:ci": "deno run --allow-read --allow-run --allow-env tools/autoflow/mod3.ts ci",
     "autoflow:patch-release": "deno run --allow-read --allow-write --allow-run --allow-env tools/autoflow/mod3.ts patch-release",
-    "autoflow:minor-plan": "deno run --allow-read --allow-run tools/autoflow/mod3.ts minor-plan",
     "autoflow:release": "deno run --allow-read --allow-write --allow-run --allow-env tools/autoflow/mod3.ts release",
     "autoflow:release-dispatch": "deno run --allow-read --allow-write --allow-run --allow-env tools/autoflow/mod3.ts release-dispatch",
     "autoflow:release-prepare": "deno run --allow-read --allow-write --allow-run --allow-env tools/autoflow/mod3.ts release-prepare",
@@ -122,7 +119,6 @@
     "exclude": [
       "www/content/blog/",
       "www/app/data/",
-      "www/design/mockups/",
       "www/public/assets/",
       "custom-dist/",
       "dist-test-ssg-render/",
@@ -157,7 +153,6 @@
     "**/dist/**",
     "**/node_modules/**",
     ".deno",
-    ".deno_cache",
     "custom-dist",
     "dist-test-ssg-render",
     "vendor",

docs/adr/ADR-0118-third-audit-round-alpha19-cleanup-sweep.md

@@ -0,0 +1,46 @@
+# ADR-0118: Third Audit Round and Alpha.19 Cleanup Sweep
+
+- Status: ACCEPTED
+- Date: 2026-07-25
+
+## Context
+
+A third full-repository audit on 2026-07-25 (after alpha.18 shipped) reviewed
+architecture, redundancy and cleanliness across all five packages, the tooling
+layer, the docs site and the governance documents. It produced 26 issues
+(#481–#506), all accepted into milestone `v0.41.0-alpha.19`: three
+high-severity, twenty medium/low-severity findings grouped around correctness
+residuals, surface drift, gate blind spots and hygiene.
+
+The audit's meta-finding is an evolution of the alpha.17/18 sibling-path
+pattern: several alpha.18 fixes are correct on every path they touched but
+break on **combinations** of inputs — for example the reflect short-circuit
+misbehaves only when `removeAttribute` meets a default value, and the `For`
+drift token breaks only when content collides with the separator. Where the
+second round taught us to enumerate sibling paths, the third round teaches
+that acceptance for state-dependent fixes must enumerate input combinations,
+not just code paths.
+
+## Decision
+
+- Cut `v0.41.0-alpha.19` as a pure cleanup sweep governed by issues
+  #481–#506. It adds no new product surface and no new packages.
+- Every state-dependent fix ships with a "input combinations enumerated"
+  acceptance note, extending the sibling-path doctrine from ADR-0117.
+- Gate blind spots found by the audit (www bare version mentions, governance
+  doc bodies, export-star seams, assertion style) are mechanized so the same
+  class of drift cannot return silently.
+- Confirmed dead code, dead config entries and stale comments are deleted
+  with zero-consumer evidence recorded in each issue.
+
+## Consequences
+
+Positive: the audit's combination-path meta-finding becomes an enforceable
+acceptance rule; governance and surface drift gains mechanical coverage; the
+cleanup lowers maintenance surface before the `0.41.0` freeze decision.
+
+Negative: the alpha line lengthens once more; some deletions remain breaking
+surface changes requiring release-note migration notes.
+
+Neutral: ADR-0116 and ADR-0117 remain the parent decisions; this ADR records
+the third audit round as a continuation of the same doctrine.

docs/current/HYDRATION_CONTRACT.md

@@ -2,12 +2,10 @@
 
 The v0.41 alpha line exposes one supported component runtime:
 `@openelement/element`. Hydration internals are not application-authoring
-surface: the implementation modules remain importable as internal subpaths
-(`@openelement/element/open-element-render` and
-`@openelement/element/open-element-hydration`) for build tooling and Deno
-type generation, but they carry no compatibility promise and application code
-must not import them. Build-time helpers for adapters live behind
-`@openelement/element/build-utils`.
+surface: the `open-element-render` and `open-element-hydration` implementation
+modules are internal-only — their package subpath exports were removed in
+alpha.19 and application or tooling code must not import them. Build-time
+helpers for adapters live behind `@openelement/element/build-utils`.
 
 ## Supported imports
 
@@ -40,3 +38,12 @@ static, hydrate, or CSR implementation packages.
   `/@fs/` absolute-path specifier convention. That branch is covered by unit
   tests (`module-specifier.test.ts`) but has not been verified on a real
   Windows build; the regular root-relative path is exercised on every change.
+- `For` list tokens carry no per-item identity: objects without an `id`/`key`
+  field are replaced in place at the same position rather than matched and
+  moved. This is an accepted limitation of the current binding. (The token
+  wire signature itself has switched to a length-prefixed encoding; parsers
+  must not assume the old fixed-width format.)
+- `reflect` attribute mirroring normalizes values at the boundary: `NaN`
+  becomes `0`, `-0` becomes `0`, objects are mirrored as `String(value)`, a
+  failed `Number` parse falls back to `0`, and `removeAttribute` restores the
+  declared default, which is then re-mirrored to the attribute.

docs/current/PACKAGE_SURFACE.md

@@ -23,6 +23,15 @@ authoring modes = Basic Element standalone + full application
 Application authors should normally learn `element`, `app`, `adapter-vite`,
 and `create`; `ui` is optional.
 
+## Vocabulary
+
+- **Hydration** — element-level: how and when a component's client JavaScript
+  is loaded (`load`, `idle`, `visible`, `only`; see `HYDRATION_CONTRACT.md`).
+- **Upgrade** — island-level: the moment a server-rendered custom element is
+  defined and its instance takes over the existing markup.
+- **Activation** — framework takeover: marker activation, event binding and
+  state restoration performed by the runtime after upgrade.
+
 The Element/App root surface exposes one functional element authoring helper:
 `defineElement`. The alpha-only `defineLayout` alias was removed in alpha.13;
 layouts use `defineElement` with the same definition object.
@@ -39,7 +48,7 @@ promise and are not application-authoring surface.
 {
   "@openelement/element": {
     "supported": [".", "jsx-runtime", "jsx-dev-runtime", "build-utils"],
-    "internal": ["open-element-render", "open-element-hydration"]
+    "internal": []
   },
   "@openelement/app": {
     "supported": [".", "hono", "model", "spa", "preact"],
@@ -66,10 +75,18 @@ promise and are not application-authoring surface.
   `createRuntimeAdapter` and the runtime handler types) for build adapters.
   They were removed from the element root export; application code must not
   import them.
-- `@openelement/element/open-element-render` and
-  `@openelement/element/open-element-hydration` are hydration implementation
-  modules (see `HYDRATION_CONTRACT.md`), kept importable for build tooling
-  and Deno type generation.
+- The `open-element-render` and `open-element-hydration` modules are
+  internal-only hydration implementation modules (see
+  `HYDRATION_CONTRACT.md`); their subpath exports were removed in alpha.19.
+  The module files remain inside the package for internal relative imports
+  only.
+- The branded types `SafeHtml` and `UnsafeHtml` and the internal
+  `StyleSheetRule` type are no longer exported from the element root
+  (alpha.18 release notes already claimed their removal; alpha.19 makes it
+  true). Their declarations stay in the internal protocol files.
+- The element root no longer carries `export type *` seams (alpha.19); the
+  public type surface is an explicit export list in
+  `packages/element/src/index.ts`.
 - `@openelement/app/i18n` is the optional locale-expansion integration point.
 - App's router implementation (`internal/router`) is not exported; the router
   types (`RouteConfig`, `RouterInstance`, `RouterMode`) were removed from the