@kudzujs/core 0.10.1 → 0.10.3

package/PERFORMANCE.md

@@ -1,11 +1,59 @@
 # Performance Records
 
-Reproducibility classes: `npm run benchmark`, `npm run benchmark:keyed`, `npm run benchmark:native`, `npm run benchmark:module-cache`, `npm run benchmark:project-state`, and `npm run benchmark:source-scale` are maintained in this repository; `npm run benchmark:commerce` is a maintained paired runner over the public external storefront; older excluded-workspace sections are historical provenance only and are not current framework rankings.
+Reproducibility classes: `npm run benchmark`, `npm run benchmark:keyed`, `npm run benchmark:native`, `npm run benchmark:module-cache`, `npm run benchmark:project-navigation`, `npm run benchmark:project-state`, and `npm run benchmark:source-scale` are maintained in this repository; `npm run benchmark:commerce` is a maintained paired runner over the public external storefront; older excluded-workspace sections are historical provenance only and are not current framework rankings.
 
 `npm run benchmark:source-scale` generates its fixture outside the repository so 50,000 lines of synthetic source are not tracked. The default topology is 50 pages plus 450 route-owned imported modules. Generation is excluded from timing; fresh-process samples separately report source reads, reachable-graph discovery, source compilation, clean production build, compiler-result and deploy digests, output files/bytes, cache counters, and peak RSS. `ROUTES`, `MODULES_PER_ROUTE`, `FILLER_LINES`, `WARMUPS`, and `RUNS` may reduce or expand the fixture without changing the default acceptance floor. `TARGET_ROOT` measures another checkout; `BASELINE_ROOT` alternates that checkout with the current tree and requires identical deploy output.
 
 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.10.3 Project Persistence Recipe
+
+Measured 2026-08-22 on macOS arm64 with Node 25.6.1 and Chrome
+151.0.7922.172. `RUNS=21 npm run benchmark:project-navigation` uses fresh Chrome
+profiles and exact extensionless application routes. Every accepted sample
+updates workspace state, verifies layout identity and persisted state, then
+measures list-to-detail completion.
+
+The 0.10.2 release baseline and 0.10.3 candidate were measured with the same
+21-profile timing protocol and host; the candidate additionally verifies its
+persistence write before timing:
+
+| Revision | Session JS raw/gzip | Navigation median | Min/max |
+|---|---:|---:|---:|
+| `0.10.2` | 46,418 / 17,045 B | 1.9 ms | 1.3 / 5.5 ms |
+| `0.10.3` candidate | 53,562 / 20,323 B | 1.5 ms | 1.3 / 5.6 ms |
+
+Baseline samples:
+`[1.3, 1.8, 1.6, 1.9, 1.3, 1.3, 1.9, 5.1, 1.7, 1.4, 1.9, 5.0, 4.7, 1.9, 1.7, 5.5, 2.2, 1.7, 1.5, 2.0, 5.2]`.
+
+Candidate samples:
+`[2.6, 1.5, 1.8, 1.3, 1.5, 1.4, 1.7, 1.3, 1.5, 1.5, 1.9, 1.7, 1.6, 5.6, 1.5, 1.6, 1.5, 1.5, 1.5, 1.5, 1.6]`.
+
+The +7,144 raw / +3,278 aggregate gzip bytes are the measured cost of two
+authored layout effects, their route-owned entries, and one native clear
+handler. The median changes from 1.9 to 1.5 ms with overlapping ranges, so no
+latency improvement or regression is claimed. No compiler or browser-runtime
+source changed. `/help` remains 0 B JavaScript, so unused routes pay no
+persistence cost.
+
+## 0.10.2 Project Shared-Layout Navigation
+
+Measured 2026-08-22 on macOS arm64 with Node 25.6.1 and Chrome
+151.0.7922.172. `npm run benchmark:project-navigation` builds the tracked
+project application, updates the layout-owned workspace state, and measures
+list-to-detail completion across seven fresh Chrome profiles. Every accepted
+sample verifies retained layout identity and the shared workspace value before
+reporting timing.
+
+The two-route session uses 10 unique JavaScript files totaling 46,418 raw /
+17,045 aggregate gzip bytes. Navigation samples are
+`[2.3, 6.5, 1.4, 1.3, 5.1, 1.3, 4.0]` ms, with a 2.3 ms median and 1.3/6.5 ms
+minimum/maximum. Both routes use the existing shared runtime family;
+`workspace` has layout lifetime while summary, collection, filter, conditional,
+saved-filter, row, and detail-draft states retain route lifetime. No compiler or
+browser runtime source changed, so no revision-to-revision performance claim is
+made.
+
 ## 0.10.1 Project State Scale
 
 Measured 2026-08-22 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.10.x`: the compiler API and supported TSX surface may change.
 
-**Latest release: 0.10.1 - Application state scale.** The tracked project application now proves primitive, object, array, derived, conditional, and nested keyed state ownership with measured commit scaling and a zero-JavaScript static control. Read the [release notes](./RELEASES.md#0101---application-state-scale), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.10.1), or follow the [architecture packet](./docs/next-architecture/README.md).
+**Latest release: 0.10.3 - Application-owned persistence.** The tracked project application now restores and writes a versioned workspace record, falls back safely from invalid storage, clears state on logout, and keeps static routes free of persistence code. Read the [release notes](./RELEASES.md#0103---application-owned-persistence), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.10.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,103 @@
 # Kudzu Releases
 
+## 0.10.3 - Application-Owned Persistence
+
+Kudzu 0.10.3 proves guarded browser persistence as application code composed
+from ordinary state, effects, and native Web Storage.
+
+### Changed in 0.10.3
+
+- Added a versioned workspace restore recipe with deterministic static fallback
+  and exact value/schema/version validation.
+- Added a readiness guard so dependency persistence cannot overwrite storage
+  before mount restoration completes.
+- Added application-owned logout clearing and visible state reset in one native
+  handler.
+- Added required-Chrome cases for valid, absent, malformed, wrong-schema, and
+  wrong-version records, persistence writes, and logout removal.
+- Updated `create-kudzu@0.1.107` to generate projects on
+  `@kudzujs/core@^0.10.3`.
+
+### Output Evidence
+
+- The application fixture emits 19 files, 65,376 raw / 23,471 aggregate gzip
+  bytes, and deploy digest
+  `bb58826876bdf090a85d2c1f8a1edcbbc9abd35d5335eb3d1e7fb1fafe6bed72`.
+- The list/detail session uses 15 unique JavaScript files totaling 53,562 raw /
+  20,323 aggregate gzip bytes; `/help` remains 0 B JavaScript.
+- Matched 21-profile navigation medians are 1.9 ms for 0.10.2 and 1.5 ms for
+  0.10.3 with overlapping ranges, so no latency change is claimed.
+- No semantic primitive, compiler pass, production compiler line, runtime
+  concept, persistence API, store, or storage runtime was added.
+
+### Validation
+
+- Required Chrome proves restore, fallback, write, clear, conditional/keyed
+  release and fresh remount, route draft reset, and fresh direct documents.
+- The full suite, package smoke, registry metadata, and fresh installation are
+  release gates.
+
+### Limits
+
+Schema migration chains, expiry, encryption, cross-tab storage events, and
+server synchronization remain application concerns or later evidence packets.
+
+### Upgrade
+
+```sh
+npm install @kudzujs/core@^0.10.3
+```
+
+## 0.10.2 - Shared-layout navigation
+
+Kudzu 0.10.2 extends the tracked project-management application with explicit
+list/detail navigation, layout-owned workspace state, and route-owned drafts
+using the existing navigation and shared-state semantics.
+
+### Changed in 0.10.2
+
+- Added one Context-backed application layout that lowers through existing
+  `SharedStateIR` and persists workspace selection across list/detail routes.
+- Added an exact Alpha detail route whose draft state releases on navigation and
+  initializes fresh on revisit and direct document load.
+- Added a maintained seven-profile list-to-detail navigation benchmark with
+  session JavaScript and lifetime metadata.
+- Kept `/help` and `/login` outside the navigation group; `/help` remains a
+  complete zero-JavaScript native-navigation target.
+- Updated `create-kudzu@0.1.106` to generate projects on
+  `@kudzujs/core@^0.10.2`.
+
+### Output Evidence
+
+- The application fixture emits 14 files, 57,293 raw / 19,985 aggregate gzip
+  bytes, and deploy digest
+  `1c867ee7119f7eb23b935c4506c2a46639acb75c13f0916b29c255421b0d123d`.
+- The list/detail session uses 10 unique JavaScript files totaling 46,418 raw /
+  17,045 aggregate gzip bytes; `/help` remains 0 B JavaScript.
+- Seven fresh Chrome profiles record list-to-detail completion at a 2.3 ms
+  median, with 1.3/6.5 ms minimum/maximum.
+- No semantic primitive, compiler pass, production compiler line, runtime
+  concept, store, or SPA router was added.
+
+### Validation
+
+- Required Chrome proves layout identity and workspace persistence in both
+  directions, route DOM release, fresh draft state, and direct-load reset.
+- The full suite, required-Chrome application journey, package smoke, registry
+  metadata, and fresh installation are release gates.
+
+### Limits
+
+Navigation remains explicit and group-scoped with complete-document fallback.
+This release does not add a universal SPA router, persistence, authentication,
+server data, or cross-group shared state.
+
+### Upgrade
+
+```sh
+npm install @kudzujs/core@^0.10.2
+```
+
 ## 0.10.1 - Application state scale
 
 Kudzu 0.10.1 extends the tracked project-management journey across ordinary

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

@@ -185,6 +185,9 @@ deploy output under `v0.10.0` and the candidate. Seven fresh Chrome processes
 record commit medians of 0.5/0.6/0.9 ms as the derived binding dependency edges
 increase from 0 to 8 to 32. Runtime JavaScript is 768/10,935/11,341 raw bytes
 and 441/4,789/4,841 aggregate gzip bytes. No material regression is present.
+Release commit `f04041b`, tag `v0.10.1`, both CI jobs, the GitHub release,
+`@kudzujs/core@0.10.1`, `create-kudzu@0.1.105`, registry metadata, and a fresh
+scaffold install/check are verified.
 
 ### `0.10.2`: Shared Layout And Cross-Route State
 
@@ -200,6 +203,32 @@ and 441/4,789/4,841 aggregate gzip bytes. No material regression is present.
 - **Done condition:** state lifetime and disposal are exact in browser tests and
   static routes receive no shared-state runtime.
 
+**Completion evidence:** the greenfield application adds one exact Alpha detail
+route and one explicit navigation group around list/detail routes. A relative
+Context hook lowers through the existing `SharedStateIR`: both routes own the
+same `workspace` layout state while list state and the detail `draft` remain
+route-owned. Required Chrome proves retained layout DOM identity, workspace
+persistence in both directions, detail DOM release, fresh draft state on
+re-entry, and initial layout/draft values in a fresh document. `/help` remains
+outside the group, retains its native anchor path, and emits complete HTML with
+0 B JavaScript.
+
+This packet adds no semantic primitive, ModuleIR kind, compiler pass, production
+compiler LOC, runtime concept, normalization rule, adapter rule, store, or SPA
+router. It adds one application layout/context module, one route, one config,
+and one positive browser journey; existing navigation-group diagnostics retain
+the nearby rejected configuration boundary. The fixture emits 14 files, 57,293
+raw / 19,985 aggregate gzip bytes, with deploy SHA-256
+`1c867ee7119f7eb23b935c4506c2a46639acb75c13f0916b29c255421b0d123d`.
+The list/detail session uses 10 unique JavaScript files totaling 46,418 raw /
+17,045 aggregate gzip bytes. Seven fresh Chrome profiles record list-to-detail
+completion at `[2.3, 6.5, 1.4, 1.3, 5.1, 1.3, 4.0]` ms, median 2.3 ms.
+
+Release commit `76a45c4`, tag `v0.10.2`, both CI jobs, the GitHub release,
+`@kudzujs/core@0.10.2`, `create-kudzu@0.1.106`, registry metadata, and a fresh
+registry-backed scaffold install/check passed on 2026-08-22. Publish workflow
+`32566976581` completed every version, package, publication, and registry gate.
+
 ### `0.10.3`: Persistence Recipe And State Release
 
 - **Purpose:** prove URL, storage, and server-backed persistence without adding a
@@ -212,6 +241,35 @@ and 441/4,789/4,841 aggregate gzip bytes. No material regression is present.
 - **Done condition:** deterministic static fallback and browser recovery pass
   with no storage runtime in unused routes.
 
+**Completion evidence:** the greenfield application layout now owns one guarded
+`localStorage` recipe composed entirely from ordinary state and two existing
+effects. Static HTML starts with `Primary`; a mount effect accepts only version
+1 records whose workspace is `Primary` or `Secondary`, while absent, malformed,
+wrong-schema, and wrong-version records fall back safely. A readiness state
+prevents the dependency effect from overwriting storage before restore.
+Workspace changes write the versioned record, and logout disables persistence,
+removes the record, and resets visible state in one synchronous handler.
+
+Required Chrome proves valid restore, every fallback, post-commit persistence,
+logout removal, conditional and keyed release/fresh remount, route draft
+release/fresh revisit, and a fresh direct document. `/help` remains outside the
+navigation group with complete HTML and 0 B JavaScript. The fixture emits 19
+files, 65,376 raw / 23,471 aggregate gzip bytes, with deploy SHA-256
+`bb58826876bdf090a85d2c1f8a1edcbbc9abd35d5335eb3d1e7fb1fafe6bed72`.
+The two-route session uses 15 unique JavaScript files totaling 53,562 raw /
+20,323 aggregate gzip bytes.
+
+This packet adds zero semantic primitives, ModuleIR kinds, compiler passes,
+production compiler lines, runtime concepts, normalization rules, adapter
+rules, public APIs, stores, or persistence runtimes. One existing positive
+application fixture gains valid, absent, malformed, wrong-schema, wrong-version,
+write, and clear browser cases. A matched 21-profile measurement records the
+authored capability cost: the 0.10.2 list/detail median of 1.9 ms and 46,418 raw /
+17,045 gzip session JavaScript becomes 1.5 ms and 53,562 / 20,323 bytes. The
+timing ranges overlap with no material loss; the 7,144 raw / 3,278 gzip byte
+increase is the explicit cost of route-owned effect/native entries, not a
+compiler or shared-runtime change.
+
 ## `0.11.x`: Async And Server Data
 
 ### `0.11.0`: Owned Fetch Lifecycle
@@ -857,5 +915,7 @@ release transaction where possible or document and publish a forward-fix patch.
 | Patch | Status | Next exact action | Blocker |
 |---|---|---|---|
 | `0.10.0` | Released | Preserve the published application baseline and release evidence. | None |
-| `0.10.1` | Active | Run the full release gate and publish the accepted state-scale evidence. | None |
-| `0.10.2` onward | Blocked | Wait for the preceding patch acceptance and release record. | Ordered dependency |
+| `0.10.1` | Released | Preserve the published state-scale evidence and explicit object-field limit. | None |
+| `0.10.2` | Released | Preserve the published shared-layout navigation and exact route-release evidence. | None |
+| `0.10.3` | Active | Add the guarded application-owned persistence and state-release journey. | None |
+| `0.11.0` onward | Blocked | Wait for the preceding patch acceptance and release record. | Ordered dependency |

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.105` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.10.1`.
+`create-kudzu@0.1.107` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.10.3`.
 
 ## Release Boundary
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudzujs/core",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",
@@ -60,6 +60,7 @@
     "benchmark:commerce": "node test/commerce-build-performance.mjs",
     "benchmark:module-cache": "node test/module-cache-performance.mjs",
     "benchmark:native": "node test/native-performance.mjs",
+    "benchmark:project-navigation": "node test/project-navigation-performance.mjs",
     "benchmark:project-state": "node test/project-state-performance.mjs",
     "benchmark:source-scale": "node test/source-scale-performance.mjs",
     "prepublishOnly": "npm run check && npm test",