@kudzujs/core 0.12.1 → 0.12.3

package/PERFORMANCE.md

@@ -6,6 +6,53 @@ Reproducibility classes: `npm run benchmark`, `npm run benchmark:keyed`, `npm ru
 
 The maintained 2026-08-13 comparison used Node 24.14.0 and an Intel Core i5-9500 Linux x64 host, one warm-up, and seven alternating fresh-process samples against clean `v0.8.44`. A narrow fast path skips Kudzu semantic transformation for 450 plain `.ts` modules whose runtime edges are exclusively resolvable relative TypeScript imports or exports; all other modules retain the existing transformer. Compile median fell from 2,323.9 ms to 1,413.2 ms (39.2%) and clean-build median from 3,325.3 ms to 2,382.4 ms (28.4%); every paired sample improved. Compile peak-RSS median fell from 571.2 MiB to 552.6 MiB, while build peak RSS was 570.9 MiB versus 568.8 MiB. Compiler scratch fell from 7,328,390 to 1,971,061 bytes. Both targets emitted the same 50 static HTML files, 10,980 bytes, and deploy SHA-256 `e107d78a7f55bc8a1af0ea6e53efeffa19b3d44d21c892484d103fa346e7ba7b`. This is a source-scale compiler comparison, not a cross-framework result.
 
+## 0.12.3 Route Failure And Restoration Policy
+
+Measured 2026-08-24 on Linux x64 with Node 24.14.0 and Chrome
+142.0.7444.175. Required Chrome proves current-document retention for fetch and
+response-body transport failures, accessible failure status, restored link
+focus, retry after a failed pending prefetch, invalid-document fallback,
+capability-module fallback, stylesheet fallback, and no pre-commit route
+removal. The maintained application-owned HTTP 500 alert and explicit data
+retry continue to pass.
+
+The two-route session uses 16 JavaScript files totaling 61,126 raw / 22,663
+aggregate gzip bytes, an increase of 359 raw bytes from `0.12.2` for
+transport-error classification, status, and focus restoration. The 102-byte
+gzip difference is unpaired and environment-sensitive, so it is not attributed
+to the patch. Navigation
+samples are `[1.5, 1.6, 2.0, 1.7, 1.8, 2.4, 1.8]` ms, with a 1.8 ms median and
+1.5/2.4 ms minimum/maximum. The environment differs from the macOS arm64 Chrome
+151 `0.12.2` measurement, so no latency comparison is claimed.
+
+The application emits 43 files totaling 123,835 raw / 45,379 aggregate gzip
+bytes with deploy SHA-256
+`fb9d24cc01791bf80b67b659738ba62beded6ff6ce14a86a278fa4b34d088acf`.
+Core semantic LOC remains 5,682 with no semantic primitive, compiler pass, core
+compiler line, runtime concept, or public API. Navigation runtime source grows
+from 351 to 374 lines. `/help` remains 0 B JavaScript.
+
+## 0.12.2 Authentication And Permission Boundary
+
+Measured 2026-08-23 on macOS arm64 with Node 25.6.1 and Chrome
+151.0.7922.172. Required Chrome proves invalid and valid login, token-backed
+reload restoration, anonymous and rejected direct entry, role-aware controls,
+server-enforced API and admin authorization, token clearing, and logout.
+
+The two-route session uses 16 JavaScript files totaling 60,767 raw / 22,561
+aggregate gzip bytes, an increase of 1,793 raw / 432 gzip bytes from `0.12.1`
+for authored session state, restoration, and authorization headers. Navigation
+samples are `[1.3, 1.5, 1.5, 1.2, 1.3, 1.4, 1.4]` ms, with a 1.4 ms median and
+1.2/1.5 ms minimum/maximum. The range overlaps `0.12.1`, so no latency change
+is claimed.
+
+The application emits 43 files totaling 123,476 raw / 45,305 aggregate gzip
+bytes with deploy SHA-256
+`81d0b3c5e0d1d1f72f29d219647601463f5317f215274e14a45fe5ba92eb033e`.
+The login route uses 12,093 raw / 5,795 aggregate gzip JavaScript bytes. Core
+semantic LOC remains 5,682 with no pass, primitive, production compiler/runtime
+change, or runtime-concept change. `/help` remains 0 B JavaScript.
+
 ## 0.12.1 Shared Layout, History, Focus, And Scroll
 
 Measured 2026-08-23 on macOS arm64 with Node 25.6.1 and Chrome

package/README.md

@@ -14,7 +14,7 @@ Kudzu compiles ordinary React-shaped TypeScript and TSX into complete static HTM
 
 > Experimental `0.12.x`: the compiler API and supported TSX surface may change.
 
-**Latest release: 0.12.1 - Shared layout, history, focus, and scroll.** Enhanced route groups now prove retained layout state, route cleanup, back/forward history, titles, live announcements, hash and heading focus, explicit scroll policy, and native navigation outside the group. Read the [release notes](./RELEASES.md#0121---shared-layout-history-focus-and-scroll), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.12.1), or follow the [architecture packet](./docs/next-architecture/README.md).
+**Latest release: 0.12.3 - Route failure and restoration policy.** Fetch and response-body transport failures retain the current document for focused retry, while invalid documents and assets keep native fallback. Read the [release notes](./RELEASES.md#0123---route-failure-and-restoration-policy), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.12.3), or follow the [architecture packet](./docs/next-architecture/README.md).
 
 - [Documentation](https://kudzujs.cloud/docs)
 - [Installation guide](https://kudzujs.cloud/docs#install)

package/RELEASES.md

@@ -1,5 +1,106 @@
 # Kudzu Releases
 
+## 0.12.3 - Route Failure And Restoration Policy
+
+Kudzu 0.12.3 defines recovery for enhanced route failures without adding an
+error-boundary renderer or client router.
+
+### Changed in 0.12.3
+
+- Retained the current document when an enhanced navigation fetch or response
+  body fails in transit.
+- Announced transport failure through the existing polite status and restored
+  focus to the initiating native link for explicit retry.
+- Kept invalid document identity, missing capability modules, and missing
+  stylesheets on the existing native fallback path before route disposal.
+- Proved retry after a failed pending prefetch and subsequent click request.
+- Updated `create-kudzu@0.1.116` to generate projects on
+  `@kudzujs/core@^0.12.3`.
+
+### Output Evidence
+
+- The application emits 43 files, 123,835 raw / 45,379 aggregate gzip bytes,
+  and deploy digest
+  `fb9d24cc01791bf80b67b659738ba62beded6ff6ce14a86a278fa4b34d088acf`.
+- The maintained enhanced session uses 16 JavaScript files totaling 61,126 raw
+  / 22,663 aggregate gzip bytes, 359 raw bytes above `0.12.2`.
+- `/help` remains complete HTML with 0 B JavaScript.
+- No semantic primitive, compiler pass, core compiler line, runtime concept,
+  public API, error-boundary renderer, or browser file was added.
+
+### Validation
+
+- Required Chrome proves retained fetch and body failures, accessible status,
+  restored link focus, retry, and native invalid-document/module/style fallback.
+- Seven fresh Chrome profiles record a 1.8 ms navigation median with a 1.5-2.4
+  ms range. The host differs from `0.12.2`, so no latency change is claimed.
+- The full 273-test suite, package smoke, registry metadata, and fresh
+  installation are release gates.
+
+### Limits
+
+The retained-document policy covers classified transport failures. Invalid
+documents and assets use native navigation; arbitrary corrupted generated mount
+descriptors are outside this packet.
+
+### Upgrade
+
+```sh
+npm install @kudzujs/core@^0.12.3
+```
+
+## 0.12.2 - Authentication And Permission Boundary
+
+Kudzu 0.12.2 completes the project application's login, restoration,
+permission-aware UI, server rejection, and logout journey using existing
+application primitives.
+
+### Changed in 0.12.2
+
+- Replaced the placeholder login route with a native constrained form and one
+  application-owned async submit handler.
+- Added layout-owned token restoration, session validation, authenticated user
+  state, role-aware admin controls, and explicit logout.
+- Added bearer authorization to project reads and mutations; the deterministic
+  server rejects missing tokens with 401 and member mutations with 403.
+- Proved that protected static HTML is a UX shell while server authorization is
+  the security boundary.
+- Updated `create-kudzu@0.1.115` to generate projects on
+  `@kudzujs/core@^0.12.2`.
+
+### Output Evidence
+
+- The application emits 43 files, 123,476 raw / 45,305 aggregate gzip bytes,
+  and deploy digest
+  `81d0b3c5e0d1d1f72f29d219647601463f5317f215274e14a45fe5ba92eb033e`.
+- The maintained enhanced session uses 16 JavaScript files totaling 60,767 raw
+  / 22,561 aggregate gzip bytes, 1,793 raw / 432 gzip bytes above `0.12.1`.
+- The login route uses 12,093 raw / 5,795 aggregate gzip JavaScript bytes, while
+  `/help` remains complete HTML with 0 B JavaScript.
+- No semantic primitive, compiler pass, core compiler line, runtime concept,
+  public API, auth runtime, or server was added to Kudzu.
+
+### Validation
+
+- Required Chrome proves invalid and valid login, reload restoration, direct
+  anonymous and rejected entry, member/admin UI, server 401/403 responses,
+  token clearing, and logout.
+- Seven fresh Chrome profiles record a 1.4 ms navigation median with a 1.2-1.5
+  ms range. The range overlaps `0.12.1`, so no latency change is claimed.
+- The full suite, package smoke, registry metadata, and fresh installation are
+  release gates.
+
+### Limits
+
+Client conditional rendering only controls presentation. Applications and
+deployment hosts remain responsible for authorizing protected data and actions.
+
+### Upgrade
+
+```sh
+npm install @kudzujs/core@^0.12.2
+```
+
 ## 0.12.1 - Shared Layout, History, Focus, And Scroll
 
 Kudzu 0.12.1 completes the accepted same-document project route group with

package/docs/next-architecture/application-capability-release-plan.md

@@ -594,15 +594,66 @@ no measured AI-delivery cost effect.
 - **Done condition:** server authorization and client UX responsibilities are
   executable and explicit.
 
+**Completion evidence:** the project application replaces its placeholder login
+route with a native constrained form and one async handler. The shared layout
+restores a stored token, validates the current user, exposes authenticated
+identity and role state, and clears local state before replacement navigation on
+rejection or logout. Required Chrome proves invalid and valid login, reload
+restoration, anonymous and rejected direct protected entry, member/admin control
+visibility, server 401/403 enforcement, token clearing, and logout. Client
+conditions are recorded as presentation only; the deterministic API server
+authorizes every protected read and mutation.
+
+Existing native forms, state, layout ownership, effects, storage, fetch, and
+native navigation are sufficient. This packet adds zero semantic primitives,
+ModuleIR kinds, compiler passes, production compiler/runtime lines, runtime
+concepts, normalization rules, adapter rules, public APIs, auth runtimes, or
+servers. The fixture emits 43 files totaling 123,476 raw / 45,305 aggregate gzip
+bytes with deploy SHA-256
+`81d0b3c5e0d1d1f72f29d219647601463f5317f215274e14a45fe5ba92eb033e`.
+The login route uses 12,093 raw / 5,795 gzip JavaScript bytes. The two-route
+session uses 16 JavaScript files totaling 60,767 raw / 22,561 aggregate gzip
+bytes. Seven fresh Chrome profiles record a 1.4 ms navigation median with a
+1.2/1.5 ms range; the range overlaps `0.12.1`, so no latency change is claimed.
+`/help` remains 0 B JavaScript.
+
 ### `0.12.3`: Route Failure And Restoration Policy
 
 - **Purpose:** decide application-visible handling of navigation/data failures.
 - **Expected boundary:** native fallback and application-owned error UI first.
 - **Acceptance:** invalid document, asset failure, offline/error state, retry,
-  focus restoration, and no half-replaced route.
+  focus restoration, and no half-replaced route for those precommit failures.
 - **Stop condition:** a generic React-style error-boundary renderer is required.
-- **Done condition:** every failure leaves a valid document and recoverable
-  navigation path.
+- **Done condition:** each classified transport, document-validation,
+  capability-loading, or stylesheet-loading failure leaves a valid document
+  and recoverable navigation path.
+
+**Completion evidence:** required Chrome injects deterministic fetch and
+response-body transport rejections through a pending prefetch and click retry,
+then proves the current URL, route DOM, and retained layout remain unchanged.
+The test moves focus away while the request is pending; the existing polite
+navigation status announces the failure and restores the initiating link.
+Activating that link again completes list-to-detail replacement and focuses the
+destination heading.
+Separate invalid-identity, missing-capability-module, and missing-stylesheet
+responses fail before route disposal and recover through the existing native
+document fallback. The maintained HTTP 500 project read still reports an
+application-owned alert and succeeds on explicit retry.
+
+Only `navigation-runtime.js` changes: fetch and response-body transport failures
+receive one private error classification, while document validation and asset
+failures keep their existing fallback. The source grows from 351 to 374 lines and adds no
+semantic primitive, ModuleIR kind, compiler pass, core compiler line, runtime
+concept, public API, error-boundary renderer, route registry, or additional
+browser file. The application emits 43 files totaling 123,835 raw / 45,379
+aggregate gzip bytes with deploy SHA-256
+`fb9d24cc01791bf80b67b659738ba62beded6ff6ce14a86a278fa4b34d088acf`.
+The two-route session remains 16 JavaScript files totaling 61,126 raw / 22,663
+aggregate gzip bytes, 359 raw bytes above `0.12.2`; the unpaired,
+environment-sensitive 102-byte gzip difference is not attributed to the patch.
+`/help` remains 0 B JavaScript. Seven fresh Linux x64 Chrome 142 profiles record
+a 1.8 ms median with a 1.5/2.4 ms range. No latency comparison is claimed
+against the macOS arm64 Chrome 151 `0.12.2` samples.
 
 ### `0.12.4`: Nested Layout Evidence Decision
 
@@ -1150,5 +1201,8 @@ release transaction where possible or document and publish a forward-fix patch.
 | `0.11.3` | Released | Preserve the published optimistic rollback, duplicate prevention, navigation, and retry evidence. | None |
 | `0.11.4` | Released | Preserve the published bounded pagination, history, refresh, polling cleanup, and exact request-count evidence. | None |
 | `0.12.0` | Released | Preserve direct runtime entry, reload, rewrite, and native fallback evidence. | None |
-| `0.12.1` | Active | Release the completed layout/history/focus/scroll evidence. | None |
-| `0.12.2` onward | Blocked | Complete the `0.12.1` release transaction first. | Ordered patch boundary |
+| `0.12.1` | Released | Preserve the published layout/history/focus/scroll evidence. | None |
+| `0.12.2` | Released | Preserve the published authentication and permission evidence. | None |
+| `0.12.3` | Released | Preserve the published route failure, focused retry, native fallback, and precommit retention evidence. | None |
+| `0.12.4` | Active | Complete the nested layout evidence decision. | None |
+| `0.12.5` onward | Blocked | Complete the `0.12.4` release transaction first. | Ordered patch boundary |

package/docs/next-architecture/versioning.md

@@ -66,7 +66,7 @@ Keep each patch behavior-preserving and independently reviewable. If a boundary
 
 ## Generator Versions
 
-`create-kudzu@0.1.114` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.12.1`.
+`create-kudzu@0.1.116` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.12.3`.
 
 ## Release Boundary
 

package/framework/navigation-runtime.js

@@ -28,7 +28,7 @@ document.addEventListener("click", event => {
   if (!eligibleClick(event, anchor)) return
   const url = new URL(anchor.href)
   event.preventDefault()
-  navigate(url, true)
+  navigate(url, true, anchor)
 })
 document.addEventListener("pointerover", event => prefetchAnchor(event.target.closest?.("a[href]")))
 document.addEventListener("focusin", event => prefetchAnchor(event.target.closest?.("a[href]")))
@@ -111,7 +111,7 @@ function prune(anchors) {
   for (const key of documents.keys()) if (!retained.has(key)) documents.delete(key)
 }
 
-async function navigate(url, push) {
+async function navigate(url, push, source) {
   await ready
   const record = matchRoute(url.pathname)
   if (!record) return fallback(url, push)
@@ -158,6 +158,11 @@ async function navigate(url, push) {
     styleUpdate?.rollback()
     if (pendingStyleUpdate === styleUpdate) pendingStyleUpdate = undefined
     if (current !== revision || error.name === "AbortError") return
+    if (push && error.name === "NavigationRequestError") {
+      status.textContent = "Navigation failed. Retry the link."
+      if (source?.isConnected) source.focus({ preventScroll: true })
+      return
+    }
     fallback(url, push)
     if (committed) return
   }
@@ -172,9 +177,20 @@ async function loadCapabilities(parsed) {
 }
 
 async function fetchDocument(url, record, signal) {
-  const response = await fetch(url, { signal, redirect: "manual", headers: { accept: "text/html" } })
+  let response
+  try {
+    response = await fetch(url, { signal, redirect: "manual", headers: { accept: "text/html" } })
+  } catch (cause) {
+    throw requestError(cause)
+  }
   if (!response.ok || response.redirected || response.type === "opaqueredirect" || !response.headers.get("content-type")?.toLowerCase().includes("text/html")) throw new Error("Navigation response is not successful nonredirected HTML")
-  const incoming = new DOMParser().parseFromString(await response.text(), "text/html")
+  let html
+  try {
+    html = await response.text()
+  } catch (cause) {
+    throw requestError(cause)
+  }
+  const incoming = new DOMParser().parseFromString(html, "text/html")
   const parsed = validate(incoming, record)
   return { incoming, parsed, capabilities: await loadCapabilities(parsed), record }
 }
@@ -315,6 +331,13 @@ function fallback(url, push) {
   else location.reload()
 }
 
+function requestError(cause) {
+  if (cause?.name === "AbortError") return cause
+  const error = new Error("Navigation request failed", { cause })
+  error.name = "NavigationRequestError"
+  return error
+}
+
 function between(start, end) {
   if (start.parentNode !== end.parentNode) throw new Error("Route markers must share a parent")
   const nodes = []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudzujs/core",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",