@zakkster/lite-signal-decorators 1.1.0 → 1.1.1

package/CHANGELOG.md

@@ -4,6 +4,61 @@ All notable changes to `@zakkster/lite-signal-decorators` are documented here.
 The format follows Keep a Changelog; this project adheres to Semantic
 Versioning.
 
+## [1.1.1] - 2026-08-30
+
+A docs-accuracy patch. No runtime, fixture, or emit-matrix byte changed; the
+accessor canon and every export are byte-identical to 1.1.0. The only test
+changes are `test/15`'s cookbook ground-truth recount for wave 2 and two
+comment-only lines in the gate's step description -- no budget moved anywhere.
+Surface stays at 18 exports; pack stays the same 7-file set.
+
+### Changed
+
+- Standards phrasing pass across README, llms.txt, package.json, the main-file
+  header, and the catalog card. TC39 lists the decorators proposal (and
+  Decorator Metadata) at Stage 2.7 since the 2026-05 plenary, down from Stage 3;
+  the emitters are unchanged -- TypeScript 5.x standard emit and Babel `2023-11`
+  remain the only real-world paths, no native engine ships decorators. Each doc
+  now names the fact once and refers to the protocol by its emitters everywhere
+  else, since stage labels drift and emitter names do not. Only the stage LABEL
+  moved: the emit matrix, the committed TS/Babel fixtures, and every test are
+  byte-untouched by this pass. Recorded in `research/feature-gap-2026-08-30.md` section 1 and
+  the `decisions/0011` addendum. Three-place version sync to 1.1.1
+  (`package.json`, the `VERSION` const, `llms.txt`).
+
+### Added
+
+- Cookbook wave 2: six recipes appended, `r12`..`r17`.
+  - `r12` -- Wait for a condition, as a Promise.
+  - `r13` -- React to a computed value, not every write (GATED).
+  - `r14` -- Tie teardown to an AbortSignal.
+  - `r15` -- Async state without async in the graph.
+  - `r16` -- Read without subscribing.
+  - `r17` -- Start the resource when someone is watching (GATED).
+- Cookbook gated set grows 6 -> 8 (adds `r13`, `r17`).
+- Publications refresh (P3): the outward drafts restamped to the 1.1.x story;
+  files stay git-untracked.
+- Bench chart artifact (closes ROADMAP open question 5): `bench/chart.mjs`
+  renders `bench/results-chart.svg` -- the CHURN lane (ops/s + heapMed per
+  adapter) parsed verbatim from the stamped `bench/results.txt`, deterministic
+  and dev-side only (never in `files[]`); wired into the README numbers section.
+
+### Gate output (section-10 chain, archived verbatim)
+
+```
+  fixtures              OK       exit 0 -- emit fixtures regenerated
+  test                  OK       exit 0 -- 257 pass / 0 fail
+  test:gc               OK       exit 0 -- 257 pass / 0 fail
+  torture               OK       exit 0 -- 14 passed, 2 skipped, 0 warned, 0 failed in 33.1s
+  torture:controls      OK       exit 0 -- 16 passed, 0 skipped, 0 warned, 0 failed in 2.0s
+  torture:peer-preview  REPORTED NON-BLOCKING -- lane completed (exit 0) [preview   1.9.0-preview.6     SUITE-GREEN     16 passed, 0 skipped, 0 warned, 0 failed; canary    1.9.0-canary.1      SUITE-GREEN     16 passed, 0 skipped, 0 warned, 0 failed]
+  bench:selftest        OK       exit 0 -- ALL PASS -- 22 passed, 0 failed
+  cookbook              OK       exit 0/0 -- corpus 18/18 companions ok in 2.1s; controls 8/8 controls fail correctly in 5.0s
+  pack                  OK       exit 0 -- 7/7 files, exact 7-name set, no demo/ no Publications/
+----------------------------------------------------------------------
+  GATE PASS -- 8 blocking steps + 1 non-blocking (peer-preview)
+```
+
 ## [1.1.0] - 2026-08-30
 
 The pooled-lifetime release: an instance is no longer single-lifetime. The

package/README.md

@@ -10,9 +10,10 @@
 ![TypeScript](https://img.shields.io/badge/TypeScript-Types-informational?style=for-the-badge)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
 
-> Stage-3 decorators that turn a plain class into a reactive view-model with a
-> measured per-property cost, one deterministic teardown, and poison-on-dispose
-> safety -- built on @zakkster/lite-signal.
+> Standard decorators (TC39 decorators proposal, Stage 2.7 since 2026-05; TS
+> 5.x / Babel 2023-11 emit unchanged) that turn a plain class into a reactive
+> view-model with a measured per-property cost, one deterministic teardown, and
+> poison-on-dispose safety -- built on @zakkster/lite-signal.
 
 **`@reactive accessor` fields, `@derived` getters, `@reactiveEffect` methods, `@batched` actions, one `@reactiveHost` wiring site -- and `disposeReactive()` tears the whole instance down in one call, every time, with nothing left dangling. A decorated read costs ~1.0x a hand-written instance-field signal read. An instance costs exactly P + D + E + 1 pool nodes and gives all of them back on dispose. A buildless twin, `defineReactive()`, delivers the identical feature set with zero transpiler.**
 
@@ -70,7 +71,7 @@ npm i @zakkster/lite-signal-decorators @zakkster/lite-signal
 
 `@zakkster/lite-signal` (`>=1.5.0 <2.0.0`) is a **peer dependency**, and that is a correctness requirement, not a formality: your decorated instances, your raw signals, and the engine's node pool must live in ONE reactive graph. A second nested copy of the engine would silently split that graph. Install both at the top level.
 
-ESM-only. Ships TypeScript definitions. Node >= 18. The `@` syntax needs a Stage-3 decorator toolchain (TypeScript 5 or Babel `2023-11` -- see [Compatibility](#compatibility)); [`defineReactive`](#definereactiveclass-spec---class) needs nothing.
+ESM-only. Ships TypeScript definitions. Node >= 18. The `@` syntax needs a standard-decorators toolchain (TypeScript 5 or Babel `2023-11` -- see [Compatibility](#compatibility)); [`defineReactive`](#definereactiveclass-spec---class) needs nothing.
 
 ### Quick start
 
@@ -259,7 +260,7 @@ With labels and audit off, the zero-GC budgets are byte-identical to 0.3.0 -- th
 | Export | Value |
 |---|---|
 | `ReactiveDisposedError` | `extends Error`; `name: "ReactiveDisposedError"`; fields `className`, `key`. Thrown on ANY touch of a disposed instance's surface. |
-| `VERSION` | `"1.1.0"` |
+| `VERSION` | `"1.1.1"` |
 
 ### The rejection matrix
 
@@ -376,7 +377,7 @@ The ~7 ns over raw batch is the guarded thunk + rest-array the decorator allocat
 | `disposeReactive(vm)` | none | allocation-free success path; poison handles are prebuilt per member at decoration time |
 | `boxOf` / `rootOf` / any throw | cold path | introspection and failure paths may allocate; never on the hot path |
 
-The gates that hold it (run on every change, all green at 1.1.0):
+The gates that hold it (run on every change, all green at 1.1.1):
 
 - `npm test` / `npm run test:gc` -- **257/257** on both lanes.
 - Suite gate (lite-leak + lite-gc-profiler): `leak=size 0/0 findings=0 warnings=0 | gc major=0 minor=0 maxMs=0.00 | ok`.
@@ -385,6 +386,10 @@ The gates that hold it (run on every change, all green at 1.1.0):
 
 The cross-framework matrix lives in `bench/` (private, never shipped): six engines -- both our tiers, the hand-written `lite-raw-boxes` baseline, MobX 7, signal-utils/signal-polyfill, and a hand-rolled alien-signals class -- across eight class-shaped scenarios (including the `churn-reuse` acquire/release lane, where the lite tiers pool with zero retained growth and MobX/signal-utils/alien-class are structurally `unsupported` -- no disposable instance lifecycle to pool), checksum-verified for identical work, stamped into `bench/results.txt`. The formal verdicts are in [`decisions/0006-kill-criteria.md`](decisions/0006-kill-criteria.md): the decorated path measured **0.94x** the hand-written baseline on vm-write and **1.10x** on a 10k-instance fleet read (the 2.0x kill line cleared with margin), and **0 major + 0 minor GC over 4096 construct/use/dispose cycles** with pools at floor -- while emitting ~12.6x less transient garbage per churn run than the hand-rolled class it replaces.
 
+![CHURN benchmark: ops/s and transient heap per adapter](https://raw.githubusercontent.com/PeshoVurtoleta/lite-signal-decorators/main/bench/results-chart.svg)
+
+The chart above is generated from the stamped `bench/results.txt` by `bench/chart.mjs` (`node bench/chart.mjs`) -- it plots the CHURN lane for every adapter at full scale, including `alien-class`, the hand-rolled reference that has no disposable instance lifecycle to pool.
+
 </details>
 
 ---
@@ -412,11 +417,11 @@ npm run test:gc     # the same 257 with --expose-gc (enables the allocation asse
 npm run gate        # the full pre-publish chain (section 10): fixtures -> test -> test:gc -> torture -> controls -> peer-preview (non-blocking) -> bench selftest -> cookbook -> pack
 ```
 
-**257 tests** across sixteen files, all green at 1.1.0. The decorator protocol is tested three times over: against a mock Stage-3 emitter *and* against committed real TypeScript 5 and Babel `2023-11` emits, so both toolchains' codegen is pinned, not assumed.
+**257 tests** across sixteen files, all green at 1.1.1. The decorator protocol is tested three times over: against a mock standard-decorators emitter *and* against committed real TypeScript 5 and Babel `2023-11` emits, so both toolchains' codegen is pinned, not assumed.
 
 | File | Tests | Covers |
 |---|---:|---|
-| `01-protocol-mock` | 30 | Decorator protocol on the mock Stage-3 emitter: wiring, values, options, rejection matrix |
+| `01-protocol-mock` | 30 | Decorator protocol on the mock standard-decorators emitter: wiring, values, options, rejection matrix |
 | `02-fixtures-ts` | 19 | The same laws on real TypeScript 5 emit (committed fixtures) |
 | `03-fixtures-babel` | 19 | The same laws on real Babel `2023-11` emit |
 | `04-fixture-freshness` | 2 | Fixture hashes match the sources (stale-emit guard) + the README emit-matrix block matches its generator |
@@ -435,7 +440,7 @@ npm run gate        # the full pre-publish chain (section 10): fixtures -> test
 
 ### Emit-support matrix
 
-Three fixture sources, two Stage-3 emitters, both emit lanes -- every cell below is a committed, hash-pinned fixture (the `04-fixture-freshness` guard above). The table is generated from the fixture manifest, so a re-emit that changes a byte is loud, not silent:
+Three fixture sources, two standard-decorators emitters, both emit lanes -- every cell below is a committed, hash-pinned fixture (the `04-fixture-freshness` guard above). The table is generated from the fixture manifest, so a re-emit that changes a byte is loud, not silent:
 
 <!-- EMIT-MATRIX:START -->
 Generated by `node test/fixtures/emit-matrix.mjs` from `test/fixtures/hashes.json` -- do not hand-edit. Toolchain pinned by the committed fixtures: **TypeScript 5.9.3**, **@babel/core 7.29.7** + **@babel/plugin-proposal-decorators 7.29.7** (`version: 2023-11`). Each `sha256` is the first 12 hex of the committed emit; `npm run fixtures` regenerates and `test/04-fixture-freshness` fails loudly on any drift.
@@ -496,7 +501,7 @@ The `demo/` directory is dev-only -- it never enters `package.json` `files[]` an
 
 | Path | Requirement |
 |---|---|
-| `@` decorator syntax | A Stage-3 (2023-11) decorator toolchain: **TypeScript >= 5.0** (standard decorators -- leave `experimentalDecorators` unset/false) or **Babel** with `["@babel/plugin-proposal-decorators", { "version": "2023-11" }]`. Both emits are first-class: the suite pins each with committed fixtures. |
+| `@` decorator syntax | A standard-decorators (2023-11) toolchain: **TypeScript >= 5.0** (standard decorators -- leave `experimentalDecorators` unset/false) or **Babel** with `["@babel/plugin-proposal-decorators", { "version": "2023-11" }]`. Both emits are first-class: the suite pins each with committed fixtures. |
 | `defineReactive` | Nothing. Any ESM runtime. |
 | Runtime | Node >= 18 (ESM-only, `sideEffects: false`); browsers via any ESM bundler or native modules. No DOM dependency anywhere in the package. |
 | Peer | `@zakkster/lite-signal` `>=1.5.0 <2.0.0`, installed at the top level (one engine instance, one graph). |
@@ -529,7 +534,7 @@ Verified against the installed `signal-utils@0.21.1`: `@signal` (on accessors or
 | `@signal accessor x` (or `@signal get x`) | `@reactive accessor x` |
 | `@cached get y()` | `@derived get y()` |
 | no disposal API at all | `disposeReactive(vm)` -- **and it disposes**: cascade teardown, poison swap, node-exact conservation |
-| Stage-3 build required | `defineReactive(Class, spec)` -- the buildless door signal-utils has no equivalent for |
+| Standard-decorators build required | `defineReactive(Class, spec)` -- the buildless door signal-utils has no equivalent for |
 
 The cross-framework numbers behind this table are stamped in [`decisions/0006-kill-criteria.md`](decisions/0006-kill-criteria.md) (both engines measured through their documented class APIs at checksum-identical work).
 
@@ -561,14 +566,14 @@ The cross-framework numbers behind this table are stamped in [`decisions/0006-ki
 
 ### The cookbook
 
-[`COOKBOOK.md`](https://github.com/PeshoVurtoleta/lite-signal-decorators/blob/main/COOKBOOK.md) collects twelve composition recipes over the frozen 16-export surface -- how to build the things this package deliberately does not ship a decorator for, by composing the ones it does. Its headline is the **MobX-parity-by-composition matrix**, mapping each remaining MobX construct (`observable.array`, `observable.map`, `observable.deep`, `toJS`, `when`, `runInAction`, `observe`/`intercept`) to a decorator, a suite member, or a recipe -- extending the migration tables above to the rest of MobX with the honest note per row. It walks the **two-plane fleet** (a sim plane of arena columns written raw per frame beside a reactive plane of a handful of committed members), the reactive-collection-without-a-node-per-element pattern, and the **lite-store boundary** where document state meets class state -- stated plainly as the one path that is *not* zero-GC, and why. Every code block is byte-verified against a runnable, GC-gated companion in `cookbook/` (`npm run cookbook`), so a quoted recipe cannot drift from working code. It is delivered GitHub-only -- the installed tarball stays the lean 7-file runtime surface (decisions/0009).
+[`COOKBOOK.md`](https://github.com/PeshoVurtoleta/lite-signal-decorators/blob/main/COOKBOOK.md) collects eighteen composition recipes over the frozen 18-export surface -- how to build the things this package deliberately does not ship a decorator for, by composing the ones it does. Its headline is the **MobX-parity-by-composition matrix**, mapping each remaining MobX construct (`observable.array`, `observable.map`, `observable.deep`, `toJS`, `when`, `runInAction`, `observe`/`intercept`) to a decorator, a suite member, or a recipe -- extending the migration tables above to the rest of MobX with the honest note per row. It walks the **two-plane fleet** (a sim plane of arena columns written raw per frame beside a reactive plane of a handful of committed members), the reactive-collection-without-a-node-per-element pattern, and the **lite-store boundary** where document state meets class state -- stated plainly as the one path that is *not* zero-GC, and why. Every code block is byte-verified against a runnable, GC-gated companion in `cookbook/` (`npm run cookbook`), so a quoted recipe cannot drift from working code. It is delivered GitHub-only -- the installed tarball stays the lean 7-file runtime surface (decisions/0009).
 
 ---
 
 ## FAQ
 
 **Why the `accessor` keyword?**
-It is the Stage-3 mechanism that gives a decorator both an `init` hook (create the box during field initialization -- eagerly, so the getter carries no `if (!box)` lazy branch) and replaceable get/set bodies, without per-instance `defineProperty` calls or a base class. `@reactive` on a plain field is a named throw pointing you to `accessor`.
+It is the standard-decorators protocol mechanism that gives a decorator both an `init` hook (create the box during field initialization -- eagerly, so the getter carries no `if (!box)` lazy branch) and replaceable get/set bodies, without per-instance `defineProperty` calls or a base class. `@reactive` on a plain field is a named throw pointing you to `accessor`.
 
 **How is this different from MobX's `@observable`?**
 Philosophy: MobX trades allocation and administration overhead for maximal transparency; this package trades a little syntax (`accessor`, explicit dispose) for zero hot-path allocation, a node-exact instance cost, and a teardown you can prove. There is no proxy, no administration object per instance, and nothing is left for the GC to find "eventually" -- which is precisely what makes 10k-instance fleets and long sessions flat.

package/SignalDecorators.js

@@ -1,7 +1,7 @@
 /**
- * @zakkster/lite-signal-decorators v1.1.0
+ * @zakkster/lite-signal-decorators v1.1.1
  * --------------------
- * Stage-3 decorator layer over @zakkster/lite-signal. Turns a plain class into
+ * Standard-decorators layer over @zakkster/lite-signal. Turns a plain class into
  * a reactive view-model with measured per-instance cost and deterministic
  * teardown:
  *   - `@reactive accessor x = v`  -- a per-instance signal box, stored in a
@@ -1944,4 +1944,4 @@ export function auditReactive(on) {
 // --- Version ------------------------------------------------------------------
 
 /** Package version. Kept in lockstep with package.json and llms.txt. */
-export const VERSION = "1.1.0";
+export const VERSION = "1.1.1";

package/llms.txt

@@ -1,8 +1,10 @@
 # @zakkster/lite-signal-decorators
 
-VERSION 1.1.0
+VERSION 1.1.1
 
-> Stage-3 decorator layer over @zakkster/lite-signal. Turns a plain class into a
+> Standard-decorators layer over @zakkster/lite-signal, built on the TC39
+> decorators proposal (Stage 2.7 since 2026-05; TS 5.x / Babel 2023-11 emit
+> unchanged). Turns a plain class into a
 > reactive view-model where each instance has a measured per-property cost, a
 > single deterministic teardown, and poison-on-dispose safety. ESM-only, zero
 > runtime dependencies beyond the peer. The accessor read/write bodies carry one
@@ -80,7 +82,7 @@ slot for a poison handle, so any later read/write throws a named
   `FinalizationRegistry` reports any instance GC'd without `disposeReactive`.
 - `ReactiveDisposedError` -- `extends Error`, `name` `"ReactiveDisposedError"`,
   fields `className` and `key`.
-- `VERSION` -- `"1.1.0"`.
+- `VERSION` -- `"1.1.1"`.
 
 ## Registry law (one registry per host chain)
 
@@ -123,7 +125,8 @@ no node leaks, on the decorator path (init-phase) and the buildless path alike.
 
 ## Buildless contract (defineReactive)
 
-`defineReactive(Class, spec)` is for consumers without a Stage-3 transpiler. The
+`defineReactive(Class, spec)` is for consumers without a standard-decorators
+(2023-11) transpiler. The
 spec normalizes (fail closed; `Reflect.ownKeys`, so symbol keys work):
 
 - `signals`: an array of keys (each initial `undefined`) OR a map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zakkster/lite-signal-decorators",
-  "version": "1.1.0",
-  "description": "Stage-3 decorator layer over @zakkster/lite-signal. The reactive class layer where an instance has a measured cost, deterministic teardown, and a churn benchmark.",
+  "version": "1.1.1",
+  "description": "Standard-decorators layer over @zakkster/lite-signal (TC39 decorators proposal, Stage 2.7 since 2026-05; TS 5.x / Babel 2023-11 emit unchanged). The reactive class layer where an instance has a measured cost, deterministic teardown, and a churn benchmark.",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
   "license": "MIT",
   "type": "module",
@@ -39,7 +39,7 @@
     "reactive",
     "reactivity",
     "decorators",
-    "stage-3",
+    "standard-decorators",
     "computed",
     "derived",
     "class",