/**
 * @lazarv/rsc - Client-side RSC deserialization implementation
 *
 * This module provides the core RSC deserialization logic that creates
 * React elements from Flight protocol streams.
 *
 * Compatible with React's Flight protocol without directly importing React.
 * API-compatible with react-server-dom-webpack/client.
 */

// React Flight Protocol constants
const REACT_ELEMENT_TYPE = Symbol.for("react.element");
const REACT_TRANSITIONAL_ELEMENT_TYPE = Symbol.for(
  "react.transitional.element"
);
const REACT_FRAGMENT_TYPE = Symbol.for("react.fragment");
const REACT_SUSPENSE_TYPE = Symbol.for("react.suspense");
const REACT_CLIENT_REFERENCE = Symbol.for("react.client.reference");
const REACT_SERVER_REFERENCE = Symbol.for("react.server.reference");

// Shared encoder/decoder instances — avoids per-call allocation overhead
const _decoder = new TextDecoder();
const _encoder = new TextEncoder();

// Dev mode detection: __DEV__ (bundler/React global), process.env.NODE_ENV (Node.js),
// default to false (production) when neither is available
const __IS_DEV__ =
  typeof __DEV__ !== "undefined"
    ? !!__DEV__
    : typeof process !== "undefined" && process.env && process.env.NODE_ENV
      ? process.env.NODE_ENV !== "production"
      : false;

/**
 * Chunk status constants
 */
const PENDING = 0;
const RESOLVED = 1;
const REJECTED = 2;

/**
 * Stamp development-mode properties onto a React element.
 * React's dev server expects elements to have _owner, _store, _debugStack,
 * _debugTask, and _debugInfo.  Without these, dev-mode rendering crashes
 * ("Cannot set properties of undefined (setting 'validated')") or warns
 * ("Attempted to render without development properties").
 * In production this is a no-op identity function.
 */
const _devElement = __IS_DEV__
  ? (el) => {
      el._owner = null;
      el._store = { validated: 1 };
      el._debugStack = new Error("react-stack-top-frame");
      el._debugTask = null;
      el._debugInfo = null;
      return el;
    }
  : (el) => el;

/**
 * Skip a single JSON value in `str` starting at position `i`.
 * Returns the position immediately after the value, or -1 on error.
 * Only handles the small header values (strings, null, numbers, booleans)
 * — does NOT recurse into objects/arrays (not needed for element headers).
 */
function _skipJsonValue(str, i) {
  const len = str.length;
  if (i >= len) return -1;
  const ch = str.charCodeAt(i);
  if (ch === 0x22) {
    // String — scan for unescaped closing quote
    i++;
    while (i < len) {
      const c = str.charCodeAt(i);
      if (c === 0x5c) {
        i += 2;
        continue;
      } // backslash escape
      if (c === 0x22) return i + 1;
      i++;
    }
    return -1;
  }
  // Number, true, false, null — scan to delimiter
  while (i < len) {
    const c = str.charCodeAt(i);
    if (c === 0x2c || c === 0x5d || c === 0x7d || c <= 0x20) return i;
    i++;
  }
  return i;
}

/**
 * Skip a JSON value of any type (including nested objects/arrays) starting
 * at position `i`.  Returns the position immediately after the value.
 * Uses depth tracking — scans through nested content character by character
 * but doesn't allocate anything.
 */
function _skipJsonValueFull(str, i) {
  const len = str.length;
  if (i >= len) return -1;
  const ch = str.charCodeAt(i);

  // String
  if (ch === 0x22) {
    i++;
    while (i < len) {
      const c = str.charCodeAt(i);
      if (c === 0x5c) {
        i += 2;
        continue;
      }
      if (c === 0x22) return i + 1;
      i++;
    }
    return -1;
  }

  // Object or array — track depth
  if (ch === 0x7b || ch === 0x5b) {
    let depth = 1;
    let inStr = false;
    i++;
    while (i < len && depth > 0) {
      const c = str.charCodeAt(i);
      if (inStr) {
        if (c === 0x5c) {
          i += 2;
          continue;
        }
        if (c === 0x22) inStr = false;
        i++;
        continue;
      }
      if (c === 0x22) {
        inStr = true;
        i++;
        continue;
      }
      if (c === 0x7b || c === 0x5b) {
        depth++;
      } else if (c === 0x7d || c === 0x5d) {
        depth--;
      }
      i++;
    }
    return i;
  }

  // Primitive (number, true, false, null)
  while (i < len) {
    const c = str.charCodeAt(i);
    if (c === 0x2c || c === 0x5d || c === 0x7d || c <= 0x20) return i;
    i++;
  }
  return i;
}

/**
 * Scan a top-level JSON object string to extract key→value-substring pairs
 * WITHOUT parsing large nested values.
 *
 * Returns an array of { key, valueStart, valueEnd, small } entries, or null
 * if the string can't be scanned (caller falls back to full JSON.parse).
 *
 * Values smaller than `threshold` characters are flagged `small: true` so the
 * caller can JSON.parse and deserialize them eagerly.  Larger values are kept
 * as raw substrings for lazy on-demand parsing.
 */
function _scanObjectRow(str, threshold) {
  const len = str.length;
  if (str.charCodeAt(0) !== 0x7b || str.charCodeAt(len - 1) !== 0x7d)
    return null;

  const fields = [];
  let i = 1; // skip opening '{'

  while (i < len) {
    // Skip whitespace
    while (i < len && str.charCodeAt(i) <= 0x20) i++;

    // End of object?
    if (str.charCodeAt(i) === 0x7d) break;

    // Expect a string key
    if (str.charCodeAt(i) !== 0x22) return null;
    const keyStart = i;
    i = _skipJsonValue(str, i); // reuse the fast string skipper
    if (i === -1) return null;
    const key = str.slice(keyStart + 1, i - 1); // strip quotes (no escapes in typical keys)

    // Skip colon + whitespace
    while (i < len && str.charCodeAt(i) <= 0x20) i++;
    if (str.charCodeAt(i) !== 0x3a) return null; // ':'
    i++;
    while (i < len && str.charCodeAt(i) <= 0x20) i++;

    // Value starts here
    const valueStart = i;
    i = _skipJsonValueFull(str, i);

    if (i === -1) return null;
    const valueEnd = i;
    const size = valueEnd - valueStart;

    fields.push({ key, valueStart, valueEnd, small: size <= threshold });

    // Skip comma + whitespace
    while (i < len && str.charCodeAt(i) <= 0x20) i++;
    if (str.charCodeAt(i) === 0x2c) {
      i++;
    }
  }

  return fields.length > 0 ? fields : null;
}

/**
 * Scan an element tuple JSON string to extract field boundaries without
 * parsing the (potentially huge) props object.
 *
 * Element tuples: ["$", type, key, props]        (React 19 production)
 *                 ["$", type, key, ref, props]    (Legacy)
 *                 ["$", type, key, props, ...]    (React 19 dev — extra fields)
 *
 * Key insight: the row string always ends with ']' (the outer array close).
 * We only need to scan the HEADER fields ("$", type, key) which are tiny
 * (~30–50 chars), then everything from the 3rd comma to the closing ']' is
 * the remaining field(s).  This makes the scanner O(header_size) ≈ O(1),
 * independent of the props size — critical for 200KB+ rows.
 *
 * Returns { type, key, rawPropsStr, rawRefStr } or null on failure.
 */
function _scanElementTuple(str) {
  const len = str.length;
  // Outer array must close with ']'
  if (str.charCodeAt(len - 1) !== 0x5d) return null;

  // Caller already verified str starts with '["$",' so skip to after it.
  let i = 5; // past '["$",'

  // Skip whitespace
  while (i < len && str.charCodeAt(i) <= 0x20) i++;

  // Field 1: type (usually a short string like "div" or "$L1")
  const typeStart = i;
  i = _skipJsonValue(str, i);
  if (i === -1) return null;
  const typeEnd = i;

  // Expect comma after type
  while (i < len && str.charCodeAt(i) <= 0x20) i++;
  if (str.charCodeAt(i) !== 0x2c) return null;
  i++;
  while (i < len && str.charCodeAt(i) <= 0x20) i++;

  // Field 2: key (usually null, a string, or a number)
  const keyStart = i;
  i = _skipJsonValue(str, i);
  if (i === -1) return null;
  const keyEnd = i;

  // Expect comma after key
  while (i < len && str.charCodeAt(i) <= 0x20) i++;
  if (str.charCodeAt(i) !== 0x2c) return null;
  i++;
  while (i < len && str.charCodeAt(i) <= 0x20) i++;

  // Parse type and key — these are tiny, JSON.parse is fast
  const type = JSON.parse(str.slice(typeStart, typeEnd));
  const key = JSON.parse(str.slice(keyStart, keyEnd));

  // Everything from position i to len-1 (before closing ']') is field 3+.
  // The closing ']' at len-1 belongs to the outer array, not to props.
  const restEnd = len - 1;

  // Peek at the first character to determine format
  const firstChar = str.charCodeAt(i);

  if (firstChar === 0x7b) {
    // '{' → React 19 format: 4th element is the props object.
    // In production there are no extra fields after props, so
    // everything from i to restEnd is the props JSON.
    // In dev mode there may be owner/debug fields after props,
    // but those trailing fields don't affect JSON.parse of the
    // props object — they just become garbage after the first
    // top-level '}'. We need to find where the props object ends.
    // For production (no extra fields): props = str[i..restEnd)
    // For dev (extra fields): need to skip the object to find its end.
    //
    // Optimization: check if the last non-whitespace char before ']'
    // is '}' — if so, props is the only remaining field.
    let j = restEnd - 1;
    while (j > i && str.charCodeAt(j) <= 0x20) j--;
    if (str.charCodeAt(j) === 0x7d) {
      // Props is the only remaining field (production path)
      return { type, key, rawPropsStr: str.slice(i, j + 1), rawRefStr: null };
    }
    // Dev mode with extra fields — fall back to full parse
    return null;
  }

  // Not an object — legacy format: 4th element is ref, 5th is props.
  // Ref is small (usually `null`), so skip it cheaply.
  const refStart = i;
  i = _skipJsonValue(str, i);
  if (i === -1) return null;
  const refEnd = i;

  // Expect comma after ref
  while (i < len && str.charCodeAt(i) <= 0x20) i++;
  if (i >= restEnd || str.charCodeAt(i) !== 0x2c) return null;
  i++;
  while (i < len && str.charCodeAt(i) <= 0x20) i++;

  // 5th element is props — everything from i to restEnd
  // Same optimization: verify last non-ws char before ']' closes the props
  let j = restEnd - 1;
  while (j > i && str.charCodeAt(j) <= 0x20) j--;
  const lastChar = str.charCodeAt(j);
  if (
    lastChar === 0x7d ||
    lastChar === 0x5d ||
    lastChar === 0x22 ||
    (lastChar >= 0x30 && lastChar <= 0x39) ||
    lastChar === 0x65 ||
    lastChar === 0x6c
  ) {
    // Ends with }, ], ", digit, 'e' (true/false), 'l' (null) — plausible JSON value end
    return {
      type,
      key,
      rawPropsStr: str.slice(i, j + 1),
      rawRefStr: str.slice(refStart, refEnd),
    };
  }

  return null;
}

/**
 * Binary row tag byte → TypedArray constructor (module-level, allocated once).
 * Covers tags that need alignment-safe copy: Int8Array through BigUint64Array.
 * Uint8Array (0x6f), ArrayBuffer (0x41), DataView (0x56), Text (0x54) are
 * handled as special cases in processBinaryRow.
 */
const _binaryTagConstructors = {
  0x4f: Int8Array, // O
  0x55: Uint8ClampedArray, // U
  0x53: Int16Array, // S
  0x73: Uint16Array, // s
  0x4c: Int32Array, // L
  0x6c: Uint32Array, // l
  0x47: Float32Array, // G
  0x67: Float64Array, // g
  0x4d: BigInt64Array, // M
  0x6d: BigUint64Array, // m
};

/**
 * Create a TypedArray from a constructor name and buffer
 */
function createTypedArray(typeName, buffer, typeRegistry = {}) {
  const constructors = {
    Int8Array,
    Uint8Array,
    Uint8ClampedArray,
    Int16Array,
    Uint16Array,
    Int32Array,
    Uint32Array,
    Float32Array,
    Float64Array,
    BigInt64Array,
    BigUint64Array,
    DataView,
  };

  // Check typeRegistry first for custom types
  const CustomConstructor = typeRegistry[typeName];
  if (CustomConstructor) {
    return new CustomConstructor(buffer);
  }

  const Constructor = constructors[typeName];
  if (Constructor) {
    return new Constructor(buffer);
  }
  // Fallback to Uint8Array
  return new Uint8Array(buffer);
}

/**
 * Internal response state for deserialization
 */
class FlightResponse {
  constructor(options = {}) {
    this.options = options;
    this.moduleLoader = options.moduleLoader || {};
    this.temporaryReferences = options.temporaryReferences || new Map();
    this.typeRegistry = options.typeRegistry || {};

    this.callServer =
      options.callServer ||
      (() => {
        throw new Error("Server actions are not configured");
      });

    // Map of chunk ID to chunk state
    this.chunks = new Map();

    // Buffer for incomplete lines (text)
    this.buffer = "";

    // Binary buffer for handling binary rows
    this.binaryBuffer = null;

    // State for reading binary row data
    this.pendingBinaryRow = null; // { id, tag, length, bytesRead }

    // The root value
    this.rootChunk = this.createChunk(0);

    // Deferred resolutions - chunks that need their properties filled after all chunks are parsed
    this.deferredChunks = [];

    // Deferred path references - path refs that need resolution after all properties are filled
    this.deferredPathRefs = [];

    // Pending module import Promises — tracked so the consume loop can
    // await them before resolving deferred chunks, ensuring import()
    // results are available synchronously when React renders.
    this.pendingModuleImports = [];

    // Model/element rows buffered because module imports are in flight.
    // The RSC protocol emits I rows before the model rows that reference
    // them.  When import() is async (Vite), the module chunks stay PENDING
    // during processData.  Rather than resolving with lazy wrappers, we
    // buffer subsequent rows and replay them after imports settle.
    // Processed by flushPendingRows() in the consume loop.
    this.pendingRows = [];
  }

  /**
   * Create a new pending chunk.
   *
   * Chunks start without a Promise — one is created lazily via
   * _ensurePromise() only when async code actually needs to await
   * the chunk.  For the common synchronous-resolve path this avoids
   * a Promise + two closure allocations per chunk.
   */
  createChunk(id) {
    const chunk = {
      id,
      status: PENDING,
      value: undefined,
      _promise: null,
      _resolve: null,
      _reject: null,
    };
    this.chunks.set(id, chunk);
    return chunk;
  }

  /**
   * Lazily create a Promise for a chunk.
   * - If already resolved/rejected synchronously, returns an already-settled promise.
   * - If still pending, allocates the real Promise with resolve/reject captures.
   */
  _ensurePromise(chunk) {
    if (chunk._promise !== null) return chunk._promise;

    if (chunk.status === RESOLVED) {
      const p = Promise.resolve(chunk.value);
      p.status = "fulfilled";
      p.value = chunk.value;
      chunk._promise = p;
    } else if (chunk.status === REJECTED) {
      const err = chunk.type === "streaming" ? chunk.error : chunk.value;
      const p = Promise.reject(err);
      p.catch(() => {}); // suppress unhandled rejection
      p.status = "rejected";
      p.reason = err;
      chunk._promise = p;
    } else {
      // Still pending — allocate a real promise
      const p = new Promise((res, rej) => {
        chunk._resolve = res;
        chunk._reject = rej;
      });
      // Suppress unhandled rejection warnings.  The rejection will be
      // observed by React's use() hook (which reads .status/.reason
      // synchronously) or by an error boundary — but Node.js fires the
      // "unhandledRejection" event before React gets a chance to read it.
      p.catch(() => {});
      p.status = "pending";
      p.value = undefined;
      chunk._promise = p;
    }
    return chunk._promise;
  }

  /**
   * Get or create a chunk
   */
  getChunk(id) {
    let chunk = this.chunks.get(id);
    if (!chunk) {
      chunk = this.createChunk(id);
    }
    return chunk;
  }

  /**
   * Get or create a streaming chunk (for async iterables, ReadableStream)
   * These chunks accumulate values instead of being resolved once.
   * Streaming chunks always allocate a real Promise because they are
   * consumed via async iteration / ReadableStream readers.
   */
  getOrCreateStreamingChunk(id) {
    let chunk = this.chunks.get(id);
    if (!chunk) {
      let resolve, reject;
      const promise = new Promise((res, rej) => {
        resolve = res;
        reject = rej;
      });

      // Suppress unhandled-rejection warnings (Node.js v24+)
      promise.catch(() => {});

      chunk = {
        id,
        status: PENDING,
        value: [],
        type: "streaming",
        _promise: promise,
        _resolve: resolve,
        _reject: reject,
      };

      promise.status = "pending";
      promise.value = undefined;

      this.chunks.set(id, chunk);
    }
    return chunk;
  }

  /**
   * Resolve a chunk with a value
   */
  resolveChunk(id, value) {
    const chunk = this.getChunk(id);
    if (chunk.status !== PENDING) {
      return;
    }

    chunk.status = RESOLVED;
    chunk.value = value;

    // If a Promise was already created (someone awaited it), fulfill it
    if (chunk._promise !== null) {
      chunk._promise.status = "fulfilled";
      chunk._promise.value = value;
      chunk._resolve(value);
    }
  }

  /**
   * Reject a chunk with an error
   */
  rejectChunk(id, error) {
    const chunk = this.getChunk(id);
    if (chunk.status !== PENDING) {
      return;
    }

    chunk.status = REJECTED;
    if (chunk.type === "streaming" && Array.isArray(chunk.value)) {
      chunk.error = error;
    } else {
      chunk.value = error;
    }
    if (chunk._controller && !chunk._controllerClosed) {
      try {
        chunk._controller.error(error);
      } catch {
        // Controller may already be closed
      }
      chunk._controllerClosed = true;
    }

    if (chunk._promise !== null) {
      chunk._promise.status = "rejected";
      chunk._promise.reason = error;
      // Attach a no-op catch handler so Node.js doesn't fire an unhandled
      // rejection when callers haven't awaited the promise yet.  The true
      // error is already recorded on chunk.value and chunk._promise.reason
      // so React's render pipeline (via use()) still observes it when it
      // eventually reads the promise.
      chunk._promise.catch(() => {});

      chunk._reject(error);
    }
  }

  /**
   * Process a line of Flight protocol
   */
  processLine(line, hasSpecialBytes = true) {
    if (!line) return;

    // Parse the line: "id:tag{json}" or "id:{json}" or ":tag{data}" (global rows)
    const colonIndex = line.indexOf(":");
    if (colonIndex === -1) return;

    const idPart = line.slice(0, colonIndex);
    const rest = line.slice(colonIndex + 1);

    // Handle global rows (no ID, starts with ":")
    if (idPart === "") {
      const tag = rest[0];
      // N = timestamp row (React's render time)
      // This is a React-specific row that we can ignore for now
      if (tag === "N") {
        // Timestamp row - ignore for compatibility
        return;
      }
      // Other global rows can be handled here
      return;
    }

    const id = parseInt(idPart, 10);

    // Check for tagged rows
    const tag = rest[0];

    if (tag === "I") {
      // Module reference
      const metadata = JSON.parse(rest.slice(1));
      this.resolveModuleReference(id, metadata);
    } else if (tag === "E") {
      // Error
      const errorInfo = JSON.parse(rest.slice(1));
      const error = new Error(errorInfo.message);
      error.stack = errorInfo.stack;
      // Add digest for production error identification
      if (errorInfo.digest) {
        error.digest = errorInfo.digest;
      }
      // For the root chunk, resolve with a React element that throws during
      // rendering instead of rejecting the promise.  This matches
      // react-server-dom-webpack behavior: createFromReadableStream always
      // resolves, and the error propagates through React's render pipeline
      // (error boundaries, SSR onError) rather than rejecting the transport
      // promise.  Rejecting would crash callers that await the result
      // (e.g. render-dom's SSR pipeline) before React ever sees the tree.
      if (id === 0) {
        const ErrorThrower = () => {
          throw error;
        };
        ErrorThrower.displayName = "FlightError";
        this.resolveChunk(0, {
          $$typeof: REACT_TRANSITIONAL_ELEMENT_TYPE,
          type: ErrorThrower,
          key: null,
          ref: null,
          props: {},
        });
      } else {
        this.rejectChunk(id, error);
      }
    } else if (tag === "H") {
      // Hint - preload
      const hint = JSON.parse(rest.slice(1));
      this.processHint(hint);
    } else if (tag === "D") {
      // Debug info - store for development tools
      const debugInfo = JSON.parse(rest.slice(1));
      this.processDebugInfo(id, debugInfo);
    } else if (tag === "P") {
      // Postpone (PPR)
      const reason = JSON.parse(rest.slice(1));
      const error = new Error(`Postponed: ${reason}`);
      error.$$typeof = Symbol.for("react.postpone");
      error.reason = reason;
      this.rejectChunk(id, error);
    } else if (tag === "W") {
      // Console replay (Warning)
      const consoleInfo = JSON.parse(rest.slice(1));
      this.processConsoleReplay(consoleInfo);
    } else if (tag === "T") {
      // Text row - streaming text content
      const textContent = rest.slice(1);
      this.appendTextChunk(id, textContent);
    } else if (tag === "B") {
      // Binary row - streaming binary content
      // The binary data is everything after the "B" tag
      const binaryContent = rest.slice(1);
      this.appendBinaryChunk(id, binaryContent);
    } else {
      // Model row - JSON data.
      // If module imports are in flight (from I rows processed earlier in
      // this same processData call), buffer this row for later.  The RSC
      // protocol guarantees I rows precede the model rows that reference
      // them.  By deferring until imports settle, $L references resolve to
      // actual module exports — matching webpack's synchronous behavior
      // and avoiding lazy wrappers that cause Suspense flashes on hydration.
      if (this.pendingModuleImports.length > 0) {
        this.pendingRows.push({ line, hasSpecialBytes });
        return;
      }
      try {
        // Fast path for element tuples: scan the raw JSON string to extract
        // header fields (type, key) without parsing the potentially huge props
        // object.  Props is kept as a raw JSON string and only parsed lazily
        // when first accessed via the self-replacing getter.
        //
        // Element tuples start with '["$",' — check the first 5 chars.
        // Only use the scanner for rows > 128 bytes — for tiny elements
        // (e.g., `["$","div",null,{}]`), V8's native JSON.parse is faster
        // than our character-level scanner.  The scanner wins on large rows
        // (200KB+) where it avoids parsing the dominant props object.
        if (
          rest.length > 128 &&
          rest.charCodeAt(0) === 0x5b &&
          rest.charCodeAt(1) === 0x22 &&
          rest.charCodeAt(2) === 0x24 &&
          rest.charCodeAt(3) === 0x22 &&
          rest.charCodeAt(4) === 0x2c
        ) {
          const scan = _scanElementTuple(rest);
          if (scan) {
            const value = this.deserializeElementFromScan(scan);
            this.resolveChunk(id, value);
            return;
          }
          // Scanner failed (unusual tuple shape) — fall through to full parse
        }

        // Fast path for wrapper objects: scan the top-level JSON object to
        // find key→value boundaries.  Large values (> 128 chars) are kept as
        // raw JSON substrings and attached as lazy getters — their JSON.parse
        // + deserializeValue cost is deferred until first property access.
        // Small values are parsed eagerly.  This is particularly effective for
        // mixed payloads like {tree: <huge element>, data: [...], date: "$D..."}.
        if (rest.length > 256 && rest.charCodeAt(0) === 0x7b) {
          const fields = _scanObjectRow(rest, 128);
          if (fields) {
            const obj = this._buildLazyObject(rest, fields);
            if (obj) {
              this.resolveChunk(id, obj);
              return;
            }
          }
          // Scanner failed — fall through to full parse
        }

        const json = JSON.parse(rest);

        // Check if this is a streaming completion marker
        if (json && typeof json === "object" && json.complete === true) {
          // This is a completion marker for a streaming chunk
          this.finalizeStreamingChunk(id, json);
          return;
        }

        // Check if this chunk is already a streaming chunk (accumulating values)
        const existingChunk = this.chunks.get(id);
        if (existingChunk && existingChunk.type === "streaming") {
          // Append value to streaming chunk
          existingChunk.value.push(json);
          return;
        }

        // Try to resolve the model row immediately.  Only fall back to
        // deferred resolution when the JSON contains chunk references ($N)
        // that haven't been resolved yet — which requires placeholders so
        // other chunks can reference this one before its properties are filled.
        //
        // For the common case (data payloads, inlined values), this avoids:
        //  • _areDepsResolved — recursive dependency scan
        //  • deferred placeholder + property-copy pass
        //  • collectPathRefSentinels — recursive sentinel scan
        const chunk = this.getChunk(id);
        let value;
        if (Array.isArray(json) && json[0] === "$" && json.length >= 3) {
          // React element tuple — always resolved immediately
          value = this.deserializeValue(json);
          this.resolveChunk(id, value);
        } else if (json && typeof json === "object") {
          // Object or array — try immediate resolution.
          //
          // Fast path: hasSpecialBytes is pre-computed from raw bytes in
          // processData using single-byte memchr (~5x faster than 2-char
          // string indexOf on large payloads).  When no '$' or '@' bytes
          // exist, the JSON.parse result needs zero transformation — skip
          // the entire deserializeValue tree walk.  This turns a 10K-element
          // array from O(n) walk to O(1).
          if (!hasSpecialBytes) {
            // Pure data — JSON.parse result is the final value.
            // Mark chunk so Map/Set builders can skip deserializeValue.

            const chunk = this.getChunk(id);
            chunk._plainData = true;
            this.resolveChunk(id, json);
          } else if (this._areDepsResolved(json)) {
            value = this.deserializeValue(json);
            this.resolveChunk(id, value);
          } else {
            // Forward/circular references exist — use deferred path
            const isArray = Array.isArray(json);
            value = isArray ? Array.from({ length: json.length }) : {};
            chunk.status = RESOLVED;
            chunk.value = value;
            chunk._rawJson = json;
            if (chunk._promise !== null) {
              chunk._promise.status = "fulfilled";
              chunk._promise.value = value;
              chunk._resolve(value);
            }
            this.deferredChunks.push({
              type: isArray ? "array" : "object",
              value,
              json,
              chunk,
            });
          }
        } else {
          value = this.deserializeValue(json);
          this.resolveChunk(id, value);
        }
      } catch (error) {
        this.rejectChunk(id, error);
      }
    }
  }

  /**
   * Append text content to a streaming chunk
   */
  appendTextChunk(id, textContent) {
    let chunk = this.chunks.get(id);
    if (!chunk) {
      // Create a streaming text chunk
      chunk = {
        status: PENDING,
        value: [],
        type: "text",
        _promise: null,
        _resolve: null,
        _reject: null,
      };
      this._ensurePromise(chunk);
      this.chunks.set(id, chunk);
    } else if (!chunk.type) {
      // Existing chunk that wasn't marked as text - upgrade it
      chunk.type = "text";
      if (!Array.isArray(chunk.value)) {
        chunk.value = [];
      }
    }

    // Append the text content
    if (Array.isArray(chunk.value)) {
      chunk.value.push(textContent);
      // If this chunk has a stream controller, push data as a string
      // (not encoded to Uint8Array) so consumers see the original text.
      if (chunk._controller) {
        try {
          chunk._controller.enqueue(textContent);
        } catch {
          // Controller may be closed
        }
      }
    }
  }

  /**
   * Append binary content to a streaming chunk
   * Content is base64 encoded for safe text transport
   */
  appendBinaryChunk(id, base64Content) {
    let chunk = this.chunks.get(id);
    if (!chunk) {
      chunk = {
        status: PENDING,
        value: [],
        type: "binary",
        _promise: null,
        _resolve: null,
        _reject: null,
      };
      this._ensurePromise(chunk);
      this.chunks.set(id, chunk);
    } else if (!chunk.type) {
      // Existing chunk that wasn't marked as binary - upgrade it
      chunk.type = "binary";
      if (!Array.isArray(chunk.value)) {
        chunk.value = [];
      }
    }

    // Decode base64 to binary
    const binaryString = atob(base64Content);
    const bytes = new Uint8Array(binaryString.length);
    for (let i = 0; i < binaryString.length; i++) {
      bytes[i] = binaryString.charCodeAt(i);
    }

    if (Array.isArray(chunk.value)) {
      chunk.value.push(bytes);
      // If this chunk has a stream controller, push data
      if (chunk._controller) {
        try {
          chunk._controller.enqueue(bytes);
        } catch {
          // Controller may be closed
        }
      }
    }
  }

  /**
   * Finalize a streaming chunk when complete marker is received
   */
  finalizeStreamingChunk(id, metadata) {
    const chunk = this.chunks.get(id);
    if (!chunk || chunk.status !== PENDING) {
      return;
    }

    // Handle ReadableStream or AsyncIterable completion
    if (
      metadata.type === "ReadableStream" ||
      metadata.type === "AsyncIterable"
    ) {
      chunk.status = RESOLVED;
      // Close the stream controller if it exists
      if (chunk._controller) {
        try {
          chunk._controller.close();
        } catch {
          // Controller may already be closed
        }
      }
      chunk._resolve(chunk.value);
      return;
    }

    if (chunk.type === "text") {
      const fullText = chunk.value.join("");
      chunk.status = RESOLVED;
      chunk.value = fullText;
      chunk._promise.status = "fulfilled";
      chunk._promise.value = fullText;
      chunk._resolve(fullText);
    } else if (chunk.type === "binary") {
      const totalLength = chunk.value.reduce(
        (sum, arr) => sum + arr.byteLength,
        0
      );
      const result = new Uint8Array(totalLength);
      let offset = 0;
      for (const arr of chunk.value) {
        result.set(arr, offset);
        offset += arr.byteLength;
      }

      let finalValue;
      if (metadata.type === "ArrayBuffer") {
        finalValue = result.buffer;
      } else if (metadata.type === "Blob") {
        finalValue = new Blob([result], { type: metadata.mimeType || "" });
      } else {
        finalValue = createTypedArray(
          metadata.type,
          result.buffer,
          this.typeRegistry
        );
      }

      chunk.status = RESOLVED;
      chunk.value = finalValue;
      chunk._promise.status = "fulfilled";
      chunk._promise.value = finalValue;
      chunk._resolve(finalValue);
    }
  }

  /**
   * Resolve a module reference
   * The moduleLoader can implement:
   * - preloadModule(metadata): Promise | null - optional, starts loading the module
   * - requireModule(metadata): T | Promise<T> - loads/returns the module (sync or async)
   */
  resolveModuleReference(id, rawMetadata) {
    // Normalize metadata: accept both array [id, chunks, name, async?] and object {id, chunks, name, async?}
    const metadata = Array.isArray(rawMetadata)
      ? {
          id: rawMetadata[0],
          chunks: rawMetadata[1] || [],
          name: rawMetadata[2] || "default",

          async: rawMetadata.length === 4 ? !!rawMetadata[3] : false,
        }
      : rawMetadata;

    const loader = this.moduleLoader;

    // Start preloading if supported - this kicks off async loading early
    let preloadPromise = null;
    if (loader.preloadModule) {
      preloadPromise = loader.preloadModule(metadata);
    }

    // Try to resolve the module now. If the loader returns a sync value,
    // resolve the chunk immediately with the actual export (matching
    // webpack's synchronous requireModule behavior). If it returns a
    // Promise (e.g. Vite's import()), keep the chunk PENDING and track
    // the Promise — the consume loop will await all pending imports
    // before calling resolveDeferredChunks(), so model rows with $L
    // references to this chunk will naturally defer until the module
    // is available. This avoids lazy wrappers entirely.
    if (loader.requireModule) {
      let result;
      try {
        result = loader.requireModule(metadata);
      } catch (syncError) {
        // requireModule threw synchronously (e.g. missing module cache).
        // Reject the chunk gracefully instead of crashing the stream consumer.
        // rejectChunk handles the lazy _promise pattern (annotates .reason,
        // attaches no-op .catch to suppress unhandledRejection, and calls
        // _reject if a promise was already materialized).
        this.rejectChunk(id, syncError);
        return;
      }
      if (result && typeof result.then === "function") {
        // Fast path: if the Promise is already fulfilled (cached import()),
        // resolve synchronously — matching webpack's moduleLoader
        // behavior where modules are always available immediately.
        if (result.status === "fulfilled") {
          const module = result.value;
          const exportName = metadata.name || "default";
          const exported =
            typeof module === "object" && module !== null
              ? (module[exportName] ?? module.default ?? module)
              : module;
          this.resolveChunk(id, exported);
          return;
        }
        // Async module — keep chunk pending, resolve when import completes
        const importPromise = result.then(
          (module) => {
            const exportName = metadata.name || "default";
            const exported =
              typeof module === "object" && module !== null
                ? (module[exportName] ?? module.default ?? module)
                : module;
            this.resolveChunk(id, exported);
          },
          (error) => {
            // Async import rejected — route through rejectChunk so the lazy
            // _promise pattern is honored (see syncError branch above).
            this.rejectChunk(id, error);
          }
        );
        this.pendingModuleImports.push(importPromise);
        return; // chunk stays pending
      }
      if (result !== undefined) {
        // Sync module — resolve directly with the export
        const exportName = metadata.name || "default";
        const exported =
          typeof result === "object" && result !== null
            ? (result[exportName] ?? result.default ?? result)
            : result;
        this.resolveChunk(id, exported);
        return;
      }
    }

    // No loader or no requireModule — resolve with a client reference
    // descriptor (used by server-side fromBuffer where no moduleLoader
    // is provided)
    const reference = {
      $$typeof: REACT_CLIENT_REFERENCE,
      $$id: metadata.id + "#" + metadata.name,
      $$metadata: metadata,
      $$loader: loader,
      $$preload: preloadPromise,
    };

    this.resolveChunk(id, reference);
  }

  /**
   * Process a hint (preload)
   */
  processHint(hint) {
    // Hints are used for preloading resources
    // The moduleLoader can implement preloadModule to handle this
    if (hint.chunks && this.moduleLoader.preloadModule) {
      for (const chunk of hint.chunks) {
        this.moduleLoader.preloadModule({ chunks: [chunk] });
      }
    }
    // Handle hint codes for different resource types
    if (hint.code && this.options.onHint) {
      this.options.onHint(hint.code, hint.model);
    }
  }

  /**
   * Process debug info
   */
  processDebugInfo(id, debugInfo) {
    // Store debug info for development tools
    if (this.options.onDebugInfo) {
      this.options.onDebugInfo(id, debugInfo);
    }
  }

  /**
   * Process console replay
   */
  processConsoleReplay(consoleInfo) {
    const { method, args, env } = consoleInfo;

    // Deserialize the args
    const deserializedArgs = args.map((arg) => {
      try {
        return this.deserializeValue(arg);
      } catch {
        return arg;
      }
    });

    // Prefix with environment name
    const prefix = env ? `[${env}]` : "[Server]";

    // Replay the console call
    if (typeof console[method] === "function") {
      console[method](prefix, ...deserializedArgs);
    }
  }

  /**
   * Deserialize a value from Flight format.
   *
   * Uses copy-on-write: if no property in an object/array changes during
   * deserialization, the original JSON-parsed object is returned directly —
   * avoiding an allocation + property copy for the common case where values
   * are plain primitives/strings with no protocol-special prefixes.
   */
  deserializeValue(value) {
    if (value === null || value === undefined) {
      return value;
    }

    if (typeof value === "string") {
      return this.deserializeString(value);
    }

    if (typeof value === "number" || typeof value === "boolean") {
      return value;
    }

    // Return TypedArrays and ArrayBuffers directly - they're already deserialized
    if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
      return value;
    }

    if (Array.isArray(value)) {
      // Check for element tuple: ["$", type, key, ref, props]
      if (value[0] === "$" && value.length >= 3) {
        return this.deserializeElement(value);
      }
      // Copy-on-write: only allocate a new array if an element changes
      let result = value;
      for (let i = 0; i < value.length; i++) {
        const orig = value[i];
        const deserialized = this.deserializeValue(orig);
        if (deserialized !== orig) {
          if (result === value) {
            // First change — shallow-copy elements seen so far
            result = value.slice(0, i);
          }
        }
        if (result !== value) {
          result.push(deserialized);
        }
      }
      return result;
    }

    if (typeof value === "object") {
      // Don't re-serialize Map, Set, or other special objects that were already deserialized
      if (
        value instanceof Map ||
        value instanceof Set ||
        value instanceof Date ||
        value instanceof RegExp ||
        ArrayBuffer.isView(value)

      ) {
        return value;
      }
      // Copy-on-write: only allocate a new object if a property value changes
      const keys = Object.keys(value);
      let result = value;
      for (let i = 0; i < keys.length; i++) {
        const key = keys[i];
        const orig = value[key];
        const deserialized = this.deserializeValue(orig);
        if (deserialized !== orig) {
          if (result === value) {
            // First change — copy properties seen so far
            result = {};
            for (let j = 0; j < i; j++) result[keys[j]] = value[keys[j]];
          }
        }
        if (result !== value) {
          result[key] = deserialized;
        }
      }
      return result;
    }

    return value;
  }

  /**
   * Deserialize a string value
   */
  deserializeString(value) {
    // Fast exit for the overwhelmingly common case: plain strings with no
    // protocol prefix.  Checking the first char code avoids the cost of
    // multiple startsWith calls on every string in the payload.
    const ch = value.charCodeAt(0);
    // 0x24 = '$', 0x40 = '@'
    if (ch !== 0x24 && ch !== 0x40) {
      return value;
    }

    // Handle @ prefixes
    if (ch === 0x40) {
      // @@ escaped strings (literal @ prefix)
      if (value.charCodeAt(1) === 0x40) {
        return value.slice(1);
      }
      // @ or $@ references (Promise references)
      const id = parseInt(value.slice(1), 10);
      const chunk = this.getChunk(id);
      return this._ensurePromise(chunk);
    }

    // Handle $@ references (Promise references - React format)
    if (value.charCodeAt(1) === 0x40) {
      const id = parseInt(value.slice(2), 10);
      const chunk = this.getChunk(id);
      return this._ensurePromise(chunk);
    }

    if (value === "$undefined") {
      return undefined;
    }
    if (value === "$NaN") {
      return NaN;
    }
    if (value === "$Infinity") {
      return Infinity;
    }
    if (value === "$-Infinity") {
      return -Infinity;
    }
    if (value === "$-0") {
      return -0;
    }

    if (value.startsWith("$$")) {
      // Escaped $
      return value.slice(1);
    }

    if (value.startsWith("$n")) {
      // BigInt
      return BigInt(value.slice(2));
    }

    if (value.startsWith("$R")) {
      // RegExp - $R followed by the regex string (e.g., /pattern/flags)
      const regexStr = value.slice(2);
      const match = regexStr.match(/^\/(.*)\/([gimsuy]*)$/);
      if (match) {
        return new RegExp(match[1], match[2]);
      }
      // Fallback: try to eval the regex string
      try {
        return new Function("return " + regexStr)();
      } catch {
        return regexStr;
      }
    }

    // Check exact match for $S (Suspense) before startsWith check for symbols
    if (value === "$S") {
      return REACT_SUSPENSE_TYPE;
    }

    if (value.startsWith("$S")) {
      // Symbol - $S followed by the symbol key
      return Symbol.for(value.slice(2));
    }

    // Fragment type
    if (value === "$f") {
      return REACT_FRAGMENT_TYPE;
    }

    if (value.startsWith("$D")) {
      // Date
      return new Date(value.slice(2));
    }

    if (value.startsWith("$T")) {
      // Temporary reference - look up in the temp refs map
      const key = value.slice(2);
      if (this.temporaryReferences && this.temporaryReferences.has(key)) {
        return this.temporaryReferences.get(key);
      }
      // If not found, return the raw value (shouldn't happen in valid round-trips)
      return value;
    }

    if (value.startsWith("$Q")) {
      // Map — $Q followed by a chunk id (digit) or inline JSON
      const rest = value.slice(2);
      const ch2 = rest.charCodeAt(0);
      if (ch2 >= 0x30 && ch2 <= 0x39) {
        // Row reference ($Q<digits>)
        const id = parseInt(rest, 10);
        const chunk = this.getChunk(id);
        if (chunk.status === RESOLVED) {
          const entries = chunk._rawJson || chunk.value;
          // If the entries chunk was pure data (no $ or @ in its row),
          // all keys/values are plain — skip per-entry deserializeValue.
          return this._buildMap(entries, !!chunk._plainData);
        }
        return this._ensurePromise(chunk).then((entries) =>
          this._buildMap(entries)
        );
      }
      return this._buildMap(JSON.parse(rest));
    }

    if (value.startsWith("$W")) {
      // Set — $W followed by a chunk id (digit) or inline JSON
      const rest = value.slice(2);
      const ch2 = rest.charCodeAt(0);
      if (ch2 >= 0x30 && ch2 <= 0x39) {
        const id = parseInt(rest, 10);
        const chunk = this.getChunk(id);
        if (chunk.status === RESOLVED) {
          const items = chunk._rawJson || chunk.value;
          return this._buildSet(items, !!chunk._plainData);
        }
        return this._ensurePromise(chunk).then((items) =>
          this._buildSet(items)
        );
      }
      return this._buildSet(JSON.parse(rest));
    }

    if (value.startsWith("$Y")) {
      // TypedArray/ArrayBuffer/DataView (including custom subclasses)
      const { type, data } = JSON.parse(value.slice(2));
      const binary = atob(data);
      const bytes = new Uint8Array(binary.length);
      for (let i = 0; i < binary.length; i++) {
        bytes[i] = binary.charCodeAt(i);
      }
      if (type === "ArrayBuffer") {
        return bytes.buffer;
      }
      // Check typeRegistry first for custom classes, then globalThis for built-ins
      const TypedArrayConstructor = this.typeRegistry[type] || globalThis[type];
      if (TypedArrayConstructor) {
        return new TypedArrayConstructor(bytes.buffer);
      }
      return bytes;
    }

    if (value.startsWith("$L")) {
      // Lazy reference (client reference)
      const rest = value.slice(2);
      const id = parseInt(rest, 10);

      // Check if it's a numeric ID (references a module row) or inline format (id#name)
      if (!isNaN(id)) {
        // Numeric ID - references a module row (I row).
        // With async module loading (browser), resolveModuleReference keeps
        // the chunk PENDING until import() completes, then resolves it with
        // the actual module export (function).  For sync loaders, the chunk
        // is already RESOLVED with the export.  For no-loader contexts

        // (server-side fromBuffer), the chunk holds a client reference
        // descriptor — in that case we need a lazy wrapper so the RSC
        // renderer can call _init to get the reference.
        const chunk = this.getChunk(id);

        if (chunk.status === RESOLVED) {
          const resolvedValue = chunk.value;
          // If the resolved value is an actual module export (function/string),
          // return it directly — this is the fast path for resolved imports.
          if (
            typeof resolvedValue === "function" ||
            typeof resolvedValue === "string"
          ) {
            return resolvedValue;
          }
          // If it's a client reference descriptor (from no-loader context),
          // wrap in a lazy wrapper so the RSC server renderer can properly
          // process it via _init/_payload.
          if (
            resolvedValue &&
            resolvedValue.$$typeof === REACT_CLIENT_REFERENCE
          ) {
            return this.createLazyWrapper(chunk);
          }
          // Other resolved values (plain objects, etc.) — return directly
          return resolvedValue;
        }
        // Chunk still pending (async import in progress) — return a lazy
        // wrapper so React can suspend and retry when the import completes
        return this.createLazyWrapper(chunk);
      }

      // Inline format: $Lmodule/path.js#exportName
      // Parse the inline client reference
      const hashIndex = rest.indexOf("#");
      if (hashIndex !== -1) {
        const moduleId = rest.slice(0, hashIndex);
        const exportName = rest.slice(hashIndex + 1);

        const loader = this.moduleLoader;
        if (loader && loader.requireModule) {
          // Create metadata for the module loader
          const metadata = {
            id: moduleId,
            name: exportName,
            chunks: [],
          };

          // Start preloading if supported
          if (loader.preloadModule) {
            loader.preloadModule(metadata);
          }

          // Create a client reference
          const reference = {
            $$typeof: REACT_CLIENT_REFERENCE,
            $$id: rest,
            $$metadata: metadata,
            $$loader: loader,
          };

          // Create a synthetic chunk for the lazy wrapper
          const syntheticChunk = {
            id: rest,
            status: RESOLVED,
            value: reference,
            promise: Promise.resolve(reference),
          };

          return this.createLazyWrapper(syntheticChunk);
        }
      }

      // No moduleLoader or invalid format - return a placeholder reference
      return {
        $$typeof: REACT_CLIENT_REFERENCE,
        $$id: rest,
      };
    }

    if (value.startsWith("$h")) {
      // Server reference (outlined chunk) — React's wire format
      // $h<chunkId> where chunkId references a model row with {id, bound}
      const chunkId = parseInt(value.slice(2), 10);
      const chunk = this.getChunk(chunkId);
      if (chunk.status === RESOLVED) {
        const model = chunk._rawJson || chunk.value;
        const id = model.id;
        // Deserialize bound to resolve $@ Promise references (webpack) or inline arrays (lazarv)
        const bound = this.deserializeValue(model.bound);
        if (bound && Array.isArray(bound) && bound.length > 0) {
          return this.createServerAction(id, bound);
        }
        // bound may be a Promise (from $@ reference in React's format)
        if (bound && typeof bound.then === "function") {
          // Wrap in a server action that resolves bound args lazily
          const action = this.createServerAction(id);
          const originalAction = action;
          const response = this;
          const lazyAction = async (...args) => {
            const resolvedBound = await bound;
            return response.callServer(id, [...resolvedBound, ...args]);
          };
          lazyAction.$$typeof = originalAction.$$typeof;
          lazyAction.$$id = originalAction.$$id;
          lazyAction.$$bound = bound;
          lazyAction.$$FORM_ACTION = originalAction.$$FORM_ACTION;
          lazyAction.$$IS_SIGNATURE_EQUAL = originalAction.$$IS_SIGNATURE_EQUAL;
          lazyAction.bind = originalAction.bind;
          return lazyAction;
        }
        return this.createServerAction(id);
      }
      // Chunk not yet resolved — shouldn't normally happen since outlined chunks
      // are emitted before the model row that references them
      return this._ensurePromise(chunk).then((model) => {
        const id = model.id;
        const bound = model.bound;
        if (bound && Array.isArray(bound) && bound.length > 0) {
          const boundArgs = bound.map((arg) => this.deserializeValue(arg));
          return this.createServerAction(id, boundArgs);
        }
        return this.createServerAction(id);
      });
    }

    // Note: $@ (Promise references) and @ (legacy Promise refs) are handled at the top of deserializeString
    // Note: $S (Symbol.for) and $f (Fragment) are handled earlier in the function

    if (value.startsWith("$K")) {
      // FormData - may contain async values (Blobs)
      const entries = JSON.parse(value.slice(2));
      const formData = new FormData();

      // Check if any entries contain Blob references
      const hasAsyncValues = entries.some(
        ([, v]) =>
          typeof v === "string" && (v.startsWith("$B") || v.startsWith("$b"))
      );

      if (hasAsyncValues) {
        // Return a Promise that resolves to FormData after all async values are resolved
        return (async () => {
          for (const [k, v] of entries) {
            let resolved = this.deserializeValue(v);
            if (resolved instanceof Promise) {
              resolved = await resolved;
            }
            formData.append(k, resolved);
          }
          return formData;
        })();
      }

      // Synchronous case - no Blob references
      for (const [k, v] of entries) {
        formData.append(k, this.deserializeValue(v));
      }
      return formData;
    }

    if (value.startsWith("$l")) {
      // URL
      return new URL(value.slice(2));
    }

    if (value.startsWith("$U")) {
      // URLSearchParams
      const entries = JSON.parse(value.slice(2));
      const params = new URLSearchParams();
      for (const [k, v] of entries) {
        params.append(k, v);
      }
      return params;
    }

    if (value.startsWith("$Z")) {
      // Error object
      const errorInfo = JSON.parse(value.slice(2));
      const ErrorConstructor = globalThis[errorInfo.name] || Error;
      const error = new ErrorConstructor(errorInfo.message);
      error.stack = errorInfo.stack;
      // Restore any custom properties
      for (const key of Object.keys(errorInfo)) {
        if (key !== "name" && key !== "message" && key !== "stack") {
          error[key] = this.deserializeValue(errorInfo[key]);
        }
      }
      return error;
    }

    if (value.startsWith("$b")) {
      // Binary stream reference (large TypedArray/ArrayBuffer)
      const id = parseInt(value.slice(2), 16);
      const chunk = this.getChunk(id);
      return this._ensurePromise(chunk);
    }

    if (value.startsWith("$B")) {
      // Blob stream reference

      const id = parseInt(value.slice(2), 16);
      const chunk = this.getChunk(id);
      return this._ensurePromise(chunk);
    }

    if (value.startsWith("$r")) {
      // ReadableStream reference
      const id = parseInt(value.slice(2), 16);
      const chunk = this.getOrCreateStreamingChunk(id);
      return this.createStreamWrapper(chunk, "ReadableStream");
    }

    if (value.startsWith("$i")) {
      // Async iterable reference
      const id = parseInt(value.slice(2), 16);
      const chunk = this.getOrCreateStreamingChunk(id);
      return this.createAsyncIterableWrapper(chunk);
    }

    // Handle generic chunk references ($1, $2, etc.) and path references ($1:key:...)
    // The second char must be a digit (0x30-0x39) to distinguish from named prefixes
    // like $S, $D, $Q etc. that were already handled above.
    {
      const ch1 = value.charCodeAt(1);
      if (ch1 >= 0x30 && ch1 <= 0x39) {
        const colonIndex = value.indexOf(":");
        if (colonIndex === -1) {
          // Simple chunk ref: $N
          const id = parseInt(value.slice(1), 10);
          const chunk = this.getChunk(id);
          if (chunk.status === RESOLVED) {
            return chunk.value;
          }
          return this._ensurePromise(chunk).then((v) => v);
        }
        // Path ref: $N:path:to:prop
        const id = parseInt(value.slice(1, colonIndex), 10);
        const path = value.slice(colonIndex + 1);
        const chunk = this.getChunk(id);
        if (chunk.status === RESOLVED) {
          if (this._resolvingDeferred) {
            return { __pathRef: true, id, path };
          }
          return this.resolvePath(chunk.value, path);
        }
        return this._ensurePromise(chunk).then((v) =>
          this.resolvePath(v, path)
        );
      }
    }

    return value;
  }

  /**
   * Resolve a path reference like "first" or "a:ref" within an object
   */
  resolvePath(obj, path) {
    const keys = path.split(":");
    let current = obj;
    for (const key of keys) {
      if (current == null) return undefined;
      // Handle array indices (numeric keys)
      current = current[key];
    }
    return current;
  }

  /**
   * Create a wrapper for a streaming ReadableStream
   */
  createStreamWrapper(chunk, _type) {
    // Return a ReadableStream that receives chunks pushed via the controller
    return new ReadableStream({
      start(controller) {
        // Store controller reference for streaming data push
        chunk._controller = controller;

        // Flush any already-accumulated values that arrived before the
        // controller was set up (text/binary rows received before $r deserialization)
        if (Array.isArray(chunk.value) && chunk.value.length > 0) {
          for (const item of chunk.value) {
            try {
              // Enqueue text as strings, binary as Uint8Array — preserve the
              // original type so consumers see what the server sent.
              controller.enqueue(item);
            } catch {
              // Controller may be closed
            }
          }
        }

        // If chunk is already complete, close
        if (chunk.status === RESOLVED) {
          controller.close();
        } else if (chunk.status === REJECTED) {
          controller.error(chunk.reason);
        }
      },
      cancel() {
        // Handle cancellation — mark as closed and reject the chunk
        // so that any other consumers (e.g. async iterable wrapper) also stop.
        chunk._controllerClosed = true;
        if (chunk.status === PENDING) {
          chunk.status = REJECTED;
          chunk.error = new DOMException(
            "The stream was cancelled",
            "AbortError"
          );
          chunk._reject(chunk.error);
        }
      },
    });
  }

  /**
   * Create a wrapper for a streaming async iterable
   */
  createAsyncIterableWrapper(chunk) {
    const self = this;
    const wrapper = {
      [Symbol.asyncIterator]: function asyncIterator() {
        let index = 0;
        const iterator = {
          async next() {
            // If we have accumulated values, yield them first
            if (Array.isArray(chunk.value) && index < chunk.value.length) {
              const value = self.deserializeValue(chunk.value[index++]);
              return { done: false, value };
            }
            // Check for error after yielding all accumulated values
            if (chunk.status === REJECTED) {
              throw chunk.error || chunk.value;
            }
            // If complete and we've consumed all values, done
            if (chunk.status === RESOLVED) {
              return { done: true, value: undefined };
            }
            // Wait for more data
            await new Promise((resolve) => setTimeout(resolve, 10));
            return iterator.next();
          },
        };
        return iterator;
      },
    };
    return wrapper;
  }

  /**
   * Deserialize a React element from tuple format
   */
  deserializeElement(tuple) {
    // Formats:
    // React 19: ["$", type, key, props, owner?, debugInfo?, debugStack?]
    // Legacy:   ["$", type, key, ref, props]
    //
    // Heuristic: if the 4th element is a non-array object (or undefined),
    // it's props (React 19 format).  Otherwise it's a ref (legacy).
    const rawType = tuple[1];
    const rawKey = tuple[2];

    // Deserialize type — usually a plain string (e.g., "div") which
    // deserializeString returns unchanged via the fast charCode path.
    const type =
      typeof rawType === "string"
        ? this.deserializeString(rawType)
        : this.deserializeValue(rawType);

    const fourth = tuple[3];
    const isLegacy =
      tuple.length === 5 || (fourth === null && tuple[4] !== undefined);
    const isReact19 =
      !isLegacy &&
      fourth !== undefined &&
      fourth !== null &&
      typeof fourth === "object" &&
      !Array.isArray(fourth);

    // For trivial cases (no props), resolve immediately — no getter overhead
    if (!isLegacy && !isReact19) {
      return _devElement({
        $$typeof: REACT_TRANSITIONAL_ELEMENT_TYPE,
        type,
        key: rawKey !== undefined ? rawKey : null,
        ref: null,
        props: {},
      });
    }

    // Determine raw props source for lazy deserialization
    const rawProps = isLegacy ? tuple[4] : fourth;
    const rawRef = isLegacy ? fourth : null;

    // If rawProps is falsy (null/undefined), resolve immediately
    if (!rawProps) {
      return _devElement({
        $$typeof: REACT_TRANSITIONAL_ELEMENT_TYPE,
        type,
        key: rawKey !== undefined ? rawKey : null,

        ref:
          rawRef !== null && rawRef !== undefined
            ? this.deserializeValue(rawRef)
            : null,
        props: {},
      });
    }

    // For small props objects without nested elements or references,
    // eager resolution is faster (avoids Object.defineProperty + closure).
    // Use lazy getter only when props is large enough to benefit.
    const propKeys = Object.keys(rawProps);
    let isSimpleProps = propKeys.length <= 4;
    if (isSimpleProps) {
      for (let k = 0; k < propKeys.length; k++) {
        const v = rawProps[propKeys[k]];
        if (
          typeof v === "string" &&
          v.length > 0 &&
          (v.charCodeAt(0) === 0x24 || v.charCodeAt(0) === 0x40)
        ) {
          isSimpleProps = false;
          break;
        }
        if (typeof v === "object" && v !== null) {
          isSimpleProps = false;
          break;
        }
      }
    }

    if (isSimpleProps) {
      // Eager path — deserialize props inline, no lazy getter overhead
      const props = this.deserializeValue(rawProps);
      const isR19 = !isLegacy;
      return _devElement({
        $$typeof: REACT_TRANSITIONAL_ELEMENT_TYPE,
        type,
        key: rawKey !== undefined ? rawKey : null,
        ref: isR19
          ? props.ref || null
          : rawRef !== null && rawRef !== undefined
            ? this.deserializeValue(rawRef)
            : null,
        props,
      });
    }

    // Lazy props deserialization via self-replacing getter.
    // React elements in large trees are often only partially consumed
    // (e.g., a list of 1000 items where only 50 are visible). Deferring
    // props deserialization until first access avoids recursively walking
    // the entire element tree upfront.
    return this._makeElementWithLazyProps(
      type,
      rawKey,
      rawRef,
      rawProps,
      false,
      !isLegacy
    );
  }

  /**
   * Create an element from a scan result (partial JSON parse).
   * Props are still a raw JSON string — JSON.parse is deferred to the lazy getter.
   */
  deserializeElementFromScan(scan) {
    // Deserialize type — usually a plain string (e.g., "div")
    const type =
      typeof scan.type === "string"
        ? this.deserializeString(scan.type)
        : this.deserializeValue(scan.type);

    const rawPropsStr = scan.rawPropsStr;

    // Trivial: no props string or "null" / "{}"
    if (!rawPropsStr || rawPropsStr === "null") {
      return _devElement({
        $$typeof: REACT_TRANSITIONAL_ELEMENT_TYPE,
        type,
        key: scan.key !== undefined ? scan.key : null,
        ref: scan.rawRefStr
          ? this.deserializeValue(JSON.parse(scan.rawRefStr))
          : null,
        props: {},
      });
    }

    if (rawPropsStr === "{}") {
      return _devElement({
        $$typeof: REACT_TRANSITIONAL_ELEMENT_TYPE,
        type,
        key: scan.key !== undefined ? scan.key : null,
        ref: scan.rawRefStr
          ? this.deserializeValue(JSON.parse(scan.rawRefStr))
          : null,
        props: {},
      });
    }

    // Determine if legacy (has rawRefStr) or React 19
    const isLegacy = scan.rawRefStr !== null;
    const rawRef = isLegacy && scan.rawRefStr ? scan.rawRefStr : null;

    return this._makeElementWithLazyProps(
      type,
      scan.key,
      rawRef,
      rawPropsStr,
      true,
      !isLegacy
    );
  }

  /**
   * Shared implementation for creating elements with lazy props.
   * @param {*} type - Already-deserialized element type
   * @param {*} rawKey - Raw key value
   * @param {*} rawRef - Raw ref (string for scan path, object for tuple path), or null
   * @param {*} rawProps - Either a parsed object (tuple path) or a raw JSON string (scan path)
   * @param {boolean} propsIsString - true if rawProps is a JSON string needing JSON.parse first
   * @param {boolean} isReact19 - true if React 19 format (ref is inside props)
   */
  _makeElementWithLazyProps(
    type,
    rawKey,
    rawRef,
    rawProps,
    propsIsString,
    isReact19
  ) {
    const response = this;
    const element = _devElement({
      $$typeof: REACT_TRANSITIONAL_ELEMENT_TYPE,
      type,
      key: rawKey !== undefined ? rawKey : null,
      ref:
        !isReact19 && rawRef != null
          ? propsIsString
            ? response.deserializeValue(JSON.parse(rawRef))
            : response.deserializeValue(rawRef)
          : null,
    });

    let _cachedProps;
    Object.defineProperty(element, "props", {
      get() {
        if (_cachedProps === undefined) {
          // If props is a raw JSON string, parse it first, then deserialize
          const parsed = propsIsString ? JSON.parse(rawProps) : rawProps;
          _cachedProps = response.deserializeValue(parsed);
          if (isReact19) {
            element.ref = _cachedProps.ref || null;
          }
          // Replace getter with plain data property for subsequent accesses
          Object.defineProperty(element, "props", {
            value: _cachedProps,
            writable: true,
            enumerable: true,
            configurable: true,
          });
        }
        return _cachedProps;
      },
      set(v) {
        _cachedProps = v;
        Object.defineProperty(element, "props", {
          value: v,
          writable: true,
          enumerable: true,
          configurable: true,
        });
      },
      enumerable: true,
      configurable: true,
    });

    return element;
  }

  /**
   * Build an object from scanned field descriptors, using lazy getters for
   * large values and eager JSON.parse + deserializeValue for small ones.
   *
   * Returns the constructed object, or null if any field can't be handled
   * (caller falls back to full JSON.parse).
   */
  _buildLazyObject(str, fields) {
    const response = this;
    const obj = {};

    for (let f = 0; f < fields.length; f++) {
      const { key, valueStart, valueEnd, small } = fields[f];

      if (small) {
        // Small value — parse and deserialize eagerly (cheap)
        const raw = str.slice(valueStart, valueEnd);
        const parsed = JSON.parse(raw);
        obj[key] = response.deserializeValue(parsed);