@peers-app/peers-sdk 0.26.6 → 0.27.1

package/dist/serial-json.js

@@ -6,193 +6,252 @@ exports.fromJSON = fromJSON;
 exports.toJSONString = toJSONString;
 exports.fromJSONString = fromJSONString;
 const _ = require("lodash");
-/** True for plain object literals (excludes array, Date, and null). */
+/**
+ * True for any non-null object or function that isn't an array or a Date. Despite the name, class
+ * instances, Maps and RegExps count.
+ */
 function isObject(x) {
     return _.isObject(x) && !_.isArray(x) && !_.isDate(x) && x !== null;
 }
+/** Prefix of the string that stands in for a shared object (`obj_N`) or array (`ary_N`). */
+const SHARED_REF_PREFIX = "__duplicate_ref_";
+/** First element of an array that other places refer to; the text after the colon is its marker. */
+const ARRAY_TAG_PREFIX = "__this_ref:";
 /**
- * Clones a value into a JSON-serializable tree: Dates, Buffers, cycles, `undefined`, `NaN`, RegExp, etc. use sentinel strings.
- * Shared references are preserved with `__duplicate_ref_*` and `__this_ref` markers for {@link fromJSON}.
+ * Encodes a value as a JSON-safe tree, using in-band sentinel strings for what JSON can't hold:
+ * - `undefined`, `NaN`, `Infinity` → `"__UNDEFINED"`, `"__NAN"`, `"__INFINITY"`
+ * - Date → `"__DATE <ISO>"`, RegExp → `"__REGEXP /src/flags"`, Error → `"__ERROR <stack>"`
+ * - Buffer → `"__BUFFER <base64>"`, Uint8Array → `"__UINT8ARRAY <base64>"`
+ * - functions → `"__FUNCTION <source>"` (one-way: {@link fromJSON} leaves the string)
+ * - keys starting with `$` → `__DOLLAR_…`
+ *
+ * A shared object or array (including a cycle) is copied once: the first copy is tagged with a
+ * `__this_ref` key (objects) or a `"__this_ref:<marker>"` first element (arrays), and every other
+ * occurrence becomes the `__duplicate_ref_obj_N` / `__duplicate_ref_ary_N` marker string. The
+ * markers only resolve when the whole tree is decoded together.
+ *
+ * Map, Set and class instances become plain objects, `-Infinity` and `-0` survive the tree but
+ * not `JSON.stringify`. BigInt and symbols remain in the tree; JSON text throws on BigInt and
+ * drops symbols (or writes null in arrays). Invalid Dates throw, and own `__proto__` keys aren't
+ * emitted. Strings that look like sentinels aren't escaped, so they decode as the value they spell.
+ *
+ * The output is signed (`canonicalJSONString` in keys.ts), so it must stay byte-identical across
+ * versions; `serial-json.compat.test.ts` checks it against a frozen copy.
+ * @returns A new tree; the input is never modified. Top-level primitives are returned as-is.
  */
 function toJSON(obj) {
     if (!_.isObject(obj)) {
         return obj;
     }
-    //console.log('toJSON');
-    const knownObjs = [];
-    const objRefs = [];
-    const newObjs = [];
-    let refCount = 0;
-    function recurse(obj) {
-        // stringify values
-        if (Number.isNaN(obj))
-            return "__NAN";
-        if (obj === undefined)
-            return "__UNDEFINED";
-        if (obj === Infinity)
-            return "__INFINITY";
-        if (obj instanceof RegExp)
-            return `__REGEXP ${obj.toString()}`;
-        //   if(isDate(obj))
-        //       return "__DATE " + obj.toISOString();
-        if (_.isDate(obj)) {
-            return `__DATE ${obj.toISOString()}`;
+    // Every object or array met so far, with its marker and the copy that gets the tag if it recurs.
+    const seen = new Map();
+    function recurse(value) {
+        switch (typeof value) {
+            case "string":
+            case "boolean":
+            case "bigint":
+            case "symbol":
+                return value;
+            case "number":
+                if (Number.isNaN(value))
+                    return "__NAN";
+                if (value === Infinity)
+                    return "__INFINITY";
+                return value;
+            case "undefined":
+                return "__UNDEFINED";
         }
-        if (_.isFunction(obj))
-            return `__FUNCTION ${obj.toString()}`;
-        if (_.isElement(obj)) {
-            return `__HTML ${obj.outerHTML}`;
-        }
-        if (typeof window !== "undefined" && window && obj === window) {
+        if (value === null)
+            return null;
+        if (value instanceof RegExp)
+            return `__REGEXP ${value.toString()}`;
+        if (_.isDate(value))
+            return `__DATE ${value.toISOString()}`;
+        if (_.isFunction(value))
+            return `__FUNCTION ${value.toString()}`;
+        if (_.isElement(value))
+            return `__HTML ${value.outerHTML}`;
+        if (typeof window !== "undefined" && window && value === window)
             return "__WINDOW";
+        if (_.isError(value))
+            return `__ERROR ${value.stack}`;
+        if (Buffer.isBuffer(value))
+            return `__BUFFER ${value.toString("base64")}`;
+        if (value instanceof Uint8Array)
+            return `__UINT8ARRAY ${Buffer.from(value).toString("base64")}`;
+        const known = seen.get(value);
+        if (known) {
+            const target = known.copy;
+            if (Array.isArray(target)) {
+                if (typeof target[0] !== "string" || !target[0].startsWith(ARRAY_TAG_PREFIX)) {
+                    target.unshift(`${ARRAY_TAG_PREFIX}${known.ref}`);
+                }
+            }
+            else if (isObject(target) && !target.__this_ref) {
+                target.__this_ref = known.ref;
+            }
+            return known.ref;
         }
-        if (_.isError(obj)) {
-            return `__ERROR ${obj.stack}`;
-        }
-        if (Buffer.isBuffer(obj)) {
-            // Convert Buffer to base64 string for JSON serialization (backward compatibility)
-            return `__BUFFER ${obj.toString("base64")}`;
-        }
-        if (obj instanceof Uint8Array) {
-            // Convert Uint8Array to base64 string for JSON serialization
-            return `__UINT8ARRAY ${Buffer.from(obj).toString("base64")}`;
-        }
-        // non-objects can just be returned at this point
-        if (!(isObject(obj) || _.isArray(obj))) {
-            return obj;
-        }
-        // if we've found a duplicate reference, deal with it
-        const iObj = knownObjs.indexOf(obj);
-        if (iObj >= 0) {
-            const ref = objRefs[iObj];
-            const duplicateTarget = newObjs[iObj];
-            if (_.isArray(duplicateTarget) &&
-                (!_.isString(duplicateTarget[0]) || !duplicateTarget[0].match(/^__this_ref:/)))
-                duplicateTarget.unshift(`__this_ref:${ref}`);
-            else if (isObject(duplicateTarget) && !duplicateTarget.__this_ref)
-                duplicateTarget.__this_ref = ref;
-            return ref;
-        }
-        // capture references in case we need them later
-        refCount++;
-        const newRef = `__duplicate_ref_${_.isArray(obj) ? "ary_" : "obj_"}${refCount}`;
-        const nObj = _.isArray(obj) ? [] : {};
-        knownObjs.push(obj);
-        objRefs.push(newRef);
-        newObjs.push(nObj);
-        // recurse on properties
-        if (_.isArray(obj)) {
-            for (let i = 0; i < obj.length; i++)
-                nObj.push(recurse(obj[i])); // use push so offset from reference capture doesn't mess things up
+        const isArray = Array.isArray(value);
+        const ref = `${SHARED_REF_PREFIX}${isArray ? "ary_" : "obj_"}${seen.size + 1}`;
+        const copy = isArray ? [] : {};
+        seen.set(value, { ref, copy });
+        // Each key is added only after its value is encoded, so a tag added meanwhile comes first.
+        // Signatures depend on that order.
+        if (isArray) {
+            for (let i = 0; i < value.length; i++)
+                copy.push(recurse(value[i]));
         }
         else {
-            for (const key of Object.keys(obj)) {
-                let outKey = key;
-                const value = recurse(obj[key]);
-                if (outKey[0] === "$")
-                    // escape leading dollar signs
-                    outKey = `__DOLLAR_${outKey.substring(1)}`;
-                nObj[outKey] = value;
+            for (const key of Object.keys(value)) {
+                const item = recurse(value[key]);
+                copy[key[0] === "$" ? `__DOLLAR_${key.substring(1)}` : key] = item;
             }
         }
-        return nObj;
+        return copy;
+    }
+    return recurse(obj);
+}
+// Orphaned markers are warned about once each per process, up to a cap, because a stored value
+// can be decoded over and over.
+const MAX_ORPHAN_WARNINGS = 100;
+const warnedOrphans = new Set();
+function warnOrphanedRefs(refs) {
+    for (const ref of refs) {
+        if (warnedOrphans.has(ref) || warnedOrphans.size >= MAX_ORPHAN_WARNINGS)
+            continue;
+        warnedOrphans.add(ref);
+        // One string argument, so the console log pipeline never stores the bare marker.
+        console.warn(`[serial-json] shared-reference marker ${ref} has no target in the decoded value, so it decodes empty`);
     }
-    obj = recurse(obj);
-    return obj;
 }
 /**
- * Reverses {@link toJSON}: restores special values, shared references, and keys escaped with `__DOLLAR_`.
- * @param _externalReferences Reserved for future use (function revival, etc.)
+ * Reverses {@link toJSON}: restores the sentinel values, shared objects and cycles, and keys
+ * escaped with `__DOLLAR_`.
+ *
+ * Input may come from another device. Shared-reference tags never resolve to a prototype or to a
+ * target of the other kind (object vs array), `__proto__` keys are dropped, and `__HTML` /
+ * `__WINDOW` stay plain strings. A marker with no accepted target in the same tree decodes to an
+ * empty object or array and warns once per distinct marker, up to 100 warnings per process.
+ *
+ * Only arrays and objects are walked. Values that are already decoded (Date, RegExp, Error, Buffer
+ * and any other typed array or DataView) are returned as they are, so decoding a partly decoded
+ * tree preserves these instances. Marker-like strings may decode again; live cycles aren't supported.
+ * @param obj Parsed JSON, a msgpack-decoded tree, or a mix with decoded values. Never modified.
+ * @param _externalReferences Unused. Callers pass `.map` indexes into it, so it must stay ignored.
+ * @returns A new tree for walked arrays and objects. Passed-through values retain their identity
+ * and properties.
+ * @throws SyntaxError for a `__REGEXP` sentinel that isn't a valid regular expression; RangeError
+ * when the tree is nested deeper than the call stack allows.
  */
 function fromJSON(obj, _externalReferences) {
-    var dup_refs = {};
-    function recurse(obj) {
-        if (_.isString(obj)) {
-            // restore values
-            if (obj === "__UNDEFINED")
-                return undefined;
-            if (obj === "__NAN")
-                return NaN;
-            if (obj === "__INFINITY")
-                return Infinity;
-            if (obj.match(/^__REGEXP /)) {
-                const m = obj.split("__REGEXP ")[1].match(/\/(.*)\/(.*)?/);
-                if (!m) {
-                    return /(?:)/;
-                }
-                return new RegExp(m[1], m[2] || "");
-            }
-            if (obj.startsWith("__DATE ")) {
-                return new Date(obj.substring(7));
-            }
-            // // assuming strings like this should be dates
-            // if (obj.match(/^\d{4}-\d{2}-\d{2}T\d{2}\:\d{2}\:\d{2}\.\d{3}Z$/)) {
-            //   return new Date(obj)
-            // }
-            // if (obj.match(/^__FUNCTION /)) {
-            //   return js(obj.substring(11), externalReferences);
-            // }
-            if (obj.match(/^__HTML /)) {
-                //@ts-expect-error
-                if (typeof $ !== "undefined")
-                    return $(obj.substring(7))[0];
-                else
-                    return obj;
-            }
-            if (obj.startsWith("__ERROR ")) {
-                const error = new Error();
-                error.stack = obj.substring(8);
-                return error;
+    // A Map, so no marker or `__this_ref` value (e.g. `"__proto__"`) can resolve to a prototype.
+    const dupRefs = new Map();
+    const referenced = new Set();
+    const tagged = new Set();
+    function decodeString(value) {
+        if (value === "__UNDEFINED")
+            return undefined;
+        if (value === "__NAN")
+            return NaN;
+        if (value === "__INFINITY")
+            return Infinity;
+        if (value.startsWith("__REGEXP ")) {
+            const match = value.split("__REGEXP ")[1].match(/\/(.*)\/(.*)?/);
+            if (!match)
+                return /(?:)/;
+            return new RegExp(match[1], match[2] || "");
+        }
+        if (value.startsWith("__DATE "))
+            return new Date(value.substring(7));
+        if (value.startsWith("__ERROR ")) {
+            const error = new Error();
+            error.stack = value.substring(8);
+            return error;
+        }
+        if (value.startsWith("__UINT8ARRAY ")) {
+            return new Uint8Array(Buffer.from(value.substring(13), "base64"));
+        }
+        if (value.startsWith("__BUFFER "))
+            return Buffer.from(value.substring(9), "base64");
+        if (value.startsWith(SHARED_REF_PREFIX)) {
+            referenced.add(value);
+            let target = dupRefs.get(value);
+            if (!target) {
+                target = value.includes("_obj_") ? {} : [];
+                dupRefs.set(value, target);
             }
-            if (obj === "__WINDOW") {
-                return window;
+            return target;
+        }
+        return value;
+    }
+    function recurse(value) {
+        if (typeof value === "string") {
+            // Every sentinel starts with "__" (95 is "_").
+            return value.charCodeAt(0) === 95 && value.charCodeAt(1) === 95 ? decodeString(value) : value;
+        }
+        if (value === null || typeof value !== "object")
+            return value;
+        const isArray = Array.isArray(value);
+        if (!isArray && Object.getPrototypeOf(value) !== Object.prototype) {
+            if (ArrayBuffer.isView(value) || _.isDate(value) || _.isRegExp(value) || _.isError(value)) {
+                return value;
             }
-            if (obj.startsWith("__UINT8ARRAY ")) {
-                // Convert base64 string back to Uint8Array
-                return new Uint8Array(Buffer.from(obj.substring(13), "base64"));
+            if (_.isString(value) && value.startsWith("__")) {
+                const decoded = decodeString(value);
+                if (decoded !== value)
+                    return decoded;
             }
-            if (obj.startsWith("__BUFFER ")) {
-                // Convert base64 string back to Buffer (backward compatibility)
-                return Buffer.from(obj.substring(9), "base64");
+        }
+        let ref;
+        let start = 0;
+        if (isArray) {
+            const first = value[0];
+            if (_.isString(first) && first.startsWith(ARRAY_TAG_PREFIX)) {
+                ref = first.split(":")[1];
+                start = 1;
             }
-            // deal with duplicate refs
-            if (obj.match(/^__duplicate_ref_/)) {
-                if (!dup_refs[obj])
-                    dup_refs[obj] = obj.match(/_obj_/) ? {} : [];
-                return dup_refs[obj];
+        }
+        else {
+            ref = value.__this_ref;
+        }
+        let target = isArray ? [] : {};
+        // toJSON only writes string tags. A primitive keeps the old object-key coercion; an object tag
+        // names no target (coercing it can throw on crafted input).
+        if (ref && typeof ref !== "object") {
+            const refKey = String(ref);
+            const existing = dupRefs.get(refKey);
+            // toJSON never tags an object and an array with one marker. Crafted input can, and an
+            // object's keys written onto an array (`length`, a big index) make it huge or throw.
+            if (!existing || Array.isArray(existing) === isArray) {
+                if (existing)
+                    target = existing;
+                else
+                    dupRefs.set(refKey, target);
+                tagged.add(refKey);
             }
         }
-        if (!(isObject(obj) || _.isArray(obj)))
-            return obj;
-        // deal with objects that have duplicate refs
-        let dup_ref = null;
-        obj = _.clone(obj); // don't mess up the original JSON object
-        if (_.isArray(obj) && _.isString(obj[0]) && obj[0].match(/^__this_ref:/))
-            dup_ref = obj.shift().split(":")[1];
-        else if (obj.__this_ref) {
-            dup_ref = obj.__this_ref;
-            delete obj.__this_ref;
+        if (isArray) {
+            for (let i = start; i < value.length; i++)
+                target[i - start] = recurse(value[i]);
         }
-        let mObj = _.isArray(obj) ? [] : {};
-        if (dup_ref)
-            if (!dup_refs[dup_ref])
-                dup_refs[dup_ref] = mObj;
-            else
-                mObj = dup_refs[dup_ref];
-        // restore keys and recurse on objects
-        for (const key of Object.keys(obj)) {
-            if (!Object.hasOwn(obj, key))
-                continue;
-            let outKey = key;
-            const value = recurse(obj[outKey]);
-            if (outKey.match(/^__DOLLAR_/))
-                outKey = `$${outKey.substring(9)}`;
-            mObj[outKey] = value;
+        else {
+            for (const key of Object.keys(value)) {
+                // A truthy `__this_ref` is the tag read above. Assigning `__proto__` would set the
+                // target's prototype, and toJSON never writes that key.
+                if (key === "__proto__" || (ref && key === "__this_ref"))
+                    continue;
+                const item = recurse(value[key]);
+                target[key.startsWith("__DOLLAR_") ? `$${key.substring(9)}` : key] = item;
+            }
         }
-        return mObj;
+        return target;
     }
-    obj = recurse(obj);
-    return obj;
+    const result = recurse(obj);
+    // Checked only now: a marker can come before its target in the tree.
+    if (referenced.size)
+        warnOrphanedRefs([...referenced].filter((ref) => !tagged.has(ref)));
+    return result;
 }
 /**
  * `JSON.stringify` of {@link toJSON}: extended types are encoded deterministically, but keys keep

package/dist/serial-json.oracle.d.ts

@@ -0,0 +1,21 @@
+/** True for plain object literals (excludes array, Date, and null). */
+export declare function isObject(x: any): x is Record<string, any>;
+/**
+ * Clones a value into a JSON-serializable tree: Dates, Buffers, cycles, `undefined`, `NaN`, RegExp, etc. use sentinel strings.
+ * Shared references are preserved with `__duplicate_ref_*` and `__this_ref` markers for {@link fromJSON}.
+ */
+export declare function toJSON(obj: any): any;
+/**
+ * Reverses {@link toJSON}: restores special values, shared references, and keys escaped with `__DOLLAR_`.
+ * Input may come from another device: shared-reference tags never resolve to a prototype, and
+ * `__proto__` keys are dropped.
+ * @param _externalReferences Reserved for future use (function revival, etc.)
+ */
+export declare function fromJSON(obj: any, _externalReferences?: any): any;
+/**
+ * `JSON.stringify` of {@link toJSON}: extended types are encoded deterministically, but keys keep
+ * insertion order. Not canonical; for signatures use `canonicalJSONString` in `keys.ts`.
+ */
+export declare function toJSONString(obj: any): string;
+/** `JSON.parse` then {@link fromJSON}. */
+export declare function fromJSONString(str: string): any;

package/dist/serial-json.oracle.js

@@ -0,0 +1,222 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isObject = isObject;
+exports.toJSON = toJSON;
+exports.fromJSON = fromJSON;
+exports.toJSONString = toJSONString;
+exports.fromJSONString = fromJSONString;
+/**
+ * Test oracle: a frozen copy of `serial-json.ts` as it stood after the prototype-pollution fix
+ * (2026-10-19), before the speed and safety rewrite. `serial-json.compat.test.ts` checks that the
+ * live encoder still produces byte-identical output and that each decoder reads the other's output.
+ * Tests only: never import it from runtime code, and don't edit it (delete it once the old format
+ * no longer matters).
+ */
+const _ = require("lodash");
+/** True for plain object literals (excludes array, Date, and null). */
+function isObject(x) {
+    return _.isObject(x) && !_.isArray(x) && !_.isDate(x) && x !== null;
+}
+/**
+ * Clones a value into a JSON-serializable tree: Dates, Buffers, cycles, `undefined`, `NaN`, RegExp, etc. use sentinel strings.
+ * Shared references are preserved with `__duplicate_ref_*` and `__this_ref` markers for {@link fromJSON}.
+ */
+function toJSON(obj) {
+    if (!_.isObject(obj)) {
+        return obj;
+    }
+    //console.log('toJSON');
+    const knownObjs = [];
+    const objRefs = [];
+    const newObjs = [];
+    let refCount = 0;
+    function recurse(obj) {
+        // stringify values
+        if (Number.isNaN(obj))
+            return "__NAN";
+        if (obj === undefined)
+            return "__UNDEFINED";
+        if (obj === Infinity)
+            return "__INFINITY";
+        if (obj instanceof RegExp)
+            return `__REGEXP ${obj.toString()}`;
+        //   if(isDate(obj))
+        //       return "__DATE " + obj.toISOString();
+        if (_.isDate(obj)) {
+            return `__DATE ${obj.toISOString()}`;
+        }
+        if (_.isFunction(obj))
+            return `__FUNCTION ${obj.toString()}`;
+        if (_.isElement(obj)) {
+            return `__HTML ${obj.outerHTML}`;
+        }
+        if (typeof window !== "undefined" && window && obj === window) {
+            return "__WINDOW";
+        }
+        if (_.isError(obj)) {
+            return `__ERROR ${obj.stack}`;
+        }
+        if (Buffer.isBuffer(obj)) {
+            // Convert Buffer to base64 string for JSON serialization (backward compatibility)
+            return `__BUFFER ${obj.toString("base64")}`;
+        }
+        if (obj instanceof Uint8Array) {
+            // Convert Uint8Array to base64 string for JSON serialization
+            return `__UINT8ARRAY ${Buffer.from(obj).toString("base64")}`;
+        }
+        // non-objects can just be returned at this point
+        if (!(isObject(obj) || _.isArray(obj))) {
+            return obj;
+        }
+        // if we've found a duplicate reference, deal with it
+        const iObj = knownObjs.indexOf(obj);
+        if (iObj >= 0) {
+            const ref = objRefs[iObj];
+            const duplicateTarget = newObjs[iObj];
+            if (_.isArray(duplicateTarget) &&
+                (!_.isString(duplicateTarget[0]) || !duplicateTarget[0].match(/^__this_ref:/)))
+                duplicateTarget.unshift(`__this_ref:${ref}`);
+            else if (isObject(duplicateTarget) && !duplicateTarget.__this_ref)
+                duplicateTarget.__this_ref = ref;
+            return ref;
+        }
+        // capture references in case we need them later
+        refCount++;
+        const newRef = `__duplicate_ref_${_.isArray(obj) ? "ary_" : "obj_"}${refCount}`;
+        const nObj = _.isArray(obj) ? [] : {};
+        knownObjs.push(obj);
+        objRefs.push(newRef);
+        newObjs.push(nObj);
+        // recurse on properties
+        if (_.isArray(obj)) {
+            for (let i = 0; i < obj.length; i++)
+                nObj.push(recurse(obj[i])); // use push so offset from reference capture doesn't mess things up
+        }
+        else {
+            for (const key of Object.keys(obj)) {
+                let outKey = key;
+                const value = recurse(obj[key]);
+                if (outKey[0] === "$")
+                    // escape leading dollar signs
+                    outKey = `__DOLLAR_${outKey.substring(1)}`;
+                nObj[outKey] = value;
+            }
+        }
+        return nObj;
+    }
+    obj = recurse(obj);
+    return obj;
+}
+/**
+ * Reverses {@link toJSON}: restores special values, shared references, and keys escaped with `__DOLLAR_`.
+ * Input may come from another device: shared-reference tags never resolve to a prototype, and
+ * `__proto__` keys are dropped.
+ * @param _externalReferences Reserved for future use (function revival, etc.)
+ */
+function fromJSON(obj, _externalReferences) {
+    // A Map, so no marker or `__this_ref` value (e.g. `"__proto__"`) can resolve to a prototype.
+    const dupRefs = new Map();
+    function recurse(obj) {
+        if (_.isString(obj)) {
+            // restore values
+            if (obj === "__UNDEFINED")
+                return undefined;
+            if (obj === "__NAN")
+                return NaN;
+            if (obj === "__INFINITY")
+                return Infinity;
+            if (obj.match(/^__REGEXP /)) {
+                const m = obj.split("__REGEXP ")[1].match(/\/(.*)\/(.*)?/);
+                if (!m) {
+                    return /(?:)/;
+                }
+                return new RegExp(m[1], m[2] || "");
+            }
+            if (obj.startsWith("__DATE ")) {
+                return new Date(obj.substring(7));
+            }
+            // // assuming strings like this should be dates
+            // if (obj.match(/^\d{4}-\d{2}-\d{2}T\d{2}\:\d{2}\:\d{2}\.\d{3}Z$/)) {
+            //   return new Date(obj)
+            // }
+            // if (obj.match(/^__FUNCTION /)) {
+            //   return js(obj.substring(11), externalReferences);
+            // }
+            if (obj.match(/^__HTML /)) {
+                //@ts-expect-error
+                if (typeof $ !== "undefined")
+                    return $(obj.substring(7))[0];
+                else
+                    return obj;
+            }
+            if (obj.startsWith("__ERROR ")) {
+                const error = new Error();
+                error.stack = obj.substring(8);
+                return error;
+            }
+            if (obj === "__WINDOW") {
+                return window;
+            }
+            if (obj.startsWith("__UINT8ARRAY ")) {
+                // Convert base64 string back to Uint8Array
+                return new Uint8Array(Buffer.from(obj.substring(13), "base64"));
+            }
+            if (obj.startsWith("__BUFFER ")) {
+                // Convert base64 string back to Buffer (backward compatibility)
+                return Buffer.from(obj.substring(9), "base64");
+            }
+            // deal with duplicate refs
+            if (obj.match(/^__duplicate_ref_/)) {
+                if (!dupRefs.has(obj))
+                    dupRefs.set(obj, obj.match(/_obj_/) ? {} : []);
+                return dupRefs.get(obj);
+            }
+        }
+        if (!(isObject(obj) || _.isArray(obj)))
+            return obj;
+        // deal with objects that have duplicate refs
+        let dup_ref = null;
+        obj = _.clone(obj); // don't mess up the original JSON object
+        if (_.isArray(obj) && _.isString(obj[0]) && obj[0].match(/^__this_ref:/))
+            dup_ref = obj.shift().split(":")[1];
+        else if (obj.__this_ref) {
+            dup_ref = obj.__this_ref;
+            delete obj.__this_ref;
+        }
+        let mObj = _.isArray(obj) ? [] : {};
+        // toJSON only writes string tags. A primitive keeps the old object-key coercion; an object tag
+        // names no target (coercing it can throw on crafted input).
+        if (dup_ref && typeof dup_ref !== "object") {
+            const refKey = String(dup_ref);
+            if (dupRefs.has(refKey))
+                mObj = dupRefs.get(refKey);
+            else
+                dupRefs.set(refKey, mObj);
+        }
+        // restore keys and recurse on objects
+        for (const key of Object.keys(obj)) {
+            // Assigning `__proto__` would set mObj's prototype; toJSON never emits the key either.
+            if (!Object.hasOwn(obj, key) || key === "__proto__")
+                continue;
+            let outKey = key;
+            const value = recurse(obj[outKey]);
+            if (outKey.match(/^__DOLLAR_/))
+                outKey = `$${outKey.substring(9)}`;
+            mObj[outKey] = value;
+        }
+        return mObj;
+    }
+    obj = recurse(obj);
+    return obj;
+}
+/**
+ * `JSON.stringify` of {@link toJSON}: extended types are encoded deterministically, but keys keep
+ * insertion order. Not canonical; for signatures use `canonicalJSONString` in `keys.ts`.
+ */
+function toJSONString(obj) {
+    return JSON.stringify(toJSON(obj));
+}
+/** `JSON.parse` then {@link fromJSON}. */
+function fromJSONString(str) {
+    return fromJSON(JSON.parse(str));
+}