docs: document PathKey encoding and immer performance considerations (#14 #15)

.changeset/path-key-and-immer-docs.md

@@ -0,0 +1,10 @@
+---
+"@ilokesto/form": patch
+---
+
+Document performance considerations for PathKey encoding and immer dependency.
+
+- README.md/README.ko.md FormPath section: note that `JSON.stringify`/`JSON.parse` could be replaced with NUL-separator encoding for large forms; benchmark before migrating.
+- README.md/README.ko.md FormStateWriter section: note that immer (~5KB) could be replaced with spread-based updates for flat record structure; benchmark before migrating.
+
+No code changes — documentation of design decisions and future optimization paths.

README.ko.md

@@ -1054,6 +1054,8 @@ Reader는 store를 직접 소유하지 않고 snapshot getter를 받기 때문
 
 `FormStateWriter`는 모든 state mutation을 `immer`로 수행한다.
 
+> **번들 참고:** `immer`는 컨슈머 번들에 ~5KB를 추가한다. `FormState`가 flat `Record<PathKey, FieldState>` 구조이므로 spread 기반 업데이트(`{ ...state, [key]: nextField }`)로 immer를 대체해도 동작이 동일하다. 마이그레이션 전에 벤치마크하라 — immer는 구조 공유와 가독성 이점을 제공하며, array rebasing 경로에서는 크기 비용을 상회할 수 있다.
+
 `setValue()`:
 
 - Tuple path를 `PathKey`로 변환한다.
@@ -1099,6 +1101,8 @@ Key methods:
 
 JSON encoding이 path collision을 방지한다.
 
+> **성능 참고:** `pathToKey`는 `JSON.stringify`를, `keyToPath`는 `JSON.parse`를 사용한다. 큰 폼(수백 필드)에서 잦은 업데이트 시 NUL separator 기반 커스텀 인코딩으로 hot path 오버헤드를 줄일 수 있다. 마이그레이션 전에 벤치마크하라 — 현재 접근은 정확하고 읽기 쉬우며 실제 영향은 보통 미미하다.
+
 ### `src/core/value/ValueHelper.ts`
 
 `ValueHelper`는 immutable nested value operations를 제공한다.

README.md

@@ -1057,6 +1057,8 @@ The reader receives a snapshot getter rather than owning the store directly, so
 
 `FormStateWriter` performs all state mutations through `immer`.
 
+> **Bundle note:** `immer` adds ~5KB to consumer bundles. Since `FormState` uses a flat `Record<PathKey, FieldState>`, spread-based updates (`{ ...state, [key]: nextField }`) could replace immer with no behavioral change. Benchmark before migrating — immer provides structural sharing and readability benefits that may outweigh the size cost for array rebasing paths.
+
 `setValue()`:
 
 - Converts the tuple path to a `PathKey`.
@@ -1102,6 +1104,8 @@ Key methods:
 
 The JSON encoding is what prevents path collisions.
 
+> **Performance note:** `pathToKey` uses `JSON.stringify` and `keyToPath` uses `JSON.parse`. For large forms (hundreds of fields) with frequent updates, a custom separator-based encoding (e.g. NUL-joined) could reduce hot-path overhead. Benchmark before migrating — the current approach is correct and readable, and real-world impact is typically negligible.
+
 ### `src/core/value/ValueHelper.ts`
 
 `ValueHelper` provides immutable nested value operations.