"""
Accordance 8-bit apparatus encoding → Unicode.

The MT-ETCBC-A apparatus binary uses two font-specific 8-bit encodings:
  - **Helena font**: 8-bit Greek characters with precomposed diacritics
  - **Yehudit font**: 8-bit Hebrew consonants and vowel points

ASCII bytes (0x00–0x7F) serve double duty:
  - Apparatus notation abbreviations (Latin: "cp", "cf", "frt", etc.)
  - Hebrew consonant Beta Code (e.g. b=bet, r=resh, a=aleph, s=shin)

8-bit bytes (0x80–0xFF) are precomposed characters or vowel points.
Vowel points modify the nearest Hebrew consonant in context.

The mixed encoding requires a post-decoding pass to convert ASCII Beta
Code Hebrew letters to Unicode Hebrew when adjacent to Hebrew characters.

Mapping sources:
  - Greek diacritics: deduced from apparatus context (e.g. kai + 0xC7 = καὶς)
  - Hebrew consonants: deduced from known words (e.g. bereshit = בראשית)
  - Formatting bytes: identified from binary structure
  - Apparatus sigla: identified from repeated context clues
"""

# ── Greek diacritic characters (Helena font) ──────────────────────────
# Frida-verified via CTLine runtime capture where noted.  The Helena.otf
# font renders these MacRoman codepoints as pre-composed Greek diacritics.
GREEK_DIACRITIC_MAP: dict[int, str] = {
    # ── Frida-verified (CTLine ground truth) ──
    0xA2: "\u03cd",  # ύ  upsilon-tonos     (Frida: ¢ U+00A2, from u¢dwr = ὕδωρ)
    0xA7: "\u03c2",  # ς  final sigma        (Frida: ß U+00DF, frequent)
    0xC0: "\u1f70",  # ὰ  alpha-varia        (Frida: ¿ U+00BF)
    0xC7: "\u03ac",  # ά  alpha-tonos        (Frida: « U+00AB, from kai« = καὶ)
    0xC8: "\u1f72",  # ὲ  epsilon-varia      (Frida: » U+00BB)
    0xD6: "\u03ad",  # έ  epsilon-tonos      (Frida: ÷ U+00F7, from e˙ge÷neto = ἐγένετο)
    0xE0: "\u03ce",  # ώ  omega-tonos        (Frida: ‡ U+2021, from w‡fqh = ὤφθη)
    0xE4: "\u03af",  # ί  iota-tonos         (Frida: ‰ U+2030, single occurrence)
    0xFA: "\u03ae",  # ή  eta-tonos          (Frida: ˙ U+02D9, from ei˙ß = εἷς)
    # ── Previously deduced (not yet Frida-verified) ──
    0xC3: "\u1f70",  # ὰ  alpha with varia
    0xC9: "\u03cc",  # ό  omicron tonos (variant)
    0xCE: "\u03ae",  # ή  eta tonos (variant)
    0xEE: "\u1f00",  # ἀ  alpha smooth breathing
    0xEF: "\u1f40",  # ὀ  omicron smooth breathing (variant)
    0xF0: "\u1f50",  # ὐ  upsilon smooth breathing
    # Note: 0xA7 (§) is handled specially by encoding.py as final-sigma
    # in Greek context — not included here to avoid double-mapping.
    0xA5: "\u03cc",  # ό  omicron with tonos
    0xA6: "\u1f14",  # ἔ  epsilon smooth+acute (from eiA5nai context)
    0xE1: "\u1f71",  # ά  alternate alpha tonos — may be breathing variant
    # ── Frida-verified formatting markers ──
    0xA1: "\u00b0",  # °  degree/apparatus marker (Frida: °, 2535× in MT, 9418× NA28)
}

# ── Hebrew consonant and vowel point mapping (Yehudit font) ────────────
# Frida-verified via CTLine runtime capture (Session 91).  Each byte
# is decoded by Accordance via MacRoman to the shown character, then
# Yehudit.otf renders it as the listed Hebrew Unicode glyph.
HEBREW_MAP: dict[int, str] = {
    # ── Frida-verified (CTLine ground truth) ──
    0xB4: "\u05b4",  # ִ  chirik    (Frida: ¥ U+00A5)
    0xCF: "\u05b0",  # ְ  sheva     (Frida: œ U+0153)
    0xD7: "\u05b0",  # ְ  sheva     (Accordance: Gen 1:30 וְאת; Frida: ◊ U+25CA)
    0xE3: "\u05d0",  # א  aleph     (Frida: „ U+201E)
    0xEA: "\u05d0",  # א  aleph     (Frida: Í U+00CD)
    0xEB: "\u05b8",  # ָ  qamats    (Accordance: Gen 1:30 נָתַתִּי; Frida: Î U+00CE)
    0xED: "\u05b5",  # ֵ  tsere     (Frida: Ì U+00CC)
    0xF2: "\u05bc",  # ּ  dagesh    (Frida: Ú U+00DA)
    # ── Frida-verified vowel points (previously unmapped) ──
    0x81: "\u05b7",  # ַ  patach    (Frida: Å U+00C5, 17 occurrences)
    0xB6: "\u05b8",  # ָ  qamats    (Frida: ∂ U+2202)
    0xBD: "\u05da",  # ך  final kaf (Frida: Ω U+03A9, single occurrence)
    0xC3: "\u05b0",  # ְ  sheva variant (Frida: √ U+221A)
    # ── Probable (not yet Frida-verified, from earlier analysis) ──
    0xF1: "\u05d5",  # ו  vav
    0xF3: "\u05d7",  # ח  chet
    0xF4: "\u05d8",  # ט  tet
    0xE5: "\u05d9",  # י  yod
    0xE6: "\u05dc",  # ל  lamed
    0xF5: "\u05de",  # מ  mem
    0xE7: "\u05e0",  # נ  nun
    0xF7: "\u05e2",  # ע  ayin
    0xEE: "\u05e7",  # ק  qof
    0xF0: "\u05e9",  # ש  shin
    0xF6: "\u05ea",  # ת  tav
    # ── Final (sofit) forms ──
    0xBF: "\u05dd",  # ם  final mem
    0xAF: "\u05df",  # ן  final nun
    0xAE: "\u05e3",  # ף  final pe
    0xBC: "\u05e5",  # ץ  final tsadi
}

# ── Apparatus sigla marks ─────────────────────────────────────────────
APPARATUS_SIGLA_MAP: dict[int, str] = {
    # ── LXX/Septuagint cross-reference marker ──
    0xFD: "\U0001d50a",  # 𝔊  LXX/Septuagint Fraktur G
    0xE3: "\u214f",  # ⅏  SYMBOL FOR SAMARITAN SOURCE (Gen 2:2 note-start)
    0xEA: "\U0001d516",  # 𝔖  MATHEMATICAL FRAKTUR CAPITAL S (Gen 2:2 note-start)
    # ── Other apparatus sigla ──
    0xB7: "\u00b7",  # ·  middle dot (syllable/word separator) — Frida shows MacRoman
    # ∑ (U+2211 N-ARY SUMMATION), but Accordance's Latin-1
    # interpretation is the middle dot; lexicon_module.py:585
    # describes it as "middle dot (syllable separator)".
    0xFF: "\u25cb",  # ○  circle/siglum marker — Frida shows MacRoman ˇ (U+02C7
    # CARON), but Accordance renders this as a circle siglum;
    # appears at end of apparatus section markers („ˇˇ → ⅏○○).
    0x82: "\u03c2",  # ς  (sometimes used as siglum)
    0xD0: "\u2013",  # –  en dash (apparatus reference separator)
    0xD1: "\u2014",  # —  em dash
    # 0x81 is patach ַ (\u05B7) — mapped in HEBREW_MAP; removed from here
    # to avoid None-override of the valid Hebrew vowel-point mapping.
    # ── Punctuation / Separators ──
    0x94: " ",  # formatting artifact → space
    0x8C: "\u2135",  # ℵ  aleph siglum (Codex Sinaiticus) — from Vector B
    0xB4: "\u05b4",  # ִ  chirik vowel point (Hebrew context)
    0xB6: "\u05b8",  # ָ  qamats vowel point
    0x8A: "\u05b7",  # ַ  patach vowel point
    0x8E: "\u05b6",  # ֶ  segol vowel point
    # ── Additional formatting ──
    0x9F: " ",  # formatting → space
    # NOTE: 0xA8 (MacRoman ® / Latin-1 ¨) is intentionally NOT mapped.
    # It is an Accordance transliteration/formatting marker
    # (cf. encoding.py _HEBREW_POINTS: "formatting") that appears
    # between Hebrew consonants in apparatus (e.g. Er®a).
    # No clear Unicode sigla meaning; leaving unmapped for now.
    # Including it as None would violate the dict[int, str] type
    # and produce a runtime None on lookup — callers handle unmapped
    # bytes via COMBINED_MAP.get(b) fallback.
}

# ── Bytes that are formatting / non-text ──────────────────────────────
FORMATTING_BYTES: set[int] = {
    0xCA,  # padding byte (appears as 5× before note variant letters)
    0x0D,  # carriage return (\r) — paragraph/verse separator
    0x09,  # tab — field separator in some sections
    0x00,  # null byte
    0x7C,  # pipe | — entry delimiter (some entries end with it)
}


# ── Combined decode map builder ────────────────────────────────────────
def _build_decode_map(*, include_hebrew: bool = False) -> dict[int, str]:
    """Build a combined 8-bit → Unicode decode map.

    Priority order (first write wins — later ``.update()`` / writes
    override, so "higher" layers appear first in the build order):

    **include_hebrew=True** (MT-ETCBC-A apparatus):
      1. Hebrew consonants/vowels (HEBREW_MAP)
      2. Apparatus sigla (APPARATUS_SIGLA_MAP) — overrides Hebrew
      3. Greek diacritics — fill gaps only

      Known byte collisions resolved by Hebrew-first priority:
      - 0xCF: Hebrew sheva (U+05B0) vs Greek (U+1FF6)
      - 0xEE: Hebrew qof (U+05E7) vs Greek alpha-smooth (U+1F00)
      - 0xF0: Hebrew shin (U+05E9) vs Greek upsilon-smooth (U+1F50)
      - 0xF6: Hebrew tav (U+05EA) vs Greek iota-tonos (U+03AF)
      Apparatus context determines meaning — Hebrew wins for MT-ETCBC-A.

    **include_hebrew=False** (NA28/LXX/LXX2 apparatus):
      1. encoding.py Vector B sigla (most authoritative for Greek apparatus)
      2. apparatus_charset sigla — excluding Hebrew vowel points
         (0x8A,0x8E,0xB4,0xB6) which are MT-ETCBC-A only
      3. Greek diacritics — fill gaps only
      4. Final sigma (0xA7 → ς) — always available if not already mapped
    """
    m: dict[int, str] = {}

    if not include_hebrew:
        # encoding.py sigla at highest priority for Greek apparatus
        try:
            from accordance_parser.encoding import _APPARATUS_SIGLA_MAP as _enc_s  # type: ignore[no-redef]
        except ImportError:
            _enc_s: dict[int, str] = {}  # type: ignore[no-redef]
        m.update(_enc_s)

    if include_hebrew:
        # Hebrew-map first (Greek-only apparatus never needs Hebrew)
        m.update(HEBREW_MAP)
        # Apparatus sigla override Hebrew
        for k, v in APPARATUS_SIGLA_MAP.items():
            if v is not None:
                m[k] = v
    else:
        # Apparatus sigla minus Hebrew vowel points (MT-ETCBC-A only).
        # _HEBREW_VOWEL_BYTES_IN_SIGLA is defined later in the module
        # but only evaluated when include_hebrew=False, i.e. after its
        # definition at module level.
        for k, v in APPARATUS_SIGLA_MAP.items():
            if v is not None and k not in m and k not in _HEBREW_VOWEL_BYTES_IN_SIGLA:
                m[k] = v

    # Greek diacritics — lowest priority, fill gaps only
    for k, v in GREEK_DIACRITIC_MAP.items():
        if k not in m:
            m[k] = v

    # Final sigma (0xA7) — always available if not already mapped.
    # (Already present in GREEK_DIACRITIC_MAP, but explicit fallback
    # ensures it is never absent from the decode table.)
    _FINAL_SIGMA = 0xA7
    if _FINAL_SIGMA not in m:
        m[_FINAL_SIGMA] = "\u03c2"

    return m


COMBINED_MAP: dict[int, str] = _build_decode_map(include_hebrew=True)


def decode_byte(b: int) -> str:
    """Decode a single 8-bit apparatus byte to Unicode.

    Returns the Unicode string if mapped, or a hex placeholder like ``[CF]``
    if the byte is unmapped and in the 8-bit range.
    ASCII bytes (0x00–0x7F) are returned as ``chr(b)``.
    """
    if b < 0x80:
        return chr(b)
    if b in FORMATTING_BYTES:
        return ""  # skip formatting bytes
    mapped = COMBINED_MAP.get(b)
    if mapped is not None:
        return mapped
    # Unmapped high byte: return as hex placeholder
    return f"[{b:02X}]"


def decode_bytes(data: bytes) -> str:
    """Decode a byte sequence from apparatus encoding to Unicode.

    Each byte is decoded individually using :func:`decode_byte`.
    Formatting bytes are silently dropped.

    After decoding, ``convert_hebrew_beta_code`` should be called to
    convert remaining ASCII Beta Code Hebrew consonants to Unicode.
    """
    parts = []
    for b in data:
        result = decode_byte(b)
        if result:
            parts.append(result)
    return "".join(parts)


def decode_apparatus_text(raw: bytes) -> str:
    """Decode apparatus text with full Hebrew Beta Code support.

    Combines 8-bit byte decoding with Hebrew Beta Code consonant
    conversion to produce readable Hebrew Unicode text.

    This is the recommended entry point for MT-ETCBC-A apparatus text.
    """
    decoded = decode_bytes(raw)
    return convert_hebrew_beta_code(decoded)


# ═══════════════════════════════════════════════════════════════════════
# Hebrew Beta Code → Unicode post-decoding conversion
# ═══════════════════════════════════════════════════════════════════════
#
# After 8-bit bytes are decoded to Hebrew Unicode (vowel points and
# Yehudit-font consonants), remaining ASCII letters that represent
# Hebrew Beta Code consonants must be converted to their Hebrew
# Unicode equivalents.

# Hebrew Beta Code consonant mapping (ASCII → Hebrew Unicode).
# The MT-ETCBC-A apparatus uses specific ASCII letters for consonants:
#   b=bet(ב), g=gimel(ג), d=dalet(ד), h=he(ה), w=vav(ו), z=zayin(ז),
#   x=chet(ח), j=tet(ט), y=yod(י), k=kaf(כ), l=lamed(ל), m=mem(מ),
#   n=nun(נ), s=shin(ש), p=pe(פ), c=tsadi(צ),
#   q=qof(ק), r=resh(ר), v=shin(ש), t=tav(ת), a=aleph(א),
#   o=ayin(ע), f=tet(ט)
#
# Note: differs slightly from encoding.py's _HEBREW_ASCII because
# the apparatus uses s for shin (not samekh) and j for tet (not yod).

HEBREW_BETA_CODE_MAP: dict[str, str] = {
    "a": "\u05d0",  # aleph
    "b": "\u05d1",  # bet
    "g": "\u05d2",  # gimel
    "d": "\u05d3",  # dalet
    "h": "\u05d4",  # he
    "w": "\u05d5",  # vav
    "z": "\u05d6",  # zayin
    "x": "\u05d7",  # chet
    "j": "\u05d8",  # tet
    "y": "\u05d9",  # yod
    "i": "\u05d9",  # yod (variant used in apparatus)
    "k": "\u05db",  # kaf
    "l": "\u05dc",  # lamed
    "m": "\u05de",  # mem
    "n": "\u05e0",  # nun
    "s": "\u05e9",  # shin
    "p": "\u05e4",  # pe
    "c": "\u05e6",  # tsadi
    "q": "\u05e7",  # qof
    "r": "\u05e8",  # resh
    "v": "\u05e9",  # ש  shin (shin dot omitted — prevents dagesh ordering issue)
    "t": "\u05ea",  # tav
    "f": "\u05d8",  # tet (variant)
    "o": "\u05e2",  # ayin
}

# Uppercase ASCII → Hebrew final (sofit) forms.
# These appear as word-final indicators in Beta Code text.
HEBREW_FINAL_FORM_MAP: dict[str, str] = {
    "K": "\u05da",  # final kaf
    "M": "\u05dd",  # final mem
    "N": "\u05df",  # final nun
    "P": "\u05e3",  # final pe
    "C": "\u05e5",  # final tsadi
}

# ASCII letters that are Hebrew Beta Code consonants (lowercase)
_HEBREW_BETA_CODE_SET: frozenset[str] = frozenset(HEBREW_BETA_CODE_MAP.keys())

# Set of ALL characters that are Hebrew Beta Code (consonants + final forms)
_HEBREW_BETA_CODE_ALL: frozenset[str] = _HEBREW_BETA_CODE_SET | frozenset(
    HEBREW_FINAL_FORM_MAP.keys()
)

# Characters that are valid within a Hebrew Beta Code word
# (consonants, final forms, underscore separator, semicolons)
_HEBREW_WORD_CHARS: frozenset[str] = _HEBREW_BETA_CODE_ALL | {"_", ";"}

# ── Apparatus notation abbreviations (NEVER convert to Hebrew) ──────────
# These are Latin/German/English apparatus terms that happen to be
# composed of letters in the Hebrew Beta Code set.  They must be
# excluded from conversion.
_APPARATUS_ABBREVIATIONS: frozenset[str] = frozenset(
    {
        # Latin apparatus shorthand
        "cf",  # confer (compare)
        "vel",  # or
        "et",  # and
        "non",  # not
        "sed",  # but
        # Insertion/omission notations
        "ins",  # insert
        "om",  # omit
        "add",  # add
        "hab",  # habet (see)
        "del",  # delete
        "tr",  # transpose
        "pc",  # pauci (a few)
        "pr",  # probably (abbreviated)
        "prb",  # probably
        "prp",  # proposed
        "frt",  # fortasse (perhaps)
        "frts",  # fortasse (variant)
        "Mss",  # manuscripts
        "Ms",  # manuscript
        "mlt",  # multi (many)
        "cet",  # ceteri (the rest)
        "cett",  # ceteri (variant)
        # Critical marks / abbreviations
        "txt",  # text
        "vg",  # Vulgate
        "vgmss",  # Vulgate manuscripts
        "vgms",  # Vulgate manuscripts
        "vgs",  # Vulgate variant
        "vgst",  # Vulgate stichometry
        "lat",  # Latin
        "syr",  # Syriac
        "syh",  # Syro-Hexapla
        "syp",  # Syriac Peshitta
        "cop",  # Coptic
        "bopt",  # Bohairic Coptic
        "ita",  # Itala (Old Latin)
        "itb",  # Old Latin variant
        "itc",  # Old Latin variant
        # Hebrew-related apparatus terms
        "Orig",  # Origen
        "Samar",  # Samaritan
        "exc",  # except
        "nonn",  # nonnulli (some)
        "sq",  # sequens (following)
        "al",  # alii (others)
        "sol",  # solus (alone)
        "ol",  # olim (formerly)
        "an",  # an (or, whether)
        "tot",  # totum (whole)
        "dl",  # dele (delete)
        "cj",  # conjecit (conjectured)
        "oc",  # occidens?
        "ocb",  # apparatus abbreviation
        "dva",  # apparatus abbreviation
        "bv",  # abbreviation
        "c",  # single-letter ref
        "d",  # single-letter ref
        "v",  # single-letter ref
        "l",  # l (abbreviation for "lege" = read)
        "b",  # b (variant note ref)
        "Cp",  # chapter-verse marker (MT-ETCBC-A format)
        "cp",  # chapter-verse marker (lowercase variant)
    }
)

# ── Reverse Hebrew Unicode → ASCII Beta Code mapping ────────────────────
# Used by ``_restore_abbreviations`` to detect and revert erroneously
# converted apparatus abbreviation words.
_REVERSE_HEBREW: dict[str, str] = {}
for _ascii_char, _heb_char in HEBREW_BETA_CODE_MAP.items():
    _REVERSE_HEBREW[_heb_char] = _ascii_char


def _restore_abbreviations(text: str) -> str:
    """Restore known apparatus abbreviations that were converted to Hebrew.

    After ``convert_hebrew_beta_code`` converts ASCII Beta Code letters
    to Hebrew Unicode, any known Latin apparatus abbreviations that
    happen to be composed of Hebrew-mappable letters (e.g. "prb", "cf",
    "pr", "nonn", "Samar") may have been erroneously converted.  This
    function scans for the Hebrew-converted form of each known
    abbreviation and restores the original Latin text.

    Handles partial matches: when a span boundary cuts off a leading
    non-Beta-Code character (e.g. the "S" in "Samar"), the function
    also tries matching the Beta-Code portion alone.

    Single-letter abbreviations are NOT restored because they are
    fundamentally ambiguous — the same Hebrew letter can be a
    legitimate consonant in apparatus Hebrew text.
    """
    for abbr in sorted(_APPARATUS_ABBREVIATIONS, key=len, reverse=True):
        if len(abbr) < 2:
            continue  # single-letter abbreviations are too ambiguous
        # Compute what this abbreviation would look like if converted to Hebrew
        heb_form = "".join(HEBREW_BETA_CODE_MAP.get(c, c) for c in abbr)
        if heb_form != abbr:  # Only if it was actually converted
            text = text.replace(heb_form, abbr)
        # Handle partial matches where the first character of the
        # abbreviation is not a Beta Code letter and was excluded
        # from the Hebrew span (e.g. "S" in "Samar" → span covers "amar")
        if len(abbr) > 2 and abbr[0] not in HEBREW_BETA_CODE_MAP:
            partial_heb = heb_form[1:]  # strip the non-converted leading char
            partial_abbr = abbr[1:]
            if partial_heb != partial_abbr:
                text = text.replace(partial_heb, partial_abbr)
    return text


# ── Hebrew vowel point Unicode range ───────────────────────────────────
# Vowel points (niqqud): U+05B0–U+05C3
# Cantillation marks: U+0591–U+05AF
# Hebrew consonants/letters: U+05D0–U+05EA
# The full Hebrew block is U+0590–U+05FF
_HEBREW_UNICODE_START = 0x0590
_HEBREW_UNICODE_END = 0x05FF


def _is_hebrew_unicode(ch: str) -> bool:
    """Return True if *ch* is a Hebrew Unicode character (from 8-bit decoding)."""
    if not ch:
        return False
    cp = ord(ch[0])  # first char (multi-char combos like שׁ have consonant first)
    return _HEBREW_UNICODE_START <= cp <= _HEBREW_UNICODE_END


def _extract_word_before_space(result: list[str], space_idx: int) -> str:
    """Extract the word before a space at index *space_idx* in *result*."""
    word: list[str] = []
    j = space_idx - 1
    while j >= 0:
        ch = result[j]
        if "a" <= ch <= "z" or "A" <= ch <= "Z" or ch in ("_", ";"):
            word.append(ch)
            j -= 1
        else:
            break
    return "".join(reversed(word))


def _is_likely_latin_word(word: str) -> bool:
    """Return True if a word looks like Latin/German/English apparatus text.

    Used to avoid converting apparatus notation words that happen to be
    composed of ASCII letters in the Hebrew Beta Code set.
    """
    if not word:
        return False
    lower = word.lower()
    if lower in _APPARATUS_ABBREVIATIONS:
        return True
    # Words with uppercase letters that aren't final-form markers
    # (K, M, N, P, C) are almost certainly Latin (e.g. "Samar", "Orig")
    for ch in word:
        if "A" <= ch <= "Z" and ch not in HEBREW_FINAL_FORM_MAP:
            return True
    return False


def convert_hebrew_beta_code(text: str) -> str:
    """Convert ASCII Beta Code Hebrew consonants to Hebrew Unicode.

    After :func:`decode_bytes` converts 8-bit bytes to Hebrew vowel points
    and Yehudit-font consonants, remaining ASCII letters that represent
    Hebrew Beta Code consonants (e.g. ``b``=bet, ``r``=resh) are still
    Latin.  This function detects Hebrew context and converts them.

    The apparatus encoding has a specific structure:
    - ASCII Beta Code letters are Hebrew consonants
    - ASCII ``a`` (0x61) is a **transliteration placeholder** when it
      immediately precedes a Hebrew vowel point — it is stripped.
    - ASCII ``a`` elsewhere in Hebrew context is the consonant aleph.
    - When two Hebrew vowel points appear consecutively, the first
      belongs to the preceding consonant, the second to the next
      consonant (vowel reassignment).

    Known apparatus abbreviations (``cf``, ``ins``, ``vel``, etc.)
    are excluded from conversion.

    Safe to call on text with mixed Greek/Latin/Hebrew content.
    """
    if not text:
        return text

    # Build a list of characters for in-place mutation
    chars = list(text)
    n = len(chars)

    # ── Pass 1: Mark Hebrew Unicode anchors and convert adjacent consonants ──
    # Find all positions of Hebrew Unicode characters (from 8-bit decoding)
    hebrew_positions: set[int] = set()
    for i, ch in enumerate(chars):
        if _is_hebrew_unicode(ch):
            hebrew_positions.add(i)

    if not hebrew_positions:
        # No Hebrew 8-bit bytes — try word-based detection
        return _convert_standalone_hebrew_words(chars)

    # Convert ASCII Beta Code consonants that are adjacent to Hebrew
    # Unicode characters (walking outward from each Hebrew anchor).
    # IMPORTANT: "a" is NOT converted here — it may be a placeholder.
    # "a" is handled in Pass 2.
    _beta_code_no_a = _HEBREW_BETA_CODE_SET - {"a"}

    for hi in sorted(hebrew_positions):
        # Walk backward: convert preceding ASCII Beta Code letters
        j = hi - 1
        while j >= 0:
            ch = chars[j]
            if ch in _beta_code_no_a:
                chars[j] = HEBREW_BETA_CODE_MAP[ch]
                j -= 1
            elif ch == "a":
                # "a" is a placeholder or aleph — skip over it,
                # continue walking to find the real consonant
                j -= 1
            elif ch in HEBREW_FINAL_FORM_MAP:
                chars[j] = HEBREW_FINAL_FORM_MAP[ch]
                j -= 1
            elif ch in ("_", ";"):
                j -= 1  # Hebrew word separators
            elif ch == " ":
                # Check if word before space is a Latin abbreviation
                prev_word = _extract_word_before_space(chars, j)
                if prev_word.lower() in _APPARATUS_ABBREVIATIONS:
                    break
                if _is_likely_latin_word(prev_word):
                    break
                j -= 1  # Cross space within Hebrew phrase
            else:
                break  # Non-Hebrew character

        # Walk forward: convert following ASCII Beta Code letters
        j = hi + 1
        while j < n:
            ch = chars[j]
            if ch in _beta_code_no_a:
                chars[j] = HEBREW_BETA_CODE_MAP[ch]
                j += 1
            elif ch == "a":
                # "a" is a placeholder or aleph — skip over it
                j += 1
            elif ch in HEBREW_FINAL_FORM_MAP:
                chars[j] = HEBREW_FINAL_FORM_MAP[ch]
                j += 1
            elif ch in ("_", ";"):
                j += 1
            elif ch == " ":
                # Only cross space if next char is also Hebrew
                j += 1
                if j < n and (
                    _is_hebrew_unicode(chars[j]) or chars[j] in _HEBREW_BETA_CODE_ALL
                ):
                    continue
                else:
                    break
            elif _is_hebrew_unicode(ch):
                j += 1  # Continue through Hebrew chars
            else:
                break  # Non-Hebrew character

    # ── Pass 2: Strip "a" placeholders and convert real "a" to aleph ──
    # An ASCII "a" that immediately precedes a Hebrew vowel combining
    # mark is a transliteration placeholder — replace with empty string.
    # An ASCII "a" elsewhere in Hebrew context becomes aleph.
    # We also strip consecutive "a" after a Hebrew consonant (the
    # placeholder pattern "consonant + a + vowel").
    i = 0
    while i < len(chars):
        if chars[i] == "a":
            if _a_is_placeholder(chars, i):
                chars[i] = ""  # Mark for removal
            elif _is_in_hebrew_context(chars, i):
                # "a" in Hebrew context but not a placeholder → aleph
                chars[i] = "\u05d0"
        i += 1

    # ── Pass 3: Vowel reassignment ──
    # When two consecutive Hebrew vowel combining marks appear
    # (e.g. sheva U+05B0 + tsere U+05B5), the second vowel should
    # attach to the NEXT Hebrew consonant, not stay on the current one.
    # Move the second vowel forward past any placeholder-stripped slots
    # to land after the next consonant.
    chars = _reassign_vowels(chars)
    hebrew_positions = {i for i, ch in enumerate(chars) if _is_hebrew_unicode(ch)}

    # ── Pass 4: Remove marked placeholders (empty strings) ──
    chars = [c for c in chars if c != ""]

    # ── Pass 5: Strip orphaned vowels ──
    # After placeholder stripping, some vowel combining marks end up
    # between two consonants where they don't belong.  Strip a vowel
    # that sits between two Hebrew consonants when:
    #   - The first consonant is NOT word-initial (it already had its
    #     own vowel from the original encoding)
    #   - The second consonant has its own vowel following
    chars = _strip_orphaned_vowels(chars)

    # ── Pass 6: Final-form uppercase detection for words without Hebrew anchors ──
    result = "".join(chars)
    result = _convert_standalone_hebrew_words(list(result))

    # ── Pass 7: Restore known abbreviations that were erroneously converted ──
    result = _restore_abbreviations(result)

    return result


def _strip_orphaned_vowels(chars: list[str]) -> list[str]:
    """Strip Hebrew vowel combining marks that are orphaned.

    An orphaned vowel is one that appears after a consonant that
    already has its own vowel.  These arise from the apparatus
    encoding where a placeholder 'a' + vowel byte pair is stripped,
    leaving an extra vowel on a consonant that already received
    its proper vowel from another byte.
    """
    _VOWEL_START = 0x05B0
    _VOWEL_END = 0x05C3

    # Consonant-modifier marks (NOT true vowels).  A consonant can
    # legitimately carry dagesh + a vowel point, so these should
    # NOT count as "already has a vowel" below.
    _CONSONANT_MODIFIERS: frozenset[int] = frozenset(
        {
            0x05BC,  # dagesh ּ
            0x05C1,  # shin dot ׁ
            0x05C2,  # sin dot ׂ
        }
    )

    def _is_hebrew_cons(ch: str) -> bool:
        if not ch:
            return False
        cp = ord(ch[0])  # ch[0] for combos like שׁ
        return 0x05D0 <= cp <= 0x05EA

    def _is_true_vowel(cp: int) -> bool:
        """Return True if *cp* is a vowel/cantillation mark, not a modifier."""
        return _VOWEL_START <= cp <= _VOWEL_END and cp not in _CONSONANT_MODIFIERS

    result: list[str] = []
    for i, ch in enumerate(chars):
        cp = ord(ch[0]) if ch else -1  # ch[0] for combos like שׁ

        # Check if this is a Hebrew vowel combining mark
        if _VOWEL_START <= cp <= _VOWEL_END:
            # Find the most recent consonant in the result
            prev_cons_idx = -1
            for j in range(len(result) - 1, -1, -1):
                if _is_hebrew_cons(result[j]):
                    prev_cons_idx = j
                    break
                if result[j] in (" ", "\n", "\r", "\t"):
                    break  # Word boundary — vowel is for this word's first consonant

            if prev_cons_idx >= 0:
                # Check if this consonant already has a TRUE vowel
                # after it (dagesh/shin-dot/sin-dot don't count).
                has_vowel_already = False
                for j in range(prev_cons_idx + 1, len(result)):
                    rc = result[j]
                    rp = ord(rc) if rc else -1
                    if _is_true_vowel(rp):
                        has_vowel_already = True
                        break
                    if _is_hebrew_cons(rc):
                        break  # Another consonant — this vowel would be for it

                if has_vowel_already:
                    # Previous consonant already has its vowel — skip this extra one
                    continue

        result.append(ch)

    return result


def _a_is_placeholder(chars: list[str], i: int) -> bool:
    """Return True if 'a' at *i* is a transliteration placeholder.

    A placeholder 'a' is followed (after skipping other placeholders
    and Beta Code letters) by a Hebrew vowel combining mark
    (U+05B0–U+05C3).
    """
    n = len(chars)
    j = i + 1
    while j < n:
        ch = chars[j]
        if ch == "":
            j += 1
            continue
        cp = ord(ch[0]) if ch else -1  # ch[0] for combos
        if 0x05B0 <= cp <= 0x05C3:
            # Hebrew vowel point — this 'a' is a placeholder
            return True
        if ch in _HEBREW_BETA_CODE_SET or ch == "a":
            # Another Beta Code letter or "a" — skip, keep looking
            j += 1
            continue
        # Non-Hebrew character — this 'a' is not a placeholder
        return False
    return False


def _is_in_hebrew_context(chars: list[str], i: int) -> bool:
    """Return True if position *i* is within a Hebrew word context.

    Only checks within the same word (bounded by spaces/newlines).
    Does NOT cross word boundaries.
    """
    n = len(chars)
    # Look backward within the current word for Hebrew characters
    j = i - 1
    while j >= 0:
        ch = chars[j]
        if ch in (" ", "\n", "\r", "\t"):
            break  # Word boundary — don't cross
        if _is_hebrew_unicode(ch):
            return True
        if ch and (0x05D0 <= ord(ch[0]) <= 0x05EA):
            return True  # Already converted Hebrew consonant
        if ch in _HEBREW_BETA_CODE_ALL or ch in ("_", ";"):
            j -= 1
            continue
        break  # Non-Hebrew character within the word
    # Look forward within the current word for Hebrew characters
    j = i + 1
    while j < n:
        ch = chars[j]
        if ch in (" ", "\n", "\r", "\t"):
            break  # Word boundary
        if _is_hebrew_unicode(ch):
            return True
        if ch and (0x05D0 <= ord(ch[0]) <= 0x05EA):
            return True
        if ch in _HEBREW_BETA_CODE_ALL or ch in ("_", ";"):
            j += 1
            continue
        break
    return False


def _reassign_vowels(chars: list[str]) -> list[str]:
    """Reassign consecutive vowel marks to correct consonants.

    When two consecutive Hebrew vowel combining marks appear
    (both in U+05B0–U+05C3 range), the second should attach to
    the NEXT Hebrew consonant, not the current one.

    Exception: dagesh (U+05BC) is a consonant modifier, not a true
    vowel.  When dagesh is the first of two consecutive marks,
    both marks belong to the SAME preceding consonant — do not
    reassign.  (e.g.  tav+dagesh+chirik = ``תִּ``, not ``תּיִ``)

    **Mutation safety invariant:**

    This function mutates ``chars`` in-place with ``.insert()`` and
    ``chars[j] = ""`` replacement.  The insert at position ``k+1``
    (line below) is always **after** the current iteration index ``i``
    because ``k > j > i`` and ``j = i+1`` at minimum.  Since
    ``k+1 > i``, the insertion does not shift the element currently
    under inspection.  The ``n += 1`` following insert keeps the
    ``while i < n`` guard consistent.  No element is ever skipped
    or double-processed.

    If this function is ever extended to insert before the current
    index, the invariant must be revisited.
    """
    _DAGESH = 0x05BC

    n = len(chars)
    i = 0
    while i < n:
        ch = chars[i]
        cp = ord(ch[0]) if ch else -1  # ch[0] handles multi-char combos like שׁ

        # Found a Hebrew vowel combining mark
        if 0x05B0 <= cp <= 0x05C3:
            # Check if NEXT char is also a vowel combining mark
            j = i + 1
            while j < n and chars[j] == "":
                j += 1
            if j >= n:
                break
            if j < n and 0x05B0 <= ord(chars[j][0]) <= 0x05C3:
                # Two consecutive marks — but if the first is dagesh,
                # both belong to the same consonant; skip reassignment.
                if cp == _DAGESH:
                    i += 1
                    continue
                second_vowel = chars[j]
                # When the second vowel is sheva (U+05B0) and the next
                # character after it is a Hebrew consonant from 8-bit
                # encoding (not Beta Code), the sheva is a boundary
                # separator — drop it instead of reassigning.
                # (e.g., bereshit: tsere+sheva+aleph → drop sheva)
                if second_vowel == "\u05b0":
                    k = j + 1
                    while k < n and chars[k] == "":
                        k += 1
                    if k < n and 0x05D0 <= ord(chars[k][0]) <= 0x05EA:
                        chars[j] = ""
                        i += 1
                        continue
                chars[j] = ""  # Remove second vowel from current position

                # Find the next Hebrew consonant (skip placeholders
                # and Beta Code letters).  Only actual Hebrew
                # consonants (U+05D0–U+05EA) are valid anchors;
                # other Hebrew-range chars (vowel marks, etc.) are
                # NOT consonants and should be skipped.
                k = j + 1
                while k < n:
                    ck = chars[k]
                    ck_cp = ord(ck[0]) if ck else -1  # ch[0] for combos like שׁ
                    if 0x05D0 <= ck_cp <= 0x05EA:
                        # Hebrew consonant found — insert vowel AFTER it
                        chars.insert(k + 1, second_vowel)
                        n += 1
                        break
                    if ck in _HEBREW_BETA_CODE_ALL or ck in ("_", ";"):
                        k += 1
                        continue
                    # Non-Hebrew — drop the vowel
                    break
        i += 1

    return chars


def _convert_standalone_hebrew_words(chars: list[str]) -> str:
    """Convert Hebrew Beta Code words that lack 8-bit Hebrew anchors.

    Handles words like ``wyra``, ``alhyM``, ``ky_fwb`` that are
    pure ASCII Beta Code with no vowel points.  Detection via
    uppercase final-form letters (K, M, N, P, C) and underscore
    separators.
    """
    text = "".join(chars)
    if not text:
        return text

    # Split into word-like tokens
    tokens = _tokenize(text)

    result_parts: list[str] = []
    for token in tokens:
        if (
            token in _APPARATUS_ABBREVIATIONS
            or token.lower() in _APPARATUS_ABBREVIATIONS
        ):
            result_parts.append(token)
        elif _is_hebrew_beta_code_word(token):
            result_parts.append(_convert_word(token))
        else:
            result_parts.append(token)

    return "".join(result_parts)


def _tokenize(text: str) -> list[str]:
    """Split text into word-like tokens, preserving spaces/punctuation."""
    import re

    return re.split(r"(\s+)", text)


def _is_hebrew_beta_code_word(word: str) -> bool:
    """Return True if *word* is entirely Hebrew Beta Code."""
    if not word or len(word) < 2:
        return False
    # Check characters
    has_hebrew_char = False
    for ch in word:
        if ch in _HEBREW_BETA_CODE_ALL:
            has_hebrew_char = True
        elif ch in ("_", ";"):
            continue
        else:
            return False
    if not has_hebrew_char:
        return False
    # Additional signals: uppercase final form or underscore separator
    has_final = any(ch in HEBREW_FINAL_FORM_MAP for ch in word)
    has_underscore = "_" in word
    # For all-lowercase words, require length >= 4 to reduce false positives
    if not has_final and not has_underscore and len(word) < 4:
        return False
    return True


def _convert_word(word: str) -> str:
    """Convert a pure Hebrew Beta Code word to Hebrew Unicode."""
    result: list[str] = []
    for ch in word:
        if ch in HEBREW_BETA_CODE_MAP:
            result.append(HEBREW_BETA_CODE_MAP[ch])
        elif ch in HEBREW_FINAL_FORM_MAP:
            result.append(HEBREW_FINAL_FORM_MAP[ch])
        elif ch in ("_", ";"):
            result.append(ch)
        else:
            result.append(ch)
    return "".join(result)


# ═══════════════════════════════════════════════════════════════════════
# NA28 / LXX / LXX2 apparatus entry decoding
# ═══════════════════════════════════════════════════════════════════════
#
# These apparatus modules use a mixed encoding:
#   - Greek text: ASCII Beta Code (a=α, b=β, g=γ, ...) WITHOUT diacritics
#     (apparatus text cites readings, not a full critical edition)
#   - 8-bit bytes (0x80-0xFF): apparatus sigla and critical marks
#     (ℵ, 𝔐, f¹, ‖, –, etc.) — NOT Greek diacritic modifiers
#   - English/Latin apparatus notes and headers: plain ASCII
#
# The decoding strategy:
#   1. Replace known 8-bit sigla bytes with Unicode equivalents
#   2. Detect ASCII Beta Code runs of 3+ letters in Greek context
#      and convert to Greek Unicode using encoding.py's _GREEK_ASCII
#   3. Convert § (0xA7) to final sigma (ς) in Greek context
#   4. Preserve English/Latin text (do NOT convert to Greek)
#   5. Do NOT apply Hebrew Beta Code conversion

# ── Get _GREEK_ASCII from encoding.py ─────────────────────────────────
try:
    from accordance_parser.encoding import _GREEK_ASCII as _ENC_GREEK_ASCII
    from accordance_parser.encoding import _postprocess_decoded as _ENC_POSTPROCESS
except ImportError:
    _ENC_GREEK_ASCII: dict[int, str] = {}  # type: ignore[no-redef]

    def _ENC_POSTPROCESS(s: str) -> str:  # type: ignore[misc]
        return s  # no-op fallback


# ── Known apparatus notation abbreviations (never Beta Code Greek) ────
# These Latin/German/English apparatus terms must NOT be converted to
# Greek even if they look like Beta Code.
_NON_GREEK_ABBREVS: frozenset[str] = frozenset(
    {
        # Latin apparatus shorthand
        "cf",
        "vel",
        "et",
        "non",
        "sed",
        "ins",
        "om",
        "add",
        "hab",
        "del",
        "tr",
        "pc",
        "prb",
        "prp",
        "frt",
        "frts",
        "Mss",
        "Ms",
        "mlt",
        "cet",
        "cett",
        "txt",
        "vg",
        "vgmss",
        "vgms",
        "vgs",
        "vgst",
        "lat",
        "syr",
        "syh",
        "syp",
        "cop",
        "bopt",
        "ita",
        "itb",
        "itc",
        "exc",
        "nonn",
        "sq",
        "al",
        "sol",
        "ol",
        "an",
        "tot",
        "dl",
        "cj",
        "oc",
        "ocb",
        "dva",
        "pr",
        "bv",
        "Orig",
        "Samar",
        # English/German in apparatus
        "see",
        "vid",
        "ms",
        "mss",
        "f",
        "ff",
        "pm",
        "alii",
        "pler",
        "rell",
        "scr",
        "cod",
        "codd",
        "ed",
        "edd",
        "orig",
        "pref",
        "inc",
        "expl",
        "omitt",
        "omit",
        "addit",
        "inser",
        "transp",
        # Latin words that appear in apparatus verse text
        "Inscriptio",
        "inscriptio",
        "boms",  # Latin abbreviation (bom = Bohairic manuscript siglum + s)
        "bom",
        "can",  # Latin "canon"
        "cap",  # Latin "caput" (chapter)
        "cf",
        "cp",
        # English book names and abbreviations
        "Matthew",
        "Mark",
        "Luke",
        "John",
        "Acts",
        "Romans",
        "Corinthians",
        "Galatians",
        "Ephesians",
        "Philippians",
        "Colossians",
        "Thessalonians",
        "Timothy",
        "Titus",
        "Philemon",
        "Hebrews",
        "James",
        "Peter",
        "Jude",
        "Revelation",
        "Genesis",
        "Exodus",
        "Leviticus",
        "Numbers",
        "Deuteronomy",
        "Joshua",
        "Judges",
        "Ruth",
        "Samuel",
        "Kings",
        "Chronicles",
        "Ezra",
        "Nehemiah",
        "Esther",
        "Job",
        "Psalms",
        "Proverbs",
        "Ecclesiastes",
        "Song",
        "Isaiah",
        "Jeremiah",
        "Lamentations",
        "Ezekiel",
        "Daniel",
        "Hosea",
        "Joel",
        "Amos",
        "Obadiah",
        "Jonah",
        "Micah",
        "Nahum",
        "Habakkuk",
        "Zephaniah",
        "Haggai",
        "Zechariah",
        "Malachi",
        # Common book abbreviations
        "Gn",
        "Ex",
        "Lv",
        "Nu",
        "Dt",
        "Jos",
        "Jdg",
        "Ru",
        "Sm",
        "Ki",
        "Ch",
        "Chr",
        "Ezr",
        "Neh",
        "Est",
        "Jb",
        "Ps",
        "Pr",
        "Ec",
        "So",
        "Is",
        "Jr",
        "La",
        "Ezk",
        "Dn",
        "Ho",
        "Jl",
        "Am",
        "Ob",
        "Jnh",
        "Mi",
        "Na",
        "Hab",
        "Zp",
        "Hg",
        "Zc",
        "Mal",
        "Mt",
        "Mk",
        "Lk",
        "Jn",
        "Ac",
        "Ro",
        "Co",
        "Ga",
        "Eph",
        "Php",
        "Col",
        "Th",
        "Ti",
        "Tt",
        "Phm",
        "Heb",
        "Jas",
        "Pe",
        "Jd",
        "Rev",
        "Rth",  # Ruth abbreviation
        # Common English/Latin terms
        "Chapter",
        "chapter",
        "vol",
        "Vol",
        "p",
        "pp",
        "Intro",
        "introduction",
        # Apparatus manuscript sigla that look like Beta Code
        "mae",  # Latin abbreviation
        "boms",
        "bom",
        "Zare",  # Proper noun
        # More Latin apparatus terms
        "abs",
        "rel",
        "rell",
        "reliqui",
        "multi",
        "pauci",
        "plerique",
        "uncial",
        "minusc",
        "lect",
        "lectionary",
    }
)

# Normalize to all-lowercase so case-insensitive matching works reliably
_NON_GREEK_ABBREVS = frozenset(w.lower() for w in _NON_GREEK_ABBREVS)


def _is_non_greek_word(word: str) -> bool:
    """Return True if *word* is a known Latin/English apparatus term."""
    return word.lower() in _NON_GREEK_ABBREVS


# ── Strong Greek signal letters ──────────────────────────────────────
# ASCII letters that almost NEVER appear in native English/Latin words
# but ARE common in Greek Beta Code.  Runs containing these are almost
# certainly Greek text and should be converted.
_STRONG_GREEK_SIGNALS: frozenset[int] = frozenset(
    {
        ord("q"),  # θ (theta) — no native English words use 'q' without 'u'
        ord("j"),  # η/ι/τ — rare in English; in Beta Code = eta/yod/tet
        ord("y"),  # ψ (psi) — only at end of English words, but common in Greek
        ord("x"),  # ξ (xi) — rare in English, common in Greek (Christos = xristos)
    }
)

# ── Final sigma byte ─────────────────────────────────────────────────
_FINAL_SIGMA_BYTE: int = 0xA7


# ── Build a clean Greek+Sigma apparatus sigla map ────────────────────
# Exclude Hebrew vowel-point entries that were placed in APPARATUS_SIGLA_MAP
# for MT-ETCBC-A but are not valid sigla for NA28/LXX/LXX2.
_HEBREW_VOWEL_BYTES_IN_SIGLA: frozenset[int] = frozenset(
    {
        0x8A,  # patach
        0x8E,  # segol
        0xB4,  # chirik
        0xB6,  # qamats
    }
)

# ── Greek-apparatus sigla decode map (NA28/LXX/LXX2) ──────────────────
# Built from the same _build_decode_map builder as COMBINED_MAP, but
# with include_hebrew=False — encoding.py sigla at top priority,
# no Hebrew consonants/vowels.
_APPARATUS_DECODE_MAP: dict[int, str] = _build_decode_map(include_hebrew=False)


def decode_apparatus_entry(raw_text: str) -> str:
    """Decode a NA28 / LXX / LXX2 apparatus entry to Unicode.

    Delegates to ``encoding.py``'s proven ``decode_apparatus`` which
    handles 8-bit apparatus sigla, Beta Code Greek, and final-sigma
    detection.  Unmapped high bytes pass through as readable Latin-1
    rather than ``[XX]`` hex noise.
    """
    if not raw_text:
        return ""

    # Use encoding.py's proven apparatus decoder (Vector B)
    data = raw_text.encode("latin-1", errors="replace")
    try:
        from accordance_parser.encoding import decode_apparatus as _enc_decode

        return _enc_decode(data)
    except ImportError:
        pass

    # Fallback: basic sigla replacement
    result: list[str] = []
    for b in data:
        if b < 0x80:
            result.append(chr(b) if b >= 0x20 else " ")
        elif b in APPARATUS_SIGLA_MAP and APPARATUS_SIGLA_MAP[b] is not None:
            result.append(APPARATUS_SIGLA_MAP[b])
        else:
            result.append(chr(b))  # pass through as Latin-1
    return "".join(result)


def _has_greek_or_sigla_before(result: list[str], max_lookback: int = 5) -> bool:
    """Check if recently decoded output contains Greek or sigla characters.

    Looks back through *result* (skipping whitespace) for Greek Unicode
    letters or high-codepoint sigla (U+2000+).  Returns True if found
    within *max_lookback* non-whitespace tokens.
    """
    tokens_seen = 0
    for s in reversed(result):
        if not s:
            continue
        # Skip whitespace-only strings
        stripped = s.strip()
        if not stripped:
            continue
        tokens_seen += 1
        if tokens_seen > max_lookback:
            break
        # Check the last character of this token
        last_ch = stripped[-1]
        if _char_is_greek_unicode(last_ch):
            return True
        if ord(last_ch) >= 0x2000:
            return True
    return False


def _has_greek_or_sigla_after(
    data: bytes, start: int, n: int, max_lookahead: int = 20
) -> bool:
    """Check if bytes after *start* contain a Greek signal within *max_lookahead* bytes.

    Skips whitespace and digits.  Returns True if an 8-bit byte (>=0x80),
    final-sigma byte (0xA7), or a likely-Greek Beta Code word is found.
    """
    j = start
    while j < n and j - start < max_lookahead:
        b = data[j]
        if b >= 0x80:
            return True
        if b == _FINAL_SIGMA_BYTE:
            return True
        if b in (0x20, 0x09, 0x0D, 0x0A):  # whitespace
            j += 1
            continue
        if 0x30 <= b <= 0x39:  # digits
            j += 1
            continue
        if (0x41 <= b <= 0x5A) or (0x61 <= b <= 0x7A):
            # Found an ASCII letter run — check if it's likely Greek
            peek = j
            while peek < n and (
                (0x41 <= data[peek] <= 0x5A) or (0x61 <= data[peek] <= 0x7A)
            ):
                peek += 1
            next_word_bytes = data[j:peek]
            next_word = next_word_bytes.decode("ascii", errors="replace")
            # A 3+ letter word with a strong Greek signal is Greek
            if len(next_word_bytes) >= 3 and any(
                cb in _STRONG_GREEK_SIGNALS for cb in next_word_bytes
            ):
                return True
            # A 3+ letter word with all Greek-mappable lowercase letters
            # in Greek context is likely Greek
            if len(next_word_bytes) >= 3 and not _is_non_greek_word(next_word):
                all_map = all(
                    _ENC_GREEK_ASCII.get(cb) is not None for cb in next_word_bytes
                )
                if all_map:
                    return True
            return False  # non-Greek word found
        return False  # non-letter, non-sigla, non-whitespace
    return False


def _decode_apparatus_bytes(data: bytes) -> str:
    """Core decoding: sigla replacement + Beta Code Greek detection.

    Process byte by byte:
    1. 8-bit bytes: replace with sigla/Greek from _APPARATUS_DECODE_MAP
    2. ASCII letter runs: detect as Greek Beta Code based on:
       a. Contains a strong Greek signal letter (q, j, y, x) → Greek
       b. 5+ lowercase letters, all mappable → Greek
       c. 3-4 lowercase letters adjacent to Greek/sigla context → Greek
       d. Known Latin abbreviation → NOT Greek
       e. Uppercase-dominated run (all caps) → NOT Greek (Roman numerals, sigla)
    3. Other ASCII: pass through.
    """
    n = len(data)
    result: list[str] = []
    i = 0

    while i < n:
        b = data[i]

        # ── 8-bit range: sigla / Greek char / hex placeholder ─────
        if b >= 0x80:
            mapped = _APPARATUS_DECODE_MAP.get(b)
            if mapped is not None:
                result.append(mapped)
            else:
                result.append(f"[{b:02X}]")
            i += 1
            continue

        # ── ASCII letter run ──────────────────────────────────────
        if (0x41 <= b <= 0x5A) or (0x61 <= b <= 0x7A):
            run_start = i
            while i < n and ((0x41 <= data[i] <= 0x5A) or (0x61 <= data[i] <= 0x7A)):
                i += 1
            run_bytes = data[run_start:i]
            word = run_bytes.decode("ascii", errors="replace")

            # Never convert known Latin/English abbreviations
            if _is_non_greek_word(word):
                result.append(word)
                continue

            # Check if ALL letters have Greek Beta Code mappings
            greek_chars: list[str] = []
            all_greek = True
            for cb in run_bytes:
                gc = _ENC_GREEK_ASCII.get(cb)
                if gc is None:
                    all_greek = False
                    break
                greek_chars.append(gc)

            if not all_greek:
                result.append(word)
                continue

            run_len = len(greek_chars)

            # ── Detection rule 1: strong Greek signal letter ──────
            # q=θ, j=η/ι/τ, y=ψ, x=ξ — these almost never appear
            # in native English/Latin words in these positions.
            has_strong_signal = any(cb in _STRONG_GREEK_SIGNALS for cb in run_bytes)

            # ── Detection rule 2: all-caps runs are NOT Greek ──────
            # Roman numerals (III, VII, XIV) and manuscript sigla
            # (𝔐, ℵ) are all-uppercase and should not be converted.
            all_caps = all(0x41 <= cb <= 0x5A for cb in run_bytes)

            # ── Detection rule 3: context check ────────────────────
            # Is this run within a Greek context?  Look backward and
            # forward through whitespace/punctuation for Greek signals.
            prev_is_greek = _has_greek_or_sigla_before(result)
            next_is_greek = _has_greek_or_sigla_after(data, i, n)

            # ── Decision logic ─────────────────────────────────────
            should_convert = False

            if has_strong_signal:
                # Always convert runs with Greek-only letters (e.g. Matqaion, xristos)
                should_convert = True
            elif all_caps:
                # Never convert all-uppercase runs (Roman numerals, manuscript sigla)
                should_convert = False
            elif run_len >= 5:
                # Long lowercase/mixed runs: check for English body text patterns
                # If the run is 5+ lowercase letters → likely Greek
                has_upper = any(0x41 <= cb <= 0x5A for cb in run_bytes)
                if not has_upper:
                    should_convert = True
                else:
                    # Mixed-case: only convert if in Greek context
                    should_convert = prev_is_greek or next_is_greek
            elif run_len >= 3:
                # Short runs (3-4 letters): convert if in Greek context
                should_convert = prev_is_greek or next_is_greek
            elif run_len == 2:
                # Very short (2 letters): only convert if strong context
                should_convert = prev_is_greek and next_is_greek

            if should_convert:
                result.extend(greek_chars)
            else:
                result.append(word)
            continue

        # ── Non-letter ASCII ──────────────────────────────────────
        if 0x20 <= b < 0x7F:
            result.append(chr(b))
        elif b == 0x0D:
            result.append("\n")
        elif b == 0x09:
            result.append("\t")
        else:
            result.append(" ")
        i += 1

    return "".join(result)


def _char_is_greek_unicode(ch: str) -> bool:
    """Return True if character *ch* is in the Greek Unicode range."""
    if not ch:
        return False
    cp = ord(ch)
    return (0x0370 <= cp <= 0x03FF) or (0x1F00 <= cp <= 0x1FFF)


# ═══════════════════════════════════════════════════════════════════════
# Context-aware decoding for MT-ETCBC-A apparatus (mixed Hebrew/Greek)
# ═══════════════════════════════════════════════════════════════════════
#
# The apparatus text mixes Greek (Helena font) and Hebrew (Yehudit font)
# 8-bit encodings.  Some byte values overlap (0xCF, 0xEE, 0xF0, 0xF6,
# 0xD7).  This module uses a span-based approach:
#   1. Detect Hebrew byte ranges using unique Hebrew consonant bytes
#   2. Within Hebrew spans: full Hebrew decoding (Beta Code + vowel marks)
#   3. Outside Hebrew spans: Greek decoding (diacritics + sigla)
#
# ASCII apparatus abbreviations (cf, vel, Mss, prb, etc.) are never
# converted to Hebrew even when adjacent to Hebrew text.

# ── Additional Hebrew vowel-point bytes for apparatus context ──────────
# These appear in Hebrew spans but are not in HEBREW_MAP or
# APPARATUS_SIGLA_MAP.  Sourced from encoding.py's _HEBREW_POINTS.
_APPARATUS_HEBREW_POINTS: dict[int, str] = {
    0xD7: "\u05b0",  # sheva  ְ  (Accordance verified: Gen 1:30 וְאת)
    0xEB: "\u05b8",  # qamats ָ  (Accordance verified: Gen 1:30 נָתַתִּי)
    0xF2: "\u05bc",  # dagesh ּ  (apparatus-specific; modifies preceding consonant)
}

# ── Vowel markers (uppercase ASCII) in apparatus Hebrew Beta Code ──────
_APPARATUS_VOWEL_MARKERS: dict[str, str] = {
    "A": "\u05b7",  # patach
    "E": "\u05b6",  # segol
    "I": "\u05b4",  # chirik
    "O": "\u05b9",  # holem
    "U": "\u05bb",  # qubuts
}

# ── Bytes that are unique to Hebrew (never Greek/sigla) ────────────────
# These 8-bit bytes serve as anchor seeds for Hebrew span detection.
_UNIQUE_HEBREW_SEED_BYTES: frozenset[int] = frozenset(
    {
        0xE3,
        0xE5,
        0xE6,
        0xE7,  # aleph, yod, lamed, nun
        0xEA,
        0xEB,  # aleph variant, tsadi
        0xF1,
        0xF3,
        0xF4,
        0xF5,
        0xF7,  # vav, chet, tet, mem, ayin
        0xF2,  # dagesh (Hebrew-only in apparatus)
        0xAE,
        0xAF,
        0xBC,
        0xBD,
        0xBF,  # sofit: final pe, nun, tsadi, kaf, mem
    }
)

# ── 8-bit bytes that can appear within Hebrew context ──────────────────
# Includes consonants, vowel points, and Hebrew-related sigla.
_HEBREW_CONTEXT_BYTES: frozenset[int] = _UNIQUE_HEBREW_SEED_BYTES | frozenset(
    {
        0xCF,
        0xED,  # sheva, tsere (from HEBREW_MAP)
        0x8A,
        0x8E,
        0xB4,
        0xB6,  # patach, segol, chirik, qamats (from SIGLA)
        0xD7,  # holem
        0xF2,
        0xEE,
        0xF0,
        0xF6,  # pe/qof/shin/tav — ambiguous but Hebrew in context
        0xFD,  # unmapped siglum byte (frequent, unknown glyph)
    }
)

# ── Bytes that clearly indicate Greek (stop Hebrew span expansion) ─────
_GREEK_BOUNDARY_BYTES: frozenset[int] = frozenset(
    set(GREEK_DIACRITIC_MAP.keys())
    - set(HEBREW_MAP.keys())
    - set(APPARATUS_SIGLA_MAP.keys())
    - {0xD7}  # 0xD7 is ambiguous; don't use as boundary
)

# Uppercase ASCII that is definitely NOT Hebrew (Latin apparatus words)
_NON_HEBREW_UPPERCASE: frozenset[str] = frozenset(
    {
        "B",
        "D",
        "F",
        "G",
        "H",
        "J",
        "L",
        "Q",
        "R",
        "S",
        "T",
        "V",
        "W",
        "X",
        "Y",
        "Z",
    }
)


# ── Hebrew span detection helpers ──────────────────────────────────────
# Decomposed from _find_apparatus_hebrew_spans (was CC 57, now ≤ 15 each).


def _collect_hebrew_seeds(data: bytes) -> list[int]:
    """Find byte positions of unique Hebrew consonant/sofit bytes.

    These serve as anchor seeds for Hebrew span detection.
    Returns a sorted list of byte offsets.
    """
    seeds: set[int] = set()
    for i, b in enumerate(data):
        if b in _UNIQUE_HEBREW_SEED_BYTES:
            seeds.add(i)
    return sorted(seeds)


def _merge_seeds_into_spans(data: bytes, seeds: list[int]) -> list[tuple[int, int]]:
    """Merge nearby seed positions into initial spans.

    Seeds within GAP=15 bytes are merged.  Spans are split at:
    - Greek-only bytes (_GREEK_BOUNDARY_BYTES)
    - Non-Hebrew uppercase ASCII runs (Latin apparatus words)

    Returns list of (start, end) half-open spans.
    """
    GAP = 15
    raw_spans: list[tuple[int, int]] = []
    span_start = seeds[0]
    prev = seeds[0]

    for pos in seeds[1:]:
        if pos - prev > GAP:
            gap_bytes = data[prev + 1 : pos]
            # Split on Greek bytes
            if any(b in _GREEK_BOUNDARY_BYTES for b in gap_bytes):
                raw_spans.append((span_start, prev + 1))
                span_start = pos
            # Split on non-Hebrew uppercase (Latin words)
            elif any(b in range(0x41, 0x5B) for b in gap_bytes):
                gap_text = gap_bytes.decode("latin-1", errors="replace")
                latin_chars = sum(1 for ch in gap_text if ch in _NON_HEBREW_UPPERCASE)
                if latin_chars > 0 and len(gap_text) > 3:
                    raw_spans.append((span_start, prev + 1))
                    span_start = pos
        prev = pos
    raw_spans.append((span_start, prev + 1))
    return raw_spans


def _expand_hebrew_span_left(data: bytes, start: int) -> int:
    """Expand a Hebrew span start position leftward through adjacent Hebrew bytes.

    Expands through:
    - 8-bit Hebrew context bytes (_HEBREW_CONTEXT_BYTES)
    - ASCII Beta Code Hebrew letters
    - Apparatus vowel markers (uppercase A/E/I/O/U)
    - Hebrew internal separators (_, ;, ,)
    - Single spaces when the next char continues Hebrew context

    Stops at Greek-only bytes, Latin apparatus words, note-letter padding,
    and non-Hebrew ASCII.  Caps expansion at 30 bytes leftward.
    """
    ns = start
    while ns > 0:
        b = data[ns - 1]
        if b in _HEBREW_CONTEXT_BYTES:
            ns -= 1
        elif b < 0x80:
            ch = chr(b)
            if ch in _HEBREW_BETA_CODE_ALL or ch in _APPARATUS_VOWEL_MARKERS:
                ns -= 1
            elif ch in ("_", ";", ","):
                ns -= 1
            elif ch == " ":
                # Cross single space if next char continues Hebrew context
                if ns > 1:
                    next_b = data[ns - 2]
                    next_ch = chr(next_b) if next_b < 0x80 else ""
                    # Don't cross into note letters (single char after 0xCA padding)
                    if (
                        ns >= 2
                        and data[ns - 1] == 0x20
                        and ns >= 3
                        and data[ns - 3] == 0xCA
                    ):
                        break
                    if (
                        next_b >= 0x80
                        or next_ch in _HEBREW_BETA_CODE_ALL
                        or next_ch in ("_", ";", ",")
                    ):
                        ns -= 1
                    else:
                        break
                else:
                    break
            else:
                break
        else:
            break
        if start - ns > 30:
            break
    return ns


def _expand_hebrew_span_right(data: bytes, start: int, end: int) -> int:
    """Expand a Hebrew span end position rightward through adjacent Hebrew bytes.

    Same expansion rules as ``_expand_hebrew_span_left`` but moving forward.
    Caps expansion at 60 bytes rightward from the seed boundary.
    """
    n = len(data)
    ne = end
    while ne < n:
        b = data[ne]
        if b in _HEBREW_CONTEXT_BYTES:
            ne += 1
        elif b < 0x80:
            ch = chr(b)
            if ch in _HEBREW_BETA_CODE_ALL or ch in _APPARATUS_VOWEL_MARKERS:
                ne += 1
            elif ch in ("_", ";", ","):
                ne += 1
            elif ch == " ":
                # Cross single space if next char continues Hebrew context
                if ne + 1 < n:
                    next_b = data[ne + 1]
                    next_ch = chr(next_b) if next_b < 0x80 else ""
                    if (
                        next_b >= 0x80
                        or next_ch in _HEBREW_BETA_CODE_ALL
                        or next_ch in ("_", ";", ",")
                    ):
                        ne += 1
                    else:
                        break
                else:
                    break
            else:
                break
        else:
            break
        if ne - start > 60:
            break
    return ne


def _expand_hebrew_span(data: bytes, start: int, end: int) -> tuple[int, int]:
    """Expand a seed-based span outward through adjacent Hebrew bytes.

    Delegates to ``_expand_hebrew_span_left`` and
    ``_expand_hebrew_span_right`` for each direction.
    """
    ns = _expand_hebrew_span_left(data, start)
    ne = _expand_hebrew_span_right(data, ns, end)
    return (ns, ne)


def _merge_overlapping_spans(spans: list[tuple[int, int]]) -> list[tuple[int, int]]:
    """Merge overlapping or adjacent spans into a minimal set."""
    if not spans:
        return []
    sorted_spans = sorted(spans)
    merged = [sorted_spans[0]]
    for sp in sorted_spans[1:]:
        if sp[0] <= merged[-1][1]:
            merged[-1] = (merged[-1][0], max(merged[-1][1], sp[1]))
        else:
            merged.append(sp)
    return merged


def _trim_leading_sigla(
    data: bytes, spans: list[tuple[int, int]]
) -> list[tuple[int, int]]:
    """Trim leading apparatus sigla bytes from Hebrew spans.

    Bytes 0xE3/0xEA/0xFD/0x8C are apparatus sigla (⅏/𝔖/𝔊/ℵ) when
    they appear at the start of a note, before any Hebrew text.
    They should NOT be decoded as Hebrew consonants (aleph).
    Trim them from the span start if followed by a space and Hebrew
    content further on.
    """
    _LEADING_SIGLA = frozenset({0xE3, 0xEA, 0xFD, 0x8C})
    trimmed: list[tuple[int, int]] = []
    for start, end in spans:
        s = start
        # Skip leading sigla bytes as long as they're followed by
        # space and more Hebrew content (not the end of the span).
        while s < end and data[s] in _LEADING_SIGLA:
            # Check: after this sigla, is there a space then Hebrew?
            peek = s + 1
            while peek < end and data[peek] == 0x20:
                peek += 1
            if peek < end and (
                data[peek] >= 0x80 or chr(data[peek]) in _HEBREW_BETA_CODE_ALL
            ):
                s += 1  # Trim this sigla byte
            else:
                break  # No Hebrew after — keep sigla in span
        if s < end:
            trimmed.append((s, end))
    return trimmed


def _find_apparatus_hebrew_spans(data: bytes) -> list[tuple[int, int]]:
    """Detect Hebrew byte ranges in MT-ETCBC-A apparatus text.

    Uses unique Hebrew consonant/sofit bytes as seeds.  Expands
    outward through Hebrew-related bytes but stops at Greek-only
    bytes, Latin apparatus words, and spaces between Latin words.

    Decomposed into sub-functions (was CC 57, now CC ≤ 15 each):
      _collect_hebrew_seeds → _merge_seeds_into_spans
      → _expand_hebrew_span → _merge_overlapping_spans
      → _trim_leading_sigla
    """
    seeds = _collect_hebrew_seeds(data)
    if not seeds:
        return []
    raw = _merge_seeds_into_spans(data, seeds)
    expanded = [_expand_hebrew_span(data, s, e) for s, e in raw]
    merged = _merge_overlapping_spans(expanded)
    return _trim_leading_sigla(data, merged)


def _is_hebrew_cons(ch: str) -> bool:
    """Return True if *ch* is a Hebrew consonant (U+05D0–U+05EA)."""
    if not ch:
        return False
    cp = ord(ch[0])  # check first char (consonant, before any vowel point)
    return 0x05D0 <= cp <= 0x05EA


def _decode_hebrew_span(span_bytes: bytes) -> str:
    """Decode a Hebrew span — 8-bit bytes only, ASCII kept verbatim.

    8-bit bytes are decoded using the Hebrew consonant map, vowel
    point map (applied to preceding consonant), and sigla map.
    ASCII bytes — including Beta Code letters, vowel markers,
    and apparatus abbreviations — are left as-is for the
    ``convert_hebrew_beta_code`` post-processing step.
    """
    raw: list[str] = []
    i = 0
    n = len(span_bytes)

    def _last_cons(chars: list[str]) -> int:
        for k in range(len(chars) - 1, -1, -1):
            ch = chars[k]
            if _is_hebrew_cons(ch):
                return k
            # Also check for ASCII Beta Code Hebrew consonants
            if len(ch) == 1 and ch in _HEBREW_BETA_CODE_ALL:
                return k
        return -1

    while i < n:
        b = span_bytes[i]

        if b < 0x80:
            # Filter C0 control characters (0x00-0x1F) except \t \n \r
            if b < 0x20 and b not in (0x09, 0x0A, 0x0D):
                i += 1  # skip C0 controls
                continue
            # ASCII: handle vowel markers, Beta Code, and Hebrew separators
            ch = chr(b)
            if ch in _APPARATUS_VOWEL_MARKERS:
                raw.append(_APPARATUS_VOWEL_MARKERS[ch])
            elif ch == ";" and len(raw) > 0:
                # Semicolons represent dagesh (U+05BC) ONLY when
                # between two Hebrew Beta Code letters or before a
                # vowel marker — peek ahead to distinguish.  A
                # semicolon followed by a space or apparatus
                # notation is a real separator, not dagesh.
                peek = i + 1
                while peek < n and span_bytes[peek] in (0xCA, 0x00, 0x0D, 0x09):
                    peek += 1
                if peek < n:
                    next_b = span_bytes[peek]
                    if next_b < 0x80:
                        next_ch = chr(next_b)
                        if (
                            next_ch in _HEBREW_BETA_CODE_ALL
                            or next_ch in _APPARATUS_VOWEL_MARKERS
                        ):
                            raw.append("\u05bc")  # dagesh between Hebrew letters
                        else:
                            raw.append(";")  # real separator (e.g. before "prb")
                    else:
                        raw.append(";")  # separator before 8-bit byte
                else:
                    raw.append(";")  # end-of-span separator
            else:
                raw.append(ch)
            i += 1
            continue

        # ── 8-bit range ──
        if b in (0xCA, 0x00, 0x0D, 0x09):
            i += 1  # skip formatting
            continue

        if b == 0xFD:
            raw.append(APPARATUS_SIGLA_MAP.get(b, "\U0001d50a"))
            i += 1
            continue

        # Check vowel points FIRST (apparatus-specific, like dagesh)
        # before consonant map — shared bytes like 0xF2 are vowel
        # points in the apparatus, not consonants.
        mapped = _APPARATUS_HEBREW_POINTS.get(b)
        if mapped is not None:
            # Sheva separator: if this is a sheva (0xCF→U+05B0) and the
            # previous byte was also a vowel point, and the next byte is
            # a Hebrew consonant, this sheva is a separator — skip it.
            # Example: bereshit pattern where second 0xCF between 0xED and 0xEA
            # is an invisible boundary marker, not a vowel.
            if b == 0xCF and i > 0:
                prev_b = span_bytes[i - 1]
                if prev_b >= 0x80 and prev_b not in (0xCA, 0x00, 0x0D, 0x09, 0xFD):
                    # Previous byte was a vowel/consonant byte
                    if i + 1 < n and span_bytes[i + 1] >= 0x80:
                        # Next byte is also 8-bit — this sheva is a separator
                        i += 1
                        continue
            raw.append(mapped)
            i += 1
            continue

        # Try Hebrew consonant map
        mapped = HEBREW_MAP.get(b)
        if mapped is not None:
            raw.append(mapped)
            i += 1
            continue

        # Try apparatus sigla
        mapped = APPARATUS_SIGLA_MAP.get(b)
        if mapped is not None:
            raw.append(mapped)
            i += 1
            continue

        # C1 control range (0x80-0x9F): filter as space
        if 0x80 <= b <= 0x9F:
            raw.append(" ")
            i += 1
            continue

        # Pass through as Latin-1 (Accordance MacRoman convention)
        if b >= 0xA0:
            raw.append(chr(b))
            i += 1
            continue

        raw.append(f"[{b:02X}]")
        i += 1

    return "".join(raw)


def decode_apparatus_bytes_contextual(data: bytes) -> str:
    """Decode apparatus bytes with context-aware Hebrew/Greek detection.

    Uses ``_find_apparatus_hebrew_spans`` to identify Hebrew byte
    ranges.  Within Hebrew spans, applies full Hebrew decoding
    including Beta Code consonants, vowel markers, and vowel points.
    Outside Hebrew spans, applies Greek diacritic decoding and keeps
    apparatus notation as Latin transliteration.

    0xFD is left unmapped (unknown siglum glyph).
    Formatting bytes (0xCA, 0x0D, 0x09, 0x00) are silently dropped.
    """
    if not data:
        return ""

    # Detect Hebrew byte ranges
    spans = _find_apparatus_hebrew_spans(data)
    hebrew_positions: set[int] = set()
    for start, end in spans:
        for i in range(start, end):
            hebrew_positions.add(i)

    # Decode: Hebrew spans get 8-bit Hebrew decoding (ASCII kept
    # verbatim for Beta Code post-processing).  Non-Hebrew spans
    # get Greek/Latin decoding.
    # We track each decoded segment and whether it's Hebrew.
    segments: list[tuple[str, bool]] = []  # (text, is_hebrew)
    i = 0
    while i < len(data):
        if i in hebrew_positions:
            # Find end of this Hebrew span
            span_start = i
            while i < len(data) and i in hebrew_positions:
                i += 1
            heb_text = _decode_hebrew_span(data[span_start:i])
            # Apply Beta Code conversion immediately to this Hebrew segment
            heb_converted = convert_hebrew_beta_code(heb_text)
            segments.append((heb_converted, True))
        else:
            b = data[i]
            if b in (0xCA, 0x0D, 0x09, 0x00):
                pass  # skip formatting
            elif b < 0x80:
                # Filter C0 control characters (0x00-0x1F) except \t \n \r
                if b < 0x20 and b not in (0x09, 0x0A, 0x0D):
                    pass  # skip C0 controls
                else:
                    segments.append((chr(b), False))
            elif b == 0xFD:
                segments.append((APPARATUS_SIGLA_MAP.get(b, "\U0001d50a"), False))
            else:
                mapped = GREEK_DIACRITIC_MAP.get(b)
                if mapped is None:
                    mapped = APPARATUS_SIGLA_MAP.get(b)
                if mapped is None:
                    mapped = _APPARATUS_HEBREW_POINTS.get(b)
                if mapped is None:
                    mapped = HEBREW_MAP.get(b)
                if mapped is None:
                    # C1 control range (0x80-0x9F): filter as space
                    if 0x80 <= b <= 0x9F:
                        mapped = " "
                    else:
                        # Pass through as Latin-1 (Accordance MacRoman convention)
                        mapped = chr(b)
                segments.append((mapped, False))
            i += 1

    result = "".join(text for text, _ in segments)
    # Post-process: convert remaining ASCII Beta Code Hebrew words
    # (e.g. wyra→וירא, alhyM→אלהים) that appear in non-Hebrew
    # segments without 8-bit Hebrew anchors.
    result = convert_hebrew_beta_code(result)
    return result
