feat(specification): enhance Content Format V3 with improved field efficiency and support for image content in V4

Author: PromiseFru

docs/specification.md

@@ -194,70 +194,53 @@
 
 > [!NOTE]
 >
-> This format uses a bitmap to indicate which fields are present, making it more efficient than previous versions.
+> This format improves efficiency by only including length fields for applicable fields per service type, rather than including all fields with zero lengths.
 >
 > **All 2-byte length fields are encoded as unsigned little-endian.**
 
-#### Field Bitmap Definition
-
-The bitmap is a single byte where each bit represents the presence of a specific field:
-
-- **Bit 0 (0x01)**: `from` field
-- **Bit 1 (0x02)**: `to` field
-- **Bit 2 (0x04)**: `cc` field
-- **Bit 3 (0x08)**: `bcc` field
-- **Bit 4 (0x10)**: `subject` field
-- **Bit 5 (0x20)**: `body` field
-- **Bit 6 (0x40)**: `access_token` field
-- **Bit 7 (0x80)**: `refresh_token` field
-
 1. **Email format**: Binary-encoded fields with the following structure:
 
-   - **1 byte**: Field presence bitmap
-   - **1 byte**: Length of `from` field (if bit 0 is set)
-   - **2 bytes**: Length of `to` field (if bit 1 is set)
-   - **2 bytes**: Length of `cc` field (if bit 2 is set)
-   - **2 bytes**: Length of `bcc` field (if bit 3 is set)
-   - **1 byte**: Length of `subject` field (if bit 4 is set)
-   - **2 bytes**: Length of `body` field (if bit 5 is set)
-   - **2 bytes**: Length of `access_token` field (if bit 6 is set)
-   - **2 bytes**: Length of `refresh_token` field (if bit 7 is set)
-   - **Variable**: Value of `from` field (if present)
-   - **Variable**: Value of `to` field (if present)
-   - **Variable**: Value of `cc` field (if present)
-   - **Variable**: Value of `bcc` field (if present)
-   - **Variable**: Value of `subject` field (if present)
-   - **Variable**: Value of `body` field (if present)
-   - **Variable**: Value of `access_token` field (if present)
-   - **Variable**: Value of `refresh_token` field (if present)
+   - **1 byte**: Length of `from` field.
+   - **2 bytes**: Length of `to` field.
+   - **2 bytes**: Length of `cc` field.
+   - **2 bytes**: Length of `bcc` field.
+   - **1 byte**: Length of `subject` field.
+   - **2 bytes**: Length of `body` field.
+   - **2 bytes**: Length of `access_token` field (optional).
+   - **2 bytes**: Length of `refresh_token` field (optional).
+   - **Variable**: Value of `from` field.
+   - **Variable**: Value of `to` field.
+   - **Variable**: Value of `cc` field.
+   - **Variable**: Value of `bcc` field.
+   - **Variable**: Value of `subject` field.
+   - **Variable**: Value of `body` field.
+   - **Variable**: Value of `access_token` field (if present).
+   - **Variable**: Value of `refresh_token` field (if present).
 
 2. **Text format**: Binary-encoded fields with the following structure:
 
-   - **1 byte**: Field presence bitmap
-   - **1 byte**: Length of `from` field (if bit 0 is set)
-   - **2 bytes**: Length of `body` field (if bit 5 is set)
-   - **2 bytes**: Length of `access_token` field (if bit 6 is set)
-   - **2 bytes**: Length of `refresh_token` field (if bit 7 is set)
-   - **Variable**: Value of `from` field (if present)
-   - **Variable**: Value of `body` field (if present)
-   - **Variable**: Value of `access_token` field (if present)
-   - **Variable**: Value of `refresh_token` field (if present)
+   - **1 byte**: Length of `from` field.
+   - **2 bytes**: Length of `body` field.
+   - **2 bytes**: Length of `access_token` field (optional).
+   - **2 bytes**: Length of `refresh_token` field (optional).
+   - **Variable**: Value of `from` field.
+   - **Variable**: Value of `body` field.
+   - **Variable**: Value of `access_token` field (if present).
+   - **Variable**: Value of `refresh_token` field (if present).
 
 3. **Message format**: Binary-encoded fields with the following structure:
 
-   - **1 byte**: Field presence bitmap
-   - **1 byte**: Length of `from` field (if bit 0 is set)
-   - **2 bytes**: Length of `to` field (if bit 1 is set)
-   - **2 bytes**: Length of `body` field (if bit 5 is set)
-   - **Variable**: Value of `from` field (if present)
-   - **Variable**: Value of `to` field (if present)
-   - **Variable**: Value of `body` field (if present)
+   - **1 byte**: Length of `from` field.
+   - **2 bytes**: Length of `to` field.
+   - **2 bytes**: Length of `body` field.
+   - **Variable**: Value of `from` field.
+   - **Variable**: Value of `to` field.
+   - **Variable**: Value of `body` field.
 
 4. **Test format**: Binary-encoded fields with the following structure:
 
-   - **1 byte**: Field presence bitmap
-   - **1 byte**: Length of `from` field (if bit 0 is set)
-   - **Variable**: Value of `from` field (considered the test ID, if present)
+   - **1 byte**: Length of `from` field.
+   - **Variable**: Value of `from` field (considered the test ID).
 
 ### Content Format V4
 
@@ -267,89 +250,81 @@ The bitmap is a single byte where each bit represents the presence of a specific
 
 > [!NOTE]
 >
-> This format extends V3 by using a 2-byte bitmap instead of 1-byte, with bits 8 and 9 representing content types.
+> This format extends V3 by adding support for image content. A content type indicator determines which content types are present.
 >
 > **All 2-byte length fields are encoded as unsigned little-endian.**
 
-#### Field Bitmap Definition (2 bytes)
-
-The bitmap is 2 bytes where each bit represents the presence of a specific field:
+#### Content Type Indicator
 
-**First byte (bits 0-7) - Standard fields:**
+The content type indicator is a single byte where each bit represents the presence of a specific content type:
 
-- **Bit 0 (0x01)**: `from` field
-- **Bit 1 (0x02)**: `to` field
-- **Bit 2 (0x04)**: `cc` field
-- **Bit 3 (0x08)**: `bcc` field
-- **Bit 4 (0x10)**: `subject` field
-- **Bit 5 (0x20)**: `body` field
-- **Bit 6 (0x40)**: `access_token` field
-- **Bit 7 (0x80)**: `refresh_token` field
+- **Bit 0 (0x01)**: Text content present
+- **Bit 1 (0x02)**: Image content present
 
-**Second byte (bits 8-15) - Content type:**
+Possible combinations:
 
-- **Bit 8 (0x0100)**: Text content present
-- **Bit 9 (0x0200)**: Image content present
+- **0x01**: Text-only content
+- **0x02**: Image-only content
+- **0x03**: Text and image content
 
 1. **Email format**: Binary-encoded fields with the following structure:
 
-   - **2 bytes**: Field and content type bitmap
-   - **1 byte**: Length of `from` field (if bit 0 is set and bit 8 is set)
-   - **2 bytes**: Length of `to` field (if bit 1 is set and bit 8 is set)
-   - **2 bytes**: Length of `cc` field (if bit 2 is set and bit 8 is set)
-   - **2 bytes**: Length of `bcc` field (if bit 3 is set and bit 8 is set)
-   - **1 byte**: Length of `subject` field (if bit 4 is set and bit 8 is set)
-   - **2 bytes**: Length of `body` field (if bit 5 is set and bit 8 is set)
-   - **2 bytes**: Length of `access_token` field (if bit 6 is set and bit 8 is set)
-   - **2 bytes**: Length of `refresh_token` field (if bit 7 is set and bit 8 is set)
-   - **2 bytes**: `Image Session ID` (if bit 9 is set)
-   - **1 byte**: `Image Segment info` (if bit 9 is set)
-   - **2 bytes**: Length of `Image` (if bit 9 is set)
-   - **Variable**: Value of `from` field (if present)
-   - **Variable**: Value of `to` field (if present)
-   - **Variable**: Value of `cc` field (if present)
-   - **Variable**: Value of `bcc` field (if present)
-   - **Variable**: Value of `subject` field (if present)
-   - **Variable**: Value of `body` field (if present)
-   - **Variable**: Value of `access_token` field (if present)
-   - **Variable**: Value of `refresh_token` field (if present)
-   - **Variable**: Value of `Image` (if present)
+   - **1 byte**: Content type indicator
+   - **1 byte**: Length of `from` field (if text content present).
+   - **2 bytes**: Length of `to` field (if text content present).
+   - **2 bytes**: Length of `cc` field (if text content present).
+   - **2 bytes**: Length of `bcc` field (if text content present).
+   - **1 byte**: Length of `subject` field (if text content present).
+   - **2 bytes**: Length of `body` field (if text content present).
+   - **2 bytes**: Length of `access_token` field (if text content present and optional).
+   - **2 bytes**: Length of `refresh_token` field (if text content present and optional).
+   - **2 bytes**: `Image Session ID` (if image content present).
+   - **1 byte**: `Image Segment info` (if image content present).
+   - **2 bytes**: Length of `Image` (if image content present).
+   - **Variable**: Value of `from` field (if text content present).
+   - **Variable**: Value of `to` field (if text content present).
+   - **Variable**: Value of `cc` field (if text content present).
+   - **Variable**: Value of `bcc` field (if text content present).
+   - **Variable**: Value of `subject` field (if text content present).
+   - **Variable**: Value of `body` field (if text content present).
+   - **Variable**: Value of `access_token` field (if text content present and token provided).
+   - **Variable**: Value of `refresh_token` field (if text content present and token provided).
+   - **Variable**: Value of `Image` (if image content present).
 
 2. **Text format**: Binary-encoded fields with the following structure:
 
-   - **2 bytes**: Field and content type bitmap
-   - **1 byte**: Length of `from` field (if bit 0 is set and bit 8 is set)
-   - **2 bytes**: Length of `body` field (if bit 5 is set and bit 8 is set)
-   - **2 bytes**: Length of `access_token` field (if bit 6 is set and bit 8 is set)
-   - **2 bytes**: Length of `refresh_token` field (if bit 7 is set and bit 8 is set)
-   - **2 bytes**: `Image Session ID` (if bit 9 is set)
-   - **1 byte**: `Image Segment info` (if bit 9 is set)
-   - **2 bytes**: Length of `Image` (if bit 9 is set)
-   - **Variable**: Value of `from` field (if present)
-   - **Variable**: Value of `body` field (if present)
-   - **Variable**: Value of `access_token` field (if present)
-   - **Variable**: Value of `refresh_token` field (if present)
-   - **Variable**: Value of `Image` (if present)
+   - **1 byte**: Content type indicator
+   - **1 byte**: Length of `from` field (if text content present).
+   - **2 bytes**: Length of `body` field (if text content present).
+   - **2 bytes**: Length of `access_token` field (if text content present and optional).
+   - **2 bytes**: Length of `refresh_token` field (if text content present and optional).
+   - **2 bytes**: `Image Session ID` (if image content present).
+   - **1 byte**: `Image Segment info` (if image content present).
+   - **2 bytes**: Length of `Image` (if image content present).
+   - **Variable**: Value of `from` field (if text content present).
+   - **Variable**: Value of `body` field (if text content present).
+   - **Variable**: Value of `access_token` field (if text content present and token provided).
+   - **Variable**: Value of `refresh_token` field (if text content present and token provided).
+   - **Variable**: Value of `Image` (if image content present).
 
 3. **Message format**: Binary-encoded fields with the following structure:
 
-   - **2 bytes**: Field and content type bitmap
-   - **1 byte**: Length of `from` field (if bit 0 is set and bit 8 is set)
-   - **2 bytes**: Length of `to` field (if bit 1 is set and bit 8 is set)
-   - **2 bytes**: Length of `body` field (if bit 5 is set and bit 8 is set)
-   - **2 bytes**: `Image Session ID` (if bit 9 is set)
-   - **1 byte**: `Image Segment info` (if bit 9 is set)
-   - **2 bytes**: Length of `Image` (if bit 9 is set)
-   - **Variable**: Value of `from` field (if present)
-   - **Variable**: Value of `to` field (if present)
-   - **Variable**: Value of `body` field (if present)
-   - **Variable**: Value of `Image` (if present)
+   - **1 byte**: Content type indicator
+   - **1 byte**: Length of `from` field (if text content present).
+   - **2 bytes**: Length of `to` field (if text content present).
+   - **2 bytes**: Length of `body` field (if text content present).
+   - **2 bytes**: `Image Session ID` (if image content present).
+   - **1 byte**: `Image Segment info` (if image content present).
+   - **2 bytes**: Length of `Image` (if image content present).
+   - **Variable**: Value of `from` field (if text content present).
+   - **Variable**: Value of `to` field (if text content present).
+   - **Variable**: Value of `body` field (if text content present).
+   - **Variable**: Value of `Image` (if image content present).
 
 4. **Test format**: Binary-encoded fields with the following structure:
 
-   - **2 bytes**: Field and content type bitmap
-   - **1 byte**: Length of `from` field (if bit 0 is set)
-   - **Variable**: Value of `from` field (considered the test ID, if present)
+   - **1 byte**: Length of `from` field (if text content present).
+   - **Variable**: Value of `from` field (considered the test ID, if text content present).
 
 ## Supported Payload Versions
 
@@ -359,7 +334,7 @@ The bitmap is 2 bytes where each bit represents the presence of a specific field
 | [v1](#payload-format-v1) | `0x01`                | `1`               | Introduces version marker, 2-byte ciphertext length, explicit device ID length field, and language code support. Uses Content Format V1 with 1-byte token length fields. |
 | [v2](#payload-format-v2) | `0x02`                | `2`               | Same payload structure as V1 but uses Content Format V2 with 2-byte token length fields for better support of longer access/refresh tokens.                              |
 | [v3](#payload-format-v3) | `0x03`                | `3`               | Same payload structure as V1/V2 but uses Content Format V3 with bitmap-based field presence indication for more efficient encoding.                                      |
-| [v4](#payload-format-v4) | `0x04`                | `4`               | Same payload structure as V1/V2/V3 but uses Content Format V4 with 2-byte bitmap supporting image content.                                                               |
+| [v4](#payload-format-v4) | `0x04`                | `4`               | Same payload structure as V1/V2/V3 but uses Content Format V4 with support for image content.                                                                            |
 
 ## Payload Format V0