json-as 1.4.0 → 1.5.0

package/assembly/index.ts

@@ -16,6 +16,7 @@ import {
   serializeFloat64,
   serializeStruct,
   serializeObject,
+  serializeJsonArray,
   serializeRaw,
   serializeString,
   serializeArrayBufferUnsafe,
@@ -34,10 +35,13 @@ import {
   deserializeStaticArray,
   deserializeArbitrary,
   deserializeObject,
+  deserializeJsonArray,
   deserializeRaw,
   deserializeString,
   deserializeArrayBuffer,
   deserializeTypedArray,
+  setParseSrc,
+  getParseSrc,
 } from "./deserialize";
 import {
   BACK_SLASH,
@@ -53,81 +57,155 @@ import {
   FALSE_WORD_U64,
 } from "./custom/chars";
 import { itoa_buffered } from "util/number";
-import {
-  dragonbox_f32_buffered,
-  dragonbox_f64_buffered,
-} from "./util/dragonbox";
+import { dtoa_buffered, ftoa_buffered } from "xjb-as";
 import { ptrToStr } from "./util/ptrToStr";
 import { atoi, bytes, scanStringEnd } from "./util";
 import { scanValueEnd_SIMD } from "./util/scanValueEndSimd";
 import { scanValueEnd_SWAR } from "./util/scanValueEndSwar";
 
-// --- NaN-boxing encoding for JSON.Value ----------------------------------
-// JSON.Value packs its type tag and payload into a single 8-byte word.
-// Real f64 values are stored as their raw IEEE-754 bits; every other type is
-// encoded inside a quiet-NaN ("boxed") word: a 5-bit tag (the JSON.Types id,
-// or Struct for @json classes) plus a 45-bit payload holding a 32-bit pointer
-// or a small scalar. 64-bit ints that don't fit the payload are spilled to a
-// heap StaticArray<u64> referenced by the payload pointer and flagged in the
-// sign bit. Only quiet-NaN doubles whose top two mantissa bits are both set
-// collide with the box signature; hardware NaN is 0x7FF8.. so finite/Inf/NaN
-// doubles all pass through untouched.
-//
-// The managed reference packed into the word is traced by JSON.Value.__visit;
-// AssemblyScript only wires that hook for library-declared classes, so the
-// json-as transform marks this source as a library source (see afterParse).
-// @ts-expect-error: Decorator valid here
-@inline const VAL_QNAN: u64 = 0x7ffc000000000000; // boxed signature (quiet NaN)
-// @ts-expect-error: Decorator valid here
-@inline const VAL_TAG_SHIFT: u8 = 45;
-// @ts-expect-error: Decorator valid here
-@inline const VAL_PAYLOAD_MASK: u64 = 0x00001fffffffffff; // low 45 bits
-// @ts-expect-error: Decorator valid here
-@inline const VAL_PTR_MASK: u64 = 0xffffffff; // wasm32 pointer
-// @ts-expect-error: Decorator valid here
-@inline const VAL_BOX64: u64 = 0x8000000000000000; // sign bit: 64-bit int spilled to heap
-// @ts-expect-error: Decorator valid here
-@inline const VAL_NULL: u64 = VAL_QNAN; // tag 0 (Null), payload 0
-// @ts-expect-error: Decorator valid here
-@inline const VAL_I64_LIMIT: i64 = 17592186044416; // 2^44 — inline range is [-2^44, 2^44)
-// @ts-expect-error: Decorator valid here
-@inline const VAL_U64_LIMIT: u64 = 35184372088832; // 2^45 — inline range is [0, 2^45)
-
-// @ts-expect-error: Decorator valid here
-@inline function valBoxed(w: u64): bool {
+const VAL_QNAN: u64 = 0x7ffc000000000000; // boxed signature (quiet NaN)
+const VAL_TAG_SHIFT: u8 = 45;
+const VAL_PAYLOAD_MASK: u64 = 0x00001fffffffffff; // low 45 bits
+const VAL_PTR_MASK: u64 = 0xffffffff; // wasm32 pointer
+const VAL_BOX64: u64 = 0x8000000000000000; // sign bit: 64-bit int spilled to heap
+const VAL_NULL: u64 = VAL_QNAN; // tag 0 (Null), payload 0
+const VAL_I64_LIMIT: i64 = 17592186044416; // 2^44 - inline range is [-2^44, 2^44)
+const VAL_U64_LIMIT: u64 = 35184372088832; // 2^45 - inline range is [0, 2^45)
+
+// Lazy value-slot payload layout (45-bit box payload), see JSON.Value.lazyBits.
+// Compact form (bit 44 = 0): a source-relative start offset (23 bits) + the
+// value's length (21 bits), both in UTF-16 units. Offset-heavy on purpose:
+// object/array fields are usually small while the document can be large, so
+// offset overflow (a field late in a big doc) is the realistic trigger, not a
+// single giant field - so the offset field gets the wider range. bit 44 flags
+// the absolute (scan-on-demand) fallback for a source/value past those ranges.
+//   bits [0..22] offset (<=~16MB src) · [23..43] length (<=~4MB val) · 44 abs
+const LZ_OFF_BITS: u64 = 23;
+const LZ_OFF_MASK: u64 = 0x7fffff; // (1 << 23) - 1
+const LZ_LEN_MASK: u64 = 0x1fffff; // (1 << 21) - 1
+const LZ_ABS_FLAG: u64 = 0x100000000000; // 1 << 44
+
+// A materialized String box only uses the low 32 payload bits for its pointer,
+// so two spare bits [32..33] cache the value's serialize-escape class. This lets
+// re-serializing a dynamic string skip the per-char escape scan - a clean string
+// emits via a single memcpy. `valPtr` masks bit 32+ off, so the pointer (and GC)
+// are unaffected.
+//   0 = unclassified · 1 = clean (no escaping -> memcpy) · 2 = needs escaping
+const VAL_STR_CLASS_SHIFT: u64 = 32;
+const VAL_STR_CLASS_MASK: u64 = 0x0000000300000000; // bits [32..33]
+const STR_CLASS_UNKNOWN: u32 = 0;
+const STR_CLASS_CLEAN: u32 = 1;
+const STR_CLASS_ESCAPE: u32 = 2;
+
+function valBoxed(w: u64): bool {
   return (w & VAL_QNAN) == VAL_QNAN;
 }
-// @ts-expect-error: Decorator valid here
-@inline function valTag(w: u64): u32 {
+function valTag(w: u64): u32 {
   return <u32>((w >> VAL_TAG_SHIFT) & 0x1f);
 }
-// @ts-expect-error: Decorator valid here
-@inline function valPayload(w: u64): u64 {
+function valPayload(w: u64): u64 {
   return w & VAL_PAYLOAD_MASK;
 }
-// @ts-expect-error: Decorator valid here
-@inline function valPtr(w: u64): usize {
+function valPtr(w: u64): usize {
   return <usize>(w & VAL_PTR_MASK);
 }
-// @ts-expect-error: Decorator valid here
-@inline function valBox(tag: u32, payload: u64): u64 {
+function valBox(tag: u32, payload: u64): u64 {
   return (
     VAL_QNAN | ((<u64>tag) << VAL_TAG_SHIFT) | (payload & VAL_PAYLOAD_MASK)
   );
 }
-// @ts-expect-error: Decorator valid here
-@inline function valIntTag<T>(): u32 {
+function valLazy(w: u64): bool {
+  return valBoxed(w) && valTag(w) == JSON.Types.Lazy;
+}
+function valIntTag<T>(): u32 {
   if (sizeof<T>() == 1) return isSigned<T>() ? JSON.Types.I8 : JSON.Types.U8;
   if (sizeof<T>() == 2) return isSigned<T>() ? JSON.Types.I16 : JSON.Types.U16;
   if (sizeof<T>() == 4) return isSigned<T>() ? JSON.Types.I32 : JSON.Types.U32;
   return isSigned<T>() ? JSON.Types.I64 : JSON.Types.U64;
 }
 
+function hashUtf16(ptr: usize, len: i32): u32 {
+  let h: u32 = 2166136261;
+  for (let i = 0; i < len; i++) {
+    h ^= <u32>load<u16>(ptr + ((<usize>i) << 1));
+    h *= 16777619;
+  }
+  h ^= <u32>len;
+  h *= 16777619;
+  return h;
+}
+
+// v128 path: compare 8 code units (16 bytes) per step, then a u64 step (4) and
+// a scalar tail. Each load is bounded by `len`, so it never reads past either
+// key. Only reachable (and thus only compiled) when the SIMD feature is on, so
+// the intrinsics don't break the naive/swar builds.
+function utf16Equals_SIMD(ptrA: usize, ptrB: usize, len: i32): bool {
+  let i = 0;
+  for (; i + 8 <= len; i += 8) {
+    const off = (<usize>i) << 1;
+    if (v128.any_true(v128.xor(v128.load(ptrA + off), v128.load(ptrB + off))))
+      return false;
+  }
+  for (; i + 4 <= len; i += 4) {
+    const off = (<usize>i) << 1;
+    if (load<u64>(ptrA + off) != load<u64>(ptrB + off)) return false;
+  }
+  for (; i < len; i++) {
+    const off = (<usize>i) << 1;
+    if (load<u16>(ptrA + off) != load<u16>(ptrB + off)) return false;
+  }
+  return true;
+}
+
+function utf16Equals(ptrA: usize, ptrB: usize, len: i32): bool {
+  if (ASC_FEATURE_SIMD) return utf16Equals_SIMD(ptrA, ptrB, len);
+  // Scalar: 4 code units (one u64) per step, scalar tail. Bounded by `len`.
+  let i = 0;
+  for (; i + 4 <= len; i += 4) {
+    const off = (<usize>i) << 1;
+    if (load<u64>(ptrA + off) != load<u64>(ptrB + off)) return false;
+  }
+  for (; i < len; i++) {
+    const off = (<usize>i) << 1;
+    if (load<u16>(ptrA + off) != load<u16>(ptrB + off)) return false;
+  }
+  return true;
+}
+
 // Shared zero-length sentinel for JSON.Obj's key buffer, so an empty object
 // allocates no key storage until its first key is inserted. Never mutated.
 // @ts-expect-error: Decorator valid here
 @lazy const EMPTY_KEYS: StaticArray<u16> = new StaticArray<u16>(0);
 
+// Shared zero-length sentinel for JSON.Obj's key-position/index buffers.
+// Never mutated.
+// @ts-expect-error: Decorator valid here
+@lazy const EMPTY_I32S: StaticArray<i32> = new StaticArray<i32>(0);
+
+// Shared zero-length sentinel for JSON.Obj's value-slot buffer, so an empty
+// object allocates no slot storage until its first value. Never mutated.
+// @ts-expect-error: Decorator valid here
+@lazy const EMPTY_VALS: StaticArray<u64> = new StaticArray<u64>(0);
+
+// A JSON.Obj with at most this many keys resolves lookups by linear scan and
+// never allocates/hashes a key index. Most JSON objects are small and dynamic
+// access touches only a few keys, so the O(n) index build a hash table needs is
+// pure overhead below this size. Above it, the hash index amortizes.
+const OBJ_LINEAR_MAX: i32 = 6;
+
+// Deferred-value record for a lazy JSON.Value (see JSON.Types.Lazy). `lz` packs
+// the unparsed source slice as (sliceStart << 32) | sliceEnd - the same encoding
+// the transform uses for @lazy struct fields. `src` is the GC anchor that keeps
+// the source string (and therefore the slice pointers, which index into its
+// UTF-16 buffer) alive until the value is materialized. Managed so `src` is
+// traced automatically; a JSON.Value's __visit traces the LazyRef itself.
+// @ts-expect-error: decorators allowed here
+@final
+class LazyRef {
+  lz: u64 = 0;
+  src: string = "";
+}
+
 export namespace JSON {
   /**
    * On-demand field marker. `JSON.Lazy<T>` is structurally just `T` (a no-op
@@ -139,15 +217,14 @@ export namespace JSON {
   export type Lazy<T> = T;
 
   /**
-   * Whether a lazy slot's value is JSON null — for `@omitnull` on lazy fields,
+   * Whether a lazy slot's value is JSON null - for `@omitnull` on lazy fields,
    * without forcing materialization. The slot encodes the state: `u64.MAX_VALUE`
    * = materialized (null iff the value pointer is 0), `0` = absent (null), any
    * other value = a not-yet-parsed slice range (null iff it is literally `null`).
    * @param valPtr pointer of the materialized value (0 when null)
    * @param lz    the packed slot
    */
-  // @ts-expect-error: inline
-  @inline export function __lazyIsNull(valPtr: usize, lz: u64): bool {
+  export function __lazyIsNull(valPtr: usize, lz: u64): bool {
     if (lz == u64.MAX_VALUE) return valPtr == 0;
     if (lz == 0) return true;
     const hi = <usize>(lz >>> 32);
@@ -182,11 +259,7 @@ export namespace JSON {
    * @param data T
    * @returns string
    */
-  // @ts-expect-error: inline
-  @inline export function stringify<T>(
-    data: T,
-    out: string | null = null,
-  ): string {
+  export function stringify<T>(data: T, out: string | null = null): string {
     if (isBoolean<T>()) {
       if (out) {
         if (<bool>data == true) {
@@ -226,13 +299,14 @@ export namespace JSON {
       return data.toString();
     } else if (isFloat<T>(data)) {
       out = out
-        ? changetype<string>(__renew(changetype<usize>(out), 64))
-        : changetype<string>(__new(64, idof<string>()));
+        ? changetype<string>(__renew(changetype<usize>(out), 128))
+        : changetype<string>(__new(128, idof<string>()));
+      const startPtr = changetype<usize>(out);
       const bytes =
         (sizeof<T>() == 4
-          ? dragonbox_f32_buffered(changetype<usize>(out), <f32>data)
-          : dragonbox_f64_buffered(changetype<usize>(out), <f64>data)) << 1;
-      return changetype<string>(__renew(changetype<usize>(out), bytes));
+          ? ftoa_buffered(startPtr, <f32>data)
+          : dtoa_buffered(startPtr, <f64>data)) << 1;
+      return changetype<string>(__renew(startPtr, bytes));
     } else if (isNullable<T>() && changetype<usize>(data) == <usize>0) {
       if (out) {
         out = changetype<string>(__renew(changetype<usize>(out), 8));
@@ -289,21 +363,31 @@ export namespace JSON {
   // A type-correct "zero" for any T: null pointer for references, 0/false for
   // value types. `changetype<T>(0)` alone fails for bool/f64 (size mismatch),
   // so branch on isReference at compile time.
-  // @ts-ignore: inline
-  @inline function __zero<T>(): T {
+  function __zero<T>(): T {
     // @ts-ignore: compile-time intrinsic
     if (isReference<T>() || isManaged<T>()) return changetype<T>(0);
     return <T>0;
   }
 
-  // @ts-expect-error: inline
-  @inline export function parse<T>(data: string, out: T = __zero<T>()): T {
+  export function parse<T>(data: string, out: T = __zero<T>()): T {
+    // Anchor the source for any lazy JSON.Obj/JSON.Value built while parsing, so
+    // their stored slice pointers (into `data`'s buffer) stay valid and resolve
+    // against the right string. Save/restore makes nested parses (e.g. a custom
+    // deserializer calling JSON.parse, or JSON.Obj.from) re-entrant-safe.
+    const prevSrc = getParseSrc();
+    setParseSrc(data);
+    const result = parseInternal<T>(data, out);
+    setParseSrc(prevSrc);
+    return result;
+  }
+
+  function parseInternal<T>(data: string, out: T = __zero<T>()): T {
     let dataPtr = changetype<usize>(data);
     const dataEnd = dataPtr + bytes(data);
     // Entry point skips leading whitespace: every deserialize handler may then
     // assume srcStart points at the first non-whitespace char. Handlers must
     // NOT re-skip leading whitespace themselves. (Trailing whitespace is left
-    // intact — scalars stop at the value end, composites self-trim, and
+    // intact - scalars stop at the value end, composites self-trim, and
     // JSON.Raw intentionally preserves trailing bytes.)
     while (dataPtr < dataEnd && JSON.Util.isSpace(load<u16>(dataPtr)))
       dataPtr += 2;
@@ -337,11 +421,18 @@ export namespace JSON {
         isDefined(type.__DESERIALIZE_FAST)
       ) {
         // Reuse the caller-supplied `out` graph when given; otherwise allocate.
-        const obj = changetype<usize>(out)
+        const reuse = changetype<usize>(out) != 0;
+        const obj = reuse
           ? changetype<nonnull<T>>(changetype<usize>(out))
           : changetype<nonnull<T>>(
               __new(offsetof<nonnull<T>>(), idof<nonnull<T>>()),
             );
+        // A freshly allocated object holds uninitialized fields (__new does not
+        // zero). The fast path writes fields in place and may leave some
+        // unwritten (@optional / skip-unknown), so it must run against defaults,
+        // not garbage. A reused graph is already initialized - skip it.
+        // @ts-expect-error: Defined by transform
+        if (!reuse && isDefined(type.__INITIALIZE)) obj.__INITIALIZE();
         // @ts-expect-error: Defined by transform
         if (isDefined(type.__DESERIALIZE_FAST)) {
           // @ts-expect-error: Defined by transform
@@ -358,7 +449,7 @@ export namespace JSON {
             JSON.Util.skipWhitespace(fastEnd, dataPtr + dataSize) ==
               dataPtr + dataSize
           ) {
-            // @ts-expect-error: Defined by transform for @lazy-field structs —
+            // @ts-expect-error: Defined by transform for @lazy-field structs -
             // pins the source so stored slice ranges stay valid.
             if (isDefined(obj.__SET_SRC)) obj.__SET_SRC(data);
             return obj;
@@ -383,11 +474,15 @@ export namespace JSON {
           0,
         );
       } else if (type instanceof Array) {
+        // Reuse the caller-supplied array when given (no allocation); the
+        // element loop overwrites slots and trims length. Otherwise allocate.
         // @ts-expect-error
         return deserializeArray<nonnull<T>>(
           dataPtr,
           dataPtr + dataSize,
-          changetype<usize>(instantiate<T>()),
+          changetype<usize>(out) != 0
+            ? changetype<usize>(out)
+            : changetype<usize>(instantiate<T>()),
         );
       } else if (
         type instanceof Int8Array ||
@@ -413,8 +508,13 @@ export namespace JSON {
         // @ts-expect-error
         return deserializeSet<nonnull<T>>(dataPtr, dataPtr + dataSize, 0);
       } else if (type instanceof Map) {
+        // Reuse the caller-supplied map when given (keys overwrite in place).
         // @ts-expect-error
-        return deserializeMap<nonnull<T>>(dataPtr, dataPtr + dataSize, 0);
+        return deserializeMap<nonnull<T>>(
+          dataPtr,
+          dataPtr + dataSize,
+          changetype<usize>(out),
+        );
       } else if (type instanceof Date) {
         // @ts-expect-error
         return deserializeDate(dataPtr, dataPtr + dataSize);
@@ -422,11 +522,30 @@ export namespace JSON {
         // @ts-expect-error: type
         return deserializeRaw(dataPtr, dataPtr + dataSize);
       } else if (type instanceof JSON.Value) {
+        // Reuse the caller-supplied JSON.Value handle when given (`out`); the
+        // deserializer writes the parsed bits into it. Otherwise allocate.
         // @ts-expect-error
-        return deserializeArbitrary(dataPtr, dataPtr + dataSize, 0);
+        return deserializeArbitrary(
+          dataPtr,
+          dataPtr + dataSize,
+          changetype<usize>(out),
+        );
       } else if (type instanceof JSON.Obj) {
+        // Reuse the caller-supplied JSON.Obj (cleared, buffers kept). Otherwise allocate.
         // @ts-expect-error
-        return deserializeObject(dataPtr, dataPtr + dataSize, 0);
+        return deserializeObject(
+          dataPtr,
+          dataPtr + dataSize,
+          changetype<usize>(out),
+        );
+      } else if (type instanceof JSON.Arr) {
+        // Reuse the caller-supplied JSON.Arr (cleared, buffers kept). Otherwise allocate.
+        // @ts-expect-error
+        return deserializeJsonArray(
+          dataPtr,
+          dataPtr + dataSize,
+          changetype<usize>(out),
+        );
       } else if (type instanceof JSON.Box) {
         // @ts-expect-error
         return new JSON.Box(parseBox(data, changetype<nonnull<T>>(0).value));
@@ -453,47 +572,33 @@ export namespace JSON {
    */
   export namespace Types {
     /** Represents a null value */
-    // @ts-expect-error
-    @inline export const Null: u16 = 0;
-    // @ts-expect-error
-    @inline export const Raw: u16 = 1;
-    // @ts-expect-error
-    @inline export const U8: u16 = 2;
-    // @ts-expect-error
-    @inline export const U16: u16 = 3;
-    // @ts-expect-error
-    @inline export const U32: u16 = 4;
-    // @ts-expect-error
-    @inline export const U64: u16 = 5;
-    // @ts-expect-error
-    @inline export const I8: u16 = 6;
-    // @ts-expect-error
-    @inline export const I16: u16 = 7;
-    // @ts-expect-error
-    @inline export const I32: u16 = 8;
-    // @ts-expect-error
-    @inline export const I64: u16 = 9;
-    // @ts-expect-error
-    @inline export const F32: u16 = 10;
-    // @ts-expect-error
-    @inline export const F64: u16 = 11;
-    // @ts-expect-error
-    @inline export const Bool: u16 = 12;
+    export const Null: u16 = 0;
+    export const Raw: u16 = 1;
+    export const U8: u16 = 2;
+    export const U16: u16 = 3;
+    export const U32: u16 = 4;
+    export const U64: u16 = 5;
+    export const I8: u16 = 6;
+    export const I16: u16 = 7;
+    export const I32: u16 = 8;
+    export const I64: u16 = 9;
+    export const F32: u16 = 10;
+    export const F64: u16 = 11;
+    export const Bool: u16 = 12;
     // Managed
-    // @ts-expect-error
-    @inline export const String: u16 = 13;
-    // @ts-expect-error
-    @inline export const Object: u16 = 14;
-    // @ts-expect-error
-    @inline export const Array: u16 = 15;
-    // @ts-expect-error
-    @inline export const Map: u16 = 16;
-    // @ts-expect-error
-    @inline export const Struct: u16 = 17;
-    // @ts-expect-error
-    @inline export const TypedArray: u16 = 18;
-    // @ts-expect-error
-    @inline export const ArrayBuffer: u16 = 19;
+    export const String: u16 = 13;
+    export const Object: u16 = 14;
+    export const Array: u16 = 15;
+    export const Map: u16 = 16;
+    export const Struct: u16 = 17;
+    export const TypedArray: u16 = 18;
+    export const ArrayBuffer: u16 = 19;
+    /**
+     * Internal: a not-yet-materialized value holding a raw source slice
+     * (see LazyRef). Never returned by `JSON.Value.type` - accessing the value
+     * materializes it first, so callers only ever observe the concrete type.
+     */
+    export const Lazy: u16 = 20;
   }
 
   /**
@@ -542,7 +647,7 @@ export namespace JSON {
      * @param data - A valid JSON string
      * @returns A new Raw instance
      */
-    @inline static from(data: string): JSON.Raw {
+    static from(data: string): JSON.Raw {
       return new JSON.Raw(data);
     }
   }
@@ -566,8 +671,7 @@ export namespace JSON {
    * ```
    */
   // @ts-expect-error: decorators allowed here
-  @final
-  export class Value {
+  @final export class Value {
     /** Map of struct type IDs to their serialization function indices */
     @lazy static METHODS: Map<u32, u32> = new Map<u32, u32>();
 
@@ -584,6 +688,7 @@ export namespace JSON {
      * stored object's runtime header.
      */
     get type(): u16 {
+      this.materialize();
       const w = this.bits;
       if (!valBoxed(w)) return JSON.Types.F64;
       const tag = valTag(w);
@@ -598,7 +703,7 @@ export namespace JSON {
      * Creates an JSON.Value instance with no set value.
      * @returns An instance of JSON.Value.
      */
-    @inline static empty(): JSON.Value {
+    static empty(): JSON.Value {
       const out = changetype<JSON.Value>(
         __new(offsetof<JSON.Value>(), idof<JSON.Value>()),
       );
@@ -611,7 +716,7 @@ export namespace JSON {
      * @param value - The value to be encapsulated.
      * @returns An instance of JSON.Value.
      */
-    @inline static from<T>(value: T): JSON.Value {
+    static from<T>(value: T): JSON.Value {
       if (value instanceof JSON.Value) return value;
       const out = changetype<JSON.Value>(
         __new(offsetof<JSON.Value>(), idof<JSON.Value>()),
@@ -620,12 +725,248 @@ export namespace JSON {
       return out;
     }
 
+    /**
+     * Creates a lazy JSON.Value wrapping the unparsed source slice
+     * `[sliceStart, sliceEnd)` (UTF-16 byte pointers into `src`). The slice is
+     * parsed into a concrete value on first access (see `materialize`); until
+     * then it serializes by passing those bytes through verbatim. `src` anchors
+     * the source string so the slice pointers stay valid. Internal - produced by
+     * the dynamic deserializers, never called by user code.
+     */
+    static fromSlice(
+      sliceStart: usize,
+      sliceEnd: usize,
+      src: string,
+    ): JSON.Value {
+      const ref = new LazyRef();
+      ref.lz = ((<u64>sliceStart) << 32) | (<u64>(<u32>sliceEnd));
+      ref.src = src;
+      const out = changetype<JSON.Value>(
+        __new(offsetof<JSON.Value>(), idof<JSON.Value>()),
+      );
+      out.bits = valBox(JSON.Types.Lazy, <u64>changetype<usize>(ref));
+      return out;
+    }
+
+    /**
+     * Copy `src`'s NaN-boxed bits into the already-allocated value at `dst`,
+     * applying the itcms write barrier for any managed payload (mirrors
+     * `__visit`'s tracing rule: tags >= String carry a pointer, as do
+     * heap-spilled 64-bit ints). Lets `JSON.parse<JSON.Value>(data, out)` reuse
+     * the caller's handle without materializing `src`.
+     */
+    @unsafe static __adoptInto(dst: usize, src: JSON.Value): JSON.Value {
+      const target = changetype<JSON.Value>(dst);
+      const bits = src.bits;
+      target.bits = bits;
+      if (valBoxed(bits)) {
+        const tag = valTag(bits);
+        if (
+          tag >= JSON.Types.String ||
+          ((tag == JSON.Types.U64 || tag == JSON.Types.I64) &&
+            (bits & VAL_BOX64) != 0)
+        ) {
+          __link(dst, valPtr(bits), false);
+        }
+      }
+      return target;
+    }
+
+    /**
+     * Parses a deferred (lazy) value into a concrete one in place, replacing the
+     * boxed slice with the real boxed value (cached for subsequent reads). The
+     * deferred shapes are strings, objects and arrays; a string materializes to
+     * a `string`, while a composite's own nested deferred children stay lazy -
+     * one level is peeled per access. A no-op for already-materialized values.
+     * Never allocates during GC (not called from `__visit`).
+     */
+    private materialize(): void {
+      const w = this.bits;
+      if (!valLazy(w)) return;
+      const ref = changetype<LazyRef>(valPtr(w));
+      const lz = ref.lz;
+      this.bits = JSON.Value.parseSliceBits(
+        <usize>(lz >>> 32),
+        <usize>(<u32>lz),
+        ref.src,
+      );
+    }
+
+    /**
+     * Parses the raw slice `[start, end)` (the allocating shapes only: string,
+     * object, array) into a concrete value and returns its NaN-boxed bits. A
+     * composite's own nested string/composite children stay lazy - one level is
+     * peeled. Shared by `JSON.Value.materialize` (standalone lazy values) and
+     * `JSON.Obj`'s value-slot materialization.
+     */
+    static parseSliceBits(start: usize, end: usize, src: string): u64 {
+      const first = load<u16>(start);
+      if (first == 0x22 /* '"' */) {
+        // A string anchors no children, so no source pinning is needed.
+        return valBox(
+          JSON.Types.String,
+          <u64>changetype<usize>(deserializeString(start, end)),
+        );
+      }
+      // Pin the same source for the one level we peel so its children defer too.
+      const prev = getParseSrc();
+      setParseSrc(src);
+      let bits: u64;
+      if (first == 0x7b /* '{' */) {
+        bits = valBox(
+          JSON.Types.Object,
+          <u64>changetype<usize>(deserializeObject(start, end, 0)),
+        );
+      } else {
+        bits = valBox(
+          JSON.Types.Array,
+          <u64>changetype<usize>(deserializeJsonArray(start, end, 0)),
+        );
+      }
+      setParseSrc(prev);
+      return bits;
+    }
+
+    /**
+     * Internal: the packed slice `(start << 32) | end` if this value is still a
+     * deferred slice, else 0. Lets the serializer pass raw bytes through without
+     * forcing materialization. `start` is a non-zero pointer, so a real slice is
+     * never 0.
+     */
+    __lazySlice(): u64 {
+      const w = this.bits;
+      if (!valLazy(w)) return 0;
+      return changetype<LazyRef>(valPtr(w)).lz;
+    }
+
+    /**
+     * The cached serialize-escape class of a materialized String value: 0 = not
+     * yet classified, 1 = clean (no chars need escaping, so it serializes via a
+     * single memcpy), 2 = needs escaping. Stored in two spare payload bits so the
+     * scan is paid once and reused. Only meaningful for String-tagged values.
+     */
+    __strClass(): u32 {
+      return <u32>((this.bits >> VAL_STR_CLASS_SHIFT) & 3);
+    }
+    /** Records the serialize-escape class on this String value (see __strClass). */
+    __setStrClass(c: u32): void {
+      this.bits =
+        (this.bits & ~VAL_STR_CLASS_MASK) | ((<u64>c) << VAL_STR_CLASS_SHIFT);
+    }
+    /**
+     * Raw boxed bits. Lets the JSON.Obj/JSON.Arr serializers read back a class
+     * the serializer cached on a transient value (see `serializeArbitrary`) and
+     * persist it into their flat u64 slot, so re-serializing reuses it.
+     */
+    __bits(): u64 {
+      return this.bits;
+    }
+
+    // --- value-slot helpers (JSON.Obj stores values as flat NaN-boxed u64 ---
+    // slots instead of heap JSON.Value objects; these build/inspect/decode the
+    // raw bits without allocating, while keeping the box layout encapsulated).
+
+    /**
+     * Bits for a deferred slot. The 45-bit payload has two forms (bit 44 selects):
+     *
+     *   compact (bit 44 = 0): the value's start *offset* and *length*, both in
+     *     UTF-16 units relative to the source base - `(length << 22) | offset`.
+     *     Gives the exact end with no scan for any value inside a source up to
+     *     2^22 units (8 MB) whose own length is also < 8 MB. This is the common
+     *     case, and storing a relative offset (vs an absolute pointer) is also
+     *     GC-relocation-safe.
+     *
+     *   absolute (bit 44 = 1): the absolute start pointer in the low 32 bits;
+     *     the end is scanned on demand. Fallback for a source or value past the
+     *     8 MB field range - rare, and correct (it scans from the value start;
+     *     scanning a composite cannot safely resume mid-value).
+     */
+    static lazyBits(srcBase: usize, start: usize, end: usize): u64 {
+      const offset = <u64>((start - srcBase) >> 1);
+      const length = <u64>((end - start) >> 1);
+      let payload: u64;
+      if (offset <= LZ_OFF_MASK && length <= LZ_LEN_MASK) {
+        payload = (length << LZ_OFF_BITS) | offset;
+      } else {
+        payload = LZ_ABS_FLAG | ((<u64>start) & VAL_PTR_MASK);
+      }
+      return valBox(JSON.Types.Lazy, payload);
+    }
+    /** The value-end pointer of a lazy slot - from the packed length, or scanned. */
+    static slotEnd(w: u64, srcBase: usize, srcEnd: usize): usize {
+      const p = valPayload(w);
+      if (p & LZ_ABS_FLAG) {
+        return JSON.Util.scanValueEnd<JSON.Value>(
+          <usize>(p & VAL_PTR_MASK),
+          srcEnd,
+        );
+      }
+      const start = srcBase + ((<usize>(p & LZ_OFF_MASK)) << 1);
+      const length = <usize>((p >> LZ_OFF_BITS) & LZ_LEN_MASK);
+      return start + (length << 1);
+    }
+    /** Bits for a JSON null. */
+    static nullBits(): u64 {
+      return VAL_NULL;
+    }
+    /** Bits for a boolean. */
+    static boolBits(b: bool): u64 {
+      return valBox(JSON.Types.Bool, b ? 1 : 0);
+    }
+    /** Bits for an f64 (raw IEEE-754, NaN canonicalized off the box signature). */
+    static f64Bits(v: f64): u64 {
+      return isNaN(v) ? 0x7ff8000000000000 : reinterpret<u64>(v);
+    }
+    /** Whether a slot is still a deferred (start-pointer) slice. */
+    static slotIsLazy(w: u64): bool {
+      return valLazy(w);
+    }
+    /** The start pointer held by a lazy slot (compact offset or absolute). */
+    static slotPtr(w: u64, srcBase: usize): usize {
+      const p = valPayload(w);
+      if (p & LZ_ABS_FLAG) return <usize>(p & VAL_PTR_MASK);
+      return srcBase + ((<usize>(p & LZ_OFF_MASK)) << 1);
+    }
+    /** Wraps raw bits in a JSON.Value (eager scalar / materialized reference). */
+    static fromBits(w: u64): JSON.Value {
+      const out = changetype<JSON.Value>(
+        __new(offsetof<JSON.Value>(), idof<JSON.Value>()),
+      );
+      out.bits = w;
+      return out;
+    }
+    /** Concrete NaN-boxed bits for a value of type T (materializing if lazy). */
+    static bitsFrom<T>(value: T): u64 {
+      const v = JSON.Value.from<T>(value);
+      v.materialize();
+      return v.bits;
+    }
+    /** Decodes NaN-boxed bits into T (the body of the instance `get<T>`). */
+    static decodeBits<T>(w: u64): T {
+      if (isFloat<T>()) {
+        if (sizeof<T>() == 4) return <T>reinterpret<f32>(<u32>valPayload(w));
+        return <T>reinterpret<f64>(w);
+      } else if (isInteger<T>()) {
+        if (sizeof<T>() == 8) {
+          if (w & VAL_BOX64) return load<T>(valPtr(w));
+          if (isSigned<T>()) return <T>((<i64>(valPayload(w) << 19)) >> 19);
+          return <T>valPayload(w);
+        }
+        return <T>valPayload(w);
+      } else if (isBoolean<T>()) {
+        return <T>valPayload(w);
+      } else if (isReference<T>()) {
+        return changetype<T>(valPtr(w));
+      }
+      return unreachable();
+    }
+
     /**
      * Gets the type of a given value as a JSON.Types enum.
      * @param value - any
      * @returns JSON.Types
      */
-    @inline getType<T>(value: T): JSON.Types {
+    getType<T>(value: T): JSON.Types {
       if (isNullable<T>() && changetype<usize>(value) === 0)
         return JSON.Types.Null;
       if (isBoolean<T>()) return JSON.Types.Bool;
@@ -672,13 +1013,14 @@ export namespace JSON {
       if (value instanceof Map) return JSON.Types.Map;
       if (value instanceof JSON.Raw) return JSON.Types.Raw;
       if (value instanceof JSON.Obj) return JSON.Types.Object;
+      if (value instanceof JSON.Arr) return JSON.Types.Array;
       return JSON.Types.Null;
     }
     /**
      * Sets the value of the JSON.Value instance.
      * @param value - The value to be set.
      */
-    @inline set<T>(value: T): void {
+    set<T>(value: T): void {
       if (value instanceof JSON.Box) {
         this.set(value.value);
       } else if (isBoolean<T>()) {
@@ -739,9 +1081,16 @@ export namespace JSON {
         this.bits = valBox(JSON.Types.Map, <u64>changetype<usize>(value));
       } else if (value instanceof JSON.Obj) {
         this.bits = valBox(JSON.Types.Object, <u64>changetype<usize>(value));
+      } else if (value instanceof JSON.Arr) {
+        this.bits = valBox(JSON.Types.Array, <u64>changetype<usize>(value));
         // @ts-expect-error
       } else if (isArray<T>() && idof<valueof<T>>() == idof<JSON.Value>()) {
-        this.bits = valBox(JSON.Types.Array, <u64>changetype<usize>(value));
+        // A JSON.Value[] is converted to the buffer-backed JSON.Arr form, so
+        // the Array tag always boxes a JSON.Arr.
+        this.bits = valBox(
+          JSON.Types.Array,
+          <u64>changetype<usize>(JSON.Arr.from<T>(value)),
+        );
       }
     }
 
@@ -774,24 +1123,9 @@ export namespace JSON {
      * Gets the value of the JSON.Value instance.
      * @returns The encapsulated value.
      */
-    @inline get<T>(): T {
-      const w = this.bits;
-      if (isFloat<T>()) {
-        if (sizeof<T>() == 4) return <T>reinterpret<f32>(<u32>valPayload(w));
-        return <T>reinterpret<f64>(w);
-      } else if (isInteger<T>()) {
-        if (sizeof<T>() == 8) {
-          if (w & VAL_BOX64) return load<T>(valPtr(w));
-          if (isSigned<T>()) return <T>((<i64>(valPayload(w) << 19)) >> 19);
-          return <T>valPayload(w);
-        }
-        return <T>valPayload(w);
-      } else if (isBoolean<T>()) {
-        return <T>valPayload(w);
-      } else if (isReference<T>()) {
-        return changetype<T>(valPtr(w));
-      }
-      return unreachable();
+    get<T>(): T {
+      this.materialize();
+      return JSON.Value.decodeBits<T>(this.bits);
     }
 
     /**
@@ -799,7 +1133,7 @@ export namespace JSON {
      * Alias for .get<T>()
      * @returns The encapsulated value.
      */
-    @inline as<T>(): T {
+    as<T>(): T {
       return this.get<T>();
     }
 
@@ -808,7 +1142,8 @@ export namespace JSON {
      * Alias for .get<T>()
      * @returns The encapsulated value.
      */
-    @inline asBox<T>(): Box<T> | null {
+    asBox<T>(): Box<T> | null {
+      this.materialize();
       if (this.type === JSON.Types.Null) return null;
       return changetype<Box<T>>(JSON.Box.fromValue<T>(this));
     }
@@ -818,6 +1153,7 @@ export namespace JSON {
      * @returns The string representation of the JSON.Value.
      */
     toString(): string {
+      this.materialize();
       switch (this.type) {
         case JSON.Types.Null:
           return "null";
@@ -849,19 +1185,7 @@ export namespace JSON {
           return this.get<JSON.Raw>().toString();
         }
         case JSON.Types.Array: {
-          const arr = this.get<JSON.Value[]>();
-          if (!arr.length) return "[]";
-          let out = "[";
-          const end = arr.length - 1;
-          for (let i = 0; i < end; i++) {
-            const element = unchecked(arr[i]);
-            out += element.toString() + ",";
-          }
-
-          const element = unchecked(arr[end]);
-          out += element.toString() + "]";
-
-          return out.toString();
+          return JSON.stringify(this.get<JSON.Arr>());
         }
         case JSON.Types.TypedArray:
         case JSON.Types.ArrayBuffer: {
@@ -885,6 +1209,14 @@ export namespace JSON {
       const w = this.bits;
       if (!valBoxed(w)) return; // raw f64 holds no reference
       const tag = valTag(w);
+      // A deferred value carries a LazyRef pointer; tracing it keeps the LazyRef
+      // (and, transitively, its `src` anchor) alive. Must precede the
+      // `tag >= String` branch since Lazy(20) would otherwise fall into it.
+      // Trace-only - never materialize here (no allocation during GC).
+      if (tag == JSON.Types.Lazy) {
+        __visit(valPtr(w), cookie);
+        return;
+      }
       // String(13)..ArrayBuffer(19) and Struct all carry a managed pointer;
       // Raw(1) is intentionally not traced (matches prior behavior).
       if (tag >= JSON.Types.String) {
@@ -917,25 +1249,24 @@ export namespace JSON {
    * console.log(JSON.stringify(obj));  // {"key":"value","count":42}
    * ```
    */
-  export class Obj {
-    // Keys are packed into one growable buffer, each prefixed by a u16 length
-    // (UTF-16 code units), instead of allocating a heap string per key. Values
-    // are a parallel array. A key -> position index is built lazily on the
-    // first keyed access (never during parsing). Per-object allocation count
-    // matches the previous Map-based storage, while deserialization avoids the
-    // per-key string allocation and hashing entirely.
+  @final export class Obj {
     _kbuf: StaticArray<u16> = EMPTY_KEYS;
     _kused: i32 = 0;
-    _vals: JSON.Value[] = [];
-    private _index: Map<string, i32> | null = null;
+    _kpos: StaticArray<i32> = EMPTY_I32S;
+    _vals: StaticArray<u64> = EMPTY_VALS;
+    _vused: i32 = 0;
+    /** Source string the lazy slot pointers index into; anchors it for GC. */
+    _src: string = "";
+    private _index: StaticArray<i32> | null = null;
+    private _indexMask: i32 = 0;
 
     constructor() {}
 
     /**
      * Gets the number of key-value pairs in the object.
      */
-    @inline get size(): i32 {
-      return this._vals.length;
+    get size(): i32 {
+      return this._vused;
     }
 
     /** Grows the key buffer to hold at least `need` code units. */
@@ -954,11 +1285,28 @@ export namespace JSON {
       this._kbuf = nb;
     }
 
+    /** Grows the key-position buffer to hold at least `need` entries. */
+    private ensureKeyPosCap(need: i32): void {
+      const cap = this._kpos.length;
+      if (cap >= need) return;
+      let n = cap ? cap : 8;
+      while (n < need) n <<= 1;
+      const nb = new StaticArray<i32>(n);
+      if (this._vused)
+        memory.copy(
+          changetype<usize>(nb),
+          changetype<usize>(this._kpos),
+          (<usize>this._vused) << 2,
+        );
+      this._kpos = nb;
+    }
+
     /** Appends a length-prefixed key (from a source memory range). */
-    private pushKeyBytes(keyStart: usize, keyEnd: usize): void {
+    private pushKeyBytes(keyStart: usize, keyEnd: usize, slotIndex: i32): void {
       const len = <i32>((keyEnd - keyStart) >> 1);
       const pos = this._kused;
       this.ensureKeyCap(pos + 1 + len);
+      this.ensureKeyPosCap(slotIndex + 1);
       const buf = changetype<usize>(this._kbuf);
       store<u16>(buf + ((<usize>pos) << 1), <u16>len);
       if (len)
@@ -967,6 +1315,7 @@ export namespace JSON {
           keyStart,
           (<usize>len) << 1,
         );
+      unchecked((this._kpos[slotIndex] = pos));
       this._kused = pos + 1 + len;
     }
 
@@ -982,38 +1331,215 @@ export namespace JSON {
       return out;
     }
 
+    /** Grows the value-slot buffer to hold at least `need` slots. */
+    private ensureValCap(need: i32): void {
+      const cap = this._vals.length;
+      if (cap >= need) return;
+      let n = cap ? cap : 8;
+      while (n < need) n <<= 1;
+      const nb = new StaticArray<u64>(n);
+      if (this._vused)
+        memory.copy(
+          changetype<usize>(nb),
+          changetype<usize>(this._vals),
+          (<usize>this._vused) << 3,
+        );
+      this._vals = nb;
+    }
+
+    /** Writes a slot and, if it carries a managed pointer, links it for the GC. */
+    private storeSlot(i: i32, bits: u64): void {
+      unchecked((this._vals[i] = bits));
+      if (valBoxed(bits)) {
+        const tag = valTag(bits);
+        // Lazy slots hold an interior `_src` pointer (anchored by the _src
+        // field), not an owned object - never link those.
+        if (
+          tag != JSON.Types.Lazy &&
+          (tag >= JSON.Types.String ||
+            ((tag == JSON.Types.U64 || tag == JSON.Types.I64) &&
+              bits & VAL_BOX64))
+        ) {
+          __link(changetype<usize>(this), valPtr(bits), false);
+        }
+      }
+    }
+
+    /** Appends a value slot (raw NaN-boxed bits). */
+    private pushValSlot(bits: u64): void {
+      const pos = this._vused;
+      this.ensureValCap(pos + 1);
+      this._vused = pos + 1;
+      this.storeSlot(pos, bits);
+    }
+
+    /** End pointer of the source buffer (upper bound for scanning a lazy slot). */
+    private srcEnd(): usize {
+      return changetype<usize>(this._src) + ((<usize>this._src.length) << 1);
+    }
+
+    /** Compares a lookup key against the stored key bytes for slot `i`. */
+    private keyEquals(i: i32, key: string): bool {
+      const pos = unchecked(this._kpos[i]);
+      const buf = changetype<usize>(this._kbuf) + ((<usize>pos) << 1);
+      const len = <i32>load<u16>(buf);
+      if (len != <i32>key.length) return false;
+      return utf16Equals(changetype<usize>(key), buf + 2, len);
+    }
+
+    /** Compares two stored key slots without materializing strings. */
+    private slotEqualsSlot(a: i32, b: i32): bool {
+      const posa = unchecked(this._kpos[a]);
+      const bufA = changetype<usize>(this._kbuf) + ((<usize>posa) << 1);
+      const lenA = <i32>load<u16>(bufA);
+      const posb = unchecked(this._kpos[b]);
+      const bufB = changetype<usize>(this._kbuf) + ((<usize>posb) << 1);
+      const lenB = <i32>load<u16>(bufB);
+      if (lenA != lenB) return false;
+      return utf16Equals(bufA + 2, bufB + 2, lenA);
+    }
+
+    /** Hashes the stored key for slot `i`. */
+    private keyHashAt(i: i32): u32 {
+      const pos = unchecked(this._kpos[i]);
+      const buf = changetype<usize>(this._kbuf) + ((<usize>pos) << 1);
+      const len = <i32>load<u16>(buf);
+      return hashUtf16(buf + 2, len);
+    }
+
+    /** Resolves a key to its slot index, or -1 if absent. */
+    private indexOf(key: string): i32 {
+      const n = this._vused;
+      const keyLen = <i32>key.length;
+      // Small objects: scan linearly and never build a hash index. The keys are
+      // packed contiguously in _kbuf and the length prefix rejects mismatches
+      // before any byte compare. Scan from the end so a duplicate key resolves
+      // to its LAST occurrence - JSON last-value-wins, matching buildIndex()
+      // (which overwrites the slot on a collision) for objects above the
+      // threshold; a forward scan would return the first and disagree.
+      if (n <= OBJ_LINEAR_MAX) {
+        const kbuf = changetype<usize>(this._kbuf);
+        const keyPtr = changetype<usize>(key);
+        const kpos = this._kpos;
+        for (let i = n - 1; i >= 0; i--) {
+          const buf = kbuf + ((<usize>unchecked(kpos[i])) << 1);
+          if (
+            <i32>load<u16>(buf) == keyLen &&
+            utf16Equals(keyPtr, buf + 2, keyLen)
+          )
+            return i;
+        }
+        return -1;
+      }
+      const idx = this.buildIndex();
+      const mask = this._indexMask;
+      if (mask == 0) {
+        const entry = unchecked(idx[0]);
+        return entry != 0 && this.keyEquals(entry - 1, key) ? entry - 1 : -1;
+      }
+      let slot = <i32>(
+        (hashUtf16(changetype<usize>(key), <i32>key.length) & (<u32>mask))
+      );
+      const start = slot;
+      while (true) {
+        const entry = unchecked(idx[slot]);
+        if (entry == 0) return -1;
+        const i = entry - 1;
+        if (this.keyEquals(i, key)) return i;
+        slot = (slot + 1) & mask;
+        // A correctly-maintained table stays below full load, so an empty slot
+        // is found first. This wrap check is a safety net against spinning
+        // forever should that invariant ever be violated.
+        if (slot == start) return -1;
+      }
+    }
+
+    /** Parses a lazy slot in place, caching the concrete box, and returns it. */
+    private materializeSlot(i: i32): u64 {
+      const slot = unchecked(this._vals[i]);
+      if (!JSON.Value.slotIsLazy(slot)) return slot;
+      const base = changetype<usize>(this._src);
+      const start = JSON.Value.slotPtr(slot, base);
+      const end = JSON.Value.slotEnd(slot, base, this.srcEnd());
+      const bits = JSON.Value.parseSliceBits(start, end, this._src);
+      this.storeSlot(i, bits);
+      return bits;
+    }
+
     /**
-     * Appends a key (from a source memory range) and value without a
-     * duplicate-key check. Used by the deserializer — no per-key string
-     * allocation, no hashing.
+     * Appends a key (from a source memory range) and a precomputed NaN-boxed
+     * value slot without a duplicate-key check. Used by the deserializer - no
+     * per-key string allocation, no per-value object, no hashing.
+     */
+    appendRawSlot(keyStart: usize, keyEnd: usize, bits: u64): void {
+      const slotIndex = this._vused;
+      this.pushKeyBytes(keyStart, keyEnd, slotIndex);
+      this.pushValSlot(bits);
+      this.insertIndex(slotIndex);
+    }
+
+    /**
+     * Appends a key and value (any T) without a duplicate-key check. Eagerly
+     * boxes the value into a slot.
      */
     appendRaw<T>(keyStart: usize, keyEnd: usize, value: T): void {
-      this.pushKeyBytes(keyStart, keyEnd);
-      this._vals.push(JSON.Value.from<T>(value));
+      this.appendRawSlot(keyStart, keyEnd, JSON.Value.bitsFrom<T>(value));
+    }
+
+    /** Inserts a single slot into an already-built index. */
+    private insertIndex(slotIndex: i32): void {
       const idx = this._index;
-      if (idx !== null) {
-        const len = <i32>((keyEnd - keyStart) >> 1);
-        const k = changetype<string>(__new((<usize>len) << 1, idof<string>()));
-        if (len) memory.copy(changetype<usize>(k), keyStart, (<usize>len) << 1);
-        idx.set(k, this._vals.length - 1);
+      if (idx === null) return;
+      const mask = this._indexMask;
+      let slot = <i32>(this.keyHashAt(slotIndex) & (<u32>mask));
+      const start = slot;
+      while (unchecked(idx[slot]) != 0) {
+        const entry = unchecked(idx[slot]) - 1;
+        if (this.slotEqualsSlot(entry, slotIndex)) {
+          unchecked((idx[slot] = slotIndex + 1));
+          return;
+        }
+        slot = (slot + 1) & mask;
+        if (slot == start) {
+          this._index = null;
+          return;
+        }
       }
+      unchecked((idx[slot] = slotIndex + 1));
+      // buildIndex() sizes the table at >2x the entry count (load < 0.5), but it
+      // only runs lazily; appends since then go through here without resizing.
+      // Once we cross half load, drop the index so the next access rebuilds it at
+      // double capacity — this keeps an empty slot available for every probe.
+      // Without it a small (e.g. cap-2) table fills and indexOf() spins forever.
+      if ((slotIndex + 1) << 1 > mask + 1) this._index = null;
     }
 
     /** Builds (once) and returns the lazy key -> position index. */
-    private buildIndex(): Map<string, i32> {
+    private buildIndex(): StaticArray<i32> {
       let idx = this._index;
       if (idx === null) {
-        idx = new Map<string, i32>();
-        const buf = changetype<usize>(this._kbuf);
-        const used = this._kused;
-        let pos = 0;
-        let i = 0;
-        while (pos < used) {
-          const len = <i32>load<u16>(buf + ((<usize>pos) << 1));
-          idx.set(this.makeKey(pos + 1, len), i++);
-          pos += 1 + len;
+        const used = this._vused;
+        let cap = 2;
+        while (cap <= used << 1) cap <<= 1;
+        idx = new StaticArray<i32>(cap);
+        const mask = cap - 1;
+        for (let i = 0; i < used; i++) {
+          const keyPos = unchecked(this._kpos[i]);
+          const buf = changetype<usize>(this._kbuf) + ((<usize>keyPos) << 1);
+          const len = <i32>load<u16>(buf);
+          let slot = <i32>(hashUtf16(buf + 2, len) & (<u32>mask));
+          while (unchecked(idx[slot]) != 0) {
+            const entry = unchecked(idx[slot]) - 1;
+            if (this.slotEqualsSlot(entry, i)) {
+              unchecked((idx[slot] = i + 1));
+              break;
+            }
+            slot = (slot + 1) & mask;
+          }
+          if (unchecked(idx[slot]) == 0) unchecked((idx[slot] = i + 1));
         }
         this._index = idx;
+        this._indexMask = mask;
       }
       return idx;
     }
@@ -1024,27 +1550,57 @@ export namespace JSON {
      * @param value - The value (will be wrapped in JSON.Value)
      */
     set<T>(key: string, value: T): void {
-      const idx = this.buildIndex();
-      if (idx.has(key)) {
-        unchecked((this._vals[idx.get(key)] = JSON.Value.from<T>(value)));
+      const bits = JSON.Value.bitsFrom<T>(value);
+      const i = this.indexOf(key);
+      if (i >= 0) {
+        this.storeSlot(i, bits);
       } else {
+        const slotIndex = this._vused;
         this.pushKeyBytes(
           changetype<usize>(key),
           changetype<usize>(key) + ((<usize>key.length) << 1),
+          slotIndex,
         );
-        this._vals.push(JSON.Value.from<T>(value));
-        idx.set(key, this._vals.length - 1);
+        this.pushValSlot(bits);
+        this.insertIndex(slotIndex);
       }
     }
 
     /**
-     * Gets a value by key.
+     * Gets a value by key as a JSON.Value (dynamic access).
      * @param key - The key to look up
      * @returns The JSON.Value or null if not found
      */
-    @inline get(key: string): JSON.Value | null {
-      const idx = this.buildIndex();
-      return idx.has(key) ? unchecked(this._vals[idx.get(key)]) : null;
+    get(key: string): JSON.Value | null {
+      const i = this.indexOf(key);
+      if (i < 0) return null;
+      const slot = unchecked(this._vals[i]);
+      if (JSON.Value.slotIsLazy(slot)) {
+        // Hand back a self-contained lazy value (its own slice + anchor) so it
+        // can materialize independently of this object.
+        const base = changetype<usize>(this._src);
+        const start = JSON.Value.slotPtr(slot, base);
+        const end = JSON.Value.slotEnd(slot, base, this.srcEnd());
+        return JSON.Value.fromSlice(start, end, this._src);
+      }
+      return JSON.Value.fromBits(slot);
+    }
+
+    /**
+     * Gets a value by key directly as `T`, with no intermediate JSON.Value
+     * allocation. A deferred slot is parsed (and cached) on first access; an
+     * absent key returns the type's default (null / 0 / false).
+     *
+     * Named `getAs` rather than `get<T>` because AssemblyScript has no method
+     * overloading - `get(key)` (dynamic) and a typed `get` can't share a name.
+     * @param key - The key to look up
+     */
+    getAs<T>(key: string): T {
+      const i = this.indexOf(key);
+      if (i < 0) return __zero<T>();
+      let slot = unchecked(this._vals[i]);
+      if (JSON.Value.slotIsLazy(slot)) slot = this.materializeSlot(i);
+      return JSON.Value.decodeBits<T>(slot);
     }
 
     /**
@@ -1052,8 +1608,8 @@ export namespace JSON {
      * @param key - The key to check
      * @returns true if the key exists
      */
-    @inline has(key: string): bool {
-      return this.buildIndex().has(key);
+    has(key: string): bool {
+      return this.indexOf(key) >= 0;
     }
 
     /**
@@ -1062,34 +1618,53 @@ export namespace JSON {
      * @returns true if the key was found and deleted
      */
     delete(key: string): bool {
-      const idx = this.buildIndex();
-      if (!idx.has(key)) return false;
-      const removed = idx.get(key);
+      const removed = this.indexOf(key);
+      if (removed < 0) return false;
       const keys = this.keys();
-      const vals = this._vals;
+      const oldVals = this._vals;
+      const n = this._vused;
       this._kbuf = EMPTY_KEYS;
       this._kused = 0;
-      const newVals = new Array<JSON.Value>();
-      for (let j = 0; j < keys.length; j++) {
+      this._kpos = EMPTY_I32S;
+      this._vals = EMPTY_VALS;
+      this._vused = 0;
+      for (let j = 0; j < n; j++) {
         if (j == removed) continue;
         const k = unchecked(keys[j]);
         this.pushKeyBytes(
           changetype<usize>(k),
           changetype<usize>(k) + ((<usize>k.length) << 1),
+          this._vused,
         );
-        newVals.push(unchecked(vals[j]));
+        this.pushValSlot(unchecked(oldVals[j]));
       }
-      this._vals = newVals;
       this._index = null;
+      this._indexMask = 0;
       return true;
     }
 
+    /**
+     * Removes all entries. Backing key/value buffer capacity is kept so a
+     * subsequent parse or insert reuses it without re-allocating - this is what
+     * makes `JSON.parse<JSON.Obj>(data, out)` allocation-light. `__visit` only
+     * traces `[0, _vused)`, so resetting the used counters drops the old slots
+     * from GC tracing safely.
+     */
+    clear(): void {
+      this._kused = 0;
+      this._kpos = EMPTY_I32S;
+      this._vused = 0;
+      this._src = "";
+      this._index = null;
+      this._indexMask = 0;
+    }
+
     /**
      * Gets all keys in the object.
      * @returns Array of string keys (in insertion order)
      */
     keys(): string[] {
-      const out = new Array<string>(this._vals.length);
+      const out = new Array<string>(this._vused);
       const buf = changetype<usize>(this._kbuf);
       const used = this._kused;
       let pos = 0;
@@ -1106,15 +1681,29 @@ export namespace JSON {
      * Gets all values in the object.
      * @returns Array of JSON.Value instances (in insertion order)
      */
-    @inline values(): JSON.Value[] {
-      return this._vals.slice();
+    values(): JSON.Value[] {
+      const n = this._vused;
+      const out = new Array<JSON.Value>(n);
+      const base = changetype<usize>(this._src);
+      const srcEnd = this.srcEnd();
+      for (let i = 0; i < n; i++) {
+        const slot = unchecked(this._vals[i]);
+        if (JSON.Value.slotIsLazy(slot)) {
+          const start = JSON.Value.slotPtr(slot, base);
+          const end = JSON.Value.slotEnd(slot, base, srcEnd);
+          unchecked((out[i] = JSON.Value.fromSlice(start, end, this._src)));
+        } else {
+          unchecked((out[i] = JSON.Value.fromBits(slot)));
+        }
+      }
+      return out;
     }
 
     /**
      * Serializes the object to a JSON string.
      * @returns JSON string representation
      */
-    @inline toString(): string {
+    toString(): string {
       return JSON.stringify(this);
     }
 
@@ -1147,6 +1736,537 @@ export namespace JSON {
       }
       return parsed.get<JSON.Obj>();
     }
+
+
+    @unsafe private __visit(cookie: u32): void {
+      __visit(changetype<usize>(this._kbuf), cookie);
+      __visit(changetype<usize>(this._kpos), cookie);
+      __visit(changetype<usize>(this._vals), cookie);
+      __visit(changetype<usize>(this._src), cookie);
+      __visit(changetype<usize>(this._index), cookie); // null-safe in rt
+      const vals = this._vals;
+      const n = this._vused;
+      for (let i = 0; i < n; i++) {
+        const w = unchecked(vals[i]);
+        if (!valBoxed(w)) continue; // raw f64, no reference
+        const tag = valTag(w);
+        if (tag == JSON.Types.Lazy) continue; // interior _src pointer
+        if (tag >= JSON.Types.String) {
+          __visit(valPtr(w), cookie);
+        } else if (
+          (tag == JSON.Types.U64 || tag == JSON.Types.I64) &&
+          w & VAL_BOX64
+        ) {
+          __visit(valPtr(w), cookie); // heap-spilled 64-bit int
+        }
+      }
+    }
+  }
+
+  /**
+   * Dynamic JSON array with JSON.Value elements, backed by the same flat
+   * NaN-boxed u64 slot buffer as JSON.Obj (no per-element JSON.Value objects).
+   * Deferred string/array/object elements are parsed on first access; untouched
+   * elements serialize straight from their source bytes.
+   *
+   * Index with `arr.at(i)` (returns a JSON.Value) or read typed via `getAs<T>(i)`.
+   *
+   * @example
+   * ```typescript
+   * const arr = JSON.parse<JSON.Arr>('[1,"two",[3,4]]');
+   * arr.at(0).get<f64>();           // 1
+   * arr.getAs<string>(1);           // "two"
+   * arr.getAs<JSON.Arr>(2).at(0);   // 3
+   * ```
+   */
+  @final export class Arr {
+    // Same flat slot model as JSON.Obj, without the key buffer. See JSON.Obj for
+    // the slot encoding, the custom `__visit`, and the `__link` write barrier.
+    _vals: StaticArray<u64> = EMPTY_VALS;
+    _vused: i32 = 0;
+    /** Source string the lazy slot pointers index into; anchors it for GC. */
+    _src: string = "";
+
+    constructor() {}
+
+    /** Number of elements. */
+    get length(): i32 {
+      return this._vused;
+    }
+
+    /**
+     * Removes all elements, keeping the value-slot buffer capacity so a
+     * subsequent parse or push reuses it - powers `JSON.parse<JSON.Arr>(data,
+     * out)`. `__visit` only traces `[0, _vused)`, so this is GC-safe.
+     */
+    clear(): void {
+      this._vused = 0;
+      this._src = "";
+    }
+
+    /** Grows the value-slot buffer to hold at least `need` slots. */
+    private ensureValCap(need: i32): void {
+      const cap = this._vals.length;
+      if (cap >= need) return;
+      let n = cap ? cap : 8;
+      while (n < need) n <<= 1;
+      const nb = new StaticArray<u64>(n);
+      if (this._vused)
+        memory.copy(
+          changetype<usize>(nb),
+          changetype<usize>(this._vals),
+          (<usize>this._vused) << 3,
+        );
+      this._vals = nb;
+    }
+
+    /** Writes a slot and, if it carries a managed pointer, links it for the GC. */
+    private storeSlot(i: i32, bits: u64): void {
+      unchecked((this._vals[i] = bits));
+      if (valBoxed(bits)) {
+        const tag = valTag(bits);
+        if (
+          tag != JSON.Types.Lazy &&
+          (tag >= JSON.Types.String ||
+            ((tag == JSON.Types.U64 || tag == JSON.Types.I64) &&
+              bits & VAL_BOX64))
+        ) {
+          __link(changetype<usize>(this), valPtr(bits), false);
+        }
+      }
+    }
+
+    /** Appends a value slot (raw NaN-boxed bits). Deserializer entry point. */
+    pushRawSlot(bits: u64): void {
+      const pos = this._vused;
+      this.ensureValCap(pos + 1);
+      this._vused = pos + 1;
+      this.storeSlot(pos, bits);
+    }
+
+    /** End pointer of the source buffer (upper bound for scanning a lazy slot). */
+    private srcEnd(): usize {
+      return changetype<usize>(this._src) + ((<usize>this._src.length) << 1);
+    }
+
+    /** Parses a lazy slot in place, caching the concrete box, and returns it. */
+    private materializeSlot(i: i32): u64 {
+      const slot = unchecked(this._vals[i]);
+      if (!JSON.Value.slotIsLazy(slot)) return slot;
+      const base = changetype<usize>(this._src);
+      const start = JSON.Value.slotPtr(slot, base);
+      const end = JSON.Value.slotEnd(slot, base, this.srcEnd());
+      const bits = JSON.Value.parseSliceBits(start, end, this._src);
+      this.storeSlot(i, bits);
+      return bits;
+    }
+
+    /** Element access as a JSON.Value: `arr.at(i)`. */
+    at(index: i32): JSON.Value {
+      if (<u32>index >= <u32>this._vused) throw new Error("Index out of range");
+      const slot = unchecked(this._vals[index]);
+      if (JSON.Value.slotIsLazy(slot)) {
+        const base = changetype<usize>(this._src);
+        const start = JSON.Value.slotPtr(slot, base);
+        const end = JSON.Value.slotEnd(slot, base, this.srcEnd());
+        return JSON.Value.fromSlice(start, end, this._src);
+      }
+      return JSON.Value.fromBits(slot);
+    }
+
+    /**
+     * Reads element `i` directly as `T`, with no intermediate JSON.Value
+     * allocation. A deferred slot is parsed (and cached) on first access.
+     * @param i - element index
+     */
+    getAs<T>(i: i32): T {
+      let slot = unchecked(this._vals[i]);
+      if (JSON.Value.slotIsLazy(slot)) slot = this.materializeSlot(i);
+      return JSON.Value.decodeBits<T>(slot);
+    }
+
+    /** Appends a value (any T), eagerly boxed into a slot. */
+    push<T>(value: T): void {
+      this.pushRawSlot(JSON.Value.bitsFrom<T>(value));
+    }
+
+    /** Overwrites element `i`. */
+    set<T>(i: i32, value: T): void {
+      this.storeSlot(i, JSON.Value.bitsFrom<T>(value));
+    }
+
+    /**
+     * Bounds-checked element access via `arr[i]` - returns a `JSON.Value`
+     * (allocating), mirroring `at(i)`. For an allocation-free typed read use
+     * `getAs<T>(i)`.
+     */
+    @operator("[]") private __get(index: i32): JSON.Value {
+      return this.at(index);
+    }
+
+    /** Element assignment via `arr[i] = value` (any `JSON.Value`). */
+    @operator("[]=") private __set(index: i32, value: JSON.Value): void {
+      this.set<JSON.Value>(index, value);
+    }
+
+    /** Serializes the array to a JSON string. */
+    toString(): string {
+      return JSON.stringify(this);
+    }
+
+    /** Creates a JSON.Arr from a JSON.Value[] (or returns an existing one). */
+    static from<T>(value: T): JSON.Arr {
+      if (value instanceof JSON.Arr) return value;
+      // @ts-expect-error: handled by the isArray guard below
+      if (isArray<T>() && idof<valueof<T>>() == idof<JSON.Value>()) {
+        const out = new JSON.Arr();
+        // @ts-expect-error: T is JSON.Value[] here
+        const arr = changetype<JSON.Value[]>(value);
+        for (let i = 0; i < arr.length; i++) {
+          out.pushRawSlot(JSON.Value.bitsFrom<JSON.Value>(unchecked(arr[i])));
+        }
+        return out;
+      }
+      throw new Error("JSON.Arr.from expects a JSON.Value[]");
+    }
+
+    // ---- Array-like API: slot-optimized ports of the AssemblyScript stdlib ----
+    // Slot-shuffling ops (reverse/fill/copyWithin/pop/shift/unshift/slice/splice)
+    // move the raw u64 slots directly - no per-element JSON.Value - and keep any
+    // managed pointers linked to the same owner. New single-source results share
+    // `_src`, so copied deferred ranges stay lazy. Callbacks get a JSON.Value view
+    // of each element via `at(i)`.
+
+    /** Concrete, source-independent bits for slot `i` (resolves a deferred slot
+     *  without caching it back into this array - used by cross-source ops). */
+    private resolvedBits(i: i32): u64 {
+      const slot = unchecked(this._vals[i]);
+      if (!JSON.Value.slotIsLazy(slot)) return slot;
+      const base = changetype<usize>(this._src);
+      const start = JSON.Value.slotPtr(slot, base);
+      const end = JSON.Value.slotEnd(slot, base, this.srcEnd());
+      return JSON.Value.parseSliceBits(start, end, this._src);
+    }
+
+    /** Appends `count` raw slots from `this[from..]` into a fresh `dst`, sharing
+     *  `_src` so copied deferred ranges still resolve. */
+    private copyInto(dst: JSON.Arr, from: i32, count: i32): void {
+      if (count <= 0) return;
+      dst._src = this._src;
+      const at = dst._vused;
+      dst.ensureValCap(at + count);
+      for (let k = 0; k < count; k++)
+        dst.storeSlot(at + k, unchecked(this._vals[from + k]));
+      dst._vused = at + count;
+    }
+
+    /** Truncates (drops the tail) or extends (pads with `null`) the array. */
+    set length(newLength: i32) {
+      if (newLength < 0) throw new Error("Invalid array length");
+      const used = this._vused;
+      if (newLength <= used) {
+        this._vused = newLength;
+        return;
+      }
+      this.ensureValCap(newLength);
+      for (let i = used; i < newLength; i++)
+        unchecked((this._vals[i] = JSON.Value.nullBits()));
+      this._vused = newLength;
+    }
+
+    /** Removes and returns the last element. */
+    pop(): JSON.Value {
+      const n = this._vused;
+      if (n == 0) throw new Error("pop from empty JSON.Arr");
+      const v = this.at(n - 1);
+      this._vused = n - 1;
+      return v;
+    }
+
+    /** Removes and returns the first element, shifting the rest down. */
+    shift(): JSON.Value {
+      const n = this._vused;
+      if (n == 0) throw new Error("shift from empty JSON.Arr");
+      const v = this.at(0);
+      const base = changetype<usize>(this._vals);
+      memory.copy(base, base + 8, (<usize>(n - 1)) << 3);
+      this._vused = n - 1;
+      return v;
+    }
+
+    /** Prepends `value`, shifting existing elements up. Returns the new length. */
+    unshift<T>(value: T): i32 {
+      const n = this._vused;
+      this.ensureValCap(n + 1);
+      const base = changetype<usize>(this._vals);
+      if (n) memory.copy(base + 8, base, (<usize>n) << 3);
+      this._vused = n + 1;
+      this.storeSlot(0, JSON.Value.bitsFrom<T>(value));
+      return n + 1;
+    }
+
+    /** Reverses the elements in place (slot swap). */
+    reverse(): JSON.Arr {
+      const vals = this._vals;
+      let lo = 0;
+      let hi = this._vused - 1;
+      while (lo < hi) {
+        const t = unchecked(vals[lo]);
+        unchecked((vals[lo] = unchecked(vals[hi])));
+        unchecked((vals[hi] = t));
+        lo++;
+        hi--;
+      }
+      return this;
+    }
+
+    /** Fills `[start, end)` with `value`. */
+    fill<T>(value: T, start: i32 = 0, end: i32 = i32.MAX_VALUE): JSON.Arr {
+      const n = this._vused;
+      let s = start < 0 ? max(n + start, 0) : min(start, n);
+      const e = end < 0 ? max(n + end, 0) : min(end, n);
+      const bits = JSON.Value.bitsFrom<T>(value);
+      for (; s < e; s++) this.storeSlot(s, bits);
+      return this;
+    }
+
+    /** Copies the slot block `[start, end)` to `target`, in place. */
+    copyWithin(target: i32, start: i32, end: i32 = i32.MAX_VALUE): JSON.Arr {
+      const n = this._vused;
+      const t = target < 0 ? max(n + target, 0) : min(target, n);
+      const s = start < 0 ? max(n + start, 0) : min(start, n);
+      const e = end < 0 ? max(n + end, 0) : min(end, n);
+      const count = min(e - s, n - t);
+      if (count > 0) {
+        const base = changetype<usize>(this._vals);
+        memory.copy(
+          base + ((<usize>t) << 3),
+          base + ((<usize>s) << 3),
+          (<usize>count) << 3,
+        );
+      }
+      return this;
+    }
+
+    /** Returns a new JSON.Arr with the elements in `[start, end)` (lazy-preserving). */
+    slice(start: i32 = 0, end: i32 = i32.MAX_VALUE): JSON.Arr {
+      const n = this._vused;
+      const s = start < 0 ? max(n + start, 0) : min(start, n);
+      const e = end < 0 ? max(n + end, 0) : min(end, n);
+      const out = new JSON.Arr();
+      this.copyInto(out, s, e - s);
+      return out;
+    }
+
+    /** Removes `deleteCount` elements at `start`; returns them as a new JSON.Arr. */
+    splice(start: i32, deleteCount: i32 = i32.MAX_VALUE): JSON.Arr {
+      const n = this._vused;
+      const s = start < 0 ? max(n + start, 0) : min(start, n);
+      const d = max(min(deleteCount, n - s), 0);
+      const removed = new JSON.Arr();
+      this.copyInto(removed, s, d);
+      const tail = n - (s + d);
+      if (tail > 0) {
+        const base = changetype<usize>(this._vals);
+        memory.copy(
+          base + ((<usize>s) << 3),
+          base + ((<usize>(s + d)) << 3),
+          (<usize>tail) << 3,
+        );
+      }
+      this._vused = n - d;
+      return removed;
+    }
+
+    /** Returns a new JSON.Arr = this followed by `other` (resolves deferred slots
+     *  since the two sources can't share one `_src`). */
+    concat(other: JSON.Arr): JSON.Arr {
+      const out = new JSON.Arr();
+      const a = this._vused;
+      const b = other._vused;
+      out.ensureValCap(a + b);
+      for (let i = 0; i < a; i++) out.pushRawSlot(this.resolvedBits(i));
+      for (let i = 0; i < b; i++) out.pushRawSlot(other.resolvedBits(i));
+      return out;
+    }
+
+    /** First index of `value` (typed compare via getAs<T>), or -1. */
+    indexOf<T>(value: T, fromIndex: i32 = 0): i32 {
+      const n = this._vused;
+      let i = fromIndex < 0 ? max(n + fromIndex, 0) : fromIndex;
+      for (; i < n; i++) if (this.getAs<T>(i) == value) return i;
+      return -1;
+    }
+
+    /** Last index of `value`, searching backwards, or -1. */
+    lastIndexOf<T>(value: T, fromIndex: i32 = i32.MAX_VALUE): i32 {
+      const n = this._vused;
+      let i = fromIndex < 0 ? n + fromIndex : min(fromIndex, n - 1);
+      for (; i >= 0; i--) if (this.getAs<T>(i) == value) return i;
+      return -1;
+    }
+
+    /** Whether `value` is present. */
+    includes<T>(value: T, fromIndex: i32 = 0): bool {
+      return this.indexOf<T>(value, fromIndex) >= 0;
+    }
+
+    /** Calls `fn` for each element. */
+    forEach(
+      fn: (value: JSON.Value, index: i32, array: JSON.Arr) => void,
+    ): void {
+      for (let i = 0, n = this._vused; i < n; i++) fn(this.at(i), i, this);
+    }
+
+    /** New JSON.Arr of `fn`'s results. */
+    map(
+      fn: (value: JSON.Value, index: i32, array: JSON.Arr) => JSON.Value,
+    ): JSON.Arr {
+      const n = this._vused;
+      const out = new JSON.Arr();
+      out.ensureValCap(n);
+      for (let i = 0; i < n; i++) out.push<JSON.Value>(fn(this.at(i), i, this));
+      return out;
+    }
+
+    /** New JSON.Arr of elements passing `fn` (lazy-preserving). */
+    filter(
+      fn: (value: JSON.Value, index: i32, array: JSON.Arr) => bool,
+    ): JSON.Arr {
+      const out = new JSON.Arr();
+      for (let i = 0, n = this._vused; i < n; i++)
+        if (fn(this.at(i), i, this)) this.copyInto(out, i, 1);
+      return out;
+    }
+
+    /** First element passing `fn`, or `null`. */
+    find(
+      fn: (value: JSON.Value, index: i32, array: JSON.Arr) => bool,
+    ): JSON.Value | null {
+      for (let i = 0, n = this._vused; i < n; i++) {
+        const v = this.at(i);
+        if (fn(v, i, this)) return v;
+      }
+      return null;
+    }
+
+    /** Index of the first element passing `fn`, or -1. */
+    findIndex(
+      fn: (value: JSON.Value, index: i32, array: JSON.Arr) => bool,
+    ): i32 {
+      for (let i = 0, n = this._vused; i < n; i++)
+        if (fn(this.at(i), i, this)) return i;
+      return -1;
+    }
+
+    /** Last element passing `fn`, or `null`. */
+    findLast(
+      fn: (value: JSON.Value, index: i32, array: JSON.Arr) => bool,
+    ): JSON.Value | null {
+      for (let i = this._vused - 1; i >= 0; i--) {
+        const v = this.at(i);
+        if (fn(v, i, this)) return v;
+      }
+      return null;
+    }
+
+    /** Index of the last element passing `fn`, or -1. */
+    findLastIndex(
+      fn: (value: JSON.Value, index: i32, array: JSON.Arr) => bool,
+    ): i32 {
+      for (let i = this._vused - 1; i >= 0; i--)
+        if (fn(this.at(i), i, this)) return i;
+      return -1;
+    }
+
+    /** Whether every element passes `fn`. */
+    every(fn: (value: JSON.Value, index: i32, array: JSON.Arr) => bool): bool {
+      for (let i = 0, n = this._vused; i < n; i++)
+        if (!fn(this.at(i), i, this)) return false;
+      return true;
+    }
+
+    /** Whether any element passes `fn`. */
+    some(fn: (value: JSON.Value, index: i32, array: JSON.Arr) => bool): bool {
+      for (let i = 0, n = this._vused; i < n; i++)
+        if (fn(this.at(i), i, this)) return true;
+      return false;
+    }
+
+    /** Left fold. */
+    reduce<U>(
+      fn: (acc: U, value: JSON.Value, index: i32, array: JSON.Arr) => U,
+      initialValue: U,
+    ): U {
+      let acc = initialValue;
+      for (let i = 0, n = this._vused; i < n; i++)
+        acc = fn(acc, this.at(i), i, this);
+      return acc;
+    }
+
+    /** Right fold. */
+    reduceRight<U>(
+      fn: (acc: U, value: JSON.Value, index: i32, array: JSON.Arr) => U,
+      initialValue: U,
+    ): U {
+      let acc = initialValue;
+      for (let i = this._vused - 1; i >= 0; i--)
+        acc = fn(acc, this.at(i), i, this);
+      return acc;
+    }
+
+    /** Sorts in place by `comparator(a, b)` (materializes for comparison). */
+    sort(comparator: (a: JSON.Value, b: JSON.Value) => i32): JSON.Arr {
+      const n = this._vused;
+      if (n < 2) return this;
+      const view = new Array<JSON.Value>(n);
+      for (let i = 0; i < n; i++) unchecked((view[i] = this.at(i)));
+      view.sort(comparator);
+      for (let i = 0; i < n; i++)
+        this.storeSlot(i, JSON.Value.bitsFrom<JSON.Value>(unchecked(view[i])));
+      return this;
+    }
+
+    /** JS-parity element string: strings unquoted, null -> "", everything else
+     *  via ES-exact JSON (numbers drop a trailing `.0`). */
+    private elemStr(i: i32): string {
+      const v = this.at(i);
+      const t = v.type;
+      if (t == JSON.Types.String) return v.get<string>();
+      if (t == JSON.Types.Null) return "";
+      return JSON.stringify(v);
+    }
+
+    /** Joins the elements with `separator` (JS `Array#join` semantics). */
+    join(separator: string = ","): string {
+      const n = this._vused;
+      if (n == 0) return "";
+      let out = this.elemStr(0);
+      for (let i = 1; i < n; i++) out += separator + this.elemStr(i);
+      return out;
+    }
+
+    // See JSON.Obj.__visit - same custom GC visitor for the slot buffer.
+    @unsafe private __visit(cookie: u32): void {
+      __visit(changetype<usize>(this._vals), cookie);
+      __visit(changetype<usize>(this._src), cookie);
+      const vals = this._vals;
+      const n = this._vused;
+      for (let i = 0; i < n; i++) {
+        const w = unchecked(vals[i]);
+        if (!valBoxed(w)) continue;
+        const tag = valTag(w);
+        if (tag == JSON.Types.Lazy) continue;
+        if (tag >= JSON.Types.String) {
+          __visit(valPtr(w), cookie);
+        } else if (
+          (tag == JSON.Types.U64 || tag == JSON.Types.I64) &&
+          w & VAL_BOX64
+        ) {
+          __visit(valPtr(w), cookie);
+        }
+      }
+    }
   }
   /**
    * Box for primitive types
@@ -1161,7 +2281,7 @@ export namespace JSON {
      * @param value T
      * @returns this
      */
-    @inline set(value: T): Box<T> {
+    set(value: T): Box<T> {
       this.value = value;
       return this;
     }
@@ -1176,7 +2296,7 @@ export namespace JSON {
      * @param from T
      * @returns Box<T> | null
      */
-    @inline static fromValue<T>(value: JSON.Value): Box<T> | null {
+    static fromValue<T>(value: JSON.Value): Box<T> | null {
       if (!(value instanceof JSON.Value))
         throw new Error("value must be of type JSON.Value");
       if (value.type === JSON.Types.Null) return null;
@@ -1195,7 +2315,7 @@ export namespace JSON {
      * @param from T
      * @returns Box<T>
      */
-    @inline static from<T>(value: T): Box<T> {
+    static from<T>(value: T): Box<T> {
       return new Box(value);
     }
     toString(): string {
@@ -1260,7 +2380,7 @@ export namespace JSON {
   function __deserialize<T>(srcStart: usize, srcEnd: usize, dst: usize = 0): T {
     // Skip leading whitespace once here so every handler below may assume
     // srcStart is at the first non-whitespace char. (Trailing whitespace is
-    // left intact — composites self-trim and JSON.Raw preserves it.)
+    // left intact - composites self-trim and JSON.Raw preserves it.)
     while (srcStart < srcEnd && JSON.Util.isSpace(load<u16>(srcStart)))
       srcStart += 2;
     if (isBoolean<T>()) {
@@ -1272,6 +2392,17 @@ export namespace JSON {
         : deserializeUnsigned<T>(srcStart, srcEnd);
     } else if (isFloat<T>()) {
       return deserializeFloat<T>(srcStart, srcEnd);
+    } else if (
+      isNullable<T>() &&
+      srcEnd - srcStart == 8 &&
+      load<u64>(srcStart) == NULL_WORD_U64
+    ) {
+      // A `null` literal must be matched before the string branch: a nullable
+      // string (`string | null`) reports `isString<T>() == true`, so without
+      // this `null` would be (mis)handled as a quoted string and abort. Mirrors
+      // the same-ordered check in `parseInternal`. Reached by lazy-field
+      // materialization, which routes every slot value through `__deserialize`.
+      return null;
     } else if (isString<T>()) {
       if (srcEnd - srcStart < 4)
         throw new Error(
@@ -1279,12 +2410,6 @@ export namespace JSON {
         );
 
       return deserializeString(srcStart, srcEnd) as T;
-    } else if (
-      isNullable<T>() &&
-      srcEnd - srcStart == 8 &&
-      load<u64>(srcStart) == NULL_WORD_U64
-    ) {
-      return null;
     } else {
       let type: nonnull<T> = changetype<nonnull<T>>(0);
       // @ts-expect-error: Defined by transform
@@ -1323,10 +2448,10 @@ export namespace JSON {
       }
       if (type instanceof StaticArray) {
         // @ts-expect-error: type
-        return deserializeStaticArray<T>(srcStart, srcEnd, dst);
+        return deserializeStaticArray<nonnull<T>>(srcStart, srcEnd, dst) as T;
       } else if (type instanceof Array) {
         // @ts-expect-error: type
-        return deserializeArray<T>(srcStart, srcEnd, dst);
+        return deserializeArray<nonnull<T>>(srcStart, srcEnd, dst) as T;
       } else if (
         type instanceof Int8Array ||
         type instanceof Uint8Array ||
@@ -1361,6 +2486,9 @@ export namespace JSON {
       } else if (type instanceof JSON.Obj) {
         // @ts-expect-error: type
         return deserializeObject(srcStart, srcEnd, 0);
+      } else if (type instanceof JSON.Arr) {
+        // @ts-expect-error: type
+        return deserializeJsonArray(srcStart, srcEnd, 0);
       } else if (type instanceof JSON.Box) {
         // @ts-expect-error: type
         return new JSON.Box(
@@ -1381,21 +2509,15 @@ export namespace JSON {
     );
   }
   export namespace Util {
-    // @ts-expect-error: decorator
-    @inline export function isSpace(code: u16): boolean {
+    export function isSpace(code: u16): boolean {
       return code == 0x20 || code - 9 <= 4;
     }
     /** Advance past JSON whitespace (space, tab, LF, VT, FF, CR). */
-    // @ts-expect-error: decorator
-    @inline export function skipWhitespace(
-      srcStart: usize,
-      srcEnd: usize,
-    ): usize {
+    export function skipWhitespace(srcStart: usize, srcEnd: usize): usize {
       while (srcStart < srcEnd && isSpace(load<u16>(srcStart))) srcStart += 2;
       return srcStart;
     }
-    // @ts-expect-error: decorator
-    @inline function scanQuotedValueEnd(srcStart: usize, srcEnd: usize): usize {
+    function scanQuotedValueEnd(srcStart: usize, srcEnd: usize): usize {
       const endQuote = scanStringEnd(srcStart, srcEnd);
       return endQuote >= srcEnd ? 0 : endQuote + 2;
     }
@@ -1433,8 +2555,7 @@ export namespace JSON {
 
       return srcStart;
     }
-    // @ts-expect-error: decorator
-    @inline export function scanValueEnd<T = JSON.Value>(
+    export function scanValueEnd<T = JSON.Value>(
       srcStart: usize,
       srcEnd: usize,
     ): usize {
@@ -1461,8 +2582,7 @@ export namespace JSON {
         return scanCompositeValueEnd(ptr, srcEnd);
       return scanScalarValueEnd(ptr, srcEnd);
     }
-    // @ts-expect-error: decorator
-    @inline export function ptrToStr(start: usize, end: usize): string {
+    export function ptrToStr(start: usize, end: usize): string {
       const size = end - start;
       const out = __new(size, idof<string>());
       memory.copy(out, start, size);
@@ -1499,8 +2619,7 @@ export namespace JSON {
      * @param data - string
      * @returns - T
      */
-    // @ts-expect-error: inline
-    @inline export function parse<T>(data: string): T {
+    export function parse<T>(data: string): T {
       bs.saveState();
       const result = JSON.parse<T>(data);
       bs.loadState();
@@ -1515,8 +2634,7 @@ export namespace JSON {
  * and `Date` fast paths are handled by the callers (which have buffer-reuse
  * optimizations); everything else routes here so the dispatch chain lives once.
  */
-// @ts-expect-error: @inline is a valid decorator
-@inline function serializeReference<T>(data: T): void {
+function serializeReference<T>(data: T): void {
   if (data instanceof Array) {
     // @ts-expect-error
     serializeArray(changetype<nonnull<T>>(data));
@@ -1563,6 +2681,8 @@ export namespace JSON {
     serializeArbitrary(data);
   } else if (data instanceof JSON.Obj) {
     serializeObject(data);
+  } else if (data instanceof JSON.Arr) {
+    serializeJsonArray(data);
   } else if (data instanceof JSON.Box) {
     JSON.__serialize(data.value);
   } else {
@@ -1580,12 +2700,11 @@ export enum JSONMode {
   NAIVE = 2,
 }
 
-// @ts-expect-error: decorator
-@inline function parseBox<T>(data: string, ty: T): T {
+function parseBox<T>(data: string, ty: T): T {
   return JSON.parse<T>(data);
 }
-// @ts-expect-error: inline
-@inline function deserializeBox<T>(
+
+function deserializeBox<T>(
   srcStart: usize,
   srcEnd: usize,
   dst: usize,
@@ -1594,16 +2713,13 @@ export enum JSONMode {
   return JSON.__deserialize<T>(srcStart, srcEnd, dst);
 }
 
-// @ts-expect-error: inline
-@inline export function toRaw(data: string): JSON.Raw {
+export function toRaw(data: string): JSON.Raw {
   return new JSON.Raw(data);
 }
-// @ts-expect-error: inline
-@inline export function fromRaw(data: JSON.Raw): string {
+export function fromRaw(data: JSON.Raw): string {
   return data.data;
 }
 
-// @ts-expect-error: inline
-@inline export function toBox<T>(data: T): JSON.Box<T> {
+export function toBox<T>(data: T): JSON.Box<T> {
   return new JSON.Box<T>(data);
 }