@ktjs/mui-icon 0.32.5 → 0.33.1

package/README.md

@@ -12,11 +12,14 @@
 
 <p align="center"><strong>Visit KT.js: <a href="https://baendlorel.github.io/kt.js/">https://baendlorel.github.io/kt.js/</a></strong></p>
 
+> kt.js is still under development, so there might be some breaking changes. Note the Update Log below
+
 ## Recent Updates
 
-1. Special refs for `Array`, `Set`, `Map`, `WeakMap`, `WeakSet`, `Date` to better track mutations.
-   - e.g. `const a = ref.array([1, 2])`, then we can call `a.push(3)` to make a reactive change instead of `a.value.push(3)`.
-2. Fixed issues of `svg` and `mathml` elements.
+1. `ref.value` remains the standard read API, and it can also replace the whole outer value with `ref.value = nextValue`.
+2. `ref.draft` is the deep-mutation entry for nested objects, arrays, `Map` / `Set`, and custom mutable objects.
+3. `ref.draft` itself is not assignable; mutate nested fields or call mutating methods on the returned object instead.
+4. `addOnChange((newValue, oldValue) => ...)` keeps `oldValue` as the previous reference, not a deep snapshot.
 
 ## Community
 
@@ -29,6 +32,35 @@ kt.js is a simple framework with a tiny runtime that renders real DOM directly (
 
 KT.js focuses on one principle: keep direct control of the DOM and avoid unnecessary repainting.
 
+## Reactive Contract
+
+```ts
+const user = ref({ profile: { name: 'John' }, tags: ['new'] });
+
+console.log(user.value.profile.name); // read
+
+user.value = {
+  ...user.value,
+  profile: { ...user.value.profile, name: 'Jane' },
+  tags: [...user.value.tags],
+}; // replace the whole outer value
+
+user.draft.profile.name = 'Jane'; // deep write
+user.draft.tags.push('active'); // array / map / set / custom-object style mutation
+```
+
+Rules:
+
+- Read with `.value`.
+- Replace the whole outer value with `.value = nextValue`.
+- Use `.draft` for deep mutations on nested objects, arrays, `Map` / `Set`, or other mutable instances.
+- Do not assign to `.draft` itself; mutate inside it.
+- `computed` stays read-only and is consumed through `.value`.
+- `oldValue` in change listeners is the previous reference only, not a deep-cloned snapshot.
+- Correctness is expected to come from the transformer and TypeScript checks; runtime hot paths stay minimal on purpose.
+
+This is an explicit contract, closer to a Rust-style model than permissive runtime magic: unclear code should fail early.
+
 ## Quick Start
 
 ```bash