wscodec 0.2.0 → 0.3.0

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.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",
@@ -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,15 @@
     "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 scripts/json-to-db.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) {