wscodec 0.1.0 → 0.2.0

package/README.md

@@ -1,13 +1,17 @@
 # wscodec
 
-Pure-JS codec for Soulmask `actor_data` property streams — the binary
-payload UE 4.27 emits for every actor's serialized state, with the
-Soulmask-specific quirks layered on top.
+Pure-JS codec for Soulmask `actor_data` property streams. Soulmask is a
+survival game whose dedicated server stores world state in a `world.db`
+SQLite file; every actor's serialized state lives in the `actor_data`
+column as an LZ4-compressed UE 4.27 `FPropertyTag` byte stream with a
+few Soulmask-specific quirks layered on top.
+
+wscodec parses the property stream into a JavaScript object tree and
+serializes it back. Repo: https://github.com/auroris/SoulmaskCodec.
 
 Zero runtime dependencies. Accepts uncompressed bytes, returns
 JavaScript objects, and vice versa. Round-trip is byte-identical
-against every actor in a tested `world.db` (174.6 MB across 11,667
-rows; `npm test`).
+against every actor in a tested `world.db` (`npm test`).
 
 ## Scope
 
@@ -23,7 +27,7 @@ actor_data column bytes
 ```
 
 wscodec handles the bottom half (the bytes that come out of LZ4
-decompression). The caller handles LZ4 — see "LZ4 integration" below
+decompression). The caller handles LZ4. See "LZ4 integration" below
 for a copy-paste recipe with `lz4-wasm-nodejs`.
 
 The SQLite `actor_table.data_version` column stores the NEGATIVE of
@@ -31,11 +35,36 @@ the on-wire DataVersion. A healthy blob with wire `DataVersion=2`
 lives in a row whose `data_version` column reads `-2`. The wire
 bytes themselves are always the unsigned `0x00000002`.
 
-## Install
+## Setup
 
-```sh
-npm install wscodec
-```
+wscodec itself has zero runtime dependencies, but a realistic workflow
+also needs LZ4 decompression and a SQLite reader. The recommended
+stack:
+
+1. **Node.js LTS.** Install from <https://nodejs.org/>. On Windows, tick
+   the "Automatically install the necessary tools" checkbox in the
+   installer; this pulls in the Visual Studio Build Tools and Python
+   that `better-sqlite3` needs to compile its native bindings. Without
+   them `npm install better-sqlite3` will fail with a node-gyp error.
+
+2. **Install wscodec:**
+
+   ```sh
+   npm install wscodec
+   ```
+
+3. **Install the LZ4 + SQLite peers** when you need them:
+
+   ```sh
+   npm install lz4-wasm-nodejs better-sqlite3
+   ```
+
+   - `lz4-wasm-nodejs` is pure WASM, no build step.
+   - `better-sqlite3` builds native bindings (hence the optional tools above).
+
+The test suite uses both peers; if you're only consuming wscodec
+programmatically against bytes you already have in memory, neither
+peer is required.
 
 ## API
 
@@ -44,9 +73,9 @@ npm install wscodec
 ```js
 import { UnrealBlob } from 'wscodec';
 
-const blob = UnrealBlob.decode(uncompressedBytes); // Uint8Array → blob
-const bytes = blob.serialize();                    // blob → Uint8Array
-UnrealBlob.detect(u8);                              // sniff version tag → boolean
+const blob = UnrealBlob.decode(uncompressedBytes); // Uint8Array to blob
+const bytes = blob.serialize();                    // blob to Uint8Array
+UnrealBlob.detect(u8);                              // sniff version tag, returns boolean
 ```
 
 `UnrealBlob.decode(u8)` parses the version tag + property stream and
@@ -68,25 +97,28 @@ is true it re-emits the property stream from `properties` via
 `writePropertyStream`.
 
 `blob.findProperty(name)` returns the first top-level property whose
-tag name matches, or `null`.
+tag name matches, or `null`. It does NOT traverse into embedded
+streams, struct values, array elements, or map entries; use
+`blob.findPropertyDeep(name)` for a depth-first walk across the whole
+property tree.
 
 ### Property tree
 
 `blob.properties` is an array of `Property` instances. Each carries
-a `PropertyTag` (`name`, `type`, `size`, …) and a `value` whose
+a `PropertyTag` (`name`, `type`, `size`, ...) and a `value` whose
 JavaScript shape depends on the tag's type:
 
 | tag type | value shape |
 |---|---|
-| `IntProperty`, `FloatProperty`, `BoolProperty`, … | plain JS primitive |
+| `IntProperty`, `FloatProperty`, `BoolProperty`, ... | plain JS primitive |
 | `StrProperty`, `NameProperty` | string / `FName` |
-| `StructProperty` | `StructValue` — `.value` is either a plain object (known binary structs like `Vector`, `Quat`, `Transform`, `Guid`, …) or a nested property array |
+| `StructProperty` | `StructValue`. `.value` is either a plain object for known binary structs (`Vector`, `Quat`, `Transform`, ...), an `FGuid` instance for the `Guid` struct, or a nested property array for unknown structs |
 | `ArrayProperty`, `SetProperty` | `ArrayValue` / `SetValue` with `.elements` |
-| `MapProperty` | `MapValue` with `.entries: [[key, value], …]` |
+| `MapProperty` | `MapValue` with `.entries: [[key, value], ...]` |
 | `ObjectProperty`, `ClassProperty`, `Weak*`, `Lazy*`, `WSObjectProperty` | `ObjectRef` (kind + optional path/classPath/embedded stream) |
 | `SoftObjectProperty`, `SoftClassProperty` | `SoftObjectRef` (`assetPath`, `subPath`) |
 | `TextProperty` | `FTextValue` (handles UE4 FText history types -1, 0, 2, 4) |
-| anything wscodec couldn't structurally decode | `OpaqueValue` — bytes retained verbatim |
+| anything wscodec couldn't structurally decode | `OpaqueValue`. Bytes retained verbatim |
 
 Submodule re-exports make the value classes importable directly:
 
@@ -97,33 +129,103 @@ import { FName, FGuid } from 'wscodec';
 ```
 
 Lower-level helpers (`Cursor`, `Writer`, `readPropertyStream`,
-`writePropertyStream`, `readValue`, `writeValue`, `STRUCT_HANDLERS`)
-are also exported for callers building custom workflows on top.
+`writePropertyStream`, `readValue`, `writeValue`, `STRUCT_HANDLERS`,
+`registerStructHandler`) are also exported for callers building
+custom workflows on top.
+
+### Extending the struct registry
+
+`STRUCT_HANDLERS` is a mutable registry of binary struct handlers
+(`Vector`, `Quat`, `Transform`, `Guid`, ...). Unknown struct names
+fall through to the nested-property-stream path, which is correct
+when the struct is tagged and byte-identical via `OpaqueValue` when
+it isn't. To teach the codec a new binary shape, use
+`registerStructHandler`:
+
+```js
+import { registerStructHandler, Cursor, Writer } from 'wscodec';
+
+registerStructHandler('MyVector', {
+  read:  (c) => ({ x: c.readFloat32(), y: c.readFloat32(), z: c.readFloat32() }),
+  write: (w, v) => { w.writeFloat32(v.x); w.writeFloat32(v.y); w.writeFloat32(v.z); },
+});
+```
+
+The helper validates that both `read(cursor)` and `write(writer, value)`
+are functions. Register before calling `UnrealBlob.decode` on any blob
+that uses the type.
 
 ### Editing
 
+The library does not provide typed mutators. Callers manipulate the
+`properties` tree directly, then set `_dirty` on the ROOT blob to
+force a re-encode.
+
 ```js
-import { UnrealBlob } from 'wscodec';
+import { UnrealBlob, FName } from 'wscodec';
 
 const blob = UnrealBlob.decode(inner);
 
-// Mutate the tree directly. The library does not provide typed
-// mutators; callers manipulate `properties` and set `_dirty` to
-// force re-encode.
+// (1) Edit a primitive value.
+//     JianZhuHP (jianzhu = "building") is the building's HP property.
 blob.findProperty('JianZhuHP').value = 100;
+
+// (2) Replace an FName-typed value. NameProperty values are FName
+//     instances, not bare strings.
+blob.findProperty('CharacterClass').value = new FName('NPC_Skeleton');
+
+// (3) Mutate a nested struct. Known binary structs (Vector, Quat, ...)
+//     expose .value as a plain object.
+const transform = blob.findProperty('Transform');
+transform.value.value.translation = { x: 100, y: 200, z: 50 };
+
+// (4) Append to an array. ArrayValue.elements is a plain JS array.
+const inventory = blob.findProperty('InventoryItems');
+inventory.value.elements.push(new FName('Item_Wood'));
+
+// (5) Remove an element. Just splice it out; don't set null.
+inventory.value.elements.splice(0, 1);
+
+// Always set _dirty on the ROOT blob (not on nested properties). The
+// flag is read by blob.serialize() to decide pass-through vs re-encode.
 blob._dirty = true;
 
 const updatedBytes = blob.serialize(); // re-emits from properties
 ```
 
+Gotchas:
+
+- `_dirty` lives on the root `UnrealBlob`, not on nested `Property` /
+  `ArrayValue` / `StructValue` objects. Mutating a deep value without
+  setting `blob._dirty = true` returns the original `_raw` bytes
+  unchanged.
+- `BoolProperty` values live in the `tag` (`tag.boolVal`), not in
+  `property.value`. To flip a bool, edit `prop.tag.boolVal`.
+- Removing a property means splicing it out of `blob.properties`, not
+  setting `property.value = null`.
+- If you change a value's encoded SIZE (e.g. extending an FString),
+  the property's `tag.size` is recomputed on write, but any property
+  that previously carried a `_sizeMismatch` annotation refuses to
+  re-emit. Such properties are extremely rare in healthy world.db
+  files and are reported by `npm test`.
+- `serialize()` throws if `_dirty` is true AND `error` is set:
+  re-emitting from an empty properties array would produce a malformed
+  stream. Leave `_dirty=false` to pass through `_raw` verbatim, or
+  clear `.error` first if you've replaced `.properties` manually.
+- 64-bit integer values (`Int64Property`, `UInt64Property`,
+  `DateTime`, `Timespan`) round-trip as decimal strings. If you
+  replace such a value with a Number, it must be a safe integer
+  (`|v| <= Number.MAX_SAFE_INTEGER`); otherwise the writer throws
+  rather than silently lose precision.
+
 `serialize()` for a dirty blob is byte-identical to a fresh
-`decode + serialize` cycle on its output — verified on every row
-of the tested `world.db`.
+`decode + serialize` cycle on its output, verified on every row of
+the tested `world.db`.
 
 ## LZ4 integration
 
 `actor_data` column bytes come out of LZ4 compression. wscodec
-doesn't bundle an LZ4 implementation — that's a caller concern. A
+doesn't bundle an LZ4 implementation; that's a caller concern. A
 working recipe using `lz4-wasm-nodejs`:
 
 ```js
@@ -161,11 +263,11 @@ for (const row of db.prepare('SELECT actor_serial, actor_data FROM actor_table')
 }
 ```
 
-Note: LZ4 compression is not deterministic — two compressors will
-produce different bytes for the same input. wscodec's
-byte-identical guarantee covers the inner property-stream bytes;
-the outer column bytes round-trip only for unmodified blobs (cache
-the input column bytes if you need that).
+Note: LZ4 compression is not deterministic. Two compressors will
+produce different bytes for the same input. wscodec's byte-identical
+guarantee covers the inner property-stream bytes; the outer column
+bytes round-trip only for unmodified blobs (cache the input column
+bytes if you need that).
 
 ## Round-trip guarantees
 
@@ -175,36 +277,56 @@ For every row in the tested `world.db`:
 - `blob.serialize()` with `_dirty = false` returns the input bytes byte-identical.
 - `blob.serialize()` with `_dirty = true` re-emits from `properties` and is byte-identical to the input.
 
-Coverage: 174,610,207 bytes across 11,667 actors, including every
-known Soulmask wire-format quirk:
-
-- `kind=0x01` ObjectProperty with the 4-byte actor-ref prefix.
-- Embedded ObjectProperty streams with the 4-byte FName.Number trailer
-  (the Soulmask `JianZhuInstGLQComponent`-style nested format).
-- ArrayProperty<ObjectProperty> with the JianZhuInstYuanXings
-  per-element placement-binary blocks (8-byte header + three
-  stride/count sections per yuan-xing prototype).
-- ArrayProperty<TextProperty> elements with FText history types
-  -1, 0, 2, and 4 (including the legacy UE3-style uint32 booleans in
-  FNumberFormattingOptions).
-- SetProperty<StructProperty> with implicit FGuid struct keys.
-- Custom Soulmask Map<Struct,Struct> framing.
+Coverage includes every known Soulmask wire-format quirk:
+
+- **kind=0x01 ObjectProperty with the 4-byte actor-ref prefix.**
+  Soulmask's hard actor references (a pawn pointing at its inventory
+  actor, for example) prepend an extra 4-byte field between the kind
+  byte and the path FString. Observed value is always 1; semantic is
+  unknown but the bytes are captured and replayed verbatim.
+- **Embedded ObjectProperty streams with the 4-byte FName.Number trailer.**
+  Some Soulmask nested ObjectProperty values (`JianZhuInstGLQComponent`
+  is the canonical example; `JianZhu` = "building") carry the
+  outermost-stream None trailer (a 4-byte FName.Number = 0) after their
+  embedded property stream, where stock UE 4.27 nested streams do not.
+- **ArrayProperty<ObjectProperty> with per-element placement-binary blocks.**
+  `JianZhuInstYuanXings` arrays (`YuanXing` = "prototype", so
+  "building-zone yuan-xing" is the list of building-piece prototypes
+  inside a building zone) interleave a fixed-shape binary block after
+  each ObjectProperty element: an 8-byte header + three stride/count
+  sections (per-piece world transforms, ids, and aux data).
+- **ArrayProperty<TextProperty> with mixed FText history types.**
+  Elements use history types -1 (culture-invariant), 0 (localized),
+  2 (ordered format), and 4 (`FTextHistory_AsNumber`). History type 4
+  embeds a legacy UE3-style `FNumberFormattingOptions` whose boolean
+  fields are 4 bytes wide rather than the modern 1 byte; the codec
+  emits this correctly.
+- **SetProperty<StructProperty> with implicit FGuid struct keys.**
+  Soulmask `SetProperty` declarations whose inner is `StructProperty`
+  don't carry an inner struct shape; every populated instance in
+  `world.db` uses raw 16-byte FGuids as elements.
+- **Custom Soulmask Map<Struct,Struct> framing.** The guild-data maps
+  (`GongHuiMap`, `PlayerGongHuiDataMap`; `GongHui` = "guild") use a
+  non-standard layout. The map's tag.size lies (observed 632838 vs
+  actual 636422); pair shapes are detected by peeking at the next
+  bytes rather than trusting the declared size.
 
 ## Running the test
 
 ```sh
-git clone …                # repo with world.db at the root
-cd repo/wscodec
+git clone https://github.com/auroris/SoulmaskCodec.git
+cd SoulmaskCodec
 npm install
-npm test                    # looks for world.db two dirs up by default
+npm test                                  # looks for world.db two dirs up by default
 # or
 node test/test-roundtrip.mjs /path/to/world.db
 ```
 
-Test deps: `lz4-wasm-nodejs` (LZ4 inside the test), `better-sqlite3`
-(reads the `world.db` SQLite file). Both are picked up via npm
-module resolution; if `better-sqlite3` isn't installed at the package
-root the test will surface that with a clear error.
+Test deps: `lz4-wasm-nodejs` (LZ4 inside the test) and
+`better-sqlite3` (reads the `world.db` SQLite file). Both are picked
+up via npm module resolution; if `better-sqlite3` isn't installed at
+the package root the test will surface that with a clear error. See
+the Setup section above for the build-tools prerequisite on Windows.
 
 ## License
 

package/io.mjs

@@ -1,5 +1,5 @@
 /**
- * Cursor + Writer — byte-level read/write primitives over a Uint8Array.
+ * Cursor + Writer: byte-level read/write primitives over a Uint8Array.
  *
  * No Unreal semantics here. FString lives here too because it's a stateful
  * read/write on the same DataView; everything else (FName, FGuid, structs,
@@ -15,8 +15,33 @@ export class Cursor {
   pos()       { return this.offset; }
   eof()       { return this.offset >= this.bytes.length; }
   remaining() { return this.bytes.length - this.offset; }
-  skip(n)     { this.offset += n; }
-  seek(n)     { this.offset = n; }
+
+  /**
+   * Advance the cursor by `n` bytes. Throws RangeError if `n` is negative or
+   * would take the cursor past the end of the buffer. Use `seek(n)` to jump
+   * to an absolute offset (including backwards).
+   */
+  skip(n) {
+    if (!Number.isFinite(n) || n < 0) {
+      throw new RangeError(`Cursor.skip: n must be a non-negative finite number, got ${n}`);
+    }
+    if (this.offset + n > this.bytes.length) {
+      throw new RangeError(`Cursor.skip: ${n} bytes from offset ${this.offset} exceeds buffer length ${this.bytes.length}`);
+    }
+    this.offset += n;
+  }
+
+  /**
+   * Move the cursor to absolute offset `n`. Throws RangeError if `n` is out
+   * of `[0, buffer.length]` (note: length is allowed; the cursor is then at
+   * EOF and any further read would throw).
+   */
+  seek(n) {
+    if (!Number.isFinite(n) || n < 0 || n > this.bytes.length) {
+      throw new RangeError(`Cursor.seek: offset ${n} out of range [0, ${this.bytes.length}]`);
+    }
+    this.offset = n;
+  }
 
   readUint8()   { const v = this.dv.getUint8(this.offset);            this.offset += 1; return v; }
   readInt8()    { const v = this.dv.getInt8(this.offset);             this.offset += 1; return v; }
@@ -28,6 +53,14 @@ export class Cursor {
   readInt64()   { const v = this.dv.getBigInt64(this.offset, true);   this.offset += 8; return v; }
   readFloat32() { const v = this.dv.getFloat32(this.offset, true);    this.offset += 4; return v; }
   readFloat64() { const v = this.dv.getFloat64(this.offset, true);    this.offset += 8; return v; }
+
+  /**
+   * Read `n` bytes and return them as a Uint8Array VIEW over the underlying
+   * buffer (no copy). The returned subarray shares storage with this cursor's
+   * buffer: mutating it mutates the buffer, and the view becomes stale if
+   * the buffer is detached. Callers that need to retain the bytes past the
+   * buffer's lifetime should `.slice()` the result.
+   */
   readBytes(n)  { const out = this.bytes.subarray(this.offset, this.offset + n); this.offset += n; return out; }
 
   /**
@@ -94,8 +127,18 @@ export class Writer {
   writeInt16(v)   { this._ensure(2); this.dv.setInt16(this.offset, v, true);        this.offset += 2; }
   writeUint32(v)  { this._ensure(4); this.dv.setUint32(this.offset, v >>> 0, true); this.offset += 4; }
   writeInt32(v)   { this._ensure(4); this.dv.setInt32(this.offset, v | 0, true);    this.offset += 4; }
-  writeUint64(v)  { this._ensure(8); this.dv.setBigUint64(this.offset, BigInt(v), true); this.offset += 8; }
-  writeInt64(v)   { this._ensure(8); this.dv.setBigInt64(this.offset, BigInt(v), true);  this.offset += 8; }
+
+  /**
+   * Write a 64-bit unsigned integer. Accepts BigInt, a decimal string, or a
+   * safe-integer Number (|v| <= Number.MAX_SAFE_INTEGER = 2^53 - 1). A Number
+   * outside that range throws RangeError rather than silently losing precision
+   * via `BigInt(largeNumber)`. The codec's decoders return I64/U64 values as
+   * strings for this reason; this guard catches accidental mutation that
+   * substitutes an unsafe Number.
+   */
+  writeUint64(v)  { this._ensure(8); this.dv.setBigUint64(this.offset, _toBigInt64(v, 'Writer.writeUint64'), true); this.offset += 8; }
+  /** Signed 64-bit integer. See writeUint64 for accepted value forms. */
+  writeInt64(v)   { this._ensure(8); this.dv.setBigInt64(this.offset, _toBigInt64(v, 'Writer.writeInt64'), true); this.offset += 8; }
   writeFloat32(v) { this._ensure(4); this.dv.setFloat32(this.offset, v, true);      this.offset += 4; }
   writeFloat64(v) { this._ensure(8); this.dv.setFloat64(this.offset, v, true);      this.offset += 8; }
   writeBytes(u8)  { this._ensure(u8.length); this.bytes.set(u8, this.offset);       this.offset += u8.length; }
@@ -148,3 +191,23 @@ export class Writer {
     }
   }
 }
+
+/**
+ * Coerce a 64-bit integer value into a BigInt suitable for
+ * DataView.setBig{Int,Uint}64. Accepts BigInt directly; converts string and
+ * safe-integer Number; throws on unsafe Number or unsupported types.
+ *
+ * The motivation: `BigInt(largeNumber)` silently loses precision for
+ * |v| > 2^53. The decoder paths return I64/U64 values as decimal strings
+ * specifically to avoid this; tightening the writer's contract catches
+ * accidental round-trip-breaking mutation at the source.
+ */
+function _toBigInt64(v, fnName) {
+  if (typeof v === 'bigint') return v;
+  if (typeof v === 'string')  return BigInt(v);
+  if (typeof v === 'number') {
+    if (Number.isInteger(v) && Math.abs(v) <= Number.MAX_SAFE_INTEGER) return BigInt(v);
+    throw new RangeError(`${fnName}: Number ${v} is unsafe for 64-bit conversion (non-integer or |v| > 2^53). Pass a BigInt or decimal string.`);
+  }
+  throw new TypeError(`${fnName}: expected BigInt, string, or safe-integer Number; got ${typeof v}`);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wscodec",
-  "version": "0.1.0",
-  "description": "Pure-JS codec for Soulmask actor_data property streams (UE4.27 FPropertyTag wire format). Zero runtime dependencies — accepts uncompressed bytes, returns JS objects, and vice versa. Round-trip byte-identical against every actor.",
+  "version": "0.2.0",
+  "description": "Pure-JS codec for Soulmask actor_data property streams (UE 4.27 FPropertyTag wire format). Zero runtime dependencies. Accepts uncompressed bytes, returns JS objects, and vice versa. Round-trip byte-identical against every actor.",
   "type": "module",
   "main": "./wscodec.mjs",
   "exports": {
@@ -29,9 +29,23 @@
     "unreal",
     "ue4",
     "fpropertytag",
-    "codec"
+    "codec",
+    "world.db",
+    "actor_data"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/auroris/SoulmaskCodec.git"
+  },
+  "homepage": "https://github.com/auroris/SoulmaskCodec#readme",
+  "bugs": {
+    "url": "https://github.com/auroris/SoulmaskCodec/issues"
+  },
+  "author": "auroris",
   "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
   "devDependencies": {
     "better-sqlite3": "^12.10.0",
     "lz4-wasm-nodejs": "^0.9.2"

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

@@ -30,7 +30,7 @@ import { StructValue, STRUCT_HANDLERS }                       from './structs.mj
 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 +124,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 +137,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 +163,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 +207,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 +279,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();
@@ -297,7 +297,7 @@ function readFText(cursor, sizeHint) {
       // 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 +328,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 +366,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);
@@ -420,7 +420,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 +459,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 +471,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 +484,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');
@@ -598,14 +598,14 @@ function readArrayValue(cursor, tag, sizeHint) {
  *   [u32 stride=64] [u32 count]  [count×64 bytes]   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
+ * when the bytes don't match. Non-JianZhuInstYuanXings ObjectProperty arrays
  * have no such block, so peeking-and-rolling-back keeps them unaffected.
  *
  * 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.
+ * elements" model was wrong; these blocks are interleaved per element.
  */
 function tryReadObjectArrayPerElementBlock(cursor, endOff) {
   const start = cursor.pos();
@@ -688,7 +688,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 +737,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 +751,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 +767,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 +798,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 +844,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 +915,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 +929,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 +966,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 +998,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
@@ -1103,7 +1154,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) {

package/structs.mjs

@@ -3,16 +3,20 @@
  *
  * Soulmask is UE 4.27 so "core" structs (Vector etc.) use 32-bit floats.
  * Known struct names read directly as binary; unknown struct names fall
- * through to a nested property stream (handled in properties.mjs, not here
- * — StructValue.read is supplied a `streamReader` callback to avoid a
+ * through to a nested property stream (handled in properties.mjs, not here;
+ * StructValue.read is supplied a `streamReader` callback to avoid a
  * load-order cycle).
  */
 
 import { FGuid } from './primitives.mjs';
 
-// Binary struct handlers. Each entry has read(cursor) → plain object and
+// Binary struct handlers. Each entry has read(cursor) -> plain object and
 // write(writer, plainObject). The plain object is what callers see as
 // `structValue.value` when the struct is one of these known shapes.
+//
+// Consumers can extend this registry to teach the codec about additional
+// known-binary structs; prefer the `registerStructHandler` helper below over
+// mutating this object directly, since it validates the handler shape.
 export const STRUCT_HANDLERS = {
   Vector:      { read: c => ({ x: c.readFloat32(), y: c.readFloat32(), z: c.readFloat32() }),
                  write: (w, v) => { w.writeFloat32(v.x); w.writeFloat32(v.y); w.writeFloat32(v.z); } },
@@ -24,12 +28,20 @@ export const STRUCT_HANDLERS = {
                  write: (w, v) => { w.writeFloat32(v.pitch); w.writeFloat32(v.yaw); w.writeFloat32(v.roll); } },
   Quat:        { read: c => ({ x: c.readFloat32(), y: c.readFloat32(), z: c.readFloat32(), w: c.readFloat32() }),
                  write: (w, v) => { w.writeFloat32(v.x); w.writeFloat32(v.y); w.writeFloat32(v.z); w.writeFloat32(v.w); } },
+  // FColor wire order is B, G, R, A (not R, G, B, A). This matches UE4's
+  // FColor::Serialize, where the in-memory union exposes the bytes in BGRA
+  // order to match Windows DIB / DirectX texture layout. Don't "fix" the
+  // ordering; it's correct as-is.
   Color:       { read: c => ({ b: c.readUint8(), g: c.readUint8(), r: c.readUint8(), a: c.readUint8() }),
                  write: (w, v) => { w.writeUint8(v.b); w.writeUint8(v.g); w.writeUint8(v.r); w.writeUint8(v.a); } },
   LinearColor: { read: c => ({ r: c.readFloat32(), g: c.readFloat32(), b: c.readFloat32(), a: c.readFloat32() }),
                  write: (w, v) => { w.writeFloat32(v.r); w.writeFloat32(v.g); w.writeFloat32(v.b); w.writeFloat32(v.a); } },
-  Guid:        { read: c => FGuid.read(c).value,
-                 write: (w, v) => new FGuid(v).write(w) },
+  // Guid returns an FGuid INSTANCE (not a bare string). FGuid carries
+  // toJSON/equals/isZero helpers; the write path accepts FGuid or a bare
+  // 8-4-4-4-12 string for backward compatibility with code that built the
+  // struct value from a literal.
+  Guid:        { read: c => FGuid.read(c),
+                 write: (w, v) => FGuid.from(v).write(w) },
   DateTime:    { read: c => c.readInt64().toString(),
                  write: (w, v) => w.writeInt64(v) },
   Timespan:    { read: c => c.readInt64().toString(),
@@ -48,6 +60,27 @@ export const STRUCT_HANDLERS = {
                  write: (w, v) => { STRUCT_HANDLERS.Quat.write(w, v.rotation); STRUCT_HANDLERS.Vector.write(w, v.translation); STRUCT_HANDLERS.Vector.write(w, v.scale3D); } },
 };
 
+/**
+ * Register (or replace) a struct handler. Callers can use this to teach the
+ * codec about additional binary structs the game emits that aren't in the
+ * stock registry. Without a handler, an unknown struct name falls through to
+ * the nested-property-stream path; that's still correct when the struct is
+ * actually tagged, and is byte-identical on round-trip via OpaqueValue when
+ * it isn't.
+ *
+ * Validates that `handler` has both `read(cursor)` and `write(writer, value)`
+ * functions and that `name` is a non-empty string.
+ */
+export function registerStructHandler(name, handler) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new TypeError('registerStructHandler: name must be a non-empty string');
+  }
+  if (!handler || typeof handler.read !== 'function' || typeof handler.write !== 'function') {
+    throw new TypeError('registerStructHandler: handler must expose read(cursor) and write(writer, value) functions');
+  }
+  STRUCT_HANDLERS[name] = handler;
+}
+
 export class StructValue {
   constructor(structName, { value = null, terminated = false, decodeError = null, opaqueTail = null } = {}) {
     this._structName = structName;
@@ -70,7 +103,7 @@ export class StructValue {
    * PropertyTag (FString name with identifier-character ASCII content).
    * When supplied and the wire bytes look tagged, the read switches to
    * the property-stream path even for structs that have a known binary
-   * handler — Soulmask encodes known-binary structs (Transform, Box, ...)
+   * handler: Soulmask encodes known-binary structs (Transform, Box, ...)
    * as TAGGED property streams inside Map struct values, which would
    * otherwise be misread as raw 40-byte Transforms / etc. The decision
    * is recorded on the returned StructValue via `Array.isArray(value)`,

package/values.mjs

@@ -1,9 +1,9 @@
 /**
  * Wrapper classes for non-trivial property-value shapes:
- *   ObjectRef       — ObjectProperty / ClassProperty / Weak / Lazy
- *   SoftObjectRef   — SoftObjectProperty / SoftClassProperty
- *   FTextValue      — TextProperty (FText: localized / culture-invariant string)
- *   OpaqueValue     — bytes we don't decode (fallback for unknown/unimplemented)
+ *   ObjectRef       : ObjectProperty / ClassProperty / Weak / Lazy
+ *   SoftObjectRef   : SoftObjectProperty / SoftClassProperty
+ *   FTextValue      : TextProperty (FText: localized / culture-invariant string)
+ *   OpaqueValue     : bytes we don't decode (fallback for unknown/unimplemented)
  *
  * Array/Set/Map values live in properties.mjs because they're tightly
  * coupled to PropertyTag (struct arrays carry an inner tag).
@@ -16,7 +16,7 @@
 import { writeNestedPropertyStream } from './properties.mjs';
 
 /**
- * Soulmask ObjectProperty value layout. Each field is optional — the wire
+ * Soulmask ObjectProperty value layout. Each field is optional; the wire
  * shape is bounded by the property tag's size budget and the reader stops
  * at whichever boundary it hits first:
  *
@@ -25,7 +25,7 @@ import { writeNestedPropertyStream } from './properties.mjs';
  *                             4-byte field sitting between the kind byte
  *                             and pathFS. Observed value is always 1; the
  *                             semantic meaning is unclear (a flag, an
- *                             FName.Number, or a count) — we capture and
+ *                             FName.Number, or a count); we capture and
  *                             replay it verbatim for byte-identical
  *                             round-trip. Seen on hard actor references
  *                             like NPC `HBindBGCompActor` (the pawn's
@@ -67,7 +67,7 @@ export class ObjectRef {
     this.terminated = terminated;
     // When true, the embedded property stream was followed by a 4-byte
     // FName.Number trailer (the outermost-stream None-trailer convention,
-    // applied here by Soulmask to some nested ObjectProperty embeddeds —
+    // applied here by Soulmask to some nested ObjectProperty embeddeds,
     // e.g. JianZhuInstGLQComponent). The reader detects this when exactly
     // 4 trailing bytes remain inside the tag's size budget; the writer
     // replays them so round-trip stays byte-identical.
@@ -118,28 +118,28 @@ export class SoftObjectRef {
  * UE4 FText wire format:
  *   uint32  Flags
  *   int8    HistoryType
- *   — HistoryType -1 (None / culture-invariant):
+ *   HistoryType -1 (None / culture-invariant):
  *       int32   bHasCultureInvariantString
  *       [FString displayString]   (only when bHasCultureInvariantString != 0)
- *   — HistoryType 0 (Base / localized):
+ *   HistoryType 0 (Base / localized):
  *       FString Namespace
  *       FString Key
  *       FString SourceString
- *   — HistoryType 2 (OrderedFormat):
- *       FText   SourceFmt        — the format pattern, e.g. "{0} < {1} >"
+ *   HistoryType 2 (OrderedFormat):
+ *       FText   SourceFmt        (the format pattern, e.g. "{0} < {1} >")
  *       int32   NumArguments
  *       for each: int8 ContentType + value
  *         0=Int(int64)  1=UInt(uint64)  2=Float(f32)  3=Double(f64)
  *         4=Text(FText) 5=Gender(int8)
- *   — HistoryType 4 (AsNumber, FTextHistory_AsNumber):
+ *   HistoryType 4 (AsNumber, FTextHistory_AsNumber):
  *       FFormatArgumentValue SourceValue (int8 type + value-by-type)
  *       uint32 bHasFormatOptions  ← legacy UE3-style 4-byte bool, NOT 1-byte
  *       [FNumberFormattingOptions FormatOptions]
  *       uint32 bHasCulture        ← also a uint32 bool
  *       [FString TargetCulture]
  *       FNumberFormattingOptions = AlwaysSign(uint32) + UseGrouping(uint32) +
- *         RoundingMode(int8) + 4 × int32 digit-count fields.
- *   — All other types: remaining bytes stored in _raw for verbatim round-trip.
+ *         RoundingMode(int8) + 4 x int32 digit-count fields.
+ *   All other types: remaining bytes stored in _raw for verbatim round-trip.
  */
 export class FTextValue {
   constructor({
@@ -195,20 +195,21 @@ export class FTextValue {
 }
 
 /**
- * Holds raw bytes we couldn't (or wouldn't) decode. `reason` is for
- * debugging only; encoding writes the bytes back verbatim.
+ * Holds raw bytes we couldn't (or wouldn't) decode. `reason` is a free-form
+ * string for debugging only; encoding writes the bytes back verbatim, so a
+ * value the codec couldn't parse still round-trips byte-identical.
  *
- * Two access paths intentionally co-exist:
- *   - `.bytes` / `.reason` — the canonical getter API.
- *   - `._opaque` / `._opaqueReason` — backing-store fields, also publicly
- *     readable for consumers that pre-date the getter API.
+ * OpaqueValue is the codec's universal fallback for everything from unknown
+ * property types to mid-decode recoveries (Struct/Array/Set/Map/Text whose
+ * inner shape didn't parse cleanly). The reader's contract is: on any
+ * structural failure inside a finite byte budget, rewind to the value's
+ * start and capture the budget verbatim into an OpaqueValue, so the outer
+ * stream stays byte-aligned regardless of what went wrong inside.
  */
 export class OpaqueValue {
   constructor(bytes, reason = null) {
-    this._opaque = bytes;
-    if (reason) this._opaqueReason = reason;
+    this.bytes = bytes;
+    this.reason = reason;
   }
-  get bytes()  { return this._opaque; }
-  get reason() { return this._opaqueReason ?? null; }
-  write(writer) { writer.writeBytes(this._opaque); }
+  write(writer) { writer.writeBytes(this.bytes); }
 }

package/wscodec.mjs

@@ -1,9 +1,9 @@
 /**
- * wscodec — pure-JS codec for Soulmask actor_data property streams.
+ * wscodec: pure-JS codec for Soulmask actor_data property streams.
  *
  * The library accepts uncompressed bytes (the payload that comes out of
  * Soulmask's outer LZ4 wrapper) and returns a JavaScript object tree, and
- * vice versa. It has zero runtime dependencies — LZ4 handling, SQLite
+ * vice versa. It has zero runtime dependencies; LZ4 handling, SQLite
  * access, etc. are the caller's responsibility.
  *
  * Wire layout (the bytes accepted by `UnrealBlob.decode` and produced by
@@ -18,14 +18,14 @@
  * The SQLite `actor_table.data_version` column stores the NEGATIVE of the
  * wire-format DataVersion. A healthy blob with DataVersion=2 lives in a row
  * whose `data_version` column reads -2. The wire bytes themselves are
- * always the unsigned 0x00000002 — the negation is purely a column-side
+ * always the unsigned 0x00000002; the negation is purely a column-side
  * convention.
  *
  * Round-trip safety: when `_dirty` is false, `serialize` returns the
  * original input bytes verbatim. When `_dirty` is true, it re-emits the
  * property stream from scratch via `writePropertyStream`. Both paths are
  * verified byte-identical against every row in a tested world.db
- * (174.6 MB, 11,667 rows; `npm test`).
+ * (`npm test`).
  *
  * Re-exports the most commonly used types so callers can do
  *   import { UnrealBlob, FName, FGuid, ObjectRef, ... } from 'wscodec';
@@ -38,7 +38,7 @@ import { readPropertyStream, writePropertyStream } from './properties.mjs';
 // Convenience re-exports for the public API surface.
 export { Cursor, Writer } from './io.mjs';
 export { FName, FGuid } from './primitives.mjs';
-export { StructValue, STRUCT_HANDLERS } from './structs.mjs';
+export { StructValue, STRUCT_HANDLERS, registerStructHandler } from './structs.mjs';
 export { ObjectRef, SoftObjectRef, FTextValue, OpaqueValue } from './values.mjs';
 export {
   PropertyTag, Property,
@@ -69,10 +69,25 @@ export class UnrealBlob {
     this._dirty = false;
   }
 
-  get kind()      { return NAME; }
+  /**
+   * Codec-adapter name (`'unreal-properties'`). Surfaced for registries that
+   * dispatch on a codec's `kind` field; matches the `name` on the bare
+   * `codec` adapter exported at the bottom of this module.
+   */
+  get kind() { return NAME; }
+
+  /**
+   * Number of bytes the blob was decoded from (`_raw.length`), or 0 if the
+   * blob was constructed without an input buffer. NOT the post-serialize
+   * size; for that, call `serialize().length`.
+   */
   get totalSize() { return this._raw ? this._raw.length : 0; }
 
-  /** First top-level property with the given name, or null. */
+  /**
+   * First TOP-LEVEL property with the given tag name, or null. Does NOT
+   * traverse into embedded streams, struct values, array elements, or map
+   * entries. Use `findPropertyDeep` to walk the full tree.
+   */
   findProperty(propName) {
     for (const p of this.properties) {
       if (p.tag && p.tag.name && p.tag.name.value === propName) return p;
@@ -80,6 +95,23 @@ export class UnrealBlob {
     return null;
   }
 
+  /**
+   * First property with the given tag name found anywhere in the property
+   * tree, or null. Performs a depth-first traversal across:
+   *
+   *   - top-level properties
+   *   - ObjectRef.embedded streams (nested ObjectProperty values)
+   *   - StructValue.value when it's a tagged property array
+   *   - ArrayProperty / SetProperty struct elements
+   *   - MapProperty entries: both key (if StructValue) and value
+   *
+   * Returns the first match in traversal order; later matches are not
+   * surfaced. For all matches, walk the tree manually.
+   */
+  findPropertyDeep(propName) {
+    return _findPropertyDeep(this.properties, propName);
+  }
+
   static detect(u8) {
     if (!u8 || u8.length < VERSION_HEADER_SIZE) return false;
     const dv = new DataView(u8.buffer, u8.byteOffset, u8.byteLength);
@@ -90,7 +122,7 @@ export class UnrealBlob {
    * Parse uncompressed property-stream bytes into an UnrealBlob.
    *
    * On unrecoverable structural failure the returned blob has `error` set
-   * and `properties` empty — callers that need a hard failure should check
+   * and `properties` empty. Callers that need a hard failure should check
    * `blob.error` after decode.
    */
   static decode(u8) {
@@ -125,14 +157,27 @@ export class UnrealBlob {
   /**
    * Return the uncompressed property-stream bytes for this blob.
    *
-   * Pass-through when `_dirty` is false: returns the input bytes verbatim.
-   * Re-encodes from `properties` when `_dirty` is true. `bodyTrailing`, if
-   * present, is appended after the None terminator + 4-byte FName.Number
+   * Pass-through when `_dirty` is false: returns the input bytes verbatim,
+   * even if `error` is set (the original bytes round-trip even when decode
+   * was incomplete). Re-encodes from `properties` when `_dirty` is true,
+   * appending `bodyTrailing` after the None terminator + 4-byte FName.Number
    * trailer that `writePropertyStream` emits.
+   *
+   * Throws if `_dirty` is true AND `error` is set: re-emitting would produce
+   * a malformed stream (the property tree is empty after a structural
+   * failure). Clear `.error` first if you intentionally want to emit from
+   * an externally-constructed properties array.
    */
   serialize() {
     if (!this._dirty && this._raw instanceof Uint8Array) return this._raw;
 
+    if (this.error != null) {
+      throw new Error(
+        `UnrealBlob.serialize: cannot re-emit a blob with decode error (${this.error}). ` +
+        `Leave _dirty=false to pass through _raw verbatim, or clear .error if you've replaced .properties manually.`
+      );
+    }
+
     const w = new Writer(this._raw?.length || 256);
     w.writeUint32(this.versionTag);
     writePropertyStream(w, this.properties, /*emitTerminatorTrailer=*/true);
@@ -143,6 +188,59 @@ export class UnrealBlob {
   }
 }
 
+// Deep-search helper. Walks the property tree in depth-first order and
+// returns the first Property whose tag.name matches. Kept out of the class
+// body so the recursion can reach into nested shapes uniformly without
+// having to thread `this` around.
+function _findPropertyDeep(properties, propName) {
+  if (!Array.isArray(properties)) return null;
+  for (const p of properties) {
+    if (p.tag && p.tag.name && p.tag.name.value === propName) return p;
+    const v = p.value;
+    if (v == null) continue;
+    // ObjectRef with embedded property stream.
+    if (v.embedded) {
+      const hit = _findPropertyDeep(v.embedded, propName);
+      if (hit) return hit;
+    }
+    // StructValue: .value is either a property array (unknown struct) or a
+    // plain binary record (known struct). Only the array form is searchable.
+    if (v._structName && Array.isArray(v.value)) {
+      const hit = _findPropertyDeep(v.value, propName);
+      if (hit) return hit;
+    }
+    // ArrayProperty / SetProperty struct elements + ObjectRef embeddeds.
+    if (Array.isArray(v.elements)) {
+      for (const e of v.elements) {
+        if (e && e._structName && Array.isArray(e.value)) {
+          const hit = _findPropertyDeep(e.value, propName);
+          if (hit) return hit;
+        }
+        if (e && e.embedded) {
+          const hit = _findPropertyDeep(e.embedded, propName);
+          if (hit) return hit;
+        }
+      }
+    }
+    // MapProperty entries: both key (if StructValue) and value can hold a
+    // nested property stream.
+    if (Array.isArray(v.entries)) {
+      for (const ent of v.entries) {
+        if (ent.key && ent.key._structName && Array.isArray(ent.key.value)) {
+          const hit = _findPropertyDeep(ent.key.value, propName);
+          if (hit) return hit;
+        }
+        const ev = ent.value;
+        if (ev && ev._structName && Array.isArray(ev.value)) {
+          const hit = _findPropertyDeep(ev.value, propName);
+          if (hit) return hit;
+        }
+      }
+    }
+  }
+  return null;
+}
+
 // Generic codec-adapter shape (name + detect + decode + encode), suitable
 // for plugging into any registry that uses that quartet. Operates on the
 // uncompressed bytes that `UnrealBlob.decode` accepts; for callers reading