first commit

docs/media/fonts/font-compress/src/utils/encode-string.md

@@ -0,0 +1,60 @@
+# encode-string
+
+## Purpose
+
+Utilities for encoding and decoding length-prefixed UTF-8 strings in the BTF binary format. They provide the wire encoding used by `BinaryFontPacker` to store font family name, CSS weight, and CSS style as inline strings in the binary header.
+
+Every string is encoded as `[uint32 byte-length LE][UTF-8 bytes]`, which allows safe decoding without a sentinel character and handles arbitrary Unicode content including multi-byte sequences.
+
+## Features
+
+- `encodeString`: encodes a JS string as `[uint32 LE length][UTF-8 bytes]`
+- `decodeString`: reads a length-prefixed string from a buffer at a given byte offset and returns the decoded value and the new offset after the string
+
+## Usage: Basic Example
+
+```typescript
+import { encodeString, decodeString } from "@suaveplan/font-compress/utils/encode-string";
+
+const encoded = encodeString("Arial");
+// [5, 0, 0, 0, 65, 114, 105, 97, 108]
+
+const { value, offset } = decodeString(encoded, 0);
+// value = "Arial", offset = 9
+```
+
+## Usage: Advanced Example
+
+```typescript
+// Chaining multiple string reads during unpack
+let off = 0;
+const r1 = decodeString(data, off); off = r1.offset;
+const r2 = decodeString(data, off); off = r2.offset;
+const r3 = decodeString(data, off); off = r3.offset;
+// r1.value = familyName, r2.value = cssFontWeight, r3.value = cssFontStyle
+```
+
+## API Reference
+
+### `encodeString(str: string): Uint8Array`
+
+Encodes `str` as `[uint32 LE byte-length][UTF-8 bytes]`.
+
+**Parameters:** `str` — any JS string including multi-byte Unicode.
+
+**Returns:** `Uint8Array` of `4 + byteLength` bytes.
+
+### `decodeString(data: Uint8Array, offset: number): { value: string; offset: number }`
+
+Reads a length-prefixed string at `offset` in `data`.
+
+**Parameters:**
+
+- `data` — source buffer
+- `offset` — byte position of the uint32 length prefix
+
+**Returns:** `{ value: string; offset: number }` where `offset` is the position immediately after the string bytes.
+
+## Implementation Notes
+
+Uses the platform `TextEncoder` / `TextDecoder` singletons. The returned `offset` from `decodeString` is the cursor position immediately following the string's last byte, suitable for passing directly to the next read operation.