⚡ general improvements

.github/copilot-instructions.md

@@ -19,8 +19,10 @@ Purpose: Provide just enough project context so an AI assistant can make correct
 * Decode limits: default `depth=5`, `parameterLimit=1000`, `listLimit=20`; exceeding may coerce indices into object keys or (with strict flags) throw.
 * List vs Map merging mimics Node: duplicate keys accumulate to lists unless `duplicates` option changes strategy.
 * `Undefined` entries are placeholders stripped by `Utils.compact` post‑decode / during encode pruning; never serialize `Undefined` itself.
+* `Utils.encode` uses `allowMalformed: true` when decoding `ByteBuffer` as UTF‑8 to match Node `Buffer.toString('utf8')`.
 * Charset sentinel: when `charsetSentinel=true`, `utf8=✓` token (encoded differently per charset) overrides provided `charset` and is omitted from output.
 * `allowDots` & `decodeDotInKeys`: invalid combination (`decodeDotInKeys: true` with `allowDots: false`) must throw (constructor asserts). Preserve that invariant.
+* Merge semantics: list holes are treated as missing values when merging list‑of‑maps by index (no `[Undefined, map]` pair at an index); `parseLists=false` normalizes list results into string‑key maps.
 * Negative `listLimit` disables numeric indexing; with `throwOnLimitExceeded` certain pushes must throw `RangeError` (match existing patterns in decode logic—consult decode part file before altering behavior).
 * Encoding pipeline can inject custom encoder/decoder hooks; preserve argument order and named params (`charset`, `format`, `kind`).
 

CHANGELOG.md

@@ -1,3 +1,14 @@
+## 1.7.0-wip
+
+* [FEAT] add `DecodeOptions.throwOnLimitExceeded` for strict limit enforcement on parameter, list, and depth overflows
+* [FIX] tolerate malformed UTF-8 when encoding `ByteBuffer` values to match Node `Buffer.toString('utf8')`
+* [FIX] encode `ByteBuffer` values via charset even when `encode=false` (avoid `Instance of 'ByteBuffer'` output)
+* [FIX] ensure invalid charset in `Utils.encode` consistently throws `ArgumentError`
+* [FIX] improve merge semantics for lists/maps (hole replacement, undefined normalization under `parseLists=false`, and non-mutating list/set merges)
+* [FIX] add runtime validation and DecodeOptions constructor asserts for invalid charsets and inconsistent dot options
+* [CHORE] refactor encode/merge internals to stack-based frames (`EncodeFrame`, `MergeFrame`, `MergePhase`) for deep-nesting safety
+* [CHORE] expand coverage for encode/decode/merge edge cases and add a shared `FakeEncoding` test helper
+
 ## 1.6.1
 
 * [FIX] prevent `DecodeOptions.listLimit` bypass in bracket notation to mitigate potential DoS via memory exhaustion

README.md

@@ -575,6 +575,10 @@ expect(
 );
 ```
 
+Note: when a value is a `ByteBuffer`, it is still decoded using the selected
+charset even when `encode` is `false`, so the emitted value reflects the buffer
+contents.
+
 Encoding can be disabled for keys by setting the [EncodeOptions.encodeValuesOnly] option to `true`:
 
 ```dart

lib/src/enums/merge_phase.dart

@@ -0,0 +1,17 @@
+import 'package:meta/meta.dart' show internal;
+
+/// Internal phases for the iterative merge walker.
+///
+/// These drive the state machine used by [Utils.merge] to avoid recursion
+/// while preserving `qs` merge semantics for maps and iterables.
+@internal
+enum MergePhase {
+  /// Initial dispatch and shape normalization.
+  start,
+
+  /// Iterating over map entries during a merge step.
+  mapIter,
+
+  /// Iterating over list/set indices during a merge step.
+  listIter,
+}