[u9g]

Summary

Adds a packetParseFailure client event so that consumers can diagnose incoming packets that could not be parsed, without reaching into the deserializer.

This is the NMP side of PrismarineJS/mineflayer#4164 ("Dump packets that fail to parse to a local file"). That PR currently monkey-patches client.deserializer.parsePacketBuffer on every state change to catch the three failure kinds; @rom1504 asked in PrismarineJS/mineflayer#4164 (comment) for NMP to own the diagnostic so Mineflayer only consumes it. Once this is released, mineflayer#4164 will be reworked to listen to this event instead.

The event

client.on('packetParseFailure', failure => ...) with:

{
  type: 'ReadError' | 'PartialReadError' | 'SizeMismatch',
  state,       // protocol state the deserializer was built for
  direction,   // 'toClient' on a client, 'toServer' on a server-side client
  buffer,      // the raw (decompressed) packet buffer, including the packet id
  packetId,    // leading varint of buffer, or null
  packetName,  // from this version's protocol data for state/direction, or null
  error,       // the Error for ReadError / PartialReadError, else null
  bytesRead,   // metadata.size for SizeMismatch, else null
  partialData  // parsed data for SizeMismatch, else null
}

• ReadError: emitted from the existing deserializer error handler, before the existing error event. Existing behaviour is unchanged.
• PartialReadError: listens to the partialReadError event FullPacketParser emits since FullPacketParser: emit partialReadError with the chunk it could not read ProtoDef-io/node-protodef#178 (protodef 1.20.0, merged but not yet published to npm). Still not turned into an error event.
• SizeMismatch: in the data handler, when metadata.size !== fullBuffer.length; the packet is then emitted as before.

Nothing is computed unless there is a listener (listenerCount), and the diagnostic is wrapped so it can never throw into the stream pipeline. No stack-frame parsing: error.field / error.stack are passed through as-is.

Also adds the event to src/index.d.ts and documents it in docs/API.md.

Tests

test/packetParseFailureTest.js spins up an NMP server per supported version, connects a client, and has the server writeRaw:

• the keep_alive id with no body → PartialReadError with state: 'play', direction: 'toClient', packetName: 'keep_alive' and the sent buffer. This case is marked pending until protodef >= 1.20.0 is installed, since 1.19.0 swallows partial reads silently.
• a valid keep_alive with trailing bytes → SizeMismatch with bytesRead < buffer.length, and the keep_alive packet is still emitted.
• a well-formed keep_alive → no event.

A ReadError case is not covered: an unknown packet id parses as a 1-byte packet (a SizeMismatch) rather than throwing, so there is no easy raw-bytes way to trigger one.

Local results (protodef 1.19.0, Java 21): lint clean; packetTest, serverTest, cyclePacketTest, compressionTest, pingTest, docTest and the new test pass for 26.1, 1.12.2 and 1.8.8, plus the vanilla-server clientTest for 1.8.8 (26.1's vanilla server needs Java 25). With protodef master installed, the new PartialReadError case passes for all 30 versions.

---

Generated by Claude Code