wscodec 0.1.0 → 0.3.0

package/primitives.mjs

@@ -1,15 +1,28 @@
 /**
- * FName and FGuid.
+ * FName and FGuid: the two pervasive identifier types in UE serialization.
  *
- * In this Soulmask format FName is serialized as a plain FString (no
- * trailing FName.Number int32). The `number` field stays 0 and exists
- * only for symmetry with full UE FNames.
+ * Soulmask's quirk for FName: the property-stream wire form is a plain
+ * FString (no trailing FName.Number int32). Stock UE 4.27 serializes FName
+ * inside a property tag as FString + int32 Number; Soulmask drops the int32
+ * everywhere except the OUTERMOST None terminator (which still carries a
+ * 4-byte FName.Number = 0 trailer, handled by the property-stream reader).
+ *
+ * `FName.read` / instance `write` therefore use the Soulmask form (bare
+ * FString). The full UE form is exposed separately as `FName.readWithNumber`
+ * / instance `writeWithNumber`: not used by Soulmask today, but wired up so
+ * the codec can speak the standard wire format if the game's serializer ever
+ * adopts it.
  */
 
+const ZERO_GUID = '00000000-0000-0000-0000-000000000000';
+
 export class FName {
   constructor(value, { isUnicode = false, number = 0, isNull = false } = {}) {
     this.value = value;
     this.isUnicode = isUnicode;
+    // FName.Number: zero in every observed Soulmask FName (the wire form
+    // omits it). Preserved on the instance for round-trip when the full UE
+    // form is used via readWithNumber/writeWithNumber.
     this.number = number;
     // Tracks the wire-form distinction between an FString with SaveNum=0
     // (the "null" form) and SaveNum=1 (empty-with-terminator). Only ever
@@ -18,15 +31,39 @@ export class FName {
     this.isNull = isNull;
   }
   toString() { return this.value; }
+  /** JSON-friendly form: the bare name string (drops isUnicode/number/isNull metadata). */
+  toJSON() { return this.value; }
 
+  /**
+   * Read an FName in the Soulmask property-stream form: a bare FString,
+   * no trailing FName.Number. `number` is left at 0.
+   */
   static read(cursor) {
     const s = cursor.readFString();
     return new FName(s.value, { isUnicode: s.isUnicode, isNull: !!s.isNull });
   }
 
+  /** Write the Soulmask form (FString only). */
   write(writer) { writer.writeFString(this.value, this.isUnicode, this.isNull); }
 
-  /** Accepts an FName, a bare string, or a plain {value,isUnicode,isNull} record. */
+  /**
+   * Read an FName in the stock UE 4.27 property-tag form: FString + int32
+   * Number. Use this if you're decoding a non-Soulmask stream or a future
+   * Soulmask wire format that re-adopts the int32 suffix.
+   */
+  static readWithNumber(cursor) {
+    const s = cursor.readFString();
+    const number = cursor.readInt32();
+    return new FName(s.value, { isUnicode: s.isUnicode, isNull: !!s.isNull, number });
+  }
+
+  /** Write the stock UE form (FString + int32 Number). */
+  writeWithNumber(writer) {
+    writer.writeFString(this.value, this.isUnicode, this.isNull);
+    writer.writeInt32(this.number | 0);
+  }
+
+  /** Accepts an FName, a bare string, or a plain {value,isUnicode,isNull,number} record. */
   static from(x) {
     if (x instanceof FName) return x;
     if (typeof x === 'string') return new FName(x);
@@ -46,6 +83,31 @@ export class FGuid {
   constructor(value) { this.value = value; }
   toString() { return this.value; }
 
+  /**
+   * JSON-friendly form: the bare GUID string, so `JSON.stringify(fguid)`
+   * yields `"AABBCCDD-..."` rather than `{"value":"AABBCCDD-..."}`.
+   */
+  toJSON() { return this.value; }
+
+  /**
+   * Structural equality. Case-insensitive: an FGuid constructed from a
+   * lowercase string compares equal to one read off the wire (uppercase).
+   * Accepts an FGuid or a string; anything else returns false.
+   */
+  equals(other) {
+    const otherStr = other instanceof FGuid ? other.value
+                   : typeof other === 'string' ? other
+                   : null;
+    if (otherStr == null) return false;
+    return String(this.value).toUpperCase() === otherStr.toUpperCase();
+  }
+
+  /** True iff the GUID is all zeros (the conventional null-GUID sentinel). */
+  isZero() { return String(this.value).toUpperCase() === ZERO_GUID; }
+
+  /** All-zero FGuid sentinel. New instance per call (FGuid is mutable). */
+  static zero() { return new FGuid(ZERO_GUID); }
+
   static read(cursor) {
     const A = cursor.readUint32(), B = cursor.readUint32(), C = cursor.readUint32(), D = cursor.readUint32();
     const h = (n, w) => n.toString(16).padStart(w, '0').toUpperCase();
@@ -62,6 +124,7 @@ export class FGuid {
     writer.writeUint32(A); writer.writeUint32(B); writer.writeUint32(C); writer.writeUint32(D);
   }
 
+  /** Accepts an FGuid or a canonical 8-4-4-4-12 hex string. */
   static from(x) {
     if (x instanceof FGuid) return x;
     if (typeof x === 'string') return new FGuid(x);

package/properties.mjs

@@ -25,12 +25,13 @@
  * elements, embedded object data) do NOT.
  */
 
+import { Writer }                                             from './io.mjs';
 import { FName, FGuid }                                       from './primitives.mjs';
 import { StructValue, STRUCT_HANDLERS }                       from './structs.mjs';
 import { ObjectRef, SoftObjectRef, FTextValue, OpaqueValue }  from './values.mjs';
 
 // ==========================================================================
-// PropertyTag — the header preceding each property's value bytes.
+// PropertyTag: the header preceding each property's value bytes.
 // ==========================================================================
 export class PropertyTag {
   constructor(fields = {}) {
@@ -124,7 +125,7 @@ export class MapValue {
 }
 
 // ==========================================================================
-// Property — one tag + its decoded value.
+// Property: one tag + its decoded value.
 // ==========================================================================
 export class Property {
   constructor(tag, value, { sizeMismatch = null } = {}) {
@@ -137,7 +138,7 @@ export class Property {
 }
 
 // ==========================================================================
-// Value codec — dispatches on tag.type.value.
+// Value codec: dispatches on tag.type.value.
 //
 // sizeHint is the tag's Size field (bytes following the tag). Containers
 // (Array/Set/Map) and StructProperty use it as the byte budget for nested
@@ -163,7 +164,7 @@ export function readValue(cursor, tag, sizeHint) {
     case 'ClassProperty':
     case 'WeakObjectProperty':
     case 'LazyObjectProperty':
-    case 'WSObjectProperty':           // Soulmask-specific alias (per BLOB_FORMAT.md)
+    case 'WSObjectProperty':           // Soulmask alias for ObjectProperty (same wire layout, different tag name)
       return readObjectValue(cursor, sizeHint);
     case 'SoftObjectProperty':
     case 'SoftClassProperty':
@@ -207,7 +208,7 @@ export function readValue(cursor, tag, sizeHint) {
 }
 
 export function writeValue(writer, tag, value) {
-  // Decode may have fallen back to OpaqueValue for any property type —
+  // Decode may have fallen back to OpaqueValue for any property type:
   // Array/Set/Map/Struct/Text decode failures, unknown property types,
   // overshoot recoveries, etc. Emit the captured bytes verbatim so the
   // outer stream stays aligned regardless of which slot held the opaque.
@@ -279,7 +280,7 @@ function readFText(cursor, sizeHint) {
     if (historyType === 0) {
       // Base / localized: namespace + key + source string. Empty strings on
       // the wire may use either null-form (SaveNum=0) or empty-with-terminator
-      // (SaveNum=1) — capture `isNull` per-field so the writer reproduces the
+      // (SaveNum=1). Capture `isNull` per-field so the writer reproduces the
       // exact wire form.
       const nsFS  = cursor.readFString();
       const kFS   = cursor.readFString();
@@ -291,13 +292,42 @@ function readFText(cursor, sizeHint) {
         sourceString: ssFS.value, sourceStringIsNull: ssFS.isNull,
       });
     }
+    if (historyType === 1) {
+      // NamedFormat (FTextHistory_NamedFormat): a format-pattern FText plus a
+      // TMap<FString, FFormatArgumentValue>. Wire shape:
+      //   FText  SourceFmt
+      //   int32  NumArguments
+      //   for each: FString Key, int8 ContentType, value-by-type
+      // ContentType codes match historyType=2 (0=Int64 1=UInt64 2=Float32
+      // 3=Float64 4=Text 5=Gender). Soulmask uses this for named placeholders
+      // like "X={X} Y={Y} Z={Z}" in ParamArrayTxt elements of JingYingRiZhiList.
+      const sourceFmt = readFText(cursor, Infinity);
+      const numArgs = cursor.readInt32();
+      const args = [];
+      for (let i = 0; i < numArgs; i++) {
+        const keyFS = cursor.readFString();
+        const type = cursor.readInt8();
+        let value;
+        switch (type) {
+          case 0: value = cursor.readInt64().toString();  break;
+          case 1: value = cursor.readUint64().toString(); break;
+          case 2: value = cursor.readFloat32();           break;
+          case 3: value = cursor.readFloat64();           break;
+          case 4: value = readFText(cursor, Infinity);    break;
+          case 5: value = cursor.readInt8();              break;
+          default: throw new Error(`readFText: unknown NamedFormat ContentType ${type}`);
+        }
+        args.push({ key: keyFS.value, keyIsNull: keyFS.isNull, type, value });
+      }
+      return new FTextValue({ flags, historyType: 1, sourceFmt, arguments: args });
+    }
     if (historyType === 2) {
       // ArgumentFormat: a format-pattern FText plus an ordered argument list.
       // Each argument is a ContentType byte (EFormatArgumentType) followed by
       // the value for that type:
       //   0=Int(int64)  1=UInt(uint64)  2=Float(f32)  3=Double(f64)
       //   4=Text(FText, recursive)  5=Gender(int8)
-      // No argument names on the wire — arguments are positional ({0}, {1} …).
+      // No argument names on the wire; arguments are positional ({0}, {1} ...).
       const sourceFmt = readFText(cursor, Infinity);
       const numArgs = cursor.readInt32();
       const args = [];
@@ -328,7 +358,7 @@ function readFText(cursor, sizeHint) {
       // Inside FNumberFormattingOptions, AlwaysSign and UseGrouping are also
       // uint32 booleans. Only RoundingMode (int8) and the four digit-count
       // fields (int32) follow the modern sizes. This matches the actual wire
-      // bytes — empirically MaxIntDigits = ~324 (close to DBL_MAX_10_EXP+1
+      // bytes: empirically MaxIntDigits = ~324 (close to DBL_MAX_10_EXP+1
       // = 309) and MaxFracDigits = 3 (UE default) under this interpretation.
       const argType = cursor.readInt8();
       let argValue;
@@ -366,7 +396,7 @@ function readFText(cursor, sizeHint) {
     }
     // Unknown history type: preserve remaining bytes verbatim for round-trip.
     // When called from an array-element context sizeHint is Infinity because
-    // the per-element byte budget is unknown — throw so the callers can decide
+    // the per-element byte budget is unknown; throw so the callers can decide
     // whether to fall back to OpaqueValue at the element or array level.
     if (!isFinite(sizeHint)) throw new Error(`readFText: unimplemented historyType ${historyType} (no size budget; cannot store raw bytes)`);
     const remaining = sizeHint - (cursor.pos() - start);
@@ -393,6 +423,22 @@ function writeFText(writer, value) {
     writer.writeFString(value.namespace ?? '',    null, value._namespaceIsNull);
     writer.writeFString(value.key ?? '',          null, value._keyIsNull);
     writer.writeFString(value.sourceString ?? '', null, value._sourceStringIsNull);
+  } else if (value.historyType === 1) {
+    writeFText(writer, value.sourceFmt);
+    writer.writeInt32(value.arguments.length);
+    for (const arg of value.arguments) {
+      writer.writeFString(arg.key ?? '', null, arg.keyIsNull);
+      writer.writeInt8(arg.type);
+      switch (arg.type) {
+        case 0: writer.writeInt64(arg.value);   break;
+        case 1: writer.writeUint64(arg.value);  break;
+        case 2: writer.writeFloat32(arg.value); break;
+        case 3: writer.writeFloat64(arg.value); break;
+        case 4: writeFText(writer, arg.value);  break;
+        case 5: writer.writeInt8(arg.value);    break;
+        default: throw new Error(`writeFText: unknown NamedFormat ContentType ${arg.type}`);
+      }
+    }
   } else if (value.historyType === 2) {
     writeFText(writer, value.sourceFmt);
     writer.writeInt32(value.arguments.length);
@@ -420,7 +466,7 @@ function writeFText(writer, value) {
       case 5: writer.writeInt64(sv.value);   break;
       default: throw new Error(`writeFText: unknown FFormatArgumentValue type ${sv.type} in AsNumber`);
     }
-    // Legacy uint32 booleans — see readFText AsNumber for rationale.
+    // Legacy uint32 booleans (see readFText AsNumber for rationale).
     const hasFormatOptions = value.formatOptions != null;
     writer.writeUint32(hasFormatOptions ? 1 : 0);
     if (hasFormatOptions) {
@@ -459,7 +505,7 @@ function writeFText(writer, value) {
 // preserves the wire's choice between null-form (SaveNum=0, 4 bytes) and
 // empty-with-terminator (SaveNum=1 plus 1-byte NUL, 5 bytes). The previous
 // version always wrote `writeFString(this.path)` for ObjectRef and emitted
-// a 4-byte null FString even for kind-only values — silently inflating the
+// a 4-byte null FString even for kind-only values, silently inflating the
 // encoded blob by 4 B for every kind-only reference.
 function readObjectValue(cursor, sizeHint) {
   const start = cursor.pos();
@@ -471,7 +517,7 @@ function readObjectValue(cursor, sizeHint) {
     }
     // Soulmask kind=0x01 (hard actor reference, e.g. HBindBGCompActor on
     // NPC pawns) prepends a 4-byte field between the kind byte and the
-    // path FString. Observed value is always 1; semantic unknown — captured
+    // path FString. Observed value is always 1; semantic unknown. Captured
     // verbatim and replayed on write. Without this branch the reader treats
     // those four bytes as the path FString's SaveNum, which overshoots the
     // budget and falls back to OpaqueValue (the symptom that hid every
@@ -484,7 +530,7 @@ function readObjectValue(cursor, sizeHint) {
       }
     }
     const pathFS = cursor.readFString();
-    // Guard against path FStrings whose SaveNum overshoots the value budget —
+    // Guard against path FStrings whose SaveNum overshoots the value budget:
     // this happens for properties whose format differs from kind+path+... and
     // whose first "path" bytes happen to encode a huge length.
     if (cursor.pos() - start > sizeHint) throw new Error('path FString exceeded value budget');
@@ -593,19 +639,23 @@ function readArrayValue(cursor, tag, sizeHint) {
  * yuan-xing element is followed by a fixed-shape block:
  *
  *   [8 bytes zero header]
- *   [u32 stride=64] [u32 count]  [count×64 bytes]   world 4×4 transforms (per placed piece)
- *   [u32 stride= 4] [u32 count]  [count× 4 bytes]   per-piece u32 ids
- *   [u32 stride=64] [u32 count]  [count×64 bytes]   per-piece aux (bbox + scale-ish floats)
+ *   [u32 stride=64] [u32 count]  [count × 16 float32]   world 4×4 transforms (per placed piece)
+ *   [u32 stride= 4] [u32 count]  [count × u32]          per-piece u32 ids
+ *   [u32 stride=64] [u32 count]  [count × 16 float32]   per-piece aux (bbox + scale-ish floats)
  *
- * Returns { header, sections } on success. Returns null (cursor rolled back)
- * when the bytes don't match — non-JianZhuInstYuanXings ObjectProperty arrays
- * have no such block, so peeking-and-rolling-back keeps them unaffected.
+ * Returns { transforms, ids, aux } on success: arrays of decoded values
+ * (rather than raw byte slices). Returns null (cursor rolled back) when the
+ * bytes don't match. Non-JianZhuInstYuanXings ObjectProperty arrays have no
+ * such block, so peeking-and-rolling-back keeps them unaffected.
+ *
+ * The 8-byte zero header and the fixed strides (64/4/64) are synthesized on
+ * write — no field in the returned object carries them.
  *
  * Verified by in-game experiment 2026-05-18: numElements counts UNIQUE
- * prototypes (foundation, wall, door frame, …); section 0/1 counts are the
- * placed-piece count for that prototype; section 2 count is typically that
- * count or one greater. The earlier "single trailing block after all
- * elements" model was wrong — these blocks are interleaved per element.
+ * prototypes (foundation, wall, door frame, …); transforms.length is the
+ * placed-piece count for that prototype; aux.length is typically the same
+ * or one greater. The earlier "single trailing block after all elements"
+ * model was wrong; these blocks are interleaved per element.
  */
 function tryReadObjectArrayPerElementBlock(cursor, endOff) {
   const start = cursor.pos();
@@ -618,8 +668,7 @@ function tryReadObjectArrayPerElementBlock(cursor, endOff) {
   if (cursor.dv.getUint32(start + 8, true) !== 64) return null;
 
   try {
-    cursor.skip(8);
-    const header = cursor.bytes.subarray(start, start + 8).slice();
+    cursor.skip(8);   // zero header
     const sections = [];
     const expected = [64, 4, 64];
     for (let i = 0; i < 3; i++) {
@@ -630,9 +679,26 @@ function tryReadObjectArrayPerElementBlock(cursor, endOff) {
       if (count > 1_000_000) throw new Error(`implausible count ${count}`);
       const dataBytes = stride * count;
       if (cursor.pos() + dataBytes > endOff) throw new Error(`section ${i} data overruns budget`);
-      sections.push({ stride, count, data: cursor.readBytes(dataBytes).slice() });
+      if (i === 1) {
+        const ids = new Array(count);
+        for (let k = 0; k < count; k++) ids[k] = cursor.readUint32();
+        sections.push(ids);
+      } else {
+        // 16 float32 per element (4×4 matrix, row-major in UE's FMatrix layout).
+        // Non-canonical NaN bit patterns are common in Soulmask aux data
+        // (observed 0xFFFFFFFF as "invalid" sentinel) and would collapse to
+        // canonical 0x7FC00000 if round-tripped via a JS Number, so we
+        // capture them as { $nanBits } wrappers instead.
+        const arr = new Array(count);
+        for (let k = 0; k < count; k++) {
+          const m = new Array(16);
+          for (let j = 0; j < 16; j++) m[j] = readFloat32PreservingNan(cursor);
+          arr[k] = m;
+        }
+        sections.push(arr);
+      }
     }
-    return { header, sections };
+    return { transforms: sections[0], ids: sections[1], aux: sections[2] };
   } catch {
     cursor.seek(start);
     return null;
@@ -640,11 +706,45 @@ function tryReadObjectArrayPerElementBlock(cursor, endOff) {
 }
 
 function writeObjectArrayPerElementBlock(writer, block) {
-  writer.writeBytes(block.header);
-  for (const s of block.sections) {
-    writer.writeUint32(s.stride);
-    writer.writeUint32(s.count);
-    writer.writeBytes(s.data);
+  // 8-byte zero header.
+  writer.writeUint32(0);
+  writer.writeUint32(0);
+  // Section 0: transforms (count × 16 float32).
+  writer.writeUint32(64);
+  writer.writeUint32(block.transforms.length);
+  for (const m of block.transforms) for (const f of m) writeFloat32PreservingNan(writer, f);
+  // Section 1: ids (count × u32).
+  writer.writeUint32(4);
+  writer.writeUint32(block.ids.length);
+  for (const id of block.ids) writer.writeUint32(id);
+  // Section 2: aux (count × 16 float32).
+  writer.writeUint32(64);
+  writer.writeUint32(block.aux.length);
+  for (const m of block.aux) for (const f of m) writeFloat32PreservingNan(writer, f);
+}
+
+// Float32 helpers that preserve non-canonical NaN bit patterns. JavaScript's
+// Number type collapses all NaN bit patterns into the canonical 0x7FC00000
+// on any DataView.setFloat32 call, so a wire NaN like 0xFFFFFFFF (observed in
+// Soulmask JianZhuInstYuanXings aux data) would not round-trip if we used
+// readFloat32 / writeFloat32 directly. We instead carry NaN-bit-patterns as
+// { $nanBits: u32 } wrapper objects.
+function readFloat32PreservingNan(cursor) {
+  const bits = cursor.dv.getUint32(cursor.offset, true);
+  // NaN: exponent all 1s AND mantissa non-zero. The single "canonical NaN"
+  // (0x7FC00000) is allowed to round-trip through Number, but every other
+  // NaN bit pattern needs the wrapper.
+  if ((bits & 0x7F800000) === 0x7F800000 && (bits & 0x007FFFFF) !== 0 && bits !== 0x7FC00000) {
+    cursor.offset += 4;
+    return { $nanBits: bits >>> 0 };
+  }
+  return cursor.readFloat32();
+}
+function writeFloat32PreservingNan(writer, f) {
+  if (f !== null && typeof f === 'object' && '$nanBits' in f) {
+    writer.writeUint32(f.$nanBits >>> 0);
+  } else {
+    writer.writeFloat32(f);
   }
 }
 
@@ -656,14 +756,33 @@ function isObjectInnerType(t) {
 
 function writeArrayValue(writer, tag, value) {
   const innerType = tag.innerType.value;
+  const recompute = !!writer._wsRecomputeSizes;
   writer.writeInt32(value.elements.length);
   if (innerType === 'StructProperty') {
-    value._arrayInnerTag.write(writer);
     const structName = value._arrayInnerTag.structName.value;
     const handler = STRUCT_HANDLERS[structName];
-    for (const e of value.elements) {
-      if (handler) handler.write(writer, e.value);
-      else writeNestedPropertyStream(writer, e.value);
+    // On recompute, set innerTag.size to the encoded size of element 0.
+    // All array-of-struct elements share the same innerTag, and stock UE
+    // uses one size value as a hint for the whole element shape. Self-
+    // delimiting struct streams (None terminator) make the exact value less
+    // critical for reading, but writing the truthful size keeps validators
+    // happy.
+    let origInnerSize = value._arrayInnerTag.size;
+    if (recompute && value.elements.length > 0) {
+      const sub = new Writer(64);
+      sub._wsRecomputeSizes = true;
+      if (handler) handler.write(sub, value.elements[0].value);
+      else writeNestedPropertyStream(sub, value.elements[0].value);
+      value._arrayInnerTag.size = sub.finalize().length;
+    }
+    try {
+      value._arrayInnerTag.write(writer);
+      for (const e of value.elements) {
+        if (handler) handler.write(writer, e.value);
+        else writeNestedPropertyStream(writer, e.value);
+      }
+    } finally {
+      if (recompute) value._arrayInnerTag.size = origInnerSize;
     }
     return;
   }
@@ -688,7 +807,7 @@ function readSetValue(cursor, tag) {
 // Set elements for StructProperty inner type are raw binary structs with no
 // inner PropertyTag wrapper (unlike ArrayProperty<StructProperty>, which does
 // have one). Every observed Set<StructProperty> in world.db uses 16-byte Guids
-// as elements — the same assumption MapProperty makes for Struct keys.
+// as elements: the same assumption MapProperty makes for Struct keys.
 function readSetElement(cursor, innerType) {
   if (innerType === 'StructProperty') return FGuid.read(cursor).value;
   return readArrayElement(cursor, innerType);
@@ -737,7 +856,7 @@ function writeMapValue(writer, tag, value) {
 
 /**
  * Map element (one key or one value) when the map's inner/value type is
- * StructProperty — Soulmask uses several conventions that diverge from
+ * StructProperty: Soulmask uses several conventions that diverge from
  * stock UE 4.27 here:
  *
  *   Key  (StructProperty)  → a raw 16-byte FGuid. The map tag declares
@@ -751,7 +870,7 @@ function writeMapValue(writer, tag, value) {
  *                            `GeRenJianZhuYingHuoList`, `GeRenMapRiZhi`)
  *                            OR a raw 16-byte FGuid (`PlayerGongHuiMap`,
  *                            a player→guild membership lookup).
- *                            We sniff which by peeking ahead — a
+ *                            We sniff which by peeking ahead. A
  *                            property stream starts with an FString
  *                            length prefix for the first tag's name
  *                            (small positive int, body is identifier
@@ -767,7 +886,7 @@ function writeMapValue(writer, tag, value) {
  * NOT match the actual byte span of the data section (observed:
  * tag.size=632838, actual=636422 for a populated GongHuiMap). The
  * decoder advances the cursor based on pair count + per-pair shape,
- * NOT the tag.size — which is why this works despite the size lie.
+ * NOT the tag.size, which is why this works despite the size lie.
  */
 function readMapElement(cursor, type, isKey) {
   if (type !== 'StructProperty') return readArrayElement(cursor, type);
@@ -798,17 +917,25 @@ function writeMapElement(writer, type, value, isKey) {
 
 /**
  * Peek the next bytes of `cursor` (without advancing): do they look like
- * the start of a PropertyTag — i.e. an FString that names a property?
+ * the start of a PropertyTag (i.e. an FString that names a property)?
  *
  * A property name FString is:
  *   - int32 SaveNum > 0 and reasonably small (<= 64 chars in Soulmask)
  *   - SaveNum bytes of ANSI body whose last byte is NUL
  *   - body chars (minus NUL) are identifier-safe: A-Z, a-z, 0-9, _.
  *
- * Random GUID bytes effectively never satisfy this — the first uint32
+ * Random GUID bytes effectively never satisfy this: the first uint32
  * of a Guid is ~uniform over [0..2^32), and even when it lands in a
  * "plausible length" range the printable-ASCII + NUL-terminator check
  * eliminates the false positives.
+ *
+ * Caveat: we only match ANSI property names (SaveNum > 0). Every Soulmask
+ * property name observed in world.db is ASCII, so a negative-SaveNum
+ * (UTF-16) tag is currently treated as "not a tag" and the caller falls
+ * through to the alternate read path. If a future Soulmask version emits
+ * UTF-16 property names inside a Map<Struct,Struct> value, this needs an
+ * additional branch matching saveNum < 0 with the equivalent UTF-16
+ * identifier-character + NUL-terminator check.
  */
 function peekLooksLikePropertyTag(cursor) {
   if (cursor.remaining() < 8) return false;
@@ -836,6 +963,49 @@ function peekLooksLikePropertyTag(cursor) {
 // kind+path, kind+path+classPath, or full kind+path+classPath+embedded).
 // Other inner types have fixed sizes determined by the type itself, so
 // they ignore the hint.
+//
+// =====================================================================
+// Heuristics preamble: how this reader disambiguates ObjectProperty
+// elements that don't carry a per-element delimiter on the wire.
+//
+// Stock UE ArrayProperty<ObjectProperty> writes a sequence of object
+// values back-to-back with no length tag and no separator between
+// elements. Each element's wire form is one of:
+//
+//   (A) kind-only         1 byte
+//   (B) kind+path         1 byte + FString
+//   (C) kind+path+class   1 byte + FString + FString
+//   (D) kind+path+class+embedded property stream  (terminated by None)
+//
+// Without per-element bounds we'd read past the element's actual end
+// into either the next element's kind byte or a trailing binary section
+// (origin / placement data) and cascade-fail.
+//
+// We address this with four guards, each cheap and orthogonal:
+//
+//   Guard 1: budget exhaustion. After path, if there's no room for even
+//            a null-form classPath FString (4 bytes), stop here.
+//   Guard 2: implausible saveNum magnitude. A real classPath is short
+//            (<= 1024 chars); a peek that decodes to a huge magnitude
+//            usually means we're looking at the start of the next
+//            element's bytes instead.
+//   Guard 3: classPath starts with '/'. Soulmask asset paths are always
+//            "/Script/..." or "/Game/...". A peek whose first content
+//            byte isn't '/' (or '/' '\0' for UTF-16) is the next
+//            element's payload, not a real classPath.
+//   Guard 4: embedded-stream signature. The bytes following classPath
+//            either start a PropertyTag (identifier-character name with
+//            a small ANSI SaveNum) or they don't; if they don't, the
+//            element ends without an embedded stream.
+//
+// The same logic governs whether a 4-byte trailer at the element's tail
+// is consumed: only when the next 4 bytes are 0x00000000 (FName.Number)
+// AND we're still within budget.
+//
+// In practice this catches every known Soulmask actor in the tested
+// world.db. Adding a new game-specific element shape means adding a
+// new guard, not relaxing the existing ones.
+// =====================================================================
 function readArrayElement(cursor, innerType, sizeHint = Infinity) {
   switch (innerType) {
     case 'IntProperty':    return cursor.readInt32();
@@ -864,7 +1034,7 @@ function readArrayElement(cursor, innerType, sizeHint = Infinity) {
     case 'WSObjectProperty': {
       // Bounded read, mirroring readObjectValue. The variable wire shapes
       // (kind-only, +path, +path+classPath, +embedded) are disambiguated by
-      // sizeHint — without the bound we'd read past the element into the
+      // sizeHint. Without the bound we'd read past the element into the
       // next property's tag, which causes catastrophic cascade failures
       // (cf. ChengHaoList in serial 92 and friends). Capture per-FString
       // isNull flags for byte-identical round-trip of empty wire-FStrings.
@@ -878,7 +1048,7 @@ function readArrayElement(cursor, innerType, sizeHint = Infinity) {
       // kind byte with no path, classPath, or embedded stream. Without this
       // early-out, the FString reader would interpret the next 4 bytes (which
       // belong to either the next element or the trailing binary section)
-      // as a path saveNum — typically a huge garbage value that overshoots
+      // as a path saveNum: typically a huge garbage value that overshoots
       // the array. Seen in JianZhuInstYuanXings, ZhuangBeiLanDaoJuJiYiList,
       // and KuaiJieLanDaoJuJiYiList trailing slots.
       if (kind === 0) {
@@ -915,7 +1085,7 @@ function readArrayElement(cursor, innerType, sizeHint = Infinity) {
         // "/Script/Module.Class" or "/Game/...". The first content character
         // is therefore "/" (0x2F). When the bytes after path are actually the
         // start of the NEXT element (kind byte + optional kindOnePrefix +
-        // path saveNum), peekSN can fall in the [-1024, 1024] range — e.g.
+        // path saveNum), peekSN can fall in the [-1024, 1024] range, e.g.
         // bytes `01 01 00 00` from a kind=1 element with kindOnePrefix=1 read
         // as int32 = 257. The previous saveNum-magnitude guard misses this;
         // checking the first content byte for '/' catches it cleanly. Allow
@@ -947,7 +1117,7 @@ function readArrayElement(cursor, innerType, sizeHint = Infinity) {
         });
       }
       // Guard 4: embedded-stream presence. Same problem as the classPath
-      // guards but one level deeper — when the element has classPath but
+      // guards but one level deeper: when the element has classPath but
       // NO embedded stream, the bytes that follow classPath are the start
       // of the NEXT element (kind byte) or the trailing binary section
       // (12 zero bytes of origin). An embedded stream begins with a
@@ -1088,12 +1258,40 @@ export function readPropertyStream(cursor, endOffset = Infinity, consumeTerminat
 }
 
 export function writePropertyStream(writer, properties, emitTerminatorTrailer = false) {
+  // When the writer carries the recompute flag, we encode each property's
+  // value into a temporary sub-buffer, then overwrite tag.size with the
+  // sub-buffer's length before writing the tag. This is required for edits:
+  // the wire stores tag.size literally, and a stale value (e.g. after
+  // lengthening an FString) leaves the next reader misaligned.
+  //
+  // The flag propagates to sub-buffers so nested streams inside StructValue /
+  // ObjectRef / Array<Struct> also get recomputed sizes. Direct callers that
+  // want byte-identical preservation (the test-roundtrip.mjs path) leave the
+  // flag unset; UnrealBlob.serialize sets it from blob._recomputeSizes.
+  const recompute = !!writer._wsRecomputeSizes;
   for (const p of properties) {
     if (p._sizeMismatch) {
       throw new Error(`writePropertyStream: property '${p.name}' has _sizeMismatch (${JSON.stringify(p._sizeMismatch)}); cannot safely re-emit`);
     }
-    p.tag.write(writer);
-    writeValue(writer, p.tag, p.value);
+    if (recompute) {
+      const sub = new Writer(64);
+      sub._wsRecomputeSizes = true;
+      writeValue(sub, p.tag, p.value);
+      const valueBytes = sub.finalize();
+      const origSize = p.tag.size;
+      p.tag.size = valueBytes.length;
+      try {
+        p.tag.write(writer);
+        writer.writeBytes(valueBytes);
+      } finally {
+        // Restore so we don't mutate the blob's tags across multiple
+        // serialize() calls. A subsequent recompute will rewrite them.
+        p.tag.size = origSize;
+      }
+    } else {
+      p.tag.write(writer);
+      writeValue(writer, p.tag, p.value);
+    }
   }
   new FName('None').write(writer);
   if (emitTerminatorTrailer) writer.writeInt32(0);
@@ -1103,7 +1301,7 @@ export function writePropertyStream(writer, properties, emitTerminatorTrailer =
 // StructValue.write) to avoid needing a writePropertyStream re-export.
 // `emitTerminatorTrailer` defaults to false because nested streams in
 // stock UE 4.27 don't carry the 4-byte FName.Number trailer that the
-// outermost stream does — but some Soulmask embedded ObjectProperty
+// outermost stream does. But some Soulmask embedded ObjectProperty
 // streams DO (see ObjectRef.hasTerminatorTrailer / readObjectValue's
 // trailer-skip detection), so callers can opt in.
 export function writeNestedPropertyStream(writer, properties, emitTerminatorTrailer = false) {