feat(lua): backport 5.1 hexadecimal number literals via source transpile

Lua 5.0's lexer reads only decimal digits + one '.' + 'e' exponent, so a
`0x...` literal is a compile error (hence addons resort to
`tonumber("0x...", 16)`). Lua 5.1 added hex literals. As with `#` / `%` /
`...`, we rewrite the SOURCE at the luaL_loadbuffer chokepoint: each hex
INTEGER token becomes the exact decimal it denotes (unsigned), which 5.0's
lexer accepts and reads as the same double 5.1 would.

RewriteHex runs first in the transpile pipeline, gated on a "0x"/"0X"
presence scan; it reuses the tokenizer (so strings/comments are never
touched) and inserts no newlines (line numbers preserved). Hex floats
(0x1.8p3) and > 64-bit literals are left as-is — vanishingly rare, and they
fail exactly as today (no regression). Also fixed SkipNumber to stop a
number at a `..` so `0xFF.."x"` (hex then concat) tokenizes cleanly.
Toggle: _classicapi_SetTranspileOption("HexLiterals", false).

Docs: API.md "Lua 5.1 syntax" section + README behaviors row.

Verified in-game (19/19 harness asserts) and cross-checked against retail:
0xFF->255, 0xFFFFFFFF->4294967295, bit.band(0xF0,0x0F)->0, "0xFF" untouched
all match modern WoW exactly.

Author: brues-code

README.md

@@ -234,7 +234,7 @@ Transparent engine tweaks — no API to call, they just fix a vanilla limitation
 |-------|--------|
 | Tooltip line cap | Lifts `GameTooltip`'s hard 30-line limit to 60 for every `GameTooltipTemplate` frame (`GameTooltip`, `ShoppingTooltip1/2`, `ItemRefTooltip`, AtlasLoot, …). Stat-heavy tooltips and comparison blocks (e.g. pfUI's eqcompare) no longer have their extra lines silently dropped. Done in pure C++ by growing the engine's FontString pool at tooltip-creation time. |
 | Inline textures | Draws inline texture markup (`\|T…\|t`) as icons in FontStrings, chat, and tooltips, the way 4.3.4+ clients do. Vanilla 1.12 shows the raw escape as literal text instead. This covers item and spell icons, raid-target markers, and the coin icons in money strings. `GetStringWidth` and `GetStringHeight` count the icons, so measured width and text wrapping stay correct. Done in pure C++ by hooking the engine's text pipeline — no addon. |
-| Lua 5.1 syntax | Compiles the Lua 5.1 length (`#`), modulo (`%`), and `...`-expression syntax that vanilla's Lua 5.0 rejects, by rewriting addon source before it compiles. Each addon file also receives its `(name, table)` through `...` (`local name, tbl = ...`). See [Lua 5.1 syntax](docs/API.md#lua-51-syntax-length-modulo-and-vararg). |
+| Lua 5.1 syntax | Compiles the Lua 5.1 length (`#`), modulo (`%`), `...`-expression, and `0x` hex-literal syntax that vanilla's Lua 5.0 rejects, by rewriting addon source before it compiles. Each addon file also receives its `(name, table)` through `...` (`local name, tbl = ...`). See [Lua 5.1 syntax](docs/API.md#lua-51-syntax). |
 | Lua 5.1 environment protection | `getfenv` / `setfenv` honor a `__environment` metatable field — the Lua 5.1 sandbox form — in addition to vanilla's raw `__fenv`. See [getfenv / setfenv environment protection](docs/API.md#getfenv--setfenv-environment-protection). |
 | Multi-flavor & conditional TOC loading | Loads modern multi-flavor addons that ship one folder. Selects a version-specific TOC (`<Name>_ClassicAPI.toc` or `<Name>_Turtle.toc`) and the matching keybinding file (`Bindings_ClassicAPI.xml` / `Bindings_Turtle.xml`), accepts a comma-separated `## Interface:` version list (compatible when it includes the client version `11200`), and honors per-line `[AllowLoadGameType]` / `[AllowLoadTextLocale]` conditions and `[Family]` / `[Game]` / `[TextLocale]` path variables inside a TOC. See [Conditional and multi-flavor TOC loading](docs/API.md#conditional-and-multi-flavor-toc-loading). |
 | SavedVariables loaded first | Honors the modern `## LoadSavedVariablesFirst` TOC directive: a flagged addon's SavedVariables load before its Lua runs, so file-scope code sees restored config (instead of vanilla's `nil`). See [SavedVariables loaded first](docs/API.md#savedvariables-loaded-first). |

docs/API.md

@@ -343,7 +343,7 @@ build instructions.
   - [`C_LossOfControl.GetActiveLossOfControlData(index)`](#c_lossofcontrolgetactivelossofcontroldataindex)
 
 - [Lua](#lua)
-  - [Lua 5.1 syntax: length, modulo, and vararg](#lua-51-syntax-length-modulo-and-vararg)
+  - [Lua 5.1 syntax](#lua-51-syntax)
   - [`getfenv` / `setfenv` environment protection](#getfenv--setfenv-environment-protection)
   - [`select(index, ...)`](#selectindex-)
   - [`table.wipe(t)`](#tablewipet)
@@ -8486,17 +8486,19 @@ backported addons find them. Most are single-function additions (several are
 just the 5.0→5.1 renames — `string.gmatch`←`gfind`, `math.fmod`←`math.mod`);
 `coroutine.*` restores the whole stripped coroutine library.
 
-### Lua 5.1 syntax: length, modulo, and vararg
+### Lua 5.1 syntax
 
-1.12 runs Lua 5.0. It cannot compile three pieces of Lua 5.1 syntax that
+1.12 runs Lua 5.0. It cannot compile four pieces of Lua 5.1 syntax that
 modern addons use. These are the length operator `#`, the modulo operator
-`%`, and `...` used as an expression. ClassicAPI rewrites addon source to
-the 5.0 equivalent before it compiles, so all three work:
+`%`, `...` used as an expression, and `0x` hexadecimal number literals.
+ClassicAPI rewrites addon source to the 5.0 equivalent before it compiles,
+so all four work:
 
 ```lua
 local n = #myTable          -- length operator
 local r = a % b             -- modulo operator
 local args = { ... }        -- ... as an expression, not only in a parameter list
+local mask = 0xFF00         -- hex number literal
 ```
 
 The rewrite is transparent. You do not call anything. It runs on every
@@ -8512,6 +8514,9 @@ What each form does:
   `-1 % 3` is `2`, while `math.mod(-1, 3)` is `-1`.
 - `...` as an expression yields all the varargs. The `...` in a function
   parameter list stays as the vararg declaration.
+- `0xFF00` becomes its decimal value (`65280`) — the same number Lua 5.1
+  produces. Vanilla's lexer rejects `0x` literals, so without this an addon
+  needs `tonumber("0xFF00", 16)`.
 
 **Addon file arguments.** A modern addon reads its name and its private
 table from the file arguments:
@@ -8534,14 +8539,17 @@ needs that addon's opt-in.
 - A nested long string or comment (`[[ a [[ b ]] c ]]`) matches at the
   first close, not by depth. This is a 5.0-only form that addons almost
   never use.
+- Only integer hex is converted. Hex *floats* (`0x1.8p3`) and literals
+  wider than 64 bits are left as-is. Both are almost nonexistent in addon
+  code.
 - Error line numbers stay correct. The rewrite adds no new lines.
 - The globals `__len` and `__mod` are the rewrite's helper functions.
   Treat them as internal. Do not call them directly.
 - To turn a rewrite off for diagnosis, call
   `_classicapi_SetTranspileOption(name, false)`, where `name` is
-  `"Length"`, `"Modulo"`, or `"VarargExpansion"`. This reverts affected
-  chunks to the state that fails to compile, so use it only to answer
-  "is the rewrite breaking this addon?".
+  `"Length"`, `"Modulo"`, `"VarargExpansion"`, or `"HexLiterals"`. This
+  reverts affected chunks to the state that fails to compile, so use it
+  only to answer "is the rewrite breaking this addon?".
 
 ### `getfenv` / `setfenv` environment protection
 

src/luasyntax/Transpile.cpp

@@ -14,17 +14,19 @@
 // Lua 5.1 syntax backport (source-level transpile).
 //
 // Vanilla's Lua is 5.0. It lacks the 5.1 operators `#` (length) and `%`
-// (modulo) AND `...` used as an expression, so modern addon ports that use
-// them fail to COMPILE. We don't touch the 5.0 parser/VM (there is no
-// OP_LEN / OP_MOD and no free opcode); instead we rewrite the SOURCE before it
-// reaches the parser: co-hook `luaL_loadbuffer` (the one function every compile
-// funnels through — file scripts, `loadstring`, XML `<OnLoad>`) and rewrite:
+// (modulo), `...` used as an expression, AND `0x` hexadecimal number
+// literals, so modern addon ports that use them fail to COMPILE. We don't
+// touch the 5.0 parser/VM (there is no OP_LEN / OP_MOD and no free opcode);
+// instead we rewrite the SOURCE before it reaches the parser: co-hook
+// `luaL_loadbuffer` (the one function every compile funnels through — file
+// scripts, `loadstring`, XML `<OnLoad>`) and rewrite:
 //     #operand      ->  __len(operand)
 //     a % b         ->  __mod(a, b)
 //     ...           ->  unpack(arg)      (the `...` EXPRESSION, not the decl)
+//     0xHH...       ->  <decimal>        (5.0's lexer rejects hex literals)
 // `__len` / `__mod` are C globals we register (see below); `unpack` and the
-// 5.0 `arg` table are already present. RewriteChunk runs the vararg pass first,
-// then the # / % precedence parser.
+// 5.0 `arg` table are already present. RewriteChunk runs the hex pass first,
+// then the vararg pass, then the # / % precedence parser.
 //
 // Why a real parser (not regex / one-term-each-side): `#` is prefix but `%`
 // is binary infix, so its operands must be delimited by PRECEDENCE —
@@ -50,10 +52,15 @@
 //     use first-close matching, not depth. Real addons ~never nest these.
 //   * `__len` on a table returns a border (bisection) = 5.1 `#`; it ignores
 //     any `table.setn` count (5.1 has no setn — correct `#` semantics).
+//   * Hex literals: only INTEGER `0x…` (up to 16 hex digits) are converted,
+//     to the exact decimal the value represents — the same double 5.1 would
+//     produce. Hex FLOATS (`0x1.8p3`) and > 64-bit literals are left as-is
+//     (vanishingly rare in addons; they fail to compile exactly as today, so
+//     no regression). The value is unsigned (`0xFFFFFFFF` -> 4294967295).
 //   * Diagnostic `_classicapi_TranspileLength(src)` returns the full rewrite.
 //   * Toggles via `_classicapi_SetTranspileOption(name, bool)` /
 //     `_classicapi_GetTranspileOption(name)` (name = "Length" / "Modulo" /
-//     "VarargExpansion").
+//     "VarargExpansion" / "HexLiterals").
 //   * `...` expands to `unpack(arg)`, which is faithful in every position and
 //     preserves embedded nils via `arg.n` (this build's `unpack` honors it).
 //     Only the `...` in a function's parameter list is left intact.
@@ -88,11 +95,12 @@ namespace {
 
 constexpr size_t NPOS = static_cast<size_t>(-1);
 
-// Runtime switches, default ON — a `#`/`%`/`...`-bearing chunk does not compile
-// on 5.0 today, so enabling by default cannot regress working addons.
+// Runtime switches, default ON — a `#`/`%`/`...`/`0x`-bearing chunk does not
+// compile on 5.0 today, so enabling by default cannot regress working addons.
 bool g_lenEnabled = true;
 bool g_modEnabled = true;
 bool g_varargEnabled = true;
+bool g_hexEnabled = true;
 
 // lua_rawgeti(L, idx, n) — push table_at_idx[n] without metamethods. Not
 // exposed via Game::Lua; used to probe table elements for the border search.
@@ -181,7 +189,9 @@ size_t SkipNumber(const char *src, size_t len, size_t pos) {
     while (i < len) {
         char c = src[i];
         if (c == '.') {
-            if (seenDot)
+            // A second dot, or the `..` concat operator, ends the number so
+            // `0xFF.."x"` / `1..2` split cleanly (the concat is not consumed).
+            if (seenDot || (i + 1 < len && src[i + 1] == '.'))
                 break;
             seenDot = true;
             i++;
@@ -720,13 +730,87 @@ bool RewriteVararg(const char *src, size_t len, std::string &out) {
     return true;
 }
 
-// Run every syntax rewrite over a chunk (vararg first, then # / %). Returns
-// true and fills `out` if anything changed.
+// ============================================================================
+// Hex-literal pass: rewrite 5.1 `0x…` integer literals to decimal.
+//
+// Lua 5.0's lexer reads only decimal digits + one `.` + `e` exponent, so a
+// `0x…` literal fails to compile (which is why addons resort to
+// `tonumber("0x…", 16)`). We convert each hex INTEGER token to the exact
+// decimal it denotes — Lua then reads it as the same double 5.1 would. The
+// value is unsigned. Hex floats and > 64-bit literals are left untouched (they
+// fail to compile as they do today — no regression). Runs before the other
+// passes; the tokenizer already skips strings/comments, so `"0xFF"` / `--0xFF`
+// are safe, and it never inserts a newline (line numbers preserved).
+// ============================================================================
+
+inline bool IsHexDigit(unsigned char c) {
+    return (c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F');
+}
+
+bool ContainsHexPrefix(const char *src, size_t len) {
+    for (size_t i = 0; i + 1 < len; i++)
+        if (src[i] == '0' && (src[i + 1] == 'x' || src[i + 1] == 'X'))
+            return true;
+    return false;
+}
+
+bool RewriteHex(const char *src, size_t len, std::string &out) {
+    if (src == nullptr || len == 0 || !g_hexEnabled)
+        return false;
+    if (!ContainsHexPrefix(src, len))
+        return false;
+
+    std::vector<Token> toks;
+    Tokenize(src, len, toks);
+
+    out.clear();
+    out.reserve(len);
+    size_t p = 0;
+    bool any = false;
+    for (const Token &t : toks) {
+        if (t.kind != TK_NUMBER || t.end - t.start < 3)
+            continue; // need "0x" + >= 1 digit
+        if (src[t.start] != '0')
+            continue;
+        char x = src[t.start + 1];
+        if (x != 'x' && x != 'X')
+            continue;
+        const size_t nDigits = t.end - (t.start + 2);
+        if (nDigits == 0 || nDigits > 16)
+            continue; // no digits, or wider than uint64 — leave as-is
+
+        uint64_t val = 0;
+        bool pure = true;
+        for (size_t i = t.start + 2; i < t.end; i++) {
+            unsigned char c = static_cast<unsigned char>(src[i]);
+            if (!IsHexDigit(c)) { pure = false; break; } // hex float ('.'/'p') or junk
+            val = val * 16 + ((c <= '9') ? (c - '0') : ((c | 0x20) - 'a' + 10));
+        }
+        if (!pure)
+            continue;
+
+        out.append(src + p, t.start - p);
+        out.append(std::to_string(val));
+        p = t.end;
+        any = true;
+    }
+    if (!any)
+        return false;
+    out.append(src + p, len - p);
+    return true;
+}
+
+// Run every syntax rewrite over a chunk (hex first, then vararg, then # / %).
+// Returns true and fills `out` if anything changed.
 bool RewriteChunk(const char *src, size_t len, std::string &out) {
+    std::string h;
+    bool didHex = RewriteHex(src, len, h);
+    const char *cur = didHex ? h.data() : src;
+    size_t curLen = didHex ? h.size() : len;
+
     std::string a;
-    bool didVararg = RewriteVararg(src, len, a);
-    const char *cur = didVararg ? a.data() : src;
-    size_t curLen = didVararg ? a.size() : len;
+    bool didVararg = RewriteVararg(cur, curLen, a);
+    if (didVararg) { cur = a.data(); curLen = a.size(); }
 
     std::string b;
     if (RewriteAll(cur, curLen, b)) {
@@ -737,6 +821,10 @@ bool RewriteChunk(const char *src, size_t len, std::string &out) {
         out = std::move(a);
         return true;
     }
+    if (didHex) {
+        out = std::move(h);
+        return true;
+    }
     return false;
 }
 
@@ -896,11 +984,21 @@ int __fastcall LoadBuffer_h(void *L, const char *buff, unsigned size, const char
     if (buff == nullptr || size == 0)
         return g_origLoadBuffer(L, buff, size, name);
 
-    // Syntax transpile: vararg first, then # / %.
+    // Syntax transpile: hex literals first, then vararg, then # / %.
+    std::string hx;
+    const char *body = buff;
+    size_t bodyLen = size;
+    if (RewriteHex(body, bodyLen, hx)) {
+        body = hx.data();
+        bodyLen = hx.size();
+    }
+
     std::string va;
-    bool didVararg = RewriteVararg(buff, size, va);
-    const char *body = didVararg ? va.data() : buff;
-    size_t bodyLen = didVararg ? va.size() : size;
+    bool didVararg = RewriteVararg(body, bodyLen, va);
+    if (didVararg) {
+        body = va.data();
+        bodyLen = va.size();
+    }
 
     std::string ops;
     if (RewriteAll(body, bodyLen, ops)) {
@@ -982,6 +1080,7 @@ const Toggle kToggles[] = {
     {"Length", &g_lenEnabled},
     {"Modulo", &g_modEnabled},
     {"VarargExpansion", &g_varargEnabled},
+    {"HexLiterals", &g_hexEnabled},
 };
 bool *FindToggle(const char *name) {
     if (name)