wscodec 0.2.0 → 0.3.1

package/README.md

@@ -90,11 +90,15 @@ returns an `UnrealBlob` with:
 | `error` | `string \| null` | populated when structural decode failed |
 | `_raw` | `Uint8Array` | the input bytes, retained for pass-through serialize |
 | `_dirty` | `boolean` | set by mutating callers to force re-encode |
+| `_recomputeSizes` | `boolean` | when true, every `tag.size` is rewritten from the actual value byte count on serialize. Set automatically by `jsonToBlob`; see [Editing](#editing) |
 
-`blob.serialize()` returns a `Uint8Array`. When `_dirty` is false it
-returns `_raw` verbatim (byte-identical pass-through). When `_dirty`
-is true it re-emits the property stream from `properties` via
-`writePropertyStream`.
+`blob.serialize(options?)` returns a `Uint8Array`. When `_dirty` is
+false it returns `_raw` verbatim (byte-identical pass-through). When
+`_dirty` is true it re-emits the property stream from `properties` via
+`writePropertyStream`. Pass `{ recomputeSizes: true }` (or set
+`blob._recomputeSizes`) to recompute every `tag.size` from the actual
+encoded value bytes — required after any edit that changes a
+variable-length field.
 
 `blob.findProperty(name)` returns the first top-level property whose
 tag name matches, or `null`. It does NOT traverse into embedded
@@ -114,10 +118,10 @@ JavaScript shape depends on the tag's type:
 | `StrProperty`, `NameProperty` | string / `FName` |
 | `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 }, ...]` and `.removed: [...]` |
 | `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) |
+| `TextProperty` | `FTextValue` (handles UE4 FText history types -1, 0, 1, 2, 4) |
 | anything wscodec couldn't structurally decode | `OpaqueValue`. Bytes retained verbatim |
 
 Submodule re-exports make the value classes importable directly:
@@ -126,6 +130,8 @@ Submodule re-exports make the value classes importable directly:
 import { ObjectRef, SoftObjectRef, FTextValue, OpaqueValue, StructValue } from 'wscodec';
 import { PropertyTag, ArrayValue, SetValue, MapValue } from 'wscodec';
 import { FName, FGuid } from 'wscodec';
+import { blobToJSON, jsonToBlob, blobToJSONString, jsonStringToBlob,
+         jsonReplacer, jsonReviver } from 'wscodec';
 ```
 
 Lower-level helpers (`Cursor`, `Writer`, `readPropertyStream`,
@@ -155,11 +161,77 @@ 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.
 
+### JSON conversion
+
+The object tree round-trips through JSON. This is the recommended path
+for editing: the tree becomes plain JSON, edits are plain JS object
+mutations, and the JSON-to-blob pipeline handles size recomputation,
+sentinel substitution for `-0` / `Infinity` / `NaN`, and base64 for the
+small fraction of bytes that the codec doesn't structurally decode.
+
+```js
+import {
+  UnrealBlob,
+  blobToJSON, jsonToBlob,
+  blobToJSONString, jsonStringToBlob,
+} from 'wscodec';
+
+const blob = UnrealBlob.decode(uncompressedBytes);
+
+// Object-tree round trip (preserves -0 in memory via Object.is, but a
+// naive JSON.stringify on the result would lose it; see below).
+const obj  = blobToJSON(blob);
+const blob2 = jsonToBlob(obj);
+
+// String round trip — use this whenever the JSON crosses a stringify
+// boundary (file I/O, sockets, etc.). The sentinels guard non-finite
+// numbers and -0 across the conversion.
+const json = blobToJSONString(blob, 2 /* optional indent */);
+const blob3 = jsonStringToBlob(json);
+
+// blob3.serialize() reproduces the input bytes (modulo the wire's
+// optional "inflated tag.size" lies, which jsonToBlob normalizes).
+```
+
+`blobToJSON` produces a plain-object tree with:
+
+- `FName` values flattened to bare strings (with metadata-object fallback only when `isUnicode`/`isNull`/`number` aren't defaults)
+- `FGuid` flattened to its canonical 8-4-4-4-12 hex string
+- `Int64Property` / `UInt64Property` / `DateTime` / `Timespan` as decimal strings
+- `StructValue` discriminated by `form: "binary" | "propStream" | "decodeError"`
+- `OpaqueValue` as `{ _opaque: true, bytes: <base64>, reason }`
+- `bodyTrailing` as base64 when present
+- `ArrayValue._perElementTrailings` (the `JianZhuInstYuanXings` per-piece placement cache) as `{ transforms: [[16 floats], …], ids: [u32, …], aux: [[16 floats], …] }` — see [Round-trip guarantees](#round-trip-guarantees) for the NaN-bit-preservation note
+
+`jsonToBlob` returns an `UnrealBlob` with `_dirty = true` and
+`_recomputeSizes = true`, so `blob.serialize()` will rewrite every
+`tag.size` from the actual encoded value bytes. That makes the JSON
+pipeline safe for arbitrary edits — including ones that change FString
+lengths, add/remove array elements, or grow nested structs.
+
+If you need to build a larger JSON envelope around an `UnrealBlob`
+(e.g., a full db export), use `jsonReplacer` / `jsonReviver` with your
+own `JSON.stringify` / `JSON.parse` calls so the same `-0`/`NaN`/`Infinity`
+sentinels are applied uniformly:
+
+```js
+import { blobToJSON, jsonToBlob, jsonReplacer, jsonReviver } from 'wscodec';
+
+const envelope = { actor_serial: 17, blob: blobToJSON(blob), other: '...' };
+const text     = JSON.stringify(envelope, jsonReplacer);
+const parsed   = JSON.parse(text, jsonReviver);
+const blob2    = jsonToBlob(parsed.blob);
+```
+
+The codec is consumable as a submodule: `import { blobToJSON } from 'wscodec/json';`.
+
 ### 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.
+Two paths are supported. For most edits, **go through JSON** ([§
+JSON conversion](#json-conversion)) — it handles size recomputation
+and numeric edge cases automatically. For low-level edits that
+change zero-cost fields (numbers, bools, single bytes), you can also
+mutate the object tree directly.
 
 ```js
 import { UnrealBlob, FName } from 'wscodec';
@@ -186,31 +258,38 @@ 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.
+// Tell the encoder to (a) re-emit from properties at all, and (b)
+// recompute every tag.size from the actual encoded value bytes. The
+// recompute is REQUIRED whenever any edit could change a value's
+// encoded byte count (FStrings, FText, array length, nested structs).
+// It's free when nothing changed in size, so just turning it on by
+// default for any direct edit is the safest path.
 blob._dirty = true;
+blob._recomputeSizes = 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.
+- `_dirty` and `_recomputeSizes` live 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`.
+- **Anything that changes encoded byte count requires `_recomputeSizes = true`.**
+  Lengthening an FString, adding an array element, swapping a known-
+  binary struct for a propStream — any of these without recompute leaves
+  every dependent `tag.size` stale, and Soulmask's reader will walk off
+  the end of the value into the next property's bytes. Symptom: edited
+  blob loads but with reset/missing fields downstream of the edit.
+- The JSON pipeline (`jsonToBlob`, `jsonStringToBlob`) sets this for you.
 - `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
+  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
@@ -218,9 +297,12 @@ Gotchas:
   (`|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`.
+`serialize()` is byte-identical to a fresh `decode + serialize` cycle
+on its output, verified on every row of the tested `world.db`. With
+recompute enabled the encoder may produce shorter bytes than the
+original when the wire's `tag.size` over-stated the actual value byte
+count (some Soulmask Maps do this); the bytes still decode to the same
+object tree, and tested in-game loads accept both forms.
 
 ## LZ4 integration
 
@@ -273,9 +355,11 @@ bytes if you need that).
 
 For every row in the tested `world.db`:
 
-- `UnrealBlob.decode(inner)` succeeds without `error` set.
-- `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.
+- `UnrealBlob.decode(inner)` succeeds without `error` set and produces zero `OpaqueValue` entries (every property type decodes structurally).
+- `blob.serialize()` with `_dirty = false` returns the input bytes byte-identical (pass-through).
+- `blob.serialize()` with `_dirty = true` and `_recomputeSizes = false` re-emits from `properties` and is byte-identical to the input.
+- `blob.serialize()` with `_dirty = true` and `_recomputeSizes = true` (the JSON-pipeline default) re-emits with `tag.size` rewritten from the actual value byte count. Decoding the result yields the same property tree as the input; the wire bytes may differ where the input's stored sizes over-stated the actual value byte count (some Soulmask Maps do this).
+- The same `UnrealBlob` going through `blobToJSON` → `jsonToBlob` → `serialize` yields bytes that decode to the same tree as the input.
 
 Coverage includes every known Soulmask wire-format quirk:
 
@@ -293,11 +377,22 @@ Coverage includes every known Soulmask wire-format quirk:
   `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).
+  each ObjectProperty element. The codec decodes the block structurally
+  into `{ transforms: [[16 floats], …], ids: [u32, …], aux: [[16 floats], …] }`.
+  The transforms are row-major UE `FMatrix`-style 4×4 matrices; the
+  translation lives at indices 12, 13, 14. Non-canonical NaN bit
+  patterns (observed `0xFFFFFFFF` as a sentinel in aux data) are
+  preserved via `{ $nanBits: u32 }` wrappers, because JS `Number`
+  collapses all NaNs to `0x7FC00000`. In-game testing confirms Soulmask
+  renders building pieces from their `RelativeTransform` property (a
+  `StructProperty<Transform>` in `MapInstJianZhuDataList`); the
+  per-element trailings carry the same data as a render-side cache, so
+  edits that move pieces must update both.
 - **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
+  1 (`FTextHistory_NamedFormat` — a format pattern plus a
+  `TMap<FString, FFormatArgumentValue>` of named arguments), 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.
@@ -311,23 +406,66 @@ Coverage includes every known Soulmask wire-format quirk:
   actual 636422); pair shapes are detected by peeking at the next
   bytes rather than trusting the declared size.
 
-## Running the test
+## Running the tests
 
 ```sh
 git clone https://github.com/auroris/SoulmaskCodec.git
 cd SoulmaskCodec
 npm install
+
+# Byte-identical roundtrip across every row of a world.db.
 npm test                                  # looks for world.db two dirs up by default
-# or
 node test/test-roundtrip.mjs /path/to/world.db
+
+# JSON-pipeline roundtrip. Encodes both sides with recomputeSizes=true
+# and compares; verifies blobToJSON ↔ jsonToBlob is lossless.
+npm run test:json -- /path/to/world.db
+npm run test:json-spot -- /path/to/world.db   # spot-check on rows that exercise each code path
 ```
 
 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 package root the tests will surface that with a clear error. See
 the Setup section above for the build-tools prerequisite on Windows.
 
+## Bundled scripts
+
+The repo also ships full db ↔ JSON utilities under [scripts/](scripts/).
+These are NOT shipped in the npm package (the codec stays zero-dep); they
+live in the repo as reference workflows.
+
+```sh
+# Dump every row of a world.db (LZ4-decompressing actor_data and decoding
+# through wscodec where possible) to a single JSON file.
+npm run export-db -- /path/to/world.db world.json
+
+# Inverse: rebuild a SQLite db from the JSON export. The npm script
+# already runs node with --max-old-space-size=4096 (necessary for
+# multi-hundred-MB exports).
+npm run import-db -- world.json /path/to/new.db
+
+# Diff two world.db files at the uncompressed level (tolerates LZ4 re-compression).
+node scripts/diff-dbs.mjs a.db b.db
+
+# Search every decoded blob for a substring (custom names, UIDs, asset paths).
+node scripts/find-string.mjs /path/to/world.db "Claude's Chest"
+
+# Pretty-print one actor's full property tree.
+node scripts/dump-actor.mjs /path/to/world.db <actor_serial> [out.json]
+
+# Merge every workbench access log, NPC work log, and clan log into a single
+# timestamp-sorted .log file. .NET ticks → ISO-8601 UTC; FText placeholders
+# substituted into their NamedFormat / OrderedFormat templates.
+npm run dump-logs -- /path/to/world.db world.log
+```
+
+The export/import pair has been validated end-to-end against Soulmask
+itself: a full db → JSON → db round-trip produces a save that the game
+loads cleanly. See [docs/helpers-handoff.md](docs/helpers-handoff.md)
+for notes on building a higher-level save-edit helper library on top of
+the codec.
+
 ## License
 
 MIT.

package/json.mjs

@@ -0,0 +1,614 @@
+/**
+ * JSON converter for the wscodec object tree. Part of the public codec API.
+ *
+ *   blobToJSON(blob)        UnrealBlob → JSON-safe plain object
+ *   jsonToBlob(json)        plain object → UnrealBlob
+ *   blobToJSONString(blob)  shortcut: blobToJSON + JSON.stringify (with -0/NaN/Inf handling)
+ *   jsonStringToBlob(str)   shortcut: JSON.parse (with -0/NaN/Inf handling) + jsonToBlob
+ *
+ * Round-trip guarantee: when the input bytes decode cleanly, the chain
+ *   bytes → UnrealBlob.decode → blobToJSON → JSON.stringify
+ *         → JSON.parse → jsonToBlob → UnrealBlob.serialize
+ * produces the same bytes as the input. Verified on every row of every tested
+ * Soulmask world.db (`node test/test-json-full.mjs <path>`).
+ *
+ * Design rules:
+ *   - Convert as much as possible to structured JSON. Base64 is reserved for
+ *     genuinely undecoded content: OpaqueValue (codec gave up on this slot)
+ *     and ArrayValue._perElementTrailings (JianZhuInstYuanXings placement
+ *     blocks whose semantics we don't decode).
+ *   - Preserve every wire-form distinction needed for byte-identical round
+ *     trip: FString isNull flags, ObjectRef kindOnePrefix /
+ *     hasTerminatorTrailer, StructValue propStream-vs-binary form, FText
+ *     historyType variants, ArrayValue innerTag for struct arrays,
+ *     MapProperty<StructProperty,_> key/value conventions, etc.
+ *   - JSON shapes are tagged with discriminators where the decoder needs to
+ *     dispatch: `form` on StructValue ('binary' | 'propStream' | 'decodeError'),
+ *     `historyType` on FTextValue, `_opaque` on OpaqueValue payloads.
+ *
+ * Numeric edge cases (-0, NaN, +/-Infinity) round-trip through
+ * blobToJSONString / jsonStringToBlob via a sentinel substitution; the bare
+ * blobToJSON / jsonToBlob pair preserves them inside the JS object tree
+ * (because Object.is(-0, -0)) but a naive JSON.stringify would lose them.
+ */
+
+import { FName, FGuid }                                       from './primitives.mjs';
+import { StructValue }                                        from './structs.mjs';
+import { PropertyTag, Property, ArrayValue, SetValue, MapValue } from './properties.mjs';
+import { ObjectRef, SoftObjectRef, FTextValue, OpaqueValue }  from './values.mjs';
+// Intentional cycle: UnrealBlob is defined in wscodec.mjs, and wscodec.mjs
+// re-exports this module's symbols. ESM live bindings make this safe as long
+// as UnrealBlob is only USED inside function bodies (deferred), which it is.
+import { UnrealBlob } from './wscodec.mjs';
+
+// ── base64 helpers (Node Buffer) ────────────────────────────────────────────
+function b64encode(u8) { return Buffer.from(u8.buffer, u8.byteOffset, u8.byteLength).toString('base64'); }
+function b64decode(s)  { return new Uint8Array(Buffer.from(s, 'base64')); }
+
+// ── FName helpers ───────────────────────────────────────────────────────────
+// Names round-trip as bare strings in the common case. When isUnicode or
+// isNull is non-default, fall back to an object form so the wire flags survive.
+function nameJSON(fn) {
+  if (fn == null) return null;
+  if (fn instanceof FName) {
+    if (!fn.isUnicode && !fn.isNull && (fn.number | 0) === 0) return fn.value;
+    return { value: fn.value, isUnicode: fn.isUnicode, isNull: fn.isNull, number: fn.number };
+  }
+  return String(fn);
+}
+function nameFromJSON(j) {
+  if (j == null) return null;
+  return FName.from(j);
+}
+
+// ── PropertyTag JSON ────────────────────────────────────────────────────────
+function tagToJSON(tag) {
+  const j = { name: nameJSON(tag.name), type: nameJSON(tag.type), size: tag.size };
+  if (tag.arrayIndex) j.arrayIndex = tag.arrayIndex;
+  switch (tag.type?.value) {
+    case 'StructProperty': j.structName = nameJSON(tag.structName); j.structGuid = tag.structGuid?.value ?? null; break;
+    case 'BoolProperty':   j.boolVal = tag.boolVal; break;
+    case 'ByteProperty':
+    case 'EnumProperty':   j.enumName = nameJSON(tag.enumName); break;
+    case 'ArrayProperty':
+    case 'SetProperty':    j.innerType = nameJSON(tag.innerType); break;
+    case 'MapProperty':    j.innerType = nameJSON(tag.innerType); j.valueType = nameJSON(tag.valueType); break;
+  }
+  if (tag.hasPropertyGuid) {
+    j.hasPropertyGuid = true;
+    j.propertyGuid = tag.propertyGuid?.value ?? null;
+  }
+  return j;
+}
+function tagFromJSON(j) {
+  const tag = new PropertyTag({
+    name: nameFromJSON(j.name),
+    type: nameFromJSON(j.type),
+    size: j.size,
+    arrayIndex: j.arrayIndex || 0,
+    hasPropertyGuid: !!j.hasPropertyGuid,
+  });
+  switch (tag.type?.value) {
+    case 'StructProperty': tag.structName = nameFromJSON(j.structName); tag.structGuid = j.structGuid ? new FGuid(j.structGuid) : null; break;
+    case 'BoolProperty':   tag.boolVal = j.boolVal; break;
+    case 'ByteProperty':
+    case 'EnumProperty':   tag.enumName = nameFromJSON(j.enumName); break;
+    case 'ArrayProperty':
+    case 'SetProperty':    tag.innerType = nameFromJSON(j.innerType); break;
+    case 'MapProperty':    tag.innerType = nameFromJSON(j.innerType); tag.valueType = nameFromJSON(j.valueType); break;
+  }
+  if (tag.hasPropertyGuid) tag.propertyGuid = j.propertyGuid ? new FGuid(j.propertyGuid) : null;
+  return tag;
+}
+
+// ── Value JSON, dispatching on tag.type and tag.innerType/valueType ─────────
+function valueToJSON(tag, value) {
+  if (value instanceof OpaqueValue) {
+    return { _opaque: true, bytes: b64encode(value.bytes), reason: value.reason };
+  }
+  const t = tag.type.value;
+  switch (t) {
+    case 'IntProperty': case 'Int8Property': case 'Int16Property':
+    case 'UInt16Property': case 'UInt32Property':
+    case 'FloatProperty': case 'DoubleProperty':
+    case 'BoolProperty':
+      return value;
+    case 'Int64Property': case 'UInt64Property':
+      return value;                                // already string
+    case 'StrProperty':
+      return value;                                // bare string
+    case 'NameProperty':
+    case 'EnumProperty':
+      return nameJSON(value);
+    case 'ByteProperty':
+      // enumName==='None' → numeric byte, else FName.
+      return tag.enumName?.value === 'None' ? value : nameJSON(value);
+    case 'ObjectProperty': case 'ClassProperty':
+    case 'WeakObjectProperty': case 'LazyObjectProperty':
+    case 'WSObjectProperty':
+      return objectRefToJSON(value);
+    case 'SoftObjectProperty': case 'SoftClassProperty':
+      return { assetPath: value.assetPath, subPath: value.subPath };
+    case 'StructProperty':
+      return structValueToJSON(value);
+    case 'ArrayProperty':
+      return arrayValueToJSON(value, tag);
+    case 'SetProperty':
+      return setValueToJSON(value, tag);
+    case 'MapProperty':
+      return mapValueToJSON(value, tag);
+    case 'TextProperty':
+      return fTextToJSON(value);
+    default:
+      throw new Error(`valueToJSON: unsupported type ${t}`);
+  }
+}
+
+function valueFromJSON(tag, j) {
+  if (j && typeof j === 'object' && !Array.isArray(j) && j._opaque) {
+    return new OpaqueValue(b64decode(j.bytes), j.reason ?? null);
+  }
+  const t = tag.type.value;
+  switch (t) {
+    case 'IntProperty': case 'Int8Property': case 'Int16Property':
+    case 'UInt16Property': case 'UInt32Property':
+    case 'FloatProperty': case 'DoubleProperty':
+    case 'BoolProperty':
+      return j;
+    case 'Int64Property': case 'UInt64Property':
+      return String(j);
+    case 'StrProperty':
+      return j;
+    case 'NameProperty':
+    case 'EnumProperty':
+      return nameFromJSON(j);
+    case 'ByteProperty':
+      return tag.enumName?.value === 'None' ? j : nameFromJSON(j);
+    case 'ObjectProperty': case 'ClassProperty':
+    case 'WeakObjectProperty': case 'LazyObjectProperty':
+    case 'WSObjectProperty':
+      return objectRefFromJSON(j);
+    case 'SoftObjectProperty': case 'SoftClassProperty':
+      return new SoftObjectRef({ assetPath: j.assetPath, subPath: j.subPath });
+    case 'StructProperty':
+      return structValueFromJSON(j, tag.structName?.value);
+    case 'ArrayProperty':
+      return arrayValueFromJSON(j, tag);
+    case 'SetProperty':
+      return setValueFromJSON(j, tag);
+    case 'MapProperty':
+      return mapValueFromJSON(j, tag);
+    case 'TextProperty':
+      return fTextFromJSON(j);
+    default:
+      throw new Error(`valueFromJSON: unsupported type ${t}`);
+  }
+}
+
+// ── ObjectRef ───────────────────────────────────────────────────────────────
+function objectRefToJSON(v) {
+  if (!(v instanceof ObjectRef)) throw new Error(`objectRefToJSON: expected ObjectRef, got ${v?.constructor?.name}`);
+  const j = { kind: v._objectKind };
+  if (v._kindOnePrefix != null) j.kindOnePrefix = v._kindOnePrefix;
+  if (v.path !== null) j.path = v.path;
+  if (v._pathIsNull) j.pathIsNull = true;
+  if (v.classPath !== null) j.classPath = v.classPath;
+  if (v._classPathIsNull) j.classPathIsNull = true;
+  if (Array.isArray(v.embedded)) {
+    j.embedded = v.embedded.map(propertyToJSON);
+    if (v.terminated) j.embeddedTerminated = true;
+    if (v.hasTerminatorTrailer) j.hasTerminatorTrailer = true;
+  }
+  return j;
+}
+function objectRefFromJSON(j) {
+  return new ObjectRef({
+    kind: j.kind,
+    kindOnePrefix: 'kindOnePrefix' in j ? j.kindOnePrefix : null,
+    path: 'path' in j ? j.path : null,
+    pathIsNull: !!j.pathIsNull,
+    classPath: 'classPath' in j ? j.classPath : null,
+    classPathIsNull: !!j.classPathIsNull,
+    embedded: Array.isArray(j.embedded) ? j.embedded.map(propertyFromJSON) : null,
+    terminated: !!j.embeddedTerminated,
+    hasTerminatorTrailer: !!j.hasTerminatorTrailer,
+  });
+}
+
+// ── StructValue ─────────────────────────────────────────────────────────────
+// Three forms, distinguished by the `form` discriminator:
+//   "binary"     — STRUCT_HANDLERS produced a plain object/string for this struct
+//   "propStream" — unknown struct name, decoded as a nested property stream
+//   "decodeError"— struct decode failed; opaqueTail holds the leftover bytes
+function structValueToJSON(v) {
+  if (!(v instanceof StructValue)) throw new Error(`structValueToJSON: expected StructValue, got ${v?.constructor?.name}`);
+  if (v._structDecodeError) {
+    return {
+      form: 'decodeError',
+      error: v._structDecodeError,
+      opaqueTail: v._opaqueTail ? b64encode(v._opaqueTail) : null,
+    };
+  }
+  if (Array.isArray(v.value)) {
+    return {
+      form: 'propStream',
+      terminated: !!v.terminated,
+      properties: v.value.map(propertyToJSON),
+    };
+  }
+  // Binary handler. Special-case value shapes that aren't plain objects:
+  //   Guid → FGuid (has .value); we JSON it as a bare string
+  //   DateTime/Timespan → already string
+  let jval = v.value;
+  if (v.value instanceof FGuid) jval = v.value.value;
+  return { form: 'binary', value: jval };
+}
+function structValueFromJSON(j, structName) {
+  if (j.form === 'decodeError') {
+    return new StructValue(structName, {
+      value: [], decodeError: j.error,
+      opaqueTail: j.opaqueTail ? b64decode(j.opaqueTail) : null,
+    });
+  }
+  if (j.form === 'propStream') {
+    return new StructValue(structName, {
+      value: j.properties.map(propertyFromJSON),
+      terminated: !!j.terminated,
+    });
+  }
+  if (j.form === 'binary') {
+    let val = j.value;
+    if (structName === 'Guid' && typeof val === 'string') val = new FGuid(val);
+    return new StructValue(structName, { value: val });
+  }
+  throw new Error(`structValueFromJSON: unknown form '${j.form}'`);
+}
+
+// ── ArrayValue / SetValue / MapValue ────────────────────────────────────────
+function arrayValueToJSON(v, tag) {
+  if (!(v instanceof ArrayValue)) throw new Error(`arrayValueToJSON: expected ArrayValue, got ${v?.constructor?.name}`);
+  const innerType = tag.innerType.value;
+  const j = { elements: v.elements.map(e => arrayElementToJSON(e, innerType, v._arrayInnerTag)) };
+  if (v._arrayInnerTag) j.innerTag = tagToJSON(v._arrayInnerTag);
+  if (v._perElementTrailings) {
+    // Per-element placement-binary block (JianZhuInstYuanXings). Each entry is
+    // either null OR { transforms: [[16 floats], …], ids: [u32, …], aux: [[16 floats], …] }.
+    // Header and strides are constants on the wire — synthesized on write.
+    j.perElementTrailings = v._perElementTrailings.map(t => {
+      if (t == null) return null;
+      return { transforms: t.transforms, ids: t.ids, aux: t.aux };
+    });
+  }
+  return j;
+}
+function arrayValueFromJSON(j, tag) {
+  const innerType = tag.innerType.value;
+  const innerTag = j.innerTag ? tagFromJSON(j.innerTag) : null;
+  const elements = j.elements.map(e => arrayElementFromJSON(e, innerType, innerTag));
+  let perElementTrailings = null;
+  if (Array.isArray(j.perElementTrailings)) {
+    perElementTrailings = j.perElementTrailings.map(t => {
+      if (t == null) return null;
+      return { transforms: t.transforms, ids: t.ids, aux: t.aux };
+    });
+  }
+  return new ArrayValue({ elements, innerTag, perElementTrailings });
+}
+
+// Array/Set element converters. For StructProperty arrays the element is a
+// StructValue (the struct-array path always emits one inner PropertyTag and
+// uses STRUCT_HANDLERS or a property stream per element).
+function arrayElementToJSON(e, innerType, innerTag) {
+  if (innerType === 'StructProperty') return structValueToJSON(e);
+  switch (innerType) {
+    case 'IntProperty': case 'Int8Property': case 'Int16Property':
+    case 'UInt16Property': case 'UInt32Property':
+    case 'FloatProperty': case 'DoubleProperty':
+    case 'BoolProperty': case 'ByteProperty':
+      return e;
+    case 'Int64Property': case 'UInt64Property':
+      return e;                                  // already string
+    case 'StrProperty':
+      return e;
+    case 'NameProperty': case 'EnumProperty':
+      return nameJSON(e);
+    case 'TextProperty':
+      if (e instanceof OpaqueValue) return { _opaque: true, bytes: b64encode(e.bytes), reason: e.reason };
+      return fTextToJSON(e);
+    case 'ObjectProperty': case 'ClassProperty':
+    case 'WeakObjectProperty': case 'LazyObjectProperty':
+    case 'WSObjectProperty':
+      return objectRefToJSON(e);
+    case 'SoftObjectProperty': case 'SoftClassProperty':
+      return { assetPath: e.assetPath, subPath: e.subPath };
+    default:
+      throw new Error(`arrayElementToJSON: unsupported innerType ${innerType}`);
+  }
+}
+function arrayElementFromJSON(j, innerType, innerTag) {
+  if (innerType === 'StructProperty') return structValueFromJSON(j, innerTag?.structName?.value);
+  if (j && typeof j === 'object' && !Array.isArray(j) && j._opaque) {
+    return new OpaqueValue(b64decode(j.bytes), j.reason ?? null);
+  }
+  switch (innerType) {
+    case 'IntProperty': case 'Int8Property': case 'Int16Property':
+    case 'UInt16Property': case 'UInt32Property':
+    case 'FloatProperty': case 'DoubleProperty':
+    case 'BoolProperty': case 'ByteProperty':
+      return j;
+    case 'Int64Property': case 'UInt64Property':
+      return String(j);
+    case 'StrProperty':
+      return j;
+    case 'NameProperty': case 'EnumProperty':
+      return nameFromJSON(j);
+    case 'TextProperty':
+      return fTextFromJSON(j);
+    case 'ObjectProperty': case 'ClassProperty':
+    case 'WeakObjectProperty': case 'LazyObjectProperty':
+    case 'WSObjectProperty':
+      return objectRefFromJSON(j);
+    case 'SoftObjectProperty': case 'SoftClassProperty':
+      return new SoftObjectRef({ assetPath: j.assetPath, subPath: j.subPath });
+    default:
+      throw new Error(`arrayElementFromJSON: unsupported innerType ${innerType}`);
+  }
+}
+
+function setValueToJSON(v, tag) {
+  return {
+    removed:  v.removed.map(e => setElementToJSON(e, tag.innerType.value)),
+    elements: v.elements.map(e => setElementToJSON(e, tag.innerType.value)),
+  };
+}
+function setValueFromJSON(j, tag) {
+  return new SetValue({
+    removed:  j.removed.map(e => setElementFromJSON(e, tag.innerType.value)),
+    elements: j.elements.map(e => setElementFromJSON(e, tag.innerType.value)),
+  });
+}
+// Set<StructProperty> elements are raw FGuid values (per readSetElement);
+// other inner types share the array-element shape.
+function setElementToJSON(e, innerType) {
+  if (innerType === 'StructProperty') return e;       // Guid string
+  return arrayElementToJSON(e, innerType, null);
+}
+function setElementFromJSON(j, innerType) {
+  if (innerType === 'StructProperty') return j;       // Guid string
+  return arrayElementFromJSON(j, innerType, null);
+}
+
+function mapValueToJSON(v, tag) {
+  const keyType = tag.innerType.value;
+  const valType = tag.valueType.value;
+  return {
+    removed: v.removed.map(k => mapElementToJSON(k, keyType, /*isKey=*/true)),
+    entries: v.entries.map(e => ({
+      key:   mapElementToJSON(e.key,   keyType, true),
+      value: mapElementToJSON(e.value, valType, false),
+    })),
+  };
+}
+function mapValueFromJSON(j, tag) {
+  const keyType = tag.innerType.value;
+  const valType = tag.valueType.value;
+  return new MapValue({
+    removed: j.removed.map(k => mapElementFromJSON(k, keyType, true)),
+    entries: j.entries.map(e => ({
+      key:   mapElementFromJSON(e.key,   keyType, true),
+      value: mapElementFromJSON(e.value, valType, false),
+    })),
+  });
+}
+// Map<StructProperty,_> keys are always 16-byte FGuids (string). Map values
+// with StructProperty type are either a StructValue (propStream form) OR a
+// Guid string; we distinguish on JSON shape (object with form=propStream vs
+// bare string).
+function mapElementToJSON(v, type, isKey) {
+  if (type === 'StructProperty') {
+    if (isKey) return v;                                            // Guid string
+    if (v instanceof StructValue) return structValueToJSON(v);
+    return v;                                                        // Guid string
+  }
+  return arrayElementToJSON(v, type, null);
+}
+function mapElementFromJSON(j, type, isKey) {
+  if (type === 'StructProperty') {
+    if (isKey) return j;
+    if (j && typeof j === 'object' && j.form) return structValueFromJSON(j, '(map value)');
+    return j;
+  }
+  return arrayElementFromJSON(j, type, null);
+}
+
+// ── FText ───────────────────────────────────────────────────────────────────
+function fTextToJSON(v) {
+  if (!(v instanceof FTextValue)) throw new Error(`fTextToJSON: expected FTextValue, got ${v?.constructor?.name}`);
+  const j = { flags: v.flags, historyType: v.historyType };
+  if (v.historyType === -1) {
+    if (v.displayString != null) {
+      j.displayString = v.displayString;
+      if (v._displayStringIsNull) j.displayStringIsNull = true;
+    } else {
+      j.displayString = null;
+    }
+  } else if (v.historyType === 0) {
+    j.namespace = v.namespace; if (v._namespaceIsNull) j.namespaceIsNull = true;
+    j.key = v.key;             if (v._keyIsNull) j.keyIsNull = true;
+    if (v.sourceString != null) {
+      j.sourceString = v.sourceString;
+      if (v._sourceStringIsNull) j.sourceStringIsNull = true;
+    } else {
+      j.sourceString = null;
+    }
+  } else if (v.historyType === 1) {
+    j.sourceFmt = fTextToJSON(v.sourceFmt);
+    j.arguments = v.arguments.map(a => fTextNamedArgToJSON(a));
+  } else if (v.historyType === 2) {
+    j.sourceFmt = fTextToJSON(v.sourceFmt);
+    j.arguments = v.arguments.map(a => fTextArgToJSON(a));
+  } else if (v.historyType === 4) {
+    j.sourceValue = fTextArgToJSON(v.sourceValue);
+    j.formatOptions = v.formatOptions;
+    if (v.culture != null) {
+      j.culture = v.culture;
+      if (v._cultureIsNull) j.cultureIsNull = true;
+    } else {
+      j.culture = null;
+    }
+  } else {
+    // Unknown historyType: codec stored remaining bytes verbatim in _raw.
+    j._raw = v._raw ? b64encode(v._raw) : null;
+  }
+  return j;
+}
+function fTextFromJSON(j) {
+  const ht = j.historyType;
+  if (ht === -1) {
+    return new FTextValue({
+      flags: j.flags, historyType: -1,
+      displayString: j.displayString ?? null,
+      displayStringIsNull: !!j.displayStringIsNull,
+    });
+  }
+  if (ht === 0) {
+    return new FTextValue({
+      flags: j.flags, historyType: 0,
+      namespace: j.namespace ?? '',       namespaceIsNull: !!j.namespaceIsNull,
+      key: j.key ?? '',                   keyIsNull: !!j.keyIsNull,
+      sourceString: j.sourceString ?? null, sourceStringIsNull: !!j.sourceStringIsNull,
+    });
+  }
+  if (ht === 1) {
+    return new FTextValue({
+      flags: j.flags, historyType: 1,
+      sourceFmt: fTextFromJSON(j.sourceFmt),
+      arguments: j.arguments.map(a => fTextNamedArgFromJSON(a)),
+    });
+  }
+  if (ht === 2) {
+    return new FTextValue({
+      flags: j.flags, historyType: 2,
+      sourceFmt: fTextFromJSON(j.sourceFmt),
+      arguments: j.arguments.map(a => fTextArgFromJSON(a)),
+    });
+  }
+  if (ht === 4) {
+    return new FTextValue({
+      flags: j.flags, historyType: 4,
+      sourceValue: fTextArgFromJSON(j.sourceValue),
+      formatOptions: j.formatOptions ?? null,
+      culture: j.culture ?? null,
+      cultureIsNull: !!j.cultureIsNull,
+    });
+  }
+  return new FTextValue({
+    flags: j.flags, historyType: ht,
+    _raw: j._raw ? b64decode(j._raw) : null,
+  });
+}
+function fTextArgToJSON(a) {
+  if (a.type === 4) return { type: 4, value: fTextToJSON(a.value) };
+  return { type: a.type, value: a.value };
+}
+function fTextArgFromJSON(a) {
+  if (a.type === 4) return { type: 4, value: fTextFromJSON(a.value) };
+  return { type: a.type, value: a.value };
+}
+// Named-format arg: same as positional but with a key FString prefix.
+function fTextNamedArgToJSON(a) {
+  const j = { key: a.key };
+  if (a.keyIsNull) j.keyIsNull = true;
+  j.type = a.type;
+  j.value = a.type === 4 ? fTextToJSON(a.value) : a.value;
+  return j;
+}
+function fTextNamedArgFromJSON(a) {
+  return {
+    key: a.key,
+    keyIsNull: !!a.keyIsNull,
+    type: a.type,
+    value: a.type === 4 ? fTextFromJSON(a.value) : a.value,
+  };
+}
+
+// ── Property ────────────────────────────────────────────────────────────────
+function propertyToJSON(p) {
+  return { tag: tagToJSON(p.tag), value: valueToJSON(p.tag, p.value) };
+}
+function propertyFromJSON(j) {
+  const tag = tagFromJSON(j.tag);
+  const value = valueFromJSON(tag, j.value);
+  return new Property(tag, value);
+}
+
+// ── Top-level UnrealBlob ────────────────────────────────────────────────────
+export function blobToJSON(blob) {
+  const j = {
+    versionTag: blob.versionTag,
+    terminated: !!blob.terminated,
+    properties: blob.properties.map(propertyToJSON),
+  };
+  if (blob.bodyTrailing && blob.bodyTrailing.length > 0) {
+    j.bodyTrailing = b64encode(blob.bodyTrailing);
+  }
+  return j;
+}
+export function jsonToBlob(j) {
+  const blob = new UnrealBlob({
+    versionTag: j.versionTag,
+    properties: j.properties.map(propertyFromJSON),
+    terminated: !!j.terminated,
+    bodyTrailing: j.bodyTrailing ? b64decode(j.bodyTrailing) : null,
+  });
+  blob._dirty = true;            // force re-encode path on serialize()
+  blob._recomputeSizes = true;   // JSON is the editing path; tag.size must
+                                 // be rewritten from actual value bytes.
+  return blob;
+}
+
+// ── -0 / NaN / Infinity preservation ────────────────────────────────────────
+// JSON drops sign on negative zero (`JSON.stringify(-0) === "0"`) and turns
+// non-finite numbers into `null`. UE serializes them verbatim, so any of these
+// in the data round-trips as a different bit pattern unless we intervene.
+// We substitute a sentinel string at stringify time and reverse it at parse
+// time, via JSON.stringify's replacer / JSON.parse's reviver hooks.
+//
+// The sentinel surface is space-bounded to make accidental collision with a
+// real string vanishingly unlikely. If you ever see a string field containing
+// these exact literals in your data, audit this list first.
+const NEG_ZERO_SENTINEL = ' __wscodec_neg_zero__ ';
+const POS_INF_SENTINEL  = ' __wscodec_pos_inf__ ';
+const NEG_INF_SENTINEL  = ' __wscodec_neg_inf__ ';
+const NAN_SENTINEL      = ' __wscodec_nan__ ';
+
+/**
+ * JSON.stringify replacer that substitutes sentinels for -0 / Infinity / NaN.
+ * Pass this to any JSON.stringify call that may contain wscodec-derived numbers
+ * (including a blob nested inside a larger envelope). Use jsonReviver on the
+ * matching JSON.parse to invert.
+ */
+export function jsonReplacer(_key, value) {
+  if (typeof value !== 'number') return value;
+  if (Object.is(value, -0)) return NEG_ZERO_SENTINEL;
+  if (value === Infinity)   return POS_INF_SENTINEL;
+  if (value === -Infinity)  return NEG_INF_SENTINEL;
+  if (Number.isNaN(value))  return NAN_SENTINEL;
+  return value;
+}
+/** Inverse of jsonReplacer. Pass to JSON.parse(text, jsonReviver). */
+export function jsonReviver(_key, value) {
+  if (typeof value !== 'string') return value;
+  switch (value) {
+    case NEG_ZERO_SENTINEL: return -0;
+    case POS_INF_SENTINEL:  return Infinity;
+    case NEG_INF_SENTINEL:  return -Infinity;
+    case NAN_SENTINEL:      return NaN;
+    default: return value;
+  }
+}
+
+/** Stringify a blob with proper handling of -0 / Infinity / NaN. Use this instead of bare JSON.stringify. */
+export function blobToJSONString(blob, indent) { return JSON.stringify(blobToJSON(blob), jsonReplacer, indent); }
+/** Parse + reconstruct a blob with proper handling of -0 / Infinity / NaN. Use this instead of bare JSON.parse. */
+export function jsonStringToBlob(str)         { return jsonToBlob(JSON.parse(str, jsonReviver)); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wscodec",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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",
@@ -10,7 +10,8 @@
     "./primitives": "./primitives.mjs",
     "./structs": "./structs.mjs",
     "./values": "./values.mjs",
-    "./properties": "./properties.mjs"
+    "./properties": "./properties.mjs",
+    "./json": "./json.mjs"
   },
   "files": [
     "wscodec.mjs",
@@ -19,10 +20,16 @@
     "structs.mjs",
     "values.mjs",
     "properties.mjs",
+    "json.mjs",
     "README.md"
   ],
   "scripts": {
-    "test": "node test/test-roundtrip.mjs"
+    "test": "node test/test-roundtrip.mjs",
+    "test:json": "node test/test-json-full.mjs",
+    "test:json-spot": "node test/test-json-roundtrip.mjs",
+    "export-db": "node scripts/db-to-json.mjs",
+    "import-db": "node --max-old-space-size=4096 scripts/json-to-db.mjs",
+    "dump-logs": "node scripts/dump-logs.mjs"
   },
   "keywords": [
     "soulmask",

package/properties.mjs

@@ -25,6 +25,7 @@
  * 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';
@@ -291,6 +292,35 @@ 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
@@ -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);
@@ -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 { 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.
  *
- * 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.
+ * 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;
   }
@@ -1139,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);

package/values.mjs

@@ -168,6 +168,9 @@ export class FTextValue {
       this._keyIsNull = keyIsNull;
       this.sourceString = sourceString ?? null;
       this._sourceStringIsNull = sourceStringIsNull;
+    } else if (historyType === 1) {
+      this.sourceFmt = sourceFmt ?? null;   // FTextValue (the pattern)
+      this.arguments = args ?? [];          // [{key, keyIsNull, type, value}]
     } else if (historyType === 2) {
       this.sourceFmt = sourceFmt ?? null;   // FTextValue (the pattern)
       this.arguments = args ?? [];          // [{type, value}]
@@ -185,6 +188,7 @@ export class FTextValue {
   get text() {
     if (this.historyType === -1) return this.displayString;
     if (this.historyType === 0) return this.sourceString ?? null;
+    if (this.historyType === 1) return this.sourceFmt?.text ?? null;
     if (this.historyType === 2) return this.sourceFmt?.text ?? null;
     if (this.historyType === 4) {
       const v = this.sourceValue?.value;

package/wscodec.mjs

@@ -46,6 +46,14 @@ export {
   readPropertyStream, writePropertyStream, writeNestedPropertyStream,
   readValue, writeValue,
 } from './properties.mjs';
+// JSON converter: declared at the bottom so UnrealBlob (below) is already
+// defined when json.mjs's deferred references resolve. ESM live bindings
+// keep this load-order safe even with the json.mjs ↔ wscodec.mjs cycle.
+export {
+  blobToJSON, jsonToBlob,
+  blobToJSONString, jsonStringToBlob,
+  jsonReplacer, jsonReviver,
+} from './json.mjs';
 
 const NAME = 'unreal-properties';
 const VERSION_HEADER_SIZE = 4;
@@ -163,12 +171,22 @@ export class UnrealBlob {
    * appending `bodyTrailing` after the None terminator + 4-byte FName.Number
    * trailer that `writePropertyStream` emits.
    *
+   * Options:
+   *   `recomputeSizes` — override `this._recomputeSizes`. When truthy, every
+   *     PropertyTag.size field (and ArrayValue innerTag.size) is rewritten
+   *     from the actual encoded value byte count. Required after edits that
+   *     change variable-length fields (FString contents, FText, MapValue
+   *     contents, etc.); without it, a stale size field leaves the Soulmask
+   *     reader misaligned and the blob is rejected on load. The default is
+   *     to honor `this._recomputeSizes`; jsonToBlob sets that to true so
+   *     the JSON pipeline always recomputes.
+   *
    * 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() {
+  serialize({ recomputeSizes } = {}) {
     if (!this._dirty && this._raw instanceof Uint8Array) return this._raw;
 
     if (this.error != null) {
@@ -179,6 +197,7 @@ export class UnrealBlob {
     }
 
     const w = new Writer(this._raw?.length || 256);
+    if (recomputeSizes ?? this._recomputeSizes) w._wsRecomputeSizes = true;
     w.writeUint32(this.versionTag);
     writePropertyStream(w, this.properties, /*emitTerminatorTrailer=*/true);
     if (this.bodyTrailing && this.bodyTrailing.length > 0) {