eolib 1.2.0__tar.gz → 2.0.1__tar.gz

eolib-2.0.1/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "eo-protocol"]
+	path = eo-protocol
+	url = https://github.com/cirras/eo-protocol.git

eolib-2.0.1/CHANGELOG.md

@@ -0,0 +1,172 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2.0.1] - 2025-07-06
+
+### Fixed
+
+- Make `eolib.protocol.pub.server` types available from the top-level `eolib` package.
+
+## [2.0.0] - 2025-06-30
+
+### Added
+
+- `SpellReplyServerPacket` packet class.
+- `SkillStatRequirements` class.
+- `PlayerEffect` class.
+- `TileEffect` class.
+- `EffectPlayerServerPacket.effects` field.
+- `EffectAgreeServerPacket.effects` field.
+- `AdminInteractTellServerPacket.gold_bank` field.
+
+### Changed
+
+- Make protocol objects immutable.
+  - Protocol data structures are now fully instantiated via `__init__`, and can't be modified later.
+  - Array fields are now typed as tuples.
+- Rename `QuestReportServerPacket.npc_id` field to `npc_index`.
+- Make `CastReplyServerPacket.caster_tp` field optional.
+- Make `CastSpecServerPacket.caster_tp` field optional.
+- Make `CastAcceptServerPacket.caster_tp` field optional.
+- Make `CastAcceptServerPacket.experience` field optional.
+- Make `CastAcceptServerPacket.level_up` field optional.
+- Make `NpcAcceptServerPacket.experience` field optional.
+- Make `NpcAcceptServerPacket.level_up` field optional.
+- Change `TradeItemData` to represent a single player's trade items instead of both trade partners.
+- Change `TradeReplyServerPacket.trade_data` field type from `TradeItemData` to `TradeItemData[]`.
+- Change `TradeAdminServerPacket.trade_data` field type from `TradeItemData` to `TradeItemData[]`.
+- Change `TradeUseServerPacket.trade_data` field type from `TradeItemData` to `TradeItemData[]`.
+
+### Removed
+
+- All protocol object field setters.
+- `EffectPlayerServerPacket.player_id` field.
+- `EffectPlayerServerPacket.effect_id` field.
+- `EffectAgreeServerPacket.coords` field.
+- `EffectAgreeServerPacket.effect_id` field.
+- `WalkPlayerServerPacket.Direction` field.
+
+### Fixed
+
+- Fix incorrect (de)serialization of `EffectPlayerServerPacket` due to only the first effect in the
+  array being recognized.
+- Fix incorrect (de)serialization of `EffectAgreeServerPacket` due to only the first effect in the
+  array being recognized.
+- Fix inaccurate serialization of `QuestAcceptClientPacket` where the char value 0 should be written
+  for `DialogReply.Ok`.
+- Fix inaccurate serialization of `AccountReplyServerPacket` where the string value "OK" should be
+  written for `AccountReply.Changed`, but "NO" was being written instead.
+- Fix inaccurate serialization of `AdminInteractTellServerPacket` where the `gold_bank` field was
+  missing.
+- Fix inaccurate serialization of `RecoverPlayerServerPacket` where a trailing 0 short value was
+  missing.
+- Fix inaccurate serialization of `ShopOpenServerPacket` where a trailing break byte was erroneously
+  being written.
+- Fix inaccurate serialization of `DoorOpenServerPacket` where a trailing 0 char value was
+  erroneously being written.
+- Change incorrect `CharacterStatsInfoLookup.secondary_stats` field type from
+  `CharacterSecondaryStats` to `CharacterSecondaryStatsInfoLookup`.
+- Change incorrect `SkillLearn.stat_requirements` field type from `CharacterBaseStats` to
+  `SkillStatRequirements`.
+
+## [1.2.0] - 2025-06-30
+
+### Added
+
+- Support for Python 3.13.
+- Support for Python 3.14.
+- Support for server pub files:
+  - `DropRecord` class.
+  - `DropNpcRecord` class.
+  - `DropFile` class.
+  - `InnQuestionRecord` class.
+  - `InnRecord` class.
+  - `InnFile` class.
+  - `SkillMasterSkillRecord` class.
+  - `SkillMasterRecord` class.
+  - `SkillMasterFile` class.
+  - `ShopTradeRecord` class.
+  - `ShopCraftIngredientRecord` class.
+  - `ShopCraftRecord` class.
+  - `ShopRecord` class.
+  - `ShopFile` class.
+  - `TalkMessageRecord` class.
+  - `TalkRecord` class.
+  - `TalkFile` class.
+- `GuildTakeClientPacket.guild_tag` field.
+
+### Fixed
+
+- Fix bug on Python 3.13+ where any protocol enum instance constructed from an int value would be
+  treated like an unrecognized value.
+- Fix `AttributeError` on Python 3.14 because the readonly `__doc__` attribute was being assigned to
+  in generated protocol code.
+- Fix incorrect (de)serialization of some data structures containing arrays with trailing delimiters.
+- Fix incorrect (de)serialization of data structures containing both `<dummy>` and `<field>` elements.
+  (Only `ChestCloseServerPacket` was impacted.)
+- Fix incorrect (de)serialization of `NpcAgreeServerPacket` due to the `npcs` array's length being
+  treated as a `short` instead of `char`.
+- Fix incorrect (de)serialization of `GuildTakeClientPacket` due to missing `guild_tag` field.
+- Fix incorrect (de)serialization of `AvatarAdminServerPacket` due to incorrect ordering of the
+  `caster_direction` and `damage` fields.
+- Fix inaccurate (de)serialization of `JukeboxMsgClientPacket` due to the packet being treated as a
+  chunked data structure.
+- Sanitize strings within chunked sections of protocol data structures.
+  - Generated code now sets `EoWriter.string_sanitization_mode` during serialization.
+  - For more information, see
+    [Chunked Reading: Sanitization](https://github.com/Cirras/eo-protocol/blob/master/docs/chunks.md#sanitization).
+- Properly escape characters from the upsteam protocol XML in docstrings and downstream generated documentation.
+
+## [1.1.1] - 2024-08-22
+
+### Changed
+
+- The package is now [PEP 561](https://peps.python.org/pep-0561/) compatible, exposing type
+  information for usage in type checkers like
+  [mypy](https://mypy.readthedocs.io/en/stable/index.html).
+
+## [1.1.0] - 2023-12-19
+
+### Added
+
+- `WalkPlayerServerPacket.direction` field.
+
+### Changed
+
+- Remove trailing break from `ArenaSpecServerPacket`.
+- Remove trailing break from `ArenaAcceptServerPacket`.
+- Deprecate `WalkPlayerServerPacket.Direction` field.
+
+## [1.0.0] - 2023-11-07
+
+### Added
+
+- Support for EO data structures:
+  - Client packets
+  - Server packets
+  - Endless Map Files (EMF)
+  - Endless Item Files (EIF)
+  - Endless NPC Files (ENF)
+  - Endless Spell Files (ESF)
+  - Endless Class Files (ECF)
+- Utilities:
+  - Data reader
+  - Data writer
+  - Number encoding
+  - String encoding
+  - Data encryption
+  - Packet sequencer
+
+[Unreleased]: https://github.com/cirras/eolib-python/compare/v2.0.1...HEAD
+[2.0.1]: https://github.com/cirras/eolib-python/compare/v2.0.0...v2.0.1
+[2.0.0]: https://github.com/cirras/eolib-python/compare/v1.2.0...v2.0.0
+[1.2.0]: https://github.com/cirras/eolib-python/compare/v1.1.1...v1.2.0
+[1.1.1]: https://github.com/cirras/eolib-python/compare/v1.1.0...v1.1.1
+[1.1.0]: https://github.com/cirras/eolib-python/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/cirras/eolib-python/releases/tag/v1.0.0

eolib-2.0.1/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: eolib
+Version: 2.0.1
+Summary: Core library for writing applications related to Endless Online.
+Project-URL: Documentation, https://cirras.github.io/eolib-python
+Project-URL: Issues, https://github.com/Cirras/eolib-python/issues
+Project-URL: Source, https://github.com/Cirras/eolib-python
+Author-email: Jonah Jeleniewski <cirrasbu@hotmail.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Keywords: endless-online
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# EOLib
+
+[![PyPI - Version](https://img.shields.io/pypi/v/eolib.svg)](https://pypi.org/project/eolib)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/eolib.svg)](https://pypi.org/project/eolib)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=Cirras_eolib-python&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=Cirras_eolib-python)
+[![Lint](https://github.com/Cirras/eolib-python/actions/workflows/lint.yml/badge.svg?event=push)](https://github.com/Cirras/eolib-python/actions/workflows/lint.yml)
+
+A core Python library for writing applications related to Endless Online.
+
+## Installation
+
+```console
+pip install eolib
+```
+
+## Features
+
+Read and write the following EO data structures:
+
+- Client packets
+- Server packets
+- Endless Map Files (EMF)
+- Endless Item Files (EIF)
+- Endless NPC Files (ENF)
+- Endless Spell Files (ESF)
+- Endless Class Files (ECF)
+
+Utilities:
+
+- Data reader
+- Data writer
+- Number encoding
+- String encoding
+- Data encryption
+- Packet sequencer
+
+## Development
+
+### Requirements
+
+- [Python](https://www.python.org/downloads/) 3.8+
+- [Hatch](https://hatch.pypa.io/latest/install/)
+
+### Available Commands
+
+| Command                     | Description                                            |
+| --------------------------- | ------------------------------------------------------ |
+| `hatch build`               | Build package                                          |
+| `hatch clean`               | Remove build artifacts                                 |
+| `hatch run test`            | Run unit tests with coverage                           |
+| `hatch run lint:format`     | Format source files using `black`                      |
+| `hatch run lint:style`      | Check formatting using `black`                         |
+| `hatch run lint:typing`     | Check typing using `mypy`                              |
+| `hatch run lint:all`        | Check formatting using `black` and typing using `mypy` |
+| `hatch run docs:build`      | Build documentation using `mkdocs`                     |
+| `hatch run docs:serve`      | Build and serve documentation using `mkdocs`           |
+| `hatch run docs:deploy`     | Build and deploy documentation using `mkdocs` & `mike` |
+| `hatch run release:prepare` | Prepare and tag a new release                          |

eolib-2.0.1/eo-protocol/README.md

@@ -0,0 +1,51 @@
+# EO Protocol
+
+An XML-based specification of the Endless Online network protocol and data files.
+
+## Motivation
+
+Most of this information has been available for some time. It's been scattered through different projects, only partially documented, or living in the heads of various community members.
+
+The idea is to put all of that collective knowledge in one place.
+
+## Use cases
+
+- Documentation
+- Code generation
+
+## Projects
+
+Community projects based on this specification.
+
+### Libraries
+
+1. **[eolib-dotnet](https://github.com/ethanmoffat/eolib-dotnet)** ([@ethanmoffat](https://github.com/ethanmoffat))
+    * Core .NET library for writing Endless Online applications.
+2. **[eolib-go](https://github.com/ethanmoffat/eolib-go)** ([@ethanmoffat](https://github.com/ethanmoffat))
+    * Core Golang library for writing Endless Online applications.
+3. **[eolib-java](https://github.com/cirras/eolib-java)** ([@cirras](https://github.com/cirras))
+    * Core Java library for writing Endless Online applications.
+4. **[eolib-pas](https://github.com/cirras/eolib-pas)** ([@cirras](https://github.com/cirras))
+    * Core Pascal library for writing Endless Online applications.
+5. **[eolib-php](https://github.com/exilestudios/eolib-php)** ([@exilestudios](https://github.com/exilestudios))
+    * Core PHP library for writing Endless Online applications.
+6. **[eolib-python](https://github.com/cirras/eolib-python)** ([@cirras](https://github.com/cirras))
+    * Core Python library for writing Endless Online applications.
+7. **[eolib-rs](https://github.com/sorokya/eolib-rs)** ([@sorokya](https://github.com/sorokya))
+    * Core Rust library for writing Endless Online applications.
+8. **[eolib-ts](https://github.com/cirras/eolib-ts)** ([@cirras](https://github.com/cirras))
+    * Core Typescript library for writing Endless Online applications.
+
+### Documentation
+
+1. **[eo-protocol-web](https://eoserv.net/eo-protocol-web/)** ([@tehsausage](https://github.com/tehsausage))
+    * Generated protocol documentation site.
+
+## Acknowledgements
+
+- Julian Smythe
+  - The `eo_protocol.txt` and `pub_protocol.txt` documentation that this project is based on, which was [released](https://eoserv.net/forum/topic/23799) in 2017 on the EOSERV forums.
+  - The [EOSERV](https://github.com/eoserv/eoserv) project, which has been a valuable reference point.
+  - Answering questions that none of us even knew we had about the protocol and official packet reader.
+- Richard Leek
+  - Improvements and corrections to the aforementioned `eo_protocol.txt` and `pub_protocol.txt` documentation. (See [eo_protocol](https://github.com/sorokya/eo_protocol))

eolib-2.0.1/eo-protocol/docs/chunks.md

@@ -0,0 +1,289 @@
+# Chunked Reading
+
+## Background
+In the official EO client and server, packets and data files are typically just treated as ansi strings.
+The notable exception is the "chunked" reading mode, typically used for reading data that contains multiple variable-sized fields.
+
+### How it works
+- Chunked reading mode gets activated.
+  - For our example, we'll call this function `DataReader::StartChunking`.
+  - The data string is split on `0xFF` bytes, which are called `break` bytes in this context.
+- Chunks of data are requested sequentially, with the next string chunk being returned each time.
+  - For our example, we'll call this function `DataReader::GetChunk`.
+
+#### Example:
+``` cpp
+// This is an approximation of how the packet chunking looks in the official data reader.
+//
+// Let's read a FOO_BAR packet containing the following data:
+//   char reply_code
+//   break
+//   string name
+//   break
+//   int session_id
+//   short class_id
+void FooBar(DataReader* reader)
+{
+    // Read the reply_code directly from the packet data. This is how data is read in a standard case.
+    unsigned char reply_code = DecodeNumber(reader->data.SubString(1, 1));
+
+    // Activate chunked reading.
+    reader->StartChunking();
+
+    // Discard the first chunk containing the reply code.
+    reader->GetChunk();
+
+    // Get the entire second chunk for the name field.
+    AnsiString name = reader->GetChunk();
+
+    // Get the third chunk, containing 2 number fields.
+    AnsiString numbers = reader->GetChunk();
+
+    // Read number fields from the 3rd chunk.
+    unsigned int session_id = DecodeNumber(numbers.SubString(1, 4));
+    unsigned short class_id = DecodeNumber(numbers.SubString(5, 2));
+}
+```
+
+> **Notes:**
+> - Indexing of the C++ builder `AnsiString` type is 1-based.
+>   - See: [System.AnsiString](https://docwiki.embarcadero.com/Libraries/en/System.AnsiString)
+
+## Peculiarities
+There are 3 notable peculariarities in this chunked reading mode.
+
+### 1. Under-read
+In chunked reading mode, the official data reader splits the data string on `0xFF` bytes.
+- Typically, consumers of these chunks will read the **expected** data out of a chunk, then discard it and move on to the next chunk.
+- This means it's possible to insert **unexpected** data at the end of a chunk. The chunk will get discarded and the garbage data will be ignored.
+
+> **Implementation notes:**
+> - When a `<break>` is reached...
+>   - The deserializer should seek from the current position to the next `0xFF` byte and consume it, ignoring any data in between.
+
+#### Example:
+``` cpp
+// Expected data:
+//   char foo
+//   break
+//   short bar
+//
+// Actual data:
+//   char = 123
+//   string = "garbage"
+//   break
+//   short = 12345
+void GarbageData(DataReader* reader)
+{
+    // Activate chunked reading.
+    reader->StartChunking();
+
+    // The first chunk contains our expected char, and some unexpected garbage data too.
+    // This will return "|garbage", which is [0x7C, 0x67, 0x61, 0x72, 0x62, 0x61, 0x67, 0x65].
+    AnsiString foo_chunk = reader->GetChunk();
+
+    // [0x7C, 0xFE, 0xFE, 0xFE] decodes to 123.
+    unsigned char foo = DecodeNumber(foo_chunk.SubString(1, 1));
+
+    // The "garbage" string gets ignored, as we've moved on to the next chunk.
+    // This will return "Ê1", which is [0xCA, 0x31].
+    AnsiString bar_chunk = reader->GetChunk();
+
+    // [0xCA, 0x31, 0xFE, 0xFE] decodes to 12345.
+    unsigned short baz = DecodeNumber(bar_chunk.SubString(1, 2));
+}
+```
+
+### 2. Over-read
+The result of overreading past a chunk (or the end of the input data) is a truncated ansi string.
+- For a string field, this would just mean truncation.
+- For numeric fields, the missing bytes are effectively 0.
+
+> **Implementation notes:**
+> - If the end of input data is reached...
+>   - Missing bytes should be treated as `0x00` when reading unencoded numbers.
+>   - Missing bytes should be treated as `0xFE` when reading encoded numbers.
+>   - Strings should be truncated.
+> - When chunked reading is enabled...
+>   - `0xFF` bytes may not be consumed until an expected `<break>` is reached in the deserialization logic.
+>   - If `0xFF` is reached and hasn't been consumed yet, the end-of-input rules should be followed.
+
+#### Example:
+``` cpp
+// Expected data:
+//   int foo
+//   break
+//   short bar
+//
+// Actual data:
+//   break
+//   char = 123
+void TruncatedNumbers(DataReader* reader)
+{
+    // Activate chunked reading.
+    reader->StartChunking();
+
+    // This will return an empty string.
+    AnsiString foo_chunk = reader->GetChunk();
+
+    // This is equivalent to decoding [0xFE, 0xFE, 0xFE, 0xFE], so the result is 0.
+    unsigned int foo = DecodeNumber(foo_chunk.SubString(1, 4));
+
+    // This will return "|", which is [0x7C].
+    AnsiString bar_chunk = reader->GetChunk();
+
+    // This is equivalent to decoding [0x7C, 0xFE, 0xFE, 0xFE], so the result is 123.
+    unsigned short bar = DecodeNumber(bar_chunk.SubString(1, 2));
+}
+```
+
+### 3. Double-read
+As shown with `reply_code` in the `FooBar` example, the official software sometimes mixes "standard" reading with chunked reading.
+
+The way this usually looks is:
+- Some fields are read directly from the data string.
+- Chunked reading is activated.
+- The first chunk is discarded.
+- The rest of the chunks are read via chunked reading.
+
+This can cause surprising and unexpected behavior in the official data reader.
+
+> **Implementation notes:**
+> - When the first `<chunked>` section is reached...
+>   - If the first expected element is a `<break>`, the deserializer should seek to the first `0xFF` byte in the input data before consuming it.
+
+#### Example:
+``` cpp
+// Expected data:
+//   int foo
+//   break
+//   char bar
+//   short baz
+//
+// Actual data:
+//   break
+//   char = 123
+//   short = 12345
+void DoubleRead(DataReader* reader)
+{
+    // Because the foo int was not sent in the actual data, we're unexpectedly reading into the second chunk.
+    // The following break byte, char field, and short field are read as if they were one int.
+    // This ends up being [0xFF, 0x7C, 0xCA, 0x31], which decodes to 790222478.
+    int foo = DecodeNumber(foo_chunk.SubString(1, 4));
+
+    // Activate chunked reading.
+    reader->StartChunking();
+
+    // Discard the first chunk.
+    // Intended to discard the foo int, but really just discards an empty chunk.
+    reader->GetChunk();
+
+    // This will return "|Ê1", which is [0x7C, 0xCA, 0x31].
+    AnsiString numbers = reader->GetChunk();
+
+    // [0x7C, 0xFE, 0xFE, 0xFE] decodes to 123.
+    unsigned char bar = DecodeNumber(bar_chunk.SubString(1, 1));
+
+    // [0xCA, 0x31, 0xFE, 0xFE] decodes to 12345.
+    unsigned short baz = DecodeNumber(bar_chunk.SubString(2, 2));
+}
+```
+
+## A practical example
+
+The official client and server *rely* on the aforementioned peculiarities for correct behavior.
+
+A prominent example (and good litmus test for a correct double-read implementation) is the
+`PLAYERS_AGREE` packet.
+
+### The client expects...
+```
+char characters_count
+break
+array of CharacterMapInfo[characters_count] (delimited by break)
+break
+array of NpcMapInfo
+break
+array of ItemMapInfo
+```
+
+### But the server sends...
+```
+break
+struct CharacterMapInfo
+break
+char 1
+```
+
+### How does this work?
+You might be scratching your head at this point, wondering how this could possibly work.
+
+Let's pull back the curtain on how a `PLAYERS_AGREE` packet is actually read by the client.
+```cpp
+void PlayersAgree(DataReader* reader)
+{
+    // Read the characters_count directly from the packet data.
+    // This reads the break byte (!) and the `0xFF` byte is interpreted by the number decoder as 254.
+    unsigned char characters_count = DecodeNumber(reader->data.SubString(1, 1));
+
+    // Activate chunked reading.
+    reader->StartChunking();
+
+    // Discard the first chunk.
+    // Intended to discard the characters_count char, but really just discards an empty chunk.
+    reader->GetChunk();
+
+    // Read characters_count number of chunks as CharacterMapInfo records.
+    for (unsigned char i = 0; i < characters_count; ++i)
+    {
+        AnsiString chunk = reader->GetChunk();
+        if (chunk.Length() < 42)
+        {
+            // Any chunks under 42 bytes in length are discarded here.
+            // The first CharacterMapInfo record is read correctly.
+            // The second chunk is a single "char 1" value, so it's discarded.
+            // The remaining 252 chunks are empty, so they're also discarded.
+            continue;
+        }
+        ReadCharacterMapInfo(chunk);
+    }
+
+    // Read the next chunk as a non-delimited array of NpcMapInfo.
+    // There is no remaining data, so this chunk is empty and npcs_count = 0.
+    AnsiString npcs = reader->GetChunk();
+    int npcs_count = npcs.Length() / NpcMapInfo::ByteSize();
+
+    for (int i = 0; i < npcs_count; ++i)
+    {
+        int npc_pos = 1 + (i * NpcMapInfo::ByteSize());
+        AnsiString npc = chunk.SubString(npc_pos, NpcMapInfo::ByteSize());
+        ReadNpcMapInfo(npc);
+    }
+
+    // Read the next chunk as a non-delimited array of ItemMapInfo.
+    // There is no remaining data, so this chunk is empty and items_count = 0.
+    AnsiString items = reader->GetChunk();
+    int items_count = items.Length() / ItemMapInfo::ByteSize();
+
+    for (int i = 0; i < items_count; ++i)
+    {
+        int item_pos = 1 + (i * ItemMapInfo::ByteSize());
+        AnsiString item = chunk.SubString(item_pos, ItemMapInfo::ByteSize());
+        ReadItemMapInfo(item);
+    }
+}
+```
+
+The client ends up with the single intended `CharacterMapInfo` update, and everything _accidentally_ works out fine!
+
+## Sanitization
+Some packets treat `0xFF` bytes as data, while others treat them as meaningful `break` bytes for data chunking.
+
+A problematic scenario presents itself:
+- A client sends a string containing `0xFF` (the ÿ character) in a packet where `0xFF` bytes are treated as data.
+- The server sends that string back out to clients in a packet where `0xFF` bytes are treated as `break` bytes.
+- The clients receiving those packets are unable to read them correctly due to the unexpected `break` bytes.
+
+> **Implementation notes:**
+> - The serializer should sanitize `0xFF` bytes in strings when within a `<chunked>` section.
+> - Since `0xFF` maps to character **ÿ** in ansi codepage 1252, it can simply be swapped to **y** (`0x79`).