// ❌ 直觉写法
var head = new byte[3];
int n = source.Read(head, 0, 3);        // 以为 n == 3
if (head 是 BOM) { /* 跳过 3 字节 */ }

private static int ReadFull(Stream source, byte[] buffer, int count)
{
    var total = 0;
    while (total < count)
    {
        var n = source.Read(buffer, total, count - total);
        if (n <= 0) break;
        total += n;
    }
    return total;
}

// 调用处：读满 3 字节再判断
var head = new byte[3];
var headLen = ReadFull(source, head, head.Length);
var offset = (headLen == 3 && head[0] == 0xEF && head[1] == 0xBB && head[2] == 0xBF) ? 3 : 0;
Feed(head.AsSpan(offset, headLen - offset));

/// 按 Kotlin BufferedReader.readLine 的规则切行，并给出每行的字节区间。
///
/// 这里刻意不借助 C# 的 StreamReader：它会在某些设置下把 BOM 吃掉，
/// 而 Android 上的 InputStreamReader 不会 —— BOM 会以 U+FEFF 出现在首行，
/// 这正是 UTS 实现所依赖的行为。

void Feed(ReadOnlySpan<byte> span)
{
    foreach (var b in span)
    {
        if (pendingCr)
        {
            pendingCr = false;
            sink.Push(0x0A);            // 上一个 CR 补一个 LF
            if (b == 0x0A) continue;    // CRLF：当前字节已被消费
        }
        if (b == 0x0D) { pendingCr = true; continue; }
        sink.Push(b);
    }
}

private void FlushEmit()
{
    if (_emitLen == 0) return;
    _hasher.AppendData(_emit, 0, _emitLen);
    CharCount += _decoder.GetChars(_emit.AsSpan(0, _emitLen), _chars, false);
    _emitLen = 0;
}

function utf8ByteLen(s : string) : number {
    let n = 0
    let i = 0
    const len = s.length
    while (i < len) {
        const c = s.charCodeAt(i)!
        if (c < 0x80) {
            n = n + 1
        } else if (c < 0x800) {
            n = n + 2
        } else if (c >= 0xD800 && c <= 0xDBFF && i + 1 < len) {
            const c2 = s.charCodeAt(i + 1)!
            if (c2 >= 0xDC00 && c2 <= 0xDFFF) {
                // 代理对：一个字符占 4 字节
                n = n + 4
                i = i + 1              // 两个 char 一起消费
            } else {
                n = n + 3
            }
        } else {
            n = n + 3
        }
        i = i + 1
    }
    return n
}

export function scanChapterMarks(path : string, ...) : ChapterScanResult {
    // ...
    let charPos = 0
    let bytePos = 0
    let first = true
    const reader = new BufferedReader(new InputStreamReader(input, Charset.forName(enc)), 65536)
    let line = reader.readLine()
    while (line != null) {
        let s = line
        if (first) {
            if (s.length > 0 && s.charCodeAt(0) == 0xFEFF) {
                s = s.substring(1)
                // BOM 占 3 个字节，但不计字符
                bytePos = bytePos + 3
            }
            first = false
        }
        const lineCharStart = charPos
        const lineByteStart = bytePos
        const contentBytes = utf8ByteLen(s)
        // 字符下标按「含换行」的口径累加（每行 +1 表示那个 \n），
        // 这样得到的下标与「把整本读成字符串后逐字符数」完全一致 ——
        // 否则章节 start/end 会和旧版本记录对不上，进度百分比也会整体偏移。
        charPos = charPos + s.length + 1
        bytePos = bytePos + contentBytes + 1
        // ... 记录候选标题行、兜底分块 ...
        line = reader.readLine()
    }
    // 累加值应满足：末行有换行 → 等于文件大小；末行无换行 → 多算 1。
    // 其余情况说明行尾不是纯 \n（CRLF 会让每行少算 1 字节、一路偏小），索引不可信。
    const ok = bytePos == fileSize || bytePos == fileSize + 1
    // ...
}

/**
 * 读取文件中 [startByte, endByte) 这一段字节所对应的文本。
 *
 * 起止都是「行首字节偏移」（由 scanChapterMarks 给出），天然落在字符边界上，
 * 因此不用处理「UTF-8 续字节被切断」的问题。
 * 文件是 UTF-8 + LF，按 readLine 逐行读、行间补 \n，即可原样还原这一段。
 */
export function readByteRange(path : string, startByte : number, endByte : number) : string {