From fd386e75aed791ea9502d0acdb03edd8922fa5e3 Mon Sep 17 00:00:00 2001
From: Sam Sung <51686767+samwhosung@users.noreply.github.com>
Date: Fri, 25 Sep 2026 01:58:49 +0700
Subject: [PATCH] Comments in benilla-ui: one line of fact each, no history, no
 record numbers (#143)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Part of #41: the comments of `benilla-ui` (the Lua UI engine, its FrameXML loader and its widgets) are rewritten to the rule in `docs/METHOD.md`, which is what the code does and the reference fact behind it, in a line. 43,140 comment lines become 15,161.

- **The mechanical strip.** The citations that were only a private record number go first, and each edit is shown to be a pure removal.
- **Wrong facts corrected.** The rewrite corrects the comments that stated wrong facts. Among them:
  - `0x64a480` is the case-sensitive compare (a byte `repz cmpsb`), and `0x64a4c0` the case-insensitive one.
  - A frame's id sits at `+0xb0`, not `+0xb4`. `EnableKeyboard`/`IsKeyboardEnabled` are `0x776ec0`/`0x776f90`.
  - A region's unpinned edge has no fallback to its owner's rect: the owner supplies only the scale.
  - `$parent` expands to the nearest named ancestor, or "Top" when none is named (`0x76c5b0`), not simply to the parent.
  - A StatusBar fills from its internal normalised fraction, not from `GetValue()`.
  - The addresses of `StartDuel` and `StartDuelUnit` were swapped.
  - Many "untraced" notes now give the traced reference fact: the drag threshold, the per-grip sizing edges, the empty-`autoFocus` skip, and `SetTexCoordModifiesRect`'s default.
  - Stock FrameXML line citations are checked against the stock 1.12 files and corrected. `ref-` file names become the stock file names.
- **Deviation labels.** "Deviation:" now marks only a choice with a reason. A surface that exists only for the retired Era addon target says so plainly: it is not 1.12.
- **Verification.** Every file strips to identical code, and `cargo fmt --check` is clean. Nine second readers compared every file old against new, restored the facts the rewrite had dropped, and checked each new citation against the code, the stock files, vmangos and the reference.

Behaviour differences the rewrite surfaced are filed as their own issues (#131–#142), and more are being validated. The comments here state what the code does. String literals are untouched; they are #92.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 crates/benilla-ui/examples/dump_globals.rs    |   52 +-
 .../examples/dump_widget_methods.rs           |    7 +-
 crates/benilla-ui/src/bindings_xml.rs         |  177 +-
 crates/benilla-ui/src/civil.rs                |   33 +-
 crates/benilla-ui/src/framexml.rs             |  387 +---
 crates/benilla-ui/src/justify.rs              |  157 +-
 crates/benilla-ui/src/layout.rs               |  395 +---
 crates/benilla-ui/src/lib.rs                  |   24 +-
 crates/benilla-ui/src/loader/backdrop.rs      |   14 +-
 crates/benilla-ui/src/loader/geometry.rs      |  131 +-
 crates/benilla-ui/src/loader/mod.rs           |  688 ++----
 crates/benilla-ui/src/loader/regions.rs       |  273 +--
 crates/benilla-ui/src/loader/scripts.rs       |  144 +-
 crates/benilla-ui/src/loader/tests.rs         |  577 ++---
 crates/benilla-ui/src/loader/widgets.rs       |  365 +---
 crates/benilla-ui/src/markup.rs               |  478 ++---
 crates/benilla-ui/src/messages.rs             |  108 +-
 crates/benilla-ui/src/order.rs                |  441 ++--
 crates/benilla-ui/src/script/action.rs        |  253 +--
 .../src/script/action_bar_toggles.rs          |  120 +-
 crates/benilla-ui/src/script/addon.rs         |  513 ++---
 crates/benilla-ui/src/script/addon_gate.rs    |  108 +-
 crates/benilla-ui/src/script/addon_message.rs |  371 +---
 crates/benilla-ui/src/script/auction.rs       |  354 +--
 crates/benilla-ui/src/script/aura/mod.rs      |  295 +--
 .../benilla-ui/src/script/aura/player_buff.rs |  259 +--
 crates/benilla-ui/src/script/backdrop.rs      |  192 +-
 crates/benilla-ui/src/script/bank.rs          |  171 +-
 .../src/script/battlefield_positions.rs       |   40 +-
 .../src/script/battlefield_queue.rs           |  152 +-
 .../src/script/battlefield_score.rs           |  104 +-
 crates/benilla-ui/src/script/bind_confirm.rs  |   83 +-
 crates/benilla-ui/src/script/binder.rs        |   32 +-
 crates/benilla-ui/src/script/binding_abi.rs   |  342 +--
 crates/benilla-ui/src/script/button.rs        |  651 ++----
 crates/benilla-ui/src/script/camera_view.rs   |  117 +-
 crates/benilla-ui/src/script/channel.rs       |  311 +--
 crates/benilla-ui/src/script/char_stats.rs    |  867 ++------
 crates/benilla-ui/src/script/chat_misc.rs     |   44 +-
 crates/benilla-ui/src/script/chat_send.rs     |  134 +-
 crates/benilla-ui/src/script/chat_types.rs    |   62 +-
 crates/benilla-ui/src/script/chat_window.rs   |  487 +----
 crates/benilla-ui/src/script/client.rs        |  275 +--
 crates/benilla-ui/src/script/clip.rs          |   26 +-
 crates/benilla-ui/src/script/colorselect.rs   |  282 +--
 crates/benilla-ui/src/script/container.rs     |  640 ++----
 crates/benilla-ui/src/script/craft.rs         |  342 +--
 crates/benilla-ui/src/script/cursor.rs        |  460 ++--
 .../benilla-ui/src/script/cursor/bag_verbs.rs |  193 +-
 crates/benilla-ui/src/script/cursor/bar.rs    |  132 +-
 crates/benilla-ui/src/script/cursor/doll.rs   |  161 +-
 crates/benilla-ui/src/script/cursor/drag.rs   |  135 +-
 crates/benilla-ui/src/script/cursor/money.rs  |   59 +-
 crates/benilla-ui/src/script/cursor/pet.rs    |  249 +--
 crates/benilla-ui/src/script/cvars.rs         |  836 ++------
 crates/benilla-ui/src/script/death.rs         |   91 +-
 crates/benilla-ui/src/script/diagnostics.rs   |  219 +-
 crates/benilla-ui/src/script/dialog_verbs.rs  |   72 +-
 crates/benilla-ui/src/script/dressup.rs       |   80 +-
 crates/benilla-ui/src/script/duel.rs          |   50 +-
 crates/benilla-ui/src/script/editbox.rs       |  371 +---
 .../benilla-ui/src/script/editbox/interact.rs |   62 +-
 .../benilla-ui/src/script/editbox/methods.rs  |  229 +-
 crates/benilla-ui/src/script/editbox/seam.rs  |   65 +-
 crates/benilla-ui/src/script/editbox/tests.rs |  294 +--
 crates/benilla-ui/src/script/event.rs         |  170 +-
 crates/benilla-ui/src/script/extract.rs       |  376 +---
 crates/benilla-ui/src/script/follow.rs        |   56 +-
 crates/benilla-ui/src/script/font.rs          |  304 +--
 crates/benilla-ui/src/script/font_block.rs    |  261 +--
 crates/benilla-ui/src/script/gm_ticket.rs     |   92 +-
 crates/benilla-ui/src/script/gossip.rs        |  143 +-
 crates/benilla-ui/src/script/guild.rs         |  577 ++---
 crates/benilla-ui/src/script/handler_prof.rs  |  151 +-
 crates/benilla-ui/src/script/inspect.rs       |  202 +-
 crates/benilla-ui/src/script/instance.rs      |   48 +-
 crates/benilla-ui/src/script/item_stats.rs    |  503 ++---
 crates/benilla-ui/src/script/item_text.rs     |   37 +-
 crates/benilla-ui/src/script/keybind.rs       |  396 +---
 crates/benilla-ui/src/script/keyboard.rs      |  171 +-
 crates/benilla-ui/src/script/layout.rs        |  922 ++------
 crates/benilla-ui/src/script/layout_cache.rs  |  142 +-
 crates/benilla-ui/src/script/loot.rs          |  383 +---
 crates/benilla-ui/src/script/loot_roll.rs     |  174 +-
 crates/benilla-ui/src/script/lua50.rs         |  672 ++----
 .../benilla-ui/src/script/lua50/table_size.rs |  167 +-
 crates/benilla-ui/src/script/macros.rs        |  202 +-
 crates/benilla-ui/src/script/mail.rs          |  401 +---
 crates/benilla-ui/src/script/measure.rs       |  107 +-
 crates/benilla-ui/src/script/merchant.rs      |  390 +---
 .../benilla-ui/src/script/messageframe/mod.rs |  221 +-
 .../src/script/messageframe/plain.rs          |  164 +-
 .../src/script/messageframe/scrolling.rs      |  216 +-
 crates/benilla-ui/src/script/minimap.rs       |  103 +-
 crates/benilla-ui/src/script/mod.rs           |  876 ++------
 crates/benilla-ui/src/script/model.rs         | 1890 ++++-------------
 crates/benilla-ui/src/script/modelframe.rs    |  418 +---
 crates/benilla-ui/src/script/nameplate.rs     |  475 +----
 crates/benilla-ui/src/script/net_stats.rs     |   25 +-
 crates/benilla-ui/src/script/object.rs        |  451 ++--
 .../src/script/object/anchor_args.rs          |  128 +-
 .../src/script/object/events_regions.rs       |  267 +--
 .../src/script/object/frame_state.rs          |  389 +---
 .../src/script/object/layout_methods.rs       |  176 +-
 .../benilla-ui/src/script/object/movable.rs   |  376 +---
 .../benilla-ui/src/script/object/toplevel.rs  |  180 +-
 crates/benilla-ui/src/script/party.rs         |  650 ++----
 crates/benilla-ui/src/script/pet.rs           |  470 +---
 crates/benilla-ui/src/script/petition.rs      |  285 +--
 crates/benilla-ui/src/script/pointer.rs       |  593 ++----
 crates/benilla-ui/src/script/pvp/mod.rs       |  573 ++---
 crates/benilla-ui/src/script/pvp/tests.rs     |  248 +--
 crates/benilla-ui/src/script/quest.rs         |  213 +-
 crates/benilla-ui/src/script/quest_log.rs     |  556 ++---
 crates/benilla-ui/src/script/region.rs        |  464 +---
 crates/benilla-ui/src/script/region/layout.rs |   80 +-
 crates/benilla-ui/src/script/region/paint.rs  |  382 +---
 crates/benilla-ui/src/script/region/text.rs   |  166 +-
 crates/benilla-ui/src/script/region_map.rs    |  134 +-
 crates/benilla-ui/src/script/reputation.rs    |  302 +--
 crates/benilla-ui/src/script/saved.rs         |  162 +-
 crates/benilla-ui/src/script/screenshot.rs    |   23 +-
 crates/benilla-ui/src/script/scrollframe.rs   |  189 +-
 crates/benilla-ui/src/script/session.rs       |   76 +-
 crates/benilla-ui/src/script/shapeshift.rs    |   63 +-
 .../benilla-ui/src/script/simplehtml/mod.rs   |  342 +--
 .../benilla-ui/src/script/simplehtml/parse.rs |  255 +--
 crates/benilla-ui/src/script/skills.rs        |  378 +---
 crates/benilla-ui/src/script/slash.rs         |   83 +-
 crates/benilla-ui/src/script/slider.rs        |  171 +-
 crates/benilla-ui/src/script/social.rs        |  239 +--
 crates/benilla-ui/src/script/sound.rs         |  118 +-
 crates/benilla-ui/src/script/spellbook.rs     |  644 ++----
 crates/benilla-ui/src/script/stable.rs        |  336 +--
 crates/benilla-ui/src/script/statusbar.rs     |   74 +-
 crates/benilla-ui/src/script/stdlib.rs        |  263 +--
 crates/benilla-ui/src/script/summon.rs        |   66 +-
 crates/benilla-ui/src/script/surface.rs       |   53 +-
 crates/benilla-ui/src/script/tabard.rs        |  103 +-
 crates/benilla-ui/src/script/talent.rs        |  148 +-
 crates/benilla-ui/src/script/taxi.rs          |  105 +-
 .../src/script/tests/addon_argument_abi.rs    |   47 +-
 .../src/script/tests/addon_index_space.rs     |   59 +-
 crates/benilla-ui/src/script/tests/anchors.rs |  114 +-
 .../benilla-ui/src/script/tests/backdrop.rs   |   42 +-
 crates/benilla-ui/src/script/tests/button.rs  |  295 +--
 crates/benilla-ui/src/script/tests/channel.rs |   98 +-
 .../benilla-ui/src/script/tests/cooldown.rs   |   38 +-
 .../src/script/tests/create_frame_template.rs |  126 +-
 .../src/script/tests/dispatch_bench.rs        |   59 +-
 .../benilla-ui/src/script/tests/end_to_end.rs |   11 +-
 crates/benilla-ui/src/script/tests/events.rs  |   87 +-
 .../src/script/tests/font_object.rs           |  268 +--
 .../benilla-ui/src/script/tests/frame_api.rs  |   15 +-
 .../src/script/tests/generic_for.rs           |   82 +-
 .../benilla-ui/src/script/tests/gm_ticket.rs  |   46 +-
 .../src/script/tests/handler_prof.rs          |   28 +-
 crates/benilla-ui/src/script/tests/input.rs   |  200 +-
 .../benilla-ui/src/script/tests/keyboard.rs   |   51 +-
 .../src/script/tests/layout_gate.rs           |  129 +-
 crates/benilla-ui/src/script/tests/measure.rs |  135 +-
 crates/benilla-ui/src/script/tests/minimap.rs |   81 +-
 crates/benilla-ui/src/script/tests/mod.rs     |   61 +-
 .../src/script/tests/model_clock.rs           |   82 +-
 .../benilla-ui/src/script/tests/modelframe.rs |  216 +-
 crates/benilla-ui/src/script/tests/movable.rs |  141 +-
 .../src/script/tests/name_targets.rs          |   61 +-
 .../benilla-ui/src/script/tests/nameplate.rs  |  246 +--
 .../src/script/tests/numeric_shape_gate.rs    |   42 +-
 .../src/script/tests/reference_surface.rs     |  569 +----
 .../benilla-ui/src/script/tests/region_map.rs |   46 +-
 crates/benilla-ui/src/script/tests/regions.rs |  395 +---
 .../src/script/tests/resize_bounds.rs         |   56 +-
 .../src/script/tests/scrollframe.rs           |  115 +-
 .../benilla-ui/src/script/tests/setparent.rs  |   56 +-
 .../benilla-ui/src/script/tests/simplehtml.rs |  215 +-
 .../src/script/tests/size_changed.rs          |   51 +-
 crates/benilla-ui/src/script/tests/slider.rs  |  137 +-
 .../benilla-ui/src/script/tests/statusbar.rs  |    9 +-
 crates/benilla-ui/src/script/tests/stdlib.rs  |  161 +-
 .../src/script/tests/structure_queries.rs     |   57 +-
 crates/benilla-ui/src/script/tests/talent.rs  |   25 +-
 crates/benilla-ui/src/script/tests/taxi.rs    |    9 +-
 .../src/script/tests/texcoord_font.rs         |   36 +-
 crates/benilla-ui/src/script/tests/tooltip.rs |  220 +-
 .../src/script/tests/tooltip_item/bindings.rs |  110 +-
 .../src/script/tests/tooltip_item/law.rs      |  195 +-
 .../script/tests/tooltip_item/mechanics.rs    |  110 +-
 .../src/script/tests/tooltip_item/mod.rs      |   30 +-
 .../src/script/tests/tooltip_item/set.rs      |   38 +-
 .../src/script/tests/tooltip_spell.rs         |  147 +-
 .../src/script/tests/tooltip_unit.rs          |   98 +-
 .../benilla-ui/src/script/tests/toplevel.rs   |  210 +-
 .../benilla-ui/src/script/tests/visibility.rs |    2 +-
 .../src/script/tests/widget_surface.rs        |  105 +-
 .../benilla-ui/src/script/tests/worldframe.rs |   12 +-
 .../benilla-ui/src/script/tests/worldmap.rs   |  177 +-
 crates/benilla-ui/src/script/tick.rs          |  198 +-
 crates/benilla-ui/src/script/tooltip/mod.rs   |  380 +---
 crates/benilla-ui/src/script/tooltip/verbs.rs |  247 +--
 .../benilla-ui/src/script/tooltip_item/mod.rs |  491 ++---
 .../src/script/tooltip_item/names.rs          |   98 +-
 .../src/script/tooltip_item/render.rs         |  578 ++---
 crates/benilla-ui/src/script/tooltip_spell.rs |  379 +---
 crates/benilla-ui/src/script/tooltip_unit.rs  |  254 +--
 crates/benilla-ui/src/script/trade.rs         |  208 +-
 .../benilla-ui/src/script/tradeskill/api.rs   |  112 +-
 .../benilla-ui/src/script/tradeskill/mod.rs   |  237 +--
 .../benilla-ui/src/script/tradeskill/tests.rs |  127 +-
 .../benilla-ui/src/script/tradeskill/view.rs  |  138 +-
 crates/benilla-ui/src/script/trainer/mod.rs   |  507 +----
 crates/benilla-ui/src/script/trainer/tests.rs |  147 +-
 crates/benilla-ui/src/script/tutorial.rs      |   34 +-
 crates/benilla-ui/src/script/types.rs         |  762 ++-----
 crates/benilla-ui/src/script/ui_errors.rs     |   22 +-
 crates/benilla-ui/src/script/unit/bindings.rs |  794 ++-----
 crates/benilla-ui/src/script/unit/mod.rs      |  775 ++-----
 crates/benilla-ui/src/script/unit/tests.rs    |  492 ++---
 .../benilla-ui/src/script/weapon_enchant.rs   |  130 +-
 crates/benilla-ui/src/script/who_sort.rs      |  158 +-
 crates/benilla-ui/src/script/worldmap.rs      |  496 ++---
 .../benilla-ui/src/script/worldmap_arrow.rs   |   96 +-
 crates/benilla-ui/src/script/worldstate.rs    |   76 +-
 crates/benilla-ui/src/script/worn_display.rs  |   79 +-
 crates/benilla-ui/src/source.rs               |  136 +-
 crates/benilla-ui/src/strings.rs              |  207 +-
 crates/benilla-ui/src/toc.rs                  |  168 +-
 crates/benilla-ui/src/widget/kinds/editbox.rs |  521 ++---
 .../src/widget/kinds/messageframe.rs          |  364 +---
 crates/benilla-ui/src/widget/kinds/mod.rs     | 1412 +++---------
 crates/benilla-ui/src/widget/mod.rs           |  542 +----
 crates/benilla-ui/src/widget/propagation.rs   |  291 +--
 crates/benilla-ui/src/widget/tests.rs         |   50 +-
 233 files changed, 14108 insertions(+), 42094 deletions(-)

diff --git a/crates/benilla-ui/examples/dump_globals.rs b/crates/benilla-ui/examples/dump_globals.rs
index b85f510f..1ff2df50 100644
--- a/crates/benilla-ui/examples/dump_globals.rs
+++ b/crates/benilla-ui/examples/dump_globals.rs
@@ -1,40 +1,17 @@
-//! `dump_globals` — print benilla's Lua global namespace, asked of a real VM.
+//! `dump_globals`: print benilla's Lua global namespace, asked of a real VM.
 //!
 //! ```text
 //! cargo run -q -p benilla-ui --example dump_globals            # name<TAB>type, one per line
-//! cargo run -q -p benilla-ui --example dump_globals --members  # ...the stdlib TABLES' members too
+//! cargo run -q -p benilla-ui --example dump_globals --members  # plus the stdlib tables' members
 //! ```
 //!
-//! **The point is that it is a run, not a grep** (decisions 1188, 1189). Every wrong number in the
-//! addon arc came from measuring our API surface by pattern-matching Rust source: a regex over
-//! `.set("Name", …)` misses the Lua prelude, miscounts a `format!`-registered family, and cannot
-//! see what the sandbox removed. When the question is what a running system exposes, ask the
-//! running system — this is the four-minute answer 1188 §4 describes, made permanent.
-//!
-//! This is [`UiScript::new`]'s namespace: the Rust bindings plus the Lua stdlib prelude, i.e. what
-//! an addon sees *before* any FrameXML loads. That is deliberately the engine half — it is
-//! deterministic, needs no install, and is exactly what `scripts/api-coverage.sh` compares against
-//! `reference/1.12-globals.tsv`'s `engine` and `lua` rows.
-//!
-//! ## `--members`, and the blind spot it closes (decision 1194)
-//!
-//! `_G` is not the whole surface an addon can tell apart. `table.setn` is not a global — it is a
-//! member of the `table` table — and it stopped **61 of 218** real addons dead, because mlua's Lua
-//! 5.1 raises `'setn' is obsolete` where the 1.12 client's Lua 5.0 does the thing. A `_G`-only
-//! instrument cannot see that, and did not: the arc measured coverage for two sessions with this
-//! gap wide open. `--members` prints `table.setn`-style rows for the stdlib tables, so the dialect
-//! is measurable the same way the API surface is.
-//!
-//! It also prints the **per-type metatables** (decision 2171), which is the same blind spot one
-//! layer further down and stayed open longer because a metatable is not a *name*: 5.1 gives the
-//! string type one and 5.0 cannot have one, so `("x"):upper()` worked here and raised on the
-//! reference for as long as nothing thought to look.
+//! The namespace is [`UiScript::new`]'s, the engine half before any FrameXML loads, which
+//! `scripts/api-coverage.sh` compares with `reference/1.12-globals.tsv`. `--members` adds what `_G`
+//! cannot show: the stdlib tables' members (`table.setn` is one) and the per-type metatables.
 use benilla_ui::script::UiScript;
 
-/// The tables whose membership an addon can observe and depend on.
-///
-/// Deliberately a fixed list, not "every table-valued global": `_G` would recurse, and a *frame*
-/// table's members are the widget API, which is a different question with a different reference.
+/// The stdlib tables whose members an addon can observe: a fixed list, since `_G` would recurse
+/// and a frame's members are the widget API.
 const STDLIB: &[&str] = &["string", "table", "math", "coroutine", "os", "io", "debug"];
 
 fn main() -> mlua::Result<()> {
@@ -66,18 +43,9 @@ fn main() -> mlua::Result<()> {
             rows.extend(members);
         }
 
-        // **The per-type metatables — the surface `_G` and the member lists both miss** (decision
-        // 2171). `table.setn` taught 1194 that a `_G`-only instrument cannot see a *member*; the
-        // string metatable is the same lesson one layer further down, and it stayed invisible for
-        // longer because it is not a name at all. 1.12 installs none — `lua_setmetatable 0x6f4020`
-        // accepts only LUA_TTABLE and LUA_TUSERDATA and returns 0 for every other tag, so a
-        // primitive type there *cannot* carry one — while stock 5.1 gives `string` a metatable
-        // whose `__index` is the `string` table itself, which is what makes `("x"):upper()` work
-        // on 5.1 and raise on 5.0. Every row here should read `nil`.
-        //
-        // Written as a fixed list rather than a table because a `nil` value has no entry to
-        // iterate — the one type whose metatable slot is easiest to forget is the one a
-        // constructor silently drops.
+        // The per-type metatables. Every row should read `nil`: 1.12's `lua_setmetatable`
+        // (`0x6f4020`) takes only tables and userdata, where 5.1 gives strings one whose `__index`
+        // makes `("x"):upper()` work. Probed one by one, since a `nil` has no table entry.
         let metatables: Vec<String> = script.eval(
             "local out = {} \
              local function probe(name, v) \
diff --git a/crates/benilla-ui/examples/dump_widget_methods.rs b/crates/benilla-ui/examples/dump_widget_methods.rs
index ad0d3dc7..27550a20 100644
--- a/crates/benilla-ui/examples/dump_widget_methods.rs
+++ b/crates/benilla-ui/examples/dump_widget_methods.rs
@@ -1,13 +1,10 @@
-//! `dump_widget_methods` — print benilla's widget METHOD surface, asked of a real VM.
+//! `dump_widget_methods`: print benilla's widget method surface, asked of a real VM.
 //!
 //! ```text
 //! cargo run -q -p benilla-ui --example dump_widget_methods    # class<TAB>method, one per line
 //! ```
 //!
-//! The sibling of [`dump_globals`](../dump_globals.rs). The measurement itself lives in
-//! `benilla_ui::script::widget_method_census` — its module doc is the *why*, and the widget-surface
-//! gate (decision 2142) reads the same function, so the instrument you look at by hand and the gate
-//! that fails the build can never disagree about what our surface is.
+//! The census is `widget_method_census`, the same function the widget-surface gate reads.
 use benilla_ui::script::{widget_method_census, UiScript};
 
 fn main() -> mlua::Result<()> {
diff --git a/crates/benilla-ui/src/bindings_xml.rs b/crates/benilla-ui/src/bindings_xml.rs
index 0a714285..895c9d3e 100644
--- a/crates/benilla-ui/src/bindings_xml.rs
+++ b/crates/benilla-ui/src/bindings_xml.rs
@@ -1,107 +1,37 @@
-//! **`Bindings.xml`** — an addon's key-binding declaration (decision 1188 phase 4).
+//! An addon's `Bindings.xml`, its key-binding declarations. The reference loads one per addon in
+//! `AddOn_Load 0x51f240`, after the addon's `.toc` files (`0x51f3fa`) and before its saved
+//! variables (`0x51f400` to `0x51f4b5`). The stock file has 228 live bindings (94 `runOnUp`, 13
+//! `header`, 12 `hidden`, 9 `debug`, 5 `platform`); the six `MOVEVIEW*` ones sit in an XML comment.
 //!
-//! The reference loads one per addon, at a verified position inside `AddOn_Load 0x51f240`:
-//! **after** that addon's `.toc`-listed files (`0x51f3fa`) and **before** its saved-variables
-//! files (`0x51f400` → `0x51f4b5`). Both of benilla's load paths
-//! attach there — the startup walk (`benilla_app::ui_script::addons`) and the demand load
-//! ([`crate::script::addon`]) — and what they parse here feeds the same table the Key Bindings
-//! window edits ([`crate::script::keybind`]).
-//!
-//! ## The format, read off the client's own file, not remembered
-//!
-//! `Interface\FrameXML\Bindings.xml` (extracted 1.12.1) is **228 live `<Binding>` elements**,
-//! every one named, and the whole schema it uses is six attributes: `name` (228), `runOnUp` (94),
-//! `header` (13), `hidden` (12), `debug` (9), `platform` (5).
-//!
-//! *Live*, because a text search says 234: six more sit inside an XML comment — Blizzard commented
-//! out the whole `MOVEVIEW*` family in place. A parser that finds bindings by scanning text (and
-//! any count taken by `grep`) registers those six as real, which is why the counts here are the
-//! ones this module's own parse returns and why `a_commented_out_binding_is_not_a_binding` exists.
-//! The counts are pinned against the install itself by
-//! `benilla_app::bindings::commands::tests::the_installs_bindings_xml_reads_as_the_parsers_header_says`
-//! — there, because there is where the patch chain is (this crate reads no install).
-//!
-//! ```xml
-//! <Bindings>
-//!     <Binding name="MOVEFORWARD" runOnUp="true" header="MOVEMENT">
-//!         if ( keystate == "down" ) then MoveForwardStart(); else MoveForwardStop(); end
-//!     </Binding>
-//! </Bindings>
-//! ```
-//!
-//! - **The body is ONE Lua chunk, run once or twice.** A `runOnUp="true"` binding runs on the
-//!   press *and again* on the release, with the global `keystate` set to `"down"` / `"up"` — which
-//!   is why every shipped `runOnUp` body is an `if ( keystate == "down" )` fork. A binding without
-//!   it runs once, on the press. (Our own registry says the same thing a second way:
-//!   `benilla_app::bindings::commands::Kind::EdgeUpDown` holds the two halves as two strings,
-//!   because a host command's halves are ours to write. An addon's is one string and a global.)
-//! - **`header` is a GLOBAL-STRING KEY, and it opens a SECTION.** `header="MOVEMENT"` means the
-//!   category `BINDING_HEADER_MOVEMENT`, and every following binding *without* a `header` belongs
-//!   to it: 13 headers over 228 bindings is 13 sections, and the client's own list is flat with
-//!   `HEADER_*` pseudo-entries in it (`Blizzard_BindingUI.lua:87` tests
-//!   `strsub(commandName, 1, 6) == "HEADER"`). The carry-forward is applied at *registration*, not
-//!   here, so this type stays a faithful record of what the file says — see
-//!   [`crate::script::UiScript::register_addon_bindings`].
-//! - **`hidden="true"` keeps a binding out of the Key Bindings window** while leaving it bindable
-//!   and dispatchable — 1.12 uses it for the debug toggles and for the three mouselook bindings
-//!   (`TURNORACTION`, `CAMERAORSELECTORMOVE`, …) that the mouse owns rather than the player.
-//! - **`platform="mac"` is the file's own OS gate**, and its five uses are the whole of it: the
-//!   `ITUNES_REMOTE` block, which remotes the *system* music player and therefore exists only in
-//!   the Mac build. It is carried on [`AddonBinding::platform`] and acted on at registration
-//!   ([`crate::script::UiScript::register_addon_bindings`]) — a row for another platform is not
-//!   registered at all, so it never reaches the Key Bindings window, a save file, or a chord.
-//!   Registering it instead would list a command whose body calls functions this build does not
-//!   have, which is a row that can only ever error on its first press.
-//! - `debug="true"` is **read and not acted on**: it appears only on the client's own nine
-//!   hidden dev toggles, always together with `hidden="true"` (which IS acted on and is what
-//!   keeps them out of the window), and no addon in the wild uses it. Recording that it exists is
-//!   the point; inventing a second meaning for it would be a guess.
-//!
-//! ## Why this lives beside `toc` and `framexml` rather than under `script/`
-//!
-//! It is the third of the client's **file formats**, and the crate's top level is where a format
-//! becomes owned data with no VM in sight: [`crate::toc`] turns manifest text into a load list,
-//! [`crate::framexml`] turns document text into a tree, and this turns binding text into
-//! [`AddonBinding`]s. `script/` is the other side of that line — the live Lua-facing runtime,
-//! which *consumes* what these three produce. A parser under `script/keybind` would also be
-//! unreachable from the host's own load path without going through the VM, which is exactly the
-//! shape 1186 spent a decision untangling.
-//!
-//! XML *parsing* is delegated plumbing here for the same reason it is in [`crate::framexml`] —
-//! `roxmltree` reads the bytes, and only the schema→meaning map below is ours.
+//! A body is one Lua chunk; with `runOnUp="true"` it runs on press and again on release, the
+//! global `keystate` set to `"down"` or `"up"`. `header="X"` opens the section
+//! `BINDING_HEADER_X` that following header-less bindings join, in a flat list with `HEADER`
+//! pseudo-entries (`Blizzard_BindingUI.lua:87`). `hidden="true"` keeps a binding bindable but out
+//! of the Key Bindings window. `platform="mac"` marks the `ITUNES_REMOTE` rows; the reference
+//! skips another platform's row at load (`0x4b70c3`–`0x4b70e5`), benilla at registration.
 
 use std::fmt;
 
-/// One `<Binding>` element, exactly as the file states it.
-///
-/// Deliberately a *record of the file*, not of the registered binding: `header` is the raw
-/// attribute (`None` when the element carries none, which is 221 of the reference's 234), and the
-/// section carry-forward and the `BINDING_HEADER_` prefixing happen where the addon's identity is
-/// known — [`crate::script::UiScript::register_addon_bindings`]. (`None` for 215 of the
-/// reference's 228 rows, which is what makes the carry-forward the whole story rather than a
-/// detail.)
+/// One `<Binding>` element as the file states it; the section carry-forward and the
+/// `BINDING_HEADER_` prefix are applied by [`crate::script::UiScript::register_addon_bindings`].
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AddonBinding {
-    /// The `name` attribute — the command name `SetBinding`/`GetBindingKey` speak in.
+    /// The command name `SetBinding` and `GetBindingKey` speak in.
     pub name: String,
-    /// The `header` attribute's global-string *suffix* (`MOVEMENT` → `BINDING_HEADER_MOVEMENT`),
-    /// when this element opens a section.
+    /// The raw `header` suffix (`MOVEMENT` of `BINDING_HEADER_MOVEMENT`), opening a section.
     pub header: Option<String>,
-    /// `runOnUp="true"` — the body runs on the press **and** on the release (see the module doc).
+    /// `runOnUp="true"`: the body runs on press and on release.
     pub run_on_up: bool,
-    /// `hidden="true"` — bindable and dispatchable, but not listed in the Key Bindings window.
+    /// `hidden="true"`: bindable, but not listed in the Key Bindings window.
     pub hidden: bool,
-    /// `platform="mac"` — the row belongs to one build only, lower-cased. `None` on every row
-    /// that carries no such attribute, which is every row but five.
+    /// `platform=`, lower-cased: the one build the row belongs to.
     pub platform: Option<String>,
-    /// The element's own text: one Lua chunk, verbatim (entities already decoded, so a body that
-    /// wrote `&lt;` arrives as `<`).
+    /// The element's own text, one Lua chunk, entities decoded (`&lt;` arrives as `<`).
     pub body: String,
 }
 
-/// A malformed document. Everything softer — an element with no `name`, an unknown attribute, an
-/// unexpected root — is tolerated the way the real loader tolerates it; only bytes that are not
-/// XML stop the file.
+/// Bytes that are not XML. A nameless element, an unknown attribute or an unexpected root is
+/// tolerated, as the reference's loader tolerates them.
 #[derive(Debug)]
 pub enum Error {
     Xml(roxmltree::Error),
@@ -123,23 +53,13 @@ impl std::error::Error for Error {
     }
 }
 
-/// Parse `Bindings.xml` text into its bindings, in document order.
-///
-/// **Every `<Binding>` under the root**, at any depth and matched case-insensitively like every
-/// other element compare in this crate (`0x64a4c0`, see [`crate::framexml`]'s header). The shipped
-/// root is `<Bindings>` and the elements are its direct children, but a descendant walk costs
-/// nothing and cannot over-collect — a `<Binding>` never nests — while it does keep an addon that
-/// wraps its bindings in a `<Ui>` root (or ships them inside a `<Bindings>` inside one) working.
-///
-/// **A `<Binding>` with no `name` is skipped**: there is nothing for `SetBinding` to name and
-/// nothing for the reference's record to key on. Defensive rather than observed — all 228 of the
-/// client's own are named.
+/// Parse `Bindings.xml` text into its bindings, in document order: every `<Binding>` at any
+/// depth, the tag matched case-insensitively (`0x64a4c0`), skipping one with no `name`. The
+/// reference reads only the root's children (`0x4b701f`) and also skips a row with an empty body
+/// (`0x4b7093`–`0x4b709e`) or `debug="true"` (`0x4b70a4`–`0x4b70bd`), which this keeps.
 pub fn parse(text: &str) -> Result<Vec<AddonBinding>, Error> {
-    // Namespace-oblivious, like the FrameXML document layer beside it and for the same reason
-    // (decision 2155; `framexml::parse`'s comment is the mechanism): a `Bindings.xml` is read by
-    // the same `XMLTree.cpp` tree the client builds with expat's `XML_ParserCreate`, which has no
-    // namespace processing at all — so an undeclared prefix cannot be an error there, and must not
-    // cost the whole file here.
+    // The reference's expat has no namespace processing, so an undeclared prefix is bound and the
+    // text re-read rather than costing the file, as in `framexml::parse`.
     let repaired;
     let doc = match roxmltree::Document::parse(text) {
         Ok(doc) => doc,
@@ -171,25 +91,21 @@ pub fn parse(text: &str) -> Result<Vec<AddonBinding>, Error> {
     Ok(out)
 }
 
-/// Case-insensitive attribute lookup — Blizzard's own XML is inconsistent about attribute casing
-/// and the real loader's `GetAttribute 0x6f2cf0` folds case ([`crate::framexml`]).
+/// Case-insensitive attribute lookup, as the reference's `GetAttribute 0x6f2cf0` folds case.
 fn attr_ci(node: roxmltree::Node, name: &str) -> Option<String> {
     node.attributes()
         .find(|a| a.name().eq_ignore_ascii_case(name))
         .map(|a| a.value().to_string())
 }
 
-/// A boolean attribute: true **iff** present and equal to the literal `"true"`, case-insensitively
-/// — the client's own rule (`0x6f1b30`'s true-cmp; there is no `"false"` branch, so `runOnUp="1"`
-/// is false exactly as it is in the real loader).
+/// True only for a case-insensitive `"true"` (`0x6f1b30` has no `"false"` branch), so
+/// `runOnUp="1"` is false.
 fn attr_bool(node: roxmltree::Node, name: &str) -> bool {
     attr_ci(node, name).is_some_and(|v| v.eq_ignore_ascii_case("true"))
 }
 
-/// The node's own direct text/CDATA children, concatenated — the binding's Lua chunk. Does not
-/// descend into child elements, and so drops the `<!-- … -->` comments the shipped file is full
-/// of. Concatenation (rather than the first text node) is what keeps a body containing an entity
-/// whole: `a &lt; b` arrives from `roxmltree` as three text nodes.
+/// The node's direct text and CDATA, concatenated: `roxmltree` splits `a &lt; b` into three text
+/// nodes.
 fn direct_text(node: roxmltree::Node) -> String {
     node.children()
         .filter(|n| n.is_text())
@@ -201,15 +117,6 @@ fn direct_text(node: roxmltree::Node) -> String {
 mod tests {
     use super::*;
 
-    /// **The reference's own shape**, element for element: the `runOnUp` + `header` opener with a
-    /// multi-line `keystate` fork, a plain one-shot binding, a `hidden` debug toggle, and — the
-    /// one case a hand-written addon file actually hits — an entity inside a body.
-    ///
-    /// What this catches: a parser that reads only the first text node (the `&lt;` body comes back
-    /// truncated at the entity), one that treats `runOnUp="1"`/absent as true, one that swallows
-    /// the newlines a Lua chunk needs to stay a Lua chunk, and one that hands back the `header`
-    /// already prefixed (the prefixing is registration's job — a doubled
-    /// `BINDING_HEADER_BINDING_HEADER_MOVEMENT` is the failure that would follow).
     #[test]
     fn the_reference_shape_parses_attribute_for_attribute() {
         let binds = parse(
@@ -270,8 +177,7 @@ mod tests {
             "the body is a Lua chunk — its newlines are load-bearing"
         );
 
-        // A binding with no header of its own carries none: the section it belongs to is a
-        // property of the LIST, resolved at registration.
+        // Section membership is resolved at registration, not here.
         assert_eq!(binds[1].name, "JUMP");
         assert_eq!(binds[1].header, None);
         assert!(!binds[1].run_on_up);
@@ -279,23 +185,18 @@ mod tests {
         assert!(binds[2].hidden, "hidden=\"true\" is recorded, not dropped");
         assert!(!binds[2].run_on_up);
 
-        // Attribute name AND value fold case (the loader's own compares do); the entity is
-        // decoded and the body around it survives whole.
+        // Attribute names and values fold case; the entity decodes and the body stays whole.
         assert!(binds[3].run_on_up, "RUNONUP=\"TRUE\" is runOnUp");
         assert_eq!(binds[3].body.trim(), "if ( a < b ) then Probe(); end");
 
-        // ...but only the literal `true` is true — there is no `"false"` branch in the client's
-        // parse, so `"1"` is simply not it.
         assert!(
             !binds[4].run_on_up,
             "runOnUp=\"1\" is false: the client's bool compares against \"true\" alone"
         );
     }
 
-    /// A nameless `<Binding>` is skipped rather than registered under `""` — where it would eat
-    /// `GetBindingAction`'s "no command is bound to this key" answer, which IS the empty string.
-    /// A `<Binding>` nested under a wrapper element still counts, so an addon that wraps its
-    /// bindings does not silently lose them.
+    /// Registered under `""`, a nameless binding would shadow `GetBindingAction`'s empty answer
+    /// for an unbound key.
     #[test]
     fn nameless_bindings_are_skipped_and_nesting_is_tolerated() {
         let binds = parse(
@@ -312,11 +213,6 @@ mod tests {
         assert_eq!(binds[0].name, "PROBEWRAPPED");
     }
 
-    /// **A commented-out `<Binding>` is not a binding** — and this is not a hypothetical: the
-    /// client's own file carries the entire `MOVEVIEW*` family (six bindings) inside one XML
-    /// comment, which is the whole gap between the 234 elements a text search finds and the 228
-    /// the loader sees. Registering them would put six commands in the Key Bindings window that
-    /// the client does not have, each one a key a player could bind to nothing at all.
     #[test]
     fn a_commented_out_binding_is_not_a_binding() {
         let binds = parse(
@@ -339,9 +235,6 @@ mod tests {
         );
     }
 
-    /// Bytes that are not XML stop the file — the one hard error. The addon's other files have
-    /// already run by then (`Bindings.xml` loads after them, `0x51f400`), so the load path reports
-    /// this and carries on; what it must not do is silently register nothing.
     #[test]
     fn malformed_xml_is_an_error() {
         let e = parse("<Bindings><Binding name=\"X\"></Bindings>").expect_err("malformed");
diff --git a/crates/benilla-ui/src/civil.rs b/crates/benilla-ui/src/civil.rs
index c050a795..a919a1a7 100644
--- a/crates/benilla-ui/src/civil.rs
+++ b/crates/benilla-ui/src/civil.rs
@@ -1,14 +1,6 @@
-//! **The tree's one civil-time conversion** — broken-down UTC from an epoch second.
-//!
-//! It lives here because this crate already had to have one: 1.12's `date()` global is Lua 5.0's
-//! `os.date` hoisted, and the sandbox strips `os` ([`crate::script`]'s stdlib), so the calendar
-//! had to be written by hand. The screenshot writer is its second caller (decision 1487), and one
-//! correct closed form with two callers beats two hand-rolled loops.
-//!
-//! **UTC, deliberately, and it is a stated divergence wherever a caller wanted local time.** The
-//! workspace has no date dependency at all — every format crate in it is in-repo — and resolving a
-//! local offset needs a timezone source, not a different algorithm. `date()` records the same
-//! divergence for the same reason.
+//! Broken-down UTC time from an epoch second, the calendar behind `date()` and screenshot names.
+//! Deviation: UTC where the reference's callers use local time, because the workspace has no
+//! timezone source.
 
 /// Broken-down UTC time.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
@@ -27,12 +19,8 @@ pub struct Civil {
     pub yearday: u32,
 }
 
-/// Break an epoch second down into UTC fields.
-///
-/// The civil-from-days conversion is Howard Hinnant's, shifted to a March-based year so the leap
-/// day lands at the end and no month-length table is needed. Chosen over a hand-rolled loop
-/// because it is a known-correct closed form with no accumulation error, which matters for the
-/// "persisted last session, compared this session" use every corpus `date()` caller has.
+/// Break an epoch second down into UTC fields, by Howard Hinnant's civil-from-days: years count
+/// from month 3, so the leap day falls last and no month-length table is needed.
 pub fn from_unix(secs: i64) -> Civil {
     let days = secs.div_euclid(86_400);
     let rem = secs.rem_euclid(86_400);
@@ -55,7 +43,6 @@ pub fn from_unix(secs: i64) -> Civil {
     let month = if mp < 10 { mp + 3 } else { mp - 9 } as u32;
     let year = if month <= 2 { y + 1 } else { y };
 
-    // Day of the year, from the same conversion applied to Jan 1.
     let yearday = (days - days_from_civil(year, 1, 1) + 1) as u32;
     Civil {
         year,
@@ -69,7 +56,6 @@ pub fn from_unix(secs: i64) -> Civil {
     }
 }
 
-/// Days since the epoch for a civil date — the inverse of the above, used only for `yearday`.
 fn days_from_civil(y: i64, m: u32, d: u32) -> i64 {
     let y = if m <= 2 { y - 1 } else { y };
     let era = y.div_euclid(400);
@@ -80,8 +66,7 @@ fn days_from_civil(y: i64, m: u32, d: u32) -> i64 {
     era * 146_097 + doe - 719_468
 }
 
-/// Wall-clock seconds since the Unix epoch. Before the epoch is not a state a game client is in; a
-/// clock that somehow reports it clamps to 0 rather than raising inside an addon's file scope.
+/// Wall-clock seconds since the Unix epoch; a clock set before 1970 reads 0 rather than raising.
 pub fn unix_seconds() -> i64 {
     std::time::SystemTime::now()
         .duration_since(std::time::UNIX_EPOCH)
@@ -93,8 +78,7 @@ pub fn unix_seconds() -> i64 {
 mod tests {
     use super::*;
 
-    /// Four instants that between them cover the epoch itself, a leap day, a century boundary and
-    /// an ordinary afternoon — the cases a closed-form conversion gets wrong when it is wrong.
+    /// The epoch, an ordinary afternoon, a leap day and the eve of 2000.
     #[test]
     fn known_instants_break_down() {
         let cases = [
@@ -121,8 +105,7 @@ mod tests {
         }
     }
 
-    /// Before 1970 is not a state a client is in, but the arithmetic must not wrap into nonsense
-    /// if a clock reports it — `div_euclid`/`rem_euclid` are load-bearing here, not stylistic.
+    /// `div_euclid`/`rem_euclid` keep a second before 1970 from wrapping into nonsense.
     #[test]
     fn negative_seconds_stay_civil() {
         assert_eq!(
diff --git a/crates/benilla-ui/src/framexml.rs b/crates/benilla-ui/src/framexml.rs
index 7720333f..957e8e3a 100644
--- a/crates/benilla-ui/src/framexml.rs
+++ b/crates/benilla-ui/src/framexml.rs
@@ -1,44 +1,25 @@
-//! The FrameXML **document** layer (decision 0068): turns a `.xml` file's text into an owned,
-//! order-preserving tree, resolves `virtual`/`inherits` template expansion, and rewrites `$parent`
-//! name tokens. This is XML-tree semantics only — no widget instantiation (frame factories, anchor
-//! resolution, script compilation) and no Lua; those live in the layer above, which walks the tree
-//! this module produces.
-//!
-//! Ground truth is the real client's loader (`0x6edc00–0x6f3000`):
-//! - the file loader `0x6ede10` — the schema → frame-op interpretation, the full top-level +
-//!   per-element op map
-//! - `LoadChildFrames 0x76a060` — `<Frames>` / load-order (widget-layer concern; cited
-//!   here only for the "spliced before the instance's own nodes" ordering that also governs template
-//!   `<Frames>` children, which this module's generic child-concat already gets right)
-//! - `0x76c5b0` — the `$parent` substitution rule
-//!
-//! XML *parsing* is delegated plumbing in the reference too (an embedded expat); the schema→op map
-//! is its own — we use `roxmltree` rather than reproduce a tokenizer; only the schema→op
-//! interpretation below is transcribed from the reference.
+//! The FrameXML document layer: a `.xml` file's text as an owned, order-preserving tree, with
+//! `inherits` template expansion and `$parent` name substitution; no widgets and no Lua. It
+//! follows the reference's loader (`0x6edc00`–`0x6f3000`, the file loader `0x6ede10`), whose XML
+//! tokenizer is an embedded expat and ours `roxmltree`.
 
 use std::collections::{HashMap, HashSet};
 use std::fmt;
 
-/// An owned XML element: tag, attributes (order preserved — Blizzard XML attribute order is
-/// sometimes meaningful for authoring tools, and always useful for round-tripping/debugging), and
-/// element children. Case-insensitive attribute lookup: "attrs via `GetAttribute 0x6f2cf0`" and
-/// element-name compares are case-insensitive in the real loader (`0x64a4c0`), and Blizzard's own
-/// shipped XML is inconsistent about attribute casing (e.g. both `relativeTo` and stray
-/// all-lowercase variants appear in the wild), so lookups here fold case rather than assume a
-/// canonical spelling.
+/// An owned XML element, attributes in document order. Lookups fold case, as the reference's
+/// `GetAttribute 0x6f2cf0` and element-name compares (`0x64a4c0`) do.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Element {
     pub tag: String,
     attrs: Vec<(String, String)>,
     pub children: Vec<Element>,
-    /// The node's own direct text content (the XML node struct's `body-text @ +0xc`). Populated for
-    /// text-bearing elements such as `<Scripts>` handler bodies (`<OnLoad>lua…</OnLoad>`) and
-    /// inline `<Script>` bodies. Empty for purely structural elements.
+    /// The node's own direct text (the reference node's body text at `+0xc`): a handler or
+    /// `<Script>` body.
     pub body: String,
 }
 
 impl Element {
-    /// Case-insensitive attribute lookup (see struct docs).
+    /// Case-insensitive attribute lookup.
     pub fn attr(&self, name: &str) -> Option<&str> {
         self.attrs
             .iter()
@@ -46,92 +27,68 @@ impl Element {
             .map(|(_, v)| v.as_str())
     }
 
-    /// A boolean attribute (`hidden="true"`, `virtual="true"`, …): true iff present and equal to
-    /// the literal `"true"`, case-insensitively (`0x6f1b30`'s true-cmp).
-    /// Absent or any other value is false — matching the client (there is no explicit `"false"`
-    /// branch in the reference; only a `true` match flips the flag).
+    /// True only for a case-insensitive `"true"` (`0x6f1b30`); there is no `"false"` branch.
     pub fn attr_bool(&self, name: &str) -> bool {
         self.attr(name)
             .is_some_and(|v| v.eq_ignore_ascii_case("true"))
     }
 
-    /// The same, but **presence-aware** — `None` when the attribute is absent.
-    ///
-    /// [`attr_bool`](Self::attr_bool) folds "absent" and `="false"` together, which is fine for a
-    /// flag whose default is off and *silently wrong* for one whose default is on: it turns an
-    /// explicit opt-out into a no-op. `<EditBox autoFocus="false">` is exactly that flag, and the
-    /// shipped UI writes it ten times.
+    /// [`attr_bool`](Self::attr_bool), but `None` when absent, for a flag whose default is on
+    /// (`<EditBox autoFocus="false">`).
     pub fn attr_bool_opt(&self, name: &str) -> Option<bool> {
         self.attr(name).map(|v| v.eq_ignore_ascii_case("true"))
     }
 
-    /// The `name` attribute, if any.
     pub fn name(&self) -> Option<&str> {
         self.attr("name")
     }
 
-    /// All attributes, in document order, as written.
     pub fn attrs(&self) -> &[(String, String)] {
         &self.attrs
     }
 }
 
-/// A `<Script>` reference: an external file (`<Script file="…"/>`) or an inline body
-/// (`<Script>lua…</Script>`). Both run in document order relative to everything else at the top
-/// level (`0x704bc0` / `0x704cd0`, from `0x6ede10`'s walk — this is how XML-referenced FrameXML Lua
-/// loads).
+/// A `<Script file=…>` or an inline `<Script>` body; both run in document order with the rest of
+/// the top level (`0x704bc0`/`0x704cd0`, from `0x6ede10`'s walk).
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum ScriptRef {
     File(String),
     Inline {
         body: String,
-        /// The 1-based line **of this XML file** that `body`'s first character sits on.
-        ///
-        /// Carried so the loader can pad the chunk out to that offset, making Lua's own error
-        /// lines the file's lines. Without it every inline block starts at line 1 and a raise
-        /// reports a number belonging to no file — worse than no number, because it looks like one
-        /// you could go and read (decision 1214).
+        /// The 1-based line of the file that `body` starts on, so the loader can pad the chunk and
+        /// Lua's error lines are the file's.
         line: u32,
     },
 }
 
-/// One top-level item of a FrameXML document, in document order. Modeled as an order-preserving
-/// `Vec<TopLevel>` rather than a split `{ scripts, fonts, templates, instances }` struct because the
-/// real loader executes `<Include>`/`<Script>` interleaved with frame element definitions **in
-/// document order** (`0x6ede10`) — a split-by-kind struct would lose that
-/// order and misrepresent Lua load sequencing.
+/// One top-level item, kept in document order: the reference runs `<Include>` and `<Script>`
+/// interleaved with frame definitions (`0x6ede10`).
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum TopLevel {
-    /// `<Include file="…"/>` — recurse-load another file at this point in the sequence
-    /// (`0x8710c0`). File resolution/recursion is the loader
-    /// layer's job; this only preserves *where* the include happens relative to everything else.
+    /// `<Include file=…>`: load another file at this point (`0x8710c0`).
     Include(String),
     Script(ScriptRef),
-    /// `<Font …>` — a named font definition (`0x87106c`).
+    /// `<Font …>`, a named font definition (`0x87106c`).
     Font(Element),
-    /// A frame/region element with `virtual="true"`: registered as a template keyed by `name`, not
-    /// instantiated (`0x6ee500`).
+    /// An element with `virtual="true"`: a template keyed by `name`, not instantiated
+    /// (`0x6ee500`).
     Template(Element),
-    /// A frame/region element without `virtual="true"`: instantiated in place.
+    /// An element without `virtual="true"`: instantiated in place.
     Instance(Element),
 }
 
-/// The result of parsing one FrameXML document: its top-level items in order, plus any tolerable
-/// issues found along the way.
+/// One parsed document: its top-level items in order, and the issues it loaded past.
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct ParsedDocument {
     pub items: Vec<TopLevel>,
-    /// Tolerable issues: unregistered (unnamed) virtual templates, missing `Include`/`Font`
-    /// attributes, a non-`<Ui>` root, and similar — the real client logs and continues rather than
-    /// aborting the whole file for these, so parsing does too (see [`parse`]'s docs).
+    /// An unnamed virtual, an `<Include>` or `<Font>` missing its attribute, a root that is not
+    /// `<Ui>`: logged, and the file goes on.
     pub warnings: Vec<String>,
 }
 
 impl ParsedDocument {
-    /// All registered templates, keyed by name, for use with [`expand`]. A [`TopLevel::Template`]
-    /// with no `name` (already flagged in [`ParsedDocument::warnings`] at parse time — an
-    /// "Unnamed virtual node" load error in the real client, `0x6ee500`) is simply
-    /// absent here, matching the fact that nothing can `inherits=` it.
+    /// The named templates, for [`expand`]; an unnamed one (the reference's "Unnamed virtual
+    /// node" error, `0x6ee500`) is absent.
     pub fn templates(&self) -> HashMap<&str, &Element> {
         self.items
             .iter()
@@ -143,8 +100,7 @@ impl ParsedDocument {
     }
 }
 
-/// A document parse error: malformed XML. Tolerable issues (unknown tags, missing optional
-/// attributes, an unregistrable template) are not errors — see [`ParsedDocument::warnings`].
+/// Malformed XML; anything softer is a [`ParsedDocument::warnings`] entry.
 #[derive(Debug)]
 pub enum Error {
     Xml(roxmltree::Error),
@@ -166,44 +122,16 @@ impl std::error::Error for Error {
     }
 }
 
-/// Parse FrameXML document text into an owned, order-preserving tree.
-///
-/// Top-level semantics (`0x6ede10`): the root's children are walked in
-/// order; `<Include file=>` and `<Script file=>`/inline `<Script>` are preserved as-is (their
-/// execution is the loader layer's job — this only fixes their position); `<Font>` becomes a font
-/// definition; any other element with `virtual="true"` registers as a template (by `name`); anything
-/// else is an instance. Unknown top-level tags (not one of the 13 known frame-element types) are
-/// kept as generic [`Element`]s and classified the same way (template if `virtual="true"`, else
-/// instance) — the real client's loader tolerates them the same way (widget-type validation happens
-/// later, at instantiation, which is out of this module's scope).
-///
-/// A root element that isn't (case-insensitively) `<Ui>` is tolerated with a warning, not a hard
-/// error: nothing establishes that the loader checks the root's own tag name, only that it walks
-/// its children (`0x6ede10`).
+/// Parse FrameXML text. As in `0x6ede10`, the root's children are walked in order: `<Include>`
+/// and `<Script>` keep their place, `<Font>` is a font, and any other element, known tag or not,
+/// is a template when `virtual="true"` and an instance otherwise; widget types are checked at
+/// instantiation. A root that is not `<Ui>` only warns: the reference's walk is not known to check
+/// the root's tag.
 pub fn parse(text: &str) -> Result<ParsedDocument, Error> {
-    // **The reference has no XML Namespaces, and our stand-in parser does** (decision 2155).
-    //
-    // The client's document tree is `XMLTree.cpp`'s, built by embedded **expat 1.95.5** created
-    // through `XML_ParserCreate 0x7e6690` — *not* `XML_ParserCreateNS` — so namespace processing
-    // is off: a prefix is opaque bytes inside the attribute's name, an `xmlns:` declaration is an
-    // ordinary attribute, and an *undeclared* prefix cannot be an error because nothing is
-    // resolving one. The node struct the FrameXML loader walks is that same tree (name `@+0x8`,
-    // the `{char*, char*}` attribute array `@+0x14`, looked up by `GetAttribute 0x6f2cf0`'s linear
-    // case-insensitive scan).
-    //
-    // `roxmltree` is namespace-aware and has no switch for it, so it refuses
-    // `<Ui xsi:schemaLocation="…">` with `UnknownNamespace` when the file never declares
-    // `xmlns:xsi` — and takes the **whole document** with it. That is not a rare authoring slip:
-    // Auctioneer writes exactly that line at the top of all five of its UI documents and
-    // BeanCounter includes two of them, so the Auction House replacement lost its entire interface
-    // to a concept the client it targets does not implement.
-    //
-    // So a namespace error is answered by giving the parser the binding it wants and re-reading —
-    // driven by the prefix the error itself names, never by scanning the text for colons (which
-    // would fire inside comments, CDATA and attribute values). The document's own bytes are
-    // otherwise untouched, and [`element_from_node`] drops every prefixed attribute, so nothing
-    // downstream can see the difference between a repaired document and one that never had a
-    // prefix.
+    // The reference's expat is created by `XML_ParserCreate 0x7e6690`, not the NS variant, so a
+    // prefix is opaque and an undeclared one (`xsi:` with no `xmlns:xsi`) is no error, where
+    // `roxmltree` rejects the whole document. Bind the prefix the error names and re-read; the
+    // bytes are otherwise untouched, and `element_from_node` drops prefixed attributes.
     let repaired;
     let doc = match roxmltree::Document::parse(text) {
         Ok(doc) => doc,
@@ -267,22 +195,10 @@ pub fn parse(text: &str) -> Result<ParsedDocument, Error> {
     Ok(ParsedDocument { items, warnings })
 }
 
-/// Declare every prefix the document uses but never binds, so a namespace-aware parser stops
-/// having an opinion the reference's parser cannot have (decision 2155; the *why* is in
-/// [`parse`]).
-///
-/// **Driven by the parser's own error, not by a scan.** `roxmltree` names the offending prefix in
-/// `UnknownNamespace`, so each round adds exactly that one binding to the ROOT element's start tag
-/// — where a declaration is in scope for the whole document, including the root's own name — and
-/// re-parses. A text scan for `name:` would fire inside comments, CDATA and attribute values
-/// (`Interface\AddOns\…` and `$Id:` lines are everywhere in this corpus), and would have to
-/// re-implement the tokenizer to avoid it.
-///
-/// Bounded, and honest when it gives up: a document that keeps naming new prefixes stops after
-/// [`MAX_BOUND_PREFIXES`] rounds and the text is returned as it stands, so [`parse`] reports the
-/// parser's real error rather than looping. A document whose error is something else on the retry
-/// (a genuinely malformed file that also has a stray prefix) reports that error, which is the one
-/// worth reading.
+/// Declare each prefix the document uses but never binds, one per round on the root's start tag
+/// (in scope everywhere, the root's own name included), taking the prefix each
+/// `UnknownNamespace` error names, never a text scan, which would match inside comments and
+/// values. Any other error, or [`MAX_BOUND_PREFIXES`] rounds, returns the text as it stands.
 pub(crate) fn bind_undeclared_prefixes(text: &str) -> String {
     let mut out = text.to_string();
     for _ in 0..MAX_BOUND_PREFIXES {
@@ -293,9 +209,7 @@ pub(crate) fn bind_undeclared_prefixes(text: &str) -> String {
         let Some(at) = root_attr_insertion_point(&out) else {
             return out;
         };
-        // The URI is inert and never read: nothing downstream resolves a namespace, and
-        // `element_from_node` drops prefixed attributes outright. It only has to be *a* URI, and
-        // distinct per prefix so two stray prefixes are not silently the same namespace.
+        // An inert URI, distinct per prefix so two stray prefixes stay two namespaces.
         out.insert_str(
             at,
             &format!(" xmlns:{prefix}=\"urn:benilla:undeclared:{prefix}\""),
@@ -304,20 +218,12 @@ pub(crate) fn bind_undeclared_prefixes(text: &str) -> String {
     out
 }
 
-/// How many distinct undeclared prefixes [`bind_undeclared_prefixes`] will bind before it stops.
-///
-/// Generous against the real cause (one file, one stray `xsi:`) and small enough that a
-/// pathological document cannot turn a failed parse into a long loop.
+/// The most undeclared prefixes [`bind_undeclared_prefixes`] binds before giving up.
 const MAX_BOUND_PREFIXES: usize = 8;
 
-/// The byte offset inside the ROOT element's start tag at which a new attribute may be inserted —
-/// just before the `>` or `/>` that closes it.
-///
-/// Walks the prolog by hand rather than parsing, because the document by definition does not parse
-/// at this point: `<?…?>`, `<!--…-->` and `<!…>` are skipped, and the first remaining `<` opens the
-/// root. Inside that tag, `'` and `"` runs are stepped over whole, so a `>` living in an attribute
-/// value (`hyperlinkFormat="|H%s|h[%s]|h"` is the shape that exists in this corpus) cannot be
-/// mistaken for the tag's end.
+/// The byte offset just before the `>` or `/>` closing the root's start tag, found by hand since
+/// the document does not parse yet: the prolog is skipped and quoted values are stepped over, so
+/// a `>` inside one (`hyperlinkFormat="|H%s|h[%s]|h"`) is not the tag's end.
 fn root_attr_insertion_point(text: &str) -> Option<usize> {
     let b = text.as_bytes();
     let mut i = 0usize;
@@ -334,7 +240,7 @@ fn root_attr_insertion_point(text: &str) -> Option<usize> {
         } else if rest.starts_with("<!") {
             i += rest.find('>').map(|n| n + 1)?;
         } else {
-            // The root's start tag. Step over quoted runs so a `>` inside a value is not its end.
+            // The root's start tag.
             let mut j = i + 1;
             while j < b.len() {
                 match b[j] {
@@ -365,14 +271,8 @@ fn attr_ci(node: roxmltree::Node, name: &str) -> Option<String> {
         .map(|a| a.value().to_string())
 }
 
-/// Concatenates a node's own direct text/CDATA children (not descending into child elements) —
-/// the XML node struct's `body-text @ +0xc`.
-/// The 1-based line of the first text byte inside a `<Script>` element.
-///
-/// Taken from the first text child's own range rather than the element's, because a CDATA section
-/// puts `<![CDATA[` between the two and every FrameXML script block in this project uses one — the
-/// element's start line would be off by however much of the opening tag precedes the body.
-/// Falls back to the element's line for a `<Script></Script>` with no text at all.
+/// The 1-based line of the first text byte inside a `<Script>`: the first text child's, since
+/// `<![CDATA[` can sit between the tag and the body, else the element's own.
 fn inline_start_line(doc: &roxmltree::Document, node: roxmltree::Node) -> u32 {
     let at = node
         .children()
@@ -395,13 +295,9 @@ fn element_from_node(node: roxmltree::Node) -> Element {
         tag: node.tag_name().name().to_string(),
         attrs: node
             .attributes()
-            // **A prefixed attribute is unreachable in the reference, so it is not an attribute
-            // here** (decision 2155). `GetAttribute 0x6f2cf0` compares a lookup key against the
-            // stored name whole, and no FrameXML attribute name contains a colon — so
-            // `xsi:schemaLocation` can never match any key the loader asks for. Dropping it is
-            // what keeps a *declared* prefix (stock FrameXML's own `<Ui xmlns:xsi=… xsi:schema
-            // Location=…>`) and an *undeclared* one (Auctioneer's) behave identically, and stops
-            // `roxmltree`'s local-name view from making `xsi:name` answer a lookup for `name`.
+            // `GetAttribute 0x6f2cf0` matches the whole stored name and no FrameXML key has a
+            // colon, so a prefixed attribute is unreachable; dropping it also stops `roxmltree`'s
+            // local names from letting `xsi:name` answer for `name`.
             .filter(|a| a.namespace().is_none())
             .map(|a| (a.name().to_string(), a.value().to_string()))
             .collect(),
@@ -414,38 +310,12 @@ fn element_from_node(node: roxmltree::Node) -> Element {
     }
 }
 
-/// Resolve `inherits="A, B"` template references into a fully materialized [`Element`]: a
-/// structural merge with inherited content first, the element's own content last.
-///
-/// **Splice order** (in the reference, a matched template's stored attribute/child nodes are
-/// spliced in first, then the instance's own nodes are read on top; `LoadChildFrames 0x76a060`
-/// keeps the same "inherited-first" ordering for a template's own `<Frames>` children) — so:
-/// - **children**: the (fully expanded) template's children first, in order, then the element's own
-///   children appended after.
-/// - **attributes**: the template's attributes, with the element's own attributes overriding any
-///   attribute of the same name (case-insensitively) and adding any the template didn't have. This
-///   is the literal reading of "spliced in first, then the instance's own" applied to attributes —
-///   note this means an element that omits `name` entirely while inheriting a *named* template would
-///   inherit that template's registration name, and `virtual="true"`/`inherits="…"` themselves are
-///   ordinary attributes that splice through too (harmlessly inert post-expansion: nothing reads
-///   them again after the one-time top-level virtual/instance routing decision, which already
-///   happened on the *outer* node before expansion ever runs). Real FrameXML avoids ever hitting the
-///   `name` case (instances either supply their own name or stay anonymous), and no
-///   `name`/`virtual` exception is established for the reference, so this implementation does not
-///   special-case them — flagged as an unverified edge case, not a silent guess.
-///
-/// **Multiple `inherits`** (`"A, B"`, comma-separated, left-to-right): each named template is
-/// resolved and merged in order, so `B`'s content lands on top of `A`'s where they overlap, and the
-/// element's own content lands on top of both. Multi-template precedence is not established from
-/// the reference; left-to-right precedence (later name wins ties) is the natural reading
-/// and is what this function implements — flagged, not guessed silently, since it isn't
-/// byte-verified for the multi-name case specifically.
-///
-/// **Chains** (a template inheriting another template) recurse: each named template is itself fully
-/// expanded (its own `inherits` resolved) before being merged in.
-///
-/// **Cycles** are guarded: if expanding a chain would re-enter a template already being expanded,
-/// that reference is skipped and a warning is appended instead of infinite-recursing.
+/// Resolve `inherits` into a materialized [`Element`]: the named template, itself expanded first,
+/// then the element on top, as the reference splices a template's nodes before the instance's
+/// own (`LoadChildFrames 0x76a060` keeps that order for `<Frames>`). Children are the template's
+/// then the element's; the element's attributes override or extend the template's
+/// (case-insensitively). `name` and `virtual` splice like any attribute; whether the reference
+/// exempts them is untraced. A cycle is skipped with a warning.
 pub fn expand(
     element: &Element,
     templates: &HashMap<&str, &Element>,
@@ -454,14 +324,8 @@ pub fn expand(
     expand_known(element, templates, &HashSet::new(), warnings)
 }
 
-/// [`expand`], plus the names that are known to be **font objects** rather than element templates.
-///
-/// A `<FontString inherits="GameFontNormalSmall">` names a font, not a template, and the font is
-/// applied later by its own path (`apply_fontstring_font`) — so the name must be skipped here
-/// silently rather than warned as unknown. `Loader::expand_region` already made that distinction
-/// for an INSTANCE; it could not make it one level down, and stock `BuffFrame.xml` is exactly that
-/// case: `BuffButtonDurationTemplate` is a virtual `<FontString>` that inherits a font object, so
-/// every instance of it warned twenty-six times over (decision 1874).
+/// [`expand`], skipping without a warning an `inherits` that names a font object: a
+/// `<FontString inherits="GameFontNormalSmall">` takes a font, applied later, not a template.
 pub fn expand_known(
     element: &Element,
     templates: &HashMap<&str, &Element>,
@@ -483,25 +347,10 @@ fn expand_inner(
         return element.clone();
     };
 
-    // ── ONE name, matched case-INSENSITIVELY (template-name lookup `0x6ee6f0`) ─────────────────
-    //
-    // **No comma splitting.** 1.12's registry lookup `0x6ee6f0` has no splitter at all:
-    // `inherits="A, B"` is ONE literal name, misses, and applies neither template. Supporting the
-    // list is what LATER clients do, so splitting here made us a superset of 1.12 (1189). Nothing
-    // uses it — 0 comma lists in our own assets, 0 across the 218-addon corpus, and 0 in stock
-    // Blizzard XML's 249 distinct `inherits=` values.
-    //
-    // **Case-insensitive.** The compare is `SStrCmpI` → `_strnicmp` at `0x6ee747`, and the trap
-    // that decides it is the BUCKET HASH: `SStrHash 0x64b3f0` uppercases before mixing, so a
-    // mis-cased name lands in the same bucket and the stored-hash pre-check passes rather than
-    // short-circuiting. `Recap`'s `inherits="UIDropdownMenuTemplate"` (lowercase d) resolves on the
-    // real client. ASCII-only, like every other fold in this engine — bytes >= 0x80 are untouched.
-    //
-    // The fold is done as a scan on miss rather than by re-keying the view, because this same
-    // function resolves the FONT registry too and both are name→element maps of the same shape.
-    // Verbatim — not trimmed. `GetAttribute 0x6f2cf0` returns the parsed value as expat stored it
-    // (`SStrDup`, no trim, no fold), and the empty test is a single `cmp [esi],0` on the first
-    // byte: `inherits=""` is a silent skip, `inherits=" "` is a lookup that misses.
+    // `inherits` is one name, not a list: `0x6ee6f0` has no splitter, so `"A, B"` misses (later
+    // clients split it). It is used verbatim (`GetAttribute 0x6f2cf0` does not trim; `""` is
+    // skipped, `" "` misses) and matched case-insensitively, ASCII only: `_strnicmp` at
+    // `0x6ee747`, reached despite a mis-cased name because `SStrHash 0x64b3f0` uppercases.
     let mut base: Option<Element> = None;
     for name in [inherits].into_iter().filter(|s| !s.is_empty()) {
         if !active.insert(name.to_string()) {
@@ -517,8 +366,7 @@ fn expand_inner(
                 .map(|(_, v)| *v)
         });
         let Some(template) = hit else {
-            // A FONT OBJECT is not an unknown template: it is a different namespace, applied by
-            // `apply_fontstring_font` after this. Skip it without a word (1874).
+            // A font object is not an unknown template; it is applied after this.
             if !fonts.contains(name) {
                 warnings.push(format!(
                     "unknown template '{name}' referenced by inherits; skipping"
@@ -541,10 +389,7 @@ fn expand_inner(
     }
 }
 
-/// The structural merge documented on [`expand`]: `base`'s children first, `over`'s appended after;
-/// `over`'s attributes override `base`'s of the same name (case-insensitive), and are added if
-/// `base` didn't have them. `over`'s tag and body win (an instance's own tag/handler body, if any,
-/// is what actually runs).
+/// [`expand`]'s merge; `over`'s tag wins, and its body when it has one.
 fn merge(base: &Element, over: &Element) -> Element {
     let mut attrs = base.attrs.clone();
     for (k, v) in &over.attrs {
@@ -570,19 +415,9 @@ fn merge(base: &Element, over: &Element) -> Element {
     }
 }
 
-/// The synthetic element a **runtime** `CreateFrame(kind, name, parent, "A, B")` expands: a bare
-/// node of the caller's own `tag` carrying nothing but the `inherits=` list.
-///
-/// Handing this to [`expand`] is what makes the Lua path and the XML path *the same* path — one
-/// comma-split, one chain resolution, one cycle guard, one unknown-template warning, one splice
-/// order. Nothing about `inherits=` is written twice.
-///
-/// And because [`merge`] takes the **overriding** node's tag, the expanded result carries `tag` —
-/// the kind `CreateFrame` was actually given — whatever the templates were declared as. That is
-/// the honest answer to `CreateFrame("Frame", n, p, "SomeButtonTemplate")`: the frame already
-/// exists as a Frame, so the template's `<Button>` tag cannot retype it, and the loader's per-kind
-/// passes (which every one of them gate on the element tag) skip the parts that could not apply
-/// anyway.
+/// The bare node a runtime `CreateFrame(kind, name, parent, inherits)` expands through
+/// [`expand`], so Lua and XML resolve `inherits` alike. The result keeps `tag`, the kind
+/// `CreateFrame` was given: a template's `<Button>` cannot retype a `"Frame"`.
 pub fn inherits_node(tag: &str, inherits: &str) -> Element {
     Element {
         tag: tag.to_string(),
@@ -592,31 +427,15 @@ pub fn inherits_node(tag: &str, inherits: &str) -> Element {
     }
 }
 
-/// The literal fallback base name: when a `$parent`-prefixed name has no named ancestor to
-/// substitute (e.g. a top-level element), the real client seeds the result with the literal string
-/// `"Top"` (VA `0x8788ac`) rather than leaving the token literal, erroring, or producing an empty
-/// name.
+/// What `$parent` expands to with no named ancestor: the literal `"Top"` (`0x8788ac`).
 pub const DEFAULT_PARENT_NAME: &str = "Top";
 
-/// `$parent` name-token substitution (`0x76c5b0`).
-///
-/// A `name` attribute beginning, **case-insensitively**, with the literal `"$parent"` (the
-/// compare folds `A`–`Z`; `$Parent`/`$PARENT` all match — the *only* such token, there is no
-/// `$parentKey`/`$parentN` variant) has that 7-character prefix replaced with
-/// `parent_name`, and the remainder of `raw` appended verbatim (`SStrCat`). A `name` not starting
-/// with the token is copied through unchanged.
-///
-/// `parent_name` must be the caller's **already-resolved** name for the nearest ancestor that has
-/// one — i.e. the caller walks the ancestor chain (`this+0x9c`) for the first ancestor
-/// whose own (already-substituted) name is non-empty, and passes [`DEFAULT_PARENT_NAME`] (`"Top"`)
-/// if there is none. Passing the already-resolved name (not the raw ancestor `name=` attribute
-/// text) is what makes nested `$parent` chains compose: a child of a
-/// `$parent`-named parent inherits the parent's fully-resolved name, e.g. parent `PlayerFrame` +
-/// `"$parentHealthBar"` → `"PlayerFrameHealthBar"`, and a grandchild's `"$parentBar"` resolves
-/// against `"PlayerFrameHealthBar"`, not against the literal text `"$parentHealthBar"`.
-///
-/// Applies only to the `name` attribute — `parent=` (which *resolves* the enclosing
-/// frame) is never `$parent`-substituted, and no other attribute is either.
+/// `$parent` substitution (`0x76c5b0`): a leading `$parent`, case-insensitive and the only such
+/// token, becomes `parent_name`, the rest appended verbatim. `parent_name` is the already-resolved
+/// name of the nearest named ancestor (the `+0x9c` walk), else [`DEFAULT_PARENT_NAME`], so nested
+/// `$parent` names compose. The reference calls it from two sites only, in `SetName` (`0x76c691`)
+/// and in the layout resolver `0x76c700` (`0x76c71c`): a name and an anchor's `relativeTo` (XML,
+/// `SetPoint` or `SetAllPoints`) expand, and `parent=` never does.
 pub fn resolve_name(raw: &str, parent_name: &str) -> String {
     const TOKEN: &str = "$parent";
     match raw.get(..TOKEN.len()) {
@@ -631,15 +450,6 @@ pub fn resolve_name(raw: &str, parent_name: &str) -> String {
 mod tests {
     use super::*;
 
-    /// **An undeclared namespace prefix is not an error, because the reference has no namespaces**
-    /// (decision 2155). The client's tree is `XMLTree.cpp`'s, built by expat 1.95.5 through
-    /// `XML_ParserCreate 0x7e6690` — never `XML_ParserCreateNS` — so nothing is resolving a prefix
-    /// and nothing can find one unbound.
-    ///
-    /// The literal line is Auctioneer's, at the top of all five of its UI documents (and two of
-    /// them are `<Include>`d by BeanCounter): a `roxmltree` `UnknownNamespace` there cost the
-    /// Auction House replacement its entire interface, an element at a time, to a concept the
-    /// client it targets does not implement.
     #[test]
     fn an_undeclared_namespace_prefix_does_not_cost_the_document() {
         let doc = parse(
@@ -655,9 +465,7 @@ mod tests {
         assert_eq!(el.name(), Some("Survived"));
     }
 
-    /// Two stray prefixes, and one of them on an ELEMENT rather than an attribute — the binding
-    /// goes on the root, where it is in scope for the whole document including the root's own
-    /// name, and the retry loop is driven by the parser naming each prefix in turn.
+    /// One stray prefix is on an element, not an attribute.
     #[test]
     fn several_undeclared_prefixes_are_all_bound() {
         let doc = parse(
@@ -670,10 +478,7 @@ mod tests {
         assert_eq!(doc.items.len(), 2);
     }
 
-    /// **A prefixed attribute is not an attribute** — `GetAttribute 0x6f2cf0` compares a lookup key
-    /// against the stored name whole, and no FrameXML key contains a colon, so `xsi:name` can never
-    /// answer a lookup for `name`. Asserted on a *declared* prefix as well, because stock FrameXML
-    /// writes one on every `<Ui>` and the two spellings must behave identically.
+    /// Both spellings, since stock FrameXML declares `xmlns:xsi` on every `<Ui>`.
     #[test]
     fn a_prefixed_attribute_never_answers_an_unprefixed_lookup() {
         for text in [
@@ -691,16 +496,11 @@ mod tests {
         }
     }
 
-    /// A genuinely malformed document still fails — the repair answers `UnknownNamespace` and
-    /// nothing else, so a mismatched tag is still the error a reader gets.
     #[test]
     fn a_malformed_document_still_fails_with_its_own_error() {
         assert!(parse(r#"<Ui xsi:a="b"><Frame></Ui>"#).is_err());
     }
 
-    /// The insertion point is found in the ROOT's start tag, past a prolog and past a `>` that
-    /// lives inside an attribute value — the shape `hyperlinkFormat="|H%s|h[%s]|h"` has in this
-    /// corpus, and the reason this walks quotes rather than searching for the first `>`.
     #[test]
     fn the_root_tag_is_found_past_a_prolog_and_a_quoted_angle_bracket() {
         let doc = parse(
@@ -709,7 +509,7 @@ mod tests {
         )
         .unwrap();
         assert_eq!(doc.items.len(), 1);
-        // …and a self-closing root: the attribute goes before the slash, not between it and `>`.
+        // A self-closing root: the binding goes before the slash.
         assert!(parse(r#"<Ui xsi:a="b"/>"#).is_ok());
     }
 
@@ -832,17 +632,8 @@ print(x)</Script>
         assert!(doc.warnings.is_empty());
     }
 
-    /// `inherits="A, B"` is **one name**, not a list — and it misses.
-    ///
-    /// This test used to assert the opposite (that both templates merged, children concatenated in
-    /// order). That was a superset of 1.12 borrowed from later clients: there is no splitter
-    /// anywhere in the loader — all 8 call sites hand `0x6ee6f0` the pointer `GetAttribute`
-    /// returned, one or two instructions later, and no comma is examined in `0x6ed000–0x6f6000` at
-    /// all. So the lookup runs **once**, for the literal name `"A, B"`, misses, warns at
-    /// severity 1, and the element loads with **neither** template applied.
-    ///
-    /// Whitespace is never trimmed either, which is why the second half asserts `" A "` misses a
-    /// template that genuinely exists.
+    /// All eight callers of `0x6ee6f0` pass `GetAttribute`'s pointer as is, and nothing in
+    /// `0x6ed000`–`0x6f6000` examines a comma; the value is not trimmed either.
     #[test]
     fn a_comma_list_is_one_literal_name_that_misses_and_applies_neither_template() {
         let doc = parse(
@@ -867,14 +658,13 @@ print(x)</Script>
         let mut warnings = Vec::new();
         let expanded = expand(inst, &templates, &mut warnings);
 
-        // Warned, naming the whole unsplit string — not split, not silently ignored.
         assert_eq!(warnings.len(), 1, "{warnings:?}");
         assert!(
             warnings[0].contains("A, B"),
             "the warning must name the literal it looked up: {warnings:?}"
         );
 
-        // The element still loads, with all of its OWN content and none of the templates'.
+        // The element loads with its own content only.
         assert_eq!(expanded.attr("alpha"), Some("1.0"));
         assert_eq!(expanded.children.len(), 1);
         fn texture_name(el: &Element) -> &str {
@@ -882,7 +672,7 @@ print(x)</Script>
         }
         assert_eq!(texture_name(&expanded.children[0]), "FromInst");
 
-        // And a padded name misses a template that exists — the value is used verbatim.
+        // A padded name misses: the value is used verbatim.
         let TopLevel::Instance(padded) = &doc.items[3] else {
             panic!("expected instance")
         };
@@ -916,8 +706,7 @@ print(x)</Script>
         let mut warnings = Vec::new();
         let expanded = expand(leaf, &templates, &mut warnings);
         assert!(warnings.is_empty());
-        // Mid's own frameStrata (it overrode Root's) wins, since chain-expanding Mid resolves Root
-        // first and Mid's own attrs on top, before Leaf (which sets nothing) merges on top of that.
+        // Mid's frameStrata overrides Root's, and Leaf sets none.
         assert_eq!(expanded.attr("frameStrata"), Some("MEDIUM"));
         assert_eq!(
             expanded.children.len(),
@@ -941,7 +730,6 @@ print(x)</Script>
             panic!("expected instance")
         };
         let mut warnings = Vec::new();
-        // Must terminate (not infinitely recurse) and report the cycle.
         let _expanded = expand(inst, &templates, &mut warnings);
         assert!(
             warnings.iter().any(|w| w.contains("cycle")),
@@ -964,14 +752,13 @@ print(x)</Script>
             resolve_name("NotAParentName", "PlayerFrame"),
             "NotAParentName"
         );
-        // No named ancestor: caller passes the literal "Top" fallback.
+        // No named ancestor: the caller passes the literal "Top".
         assert_eq!(resolve_name("$parentFoo", DEFAULT_PARENT_NAME), "TopFoo");
     }
 
     #[test]
     fn parent_name_substitution_composes_through_nested_children() {
-        // A named parent, a child using $parent, and a grandchild using $parent against the
-        // child's *resolved* name — not the child's raw literal "$parent..." text.
+        // The grandchild resolves against the child's resolved name, not its raw "$parent…" text.
         let parent_name = "PlayerFrame";
         let child_name = resolve_name("$parentHealthBar", parent_name);
         assert_eq!(child_name, "PlayerFrameHealthBar");
diff --git a/crates/benilla-ui/src/justify.rs b/crates/benilla-ui/src/justify.rs
index bce2e153..a2a2255c 100644
--- a/crates/benilla-ui/src/justify.rs
+++ b/crates/benilla-ui/src/justify.rs
@@ -1,56 +1,11 @@
-//! The justify enum — **one** transcription of `.rdata 0x811ad0`, shared by every table that
-//! speaks it.
-//!
-//! ## Why this is a module and not three sets of `match` arms
-//!
-//! Justification is set on **three** widget tables — a `FontString` (`0x87c1d8`), a `<Font>`
-//! object (`0x87c7c8`) and an `EditBox` — and each had been transcribed *independently* from the
-//! same byte law. Each drifted its own way, and each looked right alone:
-//!
-//! | | FontString ([`crate::script::region`]) | Font ([`crate::script::font`]) | EditBox ([`crate::widget::kinds::editbox`]) | the bytes |
-//! |---|---|---|---|---|
-//! | `GetJustifyH`/`V` | **absent** | present | present | present (`0x79e5f0`/`0x79e7f0`) |
-//! | space-padded token | rejected | `.trim()`ed, **accepted** | rejected | rejected (whole-string) |
-//! | unmatched string | silently `CENTER` | silently `CENTER` | **raises** | **raises** |
-//! | cross-axis token | silently `CENTER` | silently `CENTER` | **clears the axis** | clears the axis |
-//! | axis storage | resolved enum → **the dword** (1239) | resolved enum | **the raw dword** | one dword |
-//!
-//! That is the seam class the addon-lane round trip named: halves transcribed separately from one
-//! law drift where they meet, while every test on every side still passes. **The EditBox column is
-//! the one that was right** — written last, straight from the bytes, and never consulted by the two
-//! older tables. So this module is not new law: it is that column, lifted to where all three reach
-//! it. It sits at the crate root rather than under `script` because `widget::kinds` needs it too.
-//!
-//! ## The law
-//!
-//! Storage is a single dword — `CSimpleFont+0x54`, `CSimpleFontString+0x120` — with **bits 0–2
-//! horizontal and bits 3–5 vertical**. `SetJustifyH 0x79fc20` computes `(cur ^ parsed) & 0x07 ^
-//! cur`, i.e. `(cur & !0x07) | (parsed & 0x07)`, replacing only its own axis (VERIFIED at
-//! `0x79fc5d`–`0x79fc64`); `SetJustifyV 0x79fce0` uses mask `0x38`. The ctor default is `0x212` =
-//! `CENTER | MIDDLE | 0x200`, bit 9 being outside both masks and read by neither accessor.
-//!
-//! Two consequences fall out of that arithmetic, and both are transcribed below:
-//!
-//! - **A cross-axis token is accepted and clears.** `SetJustifyH("TOP")` parses fine (`0x08`) but
-//!   `0x08 & 0x07 == 0`, so it erases the horizontal justification with **no error raised**, and a
-//!   following `GetJustifyH()` answers `"UNKNOWN"` — while the glyphs keep drawing **centred**.
-//!   The two readers genuinely disagree, which is why [`Justify`] stores the dword rather than a
-//!   resolved enum: [`Justify::name_h`] is the getter's answer and [`Justify::paint_h`] is the
-//!   draw path's, and they differ only in this state.
-//! - **A non-token raises.** `0x6f1990` scans all six entries with `SStrCmpI` — whole-string,
-//!   case-insensitive, **no trimming** — and returns 0 on a miss, which is the caller's cue to
-//!   raise `Usage: %s:SetJustifyH("justify")` (`.rdata 0x87c77c`) / `…SetJustifyV…`
-//!   (`0x87c7a0`). Per `script::binding_abi`, that arm does not return: it abandons the caller's
-//!   statement.
-//!
-//! The setter also clears the inherit bit unconditionally, whether or not the axis value changed
-//! (`0x79fc7c`).
+//! The justify dword and its token table (`.rdata 0x811ad0`), shared by the `FontString`
+//! (`0x87c1d8`), `Font` (`0x87c7c8`) and `EditBox` method tables. Each setter replaces only its
+//! own axis, and also clears the inherit bit whether or not the value changed (`0x79fc7c`).
 
 use crate::script::{JustifyH, JustifyV};
 
-/// `.rdata 0x811ad0` — six `{u32 bits, const char* name}` entries, in image order. The order is
-/// load-bearing twice over: `0x6f1990` scans it linearly, and `0x6f1a00` answers with the **first**
-/// entry whose bit is set.
+/// `.rdata 0x811ad0`, six `{u32 bits, const char* name}` entries in image order. The order
+/// matters: `0x6f1990` scans linearly and `0x6f1a00` answers the first entry with its bit set.
 const TOKENS: [(u32, &str); 6] = [
     (0x01, "LEFT"),
     (0x02, "CENTER"),
@@ -63,43 +18,30 @@ const TOKENS: [(u32, &str); 6] = [
 /// The literal `0x6f1a00` answers when no bit in the requested axis is set (`.data 0x838044`).
 pub const UNKNOWN: &str = "UNKNOWN";
 
-/// The horizontal axis — bits 0–2, `SetJustifyH`'s mask.
+/// The horizontal axis, bits 0–2: the mask of `SetJustifyH 0x79fc20`.
 pub const H_MASK: u32 = 0x07;
-/// The vertical axis — bits 3–5, `SetJustifyV`'s mask.
+/// The vertical axis, bits 3–5: the mask of `SetJustifyV 0x79fce0`.
 pub const V_MASK: u32 = 0x38;
 
-/// What a justify argument turned out to be — the three outcomes of `0x6f1990` followed by the
-/// setter's mask.
+/// A justify argument after `0x6f1990` and the setter's mask.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum Set<J> {
-    /// A token carrying a bit on *this* axis: the new justification.
+    /// A token with a bit on this axis.
     To(J),
-    /// A token that matched the table but carries no bit on this axis — `SetJustifyH("TOP")`.
-    /// The reference **clears** the axis and raises nothing; `GetJustifyH()` then answers
-    /// `"UNKNOWN"` while the glyphs keep drawing centred ([`Justify::paint_h`]).
-    ///
-    /// Not hypothetical: 13 corpus sites call `SetJustifyV("CENTER")` meaning "middle"
-    /// (`FonzAppraiser` ×12, `Roid-Macros`), which parses and then erases the vertical axis.
+    /// A token with no bit on this axis (`SetJustifyH("TOP")`): the reference clears the axis and
+    /// raises nothing; corpus addons call `SetJustifyV("CENTER")` and hit this.
     Clears,
-    /// No entry matched. The caller raises its own `Usage:` string; it does not coerce.
+    /// No entry matched: the caller raises its `Usage:` string, never coerces.
     NoMatch,
 }
 
-/// The ctor default — `CENTER | MIDDLE | 0x200`. Bit 9 is outside both axis masks and is read by
-/// neither accessor nor the gx translator. `CSimpleFontString`'s **own** ctor writes it at
-/// `0x770dd3`, so a FontString that has never been told otherwise reads `CENTER`/`MIDDLE`.
+/// `CENTER | MIDDLE | 0x200`, as `CSimpleFontString`'s ctor writes it (`0x770dd3`); bit 9 is in
+/// neither axis and no reader looks at it.
 const CTOR_DEFAULT: u32 = 0x212;
 
-/// The justify **dword** — `CSimpleFont+0x54`, `CSimpleFontString+0x120`, `CSimpleEditBox`'s own —
-/// with bits 0–2 horizontal and bits 3–5 vertical.
-///
-/// Stored as the dword rather than a pair of resolved enums because **an axis with no bit set is a
-/// real, reachable state** and a resolved enum cannot hold it: `SetJustifyH("TOP")` parses `0x08`,
-/// contributes nothing to mask `0x07`, and erases the axis with no error raised.
-///
-/// The two readers then disagree, faithfully, and that is the whole reason this type exists:
-/// [`Justify::name_h`] (the Lua getter) answers `"UNKNOWN"`, while [`Justify::paint_h`] (the draw
-/// path) answers `CENTER`. Anything that collapses the two loses one of them.
+/// The justify dword (`CSimpleFont+0x54`, `CSimpleFontString+0x120`, `CSimpleEditBox`'s own),
+/// bits 0–2 horizontal and 3–5 vertical. Kept raw because an axis with no bit set is reachable,
+/// and there the getter answers `"UNKNOWN"` while the draw path centres.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct Justify(pub u32);
 
@@ -110,11 +52,9 @@ impl Default for Justify {
 }
 
 impl Justify {
-    /// Replace the horizontal bits — `(cur & !0x07) | (parsed & 0x07)`.
     pub fn set_h(&mut self, j: JustifyH) {
         self.0 = set_axis(self.0, H_MASK, bits_h(j));
     }
-    /// Replace the vertical bits — `(cur & !0x38) | (parsed & 0x38)`.
     pub fn set_v(&mut self, j: JustifyV) {
         self.0 = set_axis(self.0, V_MASK, bits_v(j));
     }
@@ -122,46 +62,36 @@ impl Justify {
     pub fn clear_h(&mut self) {
         self.0 = set_axis(self.0, H_MASK, 0);
     }
-    /// Erase the vertical axis.
     pub fn clear_v(&mut self) {
         self.0 = set_axis(self.0, V_MASK, 0);
     }
 
-    /// `GetJustifyH`'s answer — `0x6f1a00`, so `"UNKNOWN"` for a cleared axis.
+    /// `GetJustifyH`'s answer (`0x79e5f0`) through `0x6f1a00`: `"UNKNOWN"` for a cleared axis.
     pub fn name_h(self) -> &'static str {
         name_of(self.0, H_MASK)
     }
-    /// `GetJustifyV`'s answer.
+    /// `GetJustifyV`'s answer (`0x79e7f0`).
     pub fn name_v(self) -> &'static str {
         name_of(self.0, V_MASK)
     }
 
-    /// What the glyphs actually draw at horizontally — the ui→gx translator `0x44d420`, whose one
-    /// call site image-wide is `0x772693`.
-    ///
-    /// **It is a priority ladder, not a switch, and the fall-through is `CENTER` — not `LEFT`.**
-    /// Each axis's result register is pre-set to `1` *between* the `test` and the `jcc`
-    /// (`0x44d4fb mov ebx,0x1`, then `0x44d516 je`), so an all-clear axis exits with `1` still in
-    /// it, and `1` is bit-identical to CENTER. A cleared axis is therefore visually
-    /// indistinguishable from the ctor default.
-    ///
-    /// **The trap, quoted from the finding:** the gx layer's `else` arms genuinely *are* LEFT and
-    /// BOTTOM, but both are unreachable from a FontString — `0x44d420` emits only `{0,1,2}` and
-    /// `0x5c1c30` rejects `>= 3`. *Mapping the ui bitmask onto the gx enum with a `0` default
-    /// inverts both axes.*
+    /// Where the glyphs draw horizontally: the translator `0x44d420` (called only from
+    /// `0x772693`) is a ladder whose result is pre-set to `1`, CENTER (`0x44d4fb`, before the
+    /// `je` at `0x44d516`), so a cleared axis draws centred. The gx enum's `else` arms, LEFT and
+    /// BOTTOM, are unreachable (`0x44d420` emits only 0 to 2, `0x5c1c30` rejects 3 and up):
+    /// mapping the bitmask onto that enum with a `0` default inverts both axes.
     pub fn paint_h(self) -> JustifyH {
         if self.0 & 0x04 != 0 {
             JustifyH::Right
         } else if self.0 & 0x01 != 0 {
             JustifyH::Left
         } else {
-            JustifyH::Center // 0x02 set, or NOTHING set — the pre-set `1`
+            JustifyH::Center // 0x02 set, or no bit set: the pre-set `1`
         }
     }
 
-    /// What the glyphs draw at vertically — the same ladder, `TOP > BOTTOM > MIDDLE`, falling
-    /// through to `MIDDLE`. `0x44d536`'s redundant `mov esi,0x1` on the MIDDLE arm is MSVC's own
-    /// tell that `default:` and `MIDDLE` share a constant.
+    /// The same ladder vertically, `TOP > BOTTOM > MIDDLE`, falling through to MIDDLE
+    /// (`0x44d536`).
     pub fn paint_v(self) -> JustifyV {
         if self.0 & 0x08 != 0 {
             JustifyV::Top
@@ -189,8 +119,7 @@ fn bits_v(j: JustifyV) -> u32 {
     }
 }
 
-/// `0x6f1990` — a linear scan of all six entries with `SStrCmpI`: **whole-string,
-/// case-insensitive, and without trimming**, so `"left "` is a miss.
+/// `0x6f1990`: `SStrCmpI` over the six entries, whole-string and untrimmed, so `"left "` misses.
 pub fn parse_bits(s: &str) -> Option<u32> {
     TOKENS
         .iter()
@@ -198,7 +127,7 @@ pub fn parse_bits(s: &str) -> Option<u32> {
         .map(|(bits, _)| *bits)
 }
 
-/// `0x6f1a00` — the **first** entry whose bit is set within `mask`, else the literal `UNKNOWN`.
+/// `0x6f1a00`: the first entry whose bit is set within `mask`, else the literal `UNKNOWN`.
 pub fn name_of(bits: u32, mask: u32) -> &'static str {
     TOKENS
         .iter()
@@ -206,14 +135,13 @@ pub fn name_of(bits: u32, mask: u32) -> &'static str {
         .map_or(UNKNOWN, |(_, name)| *name)
 }
 
-/// Replace one axis's bits with `parsed`'s, masked to that axis — `0x79fc5d`'s
-/// `(cur ^ parsed) & mask ^ cur`, i.e. `(cur & !mask) | (parsed & mask)`. This is the operation
-/// that makes a cross-axis token *clear* rather than raise.
+/// The setters' `(cur ^ parsed) & mask ^ cur` (`SetJustifyH` at `0x79fc5d`–`0x79fc64`), which is
+/// why a cross-axis token clears rather than raises.
 pub fn set_axis(cur: u32, mask: u32, parsed: u32) -> u32 {
     (cur & !mask) | (parsed & mask)
 }
 
-/// `SetJustifyH`'s argument, resolved against mask `0x07`.
+/// `SetJustifyH`'s argument, against mask `0x07`.
 pub fn parse_h(s: &str) -> Set<JustifyH> {
     match parse_bits(s) {
         None => Set::NoMatch,
@@ -224,7 +152,7 @@ pub fn parse_h(s: &str) -> Set<JustifyH> {
     }
 }
 
-/// `SetJustifyV`'s argument, resolved against mask `0x38`.
+/// `SetJustifyV`'s argument, against mask `0x38`.
 pub fn parse_v(s: &str) -> Set<JustifyV> {
     match parse_bits(s) {
         None => Set::NoMatch,
@@ -235,18 +163,17 @@ pub fn parse_v(s: &str) -> Set<JustifyV> {
     }
 }
 
-/// `GetJustifyH`'s answer for a resolved horizontal justification, through the same table.
+/// `GetJustifyH`'s answer for a resolved justification.
 pub fn name_h(j: JustifyH) -> &'static str {
     name_of(bits_h(j), H_MASK)
 }
 
-/// `GetJustifyV`'s answer for a resolved vertical justification, through the same table.
 pub fn name_v(j: JustifyV) -> &'static str {
     name_of(bits_v(j), V_MASK)
 }
 
-/// The `Usage:` string `SetJustifyH` raises on a miss (`.rdata 0x87c77c`). The `%s` is spelled as
-/// the widget type, matching the shipped convention in `script::font_block`.
+/// The `Usage:` string `SetJustifyH` raises on a miss (`.rdata 0x87c77c`), the `%s` spelled as
+/// the widget type.
 pub fn usage_h(widget: &str) -> mlua::Error {
     mlua::Error::runtime(format!("Usage: <{widget}>:SetJustifyH(\"justify\")"))
 }
@@ -265,8 +192,7 @@ mod tests {
         assert_eq!(parse_h("LEFT"), Set::To(JustifyH::Left));
         assert_eq!(parse_h("left"), Set::To(JustifyH::Left));
         assert_eq!(parse_h("LeFt"), Set::To(JustifyH::Left));
-        // `SStrCmpI` compares the whole string; the client does not trim, and neither do we —
-        // the Font-object path used to, which is the divergence this module exists to end.
+        // `SStrCmpI` compares the whole string, untrimmed.
         assert_eq!(parse_h("left "), Set::NoMatch);
         assert_eq!(parse_h(" left"), Set::NoMatch);
         assert_eq!(parse_h("leftmost"), Set::NoMatch);
@@ -275,8 +201,6 @@ mod tests {
 
     #[test]
     fn an_unmatched_string_does_not_coerce_to_center() {
-        // The whole point of the raise: the reference tells the addon it passed nonsense, where we
-        // used to silently answer CENTER on both tables.
         assert_eq!(parse_h("MIDDLE_LEFT"), Set::NoMatch);
         assert_eq!(parse_v("CENTERED"), Set::NoMatch);
     }
@@ -303,15 +227,12 @@ mod tests {
 
     #[test]
     fn the_formatter_is_first_bit_set_within_the_axis_else_unknown() {
-        // `0x6f1a00`'s two documented edges, neither reachable through our resolved enums but both
-        // part of the law being transcribed: no bit in the axis answers the literal UNKNOWN, and a
-        // dword with two bits set answers the *first* table entry rather than the largest.
+        // `0x6f1a00`: no bit in the axis answers UNKNOWN, two bits answer the first table entry.
         assert_eq!(name_of(0x00, H_MASK), "UNKNOWN");
         assert_eq!(name_of(0x38, H_MASK), "UNKNOWN"); // vertical bits only
         assert_eq!(name_of(0x05, H_MASK), "LEFT"); // LEFT | RIGHT
         assert_eq!(name_of(0x30, V_MASK), "MIDDLE"); // MIDDLE | BOTTOM
-                                                     // The ctor default `0x212` reads CENTER/MIDDLE, and bit 9 is invisible to both axes.
-        assert_eq!(name_of(0x212, H_MASK), "CENTER");
+        assert_eq!(name_of(0x212, H_MASK), "CENTER"); // the ctor default; bit 9 is in no axis
         assert_eq!(name_of(0x212, V_MASK), "MIDDLE");
     }
 }
diff --git a/crates/benilla-ui/src/layout.rs b/crates/benilla-ui/src/layout.rs
index 8ec33152..8c68f058 100644
--- a/crates/benilla-ui/src/layout.rs
+++ b/crates/benilla-ui/src/layout.rs
@@ -1,66 +1,37 @@
-//! The frame anchor/layout resolver — anchor graph → resolved rects (decision 0068).
+//! The frame anchor resolver: the 1.12 client's `CLayoutFrame` rect resolution, transcribed
+//! function by function, with the reference's operations in the reference's order.
 //!
-//! This is a faithful transcription of the WoW 1.12.1 client's `CLayoutFrame` geometry resolver,
-//! reverse-engineered bit-exact against `WoW.exe`. The leaf float kernels and the
-//! recursion-guarded per-edge composition are transcribed from the reference, function by function
-//! and verified bit-exact. Matching the reference's operations and their order — not "improving"
-//! the arithmetic — is the goal.
+//! The client computes on the x87 at 53-bit precision, which `f64` matches, and narrows to `f32`
+//! only at its stores (each sub-edge before a `combine_*`, each final edge, the `width * scale`
+//! span), so the arithmetic here runs in `f64` with an explicit `as f32` at exactly those sites.
 //!
-//! ## Precision — why `f64` intermediates, not naive `f32`
-//!
-//! The client is an x87 binary: every intermediate lives in an FPU register at PC_53 (53-bit
-//! mantissa = IEEE `f64` precision) and is narrowed to `f32` *only* at the documented `fstp m32`
-//! store sites (each sub-edge result before a `combine_*`; each final edge into the out-rect; the
-//! `width·scale` span). A leaf like `(right + left) * 0.5 + xOff·scale` therefore rounds **once**
-//! (at the final store), whereas doing every operation in `f32` would round at each step and
-//! diverge. So "the client is f32" is true only at the storage boundaries: to be bit-faithful the
-//! chain of `+`/`-`/`*0.5` runs in `f64` (host-exact — every operand is `f32`-derived, so each op is
-//! exact in `f64`) with an explicit `as f32` at exactly the sites the reference pins.
-//!
-//! ## Coordinate space
-//!
-//! Rects are stored in the client's own convention: `[bottom, left, top, right]` (frame-absolute
-//! `+0x64/+0x68/+0x6c/+0x70`; `GetRect 0x768320` and the Lua `GetBottom/Left/Top/Right`
-//! readers). WoW UI space is **y-up**: `top > bottom`, the screen root's rect is the
-//! physical screen (the anchor chain bottoms out at the `CSimpleTop` root), and `width = right −
-//! left`, `height = top − bottom`. Coordinates are screen pixels throughout; `scale` (layoutScale =
-//! effective scale, `0x76ac90`) scales only the per-anchor offsets and the
-//! `width/height` span.
+//! Rects are `[bottom, left, top, right]` (frame `+0x64..+0x70`, `GetRect` `0x768320`) in screen
+//! pixels, y-up.
 
 use std::collections::VecDeque;
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Constants (objdump-read from `WoW.exe`)
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Constants ────────────────────────────────────────────────────────────────────────────────
 
-/// UNSET coordinate sentinel: `+Infinity` (the `.data` slot `0xcf550c`, runtime-initialized from
-/// `[0x81d56c] = 0x7f800000`). "coordinate is set" ⇔ `x != +Inf`. Intermediates carry
-/// this in `f64`; the `f32` narrowing preserves it (`+Inf as f32 == +Inf`).
+/// The unset-coordinate sentinel, `+Inf` (`0xcf550c`, set at runtime from `0x81d56c`).
 const UNSET: f64 = f64::INFINITY;
 
-/// `OnSizeChanged` trigger ε — `_DAT_008029d4` = `0x34800000` ≈ 2.384e-7 (applied in
-/// `ApplyRect 0x76b580`). `OnSizeChanged(width,height)` fires iff `|Δwidth| ≥ ε` OR
-/// `|Δheight| ≥ ε` between the old and new resolved rect. See [`size_changed`].
+/// The least width or height change that fires `OnSizeChanged`: 2^-22, bits `0x34800000` at
+/// `0x8029d4`, tested in `ApplyRect` (`0x76b580`).
 pub const SIZE_EPS: f64 = 2.384_185_791_015_625e-7;
 
-/// Recompute change threshold ε — `_DAT_0080c5c8` = `0x3727c5ac` ≈ 9.96e-6 (applied in
-/// `recompute 0x768d20`): an edge must move at least this far vs the cached rect for a re-store +
-/// `ApplyRect`. Benilla owns its own caching (the caller's dirty gate); this const records the client's
-/// documented threshold for fidelity work that needs it.
+/// The least edge move against the cached rect for the client to re-store it and `ApplyRect`, 1e-5
+/// (`0x80c5c8`, in `0x768d20`). Recorded, not applied: the caller's own dirty gate decides.
 pub const RESOLVE_EPS: f64 = f32::from_bits(0x3727_c5ac) as f64;
 
-/// point-id → X column (table `0x81c3b8`..):
-/// `{0,3,6}` (LEFT column) → 0, `{1,4,7}` (center) → 1, `{2,5,8}` (RIGHT column) → 2.
+/// Point id to X column: left 0, center 1, right 2.
 const X_COL: [u8; 9] = [0, 1, 2, 0, 1, 2, 0, 1, 2];
-/// point-id → Y row: `{0,1,2}` (TOP row) → 0, `{3,4,5}` (center) → 1, `{6,7,8}` (BOTTOM row) → 2.
+/// Point id to Y row: top 0, center 1, bottom 2.
 const Y_ROW: [u8; 9] = [0, 0, 0, 1, 1, 1, 2, 2, 2];
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Public types
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Public types ─────────────────────────────────────────────────────────────────────────────
 
-/// The nine anchor points, with the client's exact discriminants (static tables
-/// `0x81c3b8–0x81c3fc`): the id is the slot index in the client's `anchorPoints[9]`.
+/// The nine anchor points; the discriminant is the client's point id, the slot in its
+/// `anchorPoints[9]` (tables at `0x81c3b8..0x81c3fc`).
 #[repr(u8)]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 pub enum Point {
@@ -76,13 +47,11 @@ pub enum Point {
 }
 
 impl Point {
-    /// The point-id (0..=8), which is also the `anchorPoints[9]` slot index.
     #[inline]
     pub const fn id(self) -> u8 {
         self as u8
     }
 
-    /// Build a [`Point`] from its client id, `None` if out of range.
     pub const fn from_id(id: u8) -> Option<Point> {
         Some(match id {
             0 => Point::TopLeft,
@@ -99,11 +68,10 @@ impl Point {
     }
 }
 
-/// An opaque handle to an anchor target. This crate does not own the frame arena; the caller maps
-/// handles to frames / external rects. (In the client this is the `CAnchor+0xc relativeTo` pointer.)
+/// An anchor target, which the caller maps to a frame or an external rect (`CAnchor+0xc`).
 pub type Handle = u32;
 
-/// A resolved rect in the client's `[bottom, left, top, right]` convention (screen pixels, y-up).
+/// A resolved rect, `[bottom, left, top, right]` in screen pixels, y-up.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct Rect {
     pub bottom: f32,
@@ -113,7 +81,6 @@ pub struct Rect {
 }
 
 impl Rect {
-    /// Construct from the four edges in client order.
     pub const fn new(bottom: f32, left: f32, top: f32, right: f32) -> Rect {
         Rect {
             bottom,
@@ -123,51 +90,39 @@ impl Rect {
         }
     }
 
-    /// `[bottom, left, top, right]` — the client's cached-rect layout (`+0x64..0x70`).
     #[inline]
     pub const fn to_array(self) -> [f32; 4] {
         [self.bottom, self.left, self.top, self.right]
     }
 
-    /// From `[bottom, left, top, right]`.
     #[inline]
     pub const fn from_array(a: [f32; 4]) -> Rect {
         Rect::new(a[0], a[1], a[2], a[3])
     }
 
-    /// `right − left` (`GetWidth` semantics).
     #[inline]
     pub fn width(self) -> f32 {
         self.right - self.left
     }
 
-    /// `top − bottom` (`GetHeight` semantics; y-up).
     #[inline]
     pub fn height(self) -> f32 {
         self.top - self.bottom
     }
 }
 
-/// One anchor of a frame — a `CAnchor` record
-/// (`{xOff@4, yOff@8, relativeTo@0xc, relativePoint@0x10}`). `point` is the point *on this frame*
-/// being pinned (its `anchorPoints[9]` slot); `relative_point` is the point *on the target* it
-/// pins to.
+/// One anchor, a client `CAnchor` (`xOff +4`, `yOff +8`, `relativeTo +0xc`, `relativePoint +0x10`):
+/// `point` on this frame pins to `relative_point` on the target.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct Anchor {
-    /// The point on *this* frame that is being anchored (its `anchorPoints[9]` slot index).
     pub point: Point,
-    /// The target frame/region this anchor is relative to (`CAnchor+0xc`).
     pub relative_to: Handle,
-    /// The point on the *target* this anchor pins to (`CAnchor+0x10 relativePoint`).
     pub relative_point: Point,
-    /// X offset (`CAnchor+4`), scaled by the requesting frame's `scale`.
     pub x_off: f32,
-    /// Y offset (`CAnchor+8`), scaled by `scale`.
     pub y_off: f32,
 }
 
 impl Anchor {
-    /// Convenience constructor.
     pub fn new(
         point: Point,
         relative_to: Handle,
@@ -185,28 +140,24 @@ impl Anchor {
     }
 }
 
-/// A frame's full layout input: its anchors, its optional explicit size, its scale, and the
-/// clamp-to-screen flag + extents. Mirrors the client's geometry subobject fields consulted by the
-/// resolver: `anchorPoints[9]` (`G+0x28`), `width`
-/// (`G+0x50`), `height` (`G+0x54`), `layoutScale` (`G+0x58`), flags bit4 = clamp (`G+0x3c`).
+/// A frame's layout input, the geometry fields the client's resolver reads: `anchorPoints[9]`
+/// (`G+0x4`), `width` (`G+0x50`), `height` (`G+0x54`), `layoutScale` (`G+0x58`) and the clamp flag
+/// (bit 4 of `G+0x3c`).
 #[derive(Clone, Debug, PartialEq)]
 pub struct LayoutInput {
-    /// The frame's anchors. Placed into the nine `anchorPoints` slots by their `point`; if two share
-    /// a `point`, the *last* wins (the client's `SetPoint 0x767c70` overwrites the slot).
+    /// Slotted by `point`, the later of two on one point winning (`SetPoint`, `0x767c70`).
     pub anchors: Vec<Anchor>,
-    /// Explicit width (`G+0x50`); **`0.0` ⇒ derive from opposing anchors** (the no-explicit-size
-    /// sentinel `DAT_007ffd74`).
+    /// `0.0` is the no-size sentinel (`0x7ffd74`): the axis derives from the anchors.
     pub width: f32,
-    /// Explicit height (`G+0x54`); `0.0` ⇒ derive from opposing anchors.
     pub height: f32,
-    /// `layoutScale` = effective scale (`parentScale · ownScale`, ε-gated; `0x76ac90`); the
-    /// px↔coord multiplier applied to offsets and the size span. Default `1.0`.
+    /// The effective scale, parent times own (`0x76ac90`), applied only to the anchor offsets and
+    /// the size span.
     pub scale: f32,
-    /// Clamp the assembled rect into `[0, extent]` per axis (`G` flags bit4; `assemble 0x767a20`).
+    /// Clamp the rect into `[0, extent]` on each axis.
     pub clamp: bool,
-    /// Screen X extent, only consulted when `clamp` (client `0x41ae60` return, default `0.8`).
+    /// The clamp's X extent; the client's default is `0.8` (`0x41ae60`).
     pub extent_x: f32,
-    /// Screen Y extent, only consulted when `clamp` (client `0x41ae70` return, default `0.6`).
+    /// The clamp's Y extent; the client's default is `0.6` (`0x41ae70`).
     pub extent_y: f32,
 }
 
@@ -236,31 +187,18 @@ impl LayoutInput {
     }
 }
 
-/// The outcome of resolving one frame's rect.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub enum ResolveOutcome {
-    /// Every edge resolved → the cached rect `[bottom, left, top, right]` (`assemble` returned 1).
     Resolved(Rect),
-    /// At least one edge stayed `+Inf` — under-constrained (`assemble 0x767a20` returns 0, caller
-    /// sets flags bit3 "resolution-failed").
+    /// An edge stayed `+Inf`: the client's `assemble` returns 0 and its caller sets flags bit 3.
     Unresolvable,
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Leaf float kernels — the owned-fidelity math. Each returns its coordinate in `f64` (the
-// un-narrowed x87 `st0` observable); callers narrow to `f32` at the documented store sites.
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Leaf kernels: each returns the un-narrowed `f64` ─────────────────────────────────────────
 
-/// `combineEdge 0x767440(center, opp, span)`: resolve one edge from the opposite
-/// edge, the axis center, and the signed `size·scale` span, in that fallback order.
-///
-/// - opposite known and non-zero span → `opp + span` (edge = opposite ± size·scale);
-/// - else center known: non-zero span → `span·0.5 + center` (edge = center ± half-size);
-///   else opposite known → `(center − opp) + center` (= 2·center − opposite, the mirror);
-/// - else → `+Inf` (unresolvable).
-///
-/// The `+Inf`/`0.0` sentinels are compared with IEEE equality, matching the binary's `fcomp`
-/// against the `.data` slots (a NaN operand is unordered ⇒ "not equal to the sentinel").
+/// `combineEdge` (`0x767440`): an edge from the opposite edge and the signed `size * scale` span,
+/// else from the axis center. The sentinels compare by IEEE equality, as the client's `fcomp`
+/// does, so a NaN never matches one.
 #[allow(clippy::float_cmp)]
 pub fn combine_edge(center: f32, opp: f32, span: f32) -> f64 {
     let (c, o, s) = (f64::from(center), f64::from(opp), f64::from(span));
@@ -278,12 +216,7 @@ pub fn combine_edge(center: f32, opp: f32, span: f32) -> f64 {
     UNSET
 }
 
-/// `combineCenter 0x7672d0(lo, hi, span)`: resolve an axis center from the low edge,
-/// the high edge, and the signed `size·scale` span.
-///
-/// - low known: high known → `(lo+hi)·0.5`; else non-zero span → `span·0.5 + lo`;
-/// - else high known and non-zero span → `hi − span·0.5`;
-/// - else → `+Inf`.
+/// `combineCenter` (`0x7672d0`): an axis center from the low and high edges and the signed span.
 #[allow(clippy::float_cmp)]
 pub fn combine_center(lo: f32, hi: f32, span: f32) -> f64 {
     let (l, h, s) = (f64::from(lo), f64::from(hi), f64::from(span));
@@ -301,16 +234,9 @@ pub fn combine_center(lo: f32, hi: f32, span: f32) -> f64 {
     UNSET
 }
 
-/// `CAnchor::ResolveX 0x7a2f90(scale)`: resolve this anchor's X coordinate against its
-/// `relativeTo`'s cached rect.
-///
-/// `rect` = the target's cached rect `[bottom, left, top, right]` when `GetRect` succeeded (cache
-/// valid), `None` when it failed ⇒ `+Inf`. `mirror` = the target's geometry-vtable `+0x24`
-/// normalize predicate (RTL/local-origin): when set, X edges are translated so `left → 0`,
-/// `right → right − left` (each stored back as `f32`, the binary's `fstp m32`). For an ordinary
-/// frame the predicate returns 0, so `mirror` is `false` (`0x46ff60 = xor eax,eax; ret`).
-/// `coord = xOff·scale + edge` for the relativePoint's column
-/// (center = mid-X + xOff·scale). `rel_point > 8` ⇒ `+Inf`.
+/// `CAnchor::ResolveX` (`0x7a2f90`): the anchor's X against its target's cached `rect`, which is
+/// `None` when `GetRect` fails. `mirror` is the target's normalize predicate (vtable `+0x24`, 0 for
+/// an ordinary frame at `0x46ff60`), which shifts the edges to start at 0, each stored as `f32`.
 pub fn anchor_resolve_x(
     scale: f32,
     x_off: f32,
@@ -337,9 +263,7 @@ pub fn anchor_resolve_x(
     }
 }
 
-/// `CAnchor::ResolveY 0x7a3070(scale)` — the Y twin of [`anchor_resolve_x`]. `mirror`
-/// normalizes the Y edges (`bottom → 0`, `top → top − bottom`); `coord = yOff·scale + edge` for the
-/// relativePoint's row (center = mid-Y + yOff·scale). `rect` = `[bottom, left, top, right]`.
+/// `CAnchor::ResolveY` (`0x7a3070`), the Y counterpart of [`anchor_resolve_x`].
 pub fn anchor_resolve_y(
     scale: f32,
     y_off: f32,
@@ -366,21 +290,16 @@ pub fn anchor_resolve_y(
     }
 }
 
-/// The assembled (and possibly clamped) rect + whether every edge resolved.
+/// [`assemble_rect`]'s result: `ok` when every edge resolved.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct AssembleRect {
     pub ok: bool,
-    /// `[bottom, left, top, right]` (meaningful only when `ok`).
+    /// `[bottom, left, top, right]`, meaningful only when `ok`.
     pub rect: [f32; 4],
 }
 
-/// `assemble 0x767a20`: given the four resolved edge coordinates `[bottom, left, top,
-/// right]` (each `+Inf` ⇒ unresolvable), fail if any is `+Inf`; else optionally clamp into
-/// `[0, extent]` per axis.
-///
-/// Clamp (geom flags bit4): a low edge `< 0` shifts to 0 carrying the span to the high edge; a high
-/// edge past the screen extent shifts back carrying to the low edge, high edge = extent. Each store
-/// is narrowed to `f32`.
+/// `assemble` (`0x767a20`): fails if any edge is `+Inf`, else with `clamp` (flags bit 4) shifts
+/// the rect into `[0, extent]` on each axis, low edge first, keeping its size.
 #[allow(clippy::float_cmp)]
 pub fn assemble_rect(edges: [f32; 4], clamp: bool, extent_x: f32, extent_y: f32) -> AssembleRect {
     let [mut bottom, mut left, mut top, mut right] = edges;
@@ -417,9 +336,8 @@ pub fn assemble_rect(edges: [f32; 4], clamp: bool, extent_x: f32, extent_y: f32)
     }
 }
 
-/// `OnSizeChanged` fire test (`ApplyRect 0x76b580`): fires iff `|Δwidth| ≥ [`SIZE_EPS`]`
-/// OR `|Δheight| ≥ SIZE_EPS`, with `width = right − left`, `height = top − bottom`. Deltas are `f64`
-/// of the `f32` edges (the binary's `fsub` of the `fld`'d rect components).
+/// `ApplyRect`'s `OnSizeChanged` test (`0x76b580`): width or height moved by at least
+/// [`SIZE_EPS`], the deltas taken in `f64` from the `f32` edges.
 pub fn size_changed(old: Rect, new: Rect) -> bool {
     let dw =
         (f64::from(new.right) - f64::from(new.left)) - (f64::from(old.right) - f64::from(old.left));
@@ -428,15 +346,9 @@ pub fn size_changed(old: Rect, new: Rect) -> bool {
     dw.abs() >= SIZE_EPS || dh.abs() >= SIZE_EPS
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The composed resolver — recursion-guarded per-edge sequencing over the leaves above,
-// bit-exact over the binary's `assemble 0x767a20` → six per-edge resolvers → anchor scans → leaf
-// kernels. Adds NO new arithmetic — only integer control flow + the documented `fstp m32` `f32`
-// narrowing at each site.
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The composed resolver: `assemble` over six recursion-guarded edge resolvers ──────────────
 
-/// A resolved anchor for the internal edge tree: like [`Anchor`] but with the target's rect already
-/// looked up (`None` ⇒ target had no valid rect ⇒ `GetRect`-fail leg).
+/// An [`Anchor`] with its target's rect looked up, `None` where `GetRect` would fail.
 #[derive(Clone, Copy)]
 struct AnchorRel {
     x_off: f32,
@@ -446,8 +358,6 @@ struct AnchorRel {
     mirror: bool,
 }
 
-/// Internal per-edge resolver input: the nine `anchorPoints` slots (by point-id) with rects
-/// resolved, plus the size/scale/clamp fields.
 struct EdgeInput {
     anchors: [Option<AnchorRel>; 9],
     width: f32,
@@ -458,7 +368,7 @@ struct EdgeInput {
     extent_y: f32,
 }
 
-// recursion-guard bits (the binary's `G+0x28` bitfield).
+// The recursion-guard bits of the client's `G+0x28`.
 const G_LEFT: u32 = 0x01;
 const G_TOP: u32 = 0x02;
 const G_RIGHT: u32 = 0x04;
@@ -466,7 +376,7 @@ const G_BOTTOM: u32 = 0x08;
 const G_XC: u32 = 0x10;
 const G_YC: u32 = 0x20;
 
-// per-edge point-id scan tables (`.rdata` 0x81c3b8..0x81c3f4).
+// The point ids each edge scans (`.rdata` 0x81c3b8..0x81c3f4).
 const IDS_LEFT: [usize; 3] = [0, 3, 6];
 const IDS_RIGHT: [usize; 3] = [2, 5, 8];
 const IDS_TOP: [usize; 3] = [0, 1, 2];
@@ -474,8 +384,7 @@ const IDS_BOTTOM: [usize; 3] = [6, 7, 8];
 const IDS_XC: [usize; 3] = [1, 4, 7];
 const IDS_YC: [usize; 3] = [3, 4, 5];
 
-/// `anchorScanX 0x7671a0`: over the edge's three point-ids, the first present anchor whose
-/// `ResolveX` is non-`+Inf` wins; else `+Inf`.
+/// `anchorScanX` (`0x7671a0`): the first of the edge's anchors whose X resolves, else `+Inf`.
 #[allow(clippy::float_cmp)]
 fn anchor_scan_x(ids: &[usize; 3], f: &EdgeInput) -> f64 {
     for &id in ids {
@@ -489,7 +398,7 @@ fn anchor_scan_x(ids: &[usize; 3], f: &EdgeInput) -> f64 {
     UNSET
 }
 
-/// `anchorScanY 0x7671f0` — the Y twin.
+/// `anchorScanY` (`0x7671f0`).
 #[allow(clippy::float_cmp)]
 fn anchor_scan_y(ids: &[usize; 3], f: &EdgeInput) -> f64 {
     for &id in ids {
@@ -503,18 +412,10 @@ fn anchor_scan_y(ids: &[usize; 3], f: &EdgeInput) -> f64 {
     UNSET
 }
 
-/// `width·scale` / `height·scale` — the per-edge resolvers' shared span step (`LEFT 0x7673d0` et
-/// al.): operands are `f32` fields, the product narrowed to `f32` at the `fstp [esp]` site,
-/// negated for LEFT/BOTTOM.
-///
-/// **`size` is not always the authored field, and this is the trap** (decision 1349): each
-/// caller's `call [eax+0x1c]` is **virtual**. A plain frame lands on
-/// `0x768420 fld [G+0x50]` — the flat read this signature assumes — but a `CSimpleTexture` lands on
-/// `0x770720` and a `CSimpleFontString` on `0x772930`, both of which substitute a **content-derived**
-/// extent when the authored value is exactly `0.0` (the texture's own texel size, one texel per
-/// FrameXML unit; the string's measured text, floored at one unit). benilla feeds this the authored
-/// number only, so a zero-authored *texture* axis yields a zero span here where the client yields a
-/// real one. 1349 §4 carries the change and its scope; do not read this kernel as the whole law.
+/// The edge resolvers' span, `size * scale` narrowed to `f32`, negated for LEFT and BOTTOM. The
+/// client reads `size` through a virtual getter: a frame's is the authored field (`0x768420`), but
+/// a texture (`0x770720`) and a font string (`0x772930`) replace an authored `0.0` with their
+/// content's extent, so a region's [`LayoutInput`] must already carry that extent.
 fn size_span(size: f32, scale: f32, negate: bool) -> f32 {
     let span = (f64::from(size) * f64::from(scale)) as f32;
     if negate {
@@ -524,7 +425,7 @@ fn size_span(size: f32, scale: f32, negate: bool) -> f32 {
     }
 }
 
-/// `LEFT 0x7673d0` — direct anchor scan, else `combineEdge(Xcenter, RIGHT, −width·scale)`.
+/// LEFT (`0x7673d0`): its anchor scan, else `combineEdge(Xcenter, RIGHT, -width * scale)`.
 #[allow(clippy::float_cmp)]
 fn resolve_left(f: &EdgeInput, guard: &mut u32) -> f64 {
     if *guard & G_LEFT != 0 {
@@ -544,7 +445,7 @@ fn resolve_left(f: &EdgeInput, guard: &mut u32) -> f64 {
     r
 }
 
-/// `RIGHT 0x767540` — direct anchor scan, else `combineEdge(Xcenter, LEFT, +width·scale)`.
+/// RIGHT (`0x767540`): its anchor scan, else `combineEdge(Xcenter, LEFT, width * scale)`.
 #[allow(clippy::float_cmp)]
 fn resolve_right(f: &EdgeInput, guard: &mut u32) -> f64 {
     if *guard & G_RIGHT != 0 {
@@ -564,7 +465,7 @@ fn resolve_right(f: &EdgeInput, guard: &mut u32) -> f64 {
     r
 }
 
-/// `TOP 0x7674d0` — direct anchor scan, else `combineEdge(Ycenter, BOTTOM, +height·scale)`.
+/// TOP (`0x7674d0`): its anchor scan, else `combineEdge(Ycenter, BOTTOM, height * scale)`.
 #[allow(clippy::float_cmp)]
 fn resolve_top(f: &EdgeInput, guard: &mut u32) -> f64 {
     if *guard & G_TOP != 0 {
@@ -584,7 +485,7 @@ fn resolve_top(f: &EdgeInput, guard: &mut u32) -> f64 {
     r
 }
 
-/// `BOTTOM 0x7675b0` — direct anchor scan, else `combineEdge(Ycenter, TOP, −height·scale)`.
+/// BOTTOM (`0x7675b0`): its anchor scan, else `combineEdge(Ycenter, TOP, -height * scale)`.
 #[allow(clippy::float_cmp)]
 fn resolve_bottom(f: &EdgeInput, guard: &mut u32) -> f64 {
     if *guard & G_BOTTOM != 0 {
@@ -604,7 +505,7 @@ fn resolve_bottom(f: &EdgeInput, guard: &mut u32) -> f64 {
     r
 }
 
-/// `Xcenter 0x767260` — direct anchor scan, else `combineCenter(LEFT, RIGHT, +width·scale)`.
+/// Xcenter (`0x767260`): its anchor scan, else `combineCenter(LEFT, RIGHT, width * scale)`.
 #[allow(clippy::float_cmp)]
 fn resolve_xcenter(f: &EdgeInput, guard: &mut u32) -> f64 {
     if *guard & G_XC != 0 {
@@ -624,7 +525,7 @@ fn resolve_xcenter(f: &EdgeInput, guard: &mut u32) -> f64 {
     r
 }
 
-/// `Ycenter 0x767360` — direct anchor scan, else `combineCenter(BOTTOM, TOP, +height·scale)`.
+/// Ycenter (`0x767360`): its anchor scan, else `combineCenter(BOTTOM, TOP, height * scale)`.
 #[allow(clippy::float_cmp)]
 fn resolve_ycenter(f: &EdgeInput, guard: &mut u32) -> f64 {
     if *guard & G_YC != 0 {
@@ -644,12 +545,8 @@ fn resolve_ycenter(f: &EdgeInput, guard: &mut u32) -> f64 {
     r
 }
 
-/// `assemble 0x767a20` composed: resolve all four edges (each `fst`'d to the `f32` out-rect),
-/// returning [`ResolveOutcome::Unresolvable`] if any stayed `+Inf`, else the assembled (and, when
-/// `clamp`, screen-clamped) rect. The four top-level resolves share a fresh guard; the binary
-/// clears each edge's bit on return, so order is immaterial — we keep the binary's LEFT→BOTTOM→
-/// RIGHT→TOP order. The `+Inf` test is on the un-narrowed `f64` edge (the binary's `fcomp` before
-/// the `fst`).
+/// `assemble` (`0x767a20`) composed, resolving LEFT, BOTTOM, RIGHT, TOP in the client's order; the
+/// `+Inf` test reads the un-narrowed `f64` edge, as the client's `fcomp` precedes its `fst`.
 #[allow(clippy::float_cmp)]
 fn resolve_edges(f: &EdgeInput) -> ResolveOutcome {
     let mut guard = 0u32;
@@ -665,13 +562,8 @@ fn resolve_edges(f: &EdgeInput) -> ResolveOutcome {
     ResolveOutcome::Resolved(Rect::from_array(a.rect))
 }
 
-/// Resolve one frame's rect. `target_rect` supplies each anchor target's already-resolved rect
-/// (`None` ⇒ the target has no valid rect ⇒ that anchor contributes `+Inf`, the `GetRect`-fail
-/// leg). Anchors are placed into the nine `anchorPoints` slots by their `point`; on a duplicate the
-/// later anchor wins (the client's `SetPoint` overwrite).
-///
-/// This is the fidelity surface: it builds the client's `anchorPoints[9]` view and runs the
-/// composed `assemble 0x767a20`.
+/// Resolve one frame's rect; `target_rect` gives each anchor target's resolved rect, and `None`
+/// makes that anchor `+Inf`, as a failed `GetRect` does.
 pub fn resolve_rect(
     frame: &LayoutInput,
     target_rect: impl FnMut(Handle) -> Option<Rect>,
@@ -679,9 +571,6 @@ pub fn resolve_rect(
     resolve_edges(&build_edge_input(frame, target_rect))
 }
 
-/// Build the client's `anchorPoints[9]` view + size/scale/clamp fields for `frame`, resolving each
-/// anchor target's rect through `target_rect`. Shared by [`resolve_rect`] (all-or-nothing) and
-/// [`resolve_rect_edges`] (per-edge).
 fn build_edge_input(
     frame: &LayoutInput,
     mut target_rect: impl FnMut(Handle) -> Option<Rect>,
@@ -693,8 +582,7 @@ fn build_edge_input(
             y_off: a.y_off,
             rel_point: a.relative_point.id() as u32,
             rel_rect: target_rect(a.relative_to).map(Rect::to_array),
-            // Ordinary frames' normalize predicate returns 0 (`0x46ff60`); RTL/mirror
-            // frames are not modeled here (the leaf `anchor_resolve_*` covers that leg).
+            // An ordinary frame's normalize predicate returns 0 (`0x46ff60`).
             mirror: false,
         });
     }
@@ -709,12 +597,8 @@ fn build_edge_input(
     }
 }
 
-/// Resolve one frame's four edges, returning each as `Some(edge)` when the anchor graph + explicit
-/// size determined it, or `None` when it stayed `+Inf` (unset). The per-edge view **regions** need:
-/// a region inherits any edge its anchors + size don't pin from its owner frame (decision 0068's v1
-/// region model — see [`crate::script`]'s region resolution), so it must see *which* edges resolved,
-/// not the all-or-nothing verdict [`resolve_rect`] gives. Order matches [`Rect`]: `[bottom, left,
-/// top, right]`. No `assemble`/clamp is applied (regions never clamp to screen in v1).
+/// Resolve one frame's edges, `[bottom, left, top, right]`, each `None` where it stayed unset;
+/// `assemble` and its clamp are not applied. The region pass reads it axis by axis.
 #[allow(clippy::float_cmp)]
 pub fn resolve_rect_edges(
     frame: &LayoutInput,
@@ -730,55 +614,27 @@ pub fn resolve_rect_edges(
     [cvt(bottom), cvt(left), cvt(top), cvt(right)]
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Graph driver — resolve a set of frames in dependency order (anchor targets before dependents),
-// detecting cycles. This is benilla's orchestration, not client fidelity math: the client resolves
-// lazily-on-read + per-frame-batched via a dependency-ordered deferred queue (`0x7680e0`, ordered
-// by `0x7681b0`); we express the same dependency ordering as an explicit topological pass.
-//
-// ## Why a dense, reusable solver rather than a fresh map-backed graph
-//
-// The caller re-solves the whole widget set every round of its fixpoint, and the fixpoint runs
-// every frame. A map-backed graph rebuilt per round paid, per round: one `LayoutInput` clone
-// (heap `Vec<Anchor>`) per frame, a `BTreeMap` insert per node, and a `BTreeMap` probe per anchor
-// target during the solve. Measured on the shipped default UI (1881 frames + 5478 regions,
-// release): 1.36 ms per resolve, of which ~0.25 ms was graph construction and ~0.64 ms the solve
-// itself — paid on a completely quiet frame.
-//
-// [`Handle`]s are the caller's own dense id space (benilla's `Model::next_id`, monotonic from 1
-// with frames and regions sharing the counter), so every per-node map collapses to an array index
-// and every buffer can live across calls. `begin` clears only the slots the previous round
-// touched, so a round costs O(nodes), never O(id space). Iteration order is kept **ascending by
-// handle** — identical to the `BTreeMap` it replaces — because cycle members are resolved
-// best-effort in that order and the result depends on it.
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Graph driver ─────────────────────────────────────────────────────────────────────────────
 
-/// A reusable dependency solver over a set of anchored frames plus *external* pre-resolved rects
-/// (the screen root — the client's `CSimpleTop`, whose rect is the physical screen — and any fixed
-/// targets, such as already-resolved regions).
-///
-/// One solver is kept alive across frames so its buffers are reused. A round is:
-/// [`begin`](Self::begin) → [`set_external`](Self::set_external) /
-/// [`set_frame`](Self::set_frame) → [`solve`](Self::solve) → [`rect`](Self::rect).
+/// Resolves anchored frames in dependency order, a driver of benilla's own: the client resolves
+/// lazily through a dependency-ordered deferred queue (`0x7680e0`, ordered by `0x7681b0`). Handles
+/// index its arrays directly, so they must be dense. A round: [`begin`](Self::begin),
+/// [`set_external`](Self::set_external) and [`set_frame`](Self::set_frame), [`solve`](Self::solve).
 #[derive(Clone, Debug, Default)]
 pub struct LayoutSolver {
-    /// Per-handle layout input. Persistent storage: [`set_frame`](Self::set_frame) overwrites in
-    /// place so the anchors `Vec` keeps its allocation across rounds.
+    /// Overwritten in place, so each anchors `Vec` keeps its allocation.
     input: Vec<LayoutInput>,
-    /// Is `input[h]` a frame to solve this round?
     is_frame: Vec<bool>,
-    /// Per-handle rect: externals as seeded, frames as they resolve. `None` = not (yet) known.
+    /// Externals as seeded, frames as they resolve.
     rect: Vec<Option<Rect>>,
-    /// Kahn in-degree, and the reverse edges (each inner `Vec` is cleared, never freed).
+    /// Kahn in-degree and reverse edges; each inner `Vec` is cleared, never freed.
     indeg: Vec<u32>,
     dependents: Vec<Vec<Handle>>,
-    /// Handles whose slots were written this round — `begin` resets exactly these.
+    /// The handles written this round, the ones `begin` resets.
     touched: Vec<Handle>,
-    /// Is `h` already in `touched`?
     marked: Vec<bool>,
-    /// The frames to solve, ascending (the `BTreeMap` iteration order this replaces).
+    /// Ascending: cycle members resolve in this order, and the result depends on it.
     live: Vec<Handle>,
-    /// Kahn scratch + output.
     queue: VecDeque<Handle>,
     emitted: Vec<bool>,
     order: Vec<Handle>,
@@ -787,12 +643,10 @@ pub struct LayoutSolver {
 }
 
 impl LayoutSolver {
-    /// A new, empty solver.
     pub fn new() -> LayoutSolver {
         LayoutSolver::default()
     }
 
-    /// Grow the per-handle arrays to cover `h`.
     fn ensure(&mut self, h: Handle) {
         let need = h as usize + 1;
         if self.input.len() < need {
@@ -806,7 +660,7 @@ impl LayoutSolver {
         }
     }
 
-    /// Mark `h` as written this round (so [`begin`](Self::begin) will reset its slot).
+    /// Record `h` for [`begin`](Self::begin) to reset.
     fn touch(&mut self, h: Handle) {
         let i = h as usize;
         if !self.marked[i] {
@@ -815,7 +669,7 @@ impl LayoutSolver {
         }
     }
 
-    /// Start a round: reset every slot the previous round touched (O(nodes), not O(id space)).
+    /// Start a round, resetting only the slots the last round touched.
     pub fn begin(&mut self) {
         for &h in &self.touched {
             let i = h as usize;
@@ -834,17 +688,15 @@ impl LayoutSolver {
         self.unresolvable.clear();
     }
 
-    /// Seed a pre-resolved rect at `h` — an anchor target this solve does not compute (the screen
-    /// root, an already-resolved region). Also used to publish a rect mid-sweep so later nodes in
-    /// the same pass see it.
+    /// Seed a rect this solve does not compute, such as the screen root (`CSimpleTop`); also
+    /// publishes one mid-sweep for later nodes of the same pass.
     pub fn set_external(&mut self, h: Handle, rect: Rect) {
         self.ensure(h);
         self.touch(h);
         self.rect[h as usize] = Some(rect);
     }
 
-    /// Register a frame to solve, copying `src` into the solver's persistent slot (the anchors
-    /// `Vec` is refilled in place, so a steady round allocates nothing).
+    /// Register a frame to solve, copying `src` into its slot; a steady round allocates nothing.
     pub fn set_frame(&mut self, h: Handle, src: &LayoutInput) {
         self.ensure(h);
         self.touch(h);
@@ -856,9 +708,7 @@ impl LayoutSolver {
         self.live.push(h);
     }
 
-    /// [`set_frame`](Self::set_frame) with `src`'s anchors replaced by exactly `anchor` — the
-    /// ScrollFrame child override (decision 0112), which otherwise cost a full input clone plus a
-    /// one-element `Vec` per scroll child per round.
+    /// [`set_frame`](Self::set_frame) with `anchor` as the only anchor: a ScrollFrame child's.
     pub fn set_frame_anchored(&mut self, h: Handle, src: &LayoutInput, anchor: Anchor) {
         self.ensure(h);
         self.touch(h);
@@ -870,7 +720,6 @@ impl LayoutSolver {
         self.live.push(h);
     }
 
-    /// The non-anchor fields, copied verbatim.
     fn copy_fields(dst: &mut LayoutInput, src: &LayoutInput) {
         dst.width = src.width;
         dst.height = src.height;
@@ -880,18 +729,13 @@ impl LayoutSolver {
         dst.extent_y = src.extent_y;
     }
 
-    /// Resolve every registered frame in dependency order (each anchor target before its
-    /// dependents), detecting cycles. Cycle members are still resolved best-effort, ascending by
-    /// handle, against whatever rects were available — matching the map-backed driver this
-    /// replaces.
+    /// Resolve every registered frame, anchor targets first; cycle members then resolve
+    /// best-effort, ascending by handle, against the rects known by then.
     pub fn solve(&mut self) {
         self.live.sort_unstable();
 
-        // Frame→frame anchor edges. A dependency on an external or an unknown handle does not
-        // constrain ordering (its rect is fixed / missing, not produced by this pass); only
-        // frame→frame edges do. A self-anchor counts as an edge, so a self-referential frame is
-        // never emitted ⇒ reported as a cycle. Duplicate targets count once (an anchor slot set is
-        // at most 9, so the dedupe is a linear scan, not a set).
+        // Only frame-to-frame anchors order the pass. A self-anchor counts, so a self-anchored
+        // frame lands in `cycle`; a target named twice counts once.
         for idx in 0..self.live.len() {
             let h = self.live[idx];
             let mut seen: [Handle; 9] = [0; 9];
@@ -936,7 +780,7 @@ impl LayoutSolver {
             self.resolve_one(h);
         }
 
-        // Frames never emitted are on (or behind) a cycle; resolve them best-effort, ascending.
+        // A frame never emitted is on or behind a cycle.
         for idx in 0..self.live.len() {
             let h = self.live[idx];
             if !self.emitted[h as usize] {
@@ -946,7 +790,6 @@ impl LayoutSolver {
         }
     }
 
-    /// Resolve one frame against the rects known so far, recording failure.
     fn resolve_one(&mut self, h: Handle) {
         let outcome = {
             let input = &self.input[h as usize];
@@ -959,20 +802,18 @@ impl LayoutSolver {
         }
     }
 
-    /// The rect known at `h`: an external as seeded, or a frame's resolved rect. `None` if the
-    /// handle is unknown or its frame was under-constrained.
+    /// The rect at `h`: an external as seeded, a frame as resolved.
     #[inline]
     pub fn rect(&self, h: Handle) -> Option<Rect> {
         self.rect.get(h as usize).copied().flatten()
     }
 
-    /// Frames on (or behind) an anchor dependency cycle — no valid topological position. Ascending.
+    /// Frames on or behind an anchor cycle, ascending.
     pub fn cycle(&self) -> &[Handle] {
         &self.cycle
     }
 
-    /// Frames whose `assemble` returned unresolvable (under-constrained, or depending on an
-    /// unresolvable/missing target). May overlap [`cycle`](Self::cycle).
+    /// Frames that did not resolve; may overlap [`cycle`](Self::cycle).
     pub fn unresolvable(&self) -> &[Handle] {
         &self.unresolvable
     }
@@ -982,10 +823,8 @@ impl LayoutSolver {
 mod tests {
     use super::*;
 
-    // Screen-root handle used across tests; its rect is the physical screen (y-up).
     const SCREEN: Handle = 0;
     fn screen_rect() -> Rect {
-        // [bottom, left, top, right]
         Rect::new(0.0, 0.0, 600.0, 800.0)
     }
 
@@ -1007,12 +846,10 @@ mod tests {
     }
 
     // ── Leaf kernels ─────────────────────────────────────────────────────────────────────────
-    // Expected outputs are hand-computed from the formulas above — this crate has no `WoW.exe`
-    // emulator, so these are spec-derived, not binary-diffed.
+    // Expected values are hand-computed from the formulas, not taken from the client.
 
     #[test]
     fn combine_edge_legs() {
-        // (center, opp, span)
         assert_eq!(combine_edge(10.0, 50.0, 7.0), 57.0); // opp+span
         assert_eq!(combine_edge(10.0, f32::INFINITY, 7.0), 7.0 * 0.5 + 10.0); // span/2+center
         assert_eq!(combine_edge(10.0, 50.0, 0.0), (10.0 - 50.0) + 10.0); // 2c-opp = -30
@@ -1043,14 +880,13 @@ mod tests {
     #[test]
     fn anchor_resolve_x_columns() {
         let r = [3.0f32, 100.0, 480.0, 260.0]; // [bottom, left, top, right]
-                                               // relLeft, center, relRight (point-ids 0,1,2), scale 1, xOff 5
+                                               // point ids 0, 1, 2 (left, center, right), xOff 5
         assert_eq!(anchor_resolve_x(1.0, 5.0, 0, Some(r), false), 5.0 + 100.0);
         assert_eq!(
             anchor_resolve_x(1.0, 5.0, 1, Some(r), false),
             (260.0 + 100.0) * 0.5 + 5.0
         );
         assert_eq!(anchor_resolve_x(1.0, 5.0, 2, Some(r), false), 5.0 + 260.0);
-        // scale multiplies the offset
         assert_eq!(
             anchor_resolve_x(2.0, 5.0, 0, Some(r), false),
             2.0 * 5.0 + 100.0
@@ -1112,7 +948,7 @@ mod tests {
 
     // ── Composed resolver ─────────────────────────────────────────────────────────────────────
 
-    /// A numeric oracle for `assemble 0x767a20`, confirmed against a running `WoW.exe`.
+    /// The rect the running reference client's `assemble` (`0x767a20`) produced.
     #[test]
     fn oracle_single_topleft_explicit_size() {
         let f = LayoutInput::sized(
@@ -1126,16 +962,14 @@ mod tests {
             200.0,
             50.0,
         );
-        // screen root [0,0,600,800] (probe uses root top=600, right=800)
+        // The reference run's screen root: top 600, right 800.
         let got = resolve_rect(&f, |_| Some(Rect::new(0.0, 0.0, 600.0, 800.0)));
         assert_rect(got, Rect::new(545.0, 10.0, 595.0, 210.0));
     }
 
     #[test]
     fn single_anchor_all_nine_points_explicit_size() {
-        // For each own-point p, anchor p -> the same point on screen, xOff/yOff 0, w100 h40.
-        // The anchored corner/edge pins directly; the rest derive from size. We assert the pinned
-        // coordinate and the resulting width/height, computed by hand from the formulas above.
+        // Each point pinned to the same point on the screen: every leg must keep the 100x40 size.
         let screen = screen_rect();
         for &p in &[
             Point::TopLeft,
@@ -1154,7 +988,6 @@ mod tests {
                 ResolveOutcome::Resolved(r) => r,
                 ResolveOutcome::Unresolvable => panic!("{p:?} unresolvable"),
             };
-            // width/height always preserved
             assert_eq!(r.width().to_bits(), 100.0f32.to_bits(), "{p:?} width");
             assert_eq!(r.height().to_bits(), 40.0f32.to_bits(), "{p:?} height");
         }
@@ -1190,7 +1023,6 @@ mod tests {
 
     #[test]
     fn scale_interaction() {
-        // scale 2 -> offsets and size span doubled.
         let f = LayoutInput {
             anchors: vec![Anchor::new(
                 Point::TopLeft,
@@ -1266,8 +1098,7 @@ mod tests {
 
     #[test]
     fn unset_sentinel_propagates() {
-        // Anchor to a target with no valid rect (GetRect fail) -> that edge is +Inf -> frame
-        // unresolvable (single anchor, so opposite edges can't derive).
+        // The one anchor's target has no rect, so its edges are +Inf and nothing else pins them.
         let f = LayoutInput::sized(
             vec![Anchor::new(
                 Point::TopLeft,
@@ -1330,7 +1161,6 @@ mod tests {
         s.solve();
         assert!(s.cycle().contains(&A));
         assert!(s.cycle().contains(&B));
-        // neither can resolve (each depends on the other's rect, unavailable)
         assert!(s.unresolvable().contains(&A));
         assert!(s.unresolvable().contains(&B));
     }
@@ -1355,18 +1185,15 @@ mod tests {
     #[test]
     fn size_changed_epsilon() {
         let r = Rect::new(0.0, 0.0, 40.0, 100.0);
-        // sub-epsilon width change -> not fired
+        // 1e-7 is under SIZE_EPS.
         let tiny = Rect::new(0.0, 0.0, 40.0, 100.0 + 1e-7);
         assert!(!size_changed(r, tiny));
-        // supra-epsilon -> fired
         let big = Rect::new(0.0, 0.0, 40.0, 100.001);
         assert!(size_changed(r, big));
     }
 
-    /// The solver's buffers live across rounds, so `begin` must leave NO trace of the previous
-    /// one — a stale rect, in-degree, dependent edge, or `is_frame` flag would silently corrupt
-    /// the next solve. Round 2 registers a *disjoint* frame set that anchors to a handle round 1
-    /// used, and must see it as unknown (not round 1's rect).
+    /// The buffers live across rounds, so `begin` must leave nothing behind: round 2 anchors to a
+    /// handle only round 1 registered and must find it unknown.
     #[test]
     fn begin_leaves_no_state_from_the_previous_round() {
         const A: Handle = 1;
@@ -1402,8 +1229,7 @@ mod tests {
         let a_first = s.rect(A).expect("A resolved in round 1");
         assert!(s.rect(B).is_some());
 
-        // Round 2: ONLY B, still anchored to A — but A is no longer registered and no external
-        // seeds it, so B must be unresolvable rather than reusing round 1's stale A rect.
+        // Round 2: only B, whose target A is no longer registered.
         s.begin();
         s.set_external(SCREEN, screen_rect());
         s.set_frame(
@@ -1426,8 +1252,7 @@ mod tests {
         assert!(s.unresolvable().contains(&B));
         assert!(s.cycle().is_empty(), "cycle list must be cleared too");
 
-        // Round 3: the original pair again — identical results to round 1 (no accumulated
-        // in-degree or dependent edges from the rounds between).
+        // Round 3: the original pair again, which must match round 1.
         s.begin();
         s.set_external(SCREEN, screen_rect());
         s.set_frame(
@@ -1460,9 +1285,8 @@ mod tests {
         assert!(s.unresolvable().is_empty());
     }
 
-    /// A frame registered with the ScrollFrame override keeps its size/scale but drops its own
-    /// anchors for exactly the override (decision 0112) — and the slot's anchor `Vec` is reused,
-    /// so the previous round's anchors must not leak through.
+    /// The override keeps the size and scale but replaces the anchors, and the reused anchors `Vec`
+    /// must not leak the last round's.
     #[test]
     fn set_frame_anchored_replaces_only_the_anchors() {
         const A: Handle = 1;
@@ -1486,8 +1310,7 @@ mod tests {
             bits(Rect::new(0.0, 0.0, 600.0, 800.0))
         );
 
-        // Overridden: the two authored anchors are gone, replaced by one TOPLEFT pin at (10, -5),
-        // so the explicit 100x40 size now decides the other two edges.
+        // Overridden: one TOPLEFT pin at (10, -5), so the 100x40 size decides the other edges.
         s.begin();
         s.set_external(SCREEN, screen_rect());
         s.set_frame_anchored(
diff --git a/crates/benilla-ui/src/lib.rs b/crates/benilla-ui/src/lib.rs
index 0bb5bbbc..4af31f01 100644
--- a/crates/benilla-ui/src/lib.rs
+++ b/crates/benilla-ui/src/lib.rs
@@ -1,25 +1,5 @@
-//! The engine-free core of benilla's UI engine (decision 0068): the WoW interface is data + a
-//! runtime — TOC manifests, FrameXML documents, and Lua — and this crate owns everything about
-//! that runtime which needs neither Bevy nor a GPU: parsing, template expansion, the anchor/layout
-//! resolver, and the draw-order key. The Bevy side (rendering, input, the game-state API bindings)
-//! lives in the app; the Lua VM is embedded by the app and calls back into this crate's model.
-//!
-//! Built currently: [`toc`] — the addon/FrameXML manifest parser; [`framexml`] — the FrameXML
-//! document parser (order-preserving tree, template expansion, `$parent` substitution);
-//! [`bindings_xml`] — the per-addon `Bindings.xml` parser (the third file format, feeding
-//! [`script::keybind`]'s table); [`layout`]
-//! — the anchor/layout resolver (anchor graph → resolved rects), transcribed bit-faithfully from
-//! the reference; [`widget`] — the frame arena and its show/hide/strata/level/
-//! scale/alpha propagation mutations; [`order`] — the strata/draw-layer vocabulary, the packed
-//! total-order key, and the visible-tree traversal that realizes the client's painter order;
-//! [`script`] — the engine-free Lua host (mlua 5.1) binding the arena/layout/order model to the
-//! FrameScript object model + WoW stdlib so FrameXML/addon Lua runs against it (decision 0068);
-//! [`loader`] — the FrameXML loader that joins the two, walking a parsed document to materialize live
-//! frames in a running [`script::UiScript`] by driving the object model exactly as an addon does;
-//! [`markup`] — the single owner of WoW's inline-markup grammar (`|cAARRGGBB`, `|H…|h…|h`, `|n`,
-//! `||`): the client's token decoder and the per-byte class map its cursor law is built on;
-//! [`source`] — what a UI source file *is* before any parser sees it: bytes, BOM-stripped, decoded
-//! to text only where a Rust parser forces it (decision 1193).
+//! The engine-free core of benilla's UI: the `.toc`, FrameXML and `Bindings.xml` parsers, the
+//! layout resolver, the frame arena, draw order and the Lua host FrameXML runs in; no Bevy, no GPU.
 
 pub mod bindings_xml;
 pub mod civil;
diff --git a/crates/benilla-ui/src/loader/backdrop.rs b/crates/benilla-ui/src/loader/backdrop.rs
index 673df8e9..9b22381a 100644
--- a/crates/benilla-ui/src/loader/backdrop.rs
+++ b/crates/benilla-ui/src/loader/backdrop.rs
@@ -5,11 +5,9 @@ use crate::framexml::Element;
 use super::{abs_value, children_named, color_of, Loader};
 
 impl Loader<'_> {
-    /// `<Backdrop bgFile edgeFile tile>` + children `<EdgeSize>`/`<TileSize>`/`<BackgroundInsets>`/
-    /// `<Color>`/`<BorderColor>` (LoadXML `0x77e6c0`). Builds the same table Lua `SetBackdrop`
-    /// reads and installs it, then applies the two colors — the XML `<Color>` parser (`0x6f23d0`)
-    /// defaults a *present* element's missing channels to **black** (r=g=b=0, a=1 via
-    /// [`color_of`]), distinct from the ctor white a table `SetBackdrop` leaves.
+    /// `<Backdrop>` (LoadXML `0x77e6c0`): the table Lua `SetBackdrop` takes, then the two colours.
+    /// A present `<Color>` defaults a missing channel to black, alpha 1 (`0x6f23d0`), not the
+    /// white a table `SetBackdrop` leaves.
     pub(super) fn apply_backdrop(&mut self, el: &Element, wrapper: &Table, dbg: &str) {
         let Some(bd) = children_named(el, "Backdrop").next() else {
             return;
@@ -32,10 +30,8 @@ impl Loader<'_> {
         }
     }
 
-    /// Build the `SetBackdrop` table from a `<Backdrop>` element: `bgFile`/`edgeFile`/`tile` attrs,
-    /// `<EdgeSize>`/`<TileSize>` scalars ([`abs_value`]), and `<BackgroundInsets>` (an `<AbsInset>`
-    /// child or inline `left`/`right`/`top`/`bottom` attrs). Missing keys are simply absent — the
-    /// object-model `SetBackdrop` leaves the ctor default (tileSize 0, edgeSize 32, insets 0).
+    /// The `SetBackdrop` table for a `<Backdrop>`. A key the element omits stays absent, so
+    /// `SetBackdrop` keeps the ctor's default (tileSize 0, edgeSize 32, insets 0).
     pub(super) fn build_backdrop_table(&self, bd: &Element) -> mlua::Result<Table> {
         let t = self.lua().create_table()?;
         if let Some(f) = bd.attr("bgFile") {
diff --git a/crates/benilla-ui/src/loader/geometry.rs b/crates/benilla-ui/src/loader/geometry.rs
index d7aa26af..84d3a756 100644
--- a/crates/benilla-ui/src/loader/geometry.rs
+++ b/crates/benilla-ui/src/loader/geometry.rs
@@ -6,33 +6,15 @@ use super::regions::FontAttrs;
 use super::{abs_dim, children_named, Loader};
 
 impl Loader<'_> {
-    /// LoadXML attribute handling (`0x769820`): the subset the v1 object model exposes, plus a
-    /// warn-once for the attributes whose methods don't exist yet (a next-phase gap, not a workaround).
+    /// A frame element's LoadXML attributes and simple children (`0x769820`), and a model pane's
+    /// own (`0x76cac0`).
     pub(super) fn apply_attrs(&mut self, el: &Element, wrapper: &Table, dbg: &str) {
         if el.attr_bool("hidden") {
             self.call(wrapper, "Hide", (), dbg);
         }
-        // **An unrecognised `frameStrata=` WARNS and skips; it does not raise** (decision 2160).
-        //
-        // The two doors are genuinely different in the reference and this is the one that is
-        // quiet. `CSimpleFrame::LoadXML 0x769820` resolves the name through `0x6f17d0`, whose miss
-        // arm returns `eax = 0` without writing the caller's out-parameter (`0x6f17ff`); the miss
-        // leg then pushes `0x878658 "Frame %s: Unknown frame strata: %s"` at severity 1 into the
-        // document's `CStatus` sink (`0x7699a4 call [edx+0xc]`, which returns — all five `Add`
-        // implementations image-wide are raise-free) and **reconverges with the hit path at
-        // `0x7699ad`**, carrying straight on into `frameLevel` and the rest of the subtree.
-        // `SetFrameStrata 0x76a470` is called only on the hit arm (`0x769971`), so the frame keeps
-        // whatever stratum it already had — its template's, its parent's, or the ctor's MEDIUM
-        // (`[+0xc0] = 3` at `0x7690c2`).
-        //
-        // The **Lua** binding is the loud one and stays as it is: `0x774360`'s miss reaches
-        // `0x774456 call 0x6f4940` (`luaL_error`), whose callee chain `luaG_errormsg 0x6fc780` /
-        // `luaD_throw 0x6f5d80` contains no `ret` at all — the epilogue after it is dead code.
-        //
-        // Resolving here rather than letting `SetFrameStrata` raise is what reproduces that split:
-        // routed through `self.call`, a bad value became a `report.errors` row, which is a script
-        // error the player sees — and it cost `EQL3` its whole `EQL3_Log.xml`, on a `<Frame
-        // frameStrata="ARTWORK">` (a draw-LAYER name) the real client shrugs at.
+        // An unknown `frameStrata=` is logged (`0x7699a4`) and skipped, not raised as the Lua
+        // binding would (`0x774360`): `SetFrameStrata` runs only on a hit (`0x769971`), so the
+        // frame keeps the strata it had.
         if let Some(strata) = el.attr("frameStrata") {
             if crate::script::object::strata_from_str(strata).is_some() {
                 self.call(wrapper, "SetFrameStrata", strata.to_string(), dbg);
@@ -52,20 +34,8 @@ impl Loader<'_> {
                 self.call(wrapper, "SetAlpha", a, dbg);
             }
         }
-        // `scale=` on a MODEL pane is the model's own scale, not the frame's: `CSimpleModel::
-        // LoadXML` (`0x76cac0`) writes it into `+0x3a0` at `76cb61` — the field `SetModelScale`
-        // writes — and raises `Frame %s: Invalid model scale: %s` at `76cb92` for `≤ 0` (a raise,
-        // not a clamp). Every `scale=` in the shipped
-        // FrameXML sits on a model pane (the cooldown indicator's 0.75, the autocast shine's
-        // 1.2/1.22, the pings' 0.4, the dressing room's 2.0), and until decision 2007 the loader
-        // read none of them. Whether the generic frame loader (`0x769820`) reads a `scale`
-        // attribute of its own is unconfirmed; a plain frame's `scale=` is left as it was.
 
-        // `file=` on a model pane is `SetModel` (`CSimpleModel::LoadXML` `0x76cac0` installs the
-        // file into the widget, resident or streaming — decision 2013). Until 2013 no XML-declared
-        // pane ever held a file: the loader read `file=` only to turn the cooldown indicator's
-        // pane into a native widget of ours (retired by 2019), and the pings, the shine and the
-        // item card were bare panes to the engine.
+        // A model pane's `file=` is `SetModel` (`0x76cac0`).
         let model_kind = super::model_kind_tag(&el.tag);
         if model_kind {
             if let Some(file) = el.attr("file") {
@@ -73,6 +43,9 @@ impl Loader<'_> {
                 self.call(wrapper, "SetModel", text, dbg);
             }
         }
+        // A model pane's `scale=` is the model's scale, the field `SetModelScale` writes
+        // (`0x76cb61`); a value of 0 or less is refused, never clamped (`0x76cb92`). A plain
+        // frame's `scale=` is ignored; whether `0x769820` reads one is untraced.
         if let Some(scale) = el.attr("scale") {
             if model_kind {
                 match scale.trim().parse::<f32>() {
@@ -84,12 +57,8 @@ impl Loader<'_> {
                 }
             }
         }
-        // The model pane's own fog attributes and `<FogColor>` child (`CSimpleModel::LoadXML`
-        // `0x76cac0`). `fogNear`/`fogFar` are **clamped at `≥ 0`** here and only
-        // here (`76cbbb`-`76cbd2` / `76cbf3`-`76cc0a`: `0.0 fcomp value ; jne store ; else store
-        // 0.0`) — the Lua setters store raw. The `<FogColor>` child writes the packed colour AND
-        // arms the fog bit, so it is `SetFogColor` in every respect; nothing in XML touches the
-        // light. Decision 2027.
+        // A model pane's fog: `fogNear`/`fogFar` clamp at 0 here only (`0x76cbbb`, `0x76cbf3`),
+        // where the Lua setters store raw; `<FogColor>` is `SetFogColor`, fog bit included.
         if model_kind {
             for (attr, verb) in [("fogNear", "SetFogNear"), ("fogFar", "SetFogFar")] {
                 if let Some(v) = el.attr(attr).and_then(|v| v.trim().parse::<f32>().ok()) {
@@ -115,22 +84,14 @@ impl Loader<'_> {
                 self.call(wrapper, "SetID", n, dbg);
             }
         }
-        // `clampedToScreen="true"` → SetClampedToScreen (`0x768cc0` — geometry flags bit4,
-        // the layout resolve's screen clamp; GameTooltip frames carry it by construction).
+        // `clampedToScreen`: the layout's screen clamp, geometry flag bit 4 (`0x768cc0`).
         if el.attr_bool("clampedToScreen") {
             self.call(wrapper, "SetClampedToScreen", true, dbg);
         }
-        // `enableMouse` lands as the real EnableMouse call (the hit test gates on it —
-        // pointer.rs): a ref frame authored mouse-blocking (StaticPopup, BlackoutWorld, the
-        // minimap cluster) must actually capture. The loader ignored it for a while after the
-        // native landed — the stale "v1 gap" note here — which left those frames click-through
-        // and the minimap deaf to its ping click (0434 phase 6c's root cause).
         if el.attr_bool("enableMouse") {
             self.call(wrapper, "EnableMouse", true, dbg);
         }
-        // `<HitRectInsets><AbsInset left= right= top= bottom=/></HitRectInsets>` (also accepted
-        // inline on the element) → SetHitRectInsets: the frame's MOUSE rect, inset from its
-        // resolved rect. Absent sides read 0, so a partial element insets only what it names.
+        // `<HitRectInsets>`: the mouse rect, inset from the frame's; a side it omits is 0.
         if let Some(ins) = children_named(el, "HitRectInsets").next() {
             let src = children_named(ins, "AbsInset").next().unwrap_or(ins);
             let side = |k: &str| {
@@ -145,70 +106,33 @@ impl Loader<'_> {
                 dbg,
             );
         }
-        // `<ResizeBounds><minResize><AbsDimension x= y=/></minResize><maxResize>…` → the resize
-        // quad (`0x769820`'s child-loop arm at `0x769baa`). Three clauses from the reference
-        // rather than from the shape of the element:
-        //
-        //  · **Both pairs are written unconditionally once `<ResizeBounds>` matches**, each side
-        //    defaulting to `0` before its lookup — so a block carrying only `<minResize>` RESETS
-        //    the max pair to unbounded. That is why this writes both calls, never just the one it
-        //    found.
-        //  · `x` is the WIDTH and `y` the HEIGHT, through the same logical→internal transform
-        //    `<Size>` uses — the same `abs_dim` reader, and the same inline-or-`AbsDimension` pair
-        //    of forms.
-        //  · `<Size>` and `<Anchors>` are consumed by the base-class `CLayoutFrame::LoadXML`
-        //    *before* the child loop is entered at all, so they always precede this structurally
-        //    whatever the document order — and neither path clamps, so an authored `<Size>`
-        //    outside the authored bounds survives load unchanged.
-        //
-        // The shipped 1.12.1 FrameXML uses it exactly once (`FloatingChatFrame.xml:223`,
-        // min 296×75 / max 608×400) and never calls the Lua setters at all.
+        // `<ResizeBounds>` (`0x769baa`): both pairs are always written, an absent one as 0, so a
+        // lone `<minResize>` resets the max to unbounded. A `<Size>` outside them is not clamped.
         if let Some(rb) = children_named(el, "ResizeBounds").next() {
             for (tag, verb) in [("minResize", "SetMinResize"), ("maxResize", "SetMaxResize")] {
                 let (x, y) = children_named(rb, tag).next().map_or((None, None), abs_dim);
                 self.call(wrapper, verb, (x.unwrap_or(0.0), y.unwrap_or(0.0)), dbg);
             }
         }
-        // `movable`/`resizable` → SetMovable/SetResizable — the same flag word the methods write
-        // (`0x76a3c0` with mask 0x100 / 0x200; the XML loader `0x769820` calls that very setter).
-        // Both were in the gap list below until the movable family
-        // landed; leaving them there would have left every `movable="true"` reference window
-        // undraggable while `SetMovable` worked from Lua.
+        // `movable`/`resizable`: flag bits 0x100/0x200, via the setter Lua uses (`0x76a3c0`).
         if el.attr_bool("movable") {
             self.call(wrapper, "SetMovable", true, dbg);
         }
         if el.attr_bool("resizable") {
             self.call(wrapper, "SetResizable", true, dbg);
         }
-        // `toplevel` → SetToplevel — the third bit of that same flag word (`0x76a3c0` mask `0x1`,
-        // XML site `0x7698ec`), and the third attribute to
-        // graduate out of the gap list below for the same reason: the raise law is built
-        // (`script::object::toplevel`), so accepting the attribute now means the behaviour, not
-        // silence. 82 corpus addons and thirteen of our own frames declare it.
+        // `toplevel`: bit 0x1 of the same flag word (`0x7698ec`).
         if el.attr_bool("toplevel") {
             self.call(wrapper, "SetToplevel", true, dbg);
         }
-        // `enableKeyboard="true"` — the XML half of the flag, which enables BOTH key kinds
-        // (`0x769ae8`/`0x769af3`). The flag is real, and `script::keyboard`'s delivery
-        // walk is what reads it (1319).
+        // `enableKeyboard` enables both key kinds (`0x769ae8`, `0x769af3`).
         if el.attr_bool("enableKeyboard") {
             self.call(wrapper, "EnableKeyboard", true, dbg);
         }
     }
 
-    /// `<Size>` → SetWidth/SetHeight (`0x767800`). Accepts either `<Size><AbsDimension x= y=/>`
-    /// or the inline `<Size x= y=/>` form; a dimension that's absent is left untouched (the client's
-    /// "0 = derive"). ALL `<Size>` children apply, in document order — template expansion appends the
-    /// instance's children after the template's ([`crate::framexml::expand`]), and the client simply
-    /// processes each child in turn, so an instance's own `<Size>` overwrites its template's. (Taking
-    /// only `.next()` here silently pinned every templated frame to the TEMPLATE's size; caught on
-    /// the quest log's Abandon button — 125×21 in the instance XML, 80×22 on screen.)
-    /// `<TitleRegion setAllPoints="true"/>` (or one with its own `<Size>`/`<Anchors>`): the
-    /// frame's drag handle, built through the same `CreateTitleRegion` the Lua API exposes — so
-    /// the element and a later `frame:CreateTitleRegion()` name ONE object (XML site `0x769b2a`
-    /// is the same code path as `CreateTitleRegion 0x773910`, idempotent) — then laid out like
-    /// any region.
-    /// The stock `TutorialFrame.xml` declares one over its whole plate (1976).
+    /// `<TitleRegion>`: the drag handle, built through the idempotent `CreateTitleRegion` so the
+    /// element and a later Lua call name one object (`0x769b2a` takes `0x773910`'s path).
     pub(super) fn apply_title_region(
         &mut self,
         el: &Element,
@@ -231,6 +155,8 @@ impl Loader<'_> {
         self.apply_region_layout(tr, &region, self_name, dbg, FontAttrs::Own);
     }
 
+    /// `<Size>` (`0x767800`). Every one applies in document order, and expansion puts an
+    /// instance's children after its template's, so the instance's own `<Size>` wins.
     pub(super) fn apply_size(&mut self, el: &Element, wrapper: &Table, dbg: &str) {
         for size in children_named(el, "Size") {
             let (x, y) = abs_dim(size);
@@ -243,13 +169,9 @@ impl Loader<'_> {
         }
     }
 
-    /// `<Anchors>` → SetPoint per `<Anchor point= relativeTo= relativePoint=><Offset .../></Anchor>`
-    /// (`0x767800`). `relativePoint` defaults to `point`; `relativeTo` is `$parent`-substituted
-    /// (`0x76c5b0`) and passed by name (the object model resolves it, falling back to the parent
-    /// when absent/unresolved); a missing `point` is skipped with a warning ("Invalid anchor
-    /// point").
-    /// The `setAllPoints="true"` shorthand applies first, like the region path — a frame carrying
-    /// only the attribute (WorldMapFrame's chrome layers) pins TOPLEFT+BOTTOMRIGHT to its parent.
+    /// `<Anchors>` (`0x767800`), after the `setAllPoints` shorthand: `relativePoint` defaults to
+    /// `point`, and `relativeTo` expands `$parent` to the nearest named ancestor's name, else
+    /// `Top` (`0x76c5b0`).
     pub(super) fn apply_anchors(
         &mut self,
         el: &Element,
@@ -289,8 +211,7 @@ impl Loader<'_> {
                     args,
                     dbg: dbg.to_string(),
                 };
-                // The XML path's own law, which resolves the name itself and defers a target
-                // the enclosing frame's subtree has not built yet (`Loader::apply_anchor`).
+                // Deferred while the enclosing subtree has not built its target yet.
                 self.apply_anchor(d, true);
             }
         }
diff --git a/crates/benilla-ui/src/loader/mod.rs b/crates/benilla-ui/src/loader/mod.rs
index 3fd125c6..435bbff9 100644
--- a/crates/benilla-ui/src/loader/mod.rs
+++ b/crates/benilla-ui/src/loader/mod.rs
@@ -1,58 +1,12 @@
-//! The FrameXML **loader** (decision 0068): the join between the document layer ([`crate::framexml`])
-//! and the runtime ([`crate::script`]). It walks a parsed FrameXML document and *materializes* it —
-//! turning `<Include>`/`<Script>` sequencing, template instances, `<Layers>` regions, nested
-//! `<Frames>`, and `<Scripts>` handlers into live frames in a running [`UiScript`] — by driving the
-//! FrameScript object model exactly as an addon does (the `CreateFrame` global + the widget/region
-//! method surface installed in [`crate::script`]), never by reaching into the arena directly.
+//! The FrameXML loader: builds live frames from a parsed document ([`crate::framexml`]) by driving
+//! the Lua object model ([`crate::script`]) as an addon does, never the arena directly.
 //!
-//! ## Ground truth (`0x6edc00–0x6f3000`)
+//! The caller's `files` provider supplies bytes, so the loader does no IO; a `<Script file=>`
+//! chunk reaches Lua as the bytes on disk, as `luaL_loadbuffer` receives them. The loader joins a
+//! relative path to its file's directory ([`join_ref`]); the provider decides what it may reach.
 //!
-//! - The element→op map this module transcribes: the top-level `<Include>`/`<Script>`/`<Font>`/
-//!   frame routing (`0x6ede10`), `LoadXML` attribute handling
-//!   (`hidden`/`toplevel`/`movable`/`frameStrata`/`frameLevel`/`alpha`/`enableMouse`, `0x769820`),
-//!   `<Size>` + `<Anchors>` → `SetWidth`/`SetHeight`/`SetPoint` (`0x767800`), and
-//!   `<Layers>`/`<Layer>`/`<Texture>`/`<FontString>` (`0x769d70`), `<Scripts>` → `SetScript`
-//!   (`0x769ef0`).
-//! - `LoadChildFrames 0x76a060`: nested `<Frames>` is a post-load pass that gives **bottom-up
-//!   `OnLoad` ordering** (a frame's children are fully built, and their `OnLoad`s fired, *before*
-//!   the parent's `OnLoad` runs).
-//! - `SetName 0x76c650` / the `$parent` token, applied here (via
-//!   [`crate::framexml::resolve_name`]) to frame/region names and to anchor `relativeTo`.
-//!
-//! ## The engine-free seam
-//!
-//! `<Include>`/`<Script file=>` need file bytes, which this crate must not read itself (no Bevy, no
-//! IO — decision 0068 §1). The app supplies a `files` closure that resolves a FrameXML path to its
-//! **bytes** (from the MPQ/addon dir); the loader stays IO-free.
-//!
-//! **Bytes, not text** (decision 1193). A `<Script file=>` chunk is handed to Lua as the bytes on
-//! disk, exactly as the reference's `luaL_loadbuffer` receives them; only an `<Include>`d document
-//! is decoded ([`crate::source::decode`]), because roxmltree needs `&str` and Lua does not. Before
-//! 1193 the provider returned `String`, so a cp1252 locale file did not lose a glyph — it read as
-//! *absent*, and the include or every handler in the script vanished with it.
-//!
-//! **The loader owns relative-path resolution; the provider owns the root** (decision 1186). A
-//! reference is relative to the directory of the *file that contains it*, and may walk up with `..`
-//! — `Bagnon/src/main.xml` reaches its sibling as `templates.xml` and a shared library addon as
-//! `..\..\BagBrother\core\core.xml`. Only the loader knows the include tree, so it does the joining
-//! ([`join_ref`]) and hands the provider one already-resolved path; the provider decides what that
-//! path is allowed to reach. [`load`] starts at the root, [`load_in`] starts at a named directory.
-//!
-//! A path with **no provider hit gets its own list**, [`LoadReport::missing_files`] — neither a
-//! warning nor an error (decision 2155). It was a warning until 1186, and the cost was that an
-//! addon which resolved *nothing* reported success — Bagnon missed all eleven of its references
-//! and came back with zero errors. 1186 answered that by calling it an error, which fixed the
-//! visibility and got the *severity* wrong the other way: the reference logs `"Couldn't open %s"`
-//! and carries on, with nothing raised, so an addon shipping an incomplete package was scoring as
-//! a client script error and reaching the player's red error dialog. Both facts are true and they
-//! need two different lists. The load continues either way (0068: the client logs and carries on).
-//!
-//! ## MAXCSTACK discipline (decision 0068, probe A)
-//!
-//! Like the host it drives, the loader holds **no** breadth-wise accumulation of Lua handles: a
-//! frame's wrapper `Table` and its (optional) `OnLoad` `Function` live only on the Rust stack across
-//! *that frame's own* subtree build (depth-bounded), and region wrappers are dropped as soon as their
-//! visuals are applied. Everything durable lives Lua-side in the host's registry.
+//! Lua handles are never accumulated breadth-wise (MAXCSTACK): a frame's wrapper and `OnLoad`
+//! live only across its own subtree build, and everything durable lives Lua-side.
 
 use std::collections::{HashMap, HashSet};
 
@@ -67,63 +21,28 @@ mod regions;
 mod scripts;
 mod widgets;
 
-/// The outcome of a [`load`]: what went wrong tolerably (`warnings`), what went wrong that dropped
-/// something (`errors`), and how much got built (`frames`). Never a panic and never an abort — a bad
-/// handler body, an unknown frame type, a missing include, or an unsupported attribute is an entry
-/// here and the load continues (decision 0068: the client logs-and-continues; so do we).
+/// The outcome of a [`load`]; nothing aborts a load, as the reference logs and continues.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct LoadReport {
-    /// Tolerable issues: a missing include/script provider, an unsupported-in-v1 attribute or script
-    /// handler, an unregistered `inherits=` font object, and the parse/expand warnings folded in from
-    /// the document layer. None of these dropped a frame — except one, on purpose: an **unknown
-    /// frame type** drops its own node here rather than in `errors`, because that is the channel
-    /// the reference uses for it at the XML door (`0x6ee356`, logged and non-fatal; decision 2191).
+    /// Issues that dropped nothing, and the document layer's parse warnings. An unknown frame type
+    /// drops its node yet lands here: the reference logs it and goes on (`0x6ee356`).
     pub warnings: Vec<String>,
-    /// Things that dropped a frame or a handler and that the reference RAISES on: a handler that
-    /// failed to compile, a method call that errored, a malformed included document.
+    /// Failures the reference raises on: a handler that fails to compile, a method call that
+    /// errors, a malformed included document.
     pub errors: Vec<String>,
-    /// **A named file the provider does not have** — an `<Include file=>` or `<Script file=>` whose
-    /// resolved path hit nothing (decision 2155).
-    ///
-    /// Its own list because it is its own severity, and 1186 put it in the wrong one. The reference
-    /// does not raise here: `0x6edaa0` logs `"Couldn't open %s"` (`0x846ff4`) and returns null, the
-    /// `<Include>` arm never tests the recursion's result (`0x6ee00d` → `0x6ee012`), and the
-    /// `<Script>` leg reports `"Error loading %s"` (`0x872e50`) and returns 0 — every failure leg
-    /// reports through the sink and returns normally, with no throw and no `longjmp`. This is the
-    /// same rule 2107 unified for the `.toc` walk and the demand load, at the two doors 2107 did
-    /// not reach.
-    ///
-    /// **1186's finding is preserved and it is why this is not simply folded into
-    /// [`Self::warnings`]:** a document that resolved *nothing* must not report success — Bagnon
-    /// missed all eleven of its references and came back with zero errors. It still reports them,
-    /// under a name that says which kind of failure it is, and the caller decides severity by
-    /// whose manifest lied (`ui_script::addons`: ours is an `error!`, a player's addon a `warn!`,
-    /// both retained where the player can read them and neither raising a script error).
+    /// `<Include file=>` and `<Script file=>` paths the provider lacks. The reference logs
+    /// `"Couldn't open %s"` (`0x6edaa0`, `0x846ff4`) or `"Error loading %s"` (`0x872e50`) and goes
+    /// on (`0x6ee00d`); kept apart from `warnings` so a load that resolved nothing is not clean.
     pub missing_files: Vec<String>,
-    /// How many frame instances were successfully created (`CreateFrame` returned a wrapper) — the
-    /// coverage number the real-file smoke test reports.
+    /// Frame instances `CreateFrame` built.
     pub frames: usize,
-    /// **The loader's trace lines, emitted only while `FrameXML_Debug` is on** (decision 2160).
-    ///
-    /// Empty in every normal load, which is the reference's own default: `[0xceea30]` boots at 0
-    /// and each of the loader's five trace sites is gated `flag > 0` (`0x6ee298 jle`). Its own
-    /// list rather than a `warnings` row because a trace is not a defect — the reference files it
-    /// into the same per-document record at severity **0**, one below the `frameStrata` warning's
-    /// severity 1.
+    /// Trace lines, only while `FrameXML_Debug` is on: the reference's flag (`[0xceea30]`) boots 0
+    /// and its loader traces gate on `flag > 0` (`0x6ee298`). A trace is severity 0, not a warning.
     pub traces: Vec<String>,
 }
 
-/// Materialize a parsed FrameXML document into live frames in `script`.
-///
-/// Walks `doc.items` in document order (`0x6ede10`, top level): `<Include>` resolves via
-/// `files` and recurses; `<Script file=>`/inline `<Script>` run through the host **in order** (this is
-/// how XML-referenced FrameXML Lua loads); `<Font>` resolves + registers a named font object
-/// ([`Loader::do_font`]); a `virtual` template is registered for later `inherits=`; a non-virtual
-/// instance is expanded ([`crate::framexml::expand`]) and materialized.
-///
-/// `files` is the engine-free seam (see module docs): it resolves a FrameXML/Lua path to its
-/// **bytes**. Returning `None` yields a [`LoadReport::missing_files`] row — reported, but not an
-/// error, because nothing raised (decision 2155).
+/// Materialize a parsed FrameXML document into live frames in `script`, in document order
+/// (`0x6ede10`). `files` returns a path's bytes; a `None` is a [`LoadReport::missing_files`] row.
 pub fn load(
     script: &UiScript,
     doc: &ParsedDocument,
@@ -132,20 +51,8 @@ pub fn load(
     load_in(script, doc, "", files)
 }
 
-/// [`load`] for a document that does **not** sit at the provider's root.
-///
-/// `path` is the document's **own path** in the provider's path space (`/`-separated; `""` for a
-/// document with no path, which only tests have). Its directory is what every `<Include>`/`<Script
-/// file=>` inside resolves against, and each nested include resolves against *its* own directory in
-/// turn — so an addon whose manifest lists `src\main.xml` passes `"<Addon>/src/main.xml"` here and
-/// its `<Include file="templates.xml">` reaches `<Addon>/src/templates.xml` (decision 1186).
-///
-/// **The path, not the directory, because the loader has to be able to say where a raise came
-/// from.** Every `<Script>` chunk is named after the file carrying it; an unnamed chunk takes
-/// mlua's `#[track_caller]` default, which is *this file's* Rust source line, and 26 of the corpus
-/// survey's 70 readable failures pointed at `crates/benilla-ui/src/loader/mod.rs` instead of the
-/// addon (decision 1217). Three callers used to derive this directory themselves with the same
-/// three lines; they pass the path now and [`dir_of`] does it once.
+/// [`load`] for a document at `path` in the provider's path space (`/`-separated, `""` for none),
+/// which its relative references resolve against and its inline `<Script>` chunks are named after.
 pub fn load_in(
     script: &UiScript,
     doc: &ParsedDocument,
@@ -155,9 +62,7 @@ pub fn load_in(
     load_into(script.lua(), doc, path, files)
 }
 
-/// [`load_in`] against the VM directly, for a caller that holds `&Lua` rather than `&UiScript` —
-/// which is every Lua binding, and therefore `LoadAddOn` (1188 phase 2). Identical behaviour;
-/// `load_in` is the same call with the script's own VM.
+/// [`load_in`] on the VM directly, for a Lua binding (`LoadAddOn`), which holds only `&Lua`.
 pub fn load_into(
     lua: &mlua::Lua,
     doc: &ParsedDocument,
@@ -172,51 +77,22 @@ pub fn load_into(
         warned: HashSet::new(),
         deferred_anchors: Vec::new(),
     };
-    // Fold the document layer's own parse warnings in (decision 0068: reuse framexml's warnings).
     loader.report.warnings.extend(doc.warnings.iter().cloned());
     loader.load_doc(doc);
     loader.report
 }
 
-/// Apply a **template** to a frame that already exists — the runtime half of `inherits=`.
-///
-/// This is the fourth argument of `CreateFrame(kind, name, parent, "UIPanelButtonTemplate")`, and
-/// it is the single most common way an addon builds anything. `wrapper` is the frame the binding
-/// has just created, `kind` is the kind string it was given, and `template` is the raw — possibly
-/// comma-separated — `inherits=` list. Returns the messages worth surfacing (warnings first, then
-/// the errors that dropped something); the caller decides where they go. Nothing here can fail
-/// the call.
-///
-/// **The caller's own name wins, and that is the load-bearing part.** `CreateFrame("Button",
-/// "MyButton", p, "SomeTemplate")` is a frame named `MyButton`, so the template's `$parentText`
-/// resolves to `MyButtonText` — which is the global the addon's very next line calls `getglobal`
-/// on. A template whose children came out named after the *template* would be useless.
-///
-/// **The frame is never dropped, whatever the template turns out to be.** Four cases, each a
-/// message and a usable frame:
-/// - an **unknown** name — the reference creates the frame anyway, so we do;
-/// - a name whose element was **not `virtual="true"`** — only virtual elements are ever registered
-///   ([`Loader::load_doc`]), so from the registry's side it is indistinguishable from unknown, and
-///   it reads as unknown;
-/// - a **region** template (a virtual `<Texture>`/`<FontString>`) where a frame was asked for —
-///   its frame-shaped content (`<Size>`, `<Anchors>`) still applies, its region-only content
-///   cannot, and it says so;
-/// - a **kind that disagrees with the template's tag** — the frame already exists as the kind
-///   `CreateFrame` was given and no template can retype it, so [`framexml::inherits_node`] keeps
-///   the caller's kind and the per-kind passes skip what would not apply. Named, not pretended.
-///
-/// **Why this cannot simply call [`Loader::materialize`]:** materialize's step 1 *is*
-/// `CreateFrame`, and this runs from inside that binding — it would recurse forever. The steps
-/// after it are [`Loader::decorate`], which is what both entry points share.
-///
-/// Reachable from a Lua binding at all only because decision 1191 §4 made the loader `&Lua`-native.
+/// Apply a template to an existing frame, `CreateFrame`'s fourth argument. Returns the warnings,
+/// then the errors. The frame always survives: an unknown name leaves it bare, as in the
+/// reference, and only virtual elements are registered. The frame's own name is the `$parent`
+/// base (`MyButton` makes `$parentText` `MyButtonText`). Runs inside the `CreateFrame` binding, so
+/// it enters at [`Loader::decorate`]: [`Loader::materialize`] would recurse.
 pub fn apply_template(lua: &mlua::Lua, wrapper: &Table, kind: &str, template: &str) -> Vec<String> {
     let template = template.trim();
     if template.is_empty() {
         return Vec::new();
     }
-    // A template is a node in the registry, never a file: `<Include>`/`<Script file=>` are
-    // top-level-only, so nothing reachable under `decorate` can ask for bytes.
+    // A template never reads a file: `<Include>` and `<Script file=>` are top-level only.
     let no_files = |_: &str| -> Option<Vec<u8>> { None };
     let mut loader = Loader {
         lua,
@@ -234,18 +110,14 @@ pub fn apply_template(lua: &mlua::Lua, wrapper: &Table, kind: &str, template: &s
         own_name.as_deref().unwrap_or("<unnamed>")
     );
 
-    // The one thing `expand` cannot tell us: what kind each named template was *declared* as. Read
-    // it straight off the registry — a diagnostic pass only; the resolution below is still the
-    // document layer's single implementation.
+    // Diagnostic only: `expand` does not say what kind a template was declared as.
     let mut notes = Vec::new();
     let mut any_resolved = false;
     {
         let model = loader.model();
         let templates = model.framexml_templates.borrow();
-        // One name, verbatim, folded — the same law `framexml::expand` resolves under, kept in
-        // step so this diagnostic cannot disagree with the resolution it describes.
+        // Looked up as `framexml::expand` looks it up (exact, then case-folded); keep them in step.
         for name in [template].into_iter().filter(|s| !s.is_empty()) {
-            // A name that is missing entirely is `expand`'s warning to give, just below.
             let Some(el) = templates.get(name).or_else(|| {
                 templates
                     .iter()
@@ -278,10 +150,7 @@ pub fn apply_template(lua: &mlua::Lua, wrapper: &Table, kind: &str, template: &s
     }
     loader.report.warnings.extend(notes);
 
-    // One expansion, through the document layer's own splice/chain/cycle path — the same call the
-    // XML `inherits=` path makes. Its warnings are terse by design (they were written for a
-    // document walk), so prefix the ones this call produced: a log line has to name the
-    // `CreateFrame` it came from or nobody can act on it.
+    // The XML `inherits=` expansion; its warnings get the `CreateFrame` call as a prefix.
     let first = loader.report.warnings.len();
     let expanded = loader.expand(&framexml::inherits_node(kind, template));
     for w in &mut loader.report.warnings[first..] {
@@ -295,16 +164,8 @@ pub fn apply_template(lua: &mlua::Lua, wrapper: &Table, kind: &str, template: &s
     out
 }
 
-/// Join a FrameXML reference against the directory of the file that contains it, **lexically**.
-///
-/// FrameXML paths are `\`- or `/`-separated and may walk up with `..` — that is how a shared
-/// library addon is reached (`..\..\BagBrother\core\core.xml`). Resolution here touches no
-/// filesystem and follows no symlink: it is pure string arithmetic, so the provider is the only
-/// thing that decides what a resolved path may reach.
-///
-/// A `..` that walks above the root is **kept** as a leading `..` rather than clamped, so the
-/// provider can see the escape and refuse it instead of silently being handed a path that looks
-/// contained.
+/// Join a FrameXML reference to its file's directory, lexically: `\` and `/` both separate, `..`
+/// walks up. A `..` above the root is kept, not clamped, so the provider can refuse the escape.
 pub fn join_ref(base: &str, path: &str) -> String {
     let path = path.replace('\\', "/");
     let combined = if path.starts_with('/') || base.is_empty() {
@@ -328,27 +189,21 @@ pub fn join_ref(base: &str, path: &str) -> String {
     out.join("/")
 }
 
-/// Is `tag` one of the four model-pane kinds — the `CSimpleModel` family, whose own `LoadXML`
-/// (`0x76cac0`) reads the `scale=` attribute into the MODEL scale (`geometry.rs`'s
-/// `apply_attrs`, decision 2007).
+/// A `CSimpleModel` kind, whose `LoadXML` (`0x76cac0`) reads `scale=` as the model's scale.
 pub(super) fn model_kind_tag(tag: &str) -> bool {
     ["Model", "PlayerModel", "DressUpModel", "TabardModel"]
         .iter()
         .any(|k| k.eq_ignore_ascii_case(tag))
 }
 
-/// The `.lua` test `0x6ede10` opens with: `strrchr(path, '.')` on the **whole resolved path**,
-/// then a **case-insensitive** compare against `".lua"` (`0x8710c8`, through `0x64a4c0`).
-///
-/// Deliberately the last dot anywhere in the path rather than the basename's, because that is what
-/// `strrchr` does — a directory carrying a dot and a file carrying none would take the same branch
-/// in the client as it does here.
+/// The `.lua` test `0x6ede10` opens with: the last `.` anywhere in the resolved path, not the
+/// basename's (`strrchr`), compared case-insensitively to `".lua"` (`0x8710c8`, via `0x64a4c0`).
 fn has_lua_suffix(path: &str) -> bool {
     path.rsplit_once('.')
         .is_some_and(|(_, ext)| ext.eq_ignore_ascii_case("lua"))
 }
 
-/// The directory part of a provider path — `""` for a bare name.
+/// The directory part of a provider path, `""` for a bare name.
 fn dir_of(path: &str) -> &str {
     match path.rfind('/') {
         Some(i) => &path[..i],
@@ -357,41 +212,27 @@ fn dir_of(path: &str) -> &str {
 }
 
 struct Loader<'a> {
-    /// **The VM itself, not a `UiScript`** — every piece of state this loader touches
-    /// (the two FrameXML registries, the font objects, the chunk runner) is reachable from a bare
-    /// `&Lua` through [`Model`]. That is what lets `LoadAddOn` load an addon from inside a Lua
-    /// binding, synchronously, the way the reference does (1188 phase 2): a binding is handed
-    /// `&Lua` and can never obtain the `&UiScript` that owns it.
+    /// The VM, not a `UiScript`: a Lua binding such as `LoadAddOn` holds only `&Lua`, and loads
+    /// an addon synchronously from inside the binding, as the reference does.
     pub(super) lua: &'a mlua::Lua,
     pub(super) files: &'a dyn Fn(&str) -> Option<Vec<u8>>,
-    /// The current document's own path in the provider's path space. Its **directory**
-    /// ([`Loader::base`]) is what a relative `<Include>`/`<Script file=>` inside it resolves
-    /// against; its **whole path** is what names an inline `<Script>`'s chunk. Saved and restored
-    /// around each nested include, so depth-1 and depth-5 both resolve — and report — against
-    /// their own file.
+    /// The current document's path: its directory resolves relative references, the whole path
+    /// names inline `<Script>` chunks. Swapped for each nested include and restored after.
     pub(super) path: String,
-    // The template + font-element registries live on the `Model` (`framexml_templates` /
-    // `framexml_fonts`), persisted ACROSS `load` calls — the client's template table is global
-    // (`0x6ee500`), so a file may `inherits=` a template an earlier file registered (the real
-    // MerchantFrame.xml ← CharacterFrameTemplates.xml). "Register before use" in load order,
-    // including through `<Include>`s. Fonts are a separate namespace (a font inherits a font,
-    // never a frame template); each stored font element is already inherits-resolved so a later
-    // font inheriting it reads fully-flattened values.
+    // The template and font registries live on the `Model` and persist across loads: the
+    // reference's template table is global (`0x6ee500`), so `MerchantFrame.xml` inherits a template
+    // `CharacterFrameTemplates.xml` registered. Fonts are their own namespace, stored flattened.
     pub(super) report: LoadReport,
-    /// Warn-once keys (so a document with 200 `OnClick` handlers doesn't emit 200 identical warnings).
+    /// Warn-once keys.
     pub(super) warned: HashSet<String>,
-    /// Anchors whose named `relativeTo` did not resolve when its element was read, applied once
-    /// the enclosing frame's subtree exists ([`Loader::drain_deferred_anchors`]). The real
-    /// client is order-free here because it resolves anchors at layout, after every child of
-    /// the frame is built; this loader resolves a name at `SetPoint` time, so a `<ButtonText>`
-    /// hung off a `<HighlightTexture>` declared after it (the stock trainer row) — or a state
-    /// texture hung off the label declared after IT (the sort-header arrow) — needs the same
-    /// grace. Each entry belongs to the `decorate` that pushed it and drains there, so a nested
-    /// frame's anchors never wait for its parent (1957).
+    /// Anchors whose named `relativeTo` did not exist yet, applied once the enclosing frame's
+    /// subtree is built: the reference resolves anchors at layout, this loader at `SetPoint`, so a
+    /// target built later waits here (`ClassTrainerFrameTemplates.xml:67` hangs the label off the
+    /// highlight). Each `decorate` drains its own.
     pub(super) deferred_anchors: Vec<DeferredAnchor>,
 }
 
-/// One `SetPoint` the loader holds until its target can exist — see `Loader::deferred_anchors`.
+/// One `SetPoint` held until its target exists.
 pub(super) struct DeferredAnchor {
     pub(super) wrapper: Table,
     /// A region wrapper (`call_region`) rather than a frame's (`call`).
@@ -405,33 +246,20 @@ impl Loader<'_> {
         self.lua
     }
 
-    /// The current document's own directory — what a relative `<Include>`/`<Script file=>` inside
-    /// it resolves against.
+    /// The current document's directory, which its relative references resolve against.
     fn base(&self) -> &str {
         dir_of(&self.path)
     }
 
-    /// Run a chunk in the one global state — `UiScript::run`'s body, reachable from `&Lua`.
-    ///
-    /// Takes **bytes**, because a `<Script file=>` chunk is whatever is on disk (decision 1193) and
-    /// Lua 5.0 strings are byte strings. An inline `<Script>` body arrives as `&str` from the XML
-    /// and is passed through as its own bytes, which is the same thing.
-    ///
-    /// `path` names the chunk, and **naming it is not cosmetic**: mlua's `load` is `#[track_caller]`
-    /// and an unnamed chunk is named after the Rust line that loaded it, so every raise from every
-    /// FrameXML and addon `<Script>` block in this project reported `loader/mod.rs` as its source
-    /// (decision 1217). Lua's leading `@` is what makes it a *file* name rather than a quoted
-    /// source snippet, and the separator is `\` because that is the shape an addon parsing its own
-    /// `debugstack()` matches against (`crate::script::addon_chunk_name`).
+    /// Run a file chunk (bytes, as on disk) in the one global state, named after its path. The
+    /// name matters: unnamed, mlua's `#[track_caller]` `load` names it after this Rust line.
     fn run(&self, chunk: &[u8], path: &str) -> mlua::Result<()> {
-        // A FILE chunk is `"@%s"` (`0x8716e0`) over the resolved path — `0x704bc0` builds it that
-        // way for every `.lua` the loader touches, and `luaO_chunkid 0x6f5c40`'s `@` branch
-        // prints it plainly.
+        // The reference's file chunk name, `"@%s"` (`0x8716e0`, `0x704bc0`; a file name to
+        // `luaO_chunkid 0x6f5c40`), with `\` separators as in `crate::script::addon_chunk_name`.
         self.run_named(chunk, &format!("@{}", path.replace('/', "\\")))
     }
 
-    /// Run a chunk under a chunk name given **whole** — for the producers whose name is not a
-    /// path. See the inline `<Script>` arm in [`Self::load_doc`].
+    /// Run a chunk under a complete chunk name, for a producer whose name is not a path.
     fn run_named(&self, chunk: &[u8], name: &str) -> mlua::Result<()> {
         self.lua
             .load(chunk)
@@ -440,15 +268,13 @@ impl Loader<'_> {
             .exec()
     }
 
-    /// The model, for the two FrameXML registries below.
     fn model(&self) -> mlua::AppDataRefMut<'_, crate::script::Model> {
         self.lua
             .app_data_mut::<crate::script::Model>()
             .expect("model app_data")
     }
 
-    /// Run a widget handler with the client's calling convention — `UiScript::invoke_handler`'s
-    /// body, reachable from `&Lua`.
+    /// Run a widget handler with the client's calling convention, from `&Lua`.
     pub(super) fn invoke_handler(
         &self,
         wrapper: &mlua::Table,
@@ -463,31 +289,10 @@ impl Loader<'_> {
         }
     }
 
-    /// A `text=` attribute is a **GLOBAL-STRING LOOKUP, not a literal** — the single most load-bearing
-    /// thing about the attribute, and the one this loader used to get wrong.
-    ///
-    /// `<Button text=>` and `<FontString text=>` BOTH resolve through `FrameScript_GetText
-    /// 0x703bf0`, which resolves the value as a Lua global and,
-    /// **when that global is not a string, returns a pre-seeded EMPTY string** (`0x882748`), never
-    /// the key name. That is why the reference's `text="LOGOUT"` renders "Logout", and why
-    /// `GlobalStrings.lua` runs before any XML (`ui_script::load_global_strings`).
-    ///
-    /// **The MISS falls back to the raw attribute, and that is the reference's own behaviour — not
-    /// a benilla divergence, which is what this comment used to claim.** `0x703bf0`'s empty return
-    /// never reaches a label: all three `text=` readers image-wide test it and substitute the raw
-    /// attribute string. `Button::LoadXML` at `0x778c07` — a fallback to the raw attribute when
-    /// the lookup comes back empty (`0x778c31 mov eax,esi`) — and byte-identically
-    /// `CSimpleFontString::LoadXML` at `0x771006` (`771012 mov esi,eax` … `771029 test eax,eax` /
-    /// `77102b je 0x771032` / `77102d cmp BYTE [eax],0` / `771030 jne` / `771032 mov eax,esi`), and
-    /// the third reader at `0x7292a6`, which expresses the same law through a copy
-    /// (`7292db mov al,[ebp-0x424]` / `7292e1 test al,al`, empty arm pushes `edi` = the raw).
-    ///
-    /// So the reference's `PetPaperDollFrame.xml:70` `text="Level level race class"` really does
-    /// draw that placeholder until Lua overwrites it, and benilla's plain-English `text="Send
-    /// Mail"` renders for the same reason the reference's would. What IS ours is the extra signal:
-    /// a **key-shaped** value that misses warns here as well as keeping its key on screen — the
-    /// signal that was missing when the macro window shipped with "CREATE_MACROS" across its title
-    /// bar (0983 → 0991).
+    /// Resolve `text=` as a global-string key (`FrameScript_GetText 0x703bf0`), so
+    /// `GlobalStrings.lua` must run before any XML. A miss comes back empty (`0x882748`) and all
+    /// three `text=` readers then show the raw value (`0x778c07`, `0x771006`, `0x7292a6`). The
+    /// warning on a key-shaped miss is benilla's own.
     pub(super) fn resolve_text(&mut self, raw: &str, dbg: &str) -> String {
         if let Ok(s) = self.lua().globals().get::<String>(raw) {
             return s;
@@ -509,29 +314,11 @@ impl Loader<'_> {
         for item in &doc.items {
             match item {
                 TopLevel::Include(path) => self.do_include(path),
-                // **A DELIBERATE DIVERGENCE, and a strict superset of the reference.**
-                //
-                // `<Script file=X>` does NOT share `<Include>`'s path law. `0x6ee070`-`0x6ee079`
-                // tests X itself for a separator and, when it has one, uses X **verbatim** — no
-                // `dirname(referrer)` prefix, and no `..` collapse either, since that arm never
-                // enters `0x6ede10`. Only a *bare* name gets `dirname(referrer) + name`.
-                //
-                // A verbatim value cannot open on 1.12. Resolution runs through `0x647e60` against
-                // a hash index whose key is each file's path **relative to the scan root**, and the
-                // root is the process CWD (Storm's base-path global `0xc52418` has no writer
-                // image-wide, so `0x646ebc` substitutes `"."`). The basename retry at `0x647ed3` is
-                // real code but off — it needs a flag bit that `0x648be0(0)` clears at startup. So
-                // `Libs\Ace\Ace.lua` misses every leg: full-string, base-prefixed and the MPQ
-                // chain. There is no per-addon or per-document current directory anywhere in the
-                // client.
-                //
-                // We resolve it against the including document's directory anyway. That converts a
-                // guaranteed failure into a success and **cannot break anything that worked on the
-                // reference**, because under 1.12 there is no install-root `Libs\` for the verbatim
-                // value to have found. The corpus addons carrying the form are TBC-era anyway —
-                // all three report `iface=20400` and ship LibStub/CallbackHandler-1.0, none of
-                // which existed in 1.12 — so reproducing the failure would buy nothing and cost
-                // `FuBar_AtlasFu`, which works today.
+                // Deviation: a `<Script file=>` value with a separator joins the including
+                // document's directory, like a bare name. The reference uses it verbatim
+                // (`0x6ee070`-`0x6ee079`) against the process CWD (`0x647e60`, `0x646ebc`; the
+                // basename retry at `0x647ed3` is off), where it never opens, so joining breaks
+                // nothing that loads on 1.12.
                 TopLevel::Script(ScriptRef::File(path)) => {
                     let joined = join_ref(self.base(), path);
                     match (self.files)(&joined) {
@@ -549,23 +336,13 @@ impl Loader<'_> {
                     }
                 }
                 TopLevel::Script(ScriptRef::Inline { body, line }) => {
-                    // Padded to the block's own offset in the XML, so Lua counts from where the
-                    // file does. A chunk always starts at line 1; naming it after the file without
-                    // this would make every reported line a confident, checkable lie.
+                    // Deviation: padded to the block's line, so a raise reports a line a reader can
+                    // find in the file; the reference counts from the body's first line.
                     let mut chunk = "\n".repeat(line.saturating_sub(1) as usize).into_bytes();
                     chunk.extend_from_slice(body.as_bytes());
-                    // **Not a file name.** The reference names an inline `<Script>` body
-                    // `"%s:<Scripts>"` (`0x871074`) over the XML document's own path, with NO `@`
-                    // — `0x6ee0ed push ebx` / `0x6ee0ee push 0x871074` → `0x6ee0ff` sprintf →
-                    // `0x6ee10f call 0x704cd0`. So `luaO_chunkid` takes its third branch and the
-                    // frame reads `[string "Interface\FrameXML\Foo.xml:<Scripts>"]`, not a path.
-                    // Writing `@path` here made an inline block indistinguishable from the `.lua`
-                    // file beside it — including to the addons that split a `debugstack` frame on
-                    // `\AddOns\`.
-                    //
-                    // The padding above stays (1214): the reference's line numbers here are
-                    // body-relative, ours are the XML file's, and the file's are the ones a reader
-                    // can go and check — the name now carries the path that makes them checkable.
+                    // The reference names an inline body `"%s:<Scripts>"` (`0x871074`, formatted at
+                    // `0x6ee0ff`) over the document's path with no `@`, so a raise reads
+                    // `[string "Interface\FrameXML\Foo.xml:<Scripts>"]`, not a file path.
                     let name = format!("{}:<Scripts>", self.path.replace('/', "\\"));
                     if let Err(e) = self.run_named(&chunk, &name) {
                         self.report.errors.push(format!("inline <Script>: {e}"));
@@ -573,9 +350,8 @@ impl Loader<'_> {
                 }
                 TopLevel::Font(el) => self.do_font(el),
                 TopLevel::Template(el) => {
-                    // Register the raw (un-expanded) node; `expand` chain-resolves any `inherits` it
-                    // carries at instantiation time. An unnamed virtual node was already warned at
-                    // parse time and cannot be inherited, so it is simply not registered.
+                    // Registered raw; `expand` resolves its own `inherits` at instantiation. An
+                    // unnamed one was warned at parse time.
                     if let Some(name) = el.name() {
                         self.model()
                             .framexml_templates
@@ -600,24 +376,10 @@ impl Loader<'_> {
             ));
             return;
         };
-        // **`<Include>` dispatches on the EXTENSION, and a `.lua` target is RUN, not parsed.**
-        //
-        // `0x6ede10` is not "the XML loader" — it is *load one file by path*, and its first act
-        // after the `..` collapse is a case-insensitive `.lua` suffix test on the **resolved** path
-        // (`0x6edee6`-`0x6edf0f`: `strrchr(path,'.')`, then a case-insensitive compare against
-        // `".lua"` @`0x8710c8`). Extension, never a content sniff — no byte of the file has been
-        // read at that point. A match runs the chunk (`0x6edf0f call 0x704bc0`, chunk name
-        // `"@<resolved path>"` via `0x8716e0`); anything else is opened and parsed as XML.
-        //
-        // `<Include file=X>` is a **recursion into that same routine** (`0x6ee00d`), so it inherits
-        // the dispatch for free: there is no `<Include>`-specific Lua code in the client at all,
-        // and it is the same mechanism that makes a `.lua` line in a `.toc` work. Which is also the
-        // internal evidence that this was ours and not the corpus's — our own `.toc` loader has
-        // always split on extension (`ui_script::addons`, 1185), and only this arm never did.
-        //
-        // Three addons ship the form — FonzAppraiser (67 sites), AckisRecipeList (24), FonzSummon
-        // (22): an authoring habit rather than a convention, but each lost its ENTIRE library set
-        // here, because `embeds.xml` is nothing but these lines.
+        // `<Include>` recurses (`0x6ee00d`) into the reference's load-one-file routine `0x6ede10`,
+        // which dispatches on the resolved path's extension, never its content: a `.lua` suffix
+        // (`0x6edee6`-`0x6edf0f`) runs the file as a chunk (`0x704bc0`), anything else parses as
+        // XML. A `.toc` line goes through the same routine.
         if has_lua_suffix(&joined) {
             if let Err(e) = self.run(crate::source::chunk(&bytes), &joined) {
                 self.report
@@ -626,13 +388,11 @@ impl Loader<'_> {
             }
             return;
         }
-        // An included document is the one place text is forced: roxmltree parses `&str` (1193).
+        // Only an included document is decoded to text: roxmltree parses `&str`.
         match framexml::parse(&crate::source::decode(&bytes)) {
             Ok(sub) => {
                 self.report.warnings.extend(sub.warnings.iter().cloned());
-                // The included document's OWN path is what ITS relative references resolve against
-                // and what ITS inline scripts are named after — restored after, so a sibling
-                // include at this level is unaffected.
+                // The included document resolves and names against its own path until it is done.
                 let outer = std::mem::replace(&mut self.path, joined.clone());
                 self.load_doc(&sub);
                 self.path = outer;
@@ -644,15 +404,13 @@ impl Loader<'_> {
         }
     }
 
-    /// Resolve `inherits=` against the script's persistent registry (`framexml::expand`),
-    /// folding its warnings into the report.
+    /// Resolve `inherits=` against the persistent template registry (`framexml::expand`).
     pub(super) fn expand(&mut self, el: &Element) -> Element {
         let model = self.model();
         let templates = model.framexml_templates.borrow();
         let view: HashMap<&str, &Element> =
             templates.iter().map(|(k, v)| (k.as_str(), v)).collect();
-        // The font namespace, so a font object inside an inherit chain is skipped rather than
-        // warned as an unknown template (1874).
+        // A font object in an inherit chain is skipped, not warned as an unknown template.
         let fonts = model.framexml_fonts.borrow();
         let font_names: std::collections::HashSet<&str> =
             fonts.keys().map(|k| k.as_str()).collect();
@@ -667,11 +425,8 @@ impl Loader<'_> {
         out
     }
 
-    /// [`Loader::expand`] for a `<Texture>`/`<FontString>` REGION — gated on the `inherits=`
-    /// naming at least one registered element template, because a FontString's `inherits=`
-    /// usually names a font OBJECT (`framexml_fonts`, a separate namespace resolved by
-    /// `apply_fontstring_font`), which must pass through untouched rather than warn as an
-    /// unknown template. The talent branch/arrow art pool is the first region-template user.
+    /// [`Loader::expand`] for a region, only when `inherits=` names a registered element template:
+    /// a FontString's `inherits=` usually names a font object, which passes through unwarned.
     pub(super) fn expand_region(&mut self, el: &Element) -> Element {
         let hit = el.attr("inherits").is_some_and(|names| {
             let model = self.model();
@@ -688,16 +443,12 @@ impl Loader<'_> {
         }
     }
 
-    /// A top-level `<Font name=…>`: resolve its `inherits=` chain against the accumulated font
-    /// registry (a *separate* namespace from frame templates — a font inherits another font, never a
-    /// frame), read the flattened `{font, height, color, outline, justifyH}`, register the resolved
-    /// [`FontObject`] in the engine, and store the merged element so later fonts inheriting this one
-    /// see fully-flattened values. An unnamed `<Font>` was already warned at parse time; skip it.
+    /// A top-level `<Font name=…>`: flatten its `inherits=` chain (fonts inherit only fonts),
+    /// register the [`FontObject`] and store the flattened element for later fonts to inherit.
     pub(super) fn do_font(&mut self, el: &Element) {
         let Some(name) = el.name().map(str::to_string) else {
             return;
         };
-        // Resolve `inherits` against the font registry (reuse the generic template merge).
         let merged = {
             let model = self.model();
             let fonts = model.framexml_fonts.borrow();
@@ -713,27 +464,17 @@ impl Loader<'_> {
         };
 
         let font = font_object_from_element(&merged);
-        // One model borrow, then the insert — `font_objects` and `framexml_fonts` are both on it.
         {
             let mut model = self.model();
             model
                 .font_objects_by_lower
                 .insert(name.to_ascii_lowercase(), font);
-            // Store the merged (flattened) node so a chain rooted here reads resolved values.
             model
                 .framexml_fonts
                 .borrow_mut()
                 .insert(name.clone(), merged);
         }
-        // …and publish `_G[name]` as a real font OBJECT. In 1.12 a `<Font name="GameFontNormal">`
-        // is not only a style record: it is addressable Lua, and that is how the whole addon
-        // ecosystem paints text — `fs:SetFontObject(GameFontNormal)` is 3,180 of the corpus's 3,186
-        // call sites, against 6 that pass a string. Registering the record without ever publishing
-        // the name is why `Gratuity-2.0.lua:57` was handed nil and took five addons down at load.
-        // The object and its method surface are `crate::script::font`.
-        //
-        // Flattening is untouched: the merge above still resolves the `inherits=` chain once, at
-        // load, and publishing only gives the result a name.
+        // In 1.12 a named `<Font>` is also a Lua global, the object `SetFontObject` takes.
         if let Err(e) = crate::script::font::publish(self.lua(), &name) {
             self.report
                 .warnings
@@ -741,40 +482,21 @@ impl Loader<'_> {
         }
     }
 
-    /// Materialize one (already template-expanded) frame element into a live frame, then recurse its
-    /// nested `<Frames>` and fire its `OnLoad` **after** them (bottom-up, `0x76a060`).
-    ///
-    /// `parent` is the **lexically** enclosing frame's wrapper (`None` at top level) and
-    /// `parent_name` its already-resolved name (or `"Top"`). A `parent=` attribute overrides both,
-    /// and it is the *effective* parent that `$parent` substitutes against — in this frame's name
-    /// and in its anchors' `relativeTo` (`0x76c5b0`).
-    /// Returns the created frame's wrapper — `None` when `CreateFrame` refused (an unknown frame
-    /// type, `0x6ee280`'s factory-table miss), which also skips the whole subtree. The
-    /// `<ScrollChild>` pass is the one caller that needs the handle back.
+    /// Build one template-expanded frame element, its nested `<Frames>`, then its `OnLoad`
+    /// (bottom-up, `0x76a060`). `parent` is the lexically enclosing frame, which `parent=`
+    /// overrides; `None` when the frame type is unknown, which skips the subtree.
     pub(super) fn materialize(
         &mut self,
         el: &Element,
         parent: Option<&Table>,
         parent_name: &str,
     ) -> Option<Table> {
-        // ─ Step 1 and ONLY step 1 lives here: resolve the parent, resolve the name against it,
-        //   and call CreateFrame. Everything after it is `decorate`, because the runtime template
-        //   path enters at exactly that seam (`apply_template`) — its frame already exists, and
-        //   re-entering here would recurse.
+        // Only creation lives here: everything after `CreateFrame` is `decorate`, which
+        // `apply_template` enters for a frame that already exists.
 
-        // 0 · **The type lookup, and its XML miss LOGS and skips the node** (decision 2191).
-        //
-        //     `Instantiate 0x6ee280` looks the element's own tag up first (`0x6ee2e5 mov
-        //     edi,[esi+8]`, before `parent=` is read), and on a miss prints `"Unknown frame type:
-        //     %s"` (`0x871124`) at `0x6ee356` into the document's log and makes no object for that
-        //     node — non-fatal, and the walk goes on to the next sibling. Only the Lua door
-        //     raises. We used to reach the registry through the Lua `CreateFrame`, so an XML miss
-        //     became a `report.errors` row — a script error the player sees — for a document the
-        //     client shrugs at. The live case: an addon whose `.toc` lists its own `Bindings.xml`
-        //     (MonkeyDev). The toc line runner hands it to the same file loader as any `.xml`, its
-        //     `<Binding>` children are not `Include`/`Script`/`Font`, so each is a frame element
-        //     whose type does not exist — three log lines in the reference, three red dialogs here
-        //     — while the file's real reading as bindings happens at `0x51f400` regardless.
+        // 0 · The type lookup. `Instantiate 0x6ee280` checks the tag before reading `parent=`; a
+        //     miss logs `"Unknown frame type: %s"` (`0x871124`, at `0x6ee356`), builds nothing for
+        //     the node and goes on to the next sibling. Only the Lua door raises.
         if crate::script::object::registered_frame_kind(self.lua(), &el.tag).is_none() {
             self.report
                 .warnings
@@ -782,57 +504,24 @@ impl Loader<'_> {
             return None;
         }
 
-        // 1a · `parent="SomeFrame"` — the OTHER way an element names its parent, and the one the
-        //      reference's own FrameXML uses most, because its files are flat: `<Frame name="X"
-        //      parent="UIParent">` at top level rather than nested inside `<Frames>`. We only ever
-        //      read the lexical parent, so **708 corpus sites across 79 addons** produced a frame
-        //      with `GetParent() == nil` — no visibility inheritance, no scale or alpha
-        //      inheritance, and `this:GetParent():Hide()` raising on a nil. Nothing warned, because
-        //      an ignored attribute is not an error: 1205's silent-drop class again.
-        //
-        //      The attribute WINS over the lexical parent when both are present, which is the
-        //      reference's rule and is what lets an addon nest an element for authoring
-        //      convenience and still attach it elsewhere.
-        //
-        //      **The attribute is NOT `$parent`-expanded.** `0x6ee280` hands the raw string to the
-        //      by-name resolver `0x76c760` **directly** at `0x6ee3e8`, bypassing the expander that
-        //      `name=` and `relativeTo=` reach through `SetName`/`0x76c700`. Nothing in ~1100
-        //      corpus XML files writes `parent="$parent…"`, so expanding it was a dead deviation —
-        //      but a dead deviation on this line is exactly what made 2208's live one hard to see.
-        //
-        //      **Three outcomes, not two** (decision 2213):
-        //      the slot `[ebp-0x8]` is seeded at `0x6ee28b` with the incoming default parent, and
-        //      `0x6ee3ef mov [ebp-0x8],eax` writes the lookup's result back **unconditionally** —
-        //      so a *miss* stores 0 over that seed and the frame is constructed **parentless**
-        //      (`0x6ee408 mov ecx,[ebp-0x8]`), after logging `0x8710f0`. It does NOT fall back to
-        //      the enclosing frame, which is what we used to do; the divergence is invisible at
-        //      top level (there is no enclosing frame to fall back to) and only shows on a nested
-        //      element naming a parent that is not loaded yet. And an **empty** `parent=""`
-        //      short-circuits earlier still, at `0x6ee3c7`: the default parent is kept, silently,
-        //      and the `inherits` chain is not consulted for one — only an *absent* attribute
-        //      walks it (which for us happens in template expansion, upstream of here).
-        //
-        //      `None` = no attribute, or an empty one: keep the enclosing parent.
-        //      `Some(None)` = named a parent that does not resolve: parentless, and logged.
+        // 1a · `parent=` wins over the lexical parent, unexpanded: `0x6ee280` hands the raw value
+        //      to the by-name lookup `0x76c760` (at `0x6ee3e8`). A miss is logged and stores 0 over
+        //      the default parent (`0x6ee3ef`), so the frame is built parentless (`0x6ee408`); an
+        //      empty `parent=""` keeps the default parent silently (`0x6ee3c7`).
+        //      `None`: no attribute, or an empty one. `Some(None)`: a miss, parentless and logged.
         let attr_parent: Option<Option<Table>> =
             el.attr("parent")
                 .filter(|name| !name.is_empty())
                 .map(|name| {
-                    // A FRAME, not merely a global of that name. `_G` is one namespace: an addon's own
-                    // `MyAddon = {}` sits in it beside every frame, and the corpus really does write
-                    // `parent="TheoryCraft"` where the addon owns that name. Handing a plain table to
-                    // `CreateFrame` would raise and take the element's whole subtree with it — a name
-                    // collision costing a window. The identity test mirrors the reference: a frame
-                    // wrapper carries its handle at `T[0]` as lightuserdata (`0x6f3ea0`), and
-                    // nothing else does. The reference's own `0x76c760` reads the frame registry,
-                    // so a non-frame global of the right name is the same miss, with the same
-                    // message.
+                    // Only a frame counts: `0x76c760` reads the frame registry, so a non-frame
+                    // global of that name is a miss. A frame wrapper is the one table carrying
+                    // lightuserdata at `[0]` (`0x6f3ea0`).
                     let hit =
                         self.lua().globals().get::<Table>(name).ok().filter(|t| {
                             matches!(t.raw_get::<Value>(0), Ok(Value::LightUserData(_)))
                         });
                     if hit.is_none() {
-                        // The reference's own wording (`0x8710f0`), like the frame-type miss above.
+                        // The reference's wording (`0x8710f0`).
                         self.report
                             .warnings
                             .push(format!("Couldn't find frame parent: {name}"));
@@ -844,31 +533,11 @@ impl Loader<'_> {
             None => parent,
         };
 
-        // 1b · **The name, resolved AFTER the parent — and against it** (B387). `$parent` is not a
-        //      lexical token: `SetName 0x76c650` expands it in `0x76c5b0` by walking the frame's
-        //      **actual** parent chain (`this+0x9c`) to the nearest non-empty name, seeded `"Top"`.
-        //      And in `Instantiate 0x6ee280` the parent is attached *first* —
-        //      resolved at `0x6ee3e8` into `[ebp-0x8]` and passed as `ecx` to the factory's
-        //      constructor at `0x6ee408 call [ebx+0x18]` — while the node-apply step that reads
-        //      `name=` and calls `SetName` runs only afterwards, at `0x6ee4d6 call [edx+0x20]`.
-        //      So a **top-level** element whose name leans on `$parent` and whose parent
-        //      comes from the attribute resolves against that attribute's frame.
-        //
-        //      We did it the other way round: the name was substituted against the *lexical*
-        //      ancestor — `"Top"` for a top-level element — and never recomputed once the
-        //      attribute rebound the parent. ClassIcons' `<Frame name="$parentClassIcon"
-        //      inherits="UnitFrameClassIconTemplate" parent="PlayerFrame"/>` was therefore
-        //      published as `TopClassIcon`, and the addon's `PlayerFrameClassIcon:SetPoint` at
-        //      `ClassIcons.lua:228` indexed a nil.
-        //
-        //      The base name comes from the parent FRAME, not from the attribute text — the
-        //      reference reads `p->GetName()`, so a `parent="playerframe"` that resolves
-        //      case-insensitively still yields `PlayerFrame…`; and a parent that is itself
-        //      nameless walks on up, which is what [`Self::frame_names`] already does for the
-        //      runtime template path.
-        //      A parent the attribute nulled leaves the chain walk with nothing to find, so the
-        //      seed survives and `$parent` is `"Top"` — the same answer, by the same route, as a
-        //      top-level element with no parent at all.
+        // 1b · The name resolves after the parent, against it. `Instantiate 0x6ee280` passes the
+        //      parent to the constructor (`0x6ee408`) before it applies `name=` (`0x6ee4d6`), and
+        //      `SetName 0x76c650` expands `$parent` by walking the real parent chain to the nearest
+        //      name, seeded `"Top"` (`0x76c5b0`). The base is the parent frame's own name, not the
+        //      attribute text; a nulled parent leaves the `"Top"` seed.
         let attr_parent_name: Option<String> =
             attr_parent.as_ref().map(|resolved| match resolved {
                 Some(p) => {
@@ -878,15 +547,11 @@ impl Loader<'_> {
                 None => framexml::DEFAULT_PARENT_NAME.to_string(),
             });
         let parent_name = attr_parent_name.as_deref().unwrap_or(parent_name);
-        // The resolved name is what CreateFrame publishes and what this frame's own children
-        // substitute `$parent` against.
         let resolved_name: Option<String> = el
             .name()
             .map(|raw| framexml::resolve_name(raw, parent_name));
 
-        // 1 · CreateFrame(kind = element tag, name, parent). The type is already known to resolve
-        //     (step 0), so an error here is something else the call raised — record it and skip
-        //     the whole subtree.
+        // 1 · `CreateFrame(tag, name, parent)`; the type is known, so an error is a real raise.
         let create: Function = match self.lua().globals().get("CreateFrame") {
             Ok(f) => f,
             Err(e) => {
@@ -917,38 +582,25 @@ impl Loader<'_> {
             .clone()
             .unwrap_or_else(|| format!("<{}>", el.tag));
 
-        // The one trace site walked to the bytes — `Instantiate 0x6ee280`'s
-        // `0x871154 "-- Creating %s named %s"`, gated `flag > 0` at `0x6ee298` (decision 2160).
-        // The kind is the element tag, which is what the reference's first `%s` carries.
+        // One of the reference's five loader traces: `Instantiate 0x6ee280`'s `"-- Creating %s
+        // named %s"` (`0x871154`), gated `flag > 0` at `0x6ee298`; the first `%s` is the tag.
         if self.model().framexml_debug.get() > 0 {
             self.report
                 .traces
                 .push(format!("-- Creating {} named {dbg_name}", el.tag));
         }
 
-        // This frame's own name is what its *contents* (regions, nested frames) substitute
-        // `$parent` against (`0x76c5b0`: a region/child's parent is this frame); a nameless frame
-        // passes the nearest named ancestor through unchanged. This frame's *own* anchors, by
-        // contrast, substitute `$parent` against `parent_name` (their `$parent` is this frame's
-        // enclosing parent).
+        // `$parent` for its contents; a nameless frame passes its nearest named ancestor on.
         let self_name = resolved_name.as_deref().unwrap_or(parent_name).to_string();
 
         self.decorate(el, &wrapper, &self_name, parent_name, &dbg_name);
         Some(wrapper)
     }
 
-    /// Everything a frame element does to a frame that **already exists**: LoadXML attributes,
-    /// `<Size>`, `<Anchors>`, `<Layers>` regions, the per-kind extras, `<Scripts>`, the nested
-    /// `<Frames>` pass, and finally this frame's own `OnLoad` (bottom-up, `0x76a060`).
-    ///
-    /// Split out of [`Self::materialize`] because materialize's *first* step is `CreateFrame`, and
-    /// the runtime template path — [`apply_template`], i.e. `CreateFrame`'s own fourth argument —
-    /// is called from **inside** that binding. It cannot re-enter materialize without recursing
-    /// forever; it enters here instead, and the two paths share every step that follows.
-    ///
-    /// The two names are not the same thing and the difference is the load-bearing one
-    /// (`0x76c5b0`): `self_name` is what `$parent` means to this frame's **contents** (its regions,
-    /// its nested frames), `parent_name` is what `$parent` means to this frame's **own** anchors.
+    /// Everything a frame element does to an existing frame, from `LoadXML` attributes to its
+    /// `OnLoad` (last, bottom-up, `0x76a060`); shared by [`Self::materialize`] and
+    /// [`apply_template`]. `$parent` is `self_name` in this frame's contents and `parent_name` in
+    /// its own anchors (`0x76c5b0`).
     pub(super) fn decorate(
         &mut self,
         el: &Element,
@@ -957,31 +609,23 @@ impl Loader<'_> {
         parent_name: &str,
         dbg_name: &str,
     ) {
-        // Everything this frame defers drains before its OnLoad (step 8 below); a nested frame's
-        // own deferrals drain inside ITS decorate, so the mark is this frame's alone.
+        // This frame's deferred anchors drain before its OnLoad; a nested frame drains its own.
         let deferred_mark = self.deferred_anchors.len();
         // 2 · LoadXML attributes (`0x769820`).
         self.apply_attrs(el, wrapper, dbg_name);
         // 3 · <Size> and 4 · <Anchors> (the CLayoutFrame geometry base, `0x767800`).
         self.apply_size(el, wrapper, dbg_name);
         self.apply_anchors(el, wrapper, parent_name, dbg_name);
-        // 5 · <Layers> regions (`0x769d70`) — `$parent` in a region name is *this* frame.
+        // 5 · <Layers> regions (`0x769d70`); `$parent` in a region name is this frame.
         self.apply_layers(el, wrapper, self_name, dbg_name);
-        // 5·b — a frame's **direct-child** `<FontString>` (outside `<Layers>`): the engine's special
-        // font string (a ScrollingMessageFrame's line font, an EditBox's text font). Created on
-        // OVERLAY so its resolved font object (ChatFontNormal — face/height/shadow) is what the
-        // frame's line/text rendering reads. See [`Self::apply_special_fontstrings`].
+        // 5·b · a direct-child `<FontString>`: the widget's own text font (EditBox, message frame).
         self.apply_special_fontstrings(el, wrapper, self_name, dbg_name);
         // 5a · <Backdrop> plate (LoadXML `0x77e6c0`): the tiled bg + 8-piece border.
         self.apply_backdrop(el, wrapper, dbg_name);
         // 5a' · <TitleRegion>: the drag handle, through the API's own CreateTitleRegion.
         self.apply_title_region(el, wrapper, self_name, dbg_name);
-        // 5b · per-kind LoadXML extras (the reference's per-type tables) — StatusBar +
-        //      Button/CheckButton; the EditBox flags/caps (`LoadXML 0x779fb0`). Every one of
-        //      these gates on the element's own tag,
-        //      which is why `apply_template` builds its synthetic node with the kind CreateFrame was
-        //      given: a Frame asked to wear a <Button> template simply skips the Button-only steps
-        //      instead of calling SetNormalTexture on something that has no such method.
+        // 5b · per-kind LoadXML extras (EditBox `0x779fb0`), each gated on the element's own tag,
+        //      so a Frame wearing a <Button> template skips the Button steps.
         self.apply_statusbar(el, wrapper, dbg_name);
         self.apply_slider(el, wrapper, self_name, dbg_name);
         self.apply_colorselect(el, wrapper, self_name, dbg_name);
@@ -993,8 +637,7 @@ impl Loader<'_> {
         // 6 · <Scripts> handlers (`0x769ef0`); OnLoad is captured to fire bottom-up below.
         let onload = self.apply_scripts(el, wrapper, dbg_name);
 
-        // 7 · nested <Frames> — build children (firing THEIR OnLoads) before ours (`0x76a060`). A
-        //     child's `$parent` (name and anchors) resolves against this frame's name.
+        // 7 · nested <Frames>, whose OnLoads fire before ours (`0x76a060`).
         for frames_el in children_named(el, "Frames") {
             for child in &frames_el.children {
                 let expanded = self.expand(child);
@@ -1002,17 +645,9 @@ impl Loader<'_> {
             }
         }
 
-        // 7b · `<ScrollChild>` — the ScrollFrame's panning content: its single child frame is
-        //      instantiated via `0x6ee280`(childNode, this, status) — the same `Instantiate` path
-        //      `<Frames>` uses — then stored `+0x318`, flag `+0x314=1`, which is `SetScrollChild`.
-        //
-        //      **This is what gives a ScrollFrame its scroll range**, and without it
-        //      `FauxScrollFrameTemplate` — the template five corpus addons instantiate and 34 more
-        //      reach through `FauxScrollFrame_Update` — produces a frame whose range is 0, whose
-        //      `SetVerticalScroll` clamps to 0, and whose `OnVerticalScroll` therefore fires with
-        //      `arg1 = 0` forever. The list never scrolls and nothing errors.
-        //
-        //      An **empty** `<ScrollChild>` is an error in the reference, so it is one here.
+        // 7b · <ScrollChild>: its one child is built through `Instantiate 0x6ee280` like
+        //      `<Frames>`, then stored at `+0x318` with `+0x314 = 1`, which is `SetScrollChild`
+        //      and gives the ScrollFrame its scroll range. An empty one errors in the reference.
         for sc in children_named(el, "ScrollChild") {
             let Some(child) = sc.children.first() else {
                 self.report.errors.push(format!(
@@ -1032,9 +667,7 @@ impl Loader<'_> {
             }
         }
 
-        // 7c · the anchors this frame's own elements could not resolve while their targets were
-        //      still unbuilt — every child exists now, which is when the client's own layout
-        //      pass would have read them.
+        // 7c · deferred anchors: every child exists now, as at the reference's layout pass.
         self.drain_deferred_anchors(deferred_mark);
         // 8 · this frame's OnLoad, now that its subtree is complete (bottom-up).
         if let Some(func) = onload {
@@ -1042,23 +675,14 @@ impl Loader<'_> {
         }
     }
 
-    /// The two names a decoration needs, read back from the frame itself through the **public
-    /// object model** (`GetName`/`GetParent`) rather than the arena — the discipline this module
-    /// holds to everywhere else (see the module docs). Used by [`apply_template`], whose caller
-    /// hands it a wrapper and nothing else.
-    ///
-    /// Returns the frame's own name (`None` if it is anonymous) and the name of its nearest
-    /// **named** ancestor — `0x76c5b0`'s walk, with [`framexml::DEFAULT_PARENT_NAME`] when there
-    /// is none.
+    /// Apply one anchor, deferring it (when `may_defer`) while its named `relativeTo` is unbuilt.
     pub(super) fn apply_anchor(&mut self, d: DeferredAnchor, may_defer: bool) {
         let rel: Value = match d.args.1.as_deref() {
             Some(name) => {
                 match crate::script::object::anchor_args::resolve_xml_relative_to(self.lua(), name)
                 {
                     Some(t) => Value::Table(t),
-                    // Nothing by that name YET — a target declared later in the enclosing frame's
-                    // subtree. Hold it until the subtree is complete (`deferred_anchors`) and try
-                    // once more; a miss THEN is a real miss and takes the reference's leg.
+                    // Not built yet: retry once the subtree is complete; a miss then is real.
                     None if may_defer => {
                         self.deferred_anchors.push(d);
                         return;
@@ -1071,9 +695,8 @@ impl Loader<'_> {
                     }
                 }
             }
-            // No `relativeTo=`: `ebx` still holds `[ebp-0x14]`, the layout parent default that
-            // `0x76785b call [edx+0xc]` (= `0x76c6e0`) seeded before the `<Anchor>` loop. A frame
-            // with no parent gets the screen root there, which is what a Lua `nil` means here.
+            // No `relativeTo=`: the layout parent (`0x76c6e0`, called at `0x76785b`), or the
+            // screen for a parentless frame, which `nil` means here.
             None => match d
                 .wrapper
                 .call_method::<Option<Table>>("GetParent", ())
@@ -1098,8 +721,7 @@ impl Loader<'_> {
         }
     }
 
-    /// Apply the anchors deferred since `mark` (the enclosing `decorate`'s entry), in order. A
-    /// target still missing now is a real miss and warns through the resolver like any other.
+    /// Apply the anchors deferred since `mark`, in order; a target still missing now warns.
     pub(super) fn drain_deferred_anchors(&mut self, mark: usize) {
         let pending: Vec<DeferredAnchor> = self.deferred_anchors.drain(mark..).collect();
         for d in pending {
@@ -1113,8 +735,8 @@ impl Loader<'_> {
             .ok()
             .flatten();
         let mut cur = wrapper.clone();
-        // Bounded: the arena's parent chain is a tree, and a walk that somehow is not must still
-        // return rather than hang a load.
+        // The frame's own name and its nearest named ancestor's, else `"Top"` (`0x76c5b0`'s
+        // walk), read through `GetName`/`GetParent`. Bounded, so a malformed chain cannot hang.
         for _ in 0..64 {
             let Ok(Some(parent)) = cur.call_method::<Option<Table>>("GetParent", ()) else {
                 break;
@@ -1138,16 +760,9 @@ pub(super) fn children_named<'a>(
         .filter(move |c| c.tag.eq_ignore_ascii_case(tag))
 }
 
-/// Iterate an element's direct children whose tag matches ANY of `tags` (case-insensitively), in
-/// document order.
-///
-/// **Two spellings, one pass.** A 1.12 `<Button>` answers to two names for its label
-/// (`<ButtonText>` and `<NormalText>`) and two for each of its three state fonts
-/// (`<NormalFont>`/`<NormalText>`, `<HighlightFont>`/`<HighlightText>`,
-/// `<DisabledFont>`/`<DisabledText>` — `CSimpleButton::LoadXML 0x7788c0`'s tag-compare chain).
-/// Walking one spelling and then the other
-/// would apply them in tag order instead of document order, and every one of these slots is
-/// last-wins — so the alternatives have to be a single filtered walk, not two.
+/// Iterate an element's direct children whose tag matches any of `tags` (case-insensitively), in
+/// document order. One walk, not one per tag: a Button's label and state fonts each answer to two
+/// tags (`CSimpleButton::LoadXML 0x7788c0`) and each slot is last-wins.
 pub(super) fn children_named_any<'a>(
     el: &'a Element,
     tags: &'a [&'a str],
@@ -1157,13 +772,8 @@ pub(super) fn children_named_any<'a>(
         .filter(move |c| tags.iter().any(|t| c.tag.eq_ignore_ascii_case(t)))
 }
 
-/// Does this `text=` value LOOK like a GlobalStrings key? `SCREAMING_SNAKE`, two characters or more —
-/// at least one letter, and nothing but `A-Z`, `0-9`, `_`. The reference's whole string table is
-/// written this way (`CREATE_MACROS`, `DELETE`, `EXIT_GAME`), and benilla's own literals never are
-/// ("Send Mail", "No results found."), so the shape cleanly separates "you meant a key" from "you
-/// meant these words" — all [`Loader::resolve_text`] needs it for. The length floor is the one real
-/// false positive it buys off: a single-character label (`text="X"` on a close button) is a glyph,
-/// never a key.
+/// Whether a `text=` value is shaped like a GlobalStrings key: `SCREAMING_SNAKE` with a letter, two
+/// characters or more (a one-character `text="X"` is a glyph).
 fn is_global_string_key(s: &str) -> bool {
     s.len() >= 2
         && s.chars().any(|c| c.is_ascii_uppercase())
@@ -1171,8 +781,7 @@ fn is_global_string_key(s: &str) -> bool {
             .all(|c| c.is_ascii_uppercase() || c.is_ascii_digit() || c == '_')
 }
 
-/// Read an `x`/`y` dimension from a `<Size>`/`<Offset>` element: prefer a `<AbsDimension>` child,
-/// else the element's own `x`/`y` attributes. Either component may be absent.
+/// An `x`/`y` pair from a `<Size>`/`<Offset>`: its `<AbsDimension>` child, else its own attributes.
 pub(super) fn abs_dim(el: &Element) -> (Option<f32>, Option<f32>) {
     let src = children_named(el, "AbsDimension").next().unwrap_or(el);
     let x = src.attr("x").and_then(|v| v.trim().parse::<f32>().ok());
@@ -1190,25 +799,21 @@ pub(super) fn color_of(el: &Element) -> [f32; 4] {
     [c("r", 0.0), c("g", 0.0), c("b", 0.0), c("a", 1.0)]
 }
 
-/// Read a `<TexCoords left right top bottom>` child's UV rect `(l, r, t, b)`, if present and
-/// fully-specified. A `<TexCoords>` missing any of the four edges is skipped (the loader leaves the
-/// texture at full-texture UVs rather than guess a half-set crop).
+/// A `<TexCoords>` child's UV rect `(l, r, t, b)`; one missing an edge is ignored (full UVs).
 pub(super) fn tex_coords_of(el: &Element) -> Option<(f32, f32, f32, f32)> {
     let tc = children_named(el, "TexCoords").next()?;
     let edge = |k: &str| tc.attr(k).and_then(|v| v.trim().parse::<f32>().ok());
     Some((edge("left")?, edge("right")?, edge("top")?, edge("bottom")?))
 }
 
-/// Read a `<FontHeight>`/`<AbsValue>`-style scalar: prefer an `<AbsValue val=/>` child, else the
-/// element's own `val` attribute (the `Value` type's inline form). `None` if neither parses.
+/// A `<FontHeight>`-style scalar: its `<AbsValue val=>` child, else its own `val=`.
 pub(super) fn abs_value(el: &Element) -> Option<f32> {
     let src = children_named(el, "AbsValue").next().unwrap_or(el);
     src.attr("val").and_then(|v| v.trim().parse::<f32>().ok())
 }
 
-/// Build a resolved [`FontObject`] from an already-inherits-flattened `<Font>` element: the `font=`
-/// path, the *last* `<FontHeight>` and `<Color>` (merge appends inherited-first, so the last wins —
-/// an override), the `outline=` OUTLINETYPE, and optional `justifyH=`/`justifyV=`.
+/// A [`FontObject`] from a flattened `<Font>`. The merge appends inherited nodes first, so the last
+/// `<FontHeight>`, `<Color>` and `<Shadow>` win.
 pub(super) fn font_object_from_element(el: &Element) -> FontObject {
     let justify_h = el
         .attr("justifyH")
@@ -1224,9 +829,8 @@ pub(super) fn font_object_from_element(el: &Element) -> FontObject {
             "BOTTOM" => JustifyV::Bottom,
             _ => JustifyV::Middle,
         });
-    // <Shadow><Offset><AbsDimension x= y=/></Offset><Color r= g= b=/></Shadow> — inherited via the
-    // template merge like every other child (the MasterFont root's (1,-1) black reaches the whole
-    // GameFont* family; ref-Fonts.xml l.55-62).
+    // `<Shadow>` inherits like any child: `MasterFont`'s (1,-1) black reaches every `GameFont*`
+    // (`Fonts.xml:55`).
     let shadow = children_named(el, "Shadow").last().map(|sh| {
         let offset = children_named(sh, "Offset")
             .next()
diff --git a/crates/benilla-ui/src/loader/regions.rs b/crates/benilla-ui/src/loader/regions.rs
index 4700bcbe..0d91e841 100644
--- a/crates/benilla-ui/src/loader/regions.rs
+++ b/crates/benilla-ui/src/loader/regions.rs
@@ -4,43 +4,20 @@ use crate::framexml::{self, Element};
 
 use super::{abs_dim, abs_value, children_named, color_of, tex_coords_of, Loader};
 
-/// Whether a region parses **its own** font attributes — the reference's `FONTSTRING+0x12c`.
-///
-/// It exists for exactly one element in the whole schema. The ctor sets it to 1
-/// (`0x770de7 mov byte [esi+0x12c],1`) and **one site image-wide clears it** — `0x778b7b`, inside
-/// `CSimpleButton::LoadXML 0x7788c0`'s inline build `[0x778b4c, 0x778bb6)`, which is the
-/// **`<NormalText>`** leg (tag `0x879978`, compared at `0x778b43`) and nothing else. A
-/// `<ButtonText>` (tag `0x8799f0`, `0x7789c1`) is built by the ordinary `<FontString>` region
-/// builder `0x6f2780` — the `<Layers>` walker's own — which never touches the flag, so an ordinary
-/// label keeps every attribute it is written with.
-///
-/// Cleared, gate B (`0x7710d3` → `je 0x771468`) makes that string's own
-/// `CSimpleFontString::LoadXML 0x770f40` skip `0x7710e1`–`0x771467` wholesale: `font=`,
-/// `<FontHeight>`, `outline=`, `monochrome=`, the file load, `spacing=`, `justifyV=`, `justifyH=`,
-/// `<Color>` and `<Shadow>`. (Gate A, `0x770f72`, additionally drops the `inherits=` registry-hit
-/// live link.) The SAME node is fed instead to the button's persistent Normal-state `CSimpleFont`
-/// at `+0x33c` (`0x778ba9`/`0x778baf call 0x783c30`) — one owner per attribute, no double
-/// application. The word still reaches the label's paint and its `GetJustifyH` answer: that
-/// loader's tail notify writes the resolved justify into the label's own `+0x120` (`0x784111` →
-/// `0x784180` → `0x773530` → `0x770800` at `0x770876`), **after** the anchor is placed.
-///
-/// Only `justifyH`/`justifyV` are gated here because they are the only two of that surface this
-/// pass ever applied: the rest live in `apply_fontstring_font`/`apply_region_visual`, which the
-/// button's label pass does not call. Geometry — `<Size>`, `<Anchors>`, `setAllPoints`, `name=` —
-/// is `CLayoutFrame::LoadXML`'s and is outside the gate on both legs.
+/// Whether a region reads its own font attributes, the reference's `FONTSTRING+0x12c`: set by the
+/// ctor (`0x770de7`) and cleared only on a Button's `<NormalText>` (`0x778b7b`), whose string then
+/// skips them (`0x7710e1`-`0x771467`) for the button's Normal font to take (`0x783c30`). Here it
+/// gates only justify, the one font attribute the button's label pass applies.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub(super) enum FontAttrs {
-    /// The ctor's default: an ordinary region — a `<Layers>` `<FontString>`, an EditBox's special
-    /// string, a title region, **and a Button's `<ButtonText>`** — owns its font attributes.
+    /// Every other region, a Button's `<ButtonText>` included.
     Own,
-    /// A Button's `<NormalText>`, the one element the client disowns: its font attributes belong
-    /// to the button's Normal-state font, never to the label.
+    /// A Button's `<NormalText>`: its font attributes are the button's Normal font's.
     Disowned,
 }
 
 impl Loader<'_> {
-    /// `<Layers>`/`<Layer level=>`/`<Texture>`/`<FontString>` (`0x769d70`): create each region
-    /// via CreateTexture/CreateFontString on the draw layer, then apply its file/color/text.
+    /// `<Layers>` (`0x769d70`): each `<Texture>` and `<FontString>`, created on its layer.
     pub(super) fn apply_layers(
         &mut self,
         el: &Element,
@@ -52,11 +29,8 @@ impl Loader<'_> {
             for layer in children_named(layers, "Layer") {
                 let level = layer.attr("level").unwrap_or("ARTWORK").to_string();
                 for region in &layer.children {
-                    // A region's `inherits=` may name a virtual REGION template (the talent
-                    // window's branch/arrow art pool) — splice it exactly like a frame's
-                    // (`0x6ee500`'s one template registry serves both). A FontString's `inherits=`
-                    // usually names a font OBJECT instead — a separate namespace this gate
-                    // skips past to `apply_fontstring_font` below.
+                    // `inherits=` may name a region template, in the frames' one registry
+                    // (`0x6ee500`); a font object's name passes on to `apply_fontstring_font`.
                     let region = &self.expand_region(region);
                     let is_texture = region.tag.eq_ignore_ascii_case("Texture");
                     let is_fontstring = region.tag.eq_ignore_ascii_case("FontString");
@@ -83,13 +57,11 @@ impl Loader<'_> {
                                 continue;
                             }
                         };
-                    // hidden= on a Texture/FontString — the region-level VisibleRegion bit.
                     if region.attr_bool("hidden") {
                         if let Err(e) = region_wrapper.call_method::<()>("Hide", ()) {
                             self.report.errors.push(format!("{dbg}: region Hide: {e}"));
                         }
                     }
-                    // alpha= on a Texture/FontString — the region's own alpha, the frame attr's twin.
                     if let Some(a) = region
                         .attr("alpha")
                         .and_then(|v| v.trim().parse::<f32>().ok())
@@ -104,16 +76,12 @@ impl Loader<'_> {
                         FontAttrs::Own,
                     );
                     if is_fontstring {
-                        // Font object (`inherits=`) first, then the FontString's own `font=`/
-                        // `<FontHeight>`/`outline=` overrides — before the generic visual pass applies
-                        // `text`/`<Color>` on top (an explicit `<Color>` overriding the object's).
+                        // Before the visual pass, so an explicit `<Color>` beats the font object's.
                         self.apply_fontstring_font(region, &region_wrapper, dbg);
                     }
                     self.apply_region_visual(region, &region_wrapper, is_texture, dbg);
-                    // The creation-path implicit anchor (decision 1310): AFTER the authored
-                    // `<Size>`/`<Anchors>`/justify are on the region, exactly where the real
-                    // engine runs it (`0x7701c0`/`0x771480`, immediately after the region's
-                    // LoadXML returns). A region the XML anchored is untouched.
+                    // The implicit creation anchor, run after the region's LoadXML as the
+                    // reference does (`0x7701c0`, `0x771480`); an anchored region is left alone.
                     if let Err(e) =
                         crate::script::implicit_creation_anchor_lua(self.lua, &region_wrapper)
                     {
@@ -126,11 +94,8 @@ impl Loader<'_> {
         }
     }
 
-    /// A frame's **direct-child** `<FontString>` (outside `<Layers>`): the client's "special" font
-    /// string — the ScrollingMessageFrame's line font, an EditBox's text font — which real FrameXML
-    /// attaches at the OVERLAY layer. Only ChatFrame uses this in our shipped XML; without it the
-    /// chat lines fall back to the default face with no shadow. Created via the same
-    /// CreateFontString + layout/font/visual path as a `<Layers>` FontString.
+    /// A frame's direct-child `<FontString>`, its "special" string (a message frame's line font, an
+    /// EditBox's text), on the OVERLAY layer.
     pub(super) fn apply_special_fontstrings(
         &mut self,
         el: &Element,
@@ -138,30 +103,21 @@ impl Loader<'_> {
         parent_name: &str,
         dbg: &str,
     ) {
-        // **A `<SimpleHTML>`'s direct-child `<FontString>` is not a region at all** — it is the
-        // declaration of that widget's `P` element font (`0x78a1fe` → `CSimpleFont::LoadXML`), and
-        // `Loader::apply_simplehtml` owns it. Creating a real FontString here instead would leave
-        // an unanchored, textless string on the frame AND leave `elementFont[0]` empty, which is
-        // the one thing that makes every block fall back to the renderer's default face.
+        // A `<SimpleHTML>`'s direct `<FontString>` declares its `P` font, not a region
+        // (`0x78a1fe`); `apply_simplehtml` owns it.
         if el.tag.eq_ignore_ascii_case("SimpleHTML") {
             return;
         }
         for region in &el.children {
             if !region.tag.eq_ignore_ascii_case("FontString") {
-                continue; // <Layers>/<Frames>/<Scripts>/... are handled by their own passes
+                continue;
             }
             let region = &self.expand_region(region);
             let rname: Option<String> = region
                 .name()
                 .map(|raw| framexml::resolve_name(raw, parent_name));
-            // **An EditBox's direct-child `<FontString>` creates NOTHING.** `LoadXML 0x779fb0`
-            // treats it as the *embedded* font string, and its one attribute (`bytes`) writes the
-            // box's own `maxBytes` at `E+0x33c` — it is the declaration of the object the ctor
-            // already built at `0x779bee`, exactly as a `<SimpleHTML>`'s `<FontString>` declares
-            // that widget's element font (the guard at the top of this function). Creating a
-            // second region here
-            // would put an orphan on the frame AND push the authored `<Layers>` regions one place
-            // down the list `GetRegions` hands Lua.
+            // An EditBox's `<FontString>` declares the text string its ctor built (`0x779fb0`,
+            // `0x779bee`), so it creates nothing: a second region would also shift `GetRegions`.
             let existing_text = el
                 .tag
                 .eq_ignore_ascii_case("EditBox")
@@ -169,9 +125,6 @@ impl Loader<'_> {
                 .flatten();
             let region_wrapper: Table = match existing_text {
                 Some(w) => {
-                    // The embedded string is nameless in the client's own chain; an authored
-                    // `name=` still publishes both ways, exactly like a setter-created sub-texture
-                    // (`apply_slider`'s thumb).
                     if let Some(n) = rname {
                         crate::script::region::publish_region_name(self.lua(), &n, &w);
                         if let Err(e) = self.lua().globals().set(n.clone(), w.clone()) {
@@ -197,19 +150,14 @@ impl Loader<'_> {
             self.apply_region_layout(region, &region_wrapper, parent_name, dbg, FontAttrs::Own);
             self.apply_fontstring_font(region, &region_wrapper, dbg);
             self.apply_region_visual(region, &region_wrapper, false, dbg);
-            // The creation-path implicit anchor (decision 1310), as in `apply_layers`. For the
-            // EditBox adopt below it is moot — `write_inset_anchors` replaces the anchor set
-            // wholesale — but a plain special FontString (a chat window's) gets the same
-            // justify-point the real engine gives it.
+            // The implicit creation anchor, as in `apply_layers`; an EditBox's adopt replaces it.
             if let Err(e) = crate::script::implicit_creation_anchor_lua(self.lua, &region_wrapper) {
                 self.report
                     .errors
                     .push(format!("{dbg}: implicit anchor: {e}"));
             }
-            // The engine's LoadXML slot assignment: an EditBox's direct-child `<FontString>` IS
-            // its text region — typed text renders in its font, the box's insets anchor it.
-            // Assigned, never searched (a find-first adoption once grabbed the chat header out of
-            // `<Layers>`: typing overwrote "Say:" and the insets re-anchor centered it).
+            // It is the EditBox's text region by slot, never found by a search, which could take a
+            // `<Layers>` string; the box's insets anchor it.
             if el.tag.eq_ignore_ascii_case("EditBox") {
                 if let Err(e) =
                     crate::script::adopt_text_region(self.lua(), wrapper, &region_wrapper)
@@ -222,12 +170,9 @@ impl Loader<'_> {
         }
     }
 
-    /// A region's own geometry (decision 0068 v1): `<Size>` → SetWidth/SetHeight, `<Anchors>` →
-    /// SetPoint (owner-relative; `relativeTo` is `$parent`-substituted like a frame's), the
-    /// `setAllPoints="true"` shorthand, and — only for a region that [`FontAttrs::Own`]s them —
-    /// the FontString `justifyH`/`justifyV` attrs → SetJustifyH/V. This is the join that makes
-    /// region `<Size>`/`<Anchors>` actually place the region (before, both were silently dropped
-    /// — the smeared-merchant root cause).
+    /// A region's geometry: `<Size>`, a FontString's justify when [`FontAttrs::Own`],
+    /// `setAllPoints` and `<Anchors>`, whose `$parent` is the owner's name, or a nameless owner's
+    /// nearest named ancestor's.
     pub(super) fn apply_region_layout(
         &mut self,
         region: &Element,
@@ -236,8 +181,7 @@ impl Loader<'_> {
         dbg: &str,
         font_attrs: FontAttrs,
     ) {
-        // ALL `<Size>` children in document order (same last-wins rule as `apply_size`: a templated
-        // region's own `<Size>` must overwrite its template's).
+        // Every `<Size>` in document order, as in `apply_size`.
         for size in children_named(region, "Size") {
             let (x, y) = abs_dim(size);
             if let Some(w) = x {
@@ -287,8 +231,7 @@ impl Loader<'_> {
                     args,
                     dbg: dbg.to_string(),
                 };
-                // The XML path's own law, which resolves the name itself and defers a target
-                // the enclosing frame's subtree has not built yet (`Loader::apply_anchor`).
+                // Deferred while the enclosing subtree has not built its target yet.
                 self.apply_anchor(d, true);
             }
         }
@@ -304,43 +247,20 @@ impl Loader<'_> {
         let color = children_named(region, "Color").next().map(color_of);
         if is_texture {
             if let Some(file) = region.attr("file") {
-                // A `<Texture file=…>` with a `<Color>` child DISCARDS the colour — it is not a
-                // tint.
-                // `CSimpleTexture::LoadXML 0x76fe20` runs its child loop (`0x76fec1`-`0x7700fc`,
-                // where `<Color>` lands in `SetTexture(const CImVector*)` `0x770360`) to completion
-                // BEFORE it reads `file=` at `0x770102`, and a successful load overwrites the very
-                // same `+0xcc` slot (`0x7702cb`/`0x7702dc`) — the generated solid is released
-                // unused. Even the load-FAILURE fallback ignores it, hard-coding `0xff00ff00`
-                // (`0x77016a`). So: load the art, drop the colour.
+                // A `<Color>` beside `file=` is discarded, not a tint: `0x76fe20` applies it in its
+                // child loop, then the file, read after (`0x770102`), overwrites the same slot.
                 self.call_region(region_wrapper, "SetTexture", file.to_string(), dbg);
             } else if let Some(c) = color {
-                // No file: a solid colour fill (SetTexture(r,g,b,a)) — the client really generates
-                // an 8×8 texture out of it, which is why its alpha later MULTIPLIES with any
-                // SetVertexColor rather than being replaced by it (`RegionData::fill`).
+                // No file: a solid fill, an 8×8 texture in the reference, so its alpha multiplies
+                // with `SetVertexColor` rather than being replaced by it.
                 self.call_region(region_wrapper, "SetTexture", (c[0], c[1], c[2], c[3]), dbg);
             }
-            // `<Gradient orientation><MinColor/><MaxColor/></Gradient>` — the texture's FOUR-vertex
-            // colour, and the one XML surface that tints a `file=` texture. It survives alongside
-            // the art because it lands in a different field: the child loop writes the vertex
-            // colours (`+0xb8`, stride 4 — `0x77304d`-`0x77305f`, "4 iff count > 1") while `file=`
-            // is read only afterwards into `+0xcc`
-            // (`0x770102`). That is why `<Color>` beside a `file=` is
-            // discarded above and a `<Gradient>` beside one is not.
-            //
-            // Dropping this silently is what painted Bagnon's character-list popup as a WHITE SLAB:
-            // its background art is `ChatFrameBackground`, which is white by design and is meant to
-            // be tinted black→dark-grey by exactly this element (`Bagnon_Core/core/Frame.xml:32`).
-            //
-            // MinColor → the first stop, MaxColor → the second, which is the natural reading and
-            // the Lua binding's own argument order — but the XML arm's stop-to-vertex mapping is
-            // **not byte-read** (the reference confirms the `<Gradient>` tag compare at `0x7700b0`
-            // and the stride, not the arm's body). It cannot matter yet: `RegionData::gradient` is
-            // folded to its midpoint by the paint (`script::extract`), which is symmetric in the
-            // two stops. Swapping them becomes visible the day a quad carries a real two-stop tint.
+            // `<Gradient>` writes the vertex colours (`+0xb8`, `0x77304d`), which `file=` leaves
+            // alone, so unlike `<Color>` it tints the art. MinColor is the first stop and MaxColor
+            // the second; the reference's stop-to-vertex order is untraced (`0x7700b0`).
             if let Some(g) = children_named(region, "Gradient").next() {
                 let stop = |tag: &str| children_named(g, tag).next().map(color_of);
-                // A half-declared gradient is skipped whole rather than half-applied against an
-                // invented default — an absent stop is not a black one.
+                // A gradient missing a stop is skipped: an absent stop is not a black one.
                 if let (Some(min), Some(max)) = (stop("MinColor"), stop("MaxColor")) {
                     self.call_region(
                         region_wrapper,
@@ -360,22 +280,15 @@ impl Loader<'_> {
                     );
                 }
             }
-            // `<TexCoords left right top bottom>`: the UV sub-rect this texture samples (decision
-            // 0084 — quadrant/atlas slicing). ref-MerchantFrame.xml l.259/268/395.
             if let Some(tc) = tex_coords_of(region) {
                 self.call_region(region_wrapper, "SetTexCoord", tc, dbg);
             }
-            // `alphaMode="ADD"` on a `<Layers>` texture — the same blend attribute the state-texture
-            // path already applies; dropping it here rendered every layer glow (the quest log's
-            // selection highlight, ref UI-QuestLogTitleHighlight) as an opaque gray bar instead of
-            // an additive glow (the 0109 look fix).
             if let Some(mode) = region.attr("alphaMode") {
                 self.call_region(region_wrapper, "SetBlendMode", mode.to_string(), dbg);
             }
         } else {
             if let Some(text) = region.attr("text") {
-                // `<FontString text=>` is a global-string lookup, not a literal
-                // (`0x703bf0`). See `Loader::resolve_text`.
+                // A global-string key, not a literal (`0x703bf0`).
                 let text = self.resolve_text(text, dbg);
                 self.call_region(region_wrapper, "SetText", Some(text), dbg);
             }
@@ -390,34 +303,14 @@ impl Loader<'_> {
         }
     }
 
-    /// Follow a FontString's `inherits=` to the **font object** at the end of it, through any
-    /// virtual FontString templates in between.
-    ///
-    /// Returns the name unchanged when it already names a font object (the one-hop case), the
-    /// template chain's font object when it does not, and `None` when the chain ends without one —
-    /// which is the case the caller still warns about, because an `inherits=` naming nothing at all
-    /// is a real gap and not something to swallow.
-    ///
-    /// `inherits=` is comma-separated in general; the first entry that resolves wins, which matches
-    /// the single-font reality (a region cannot wear two faces) without pretending the list cannot
-    /// exist. Depth is bounded: a template registry can contain a cycle, and a loader that hangs on
-    /// a malformed addon is worse than one that gives up on it.
+    /// The font object a FontString's `inherits=` names, directly or through virtual FontString
+    /// templates; `None` when the chain ends without one. Bounded, as a registry can hold a cycle.
     pub(super) fn font_object_through_templates(&self, inherits: &str) -> Option<String> {
-        // **The probes here stay case-EXACT, and the outcome is still folded.** Font names match
-        // case-insensitively in 1.12 (`0x783870`, `SStrCmpI`), and that fold lives in
-        // `Model::font_object` — so a miss here falls through to the caller's
-        // `unwrap_or_else(|| name.to_string())` and `SetFontObject` resolves it anyway.
-        //
-        // Not folded HERE because the `framexml_fonts` element registry's other reader hands its
-        // keys to `framexml::expand`, which is the SAME expansion templates go through — and
-        // whether the client matches TEMPLATE names case-insensitively is unconfirmed. Folding this
-        // registry would quietly extend a verified font fact to unverified template behaviour.
         const MAX_HOPS: usize = 8;
         let model = self.model();
         let fonts = model.framexml_fonts.borrow();
         let templates = model.framexml_templates.borrow();
-        // One name, not a comma list — 1.12's lookup has no splitter, and supporting one is a
-        // superset of it. Folded on the probe, like the resolution itself.
+        // One name, not a comma list: 1.12's lookup has no splitter.
         for entry in [inherits] {
             let mut name = entry.to_string();
             for _ in 0..MAX_HOPS {
@@ -438,60 +331,21 @@ impl Loader<'_> {
         None
     }
 
-    /// Is `name` a registered `<Font>` OBJECT? The plain registry probe — **no template walk**,
-    /// unlike [`Self::font_object_through_templates`]. This is the reference's `0x783870(value,
-    /// create = 0)` lookup, which is a flat registry hit or nothing; the template chain is
-    /// `inherits=`'s affordance alone.
-    ///
-    /// Case-folded, because 1.12 matches font names with `SStrCmpI` (`0x783870`).
+    /// Whether `name` is a registered font object: the reference's flat, case-insensitive lookup
+    /// (`0x783870`, `SStrCmpI`), with no template walk.
     pub(super) fn is_font_object(&self, name: &str) -> bool {
         let model = self.model();
         let fonts = model.framexml_fonts.borrow();
         fonts.contains_key(name) || fonts.keys().any(|k| k.eq_ignore_ascii_case(name))
     }
 
-    /// A `<FontString>`'s font resolution: `inherits="GameFontNormal"` → `SetFontObject` (the named
-    /// virtual Font object's face/height/color/outline become this string's defaults), then the
-    /// FontString's own `font=`/`<FontHeight>`/`outline=` → `SetFont` overrides. Called before the
-    /// generic visual pass (so an explicit `<Color>` still overrides the object's color). An
-    /// unregistered `inherits=` target is a warn-once gap, not a dropped region.
-    ///
-    /// **`font=` is a font-object NAME first and a file path only on a miss** — the half of this
-    /// that was missing, and a silent one. The reference tries the registry before the filesystem:
-    /// `0x783d15 call 0x783870(value, create = 0)`, and on a hit takes the same live-link
-    /// `0x770c60` that `SetFontObject` uses, skipping the file-path branch entirely
-    /// (`CSimpleFontString::LoadXML 0x770f40` at `0x7710e1`-`0x771114`).
-    ///
-    /// Reading it as a path only is what made Bagnon's item-stack counts unreadable: its
-    /// `<FontString name="$parentCount" font="NumberFontNormal">` (`Bagnon_Core/core/Item.xml:14`)
-    /// stored the literal string `"NumberFontNormal"` as a font PATH, which resolves to no face —
-    /// so height, colour and, above all, `outline="NORMAL"` were all lost, and the atlas fell back
-    /// silently to Friz 12. The black ring around a stack count is that outline (`NumberFontNormal`
-    /// carries no `<Shadow>` in 1.12 — the readability is the halo, not a drop shadow).
-    ///
-    /// Real FrameXML never exercises this: it writes `font=` on `<Font>` elements only, always as a
-    /// path. The addon corpus writes it on FontStrings 117 times.
+    /// A `<FontString>`'s font: `inherits=` through [`Self::font_object_through_templates`], then
+    /// `font=`, a font object's name first and a file only on a miss (`0x770f40`, `0x771104`).
     pub(super) fn apply_fontstring_font(&mut self, region: &Element, wrapper: &Table, dbg: &str) {
         if let Some(name) = region.attr("inherits") {
-            // **Resolved through the TEMPLATE chain, not taken literally.** A FontString's
-            // `inherits=` may name a font object *or* a virtual FontString template, and a template
-            // may itself inherit the font object — which is how every "declare the line once, stamp
-            // it N times" addon is written. `expand_region` splices the template's attributes in,
-            // but the merged element keeps the INSTANCE's own `inherits=` (the template's name), so
-            // the font object at the far end of the chain was simply lost: one hop worked and two
-            // did not.
-            //
-            // `EQL3_Tracker.xml` is the corpus instance — `EQL3_QuestWatch_FontTemplate` inherits
-            // `GameFontHighlight` and each `EQL3_QuestWatchLine<i>` inherits the template — and it
-            // is not a cosmetic loss. `EQL3_Options.lua:1086` reads the line's font back with
-            // `GetFont()` and feeds it straight to `SetFont(t1, height, t2)`, so the dropped face
-            // came back as OUR OWN faithful `Usage: <FontString>:SetFont(...)` raise, firing on our
-            // own nil, and took the addon's session with it.
-            // An UNRESOLVED chain passes the name through UNCHANGED rather than something
-            // emptier. Handing `SetFontObject("")` an empty string is not the same request as
-            // handing it a bad name — it reads as "clear the font object", which is a silent state
-            // change where the old code produced a loud warn, and it cost EQL3 a NEW load-time
-            // failure the first time this landed.
+            // The expanded element keeps the instance's `inherits=`, a template's name, so the
+            // chain is walked to its font object. An unresolved name passes through unchanged:
+            // `SetFontObject("")` would clear the font object where a bad name warns.
             let resolved = self
                 .font_object_through_templates(name)
                 .unwrap_or_else(|| name.to_string());
@@ -502,30 +356,10 @@ impl Loader<'_> {
                 );
             }
         }
-        // **`font=` gates this whole block, and that is the shape of the bytes** — not a set of
-        // independent overrides (`0x7710e1`-`0x771254`). Three outcomes, and only three:
-        //
-        //  1. `font=` names a **registered font object** → `SetFontObject` (`0x771104` lookup,
-        //     `0x771114 call 0x770c60` — the same live link `inherits=` takes) and then
-        //     `0x771119 jmp 0x771254`, which **skips `<FontHeight>`, `outline=`, `monochrome=` and
-        //     the file load entirely**. The skipped values are not lost: the link forces all five
-        //     changed bits (`0x770d0c`) and the applier `0x770800` pushes the source's
-        //     height/face/outline down through the inherit mask.
-        //  2. `font=` names anything else → a font **FILE**, and `<FontHeight>`/`outline=`/
-        //     `monochrome=` are read as ITS companions (the miss leg, `0x77110b je 0x77111e`).
-        //  3. **No `font=` at all** → `0x7710f1`/`0x7710fa je 0x771254` jump straight past, so
-        //     `<FontHeight>` and `outline=` are **never parsed**. That block's only predecessor is
-        //     the miss leg in (2); the attributes have no independent existence.
-        //
-        // (3) is the one that changes something we already draw. Real FrameXML has exactly one such
-        // site — `ZoneText.xml`'s `AutoFollowStatusText`, `inherits="GameFontNormal"` with a
-        // `<FontHeight val="20">` and no `font=` — so the real client draws that line at
-        // GameFontNormal's **12**, and Blizzard's 20 is dead XML. Our copy carries the same dead 20
-        // and honoured it until now. The corpus has 22 more of these plus 5 stray `outline=`.
-        //
-        // Only `spacing=`/`justifyH`/`justifyV`/`<Color>`/`<Shadow>` sit past the join and are
-        // genuine post-link overrides — they are applied elsewhere (`apply_region_layout` /
-        // `apply_region_visual`), which is already the right side of this line.
+        // `font=` gates `<FontHeight>` and `outline=` (`0x7710e1`-`0x771254`): a font object's
+        // name links it and skips them (`0x771114`, `0x771119`), any other value is a file they
+        // qualify (`0x77110b`), and with no `font=` they are never read (`0x7710fa`), so
+        // `ZoneText.xml`'s `AutoFollowStatusText` draws at GameFontNormal's 12, not its own 20.
         match region.attr("font") {
             Some(name) if self.is_font_object(name) => {
                 if let Err(e) = wrapper.call_method::<()>("SetFontObject", name.to_string()) {
@@ -536,11 +370,8 @@ impl Loader<'_> {
                 }
             }
             Some(path) => {
-                // A font FILE, with its two companions. NOT the `SetFont` binding: XML supplies any
-                // subset, while the reference's `SetFont` requires a path AND a height (raising
-                // `0x87c69c` otherwise), because the real client applies XML font attributes in C++
-                // and never through the Lua method. Routing the loader through the binding is
-                // exactly what forced that binding to stay lenient — one name doing two jobs.
+                // Applied directly, not through the Lua `SetFont`, which requires a height
+                // (`0x87c69c`) where XML may omit it.
                 let height = children_named(region, "FontHeight")
                     .next()
                     .and_then(abs_value);
diff --git a/crates/benilla-ui/src/loader/scripts.rs b/crates/benilla-ui/src/loader/scripts.rs
index c48e488f..8ddabecc 100644
--- a/crates/benilla-ui/src/loader/scripts.rs
+++ b/crates/benilla-ui/src/loader/scripts.rs
@@ -5,11 +5,8 @@ use crate::framexml::Element;
 use super::{children_named, Loader};
 
 impl Loader<'_> {
-    /// `<Scripts>` → SetScript each handler (`0x769ef0`). Handler source comes from the element
-    /// body (`<OnClick>lua…</OnClick>`) or a `function="Global"` attribute. Returns the compiled
-    /// `OnLoad` handle (if any) so the caller can fire it bottom-up. A body that fails to *compile* is
-    /// an error; an unsupported handler *name* (e.g. the keyboard-focus handlers `OnKeyDown`/`OnChar`,
-    /// not yet modeled) is a warn-once gap.
+    /// `<Scripts>` (`0x769ef0`): `SetScript` for each handler. Returns the `OnLoad`, which the
+    /// caller fires bottom-up.
     pub(super) fn apply_scripts(
         &mut self,
         el: &Element,
@@ -17,16 +14,8 @@ impl Loader<'_> {
         dbg: &str,
     ) -> Option<Function> {
         let mut onload = None;
-        // **The chunk name of an XML handler body is `"<GetName()>:<Handler>"`, read off the
-        // WRAPPER — not off the loader's diagnostic string.** `0x7025fd` calls the script object's
-        // `GetName` through its own vtable (`[[esi]+4]`), falls back to `<unnamed>` (`0x84c7f0`)
-        // at `0x702611` when that is NULL, formats `"%s:%s"` (`0x872a28`) at `0x70261b`, and hands
-        // the result to `0x704c70` at `0x70263c` as the chunk name.
-        //
-        // Reading it here rather than plumbing `dbg` down is the fidelity: `dbg` is a *sentence*
-        // on the `CreateFrame` path (`CreateFrame("Button", "Foo", inherits="Bar")`), which made
-        // every template-inherited handler's errors and `debugstack` frames read as one, and an
-        // unnamed element wrote `<Button>` where the image writes `<unnamed>`.
+        // A handler's chunk name is `"<GetName()>:<Handler>"` off the wrapper, `<unnamed>` for a
+        // nameless frame (`0x7025fd`-`0x70263c`), never the loader's `dbg`.
         for scripts in children_named(el, "Scripts") {
             let owner = wrapper
                 .call_method::<Option<String>>("GetName", ())
@@ -35,31 +24,10 @@ impl Loader<'_> {
                 .unwrap_or_else(|| "<unnamed>".to_string());
             for handler in &scripts.children {
                 let name = handler.tag.clone();
-                // **AN EMPTY BODY IS A CLEAR, AND WHITESPACE IS NOT EMPTY** — the two byte
-                // tests at `SetScript 0x7025c0`, reproduced rather than approximated:
-                //
-                //     7025ec  call 0x702670      ; unref the PREVIOUS handler, unconditionally
-                //     7025f4  test ebx,ebx
-                //     7025f6  je 0x702655        ; text == NULL -> store 0 (reads back as nil)
-                //     7025f8  cmp byte ptr [ebx],0
-                //     7025fb  je 0x702655        ; text == ""   -> same
-                //
-                // The XMLTree chardata handler (`0x6f29d0`) appends every run with `len > 0` and
-                // nothing trims, so `0x7025f8` tests the FIRST BYTE of the raw body.
-                //
-                // That distinction is the whole finding, and it is not academic. 1.12's own
-                // FrameXML has **zero** `<OnX/>` and **zero** `<OnX></OnX>`; its seven blanking
-                // sites (BuffFrame ×3, BankFrame, PaperDollFrame ×2, UIPanelTemplates) are all
-                // `<OnLoad>`↵`</OnLoad>` — a body of `"\n\t\t\t"`, whose first byte is `0x0A`.
-                // Both tests fail and it **compiles to a valid empty function**. So
-                // `TempEnchant1:GetScript("OnLoad")` answers a FUNCTION in the real client, not
-                // nil, and the inherited `BuffButton_OnLoad` is displaced rather than removed.
-                // A `.trim()` here would produce the right window and the wrong answer to an addon.
-                //
-                // The clear path is still real (an empty body, or a `function=` element with no
-                // body — 5875 never reads that attribute at all, so it takes the NULL leg), and it
-                // matters that it is a stored nil: a `0` registry ref is skipped by the dispatch
-                // guard entirely, where the compiled no-op is entered and returns.
+                // An empty body clears the handler to nil, but a whitespace one is an empty
+                // function: `SetScript` (`0x7025c0`) tests only NULL and the first byte
+                // (`0x7025f8`), and nothing trims the body (`0x6f29d0`). The stock blanks
+                // (`BuffFrame.xml:101`) are whitespace, so their `GetScript` answers a function.
                 let cleared = handler.body.is_empty() && handler.attr("function").is_none();
                 let func = if cleared {
                     None
@@ -69,7 +37,6 @@ impl Loader<'_> {
                         None => continue,
                     }
                 };
-                // SetScript stores it; an unsupported name errors — surface as a gap, don't drop hard.
                 if let Err(e) = wrapper.call_method::<()>("SetScript", (name.clone(), func.clone()))
                 {
                     self.warn_once(
@@ -78,22 +45,10 @@ impl Loader<'_> {
                     );
                     continue;
                 }
-                // The real `<Scripts>` walker auto-enables the matching input kind after each
-                // successful SetScript (`0x769ef0` → `0x76af00(kind,-1)` per handler name): the
-                // five MOUSE-kind handlers arm the same enable as the XML `enableMouse` attribute —
-                // `OnDragStart` is in the set, `OnDragStop`/`OnReceiveDrag` are NOT. This is
-                // XML-load-time ONLY: the Lua SetScript binding (`0x7748d0`) never auto-enables, so
-                // the law
-                // lives here and not in SetScript itself (a runtime-created frame still needs an
-                // explicit `EnableMouse(true)`, like the real client). The KEYBOARD kinds are
-                // modelled and armed just below, and the WHEEL kind (`OnMouseWheel` = kind 3) is
-                // armed the same way right after — it used to say "a separate index this engine
-                // doesn't model yet", and the wheel dispatcher's own gate (`0x7664f0` →
-                // `0x76c180`) is what made modelling it necessary:
-                // the wheel plane is the ONE place the engine really does gate on a handler and
-                // continue past a frame that has none. Until it was its own flag, our wheel sweep
-                // had to accept any mouse-enabled frame as a stand-in, and the first such frame
-                // swallowed the wheel.
+                // After each `SetScript` the XML walker enables the handler's input kind
+                // (`0x769ef0` → `0x76af00`): these five arm the mouse (`OnDragStop` and
+                // `OnReceiveDrag` do not), `OnMouseWheel` the wheel (kind 3). The Lua `SetScript`
+                // never does (`0x7748d0`).
                 const MOUSE_KIND: [&str; 5] = [
                     "OnEnter",
                     "OnLeave",
@@ -107,20 +62,14 @@ impl Loader<'_> {
                 if name.eq_ignore_ascii_case("OnMouseWheel") {
                     self.call(wrapper, "EnableMouseWheel", true, dbg);
                 }
-                // The KEYBOARD kinds, the same walker rule one index over (`OnChar` = kind 0,
-                // `OnKeyDown`/`OnKeyUp` = kind 1). Bucket membership is what the delivery walk
-                // iterates ([`crate::script::keyboard`]) and it is the FLAG, never the presence of
-                // a script — so an XML frame carrying a key handler but no `enableKeyboard`
-                // attribute would never be reached by the dispatcher at all, and its handler could
-                // not fire. XML-load-time only, like the mouse half.
+                // The key handlers, the same rule (`OnChar` kind 0, `OnKeyDown`/`OnKeyUp` kind 1);
+                // here any of them sets the one flag both key walks read.
                 const KEY_KIND: [&str; 3] = ["OnChar", "OnKeyDown", "OnKeyUp"];
                 if KEY_KIND.iter().any(|k| name.eq_ignore_ascii_case(k)) {
                     self.call(wrapper, "EnableKeyboard", true, dbg);
                 }
                 if name.eq_ignore_ascii_case("OnLoad") {
-                    // A blanked `<OnLoad/>` leaves nothing to fire — and it must also UNSET a
-                    // handle a template's own OnLoad put here, or the caller fires the very body
-                    // this element exists to remove.
+                    // A cleared `OnLoad` also unsets a template's, or the caller would fire it.
                     onload = func;
                 }
             }
@@ -128,50 +77,11 @@ impl Loader<'_> {
         onload
     }
 
-    /// Compile a handler element into `function(self, ...) <body> end`, or resolve its
-    /// `function="Global"` reference. A syntax error in the body is recorded as an error (and the
-    /// handler dropped), never a panic.
-    ///
-    /// ## `self` falls back to `this`, and that one clause is a whole class of addon bug
-    ///
-    /// The 1.12 contract for an XML script body is that it takes **no arguments**: the frame
-    /// arrives as the `this` global, which [`crate::script::event::invoke_with_globals`] sets
-    /// around every dispatch. This engine also passes the modern `(self, event, …)` positionals —
-    /// convenient, and what Era-era addons expect — and our own FrameXML is written against
-    /// *that* spelling (`<OnEnter>BenillaBagToggle_OnEnter(self)</OnEnter>`).
-    ///
-    /// The two spellings agree right up until **an addon captures a script and calls it back**,
-    /// which is the standard 1.12 hook idiom and the reason `GetScript` exists:
-    ///
-    /// ```lua
-    /// bMainBag_OnEnter = MainMenuBarBackpackButton:GetScript("OnEnter")  -- Bagnon.lua:61
-    /// MainMenuBarBackpackButton:SetScript("OnEnter", BagnonBlizMainBag_OnEnter)
-    /// function BagnonBlizMainBag_OnEnter()
-    ///     …
-    ///     bMainBag_OnEnter()      -- l.87: no arguments. The reference's contract.
-    /// end
-    /// ```
-    ///
-    /// The re-entry is perfectly legal, `this` is correctly set (Bagnon's own body reads
-    /// `this:GetID()` one line above), and our compiled body still took `self` from argument 1 —
-    /// which was nil. The director saw it as `bad argument #2: error converting Lua nil to table`
-    /// out of `GameTooltip:SetOwner`, from a handler that works perfectly when the engine calls it.
-    ///
-    /// So the fallback lives **here**, once, rather than as `(self or this)` sprinkled through
-    /// ~20 handler bodies: any XML body in any file — ours or an addon's — now works under both
-    /// callers.
-    ///
-    /// ## The prologue shares the body's first line, and that is a line-number fix
-    ///
-    /// The reference compiles the handler body **as the chunk**: `0x704c70` takes the raw text and
-    /// `luaL_loadbuffer`s it, so body line *n* is chunk line *n*. Our wrapper used to end with a
-    /// newline, which pushed every body line down by one — a `<OnClick>` whose code sat on the
-    /// element's second line reported `:3:` where the reference reports `:2:`. Keeping the
-    /// prologue on the body's own first line restores the reference's numbering exactly; the
-    /// closing `end` is the only line we add, and it lands *after* the body.
-    ///
-    /// `owner` is the frame's `GetName()` (or `<unnamed>`) — see [`Self::apply_scripts`] for the
-    /// bytes; `dbg` names the load for the report and is deliberately not the same string.
+    /// Compile a handler body, or resolve its `function=` global: not 1.12, whose loader never
+    /// reads the attribute. A 1.12 body takes no arguments and reads its frame from `this`; the
+    /// `self` parameter is not 1.12 either (our `assets/ui` bodies use it) and falls back to `this`
+    /// for a hook that calls a captured handler bare. The prologue shares the body's first line,
+    /// so line numbers match the reference, which loads the raw body as the chunk (`0x704c70`).
     pub(super) fn compile_handler(
         &mut self,
         handler: &Element,
@@ -179,10 +89,7 @@ impl Loader<'_> {
         owner: &str,
         dbg: &str,
     ) -> Option<Function> {
-        // **The raw body, NOT a trimmed one** — 1.12 hands `node->text` straight to
-        // `luaL_loadbuffer` and tests only its first byte, so a whitespace-only body is a real
-        // (empty) chunk there and must be one here. See `apply_scripts` for the bytes and for the
-        // seven stock files that depend on it.
+        // The raw body, never trimmed: a whitespace body is a real empty chunk (`apply_scripts`).
         let body = handler.body.as_str();
         if !body.is_empty() {
             let src = format!(
@@ -221,14 +128,9 @@ impl Loader<'_> {
         None
     }
 
-    /// Fire a captured `OnLoad` with the frame wrapper as both the legacy `this` global
-    /// (`0x704d50`, set-then-restored) and the modern `self` argument — the same dual convention
-    /// the host's event path uses; we replicate only the `this` set/restore here because there is
-    /// no public host API to
-    /// fire `OnLoad` directly (it is not an event). Handler errors are recorded, never propagated.
+    /// Fire a captured `OnLoad` under the event path's convention, `this` set and restored
+    /// (`0x704d50`); an error is recorded, never propagated.
     pub(super) fn fire_onload(&mut self, wrapper: &Table, func: &Function, dbg: &str) {
-        // The `this`/`self` convention lives in one home (`UiScript::invoke_handler`); the
-        // loader doesn't re-implement the set/restore, it just supplies the wrapper + captured func.
         if let Err(e) = self.invoke_handler(wrapper, func) {
             self.report.errors.push(format!("{dbg}: OnLoad: {e}"));
         }
diff --git a/crates/benilla-ui/src/loader/tests.rs b/crates/benilla-ui/src/loader/tests.rs
index eb1820cb..a2ba089b 100644
--- a/crates/benilla-ui/src/loader/tests.rs
+++ b/crates/benilla-ui/src/loader/tests.rs
@@ -1,4 +1,4 @@
-//! Loader tests — split from `mod.rs` (file-size budget); same `super::*` view.
+//! Loader tests.
 
 mod loader_tests {
     use crate::framexml;
@@ -6,7 +6,6 @@ mod loader_tests {
     use crate::order::ZTarget;
     use crate::script::{QuadContent, UiScript};
 
-    /// No-provider `files` closure (for docs with no `<Include>`/`<Script file=>`).
     fn no_files(_: &str) -> Option<Vec<u8>> {
         None
     }
@@ -15,16 +14,9 @@ mod loader_tests {
         framexml::parse(text).expect("valid FrameXML")
     }
 
-    /// **`<Minimap>`'s two model attributes name the nine engine children** — the model half of
-    /// `CMinimap::LoadXML 0x4ee2b0`. `minimapArrowModel` goes to children 1–8 through `0x4ee170`'s
-    /// two loops (the five at `[+0x320]`, the three POI arrows at `[+0x314]`);
-    /// `minimapPlayerModel` goes to `[Minimap+0x338]` — child **9** — alone, through `0x4ee260`.
-    /// Without the split all nine read back `GetModel() == ""` and nothing in the tuple says which
-    /// one is the player arrow.
-    ///
-    /// Both halves in one document: the shipped spelling (`Minimap.xml:97` sets both explicitly)
-    /// and an attribute-less `<Minimap>`, which takes the engine defaults `0x84c768` / `0x8453c0`
-    /// rather than staying file-less.
+    /// `CMinimap::LoadXML 0x4ee2b0`: `minimapArrowModel` goes to engine children 1-8 (`0x4ee170`),
+    /// `minimapPlayerModel` to child 9 alone (`[Minimap+0x338]`, `0x4ee260`); without the
+    /// attributes the defaults are `0x84c768` and `0x8453c0`. `Minimap.xml:97` sets both.
     #[test]
     fn the_minimap_model_attributes_name_the_nine_engine_children() {
         let mut s = UiScript::new().unwrap();
@@ -49,7 +41,6 @@ mod loader_tests {
         let report = load(&s, &doc, &no_files);
         assert!(report.errors.is_empty(), "{:?}", report.errors);
 
-        // 1–8 wear the arrow, 9 wears the player model — the authored spelling, unchanged.
         for i in 1..=8 {
             assert_eq!(
                 s.eval::<String>(&format!(
@@ -67,16 +58,14 @@ mod loader_tests {
             "child 9 — [Minimap+0x338] — takes minimapPlayerModel alone"
         );
 
-        // The `<Frames>` child lands PAST the nine, because the factory runs before the descent
-        // (`0x6ee408` before `0x6ee4ea`) and both linkers append at the tail. This is the whole
-        // reason `[9]` is a stable address for an addon.
+        // The `<Frames>` child comes after the nine: the factory runs before the descent
+        // (`0x6ee408` before `0x6ee4ea`) and both append at the tail.
         assert_eq!(
             s.eval::<String>("return ({Minimap:GetChildren()})[10]:GetName()")
                 .unwrap(),
             "MiniMapPingHost"
         );
 
-        // No attributes: the engine defaults, not nothing.
         assert_eq!(
             s.eval::<String>("return ({BareMinimap:GetChildren()})[1]:GetModel()")
                 .unwrap(),
@@ -89,13 +78,7 @@ mod loader_tests {
         );
     }
 
-    /// **`parent="Name"` attaches a top-level element** — the reference's own way of doing it,
-    /// because its FrameXML is flat (decision 1211). 79 corpus addons, 708 sites.
-    ///
-    /// Three claims in one document: the attribute supplies the parent when there is no lexical
-    /// one; an anchor with no `relativeTo` then measures from THAT parent rather than the screen
-    /// (the silent half — a frame in the wrong place with nothing to report); and a name that
-    /// resolves to nothing warns and falls back instead of raising.
+    /// The stock FrameXML attaches with `parent=`; a `relativeTo`-less anchor measures from it.
     #[test]
     fn a_top_level_parent_attribute_attaches_and_anchors() {
         let mut s = UiScript::new().unwrap();
@@ -142,7 +125,6 @@ mod loader_tests {
             "a relativeTo-less anchor measures from the PARENT, not the screen"
         );
 
-        // The miss: a warning, a usable frame, and no parent — never an error.
         assert!(s.eval::<bool>("return Orphan ~= nil").unwrap());
         assert!(s.eval::<bool>("return Orphan:GetParent() == nil").unwrap());
         assert!(
@@ -151,10 +133,7 @@ mod loader_tests {
             report.warnings
         );
 
-        // And a name that exists but is NOT a frame is the same miss, not a raise. `_G` is one
-        // namespace and an addon's own `MyAddon = {}` lives in it — the corpus writes
-        // `parent="TheoryCraft"` where the addon owns that name. Handing a plain table to
-        // CreateFrame would kill the element and its whole subtree.
+        // A global that is not a frame is the same miss, not a raise.
         s.run("NotAFrame = { some = 'table' }").unwrap();
         let doc2 = parse(
             r#"<Ui>
@@ -177,16 +156,8 @@ mod loader_tests {
         );
     }
 
-    /// **A `parent=` that resolves to nothing leaves the frame PARENTLESS** — it does not fall back
-    /// to the enclosing frame (decision 2213). `0x6ee280` seeds `[ebp-0x8]` with the incoming
-    /// default parent and then writes the lookup's result back **unconditionally** at
-    /// `0x6ee3ef`, so a miss stores 0 over the seed and `0x6ee408` constructs with `ecx = 0`. And
-    /// an **empty** `parent=""` short-circuits
-    /// at `0x6ee3c7` before any of that: the default parent is kept, silently.
-    ///
-    /// Only the nested case can tell these apart — at top level there is no enclosing frame to
-    /// fall back to, which is why
-    /// [`Self::a_top_level_parent_attribute_attaches_and_anchors`] passed either way.
+    /// A miss stores 0 over the default parent (`0x6ee3ef`), so the frame is built parentless; an
+    /// empty `parent=""` keeps the default silently (`0x6ee3c7`).
     #[test]
     fn a_parent_attribute_that_misses_leaves_the_frame_parentless() {
         let mut s = UiScript::new().unwrap();
@@ -213,15 +184,13 @@ mod loader_tests {
         assert!(report.errors.is_empty(), "{:?}", report.errors);
         s.resolve();
 
-        // The miss: parentless, NOT re-attached to Enclosing.
         assert!(s.eval::<bool>("return TopMissed ~= nil").unwrap());
         assert!(
             s.eval::<bool>("return TopMissed:GetParent() == nil")
                 .unwrap(),
             "a parent= that names nothing nulls the parent; it does not fall back"
         );
-        // …and with no parent, the `$parent` chain walk finds nothing, so the "Top" seed survives
-        // (`0x76c5b0`) — hence `TopMissed`, not `EnclosingMissed`.
+        // With no parent, `$parent` falls to the `"Top"` seed (`0x76c5b0`): `TopMissed`.
         assert!(s.eval::<bool>("return EnclosingMissed == nil").unwrap());
         assert!(
             report
@@ -232,7 +201,6 @@ mod loader_tests {
             report.warnings
         );
 
-        // The empty attribute: the enclosing frame is kept, and nothing is logged.
         assert_eq!(
             s.eval::<String>("return EnclosingEmpty:GetParent():GetName()")
                 .unwrap(),
@@ -246,18 +214,8 @@ mod loader_tests {
         );
     }
 
-    /// **A top-level `name="$parent…"` resolves against the `parent=` attribute** (B387) — the
-    /// reference attaches the parent *first* (`0x6ee280` resolves it at `0x6ee3e8` and passes it to
-    /// the constructor at `0x6ee408`) and only then runs the node-apply step that reads `name=` and
-    /// calls `SetName` (`0x6ee4d6`), whose expander walks the frame's **actual** parent chain
-    /// (`0x76c5b0`). We resolved the name first, against the lexical ancestor, so ClassIcons'
-    /// `<Frame name="$parentClassIcon" parent="PlayerFrame"/>` was published as `TopClassIcon` and
-    /// every `PlayerFrameClassIcon` lookup in the addon indexed a nil.
-    ///
-    /// Four claims: the name takes the attribute parent's name; that frame's own children compose
-    /// off the corrected name; a top-level `$parent` with no attribute still falls to the `"Top"`
-    /// seed; and the `parent=` attribute itself is NOT expanded (`0x6ee3e8` calls the by-name
-    /// resolver direct, bypassing `0x76c5b0`).
+    /// The reference attaches the parent (`0x6ee408`) before it applies `name=` (`0x6ee4d6`), and
+    /// `$parent` walks the real parent chain (`0x76c5b0`); `parent=` itself is never expanded.
     #[test]
     fn a_dollar_parent_name_resolves_against_the_parent_attribute() {
         let mut s = UiScript::new().unwrap();
@@ -310,11 +268,10 @@ mod loader_tests {
             "a nested child composes off the CORRECTED name"
         );
 
-        // No attribute, no lexical parent: the expander's `"Top"` seed survives (`0x76c5b0`).
+        // No attribute, no lexical parent: the `"Top"` seed.
         assert!(s.eval::<bool>("return TopLoose ~= nil").unwrap());
 
-        // `parent="$parentPlayerFrame"` is taken LITERALLY — `0x6ee3e8` hands the raw string to
-        // `0x76c760`, so no frame of that name exists and the element falls back (and warns).
+        // `parent=` is taken literally (`0x6ee3e8` hands it to `0x76c760`), so this one misses.
         assert!(s.eval::<bool>("return Literal:GetParent() == nil").unwrap());
         assert!(
             report
@@ -326,15 +283,11 @@ mod loader_tests {
         );
     }
 
-    /// End-to-end: a virtual template, an instance inheriting it (with `<Size>`, screen `<Anchors>`,
-    /// a `<Layers>` coloured `<Texture>`, a nested child `<Frame>` in `<Frames>`, and `<OnLoad>`
-    /// handlers on both) — proving name publication, bottom-up OnLoad, `$parent`, and that
-    /// resolve()+extract() places the texture at the anchored rect.
+    /// Names, `$parent`, bottom-up `OnLoad` and the anchored texture rect, end to end.
     #[test]
     fn synthetic_full_document_materializes() {
         let mut s = UiScript::new().unwrap();
         s.set_screen_size(800.0, 600.0);
-        // Seed the ordering witness before the load runs any OnLoad.
         s.run("loadorder = {}").unwrap();
 
         let doc = parse(
@@ -373,13 +326,11 @@ mod loader_tests {
         assert!(report.errors.is_empty(), "errors: {:?}", report.errors);
         assert_eq!(report.frames, 2, "parent + child materialized");
 
-        // Frame exists by name; the child's $parent resolved to MyFrameChild; the texture published
-        // its $parent-resolved name.
         assert!(s.eval::<bool>("return MyFrame ~= nil").unwrap());
         assert!(s.eval::<bool>("return MyFrameChild ~= nil").unwrap());
         assert!(s.eval::<bool>("return MyFrameTex ~= nil").unwrap());
 
-        // OnLoad fired for both (modern `self` in child, legacy `this` in parent — both work).
+        // The child's handler uses `self`, the parent's `this`; both work.
         assert_eq!(
             s.eval::<String>("return ChildLoaded").unwrap(),
             "MyFrameChild"
@@ -390,9 +341,7 @@ mod loader_tests {
         let order: Vec<String> = s.eval("return loadorder").unwrap();
         assert_eq!(order, vec!["child".to_string(), "parent".to_string()]);
 
-        // resolve()+extract(): the texture quad sits at MyFrame's anchored rect.
-        // Screen [0,0,600,800], TOPLEFT+(10,-20), size 200x100 → Rect(bottom 480, left 10, top 580,
-        // right 210). Region rect = its owner frame's resolved rect (v1).
+        // TOPLEFT+(10,-20), 200x100 on 800x600: bottom 480, left 10, top 580, right 210.
         s.resolve();
         let quads = s.extract();
         let tex = quads
@@ -408,11 +357,8 @@ mod loader_tests {
         );
     }
 
-    /// An instance's own `<Size>` beats its template's: expansion appends the instance's children
-    /// after the template's, and `apply_size` walks EVERY `<Size>` in document order so the last
-    /// write wins — exactly the client's process-each-child behavior. (Regression: `.next()` here
-    /// once pinned every templated button to the TEMPLATE's size; the quest log's Abandon button
-    /// declared 125×21 and rendered 80×22, wrapping its label onto two lines.)
+    /// Expansion appends the instance's children after the template's and every `<Size>` applies
+    /// in order, as the client processes each child, so the last wins.
     #[test]
     fn instance_size_overrides_template_size() {
         let s = UiScript::new().unwrap();
@@ -438,10 +384,6 @@ mod loader_tests {
         );
     }
 
-    /// A `<Frame setAllPoints="true">` (no `<Size>`/`<Anchors>` of its own) resolves to its
-    /// parent's rect — the frame path honors the shorthand like the region path does.
-    /// (Regression: only regions applied it; the world map's chrome frames carried the attribute,
-    /// never resolved, and their whole subtrees — backdrop, title, buttons — silently vanished.)
     #[test]
     fn frame_set_all_points_pins_to_parent() {
         let mut s = UiScript::new().unwrap();
@@ -470,16 +412,8 @@ mod loader_tests {
         assert_eq!(s.eval::<f32>("return PinChild:GetHeight()").unwrap(), 200.0);
     }
 
-    /// **`<Include file="X.lua">` RUNS the file** — the client's `<Include>` is a recursion into
-    /// its load-one-file routine `0x6ede10`, whose first act is a case-insensitive `.lua` suffix
-    /// test on the resolved path. It never sniffs content; it never parses a `.lua` as XML.
-    ///
-    /// We parsed every target as FrameXML, so a `.lua` target died `unknown token at 1:1` and took
-    /// the whole library set with it. Three corpus addons load nothing but these lines —
-    /// FonzAppraiser, AckisRecipeList, FonzSummon — and `embeds.xml` is the whole of their Ace
-    /// dependency chain.
-    ///
-    /// The mixed document is the point: one `<Include>` of each kind, in one file, both landing.
+    /// `<Include>` recurses into `0x6ede10`, which runs a path with a case-insensitive `.lua`
+    /// suffix and parses anything else as XML; it never sniffs content.
     #[test]
     fn include_runs_a_lua_target_and_still_parses_an_xml_one() {
         let s = UiScript::new().unwrap();
@@ -511,16 +445,13 @@ mod loader_tests {
             s.eval::<bool>("return ShoutyLua").unwrap(),
             "case-insensitive suffix"
         );
-        // ...and the XML arm is untouched: both frames still exist.
         assert_eq!(report.frames, 2);
         assert!(s
             .eval::<bool>("return FromXmlInclude ~= nil and FromMain ~= nil")
             .unwrap());
     }
 
-    /// A raise inside an `.lua` Include is reported and the enclosing document CONTINUES — the
-    /// reference logs at severity 2 and falls through (`0x6ee00d` -> `0x6ee012` is unconditional,
-    /// `eax` never read), so one bad library must not cost the frames declared after it.
+    /// The reference logs the raise and falls through unconditionally (`0x6ee00d`-`0x6ee012`).
     #[test]
     fn a_raising_lua_include_does_not_take_the_rest_of_the_document() {
         let s = UiScript::new().unwrap();
@@ -550,7 +481,6 @@ mod loader_tests {
         );
     }
 
-    /// `<Include>` resolved through an in-memory provider closure.
     #[test]
     fn include_resolves_through_provider() {
         let s = UiScript::new().unwrap();
@@ -574,15 +504,8 @@ mod loader_tests {
             .unwrap());
     }
 
-    /// **An unrecognised `frameStrata=` warns and skips; the frame keeps the stratum it had, and
-    /// the rest of the document loads** (decision 2160).
-    ///
-    /// The two doors differ in the reference and this is the quiet one. `CSimpleFrame::LoadXML
-    /// 0x769820` resolves through `0x6f17d0`, whose miss returns 0 without writing the out-param;
-    /// the miss leg pushes `"Frame %s: Unknown frame strata: %s"` at severity 1 into the document
-    /// sink (`0x7699a4`, a call that returns) and reconverges with the hit path at `0x7699ad`,
-    /// never reaching `SetFrameStrata 0x76a470`. `EQL3`'s `EQL3_Log.xml` carries the literal case:
-    /// `<Frame frameStrata="ARTWORK">`, a draw-LAYER name where a strata belongs.
+    /// `CSimpleFrame::LoadXML 0x769820`: a strata `0x6f17d0` does not know logs at severity 1
+    /// (`0x7699a4`) and skips `SetFrameStrata 0x76a470`.
     #[test]
     fn an_unknown_xml_frame_strata_warns_and_leaves_the_stratum_alone() {
         let mut s = UiScript::new().unwrap();
@@ -617,10 +540,7 @@ mod loader_tests {
         );
     }
 
-    /// **The Lua door is the LOUD one and stays that way.** `SetFrameStrata 0x774360`'s miss
-    /// reaches `0x774456 call 0x6f4940` (`luaL_error`), whose chain `luaG_errormsg 0x6fc780` /
-    /// `luaD_throw 0x6f5d80` contains no `ret` at all — the epilogue after it is dead code. Pinned
-    /// beside its XML twin so the asymmetry is a test rather than a comment.
+    /// The Lua `SetFrameStrata 0x774360` raises on the same value (`luaL_error` at `0x774456`).
     #[test]
     fn the_lua_setframestrata_still_raises_on_the_same_value() {
         let s = UiScript::new().unwrap();
@@ -632,10 +552,8 @@ mod loader_tests {
         assert!(err.contains("ARTWORK"), "{err}");
     }
 
-    /// **`FrameXML_Debug` is a get-or-set whose SET arm turns on the loader's trace lines**
-    /// (decision 2160) — and `0` takes the SET arm, because the number zero is Lua-truthy and only
-    /// `nil`/`false` are not (`0x48845d`, after `lua_toboolean 0x6f34d0`). That is the half a
-    /// re-implementation gets backwards, so it is the half asserted first.
+    /// The reference sets the flag from a number, `0` included, and only reads it for any other
+    /// argument (`0x48845d`, after `lua_isnumber 0x6f34d0`).
     #[test]
     fn framexml_debug_is_a_get_or_set_and_gates_the_loader_traces() {
         let s = UiScript::new().unwrap();
@@ -660,7 +578,6 @@ mod loader_tests {
             "{on:?}"
         );
 
-        // The two arms that are easy to get wrong.
         assert_eq!(
             s.eval::<i32>("return FrameXML_Debug(nil)").unwrap(),
             1,
@@ -672,19 +589,11 @@ mod loader_tests {
             "…but 0 is TRUTHY in Lua, so it really does disable it"
         );
         assert!(load(&s, &doc(), &no_files).traces.is_empty());
-        // …and the stored value is truncated toward zero, `0x40a2b0`'s conversion.
+        // The stored value truncates toward zero (`0x40a2b0`).
         assert_eq!(s.eval::<i32>("return FrameXML_Debug(1.9)").unwrap(), 1);
     }
 
-    /// A missing include is **reported, not raised**, and the rest of the load still proceeds.
-    ///
-    /// It was a warning until 1186 and an error from 1186 to 2155; it is now its own list. Both of
-    /// the findings behind those moves are asserted here, because each undid the other:
-    /// **1186's** — a document that resolved *nothing* must not report success (Bagnon missed all
-    /// eleven of its references and came back with zero errors) — so the row is in the report; and
-    /// **2155's** — the reference logs `Couldn't open %s` (`0x6edaa0`, `0x846ff4`) and carries on
-    /// with nothing raised — so the row is *not* in `errors`, which is the list whose entries
-    /// reach the player's red error dialog.
+    /// The reference logs `Couldn't open %s` (`0x6edaa0`, `0x846ff4`) and carries on.
     #[test]
     fn missing_include_is_a_missing_file_not_an_error_and_continues() {
         let s = UiScript::new().unwrap();
@@ -705,9 +614,7 @@ mod loader_tests {
         );
     }
 
-    /// So is a missing `<Script file=>` — it drops every handler the file would have defined, and
-    /// the reference's own leg for it (`"Error loading %s"`, `0x872e50`) returns
-    /// normally rather than throwing.
+    /// The reference logs `"Error loading %s"` (`0x872e50`) for it and returns normally.
     #[test]
     fn missing_script_file_is_a_missing_file_not_an_error_and_continues() {
         let s = UiScript::new().unwrap();
@@ -721,9 +628,6 @@ mod loader_tests {
         assert!(s.eval::<bool>("return Still ~= nil").unwrap());
     }
 
-    /// **A `<Script file=>` whose chunk RAISES is still an error** — the half `missing_files` must
-    /// not swallow. The two arms sit one line apart in `load_in`, and folding a miss into the
-    /// quiet list is only correct because the raise keeps its own.
     #[test]
     fn a_script_file_that_raises_is_still_an_error() {
         let s = UiScript::new().unwrap();
@@ -740,7 +644,6 @@ mod loader_tests {
         assert!(s.eval::<bool>("return Still ~= nil").unwrap());
     }
 
-    /// `$parent` resolves in a child's *name* and in an anchor's `relativeTo`.
     #[test]
     fn parent_token_in_child_name_and_anchor_relative_to() {
         let mut s = UiScript::new().unwrap();
@@ -765,10 +668,8 @@ mod loader_tests {
         );
         let report = load(&s, &doc, &no_files);
         assert!(report.errors.is_empty(), "{:?}", report.errors);
-        // Child $parent-name resolved to PFInner and published.
         assert!(s.eval::<bool>("return PFInner ~= nil").unwrap());
 
-        // relativeTo="$parent" resolved to PF, so the child sits exactly on the parent's TOPLEFT.
         s.resolve();
         let quads = s.extract();
         let rects: Vec<_> = quads
@@ -778,8 +679,7 @@ mod loader_tests {
                 _ => None,
             })
             .collect();
-        // Parent: screen [0,0,600,800] TOPLEFT+(50,-50), 100x100 → Rect(450,50,550,150). The child,
-        // anchored TOPLEFT→parent TOPLEFT with no offset, resolves to the same rect.
+        // The parent is Rect(450,50,550,150); the child, pinned TOPLEFT to TOPLEFT, matches it.
         let expected = crate::layout::Rect::new(450.0, 50.0, 550.0, 150.0);
         assert!(
             rects.iter().filter(|r| **r == expected).count() >= 2,
@@ -787,9 +687,8 @@ mod loader_tests {
         );
     }
 
-    /// A named state texture and a named `<ButtonText>` are anchor targets by NAME, not only
-    /// globals: the stock trainer row hangs its label off `$parentHighlight`'s RIGHT, and a name
-    /// published only into `_G` sent the label to the button's own edge (1957).
+    /// The stock trainer row's shape: its label hangs off `$parentHighlight`'s RIGHT
+    /// (`ClassTrainerFrameTemplates.xml:67`).
     #[test]
     fn a_named_state_texture_is_an_anchor_target_for_its_sibling_label() {
         let mut s = UiScript::new().unwrap();
@@ -841,8 +740,6 @@ mod loader_tests {
         );
     }
 
-    /// A handler with a syntax error yields an `errors[]` entry, the load continues, and the other
-    /// frame is still built with a working handler.
     #[test]
     fn bad_handler_is_an_error_and_load_continues() {
         let s = UiScript::new().unwrap();
@@ -863,19 +760,11 @@ mod loader_tests {
             "expected a compile error, got {:?}",
             report.errors
         );
-        // The broken frame exists but its OnLoad never ran; the good frame's did.
         assert!(s.eval::<bool>("return Broken ~= nil").unwrap());
         assert!(s.eval::<bool>("return FineRan == true").unwrap());
     }
 
-    /// Unsupported handler names are warn-once gaps, not hard errors, and don't stop the frame
-    /// from building. The example is `OnAttributeChanged` — 2.0's secure-frame system, which no
-    /// 1.12 resolver has a slot for, so it is the one name on that list that is out permanently.
-    ///
-    /// It has been three names now, and each move is the rule working: `OnKeyDown` left when 1319
-    /// built the delivery walk, `OnCursorChanged` when 2141 built the caret flush's fire. A name
-    /// is accepted only once something fires it, so this test's subject is whatever is still
-    /// waiting.
+    /// `OnAttributeChanged` is 2.0's; no 1.12 handler resolver has a slot for it.
     #[test]
     fn unsupported_script_name_is_a_warning() {
         let s = UiScript::new().unwrap();
@@ -891,13 +780,8 @@ mod loader_tests {
             .any(|w| w.contains("OnAttributeChanged")));
     }
 
-    /// **An unknown frame type at the XML door is LOGGED, and its node is skipped — nothing
-    /// raises** (decision 2191).
-    ///
-    /// `Instantiate 0x6ee280` prints `"Unknown frame type: %s"` (`0x871124`) at `0x6ee356` and makes
-    /// no object for that node; only the Lua `CreateFrame` binding raises (`0x872fa8` via
-    /// `luaL_error`). The node's own `<Frames>` go with it — there is no object to parent them —
-    /// and the walk carries on to the next sibling.
+    /// `Instantiate 0x6ee280` logs `"Unknown frame type: %s"` (`0x871124`) and builds nothing for
+    /// the node or its `<Frames>`; only the Lua `CreateFrame` raises (`0x872fa8`).
     #[test]
     fn an_unknown_xml_frame_type_is_logged_and_its_node_skipped() {
         let s = UiScript::new().unwrap();
@@ -924,16 +808,13 @@ mod loader_tests {
         assert_eq!(report.frames, 1, "only the real frame built");
         assert!(s.eval::<bool>("return X == nil and Inside == nil").unwrap());
         assert!(s.eval::<bool>("return Real ~= nil").unwrap());
-        // …and the Lua door still raises, on the same lookup.
+        // The Lua door raises on the same lookup.
         let err = s.run(r#"CreateFrame("Bogus")"#).unwrap_err().to_string();
         assert!(err.contains("unknown frame type 'Bogus'"), "{err}");
     }
 
-    /// **A `.toc`-listed `Bindings.xml` loads as XML and costs nothing but log lines** (decision
-    /// 2191) — MonkeyDev's shape, the director's live report. The `.toc` line runner hands every
-    /// non-`.lua` entry to the same file loader (`0x6edd51` → `0x6ede10`), whose walk ignores the
-    /// root's own tag (`<Bindings>`, tolerated) and sees three `<Binding>` elements: three unknown
-    /// frame types, logged. The file's real reading as bindings is `0x51f400`'s, which runs anyway.
+    /// A `.toc` line hands a listed `Bindings.xml` to `0x6ede10` (from `0x6edd51`), so each
+    /// `<Binding>` logs as an unknown frame type; `0x51f400` reads the bindings regardless.
     #[test]
     fn a_bindings_document_loaded_as_framexml_raises_nothing() {
         let s = UiScript::new().unwrap();
@@ -961,8 +842,7 @@ mod loader_tests {
         );
     }
 
-    /// The WorldFrame's one-shot record, at the XML door: a second `<WorldFrame>` is an unknown
-    /// type, so it logs and builds nothing (decisions 1984, 2191) where `CreateFrame` raises.
+    /// The WorldFrame type is one-shot, so a second `<WorldFrame>` is an unknown type.
     #[test]
     fn a_second_xml_world_frame_is_logged_not_raised() {
         let s = UiScript::new().unwrap();
@@ -980,8 +860,7 @@ mod loader_tests {
         assert!(s.eval::<bool>("return Another == nil").unwrap());
     }
 
-    /// `<StatusBar>` LoadXML extras (`0x782ef0`): value attributes, `<BarTexture>` + `<BarColor>`
-    /// children, orientation — landing in the widget state and scaling the extracted bar quad.
+    /// `<StatusBar>` LoadXML extras (`0x782ef0`).
     #[test]
     fn statusbar_xml_extras_apply() {
         let mut s = UiScript::new().unwrap();
@@ -1034,10 +913,8 @@ mod loader_tests {
         );
     }
 
-    /// The creation-path implicit anchor, XML half (decision 1310; `0x7701c0`): a `<Texture>` with
-    /// zero anchors gets SetAllPoints(parent) right after its LoadXML — two corner anchors that pin
-    /// all four edges, so an authored `<Size>` is structurally unread. This is B180's engine shape:
-    /// the reference stack-split plate authors a vestigial 256×32 and renders 172×96, the frame.
+    /// An anchorless `<Texture>` gets `SetAllPoints` after its LoadXML (`0x7701c0`), so its
+    /// `<Size>` goes unread: `StackSplitFrame.xml:10` authors 256×32 and draws 172×96.
     #[test]
     fn sized_anchorless_layer_texture_fills_its_frame() {
         let mut s = UiScript::new().unwrap();
@@ -1076,9 +953,8 @@ mod loader_tests {
         );
     }
 
-    /// The FontString half of the same law: zero anchors ⇒ ONE middle-row SetPoint chosen by the
-    /// live justify word (`&7`: 1→LEFT, 4→RIGHT, else CENTER) — and the authored `<Size>` stays
-    /// LIVE (single anchor + W/H sizes the opposite edges), unlike the texture's.
+    /// A FontString with no anchors gets one middle-row point from its justify word (`&7`: 1 LEFT,
+    /// 4 RIGHT, else CENTER), so unlike a texture's its `<Size>` stays live.
     #[test]
     fn anchorless_fontstring_seats_at_its_justify_point() {
         let mut s = UiScript::new().unwrap();
@@ -1101,8 +977,7 @@ mod loader_tests {
         let report = load(&s, &doc, &no_files);
         assert!(report.errors.is_empty(), "errors: {:?}", report.errors);
         s.resolve();
-        // LEFT→LEFT at (0,0): left edge at the page's left, vertically on the page's centerline
-        // (middle-row point), 80×20 from the size. Page [0,0]..[200,100] → [0,40]..[80,60].
+        // LEFT to LEFT on the page's centreline, 80×20 from the size: [0,40]..[80,60].
         let (l, r, t, b) = s
             .eval::<(f64, f64, f64, f64)>(
                 "return SeatLeft:GetLeft(), SeatLeft:GetRight(), SeatLeft:GetTop(), SeatLeft:GetBottom()",
@@ -1115,10 +990,8 @@ mod loader_tests {
         );
     }
 
-    /// The XML state-texture ordering (decision 1310's loader half): an authored `<Anchors>` on a
-    /// `<NormalTexture>` wins outright — the materializing setter's implicit SetAllPoints is
-    /// cleared before the authored layout applies, so no implicit corner survives to weld the
-    /// region to the button (the merchant row's icon-scoped highlight is the live consumer).
+    /// The setter's implicit `SetAllPoints` is cleared before the authored anchors apply, so no
+    /// implicit corner survives to weld the state texture to the button.
     #[test]
     fn anchored_state_texture_keeps_its_authored_anchors() {
         let mut s = UiScript::new().unwrap();
@@ -1159,17 +1032,8 @@ mod loader_tests {
         );
     }
 
-    /// **An XML handler body's chunk name is `"<GetName()>:<Handler>"`, and its lines are the
-    /// body's own.** `0x7025fd` calls the script object's `GetName` through its vtable, falls back
-    /// to `<unnamed>` (`0x84c7f0`) at `0x702611`, formats `"%s:%s"` (`0x872a28`) at `0x70261b`,
-    /// and hands that to `0x704c70` at `0x70263c` — which `luaL_loadbuffer`s the raw body, so body
-    /// line *n* is chunk line *n*.
-    ///
-    /// Three producers, because they used to disagree. A named element was already right; an
-    /// unnamed one wrote `<Button>` where the image writes `<unnamed>`; and a `CreateFrame` off a
-    /// template wrote the *whole call* —
-    /// `CreateFrame("Button", "Made", inherits="ProbeTmpl"):OnClick` — into every error message
-    /// and every `debugstack` frame that handler produced.
+    /// `0x7025fd` names a handler chunk `"%s:%s"` (`0x872a28`) from the object's `GetName`, or
+    /// `<unnamed>` (`0x84c7f0`), and `0x704c70` loads the raw body, so body line n is chunk line n.
     #[test]
     fn an_xml_handler_chunk_is_named_by_its_frame_and_handler() {
         let s = UiScript::new().unwrap();
@@ -1203,22 +1067,18 @@ mod loader_tests {
                 .unwrap()
         };
 
-        // A named element. The body sits on the element's SECOND line, and the reference numbers a
-        // handler chunk from the body's own first line — so `:2:`, never `:3:`. Our wrapper used
-        // to end with a newline, which pushed every body line down by one.
+        // The `error` is on the body's second line: `:2:`.
         let named = raised(r#"NamedBtn:GetScript("OnClick")"#);
         assert!(
             named.starts_with(r#"[string "NamedBtn:OnClick"]:2: boom"#),
             "{named}"
         );
-        // A `CreateFrame` instance is named by the INSTANCE — what `GetName()` answers — not by
-        // the call that made it and not by the template it wore.
+        // A `CreateFrame` instance is named by its own `GetName()`, not by its template.
         let made = raised(r#"Made:GetScript("OnClick")"#);
         assert!(
             made.starts_with(r#"[string "Made:OnClick"]:1: tmpl"#),
             "{made}"
         );
-        // The nameless element takes the image's own fallback literal.
         let anon = raised(r#"BenillaAnon:GetScript("OnClick")"#);
         assert!(
             anon.starts_with(r#"[string "<unnamed>:OnClick"]:1: anon"#),
@@ -1226,14 +1086,8 @@ mod loader_tests {
         );
     }
 
-    /// **An inline `<Script>` body is `"<xml path>:<Scripts>"`, with no `@`** — `0x6ee0ed push ebx`
-    /// (the document's own path) / `0x6ee0ee push 0x871074` (`"%s:<Scripts>"`) → `0x6ee0ff` sprintf
-    /// → `0x6ee10f call 0x704cd0`. `luaO_chunkid` therefore takes its *third* branch and the frame
-    /// reads `[string "…"]`, not a bare path — which is how a reader (and every addon that splits a
-    /// `debugstack` frame on `\AddOns\`) tells an inline block from the `.lua` file beside it.
-    ///
-    /// `<Script file="…">` keeps the file form, `"@%s"` (`0x8716e0`), and both are asserted here so
-    /// the two arms cannot drift into each other.
+    /// An inline `<Script>` is `"%s:<Scripts>"` (`0x871074`, at `0x6ee0ff`) over the document's
+    /// path with no `@`, so it reads `[string "…"]`; a `<Script file=>` is `"@%s"` (`0x8716e0`).
     #[test]
     fn an_inline_script_chunk_is_named_for_the_document_not_as_a_file() {
         let s = UiScript::new().unwrap();
@@ -1305,7 +1159,6 @@ mod loader_tests {
             .unwrap();
         assert!(ok, "button XML attrs + textures landed");
 
-        // The checked CheckButton draws its check mark; the idle Button draws only its normal.
         s.resolve();
         let texs: Vec<String> = s
             .extract()
@@ -1320,16 +1173,12 @@ mod loader_tests {
         assert!(!texs.contains(&"Interface\\B-Hi".into()));
         assert!(texs.contains(&"Interface\\CB-Check".into()));
 
-        // A physical click fires the XML OnClick.
         s.mouse_button(30.0, 10.0, "LeftButton", true);
         s.mouse_button(30.0, 10.0, "LeftButton", false);
         assert!(s.eval::<bool>("return xml_clicked == true").unwrap());
         assert!(s.errors().is_empty(), "{:?}", s.errors());
     }
 
-    /// A state texture's own `<Size>` + `<Anchors>` scope it to less than its button (the merchant
-    /// row's icon-scoped highlight): hovering the 100px-wide button, the highlight quad renders at
-    /// the anchored 20px square, not stretched over the button.
     #[test]
     fn button_state_texture_takes_size_and_anchors() {
         let mut s = UiScript::new().unwrap();
@@ -1353,8 +1202,7 @@ mod loader_tests {
         let report = load(&s, &doc, &no_files);
         assert!(report.errors.is_empty(), "errors: {:?}", report.errors);
 
-        // Hover the button's far-right end — the highlight still sits at the anchored TOPLEFT.
-        // (Resolve first: hit-testing reads the resolved-rect cache.)
+        // Resolve first: hit-testing reads the resolved-rect cache.
         s.resolve();
         s.mouse_move(90.0, 15.0);
         s.resolve();
@@ -1375,9 +1223,7 @@ mod loader_tests {
         assert!(s.errors().is_empty(), "{:?}", s.errors());
     }
 
-    /// `<EditBox>` LoadXML extras (`0x779fb0`): `letters` → SetMaxLetters and the config flags land
-    /// in the widget state; a click focuses it and the `<OnTextChanged>` handler fires on a typed
-    /// char.
+    /// `<EditBox>` LoadXML extras (`0x779fb0`).
     #[test]
     fn editbox_xml_extras_apply() {
         let mut s = UiScript::new().unwrap();
@@ -1400,7 +1246,6 @@ mod loader_tests {
         let report = load(&s, &doc, &no_files);
         assert!(report.errors.is_empty(), "errors: {:?}", report.errors);
 
-        // letters=5 landed; numeric abort rejects a non-digit insert wholesale.
         assert_eq!(s.eval::<i64>("return XmlEdit:GetNumLetters()").unwrap(), 0);
         s.run(r#"XmlEdit:Insert("12x")"#).unwrap(); // numeric: aborts
         s.run(r#"XmlEdit:Insert("123456")"#).unwrap(); // digits, capped at 5
@@ -1409,8 +1254,7 @@ mod loader_tests {
             "12345"
         );
 
-        // A click focuses the box (mouse-enabled by construction); a typed char marks it changed,
-        // and the drain on the next tick is what actually fires OnTextChanged (decision 1831).
+        // A typed char marks the box changed; `OnTextChanged` fires on the next tick's drain.
         s.resolve();
         s.mouse_button(50.0, 10.0, "LeftButton", true);
         s.mouse_button(50.0, 10.0, "LeftButton", false);
@@ -1422,15 +1266,8 @@ mod loader_tests {
         assert!(s.errors().is_empty(), "{:?}", s.errors());
     }
 
-    /// **`autoFocus="false"` is an opt-OUT, and the only reason the attribute is ever written.**
-    ///
-    /// The ctor leaves `flags = 1` — autoFocus ON — so every one of the ten places the shipped
-    /// 1.12.1 chain names the attribute names it to turn the flag *off* (MailFrame ×3,
-    /// MoneyInputFrame ×3, FriendsFrame ×3, AddonList ×1). The flag loop used to call the setter
-    /// only when an attribute parsed as `true`, which made all ten a no-op: harmless while our own
-    /// default was off, and exactly backwards once it matches the client's (decision 1686).
-    ///
-    /// Both directions asserted, because a presence-blind reader passes the `true` half.
+    /// The EditBox ctor leaves autoFocus on (`flags = 1`), so the stock UI writes the attribute
+    /// only as `autoFocus="false"`: ten times across FrameXML and GlueXML.
     #[test]
     fn an_editbox_flag_written_false_in_xml_turns_the_flag_off() {
         let s = UiScript::new().unwrap();
@@ -1444,8 +1281,7 @@ mod loader_tests {
         let report = load(&s, &doc, &no_files);
         assert!(report.errors.is_empty(), "errors: {:?}", report.errors);
 
-        // The box is hidden first so the Show() is a real transition; an autoFocus box takes the
-        // keyboard on show, which is the observable the flag actually drives.
+        // Hidden first so `Show()` is a real transition: an autoFocus box takes focus on show.
         for (name, want) in [("OptOut", false), ("OptIn", true), ("Silent", true)] {
             s.run(&format!(
                 "{name}:Hide(); {name}:ClearFocus(); {name}:Show()"
@@ -1461,10 +1297,9 @@ mod loader_tests {
         assert!(s.errors().is_empty(), "{:?}", s.errors());
     }
 
-    // ── TexCoords + Font objects (decision 0084 engine slice) ───────────────────────────────────
+    // ── TexCoords and font objects ──────────────────────────────────────────────────────────────
 
-    /// `<TexCoords left right top bottom>` on a `<Texture>` parses into the region's UV rect and
-    /// surfaces on the extracted quad as `[left, right, top, bottom]`.
+    /// The extracted quad carries the UV rect as `[left, right, top, bottom]`.
     #[test]
     fn texcoords_parse_to_uv_on_extracted_quad() {
         let mut s = UiScript::new().unwrap();
@@ -1501,8 +1336,6 @@ mod loader_tests {
         );
     }
 
-    /// A `<Font>` `inherits=` chain resolves height + color through two levels: the leaf inherits its
-    /// face + one value from the root and overrides another mid-chain (last-wins merge).
     #[test]
     fn font_inherits_chain_resolves_height_and_color_two_levels() {
         let s = UiScript::new().unwrap();
@@ -1528,15 +1361,13 @@ mod loader_tests {
         assert_eq!(base.height, Some(12.0));
         assert_eq!(base.color, Some([1.0, 0.82, 0.0, 1.0]));
 
-        // Leaf: face inherited from Base (through Mid), color from Mid (white), height overridden (10).
+        // Leaf: Base's face through Mid, Mid's white, its own height of 10.
         let leaf = s.font_object("Leaf").expect("Leaf registered");
         assert_eq!(leaf.font.as_deref(), Some("Fonts\\FRIZQT__.TTF"));
         assert_eq!(leaf.height, Some(10.0));
         assert_eq!(leaf.color, Some([1.0, 1.0, 1.0, 1.0]));
     }
 
-    /// A `<FontString inherits="GameFontNormalSmall">` reports the *smaller* resolved height (and the
-    /// inherited face + color) on the extracted quad — the per-FontString size the renderer bakes at.
     #[test]
     fn fontstring_inherits_reports_smaller_resolved_height() {
         let mut s = UiScript::new().unwrap();
@@ -1582,7 +1413,6 @@ mod loader_tests {
             "the *Small font object resolves to the smaller height"
         );
 
-        // The inherited face + color also flow through.
         let small = s
             .extract()
             .into_iter()
@@ -1595,8 +1425,6 @@ mod loader_tests {
         ));
     }
 
-    /// An explicit `<Color>` on a FontString overrides its font object's color; an `inherits=` naming
-    /// no registered font object is a warn-once gap, not a dropped region.
     #[test]
     fn fontstring_color_overrides_object_and_unknown_inherits_warns() {
         let mut s = UiScript::new().unwrap();
@@ -1627,7 +1455,7 @@ mod loader_tests {
             report.warnings
         );
         s.resolve();
-        // A's explicit <Color> wins over GameFontNormal's gold; its height still comes from the object.
+        // A's own <Color> wins over the object's gold; its height still comes from the object.
         let a = s
             .extract()
             .into_iter()
@@ -1638,19 +1466,14 @@ mod loader_tests {
             QuadContent::Text { color: Some(c), font_height: Some(h), .. }
                 if *c == [0.1, 0.2, 0.3, 1.0] && *h == 12.0
         ));
-        // B still materialized (the unknown inherits didn't drop it).
         assert!(s
             .extract()
             .into_iter()
             .any(|q| matches!(&q.content, QuadContent::Text { text: Some(t), .. } if t == "B")));
     }
 
-    /// The chat edit box's shape: an EditBox with BOTH a `<Layers>` FontString (the "Say:" header)
-    /// and the special direct-child `<FontString>` (the engine's text-font slot). The box must
-    /// adopt the SPECIAL one as its text region — the engine ASSIGNS that slot at LoadXML, it
-    /// never searches. (The old find-first adoption grabbed the header: typing then overwrote
-    /// "Say:", and the `<TextInsets>` re-anchor clobbered the header's LEFT anchor into a
-    /// full-width rect — the centered-header + invisible-typing chat bug.)
+    /// The chat edit box's shape. The engine assigns the text slot from the direct-child
+    /// `<FontString>` at LoadXML; it never searches the regions, so the header stays its own.
     #[test]
     fn editbox_adopts_special_fontstring_not_a_layers_header() {
         let mut s = UiScript::new().unwrap();
@@ -1681,13 +1504,11 @@ mod loader_tests {
         let report = load(&s, &doc, &no_files);
         assert!(report.errors.is_empty(), "errors: {:?}", report.errors);
 
-        // Type into the focused box.
         s.run("EB:SetFocus()").unwrap();
         assert!(s.char_input("h"));
         assert!(s.char_input("i"));
 
-        // Resolve; answer every fontstring measure with a stand-in extent (30×12), resolve again
-        // (the round-trip's second solve).
+        // Answer every text measure with a stand-in 30×12, then solve again.
         s.resolve();
         let answers: Vec<(u32, f32, f32, u64)> = s
             .fontstrings_needing_measure()
@@ -1698,8 +1519,6 @@ mod loader_tests {
         s.resolve();
 
         let quads = s.extract();
-        // The header still reads "Say:" — typing lands in the box's own text region, never the
-        // header. Both strings render.
         let header = quads
             .iter()
             .find(|q| matches!(&q.content, QuadContent::Text { text: Some(t), .. } if t == "Say:"))
@@ -1709,8 +1528,7 @@ mod loader_tests {
             .find(|q| matches!(&q.content, QuadContent::Text { text: Some(t), .. } if t == "hi"))
             .expect("the typed text renders in the box's text region");
 
-        // Header rect: its own LEFT+13 anchor + the measured 30×12 extent (left-flush against the
-        // box's left edge at x=100, v-centered on the 100..132 box) — NOT the insets rect.
+        // The header: its own LEFT+13 anchor and the 30×12 extent, centred on the 100..132 box.
         assert_eq!(
             header.rect,
             Some(crate::layout::Rect::new(110.0, 113.0, 122.0, 143.0)),
@@ -1724,11 +1542,7 @@ mod loader_tests {
         );
     }
 
-    /// `<TitleRegion setAllPoints="true"/>` builds the frame's drag handle over its whole rect —
-    /// the stock `TutorialFrame.xml`'s (1976): a press inside it moves the frame with the cursor,
-    /// exactly as `frame:CreateTitleRegion():SetAllPoints()` from Lua does
-    /// (`script::tests::movable::a_title_region_drag_swallows_the_press_and_ends_on_release`);
-    /// the same frame without the element does not move.
+    /// Stock `TutorialFrame.xml:15`; drags like `CreateTitleRegion():SetAllPoints()` from Lua.
     #[test]
     fn title_region_element_builds_the_drag_handle_over_the_frame() {
         let mut s = UiScript::new().unwrap();
@@ -1794,9 +1608,7 @@ mod loader_tests {
         );
     }
 
-    /// `<HitRectInsets>` reaches SetHitRectInsets, and the inset band stops capturing the mouse
-    /// while the frame's own geometry is untouched — the ref micro-button shape (a 29x58 frame whose
-    /// art fills only the lower ~40, `top="18"`).
+    /// The stock micro-button: 29x58, `top="18"` insets (`MainMenuBarMicroButtons.xml:9`).
     #[test]
     fn hit_rect_insets_element_shrinks_the_mouse_rect() {
         let mut s = UiScript::new().unwrap();
@@ -1818,7 +1630,6 @@ mod loader_tests {
             .eval::<(f64, f64, f64, f64)>("return Micro:GetHitRectInsets()")
             .unwrap();
         assert_eq!((l, r, t, b), (0.0, 0.0, 18.0, 0.0));
-        // Geometry untouched: still a 58-tall button.
         assert_eq!(s.eval::<f64>("return Micro:GetHeight()").unwrap(), 58.0);
         // A button is mouse-enabled by construction, so the hit test is live.
         assert!(
@@ -1828,13 +1639,9 @@ mod loader_tests {
         assert!(s.hit_test(14.0, 20.0).is_some(), "the art band still hits");
     }
 
-    /// **The `<Scripts>` walker auto-enables the mouse kind when it attaches a mouse handler**
-    /// (`0x769ef0` → `0x76af00(2,-1)` per handler name) — the reference's GameTimeFrame declares
-    /// `<OnEnter>`/`<OnLeave>` and no
-    /// `enableMouse`, yet its tooltip hovers in the real client. The kind-2 name set is exactly
-    /// {OnEnter, OnLeave, OnMouseDown, OnMouseUp, OnDragStart}: `OnDragStop`/`OnReceiveDrag` are
-    /// NOT in it, and the law is XML-load-time only — the Lua SetScript binding (`0x7748d0`)
-    /// never auto-enables (verified negative there).
+    /// The `<Scripts>` walker enables the mouse for `OnEnter`, `OnLeave`, `OnMouseDown`,
+    /// `OnMouseUp` and `OnDragStart` (`0x769ef0` calls `0x76af00(2,-1)`), which is how the stock
+    /// `GameTimeFrame` hovers; the Lua `SetScript` (`0x7748d0`) never does.
     #[test]
     fn scripts_block_mouse_handlers_auto_enable_mouse() {
         let s = UiScript::new().unwrap();
@@ -1859,7 +1666,6 @@ mod loader_tests {
                 .unwrap(),
             "OnDragStop is outside the kind-2 name set"
         );
-        // Runtime SetScript never auto-enables — the law is the XML walker's, not SetScript's.
         s.run("rt = CreateFrame('Frame', 'Rt'); rt:SetScript('OnEnter', function() end)")
             .unwrap();
         assert!(
@@ -1868,26 +1674,9 @@ mod loader_tests {
         );
     }
 
-    /// **`<NormalText>` is the Button's label under its second name** — the spelling the reference
-    /// FrameXML never writes and a third-party template reaches for constantly.
-    ///
-    /// `CSimpleButton::LoadXML 0x7788c0` gives this tag strictly more than `<ButtonText>` does: it
-    /// constructs the label `CSimpleFontString` (`0x778b6c call 0x770d30`), clears its
-    /// `ownsFontAttrs` (`0x778b7b`, the one site image-wide that clears it) so its own `LoadXML`
-    /// skips the whole font-attribute surface, and feeds the SAME node to the button's persistent
-    /// Normal-state `CSimpleFont` at `+0x33c` (`0x778ba9`/`0x778baf call 0x783c30`). One owner per
-    /// attribute: the label pass reads the element's name and geometry, the state-font pass reads
-    /// its `inherits=`, and neither reads the other's.
-    ///
-    /// **Why this could sit broken indefinitely.** The reference writes `<ButtonText>` 31 times and
-    /// `<NormalText>` never, so our own FrameXML could not notice the tag was unhandled — and an
-    /// unhandled child element is silent: the button loads, paints, and simply has no label and no
-    /// global. KLHThreatMeter's column-header template is exactly this shape, and the addon died at
-    /// `PLAYER_LOGIN` indexing the `nil` global, six frames deep, naming nothing about XML.
-    ///
-    /// The document is that template, reduced: a virtual `Button` carrying a named `<NormalText>`,
-    /// reached through `inherits=` (never directly), so this covers the template path the addon
-    /// actually takes.
+    /// `CSimpleButton::LoadXML 0x7788c0` builds the label from `<NormalText>` (`0x778b6c`), clears
+    /// its `ownsFontAttrs` (`0x778b7b`) and feeds the node to the Normal-state font (`0x783c30`,
+    /// at `0x778baf`): the label takes the name and geometry, the state font the `inherits=`.
     #[test]
     fn a_button_normal_text_is_the_label_names_it_and_fonts_it() {
         let mut s = UiScript::new().unwrap();
@@ -1919,16 +1708,13 @@ mod loader_tests {
         let report = load(&s, &doc, &no_files);
         assert!(report.errors.is_empty(), "{:?}", report.errors);
 
-        // 1 · THE GLOBAL. `$parent` resolved against the instantiated button and published in `_G`
-        // — this single read is the one KLHThreatMeter died on.
+        // 1 · The global, `$parent` resolved against the instance.
         assert!(
             s.eval::<bool>("return KtmSelfHeaderNameText ~= nil")
                 .unwrap(),
             "a named <NormalText> must publish its global"
         );
-        // 2 · ...and it is the BUTTON'S label, not a loose FontString that merely shares the name.
-        // Naming a region and publishing a global are two different things (the `<ButtonText>` path
-        // learned that the expensive way), so both directions are asserted.
+        // 2 · It is the button's label, not a loose FontString with the same name.
         assert_eq!(
             s.eval::<String>("return KtmSelfHeaderNameText:GetName()")
                 .unwrap(),
@@ -1940,16 +1726,14 @@ mod loader_tests {
             "KtmSelfHeaderNameText",
             "the <NormalText> region must BE the button's label"
         );
-        // 3 · The element's own geometry landed on the label — the label pass's half.
+        // 3 · The element's geometry landed on the label.
         assert_eq!(
             s.eval::<f64>("return KtmSelfHeaderNameText:GetWidth()")
                 .unwrap(),
             70.0
         );
-        // 4 · ...and its `inherits=` landed on the button's NORMAL-STATE font, which is the half a
-        // plain `<ButtonText>` alias would have missed. Read off the painted quad rather than a
-        // getter: the state font is applied at extract, so what is on screen is the only reading
-        // that proves the link is live.
+        // 4 · Its `inherits=` reached the Normal-state font, read off the painted quad because the
+        // state font applies at extract.
         s.resolve();
         let label = s
             .extract()
@@ -1970,40 +1754,11 @@ mod loader_tests {
         );
     }
 
-    /// **The two spellings of a Button's label are two different legs, and only `<NormalText>` is
-    /// disowned of its own font attributes — so its `justifyH` never reaches the label and the
-    /// implicit anchor stays CENTER, while a `<ButtonText>`'s does and still seats LEFT.**
-    ///
-    /// `CSimpleButton::LoadXML 0x7788c0`'s child chain routes them apart:
-    /// `<ButtonText>` (tag `0x8799f0`, compared `0x7789c1`) goes to `0x7789d0 call 0x6f2780`, the
-    /// ordinary `<FontString>` region builder the `<Layers>` walker uses, which never writes
-    /// `+0x12c`; `<NormalText>` (tag `0x879978`, `0x778b43`) goes to the inline build
-    /// `[0x778b4c, 0x778bb6)` carrying `0x778b7b mov byte [edi+0x12c],0` — the one site image-wide
-    /// that clears the gate. Cleared, gate B (`0x7710d3 → je 0x771468`) makes the label's own
-    /// `CSimpleFontString::LoadXML 0x770f40` skip `0x7710e1`–`0x771467` wholesale: `font=`,
-    /// `<FontHeight>`, `outline=`, `monochrome=`, the file load, `spacing=`, **`justifyV=`,
-    /// `justifyH=`**, `<Color>` and `<Shadow>`. That node is fed instead to the button's
-    /// Normal-state `CSimpleFont` at `+0x33c` (`0x778ba9`/`0x778baf call 0x783c30`).
-    ///
-    /// So the creation post-step `0x771480` reads the `<NormalText>` label's **untouched ctor
-    /// default** `0x212` = CENTER|MIDDLE (`0x770dd3`) and seats a single CENTER→CENTER anchor
-    /// (point 4, `0x7714dc`/`0x7714e4`). The authored `justifyH="LEFT"` still reaches the *paint*
-    /// and `GetJustifyH()` — `0x783c30`'s tail notify writes the resolved word into the label's own
-    /// `+0x120` (`0x784111` → `0x784180` → `0x773530` → `0x770800` at `0x770876`) — but that runs
-    /// downstream of the anchor, and a FontString pinned at one point is exactly as wide as its
-    /// text, so a left justify inside it has nothing to move.
-    ///
-    /// The live case is Gatherer 1.0.0's minimap quick-menu, transcribed here: every row is a
-    /// `GathererUI_PopupButtonTemplate`, all rows are `SetWidth` to one common width and stacked
-    /// TOP-to-BOTTOM so they share a centreline, and the template's only alignment statement is
-    /// `<NormalText inherits=… justifyH="LEFT"/>`. Applying that word to the label seated all
-    /// seven rows LEFT→LEFT and the menu read as a left-aligned list against the reference's
-    /// centred one.
-    ///
-    /// Two controls, and the second is why this test carries both spellings: an ordinary
-    /// `<Layers>` `<FontString justifyH="LEFT">` still seats LEFT
-    /// (`anchorless_fontstring_seats_at_its_justify_point` above), and so does a
-    /// `<ButtonText justifyH="LEFT"/>` — the gate is the `<NormalText>` leg's alone.
+    /// Only the `<NormalText>` leg clears the label's `+0x12c` gate (`0x778b7b`), so the label's
+    /// `LoadXML 0x770f40` skips its font attributes, `justifyH` among them (`0x7710d3`), and
+    /// `0x771480` seats the ctor's CENTER (`0x212`, `0x770dd3`). `<ButtonText>` goes through the
+    /// ordinary FontString builder (`0x6f2780`) and seats LEFT. The justify still reaches the
+    /// paint and `GetJustifyH()` through the state font (`0x783c30`), after the anchor is set.
     #[test]
     fn a_button_label_element_does_not_own_its_justify() {
         let mut s = UiScript::new().unwrap();
@@ -2042,7 +1797,7 @@ mod loader_tests {
         let report = load(&s, &doc, &no_files);
         assert!(report.errors.is_empty(), "{:?}", report.errors);
 
-        // 1 · The anchor — the whole mechanism, read straight off the label.
+        // 1 · The label's anchor.
         let (point, rel_point, x, y) = s
             .eval::<(String, String, f64, f64)>(
                 "local p, rel, rp, x, y = GathererUI_PopupButton1:GetFontString():GetPoint(1) \
@@ -2055,8 +1810,7 @@ mod loader_tests {
             "<NormalText>'s justifyH is disowned, so 0x771480 seats the ctor's CENTER"
         );
 
-        // 2 · ...and the authored word still reaches the label's PAINT and its getter, through the
-        // Normal-state font's link. Only the anchor was ever the reference's answer here.
+        // 2 · The justify still reaches the label's getter through the state font.
         assert_eq!(
             s.eval::<String>("return GathererUI_PopupButton1:GetFontString():GetJustifyH()")
                 .unwrap(),
@@ -2064,9 +1818,7 @@ mod loader_tests {
             "the state font's justify still reaches the label"
         );
 
-        // 3 · The CONTROL, and the half the byte round corrected: `<ButtonText>` is built by the
-        // ordinary FontString builder (`0x6f2780`), which never clears `+0x12c`, so its own
-        // justifyH lands on the label and the same post-step seats it LEFT.
+        // 3 · The control: `<ButtonText>` keeps its justify, so it seats LEFT.
         let (point, rel_point) = s
             .eval::<(String, String)>(
                 "local p, rel, rp = OwnLabelButton:GetFontString():GetPoint(1) return p, rp",
@@ -2078,9 +1830,8 @@ mod loader_tests {
             "<ButtonText> owns its font attributes — the gate is the <NormalText> leg's alone"
         );
 
-        // 4 · The visible consequence, in resolved coordinates. The popup is [0,0]..[120,60] and
-        // the rows are 64 wide, centred on x=60 → [28,92]. A 40-wide label centred in that is
-        // [40,80]; seated LEFT it is [28,68] — the left edge every Gatherer row shared before this.
+        // 4 · Rows 64 wide centred on x=60 span [28,92]: a 40-wide label centred is [40,80],
+        // seated LEFT [28,68].
         s.run(
             "GathererUI_PopupButton1:GetFontString():SetWidth(40) \
              OwnLabelButton:GetFontString():SetWidth(40)",
@@ -2106,17 +1857,13 @@ mod loader_tests {
         );
     }
 
-    /// **`text=` is a GLOBAL-STRING LOOKUP, not a literal** (`FrameScript_GetText 0x703bf0`). Every
-    /// arm of [`Loader::resolve_text`] in one document:
-    /// a `<Button text=>`, a `<ButtonText text=>` and a `<FontString text=>` all resolve through
-    /// the VM's globals; a value with no matching global falls back to the LITERAL (benilla's own
-    /// divergence, so its plain-English FrameXML keeps working); and a **key-shaped** miss warns,
-    /// which is the tripwire that "CREATE_MACROS" across a title bar never had.
+    /// `text=` resolves as a global (`FrameScript_GetText 0x703bf0`) on all three element shapes;
+    /// a miss shows the raw value, as the reference's readers do, and a key-shaped miss warns.
     #[test]
     fn a_text_attribute_resolves_through_the_global_strings() {
         let mut s = UiScript::new().unwrap();
         s.set_screen_size(800.0, 600.0);
-        // The reference boots GlobalStrings.lua before any XML; so does the app.
+        // GlobalStrings.lua runs before any XML.
         s.run(r#"DELETE = "Delete" EXIT_GAME = "Exit Game" TITLE = "The Title""#)
             .unwrap();
 
@@ -2152,17 +1899,14 @@ mod loader_tests {
         assert_eq!(
             texts,
             vec![
-                // The key's VALUE, on all three element shapes…
                 "The Title",
-                // …a non-key literal untouched (the divergence that keeps our own XML working)…
                 "No results found.",
                 "Delete",
                 "Exit Game",
-                // …and a key-shaped MISS keeps its key on screen rather than blanking.
                 "NO_SUCH_KEY",
             ]
         );
-        // Exactly one warning, and it names the miss — the plain-English literal must not warn.
+        // Only the key-shaped miss warns.
         assert_eq!(
             report
                 .warnings
@@ -2176,8 +1920,6 @@ mod loader_tests {
         assert!(report.warnings.iter().any(|w| w.contains("NO_SUCH_KEY")));
     }
 
-    /// The key SHAPE test itself: `SCREAMING_SNAKE`, two characters or more. The floor is what
-    /// keeps a close button's `text="X"` from being reported as a missing string.
     #[test]
     fn key_shape_is_screaming_snake_of_two_or_more() {
         for yes in ["DELETE", "EXIT_GAME", "CHARACTER_POINTS1_COLON", "AB", "A1"] {
@@ -2188,15 +1930,11 @@ mod loader_tests {
         }
     }
 
-    // ── <SimpleHTML> (the markup widget's XML element) ───────────────────────────────────────
+    // ── <SimpleHTML> ─────────────────────────────────────────────────────────────────────────
 
-    /// **`<SimpleHTML>`'s `<FontString>` child is a font DECLARATION, not a region** — the shape
-    /// stock `ItemTextFrame.xml` uses, and the whole reason its `<H1>` renders at the `<P>` size.
-    ///
-    /// Four claims in one document: the element materializes as a real `SimpleHTML` frame with its
-    /// `<Size>`/`<Anchors>`/`<Scripts>` applied like any frame; the direct-child `<FontString
-    /// inherits=>` lands on `elementFont[0]` rather than creating a FontString region; a
-    /// `<FontStringHeader1>` lands on `elementFont[1]`; and `hyperlinkFormat=` reaches `+0x360`.
+    /// A direct-child `<FontString>` declares `elementFont[0]` and `<FontStringHeader1>`
+    /// `elementFont[1]`, neither a region, and `hyperlinkFormat=` lands at `+0x360`; stock
+    /// `ItemTextFrame.xml:214` uses the first.
     #[test]
     fn simplehtml_xml_declares_element_fonts_not_regions() {
         let mut s = UiScript::new().unwrap();
@@ -2232,7 +1970,6 @@ mod loader_tests {
                 .unwrap(),
             "|H%s|h[%s]|h"
         );
-        // The two declarations landed on their own elements…
         assert_eq!(
             s.eval::<(String, f32)>("local p, h = PageText:GetFont(); return p, h")
                 .unwrap(),
@@ -2243,8 +1980,7 @@ mod loader_tests {
                 .unwrap(),
             ("Fonts\\SKURRI.TTF".to_string(), 24.0)
         );
-        // …and NEITHER became a region. A `<FontString>` handled by the generic special-fontstring
-        // pass would leave an unanchored, textless string on the frame here.
+        // Neither declaration became a region.
         let regions = {
             let lua = s.lua();
             let model = lua
@@ -2255,7 +1991,7 @@ mod loader_tests {
         };
         assert_eq!(regions, 0, "the font declarations created no regions");
 
-        // Now drive it: three blocks, the H1 in its OWN declared face, at the frame's width.
+        // Two blocks, the H1 in its declared face, at the frame's width.
         s.run(
             r#"PageText:SetText("<HTML><BODY><H1>Title</H1><P align=\"center\">Body</P></BODY></HTML>")"#,
         )
@@ -2292,17 +2028,8 @@ mod loader_tests {
         assert!(s.errors().is_empty(), "{:?}", s.errors());
     }
 
-    /// A state-texture element with **no `file=`, no `<Color>` and no `name=`** still builds its
-    /// region: `<NormalTexture/>` is the reference's own form on `SpellBookSkillLineTabTemplate`
-    /// (ref SpellBookFrame.xml l.36), and the real client creates from the ELEMENT, not from any
-    /// attribute on it — `Button::LoadXML 0x7788c0` routes all four `<...Texture>` children through
-    /// the same texture adder the `<Layers>` walker uses (`0x6f26f0`), each followed only by the slot
-    /// store, which does no geometry.
-    ///
-    /// The report is pfUI's spellbook skin, which takes `SpellBookSkillLineTab<i>:GetNormalTexture()`
-    /// and immediately `:SetTexCoord()`s it; the corpus carries 38 bare `<DisabledTexture />` besides.
-    /// Before this, the loader materialized only on `file=`/`<Color>`/`name=`, so the getter answered
-    /// nil where the real client answers a live blank texture.
+    /// `CSimpleButton::LoadXML 0x7788c0` builds any `<...Texture>` child through the `<Layers>`
+    /// texture adder (`0x6f26f0`); `SpellBookFrame.xml:36` writes a bare `<NormalTexture/>`.
     #[test]
     fn a_bare_state_texture_element_still_builds_its_region() {
         let mut s = UiScript::new().unwrap();
@@ -2330,8 +2057,7 @@ mod loader_tests {
                 .unwrap(),
             "a bare <DisabledTexture /> builds its region"
         );
-        // Created, not painted: the region is live enough to take SetTexCoord (pfUI's next call) and
-        // still carries no art of its own.
+        // Live enough for `SetTexCoord`, with no art of its own.
         s.run("BareBtn:GetNormalTexture():SetTexCoord(0.07, 0.93, 0.07, 0.93)")
             .unwrap();
         assert!(
@@ -2351,9 +2077,6 @@ mod layer_blend_tests {
         None
     }
 
-    /// `alphaMode="ADD"` on a `<Layers>` texture reaches the extracted quad's blend flag — the
-    /// state-texture path always applied it, the layer path silently dropped it (the quest log's
-    /// selection glow rendered as an opaque gray bar — the 0109 look fix).
     #[test]
     fn layers_texture_alpha_mode_add_reaches_the_quad() {
         let s = UiScript::new().unwrap();
@@ -2401,10 +2124,7 @@ mod region_template_tests {
         None
     }
 
-    /// A `<Texture inherits="…">` layer region splices its virtual template — file, `<Size>`,
-    /// `<Anchors>` — with the instance's own nodes winning (the talent branch/arrow art pool's
-    /// shape; before this, the template was silently ignored and every pooled texture sat at
-    /// 0×0 with no file: shown, positioned by the runtime SetPoint, and invisible).
+    /// The instance's own nodes win over the template's.
     #[test]
     fn layers_texture_inherits_a_virtual_texture_template() {
         let s = UiScript::new().unwrap();
@@ -2436,7 +2156,6 @@ mod region_template_tests {
         );
         let mut s = s;
         s.set_screen_size(800.0, 600.0);
-        // The template's size/file landed; the instance's own <Size> wins over the template's.
         assert_eq!(
             s.eval::<(f64, f64)>("return Branch1:GetWidth(), Branch1:GetHeight()")
                 .unwrap(),
@@ -2464,8 +2183,6 @@ mod region_template_tests {
         );
     }
 
-    /// A `<FontString inherits="GameFontNormal">` names a FONT OBJECT, not an element template —
-    /// the region-template gate must pass it through untouched (no "unknown template" warning).
     #[test]
     fn fontstring_font_object_inherits_stays_out_of_the_template_path() {
         let s = UiScript::new().unwrap();
@@ -2492,11 +2209,6 @@ mod region_template_tests {
             report.warnings
         );
         assert_eq!(s.eval::<String>("return Label:GetText()").unwrap(), "hello");
-        // …and the font it inherited is READABLE BACK, which is the half this test did not ask.
-        // `EQL3_Options.lua:1086` is the corpus line that needs it: it reads the tracker line's
-        // font with `t1, _, t2 = EQL3_QuestWatchLine1:GetFont()` and feeds `t1` straight into
-        // `temp:SetFont(t1, height, t2)` — so a nil path there is not a cosmetic gap, it is our own
-        // faithful `Usage: <FontString>:SetFont(...)` raise firing on our own nil.
         assert_eq!(
             s.eval::<(String, f32)>("local f, h = Label:GetFont() return f, h")
                 .unwrap(),
@@ -2505,12 +2217,7 @@ mod region_template_tests {
         );
     }
 
-    /// **A font-object name resolves case-INSENSITIVELY**, because the client's font registry
-    /// compares its keys with `SStrCmpI` (`0x783870`/`0x7838c7`).
-    ///
-    /// `Recap/RecapOptions.xml:32` inherits `GameFontHighLightSmall`; the shipped font is
-    /// `GameFontHighlightSmall`, one letter's case apart. On the real client that resolves, and it
-    /// used to be a warn-once gap here — a NARROWING fix, like the unit-token fold (1247).
+    /// The reference's font registry compares names with `SStrCmpI` (`0x783870`/`0x7838c7`).
     #[test]
     fn a_font_object_inherits_resolves_whatever_its_case() {
         let s = UiScript::new().unwrap();
@@ -2544,11 +2251,7 @@ mod region_template_tests {
         );
     }
 
-    /// **EQL3's actual shape: FontString -> virtual FontString TEMPLATE -> Font object.** One hop
-    /// works (above); this is the two-hop chain every "define a line template once, stamp it N
-    /// times" addon writes, and `EQL3_Tracker.xml:6/32` is the corpus instance —
-    /// `EQL3_QuestWatch_FontTemplate` inherits `GameFontHighlight`, and each
-    /// `EQL3_QuestWatchLine<i>` inherits the template.
+    /// Two hops: a FontString inherits a virtual FontString template, which inherits a font object.
     #[test]
     fn a_fontstring_template_carries_the_font_object_it_inherits() {
         let s = UiScript::new().unwrap();
@@ -2581,7 +2284,7 @@ mod region_template_tests {
     }
 }
 
-/// Chunk naming — which FILE and which LINE a `<Script>` raise reports (decision 1217).
+/// Chunk naming: the file and line a `<Script>` raise reports.
 mod chunk_name_tests {
     use crate::framexml;
     use crate::loader::*;
@@ -2595,21 +2298,11 @@ mod chunk_name_tests {
         framexml::parse(text).expect("valid FrameXML")
     }
 
-    /// **A raise inside a `<Script>` block names the file it came from, and the file's own line.**
-    ///
-    /// Both halves are load-bearing and both were wrong. `Loader::run` loaded every chunk with no
-    /// name, and mlua's `load` is `#[track_caller]` — so the chunk was named after the *Rust* line
-    /// that ran it, and a corpus read-back of 70 failures had 26 rows saying
-    /// `crates/benilla-ui/src/loader/mod.rs:327` where the addon's file belonged (decision 1217).
-    ///
-    /// Naming it is only half. A Lua chunk starts at line 1, so an inline block 40 lines down a
-    /// file would report `File.xml:3` for its third line — a lie you can go and check, which is
-    /// strictly worse than the Rust path that was at least obviously not yours. The chunk is padded
-    /// to the block's own offset, so the number is the number you scroll to.
+    /// An inline block is padded to its line in the file, so a raise reports the file's line.
     #[test]
     fn a_script_raise_names_its_own_file_and_line() {
         let s = UiScript::new().unwrap();
-        // `error()` with no level prefixes "chunkname:line:" — exactly what a real raise carries.
+        // `error()` with no level prefixes `chunkname:line:`, as a real raise does.
         let doc = parse(
             "<Ui>\n\
              <Frame name=\"Pad\"/>\n\
@@ -2621,24 +2314,18 @@ mod chunk_name_tests {
         );
         let report = load_in(&s, &doc, "Bagnon/src/main.xml", &no_files);
         let err = report.errors.join("\n");
-        // The file, in the shape an addon's own `debugstack()` matches (backslashes, no `@`).
-        // The `:<Scripts>` suffix and the `[string "…"]` wrapper are the reference's own
-        // (`"%s:<Scripts>"` `0x871074`, `luaO_chunkid`'s third branch), not decoration of ours.
+        // Backslashes, and the reference's `"%s:<Scripts>"` form (`0x871074`).
         assert!(
             err.contains("Bagnon\\src\\main.xml:"),
             "the raise must name the document, got: {err}"
         );
-        // Line 5 of the literal above is `error("boom")` — the body starts on line 4 and the
-        // padding carries it there. Without the pad this reads `:2:`.
+        // `error("boom")` is line 5 of the literal; unpadded it would read `:2:`.
         assert!(
             err.contains("main.xml:<Scripts>\"]:5:"),
             "the line must be the FILE's line, not the block's, got: {err}"
         );
     }
 
-    /// The same, one level down: an `<Include>`d document's inline script names **its own** file,
-    /// not the includer's. The path is saved and restored around the recursion exactly as the
-    /// directory used to be, so depth-1 and depth-5 each report themselves.
     #[test]
     fn an_included_documents_script_names_the_included_file() {
         let s = UiScript::new().unwrap();
@@ -2659,11 +2346,8 @@ mod chunk_name_tests {
         );
     }
 
-    /// **The CDATA shape, which is the only shape our own FrameXML uses.** `<![CDATA[` sits
-    /// between the element's start and the body's first byte, so taking the line from the
-    /// *element* would be short by however much of the opening tag precedes it — and a
-    /// single-line-offset lie is the hardest kind to notice. The line comes from the text child's
-    /// own range instead, which is what this pins.
+    /// The line comes from the text child's own range, not the element's, which the `<![CDATA[`
+    /// opener would offset.
     #[test]
     fn a_cdata_script_block_reports_the_files_line() {
         let s = UiScript::new().unwrap();
@@ -2685,7 +2369,6 @@ mod chunk_name_tests {
         );
     }
 
-    /// A `<Script file=>` chunk is named after the file it loaded, not the document that named it.
     #[test]
     fn a_script_file_chunk_is_named_after_that_file() {
         let s = UiScript::new().unwrap();
@@ -2701,17 +2384,8 @@ mod chunk_name_tests {
         );
     }
 
-    /// **A captured script, called back the reference's way, still knows its frame.**
-    ///
-    /// This is *the* 1.12 hook idiom and the whole reason `GetScript` exists: an addon takes the
-    /// client's handler, installs its own, and calls the original with **no arguments**, because
-    /// the reference's contract passes the frame as the `this` global and nothing else. Our
-    /// wrapper is `function(self, ...)` and our own FrameXML is written against `self`, so before
-    /// the fallback in [`super::Loader::compile_handler`] that re-entry handed every body a nil
-    /// frame. The director met it as `bad argument #2: error converting Lua nil to table` out of
-    /// `GameTooltip:SetOwner`, from a handler that works perfectly when the engine calls it.
-    ///
-    /// Both spellings are asserted, because the fallback must not cost the engine's own call.
+    /// The 1.12 hook idiom: an addon captures a handler with `GetScript` and calls it with no
+    /// arguments, the frame passed only as `this`; `Loader::compile_handler` falls back to `this`.
     #[test]
     fn a_script_captured_and_called_with_no_arguments_still_sees_its_frame() {
         let s = UiScript::new().unwrap();
@@ -2727,12 +2401,11 @@ mod chunk_name_tests {
         let report = load_in(&s, &doc, "Test.xml", &no_files);
         assert!(report.errors.is_empty(), "{:?}", report.errors);
 
-        // The engine's own call: `self` is passed and `this` is set — the modern spelling.
+        // The engine's call passes `self` and sets `this`.
         s.run("SEEN = nil Hooked:Show()").unwrap();
         assert_eq!(s.eval::<String>("return SEEN").unwrap(), "Hooked");
 
-        // The addon's: capture the script, then call it back bare with only `this` standing in for
-        // the frame — exactly `Bagnon.lua:87`'s `bMainBag_OnEnter()`.
+        // The addon's: the captured script called bare, with only `this` set.
         s.run(
             "SEEN = nil \
              local original = Hooked:GetScript(\"OnShow\") \
@@ -2749,30 +2422,20 @@ mod chunk_name_tests {
     }
 }
 
-/// [`super::join_ref`] — the FrameXML path rule (decision 1186).
-///
-/// A reference is relative to the directory of the file containing it, `\` and `/` are the same
-/// separator, and `..` walks up. The escape case is the load-bearing one: a `..` above the root is
-/// KEPT as a leading `..` rather than clamped away, because the provider has to be able to SEE the
-/// escape to refuse it. Clamping would silently hand it a path that looks contained.
 #[test]
 fn join_ref_resolves_relative_framexml_paths() {
     use super::join_ref;
-    // Relative to the including file's own directory.
     assert_eq!(
         join_ref("Bagnon/src", "templates.xml"),
         "Bagnon/src/templates.xml"
     );
-    // Backslashes are separators, and `..` walks up — this is how a library addon is reached.
     assert_eq!(
         join_ref("Bagnon/src", "..\\..\\BagBrother\\core\\core.xml"),
         "BagBrother/core/core.xml"
     );
-    // At the root, a bare name stays bare (the builtin's flat tree).
     assert_eq!(join_ref("", "Fonts.xml"), "Fonts.xml");
-    // `.` is a no-op; redundant separators collapse.
     assert_eq!(join_ref("a/b", "./c//d.xml"), "a/b/c/d.xml");
-    // An escape above the root SURVIVES, so the provider can refuse it.
+    // An escape above the root survives, so the provider can refuse it.
     assert_eq!(join_ref("a", "../../secret"), "../secret");
     assert_eq!(join_ref("", "../secret"), "../secret");
     // A leading `/` re-roots rather than meaning the filesystem root.
diff --git a/crates/benilla-ui/src/loader/widgets.rs b/crates/benilla-ui/src/loader/widgets.rs
index 0c56904b..34c39519 100644
--- a/crates/benilla-ui/src/loader/widgets.rs
+++ b/crates/benilla-ui/src/loader/widgets.rs
@@ -9,11 +9,8 @@ use super::{
 };
 
 impl Loader<'_> {
-    /// `<StatusBar>` LoadXML extras (`0x782ef0`): `minValue`/`maxValue`
-    /// (a reversed pair is swapped — SetMinMaxValues normalizes identically), `defaultValue` →
-    /// SetValue, `orientation`, and the `<BarTexture>`/`<BarColor>` children; the element's
-    /// `drawLayer` names the bar texture's layer (widget default ARTWORK). The Slider's parallel
-    /// `<ThumbTexture>` path lives in [`Self::apply_slider`].
+    /// `<StatusBar>` (`0x782ef0`): a reversed `minValue`/`maxValue` pair is swapped, as
+    /// `SetMinMaxValues` also does; `drawLayer` is the bar texture's layer, ARTWORK by default.
     pub(super) fn apply_statusbar(&mut self, el: &Element, wrapper: &Table, dbg: &str) {
         if !el.tag.eq_ignore_ascii_case("StatusBar") {
             return;
@@ -41,12 +38,9 @@ impl Loader<'_> {
                     (file.to_string(), layer.clone()),
                     dbg,
                 );
-                // File + `<Color>` DISCARDS the colour, it does not tint — the same
-                // `CSimpleTexture::LoadXML` ordering `regions.rs`'s `<Texture>` arm cites
-                // (`0x76fe20`: the child loop runs first, then `file=` overwrites the same `+0xcc`).
-                // `<BarColor>` below is this widget's real tint.
+                // A `<Color>` beside `file=` is discarded, as on any texture (`0x76fe20`);
+                // `<BarColor>` is the bar's tint.
             } else if let Some(c) = color {
-                // No file: a solid-color bar (the SetStatusBarTexture(r,g,b,a) form).
                 self.call(
                     wrapper,
                     "SetStatusBarTexture",
@@ -64,15 +58,9 @@ impl Loader<'_> {
         }
     }
 
-    /// `<Button>`/`<CheckButton>` extras (`0x7788c0`/`0x785170` — the checkbox loader runs
-    /// the button one first, which this shared body mirrors): the four state textures, CheckButton's
-    /// two checked textures + `checked` attr, `<ButtonText text=>`, and the `text` attribute. Each
-    /// texture child takes a `file` or a `<Color>` (the same two forms as the Set*Texture methods)
-    /// plus the generic region layout — `<Size>`/`<Anchors>`/`setAllPoints` — so a state texture can
-    /// cover less than its button (the merchant row's icon-scoped highlight); `$parent` in a state
-    /// texture's anchors resolves against this button's own name, like a `<Layers>` region's.
-    /// The per-state fonts (`<NormalFont>` and kin) are modeled below — object and local justify
-    /// (decision 1996); not modeled (stated): `<PushedTextOffset>`.
+    /// `<Button>`, `<CheckButton>` and `<LootButton>` (`0x7788c0`, which `0x785170` runs first):
+    /// the label, the state textures with their own layout, `checked`, `text=` and the per-state
+    /// fonts. `$parent` in a child's anchors is this button.
     pub(super) fn apply_button(
         &mut self,
         el: &Element,
@@ -81,18 +69,8 @@ impl Loader<'_> {
         dbg: &str,
     ) {
         let is_check = el.tag.eq_ignore_ascii_case("CheckButton");
-        // **`<LootButton>` takes this leg too, and taking only two tags is what hid the loot
-        // window's hover highlight.** `CLootButton` is a `CSimpleButton` subclass that overrides
-        // six vtable slots on the primary table (dtor, the Lua lookup, the two type predicates,
-        // `GetObjectType`, and the click virtual) and exactly ONE on the geometry table — slot 1,
-        // the destructor's adjustor thunk. `LoadXML` is geometry slot 2 (`0x81c7c8[2]` for Button,
-        // `0x804594[2]` for LootButton), and those two entries are the same pointer: a
-        // `<LootButton>` element is parsed by `CSimpleButton::LoadXML 0x7788c0` *verbatim*.
-        // Stock `LootButtonTemplate` inherits `ItemButtonTemplate`, whose whole art is three state
-        // textures — so with the tag rejected here the rows lost their Quickslot border, their
-        // depress art and the `ButtonHilight-Square` that lights a row under the cursor. It is the
-        // BUTTON leg and not the check one: `CheckButton::LoadXML 0x785170` is a different slot 2
-        // that calls this one first, and nothing routes a LootButton through it.
+        // A `<LootButton>` loads exactly as a Button: its `LoadXML` slot holds `CSimpleButton`'s
+        // pointer (`0x804594[2]` = `0x81c7c8[2]`).
         if !is_check
             && !el.tag.eq_ignore_ascii_case("Button")
             && !el.tag.eq_ignore_ascii_case("LootButton")
@@ -101,12 +79,8 @@ impl Loader<'_> {
         }
         let tex = |tag: &str, method: &str, this: &mut Self| {
             for raw in children_named(el, tag) {
-                // A state texture may `inherits=` a virtual `<Texture>` — `<NormalTexture
-                // inherits="UIPanelButtonUpTexture"/>` is how the reference's whole shared button
-                // kit carries its art, and it is the ONLY form those templates use. Expanding here
-                // is the same call a `<Layers>` region gets (`expand_region`, which passes a
-                // non-template `inherits=` through untouched), and without it the reads below found
-                // no `file=`, no `<TexCoords>` and no `<Size>`: a button with no art and NO ERROR.
+                // A state texture may inherit a virtual `<Texture>`, the stock button kit's only
+                // form (`UIPanelButtonUpTexture`); it expands like a `<Layers>` region.
                 let expanded = this.expand_region(raw);
                 let t = &expanded;
                 if let Some(file) = t.attr("file") {
@@ -114,44 +88,19 @@ impl Loader<'_> {
                 } else if let Some(c) = children_named(t, "Color").next().map(color_of) {
                     this.call(wrapper, method, (c[0], c[1], c[2], c[3]), dbg);
                 } else {
-                    // A state texture with no art of its own — a NAMED one (`<NormalTexture
-                    // name="$parentIcon">` on the ref's own MacroFrameButtonTemplate, whose art
-                    // arrives later through `SetTexture`) or a BARE one (`<NormalTexture/>`, the
-                    // ref's own SpellBookSkillLineTabTemplate l.36). **The ELEMENT is what creates
-                    // the region; `file=` is not a gate.** `Button::LoadXML 0x7788c0` routes all
-                    // four `<...Texture>` children through the SAME texture adder the `<Layers>`
-                    // walker uses (`0x6f26f0` — `0x778903` <NormalTexture> tag `0x879a30`,
-                    // `0x778935` <PushedTexture>, `0x778967` <DisabledTexture>, `0x778999`
-                    // <HighlightTexture>), each followed only by the slot store (`0x778fd0`
-                    // state-texture family / `0x779110` highlight install), which does no
-                    // geometry. The adder constructs;
-                    // nothing in that path reads an attribute first.
-                    //
-                    // This arm used to require `t.name().is_some()`, so a bare element built
-                    // nothing and `GetNormalTexture()` answered nil where the real client answers a
-                    // live blank texture. pfUI's spellbook skin is the report — it takes
-                    // `SpellBookSkillLineTab<i>:GetNormalTexture()` and immediately
-                    // `:SetTexCoord()`s it — and the corpus carries 38 more bare
-                    // `<DisabledTexture />` besides.
-                    //
-                    // `""` is the live API's own blank form (`set_slot_texture`'s empty-string arm,
-                    // which runs `ensure_slot` and then clears), so this creates without painting.
+                    // No art: the element alone creates the region, as the reference sends all four
+                    // state textures through the `<Layers>` texture adder (`0x6f26f0`, from
+                    // `0x778903`); `""` creates the slot without painting it.
                     this.call(wrapper, method, String::new(), dbg);
                 }
-                // alphaMode / <Size> / <Anchors> / <TexCoords> apply to the region the setter just
-                // created — fetch it back through the matching getter and use the region methods.
                 let getter = method.replacen("Set", "Get", 1);
                 if let Ok(region) = wrapper.call_method::<Table>(getter.as_str(), ()) {
                     if let Some(mode) = t.attr("alphaMode") {
                         this.call_region(&region, "SetBlendMode", mode.to_string(), dbg);
                     }
-                    // The setter above MATERIALIZED the region with the runtime path's implicit
-                    // SetAllPoints (decision 1310) — but this is the XML path, where the real
-                    // engine routes state textures through the region adder (`0x778903`…: authored
-                    // `<Anchors>` first, the implicit step after). Reproduce that order: clear,
-                    // apply the authored layout, then re-run the conditional step — a same-point
-                    // SetPoint over a live implicit corner would otherwise leave the OTHER corner
-                    // standing (the slot law) and weld an anchored state texture to the button.
+                    // The setter gave the region the runtime path's implicit anchors, but the XML
+                    // path places the authored ones first and the implicit step after (`0x778903`):
+                    // clear, lay out, then re-run it, or a leftover implicit corner would pin it.
                     this.call_region(&region, "ClearAllPoints", (), dbg);
                     this.apply_region_layout(t, &region, self_name, dbg, FontAttrs::Own);
                     if let Err(e) = crate::script::implicit_creation_anchor_lua(this.lua, &region) {
@@ -162,16 +111,10 @@ impl Loader<'_> {
                     if let Some(tc) = tex_coords_of(t) {
                         this.call_region(&region, "SetTexCoord", tc, dbg);
                     }
-                    // Publish a NAMED state texture (`<HighlightTexture
-                    // name="$parentHighlightTexture">`) — the ref kit addresses these by global
-                    // (the tab template's own OnShow does `getglobal(name.."HighlightTexture")`),
-                    // exactly like a named `<Layers>` region or the ButtonText.
+                    // A named state texture is published both ways: the region registry for its
+                    // `GetName()`, `_G` for `getglobal` and a sibling's `relativeTo`.
                     if let Some(rname) = t.name().map(|raw| framexml::resolve_name(raw, self_name))
                     {
-                        // …and into the region-name registry, which is what a sibling's
-                        // `relativeTo` resolves through — the stock trainer row hangs its label
-                        // off `$parentHighlight`'s RIGHT, and a name that lives only in `_G`
-                        // sent that label to the button's edge instead (1957).
                         crate::script::region::publish_region_name(this.lua(), &rname, &region);
                         if let Err(e) = this.lua().globals().set(rname.clone(), region) {
                             this.report
@@ -182,69 +125,24 @@ impl Loader<'_> {
                 }
             }
         };
-        // The LABEL is published before the state textures, and the order is load-bearing: a
-        // state texture may anchor to `$parentText` (the reference's own sort-header template
-        // hangs its arrow off the label's RIGHT), and this loader resolves `relativeTo` eagerly by
-        // name at SetPoint time. Applied the other way round, every such anchor missed and fell
-        // back to the owner — 14 of them in one window, each a sort arrow sitting in the wrong
-        // place. The real client is order-free here because it resolves anchors later; we are not,
-        // so we order it ourselves rather than making each author work around it.
-        // **Both spellings of the label** (`ButtonText` | `NormalText`), in document order.
-        //
-        // `<NormalText>` is not a synonym bolted on here — it is the binary's own second name for
-        // this slot, and **it is a genuinely different leg**. `CSimpleButton::LoadXML
-        // 0x7788c0`'s 15-comparison child chain routes the two label spellings apart:
-        //
-        // - `<ButtonText>` (tag `0x8799f0`, compared `0x7789c1`) → `0x7789d0 call 0x6f2780`, the
-        //   **ordinary `<FontString>` region builder** — whose only other caller is the `<Layers>`
-        //   walker (`0x769e61`). It never writes `+0x12c`, so the ctor's `1` stands, both gates in
-        //   `0x770f40` stay open, and the element's `justifyH`/`justifyV` (and `inherits=`,
-        //   `font=`, `<Color>`, `<Shadow>`) apply to the LABEL, exactly like any other FontString.
-        // - `<NormalText>` (tag `0x879978`, compared `0x778b43`) → the inline build
-        //   `[0x778b4c, 0x778bb6)`, a hand-rolled copy of that builder carrying
-        //   `0x778b7b mov byte [edi+0x12c],0` — the ONE site image-wide that clears the gate. Its
-        //   font attributes are skipped on the label and fed to the button's persistent
-        //   Normal-state `CSimpleFont` at `+0x33c` (`0x778ba9`/`0x778baf call 0x783c30`) instead.
-        // - `<HighlightText>`/`<DisabledText>` build no region at all: pure aliases for the
-        //   Highlight/Disabled fonts (`0x778bf4`), which is why they are not in this loop.
-        //
-        // So both spellings make the label and take its geometry and name, and only `<NormalText>`
-        // hands its font attributes away — [`FontAttrs`] below is that one difference.
-        //
-        // The reference FrameXML writes only `<ButtonText>` (31 sites, 16 of them
-        // `name="$parentText"`) and never `<NormalText>`, so nothing we ship could notice the
-        // second spelling was missing. A third-party template is where it shows: KLHThreatMeter's
-        // `<Button name="KLHTM_SelfHeaderStringTemplate" virtual="true"><NormalText
-        // name="$parentText" …>` left `KLHTM_SelfFrameHeaderNameText` nil, and the addon died in
-        // its `PLAYER_LOGIN` handler on exactly that global.
+        // Both label spellings build the label, in document order: `<ButtonText>` through the
+        // ordinary FontString builder (`0x7789d0` → `0x6f2780`), `<NormalText>` through an inline
+        // copy that disowns its font attributes (`0x778b7b`). `<HighlightText>` and
+        // `<DisabledText>` build no region, only fonts (`0x778bf4`).
         for bt in children_named_any(el, &["ButtonText", "NormalText"]) {
-            // Which leg built this label decides who owns its font attributes — see the chain
-            // above. `<ButtonText>` goes through the ordinary FontString builder and keeps them;
-            // `<NormalText>` is the one the button disowns (`0x778b7b`).
             let font_attrs = if bt.tag.eq_ignore_ascii_case("NormalText") {
                 FontAttrs::Disowned
             } else {
                 FontAttrs::Own
             };
-            // Create the label slot even with no text yet (the geometry below must land on a real
-            // region; SetText is the slot's lazy constructor), then apply the element's own
-            // `<Size>`/`<Anchors>` to it — the ref anchors ButtonText all over (the quest
-            // greeting rows hang theirs at TOPLEFT+20 beside the bullet; without this every
-            // labelled Button centered its text over the whole face).
-            // `<ButtonText text=>` is a FontString's own attribute — the same global-string lookup
-            // `0x703bf0` gives every `<FontString text=>`. See `Loader::resolve_text`.
+            // `SetText` creates the label even with no text, so its layout lands on a real region;
+            // `text=` is a global-string key (`0x703bf0`).
             let label = match bt.attr("text") {
                 Some(raw) => self.resolve_text(raw, dbg),
                 None => String::new(),
             };
-            // A NAMED `<ButtonText name="$parentText">` is created as a named region and bound,
-            // rather than left to `SetText`'s lazy constructor and aliased afterwards.
-            //
-            // Publishing a Lua global is not the same thing as naming the region, and the gap was
-            // invisible until something anchored to it: `relativeTo="$parentText"` resolves through
-            // the engine's own named-region lookup, which a global alias never reaches, so every
-            // such anchor missed and fell back to the owner. `GetFontString():GetName()` also
-            // answered nil, which is wrong for any addon that asks.
+            // A named label is created as a named region, not aliased after `SetText`, so its
+            // `GetName()` answers.
             let bt_name = bt.name().map(|raw| framexml::resolve_name(raw, self_name));
             if let Some(rname) = bt_name.clone() {
                 match wrapper
@@ -259,30 +157,10 @@ impl Loader<'_> {
             }
             self.call(wrapper, "SetText", label, dbg);
             if let Ok(region) = wrapper.call_method::<Table>("GetFontString", ()) {
-                // Same clear→layout→implicit order as the state textures above (decision 1310):
-                // SetText materialized the label with the runtime path's implicit anchor; the XML
-                // path re-derives it AFTER the element's own `<Anchors>` apply, which is where
-                // both real legs run it (`0x6f27f5` for `<ButtonText>`, `0x778b96` for
-                // `<NormalText>` — two of that post-step's three call sites).
-                //
-                // **`font_attrs` is the load-bearing argument here** (decision 2100). On the
-                // `<NormalText>` leg the element's `justifyH`/`justifyV` belong to the button's
-                // per-state font, never to the label, so the post-step reads the string's
-                // untouched ctor word (`0x212` = CENTER|MIDDLE) and seats CENTER. Applying the
-                // word to the label instead seated Gatherer's whole quick-menu LEFT→LEFT against
-                // the reference's centred rows: its `GathererUI_PopupButtonTemplate` states its
-                // alignment once, as `<NormalText inherits="GameFontNormal" justifyH="LEFT"/>`,
-                // and every row is `SetWidth` to one common width, so a left-seated label puts all
-                // seven texts on one left edge. The word still reaches the *paint* and
-                // `GetJustifyH()` — `0x783c30`'s tail notify writes the resolved justify into the
-                // label's own `+0x120` (`0x784111` → `0x784180` → `0x773530` → `0x770800` at
-                // `0x770876`), downstream of the anchor — which is why the visible difference is
-                // the anchor alone.
-                //
-                // The adopter's own conditional anchor (`0x778d20`, `[button+0x390]` — decision
-                // 1996) is **structurally dead on both XML label paths**: the builder anchors
-                // first, and the 9-slot scan at `0x778d5f` then finds a slot filled. It is live
-                // only where the label is born from `text=` or Lua `SetText`.
+                // Clear, lay out, then the implicit step, as both reference legs do (`0x6f27f5`,
+                // `0x778b96`); the button's own adopter anchor never fires on them (`0x778d5f`).
+                // On `<NormalText>` the justify is the Normal font's, so the implicit anchor reads
+                // the ctor's CENTER (`0x212`); the justify still reaches the paint (`0x784111`).
                 self.call_region(&region, "ClearAllPoints", (), dbg);
                 self.apply_region_layout(bt, &region, self_name, dbg, font_attrs);
                 if let Err(e) = crate::script::implicit_creation_anchor_lua(self.lua, &region) {
@@ -290,11 +168,8 @@ impl Loader<'_> {
                         .errors
                         .push(format!("{dbg}: implicit anchor: {e}"));
                 }
-                // Publish the label under its resolved name (`<ButtonText name="$parentText">`) —
-                // the ref kit addresses tab/button labels by exactly this global
-                // (PanelTemplates_TabResize's `getglobal(tabName.."Text")`).
+                // Published both ways, like a named state texture.
                 if let Some(rname) = bt_name {
-                    // The registry too, for the same reason as the state textures below (1957).
                     crate::script::region::publish_region_name(self.lua(), &rname, &region);
                     if let Err(e) = self.lua().globals().set(rname.clone(), region) {
                         self.report
@@ -317,14 +192,11 @@ impl Loader<'_> {
             }
         }
         if let Some(text) = el.attr("text") {
-            // `<Button text=>` → the ButtonText fontstring, global-string resolved
-            // (`0x703bf0`). This is what makes the reference's `text="DELETE"` read "Delete".
+            // A global-string key (`0x703bf0`): `text="DELETE"` reads "Delete".
             let text = self.resolve_text(text, dbg);
             self.call(wrapper, "SetText", text, dbg);
         }
-        // The per-state label fonts (`<NormalFont inherits=>` etc. — UIPanelButtonTemplate's
-        // gold/white/gray label trio) → the 1.12 setter trio; every occurrence applies in
-        // document order (same last-wins rule as `apply_size`).
+        // The per-state fonts, two spellings each; every occurrence applies, in document order.
         for (children, method, which) in [
             (
                 ["NormalFont", "NormalText"],
@@ -343,35 +215,15 @@ impl Loader<'_> {
             ),
         ] {
             for f in children_named_any(el, &children) {
-                // These three are `<Font>`-TYPED elements — `CSimpleButton::LoadXML 0x7788c0`
-                // routes them at `0x778bf4` into the SAME `0x783c30` a top-level `<Font>` uses — so
-                // they take `inherits=` and `font=` alike, and `font=` wins: both land in one slot
-                // and `0x770c60` unlinks the previous parent (`font=`'s registry-first path is
-                // `0x783d15` → `0x783d22 call 0x770c60` → `0x783d27 jmp 0x783ee0`).
-                //
-                // Reading only `inherits=` here left every corpus button that writes `font=` on its
-                // own default font — Bagnon writes it at seven sites, which is why its character
-                // list's names and its "Show Bags" label were not the Large/normal faces they ask
-                // for. Real FrameXML always writes `inherits=`, so nothing we ship noticed.
-                //
-                // `style=` is deliberately NOT read: it does not exist in 1.12.1. An isolated-token
-                // scan for it returns zero against nine controls that each return one — it is a
-                // later-client idiom, and the reference writes `<NormalFont inherits="GameFontNormal"/>`
-                // (`UIPanelTemplates.xml:20-22`).
+                // `<Font>`-typed elements (`0x778bf4` → `0x783c30`): `inherits=` and `font=` land
+                // in one slot and `font=` wins (`0x783d22`). `style=` is not 1.12 and is not read.
                 for attr in ["inherits", "font"] {
                     if let Some(name) = f.attr(attr) {
                         self.call(wrapper, method, name.to_string(), dbg);
                     }
                 }
-                // An element-level justify (`<NormalFont inherits="QuestFont" justifyH="LEFT"/>`)
-                // is a LOCAL write on that state's embedded font — the same `0x783c30` the
-                // `inherits=` above goes through, on `+0x33c`/`+0x3b8`/`+0x434` — never on the
-                // label. It is what the adopter reads to ANCHOR a label the button later makes
-                // for itself (`UIMenuButtonTemplate`'s rows: Lua `SetText` → `0x778d20` →
-                // `[button+0x390]`), and it reaches an existing label only through the live
-                // link. The v1 form wrote it onto the label directly, which forced a label into
-                // being here with a CENTER anchor already decided — the chat menu's rows drew
-                // centred and "Macro" ran into "/macro" (decision 1996).
+                // A `justifyH` here is a local write on that state's font, never the label
+                // (`0x783c30`); the button reads it to anchor a label it makes later (`0x778d20`).
                 if let Some(j) = f.attr("justifyH") {
                     match crate::justify::parse_h(j) {
                         crate::justify::Set::To(jh) => {
@@ -383,9 +235,8 @@ impl Loader<'_> {
                                     .push(format!("{dbg}: <{}> justifyH: {e}", f.tag));
                             }
                         }
-                        // The reference's parser clears the axis on a cross-axis token and
-                        // raises on a non-token; no 1.12 FrameXML writes either on these
-                        // elements, so both are reported rather than modelled.
+                        // Reported, not modelled: the reference clears the axis on a cross-axis
+                        // token and raises on a non-token.
                         _ => self.report.warnings.push(format!(
                             "{dbg}: <{}> justifyH=\"{j}\" is not a horizontal token — ignored",
                             f.tag
@@ -396,25 +247,10 @@ impl Loader<'_> {
         }
     }
 
-    /// `<EditBox>` extras (`0x779fb0`): the `letters` cap → SetMaxLetters,
-    /// `historyLines` → SetHistoryLines (the submitted-line recall ring), and the config flags
-    /// `autoFocus`/`numeric`/`password`/`multiLine`/`ignoreArrows` → their setters.
-    /// A flag absent from the XML stays at its ctor default, and the ctor's own value is
-    /// `flags = 1` — **`autoFocus` defaults ON**, every other flag off (`0x779a29 mov eax,1` /
-    /// `0x779a2e mov [esi+0x318],eax`; LoadXML's `autoFocus` leg writes nothing for an absent or
-    /// empty attribute, `0x77a0b3`/`0x77a0b8`). So the UI.xsd's `true` default is the client's too,
-    /// and the divergence documented here — benilla applying `flags = 0` uniformly — is retired
-    /// (decision 1686).
-    ///
-    /// **The flags are read presence-aware.** This loop used to call the setter only when an
-    /// attribute parsed as `true`, so `autoFocus="false"` was a no-op — harmless while the default
-    /// was off, and precisely backwards once it is on: the ten boxes in the shipped chain that opt
-    /// OUT (MailFrame ×3, MoneyInputFrame ×3, FriendsFrame ×3, AddonList ×1) are the only places
-    /// the attribute appears at all.
-    /// `<TextInsets>` maps to `SetTextInsets`; `blinkSpeed` → SetBlinkSpeed (the caret
-    /// half-period, `E+0x370`). A declared `<FontString>` is ASSIGNED as the box's text region by
-    /// the special-fontstring pass (`adopt_text_region` — the engine's LoadXML slot, never a
-    /// search).
+    /// `<EditBox>` (`0x779fb0`). An absent flag keeps the ctor's, where `autoFocus` is on and the
+    /// rest off (`0x779a29`, `0x77a0b3`), so flags are read presence-aware: `autoFocus="false"`
+    /// clears. The reference also skips an empty `autoFocus` (`0x77a0b8`), which clears here.
+    /// `blinkSpeed` is the caret half-period (`E+0x370`).
     pub(super) fn apply_editbox(&mut self, el: &Element, wrapper: &Table, dbg: &str) {
         if !el.tag.eq_ignore_ascii_case("EditBox") {
             return;
@@ -437,9 +273,6 @@ impl Loader<'_> {
         {
             self.call(wrapper, "SetBlinkSpeed", s, dbg);
         }
-        // <TextInsets><AbsInset left= right= top= bottom=/></TextInsets> → SetTextInsets(l,r,t,b)
-        // (the ref chat box drives these from ChatEdit_UpdateHeader at runtime; the XML form seeds
-        // the static case).
         if let Some(ins) = children_named(el, "TextInsets").next() {
             let src = children_named(ins, "AbsInset").next().unwrap_or(ins);
             let get = |k: &str| {
@@ -455,8 +288,7 @@ impl Loader<'_> {
             ("numeric", "SetNumeric"),
             ("password", "SetPassword"),
             ("multiLine", "SetMultiLine"),
-            // The XML spelling of the alt-arrow flag; the Lua spelling is `SetAltArrowKeyMode`,
-            // and there is one flag behind both (`0x77a6b0`/`0x7996e0`, bit `0x10`).
+            // One flag behind both spellings (`0x77a6b0`, `0x7996e0`, bit 0x10).
             ("ignoreArrows", "SetAltArrowKeyMode"),
         ] {
             if let Some(on) = el.attr_bool_opt(attr) {
@@ -465,29 +297,8 @@ impl Loader<'_> {
         }
     }
 
-    /// The two message-frame classes' LoadXML extras — **`0x787b20` and `0x785910`, two separate
-    /// tables**, which is why the shared attrs are applied for either tag and the two divergent
-    /// ones are gated on the tag that has them:
-    ///
-    /// - both: `displayDuration`/`fadeDuration` (float, applied **iff `> 0`** — the client's own
-    ///   gate) → SetTimeVisible/SetFadeDuration, and the `fade` bool → SetFading.
-    /// - `<ScrollingMessageFrame>` only: `maxLines` (int, `> 0`, destructive `SetMaxLines`).
-    /// - `<MessageFrame>` only: `insertMode` → SetInsertMode. The scrolling class has no such
-    ///   attribute and no such binding.
-    ///
-    /// A missing attr keeps the ctor default (fading on, 10s/3s; 8 lines / insertMode BOTTOM). The
-    /// `<FontString>` child renders through the generic `<Layers>` path; its resolved font **and its
-    /// `justifyH`** are what the frame's lines bake, stack and align at (read at extract,
-    /// `crate::script::UiScript::extract`) — that child is how `UIErrorsFrame.xml` centres its
-    /// toasts and how a chat frame keeps its lines flush left.
-    /// `<Minimap>`'s LoadXML extras (`CMinimap::LoadXML 0x4ee2b0`): the two model-file attributes,
-    /// which name the nine `Model` children the arena's ctor already built
-    /// (`crate::widget::MINIMAP_ENGINE_CHILDREN`). Both have engine defaults, so an attribute-less
-    /// `<Minimap>` still gets the stock arrows — the reference reads the default string when the
-    /// attribute is absent rather than leaving the children file-less.
-    ///
-    /// Gated on the element's own tag like every other step here, so a plain `<Frame>` wearing a
-    /// Minimap template simply skips it.
+    /// `<Minimap>` (`0x4ee2b0`): the two model files for the ctor's nine `Model` children, each
+    /// the stock model when the attribute is absent, as the reference reads a default string.
     pub(super) fn apply_minimap(&mut self, el: &Element, wrapper: &Table, dbg: &str) {
         if !el.tag.eq_ignore_ascii_case("Minimap") {
             return;
@@ -508,6 +319,10 @@ impl Loader<'_> {
         }
     }
 
+    /// `<ScrollingMessageFrame>` and `<MessageFrame>`, two loaders (`0x787b20`, `0x785910`): both
+    /// take `displayDuration` and `fadeDuration` (only when > 0) and `fade`; only the scrolling one
+    /// has `maxLines` (> 0), only the plain one `insertMode`. The line font and its `justifyH` come
+    /// from the direct-child `<FontString>`.
     pub(super) fn apply_messageframe(&mut self, el: &Element, wrapper: &Table, dbg: &str) {
         let scrolling = el.tag.eq_ignore_ascii_case("ScrollingMessageFrame");
         let plain = el.tag.eq_ignore_ascii_case("MessageFrame");
@@ -551,15 +366,9 @@ impl Loader<'_> {
         }
     }
 
-    /// `<Slider>` LoadXML extras (`0x789580`): `orientation` →
-    /// SetOrientation (the ctor default is VERTICAL — decision 0250 — so an omitted attr leaves a
-    /// vertical scrollbar); `minValue`/`maxValue` → SetMinMaxValues, with `valueStep` → SetValueStep
-    /// and `defaultValue` → SetValue — the latter three **gated on BOTH minValue AND maxValue
-    /// present** (`0x789580`). Unlike StatusBar, a reversed `min > max` pair is NOT swapped. The
-    /// `<ThumbTexture>` child → SetThumbTexture (file or `<Color>`) plus the generic region layout
-    /// (`<Size>`/`<Anchors>`/`<TexCoords>`/alphaMode); the element's `drawLayer` names the thumb's
-    /// layer (widget default OVERLAY). The scrollbar template declares only the thumb + orientation;
-    /// its range/value are set at runtime by `FauxScrollFrame_Update`.
+    /// `<Slider>` (`0x789580`), VERTICAL from the ctor: the range, `valueStep` and `defaultValue`
+    /// apply only when both bounds are present, and a reversed pair is not swapped; `drawLayer` is
+    /// the thumb's layer, OVERLAY by default.
     pub(super) fn apply_slider(
         &mut self,
         el: &Element,
@@ -585,11 +394,8 @@ impl Loader<'_> {
         }
         let layer = el.attr("drawLayer").map(str::to_string);
         for raw in children_named(el, "ThumbTexture") {
-            // Same two rules as a Button's state textures, for the same reasons: `inherits=` on a
-            // virtual `<Texture>` is expanded here (see `apply_button`), and a NAMED thumb is
-            // published as a global — `UIPanelScrollBarTemplate`'s own
-            // `ScrollFrame_OnScrollRangeChanged` reaches it with
-            // `getglobal(bar:GetName().."ThumbTexture")`.
+            // As for a Button's state textures: `inherits=` expands, and a named thumb is
+            // published (`ScrollFrame_OnScrollRangeChanged` reads it by name).
             let expanded = self.expand_region(raw);
             let tt = &expanded;
             if let Some(file) = tt.attr("file") {
@@ -602,9 +408,6 @@ impl Loader<'_> {
             } else if let Some(c) = children_named(tt, "Color").next().map(color_of) {
                 self.call(wrapper, "SetThumbTexture", (c[0], c[1], c[2], c[3]), dbg);
             }
-            // alphaMode / <Size> / <Anchors> / <TexCoords> apply to the thumb region the setter just
-            // created — fetch it back through the getter and use the region methods (same shape as a
-            // Button's state textures).
             if let Ok(region) = wrapper.call_method::<Table>("GetThumbTexture", ()) {
                 if let Some(mode) = tt.attr("alphaMode") {
                     self.call_region(&region, "SetBlendMode", mode.to_string(), dbg);
@@ -625,16 +428,9 @@ impl Loader<'_> {
         }
     }
 
-    /// `<ColorSelect>`'s four texture sub-elements (loader hooks `0x78b580`, `0x78b850`,
-    /// `0x78b8a0`, `0x78ba90`) — the hue wheel, the brightness strip, and a marker for each.
-    /// Structurally `apply_slider`'s `<ThumbTexture>` loop, four times over.
-    ///
-    /// The one thing that is NOT like a thumb: **two of the four carry no `file=`, and that is not
-    /// an omission.** The client generates the wheel and the strip; there is no BLP in the chain
-    /// that is a colour wheel. So the setter is still called — with nothing — because the *region*
-    /// must exist regardless: it is what layout resolves, what the press handler hit-tests, and
-    /// what the app renderer paints into. An element that skipped the setter would leave the picker
-    /// with no wheel to click.
+    /// `<ColorSelect>`'s four textures (`0x78b580`, `0x78b850`, `0x78b8a0`, `0x78ba90`): the hue
+    /// wheel, the value strip and a thumb for each. The client generates the wheel and the strip,
+    /// so a file-less element still creates its region, for layout, hit tests and paint.
     pub(super) fn apply_colorselect(
         &mut self,
         el: &Element,
@@ -676,7 +472,6 @@ impl Loader<'_> {
                 } else if let Some(c) = children_named(tt, "Color").next().map(color_of) {
                     self.call(wrapper, setter, (c[0], c[1], c[2], c[3]), dbg);
                 } else {
-                    // The file-less form — create the region and leave it for the renderer.
                     self.call(wrapper, setter, (), dbg);
                 }
                 if let Ok(region) = wrapper.call_method::<Table>(getter, ()) {
@@ -689,9 +484,8 @@ impl Loader<'_> {
                     }
                     if let Some(rname) = tt.name().map(|raw| framexml::resolve_name(raw, self_name))
                     {
-                        // Into the region-name registry as well as `_G`: `<ColorValueTexture>`
-                        // anchors to `ColorPickerWheel` BY NAME, and a name that only reaches the
-                        // globals resolves to nothing there.
+                        // Published both ways: the stock `<ColorValueTexture>` anchors to
+                        // `ColorPickerWheel` by name.
                         crate::script::region::publish_region_name(self.lua(), &rname, &region);
                         if let Err(e) = self.lua().globals().set(rname.clone(), region) {
                             self.report
@@ -704,25 +498,9 @@ impl Loader<'_> {
         }
     }
 
-    /// `<SimpleHTML>` LoadXML extras — `CSimpleHTML::LoadXML 0x78a130`, whose whole job past the
-    /// base `CSimpleFrame::LoadXML 0x769820` is to fill the four **element fonts** and the
-    /// hyperlink format:
-    ///
-    /// - attribute **`font="NAME"`** (`0x78a152`) — looked up as a font object and `SetFontObject`ed
-    ///   onto **all four** elements at once (the `edi = 4` loop at `0x78a17a`), with
-    ///   `"Couldn't find font object named %s"` on a miss.
-    /// - child **`<FontString>`** → `elementFont[0]` (`P`), **`<FontStringHeader1|2|3>`** →
-    ///   `[1]`/`[2]`/`[3]` (`0x78a1fe`…`0x78a26e`), each through `CSimpleFont::LoadXML 0x783c30`.
-    /// - attribute **`hyperlinkFormat`** (`0x87a87c` → `0x78a540`) and attribute **`file`**
-    ///   (`0x8710b8`), the latter a localized-string lookup fed straight to `SetText`.
-    ///
-    /// **These `<FontString>` children are font DECLARATIONS, not regions**, which is why
-    /// [`Self::apply_special_fontstrings`] skips a `<SimpleHTML>`: creating a real FontString for
-    /// one would put an extra, unanchored string on the frame and leave the element font empty.
-    ///
-    /// Stock `ItemTextFrame.xml` declares exactly one `<FontString inherits="ItemTextFontNormal"/>`,
-    /// which is the whole reason an `<H1>` in a `page_text` body renders at the `<P>` size: nothing
-    /// declares a header font, so `0x78ae30`'s empty-path test sends every element back to `P`'s.
+    /// `<SimpleHTML>` (`0x78a130`): `font=` for all four element fonts (`0x78a17a`), the
+    /// `<FontString>` and `<FontStringHeader1..3>` children one each (`0x78a1fe`, through
+    /// `0x783c30`), `hyperlinkFormat` (`0x78a540`), and `file=`, a global-string key for `SetText`.
     pub(super) fn apply_simplehtml(&mut self, el: &Element, wrapper: &Table, dbg: &str) {
         if !el.tag.eq_ignore_ascii_case("SimpleHTML") {
             return;
@@ -730,8 +508,7 @@ impl Loader<'_> {
         if let Some(fmt) = el.attr("hyperlinkFormat") {
             self.call(wrapper, "SetHyperlinkFormat", fmt.to_string(), dbg);
         }
-        // `font=` on the widget itself paints all four elements; a per-element child below can
-        // still override any of them, exactly as the reference's ordering allows.
+        // Read before the children (`0x78a152`), which may override it.
         if let Some(name) = el.attr("font").filter(|n| !n.is_empty()) {
             if self.is_font_object(name) {
                 for elem in ["P", "H1", "H2", "H3"] {
@@ -746,7 +523,7 @@ impl Loader<'_> {
         }
         for child in &el.children {
             let Some(elem) = crate::script::simplehtml_element_of_xml_tag(&child.tag) else {
-                continue; // <Size>/<Anchors>/<Scripts>/<Layers>/... have their own passes
+                continue;
             };
             let child = &self.expand_region(child);
             self.apply_element_font(child, wrapper, elem, dbg);
@@ -757,14 +534,8 @@ impl Loader<'_> {
         }
     }
 
-    /// One `<FontString>`/`<FontStringHeaderN>` child of a `<SimpleHTML>` → one element font.
-    ///
-    /// The `inherits=` → `font=` gate is the same three-outcome law a `<Layers>` `<FontString>`
-    /// takes ([`Self::apply_fontstring_font`], `0x7710e1`-`0x771254`): a `font=` naming a registered
-    /// object is a `SetFontObject` and **skips** `<FontHeight>`/`outline=` entirely; a `font=`
-    /// naming anything else is a file with those two as its companions; no `font=` at all means
-    /// neither is ever parsed. Only `<Color>`/`<Shadow>`/`justifyH`/`justifyV`/`spacing` sit past
-    /// that join and are genuine post-link overrides.
+    /// One `<SimpleHTML>` font child's element font, with the same `font=` gate as
+    /// [`Self::apply_fontstring_font`].
     fn apply_element_font(&mut self, el: &Element, wrapper: &Table, elem: usize, dbg: &str) {
         let name = ["P", "H1", "H2", "H3"][elem];
         if let Some(inherits) = el.attr("inherits").filter(|n| !n.is_empty()) {
diff --git a/crates/benilla-ui/src/markup.rs b/crates/benilla-ui/src/markup.rs
index 7bb89712..e5817f9e 100644
--- a/crates/benilla-ui/src/markup.rs
+++ b/crates/benilla-ui/src/markup.rs
@@ -1,137 +1,57 @@
-//! WoW's inline text markup — the grammar every 1.12.1 string carries (`|cAARRGGBB`, `|r`,
-//! `|H…|h…|h`, `|n`, `||`), and the cursor law an edit box builds on top of it.
+//! The 1.12 inline text markup (`|cAARRGGBB`, `|r`, `|H…|h…|h`, `|n`, `||`) and the edit box's
+//! cursor law over it, one grammar for the renderer and the edit box. It transcribes the token
+//! decoder `0x5c2810` ([`token_at`]: a byte remap at `0x5c2b10` into the jump table at `0x5c2af4`)
+//! and the edit box's per-byte class array `E+0x330`, rebuilt by `0x77ba90` after every edit, with
+//! the primitives that read it ([`ClassMap`]).
 //!
-//! Pure: `&str` in, indices out. No Lua, no Bevy, no engine types, no I/O — so the renderer and the
-//! edit box can share **one** owner of the grammar instead of drifting apart on where an escape
-//! starts and ends.
+//! 1.12 has no `|T…|t` texture escape: the remap claims only `c`, `h`, `n`, `r` in either case and
+//! `|`, so `|TInterface\Icons\Foo:16:16|t` draws literally.
 //!
-//! ## Ground truth
+//! The decoder's flags word can disable classes, but no code in the 1.12 client sets the bits for
+//! `|c`, `|r`, `|H`, `|h` or `||` (`0x44d670` builds it from a font string's flags). Only `|n` can
+//! be switched off, on a single-line edit box (`SetMultiLine`, `0x77a5e2`), and the class map
+//! parses it regardless (`0x77ba90` passes 0), so that gate belongs to the renderer's line breaker.
 //!
-//! Two client mechanisms are transcribed here, and every claim below carries its address:
-//!
-//! - **`0x5c2810`** — the token decoder. Given a pointer it
-//!   returns a class 0..6 and the token's byte length, dispatching off a byte remap at `0x5c2b10`
-//!   into the 7-arm jump table at `0x5c2af4`. That is [`token_at`] / [`tokens`].
-//! - **`0x77ba90`** — the edit box's per-byte class array `E+0x330`, rebuilt in full after every
-//!   mutation, plus the five primitives that read it (`0x77bd10`, `0x77bd30`, `0x77bc80`,
-//!   `0x77bb30`, `0x77c510`, `0x77bee0`). That is [`ClassMap`].
-//!
-//! ## The seven classes — the client's own numbering
-//!
-//! - **0** `|cAARRGGBB` — 10 bytes. The `AA` is parsed and then *discarded*: `0x5c2ab2–0x5c2ace`
-//!   builds `0xFF << 24 | RR << 16 | GG << 8 | BB`. See [`Rgba`].
-//! - **1** `|r` / `|R` — 2 bytes.
-//! - **2** `\n` · `\r` · `\r\n` · `|n` / `|N` — 1 or 2 bytes.
-//! - **3** `||` — 2 bytes, draws one literal `|`.
-//! - **4** hyperlink OPEN — the **entire** `|H<payload>|h` prefix, however long.
-//! - **5** `|h` close — 2 bytes.
-//! - **6** an ordinary character — its UTF-8 length. Everything the remap doesn't claim lands here,
-//!   *including* a `|` followed by anything outside `{c C h H n N r R |}`.
-//!
-//! **1.12.1 has no `|T…|t` inline-texture escape at all.** The remap table at `0x5c2b10` (index =
-//! `ch - 'C'`) sends every byte but `C`/`H`/`N`/`R` and their lowercase siblings to the
-//! ordinary-character arm, so `|TInterface\Icons\Foo:16:16|t` draws literally, pipe and all. Inline
-//! textures are a later-expansion feature; this module must not invent one.
-//!
-//! ## What the parse gates do *not* do
-//!
-//! `0x5c2810` takes a flags word `K` that can disable classes, and `0x44d670` translates the
-//! FontString's `F` into it. An origination census over the whole image found **no writer anywhere**
-//! for the bits behind `K & 0x100` / `0x400` / `0x800`, so `|c`, `|r`, `|H`, `|h` and `||` are parsed
-//! unconditionally by every `CSimpleFontString` in build 5875. Only `|n` is switchable (`F & 0x4000`,
-//! set on a single-line edit box by `SetMultiLine` `0x77a5e2`) — and `0x77ba90` builds the class map
-//! with `K = 0` regardless, so the *cursor* model always sees `|n` as one token. This module
-//! therefore takes no flags word: the one live gate belongs to the renderer's line breaker, not to
-//! the grammar (the resulting caret drift in a single-line box carrying `|n` is inferred from the
-//! verified byte mechanism, not confirmed live, and is the renderer's to reproduce or to fix).
-//!
-//! ## The law this module exists to hold
-//!
-//! **The reachable cursor set is "a token boundary with every adjacent zero-width escape absorbed"
-//! — after any trailing `|r`/`|h`, before any leading `|c`/`|H`** (`0x77bb30`). No index inside an
-//! escape is representable as an output of [`ClassMap::advance`], at either atomicity, in either
-//! direction;
-//! atomicity adds exactly one thing, that the visible text between `|H…|h` and its closing `|h`
-//! becomes uncrossable in a single step. Every index taken or returned by anything here is a byte
-//! offset into the original string, and every one lands on a UTF-8 character boundary.
-//!
-//! ## Inferred, not verified
-//!
-//! Flagged here as well as at each site:
-//!
-//! - **`|H` opens and `|h` closes, discriminated by case.** The remap sends both to one arm and the
-//!   case test itself was not disassembled; the class table above (class 4 is the whole
-//!   `|H<payload>|h`, class 5 is `|h`) plus the empty-visible-text guard comparing against
-//!   lowercase `0x68`
-//!   (`80 7e 01 68` @`0x5c2992`) is the whole basis.
-//! - **The delimiter search is a plain forward byte scan for `|h`** that does not skip `||`. The
-//!   emitter's own scan (`0x5ccdc8`, against the literal at `0x84453c`) is described the same way;
-//!   the decoder arm's scan was not disassembled.
-//! - **`0x77bc80`'s second argument is a byte budget**, not a token count — from the `(start, count)`
-//!   signature and the byte-budget shape of its sibling kernel `0x5c6940`.
-//! - **The end-of-buffer guard on [`ClassMap::advance`] is ours.** The disassembled excerpt of
-//!   `0x77bb30` shows no bound, and its class-0/class-4 "keep skipping" arms would spin on the zero
-//!   terminator.
-//! - **The worked example is itself inferred, not independently verified** — it follows from the
-//!   verified mechanism above.
+//! A cursor stands only on a token boundary with the adjacent zero-width escapes absorbed: after
+//! any trailing `|r`/`|h`, before any leading `|c`/`|H` (`0x77bb30`). Every index here is a byte
+//! offset on a UTF-8 character boundary.
 
 use std::ops::Range;
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The colour a `|c` token carries
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The colour a `|c` token carries ──────────────────────────────────────────────────────────
 
-/// The colour decoded from `|cAARRGGBB`, packed exactly as the client packs it —
-/// `0xFF << 24 | RR << 16 | GG << 8 | BB` (`0x5c2ab2–0x5c2ace`).
-///
-/// **The `AA` nibbles are parsed and then thrown away**: there is no way to spell a
-/// translucent colour in 1.12.1 markup. A type that cannot carry alpha is how this module refuses to
-/// invent one — `|c00ff0000` and `|cffff0000` are the same opaque red.
+/// A `|cAARRGGBB` colour as the decoder packs it, `0xFFRRGGBB` (`0x5c2ab2..0x5c2ace`): the `AA` is
+/// parsed and discarded, so `|c00ff0000` and `|cffff0000` are the same red.
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
 pub struct Rgba(u32);
 
 impl Rgba {
-    /// The opaque colour with these components — the only way to build one.
     pub const fn from_rgb(r: u8, g: u8, b: u8) -> Rgba {
         Rgba(0xff00_0000 | ((r as u32) << 16) | ((g as u32) << 8) | b as u32)
     }
 
-    /// The client's packed dword, `0xFFRRGGBB`.
     pub const fn packed(self) -> u32 {
         self.0
     }
 
-    /// Red.
     pub const fn r(self) -> u8 {
         (self.0 >> 16) as u8
     }
 
-    /// Green.
     pub const fn g(self) -> u8 {
         (self.0 >> 8) as u8
     }
 
-    /// Blue.
     pub const fn b(self) -> u8 {
         self.0 as u8
     }
 
-    /// Alpha — always `0xff`. Kept as an accessor so the discard is visible at the call site.
     pub const fn a(self) -> u8 {
         0xff
     }
 
-    /// `[r, g, b, alpha]` in 0..1 — the escape's colour drawn at the **FontString's own alpha**.
-    ///
-    /// The decoder forcing `0xff` is only half the law: the emitter then patches the FontString's
-    /// alpha byte over it (`mov cl,[edi+0x2f]; mov [ebp-0x39],cl` @`0x5cceb0`/`0x5cceb6`, written
-    /// into the outColor slot *before* `mov edx,[ebp-0x3c]` reads it). So a `|c` span fades with
-    /// the string it sits in; drawing it opaque would leave a chat link burning at full alpha while
-    /// its own line faded out.
-    ///
-    /// Taking `alpha` as an argument rather than storing one keeps both halves true: the *escape*
-    /// still cannot carry alpha (`|c00ff0000` and `|cffff0000` are the same colour), and the alpha
-    /// that reaches the vertex is always the string's.
+    /// `[r, g, b, alpha]` in 0..1: the emitter patches the font string's own alpha over the decoded
+    /// `0xff` (`0x5cceb0`, `0x5cceb6`), so a `|c` span fades with its string.
     pub fn to_f32_at(self, alpha: f32) -> [f32; 4] {
         [
             self.r() as f32 / 255.0,
@@ -142,57 +62,46 @@ impl Rgba {
     }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Layer 1 — the token decoder (`0x5c2810`)
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Layer 1: the token decoder (`0x5c2810`) ──────────────────────────────────────────────────
 
-/// The token class, with the client's own numbering as the discriminant. Returned by `0x5c2810` in
-/// `eax`, and stored in bits
-/// 16..23 of every class-map entry.
+/// The token class as `0x5c2810` numbers it, and as a class-map entry stores it (bits 16..23).
 #[repr(u8)]
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
 pub enum TokenClass {
-    /// 0 — `|cAARRGGBB`, 10 bytes.
+    /// `|cAARRGGBB`, 10 bytes.
     Color = 0,
-    /// 1 — `|r` / `|R`, 2 bytes.
+    /// `|r` or `|R`, 2 bytes.
     ColorReset = 1,
-    /// 2 — `\n`, `\r`, `\r\n`, `|n` / `|N`.
+    /// `\n`, `\r`, `\r\n`, `|n` or `|N`.
     LineBreak = 2,
-    /// 3 — `||`, 2 bytes, drawing one literal `|`.
+    /// `||`, 2 bytes, drawing one `|`.
     EscapedPipe = 3,
-    /// 4 — hyperlink OPEN: the entire `|H<payload>|h` prefix.
+    /// A hyperlink's whole `|H<payload>|h` prefix.
     LinkOpen = 4,
-    /// 5 — `|h`, the close, 2 bytes.
+    /// `|h`, 2 bytes, closing a hyperlink.
     LinkClose = 5,
-    /// 6 — an ordinary character, its UTF-8 length.
+    /// An ordinary character, its UTF-8 length.
     Char = 6,
 }
 
-/// What a token *is*, with whatever it carries.
+/// A token and what it carries.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum TokenKind<'a> {
-    /// Class 0 — switch the draw colour. Opaque by construction; see [`Rgba`].
     Color(Rgba),
-    /// Class 1 — back to the string's base colour (`0x5cce99` restores `FontString+0x2c`).
+    /// Back to the string's base colour (`0x5cce99` restores `FontString+0x2c`).
     ColorReset,
-    /// Class 2 — a line break, whichever of the four spellings produced it.
     LineBreak,
-    /// Class 3 — `||`, which draws one `|` (`0x5ccec3` looks up the glyph).
+    /// Draws one `|` (`0x5ccec3` looks up the glyph).
     EscapedPipe,
-    /// Class 4 — open a hyperlink over the visible text that follows. `payload` is the text between
-    /// `|H` and the delimiting `|h` (`item:12345:0:0:0`, `player:Bob`).
     LinkOpen {
-        /// The link payload, delimiters excluded.
+        /// The text between `|H` and `|h`, such as `item:12345:0:0:0`.
         payload: &'a str,
     },
-    /// Class 5 — the closing `|h`.
     LinkClose,
-    /// Class 6 — an ordinary character. A `|` that opened nothing well-formed arrives here too.
     Char(char),
 }
 
 impl TokenKind<'_> {
-    /// The client's class number for this token.
     pub const fn class(&self) -> TokenClass {
         match self {
             TokenKind::Color(_) => TokenClass::Color,
@@ -206,39 +115,28 @@ impl TokenKind<'_> {
     }
 }
 
-/// One decoded token: what it is, and how many bytes of the source it spans.
-///
-/// The length is not derivable from the kind — `\r\n` and `\n` are both [`TokenKind::LineBreak`],
-/// and a [`TokenKind::LinkOpen`] spans its whole `|H<payload>|h` prefix — so `0x5c2810` returns it
-/// separately (`*ioLen`), and so do we.
+/// One decoded token and its byte length, which `0x5c2810` returns beside the class (`*ioLen`).
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub struct Token<'a> {
-    /// What this token is.
     pub kind: TokenKind<'a>,
-    /// Its byte length. Always ≥ 1.
+    /// At least 1.
     pub byte_len: usize,
 }
 
 impl Token<'_> {
-    /// The client's class number for this token.
     pub const fn class(&self) -> TokenClass {
         self.kind.class()
     }
 }
 
-/// Decode the token starting at byte offset `at` — the whole of `0x5c2810`.
-///
-/// `None` at (or past) the end of the string. `at` must be a UTF-8 character boundary of `text`;
-/// every offset this module produces is one.
-///
-/// The degradations are law, not tolerance: a `|` that opens nothing well-formed is an *ordinary
-/// character* of length 1, exactly as the remap table's fall-through arm makes it.
+/// Decode the token at byte offset `at`, a character boundary: `0x5c2810`. A `|` that opens
+/// nothing well-formed is an ordinary character of length 1, as the remap's fall-through makes it.
 pub fn token_at(text: &str, at: usize) -> Option<Token<'_>> {
     let rest = &text[at..];
     let b = rest.as_bytes();
     let first = *b.first()?;
 
-    // The two bare line breaks. `\r\n` is ONE class-2 token; a lone `\r` is one as well.
+    // `\r\n` is one class-2 token; a lone `\r` is one too.
     if first == b'\r' {
         let byte_len = if b.get(1) == Some(&b'\n') { 2 } else { 1 };
         return Some(Token {
@@ -254,8 +152,7 @@ pub fn token_at(text: &str, at: usize) -> Option<Token<'_>> {
     }
 
     if first == b'|' {
-        // The ordinary-character fall-through: a lone `|`, or one leading anything the remap table
-        // at `0x5c2b10` does not claim.
+        // A lone `|`, or one leading anything the remap (`0x5c2b10`) does not claim.
         let literal_pipe = Token {
             kind: TokenKind::Char('|'),
             byte_len: 1,
@@ -281,8 +178,8 @@ pub fn token_at(text: &str, at: usize) -> Option<Token<'_>> {
                 kind: TokenKind::EscapedPipe,
                 byte_len: 2,
             },
-            // INFERRED (see the module doc): uppercase opens, lowercase closes. The remap sends both
-            // to one arm and the case test itself was not disassembled.
+            // Uppercase opens and lowercase closes, inferred: the remap sends both to one arm,
+            // whose case test is untraced.
             Some(b'H') => match parse_link_open(rest) {
                 Some((payload, byte_len)) => Token {
                     kind: TokenKind::LinkOpen { payload },
@@ -305,9 +202,7 @@ pub fn token_at(text: &str, at: usize) -> Option<Token<'_>> {
     })
 }
 
-/// `b` starts with `|c` or `|C`. Parse the 8 following hex digits as `AARRGGBB` and **discard the
-/// alpha** (`0x5c2ab2–0x5c2ace`). `None` when fewer than 8 hex digits follow — a malformed colour is
-/// an ordinary character, not a swallowed escape.
+/// The 8 hex digits `AARRGGBB` after `|c`, alpha discarded; fewer leave the `|` literal.
 fn parse_color(b: &[u8]) -> Option<Rgba> {
     let digits = b.get(2..10)?;
     let mut v: u32 = 0;
@@ -317,18 +212,10 @@ fn parse_color(b: &[u8]) -> Option<Rgba> {
     Some(Rgba::from_rgb((v >> 16) as u8, (v >> 8) as u8, v as u8))
 }
 
-/// `rest` starts with `|H`. Returns the payload and the byte length of the **whole**
-/// `|H<payload>|h` prefix, or `None` for each of the three degradations that make the `|H` a literal
-/// `|` instead:
-///
-/// - no closing `|h` anywhere after it — the forward scan finds no delimiter;
-/// - the span is exactly 4 bytes, i.e. an empty payload (`83 f8 04; 75 1b` @`0x5c2972`);
-/// - the visible text is empty, i.e. the span is immediately followed by another `|h`
-///   (`80 f9 7c; 75 21; 80 7e 01 68; 75 1b` @`0x5c2992`).
-///
-/// The scan is a plain forward byte search that does not skip `||` (INFERRED — the emitter's own
-/// scan at `0x5ccdc8` is described the same way). Searching bytes is safe in UTF-8: `|` and `h` are
-/// ASCII and can never appear inside a multi-byte character.
+/// The payload after `|H` and the length of the whole `|H<payload>|h` prefix; `None`, a literal
+/// `|`, when no `|h` follows, when the payload is empty (`0x5c2972`) or when the visible text is
+/// empty (`0x5c2992`). The delimiter scan is a plain byte search that does not skip `||`, inferred
+/// from the emitter's own scan (`0x5ccdc8`, for the literal at `0x84453c`).
 fn parse_link_open(rest: &str) -> Option<(&str, usize)> {
     let b = rest.as_bytes();
     let delim = (2..b.len().saturating_sub(1)).find(|&i| b[i] == b'|' && b[i + 1] == b'h')?;
@@ -342,7 +229,7 @@ fn parse_link_open(rest: &str) -> Option<(&str, usize)> {
     Some((&rest[2..delim], span))
 }
 
-/// Every token of `text`, each with the byte offset it starts at — `char_indices`, one grammar up.
+/// Every token of `text` with the byte offset it starts at.
 pub fn tokens(text: &str) -> Tokens<'_> {
     Tokens { text, at: 0 }
 }
@@ -365,25 +252,14 @@ impl<'a> Iterator for Tokens<'a> {
     }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Layer 2 — the per-byte class map (`E+0x330`, built by `0x77ba90`)
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Layer 2: the per-byte class map (`E+0x330`, built by `0x77ba90`) ─────────────────────────
 
-/// One entry of the class map — the client's packed dword, unpacked:
+/// One class-map entry, the client's dword unpacked: byte length in bits 0..15, class in 16..23,
+/// "inside a hyperlink" in bit 31. Only a token's first byte is stored (`0x77bb0f`); continuation
+/// bytes and the terminator are zero, so they read as no class and not in a link.
 ///
-/// - bits 0..15, the token's **byte length**, non-zero only at the token's *first* byte;
-/// - bits 16..23, the token class;
-/// - bit 31, **"inside a hyperlink"**.
-///
-/// Every continuation byte, and the terminator past the end, is the all-zero dword: `0x77ba90`
-/// `rep stos`-zeroes the array and then stores only at each token's first byte
-/// (`mov [classArr + 4*ebx], ecx` @`0x77bb0f`). So [`Entry::class`] is `None` exactly where
-/// [`Entry::byte_len`] is 0, and [`Entry::in_link`] reads false on a continuation byte even inside
-/// a link — which is the client's own reading (`0x77c510` tests the whole dword's sign bit), and
-/// harmless, since no cursor can be at one.
-///
-/// The client's length field is 16 bits (`and len,0xffff` @`0x77baf3`); ours is wider, so a
-/// pathological `|H` span ≥ 64 KiB simply does not wrap.
+/// Deviation: the length keeps every bit, where the client masks it to 16 (`0x77baf3`), because a
+/// wrapped length would put the cursor inside an `|H` span of 64 KiB or more.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub struct Entry {
     byte_len: u32,
@@ -399,53 +275,39 @@ impl Entry {
         in_link: false,
     };
 
-    /// The token's byte length — 0 at a continuation byte and at the terminator.
     pub const fn byte_len(&self) -> usize {
         self.byte_len as usize
     }
 
-    /// The token class, or `None` at a continuation byte / the terminator.
     pub const fn class(&self) -> Option<TokenClass> {
         self.class
     }
 
-    /// Bit 31 — is this token part of a hyperlink? Raised on the class-4 open **inclusive**, lowered
-    /// only *after* the class-5 close, so the close is tagged too.
+    /// Bit 31: set from a link's `|H` through its closing `|h`, both included.
     pub const fn in_link(&self) -> bool {
         self.in_link
     }
 
-    /// Does a token start here? (Equivalently: is this not a continuation byte?)
     pub const fn is_token_start(&self) -> bool {
         self.byte_len != 0
     }
 }
 
-/// The per-byte token-class array the edit box keeps at `E+0x330`, and the cursor primitives that
-/// read it.
-///
-/// One entry per byte of the source string plus a terminating entry
-/// (`classArr[len] = 0` @`0x77c670`), so an index equal to the string length is always valid — the
-/// cursor's home at the end of the buffer.
-///
-/// It holds no text: every primitive here reads only the entries, which is what lets an edit box own
-/// its `String` and rebuild the map beside it after each mutation, exactly as `0x77ba90` is called
-/// at the tail of every insert (`0x77c022`).
+/// The edit box's per-byte class array (`E+0x330`) and the cursor primitives over it: one entry
+/// per byte plus a zero terminator (`0x77c670`). It holds no text; the edit box rebuilds it after
+/// every edit, as the client calls `0x77ba90` at the end of each insert (`0x77c022`).
 #[derive(Clone, PartialEq, Eq, Debug)]
 pub struct ClassMap {
     entries: Vec<Entry>,
 }
 
 impl ClassMap {
-    /// Build the map for `text` — `0x77ba90`.
-    ///
-    /// The client passes `K = 0` here (`push 0` @`0x77bad9`), so the cursor model always parses
-    /// *every* class, `|n` included, whatever the FontString's flags say.
+    /// `0x77ba90`, which parses every class, `|n` included, whatever the font string's flags
+    /// (`K = 0` at `0x77bad9`).
     pub fn new(text: &str) -> ClassMap {
         let mut entries = vec![Entry::CONTINUATION; text.len() + 1];
-        // The sticky link bit: raised BEFORE the store on a class-4 open (`or [ebp-4],0x80000000`
-        // @`0x77baec`), lowered AFTER the store on a class-5 close (`and [ebp-4],0x7fffffff`
-        // @`0x77bb1e`) — which is why the closing `|h` is tagged and the byte after it is not.
+        // The link bit rises before the store on an open (`0x77baec`) and falls after it on a
+        // close (`0x77bb1e`), so the closing `|h` is tagged and the byte after it is not.
         let mut in_link = false;
         for (at, token) in tokens(text) {
             let class = token.class();
@@ -464,27 +326,22 @@ impl ClassMap {
         ClassMap { entries }
     }
 
-    /// The byte length of the string this map was built from.
     pub fn text_len(&self) -> usize {
         self.entries.len() - 1
     }
 
-    /// The entry for byte `at`. `at == text_len()` is the terminator; anything past it panics.
+    /// `at == text_len()` is the terminator; past it panics.
     pub fn entry(&self, at: usize) -> Entry {
         self.entries[at]
     }
 
-    /// The next token's start — `0x77bd10`, which is `i + (classArr[i] & 0xffff)` and nothing else.
-    ///
-    /// A fixed point at the terminator and at any continuation byte, where the length is 0; the
-    /// client's add is unguarded in the same way, so a forward walk tests `at < text_len()` rather
-    /// than relying on this to move.
+    /// The next token's start, `0x77bd10`: a fixed point where the length is 0, as the client's
+    /// unguarded add is, so a forward walk must test `at < text_len()`.
     pub fn next_token(&self, at: usize) -> usize {
         at + self.entry(at).byte_len()
     }
 
-    /// The previous token's start — `0x77bd30`: walk back from `at - 1` while the entry is a
-    /// continuation. `None` when there is none (the client's `-1`), i.e. at offset 0.
+    /// The previous token's start, `0x77bd30`; `None`, the client's `-1`, at offset 0.
     pub fn prev_token(&self, at: usize) -> Option<usize> {
         let mut i = at.checked_sub(1)?;
         while !self.entry(i).is_token_start() {
@@ -493,16 +350,9 @@ impl ClassMap {
         Some(i)
     }
 
-    /// How many **letters** the `byte_count` bytes from `start` hold — `0x77bc80`, which counts
-    /// classes 2, 3 and 6 only (`83 fa 02/03/06` @`0x77bcb0`).
-    ///
-    /// This is what `GetNumLetters` reports and what `SetMaxLetters` caps, so **classes 0/1/4/5 are
-    /// not letters**: a 48-byte item link costs 14, its visible `[Chipped Claw]` and nothing more.
-    ///
-    /// INFERRED: that the second argument is a byte budget (only its `(start, count)` signature is
-    /// known; the sibling kernel `0x5c6940` consumes bytes the same way). A token straddling the
-    /// end of the budget is counted whole and ends the walk — deliberately *not* the sibling
-    /// kernel's run-to-the-NUL behaviour, which is a latent trap with no upside here.
+    /// The letters in `byte_count` bytes from `start`, `0x77bc80`, a per-byte scan that counts
+    /// only classes 2, 3 and 6 (`0x77bcb0`): `GetNumLetters` and `SetMaxLetters` see a 48-byte
+    /// item link as its 14 visible letters. A token starting inside the budget counts whole.
     pub fn letters(&self, start: usize, byte_count: usize) -> usize {
         let end = start.saturating_add(byte_count).min(self.text_len());
         let mut at = start;
@@ -521,29 +371,19 @@ impl ClassMap {
         letters
     }
 
-    /// The whole string's letter count — `GetNumLetters`.
+    /// The whole string's letter count, `GetNumLetters`.
     pub fn num_letters(&self) -> usize {
         self.letters(0, self.text_len())
     }
 
-    /// Move the cursor `steps` token-steps from `from` — `0x77bb30`, the heart of the cursor model.
-    /// Negative `steps` walk backward. Returns the resulting byte offset (the client returns
-    /// the *magnitude* of the delta and its caller `0x77c6b0` signs it; same thing, one fewer trap).
+    /// The byte offset `steps` token steps from `from`, backward when negative: `0x77bb30`, whose
+    /// caller `0x77c6b0` signs its result. `atomic_links` is the keyboard's walk (arrows, word
+    /// jumps, HOME/END, BACKSPACE, DELETE), crossing a whole `|H…|h[text]|h` in one step; click,
+    /// drag, UP/DOWN, the scroll-window sizing and the IME span stop on each visible character.
     ///
-    /// `atomic_links` is the whole of the difference between the keyboard and the mouse: every
-    /// arrow, word-jump, HOME/END, BACKSPACE and DELETE path passes 1 and crosses a whole
-    /// `|H…|h[text]|h` in one step, while click, drag, UP/DOWN, the scroll-window sizing and the IME
-    /// span all pass 0 and stop on each visible character. Neither ever stops *inside* an escape.
-    ///
-    /// **The end-of-buffer guard is a deliberate divergence: the real client HANGS here.** Its inner
-    /// skip loop re-enters at `0x77bb60`, past the zero guard at `0x77bb56`, and the terminator slot
-    /// decodes as class 0 with length 0 — a class the loop skips unconditionally — so a walk still
-    /// skipping at the end of the buffer spins forever consuming no bytes. Confirmed by executing
-    /// `0x77bb30` under an emulation oracle. It is reachable: a trailing `|c` hangs in
-    /// both modes and an unclosed link hangs at `atomic_links = true`, so `SetText("|cffffffff")`
-    /// plus one RIGHT freezes 1.12.1. A user cannot type it (`|` becomes `||`) but any script can
-    /// set it. We bound the loop by the buffer and land the step on the far end instead —
-    /// reproducing a freeze is not fidelity.
+    /// Deviation: a step that runs out of buffer while skipping lands on the far end, because the
+    /// client spins forever there (its skip loop re-enters at `0x77bb60`, past the zero check at
+    /// `0x77bb56`), so `SetText("|cffffffff")` and one RIGHT hang 1.12.
     pub fn advance(&self, from: usize, steps: isize, atomic_links: bool) -> usize {
         let mut at = from;
         for _ in 0..steps.unsigned_abs() {
@@ -556,7 +396,7 @@ impl ClassMap {
         at
     }
 
-    /// One step forward — the inner loop at `0x77bb60`, then the post-step absorb at `0x77bb98`.
+    /// One step forward: the skip loop at `0x77bb60`, then the absorb at `0x77bb98`.
     fn step_forward(&self, from: usize, atomic_links: bool) -> usize {
         let end = self.text_len();
         let mut at = from;
@@ -564,21 +404,20 @@ impl ClassMap {
             let entry = self.entry(at);
             let Some(class) = entry.class() else { break };
             at += entry.byte_len();
-            // `|c` and `|H…|h` are skipped whatever the atomicity: a cursor never sits after a
-            // leading escape (`74 da` @`0x77bb84`, `74 d5` @`0x77bb86`).
+            // `|c` and `|H…|h` are skipped at either atomicity (`0x77bb84`, `0x77bb86`).
             if matches!(class, TokenClass::Color | TokenClass::LinkOpen) {
                 continue;
             }
             if !atomic_links {
-                break; // `84 db; 74 09` — one visible token consumed
+                break; // one visible token consumed
             }
             if !entry.in_link() {
-                break; // `85 d2; 79 05` — bit 31 clear
+                break; // bit 31 clear
             }
             if class == TokenClass::LinkClose {
-                break; // the close is what ends the atomic skip
+                break; // the close ends the atomic skip
             }
-            // Inside a link and not the close: keep skipping (`83 ff 05; 75 c8`) — the atomicity.
+            // Inside a link and not its close: keep skipping.
         }
         // Then absorb any immediately following `|r` / `|h`, so the cursor lands past them.
         while at < end
@@ -592,18 +431,17 @@ impl ClassMap {
         at
     }
 
-    /// One step backward — the mirror at `0x77bc13` / `0x77bc1d` / `0x77bc59`.
+    /// One step backward, the mirror (`0x77bc13`, `0x77bc1d`, `0x77bc59`).
     fn step_back(&self, from: usize, atomic_links: bool) -> usize {
         let mut at = from;
-        // Trailing `|r` / `|h` first (`83 fa 01; 74 ca` / `83 fa 05; 74 c5`).
+        // Trailing `|r` and `|h` first.
         while let Some(prev) = self.prev_token(at) {
             match self.entry(prev).class() {
                 Some(TokenClass::ColorReset | TokenClass::LinkClose) => at = prev,
                 _ => break,
             }
         }
-        // One token back — extended, when atomic, over the whole link to its class-4 open
-        // (`8a 5d 10; 84 db; 74 09; 85 f6; 79 05; 83 fa 04; 75 b5`).
+        // One token back, extended when atomic over the whole link to its open.
         while let Some(prev) = self.prev_token(at) {
             let entry = self.entry(prev);
             at = prev;
@@ -611,7 +449,7 @@ impl ClassMap {
                 break;
             }
         }
-        // Then back over any preceding `|c` / `|H` (`85 f6; 74 05; 83 fe 04; 75 08`).
+        // Then back over any preceding `|c` or `|H`.
         while let Some(prev) = self.prev_token(at) {
             match self.entry(prev).class() {
                 Some(TokenClass::Color | TokenClass::LinkOpen) => at = prev,
@@ -621,23 +459,11 @@ impl ClassMap {
         at
     }
 
-    /// Widen a half-open deletion range so it cannot cut a hyperlink in half — `0x77c510`,
-    /// called by BACKSPACE/DELETE (`0x77c280`), by delete-selection (`0x77cd70`) and by Clear
-    /// (`0x77c500`).
-    ///
-    /// If `start` is inside a link, walk back to the class-4 open and then over the whole preceding
-    /// `|c`/`|H` run; if `end` is inside a link, walk forward past the closing `|h` and any following
-    /// `|r`. So **any deletion touching any byte of a link removes the whole
-    /// `|c…|H…|h[text]|h|r` unit** — a second, independent guarantee on top of the atomic walk, and
-    /// what makes even a mouse-drag partial selection delete cleanly.
-    ///
-    /// Two faithfully-kept edges. The endpoint tests read `classArr[start]` / `classArr[end]`
-    /// directly (`83 3c 96 00; 79 50` @`0x77c543`, `83 3c 86 00; 79 55` @`0x77c59d`), so an *end*
-    /// that merely abuts a link's first byte — the byte it does not include — still widens; and the
-    /// backward walk stops on class 0 as well as class 4 (both `jz`s @`0x77c550` land on the same
-    /// target), so a `|c` sitting *inside* a link's visible text ends it early. 1.12 content puts the
-    /// colour outside the link (`0x52adb0`'s `"%s|Hitem:%d:%d:%d:%d|h[%s]|h%s"`), so the second edge
-    /// is unreachable in practice; it is recorded rather than smoothed away.
+    /// Widen a deletion range so it never cuts a hyperlink: `0x77c510`, for BACKSPACE and DELETE
+    /// (`0x77c280`), delete-selection (`0x77cd70`) and Clear (`0x77c500`). Touching any byte of a
+    /// link removes the whole `|c…|H…|h[text]|h|r` unit. The endpoint tests read the entries at
+    /// `start` and `end` (`0x77c543`, `0x77c59d`), so an end that only abuts a link's `|H` still
+    /// widens, and the backward walk also stops on a `|c` inside the link text (`0x77c550`).
     pub fn snap_delete_range(&self, range: Range<usize>) -> Range<usize> {
         let Range {
             start: mut lo,
@@ -679,22 +505,16 @@ impl ClassMap {
         lo..hi
     }
 
-    /// May text be inserted at `at`? — the opening guard of `0x77bee0`.
-    ///
-    /// Refused exactly when the entry at the cursor carries bit 31 **and** the previous token's entry
-    /// carries it too (`79 16` @`0x77befb`, `0f 88 …` @`0x77bf0d`). That second test is what still
-    /// permits an insert *at* a link's leading edge, where the `|H` entry has the bit but its
-    /// predecessor — the `|c`, or whatever precedes it — does not.
-    ///
-    /// A strictly-interior cursor is reachable only by mouse (`0x77d0d0`, `atomic_links = 0`), and
-    /// the client then silently swallows the typing — inferred from the verified guard, not
-    /// independently confirmed.
+    /// The opening guard of `0x77bee0`: refused when the entry at the cursor and the previous
+    /// token's both carry bit 31 (`0x77befb`, `0x77bf0d`), so a link's leading edge still accepts.
+    /// Only the mouse (`0x77d0d0`) reaches a cursor inside a link, and the client then drops the
+    /// typing (inferred from the guard).
     pub fn insert_allowed(&self, at: usize) -> bool {
         if !self.entry(at).in_link() {
             return true;
         }
         match self.prev_token(at) {
-            // `85 c0; 7e 12` — cursor <= 0 proceeds.
+            // Cursor 0 proceeds.
             None => true,
             Some(prev) => !self.entry(prev).in_link(),
         }
@@ -705,7 +525,7 @@ impl ClassMap {
 mod tests {
     use super::*;
 
-    /// An epic item link exactly as `0x52adb0` formats one.
+    /// An epic item link as `0x52adb0` formats one.
     ///
     /// ```text
     ///  0        10                  30            44  46
@@ -714,7 +534,7 @@ mod tests {
     /// ```
     const LINK: &str = "|cffa335ee|Hitem:12345:0:0:0|h[Chipped Claw]|h|r";
 
-    /// The same link with ordinary text on both sides — every offset above shifted by 2.
+    /// The same link between ordinary text, every offset shifted by 2.
     const AROUND: &str = "ab|cffa335ee|Hitem:12345:0:0:0|h[Chipped Claw]|h|rcd";
 
     fn kinds(text: &str) -> Vec<(usize, TokenKind<'_>, usize)> {
@@ -741,7 +561,7 @@ mod tests {
             assert_eq!(one(reset).byte_len, 2);
         }
 
-        // All four spellings of class 2, and `\r\n` as ONE token rather than two.
+        // Every spelling of class 2, `\r\n` as one token.
         for (text, len) in [("\n", 1), ("\r", 1), ("\r\n", 2), ("|n", 2), ("|N", 2)] {
             assert_eq!(one(text).kind, TokenKind::LineBreak, "{text:?}");
             assert_eq!(one(text).byte_len, len, "{text:?}");
@@ -787,8 +607,7 @@ mod tests {
 
     #[test]
     fn there_is_no_inline_texture_escape_in_1_12_1() {
-        // `|T…|t` is a later-expansion feature. Here every byte of it is an ordinary character —
-        // the pipes draw, and a client that stripped the run would be inventing a 2.x escape.
+        // `|T…|t` is a later client's escape; in 1.12 every byte of it is an ordinary character.
         let text = "|TInterface\\Icons\\Foo:16:16|t";
         let first = token_at(text, 0).expect("a token");
         assert_eq!(first.kind, TokenKind::Char('|'));
@@ -797,7 +616,6 @@ mod tests {
             token_at(text, 1).expect("a token").kind,
             TokenKind::Char('T')
         );
-        // Nothing in the whole run is anything but an ordinary character.
         assert!(tokens(text).all(|(_, t)| t.class() == TokenClass::Char));
     }
 
@@ -824,8 +642,7 @@ mod tests {
         };
         assert_eq!(rgba.a(), 0xff);
         assert_eq!(rgba.packed(), 0xffff_0000);
-        // The alpha that reaches the vertex is the STRING's, never the escape's: `|c00ff0000`
-        // inside a half-faded FontString draws at 0.5, not 0.0 and not 1.0 (`0x5cceb0`).
+        // The string's alpha reaches the vertex, never the escape's (`0x5cceb0`).
         assert_eq!(rgba.to_f32_at(1.0), [1.0, 0.0, 0.0, 1.0]);
         assert_eq!(rgba.to_f32_at(0.5), [1.0, 0.0, 0.0, 0.5]);
     }
@@ -840,13 +657,13 @@ mod tests {
         // 1. No closing `|h` anywhere after it.
         degraded("|Hitem:12345:0:0:0[Chipped Claw]");
         degraded("|H");
-        // 2. The span is exactly 4 bytes — an empty payload (0x5c2972).
+        // 2. An empty payload (0x5c2972).
         degraded("|H|h[Chipped Claw]|h");
-        // 3. The visible text is empty — another `|h` immediately follows the span (0x5c2992).
+        // 3. Empty visible text: another `|h` follows at once (0x5c2992).
         degraded("|Hitem:12345:0:0:0|h|h");
 
-        // And the near-misses that must still parse: one visible character is enough, and an
-        // unterminated *link* (delimiter present, no close) still opens — the decoder is stateless.
+        // Near misses still open: one visible character is enough, and the stateless decoder
+        // opens a link that never closes.
         assert_eq!(
             token_at("|Hitem:1|h[|h", 0).expect("a token").kind,
             TokenKind::LinkOpen { payload: "item:1" }
@@ -870,7 +687,7 @@ mod tests {
         }
         assert_eq!(next, AROUND.len());
 
-        // The link buffer's shape, spelled out — every index the rest of these tests cite.
+        // The link's shape: every index the other tests cite.
         let ks = kinds(LINK);
         assert_eq!(ks[0].0, 0);
         assert_eq!(ks[0].2, 10);
@@ -898,8 +715,7 @@ mod tests {
         let map = ClassMap::new(LINK);
         for at in 0..=map.text_len() {
             let entry = map.entry(at);
-            // Raised on the class-4 open (10) inclusive, lowered only after the class-5 close, whose
-            // own entry (44) is therefore still tagged. The `|r` at 46 is not.
+            // Set from the open at 10 through the close at 44; the `|r` at 46 is outside.
             let expected = entry.is_token_start() && (10..=44).contains(&at);
             assert_eq!(entry.in_link(), expected, "bit 31 at {at}");
         }
@@ -931,7 +747,6 @@ mod tests {
         assert_eq!(map.next_token(10), 30);
         assert_eq!(map.next_token(44), 46);
         assert_eq!(map.next_token(46), 48);
-        // A fixed point at the terminator, exactly like the client's unguarded add.
         assert_eq!(map.next_token(48), 48);
 
         assert_eq!(map.prev_token(48), Some(46));
@@ -953,7 +768,7 @@ mod tests {
         assert_eq!(map.letters(30, 14), 14, "the visible text alone");
         assert_eq!(map.letters(44, 4), 0, "the |h|r tail");
 
-        // A line break and an escaped pipe are each ONE letter; `\r\n` is one, not two.
+        // A line break and an escaped pipe are one letter each; `\r\n` is one.
         let map = ClassMap::new("a||b\r\nc|nd");
         assert_eq!(map.num_letters(), 7);
         assert_eq!(ClassMap::new(AROUND).num_letters(), 18, "14 + `ab` + `cd`");
@@ -962,19 +777,9 @@ mod tests {
 
     // ── The cursor law ───────────────────────────────────────────────────────────────────────
 
-    /// Cursor 0, one RIGHT, and the whole link is behind you.
-    /// **The oracle cross-check.** The real `0x77bb30` was *executed* under Unicorn on this exact
-    /// buffer, reporting the reachable index sets below verbatim — the strongest evidence this
-    /// module can carry, because they came from the binary running rather than from anyone reading
-    /// it.
-    ///
-    /// Three things the cross-check pins that a reading could plausibly have got backwards: index
-    /// **0 is** reachable (the leading `|c`+`|H…|h` absorb into the first *step*, not off the
-    /// origin); index **30 is reachable in neither mode** — classes 0 and 4 are skipped
-    /// unconditionally, so a step arriving from the left consumes the `[` in the same step, and the
-    /// cursor can never sit between `|h` and `[`; and after the name the stop is **43 in both
-    /// modes**, never 39 or 41, because the trailing `|h|r` absorb **forward** rather than backward
-    /// onto the `]`.
+    /// The reachable sets the reference's `0x77bb30` produced, executed on this buffer: 30, between
+    /// `|h` and `[`, is reachable in neither mode, and after the name the stop is 43 in both, the
+    /// trailing `|h|r` absorbing forward.
     #[test]
     fn the_reachable_sets_match_the_emulation_oracle() {
         // `[` at 30, `]` at 38, the `d` of the typed text at 43; 51 bytes.
@@ -1000,7 +805,6 @@ mod tests {
             }
             assert_eq!(forward, expected, "forward, atomic={atomic}");
 
-            // Backward visits the identical set and returns exactly to 0.
             let mut back = vec![BUF.len()];
             let mut at = BUF.len();
             while at > 0 {
@@ -1013,24 +817,18 @@ mod tests {
             assert_eq!(back, expected, "backward, atomic={atomic}");
         }
 
-        // The refusal predicate, over every offset: exactly 30..=39 — the display text through the
-        // FIRST byte of the closing `|h`. The link's own boundaries accept (10, the `|H` slot, and
-        // 41, the `|r`), and so does 40, a token-interior byte whose slot is zero.
+        // Insertion is refused at exactly 30..=39, the text through the first byte of the closing
+        // `|h`; 40 is that token's zero interior slot.
         let refused: Vec<usize> = (0..=BUF.len())
             .filter(|&i| !map.insert_allowed(i))
             .collect();
         assert_eq!(refused, (30..=39).collect::<Vec<_>>());
     }
 
-    /// The client freezes where we stop: its inner skip loop re-enters at `0x77bb60`, past the zero
-    /// guard at `0x77bb56`, and the terminator decodes as a skip class, so a buffer whose last
-    /// token is `|c` — or an unclosed link, when atomic — spins forever. `SetText("|cffffffff")`
-    /// plus one RIGHT hangs 1.12.1. We land on the far end instead; reproducing a freeze is not
-    /// fidelity.
+    /// A buffer ending in `|c`, or in an unclosed link when atomic, where the client spins forever.
     #[test]
     fn a_trailing_escape_lands_on_the_end_where_the_client_would_hang() {
-        // Each entry is (buffer, the offset where only skip-class tokens remain, whether the
-        // non-atomic walk hangs there too — an unclosed link only traps the atomic one).
+        // (buffer, offset where only skip-class tokens remain, whether the client hangs non-atomic)
         for (buf, from, both_modes) in [
             ("|cffffffff", 0, true),
             ("ab|cffffffff", 2, true),
@@ -1053,8 +851,7 @@ mod tests {
             "past the whole link, not into it"
         );
         assert_eq!(map.advance(48, -1, true), 0, "and back again");
-        // Not ~50 presses: the visible text is 14 characters and the buffer is 48 bytes, yet the
-        // atomic walk has exactly two stops.
+        // The atomic walk has exactly two stops in the 48 bytes.
         assert_eq!(map.advance(0, 5, true), 48, "clamped at the end");
         assert_eq!(map.advance(48, -5, true), 0);
 
@@ -1068,8 +865,8 @@ mod tests {
         assert_eq!(map.advance(50, -1, true), 2, "back over the whole unit");
     }
 
-    /// The mouse path (`atomic_links = 0`, `0x77d2f6`): every visible character is its own stop, and
-    /// no index inside `|cffa335ee`, `|Hitem:…|h`, `|h` or `|r` ever is.
+    /// The mouse path (`0x77d2f6`): every visible character is a stop, and no index inside
+    /// `|cffa335ee`, `|Hitem:…|h`, `|h` or `|r` ever is.
     #[test]
     fn a_non_atomic_walk_stops_on_each_visible_character_and_never_inside_an_escape() {
         let map = ClassMap::new(LINK);
@@ -1086,7 +883,6 @@ mod tests {
         let expected: Vec<usize> = std::iter::once(0).chain(31..=43).chain([48]).collect();
         assert_eq!(stops, expected);
 
-        // And the same set walking back.
         let mut at = map.text_len();
         let mut back = vec![at];
         while at > 0 {
@@ -1096,7 +892,6 @@ mod tests {
         back.reverse();
         assert_eq!(back, expected);
 
-        // Spelled out: no stop lands inside any escape's byte span.
         for &stop in &stops {
             assert!(
                 !(1..10).contains(&stop)
@@ -1112,8 +907,7 @@ mod tests {
         }
     }
 
-    /// The canonical reachable set (`0x77bb30`): **a token boundary with every adjacent zero-width
-    /// escape absorbed — after any trailing `|r`/`|h`, before any leading `|c`/`|H`.**
+    /// The reachable set (`0x77bb30`): boundaries not before a `|r`/`|h` nor after a `|c`/`|H`.
     fn reachable_set(text: &str) -> Vec<usize> {
         let map = ClassMap::new(text);
         (0..=map.text_len())
@@ -1138,9 +932,8 @@ mod tests {
             .collect()
     }
 
-    /// The property sweep: whatever sequence of steps you take, in either direction, at either
-    /// atomicity, you can only ever land in the set above — so no index inside an escape is
-    /// representable as a cursor position. And non-atomically the whole set is reachable.
+    /// Any walk, either way, at either atomicity, lands only in the reachable set, and the walks
+    /// reach all of it.
     #[test]
     fn every_index_any_walk_can_reach_is_a_boundary_with_its_escapes_absorbed() {
         for text in [LINK, AROUND] {
@@ -1177,9 +970,8 @@ mod tests {
         }
     }
 
-    /// The two degenerate ends the guard owns: a step that runs out of buffer while skipping escapes
-    /// lands on the far end rather than spinning (ours, not the reference's — see
-    /// [`ClassMap::advance`]).
+    /// A step that runs out of buffer while skipping lands on the far end, the deviation on
+    /// [`ClassMap::advance`].
     #[test]
     fn a_step_that_runs_out_of_buffer_lands_on_the_far_end() {
         let map = ClassMap::new("ab|cffff0000");
@@ -1192,7 +984,6 @@ mod tests {
         let map = ClassMap::new("|rab");
         assert_eq!(map.advance(2, -1, true), 0, "nothing precedes the |r");
         assert_eq!(map.advance(0, 1, true), 2);
-        // And at the extremes nothing moves.
         let map = ClassMap::new(LINK);
         assert_eq!(map.advance(0, -1, true), 0);
         assert_eq!(map.advance(48, 1, true), 48);
@@ -1204,8 +995,7 @@ mod tests {
     #[test]
     fn deleting_any_byte_of_a_link_widens_to_the_whole_unit() {
         let map = ClassMap::new(AROUND);
-        // Anything touching the visible text takes the |c, the |H…|h, the |h and the |r with it,
-        // leaving exactly `abcd`.
+        // Touching the visible text takes the whole `|c…|r` unit, leaving `abcd`.
         for range in [33..38, 32..46, 33..34, 2..40, 12..46] {
             let snapped = map.snap_delete_range(range.clone());
             assert_eq!(snapped, 2..50, "{range:?}");
@@ -1222,31 +1012,28 @@ mod tests {
         assert_eq!(map.snap_delete_range(35..52), 2..52);
     }
 
-    /// The endpoint tests read the class array directly, so an exclusive end that merely abuts the
-    /// link's first tagged byte still widens. Faithful to `83 3c 86 00` @`0x77c59d`.
+    /// An exclusive end on the link's first tagged byte still widens (`0x77c59d`).
     #[test]
     fn a_deletion_ending_on_the_links_open_still_takes_the_link() {
         let map = ClassMap::new(AROUND);
         assert_eq!(map.snap_delete_range(0..12), 0..50);
-        // Whereas ending on the `|c` — which is not tagged — does not.
+        // Ending on the untagged `|c` does not.
         assert_eq!(map.snap_delete_range(0..2), 0..2);
     }
 
     #[test]
     fn insertion_is_refused_strictly_inside_a_links_visible_text() {
         let map = ClassMap::new(LINK);
-        // Everywhere outside the link.
         assert!(map.insert_allowed(0), "before the leading |c");
         assert!(map.insert_allowed(46), "between the |h and the |r");
         assert!(map.insert_allowed(48), "at the end of the buffer");
         // The leading edge: the |H entry carries bit 31, its predecessor the |c does not.
         assert!(map.insert_allowed(10), "at the link's leading edge");
-        // Strictly inside: refused at every byte from the first visible character through the
-        // closing |h, whose entry is still tagged.
+        // Refused from the first visible character through the tagged closing |h.
         for at in 30..=44 {
             assert!(!map.insert_allowed(at), "inside the link at {at}");
         }
-        // And in particular at every cursor position a mouse click can actually produce.
+        // Including every position a mouse click can produce.
         for at in reachable_set(LINK) {
             assert_eq!(
                 map.insert_allowed(at),
@@ -1265,12 +1052,10 @@ mod tests {
 
     #[test]
     fn no_primitive_can_return_an_index_inside_a_character() {
-        // Multi-byte text before, inside and after the link — 2- and 3-byte characters throughout.
         let text = "héllo |cffa335ee|Hitem:1:0:0:0|h[Épée ✚]|h|r né";
         let map = ClassMap::new(text);
         assert_eq!(map.text_len(), text.len());
 
-        // Every token start, and every index any primitive yields, is a character boundary.
         for (at, token) in tokens(text) {
             assert!(text.is_char_boundary(at), "token start {at}");
             assert!(text.is_char_boundary(at + token.byte_len), "token end {at}");
@@ -1295,17 +1080,14 @@ mod tests {
             let snapped = map.snap_delete_range(at..map.text_len());
             assert!(text.is_char_boundary(snapped.start));
             assert!(text.is_char_boundary(snapped.end));
-            // `String::replace_range` panics unless both ends are character boundaries, so a
-            // snapped range that cut a character in half fails here rather than corrupting.
+            // `replace_range` panics on a range that cuts a character.
             let mut left = text.to_owned();
             left.replace_range(snapped, "");
         }
 
-        // The multi-byte characters are letters like any other: `héllo ` = 6, `[Épée ✚]` = 8,
-        // ` né` = 3.
+        // One letter per character: `héllo ` 6, `[Épée ✚]` 8, ` né` 3.
         assert_eq!(map.num_letters(), 17);
-        // And an atomic step still crosses the whole link in one, from `héllo `'s end to ` né`'s
-        // start, whatever the byte widths in between.
+        // One atomic step still crosses the whole link.
         let open = text.find("|cffa335ee").expect("the colour push");
         let after = text.find("|r").expect("the reset") + 2;
         assert_eq!(map.advance(open, 1, true), after);
diff --git a/crates/benilla-ui/src/messages.rs b/crates/benilla-ui/src/messages.rs
index fa1a1131..4dfc3d4a 100644
--- a/crates/benilla-ui/src/messages.rs
+++ b/crates/benilla-ui/src/messages.rs
@@ -1,108 +1,60 @@
-//! The client's **message catalog** — the one table that decides where a UI message is shown.
-//!
-//! Every user-visible refusal, notice and confirmation the engine raises goes through a single
-//! function, `CGGameUI::DisplayError` (`0x496720`), which takes a **message id** and nothing else.
-//! The id indexes the registry at `0xb4b498`, 465 records of 20 bytes:
-//!
-//! | offset | field | what it is |
-//! |---|---|---|
-//! | `+0x00` | [`MessageRecord::key`] | the `GlobalStrings.lua` key, resolved by `FrameScript_GetText` |
-//! | `+0x04` | [`MessageRecord::kind`] | **where it goes** — the four-way jump at `0x496888` ([`MsgKind`]) |
-//! | `+0x08` | [`MessageRecord::sound`] | a sound cue name, or nothing |
-//! | `+0x0c` | [`MessageRecord::type_tag`] | `0x44` = play the cue; anything else is an error-speech id |
-//! | `+0x10` | [`MessageRecord::chat_type`] | the chat type handed to `0x49a870` — read on [`MsgKind::Chat`] only |
-//!
-//! **Why this table is in the tree at all.** benilla names ~160 of these keys across a dozen
-//! modules, and until now every one of them arrived by hand-tracing a `push <id>; call 0x496720`
-//! in the binary and reading the record by eye — the key *and* the surface, carried separately to
-//! the call site, with nothing checking they agreed. That is how [`super::script`]'s petition lines
-//! got their split wrong on the first try (`ui_petition::lines`' own module doc records it), and
-//! it is a tax on every future message. The registry is a **fact about the client**, of exactly the
-//! kind this project already carries as code — opcode numbers, struct offsets, DBC schemas — so it
-//! belongs here as a table, once, instead of being re-derived per call site. Nothing localized
-//! ships with it: the *keys* are `GlobalStrings.lua` identifiers (interface code, decision 1602)
-//! and the text itself is still read at runtime out of the player's own install.
-//!
-//! It is **generated**, never hand-edited — `scripts/gen-message-catalog.py` from the vendored
-//! `reference/1.12-message-catalog.tsv`, extracted by decoding the CRT static initializer
-//! `[0x484ca0, 0x488408)` that fills the table.
-//!
-//! **What the sweep settles that guessing could not:** the split does not follow the key names.
-//! `ERR_PETITION_SIGNED_S` is a chat line and `ERR_PETITION_ALREADY_SIGNED` is a red toast;
-//! `ERR_FISH_ESCAPED` is yellow and `ERR_INV_FULL` is red. 170 rows are [`MsgKind::Chat`], 28 are
-//! [`MsgKind::Info`], 267 are [`MsgKind::Error`] — and **none is the console arm**, which the
-//! dispatcher has and this build's table never reaches (`0x63cb50`'s console lines are called
-//! directly, not through a record), so [`MsgKind`] models three.
+//! The client's message catalog: `CGGameUI::DisplayError` (`0x496720`) takes only a message id,
+//! and the id's 20-byte record in the 465-row table at `0xb4b498` names the `GlobalStrings.lua`
+//! key, where it is shown and its sound. The rows are generated by
+//! `scripts/gen-message-catalog.py` from `reference/1.12-message-catalog.tsv`, decoded from the
+//! table's static initializer `[0x484ca0, 0x488408)`; the text itself is read from the install.
 
 mod catalog;
 
 pub use catalog::CATALOG;
 
-/// Where a message is shown — the record's `+0x04`, as the four-way jump at `0x496888` reads it.
-///
-/// The reference's fourth arm (`3` → the debug console `0x63cd00`) has **no tenant in 5875's
-/// table**: no row carries it, so modelling it would be modelling something that cannot happen.
-/// The generator refuses a kind it does not know, so a build whose table did use it would fail
-/// loudly here rather than silently pick a surface.
+/// Where a message is shown: the record's `+0x04`, as the jump at `0x496888` reads it. Its fourth
+/// arm, `3` (the console `0x63cd00`), has no row in this build's table (console lines call
+/// `0x63cb50` directly), and the generator refuses a kind it does not know.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum MsgKind {
-    /// `0` → the chat window, through the shared composer `0x49a870` with the record's own
-    /// [`MessageRecord::chat_type`].
+    /// `0`: a chat-window line through the composer `0x49a870`, on the record's `chat_type`.
     Chat,
-    /// `1` → `AddErrorMessage(text, 0)`, which fires `UI_INFO_MESSAGE` (`0xe1`) — the **yellow**
-    /// `UIErrorsFrame` line.
+    /// `1`: `AddErrorMessage(text, 0)`, `UI_INFO_MESSAGE` (`0xe1`), yellow in `UIErrorsFrame`.
     Info,
-    /// `2` → `AddErrorMessage(text, 1)`, which fires `UI_ERROR_MESSAGE` (`0xe0`) — the **red**
-    /// `UIErrorsFrame` line. The commonest by a wide margin, which is exactly why guessing it
-    /// usually works and is not good enough.
+    /// `2`: `AddErrorMessage(text, 1)`, `UI_ERROR_MESSAGE` (`0xe0`), red in `UIErrorsFrame`.
     Error,
 }
 
 /// One row of `0xb4b498`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct MessageRecord {
-    /// The message id — the argument `DisplayError` is called with, and this row's index.
+    /// The id `DisplayError` takes, and this row's index.
     pub id: u16,
-    /// The `GlobalStrings.lua` key whose text is displayed. An absent or empty string shows
-    /// nothing at all: the reference's own data-suppression face (`0x4967bd`/`0x4967c5`).
+    /// `+0x00`, the `GlobalStrings.lua` key; an absent or empty string shows nothing
+    /// (`0x4967bd`/`0x4967c5`).
     pub key: &'static str,
-    /// Where it is shown.
+    /// `+0x04`, where it is shown.
     pub kind: MsgKind,
-    /// The sound cue played with it, or `None` for the 435 silent rows. Read at the display, by
-    /// `benilla_app::sound::message` (decision 1815).
+    /// `+0x08`, the sound cue; `None` on the 435 silent rows.
     pub sound: Option<&'static str>,
-    /// `+0x0c`. `0x44` means "play [`Self::sound`]"; the other 56 rows carry an error-speech line
-    /// id instead, spoken in the player's own race and gender voice (decision 1815).
+    /// `+0x0c`: `0x44` plays [`Self::sound`]; the other 56 rows carry an error-speech id, spoken
+    /// in the player's race and gender voice.
     pub type_tag: u8,
-    /// The chat type handed to the composer, meaningful for [`MsgKind::Chat`] rows only. `10`
-    /// (`CHAT_MSG_SYSTEM`) for all but three — the skill-up trio `ERR_PROFICIENCY_GAINED_S`,
-    /// `ERR_SKILL_GAINED_S` and `ERR_SKILL_UP_SI` speak on `23` (`CHAT_MSG_SKILL`).
+    /// `+0x10`, read on [`MsgKind::Chat`] rows only: `10` (`CHAT_MSG_SYSTEM`), except `23`
+    /// (`CHAT_MSG_SKILL`) on the skill-up rows `ERR_PROFICIENCY_GAINED_S`, `ERR_SKILL_GAINED_S`
+    /// and `ERR_SKILL_UP_SI`.
     pub chat_type: u8,
 }
 
-/// The record for a message id, or `None` past the table's end — the reference's own bound, the
-/// `cmp id,0x1d1; jge` at `0x49672c`.
+/// The record for a message id; the table ends at the reference's bound, `cmp id,0x1d1` at
+/// `0x49672c`.
 pub fn by_id(id: u16) -> Option<&'static MessageRecord> {
     CATALOG.get(usize::from(id))
 }
 
-/// The record for a `GlobalStrings` key. Keys are unique across the table (the generator refuses a
-/// duplicate), so this is well defined.
-///
-/// A linear scan, deliberately: this is reached once per *displayed message* — a toast, a system
-/// line — which is a handful per second at the very worst, and a sorted side-table would be one
-/// more generated thing to keep true for no measurable gain.
+/// The record for a `GlobalStrings` key; keys are unique (the generator refuses a duplicate).
 pub fn by_key(key: &str) -> Option<&'static MessageRecord> {
     CATALOG.iter().find(|r| r.key == key)
 }
 
-/// Where a message goes, by key — the one question nearly every caller has.
-///
-/// A key with no row falls back to [`MsgKind::Error`]. That case cannot arise in the reference (a
-/// message is an *index*, so an unknown key is not expressible), so it only ever means benilla
-/// named a key the client does not have; the red line is both the commonest kind and the most
-/// visible place for such a mistake to show itself. `benilla-app`'s
-/// `every_error_key_in_the_source_is_a_catalog_row` test is what keeps it unreachable.
+/// Where a message goes, by key. A key with no row is a benilla typo, never a reference state
+/// (the reference addresses messages by index), and falls back to the red line.
 pub fn kind_of(key: &str) -> MsgKind {
     by_key(key).map_or(MsgKind::Error, |r| r.kind)
 }
@@ -111,7 +63,6 @@ pub fn kind_of(key: &str) -> MsgKind {
 mod tests {
     use super::*;
 
-    /// The table is complete and dense, so `CATALOG[id]` is the reference's own addressing.
     #[test]
     fn ids_are_dense_and_the_table_is_whole() {
         assert_eq!(CATALOG.len(), 465);
@@ -121,7 +72,6 @@ mod tests {
         assert!(by_id(465).is_none(), "the reference bounds at 0x1d1");
     }
 
-    /// Keys are unique — [`by_key`] would otherwise be answering an ambiguous question.
     #[test]
     fn keys_are_unique() {
         let mut keys: Vec<&str> = CATALOG.iter().map(|r| r.key).collect();
@@ -131,9 +81,6 @@ mod tests {
         assert_eq!(keys.len(), n);
     }
 
-    /// **The split does not follow the key names.** Four rows that a re-implementation reading
-    /// English would sort differently than the binary does — the petition pair that was actually
-    /// got wrong once, and the fishing verdict that sits one id away from two red neighbours.
     #[test]
     fn the_surface_is_not_guessable_from_the_key() {
         assert_eq!(kind_of("ERR_PETITION_SIGNED_S"), MsgKind::Chat);
@@ -142,7 +89,6 @@ mod tests {
         assert_eq!(kind_of("ERR_INV_FULL"), MsgKind::Error);
     }
 
-    /// The three rows that speak on a chat type other than `CHAT_MSG_SYSTEM`.
     #[test]
     fn the_skill_up_rows_speak_on_chat_msg_skill() {
         for key in [
@@ -157,8 +103,6 @@ mod tests {
         assert_eq!(by_key("ERR_QUEST_ALREADY_ON").unwrap().chat_type, 10);
     }
 
-    /// A key the client does not have is not expressible as a message id; the fallback exists so
-    /// that a benilla typo is loud rather than silent.
     #[test]
     fn an_unknown_key_falls_back_to_the_red_line() {
         assert!(by_key("ERR_NOT_A_REAL_MESSAGE").is_none());
diff --git a/crates/benilla-ui/src/order.rs b/crates/benilla-ui/src/order.rs
index e8459c90..db089796 100644
--- a/crates/benilla-ui/src/order.rs
+++ b/crates/benilla-ui/src/order.rs
@@ -1,91 +1,48 @@
-//! The draw-order primitive — the strata/layer vocabulary and the packed total-order key
-//! (`ZKey`), plus the visible-tree [`traversal`] that realizes the client's painter order
-//! (decision 0068).
+//! Draw order: the strata and draw-layer vocabulary, the packed total-order key [`ZKey`], and the
+//! visible-tree [`traversal`] in the client's painter order.
 //!
-//! ## Ground truth
+//! The 1.12 client draws in one flat painter's order, not a tree walk: every visible frame, child
+//! or not, is an entry in a per-`(strata, level)` bucket (`root+0xcd4`), so a child with a lower
+//! strata or level draws before its parent. Inside a bucket the draw layer outranks the frame: the
+//! five layer batches belong to the level node (`levelNode+0x1c`), and the emitter `0x765920` loops
+//! layers outside and frames inside, so every frame's BACKGROUND draws before any frame's BORDER.
+//! Within a layer, `0x76fb00` drains every quad, then every string, then the render callbacks.
 //!
-//! The 1.12.1 client draws in a **flat painter's order**, *not* a hierarchical walk: every visible
-//! frame — children included — is an independent entry in a per-`(strata, level)` bucket
-//! (`root+0xcd4`). A child frame with a *lower* strata/level than its
-//! parent therefore draws *before* the parent — the order is global, keyed on the tuple below, not
-//! on the tree shape.
+//! The frame term is the client's live intrusive-list position: a frame relinks at its bucket's
+//! tail when shown and when a shown frame's strata or level changes, and the later link draws on
+//! top. [`crate::widget::WidgetArena`] keeps a counter bumped at those moments, which orders the
+//! same within a bucket. The is-region bit is benilla's: the client has no frame drawable, and the
+//! frame's own slot (backdrop, scissor) must precede its regions.
 //!
-//! **Inside one `(strata, level)` bucket, the DRAW LAYER outranks the frame.** The five render
-//! batches belong to the level node (`levelNode+0x1c`), not to any frame, and the emitter
-//! `0x765920` loops `layer = 0..4` outside and frames inside. So a bucket emits every frame's
-//! BACKGROUND, then every frame's BORDER, and so on — regions are *not* grouped behind their owning
-//! frame. Within one layer the same is true of kind: the batch holds a quad sub-array and a text
-//! sub-array, and `0x76fb00` drains all quads before any text, so **all** textures of a
-//! `(strata, level, layer)` precede **all** its font strings (decision 0884).
-//!
-//! ## The total order (most- to least-significant)
-//!
-//! `(stratum, frame level, draw layer, batch rank quad<text<callback, frame link-stamp, is-region,
-//! sub-level, declaration order)` — packed big-endian-by-priority into one sortable [`ZKey`] (`u64`), so the
-//! whole render list is produced by one sort on the key. The `is-region` bit is benilla's own: the
-//! binary has no frame-level drawable (only regions draw), so it sits *below* the layer key purely
-//! to keep a frame's backdrop/scissor slot ahead of that frame's own regions.
-//!
-//! The **link-stamp** is the client's live intrusive-list position, not a creation index: a frame is
-//! (re)linked at its bucket on becoming visible, on a strata change, and on a *changing* level set
-//! — later link = drawn on top. A monotonic global counter bumped at those same moments is
-//! order-equivalent within any one bucket, which is what [`crate::widget::WidgetArena`] keeps.
-//!
-//! **Below the layer, the frame term is exact for font strings and a deterministic stand-in for
-//! textures.** The client re-sorts each layer's quad array by *texture handle* (`0x7731a0`) and
-//! never sorts the text sub-array. A texture handle is an internal allocation our texture manager
-//! assigns differently, so we reproduce the client's pre-sort array instead — identical wherever a
-//! layer's quads share a texture or don't overlap. **No content may depend on the relative order of
-//! two overlapping textures within one layer.**
-//!
-//! ## Era deltas (designed-for, not invented)
-//!
-//! - **`BLIZZARD` stratum** — the modern engine adds exactly one stratum *above* `TOOLTIP`
-//!   (decision 0068 §"strict superset"; the 1.12 `UI.xsd`↔Era diff). It is the last [`Strata`]
-//!   variant; 1.12 content never selects it.
-//! - **`textureSubLevel`** — an i8 ordering knob *within* a draw layer, first-class in Era. There
-//!   is **no sub-level in 5875 at all** (`0x76a860` takes only `(region, layer)` and head-inserts
-//!   with no comparator; the per-layer header is a plain 0xc-byte triple with nowhere to keep a
-//!   sort key). The `sub_level` field stays as the Era delta and is inert for 1.12 content.
+//! Deviation: textures in one layer keep link order where the client sorts them by texture handle
+//! (`0x7731a0`, comparator `0x7731c0`), because benilla allocates its handles differently; no
+//! content may depend on the order of two overlapping textures in one layer.
 
 use crate::widget::{FrameHandle, RegionHandle, RegionKind, WidgetArena};
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Strata — the top-level draw buckets
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Strata: the top-level draw buckets ───────────────────────────────────────────────────────
 
-/// The frame strata, in draw order (low → high). Variants 0..=8 are the client's nine
-/// buckets, byte-verified in the `CSimpleTop` ctor's 9-loop (`0x764180`): WORLD, BACKGROUND,
-/// LOW, MEDIUM (the default, id 3), HIGH, DIALOG, FULLSCREEN, FULLSCREEN_DIALOG, TOOLTIP. `BLIZZARD`
-/// (id 9) is the one stratum the modern engine adds *above* TOOLTIP (decision 0068) — an
-/// extension point, never selected by 1.12 content.
+/// The frame strata in draw order; `World` through `Tooltip` are the client's nine buckets (the
+/// `CSimpleTop` constructor's loop at `0x764180`).
 #[repr(u8)]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum Strata {
-    /// id 0 — behind everything (the 3D world layer).
+    /// The 3D world, behind everything.
     World = 0,
-    /// id 1.
     Background = 1,
-    /// id 2.
     Low = 2,
-    /// id 3 — the client default (`frameStrata` ctor value `3` at `0x7690c2`).
     Medium = 3,
-    /// id 4.
     High = 4,
-    /// id 5.
     Dialog = 5,
-    /// id 6.
     Fullscreen = 6,
-    /// id 7.
     FullscreenDialog = 7,
-    /// id 8 — topmost in 1.12.
     Tooltip = 8,
-    /// id 9 — **Era addition**, drawn above `Tooltip` (decision 0068). No 1.12 content uses it.
+    /// A later client's stratum above `Tooltip`, not a 1.12 one.
     Blizzard = 9,
 }
 
 impl Strata {
-    /// Every stratum in draw order (low → high).
+    /// Every stratum in draw order.
     pub const ALL: [Strata; 10] = [
         Strata::World,
         Strata::Background,
@@ -99,7 +56,7 @@ impl Strata {
         Strata::Blizzard,
     ];
 
-    /// The client bucket id (0..=9).
+    /// The client bucket id.
     #[inline]
     pub const fn index(self) -> u8 {
         self as u8
@@ -107,33 +64,26 @@ impl Strata {
 }
 
 impl Default for Strata {
-    /// `MEDIUM` — the client's default `frameStrata` (ctor writes `3` at `0x7690c2`).
+    /// The frame constructor writes 3 (`0x7690c2`).
     fn default() -> Strata {
         Strata::Medium
     }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Draw layers — the within-frame region order
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Draw layers ──────────────────────────────────────────────────────────────────────────────
 
-/// The five draw layers a region sits in, in draw order (the reference's five region lists
-/// ~`0x1c0`): BACKGROUND, BORDER, ARTWORK, OVERLAY, HIGHLIGHT.
+/// The five draw layers, in draw order (the reference's five region lists near `0x1c0`).
 #[repr(u8)]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum DrawLayer {
-    /// Drawn first (behind the frame's other regions).
     Background = 0,
     Border = 1,
-    /// The default layer for a texture/fontstring with no explicit `<Layer>`.
     Artwork = 2,
     Overlay = 3,
-    /// Drawn last (mouse-over highlights).
     Highlight = 4,
 }
 
 impl DrawLayer {
-    /// The layer index (0..=4).
     #[inline]
     pub const fn index(self) -> u8 {
         self as u8
@@ -141,113 +91,64 @@ impl DrawLayer {
 }
 
 impl Default for DrawLayer {
-    /// `ARTWORK` — the layer a texture/fontstring with no explicit `<Layer>` lands in.
+    /// The layer of a texture or font string with no `<Layer>`.
     fn default() -> DrawLayer {
         DrawLayer::Artwork
     }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// ZKey — the packed total-order key
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── ZKey: the packed total-order key ─────────────────────────────────────────────────────────
 //
-// Bit layout (u64), most-significant field = highest draw priority. The whole render list is a
-// single ascending sort on this key.
+// Most significant first; one ascending sort gives the render list.
 //
-//   bits 60..=63 (4)   stratum          Strata::index() 0..=9   (< 16)
-//   bits 44..=59 (16)  frame level      u16                     (< 65536)
-//   bits 41..=43 (3)   draw layer       DrawLayer::index() 0..=4 (< 8)
-//   bit  40      (1)   fontstring       0 = texture, 1 = fontstring — BUCKET-WIDE, above the frame
-//   bits 21..=39 (19)  frame link-stamp monotonic (re)link seq   (< 524288)
-//   bit  20      (1)   is-region        0 = the frame itself, 1 = one of its regions
-//   bits 12..=19 (8)   sub-level        i8 biased by +128        (0..=255) — INERT on 1.12
-//   bits  0..=11 (12)  declaration seq  region index within its owner frame (< 4096)
+//   bits 60..=63 (4)   stratum           Strata::index()
+//   bits 44..=59 (16)  frame level       u16
+//   bits 41..=43 (3)   draw layer        DrawLayer::index()
+//   bits 39..=40 (2)   batch rank        BatchRank: quad, text, callback
+//   bits 21..=38 (18)  frame link-stamp  the (re)link sequence
+//   bit  20      (1)   is-region         0 for the frame's own slot, 1 for a region
+//   bits 12..=19 (8)   sub-level         i8 biased by +128
+//   bits  0..=11 (12)  declaration seq   the region's index within its owner frame
 //
-// ## Why the draw layer outranks the frame (decision 0884 — §5-VERIFIED)
+// Stock content relies on the layer outranking the frame: a child is born at its parent's level
+// plus 1 (`SetParent` `0x76ab10`, at `0x76ab65`), `MirrorTimer.xml:62` lowers the bar by 1 to tie
+// its parent, and the tie lets the bar's ARTWORK fill draw under the parent's OVERLAY border.
 //
-// **The five render batches belong to the LEVEL NODE, not to the frame** (`levelNode+0x1c`, five
-// 0x30-byte batches), and the emitter `0x765920` loops `layer = 0..4` on the OUTSIDE and frames on
-// the inside. So the draw layer is a **bucket-wide** key: every frame sharing a `(strata, level)`
-// emits its BACKGROUND regions, then every frame its BORDER, then ARTWORK, then OVERLAY, then
-// HIGHLIGHT. It is not a within-frame ordering — which is what benilla modeled until 0884, with
-// the frame term ranked above the layer so a frame's regions stayed glued behind it.
-//
-// That inversion is what put the mirror timer's blue fill over its own border art and caption
-// (director report, 2026-08-02). The reference builds those bars as a Frame whose OVERLAY layer
-// carries the border + caption, with a child StatusBar whose `<BarTexture>` takes the default
-// **ARTWORK** layer and whose only OnLoad is `SetFrameLevel(GetFrameLevel() - 1)`. That line does
-// **not** put the child below the parent: a child is born at `parent.level + 1` (`SetParent
-// 0x76ab10` @`0x76ab65`), so the `-1` lands it at *exactly* the parent's level. Its whole job is to
-// **create the tie**, so the layer key can decide — ARTWORK(2) before OVERLAY(3), fill under
-// chrome. Ranked below the frame, there was no tie to resolve and the child always trailed.
-//
-// **`texture < fontstring` is bucket-wide too, and outranks the frame.** A layer's batch holds two
-// independent sub-arrays — the quad array `[batch+0x10]` (every `CSimpleTexture` appends via
-// `0x7706e0` → `0x772fd0`) and the text sub-batch `[batch+0x18]` (`0x772e50` → `0x773080`) — and
-// `0x76fb00` drains the WHOLE quad array before it touches the text one. So for two frames A, B at
-// one `(strata, level, layer)`, each with a texture and a font string, the client emits
-// `A.tex, B.tex, A.text, B.text` — never `A.tex, A.text, B.tex, B.text`.
-//
-// **The frame link-stamp below that is exact for font strings and a deterministic stand-in for
-// textures.** The client re-sorts a layer's quad array by *texture handle* (`0x7731a0`'s qsort,
-// comparator `0x7731c0`) and never sorts the text sub-batch. The handle is an internal allocation
-// our texture manager assigns differently, so reproducing that sort is neither achievable nor
-// desirable; we reproduce the client's PRE-sort array, which agrees wherever a layer's quads share
-// a texture or don't overlap (the common case). **No content may depend on the relative order of
-// two overlapping textures within one layer** — that is not a fidelity invariant.
-//
-// A frame's own entry zeroes the layer and everything below `is-region`, so it precedes its own
-// BACKGROUND regions. That slot is benilla's backdrop/scissor hook, not the client's — in the
-// binary a frame has no drawable of its own — so it sits *below* the layer key, never above it.
-//
-// **`sub-level` is inert on 1.12**: there is no sub-level in 5875 at all (`0x76a860` takes only
-// `(region, layer)`, head-inserts with no comparator, and the per-layer header is a plain 0xc-byte
-// triple with nowhere to keep a sort key). The field stays as the modeled Era delta; no 1.12
-// content sets it, so it is always the `0` bias.
+// The sub-level is a later client's ordering within a layer, not 1.12's, which has none
+// (`0x76a860` takes only region and layer and inserts at the head); stock content never sets it.
 
 const STRATUM_SHIFT: u32 = 60;
 const LEVEL_SHIFT: u32 = 44;
 const LAYER_SHIFT: u32 = 41;
-/// The batch RANK within a `(strata, level, layer)`: the three sub-arrays a layer batch carries and
-/// the order `0x76fb00` drains them — its quads (`+0x10`), its string batch (`+0x18`), then its
-/// render-callback list (`+0x1c`; decision 1995).
-/// Two bits at 39..40, where the one font-string bit used to be; the link stamp below lost a bit
-/// for it (18, from 19 — the arena renumbers at the cap either way).
 const RANK_SHIFT: u32 = 39;
 const INSERTION_SHIFT: u32 = 21;
 const IS_REGION_SHIFT: u32 = 20;
 const SUBLEVEL_SHIFT: u32 = 12;
 const DECL_SHIFT: u32 = 0;
 
+/// The link-stamp width; the arena renumbers its stamps at the cap.
 pub(crate) const INSERTION_BITS: u32 = 18;
 const DECL_BITS: u32 = 12;
 
-/// Which of a layer batch's three sub-arrays an entry drains from — in the order `0x76fb00` drains
-/// them. The client keeps them as three arrays on one batch object (ctor `0x772e80`: quads at
-/// `+0x10`, the `CGxStringBatch` at `+0x18`, a `RENDERCALLBACKNODE` list at `+0x1c`) and empties
-/// them in this order, so within one `(strata, level, layer)` every texture precedes every font
-/// string, and every font string precedes every model scene (decision 1995).
+/// Which of a layer batch's arrays an entry drains from, in `0x76fb00`'s order: quads at `+0x10`
+/// (a texture appends at `0x7706e0`), a `CGxStringBatch` at `+0x18` (a font string at `0x772e50`)
+/// and a render-callback list at `+0x1c` (ctor `0x772e80`). So in one `(strata, level, layer)`
+/// every texture precedes every font string, and every font string every model scene.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[repr(u8)]
 pub enum BatchRank {
-    /// A texture quad — drained first.
     Quad = 0,
-    /// A font string — the string batch, drained second.
     Text = 1,
-    /// A `Model` frame's scene — the callback list, drained last. Registered for ARTWORK only
-    /// (`0x76d17f cmp ebx,2`), which is why [`ZKey::callback`] takes the layer it is asked for
-    /// but a model's is always `ARTWORK`.
+    /// A `Model` frame's scene, registered for ARTWORK only (`0x76d17f`).
     Callback = 2,
 }
 
-/// The packed draw-order key: a single `u64` whose natural `Ord` *is* the client's total draw
-/// order. Build one with [`ZKey::frame`] or [`ZKey::region`]; sort ascending to get painter order.
+/// The packed draw-order key; its `Ord` is the client's draw order.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct ZKey(u64);
 
 impl ZKey {
-    /// The key for a **frame's own** entry — every region-level field is zero, so this sorts before
-    /// all of the frame's regions.
+    /// A frame's own entry; its region fields are zero, so it sorts before its regions.
     pub fn frame(strata: Strata, level: u16, insertion: u32) -> ZKey {
         debug_assert!(
             insertion < (1 << INSERTION_BITS),
@@ -259,9 +160,8 @@ impl ZKey {
         ZKey(bits)
     }
 
-    /// The key for one **region** of a frame. `strata`/`level`/`insertion` are the *owner frame's*
-    /// (so the region stays grouped behind its frame); `is_fontstring` places textures before
-    /// fontstrings at equal (layer, sub-level).
+    /// A region's key; `strata`, `level` and `insertion` are its owner frame's, and
+    /// `is_fontstring` picks the text rank.
     pub fn region(
         strata: Strata,
         level: u16,
@@ -279,7 +179,7 @@ impl ZKey {
             u32::from(decl) < (1 << DECL_BITS),
             "region decl seq {decl} exceeds {DECL_BITS} bits"
         );
-        // sub_level (i8, -128..=127) biased into 0..=255 so higher sub-level sorts later.
+        // Biased into 0..=255 so a higher sub-level sorts later.
         let sub_biased = (i16::from(sub_level) + 128) as u64;
         let bits = (u64::from(strata.index()) << STRATUM_SHIFT)
             | (u64::from(level) << LEVEL_SHIFT)
@@ -297,17 +197,10 @@ impl ZKey {
         ZKey(bits)
     }
 
-    /// The key a frame's own **content** draws at: its bare [`ZKey::frame`] slot promoted into its
-    /// region band at `layer` — behind that layer's textures, ahead of its declared font strings.
-    ///
-    /// Content is what a widget kind draws *itself*, with no region to hang it on — today only a
-    /// ScrollingMessageFrame's ring lines, which the client materializes as the frame's own font
-    /// strings (its `<FontString>` child is their font instance, and a font string with no
-    /// `<Layer>` is `ARTWORK`). At the bare frame slot they sorted before **all** of the frame's
-    /// regions, so the chat window's own `$parentBackground` — a `BACKGROUND` texture, faded in
-    /// on hover — painted over the messages and dimmed them (director, 2026-07-26; the white
-    /// text measured 192, exactly `255 × (1 − 0.25)`, the box's own alpha). The frame slot stays
-    /// what it was — the backdrop/scissor setup that must precede everything the frame owns.
+    /// The key for a frame's own content, text with no region: its frame slot moved into its
+    /// region band at `layer` with the text rank. The content is a ScrollingMessageFrame's lines,
+    /// which the client draws as the frame's own font strings (ARTWORK with no `<Layer>`), so the
+    /// frame's BACKGROUND art stays behind them.
     #[inline]
     #[must_use]
     pub const fn content(self, layer: DrawLayer) -> ZKey {
@@ -315,20 +208,15 @@ impl ZKey {
             self.0
                 | (1u64 << IS_REGION_SHIFT)
                 | ((layer.index() as u64) << LAYER_SHIFT)
-                // Sub-level 0 in the same +128 bias `region` uses, and the text rank: content is
-                // text, so it takes the same textures-draw-first slot a font string would.
+                // Sub-level 0, biased as in `region`.
                 | (128u64 << SUBLEVEL_SHIFT)
                 | ((BatchRank::Text as u64) << RANK_SHIFT),
         )
     }
 
-    /// The key a `Model` frame's **scene** draws at: its bare [`ZKey::frame`] slot promoted into
-    /// its region band at `layer` with the CALLBACK rank — after every texture and every font
-    /// string of that `(strata, level, layer)`, whatever their link stamps. That is the client's
-    /// own place for it: `0x76d160` registers the model's render callback into the layer batch,
-    /// and `0x76fb00` drains the callback list after the quads and the text. Two scenes in one
-    /// bucket keep the link-stamp order below the rank (registration order = FIFO), which the
-    /// bare slot's own insertion carries here (decision 1995).
+    /// The key for a `Model` frame's scene: its frame slot moved into its region band at `layer`
+    /// with the callback rank, after every texture and font string of the layer, as `0x76d160`
+    /// registers the scene into the layer batch whose callbacks `0x76fb00` drains last.
     #[inline]
     #[must_use]
     pub const fn callback(self, layer: DrawLayer) -> ZKey {
@@ -341,49 +229,38 @@ impl ZKey {
         )
     }
 
-    /// The raw packed value (the sort key).
     #[inline]
     pub const fn raw(self) -> u64 {
         self.0
     }
 
-    /// Unpack this key back into its fields.
     #[inline]
     pub const fn parts(self) -> ZParts {
         unpack(self.0)
     }
 }
 
-/// The fields of a packed [`ZKey`], in significance order — the readable face of an opaque `u64`.
-///
-/// A draw-order key is a single number by design (one sort produces the whole render list), which
-/// makes every question *about* an order — "why is this over that?", "which pairs would a re-rank
-/// invert?" — unanswerable at a glance. [`unpack`] is that answer, and it is why
-/// [`crate::script::ExtractedQuad::z`] can stay a bare `u64`.
+/// A [`ZKey`]'s fields, most significant first.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct ZParts {
-    /// The frame strata bucket id (0..=9, [`Strata::index`]).
+    /// [`Strata::index`].
     pub strata: u8,
-    /// The frame level within the strata bucket.
     pub level: u16,
-    /// The draw layer (0..=4, [`DrawLayer::index`]) — bucket-wide, above the frame (decision 0884).
+    /// [`DrawLayer::index`].
     pub layer: u8,
-    /// The batch rank: all textures of a `(strata, level, layer)` precede all its text, and all its
-    /// text precedes its model scenes ([`BatchRank`]).
     pub rank: BatchRank,
-    /// `rank == Text` — kept for the readers that only ask the old question.
+    /// `rank == BatchRank::Text`.
     pub is_fontstring: bool,
-    /// The owning frame's link-stamp — its position in the client's intrusive bucket list.
+    /// The owning frame's link-stamp.
     pub insertion: u32,
-    /// `false` for a frame's own slot, `true` for one of its regions.
     pub is_region: bool,
-    /// The Era `textureSubLevel` knob; inert for 1.12 content (always 0 there).
+    /// 0 for stock 1.12 content.
     pub sub_level: i8,
-    /// Declaration order within the owning frame's layer.
+    /// Declaration order within the owning frame.
     pub decl: u16,
 }
 
-/// Unpack a raw [`ZKey`] (e.g. [`crate::script::ExtractedQuad::z`]) into its fields.
+/// A raw [`ZKey`]'s fields, as [`crate::script::ExtractedQuad::z`] stores the key.
 #[inline]
 pub const fn unpack(raw: u64) -> ZParts {
     ZParts {
@@ -403,31 +280,26 @@ pub const fn unpack(raw: u64) -> ZParts {
     }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Traversal — the visible render list in the client's painter order
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Traversal: the visible render list in painter order ──────────────────────────────────────
 
-/// What a [`ZKey`] entry points at: a frame's own draw slot, or one of its regions.
+/// What a [`ZKey`] entry points at.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 pub enum ZTarget {
-    /// The frame itself (backdrop/scissor slot) — sorts before its regions.
+    /// The frame's own slot (backdrop, scissor).
     Frame(FrameHandle),
-    /// A texture or fontstring belonging to a frame.
     Region(RegionHandle),
 }
 
-/// The sorted draw list itself — shared, so a frame that changed nothing hands out the same one.
+/// The sorted draw list, shared so an unchanged frame hands out the same one.
 pub type DrawList = std::sync::Arc<[(ZTarget, ZKey)]>;
 
-/// [`traversal`]'s memo: the last walk (arena order) and the sorted list built from it.
+/// [`traversal`]'s memo: the last walk, in arena order, and the sorted list built from it.
 #[derive(Default, Debug)]
 pub struct OrderCache(std::cell::RefCell<Option<OrderMemo>>);
 
-/// The last walk, in arena order, and the sorted list built from it.
 type OrderMemo = (Vec<(ZTarget, ZKey)>, DrawList);
 
-/// Every `(target, key)` of the draw list, in ARENA order — the one walk both the fingerprint
-/// and the rebuild are made of, so they cannot disagree.
+/// Every `(target, key)` of the draw list, in arena order.
 fn walk(arena: &WidgetArena, mut f: impl FnMut(ZTarget, ZKey)) {
     for (fh, frame) in arena.iter_frames() {
         if !frame.effective_visible {
@@ -439,8 +311,7 @@ fn walk(arena: &WidgetArena, mut f: impl FnMut(ZTarget, ZKey)) {
             let Some(region) = arena.region(rh) else {
                 continue;
             };
-            // `Region:SetParent(nil)` orphaned this leaf: unlinked from every draw layer, still
-            // alive (see [`crate::widget::Region::detached`]). It draws nothing until re-parented.
+            // A region orphaned by `SetParent(nil)` is in no draw layer until re-parented.
             if region.detached {
                 continue;
             }
@@ -458,37 +329,14 @@ fn walk(arena: &WidgetArena, mut f: impl FnMut(ZTarget, ZKey)) {
     }
 }
 
-/// Produce the render list in the client's exact `0x765650` order.
-///
-/// Only **effective-visible** frames contribute: because `effective_visible` is maintained across
-/// the whole subtree by the arena's propagation (`set_shown`/`set_parent`), filtering on the flag
-/// is equivalent to the client's "recurse to child frames, a hidden mid-tree frame blocks its
-/// subtree" (`0x76ae10`/`0x76ad50`) — a child of a hidden frame already carries
-/// `effective_visible == false` and is skipped here. Each visible frame emits its own
-/// [`ZTarget::Frame`] entry followed by one
-/// [`ZTarget::Region`] per owned region; the returned vec is sorted ascending by [`ZKey`], which *is*
-/// the total draw order (strata → frame level → **draw layer** → texture<fontstring → frame
-/// link-stamp → is-region → sub-level → decl; the layer outranks the frame — see the `ZKey`
-/// bit-layout note and decision 0884). Ties are impossible: distinct frames differ in link-stamp, a frame and its
-/// regions differ in the is-region bit, and a frame's regions differ in the remaining fields.
-///
-/// Ordering only: this emits an entry for *every* region of a visible frame. Region-level
-/// `Show`/`Hide` (the VisibleRegion bit, `region+0xc4`) is applied one layer up, where paint lives —
-/// [`UiScript::extract`](crate::script::UiScript::extract) drops hidden regions before they become
-/// quads. (The 1.12 region-draw cluster that would pin the *draw-time* skip remains unread; the
-/// flag itself and its setter `0x77fcb0` are recorded.)
-///
-/// Cached against its own inputs (decision 1979): the list
-/// is a pure function of every visible frame's `(strata, level, insertion)` and every attached
-/// region's layer/sub-level/kind/decl — a walk over ~2 k frames and ~6 k regions, then a sort,
-/// and it was rebuilt on every frame for the extract, the pointer and the edit box alike. The
-/// walk stays (it is the fingerprint); the sort and the allocation happen only when the walk
-/// hashes differently from the last one, which on a still frame it never does.
+/// The render list in the client's `0x765650` order, sorted by [`ZKey`], with no two keys tied.
+/// Only effective-visible frames contribute, as the client skips a hidden frame's whole subtree
+/// (`0x76ae10`, `0x76ad50`). Every region of such a frame is listed; hidden ones (`region+0xc4`,
+/// set by `0x77fcb0`) are dropped by [`UiScript::extract`](crate::script::UiScript::extract), and
+/// where the client skips them at draw time is untraced. An unchanged walk returns the last list.
 pub fn traversal(arena: &WidgetArena) -> DrawList {
     let mut cache = arena.order_cache.0.borrow_mut();
-    // One walk into a scratch (the previous walk's buffer, reused), then an EXACT compare
-    // against the last walk: equal inputs hand out the same list; a hash would have made a
-    // wrong draw order a possibility, however remote, and cost a second walk on every miss.
+    // An exact compare with the last walk, not a hash: a collision would draw in a wrong order.
     let (mut walked, last) = match cache.take() {
         Some((prev, list)) => {
             let mut scratch = Vec::with_capacity(prev.len());
@@ -514,53 +362,26 @@ pub fn traversal(arena: &WidgetArena) -> DrawList {
     list
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Hit-testing — the mouse-focus capture walk
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Hit-testing: the mouse-focus capture walk ────────────────────────────────────────────────
 
-/// Find the frame the cursor captures — the reference's flat hit-test index.
+/// The frame the cursor captures, by the client's sweep `0x7660d0`: strata high to low, and in one
+/// `(strata, level)` plane the earlier-linked frame first. The first frame that takes the mouse
+/// ends the sweep whatever its handler does (`0x7663f7` overwrites the result of the call at
+/// `0x7663f4`), so a disabled button still eats the click.
 ///
-/// The sweep `0x7660d0` walks the mouse plane strata high→low and, within a stratum, the index from
-/// 0 upward, ending the ENTIRE sweep on the first probe that returns non-zero. There is **no
-/// fall-through**: `0x7663f4 call [edx+0x68]` is followed by `0x7663f7 mov eax,1`, so the handler's
-/// return is destroyed before it is tested. A frame that takes the mouse and does nothing with the
-/// click eats it — a `RegisterForClicks` miss, a disabled button and an unbound script all end the
-/// event identically. (The one real fall-through in the engine is the WHEEL plane, which does gate
-/// on a handler and continue; the engine has the idiom and deliberately does not use it here.)
+/// Equal levels go to the earlier link (`0x764aa0` appends after equals). A parent is linked before
+/// its children (show at `0x76ae85`, then `0x76aeb6`; `SetFrameLevel` likewise), so it wins a tie
+/// with its child, which `TargetFrame.lua:33` relies on; and the first-declared sibling wins, so a
+/// full-area `<Button>` declared first, mouse-enabled by its constructor, swallows its window.
+/// Drawing still puts the later link on top.
 ///
-/// **The index is FLAT** — sorted `(strata, frame level, insertion order)`, with no parent/child
-/// nesting term at all, which is exactly [`traversal`]'s key. The tie is the part that matters and
-/// the part we had backwards: `0x764aa0`'s comparison is a strict `ja`, so a frame arriving at a
-/// level that already exists is **appended after** its equals, and the sweep from index 0 therefore
-/// reaches the **earlier-linked** frame first. `SetFrameLevel` relinks the parent before recursing
-/// into children, and effective-Show registers self (`0x76ae85`) before its children (`0x76aeb6`) —
-/// so at equal levels **the parent wins over its own child**.
-///
-/// That is the whole reason `TargetFrame_OnLoad`'s `SetFrameLevel(textureFrame-1)` on the two bars
-/// works: the bars land at exactly `TargetFrame`'s own level, and the tie goes to the frame that
-/// registered first. Walking the draw order in reverse inverts it and hands the click to the
-/// child, so right-clicking a unit frame opened nothing.
-///
-/// **The SIBLING case is the one that bites hardest, and it is why this is not a local fix**
-/// (decision 1816). All children of one parent share `parent.level + 1`, so every sibling set is one
-/// big tie, resolved purely by declaration order — and under the true law the FIRST-declared sibling
-/// wins, not the last. A full-area mouse-enabled overlay declared at the top of a `<Frames>` list
-/// therefore swallows its whole window. Five of our own windows shipped exactly that (the
-/// `*WheelCatcher` `<Button>`s), correct only under the inverted order and now removed;
-/// `SkillFrame.xml` had already recorded one shipped bug from the same shape. Note that
-/// `<Button>` is mouse-enabled by its *constructor* (decision 1795), so such an overlay needs no
-/// `enableMouse` to compete — the wheel is a separate index and needs no mouse hit target at all.
-///
-/// Drawing is unaffected and stays later-on-top: this reordering is the HIT sweep's alone.
-///
-/// Pure over its inputs: `sorted` is draw-order-**ascending** (as [`traversal`] returns), and
-/// `hits(frame)` reports whether that frame is a capture candidate at the cursor. Visibility is
-/// handled upstream. Regions never capture.
+/// `sorted` is [`traversal`]'s ascending list and `hits` says whether a frame is a candidate at the
+/// cursor; regions never capture.
 pub fn hit_test<F: Fn(FrameHandle) -> bool>(
     sorted: &[(ZTarget, ZKey)],
     hits: F,
 ) -> Option<FrameHandle> {
-    // Everything above the insertion field: one (strata, level) plane of the reference's index.
+    // The key's strata and level: one plane of the client's index.
     let plane = |k: ZKey| k.0 >> LEVEL_SHIFT;
     let mut end = sorted.len();
     while end > 0 {
@@ -569,7 +390,7 @@ pub fn hit_test<F: Fn(FrameHandle) -> bool>(
         while start > 0 && plane(sorted[start - 1].1) == p {
             start -= 1;
         }
-        // Planes descend; WITHIN a plane the earlier-linked frame is probed first.
+        // Planes descend; within one, the earlier-linked frame is probed first.
         for (target, _) in &sorted[start..end] {
             if let ZTarget::Frame(fh) = *target {
                 if hits(fh) {
@@ -594,7 +415,7 @@ mod tests {
         let lo = ZKey::frame(Strata::World, u16::MAX, 0);
         let hi = ZKey::frame(Strata::Tooltip, 0, 0);
         assert!(hi > lo);
-        // BLIZZARD (Era) is above TOOLTIP.
+        // BLIZZARD is above TOOLTIP.
         assert!(ZKey::frame(Strata::Blizzard, 0, 0) > ZKey::frame(Strata::Tooltip, u16::MAX, 0));
     }
 
@@ -627,26 +448,23 @@ mod tests {
     #[test]
     fn layer_then_kind_then_frame_then_decl() {
         let mk = |layer, sub, fs, decl| ZKey::region(Strata::Medium, 3, 42, layer, sub, fs, decl);
-        // The layer is the top term below (strata, level) — it dominates everything under it.
+        // The layer is the top term below strata and level.
         assert!(
             mk(DrawLayer::Border, i8::MIN, false, 0) > mk(DrawLayer::Background, 127, true, 4095)
         );
-        // Within a layer, KIND is next: all textures precede all fontstrings — and it now outranks
-        // sub-level (0884: the layer batch's two sub-arrays, quads drained before text).
+        // Within a layer the kind is next: every texture precedes every font string, whatever the
+        // sub-level.
         assert!(
             mk(DrawLayer::Artwork, i8::MIN, true, 0) > mk(DrawLayer::Artwork, 127, false, 4095)
         );
         // Below kind, declaration order decides within one frame's layer.
         assert!(mk(DrawLayer::Artwork, 0, false, 2) > mk(DrawLayer::Artwork, 0, false, 1));
-        // Sub-level still orders below kind — inert on 1.12 (nothing sets it), kept for Era.
+        // Sub-level orders below kind.
         assert!(mk(DrawLayer::Artwork, -1, false, 0) < mk(DrawLayer::Artwork, 0, false, 0));
     }
 
-    /// The law 0884 **replaced**, kept as a test so it cannot come back: a frame's regions are not
-    /// glued behind it. The draw layer is bucket-wide, so at one `(strata, level)` every frame's
-    /// BACKGROUND draws before any frame's OVERLAY — frame A's OVERLAY sorts *after* frame B's
-    /// BACKGROUND even though A linked first. That interleave is what puts the mirror timer's
-    /// ARTWORK fill under its own parent frame's OVERLAY border and caption.
+    /// The layer is bucket-wide: at one `(strata, level)` every frame's BACKGROUND draws before any
+    /// frame's OVERLAY, so a frame's regions are not grouped behind it.
     #[test]
     fn the_layer_interleaves_frames_it_does_not_group_them() {
         let a_overlay = ZKey::region(Strata::Medium, 0, 10, DrawLayer::Overlay, 0, false, 0);
@@ -664,23 +482,20 @@ mod tests {
             "at equal layer+kind, later link draws on top"
         );
 
-        // Kind spans frames: ALL textures of a (strata, level, layer) precede ALL its fontstrings.
+        // Kind spans frames: every texture of a (strata, level, layer) precedes every font string.
         let a_text = ZKey::region(Strata::Medium, 0, 10, DrawLayer::Artwork, 0, true, 0);
         assert!(
             b_art < a_text,
             "a later frame's texture still precedes an earlier frame's fontstring"
         );
-        // …and ALL its font strings precede a model's scene, whatever the link stamps: the scene
-        // drains from the layer batch's callback list, after its quads and its text (1995). The
-        // world map's arrow (a Model linked FIRST under WorldMapFrame) over the zone overlays and
-        // the area label (a later-linked ARTWORK texture and font string) is exactly this pair.
+        // Every font string precedes a model's scene, whatever the link stamps.
         let earlier_model = ZKey::frame(Strata::Medium, 0, 9).callback(DrawLayer::Artwork);
         let later_text = ZKey::region(Strata::Medium, 0, 11, DrawLayer::Artwork, 0, true, 0);
         assert!(
             later_text < earlier_model,
             "an earlier-linked model's scene still draws after a later frame's ARTWORK text"
         );
-        // The rank sits BELOW the layer: an OVERLAY quad still covers an ARTWORK scene.
+        // The rank sits below the layer: an OVERLAY quad still covers an ARTWORK scene.
         let b_overlay = ZKey::region(Strata::Medium, 0, 11, DrawLayer::Overlay, 0, false, 0);
         assert!(
             earlier_model < b_overlay,
@@ -691,8 +506,7 @@ mod tests {
         assert!(earlier_model < later_model);
         assert_eq!(unpack(earlier_model.raw()).rank, BatchRank::Callback);
 
-        // A frame's own slot is benilla's backdrop/scissor hook: it sits BELOW the layer key, so
-        // it precedes only its own regions, starting with its BACKGROUND.
+        // A frame's own slot sorts just before its own BACKGROUND regions.
         let a_frame = ZKey::frame(Strata::Medium, 0, 10);
         let a_bg = ZKey::region(Strata::Medium, 0, 10, DrawLayer::Background, 0, false, 0);
         assert!(a_frame < a_bg);
@@ -706,9 +520,8 @@ mod tests {
     fn traversal_snapshot_over_a_small_tree() {
         let mut a = WidgetArena::new();
 
-        // A DIALOG-strata parent with a texture; a MEDIUM child (lower strata ⇒ draws *before* its
-        // parent, proving the order is flat, not hierarchical); and a hidden frame that must not
-        // appear at all.
+        // A DIALOG frame with two regions, a top-level MEDIUM frame (a MEDIUM child would be forced
+        // to DIALOG) and a hidden frame.
         let dialog = a.create(FrameKind::Frame, Some("Dialog".into()), None);
         a.set_frame_strata(dialog, Strata::Dialog);
         let dlg_bg = a
@@ -718,8 +531,6 @@ mod tests {
             .create_region(dialog, RegionKind::FontString, DrawLayer::Artwork, 0)
             .unwrap();
 
-        // set_frame_strata forced the child to DIALOG too (subtree force), so make the child a
-        // top-level MEDIUM frame instead to exercise cross-strata draw order.
         let medium = a.create(FrameKind::Frame, None, None); // MEDIUM, level 0
         let med_art = a
             .create_region(medium, RegionKind::Texture, DrawLayer::Artwork, 0)
@@ -733,9 +544,7 @@ mod tests {
 
         let list: Vec<ZTarget> = traversal(&a).iter().map(|&(t, _)| t).collect();
 
-        // Expected painter order: MEDIUM frame + its region first (lower strata), then the DIALOG
-        // frame followed by its two regions (Background texture before Artwork fontstring). The
-        // hidden frame and its region are absent.
+        // MEDIUM first; the hidden frame is absent.
         assert_eq!(
             list,
             vec![
@@ -748,13 +557,9 @@ mod tests {
         );
     }
 
-    /// The client's bucket re-add on show (`0x76ae10`):
-    /// within one (strata, level) bucket, a frame shown LATER draws over one declared later but
-    /// never hidden — the exact minimap case (MiniMapTrackingFrame is declared before
-    /// MinimapBackdrop, hidden at load, and its runtime Show must lift it over the backdrop's
-    /// ring art, as the director's reference A/B shows; decision 0557). A strata/level change on
-    /// a visible frame re-buckets to the tail the same way; on a hidden frame it does not bump
-    /// (the client's remove/add is visible-gated — it appends on the next show regardless).
+    /// Showing a frame relinks it at its bucket's tail (`0x76ae10`): `MiniMapTrackingFrame`,
+    /// declared hidden before `MinimapBackdrop` (`Minimap.xml:109`, `:415`), draws over the
+    /// backdrop once shown. A strata or level change relinks a shown frame, not a hidden one.
     #[test]
     fn showing_a_frame_moves_it_to_its_buckets_tail() {
         let mut a = WidgetArena::new();
@@ -769,8 +574,7 @@ mod tests {
             vec![ZTarget::Frame(tracking), ZTarget::Frame(backdrop)]
         );
 
-        // Hide-then-show (the XML's hidden="true" + the runtime Show()): tracking re-enters its
-        // bucket at the tail — above the backdrop.
+        // Hide then show: tracking relinks at the tail, above the backdrop.
         a.set_shown(tracking, false);
         a.set_shown(tracking, true);
         assert_eq!(
@@ -778,16 +582,14 @@ mod tests {
             vec![ZTarget::Frame(backdrop), ZTarget::Frame(tracking)]
         );
 
-        // A no-op Show (already visible) is NOT a transition — no re-add, order stays.
+        // Showing a shown frame relinks nothing.
         a.set_shown(backdrop, true);
         assert_eq!(
             order(&a),
             vec![ZTarget::Frame(backdrop), ZTarget::Frame(tracking)]
         );
 
-        // A visible frame's level round-trip re-buckets it to the tail both times — the
-        // remove/add of set_frame_level. (backdrop: level 0 → 1 → 0, ends level 0 again but now
-        // draws over tracking.)
+        // A shown frame's level round trip relinks it at the tail.
         a.set_frame_level(backdrop, 1, false);
         a.set_frame_level(backdrop, 0, false);
         assert_eq!(
@@ -795,8 +597,7 @@ mod tests {
             vec![ZTarget::Frame(tracking), ZTarget::Frame(backdrop)]
         );
 
-        // The same round-trip while HIDDEN doesn't bump: after the show it sits at the tail
-        // because of the show itself, and a hidden frame is in no bucket to move.
+        // The same round trip while hidden moves nothing; the show relinks it.
         a.set_shown(tracking, false);
         a.set_frame_level(tracking, 1, false);
         a.set_frame_level(tracking, 0, false);
@@ -812,8 +613,7 @@ mod tests {
     #[test]
     fn hit_test_returns_topmost_matching_frame_and_skips_regions() {
         let mut a = WidgetArena::new();
-        // Two overlapping frames; `top` (DIALOG) draws above `bottom` (MEDIUM). A region belongs to
-        // `top` and would sort *after* the frame in draw order — it must never be returned.
+        // `top` (DIALOG) draws above `bottom` (MEDIUM); `top`'s region must never be returned.
         let bottom = a.create(FrameKind::Frame, None, None);
         let top = a.create(FrameKind::Frame, None, None);
         a.set_frame_strata(top, Strata::Dialog);
@@ -822,12 +622,9 @@ mod tests {
             .unwrap();
 
         let sorted = traversal(&a);
-        // Both frames are candidates ⇒ the topmost-drawn (`top`) wins.
         assert_eq!(hit_test(&sorted, |_| true), Some(top));
-        // Only `bottom` is a candidate ⇒ it wins even though `top` draws above it (top is transparent
-        // to hits, e.g. mouse-disabled).
+        // A `top` that does not take the mouse lets `bottom` win.
         assert_eq!(hit_test(&sorted, |fh| fh == bottom), Some(bottom));
-        // No candidate ⇒ no capture.
         assert_eq!(hit_test(&sorted, |_| false), None);
     }
 }
diff --git a/crates/benilla-ui/src/script/action.rs b/crates/benilla-ui/src/script/action.rs
index fae1ca65..28ece326 100644
--- a/crates/benilla-ui/src/script/action.rs
+++ b/crates/benilla-ui/src/script/action.rs
@@ -1,113 +1,76 @@
-//! The action-bar bindings (decision 0068 slice 1, extended by decision 0216 §7/slice 4) — both
-//! directions of the engine seam in one place: the app pushes an **action snapshot** (what each
-//! of the 120 action slots displays, [`UiScript::set_action`], same inward shape as
-//! [`super::unit`]'s snapshots), and `UseAction` queues an outbound **intent** the app drains
-//! into the wire ([`UiScript::take_action_uses`], same outward shape as [`super::sound`]'s
-//! queue). The engine holds no spell/item/macro KNOWLEDGE — a slot is "a texture, a count, and
-//! the packed `(kind, action)` halves" — but slice 4 hands it the packed halves themselves so the
-//! cursor seam ([`super::cursor::bar`]) can pick a slot up and place it without round-tripping the
-//! app: the ENGINE owns the payload + the local slot mutation against its own optimistic mirror
-//! of `model.actions`, the APP owns the authoritative 120-table and drains the queued
-//! `action_sets` onto the wire (`CMSG_SET_ACTION_BUTTON`).
-//!
-//! Actions are keyed by the **Lua action id** (1..120, the live API's space; the 1.12 wire's
-//! 120-slot array is this minus one). `GetBonusBarOffset` reports the app-pushed stance/form
-//! page offset — the vanilla main bar shows actions `(6 + offset − 1)·12 + i` when an offset is
-//! active (warrior stances, druid forms), which the FrameXML side computes exactly like
-//! Blizzard's own bar code.
+//! The action-bar bindings. The app pushes what each of the 120 slots shows and its per-frame
+//! state, and drains the queued `UseAction` presses and the slot writes the cursor made
+//! (`CMSG_SET_ACTION_BUTTON`); the engine keeps each slot's packed `(kind, action)` so the cursor
+//! can move a slot without the app. Actions are keyed by Lua action id, 1..120, one more than the
+//! wire's slot index. FrameXML's bonus bar shows actions `(6 + offset - 1) * 12 + i` for the
+//! app-pushed `GetBonusBarOffset`.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::binding_abi::flag;
 use super::Model;
 
-/// Action-kind bytes — bits 24–31 of the wire's packed slot word (VERIFIED vmangos `Player.h`
-/// `ActionButtonType`; decision 0216 §1, `CMSG_SET_ACTION_BUTTON`'s own packing). The natural
-/// home for the constant every `ActionSlot` producer/consumer needs (`super::cursor::bar`'s
-/// pack/unpack included) — this crate is deliberately engine-free (no protocol dependency, see
-/// the crate doc), so it can't just import `benilla_protocol::messages::ACTION_KIND_*`.
+/// The kind byte, bits 24-31 of the packed slot word (vmangos `Player.h:133`). Must match
+/// `benilla_protocol`'s `ACTION_KIND_*`; this crate has no protocol dependency.
 pub(crate) const ACTION_KIND_SPELL: u8 = 0x00;
 pub(crate) const ACTION_KIND_MACRO: u8 = 0x40;
 pub(crate) const ACTION_KIND_ITEM: u8 = 0x80;
 
-/// What one action slot displays. The app resolves icons (Spell.dbc × SpellIcon.dbc for a spell,
-/// the item template chain for an item) before pushing.
+/// What one action slot shows; the app resolves the icon before pushing.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct ActionSlot {
     /// The icon texture path (`Interface\Icons\…`); `None` shows the slot's fallback.
     pub texture: Option<String>,
-    /// The wire's kind byte (bits 24–31 of the packed slot word — SPELL 0x00/MACRO 0x40/ITEM
-    /// 0x80, decision 0216 §1). Opaque to the engine beyond the cursor seam's own pack/unpack
-    /// (`super::cursor::bar`); ids, targets, and the cast are still the app's.
+    /// The kind byte, one of the `ACTION_KIND_*` above.
     pub kind: u8,
-    /// The spell/macro/item id (bits 0–23 of the packed slot word).
+    /// The spell, macro or item id (bits 0-23 of the packed slot word).
     pub action: u32,
-    /// Bag count for an ITEM-kind slot (`GetActionCount`), `0` for every other kind or an empty
-    /// bag — the app-resolved value the Count fontstring reads (decision 0216 §7).
+    /// `GetActionCount`'s bag count for an item slot, 0 otherwise.
     pub count: u32,
-    /// `IsConsumableAction`: the gate the ref's `UpdateCount` puts in front of [`Self::count`]
-    /// (decision 0926 §3). **Identity, not state** — `0x4e5250` reads nothing but the slot's own
-    /// item template, so it changes exactly when the icon does and rides the same push (decision
-    /// 1301; it lived in [`ActionState`] until the login race that split the pair).
+    /// `IsConsumableAction`: `0x4e5250` reads only the slot's item template, so this rides the
+    /// icon's push, not [`ActionState`]'s.
     pub consumable: bool,
 }
 
-/// One action's **dynamic** state — the per-frame half the app's feed pushes beside the slot's
-/// identity ([`ActionSlot`]): what the reference's `ActionButton_Update*` family reads through
-/// `IsUsableAction`/`IsActionInRange`/`IsCurrentAction`/`GetActionCooldown` and kin (decision
-/// 0137 phase 4). Split from the identity map so a state churn (range, cooldown) never disturbs
-/// the identity diff that fires `ACTIONBAR_SLOT_CHANGED`.
+/// One action's per-frame state, read by `IsUsableAction`, `IsActionInRange`, `GetActionCooldown`
+/// and kin; kept apart from [`ActionSlot`] so its churn never fires `ACTIONBAR_SLOT_CHANGED`.
 #[derive(Clone, Copy, Debug, Default, PartialEq)]
 pub struct ActionState {
-    /// `IsUsableAction`'s first return: castable right now (power etc.).
+    /// `IsUsableAction`'s first return: castable now.
     pub usable: bool,
-    /// `IsUsableAction`'s second return: unusable **specifically** for insufficient power (the
-    /// 0.5/0.5/1.0 blue tint); other unusability reads `(false, false)` (the 0.4 grey).
+    /// `IsUsableAction`'s second return: unusable only for lack of power (FrameXML's blue tint).
     pub not_enough_mana: bool,
-    /// `IsActionInRange`: `None` = rangeless action or no valid target (Lua `nil`);
-    /// `Some(true/false)` = the 1/0 verdict.
+    /// `IsActionInRange`: `None` (nil) for a rangeless action or no target, else 1 or 0.
     pub in_range: Option<bool>,
-    /// `ActionHasRange`: the action's spell has a range row to test at all.
+    /// `ActionHasRange`: the action's spell has a range to test.
     pub has_range: bool,
-    /// `IsCurrentAction`: the Attack action while auto-attack is engaged, or the action's spell
-    /// while it is our in-flight cast (the checked ring).
+    /// `IsCurrentAction`: the Attack action while auto-attack is on, or the spell being cast.
     pub current: bool,
-    /// `IsAutoRepeatAction`: the action's spell is the live autorepeat key (`0xceac30`).
+    /// `IsAutoRepeatAction`: the action's spell is the live autorepeat spell (`0xceac30`).
     pub auto_repeat: bool,
     /// `IsAttackAction`: the action is the melee auto-attack.
     pub is_attack: bool,
-    /// `IsEquippedAction`: an ITEM action currently worn (the green border).
+    /// `IsEquippedAction`: an item action currently worn.
     pub equipped: bool,
-    /// The action's cooldown as pushed: `(start_ms, duration_ms, enabled)` with `start_ms` the
-    /// cooldown's **absolute start on the `GetTime` clock** (the app converts from its own clock
-    /// at feed time — the app-side `CooldownInfo::ui_triple`'s job). Absolute so the value is
-    /// identity-preserving: one running cooldown reads the same triple every frame (no diff
-    /// churn), while a re-arm always reads a new one (the sweep restarts — the reference's own
-    /// convention, whose `GetCooldownInfo 0x6e13e0` returns the record's start and therefore
-    /// cannot alias two arms the way a `(remaining, duration)` pair did).
+    /// `(start_ms, duration_ms, enabled)`, the start absolute on the `GetTime` clock, so a running
+    /// cooldown re-pushes the same triple and a re-arm a new one (`0x6e13e0` returns the start).
     pub cooldown: Option<(i64, u32, bool)>,
 }
 
-/// [`ActionState`] as stored: the cooldown converted to the `GetTime` clock at push time.
+/// [`ActionState`] with its cooldown in `GetTime` seconds.
 #[derive(Clone, Copy, Debug, Default, PartialEq)]
 pub(crate) struct StoredActionState {
     pub(crate) state: ActionState,
-    /// `(start_s, duration_s, enabled)` in `GetTime` seconds; `None` = no cooldown.
     pub(crate) cooldown: Option<(f64, f64, bool)>,
 }
 
-/// One queued `UseAction` press — the action id, and whether it carried the **self-cast
-/// modifier**.
-///
-/// A struct rather than a `(u32, bool)` because a bare bool in a tuple is exactly the argument
-/// that gets swapped silently; the neighbouring `take_action_sets` pairs two `u32`s, where the
-/// positions are self-describing.
+/// One queued `UseAction` press.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct ActionUse {
     /// The 1-based Lua action id, as `UseAction` was given it.
     pub action: u32,
-    /// `UseAction`'s third argument — 1.12's `SELFACTIONBUTTON1`-`12` (`ALT-1`…`ALT-=`) reach the
-    /// bar through `ActionButtonUp(id, 1)`, and every other caller passes nothing.
+    /// `UseAction`'s third argument, which only the self-cast bindings (`SELFACTIONBUTTON1`-`12`)
+    /// pass, through `ActionButtonUp(id, 1)`.
     pub on_self: bool,
 }
 
@@ -125,11 +88,8 @@ impl super::UiScript {
         }
     }
 
-    /// Push (or clear) one action's dynamic state. The cooldown arrives with its **absolute
-    /// start already on the `GetTime` clock** (ms), so storing is a pure unit conversion — no
-    /// anchor derivation, no prev-comparison. A re-push of a running cooldown carries the same
-    /// start (the sweep is undisturbed — the reset-on-kill invariant holds by construction); a
-    /// re-armed one carries a new start (the sweep restarts, as the reference's does).
+    /// Push (or clear) one action's state; the cooldown start is already on the `GetTime` clock,
+    /// so storing only converts milliseconds to seconds.
     pub fn set_action_state(&mut self, action: u32, state: Option<ActionState>) {
         let mut model = self.model_mut();
         match state {
@@ -161,28 +121,20 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().action_uses)
     }
 
-    /// Drain the `(lua action id, packed)` pairs `PickupAction`/`PlaceAction` queued since the
-    /// last call (decision 0216 §7) — the app sends one `CMSG_SET_ACTION_BUTTON` per entry
-    /// (`packed == 0` clears the slot) and updates its own authoritative `PlayerActions` store.
+    /// Drain the `(lua action id, packed)` pairs `PickupAction`/`PlaceAction` queued; the app
+    /// sends each as `CMSG_SET_ACTION_BUTTON` (`packed == 0` clears) and updates its own store.
     pub fn take_action_sets(&mut self) -> Vec<(u32, u32)> {
         std::mem::take(&mut self.model_mut().action_sets)
     }
 
-    /// Drain the GlobalStrings keys queued by engine-side client-local refusals since the last
-    /// call — the app resolves each against the VM's own GlobalStrings and fires
-    /// `UI_ERROR_MESSAGE`, standing in for the reference's inline `CGGameUI::DisplayError` (whose
-    /// engine can call it directly; ours is on the far side of the crate boundary). See
-    /// [`crate::script::model::Model::ui_errors`].
+    /// Drain the GlobalStrings keys of engine-side refusals; the app fires `UI_ERROR_MESSAGE` for
+    /// each, where the reference calls `CGGameUI::DisplayError` inline.
     pub fn take_ui_errors(&mut self) -> Vec<&'static str> {
         std::mem::take(&mut self.model_mut().ui_errors)
     }
 }
 
-/// `checkCursor`'s truthiness (`UseAction`'s second argument): the reference's own numeric
-/// convention — `nil`/`false`/`0` all read falsy, anything else (including Lua's own `true`)
-/// reads truthy. Deliberately NOT Lua's plain truthiness (where `0` is truthy) — the reference
-/// passes literal `0` from a keybind meaning "never place", which only a numeric-zero check
-/// reproduces.
+/// `UseAction`'s flag test: `nil`, `false` and `0` are false, unlike Lua, where `0` is true.
 pub(super) fn truthy_nonzero(v: &Value) -> bool {
     match v {
         Value::Nil => false,
@@ -197,7 +149,6 @@ pub(super) fn truthy_nonzero(v: &Value) -> bool {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // HasAction(action) → 1/nil, the reference's predicate shape (`super::binding_abi::flag`).
     g.set(
         "HasAction",
         lua.create_function(|lua, action: u32| {
@@ -220,39 +171,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetActionText(slot) → the MACRO's own name, or nil. 1-based (`0x4e7072 dec eax`).
-    //
-    // **The classification is binary, not four-way** (`0x4e7050`). The binding tests exactly
-    // one thing — top nibble `raw & 0xf0000000 == 0x40000000` — and **spell, item and empty all
-    // collapse to the identical nil arm**. It settles nothing about how spells or items are
-    // tagged, because it never asks.
-    //
-    // | slot contents | returns |
-    // |---|---|
-    // | macro, id resolves | the macro's own name (record `+0x24`, an inline buffer) |
-    // | macro, id does not resolve | `nil` |
-    // | spell · item · empty | `nil` |
-    // | slot missing / not a number | **raises** `Usage: GetActionText(slot)` (`0x84bff4`) |
-    //
-    // A macro whose name is empty answers `""`, not nil: `+0x24` is an inline buffer and can never
-    // be the null pointer `0x6f3890`'s guard tests for, so that guard is dead at this site. Our
-    // `MacroView::name` is a `String` and reproduces that for free.
-    //
-    // **The reference's trap does not exist here, and the reason is worth stating.** There the
-    // slot's macro payload (`raw & 0x3fffffff`) is an **opaque hash key** into `[0xbdcc54]`, NOT
-    // the 1..36 index — `GetMacroInfo` translates an index through `0xbdcc60` first and
-    // `GetActionText` never does, so a client that treats the payload as an index reads the wrong
-    // macro for every macro whose id ≠ its slot. benilla's macro table has no id space at all
-    // (decision 0983: two dense lists addressed by the 1..36 Lua index), so the payload our wire
-    // carries IS that index — and this is the same lookup `ui_action::feed`'s MACRO icon arm
-    // makes, through the same `MacroState::get`, so a slot's text and its icon cannot disagree
-    // about which macro it holds.
-    //
-    // One deliberate deviation: the reference has **no bounds check** (read contiguously from the
-    // `dec` to `mov eax,[4*eax + 0xbc6980]` — no `cmp`, no clamp), so slot 0 reads the dword below
-    // a 120-dword array and slot 121 reads into the next global. Our slot store is a map, so an
-    // out-of-range slot is simply absent and answers nil. Safer than the binary, and recorded as a
-    // deviation rather than passed off as a match.
+    // GetActionText(slot): the macro's name, else nil. `0x4e7050` tests only
+    // `raw & 0xf0000000 == 0x40000000`, so spell, item and empty slots all answer nil; a missing or
+    // non-number slot raises `Usage: GetActionText(slot)` (`0x84bff4`); the slot is 1-based
+    // (`0x4e7072` `dec eax`). An empty name answers "": it is an inline buffer at `+0x24`, so
+    // `0x6f3890`'s null guard never fires.
+    // The reference's macro payload (`raw & 0x3fffffff`) is a hash key into `[0xbdcc54]`; ours is
+    // the 1..36 index, the lookup the app's macro icon makes too, so text and icon agree.
+    // Deviation: an out-of-range slot answers nil, because the reference indexes `0xbc6980` with
+    // no bounds check and reads the memory beside its 120 slots.
     g.set(
         "GetActionText",
         lua.create_function(|lua, slot: Value| {
@@ -273,28 +200,16 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UseAction(action [, checkCursor [, onSelf]]). **`onSelf` is the self-cast modifier** — the
-    // third argument stock `ActionButtonUp(id, onSelf)` forwards on its main-bar branch and this
-    // host used to drop on the floor, which is why 1.12's twelve `SELFACTIONBUTTON` bindings
-    // (`ALT-1`…`ALT-=`) had no home. It rides out on [`ActionUse::on_self`] and the app's cast
-    // resolver reads it. `checkCursor` TRUTHY (numeric nonzero — the
-    // reference's own convention, not Lua's: `0` reads falsy here even though Lua truthiness
-    // would call it true) AND a payload is held routes to [`cursor::place_action`] instead of
-    // queuing the use (decision 0216 §7's INTERIM: the reference passes 1 from a mouse click and
-    // 0 from a keybind — the 0216 §5 dispatch never pinned checkCursor's byte semantics
-    // explicitly, and place-on-click is the only reading consistent with that click/keybind
-    // split). Any of the three payload arms counts as "held" — Item/Spell/Action are all
-    // placeable onto a bar slot.
+    // UseAction(action [, checkCursor [, onSelf]]): a nonzero `checkCursor` while the cursor holds
+    // a payload places it, as `PlaceAction` does; otherwise the press is queued with `onSelf`, the
+    // self-cast flag. FrameXML passes 1 from a click and 0 from a keybind; the binding's own test
+    // of it is untraced, and place-on-click is the reading that split implies.
     g.set(
         "UseAction",
         lua.create_function(|lua, (action, rest): (u32, MultiValue)| {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
             let mut rest = rest.iter();
             let check_cursor = rest.next().is_some_and(truthy_nonzero);
-            // `onSelf` reads with the SAME truthiness as `checkCursor` — numeric-nonzero, the
-            // reference's convention rather than Lua's — because it arrives from the same
-            // callers by the same route. `ActionButtonUp(id, 1)` is the only shipped caller
-            // that passes it.
             let on_self = rest.next().is_some_and(truthy_nonzero);
             if check_cursor && model.cursor.is_some() {
                 super::cursor::place_action(&mut model, action);
@@ -305,9 +220,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // Bag count for an ITEM-kind action, 0 for every other kind (the ref's IsConsumableAction
-    // gate simplified — 0216 §7's App-section note) — the check lives HERE, not in every XML
-    // caller, so a slot fed a stray count on the wrong kind (a bug elsewhere) can't leak through.
     g.set(
         "GetActionCount",
         lua.create_function(|lua, action: u32| {
@@ -328,13 +240,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `ChangeActionBarPage()` — four instructions in the reference (`0x4e7650`: `mov ecx,0xd4;
-    // call FrameScript_SignalEvent; xor eax,eax; ret`):
-    // it fires `ACTIONBAR_PAGE_CHANGED` and does NOTHING else. The page is FrameXML state
-    // (`CURRENT_ACTIONBAR_PAGE`, which `ActionBar_PageUp/Down` and the SHIFT-n bindings write before
-    // calling this), the buttons repaint from `ActionButton_OnEvent`, and the up-arrow's OnEvent
-    // restamps the numeral. Synchronous, like the reference's `SignalEvent` (1938; the pattern is
-    // `UpdateSpells` → `SPELLS_CHANGED`, 1924). Zero return values on every path.
+    // ChangeActionBarPage(): fires `ACTIONBAR_PAGE_CHANGED` synchronously and returns nothing
+    // (`0x4e7650`); the page itself is FrameXML's `CURRENT_ACTIONBAR_PAGE`.
     g.set(
         "ChangeActionBarPage",
         lua.create_function(|lua, ()| {
@@ -343,12 +250,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ── The dynamic-state read API (decision 0137 phase 4): the reference ActionButton.lua's
-    // whole input surface, answered from the app-pushed per-action state. Return conventions are
-    // the 1.12 API's own (1/nil booleans; IsActionInRange's nil/0/1 tri-state) — the transcribed
-    // Lua tests them with plain `if`, so nil-vs-0 matters exactly where the ref makes it matter.
+    // ── Per-action state ──
+    // 1/nil booleans and `IsActionInRange`'s nil/0/1, which FrameXML tests with a plain `if`.
 
-    // A 1/nil boolean read over the state map. An absent action answers nil.
     fn state_flag(lua: &Lua, action: u32, pick: impl Fn(&ActionState) -> bool) -> Value {
         let model = lua.app_data_ref::<Model>().expect("model app_data");
         match model.action_states.get(&action) {
@@ -357,7 +261,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         }
     }
 
-    // IsUsableAction(action) → isUsable (1/nil), notEnoughMana (1/nil).
     g.set(
         "IsUsableAction",
         lua.create_function(|lua, action: u32| {
@@ -368,7 +271,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsActionInRange(action) → nil (no range / no target) | 0 | 1.
     g.set(
         "IsActionInRange",
         lua.create_function(|lua, action: u32| {
@@ -403,10 +305,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "IsAttackAction",
         lua.create_function(|lua, action: u32| Ok(state_flag(lua, action, |s| s.is_attack)))?,
     )?;
-    // The Count gate reads the SLOT, not the state map: `IsConsumableAction 0x4e5250` is a pure
-    // query over the item template the icon already came from, so it has to arrive on the same
-    // push the icon does. Split across the two feeds it answered `nil` for the whole session on a
-    // freshly logged-in character (decision 1301).
+    // From the slot, not the state map: `0x4e5250` depends only on the item template.
     g.set(
         "IsConsumableAction",
         lua.create_function(|lua, action: u32| {
@@ -422,10 +321,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, action: u32| Ok(state_flag(lua, action, |s| s.equipped)))?,
     )?;
 
-    // GetActionCooldown(action) → start, duration, enable — the reference's `(GetTime-clock
-    // seconds, seconds, 0/1)` triple. An elapsed (or absent) cooldown answers `(0, 0, 1)`: the
-    // read must go cold once `start + duration` passes, or a later event-driven
-    // `CooldownFrame_SetTimer` re-feed would re-show the sweep and replay the finish flash.
+    // GetActionCooldown(action) → start, duration, enable, in `GetTime` seconds. An absent or
+    // elapsed enabled cooldown answers `(0, 0, 1)`, or a later `CooldownFrame_SetTimer` would
+    // replay the sweep and its finish flash.
     g.set(
         "GetActionCooldown",
         lua.create_function(|lua, action: u32| {
@@ -450,7 +348,6 @@ mod tests {
     use super::ActionSlot;
     use crate::script::UiScript;
 
-    /// `(action, on_self)` pairs, which is what these assertions are actually about.
     fn uses(s: &mut UiScript) -> Vec<(u32, bool)> {
         s.take_action_uses()
             .into_iter()
@@ -458,14 +355,7 @@ mod tests {
             .collect()
     }
 
-    /// **`UseAction`'s third argument is the self-cast modifier** (1745) — 1.12's twelve
-    /// `SELFACTIONBUTTON` bindings (`ALT-1`…`ALT-=`) reach the bar as `ActionButtonUp(id, 1)`,
-    /// and this host dropped it on the floor until the day those bindings needed a home.
-    ///
-    /// It reads with `checkCursor`'s truthiness, not Lua's — **numeric-nonzero** — because it
-    /// arrives from the same callers by the same route. That is the assertion worth having: Lua
-    /// would call `0` true, and a bar where `ActionButtonUp(id, 0)` self-cast would be worse than
-    /// one where nothing did.
+    /// The numeric test: `0` is not the modifier, though Lua would call it true.
     #[test]
     fn use_actions_third_argument_is_the_self_cast_modifier() {
         let mut s = UiScript::new().unwrap();
@@ -527,7 +417,7 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetBonusBarOffset()").unwrap(), 1);
 
         s.run("UseAction(73)").unwrap();
-        s.run("UseAction(74, 0, 1)").unwrap(); // the self-cast modifier rides out
+        s.run("UseAction(74, 0, 1)").unwrap();
         assert_eq!(uses(&mut s), vec![(73, false), (74, true)]);
         assert!(s.take_action_uses().is_empty());
 
@@ -552,9 +442,7 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetActionCount(5)").unwrap(), 4);
     }
 
-    /// `UseAction`'s `checkCursor` routes to a place ONLY when truthy (numeric-nonzero, not Lua
-    /// truthiness) AND a payload is held; a keybind's bare `UseAction(id)` and an explicit `0`
-    /// both queue the ordinary use even while holding.
+    /// A place needs a nonzero `checkCursor` and a held payload; a keybind's `0` queues the use.
     #[test]
     fn use_action_check_cursor_routes_to_place_or_use() {
         use crate::script::cursor::{CursorAction, CursorPayload};
@@ -567,26 +455,21 @@ mod tests {
             texture: Some("Interface\\Icons\\Spell_A".into()),
         }));
 
-        // checkCursor 0 (a keybind's own convention): queues the use, cursor untouched.
         s.run("UseAction(9, 0)").unwrap();
         assert_eq!(uses(&mut s), vec![(9, false)]);
         assert!(s.cursor_payload().is_some(), "checkCursor 0 never places");
 
-        // checkCursor 1 (a mouse click) with a payload held: places instead of queuing.
         s.run("UseAction(9, 1)").unwrap();
         assert!(s.take_action_uses().is_empty(), "routed to place, not use");
         assert!(s.cursor_payload().is_none(), "empty destination clears");
         assert_eq!(s.take_action_sets(), vec![(9, 111)]);
 
-        // checkCursor 1 with an EMPTY cursor: the ordinary use (nothing to place).
         s.run("UseAction(10, 1)").unwrap();
         assert_eq!(uses(&mut s), vec![(10, false)]);
     }
 
-    // ── `GetActionText` (`0x4e7050`) ────────────────────────────────────────────────────────────
+    // ── `GetActionText` (`0x4e7050`) ──
 
-    /// The classification is **binary**: macro or not. A SPELL slot and an ITEM slot answer the
-    /// identical `nil` an empty slot does — the binding tests one nibble and asks nothing else.
     #[test]
     fn get_action_text_is_the_macro_name_and_nil_for_everything_else() {
         use crate::script::{MacroState, MacroView};
@@ -614,11 +497,11 @@ mod tests {
                 consumable: false,
             })
         };
-        s.set_action(1, slot(0x40, 1)); // macro 1 — "Pull"
-        s.set_action(2, slot(0x40, 2)); // macro 2 — an empty NAME, not an empty slot
-        s.set_action(3, slot(0x40, 30)); // macro id that does not resolve
-        s.set_action(4, slot(0x00, 133)); // a SPELL (Fireball)
-        s.set_action(5, slot(0x80, 117)); // an ITEM
+        s.set_action(1, slot(0x40, 1)); // macro "Pull"
+        s.set_action(2, slot(0x40, 2)); // a macro with an empty name
+        s.set_action(3, slot(0x40, 30)); // no such macro
+        s.set_action(4, slot(0x00, 133)); // a spell
+        s.set_action(5, slot(0x80, 117)); // an item
 
         assert_eq!(s.eval::<String>("return GetActionText(1)").unwrap(), "Pull");
         assert_eq!(
@@ -640,11 +523,11 @@ mod tests {
                 "{why} must be nil"
             );
         }
-        // One value on every non-raising path — never zero values.
+        // One value on every non-raising path.
         assert_eq!(s.arity("GetActionText(4)").unwrap(), 1);
     }
 
-    /// A missing or non-number slot **raises** (`0x4e70be` → `0x6f4940`, which never returns).
+    /// The raise is `0x4e70be` into `0x6f4940`, which never returns.
     #[test]
     fn get_action_text_raises_on_a_bad_slot() {
         let s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/action_bar_toggles.rs b/crates/benilla-ui/src/script/action_bar_toggles.rs
index d8d37ae2..bdb9bb9b 100644
--- a/crates/benilla-ui/src/script/action_bar_toggles.rs
+++ b/crates/benilla-ui/src/script/action_bar_toggles.rs
@@ -1,77 +1,36 @@
-//! `GetActionBarToggles` / `SetActionBarToggles` — the four extra action bars' visibility, as one
-//! server-owned nibble, byte-verified against the 1.12.1 binary.
+//! `GetActionBarToggles` and `SetActionBarToggles`: the four extra action bars' visibility, the
+//! low nibble of the server's `PLAYER_FIELD_BYTES` byte 2.
 //!
-//! ## The shape, and why it is not the shape it looks like
+//! The setter (`0x4e76e0`) only posts `CMSG_SET_ACTIONBAR_TOGGLES`; the getter (`0x4e7660`) reads
+//! the live descriptor byte, written only by the `SMSG_UPDATE_OBJECT` apply (`0x466590`), with no
+//! field-change hook (`0x468070`). A `Get` right after a `Set` returns the old value for a round
+//! trip; the stock UI reads it once, at `PLAYER_ENTERING_WORLD` (`UIParent.lua:364`).
 //!
-//! Four booleans in, four booleans out — but **the getter and the setter do not talk to each
-//! other**. `SetActionBarToggles 0x4e76e0` packs its four arguments into a stack byte, posts
-//! `CMSG_SET_ACTIONBAR_TOGGLES` and returns zero values; every store in its body is into its own
-//! `ebp` frame. `GetActionBarToggles 0x4e7660` reads the live descriptor at
-//! `[[player+0xe68]+0x102a]` — `PLAYER_FIELD_BYTES` byte 2 — on every call, with no cache. The
-//! only writer of that cell in the whole image is the generic `SMSG_UPDATE_OBJECT` value-apply
-//! (`0x466590`), and **nothing is notified when it lands**: all 49 field-change
-//! registrations at `0x468070` were enumerated and none sits at an offset ≥ `0x1000`.
-//!
-//! So `SetActionBarToggles(1)` followed immediately by `GetActionBarToggles()` returns the **old**
-//! value, for a whole round trip. That is not a bug to paper over — it is the mechanism, and it is
-//! why [`super::UiScript::set_action_bar_toggles`] (the app's descriptor push) is the *only* thing
-//! that moves our copy. Contrast [`super::worn_display`], whose setter updates its belief
-//! optimistically because its wire verb is a blind flip that would otherwise mis-compute.
-//!
-//! The reference UI does not feel the lag because it never asks: it keeps `SHOW_MULTI_ACTIONBAR_1..4`
-//! as Lua globals, updates them on the checkbox click, and reads the binding exactly once — in
-//! `UIParent.lua`'s `PLAYER_ENTERING_WORLD` handler. Our Lua layer copies that split.
-//!
-//! ## Four bits, and only four
-//!
-//! The setter's loop runs `i = 0..3` (`0x4e770e cmp esi,4`) and ORs `1 << i` for argument `i + 1`;
-//! the accumulator is written by exactly two instructions image-wide — the `mov BYTE [ebp-0x4],0`
-//! that zeroes it (`0x4e76eb`) and the loop's `or` (`0x4e7709`). Two consequences we reproduce
-//! exactly:
-//!
-//! - A **fifth argument is silently dropped**. The shipped `UIOptionsFrame_Save` passes
-//!   `ALWAYS_SHOW_MULTIBARS` as a fifth; the binding never fetches it, so it never reaches the byte
-//!   or the wire (and, consistently, it is the one option of the five that FrameXML saves locally).
-//! - A `Set` **destroys the high nibble**. It starts from zero, so whatever `0x10..0x80` the server
-//!   happened to hold is overwritten with 0 by the next post. The getter never tests those bits
-//!   either, so the client's view of this field is genuinely 4-bit.
-//!
-//! The bit→bar meaning is a FrameXML convention, not the binary's — the engine stores four
-//! unnamed bits and the names live in the UI layer.
+//! The setter builds the byte from zero out of four arguments (`0x4e76eb`, `0x4e7709`): a fifth,
+//! which `UIOptionsFrame.lua:363` passes, is dropped, and a high nibble the server held is cleared.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::binding_abi::bool_or_default;
 use super::Model;
 
-/// How many toggle bits the bindings read and write — `0x4e770e cmp esi,4` in the setter,
-/// `0x4e76cd mov eax,4` in the getter. Not a UI choice: four is what the binary does, in both
-/// directions, and bits above it are unreachable from Lua.
+/// Toggle bits the bindings read and write, four both ways (setter `0x4e770e`, getter `0x4e76cd`).
 const ACTION_BAR_TOGGLE_BITS: u32 = 4;
 
 impl super::UiScript {
-    /// Push the server's `PLAYER_FIELD_BYTES` byte 2 — the app calls this on the descriptor edge,
-    /// and it is the **only** way this value moves (see the module doc). Mirrors
-    /// [`Self::set_combo_points`], the other PRIVATE byte out of the same dword.
+    /// Push the server's `PLAYER_FIELD_BYTES` byte 2, the only way this value moves.
     pub fn set_action_bar_toggles(&mut self, toggles: u8) {
         self.model_mut().action_bar_toggles = Some(toggles);
     }
 
-    /// What the VM last had pushed into it, or `None` if nothing ever has — the app's own read,
-    /// and the tests'. `None` and `Some(0)` are indistinguishable to Lua by design: with no local
-    /// player the reference's chain fails soft and the getter returns four `nil`s, which is exactly
-    /// what a zero byte returns (`0x4e7660`).
+    /// The last pushed byte. Lua reads `None` as a zero byte, four `nil`s, as the reference does
+    /// with no local player (`0x4e7660`).
     pub fn action_bar_toggles(&self) -> Option<u8> {
         self.model_ref().action_bar_toggles
     }
 
-    /// Drain the `CMSG_SET_ACTIONBAR_TOGGLES` payloads queued since the last call — one per
-    /// `SetActionBarToggles` call, in order.
-    ///
-    /// A list rather than a "latest wins" slot because the binding gates **nothing**: it has no
-    /// did-it-change test (unlike `ShowHelm`/`ShowCloak`) and no connection check of its own, so
-    /// two calls in a frame are two packets. Dropping one here would be an optimisation the real
-    /// client does not make.
+    /// Drain the queued `CMSG_SET_ACTIONBAR_TOGGLES` payloads, one per `SetActionBarToggles` call:
+    /// the binding has no did-it-change test and no connection check, so two calls are two packets.
     pub fn take_action_bar_toggle_sends(&mut self) -> Vec<u8> {
         std::mem::take(&mut self.model_mut().action_bar_toggle_sends)
     }
@@ -81,10 +40,8 @@ impl super::UiScript {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetActionBarToggles() -> four values, each the NUMBER 1 or nil (`0x6f3810` pushes tag 3 with
-    // the double 1.0; `0x6f37f0` pushes tag 0). Never booleans — callers write `if toggle then`,
-    // and the WoW `1`-or-`nil` idiom is what the reference's own `SHOW_MULTI_ACTIONBAR_n` globals
-    // then hold. Return N tests bit `1 << (N-1)`, the exact inverse of the setter's map.
+    // GetActionBarToggles() -> four values, each the number 1 (`0x6f3810`) or nil (`0x6f37f0`),
+    // never a boolean; return N tests bit N-1.
     g.set(
         "GetActionBarToggles",
         lua.create_function(|lua, ()| {
@@ -103,16 +60,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetActionBarToggles(a, b, c, d) -> nothing. Four argument slots, no more: a fifth is never
-    // fetched (`0x4e76e0`), which matters because the shipped Options panel passes one.
-    //
-    // The arguments are read through `0x6f1c10`, NOT Lua truthiness ([`bool_or_default`]) — the
-    // panel that calls this hands option bindings the strings "0"/"1", and `"0"` is truthy in Lua.
-    // The default at this call site is FALSE (`0x4e76f4 push 0x0`), so an omitted argument is off.
-    //
-    // Nothing local is written: the byte we hold is the server's, and only the server's push moves
-    // it (module doc). A `Set` that never reaches the server therefore leaves the UI showing the
-    // truth rather than a lie.
+    // SetActionBarToggles(a, b, c, d) -> nothing. Arguments coerce through `0x6f1c10`, not Lua
+    // truthiness, so the Options panel's "0" is off; the default is false (`0x4e76f4`). Nothing
+    // local is written: only the server moves the byte.
     g.set(
         "SetActionBarToggles",
         lua.create_function(|lua, args: MultiValue| {
@@ -136,7 +86,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 mod tests {
     use crate::script::UiScript;
 
-    /// The argument→bit map, read straight off `0x4e7703 shl al,cl` with `cl = argIndex − 1`.
+    /// Argument N sets bit N-1 (`0x4e7703`).
     #[test]
     fn the_four_arguments_pack_into_bits_0_through_3() {
         let mut s = UiScript::new().unwrap();
@@ -157,8 +107,7 @@ mod tests {
         }
     }
 
-    /// The coercion is `0x6f1c10`, not `if arg then` — and the case that proves it is the one the
-    /// reference's own Options panel produces. `"0"` is truthy in Lua 5.0/5.1; here it is OFF.
+    /// The coercion is `0x6f1c10`: the Options panel's `"0"`, truthy in Lua, is off.
     #[test]
     fn the_arguments_are_coerced_the_binarys_way_not_luas() {
         let mut s = UiScript::new().unwrap();
@@ -170,7 +119,7 @@ mod tests {
             r#"the strings the panel passes: "0" is FALSE, where Lua truthiness says true"#
         );
 
-        // The number arm TRUNCATES toward zero (`0x40a2b0`, RC = chop) — it does not round.
+        // A number truncates toward zero (`0x40a2b0`).
         s.run("SetActionBarToggles(0.5, -0.9, 1.5, 0)").unwrap();
         assert_eq!(
             s.take_action_bar_toggle_sends(),
@@ -178,7 +127,6 @@ mod tests {
             "fractions inside (-1, 1) truncate to 0 and read false; 1.5 truncates to 1"
         );
 
-        // The keyword and letter arms.
         s.run(r#"SetActionBarToggles("on", "off", "enabled", "disabled")"#)
             .unwrap();
         assert_eq!(s.take_action_bar_toggle_sends(), vec![0x05]);
@@ -186,12 +134,10 @@ mod tests {
             .unwrap();
         assert_eq!(s.take_action_bar_toggle_sends(), vec![0x05]);
 
-        // Booleans, the spelling our own Lua uses.
         s.run("SetActionBarToggles(true, false, true, false)")
             .unwrap();
         assert_eq!(s.take_action_bar_toggle_sends(), vec![0x05]);
 
-        // The default arm (`push 0x0` at this call site) — a table, and an unrecognised string.
         s.run(r#"SetActionBarToggles({}, "maybe", 1, 1)"#).unwrap();
         assert_eq!(
             s.take_action_bar_toggle_sends(),
@@ -200,10 +146,6 @@ mod tests {
         );
     }
 
-    /// The shipped `UIOptionsFrame_Save` calls this with **five** arguments
-    /// (`…, ALWAYS_SHOW_MULTIBARS`). The binding's loop stops at four and never fetches the fifth,
-    /// so it reaches neither the byte nor the wire — the reason that option is the only one of the
-    /// five FrameXML saves locally.
     #[test]
     fn a_fifth_argument_is_accepted_and_dropped() {
         let mut s = UiScript::new().unwrap();
@@ -217,9 +159,6 @@ mod tests {
         );
     }
 
-    /// A `Set` starts from **zero** and ORs at most four bits, so any high nibble the server held
-    /// is destroyed by the next post. Faithful, not tidy: it is what two accumulator writes
-    /// image-wide amount to.
     #[test]
     fn a_set_destroys_whatever_the_server_held_above_the_low_nibble() {
         let mut s = UiScript::new().unwrap();
@@ -232,14 +171,11 @@ mod tests {
         );
     }
 
-    /// The getter reads the **app-pushed descriptor byte**, tests only bits 0..3, and returns the
-    /// NUMBER 1 or nil — never a boolean, never `0`.
     #[test]
     fn the_getter_returns_four_ones_or_nils_from_the_pushed_byte() {
         let mut s = UiScript::new().unwrap();
 
-        // Nothing pushed: four nils, and no error. Indistinguishable from a zero byte, exactly as
-        // "no local player" is in the reference (`0x4e7660`).
+        // Nothing pushed reads as a zero byte, as no local player does (`0x4e7660`).
         assert!(s
             .eval::<bool>(
                 "local a,b,c,d = GetActionBarToggles() \
@@ -261,7 +197,7 @@ mod tests {
             "the NUMBER 1 (0x6f3810 pushes tag 3 / double 1.0), never the boolean true"
         );
 
-        // Bits 0x10..0x80 are loaded but never tested — a byte of 0xf0 reads as all four off.
+        // The high nibble is never tested.
         s.set_action_bar_toggles(0xf0);
         assert!(s
             .eval::<bool>(
@@ -271,10 +207,6 @@ mod tests {
             .unwrap());
     }
 
-    /// Round trip: what the setter packs is what the getter reads back — but only once the value
-    /// has travelled through the app's push, because the setter deliberately does not touch the
-    /// local copy. The stale read in the middle is the mechanism, not an oversight (`0x466590`,
-    /// the only writer).
     #[test]
     fn the_setter_does_not_touch_the_local_copy_so_the_read_lags_a_round_trip() {
         let mut s = UiScript::new().unwrap();
@@ -291,7 +223,7 @@ mod tests {
 
         let sent = s.take_action_bar_toggle_sends();
         assert_eq!(sent, vec![0x03]);
-        // The server echoes it back through UPDATE_OBJECT; now the getter agrees.
+        // The server's `SMSG_UPDATE_OBJECT` echo.
         s.set_action_bar_toggles(sent[0]);
         assert!(s
             .eval::<bool>(
@@ -301,8 +233,6 @@ mod tests {
             .unwrap());
     }
 
-    /// No did-it-change gate and no connection test: two calls in a frame are two packets, in
-    /// order. The binding returns zero Lua values either way, so nothing upstream can tell.
     #[test]
     fn every_call_queues_a_packet_and_returns_nothing() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/addon.rs b/crates/benilla-ui/src/script/addon.rs
index 0cd9ba33..31185a6a 100644
--- a/crates/benilla-ui/src/script/addon.rs
+++ b/crates/benilla-ui/src/script/addon.rs
@@ -1,40 +1,8 @@
-//! **The AddOn API** (1188 phase 2) — the eleven globals an addon manager and a demand-loader use,
-//! over a registry the host fills at discovery.
-//!
-//! Every name here is in the 1.12.1 client's own `_G` with origin `engine`
-//! (`reference/1.12-globals.tsv`), so all eleven are ours to implement in Rust and the set is
-//! measured rather than remembered. `SaveAddOns`/`ResetAddOns`/`GetAddOnEnableState` are
-//! deliberately **not** here: they exist only in the *glue* namespace (`Interface\GlueXML\
-//! AddonList.lua`), which is a different `_G` from the in-world one this VM is.
-//!
-//! ## The shapes are the reference's, read off its own call sites
-//!
-//! Not from memory — from `Interface\GlueXML\AddonList.lua` and `FrameXML\UIParent.lua` in the
-//! 1.12 MPQs:
-//!
-//! ```lua
-//! name, title, notes, url, loadable, reason, security, newVersion = GetAddOnInfo(index)
-//! local loaded, reason = LoadAddOn(name)          -- UIParent.lua's UIParentLoadAddOn
-//! ```
-//!
-//! `reason` is a **token**, spliced by the reference into `getglobal("ADDON_"..reason)` — so its
-//! spelling is load-bearing and its full set is enumerable from `GlobalStrings.lua`: `MISSING`,
-//! `DISABLED`, `CORRUPT`, `BANNED`, `INSECURE`, `INTERFACE_VERSION`, `NOT_DEMAND_LOADED`, the
-//! `DEP_*` mirrors of each, and `UNKNOWN_ERROR`. `security` is likewise a token, matched against
-//! `"SECURE"`/`"INSECURE"`/`"BANNED"` by the glue's icon picker.
-//!
-//! **Index or name, everywhere.** Every verb takes either, 1-based, because the reference's do.
-//!
-//! ## The load law lives next door
-//!
-//! Every "can this load, and why not" answer comes from [`super::addon_gate`] — the reference's
-//! `AddOn_CanLoad 0x51e780` as one pure function (decision 1292). What 1191 §6 was missing has
-//! now landed: the version gate is an
-//! exact `== 11200` whose refusal the `checkAddonVersion` CVar suppresses by **actively
-//! resetting** the reason — so `INTERFACE_VERSION` is now enforced here exactly as the client
-//! enforces it, with the *Load out of date AddOns* toggle as the player's escape, instead of
-//! 1191's report-but-never-act interim. The CVar is read live per query (`0x51e780`), which is
-//! why a checkbox click needs nothing but a list repaint.
+//! The in-game AddOn API, the twelve `engine` addon globals of the 1.12 `_G`
+//! (`reference/1.12-globals.tsv`), over a registry the host fills at discovery. A verb that names
+//! an addon takes a 1-based index or a name. `reason` is a token the stock UI splices into
+//! `getglobal("ADDON_"..reason)` (`UIParent.lua:642`), so its spelling is the contract. Verdicts
+//! come from [`super::addon_gate`], the reference's `AddOn_CanLoad` (`0x51e780`).
 
 use std::path::PathBuf;
 
@@ -44,74 +12,51 @@ use super::addon_gate::{can_load, GateRow, Verdict};
 use super::binding_abi::flag;
 use super::Model;
 
-/// A reader for a chain-sourced addon's files, by chain-internal path — what the host seats
-/// through [`super::UiScript::set_addon_chain_reader`] (1957).
+/// Reads a chain-sourced addon's file by its path inside the patch chain.
 pub type AddonChainReader = Box<dyn Fn(&str) -> Option<Vec<u8>>>;
 
-/// [`AddonChainReader`] as the model holds it: shared, so a load can borrow it without holding
-/// the model.
+/// [`AddonChainReader`], shared so a load can call it without holding the model.
 pub(crate) type SharedChainReader = std::rc::Rc<dyn Fn(&str) -> Option<Vec<u8>>>;
 
-/// One addon, as the AddOn API sees it — the host fills this at discovery
-/// ([`super::UiScript::register_addons`]).
+/// One addon as the AddOn API sees it, filled by the host at discovery.
 #[derive(Clone, Debug, Default)]
 pub struct AddOnInfo {
-    /// The folder name. `GetAddOnInfo`'s first return, `ADDON_LOADED`'s `arg1`, and the key every
-    /// other verb resolves a name against (case-insensitively, as the reference does).
+    /// The folder name: `GetAddOnInfo`'s first return and `ADDON_LOADED`'s `arg1`.
     pub name: String,
-    /// `## Title`. `None` when the manifest declares none — and the reference really does return
-    /// nil there, which is why the glue writes `if title then … else SetText(name) end`.
+    /// `## Title`; `None` when absent, which the reference returns as nil.
     pub title: Option<String>,
-    /// `## Notes`.
     pub notes: Option<String>,
-    /// `## URL`.
     pub url: Option<String>,
-    /// `## Secure: 1` — Blizzard's own addons carry it. Drives the `security` token.
+    /// `## Secure: 1`, which Blizzard's own addons carry; drives the `security` token.
     pub secure: bool,
-    /// `## LoadOnDemand: 1`.
     pub load_on_demand: bool,
     /// `## Dependencies` / `## RequiredDeps`.
     pub dependencies: Vec<String>,
     /// Every `## Key: Value` in manifest order, for `GetAddOnMetadata`.
     pub directives: Vec<(String, String)>,
-    /// The `.toc`'s ordered file list — what `LoadAddOn` runs.
+    /// The `.toc`'s file list in order: what `LoadAddOn` runs.
     pub files: Vec<String>,
-    /// `## SavedVariables` — globals restored from, and written to, the account-scoped file.
+    /// `## SavedVariables`: globals restored from and written to the account-wide file.
     pub saved_variables: Vec<String>,
-    /// `## SavedVariablesPerCharacter` — the same, per character. Loaded **second**, so a
-    /// per-character value wins over the account one (`0x51f4b5` then `0x51f53b`).
+    /// `## SavedVariablesPerCharacter`, loaded after the account file so its values win.
     pub saved_variables_per_character: Vec<String>,
-    /// Enable state, from `AddOns.txt`. An addon nobody has ever disabled is enabled.
+    /// Enable state from `AddOns.txt`; an addon never disabled is enabled.
     pub enabled: bool,
-    /// `enabled` as registration found it — the last-SAVED state, which `ResetDisabledAddOns`
-    /// reverts to. Stamped by [`super::UiScript::register_addons`]; callers need not set it.
+    /// The last-saved `enabled`, which `ResetDisabledAddOns` reverts to; set by `register_addons`.
     pub saved_enabled: bool,
-    /// Has it loaded this session?
     pub loaded: bool,
-    /// `## Interface` as the client parses it (`Toc::interface_version` — the leading integer,
-    /// `0` when the line is absent). What the version gate compares (decision 1292).
+    /// `## Interface`'s leading integer, 0 when absent: what the version gate compares.
     pub interface: u32,
-    /// **The server excluded this record from the Lua index space** — `[rec+0x29]`, which
-    /// `AddOn_ReadAddonInfoReply 0x51da70` sets to 1 for every `SMSG_ADDON_INFO` record whose
-    /// `status` byte is **2** (`0x51db84`), and which the array rebuild then drops (`0x51dc4f
-    /// mov al,[ebx+0x29]` / `0x51dc54 jne`). It is written nowhere else but the ctor's zero
-    /// (`0x52059f`), so an addon the reply never covers stays visible.
-    ///
-    /// The reply covers exactly the `## Secure:` addons, in the order the client sent them, and
-    /// the 2006 retail capture answers `status = 2` for all twelve — which is why the stock
-    /// AddOns list shows the player's addons and none of Blizzard's.
+    /// Left out of the Lua index: `[rec+0x29]`, set by `0x51da70` for a `SMSG_ADDON_INFO` status of
+    /// 2 (`0x51db84`) and otherwise only zeroed (`0x52059f`), so an addon the reply skips stays
+    /// visible. A retail server answers 2 for all twelve `Blizzard_*` addons.
     pub hidden: bool,
-    /// The addon's files sit in the player's patch chain, not the AddOns folder — Blizzard's own
-    /// LoadOnDemand addons (`Blizzard_TrainerUI` and its eleven siblings), which the reference
-    /// loads through the same `LoadAddOn` path as a player's (1957). Read through the host's
-    /// chain reader ([`super::UiScript::set_addon_chain_reader`]) at
-    /// `Interface/AddOns/<Name>/<file>`; no folder root is needed for them.
+    /// The files live in the patch chain, not the AddOns folder: Blizzard's twelve LoadOnDemand
+    /// addons, read at `Interface/AddOns/<Name>/<file>` and loaded as a player's addon is.
     pub chain: bool,
 }
 
-/// The verbs' own `Usage:` literals, read out of `.data` rather than reconstructed — the message
-/// an addon's error handler prints, so the spelling is the contract. `%s`-free: each is a whole
-/// string in the image.
+/// Each verb's `Usage:` string as the reference's `.data` holds it; an error handler prints it.
 const USAGE_INFO: &str = "Usage: GetAddOnInfo(index or \"name\")"; // 0x842d68
 const USAGE_METADATA: &str = "Usage: GetAddOnMetadata(index or \"name\", \"variable\")"; // 0x842d90
 const USAGE_DEPENDENCIES: &str = "Usage: GetAddOnDependencies(index or \"name\")"; // 0x842dc8
@@ -121,62 +66,26 @@ const USAGE_LOAD_ON_DEMAND: &str = "Usage: IsAddOnLoadOnDemand(index or \"name\"
 const USAGE_LOADED: &str = "Usage: IsAddOnLoaded(index or \"name\")"; // 0x842e70
 const USAGE_LOAD: &str = "Usage: LoadAddOn(index or \"name\")"; // 0x842e98
 
-/// **The `index or "name"` argument every in-game addon verb opens with — and its two raises.**
-///
-/// All eight bindings (`GetAddOnInfo 0x48e390`, `GetAddOnMetadata 0x48e530`,
-/// `GetAddOnDependencies 0x48e5e0`, `EnableAddOn 0x48e690`, `DisableAddOn 0x48e760`,
-/// `IsAddOnLoadOnDemand 0x48e840`, `IsAddOnLoaded 0x48e8e0`, `LoadAddOn 0x48e980`) open with the
-/// *same eleven instructions*, and the shape has three arms, not one:
-///
-/// ```text
-/// edx=1; call 0x6f34d0            ; lua_isnumber — tag 3 OR a numeric string
-///   je  <string>
-///   call 0x6f3620 / 0x40a2b0      ; lua_tonumber, then double->int32 TRUNCATING toward zero
-///   dec eax                       ; the index is 1-BASED
-///   call 0x51df00                 ; name-at(index0); NULL is the bounds failure
-///   jne <shared>
-///   call 0x51def0                 ; the addon COUNT
-///   luaL_error("AddOn index must be in the range of 1 to %d" /*0x837d70*/, count)
-/// <string>:
-///   call 0x6f3510                 ; lua_isstring
-///   je  <usage>
-///   call 0x6f3690                 ; lua_tostring — used AS GIVEN, never validated here
-/// <usage>:
-///   luaL_error("Usage: <Verb>(index or \"name\")")
-/// ```
-///
-/// **`luaL_error 0x6f4940` does not return** ([`super::binding_abi`]): it longjmps, so both arms
-/// abandon the caller's statement. We answered a placeholder, a `nil` or a silent no-op for every
-/// one of them — the failure mode that module's header names: *"a client that answers `nil` there
-/// keeps executing a statement the real client never finishes."*
-///
-/// Three consequences that are easy to get wrong and are all byte-read:
-///
-/// - **The bound is UNSIGNED** (`0x51df00 cmp ecx,[0xbe1b90]; jb`), so `f(0)` decrements to
-///   `0xFFFFFFFF` and raises by the same route as `f(count+1)`.
-/// - **A numeric STRING is an INDEX**, because `0x6f34d0` coerces one — `GetAddOnInfo("2")` is the
-///   second addon, not an addon named `2`.
-/// - **A name is never checked against the registry by this prologue.** Each verb's own body
-///   decides what a miss means, and they do not agree: `GetAddOnInfo` echoes the name back with
-///   placeholders, `IsAddOnLoaded` answers nil, `GetAddOnDependencies` answers nothing.
+/// The `index or "name"` argument, read by the prologue all eight in-game verbs share
+/// (`GetAddOnInfo 0x48e390`, `GetAddOnMetadata 0x48e530`, `GetAddOnDependencies 0x48e5e0`,
+/// `EnableAddOn 0x48e690`, `DisableAddOn 0x48e760`, `IsAddOnLoadOnDemand 0x48e840`,
+/// `IsAddOnLoaded 0x48e8e0`, `LoadAddOn 0x48e980`). A numeric string is an index. An index out of
+/// range, or a non-string, raises through `luaL_error` (`0x6f4940`), which does not return; a
+/// name passes unchecked, and each verb answers a miss its own way.
 enum AddonKey {
     /// A bounds-checked 0-based position in the registry.
     Index(usize),
-    /// A name exactly as the caller spelled it — unvalidated, per the prologue above.
     Name(String),
 }
 
-/// The prologue itself. `usage` is the verb's own `.data` literal, verbatim.
+/// The prologue; `usage` is the verb's own `.data` string.
 fn addon_key(lua: &Lua, model: &Model, key: &Value, usage: &'static str) -> mlua::Result<AddonKey> {
-    // `lua_isnumber 0x6f34d0` — and `coerce_number` is its exact analogue, numeric strings and all.
+    // `coerce_number` is `lua_isnumber` (`0x6f34d0`), numeric strings included.
     if let Some(n) = lua.coerce_number(key.clone())? {
-        // `_ftol 0x40a2b0` truncates toward zero (not `floor`), then `dec eax`, then an unsigned
-        // compare — so the whole out-of-range family collapses onto one `u32` bound test.
+        // `_ftol` (`0x40a2b0`) truncates; minus one, compared unsigned, so 0 raises like count + 1.
         let index0 = (n as i64 as i32).wrapping_sub(1) as u32 as usize;
-        // **The index space is NOT the registry** (decision 2175). `0x51df00` reads
-        // `[[0xbe1b94] + 4*idx]` — the flat, Title-sorted, hidden-filtered name array — and its
-        // bound is that array's own count `[0xbe1b90]`, which `GetNumAddOns 0x51def0` returns.
-        // The registry list is a different order over a different set.
+        // An index into the sorted, filtered name array, not the registry (`0x51df00` reads
+        // `[[0xbe1b94] + 4*idx]`, bound `[0xbe1b90]`); the message is `0x837d70`'s.
         return match model.addon_index.get(index0) {
             Some(&row) => Ok(AddonKey::Index(row)),
             None => Err(mlua::Error::RuntimeError(format!(
@@ -185,36 +94,21 @@ fn addon_key(lua: &Lua, model: &Model, key: &Value, usage: &'static str) -> mlua
             ))),
         };
     }
-    // `lua_isstring 0x6f3510` → `lua_tostring 0x6f3690`. Lossy for the reason 1193/2138 give: a
-    // 5.0 string is bytes, and a stray one costs a glyph, not the call.
+    // `lua_isstring`, `lua_tostring` (`0x6f3510`, `0x6f3690`); lossy, as a Lua string is bytes.
     match key {
         Value::String(s) => Ok(AddonKey::Name(s.to_string_lossy())),
         _ => Err(mlua::Error::RuntimeError(usage.into())),
     }
 }
 
-/// **Rebuild the Lua index space** — the tail block `[0x51dc30, 0x51dcdf)` of
-/// `AddOn_ReadAddonInfoReply 0x51da70`, and the only place that array is ever built
-/// (decision 2175).
-///
-/// Three properties, all byte-read, all easy to get wrong:
-///
-/// - **The set is filtered.** `0x51dc4f mov al,[ebx+0x29]` / `0x51dc54 jne` drops every record the
-///   server marked `status = 2`. On a stock install that is all twelve `Blizzard_*` addons, which
-///   is why the AddOns list shows only the player's own.
-/// - **The order is by `## Title:`, not by folder name.** Comparator `0x51deb0` resolves both
-///   sides through `AddOn_GetTitle 0x51df20` and falls back to the folder name only when the
-///   record declares no `Title` (`0x51ded0`/`0x51ded6`), then compares with `SStrCmpI` — case
-///   INSENSITIVE. A materially different permutation from the registry's.
-/// - **No reply, no array.** `[0xbe1b90]` starts at 0 and is written nowhere else, so
-///   `GetNumAddOns()` answers 0 until the server replies.
-///
-/// The reference's `qsort 0x73f727` is **not stable**, so two records with equal keys have no
-/// defined relative order there; ours is stable, which is a strict refinement of "undefined" and
-/// cannot disagree with a defined case.
+/// Rebuild the Lua index array as `AddOn_ReadAddonInfoReply` (`0x51da70`) does in its tail,
+/// `[0x51dc30, 0x51dcdf)`, the array's only builder: hidden records dropped (`0x51dc4f`), the
+/// rest sorted case-insensitively by `## Title`, else folder name (`0x51deb0` through
+/// `AddOn_GetTitle 0x51df20`, `SStrCmpI`). Empty until the server replies. The reference's
+/// `qsort` (`0x73f727`) is unstable, which a stable sort refines.
 fn rebuild_index(model: &mut Model) {
     let Some(hidden) = model.addon_info_hidden.as_ref() else {
-        model.addon_index = Vec::new(); // no reply yet — the reference's own empty array
+        model.addon_index = Vec::new(); // no reply yet, as in the reference
         return;
     };
     let hidden: std::collections::HashSet<&str> = hidden.iter().map(String::as_str).collect();
@@ -231,8 +125,7 @@ fn rebuild_index(model: &mut Model) {
     model.addon_index = index;
 }
 
-/// A name → a position, folded. Names compare case-insensitively for the same reason dependency
-/// lookup does: a `.toc` may spell a name any way.
+/// A name's registry row, case-insensitive: a `.toc` may spell a name any way.
 fn by_name(model: &Model, name: &str) -> Option<usize> {
     model
         .addons
@@ -240,7 +133,7 @@ fn by_name(model: &Model, name: &str) -> Option<usize> {
         .position(|a| a.name.eq_ignore_ascii_case(name))
 }
 
-/// A validated key → a row, for the verbs whose miss answer is "not found" rather than a raise.
+/// A key's registry row, for the verbs that answer an unknown name rather than raise.
 fn row_of(model: &Model, key: &AddonKey) -> Option<usize> {
     match key {
         AddonKey::Index(i) => Some(*i),
@@ -248,8 +141,7 @@ fn row_of(model: &Model, key: &AddonKey) -> Option<usize> {
     }
 }
 
-/// Lower the registry into the gate's rows — ONE adapter, so every verb consults the same law
-/// ([`super::addon_gate`], decision 1292) over the same facts.
+/// The registry as [`super::addon_gate`] rows, the one input every verb's verdict reads.
 fn gate_rows(model: &Model) -> Vec<GateRow<'_>> {
     model
         .addons
@@ -265,10 +157,8 @@ fn gate_rows(model: &Model) -> Vec<GateRow<'_>> {
         .collect()
 }
 
-/// The live `checkAddonVersion` read — the gate's CVar half, re-read per query like the
-/// reference's (`IsAddonVersionCheckEnabled 0x51f180` inside `AddOn_CanLoad`). An absent
-/// table (a bare test VM, or a query before the host's seed) answers the registrar default:
-/// check ON, `"1"`.
+/// `checkAddonVersion`, read per query as `IsAddonVersionCheckEnabled` (`0x51f180`) does; unset,
+/// it is the registered default `"1"`, check on.
 fn version_check(model: &Model) -> bool {
     model
         .cvars
@@ -276,10 +166,8 @@ fn version_check(model: &Model) -> bool {
         .is_none_or(|s| s.value != "0")
 }
 
-/// [`can_load`] over the registry, in the in-game flavour (`dl=1` — the surface these verbs
-/// are): the addon's own verdict, with the loaded short-circuit the in-game `GetAddOnInfo`
-/// applies (`0x48e390`: an already-loaded addon reports loadable/nil before the gate runs, so
-/// flipping its toggle mid-session cannot retroactively mark it unloadable).
+/// [`can_load`] in the in-game flavour (`dl=1`). A loaded addon is loadable before the gate
+/// runs, as in `0x48e390`, so disabling it mid-session does not mark it unloadable.
 fn verdict(model: &Model, i: usize) -> Verdict {
     if model.addons[i].loaded {
         return Verdict::Loadable;
@@ -304,8 +192,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     g.set(
         "GetNumAddOns",
         lua.create_function(|lua, ()| {
-            // `0x51def0` is six bytes: `return [0xbe1b90]` — the count of the SORTED array, not the
-            // registry size (decision 2175).
+            // `0x51def0` returns `[0xbe1b90]`, the sorted array's count, not the registry's.
             Ok(lua
                 .app_data_ref::<Model>()
                 .expect("model")
@@ -314,48 +201,19 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `name, title, notes, enabled, loadable, reason, security` — SEVEN values, and slot 4 is
-    // **`enabled`**, not `url`.
-    //
-    // **The client registers `GetAddOnInfo` TWICE, as two different functions**, and this is the
-    // in-game one. Glue `0x46d460` returns EIGHT with `url` at slot 4 and `newVersion` at 8;
-    // in-game `0x48e390` returns SEVEN with `enabled` at slot 4 and no `url` at all. They differ in
-    // behaviour too — the in-game one passes `dl=1`,
-    // so `NOT_DEMAND_LOADED` is reachable here and never from glue, and it short-circuits an
-    // already-loaded addon to `1, nil` before the gate.
-    //
-    // We shipped the GLUE shape in the IN-GAME VM. Slots 5/6/7 aligned by luck; slot 4 did not, and
-    // it is the one the ecosystem reads:
-    //
-    //     local name, _, _, enabled, loadable = GetAddOnInfo(major)   -- AceLibrary-1.0:400
-    //
-    // `## URL` is rare, so `enabled` came back nil for nearly every addon and Ace's
-    // `if enabled and loadable` refused to load its own dependency. 70 corpus folders reach it
-    // (AceLibrary/AceAddon replicated — one library, which is what makes it wide rather than
-    // narrow). Nothing errored: a nil where a flag belongs is a legal Lua value.
-    //
-    // `enabled` is the number 1 or nil, never boolean `true` — every push in these functions is
-    // `lua_pushnumber(1.0)` via `0x6f3810`, with no `lua_pushboolean` anywhere. Same for
-    // `loadable`. `flag` already answers in that shape.
-    //
-    // `url` is not lost, it moves to where the client keeps it in-game: `GetAddOnMetadata(name,
-    // "URL")`.
+    // In-game `0x48e390` returns seven: `name, title, notes, enabled, loadable, reason,
+    // security`, the flags the number 1 or nil (`lua_pushnumber` via `0x6f3810`). The glue's
+    // `0x46d460` returns eight, `url` fourth; in-game the URL is `GetAddOnMetadata(name, "URL")`.
     g.set(
         "GetAddOnInfo",
         lua.create_function(|lua, key: Value| {
             let model = lua.app_data_ref::<Model>().expect("model");
-            // **The two argument forms miss differently** (decision 1845). The numeric one cannot
-            // reach here at all — [`addon_key`] has already raised the range error for it.
             let i = match addon_key(lua, &model, &key, USAGE_INFO)? {
                 AddonKey::Index(i) => i,
                 AddonKey::Name(name) => match by_name(&model, &name) {
                     Some(i) => i,
-                    // The STRING form is not existence-checked: it answers seven placeholders, two
-                    // of which are not nil — and **slot 1 is the caller's own string echoed back**
-                    // (`0x48e401`, non-NULL by `lua_isstring`). We used to answer the literal
-                    // `"NoSuchAddon"`, which was an illustrative example, not a constant
-                    // the image contains. Slot 4 is `enabled` in-game (the glue table's fourth is
-                    // `url`, and its eighth is an appended `newVersion` — nothing shifts).
+                    // An unknown name answers placeholders, the caller's own string first
+                    // (`0x48e401`).
                     None => {
                         return Ok(MultiValue::from_vec(vec![
                             lua_str(lua, &name)?,
@@ -369,9 +227,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     }
                 },
             };
-            // The one arbiter (decision 1292): loaded short-circuit, then `AddOn_CanLoad` in the
-            // in-game flavour — so NOT_DEMAND_LOADED and INTERFACE_VERSION are reachable here,
-            // exactly as `0x48e390` reports them.
             let reason = verdict(&model, i).token();
             let a = &model.addons[i];
             Ok(MultiValue::from_vec(vec![
@@ -394,8 +249,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, key: Value| {
             let model = lua.app_data_ref::<Model>().expect("model");
             let key = addon_key(lua, &model, &key, USAGE_LOADED)?;
-            // `0x51e6f0` takes the resolved NAME and answers `[rec+0x18]`; a miss pushes nil
-            // (`0x48e95b`), so an unknown name is one value, not a raise.
+            // `0x51e6f0` answers the record's loaded byte `[rec+0x18]`; an unknown name pushes nil
+            // (`0x48e95b`).
             Ok(flag(
                 row_of(&model, &key).is_some_and(|i| model.addons[i].loaded),
             ))
@@ -413,15 +268,13 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // Varargs of dependency names — the glue folds them into a tooltip line with `AddonTooltip_
-    // BuildDeps(GetAddOnDependencies(id))`, so "none" is zero returns, not an empty string.
+    // One return per dependency, none for none (the glue's `AddonList.lua:137` takes varargs).
     g.set(
         "GetAddOnDependencies",
         lua.create_function(|lua, key: Value| {
             let model = lua.app_data_ref::<Model>().expect("model");
             let key = addon_key(lua, &model, &key, USAGE_DEPENDENCIES)?;
-            // A name the registry does not hold reaches `0x51e350` and comes back NULL, which
-            // takes `0x48e68a` — zero values, no raise.
+            // An unknown name comes back NULL from `0x51e350` and answers nothing (`0x48e68a`).
             let Some(i) = row_of(&model, &key) else {
                 return Ok(MultiValue::new());
             };
@@ -433,15 +286,13 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The raw `## Key: Value`, by key — how an addon reads its own `## Version`.
+    // The raw `## Key: Value` by key, as an addon reads its own `## Version`.
     g.set(
         "GetAddOnMetadata",
         lua.create_function(|lua, (key, field): (Value, Value)| {
             let model = lua.app_data_ref::<Model>().expect("model");
             let key = addon_key(lua, &model, &key, USAGE_METADATA)?;
-            // Argument 2 is gated by its own `lua_isstring` (`0x48e59c`, edx=2) onto the SAME
-            // usage raise (`0x48e5cb`) — so `GetAddOnMetadata("Foo")` raises rather than
-            // answering nil.
+            // A missing or non-string argument 2 raises the same `Usage:` (`0x48e59c`, `0x48e5cb`).
             let field = super::binding_abi::string_arg(lua, field, USAGE_METADATA)?;
             let Some(i) = row_of(&model, &key) else {
                 return Ok(Value::Nil);
@@ -457,14 +308,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // **One argument, index or name — the `(character, index)` form is GLUE-ONLY** (in-game
-    // `0x48e690`/`0x48e760` read arg1 alone and key the store on `0x5abdc0()`, the logged-in
-    // character; the two-argument shape belongs to the glue registrars `0x46d7b0`/`0x46d8a0`, and
-    // our glue screen is native — no caller exists).
-    // A numeric index out of range is a **Lua error** in the reference (`luaL_error` via
-    // `0x51df00`); an unknown NAME is where we diverge, disclosed: the reference creates a
-    // phantom enable-hash entry for the typo, we no-op — the safer direction, and `resolve`'s
-    // established semantics (1191).
+    // One argument, keyed on the logged-in character (`0x48e690`, `0x48e760`, via `0x5abdc0`);
+    // the `(character, index)` form is the glue's (`0x46d7b0`, `0x46d8a0`). Deviation: an unknown
+    // name is a no-op, where the reference adds an enable-hash entry for it, so that a typo leaves
+    // no row behind.
     for (name, on, usage) in [
         ("EnableAddOn", true, USAGE_ENABLE),
         ("DisableAddOn", false, USAGE_DISABLE),
@@ -482,8 +329,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // No arguments read at all (`0x48e720`/`0x48e7f0` — the loop re-evaluates the bound and the
-    // current character each iteration; ours is one pass over the same store).
+    // No arguments read (`0x48e720`, `0x48e7f0`).
     for (name, on) in [("EnableAllAddOns", true), ("DisableAllAddOns", false)] {
         g.set(
             name,
@@ -497,13 +343,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // `ResetDisabledAddOns 0x48e830` — **revert-to-last-saved**: the reference destroys the
-    // current character's enable hash and reloads it from the on-disk `AddOns.txt` — so unsaved
-    // toggles of BOTH polarities revert,
-    // and a disable already on disk stays disabled. Within one session the current character's
-    // file is immutable until the shutdown tail writes it (the glue can only edit it with no
-    // session up), so the registration-time `enabled` — read from that very file — IS the
-    // last-saved state, and reverting to it is the same operation without re-reading disk.
+    // `0x48e830` reloads the enable state from `AddOns.txt`, which is unchanged until the shutdown
+    // write, so reverting to the state as registered is the same thing.
     g.set(
         "ResetDisabledAddOns",
         lua.create_function(|lua, ()| {
@@ -515,7 +356,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // loaded, reason — see `load_addon`.
     g.set(
         "LoadAddOn",
         lua.create_function(|lua, key: Value| {
@@ -543,15 +383,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Load one addon on demand, dependencies first — `AddOn_Load 0x51f240` reached from `LoadAddOn`
-/// rather than from the startup sweep.
-///
-/// **This runs inside a Lua binding, synchronously**, which is the whole reason the loader takes
-/// `&Lua` (see `crate::loader::load_into`): the reference's `UIParentLoadAddOn` does
-/// `local loaded = LoadAddOn(name)` and touches the addon's frames on the next line, so a deferred
-/// load would be a different function wearing the same name.
-///
-/// `Err` carries the reference's own reason token.
+/// `AddOn_Load` (`0x51f240`), dependencies first; `Err` is the reason token. Synchronous inside
+/// the Lua call, as stock callers use the addon on the next line (`UIParent.lua:577`).
 fn load_addon(lua: &Lua, i: usize) -> Result<(), String> {
     let (name, root, files, deps, already, chain, chain_reader) = {
         let model = lua.app_data_ref::<Model>().expect("model");
@@ -567,21 +400,17 @@ fn load_addon(lua: &Lua, i: usize) -> Result<(), String> {
         )
     };
     if already {
-        return Ok(()); // the reference answers a redundant load with success, not an error
+        return Ok(()); // a redundant load succeeds, as in the reference
     }
-    // The one arbiter (decision 1292): the reference's own shape — `LoadAddOn 0x48e980` refuses
-    // through `AddOn_CanLoad` (via `AddOn_Load`'s step 3) and re-derives the reason from the
-    // same gate on failure. The version gate is in here now: an out-of-date addon demand-loads
-    // only under force-load, exactly as `0x48ea8c` records.
+    // `LoadAddOn` (`0x48e980`) refuses through `AddOn_CanLoad` and takes the reason from the same
+    // gate; an out-of-date addon loads only with the version check off (`0x48ea8c`).
     {
         let model = lua.app_data_ref::<Model>().expect("model");
         if let refused @ Verdict::Refused { .. } = verdict(&model, i) {
             return Err(refused.token().expect("a refusal always carries a token"));
         }
     }
-    // Where this addon's bytes come from: the AddOns folder for a player's addon, the patch chain
-    // for Blizzard's own LoadOnDemand addons (`AddOnInfo::chain`). Either absent is `MISSING` —
-    // a hermetic capture has no folder, a bare VM has no chain.
+    // An absent source (a capture has no folder, a bare VM no chain) is `MISSING`.
     let read: Reader = if chain {
         let Some(reader) = chain_reader else {
             return Err("MISSING".into());
@@ -594,37 +423,17 @@ fn load_addon(lua: &Lua, i: usize) -> Result<(), String> {
         Box::new(move |req: &str| read_under(&root, req))
     };
 
-    // ── The *loaded* stamp goes HERE, before the dependency walk — and it is the whole reason a
-    // dependency cycle terminates (decision 2139).
-    //
-    // `AddOn_Load 0x51f240` carries **no re-entrancy guard of its own**: an image-wide census of
-    // the visiting byte `[UIADDON+0x2d]` puts every live site inside `AddOn_CanLoad 0x51e780`
-    // (writers `0x5205a8`/`0x51e8ae`/`0x51e8f1`, reader `0x51e812`) and none in the loader. What
-    // bounds the recursion is this byte: `0x51f313 mov byte [rec+0x18],1` sits between
-    // `0x51f311 test eax,eax` and `0x51f317 jbe` — a flag-neutral, therefore **unconditional**
-    // store — in the dependency loop's PREAMBLE, ahead of both the OptionalDeps body
-    // (`0x51f320`) and the required-dep body (`0x51f343`). So a re-entered frame hits the
-    // already-loaded early-out at `0x51f2d6`/`0x51f2db` and returns 1.
-    //
-    // We stamped it *after* the recursion instead, which is why `LoadAddOn` on two mutually
-    // dependent LoadOnDemand addons overflowed the stack and took the process down with SIGABRT —
-    // not a Lua error, so nothing `pcall` or the error handler could reach.
-    //
-    // **The gate strictly dominates this store** (`0x51f2fa`/`0x51f301` precede `0x51f313`), so a
-    // refusal leaves the byte clear and the load stays retryable. That ordering is why the stamp
-    // is here and not at the top of the function.
-    //
-    // **The consequence is real and is the reference's own**: inside a cycle an addon is flagged
-    // loaded before its own files run, so `IsAddOnLoaded("A")` answers 1 for the whole of B's
-    // execution, and `ADDON_LOADED` fires B before A. That is not a wart we are copying blindly —
-    // it is what makes the recursion finite.
+    // Loaded is stamped after the gate (`0x51f2fa`), so a refusal stays retryable, and before the
+    // dependencies, which is what ends a cycle: `AddOn_Load` has no re-entrancy guard, but its
+    // store `0x51f313` precedes both dependency loops (`0x51f320`, `0x51f343`), so a re-entry
+    // takes the loaded early-out (`0x51f2d6`). Inside a cycle, then, `IsAddOnLoaded("A")` is 1
+    // while B runs and `ADDON_LOADED` fires B before A, as in the reference.
     {
         let mut model = lua.app_data_mut::<Model>().expect("model");
         model.addons[i].loaded = true;
     }
 
-    // The gate said yes, so a dependency failing HERE is a load-time failure (its files errored,
-    // it was uninstalled mid-session) — still mapped to the DEP_ mirror, applied once.
+    // Past the gate, a dependency that fails to load maps to its `DEP_` reason.
     for dep in &deps {
         let d = {
             let model = lua.app_data_ref::<Model>().expect("model");
@@ -643,8 +452,7 @@ fn load_addon(lua: &Lua, i: usize) -> Result<(), String> {
                 if !loaded {
                     load_addon(lua, d).map_err(|r| {
                         if r.starts_with("DEP_") {
-                            // The prefix applies exactly once at any nesting depth
-                            // (`0x51e8ce`/`0x51e8cf`).
+                            // `DEP_` applies once at any depth (`0x51e8ce`, `0x51e8cf`).
                             r
                         } else {
                             format!("DEP_{r}")
@@ -656,25 +464,17 @@ fn load_addon(lua: &Lua, i: usize) -> Result<(), String> {
     }
 
     run_files(lua, &name, &read, &files);
-    // `Bindings.xml` (1188 phase 4) attaches here, between the files and the saved variables.
+    // `Bindings.xml` loads between the files and the saved variables.
     load_bindings(lua, &name, &read);
     load_saved_variables(lua, i);
-    // The verified position: after the files, at the end of this addon's load (`0x51f5ad`).
+    // `ADDON_LOADED` closes the addon's load (`0x51f5ad`).
     super::event::fire_global(lua, "ADDON_LOADED", &[super::ScriptValue::Str(name)]);
     Ok(())
 }
 
-/// Register this addon's `Bindings.xml` into the key-binding table (decision 1188 phase 4) — the
-/// demand-load twin of what the host's startup walk does at the same position.
-///
-/// **Position is the mechanism here too**: the reference loads it at `0x51f400`, after the
-/// addon's own `.toc` files and before its saved variables. After the files, because a binding's
-/// body calls the functions those files define; before the saved variables, because they are the
-/// next step of the same verified sequence and `ADDON_LOADED` closes it.
-///
-/// A missing file is the normal case and silent — most addons declare no bindings. `Bindings.xml`
-/// is the reference's own spelling and the only one probed; the sandbox is [`read_under`]'s, so
-/// this reads exactly what the addon's other files may read and nothing else.
+/// Register the addon's `Bindings.xml` where the reference loads it (`0x51f400`): after the
+/// addon's files, whose functions its bindings call, and before its saved variables. A missing
+/// file is the normal case and silent; it reads through the same sandbox as the other files.
 fn load_bindings(lua: &Lua, name: &str, read: &Reader) {
     let path = crate::loader::join_ref(name, "Bindings.xml");
     let Some(bytes) = read(&path) else {
@@ -682,24 +482,14 @@ fn load_bindings(lua: &Lua, name: &str, read: &Reader) {
     };
     match crate::bindings_xml::parse(&crate::source::decode(&bytes)) {
         Ok(bindings) => super::keybind::register_addon_bindings(lua, name, &bindings),
-        // Reported rather than swallowed, like a failed saved-variables chunk: a binding file that
-        // stopped parsing means keys silently stop working, which is exactly what a player cannot
-        // diagnose on their own.
+        // Reported, not swallowed: otherwise a broken binding file leaves keys dead silently.
         Err(e) => log_error(lua, &format!("{name}/Bindings.xml: {e}")),
     }
 }
 
-/// Execute this addon's saved-variables files — **account first, per-character second**, which is
-/// the reference's order (`0x51f4b5` then `0x51f53b`) and therefore why a per-character value wins.
-///
-/// Each file is *executed as a Lua chunk in the shared global state*, not parsed: the reference
-/// does exactly that (`0x704bc0` names the chunk, `0x704ae0` runs `luaL_loadbuffer` +
-/// `lua_pcall`), with no `setfenv` and no restricted environment. A missing file is a silent
-/// no-op (`0x51f4a9`, `0x51f530`) — it is the normal first-run case.
-///
-/// **Position is the mechanism**: this runs after the addon's own files (which assign the
-/// file-scope defaults) and before `ADDON_LOADED` (whose handlers are specified to see the
-/// restored value). Reverse either and the saved value can never win.
+/// Run the addon's saved-variables files, account then per-character (`0x51f4b5`, `0x51f53b`),
+/// as chunks in the shared globals with no `setfenv` (`0x704bc0`, `0x704ae0`), between its files
+/// and `ADDON_LOADED` so saved values win; a missing file is skipped (`0x51f4a9`, `0x51f530`).
 fn load_saved_variables(lua: &Lua, i: usize) {
     let (name, account, character, has_account, has_character) = {
         let model = lua.app_data_ref::<Model>().expect("model");
@@ -714,7 +504,7 @@ fn load_saved_variables(lua: &Lua, i: usize) {
     };
     for (dir, declared) in [(account, has_account), (character, has_character)] {
         if !declared {
-            continue; // an addon that declares nothing has no file, even if one is lying there
+            continue; // declares none: no file is read, even if one exists
         }
         let Some(dir) = dir else { continue };
         let path = dir.join(format!("{name}.lua"));
@@ -722,7 +512,7 @@ fn load_saved_variables(lua: &Lua, i: usize) {
             Ok(bytes) => bytes,
             Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue, // the first-run case
             Err(e) => {
-                // Present but unreadable is not "absent": hold it, like a file that will not run.
+                // Present but unreadable is held, like a file that will not run.
                 log_error(lua, &format!("{}: {e}", path.display()));
                 let mut model = lua.app_data_mut::<Model>().expect("model");
                 if !model.held_saved_files.contains(&path) {
@@ -736,10 +526,8 @@ fn load_saved_variables(lua: &Lua, i: usize) {
             &bytes,
             &crate::script::addon_chunk_name(&name.to_string(), &format!("{name}.lua")),
         ) {
-            // The reference fails this silently. We do not: a settings file that stopped parsing
-            // is exactly the thing a player needs told, and the file is left on disk untouched —
-            // held, so the shutdown write does not replace it with the defaults this session is
-            // running on (`UiScript::hold_saved_file`).
+            // Deviation: the reference fails silently; we report it, as a player needs to know,
+            // and hold the file so the shutdown write keeps it.
             log_error(lua, &format!("{}: {e}", path.display()));
             let mut model = lua.app_data_mut::<Model>().expect("model");
             if !model.held_saved_files.contains(&path) {
@@ -749,27 +537,19 @@ fn load_saved_variables(lua: &Lua, i: usize) {
     }
 }
 
-/// Run one addon's `.toc`-listed files, in listed order — the demand-load twin of the host's
-/// `Addon::load_files`, and deliberately the same rules: `.lua` is a chunk, anything else is
-/// FrameXML, and every reference resolves against the *including file's* directory (1186) inside
-/// the AddOns root as the sandbox.
-/// One addon's byte source, by a path relative to the AddOns root (`<Name>/<file>`) — the folder
-/// reader for a player's addon, the chain reader for a Blizzard LoadOnDemand one.
+/// One addon's byte source by path under the AddOns root (`<Name>/<file>`): the folder for a
+/// player's addon, the patch chain for a Blizzard LoadOnDemand one.
 type Reader = Box<dyn Fn(&str) -> Option<Vec<u8>>>;
 
+/// Run the addon's `.toc` files in order, by the startup walk's rules: `.lua` is a chunk,
+/// anything else FrameXML, each path resolved against the including file's directory.
 fn run_files(lua: &Lua, name: &str, read: &Reader, files: &[String]) {
     let provider = |req: &str| -> Option<Vec<u8>> { read(req) };
     for file in files {
         let path = crate::loader::join_ref(name, file);
         let Some(bytes) = read(&path) else {
-            // **A manifest entry the package does not ship is the PACKAGE's defect** — 1450's
-            // rule, and until 2107 this path had its own copy of it that said the opposite.
-            // The reference logs `Couldn't open %s` and carries on
-            // (`diagnostics::record_load_failure`'s doc has the bytes), so the addon still loads
-            // and `IsAddOnLoaded` still answers 1; the miss is retained and warned, never a
-            // script error. It cost 61 corpus addons their session-start row: FuBar's
-            // `LoadLoadOnDemandPlugins` demand-loads 55 plugins whose `.toc`s list a koKR
-            // localization file none of them ships.
+            // The reference logs `Couldn't open %s` and carries on, so the addon still loads and
+            // `IsAddOnLoaded` answers 1; the miss is warned, never a script error.
             load_miss(lua, name, file);
             continue;
         };
@@ -785,18 +565,14 @@ fn run_files(lua: &Lua, name: &str, read: &Reader, files: &[String]) {
         let doc = match crate::framexml::parse(&crate::source::decode(&bytes)) {
             Ok(d) => d,
             Err(e) => {
-                // The walk's severity for the same thing: a document that will not parse is a
-                // load failure, not a raise — the reference answers it with a `FrameXML.log` line
-                // and silence (`Couldn't parse XML in %s` `0x846fd8`, sink severity 2).
+                // A document that will not parse is a load failure, not a raise: the reference
+                // logs `Couldn't parse XML in %s` (`0x846fd8`) to `FrameXML.log` and goes on.
                 load_failure(lua, &format!("{name}/{file}: {e}"));
                 continue;
             }
         };
         let report = crate::loader::load_into(lua, &doc, &path, &provider);
-        // The warnings were dropped on the floor here until 2135 — an unresolved `inherits=`, a
-        // template of the wrong kind, an attribute nobody reads: the addon loads "clean", paints
-        // nothing, and the one thing that knew why was a `LoadReport` that went out of scope.
-        // They carry the `<Addon>/<file>` prefix because a bare loader warning names no document.
+        // Warnings take the `<Addon>/<file>` prefix; a bare loader warning names no document.
         for w in report.warnings {
             crate::script::diagnostics::record_warning(lua, &format!("{name}/{file}: {w}"));
         }
@@ -806,35 +582,25 @@ fn run_files(lua: &Lua, name: &str, read: &Reader, files: &[String]) {
     }
 }
 
-/// A `.toc` line naming a file the package does not contain, classified the one way
-/// ([`crate::script::diagnostics::record_load_failure`]) and logged the one severity (1450: a
-/// player's addon is never an ERROR of ours).
-///
-/// Both halves are the startup walk's, verbatim in effect: the walk pairs its `warn!` with
-/// `report_load_failure`, and this pairs the host warning channel — which the app drains at
-/// `warn!` — with the same retention call. What it deliberately does **not** touch is
-/// [`Model::errors`], the instruments' script-error channel: nothing raised.
+/// A `.toc` file the package does not ship: a load failure at warning severity, as the startup
+/// walk records it, and never in [`Model::errors`], since nothing raised.
 fn load_miss(lua: &Lua, name: &str, file: &str) {
     load_failure(lua, &format!("{name}/{file}: not found"));
 }
 
-/// Record + say out loud, the pair [`log_error`]'s louder sibling makes for a failure that
-/// **raised**. `benilla-ui` has no logger of its own, so the second half goes on the host's
-/// non-fatal warning channel, which the app drains at `warn!` — the walk's own severity for the
-/// same failure.
+/// Record a load failure that did not raise, and warn on the host channel the app drains at
+/// `warn!` (`benilla-ui` has no logger).
 fn load_failure(lua: &Lua, msg: &str) {
     let msg = format!("LoadAddOn: {msg}");
     crate::script::diagnostics::record_load_failure(lua, &msg);
-    // `warn_host_only`, not `record_warning`: `record_load_failure` above has already retained
-    // this exact sentence as a `Load` row, which is the truer kind (the addon is not running).
+    // `warn_host_only`, not `record_warning`: the line above already kept it as a `Load` row.
     lua.app_data_mut::<Model>()
         .expect("model")
         .warn_host_only(msg);
 }
 
-/// `root/rel`, refusing to escape `root` — the AddOns-root sandbox (1186), lexical and applied
-/// before any filesystem call. `join_ref` has already resolved the path, so an escape survives as
-/// a leading `..` and is what the `Normal`-component test rejects.
+/// Read `root/rel`, refusing a path that leaves `root`, lexically before any filesystem call;
+/// `join_ref` has already resolved the path, so an escape shows as a leading `..`.
 fn read_under(root: &std::path::Path, rel: &str) -> Option<Vec<u8>> {
     let rel = std::path::Path::new(rel);
     if rel
@@ -846,9 +612,8 @@ fn read_under(root: &std::path::Path, rel: &str) -> Option<Vec<u8>> {
     std::fs::read(root.join(rel)).ok()
 }
 
-/// Run a chunk that came off disk, from `&Lua` — [`crate::script::UiScript::run_chunk`]'s body for
-/// the demand-load path, which never holds a `UiScript` (1191 §4). Bytes and a BOM strip, for the
-/// reasons in [`crate::source`].
+/// Run a chunk read off disk, BOM stripped: [`crate::script::UiScript::run_chunk`] for the
+/// demand-load path, which has no `UiScript`.
 fn run_chunk(lua: &Lua, bytes: &[u8], name: &str) -> mlua::Result<()> {
     lua.load(crate::source::chunk(bytes))
         .set_name(name)
@@ -856,11 +621,8 @@ fn run_chunk(lua: &Lua, bytes: &[u8], name: &str) -> mlua::Result<()> {
         .exec()
 }
 
-/// Record a demand-load failure the way the startup walk records its own
-/// ([`super::UiScript::report_script_error`]): retained as a Load row, and dispatched to the
-/// player's error handler — plus the host drain the instruments read. It went to that drain alone
-/// until now, so a `LoadAddOn` whose file raised surfaced as a terminal line and nothing a player
-/// could see.
+/// Record a demand-load error as the startup walk does ([`super::UiScript::report_script_error`]):
+/// a `Load` row, dispatched to the player's error handler and put on the host drain.
 fn log_error(lua: &Lua, msg: &str) {
     let msg = format!("LoadAddOn: {msg}");
     super::diagnostics::record_load_failure(lua, &msg);
@@ -869,16 +631,13 @@ fn log_error(lua: &Lua, msg: &str) {
     model.errors.push(msg);
 }
 
-/// The host's push: the discovered registry and the root its files live under.
+/// The host's side: the registry, where its files live, and what to write back.
 impl super::UiScript {
-    /// Seat the host's chain reader — what a chain-sourced addon (`AddOnInfo::chain`) is read
-    /// through, by chain-internal path (1957).
+    /// Seat the reader chain-sourced addons (`AddOnInfo::chain`) are read through.
     pub fn set_addon_chain_reader(&self, reader: AddonChainReader) {
         self.model_mut().addons_chain_reader = Some(std::rc::Rc::from(reader));
     }
-    /// Replace the AddOn registry — called once at world entry, after discovery
-    /// ([`crate::script`]'s `register_bindings` is the same shape: the host owns the facts, the
-    /// engine owns the verbs).
+    /// Replace the AddOn registry; called once at world entry, after discovery.
     pub fn register_addons(
         &mut self,
         mut addons: Vec<AddOnInfo>,
@@ -886,9 +645,7 @@ impl super::UiScript {
         saved_account: Option<PathBuf>,
         saved_character: Option<PathBuf>,
     ) {
-        // The registration-time enable state IS the last-saved state (the host read it off the
-        // enable file moments ago) — snapshot it here so `ResetDisabledAddOns` has its revert
-        // point and no caller has to remember to provide one.
+        // The enable state as registered is the last-saved one, `ResetDisabledAddOns`'s target.
         for a in &mut addons {
             a.saved_enabled = a.enabled;
         }
@@ -897,31 +654,21 @@ impl super::UiScript {
         model.addons_root = root;
         model.addons_saved_account = saved_account;
         model.addons_saved_character = saved_character;
-        // The reference builds the registry at glue login and the Lua array only when the server
-        // answers; our registry is built at world entry, by which time the reply has long landed.
-        // So the rebuild runs here, off whatever the reply said — and does nothing at all if no
-        // reply ever came, which is the reference's own pre-reply state.
+        // The reference builds the array when the server's reply lands, before world entry, so
+        // the rebuild runs here; with no reply the array stays empty, as there.
         rebuild_index(&mut model);
     }
 
-    /// **The `SMSG_ADDON_INFO` (`0x2ef`) verdict** — the names the server answered `status = 2`
-    /// for, which the client stores as `[rec+0x29] = 1` and which the Lua index array then drops
-    /// (decision 2175).
-    ///
-    /// The reply carries no count and no names: it is one record per `## Secure:` addon, in the
-    /// order the client itself sent them in `CMSG_AUTH_SESSION`, so the caller does the pairing
-    /// and hands us the names (`0x51da70`).
-    /// Calling this with an empty slice is meaningful and different from never calling it: it
-    /// records that a reply arrived and hid nothing.
+    /// Record the `SMSG_ADDON_INFO` (`0x2ef`) verdict, the addons answered status 2; the caller
+    /// pairs the nameless records with `CMSG_AUTH_SESSION`'s order (`0x51da70`). An empty slice
+    /// is a reply that hid nothing, unlike no call at all.
     pub fn note_addon_info_reply(&mut self, hidden: &[String]) {
         let mut model = self.model_mut();
         model.addon_info_hidden = Some(hidden.iter().map(|n| n.to_ascii_lowercase()).collect());
         rebuild_index(&mut model);
     }
 
-    /// Execute one addon's saved-variables files, at the startup walk's verified position — the
-    /// twin of what [`load_saved_variables`] does inside `LoadAddOn`, so both halves restore state
-    /// the same way.
+    /// Run one addon's saved-variables files at the startup walk's position, as `LoadAddOn` does.
     pub fn load_addon_saved_variables(&mut self, name: &str) {
         let i = self
             .model_ref()
@@ -933,12 +680,8 @@ impl super::UiScript {
         }
     }
 
-    /// Every **loaded** addon that declares saved variables, as
-    /// `(name, account-scoped names, per-character names)` — what the host writes at shutdown.
-    ///
-    /// The gate is *loaded*, not a dirty bit: the reference gates its write on the record's loaded
-    /// byte (`0x51f711`) and has no dirty tracking at all. An addon that never loaded this session
-    /// has no globals to write, and writing it would blank the file it never read.
+    /// `(name, account names, per-character names)` to write at shutdown, for each loaded addon
+    /// that declares any: the reference gates the write on the loaded byte (`0x51f711`).
     pub fn addon_saved_variable_sets(&self) -> Vec<(String, Vec<String>, Vec<String>)> {
         self.model_ref()
             .addons
@@ -957,8 +700,7 @@ impl super::UiScript {
             .collect()
     }
 
-    /// Mark an addon loaded — the host's startup walk reporting what it ran, so `IsAddOnLoaded`
-    /// answers for the startup half exactly as it does for the `LoadAddOn` half.
+    /// Mark an addon the startup walk ran as loaded, for `IsAddOnLoaded`.
     pub fn mark_addon_loaded(&mut self, name: &str) {
         if let Some(a) = self
             .model_mut()
@@ -970,8 +712,7 @@ impl super::UiScript {
         }
     }
 
-    /// `(name, enabled)` for every registered addon, in registry order — what the host writes back
-    /// to `AddOns.txt`, so a `DisableAddOn` from Lua survives the session.
+    /// `(name, enabled)` per registered addon, in order: what the host writes to `AddOns.txt`.
     pub fn addon_enable_states(&self) -> Vec<(String, bool)> {
         self.model_ref()
             .addons
diff --git a/crates/benilla-ui/src/script/addon_gate.rs b/crates/benilla-ui/src/script/addon_gate.rs
index 4e973c19..d70a7acb 100644
--- a/crates/benilla-ui/src/script/addon_gate.rs
+++ b/crates/benilla-ui/src/script/addon_gate.rs
@@ -1,42 +1,19 @@
-//! **The one load law — `AddOn_CanLoad 0x51e780`, as a pure function** (decision 1292).
+//! `AddOn_CanLoad` (`0x51e780`) as a pure function: the one load law every surface consults.
+//! The first check that fires decides, in the reference's order: missing, the visiting guard (a
+//! cycle is loadable), enabled, banned, corrupt, version, dependencies, demand.
 //!
-//! Every question of the form "can this addon load, and if not, why" has exactly one answer in
-//! the reference: a single arbiter whose checks run in a fixed order, whose version gate and
-//! CVar read re-run on every query, and whose two out-params (`reasonOut`, `depReasonOut`)
-//! render through one formatter. benilla had three partial copies of it — the API verbs'
-//! `not_loadable`, `LoadAddOn`'s inline checks, and the startup walk's disabled set — and the
-//! screens were about to become a fourth. This module is the one copy they all consult.
+//! The version gate is an exact `==` against a hard-coded 11200 (`0x51d7d0`), so 11201 is out of
+//! date and a missing `## Interface` compares as 0. With `checkAddonVersion` off the reason is
+//! reset to none, so force-load falls through to the dependency and demand checks.
 //!
-//! The check order: **missing → visiting-guard (returns loadable — a cycle resolves
-//! optimistically) → enabled → banned → corrupt → the version gate → required-deps recursion →
-//! demand gate**. The first check that fires decides.
-//!
-//! ## The version gate, byte for byte
-//!
-//! `cmp [rec+0x1c], 11200` — an **exact `==` against a hard-coded immediate** (`0x51d7d0` is
-//! `mov eax,0x2bc0; ret`, one caller image-wide). `## Interface: 11201` is as out of date as
-//! `10000`, and a manifest with **no** `## Interface` line compares as `0` — out of date, not
-//! "unknown". On mismatch the reason `7` is written and then, when the check is OFF
-//! (`checkAddonVersion`, the *Load out of date AddOns* checkbox inverted), **actively reset to
-//! `0`** — an out-of-date addon under force-load is byte-indistinguishable from an up-to-date
-//! one; there is no "loadable but flagged" state. Force-load is a fall-through, not a success:
-//! the dependency and demand checks still run.
-//!
-//! ## The reason rendering (`0x51e930`)
-//!
-//! `reason != 0` → its token; `reason == 0 && depReason != 0` → `DEP_<token>`, applied
-//! **exactly once at any nesting depth** (the recursion passes the caller's `depReasonOut` as
-//! the callee's *both* out-params, so the deepest failure's raw token lands in the parent's dep
-//! slot); both zero → nil (all three callers guard it — `LOADABLE` is unreachable as a reason).
-//! `BANNED`/`CORRUPT`/`INSECURE` gate on the server's `SMSG_ADDON_INFO` signature state, which
-//! benilla does not model (nothing a player installs is Blizzard-signed) — the arms exist in
-//! the table for honesty and are never produced.
+//! The reason renders once (`0x51e930`): the addon's own token, else `DEP_` and the deepest failing
+//! dependency's token, else nil. `BANNED`, `CORRUPT` and `INSECURE` read the server's
+//! `SMSG_ADDON_INFO` signature state, which is not modelled; they are never produced.
 
-/// The `## Interface` this client implements — the reference's own hard-coded `0x2bc0`.
+/// The `## Interface` this client implements, the reference's hard-coded `0x2bc0`.
 pub const CLIENT_INTERFACE: u32 = 11200;
 
-/// One addon as the gate reads it — the adapter shape every registry (the VM's `AddOnInfo`
-/// rows, the app's discovered manifests, the glue screen's folder view) lowers into.
+/// One addon as the gate reads it; every addon registry lowers into this.
 pub struct GateRow<'a> {
     pub name: &'a str,
     /// This character's enable state (`AddOns.txt`; an addon nobody disabled is enabled).
@@ -45,12 +22,9 @@ pub struct GateRow<'a> {
     /// the leading integer, `0` when absent.
     pub interface: u32,
     pub load_on_demand: bool,
-    /// Loaded this session. A loaded dependency satisfies the recursion outright: the short-circuit
-    /// lives inside `AddOn_CanLoad` itself (`0x51e8ba call AddOn_IsLoaded; jne` skips the
-    /// recursion), and the recursion propagates the caller's own `demandOnly` (`0x51e790` spill →
-    /// `0x51e8c9` reload). The reference's concrete answers match this implementation exactly: a
-    /// LoadOnDemand addon over a loaded ordinary dep is loadable/nil; over an enabled-but-UNLOADED
-    /// ordinary dep it reports `DEP_NOT_DEMAND_LOADED`.
+    /// Loaded this session. A loaded dependency satisfies the recursion outright (`0x51e8ba`),
+    /// which otherwise passes on the caller's `demandOnly` (`0x51e790`, `0x51e8c9`): in game, an
+    /// ordinary dependency enabled but not loaded reports `DEP_NOT_DEMAND_LOADED`.
     pub loaded: bool,
     /// `## Dependencies` / `## RequiredDeps` / any `## Dep*` (one list in the reference).
     pub dependencies: Vec<&'a str>,
@@ -61,10 +35,9 @@ pub struct GateRow<'a> {
 pub enum Verdict {
     Loadable,
     Refused {
-        /// The addon's own reason token (`DISABLED`, `INTERFACE_VERSION`, …), when the failure
-        /// is its own.
+        /// The addon's own reason token (`DISABLED`, `INTERFACE_VERSION`, …).
         reason: Option<&'static str>,
-        /// The dependency's raw token when the failure is a dep's — rendered as `DEP_<token>`.
+        /// A failing dependency's raw token, rendered as `DEP_<token>`.
         dep: Option<&'static str>,
     },
 }
@@ -74,8 +47,7 @@ impl Verdict {
         self == Verdict::Loadable
     }
 
-    /// The formatter (`0x51e930`) plus its callers' nil-guard: the reason token, else
-    /// `DEP_<dep>`, else `None` (loadable — `LOADABLE` is unreachable as a reason).
+    /// The formatter (`0x51e930`) with its callers' nil guard, so `LOADABLE` never renders.
     pub fn token(self) -> Option<String> {
         match self {
             Verdict::Loadable => None,
@@ -88,16 +60,14 @@ impl Verdict {
 
 /// `AddOn_CanLoad` over a registry: can `rows[index]` load right now?
 ///
-/// `demand_only` is the in-game flavour (`dl=1`): an enabled, up-to-date, **non**-LoadOnDemand
-/// addon that has not loaded reports `NOT_DEMAND_LOADED` — a state the glue (`dl=0`) never
-/// produces. `version_check` is the live `checkAddonVersion` read; both re-run per query, which
-/// is why toggling the checkbox needs no rescan (`0x51e780`).
+/// `demand_only` is the in-game query (`dl=1`), where an unloaded addon that is not LoadOnDemand
+/// reports `NOT_DEMAND_LOADED`; `version_check` is the live `checkAddonVersion`, read per query.
 pub fn can_load(rows: &[GateRow], index: usize, demand_only: bool, version_check: bool) -> Verdict {
     let mut visiting = vec![false; rows.len()];
     walk(rows, index, demand_only, version_check, &mut visiting)
 }
 
-/// One level of the arbiter — the checks in the reference's evaluation order.
+/// One level of the arbiter, its checks in the reference's order.
 fn walk(
     rows: &[GateRow],
     i: usize,
@@ -105,39 +75,38 @@ fn walk(
     version_check: bool,
     visiting: &mut [bool],
 ) -> Verdict {
-    // Check 2: the in-progress guard — a cycle resolves optimistically (`[rec+0x2d]` → TRUE).
+    // Check 2: the visiting guard; a cycle resolves as loadable.
     if visiting[i] {
         return Verdict::Loadable;
     }
     let row = &rows[i];
-    // Check 3: this character's enable state.
+    // Check 3: enabled.
     if !row.enabled {
         return Verdict::Refused {
             reason: Some("DISABLED"),
             dep: None,
         };
     }
-    // Checks 4/5 (banned / corrupt): no server signature state to read — never produced.
-    // Check 6: the version gate — exact ==, then refuse or actively fall through (`0x51e876`).
+    // Checks 4 and 5, banned and corrupt: no signature state, never produced.
+    // Check 6: the version gate, exact `==`; with the check off it falls through (`0x51e876`).
     if row.interface != CLIENT_INTERFACE && version_check {
         return Verdict::Refused {
             reason: Some("INTERFACE_VERSION"),
             dep: None,
         };
     }
-    // Check 7: required dependencies, recursively; the first failure decides, and the deepest
-    // failure's raw token is the one `DEP_` wraps (`0x51e8ce`'s shared out-param).
+    // Check 7: the dependencies, recursively; a shared out-param makes the deepest failure's raw
+    // token the one `DEP_` wraps (`0x51e8ce`).
     visiting[i] = true;
     for dep in &row.dependencies {
         let found = rows.iter().position(|r| r.name.eq_ignore_ascii_case(dep));
         let verdict = match found {
-            // The recursion's check 1: a name not in the registry is MISSING.
+            // Check 1, in the recursion: a name not in the registry is `MISSING`.
             None => Verdict::Refused {
                 reason: Some("MISSING"),
                 dep: None,
             },
-            // A loaded dependency satisfies the walk outright — `0x51e8ba`, before the
-            // recursion (see the row doc).
+            // A loaded dependency satisfies the walk before any recursion (`0x51e8ba`).
             Some(d) if rows[d].loaded => Verdict::Loadable,
             Some(d) => walk(rows, d, demand_only, version_check, visiting),
         };
@@ -150,7 +119,7 @@ fn walk(
         }
     }
     visiting[i] = false;
-    // Check 8: the demand gate — reachable only from the in-game surface (`dl=1`).
+    // Check 8: the demand gate, in game only (`dl=1`).
     if demand_only && !row.load_on_demand && !row.loaded {
         return Verdict::Refused {
             reason: Some("NOT_DEMAND_LOADED"),
@@ -175,13 +144,12 @@ mod tests {
         }
     }
 
-    /// The check ORDER is the law: a disabled addon reports only DISABLED, whatever else is
-    /// wrong with it — the glue colours that row grey, never red (1197's precedence).
+    /// Enabled comes before every later check, so the glue shows a disabled row grey, never red.
     #[test]
     fn a_disabled_addon_reports_only_disabled() {
         let mut a = row("A", vec!["Ghost"]);
         a.enabled = false;
-        a.interface = 0; // out of date too — and still invisible behind DISABLED
+        a.interface = 0; // out of date too
         let rows = vec![a];
         assert_eq!(
             can_load(&rows, 0, false, true).token().as_deref(),
@@ -189,9 +157,6 @@ mod tests {
         );
     }
 
-    /// The version gate (`0x51e876`) byte for byte: exact `==` (11201 is out of date), missing
-    /// `## Interface` is 0 and out of date, and force-load RESETS the reason — indistinguishable
-    /// from up to date.
     #[test]
     fn the_version_gate_is_exact_and_force_load_erases_it() {
         let mut a = row("A", vec![]);
@@ -212,8 +177,6 @@ mod tests {
         );
     }
 
-    /// `DEP_` is applied exactly once at any depth (`0x51e8ce`) — the deepest failure's raw token
-    /// is what the top level wraps.
     #[test]
     fn dep_prefix_applies_once_at_any_depth() {
         let a = row("A", vec!["B"]);
@@ -226,7 +189,7 @@ mod tests {
             Some("DEP_DISABLED"),
             "not DEP_DEP_DISABLED — the shared out-param collapses the nesting"
         );
-        // And a dep that is not installed at all is the recursion's own check 1.
+        // A dependency not installed fails the recursion's check 1.
         let rows = vec![row("A", vec!["Ghost"])];
         assert_eq!(
             can_load(&rows, 0, false, true).token().as_deref(),
@@ -234,8 +197,6 @@ mod tests {
         );
     }
 
-    /// Check 2: a dependency cycle resolves optimistically (the visiting guard returns TRUE),
-    /// so neither side reports a failure from the query side.
     #[test]
     fn a_cycle_is_loadable_to_the_query() {
         let a = row("Ping", vec!["Pong"]);
@@ -244,8 +205,6 @@ mod tests {
         assert_eq!(can_load(&rows, 0, false, true), Verdict::Loadable);
     }
 
-    /// Check 8 is in-game only (`dl=1`), runs AFTER the dep loop, and force-load does not skip
-    /// it — an out-of-date addon under force-load can still be NOT_DEMAND_LOADED.
     #[test]
     fn the_demand_gate_is_in_game_only_and_survives_force_load() {
         let mut a = row("A", vec![]);
@@ -259,9 +218,6 @@ mod tests {
         );
     }
 
-    /// A LoadOnDemand addon whose required dep already loaded at startup is loadable from the
-    /// in-game surface — the loaded short-circuit at `0x51e8ba` (inside `AddOn_CanLoad`,
-    /// before the recursion; the reference's own concrete A/B verdict is this assertion).
     #[test]
     fn a_loaded_dependency_satisfies_the_demand_query() {
         let mut a = row("A", vec!["B"]);
diff --git a/crates/benilla-ui/src/script/addon_message.rs b/crates/benilla-ui/src/script/addon_message.rs
index f3cb98aa..f4a4c583 100644
--- a/crates/benilla-ui/src/script/addon_message.rs
+++ b/crates/benilla-ui/src/script/addon_message.rs
@@ -1,161 +1,40 @@
-//! **`SendAddonMessage`** — the addon-to-addon channel (decision 1235).
+//! `SendAddonMessage(prefix, message [, distribution])`, the addon-to-addon channel. 1.12 has no
+//! addon opcode: the binding (`0x49f920`) sends `prefix`, a TAB and `message` as one
+//! `CMSG_MESSAGECHAT` string with language `LANG_ADDON` (`0xFFFFFFFF`), the only mark of addon
+//! data on either side, and the receiver splits on the first TAB (`0x49a8d0`). The binding reads
+//! Lua arguments 1 to 3 only: 1.12 has no whispered addon message.
 //!
-//! ```lua
-//! SendAddonMessage(prefix, message [, distribution])
-//! ```
-//!
-//! The corpus's single most-wanted missing global (24 of 218 addons name it). It is how an addon
-//! talks to *its own copy running on someone else's client*: oRA2 broadcasting a CTRA raid status,
-//! KLHThreatMeter shipping a threat table, BigWigs syncing a boss timer.
-//!
-//! ## 1.12.1 has no addon opcode — the whole thing is one sentinel in the language field
-//!
-//! There is no `CMSG_ADDON_MESSAGE`. `SendAddonMessage` composes its two strings into ONE chat
-//! line, sends it as an ordinary `CMSG_MESSAGECHAT` on an ordinary chat lane, and sets the
-//! `language` field to `LANG_ADDON` (`0xFFFFFFFF`). That sentinel is the *only* thing separating
-//! addon data from speech, on both sides of the wire.
-//!
-//! VERIFIED in `WoW.exe` (5875). The binding is `0x49f920`, body
-//! `[0x49f920, 0x49fb2a)`:
-//!
-//! ```text
-//! 49f951/49f958: lua_tostring(L,1)  -> prefix    (NULL -> "" at 0x49f96b-0x49f97a)
-//! 49f95d/49f966: lua_tostring(L,2)  -> message   (NULL -> "" likewise)
-//! 49f97f-49f987: BOTH empty -> luaL_error("Usage: SendAddonMessage(...)")
-//! 49f9a2: push 0x844b5c            ; "%s\t%s"  (raw 25 73 09 25 73 00)
-//! 49f9ad: push 0x800               ; 2048
-//! 49f9b2: push eax                 ; dst = [ebp-0x81c]
-//! 49f9b3: call 0x64a7f0            ; _snprintf(dst, 0x800, "%s\t%s", prefix, message)
-//! 49fa0b/49fa15: lua_isstring(L,3) ; absent/non-string -> esi = 1 = PARTY (0x49fa06/0x49fa12)
-//! 49fa3f: cmp esi,0x01 ; je        ; PARTY
-//! 49fa44: cmp esi,0x02 ; je        ; RAID
-//! 49fa49: cmp esi,0x03 ; je        ; GUILD
-//! 49fa4e: cmp esi,0x5c ; je        ; BATTLEGROUND
-//! 49fa53: push 0x844b44 ; call 0x6f4940   ; luaL_error("Unknown addon chat type")
-//! 49facf: call 0x418190             ; u32 opcode 0x95 = CMSG_MESSAGECHAT
-//! 49fad8: call 0x418190             ; u32 chat type
-//! 49fab9: or  ebx,-0x1
-//! 49fadd: push ebx
-//! 49fae1: call 0x4181f0             ; u32 language = 0xFFFFFFFF
-//! 49faf0: call 0x418430             ; CString message
-//! ```
-//!
-//! Three consequences the shape forces, and each is a thing an implementation gets wrong:
-//!
-//! - **The prefix is not a wire field.** It is glued to the message with a literal TAB and the
-//!   pair rides as one C-string. The receiver splits on the FIRST tab (`0x49a8d0`). Nothing on
-//!   the wire knows a prefix exists.
-//! - **There is no `target` argument.** The body fetches Lua indices `1`, `2` and `3` and no
-//!   other — there is no arg-4 fetch anywhere in its 522 bytes. 1.12 has no whispered addon
-//!   message; the modern 4-argument `SendAddonMessage(prefix, msg, "WHISPER", target)` does not
-//!   exist here, and `"WHISPER"` is not even a legal distribution (below).
-//! - **`_snprintf` with size `0x800` truncates silently at 2047 bytes + NUL** (`0x64a861`-
-//!   `0x64a868`). No error, no tell.
-//!
-//! ## The distribution set is FOUR, and it is narrower than the server's
-//!
-//! [`AddonDistribution`] is the whole legal set — `PARTY`/`RAID`/`GUILD`/`BATTLEGROUND`. Two
-//! independent mechanisms in the binary name the identical four, which is the cross-check that
-//! settles it: the send-side whitelist above, and the *receive* side's remap table (`0x49aff4`,
-//! 92 bytes = `00 01 02` then `04` x88 then `03`) feeding the 5-entry jump table `0x49afe0`, whose
-//! four real arms push `"PARTY"`/`"RAID"`/`"GUILD"`/`"BATTLEGROUND"` and whose default pushes the
-//! literal `"UNKNOWN"`.
-//!
-//! **vmangos is WIDER than the client** and that gap is deliberate, not a bug to close:
-//! `WorldSession::IsLanguageAllowedForChatType` also permits `LANG_ADDON` on OFFICER,
-//! RAID_LEADER, RAID_WARNING, BATTLEGROUND_LEADER and CHANNEL. A real client *accepts* addon
-//! traffic inbound on all of those (the receive-side discriminator is language-only and reads no
-//! type byte) while refusing to *send* on them. We match the client, not the server: the four.
-//!
-//! An unknown token and a known-but-not-whitelisted one (`"SAY"`, `"WHISPER"`, `"CHANNEL"`,
-//! `"OFFICER"`, `"RAID_WARNING"` — all of which DO resolve in the shared 13-record type table at
-//! `0x49f7a0`) converge on the **same** `luaL_error` at `0x49fa53`. That is why this module does
-//! not model the 13-record table at all: its output is unobservable through this binding, because
-//! both paths raise the identical error text. The note says so outright — *"a caller cannot tell a
-//! typo from a rejection."*
-//!
-//! ## The seam
-//!
-//! [`super::chat_send`]'s shape: the verb validates, composes, and queues an [`AddonSend`]; the app
-//! drains it ([`super::UiScript::take_addon_sends`]) into `ClientCommand::AddonMessage` and the
-//! writer puts it on the wire. Plain data across the boundary — this crate holds no wire types —
-//! but the distribution crosses as an **enum, not a token string**, so the app's map is total and
-//! the "unknown type silently guessed into SAY" failure is impossible by construction rather than
-//! by a second validation nobody remembers to write.
-//!
-//! ## The `|`-escape scan — carved, and it is a forward SKIP, not a flat scan (decision 1236)
-//!
-//! `0x49f9bb`-`0x49fa04`, running on the **composed** buffer (cursor `0x49f9bd
-//! lea ecx,[ebp-0x81c]`, byte-identical to the `_snprintf` destination `lea` at `0x49f9a7`) and
-//! strictly **before** the type whitelist — `0x49fa06` is the sole predecessor of `0x49fa0b`, so a
-//! payload with a bad escape *and* a bad distribution reports the escape and never fetches
-//! argument 3. See [`validate_escapes`] for the loop; the two facts that make it non-obvious:
-//!
-//! - **`|c` skips PAST its closer.** `strstr` (`0x64b4f0`, case-**sensitive** — the binary has a
-//!   folding twin at `0x64b540` and deliberately does not use it here) finds the first literal
-//!   `"|r"` and the cursor becomes `lea esi,[eax+0x2]` (`0x49f9f4`), i.e. beyond it. That single
-//!   `lea` is why a well-formed `|r` never reaches the loop head — under a flat scan its own `|`
-//!   would be a `|` followed by `r` and every colour escape in the game would raise.
-//! - **An unmatched `|c` is not an error.** It NUL-terminates in place at the opening `|`
-//!   (`0x49fa6a`) and then `0x49fa6d jmp 0x49fa06` lands on the accept path — **the truncated text
-//!   is transmitted**, with no error and no signal to the addon.
-//!
-//! Because the scan runs on the composed buffer, prefix and message are validated as **one
-//! string**: a `|c` opened in the prefix can be closed by a `|r` in the message, and an unmatched
-//! one in the prefix truncates the payload to a bare prefix with no tab at all.
-//!
-//! ## What is deliberately NOT here, named rather than left to be found
-//!
-//! - **The no-group silent return** (`0x49fa9f`-`0x49faab` -> `0x49fb21`): the reference drops an
-//!   effective-PARTY send when `[0xbc6f48]`/`[0xbc6f4c]` are both zero, with no error and no
-//!   packet. Those two are **`partyMemberGuid[0].lo/.hi` — element 0 of a FOUR-entry array**
-//!   (stride 8, limit `0x20`; `Ui\PartyFrame.cpp`), not "the party GUID" as 1235 called them:
-//!   slot 0 being non-zero is a sound "in a party" test only because `SMSG_GROUP_LIST` refills the
-//!   roster lowest-slot-first (decision 1236 §3).
-//!   We do not implement it, and the reason is a window we have and the reference does
-//!   not: its gate reads the live group GUID, ours would read [`super::party::PartyState`], which
-//!   is `default()` between world entry and the first `SMSG_GROUP_LIST`. Implementing it would
-//!   silently swallow a real broadcast in that window — the exact failure this verb exists to
-//!   avoid. Not implementing it costs one `CMSG_MESSAGECHAT` that vmangos discards
-//!   (`HandleChatMessageOpcode`'s `if (!group) return`), which is the same observable nothing.
+//! Deviation: the reference drops a send that resolves to PARTY while party slot 0's guid
+//! (`0xbc6f48`) is zero (`0x49fa9f`-`0x49faab`); benilla sends it, because `PartyState` is empty
+//! until the first `SMSG_GROUP_LIST` and the gate would swallow a real broadcast. vmangos drops a
+//! group-less party line anyway (`ChatHandler.cpp:476`).
 
 use mlua::{Lua, Value};
 
 use super::Model;
 
-/// The **four** distributions `SendAddonMessage` will send on — the client's own hard whitelist at
-/// `0x49fa3f`-`0x49fa4e`, corroborated by the receive side's remap table (module doc).
-///
-/// An enum rather than a token string on purpose: the binding is the only place a distribution can
-/// be rejected, so everything downstream must be total. The wire type bytes it names are
-/// `ChatMsg::CHAT_MSG_*` and live in `benilla_protocol::messages`; this crate carries no wire
-/// types, so the app maps the variant.
+/// The four distributions the binding sends on (whitelist `0x49fa3f`-`0x49fa4e`); the receiving
+/// side's jump table (`0x49afe0`) names the same four. vmangos also accepts `LANG_ADDON` on the
+/// officer, raid-leader, raid-warning, battleground-leader and channel lanes
+/// (`ChatHandler.cpp:78`), where the 1.12 client never sends it.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum AddonDistribution {
-    /// `PARTY` — wire chat type `0x01`. The **default** when the third argument is absent or not a
-    /// string (`esi` pre-seeded `1` at `0x49fa06`/`0x49fa12`, only overwritten by a successful
-    /// `lua_isstring`+lookup).
+    /// Chat type `0x01`; the default when the third argument is absent or not a string
+    /// (`0x49fa06`).
     Party,
-    /// `RAID` — wire chat type `0x02`. Downgraded to [`Self::Party`] outside a raid; see
-    /// [`AddonDistribution::effective`].
+    /// Chat type `0x02`; sent as PARTY outside a raid.
     Raid,
-    /// `GUILD` — wire chat type `0x03`.
+    /// Chat type `0x03`.
     Guild,
-    /// `BATTLEGROUND` — wire chat type `0x5C`.
+    /// Chat type `0x5C`.
     Battleground,
 }
 
 impl AddonDistribution {
-    /// Resolve a Lua distribution token. `None` = raise `"Unknown addon chat type"`, which is the
-    /// binding's single answer for both an unrecognised token and a recognised-but-not-whitelisted
-    /// one (module doc).
-    ///
-    /// Case-insensitive because the reference's own lookup is: the shared table at `0x49f7a0` is
-    /// scanned with the case-insensitive compare `0x64a4c0` (`0x49f861`-`0x49f875`), so
-    /// `SendAddonMessage("p", "m", "raid")` is a RAID send on a real client.
+    /// A Lua distribution token, case-insensitive like the reference's lookup (`0x64a4c0` over the
+    /// table at `0x49f7a0`). `None` raises `Unknown addon chat type`, the one error the reference
+    /// gives an unknown token and a chat type outside the four alike (`0x49fa53`).
     pub fn from_token(token: &str) -> Option<Self> {
-        // `eq_ignore_ascii_case` rather than an uppercased allocation: the four tokens are ASCII
-        // and this runs on every addon broadcast.
         for (name, dist) in [
             ("PARTY", Self::Party),
             ("RAID", Self::Raid),
@@ -169,8 +48,7 @@ impl AddonDistribution {
         None
     }
 
-    /// The token the receive side reports as `CHAT_MSG_ADDON`'s 3rd argument — the strings the four
-    /// jump-table arms push (`0x8441b0`, `0x844600`, `0x8441a8`, `0x8445f0`).
+    /// The token the receiving side reports as `CHAT_MSG_ADDON`'s third argument (`0x49afe0`).
     pub fn token(self) -> &'static str {
         match self {
             Self::Party => "PARTY",
@@ -180,28 +58,10 @@ impl AddonDistribution {
         }
     }
 
-    /// **RAID sent from outside a raid goes to PARTY**, silently — `0x49fa8b`-`0x49fa93` tests
-    /// `[0xb713e0]` and falls into the PARTY arm when it is zero. Every other distribution passes
-    /// through untouched.
-    ///
-    /// This is the same downgrade a player sees when `/raid` in a 5-man party lands in party chat,
-    /// and vmangos is the reason it has to exist client-side: `HandleChatMessageOpcode`'s
-    /// `CHAT_MSG_RAID` arm requires `group->IsRaidGroup()` and drops the message otherwise. Without
-    /// it, oRA2 — which sends `SendAddonMessage("CTRA", msg, "RAID")` unconditionally
-    /// (`Core.lua:563`) — would reach nobody in an ordinary 5-man group, which is most of the time
-    /// it runs.
-    ///
-    /// `in_raid` is [`super::party::PartyState::raid`] being non-empty, that list being
-    /// `GetNumRaidMembers()`'s own backing (empty outside a raid, and including the player inside
-    /// one).
-    ///
-    /// **That is not an analogy — it is the same cell** (decision 1236). `[0xb713e0]` is not a
-    /// flag: it is the raid member **count**, used as an unsigned loop bound over the 40-slot
-    /// roster at `0xb712a8`, and the binding `GetNumRaidMembers` (`0x4bb530`, `Ui\RaidInfo.cpp`)
-    /// returns that cell verbatim. So the reference's test `[0xb713e0] == 0` *is*
-    /// `GetNumRaidMembers() == 0`, and reading our own `GetNumRaidMembers` backing is the
-    /// mechanism rather than a stand-in for it. (1235 recorded this identity as corroborated but
-    /// hedged; the hedge is now retired.)
+    /// RAID outside a raid silently goes out as PARTY (`0x49fa8b`-`0x49fa93`); vmangos drops a raid
+    /// line from a non-raid group (`ChatHandler.cpp:522`). The reference tests the raid member
+    /// count at `0xb713e0`, the cell `GetNumRaidMembers` (`0x4bb530`) returns, so `in_raid` is
+    /// `PartyState::raid` being non-empty.
     pub fn effective(self, in_raid: bool) -> Self {
         match self {
             Self::Raid if !in_raid => Self::Party,
@@ -210,94 +70,57 @@ impl AddonDistribution {
     }
 }
 
-/// One queued addon broadcast, drained by the app into the wire.
-///
-/// Plain data — [`super::chat_send::ChatSend`]'s twin. The prefix/message split is **already
-/// gone** by the time one of these exists: the reference composes at the binding
-/// (`_snprintf(dst, 0x800, "%s\t%s", …)` at `0x49f9b3`) and so do we, because the tab is the only
-/// separator the wire has and nothing downstream may re-decide where it goes.
+/// One queued addon broadcast, composed at the binding as the reference's is (`_snprintf` at
+/// `0x49f9b3`) and drained by the app onto the wire.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct AddonSend {
-    /// The composed payload — `prefix`, TAB, `message` — truncated to the reference's 2047 bytes.
-    /// Sent verbatim as the `CMSG_MESSAGECHAT` message C-string; vmangos does not sanitise a
-    /// `LANG_ADDON` line (`SanitizeChatMessage` returns early, `Handlers/ChatHandler.cpp:49`), so
-    /// the tab survives to the far client's splitter.
+    /// `prefix`, TAB, `message`, cut at 2047 bytes. vmangos passes a `LANG_ADDON` line through
+    /// unsanitised (`ChatHandler.cpp:49`), so the TAB reaches the receiver.
     pub text: String,
-    /// The lane, **after** the outside-a-raid downgrade ([`AddonDistribution::effective`]) — what
-    /// the app should actually send on, not what the addon asked for.
+    /// The lane to send on, after the outside-a-raid downgrade.
     pub distribution: AddonDistribution,
 }
 
 /// `_snprintf(dst, 0x800, …)` writes at most 2047 bytes plus its NUL (`0x64a861`-`0x64a868`).
 const ADDON_MESSAGE_CAP: usize = 0x800 - 1;
 
-/// **The `|`-escape scan** (`0x49f9bb`-`0x49fa04`, decision 1236) — the reference's only text
-/// validation, run on the already-composed payload and **before** the distribution is even
-/// fetched.
-///
-/// Returns `Err` for an invalid escape (the caller raises the reference's own message); otherwise
-/// `Ok`, having possibly **truncated `text` in place** at an unmatched `|c`, which is the
-/// reference's silent leg — the shortened payload still goes out.
-///
-/// The loop, arm for arm (`esi` = the cursor, always pointing at a `|` found by `strchr`):
-///
-/// | at `|` the next byte is | reference | cursor |
-/// |---|---|---|
-/// | `\|` | accept the escaped pipe | `+2` (`0x49f9d7 add esi,0x2`) |
-/// | `c` and a later `"\|r"` exists | accept the whole colour run | past the closer (`0x49f9f4 lea esi,[eax+0x2]`) |
-/// | `c` and no `"\|r"` | **truncate here, then accept** | — (`0x49fa6a`, `0x49fa6d jmp 0x49fa06`) |
-/// | anything else, incl. the NUL | `luaL_error` | — (`0x49fa6f`) |
-///
-/// Consequences that fall straight out of that table and are pinned by the tests, because every
-/// one of them is a thing a reimplementation gets wrong:
-///
-/// - **`||` and `|c` are the ONLY accepted escape starts.** A bare `|r` raises, and so do `|H`,
-///   `|h`, `|T`, `|t`, `|n` — and `|C`, because the `c` test is case-sensitive. Item links survive
-///   only because they are *wrapped*: `|cffffffff|Hitem:…|h[x]|h|r` opens with `|c`, so the whole
-///   run including every `|H`/`|h` is skipped to the closing `|r` without being examined.
-/// - **Nothing between a `|c` and its first `|r` is validated.** No hex-digit check; a nested
-///   `|c` is legal precisely because it is never looked at. This is a skip, not a nesting counter.
-/// - **`|R` does not close `|c`** (case-sensitive `strstr`) — it truncates instead.
-/// - **A lone trailing `|` raises**, because `strchr` will not match the NUL terminator
-///   (`0x64a402` tests before `0x64a406` compares), so the byte after it is the NUL and the NUL is
-///   not `|` or `c`. Pipe runs must therefore be even: `||||` is sent verbatim, `|||` raises.
+/// The reference's `|`-escape scan (`0x49f9bb`-`0x49fa04`), its only text check, run on the
+/// composed payload before the distribution is read. After each `|`: `||` skips both bytes; `|c`
+/// skips past the first later `|r` (case-sensitive `strstr`, `0x49f9f4`), leaving the run between
+/// unchecked; `|c` with no `|r` cuts `text` at the `|` and accepts (`0x49fa6a`); anything else,
+/// the NUL after a trailing `|` included, is `Err` (`0x49fa6f`).
 fn validate_escapes(text: &mut String) -> Result<(), ()> {
     let bytes = text.as_bytes();
     let mut i = 0usize;
     while let Some(off) = bytes[i..].iter().position(|&b| b == b'|') {
         let pipe = i + off;
         match bytes.get(pipe + 1) {
-            // `||` — an escaped pipe. Past both bytes.
             Some(b'|') => i = pipe + 2,
             Some(b'c') => {
-                // `strstr` from the `|c`'s own `|` for the literal two bytes `"|r"` (operand
-                // `0x844538` = image bytes `7c 72 00`). `|c` cannot match `|r`, so the hit is
-                // always a later closer.
+                // The reference's `strstr` starts at the `|c`, which cannot itself match `|r`.
                 match bytes[pipe..]
                     .windows(2)
                     .position(|w| w == b"|r")
                     .map(|p| pipe + p)
                 {
-                    // Skip PAST the closer, so its own `|` is never fed back to the loop head.
+                    // Past the closer: its `|` must not reach the loop head, where `|r` raises.
                     Some(closer) => i = closer + 2,
-                    // No closer: NUL-terminate at the opening `|` and accept what is left.
+                    // No closer: the reference cuts at the `|` and accepts.
                     None => {
                         text.truncate(pipe);
                         return Ok(());
                     }
                 }
             }
-            // Anything else — including `None`, the NUL that ends a lone trailing `|`.
+            // Anything else, including `None`: the NUL after a trailing `|`.
             _ => return Err(()),
         }
     }
     Ok(())
 }
 
-/// `lua_tostring` semantics + the reference's NULL replacement: strings and numbers coerce,
-/// everything else (nil, boolean, table, function) becomes the shared empty string `0x882748`
-/// (`0x49f96b`-`0x49f97a`). `Lua::coerce_string` **is** `lua_tostring`, so this is the mechanism
-/// rather than an imitation of it.
+/// `lua_tostring` with the reference's NULL-to-empty replacement (`0x49f96b`-`0x49f97a`): strings
+/// and numbers coerce, anything else is `""`.
 fn lua_tostring(lua: &Lua, v: &Value) -> mlua::Result<String> {
     Ok(lua
         .coerce_string(v.clone())?
@@ -312,21 +135,16 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             |lua, (prefix, message, distribution): (Value, Value, Value)| {
                 let prefix = lua_tostring(lua, &prefix)?;
                 let message = lua_tostring(lua, &message)?;
-                // BOTH empty is the usage error, and only both — there is no empty-prefix-only and
-                // no empty-message-only check (`0x49f97f`-`0x49f987`). AceEvent-2.0 relies on it:
-                // `SendAddonMessage("LOOT_OPENED", "", "RAID")` is 24 of the corpus's 35 call
-                // sites (the same line, in 23 addons' embedded copies) and its message is
-                // deliberately empty. An empty-message guard would break the largest row here.
+                // Only both empty is the usage error (`0x49f97f`-`0x49f987`): AceEvent-2.0 sends
+                // `SendAddonMessage("LOOT_OPENED", "", "RAID")`.
                 if prefix.is_empty() && message.is_empty() {
                     return Err(mlua::Error::RuntimeError(
                         r#"Usage: SendAddonMessage("prefix", "message" [,"type"])"#.into(),
                     ));
                 }
                 let mut text = format!("{prefix}\t{message}");
-                // Truncate exactly where `_snprintf` does — by BYTES, since the reference is
-                // writing a C buffer. `floor_char_boundary` is not stable, so walk back to the
-                // nearest boundary: identical to the reference for ASCII (every corpus payload),
-                // and the alternative is a `String` that is not UTF-8, which cannot exist.
+                // Cut at 2047 bytes as `_snprintf` does. Deviation: backed off to a char boundary,
+                // because a `String` must stay UTF-8; the cut is the same for ASCII.
                 if text.len() > ADDON_MESSAGE_CAP {
                     let mut cut = ADDON_MESSAGE_CAP;
                     while cut > 0 && !text.is_char_boundary(cut) {
@@ -334,21 +152,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     }
                     text.truncate(cut);
                 }
-                // **The escape scan runs HERE — after the compose, before argument 3 is fetched**
-                // (`0x49fa06` is the sole predecessor of `0x49fa0b`; decision 1236). So a call
-                // that is wrong in both ways reports the ESCAPE, and a bad distribution beside a
-                // bad escape is never even looked at. It may truncate `text` in place, which is
-                // the reference's silent leg.
+                // After the compose, before argument 3 is read (`0x49fa06` precedes `0x49fa0b`),
+                // so a bad escape is reported over a bad distribution.
                 if validate_escapes(&mut text).is_err() {
                     return Err(mlua::Error::RuntimeError(
                         "Invalid escape code in chat message".into(),
                     ));
                 }
-                // The third argument goes through `lua_isstring`, which is TRUE for a number too
-                // (`0x49fa0b`/`0x49fa15`) — so `SendAddonMessage("p", "m", 1)` resolves the token
-                // `"1"`, finds nothing, and raises, rather than being read as chat type 1. Absent
-                // or non-string (nil, table, boolean) takes `0x49fa1c je 0x49fa9f`, which skips
-                // the whitelist entirely with the pre-seeded `esi = 1` — the PARTY default.
+                // `lua_isstring` (`0x49fa15`) is true for a number, so `1` is the token "1" and
+                // raises; anything else that is not a string is PARTY (`0x49fa1c`).
                 let asked = match lua.coerce_string(distribution)? {
                     Some(token) => AddonDistribution::from_token(&token.to_string_lossy())
                         .ok_or_else(|| {
@@ -387,9 +199,6 @@ mod tests {
     use crate::script::party::{PartyState, RaidMemberInfo};
     use crate::script::UiScript;
 
-    /// The composition law: prefix, a literal TAB, message — one string, and the prefix is not a
-    /// field. Plus the default distribution, which is PARTY and not SAY (this verb's default is
-    /// not `SendChatMessage`'s).
     #[test]
     fn a_broadcast_is_prefix_tab_message_and_defaults_to_party() {
         let mut s = UiScript::new().unwrap();
@@ -401,19 +210,13 @@ mod tests {
                 distribution: AddonDistribution::Party,
             }]
         );
-        // Drained, not re-read.
         assert!(s.take_addon_sends().is_empty());
     }
 
-    /// **The four, and only the four.** Every token the shared 13-record table at `0x49f7a0`
-    /// resolves but the whitelist at `0x49fa3f`-`0x49fa4e` rejects must raise — SAY and WHISPER
-    /// especially, since a client that accepted them would be inventing a 1.12 whispered addon
-    /// message that does not exist. The error text is the reference's, and it is the SAME one an
-    /// unknown token gets.
     #[test]
     fn the_distribution_set_is_exactly_party_raid_guild_battleground() {
         let mut s = UiScript::new().unwrap();
-        // In a raid, so RAID is not downgraded and its own byte is what is under test.
+        // In a raid, so RAID is not downgraded.
         s.set_party(PartyState {
             raid: vec![RaidMemberInfo::default()],
             ..Default::default()
@@ -423,7 +226,6 @@ mod tests {
             ("RAID", AddonDistribution::Raid),
             ("GUILD", AddonDistribution::Guild),
             ("BATTLEGROUND", AddonDistribution::Battleground),
-            // Case-insensitive: the reference's lookup uses the case-insensitive compare 0x64a4c0.
             ("raid", AddonDistribution::Raid),
             ("Guild", AddonDistribution::Guild),
         ] {
@@ -433,7 +235,8 @@ mod tests {
             assert_eq!(sent.len(), 1, "{token}");
             assert_eq!(sent[0].distribution, want, "{token}");
         }
-        // Resolved by the shared table, refused by the whitelist — one error text for both classes.
+        // Chat types the reference's table resolves (`0x49f7a0`) but the whitelist refuses, and
+        // unknown tokens: one error for both.
         for token in [
             "SAY",
             "YELL",
@@ -463,14 +266,9 @@ mod tests {
         }
     }
 
-    /// A refused distribution sends **nothing** — the whole point of the enum seam. An addon that
-    /// asked for a lane we cannot send on gets an error it can see, never a silent reroute onto
-    /// SAY (which would put its serialized payload in front of every player in range).
     #[test]
     fn a_number_distribution_raises_rather_than_being_read_as_a_type_byte() {
         let mut s = UiScript::new().unwrap();
-        // `lua_isstring` is true for a number, so the reference resolves the TOKEN "1" — which is
-        // not in the type table — and raises. It does not read 1 as CHAT_MSG_PARTY.
         let err = s
             .run(r#"SendAddonMessage("p", "m", 1)"#)
             .expect_err("a numeric distribution must raise");
@@ -478,8 +276,6 @@ mod tests {
         assert!(s.take_addon_sends().is_empty());
     }
 
-    /// Non-string, non-number third argument is **absent**, not an error: `lua_isstring` fails and
-    /// the pre-seeded PARTY default stands.
     #[test]
     fn a_non_string_distribution_takes_the_party_default() {
         let mut s = UiScript::new().unwrap();
@@ -492,9 +288,6 @@ mod tests {
             .all(|a| a.distribution == AddonDistribution::Party));
     }
 
-    /// **RAID outside a raid is PARTY.** The corpus's one live caller (oRA2 `Core.lua:563`) sends
-    /// `"RAID"` unconditionally, so without this its broadcasts reach nobody in an ordinary 5-man
-    /// group — vmangos drops a `CHAT_MSG_RAID` from a non-raid group.
     #[test]
     fn raid_outside_a_raid_is_downgraded_to_party() {
         let mut s = UiScript::new().unwrap();
@@ -505,7 +298,6 @@ mod tests {
             s.take_addon_sends()[0].distribution,
             AddonDistribution::Party
         );
-        // In a raid it stays RAID…
         s.set_party(PartyState {
             raid: vec![RaidMemberInfo::default()],
             ..Default::default()
@@ -516,7 +308,7 @@ mod tests {
             s.take_addon_sends()[0].distribution,
             AddonDistribution::Raid
         );
-        // …and the downgrade is RAID's alone — GUILD and BATTLEGROUND never move.
+        // Only RAID is downgraded.
         s.set_party(PartyState::default());
         for (token, want) in [
             ("GUILD", AddonDistribution::Guild),
@@ -528,9 +320,6 @@ mod tests {
         }
     }
 
-    /// Both arguments empty is the usage error; **either one alone is not**. AceEvent-2.0 —
-    /// literally every one of this verb's replicated corpus callers — sends an empty message with
-    /// a real prefix, and erroring on it would break the row this verb was written for.
     #[test]
     fn only_both_empty_is_a_usage_error() {
         let mut s = UiScript::new().unwrap();
@@ -539,19 +328,15 @@ mod tests {
             .expect_err("both empty must raise");
         assert!(err.to_string().contains("Usage: SendAddonMessage"), "{err}");
         assert!(s.take_addon_sends().is_empty());
-        // AceEvent-2.0.lua's own line, verbatim — the empty message must go out.
+        // AceEvent-2.0's own call.
         s.run(r#"SendAddonMessage("LOOT_OPENED", "", "RAID")"#)
             .unwrap();
-        // A prefix-less payload is legal too; the receiver reads prefix "" and message "m".
         s.run(r#"SendAddonMessage("", "m")"#).unwrap();
         let sent = s.take_addon_sends();
         assert_eq!(sent[0].text, "LOOT_OPENED\t");
         assert_eq!(sent[1].text, "\tm");
     }
 
-    /// `lua_tostring` coercion, and the NULL -> "" replacement at `0x49f96b`-`0x49f97a`: a number
-    /// coerces, a table does not and becomes empty. `SendAddonMessage({}, {})` is therefore the
-    /// usage error, reached the same way `("", "")` reaches it.
     #[test]
     fn arguments_coerce_like_lua_tostring_and_nil_becomes_empty() {
         let mut s = UiScript::new().unwrap();
@@ -559,16 +344,13 @@ mod tests {
         assert_eq!(s.take_addon_sends()[0].text, "v\t314");
         s.run(r#"SendAddonMessage(42, "m")"#).unwrap();
         assert_eq!(s.take_addon_sends()[0].text, "42\tm");
-        // Non-coercible -> "" on both sides -> the usage error, not a Rust type error.
         let err = s
             .run(r#"SendAddonMessage({}, {})"#)
             .expect_err("two tables coerce to two empty strings");
         assert!(err.to_string().contains("Usage: SendAddonMessage"), "{err}");
     }
 
-    /// **The first tab is the split, so a tab inside the prefix is a payload bug the reference also
-    /// has** — no sanitisation of `0x09` exists anywhere in the binding. Pinned so nobody "fixes"
-    /// it: the receiver would split at the prefix's own tab and read a truncated prefix.
+    /// The reference does not strip a TAB from the prefix either; the receiver splits at it.
     #[test]
     fn a_tab_inside_the_prefix_is_passed_through_unsanitised() {
         let mut s = UiScript::new().unwrap();
@@ -576,8 +358,6 @@ mod tests {
         assert_eq!(s.take_addon_sends()[0].text, "pre\tfix\tbody");
     }
 
-    /// Silent truncation at 2047 bytes + the implicit NUL — `_snprintf`'s `0x800`, not the message
-    /// length and not the prefix length. No error: the addon is never told.
     #[test]
     fn the_payload_truncates_silently_at_2047_bytes() {
         let mut s = UiScript::new().unwrap();
@@ -585,30 +365,24 @@ mod tests {
             .unwrap();
         let sent = s.take_addon_sends();
         assert_eq!(sent[0].text.len(), 2047);
-        // The tab survives the cut — it is at byte 1, far inside the cap.
         assert!(sent[0].text.starts_with("p\tx"));
-        // A payload that exactly fills the buffer is NOT truncated.
+        // 1 + 1 + 2045 bytes fills the buffer exactly and is not cut.
         s.run(r#"SendAddonMessage("p", string.rep("y", 2045))"#)
             .unwrap();
         assert_eq!(s.take_addon_sends()[0].text.len(), 2047);
     }
 
-    /// **The escape scan is a forward SKIP, and a well-formed colour run must survive it.** This
-    /// is the test that would have caught the naive flat scan: under one, the `|` of every `|r`
-    /// terminator is a `|` followed by `r` and *every* colour escape in the game raises.
     #[test]
     fn a_well_formed_colour_run_passes_and_its_closer_is_skipped_not_scanned() {
         let mut s = UiScript::new().unwrap();
         for payload in [
             "|cffff0000red|r",
             "before |cffff0000red|r after",
-            // Nested opens are legal precisely because nothing between `|c` and the first `|r` is
-            // examined — a skip, not a nesting counter.
+            // Nothing between `|c` and the first `|r` is examined, so a nested open passes.
             "|cffAA0000 a |cff00BB00 b |r",
-            // An item link survives only because it is WRAPPED: the `|H`/`|h` inside the colour
-            // run are never looked at.
+            // A link passes only inside a colour run.
             "|cffa335ee|Hitem:12345:0:0:0|h[Thunderfury]|h|r",
-            // Escaped pipes, in even runs.
+            // Escaped pipes come in even runs.
             "a || b",
             "||||",
         ] {
@@ -627,20 +401,17 @@ mod tests {
         }
     }
 
-    /// `||` and `|c` are the ONLY accepted starts — everything else raises with the reference's own
-    /// text, including a **bare `|r`**, the link tokens outside a colour run, the case-flipped
-    /// `|C`, and a lone trailing `|` (whose next byte is the NUL, which `strchr` never matches).
     #[test]
     fn every_other_escape_start_raises_including_a_bare_closer_and_a_trailing_pipe() {
         let mut s = UiScript::new().unwrap();
         for payload in [
             "|r",                    // a closer with nothing open
-            "|Hitem:1:0:0:0|h[x]|h", // link tokens NOT wrapped in a colour run
+            "|Hitem:1:0:0:0|h[x]|h", // link tokens outside a colour run
             "|h",
             "|T",
             "|t",
             "|n",
-            "|C",         // |C is not |c — the test is case-sensitive
+            "|C",         // |C is not |c: the test is case-sensitive
             "trailing |", // next byte is the NUL
             "|||",        // odd pipe run: the third one's next byte is the NUL
         ] {
@@ -662,28 +433,22 @@ mod tests {
         }
     }
 
-    /// **An unmatched `|c` is NOT an error — it truncates in place and the short payload is still
-    /// sent** (`0x49fa6a` then `0x49fa6d jmp 0x49fa06`, the accept path). Silent, exactly as the
-    /// reference is: the addon is never told its message was cut.
     #[test]
     fn an_unmatched_colour_open_truncates_in_place_and_still_sends() {
         let mut s = UiScript::new().unwrap();
         s.run(r#"SendAddonMessage("P", "keep|cff00ff00dropped", "GUILD")"#)
             .unwrap();
         assert_eq!(s.take_addon_sends()[0].text, "P\tkeep");
-        // `|R` does not close `|c` — the strstr is case-SENSITIVE, so this truncates too.
+        // `|R` does not close `|c`: the reference's `strstr` is case-sensitive.
         s.run(r#"SendAddonMessage("P", "keep|cff00ff00x|Ry", "GUILD")"#)
             .unwrap();
         assert_eq!(s.take_addon_sends()[0].text, "P\tkeep");
-        // The scan runs on the COMPOSED buffer, so an unmatched open in the PREFIX truncates the
-        // payload to a bare prefix — no tab, no message at all.
+        // The scan runs on the composed text: an open in the prefix cuts the TAB and message off.
         s.run(r#"SendAddonMessage("pre|cffAABBCCfix", "body", "GUILD")"#)
             .unwrap();
         assert_eq!(s.take_addon_sends()[0].text, "pre");
     }
 
-    /// **Prefix and message are validated as ONE string**, because the scan runs after the
-    /// compose — so a colour opened in the prefix is legally closed by the message.
     #[test]
     fn a_colour_run_may_span_the_tab_because_the_scan_is_on_the_composed_buffer() {
         let mut s = UiScript::new().unwrap();
@@ -692,9 +457,6 @@ mod tests {
         assert_eq!(s.take_addon_sends()[0].text, "|cffff0000pre\tpost|r");
     }
 
-    /// **Ordering: the escape check precedes the distribution fetch.** A call that is wrong in
-    /// both ways reports the ESCAPE — `0x49fa06` is the sole predecessor of `0x49fa0b`, so
-    /// argument 3 is never even read. (1235 shipped these the other way round; 1236 corrects it.)
     #[test]
     fn a_bad_escape_beats_a_bad_distribution() {
         let s = UiScript::new().unwrap();
@@ -706,16 +468,13 @@ mod tests {
                 .contains("Invalid escape code in chat message"),
             "the escape must win, not the type: {err}"
         );
-        // But an UNMATCHED `|c` is not an error, so there the bad type does surface — the exact
-        // asymmetry the two legs of the scan produce.
+        // An unmatched `|c` is not an error, so the bad distribution is reported.
         let err = s
             .run(r#"SendAddonMessage("P", "|cff000000x", "TOTALLY_BOGUS")"#)
             .expect_err("must raise");
         assert!(err.to_string().contains("Unknown addon chat type"), "{err}");
     }
 
-    /// The distribution tokens round-trip to the strings the RECEIVE side reports as
-    /// `CHAT_MSG_ADDON`'s third argument (the four jump-table arms at `0x49a918`/`91f`/`926`/`92d`).
     #[test]
     fn the_tokens_are_the_receive_sides_own_strings() {
         for (dist, token) in [
diff --git a/crates/benilla-ui/src/script/auction.rs b/crates/benilla-ui/src/script/auction.rs
index 3a20cb05..5c466cdb 100644
--- a/crates/benilla-ui/src/script/auction.rs
+++ b/crates/benilla-ui/src/script/auction.rs
@@ -1,44 +1,9 @@
-//! The auction-house bindings (decision 1511) — the Era-shaped auctioneer surface, the same two-way
-//! seam as [`super::merchant`]/[`super::mail`]: the app pushes an **auction snapshot** (three lists
-//! of rows, already resolved from the wire to name/icon/quality/owner and already in display order)
-//! and the Lua `QueryAuctionItems`/`PlaceAuctionBid`/`StartAuction`/… calls queue outbound
-//! **intents** the app drains. The engine holds no auction knowledge: a row is a header, the sort
-//! is a pushed ordering, and the category tree is a pushed table.
+//! The auction-house bindings: the app pushes a snapshot of three lists, rows already resolved and
+//! in display order, and the Lua calls queue intents the app drains. Getters are keyed by `"list"`
+//! (Browse), `"bidder"` (Bids) or `"owner"` (Auctions), with `index` 1-based in the 50-row batch.
 //!
-//! ## Three lists, one API
-//!
-//! Every getter is keyed by a list type string — `"list"` (Browse), `"bidder"` (Bids) and
-//! `"owner"` (Auctions) — and `index` is **1-based within the current 50-row batch**, not within
-//! the whole result set. `GetNumAuctionItems` returns the pair `numBatchAuctions, totalAuctions`;
-//! when `total > batch` the window is paging, and the page turners re-query rather than scroll.
-//!
-//! ## The two null shapes that are load-bearing
-//!
-//! `GetAuctionSellItemInfo()` **always returns six values, never zero** — an empty sell slot pushes
-//! `nil, nil, 1, -1, nil, 0`, with a hard `count = 1` and `quality = -1` rather than nils. The
-//! reference Lua reads that count unguarded (`if count > 1`), so a nil there throws the moment the
-//! player pulls the item back out of the slot. `GetAuctionItemInfo` answers a lone `nil` for an
-//! out-of-range index, which is the shape its callers test.
-//!
-//! ## Sorting is ours, and it is not a three-state cycle
-//!
-//! The wire carries no sort field, so the ordering is entirely client-side over the ≤50 rows the
-//! server returned. Each list owns an **8-deep most-recently-clicked key stack** of
-//! `(key, reversed)` pairs: clicking the column that is already primary toggles its direction;
-//! clicking any other promotes it to primary **keeping the direction it remembers**. That is why
-//! `IsAuctionSortReversed` can answer "reversed" for a column that is not currently sorting
-//! anything. [`super::UiScript::take_auction_sorts`] hands the click to the app, which owns the
-//! stacks and pushes both the reordered rows and the stack back. The selection rides through all
-//! of it untouched, because it is stored as an auction **id** and only resolved to a row position
-//! when something asks (`0x4cfda0`/`0x4cfec0`).
-//!
-//! ## The deposit is computed here, and it is the *client's* arithmetic
-//!
-//! `CalculateAuctionDeposit(minutes)` reproduces the real client's formula —
-//! `floor(rate × stackValue / 100) × floor(minutes / 120)` — including the intermediate truncation
-//! that makes it disagree with what the server actually charges on cheap items. Decision 1511 §7
-//! records why the label follows the client rather than the server: it is a client artifact, and
-//! benilla renders what the director's client renders.
+//! The wire carries no sort: each list keeps an 8-deep stack of `(key, reversed)`, where clicking
+//! the primary column toggles it and another column is promoted with the direction it remembers.
 
 use mlua::{Lua, MultiValue, Value};
 
@@ -46,26 +11,21 @@ use super::binding_abi::flag;
 use super::cursor::{self, CursorPayload};
 use super::Model;
 
-/// The three list types, in the order the app pushes them. The wire calls them nothing at all —
-/// this is purely the Lua API's own keying.
+/// The three list types, in the order the app pushes them.
 pub const LIST: usize = 0;
 pub const BIDDER: usize = 1;
 pub const OWNER: usize = 2;
 
-/// The eight sort keys the reference's headers pass. Order here is the API's, not the comparator's
-/// (decision 1511's INTERIM: the comparator's own mode order is pinned to an in-flight
-/// investigation).
+/// The eight sort keys the reference's column headers pass, in the API's order.
 pub const SORT_KEYS: [&str; 8] = [
     "level", "quality", "bid", "duration", "buyout", "status", "name", "seller",
 ];
 
-/// `"list"` / `"bidder"` / `"owner"` → the index the snapshot stores them at, for the other
-/// modules that key off the same three names (the tooltip's `SetAuctionItem`).
+/// A list type's snapshot index, for the other modules (the tooltip's `SetAuctionItem`).
 pub(super) fn list_index_of(kind: &str) -> Option<usize> {
     list_index(kind)
 }
 
-/// `"list"` / `"bidder"` / `"owner"` → the index the snapshot stores them at.
 fn list_index(kind: &str) -> Option<usize> {
     match kind {
         "list" => Some(LIST),
@@ -75,58 +35,46 @@ fn list_index(kind: &str) -> Option<usize> {
     }
 }
 
-/// One auction row, resolved by the app from a wire record (decision 1511). Plain data — its
-/// 1-based order in the window is its position in [`AuctionListState::rows`], which is already the
-/// sorted display order.
+/// One auction row, resolved by the app from a wire record.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct AuctionItemRow {
-    /// The wire auction id — what a bid or a cancel addresses. Never shown; the app maps a clicked
-    /// row index back through this.
+    /// The wire auction id a bid or a cancel addresses; never shown.
     pub auction_id: u32,
-    /// The item's template entry — the tooltip store's key and the link's identity.
     pub item_id: u32,
-    /// The listed item's **random-suffix roll** (the wire's `randomPropertyId`) — what the row
-    /// hover resolves its enchant lines from, and the id whose suffix [`Self::name`] already
-    /// carries. `0` = unrolled. The reference's `SetAuctionItem` writes exactly this into the
-    /// tooltip's `+0x424` (decision 1547).
+    /// The wire's `randomPropertyId`, 0 when unrolled; [`Self::name`] already carries its suffix,
+    /// and the reference's `SetAuctionItem` writes it into the tooltip's `+0x424`.
     pub random_property_id: u32,
-    /// `None` while the item template answer is in flight (the row shows a placeholder and fills
-    /// in when it lands, the merchant/mail pattern).
+    /// `None` while the item template query is in flight.
     pub name: Option<String>,
     pub texture: Option<String>,
     pub count: u32,
     pub quality: Option<u32>,
-    /// `RequiredLevel` — printed red when it exceeds the player's own level.
+    /// `RequiredLevel`, printed red above the player's level.
     pub level: u32,
-    /// The seller's opening price. This is what the row shows as the current bid while
-    /// [`Self::bid_amount`] is 0.
+    /// The seller's opening price, shown as the current bid while [`Self::bid_amount`] is 0.
     pub min_bid: u32,
-    /// The minimum step above the current bid — `0` while nobody has bid.
+    /// The minimum step above the current bid; 0 before any bid.
     pub min_increment: u32,
     /// `0` = no buyout.
     pub buyout_price: u32,
-    /// The current high bid; `0` = no bids yet.
+    /// The current high bid; 0 before any bid.
     pub bid_amount: u32,
-    /// Whether *the player* holds the high bid — a flag, not a name. The Browse row's "Your bid:"
-    /// caption and both action-button gates read it.
+    /// Whether the player holds the high bid: a flag, not a name.
     pub high_bidder: bool,
     /// The seller's name; `None` while the name query is in flight.
     pub owner: Option<String>,
-    /// The time-left bucket, `1..=4` (Short/Medium/Long/Very Long); `0` = not known yet.
+    /// The time-left bucket, `1..=4` (Short, Medium, Long, Very Long); 0 when not known yet.
     pub time_left: u32,
-    /// The full item link, built app-side from the row's entry + enchant + random-property +
-    /// suffix (auction rows carry all four on the wire, so the link is the complete one).
+    /// The full item link: auction rows carry entry, enchant, random property and suffix.
     pub link: Option<String>,
 }
 
-/// One of the three lists: the batch the server sent, the pre-cap match count, and the sort stack
-/// that ordered it.
+/// One of the three lists: the batch the server sent, the pre-cap match count and its sort stack.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct AuctionListState {
-    /// The current batch, already in display order (≤50 — the server's own page cap).
+    /// The current batch in display order, at most 50 (the server's page cap).
     pub rows: Vec<AuctionItemRow>,
-    /// `totalAuctions` — how many matched *before* the 50-row cap, so the pager can say
-    /// "( %d total )". Equal to `rows.len()` when everything fits on one page.
+    /// `totalAuctions`: the match count before the 50-row cap.
     pub total: u32,
     /// The most-recently-clicked sort stack, primary first: `(key, reversed)`.
     pub sort: Vec<(String, bool)>,
@@ -142,21 +90,18 @@ impl AuctionListState {
     }
 }
 
-/// One row of the Browse tab's category tree, pushed by the app from the player's own
-/// `ItemClass.dbc` / `ItemSubClass.dbc` (decision 1511 §5 — the set and order of classes is a
-/// structural fact; every string here comes off the player's install).
+/// One class of the Browse tab's category tree, from the player's `ItemClass.dbc`.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct AuctionCategory {
-    /// The wire's `mainCategory` — an item class id, **not** the menu position.
+    /// The wire's `mainCategory`: an item class id, not the menu position.
     pub class_id: u32,
     pub name: String,
-    /// The `0x807060` table's second column: whether the class offers subclass rows at all.
-    /// `false` (Consumable, Trade Goods, Reagent, Miscellaneous) makes `GetAuctionItemSubClasses`
-    /// and `GetAuctionInvTypes` answer nothing — but `QueryAuctionItems` never reads it, so
-    /// [`Self::subclasses`] is still the class's full non-excluded list either way.
+    /// The `0x807060` table's second column. False (Consumable, Trade Goods, Reagent,
+    /// Miscellaneous) empties `GetAuctionItemSubClasses` and `GetAuctionInvTypes`, but
+    /// `QueryAuctionItems` never reads it.
     pub has_subclass_filter: bool,
-    /// The class's `ItemSubClass.dbc` rows whose `DisplayFlags & 2` is clear, in file order —
-    /// the list both the menu and the query's index scan walk.
+    /// The class's `ItemSubClass.dbc` rows with `DisplayFlags & 2` clear, in file order: what both
+    /// the menu and the query's index scan walk.
     pub subclasses: Vec<AuctionSubCategory>,
 }
 
@@ -165,58 +110,53 @@ pub struct AuctionSubCategory {
     /// The wire's `subCategory`.
     pub sub_id: u32,
     pub name: String,
-    /// Whether selecting this subclass offers the 14 inventory-slot rows beneath it
-    /// (`GetAuctionInvTypes`) — the row's `ItemSubClass.Flags & 0x200` (`0x4cfb63`), read
-    /// app-side off the player's own DBC.
+    /// `ItemSubClass.Flags & 0x200` (`0x4cfb63`): whether the subclass offers the 14
+    /// inventory-slot rows.
     pub has_inv_types: bool,
 }
 
-/// The open auction house's snapshot. Pushed whole by the app; `None` means no auctioneer session
-/// is open (the window is closed).
+/// The open auction house's snapshot, pushed whole by the app.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct AuctionState {
     /// Browse / Bids / Auctions, indexed by [`LIST`], [`BIDDER`], [`OWNER`].
     pub lists: [AuctionListState; 3],
-    /// `GetAuctionHouseDepositRate()` — the percentage this house charges, read from
-    /// `AuctionHouse.dbc` at the `houseId` the hello reply carried.
+    /// `GetAuctionHouseDepositRate()`: the house's `AuctionHouse.dbc` deposit percentage.
     pub deposit_percent: u32,
 }
 
-/// A drained `QueryAuctionItems` — the Browse search, exactly as the reference builds it: every
-/// filter is already the wire's item-template id (the binding maps the Lua's menu positions, as
-/// `0x4ce980` does). The app copies this into `CMSG_AUCTION_LIST_ITEMS` (decision 1511 P1).
+/// A drained `QueryAuctionItems`, the `CMSG_AUCTION_LIST_ITEMS` filters: each is already a wire id,
+/// mapped from the Lua's menu position as `0x4ce980` does.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct AuctionQuery {
     pub name: String,
     /// `0` = no filter, for both.
     pub min_level: u32,
     pub max_level: u32,
-    /// `None` = no filter (the wire's `0xFFFFFFFF` sentinel). Ids, never menu positions: an
-    /// `InventoryType`, an item class, a subclass of that class.
+    /// `None` = no filter (the wire's `0xFFFFFFFF`), for all three.
     pub inv_type: Option<u32>,
     pub class: Option<u32>,
     pub sub_class: Option<u32>,
-    /// A **minimum** quality, not an equality. `None` = no filter (the dropdown's `All`, −1).
+    /// A minimum quality, not an equality; `None` = no filter (the dropdown's All, -1).
     pub quality: Option<u32>,
-    /// The page, 0-based. The app multiplies by 50 for the wire's item offset.
+    /// 0-based; the app multiplies by 50 for the wire's item offset.
     pub page: u32,
     pub usable_only: bool,
 }
 
-/// A drained `StartAuction` (decision 1511 P2).
+/// A drained `StartAuction`.
 #[derive(Clone, Debug, PartialEq)]
 pub struct AuctionStartRequest {
     pub min_bid: u32,
     /// `0` = no buyout.
     pub buyout: u32,
-    /// Minutes — only 120, 480 or 1440 are legal, and the reference refuses to send anything else.
+    /// Minutes: 120, 480 or 1440, the only values the reference sends.
     pub duration: u32,
 }
 
 /// A drained `PlaceAuctionBid`.
 #[derive(Clone, Debug, PartialEq)]
 pub struct AuctionBid {
-    /// The list the index addresses ([`LIST`] or [`BIDDER`] — the Auctions tab has no bid button).
+    /// [`LIST`] or [`BIDDER`]: the Auctions tab has no bid button.
     pub list: usize,
     /// 1-based row within the current batch; the app maps it to the wire auction id.
     pub index: u32,
@@ -224,32 +164,23 @@ pub struct AuctionBid {
 }
 
 impl super::UiScript {
-    /// Push (or clear, with `None`) the open auction house's snapshot. Replacing a list's rows
-    /// **clears that list's selection**, which is why this is one call and not two: the reference's
-    /// selection is C-side state that cannot survive the batch it indexes into, and a stale index
-    /// would silently address a different auction.
-    /// Push the Browse tab's class tree — `GetAuctionItemClasses` and its two siblings read it.
-    /// Login-scoped, not the session's: the stock `AuctionFrameBrowse_OnLoad` reads the classes at
-    /// the addon's LOAD, before any auctioneer, and in the client they are `ItemClass.dbc` names
-    /// with no session behind them (1971).
+    /// Push the Browse tab's class tree. Login-scoped: the stock `AuctionFrameBrowse_OnLoad` reads
+    /// the classes when the addon loads, before any auctioneer session.
     pub fn set_auction_item_classes(&mut self, classes: Vec<AuctionCategory>) {
         self.model_mut().auction_item_classes = classes;
     }
 
     pub fn set_auction(&mut self, state: Option<AuctionState>) {
         let mut model = self.model_mut();
-        // Only opening or closing the session drops the selection. A new PAGE does not, and
-        // neither does a re-sort: the selection is an auction **id**, so it survives the row
-        // moving and simply stops resolving if the auction leaves the page (`0x4cfda0`/`0x4cfec0`).
+        // Only opening or closing the session drops the selection: it is an auction id, so it
+        // survives a new page or a re-sort and stops resolving when the auction leaves the page.
         if model.auction.is_none() || state.is_none() {
             model.auction_selected = [0; 3];
         }
         model.auction = state;
     }
 
-    /// Push `CanSendAuctionQuery()`'s answer — the app's throttle, read by the Search button's
-    /// every-frame `OnUpdate`. Separate from the snapshot precisely because it changes every frame
-    /// while throttled and would otherwise churn the snapshot's diff.
+    /// Push `CanSendAuctionQuery()`'s answer, the app's query throttle.
     pub fn set_auction_can_query(&mut self, can: bool) {
         self.model_mut().auction_can_query = can;
     }
@@ -294,8 +225,7 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().auction_close)
     }
 
-    /// The item currently in the sell slot — the app resolves its `(bag, slot)` to the wire item
-    /// guid when `StartAuction` fires (the lazy resolve mail's send uses).
+    /// The sell slot's `(bag, slot)`, resolved by the app to the item guid on `StartAuction`.
     pub fn auction_sell_item(&mut self) -> Option<(i64, u32)> {
         self.model_mut()
             .auction_sell_item
@@ -303,14 +233,12 @@ impl super::UiScript {
             .map(|it| (it.bag, it.slot))
     }
 
-    /// Empty the sell slot — the app calls this once the auction is away, and on session close.
+    /// Empty the sell slot, once the auction is sent and on session close.
     pub fn clear_auction_sell_item(&mut self) {
         self.model_mut().auction_sell_item = None;
     }
 }
 
-/// Fetch a cloned row for a list type + 1-based index, or `None` (unknown type / out of range /
-/// no session open).
 fn row_at(model: &Model, kind: &str, index: usize) -> Option<AuctionItemRow> {
     let i = list_index(kind)?;
     model
@@ -320,12 +248,11 @@ fn row_at(model: &Model, kind: &str, index: usize) -> Option<AuctionItemRow> {
         .cloned()
 }
 
-/// The sell slot's `(name, texture, count, quality, canUse, stackValue)`, or `None` when empty.
-/// `stackValue` is the item's vendor sell price **times the stack**, which is what the reference's
-/// suggested opening price and the deposit are both computed from.
+/// The sell slot's `(name, texture, count, quality, canUse, stackValue)`, `stackValue` being the
+/// vendor price times the stack: the base of the suggested opening price and the deposit.
 fn sell_item_info(model: &Model) -> Option<(String, Option<String>, u32, i64, bool, u32)> {
     let it = model.auction_sell_item.as_ref()?;
-    // The TRUE stack size, not the split-carry field — the deposit is per stack.
+    // The real stack size, not the split-carry field: the deposit is per stack.
     let count = cursor::held_count(model, it);
     let template = model.item_templates.get(&it.item_id);
     let name = cursor::item_link_name(it.link.as_deref());
@@ -342,10 +269,8 @@ fn sell_item_info(model: &Model) -> Option<(String, Option<String>, u32, i64, bo
     ))
 }
 
-/// The real client's deposit arithmetic, reproduced including its intermediate truncation
-/// (decision 1511 §7): `floor(rate × stackValue / 100) × floor(minutes / 120)`. Both floors matter
-/// — the inner one is what makes a cheap stack deposit zero here while the server still charges a
-/// few copper, and the outer is why 120/480/1440 minutes scale as 1/4/12 rather than continuously.
+/// The reference client's deposit, `floor(rate × stackValue / 100) × floor(minutes / 120)`: the
+/// inner floor zeroes a cheap stack the server still charges a few copper for.
 fn deposit_for(rate: u32, stack_value: u32, minutes: u32) -> u32 {
     let per_unit = u64::from(rate).saturating_mul(u64::from(stack_value)) / 100;
     let units = u64::from(minutes) / 120;
@@ -355,8 +280,7 @@ fn deposit_for(rate: u32, stack_value: u32, minutes: u32) -> u32 {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetNumAuctionItems(type) → numBatchAuctions, totalAuctions. The pair is the whole paging
-    // model: batch is what this packet carried (≤50), total is what matched before the cap.
+    // GetNumAuctionItems(type) → numBatchAuctions (at most 50), totalAuctions (before the cap).
     g.set(
         "GetNumAuctionItems",
         lua.create_function(|lua, kind: String| {
@@ -379,8 +303,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetAuctionItemInfo(type, index) → the 12-tuple. `highBidder` is a FLAG, not a name — the
-    // seller's name is the last return, and it is what the Browse "Seller" column shows.
+    // GetAuctionItemInfo(type, index) → twelve values; `highBidder` is a flag, not the seller.
     g.set(
         "GetAuctionItemInfo",
         lua.create_function(|lua, (kind, index): (String, usize)| {
@@ -389,10 +312,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 row_at(&model, &kind, index)
             };
             let Some(r) = row else {
-                // The null tail is TWELVE values, not a lone nil — an unknown type string, an
-                // out-of-range index and an item-cache miss all share it, with a hard `count = 1`
-                // and `quality = -1` (one shared exit at `0x4cf1ec`). Callers
-                // destructure all twelve unguarded, so a short return throws.
+                // A miss (unknown type, out of range, not cached) still answers twelve values, with
+                // `count = 1` and `quality = -1` (one shared exit, `0x4cf1ec`), read unguarded.
                 return Ok(MultiValue::from_vec(vec![
                     Value::Nil,         // name
                     Value::Nil,         // texture
@@ -408,9 +329,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     Value::Nil,         // owner
                 ]));
             };
-            // `canUse` is computed HERE rather than pushed with the row: it depends on the
-            // player's own level, class and spellbook, which move independently of the auction
-            // snapshot. A pushed flag would go stale the moment the player dinged mid-browse.
+            // `canUse` is per call, not pushed: it follows the player's level, class and spellbook.
             let can_use = {
                 let model = lua.app_data_ref::<Model>().expect("model app_data");
                 super::item_stats::item_usable_by_id(&model, r.item_id)
@@ -441,9 +360,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetAuctionItemTimeLeft(type, index) → 1..4, the bucket the row's text and tooltip key off.
-    // 0 for a row we have no answer for yet; the reference has no live countdown (its ticking
-    // version is commented out), so this only moves when a fresh list lands.
+    // GetAuctionItemTimeLeft(type, index) → the 1..4 bucket, 0 when unknown. The reference has no
+    // live countdown: it moves only when a new list lands.
     g.set(
         "GetAuctionItemTimeLeft",
         lua.create_function(|lua, (kind, index): (String, usize)| {
@@ -452,9 +370,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetAuctionItemLink(type, index) → the full item link. Auction rows carry enchant, random
-    // property and suffix on the wire, so the app builds the complete link rather than the
-    // zeroed-tail one the bag path settles for.
     g.set(
         "GetAuctionItemLink",
         lua.create_function(|lua, (kind, index): (String, usize)| {
@@ -462,8 +377,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 let model = lua.app_data_ref::<Model>().expect("model app_data");
                 row_at(&model, &kind, index).and_then(|r| r.link)
             };
-            // A miss returns NO values at all — not nil (`0x4cf45b`). `DressUpItemLink(nil)`
-            // and `nil` reaching a chat insert behave differently from an empty argument list.
+            // A miss returns no values at all, not nil (`0x4cf45b`).
             Ok(match link {
                 Some(l) => MultiValue::from_vec(vec![Value::String(lua.create_string(&l)?)]),
                 None => MultiValue::new(),
@@ -471,13 +385,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSelectedAuctionItem(type) → the 1-based selected row, or 0 for none.
-    //
-    // Stored as the **auction id**, resolved to a row position on the way out
-    // (`0x4cfda0`/`0x4cfec0`).
-    // That indirection is the whole reason a re-sort cannot silently move the selection onto a
-    // different auction: the id follows the row wherever the comparator puts it, and an auction
-    // that has left the page simply stops resolving instead of pointing at its neighbour.
+    // GetSelectedAuctionItem(type) → the selected row, 0 for none. Stored as the auction id and
+    // resolved on the way out (`0x4cfda0`/`0x4cfec0`), so it follows its auction through a re-sort.
     g.set(
         "GetSelectedAuctionItem",
         lua.create_function(|lua, kind: String| {
@@ -499,8 +408,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetSelectedAuctionItem(type, index) — takes a row position and remembers the auction it
-    // names. An out-of-range index clears the selection rather than remembering a phantom.
+    // SetSelectedAuctionItem(type, index): remembers the auction at that row; out of range clears.
     g.set(
         "SetSelectedAuctionItem",
         lua.create_function(|lua, (kind, index): (String, usize)| {
@@ -518,9 +426,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SortAuctionItems(type, key) — queue the header click; the app owns the stacks and pushes the
-    // reordered rows back. The reference raises on a bad type, and that Usage string is recorded,
-    // so it is reproduced here rather than swallowed.
+    // SortAuctionItems(type, key): queue the header click for the app, which pushes the reordered
+    // rows back. The reference raises this `Usage:` only for an argument neither string nor number
+    // (`0x6f3510`) and matches both strings case-insensitively (`0x64a4c0`), an unknown one sorting
+    // nothing (`0x4cfd90`); here an unknown or differently cased type or column raises.
     g.set(
         "SortAuctionItems",
         lua.create_function(|lua, (kind, key): (String, String)| {
@@ -540,8 +449,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsAuctionSortReversed(type, key) → 1/nil. Answers for ANY key the stack remembers, not just
-    // the primary one — which is the whole reason a non-primary column's arrow can point down.
+    // IsAuctionSortReversed(type, key) → 1/nil, for any key the stack remembers.
     g.set(
         "IsAuctionSortReversed",
         lua.create_function(|lua, (kind, key): (String, String)| {
@@ -553,8 +461,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CanSendAuctionQuery() → 1/nil. Polled every frame by the Search button's OnUpdate, because
-    // a throttled query is dropped silently and there is no failure event to react to.
+    // CanSendAuctionQuery() → 1/nil; a throttled query is dropped silently.
     g.set(
         "CanSendAuctionQuery",
         lua.create_function(|lua, ()| {
@@ -563,10 +470,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetAuctionItemClasses() → the class names, in the reference's own menu order. The ORDER and
-    // the set are structural (ten auctionable classes); every string is the player's own
-    // ItemClass.dbc row, so none of Blizzard's text ships with us (decisions 1234/1260). Static —
-    // pushed at login, read by the stock addon at its load (1971), no session required.
+    // GetAuctionItemClasses() → the ten auctionable class names in the reference's menu order, off
+    // the player's ItemClass.dbc; pushed at login, no session needed.
     g.set(
         "GetAuctionItemClasses",
         lua.create_function(|lua, ()| {
@@ -586,9 +491,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetAuctionItemSubClasses(classIndex) → the subclass names under a 1-based menu class. An
-    // out-of-range index, or a class whose `0x807060` flag is 0, returns nothing — the
-    // reference's own bound-with-no-error (`0x4cfa00`, `0x4cfa0e`).
+    // GetAuctionItemSubClasses(classIndex) → the subclass names; an out-of-range index or a class
+    // whose `0x807060` flag is 0 returns nothing, without an error (`0x4cfa00`, `0x4cfa0e`).
     g.set(
         "GetAuctionItemSubClasses",
         lua.create_function(|lua, class_index: usize| {
@@ -610,12 +514,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetAuctionInvTypes(classIndex, subclassIndex) → the 14 inventory-slot GlobalString KEYS, or
-    // nothing. The pair only decides WHETHER the list is offered — the list itself is fixed.
-    // `0x4cfab0`: no class (index out of range, or its `0x807060` flag 0) → nothing; a FOUND
-    // subclass offers the list only with `ItemSubClass.Flags & 0x200` (pushed as
-    // `has_inv_types`); and a subclass index the scan runs off the end of skips that gate and
-    // offers all fourteen (the exhaust edge at `0x4cfb61` lands past the gate at `0x4cfb63`).
+    // GetAuctionInvTypes(classIndex, subclassIndex) → the fixed 14 inventory-slot GlobalString
+    // keys, or nothing (`0x4cfab0`): nothing without a class (or with its `0x807060` flag 0); a
+    // found subclass needs `Flags & 0x200`, but an index the scan runs past skips that gate (the
+    // exhaust edge at `0x4cfb61` lands past the test at `0x4cfb63`).
     g.set(
         "GetAuctionInvTypes",
         lua.create_function(|lua, (class_index, sub_index): (usize, usize)| {
@@ -644,12 +546,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // QueryAuctionItems(name, minLevel, maxLevel, invTypeIndex, classIndex, subclassIndex, page,
-    // isUsable, qualityIndex) — nine arguments (TBC's tenth, exactMatch, does not exist on 5875).
-    // The level boxes hand us strings. Every filter argument is a 1-based MENU POSITION, and —
-    // exactly as the reference's `0x4ce980` does — it is turned into the wire's item-template id
-    // here, before anything is queued: invType through the `0x8070b0` rows, class through the
-    // `0x807060` table, subclass as the Nth non-excluded subclass row of that class (a scan that
-    // never reads the class's filter flag). Anything that does not resolve is the wire's "any".
+    // isUsable, qualityIndex): nine arguments, no `exactMatch` in 1.12. Each filter is a 1-based
+    // menu position mapped to the wire id as `0x4ce980` does: invType through the `0x8070b0` rows,
+    // class through `0x807060`, subclass as the class's Nth non-excluded row (a scan that never
+    // reads the class's filter flag). Anything unresolved is the wire's "any".
     g.set(
         "QueryAuctionItems",
         lua.create_function(|lua, args: MultiValue| {
@@ -679,7 +579,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 Some(Value::Number(n)) if *n >= 0.0 => Some(*n as u32),
                 _ => None,
             };
-            // A 1-based position into a table, `None` for a missing, zero or negative argument.
             let position = |i: usize| num(i).and_then(|n| (n as usize).checked_sub(1));
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
             let inv_type = position(3)
@@ -707,8 +606,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetOwnerAuctionItems([page]) / GetBidderAuctionItems([page]) — the other two tabs' fetches.
-    // Neither is throttled the way Browse is; both default to page 0.
+    // GetOwnerAuctionItems([page]) / GetBidderAuctionItems([page]): unthrottled, page 0 by default.
     g.set(
         "GetOwnerAuctionItems",
         lua.create_function(|lua, page: Option<u32>| {
@@ -726,8 +624,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // PlaceAuctionBid(type, index, bidAmount). A buyout is not a distinct verb — it is a bid of
-    // exactly the buyout price, which is why the confirmation popup calls straight into this.
+    // PlaceAuctionBid(type, index, bidAmount); a buyout is a bid of exactly the buyout price.
     g.set(
         "PlaceAuctionBid",
         lua.create_function(|lua, (kind, index, amount): (String, u32, u32)| {
@@ -744,7 +641,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // StartAuction(minBid, buyoutPrice, runTime) — runTime in minutes.
+    // StartAuction(minBid, buyoutPrice, runTime), runTime in minutes.
     g.set(
         "StartAuction",
         lua.create_function(|lua, (min_bid, buyout, duration): (u32, u32, u32)| {
@@ -758,7 +655,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CancelAuction(index) — always an "owner" row.
+    // CancelAuction(index), always an "owner" row.
     g.set(
         "CancelAuction",
         lua.create_function(|lua, index: u32| {
@@ -768,8 +665,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetAuctionHouseDepositRate() → the percentage, off AuctionHouse.dbc at this session's house.
-    // The shipped reference addon never calls it; third-party addons may, so we ship it.
     g.set(
         "GetAuctionHouseDepositRate",
         lua.create_function(|lua, ()| {
@@ -781,8 +676,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CalculateAuctionDeposit(runTime) → copper. See `deposit_for` — this is the client's own
-    // arithmetic, truncation included, not the server's charge.
+    // CalculateAuctionDeposit(runTime) → copper, by the client's arithmetic (`deposit_for`).
     g.set(
         "CalculateAuctionDeposit",
         lua.create_function(|lua, minutes: u32| {
@@ -793,9 +687,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetAuctionSellItemInfo() → name, texture, count, quality, canUse, price. SIX values ALWAYS —
-    // the empty slot pushes a hard count of 1 and a quality of -1, never nils, because the
-    // reference Lua reads that count unguarded the moment the slot empties.
+    // GetAuctionSellItemInfo() → name, texture, count, quality, canUse, price: six values always.
+    // An empty slot answers count 1 and quality -1: the stock Lua reads `count > 1` unguarded.
     g.set(
         "GetAuctionSellItemInfo",
         lua.create_function(|lua, ()| {
@@ -831,9 +724,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ClickAuctionSellItemButton() — attach the cursor's item, or take back the attached one. The
-    // mail send slot's exact shape (decision 0216's rails): every cursor write is followed by both
-    // queues, which is the law that keeps CURSOR_UPDATE and ITEM_LOCK_CHANGED honest.
+    // ClickAuctionSellItemButton(): attach the cursor's item, or pick the attached one back up;
+    // every cursor write queues both CURSOR_UPDATE and ITEM_LOCK_CHANGED.
     g.set(
         "ClickAuctionSellItemButton",
         lua.create_function(|lua, ()| {
@@ -843,7 +735,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CloseAuctionHouse() — the client-side close. Vanilla sends nothing; the session simply ends.
+    // CloseAuctionHouse(): the client-side close; nothing goes on the wire.
     g.set(
         "CloseAuctionHouse",
         lua.create_function(|lua, ()| {
@@ -856,10 +748,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// The fourteen inventory-slot rows the reference offers — the `0x8070b0` table's
-/// `{u32 invTypeId; char name[0x20]}` rows, in its own order. The name is a GlobalString **key**
-/// the Lua resolves through the player's own strings, so no English ships here; the id is what
-/// `QueryAuctionItems` puts on the wire for the row's 1-based position.
+/// The `0x8070b0` table's fourteen `{u32 invTypeId; char name[0x20]}` rows, in its order: the id
+/// goes on the wire, the name is a GlobalString key.
 const AUCTION_INV_TYPES: [(u32, &str); 14] = [
     (1, "INVTYPE_HEAD"),
     (2, "INVTYPE_NECK"),
@@ -877,9 +767,8 @@ const AUCTION_INV_TYPES: [(u32, &str); 14] = [
     (23, "INVTYPE_HOLDABLE"),
 ];
 
-/// Attach the cursor's held item to the sell slot, or — with an empty cursor — pick the attached
-/// one back up. A spell or action payload is refused and put back untouched, exactly as the mail
-/// send slot refuses it.
+/// Attach the cursor's item to the sell slot, or with an empty cursor pick the attached one back
+/// up; any other payload stays on the cursor.
 fn click_auction_sell_item(model: &mut Model) {
     match model.cursor.take() {
         Some(CursorPayload::Item(item)) => {
@@ -927,12 +816,6 @@ mod tests {
         state
     }
 
-    /// The selection is an auction id, not a row position — so a re-sort moves the row under it
-    /// and the selection follows, rather than coming to mean whatever took that slot.
-    ///
-    /// This is the case an index would get silently wrong: pick row 2, re-sort, and an
-    /// index-based selection is now pointing at a *different auction* that the Bid button would
-    /// happily bid on.
     #[test]
     fn the_selection_follows_its_auction_through_a_resort() {
         let mut s = UiScript::new().unwrap();
@@ -955,7 +838,7 @@ mod tests {
             "auction 22 moved to row 1 and the selection went with it"
         );
 
-        // It leaves the page entirely (outbid, bought, or filtered out by a new search).
+        // It leaves the page.
         s.set_auction(Some(page(&[33, 44])));
         assert_eq!(
             s.eval::<i64>(r#"return GetSelectedAuctionItem("list")"#)
@@ -976,17 +859,12 @@ mod tests {
         );
     }
 
-    /// A WHOLE-STACK pickup carries no count of its own, so the sell slot has to read the real
-    /// stack size back off the source slot. Reading the cursor field directly answers 1 for a
-    /// stack of twenty — and since the deposit is charged per stack, the pane would quote a
-    /// twentieth of what the server then takes.
     #[test]
     fn the_sell_slot_reads_a_whole_stacks_real_size() {
         use crate::script::container::{ContainerSlot, ContainerState};
         use crate::script::cursor::CursorItem;
 
         let mut s = UiScript::new().unwrap();
-        // Twenty of item 2589 sitting in backpack slot 1.
         let mut slots = std::collections::HashMap::new();
         slots.insert(
             1u32,
@@ -1004,7 +882,7 @@ mod tests {
                 slots,
             }),
         );
-        // Picked up whole — `count: None` is the "whole stack" signal, not "one".
+        // Picked up whole: `count: None` means the whole stack, not one.
         {
             let mut model = s.model_mut();
             model.auction_sell_item = Some(CursorItem {
@@ -1025,9 +903,6 @@ mod tests {
         assert_eq!(count, 20, "the whole stack, not one of it");
     }
 
-    /// The null tail is twelve values with a hard `count = 1` and `quality = -1`. The reference
-    /// Lua destructures all twelve unguarded, so a short return throws rather than showing an
-    /// empty row.
     #[test]
     fn a_missing_row_still_answers_twelve_values() {
         let s = UiScript::new().unwrap();
@@ -1038,18 +913,14 @@ mod tests {
             .unwrap();
         assert_eq!((count, quality), (1, -1));
 
-        // The link, by contrast, answers with NO values on a miss — not a nil.
+        // The link answers no values on a miss, not a nil.
         let n = s.arity(r#"GetAuctionItemLink("list", 99)"#).unwrap();
         assert_eq!(n, 0, "zero values, not one nil");
     }
 
-    /// The client's own deposit arithmetic, including the intermediate truncation that makes it
-    /// disagree with the server (decision 1511 §7). The cheap-stack case is the one that matters:
-    /// a 9-copper vendor value at 5% over 24h floors to 0 here while vmangos still charges 5, and
-    /// that divergence is deliberate — the label is a client artifact.
+    /// A 9-copper stack at 5% over 24 h deposits 0 here, where vmangos charges 5.
     #[test]
     fn the_deposit_is_the_clients_arithmetic_truncation_and_all() {
-        // 5% of 9c = 0 after the inner floor, so no duration can lift it off zero.
         assert_eq!(deposit_for(5, 9, 1440), 0);
         // Once the inner floor clears, the duration scales it 1 / 4 / 12.
         assert_eq!(deposit_for(5, 10_000, 120), 500);
@@ -1057,14 +928,11 @@ mod tests {
         assert_eq!(deposit_for(5, 10_000, 1440), 6_000);
         // Blackwater's 25% on the same stack.
         assert_eq!(deposit_for(25, 10_000, 120), 2_500);
-        // A duration under the two-hour unit floors the whole thing away — the reference refuses
-        // to send such a duration at all, so this is a shape check, not a reachable state.
+        // Under the two-hour unit it floors to 0; the reference never sends such a duration.
         assert_eq!(deposit_for(5, 10_000, 60), 0);
     }
 
-    /// The browse tree as the reference's `0x807060` table shapes it: Weapon (filterable) first,
-    /// then Armor, then Consumable (flag 0 — no subclass rows offered, but its subclasses still
-    /// exist for the query's own scan).
+    /// Weapon and Armor, then Consumable (flag 0: no subclass rows, but the query scans them).
     fn tree() -> Vec<AuctionCategory> {
         let sub = |sub_id: u32, name: &str, has_inv_types: bool| AuctionSubCategory {
             sub_id,
@@ -1093,10 +961,6 @@ mod tests {
         ]
     }
 
-    /// `QueryAuctionItems` takes menu POSITIONS and puts item-template IDS on the wire — the
-    /// reference does the mapping itself (`0x4ce980`: invType through `0x8070b0`, class through
-    /// `0x807060`, subclass as the Nth non-excluded `ItemSubClass.dbc` row of that class). Sending
-    /// the position instead asked vmangos for class 1 (Container) when the player picked Weapon.
     #[test]
     fn query_sends_ids_not_menu_positions() {
         let mut s = UiScript::new().unwrap();
@@ -1110,7 +974,7 @@ mod tests {
         assert_eq!(q.class, Some(2), "Weapon is item class 2, not position 1");
         assert_eq!(q.sub_class, Some(0), "the first weapon subclass is id 0");
 
-        // Armor / its SECOND subclass skips the id gap: Shield is 6, not 2.
+        // Armor / its second subclass skips the id gap: Shield is 6, not 2.
         s.run(r#"QueryAuctionItems("", "", "", 14, 2, 2, 0, nil, -1)"#)
             .unwrap();
         let q = s.take_auction_query().expect("queued");
@@ -1119,8 +983,7 @@ mod tests {
             (Some(23), Some(4), Some(6))
         );
 
-        // The query's scan ignores the class's filter flag: Consumable offers no subclass rows,
-        // yet an index still resolves against its (non-excluded) subclasses.
+        // The scan ignores the filter flag: Consumable offers no subclass rows, yet resolves one.
         s.run(r#"QueryAuctionItems("", "", "", 0, 3, 1, 0, nil, -1)"#)
             .unwrap();
         let q = s.take_auction_query().expect("queued");
@@ -1137,10 +1000,7 @@ mod tests {
         assert_eq!((q.inv_type, q.class, q.sub_class), (None, Some(2), None));
     }
 
-    /// `0x4cf9c0` / `0x4cfab0` return nothing for a class whose `0x807060` flag is 0, and
-    /// `0x4cfab0` gates a FOUND subclass on `ItemSubClass.Flags & 0x200` but pushes all fourteen
-    /// when the scan runs off the end (the exhaust edge at `0x4cfb61` lands past the gate at
-    /// `0x4cfb63`).
+    /// The gates of `0x4cf9c0` (subclasses) and `0x4cfab0` (inventory types).
     #[test]
     fn subclass_and_inv_type_menus_follow_the_reference_gates() {
         let mut s = UiScript::new().unwrap();
@@ -1162,8 +1022,6 @@ mod tests {
         );
     }
 
-    /// The sort stack answers for any key it remembers, not just the primary — the reason a
-    /// non-primary column's arrow can still point down.
     #[test]
     fn reversed_answers_for_any_remembered_key() {
         let list = AuctionListState {
diff --git a/crates/benilla-ui/src/script/aura/mod.rs b/crates/benilla-ui/src/script/aura/mod.rs
index d0553987..db930c69 100644
--- a/crates/benilla-ui/src/script/aura/mod.rs
+++ b/crates/benilla-ui/src/script/aura/mod.rs
@@ -1,86 +1,15 @@
-//! The game-state aura bindings — **two dialects over one list** (decisions 0255, 0257).
+//! The aura bindings, over the per-token lists the app pushes through [`UiScript::set_auras`] in
+//! display order: the player's in the reference's insertion-ordered cache (`0xbc6040`), kept by
+//! `benilla::ui_aura`, any other unit's by ascending aura slot. The player's list keeps cache order
+//! under every token, where the reference's `UnitBuff("player", i)` reads by slot.
 //!
-//! Same engine-free seam as [`super::unit`]: the app pushes a per-token, **already ordered** list of
-//! [`AuraState`] via [`UiScript::set_auras`], and these globals index it. This module deliberately
-//! knows nothing about slots, caches, or descriptors — the *order* of the list is the app's to decide,
-//! because the two orderings the reference uses are not derivable from a snapshot:
+//! `UnitAura`, `UnitBuff`, `UnitDebuff` and `CancelUnitBuff` take a token and a 1-based index into
+//! the sign-filtered list; the getters answer nil past the end. The 1.12 `GetPlayerBuff`
+//! ([`player_buff`]) takes a 0-based index and returns a cache position, the same number under
+//! every filter, which its siblings and `GameTooltip:SetPlayerBuff` take in place of the counter.
 //!
-//! - the player's own bar walks a densely packed cache in **insertion order** (`GetPlayerBuff`), and
-//! - any other unit is read straight off its aura array, ascending slot (`UnitBuff`/`UnitDebuff`).
-//!
-//! Decision 0257 resolves that split toward the player-bar law for the local player under every token,
-//! since the Era API has one aura function where 1.12 had two.
-//!
-//! # The two dialects
-//!
-//! **Era** — `UnitAura`/`UnitBuff`/`UnitDebuff`/`CancelUnitBuff`: a token plus a **1-based** index
-//! *within the sign-filtered list*, terminated by a bare `nil`. This is the shape our own transcribed
-//! frames use.
-//!
-//! **1.12** — the `GetPlayerBuff*` family plus `CancelPlayerBuff`: the player only, no token, a
-//! **0-based** index, and — the part no documentation gets right — `GetPlayerBuff` does not return the
-//! aura. It returns a **handle**: the aura's *physical position* in the cache, `-1` past the end. Every
-//! sibling (`GetPlayerBuffTexture`, `…TimeLeft`, `…DispelType`, `…Applications`, `CancelPlayerBuff`,
-//! and `GameTooltip:SetPlayerBuff`) takes that position, **not** the loop counter. So the family is a
-//! two-step: enumerate to get a position, then read the position.
-//!
-//! That two-step is what makes the index space *absolute*: the position a filtered enumeration hands
-//! back is the same number an unfiltered one would, which is exactly what the corpus relies on
-//! (`CT_BuffMod/CT_BuffFrame.lua:73-79` obtains an index under `"HARMFUL"` and compares it for
-//! equality against one obtained under `"HELPFUL|HARMFUL"`; `Zorlen/Zorlen.lua:2798` intersects the
-//! filtered and unfiltered walks at the same counter).
-//!
-//! Because [`AuraState`] lists are pushed in the app's display order and the player's list **is** the
-//! reference's `0xbc6040` insertion-ordered cache (`benilla::ui_aura`), a cache position is simply a
-//! 0-based index into `model.auras["player"]`. No second structure exists, and none is needed.
-//!
-//! # Byte-verified signatures (the 1.12.1 binary)
-//!
-//! Read off the disassembly, not off a wiki — a later client changed every one of these shapes, and a
-//! wrong shape fails *silently*.
-//!
-//! | verb | addr | returns | miss |
-//! |---|---|---|---|
-//! | `GetPlayerBuff(index [, "filter"])` | `0x4e45d0` | **always 2** numbers: `pos`, `untilCancelled` | `(-1, 0)` |
-//! | `GetPlayerBuffTexture(pos)` | `0x4e4740` | 1: icon path or nil | nil |
-//! | `GetPlayerBuffDispelType(pos)` | `0x4e4800` | 1: dispel-class name or nil | nil |
-//! | `GetPlayerBuffApplications(pos)` | `0x4e48b0` | 1: number | **`1`** |
-//! | `GetPlayerBuffTimeLeft(pos)` | `0x4e4930` | 1: **seconds** | `0` |
-//! | `CancelPlayerBuff(pos)` | `0x4e49a0` | **0** values | — |
-//!
-//! The traps, each with the site that pins it:
-//!
-//! - **`-1`, never nil.** `GetPlayerBuff` seeds its out-parameter to `-1` (`mov DWORD PTR [ebp-4],
-//!   0xffffffff`, `0x4e46ea`) and pushes it unconditionally, then pushes `record+0xc` or `0`
-//!   (`0x4e46f6`/`0x4e4728`), returning `mov eax,0x2` on **both** paths. The corpus terminates on the
-//!   number — `while GetPlayerBuff(counter) >= 0 do` (`_LazyPig/LazyPig.lua:1174`) — so a nil past the
-//!   end is `attempt to compare nil with number`, and *zero* returns is the same crash.
-//! - **0-based.** `lua_tonumber` → `__ftol` → used raw, with **no `dec`** (`0x4e460a`-`0x4e4616`);
-//!   contrast `UnitBuff 0x519500`, which does `dec eax` at `0x519579`. Every enumerating call site in
-//!   the corpus starts at `0`; the reference's own buttons are `BuffButton0`..`BuffButton23` with
-//!   `id="0"` upward (`ref-BuffFrame.xml:159`).
-//! - **The default filter is `HELPFUL|HARMFUL`, not `HELPFUL`.** `mov esi,0x3` at `0x4e4618`, kept
-//!   when the `lua_isstring` check on arg 2 fails. This is the one that would have failed silently:
-//!   `Zorlen/Zorlen.lua:2797-2801` walks *unfiltered* and feeds each index to
-//!   `GetPlayerBuffDispelType` looking for `"Poison"`/`"Disease"` (`Zorlen_Other.lua:94,98`) — a
-//!   debuff-only concept. Under a `HELPFUL` default that check never matches, and nothing errors.
-//! - **`untilCancelled` is the number `0`/`1`.** Five corpus sites compare it to the *number* `1`
-//!   (`CT_BuffMod/CT_BuffFrame.lua:175,232`; `_LazyPig/LazyPig.lua:2071`; `Zorlen/Zorlen.lua:2800`;
-//!   `ElkBuffBar/ElkBuffBar.lua:502`), as does `ref-BuffFrame.lua:124`. A boolean breaks all six:
-//!   `true ~= 1`.
-//! - **`PASSIVE` is not a token here.** The parser knows exactly four (`stricmp` against `0x84bc34`
-//!   `HELPFUL`=`0x1`, `0x84bc2c` `HARMFUL`=`0x2`, `0x84bc20` `CANCELABLE`=`0x10`, `0x84bc10`
-//!   `NOT_CANCELABLE`=`0x20`; `0x4e4661`-`0x4e46cf`). A `"PASSIVE"` string does exist in the binary at
-//!   `0x806a30`, but `0x4e45d0` never references it — and no corpus addon passes it.
-//! - **The mask starts at ZERO once a filter string is given** (`xor esi,esi`, `0x4e4639`). So
-//!   `GetPlayerBuff(0, "CANCELABLE")` matches *nothing* — neither sign bit is set — where
-//!   [`super::unit`]-style parsing would have defaulted the sign to helpful. Delimiters are
-//!   `" |"` (`0x84bc3c`), i.e. space **or** pipe.
-//!
-//! **Stated gaps, not hidden.** `source` (the caster) is always nil and `duration`/`expirationTime`
-//! are `0` for every unit but the player: the 1.12 wire carries no aura caster at all, and no duration
-//! for anyone but yourself (byte-verified, decision 0257 B6/B10). The reference's own target and party
-//! frames show no timers for the same reason.
+//! `source` is always nil, and only the player's auras carry a duration: the 1.12 wire has no aura
+//! caster and sends durations for the player alone, so the stock target frame shows no timers.
 
 use mlua::{Lua, MultiValue, Value};
 
@@ -88,69 +17,51 @@ use super::Model;
 
 mod player_buff;
 
-/// One aura on one unit, as the Era `UnitAura` family reports it. Plain data (no mlua handles, no ECS
-/// types), pushed by the app's [`crate::script::UiScript::set_auras`] feed each frame.
+/// One aura on one unit, as the app's [`crate::script::UiScript::set_auras`] feed pushes it.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct AuraState {
-    /// `Spell.dbc` id (`UnitAura`'s `spellId`).
+    /// `Spell.dbc` id, `UnitAura`'s `spellId`.
     pub spell_id: u32,
-    /// The spell's name, or `None` when the catalog doesn't know the id (`UnitAura` returns nil).
+    /// The spell's name; `None` when the catalog lacks the id.
     pub name: Option<String>,
     /// The icon's extensionless MPQ path (`Interface\Icons\…`).
     pub icon: Option<String>,
-    /// Stack count, ≥ 1 (`UnitAura`'s `count`). The reference shows the number only above 1.
+    /// Stack count, at least 1; the reference shows it only above 1.
     pub count: u8,
-    /// `"Magic"`/`"Curse"`/`"Disease"`/`"Poison"`, or `None` for an undispellable class — the
-    /// `debuffType` return, which the debuff border tints by.
+    /// `"Magic"`, `"Curse"`, `"Disease"`, `"Poison"` or `None`; the debuff border tints by it.
     pub debuff_type: Option<String>,
-    /// The full duration in seconds as the last apply/refresh reported it; `0.0` = no duration
-    /// (a permanent aura, or any aura on a unit that isn't the player).
+    /// Seconds, from the last apply or refresh; 0 when permanent or on a unit not the player.
     pub duration: f64,
-    /// The `GetTime()`-based instant this aura runs out; `0.0` when [`Self::duration`] is `0.0`.
-    /// Lua counts down against it, exactly as `CastingBar.xml` does for a cast.
+    /// The `GetTime()` instant it runs out; 0 when [`Self::duration`] is 0.
     pub expiration_time: f64,
-    /// A buff (helpful) rather than a debuff — the `HELPFUL`/`HARMFUL` filter's discriminator.
+    /// A buff rather than a debuff: the `HELPFUL`/`HARMFUL` filter's test.
     pub helpful: bool,
-    /// Whether right-clicking it will be honoured (the wire's `AFLAG_CANCELABLE`) — the
-    /// `CANCELABLE`/`NOT_CANCELABLE` filter's discriminator.
+    /// The wire's `AFLAG_CANCELABLE`: the `CANCELABLE`/`NOT_CANCELABLE` filter's test.
     pub cancelable: bool,
-    /// **`GetPlayerBuff`'s second return** — the reference's cache record `+0xc`: "this aura has no
-    /// finite duration to display."
-    ///
-    /// DBC-derived at cache-build time, and deliberately **not** the same question as
-    /// `expiration_time == 0.0`: it is computed from the spell, so it is right on the frame an aura
-    /// appears, before any `SMSG_UPDATE_AURA_DURATION` has arrived. That is the whole point of it —
-    /// `ref-BuffFrame.lua:124` returns *before* calling `GetPlayerBuffTimeLeft` when it is `1`, so a
-    /// permanent aura never flickers a `0 s` timer. The app fills it (`benilla::ui_aura`) from the
-    /// byte-verified derivation at `0x4e452e`-`0x4e45c5`; see there for the two clauses.
+    /// `GetPlayerBuff`'s second return, cache record `+0xc`: no finite duration to show. Derived
+    /// from the spell (`0x4e452e`-`0x4e45c5`), not from `expiration_time`, so it holds before any
+    /// `SMSG_UPDATE_AURA_DURATION` and a permanent aura never shows a `0 s` timer.
     pub until_cancelled: bool,
-    /// `Spell.dbc` `AttributesEx & 0x4` (`SPELL_ATTR_EX_IS_CHANNELED`) — the **second** arm of the
-    /// cancel gate, and the only one that can authorise cancelling a *negative* aura. See
-    /// [`cancel_authorized`].
+    /// `AttributesEx & 0x4` (`SPELL_ATTR_EX_IS_CHANNELED`), [`cancel_authorized`]'s second arm.
     pub channeled: bool,
 }
 
-/// The player's active tracking aura — the engine mirror of the reference's tracking global
-/// (`DAT_00bc6378`): during the aura-cache rebuild the client *excludes* a tracking-effect spell
-/// (Find Minerals, Track Beasts, …) from the display cache and records it here instead;
-/// `GetTrackingTexture` is the one reader (`0x4e4a20`, the
-/// `{0x2c,0x2d,0x97}` effect test). Pushed by the app's aura feed via [`UiScript::set_tracking`];
-/// `None` = no tracking active (the minimap frame hides).
+/// The player's active tracking aura, the reference's tracking global (`0xbc6378`): the cache
+/// rebuild records a spell with a tracking effect (`0x2c`, `0x2d`, `0x97`) there instead of in
+/// the display cache, and `GetTrackingTexture` (`0x4e4a20`) reads it.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TrackingState {
-    /// `Spell.dbc` id — `CancelTrackingBuff`'s `CMSG_CANCEL_AURA` payload.
+    /// `Spell.dbc` id, the `CMSG_CANCEL_AURA` payload of `CancelTrackingBuff`.
     pub spell_id: u32,
-    /// The spell's name, or `None` when the catalog doesn't know the id (tooltip fallback line).
+    /// The spell's name; `None` when the catalog lacks the id.
     pub name: Option<String>,
-    /// The icon's extensionless MPQ path — `GetTrackingTexture`'s return (`nil` when unknown).
+    /// The icon's extensionless MPQ path, `GetTrackingTexture`'s return.
     pub icon: Option<String>,
-    /// The wire's `AFLAG_CANCELABLE` on the tracking aura's slot — `CancelTrackingBuff`'s gate,
-    /// same client-side check as `CancelUnitBuff`'s.
+    /// The wire's `AFLAG_CANCELABLE` on the aura's slot, `CancelTrackingBuff`'s gate.
     pub cancelable: bool,
 }
 
-/// The parsed `filter` argument: a `|`-separated token set. Absent or sign-less defaults to
-/// `HELPFUL`, matching the live API (`UnitAura(unit, i)` enumerates buffs).
+/// `UnitAura`'s `filter`: `|`-separated tokens, the sign defaulting to `HELPFUL` as in the Era API.
 struct Filter {
     helpful: bool,
     cancelable: Option<bool>,
@@ -161,12 +72,11 @@ impl Filter {
         let spec = spec.unwrap_or("");
         let has = |t: &str| spec.split('|').any(|s| s.trim().eq_ignore_ascii_case(t));
         Self {
-            // HARMFUL wins only if named; everything else (including "CANCELABLE" alone) is HELPFUL.
             helpful: !has("HARMFUL"),
             cancelable: match (has("CANCELABLE"), has("NOT_CANCELABLE")) {
                 (true, false) => Some(true),
                 (false, true) => Some(false),
-                // Both or neither: no cancelable constraint (the reference never passes both).
+                // Both or neither: no constraint; the reference never passes both.
                 _ => None,
             },
         }
@@ -177,35 +87,16 @@ impl Filter {
     }
 }
 
-/// May this aura be cancelled? **One law, two entry points** — `CancelUnitBuff` (the Era name) and
-/// `CancelPlayerBuff` (the 1.12 name) are the same verb over the same cache, so they share the gate
-/// and the queue rather than growing a second mechanism.
-///
-/// Byte-verified, `CancelPlayerBuff 0x4e49a0` (`0x4e49fb`-`0x4e4a14`) — an **OR** of two arms:
-///
-/// 1. the **wire** arm: the aura sits in the positive half (`record.slot < 0x20`, i.e. helpful) AND
-///    carries `AFLAG_CANCELABLE` (`record+0xa & 0x1`), which vmangos sets iff the aura is positive
-///    and the spell lacks `SPELL_ATTR_NO_AURA_CANCEL`; OR
-/// 2. the **DBC** arm: the spell has `AttributesEx & 0x4` (`SPELL_ATTR_EX_IS_CHANNELED`) — the only
-///    way a *negative* aura becomes cancellable, which is how you break a channel being held on you.
-///
-/// Neither arm alone is the gate; reading only the first (the shape `CancelUnitBuff` shipped with)
-/// silently refuses the channeled case.
+/// The cancel gate of `CancelUnitBuff` and `CancelPlayerBuff` (`0x4e49a0`, `0x4e49fb`-`0x4e4a14`):
+/// a helpful aura with `AFLAG_CANCELABLE` (vmangos: unless `SPELL_ATTR_NO_AURA_CANCEL`), or any
+/// aura of a channeled spell, the only negative aura that cancels (breaking a channel on you).
 pub(super) fn cancel_authorized(a: &AuraState) -> bool {
     (a.helpful && a.cancelable) || a.channeled
 }
 
-/// `UnitAura`'s return tuple for a hit. Order and arity follow the Classic Era signature:
-/// `name, icon, count, debuffType, duration, expirationTime, source, isStealable,
-/// nameplateShowPersonal, spellId`. The three we cannot know on this wire (`source`, `isStealable`,
-/// `nameplateShowPersonal`) return nil — an addon that reads them sees "unknown", which is honest,
-/// rather than a fabricated value.
-/// The **1.12** return tuple, which is a different shape and not a prefix of the Era one: the first
-/// value is the TEXTURE, not the name. `UnitBuff` returns `(texture, applications)` (`0x519500`) and
-/// `UnitDebuff` returns `(texture, applications, dispelType)` (`0x5198f0`) — both are what the
-/// reference's own FrameXML reads
-/// (`TargetFrame.lua:287-290` binds `debuff, debuffStack, debuffType` and then
-/// `SetTexture(debuff)`). Decision 1818, which also records why the Era shape was serving nobody.
+/// The 1.12 tuple, not a prefix of the Era one: `UnitBuff` returns `(texture, applications)`
+/// (`0x519500`) and `UnitDebuff` adds `dispelType` (`0x5198f0`), as stock `TargetFrame.lua:287-290`
+/// reads them.
 fn returns_1121(lua: &Lua, a: &AuraState, with_dispel_type: bool) -> mlua::Result<MultiValue> {
     let icon = match &a.icon {
         Some(t) => Value::String(lua.create_string(t)?),
@@ -221,10 +112,10 @@ fn returns_1121(lua: &Lua, a: &AuraState, with_dispel_type: bool) -> mlua::Resul
     Ok(MultiValue::from_vec(out))
 }
 
-/// Which return shape a getter wants — the two are not compatible, see [`returns_1121`].
+/// Which return tuple a getter pushes.
 #[derive(Clone, Copy)]
 enum Shape {
-    /// `UnitAura`'s ten values. Era-only: the name does not exist in 1.12 FrameXML at all.
+    /// `UnitAura`'s ten values, the Era signature.
     Era,
     /// `UnitBuff`'s two.
     Buff,
@@ -246,16 +137,15 @@ fn returns(lua: &Lua, a: &AuraState) -> mlua::Result<MultiValue> {
         s(&a.debuff_type)?,
         Value::Number(a.duration),
         Value::Number(a.expiration_time),
-        Value::Nil, // source — no aura caster exists on the 1.12 wire, for any unit (0257 B10)
-        Value::Nil, // isStealable — Spellsteal is TBC
+        Value::Nil, // source: the 1.12 wire carries no aura caster
+        Value::Nil, // isStealable: Spellsteal is TBC
         Value::Nil, // nameplateShowPersonal
         Value::Integer(i64::from(a.spell_id)),
     ]))
 }
 
-/// The shared body of `UnitAura`/`UnitBuff`/`UnitDebuff`: take the `index`-th (1-based) aura of
-/// `unit` that passes `filter`, in the order the app pushed them. Out of range → a bare nil, the
-/// live API's "no more auras" terminator that every `for i = 1, N` loop breaks on.
+/// The `index`-th (1-based) aura of `token` passing `filter`, in pushed order; out of range is a
+/// bare nil, the loop terminator.
 fn nth_aura(
     lua: &Lua,
     token: &Option<String>,
@@ -289,9 +179,8 @@ fn nth_aura(
 }
 
 impl super::UiScript {
-    /// Push (or clear) a unit token's aura list, **in display order** — the app decides that order
-    /// (decision 0257): the maintained insertion-order cache for the local player, ascending aura
-    /// slot for anyone else. `None` (or an empty list) makes every `UnitAura(token, i)` return nil.
+    /// Push or clear a token's aura list, in display order: cache order for the player, ascending
+    /// aura slot for anyone else.
     pub fn set_auras(&mut self, token: &str, auras: Option<Vec<AuraState>>) {
         let mut model = self.model_mut();
         match auras {
@@ -304,28 +193,24 @@ impl super::UiScript {
         }
     }
 
-    /// Push (or clear) the player's active tracking aura ([`TrackingState`] doc) — the app's aura
-    /// feed derives it from the same walk that excludes tracking spells from the display lists.
+    /// Push or clear the player's active [`TrackingState`].
     pub fn set_tracking(&mut self, tracking: Option<TrackingState>) {
         self.model_mut().tracking = tracking;
     }
 
-    /// Drain the spell ids `CancelUnitBuff` queued since the last call — the app sends one
-    /// `CMSG_CANCEL_AURA` per id (the server cancels by spell, never by slot; decision 0257 B8).
+    /// Drain the queued cancels, one `CMSG_CANCEL_AURA` per spell id: the server cancels by spell,
+    /// never by slot.
     pub fn take_cancel_aura_requests(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().cancel_aura_requests)
     }
 }
 
-/// Register `UnitAura`, `UnitBuff`, `UnitDebuff` and `CancelUnitBuff`, plus the 1.12 `GetPlayerBuff*`
-/// family ([`player_buff`]).
+/// Register the aura and tracking globals, the `GetPlayerBuff` family from [`player_buff`].
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // UnitAura(unit, index [, filter]) — filter defaults to HELPFUL, like the live API. This one
-    // keeps the Era tuple: it is not a 1.12 verb at all (zero occurrences in the reference's
-    // FrameXML) and has zero call sites in the 110-addon corpus, so it costs nothing and stays the
-    // Era-compat surface 0068 asked for.
+    // UnitAura(unit, index [, filter]), filter defaulting to HELPFUL, with the Era tuple: not a
+    // 1.12 verb.
     g.set(
         "UnitAura",
         lua.create_function(
@@ -341,18 +226,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?,
     )?;
 
-    // UnitBuff(unit, index [, raidFilter]) / UnitDebuff(unit, index [, raidFilter]) — the 1.12
-    // signature and the 1.12 RETURN SHAPE (decision 1818). The sign is fixed by the verb, not by a
-    // filter word: `0x519500` reads aura slots 0..31 and `0x5198f0` reads 32..47.
-    //
-    // **The third argument is a `raidFilter` flag, not Era's filter string.** Non-zero enables ONE
-    // extra per-slot predicate — castable-by-me for buffs (`0x4b3870`), dispellable-by-me for
-    // debuffs (`0x4b3920`). We accept it and DO NOT apply it, because [`AuraState`] holds neither
-    // fact and neither is derivable from the aura feed: castable-by-me needs the player's spellbook,
-    // dispellable-by-me needs a class→dispel-type table joined to `debuff_type`. Inventing an answer
-    // is the guess 1203 exists to prevent, so the flag is parked here in the open. Visible
-    // consequence, so nobody has to rediscover it: the pet frame's buff row and the
-    // dispellable-debuff rows show everything rather than only what the player can cast or dispel.
+    // UnitBuff(unit, index [, raidFilter]) and UnitDebuff: the verb fixes the sign, `0x519500`
+    // reading aura slots 0..31 and `0x5198f0` slots 32..47. A non-zero `raidFilter` keeps only
+    // buffs the player can cast (`0x4b3870`) or debuffs they can dispel (`0x4b3920`); it is
+    // accepted, not applied, as `AuraState` holds neither fact, so the pet frame's buff row and the
+    // dispellable-debuff rows show every aura.
     g.set(
         "UnitBuff",
         lua.create_function(
@@ -382,11 +260,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?,
     )?;
 
-    // CancelUnitBuff(unit, index [, filter]) — the Era name for the reference's
-    // `CancelPlayerBuff(buffIndex)`. Resolves the aura the same way the getters do, then queues its
-    // SPELL ID for the app: the server's `CMSG_CANCEL_AURA` carries a spell, not a slot, and refuses
-    // anything not cancelable. A non-cancelable aura (or a missing one) is a silent no-op, as in the
-    // reference, where the client's own `AFLAG_CANCELABLE` gate never sends the packet.
+    // CancelUnitBuff(unit, index [, filter]): not a 1.12 verb, the Era name for the reference's
+    // `CancelPlayerBuff`. It queues the aura's spell id, what `CMSG_CANCEL_AURA` carries; an aura
+    // the gate refuses is a silent no-op, as in the reference.
     g.set(
         "CancelUnitBuff",
         lua.create_function(
@@ -420,9 +296,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 
     player_buff::install(lua)?;
 
-    // GetTrackingTexture() — the reference's `0x4e4a20`: the icon path of the active tracking
-    // spell (the tracking global's occupant), or nil when none — `MiniMapTrackingFrame`'s
-    // show/hide + SetTexture driver on PLAYER_AURAS_CHANGED (ref-Minimap.xml l.150-159).
+    // GetTrackingTexture() (`0x4e4a20`): the tracking spell's icon or nil, which shows or hides
+    // the stock `MiniMapTrackingFrame` (`Minimap.xml:150-159`).
     g.set(
         "GetTrackingTexture",
         lua.create_function(|lua, ()| {
@@ -431,10 +306,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CancelTrackingBuff() — the reference's `0x4e4a80` (the tracking frame's right-click): cancel
-    // the active tracking aura by SPELL id through the same `CMSG_CANCEL_AURA` queue as
-    // `CancelUnitBuff`, behind the same client-side `AFLAG_CANCELABLE` gate. No tracking active
-    // is a silent no-op.
+    // CancelTrackingBuff() (`0x4e4a80`), the tracking frame's right-click: queues the tracking
+    // spell's id behind its `AFLAG_CANCELABLE`; with no tracking it is a no-op.
     g.set(
         "CancelTrackingBuff",
         lua.create_function(|lua, ()| {
@@ -470,8 +343,6 @@ mod tests {
         }
     }
 
-    /// The list the app pushes IS the enumeration order — the binding never re-sorts it. This is the
-    /// contract decision 0257 rests on: the player's insertion-ordered cache survives the seam.
     #[test]
     fn unit_aura_enumerates_the_pushed_order_not_the_spell_id_order() {
         let mut s = UiScript::new().unwrap();
@@ -483,14 +354,12 @@ mod tests {
                 aura(589, "Shadow Word: Pain", false, false),
             ]),
         );
-        // Buffs, in the pushed order (not ascending spell id).
         assert_eq!(
             s.eval::<String>(r#"return (UnitAura("player", 1))"#)
                 .unwrap(),
             "Battle Stance"
         );
-        // `UnitBuff`/`UnitDebuff` enumerate the same list, but their first return is the ICON, not
-        // the name (1.12's shape — decision 1818), so they are addressed by it here.
+        // `UnitBuff` and `UnitDebuff` return the icon first, the 1.12 shape.
         assert_eq!(
             s.eval::<String>(r#"return (UnitBuff("player", 2))"#)
                 .unwrap(),
@@ -502,14 +371,12 @@ mod tests {
                 .unwrap(),
             "Interface\\Icons\\Spell_589"
         );
-        // Past the end → nil, the loop terminator.
         assert!(s
             .eval::<bool>(r#"return UnitBuff("player", 3) == nil"#)
             .unwrap());
         assert!(s
             .eval::<bool>(r#"return UnitDebuff("player", 2) == nil"#)
             .unwrap());
-        // An unknown token, and a zero/negative index, are the same "no aura" shape.
         assert!(s
             .eval::<bool>(r#"return UnitAura("target", 1) == nil"#)
             .unwrap());
@@ -525,11 +392,11 @@ mod tests {
             "player",
             Some(vec![
                 aura(2457, "Battle Stance", true, true),
-                aura(9999, "Sealed", true, false), // helpful but not cancelable
+                aura(9999, "Sealed", true, false), // helpful, not cancelable
                 aura(589, "Pain", false, false),
             ]),
         );
-        // No filter ⇒ HELPFUL: two hits, the debuff invisible.
+        // No filter means HELPFUL.
         assert_eq!(
             s.eval::<i64>(
                 r#"local n = 0 for i=1,10 do if UnitAura("player", i) then n = n + 1 end end return n"#
@@ -537,13 +404,11 @@ mod tests {
             .unwrap(),
             2
         );
-        // HARMFUL names the sign explicitly.
         assert_eq!(
             s.eval::<String>(r#"return (UnitAura("player", 1, "HARMFUL"))"#)
                 .unwrap(),
             "Pain"
         );
-        // CANCELABLE / NOT_CANCELABLE partition the helpful set.
         assert_eq!(
             s.eval::<String>(r#"return (UnitAura("player", 1, "HELPFUL|CANCELABLE"))"#)
                 .unwrap(),
@@ -554,7 +419,7 @@ mod tests {
                 .unwrap(),
             "Sealed"
         );
-        // A bare CANCELABLE still means helpful (the sign defaults, it isn't cleared).
+        // A bare CANCELABLE keeps the helpful default.
         assert_eq!(
             s.eval::<String>(r#"return (UnitAura("player", 1, "CANCELABLE"))"#)
                 .unwrap(),
@@ -586,11 +451,6 @@ mod tests {
         assert_eq!(spell, 589);
     }
 
-    /// The **1.12** shape, which is not a prefix of the Era one: `UnitBuff` → `(texture,
-    /// applications)`, `UnitDebuff` → `(texture, applications, dispelType)`, and the FIRST value is
-    /// the texture. Decision 1818; `0x519500`/`0x5198f0`. The
-    /// reference's own FrameXML reads exactly this (`TargetFrame.lua:287-290`), and so does every
-    /// one of the 184 call sites in the addon corpus.
     #[test]
     fn unit_buff_and_unit_debuff_return_the_1121_tuple_not_the_era_one() {
         let mut s = UiScript::new().unwrap();
@@ -601,7 +461,6 @@ mod tests {
         debuff.debuff_type = Some("Magic".into());
         s.set_auras("target", Some(vec![buff, debuff]));
 
-        // UnitBuff returns exactly TWO values, texture first.
         let (icon, count, third) = s
             .eval::<(String, i64, Option<String>)>(
                 r#"local a, b, c = UnitBuff("target", 1) return a, b, c"#,
@@ -611,7 +470,6 @@ mod tests {
         assert_eq!(count, 1);
         assert_eq!(third, None, "UnitBuff returns two values, never a third");
 
-        // UnitDebuff returns THREE, the dispel type last.
         let (icon, count, dispel, fourth) = s
             .eval::<(String, i64, String, Option<String>)>(
                 r#"local a, b, c, d = UnitDebuff("target", 1) return a, b, c, d"#,
@@ -624,8 +482,7 @@ mod tests {
             "UnitDebuff returns three values, never a fourth"
         );
 
-        // The reference's own read, verbatim from TargetFrame.lua:287-297 — the comparison that
-        // raised `attempt to compare number with string` while we returned the Era tuple.
+        // Stock `TargetFrame.lua:287-297`'s read, verbatim.
         assert!(s
             .eval::<bool>(
                 r#"local d, stack, dtype = UnitDebuff("target", 1)
@@ -633,8 +490,7 @@ mod tests {
             )
             .unwrap());
 
-        // The raidFilter argument is ACCEPTED and its predicate is not applied (1818): passing it
-        // must not error, and must not change the answer.
+        // The raidFilter flag is accepted and not applied.
         assert_eq!(
             s.eval::<String>(r#"return (UnitDebuff("target", 1, 1))"#)
                 .unwrap(),
@@ -655,24 +511,17 @@ mod tests {
         );
         assert!(s.take_cancel_aura_requests().is_empty());
 
-        // A cancelable buff queues its SPELL id (not its index).
+        // Only the cancelable buff queues, by spell id; the others are silent no-ops.
         s.eval::<()>(r#"CancelUnitBuff("player", 1)"#).unwrap();
-        // A non-cancelable one is a silent no-op, as in the reference.
         s.eval::<()>(r#"CancelUnitBuff("player", 2)"#).unwrap();
-        // So is an out-of-range index, and a debuff reached through the helpful filter.
         s.eval::<()>(r#"CancelUnitBuff("player", 9)"#).unwrap();
         assert_eq!(s.take_cancel_aura_requests(), vec![2457]);
         assert!(s.take_cancel_aura_requests().is_empty());
     }
 
-    /// The tracking seam (the reference's `GetTrackingTexture`/`CancelTrackingBuff` pair over the
-    /// tracking global): the pushed state is what the bindings read, the cancel queues the SPELL
-    /// id behind the same `AFLAG_CANCELABLE` gate as `CancelUnitBuff`, and no tracking is nil +
-    /// no-op.
     #[test]
     fn tracking_bindings_read_the_pushed_state_and_cancel_by_spell_id() {
         let mut s = UiScript::new().unwrap();
-        // No tracking pushed yet: nil texture, cancel is a silent no-op.
         assert!(s
             .eval::<bool>("return GetTrackingTexture() == nil")
             .unwrap());
@@ -692,7 +541,6 @@ mod tests {
         s.eval::<()>("CancelTrackingBuff()").unwrap();
         assert_eq!(s.take_cancel_aura_requests(), vec![2580]);
 
-        // A non-cancelable tracking aura refuses, exactly like CancelUnitBuff's gate.
         s.set_tracking(Some(TrackingState {
             spell_id: 2580,
             cancelable: false,
@@ -701,7 +549,6 @@ mod tests {
         s.eval::<()>("CancelTrackingBuff()").unwrap();
         assert!(s.take_cancel_aura_requests().is_empty());
 
-        // Cleared: back to nil (the minimap frame's hide branch).
         s.set_tracking(None);
         assert!(s
             .eval::<bool>("return GetTrackingTexture() == nil")
diff --git a/crates/benilla-ui/src/script/aura/player_buff.rs b/crates/benilla-ui/src/script/aura/player_buff.rs
index 062a8f9e..d41eaa73 100644
--- a/crates/benilla-ui/src/script/aura/player_buff.rs
+++ b/crates/benilla-ui/src/script/aura/player_buff.rs
@@ -1,33 +1,20 @@
-//! **The 1.12 dialect** of the aura API — `GetPlayerBuff` and the five verbs that consume the cache
-//! position it hands back, plus `CancelPlayerBuff`.
-//!
-//! The index law, the byte-verified signature table, and the traps each shape hides are in the
-//! parent module's header ([`super`]); this file is the implementation. Everything here reads the
-//! *same* `model.auras["player"]` list the Era verbs read — the player's list **is** the reference's
-//! `0xbc6040` insertion-ordered cache — so a "cache position" needs no structure of its own.
-//!
-//! The one thing that is genuinely not shared with [`super`] is the **filter**: see
-//! [`PlayerBuffFilter`] for why reusing the Era parser would be a silent bug rather than a tidy-up.
+//! The 1.12 aura verbs: `GetPlayerBuff`, which returns a cache position, and the five that take
+//! one. A position is a 0-based index into the pushed `"player"` list, which is the reference's
+//! insertion-ordered cache (`0xbc6040`).
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::{cancel_authorized, AuraState, Model};
 
-/// `GetPlayerBuff`'s filter, as a **bitmask** — deliberately *not* [`Filter`].
-///
-/// The two parsers are not the same function and sharing one would be the silent-shape bug this
-/// module's header is about. `UnitAura`'s filter defaults its *sign* to helpful and treats a bare
-/// `"CANCELABLE"` as `HELPFUL|CANCELABLE`; `GetPlayerBuff`'s mask starts at **zero** the moment a
-/// filter string is supplied (`xor esi,esi`, `0x4e4639`), so a bare `"CANCELABLE"` sets no sign bit
-/// and matches nothing at all. And with **no** filter argument the mask is `HELPFUL|HARMFUL`
-/// (`mov esi,0x3`, `0x4e4618`), where `UnitAura`'s default is helpful only.
+/// `GetPlayerBuff`'s filter mask, not `UnitAura`'s parser: no filter argument means
+/// `HELPFUL|HARMFUL` (`0x4e4618`), and a filter string starts the mask at zero (`0x4e4639`), so a
+/// bare `"CANCELABLE"` matches nothing.
 #[derive(Clone, Copy)]
 struct PlayerBuffFilter(u32);
 
 impl PlayerBuffFilter {
-    /// `stricmp` against the four `.rdata` tokens (`0x4e4661`-`0x4e46cf`). Anything else — including
-    /// `"PASSIVE"` — contributes no bit, exactly as the reference's `strtok`/`stricmp` chain falls
-    /// through. Delimiters are `" |"` (`0x84bc3c`): space or pipe, runs collapsed like `strtok`'s.
+    /// Case-insensitive match against the four tokens (`0x4e4661`-`0x4e46cf`); anything else,
+    /// `"PASSIVE"` included, sets no bit. Space and pipe both delimit, runs collapsed (`0x84bc3c`).
     fn parse(spec: Option<&str>) -> Self {
         const HELPFUL: u32 = 0x1;
         const HARMFUL: u32 = 0x2;
@@ -35,7 +22,6 @@ impl PlayerBuffFilter {
         const NOT_CANCELABLE: u32 = 0x20;
 
         let Some(spec) = spec else {
-            // No filter argument at all: the preloaded `HELPFUL|HARMFUL`, both halves.
             return Self(HELPFUL | HARMFUL);
         };
         let mut mask = 0;
@@ -54,8 +40,8 @@ impl PlayerBuffFilter {
         Self(mask)
     }
 
-    /// The enumerator's per-record test (`0x4e43c9`-`0x4e43f7`): the sign bit for this record's half
-    /// must be set, then `CANCELABLE`/`NOT_CANCELABLE` (if named) must agree with `record+0xa & 1`.
+    /// The enumerator's per-record test (`0x4e43c9`-`0x4e43f7`): the record's sign bit, then any
+    /// named `CANCELABLE`/`NOT_CANCELABLE` against `record+0xa & 1`.
     fn matches(self, a: &AuraState) -> bool {
         const HELPFUL: u32 = 0x1;
         const HARMFUL: u32 = 0x2;
@@ -69,47 +55,29 @@ impl PlayerBuffFilter {
     }
 }
 
-/// `lua_isnumber`-then-`lua_tonumber`-then-`__ftol`, with the reference's own usage message.
-///
-/// Every verb in the family opens with exactly this (`0x4e45d6`, `0x4e4748`, `0x4e4808`, `0x4e48bc`,
-/// `0x4e493e`, `0x4e49a8`): a non-number argument raises through `luaL_error` (`0x6f4940` =
-/// `luaL_where` + `lua_pushvfstring` + `lua_concat` + `lua_error`) rather than returning nil, so an
-/// addon sees the same "Usage:" line the reference prints. Lua 5.1's `lua_isnumber` accepts a numeric
-/// *string*, and [`Lua::coerce_number`] is that same coercion.
+/// The family's index argument, as every verb opens (`0x4e45d6`, `0x4e4748`, `0x4e4808`,
+/// `0x4e48bc`, `0x4e493e`, `0x4e49a8`): a number or numeric string, truncated; anything else raises
+/// the reference's usage line through `luaL_error` (`0x6f4940`).
 fn buff_index_arg(lua: &Lua, v: Value, usage: &'static str) -> mlua::Result<i64> {
     match lua.coerce_number(v)? {
-        // `__ftol` truncates toward zero; `as i64` on f64 does the same (and saturates).
+        // `__ftol` truncates toward zero, as `as i64` does.
         Some(n) => Ok(n as i64),
         None => Err(mlua::Error::RuntimeError(usage.into())),
     }
 }
 
-/// The player's display cache — the reference's `0xbc6040`, which for us **is** the pushed
-/// `"player"` list (decision 0257; `benilla::ui_aura` maintains the insertion order across frames).
-/// `pos` is a physical cache position, 0-based.
-///
-/// Out of range is `None`, covering both of the reference's miss shapes: `0x4e4430` hands back NULL
-/// for `pos < 0` and `pos >= 0x30`, and a position inside the array but past the packed prefix
-/// resolves to a **cleared** record (`slot = -1`, `spellId = 0`), which every sibling then treats as
-/// absent anyway — `GetPlayerBuffTexture` fails its `Spell.dbc` lookup on id 0 and pushes nil,
-/// `…TimeLeft` returns 0 on `slot < 0`, `CancelPlayerBuff` finds no spell and no-ops. (One reference
-/// quirk is deliberately *not* reproduced: `GetPlayerBuffApplications` on a cleared record reads
-/// `+0x9`, which `BuildBuffRecord` never rewrites when it clears — so the real client hands back the
-/// previous occupant's stack count. It is unreachable from any guarded call site, and stale memory is
-/// not a mechanism worth mirroring; we answer with the absent-record default, `1`.)
+/// The record at cache position `pos`, or `None` past the packed prefix, where the reference has
+/// NULL outside `0..0x30` (`0x4e4430`) and cleared records its siblings treat as absent. Deviation:
+/// `GetPlayerBuffApplications` answers 1 for a cleared record where the reference reads its stale
+/// `+0x9`, the previous occupant's count, because no guarded caller reaches it.
 fn player_buff_record(lua: &Lua, pos: i64) -> Option<AuraState> {
     let pos = usize::try_from(pos).ok()?;
     let model = lua.app_data_ref::<Model>().expect("model app_data");
     model.auras.get("player")?.get(pos).cloned()
 }
 
-/// The enumerator, `0x4e43b0`: walk the cache by ascending physical position, counting only records
-/// that pass `filter`, and stop when that count reaches `index`. Returns the **position** and the
-/// record — the position is what every sibling verb consumes.
-///
-/// A negative `index` can never match: the reference's counter starts at 0 and only increments, and
-/// the hit test is an equality (`cmp ebx,[ebp-4]; je`), so it walks the whole cache and falls out
-/// with `*outPos` still at its pre-seeded `-1`.
+/// The enumerator (`0x4e43b0`): the `index`-th record passing `filter`, by ascending position,
+/// with that position. A negative `index` never matches the counter, which counts up from 0.
 fn enumerate_player_buff(
     lua: &Lua,
     index: i64,
@@ -129,19 +97,16 @@ fn enumerate_player_buff(
         .map(|(pos, a)| (pos, a.clone()))
 }
 
-/// Register the six 1.12 globals. Signatures are byte-verified — see [`super`]'s header table for
-/// the addresses and the corpus/FrameXML site that pins each shape.
+/// Register the six 1.12 globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetPlayerBuff(index [, "filter"]) — 0x4e45d0. ALWAYS two numbers: the physical cache position
-    // (-1 past the end) and untilCancelled (0/1). Never nil, never a different arity: both the hit
-    // path (0x4e471e) and the miss path (0x4e4733) end `mov eax,0x2`.
-    //
-    // With the default HELPFUL|HARMFUL mask every live record passes the sign test, so the match
-    // counter advances in lockstep with the position and `GetPlayerBuff(i)` returns exactly `i` over
-    // the packed prefix — which `_LazyPig/LazyPig.lua:1174-1181` relies on, enumerating with
-    // `counter` and then cancelling `counter` rather than the returned index.
+    // GetPlayerBuff(index [, "filter"]) (`0x4e45d0`) returns two numbers on both paths
+    // (`0x4e471e`, `0x4e4733`): the position, -1 past the end and never nil, as addons loop while
+    // it is `>= 0`; and untilCancelled as the number 0 or 1, which stock `BuffFrame.lua:124`
+    // compares with `1`. The index is 0-based, used without `UnitBuff`'s `dec` (`0x4e460a`,
+    // `0x519579`). Unfiltered, every record passes, so `GetPlayerBuff(i)` is `i`, which addons use
+    // to cancel by the counter.
     g.set(
         "GetPlayerBuff",
         lua.create_function(|lua, (index, filter): (Value, Option<String>)| {
@@ -158,14 +123,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPlayerBuffTexture(buffIndex) — 0x4e4740. One value: the icon path, or nil when the position
-    // is absent or the spell/icon row is missing (three separate `lua_pushnil; mov eax,0x1` exits).
-    // Nil is load-bearing: `SnaFu/SnaFu.lua:317` uses this call *as its loop condition*
-    // (`while GetPlayerBuffTexture(i) do`), so an empty string past the end would spin forever.
-    //
-    // The extra argument `CT_BuffMod/CT_BuffFrame.lua:148` passes
-    // (`GetPlayerBuffTexture(buffIndex, "HELPFUL|HARMFUL")`) is simply ignored — the reference reads
-    // argument 1 and nothing else, and mlua drops the surplus for the same reason.
+    // GetPlayerBuffTexture(buffIndex) (`0x4e4740`): the icon path, or nil for an absent position or
+    // a missing spell or icon row; addons loop until the nil. A surplus argument is ignored, as the
+    // reference reads only the first.
     g.set(
         "GetPlayerBuffTexture",
         lua.create_function(|lua, index: Value| {
@@ -174,17 +134,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPlayerBuffDispelType(buffIndex) — 0x4e4800. One value: SpellDispelType.dbc's name for the
-    // spell's `Dispel` column, or nil (dispel id 0, or any missing row — gated at 0x4e485e before
-    // the DBC is touched). The vocabulary is the DBC's, shared with `UnitDebuff`'s third return.
-    //
-    // Nil, never `""` and never `"none"`: the corpus indexes `DebuffTypeColor[debuffType]` behind an
-    // `if ( debuffType )` and falls back to the `"none"` key itself
-    // (`ElkBuffBar/ElkBuffBar.lua:324-329`, `CT_BuffMod/CT_BuffFrame.lua:137-142`). An empty string
-    // is truthy in Lua, so it would take the wrong branch and then index a nil colour.
-    //
-    // It must also tolerate `-1` directly: `ref-BuffFrame.lua:83` calls
-    // `GetPlayerBuffDispelType(GetPlayerBuff(this:GetID(), "HARMFUL"))` with no guard between them.
+    // GetPlayerBuffDispelType(buffIndex) (`0x4e4800`): the `SpellDispelType.dbc` name of the
+    // spell's `Dispel`, or nil for dispel 0 or a missing row (`0x4e485e`); never `""`, which Lua
+    // takes as true. Stock `BuffFrame.lua:83` passes it `GetPlayerBuff`'s result unguarded, -1 too.
     g.set(
         "GetPlayerBuffDispelType",
         lua.create_function(|lua, index: Value| {
@@ -193,15 +145,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPlayerBuffApplications(buffIndex) — 0x4e48b0. One value, always a number: the record's
-    // stack count, and **1** for an absent position (`push 0x3ff00000; push 0x0` = the double 1.0,
-    // 0x4e4917). Never nil — `CT_BuffMod/CT_BuffFrame.lua:216` and `ElkBuffBar/ElkBuffBar.lua:278`
-    // both do `if ( count > 1 )` with no guard, which nil turns into a hard error.
-    //
-    // (The reference's usage string here is `0x84bcc0`, "Usage: GetPlayerBuffTimeLeft(buffIndex)" —
-    // the same constant 0x4e4930 pushes. A copy-paste in the shipped binary; we name the verb the
-    // caller actually called, since nothing can depend on the wrong name and a debugging addon
-    // author would be misled by it.)
+    // GetPlayerBuffApplications(buffIndex) (`0x4e48b0`): the stack count, and 1 for an absent
+    // position (`0x4e4917`), never nil, as addons test `count > 1` unguarded. Deviation: the
+    // reference's usage line names `GetPlayerBuffTimeLeft` (`0x84bcc0`, shared with `0x4e4930`);
+    // ours names this verb, because nothing can depend on the wrong name.
     g.set(
         "GetPlayerBuffApplications",
         lua.create_function(|lua, index: Value| {
@@ -210,36 +157,23 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPlayerBuffTimeLeft(buffIndex) — 0x4e4930 over the reader 0x4e4450. One value, always a
-    // number in **seconds** (the reader returns ms and 0x4e4986 multiplies by the 0.001 at
-    // 0x801608): `max(0, expiry - now)`, and **0** for an absent position, a cleared record, or an
-    // aura with no expiry at all.
-    //
-    // Never nil: `oRA2/Participant/Buff.lua:286` computes `floor(GetPlayerBuffTimeLeft(index) + .5)`
-    // with no guard whatsoever, and `PowerAuras/PowerAuras.lua:593` feeds the result of a *possibly
-    // -1* `GetPlayerBuff` straight in and then compares `> 0`.
-    //
-    // The clock is the VM's own `GetTime()` session clock, the same one `expiration_time` is
-    // expressed on (decision 0257) — so this is a live subtraction per call, exactly as
-    // `ref-BuffFrame.lua:130` re-reads it every frame from `OnUpdate` rather than caching it on the
-    // event.
+    // GetPlayerBuffTimeLeft(buffIndex) (`0x4e4930`, reader `0x4e4450`): seconds, the reader's ms
+    // times the 0.001 at `0x801608` (`0x4e4986`), as `max(0, expiry - now)`, and 0 for an absent,
+    // cleared or permanent aura, never nil, as addons do arithmetic on it unguarded. It is computed
+    // per call against `GetTime()`, as stock `BuffFrame.lua:130` re-reads it every frame.
     g.set(
         "GetPlayerBuffTimeLeft",
         lua.create_function(|lua, index: Value| {
             let pos = buff_index_arg(lua, index, "Usage: GetPlayerBuffTimeLeft(buffIndex)")?;
             let now: f64 = lua.globals().get("__benilla_now").unwrap_or(0.0);
-            // The `max(0, …)` covers both of the reference's zero cases at once: an expired aura,
-            // and a permanent one, whose expiry array slot holds 0 so that `now - 0` is positive.
+            // `max(0, …)` covers both zero cases: an expired aura, and a permanent one, expiry 0.
             Ok(player_buff_record(lua, pos).map_or(0.0, |a| (a.expiration_time - now).max(0.0)))
         })?,
     )?;
 
-    // CancelPlayerBuff(buffIndex) — 0x4e49a0. **Zero** return values on every path, including the
-    // successful one (`xor eax,eax; ret`). Resolves the position to a record, applies
-    // [`cancel_authorized`], and queues the SPELL id onto the same drain `CancelUnitBuff` uses —
-    // there is one queue because there is one packet: `Spell_C::CancelAura 0x6e7040` sends
-    // `CMSG_CANCEL_AURA` (0x136) with a single u32 spell id (decision 0257 B8). A refused or absent
-    // aura is a silent no-op, as in the reference.
+    // CancelPlayerBuff(buffIndex) (`0x4e49a0`): no return values on any path. It queues the spell
+    // id, the one `u32` of `CMSG_CANCEL_AURA` (0x136, `Spell_C::CancelAura` `0x6e7040`), on the
+    // queue `CancelUnitBuff` uses; a refused or absent aura is a silent no-op.
     g.set(
         "CancelPlayerBuff",
         lua.create_function(|lua, index: Value| {
@@ -259,8 +193,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 mod tests {
     use crate::script::{AuraState, UiScript};
 
-    /// A plain aura as the app's feed would push it. Local to this module's fixtures: the 1.12
-    /// verbs read fields (`until_cancelled`, `channeled`) the Era tests have no use for.
     fn aura(spell_id: u32, name: &str, helpful: bool, cancelable: bool) -> AuraState {
         AuraState {
             spell_id,
@@ -277,14 +209,13 @@ mod tests {
         }
     }
 
-    /// The player's cache as the app pushes it: buffs and debuffs in ONE insertion-ordered list,
-    /// which is what makes a cache position an absolute handle across filters.
+    /// The player's cache as the app pushes it: buffs and debuffs in one insertion-ordered list.
     fn player_cache() -> Vec<AuraState> {
         let mut mark = aura(1126, "Mark of the Wild", true, true);
         mark.count = 1;
         mark.expiration_time = 100.0;
         let mut stance = aura(2457, "Battle Stance", true, false);
-        stance.until_cancelled = true; // permanent: no SpellDuration row to count down
+        stance.until_cancelled = true; // permanent
         let mut pain = aura(589, "Shadow Word: Pain", false, false);
         pain.count = 3;
         pain.debuff_type = Some("Magic".into());
@@ -299,14 +230,7 @@ mod tests {
         s
     }
 
-    /// **The sentinel, and the arity that carries it.** `GetPlayerBuff` returns two numbers on every
-    /// path — `(-1, 0)` past the end, never nil and never a different count.
-    ///
-    /// The arity assertions are the half that matters, exactly as in
-    /// [`super::super::item_stats`]'s `get_item_info_tests`: an implementation that returned `nil`
-    /// for a miss still "works" for every individual read, and only the arity notices. Here it is
-    /// worse than cosmetic — the corpus's termination test is `>= 0` on the *first* value, so nil is
-    /// `attempt to compare nil with number` and zero returns is the same crash.
+    /// The arity is the point: a nil miss passes each single read but breaks every `>= 0` loop.
     #[test]
     fn get_player_buff_returns_two_numbers_and_minus_one_past_the_end() {
         let mut s = with_player_cache();
@@ -323,12 +247,11 @@ mod tests {
             "and a MISS pushes two as well (0x4e4733), not zero and not nil"
         );
 
-        // 0-based: position 0 is the first aura, not the second.
+        // 0-based: position 0 is the first aura.
         assert_eq!(
             s.eval::<(i64, i64)>("return GetPlayerBuff(0)").unwrap(),
             (0, 0)
         );
-        // Past the end: the -1 sentinel, and untilCancelled 0 beside it.
         assert_eq!(
             s.eval::<(i64, i64)>("return GetPlayerBuff(3)").unwrap(),
             (-1, 0)
@@ -337,20 +260,17 @@ mod tests {
             s.eval::<(i64, i64)>("return GetPlayerBuff(99)").unwrap(),
             (-1, 0)
         );
-        // A negative index can never match the counter, so it is a miss, not an error.
         assert_eq!(
             s.eval::<(i64, i64)>("return GetPlayerBuff(-1)").unwrap(),
             (-1, 0)
         );
-        // untilCancelled is the NUMBER 1 — five corpus sites compare it to `1`, so a boolean
-        // (`true ~= 1`) would silently invert every one of them.
+        // untilCancelled is the number 1, not `true`: callers compare it with `1`.
         assert!(s
             .eval::<bool>("local _, uc = GetPlayerBuff(1) return uc == 1")
             .unwrap());
         assert!(s
             .eval::<bool>("local _, uc = GetPlayerBuff(0) return uc == 0")
             .unwrap());
-        // An empty cache is the same miss shape as an over-long index (not an error, not nil).
         s.set_auras("player", None);
         assert_eq!(
             s.eval::<(i64, i64)>("return GetPlayerBuff(0)").unwrap(),
@@ -358,15 +278,8 @@ mod tests {
         );
     }
 
-    /// **The corpus's own loop.** `while GetPlayerBuff(counter) >= 0 do … end` over a real cache
-    /// must visit every aura once and then *stop* — `_LazyPig/LazyPig.lua:1174`,
-    /// `Zorlen/Zorlen.lua:2797`. Not terminating is the failure mode that matters: it is an infinite
-    /// loop inside a `PLAYER_AURAS_CHANGED` handler, i.e. a frozen client, and no gate but this one
-    /// would see it.
-    ///
-    /// The loop also pins LazyPig's assumption that `counter` and the returned index are
-    /// interchangeable under the default filter, and that the walk covers **debuffs too** (the
-    /// `HELPFUL|HARMFUL` default).
+    /// The corpus's loop (`_LazyPig/LazyPig.lua:1174`) visits every aura, debuffs included, and
+    /// ends: a hang there freezes the client inside a `PLAYER_AURAS_CHANGED` handler.
     #[test]
     fn the_corpus_while_ge_zero_loop_terminates_and_visits_every_aura() {
         let mut s = with_player_cache();
@@ -397,7 +310,6 @@ mod tests {
             "Interface\\Icons\\Spell_1126;Interface\\Icons\\Spell_2457;Interface\\Icons\\Spell_589;"
         );
 
-        // The same loop over an EMPTY cache terminates immediately rather than spinning.
         s.set_auras("player", Some(vec![]));
         assert_eq!(
             s.eval::<i64>(
@@ -410,32 +322,23 @@ mod tests {
         );
     }
 
-    /// **The default filter is `HELPFUL|HARMFUL`.** The trap that fails silently: under a `HELPFUL`
-    /// default (which is what `UnitAura` uses, one function away in this file)
-    /// `Zorlen/Zorlen.lua:2797-2801` — an unfiltered walk feeding `GetPlayerBuffDispelType` and
-    /// matching `"Poison"`/`"Disease"` — simply never finds anything, and nothing errors.
-    ///
-    /// Also pins the absolute index space: a `"HARMFUL"` enumeration hands back the same position an
-    /// unfiltered one does, which `CT_BuffMod/CT_BuffFrame.lua:73-79` compares for equality across
-    /// the two filters.
+    /// Under a `HELPFUL` default an unfiltered walk for `"Poison"` would find nothing, silently;
+    /// and a position is the same number under every filter, which callers compare.
     #[test]
     fn get_player_buff_defaults_to_both_halves_and_indexes_absolutely() {
         let s = with_player_cache();
 
-        // No filter: three matches — the debuff included.
         assert_eq!(
             s.eval::<i64>("local n = 0 while GetPlayerBuff(n) >= 0 do n = n + 1 end return n")
                 .unwrap(),
             3
         );
-        // The debuff is reachable unfiltered, and its dispel class comes back.
         assert_eq!(
             s.eval::<String>("return GetPlayerBuffDispelType(GetPlayerBuff(2))")
                 .unwrap(),
             "Magic"
         );
-        // "HARMFUL" alone finds it at ordinal 0 — and hands back position 2, the SAME number the
-        // unfiltered walk used.
+        // "HARMFUL" finds the debuff at ordinal 0 and returns position 2, the unfiltered number.
         assert_eq!(
             s.eval::<i64>(r#"return (GetPlayerBuff(0, "HARMFUL"))"#)
                 .unwrap(),
@@ -446,7 +349,6 @@ mod tests {
                 .unwrap(),
             -1
         );
-        // "HELPFUL" alone: two, at positions 0 and 1.
         assert_eq!(
             s.eval::<(i64, i64)>(
                 r#"return (GetPlayerBuff(0, "HELPFUL")), (GetPlayerBuff(1, "HELPFUL"))"#
@@ -454,7 +356,7 @@ mod tests {
             .unwrap(),
             (0, 1)
         );
-        // CT_BuffMod's own literal, and the space-delimited spelling the reference's strtok accepts.
+        // Pipe- and space-delimited.
         assert_eq!(
             s.eval::<i64>(r#"return (GetPlayerBuff(2, "HELPFUL|HARMFUL"))"#)
                 .unwrap(),
@@ -465,20 +367,18 @@ mod tests {
                 .unwrap(),
             2
         );
-        // The zero-mask rule: a filter STRING with no sign token matches nothing at all, because the
-        // mask starts at 0 (`xor esi,esi`) rather than defaulting the sign the way UnitAura's does.
+        // A filter string with no sign token matches nothing: the mask starts at 0.
         assert_eq!(
             s.eval::<i64>(r#"return (GetPlayerBuff(0, "CANCELABLE"))"#)
                 .unwrap(),
             -1
         );
-        // "PASSIVE" is not a token in this parser: it contributes no bit, so it is a zero mask too.
+        // "PASSIVE" is not a token.
         assert_eq!(
             s.eval::<i64>(r#"return (GetPlayerBuff(0, "PASSIVE"))"#)
                 .unwrap(),
             -1
         );
-        // CANCELABLE / NOT_CANCELABLE partition a named sign.
         assert_eq!(
             s.eval::<i64>(r#"return (GetPlayerBuff(0, "HELPFUL|CANCELABLE"))"#)
                 .unwrap(),
@@ -491,14 +391,12 @@ mod tests {
         );
     }
 
-    /// **The accessors' empty-slot answers**, each of which is a different shape, and each of which
-    /// a corpus site would crash on if it were nil.
     #[test]
     fn the_player_buff_accessors_answer_an_absent_position_without_nil_arithmetic() {
         let mut s = with_player_cache();
-        s.tick(0.0); // GetTime() = 0, the clock GetPlayerBuffTimeLeft counts against
+        s.tick(0.0); // GetTime() = 0
 
-        // Every accessor returns exactly ONE value, hit or miss — the reference's `mov eax,0x1`.
+        // One value, hit or miss.
         for verb in [
             "GetPlayerBuffTexture",
             "GetPlayerBuffDispelType",
@@ -513,13 +411,12 @@ mod tests {
                 );
             }
         }
-        // CancelPlayerBuff pushes NONE (`xor eax,eax; ret`), on every path.
         for arg in ["0", "-1", "99"] {
             assert_eq!(s.arity(&format!("CancelPlayerBuff({arg})")).unwrap(), 0);
         }
         s.take_cancel_aura_requests();
 
-        // Texture: nil past the end — SnaFu's `while GetPlayerBuffTexture(i) do` loop condition.
+        // Texture: nil past the end, a loop condition in the corpus.
         assert!(s
             .eval::<bool>("return GetPlayerBuffTexture(3) == nil")
             .unwrap());
@@ -536,21 +433,18 @@ mod tests {
             3
         );
 
-        // DispelType: nil, never "" and never "none" — the corpus branches on truthiness and then
-        // indexes DebuffTypeColor with the value, so "" would take the wrong branch.
+        // DispelType: nil, never "".
         assert!(s
             .eval::<bool>("return GetPlayerBuffDispelType(0) == nil")
             .unwrap());
         assert!(s
             .eval::<bool>("return GetPlayerBuffDispelType(99) == nil")
             .unwrap());
-        // ref-BuffFrame.lua:83 nests the calls with no guard, so -1 must pass straight through.
+        // Stock BuffFrame.lua:83 nests the calls unguarded.
         assert!(s
             .eval::<bool>(r#"return GetPlayerBuffDispelType(GetPlayerBuff(9, "HARMFUL")) == nil"#)
             .unwrap());
 
-        // Applications: a NUMBER always, and 1 (not 0, not nil) for an absent position — the
-        // reference's `push 0x3ff00000`. `count > 1` is unguarded in CT_BuffMod and ElkBuffBar.
         assert_eq!(
             s.eval::<i64>("return GetPlayerBuffApplications(2)")
                 .unwrap(),
@@ -570,8 +464,6 @@ mod tests {
             .eval::<bool>("return GetPlayerBuffApplications(-1) > 1 == false")
             .unwrap());
 
-        // TimeLeft: a NUMBER always, in seconds, 0 for absent/permanent — oRA2 does
-        // `floor(GetPlayerBuffTimeLeft(index) + .5)` with no guard at all.
         assert_eq!(
             s.eval::<f64>("return GetPlayerBuffTimeLeft(2)").unwrap(),
             18.0
@@ -589,7 +481,7 @@ mod tests {
             s.eval::<f64>("return GetPlayerBuffTimeLeft(-1)").unwrap(),
             0.0
         );
-        // The unguarded corpus arithmetic, run for real.
+        // The corpus's unguarded arithmetic.
         assert_eq!(
             s.eval::<f64>("return math.floor(GetPlayerBuffTimeLeft(-1) + .5)")
                 .unwrap(),
@@ -601,28 +493,26 @@ mod tests {
             0.0
         );
 
-        // It counts down against the VM's GetTime clock, live, per call.
+        // It counts down against GetTime, per call, and floors at 0.
         s.tick(5.0);
         assert_eq!(
             s.eval::<f64>("return GetPlayerBuffTimeLeft(2)").unwrap(),
             13.0
         );
-        // And floors at 0 rather than going negative once the aura is past its expiry.
         s.tick(20.0);
         assert_eq!(
             s.eval::<f64>("return GetPlayerBuffTimeLeft(2)").unwrap(),
             0.0
         );
 
-        // A surplus argument is ignored, not an error — CT_BuffMod/CT_BuffFrame.lua:148 passes a
-        // filter string to GetPlayerBuffTexture, which takes none.
+        // A surplus argument is ignored.
         assert_eq!(
             s.eval::<String>(r#"return GetPlayerBuffTexture(0, "HELPFUL|HARMFUL")"#)
                 .unwrap(),
             "Interface\\Icons\\Spell_1126"
         );
 
-        // A non-number argument raises with the reference's own usage line, rather than answering.
+        // A non-number argument raises the reference's usage line.
         let err = s
             .eval::<()>("GetPlayerBuff({})")
             .expect_err("a table index must raise");
@@ -632,34 +522,27 @@ mod tests {
         );
     }
 
-    /// `CancelPlayerBuff` is `CancelUnitBuff` under its 1.12 name: the same gate, the same queue,
-    /// the same `CMSG_CANCEL_AURA` spell id — never a second mechanism. It differs only in how the
-    /// aura is addressed (a cache position, not a token plus a filtered ordinal).
     #[test]
     fn cancel_player_buff_shares_the_gate_and_the_queue_with_cancel_unit_buff() {
         let mut s = with_player_cache();
         assert!(s.take_cancel_aura_requests().is_empty());
 
-        // Position 0 is a cancelable buff: its SPELL id is queued, not its index.
+        // Position 0 is cancelable: its spell id queues.
         s.eval::<()>("CancelPlayerBuff(0)").unwrap();
         assert_eq!(s.take_cancel_aura_requests(), vec![1126]);
 
-        // Position 1 is a buff without AFLAG_CANCELABLE, position 2 a plain debuff, and 99/-1 are
-        // absent — all silent no-ops, exactly as the reference's gate falls through.
+        // Not cancelable, a plain debuff, absent: all silent no-ops.
         for arg in ["1", "2", "99", "-1"] {
             s.eval::<()>(&format!("CancelPlayerBuff({arg})")).unwrap();
         }
         assert!(s.take_cancel_aura_requests().is_empty());
 
-        // Both names reach the same queue for the same aura: CancelUnitBuff addresses it as the
-        // 1st helpful aura of "player", CancelPlayerBuff as cache position 0.
+        // Both names reach one queue: the first helpful aura is cache position 0.
         s.eval::<()>(r#"CancelUnitBuff("player", 1)"#).unwrap();
         s.eval::<()>("CancelPlayerBuff(0)").unwrap();
         assert_eq!(s.take_cancel_aura_requests(), vec![1126, 1126]);
 
-        // The channeled arm — the only way a NEGATIVE aura is cancelable (DBC AttributesEx & 0x4,
-        // 0x4e4a10). Without it the debuff below is refused, which is the shape CancelUnitBuff
-        // shipped with.
+        // The channeled arm (`AttributesEx & 0x4`, `0x4e4a10`) cancels a negative aura.
         let mut channeled = aura(689, "Drain Life", false, false);
         channeled.channeled = true;
         s.set_auras("player", Some(vec![channeled]));
diff --git a/crates/benilla-ui/src/script/backdrop.rs b/crates/benilla-ui/src/script/backdrop.rs
index 1183dc0c..41c94743 100644
--- a/crates/benilla-ui/src/script/backdrop.rs
+++ b/crates/benilla-ui/src/script/backdrop.rs
@@ -1,20 +1,13 @@
-//! The frame `Backdrop` mechanism — byte-faithful to the 1.12.1 client. A backdrop is the tiled
-//! bg + 8-piece border a `<Backdrop>` element or Lua `SetBackdrop`
-//! installs on a frame (the tooltip/dialog/panel plate). This module owns the **data** ([`Backdrop`])
-//! and the **geometry** ([`pieces`]); the Lua verbs live in [`super::object`] and the XML parse in
-//! [`crate::loader`]. The renderer is the app's job — [`pieces`] hands it screen-space quads with
-//! explicit per-corner UVs.
+//! The frame backdrop as the 1.12 client builds it: the tiled background and 8-piece border that a
+//! `<Backdrop>` element or `SetBackdrop` installs. This module owns the data ([`Backdrop`]) and the
+//! geometry ([`pieces`], screen-space quads with per-corner UVs); the app renders them.
 
 use crate::layout::Rect;
 
-/// The default `edgeSize`, **logical** px: the ctor writes device `DAT_0081c9b0 = 0.025`, which is
-/// logical 32 through the ×1/1024·0.8 logical→device transform (`+0x48`, and
-/// the usage string `edgeSize = 32`). Our layout is already in logical px, so we carry 32 directly.
+/// The default `edgeSize`, logical 32: the constructor writes device 0.025 (`DAT_0081c9b0`).
 pub const DEFAULT_EDGE_SIZE: f32 = 32.0;
 
-/// The `BackgroundInsets` — the bg texture is the frame rect inset by these (the border is *not*
-/// inset; it sits flush inside the frame rect). Default all 0 (`0x77e5f0`). Field order matches the
-/// struct offsets `+0x50 top / +0x54 bottom / +0x58 left / +0x5c right`.
+/// `BackgroundInsets`: the background's inset from the frame rect; the border is never inset.
 #[derive(Clone, Copy, Debug, Default, PartialEq)]
 pub struct Insets {
     pub left: f32,
@@ -23,37 +16,32 @@ pub struct Insets {
     pub bottom: f32,
 }
 
-/// A frame's installed backdrop (the 0x68-byte struct at `frame+0x1ac`). The
-/// field set is *exactly* what the compiled reader accepts — `bgFile, edgeFile, tile, tileSize,
-/// edgeSize, insets` — plus the two colors; no other keys exist in the compiled reader
-/// (`0x7776e0`). Colors default to opaque
-/// **white** (the ctor `+0x60/+0x64 = 0xffffffff`); the XML `<Color>`/`<BorderColor>` *parser*
-/// separately defaults a *present-but-partial* element to black, which the loader applies.
+/// A frame's installed backdrop (the 0x68-byte struct at `frame+0x1ac`): exactly the keys the
+/// reader accepts (`0x7776e0`) plus the two colours. The colours default to opaque white; the XML
+/// parser defaults a present but partial `<Color>` or `<BorderColor>` to black.
 #[derive(Clone, Debug, PartialEq)]
 pub struct Backdrop {
-    /// The tiled background texture (`+0x24`); `None`/empty ⇒ no bg piece.
+    /// The background texture (`+0x24`); none or empty draws no background.
     pub bg_file: Option<String>,
-    /// The 8-slice border texture (`+0x30`); `None`/empty ⇒ no border pieces.
+    /// The 8-slice border texture (`+0x30`); none or empty draws no border.
     pub edge_file: Option<String>,
-    /// `tile` (`+0x40`): tile the bg (else stretch it). Default false.
+    /// Tile the background, else stretch it (`+0x40`).
     pub tile: bool,
-    /// `tileSize` (`+0x4c`), logical px; `0.0` ⇒ use `edge_size` as the tile period (`0x77f0c0`).
-    /// Default 0.
+    /// `tileSize` in logical px (`+0x4c`); 0 tiles at `edge_size` (`0x77f0c0`).
     pub tile_size: f32,
-    /// `edgeSize` (`+0x48`), logical px — the border piece size and the edge tiling period. Default 32.
+    /// `edgeSize` in logical px (`+0x48`): the border piece size and the edge tiling period.
     pub edge_size: f32,
-    /// `BackgroundInsets` (`+0x50..0x5c`). Default 0.
+    /// `BackgroundInsets` (`+0x50..0x5c`).
     pub insets: Insets,
-    /// bg vertex color (`+0x60`, `SetBackdropColor`). Default opaque white.
+    /// The background's vertex colour (`+0x60`, `SetBackdropColor`).
     pub bg_color: [f32; 4],
-    /// border vertex color (`+0x64`, `SetBackdropBorderColor`; all 8 pieces, never the bg). Default white.
+    /// All 8 border pieces' vertex colour (`+0x64`, `SetBackdropBorderColor`).
     pub border_color: [f32; 4],
 }
 
 impl Default for Backdrop {
     fn default() -> Self {
-        // The ctor (`0x77e5f0`): files empty, tile 0, tileSize 0,
-        // edgeSize logical 32, insets 0, both colors 0xffffffff.
+        // The constructor (`0x77e5f0`).
         Self {
             bg_file: None,
             edge_file: None,
@@ -76,59 +64,39 @@ impl Backdrop {
     }
 }
 
-/// One drawable backdrop piece (the bg, or one of the 8 border pieces). Carries four explicit corner
-/// **positions** (not a rect) so the shipped BR-inset bug's slant is representable, plus four explicit
-/// per-corner **UVs** (the TOP/BOTTOM edges are rotated 90°, `0x77f0c0`). Both arrays are in
-/// `[top-left, top-right, bottom-right, bottom-left]` screen order (y-up, the layout convention).
+/// One drawable piece, the background or one of the 8 border pieces: explicit corners, not a rect,
+/// so the bottom-right inset quirk can slant it, and per-corner UVs, since the top and bottom edges
+/// are rotated 90° (`0x77f0c0`). Both arrays run `[TL, TR, BR, BL]`, y-up.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct BackdropPiece {
-    /// Corner positions in screen px, y-up: `[TL, TR, BR, BL]`.
+    /// Corner positions in screen px.
     pub corners: [[f32; 2]; 4],
-    /// Corner UVs (texture space), same `[TL, TR, BR, BL]` order.
+    /// Corner UVs in texture space.
     pub uvs: [[f32; 2]; 4],
-    /// The texture needs REPEAT (wrap) addressing — the edge strips run UVs `[0..N]` and a tiled bg
-    /// `[0..w/period]`. The corners' UVs stay in `[0,1]` but share the edge texture, so they carry
-    /// `true` too (one texture identity ⇒ the 9 pieces batch, `0x77e8d0`'s shared edge texture).
+    /// The texture needs repeat addressing. The corners stay in `[0,1]` but share the edge texture,
+    /// so they carry `true` too and the border batches as one texture (`0x77e8d0`).
     pub tile: bool,
-    /// The bg piece (`true`) draws with [`Backdrop::bg_file`]/`bg_color`; a border piece (`false`)
-    /// with `edge_file`/`border_color`. The app resolves the path + tint from the [`Backdrop`].
+    /// Drawn with `bg_file` and `bg_color`, else with `edge_file` and `border_color`.
     pub is_bg: bool,
 }
 
 const SLICE: f32 = 0.125;
 
-/// Pull a piece's UV rect half a texel inward on every axis whose range is **bounded** — i.e. does
-/// not tile — so bilinear magnification cannot reach across an atlas slice boundary.
-///
-/// The 8 border pieces live side by side in ONE texture, each occupying a [`SLICE`] of `u`, and the
-/// sampler is Linear+Repeat. A quad whose `u` ends exactly on a slice boundary samples, at its own
-/// edge, precisely the seam between two texels — so bilinear returns a 50/50 blend of this slice's
-/// last column and the **neighbouring piece's first**. Half a texel of inset moves that edge sample
-/// onto the texel's centre instead, which is the whole fix.
-///
-/// It is invisible at the reference's own 1024×768, where the 32-texel slice draws into a 16 px
-/// border and the bleed is subpixel. We draw the same slice into ~40 device px at 1440p — a 1.25×
-/// **magnification**, which gives the boundary texel a visible band of its own. In this atlas
-/// (`ChatBubble-Backdrop`, 256×32) the column next to the TOP slice is `(255,251,255)` at alpha 0,
-/// so what leaked in was **white**: the pale horizontal line the director reported through the
-/// speech bubble (1402), with a fainter twin under it from the BOTTOM slice's own boundary.
-///
-/// The bounded-axis test is what keeps this from breaking the tiling it sits next to: `u` always
-/// spans one slice and is always inset, while an edge strip's `v` runs `[0, run]` and only gets the
-/// inset when `run ≤ 1`. A strip that genuinely repeats keeps its exact period — insetting a tiling
-/// axis would make every period land a fraction short and walk the art along the run.
+/// Pull a piece's UVs half a texel inward on every axis that does not tile, so bilinear
+/// magnification cannot sample the neighbouring slice of the shared border atlas (in
+/// `ChatBubble-Backdrop`, a white alpha-0 column: a pale line through the speech bubble). A tiling
+/// axis, a strip's `v` past 1, is left exact, or each period would land short and walk the art.
 #[must_use]
 pub fn inset_atlas_bleed(uvs: [[f32; 2]; 4], tex_w: f32, tex_h: f32) -> [[f32; 2]; 4] {
     let mut out = uvs;
     for (axis, tex) in [(0usize, tex_w), (1usize, tex_h)] {
         if tex < 2.0 {
-            continue; // a 1-texel axis has no interior to inset toward
+            continue; // a 1-texel axis has no interior
         }
         let (lo, hi) = uvs.iter().fold((f32::MAX, f32::MIN), |(lo, hi), c| {
             (lo.min(c[axis]), hi.max(c[axis]))
         });
-        // A tiling axis is left exactly alone (see above); `1.0` is one whole period, which is
-        // bounded and does get the inset — that is the corner pieces, whose `v` is `[0,1]`.
+        // A range of exactly 1, the corners' `v`, is bounded and gets the inset.
         if hi - lo > 1.0 + f32::EPSILON {
             continue;
         }
@@ -143,8 +111,7 @@ pub fn inset_atlas_bleed(uvs: [[f32; 2]; 4], tex_w: f32, tex_h: f32) -> [[f32; 2
     out
 }
 
-/// Axis-aligned corners `[TL, TR, BR, BL]` (y-up) for a piece spanning `x∈[x0,x1]`, `y∈[y0,y1]`
-/// (`y1` = top). The bg overrides its own corners to reproduce the BR-inset bug.
+/// Axis-aligned corners `[TL, TR, BR, BL]`, y-up.
 fn aa_corners(x0: f32, x1: f32, y_bottom: f32, y_top: f32) -> [[f32; 2]; 4] {
     [
         [x0, y_top],    // TL
@@ -154,15 +121,14 @@ fn aa_corners(x0: f32, x1: f32, y_bottom: f32, y_top: f32) -> [[f32; 2]; 4] {
     ]
 }
 
-/// Compute the backdrop's drawable pieces for a frame whose resolved rect is `frame` (y-up), in the
-/// client's paint order: the bg (layer BACKGROUND) first, then the 8 border pieces (layer BORDER) —
-/// `0x77e8d0`. Empty when neither file is set. All geometry is `0x77e8d0`; all UVs `0x77f0c0`.
+/// The drawable pieces for a frame's resolved rect (y-up), in paint order: the background (layer
+/// `BACKGROUND`), then the 8 border pieces (layer `BORDER`). Geometry `0x77e8d0`, UVs `0x77f0c0`.
 pub fn pieces(frame: Rect, bd: &Backdrop) -> Vec<BackdropPiece> {
     let mut out = Vec::with_capacity(9);
     let e = bd.edge_size;
     let (l, r, b, t) = (frame.left, frame.right, frame.bottom, frame.top);
 
-    // ── The background piece (`0x77e8d0`, the bg anchor row) ───────────────────────────────────
+    // ── The background piece ──
     if bd.has_bg() {
         let (il, ir, it, ib) = (
             bd.insets.left,
@@ -170,18 +136,15 @@ pub fn pieces(frame: Rect, bd: &Backdrop) -> Vec<BackdropPiece> {
             bd.insets.top,
             bd.insets.bottom,
         );
-        // The four SetPoint anchors, y-up. **⚠ BR uses the TOP inset**, not bottom
-        // — the shipped 1.12.1 bug ("the BR-inset quirk", bytes `8b 46 50` @ 0x77e9ae:
-        // `SetPoint(8, frame+0x24, 8, −right, +top, 0)` loads `+0x50` = top, not `+0x54` = bottom).
-        // Invisible whenever top==bottom (every shipping backdrop); reproduced for fidelity.
+        // The four anchors, y-up. Bottom-right takes the top inset, as the reference does
+        // (`0x77e9ae` loads `+0x50`, top, not `+0x54`); invisible when the two are equal.
         let corners = [
-            [l + il, t - it], // TL ← frame TL (+left, −top)
-            [r - ir, t - it], // TR ← frame TR (−right, −top)
-            [r - ir, b + it], // BR ← frame BR (−right, +top)  ⚠ bug: top inset
-            [l + il, b + ib], // BL ← frame BL (+left, +bottom)
+            [l + il, t - it],
+            [r - ir, t - it],
+            [r - ir, b + it], // BR: the top inset
+            [l + il, b + ib],
         ];
-        // Tiled bg UVs (`0x77f0c0`): period = tileSize, or edgeSize when tileSize==0. When not
-        // tiled, no SetTexCoord runs and the bg keeps [0,1] (stretch).
+        // Untiled, no `SetTexCoord` runs and the background stretches over `[0,1]` (`0x77f0c0`).
         let uvs = if bd.tile {
             let period = if bd.tile_size != 0.0 { bd.tile_size } else { e };
             let bg_w = (r - ir) - (l + il);
@@ -199,14 +162,12 @@ pub fn pieces(frame: Rect, bd: &Backdrop) -> Vec<BackdropPiece> {
         });
     }
 
-    // ── The 8 border pieces (`0x77e8d0` edge rows + `0x77f0c0` UV rows) ────────────────────────
+    // ── The 8 border pieces ──
     if bd.has_border() {
-        // Run lengths (`0x77f0c0`): the edge strips tile `run` periods between the two corner
-        // squares (no upper clamp — they TILE, never stretch); clamped to 0 below 2·edgeSize.
+        // Edge strips tile `run` periods between the corners, 0 below two edges (`0x77f0c0`).
         let w_run = ((r - l) / e - 2.0).max(0.0);
         let h_run = ((t - b) / e - 2.0).max(0.0);
 
-        // Helper: push an axis-aligned edge/corner piece.
         let mut edge = |x0: f32, x1: f32, y0: f32, y1: f32, uvs: [[f32; 2]; 4]| {
             out.push(BackdropPiece {
                 corners: aa_corners(x0, x1, y0, y1),
@@ -216,7 +177,7 @@ pub fn pieces(frame: Rect, bd: &Backdrop) -> Vec<BackdropPiece> {
             });
         };
 
-        // LEFT (slice 0): upright, v ∈ [0, h_run].
+        // LEFT, slice 0, upright.
         edge(
             l,
             l + e,
@@ -224,7 +185,7 @@ pub fn pieces(frame: Rect, bd: &Backdrop) -> Vec<BackdropPiece> {
             t - e,
             [[0.0, 0.0], [SLICE, 0.0], [SLICE, h_run], [0.0, h_run]],
         );
-        // RIGHT (slice 1): upright.
+        // RIGHT, slice 1, upright.
         edge(
             r - e,
             r,
@@ -237,8 +198,7 @@ pub fn pieces(frame: Rect, bd: &Backdrop) -> Vec<BackdropPiece> {
                 [SLICE, h_run],
             ],
         );
-        // TOP (slice 2): ROTATED — atlas-u→screen-Y (0.25 top, 0.375 bottom), atlas-v→screen-X
-        // reversed (w_run at the LEFT end, 0 at the RIGHT).
+        // TOP, slice 2, rotated: atlas `u` runs down the screen, atlas `v` right to left.
         edge(
             l + e,
             r - e,
@@ -251,7 +211,7 @@ pub fn pieces(frame: Rect, bd: &Backdrop) -> Vec<BackdropPiece> {
                 [3.0 * SLICE, w_run],
             ],
         );
-        // BOTTOM (slice 3): same rotation as TOP.
+        // BOTTOM, slice 3, rotated as TOP.
         edge(
             l + e,
             r - e,
@@ -264,7 +224,7 @@ pub fn pieces(frame: Rect, bd: &Backdrop) -> Vec<BackdropPiece> {
                 [4.0 * SLICE, w_run],
             ],
         );
-        // Corners (slices 4..7): upright, v ∈ [0,1].
+        // The corners, slices 4 to 7, upright.
         let corner_uv = |i: f32| {
             let u0 = i * SLICE;
             let u1 = (i + 1.0) * SLICE;
@@ -283,21 +243,16 @@ pub fn pieces(frame: Rect, bd: &Backdrop) -> Vec<BackdropPiece> {
 mod tests {
     use super::*;
 
-    /// The bleed inset moves each BOUNDED axis's edge sample onto a texel CENTRE, and leaves a
-    /// tiling axis bit-exact. Pinned against the real `ChatBubble-Backdrop` geometry (256×32, eight
-    /// 32-texel slices) because that is the atlas whose white alpha-0 column put a line through the
-    /// speech bubble (1402).
+    /// On the `ChatBubble-Backdrop` geometry: 256×32, eight 32-texel slices.
     #[test]
     fn the_bleed_inset_lands_on_texel_centres_and_spares_tiling() {
         const W: f32 = 256.0;
         const H: f32 = 32.0;
         let half_u = 0.5 / W;
 
-        // A CORNER: u = one slice, v = [0,1]. Both axes are bounded, so both inset.
         let corner = [[0.5, 0.0], [0.625, 0.0], [0.625, 1.0], [0.5, 1.0]];
         let got = inset_atlas_bleed(corner, W, H);
-        // In texel coordinates the edges now sit on 128.5 / 159.5 — the centres of the first and
-        // last texels of the slice, which is exactly what stops bilinear reaching texel 127.
+        // 128.5 and 159.5 are the centres of the slice's first and last texels.
         let us: Vec<f32> = got.iter().map(|c| c[0] * W).collect();
         assert!((us[0] - 128.5).abs() < 1e-3, "left u at {} texels", us[0]);
         assert!((us[1] - 159.5).abs() < 1e-3, "right u at {} texels", us[1]);
@@ -305,8 +260,6 @@ mod tests {
         assert!((vs[0] - 0.5).abs() < 1e-3, "top v at {} texels", vs[0]);
         assert!((vs[2] - 31.5).abs() < 1e-3, "bottom v at {} texels", vs[2]);
 
-        // A TILING edge strip: u = one slice (bounded → inset), v = [0, 8] (tiling → untouched).
-        // Touching v would make every period land a fraction short and walk the art along the run.
         let strip = [[0.25, 8.0], [0.25, 0.0], [0.375, 0.0], [0.375, 8.0]];
         let got = inset_atlas_bleed(strip, W, H);
         for (g, s) in got.iter().zip(strip.iter()) {
@@ -315,7 +268,6 @@ mod tests {
         assert!((got[0][0] - (0.25 + half_u)).abs() < 1e-6);
         assert!((got[2][0] - (0.375 - half_u)).abs() < 1e-6);
 
-        // The inset NEVER crosses a slice boundary — the property the whole thing exists for.
         for i in 0u8..8 {
             let (u0, u1) = (f32::from(i) * SLICE, f32::from(i + 1) * SLICE);
             let piece = [[u0, 0.0], [u1, 0.0], [u1, 1.0], [u0, 1.0]];
@@ -328,7 +280,6 @@ mod tests {
             }
         }
 
-        // Degenerate inputs are identities, not panics or inversions.
         assert_eq!(inset_atlas_bleed(corner, 0.0, 0.0), corner);
         let sliver = [[0.0, 0.0], [0.001, 0.0], [0.001, 1.0], [0.0, 1.0]];
         assert_eq!(
@@ -355,62 +306,53 @@ mod tests {
         }
     }
 
-    // The primary piece-geometry check: a 200×100 frame, edgeSize 16, insets 5/5/5/5 (the tooltip's
-    // shape). Frame y-up rect = [bottom 0, left 0, top 100, right 200].
+    // The tooltip's shape on a 200×100 frame (`Rect::new` takes bottom, left, top, right).
     #[test]
     fn piece_geometry_200x100_edge16_inset5() {
         let frame = Rect::new(0.0, 0.0, 100.0, 200.0);
         let bd = tooltip_backdrop(16.0, 5.0);
         let ps = pieces(frame, &bd);
-        // bg + 8 border pieces.
         assert_eq!(ps.len(), 9);
 
-        // bg: inset by 5 on every side; with symmetric insets the BR bug is invisible (rect exact).
+        // Symmetric insets hide the bottom-right quirk.
         let bg = ps[0];
         assert!(bg.is_bg);
-        assert_eq!(bg.corners[0], [5.0, 95.0]); // TL (left+5, top-5)
+        assert_eq!(bg.corners[0], [5.0, 95.0]); // TL
         assert_eq!(bg.corners[1], [195.0, 95.0]); // TR
-        assert_eq!(bg.corners[2], [195.0, 5.0]); // BR (bottom+top_inset = 0+5)
-        assert_eq!(bg.corners[3], [5.0, 5.0]); // BL (bottom+bottom_inset = 0+5)
-                                               // Tiled bg UVs: period = tileSize 16; bg is 190×90 ⇒ 11.875 × 5.625 tiles.
+        assert_eq!(bg.corners[2], [195.0, 5.0]); // BR
+        assert_eq!(bg.corners[3], [5.0, 5.0]); // BL
         assert_eq!(bg.uvs[0], [0.0, 0.0]);
         assert!((bg.uvs[1][0] - 190.0 / 16.0).abs() < 1e-4);
         assert!((bg.uvs[2][1] - 90.0 / 16.0).abs() < 1e-4);
 
-        // The border pieces are LEFT, RIGHT, TOP, BOTTOM, TL, TR, BL, BR (indices 1..9). The whole
-        // border sits INSIDE the frame rect, flush, insets untouched.
+        // Border pieces 1 to 8: LEFT, RIGHT, TOP, BOTTOM, TL, TR, BL, BR, flush inside the frame.
         let left = ps[1];
         assert!(!left.is_bg && left.tile);
-        // LEFT edge spans x∈[0,16], y∈[16,84] (b+e .. t-e); corners [TL,TR,BR,BL] y-up.
         assert_eq!(
             left.corners,
             [[0.0, 84.0], [16.0, 84.0], [16.0, 16.0], [0.0, 16.0]]
         );
-        // h_run = 100/16 - 2 = 4.25; LEFT UVs upright, v ∈ [0, 4.25].
+        // h_run = 100/16 - 2 = 4.25.
         assert_eq!(left.uvs[0], [0.0, 0.0]);
         assert_eq!(left.uvs[1], [0.125, 0.0]);
         assert!((left.uvs[3][1] - 4.25).abs() < 1e-4);
 
-        // TOP (index 3): ROTATED. x∈[16,184], y∈[84,100]. w_run = 200/16 - 2 = 10.5.
+        // TOP, rotated; w_run = 200/16 - 2 = 10.5.
         let top = ps[3];
         assert_eq!(top.corners[0], [16.0, 100.0]); // TL
         assert_eq!(top.corners[2], [184.0, 84.0]); // BR
-                                                   // atlas-u→screen-Y: top row u=0.25, bottom row u=0.375.
         assert_eq!(top.uvs[0][0], 0.25); // TL u
         assert_eq!(top.uvs[3][0], 0.375); // BL u
-                                          // atlas-v→screen-X reversed: LEFT end v=w_run, RIGHT end v=0.
         assert!((top.uvs[0][1] - 10.5).abs() < 1e-4); // TL v = w_run
         assert_eq!(top.uvs[1][1], 0.0); // TR v = 0
 
-        // BOTTOMRIGHT corner (index 8): slice 7, upright, v∈[0,1], x∈[184,200], y∈[0,16].
+        // BOTTOMRIGHT, slice 7, upright.
         let br = ps[8];
         assert_eq!(br.corners[0], [184.0, 16.0]); // TL
         assert_eq!(br.uvs[0], [0.875, 0.0]);
         assert_eq!(br.uvs[2], [1.0, 1.0]);
     }
 
-    // The BR-inset quirk (bytes 8b 46 50 @ 0x77e9ae): with top != bottom the bg's
-    // BOTTOMRIGHT corner rides the TOP inset, not the bottom. Asymmetric insets make it assertable.
     #[test]
     fn bg_bottomright_rides_top_inset_bug() {
         let frame = Rect::new(0.0, 0.0, 100.0, 200.0);
@@ -424,21 +366,16 @@ mod tests {
             ..tooltip_backdrop(16.0, 0.0)
         };
         let bg = pieces(frame, &bd)[0];
-        // BL uses the (correct) bottom inset: y = bottom + 9.
         assert_eq!(bg.corners[3], [3.0, 9.0]);
-        // BR uses the TOP inset (the bug): y = bottom + 7, NOT bottom + 9.
+        // BR takes the top inset, 7, not the bottom's 9.
         assert_eq!(bg.corners[2], [196.0, 7.0]);
-        // The other three edges are regular: TL/TR ride the top inset (−7), left/right insets applied.
-        assert_eq!(bg.corners[0], [3.0, 93.0]); // TL (left+3, top-7)
-        assert_eq!(bg.corners[1], [196.0, 93.0]); // TR (right-4, top-7)
+        assert_eq!(bg.corners[0], [3.0, 93.0]); // TL
+        assert_eq!(bg.corners[1], [196.0, 93.0]); // TR
     }
 
-    // Run clamp at tiny sizes: a frame narrower/shorter than 2·edgeSize clamps both runs to 0 (no
-    // negative tiling), so the edge strips carry a zero-length run (`0x77f0c0`, clamped to 0 if
-    // < 0).
     #[test]
     fn run_clamps_to_zero_below_two_edges() {
-        // 20×20 frame, edgeSize 16 ⇒ width/16 - 2 = -0.75 → 0.
+        // 20/16 - 2 = -0.75.
         let frame = Rect::new(0.0, 0.0, 20.0, 20.0);
         let bd = tooltip_backdrop(16.0, 5.0);
         let ps = pieces(frame, &bd);
@@ -448,7 +385,6 @@ mod tests {
         assert_eq!(top.uvs[0][1], 0.0, "w_run clamped to 0"); // TL v
     }
 
-    // No files ⇒ no pieces; bg-only ⇒ 1; border-only ⇒ 8.
     #[test]
     fn presence_gates_pieces() {
         let frame = Rect::new(0.0, 0.0, 100.0, 100.0);
diff --git a/crates/benilla-ui/src/script/bank.rs b/crates/benilla-ui/src/script/bank.rs
index f88c9c2c..0e757aeb 100644
--- a/crates/benilla-ui/src/script/bank.rs
+++ b/crates/benilla-ui/src/script/bank.rs
@@ -1,54 +1,22 @@
-//! The bank bindings (decision 0604 phase 4) — the Era-shaped bank surface, the same two-way seam
-//! as [`super::merchant`]: the app pushes a **bank snapshot** ([`UiScript::set_bank`] — the
-//! purchased-slot count off the descriptor's `PLAYER_BYTES_2` byte 2 plus the next slot's
-//! `BankBagSlotPrices.dbc` cost), and the Lua `PurchaseSlot`/`CloseBankFrame` calls queue outbound
-//! **intents** the app drains ([`UiScript::take_bank_purchase`] / [`UiScript::take_bank_close`]).
+//! The bank bindings: the app pushes the open bank's snapshot ([`UiScript::set_bank`]), and
+//! `PurchaseSlot` and `CloseBankFrame` queue intents it drains.
 //!
-//! The bank's *contents* never pass through here: bank slots are player-array slots the container
-//! seam already carries — the app feeds them as container `-1` (`BANK_CONTAINER`, the 24 generic
-//! slots) and containers `5..=10` (the six bank bags), the reference client's own id space
-//! (`BankFrame.lua:1-4`), so the container verbs, the cursor drag-drop, and the stack split all
-//! work on bank slots with no bank-specific surface.
-//!
-//! Nor do the six bank BAGS — the bag items themselves, as opposed to what is inside them. Those
-//! are inventory slots at live ids 64..=69, fed beside the paper doll's
-//! ([`super::char_stats::BankBagSlots`]) and read through the ordinary `GetInventoryItem*` /
-//! `PickupBagFromSlot` surface, which is exactly how the reference's own bank reads them
-//! (`BankFrame.lua:28`, `ButtonInventorySlot`). They stream in the player descriptor whether or
-//! not a banker is open, so they are not part of the window's snapshot.
-//!
-//! ## The 5875 API shape (the reference `BankFrame.lua`, read as behavior spec this session)
-//!
-//! - `GetNumBankSlots()` → `numSlots, full` — purchased count 0..6, `full` as `1`/`nil`
-//!   (`UpdateBagSlotStatus` destructures exactly this pair; `full` hides the purchase frame).
-//! - `GetBankSlotCost(numSlots)` → the NEXT slot's cost in copper. The real binding reads
-//!   `BankBagSlotPrices.dbc` — whose rows 7+ hold a 999999999 sentinel, so the call answers even
-//!   when the bank is full (the purchase frame is already hidden then). The argument is ignored
-//!   here as it is there: the cost of "the next slot" is a fact of the pushed state.
-//! - `PurchaseSlot()` — the confirm popup's accept (`StaticPopup.lua` `CONFIRM_BUY_BANK_SLOT`):
-//!   queue the buy intent; the app sends `CMSG_BUY_BANK_SLOT`. No packet on success — the
-//!   descriptor's byte-2 delta is the confirmation (`PLAYERBANKBAGSLOTS_CHANGED`).
-//! - `CloseBankFrame()` — client-side close, **no packet exists** for it (decision 0604): flag the
-//!   app to clear its session, the merchant/gossip pattern.
-//! - `BankButtonIDToInvSlotID(id, isBag)` — the pure button→live-inventory-slot map: item button
-//!   `i` (1..24) → live `39 + i` (wire 39..62 + 1), bag button — whose id is the **container id**
-//!   5..10, not a bag number — → live `59 + id` (wire 63..68 + 1); the same "live id − 1 = wire
-//!   slot" law as the doll (`crate::script::container`'s `EQUIPMENT_BAG` space). See the binding
-//!   for the four places the reference's own file pins the bag arm's numbering.
+//! The vault is container `-1` (24 slots) and containers 5..=10 (the six bags), the reference's
+//! own ids (`BankFrame.lua:1-4`), so the container verbs work on it unchanged. The bag items
+//! themselves are inventory slots 64..=69, read through `GetInventoryItem*` as the reference's bank
+//! reads them (`BankFrame.lua:28`); they stream whether or not a banker is open.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// The open bank window's snapshot: what the purchase row and the six bag buttons need. Pushed
-/// whole by the app while the bank session is open; `None` = no bank open (the window is closed).
-/// The bank's item contents ride the container seam (module doc), not this.
+/// The open bank's purchase row, pushed whole by the app.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct BankState {
-    /// Purchased bank-bag slots (0..=6) — the descriptor's `PLAYER_BYTES_2` byte 2.
+    /// Purchased bag slots, 0..=6: `PLAYER_BYTES_2` byte 2.
     pub num_purchased: u32,
-    /// The NEXT slot's price in copper (`BankBagSlotPrices.dbc` row `num_purchased + 1`; the DBC's
-    /// own 999999999 sentinel past slot 6). 0 only if the DBC row is genuinely absent.
+    /// The next slot's price in copper, `BankBagSlotPrices.dbc` row `num_purchased + 1`; the rows
+    /// past 6 hold 999999999, and 0 means the row is absent.
     pub next_cost: u32,
 }
 
@@ -58,14 +26,14 @@ impl super::UiScript {
         self.model_mut().bank = state;
     }
 
-    /// Whether `PurchaseSlot()` was called since the last drain (and clear the flag). The app
-    /// sends `CMSG_BUY_BANK_SLOT` to the open session's banker.
+    /// Whether `PurchaseSlot()` was called since the last drain; the app sends
+    /// `CMSG_BUY_BANK_SLOT`. Success has no reply packet, only the `PLAYER_BYTES_2` byte-2 change
+    /// (`ItemHandler.cpp:934`).
     pub fn take_bank_purchase(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().bank_purchase)
     }
 
-    /// Whether `CloseBankFrame()` was called since the last drain (and clear the flag). No packet
-    /// — the app just clears its local bank session (the merchant pattern).
+    /// Whether `CloseBankFrame()` was called since the last drain; no packet exists for it.
     pub fn take_bank_close(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().bank_close)
     }
@@ -75,8 +43,8 @@ impl super::UiScript {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetNumBankSlots() → numSlots, full (1/nil — the client's boolean shape; the reference
-    // destructures `local numSlots, full = GetNumBankSlots()`). 0, nil with no bank open.
+    // GetNumBankSlots() → numSlots, full: `full` is 1 from six slots up, else nil (`0x4f85b0`:
+    // `cmp esi,6; jl`).
     g.set(
         "GetNumBankSlots",
         lua.create_function(|lua, ()| {
@@ -96,8 +64,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetBankSlotCost(numSlots) → the next slot's cost in copper (module doc: the argument is
-    // decorative — the pushed state already names the next slot). 0 with no bank open.
+    // GetBankSlotCost(numSlots): the argument is unread; the pushed state names the next slot.
     g.set(
         "GetBankSlotCost",
         lua.create_function(|lua, _n: Option<u32>| {
@@ -106,10 +73,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // BenillaGetBankBagTexture(i) → the bank bag slot's held-bag icon path | nil (empty slot, or
-    // no bank open) — benilla-named (module doc: the snapshot carries what the reference read
-    // through the inventory-item API).
-    // PurchaseSlot() — queue the bank-slot buy intent (the CONFIRM_BUY_BANK_SLOT popup's accept).
+    // PurchaseSlot(): the `CONFIRM_BUY_BANK_SLOT` popup's accept (`StaticPopup.lua:52`).
     g.set(
         "PurchaseSlot",
         lua.create_function(|lua, ()| {
@@ -119,7 +83,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CloseBankFrame() — client-side close (no packet exists, decision 0604): flag the app.
     g.set(
         "CloseBankFrame",
         lua.create_function(|lua, ()| {
@@ -129,39 +92,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // BankButtonIDToInvSlotID(id, isBag) — the pure button→live-slot map (module doc).
-    //
-    // `0x4f8530` (118 bytes). Three findings, and two of them corrected
-    // this binding:
-    //
-    // 1 · **The arithmetic is `+59` / `+39`, and the bag arm takes the CONTAINER id 5..10** — not
-    //   a bag number 1..6, which is what this used to compute. `0x4f8575 dec esi` runs BEFORE the
-    //   branch and `0x4f8587 inc esi` AFTER it, so the pair cancels and the constants stand as
-    //   written (`0x4f857f add esi,0x3b` / `0x4f8584 add esi,0x27`). The bag arm is numerically
-    //   identical to `ContainerIDToInventoryID 0x4f94e0`'s own `id >= 5` arm — two functions, two
-    //   instruction sequences, one constant. The reference's file pins the same numbering four
-    //   times over: `BankFrame.xml` gives `BankFrameBag1` `id="5"`, `ButtonInventorySlot` hands
-    //   `this:GetID()` straight in, and `UpdateBagButtonHighlight`/`BankFrameItemButton_UpdateLock`
-    //   both subtract 4 from it to get back to 1..6.
-    //
-    // 2 · **`isBag` is a TYPE test, not a truthiness test.** `0x4f8576 call 0x6f34d0` is
-    //   `lua_isnumber(L, 2)`, which accepts tag 3 or a tag-4 string `luaO_str2d` fully consumes,
-    //   and refuses every other tag at `0x6f7c35` without ever loading the value. So **`true`
-    //   takes the same arm as `nil`, `false` and a missing argument**, while `0` and `"1"` take
-    //   the BAG arm. `BankFrame.lua:24` writes `this.isBag = 1` — a NUMBER — so the stock UI is
-    //   correct either way; a client that models the flag as a boolean diverges the moment an
-    //   addon passes `true`, and would then resolve the six bank bags to 44..49, colliding with
-    //   `BankFrameItem5..10`.
-    //
-    // 3 · **Total, with no range check of any kind.** The only `test`/`cmp` in all 118 bytes are
-    //   on `lua_isnumber`'s return value: no clamp, no mask, no `nil`. This used to answer 0
-    //   outside 1..24 / 5..10 as a "wired wrong" tell; that was our invention, and the reference
-    //   simply returns the arithmetic. Its immediate neighbour `GetNumBankSlots 0x4f85b0` carries
-    //   a real `cmp esi,6; jl`, so a bound would have been visible here if one existed.
-    //
-    // Argument 1 is shape A ([`binding_abi::number_arg`]): `lua_isnumber` gated, truncated toward
-    // zero by the `0x40a2b0` ftol, low dword only, and raising the `.data` usage string verbatim
-    // — which names only `buttonID`, the reference's own omission of the second parameter.
+    // BankButtonIDToInvSlotID(id, isBag) (`0x4f8530`): `id + 39` for an item button, `id + 59`
+    // for a bag button, whose id is the container id 5..=10 (`BankFrame.xml:372`), the same
+    // arithmetic as `ContainerIDToInventoryID`'s bank-bag arm (`0x4f94e0`). There is no range
+    // check. `isBag` is `lua_isnumber(L, 2)` (`0x4f8576`), not truthiness: `true` takes the item
+    // arm, `0` and `"1"` the bag arm; stock sets `this.isBag = 1` (`BankFrame.lua:24`). Argument 1
+    // truncates toward zero (`0x40a2b0`), and its usage string names only `buttonID`.
     g.set(
         "BankButtonIDToInvSlotID",
         lua.create_function(|lua, (id, is_bag): (Value, Option<Value>)| {
@@ -170,7 +106,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 id,
                 "Usage: BankButtonIDToInvSlotID(buttonID)",
             )?;
-            // Finding 2: `lua_isnumber(L, 2)`, asked of the VALUE's type — never its truthiness.
             let is_bag = is_bag
                 .and_then(|v| lua.coerce_number(v).ok().flatten())
                 .is_some();
@@ -187,8 +122,6 @@ mod tests {
     use super::BankState;
     use crate::script::UiScript;
 
-    /// The purchase-row reads: closed → (0, nil)/0; open → the pushed count + next cost; six
-    /// purchased → `full` = 1 (the reference hides the purchase frame on it).
     #[test]
     fn bank_snapshot_reads() {
         let mut s = UiScript::new().unwrap();
@@ -206,7 +139,7 @@ mod tests {
             .unwrap());
         assert_eq!(s.eval::<i64>("return GetBankSlotCost(2)").unwrap(), 100_000);
 
-        // Six purchased: full = 1; the cost read still answers (the DBC's own sentinel row).
+        // Six purchased: full = 1, and 999999999 is the DBC's sentinel row.
         s.set_bank(Some(BankState {
             num_purchased: 6,
             next_cost: 999_999_999,
@@ -215,17 +148,14 @@ mod tests {
             .eval::<bool>("local n, full = GetNumBankSlots()\nreturn n == 6 and full == 1")
             .unwrap());
 
-        // Clearing empties it.
         s.set_bank(None);
         assert!(s
             .eval::<bool>("local n, full = GetNumBankSlots()\nreturn n == 0 and full == nil")
             .unwrap());
     }
 
-    /// The six bank BAGS are inventory slots at live ids 64..=69, read through the ordinary
-    /// inventory API — the band the reference's own bank uses (`ButtonInventorySlot` →
-    /// `BankButtonIDToInvSlotID(id, this.isBag)`, BankFrame.lua:28). Empty slots answer nil, and
-    /// the band does not bleed into the equipment array below it.
+    /// The bank bags are inventory slots 64..=69, as the reference's bank reads them
+    /// (`BankFrame.lua:28`).
     #[test]
     fn bank_bag_slots_read_through_the_inventory_api() {
         let mut s = UiScript::new().unwrap();
@@ -260,7 +190,7 @@ mod tests {
                 .unwrap(),
             4500
         );
-        // Bag slot 2 is empty, and slot 70 is past the band — neither falls through to the doll.
+        // Slot 65 is empty and 70 is past the band; neither falls through to the doll.
         assert!(s
             .eval::<bool>("return GetInventoryItemTexture(\"player\", 65) == nil")
             .unwrap());
@@ -283,14 +213,8 @@ mod tests {
         assert!(!s.take_bank_close(), "drained");
     }
 
-    /// **The bank's inventory BAND answers from the container feed** — the map decision 1751's
-    /// bank swap turns on. The reference's bank paints every slot through the inventory API
-    /// (`BankFrameItemButton_OnUpdate` → `GetInventoryItemTexture("player", BankButtonIDToInv
-    /// SlotID(id))`, BankFrame.lua:35) while benilla feeds the same items as container `-1`. If
-    /// those two ever disagree the bank draws empty, which is exactly the failure this pins.
-    ///
-    /// Asserted through the live API rather than the model, because the API is what the
-    /// reference's file calls, and the tooltip must agree with the icon under it.
+    /// The reference paints the vault through the inventory API (`BankFrame.lua:35`) while the app
+    /// feeds it as container `-1`; if the two disagree the bank draws empty.
     #[test]
     fn the_bank_band_reads_the_vault_through_the_inventory_api() {
         let mut s = UiScript::new().unwrap();
@@ -315,7 +239,7 @@ mod tests {
             }),
         );
 
-        // Vault slot 3 is live-API inventory id 42 (BankButtonIDToInvSlotID(3)).
+        // Vault slot 3 is inventory id 42.
         assert_eq!(
             s.eval::<i64>("return BankButtonIDToInvSlotID(3)").unwrap(),
             42
@@ -335,8 +259,7 @@ mod tests {
                 .unwrap(),
             4496
         );
-        // …and an empty vault slot answers nil, not the equipment slot that shares no numbering
-        // with it — the band must not fall through to `inventory_slots`.
+        // An empty vault slot answers nil rather than falling through to `inventory_slots`.
         assert!(s
             .eval::<bool>("return GetInventoryItemTexture(\"player\", 43) == nil")
             .unwrap());
@@ -346,13 +269,8 @@ mod tests {
             .unwrap());
     }
 
-    /// The button→live-slot map: item buttons 1..24 → 40..63; bag buttons — **whose ids are the
-    /// container ids 5..10, not bag numbers** — → 64..69 (live id − 1 = the wire slot: bank items
-    /// 39..62, bank bags 63..68).
-    ///
-    /// The bag arm's numbering is checked here because getting it wrong reads six slots off the
-    /// end of the band and draws an empty bag row — which is what this binding did before
-    /// `0x4f8530` was read.
+    /// Item buttons 1..=24 map to 40..=63 and bag buttons, whose ids are the container ids 5..=10,
+    /// to 64..=69; the wire slot is one less.
     #[test]
     fn bank_button_to_inv_slot() {
         let s = UiScript::new().unwrap();
@@ -376,9 +294,8 @@ mod tests {
             69,
             "BankFrameBag6 carries id 10"
         );
-        // It is the SAME map `ContainerIDToInventoryID` computes for a bank bag — one arithmetic
-        // under two names, and a drift between them would put the bag row and the bag windows on
-        // different slots.
+        // The same map as `ContainerIDToInventoryID` for a bank bag; a drift would put the bag row
+        // and the bag windows on different slots.
         for id in 5..=10 {
             assert_eq!(
                 s.eval::<i64>(&format!("return BankButtonIDToInvSlotID({id}, 1)"))
@@ -389,16 +306,12 @@ mod tests {
         }
     }
 
-    /// The three things `0x4f8530` corrected, each of which this binding had wrong or invented.
     #[test]
     fn bank_button_to_inv_slot_follows_the_carved_abi() {
         let s = UiScript::new().unwrap();
 
-        // **`isBag` is a TYPE test** (`lua_isnumber(L,2)`), not a truthiness test. `true` is not a
-        // number, so it takes the ITEM arm exactly as nil and false do; `0` and `"1"` are numbers
-        // and take the BAG arm. The stock UI is safe either way — `BankFrame.lua:24` writes
-        // `this.isBag = 1` — but an addon passing `true` would otherwise land the six bank bags on
-        // 44..49, on top of `BankFrameItem5..10`.
+        // `isBag` is `lua_isnumber(L, 2)`: `true` takes the item arm as nil and false do, while
+        // `0` and `"1"` take the bag arm.
         for (call, want) in [
             ("BankButtonIDToInvSlotID(5, true)", 44),
             ("BankButtonIDToInvSlotID(5, false)", 44),
@@ -415,8 +328,7 @@ mod tests {
             );
         }
 
-        // **Total — no range check of any kind.** Answering 0 outside the button ranges was ours,
-        // not the reference's; the only compares in the body are on `lua_isnumber`'s result.
+        // No range check: the only compares in `0x4f8530` test `lua_isnumber`'s result.
         assert_eq!(
             s.eval::<i64>("return BankButtonIDToInvSlotID(25)").unwrap(),
             64
@@ -427,9 +339,8 @@ mod tests {
             -61
         );
 
-        // Argument 1 is shape A: `lua_isnumber` gated, truncated toward ZERO by the `0x40a2b0`
-        // ftol (not floored), and raising the `.data` usage string — which names only `buttonID`,
-        // the reference's own omission of the second parameter.
+        // Argument 1 truncates toward zero (`0x40a2b0`), and the usage string names only
+        // `buttonID`.
         assert_eq!(
             s.eval::<i64>("return BankButtonIDToInvSlotID(-2.9)")
                 .unwrap(),
diff --git a/crates/benilla-ui/src/script/battlefield_positions.rs b/crates/benilla-ui/src/script/battlefield_positions.rs
index 52858ef9..02a96108 100644
--- a/crates/benilla-ui/src/script/battlefield_positions.rs
+++ b/crates/benilla-ui/src/script/battlefield_positions.rs
@@ -1,31 +1,22 @@
-//! The battleground **position** family (decision 1980; fed by the wire handler `0x4aad40` for
-//! opcode `0x2E9`): the six verbs the stock
-//! `WorldMapFrame.lua` and `Blizzard_BattlefieldMinimap.lua` poll to place teammates and the
-//! flag carrier on the map.
-//!
-//! The wire carries raw world floats for the teammates outside the requester's group; the
-//! reference filters out itself, its four party slots and its raid roster, prefers the live
-//! object's position over the packet's, and normalizes through the world-map projection under the
-//! active queue slot's map — all app-side facts here, so the app pushes the finished list every
-//! frame ([`BattlefieldPositionView`], already filtered and projected) and the VM owns the getters'
-//! shapes: three values on every non-raising leg, `(0, 0, nil)` off the list.
+//! The battleground position verbs `WorldMapFrame.lua` and `Blizzard_BattlefieldMinimap.lua` poll
+//! to place teammates and the flag carrier (opcode `0x2E9`, handler `0x4aad40`). The reference
+//! drops itself, its party and its raid, prefers a live object's position and projects onto the
+//! active slot's map; the app does all that and pushes the finished list here.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::binding_abi::number_arg;
 use super::Model;
 
-/// One teammate as the app resolved it: the map-normalized pair (`(0, 0)` = off the displayed
-/// map) and the name, `None` while the name cache has not answered.
+/// One teammate: map-normalized position, `(0, 0)` off the displayed map, and name if known.
 #[derive(Clone, Debug, PartialEq, Default)]
 pub struct BattlefieldPositionView {
     pub uv: (f32, f32),
     pub name: Option<String>,
 }
 
-/// The flag carrier as the app resolved it: the pair, and the token the local player's faction
-/// selects (`"HordeFlag"` for an Alliance viewer, `"AllianceFlag"` for a Horde one, `None` for
-/// neither).
+/// The flag carrier: the position and the token the viewer's faction picks, `"HordeFlag"` for an
+/// Alliance viewer and `"AllianceFlag"` for a Horde one.
 #[derive(Clone, Debug, PartialEq, Default)]
 pub struct BattlefieldFlagView {
     pub uv: (f32, f32),
@@ -33,7 +24,7 @@ pub struct BattlefieldFlagView {
 }
 
 impl super::UiScript {
-    /// Push the resolved positions, the carrier (or none) and the active map's icon scale.
+    /// Push the positions, the carrier and the active map's icon scale.
     pub fn set_battlefield_positions(
         &mut self,
         players: Vec<BattlefieldPositionView>,
@@ -46,8 +37,8 @@ impl super::UiScript {
         model.battlefield_icon_scale = icon_scale;
     }
 
-    /// `RequestBattlefieldPositions()` calls since the last drain — the app throttles to 5000 ms
-    /// and sends only with an active slot.
+    /// `RequestBattlefieldPositions()` calls since the last drain; the app sends at most every
+    /// 5000 ms, and only with an active slot.
     pub fn take_battlefield_position_requests(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().battlefield_position_requests)
     }
@@ -67,7 +58,6 @@ fn three(lua: &Lua, uv: (f32, f32), third: Option<&str>) -> mlua::Result<MultiVa
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // `GetNumBattlefieldPositions()` — the survivors of the filter, one number.
     g.set(
         "GetNumBattlefieldPositions",
         lua.create_function(|lua, ()| {
@@ -76,8 +66,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBattlefieldPosition(index)` — the usage raise; 1-based over the survivors; three values
-    // on every leg, `(0, 0, nil)` off the list and for 0 or a negative.
+    // Three values on every leg that does not raise: `(0, 0, nil)` off the list, 0 and below too.
     g.set(
         "GetBattlefieldPosition",
         lua.create_function(|lua, index: Value| {
@@ -94,7 +83,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetNumBattlefieldFlagPositions()` — one carrier slot: 1 or 0.
     g.set(
         "GetNumBattlefieldFlagPositions",
         lua.create_function(|lua, ()| {
@@ -103,8 +91,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBattlefieldFlagPosition(index)` — the usage raise; selected only for index 1 with a
-    // carrier; three values always.
     g.set(
         "GetBattlefieldFlagPosition",
         lua.create_function(|lua, index: Value| {
@@ -117,8 +103,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBattlefieldMapIconScale()` — the active map's `MinimapIconScale` (map 0's with no slot,
-    // 1.0 on a missing row), pushed by the app.
+    // The active map's `MinimapIconScale`: map 0's with no slot, 1.0 for a missing row.
     g.set(
         "GetBattlefieldMapIconScale",
         lua.create_function(|lua, ()| {
@@ -127,7 +112,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `RequestBattlefieldPositions()` — counted; the app's 5000 ms throttle and slot gate decide.
     g.set(
         "RequestBattlefieldPositions",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/battlefield_queue.rs b/crates/benilla-ui/src/script/battlefield_queue.rs
index 8af3d67f..2fbf1fac 100644
--- a/crates/benilla-ui/src/script/battlefield_queue.rs
+++ b/crates/benilla-ui/src/script/battlefield_queue.rs
@@ -1,58 +1,25 @@
-//! The battleground **list and queue** family (decision 1974): the fourteen
-//! verbs the stock `BattlefieldFrame.lua` and `Minimap.xml` call, over the instance list and the
-//! three queue slots the app pushes. The scoreboard half of the same TU is
-//! [`super::battlefield_score`]; `AcceptBattlefieldPort` is [`super::dialog_verbs`]'s.
-//!
-//! ## What is the app's and what is the VM's
-//!
-//! The reference keeps three caches in `BattlefieldInfo.cpp`: the instance-id vector the
-//! `SMSG_BATTLEFIELD_LIST` handler fills (`0xb6e860`, `0x4aa6c0`), the fixed three-slot queue array
-//! `SMSG_BATTLEFIELD_STATUS` writes (`0xb6e9d0`, `0x4aa850`), and four scalars beside them — the
-//! battlemaster guid, the listed map, the bracket-adjusted level pair, and the **selected instance
-//! id**. Every
-//! verb below reads those and nothing else. The app owns the wire, the clock and the Map.dbc
-//! resolves, so it pushes the list ([`BattlefieldListView`]) when a list lands and the slots
-//! ([`BattlefieldQueueSlot`], with every clock-shaped value already in milliseconds) every frame;
-//! the VM owns the selection (`[0xb6eba0]`), the index arithmetic and the getters' shapes.
-//!
-//! ## The selection is a value, not an index
-//!
-//! `SetSelectedBattlefield(n)` stores the **instance id** at list position `n`, and
-//! `GetSelectedBattlefield()` scans the current list for that id — so a fresh list between the
-//! two calls can move or drop the selection, which the stock window's `zoneIndex − 1 ==
-//! GetSelectedBattlefield()` highlight then follows. A client that remembered an index would
-//! diverge the moment a list reorders.
-//!
-//! ## Shapes
-//!
-//! Every required index is shape A (`lua_isnumber`, so a numeric string passes; truncated toward
-//! zero; a non-number raises the binding's own `Usage:`), 1-based with the reference's unsigned
-//! `dec; cmp; jae` gate that rejects 0 and negatives in one branch. `GetBattlefieldStatus`
-//! answers **five values on every leg** — `(nil, nil, 0, 0, 0)` off the three slots.
-//! `GetBattlefieldInfo` answers nine or none. `GetBattlefieldInstanceInfo` raises with
-//! `GetBattlefieldInfo`'s usage string — the shipped client's own mislabel, reproduced.
-//! `CloseBattlefield` does nothing (`xor eax,eax; ret`).
+//! The battleground list and queue verbs of `BattlefieldFrame.lua` and `Minimap.xml`. They read
+//! the reference's instance list (`0xb6e860`, filled by `0x4aa6c0`), its three queue slots
+//! (`0xb6e9d0`, written by `0x4aa850`) and the selected instance id (`[0xb6eba0]`); the app pushes
+//! the list and the slots, clock values in ms, and the VM owns the selection.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::binding_abi::{bool_or_default, flag, number_arg};
 use super::Model;
 
-/// One queue slot as the app pushes it — the reference's `0x20`-byte slot (`0xb6e9d0`) plus the map
-/// name its `GetBattlefieldStatus` resolves off Map.dbc, and the three clock-shaped fields
-/// already reduced against the app's clock.
+/// One queue slot: the reference's `0x20`-byte slot (`0xb6e9d0`) plus its Map.dbc name.
 #[derive(Clone, Debug, PartialEq, Eq, Default)]
 pub struct BattlefieldQueueSlot {
-    /// `+0x00` — the Map.dbc row id; `0` for a cleared slot. The name is resolved for that id too
-    /// (the reference looks map 0 up like any other row).
+    /// `+0x00`, the Map.dbc row id; 0 is a cleared slot, its name looked up like any other.
     pub map_id: u32,
     /// The localized map name, or `None` when the id has no row (a real `nil`).
     pub map_name: Option<String>,
-    /// `+0x04` — `0` none, `1` queued, `2` confirm, `3` active; anything else answers `"error"`.
+    /// `+0x04`: `0` none, `1` queued, `2` confirm, `3` active; anything else answers `"error"`.
     pub status: u32,
-    /// `+0x10` — the instance id.
+    /// `+0x10`.
     pub instance_id: u32,
-    /// `+0x08`/`+0x0c` — the bracket-adjusted level pair.
+    /// `+0x08`/`+0x0c`: the bracket-adjusted level pair.
     pub min_level: u32,
     pub max_level: u32,
     /// `GetBattlefieldPortExpiration`: `deadline − now` in ms, 0 when unset or past.
@@ -66,15 +33,12 @@ pub struct BattlefieldQueueSlot {
 /// The Map.dbc half of `GetBattlefieldInfo` (`0x4ab0b0`), resolved by the app for the listed map.
 #[derive(Clone, Debug, PartialEq, Default)]
 pub struct BattlefieldMapInfo {
-    /// The localized map name (value 1).
     pub name: String,
-    /// The faction-side description (value 2) — `None` on the reference's `-1` faction leg, where
-    /// it pushes nothing at all and Lua reads a stack slot below the tuple; here that leg answers
-    /// `nil`, the one shape this binding does not reproduce (the leg is data-unreachable: every
-    /// playable race carries a faction bit).
+    /// The description for the player's faction. Deviation: `None` answers `nil` where the
+    /// reference's `-1` faction leg pushes nothing (Lua reads below the tuple), because no
+    /// playable race reaches that leg.
     pub description: Option<String>,
-    /// The row's raw `MinLevel`/`MaxLevel` columns (values 3 and 4 — the stock Lua names them
-    /// `minLevel, maxLevel`; the bracket-adjusted pair is values 8 and 9).
+    /// The row's raw `MinLevel`/`MaxLevel` (values 3 and 4), not the bracket-adjusted pair.
     pub min_level: u32,
     pub max_level: u32,
     /// Values 5–7: `[row+0x40]` signed, `[row+0x44]` and `[row+0x48]` f32.
@@ -83,7 +47,7 @@ pub struct BattlefieldMapInfo {
     pub field_18: f32,
 }
 
-/// The instance list and its scalars as the app pushes them ([`super::UiScript::set_battlefield_list`]).
+/// The instance list and the scalars beside it, as the app pushes them.
 #[derive(Clone, Debug, PartialEq, Default)]
 pub struct BattlefieldListView {
     /// The instance ids in wire order (`[0xb6e868]`).
@@ -91,15 +55,13 @@ pub struct BattlefieldListView {
     /// The bracket-adjusted level pair the list handler derived (`[0xb6eba8]`/`[0xb6ebac]`).
     pub bracket_min: u32,
     pub bracket_max: u32,
-    /// The listed map's row, `None` when the id resolves to no row (the second zero-values gate).
+    /// The listed map's row; `None` when the id has no row, which answers no values.
     pub info: Option<BattlefieldMapInfo>,
-    /// The listed map row's group-queue flag (`[row+0xa0]`, `0x4ac380`) —
-    /// `CanJoinBattlefieldAsGroup`.
+    /// The map row's group-queue flag, `[row+0xa0]`.
     pub group_queue: bool,
 }
 
-/// The reference's 1-based index gate: `dec eax; cmp eax,n; jae bail` — an unsigned compare, so
-/// `0` and every negative fall out in the same branch as `> n`.
+/// The reference's 1-based gate (`dec; cmp; jae`), unsigned: 0 and negatives fail as too large.
 fn slot_index(index: i32, n: usize) -> Option<usize> {
     usize::try_from(index)
         .ok()?
@@ -107,15 +69,13 @@ fn slot_index(index: i32, n: usize) -> Option<usize> {
         .filter(|&i| i < n)
 }
 
-/// The local-player gate `GetBattlefieldInfo` and `GetBattlefieldInstanceInfo` answer zero values
-/// behind (`0x468550` + `0x468460(ecx = 0x10)`: the player object, read at call time) — here the
-/// unit model's `"player"` token, the same answer `UnitExists("player")` gives.
+/// The local-player gate of `GetBattlefieldInfo` and `GetBattlefieldInstanceInfo`, read at call
+/// time (`0x468550`, `0x468460` with `ecx = 0x10`): the answer `UnitExists("player")` gives.
 fn player_exists(model: &Model) -> bool {
     model.unit("player").is_some_and(|u| u.exists)
 }
 
-/// `[slot+0x04]` → the status string, through the reference's four-entry jump table with its
-/// `"error"` default (`0x4ab604`).
+/// The reference's four-entry status jump table with its `"error"` default (`0x4ab604`).
 fn status_text(status: u32) -> &'static str {
     match status {
         0 => "none",
@@ -127,21 +87,19 @@ fn status_text(status: u32) -> &'static str {
 }
 
 impl super::UiScript {
-    /// Push the instance list. The selection (`[0xb6eba0]`) is left alone — a new list does not
-    /// clear it, it only decides whether `GetSelectedBattlefield` still finds it (`0x4ab360`).
+    /// Push the instance list. A new list leaves the selection (`[0xb6eba0]`) alone; it only
+    /// decides whether `GetSelectedBattlefield` still finds it (`0x4ab360`).
     pub fn set_battlefield_list(&mut self, list: BattlefieldListView) {
         self.model_mut().battlefield_list = list;
     }
 
-    /// The world-enter reset's half of this family (`0x4a9db0`): the selection cleared with the
-    /// list.
+    /// The world-enter reset (`0x4a9db0`) clears the selection with the list.
     pub fn reset_battlefield_selection(&mut self) {
         self.model_mut().battlefield_selected = 0;
     }
 
-    /// Push the three queue slots (clock-shaped values already reduced) and the instance
-    /// expiration (`[0xb6ebb8]`, `deadline − now`, 0 when unset or past) — every frame, since
-    /// three of the getters move with the clock.
+    /// Push the queue slots and the instance expiration (`[0xb6ebb8]`) every frame, since the
+    /// clock getters move.
     pub fn set_battlefield_queue(
         &mut self,
         slots: Vec<BattlefieldQueueSlot>,
@@ -152,15 +110,13 @@ impl super::UiScript {
         model.battlefield_instance_expiration_ms = instance_expiration_ms;
     }
 
-    /// `JoinBattlefield` calls since the last drain: `(instance id, 0 = first available; as a
-    /// group)`. The app adds the map, the cached battlemaster guid (which picks the opcode) and
-    /// the group-size refusal (`0x4a9f60`).
+    /// `JoinBattlefield` calls since the last drain, `(instance, as group)`; instance 0 is first
+    /// available. The app adds the map, the opcode and the group-size refusal (`0x4a9f60`).
     pub fn take_battlefield_join_requests(&mut self) -> Vec<(u32, bool)> {
         std::mem::take(&mut self.model_mut().battlefield_join_requests)
     }
 
-    /// `ShowBattlefieldList` calls that passed their gates since the last drain: the queued
-    /// slot's map id, `CMSG_BATTLEFIELD_LIST`'s payload.
+    /// `ShowBattlefieldList` calls since the last drain: the map ids for `CMSG_BATTLEFIELD_LIST`.
     pub fn take_battlefield_list_requests(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().battlefield_list_requests)
     }
@@ -169,7 +125,6 @@ impl super::UiScript {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // `GetNumBattlefields()` — 0 args, never raises: the instance count.
     g.set(
         "GetNumBattlefields",
         lua.create_function(|lua, ()| {
@@ -178,8 +133,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBattlefieldInfo()` — 0 args, never raises; ZERO values behind either gate (no player, no
-    // map row), else nine (`0x4ab0b0`).
+    // No values without a player or a map row, else nine (`0x4ab0b0`).
     g.set(
         "GetBattlefieldInfo",
         lua.create_function(|lua, ()| {
@@ -206,9 +160,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBattlefieldInstanceInfo(index)` — raises with GetBattlefieldInfo's usage string (the
-    // shipped mislabel, `0x845c48`); no player or out of range → zero values; else the instance id,
-    // pushed SIGNED (`fild dword`).
+    // Raises with `GetBattlefieldInfo`'s usage string, the reference's own mislabel (`0x845c48`).
+    // No values without a player or out of range, else the instance id pushed signed (`fild`).
     g.set(
         "GetBattlefieldInstanceInfo",
         lua.create_function(|lua, index: Value| {
@@ -227,11 +180,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `JoinBattlefield(index [, asGroup])` — arg 1 shape A, arg 2 the never-raising optional
-    // boolean reader; the instance is `index−1 < count ? list[index−1] : 0` (0 = first
-    // available, and what an out-of-range index — 0 included — degrades to), `0x4a9f60`. The
-    // refusal
-    // leg and the opcode choice are the app's and invisible to Lua.
+    // An out-of-range index, 0 included, joins instance 0, the first available (`0x4a9f60`).
     g.set(
         "JoinBattlefield",
         lua.create_function(|lua, (index, as_group): (Value, Value)| {
@@ -245,11 +194,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `CloseBattlefield()` — `xor eax,eax; ret`: nothing, and the stock window calls it on hide.
+    // A no-op in the reference (`xor eax,eax; ret`); the stock window calls it on hide.
     g.set("CloseBattlefield", lua.create_function(|_, ()| Ok(()))?)?;
 
-    // `SetSelectedBattlefield(index)` — stores the instance id at that position, or 0 when out
-    // of range (`0x4ab300`).
+    // Stores the instance id at that position, 0 when out of range (`0x4ab300`).
     g.set(
         "SetSelectedBattlefield",
         lua.create_function(|lua, index: Value| {
@@ -261,8 +209,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetSelectedBattlefield()` — the 1-based position of the stored id in the CURRENT list, or
-    // 0 on a miss (which is also what a stored 0 answers: the "first available" row).
+    // The stored id's 1-based position in the current list; 0 on a miss, as for a stored 0.
     g.set(
         "GetSelectedBattlefield",
         lua.create_function(|lua, ()| {
@@ -277,8 +224,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBattlefieldStatus(index)` — five values on EVERY leg (`0x4ab5c7`): off 1..3 it is
-    // `(nil, nil, 0, 0, 0)`, never a raise and never zero values.
+    // Five values on every leg (`0x4ab5c7`): `(nil, nil, 0, 0, 0)` off slots 1..3.
     g.set(
         "GetBattlefieldStatus",
         lua.create_function(|lua, index: Value| {
@@ -308,9 +254,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The three per-slot clock-shaped getters (`0x4ab620`/`0x4ab790`/`0x4ab820`): shape A index,
-    // 0 off 1..3, one number always. The app reduces each against its clock; the values arrive
-    // in ms.
+    // The per-slot clock getters (`0x4ab620`, `0x4ab790`, `0x4ab820`), in ms; 0 off slots 1..3.
     for (name, usage, read) in [
         (
             "GetBattlefieldPortExpiration",
@@ -342,7 +286,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // `GetBattlefieldInstanceExpiration()` — 0 args: `[0xb6ebb8] − now`, 0 when unset or past.
+    // `[0xb6ebb8] − now`, 0 when unset or past.
     g.set(
         "GetBattlefieldInstanceExpiration",
         lua.create_function(|lua, ()| {
@@ -351,8 +295,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `ShowBattlefieldList(index)` — shape A; silent off 1..3, on an empty slot, and on any
-    // status but "queued"; else the slot's map goes out as `CMSG_BATTLEFIELD_LIST`. No event.
+    // Silent unless the slot is queued; fires no event.
     g.set(
         "ShowBattlefieldList",
         lua.create_function(|lua, index: Value| {
@@ -369,8 +312,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `CanJoinBattlefieldAsGroup()` — `1` or nil off the listed map's `+0xa0` flag (`0x4ac380`).
-    // The join-time size check reads a different column and lives with the sender.
+    // `1` or nil (`0x4ac380`); the join-time group-size check reads another column, in the app.
     g.set(
         "CanJoinBattlefieldAsGroup",
         lua.create_function(|lua, ()| {
@@ -387,7 +329,7 @@ mod tests {
     use super::*;
     use crate::script::UiScript;
 
-    /// A VM with a local player — the state every in-world call is made in.
+    /// A VM with a local player, as every in-world call has.
     fn vm() -> UiScript {
         let mut s = UiScript::new().unwrap();
         s.set_unit(
@@ -433,7 +375,6 @@ mod tests {
         }
     }
 
-    /// The reference's 1-based gate: 0 and negatives fall out with the too-large ones.
     #[test]
     fn the_index_gate_is_unsigned_and_one_based() {
         assert_eq!(slot_index(1, 3), Some(0));
@@ -444,8 +385,6 @@ mod tests {
         assert_eq!(slot_index(1, 0), None);
     }
 
-    /// Nine values past both gates, none behind either; the two raw row levels sit at 3 and 4
-    /// and the bracket pair at 8 and 9.
     #[test]
     fn get_battlefield_info_answers_nine_or_none() {
         let mut s = vm();
@@ -478,7 +417,6 @@ mod tests {
         assert_eq!(got, "Arathi Basin|20|60|-1|20|29");
     }
 
-    /// The instance verb: the wrong usage string, the silent out-of-range leg, the signed push.
     #[test]
     fn get_battlefield_instance_info_raises_with_the_mislabel_and_bails_silently() {
         let mut s = vm();
@@ -507,7 +445,6 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetNumBattlefields()").unwrap(), 2);
     }
 
-    /// The selection round-trips by VALUE: a reordered list moves it, a shortened one drops it.
     #[test]
     fn the_selection_is_an_instance_id_not_a_position() {
         let mut s = vm();
@@ -542,8 +479,6 @@ mod tests {
         );
     }
 
-    /// `JoinBattlefield`: the instance at the position, 0 for "first available" and for any
-    /// out-of-range index, the optional group flag through the never-raising reader.
     #[test]
     fn join_battlefield_resolves_the_instance_and_the_group_flag() {
         let mut s = vm();
@@ -560,7 +495,6 @@ mod tests {
         s.run("CloseBattlefield()").unwrap();
     }
 
-    /// Five values on every leg of the status verb; the four status strings and the default.
     #[test]
     fn get_battlefield_status_answers_five_values_on_every_leg() {
         let mut s = UiScript::new().unwrap();
@@ -606,8 +540,6 @@ mod tests {
         );
     }
 
-    /// The clock-shaped getters read the pushed ms and answer 0 off the slots; the instance
-    /// expiration is the singleton.
     #[test]
     fn the_time_getters_read_the_pushed_milliseconds() {
         let mut s = UiScript::new().unwrap();
@@ -659,8 +591,6 @@ mod tests {
         }
     }
 
-    /// `ShowBattlefieldList` sends only for a queued, non-empty slot; the group predicate is
-    /// `1` or nil.
     #[test]
     fn show_battlefield_list_gates_on_a_queued_slot() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/battlefield_score.rs b/crates/benilla-ui/src/script/battlefield_score.rs
index 7d12537f..c23a0c65 100644
--- a/crates/benilla-ui/src/script/battlefield_score.rs
+++ b/crates/benilla-ui/src/script/battlefield_score.rs
@@ -1,32 +1,13 @@
-//! The battleground **scoreboard** family (decision 1972): the eleven
-//! verbs the stock `WorldStateFrame.lua` score frame calls, over a board the app pushes.
-//!
-//! ## What is the app's and what is the VM's
-//!
-//! The wire (`MSG_PVP_LOG_DATA`) carries rows in wire order with GUIDs; the reference resolves
-//! every name through its name cache first (`0x4aa580` — the board is not rebuilt, and the event
-//! not fired, until the last name arrives) and derives each row's **team** from the resolved race
-//! (`0` Horde, `1` Alliance, `-1` neither). That resolution is the app's — it owns the name
-//! cache and the race tables — so the app pushes [`BattlefieldScores`] with names, teams, race and
-//! class strings already in place. The VM owns what the reference's `0x4aa200` rebuild owns: the
-//! faction filter, the sort, the filtered count, and the getters' shapes.
-//!
-//! ## The sort, and the filter that is a sort (`0x4aa350`, `0x4aa200`)
-//!
-//! Rows are ordered by: the filter's team first (only when a filter is set), then killing blows
-//! descending, deaths ascending, honor gained descending, name ascending. `GetNumBattlefieldScores`
-//! is the **filtered** count; `GetBattlefieldScore(index)` and `GetBattlefieldStatData` are bounded
-//! by the **wire** count — an index past the filtered count still answers a real row of the other
-//! team, exactly as the reference does, because the filter sorts rather than compacts.
-//!
-//! Every raise is the reference's own `Usage:`; `SetBattlefieldScoreFaction` never raises.
+//! The battleground scoreboard verbs of `WorldStateFrame.lua`, over a board the app pushes with
+//! every name resolved, as the reference waits for the last name (`0x4aa580`). The filter sorts
+//! its team first rather than compacting, so an index past the filtered count answers a real row.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::binding_abi::number_arg;
 use super::Model;
 
-/// One scoreboard row as the app resolved it (wire order, see the module doc).
+/// One scoreboard row as the app resolved it, in wire order.
 #[derive(Clone, Debug, PartialEq, Eq, Default)]
 pub struct BattlefieldScoreRow {
     /// The bare name, or `Name-Realm` for a cross-realm player (the reference's `%s-%s`).
@@ -35,19 +16,17 @@ pub struct BattlefieldScoreRow {
     pub honorable_kills: u32,
     pub deaths: u32,
     pub honor_gained: u32,
-    /// `0` Horde, `1` Alliance, `-1` neither — client-derived from the race, never wire data.
+    /// `0` Horde, `1` Alliance, `-1` neither, derived from the race, never sent on the wire.
     pub faction: i32,
     pub rank: i32,
     /// The race's localized name, `None` for an id the tables do not carry (a nil return).
     pub race: Option<String>,
-    /// The class's localized name, likewise.
     pub class: Option<String>,
     /// The extra-stat dwords, eight slots (the client's block), unfilled ones zero.
     pub stats: [u32; 8],
 }
 
-/// One scoreboard column header — a `WorldStateUI.dbc` `Type == 2` row for the map
-/// (`GetBattlefieldStatInfo`): text raw (no macro expansion), icon, tooltip.
+/// A column header: a `WorldStateUI.dbc` `Type == 2` row for the map, its text not expanded.
 #[derive(Clone, Debug, PartialEq, Eq, Default)]
 pub struct BattlefieldStatColumn {
     pub text: String,
@@ -55,32 +34,30 @@ pub struct BattlefieldStatColumn {
     pub tooltip: String,
 }
 
-/// The whole board the app pushes ([`super::UiScript::set_battlefield_scores`]).
+/// The whole board the app pushes.
 #[derive(Clone, Debug, PartialEq, Eq, Default)]
 pub struct BattlefieldScores {
     pub rows: Vec<BattlefieldScoreRow>,
-    /// The `MSG_PVP_LOG_DATA` "ended" byte — gates `GetBattlefieldWinner` and `LeaveBattlefield`.
+    /// The `MSG_PVP_LOG_DATA` "ended" byte; gates the winner and `LeaveBattlefield`.
     pub ended: bool,
     /// `0` Horde, `1` Alliance; read only when `ended`.
     pub winner: u8,
     pub columns: Vec<BattlefieldStatColumn>,
 }
 
-/// The VM's half of the board: the pushed rows, the filter, and the order the filter and sort
-/// produce (indices into `rows`).
+/// The VM's half of the board: the pushed rows, the filter and the sorted order into `rows`.
 #[derive(Clone, Debug)]
 pub(crate) struct ScoreBoard {
     pub(crate) scores: BattlefieldScores,
     /// `SetBattlefieldScoreFaction`'s store: `-1` every team (the reset value), `0`, `1`.
     pub(crate) filter: i32,
     pub(crate) order: Vec<usize>,
-    /// The filtered count (`0xb6ebc4`) — the rows whose team equals the filter, or all with `-1`.
+    /// The filtered count (`0xb6ebc4`).
     pub(crate) filtered: usize,
 }
 
 impl Default for ScoreBoard {
-    /// The filter starts at `-1`, every team — the value the status-3 arm resets it to
-    /// (`or ecx,-1; call 0x4aa5a0`).
+    /// The filter starts at `-1`, the value the status-3 arm resets it to (`0x4aa5a0`).
     fn default() -> Self {
         Self {
             scores: BattlefieldScores::default(),
@@ -92,7 +69,7 @@ impl Default for ScoreBoard {
 }
 
 impl ScoreBoard {
-    /// `0x4aa200`'s recount and sort, over the pushed rows.
+    /// The reference's recount and sort (`0x4aa200`).
     fn rebuild(&mut self) {
         let rows = &self.scores.rows;
         let filter = self.filter;
@@ -105,7 +82,6 @@ impl ScoreBoard {
         order.sort_by(|&a, &b| {
             let (ra, rb) = (&rows[a], &rows[b]);
             if filter != -1 && ra.faction != rb.faction {
-                // The selected team's row appears first, with no score comparison at all.
                 return (rb.faction == filter).cmp(&(ra.faction == filter));
             }
             rb.killing_blows
@@ -119,41 +95,39 @@ impl ScoreBoard {
 
     fn row(&self, index_1based: i32) -> Option<&BattlefieldScoreRow> {
         let i = usize::try_from(index_1based).ok()?.checked_sub(1)?;
-        // Bounded by the WIRE count (`0xb6ebc0`), over the sorted order.
+        // Bounded by the wire count (`0xb6ebc0`), not the filtered one.
         self.order.get(i).map(|&r| &self.scores.rows[r])
     }
 }
 
 impl super::UiScript {
-    /// Push the resolved board. The filter is the VM's and survives a push; the order is rebuilt.
-    /// The app fires `UPDATE_BATTLEFIELD_SCORE` itself after this, so the reference's ordering
-    /// against `UPDATE_BATTLEFIELD_STATUS` on the status-3 message holds (`0x4aaa5a`/`0x4aab05`).
+    /// Push the resolved board; the filter survives. The app fires `UPDATE_BATTLEFIELD_SCORE`
+    /// itself, keeping the reference's order against `UPDATE_BATTLEFIELD_STATUS` on the status-3
+    /// message (`0x4aaa5a`/`0x4aab05`).
     pub fn set_battlefield_scores(&mut self, scores: BattlefieldScores) {
         let mut model = self.model_mut();
         model.battlefield_board.scores = scores;
         model.battlefield_board.rebuild();
     }
 
-    /// `GetBattlefieldInstanceRunTime()`'s answer, in ms — the app's clock against the stamp the
-    /// status-3 message set (`now − Δ₂`), pushed each frame.
+    /// `GetBattlefieldInstanceRunTime()`'s answer in ms, pushed each frame.
     pub fn set_battlefield_run_time_ms(&mut self, ms: u32) {
         self.model_mut().battlefield_run_time_ms = ms;
     }
 
-    /// `RequestBattlefieldScoreData()` calls since the last drain — the app throttles to 5000 ms
-    /// and sends `MSG_PVP_LOG_DATA` empty.
+    /// `RequestBattlefieldScoreData()` calls since the last drain.
     pub fn take_battlefield_score_requests(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().battlefield_score_requests)
     }
 
-    /// `LeaveBattlefield()` calls that passed the "ended" gate — the app sends
+    /// `LeaveBattlefield()` calls that passed the "ended" gate; the app sends
     /// `CMSG_LEAVE_BATTLEFIELD` with the active slot's map.
     pub fn take_battlefield_leave_requests(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().battlefield_leave_requests)
     }
 }
 
-/// A Lua number-ish → i32 by the client's `__ftol` (truncate), `None` for a non-number.
+/// A Lua number or numeric string to `i32`, truncated as the client's `__ftol` does.
 fn number_of(v: &Value) -> Option<i32> {
     match v {
         Value::Integer(i) => Some(*i as i32),
@@ -170,7 +144,6 @@ fn number_of(v: &Value) -> Option<i32> {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // `GetNumBattlefieldScores()` — the FILTERED count `[0xb6ebc4]`.
     g.set(
         "GetNumBattlefieldScores",
         lua.create_function(|lua, ()| {
@@ -179,9 +152,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBattlefieldScore(index)` — nine values on every leg (`0x4ab9d0`): name, killingBlows,
-    // honorableKills, deaths, honorGained, faction, rank, race, class; the fail leg is
-    // `nil, 0,0,0,0,0,0, nil, nil`. Bounded by the wire count over the sorted order.
+    // Nine values on every leg, the fail leg included (`0x4ab9d0`).
     g.set(
         "GetBattlefieldScore",
         lua.create_function(|lua, index: Value| {
@@ -220,7 +191,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBattlefieldWinner()` — nil until the "ended" byte, then the winner (0 Horde, 1 Alliance).
     g.set(
         "GetBattlefieldWinner",
         lua.create_function(|lua, ()| {
@@ -234,9 +204,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `SetBattlefieldScoreFaction([faction])` — never raises: a non-number means -1; only
-    // {-1, 0, 1} store, and a stored value recounts, re-sorts and fires UPDATE_BATTLEFIELD_SCORE
-    // (`0x4abc90`) — here on the deferred lane, the next dispatch.
+    // Never raises; a stored filter fires `UPDATE_BATTLEFIELD_SCORE` (`0x4abc90`), here on the
+    // next dispatch.
     g.set(
         "SetBattlefieldScoreFaction",
         lua.create_function(|lua, faction: Option<Value>| {
@@ -254,7 +223,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetNumBattlefieldStats()` — the column count, no gate.
     g.set(
         "GetNumBattlefieldStats",
         lua.create_function(|lua, ()| {
@@ -263,9 +231,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBattlefieldStatInfo(index)` — three values: text (raw), icon, tooltip; three nils
-    // for a column the map has not (the reference falls into its lookup with row id 0 and
-    // finds no row).
+    // A column the map lacks answers three nils: the reference looks up row id 0 and finds none.
     g.set(
         "GetBattlefieldStatInfo",
         lua.create_function(|lua, index: Value| {
@@ -290,9 +256,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBattlefieldStatData(playerIndex, statIndex)` — both required numbers; one number on
-    // every leg: the row's stat, or 0 for a bad row or a stat index outside 1..=8 (the reference
-    // (`0x4abdc0`) admits 9 and reads one dword past its block — ours answers 0 there).
+    // A bad row or a stat outside 1..=8 answers 0. Deviation: the reference (`0x4abdc0`) admits 9
+    // and reads one dword past its block; we answer 0 because that read is out of bounds.
     g.set(
         "GetBattlefieldStatData",
         lua.create_function(|lua, (player, stat): (Value, Value)| {
@@ -310,8 +275,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `RequestBattlefieldScoreData()` — 0 args, 0 returns; the app sends `MSG_PVP_LOG_DATA` empty
-    // under the client's 5000 ms throttle (`0x4aa170`).
+    // The app sends an empty `MSG_PVP_LOG_DATA` under the client's 5000 ms throttle (`0x4aa170`).
     g.set(
         "RequestBattlefieldScoreData",
         lua.create_function(|lua, ()| {
@@ -321,10 +285,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `LeaveBattlefield()` — a gate, then a payload (`0x4abe66`): nothing at all until the
-    // scoreboard's
-    // "ended" byte has arrived; then `CMSG_LEAVE_BATTLEFIELD` with the active slot's map (the
-    // app's, which holds the queue).
+    // Nothing at all until the scoreboard's "ended" byte has arrived (`0x4abe66`).
     g.set(
         "LeaveBattlefield",
         lua.create_function(|lua, ()| {
@@ -336,8 +297,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBattlefieldInstanceRunTime()` — 0 args, one number: ms since the instance's stamp
-    // (`now − [0xb6ebbc]`, no sign guard; 0 with no stamp). The app keeps the clock.
+    // Ms since the status-3 stamp (`now - [0xb6ebbc]`, no sign guard, 0 with no stamp).
     g.set(
         "GetBattlefieldInstanceRunTime",
         lua.create_function(|lua, ()| {
@@ -389,9 +349,7 @@ mod tests {
         s
     }
 
-    /// The sort law (`0x4aa350`): killing blows descending, deaths ascending, honor descending,
-    /// name; a filter puts its team first and shrinks the count without compacting the array
-    /// (`0xb6ebc4`/`0xb6ebc0`).
+    /// The order of `0x4aa350`; a filter shrinks the count, not the array.
     #[test]
     fn the_board_sorts_like_the_client_and_the_filter_is_a_sort() {
         let s = board();
@@ -432,8 +390,6 @@ mod tests {
         );
     }
 
-    /// The getters' shapes: nine values with the fail leg's nils and zeros, the raises, the
-    /// column triple, the stat datum, the winner gate and the leave gate.
     #[test]
     fn the_getters_answer_the_clients_shapes() {
         let mut s = board();
diff --git a/crates/benilla-ui/src/script/bind_confirm.rs b/crates/benilla-ui/src/script/bind_confirm.rs
index e7b56e78..ee5eafe2 100644
--- a/crates/benilla-ui/src/script/bind_confirm.rs
+++ b/crates/benilla-ui/src/script/bind_confirm.rs
@@ -1,81 +1,47 @@
-//! The **item soulbind confirmations** other than the loot one — the Era API surface behind
-//! `EQUIP_BIND` / `AUTOEQUIP_BIND` / `USE_BIND` (decision 1750). Three globals, no snapshot: the
-//! question arrives as an event and the answer goes straight back out, exactly like
-//! [`super::binder`] and [`super::duel`].
-//!
-//! ## What the three verbs mean, at the 1.12 bytes
-//!
-//! `EquipPendingItem(index)` `0x4898f0` and `CancelPendingEquip(index)` `0x489960` both delegate to
-//! `0x5e1be0(index, accept)`. **`index` is not a slot** — it is a 0-based index into the client's
-//! own growable pending-equip array (capacity `0xc4c290`, count `0xc4c294`, base `0xc4c298`, stride
-//! `0x20`), which is also what `EQUIP_BIND_CONFIRM`'s and `AUTOEQUIP_BIND_CONFIRM`'s `arg1` carries.
-//! `UIParent.lua:324-339` hangs it on `dialog.data` and the entries hand it straight back, so the
-//! number is opaque on both sides — which is why benilla keeps the reference's index space here
-//! instead of translating it the way the loot arm's row number is translated (1744).
-//!
-//! **Accept is a re-issue of the original action with a suppress flag, not a confirm packet** —
-//! there is no `CMSG_CONFIRM_*` in 1.12. Cancel sends nothing at all; it only releases the item
-//! locks the deferred action took (`UnlockItem 0x495420`).
-//!
-//! `ConfirmBindOnUse()` `0x48d770` is the use arm's answer and takes **no** argument, because that
-//! arm's pending state is not the array: it is two globals the fire site stamps (the item guid at
-//! `0xc4c240`, the target guid at `0xc4c1d0`), and the accept is `CGItem::Use(&target, suppress=1)`.
-//! `USE_BIND_CONFIRM` carries no arguments either, and the reference ships **no** cancel binding for
-//! it — declining simply drops the question.
-//!
-//! All three decisions are **client-local**: the client reads the cached item template's `bonding`
-//! and defers its own send. No packet raises any of them.
-//!
-//! The app owns the pending records, so this module holds only the intents.
+//! The soulbind confirmations other than loot's: `EQUIP_BIND`, `AUTOEQUIP_BIND` and `USE_BIND`.
+//! They are client-local: the client reads the cached template's bonding and defers its own send,
+//! and an accept re-issues that action with a suppress flag, as 1.12 has no confirm packet. The
+//! app owns the pending records; this module holds only the intents.
 
 use mlua::Lua;
 
 use super::Model;
 
-/// One answer to a pending-equip question: the 0-based array index the event handed out, and
-/// whether the player accepted.
+/// One answer to a pending-equip question.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct PendingEquipAnswer {
-    /// The index `EQUIP_BIND_CONFIRM`/`AUTOEQUIP_BIND_CONFIRM` carried out on `arg1`.
+    /// The event's `arg1`, not a slot: a 0-based index into the reference's pending-equip array
+    /// (`0xc4c298`, stride `0x20`), kept untranslated because Lua only hands it back.
     pub index: u32,
-    /// `true` from `EquipPendingItem` (re-issue the action), `false` from `CancelPendingEquip`
-    /// (release the locks, send nothing).
+    /// Accept re-issues the action; cancel sends nothing and only releases the item locks
+    /// (`0x495420`).
     pub accept: bool,
 }
 
 impl super::UiScript {
-    /// Drain the `EquipPendingItem`/`CancelPendingEquip` answers queued since the last drain, in
-    /// call order. An index the app is not holding a record for is the app's to ignore — the
-    /// reference's `0x5e1be0` bounds-checks against the live element count and returns.
+    /// The equip answers in call order. The app ignores an index it holds no record for, as the
+    /// reference's `0x5e1be0` bounds-checks it and returns.
     pub fn take_pending_equip_answers(&mut self) -> Vec<PendingEquipAnswer> {
         std::mem::take(&mut self.model_mut().pending_equip_answers)
     }
 
-    /// Drain the `ConfirmBindOnUse()` calls queued since the last drain — a count, because the verb
-    /// has no payload ([`super::UiScript::take_binder_confirms`]'s shape and its reason).
+    /// `ConfirmBindOnUse()` calls since the last drain.
     pub fn take_bind_on_use_confirms(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().bind_on_use_confirms)
     }
 
-    /// The client's item-usable predicate `0x5ea930` for an item known by entry — one of the two
-    /// non-trivial conjuncts on the equip arms' deferral (an item the player *cannot* equip is
-    /// never asked about, because the action it would confirm is one the server would refuse).
-    ///
-    /// Public because the deferral is decided app-side, where the send is: the engine holds the
-    /// templates and the player's requirement state, so the question has to be asked here.
-    /// Same conventions as every other caller ([`super::item_stats::item_usable_by_id`]): entry `0`
-    /// and an unanswered template are both usable.
+    /// The client's item-usable predicate (`0x5ea930`), which the app's equip deferral asks: an
+    /// item the player cannot equip is never asked about. Entry `0` and an unanswered template
+    /// read usable.
     pub fn item_usable(&self, item_id: u32) -> bool {
         super::item_stats::item_usable_by_id(&self.model_ref(), item_id)
     }
 }
 
-/// Register the three globals (the style [`super::binder`] registers its two).
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // EquipPendingItem(index) — `StaticPopupDialogs["EQUIP_BIND"].OnAccept` and its AUTOEQUIP twin
-    // (`StaticPopup.lua:612-647`). Re-issues the deferred action; the app owns what that action was.
+    // `0x4898f0`, the `OnAccept` of `EQUIP_BIND` and `AUTOEQUIP_BIND` (`StaticPopup.lua:612-647`).
     g.set(
         "EquipPendingItem",
         lua.create_function(|lua, index: u32| {
@@ -88,10 +54,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CancelPendingEquip(index) — the same two entries' `OnCancel` AND their `OnHide`, which is not
-    // redundancy: `exclusive = 1` means a second bind question hides the standing dialog, and the
-    // reference relies on that `OnHide` to cancel the record it supersedes. A superseded pending
-    // equip is CANCELLED, never silently overwritten — without it the old item's locks leak.
+    // `0x489960`, their `OnCancel` and also their `OnHide`: a second bind question hides the
+    // standing dialog (`exclusive = 1`), and that cancel releases the superseded item's locks.
     g.set(
         "CancelPendingEquip",
         lua.create_function(|lua, index: u32| {
@@ -104,9 +68,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ConfirmBindOnUse() — `StaticPopupDialogs["USE_BIND"].OnAccept` (`StaticPopup.lua:648-658`).
-    // No argument and no cancel twin: the use arm's pending state is a single client global, and
-    // declining just drops it.
+    // `0x48d770`, `USE_BIND`'s `OnAccept`, with no argument and no cancel: the use arm's pending
+    // state is two globals (item `0xc4c240`, target `0xc4c1d0`), and declining drops it.
     g.set(
         "ConfirmBindOnUse",
         lua.create_function(|lua, ()| {
@@ -123,9 +86,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 mod tests {
     use crate::script::UiScript;
 
-    /// The two equip verbs share one queue and are distinguished only by their answer — the app
-    /// needs the call ORDER as well as the verdicts, because a supersede is a cancel of one record
-    /// arriving between two others.
+    /// Order matters: a supersede is a cancel of one record arriving between two others.
     #[test]
     fn the_equip_answers_queue_in_call_order_with_their_verdicts() {
         let mut s = UiScript::new().unwrap();
@@ -142,8 +103,6 @@ mod tests {
         assert!(s.take_pending_equip_answers().is_empty(), "drained");
     }
 
-    /// `ConfirmBindOnUse` is a count, like `ConfirmBinder`: the verb carries no payload because the
-    /// pending item is the app's.
     #[test]
     fn confirm_bind_on_use_counts() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/binder.rs b/crates/benilla-ui/src/script/binder.rs
index f5b56083..2487e217 100644
--- a/crates/benilla-ui/src/script/binder.rs
+++ b/crates/benilla-ui/src/script/binder.rs
@@ -1,31 +1,19 @@
-//! The innkeeper-bind **Era API surface** (decision 1331) — two globals, no snapshot.
-//!
-//! These are the whole Lua side of setting a hearthstone, and they exist because the reference's
-//! `CONFIRM_BINDER` dialog is written against exactly them (`StaticPopup.lua:1308-1322`):
-//! `OnAccept` calls [`ConfirmBinder`], and `OnUpdate` hides the dialog the moment
-//! [`CheckBinderDist`] goes false. Both are engine bindings in 1.12 (`reference/1.12-globals.tsv`
-//! lists `ConfirmBinder` and `CheckBinderDist` as `function`/`engine`), and there are no others in
-//! the family — the question itself arrives as the `CONFIRM_BINDER` event's argument, so there is
-//! nothing to read back, exactly like [`super::duel`].
-//!
-//! The app owns the innkeeper's guid ([`crate::script::UiScript::set_binder_pending`]'s writer),
-//! which is why `ConfirmBinder()` takes no arguments and queues only a count.
+//! `ConfirmBinder` and `CheckBinderDist`, the engine globals the `CONFIRM_BINDER` dialog calls
+//! (`StaticPopup.lua:1321-1335`): Accept binds, and the dialog hides once the distance check
+//! fails. The question arrives as the event's argument, so there is nothing to read back.
 
 use mlua::Lua;
 
 use super::Model;
 
 impl super::UiScript {
-    /// Drain the `ConfirmBinder()` calls queued since the last drain — each one is a
-    /// `CMSG_BINDER_ACTIVATE`. [`super::UiScript::take_played_time_asks`]'s shape, and a count for
-    /// the same reason: the intent has no payload of its own.
+    /// `ConfirmBinder()` calls since the last drain, each a `CMSG_BINDER_ACTIVATE`; a count, since
+    /// the app holds the innkeeper's guid.
     pub fn take_binder_confirms(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().binder_confirms)
     }
 
-    /// Push whether an innkeeper's bind question is live and still in range — the host's half of
-    /// `CheckBinderDist()`. Idempotent; `false` covers both "no question pending" and "you walked
-    /// away", which is all the dialog's OnUpdate needs to decide to hide.
+    /// Push whether a bind question is pending with the innkeeper still in range.
     pub fn set_binder_pending(&mut self, pending: bool) {
         let mut model = self.model_mut();
         if model.binder_pending != pending {
@@ -34,12 +22,11 @@ impl super::UiScript {
     }
 }
 
-/// Register the two binder globals (the style [`super::duel`] registers its four).
+/// Register the two binder globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // ConfirmBinder() — the CONFIRM_BINDER dialog's Accept. The one call in the client that binds
-    // a hearthstone: everything before it is a question.
+    // `ConfirmBinder()`: the dialog's Accept, the one call that binds a hearthstone.
     g.set(
         "ConfirmBinder",
         lua.create_function(|lua, ()| {
@@ -49,7 +36,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CheckBinderDist() — polled from the dialog's OnUpdate; false hides it.
+    // `CheckBinderDist()`, polled by the dialog's OnUpdate. This answers a boolean; the
+    // reference (`0x48d210`) answers 1 or nil.
     g.set(
         "CheckBinderDist",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/binding_abi.rs b/crates/benilla-ui/src/script/binding_abi.rs
index 6eef6356..9b76b6b6 100644
--- a/crates/benilla-ui/src/script/binding_abi.rs
+++ b/crates/benilla-ui/src/script/binding_abi.rs
@@ -1,60 +1,28 @@
-//! The **registered-binding argument/error ABI** — the marshalling contract every one of build
-//! 5875's ~700 registered Lua C-bindings opens with, in one place because getting it wrong is
-//! wrong 700 times.
+//! The argument and error ABI every registered Lua C-binding of the 1.12 client opens with.
 //!
-//! ## The three helpers the reference uses, and what they accept
+//! The reference's helpers: `is-number` (`0x6f34d0`) accepts tag 3 or a string coerced through
+//! `0x6f7c20`; `is-number-or-string` (`0x6f3510`) accepts tag 3 or 4; `tonumber` (`0x6f3620`)
+//! feeds `0x40a2b0`, a double-to-int32 cast that truncates toward zero (the x87 rounding control
+//! set to chop), so -2.9 is -2.
 //!
-//! | addr | contract |
-//! |---|---|
-//! | `0x6f34d0` | `is-number(L, idx)` — tag 3, **or** a string coerced through `0x6f7c20` |
-//! | `0x6f3510` | `is-number-**or**-string(L, idx)` — strictly wider: tag 3 or tag 4 |
-//! | `0x6f3620` → `0x40a2b0` | `tonumber` then `double → int32`, **truncating toward zero** |
+//! A bad argument raises: `0x6f4940` is `luaL_error`, which never returns (it ends in `longjmp` or
+//! `exit(1)` through `0x6f4440`, `0x6fc780`, `0x6f5d80`), so the `xor eax,eax; ret` after it is
+//! unreachable and the caller's statement is abandoned. An empty answer is settled per binding:
 //!
-//! `0x40a2b0` sets the x87 rounding control to chop (`or ah,0xc`) before `fistp`, so it is a C
-//! cast and **not** `floor`: `−2.9 → −2`. [`number_arg`] reproduces that (Rust's `as` on a float
-//! truncates toward zero as well), and hands back the low dword the bindings actually consume.
-//!
-//! ## The headline: the `Usage:` arm RAISES
-//!
-//! `0x6f4940` is `luaL_error`, and it **does not return**: `luaL_where` + `lua_pushvfstring` +
-//! `lua_concat` + `lua_error`, whose own chain (`0x6f4440` → `0x6fc780` → `0x6f5d80`) ends in a
-//! CRT `longjmp` or `exit(1)` on both legs. The `xor eax,eax; ret` that MSVC emits after every
-//! such call inside a binding is **unreachable boilerplate**, not a "returns zero values" arm.
-//!
-//! So a binding's bad-argument path **abandons the caller's statement** and unwinds to the
-//! enclosing protected call. It returns neither `nil` nor zero values, and a client that answers
-//! `nil` there keeps executing a statement the real client never finishes.
-//!
-//! Stated as the negative, because it is as load-bearing as the positive: the **zero Lua values**
-//! outcome is real only where a binding reaches `xor eax,eax; ret` *without* passing through
-//! `0x6f4940` — `GetDefaultLanguage`'s four object/bounds failure edges are this repo's one
-//! example ([`super::session`]). Those arms genuinely return nothing.
-//!
-//! ## The three shapes an "empty answer" can take
-//!
-//! Settled per binding, never generalised:
-//!
-//! 1. **push nil**, one Lua value (`UnitAffectingCombat` on a false/unresolved unit,
-//!    `GetActionText` on a non-macro slot, `UnitInRaid` on a miss).
-//! 2. **zero Lua values** — distinct from `nil` for anything that counts the return list (5.0's
-//!    `arg.n`, or [`crate::script::UiScript::arity`] on the host side) and for a multiple
-//!    assignment, identical to it for a single-value caller (`GetDefaultLanguage`'s failure edges).
-//! 3. **raise** — the statement is abandoned.
+//! 1. push nil, one value (`UnitAffectingCombat` on a unit out of combat, or a token naming none);
+//! 2. zero values, distinct from nil to anything counting the returns (`arg.n`), reached only by a
+//!    `xor eax,eax; ret` that skips `0x6f4940` (`GetDefaultLanguage`'s failure edges);
+//! 3. raise.
 
 use mlua::{Lua, Value};
 
-/// `is-number` (`0x6f34d0`) → `tonumber` (`0x6f3620`) → `double → int32` truncating toward zero
-/// (`0x40a2b0`), with the binding's own `Usage:` string on the failure edge.
+/// Shape A: `is-number` (`0x6f34d0`), `tonumber` (`0x6f3620`), then the truncating `0x40a2b0`,
+/// raising the binding's `Usage:` on failure. A missing argument fails like a wrong-typed one
+/// (`0x6f3410` returns NULL past `L->top`); a numeric string passes. `0x40a2b0` stores a qword but
+/// the bindings consume only the low dword, hence `i32`.
 ///
-/// A **missing** argument fails the same test a wrong-typed one does — `0x6f3410` returns NULL
-/// past `L->top`, which `0x6f34d0` reports as "not a number" — so `f()` and `f({})` take the same
-/// raise. A numeric *string* passes: Lua 5.1's `lua_isnumber` coerces, and so does
-/// [`Lua::coerce_number`].
-///
-/// The `i32` is deliberate: `0x40a2b0` stores a qword but every binding here consumes only `eax`,
-/// the low dword. Rust's `i64 as i32` truncates the same way. (Past ±2^63 the two diverge — the
-/// x87 stores the "integer indefinite" pattern where Rust saturates — which no caller can reach
-/// and no consumer could tell apart, since both answers are garbage.)
+/// Deviation: past ±2^63 Rust saturates where the x87 stores its integer-indefinite pattern,
+/// because no real argument reaches that range.
 pub(crate) fn number_arg(lua: &Lua, v: Value, usage: &'static str) -> mlua::Result<i32> {
     match lua.coerce_number(v)? {
         Some(n) => Ok(n as i64 as i32),
@@ -62,85 +30,41 @@ pub(crate) fn number_arg(lua: &Lua, v: Value, usage: &'static str) -> mlua::Resu
     }
 }
 
-/// **Shape D** — a `lua_isnumber`-gated *flag* whose failure edge does NOT raise: the local keeps
-/// the zero it was seeded with and the binding carries on. `SetInventoryItem`'s optional third
-/// argument, the one the image's own usage string (`0x8552dc`) calls `nameOnly`, is this repo's
-/// example, and it is stricter than the other shapes on one point: after the
-/// `is-number(L, idx)` guard (`0x6f34d0`, so a numeric STRING passes it) the value is compared
-/// `> 0.0` **strictly** — `0x53303f fcomp qword [0x802970]` against a literal `0.0`, then
-/// `0x533047 test ah,0x41; 0x53304a jne` onto the block that keeps the zero. Masked AH is `0x00`
-/// only for greater-than; less (`0x01`), equal (`0x40`) and unordered (`0x41`) all jump. So `0`,
-/// a negative and NaN are false, and `1`, `0.5` and `"1"` are true.
-///
-/// The distinction from [`number_arg`] is the whole point: shape A *raises* `Usage:` on a
-/// non-number, shape D shrugs. Which shape an argument takes is per binding.
+/// Shape D: an `is-number`-gated flag whose failure keeps its zero instead of raising. The value
+/// must be strictly `> 0.0` (`0x53303f`), so 0, a negative and NaN are false and `0.5` or `"1"`
+/// true; `SetInventoryItem`'s `nameOnly` is one.
 pub(crate) fn positive_number_flag(lua: &Lua, v: Value) -> mlua::Result<bool> {
     Ok(lua.coerce_number(v)?.is_some_and(|n| n > 0.0))
 }
 
-/// **Shape C** — a numeric argument the binding reads with a bare `lua_tonumber 0x6f3620` and NO
-/// `lua_isnumber` guard, so it cannot fail: absent, `nil`, `true`, a table, a function, or an
-/// unparseable string all land on **`0.0`** and the binding completes.
-///
-/// This is the counterpart to [`number_arg`] (shape A, which raises `Usage:`), and which shape a
-/// given argument takes is **per binding, not a global law** — a census of all 408
-/// widget-registrar entries found 110 gated positions against 64 ungated ones. The clustering is
-/// the useful part: C is the
-/// colour/coordinate tuples (`Set*Color`'s r/g/b, `SetTexCoord`, `SetPosition`), A is the single
-/// scalar setters (`SetAlpha`, `SetWidth`, `SetValue`, `SetID`). Do not reach for this one because
-/// an argument "looks optional" — check the census.
-///
-/// One instruction settles why nil and a table are not distinguished: `0x6f7c32 cmp ecx,4;
-/// jne 0x6f7c6a` refuses every non-string tag without inspecting the value.
+/// Shape C: a bare `lua_tonumber` (`0x6f3620`) with no `is-number` guard, so it cannot fail:
+/// anything but a number or numeric string reads as 0.0. The reference uses it for colour and
+/// coordinate tuples (`Set*Color`, `SetTexCoord`, `SetPosition`) and shape A for scalar setters
+/// (`SetAlpha`, `SetWidth`, `SetValue`, `SetID`); which applies is per binding.
 pub(crate) fn coerced_number(lua: &Lua, v: Option<Value>) -> f64 {
     v.and_then(|v| lua.coerce_number(v).ok().flatten())
         .unwrap_or(0.0)
 }
 
-/// `is-number-or-string` (`0x6f3510`) → `arg-as-C-string` (`0x6f3690`), with the binding's own
-/// `Usage:` string on the failure edge.
-///
-/// Strictly wider than [`number_arg`]'s guard: a *number* is accepted and stringified, which is
-/// why `UnitAffectingCombat(5)` does not raise in the reference — it resolves the token `"5"`,
-/// finds nothing, and answers `nil`. Everything else (nil, boolean, table, function) raises.
+/// `is-number-or-string` (`0x6f3510`) then `0x6f3690`, raising the binding's `Usage:` on failure:
+/// a number is stringified (`UnitAffectingCombat(5)` passes here, then the unit resolver raises
+/// `Unknown unit name` for `"5"`, `0x515c14`), and nil, a boolean, a table or a function raises.
 pub(crate) fn string_arg(lua: &Lua, v: Value, usage: &'static str) -> mlua::Result<String> {
     match lua.coerce_string(v)? {
-        // Lossy, per decision 1193: a Lua 5.0 string is BYTES and the reference reads it as
-        // bytes, so an argument that is not valid UTF-8 costs a glyph here — it does not cost
-        // the call. `to_str()` used to raise, which turned one stray byte in one cp1252 addon's
-        // literal into a dead handler (2138).
+        // Lossy: a Lua string is bytes, so invalid UTF-8 costs a glyph, never the call.
         Some(s) => Ok(s.to_string_lossy()),
         None => Err(mlua::Error::RuntimeError(usage.into())),
     }
 }
 
-/// **[`string_arg`]'s shape-C partner**: coerce like the reference, and treat everything else as
-/// **absent** rather than raising.
-///
-/// The pair is 1717's rule applied to string positions — *which* shape a position takes is settled
-/// per binding, never generalised — and the model-pane and region constructors are the two ends of
-/// it, verified together:
-///
-/// | position | fetch | a table there |
-/// |---|---|---|
-/// | `Model:SetModel` arg 1 | `0x6f3510` → `0x6f3690`, result **tested** | **raises** ([`string_arg`]) |
-/// | `CreateFontString`/`CreateTexture` `name`, `layer` | `0x6f3510` → `0x6f3690`, result **not** tested | absent — this fn |
-/// | `CreateFrame` `name`, `inherits` | `0x6f3690` **unguarded** | absent — this fn |
-///
-/// **The discriminator is not the argument's type; it is whether the binding TESTS its parser's
-/// return.**
-///
-/// A **number** is accepted and stringified, exactly as `lua_tostring` coerces it — so
-/// `CreateFrame("Frame", 5)` names the frame `"5"`. Callers that must *not* coerce a number (the
-/// `lua_type(L,idx) == LUA_TSTRING` gate `CreateTexture`/`CreateFontString` put on their **fourth**
-/// argument, and only there) test the tag themselves before calling this.
+/// [`string_arg`]'s shape-C partner, for a binding that does not test the parse: a string or a
+/// number is coerced (`CreateFrame("Frame", 5)` names the frame `"5"`), anything else is absent.
+/// `CreateFrame`'s `name` and `inherits` and `CreateFontString`/`CreateTexture`'s `name` and
+/// `layer` take this; `Model:SetModel`, which tests it, takes [`string_arg`]. A caller that must
+/// refuse a number (the fourth argument of `CreateTexture`/`CreateFontString`) checks the tag.
 pub(crate) fn optional_string(lua: &Lua, v: &Value) -> Option<String> {
     match v {
-        // Lossy, per decision 1193 and for the same reason as [`string_arg`] — with a sharper
-        // symptom, because this one's failure was SILENT: `to_str().ok()` folded a string that
-        // was not valid UTF-8 into `None`, which every caller here reads as *the argument was
-        // not there*. `AddMessage` printed nothing, `CreateFrame` produced an unnamed frame, and
-        // nothing anywhere said why (2138).
+        // Lossy: invalid UTF-8 must not read as an absent argument.
         Value::String(_) | Value::Number(_) | Value::Integer(_) => lua
             .coerce_string(v.clone())
             .ok()
@@ -150,21 +74,9 @@ pub(crate) fn optional_string(lua: &Lua, v: &Value) -> Option<String> {
     }
 }
 
-/// **A free-text argument — the player-visible kind — as the reference takes it** (decision 2138).
-///
-/// The text sinks (`FontString`/`Button`/`EditBox`/`SimpleHTML` `SetText`, `SetFormattedText`,
-/// `EditBox:Insert`) took their argument as mlua's `Option<String>`, whose `FromLua` demands valid
-/// UTF-8 and **raises** otherwise. Decision 1193 settled that a UI source file is bytes and that
-/// "the right place to turn bytes into text is the boundary that actually requires text… A stray
-/// byte should cost one glyph, not the file" — and then these boundaries cost the whole call.
-/// `strsub` is byte-indexed (1193 keeps it that way deliberately), so *any* addon slicing
-/// non-ASCII text hands a sink a broken sequence, and a cp1252 literal is a broken sequence to
-/// begin with.
-///
-/// This is `Option<String>`'s conversion with exactly one arm changed: a **string** becomes its
-/// lossy text. Every other type behaves as before — absent and `nil` are `None`, a number
-/// coerces, a table or a function raises mlua's own conversion error — so the raise/absent split
-/// each binding already had ([`optional_string`]'s table) is untouched.
+/// A free-text argument for the text sinks (`SetText`, `SetFormattedText`, `EditBox:Insert`):
+/// `Option<String>`'s conversion, except that a string that is not valid UTF-8 becomes lossy text
+/// instead of raising, as the reference takes bytes.
 pub(crate) fn text_arg(lua: &Lua, v: Option<Value>) -> mlua::Result<Option<String>> {
     match v {
         None | Some(Value::Nil) => Ok(None),
@@ -173,63 +85,14 @@ pub(crate) fn text_arg(lua: &Lua, v: Option<Value>) -> mlua::Result<Option<Strin
     }
 }
 
-/// `GetBoolOrDefault` (`0x6f1c10`) — the reference's **boolean argument** coercion, which is *not*
-/// Lua truthiness and gets three arms backwards from the obvious reading. The whole jump table
-/// sits at `0x6f1ce8`.
+/// Lua's number-to-string as the 1.12 client compiles it: MSVC's `sprintf("%.14g")`
+/// (`luaV_tostring` `0x6f7c80`, format `0x871960`). `EditBox:SetNumber` (`0x798690`) formats
+/// through it too, being byte-identical to `SetText` (`0x7984c0`). The exponent has at least three
+/// digits: `1e20` prints `1e+020`.
 ///
-/// `v` is `None` for an **absent** argument (`LUA_TNONE` = −1, unsigned-compares above the table's
-/// bound and takes the default arm). mlua collapses "missing" into `Value::Nil` for a plain
-/// `Value` parameter, and the two are *different* here, so a binding whose default is `true` must
-/// take its argument as a `MultiValue` to tell them apart.
-///
-/// | Lua type | result |
-/// |---|---|
-/// | absent (`None`) | `default` |
-/// | `nil` | **false** |
-/// | boolean | itself |
-/// | lightuserdata | `default` |
-/// | number | truncate toward zero (`0x40a2b0`), then `!= 0` |
-/// | string | the table below |
-/// | table / function / userdata / thread | `default` |
-///
-/// The **string** arm is the one that bites. It does not parse the number; it dispatches on the
-/// **first byte** through the 0x4a-entry remap table at `0x6f1d08` (indexed `byte − 0x30`,
-/// *signed*, so anything outside `'0'..='y'` — an empty string's terminator included — falls to the
-/// keyword arm):
-///
-/// - first byte `'0' 'F' 'N' 'f' 'n'` → **false**
-/// - first byte `'1'..='9' 'T' 'Y' 't' 'y'` → **true**
-/// - anything else → whole-string, case-insensitive (`SStrCmpI 0x64a4c0`): `"off"`/`"disabled"` →
-///   false, `"on"`/`"enabled"` → true, and **anything unrecognised takes the `default`**
-///
-/// So `"0"` is FALSE where Lua truthiness says true (in Lua every string is truthy), which is
-/// load-bearing rather than pedantic: 1.12's own Interface panel hands its option bindings the
-/// *strings* `"0"`/`"1"`, and a re-implementation wired to `lua_toboolean` inverts every
-/// string-valued option in the game. Equally, `"0.5"` and `"-1"` are decided by their first byte
-/// alone — false and `default` — never by their numeric value.
-/// Lua 5.0's own number→string rule as the 1.12 client compiles it: `sprintf("%.14g")`
-/// (`luaV_tostring 0x6f7c80`, format string `0x871960`). Decision 1831.
-///
-/// This is the whole of `EditBox:SetNumber`'s formatting, because **`SetNumber 0x798690` and
-/// `SetText 0x7984c0` are byte-identical functions** — 245 bytes each, zero differences after
-/// masking rel32 and absolute-VA operands, differing only in which usage string they carry. The
-/// numeric verb does no numeric work of its own; the shared `lua_tostring` marshalling does it all.
-///
-/// The rule, and the three places it is not Rust's `{}`:
-///
-/// - **14 significant digits**, then trailing zeros and a bare trailing `.` are dropped.
-/// - **Exponential iff `exp < -4 || exp >= 14`** — the C `%g` switch.
-/// - **A three-digit exponent, always.** `1e20` prints `1e+020`, not `1e+20`: the exponent is
-///   copied from the literal template `"e+000"` and digits are written onto it. This is MSVC's
-///   `%g`, not C99's, and it is the single most surprising thing here.
-///
-/// **What this deliberately does NOT reproduce**, stated so it is not mistaken for an oversight:
-/// the reference's printf is not correctly rounded. It generates 17 digits half-up and then
-/// re-rounds *that string* to 14, also half-up and with no sticky bit, so it disagrees with a
-/// correctly-rounded formatter on roughly 0.05% of doubles (`-0.11594045739607` where a correct
-/// one gives `…606`). Reproducing that needs the two-stage decimal path, not a format string, and
-/// no consumer we have is sensitive to the fourteenth digit. If one ever is, this is the note that
-/// says where to look.
+/// Deviation: the result is correctly rounded, where the reference rounds to 17 digits half-up and
+/// then again to 14, differing in the last digit on about 0.05% of doubles, because no consumer
+/// reads that digit.
 pub(crate) fn lua_number_text(v: f64) -> String {
     if v.is_nan() {
         // MSVC's own spellings, which are not "NaN".
@@ -267,8 +130,7 @@ pub(crate) fn lua_number_text(v: f64) -> String {
         let (m, _) = mantissa.split_once('e').unwrap_or((mantissa.as_str(), "0"));
         let m = trim_g(m);
         let sign = if exp < 0 { '-' } else { '+' };
-        // Three digits minimum, and MORE if the exponent needs them — the template is padded,
-        // never truncated.
+        // At least three exponent digits, more when needed.
         format!("{m}e{sign}{:03}", exp.abs())
     } else {
         let decimals = (SIG - 1 - exp).max(0) as usize;
@@ -284,6 +146,19 @@ fn trim_g(s: &str) -> &str {
     s.trim_end_matches('0').trim_end_matches('.')
 }
 
+/// `GetBoolOrDefault` (`0x6f1c10`, jump table `0x6f1ce8`), the reference's boolean argument
+/// coercion, which is not Lua truthiness:
+///
+/// - absent (`None`, `LUA_TNONE`) takes `default`, but nil is false; a binding whose default is
+///   true takes a `MultiValue`, since mlua turns a missing argument into nil
+/// - a boolean is itself; a number truncates toward zero (`0x40a2b0`), then `!= 0`
+/// - a string goes by its first byte, through the remap table at `0x6f1d08`: `'0' 'F' 'N' 'f' 'n'`
+///   false, `'1'..='9' 'T' 'Y' 't' 'y'` true; any other is compared whole, case-insensitively
+///   (`0x64a4c0`): `"off"`/`"disabled"` false, `"on"`/`"enabled"` true, anything else `default`
+/// - lightuserdata, a table, function, userdata or thread takes `default`
+///
+/// So `"0"` is false and `"0.5"` goes by its first byte: the Interface panel passes its options
+/// the strings `"0"` and `"1"`.
 pub(crate) fn bool_or_default(v: Option<&Value>, default: bool) -> bool {
     let Some(v) = v else {
         return default; // LUA_TNONE
@@ -292,9 +167,7 @@ pub(crate) fn bool_or_default(v: Option<&Value>, default: bool) -> bool {
         Value::Nil => false,
         Value::Boolean(b) => *b,
         Value::LightUserData(_) => default,
-        // `lua_tonumber` then `0x40a2b0`, whose RC = chop makes it a C cast; the caller tests the
-        // low dword only, which is why the double round-trips through `i64 as i32` (see
-        // [`number_arg`]).
+        // Truncated like `0x40a2b0`, testing only the low dword.
         Value::Integer(i) => (*i as i32) != 0,
         Value::Number(n) => (*n as i64 as i32) != 0,
         Value::String(s) => {
@@ -302,8 +175,8 @@ pub(crate) fn bool_or_default(v: Option<&Value>, default: bool) -> bool {
             match bytes.first() {
                 Some(b'0' | b'F' | b'N' | b'f' | b'n') => false,
                 Some(b'1'..=b'9' | b'T' | b'Y' | b't' | b'y') => true,
-                // The keyword arm — and the fall-through for every byte the remap table cannot
-                // index, which is why an empty string lands here too.
+                // The keyword arm, also reached by every byte the remap table cannot index (and
+                // by an empty string).
                 _ => {
                     if bytes.eq_ignore_ascii_case(b"off") || bytes.eq_ignore_ascii_case(b"disabled")
                     {
@@ -322,69 +195,13 @@ pub(crate) fn bool_or_default(v: Option<&Value>, default: bool) -> bool {
     }
 }
 
-/// **The 1.12 predicate return** — `1` for true, `nil` for false, and never a Lua boolean.
-///
-/// The reference client has essentially no boolean-returning query. Across the 1503 rows
-/// `reference/1.12-shapes.tsv` marks `kinds_conf = agree`, exactly two slots in the whole binding
-/// surface are `boolean`: `IsPetAttackActive` (which really does call `lua_pushboolean 0x6f39f0`,
-/// noted in [`super::pet`]) and Lua's own `rawequal`. Every other `Is*`, `Can*`, `Has*` and every
-/// predicate slot of a multi-value answer is `(nil) | (number)`.
-///
-/// **The difference is invisible to `if x then` and decisive to everything else** — `x == 1`,
-/// `x == nil`, `tostring(x)`, arithmetic, a table key, a value round-tripped through a saved
-/// variable. That is why it survived so long: the transcribed FrameXML reads every one of these
-/// with a plain `if`, so `true` and `1` were interchangeable for as long as *we* wrote the callers.
-/// Real 1.12 addons are not our callers — `ColorPickerPlus.lua:121` writes
-/// `if IsShiftKeyDown() == 1 then`, and reads a `true` as "not held" (decision 2118).
-///
-/// Enforced, not remembered: `ui_script::shape_gate::no_query_binding_answers_a_lua_boolean`
-/// probes the whole registered query surface and fails on any Lua boolean.
-///
-/// ## What `predicate` said, folded in (2142)
-///
-/// This helper had a byte-identical TWIN sixty lines up the same file — `predicate`, 49 call
-/// sites to this one's 77 — carrying its own half of the evidence. 2118 consolidated five *local*
-/// copies into this one and left that one standing, which is the same drift one level up: a house
-/// rule with two homes gets re-derived at each new file, and the file that picks the wrong one is
-/// invisible against the others. The twin is gone; everything it recorded is below.
-///
-///
-/// The return-side counterpart to [`bool_or_default`], and the same class of fact: 1.12's widget
-/// predicates (1830) and its 29 `Unit*` predicates (2043) do not push booleans. `lua_pushboolean
-/// 0x6f39f0` has seven call sites in the whole image; **not one is inside a widget registrar body,
-/// and no binding in the 83-entry unit table at `0x850438` calls it at all** — those predicates go
-/// through `lua_pushnumber 0x6f3810` (the constant double `1.0`) / `lua_pushnil 0x6f37f0`, exactly
-/// one value at every live `ret`.
-///
-/// **Not a whole-image absolute, and 2048 corrects 2043 for saying so.** `lua_pushboolean` is real
-/// and one of its seven callers *is* a registered FrameScript binding: `IsPetAttackActive
-/// 0x4be0e0` answers a genuine Lua `true`/`false` and **never nil** (ours matches — see
-/// [`super::pet`]). The other six are `rawequal`/`pcall`/`xpcall` in the base table `0x811e28` and
-/// two unregistered helpers. So "1.12 has no `lua_pushboolean`" is false; "these two predicate
-/// families never reach it" is what the bytes support, and is what this helper encodes.
-///
-/// **The false leg is settled per body, never inherited from a neighbour.** `IsEnabled 0x7800b0`
-/// is number-`1`/number-`0`-and-never-nil (`setne` + `fild`), which is what makes
-/// `FriendsFrame.lua:404`'s `== 0` live code — so it does NOT come through here. Inside the unit
-/// table itself the *numeric getters* answer the number `0.0` where the predicates answer `nil`
-/// (`UnitLevel 0x518144`, `UnitMana 0x5177c8`, `UnitXP 0x5173f5`, ~15 more; `UnitSex 0x517f9f`
-/// pushes `2.0`).
-///
-/// **Truthiness hides the difference and direct comparison inverts it**, which is why this survived
-/// so long. `if frame:IsVisible()` reads the same either way; `if frame:IsVisible() == nil` does
-/// not — under a boolean a hidden frame answers `false`, and `false == nil` is FALSE, so the caller
-/// concludes the frame is visible exactly when it is not. The 1.12 addon corpus has 21 such direct
-/// comparisons (`IsVisible() == nil` ×9, `GetChecked() == 1` ×6, `IsVisible() ~= nil` ×4, and one
-/// each of `~= 1` / `== 1`) across Questie, AtlasQuest, CT_BagMod, MikScrollingBattleText's options
-/// and `_dl`.
-///
-/// The reference proves its own shape without needing the bytes: stock `UIOptionsFrame.xml:310`
-/// saves a checkbox as `SHOW_BUFF_DURATIONS = tostring(this:GetChecked())` and stock
-/// `BuffFrame.lua:71` reads it back as `== "1"`. That round-trip only closes if `GetChecked`
-/// returns the number 1 — `tostring(true)` is `"true"`, and buff timers would never appear.
-///
-/// Adopting it is strictly safer than what it replaces: every `if x` and `not x` site reads
-/// identically, and only the direct comparisons change — from wrong to right.
+/// The 1.12 predicate return: `1` for true, nil for false, never a Lua boolean. The widget and
+/// `Unit*` predicates push the number 1 (`0x6f3810`) or nil (`0x6f37f0`); outside the base library
+/// (`rawequal`, `pcall`, `xpcall`), the one binding that calls `lua_pushboolean` (`0x6f39f0`) is
+/// `IsPetAttackActive` (`0x4be0e0`). Direct comparisons see it: stock `UIOptionsFrame.xml:310`
+/// saves `tostring(this:GetChecked())` and `BuffFrame.lua:71` compares it with `"1"`. The false
+/// leg is per binding: `IsEnabled` (`0x7800b0`) and numeric getters such as `UnitLevel`
+/// (`0x518144`) answer 0 and do not use this.
 pub(crate) fn flag(b: bool) -> Value {
     if b {
         Value::Integer(1)
@@ -401,22 +218,20 @@ mod tests {
         Lua::new()
     }
 
-    /// Every arm of `0x6f1c10`, including the three a plausible implementation gets backwards.
     #[test]
     fn bool_or_default_is_not_lua_truthiness() {
         let lua = lua();
         let st = |t: &str| Value::String(lua.create_string(t).unwrap());
 
-        // Absent takes the DEFAULT; an explicit nil is FALSE. The two are different arms.
+        // Absent takes the default; an explicit nil is false.
         assert!(bool_or_default(None, true));
         assert!(!bool_or_default(None, false));
         assert!(!bool_or_default(Some(&Value::Nil), true));
 
-        // Booleans pass through.
         assert!(bool_or_default(Some(&Value::Boolean(true)), false));
         assert!(!bool_or_default(Some(&Value::Boolean(false)), true));
 
-        // Numbers TRUNCATE toward zero — they do not round. `0.5` is off, not on.
+        // Numbers truncate toward zero: `0.5` is off.
         assert!(!bool_or_default(Some(&Value::Number(0.5)), true));
         assert!(!bool_or_default(Some(&Value::Number(-0.5)), true));
         assert!(!bool_or_default(Some(&Value::Number(-0.999)), true));
@@ -425,14 +240,13 @@ mod tests {
         assert!(!bool_or_default(Some(&Value::Integer(0)), true));
         assert!(bool_or_default(Some(&Value::Integer(7)), false));
 
-        // THE headline: `"0"` is FALSE, where Lua truthiness would say true.
+        // `"0"` is false, where Lua truthiness says true.
         assert!(!bool_or_default(Some(&st("0")), true));
         assert!(bool_or_default(Some(&st("1")), false));
-        // First byte only — `"0.5"` is false because it starts `'0'`, not because it truncates.
+        // First byte only: `"0.5"` is false because it starts with `'0'`.
         assert!(!bool_or_default(Some(&st("0.5")), true));
         assert!(bool_or_default(Some(&st("9lives")), false));
 
-        // The letter arms.
         for t in ["false", "F", "no", "NIL", "nope"] {
             assert!(
                 !bool_or_default(Some(&st(t)), true),
@@ -446,14 +260,14 @@ mod tests {
             );
         }
 
-        // The keyword arm, case-insensitive whole-string.
+        // The keyword arm, whole-string and case-insensitive.
         assert!(!bool_or_default(Some(&st("off")), true));
         assert!(!bool_or_default(Some(&st("OFF")), true));
         assert!(!bool_or_default(Some(&st("Disabled")), true));
         assert!(bool_or_default(Some(&st("on")), false));
         assert!(bool_or_default(Some(&st("ENABLED")), false));
 
-        // Unrecognised strings — and every byte the remap table cannot index — take the DEFAULT.
+        // Unrecognised strings, and every byte the remap table cannot index, take the default.
         for t in ["", "-1", "?", "maybe", "@"] {
             assert!(bool_or_default(Some(&st(t)), true), "{t:?} → default true");
             assert!(
@@ -462,7 +276,7 @@ mod tests {
             );
         }
 
-        // Table/function take the default arm, like an absent argument.
+        // A table takes the default, like an absent argument.
         let tbl = Value::Table(lua.create_table().unwrap());
         assert!(bool_or_default(Some(&tbl), true));
         assert!(!bool_or_default(Some(&tbl), false));
@@ -471,7 +285,6 @@ mod tests {
     #[test]
     fn number_arg_truncates_toward_zero_not_floor() {
         let lua = lua();
-        // `0x40a2b0` sets RC = chop before `fistp` — a C cast, not `floor`.
         assert_eq!(number_arg(&lua, Value::Number(2.9), "u").unwrap(), 2);
         assert_eq!(number_arg(&lua, Value::Number(-2.9), "u").unwrap(), -2);
         assert_eq!(number_arg(&lua, Value::Number(-0.5), "u").unwrap(), 0);
@@ -482,8 +295,7 @@ mod tests {
         let lua = lua();
         let s = lua.create_string("7").unwrap();
         assert_eq!(number_arg(&lua, Value::String(s), "u").unwrap(), 7);
-        // Missing and wrong-typed take the SAME arm: `0x6f3410` hands `0x6f34d0` a NULL for an
-        // absent argument, which reports "not a number" exactly as a table does.
+        // Missing and wrong-typed arguments take the same raise.
         for v in [Value::Nil, Value::Boolean(true)] {
             let err = number_arg(&lua, v, "Usage: Thing(n)").unwrap_err();
             assert!(format!("{err}").contains("Usage: Thing(n)"));
diff --git a/crates/benilla-ui/src/script/button.rs b/crates/benilla-ui/src/script/button.rs
index f1cc24f5..59188c70 100644
--- a/crates/benilla-ui/src/script/button.rs
+++ b/crates/benilla-ui/src/script/button.rs
@@ -1,21 +1,8 @@
-//! The `Button`/`CheckButton` method surface — per-kind behavior over the frame arena
-//! (`CSimpleButton` `0x6eeab0` / `CSimpleCheckbox` `0x6eeb30`).
-//!
-//! Grounded in the client's LoadXML table (`0x7788c0`): the four state textures
-//! (`Normal/Pushed/Disabled/Highlight`), the `ButtonText` fontstring + `text` attribute, the
-//! `OnClick` script slot (`+0x4cc`); CheckButton runs Button's loader first and adds
-//! `CheckedTexture`/`DisabledCheckedTexture` + the `checked` bool (`+0x4dc`). Which texture *shows*
-//! is **latched on the transition**, not resolved at paint: [`ButtonState::set_state`] is the
-//! client's `SetState 0x779790` and [`settle`] is where the derived inputs reach it. Two stated v1
-//! gaps: the highlight draws with normal blending (the client ADD-blends it; the quad pass has no
-//! blend modes yet), and `PushedTextOffset` is not modeled. Per-state label fonts *are*: the
-//! `*FontObject` trio picks which object each state inherits and `extract` re-resolves it every
-//! frame, while `SetFont` writes the button's own face/size/flags over all of them
-//! ([`crate::widget::ButtonFont`]).
-//!
-//! Method resolution: CheckButton's table is consulted first, then Button's, then the shared frame
-//! table — mirroring the client's class chain, and keeping duck-typing honest (`frame.SetChecked`
-//! is nil on a plain Button; `frame.GetText` is nil on a plain Frame).
+//! The `Button` and `CheckButton` methods (`CSimpleButton` `0x6eeab0`, `CSimpleCheckbox`
+//! `0x6eeb30`). The shown state texture latches at each state edge (`SetState` `0x779790`), not at
+//! paint. `<PushedTextOffset>` is not built: a pushed label does not shift.
+//! Lookup runs CheckButton's table, then Button's, then the frame table, the client's class chain,
+//! so `SetChecked` is nil on a plain Button and `GetText` on a plain Frame.
 
 use mlua::{Lua, MultiValue, ObjectLike, Table, Value};
 
@@ -32,7 +19,7 @@ use crate::widget::{
 pub(super) const REG_BUTTON_METHODS: &str = "__benilla_button_methods";
 pub(super) const REG_CHECKBUTTON_METHODS: &str = "__benilla_checkbutton_methods";
 
-/// The Button state-texture/text slots (each an arena region created on first set).
+/// A Button's texture and label slots, each an arena region created on first set.
 #[derive(Clone, Copy, PartialEq, Eq)]
 enum Slot {
     Normal,
@@ -57,10 +44,8 @@ impl Slot {
         }
     }
 
-    /// The three STATE slots go through [`ButtonState::set_state_slot`] — the client's
-    /// `0x778fd0` family, which stores the slot *and* pushes it to the shown pointer when it is
-    /// the current state's. Every other slot is a plain field: the highlight, the checked pair
-    /// and the label are not in the state array and have show rules of their own.
+    /// The three state slots go through [`ButtonState::set_state_slot`] (`0x778fd0`), which also
+    /// shows the texture when it is the current state's; the others are plain fields.
     fn set(self, bs: &mut ButtonState, rh: Option<crate::widget::RegionHandle>) {
         match self {
             Slot::Normal => bs.set_state_slot(ButtonVisualState::Normal, rh),
@@ -73,8 +58,8 @@ impl Slot {
         }
     }
 
-    /// The slot's region kind + default draw layer: state textures under the text, the highlight
-    /// in its own top layer (drawLayer table `0x811a84`), the checked marks above the state.
+    /// The region kind and default layer: state textures under the label, the highlight in its own
+    /// layer (the draw-layer table `0x811a84`), the checked marks above the state.
     fn shape(self) -> (RegionKind, DrawLayer) {
         match self {
             Slot::Normal | Slot::Pushed | Slot::Disabled => {
@@ -87,11 +72,8 @@ impl Slot {
     }
 }
 
-/// The NORMAL embedded font's justify word — `[button+0x390]` (`+0x33c`, the normal `CSimpleFont`,
-/// plus its `+0x54` justify cell): the element-level `<NormalFont justifyH=>` when the template
-/// wrote one (a local write on that instance, severed from what it inherits), else what the
-/// instance inherits from its font object, else the ctor default (CENTER). The word the label
-/// adopter anchors by — decision 1996.
+/// The normal font's justify (`[button+0x390]`): its own `<NormalFont justifyH=>`, else its font
+/// object's, else CENTER. The label adopter anchors by it.
 fn normal_font_justify(model: &Model, bs: &ButtonState) -> Justify {
     let mut word = Justify::default();
     let inherited = || {
@@ -106,19 +88,9 @@ fn normal_font_justify(model: &Model, bs: &ButtonState) -> Justify {
     word
 }
 
-/// `CSimpleButton::SetFontString 0x778d20`'s tail — the ONE path a button label enters by,
-/// whether `SetText` made it (`0x778dc0` allocates, then calls this) or Lua handed one over
-/// (`SetFontString`): anchor it to the button **only if it has no anchor of its own** and **by the
-/// NORMAL font's justify word** (`[button+0x390]`: LEFT→LEFT, RIGHT→RIGHT, else CENTER — never
-/// the string's own `+0x120`, which on a fresh string is the ctor's CENTER), then apply the
-/// button's per-state font to it on the spot (`0x779810`).
-///
-/// The word's source is the whole bug this fixes (decision 1996): a `UIMenuButtonTemplate` row
-/// has no `<ButtonText>` — its label is born from the reference's `UIMenu_AddButton` →
-/// `button:SetText(text)` — and its `<NormalFont inherits="GameFontNormal" justifyH="LEFT"/>` is
-/// the only thing that puts the label at the row's left edge. Reading the fresh string's own
-/// word instead seated every row CENTER, and with the shortcut string anchored RIGHT in a fixed
-/// 104-wide row, "Macro" ran into "/macro".
+/// `SetFontString`'s tail (`0x778d20`), which `SetText` also creates its label through
+/// (`0x778dc0`): an unanchored label anchors LEFT, RIGHT or CENTER by the normal font's justify,
+/// never its own (`+0x120`, CENTER on a fresh string), then takes the per-state font (`0x779810`).
 fn adopt_label(model: &mut Model, owner: FrameHandle, rh: RegionHandle) {
     let point = {
         let Some(frame) = model.arena.frame(owner) else {
@@ -133,34 +105,12 @@ fn adopt_label(model: &mut Model, owner: FrameHandle, rh: RegionHandle) {
     apply_normal_font(model, owner);
 }
 
-/// Point the ButtonText at the button's NORMAL font — object and local justify — so the label's
-/// *query* surface answers what its paint already shows. The live link the reference's per-state
-/// applier `0x779810` → `0x770c60` installs: the instance's field block flows onto the label
-/// behind the label's own severance mask.
-///
-/// Before this, the two disagreed. `extract` resolves the per-state font object every frame and
-/// overlays it onto a CLONE of the region's data (`extract.rs` l.114-122), so the label painted
-/// correctly while `region_data.font_object` stayed `None` — and a dropdown row's
-/// `GetFontObject()` answered **nil**, `GetFont()` answered **nil, nil**. Nothing errored: a
-/// FontString with no font of its own is a legal state, so this was invisible in exactly the way
-/// 1205's silent-drop class predicts.
-///
-/// The measured consequence is smaller than it first looks, and that is stated rather than implied.
-/// The corpus's 65 `GetFontObject` sites are on FontStrings the addon created and linked itself
-/// (Dewdrop-2.0 calls `text:SetFontObject(GameFontHighlightSmall)` one line before it reads the
-/// object back), so none of them were reaching this. What WAS reaching it is the reference's own
-/// `DropDownList1` OnLoad, which derives `UIDROPDOWNMENU_DEFAULT_TEXT_HEIGHT` from
-/// `DropDownList1Button1NormalText:GetFont()` and got nil.
-///
-/// **Normal only, deliberately.** The highlight and disabled objects are transient states that
-/// extract overlays at paint time; linking either here would make a resting button report its hover
-/// font. The remaining divergence, stated: while a button is disabled or hovered, the reference's
-/// label reports that state's font and ours still reports the normal one. The paint is unaffected
-/// either way, and no corpus site reads a label's font mid-state.
-///
-/// `font::repaint` honours the severance mask (`CSimpleFontString+0xd4`), so a `<FontHeight>` or
-/// `SetTextColor` the label set for itself survives the link, and the
-/// local justify goes behind the same mask.
+/// Link the label to the normal font object and local justify, the reference's `0x779810` →
+/// `0x770c60`, so its `GetFont` answers what it paints; the stock `DropDownList1` reads it
+/// (`UIDropDownMenu.xml:11`). Deviation: a hovered or disabled label still reports the normal
+/// font, since the state fonts are overlaid at paint and a link made here would outlive the state.
+/// `font::repaint` keeps what the label set itself (its severance mask, `CSimpleFontString+0xd4`),
+/// and the local justify obeys the same mask.
 fn apply_normal_font(model: &mut Model, owner: FrameHandle) {
     let (rh, name, local_justify) = {
         let Some(frame) = model.arena.frame(owner) else {
@@ -174,8 +124,7 @@ fn apply_normal_font(model: &mut Model, owner: FrameHandle) {
         };
         (rh, bs.normal_font.clone(), bs.normal_justify_h)
     };
-    // An unregistered name is not an error here: `SetTextFontObject` already accepted it, and the
-    // loader's own log-and-continue rule (0068) owns the reporting.
+    // An unregistered name is no error here: the setter accepted it and the loader reports it.
     let fo = name.as_deref().and_then(|n| model.font_object(n).cloned());
     let d = model.region_data.entry(rh).or_default();
     match (&name, fo) {
@@ -202,14 +151,9 @@ pub(crate) enum LabelFont {
     Disabled,
 }
 
-/// `<NormalFont justifyH=>` / `<HighlightFont justifyH=>` / `<DisabledFont justifyH=>` — the
-/// loader-facing write of a per-state embedded font's own justify (`CSimpleButton::LoadXML
-/// 0x7788c0` → the `<Font>` loader `0x783c30` on `+0x33c`/`+0x3b8`/`+0x434`: a `<Font>`-typed
-/// element, so the attribute lands on the instance itself, severed from whatever it inherits).
-/// No 1.12 Lua verb writes this — the API trio sets the OBJECT each instance inherits, never its
-/// local fields — which is why it is crate-internal rather than a method. A label already
-/// adopted keeps its anchor (the reference decided that at adoption) while its own justify word
-/// follows the normal instance, as the live link propagates the write.
+/// The loader's `<NormalFont justifyH=>` and kin: `LoadXML` (`0x7788c0`) runs the `<Font>` loader
+/// (`0x783c30`) on the embedded font, so the justify is its own, not inherited; no Lua verb
+/// writes it. An adopted label keeps its anchor and takes the new normal justify.
 pub(crate) fn set_label_font_justify_h_lua(
     lua: &Lua,
     wrapper: &Table,
@@ -229,14 +173,8 @@ pub(crate) fn set_label_font_justify_h_lua(
     Ok(())
 }
 
-/// Run `f` over a frame's Button state under one short write borrow.
-///
-/// **It no longer settles a state machine afterwards, because there is no longer one to settle**
-/// (decision 2134). The button's state is a latch the engine's own edges write; a Lua write moves
-/// it only when the write IS an edge (`Enable`/`Disable`, `SetButtonState`), and those call the
-/// edge themselves. `RegisterForClicks` and the texture setters no longer disturb the state at
-/// all — which is the reference's behaviour: re-registering a held button's clicks does not
-/// un-press it.
+/// Run `f` over a frame's Button state under one short write borrow. It moves no state, only an
+/// edge does: re-registering a held button's clicks does not un-press it, as in the reference.
 fn with_button<T>(
     lua: &Lua,
     this: &Table,
@@ -254,53 +192,11 @@ fn with_button<T>(
     }
 }
 
-/// `Enable()` / `Disable()` — and the second thing they do, which is not the state texture.
-///
-/// `Disable 0x77ffd0` ends `0x78009a call [vtbl+0x90](0)`, reaching the shared helper
-/// `0x779160`; the constructor reaches the same helper with `1` (`0x778766`), which is what puts
-/// a fresh button in NORMAL. That helper does **two** things:
-///
-/// - `[vtbl+0x9c](state, 0)` = `SetButtonState 0x779790` — [`ButtonState::set_enabled`]'s half,
-///   whose two early-outs (nothing happens if the button is already in the state being asked for)
-///   are the helper's own; and
-/// - `0x7791bb push 4; call 0x76a730` — the per-layer enable for layer **4 = HIGHLIGHT**, written
-///   into the very `[frame+0x198]` array that `Enable/DisableDrawLayer` writes and that
-///   `0x76b3a0` reads back at draw time.
-///
-/// So a disabled button's highlight is switched off **at the layer**, which takes every region
-/// the frame owns there with it — not only the HighlightTexture. That is why the highlight is no
-/// longer gated on `enabled` inside [`ButtonState::region_visible`]: one mechanism, in the place
-/// the client keeps it, instead of a second rule that agreed with it on the common case and
-/// disagreed on `<Layer level="HIGHLIGHT">` art the button did not put there itself.
-///
-/// **The restore is NOT symmetric, and this comment used to claim it was** — *"one array and one
-/// writer, so an addon's `DisableDrawLayer("HIGHLIGHT")` is undone by the next `Enable()`"*. Both
-/// halves are false (`0x779160`). The indexed form
-/// `[reg + 4*reg + 0x198]` has **three** sites image-wide — `0x76a717` (=1), `0x76a737` (=0) and
-/// `DrawLayer 0x76b3a6`'s read — so there are **two** writers; and the enable arm calls
-/// *neither* helper. It reaches the ON one only one hop away and only when the button is the
-/// frame under the cursor:
-///
-/// ```text
-/// 779183  mov ecx,[esi+0xa0]   ; the CSimpleTop singleton
-/// 779189  cmp esi,[ecx+0x7c]   ; am I the hover target?
-/// 77918c  jne 0x7791ce         ;   no -> return, layer untouched
-/// 779192  call [edx+0x4c]      ; = 0x779490 -> 0x76b6a0 -> 0x76b6c9 push 4; call 0x76a710
-/// ```
-///
-/// — i.e. `Enable()` on a hovered button restores the layer **by re-running the frame's Lua
-/// `<OnEnter>`**, and on a non-hovered one restores nothing (the next hover-enter does it). Both
-/// restore paths are gated on the LockHighlight flag `[frame+0xf8]`, and the disable arm's
-/// `0x7791bb call 0x76a730(4)` is the one site in the image that is *not* — so
-/// `LockHighlight()` → `Disable()` → `Enable()` leaves the layer off in the reference, and only
-/// `UnlockHighlight()`+`LockHighlight()` or an explicit `EnableDrawLayer` brings it back.
-///
-/// **Ours is the symmetric bit-flip**, which draws the same in the ordinary case — a highlight is
-/// only visible while hovered, and every hover-enter sets it — and diverges in two script-visible
-/// ways: we do not fire the `<OnEnter>` the reference synthesises when you `Enable()` a hovered
-/// button, and we restore a locked-then-disabled highlight the reference leaves dark. Named here
-/// rather than fixed, because the faithful shape needs the layer restore moved onto the hover
-/// path where the reference keeps it.
+/// `Enable()`/`Disable()`. `Disable` (`0x77ffd0`) reaches `SetEnabled` (`0x779160`), which also
+/// turns draw layer 4, HIGHLIGHT, off (`0x7791bb`) in the array `DisableDrawLayer` writes, so every
+/// region in that layer goes dark, not only the HighlightTexture. `Enable()` here turns it back
+/// on; the reference restores it only on a hovered button, by re-running its `<OnEnter>`
+/// (`0x779183`), and never while `LockHighlight` holds (`[frame+0xf8]`).
 fn set_enabled(lua: &Lua, this: &Table, on: bool) -> mlua::Result<()> {
     let h = frame_handle_of(lua, this)?;
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -308,9 +204,6 @@ fn set_enabled(lua: &Lua, this: &Table, on: bool) -> mlua::Result<()> {
         .arena
         .frame_mut(h)
         .ok_or_else(|| mlua::Error::runtime("stale frame handle"))?;
-    // The state half is [`ButtonState::set_enabled`], whose two early-outs are the client's:
-    // `Enable()` on a button that is not DISABLED does nothing at all, and neither does
-    // `Disable()` on one that already is.
     match &mut frame.kind_state {
         KindState::Button(bs) => bs.set_enabled(on),
         _ => return Err(mlua::Error::runtime("not a Button")),
@@ -324,15 +217,9 @@ fn set_enabled(lua: &Lua, this: &Table, on: bool) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Run one of the engine's own state edges over frame `h`, if it is a live Button.
-///
-/// The reference's edge set is exactly seven `SetButtonState 0x779790` call sites and **six of
-/// them are engine-side**: Enable, Disable, the hide
-/// notify, mouse-down, mouse-up and the drag-threshold crossing. There is **no enter or leave
-/// edge** — which is why the pointer path no longer calls anything here when the cursor crosses a
-/// button's boundary (decision 2134).
-///
-/// Harmless on a non-Button handle, and on a stale one.
+/// Run an engine state edge over frame `h` if it is a live Button. The reference has six, all of
+/// `0x779790`'s call sites but Lua's: enable, disable, hide, press, release and drag start; the
+/// cursor entering or leaving a button is not one.
 pub(super) fn edge(model: &mut Model, h: FrameHandle, f: impl FnOnce(&mut ButtonState)) {
     if let Some(frame) = model.arena.frame_mut(h) {
         if let KindState::Button(bs) = &mut frame.kind_state {
@@ -341,37 +228,12 @@ pub(super) fn edge(model: &mut Model, h: FrameHandle, f: impl FnOnce(&mut Button
     }
 }
 
-/// Does a hover edge on frame `h` reach the **base** enter/leave notify — the HIGHLIGHT layer and
-/// the Lua `<OnEnter>`/`<OnLeave>` script slots — or is it swallowed on the way there?
-///
-/// `CSimpleButton::OnEnter 0x779490` and `OnLeave 0x7794e0` both open on the state word, and the
-/// branch skips the *whole* body except the sound:
-///
-/// ```text
-/// 779493  mov eax,[esi+0x328]
-/// 779499  test eax,eax
-/// 77949b  je 0x7794b0          ; DISABLED -> skip the base notify AND the label restyle
-/// 77949d  call 0x76b6a0        ; CSimpleFrame::OnEnter — highlight layer on, <OnEnter> at +0x140
-/// ```
-///
-/// — so **a DISABLED Button runs neither script**, and `0x7794b0`'s hover sound is the only thing
-/// past the branch; the base pair's
-/// script slots are `+0x140`/`+0x148`. Every path that delivers a hover
-/// edge dispatches through the object's own vtable, so there is no way around the guard: the hover
-/// walk (`0x766218`–`0x76623c`, `[vt+0x50]` then `[vt+0x4c]`), `SetMouseFocus 0x764dc0`
-/// (`0x764ddd push 0`), and the hide/removal tail (`0x764cce mov edx,[edi]; push 1;
-/// call [edx+0x50]`). `CheckButton` inherits both slots; the Hyperlink and NamePlate buttons
-/// override them and tail straight back into this pair (`0x7cb8a5`), so the guard covers the
-/// family.
-///
-/// The hover **target** still moves — the walk reassigns `[root+0x7c]` *before* it fires either
-/// notify — so `GetMouseFocus()` answers a disabled button; it is the scripts alone that stay
-/// quiet. This is what makes AtlasLoot's unset QuickLook buttons safe on the reference: their
-/// `<OnEnter>` guards with `if this:IsEnabled() then`, which is a NUMBER `1`/`0` and therefore
-/// always truthy (`IsEnabled 0x7800b0`), so the body would index a nil
-/// `QuickLooks[n]` — the reference never runs it at all.
-///
-/// `None` (the cursor over no frame) and every non-Button kind notify normally.
+/// Whether a hover edge on `h` reaches the base notify, the HIGHLIGHT layer and the Lua
+/// `<OnEnter>`/`<OnLeave>`: `OnEnter`/`OnLeave` (`0x779490`/`0x7794e0`) skip it on a DISABLED
+/// Button, leaving only the hover sound (`0x7794b0`). Every hover path goes through that pair
+/// (the hover walk `0x766218`, `SetMouseFocus` `0x764dc0`, the hide tail `0x764cce`), and the
+/// Hyperlink and NamePlate overrides chain back (`0x7cb8a5`). The hover target still moves, so
+/// `GetMouseFocus()` answers a disabled button.
 pub(super) fn hover_notify_runs(model: &Model, h: Option<FrameHandle>) -> bool {
     let Some(h) = h else { return true };
     match model.arena.frame(h).map(|f| &f.kind_state) {
@@ -380,8 +242,7 @@ pub(super) fn hover_notify_runs(model: &Model, h: Option<FrameHandle>) -> bool {
     }
 }
 
-/// Write [`ButtonState::loot_slot`] — `LootButton:SetSlot`'s whole body, kept here beside the
-/// other `ButtonState` writers rather than reaching into the arena from `script::loot`.
+/// `LootButton:SetSlot`: writes [`ButtonState::loot_slot`].
 pub(super) fn set_loot_slot(lua: &Lua, this: &Table, slot: Option<u32>) -> mlua::Result<()> {
     let h = frame_handle_of(lua, this)?;
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -394,9 +255,7 @@ pub(super) fn set_loot_slot(lua: &Lua, this: &Table, slot: Option<u32>) -> mlua:
             bs.loot_slot = slot;
             Ok(())
         }
-        // The reference's own guard: `SetSlot` type-checks `this` against the LootButton tag via
-        // vtable slot 4 (`0x4c18ee`), so calling it on a plain Button raises rather than writing a
-        // field nothing would ever read.
+        // `SetSlot` type-checks `this` as a LootButton (`0x4c18ee`) and raises on anything else.
         _ => Err(mlua::Error::runtime(
             "SetSlot: 'this' is not a LootButton widget",
         )),
@@ -424,9 +283,10 @@ fn ensure_slot(lua: &Lua, this: &Table, slot: Slot) -> mlua::Result<u32> {
                 .arena
                 .create_region(h, kind, layer, 0)
                 .ok_or_else(|| mlua::Error::runtime("stale frame handle"))?;
-            // The highlight draws ADD by contract (the live API's SetHighlightTexture default
-            // blend; highlight art is authored for it — under straight alpha it reads as a
-            // dark box over the icon).
+            // A new highlight blends ADD, `SetHighlightTexture`'s default (`0x781d92`). The
+            // reference applies that mode, or a third argument's, on every call and to a handed-in
+            // Texture too (`0x7703f0` from `0x779050` and `0x779110`); here only a new region
+            // takes it.
             model.region_data.insert(
                 rh,
                 RegionData {
@@ -438,20 +298,14 @@ fn ensure_slot(lua: &Lua, this: &Table, slot: Slot) -> mlua::Result<u32> {
                     ..Default::default()
                 },
             );
-            model.touch_layout(); // a region entered the layout gate's read set (decision 0740)
+            model.touch_layout(); // a region entered the layout gate's read set
             if let Some(frame) = model.arena.frame_mut(h) {
                 if let KindState::Button(bs) = &mut frame.kind_state {
                     slot.set(bs, Some(rh));
                 }
             }
-            // A freshly built slot region gets its creation-path implicit anchor (decision 1310)
-            // — an EXISTING slot region is never touched here; the get half of get-or-create
-            // changes no geometry. Which anchor depends on the slot: the reference's C++ string
-            // setters SetAllPoints a fresh state texture outright (`0x778f9d`/`0x7790db` — fresh
-            // means zero anchors, so the conditional form is equivalent), while a fresh LABEL is
-            // handed to the adopter (`SetText 0x778dc0` → `0x778d20`), which anchors it by the
-            // button's normal font and links it (decision 1996). The XML loader re-derives after
-            // applying authored `<Anchors>` (see `loader/widgets.rs`).
+            // Only a new region gets an implicit anchor: a state texture fills the button
+            // (`0x778f9d`/`0x7790db`), a label goes to the adopter (`0x778dc0` → `0x778d20`).
             match slot {
                 Slot::Text => adopt_label(&mut model, h, rh),
                 _ => super::region::implicit_creation_anchor(&mut model, rh),
@@ -462,9 +316,8 @@ fn ensure_slot(lua: &Lua, this: &Table, slot: Slot) -> mlua::Result<u32> {
     Ok(model.region_id(rh))
 }
 
-/// Point `slot` at `rh` (or at nothing) and hand back whatever it held before, when that is a
-/// different region. The reference's slot store `0x778fd0` ends in the outgoing object's
-/// vtable-slot-0 dtor, so the caller frees it.
+/// Point `slot` at `rh` or at nothing, returning the different region it held for the caller to
+/// free, as the slot store `0x778fd0` destroys the outgoing object.
 fn swap_slot(
     model: &mut Model,
     h: FrameHandle,
@@ -484,7 +337,7 @@ fn swap_slot(
     Ok(outgoing)
 }
 
-/// Free the region a slot just gave up — never the one that just moved in.
+/// Free the region a slot gave up, never the one that moved in.
 fn free_outgoing(lua: &Lua, outgoing: Option<RegionHandle>, incoming: RegionHandle) {
     if let Some(old) = outgoing.filter(|old| *old != incoming) {
         super::region::free_region(
@@ -494,26 +347,18 @@ fn free_outgoing(lua: &Lua, outgoing: Option<RegionHandle>, incoming: RegionHand
     }
 }
 
-/// The shared body of `Set<State>Texture(texture | "path" | nil)` / `(r, g, b [, a])`.
-///
-/// The reference forks on `lua_type(L, 2)` into four legs (`0x781970`).
-/// **Two of them never touch the
-/// slot's own region at all**, so they are resolved *before* [`ensure_slot`] — which would
-/// otherwise lazily build a region for a call whose entire purpose is to replace or drop one.
+/// `Set<State>Texture(texture | "path" | nil)`, forked on the argument's type (`0x781970`). The
+/// object and nil legs never touch the slot's own region, so they run before [`ensure_slot`]
+/// would create one. The `(r, g, b [, a])` form is not 1.12's, which reads a number as a path
+/// (`0x781b23`).
 fn set_slot_texture(lua: &Lua, this: &Table, slot: Slot, args: &MultiValue) -> mlua::Result<()> {
     match args.front() {
-        // **A widget object installs THAT region into the slot** (`0x781b0b`: `push the Texture
-        // object; push idx; call 0x778fd0`) — it does not load a path into the slot's own region.
-        // Three corpus addons build a highlight exactly this way and every one of them was a
-        // silent no-op here: Bongos' bar-drag button (`bar.lua:64-71`), _Nameplates' mouseover
-        // glow (`_Nameplates.lua:217-222`) and Quiver's option rows (`Quiver.bundle.lua:8949-53`)
-        // each `CreateTexture` on the button, colour it, `SetAllPoints`, and hand it over.
+        // A Texture object is itself installed into the slot (`0x781b0b` → `0x778fd0`).
         Some(Value::Table(t)) => {
             let rh = super::region::region_handle_of(lua, t)?;
             let h = frame_handle_of(lua, this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // The reference type-checks the handed object and raises rather than installing a
-            // FontString into a texture slot (`0x781ab1`, `0x87a1e0`).
+            // Any other widget raises (`0x781ab1`, message `0x87a1e0`).
             if model.arena.region(rh).map(|r| r.kind) != Some(RegionKind::Texture) {
                 return Err(mlua::Error::runtime("Wrong object type, expected texture"));
             }
@@ -522,15 +367,9 @@ fn set_slot_texture(lua: &Lua, this: &Table, slot: Slot, args: &MultiValue) -> m
             free_outgoing(lua, outgoing, rh);
             return Ok(());
         }
-        // **nil CLEARS the slot** (`0x781b5a`: `push 0; push idx; call 0x778fd0`, whose tail runs
-        // the outgoing object's dtor). Clearing the pointer alone would be worse than doing
-        // nothing: `ButtonState::region_visible` shows any region that is not one of the button's
-        // own slots unconditionally, so an unhooked state texture would start drawing in *every*
-        // state instead of none. `TheoryCraft/TheoryCraftUI.lua:215-217` strips a talent-rank
-        // button's normal/pushed/highlight art with three of these.
-        //
-        // A call with NO argument is left alone: `LUA_TNONE` is not `LUA_TNIL`, and the
-        // reference's own nil test is `0x781b4f call 0x6f3400 == 0`.
+        // nil clears the slot and destroys the old region (`0x781b5a` → `0x778fd0`): unhooked but
+        // alive, it would draw in every state. No argument is not nil (`0x781b4f`) and clears
+        // nothing.
         Some(Value::Nil) => {
             let h = frame_handle_of(lua, this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -552,9 +391,7 @@ fn set_slot_texture(lua: &Lua, this: &Table, slot: Slot, args: &MultiValue) -> m
     let rh = *model.id_to_region.get(&id).expect("slot region id");
     let data = model.region_data.entry(rh).or_default();
     match args.front() {
-        // `Set<State>Texture("")` CLEARS — the live API's blank form (ref QuestLogFrame.lua:165
-        // clears the quest rows' +/- slot with exactly this), same as SetTexture(nil)/("") on a
-        // plain region.
+        // `""` clears the texture, which `QuestLogFrame.lua:165` relies on.
         Some(Value::String(s)) if s.to_str()?.is_empty() => {
             data.texture = None;
             data.fill = None;
@@ -563,8 +400,7 @@ fn set_slot_texture(lua: &Lua, this: &Table, slot: Slot, args: &MultiValue) -> m
             data.texture = Some(s.to_str()?.to_string());
             data.fill = None;
         }
-        // The colour form generates a solid texture into the same slot the path form loads into
-        // ([`RegionData::fill`]) — never a tint, so each clears the other.
+        // The colour form is a solid texture, not a tint: it and the path clear each other.
         Some(v @ (Value::Number(_) | Value::Integer(_))) => {
             let arg = |i: usize| args.get(i).map(as_f32);
             data.fill = Some([
@@ -580,7 +416,7 @@ fn set_slot_texture(lua: &Lua, this: &Table, slot: Slot, args: &MultiValue) -> m
     Ok(())
 }
 
-/// The shared body of `Get<State>Texture` — the region wrapper, or nil while unset.
+/// `Get<State>Texture`: the region wrapper, or nil while unset.
 fn get_slot_texture(lua: &Lua, this: &Table, slot: Slot) -> mlua::Result<Value> {
     let rh = with_button(lua, this, |bs| slot.get(bs))?;
     let id = {
@@ -616,17 +452,13 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     texture_pair(lua, &m, "Disabled", Slot::Disabled)?;
     texture_pair(lua, &m, "Highlight", Slot::Highlight)?;
 
-    // SetText/GetText target the ButtonText fontstring (`0x778dc0`: the `text` attr routes there).
+    // SetText/GetText go to the ButtonText fontstring, as the `text` attribute does (`0x778dc0`).
     m.set(
         "SetText",
         lua.create_function(|lua, (this, text): (Table, Option<Value>)| {
             let text = super::binding_abi::text_arg(lua, text)?;
-            // `CSimpleButton::SetText 0x778dc0` opens `if (!text) return;` (`0x778dcc`) — a nil
-            // never reaches the label at all, so
-            // it neither clears the text nor lazily creates the FontString. That guard is the
-            // BUTTON's own: a `FontString:SetText(nil)` is not a no-op, it truncates the cell
-            // (`0x771d80`, decision 2110). Below the guard the button is a pass-through to
-            // `[button+0x338]->0x771d80`.
+            // A nil returns at once (`0x778dcc`): no clear, no label created. The guard is the
+            // button's own; `FontString:SetText(nil)` clears (`0x771d80`).
             let Some(text) = text else { return Ok(()) };
             let id = ensure_slot(lua, &this, Slot::Text)?;
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -636,10 +468,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // GetText — like the FontString's own (`region::text`, decision 2110), an **empty label reads
-    // back nil**: `Button:GetText 0x780e10` carries the same first-byte substitution at `0x780ec5`,
-    // over three nil conditions rather than two (no label region, a NULL cell, an empty cell).
-    // Its EditBox neighbour deliberately does not — the law is per binding.
+    // GetText (`0x780e10`): nil for no label, and for an empty one (`0x780ec5`).
     m.set(
         "GetText",
         lua.create_function(|lua, this: Table| {
@@ -661,50 +490,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, this: Table| get_slot_texture(lua, &this, Slot::Text))?,
     )?;
 
-    // SetFontString(fontString) — ADOPT a caller-made FontString as this Button's label.
-    //
-    // End to end (decision 1505): the binding `0x780a60` is gates + a delegate to
-    // `CSimpleButton::SetFontString 0x778d20`, which is the SAME function `SetText`'s lazy creation
-    // path funnels through — so adopting and creating share their whole tail, and only the
-    // allocation differs.
-    //
-    // The idiom it exists for: build the label yourself so you can style and place it, then hand
-    // it to the button so `SetText` and the per-state font machinery drive it. Quiver's
-    // `Component/Select.wow.lua` builds every dropdown option row that way, and with the method
-    // nil the row died on its first line — the second of B267's three walls.
-    //
-    // **It raises, in three distinct ways, and never silently no-ops on a bad argument** — the
-    // first shape I built here was a lenient no-op and the bytes say otherwise:
-    //
-    //  · a **missing** argument, `nil`, a number, a string or a boolean → `lua_type(L,2) != TABLE`
-    //    → `Usage: %s:SetFontString(fontstring)` (`0x87a100`). Missing and nil take the identical
-    //    leg (`index2adr` answers NULL → type −1), so `SetFontString(nil)` **cannot clear the
-    //    label from Lua**; the C++ clear exists but no binding reaches it.
-    //  · a **table that is not a widget** → `%s:SetFontString(): Couldn't find 'this' in
-    //    fontstring` (`0x87a160`).
-    //  · a **Frame or a Texture** — anything that is not a FontString → `%s:SetFontString():
-    //    Wrong object type, expected fontstring` (`0x87a124`), gated by an `IsA` against the
-    //    FontString token, which a Texture fails.
-    //
-    // `%s` is the BUTTON's name (or `<unnamed>`), never the argument's. Zero return values.
-    //
-    // What `0x778d20` then does, all four clauses VERIFIED and all four here:
-    //
-    //  · **`new == old` is a total no-op** — the first compare, before anything is touched.
-    //  · **the previous label is DESTROYED**, not orphaned (`old->vtable[0](1)`, the scalar
-    //    deleting destructor, returning the storage to the FontString pool). So a button whose
-    //    `SetText` already lazily made one does not leak a stray string behind the new label.
-    //  · **the string is RE-PARENTED to the button and its draw layer forced to ARTWORK**
-    //    (`0x77fd10(parent, 2, 1)` — layer id 2 in the client's own `.rdata 0x811a80` name table).
-    //    Always, whatever it was parented to or drawn in before.
-    //  · **it is anchored only if it has NO anchors of its own** (a scan of all nine
-    //    `anchorPoints` slots): LEFT/RIGHT/CENTER by the justify bits of the **button's normal
-    //    font** (`[button+0x390]`), to the matching point on the button — [`adopt_label`], the
-    //    same `& 7` → LEFT(1)/RIGHT(4)/else-CENTER chain the FontString post-step runs, over the
-    //    other word. (It used to reuse the post-step and read the string's own word; the two
-    //    only agree when the normal font has no justify — decision 1996.)
-    //  · **the button's per-state font is applied immediately** (`0x779810`) — the same
-    //    [`adopt_label`] links the label to the normal font, so its query surface answers.
+    // SetFontString(fontString) (`0x780a60` → `0x778d20`) raises, naming the button, on a
+    // non-table (`0x87a100`), nil included, so Lua cannot clear the label; on a non-widget
+    // (`0x87a160`); on a non-FontString (`0x87a124`). The same label is a no-op; otherwise the old
+    // one is destroyed and the new one moves to the button at ARTWORK (`0x77fd10`) and is adopted.
     m.set(
         "SetFontString",
         lua.create_function(|lua, args: MultiValue| {
@@ -727,11 +516,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     "Usage: {who}:SetFontString(fontstring)"
                 )));
             };
-            // The two remaining legs are DIFFERENT questions and the reference asks them in this
-            // order: first "is this a framescript object at all" (`0x780b27`), then "is it a
-            // FontString" (`0x780b90`'s `IsA` against the FontString token). A Frame or a Texture
-            // passes the first and fails the second — so resolving straight to a region handle
-            // would collapse both onto the first message and mislabel every widget argument.
+            // Two checks in the reference's order, a widget at all (`0x780b27`), then a FontString
+            // (`0x780b90`), so a Frame or a Texture gets the second message.
             let rh = {
                 let not_an_object = || {
                     mlua::Error::runtime(format!(
@@ -767,8 +553,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             with_button(lua, &this, |bs| bs.text = Some(rh))?;
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
             if let Some(dead) = old {
-                // DESTROYED, not orphaned — the shared region-lifetime law, whose doc carries the
-                // reason (`0x778d3c`'s scalar deleting destructor).
+                // Destroyed, not orphaned (`0x778d3c`).
                 super::region::free_region(&mut model, dead);
             }
             model.arena.set_region_owner(rh, Some(owner));
@@ -776,41 +561,20 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 r.draw_layer = DrawLayer::Artwork;
             }
             adopt_label(&mut model, owner, rh);
-            // A new label, a new owner and a possible new anchor — the layout's read set moved,
-            // and the string's extents are what the button's own `GetTextWidth` reports.
+            // The layout's read set moved, and `GetTextWidth` reads the new label's extents.
             model.touch_layout();
             model.touch_measure(rh);
             Ok(())
         })?,
     )?;
 
-    // GetTextWidth / GetTextHeight — the Button's OWN text-extent readers (`0x782290` /
-    // `0x782390`); both are present on Button's own method table, `GetStringWidth` is not.
-    // Both are thin forwards onto the label FontString's own extent vtable slots
-    // (`0x1c` / `0x20`), which is exactly what this delegation is.
-    //
-    // **Who asks.** `Bagnon_Forever/database/ui.lua:61` sizes its character-switch dropdown from
-    // `button:GetTextWidth() + 40` over every saved character — with the method nil the whole
-    // dropdown died on the first row, so the director could not switch characters in Bagnon at all.
-    // The idiom generalises: it is how a 1.12 kit fits a button to its label, and the reference's
-    // own `MoneyFrame.lua` l.202 (`SetWidth(GetTextWidth() + iconWidth)`) is the same shape.
-    //
-    // **Which measurement**, since a FontString carries two. The label's `GetStringWidth` — the
-    // NATURAL, unwrapped extent — never the laid-out `GetWidth`. A button label does not wrap, so
-    // the two agree in the ordinary case; where they differ, serving the laid-out width would hand
-    // every "size the button to its text" caller its own previous output as its next input, which
-    // is decision 0997's measured feedback loop (the macro window's tab that changed width every
-    // frame). The unwrapped extent is the one that settles.
-    //
-    // `0` before the host has measured the string (a frame's latency, as everywhere else), and `0`
-    // for a Button with no label at all — the reference dereferences its FontString pointer `+0x338`
-    // here where `SetFont`/`GetFont` deliberately do not, and what a null one does is NOT byte-read,
-    // so this answers the harmless number rather than raising on a guess.
+    // GetTextWidth/GetTextHeight (`0x782290`/`0x782390`) forward to the label's extents (vtable
+    // `0x1c`/`0x20`). The width is the natural, unwrapped one: the laid-out width would feed a
+    // size-to-text caller (`MoneyFrame.lua:202`) its own output. 0 before measurement and with no
+    // label, where the reference dereferences `+0x338` and what it does on null is untraced.
     for (name, region_getter) in [
         ("GetTextWidth", "GetStringWidth"),
-        // `GetHeight`, not a `GetStringHeight` — 1.12 has no such method (byte-verified absent
-        // in every encoding), and the reference's own `Button:GetTextHeight 0x782390` is this
-        // same call on the embedded FontString rather than a separate API.
+        // 1.12 has no `GetStringHeight`; `0x782390` reads the label's height.
         ("GetTextHeight", "GetHeight"),
     ] {
         m.set(
@@ -825,17 +589,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // The per-state label fonts (the 1.12 API trio; XML `<NormalFont>/<HighlightFont>/
-    // <DisabledFont>` route here through the loader). Stored as font-object NAMES — extract
-    // re-points the ButtonText to the current state's object each frame, so Enable/Disable and
-    // hover swap the label's paint with no Lua involvement (the client's own behavior:
-    // UIPanelButtonTemplate's gold/white/gray label states).
-    //
-    // Each takes the font OBJECT, its name, or nil, like `FontString:SetFontObject` — across the
-    // trio the corpus splits 5 object-form to 4 string-form, so accepting one shape only would
-    // break about half the callers, and nil clears the state back to the default. Because the
-    // state is stored as a NAME and re-resolved at every `extract`, a later mutation of that font
-    // object reaches these labels for free.
+    // The per-state label fonts, and `<NormalFont>` and kin through the loader. Each takes a font
+    // object, its name or nil, stored by name: extract re-resolves the current state's font every
+    // frame, so a state change or a later edit to the object reaches the label.
     m.set(
         "SetTextFontObject",
         lua.create_function(|lua, (this, font): (Table, Value)| {
@@ -862,30 +618,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetFont(file, height [, flags]) / GetFont() — the Button's own font, `0x780880`/`0x79f3b0`.
-    // `_LazyPig/LazyPigMenu.lua:214` calls it straight on a `CreateFrame("Button", …)`, and it is
-    // that addon's only blocker.
-    //
-    // Three contract details, each a plausible implementation's silent divergence:
-    //
-    //  · **It returns ZERO values.** The shared impl `0x79f210` pushes `1`/nil (a real font-load
-    //    probe on a Font object — `!OmniCC` uses it), but `Button:SetFont` DISCARDS it
-    //    (`xor eax,eax`), so a failed font load is undetectable from a Button. Returning `true`
-    //    here would look harmless and would hand an addon a probe the client does not have.
-    //  · **It never touches the label.** `SetFont`/`GetFont` do not dereference the FontString
-    //    pointer `+0x338` at all, so styling a bare `CreateFrame("Button")` with no `<ButtonText>`
-    //    is no error, no crash and **no lazy creation** — which is why the style is stored on the
-    //    button ([`ButtonState::font`]) and `extract` applies it to whatever label exists. A later
-    //    `SetText` (which *does* lazily create one, `0x778dc0`) then picks it up, so either call
-    //    order works, exactly as the reference's does.
-    //  · **It retunes all three embedded fonts** (normal `+0x33c`, disabled `+0x434`, highlight
-    //    `+0x3b8`) and `GetFont` reads back only the normal one — see [`ButtonFont`] for why one
-    //    record is the faithful shape for three identical writes.
-    //
-    // The argument gate is the shared impl's: arg2 `lua_isstring` and arg3 `lua_isnumber`, else
-    // `luaL_error("Usage: %s:SetFont(\"font\", fontHeight [, flags])")` (`0x87c69c`). Both
-    // predicates are the *coercing* ones in 5.0 — `lua_isstring` takes a number, `lua_isnumber`
-    // takes a numeric string — so the leniency is transcribed rather than tightened.
+    // SetFont(file, height [, flags]) (`0x780880`) sets all three embedded fonts and returns
+    // nothing, discarding the shared `0x79f210`'s load result. It never touches the label
+    // (`+0x338`), so creates none: extract applies the stored font to whatever label exists. Its
+    // checks are 5.0's coercing `lua_isstring`/`lua_isnumber`, else a usage error (`0x87c69c`).
     m.set(
         "SetFont",
         lua.create_function(
@@ -915,15 +651,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                         flags,
                     })
                 })
-                // …and nothing is returned: `with_button` yields `()`.
             },
         )?,
     )?;
-    // GetFont() → file, height, flags — **3 values**, read off the NORMAL embedded font. Unset
-    // locally, that font still resolves through what the normal state inherits
-    // (`<NormalFont>`/`SetTextFontObject`), which is how a `GameMenuButtonTemplate` button answers
-    // GameFontNormal's face before anything calls `SetFont`. Nil path / nil height when neither
-    // exists, still 3 values.
+    // GetFont() (`0x7809a0` → `0x79f3b0`) → file, height, flags off the normal font, else the
+    // object it inherits (`<NormalFont>`, `SetTextFontObject`); always three values.
     m.set(
         "GetFont",
         lua.create_function(|lua, this: Table| {
@@ -952,10 +684,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The per-state label COLORS (Button:SetTextColor + the Highlight/Disabled pair): the state's
-    // color, when set, repaints the ButtonText over the state font object's paint at extract —
-    // the dropdown kit's rows use all three (info.textR/G/B rows, isTitle's NORMAL-yellow and
-    // notClickable's HIGHLIGHT-white recolors of a disabled row).
+    // The per-state label colours: a set one paints over the state font's colour at extract.
     m.set(
         "SetTextColor",
         lua.create_function(
@@ -972,25 +701,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             },
         )?,
     )?;
-    // GetTextColor() → r, g, b, a — **FOUR values** (`0x781100`, table `0x879d00`, argc 1, arity 4,
-    // kinds `(number,number,number,number)`), the same shape as the FontString/Font-object twins
-    // (`0x79d840` table `0x87c1d8`, `0x79f680`) this codebase already answers. Three is the
-    // plausible wrong answer, and the shapes table calls the name `name-not-unique` precisely
-    // because it is registered on seven tables; this is the Button one.
-    //
-    // **Read like `GetFont` right above, not like `SetTextColor` right above that.** The reference
-    // reads the colour back off the button's NORMAL embedded `CSimpleFont`, and an unset local
-    // colour there still resolves through what the normal state INHERITS
-    // (`<NormalFont>`/`SetTextFontObject`) — which is how a `GameMenuButtonTemplate` button answers
-    // `GameFontNormal`'s colour before anything calls `SetTextColor`. Falling back to white would
-    // be wrong in exactly the case the corpus cares about: reading a stock button's colour to
-    // restore it after a temporary recolour. White is the last resort, matching every other colour
-    // getter here (`GetVertexColor`, `FontString:GetTextColor`) — the untinted default a region
-    // with no colour anywhere draws at.
-    //
-    // Completeness rather than a live break: the census found no corpus site with a Button
-    // receiver (every measured `GetTextColor` call is on a FontString or a font object). It is here
-    // because the reference registers it and the widget shape gate can then cover it.
+    // GetTextColor() (`0x781100`) → r, g, b, a, four values, off the normal font: its own colour,
+    // else the inherited object's (`<NormalFont>`, `SetTextFontObject`), else white.
     m.set(
         "GetTextColor",
         lua.create_function(|lua, this: Table| {
@@ -1039,8 +751,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?,
     )?;
 
-    // LockHighlight/UnlockHighlight — pin the HighlightTexture on regardless of hover (ref
-    // CButton::LockHighlight; the dropdown kit's checked rows stay lit).
+    // LockHighlight (`0x782840`) and UnlockHighlight: the highlight shows regardless of hover.
     m.set(
         "LockHighlight",
         lua.create_function(|lua, this: Table| {
@@ -1062,28 +773,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "Disable",
         lua.create_function(|lua, this: Table| set_enabled(lua, &this, false))?,
     )?;
-    // IsEnabled() → the NUMBER 1 or the NUMBER 0 — never a boolean, and never nil.
-    //
-    // The Button method table at
-    // `0x879d10` gives `IsEnabled 0x7800b0`, which reads the three-valued STATE at `[obj+0x328]`
-    // (0 DISABLED / 1 NORMAL / 2 PUSHED), does `setne cl` for "not disabled", and pushes that as a
-    // NUMBER. So the reference's own `IsEnabled() == 0` and `== 1` tests (FriendsFrame.lua l.404,
-    // StaticPopup.lua l.713) are live code.
-    //
-    // **This answered a Lua boolean until now, and the difference is not cosmetic, because 0 is
-    // TRUTHY in Lua.** A caller writing the reference's `== 0` got false forever; a caller writing
-    // `IsEnabled() > 0` got "attempt to compare number with boolean" — which is where pfUI's
-    // `api/ui-widgets.lua:812` icon-fade died, taking the widget module with it. The divergence was
-    // known and worked around by hand in three of our own files (FriendsFrame.xml's
-    // `guildButtonDisabled` read BOTH spellings and said so); those workarounds go with this
-    // change, which is 1719's bar — a prior call revisited because a new measurement arrived.
-    //
-    // Slider used to carry its own `IsEnabled` (slider.rs), left alone here because "whether the
-    // slider widget shares the contract is unverified". It does not share it — it does not HAVE
-    // one: 1.12 registers `Enable`/`Disable`/`IsEnabled` on this table alone, and the Slider's
-    // LoadXML `0x789580` has no `enabled` attribute either, so ours was a superset. The trio came
-    // off the Slider rather than being brought into line with this contract; see the note at its
-    // old site in `slider.rs`.
+    // IsEnabled() (`0x7800b0`) → the number 1 or 0 from the state at `+0x328`, never a boolean:
+    // 0 is truthy in Lua, and the stock UI tests `== 0` (`FriendsFrame.lua:404`) and `== 1`
+    // (`StaticPopup.lua:713`).
     m.set(
         "IsEnabled",
         lua.create_function(|lua, this: Table| {
@@ -1091,10 +783,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // RegisterForClicks(...): replaces the button's registered-click set outright (the live API's
-    // contract — not additive) with its varargs, verbatim strings (`"LeftButtonUp"`,
-    // `"RightButtonDown"`, …). [`UiScript::mouse_button`] consults the set via [`wants_click`] to
-    // decide whether a press or a release reaches `OnClick`.
+    // RegisterForClicks(...) (`0x782490`) replaces the registered set rather than adding to it
+    // (`0x779730` stores the mask), matching the names in any case (`0x64a4c0`); [`wants_click`]
+    // reads it.
     m.set(
         "RegisterForClicks",
         lua.create_function(|lua, (this, args): (Table, MultiValue)| {
@@ -1108,21 +799,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // **`SetButtonState(state[, lock]) 0x780270` — TWO arguments**, and the second is not
-    // cosmetic. It reads three stack
-    // indices and returns none; the state maps case-insensitively over exactly
-    // `{"DISABLED", "NORMAL", "PUSHED"}` (`0x780390`, `SStrCmpI`) and an unrecognised string
-    // raises `Usage: %s:SetButtonState("state", lock)`; the flag is `GetBoolOrDefault` with
-    // **default 0** (`0x78032c push 0`), whose number arm truncates through `_ftol`, so the
-    // literal `1` that `MainMenuBarMicroButtons.lua` passes arms it.
-    //
-    // **The lock is the whole of decision 2134.** While it is set the button ignores the mouse
-    // press/release transitions; while it is clear, the next release un-pushes a scripted push —
-    // which is what Tablet-2.0's rows depend on, since the library pushes them and never calls
-    // `SetButtonState("NORMAL")` anywhere.
-    //
-    // DISABLED really is accepted here — the mapper takes it — even though the 1.12 FrameXML
-    // never passes it.
+    // SetButtonState(state [, lock]) (`0x780270`): DISABLED, NORMAL or PUSHED in any case
+    // (`0x780390`), else a usage error; `lock` is `GetBoolOrDefault` with default 0 (`0x78032c`),
+    // so the `1` of `MainMenuBarMicroButtons.lua:22` sets it. While locked, presses and releases
+    // leave the state alone; unlocked, the next release un-pushes a scripted push.
     m.set(
         "SetButtonState",
         lua.create_function(|lua, (this, state, lock): (Table, String, MultiValue)| {
@@ -1145,12 +825,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     m.set(
         "GetButtonState",
         lua.create_function(|lua, this: Table| {
-            // ONE variable, read back (`0x780180` reads `[obj+0x328]`). This used to OR in the
-            // live mouse-held press, because the state was derived and the press lived outside
-            // the widget; now the press *wrote* the state at its edge, so a mouse-held button
-            // answers "PUSHED" for the same reason the reference does — and cannot disagree with
-            // the art the way a re-derived answer could (decision 2134). The chat scroll buttons'
-            // hold-repeat (ref `MessageFrameScrollButton_OnUpdate`) still reads what it needs.
+            // The latched state (`0x780180` reads `+0x328`): a held button answers PUSHED because
+            // its press wrote it, which the chat scroll repeat reads (`ChatFrame.lua:1588`).
             with_button(lua, &this, |bs| match bs.button_state() {
                 ButtonVisualState::Disabled => "DISABLED",
                 ButtonVisualState::Pushed => "PUSHED",
@@ -1159,7 +835,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // Click([button]) — the programmatic click: same path as a physical one (toggle-then-OnClick).
+    // Click([button]) (`0x7826c0`): the physical click's path, toggle and `OnClick` alike.
     m.set(
         "Click",
         lua.create_function(|lua, (this, button): (Table, Option<String>)| {
@@ -1169,8 +845,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 model.frame_id(h)
             };
             let btn = button.unwrap_or_else(|| "LeftButton".to_string());
-            // A programmatic Click() always emulates a completed (released) click.
-            // A programmatic Click() — `scripted = true`, which only a LootButton reads.
+            // A released click, flagged as scripted, which only a LootButton reads.
             click_button(lua, id, &btn, false, true);
             Ok(())
         })?,
@@ -1178,21 +853,19 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 
     lua.set_named_registry_value(REG_BUTTON_METHODS, m)?;
 
-    // CheckButton's own table (consulted before Button's — the class chain).
+    // CheckButton's own table, consulted before Button's.
     let c = lua.create_table()?;
     texture_pair(lua, &c, "Checked", Slot::Checked)?;
     texture_pair(lua, &c, "DisabledChecked", Slot::DisabledChecked)?;
     c.set(
         "SetChecked",
         lua.create_function(|lua, (this, v): (Table, Value)| {
-            // Numeric coercion, NOT Lua truthiness (decision 0227; `SetChecked 0x799bf0` →
-            // `0x6f1c10`): a number goes through `lua_tonumber` then a truncate-to-int (`fistp`,
-            // round-toward-zero, `0x40a2b0`) and the C++ setter tests `!= 0`. So `SetChecked(0)`
-            // UNchecks (0 is Lua-truthy — only a numeric read gets this right) and `SetChecked(1)`
-            // checks; the type-dispatched helper also honors the keyword strings the reference
-            // passes ("true"/"false" — SpellBookFrame.lua l.296-303), while a non-keyword string
-            // falls to tonumber (→ 0 → unchecked). nil/other → false; booleans honored as-is for
-            // this codebase's own Era-style callers.
+            // `SetChecked` (`0x799bf0`) reads its argument through `0x6f1c10` with default 1
+            // (`0x799c77`), not Lua truthiness: a number truncates toward zero (`0x40a2b0`), so
+            // `SetChecked(0)` unchecks, and the stock UI passes `"true"`/`"false"`
+            // (`SpellBookFrame.lua:296-303`). Here a missing argument unchecks and a string checks
+            // only as `"true"` or a nonzero number, where the reference checks for a missing one
+            // and reads a string by its first byte, so `"yes"` checks there.
             let checked = match v {
                 Value::Boolean(b) => b,
                 Value::Integer(i) => i != 0,
@@ -1208,13 +881,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
     c.set(
-        // GetChecked() -> the NUMBER 1 or nil, never a boolean (1830). Its neighbour
-        // `IsEnabled` two entries up was corrected for the same reason under 1719, whose comment
-        // records that a boolean here killed pfUI's widget module outright; this is that call
-        // finished. The reference proves the shape in its own source rather than only at the
-        // bytes: stock `UIOptionsFrame.xml:310` saves a checkbox as
-        // `tostring(this:GetChecked())` and stock `BuffFrame.lua:71` reads it back as `== "1"`,
-        // a round-trip that only closes on the number.
+        // GetChecked() → the number 1 or nil, never a boolean: `UIOptionsFrame.xml:310` saves
+        // `tostring(this:GetChecked())` and `BuffFrame.lua:71` compares it with `"1"`.
         "GetChecked",
         lua.create_function(|lua, this: Table| {
             let checked = with_button(lua, &this, |bs| bs.checked)?;
@@ -1226,12 +894,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Whether frame `h` should fire `OnClick` for the input transition `name`
-/// (`"<Button>ButtonUp"`/`"<Button>ButtonDown"`, e.g. `"RightButtonDown"`) — the
-/// [`UiScript::mouse_button`](super::UiScript::mouse_button) gate. A Button/CheckButton consults
-/// its `RegisterForClicks` set (case-insensitively — the live API is forgiving of case); any
-/// other kind with an `OnClick` fires exactly as it always has, before `RegisterForClicks`
-/// existed: on release only (`name` ending `"Up"`), for any button, never on press.
+/// Whether `h` fires `OnClick` for the transition `name` (e.g. `"RightButtonDown"`): a Button
+/// checks its `RegisterForClicks` set, ignoring case; any other kind fires on release only.
 pub(super) fn wants_click(model: &Model, h: FrameHandle, name: &str) -> bool {
     match model.arena.frame(h).map(|f| &f.kind_state) {
         Some(KindState::Button(bs)) => bs
@@ -1242,28 +906,10 @@ pub(super) fn wants_click(model: &Model, h: FrameHandle, name: &str) -> bool {
     }
 }
 
-/// Whether frame `h` is registered for `button` (`"LeftButton"`, `"RightButton"`, …) in **either**
-/// variant — the press-visual gate, which is a strictly weaker test than [`wants_click`]'s.
-///
-/// `CButton::OnMouseDown 0x779210` runs the two as separate tests in one pass, and the difference
-/// between them is the whole of this:
-///
-/// ```text
-/// 0x779238  eax = event.buttonMask
-/// 0x779243  ecx = eax << 8 | eax
-/// 0x77924b  test [this+0x330], ecx   ; registered EITHER WAY -> keep going, else nothing at all
-/// 0x779256  hit-test the point       ; else nothing
-/// 0x77926b  test event.buttonMask, [this+0x330]  ; the DOWN bits alone -> fire OnClick
-/// 0x7792ad  push 2 ; SetState(PUSHED)            ; unconditional past the gates above
-/// ```
-///
-/// So `[this+0x330]` is one dword holding the `"…ButtonDown"` registrations in byte 0 and the
-/// `"…ButtonUp"` registrations in byte 1, and the mask `m | m << 8` asks "this button, either
-/// variant". **The pushed art is not conditional on the click firing, or on the handler doing
-/// anything** — it is conditional only on the button being registered for that mouse button at
-/// all, which is why a right-click on an action, spellbook or pet slot lights up even when the
-/// right-click does nothing (they all register `RightButtonUp`), and why a right-click on a plain
-/// `LeftButtonUp` button does not.
+/// Whether `h` is registered for `button` (`"LeftButton"`, …) as Up or Down, the press-art gate.
+/// `OnMouseDown` (`0x779210`) tests `m | m << 8` against `[this+0x330]` (Down in byte 0, Up in
+/// byte 1, `0x77924b`) before the Down-only `OnClick` test (`0x77926b`), so any registration for
+/// that button pushes the art, click or not.
 pub(super) fn wants_press_visual(model: &Model, h: FrameHandle, button: &str) -> bool {
     match model.arena.frame(h).map(|f| &f.kind_state) {
         Some(KindState::Button(bs)) => bs.registered_clicks.iter().any(|s| {
@@ -1275,18 +921,12 @@ pub(super) fn wants_press_visual(model: &Model, h: FrameHandle, button: &str) ->
     }
 }
 
-/// The click behavior shared by the input path and `Click()`: gated on `enabled`; a CheckButton
-/// **toggles before OnClick fires** (the documented widget contract — a handler reading
-/// `self:GetChecked()` sees the new state); then `OnClick(self, button, down)` — `down` is `true`
-/// only for a press that fired via a `"<Button>ButtonDown"` registration, `false` for every
-/// release-fired or programmatic click (the Era signature: `down` mirrors which transition fired).
-///
-/// `scripted` says the click came from Lua `:Click()` rather than from hardware — the reference's
-/// second `OnClick` argument (`0` from `0x779280`/`0x7793a4`, `1` from the `Button:Click` binding
-/// `0x7826c0`). Only [`crate::widget::FrameKind::LootButton`] reads it, and it reads it as a hard
-/// gate: `0x4c182b` returns before the base call, so **a scripted click on a loot row does
-/// nothing at all — not even run the row's own Lua `OnClick`**. Every other kind ignores it, which
-/// is the reference's shape too (the base `0x779540` never looks at the flag).
+/// The click shared by the input path and `Click()`: a disabled Button fires nothing, a CheckButton
+/// toggles before `OnClick` runs (`0x785550`), then `OnClick` gets the button name and `down`, true
+/// only for a click a `…ButtonDown` registration fired. The second argument is not 1.12's, whose
+/// `OnClick` gets the name alone (`0x779540`). `scripted` marks a Lua `Click()` (`0x7826c0` passes
+/// 1, the mouse `0x779280`/`0x7793a4` pass 0): a LootButton then does nothing at all, not even its
+/// `OnClick` (`0x4c182b`); every other kind ignores it.
 pub(super) fn click_button(lua: &Lua, id: u32, button: &str, down: bool, scripted: bool) {
     let mut take_loot = None;
     let fire = {
@@ -1302,12 +942,10 @@ pub(super) fn click_button(lua: &Lua, id: u32, button: &str, down: bool, scripte
             if scripted {
                 return;
             }
-            // Read the take BEFORE the handler runs, but queue it after: the reference reads
-            // `[esi+0x4dc]` after the base call, and a handler that re-slots its own row mid-click
-            // is not a case the shipped UI produces — reading first keeps the borrow simple and
-            // the two cannot disagree. The modifier gate is `0x4c183a`/`0x4c1848`/`0x4c1856`:
-            // shift, ctrl OR alt suppresses, and it is the whole reason the shipped
-            // `LootFrameItem_OnClick` never calls a take itself.
+            // Deviation: the slot is read before the handler, where the reference reads it after
+            // (`[esi+0x4dc]`), because reading first keeps the borrow simple and no stock handler
+            // re-slots its row. Shift, ctrl or alt suppresses the take (`0x4c183a`/`0x4c1848`/
+            // `0x4c1856`).
             let (shift, ctrl, alt) = model.modifiers;
             if !shift && !ctrl && !alt {
                 take_loot = model.arena.frame(h).and_then(|f| match &f.kind_state {
@@ -1321,7 +959,7 @@ pub(super) fn click_button(lua: &Lua, id: u32, button: &str, down: bool, scripte
         };
         let is_check = frame.kind == FrameKind::CheckButton;
         match &mut frame.kind_state {
-            // A Button/CheckButton click is gated on its enabled flag…
+            // A Button fires only while enabled;
             KindState::Button(bs) => {
                 if bs.enabled() {
                     if is_check {
@@ -1332,7 +970,7 @@ pub(super) fn click_button(lua: &Lua, id: u32, button: &str, down: bool, scripte
                     false
                 }
             }
-            // …every other kind with an OnClick just fires (plain frames can carry one too).
+            // any other kind with an `OnClick` just fires.
             _ => true,
         }
     };
@@ -1349,21 +987,16 @@ pub(super) fn click_button(lua: &Lua, id: u32, button: &str, down: bool, scripte
             .expect("model app_data")
             .record_script_error(e.to_string());
     }
-    // **A nameplate's click is the engine's too** (decision 2148): the reference's plate overrides
-    // the button click slot (`0x7cb910`) *and* chains the base, so its unit is selected whether the
-    // click came from the pointer or from Lua's own `Click()` — this funnel is both. Recorded after
-    // the handler, like the loot take below and for the same reason: an addon hook that errors
-    // cannot silently eat the selection. A press (`down`) records nothing — the plate registers for
-    // `LeftButtonUp | RightButtonUp` only (`RegisterForClicks(0x500)` at `0x7cb637`).
+    // A nameplate click selects its unit, from the pointer or `Click()` alike (the plate's
+    // override `0x7cb910` chains the base), after the handler so an erroring hook cannot eat it. A
+    // press selects nothing: the plate registers Up clicks only (`0x7cb637`).
     if !down {
         super::nameplate::note_click(lua, id, button);
     }
-    // …and then the take, unconditionally on the handler's outcome. `0x4c1867` is not guarded by
-    // anything the Lua side did: the base call at `0x4c1833` returns void and its result is never
-    // tested. A row whose `OnClick` errored still loots, which is the reference's behaviour and
-    // the reason a broken addon hook cannot silently eat your loot.
+    // The take runs whatever the handler did (`0x4c1867`): a row whose `OnClick` errored still
+    // loots.
     if let Some(slot) = take_loot {
-        // The 0-based store, back to the 1-based display row the take queue speaks.
+        // The slot is 0-based; the take queue speaks the 1-based row.
         lua.app_data_mut::<Model>()
             .expect("model app_data")
             .loot_picks
diff --git a/crates/benilla-ui/src/script/camera_view.rs b/crates/benilla-ui/src/script/camera_view.rs
index 93b56703..9d7026bf 100644
--- a/crates/benilla-ui/src/script/camera_view.rs
+++ b/crates/benilla-ui/src/script/camera_view.rs
@@ -1,103 +1,50 @@
-//! The **five camera views** — `SetView` / `SaveView` / `ResetView` / `NextView` / `PrevView`,
-//! plus `FlipCameraYaw`: the outbound half of the reference's `UIUtil\Camera.cpp` Lua surface.
+//! The camera-view verbs from the reference's Lua table at `0x84f7a0`: `SetView`, `SaveView`,
+//! `ResetView`, `NextView`, `PrevView` and `FlipCameraYaw`. Each acts on engine state the VM does
+//! not hold, so each call queues a [`CameraViewRequest`] for the app's camera rig.
 //!
-//! Six globals, no state — [`super::follow`]'s shape exactly. Nothing here reads the camera: every
-//! one of these is an **engine action** over state this VM does not hold (the orbit arm, the pitch,
-//! the character's facing, the zoom ceiling), so each call queues a [`CameraViewRequest`] the app
-//! drains ([`super::UiScript::take_camera_view_requests`]) and applies to the rig
-//! (`benilla_app::player::camera_view`). The alternative — reaching into the ECS from inside the
-//! VM — is the thing decision 0068 §3 exists to forbid.
-//!
-//! **Where they come from.** The reference registers them in one table, `0x84f7a0` (`{const char*
-//! name; handler}` pairs, dumped from `WoW.exe` 5875): rows 15…20 are `SetView 0x50b5b0`,
-//! `SaveView 0x50b600`, `ResetView 0x50b640`, `NextView 0x50b680`, `PrevView 0x50b690`,
-//! `FlipCameraYaw 0x50b6a0`. Sixteen 1.12 binding commands have one of these as their whole body
-//! (`SETVIEW1`…`5`, `SAVEVIEW2`…`5`, `RESETVIEW2`…`5`, `NEXTVIEW`, `PREVVIEW`, `FLIPCAMERAYAW`).
-//!
-//! ## The argument ABI is a third shape, and it is neither of [`super::binding_abi`]'s two
-//!
-//! The four indexed entry points share one prologue, byte-identical across `0x50b5b0` /
-//! `0x50b600` / `0x50b640`:
-//!
-//! ```text
-//! 50b5b8  call 0x6f34d0          ; is-number(L, 1)  — a number, or a coercible string
-//! 50b5bf  je   <exit>            ; NOT a number -> xor eax,eax ; ret   (silent, zero Lua values)
-//! 50b5c8  call 0x6f3620          ; tonumber(L, 1)
-//! 50b5cd  call 0x40a2b0          ; double -> int32, truncating toward zero
-//! 50b5d4  jle  <exit>            ; n <= 0  -> silent
-//! 50b5d9  jg   <exit>            ; n >  5  -> silent
-//! 50b5e5  dec  eax               ; Lua 1..5  ->  internal view 0..4
-//! ```
-//!
-//! So the failure edge **returns without raising** — it never reaches `luaL_error 0x6f4940`, which
-//! is the discriminator [`super::binding_abi`]'s header sets out. A macro doing `SetView(0)`,
-//! `SetView(9)`, `SetView("left")` or `SetView()` is a silent no-op in the real client, and is one
-//! here. That rules out `binding_abi::number_arg` (shape A — raises) and makes
-//! `binding_abi::coerced_number` (shape C — no guard, defaults to `0.0`) merely *accidentally*
-//! right, so the guard is written out rather than borrowed.
-//!
-//! `FlipCameraYaw` takes the same is-number guard and then the raw float — `0x6f3620` straight to
-//! `fstp [ebp-4]`, with no `0x40a2b0` — so its argument is **not** truncated to an integer.
-//!
-//! ## Two verified facts that a reader will expect to be otherwise
-//!
-//! - **The range is 1…5 for all three of Set/Save/Reset.** `SaveView(1)` and `ResetView(1)` are
-//!   accepted by the engine and act on `FIRST_PERSON`; `0x50fa30` (SaveView's body) has no view-0
-//!   gate at all. 1.12 ships no `SAVEVIEW1`/`RESETVIEW1` *binding*, which is a `Bindings.xml`
-//!   decision, not an engine one — a macro reaches what the keybinding cannot.
-//! - **`NextView`/`PrevView` do not wrap.** `0x50faa0` is `eax = view + 1; cmp eax,5; jge <ret>`
-//!   and `0x50fac0` is `test eax,eax; jle <ret>; dec eax` — each is a hard stop at its end of the
-//!   range, so holding `END` walks 1→2→3→4→5 and stays there. The app enforces it (this side only
-//!   queues the verb).
+//! The indexed verbs share one prologue and return silently, never reaching `luaL_error`
+//! (`0x6f4940`), on anything but a number that truncates to 1 to 5; `FlipCameraYaw` keeps its
+//! argument's fraction. `SaveView(1)` and `ResetView(1)` act on first person (`0x50fa30` has no
+//! view-0 gate; only `Bindings.xml` lacks the bindings). `NextView` and `PrevView` stop at the
+//! ends and never wrap (`0x50faa0`, `0x50fac0`).
 
 use mlua::{Lua, Value};
 
 use super::Model;
 
-/// The number of camera views — the reference's default-string table `0x84f488` is five rows, and
-/// every entry point above is bounded by it.
+/// The number of camera views, the rows of the reference's default-string table `0x84f488`.
 pub const CAMERA_VIEW_COUNT: u8 = 5;
 
-/// One camera-view intent queued by the Lua surface, drained by the app
-/// ([`super::UiScript::take_camera_view_requests`]). Plain data — [`super::follow::FollowRequest`]'s
-/// twin.
-///
-/// The indices are the **internal** ones, `0..CAMERA_VIEW_COUNT`, already range-checked here
-/// exactly where the reference range-checks them (its Lua handler, `dec eax`). The app applies
-/// them; it never re-validates a number that cannot be out of range.
+/// A camera-view intent for the app. Indices are internal, `0..CAMERA_VIEW_COUNT`, range-checked
+/// here where the reference checks them, in the Lua handler.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub enum CameraViewRequest {
-    /// `SetView(n)` — make view `n-1` the live one (distance, pitch and the saved yaw offset).
+    /// `SetView(n)`: make view `n-1` live (distance, pitch and the saved yaw offset).
     Set(u8),
-    /// `SaveView(n)` — store the live pose into view `n-1`.
+    /// `SaveView(n)`: store the live pose into view `n-1`.
     Save(u8),
-    /// `ResetView(n)` — put view `n-1` back to its shipped default.
+    /// `ResetView(n)`: put view `n-1` back to its shipped default.
     Reset(u8),
-    /// `NextView()` — the view above the current one, if there is one (no wrap).
+    /// `NextView()`: the view above the current one, if any.
     Next,
-    /// `PrevView()` — the view below the current one, if there is one (no wrap).
+    /// `PrevView()`: the view below the current one, if any.
     Prev,
-    /// `FlipCameraYaw(degrees)` — add this many **degrees** to the camera's yaw. The binding body
-    /// 1.12 ships is `FlipCameraYaw(180)`.
+    /// `FlipCameraYaw(degrees)`: add degrees to the camera's yaw; `Bindings.xml:795` passes 180.
     FlipYaw(f32),
 }
 
 impl super::UiScript {
-    /// Drain the camera-view intents queued since the last call — the app applies each to the
-    /// camera rig.
+    /// Drain the camera-view intents queued since the last call.
     pub fn take_camera_view_requests(&mut self) -> Vec<CameraViewRequest> {
         std::mem::take(&mut self.model_mut().camera_view_requests)
     }
 }
 
-/// The shared prologue of `SetView`/`SaveView`/`ResetView`: `is-number` → `tonumber` → truncate to
-/// `i32` → the `1 ..= 5` window → the internal index. `None` is every silent-return edge in one.
+/// The indexed verbs' shared prologue: the internal index, or `None` for a silent return.
 fn view_arg(lua: &Lua, v: Value) -> Option<u8> {
-    // `0x6f34d0` is-number, then `0x6f3620` tonumber, then `0x40a2b0`'s chop-toward-zero cast —
-    // `lua.coerce_number` is the first two (Lua coerces a numeric string), `as i64 as i32` the
-    // third (see `binding_abi::number_arg`, whose only difference from this is that it raises).
+    // Is-number (`0x6f34d0`) and `tonumber` (`0x6f3620`) take a numeric string; the cast
+    // truncates toward zero, as `0x40a2b0` does.
     let n = lua.coerce_number(v).ok().flatten()? as i64 as i32;
-    // `test eax,eax; jle` then `cmp eax,5; jg` — both silent.
     (1..=i32::from(CAMERA_VIEW_COUNT))
         .contains(&n)
         .then(|| (n - 1) as u8)
@@ -107,9 +54,8 @@ fn view_arg(lua: &Lua, v: Value) -> Option<u8> {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // SetView(n) — `0x50b5b0`. Load view n (1..5). The reference then calls `0x512e90(view,
-    // cameraViewBlendStyle)`, which also writes the `cameraView` CVar so the active view survives
-    // a restart; the app does both halves.
+    // SetView(n), `0x50b5b0`. The reference's `0x512e90` also writes the `cameraView` CVar, so
+    // the view survives a restart; the app does both.
     g.set(
         "SetView",
         lua.create_function(|lua, n: Value| {
@@ -123,9 +69,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SaveView(n) — `0x50b600` → `0x50fa30`, which reads the camera's three TARGET fields
-    // (`+0x198` distance, `+0x1e0` pitch, `+0x210` yaw) into the slot array and writes each to its
-    // archived CVar. Accepts n = 1 (see the module header).
+    // SaveView(n), `0x50b600` → `0x50fa30`: the camera's target distance, pitch and yaw go into
+    // the slot and each to its archived CVar.
     g.set(
         "SaveView",
         lua.create_function(|lua, n: Value| {
@@ -139,8 +84,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ResetView(n) — `0x50b640` → `0x50fae0`, which re-parses the shipped default strings at
-    // `0x84f488 + 12·view` into the slot and re-applies the view if it is the live one.
+    // ResetView(n), `0x50b640` → `0x50fae0`: re-parses the view's default string (`0x84f488`)
+    // into the slot and re-applies the view if it is live.
     g.set(
         "ResetView",
         lua.create_function(|lua, n: Value| {
@@ -154,8 +99,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // NextView() / PrevView() — `0x50b680` → `0x50faa0` and `0x50b690` → `0x50fac0`. No arguments
-    // at all: neither handler touches the Lua stack. Neither wraps.
+    // NextView() and PrevView(), `0x50b680` and `0x50b690`: neither reads the Lua stack.
     g.set(
         "NextView",
         lua.create_function(|lua, ()| {
@@ -173,9 +117,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // FlipCameraYaw(degrees) — `0x50b6a0`, the whole body being
-    // `cam[+0x100] += arg × 0.01745329238474369`. Its argument keeps its fraction (no `0x40a2b0`),
-    // and the is-number guard's failure edge is the same silent return the four above take.
+    // FlipCameraYaw(degrees), `0x50b6a0`: adds `degrees × π/180` to the camera's yaw, fraction
+    // kept; a non-number returns silently.
     g.set(
         "FlipCameraYaw",
         lua.create_function(|lua, degrees: Value| {
diff --git a/crates/benilla-ui/src/script/channel.rs b/crates/benilla-ui/src/script/channel.rs
index 0ea2faa3..7f44a22b 100644
--- a/crates/benilla-ui/src/script/channel.rs
+++ b/crates/benilla-ui/src/script/channel.rs
@@ -1,42 +1,15 @@
-//! `GetChannelName` — the joined-channel lookup, in both directions.
-//!
-//! **The state this reads already existed and was built for this verb.** `ui_chat::edit`'s
-//! `ChannelState` has held `joined: Vec<String>` in join order since the chat arc, and its own doc
-//! comment names `GetChannelName(n)` as the law it implements. Only the registration was missing —
-//! the same silent-gap shape the loader arc kept finding, one layer up: the capability was built,
-//! nothing exposed it, and nothing complained.
-//!
-//! Corpus demand, counted by reading every line rather than the grep total (1207): **17 sites
-//! across 6 addons**, every one an unguarded call, no library replicated —
-//! `ChatLog` 7, `Recap` 4, `SmartRes` 2, `Enchantrix` 2, `FuBar_AssistFu` 1, `_LazyPig` 1. Both
-//! lookup directions are live in the corpus: by index (`GetChannelName(i)`) and by name
-//! (`GetChannelName("world")`, `GetChannelName("Trade - City")`).
-//!
-//! Signature verified against the reference — `GetChannelName = 0x4a05e0`, **three** returns:
-//!
-//! | # | the client's | ours |
-//! |---|---|---|
-//! | 1 | `slot[+0x00]`, the client-local **1-based joined-slot index** (= `CHAT_MSG_*` arg8) | the position in `joined` |
-//! | 2 | `slot[+0x04]`, the channel name | the `joined` entry |
-//! | 3 | `slot[+0x98]`, FrameXML's `instanceID` (= arg10) | **0** — see below |
-//!
-//! **Return 3 is 0, not nil, and that is a recorded position rather than a shrug.** It is the split
-//! index from `YOU_JOINED`'s second u32, which `ui_chat::event`'s doc already records as "0 on every
-//! vanilla emulator" and deliberately does not store. A client that one day meets a server which
-//! splits channels would need the field; nothing in the corpus reads it.
+//! The chat-channel globals: the joined-channel lookups, the join, leave and management verbs the
+//! app sends, and the guild-recruitment auto-join latch. `GetChannelName` (`0x4a05e0`) looks up by
+//! 1-based slot or by name and returns three values: the slot (`CHAT_MSG_*` arg8), the name and
+//! `instanceID` (arg10).
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// The 1-based slot of `name`, case-insensitively — `GetChannelName`'s first return.
-/// One `ChatChannels.dbc` row as the VM needs it for `JoinChannelByName` (decision 1908),
-/// `Add/RemoveChatWindowChannel` (`0x4a1000`/`0x4a1260`) and `EnumerateServerChannels`
-/// (`0x4a1790`): the id, the **Shortcut** (`General`, `Trade`, … — what every one of those verbs
-/// compares a typed name against, whole and case-folded), the name composed for the zone the
-/// player is in (`General - Elwynn Forest`; `None` while the zone text is empty, which is the
-/// verbs' nil leg), and whether the row is listed here at all (a `flags & 0x10` city row is, only
-/// in a city).
+/// One `ChatChannels.dbc` row for the channel verbs: the id, the Shortcut a typed name is matched
+/// against case-folded, the name composed for the player's zone (`None` while the zone text is
+/// empty, the verbs' nil leg), and whether it is listed (a `flags & 0x10` city row only in a city).
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct ZoneChannelRow {
     pub id: u32,
@@ -45,12 +18,11 @@ pub struct ZoneChannelRow {
     pub listed: bool,
 }
 
-/// A channel verb's ask, drained by the app into its `CMSG_*` (all of which
-/// `benilla-protocol::messages::client` already builds). The verbs are the stock
-/// `ChatFrame.lua` slash handlers' calls, one variant each.
+/// A channel verb's ask, drained by the app into its `CMSG_*`: the stock `ChatFrame.lua` slash
+/// handlers' calls, one variant each.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum ChannelCommand {
-    /// `JoinChannelByName(name, password)` — sent on both of 1908's non-nil legs.
+    /// `JoinChannelByName(name, password)`, sent on both non-nil legs.
     Join {
         name: String,
         password: String,
@@ -59,13 +31,13 @@ pub enum ChannelCommand {
     Leave {
         name: String,
     },
-    /// `ListChannelByName(name)` — `CMSG_CHANNEL_LIST`.
+    /// `ListChannelByName(name)`: `CMSG_CHANNEL_LIST`.
     List {
         name: String,
     },
-    /// `ListChannels()` — the roster of every joined channel.
+    /// `ListChannels()`: the roster of every joined channel.
     ListAll,
-    /// `DisplayChannelOwner(name)` — `CMSG_CHANNEL_OWNER`.
+    /// `DisplayChannelOwner(name)`: `CMSG_CHANNEL_OWNER`.
     DisplayOwner {
         name: String,
     },
@@ -111,7 +83,7 @@ pub enum ChannelCommand {
         name: String,
         player: String,
     },
-    /// `ChannelModerate(name)` — toggles moderation.
+    /// `ChannelModerate(name)`: toggles moderation.
     Moderate {
         name: String,
     },
@@ -122,8 +94,7 @@ pub enum ChannelCommand {
 }
 
 impl super::UiScript {
-    /// The zone-channel catalog for the player's current zone — fed whenever the zone (and so
-    /// every resolved name) changes.
+    /// Feed the zone-channel catalog, whenever the zone, and so every resolved name, changes.
     pub fn set_zone_channel_catalog(&mut self, rows: Vec<ZoneChannelRow>) {
         self.model_mut().zone_channel_catalog = rows;
     }
@@ -133,35 +104,33 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().channel_commands)
     }
 
-    /// The guild-recruitment auto-join latch — `0` STANDARD, `1` AUTO (decision 2115).
+    /// The guild-recruitment auto-join latch: `0` STANDARD, `1` AUTO.
     pub fn guild_recruitment_mode(&self) -> u8 {
         self.model_ref().guild_recruitment_mode
     }
 
-    /// Seat the latch from the host (the per-character chat cache at login). A host write is not
-    /// a player gesture, so it does **not** arm [`Self::take_guild_recruitment_change`] — the same
-    /// split `set_cvar_from_host` keeps one store over, and what stops a login from composing the
-    /// player's file out of a value the login itself just read.
+    /// Seat the latch from the chat cache at login. A host write is not a player gesture, so it
+    /// does not arm [`Self::take_guild_recruitment_change`]: a login must not save what it read.
     pub fn set_guild_recruitment_mode(&mut self, mode: u8) {
         let mut model = self.model_mut();
         model.guild_recruitment_mode = mode;
         model.guild_recruitment_changed = false;
     }
 
-    /// Has Lua moved the latch since the last drain? The chat cache's dirty signal.
+    /// Whether Lua moved the latch since the last drain: the chat cache's dirty signal.
     pub fn take_guild_recruitment_change(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().guild_recruitment_changed)
     }
 
-    /// Has Lua called `SetGuildRecruitmentMode(1)` since the last drain? The cascade's cue
-    /// (`0x49ea70` → `0x49ea90`; decision 2144).
+    /// Whether Lua called `SetGuildRecruitmentMode(1)` since the last drain: the cue for the
+    /// cascade (`0x49ea70` → `0x49ea90`).
     pub fn take_guild_recruitment_cascade(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().guild_recruitment_cascade)
     }
 
-    /// **A manual join or leave of `GuildRecruitment` forces the latch to 0** — the reference's
-    /// `0x49ed3d`/`0x49ef8f`, `call 0x49ea70(0)`: a player gesture, so unlike the host seat it
-    /// **does** arm the save. No cascade (mode 0 is the latch alone). Answers whether it moved.
+    /// A manual join or leave of `GuildRecruitment` forces the latch to 0 (`0x49ed3d`, `0x49ef8f`)
+    /// and, as a player gesture, arms the save; mode 0 has no cascade, and the cascade's own join
+    /// passes a flag that skips this reset. Returns whether the latch moved.
     pub fn reset_guild_recruitment_mode(&mut self) -> bool {
         let mut model = self.model_mut();
         if model.guild_recruitment_mode == 0 {
@@ -190,12 +159,9 @@ fn slot_of(model: &Model, name: &str) -> Option<usize> {
         .map(|i| i + 1)
 }
 
-/// The name occupying slot `n` (1-based), or `None` for out of range **or a freed slot**.
-///
-/// The hole case is the reference's, not a convenience: its by-index lookup `0x49bf30` bounds-checks
-/// against the record count and then demands the entry's own number field equal the index asked for
-/// (`cmp esi,ecx / jnz`), which a leave zeroed (`0x49bbd0`). So a channel left is a number that
-/// answers "not joined" while every channel above it keeps its own (1286).
+/// The name in slot `n` (1-based), `None` out of range or for a freed slot: the reference's lookup
+/// `0x49bf30` requires the entry's own number to equal `n`, which a leave zeroes (`0x49bbd0`), so a
+/// left channel's number answers "not joined" while every channel above it keeps its own.
 fn name_at(model: &Model, n: usize) -> Option<&str> {
     model.joined_channels.get(n.checked_sub(1)?)?.as_deref()
 }
@@ -203,78 +169,33 @@ fn name_at(model: &Model, n: usize) -> Option<&str> {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // ── The guild-recruitment auto-join pair (decision 2115) ──────────────────────────────────
-    //
-    // `GetGuildRecruitmentMode 0x4a0040` / `SetGuildRecruitmentMode 0x4a0060` — the store behind
-    // the reference's *Auto-join the Guild Recruitment Channel* option
-    // (`UIOptionsFrameCheckButtons["AUTO_JOIN_GUILD_CHANNEL"]`, index 51). The table entry is a
-    // bare `{ index = 51 }` with no cvar and no uvar, which reads as "unbound" and is not: the
-    // store is the three special-case arms `UIOptionsFrame_Load` (l.243-248), `_Save` (l.326-331)
-    // and `_SetDefaults` (l.649) keep for that key. Exactly the `SHOW_TUTORIALS` shape decision
-    // 2077 corrected, and this tree's own `OptionsFrame.xml` carried the wrong reading until 2115.
-    //
-    // **The state is one int** — the reference's `[0x843608]`, written only by `0x49ea70`
-    // (`mov ds:0x843608,ecx`; five call sites, no address-takes) and read by the Lua getter and by
-    // the chat-cache writer. Ours is `Model::guild_recruitment_mode`, seated at login and rendered
-    // back out by `ui_chat::settings`; the whole round trip is that file's one
-    // `OPTION_GUILD_RECRUITMENT_CHANNEL STANDARD|AUTO` line, written at teardown (`0x499a80` at
-    // `0x499b0e`: `latch == 1` → `AUTO`, else `STANDARD`), never at set time.
-    //
-    // **It boots at 1 (AUTO)**, and that is a `.data` initialiser rather than a BSS zero — `raw
-    // 0x443608` is `01 00 00 00` — corroborated twice over: `_SetDefaults` calls
-    // `SetGuildRecruitmentMode(1)`, and all 33 `chat-cache.txt` files the reference client itself
-    // wrote in this repo's install say `AUTO`. See `Model::guild_recruitment_mode`.
+    // ── The guild-recruitment auto-join pair ──────────────────────────────────
+    // `GetGuildRecruitmentMode` (`0x4a0040`) and `SetGuildRecruitmentMode` (`0x4a0060`) store the
+    // Auto-join Guild Recruitment Channel option, which has no cvar: `UIOptionsFrame.lua` binds it
+    // by special arms (`:243`, `:328`, `:647`). The state is one int, `[0x843608]`, a `.data`
+    // initialiser of 1 written only by `0x49ea70`, and the chat cache saves it at teardown
+    // (`0x499a80`), never at set time.
     g.set(
         "GetGuildRecruitmentMode",
-        // `[0x4a0040, 0x4a0057)` is 23 bytes and one path: `fild dword [0x843608]` (signed i32),
-        // `fstp qword [esp]`, `lua_pushnumber`, `mov eax,1`, `ret`. No arguments, no gates — a
-        // NUMBER, always, never nil. `UIOptionsFrame_Load` compares it `== 1`, so a nil here would
-        // read as a silent "not auto".
+        // Always a number, never nil: `UIOptionsFrame_Load` tests it `== 1`.
         lua.create_function(|lua, ()| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             Ok(f64::from(model.guild_recruitment_mode))
         })?,
     )?;
-    // ── The `ecx == 1` cascade (decision 2144) ──────────────────────────────────────────
-    // `0x49ea70` writes the latch and then tail-jumps into `0x49ea90` **only when the new
-    // mode is 1**, and `0x49ea90` is not bookkeeping — it acts, on the wire: a guilded
-    // player leaves `GuildRecruitment - City`, an unguilded one in a capital joins it, and
-    // otherwise the one-shot `[0xb6e5e4]` is armed for the next autojoin pass. The whole of
-    // it lives on the app side (`ui_chat::recruitment`), where the player's guild id, the
-    // zone row and the wire are; this binding only raises the ask
-    // (`take_guild_recruitment_cascade`). `Set(0)` is the latch alone — `0x49ea70`'s `jne`
-    // stops at `0x49ea80`, no packet.
-    //
-    // The verb itself fires `UPDATE_CHAT_WINDOWS` once (`0x4a00a9`), unconditionally; the
-    // cascade's two acting arms fire it again, so an acting `Set(1)` fires it twice.
-    //
-    // The mirror: `JoinChannelByName("GuildRecruitment")` (`0x49ed3d`) and
-    // `LeaveChannelByName` (`0x49ef8f`) each force the latch back to 0 — the join's reset is
-    // conditional on the caller's `flag` argument, which the Lua binding passes as 1 and
-    // `0x49ea90`'s own internal join passes as 0 (so the cascade does not undo the mode it
-    // is acting on). That is `reset_guild_recruitment_mode`, called from the app's drain of
-    // both verbs.
+    // ── The `ecx == 1` cascade ──────────────────────────────────────────
+    // For mode 1 only, `0x49ea70` tail-jumps into `0x49ea90`, which acts on the wire (a guilded
+    // player leaves `GuildRecruitment - City`, an unguilded one in a capital joins it); that runs
+    // app-side in `ui_chat::recruitment`, and an acting cascade fires `UPDATE_CHAT_WINDOWS` again.
     g.set(
         "SetGuildRecruitmentMode",
-        // `[0x4a0060, 0x4a00c4)`. One argument at stack index 1, and **two ways to raise** — this
-        // raises on a bad argument rather than swallowing a nil, unlike many bindings:
-        //
-        //   * `lua_isnumber 0x6f34d0` — so a NUMERIC STRING passes (`"1"` works) — else
-        //     `luaL_error("Usage: SetGuildRecruitmentMode(mode)")`, which longjmps.
-        //   * then `__ftol 0x40a2b0`, **truncating toward zero**, so `1.7` is silently accepted as
-        //     1 and `-0.5` as 0.
-        //   * then the range gate `0x4a0094 jl` / `0x4a009b jge 2` →
-        //     `luaL_error("SetGuildRecruitmentMode: invalid mode")` for `-1`, `2`, `-1.7`.
-        //
-        // Success returns **0 values** (`xor eax,eax; ret`), not nil. Stock FrameXML can reach
-        // neither raise: `UIOptionsFrame_Save` passes `button:GetChecked()` and coerces its nil to
-        // 0 itself. An ADDON can, and getting the raise right is the difference between an addon
-        // seeing its own bug and seeing ours.
+        // As `0x4a0060`: `lua_isnumber` (`0x6f34d0`, so `"1"` passes), truncation toward zero
+        // (`0x40a2b0`), then the 0..2 range gate (`0x4a0094`); success returns zero values.
         lua.create_function(|lua, mode: Option<Value>| {
             let n = match mode.as_ref() {
                 Some(Value::Integer(i)) => *i as f64,
                 Some(Value::Number(n)) => *n,
-                // `lua_isnumber` is true for a string luaO_str2d fully consumes.
+                // `lua_isnumber` is true for a string `luaO_str2d` fully consumes.
                 Some(Value::String(s)) => s
                     .to_str()
                     .ok()
@@ -311,10 +232,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, key: Value| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             let slot = match &key {
-                // The numeric form. The reference bounds-checks `1 <= n <= count` (`0x49bf30`) and
-                // answers only for a CONFIRMED-joined slot; `joined` holds exactly the confirmed
-                // ones (`ui_chat::feed` appends on the server's YOU_JOINED, not on the request), so
-                // the bound is the whole check here.
+                // The reference bounds-checks `1 <= n <= count` (`0x49bf30`) and answers only a
+                // confirmed slot; `joined` holds only those, so the bound is the whole check.
                 Value::Integer(_) | Value::Number(_) => {
                     let n = match &key {
                         Value::Integer(i) => *i,
@@ -325,9 +244,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                         .ok()
                         .filter(|n| name_at(&model, *n).is_some())
                 }
-                // The name form. A numeric STRING arrives here and must still resolve as a number:
-                // `ChatFrame.lua:2113` passes the result of a `gsub` — `GetChannelName("1")` — and
-                // Lua's own coercion is what makes that work on the real client.
+                // A numeric string still resolves as a number, as Lua's coercion does in the
+                // reference: `ChatFrame.lua:2113` passes a `gsub` result, `GetChannelName("1")`.
                 Value::String(s) => {
                     let name = s.to_str()?;
                     match name.trim().parse::<usize>() {
@@ -340,16 +258,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             };
 
             let Some(slot) = slot else {
-                // **`0, nil, 0` — three values, not one.** This used to push the number alone,
-                // reasoning that `channelName` is unread by every caller on this branch. True of
-                // the callers; not true of the client. `0x4a05e0` pushes three on every path, and
-                // slot 2 is neither the empty string nor the argument echoed back:
-                // `0x4a0659 xor edx,edx` then `lua_pushstring(NULL)`, which tail-jumps to
-                // `lua_pushnil`. Decision 1845.
-                //
-                // "Not joined" is also wider than a bad index: the lookup answers NULL while the
-                // join-pending word is non-zero, so a channel already in the list but not yet
-                // CONFIRMED reads `0, nil, 0` identically — which is what `joined` models here.
+                // Three values on every path, the name `lua_pushstring(NULL)`, which is nil
+                // (`0x4a0659`); an unconfirmed channel answers the same, as `joined` models.
                 return Ok(MultiValue::from_vec(vec![
                     Value::Integer(0),
                     Value::Nil,
@@ -360,44 +270,21 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(MultiValue::from_vec(vec![
                 Value::Integer(slot as i64),
                 Value::String(lua.create_string(&name)?),
-                // instanceID — see the module doc: 0 on every vanilla emulator, and a number
-                // rather than nil so a caller can compare it like the client's.
+                // `instanceID`: `YOU_JOINED`'s split index, 0 on vanilla servers; never nil.
                 Value::Integer(0),
             ]))
         })?,
     )?;
 
-    // GetChannelList() → slot1, name1, slot2, name2, … over every joined channel, in join order.
-    //
-    // **The shape is settled by two independent consumers, not by a recorded signature** — the
-    // reference gives the address (`0x4a02d0`) and no contract:
-    //
-    //  · the reference's own `FCFDropDown_LoadChannels(...)` walks `for i=1, arg.n, 2` and reads
-    //    `arg[i+1]` as the NAME (FloatingChatFrame.lua l.445-455) — so the pair is (slot, name),
-    //    in that order, and the caller steps by two;
-    //  · `ChatLog.lua:424` packs it with `{ GetChannelList() }` and tests
-    //    `type(value) == "number"` to spot an id — so it is a FLAT vararg, never a table.
-    //
-    // A third witness pins the flatness harder: `AceComm-2.0.lua:334` unpacks TEN pairs in one
-    // statement, `local _,a,_,b,…,j = GetChannelList()`.
-    //
-    // The slot numbering is [`slot_of`]'s — position in `joined_channels` + 1 — so this verb and
-    // `GetChannelName` can never disagree about which channel is 3.
-    //
-    // Zero joined channels is zero returns, not nil: `{ GetChannelList() }` is then an empty
-    // table, which is what every caller above already handles.
-    //
-    // Demand: 4 addons, and only ONE of them names it in its own source (ChatLog). The other
-    // three — FuBar_BGQueueNumber, FuBar_MageFu, FuBar_TankPointsFu — reach it through their
-    // embedded AceComm-2.0. That gap between "greps for the name" and "wants the name" is why the
-    // survey's own read-back exists (`--why`, d2fcef94) and why a hand grep is not the oracle here.
+    // GetChannelList() (`0x4a02d0`): a flat vararg of slot, name pairs in join order, as
+    // `FCFDropDown_LoadChannels` steps it (`FloatingChatFrame.lua:445`); none joined is zero
+    // returns. The slots must match `slot_of`'s, so it agrees with `GetChannelName`.
     g.set(
         "GetChannelList",
         lua.create_function(|lua, ()| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             let mut out = Vec::with_capacity(model.joined_channels.len() * 2);
-            // Occupied slots only — a freed one is a number nothing is on, so it has no pair to
-            // contribute (the reference walks its record array and skips the cleared entries).
+            // Occupied slots only: the reference skips the cleared entries of its record array.
             for (i, name) in model.joined_channels.iter().enumerate() {
                 let Some(name) = name.as_deref() else {
                     continue;
@@ -409,24 +296,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // JoinChannelByName(name [, password [, frameId]]) — `0x49ff00` → `0x49eb70`, the contract
-    // decision 1908 carved:
-    //
-    //   matched DBC row                        → (ChannelID, resolvedName)
-    //   custom channel (no row)                → (0, nil)      — and 0 is truthy in Lua
-    //   a space in the name, or a matched row  → nil           — no send
-    //     whose zone substitution is empty
-    //
-    // `CMSG_JOIN_CHANNEL` goes out on both non-nil legs. **The third argument registers the
-    // channel in that window's own list** (`0x49ec24`–`0x49ede7`):
-    // `frameId` is `lua_tonumber`d, truncated and decremented, and anything outside `0..10`
-    // after that — a missing or non-numeric argument yields `-1` — silently skips the
-    // registration; otherwise `(Shortcut, ChannelID)` for a matched row and `(name, 0)` for a
-    // custom one is appended to window `frameId - 1`'s parallel arrays, deduplicated by name
-    // (`SStrCmpI`), on both sending legs. It is what puts a `/join`ed channel back into the
-    // window after a `/leave` stripped it — the window's `ZONECHANNELS` word is the character's
-    // registration for that channel's lines, and without this a leave-then-join-then-relog left
-    // General joined and its every line dropped (decision 2144, live run F).
+    // JoinChannelByName(name [, password [, frameId]]) (`0x49ff00` → `0x49eb70`): a DBC row
+    // answers `(ChannelID, resolvedName)` and a custom channel `(0, nil)`, both sending; a name
+    // with a space, or a row whose zone text is empty, answers nil and sends nothing. A `frameId`
+    // that truncates to 1..=10 registers the channel in that window's list, deduplicated by name
+    // (`0x49ec24`), which is what brings a `/leave`-stripped channel's lines back to the window.
     g.set(
         "JoinChannelByName",
         lua.create_function(
@@ -489,10 +363,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?,
     )?;
 
-    // EnumerateServerChannels() — `0x4a1790`: the `ChatChannels.dbc`
-    // **shortcuts** in row order, a `flags & 0x10` row only when the zone is a city
-    // (`AreaTable.Flags & 0x8`); 0 values while the zone is unresolvable (an empty catalog here).
-    // Never the composed `<name> - <zone>`: `FCFDropDown_LoadServerChannels` shows these bare.
+    // EnumerateServerChannels() (`0x4a1790`): the `ChatChannels.dbc` Shortcuts in row order, never
+    // the composed names, a `flags & 0x10` row only in a city (`AreaTable.Flags & 0x8`); zero
+    // values while the zone is unresolved.
     g.set(
         "EnumerateServerChannels",
         lua.create_function(|lua, _ignored: MultiValue| {
@@ -505,27 +378,14 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // LeaveChannelByName(name) — `0x4a0000` → `0x49ee70`, the contract decision 2144 carved. The
-    // only stock caller is
-    // `SlashCmdList["LEAVE"]`, which passes the first whitespace token of the slash text.
-    //
-    //   1. a string or number, else it RAISES `Usage: LeaveChannelByName("name")`; 0 returns.
-    //   2. `SStrToInt(name) != 0` → the key names joined slot n — resolved on the app side, which
-    //      holds the slot states (a suspended or absent slot is a complete no-op there); no
-    //      window strip, because a slot name never equals a window entry.
-    //   3. else a case-insensitive Shortcut match → the composed name for this zone, or a
-    //      complete no-op with no zone text; the window strip is keyed on the DBC's Shortcut.
-    //   4. else a custom channel: the argument verbatim, stripped verbatim.
-    //
-    // **One deliberate divergence, recorded in 2144.** The reference composes the shortcut leg
-    // with `GetRealZoneText` ALONE (`0x49efe8`), never the `"City"` row — so in a capital
-    // `/leave Trade` sends `"Trade - Stormwind City"`, a channel the player is not in, and
-    // leaves nothing. Ours composes with the join's own city-aware substitution (the catalog's
-    // `resolved`), so `/leave Trade` leaves `Trade - City`. The mechanism, done right, not the
-    // reference's broken form of it.
-    //
-    // Nothing local is freed here and no event fires: the slot goes when the server's
-    // `YOU_LEFT` matches its stored name, and the mask bit with it — both the app's.
+    // LeaveChannelByName(name) (`0x4a0000` → `0x49ee70`) returns nothing and raises `Usage:` on a
+    // non-string, non-number. A key whose `SStrToInt` is non-zero is a joined slot, resolved
+    // app-side and never a window entry; a Shortcut leaves the name composed for this zone (a
+    // no-op with no zone text) and strips by Shortcut; anything else is a custom channel.
+    // Deviation: the reference composes the Shortcut with `GetRealZoneText` alone (`0x49efe8`), so
+    // in a capital `/leave Trade` sends `Trade - Stormwind City` and leaves nothing; ours uses the
+    // join's city-aware name, because the reference's form cannot leave the channel it joined.
+    // The slot is freed app-side when the server's `YOU_LEFT` arrives.
     g.set(
         "LeaveChannelByName",
         lua.create_function(|lua, name: Option<Value>| {
@@ -598,7 +458,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The two-name verbs: (channel, player) — or (channel, password) for the password.
+    // The two-name verbs: (channel, player), or (channel, password) for the password.
     for (verb, make) in [
         (
             "SetChannelOwner",
@@ -644,8 +504,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             lua.create_function(
                 move |lua, (name, second): (Option<String>, Option<String>)| {
                     if let Some(name) = non_empty(name) {
-                        // A password may legitimately be empty (`/password General` clears it); a
-                        // player name may not.
+                        // A password may be empty (`/password General` clears it); a player name
+                        // may not.
                         let second = second.unwrap_or_default();
                         if verb == "SetChannelPassword" || !second.trim().is_empty() {
                             push(lua, make(name, second.trim().to_string()));
@@ -661,12 +521,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 }
 
 impl super::UiScript {
-    /// Mirror the app's confirmed-joined channel list, in join order, for [`install`]'s verb.
-    ///
-    /// The `model.party` shape (`party.rs:172`), deliberately, and NOT the `open_chat_requests`
-    /// shape the chat-window work used: that one is a QUEUE the app drains (Lua → app), and this is
-    /// app state READ BY Lua, which is the opposite direction. `ui_chat::feed` owns both edges that
-    /// change it — the server's YOU_JOINED and YOU_LEFT notices — so it pushes here from one place.
+    /// Mirror the app's confirmed-joined channels in join order, `None` for a freed slot;
+    /// `ui_chat::feed` pushes it on each `YOU_JOINED` and `YOU_LEFT`.
     pub fn set_joined_channels(&mut self, joined: Vec<Option<String>>) {
         self.model_mut().joined_channels = joined;
     }
@@ -694,7 +550,7 @@ mod command_tests {
         ]
     }
 
-    /// Decision 1908's three legs, and that 0 is truthy.
+    /// The row, custom-channel and nil legs, and that 0 is truthy.
     #[test]
     fn join_channel_by_name_answers_the_three_legs_of_1908() {
         let mut s = UiScript::new().unwrap();
@@ -790,11 +646,8 @@ mod command_tests {
         );
     }
 
-    /// **`JoinChannelByName`'s third argument registers the channel in that window**
-    /// (`0x49ec24`–`0x49ede7`; decision 2144): `frameId - 1` indexes the ten window records,
-    /// `(Shortcut, ChannelID)` for a DBC row and `(name, 0)` for a custom channel, deduplicated by
-    /// name; a missing, non-numeric or out-of-range frame skips the registration and nothing else.
-    /// It is what puts a `/join`ed channel back into a window a `/leave` had stripped it from.
+    /// `frameId - 1` indexes the ten window records (`0x49ec24`); a missing, non-numeric or
+    /// out-of-range frame skips the registration and nothing else.
     #[test]
     fn join_channel_by_name_registers_the_channel_in_the_named_window() {
         let mut s = UiScript::new().unwrap();
@@ -828,17 +681,13 @@ mod command_tests {
             vec![0, 1],
             "…and both windows are owed a save"
         );
-        // The joins themselves went out regardless of the frame argument — five, because this
-        // catalog's Trade is unresolvable (the nil leg, asserted above), and that leg registers
-        // nothing either.
+        // The joins went out whatever the frame argument: five, as this catalog's Trade is the
+        // nil leg, which registers nothing either.
         assert_eq!(s.take_channel_commands().len(), 5);
     }
 
-    /// `LeaveChannelByName`'s legs (`0x4a0000` → `0x49ee70`; decision 2144): a number passes
-    /// through for the app's slot lookup and strips nothing; a shortcut composes for the zone and
-    /// strips the window entry it was registered under, in every window; an unresolvable shortcut
-    /// is a complete no-op; a custom name goes verbatim and strips verbatim. Nil raises. Zero
-    /// returns.
+    /// `LeaveChannelByName`'s four legs and its raise (`0x4a0000` → `0x49ee70`); a Shortcut strips
+    /// its entry from every window.
     #[test]
     fn leave_channel_by_name_composes_strips_and_raises_the_way_the_reference_does() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/char_stats.rs b/crates/benilla-ui/src/script/char_stats.rs
index 605cdf18..634f4683 100644
--- a/crates/benilla-ui/src/script/char_stats.rs
+++ b/crates/benilla-ui/src/script/char_stats.rs
@@ -1,63 +1,26 @@
-//! The character-window stats + equipment seam (decision 0208 §3) — the paper doll's data feed.
+//! The paper doll's data feed: the stat and equipment-slot globals, read from the combat-stats
+//! snapshots the app pushes for `"player"` and `"pet"` and from its inventory-slot snapshot.
 //!
-//! Same engine-free shape as [`super::unit`]: the app pushes a **combat-stats snapshot** per unit
-//! that has one ([`super::UiScript::set_player_combat_stats`] /
-//! [`super::UiScript::set_pet_combat_stats`]) and an **inventory-slot snapshot**
-//! ([`super::UiScript::set_inventory_slots`]) each frame they change, and the stat/slot globals
-//! here read that plain data.
+//! As in the reference, the pet sheet calls the same `PaperDollFrame_Set*` helpers with `"pet"`
+//! (`PetPaperDollFrame.lua:75-81`). Any other token, or a snapshot not yet pushed, serves the
+//! absent shape: zeros, `percent` 1.0. A pet has no PLAYER block, so its buff splits read 0.
 //!
-//! **The stat family is unit-parameterised, as the reference's is** (decision 1057): every
-//! `PaperDollFrame_Set*(unit, prefix)` helper the character sheet calls with `"player"`, the pet
-//! sheet calls with `"pet"` (ref `PetPaperDollFrame.lua:73-81`), through these very bindings. So
-//! `UnitStat`/`UnitResistance`/`UnitArmor`/… route on the token — `"player"` and `"pet"` each read
-//! their own pushed snapshot, and **every other token (and a snapshot the app has not pushed yet)
-//! serves the absent shape**: zeros, `percent` 1.0. A pet's descriptor carries the UNIT half and no
-//! PLAYER block at all, which is why its buff decompositions read `0` and the ref's own pet sheet
-//! shows plain white numbers.
+//! For a third unit, zeros are right for `UnitStat` (`0x518600`): `UNIT_FIELD_STAT*` is PRIVATE +
+//! OWNER_ONLY, so the reference holds zeros too. Not built: vmangos also sends a beast's
+//! `UNIT_FIELD_RESISTANCES` to the caster of its Beast Lore (`Object.cpp:1065-1067`,
+//! `Player.cpp:2603-2610`), and the reference's `UnitResistance` and `UnitArmor` then answer them.
 //!
-//! (Until 1057 the router was a hard `token == "player"` test documented as "the faithful
-//! player-only gate". It was neither: it was "no consumer yet". The reference passes `"pet"` into
-//! the same bindings, and the gate was simply never exercised.)
-//!
-//! **The absent shape for a third unit is the right ANSWER for `UnitStat` and a known GAP for the
-//! resistance pair — and the reason it used to be filed as blanket-faithful was wrong.** The binary
-//! does not gate slots 1/2 on SELF at all: `UnitStat`'s are NULL + typemask bit 3 only, and it
-//! returns whatever the client's copy of `UNIT_FIELD_STAT0+i` holds (`UnitStat 0x518600`). What
-//! makes our zeros agree there is the *server's* visibility, not a client gate: `UNIT_FIELD_STAT*`
-//! is PRIVATE + OWNER_ONLY, and the only owner-visible units a 1.12 unit token can name are the two
-//! we already serve — so a stranger's copy is zero on the reference too. `UNIT_FIELD_RESISTANCES`
-//! carries a third flag, **`SPECIAL_INFO`**, which vmangos grants to the caster of
-//! `SPELL_AURA_EMPATHY` — its own comment reads `// Beast Lore` (`Player.cpp:2603-2610`,
-//! `Object.cpp:1065-1067`). So with Beast Lore up on a beast, the reference's
-//! `UnitResistance("target", i)` / `UnitArmor("target")` return that creature's real numbers
-//! through their non-SELF leg, and ours return zeros. That is a real, reachable divergence, unfed
-//! rather than decided: the app pushes snapshots for two tokens only.
-//! `unit_combat_stats` already works over any store, so the missing piece is a third push.
-//!
-//! **Return shapes differ BY FAMILY, and the reference Lua's own asymmetry is the tell**
-//! (decision 1397 — reading one and assuming the other is how 0208 got the stat row wrong).
-//! `UnitStat` serves the **raw** `UNIT_FIELD_STAT` twice — once as-is, once clamped at zero — and
-//! leaves the subtraction to `PaperDollFrame_SetStats`, which writes `(stat - posBuff - negBuff)`
-//! itself. `UnitResistance`/`UnitArmor` serve a **decomposed** first return, because the engine
-//! helper `0x5efcd0` does that subtraction for them; their callers use it directly.
-//!
-//! The negative deltas are **negative-or-zero** where the wire can carry them at all, matching the
-//! ref's `negBuff < 0` tests — but see 1397 for how little of that survives a given server: these
-//! four arrays are stored float and narrowed to int by `Object::BuildValuesUpdate`, and that cast
-//! saturates a negative to `0` on an arm64 host while wrapping it correctly on x86.
+//! vmangos narrows the four buff-split arrays with `uint32(float)` (`Object.cpp:759-763`), so a
+//! negative delta arrives as 0 from an arm64 server and intact from x86.
 
 use mlua::{Lua, Value};
 
 use super::binding_abi::flag;
 use super::{binding_abi, Model};
 
-/// The 1.12 weapon-subclass → `SkillLine.dbc` id table, transcribed from vmangos
-/// `ItemPrototype::GetProficiencySkill`'s `item_weapon_skills` (`Objects/Item.cpp:700-707`;
-/// subclass ids `Objects/ItemPrototype.h:190-213`, skill ids `SharedDefines.h:951-1038`) — item
-/// class 2 (weapon) subclasses `0..=20`. `None` = no proficiency skill backs the subclass (the
-/// obsolete/exotic/misc rows) or out of range. The app resolves the paper doll's weapon-skill
-/// line ("Both Hands"/"Ranged") through this, falling back to [`SKILL_UNARMED`] with no weapon
-/// (vmangos `Player::GetBaseWeaponSkillValue`, `Objects/Player.cpp:20175-20186`).
+/// The `SkillLine.dbc` id behind weapon subclass `0..=20` (vmangos `Item.cpp:700-707`), `None`
+/// for the obsolete, exotic and misc rows; with no weapon the skill is [`SKILL_UNARMED`]
+/// (`Player.cpp:20144-20155`).
 pub fn weapon_subclass_skill(subclass: u32) -> Option<u32> {
     const TABLE: [u32; 21] = [
         44,  // 0 axe → SKILL_AXES
@@ -73,7 +36,7 @@ pub fn weapon_subclass_skill(subclass: u32) -> Option<u32> {
         136, // 10 staff → SKILL_STAVES
         0,   // 11 exotic
         0,   // 12 exotic2
-        162, // 13 fist weapon → SKILL_UNARMED (vmangos's own row — fists ride the unarmed skill)
+        162, // 13 fist weapon → SKILL_UNARMED (vmangos's own row: fists use the unarmed skill)
         0,   // 14 misc
         173, // 15 dagger → SKILL_DAGGERS
         176, // 16 thrown → SKILL_THROWN
@@ -85,27 +48,15 @@ pub fn weapon_subclass_skill(subclass: u32) -> Option<u32> {
     TABLE.get(subclass as usize).copied().filter(|&s| s != 0)
 }
 
-/// `SKILL_UNARMED` (162, vmangos `SharedDefines.h:987`) — the melee weapon-skill line's fallback
-/// when no weapon is equipped (`Player::GetBaseWeaponSkillValue`, `Objects/Player.cpp:20184`).
+/// The melee skill with no weapon equipped (vmangos `SharedDefines.h:987`, `Player.cpp:20153`).
 pub const SKILL_UNARMED: u32 = 162;
 
-/// `SKILL_DEFENSE` — the Defense skill line `UnitDefense` reports. **Read out of the shipped
-/// 1.12.1 `SkillLine.dbc` this session**, not remembered: the file's 123 records carry exactly one
-/// row whose enUS `displayName` (column 3, the `SkillLinefmt` layout in
-/// `benilla_formats::skill_lines`) is `"Defense"`, and it is id **95**, category 6 (Weapon Skills).
-/// Corroborated by vmangos `SharedDefines.h:961` (`SKILL_DEFENSE = 95`).
+/// The `SkillLine.dbc` Defense row `UnitDefense` reports (vmangos `SharedDefines.h:961`).
 pub const SKILL_DEFENSE: u32 = 95;
 
-/// One unit's combat-stats snapshot behind a paper doll's stat pane — plain data the app derives
-/// from that unit's descriptor accessors ([`UnitStat`]/[`UnitResistance`]/… read it). Arrays are
-/// in field order: stats 0..4 = Str/Agi/Stam/Int/Spi (`UNIT_FIELD_STAT0..4`), schools 0..6 with
-/// `[0]` = armor/physical. The `*_neg` values are **negative-or-zero** (the stored wire sign; see
-/// the module doc).
-///
-/// Two units carry one: the player and (decision 1057) the pet. A **creature's** descriptor has no
-/// PLAYER block, so every field sourced from one — the stat/resistance buff splits, the
-/// damage-done mods, the skill pairs — keeps its default for a pet, which is exactly the ref pet
-/// sheet's plain white numbers with no buff decomposition in the tooltip.
+/// One unit's combat stats behind a paper doll, from its descriptor. Arrays are in field order:
+/// stats Str/Agi/Sta/Int/Spi, schools with `[0]` armor. A pet leaves the PLAYER-block fields (buff
+/// splits, damage-done mods, skill pairs) at their defaults.
 #[derive(Clone, Debug, PartialEq)]
 pub struct UnitCombatStats {
     /// Effective (post-buff) primary stats (`UNIT_FIELD_STAT0..4`).
@@ -129,14 +80,12 @@ pub struct UnitCombatStats {
     /// Physical damage-done bonuses (`PLAYER_FIELD_MOD_DAMAGE_DONE_POS[0]` / `_NEG[0]`, neg ≤ 0).
     pub physical_bonus_pos: i32,
     pub physical_bonus_neg: i32,
-    /// The physical damage-done multiplier (`PLAYER_FIELD_MOD_DAMAGE_DONE_PCT[0]`, a true float —
-    /// the app fills `1.0` while the field hasn't streamed; the default here is `1.0` too).
+    /// The physical damage multiplier (`PLAYER_FIELD_MOD_DAMAGE_DONE_PCT[0]`), 1.0 until streamed.
     pub damage_percent: f32,
     /// Attack speeds in ms (`UNIT_FIELD_BASEATTACKTIME[0..2]`).
     pub main_attack_time_ms: u32,
     pub offhand_attack_time_ms: u32,
-    /// Whether an offhand **weapon** is equipped — gates `UnitAttackSpeed`'s second return (the
-    /// app decides from the inv slots; the offhand fields stream regardless).
+    /// Whether an off-hand weapon is equipped, which gates `UnitAttackSpeed`'s second return.
     pub has_offhand: bool,
     /// Melee AP + its split mods (`UNIT_FIELD_ATTACK_POWER` / `_MODS`, neg ≤ 0).
     pub attack_power: i32,
@@ -151,60 +100,27 @@ pub struct UnitCombatStats {
     /// Ranged damage range (`UNIT_FIELD_MINRANGEDDAMAGE`/`MAXRANGEDDAMAGE`).
     pub ranged_min_damage: f32,
     pub ranged_max_damage: f32,
-    /// The equipped main-hand weapon's skill line as **`(value + PERM bonus, TEMP bonus)`** — the
-    /// app resolves WHICH skill via [`weapon_subclass_skill`] (unarmed = [`SKILL_UNARMED`]) and
-    /// reads the pair from `PLAYER_SKILL_INFO`; `UnitAttackBothHands` serves it verbatim.
-    ///
-    /// **The permanent half belongs to the BASE, not to the modifier** (`0x5ea460`; corrected here
-    /// by decision 1812). Every one of these four pairs comes out of that one reader, so all four
-    /// carry the split.
+    /// The main hand's skill line (picked by [`weapon_subclass_skill`]) as `(value + perm, temp)`,
+    /// the split the reference's skill reader `0x5ea460` makes for all four skill pairs.
     pub main_weapon_skill: (i32, i32),
-    /// The OFF hand's, read the same way. `UnitAttackBothHands` pushes both hands (`0x518810`
-    /// calls `[vtbl+0xb0]` twice, hand 0 then hand 1), and an empty or non-weapon off hand is
-    /// Unarmed exactly as the main hand is.
+    /// The off hand's pair, read the same way; an empty or non-weapon off hand is Unarmed.
     pub offhand_weapon_skill: (i32, i32),
-    /// The ranged weapon's skill pair (`UnitRangedAttack`), same split.
-    ///
-    /// **Player-only, and by a different gate than its two neighbours.** `UnitRangedAttack`
-    /// `0x518b90` is a DIRECT call gated on the PLAYER typemask alone — no vtable slot and **no
-    /// `CGUnit_C` fallback body**. So where
-    /// `UnitDefense` and `UnitAttackBothHands` pass a pet through SELF-OR-MINE and answer
-    /// `level * 5`, this one answers `(0, 0)` for a pet and for every other player too. Mirroring
-    /// [`cgunit_skill`] here would be wrong.
+    /// The ranged weapon's pair, the same split. Player only: `UnitRangedAttack` (`0x518b90`)
+    /// has no creature fallback, so a pet answers `(0, 0)` where `UnitDefense` answers level * 5.
     pub ranged_weapon_skill: (i32, i32),
-    /// The [`SKILL_DEFENSE`] line's pair, in the same `(value + perm, temp)` split as the three
-    /// above and out of the same reader; `UnitDefense` serves it verbatim.
-    ///
-    /// **The player's only.** A creature has no skill block, and the client does not read one for
-    /// it: `UnitDefense` forks on the resolved unit's vtable and gives a non-player
-    /// `UNIT_FIELD_LEVEL * 5` instead ([`cgunit_skill`]), so the pet feed never fills this and the
-    /// binding never reads it for a pet.
+    /// The [`SKILL_DEFENSE`] pair, the same split. The player's only: `UnitDefense` gives a
+    /// non-player level * 5 instead (`cgunit_skill`), so the pet feed leaves it unset.
     pub defense_skill: (i32, i32),
-    /// Whether a wand is equipped (`HasWandEquipped` — the ref swaps the ranged-attack action for
-    /// wand Shoot on it).
+    /// Whether a wand is equipped (`HasWandEquipped`).
     pub has_wand: bool,
-    /// `GetDodgeChance()` / `GetParryChance()` / `GetBlockChance()` — the player's avoidance
-    /// percentages (`PLAYER_DODGE_PERCENTAGE` and its two siblings), already a percent on the
-    /// wire: `2.62` is "2.62%".
-    ///
-    /// **The player's only, and no unit argument.** All three bindings take zero arguments and
-    /// return exactly one number (`reference/1.12-shapes.tsv`: `GetDodgeChance 0x516f00`,
-    /// `GetBlockChance 0x516f60`, `GetParryChance 0x516fc0` — argc 0, arity 1, kind number, all
-    /// `exact`), so there is no pet leg to mirror and no absent answer to model: a field that has
-    /// not streamed reads 0, which is what the wire's own default is.
-    ///
-    /// The shipped 1.12 FrameXML never calls them — the character sheet's own defense block is
-    /// `UnitDefense` — so this trio is addon-facing surface, and the corpus asks for it: four
-    /// vanilla addons read `GetDodgeChance` (FuBar_TankPointsFu, FuBar_DakSmak, Outfitter,
-    /// BetterCharacterStats) and three read each of the other two.
+    /// Avoidance chances, already percents on the wire (`PLAYER_DODGE_PERCENTAGE` and siblings).
     pub dodge_percent: f32,
     pub parry_percent: f32,
     pub block_percent: f32,
 }
 
 impl Default for UnitCombatStats {
-    /// All-zeros except `damage_percent` = `1.0` — the multiplicative identity, so the absent
-    /// shape never feeds the ref's `bonus / percent` math a division by zero.
+    /// All zeros but `damage_percent` 1.0, which stock divides by (`PaperDollFrame.lua:298`).
     fn default() -> Self {
         UnitCombatStats {
             stats: [0; 5],
@@ -244,108 +160,61 @@ impl Default for UnitCombatStats {
     }
 }
 
-/// One resolved equipment/ammo slot view (the `GetInventoryItem*` family reads it), resolved by
-/// the app like [`super::container::ContainerSlot`]: icon from the display catalog, count/quality
-/// from the item object + template. Plain data.
+/// One equipment or ammo slot as the `GetInventoryItem*` family reads it, resolved by the app like
+/// [`super::container::ContainerSlot`].
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct InvSlotView {
     /// The item's template entry (`GetInventoryItemID`).
     pub item_id: u32,
-    /// The doll twin of [`super::container::ContainerSlot::bar_placeable`] — an equipped item
-    /// dragged straight to the bar goes through the same filter.
+    /// Whether the item may go on an action bar, by the same filter as a bag slot's.
     pub bar_placeable: bool,
     /// Icon texture path (`Interface\Icons\…`); `None` while the template answer is in flight.
     pub icon: Option<String>,
-    /// `ITEM_FIELD_STACK_COUNT` — what `GetInventoryItemCount 0x4c8680` pushes for an ordinary
-    /// item (1 for equipment; the ammo slot's own leg puts the carried total here).
+    /// `ITEM_FIELD_STACK_COUNT`, or for the ammo slot the bag-summed carried total.
     pub count: u32,
-    /// What that same function pushes when the item is a **CONTAINER** (`OBJECT_FIELD_TYPE`'s
-    /// `TYPEMASK_CONTAINER` bit — `0x4c87a6`), which is a different number entirely: the sum of
-    /// its contents' stack counts when its `(class, subclass)` row carries `ItemSubClass.dbc`'s
-    /// `DisplayFlags & 0x4` (`0x4c881a`, set on Soul Bag and the quivers only), and **0**
-    /// otherwise. `None` = not a container, and [`Self::count`] answers.
-    ///
-    /// The slot-dependent half of the law is NOT here — it is at the binding, where the reference
-    /// keeps it: a container whose 0-based slot is past `0x16` (everything but the four equipped
-    /// bag slots — the bank's six bag slots included) short-circuits to 0 at `0x4c87af` before any
-    /// of this is read.
+    /// For a container (`TYPEMASK_CONTAINER`, `0x4c87a6`), what `GetInventoryItemCount` pushes:
+    /// its contents' summed stacks when its `ItemSubClass.dbc` row has `DisplayFlags & 0x4` (Soul
+    /// Bag and quivers, `0x4c881a`), else 0; past 0-based slot `0x16` the binding answers 0 first.
     pub contents_count: Option<u32>,
     /// Item quality 0..6 (`GetInventoryItemQuality`).
     pub quality: i32,
-    /// The item's name, when known (tooltip/link consumers).
+    /// The item's name, once known.
     pub name: Option<String>,
-    /// The instance's live durability `(current, max)` — the equipped-item tooltip's
-    /// "Durability X / Y" line (see [`super::container::ContainerSlot::durability`]).
+    /// Live durability `(current, max)`, the tooltip's "Durability X / Y" line.
     pub durability: Option<(u32, u32)>,
-    /// `ITEM_FIELD_FLAGS` (wire field 21) — the alert/broken laws read two bits (`0x4c7ee0`):
-    /// `0x08` wrapped (a gift — never alerts, never broken),
-    /// `0x10` force-red (alert status 4 regardless of durability).
+    /// `ITEM_FIELD_FLAGS`; the alert recompute `0x4c7ee0` reads two bits: `0x10` force-red
+    /// (status 4) and `0x08` wrapped (no durability alert).
     pub flags: u32,
-    /// `0x5da2c0` — **the instance is runtime-bound**: `ITEM_FIELD_FLAGS & 1` (soulbound), or a
-    /// live enchant slot naming a `SpellItemEnchantment` row that binds. App-resolved off the raw
-    /// descriptor (the doll twin of [`super::container::ContainerSlot::already_bound`]); the
-    /// tooltip's bind line overrides to **Soulbound** on it (B310).
+    /// Bound at runtime (`0x5da2c0`): `ITEM_FIELD_FLAGS & 1`, or an enchant whose
+    /// `SpellItemEnchantment` row binds. The tooltip's bind line then says Soulbound.
     pub already_bound: bool,
-    /// An `|Hitem:…|h[Name]|h` link once the name is known — the doll twin of
-    /// `ContainerSlot::link`; carried onto the cursor payload so a world-drop `DELETE_ITEM_CONFIRM`
-    /// off an equipped item can report its name (decision 0208 phase 1b).
+    /// An `|Hitem:…|h[Name]|h` link once the name is known.
     pub link: Option<String>,
-    /// Whether an outstanding pending op covers `(EQUIPMENT_BAG, this slot)` — the app's
-    /// `PendingItemOps` feed (decision 0216 §4/0218 §3), fed by `ui_char.rs::feed_char` the same
-    /// way `ContainerSlot::locked` is. `IsInventoryItemLocked` ORs this with the payload-held-here
-    /// check.
+    /// Whether a pending item operation covers this slot (`IsInventoryItemLocked`).
     pub locked: bool,
-    /// The 1-based live-API inventory slot ids this item could be EQUIPPED into (empty = not
-    /// equippable; an equipped ring's own two finger slots, say) — decision 0208 phase 1b's "the
-    /// fit rule", resolved app-side via `ui_items::find_equip_slot`.
+    /// The 1-based live-API slots this item could be equipped into; empty if none.
     pub equip_slots: Vec<u8>,
-    /// The RESOLVED `ITEM_FIELD_CREATOR` name — the equipped-item tooltip's green
-    /// "<Made by %s>" line (see [`super::container::ContainerSlot::creator`], the bag twin).
+    /// The resolved `ITEM_FIELD_CREATOR` name, the tooltip's "<Made by %s>" line.
     pub creator: Option<String>,
-    /// The instance's resolved enchant slots, in slot order — the doll twin of
-    /// [`super::container::ContainerSlot::enchants`] (decisions 0915/0920). Our own equipped item
-    /// reads all 7 slots off its streamed item object; an INSPECTED player's record carries 7 too
-    /// and the reference renders all 7 from it — but a 1.12 server fills only PERM and TEMP, so in
-    /// practice that is what an inspect hover shows.
+    /// The resolved enchant slots in slot order. An inspected player's record has all 7 too, but
+    /// vmangos fills only PERM and TEMP (`Player.cpp:10518-10519`).
     pub enchants: Vec<super::EnchantView>,
-    /// **The instance's remaining LIFETIME in milliseconds** — the doll twin of
-    /// [`super::container::ContainerSlot::duration_ms`]. `None` = no timer. In practice an
-    /// equipped duration item is rare (the holiday masks are the shipped case), but the line law
-    /// is one law and the doll hover runs the same builder. Decision 1933.
+    /// The instance's remaining lifetime in ms; `None` without a timer.
     pub duration_ms: Option<u64>,
 }
 
-/// The inventory-slot snapshot: index 0 = ammo, 1..=19 the equipment slots, 20..=23 the four
-/// equipped-bag icons (all the client's `GetInventorySlotInfo` slot ids — decision 0216 slice 2's
-/// bag bar). `None` = an empty slot.
+/// The doll snapshot: 0 ammo, 1..=19 equipment, 20..=23 the equipped bags, as
+/// `GetInventorySlotInfo` numbers them; `None` is an empty slot.
 pub const INVENTORY_SLOT_COUNT: usize = 24;
 pub type InventorySlots = [Option<InvSlotView>; INVENTORY_SLOT_COUNT];
 
-/// The six BANK-BAG slots' snapshot, in button order (live-API ids 64..=69 —
-/// `BankButtonIDToInvSlotID(1..6, isBag)`). `None` = the slot is empty (or not purchased).
-///
-/// **A separate dense array rather than a wider [`InventorySlots`]**, because the live-id space
-/// between them is not ours to fill: 24..=39 is the backpack and 40..=63 the vault, and both of
-/// those the model already holds as CONTAINERS — [`Model::inv_slot`]'s bank band maps them rather
-/// than storing them twice. Growing the doll array to 70 would leave a 40-entry hole whose
-/// emptiness means "look somewhere else", which is exactly the kind of implicit second rule that
-/// lets a tooltip disagree with the icon under it. Three bands, three named sources.
-///
-/// Fed by the same system as the doll snapshot ([`super::UiScript::set_bank_bag_slots`]): these
-/// are player-descriptor inventory slots that exist whether or not the bank window is open, not
-/// part of the bank *window*'s state.
+/// The six bank-bag slots in button order, live-API ids 64..=69; `None` is empty or unbought.
+/// They are player-descriptor slots, present whether or not the bank window is open.
 pub const BANK_BAG_SLOT_COUNT: usize = 6;
 pub type BankBagSlots = [Option<InvSlotView>; BANK_BAG_SLOT_COUNT];
 
-/// The client's own `PaperDollItemFrame.dbc` rows (re-verified against the 1.12.1 (build 5875)
-/// MPQ this session, byte-exact — 36 records, 3 `u32` fields each: `SlotName` offset,
-/// `SlotTexture` offset, `SlotID`): `(slotName, slotId, empty-slot art suffix)` for all 36 rows —
-/// the 20 equipment+ammo rows, `Bag0Slot`..`Bag3Slot` (ids **20..23**, every one pointing at the
-/// same `interface\paperdoll\UI-PaperDoll-Slot-Bag.blp`, matching the reference
-/// `CharacterBag0Slot` bag-bar buttons' `GetID()`s), and `Bag1`..`Bag12` (ids 64..75 — the
-/// bank-bag band; see the note over those rows). The oddballs: `BackSlot` shows the **Chest** art
-/// and `AmmoSlot` the **Ranged** art (both confirmed by their `SlotTexture` offset pointing at
-/// that other row's string, not a fresh one).
+/// `PaperDollItemFrame.dbc`'s 36 rows as `(SlotName, SlotID, art suffix)`. The texture column
+/// shares strings between rows, so `BackSlot` shows the Chest art and `AmmoSlot` the Ranged.
 const SLOT_INFO: [(&str, i64, &str); 36] = [
     ("AmmoSlot", 0, "Ranged"),
     ("HeadSlot", 1, "Head"),
@@ -371,16 +240,7 @@ const SLOT_INFO: [(&str, i64, &str); 36] = [
     ("Bag1Slot", 21, "Bag"),
     ("Bag2Slot", 22, "Bag"),
     ("Bag3Slot", 23, "Bag"),
-    // The twelve rows this table was short of. The shipped DBC has **36 records, not 24**, and
-    // `Bag1`..`Bag12` at SlotNumbers 64..75 are in the very table this binding scans — 64..69 is
-    // exactly the bank-bag band `ContainerIDToInventoryID` produces. This file used to call them
-    // "a different, unrelated numbering — not `GetInventorySlotInfo` names, out of scope"; that is
-    // refuted, and the scan reaches them like any other row.
-    //
-    // All twelve share ONE string-block offset with `Bag0Slot`..`Bag3Slot` — sixteen rows, one
-    // string (`+1001`). Read at the offset rather than resolved from the row name, because that is
-    // how this column works: 36 rows carry only 17 distinct offsets, which is why `BackSlot` shows
-    // the Chest art and `AmmoSlot` the Ranged art rather than art of their own.
+    // The bank-bag band is 64..69; all sixteen bag rows share one texture string.
     ("Bag1", 64, "Bag"),
     ("Bag2", 65, "Bag"),
     ("Bag3", 66, "Bag"),
@@ -395,18 +255,13 @@ const SLOT_INFO: [(&str, i64, &str); 36] = [
     ("Bag12", 75, "Bag"),
 ];
 
-/// The durability-alert regions in the client's own slot table (`0x806eb8` — 12 entries): alert
-/// index 1..=11 → the live-id equipment slot (Head,
-/// Shoulders, Chest, Waist, Legs, Feet, Wrists, Hands, Weapon, Shield, Ranged — the ref
-/// FrameXML's `INVENTORY_ALERT_STATUS_SLOTS` order), index 12 → the client's low-ammo region
-/// (slot -1 in its table; FrameXML never reads it, the binding answers it). Our live-id 0 IS
-/// the ammo view, so the 12th entry maps there.
+/// The client's 12 durability-alert regions (`0x806eb8`) as live slot ids: stock's 11
+/// `INVENTORY_ALERT_STATUS_SLOTS` (`DurabilityFrame.lua:2-12`), then low ammo, which the client
+/// table holds as slot -1 and we as the ammo view, slot 0.
 const ALERT_SLOTS: [usize; 12] = [1, 3, 5, 6, 7, 8, 9, 10, 16, 17, 18, 0];
 
-/// The broken classification the doll tint (`GetInventoryItemBroken`) and alert status 4 share
-/// (the recompute `0x4c7ee0`, byte-verified): a wrapped item (`flags & 0x08`) is never broken;
-/// `flags & 0x10` forces broken regardless of durability; else broken ⇔ tracks durability
-/// (max > 0) at 0.
+/// Broken for the doll's red tint, from `0x4c7ee0`'s bits: never when wrapped (`0x08`), else when
+/// force-red (`0x10`) or at durability 0 of a nonzero max.
 fn slot_is_broken(v: &InvSlotView) -> bool {
     if v.item_id == 0 || v.flags & 0x08 != 0 {
         return false;
@@ -414,13 +269,9 @@ fn slot_is_broken(v: &InvSlotView) -> bool {
     v.flags & 0x10 != 0 || matches!(v.durability, Some((0, max)) if max > 0)
 }
 
-/// One region's `GetInventoryAlertStatus` value — the recompute `0x4c7ee0`'s per-item
-/// classification (the enum's own name is `INV_ALERT_STATUS`): `4` (red) = broken per
-/// [`slot_is_broken`]; `3` (yellow) = tracks
-/// durability and **`1..=5` points left — an ABSOLUTE count, no percentage, maxDurability is
-/// only the tracks-durability gate** (`cmp [D+0xa0],5`); `0` otherwise. Statuses 1/2 are the
-/// temp-weapon-enchant alerts (present/expiring-in-30s) — no enchant feed yet, and the 1.12
-/// FrameXML disables their colors anyway; a named deferral.
+/// One region's `GetInventoryAlertStatus` (`0x4c7ee0`): 4 when force-red or broken, 3 with 1..=5
+/// durability points left (an absolute count, not a percentage), else 0. Statuses 1 and 2, the
+/// temporary-enchant alerts, are not fed; stock gives them no color (`DurabilityFrame.lua:18-19`).
 fn alert_status(slot: &Option<InvSlotView>) -> u8 {
     let Some(v) = slot.as_ref().filter(|v| v.item_id != 0) else {
         return 0;
@@ -438,9 +289,7 @@ fn alert_status(slot: &Option<InvSlotView>) -> u8 {
     }
 }
 
-/// The 12th region's low-ammo status (`0x4c7ee0`'s slot −1 arm): an equipped ammo item whose
-/// carried count is `<= 20` reads `3`; no ammo (or plenty) reads `0`. The ammo view's count is
-/// already the bag-summed carried total.
+/// The low-ammo region (`0x4c7ee0`'s slot -1 arm): 3 when the carried ammo is 20 or fewer, else 0.
 fn ammo_alert_status(slot: &Option<InvSlotView>) -> u8 {
     match slot.as_ref().filter(|v| v.item_id != 0) {
         Some(v) if v.count <= 20 => 3,
@@ -449,22 +298,17 @@ fn ammo_alert_status(slot: &Option<InvSlotView>) -> u8 {
 }
 
 impl super::UiScript {
-    /// Push (or clear, with `None`) the player's combat-stats snapshot — the app calls this each
-    /// frame any of the backing descriptor fields changed (decision 0208 §3).
+    /// Push, or clear with `None`, the player's combat-stats snapshot.
     pub fn set_player_combat_stats(&mut self, stats: Option<UnitCombatStats>) {
         self.model_mut().player_combat_stats = stats;
     }
 
-    /// The `"pet"` twin (decision 1057) — `None` whenever there is no pet, which is what makes
-    /// every `Unit*("pet")` fall back to the absent shape the moment one is dismissed.
+    /// The pet's snapshot; `None` without a pet, so `Unit*("pet")` reads the absent shape.
     pub fn set_pet_combat_stats(&mut self, stats: Option<UnitCombatStats>) {
         self.model_mut().pet_combat_stats = stats;
     }
 
-    /// Push the equipment/ammo slot snapshot (index 0 = ammo, 1..=19 equipment). Recomputes the
-    /// 11 durability-alert region statuses off the live pairs; a change fires
-    /// `UPDATE_INVENTORY_ALERTS` — the DurabilityFrame's own repaint signal (the real engine
-    /// computes these statuses itself and fires the same event).
+    /// Push the doll snapshot, recompute the 12 alert statuses and fire `UPDATE_INVENTORY_ALERTS`.
     pub fn set_inventory_slots(&mut self, slots: InventorySlots) {
         {
             let mut model = self.model_mut();
@@ -478,42 +322,24 @@ impl super::UiScript {
             model.inventory_slots = slots;
             model.inventory_alerts = alerts;
         }
-        // Unconditionally, the client's own shape (VERIFIED `0x4c7ee0`: the event fires at the
-        // tail of EVERY recompute, never diffed against prior state) — SetAlerts re-derives the
-        // whole frame from the statuses each time, so glyph choices (the off-hand
-        // shield/off-weapon swap) can never go stale. The app pushes only on real slot-view
-        // change, so this stays quiet between changes.
+        // Every recompute fires it, never diffed against the last (`0x4c7ee0`); the app pushes
+        // only on a real change.
         self.fire_event("UPDATE_INVENTORY_ALERTS", vec![]);
     }
 
-    /// Push the six bank-bag slots ([`BankBagSlots`] — live ids 64..=69).
-    ///
-    /// **The repaint signal is `PLAYERBANKSLOTS_CHANGED`, and nothing else will do** (1771). The
-    /// reference's bank buttons register exactly `BANKFRAME_OPENED`, `PLAYERBANKSLOTS_CHANGED`,
-    /// `ITEM_LOCK_CHANGED` and `CURSOR_UPDATE` (`BankFrameBaseButton_OnLoad`); of those, only the
-    /// first two reach `BankFrameItemButton_OnUpdate`, the icon/count/lock repaint. That function
-    /// is NOT an `OnUpdate` handler despite the name — `BankItemButtonTemplate`'s `<OnUpdate>` is
-    /// `CursorOnUpdate()`, and the repaint is only ever reached from
-    /// `BankFrameItemButton_OnEvent`. `UNIT_INVENTORY_CHANGED`, which rides
-    /// [`Self::set_inventory_slots`] beside this push, is not registered by these buttons at all.
-    /// So `ui_char::feed_char` fires `PLAYERBANKSLOTS_CHANGED` for every bag slot whose ITEM
-    /// changed, and leaves the lock to `ITEM_LOCK_CHANGED`.
+    /// Push the six bank-bag slots. The caller fires `PLAYERBANKSLOTS_CHANGED` for a changed item:
+    /// the stock bank buttons repaint only on it and `BANKFRAME_OPENED` (`BankFrame.lua:206-212`).
     pub fn set_bank_bag_slots(&mut self, slots: BankBagSlots) {
         self.model_mut().bank_bag_slots = slots;
     }
 
-    /// Drain the inventory-slot ids `UseInventoryItem` queued (decision 0208 phase 1b) — the app
-    /// resolves each to the equipped item's guid and sends `CMSG_USE_ITEM` (bag 255 + the
-    /// 0-based wire slot).
+    /// Drain the slot ids `UseInventoryItem` queued; the app sends each as `CMSG_USE_ITEM`, bag
+    /// 255 and the 0-based slot.
     pub fn take_inventory_uses(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().inventory_uses)
     }
 }
 
-/// Read a unit's combat-stats snapshot under a short model borrow, routed by token: `"player"` and
-/// `"pet"` each read their own pushed snapshot, anything else — and a snapshot the app has not
-/// pushed yet — reads the default (the absent shape: zeros, `damage_percent` 1.0). See the module
-/// doc for why exactly these two tokens and no more.
 fn with_unit_stats<T>(
     lua: &Lua,
     token: &Option<String>,
@@ -529,43 +355,23 @@ fn with_unit_stats<T>(
     f(pushed.unwrap_or(&absent))
 }
 
-/// The post-processing both skill-shaped bindings share: **`if (mod + base) < 0 then mod = -base`**
-/// — so the pair can never sum below zero (`0x519298` for `UnitDefense`, `0x5188a7` per hand for
-/// `UnitAttackBothHands`). A debuff deeper than
-/// the skill itself reads as "reduced to 0", never as a negative total.
+/// The clamp `UnitDefense` (`0x519298`) and each hand of `UnitAttackBothHands` (`0x5188a7`) apply:
+/// a modifier below `-base` becomes `-base`, so the total never reads negative.
 fn skill_clamped((base, modifier): (i32, i32)) -> (i64, i64) {
     let base = i64::from(base);
     let modifier = i64::from(modifier);
     (base, if modifier + base < 0 { -base } else { modifier })
 }
 
-/// A **non-player** unit's answer to both skill-shaped questions — `UnitDefense` and
-/// `UnitAttackBothHands` — which is `UNIT_FIELD_LEVEL * 5`, flat.
-///
-/// It is one helper because it is one function in the client: both bindings dispatch through the
-/// resolved unit's vtable, and a `CGUnit_C` lands on a three-line body that multiplies the level by
-/// five and writes 0 to the modifier (`0x613680` / `0x6136b0`). Nothing here is skill data — a
-/// creature has no skill
-/// block at all, which is exactly why the client substitutes a formula.
+/// A non-player's `UnitDefense` and `UnitAttackBothHands` answer: `CGUnit_C`'s vtable bodies
+/// (`0x613680`, `0x6136b0`) return level * 5 with a 0 modifier; a creature has no skill block.
 fn cgunit_skill(model: &Model, token: &str) -> i64 {
     model.unit(token).map_or(0, |u| i64::from(u.level)) * 5
 }
 
-/// Read inventory slot `slot` under a short borrow, cloned out so the caller holds no borrow.
-/// `None` = empty / out of range / a token with no equipment source.
-///
-/// **Unit-keyed, and that is the reference's own shape** (decision 0631): the engine answers
-/// `GetInventoryItemTexture(unit, slot)` for any unit whose item data it holds, which is why the
-/// inspect paper doll reuses the very same bindings rather than a parallel `GetInspectItem*`
-/// family. Two sources, by token:
-///
-/// - `"player"` → the self feed ([`Model::inventory_slots`]), resolved from our PRIVATE
-///   `PLAYER_FIELD_INV_SLOT_*` guids → item objects → templates. Carries counts, durability,
-///   locks — everything an owned item object knows.
-/// - the **inspected** token → [`Model::inspect`], resolved from the target's PUBLIC
-///   `PLAYER_VISIBLE_ITEM_*` entries. No item objects exist for a foreign player (their inventory
-///   guids are server-private), so those views carry entry/icon/name/quality and nothing else —
-///   which is exactly why the reference's inspect window shows no stack counts or durability.
+/// `token`'s inventory slot, unit-keyed as in the reference so the inspect doll reuses these
+/// bindings: `"player"` reads our own items, the inspected unit its public
+/// `PLAYER_VISIBLE_ITEM_*` entries, which carry no counts or durability.
 fn player_inv_slot(lua: &Lua, token: &Option<String>, slot: i64) -> Option<InvSlotView> {
     let token = token.as_deref()?;
     let idx = usize::try_from(slot).ok()?;
@@ -573,30 +379,17 @@ fn player_inv_slot(lua: &Lua, token: &Option<String>, slot: i64) -> Option<InvSl
     model.inv_slot(token, idx)
 }
 
-/// The live-API inventory ids the BANK occupies — `BankButtonIDToInvSlotID`'s own two bands
-/// (`super::bank`): the 24 vault slots at 40..=63, the six bank-bag slots at 64..=69.
+/// The bank's live-API ids, `BankButtonIDToInvSlotID`'s two bands: 24 vault slots, 6 bag slots.
 const BANK_INV_SLOTS: std::ops::RangeInclusive<usize> = 40..=63;
 const BANK_BAG_INV_SLOTS: std::ops::RangeInclusive<usize> = 64..=69;
 
-/// The container id the vault's own slots live under — `ui_items`' constant of the same name,
-/// restated here because this file is the other end of the same map.
+/// The vault's container id; must match `ui_items::BANK_CONTAINER` in the app.
 const BANK_CONTAINER: i64 = -1;
 
 impl Model {
-    /// The equipment slot `token` exposes at live-API id `slot`, or `None`. The one place the
-    /// source routing is decided — shared by the `GetInventoryItem*` getters and
-    /// `GameTooltip:SetInventoryItem`, so a tooltip can never disagree with the icon under it.
-    ///
-    /// **THREE sources now, and the third is a VIEW, not a store** (decision 1751's bank swap).
-    /// The reference's bank paints every one of its slots through the *inventory* API —
-    /// `BankFrameItemButton_OnUpdate` reads `GetInventoryItemTexture("player", BankButtonIDToInv
-    /// SlotID(id))` (BankFrame.lua:35) — while benilla feeds the very same items as *containers*
-    /// (`-1` for the vault, `5..10` for the bank bags), which is how our own bank window read
-    /// them. Those are two names for one set of descriptor fields, so the fix is a map, not a
-    /// second copy: a read in the bank band is answered from the container snapshot. Duplicating
-    /// the items into a wider `inventory_slots` array would put two truths in the model and let
-    /// a tooltip disagree with the icon under it, which is the one thing this function exists to
-    /// prevent.
+    /// The item `token` exposes at live-API id `slot`, the one routing the `GetInventoryItem*`
+    /// getters and `GameTooltip:SetInventoryItem` share. Stock paints the bank through this API
+    /// (`BankFrame.lua:35`), so the bank band is answered from the container snapshot.
     pub(super) fn inv_slot(&self, token: &str, slot: usize) -> Option<InvSlotView> {
         if token.eq_ignore_ascii_case("player") {
             if let Some(view) = self.bank_inv_slot(slot) {
@@ -612,7 +405,6 @@ impl Model {
             .clone()
     }
 
-    /// The bank band's answer, or `None` for any id outside it — see [`Model::inv_slot`].
     fn bank_inv_slot(&self, slot: usize) -> Option<InvSlotView> {
         if BANK_INV_SLOTS.contains(&slot) {
             let vault = self.containers.get(&BANK_CONTAINER)?;
@@ -620,12 +412,8 @@ impl Model {
             return vault.slots.get(&n).map(InvSlotView::from_container_slot);
         }
         if BANK_BAG_INV_SLOTS.contains(&slot) {
-            // A bank BAG is not a slot in a container — it IS one, so there is no container slot
-            // to map and this band is a real store ([`BankBagSlots`], fed off the player
-            // descriptor's own `PLAYER_FIELD_BANK_BAG_SLOT_*` guids by the same system that feeds
-            // the doll). It has to be the whole item, not just its icon: the reference picks a
-            // bank bag up with `PickupBagFromSlot(BankButtonIDToInvSlotID(i, 1))` and describes it
-            // with `GameTooltip:SetInventoryItem("player", …)`, both of which read this band.
+            // A bank bag is a container, not a slot in one, so this band is its own store; stock
+            // picks it up and describes it through this API.
             let i = slot - BANK_BAG_INV_SLOTS.start();
             return self.bank_bag_slots.get(i)?.clone();
         }
@@ -633,15 +421,9 @@ impl Model {
     }
 }
 
-/// The shared inventory-slot reader's whitelist (`0x4c8520`), on the **0-based** value it hands
-/// back (`0x4c8546 dec eax`) — Lua ids are one higher. Anything outside it raises the calling
-/// binding's own "Invalid inventory slot in …", which is not the same thing as an empty answer.
-///
-/// The bands are the reader's own, kept apart rather than merged into one 39..=68 range because
-/// they are different stores: the ammo pseudo-slot, the doll (equipment + the four equipped bag
-/// icons), the bank's 24 vault slots, its 6 bag slots, and the keyring. Note what is NOT here —
-/// the backpack's own 16 item slots (0-based 23..=38) and buyback (69..=80): both are addressed
-/// through the container API instead, and a macro handing either to an inventory binding raises.
+/// The inventory-slot reader's whitelist (`0x4c8520`) on its 0-based slot (`0x4c8546`); outside
+/// it the binding raises "Invalid inventory slot in …". The backpack's item slots (23..=38) and
+/// buyback (69..=80) are container-API slots, not in it.
 fn inventory_slot_reader_accepts(slot0: i32) -> bool {
     slot0 == -1                            // Lua 0      the ammo leg
         || (0x00..=0x16).contains(&slot0)  // Lua 1..=23   the doll + the four equipped bags
@@ -650,7 +432,6 @@ fn inventory_slot_reader_accepts(slot0: i32) -> bool {
         || (0x51..=0x70).contains(&slot0) // Lua 82..=113 the keyring
 }
 
-/// The display name inside an item link — the text between `|h[` and `]|h`.
 fn link_item_name(link: &str) -> Option<String> {
     let (_, rest) = link.split_once("|h[")?;
     let (name, _) = rest.split_once("]|h")?;
@@ -658,11 +439,7 @@ fn link_item_name(link: &str) -> Option<String> {
 }
 
 impl InvSlotView {
-    /// The same item, seen through the inventory API instead of the container API — the map
-    /// [`Model::inv_slot`]'s bank band is built on. Every field is the same descriptor field under
-    /// the other name; what a `ContainerSlot` has and this does not (`equip_slots`, `cooldown`,
-    /// `readable`) has no inventory-API reader, and what this has and a container slot does not
-    /// (`flags`) is not carried by the container feed.
+    /// A container slot seen through the inventory API, for `Model::inv_slot`'s bank band.
     fn from_container_slot(slot: &super::container::ContainerSlot) -> Self {
         InvSlotView {
             item_id: slot.item_id,
@@ -670,9 +447,7 @@ impl InvSlotView {
             icon: slot.texture.clone(),
             count: slot.count,
             quality: slot.quality.map_or(0, |q| q as i32),
-            // A container slot carries no `name` of its own — the container API never asks for one
-            // — but its `link` is composed FROM the name (`|Hitem:…|h[Name]|h`), so the one field
-            // the inventory API adds is recoverable rather than absent.
+            // A container slot has no name, but its link is built from it.
             name: slot.link.as_deref().and_then(link_item_name),
             durability: slot.durability,
             already_bound: slot.already_bound,
@@ -680,65 +455,32 @@ impl InvSlotView {
             locked: slot.locked,
             creator: slot.creator.clone(),
             enchants: slot.enchants.clone(),
-            // Every band this mapper serves — the bank vault, Lua 40..=63 — sits past the
-            // binding's `0x16` short-circuit, so a container met here answers 0 whatever is inside
-            // it and only the `Some`/`None` distinction carries information. "Names Bag0Slot as a
-            // place it could be worn" is the same set as TYPEMASK_CONTAINER (`INVTYPE_BAG` is the
-            // only inventory type `FindEquipSlot` maps there — `cursor::bag_verbs::is_container`
-            // states the equivalence in full), and it is what a container slot carries.
+            // Slot 20 (`Bag0Slot`) among `equip_slots` marks a container (`INVTYPE_BAG`). The bank
+            // vault is past the `0x16` short-circuit, so only `Some` versus `None` matters.
             contents_count: slot.equip_slots.contains(&20).then_some(0),
             ..Default::default()
         }
     }
 }
 
-/// The four reference `.data` literals the two indexed stat bindings raise with — read out of the
-/// shipped 5875 image, verbatim, and NOT paraphrased (the house rule `GetInventorySlotInfo` sets:
-/// an addon may compare or key on the message text).
-///
-/// **Each binding has TWO raises with different strings, and the string pool interleaves them so
-/// that "the nearest `Usage:`" picks the WRONG binding's.** The layout is
-/// `Usage: UnitResistance…` (`0x8510fc`) · `Invalid resistance index…` (`0x85112c`) ·
-/// `Usage: UnitStat…` (`0x851158`) · `Invalid stat index…` (`0x85117c`) — so the `Usage:` two
-/// padding bytes after `UnitResistance`'s index message belongs to `UnitStat`. Each literal is
-/// fixed by the `push <VA>` that names it (`0x5187d6`/`0x5187ed` for `UnitStat`,
-/// `0x5185cb`/`0x5185e2` for `UnitResistance`), never by proximity. This is the same trap
-/// `GetInventorySlotInfo`'s transcription records, one degree worse.
-///
-/// The **index** arm is these two — no `Usage:` prefix, and the offending index is *not*
-/// interpolated (`luaL_error` is called cdecl with exactly two dwords at all four sites: the `L`
-/// and the message, no varargs, so the literal is never a format string).
+/// The reference's verbatim index-arm strings, pushed at `0x5187d6` (`0x85117c`) and `0x5185cb`
+/// (`0x85112c`): no `Usage:` prefix, the index not interpolated. The pool interleaves the two
+/// bindings' strings, so each is fixed by its `push`, never by adjacency.
 const STAT_INDEX_ERROR: &str = "Invalid stat index in UnitStat";
 const RESISTANCE_INDEX_ERROR: &str = "Invalid resistance index in UnitResistance";
-/// The **argument-type** arm — a separate, earlier raise, reached only by a value that is neither
-/// numeric nor a numeric string (the guards are coercion-aware: `UnitStat("player", "3")` serves
-/// stat 3). [`binding_abi`] owns that contract.
+/// The argument-type arm, pushed at `0x5187ed` (`0x851158`) and `0x5185e2` (`0x8510fc`), for a
+/// value neither a number nor a numeric string ([`binding_abi`]).
 const STAT_USAGE: &str = "Usage: UnitStat(\"unit\", statIndex)";
 const RESISTANCE_USAGE: &str = "Usage: UnitResistance(\"unit\", resistanceIndex)";
 
-/// Register the paper-doll stat/slot globals (decision 0208 §3).
+/// Register the paper-doll stat/slot globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // UnitStat("player", i /*1..=5*/) → (stat, effectiveStat, posBuff, negBuff).
-    //
-    // **The first two returns are the same field, UNDECOMPOSED** — `UNIT_FIELD_STAT0+i` raw
-    // (`fild`, `0x518689`), then that same value clamped at zero (`0x5186a3`–`0x5186b7`:
-    // `setl cl; dec ecx; and ecx,eax`). Slots 3/4 are `PLAYER_FIELD_POSSTAT0+i` (`0x518712`) and
-    // `NEGSTAT0+i` (`0x518772`), each behind a SELF gate.
-    //
-    // This served `effective − pos − neg` as the first return until decision 1397. Subtracting is
-    // the ref Lua's *own* job — `PaperDollFrame_SetStats` writes the tooltip's base as
-    // `(stat - posBuff - negBuff)` — so a pre-subtracted `stat` deducts the buff twice. It was
-    // invisible only because pos/neg were stuck at 0 by the field-decode bug 1397 fixes; the two
-    // are one repair.
-    //
-    // **Note the contrast with the two resistance bindings below**, whose first return really *is*
-    // the decomposed base (`0x5efcd0`: `*arg2 = raw - pos - neg`). The reference reads the two
-    // families differently, and the ref Lua's own asymmetry — `SetStats` subtracts, `SetResistances`
-    // and `PaperDollFormatStat` do not — is the tell.
-    //
-    // **An out-of-range index RAISES; it does not answer zeros** (see [`STAT_INDEX_ERROR`]).
+    // UnitStat(unit, 1..=5) → (stat, effectiveStat, posBuff, negBuff): `UNIT_FIELD_STAT0+i` raw
+    // (`0x518689`), then clamped at zero (`0x5186a3`-`0x5186b7`), then `POSSTAT0+i` and
+    // `NEGSTAT0+i` behind a SELF gate (`0x518712`, `0x518772`). Unlike `UnitResistance` it is not
+    // decomposed: stock subtracts the buffs itself (`PaperDollFrame.lua:152`). A bad index raises.
     g.set(
         "UnitStat",
         lua.create_function(|lua, (token, i): (Value, Value)| {
@@ -760,11 +502,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitResistance("player", school /*0..=6*/) → (base, resistance, positive, negative) — the
-    // decomposition helper `0x5efcd0` per school ([0] = armor): `base = raw − pos − neg`, computed
-    // BEFORE the clamp, and `resistance = max(raw, 0)`. A school cursed below zero therefore reads
-    // a *displayed* 0 with the real (negative) total still folded out of `base`.
-    // Out-of-range raises too, with its own string ([`RESISTANCE_INDEX_ERROR`]).
+    // UnitResistance(unit, 0..=6) → (base, resistance, positive, negative) through `0x5efcd0`,
+    // school 0 armor: `base = raw - pos - neg` before the clamp, `resistance = max(raw, 0)`.
     g.set(
         "UnitResistance",
         lua.create_function(|lua, (token, school): (Value, Value)| {
@@ -790,9 +529,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitArmor("player") → (base, effectiveArmor, armor, posBuff, negBuff) — school 0 through the
-    // same `0x5efcd0`, whose 3rd and 4th out-params are both the clamped total (the ref reads
-    // effectiveArmor and armor equivalently, and both are zeroed together when raw < 0).
+    // UnitArmor(unit) → (base, effectiveArmor, armor, posBuff, negBuff): school 0 through
+    // `0x5efcd0`, effectiveArmor and armor both its clamped total.
     g.set(
         "UnitArmor",
         lua.create_function(|lua, token: Option<String>| {
@@ -809,10 +547,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitDamage("player") → (minDamage, maxDamage, minOffHandDamage, maxOffHandDamage,
-    // physicalBonusPos, physicalBonusNeg, percent) — the damage fields verbatim plus the
-    // school-0 MOD_DAMAGE_DONE decomposition (percent 1.0 when absent; decision 0208 "to
-    // confirm" flags the buffed decomposition as inferred).
+    // UnitDamage(unit) → (minDamage, maxDamage, minOffHandDamage, maxOffHandDamage,
+    // physicalBonusPos, physicalBonusNeg, percent): the damage fields verbatim, then school 0's
+    // `MOD_DAMAGE_DONE` split, which is inferred, not traced in the reference.
     g.set(
         "UnitDamage",
         lua.create_function(|lua, token: Option<String>| {
@@ -830,9 +567,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitAttackSpeed("player") → (mainSpeed, offhandSpeed|nil) in seconds (BASEATTACKTIME /
-    // 1000). Offhand is nil unless an offhand weapon is equipped — the snapshot's has_offhand,
-    // the app's call (the field itself streams regardless).
+    // UnitAttackSpeed(unit) → (mainSpeed, offhandSpeed) in seconds; nil offhand without a weapon.
     g.set(
         "UnitAttackSpeed",
         lua.create_function(|lua, token: Option<String>| {
@@ -846,8 +581,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitAttackPower("player") → (base, posBuff, negBuff): base = UNIT_FIELD_ATTACK_POWER, the
-    // buffs the MODS field's split signed halves (neg ≤ 0 — StatSystem.cpp:335-336).
+    // UnitAttackPower(unit) → (base, posBuff, negBuff): `UNIT_FIELD_ATTACK_POWER` and the signed
+    // halves of `_MODS` (vmangos `StatSystem.cpp:335-336`).
     g.set(
         "UnitAttackPower",
         lua.create_function(|lua, token: Option<String>| {
@@ -861,7 +596,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitRangedAttackPower("player") → (base, posBuff, negBuff) — the ranged twin.
+    // UnitRangedAttackPower(unit) → (base, posBuff, negBuff), from the ranged fields.
     g.set(
         "UnitRangedAttackPower",
         lua.create_function(|lua, token: Option<String>| {
@@ -875,21 +610,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitAttackBothHands("player") → (mainBase, mainMod, offBase, offMod) — **FOUR** returns, one
-    // pair per hand: each hand's weapon-skill line, value + its temp+perm bonus, resolved app-side
-    // via the weapon_subclass_skill table (unarmed = SKILL_UNARMED for an empty or non-weapon
-    // hand).
-    //
-    // **It answered two until decision 1810**, which is 1793's shape at its quietest: `0x518810`
-    // calls `[vtbl+0xb0]` TWICE, hand 0 then hand 1, and pushes `(base0, mod0, base1, mod1)`.
-    // The reference's own
-    // `PaperDollFrame_SetAttackBothHands` destructures only the first two — its next line is
-    // `-- FIXME: The offhand stats aren't displayed yet.` — so putting the stock character sheet on
-    // the chain could never have exposed this. An addon reading four gets two nils.
-    //
-    // A non-player unit takes the same virtual fork `UnitDefense` does (`0x6136b0`) and lands on
-    // the identical `level * 5` — and that one **ignores its hand index outright**, so both hands
-    // answer the same pair. The pet sheet's Attack row reads 300 at level 60, like its Defense row.
+    // UnitAttackBothHands(unit) → (mainBase, mainMod, offBase, offMod): `0x518810` calls
+    // `[vtbl+0xb0]` for hand 0 then hand 1. Stock reads only the first pair
+    // (`PaperDollFrame.lua:398-399`). A pet's `CGUnit_C` body (`0x6136b0`) ignores the hand, so
+    // both pairs are `(level * 5, 0)`.
     g.set(
         "UnitAttackBothHands",
         lua.create_function(|lua, token: Option<String>| {
@@ -912,7 +636,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitRangedAttack("player") → (base, modifier) — the ranged weapon's skill pair.
+    // UnitRangedAttack(unit) → (base, modifier), the ranged weapon's skill pair.
     g.set(
         "UnitRangedAttack",
         lua.create_function(|lua, token: Option<String>| {
@@ -925,19 +649,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitDefense(unit) → (base, modifier). The ref reads exactly two numbers and folds the
-    // modifier's sign itself (PaperDollFrame.lua:259-271: modifier > 0 → a green posBuff, < 0 → a
-    // red negBuff).
-    //
-    // **The fork is a VIRTUAL CALL on the resolved unit, not a token test** (correcting decision
-    // 1057's INTERIM):
-    // `[vtbl+0xac]` is either `CGPlayer_C 0x5eda20` — resolve the Defense SkillLine (`0x6de040`)
-    // and read `PLAYER_SKILL_INFO` — or `CGUnit_C 0x613680`, which is three lines:
-    // `*out1 = UNIT_FIELD_LEVEL * 5; *out2 = 0`. **A level-60 pet shows 300**,
-    // not the 0 that 1057 shipped. The outer gate is SELF **or**
-    // `UNIT_FIELD_SUMMONEDBY == my guid`, which our pet passes and no other token we serve does —
-    // so `"player"` takes the skill leg, `"pet"` the level leg (a warlock's minion included: it is
-    // summoned by us too), and everything else the gate-failure zeros.
+    // UnitDefense(unit) → (base, modifier); stock splits the modifier's sign itself
+    // (`PaperDollFrame.lua:259-271`). The gate is SELF or `UNIT_FIELD_SUMMONEDBY` = us, then
+    // `[vtbl+0xac]`: `CGPlayer_C` `0x5eda20` reads the Defense skill (`0x6de040`), `CGUnit_C`
+    // `0x613680` answers level * 5 and 0. Any other token gets the gate's zeros.
     g.set(
         "UnitDefense",
         lua.create_function(|lua, token: Option<String>| {
@@ -953,10 +668,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetDodgeChance() / GetParryChance() / GetBlockChance() → one number each, no unit argument
-    // (`reference/1.12-shapes.tsv`, all three `exact` on argc, arity and kind). Player-implicit,
-    // like `HasWandEquipped` below; a field that has not streamed reads 0, which is the wire's own
-    // default rather than an absence to model.
+    // GetDodgeChance(), GetParryChance(), GetBlockChance() → one number each, no unit argument
+    // (`0x516f00`, `0x516fc0`, `0x516f60`); 0 before the field streams.
     for (name, pick) in [
         ("GetDodgeChance", 0usize),
         ("GetParryChance", 1),
@@ -978,9 +691,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // UnitRangedDamage("player") → (speed, minDamage, maxDamage, physicalBonusPos,
-    // physicalBonusNeg, percent) — RANGEDATTACKTIME/1000 + the ranged damage range + the same
-    // school-0 mods as UnitDamage.
+    // UnitRangedDamage(unit) → (speed, minDamage, maxDamage, physicalBonusPos, physicalBonusNeg,
+    // percent), with `UnitDamage`'s school-0 mods.
     g.set(
         "UnitRangedDamage",
         lua.create_function(|lua, token: Option<String>| {
@@ -997,8 +709,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // HasWandEquipped() → 1/nil (the ref's ranged block swaps "Shoot" in on it). No unit arg —
-    // the live global is player-implicit.
+    // HasWandEquipped() → 1 or nil, for the player.
     g.set(
         "HasWandEquipped",
         lua.create_function(|lua, ()| {
@@ -1012,8 +723,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInventoryItemID("player", slot) → itemId | nil (slot per GetInventorySlotInfo: 0 ammo,
-    // 1..=19 equipment). Player-token-only like the stat block — the INV_SLOT guids are PRIVATE.
+    // GetInventoryItemID(unit, slot) → itemId or nil.
     g.set(
         "GetInventoryItemID",
         lua.create_function(|lua, (token, slot): (Option<String>, i64)| {
@@ -1024,8 +734,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInventoryItemTexture("player", slot) → icon path | nil (nil while the template answer is
-    // in flight — the button shows the empty-slot art until the push lands).
+    // GetInventoryItemTexture(unit, slot) → icon path, or nil until the item's template arrives.
     g.set(
         "GetInventoryItemTexture",
         lua.create_function(|lua, (token, slot): (Option<String>, i64)| {
@@ -1036,12 +745,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInventoryItemLink(unit, slot) → the full escaped `|cff…|Hitem:…|h[Name]|h|r` | nil (nil
-    // while the template answer is in flight — the link is built from the item's name + quality,
-    // and neither is known until it lands). Unit-keyed like its siblings, so the reference's paper
-    // doll and its inspect twin both reach it from one binding:
-    // `DressUpItemLink(GetInventoryItemLink("player", this:GetID()))` (PaperDollFrame.lua:650) and
-    // the shift-click `ChatFrameEditBox:Insert(...)` beside it (l.653). Decision 1059.
+    // GetInventoryItemLink(unit, slot) → `|cff…|Hitem:…|h[Name]|h|r`, or nil until the template
+    // arrives with the name and quality.
     g.set(
         "GetInventoryItemLink",
         lua.create_function(|lua, (token, slot): (Option<String>, i64)| {
@@ -1052,32 +757,14 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The binding's own two `.data` literals, read out of the shipped 5875 image and NOT
-    // paraphrased (the house rule `GetInventorySlotInfo` set: an addon may compare on the text).
-    // Neither carries a period or a newline.
-    //
-    //   `0x8489b4`  arg 1 fails `is-number-or-string 0x6f3510`
-    //   `0x848984`  arg 2 fails `lua_isnumber`, OR names a slot outside the reader's whitelist
-    //
-    // (`0x848b54` is the sibling `Invalid inventory slot in IsInventoryItemLocked`, unclaimed
-    // here: that binding's own argument reader has not been carved, and guessing it is exactly
-    // what this block exists to stop.)
+    // The reference's verbatim strings: `0x8489b4` when arg 1 is neither number nor string
+    // (`0x6f3510`), `0x848984` when arg 2 is not a number or not a whitelisted slot.
     const USAGE_GET_INVENTORY_ITEM_COUNT: &str = "Usage: GetInventoryItemCount(unit, slot)";
     const INVALID_SLOT_GET_INVENTORY_ITEM_COUNT: &str =
         "Invalid inventory slot in GetInventoryItemCount";
-    // GetInventoryItemCount("player", slot) — CARVED (`0x4c8680`), and it is nothing like the
-    // shape every secondary source describes. Four answers, in the reference's own order:
-    //
-    //  · an EMPTY slot pushes **1**, not 0 (`0x4c8797`). Both FrameXML callers gate on
-    //    `GetInventoryItemTexture` first, which is why nobody ever noticed.
-    //  · a non-container pushes `ITEM_FIELD_STACK_COUNT`.
-    //  · a CONTAINER (`OBJECT_FIELD_TYPE & 4`, `0x4c87a6`) in a slot whose 0-based id is **past
-    //    `0x16`** pushes a literal 0 (`0x4c87af cmp …,0x16` / `jg 0x4c8813`) — before any lookup.
-    //    The bank's six bag slots (Lua 64..69 → 0-based 63..68) are all in that band, which is the
-    //    whole reason `BankFrameBag1` shows no digit in the real client: `SetItemButtonCount`'s
-    //    `isBag and count > 0` arm never fires.
-    //  · a CONTAINER in one of the four equipped bag slots pushes the `ItemSubClass.dbc`-gated
-    //    sum of its contents — see [`InvSlotView::contents_count`].
+    // GetInventoryItemCount(unit, slot) (`0x4c8680`): an empty slot pushes 1 (`0x4c8797`), a
+    // non-container its stack count, a container past 0-based slot `0x16` 0 before any lookup
+    // (`0x4c87af`, so a bank bag shows no digit), and an equipped bag its `contents_count`.
     g.set(
         "GetInventoryItemCount",
         lua.create_function(|lua, (unit, slot): (Value, Value)| {
@@ -1101,8 +788,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInventoryItemQuality("player", slot) → 0..6 | nil (nil for an empty slot — the wiki
-    // shape; the ref keys quality borders on it).
+    // GetInventoryItemQuality(unit, slot) → 0..6, or nil for an empty slot (the wiki's shape).
     g.set(
         "GetInventoryItemQuality",
         lua.create_function(|lua, (token, slot): (Option<String>, i64)| {
@@ -1113,10 +799,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInventoryItemBroken("player", slot) → 1 | nil — the shared broken classification
-    // ([`slot_is_broken`]: durability 0 with a max, or the force-red flag bit; wrapped never).
-    // The ref's PaperDollItemSlotButton_Update keys the red slot tint on it
-    // (PaperDollFrame.lua:670-676).
+    // GetInventoryItemBroken(unit, slot) → 1 or nil, per `slot_is_broken`.
     g.set(
         "GetInventoryItemBroken",
         lua.create_function(|lua, (token, slot): (Option<String>, i64)| {
@@ -1127,22 +810,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInventoryItemCooldown(unit, slot) → (start, duration, enable), the EQUIPPED twin of
-    // `GetContainerItemCooldown` (container.rs) and the same `GetTime`-clock convention.
-    //
-    // **It answers "no cooldown" and that is an absent FEED, not a pretended one.** benilla has no
-    // equipped-item cooldown source yet — the same gap `tooltip_item`'s `SetInventoryItem` already
-    // records where it leaves `hasCooldown` nil — so there is nothing to report and `(0, 0, 1)` is
-    // exactly what the container twin answers for a slot with no record. It is bound rather than
-    // left absent because the SOURCED `PaperDollFrame.lua` calls it UNCONDITIONALLY, once per
-    // `PaperDollItemSlotButton_Update`: without it every button built from
-    // `PaperDollItemSlotButtonTemplate` or `BagSlotButtonTemplate` raises inside its own OnLoad,
-    // which is how pfUI's bag bar would meet it. A raise there is not the loud-and-correct kind
-    // (1203) — it is a raise on a verb whose honest answer we already know.
-    //
-    // When an equipped-cooldown feed lands, this reads it the way the container twin reads
-    // `container_cooldowns`, and the CooldownFrame the doll slots already carry starts sweeping
-    // with no caller change.
+    // GetInventoryItemCooldown(unit, slot) → (start, duration, enable). Not fed: with no
+    // equipped-item cooldown source it answers `(0, 0, 1)`, no cooldown, as the container verb
+    // does; stock calls it on every slot update (`PaperDollFrame.lua:691`).
     g.set(
         "GetInventoryItemCooldown",
         lua.create_function(|_, (_token, _slot): (Option<String>, i64)| {
@@ -1150,10 +820,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInventoryAlertStatus(index) → the region's alert status (`INV_ALERT_STATUS`: 0 none,
-    // 3 damaged/low-ammo, 4 broken; 1/2 = temp-enchant alerts, unfed) — DurabilityFrame's
-    // armor-guy read. Valid 1..=12 (the client's own 12-entry table; index 12 = low ammo, which
-    // the 1.12 FrameXML never reads); out-of-range reads 0.
+    // GetInventoryAlertStatus(index) → the status of region 1..=12: 0 none, 3 damaged or low ammo,
+    // 4 broken.
     g.set(
         "GetInventoryAlertStatus",
         lua.create_function(|lua, index: usize| {
@@ -1166,9 +834,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // OffhandHasWeapon() → 1 | nil — whether the off-hand slot holds a WEAPON (item class 2)
-    // rather than a shield/held-in-off-hand; DurabilityFrame.lua swaps the shield glyph for the
-    // off-weapon glyph on it. Read off the equipped slot view + the template store.
+    // OffhandHasWeapon() → 1 or nil: whether the off hand holds a weapon (item class 2).
     g.set(
         "OffhandHasWeapon",
         lua.create_function(|lua, (): ()| {
@@ -1182,64 +848,33 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInventorySlotInfo(slotName) → (slotId, textureName, checkRelic) — the client's own
-    // PaperDollItemFrame.dbc rows (SLOT_INFO above). An unknown name is a Lua error, the client's
-    // own behavior.
-    //
-    // `checkRelic` is the number 1 for the ranged slot and nil elsewhere, unconditionally — it is
-    // a property of the SLOT, not of the player. It pairs with `UnitHasRelicSlot("player")`,
-    // which is the class half, and stock reads the two as a conjunction
-    // (`PaperDollFrame.lua:680`/`:744`). This comment used to say `UnitHasRelicSlot` is a
-    // later-era concept, always false in vanilla; it is not — decision 1796.
+    // GetInventorySlotInfo(slotName) → (slotId, textureName, checkRelic) from `SLOT_INFO`.
+    // `checkRelic` is a property of the slot; stock pairs it with `UnitHasRelicSlot("player")`
+    // (`PaperDollFrame.lua:680`, `:744`).
     g.set(
         "GetInventorySlotInfo",
         lua.create_function(|lua, name: String| {
-            // **The name match is CASE-INSENSITIVE, and that was the whole bug.** `0x4c8215` calls
-            // `0x64a4c0` -> `0x414310`, the CRT `_strnicmp`, whose comparison folds BOTH operands
-            // (`0x414352 add ah,dh` / `0x41435c add al,dh`, with `dh = 0x20` and the A-Z bounds in
-            // `bh`/`bl`) before the byte compare — ASCII folding, which is exactly
-            // `eq_ignore_ascii_case`. Its locale-aware arm folds too, so the verdict does not
-            // depend on one. `maxlen` is `0x7fffffff` and the loop stops at the first NUL on either
-            // side, so it is a FULL-STRING compare, not a prefix. The non-circular control is that
-            // the image also ships a byte-identical case-SENSITIVE wrapper (`0x64a480` ->
-            // `0x40de80`, `rep cmpsb`, no fold) and this binding does not call it.
-            //
-            // Two 1.12-era corpus addons died at session start on this and both worked on the real
-            // client: `FuBar_AmmoFu` passes `"ammoSlot"` and `FuBar_PoisonFu` `"MAINHANDSLOT"`.
-            // The 36 shipped names stay pairwise distinct after folding, so first-match-wins cannot
-            // become ambiguous.
+            // A full-string ASCII case-insensitive match: `0x4c8215` calls `_strnicmp` (`0x64a4c0`
+            // -> `0x414310`) with no length limit. The 36 names stay distinct after folding.
             let Some((_, id, art)) = SLOT_INFO
                 .iter()
                 .find(|(n, _, _)| n.eq_ignore_ascii_case(&name))
             else {
-                // The raise is faithful — there is no nil path, and `0x4c823c xor eax,eax; ret` is
-                // dead code after `luaL_error` longjmps. The message is the reference's own
-                // (`.rdata 0x848894`): no `Usage:` prefix, and the offending name is NOT
-                // interpolated. The `Usage:` literals either side of it in the string pool belong
-                // to `KeyRingButtonIDToInvSlotID` and `GetInventoryItemTexture` — the adjacency
-                // trap.
+                // An unknown name raises, never nil; the string is `0x848894`'s, verbatim.
                 return Err(mlua::Error::runtime(
                     "Invalid inventory slot in GetInventorySlotInfo",
                 ));
             };
             Ok((
                 *id,
-                // The DBC string, VERBATIM. `0x4c825b` pushes `[esi+4]` straight through
-                // (`0x6f3890`, `repne scasb` for the length) with no normalisation anywhere, and
-                // the stored bytes are `interface\paperdoll\UI-PaperDoll-Slot-Bag.blp` — a
-                // LOWERCASE directory, and the `.blp` extension present. Only the
-                // `UI-PaperDoll-Slot-` leaf is mixed case. Texture *loading* would not care (the
-                // asset VFS folds case), but this is a Lua-visible string: anything that compares
-                // it, keys a table by it or concatenates it sees these bytes.
+                // The DBC's bytes verbatim, unnormalised (`0x4c825b`): a lowercase directory and
+                // the `.blp` extension, visible to any Lua that compares the string.
                 Value::String(
                     lua.create_string(format!(
                         "interface\\paperdoll\\UI-PaperDoll-Slot-{art}.blp"
                     ))?,
                 ),
-                // `checkRelic` — the NUMBER 1, never a boolean, and only for `RangedSlot`
-                // (`0x4c8263 dec ecx; cmp ecx,0x11`, i.e. SlotNumber 18); nil for every other slot.
-                // It shipped as a constant `false` here, which is falsey like nil but is the wrong
-                // type for a caller that compares it to 1, and wrong outright for the ranged slot.
+                // `checkRelic`: the number 1 for `RangedSlot` only (`0x4c8263`), not a boolean.
                 if *id == 18 {
                     Value::Integer(1)
                 } else {
@@ -1298,8 +933,7 @@ mod tests {
         }
     }
 
-    /// A pet's snapshot: the UNIT half filled, every PLAYER-block-sourced field at its default —
-    /// what `ui_char::unit_combat_stats` really produces over a creature's descriptor.
+    /// A pet's snapshot: the UNIT fields filled, the PLAYER-block ones at their defaults.
     fn pet_stats() -> UnitCombatStats {
         UnitCombatStats {
             stats: [63, 45, 68, 32, 42],
@@ -1334,26 +968,16 @@ mod tests {
         assert_eq!(weapon_subclass_skill(18), Some(226)); // crossbow
         assert_eq!(weapon_subclass_skill(19), Some(228)); // wand
         assert_eq!(weapon_subclass_skill(20), Some(356)); // fishing pole
-                                                          // The skill-less rows + out of range.
         for sub in [9u32, 11, 12, 14, 21, 100] {
             assert_eq!(weapon_subclass_skill(sub), None, "subclass {sub}");
         }
     }
 
-    /// **The three avoidance verbs are player-implicit and answer ONE number each.**
-    ///
-    /// `reference/1.12-shapes.tsv` has all three at argc 0 / arity 1 / kind number, every column
-    /// `exact` (`GetDodgeChance 0x516f00`, `GetBlockChance 0x516f60`, `GetParryChance 0x516fc0`),
-    /// so an argument is ignored rather than resolved and there is no pet leg. The absent
-    /// snapshot answers 0 — the wire's own default for a field that has not streamed, and the
-    /// only answer a one-number arity can give.
-    ///
-    /// The three values below are exactly representable in `f32`, so the widening to Lua's double
-    /// is lossless and the assertions can be equalities rather than epsilons.
+    /// The values are exact in `f32`, so the assertions compare equal.
     #[test]
     fn the_avoidance_verbs_are_player_implicit_and_answer_one_number() {
         let mut s = UiScript::new().unwrap();
-        // Before anything streams: a number, not nil — the arity is exact.
+        // Before anything streams: 0, not nil.
         assert_eq!(s.eval::<f64>("return GetDodgeChance()").unwrap(), 0.0);
         s.set_player_combat_stats(Some(UnitCombatStats {
             dodge_percent: 5.25,
@@ -1364,8 +988,7 @@ mod tests {
         assert_eq!(s.eval::<f64>("return GetDodgeChance()").unwrap(), 5.25);
         assert_eq!(s.eval::<f64>("return GetParryChance()").unwrap(), 3.5);
         assert_eq!(s.eval::<f64>("return GetBlockChance()").unwrap(), 2.75);
-        // Exactly one return, and a unit token is not a parameter — an addon passing one gets the
-        // player's number, which is what a zero-argc binding does with a stack it never reads.
+        // One return, and a unit argument is ignored.
         assert_eq!(
             s.eval::<i64>("local a, b = GetDodgeChance() return b == nil and 1 or 2")
                 .unwrap(),
@@ -1381,21 +1004,19 @@ mod tests {
     fn unit_stat_serves_the_raw_field_twice_and_the_buff_split() {
         let mut s = UiScript::new().unwrap();
         s.set_player_combat_stats(Some(stats()));
-        // Str: the raw field 25 in BOTH of the first two slots, then the +4/0 split. The ref Lua
-        // does the subtraction itself (`stat - posBuff - negBuff` = 21 for the tooltip's base) —
-        // this binding must not pre-subtract, or the buff is deducted twice.
+        // Str: raw 25 in both first slots; stock subtracts the +4 itself.
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(r#"return UnitStat("player", 1)"#)
                 .unwrap(),
             (25, 25, 4, 0)
         );
-        // Agi: raw 20 with a −2 debuff (the ref tests negBuff < 0 to pick red over green).
+        // Agi: raw 20 with a −2 debuff.
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(r#"return UnitStat("player", 2)"#)
                 .unwrap(),
             (20, 20, 0, -2)
         );
-        // Only the SECOND return is clamped: a stat driven below zero keeps its sign in slot 1.
+        // Only the second return is clamped.
         s.set_player_combat_stats(Some(UnitCombatStats {
             stats: [-3, 20, 22, 10, 11],
             ..stats()
@@ -1406,7 +1027,6 @@ mod tests {
             (-3, 0, 4, 0)
         );
         s.set_player_combat_stats(Some(stats()));
-        // A non-player token serves the absent zeros (no other unit streams these fields).
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(r#"return UnitStat("target", 1)"#)
                 .unwrap(),
@@ -1414,10 +1034,8 @@ mod tests {
         );
     }
 
-    /// The index arm **raises**, and the truncation that decides which side of the range an
-    /// argument lands on happens FIRST. Both ends converge on one raise (`0x51865a js` and
-    /// `0x518663 jge` → `0x5187d6`), and `_ftol` chops toward zero rather than flooring, so `1.9`
-    /// is a valid `1` while `0.5` and any negative are not.
+    /// The index truncates toward zero (`_ftol`) ahead of the range test (`0x51865a`,
+    /// `0x518663`): 1.9 is stat 1, while 0.5 and any negative raise.
     #[test]
     fn an_out_of_range_stat_index_raises_the_references_own_string() {
         let mut s = UiScript::new().unwrap();
@@ -1431,23 +1049,20 @@ mod tests {
                 msg.contains(STAT_INDEX_ERROR),
                 "UnitStat(\"player\", {arg}) must raise {STAT_INDEX_ERROR:?}, got {msg:?}"
             );
-            // The index arm carries no `Usage:` prefix, and the pool's interleaving makes the
-            // WRONG binding's usage line the nearest one — so assert we took neither.
             assert!(!msg.contains("Usage:"), "no Usage: prefix on the index arm");
         }
-        // Truncation toward zero, ahead of the range test: 1.9 → 1 → stat 0, the valid answer.
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(r#"return UnitStat("player", 1.9)"#)
                 .unwrap(),
             (25, 25, 4, 0)
         );
-        // The guard is coercion-aware — a numeric STRING is a number here.
+        // A numeric string is a number.
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(r#"return UnitStat("player", "2")"#)
                 .unwrap(),
             (20, 20, 0, -2)
         );
-        // Neither numeric nor a numeric string takes the OTHER raise, with the other string.
+        // Anything else takes the Usage arm.
         for arg in ["nil", "{}", "true", r#""abc""#] {
             let msg = format!(
                 "{}",
@@ -1459,8 +1074,7 @@ mod tests {
                 "UnitStat(\"player\", {arg}) must take the Usage arm, got {msg:?}"
             );
         }
-        // A missing unit token fails the same way (`0x6f3510` reports NULL past the top as
-        // neither number nor string).
+        // A missing unit fails the same way: `0x6f3510` sees neither number nor string.
         assert!(format!(
             "{}",
             s.eval::<i64>(r#"return UnitStat(nil, 1)"#).unwrap_err()
@@ -1484,27 +1098,24 @@ mod tests {
                 .unwrap(),
             (0, 20, 25, -5)
         );
-        // A school cursed below zero (arcane: −5 total, all from the debuff): the DISPLAYED total
-        // is clamped to 0 (`0x5efcd0`'s tail), while `base` keeps the pre-clamp decomposition.
+        // Arcane cursed to −5: the displayed total clamps to 0, `base` keeps the pre-clamp split.
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(r#"return UnitResistance("player", 6)"#)
                 .unwrap(),
             (0, 0, 0, -5)
         );
-        // UnitArmor is school 0 with the five-return shape (effectiveArmor = armor = the total).
+        // UnitArmor is school 0, effectiveArmor = armor = the total.
         assert_eq!(
             s.eval::<(i64, i64, i64, i64, i64)>(r#"return UnitArmor("player")"#)
                 .unwrap(),
             (130, 150, 150, 30, -10)
         );
-        // A non-player token: zeros. (UnitArmor takes no index and so has no index raise.)
         assert_eq!(
             s.eval::<(i64, i64, i64, i64, i64)>(r#"return UnitArmor("target")"#)
                 .unwrap(),
             (0, 0, 0, 0, 0)
         );
-        // Out of range RAISES, with UnitResistance's own string — not UnitStat's, which is the
-        // literal sitting two padding bytes away in the reference's string pool.
+        // Out of range raises `UnitResistance`'s own string, not the adjacent `UnitStat` one.
         for arg in ["7", "-1"] {
             let msg = format!(
                 "{}",
@@ -1518,7 +1129,7 @@ mod tests {
                 "UnitResistance(\"player\", {arg}) must raise {RESISTANCE_INDEX_ERROR:?}, got {msg:?}"
             );
         }
-        // School 0 is in range and is armor — the low end is inclusive, unlike UnitStat's.
+        // School 0 is in range, unlike `UnitStat`'s index 0.
         assert!(s
             .eval::<(i64, i64, i64, i64)>(r#"return UnitResistance("player", 0)"#)
             .is_ok());
@@ -1533,11 +1144,10 @@ mod tests {
                 .unwrap(),
             (12.5, 19.5, 5.0, 9.0, 25, -3, f64::from(1.1f32))
         );
-        // No offhand equipped → second return nil.
+        // No off-hand weapon: the second return is nil.
         assert!(s
             .eval::<bool>(r#"local m, o = UnitAttackSpeed("player") return m == 2.9 and o == nil"#)
             .unwrap());
-        // With an offhand: both speeds, in seconds.
         s.set_player_combat_stats(Some(UnitCombatStats {
             has_offhand: true,
             ..stats()
@@ -1547,7 +1157,7 @@ mod tests {
                 .unwrap(),
             (2.9, 1.5)
         );
-        // Absent snapshot / non-player token: zeros, percent 1.0 (the div-safe identity).
+        // Another token, or no snapshot: zeros and percent 1.0.
         assert_eq!(
             s.eval::<(f64, f64, f64, f64, i64, i64, f64)>(r#"return UnitDamage("target")"#)
                 .unwrap(),
@@ -1592,7 +1202,6 @@ mod tests {
                 .unwrap(),
             (2.8, 31.0, 47.0, 25, -3, f64::from(1.1f32))
         );
-        // Non-player: the absent zeros throughout.
         assert_eq!(
             s.eval::<(i64, i64, i64)>(r#"return UnitAttackPower("target")"#)
                 .unwrap(),
@@ -1605,18 +1214,9 @@ mod tests {
         );
     }
 
-    /// **`UnitRangedAttack` does NOT take the pet fork its two neighbours take** (decision 1812).
-    ///
-    /// `UnitDefense` `0x519200` and `UnitAttackBothHands` `0x518810` gate on SELF-OR-MINE and then
-    /// dispatch through the resolved unit's vtable, so a pet passes and lands on `CGUnit_C`'s
-    /// `level * 5`. `UnitRangedAttack` `0x518b90` is a **direct call** gated on the PLAYER typemask
-    /// alone, with no vtable slot and **no `CGUnit_C` fallback body at all** — `0x612b40`,
-    /// `0x5edae0` and `0x5ea460` appear as a dword zero times image-wide, against a positive
-    /// control of one hit each for the four addresses that ARE in a vtable.
-    ///
-    /// So a pet's ranged attack is `(0, 0)`, not `level * 5`. The whole reason this is a test and
-    /// not a comment is that the three verbs look interchangeable from the FrameXML side, and
-    /// mirroring the defense handling here would be a plausible, silent, wrong number.
+    /// `UnitDefense` (`0x519200`) and `UnitAttackBothHands` (`0x518810`) fork through the unit's
+    /// vtable to a creature body; `UnitRangedAttack` (`0x518b90`) is a direct call gated on the
+    /// PLAYER typemask (`0x612b40`, `0x5edae0`, `0x5ea460` are in no vtable), so a pet gets zeros.
     #[test]
     fn ranged_attack_gives_a_pet_zeros_where_defense_gives_it_level_times_five() {
         let mut s = UiScript::new().unwrap();
@@ -1642,7 +1242,7 @@ mod tests {
             (0, 0),
             "no fork, no fallback body — a pet fails the PLAYER typemask and gets zeros"
         );
-        // …and so does another PLAYER, which is the same gate seen from the other side.
+        // Another player gets zeros too.
         assert_eq!(
             s.eval::<(i64, i64)>(r#"return UnitRangedAttack("target")"#)
                 .unwrap(),
@@ -1650,17 +1250,7 @@ mod tests {
         );
     }
 
-    /// **`UnitAttackBothHands` pushes FOUR values, one pair per hand — and it pushed two until
-    /// decision 1810.**
-    ///
-    /// The quietest shape decision 1793 describes: `0x518810` calls `[vtbl+0xb0]` twice, hand 0
-    /// then hand 1, and pushes `(base0, mod0, base1, mod1)`. The reference's own
-    /// `PaperDollFrame_SetAttackBothHands` destructures only the first two — its very next line is
-    /// `-- FIXME: The offhand stats aren't displayed yet.` — so no amount of running the stock
-    /// character sheet could have exposed it. An addon reading four got two nils.
-    ///
-    /// The pet leg is here too because it is the same call: `CGUnit_C 0x6136b0` takes a hand index
-    /// and **never reads it**, so both hands answer the identical `level * 5`.
+    /// `0x518810` pushes `(base0, mod0, base1, mod1)`, one pair per hand.
     #[test]
     fn attack_both_hands_answers_a_pair_per_hand() {
         let mut s = UiScript::new().unwrap();
@@ -1675,8 +1265,7 @@ mod tests {
             (300, 5, 275, -12),
             "each hand's own skill line, in hand order"
         );
-        // …and the per-hand clamp the binding applies after each virtual call
-        // (`0x5188a7`: `if (out2 + out1 < 0) out2 = -out1`), which `UnitDefense` shares.
+        // The per-hand clamp (`0x5188a7`), which `UnitDefense` shares.
         s.set_player_combat_stats(Some(UnitCombatStats {
             main_weapon_skill: (40, -100),
             offhand_weapon_skill: (40, -40),
@@ -1697,18 +1286,13 @@ mod tests {
         );
     }
 
-    /// **The pet routing, end to end** (decision 1057) — the thing no build gate can catch: a
-    /// pushed pet snapshot really is what `Unit*("pet")` answers, while `"player"` still answers
-    /// the player's and a third token still answers the absent shape. The failure this guards is
-    /// silent: a mis-routed reader shows a pet sheet full of the *player's* numbers, or of zeros,
-    /// and nothing errors.
     #[test]
     fn the_pet_token_reads_the_pet_snapshot_and_only_it() {
         let mut s = UiScript::new().unwrap();
         s.set_player_combat_stats(Some(stats()));
         s.set_pet_combat_stats(Some(pet_stats()));
 
-        // Stamina (index 3): the pet's 68 with no buff split, the player's 22 with its own.
+        // Stamina: the pet's 68, the player's 22.
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(r#"return UnitStat("pet", 3)"#)
                 .unwrap(),
@@ -1719,8 +1303,7 @@ mod tests {
                 .unwrap(),
             (22, 22, 0, 0)
         );
-        // Str, where the two genuinely differ AND the player carries a buff: the pet must not
-        // inherit either number.
+        // Str, where the player carries a buff the pet must not inherit.
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(r#"return UnitStat("pet", 1)"#)
                 .unwrap(),
@@ -1731,7 +1314,7 @@ mod tests {
                 .unwrap(),
             (25, 25, 4, 0)
         );
-        // Resistances: fire (school 2) — 15 for the pet, 20 (+25/−5) for the player.
+        // Fire resistance: the pet's 15, the player's 20 (+25/−5).
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(r#"return UnitResistance("pet", 2)"#)
                 .unwrap(),
@@ -1753,8 +1336,7 @@ mod tests {
                 .unwrap(),
             (130, 150, 150, 30, -10)
         );
-        // The rest of the family routes too — and `percent` stays the divide-safe 1.0 for the pet
-        // (the ref Lua divides the damage range by it).
+        // The rest routes too; the pet's `percent` stays 1.0.
         assert_eq!(
             s.eval::<(f64, f64, f64, f64, i64, i64, f64)>(r#"return UnitDamage("pet")"#)
                 .unwrap(),
@@ -1765,12 +1347,11 @@ mod tests {
                 .unwrap(),
             (178, 12, -4)
         );
-        // No offhand ⇒ the second return is nil, the same gate as the player's.
         assert!(s
             .eval::<bool>(r#"local m, o = UnitAttackSpeed("pet") return m == 2.0 and o == nil"#)
             .unwrap());
 
-        // A third token is still the absent shape…
+        // A third token is still the absent shape.
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(r#"return UnitStat("target", 1)"#)
                 .unwrap(),
@@ -1781,7 +1362,7 @@ mod tests {
                 .unwrap(),
             (0, 0, 0, 0, 0)
         );
-        // …and so is `"pet"` once the pet is dismissed (the feed pushes None).
+        // So is `"pet"` once the pet is dismissed (the feed pushes `None`).
         s.set_pet_combat_stats(None);
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(r#"return UnitStat("pet", 1)"#)
@@ -1801,12 +1382,8 @@ mod tests {
         );
     }
 
-    /// `UnitDefense` always answers two numbers (the ref reads `local base, modifier`), and **the
-    /// two legs are different functions, not one function with missing data**: the player's is the
-    /// skill pair, a pet's is `level * 5` with a flat 0 modifier (the vtable fork,
-    /// `0x5eda20`/`0x613680`). `UnitAttackBothHands` takes the same fork and must agree with it —
-    /// that agreement is the point, since a mismatch is exactly what a snapshot-only
-    /// implementation would produce.
+    /// The vtable fork (`0x5eda20`, `0x613680`): the player's skill pair, a pet's level * 5 with a
+    /// 0 modifier; `UnitAttackBothHands` takes the same fork.
     #[test]
     fn unit_defense_forks_the_player_skill_from_a_pets_level_times_five() {
         let mut s = UiScript::new().unwrap();
@@ -1837,19 +1414,17 @@ mod tests {
             (300, 0, 300, 0),
             "the Attack row takes the same fork — and ignores its hand index, so both pairs match"
         );
-        // The pet's snapshot carries neither pair, which is the whole point: the numbers above
-        // cannot have come from it.
+        // The pet's snapshot carries neither pair; the numbers above come from its level.
         assert_eq!(pet_stats().defense_skill, (0, 0));
         assert_eq!(pet_stats().main_weapon_skill, (0, 0));
-        // A pet the level feed has not reached yet reads 0 rather than a stale or invented number.
+        // A pet with no level fed yet reads 0.
         s.set_unit("pet", None);
         assert_eq!(
             s.eval::<(i64, i64)>(r#"return UnitDefense("pet")"#)
                 .unwrap(),
             (0, 0)
         );
-        // A token that fails the client's SELF-or-SUMMONEDBY gate gets the failure zeros, not
-        // some other unit's level.
+        // A token failing the SELF-or-SUMMONEDBY gate gets zeros, not its level.
         s.set_unit(
             "target",
             Some(super::super::UnitState {
@@ -1863,8 +1438,7 @@ mod tests {
                 .unwrap(),
             (0, 0)
         );
-        // A negative modifier survives the round trip — the ref branches on `modifier < 0` to
-        // paint the number red.
+        // A negative modifier survives; stock paints it red.
         s.set_player_combat_stats(Some(UnitCombatStats {
             defense_skill: (300, -25),
             ..stats()
@@ -1887,19 +1461,8 @@ mod tests {
         assert!(s.eval::<bool>("return HasWandEquipped()").unwrap());
     }
 
-    /// **`GetInventoryItemCount`'s container fork** (`0x4c8680`). Four answers, and three of them
-    /// are not the stack count:
-    ///
-    /// · an equipped QUIVER (its `ItemSubClass.dbc` row has `DisplayFlags & 0x4`) answers the sum
-    ///   of its arrows — the number that shows on the bag bar;
-    /// · an equipped PLAIN BAG answers **0**, which is why the bar shows it no digit even though
-    ///   `BagSlotButtonTemplate` sets `isBag = 1` and `SetItemButtonCount` would print any
-    ///   positive number;
-    /// · the SAME plain bag in a BANK BAG slot answers 0 too, but for a different reason and
-    ///   earlier: `cmp …,0x16 / jg` short-circuits every container past the four equipped bag
-    ///   slots before the DBC is ever consulted. This is the digit the director saw on
-    ///   `BankFrameBag1` (decision 1771's sibling), and asserting it here rather than only through
-    ///   the window is the point — the window can only ever show that the two agree.
+    /// `0x4c8680`'s container fork: an equipped quiver counts its arrows, a plain bag 0, and any
+    /// container in a bank bag slot 0 before the DBC is read.
     #[test]
     fn get_inventory_item_count_forks_on_the_container_bit_and_the_slot() {
         let mut s = UiScript::new().unwrap();
@@ -1943,10 +1506,7 @@ mod tests {
             "0-based 63 is past 0x16: every container short-circuits, quiver or not"
         );
 
-        // The two `.data` literals, and the fact that both arms RAISE rather than answer. A slot
-        // outside the shared reader's whitelist is not an empty slot: the backpack's own item
-        // slots (Lua 24..=39) are addressed through the container API, and handing one here
-        // abandons the statement.
+        // Both arms raise. The backpack's item slots (Lua 24..=39) are outside the whitelist.
         let err = |code: &str| s.run(code).unwrap_err().to_string();
         assert!(
             err(r#"GetInventoryItemCount("player", 30)"#)
@@ -2030,9 +1590,7 @@ mod tests {
                 .unwrap(),
             200
         );
-        // An empty slot: nil id/texture/quality — and **count 1, not 0** (`0x4c8797`). Every
-        // secondary source says 0; the image pushes the literal 1, and both FrameXML callers gate
-        // on `GetInventoryItemTexture` first, which is why nobody ever caught it.
+        // An empty slot: nil id, texture and quality, and count 1 (`0x4c8797`).
         assert!(s
             .eval::<bool>(r#"return GetInventoryItemID("player", 5) == nil"#)
             .unwrap());
@@ -2047,7 +1605,7 @@ mod tests {
         assert!(s
             .eval::<bool>(r#"return GetInventoryItemQuality("player", 5) == nil"#)
             .unwrap());
-        // A non-player token: the empty shape (the INV_SLOT fields are PRIVATE — player only).
+        // A token with no items behind it: the empty shape.
         assert!(s
             .eval::<bool>(r#"return GetInventoryItemID("target", 1) == nil"#)
             .unwrap());
@@ -2091,9 +1649,7 @@ mod tests {
                 "interface\\paperdoll\\UI-PaperDoll-Slot-Ranged.blp".into()
             )
         );
-        // The bag rows: the four equipped-bag icons at 20..23 AND `Bag1`..`Bag12` at 64..75, which
-        // this table was short of until the DBC was re-read (36 records, not 24). All SIXTEEN share
-        // one string-block offset, which is why they answer the same art.
+        // The bag rows, 20..23 and 64..75, share one texture string.
         const BAG_ART: &str = "interface\\paperdoll\\UI-PaperDoll-Slot-Bag.blp";
         for (name, id) in [
             ("Bag0Slot", 20),
@@ -2124,20 +1680,13 @@ mod tests {
                 "interface\\paperdoll\\UI-PaperDoll-Slot-SecondaryHand.blp".into()
             )
         );
-        // An unknown slot name is a Lua error (the client's own behavior).
         assert!(s
             .eval::<i64>(r#"return GetInventorySlotInfo("NoSuchSlot")"#)
             .is_err());
     }
 
-    /// The character and pet paper dolls' facings are **the panes' own `SetRotation` state**, read
-    /// back by name — not the two benilla-named scalars they were until decision 1751.
-    ///
-    /// The two tabs are two `<PlayerModel>`s that can sit at different facings, which is the whole
-    /// reason this is per-pane at all: turning one must leave the other alone. It used to be
-    /// guaranteed by there being two fields on `Model`; now it is guaranteed by there being two
-    /// frames, which is also what the reference relies on (`Model_RotateLeft(model)` takes the
-    /// pane).
+    /// Each paper doll's facing is its pane's own `SetRotation` state, so turning one leaves the
+    /// other alone, as stock `Model_RotateLeft(model)` expects.
     #[test]
     fn each_model_pane_carries_its_own_facing_for_the_app_to_sample() {
         let s = UiScript::new().unwrap();
@@ -2153,10 +1702,10 @@ mod tests {
         "#,
         )
         .unwrap();
-        // The reference's own default, as `Model_OnLoad` writes it.
+        // Stock's default, as `Model_OnLoad` writes it (`UIParent.lua:1422`).
         s.run("CharacterModelFrame:SetRotation(0.61)").unwrap();
         assert_eq!(s.model_pane_facing("CharacterModelFrame"), 0.61);
-        // Persistent, not a drain — two reads see the same value.
+        // Persistent, not a drain.
         assert_eq!(s.model_pane_facing("CharacterModelFrame"), 0.61);
         assert_eq!(
             s.model_pane_facing("PetModelFrame"),
@@ -2175,11 +1724,9 @@ mod tests {
         s.run("CharacterModelFrame:SetRotation(-0.5)").unwrap();
         assert_eq!(s.model_pane_facing("CharacterModelFrame"), -0.5);
 
-        // A name nothing declares reads 0.0 rather than raising — the app samples this every
-        // frame, including before the window's file has loaded.
+        // An undeclared name reads 0.0: the app samples this before the window loads.
         assert_eq!(s.model_pane_facing("NoSuchModelFrame"), 0.0);
-        // …and so does a name that IS declared but is not a model pane, which is the shape a
-        // renamed window would take.
+        // A declared frame that is not a model pane has no pane.
         s.run(r#"CreateFrame("Frame", "NotAPane")"#).unwrap();
         assert!(s.model_pane("NotAPane").is_none());
     }
diff --git a/crates/benilla-ui/src/script/chat_misc.rs b/crates/benilla-ui/src/script/chat_misc.rs
index 36d40c82..52b9e29b 100644
--- a/crates/benilla-ui/src/script/chat_misc.rs
+++ b/crates/benilla-ui/src/script/chat_misc.rs
@@ -1,27 +1,21 @@
-//! The chat slash handlers' engine verbs that are not sends, channels, or window state —
-//! `DoEmote`, `RandomRoll`, `AssistByName`, `UninviteByName`, `ConsoleExec`, `LoggingChat`,
-//! `LoggingCombat`. Each is what a stock `ChatFrame.lua` built-in handler calls once it has
-//! parsed the line (`SlashCmdList` walk, decision 1195); the app used to parse these lines
-//! itself (`ui_chat/input/parse.rs`) and now drains what the reference's own Lua decided.
-//!
-//! Every verb is a queue or a flag — the engine-free seam (0068 §3): the VM never sees the wire,
-//! the app drains and sends. Registrar addresses:
-//! `0x49fd30 DoEmote`, `0x48c7b0 RandomRoll`, `0x489c40 AssistByName`, `0x48a610 UninviteByName`.
+//! The engine verbs stock `ChatFrame.lua`'s slash handlers call that are not sends, channels or
+//! window state: `DoEmote` (`0x49fd30`), `RandomRoll` (`0x48c7b0`), `AssistByName` (`0x489c40`),
+//! `UninviteByName` (`0x48a610`), `ConsoleExec`, `LoggingChat` and `LoggingCombat`. Each is a
+//! queue or a flag the app drains.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// `DoEmote(token [, target])` — the `EmotesText.dbc` **name token** (`"WAVE"`, not `/wave`) and
-/// the optional target name the handler split off the line.
+/// `DoEmote(token [, target])`: the `EmotesText.dbc` name token (`"WAVE"`, not `/wave`) and an
+/// optional target name.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct EmoteRequest {
     pub token: String,
     pub target: Option<String>,
 }
 
-/// Lua number coercion the way the reference's `lua_tonumber` does it: an integer, a float, or a
-/// string that parses; anything else is 0.
+/// The reference's `lua_tonumber` coercion: a number or a numeric string; anything else is 0.
 fn to_u32(v: &Value) -> u32 {
     match v {
         Value::Integer(i) => u32::try_from(*i).unwrap_or(0),
@@ -53,8 +47,7 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().emote_requests)
     }
 
-    /// `RandomRoll(min, max)` calls since the last drain, as the app sends them
-    /// (`CMSG_RANDOM_ROLL`).
+    /// `RandomRoll(min, max)` calls since the last drain, each a `CMSG_RANDOM_ROLL`.
     pub fn take_roll_requests(&mut self) -> Vec<(u32, u32)> {
         std::mem::take(&mut self.model_mut().roll_requests)
     }
@@ -64,21 +57,18 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().uninvite_requests)
     }
 
-    /// `ConsoleExec` lines whose first word is not a registered CVar — the console commands the
-    /// app owns (`reloadui`, …). A CVar line is written to the store directly and never appears
-    /// here.
+    /// `ConsoleExec` lines that write no CVar: the app's console commands (`reloadui`, …).
     pub fn take_console_lines(&mut self) -> Vec<String> {
         std::mem::take(&mut self.model_mut().console_lines)
     }
 
-    /// `(chat, combat)` — the two logging flags as `LoggingChat`/`LoggingCombat` last set them.
+    /// `(chat, combat)`, as `LoggingChat` and `LoggingCombat` last set them.
     pub fn logging_flags(&self) -> (bool, bool) {
         let model = self.model_mut();
         (model.logging_chat, model.logging_combat)
     }
 
-    /// Whether either logging flag moved since the last drain — the app's cue to open or close
-    /// its log files.
+    /// Whether a logging flag moved since the last drain: the app's cue to open or close its logs.
     pub fn take_logging_changes(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().logging_changed)
     }
@@ -138,12 +128,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ConsoleExec("name value") — the console line `/console` hands over. A registered CVar
-    // WITH a value is written the way `SetCVar` writes it (same store, same change queue, no
-    // CVAR_UPDATE token), synchronously, so a script reading it back on the next line sees the
-    // write. Everything else — a command name, or a bare CVar name, which the reference's
-    // per-CVar console command answers with `CVar "%s" is "%s"` (`0x63dde0`) — is a line for
-    // the host's command registry (decision 2303).
+    // `ConsoleExec("name value")`: a registered CVar with a value is written at once, as `SetCVar`
+    // writes it; anything else, a bare CVar name included (the reference answers it with
+    // `CVar "%s" is "%s"`, `0x63dde0`), goes to the app's command registry.
     g.set(
         "ConsoleExec",
         lua.create_function(|lua, line: Option<String>| {
@@ -252,8 +239,7 @@ mod tests {
             "0.8",
             "the CVar store is the same one SetCVar writes, matched case-insensitively"
         );
-        // A bare CVar name is the host's to answer (2303: the reference prints its value from
-        // the per-CVar console command), so it rides the command lane like `reloadui`.
+        // A bare CVar name, whose value the reference prints, goes to the command lane.
         assert_eq!(
             s.take_console_lines(),
             vec!["reloadui".to_string(), "uiScale".to_string()]
diff --git a/crates/benilla-ui/src/script/chat_send.rs b/crates/benilla-ui/src/script/chat_send.rs
index 981a1fcb..8942e15b 100644
--- a/crates/benilla-ui/src/script/chat_send.rs
+++ b/crates/benilla-ui/src/script/chat_send.rs
@@ -1,77 +1,47 @@
-//! **`SendChatMessage`** — the addon's own line into the chat wire (decision 1199).
+//! `SendChatMessage(text [, chatType [, language [, target]]])` (`0x49f1e0`): the engine verb an
+//! addon speaks through, with no FrameXML between it and the wire. `chatType` defaults to
+//! `"SAY"`; the fourth argument is the whisper target or the channel name or number.
 //!
-//! 24 corpus addons call it, and it is the one verb that makes an addon able to *say* anything:
-//! every "announce the pull", every raid warning helper, every whisper-the-invite bot is this one
-//! call. It is `function engine` in the captured `_G` — the engine takes the line and the wire
-//! sends it, with no FrameXML in between.
+//! It queues a [`ChatSend`] rather than going through the edit box, whose drain runs the slash
+//! grammar: an addon's `SendChatMessage("/dance")` says the characters. The reference splits the
+//! same way, `ChatEdit_SendText` parsing and `SendChatMessage` not.
 //!
-//! ```lua
-//! SendChatMessage(text [, chatType [, language [, channel/target]]])
-//! ```
+//! `language` is accepted and dropped, so every line goes in the speaker's default tongue: the
+//! app's chat command has no language field. The reference sends the named language.
 //!
-//! `chatType` defaults to `"SAY"`; `language` is accepted and **ignored** (`0x49f1e0`); the fourth
-//! argument is the whisper target for `"WHISPER"` and the channel name or number for
-//! `"CHANNEL"`, and is unused otherwise.
-//!
-//! ## The seam
-//!
-//! Same shape as [`super::social`]'s: the verb queues a [`ChatSend`] and the app drains it
-//! ([`super::UiScript::take_chat_sends`]) into `ClientCommand::Chat`. It deliberately does **not**
-//! go through the chat edit box's own drain: that path runs the slash grammar, and an addon's
-//! `SendChatMessage("/dance", "SAY")` must *say the four characters*, not dance. The reference has
-//! the same split — `ChatEdit_SendText` parses, `SendChatMessage` does not.
-//!
-//! ## What is not carried, and why
-//!
-//! **`language`.** The reference resolves a language id to the garble table the receiver's client
-//! reverses. benilla sends every line in the speaker's own tongue because the app's chat command
-//! carries no language field yet, and inventing one here would put the id in a queue nothing
-//! reads. Accepted and dropped, said out loud rather than silently — an addon passing it is not
-//! wrong, we are incomplete.
-//!
-//! **No rate limit and no length cap.** The reference truncates at 255 and the *server* throttles.
-//! Ours passes the line through; vmangos enforces both, so a misbehaving addon meets the same wall
-//! it would meet on a real server rather than a client-side one we made up.
+//! Deviation: no truncation at 255 characters (`0x49f604`), because vmangos refuses a longer line
+//! itself (`Chat.cpp:2177`): it is dropped where the reference sends its first 255. The server
+//! throttles in both.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
 impl super::UiScript {
-    /// Push the player's **default chat language** — the name `GetDefaultLanguage()` answers.
-    /// `None` (the default) is the reference's own no-player-object state, which returns **zero
-    /// Lua values**, not `nil`. The app resolves it once per world entry from
-    /// `ChrRaces.BaseLanguage` × `Languages.dbc` (`benilla_formats::DefaultLanguages`).
+    /// Push the name `GetDefaultLanguage()` answers. `None` is the reference's no-player state,
+    /// which returns zero values, not `nil`; the app resolves it per world entry from
+    /// `ChrRaces.BaseLanguage` and `Languages.dbc`.
     pub fn set_default_language(&mut self, name: Option<String>) {
         self.model_mut().default_language = name;
     }
 }
 
-/// One queued outbound chat line (`SendChatMessage`), drained by the app into the wire.
-///
-/// Plain data — [`super::social::SocialRequest`]'s twin, and deliberately *not* the app's own
-/// `ClientCommand::Chat`: this crate has no wire types and must not grow one.
+/// One queued `SendChatMessage` line, plain data: this crate holds no wire types.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct ChatSend {
-    /// The line, verbatim. Never parsed here — a leading `/` is four characters, not a command.
+    /// The line, verbatim: a leading `/` is text, not a command.
     pub text: String,
-    /// The chat type token, uppercased (`"SAY"`, `"YELL"`, `"PARTY"`, `"GUILD"`, `"WHISPER"`,
-    /// `"CHANNEL"`, `"EMOTE"`, …). Uppercased because the reference's own token compare is, and
-    /// addons write `"say"` as often as `"SAY"`.
+    /// The chat type token (`"SAY"`, `"WHISPER"`, `"CHANNEL"`, …), uppercased, since the
+    /// reference's compare ignores case.
     pub chat_type: String,
-    /// The whisper target (`"WHISPER"`) or the channel name/number (`"CHANNEL"`); `None`
-    /// otherwise. Kept as a string for the channel case, where an addon passes either `"General"`
-    /// or `1` and the app resolves both.
+    /// The whisper target or the channel name or number, as text; the app resolves either.
     pub target: Option<String>,
 }
 
 impl super::UiScript {
-    /// The languages this character **knows**, in `Languages.dbc` row order — what
-    /// `GetNumLaguages`/`GetLanguageByIndex` walk. The app folds it the reference's way:
-    /// `0x4b25b0` stores `[languageId] = spellId` for every known spell whose `Effect_1 == 39`,
-    /// and `0x5ec720` answers non-zero only when that spell's skill line is in the player's
-    /// skill block. Fires `LANGUAGE_LIST_CHANGED`
-    /// (`0x49b970`, event 0x102) when the list moves.
+    /// The languages this character knows, in `Languages.dbc` row order: a language counts when a
+    /// known spell with `Effect_1 == 39` teaches it (`0x4b25b0`) and its skill line is in the skill
+    /// block (`0x5ec720`). A change fires `LANGUAGE_LIST_CHANGED` (`0x49b970`, event 0x102).
     pub fn set_known_languages(&mut self, names: Vec<String>) {
         let changed = {
             let mut model = self.model_mut();
@@ -89,8 +59,8 @@ impl super::UiScript {
 }
 
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
-    // GetNumLaguages() — `0x49fb30`, the binary's own spelling. Walks `Languages.dbc` and counts
-    // the rows `0x5ec720` answers non-zero for; **one number**.
+    // GetNumLaguages(), `0x49fb30`: one number, the known languages. The misspelling is the
+    // reference's registered name (`0x843628`); the correct spelling is nowhere in the binary.
     lua.globals().set(
         "GetNumLaguages",
         lua.create_function(|lua, _ignored: MultiValue| {
@@ -98,8 +68,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(model.known_languages.len() as i64)
         })?,
     )?;
-    // GetLanguageByIndex(i) — `0x49fbe0`: the same walk, pushing **one string** — the
-    // `Name_lang` of the i-th (1-based) *known* language. Positional among the known rows,
+    // GetLanguageByIndex(i), `0x49fbe0`: the `Name_lang` of the i-th known language, positional,
     // never a row number or a language id; past the end it pushes nothing.
     lua.globals().set(
         "GetLanguageByIndex",
@@ -115,33 +84,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             })
         })?,
     )?;
-    // GetDefaultLanguage() → **exactly ONE value, a string** — or **zero values**, which is not
-    // the same thing (`0x49fcd0`).
-    //
-    // The binding takes **no arguments** (no arg-presence check and no arg-fetch call anywhere in
-    // its 94 bytes — contrast its sibling `GetLanguageByIndex 0x49fbe0`, which opens with
-    // `0x6f34d0`), so the corpus's `GetDefaultLanguage("player")` — `Auctioneer/AucAskPrice.lua:42`
-    // and `Enchantrix/EnchantrixBarker.lua:149` both write it — is harmlessly ignored, here as
-    // there.
-    //
-    // There is exactly one push in the body and it is `0x6f3890` (push-STRING): the numeric
-    // language id is consumed as a table index and never reaches Lua, so this is not `(name, id)`
-    // and not an id. All **four** failure edges — no player object, a negative id, an id past the
-    // language count, a null record — converge on `0x49fd2a xor eax,eax; ret`, i.e. **zero Lua
-    // values**. That is shape 2 of the argument ABI ([`super::binding_abi`]) and it is the one
-    // place in this repo where the distinction is observable: the call's return-list COUNT is `0`
-    // outside the world and `1` inside it, while a single-value caller reads `nil` either way.
-    // Returning `nil` here would be a quiet divergence, so we do not.
-    //
-    // **Its sibling is misspelled in the binary, and is deliberately NOT registered here.** The
-    // `.data` `{const char* name, void* fn}` record at `0x843628` names `0x49fb30`
-    // **`GetNumLaguages`** — and a whole-image byte search for the correct spelling returns **zero
-    // hits** (with `GetNumLaguages` and `GetDefaultLanguage` as satisfied positive controls), so
-    // the typo is the only Lua-visible name and a faithful client would ship it. What is missing
-    // is not the name but the *answer*: `0x49fb30`'s body was not carved beyond "returns through
-    // the push-number helper", no corpus addon calls it at all, and registering it would mean
-    // inventing a count. The name is recorded here so that whoever carves the body knows how to
-    // spell the global.
+    // GetDefaultLanguage(), `0x49fcd0`: one string (`0x6f3890`), or zero values, never `nil`, on
+    // all four failure edges (`0x49fd2a`). It reads no arguments, so an addon's
+    // `GetDefaultLanguage("player")` is ignored.
     lua.globals().set(
         "GetDefaultLanguage",
         lua.create_function(|lua, _ignored: MultiValue| {
@@ -160,13 +105,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "SendChatMessage",
         lua.create_function(
             |lua, (text, chat_type, _language, target): (String, Option<String>, Value, Value)| {
-                // The reference's default is SAY — an addon that passes only a string is saying it.
                 let chat_type = chat_type
                     .unwrap_or_else(|| "SAY".into())
                     .to_ascii_uppercase();
-                // The fourth argument is a name for WHISPER and a name-or-number for CHANNEL, so
-                // it arrives as either a string or a number and is normalised to text here rather
-                // than at every consumer.
+                // A channel arrives as a name or a number; both become text.
                 let target = match target {
                     Value::String(s) => Some(s.to_string_lossy()),
                     Value::Integer(n) => Some(n.to_string()),
@@ -200,11 +142,6 @@ mod tests {
     use super::*;
     use crate::script::UiScript;
 
-    /// The default is SAY, the type is uppercased, and **a leading slash is text**.
-    ///
-    /// That last one is the whole reason this verb has its own queue rather than reusing the chat
-    /// box's: the box's drain runs the slash grammar, and an addon announcing "/dance" wants the
-    /// six characters said, not the emote played. The reference splits the same way.
     #[test]
     fn send_chat_message_queues_a_line_without_parsing_it() {
         let mut s = UiScript::new().unwrap();
@@ -225,12 +162,9 @@ mod tests {
                 },
             ]
         );
-        // Drained, not re-read.
         assert!(s.take_chat_sends().is_empty());
     }
 
-    /// The fourth argument is a whisper target or a channel, and a channel arrives as either a
-    /// name or a number — both normalise to text so one consumer handles both.
     #[test]
     fn the_target_argument_takes_a_name_or_a_channel_number() {
         let mut s = UiScript::new().unwrap();
@@ -247,8 +181,6 @@ mod tests {
         assert_eq!(sent[1].chat_type, "CHANNEL");
     }
 
-    /// `language` is accepted and dropped — an addon passing it must not error, and the module
-    /// doc says why nothing reads it.
     #[test]
     fn the_language_argument_is_accepted_and_ignored() {
         let mut s = UiScript::new().unwrap();
@@ -257,11 +189,7 @@ mod tests {
         assert!(s.errors().is_empty(), "{:?}", s.errors());
     }
 
-    /// **One string, or ZERO values — never `nil`.** The four failure edges reach
-    /// `0x49fd2a xor eax,eax; ret` *without* passing through `luaL_error`, which is the only place
-    /// the "returns nothing" shape is real. A single-value caller cannot tell the two apart; the
-    /// return-list count can ([`UiScript::arity`]), and both corpus callers feed the result straight to
-    /// `SendChatMessage`, where the difference is an argument that exists versus one that does not.
+    /// The count matters: an addon passes the result straight to `SendChatMessage` as `language`.
     #[test]
     fn get_default_language_is_one_string_or_zero_values() {
         let mut s = UiScript::new().unwrap();
@@ -281,7 +209,7 @@ mod tests {
             s.eval::<String>("return GetDefaultLanguage()").unwrap(),
             "Common"
         );
-        // The binding reads NO arguments; the corpus passes `"player"` anyway and must not error.
+        // The binding reads no arguments; addons pass `"player"` anyway.
         assert_eq!(
             s.eval::<String>(r#"return GetDefaultLanguage("player")"#)
                 .unwrap(),
diff --git a/crates/benilla-ui/src/script/chat_types.rs b/crates/benilla-ui/src/script/chat_types.rs
index d175d757..2f0d0e6c 100644
--- a/crates/benilla-ui/src/script/chat_types.rs
+++ b/crates/benilla-ui/src/script/chat_types.rs
@@ -1,30 +1,6 @@
-//! The chat-type colour registry — `GetChatTypeIndex`, `ChangeChatColor`, `ResetChatColors`.
-//!
-//! The reference keeps one runtime table of chat types (`0xb4e518`, stride 0x43: a 0x40-byte
-//! name and three RGB bytes), seeded at boot from the 94-entry static table at `0x804710` and
-//! then extended with ten extras `CHANNEL1`…`CHANNEL10`, each coloured from the live `CHANNEL`
-//! entry (`0x4982c0`). The `chat-cache.txt`
-//! `COLORS` block overwrites matched entries in place at load — absent names keep the compiled
-//! defaults — and the app owns that file; here the table is state the app feeds and drains
-//! ([`super::UiScript::set_chat_colors`], [`super::UiScript::take_chat_color_changes`]).
-//!
-//! The Lua surface, from the same node:
-//!
-//! - `GetChatTypeIndex(name)` — a case-insensitive linear scan of the 94 fixed entries, **1-based**
-//!   (`4a0adf: inc ebx` before the match test); no fixed match → the extras, numbered **95, 96, …**
-//!   (`count_before_match + 0x5f`); no match at all → **0**.
-//! - `ChangeChatColor(name, r, g, b)` — `r,g,b` are 0.0–1.0 floats, each `fmul 255.0` then
-//!   `__ftol` (**truncate**, no rounding, bytes `4a085f–4a08a3`), written into the matched entry.
-//!   On success fires `UPDATE_CHAT_COLOR` with `"%s%f%f%f"`: the name and the three
-//!   **just-written bytes re-normalised** by `f32 1/255` — so an addon that passed `0.5` hears
-//!   `127/255`, not `0.5`. (The event's symbolic name is the node's one INFERRED item — it is
-//!   `0xe2` in a runtime-populated listener table; `ChatFrame.lua:1349` registers and reads it
-//!   as `UPDATE_CHAT_COLOR` with exactly those four args.)
-//! - `ResetChatColors()` — the boot seed again: the 94 defaults copied back, then every extra
-//!   recoloured from the live `CHANNEL` entry.
-//!
-//! What the line colours *mean* to a message frame is `ScrollingMessageFrame:UpdateColorByID`,
-//! which lives with the frame (`messageframe/scrolling.rs`); this file is only the registry.
+//! The chat-type colour registry behind `GetChatTypeIndex`, `ChangeChatColor` and
+//! `ResetChatColors`: the reference's runtime table (`0xb4e518`), which the `COLORS` block of
+//! `chat-cache.txt` overwrites in place at load; the app owns that file.
 
 use mlua::{Lua, MultiValue, Value};
 
@@ -32,11 +8,11 @@ use super::Model;
 
 /// The fixed segment: 94 entries, in the reference's order (index = position + 1).
 pub const FIXED_CHAT_TYPES: usize = 94;
-/// The extras seeded at boot: `CHANNEL1`…`CHANNEL10`, indices 95–104.
+/// The extras seeded at boot: `CHANNEL1` to `CHANNEL10`, indices 95 to 104.
 pub const EXTRA_CHAT_TYPES: usize = 10;
 
-/// `0x804710` — name and default RGB, verbatim. The order is load-bearing: it *is* the index
-/// `GetChatTypeIndex` answers.
+/// The reference's table at `0x804710`, verbatim; its order is the index `GetChatTypeIndex`
+/// answers.
 const DEFAULTS: [(&str, [u8; 3]); FIXED_CHAT_TYPES] = [
     ("SAY", [255, 255, 255]),
     ("PARTY", [170, 170, 255]),
@@ -134,7 +110,7 @@ const DEFAULTS: [(&str, [u8; 3]); FIXED_CHAT_TYPES] = [
     ("BATTLEGROUND_LEADER", [255, 219, 183]),
 ];
 
-/// The 1-based index of the `CHANNEL` entry — the extras' colour source at seed and reset.
+/// The 1-based index of `CHANNEL`, the extras' colour source at seed and reset.
 const CHANNEL_INDEX: usize = 15;
 
 /// One registry entry: the type's name and its live colour bytes.
@@ -144,7 +120,7 @@ pub struct ChatTypeColor {
     pub rgb: [u8; 3],
 }
 
-/// The boot seed: the 94 defaults, then `CHANNEL1`…`CHANNEL10` coloured from the live `CHANNEL`.
+/// The boot seed: the defaults, then the extras coloured from `CHANNEL` (`0x4982c0`).
 pub(super) fn seed() -> Vec<ChatTypeColor> {
     let mut table: Vec<ChatTypeColor> = DEFAULTS
         .iter()
@@ -163,7 +139,7 @@ pub(super) fn seed() -> Vec<ChatTypeColor> {
     table
 }
 
-/// `ResetChatColors`' copy loop: the fixed segment back to `0x804710`, the extras from `CHANNEL`.
+/// `ResetChatColors`: the defaults back first, then the extras from the restored `CHANNEL`.
 fn reset(table: &mut [ChatTypeColor]) {
     for (entry, (_, rgb)) in table.iter_mut().zip(DEFAULTS.iter()) {
         entry.rgb = *rgb;
@@ -174,13 +150,13 @@ fn reset(table: &mut [ChatTypeColor]) {
     }
 }
 
-/// The reference's compare (`0x64a4c0` → `0x414310`): an `'A'–'Z' + 0x20` fold, i.e. ASCII
-/// case-insensitive and nothing wider.
+/// ASCII case-insensitive and nothing wider: the reference's compare folds only `A` to `Z`
+/// (`0x64a4c0`, `0x414310`).
 fn position(table: &[ChatTypeColor], name: &str) -> Option<usize> {
     table.iter().position(|e| e.name.eq_ignore_ascii_case(name))
 }
 
-/// `fmul 255.0; __ftol` — truncation toward zero, then the low byte is what the `mov` stores.
+/// Truncates, never rounds: the reference's `fmul 255.0; __ftol` (`0x4a085f`-`0x4a08a3`).
 fn to_byte(x: f64) -> u8 {
     if !x.is_finite() {
         return 0;
@@ -188,15 +164,15 @@ fn to_byte(x: f64) -> u8 {
     ((x * 255.0).trunc() as i64) as u8
 }
 
-/// `fmul dword [0x8026c8]` — the f32 reciprocal, so the event carries `byte / 255` in single
-/// precision, widened.
+/// `UPDATE_CHAT_COLOR`'s value: the stored byte times the f32 reciprocal of 255 (`0x8026c8`), so
+/// an addon that passed `0.5` hears `127/255`.
 fn from_byte(b: u8) -> f64 {
     f64::from(b as f32 * (1.0f32 / 255.0f32))
 }
 
 impl super::UiScript {
-    /// The `COLORS` block of `chat-cache.txt`, applied the way the loader applies it: each named
-    /// entry overwritten in place, unknown names ignored, absent names left at their defaults.
+    /// Apply the `COLORS` block of `chat-cache.txt` as the loader does: matched entries
+    /// overwritten in place, unknown names ignored.
     pub fn set_chat_colors(&mut self, colors: impl IntoIterator<Item = (String, [u8; 3])>) {
         let mut model = self.model_mut();
         for (name, rgb) in colors {
@@ -211,8 +187,7 @@ impl super::UiScript {
         self.model_mut().chat_colors.clone()
     }
 
-    /// Whether a Lua-side write (`ChangeChatColor`, `ResetChatColors`) has landed since the last
-    /// drain — the app's persist cue.
+    /// Whether Lua changed a colour since the last drain, the app's cue to persist.
     pub fn take_chat_color_changes(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().chat_colors_changed)
     }
@@ -371,8 +346,7 @@ mod tests {
         let s = UiScript::new().unwrap();
         s.run("ChangeChatColor('CHANNEL', 0.0, 0.0, 0.0) ChangeChatColor('CHANNEL2', 1, 1, 1)")
             .unwrap();
-        // Reset copies the fixed defaults first, so CHANNEL is back to FFC0C0 by the time the
-        // extras are recoloured from it.
+        // The defaults come back first, so the extras take `CHANNEL`'s default, not the black.
         s.run("ResetChatColors()").unwrap();
         assert_eq!(s.chat_colors()[FIXED_CHAT_TYPES + 1].rgb, [255, 192, 192]);
     }
diff --git a/crates/benilla-ui/src/script/chat_window.rs b/crates/benilla-ui/src/script/chat_window.rs
index 72afe32b..6a19f5eb 100644
--- a/crates/benilla-ui/src/script/chat_window.rs
+++ b/crates/benilla-ui/src/script/chat_window.rs
@@ -1,149 +1,39 @@
-//! The chat **window** surface: `GetChatWindowInfo` (the engine's per-window settings getter) and
-//! `ChatFrame_OpenChat` (the FrameXML verb that opens the edit box prefilled).
+//! The chat window settings bindings: `GetChatWindowInfo`, its setters and `ChatFrame_OpenChat`.
 //!
-//! The windows themselves are frames, declared in the app's shipped `ChatFrame.xml` —
-//! `ChatFrame1`..`ChatFrame7`, of which 1 and 2 are docked and 3..7 ship hidden and undocked, the
-//! reference's own arrangement. This module is the *settings* half: what an addon learns when it
-//! asks about window `i` without touching the frame.
+//! The reference keeps one record per window (`0xb4fe50`, stride 0x98, 10 slots), loaded from and
+//! saved to `chat-cache.txt`: name `+0x00`, message-group flags `+0x20`, channel names and ids
+//! `+0x64`/`+0x74`, font size `i32` `+0x84`, the colour one packed `CImVector` in BGRA order
+//! (`+0x88` B, `+0x89` G, `+0x8a` R, `+0x8b` A), locked `+0x8c`, docked `+0x90`, shown `+0x94`.
+//! `GetChatWindowInfo(id)` (`0x4a0ba0`) answers `name, fontSize, r, g, b, a, shown, locked,
+//! docked`, each colour byte times the f32 1/255 at `0x8026c8`.
 //!
-//! ## `GetChatWindowInfo(id)` → `name, fontSize, r, g, b, a, shown, locked, docked`
+//! Three traps in that tuple. `name` is `""` until a window is named, and FrameXML's
+//! `FCF_SetWindowName` (FloatingChatFrame.lua:681) substitutes "General" and "Combat Log".
+//! `shown`, `locked` and `docked` are a number or nil, never 0, because FrameXML tests them bare
+//! (FloatingChatFrame.lua:59, 69). `docked` is a dock position, the index `FCF_DockFrame` takes.
 //!
-//! A registered Lua binding in the real client (`0x4a0ba0`), reading the per-window struct array at
-//! `0xb4fe50` — stride 0x98, **10 windows**, colour bytes at +0xd8..+0xdb renormalised by the f32
-//! 1/255 (`0x8026c8`). Those structs are loaded from the character's `chat-cache.txt`, and a real
-//! stock one, written by the reference client itself, is on disk — every value below is quoted from
-//! it:
-//!
-//! ```text
-//! WINDOW 1   SIZE 0  COLOR 0 0 0 0  LOCKED 1  DOCKED 1  SHOWN 1
-//! WINDOW 2   SIZE 0  COLOR 0 0 0 0  LOCKED 1  DOCKED 2  SHOWN 0
-//! WINDOW 3…10 SIZE 0 COLOR 0 0 0 0  LOCKED 1  DOCKED 0  SHOWN 0
-//! ```
-//!
-//! **Three traps live in that tuple, and all three are load-bearing:**
-//!
-//! 1. **`name` is the empty string, not "General".** Nothing writes a window name until the user
-//!    renames a tab, so a stock client answers `""` for every window including the first two. The
-//!    familiar labels are a *FrameXML fallback*, not data: `FCF_SetWindowName` (FloatingChatFrame.lua
-//!    l.680-684) reads `if ( not name or name == "" )` and substitutes `GENERAL` / `COMBAT_LOG` /
-//!    `format(CHAT_NAME_TEMPLATE, id)`. Our own tab labels are that fallback, hardcoded. An addon
-//!    proves the contract from the other side: `Enchantrix/EnxConfig.lua:113` does
-//!    `local name = GetChatWindowInfo(i); if ( name == "" ) then if (i == 1) then name =
-//!    _ENCH('TextGeneral') …` — it would not have been written if the getter answered "General".
-//!    Answering "General" here would look friendlier and would be a divergence.
-//! 2. **`shown`/`locked`/`docked` are numbers or `nil` — never `0`.** FrameXML branches on them
-//!    bare (`if ( shown ) then chatFrame:Show()`, `if ( docked ) then FCF_DockFrame(…)` —
-//!    FloatingChatFrame.lua l.59/69), and `0` is TRUE in Lua. A getter that returned the cache's
-//!    literal `0` would show every hidden window.
-//! 3. **`docked` is a dock POSITION, not a flag.** Window 1 answers `1`, window 2 answers `2` —
-//!    the order tabs sit in the dock, which is why `FCF_DockFrame(frame, docked)` takes it as an
-//!    index. Reading it as a boolean happens to work; reading it as "is docked" and writing back
-//!    `1` would silently reorder the dock.
-//!
-//! `fontSize` is the cache's `SIZE`, and `0` is what a stock client stores — "use the font's own
-//! height". No FrameXML path applies it (`FloatingChatFrame_Update` destructures it and never
-//! reads it; the options dropdown checks `FCF_GetCurrentChatFrame():GetFont()` instead), and no
-//! corpus addon reads it.
-//!
-//! ## The three setters, and why this getter stopped being a constant (decision 1589)
-//!
-//! Until 1589 the whole tuple above was a frozen table: benilla had no way to *change* a window's
-//! look, so answering with the stock cache row was the honest answer. B246 ("no chat options at
-//! all — background transparency has no home") is the report that ends that, and the reference's
-//! own home for it is the chat tab's right-click menu → **Background**, a colour swatch with an
-//! opacity slider. So three of the nine values are now real state, written by the reference's own
-//! three setters and read straight back out of this getter:
-//!
-//! | binding | address | what it stores |
-//! |---|---|---|
-//! | `SetChatWindowColor(id, r, g, b)` | `0x4a14f0` | `__ftol(x · 255.0)` per channel |
-//! | `SetChatWindowAlpha(id, a)` | `0x4a15d0` | `__ftol(a · 255.0)` |
-//! | `SetChatWindowSize(id, size)` | `0x4a1470` | the cache's `SIZE` |
-//! | `SetChatWindowLocked(id, isLocked)` | `0x4a1650` | the cache's `LOCKED` |
-//!
-//! (`[0x806498]` is the 255.0 the first two multiply by.) **Bytes, not floats** — that is
-//! why the getter renormalises by 1/255, and why [`ChatWindowLook`] stores the colour as `u8`: a
-//! set→get round trip through the real client quantises, and a store of `f32` here would
-//! round-trip values the reference cannot hold. `SetChatWindowAlpha(1, 0.4)` answers
-//! `102/255 = 0.4`, not `0.4`.
-//!
-//! **The record's own layout**: the colour is ONE packed `CImVector` at
-//! **`+0x88` B, `+0x89` G, `+0x8a` R, `+0x8b` A** — note the **BGRA** order — and the font size is
-//! an `i32` at **`+0x84`**, not a byte and with no `× 255` anywhere near it. (Both correct this
-//! module's earlier `+0xd8..+0xdb`, which was the low half of the *absolute* operand
-//! `[esi + 0xb4fed8]`: `0xb4fed8 − 0xb4fe50 = 0x88`.) `chat-cache.txt`'s `COLOR` line is written
-//! **R G B A** from `+0x8a,+0x89,+0x88,+0x8b` and parsed straight back as bytes, so the file
-//! round-trip is bit-exact and the `×255` / `×1/255` pair exists only at the Lua boundary.
-//!
-//! Two behaviours of the reference's setters that are easy to miss and are transcribed here:
-//!
-//! - **`SetChatWindowSize` silently drops a size `<= 0`** (`0x4a14bc jle`). A stock cache holds
-//!   `SIZE 0`, so "no size stored" and "cannot store 0" coexist: the field is only ever written by
-//!   a real pick off the Font Size menu.
-//! - **Nothing clamps.** `__ftol` (`0x40a2b0`) truncates, and the setters store the low byte of
-//!   the result with no bound: on a real client `SetChatWindowAlpha(1, 2.0)` stores **254**,
-//!   `(1, -1.0)` stores **1**, and `0.5` stores **127**, not 128.
-//!
-//! **We clamp where it wraps, and that is the one deliberate divergence.** Nothing in FrameXML or
-//! the corpus can reach the out-of-domain case (the colour picker's channels and its opacity
-//! slider are all `0..1`), and the camera pose file already set this posture: a value nothing can
-//! produce is not a thing to be faithful to. The truncation itself IS kept — `0.5` stores 127 here
-//! too.
-//!
-//! **`locked` joined them the day the windows could move.** `SetChatWindowLocked(id, isLocked)` is
-//! the fourth setter here now: the chat tab's *Lock/Unlock Window* row is what turns the resize
-//! grips and the tab drag on, so a value that used to be a constant has a player-reachable writer
-//! and belongs in the record with the rest. The other five stay constants, and that is the honest
-//! tree rather than an omission: benilla has no rename, no undock and no window create/close, so
-//! `name`, `shown` and `docked` still have nothing that could move them (0288 §2).
-//!
-//! Measured demand: **3 of the 5 corpus addons that iterate `NUM_CHAT_WINDOWS` call this on the
-//! very next line** — `EnhTooltip/Tooltip.lua:1302`, `MikScrollingBattleText.lua:1951` and
-//! `Enchantrix/EnxConfig.lua:110`. The first two are the same idiom (look for a window the user
-//! named "debug"/"ettdebug"); the third builds a name→index map for its `/enx print-in` config.
-//! Without this getter, declaring `NUM_CHAT_WINDOWS` hands those three a loop that raises on its
-//! first iteration, so the constant and the getter are one change, not two.
-//!
-//! ## `ChatFrame_OpenChat(text, chatFrame)`
-//!
-//! FrameXML in the reference (ChatFrame.lua l.1545), and the same seam as its neighbour
-//! `ChatFrame_SendTell` ([`super::party`]): benilla's chat edit machine is app-side
-//! (`benilla_app::ui_chat::edit`), so the verb queues the request and the app opens the box.
+//! `SetChatWindowColor` (`0x4a14f0`) and `SetChatWindowAlpha` (`0x4a15d0`) store
+//! `__ftol(x · 255.0)` (`[0x806498]` is the 255.0; `__ftol` `0x40a2b0` truncates), so a round trip
+//! quantises: alpha 0.4 reads back 102/255, 0.5 reads 127/255. Deviation: a value outside 0..1
+//! clamps, where the reference keeps the low byte (alpha 2.0 stores 254, -1.0 stores 1), because no
+//! FrameXML or addon caller passes one.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::channel::ZoneChannelRow;
 use super::Model;
 
-/// How many chat windows the client's own settings array holds — **10**, both in the engine
-/// (`0xb4fe50`, stride 0x98) and in `chat-cache.txt`, which writes `WINDOW 1` … `WINDOW 10`.
-/// FrameXML declares `ChatFrame1TabDockRegion`..`ChatFrame10TabDockRegion` to match, and then
-/// builds only seven `ChatFrame`s: `NUM_CHAT_WINDOWS = 7` is the *UI's* count, not the engine's.
-/// Recorded so the 7 below reads as a deliberate choice rather than a miscount.
+/// The reference's record slots (`0xb4fe50`); FrameXML builds only [`NUM_CHAT_WINDOWS`] frames.
 pub(super) const ENGINE_CHAT_WINDOW_SLOTS: usize = 10;
 
-/// The windows benilla actually builds — `ChatFrame1`..`ChatFrame7` in the app's `ChatFrame.xml`,
-/// which is also `NUM_CHAT_WINDOWS`. `benilla_app`'s `chat_tests` cross-checks every entry against
-/// the shipped XML so the two cannot drift.
+/// `NUM_CHAT_WINDOWS = 7` (ChatFrame.lua:5), the frames `ChatFrame1`..`ChatFrame7`.
 pub(super) const NUM_CHAT_WINDOWS: usize = 7;
 
-/// One chat window's **look** — the mutable slice of the engine's per-window record (decision
-/// 1589): the background tint, the background alpha, and the font size. The colour is bytes
-/// because the engine's colour is bytes (`0xb4fe50 + n*0x98 + 0x88..0x8b`, packed BGRA,
-/// `__ftol(x · 255.0)` in and `× 1/255` out); the font size is an `i32` because the engine's is
-/// (`+0x84`). See this module's docs for why that quantisation is kept rather than smoothed over.
-///
-/// [`Self::default`] is the stock `chat-cache.txt` row — `COLOR 0 0 0 0`, `SIZE 0`, `LOCKED 1` —
-/// i.e. a black box at alpha 0 that cannot be dragged, which is the classic "chat is text over the
-/// world until you mouse over it".
-/// `CHATMSGGROUP` — the client's 68-entry message-group table at `0x805fb0`:
-/// `(name, defaultOn, addedVersion)`, stride 0xc,
-/// in the order that IS the record's `+0x20` flag index. **Not** the 94-entry colour table: 67
-/// names are shared, `CREATURE` exists only here, and 27 colour names (RAID, OFFICER,
-/// WHISPER_INFORM, EMOTE, TEXT_EMOTE, MONSTER_*, CHANNEL_JOIN/LEAVE/LIST/NOTICE[_USER], AFK, DND,
-/// IGNORED, BG_SYSTEM_*, RAID_LEADER/WARNING/BOSS_EMOTE, FOREIGN_TELL, FILTERED, BATTLEGROUND[_LEADER])
-/// have no group. `defaultOn` is what the boot init (`0x4982c0`) copies into window 2's flags;
-/// `addedVersion` is the loader's (`0x498a60`) back-fill for a file older than `ADDEDVERSION 2`.
+/// `CHATMSGGROUP`, the client's 68-entry message-group table (`0x805fb0`, stride 0xc):
+/// `(name, defaultOn, addedVersion)` in the order of the record's `+0x20` flags. Not the 94-entry
+/// colour table: `CREATURE` is only here, and 27 colour types have no group. The boot init
+/// (`0x4982c0`) enables the `defaultOn` groups in window 2; the loader (`0x498a60`) back-fills by
+/// `addedVersion` for a file older than `ADDEDVERSION 2`.
 pub const MESSAGE_GROUPS: [(&str, bool, u8); 68] = [
     ("SYSTEM", true, 0),
     ("SAY", true, 0),
@@ -215,55 +105,35 @@ pub const MESSAGE_GROUPS: [(&str, bool, u8); 68] = [
     ("MONEY", true, 2),
 ];
 
-/// The flag index of a group name, matched the loader's way (`SStrCmpI` — an ASCII case-fold).
+/// The flag index of a group name, case-folded as the loader's `SStrCmpI` matches it.
 pub fn message_group_index(name: &str) -> Option<usize> {
     MESSAGE_GROUPS
         .iter()
         .position(|(n, _, _)| n.eq_ignore_ascii_case(name))
 }
 
+/// One window's record as `chat-cache.txt` persists it, in the reference's own field types.
 #[derive(Clone, PartialEq, Eq, Debug)]
 pub struct ChatWindowLook {
-    /// Background tint, `0..=255` each. The engine renormalises by 1/255 on the way out.
+    /// Background tint, one byte per channel.
     pub r: u8,
-    /// See [`Self::r`].
     pub g: u8,
-    /// See [`Self::r`].
     pub b: u8,
-    /// Background alpha, `0..=255`. `0` is the stock value and what benilla shipped as a constant
-    /// until 1589 — the hover fade lifts it to `DEFAULT_CHATFRAME_ALPHA` and drops it back.
+    /// Background alpha byte; stock 0, which the FrameXML hover fade lifts.
     pub a: u8,
-    /// The cache's `SIZE` — the chat font height in points, or `0` for "the font's own height".
-    /// The reference's own values are `CHAT_FONT_HEIGHTS = {12, 14, 16, 18}`. An `i32` because the
-    /// record's field is (`+0x84`), and never `<= 0` once set: the setter drops those.
+    /// `SIZE`: the font height, or 0 for the font's own; the setter never stores `<= 0`.
     pub font_size: i32,
-    /// The cache's `LOCKED` — whether the window refuses to be dragged or resized.
-    ///
-    /// **`true` out of the box**, because the stock row is `LOCKED 1` for every window: a fresh
-    /// character's chat box cannot be nudged out of place by a stray drag, and unlocking it is a
-    /// deliberate trip through the tab menu (`FCF_ToggleLock`). It joined this struct with the
-    /// move/resize arc: until something could *move* a window, writing the key would have
-    /// persisted state nothing could change, which is the honest-tree rule (1134 §4) at the
-    /// persistence layer, and the reason 1589 §6 left it out.
+    /// `LOCKED`, stock true for every window; the tab menu's `FCF_ToggleLock` moves it.
     pub locked: bool,
-    /// The cache's `DOCKED` — the window's **position in the dock**, 1-based, or `None` for a
-    /// window that is not docked. Not a flag: window 1 answers `1` and window 2 `2`, which is the
-    /// index `FCF_DockFrame(frame, docked)` takes (this module's §3 note), and the order the tabs
-    /// sit in.
-    ///
-    /// It joined this struct with the dock verbs (1714), by the same rule `locked` did: until
-    /// `FCF_DockFrame`/`FCF_UnDockFrame` existed there was nothing that could move it, so it was a
-    /// per-window constant read straight out of [`WINDOW_STATE`]. There is now, so it is state.
+    /// `DOCKED`: the 1-based dock position `FCF_DockFrame(frame, docked)` takes, `None` undocked.
     pub docked: Option<u8>,
-    /// `+0x00` — the window's name as `SetChatWindowName` stored it: `""` until FrameXML names
-    /// it (the getter's first return; the `NAME` line is emitted only when non-empty).
+    /// `+0x00`: `""` until `SetChatWindowName` stores one; `NAME` is written only when non-empty.
     pub name: String,
-    /// `+0x94` — `SHOWN`; the getter answers 1 or nil off it.
+    /// `+0x94`, `SHOWN`.
     pub shown: bool,
-    /// `+0x20` — the enabled message-type names, the `MESSAGES … END` block.
+    /// `+0x20`: the enabled message-group names, the `MESSAGES … END` block.
     pub messages: Vec<String>,
-    /// `+0x64` / `+0x74` — the channels this window shows, `(name, zone channel id)` pairs: the
-    /// `CHANNELS … END` block.
+    /// `+0x64`/`+0x74`: `(name, zone channel id)` pairs, the `CHANNELS … END` block.
     pub channels: Vec<(String, u32)>,
 }
 
@@ -274,7 +144,7 @@ impl Default for ChatWindowLook {
 }
 
 impl ChatWindowLook {
-    /// The stock `chat-cache.txt` row, as a const so [`super::Model`]'s array literal can use it.
+    /// The boot record of windows 3 to 10 (`0x4982c0`), which [`Self::stock`] builds 1 and 2 on.
     pub(super) const DEFAULT: Self = Self {
         r: 0,
         g: 0,
@@ -282,9 +152,6 @@ impl ChatWindowLook {
         a: 0,
         font_size: 0,
         locked: true,
-        // The stock row's `DOCKED` differs per window, so the array literal that uses this const
-        // seeds each slot from [`WINDOW_STATE`] afterwards. `None` here is only the value a
-        // slot holds before that seeding, and the value a *hand-built* look starts at.
         docked: None,
         name: String::new(),
         shown: false,
@@ -292,17 +159,10 @@ impl ChatWindowLook {
         channels: Vec::new(),
     };
 
-    /// The stock row for window `index` (0-based) — [`Self::DEFAULT`] with that window's own
-    /// `DOCKED` position from [`WINDOW_STATE`]. The seed for the model's array and for the
-    /// settings parser's per-line default, so a file that never mentions `DOCKED` keeps the
-    /// shipped dock rather than silently undocking both windows.
-    /// The boot init `0x4982c0` — the record a client with no
-    /// `chat-cache.txt` runs from, and what FrameXML's own `FloatingChatFrame_Update` then docks,
-    /// hides and saves: window 1 shown and undocked (it IS the dock — `FCF_DockFrame(ChatFrame1, 1)`
-    /// at FloatingChatFrame.xml's file scope), groups 1–10 by a literal fill; window 2 shown and
-    /// `docked 1`, every `defaultOn` group of 11–68 (the 34 the stock file lists); windows 3–10
-    /// hidden with nothing enabled. Every window locked, size 0, colour 0, name empty, ten empty
-    /// channel slots. The init fires no event; the loader (`0x498a60`) does.
+    /// Window `index`'s (0-based) record at boot (`0x4982c0`), what a client with no
+    /// `chat-cache.txt` runs from: window 1 shown and undocked (FrameXML docks it,
+    /// FloatingChatFrame.xml:835) with groups 1-10; window 2 shown, docked at 1, with the
+    /// `defaultOn` groups of 11-68; the rest hidden with no groups.
     pub fn stock(index: usize) -> Self {
         let groups = |range: std::ops::Range<usize>, all: bool| -> Vec<String> {
             MESSAGE_GROUPS[range]
@@ -327,9 +187,8 @@ impl ChatWindowLook {
         }
     }
 
-    /// The loader's discipline over the message set — unknown names dropped, duplicates folded,
-    /// **table order** — so `GetChatWindowMessages` (`0x4a0d20`) answers the way a flag walk does —
-    /// table order 0..67 — whatever order a file or a caller listed them in.
+    /// Drops unknown names and duplicates and puts the rest in table order, so
+    /// `GetChatWindowMessages` (`0x4a0d20`) answers as the reference's flag walk does.
     pub fn normalize_messages(&mut self) {
         let mut flags = [false; MESSAGE_GROUPS.len()];
         for m in &self.messages {
@@ -346,10 +205,8 @@ impl ChatWindowLook {
     }
 }
 
-/// `x` in the reference's `0..1` float domain → the byte its `__ftol(x · 255.0)` stores, clamped
-/// (see the module docs' divergence note). `NaN` lands on `0` rather than propagating.
-/// `SStrToInt` — the leading decimal integer of a string (an optional sign, then digits), 0 when
-/// there is none.
+/// The leading decimal integer after optional whitespace and a sign, 0 when there is none. The
+/// reference's `SStrToInt` (`0x64ac60`) takes neither the whitespace nor a `+`.
 pub(super) fn leading_int(s: &str) -> i64 {
     let s = s.trim_start();
     let (neg, digits) = match s.strip_prefix('-') {
@@ -370,6 +227,7 @@ pub(super) fn leading_int(s: &str) -> i64 {
     }
 }
 
+/// The byte `__ftol(x · 255.0)` stores, clamped (the module's deviation); non-finite stores 0.
 fn to_byte(x: f64) -> u8 {
     if !x.is_finite() {
         return 0;
@@ -377,13 +235,13 @@ fn to_byte(x: f64) -> u8 {
     (x * 255.0).trunc().clamp(0.0, 255.0) as u8
 }
 
-/// The byte the engine stores → the `0..1` float `GetChatWindowInfo` answers.
 fn from_byte(b: u8) -> f64 {
     f64::from(b) / 255.0
 }
 
-/// The 1-based Lua window id → a live index, or the raise every out-of-range ask gets. Shared by
-/// the getter and the three setters so a window that cannot be read cannot be written either.
+/// The 0-based index of a Lua window id. Deviation: an id outside the seven built windows raises,
+/// where the reference serves ten records and silently ignores any other id (`0x4a0be1`), because
+/// benilla keeps only the seven and every caller loops `1, NUM_CHAT_WINDOWS`.
 fn window_index(id: i64) -> mlua::Result<usize> {
     if id < 1 || id as usize > NUM_CHAT_WINDOWS {
         return Err(mlua::Error::runtime(format!(
@@ -396,11 +254,9 @@ fn window_index(id: i64) -> mlua::Result<usize> {
 }
 
 impl super::Model {
-    /// **Register a channel in window `window`'s list** — the shared tail of `JoinChannelByName`
-    /// (`0x49ec24`–`0x49ede7`) and `AddChatWindowChannel` (`0x4a1000`): `(name, id)` appended
-    /// unless an entry of that name is already there (`SStrCmpI`), and the window marked for the
-    /// persist pass. `name` is the DBC's own Shortcut for a matched row, the argument verbatim for
-    /// a custom channel. Answers whether anything was added.
+    /// Appends `(name, id)` to window `window`'s channels unless the name is there (case-folded):
+    /// the shared tail of `JoinChannelByName` (`0x49ec24`-`0x49ede7`) and `AddChatWindowChannel`
+    /// (`0x4a1000`). `name` is the DBC Shortcut for a matched row, else the argument verbatim.
     pub(super) fn register_window_channel(&mut self, window: usize, name: String, id: u32) -> bool {
         let Some(look) = self.chat_window_looks.get_mut(window) else {
             return false;
@@ -417,11 +273,9 @@ impl super::Model {
         true
     }
 
-    /// **Strip `key` from every window's list** — leave-by-name `0x49ee70`'s `0x49f001`–`0x49f085`:
-    /// all ten windows, the first entry whose name
-    /// equals `key` case-insensitively, the cell blanked. `key` is the DBC Shortcut when the
-    /// argument matched a row, else the argument verbatim; the numeric form strips nothing,
-    /// because a slot name never equals a window entry. Answers whether anything was stripped.
+    /// Removes the first entry named `key` (case-folded) from every window, as leave-by-name
+    /// `0x49ee70` does (`0x49f001`-`0x49f085`). `key` is the DBC Shortcut for a matched row, else
+    /// the argument; a numeric leave strips nothing, as a slot name never equals a window entry.
     pub(super) fn strip_window_channel(&mut self, key: &str) -> bool {
         let mut stripped = false;
         for (i, look) in self.chat_window_looks.iter_mut().enumerate() {
@@ -440,16 +294,15 @@ impl super::Model {
 }
 
 impl super::UiScript {
-    /// Host-side [`Model::register_window_channel`] — the guild-recruitment cascade's join arm,
-    /// which registers `GuildRecruitment` in window 1 the way `0x49eb70(frameIdx = 0)` does.
+    /// Host-side [`Model::register_window_channel`], for the guild-recruitment join, which
+    /// registers `GuildRecruitment` in window 1 as `0x49eb70(frameIdx = 0)` does.
     pub fn register_chat_window_channel(&mut self, window: usize, name: &str, id: u32) -> bool {
         self.model_mut()
             .register_window_channel(window, name.to_string(), id)
     }
 
-    /// Seed the per-window looks from the host's persisted store — the load path, so it queues no
-    /// change (an echo would re-dirty the file it was just read from; [`Self::set_cvar_host`]'s
-    /// reason, one store over).
+    /// Seeds the records from the host's persisted store. A load queues no change: an echo would
+    /// re-dirty the file just read.
     pub fn set_chat_window_looks(
         &mut self,
         looks: impl IntoIterator<Item = (usize, ChatWindowLook)>,
@@ -463,14 +316,12 @@ impl super::UiScript {
         }
     }
 
-    /// Snapshot every window's look, index 0 = `ChatFrame1` — what the saver writes out.
+    /// Every window's record, index 0 being `ChatFrame1`, for the saver.
     pub fn chat_window_looks(&self) -> Vec<ChatWindowLook> {
         self.model_mut().chat_window_looks.to_vec()
     }
 
-    /// Drain the 0-based indices whose look Lua moved since the last call — the host's cue to
-    /// persist. Deduplicated and ascending, so a slider drag that wrote one window forty times
-    /// costs the saver one entry.
+    /// Drains the 0-based windows Lua changed since the last call, deduplicated and ascending.
     pub fn take_chat_window_changes(&mut self) -> Vec<usize> {
         let mut v: Vec<usize> = std::mem::take(&mut self.model_mut().chat_window_changes)
             .into_iter()
@@ -481,9 +332,7 @@ impl super::UiScript {
 }
 
 impl super::UiScript {
-    /// Drain the `ChatFrame_OpenChat` requests queued since the last call — each is the text the
-    /// caller wants the chat edit box to open prefilled with. The app opens and focuses the box,
-    /// applies its own sticky-type law, and lets the live parse take the text from there.
+    /// Drains the texts `ChatFrame_OpenChat` queued since the last call.
     pub fn take_open_chat_requests(&mut self) -> Vec<String> {
         std::mem::take(&mut self.model_mut().open_chat_requests)
     }
@@ -491,12 +340,6 @@ impl super::UiScript {
 
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     // GetChatWindowInfo(id) → name, fontSize, r, g, b, a, shown, locked, docked.
-    //
-    // Out of range RAISES rather than answering. The reference's array has 10 slots and benilla
-    // builds 7 windows; a question about window 8 is a question about a window that does not exist
-    // here, and the two honest answers are "raise" or "invent a row". Every corpus caller loops
-    // `1, NUM_CHAT_WINDOWS`, so the raise is unreachable from real code and exists to keep the
-    // next caller from reading a fabricated window as a real one.
     lua.globals().set(
         "GetChatWindowInfo",
         lua.create_function(|lua, id: i64| {
@@ -507,43 +350,32 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 .chat_window_looks[i]
                 .clone();
             let shown = if look.shown { Some(1) } else { None };
-            // `docked` is the LIVE position now, not the table's — `FCF_DockFrame`/
-            // `FCF_UnDockFrame` move it through `SetChatWindowDocked` below.
             let docked = look.docked.map(i64::from);
             let num = |v: Option<i64>| match v {
                 Some(n) => Value::Integer(n),
                 None => Value::Nil,
             };
             Ok(MultiValue::from_vec(vec![
-                // name: "" until `SetChatWindowName` stores one — never a label of ours. See
-                // the module docs' trap 1.
                 Value::String(lua.create_string(&look.name)?),
-                // The three the setters below own (1589). Stock is SIZE 0 / COLOR 0 0 0 0 — the
-                // same tuple this getter answered as a constant before those setters existed.
                 Value::Integer(i64::from(look.font_size)),
                 Value::Number(from_byte(look.r)),
                 Value::Number(from_byte(look.g)),
                 Value::Number(from_byte(look.b)),
                 Value::Number(from_byte(look.a)),
                 num(shown), // 1 or nil, never 0
-                // locked — the cache's LOCKED, stock `1`, moved by `SetChatWindowLocked` below.
-                // `1` or nil like `shown`, never `0`: the reference's own boolean-in-a-number.
+                // locked: 1 or nil, never 0
                 if look.locked {
                     Value::Integer(1)
                 } else {
                     Value::Nil
                 },
-                num(docked), // the dock POSITION (1, 2) or nil
+                num(docked), // the dock position or nil
             ]))
         })?,
     )?;
 
-    // SetChatWindowColor(id, r, g, b) — 0x4a14f0, `__ftol(x · 255.0)` per channel.
-    //
-    // FrameXML's caller is `FCF_SetWindowColor` (FloatingChatFrame.lua l.696-704), which tints the
-    // nine CHAT_FRAME_TEXTURES and then saves through here; the tab menu's Background swatch
-    // reaches it via `FCF_SetChatWindowBackGroundColor`. The write is what makes the tint survive
-    // a session — the *visible* tint is the Lua SetVertexColor, not this.
+    // SetChatWindowColor(id, r, g, b) (`0x4a14f0`) only stores: `FCF_SetWindowColor`
+    // (FloatingChatFrame.lua:699) tints the textures itself.
     lua.globals().set(
         "SetChatWindowColor",
         lua.create_function(|lua, (id, r, g, b): (i64, f64, f64, f64)| {
@@ -564,11 +396,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetChatWindowAlpha(id, alpha) — 0x4a15d0, `__ftol(alpha · 255.0)`.
-    //
-    // FrameXML's caller is `FCF_SetWindowAlpha` (l.706-716), the other half of the tab menu's
-    // Background row: its opacity slider drives `FCF_SetChatWindowOpacity` on every drag step.
-    // `frame.oldAlpha` — the value the hover fade returns to — is that same number.
+    // SetChatWindowAlpha(id, alpha) (`0x4a15d0`), called on every opacity-slider step.
     lua.globals().set(
         "SetChatWindowAlpha",
         lua.create_function(|lua, (id, alpha): (i64, f64)| {
@@ -584,22 +412,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetChatWindowLocked(id, isLocked) — `0x4a1650`, writing the record's `+0x8c` locked field
-    // (`0x4a16a2 mov [esi+0xb4fedc],eax`, initialised to **1** at `0x4984e4`, read back as
-    // `GetChatWindowInfo`'s 8th return at `0x4a0cbf`).
-    //
-    // **A `bool` is the faithful store even though the field is an `i32`**: the cache writer
-    // booleanises it through `setne` (`0x499e8b`, fmt `LOCKED %d`), so nothing outside `{0,1}`
-    // survives a file round trip — the same note records that as the difference between this field
-    // and `SIZE`, which does round-trip arbitrary values.
-    //
-    // The one value of the tuple the *player* moves rather than the layout: `FCF_SetLocked`
-    // (FloatingChatFrame.lua l.802-805) writes the frame field and this store in the same breath,
-    // and `FloatingChatFrame_Update` (l.56) seats the frame back from here at load.
-    //
-    // Lua truthiness, not a strict boolean, because the reference's callers pass `1` and `nil` —
-    // `FCF_ToggleLock`'s two arms and `FCF_OpenNewWindow`'s `SetChatWindowLocked(i, nil)`. mlua
-    // marshals both the way the reference binding's own `toboolean` does.
+    // SetChatWindowLocked(id, isLocked) (`0x4a1650`): the record's `+0x8c` (`0x4a16a2`), 1 at
+    // boot (`0x4984e4`). A `bool` holds it, as the cache writer stores it through `setne`
+    // (`0x499e8b`). The argument is Lua truthiness, where the reference coerces through `0x6f1c10`
+    // (default 0): `0` and "off" unlock there and lock here. FrameXML passes only 1 and nil.
     lua.globals().set(
         "SetChatWindowLocked",
         lua.create_function(|lua, (id, locked): (i64, bool)| {
@@ -613,21 +429,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // SetChatWindowDocked(id, position) — the dock half of the record, written by `FCF_SaveDock`
-    // (FloatingChatFrame.lua l.1276-1285) once per docked window on every dock change, and by
-    // `FCF_UnDockFrame` (l.1182) with `nil` to clear it.
-    //
-    // **The argument is a POSITION, not a flag** — this module's §3 trap, and the reason this
-    // takes a number rather than the `bool` `SetChatWindowLocked` takes: `FCF_SaveDock` passes the
-    // running `count`, so window 1 stores `1` and window 2 stores `2`, and that is what
-    // `GetChatWindowInfo`'s 9th return hands back to `FCF_DockFrame(frame, docked)` as its index.
-    // A `nil` clears it (undocked); anything `<= 0` is treated as a clear too, since a dock
-    // position is 1-based and the reference has no zeroth slot.
-    //
-    // **Not persisted yet, and that is a stated gap.** The `chat-cache` writer
-    // (`benilla_app`'s `ui_chat::settings`) renders `DOCKED` alongside `LOCKED`, but an absent key
-    // must keep the *per-window* stock rather than one flat default — see
-    // [`ChatWindowLook::stock`], which is what the parser seeds from.
+    // SetChatWindowDocked(id, position) (`0x4a16b0`): `FCF_SaveDock` (FloatingChatFrame.lua:1282)
+    // writes each docked window's 1-based position, `FCF_UnDockFrame` nil. Nil or a position
+    // outside 1..=255 clears it here; the reference stores a number truncated, a non-number as 0.
     lua.globals().set(
         "SetChatWindowDocked",
         lua.create_function(|lua, (id, position): (i64, Option<i64>)| {
@@ -644,23 +448,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // SetChatWindowSize(id, fontSize) — 0x4a1470.
-    //
-    // FrameXML's caller is `FCF_SetChatWindowFontSize` (l.752-763), which does the visible half
-    // (`chatFrame:SetFont(file, size, flags)`) and then saves through here. A size the reference
-    // never stores is `0` — "the font's own height" — which is what a stock cache holds and what
-    // benilla ships until the player picks one off the Font Size submenu.
+    // SetChatWindowSize(id, fontSize) (`0x4a1470`) only stores; FrameXML sets the font itself.
     lua.globals().set(
         "SetChatWindowSize",
         lua.create_function(|lua, (id, size): (i64, f64)| {
             let i = window_index(id)?;
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
             let look = &mut model.chat_window_looks[i];
-            // The cache's SIZE is a small integer; anything unrepresentable clamps rather than
-            // wrapping (the module docs' divergence, same reason).
-            // `<= 0` is dropped, not stored — the reference's own `jle` at `0x4a14bc`. That is
-            // why a stock `SIZE 0` and "the player picked a size" are different states rather
-            // than the same one written twice.
+            // A size `<= 0` after truncation is dropped (`0x4a14bc jle`). Deviation: one past
+            // `i32::MAX` clamps where the reference keeps the low 32 bits, for the colours' reason.
             let s = if size.is_finite() && size >= 1.0 {
                 size.trunc().min(f64::from(i32::MAX)) as i32
             } else {
@@ -674,29 +470,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ChatFrame_OpenChat(text, chatFrame) — open the chat edit box prefilled with `text`.
-    //
-    // **The second argument is inert, and that is the reference's doing, not a shortcut.** The ref
-    // reaches the box through `chatFrame.editBox`, and in 1.12 every chat frame's `.editBox` is
-    // the *same* global `ChatFrameEditBox`: `FloatingChatFrame_OnLoad` sets
-    // `this.editBox = ChatFrameEditBox` for each frame (FloatingChatFrame.lua l.30), and
-    // ChatFrame1 — which loads before the edit box exists and so skips that `if` — is patched by
-    // the box's own OnLoad, `DEFAULT_CHAT_FRAME.editBox = this` (FloatingChatFrame.xml l.742).
-    // Per-frame edit boxes are a 2.x feature. So `ChatFrame_OpenChat(text, ChatFrame5)` opens the
-    // one and only edit box on a real 1.12 client too, and accepting-and-ignoring the frame here
-    // is exact rather than approximate. `benilla_app`'s `chat_tests` states that as a claim.
-    //
-    // Measured demand: 3 distinct addons, and all three are the same shape — check the box is not
-    // already up, then open it prefilled, else fall back to SetText/Insert:
-    //   FuBar_HeyFu/Core.lua:281,292      ChatFrame_OpenChat(reply, DEFAULT_CHAT_FRAME)
-    //   FuBar_FriendsFu/FriendsFu.lua:434 ChatFrame_OpenChat(format("/w %s ", name))   -- 1 arg
-    //   TipBuddy/TipBuddy.xml:2715,2717   ChatFrame_OpenChat("", chatFrame) / ("/", chatFrame)
-    // Two of the three prefill `/w <name> `, which the app's live parse then turns into whisper
-    // mode with the target extracted — the same path a human typing those characters takes.
-    //
-    // The ref's tail — the PARTY/RAID/BATTLEGROUND sticky downgrade (l.1554-1565) — is not skipped,
-    // it is the app's: `ui_chat::edit`'s open path already applies exactly that law (a sticky PARTY
-    // with nobody in the party opens as SAY), so running it here would be running it twice.
+    // ChatFrame_OpenChat(text, chatFrame) queues `text` for the host to open the chat box with. The
+    // frame is inert: in 1.12 every chat frame's `editBox` is the one `ChatFrameEditBox`
+    // (FloatingChatFrame.lua:30, FloatingChatFrame.xml:742). The stock ChatFrame.lua:1545 defines
+    // the same global and replaces this one when it loads.
     lua.globals().set(
         "ChatFrame_OpenChat",
         lua.create_function(|lua, (text, _chat_frame): (Option<String>, Value)| {
@@ -706,14 +483,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ── The rest of the 0x98 record: name, shown, message types, channels ──────────────────
+    // ── The rest of the record: name, shown, message groups, channels ──────────────────────
     //
-    // `SetChatWindowName 0x4a13f0` / `SetChatWindowShown 0x4a1730` are registrar entries beside
-    // the look setters; `Add/Remove/GetChatWindowMessages`
-    // (`0x4a0e80`/`0x4a0f40`/`0x4a0d20`) and `Add/Remove/GetChatWindowChannel(s)`
-    // (`0x4a1000`/`0x4a1260`/`0x4a0dc0`) read and write the `+0x20` flags and the `+0x64`/`+0x74`
-    // arrays the same census bounded. Every write that moves the record queues the window
-    // for the app's persist pass, like the look setters.
+    // `SetChatWindowName` `0x4a13f0`, `SetChatWindowShown` `0x4a1730`,
+    // `Add/Remove/GetChatWindowMessages` `0x4a0e80`/`0x4a0f40`/`0x4a0d20` and
+    // `Add/Remove/GetChatWindowChannel(s)` `0x4a1000`/`0x4a1260`/`0x4a0dc0`.
 
     fn with_look<T>(
         lua: &Lua,
@@ -730,8 +504,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         Ok(out)
     }
 
-    // The names, resolved against `CHATMSGGROUP` the loader's way; a name with no group is
-    // silently nothing (`0x4a0ea9` scan, no match → no write).
+    // Group names, case-folded; an unknown name is skipped (`0x4a0ea9`).
     fn names_of(args: MultiValue) -> Vec<&'static str> {
         args.iter()
             .filter_map(|v| match v {
@@ -742,8 +515,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             .collect()
     }
 
-    // SetChatWindowName(id, name) — `SStrCopy(record+0, name, 0x20)`: 31 bytes and the NUL; a
-    // non-string second argument is the empty string (`0x4a1436`).
+    // SetChatWindowName(id, name): `SStrCopy(record+0, name, 0x20)`, 31 bytes and the NUL. The
+    // reference stores "" for a name neither string nor number (`0x4a1436`); here a missing or nil
+    // name stores "", and a boolean or table raises.
     lua.globals().set(
         "SetChatWindowName",
         lua.create_function(|lua, (id, name): (i64, Option<String>)| {
@@ -759,10 +533,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetChatWindowShown(id [, shown]) — `+0x94 = 0x6f1c10(L, 2, default 1)`: NO second argument
-    // stores 1; an explicit nil, `false`, `0` or `"off"` store 0 — the reference's own flag
-    // coercion (a boolean, a number by `__ftol`, a string by its digits or by
-    // on/off/enabled/disabled).
+    // SetChatWindowShown(id [, shown]): `+0x94` through the flag coercion `0x6f1c10`, default 1.
+    // No argument stores 1; nil, false, 0, "0", "off" and "disabled" store 0. The reference also
+    // stores 0 for a string opening F or N ("false", "no"), which stores 1 here.
     lua.globals().set(
         "SetChatWindowShown",
         lua.create_function(|lua, (id, rest): (i64, MultiValue)| {
@@ -789,7 +562,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // AddChatWindowMessages(id, "TYPE", "TYPE", …) — each name set in the window's flags.
     lua.globals().set(
         "AddChatWindowMessages",
         lua.create_function(|lua, (id, names): (i64, MultiValue)| {
@@ -815,8 +587,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetChatWindowMessages(id) — the enabled names as a vararg list, which
-    // `ChatFrame_RegisterForMessages(GetChatWindowMessages(id))` consumes directly.
+    // GetChatWindowMessages(id): the enabled group names as varargs, in table order.
     lua.globals().set(
         "GetChatWindowMessages",
         lua.create_function(|lua, id: i64| {
@@ -830,13 +601,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // AddChatWindowChannel(id, "channel") — `0x4a1000`: (i) the
-    // `ChatChannels.dbc` walk compares the argument with each row's **Shortcut**, whole, case-
-    // folded; no match → id 0 and the Lua string; a match with no zone text yet → **nil** (0
-    // values) and nothing stored; a match → the row's id and **the DBC's own Shortcut string**,
-    // not the argument. (ii) The id is the one push. (iii) A name already in the window answers
-    // the id and stores nothing. `ChatFrame_AddChannel` keys its bookkeeping on the answer's
-    // truthiness, and 0 is truthy.
+    // AddChatWindowChannel(id, name) (`0x4a1000`): a whole, case-folded match on a
+    // `ChatChannels.dbc` Shortcut stores the DBC's spelling and answers the row id; no match stores
+    // the name and answers 0, which `ChatFrame_AddChannel` reads as truthy; a matched row with no
+    // zone text yet answers and stores nothing. A name already there only answers the id.
     lua.globals().set(
         "AddChatWindowChannel",
         lua.create_function(|lua, (id, name): (i64, Option<String>)| {
@@ -871,10 +639,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // RemoveChatWindowChannel(id, "channel" | n) — `0x4a1260`: a numeric argument (`SStrToInt`,
-    // n ≠ 0) names joined slot n, whose name is the key — or nothing, when no such slot; 0 (no
-    // digits) keeps the string. Then the shortcut walk above resolves the key to the DBC's own
-    // spelling, and the slot with that name is freed. 0 values.
+    // RemoveChatWindowChannel(id, name | n) (`0x4a1260`): a numeric key names the joined channel
+    // in slot n, and an empty slot removes nothing; the key then resolves to its DBC Shortcut as
+    // above, and the entry of that name is freed.
     lua.globals().set(
         "RemoveChatWindowChannel",
         lua.create_function(|lua, (id, key): (i64, Option<String>)| {
@@ -912,8 +679,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetChatWindowChannels(id) — name, zoneId, name, zoneId, … which
-    // `ChatFrame_RegisterForChannels` walks two at a time.
+    // GetChatWindowChannels(id): `name, zoneId` pairs in slot order.
     lua.globals().set(
         "GetChatWindowChannels",
         lua.create_function(|lua, id: i64| {
@@ -935,16 +701,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 mod tests {
     use crate::script::UiScript;
 
-    /// The tuple is nine values wide and in the reference's own order.
     #[test]
     fn get_chat_window_info_answers_the_nine_value_tuple() {
         let s = UiScript::new().unwrap();
         assert_eq!(s.arity("GetChatWindowInfo(1)").unwrap(), 9);
     }
 
-    /// Trap 1: a stock client has never been told a window's name, so the getter answers `""` and
-    /// FrameXML supplies "General"/"Combat Log". Enchantrix's `if ( name == "" )` fallback is only
-    /// correct because of this.
     #[test]
     fn every_window_name_is_the_empty_string_not_a_label() {
         let s = UiScript::new().unwrap();
@@ -956,11 +718,8 @@ mod tests {
         }
     }
 
-    /// Trap 2: `shown`/`docked` are `nil` where the record stores 0, because FrameXML branches
-    /// on them bare and `0` is true in Lua. At the boot init (`0x4982c0`) window 1
-    /// is shown and undocked — it is the dock, `FCF_DockFrame(ChatFrame1, 1)` at file scope —
-    /// window 2 is shown with `docked 1`, and 3..7 are neither; the `DOCKED 1`/`DOCKED 2`,
-    /// `SHOWN 1`/`SHOWN 0` a stock file carries are what FrameXML's own dock pass then saved.
+    /// At boot (`0x4982c0`) window 1 is shown and undocked, window 2 shown and docked at 1, and
+    /// windows 3 to 7 neither.
     #[test]
     fn hidden_and_undocked_windows_answer_nil_never_zero() {
         let s = UiScript::new().unwrap();
@@ -982,7 +741,7 @@ mod tests {
         for id in 3..=7 {
             assert_eq!(probe(id), ("nil".into(), "nil".into()), "window {id}");
         }
-        // And the truthiness FrameXML actually branches on.
+        // The truthiness FrameXML branches on.
         assert!(s
             .eval::<bool>(
                 "for i = 3, 7 do local _,_,_,_,_,_,shown = GetChatWindowInfo(i) \
@@ -991,9 +750,7 @@ mod tests {
             .unwrap());
     }
 
-    /// Trap 3: `docked` is the dock POSITION `FCF_DockFrame(frame, index)` inserts at — the
-    /// init's window 2 answers 1 (`0x4982c0`: `mov ds:0xb4ff78, 1`), and once FrameXML has saved
-    /// its dock (`FCF_SaveDock`) the stored positions are whatever it wrote.
+    /// The boot init docks window 2 at 1 (`0x4982c0`: `mov ds:0xb4ff78, 1`).
     #[test]
     fn docked_is_a_dock_position_not_a_flag() {
         let mut s = UiScript::new().unwrap();
@@ -1015,8 +772,8 @@ mod tests {
         let _ = s.take_chat_window_changes();
     }
 
-    /// The corpus's own debug-window walk (MikScrollingBattleText, EnhTooltip) runs to completion
-    /// and finds nothing — `string.lower(name)` needs a string, and no window is named "debug".
+    /// The debug-window walk of MikScrollingBattleText and EnhTooltip, whose `string.lower(name)`
+    /// needs a string.
     #[test]
     fn the_corpus_debug_window_walk_completes_and_finds_none() {
         let s = UiScript::new().unwrap();
@@ -1033,7 +790,6 @@ mod tests {
         assert_eq!(found, 0);
     }
 
-    /// A window benilla has no frame for raises rather than answering with an invented row.
     #[test]
     fn a_window_past_the_last_frame_raises() {
         let s = UiScript::new().unwrap();
@@ -1041,8 +797,7 @@ mod tests {
         assert!(s.eval::<i64>("return (GetChatWindowInfo(0))").is_err());
     }
 
-    /// A size `<= 0` is DROPPED, not stored — the reference's own `jle` at `0x4a14bc`, so a stock
-    /// `SIZE 0` cannot be re-written by a caller handing it 0.
+    /// The reference's `jle` at `0x4a14bc`.
     #[test]
     fn a_non_positive_font_size_is_dropped_not_stored() {
         let s = UiScript::new().unwrap();
@@ -1058,10 +813,7 @@ mod tests {
         }
     }
 
-    /// The three setters round-trip through the getter — and they round-trip through the
-    /// reference's BYTE quantisation, not through the float they were handed. `0.4 × 255 = 102`,
-    /// and `102/255` is what comes back — and `0.5` comes back `127/255`, not `128/255`, because
-    /// `__ftol` truncates (a real client stores 127 there).
+    /// `__ftol(x · 255.0)` truncates: 0.4 stores 102 and 0.5 stores 127.
     #[test]
     fn the_setters_round_trip_through_the_engine_byte() {
         let s = UiScript::new().unwrap();
@@ -1083,7 +835,6 @@ mod tests {
             .unwrap();
         assert_eq!(size, 16);
 
-        // The truncation, on the value that shows it: `0.5 × 255 = 127.5`.
         s.run("SetChatWindowAlpha(1, 0.5)").unwrap();
         let a: f64 = s
             .eval("local _,_,_,_,_,a = GetChatWindowInfo(1) return a")
@@ -1095,7 +846,6 @@ mod tests {
         );
     }
 
-    /// Windows are independent: writing window 2 leaves window 1 on the stock row.
     #[test]
     fn a_setter_moves_only_the_window_it_names() {
         let s = UiScript::new().unwrap();
@@ -1110,8 +860,6 @@ mod tests {
         assert_eq!(two, 1.0);
     }
 
-    /// The setters raise on the same range the getter does — a window benilla has no frame for
-    /// cannot be written any more than it can be read.
     #[test]
     fn the_setters_raise_on_a_window_with_no_frame() {
         let s = UiScript::new().unwrap();
@@ -1120,8 +868,8 @@ mod tests {
         assert!(s.run("SetChatWindowSize(8, 14)").is_err());
     }
 
-    /// We clamp where the reference wraps (the module docs' one named divergence): a real client
-    /// stores the low byte of `ftol(2.0 × 255) = 510` and answers `254/255`.
+    /// The deviation: the reference stores the low byte of `__ftol(2.0 · 255) = 510`, answering
+    /// 254/255.
     #[test]
     fn an_out_of_domain_alpha_clamps_rather_than_wrapping() {
         let s = UiScript::new().unwrap();
@@ -1137,8 +885,6 @@ mod tests {
         assert_eq!(a, 0.0);
     }
 
-    /// The host seam: Lua writes queue one index per touched window however many steps the drag
-    /// took, the host load path queues nothing, and the drain is a take.
     #[test]
     fn the_host_seam_dedupes_writes_and_stays_quiet_on_load() {
         let mut s = UiScript::new().unwrap();
@@ -1176,8 +922,6 @@ mod tests {
         assert_eq!(s.chat_window_looks()[0].font_size, 14);
     }
 
-    /// A write that changes nothing queues nothing — the reference's own setters are called on
-    /// every colour-picker drag step, including the ones that land on the value already stored.
     #[test]
     fn a_write_that_moves_nothing_queues_nothing() {
         let mut s = UiScript::new().unwrap();
@@ -1187,8 +931,6 @@ mod tests {
         assert!(s.take_chat_window_changes().is_empty());
     }
 
-    /// `ChatFrame_OpenChat` queues the text for the app; the optional frame argument is accepted
-    /// and dropped (in 1.12 every chat frame shares one edit box — see the install comment).
     #[test]
     fn chat_frame_open_chat_queues_its_text_and_ignores_the_frame() {
         let mut s = UiScript::new().unwrap();
@@ -1210,8 +952,7 @@ mod record_tests {
     use super::{ChatWindowLook, MESSAGE_GROUPS};
     use crate::script::{UiScript, ZoneChannelRow};
 
-    /// The boot init (`0x4982c0`): window 1 shown with groups 1–10, window 2 shown
-    /// at dock index 1 with the 34 `defaultOn` groups of 11–68, the rest empty and hidden.
+    /// The boot init (`0x4982c0`); 34 of groups 11 to 68 are `defaultOn`.
     #[test]
     fn the_stock_records_are_the_boot_init() {
         let s = UiScript::new().unwrap();
@@ -1256,7 +997,7 @@ mod record_tests {
         assert_eq!(s.take_chat_window_changes(), vec![0, 2]);
         s.run("SetChatWindowName(3, 'Loot')").unwrap();
         assert!(s.take_chat_window_changes().is_empty(), "no move, no cue");
-        // The flag coercion (`0x6f1c10`, default 1) and the name cap (`SStrCopy`, 0x20).
+        // The flag coercion (`0x6f1c10`, default 1) and the 31-byte name cap.
         s.run(
             "SetChatWindowShown(4, 'off') SetChatWindowShown(5, '1') SetChatWindowShown(6, 0) \
              SetChatWindowName(4, 'abcdefghijklmnopqrstuvwxyz0123456789')",
@@ -1270,8 +1011,6 @@ mod record_tests {
         assert_eq!(looks[3].name.len(), 31, "31 bytes and the NUL");
     }
 
-    /// The flags: a name resolves against `CHATMSGGROUP` case-folded, an unknown name is
-    /// nothing, and the answer is the table's order whatever order the calls came in.
     #[test]
     fn message_types_are_flags_answered_in_table_order() {
         let mut s = UiScript::new().unwrap();
@@ -1290,7 +1029,6 @@ mod record_tests {
         assert!(!general.iter().any(|m| m == "SAY" || m == "LOOT"));
         assert_eq!(general.len(), 8);
         assert_eq!(s.take_chat_window_changes(), vec![0, 2]);
-        // A host-loaded set is normalised the same way.
         s.set_chat_window_looks([(
             4,
             ChatWindowLook {
@@ -1304,9 +1042,6 @@ mod record_tests {
         );
     }
 
-    /// `AddChatWindowChannel`'s legs (`0x4a1000`): a shortcut match stores the
-    /// DBC's own spelling with its id, a custom name stores as typed with 0, a shortcut with no
-    /// zone text yet is nil and nothing; a duplicate answers the id and stores nothing.
     #[test]
     fn channels_carry_the_zone_id_and_answer_it_on_add() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/client.rs b/crates/benilla-ui/src/script/client.rs
index d1b55d17..9d85cfcc 100644
--- a/crates/benilla-ui/src/script/client.rs
+++ b/crates/benilla-ui/src/script/client.rs
@@ -1,90 +1,39 @@
-//! **Client-identity and script-evaluation verbs** — the small engine globals an addon asks for
-//! before it does anything else (1188 phase 5, prioritised by the phase 6 corpus).
-//!
-//! These are not a guess at what addons want. They are the top of the measured demand list: over a
-//! 218-addon vanilla corpus, `GetBuildInfo` is called by 69 addons and `RunScript` by 52, and both
-//! are called *at file scope* — so a missing one does not degrade an addon, it stops the addon's
-//! very first chunk with `attempt to call global … (a nil value)`. `GetBuildInfo` alone was the
-//! first error for the whole Ace/Atlas/AtlasLoot family, which is a large slice of the ecosystem.
-//!
-//! ## The host-fed pair (decision 1195)
-//!
-//! `GetRealmName` and `GetFramerate` are the next two down that list — 24 addons are stopped dead
-//! by `GetRealmName` at file scope, and it is the **top runtime wall in the corpus** after the
-//! dialect gap. Both read a slot the app pushes, the same shape as the zone-text family: the
-//! engine owns the verb, the host owns the fact.
-//!
-//! `GetRealmName` returning `""` before a realm is known is deliberate and is what the reference
-//! does at the glue screen. An addon keys its saved variables on it (`db[GetRealmName()]`), so
-//! answering `nil` would make that a `table index is nil` error one call deeper — the failure mode
-//! we have been paying for all arc.
+//! The client-identity and script verbs: build, locale, realm, bind location and framerate, with
+//! `RunScript` and `FrameXML_Debug`. The realm, bind location and framerate read slots the app
+//! pushes.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// The 1.12.1 client's own build identity, read out of `WoW.exe`'s string table rather than
-/// remembered: `5875` and `1.12.1` sit adjacent in the binary, and `Sep 19 2006` is its only
-/// build-date string.
-///
-/// **Hardcoding is the faithful answer here, not a shortcut.** benilla targets exactly 1.12.1
-/// (decision 1188), so these are constants of the target, not of our build — an addon asking
-/// `GetBuildInfo()` is asking "which client am I on", and the honest answer is the one we
-/// implement the API of. Our *own* build stamp is a different question with a different verb
-/// ([`crate::script`] has no binding for it, and the reference has none either).
+/// The 1.12.1 client's build identity, as the strings in its binary spell it.
 const VERSION: &str = "1.12.1";
 const BUILD: &str = "5875";
 const BUILD_DATE: &str = "Sep 19 2006";
-// There was a `TOC_VERSION = 11200` here, and `GetBuildInfo` pushed it as a fourth value. The
-// in-game registrar pushes three (decision 1842); the interface number is a later expansion's
-// return, and `benilla.toc`'s own `## Interface` line is where that number belongs.
 
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // `GetLocale()` -> one string, and `IsMacClient()` -> nil, both ARITY-EXACT: `GetLocale
-    // 0x46ce40`/`0x48d8b0` is `0 -> 1 (string?)`, `IsMacClient 0x48c980` is `0 -> 1 (nil)`, both
-    // `exact`/`agree`.
-    //
-    // **`IsMacClient` answering nil is the whole verb, not a placeholder.** The table records the
-    // return KIND as `(nil)` — this binding pushes nil on the PC build the reference was carved
-    // from, and there is nothing else for it to say. FrameXML branches on it for Mac-only key
-    // labels; nil takes the PC arm, which is the arm this client wants.
-    //
-    // `GetLocale` is the two-registration case the shape gate warns about (1843): a glue copy and
-    // an in-game copy, same shape. Ours answers the one locale this client ships against — the
-    // enUS `GlobalStrings.lua` the manifest loads and 1804's reference defaults are read from.
-    // Decision 1880.
+    // `GetLocale()` (glue `0x46ce40`, in-game `0x48d8b0`) returns one string, `enUS`, as benilla
+    // is enUS-only. `IsMacClient()` (`0x48c980`) returns one nil, the PC build's answer, which
+    // takes FrameXML's PC key-label arm.
     g.set(
         "GetLocale",
         lua.create_function(|lua, ()| lua.create_string("enUS"))?,
     )?;
     g.set("IsMacClient", lua.create_function(|_, ()| Ok(Value::Nil))?)?;
 
-    // **`FrameXML_Debug([v])` — the XML loader's own trace switch, get-or-set** (decision 2160).
-    // `0x488440` reads the global `[0xceea30]`
-    // through `0x6edb40`, and:
-    //
-    // - a **Lua-truthy** argument takes the SET arm (`0x48845d je` after `lua_toboolean 0x6f34d0`)
-    //   — so `FrameXML_Debug(0)` genuinely disables it rather than being a masked no-op, because
-    //   the NUMBER zero is truthy in Lua; only `nil`/`false` are not;
-    // - the stored value is `lua_tonumber` truncated **toward zero** (`0x40a2b0`), so `1.9` is 1
-    //   and a non-numeric string is 0, which is 5.0's `tonumber` coercion;
-    // - an absent, nil or false argument is a pure GET and leaves the flag alone;
-    // - it always returns ONE number — the flag's value *after* the call.
-    //
-    // The reference ships a call to it commented out in its own `BasicControls.xml:20`; the
-    // corpus's consumer is `ImprovedErrorFrame`, which drives it off a saved `XMLDebug` CVar at
-    // its OnLoad and died on the missing global. What it gates is
-    // [`crate::loader::LoadReport::traces`].
+    // `FrameXML_Debug([v])` (`0x488440`): get-or-set of the XML loader's trace flag `[0xceea30]`,
+    // which gates `crate::loader::LoadReport::traces`. A Lua-truthy argument sets it, truncated
+    // toward zero (`0x40a2b0`), so `FrameXML_Debug(0)` clears it; nil or false only reads. It
+    // returns the flag after the call.
     g.set(
         "FrameXML_Debug",
         lua.create_function(|lua, v: Value| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             let truthy = !matches!(v, Value::Nil | Value::Boolean(false));
             if truthy {
-                // `lua_tonumber`'s coercion, then truncate toward zero. Anything that will not
-                // coerce is 0 — the same answer `0x6f3620` gives for a non-numeric argument.
+                // A value that will not coerce is 0, as `lua_tonumber` (`0x6f3620`) answers.
                 let n = lua.coerce_number(v)?.unwrap_or(0.0);
                 model.framexml_debug.set(n.trunc() as i32);
             }
@@ -92,7 +41,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // version, build, date — three, and no fourth (decision 1842)
+    // Version, build and date, and no fourth value (the TOC number is a later expansion's): the
+    // in-game `GetBuildInfo` (`0x4884a0`) pushes three strings, the glue one (`0x46cd70`) five.
     g.set(
         "GetBuildInfo",
         lua.create_function(|lua, ()| {
@@ -100,55 +50,26 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 Value::String(lua.create_string(VERSION)?),
                 Value::String(lua.create_string(BUILD)?),
                 Value::String(lua.create_string(BUILD_DATE)?),
-                // **THREE, not four.** The reference's in-game `GetBuildInfo 0x4884a0` pushes
-                // `(string, string, string)`; the interface/TOC number is a later-expansion return
-                // and 1.12 has no fourth value here. (Its GLUE twin `0x46cd70` pushes five — the
-                // same name with a different shape per registrar table, which is why 1842's gate
-                // keys on the table and not the name.) Decision 1842.
             ]))
         })?,
     )?;
 
-    // `RunScript(text)` — compile and run a chunk in the shared global state.
-    //
-    // `RunScript 0x48b980` (pair `0x83e288`, name `0x83ea60`) is how a macro body, a `/script`
-    // slash command and every addon's "evaluate this snippet" helper reach Lua. It inherits the
-    // same sandbox as our chunk loader: there is no `setfenv` here and none in the reference
-    // either — a script runs with full API access.
-    //
-    // Read end to end, its contract is four facts, and three of them were wrong here (2136's
-    // "left open", closed at the bytes):
-    //
-    // **1 · The chunk name is the SOURCE ITSELF, verbatim.** `0x48b9c7 mov edx,eax` and
-    // `0x48b9c9 mov ecx,eax` hand `lua_tostring 0x6f3690`'s one return to
-    // `0x704cd0 FrameScript_Execute(code, chunkname)` as BOTH arguments. `0x704cd0` strlens the
-    // code (`0x704cd7`) and passes the name straight through `FS_DoBuffer 0x704ae0`
-    // (`0x704b06 push ecx`, the fourth argument of `luaL_loadbuffer 0x6f5690` at `0x704b0c`)
-    // untouched. No `=`, no `@` — so `luaO_chunkid 0x6f5c40` renders it by its third rule,
-    // `[string "…"]`, exactly as `loadstring`'s default source-name does (2136 §4). `=[RunScript]`
-    // was a placeholder that rendered plausibly; `=` is chunkid's *print-verbatim* marker and
-    // `[RunScript]` is not a literal the image contains.
-    //
-    // **2 · A bad argument is a SILENT NO-OP, not a raise.** `0x48b988 call 0x6f3510`
-    // (`lua_isstring` — tag-based, so a *number* passes) failing takes `0x48b98f je` straight to
-    // `0x48b9f3 xor eax,eax; ret`. So does a NULL from `lua_tostring` (`0x48b99f`) and an EMPTY
-    // string (`0x48b9a1 cmp byte ptr [eax],0`). There is no `luaL_error 0x6f4940` anywhere in the
-    // function — `RunScript(nil)` does nothing at all.
-    //
-    // **3 · An error does NOT reach the caller.** `0x704ae0` pushes the registered error handler
-    // from the registry first (`0x704afe`, `[0x8722c8]` at `LUA_REGISTRYINDEX 0xffffd8f0`) and
-    // runs the chunk as `lua_pcall(L, 0, 0, -2)` (`0x704b68`); a *compile* failure takes the other
-    // leg and pcalls that same handler with the message (`0x704b42`). Either way the raise is
-    // consumed, the red line is the handler's doing, and the caller's next statement runs. Raising
-    // here made one bad `RunScript` abort whatever ran it — a macro could take FrameXML down with
-    // it.
-    //
-    // **4 · It answers zero values on every path** (`xor eax,eax` at both exits).
+    // `RunScript(text)` (`0x48b980`) runs a chunk in the shared global state with full API
+    // access, no `setfenv`. Its contract:
+    // 1. The chunk name is the source itself: the one `lua_tostring` result is passed as both
+    //    code and name to `FrameScript_Execute` (`0x704cd0`), so an error renders
+    //    `[string "…"]`, as `loadstring`'s default does.
+    // 2. An argument that is neither a string nor a number, or is empty, is a silent no-op, never
+    //    a raise (`0x48b98f`, `0x48b99f`, `0x48b9a1`); `lua_isstring` (`0x6f3510`) passes a number.
+    // 3. An error never reaches the caller: `0x704ae0` runs the chunk under `lua_pcall` with the
+    //    registered error handler (`0x704b68`), and a compile failure goes to the same handler
+    //    (`0x704b42`).
+    // 4. It returns zero values on every path.
     g.set(
         "RunScript",
         lua.create_function(|lua, text: Value| {
-            // `lua_isstring` + `lua_tostring`, in one: strings and numbers coerce, everything
-            // else is `None` — and `None` is the silent return, per fact 2.
+            // `lua_isstring` and `lua_tostring` in one: strings and numbers coerce, anything else
+            // is the silent return (2).
             let Some(s) = lua.coerce_string(text)? else {
                 return Ok(());
             };
@@ -156,8 +77,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             if raw.is_empty() {
                 return Ok(());
             }
-            // The name is the source bytes as given. Same rule as `loadstring`'s default
-            // (`stdlib::loadstring`), and for the same reason: the image passes one pointer twice.
+            // The chunk name is the source bytes as given (1).
             let name = String::from_utf8_lossy(&raw).into_owned();
             if let Err(e) = lua
                 .load(&*raw)
@@ -173,11 +93,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetRealmName()` — the realm this session is on, as the realm list spells it.
-    //
-    // The corpus's most-wanted engine verb after the dialect fix: 24 addons stop on it, and they
-    // stop *at file scope*, because the idiom is `MyAddonDB[GetRealmName()] = …` in a chunk's
-    // opening lines. `""` until the app pushes one (the glue screen's own answer), never `nil`.
+    // `GetRealmName()`: the realm as the realm list spells it; `""` until the app pushes one, the
+    // glue screen's answer, never nil, as addons index saved variables with it at file scope.
     g.set(
         "GetRealmName",
         lua.create_function(|lua, ()| {
@@ -186,15 +103,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `RequestTimePlayed()` — ask the server for /played, answered by `TIME_PLAYED_MSG`.
-    //
-    // **The request and the answer are two halves and only both are worth having.** The binding
-    // queues a `CMSG_PLAYED_TIME` the app drains; the app fires `TIME_PLAYED_MSG(total, level)`
-    // when `SMSG_PLAYED_TIME` lands. Shipping only this half would be 1203 exactly: `QuestHistory`
-    // calls it and then waits on an event that never comes, which is quieter and worse than the
-    // `attempt to call global` it gets today.
-    //
-    // It returns nothing — the answer arrives as an event, never as a return value.
+    // `RequestTimePlayed()` queues a `CMSG_PLAYED_TIME` and returns nothing; the answer is the
+    // `TIME_PLAYED_MSG(total, level)` the app fires when `SMSG_PLAYED_TIME` lands.
     g.set(
         "RequestTimePlayed",
         lua.create_function(|lua, ()| {
@@ -205,18 +115,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBindLocation()` — the hearthstone's bind location NAME, as the reference's own hearth
-    // confirmation prints it (`StaticPopup.lua:1742` formats it straight into the dialog text).
-    //
-    // Three corpus addons read it, in three separate files: FuBar_TransporterFu
-    // (`TransporterFu.lua:456`), Necrosis (`Necrosis.lua:1089`) and _LazyPig (`LazyPig.lua:623`).
-    //
-    // **`""` until the app pushes one, never nil — the same choice `GetRealmName` above makes, for
-    // the same reason.** Necrosis CONCATENATES the result (`..GetBindLocation()`), so a nil is a
-    // raise rather than a blank; the reference holds a string buffer that is empty before
-    // `SMSG_BINDPOINTUPDATE` lands, and no logged-in character is ever without a bind point, so the
-    // empty window is ours alone. Conflating "not yet known" with "bound nowhere" is the price, and
-    // it is the price the neighbouring verb already pays deliberately.
+    // `GetBindLocation()`: the hearthstone's bind location name, which the instance-boot dialog
+    // formats into its text (`StaticPopup.lua:1742`). `""` until `SMSG_BINDPOINTUPDATE` lands, as
+    // the reference's empty buffer, never nil, since addons concatenate it.
     g.set(
         "GetBindLocation",
         lua.create_function(|lua, ()| {
@@ -225,12 +126,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetFramerate()` — frames per second, as a number.
-    //
-    // 71 addons in the corpus call it; every performance readout on the ecosystem's FuBar/Titan
-    // panels is this one verb. The app pushes a smoothed value each tick
-    // ([`super::UiScript::set_framerate`]); 0 before the first push, which is what an addon's
-    // `format("%.1f", GetFramerate())` needs to not error.
+    // `GetFramerate()`: frames per second, a smoothed value the app pushes each tick; 0, a number,
+    // before the first push.
     g.set(
         "GetFramerate",
         lua.create_function(|lua, ()| {
@@ -243,18 +140,14 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 }
 
 impl super::UiScript {
-    /// Drain the `RequestTimePlayed()` asks queued since the last call — each one is a
-    /// `CMSG_PLAYED_TIME`. [`super::UiScript::take_pvp_toggles`]'s shape, and a count for the same
-    /// reason: the request packet is empty, so nothing distinguishes two asks but their number.
+    /// Drain the `RequestTimePlayed()` asks, each a `CMSG_PLAYED_TIME`: a count, as the request
+    /// body is empty.
     pub fn take_played_time_asks(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().played_time_asks)
     }
 
-    /// Push the hearthstone bind location's name — the host's half of `GetBindLocation`.
-    ///
-    /// The app resolves `SMSG_BINDPOINTUPDATE`'s AreaTable id through the same catalog the
-    /// hearthstone's `$z` token already goes through, so the two can never disagree about where the
-    /// player is bound. Idempotent; the empty string means the packet has not landed yet.
+    /// Push the bind location's name, resolved from `SMSG_BINDPOINTUPDATE`'s AreaTable id through
+    /// the catalog the hearthstone's `$z` uses, so the two agree; empty until the packet lands.
     pub fn set_bind_location(&mut self, area_name: &str) {
         let mut model = self.model_mut();
         if model.bind_location != area_name {
@@ -262,25 +155,10 @@ impl super::UiScript {
         }
     }
 
-    /// Push the realm name — the host's half of `GetRealmName` (decision 1195).
-    ///
-    /// Set at world entry from the realm the session actually connected to. Idempotent, and the
-    /// empty string is a legitimate value (no realm yet), not a "clear".
-    /// Seed the **local player record** — the reference's `0xc27d80`, copied from the char-enum
-    /// row at the character-select Enter World commit (decisions 2261/2263, and see
-    /// [`super::PlayerRecord`] for the bytes and the four verbs that read it).
-    ///
-    /// Called from the world-entry UI load beside [`Self::set_realm_name`], and for the same
-    /// reason 1195 put the realm there: the values have to be in the VM before a single addon file
-    /// runs, because `local currentPlayer = UnitName("player")` at file scope is the corpus idiom.
-    /// The reference has them a whole login earlier still.
-    ///
-    /// **A record with no name is refused, not stored.** The only unset state is "no Enter World
-    /// has been committed in this process"; once the record holds a character, nothing in the
-    /// reference's image ever empties it again, so a caller with nothing to say must leave the
-    /// last answer standing rather than blank it. The write is whole-record because the
-    /// reference's is one `rep movsd`: these four fields describe one character and can never
-    /// legitimately be seeded from two.
+    /// Seed the local player record (the reference's `0xc27d80`, [`super::PlayerRecord`]) from the
+    /// char-enum row at Enter World, before any addon file runs, as `UnitName("player")` at file
+    /// scope is common. A record with no name is refused: nothing empties the reference's record
+    /// once it holds a character, so the last one stands.
     pub fn set_player_record(&mut self, record: super::PlayerRecord) {
         if record.name.is_empty() {
             return;
@@ -291,34 +169,21 @@ impl super::UiScript {
         }
     }
 
+    /// Push the realm name, set at world entry from the realm the session connected to; the empty
+    /// string means no realm yet, not a clear.
     pub fn set_realm_name(&mut self, realm: &str) {
         {
             let mut model = self.model_mut();
             if model.realm_name != realm {
                 model.realm_name = realm.to_string();
             }
-            // The `realmName` CVar is the SAME fact, and it is set here so it cannot drift from
-            // `GetRealmName()`. It is a real 1.12 CVar (`0x83f2d0`, persisted — the client builds
-            // its SavedVariables path from it), and it had no
-            // value at all here: `Ace/AceState.lua:27` is
-            // `ace.trim(GetCVar("realmName"))` inside `SetGameState`, which EVERY Ace addon runs at
-            // PLAYER_ENTERING_WORLD, so the nil became `gsub(nil, ...)` and took the family down.
-            //
-            // Through the **engine-write** path, not a bare slot poke. `realmName` is a persisted
-            // CVar — its whole documented job is to be the last realm connected to — and a slot
-            // written in place never reaches `cvar_changes`, so the host never hears it and never
-            // dirties the config file. The value was therefore correct for exactly as long as the
-            // process lived and absent from `config.toml` forever, which is the one thing a
-            // persisted CVar must not be. `set_from_engine` is the same silent-on-unknown-name
-            // write (a bare test VM registers nothing) and additionally queues the change.
+            // The persisted `realmName` CVar (`0x83f2d0`) is the same fact, set here so it cannot
+            // drift from `GetRealmName()`; the engine write queues the change, so it is saved.
             super::cvars::set_from_engine(&mut model, "realmName", realm.to_string());
         }
     }
 
-    /// Push the current framerate — the host's half of `GetFramerate`.
-    ///
-    /// Pushed per tick from the app's own frame clock rather than computed here: this crate has no
-    /// clock, and a number an addon polls every `OnUpdate` should not be re-derived per call.
+    /// Push the current framerate, from the app's frame clock each tick; this crate has no clock.
     pub fn set_framerate(&mut self, fps: f64) {
         self.model_mut().framerate = fps;
     }
@@ -328,21 +193,8 @@ impl super::UiScript {
 mod tests {
     use crate::script::UiScript;
 
-    /// `GetBuildInfo` answers as the 1.12.1 client: **three strings, and no fourth value.**
-    ///
-    /// This used to assert four and explain the fourth as the `tocversion` an addon compares
-    /// against its own `## Interface` — which is a TBC-and-later idiom. The in-game registrar
-    /// `0x4884a0` pushes `(string, string, string)` and nothing else (decision 1842); the
-    /// interface number arrives in a later expansion.
-    ///
-    /// The corpus agrees, and it is worth the count: **458 sites** write
-    /// `local version = GetBuildInfo()` and take one value. **Four** destructure a fourth — and on
-    /// the real 1.12 client those four read `nil`, which is what their authors shipped against.
-    /// Handing them `11200` was benilla being more generous than the client, which is the superset
-    /// 1189 exists to stop.
-    ///
-    /// **The same name has a different shape in the glue registrar** (`0x46cd70`, five strings).
-    /// This VM is the in-game one. That pair is why 1842's gate keys on the table, not the name.
+    /// Three strings and no fourth, as the in-game registrar pushes (`0x4884a0`); this VM is the
+    /// in-game one, not the glue (`0x46cd70`, five).
     #[test]
     fn get_build_info_answers_as_the_1_12_1_client() {
         let s = UiScript::new().unwrap();
@@ -357,9 +209,7 @@ mod tests {
         );
     }
 
-    /// `GetRealmName` answers `""` before the host pushes one — **never `nil`**, because the
-    /// corpus idiom is `MyAddonDB[GetRealmName()] = …` at file scope and a nil index errors one
-    /// call deeper, far from the cause.
+    /// Never nil: addons index with it at file scope, and a nil index errors far from the cause.
     #[test]
     fn get_realm_name_is_empty_before_it_is_known_and_the_host_pushes_it() {
         let mut s = UiScript::new().unwrap();
@@ -376,8 +226,6 @@ mod tests {
         );
     }
 
-    /// `GetFramerate` is a number from the first call, so `format("%.1f", GetFramerate())` in an
-    /// addon's `OnUpdate` cannot error before the app has pushed a frame.
     #[test]
     fn get_framerate_is_a_number_before_the_first_push() {
         let mut s = UiScript::new().unwrap();
@@ -395,16 +243,8 @@ mod tests {
         );
     }
 
-    /// `RunScript` runs its text in the shared global state, and a failure is **recorded, not
-    /// raised** — `0x704ae0` runs the chunk under `lua_pcall(L, 0, 0, -2)` with the registry's
-    /// error handler, so the raise never reaches the caller. (The full contract, and the three
-    /// silent legs, are in `script::tests::stdlib`.)
-    ///
-    /// This test used to assert the opposite, on the reasoning that "a silent nil is a broken
-    /// macro that looks fine". The reasoning was sound and the premise was not: the reference is
-    /// not silent, it hands the message to the error handler and keeps going. Failing loudly *at
-    /// the caller* is the part it does not do, and doing it meant one bad macro could abort the
-    /// FrameXML function that ran it.
+    /// A failure is recorded, not raised: `0x704ae0` runs the chunk under `lua_pcall(L, 0, 0, -2)`
+    /// with the registry's error handler.
     #[test]
     fn run_script_evaluates_in_the_shared_state_and_reports_without_raising() {
         let mut s = UiScript::new().unwrap();
@@ -420,9 +260,8 @@ mod tests {
         );
     }
 
-    /// `GetLocale` answers one string and `IsMacClient` answers nil — the reference's own shapes
-    /// (`GetLocale 0x46ce40`/`0x48d8b0`, `IsMacClient 0x48c980`, both `exact`/`agree`), and the
-    /// arity is the half a caller branches on.
+    /// The reference's arities: `GetLocale` (`0x48d8b0`) one string, `IsMacClient` (`0x48c980`)
+    /// one nil.
     #[test]
     fn the_client_identity_pair_answers_its_reference_arity() {
         let s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/clip.rs b/crates/benilla-ui/src/script/clip.rs
index 11b1a945..9284fc9f 100644
--- a/crates/benilla-ui/src/script/clip.rs
+++ b/crates/benilla-ui/src/script/clip.rs
@@ -1,6 +1,4 @@
-//! The ScrollFrame clip (decision 0112 §4/§5) — shared by [`UiScript::extract`](super::UiScript::extract)
-//! and [`pointer`](super::pointer)'s hit-test. Both need the same answer to "which ScrollFrame rects
-//! does this frame draw/hit within?", so the walk lives here once and mod.rs re-exports it.
+//! The ScrollFrame clip, shared by `extract` and the pointer hit-test so drawing and hitting agree.
 
 use std::collections::HashMap;
 
@@ -10,11 +8,8 @@ use crate::widget::{FrameKind, KindState};
 use super::model::Model;
 use super::FrameHandle;
 
-/// Every live ScrollFrame with a resolved rect and a live child, as `child handle → the
-/// scrollframe's resolved rect`. The map [`effective_clip`] walks against; built fresh per
-/// `extract`/`hit_test` call (cheap — one pass over the arena, same cost class as
-/// [`crate::order::traversal`]), never cached, so a `SetScrollChild`/`SetVerticalScroll` between
-/// calls is picked up with no invalidation to track.
+/// Scroll child → its ScrollFrame's resolved rect, for every live ScrollFrame with a rect and a
+/// live child. Rebuilt per call and never cached, so no scroll change needs invalidating.
 pub(super) fn scroll_clip_sources(model: &Model) -> HashMap<FrameHandle, Rect> {
     let mut sources = HashMap::new();
     for (h, frame) in model.arena.iter_frames() {
@@ -35,13 +30,8 @@ pub(super) fn scroll_clip_sources(model: &Model) -> HashMap<FrameHandle, Rect> {
     sources
 }
 
-/// The effective clip a frame `h` draws/hits within: intersecting the resolved rect of every
-/// ScrollFrame whose registered child is `h` itself **or** an ancestor of `h` (walking `h` up
-/// through its parent chain) — so both the scroll child's own quads and every descendant's quads
-/// (a grandchild region, a button nested arbitrarily deep) are clipped, and nested ScrollFrames
-/// (an inner ScrollFrame's child living inside an outer one's) intersect their rects rather than
-/// the inner overriding the outer. `None` = unclipped (the common case — no ancestor is a
-/// registered scroll child).
+/// The clip `h` draws and hits within: the intersection of every ScrollFrame rect whose scroll
+/// child is `h` or an ancestor of it, so nested ScrollFrames intersect; `None` is unclipped.
 pub(super) fn effective_clip(
     model: &Model,
     sources: &HashMap<FrameHandle, Rect>,
@@ -63,10 +53,8 @@ pub(super) fn effective_clip(
     clip
 }
 
-/// Axis-aligned rect intersection (y-up: `top`/`right` shrink to the tighter bound, `bottom`/`left`
-/// grow to the tighter bound). Two ScrollFrame clips that don't overlap collapse to an inverted
-/// (empty) rect — `point_in_rect` ([`pointer`](super::pointer)) then never hits it and the CPU clip
-/// in `ui_pass` already treats a degenerate intersection as "nothing to draw" (see its `clip_quad`).
+/// Rect intersection, y-up. Disjoint rects give an inverted rect, which the pointer never hits
+/// and the app's `clip_quad` draws nothing in.
 pub(super) fn intersect_rect(a: Rect, b: Rect) -> Rect {
     Rect::new(
         a.bottom.max(b.bottom),
diff --git a/crates/benilla-ui/src/script/colorselect.rs b/crates/benilla-ui/src/script/colorselect.rs
index 08cdef69..8217a82b 100644
--- a/crates/benilla-ui/src/script/colorselect.rs
+++ b/crates/benilla-ui/src/script/colorselect.rs
@@ -1,53 +1,10 @@
-//! The `ColorSelect` method surface — the `CSimpleColorSelect` widget behavior over the kind tag
-//! (factory `0x6eef90`; LoadXML `0x78b3f0`, script-map `0x78b4f0`). The widget holds one colour and
-//! fires `OnColorSelect` (its own
-//! script slot, `+0x338`) when that colour is set.
-//!
-//! **Why this is engine-side and not four lines of Lua on `ColorPickerFrame`.** The corpus creates
-//! its own: `TipBuddy.xml` declares two `<ColorSelect>` frames (`TBColorPickerFrame`,
-//! `TBColorPickerFrame_Text`), each with its own `<OnColorSelect>` handler, and drives them with
-//! `SetColorRGB`/`GetColorRGB`. A method table hung on the one frame `assets/ui` ships would leave
-//! those two with a widget that has no methods — the "privileged built-in" failure the `.toc`
-//! header names. So it lives with `Slider`/`StatusBar`, in the per-kind dispatcher.
-//!
-//! **The colour law is byte-verified, and it is not what it looks like.** This module was first
-//! written against the obvious model — store three RGB bytes, hand them back — which is wrong.
-//! Two corrections, both load-bearing:
-//!
-//! 1. **The state is HSV `f32`, not RGB** — see [`ColorSelectState`] for the members and why.
-//! 2. **The round trip is not the identity.** Inbound and outbound use *different* quantizers
-//!    (round-half-up vs floor), so `SetColorRGB` → `GetColorRGB` returns a channel one step low on
-//!    **9.7527 % of all 256³ reachable colours** — and, because the map is idempotent-free, the
-//!    FrameXML idiom `r,g,b = f:GetColorRGB() … f:SetColorRGB(r,g,b)` **ratchets** a channel
-//!    downward one step per cycle. `SetColorRGB(0, 1, 1)` fires `OnColorSelect(0, 254/255, 1)`.
-//!    Every Ace2/Dewdrop colour option is that idiom, once per open-and-accept, so this is visible
-//!    behaviour, not a curiosity — it is transcribed because it is what the client computes, and
-//!    [`ColorSelectState`]'s docs record the one-line change that would undo it if it ever must go.
-//!
-//! **`SetColorRGB` fires `OnColorSelect`, synchronously, on every call.** VERIFIED at the bytes:
-//! `0x78ed01 call 0x78bae0` is a plain fall-through of the last basic block, and inside it the only
-//! conditional (`0x78bafd`) tests whether a handler is *bound*. There is deliberately **no
-//! change-gate** — the contrast with [`crate::widget::SliderState::store_value`] is real and was
-//! verified the other way in the same pass (`CSimpleSlider::SetValue 0x789930` skips on equal at
-//! `0x789a16`): two sibling widgets in one band, opposite gating. It matters here because a caller
-//! re-setting the colour it already holds still expects its `func` to run — which is exactly how a
-//! Dewdrop colour row opens, and how the reference's own `ColorPickerFrame.xml` paints its preview
-//! swatch (nothing else ever writes it).
-//!
-//! **The four texture accessors are carried** (`SetColorWheelTexture` `0x78de90` /
-//! `SetColorWheelThumbTexture` `0x78e160` / `SetColorValueTexture` `0x78e450` /
-//! `SetColorValueThumbTexture` `0x78e720`, plus the getters `0x78dd80`/`0x78e070`). They had zero
-//! callers in the 218-addon corpus and waited for one under decision 1195; the customer that
-//! arrived is our own `ColorPickerFrame.xml`, whose four elements the XML loader installs through
-//! exactly these — two of them with **no file at all**, because the disc and the strip are pixels
-//! the client computes and the app renderer now computes too (decision 1592 — the wheel `0x78b580`
-//! and the value strip `0x78b8a0` generate them).
-//!
-//! **NOT carried, still waiting for a customer (decision 1195):** `SetColorHSV`/`GetColorHSV`
-//! (`0x78e920`/`0x78ea00`) — zero corpus callers, though the state they would read and write is
-//! now the right shape for them, and [`ColorSelectState::set_hsv`] is already the store they'd
-//! use (three *raw* `f32` — no clamp, no quantize, zero `fcom` in its body), because the drag path
-//! needs exactly that.
+//! The `ColorSelect` methods: the `CSimpleColorSelect` widget (factory `0x6eef90`, XML load
+//! `0x78b3f0`), one colour held as HSV floats. `SetColorRGB` fires `OnColorSelect` (script map
+//! `0x78b4f0`, slot `+0x338`) on every call: `0x78ed01` calls `0x78bae0`, whose only test
+//! (`0x78bafd`) is for a bound handler, while `CSimpleSlider::SetValue` (`0x789930`) skips an equal
+//! value. The RGB round trip loses a step on 9.75 % of colours, as in the reference: in and out use
+//! different quantizers (round-half-up, then floor), so reading back and setting ratchets a channel
+//! down; see [`ColorSelectState`].
 
 use mlua::{Lua, Table, Value};
 
@@ -59,13 +16,11 @@ use crate::layout::Rect;
 use crate::order::DrawLayer;
 use crate::widget::{ColorSelectState, FrameHandle, KindState, RegionHandle, RegionKind};
 
-/// Registry key of the ColorSelect method table (the MAXCSTACK discipline: Lua-side root, named
-/// key).
+/// Registry key of the ColorSelect method table (the MAXCSTACK discipline: a Lua-side root).
 pub(super) const REG_COLORSELECT_METHODS: &str = "__benilla_colorselect_methods";
 
-/// Run `f` over a frame's ColorSelect state under one short write borrow. Errors if `this` is not a
-/// live ColorSelect (unreachable through the kind dispatcher, but the method table is a plain Lua
-/// value — a caller could fish it out and misapply it).
+/// Run `f` over a frame's ColorSelect state under one short write borrow; errors if `this` is not
+/// a live ColorSelect, as the method table is a plain Lua value a caller can misapply.
 fn with_colorselect<T>(
     lua: &Lua,
     this: &Table,
@@ -83,9 +38,8 @@ fn with_colorselect<T>(
     }
 }
 
-/// One of the widget's four texture sub-objects. The wheel and the strip are the two the press
-/// handler (`0x78bf10`) hit-tests (`[+0x318]+0x24` and `[+0x320]+0x24`);
-/// the two thumbs are pure output, positioned from the HSV at extract.
+/// One of the widget's four texture sub-objects: the press handler (`0x78bf10`) hit-tests the
+/// wheel (`+0x318`) and the strip (`+0x320`); the thumbs are output only, placed at extract.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 enum Slot {
     Wheel,
@@ -114,8 +68,8 @@ impl Slot {
         *slot = Some(rh);
     }
 
-    /// The layer a slot's region is born on: the wheel is bound at layer 2 (ARTWORK) through
-    /// `0x77fd10`, with the two markers on OVERLAY above the art they ride.
+    /// The layer a slot's region is born on: ARTWORK for the art (the wheel's layer 2, through
+    /// `0x77fd10`), OVERLAY for the two markers above it.
     fn layer(self) -> DrawLayer {
         match self {
             Slot::Wheel | Slot::ValueStrip => DrawLayer::Artwork,
@@ -124,8 +78,7 @@ impl Slot {
     }
 }
 
-/// Get-or-create one slot's texture region; `layer` re-layers an existing one. Returns the region
-/// id (for wrapper lookup). The Slider's `ensure_thumb` is the same function one slot wider.
+/// Get-or-create one slot's texture region, `layer` re-layering an existing one; returns its id.
 fn ensure_slot(lua: &Lua, this: &Table, slot: Slot, layer: Option<DrawLayer>) -> mlua::Result<u32> {
     let h = frame_handle_of(lua, this)?;
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -153,7 +106,7 @@ fn ensure_slot(lua: &Lua, this: &Table, slot: Slot, layer: Option<DrawLayer>) ->
                 .create_region(h, RegionKind::Texture, layer.unwrap_or(slot.layer()), 0)
                 .ok_or_else(|| mlua::Error::runtime("stale frame handle"))?;
             model.region_data.insert(rh, RegionData::default());
-            model.touch_layout(); // a region entered the layout gate's read set (decision 0740)
+            model.touch_layout(); // a region entered the layout gate's read set
             if let Some(frame) = model.arena.frame_mut(h) {
                 if let KindState::ColorSelect(s) = &mut frame.kind_state {
                     slot.set(s, rh);
@@ -165,10 +118,9 @@ fn ensure_slot(lua: &Lua, this: &Table, slot: Slot, layer: Option<DrawLayer>) ->
     Ok(model.region_id(rh))
 }
 
-/// `Set<Slot>Texture([path [, drawLayer]] | r, g, b [, a])`, the Slider's `SetThumbTexture` two-form
-/// plus a **third**: called with nothing at all it just creates the region. That empty form is not a
-/// convenience — it is the only one the two file-less elements can use, and it is what
-/// `<ColorWheelTexture/>` means. A slot left file-less is where the app renderer paints.
+/// `Set<Slot>Texture([path [, drawLayer]] | r, g, b [, a])`, plus an empty form that only creates
+/// the region: what `<ColorWheelTexture/>` means. A file-less slot is where the app renderer paints
+/// the disc and strip the reference computes (`0x78b580`, `0x78b8a0`).
 fn install_slot_texture(
     lua: &Lua,
     m: &Table,
@@ -232,7 +184,6 @@ fn install_slot_texture(
     Ok(())
 }
 
-/// A Lua number argument as `f32`, 0 for anything else — the Slider's own colour-form helper.
 fn num_f32(v: &Value) -> f32 {
     match v {
         Value::Number(n) => *n as f32,
@@ -246,16 +197,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 
     m.set(
         "SetColorRGB",
-        // Shape C on r, g, b (`ColorSelect:SetColorRGB 0x78eae0`, `2=C 3=C 4=C 5=B`): bare
-        // `lua_tonumber`, nil → 0.0, no raise.
+        // Shape C on r, g, b (`ColorSelect:SetColorRGB 0x78eae0`, `2=C 3=C 4=C 5=B`).
         lua.create_function(|lua, (this, r, g, b): (Table, Value, Value, Value)| {
             let (r, g, b) = (
                 crate::script::object::as_f64(&r),
                 crate::script::object::as_f64(&g),
                 crate::script::object::as_f64(&b),
             );
-            // Store through the client's quantize, then fire with what the widget now *holds* —
-            // the round-tripped values, identical to the next GetColorRGB, not the raw arguments.
+            // Store through the client's quantizer, then fire with what the widget now holds: the
+            // round-tripped values, identical to the next `GetColorRGB`, not the raw arguments.
             let (qr, qg, qb) = with_colorselect(lua, &this, |s| {
                 s.set_rgb(r, g, b);
                 s.rgb_f64()
@@ -268,10 +218,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, this: Table| with_colorselect(lua, &this, |s| s.rgb_f64()))?,
     )?;
 
-    // The four texture accessors (`0x78de90`/`0x78e160`/`0x78e450`/`0x78e720` and the getters
-    // `0x78dd80`/`0x78e070`). They had zero corpus callers and waited for one (decision 1195); the
-    // customer that arrived is our own `ColorPickerFrame.xml`, whose four elements the XML loader
-    // installs through exactly these.
+    // The four texture accessors (`0x78de90`, `0x78e160`, `0x78e450`, `0x78e720`; getters
+    // `0x78dd80`, `0x78e070`), through which the XML loader installs a ColorSelect's elements.
     install_slot_texture(
         lua,
         &m,
@@ -305,9 +253,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Fire `OnColorSelect(self, r, g, b)` — the widget's own script slot (`+0x338`). Fired
-/// outside the model borrow; a handler error goes to [`Model::errors`] rather than back to the
-/// setter's caller, the same posture as the Slider's `OnValueChanged`.
+/// Fire `OnColorSelect(self, r, g, b)`; a handler error goes to [`Model::errors`], not the caller.
 fn fire_color_select(lua: &Lua, this: &Table, r: f64, g: f64, b: f64) -> mlua::Result<()> {
     let id = {
         let h = frame_handle_of(lua, this)?;
@@ -327,27 +273,21 @@ fn fire_color_select(lua: &Lua, this: &Table, r: f64, g: f64, b: f64) -> mlua::R
     Ok(())
 }
 
-/// The wheel's normalised coordinates for a cursor at `(x, y)`: the offset from the wheel rect's
-/// centre, scaled by its **half-extents** — so a non-square wheel normalises to a disc, not an
-/// ellipse (`0x78bdd0`..: `nx=(x−cx)/((right−left)·0.5)`, `ny=(y−cy)/((top−bottom)·0.5)`). y is up,
-/// this arena's convention and the client's.
+/// The wheel's normalised coordinates for `(x, y)`: the offset from its centre over its
+/// half-extents, so a non-square wheel normalises to a disc (`0x78bdd0`); y is up, as the client's.
 fn wheel_norm(r: Rect, x: f32, y: f32) -> (f32, f32) {
     let hw = (r.right - r.left) * 0.5;
     let hh = (r.top - r.bottom) * 0.5;
     let cx = (r.left + r.right) * 0.5;
     let cy = (r.bottom + r.top) * 0.5;
-    // A degenerate rect (an unresolved region) would divide by zero; the client cannot reach that
-    // state because it only hit-tests a laid-out texture, and neither can we — but 0/0 is NaN, and
-    // NaN in the HSV would poison every colour after it.
+    // A zero-size rect gives 0, not NaN, which would poison every colour after it.
     let nx = if hw != 0.0 { (x - cx) / hw } else { 0.0 };
     let ny = if hh != 0.0 { (y - cy) / hh } else { 0.0 };
     (nx, ny)
 }
 
-/// The hue/saturation a press or drag at `(x, y)` writes, given the wheel's rect. `H` runs from
-/// `atan2(ny, nx) + π` in degrees — so the wheel's **left** edge is 0°/360° (red) and its right edge
-/// 180° (cyan) — and `S` is the radius, clamped at the rim. Raw f32 the whole way: the drag path
-/// never touches a quantizer.
+/// The hue and saturation a press or drag at `(x, y)` writes: the wheel's left edge is 0° (red)
+/// and its right 180° (cyan), `S` is the radius clamped at the rim, and nothing is quantized.
 fn wheel_hs(r: Rect, x: f32, y: f32) -> (f32, f32) {
     let (nx, ny) = wheel_norm(r, x, y);
     let radius = (nx * nx + ny * ny).sqrt();
@@ -355,9 +295,8 @@ fn wheel_hs(r: Rect, x: f32, y: f32) -> (f32, f32) {
     (hue, radius.min(1.0))
 }
 
-/// The brightness a press or drag at `y` writes, given the strip's rect: the fraction of the way up
-/// it, clamped — `V = clamp((y − bottom) / (top − bottom), 0, 1)` (`0x78beed`). x is ignored, which
-/// is why a drag that wanders sideways off the strip keeps working.
+/// The brightness a press or drag at `y` writes: the clamped fraction of the way up the strip
+/// (`0x78beed`); x is ignored, so a drag may wander sideways off it.
 fn strip_value(r: Rect, y: f32) -> f32 {
     let span = r.top - r.bottom;
     if span == 0.0 {
@@ -366,22 +305,11 @@ fn strip_value(r: Rect, y: f32) -> f32 {
     ((y - r.bottom) / span).clamp(0.0, 1.0)
 }
 
-/// The wheel thumb's rect: the marker seated at the point the current `(H, S)` *came from*. It is
-/// the inverse of [`wheel_hs`], which is the whole invariant — click a pixel, the marker lands on
-/// that pixel.
-///
-/// Byte-exact to `0x78bc20`, which does
-/// `SetPoint(CENTER, wheel, CENTER, −m·cos θ, −m·sin θ)` with `θ = H·π/180` and
-/// `m = GetWidth(wheel)·0.5·S`. Its two `fchs` are the pick law's `+π` seen from the other side:
-/// drop either sign and the marker sits diametrically opposite the colour it marks.
-///
-/// **The width is used on both axes**, deliberately — the client reads `GetWidth` for the vertical
-/// offset too, while the pick law divides `y` by half-*height*. On a non-square wheel the two
-/// therefore disagree, and that asymmetry is reproduced rather than fixed. The reference's wheel is
-/// square, so it costs nothing there and would cost fidelity anywhere else.
-///
-/// `S == 0` puts it dead centre whatever the hue is, which is what makes the `-1` grey sentinel
-/// (`ColorSelectState::hsv`) harmless here: it is multiplied by a zero radius.
+/// The wheel marker's rect, seated where the current `(H, S)` came from, the inverse of
+/// [`wheel_hs`]: `0x78bc20` sets its `CENTER` at `(−m·cos θ, −m·sin θ)` from the wheel's, with
+/// `m = GetWidth(wheel)·0.5·S`, the negations being the pick's `+π`. The width serves both axes,
+/// as in the reference, though the pick divides y by half the height. `S == 0` centres it, so the
+/// `-1` grey hue sentinel is harmless.
 pub(super) fn wheel_thumb_rect(wheel: Rect, thumb_size: Option<(f32, f32)>, hsv: [f32; 3]) -> Rect {
     let (tw, th) = thumb_size.unwrap_or((0.0, 0.0));
     let cx = (wheel.left + wheel.right) * 0.5;
@@ -392,16 +320,10 @@ pub(super) fn wheel_thumb_rect(wheel: Rect, thumb_size: Option<(f32, f32)>, hsv:
     Rect::new(y - th * 0.5, x - tw * 0.5, y + th * 0.5, x + tw * 0.5)
 }
 
-/// The value thumb's rect: centred on the strip horizontally (the reference's marker is 48 wide
-/// over a 32-wide strip, so it deliberately overhangs) and seated `V` of the way up from its
-/// BOTTOM — `0x78bcf0`'s `SetPoint(CENTER, strip, BOTTOM, 0, V·GetHeight)`.
-///
-/// **The height it scales by is the WHEEL's, not the strip's** — `0x78bcf0` dereferences
-/// `[this+0x318]`, the wheel, with no null guard of its own, while anchoring to the strip. The two
-/// are both 128 tall in the reference, so it is invisible there; it is reproduced because a client
-/// that "fixed" it would place the marker somewhere the real one does not the moment an addon
-/// declares a strip of its own height. A widget with no wheel falls back to the strip, which is the
-/// nearest thing to the client's unguarded read that does not put a NaN in a rect.
+/// The value marker's rect: centred on the strip and `V` of the way up from its bottom
+/// (`0x78bcf0`), scaled by the wheel's height, not the strip's, as the reference reads
+/// `[this+0x318]`. Deviation: with no wheel it scales by the strip's, because the reference reads
+/// the missing wheel unguarded.
 pub(super) fn value_thumb_rect(
     strip: Rect,
     wheel: Option<Rect>,
@@ -415,11 +337,8 @@ pub(super) fn value_thumb_rect(
     Rect::new(y - th * 0.5, cx - tw * 0.5, y + th * 0.5, cx + tw * 0.5)
 }
 
-/// The in-flight colour drag. The client keeps **two independent flags** (`+0x314` wheel, `+0x315`
-/// strip), both set by the same press if the rects overlap at the cursor, and its cursor-position
-/// handler applies whichever are set — so this is a pair of bools, not an enum. It also explains the
-/// feel: a drag that starts on the wheel keeps writing hue and saturation no matter where the cursor
-/// wanders, because the flag, not the current position, decides.
+/// The in-flight colour drag: the reference's two independent flags (`+0x314` wheel, `+0x315`
+/// strip), both set when a press hits both; the flag, not the cursor, decides what a move writes.
 #[derive(Clone, Copy)]
 pub(crate) struct ColorDrag {
     pub(crate) frame: FrameHandle,
@@ -427,8 +346,7 @@ pub(crate) struct ColorDrag {
     strip: bool,
 }
 
-/// The two hit rects of a ColorSelect frame — its wheel region's and its value strip's, as resolved
-/// by layout. `None` for a slot with no region, which is every ColorSelect that never declared one.
+/// The laid-out rects of a ColorSelect's wheel and value strip.
 fn hit_rects(model: &Model, h: FrameHandle) -> (Option<Rect>, Option<Rect>) {
     let (wheel, strip) = match model.arena.frame(h).map(|f| &f.kind_state) {
         Some(KindState::ColorSelect(s)) => (s.wheel, s.value_strip),
@@ -438,10 +356,8 @@ fn hit_rects(model: &Model, h: FrameHandle) -> (Option<Rect>, Option<Rect>) {
     (rect(wheel), rect(strip))
 }
 
-/// On a LeftButton press at `(x, y)` whose hit frame is `hit`: if that frame is a ColorSelect and
-/// the cursor is inside its wheel or its value strip, capture the drag and **apply it immediately**
-/// — `0x78bf10` calls the cursor-position handler through `[eax+0x3c]` before it returns, so a
-/// single click jumps the colour to the click point and fires. Returns what the caller must fire.
+/// On a LeftButton press inside a wheel or strip, capture the drag and apply it at once, as
+/// `0x78bf10` does, so a click jumps the colour; returns the id and colour the caller fires.
 pub(super) fn begin_drag(
     model: &mut Model,
     hit: Option<FrameHandle>,
@@ -463,11 +379,8 @@ pub(super) fn begin_drag(
     drag_move(model, x, y)
 }
 
-/// On a pointer move at `(x, y)` while a colour drag is captured: rewrite whichever of H/S and V the
-/// capture owns, straight into the widget's HSV floats, and hand the caller the frame id plus the
-/// colour to fire `OnColorSelect` with. Returns `Some` on **every** captured move, with no
-/// change-gate — the widget deliberately has none (`0x78bafd` tests only whether a handler is
-/// bound), which is the opposite of the Slider next door.
+/// On a pointer move during a drag, write the captured H/S and V into the widget's HSV and return
+/// the frame id and colour to fire with, on every move: there is no change gate (`0x78bafd`).
 pub(super) fn drag_move(model: &mut Model, x: f32, y: f32) -> Option<(u32, f64, f64, f64)> {
     let ColorDrag {
         frame,
@@ -506,15 +419,12 @@ pub(super) fn drag_move(model: &mut Model, x: f32, y: f32) -> Option<(u32, f64,
     Some((model.frame_id(frame), rgb.0, rgb.1, rgb.2))
 }
 
-/// Release any in-flight colour drag (LeftButton up, or the pointer leaving the window) — the
-/// widget's `0x78bf90`, which clears both flags.
+/// Release a colour drag (LeftButton up or the pointer leaving): `0x78bf90` clears both flags.
 pub(super) fn end_drag(model: &mut Model) {
     model.color_drag = None;
 }
 
-/// Fire `OnColorSelect` for a frame the pointer path just recoloured. The setter's own
-/// [`fire_color_select`] needs the caller's `this` table; the pointer has only an id, so this is the
-/// same two lines against [`event::fire_widget_handler`] directly.
+/// Fire `OnColorSelect` by frame id, for the pointer path, which has no `this` table.
 pub(super) fn fire_by_id(lua: &Lua, id: u32, r: f64, g: f64, b: f64) -> mlua::Result<()> {
     event::fire_widget_handler(
         lua,
@@ -529,8 +439,7 @@ mod tests {
     use crate::script::UiScript;
     use crate::widget::ColorSelectState;
 
-    /// A `ColorSelect` starts **white** (the ctor's `H=0, S=0, V=1`), not black. A zero-init store
-    /// would have made it black, which is the tell that the state is HSV and not RGB.
+    /// White, not black: the constructor sets `H=0, S=0, V=1`.
     #[test]
     fn a_fresh_color_select_is_white() {
         let s = UiScript::new().unwrap();
@@ -540,9 +449,7 @@ mod tests {
         assert_eq!((r, g, b), (1.0, 1.0, 1.0));
     }
 
-    /// **The round trip is not the identity, and the deviation is the client's.** `(0, 1, 1)` — cyan,
-    /// a two-channel tie at the maximum — comes back with green one step low, exactly as the
-    /// reference does. Greys are its control class and never lose.
+    /// Cyan, a two-channel tie at the maximum, loses one step of green, as in the reference.
     #[test]
     fn the_round_trip_loses_exactly_one_step_on_the_witness_colour() {
         let s = UiScript::new().unwrap();
@@ -563,10 +470,7 @@ mod tests {
         }
     }
 
-    /// **And it ratchets.** The FrameXML idiom — read the colour back, hand it straight to
-    /// `SetColorRGB` — re-applies the same lossy map instead of settling. `(0, 8, 132)`
-    /// walks to `(0, 0, 132)` in eight cycles. Every Ace2/Dewdrop colour option is that idiom, once
-    /// per open-and-accept, so this is the shape of a real player-visible drift and it is deliberate.
+    /// Reading back and setting walks `(0, 8, 132)` to `(0, 0, 132)`, as in the reference.
     #[test]
     fn the_read_back_ratchets_a_channel_downward() {
         let s = UiScript::new().unwrap();
@@ -585,7 +489,7 @@ mod tests {
             vec![7, 6, 5, 4, 3, 2, 1, 0],
             "one step down per cycle, to a fixed point at 0"
         );
-        // The fixed point holds — it is a ratchet, not a runaway.
+        // 0 is a fixed point: a ratchet, not a runaway.
         let g: f64 = s
             .eval("local r, g, b = cs:GetColorRGB() cs:SetColorRGB(r, g, b) return g")
             .unwrap();
@@ -595,7 +499,7 @@ mod tests {
     /// The two quantizers, directly. A is round-half-up and clamps; B is a floor with no clamp.
     #[test]
     fn the_two_quantizers_disagree_in_the_verified_way() {
-        // A — inbound. The clamp is part of it, so `2` is white and `-1` is black, not a wrapped byte.
+        // A, inbound, clamps: `2` is white and `-1` black, not a wrapped byte.
         assert_eq!(ColorSelectState::quantize_a(-1.0), 0);
         assert_eq!(ColorSelectState::quantize_a(0.0), 0);
         assert_eq!(ColorSelectState::quantize_a(1.0), 255);
@@ -603,7 +507,7 @@ mod tests {
         // The half-up bias: 0.5·255 = 127.5, +0.5 = 128.0, truncated = 128.
         assert_eq!(ColorSelectState::quantize_a(0.5), 128);
 
-        // B — outbound. Endpoints agree with A; a value a hair below a boundary does NOT.
+        // B, outbound: the endpoints agree with A, a half step does not.
         assert_eq!(ColorSelectState::quantize_b(0.0), 0);
         assert_eq!(ColorSelectState::quantize_b(1.0), 255);
         assert_eq!(ColorSelectState::quantize_b(0.5), 127, "floor, not half-up");
@@ -612,12 +516,11 @@ mod tests {
             ColorSelectState::quantize_a(0.5),
             "the disagreement IS the mechanism behind the drift"
         );
-        // No clamp on B — out of range wraps mod 256 (reachable only through SetColorHSV).
+        // B has no clamp: out of range wraps mod 256 (reachable only through `SetColorHSV`).
         assert_eq!(ColorSelectState::quantize_b(-0.001), 255);
     }
 
-    /// `SetColorRGB` fires `OnColorSelect` with the colour the widget now holds, and fires **again**
-    /// when the same colour is set — no change-gate (the module doc's byte-verified reason).
+    /// It fires with the colour the widget now holds, and again on the same colour: no change gate.
     #[test]
     fn set_color_rgb_fires_on_color_select_every_time() {
         let s = UiScript::new().unwrap();
@@ -637,8 +540,7 @@ mod tests {
         assert_eq!(s.eval::<usize>("return table.getn(fired)").unwrap(), 2);
         assert_eq!(s.eval::<String>("return fired[1]").unwrap(), "1,0,0");
 
-        // The handler's arguments are bit-identical to a GetColorRGB() on the next line — the
-        // binary reaches them through literally the same two calls, and so do we.
+        // The handler's arguments equal the next `GetColorRGB()` bit for bit, as in the reference.
         s.run("fired = {} cs:SetColorRGB(0, 1, 1)").unwrap();
         let (from_handler, from_getter): (String, String) = s
             .eval("local r, g, b = cs:GetColorRGB() return fired[1], r .. \",\" .. g .. \",\" .. b")
@@ -646,8 +548,6 @@ mod tests {
         assert_eq!(from_handler, from_getter);
     }
 
-    /// The methods are the ColorSelect's alone — a plain frame duck-types as *not* one, which is how
-    /// `if frame.SetColorRGB then` reads in an addon.
     #[test]
     fn the_methods_do_not_leak_onto_other_kinds() {
         let s = UiScript::new().unwrap();
@@ -657,13 +557,11 @@ mod tests {
         assert!(s.eval::<bool>("return plain.GetColorRGB == nil").unwrap());
     }
     // ─────────────────────────────────────────────────────────────────────────────────────────
-    // The wheel and the strip — the pick, the drag, and the two markers
+    // The wheel and the strip: the pick, the drag and the two markers
     // ─────────────────────────────────────────────────────────────────────────────────────────
 
-    /// A `ColorSelect` with the reference's own geometry, laid out and ready to click: a 128×128
-    /// wheel at the frame's top-left and a 32×128 strip to its right. Built through the XML loader
-    /// so the four elements' whole install path — `apply_colorselect`, the file-less setter form,
-    /// the getter round-trip that carries `<Size>`/`<Anchors>` — is what these tests exercise.
+    /// A ColorSelect with the reference's geometry, laid out: a 128×128 wheel at the top-left and a
+    /// 32×128 strip to its right, built through the XML loader so the elements' install path runs.
     fn picker() -> UiScript {
         let mut s = UiScript::new().unwrap();
         let xml = r#"<Ui>
@@ -698,7 +596,6 @@ mod tests {
         s
     }
 
-    /// The wheel's rect, from the region the loader published as a global.
     fn wheel_rect(s: &mut UiScript) -> (f32, f32, f32, f32) {
         let (l, b, w, h): (f32, f32, f32, f32) = s
             .eval(
@@ -709,8 +606,7 @@ mod tests {
         (l, b, w, h)
     }
 
-    /// The four elements install as real regions with the authored geometry, and the wheel's name
-    /// publishes as a global — which is what `<ColorValueTexture>`'s own anchor resolves against.
+    /// The wheel's name is a global, which `<ColorValueTexture>`'s anchor resolves against.
     #[test]
     fn the_four_elements_install_with_their_authored_geometry() {
         let mut s = picker();
@@ -734,11 +630,8 @@ mod tests {
         assert!(file.contains("UI-ColorPicker-Buttons"), "got {file}");
     }
 
-    /// **A click on the wheel picks the colour that pixel shows.** The disc's law and the pick law
-    /// are inverses (`0x78b580` draws it, `0x78bdd0` picks it), so
-    /// this is stated at the four cardinal points, where the hue is nameable: LEFT is red, RIGHT
-    /// cyan, TOP violet, BOTTOM chartreuse. A sign error anywhere in the chain mirrors one axis and
-    /// two of these four flip.
+    /// The disc (`0x78b580`) and the pick (`0x78bdd0`) are inverses: left is red, right cyan, top
+    /// violet, bottom chartreuse, and a sign error flips two of the four.
     #[test]
     fn a_click_on_the_wheel_picks_the_hue_under_the_cursor() {
         let mut s = picker();
@@ -763,8 +656,7 @@ mod tests {
         }
     }
 
-    /// The centre is saturation 0 — white — and it stays white however the hue would have come out,
-    /// because the `-1` grey sentinel is inert on the way back through `hsv_to_rgb`.
+    /// White whatever the hue, as the `-1` grey sentinel is inert in `hsv_to_rgb`.
     #[test]
     fn the_wheels_centre_is_unsaturated() {
         let mut s = picker();
@@ -777,17 +669,15 @@ mod tests {
         );
     }
 
-    /// **The press IS the first move of the gesture**, and the drag keeps writing the wheel even
-    /// after the cursor leaves it — the capture is a flag on the widget, not a hit test per move
-    /// (`0x78bd80` is gated on `+0x314`, never re-tested). Dragging from red round to cyan without
-    /// lifting proves both.
+    /// The press is the first move, and the capture is a flag, not a hit test per move (`0x78bd80`
+    /// is gated on `+0x314`); dragging from red to cyan without lifting proves both.
     #[test]
     fn a_wheel_drag_keeps_the_capture_when_the_cursor_wanders_off() {
         let mut s = picker();
         let (l, b, w, h) = wheel_rect(&mut s);
         let cy = b + h * 0.5;
         s.mouse_button(l + 1.0, cy, "LeftButton", true);
-        // Straight across and well past the right rim — outside the wheel's rect entirely.
+        // Well past the right rim, outside the wheel's rect.
         s.mouse_move(l + w + 200.0, cy);
         let (r, g, bl): (f64, f64, f64) = s.eval("return TestPicker:GetColorRGB()").unwrap();
         assert!(
@@ -806,8 +696,6 @@ mod tests {
         );
     }
 
-    /// The strip writes **only** brightness: dragging it down to black and back up leaves the hue
-    /// exactly where the wheel put it.
     #[test]
     fn a_strip_drag_writes_brightness_and_leaves_the_hue_alone() {
         let mut s = picker();
@@ -830,7 +718,7 @@ mod tests {
         s.mouse_move(sx, sb - 50.0); // dragged below the strip: clamps to black
         let black: (f64, f64, f64) = s.eval("return TestPicker:GetColorRGB()").unwrap();
         assert_eq!(black, (0.0, 0.0, 0.0), "V clamps at 0");
-        // (Black is exact whatever the hue: `hsv_to_rgb` scales every channel by V.)
+        // Black is exact whatever the hue: `hsv_to_rgb` scales every channel by V.
         s.mouse_move(sx, sb + sh + 50.0); // and above it: clamps to full
         let full: (f64, f64, f64) = s.eval("return TestPicker:GetColorRGB()").unwrap();
         assert!(
@@ -841,9 +729,7 @@ mod tests {
         let _ = (w, l);
     }
 
-    /// `OnColorSelect` fires on **every** step of a drag, including one that lands on the colour
-    /// the widget already holds — the widget has no change-gate (`0x78bafd` tests only whether a
-    /// handler is bound), which is the opposite of the Slider next door.
+    /// Even a step onto the colour already held fires (`0x78bafd`).
     #[test]
     fn the_drag_fires_on_every_move_with_no_change_gate() {
         let mut s = picker();
@@ -855,33 +741,24 @@ mod tests {
         let after_press: i64 = s.eval("return fires").unwrap();
         assert_eq!(after_press, 1, "the press itself fires once");
         for _ in 0..3 {
-            s.mouse_move(cx, cy); // the SAME point — no change, still fires
+            s.mouse_move(cx, cy); // the same point: no change, still fires
         }
         let after_moves: i64 = s.eval("return fires").unwrap();
         assert_eq!(after_moves, 4, "no change-gate: every captured move fires");
     }
 
-    /// A press that lands on neither the wheel nor the strip captures nothing — the surrounding
-    /// window is not a giant colour surface.
     #[test]
     fn a_press_outside_both_rects_captures_nothing() {
         let mut s = picker();
         let before: (f64, f64, f64) = s.eval("return TestPicker:GetColorRGB()").unwrap();
         s.mouse_button(340.0, 20.0, "LeftButton", true); // inside the frame, below both
-        s.mouse_move(20.0, 150.0); // ... and now over the wheel, uncaptured
+        s.mouse_move(20.0, 150.0); // then over the wheel, uncaptured
         let after: (f64, f64, f64) = s.eval("return TestPicker:GetColorRGB()").unwrap();
         assert_eq!(after, before, "no capture, no colour change");
     }
 
-    /// The two markers sit where the colour came from. Checked through **extract**, not `GetLeft`:
-    /// the markers carry no anchors — the client `ClearAllPoints`es them and re-`SetPoint`s from
-    /// C++, and benilla derives their rects at extract for the same reason — so the layout resolver
-    /// has nothing to answer with. That is the same shape as the Slider thumb's, and it is the one
-    /// place a corpus addon could tell the difference; nothing in the 218 reads a picker marker's
-    /// rect.
-    ///
-    /// The wheel marker is checked by round trip — click a point, the marker's centre lands back on
-    /// it — which is the invariant that matters and the one either `fchs` breaks.
+    /// Checked through extract: the client places the markers from C++ with no anchors, so the
+    /// resolver has nothing to answer. A click lands the wheel marker's centre on the point.
     #[test]
     fn the_markers_land_where_the_colour_came_from() {
         let mut s = picker();
@@ -900,8 +777,8 @@ mod tests {
                 cy + dy
             );
         }
-        // The value marker rides V from the strip's bottom — and scales by the WHEEL's height,
-        // which is the client's own unguarded `[this+0x318]` read. Both are 128 here.
+        // The value marker rides V from the strip's bottom, scaled by the wheel's height (the
+        // reference's `[this+0x318]` read); both are 128 here.
         let (sb, sh): (f32, f32) = s
             .eval(
                 "local r = TestPicker:GetColorValueTexture(); return r:GetBottom(), r:GetHeight()",
@@ -921,9 +798,8 @@ mod tests {
         }
     }
 
-    /// The extracted rect of the marker whose authored width is `width` — the two markers share
-    /// one BLP and are told apart by their size (10 for the wheel's, 48 for the strip's), which is
-    /// also the assertion that they kept it.
+    /// The extracted rect of the marker `width` wide: the two share one BLP and differ by size, 10
+    /// for the wheel's and 48 for the strip's.
     fn marker_rect(s: &UiScript, width: f32) -> Option<crate::layout::Rect> {
         s.extract().into_iter().find_map(|q| {
             let r = q.rect?;
diff --git a/crates/benilla-ui/src/script/container.rs b/crates/benilla-ui/src/script/container.rs
index 04a8ac51..e0d457d4 100644
--- a/crates/benilla-ui/src/script/container.rs
+++ b/crates/benilla-ui/src/script/container.rs
@@ -1,52 +1,27 @@
-//! The container bindings (decision 0068 T2) — the 1.12 bag verbs, every one of them a plain
-//! top-level global (decision 1198; measured on the corpus: `GetContainerItemLink`,
-//! `GetContainerNumSlots` and `GetContainerItemInfo` are the three most-wanted engine verbs of
-//! all, and Bagnon's data engine is built on exactly these). Same two-way seam as
-//! [`super::action`]: the app pushes a **container snapshot** per bag id
-//! ([`UiScript::set_container`] — slots already resolved to icon/count/quality by the app's
-//! item stores; the engine holds no item knowledge), and `UseContainerItem` queues an outbound
-//! **intent** the app drains into the wire ([`UiScript::take_container_uses`]).
-//!
-//! Bag ids are the live API's space: `0` the backpack, `1..4` the equipped bags (bank later).
-//! Slots are 1-based. One deliberate divergence from the 1.14 documentation:
-//! `containerInfo.iconFileID` carries our icon **texture path** (`Interface\Icons\…`), not a
-//! numeric FileDataID — 5875 has no FileDataIDs, and every measured consumer feeds the value
-//! straight to `SetTexture`, which takes both shapes in the live client.
+//! The 1.12 bag verbs, all bare globals. The app pushes each bag's resolved snapshot and drains
+//! the intents the verbs queue; the engine holds no item knowledge. Bag ids are the 1.12 client's
+//! (0 the backpack, 1-4 the worn bags, -1 the bank's own slots, 5-10 the bank bags, -2 the
+//! keyring); slots are 1-based.
 
 use mlua::{Lua, Table, Value};
 
 use super::cursor::{self, CursorItem, CursorPayload};
 use super::Model;
 
-/// The charter/petition lines an item tooltip prints under its name — the item tooltip's own
-/// emission order, line 3 (`0x854d7c..0x854dd0`): *"(petition/guild-charter items) Title /
-/// Creator / Num-signatures (white; title wraps) — a resolved petition object; keys
-/// `PETITION_*`/`GUILD_CHARTER_*`"*.
-///
-/// The two key families are picked by [`Self::is_charter`], the same record bit that picks
-/// `GetPetitionInfo`'s first return — so a charter reads *"Guild Name:"* / *"Guild Master:"* and a
-/// plain petition reads *"Petition:"* / *"Created by"*.
-///
-/// **The third line, the signature count, is deliberately NOT here.** The law names it, but neither
-/// the reference nor the packet says where the number comes from: the petition record carries no
-/// count, and the only candidate — the item's `ITEM_FIELD_ENCHANTMENT` slot-0 *charges* dword,
-/// which vmangos's own source documents as "the on-item signature count" — has its write
-/// **commented out** server-side, so it is always zero and the guess could never be falsified here.
-/// Omitted rather than invented; the line is one field away the day someone pins the source.
+/// The petition lines an item tooltip prints under the name (`0x854d7c..0x854dd0`): the title and
+/// the creator, keyed `GUILD_CHARTER_*` for a charter, else `PETITION_*`. The signature-count line
+/// is not built: its source is untraced, and vmangos's write of the on-item count is commented out.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct PetitionSlotView {
-    /// The record's charter bit: `true` picks the `GUILD_CHARTER_*` keys, `false` the `PETITION_*`
-    /// ones.
+    /// The record's charter bit, also `GetPetitionInfo`'s first return.
     pub is_charter: bool,
     /// The proposed guild's (or petition's) name.
     pub title: String,
-    /// The owner's name, app-resolved through the name cache. `None` while that query is in
-    /// flight — the line is withheld, as the creator line is, rather than printed with a hole.
+    /// The owner's name from the name cache; `None`, and no line, while the query is in flight.
     pub owner: Option<String>,
 }
 
-/// One occupied bag slot, resolved by the app (icon from ItemDisplayInfo, count/quality from the
-/// item object + template). Plain data.
+/// One occupied bag slot, resolved by the app from the item object and its template.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct ContainerSlot {
     /// Icon texture path (`Interface\Icons\…`); `None` while the template answer is in flight.
@@ -54,109 +29,65 @@ pub struct ContainerSlot {
     pub count: u32,
     /// Item quality 0..6; `None` while unresolved (the API reports `nil`).
     pub quality: Option<u32>,
-    /// The item's template entry (`containerInfo.itemID`); 0 while unresolved.
+    /// The item's template entry; 0 while unresolved.
     pub item_id: u32,
-    /// An `|Hitem:…|h[Name]|h` link once the name is known; Bagnon's search reads it.
+    /// An `|Hitem:…|h[Name]|h` link once the name is known.
     pub link: Option<String>,
     pub locked: bool,
-    /// The 1-based live-API inventory slot ids this item could be EQUIPPED into (empty = not
-    /// equippable) — the app-resolved "fit rule" decision 0208 phase 1b's cursor arc needs
-    /// (`cursor::CursorItem::equip_slots` captures it at pickup). Derived from the item
-    /// template's `inventoryType` via `ui_items::find_equip_slot`; the engine holds no item
-    /// knowledge of its own.
+    /// The 1-based inventory slots the item equips into, from `inventoryType`; empty if none.
     pub equip_slots: Vec<u8>,
-    /// Whether this item may be placed on an ACTION-BAR slot — app-resolved from the template
-    /// exactly like [`Self::equip_slots`] (the engine holds no item knowledge of its own).
-    /// `PlaceAction`'s only item filter, byte-read: an on-use spell OR equippable
-    /// (`ItemInfo::placeable_on_action_bar`, `PlaceAction 0x4e62e0` — decision 0666).
+    /// Whether the item may go on an action bar: `PlaceAction`'s only item filter (`0x4e62e0`), an
+    /// on-use spell or equippable.
     pub bar_placeable: bool,
-    /// The instance's live durability `(current, max)` — `ITEM_FIELD_DURABILITY`/`MAXDURABILITY`
-    /// off the streamed item object; `None` for indestructible items (max 0) or while the create
-    /// hasn't landed. The real-instance tooltip's "Durability X / Y" line reads it (a template
-    /// hover keeps the template's full max/max).
+    /// Current and max durability; `None` when the max is 0 or the item object has not arrived.
     pub durability: Option<(u32, u32)>,
-    /// The item's running use-cooldown as `(start_ms on the GetTime clock, duration_ms,
-    /// enabled)` — the same app-computed triple [`super::ActionState::cooldown`] carries;
-    /// `None` = cold. Stored at push ([`super::UiScript::set_container`]) so
-    /// `GetContainerItemCooldown` answers the reference's `(start, duration, enable)`.
+    /// The use cooldown, `(start_ms on the GetTime clock, duration_ms, enabled)`; `None` if cold.
     pub cooldown: Option<(i64, u32, bool)>,
-    /// Right-clicking reads this item (an instance carrying `ITEM_FIELD_ITEM_TEXT_ID` — a mail
-    /// permanent copy). `GetContainerItemInfo`'s `isReadable`; the bag hover shows the Inspect
-    /// magnifier off it (ref ContainerFrame.lua l.638 `this.readable → ShowInspectCursor()`),
-    /// and the tooltip's WRITTEN_BY/READABLE gates key on it.
+    /// The instance carries `ITEM_FIELD_ITEM_TEXT_ID` (a mail copy): `GetContainerItemInfo`'s
+    /// `readable`, which shows the Inspect cursor (`ContainerFrame.lua:638`).
     pub readable: bool,
-    /// The RESOLVED `ITEM_FIELD_CREATOR` name (app: ask-once name cache) — the tooltip's
-    /// "Written by %s" (a letter) / "<Made by %s>" (anything crafted) line. `None` = authorless
-    /// or the name query is in flight (no line; the re-push repaints the hover when it lands).
+    /// The `ITEM_FIELD_CREATOR` name for the "Written by" or "<Made by>" line, once resolved.
     pub creator: Option<String>,
-    /// The instance's `ITEM_FIELD_FLAGS` — the tooltip's openable lock sub-gate reads
-    /// UNLOCKED `0x4`, the wrapped-gift arm WRAPPED `0x8` (see
-    /// [`super::char_stats::InvSlotView::flags`], the doll twin).
+    /// `ITEM_FIELD_FLAGS`; the tooltip reads UNLOCKED `0x4` and WRAPPED `0x8`.
     pub flags: u32,
-    /// `0x5da2c0` — **the instance is runtime-bound**: `ITEM_FIELD_FLAGS & 1` (soulbound), or a
-    /// live enchant slot naming a `SpellItemEnchantment` row that binds. App-resolved off the raw
-    /// descriptor ([`crate::items::already_bound`] in benilla-app — the same predicate the enchant
-    /// cursor's bind question asks), because the binding half needs a DBC join and the engine
-    /// holds no item knowledge of its own. The tooltip's bind line overrides to **Soulbound**
-    /// on it (B310); `false` on any source with no streamed item object.
+    /// Bound at runtime (`0x5da2c0`): `ITEM_FIELD_FLAGS & 1`, or an enchant whose
+    /// `SpellItemEnchantment` row binds. The tooltip's bind line then says Soulbound.
     pub already_bound: bool,
-    /// The instance's enchant slots, resolved by the app ([`super::EnchantView`]) and in
-    /// enchant-slot order: it joins the id through `SpellItemEnchantment.dbc`'s name column and
-    /// hands over the row's name plus the three facts the line law needs to place and paint it.
-    /// Empty = unenchanted, or the enchant DBC never loaded. Decisions 0915/0920.
+    /// The enchant slots in slot order, named from `SpellItemEnchantment.dbc`; empty when none.
     pub enchants: Vec<super::EnchantView>,
-    /// **The instance's remaining LIFETIME in milliseconds** — a duration-limited item counting
-    /// down to its own destruction (a conjured stone, a holiday gift, a timed quest item). Its
-    /// only feed is `SMSG_ITEM_TIME_UPDATE`, parked as an absolute deadline and recomputed on
-    /// read ([`crate::items::Countdowns::lifetime_remaining_display_ms`] in benilla-app), floored to
-    /// the whole second so the snapshot moves once a second rather than every frame.
-    /// `None` = no timer, which is nearly every item. Decision 1933.
+    /// A timed item's lifetime left in ms (`SMSG_ITEM_TIME_UPDATE`), floored to the second.
     pub duration_ms: Option<u64>,
-    /// The petition this item names, when it is a signable charter — **line 3 of the tooltip's
-    /// emission law**, between the NAME and the green `ITEM_SIGNABLE` line.
-    ///
-    /// `None` for every ordinary item, and also for a charter whose petition record has not
-    /// arrived: the hover is what ISSUES that query, so the first hover of an unopened charter
-    /// shows the name and the green line, and the two guild lines appear on the repaint. Exactly
-    /// [`Self::creator`]'s shape one field up, for exactly its reason.
+    /// A signable charter's petition, printed between the name and the green `ITEM_SIGNABLE`
+    /// line; `None` until the record the hover queries arrives.
     pub petition: Option<PetitionSlotView>,
 }
 
-/// One enchant slot as the tooltip renders it (`0x52c9f9`–`0x52ca23`; decision 0920). The app
-/// resolves the DBC row; every rule below is the engine's.
+/// One enchant slot as the tooltip renders it (`0x52c9f9`..`0x52ca23`); the app resolves the row.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct EnchantView {
-    /// `ITEM_FIELD_ENCHANTMENT` slot: **0** permanent · **1** temporary · **2..6** the
-    /// random-property suffix. It decides the colour band — only 0 and 1 are ever coloured.
+    /// `ITEM_FIELD_ENCHANTMENT` slot: 0 permanent, 1 temporary, 2-6 the random suffix; only 0 and
+    /// 1 are coloured.
     pub slot: u8,
-    /// The enchant id was NEGATIVE. `abs(id)` names the row either way — the sign's only effect is
-    /// to paint slots 0/1 pure-red instead of green (`0x52ca29–0x52ca49`).
+    /// The id was negative: `abs(id)` names the row, and slots 0 and 1 paint red, not green
+    /// (`0x52ca29`..`0x52ca49`).
     pub negative: bool,
-    /// The `SpellItemEnchantment` row's name, verbatim (`"Agility +15"`, `"Crusader"`) — the
-    /// reference copies the string with no format at all (`0x52ca8b–0x52caa1`).
+    /// The `SpellItemEnchantment` row's name, copied unformatted (`0x52ca8b`..`0x52caa1`).
     pub name: String,
-    /// The slot's `ITEM_FIELD_ENCHANTMENT` charges dword — nonzero appends " (N Charges)".
+    /// The slot's charges; nonzero appends " (N Charges)".
     pub charges: u32,
-    /// Milliseconds left on a TEMPORARY enchant, from `SMSG_ITEM_ENCHANT_TIME_UPDATE` (the item's
-    /// own duration field is never read for this). `Some` replaces the plain name with the
-    /// countdown phrasing; `None` = no timer, or expired.
+    /// Ms left on a temporary enchant, from `SMSG_ITEM_ENCHANT_TIME_UPDATE`, never the item's own
+    /// duration field; `Some` prints the countdown form.
     pub remaining_ms: Option<u64>,
 }
 
-/// One `ItemRandomProperties` row as the engine renders it — the **random-suffix roll** a dropped,
-/// linked, auctioned or mailed item carries (decision 1547). The app resolves the DBC (both of
-/// them: the roll's table and the `SpellItemEnchantment` names its five ids land on) and pushes the
-/// whole table once at load; a tooltip source supplies only the id, exactly as in the reference.
+/// One `ItemRandomProperties` row, an item's random-suffix roll. The app pushes the whole table at
+/// load, and a tooltip source supplies only the id, as in the reference.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct RandomPropertyView {
-    /// The roll's suffix — `"of the Monkey"`. The reference joins it onto the item name through
-    /// `ITEM_SUFFIX_TEMPLATE` (`"%s %s"`) in its one name formatter `0x5d8b00`; benilla does that
-    /// join app-side, where every display name is composed, so this is carried for reference and
-    /// for the surfaces that name an item the app never composed.
+    /// The suffix (`"of the Monkey"`), joined on by `ITEM_SUFFIX_TEMPLATE` (`0x5d8b00`), for the
+    /// names the app does not compose itself.
     pub suffix: String,
-    /// The enchant lines the roll grants, already named and seated in enchant slots **2..6** —
-    /// the five dwords the builder copies out of the suffix row (`0x52b7e0–0x52b7fb`). Slots 2..6
-    /// are always white, whatever the sign.
+    /// The roll's five enchants, named, in slots 2-6 (`0x52b7e0`..`0x52b7fb`); always white.
     pub enchants: Vec<EnchantView>,
 }
 
@@ -169,11 +100,9 @@ pub struct ContainerState {
     pub slots: std::collections::HashMap<u32, ContainerSlot>,
 }
 
-/// One queued backpack pick/place/swap/split: move the item from `(src_bag, src_slot)` to
-/// `(dst_bag, dst_slot)` (live-API space, 1-based slots). The app maps a backpack-internal move
-/// (both bags 0) onto `CMSG_SWAP_INV_ITEM` player-array slots. `count`: `None` = a whole-stack
-/// move/swap (including a same-item merge — the wire tops the stack up itself); `Some(n)` = a
-/// split placement (`SplitContainerItem`) the app maps onto `CMSG_SPLIT_ITEM` instead.
+/// One queued move from `(src_bag, src_slot)` to `(dst_bag, dst_slot)`. `count` is `None` for a
+/// whole stack (a move, a swap, or a merge the server tops up), `Some(n)` for a split placement
+/// (`CMSG_SPLIT_ITEM`).
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct ContainerMove {
     pub src_bag: i64,
@@ -183,20 +112,15 @@ pub struct ContainerMove {
     pub count: Option<u32>,
 }
 
-/// One queued **auto-store into a bag** — `PutItemInBag`'s third leg and the whole of
-/// `PutItemInBackpack` (`crate::script::cursor::bag_verbs`): take the item at `(src_bag, src_slot)`
-/// and put it anywhere inside container `dst_bag`.
-///
-/// **There is no destination slot, and that is the finding, not an omission**: the reference's
-/// `CMSG_AUTOSTORE_BAG_ITEM 0x10B` carries `(srcbag, srcslot, dstbag)` and nothing else, and its
-/// split sibling `CMSG_SPLIT_ITEM 0x10E` carries the literal `0xFF` where a slot would go. The
-/// server picks. `count`: `None` = the whole stack (AUTOSTORE); `Some(n)` = a split carry, which
-/// the drain sends as SPLIT instead — the same fork the reference makes on `[0xb4b40c]`.
+/// One queued auto-store (`PutItemInBag`, `PutItemInBackpack`): the item at `(src_bag, src_slot)`
+/// into container `dst_bag`, with no slot: `CMSG_AUTOSTORE_BAG_ITEM` (0x10B) carries none and
+/// `CMSG_SPLIT_ITEM` (0x10E) sends `0xFF`, so the server picks. `Some(n)` in `count` is a split,
+/// the fork the reference makes on `[0xb4b40c]`.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct BagAutoStore {
     pub src_bag: i64,
     pub src_slot: u32,
-    /// Live-API container id (0 = backpack, 1..=4 an equipped bag, 5..=10 a bank bag).
+    /// The container id: 0 the backpack, 1-4 a worn bag, 5-10 a bank bag.
     pub dst_bag: i64,
     pub count: Option<u32>,
 }
@@ -207,11 +131,8 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().bag_autostores)
     }
 
-    /// Push (or remove, with `None`) one bag's snapshot, keyed by live-API bag id (0 = backpack).
-    /// Each slot's cooldown arrives with its absolute start already on the `GetTime` clock (ms) —
-    /// storing is a pure unit conversion, the same seam shape as
-    /// [`super::UiScript::set_action_state`] — so `GetContainerItemCooldown` answers absolute
-    /// `(start, duration, enable)` without drift.
+    /// Push one bag's snapshot, or remove it with `None`; cooldowns arrive in ms on the `GetTime`
+    /// clock and are stored in seconds.
     pub fn set_container(&mut self, bag: i64, state: Option<ContainerState>) {
         let mut model = self.model_mut();
         model.container_cooldowns.retain(|&(b, _), _| b != bag);
@@ -236,8 +157,7 @@ impl super::UiScript {
         }
     }
 
-    /// Push the app's answer to `HasKey()` — whether the player owns any `BagFamily` KEYS item
-    /// anywhere the reference's own search reaches. The keyring UI's one gate (decision 0765).
+    /// Push `HasKey()`'s answer: whether the player owns a `BagFamily` key item anywhere.
     pub fn set_has_key(&mut self, has_key: bool) {
         self.model_mut().has_key = has_key;
     }
@@ -252,31 +172,25 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().container_moves)
     }
 
-    /// Drain the `(bag, slot)` sources `AutoEquipCursorItem` queued (decision 0208 phase 1b) —
-    /// the app resolves each to wire bag/slot and sends `CMSG_AUTOEQUIP_ITEM`.
+    /// Drain the `(bag, slot)` sources `AutoEquipCursorItem` queued, for `CMSG_AUTOEQUIP_ITEM`.
     pub fn take_container_autoequips(&mut self) -> Vec<(i64, u32)> {
         std::mem::take(&mut self.model_mut().container_autoequips)
     }
 
-    /// Drain the `(bag, slot)` repair clicks the repair-mode pickup intercept queued — the app
-    /// resolves each to its item guid and sends `CMSG_REPAIR_ITEM`.
+    /// Drain the `(bag, slot)` clicks repair mode queued, for `CMSG_REPAIR_ITEM`.
     pub fn take_container_repairs(&mut self) -> Vec<(i64, u32)> {
         std::mem::take(&mut self.model_mut().container_repairs)
     }
 
-    /// Drain the `(bag, slot, count)` destroys `DeleteCursorItem` queued (`count == 0` = the
-    /// whole stack) — the app resolves each to its item guid and sends `CMSG_DESTROYITEM`.
+    /// Drain the `(bag, slot, count)` destroys `DeleteCursorItem` queued, a 0 count being the whole
+    /// stack, for `CMSG_DESTROYITEM`.
     pub fn take_container_destroys(&mut self) -> Vec<(i64, u32, u32)> {
         std::mem::take(&mut self.model_mut().container_destroys)
     }
 
-    /// **Arm the gift-wrap cursor** on the paper at `(bag, slot)` — the app's call when a
-    /// right-click takes the reference's begin-wrap arm (`ItemInfo::begins_gift_wrap`).
-    ///
-    /// Three acts, exactly the three `0x5edea0` performs: the paper's slot reads **locked**, the
-    /// displayed cursor becomes **mode 2** (`Interface\Cursor\Cast.blp` — the same art the cast
-    /// cursor uses, table `0x853b88` slot 2), and **nothing goes on the wire**. What completes it
-    /// is the next left-click on a container slot. Decision 1934.
+    /// Arm a gift wrap with the paper at `(bag, slot)`, as `0x5edea0` does: the paper locks, the
+    /// cursor takes mode 2 (the cast art, table `0x853b88`), and nothing is sent. The next
+    /// left-click on a container slot completes it.
     pub fn arm_gift_wrap(&mut self, bag: i64, slot: u32) {
         let mut model = self.model_mut();
         model.pending_wrap = Some(PendingWrap { bag, slot });
@@ -285,10 +199,9 @@ impl super::UiScript {
         cursor::queue_lock_changed(&mut model, bag, slot);
     }
 
-    /// **Cancel an armed gift wrap and nothing else** — disarm, unlock the paper, reset the
-    /// cursor. Deliberately narrower than `ClearCursor`, which also drops any held payload:
-    /// the reference records that a right-click "uses the item and cancels the wrap," not by
-    /// which of the two routes, so this touches only the half it names.
+    /// Disarm a gift wrap, unlocking the paper and resetting the cursor, but keeping any held
+    /// payload, which `ClearCursor` would drop. How the reference's right-click cancels a wrap is
+    /// untraced.
     pub fn cancel_gift_wrap(&mut self) -> Option<PendingWrap> {
         let mut model = self.model_mut();
         let wrap = model.pending_wrap.take()?;
@@ -298,33 +211,25 @@ impl super::UiScript {
         Some(wrap)
     }
 
-    /// Is a gift wrap armed, and on which slot? Read by the app to decide whether a right-click
-    /// is cancelling one.
+    /// The armed gift wrap, if any; the app reads it to tell whether a right-click cancels one.
     pub fn gift_wrap_armed(&self) -> Option<PendingWrap> {
         self.model_ref().pending_wrap
     }
 
-    /// Drain the `(giftBag, giftSlot, itemBag, itemSlot)` quads a completed wrap queued — the app
-    /// resolves each pair to the wire's bag/slot addressing and sends `CMSG_WRAP_ITEM`.
+    /// Drain the `(giftBag, giftSlot, itemBag, itemSlot)` wraps queued, for `CMSG_WRAP_ITEM`.
     pub fn take_container_wraps(&mut self) -> Vec<(i64, u32, i64, u32)> {
         std::mem::take(&mut self.model_mut().container_wraps)
     }
 
-    /// The mode the last FrameXML cursor call armed — `None` after a `ResetCursor`. This is the
-    /// *value* of the most recent write; whether a write happened at all is
-    /// [`Self::take_cursor_write`], and that is what the app acts on (decision 1061).
+    /// The mode the last FrameXML cursor call set, `None` after a `ResetCursor`; the app acts on
+    /// [`Self::take_cursor_write`] instead.
     pub fn ui_cursor(&self) -> Option<UiCursorMode> {
         self.model_ref().ui_cursor
     }
 
-    /// Drain the pending cursor write: `Some(mode)` = a `Show*Cursor` armed `mode`, `Some(None)` =
-    /// a `ResetCursor` asked for the base mode, `None` = **no FrameXML cursor call happened**, so
-    /// the sticky mode stands untouched.
-    ///
-    /// The three-state return is the point. A UI element with no cursor handler must leave the
-    /// cursor exactly as it was — that is how an armed spell keeps its cast cursor while the mouse
-    /// crosses a spellbook button, and reading a two-state latch instead is what made it snap to
-    /// Point (decision 1061).
+    /// Drain the pending cursor write: `Some(mode)` a set, `Some(None)` a reset, `None` no call,
+    /// which must leave the cursor as it was, so an armed spell keeps its cast cursor over a
+    /// spellbook button.
     #[allow(clippy::option_option)]
     pub fn take_cursor_write(&mut self) -> Option<Option<UiCursorMode>> {
         let mut model = self.model_mut();
@@ -332,72 +237,49 @@ impl super::UiScript {
     }
 }
 
-/// **The armed gift wrap** — which piece of wrapping paper the next container click will spend.
-///
-/// The reference holds this as globals beside the displayed-cursor mode rather than as a cursor
-/// *payload*; the distinction is load-bearing and is why this is its own type instead of a
-/// [`cursor::CursorPayload`] variant (see [`super::Model::pending_wrap`]).
+/// The armed gift wrap's paper. The reference keeps it beside the cursor mode, not as a cursor
+/// payload, so `CursorHasItem()` stays false while a wrap is armed.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub struct PendingWrap {
-    /// The paper's container id, in the same bag space every cursor verb speaks.
+    /// The paper's container id.
     pub bag: i64,
     /// The paper's 1-based slot within that container.
     pub slot: u32,
 }
 
-/// A **displayed-cursor override** the FrameXML cursor family arms: the
-/// single "displayed mode" (`0xbe2c2c`) the real client swaps to while a UI element wants a non-base
-/// cursor, restored to the base mode by `ResetCursor`. The app maps each to the matching
-/// `Interface\Cursor\*` art over the world classifier's Point.
+/// A displayed-cursor override from the FrameXML cursor verbs, the reference's one displayed mode
+/// (`0xbe2c2c`), until `ResetCursor`; the app maps each to its `Interface\Cursor` art.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum UiCursorMode {
-    /// Buy(3) — the coin/pouch: selling a bag item to a vendor (`ShowContainerSellCursor`, no
-    /// affordability gate), or a merchant/buyback item you can afford (`Show*SellCursor`).
+    /// Buy (3): selling a bag item, or a merchant or buyback item the player can afford.
     Buy,
-    /// UnableBuy(23) — the grayed coin: a merchant/buyback item you can't afford (`Show*SellCursor`,
-    /// player coin < price).
+    /// UnableBuy (23): a merchant or buyback item the player cannot afford.
     UnableBuy,
-    /// Inspect(7) — the magnifier the Ctrl-hover shows over an item (`ShowInspectCursor`).
+    /// Inspect (7): the magnifier, `ShowInspectCursor`.
     Inspect,
-    /// Point(1) — `SetCursor("POINT_CURSOR")`, and what a `ResetCursor` resolves to.
+    /// Point (1), `SetCursor("POINT_CURSOR")`.
     Point,
-    /// Cast(2) — `SetCursor("CAST_CURSOR")`: the lit cast cursor a unit frame shows while a spell
-    /// that CAN bind that unit is armed (`UnitFrame_OnEnter`).
+    /// Cast (2), `SetCursor("CAST_CURSOR")`: a unit frame the armed spell can target.
     Cast,
-    /// UnableCast(22) — `SetCursor("CAST_ERROR_CURSOR")`: the greyed twin, for a unit the armed
-    /// spell cannot bind, and for `UnitFrame_OnLeave` while still targeting.
+    /// UnableCast (22), `SetCursor("CAST_ERROR_CURSOR")`: a unit frame the armed spell cannot
+    /// target, and leaving one while still targeting.
     CastError,
 }
 
-/// The pick/place/swap gesture behind `PickupContainerItem` (decision 0216 §2, amended by 0218;
-/// unit-testable without Lua). Mirrors the real client's single entry point:
-/// - an empty cursor over a resolved, UNLOCKED slot picks it up (a locked slot refuses — the real
-///   client's refusal; today only the app's `locked` flag drives this, the engine's own
-///   pending-move lock lands with slice 2);
-/// - holding, a click on the SAME slot cancels (a split carry included);
-/// - holding the WHOLE stack (`count: None`), a click elsewhere queues the move and CLEARS —
-///   empty, same-item (the wire merges), and different-item (the wire swaps: the displaced item
-///   lands where the held one came from) all alike. The displaced item never hops onto the
-///   cursor: 0216 §2 shipped that exchange off 0091's gloss; the director's eye caught it and
-///   the bytes refuted it — no `SetCursorItem` on the place branch
-///   (`0x5e0c40`/`0x4f9b30`), `ClearCursor(0)`, one put-down sound (decision 0218). Bag
-///   placements are server-authoritative; only the ACTION bar
-///   hops its displaced payload (client-authoritative — the slice-4 note in 0218).
-/// - holding a SPLIT carry (`count: Some(n)`), a click onto an empty/unresolved/same-item
-///   destination queues the split move and clears; onto a DIFFERENT item it's a no-op (kept —
-///   you can't swap a partial stack).
-/// - a spell/action payload refuses a bag slot outright (no-op, kept).
+/// `PickupContainerItem`'s gesture (`0x4f9b30`):
+/// - an empty cursor picks up a resolved item whose slot is not locked;
+/// - a click on the held item's own slot cancels;
+/// - a whole stack placed anywhere else queues the move and clears the cursor; a swap lands the
+///   displaced item in the source slot, never on the cursor (no `SetCursorItem`, `0x5e0c40`);
+/// - a split carry places onto an empty or same-item slot, and stays held over another item;
+/// - a spell or action payload stays held.
 ///
-/// Returns whether the caller should repaint (the source-slot lock or the held payload changed).
+/// Returns whether the caller should repaint.
 fn pickup_container_item(model: &mut super::Model, bag: i64, slot: u32) -> bool {
-    // **The gift-wrap completion, ahead of the whole gesture** (decision 1934). `0x4f9b30` is the
-    // *only* entry to the wrap sender `0x5edfc0` image-wide — which is why the paper doll cannot
-    // finish a wrap and an equipped item is therefore unwrappable — and it takes this branch
-    // before it looks at the cursor at all.
+    // An armed gift wrap completes here, before the cursor is read. `PickupContainerItem` is the
+    // only caller of the wrap sender `0x5edfc0`, so an equipped item cannot be wrapped.
     if let Some(wrap) = model.pending_wrap {
-        // An empty or unresolved slot **bails and leaves the wrap armed** — the reference's own
-        // edge. Nothing is spent and the cursor keeps its mode, so the next click can still land
-        // on a real item.
+        // An empty or unresolved target leaves the wrap armed, as in the reference.
         if !model
             .containers
             .get(&bag)
@@ -406,10 +288,7 @@ fn pickup_container_item(model: &mut super::Model, bag: i64, slot: u32) -> bool
         {
             return false;
         }
-        // **The paper has to still be there.** `0x5edfef` bails when the stashed gift GUID no
-        // longer resolves, and — the edge worth transcribing — it then sends *and clears*
-        // nothing: the wrap stays armed and the paper's slot stays locked. So this returns
-        // without touching either.
+        // A vanished paper also bails, the wrap armed and the paper locked (`0x5edfef`).
         if !model
             .containers
             .get(&wrap.bag)
@@ -418,16 +297,12 @@ fn pickup_container_item(model: &mut super::Model, bag: i64, slot: u32) -> bool
         {
             return false;
         }
-        // No eligibility test of any kind. The wrap arm reads each item's `ITEM_FIELD_CONTAINED`
-        // and nothing else — not flags, not stack count, not bind state — and the client ships six
-        // `ERR_CANT_WRAP_*` strings for the server to answer with (`SMSG_INVENTORY_CHANGE_FAILURE`
-        // reasons 43-48). Same law as the openable click (decision 0896): gating locally would eat
-        // the click in silence and cost the player their error line.
+        // No eligibility test: the server refuses with an `ERR_CANT_WRAP_*` reason
+        // (`SMSG_INVENTORY_CHANGE_FAILURE` 43-48), and a local gate would eat that error line.
         model.pending_wrap = None;
         model.container_wraps.push((wrap.bag, wrap.slot, bag, slot));
-        // The paper unlocks and the cursor resets **immediately**, not on the server's answer:
-        // `0x5edfc0` calls `0x5eded0` at `0x5ee0aa`, right after the send. The target is never
-        // locked at all.
+        // The paper unlocks and the cursor resets right after the send (`0x5eded0` at
+        // `0x5ee0aa`), not on the answer; the target never locks.
         cursor::queue_lock_changed(model, wrap.bag, wrap.slot);
         model.ui_cursor = None;
         model.ui_cursor_dirty = true;
@@ -467,9 +342,7 @@ fn pickup_container_item(model: &mut super::Model, bag: i64, slot: u32) -> bool
             true
         }
         Some(CursorPayload::Item(held)) => {
-            // Cloned out from under `model.containers` so the moves below can borrow `model`
-            // mutably; a slot present but unresolved (item_id == 0, an in-flight template
-            // answer) reads as absent, same as a truly empty slot.
+            // Cloned so the moves below can borrow `model`; an unresolved slot reads as empty.
             let dest = model
                 .containers
                 .get(&bag)
@@ -477,16 +350,13 @@ fn pickup_container_item(model: &mut super::Model, bag: i64, slot: u32) -> bool
                 .cloned()
                 .filter(|d| d.item_id != 0);
             match (held.count, dest) {
-                // A split carry onto a DIFFERENT item can't swap a partial stack — no-op, kept.
+                // A split carry cannot swap with a different item: it stays held.
                 (Some(_), Some(d)) if d.item_id != held.item_id => {
                     model.cursor = Some(CursorPayload::Item(held));
                     false
                 }
-                // Every other placement queues its move and clears: empty and same-item take the
-                // carry's count through to the wire (a split placement or a merge the server
-                // tops up); a whole-stack place onto a different item is the plain SWAP — the
-                // displaced item lands where the held one came from, and the cursor empties
-                // (decision 0218, the director's eye over 0216 §2's hop).
+                // Anything else queues the move and clears: a split, a merge the server tops up,
+                // or a swap that lands the displaced item in the source slot.
                 (count, _) => {
                     queue_move(model, &held, bag, slot, count);
                     cursor::queue_cursor_update(model);
@@ -495,18 +365,10 @@ fn pickup_container_item(model: &mut super::Model, bag: i64, slot: u32) -> bool
                 }
             }
         }
-        // Mode 5 — **the buy**. A held vendor row dropped into a container slot is the whole
-        // point of the merchant cursor: `0x4f9efa` tests `[0xb4d900] == 5` right here and calls
-        // `0x5e1f30` = `CMSG_BUY_ITEM_IN_SLOT 0x1a3`, `{vendorGuid, itemEntry, bagGuid, bagSlot,
-        // count = 1}`. The cursor clears whether or not the server honours it.
-        //
-        // Deliberately NOT gated on the destination being empty. The reference does not look at
-        // the slot at all — the server decides, and answers `SMSG_BUY_FAILED` when it will not.
-        // What we DO refuse is a stale row: the reference's two container drop consumers
-        // dereference the vendor row without re-checking it against a list that may have been
-        // rewritten by a fresh `SMSG_LIST_INVENTORY`, which is a latent null deref there
-        // (`0x4f9f35`, `0x4c7ea5`). We treat a row that no longer resolves as a refusal — that is
-        // the third consumer `0x4c7300`'s own behaviour, and the one of the three that is right.
+        // Mode 5, a held vendor row, buys into this slot whatever it holds (`0x4f9efa` tests
+        // `[0xb4d900] == 5`): `CMSG_BUY_ITEM_IN_SLOT` (0x1a3) with count 1, and the cursor clears
+        // either way. Deviation: a row that no longer resolves is refused, as `0x4c7300` does,
+        // because this path dereferences it unchecked (`0x4f9f35`), a latent null deref.
         Some(CursorPayload::Merchant(held)) => {
             let entry = model
                 .merchant
@@ -525,10 +387,9 @@ fn pickup_container_item(model: &mut super::Model, bag: i64, slot: u32) -> bool
             | CursorPayload::Action(_)
             | CursorPayload::Macro(_)
             | CursorPayload::PetAction(_)
-            // Mode 10 (decision 1677) — a stabled pet refuses a bag/doll slot exactly as the
-            // spell/action family does, and stays on the cursor for the stable window to take.
+            // Mode 10, a stabled pet, stays held for the stable window.
             | CursorPayload::StablePet(_)
-            // Mode 2 (1962) — coins have no slot to land in; a money frame's DropFunc takes them.
+            // Mode 2, money, stays held for a money frame's DropFunc.
             | CursorPayload::Money(_)),
         ) => {
             model.cursor = Some(other);
@@ -537,7 +398,7 @@ fn pickup_container_item(model: &mut super::Model, bag: i64, slot: u32) -> bool
     }
 }
 
-/// Queue one pick/place/swap/split move (the shared tail of every clearing branch above).
+/// Queue one move, the shared tail of every clearing branch above.
 fn queue_move(
     model: &mut super::Model,
     held: &CursorItem,
@@ -554,35 +415,12 @@ fn queue_move(
     });
 }
 
-/// Register the container verbs — **top-level globals, because that is where 1.12 puts them**
-/// (decision 1198). Every name below is `function engine` in `reference/1.12-globals.tsv` as a
-/// bare global: `GetContainerNumSlots`, never `C_Container.GetContainerNumSlots`. The
-/// `C_Container` namespace 1187 reached for while chasing an Era addon is a *Dragonflight*
-/// reorganisation, and an addon that feature-detects it concludes it is on Dragonflight.
+/// Register the container verbs as bare globals, as `reference/1.12-globals.tsv` lists them;
+/// `C_Container` is a later client's namespace, and an addon that finds it assumes that client.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
-    // ContainerIDToInventoryID(containerID) → the equipment slot the bag is worn in.
-    //
-    // **Two linear arms, one signed compare, and nothing else** (`0x4f94e0`, 124 bytes). Written
-    // as the reference's
-    // own three instructions — `t = id - 1`, `if t < 4` (SIGNED), then `+20` or `+60` — rather
-    // than as the two closed forms `id+19` / `id+59`, because the wrap at the `i32` edge is then
-    // reproduced rather than approximated.
-    //
-    // | containerID | slot |
-    // |---|---|
-    // | **−2 (keyring)** | **17** |
-    // | −1 | 18 |
-    // | **0 (backpack)** | **19** |
-    // | 1 · 2 · 3 · 4 | 20 · 21 · 22 · 23 |
-    // | **5** (first bank bag) | **64** |
-    // | 6 … 10 | 65 … 69 |
-    //
-    // **There is no special case for 0 or for −2** — the "backpack is 0, keyring is −2"
-    // convention is the *caller's*, and this arithmetic merely happens to land on 19 and 17.
-    // **And there is no range check of any kind**: the only guard in the function is the up-front
-    // type test, so an out-of-range id is not clamped, not rejected, and never nil — it returns
-    // `id+19` or `id+59` as an ordinary number, and whatever the receiving binding does with an
-    // invalid slot is that binding's business.
+    // ContainerIDToInventoryID(containerID) (`0x4f94e0`): `id - 1`, then +20 below 4 else +60, so
+    // the keyring -2 → 17, the backpack 0 → 19, bags 1-4 → 20-23 and bank bags 5-10 → 64-69, with
+    // no special case and no range check.
     lua.globals().set(
         "ContainerIDToInventoryID",
         lua.create_function(|lua, id: Value| {
@@ -591,8 +429,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 id,
                 "Usage: ContainerIDToInventoryID(containerID)",
             )?;
-            // `0x4f951b dec eax` · `0x4f951f cmp eax,4` · `0x4f9524 jl` — the compare is signed
-            // and lands on the `id <= 4` arm.
+            // The reference's steps and signed compare (`0x4f9524 jl`), wrapping at the `i32` edge.
             let t = id.wrapping_sub(1);
             Ok(i64::from(if t < 4 {
                 t.wrapping_add(20)
@@ -602,45 +439,20 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetBagPortaitTexture(texture, containerID) — `0x4fa4f0` (374 B), the reference's own
-    // spelling, typo included, and CARVED. The bag window's portrait:
-    // `ContainerFrame_GenerateFrame` sets it for every container except the keyring, which takes
-    // `SetPortraitToTexture` with a fixed path one line above (ContainerFrame.lua l.418-423).
-    // benilla runs that file off the player's chain (1751), so this is a live call site.
-    //
-    // Three arms, and the FIRST is the one nobody would have guessed:
-    //
-    // 1 · **`id == 0` does nothing at all.** `0x4fa5b8 dec edi` / `0x4fa5b9 js 0x4fa65d` returns
-    //     before the clear at `0x4fa5c8` — no texture is set and none is cleared. It is not an
-    //     oversight: `ContainerFrame.xml:67` gives `$parentPortrait` no `file=`, and the backpack
-    //     takes a different ARTWORK background (`UI-BackpackBackground`) that covers the portrait
-    //     slot outright. (`Button-Backpack-Up` is nowhere on this path — its only stock use is the
-    //     main bar's own button, MainMenuBarBagButtons.xml:79.)
-    // 2 · **`id` in 1..=10** clears the texture first, then sets
-    //     `Interface\Icons\<ItemDisplayInfo.InventoryIcon_1>` for the bag in that inventory slot
-    //     — `StringLookups.dbc` row 3 measured as `"Interface\Icons"`, `.TGA` stripped,
-    //     `INV_Misc_QuestionMark` on a display-info miss. Ids 5..10 are additionally gated on the
-    //     bank being open. **An empty slot leaves the texture CLEARED** — there is no fallback art.
-    // 3 · **`id >= 11` raises** `"Invalid slot in SetBagPortaitTexture"`.
-    //
-    // Our icon comes from the same place the item's own button icon does (`GetInventoryItemTexture`
-    // reads the item template's icon), so the DBC walk above is the reference's route to the value
-    // this client already has resolved; the observable — which icon lands on the portrait — is the
-    // same one.
+    // SetBagPortaitTexture(texture, containerID) (`0x4fa4f0`, the reference's spelling): 0 and
+    // below return before the clear (`0x4fa5b9`), 1-10 clear and then set the bag's icon, 11 and
+    // up raise. The reference also needs the bank open for 5-10, which is not checked here.
     lua.globals().set(
         "SetBagPortaitTexture",
         lua.create_function(|lua, (region, container): (Table, i64)| {
-            // Arm 3, before anything is touched.
             if container >= 11 {
                 return Err(mlua::Error::runtime("Invalid slot in SetBagPortaitTexture"));
             }
-            // Arm 1: the backpack is a silent return, not a clear.
             if container <= 0 {
                 return Ok(());
             }
-            // `ContainerIDToInventoryID`'s arithmetic, deliberately re-expressed rather than
-            // called: that binding is a Lua global an addon may replace, and the engine's own
-            // portrait read does not go through Lua.
+            // `ContainerIDToInventoryID`'s arithmetic, inlined: an addon may replace that global,
+            // and the reference's portrait read does not go through Lua.
             let t = container.wrapping_sub(1);
             let inv = if t < 4 {
                 t.wrapping_add(20)
@@ -657,8 +469,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             let rh = crate::script::region::region_handle_of(lua, &region)?;
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
             let data = model.region_data.entry(rh).or_default();
-            // Arm 2. `path` is `None` for an empty slot, and that IS the answer: the reference
-            // clears unconditionally and only then tries to set.
+            // An empty slot's `None` is the answer: the reference clears first, then sets.
             data.texture = path;
             data.circular = true;
             data.portrait_unit = None;
@@ -688,10 +499,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The reference's `GetContainerItemCooldown(bag, slot)` — the bag twin of
-    // `GetActionCooldown`, identical conventions: `GetTime`-clock `(start, duration, enable)`,
-    // enable 0 = an on-hold record (parked, full duration), and the cold-at-expiry guard so an
-    // event-driven re-feed can never replay the finish flash.
+    // GetContainerItemCooldown(bag, slot) (`0x4f99b0`) → start, duration, enable on the `GetTime`
+    // clock, as `GetActionCooldown`; enable 0 is a held cooldown. An expired one reads cold, so a
+    // re-feed cannot replay the finish flash.
     lua.globals().set(
         "GetContainerItemCooldown",
         lua.create_function(|lua, (bag, slot): (i64, u32)| {
@@ -724,31 +534,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetContainerItemInfo(bag, slot)` → **`texture, itemCount, locked, quality, readable`**
-    // — the 1.12 shape, five values (decision 1199).
-    //
-    // It used to return a single 1.14-shaped `containerInfo` TABLE, inherited from decision 1187's
-    // reach for the Classic Era surface. That was wrong in a way neither instrument could see:
-    // **36 corpus addons call this and every one of them uses the 1.12 shape. Not one uses the
-    // table.** 34 destructure (`local texture, itemCount = GetContainerItemInfo(bag, slot)`), and
-    // the four that assign a single name take the *first return* — `local texture = …`, or
-    // `GetContainerItemInfo(bag, i) ~= nil` as an occupancy test. All 36 were getting
-    // `texture = <table>` and, where they destructured, `itemCount = nil`. They load clean, so the
-    // harness scores them as passes, and they misbehave silently in play.
-    //
-    // (Decision 1199 §1 says "only one uses the table shape" — that came from a first reading of
-    // the call sites and a recount disproves it. The corrected number makes the case stronger, not
-    // weaker; the record is a point-in-time snapshot and this is where the true count lives.)
-    //
-    // The shipped 1.12 FrameXML settles the shape: `ContainerFrame.lua:241` reads exactly these
-    // five names in exactly this order.
-    //
-    // **A signature is part of the API.** Decision 1198 §3 made that argument about *names*; this
-    // is the same argument one level down, and it is the more dangerous half, because a wrong name
-    // fails loudly and a wrong shape does not.
-    //
-    // `nil` for an empty or unknown slot — the reference returns no values there, and a caller's
-    // `if texture then` reads the same either way.
+    // GetContainerItemInfo(bag, slot) (`0x4f9670`) → texture, itemCount, locked, quality,
+    // readable, the five `ContainerFrame.lua:241` reads; no values for an empty or unknown slot.
     lua.globals().set(
         "GetContainerItemInfo",
         lua.create_function(|lua, (bag, slot): (i64, u32)| {
@@ -758,9 +545,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     &model.cursor,
                     Some(CursorPayload::Item(c)) if c.bag == bag && c.slot == slot
                 ) ||
-                // An armed gift wrap locks its paper for as long as it stands (`0x4953e0` at
-                // `0x5edeb5`) — the same dimming a held item's source slot shows, and released by
-                // the send or by any cancel rather than by the server (decision 1934).
+                // An armed wrap's paper reads locked until the send or a cancel (`0x4953e0` at
+                // `0x5edeb5`).
                     matches!(
                         &model.pending_wrap,
                         Some(w) if w.bag == bag && w.slot == slot
@@ -783,9 +569,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     None => Value::Nil,
                 },
                 Value::Integer(i64::from(s.count)),
-                // The picked-up source slot reads locked (the real client dims it while the cursor
-                // carries the item) — derived from the cursor, not a mutated snapshot, so the
-                // app's per-frame re-push cannot wipe it.
+                // A held item's source slot reads locked, derived from the cursor so the app's
+                // re-push cannot wipe it.
                 Value::Boolean(s.locked || held_here),
                 match s.quality {
                     Some(q) => Value::Integer(i64::from(q)),
@@ -796,19 +581,13 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `BenillaGetContainerItemID(bag, slot)` — the item id behind a slot, for OUR OWN FrameXML.
-    //
-    // 1.12 has no such verb: an addon there takes the id out of `GetContainerItemLink`'s
-    // `|Hitem:12345:…` payload. Our tooltip and delete paths want the id directly, so it rides the
-    // `Benilla` host-bridge prefix — the sanctioned escape hatch for a verb only our own
-    // transcription calls, and the one `reference_surface` covers by prefix rather than by
-    // exception. An addon that wants it parses the link, exactly as it would on the real client.
+    // BenillaGetContainerItemID(bag, slot): the item id behind a slot. Not a 1.12 verb, where the
+    // id is parsed from `GetContainerItemLink`; the `Benilla` prefix keeps it off the 1.12 surface.
     lua.globals().set(
         "BenillaGetContainerItemID",
         lua.create_function(|lua, (bag, slot): (i64, u32)| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
-            // `nil` for an unresolved id, not `0` — a slot can carry an entry whose template has
-            // not landed yet, and `0` is a number a caller will happily index a table with.
+            // nil, not 0, while the template is in flight: a caller would index a table with 0.
             Ok(model
                 .containers
                 .get(&bag)
@@ -828,35 +607,21 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The left-click drag gesture: pick up from an occupied slot, or place/swap when holding.
-    // Returns whether the caller should repaint (the source-slot lock changed) — the OnClick calls
-    // the bag's `_Update` on true so the picked slot dims / un-dims immediately (no server round
-    // trip for the local cursor state).
+    // PickupContainerItem(bag, slot) (`0x4f9b30`): pick up, or place and swap. Its boolean return,
+    // whether to repaint, is not 1.12's, whose binding returns nothing.
     lua.globals().set(
         "PickupContainerItem",
         lua.create_function(|lua, (bag, slot): (i64, u32)| {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // Two intercepts live IN the pickup path, in the reference's own order (decision
-            // 0923 re-read `PickupContainerItem 0x4f9b30` whole; the targeting rung is at
-            // `4f9c54` and the repair test at `4f9c7b`, so targeting wins — a poisoning click at
-            // a repair vendor binds the poison, it does not repair):
-            //
-            //   4f9c54  call 0x6e48a0        ; IsTargeting
-            //   4f9c5d  call 0x6e6330        ; TargetingWantsItem (word & 0x4010)
-            //   4f9c6d  call 0x495d60        ; bind THIS item — then return, nothing picked up
-            //
-            // The held-payload check precedes BOTH (`4f9c38`: a non-empty cursor jumps to the
-            // place/swap arm long before either), so a click while carrying an item is a place —
-            // transcribed by the `cursor.is_none()` gate. The word is one-shot: the app clears it
-            // on completion, cancel, or close.
+            // The reference tests a held payload first (`0x4f9c38`), then an armed item-targeting
+            // spell, which takes the item (`0x4f9c54`, `0x495d60`), then repair mode (`0x4f9c7b`),
+            // so poisoning at a repair vendor binds the poison.
             if model.item_pick_armed && model.cursor.is_none() {
                 model.item_picks.push((bag, slot));
                 return Ok(false);
             }
-            // Repair mode (`0x4f9c7b`): while the repair cursor is
-            // armed, the click means "repair this item" — queued for the app to send — and
-            // nothing is picked up. The mode STICKS across clicks (only HideRepairCursor /
-            // merchant-close clears it).
+            // Repair mode, until `HideRepairCursor`, queues a repair and picks nothing up. Unlike
+            // the reference, it does not first check for a held item.
             if model.repair_mode {
                 model.container_repairs.push((bag, slot));
                 return Ok(false);
@@ -865,14 +630,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The cursor globals (`GetCursorInfo`/`CursorHasItem`/`CursorHasSpell`/`ClearCursor`/
-    // `SplitContainerItem`/`DeleteCursorItem`) live in [`super::cursor`], the one payload seam
-    // every surface routes through — top-level there for exactly the same reason.
-
-    // ShowContainerSellCursor(bag, slot) — arm the pouch cursor for a sellable hover (5875
-    // `0x4fa460`: Buy(3) only when the slot actually holds an item —
-    // an empty slot leaves the cursor unchanged; no Unable twin, no SellPrice check — selling
-    // never grays), and the reference's own `IsTargeting` bail at its first instruction.
+    // ShowContainerSellCursor(bag, slot) (`0x4fa460`): Buy (3) over an occupied slot, with no
+    // price check, so selling never greys; an empty slot leaves the cursor alone.
     lua.globals().set(
         "ShowContainerSellCursor",
         lua.create_function(|lua, (bag, slot): (i64, u32)| {
@@ -882,11 +641,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 .get(&bag)
                 .and_then(|c| c.slots.get(&slot))
                 .is_some();
-            // `IsTargeting` bails at the function's FIRST instruction (`0x4fa469`) — an armed spell
-            // suppresses the sell cursor outright. Now
-            // that the mode is sticky, this gate has to be here rather than app-side: a write of
-            // Buy would otherwise stamp over the cast cursor and there would be no per-frame world
-            // write to put it back.
+            // An armed spell suppresses it first (`0x4fa469`); the mode is sticky, so a Buy here
+            // would stamp out the cast cursor for good.
             if occupied && !model.spell_targeting {
                 model.ui_cursor = Some(UiCursorMode::Buy);
                 model.ui_cursor_dirty = true;
@@ -894,10 +650,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // ShowInspectCursor() — the Ctrl-hover magnifier (5875 `0x48ac60`: an unconditional
-    // `CursorSetMode(Inspect=7)`). Shared across surfaces (the merchant window's Ctrl-hover, a bag
-    // item's Ctrl-hover, the generic UIParent item hover), so it lives here beside `ResetCursor`
-    // rather than in any one seam. It takes no arguments and reads no state.
+    // ShowInspectCursor() (`0x48ac60`): Inspect (7), unconditionally.
     lua.globals().set(
         "ShowInspectCursor",
         lua.create_function(|lua, ()| {
@@ -907,11 +660,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // HasKey() — "does this player own a key at all?" (5875 `0x48ae90`), the gate the main bar
-    // reads to decide whether the keyring exists in the UI. The reference pushes the NUMBER 1 on a
-    // hit and nil otherwise, not a boolean, and FrameXML only ever tests it for truth — so the
-    // shape is reproduced exactly rather than normalized to a bool. The search itself (BagFamily
-    // == 9 across equipment/bags/backpack/bank/keyring) is the app's, like every other item fact.
+    // HasKey() (`0x48ae90`) → the number 1 if the player owns a key (`BagFamily` 9) anywhere, else
+    // nil, never a boolean; the app does the search.
     lua.globals().set(
         "HasKey",
         lua.create_function(|lua, ()| {
@@ -923,15 +673,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             })
         })?,
     )?;
-    // SetCursor(name) — the reference's `0x489490`: a name->mode table (POINT/CAST/BUY/ATTACK =
-    // 1..4, each with an `*_ERROR` twin at +20) into `CursorSetMode`, falling back to a custom
-    // bitmap for an unknown name. Only the modes FrameXML actually names are mapped here; anything
-    // else is ignored rather than guessed, and a **no-arg call is a `ResetCursor`**, which is the
-    // reference's own documented shape.
-    //
-    // Its one shipped caller is the unit-frame hover pair (`UnitFrame_OnEnter`/`OnLeave`), which is
-    // the ONLY lit/grey cursor split over a UI element in 1.12 — and it is authored in Lua, not in
-    // C++.
+    // SetCursor(name) (`0x489490`): POINT, CAST, BUY and ATTACK are modes 1-4, each `*_ERROR` 20
+    // higher, and no argument is a `ResetCursor`. The stock UI calls it only from the unit-frame
+    // hover (`UnitFrame.lua:50`).
     lua.globals().set(
         "SetCursor",
         lua.create_function(|lua, name: Option<String>| {
@@ -942,9 +686,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 Some("CAST_ERROR_CURSOR") => Some(UiCursorMode::CastError),
                 Some("BUY_CURSOR") => Some(UiCursorMode::Buy),
                 Some("BUY_ERROR_CURSOR") => Some(UiCursorMode::UnableBuy),
-                // An unmapped name: the reference would load a custom bitmap. We have no such art,
-                // and silently painting the wrong stock cursor would be worse than leaving the
-                // sticky mode alone, so this is a no-op rather than a guess.
+                // Ignored: the reference loads an unknown name as a custom cursor bitmap, which is
+                // not built.
                 Some(_) => return Ok(()),
             };
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -953,8 +696,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // ResetCursor — displayed mode back to the base (the world classifier's) mode (5875
-    // `0x48ac70` → `0x523d30`): clear the whole override, whichever `Show*Cursor` armed it.
+    // ResetCursor() (`0x48ac70` → `0x523d30`): back to the base mode, whatever set the override.
     lua.globals().set(
         "ResetCursor",
         lua.create_function(|lua, ()| {
@@ -998,7 +740,7 @@ mod tests {
         );
         // An in-flight slot: the create arrived, the template answer hasn't.
         slots.insert(3, ContainerSlot::default());
-        // A readable letter (a mail permanent copy — instance item-text): isReadable true.
+        // A readable letter, a mail copy with item text.
         slots.insert(
             4,
             ContainerSlot {
@@ -1015,16 +757,10 @@ mod tests {
         }
     }
 
-    /// **The gift-wrap state machine** (decision 1934), all four of its edges. Armed by the app's
-    /// right-click on a wrapper, the arm locks the paper and paints cursor mode 2 and sends
-    /// nothing; the next LEFT-click on a container slot spends it; an empty slot bails and leaves
-    /// it armed; and any `ClearCursor` cancels it.
     #[test]
     fn an_armed_gift_wrap_spends_on_the_next_container_click() {
         let mut s = UiScript::new().unwrap();
         s.set_container(0, Some(backpack()));
-        // The arm: nothing on the wire, the paper reads locked, the cursor is mode 2, and the
-        // held-item predicate stays FALSE — this is a cursor mode, not a payload.
         s.arm_gift_wrap(0, 1);
         assert_eq!(s.gift_wrap_armed(), Some(PendingWrap { bag: 0, slot: 1 }));
         assert!(s.take_container_wraps().is_empty(), "arming sends nothing");
@@ -1038,7 +774,7 @@ mod tests {
             !s.eval::<bool>("return CursorHasItem()").unwrap(),
             "the wrap writes no payload, so every stock CursorHasItem() gate stays shut"
         );
-        // A click on an EMPTY slot bails and leaves the wrap armed — the reference's own edge.
+        // A click on an empty slot leaves the wrap armed.
         s.eval::<()>("PickupContainerItem(0, 9)").unwrap();
         assert_eq!(s.gift_wrap_armed(), Some(PendingWrap { bag: 0, slot: 1 }));
         assert!(s.take_container_wraps().is_empty());
@@ -1057,9 +793,7 @@ mod tests {
         );
     }
 
-    /// Any `ClearCursor` cancels an armed wrap — the reference tests it FIRST inside
-    /// `ClearCursor 0x495190` and does so ungated by either parameter, so all 70 of its call
-    /// sites cancel (decision 1934).
+    /// `ClearCursor` (`0x495190`) tests for an armed wrap first, whatever its arguments.
     #[test]
     fn clear_cursor_cancels_an_armed_gift_wrap() {
         let mut s = UiScript::new().unwrap();
@@ -1074,7 +808,6 @@ mod tests {
                 .unwrap(),
             "the paper unlocks with the cancel — the lock never waited on a server"
         );
-        // …and the next container click is an ordinary pickup again.
         s.eval::<()>("PickupContainerItem(0, 1)").unwrap();
         assert!(s.take_container_wraps().is_empty());
         assert!(s.cursor_payload().is_some(), "a plain pickup, as before");
@@ -1083,7 +816,6 @@ mod tests {
     #[test]
     fn container_snapshot_reads() {
         let mut s = UiScript::new().unwrap();
-        // No bag pushed: capacity 0, info nil.
         assert_eq!(s.eval::<i64>("return GetContainerNumSlots(0)").unwrap(), 0);
         assert!(s
             .eval::<bool>("return GetContainerItemInfo(0, 1) == nil")
@@ -1095,8 +827,7 @@ mod tests {
             s.eval::<String>("return GetBagName(0)").unwrap(),
             "Backpack"
         );
-        // The 1.12 five-value shape (decision 1199): texture, itemCount, locked, quality,
-        // readable — the names `ContainerFrame.lua:241` destructures into, in its order.
+        // The five values `ContainerFrame.lua:241` reads, in its order.
         let (icon, count, quality) = s
             .eval::<(String, i64, i64)>(
                 "local texture, itemCount, locked, quality = GetContainerItemInfo(0, 1)\n\
@@ -1105,8 +836,6 @@ mod tests {
             .unwrap();
         assert_eq!(icon, "Interface\\Icons\\INV_Misc_Food_16");
         assert_eq!((count, quality), (5, 1));
-        // The item id is NOT one of the five — 1.12 has no verb for it, and an addon takes it out
-        // of the link. Ours rides the host-bridge prefix.
         assert_eq!(
             s.eval::<i64>("return BenillaGetContainerItemID(0, 1)")
                 .unwrap(),
@@ -1115,7 +844,7 @@ mod tests {
         assert!(s
             .eval::<bool>("return GetContainerItemLink(0, 1) ~= nil")
             .unwrap());
-        // isReadable mirrors the slot's readable bit (the letter in 4, not the jerky in 1).
+        // readable: the letter in 4, not the jerky in 1.
         assert!(!s
             .eval::<bool>("local _, _, _, _, readable = GetContainerItemInfo(0, 1) return readable")
             .unwrap());
@@ -1123,10 +852,7 @@ mod tests {
             .eval::<bool>("local _, _, _, _, readable = GetContainerItemInfo(0, 4) return readable")
             .unwrap());
 
-        // **The in-flight slot**: an entry exists but its template has not landed, so texture and
-        // quality are nil while itemCount is real. This is the state that made the five-value
-        // shape's occupancy test subtle (decision 1199) — the reference's own `if texture then`
-        // would read this as empty, which is why our own FrameXML tests `texture or itemCount`.
+        // An in-flight slot: texture and quality nil, itemCount real.
         assert!(s
             .eval::<bool>(
                 "local texture, itemCount, locked, quality = GetContainerItemInfo(0, 3)\n\
@@ -1136,7 +862,6 @@ mod tests {
         assert!(s
             .eval::<bool>("return BenillaGetContainerItemID(0, 3) == nil")
             .unwrap());
-        // Empty slot: nil.
         assert!(s
             .eval::<bool>("return GetContainerItemInfo(0, 2) == nil")
             .unwrap());
@@ -1159,7 +884,6 @@ mod tests {
         assert!(s.cursor_item().is_none());
         assert!(!s.eval::<bool>("return CursorHasItem()").unwrap());
 
-        // Pick up slot 1 → cursor holds it, the source slot reads locked, no move queued yet.
         assert!(s.eval::<bool>("return PickupContainerItem(0, 1)").unwrap());
         let held = s.cursor_item().expect("cursor holds the picked item");
         assert_eq!((held.bag, held.slot, held.item_id), (0, 1, 117));
@@ -1173,13 +897,11 @@ mod tests {
             .unwrap());
         assert!(s.take_container_moves().is_empty());
 
-        // GetCursorInfo reports the item.
         let (kind, id) = s
             .eval::<(String, i64)>("local k, id = GetCursorInfo() return k, id")
             .unwrap();
         assert_eq!((kind.as_str(), id), ("item", 117));
 
-        // Place onto slot 5 → a move (0,1)->(0,5) queues, cursor clears, source un-locks.
         assert!(s.eval::<bool>("return PickupContainerItem(0, 5)").unwrap());
         assert!(s.cursor_item().is_none());
         assert!(!s.eval::<bool>("return CursorHasItem()").unwrap());
@@ -1193,22 +915,12 @@ mod tests {
                 count: None,
             }]
         );
-        // `local _, _, locked` — the 1.12 five-value shape, the same destructuring the positive
-        // assertion above uses. This read `local i = … return i.isLocked` until 2171: a leftover
-        // of the 1.14 `containerInfo` TABLE that 1187 reached for and 1199 corrected in the
-        // binding without correcting it here. It passed anyway, because 5.1's string metatable
-        // made indexing the `texture` string a silent `nil` and `nil` is a passing `!bool`. Taking
-        // the metatable away — 1.12 has none — is what turned a test that asserted nothing into a
-        // test that raises.
         assert!(!s
             .eval::<bool>("local _, _, locked = GetContainerItemInfo(0, 1) return locked")
             .unwrap());
     }
 
-    /// The sibling of the test above onto an OCCUPIED, DIFFERENT-item slot: the plain SWAP
-    /// (decision 0218, superseding 0216 §2's hop — byte-verified: no `SetCursorItem` on the place
-    /// branch; the wire swaps and the cursor empties, exactly like an empty destination). The
-    /// displaced item never lands on the cursor.
+    /// The reference's place runs no `SetCursorItem`: the displaced item is never held.
     #[test]
     fn pickup_place_onto_occupied_different_item_swaps_and_clears() {
         let mut s = UiScript::new().unwrap();
@@ -1240,8 +952,6 @@ mod tests {
         assert!(s.eval::<bool>("return PickupContainerItem(0, 1)").unwrap());
         assert_eq!(s.cursor_item().unwrap().item_id, 117);
 
-        // Place A onto occupied slot 5 (item B) → move (1→5) queues, the cursor EMPTIES (the
-        // server's swap lands B in slot 1), and the source un-locks.
         assert!(s.eval::<bool>("return PickupContainerItem(0, 5)").unwrap());
         assert!(
             s.cursor_item().is_none(),
@@ -1257,15 +967,12 @@ mod tests {
                 count: None,
             }]
         );
-        // The 1.12 five-value shape — see the sibling test above for what this used to read and
-        // why it passed while asserting nothing (2171).
         assert!(!s
             .eval::<bool>("local _, _, locked = GetContainerItemInfo(0, 1) return locked")
             .unwrap());
     }
 
-    /// Placing onto a SAME-item_id destination merges (the wire tops the stack up itself) —
-    /// still a plain clear-on-move.
+    /// A same-item placement is a plain move: the server merges the stacks.
     #[test]
     fn pickup_place_onto_same_item_merges_and_clears() {
         let mut s = UiScript::new().unwrap();
@@ -1343,7 +1050,6 @@ mod tests {
             (0, 1, 117, Some(3))
         );
 
-        // Placed onto an empty slot: the move carries the split count, and clears.
         assert!(s.eval::<bool>("return PickupContainerItem(0, 2)").unwrap());
         assert!(s.cursor_item().is_none());
         assert_eq!(
@@ -1357,14 +1063,12 @@ mod tests {
             }]
         );
 
-        // Re-split, then place onto a DIFFERENT item: no-op, the split carry is kept.
         s.run("SplitContainerItem(0, 1, 3)").unwrap();
         assert!(!s.eval::<bool>("return PickupContainerItem(0, 9)").unwrap());
         let held = s.cursor_item().expect("kept — can't swap a partial stack");
         assert_eq!(held.count, Some(3));
         assert!(s.take_container_moves().is_empty());
 
-        // Placed onto a SAME-item slot: the server merges — the move queues, cursor clears.
         assert!(s.eval::<bool>("return PickupContainerItem(0, 7)").unwrap());
         assert!(s.cursor_item().is_none());
         assert_eq!(
@@ -1387,7 +1091,7 @@ mod tests {
             .eval::<bool>("return SplitContainerItem(0, 1, 5)")
             .unwrap());
         assert_eq!(s.cursor_item().unwrap().count, None);
-        // Split of MORE than the stack clamps the same way.
+        // A split of more than the stack is a plain pickup too.
         s.run("ClearCursor()").unwrap();
         assert!(s
             .eval::<bool>("return SplitContainerItem(0, 1, 99)")
@@ -1401,7 +1105,6 @@ mod tests {
         s.set_container(0, Some(backpack()));
         assert!(s.eval::<bool>("return PickupContainerItem(0, 1)").unwrap());
         assert!(s.cursor_item().is_some());
-        // Click the same slot again → cancel: cursor clears, nothing queued.
         assert!(s.eval::<bool>("return PickupContainerItem(0, 1)").unwrap());
         assert!(s.cursor_item().is_none());
         assert!(s.take_container_moves().is_empty());
@@ -1411,7 +1114,7 @@ mod tests {
     fn pickup_empty_slot_holds_nothing() {
         let mut s = UiScript::new().unwrap();
         s.set_container(0, Some(backpack()));
-        // Slot 2 is empty, slot 3 is in-flight (unresolved, item_id 0) — neither is pickable.
+        // Slot 2 is empty and slot 3 unresolved: neither can be picked up.
         assert!(!s.eval::<bool>("return PickupContainerItem(0, 2)").unwrap());
         assert!(s.cursor_item().is_none());
         assert!(!s.eval::<bool>("return PickupContainerItem(0, 3)").unwrap());
@@ -1437,10 +1140,6 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetContainerNumSlots(2)").unwrap(), 0);
     }
 
-    /// `GetContainerItemCooldown` — the `GetActionCooldown` conventions on the bag twin: the
-    /// absolute-start triple stored verbatim in `GetTime` seconds, the cold `(0, 0, 1)` shape
-    /// for no-cooldown slots, the stale-refeed guard at expiry, and the re-push replacing a
-    /// bag's prior triples.
     #[test]
     fn container_item_cooldown_reads_the_gettime_triple() {
         let mut s = UiScript::new().unwrap();
@@ -1450,21 +1149,19 @@ mod tests {
         state.slots.get_mut(&1).unwrap().cooldown = Some((96_000, 10_000, true));
         s.set_container(0, Some(state));
 
-        // The pushed absolute start reads back verbatim in seconds.
         assert!(s
             .eval::<bool>(
                 "local s, d, e = GetContainerItemCooldown(0, 1)\n\
                  return s == 96 and d == 10 and e == 1"
             )
             .unwrap());
-        // A slot with no cooldown reads cold.
         assert!(s
             .eval::<bool>(
                 "local s, d, e = GetContainerItemCooldown(0, 3)\n\
                  return s == 0 and d == 0 and e == 1"
             )
             .unwrap());
-        // Past expiry, the same stored triple reads cold — the no-replayed-flash guard.
+        // Past expiry, the same stored triple reads cold.
         s.tick(7.0);
         assert!(s
             .eval::<bool>(
@@ -1484,10 +1181,6 @@ mod tests {
 
     // ── `ContainerIDToInventoryID` (`0x4f94e0`) ─────────────────────────────────────
 
-    /// Two linear arms and no range check. **−2 → 17 and 0 → 19 are not special cases** — they are
-    /// ordinary points on the `id <= 4` line that the caller-side "keyring is −2 / backpack is 0"
-    /// convention happens to land on, which is why they are asserted beside the bag slots rather
-    /// than as exceptions.
     #[test]
     fn container_id_to_inventory_id_is_two_lines_with_no_clamp() {
         let s = UiScript::new().unwrap();
@@ -1495,7 +1188,7 @@ mod tests {
             s.eval::<i64>(&format!("return ContainerIDToInventoryID({id})"))
                 .unwrap()
         };
-        // The `id <= 4` line: keyring, the odd −1, the backpack, the four worn bags.
+        // The `id <= 4` line: the keyring, -1, the backpack, the four worn bags.
         assert_eq!(slot("-2"), 17, "keyring — an ordinary point, not a case");
         assert_eq!(slot("-1"), 18);
         assert_eq!(slot("0"), 19, "backpack — likewise");
@@ -1518,13 +1211,12 @@ mod tests {
             1,
             "one value on every non-raising path"
         );
-        // `0x40a2b0` truncates toward zero — a C cast, not `floor`.
+        // `0x40a2b0` truncates toward zero, a C cast, not `floor`.
         assert_eq!(slot("2.9"), 21, "2.9 -> 2");
         assert_eq!(slot("-2.9"), 17, "-2.9 -> -2, NOT -3");
     }
 
-    /// A missing or non-number argument **raises** — the only guard in the function is the type
-    /// test, and `0x6f4940` does not return.
+    /// A missing or non-number argument raises: the type test's error `0x6f4940` does not return.
     #[test]
     fn container_id_to_inventory_id_raises_on_a_bad_argument() {
         let s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/craft.rs b/crates/benilla-ui/src/script/craft.rs
index ee276781..34d98f14 100644
--- a/crates/benilla-ui/src/script/craft.rs
+++ b/crates/benilla-ui/src/script/craft.rs
@@ -1,73 +1,11 @@
-//! The craft bindings (decision 0437 phase 3) — the Era-shaped Enchanting-window surface driving a
-//! faithful port of the real 1.12 `CraftFrame` (extracted from `interface.MPQ`:
-//! `Interface\FrameXML\Blizzard_CraftUI\CraftFrame.{xml,lua}`). The exact twin of [`super::tradeskill`]
-//! (same two-way seam, same "no wire" law, same FLAT-list INTERIM): the app pushes a **craft
-//! snapshot** ([`UiScript::set_craft`] — the recipes already resolved to name/subname/icon/
-//! description/reagents/tools/color by the app from `Spell.dbc`/`SkillLineAbility.dbc`/bag counts),
-//! and the Lua `DoCraft`/`CloseCraft` calls queue outbound **intents** the app drains
-//! ([`UiScript::take_craft_dos`] returns spell ids / [`UiScript::take_craft_close`]). The engine holds
-//! no recipe knowledge — a recipe is name/subname/icon/description/difficulty/reagents/tools, all
-//! app-resolved (0437 §"The decision" item 1). `CraftRecipe` reuses [`super::TradeSkillDifficulty`]
-//! outright (0437's own framing: "one solved pattern") rather than a second color enum — the Era
-//! `CraftTypeColor`/`TradeSkillTypeColor` tables are byte-identical (ref `Blizzard_CraftUI.lua:6-13` vs
-//! `Blizzard_TradeSkillUI.lua`'s own table), so the four color keys really are one vocabulary.
+//! The craft bindings the stock `Blizzard_CraftUI` window calls, over the recipe snapshot the app
+//! pushes ([`UiScript::set_craft`]); `DoCraft` and `CloseCraft` queue intents the app drains. The
+//! window has one action button, `DoCraft(GetCraftSelectionIndex())` (`Blizzard_CraftUI.xml:667`),
+//! and no Create All, so a craft intent is a bare spell id.
 //!
-//! ## Where Craft actually differs from TradeSkill (verified against the ref, not assumed)
-//!
-//! - **No Create All.** The 1.12 `CraftFrame` ships one action button (`DoCraft(GetCraftSelectionIndex())`,
-//!   ref `Blizzard_CraftUI.xml:667`) — no repeat-count EditBox, no `GetCraftskillRepeatCount`. `DoCraft`
-//!   therefore queues a bare spell id, never a `(spell id, count)` pair — [`UiScript::take_craft_dos`]
-//!   returns `Vec<u32>`.
-//! - **`GetCraftInfo` is a 7-tuple, not TradeSkill's 4-tuple**: `craftName, craftSubSpellName, craftType,
-//!   numAvailable, isExpanded, trainingPointCost, requiredLevel` (ref l.37/168/289) — the trailing three
-//!   are Beast Training's own fields (a pet ability's training-point cost + the pet's required level).
-//!   Beast Training is out of scope (0437's own line — the pet arc owns it), so v1 hardcodes
-//!   `trainingPointCost = 0` and `requiredLevel = 0` — never nonzero, so every ref branch gated on them
-//!   (`Craft_UpdateTrainingPoints`, the per-row Cost text, the red/green pet-level Requirements line) is
-//!   unreachable and dropped from the ported XML, not merely stubbed (this file's job is the tuple
-//!   shape; the XML's job is not painting dead branches).
-//! - **A recipe carries a `sub_name`** (`craftSubSpellName`) TradeSkill's own recipes never have — the
-//!   ref's row paints it in parens beside the name (`format(TEXT(PARENS_TEMPLATE), craftSubSpellName)`,
-//!   ref l.218) when non-empty. Enchanting itself rarely uses it (most enchant spells have no sub-rank
-//!   text), but the field is real in the ref's own tuple, so it ships in v1 rather than being folded away.
-//! - **A recipe carries a pre-resolved `description`** (`GetCraftDescription`, ref l.312) TradeSkill's
-//!   own recipe never exposes to Lua at all — Enchanting's detail pane shows the spell's flavor/effect
-//!   text above the reagent grid (ref `CraftDescription`), a region TradeSkill's own detail pane has no
-//!   analogue for.
-//! - **No product-item concept.** TradeSkill's `product_item`/`min_made`/`max_made`/`cooldown_secs`
-//!   have no Craft equivalent: an enchant recipe doesn't "create" a bag item the way a tradeskill recipe
-//!   does (it modifies an item in place, or resolves as a pure effect) — `CraftIcon`'s hover shows the
-//!   **spell**, not a product item (`GameTooltip:SetCraftSpell`, ref l.566, vs TradeSkill's
-//!   `SetTradeSkillItem` with no reagent index) — see [`super::tooltip_item`]'s `SetCraftSpell`.
-//! - **`needs_item_target` has no Lua getter.** It is pure app-side bookkeeping (0437 §"What scoping
-//!   verified": `TARGET_FLAG_ITEM` enchant casts need a client-side item pick after `DoCraft`) — the
-//!   ref XML plays no part in that flow (no such concept exists in the real client's item-target UX
-//!   either; it's the cursor/target machinery, not FrameXML). See `CraftFrame.xml`'s own header note.
-//!
-//! ## v1 is FLAT — no header rows (the law landed for TradeSkill; Craft is a named divergence)
-//!
-//! Exactly [`super::tradeskill`]'s own v1 law: [`CraftState::recipes`] renders as one flat row per
-//! recipe, `index` 1-based straight into the list — though the ORDER of that list is now this
-//! module's, not the app's (decision 1124: [`recipe_order`], the craft type's own byte-verified
-//! comparator, applied in [`UiScript::set_craft`]). `GetCraftInfo` therefore never
-//! returns the `"header"` `craftType` the ref Lua also checks for (ref l.38/77/199/252/292). The
-//! header/grouping law itself is no longer pending — decision 0446 confirmed it byte-exact
-//! (`0x4f60c0`) and TradeSkill grew the real tree engine ([`super::tradeskill`]'s `build_groups`)
-//! on it. Craft never got the same port and stays on this v1 flat render; `Expand/CollapseCraftSkillLine`
-//! are still literal no-ops, wired only so the ported XML's header-click handlers don't error
-//! (TradeSkill's `Expand/CollapseTradeSkillSubClass` precedent). 0446 also confirmed the one live case
-//! (Enchanting) renders flat either way — a single group's header suppresses under TradeSkill's own law
-//! too — so the divergence is currently unobservable, but it is real and named as a follow-up in
-//! decision 0530.
-//!
-//! ## The tooltip channels
-//!
-//! `GameTooltip:SetCraftItem(craftIndex, reagentIndex)` is registered in [`super::tooltip_item`],
-//! beside `SetTradeSkillItem`. `GameTooltip:SetCraftSpell(craftIndex)` lives in
-//! [`super::tooltip_spell`] beside `SetTrainerService`, its structural twin: both are SELECTORS
-//! into the shared spell/item builders rather than renderers of their own. The v1 two-line
-//! "name white, description gold" render is gone — `SetCraftSpell 0x533e90` funnels into the same
-//! `0x52e610`/`0x52b650` pair every other content binding does, so two lines were eight-plus short.
+//! Not built: the reference's header rows (`0x4f60c0`). The list is flat, `GetCraftInfo` never
+//! answers `"header"` and `Expand`/`CollapseCraftSkillLine` do nothing; Enchanting, with a single
+//! group, renders flat in the reference too.
 
 use mlua::{Lua, MultiValue, Value, Variadic};
 
@@ -75,35 +13,28 @@ use super::binding_abi::number_arg;
 use super::item_stats::item_link;
 use super::Model;
 
-/// One reagent a recipe consumes (`GetCraftReagentInfo`): the bag-counted need/have plus the resolved
-/// name/icon — both `None` until the app's ask-once item-template answer lands, the same miss path as
-/// [`super::tradeskill::TradeSkillReagent`] (this struct's exact twin).
+/// One reagent a recipe consumes (`GetCraftReagentInfo`); name and icon are `None` until the item
+/// template answer lands.
 #[derive(Clone, Debug, PartialEq)]
 pub struct CraftReagent {
-    /// The reagent's item entry — the tooltip channel key (`GameTooltip:SetCraftItem(i, j)` resolves
-    /// through this, never through `name`/`icon`).
+    /// The item entry `GameTooltip:SetCraftItem` resolves through.
     pub item: u32,
-    /// The resolved display name, or `None` while the ask-once template answer is still in flight.
     pub name: Option<String>,
-    /// The resolved icon texture path, or `None` while still in flight.
     pub icon: Option<String>,
-    /// How many this recipe consumes.
     pub need: u32,
-    /// How many the player's bags currently hold (`count_of`, decision 0269).
     pub have: u32,
 }
 
-/// What `GameTooltip:SetCraftSpell` describes for one row — the pre-resolved output of the
-/// app-side law (`ui_craft::craft_tooltip`, transcribing `SetCraftSpell 0x533e90`).
-/// [`super::TrainerTooltip`]'s twin in shape and its opposite in law: this one tests the recipe's
-/// **own** `Effect[i]` (24 `CREATE_ITEM` → the item, 36 `LEARN_SPELL` → the taught spell), never
-/// `57`, never sets `altCaster`, and does **not** validate that the hop resolves before taking it.
+/// What `GameTooltip:SetCraftSpell` (`0x533e90`) describes for a row, resolved by the app from the
+/// recipe's own `Effect[i]`: 24 `CREATE_ITEM` picks the item, 36 `LEARN_SPELL` the taught spell.
+/// Unlike the trainer's, it never tests 57 (`LEARN_PET_SPELL`), sets no altCaster and never checks
+/// that the target resolves.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum CraftTooltip {
-    /// The ITEM builder, on `EffectItemType[i]` of the matched `CREATE_ITEM` slot.
+    /// The item builder (`0x52b650`) on the matched `CREATE_ITEM` slot's `EffectItemType`.
     Item(u32),
-    /// The SPELL builder, on `EffectTriggerSpell[i]` of the matched `LEARN_SPELL` slot — or on the
-    /// recipe spell itself when no slot matched, which is every enchant.
+    /// The spell builder (`0x52e610`) on the matched `LEARN_SPELL` slot's `EffectTriggerSpell`, or
+    /// on the recipe itself when no slot matches, as for every enchant.
     Spell(u32),
 }
 
@@ -113,98 +44,62 @@ impl Default for CraftTooltip {
     }
 }
 
-/// One recipe row (`GetCraftInfo` + its detail-pane getters): a known spell carrying attr
-/// `SPELL_ATTR_IS_TRADESKILL`, resolved by the app from `Spell.dbc`/`SkillLineAbility.dbc`/bag counts —
-/// [`super::tradeskill::TradeSkillRecipe`]'s twin, minus the product-item concept, plus `sub_name` +
-/// `description` (module doc, "Where Craft actually differs").
+/// One recipe row: a known `SPELL_ATTR_IS_TRADESKILL` spell, resolved by the app.
 #[derive(Clone, Debug, PartialEq)]
 pub struct CraftRecipe {
-    /// The recipe spell id — what `DoCraft` queues as the `CMSG_CAST_SPELL` target.
+    /// What `DoCraft` queues for `CMSG_CAST_SPELL`.
     pub spell_id: u32,
     pub name: String,
-    /// The rank subtext (`craftSubSpellName`, ref `GetCraftInfo`'s 2nd return) — `""` for most
-    /// enchants; painted in parens beside the name when non-empty (ref l.217-221).
+    /// The rank subtext (`craftSubSpellName`), usually empty for an enchant; the stock window
+    /// paints it in parentheses when set (`Blizzard_CraftUI.lua:217-221`).
     pub sub_name: String,
-    /// The color band `GetCraftInfo`'s `craftType` reports — [`super::TradeSkillDifficulty`] REUSED
-    /// outright (module doc) for the four shared keys. The REAL client's Craft string table is
-    /// WIDER (`0x807e00`, pinned 2026-07-17): tier codes shifted 1..4 with `0 → "none"`, plus a
-    /// 5th `"used"` tier — a still-optimal recipe teaching a learnable `SPELL_EFFECT_LEARN_SPELL`,
-    /// which only Beast Training recipes carry. An Enchanting book (this window's one occupant)
-    /// can never produce either extra key, so the shared enum stays honest until the
-    /// beast-training arc feeds one (that arc grows the vocabulary).
+    /// `GetCraftInfo`'s `craftType`: one of the four keys `CraftTypeColor` colours as
+    /// `TradeSkillTypeColor` does (`Blizzard_CraftUI.lua:6-13`). The reference's table
+    /// (`0x807e00`) adds `"none"` and `"used"` (a still-optimal Beast Training recipe teaching a
+    /// learnable spell); Enchanting never produces either, and neither is built.
     pub difficulty: super::TradeSkillDifficulty,
-    /// `min` over reagents of `floor(have/need)` — `0` when any reagent is short; the count
-    /// `GetCraftInfo` reports as `numAvailable`.
+    /// `numAvailable`: the least `floor(have / need)` over the reagents.
     pub num_available: u32,
-    /// The recipe's own icon (there is no separate "product" icon concept for Craft — module doc);
-    /// `None` only while still in flight.
     pub icon: Option<String>,
-    /// The pre-substituted spell description (`GetCraftDescription`) — app-resolved (the $-token
-    /// engine lives app-side, [`super::tooltip_spell`]'s own law). `None` renders as a blank line (ref
-    /// l.316: `CraftDescription:SetText(" ")`, never hidden).
+    /// `GetCraftDescription`, `$`-tokens substituted by the app; `None` paints a blank line
+    /// (`Blizzard_CraftUI.lua:316`).
     pub description: Option<String>,
-    /// An `ENCHANT_ITEM`-family effect: `DoCraft` on this recipe arms an app-side item-target pick
-    /// (0437 §"What scoping verified": `TARGET_FLAG_ITEM`/`TARGET_FLAG_TRADE_ITEM`) — pure app-side
-    /// bookkeeping, no Lua getter (module doc).
+    /// An `ENCHANT_ITEM` effect (`TARGET_FLAG_ITEM`, `TARGET_FLAG_TRADE_ITEM`): `DoCraft` then arms
+    /// an app-side item pick. No Lua getter reads it.
     pub needs_item_target: bool,
-    /// Consumed reagents, in display order (`GetCraftNumReagents`/`GetCraftReagentInfo`).
     pub reagents: Vec<CraftReagent>,
-    /// The Requirements line's tool list — `(tool name, have)` pairs (e.g. `("Runed Copper Rod", true)`);
-    /// exposed to Lua as `GetCraftSpellFocus`'s alternating multivalue
-    /// ([`super::tradeskill::TradeSkillRecipe::tools`]'s twin).
+    /// The Requirements line's `(tool name, have)` pairs (`GetCraftSpellFocus`).
     pub tools: Vec<(String, bool)>,
-    /// What the detail-icon hover describes ([`CraftTooltip`]) — resolved app-side, because the law
-    /// reads `Spell.dbc` effect columns the engine cannot see.
     pub tooltip: CraftTooltip,
-    /// `Spell.dbc spellLevel` (`+0x74`) — the **rank-ordering key** of the Beast Training comparator
-    /// ([`recipe_order`]). Also what `GetCraftInfo`'s `requiredLevel` return is built from, though
-    /// that surface is still hardcoded `0` here (module doc).
+    /// `Spell.dbc` `spellLevel` (`+0x74`), the Beast Training comparator's rank key. The
+    /// reference's `requiredLevel` return comes from it; here that return is 0.
     pub spell_level: u32,
 }
 
-/// One open craft window: the skill line's name/rank, the craft type, and its recipe list. Pushed
-/// whole by the app ([`UiScript::set_craft`]); `None` means the window is closed.
+/// The open craft window, pushed whole by the app.
 #[derive(Clone, Debug, PartialEq)]
 pub struct CraftState {
-    /// The window's title (`GetCraftName`) — e.g. `"Enchanting"`. Also the skill line's display name
-    /// for the rank StatusBar (`GetCraftDisplaySkillLine`'s first return) — Craft has only the one
-    /// name, unlike TradeSkill's separately-fetched `GetTradeSkillLine`.
+    /// The title `GetCraftName` answers, also `GetCraftDisplaySkillLine`'s name.
     pub name: String,
     pub rank: u32,
     pub max_rank: u32,
-    /// The **craft type** — the opener spell's `EffectMiscValue[0]`, which the client stores at
-    /// `ds:0xbdcfb8` (1 Beast Training · 3 Enchanting). It is the comparator switch: `cmp
-    /// ds:0xbdcfb8,1` @ `0x4f6765` picks `0x4f6920` for Beast Training, `0x4f67a0` otherwise.
+    /// The opener spell's `EffectMiscValue[0]`, stored at `ds:0xbdcfb8`: 1 Beast Training, 3
+    /// Enchanting. It picks the row comparator (`0x4f6765`).
     pub craft_type: u32,
-    /// The window's recipe rows in ANY order — [`UiScript::set_craft`] sorts them ([`recipe_order`]);
-    /// `index` is 1-based into the sorted list.
+    /// In any order; [`UiScript::set_craft`] sorts them.
     pub recipes: Vec<CraftRecipe>,
 }
 
-/// The craft type whose comparator carries the extra `spellLevel` key ([`recipe_order`]) — the
-/// opener spell 5149 "Beast Training"'s `EffectMiscValue[0]`. The only other type this window ever
-/// opens with is Enchanting's **3**, which takes the shorter comparator `0x4f67a0`.
+/// Beast Training's craft type, the `EffectMiscValue[0]` of spell 5149.
 const CRAFT_TYPE_BEAST_TRAINING: u32 = 1;
 
-/// The Craft window's **row order** — `0x4f6920` (craft type 1, Beast Training) / `0x4f67a0` (every
-/// other type, i.e. Enchanting; decision 1124). Both are the same cascade and
-/// the Beast Training one has one extra key:
+/// The craft row order: difficulty tier (`[+0xc]`) ascending, then name (collator `0x64a4c0`),
+/// then, at Beast Training only (`0x4f6920`; every other type uses `0x4f67a0`), `spellLevel`
+/// ascending, which orders a pet ability's ranks.
 ///
-/// 1. the **difficulty tier** `[+0xc]` ascending ([`super::TradeSkillDifficulty::tier`]);
-/// 2. the localized **name** (collator `0x64a4c0`);
-/// 3. **`Spell.dbc spellLevel`** (`+0x74`) ascending — **only** in `0x4f6920`. This is the key that
-///    orders a pet ability's ranks, and the whole reason Beast Training needs its own comparator.
-///
-/// What benilla had instead was `SkillLineAbility.req_skill_value`, descending — a column the client
-/// never reads anywhere in its craft TU, and which is a constant `1` on every row of skill line 261
-/// *and* 333 in the shipped DBC. So the primary key was inert and the order collapsed to the name.
-///
-/// The trailing `spell_id` key is **ours, not the client's**: its cascade ends at `spellLevel`, so
-/// rows tying on everything above (Charge's six ranks all carry `spellLevel = 0`) fall through to its
-/// qsort's residue over an array benilla doesn't reproduce. Something must break that tie, and a
-/// deterministic key is the only honest choice — benilla's was a `HashSet`'s iteration order, which
-/// re-shuffled the pane between runs. Ascending spell id is also ascending rank across every 1.12
-/// pet-ability family, so it agrees with the reference wherever the reference is defined.
+/// Deviation: a last `spell_id` key breaks the remaining ties (Charge's six ranks all have
+/// `spellLevel` 0), because the reference leaves them to its qsort over an array benilla does not
+/// reproduce; ascending id is ascending rank in every 1.12 pet-ability family.
 fn recipe_order(a: &CraftRecipe, b: &CraftRecipe, craft_type: u32) -> std::cmp::Ordering {
     a.difficulty
         .tier()
@@ -220,9 +115,8 @@ fn recipe_order(a: &CraftRecipe, b: &CraftRecipe, craft_type: u32) -> std::cmp::
         .then_with(|| a.spell_id.cmp(&b.spell_id))
 }
 
-/// The WoW enUS collator (`0x64a4c0` — the case-**insensitive** one the craft comparators use, unlike
-/// the trainer rows' `0x64a480`), approximated: case-insensitive alphabetical, with the raw bytes as
-/// a stable tie-break so equal-when-folded names keep a deterministic order.
+/// Approximates the case-insensitive enUS collator the craft comparators call (`0x64a4c0`; the
+/// trainer rows use `0x64a480`): case-folded order, raw bytes breaking ties.
 fn collate(a: &str, b: &str) -> std::cmp::Ordering {
     a.to_lowercase()
         .cmp(&b.to_lowercase())
@@ -230,14 +124,8 @@ fn collate(a: &str, b: &str) -> std::cmp::Ordering {
 }
 
 impl super::UiScript {
-    /// Push (or clear, with `None`) the open craft window's recipe snapshot. Snapshots re-push every
-    /// time a resolved field changes — no diffing happens here. On a push, the engine **sorts the
-    /// rows** into the craft type's own order ([`recipe_order`] — the ordering is the engine's, like
-    /// the trainer tree's and the tradeskill list's, so one binding's verified comparator lives in
-    /// exactly one place) and then **preserves the selection across the replace**: if the previously
-    /// selected recipe's spell id still appears in the new list, the selection follows it to its new
-    /// index; otherwise it clears to `0` ([`super::tradeskill::set_trade_skill`]'s own
-    /// selection-survival law, verbatim). Clearing (`None`) always resets the selection.
+    /// Push the open craft window's snapshot, or clear it with `None`. A push sorts the rows and
+    /// keeps the selection on its spell id, clearing it when that recipe is gone.
     pub fn set_craft(&mut self, state: Option<CraftState>) {
         let mut model = self.model_mut();
         match state {
@@ -261,33 +149,27 @@ impl super::UiScript {
         }
     }
 
-    /// Drain the spell id intents `DoCraft` queued since the last call — the engine resolves each
-    /// clicked recipe's INDEX to its spell id, so the app sends `CMSG_CAST_SPELL` without needing the
-    /// index mapping. NO count: unlike [`super::tradeskill::take_trade_skill_dos`], the 1.12 CraftFrame
-    /// has no Create All (module doc) — one `DoCraft` call, one queued spell id.
+    /// Drain the spell ids `DoCraft` queued, one per call, with no count.
     pub fn take_craft_dos(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().craft_dos)
     }
 
-    /// Whether `CloseCraft` was called since the last drain (and clear the flag). Like
-    /// [`super::tradeskill::take_trade_skill_close`], the client-side close sends no packet.
+    /// Whether `CloseCraft` was called since the last drain; the close sends no packet.
     pub fn take_craft_close(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().craft_close)
     }
 }
 
-/// The recipe at a 1-based index, or `None` when out of range / no window is open.
+/// The recipe at a 1-based index.
 fn recipe(model: &Model, index: usize) -> Option<&CraftRecipe> {
     let n = index.checked_sub(1)?;
     model.craft.as_ref()?.recipes.get(n)
 }
 
-/// The recipe count of the open window (`0` when none is open).
 fn num_recipes(model: &Model) -> usize {
     model.craft.as_ref().map_or(0, |c| c.recipes.len())
 }
 
-/// An optional string as a Lua value (`nil` when absent).
 fn opt_str(lua: &Lua, s: Option<&String>) -> mlua::Result<Value> {
     Ok(match s {
         Some(s) => Value::String(lua.create_string(s)?),
@@ -295,7 +177,7 @@ fn opt_str(lua: &Lua, s: Option<&String>) -> mlua::Result<Value> {
     })
 }
 
-/// A `bool` as the Era `1`/`nil` shape.
+/// A `bool` as the reference's `1` or nil.
 fn era_bool(b: bool) -> Value {
     if b {
         Value::Integer(1)
@@ -308,9 +190,8 @@ fn era_bool(b: bool) -> Value {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetCraftName() → the window's title ("UNKNOWN" when closed — TradeSkill's own
-    // GetTradeSkillLine no-window convention, since the ref gives Craft no documented closed shape of
-    // its own; CraftFrameTitleText:SetText(GetCraftName()) is called unconditionally, ref l.101).
+    // GetCraftName() → the title, or "UNKNOWN" when closed (the reference's closed answer is
+    // untraced); the stock window sets its title unconditionally (`Blizzard_CraftUI.lua:101`).
     g.set(
         "GetCraftName",
         lua.create_function(|lua, ()| {
@@ -323,9 +204,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCraftDisplaySkillLine() → name, rank, maxRank; name is NIL when closed (ref l.108-109 tests
-    // it for truthiness to Show/Hide the whole rank StatusBar) — unlike GetCraftName above, which
-    // always returns a string.
+    // GetCraftDisplaySkillLine() → name, rank, maxRank; the name is nil when closed, which hides
+    // the rank bar (`Blizzard_CraftUI.lua:108-109`).
     g.set(
         "GetCraftDisplaySkillLine",
         lua.create_function(|lua, ()| {
@@ -342,7 +222,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // → the number of recipes the open window offers (0 when closed).
+    // GetNumCrafts() → the recipe count, 0 when closed.
     g.set(
         "GetNumCrafts",
         lua.create_function(|lua, ()| {
@@ -351,19 +231,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCraftInfo(index) → craftName, craftSubSpellName, craftType, numAvailable, isExpanded,
-    // trainingPointCost, requiredLevel (ref l.37/168/289's own 7-tuple — module doc). `craftType` is
-    // the difficulty color key, never "header"; `isExpanded` is always nil; the trailing two are
-    // Beast Training's own fields, hardcoded 0 (out of scope, module doc). OOB → a single nil.
-    // The two link verbs (1973).
-    //
-    // GetCraftItemLink(index) — `0x4f72a0`: the number gate raises its Usage; then the spell's
-    // Spell.dbc `castUI` decides. An Enchanting recipe (`castUI == 3` — this window's craft type,
-    // and the only shipped input: every castUI-3 row, including the twenty that create an item
-    // such as Runed Copper Rod) takes the ENCHANT leg, which cannot fail:
-    // `|cffffffff|Henchant:<spellId>|h[<spell name>]|h|r` — fixed white, the spell's id and name.
-    // Any other craft type would scan the effects for CREATE_ITEM, which no shipped row carries,
-    // and answer ZERO values — Beast Training's rows do.
+    // GetCraftItemLink(index) (`0x4f72a0`): a non-number raises its usage. The reference keys on
+    // the spell's `castUI`: 3, Enchanting's craft type, for which the type stands in here, answers
+    // `|cffffffff|Henchant:<spell id>|h[<spell name>]|h|r` and cannot miss, even for the twenty
+    // recipes that create an item; any other type scans for a `CREATE_ITEM` effect no shipped row
+    // has, so Beast Training answers zero values.
     g.set(
         "GetCraftItemLink",
         lua.create_function(|lua, index: Value| {
@@ -381,9 +253,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCraftReagentItemLink(index, reagentIndex) — `0x4f7730`, a byte-clone of the trade-skill
-    // one with its own Usage: both arguments number-gated, `reagentIndex` 1-based over the
-    // non-empty slots, ALWAYS one value — the reagent's `|Hitem:` link or nil.
+    // GetCraftReagentItemLink(index, reagentIndex) (`0x4f7730`): both arguments number-gated,
+    // `reagentIndex` counting the non-empty slots from 1; always one value, the item link or nil.
     g.set(
         "GetCraftReagentItemLink",
         lua.create_function(|lua, (index, reagent): (Value, Value)| {
@@ -409,6 +280,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
+    // GetCraftInfo(index) → craftName, craftSubSpellName, craftType, numAvailable, isExpanded,
+    // trainingPointCost, requiredLevel (`Blizzard_CraftUI.lua:168`); one nil past the end.
+    // `isExpanded` is always nil; Beast Training's cost and level answer 0, not built.
     g.set(
         "GetCraftInfo",
         lua.create_function(|lua, index: usize| {
@@ -428,7 +302,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCraftIcon(index) → icon texture path (nil while in flight / OOB).
+    // GetCraftIcon(index) → the icon path, nil while in flight or past the end.
     g.set(
         "GetCraftIcon",
         lua.create_function(|lua, index: usize| {
@@ -437,8 +311,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCraftDescription(index) → the pre-substituted description, or nil (no description / OOB) —
-    // ref l.312 tests this return for truthiness before painting it.
+    // GetCraftDescription(index) → the description or nil, which the stock window tests before
+    // painting (`Blizzard_CraftUI.lua:312`).
     g.set(
         "GetCraftDescription",
         lua.create_function(|lua, index: usize| {
@@ -450,7 +324,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCraftNumReagents(index) → this recipe's reagent count (0 when OOB / no window).
+    // GetCraftNumReagents(index) → the reagent count, 0 past the end or when closed.
     g.set(
         "GetCraftNumReagents",
         lua.create_function(|lua, index: usize| {
@@ -459,8 +333,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCraftReagentInfo(index, reagentIndex) → name, icon, need, have (a single nil when the
-    // recipe/reagent index is OOB) — TradeSkill's own GetTradeSkillReagentInfo shape, verbatim.
+    // GetCraftReagentInfo(index, reagentIndex) → name, icon, need, have; one nil past the end.
     g.set(
         "GetCraftReagentInfo",
         lua.create_function(|lua, (index, reagent_index): (usize, usize)| {
@@ -479,9 +352,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCraftSpellFocus(index) → an alternating (name, has) multivalue, one pair per Requirements
-    // tool (e.g. "Runed Copper Rod", 1) — fed into BuildColoredListString (ref l.361), TradeSkill's
-    // own GetTradeSkillTools shape. Empty when the recipe has no tools / index is OOB.
+    // GetCraftSpellFocus(index) → name, has for each required tool, alternating, the shape
+    // `BuildColoredListString` takes (`Blizzard_CraftUI.lua:361`); nothing when there are none.
     g.set(
         "GetCraftSpellFocus",
         lua.create_function(|lua, index: usize| {
@@ -497,17 +369,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCraftButtonToken() → "CREATE" (v1 constant): the ref resolves the Create button's label via
-    // getglobal(GetCraftButtonToken()) (ref l.106), swapping to a "TRAIN" token for Beast Training —
-    // out of scope (module doc), so this always returns the one token.
+    // GetCraftButtonToken() → "CREATE", the global naming the button's label
+    // (`Blizzard_CraftUI.lua:106`); Beast Training's "TRAIN" is not built.
     g.set(
         "GetCraftButtonToken",
         lua.create_function(|lua, ()| Ok(Value::String(lua.create_string("CREATE")?)))?,
     )?;
 
-    // GetCraftSelectionIndex() / SelectCraft(index) — the engine-held selection (1-based, 0 = none).
-    // Out-of-range selects clear it; the getter clamps to the current recipe count — TradeSkill's own
-    // selection contract, verbatim.
+    // SelectCraft(index) / GetCraftSelectionIndex(): the selection, 1-based with 0 for none; an
+    // out-of-range select clears it, and the getter answers 0 past the recipe count.
     g.set(
         "SelectCraft",
         lua.create_function(|lua, index: u32| {
@@ -531,7 +401,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // DoCraft(index) — queue the recipe's SPELL ID (no count, module doc). Out of range → ignored.
+    // DoCraft(index): queue the row's spell id; out of range is ignored.
     g.set(
         "DoCraft",
         lua.create_function(|lua, index: usize| {
@@ -543,8 +413,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CloseCraft() — client-side close (no packet, vanilla): flag it so the app clears its local
-    // state.
+    // CloseCraft(): no packet; the flag tells the app to clear its state.
     g.set(
         "CloseCraft",
         lua.create_function(|lua, ()| {
@@ -554,10 +423,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // Expand/CollapseCraftSkillLine(index) — no-ops in v1: the recipe list is flat (the header law
-    // landed for TradeSkill, decision 0446, but was never ported here — module doc), so the ported
-    // XML's header-click handlers have nothing to fold — TradeSkill's own
-    // Expand/CollapseTradeSkillSubClass precedent.
+    // Expand/CollapseCraftSkillLine(index): no-ops over the flat list (module doc).
     g.set(
         "ExpandCraftSkillLine",
         lua.create_function(|_, _args: Variadic<Value>| Ok(()))?,
@@ -575,10 +441,9 @@ mod tests {
     use super::*;
     use crate::script::UiScript;
 
-    /// Enchanting's `EffectMiscValue[0]` — the craft type whose comparator has no `spellLevel` key.
+    /// Enchanting's craft type, whose comparator has no `spellLevel` key.
     const CRAFT_TYPE_ENCHANTING: u32 = 3;
 
-    /// One recipe fixture — a single-reagent, single-tool row, distinct spell ids per name.
     fn recipe(
         spell_id: u32,
         name: &str,
@@ -587,8 +452,6 @@ mod tests {
     ) -> CraftRecipe {
         CraftRecipe {
             spell_id,
-            // The fixture's default subject: the recipe itself (the enchant case — no matching
-            // effect slot), so a test that cares about the item arm sets it explicitly.
             tooltip: CraftTooltip::Spell(spell_id),
             name: name.into(),
             sub_name: String::new(),
@@ -609,10 +472,7 @@ mod tests {
         }
     }
 
-    /// A two-recipe Enchanting window: Minor Beastslaying (trivial, craftable) and Minor Health
-    /// (optimal, out of reagents). Declared trivial-first on purpose — the engine sorts by
-    /// difficulty tier ascending ([`recipe_order`]), so the window renders **Minor Health at index 1**
-    /// and Beastslaying at 2, whatever order the app pushed.
+    /// Two Enchanting recipes, pushed trivial first; the sort puts Minor Health at index 1.
     fn state() -> CraftState {
         CraftState {
             name: "Enchanting".into(),
@@ -709,11 +569,10 @@ mod tests {
             "CREATE"
         );
 
-        // A header row never appears in v1 — GetCraftInfo's type is always a difficulty band.
         assert!(s
             .eval::<bool>("local _,_,t = GetCraftInfo(1) return t ~= 'header'")
             .unwrap());
-        // Expand/CollapseCraftSkillLine are wired but do nothing observable.
+        // Expand and collapse do nothing.
         s.run("ExpandCraftSkillLine(1) CollapseCraftSkillLine(1)")
             .unwrap();
         assert_eq!(s.eval::<i64>("return GetNumCrafts()").unwrap(), 2);
@@ -727,15 +586,13 @@ mod tests {
         s.run("SelectCraft(2)").unwrap();
         assert_eq!(s.eval::<i64>("return GetCraftSelectionIndex()").unwrap(), 2);
 
-        // A re-list that turns 7418 optimal moves it to index 1 — the selection FOLLOWS the spell
-        // id, not the index (and this is the case the engine-side sort makes reachable).
+        // Turning 7418 optimal moves it to index 1, and the selection follows the spell id.
         let mut promoted = state();
         promoted.recipes[0].difficulty = super::super::TradeSkillDifficulty::Optimal;
         promoted.recipes[0].name = "Aaa Beastslaying".into();
         s.set_craft(Some(promoted));
         assert_eq!(s.eval::<i64>("return GetCraftSelectionIndex()").unwrap(), 1);
 
-        // A re-push that drops the selected recipe entirely clears the selection.
         let mut without_7418 = state();
         without_7418.recipes.remove(0);
         s.set_craft(Some(without_7418));
@@ -755,7 +612,6 @@ mod tests {
         );
         assert!(s.take_craft_dos().is_empty(), "drained");
 
-        // An out-of-range index is ignored.
         s.run("DoCraft(9)").unwrap();
         assert!(s.take_craft_dos().is_empty());
     }
@@ -807,7 +663,7 @@ mod tests {
             ("Runed Copper Rod", Some(1), "Arcanite Rod", None)
         );
 
-        // A recipe with no tools returns an empty multivalue (arity 0, not one nil).
+        // No tools: zero values, not one nil.
         let mut c2 = state();
         c2.recipes[1].tools.clear();
         s.set_craft(Some(c2));
@@ -830,15 +686,7 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetCraftSelectionIndex()").unwrap(), 0);
     }
 
-    /// **Beast Training's rank order** (decision 1124), pinned against an emulated run of the
-    /// real `0x4f6920` over real `Spell.dbc` values — and the regression for the director's report
-    /// that "Beast Training lists a skill's ranks out of ascending order" (ledger B229).
-    ///
-    /// The fixture is the reported pane: four Arcane Resistance ranks and four Fire Resistance
-    /// ranks, pushed **shuffled** (as a `HashSet`'s iteration order used to deliver them), all on
-    /// one difficulty tier because pet abilities carry no trivial ranks. Name groups them; the
-    /// `spellLevel` key — 20/30/40/50 per rank — is what orders the ranks inside a group, and it is
-    /// the key the old `req_skill_value`-descending sort did not have.
+    /// The expected order is an emulated run of `0x4f6920` over the shipped `Spell.dbc` values.
     #[test]
     fn beast_training_orders_ranks_by_spell_level() {
         let rank = |spell_id: u32, name: &str, level: u32| CraftRecipe {
@@ -855,7 +703,7 @@ mod tests {
             tools: vec![],
             spell_level: level,
         };
-        // Shuffled on purpose — the exact shape of the report (Arcane read 1, 4, 3, 5).
+        // Shuffled on purpose.
         let recipes = vec![
             rank(24508, "Arcane Resistance", 30),
             rank(24441, "Fire Resistance", 30),
@@ -895,10 +743,8 @@ mod tests {
             ]
         );
 
-        // The falsifiable control: the SAME rows at the Enchanting craft type select
-        // `0x4f67a0`, which has no `spellLevel` key — so the ranks fall to the trailing spell-id
-        // tie-break instead. That they still come out ascending here is benilla's determinism, not
-        // the reference's order; what matters is that the two types differ at all.
+        // The same rows at the Enchanting type take `0x4f67a0`, with no `spellLevel` key: the ranks
+        // fall to the spell-id tie-break, benilla's order rather than the reference's.
         s.set_craft(Some(CraftState {
             name: "Beast Training".into(),
             rank: 0,
@@ -920,15 +766,11 @@ mod tests {
         );
     }
 
-    /// The craft link pair (`0x4f72a0`; 1973): an Enchanting recipe
-    /// answers the ENCHANT link — fixed white, the spell's id and name — and cannot miss; another
-    /// craft type answers zero values (no shipped CREATE_ITEM input); the reagent link is nil
-    /// until its template is in the store, then the item link in its quality colour; the raises.
     #[test]
     fn the_craft_link_verbs_answer_the_clients_shapes() {
         let mut s = UiScript::new().unwrap();
         s.set_craft(Some(state()));
-        // Row 1 is whichever recipe the window's own order puts first: the link names THAT spell.
+        // Row 1 is whichever recipe sorts first.
         let first = s.eval::<String>("return (GetCraftInfo(1))").unwrap();
         let spell = state()
             .recipes
diff --git a/crates/benilla-ui/src/script/cursor.rs b/crates/benilla-ui/src/script/cursor.rs
index 738e8596..5c371459 100644
--- a/crates/benilla-ui/src/script/cursor.rs
+++ b/crates/benilla-ui/src/script/cursor.rs
@@ -1,15 +1,7 @@
-//! The cursor payload (decision 0216, slice 1) — the client's payload-mode global `[0xb4d900]`
-//! as a typed enum, and the drag-gesture mechanics (`RegisterForDrag`/`OnDragStart`/`OnDragStop`/
-//! `OnReceiveDrag`) that transition it. One seam for every surface — bags, the paper doll
-//! ([`doll`], decision 0208 phase 1b), action bars ([`bar`], decision 0216 §7/0218 §4), and the
-//! spellbook ([`super::spellbook`]'s `PickupSpell`, slice 5 — the [`CursorSpell`] producer) — so
-//! sounds, `CURSOR_UPDATE`, grid events, and lock display can't drift apart per window.
-//!
-//! [`container`](super::container)'s `pickup_container_item`, [`doll`]'s
-//! `pickup_inventory_item`, and [`bar`]'s `pickup_action`/`place_action` (the surface-specific
-//! transition bodies) all route through [`queue_cursor_update`]/[`queue_lock_changed`], the one
-//! place those events fire from. [`bar`], [`doll`], and [`drag`] are split out purely for size —
-//! this file keeps the payload types, the shared transition seam, and `install`.
+//! The cursor payload: the client's payload-mode global `[0xb4d900]` as a typed enum, and the drag
+//! gestures ([`drag`]) that change it. Bags, the paper doll ([`doll`]), the action bars ([`bar`])
+//! and the spellbook all transition it through [`queue_cursor_update`] and [`queue_lock_changed`],
+//! so sounds, `CURSOR_UPDATE`, grid events and lock display fire from one place.
 
 use mlua::{Lua, Value};
 
@@ -27,28 +19,17 @@ pub(crate) use drag::{
     abandon_drag, arm_drag, maybe_start_drag, take_drag, DragGesture, DragRelease,
 };
 
-/// The sentinel bag id that folds the player's EQUIPPED slots into the ONE payload space
-/// (decision 0216 §1, extended to the paper doll by decision 0208 phase 1b): a
-/// [`CursorItem`]/[`super::container::ContainerMove`] whose `bag` is `EQUIPMENT_BAG` addresses
-/// `slot` as a 1-based live-API inventory slot id — `GetInventorySlotInfo`'s own numbering
-/// (HeadSlot=1 … TabardSlot=19, `char_stats::SLOT_INFO`'s convention), not a bag's contents.
-/// Disjoint from every real bag id — including the ERA's own negative container ids, which are
-/// real API surface (−1 = `BANK_CONTAINER`, decision 0604; −2 = the keyring) — so a `match` on
-/// `bag` can never confuse the spaces (its original value −1 collided with the bank the day the
-/// bank landed; the sentinel is engine-internal and never crosses the Lua boundary as a value,
-/// verified across the XML fleet at the change). Ammo (id 0) stays OUT of this space — a named
-/// deferral ([`doll::pickup_inventory_item`]'s own range guard).
+/// Sentinel bag id for the player's equipped slots, whose `slot` is a 1-based inventory slot id
+/// (`GetInventorySlotInfo`'s, HeadSlot = 1). Never a Lua value, and disjoint from every real bag
+/// id, -1 the bank and -2 the keyring included. Ammo (slot 0) is outside it.
 pub const EQUIPMENT_BAG: i64 = -100;
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 // The payload
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
-/// What the cursor carries — the client's payload-mode global [0xb4d900] as a typed enum
-/// (1 = live item, 3 = spell, **4 = pet action**, **8 =
-/// macro**, **10 = stabled pet**; our Action arm is the client's bar-slot pickup; the money arm
-/// is mode 2 ([`CursorMoney`], 1962/1965) and the preview arm stays unbuilt). One transition seam
-/// for every surface, so sounds, CURSOR_UPDATE, and lock display can't drift apart per window (decision 0216).
+/// What the cursor carries, by the client's payload mode `[0xb4d900]`: 1 item, 2 money, 3 spell,
+/// 4 pet action, 5 vendor row, 8 macro, 10 stabled pet; `Action` is the bar-slot pickup.
 #[derive(Clone, Debug, PartialEq)]
 pub enum CursorPayload {
     Item(CursorItem),
@@ -56,125 +37,69 @@ pub enum CursorPayload {
     Action(CursorAction),
     Macro(CursorMacro),
     PetAction(CursorPetAction),
-    /// A vendor row grabbed off the merchant window — **mode 5** (see [`CursorMerchantItem`]).
-    ///
-    /// Deliberately NOT `Item`: the reference's `CursorHasItem 0x4895d0` answers truthy for modes
-    /// **1 and 9 only**, so all thirteen stock `CursorHasItem()` gates (TradeFrame, MailFrame,
-    /// PlayerFrame, TargetFrame, PetFrame, StaticPopup, the keyring…) exclude a vendor cursor.
-    /// Making this an `Item` variant would silently open every one of them.
+    /// Mode 5, a vendor row. Not an `Item`: `CursorHasItem` (`0x4895d0`) is true for modes 1 and 9
+    /// only, so all thirteen stock `CursorHasItem()` gates stay shut while one is held.
     Merchant(CursorMerchantItem),
-    /// A pet picked up from the stable window — **mode 10** (see [`CursorStablePet`]).
-    ///
-    /// Mode 10 was recorded as "class/talent ability (DBC)" until the bytes corrected it (decision
-    /// 1677): `0x495020` is the stabled-pet grab, `[0xb4d900] = 10` is written at exactly one site
-    /// image-wide, and it is inside it. benilla built the stable's drag frame-locally on the
-    /// strength of that earlier reading — this variant is what puts it back on the shared cursor,
-    /// so a stable pet dropped on the world or another window clears through the same path as
-    /// every other payload.
+    /// Mode 10, a pet taken from the stable; its grab `0x495010` is the only writer of mode 10.
     StablePet(CursorStablePet),
-    /// Coins picked up off a money frame — **mode 2** (see [`CursorMoney`]).
+    /// Mode 2, coins taken off a money frame.
     Money(CursorMoney),
 }
 
-/// Copper held on the cursor — payload **mode 2**, the client's `[0xb4e2f0]` amount written by
-/// `0x494cc0` from `PickupPlayerMoney 0x48abc0` with `LOOTWINDOWCOINSOUND`. The purse is never
-/// debited by the pickup:
-/// the stock `MoneyTypeInfo["PLAYER"]` shows `GetMoney() - GetCursorMoney() - …`, the subtraction
-/// being how the held coins leave the display while the money stays yours (1962).
+/// Copper held on the cursor, mode 2 (`[0xb4e2f0]`, set by `PickupPlayerMoney`, `0x48abc0`). The
+/// purse is not debited; the stock money frame subtracts `GetCursorMoney()` (`MoneyFrame.lua:17`).
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct CursorMoney {
     pub copper: u32,
 }
 
-/// A vendor row held on the cursor — payload **mode 5**, set by `PickupMerchantItem 0x4fb760`.
-///
-/// **A buy-on-drop cursor, not an item cursor.** The reference writes three globals and this
-/// mirrors all three: the item entry (`0xb4b41c`), the display id that drives the icon
-/// (`0xb4d8ec` — we carry the resolved texture path, which is the same thing one hop later), and
-/// the **0-based** vendor row (`0xb4b420`). Dropping it on a bag slot sends
-/// `CMSG_BUY_ITEM_IN_SLOT 0x1a3`; dropping it on the world, pressing ESC, or the vendor window
-/// closing is a plain clear with **no packet**.
-///
-/// No Lua predicate reports it. `CursorHasItem`, `CursorHasSpell`, `CursorHasMoney` and
-/// `CursorCanGoInSlot` are all nil for mode 5 — no registered binding exposes it at all.
+/// A vendor row held on the cursor, mode 5, set by `PickupMerchantItem` (`0x4fb760`). A drop on a
+/// bag slot is the buy (`CMSG_BUY_ITEM_IN_SLOT`, `0x1a3`); in the reference a drop on the world,
+/// ESC or the vendor closing clears it with no packet. No registered binding reports mode 5 to Lua.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct CursorMerchantItem {
-    /// The row's item template entry — `0xb4b41c`, and what the buy addresses.
+    /// The row's item entry (`0xb4b41c`), which the buy names.
     pub item_id: u32,
-    /// The vendor row this came from, **0-based** (`0xb4b420` = `trunc(arg) - 1`). Kept because
-    /// the reference keeps it: a second `PickupMerchantItem` naming the same row is a toggle-off,
-    /// which is the only thing that reads it back.
+    /// The 0-based vendor row (`0xb4b420` = `trunc(arg) - 1`): a second `PickupMerchantItem` on the
+    /// same row drops the grab.
     pub row: u32,
-    /// The icon drawn at the mouse. The reference stores `ItemDisplayInfo`'s id (`0xb4d8ec`) and
-    /// resolves the art from it; we hold the already-resolved path, which is the same value one
-    /// hop later and the shape every other payload here uses.
+    /// The icon at the mouse, resolved from the display id the reference stores (`0xb4d8ec`).
     pub texture: Option<String>,
 }
 
-/// A pet held on the cursor from the stable window — payload **mode 10** (`0x495020`, the grab
-/// `0x495010`).
-///
-/// Mode 10 was recorded as "class/talent ability (DBC)" until the bytes corrected it (decision
-/// 1677): `[0xb4d900] = 10` is written at exactly one site image-wide and it is inside the
-/// stabled-pet grab, whose id global `[0xb4e300]` holds a **stable index**, not a spell. benilla
-/// first built the stable's drag
-/// frame-locally on the strength of that earlier reading; this puts it on the shared cursor.
+/// A pet held on the cursor from the stable window, mode 10, set by the grab `0x495010`.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct CursorStablePet {
-    /// The slot the grab came from, in the Lua index space `PickupStablePet` takes (`0` = the
-    /// summoned pet, `1..=2` a stable slot) — the client's `[0xb4e300]`.
+    /// `[0xb4e300]`, in `PickupStablePet`'s index space: 0 the summoned pet, 1..=2 a stable slot.
     pub slot: u8,
-    /// The family icon drawn at the mouse. Not merely decoration: a **non-empty icon path is the
-    /// grab's own gate** (`0x495010` refuses without one), so a payload of this shape always has
-    /// one.
+    /// The family icon at the mouse, never empty: the grab refuses a pet without one (`0x495010`).
     pub texture: String,
 }
 
-/// The item currently held on the cursor (`PickupContainerItem`/`SplitContainerItem`/
-/// `PickupInventoryItem` set it). The real client's drag state: it names *where the item was
-/// picked from* (so a second click routes the swap) and carries the icon the app draws at the
-/// mouse. Purely transient — cleared on place/cancel; the server's field updates do the actual
-/// move.
+/// An item held on the cursor: where it was picked from, so the next click routes the swap, and
+/// the icon at the mouse. The server's field updates do the actual move.
 #[derive(Clone, Debug, PartialEq)]
 pub struct CursorItem {
-    /// Live-API bag id the item was picked up from (0 = backpack, 1..=4 an equipped bag,
-    /// [`EQUIPMENT_BAG`] the player's own equipped slots).
+    /// The source bag id in the Lua API's numbering, or [`EQUIPMENT_BAG`].
     pub bag: i64,
-    /// 1-based slot the item was picked up from.
+    /// The 1-based source slot.
     pub slot: u32,
-    /// The picked item's template entry (`GetCursorInfo`'s itemID).
     pub item_id: u32,
-    /// The icon texture path to draw at the mouse (`Interface\Icons\…`); `None` if unresolved.
     pub texture: Option<String>,
-    /// The item link (`GetCursorInfo`'s itemLink), when known.
     pub link: Option<String>,
-    /// A split carry (`SplitContainerItem` picked up `n` of the stack); `None` = the whole stack.
+    /// `Some(n)` for a split of `n`, `None` for the whole stack.
     pub count: Option<u32>,
-    /// The item's quality (0..6) at pickup, carried so `DELETE_ITEM_CONFIRM` (a world drop) can
-    /// report it without a container round-trip.
+    /// Quality (0..6) at pickup, for a world drop's `DELETE_ITEM_CONFIRM`.
     pub quality: Option<u32>,
-    /// The 1-based live-API inventory slot ids this item could be EQUIPPED into (empty = not
-    /// equippable), captured at pickup from the source's own `equip_slots` (the container slot's
-    /// or the doll slot view's — decision 0208 phase 1b's "the fit rule").
-    /// [`doll::pickup_inventory_item`] reads it to decide a place-onto-doll-slot's fit;
-    /// [`doll::cursor_can_go_in_slot`] serves it straight to `CURSOR_UPDATE`'s highlight.
+    /// The 1-based inventory slot ids the item can be equipped into, empty if none: the paper
+    /// doll's place and `CursorCanGoInSlot` read it.
     pub equip_slots: Vec<u8>,
-    /// Whether this item may be placed on an ACTION-BAR slot, captured at pickup from the
-    /// source's own `bar_placeable` — `PlaceAction`'s only item filter (decision 0666).
+    /// Whether `PlaceAction` accepts it, its only item filter.
     pub bar_placeable: bool,
 }
 
-/// How many items the cursor is actually holding, for a payload picked up from a bag.
-///
-/// [`CursorItem::count`] is `None` for a **whole-stack** pickup — it records only what a *split*
-/// carry took — so reading it as `unwrap_or(1)` answers 1 for a stack of twenty. That is a
-/// display wart on a mail attachment and a real arithmetic error on an auction deposit, which is
-/// computed per stack: it would quote a twentieth of what the server then charges. So the true
-/// size comes back from the source slot, which still holds the stack (a pickup locks the slot, it
-/// does not empty it).
-///
-/// Falls back to 1 only when the source slot is genuinely unreadable — a bag the app has not
-/// pushed, or a slot that changed under us.
+/// How many items the cursor holds. A whole-stack pickup has `count: None`, so the size is read
+/// from the source slot, which a pickup locks but does not empty; 1 if that slot is unreadable.
 pub(super) fn held_count(model: &super::Model, item: &CursorItem) -> u32 {
     if let Some(n) = item.count {
         return n.max(1);
@@ -187,23 +112,19 @@ pub(super) fn held_count(model: &super::Model, item: &CursorItem) -> u32 {
         .map_or(1, |s| s.count.max(1))
 }
 
-/// A spell payload ([`super::spellbook`]'s `PickupSpell` produces it): the spellbook slot it was
-/// picked from, its book (`"spell"`/`"pet"`, the Era `GetCursorInfo` shape), and the resolved
-/// spell id.
+/// A spell payload, mode 3, from `PickupSpell` on the player's spellbook.
 #[derive(Clone, Debug, PartialEq)]
 pub struct CursorSpell {
     pub book_slot: u32,
     pub book_type: String,
     pub spell_id: u32,
     pub texture: Option<String>,
-    /// `Attributes & 0x40` (`SPELL_ATTR_PASSIVE`) — a passive cannot go on the action bar
-    /// (`PlaceAction`'s other filter, `0x4e63ad`; decision 0666).
+    /// `Attributes & 0x40` (`SPELL_ATTR_PASSIVE`): `PlaceAction` refuses a passive (`0x4e63ad`).
     pub passive: bool,
 }
 
-/// An action-slot payload ([`bar`]'s `PickupAction`/`place_action` hop produces it): the source
-/// action slot, the packed action's kind byte (SPELL/MACRO/ITEM — decision 0216's
-/// `CMSG_SET_ACTION_BUTTON` type byte), and the action id itself.
+/// An action-bar payload from `PickupAction`: the source slot, the action's type byte as
+/// `CMSG_SET_ACTION_BUTTON` packs it (spell, macro or item) and its id.
 #[derive(Clone, Debug, PartialEq)]
 pub struct CursorAction {
     pub src_slot: u32,
@@ -212,72 +133,45 @@ pub struct CursorAction {
     pub texture: Option<String>,
 }
 
-/// A pet-bar payload ([`pet`]'s `PickupPetAction` produces it) — the client's cursor mode **4**,
-/// whose payload global `[0xb4e2f8]` is the picked slot's **packed word, copied verbatim** (its
-/// sole writer `0x494f0c` is a plain `mov edx,[edi]; mov [0xb4e2f8],edx`; decision 1010).
-///
-/// The word is the payload, and that is the whole design: the drop trampoline `0x4bce00` forwards
-/// this dword into the assign core without reading a field of it, so a slot's contents after any
-/// accepted drop is a word that already existed elsewhere in client state. Nothing is encoded at
-/// drop time and nothing here needs decoding.
-///
-/// This payload is **pet-bar-only**. `PlaceAction` refuses it (`PlaceAction 0x4e62e0`'s
-/// accept table: pet actions and class abilities are the refused modes, macros are not), and
-/// nothing else produces it — which is also why a pet bar can only ever be *rearranged*, never
-/// populated from the spellbook: its contents are the server's.
+/// A pet-bar payload, mode 4, from `PickupPetAction` or the pet spellbook: the packed action word
+/// copied verbatim into `[0xb4e2f8]` (`0x494f0c`) and dropped undecoded (`0x4bce00`). Pet bar
+/// only: `PlaceAction` refuses it (`0x4e62e0`).
 #[derive(Clone, Debug, PartialEq)]
 pub struct CursorPetAction {
-    /// The 1-based pet bar slot it was picked from.
+    /// The 1-based pet bar slot it came from, 0 from the spellbook.
     pub src_slot: u32,
-    /// The slot's packed word, verbatim.
+    /// The packed action word, verbatim.
     pub packed: u32,
-    /// `Attributes & 0x40` for a spell word — carried because the assign core's one source filter
-    /// tests it at DROP time, not at pickup (`0x4bc9f8`).
+    /// `Attributes & 0x40` of a spell word, tested at the drop, not the pickup (`0x4bc9f8`).
     pub passive: bool,
     pub texture: Option<String>,
 }
 
-/// A macro payload ([`super::macros`]'s `PickupMacro` produces it) — the client's cursor mode
-/// **8**, whose payload global is the bare macro id (`[0xb4e2fc]`, the ONE non-item/non-spell
-/// payload `PlaceAction 0x4e62e0` accepts).
-/// Unlike every other arm this one carries no source slot to swap back to: a macro lives in the
-/// macro table, not in the surface it was dragged from, so a refused place just leaves it held.
+/// A macro payload from `PickupMacro`, mode 8: the bare macro id (`[0xb4e2fc]`), which
+/// `PlaceAction` accepts (`0x4e62e0`). It has no source slot, so a refused place leaves it held.
 #[derive(Clone, Debug, PartialEq)]
 pub struct CursorMacro {
-    /// The 1-based macro index (1..=18 account, 19..=36 character — [`super::macros`]'s space).
+    /// The 1-based macro index: 1..=18 account, 19..=36 character.
     pub index: u32,
     pub texture: Option<String>,
 }
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
-// The one transition seam: CURSOR_UPDATE / ITEM_LOCK_CHANGED / DELETE_ITEM_CONFIRM
+// The transition events
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
-/// Queue `CURSOR_UPDATE` — fired on EVERY payload transition (pickup, place/clear, cancel,
-/// `ClearCursor`, `DeleteCursorItem`, a world-drop clear). One push per transition.
-///
-/// Also derives `ACTIONBAR_SHOWGRID`/`ACTIONBAR_HIDEGRID` (decision 0216 §7) off
-/// [`Model::cursor_grid_shown`]'s mirror against the CURRENT `model.cursor` (already the
-/// post-transition state at every call site — every caller mutates `model.cursor` before calling
-/// this): a None→Some edge (any bar-droppable arm, any surface — bags/doll/actions alike) shows the
-/// bar's drop grid, Some→None hides it, Some→Some (the action hop) touches neither, so one
-/// gesture never churns HIDE+SHOW. This is the one seam every pickup/place/clear already routes
-/// through, so no call site needs to know about grid events at all.
+/// Queue `CURSOR_UPDATE`, once per payload transition, plus a grid event when what the bars can
+/// take changes. Call it after `model.cursor` holds the new payload; an action hop keeps the grid
+/// up rather than hiding and reshowing it.
 pub(crate) fn queue_cursor_update(model: &mut Model) {
     model
         .pending_events
         .push(("CURSOR_UPDATE".to_string(), Vec::new()));
-    // The two grids are derived off DIFFERENT predicates, because the reference fires them from
-    // different places and the payload spaces do not overlap (decision 1010):
-    //
-    // - the ACTION bar's grid follows "is anything held that could land there" — every arm except
-    //   the pet one, which `PlaceAction` refuses outright, and the vendor row (mode 5): its grab
-    //   goes through the shared setter `0x4950f0`, whose `ACTIONBAR_SHOWGRID` branch is taken for
-    //   mode 7 alone (`0x495106`/`0x49513a`);
-    // - the PET bar's grid follows the pet payload alone. The reference fires `PET_BAR_SHOWGRID`
-    //   from inside the pet-action pickup builder itself (`0x494f28`), not from a shared cursor
-    //   transition — so a spell on the cursor lights the action bar's empty slots and leaves the
-    //   pet bar alone, which is also the only honest answer: you cannot drop it there.
+    // The action bar's grid shows for any payload but a pet action, which `PlaceAction` refuses,
+    // or a vendor row, whose grab `0x4950f0` fires `ACTIONBAR_SHOWGRID` for mode 7 only
+    // (`0x495106`, `0x49513a`). The reference fires it (`0x4e58c0`) only from the item, spell and
+    // macro setters and that mode-7 grab, so coins and a stabled pet show it here and not there.
+    // The pet bar's follows the pet action alone (`0x494f28`).
     let pet_held = matches!(model.cursor, Some(CursorPayload::PetAction(_)));
     let bar_held = model.cursor.is_some()
         && !pet_held
@@ -302,9 +196,7 @@ pub(crate) fn queue_cursor_update(model: &mut Model) {
     }
 }
 
-/// Queue `ITEM_LOCK_CHANGED(bag, slot)` — a pickup locking a source slot, or a place/cancel/
-/// clear/destroy unlocking it (decision 0216 §4: the engine-derived held-here lock,
-/// `container.rs`'s `GetContainerItemInfo` `held_here` check).
+/// Queue `ITEM_LOCK_CHANGED(bag, slot)` for a source slot that a pickup locks or a put-down frees.
 pub(crate) fn queue_lock_changed(model: &mut Model, bag: i64, slot: u32) {
     model.pending_events.push((
         "ITEM_LOCK_CHANGED".to_string(),
@@ -312,10 +204,8 @@ pub(crate) fn queue_lock_changed(model: &mut Model, bag: i64, slot: u32) {
     ));
 }
 
-/// Queue `DELETE_ITEM_CONFIRM(name, quality)` for an item payload dropped on the world (the popup
-/// flow transcribed from `StaticPopup.lua`, decision 0216 §3). `name` is parsed out of the link's
-/// `[...]` segment (empty string with no link); the payload is left untouched here — the popup's
-/// `OnAccept`/`OnCancel` (`DeleteCursorItem`/`ClearCursor`) own clearing it.
+/// Queue `DELETE_ITEM_CONFIRM(name, quality)` for an item dropped on the world. The payload stays
+/// held: the popup's `DeleteCursorItem` or `ClearCursor` clears it.
 fn queue_delete_item_confirm(model: &mut Model, item: &CursorItem) {
     let name = item_link_name(item.link.as_deref());
     let quality = item.quality.unwrap_or(0);
@@ -325,8 +215,7 @@ fn queue_delete_item_confirm(model: &mut Model, item: &CursorItem) {
     ));
 }
 
-/// Parse an item link's display name out of its `|h[Name]|h` segment; empty with no link or an
-/// unrecognized shape.
+/// An item link's name, from its `|h[Name]|h` segment; empty for no link or another shape.
 pub(super) fn item_link_name(link: Option<&str>) -> String {
     link.and_then(|l| l.split_once('['))
         .and_then(|(_, rest)| rest.split_once(']'))
@@ -334,15 +223,11 @@ pub(super) fn item_link_name(link: Option<&str>) -> String {
         .unwrap_or_default()
 }
 
-/// `ClearCursor()` — drops whatever the cursor holds, any arm (the right-click/ESC cancel). An
-/// item payload also un-locks its source slot; an already-empty cursor is not a transition (no
-/// event).
+/// `ClearCursor()`: drops any payload and frees an item's source slot; an empty cursor fires
+/// nothing.
 pub(crate) fn clear_cursor(model: &mut Model) {
-    // **An armed gift wrap dies with any cancel** (decision 1934), and this is the FIRST thing
-    // the reference's `ClearCursor 0x495190` does — `0x5edf10` is its opening act and it is
-    // **ungated by either parameter**, including `ClearCursor(0)`, the flavour that deliberately
-    // keeps an ordinary held item's lock. So all 70 of its call sites cancel a wrap. The paper
-    // unlocks and the cursor mode goes back to the base.
+    // Any clear first cancels an armed gift wrap, whatever its parameters (`0x495190` opens with
+    // `0x5edf10`): the wrapping paper unlocks and the cursor mode returns to the base.
     if let Some(wrap) = model.pending_wrap.take() {
         queue_lock_changed(model, wrap.bag, wrap.slot);
         model.ui_cursor = None;
@@ -359,11 +244,9 @@ pub(crate) fn clear_cursor(model: &mut Model) {
             | CursorPayload::Macro(_)
             | CursorPayload::PetAction(_)
             | CursorPayload::StablePet(_)
-            // Mode 2 — coins go back where they never left (the purse was not debited).
+            // Coins: the purse was never debited, so nothing goes back.
             | CursorPayload::Money(_)
-            // Mode 5 clears like every other non-item payload, and clearing it sends NO packet —
-            // a vendor cursor abandoned on the world, on ESC, or by the window closing costs
-            // nothing. `ClearCursor`'s own mode-5 arm is `0x49525f`.
+            // A vendor row clears with no packet (`0x49525f`).
             | CursorPayload::Merchant(_),
         ) => {
             queue_cursor_update(model);
@@ -372,23 +255,10 @@ pub(crate) fn clear_cursor(model: &mut Model) {
     }
 }
 
-/// **The SELL fork's cursor clear** — `0x494b60 SetCursorItem(0, …)`, which is *not* `ClearCursor`
-/// and differs from [`clear_cursor`] in exactly one way that a player can see.
-///
-/// Both drop the payload and fire `CURSOR_UPDATE`. `ClearCursor` also un-locks the source slot;
-/// this does **not**: `0x494b60`'s mode-1 arm is entered with `param1 = 0`, which skips `0x495420`,
-/// so the sold item's slot stays **greyed** until the server's own inventory update removes it.
-/// Leaving the lock set is the point: the item is gone from the cursor but not yet
-/// gone from the bag, and the grey is what says so.
-///
-/// Shared by the two verbs that sell off the cursor — `PickupMerchantItem`'s sell fork
-/// (`0x4fb760`) and the interact ladder's vendor arm (`0x5df5d0`) — because they are the same
-/// clear in the binary, and two copies of it is how one of them quietly grows a different
-/// behaviour. Returns the item so the caller can address the packet by its slot.
-///
-/// A non-item payload is left exactly where it was: the fork answers for **mode 1 only**
-/// (`GetCursorItem 0x494c60`), so a spell, a macro or a vendor row on the cursor is not a sale
-/// and must not be dropped by asking.
+/// The sell fork's clear, `SetCursorItem(0, …)` (`0x494b60`), shared by `PickupMerchantItem`
+/// (`0x4fb760`) and the interact ladder's vendor arm (`0x5df5d0`): unlike [`clear_cursor`] it
+/// leaves the source slot locked, grey until the server removes the item (the mode-1 arm skips
+/// `0x495420`). Any other payload is no sale and stays held (`GetCursorItem`, `0x494c60`).
 pub(crate) fn take_cursor_item_for_sale(model: &mut Model) -> Option<CursorItem> {
     let item = match model.cursor.take() {
         Some(CursorPayload::Item(item)) => item,
@@ -401,48 +271,29 @@ pub(crate) fn take_cursor_item_for_sale(model: &mut Model) -> Option<CursorItem>
     Some(item)
 }
 
-/// What the app's world pick resolves under the cursor this frame — the reference's click-time
-/// pick state `[this+0x350]` (0 = nothing / 1 = terrain / 2 = object; `0x481f60`, decisions
-/// 0571 + 0574). Fed per frame by the app ([`super::UiScript::set_world_pick`]; stays
-/// [`WorldPick::Nothing`] in tests/captures). Routes the left world-drop
-/// ([`world_drop_click`]): over an `Object` no payload drops at all (the object leg `0x492ce0`
-/// clears only the displayId-PREVIEW gate `[0xb4b41c]` — an arm benilla doesn't carry — and
-/// dispatches SELECT/INTERACT with the payload still held); over `Terrain` an ITEM drops (the
-/// `DELETE_ITEM_CONFIRM` popup via `0x5e0320`) and a spell/action payload clears silently
-/// (decision 0843's deliberate divergence — the reference keeps it there); over `Nothing` the
-/// item pops and any other payload silently clears (`0x492d30`).
+/// What is under the cursor in the world this frame: the reference's click-time pick state
+/// `[this+0x350]` (`0x481f60`). The app feeds it; tests and captures leave it `Nothing`.
 #[derive(Clone, Copy, PartialEq, Eq, Default, Debug)]
 pub enum WorldPick {
-    /// No world hit at all (sky / beyond the world) — the reference's state 0.
+    /// State 0: no world hit (the sky).
     #[default]
     Nothing,
-    /// The cursor ray hits the world (terrain/WMO/doodad) but no unit or GameObject — state 1.
+    /// State 1: terrain, a WMO or a doodad, but no unit or GameObject.
     Terrain,
-    /// A unit or GameObject is the pick — state 2.
+    /// State 2: a unit or GameObject.
     Object,
 }
 
-/// A world drop: a completed left CLICK on the game world while a payload is held — press and
-/// release both on the world (the world frame, or no frame at all where none is loaded — the
-/// caller's `over_world`, decision 2089), no drag (the byte-verified trigger, decision 0218: the
-/// client's `0x495300` runs on the WorldFrame click release only; a drag released over the world
-/// routes as a drag and keeps carrying) — routed by [`Model::world_pick`] (`0x481f60`; decisions
-/// 0571 + 0574):
+/// A left click on the world with a payload held, press and release both over the world and no
+/// drag (`0x495300`); returns whether it was consumed. Over an `Object` (`0x492ce0`) nothing
+/// drops and the click selects. Over `Terrain` (`0x492c90`) or `Nothing` (`0x492d30`) an item
+/// raises `DELETE_ITEM_CONFIRM(name, quality)` (`0x5e0320`) and stays held for the popup to clear;
+/// a spell, action, macro or pet action clears. Coins, a vendor row and a stabled pet stay held
+/// here, where the reference puts a vendor row down on every leg and clears any non-item payload
+/// over `Nothing` (`0x492e04`).
 ///
-/// - `Object`: NOTHING drops — the object leg (`0x492ce0`) keeps every real payload and
-///   dispatches SELECT instead.
-/// - `Terrain`: an item payload fires `DELETE_ITEM_CONFIRM(name, quality)` and STAYS held (the
-///   reference popup's `OnAccept` calls `DeleteCursorItem`, `OnCancel` `ClearCursor`, and its
-///   `OnUpdate` auto-hides when the cursor empties — the engine must not pre-clear); a
-///   spell/action payload clears silently — a DELIBERATE divergence (decision 0843, the
-///   director's call): the reference's terrain leg keeps a non-item payload on the left click
-///   (`0x492c90`/`0x5e0320` clear non-items only on the right button), which leaves a spell
-///   stuck to the cursor with no left-handed way off it.
-/// - `Nothing`: the item pops the same popup; any other payload clears silently (`0x492d30`'s
-///   non-item arm — here the reference agrees).
-///
-/// Returns whether the click was consumed as a drop (an empty cursor or an `Object` pick
-/// consume nothing).
+/// Deviation: on `Terrain` the reference keeps a spell, action, macro or pet action on the left
+/// button; we clear them, because otherwise a spell has no left-click way off the cursor.
 pub(crate) fn world_drop_click(model: &mut Model) -> bool {
     match (&model.cursor, model.world_pick) {
         (Some(CursorPayload::Item(item)), WorldPick::Terrain | WorldPick::Nothing) => {
@@ -466,12 +317,9 @@ pub(crate) fn world_drop_click(model: &mut Model) -> bool {
     }
 }
 
-/// `SplitContainerItem(bag, slot, count)` — a stack-split pickup (`StackSplitFrame.lua`'s
-/// `SplitStack`): only from an EMPTY cursor, onto a resolved and unlocked slot, `count >= 1`.
-/// `count` at or past the whole stack degrades to a plain whole-stack pickup (`count: None` — the
-/// client never "splits" a full stack; vmangos rejects `count == stack` as cheat). Returns
-/// whether a payload was picked up (the repaint gate, matching `pickup_container_item`'s
-/// contract).
+/// `SplitContainerItem(bag, slot, count)`: picks up `count` of an unlocked stack onto an empty
+/// cursor. A count of the whole stack or more is a plain pickup, since vmangos refuses to split a
+/// whole stack or more (`Player.cpp:11139`, `:11147`). Returns whether anything was picked up.
 pub(crate) fn split_container_item(model: &mut Model, bag: i64, slot: u32, count: i64) -> bool {
     if model.cursor.is_some() || count < 1 {
         return false;
@@ -501,9 +349,8 @@ pub(crate) fn split_container_item(model: &mut Model, bag: i64, slot: u32, count
     true
 }
 
-/// `DeleteCursorItem()` — the delete popup's `OnAccept` (decision 0216 §3): an Item payload
-/// queues its `(bag, slot, count)` destroy (`count == 0` = the whole stack) and clears; any other
-/// payload (or an empty cursor) is a no-op — the client's contract for a stale/mismatched confirm.
+/// `DeleteCursorItem()`, the delete popup's accept: a held item queues its `(bag, slot, count)`
+/// destroy, count 0 for the whole stack, and clears; anything else is a no-op.
 pub(crate) fn delete_cursor_item(model: &mut Model) {
     let Some(CursorPayload::Item(item)) = &model.cursor else {
         return;
@@ -522,9 +369,7 @@ pub(crate) fn delete_cursor_item(model: &mut Model) {
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
 impl super::UiScript {
-    /// The item currently held on the cursor, or `None` — the Item-arm projection of
-    /// [`UiScript::cursor_payload`], kept for the app's existing extract/sound watchers
-    /// (`ui_script/extract.rs`, `sound/ui.rs`), which only ever cared about items.
+    /// The held item, if the payload is one.
     pub fn cursor_item(&self) -> Option<CursorItem> {
         match self.model_ref().cursor.clone() {
             Some(CursorPayload::Item(item)) => Some(item),
@@ -532,36 +377,28 @@ impl super::UiScript {
         }
     }
 
-    /// The full cursor payload, any arm — what the app's hardware-cursor drive
-    /// (`benilla::cursor`) and capture stand-in draw, and what the world-click consumers gate on.
+    /// The cursor payload, any arm.
     pub fn cursor_payload(&self) -> Option<CursorPayload> {
         self.model_ref().cursor.clone()
     }
 
-    /// Feed: what the app's world pick resolves under the cursor this frame
-    /// ([`Model::world_pick`], decisions 0571 + 0574) — routes [`world_drop_click`]'s legs
-    /// (object keeps everything, terrain drops items only, nothing drops any arm).
+    /// Feed the world pick under the cursor this frame ([`WorldPick`]).
     pub fn set_world_pick(&mut self, pick: WorldPick) {
         self.model_mut().world_pick = pick;
     }
 
-    /// The sell fork's take-and-clear, for the app-side interact ladder — see
-    /// [`take_cursor_item_for_sale`]. `None` for an empty cursor or any non-item payload, and in
-    /// that case the payload is left untouched.
+    /// [`take_cursor_item_for_sale`], for the app's interact ladder.
     pub fn take_cursor_item_for_sale(&mut self) -> Option<CursorItem> {
         take_cursor_item_for_sale(&mut self.model_mut())
     }
 
-    /// `ClearCursor()`'s Rust seam — drops whatever the cursor holds, any arm, silently (fires
-    /// `CURSOR_UPDATE` + the item source un-lock, exactly the Lua `ClearCursor`). The app's
-    /// world-click router calls it for a clean RIGHT-click over empty world (`0x492c90`/
-    /// `0x492d30`'s action-4 leg: `ClearCursor 0x495190(1,1)` unconditionally — decision 0571).
+    /// `ClearCursor()` from Rust, which the app calls on a right-click over empty world: both
+    /// reference legs there (`0x492c90`, `0x492d30`) call `ClearCursor(1, 1)` (`0x495190`).
     pub fn clear_cursor_payload(&mut self) {
         clear_cursor(&mut self.model_mut());
     }
 
-    /// Test-only: set the cursor payload directly, bypassing every Lua binding — drives the
-    /// Spell/Action arms in tests before a spellbook/action-bar slice can produce them.
+    /// Test-only: set the payload directly, bypassing the Lua bindings.
     #[cfg(test)]
     pub(crate) fn set_cursor_for_test(&mut self, payload: CursorPayload) {
         self.model_mut().cursor = Some(payload);
@@ -569,65 +406,53 @@ impl super::UiScript {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
-// Lua globals: GetCursorInfo / CursorHasItem / CursorHasSpell / ClearCursor / SplitContainerItem /
-// DeleteCursorItem — all top-level (the real client's `GetCursorInfo` &c. are not namespaced).
+// The targeting cursor's item pick and the enchant confirms
+// ─────────────────────────────────────────────────────────────────────────────────────────────
 impl super::UiScript {
-    /// Arm (or disarm) **the targeting cursor's item half** — the engine mirror of
-    /// `TargetingWantsItem 0x6e6330`. While armed, a bag click ([`super::container`]) or a
-    /// paper-doll click ([`doll::pickup_inventory_item`]) queues its `(bag, slot)` into the pick
-    /// list instead of running the cursor gesture, exactly as the reference's two pickup
-    /// functions reroute (`0x4f9b30` @ `4f9c54`, `0x4c7300` @ `4c76df`). The app owns the word:
-    /// it arms on a resolved item-targeted cast and clears on the bind, a cancel, or ESC
-    /// (decision 0923 — before it, this was the CraftFrame's private enchant pick).
+    /// Arm or disarm the targeting cursor's item half (`TargetingWantsItem`, `0x6e6330`): while
+    /// armed, a bag or paper-doll click queues its `(bag, slot)` as a pick instead of picking up,
+    /// as the reference's two pickups do (`0x4f9b30` at `0x4f9c54`, `0x4c7300` at `0x4c76df`).
     pub fn set_item_pick_armed(&mut self, armed: bool) {
         self.model_mut().item_pick_armed = armed;
     }
 
-    /// Push what `SpellCanTargetUnit` answers — whether the standing targeting word could bind a
-    /// unit at all (see [`crate::script::Model::spell_can_target_unit`]).
+    /// Push what `SpellCanTargetUnit` answers: whether the armed targeting cast can take a unit.
     pub fn set_spell_can_target_unit(&mut self, can: bool) {
         self.model_mut().spell_can_target_unit = can;
     }
 
-    /// Drain the `(bag, slot)` clicks the armed item half consumed since the last call. A doll
-    /// click reports as [`EQUIPMENT_BAG`] + its 1-based inventory slot — the ONE bag space, so
-    /// the app resolves both seams with one lookup.
+    /// Drain the `(bag, slot)` picks since the last call; a paper-doll pick reports as
+    /// [`EQUIPMENT_BAG`] and its 1-based inventory slot.
     pub fn take_item_picks(&mut self) -> Vec<(i64, u32)> {
         std::mem::take(&mut self.model_mut().item_picks)
     }
 
-    /// Drain the enchant-confirm popups' answers since the last call (decision 0928). Both are
-    /// answers to the *same* pick the app parked, which is why they share one queue.
+    /// Drain the enchant-confirm answers since the last call; both answer the pick the app parked.
     pub fn take_enchant_confirms(&mut self) -> Vec<EnchantConfirm> {
         std::mem::take(&mut self.model_mut().enchant_confirms)
     }
 }
 
-/// A Yes on one of the enchant-apply confirms — the two Lua globals `StaticPopup.lua` calls from
-/// `BIND_ENCHANT`'s and `REPLACE_ENCHANT`'s `OnAccept` (decision 0928). Plain intents; the app
-/// holds the item guid they answer for (the reference's `0xb4e3c0/0xb4e3c4`).
+/// A Yes on an enchant-apply confirm (`StaticPopup.lua:1245`, `:1257`); the app holds the item
+/// guid it answers for (the reference's `0xb4e3c0`/`0xb4e3c4`).
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum EnchantConfirm {
-    /// `BindEnchant()` — `0x48d2e0`, which re-invokes the enchant-apply gate `0x495d60` over the
-    /// parked guid with its "already confirmed" parameter set. So this is NOT a send: the gate
-    /// runs again and may raise the *replace* popup next.
+    /// `BindEnchant()` (`0x48d2e0`): reruns the enchant-apply gate `0x495d60` as already
+    /// confirmed, so it may raise the replace popup next rather than cast.
     Bind,
-    /// `ReplaceEnchant()` — `0x48d300`, which re-resolves the parked guid and calls the ordinary
-    /// target binder `0x6e5b40` **directly**, skipping the gate. There is no
-    /// `CMSG_REPLACE_ENCHANT` in 5875: the popup is pure client-side gating over the same cast.
+    /// `ReplaceEnchant()` (`0x48d300`): binds the parked guid through `0x6e5b40`, skipping the
+    /// gate. There is no replace packet: the popup only gates the same cast.
     Replace,
 }
 
-// The paper-doll globals (`PickupInventoryItem` &c.) install from [`doll`]; the action-bar
-// globals (`PickupAction`/`PlaceAction`) install from [`bar`].
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// Lua globals
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // BindEnchant() / ReplaceEnchant() — the two enchant-confirm popups' OnAccept (StaticPopup.lua
-    // `BIND_ENCHANT` l.1240 and `REPLACE_ENCHANT` l.1252). Both queue an intent the app answers
-    // over its parked item guid; neither sends anything from here.
+    // `BindEnchant()`, `ReplaceEnchant()`: queue an intent for the app; nothing is sent from here.
     for (name, answer) in [
         ("BindEnchant", EnchantConfirm::Bind),
         ("ReplaceEnchant", EnchantConfirm::Replace),
@@ -642,10 +467,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // GetCursorInfo() → per arm: Item ("item", itemID, itemLink); Spell ("spell", book_slot,
-    // book_type, spell_id) — the Era shape; Action ("action", src_slot). Empty ⇒ all nils. A
-    // fixed 4-return shape (padded with nil past each arm's own fields) so one function signature
-    // covers every arm; callers destructuring fewer names simply ignore the tail.
+    // `GetCursorInfo()` is not a 1.12 verb. It answers ("item", id, link), ("spell", book slot,
+    // book, spell id), ("action", slot), ("macro", index) or ("petaction", slot), padded with nil
+    // to four values; any other payload, or none, is four nils.
     g.set(
         "GetCursorInfo",
         lua.create_function(|lua, ()| {
@@ -675,40 +499,24 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     Value::Nil,
                     Value::Nil,
                 )),
-                // The Era `GetCursorInfo` shape for a macro: the kind word + the macro index.
                 Some(CursorPayload::Macro(m)) => Ok((
                     Value::String(lua.create_string("macro")?),
                     Value::Integer(i64::from(m.index)),
                     Value::Nil,
                     Value::Nil,
                 )),
-                // The pet arm follows the Action arm's shape — kind word + the slot it came from.
-                // Nothing in the shipped 1.12 UI reads it (the pet bar's own drag never asks what
-                // it is carrying); it is here so the ONE payload space stays fully describable.
                 Some(CursorPayload::PetAction(p)) => Ok((
                     Value::String(lua.create_string("petaction")?),
                     Value::Integer(i64::from(p.src_slot)),
                     Value::Nil,
                     Value::Nil,
                 )),
-                // Mode 10 — the stabled-pet grab (decision 1677). Reported as nothing: the
-                // reference's `GetCursorInfo` arms are not carved for it, the stable window never
-                // asks, and inventing a type string would put a guess where an addon could read it.
                 Some(CursorPayload::StablePet(_)) => {
                     Ok((Value::Nil, Value::Nil, Value::Nil, Value::Nil))
                 }
-                // Mode 2 — coins (1962). Reported as nothing for the same reason: the money arm
-                // of `GetCursorInfo` is not carved, and `GetCursorMoney` is the reference's own
-                // way of asking. The same gap closes once that arm is carved.
                 Some(CursorPayload::Money(_)) => {
                     Ok((Value::Nil, Value::Nil, Value::Nil, Value::Nil))
                 }
-                // Mode 5 — the vendor grab. Reported as nothing, for the same reason and with a
-                // stronger warrant: **no registered binding in the 5875 image exposes mode 5 to
-                // Lua at all.** `CursorHasItem`, `CursorHasSpell`, `CursorHasMoney` and
-                // `CursorCanGoInSlot` are each nil for it, by census. A vendor cursor is invisible
-                // from Lua and that invisibility is load-bearing — it is what keeps all thirteen
-                // stock `CursorHasItem()` gates closed while one is held.
                 Some(CursorPayload::Merchant(_)) => {
                     Ok((Value::Nil, Value::Nil, Value::Nil, Value::Nil))
                 }
@@ -770,8 +578,7 @@ mod tests {
     use super::{CursorAction, CursorItem, CursorPayload, CursorSpell};
     use crate::script::UiScript;
 
-    /// A one-item, one-slot backpack (mirrors `container::tests::backpack` closely enough for
-    /// these payload-shape tests, which don't need its in-flight slot).
+    /// A backpack holding a five-stack in slot 1.
     fn one_item_backpack() -> crate::script::container::ContainerState {
         let mut slots = std::collections::HashMap::new();
         slots.insert(
@@ -803,24 +610,14 @@ mod tests {
         }
     }
 
-    /// **The sell clear is not `ClearCursor`** — decision 1914, and the difference is the one a
-    /// player sees.
-    ///
-    /// `0x494b60 SetCursorItem(0, …)` drops the payload and fires `CURSOR_UPDATE`, but its mode-1
-    /// arm skips `0x495420` with `param1 = 0`, so it never un-locks the source slot: the item is
-    /// off the cursor and the bag slot stays **greyed** until the server's inventory update takes
-    /// it away. `ClearCursor` un-locks. Firing `ITEM_LOCK_CHANGED` here would un-grey a slot whose
-    /// item is still sitting in it awaiting the server, which is the visible wrong.
-    ///
-    /// The second half is the blast radius: the fork answers for **mode 1 only**, so asking a
-    /// spell or a vendor row must not drop it.
+    /// `SetCursorItem(0, …)` (`0x494b60`) skips `ClearCursor`'s unlock (`0x495420`) and takes only
+    /// a held item.
     #[test]
     fn the_sell_clear_keeps_the_source_slot_locked() {
         let mut s = UiScript::new().unwrap();
         s.set_container(0, Some(one_item_backpack()));
 
-        // Pick the item up, then drain whatever the pickup queued so the assert below sees only
-        // what the SELL clear itself fires.
+        // Drain the pickup's events so only the sell clear's remain.
         s.eval::<()>("PickupContainerItem(0, 1)").unwrap();
         assert!(s.cursor_item().is_some(), "the pickup did not take");
         s.model_mut().pending_events.clear();
@@ -848,7 +645,6 @@ mod tests {
              `SetCursorItem(0, …)`'s) — got {fired:?}"
         );
 
-        // Mode 1 only: every other payload is left exactly where it was.
         let mut s = UiScript::new().unwrap();
         s.set_cursor_for_test(CursorPayload::Spell(CursorSpell {
             book_slot: 1,
@@ -871,14 +667,12 @@ mod tests {
     fn get_cursor_info_and_has_checks_per_arm() {
         let mut s = UiScript::new().unwrap();
 
-        // Empty: all nils, both Has* false.
         assert!(s
             .eval::<bool>("local k = GetCursorInfo() return k == nil")
             .unwrap());
         assert!(!s.eval::<bool>("return CursorHasItem()").unwrap());
         assert!(!s.eval::<bool>("return CursorHasSpell()").unwrap());
 
-        // Item arm.
         s.set_cursor_for_test(CursorPayload::Item(CursorItem {
             bar_placeable: true,
             bag: 0,
@@ -900,7 +694,6 @@ mod tests {
         assert!(s.eval::<bool>("return CursorHasItem()").unwrap());
         assert!(!s.eval::<bool>("return CursorHasSpell()").unwrap());
 
-        // Spell arm — the Era 4-tuple shape.
         s.set_cursor_for_test(CursorPayload::Spell(CursorSpell {
             passive: false,
             book_slot: 3,
@@ -920,7 +713,6 @@ mod tests {
         assert!(!s.eval::<bool>("return CursorHasItem()").unwrap());
         assert!(s.eval::<bool>("return CursorHasSpell()").unwrap());
 
-        // Action arm.
         s.set_cursor_for_test(CursorPayload::Action(CursorAction {
             src_slot: 12,
             kind: 0,
@@ -950,10 +742,7 @@ mod tests {
         assert!(s.cursor_payload().is_none());
     }
 
-    /// The world-drop pick routing (decisions 0571 + 0574 — `0x481f60`, amended by 0843): a
-    /// spell/action payload clears silently on BOTH empty-world legs — terrain included, the
-    /// 0843 divergence (the reference keeps it on terrain; the director wants the left click to
-    /// dismiss) — while an item keeps its byte-faithful popup flow.
+    /// Clearing a spell on terrain is the deviation documented on `world_drop_click`.
     #[test]
     fn world_drop_terrain_and_nothing_both_clear_a_spell_payload() {
         use super::{world_drop_click, WorldPick};
@@ -977,7 +766,6 @@ mod tests {
             );
         }
 
-        // An item drops (the popup path) on BOTH empty-world legs, never over an object.
         let item = CursorPayload::Item(CursorItem {
             bar_placeable: true,
             bag: 0,
diff --git a/crates/benilla-ui/src/script/cursor/bag_verbs.rs b/crates/benilla-ui/src/script/cursor/bag_verbs.rs
index c7edddb2..ad17b031 100644
--- a/crates/benilla-ui/src/script/cursor/bag_verbs.rs
+++ b/crates/benilla-ui/src/script/cursor/bag_verbs.rs
@@ -1,27 +1,4 @@
-//! The three BAG-SLOT verbs — `PutItemInBag`, `PutItemInBackpack`, `PickupBagFromSlot`.
-//!
-//! CARVED, not inferred. The three findings that shape everything below:
-//!
-//! 1 · **`PutItemInBackpack()` IS `PutItemInBag(0xFF)`.** `0x4c7ed0` is a ten-byte thunk —
-//!   `mov ecx,0xff` / `jmp 0x4c7c00` — so there is one worker here too, and only the destination
-//!   differs. The `0xFF` path is *not* "bag 0": the destination guid is the player's own, which
-//!   makes the empty-slot leg unreachable and `0x4c7d3e je 0x4c7e0c` skip the swap fork outright,
-//!   so a bag dropped on the backpack button is auto-stored INTO it, never swapped with it.
-//!
-//! 2 · **`PutItemInBag` forks three ways**, on the state of the target slot and the held object:
-//!   empty slot → the paper-doll handler equips the held bag ([`super::doll::pickup_inventory_item`],
-//!   which is `0x4c7300` — the same function the byte path calls); occupied + the held object is a
-//!   CONTAINER → a bag↔bag swap; occupied + an ordinary item → auto-store into that container's
-//!   contents, with the client picking no destination slot at all.
-//!
-//! 3 · **The return value answers "was this click consumed as a placement against an existing
-//!   container?", not "did something get placed".** It is the Lua **number `1`**, never the boolean
-//!   `true` — and it is `nil` on the empty-slot leg that really does equip the bag, and whenever
-//!   the cursor is empty. That last one is the whole reason a plain left-click opens a bag:
-//!   `BagSlotButton_OnClick`'s `if ( not hadItem ) then ToggleBag(...)`.
-//!
-//! `PickupBagFromSlot` has its own, much shorter worker (`0x4c7b00`) and is a *destructive*
-//! pickup: it drops whatever the cursor already held before it looks at the slot.
+//! The bag-slot verbs: `PutItemInBag`, `PutItemInBackpack` and `PickupBagFromSlot`.
 
 use mlua::{Lua, MultiValue, Value};
 
@@ -31,21 +8,9 @@ use crate::script::Model;
 use super::{clear_cursor, queue_cursor_update, queue_lock_changed, CursorItem, CursorPayload};
 use super::{doll::pickup_inventory_item, EQUIPMENT_BAG};
 
-/// The live-API inventory ids the two verbs' shared argument reader (`0x4c8520`) accepts, minus
-/// what each binding's own floor gate (`cmp ecx,0x13; jl` on the 0-based value — `0x4c8f1f`,
-/// `0x4c8fbf`) then cuts off. In the space a Lua caller writes:
-///
-/// | band | what it is |
-/// |---|---|
-/// | 20..=23 | the four EQUIPPED bag slots (`Bag0Slot`..`Bag3Slot`) |
-/// | 40..=63 | the bank's 24 generic slots |
-/// | 64..=69 | the six BANK BAG slots |
-/// | 82..=113 | the keyring |
-///
-/// The reader rejects the backpack's own item slots (24..=39) and buyback (70..=81); the floor
-/// cuts equipment (1..=19) and ammo. **So a macro may legally hand either verb a bank item slot
-/// or a keyring slot, and nothing downstream catches it** — the reference sends a packet the
-/// server refuses. See [`autostore_container`] for the one place benilla is tighter, and why.
+/// The ids `PutItemInBag` and `PickupBagFromSlot` take: what their argument reader (`0x4c8520`)
+/// accepts above each floor gate (`0x4c8f1f`, `0x4c8fbf`), so the equipped bags 20-23, the
+/// bank's slots 40-63, its bag slots 64-69 and the keyring 82-113.
 fn accepts(live: u32) -> bool {
     (20..=23).contains(&live)
         || (40..=63).contains(&live)
@@ -53,19 +18,9 @@ fn accepts(live: u32) -> bool {
         || (82..=113).contains(&live)
 }
 
-/// The live-API **container** id a bag slot's own inventory id names — the inverse of
-/// `ContainerIDToInventoryID` (`crate::script::container`'s own table): 20..=23 → 1..=4, 64..=69 →
-/// 5..=10. `None` for an inventory id that is not a bag slot.
-///
-/// **This is the one place benilla's gate is tighter than the engine's**, and it is deliberate.
-/// [`accepts`] admits the bank's generic slots and the keyring because the reference's argument
-/// reader does; the reference then auto-stores *into* them, sending
-/// `CMSG_AUTOSTORE_BAG_ITEM(…, dstbag = live − 1)` for a `dstbag` that names no container, which
-/// the server refuses (`EQUIP_ERR_ITEM_DOESNT_GO_TO_SLOT`). benilla has no container id to name
-/// there, so [`put_item_in_bag`]'s auto-store leg answers `nil` and sends nothing. No shipped
-/// window produces the call — the reference's own two callers are `BagSlotButton_OnClick` and
-/// `BankFrameItemButtonBag_OnClick`, both of which pass a bag slot — and a refusal the player
-/// never sees is not worth a packet.
+/// The live container id of a bag slot, the inverse of `ContainerIDToInventoryID`. Deviation:
+/// an auto-store into a bank item or keyring slot sends nothing, because no container id names
+/// it and no stock caller passes one; the reference sends it and the server refuses.
 fn autostore_container(live: u32) -> Option<i64> {
     match live {
         20..=23 => Some(i64::from(live) - 19),
@@ -74,34 +29,23 @@ fn autostore_container(live: u32) -> Option<i64> {
     }
 }
 
-/// `Bag0Slot` — the first of the four EQUIPPED bag slots, and the tell that an item is a
-/// container. See [`is_container`].
+/// `Bag0Slot`, the first equipped bag slot: only a container names it in `equip_slots`.
 const BAG0_SLOT: u8 = 20;
 
-/// The six BANK BAG slots' live-API ids (`BankButtonIDToInvSlotID(1..6, isBag)`).
+/// The six bank bag slots' ids (`BankButtonIDToInvSlotID(1..6, isBag)`).
 pub(super) const BANK_BAG_INV_SLOTS: std::ops::RangeInclusive<u32> = 64..=69;
 
-/// Whether the held item is a CONTAINER — the fork the reference reads straight off the object
-/// (`0x4c7dc4 shr eax,2; test al,1`, `OBJECT_FIELD_TYPE`'s `TYPEMASK_CONTAINER` bit).
-///
-/// benilla has no object-type field on a cursor payload, and asks the equivalent question of the
-/// data it does carry: `equip_slots` is the server's own `Player::FindEquipSlot`, and
-/// `INVTYPE_BAG` is the ONLY inventory type in that table that yields the bag slots
-/// (`ui_items::find_equip_slot`, arm 18). So "this item names Bag0Slot as a place it could be
-/// worn" and "this item is a container" are the same set.
+/// Whether the held item is a container, the reference's `TYPEMASK_CONTAINER` test (`0x4c7dc4`):
+/// only `INVTYPE_BAG` maps to the bag slots in `FindEquipSlot`, so no other item names Bag0Slot.
 fn is_container(item: &CursorItem) -> bool {
     item.equip_slots.contains(&BAG0_SLOT)
 }
 
-/// Whether the held item may be dropped on doll slot `id` — the fit rule, one band wider than
-/// `equip_slots` alone.
-///
-/// The four EQUIPPED bag slots are in `equip_slots` because the server's `FindEquipSlot` names
-/// them; the six BANK BAG slots never are, because `FindEquipSlot` does not know about the bank
-/// (it is `CanBankItem`'s business there). The client's own predicate `CursorCanGoInSlot`
-/// (`0x5ea720`) is 0216 §5's unresolved residual, so the rule here is stated from the observable:
-/// a bank bag slot takes a container and nothing else, and the server's `CanBankItem` referees
-/// either way through `SMSG_INVENTORY_CHANGE_FAILURE`.
+/// Whether the held item may go in doll slot `id`: its `equip_slots`, or a bank bag slot for a
+/// container, which `FindEquipSlot` never names. The reference's fit check behind
+/// `CursorCanGoInSlot` (`0x5ea720`) passes any item at a bank bag slot, as `IsValidForSlot`
+/// answers 1 for every 0-based slot from 23 (`0x5da215`); the server's `CanBankItem` referees
+/// either way.
 pub(super) fn fits_slot(item: &CursorItem, id: u32) -> bool {
     if BANK_BAG_INV_SLOTS.contains(&id) {
         return is_container(item);
@@ -109,17 +53,16 @@ pub(super) fn fits_slot(item: &CursorItem, id: u32) -> bool {
     u8::try_from(id).is_ok_and(|id| item.equip_slots.contains(&id))
 }
 
-/// `PutItemInBag(inventorySlot)` — module doc, finding 2. Returns the reference's own `1`/`nil`
-/// as a bool the binding maps ("was this click consumed as a placement against an existing
-/// container?", NOT "did something get placed").
+/// `PutItemInBag(inventorySlot)` (`0x4c7c00`): true (the reference's `1`) when the click was
+/// consumed against an occupied slot, else false (nil). An empty cursor's nil is what lets
+/// `BagSlotButton_OnClick` open the bag.
 pub(super) fn put_item_in_bag(model: &mut Model, live: u32) -> bool {
     if !accepts(live) {
         return false;
     }
-    // `0x4c7ce4 je 0x4c7eaf` — an empty cursor is the FIRST thing tested, and it answers `nil`
-    // with nothing sent. A Spell/Action/Macro/PetAction/StablePet payload is not the client's
-    // item cursor either, and takes the same exit: this is what leaves a plain click free to open
-    // the bag.
+    // An empty or non-item cursor answers nil and sends nothing. At an occupied slot the
+    // reference clears such a cursor (`0x4c7ce4`, `0x4c7eaf`), buying a held vendor row first
+    // (`0x4c7e66`).
     let Some(CursorPayload::Item(held)) = model.cursor.clone() else {
         return false;
     };
@@ -129,16 +72,13 @@ pub(super) fn put_item_in_bag(model: &mut Model, live: u32) -> bool {
         .is_some();
 
     if !occupied {
-        // Leg 1 — the EMPTY slot. The byte path calls `0x4c7300`, the paper-doll handler, which
-        // is `pickup_inventory_item`'s place arm here: the fit predicate, the queued move, the
-        // clear and both events, all of it already the doll's. `0x4c7cae xor eax,eax` is
-        // unconditional, so this answers `nil` whether or not the bag actually went in.
+        // An empty slot: the doll handler equips the bag (`0x4c7300`), and the answer is nil
+        // whether or not it went in (`0x4c7cae xor eax,eax`).
         pickup_inventory_item(model, live);
         return false;
     }
 
-    // A pure cancel: the held item IS this bag (put back where it came from). Sends nothing, and
-    // answers `1` — the click WAS consumed.
+    // The held bag is this slot's own: a cancel that sends nothing and answers 1.
     if held.bag == EQUIPMENT_BAG && held.slot == live {
         model.cursor = None;
         queue_cursor_update(model);
@@ -147,12 +87,8 @@ pub(super) fn put_item_in_bag(model: &mut Model, live: u32) -> bool {
     }
 
     if is_container(&held) || held.bag == EQUIPMENT_BAG {
-        // Leg 2 — bag↔bag SWAP (`0x5e0c40`, `CMSG_SWAP_ITEM`/`CMSG_SWAP_INV_ITEM`). "Came from a
-        // bag equipment slot" is the reference's second entry to this fork, hence the `||`. The
-        // existing move drain already picks the opcode off the two endpoints.
-        //
-        // A split carry cannot swap: half a stack is not a bag. The reference reaches its SPLIT
-        // sender only from the auto-store leg, so this falls through to a refusal, kept.
+        // A swap (`0x5e0c40`); an item from a bag equipment slot enters this fork too, hence the
+        // `||`. A split stack cannot swap and stays held: the reference splits only when storing.
         if held.count.is_none() {
             model.cursor = None;
             model.container_moves.push(ContainerMove {
@@ -170,9 +106,8 @@ pub(super) fn put_item_in_bag(model: &mut Model, live: u32) -> bool {
         return true;
     }
 
-    // Leg 3 — AUTO-STORE into the container's contents (`CMSG_AUTOSTORE_BAG_ITEM 0x10B`, or
-    // `CMSG_SPLIT_ITEM 0x10E` for a split carry). **The client never picks a destination slot**:
-    // AUTOSTORE carries none and SPLIT carries the literal `0xFF`.
+    // Store into the bag: `CMSG_AUTOSTORE_BAG_ITEM` (`0x10B`), or `CMSG_SPLIT_ITEM` (`0x10E`) for
+    // a split. The client picks no slot: the store carries none, the split carries `0xFF`.
     let Some(dst_bag) = autostore_container(live) else {
         return false;
     };
@@ -188,9 +123,9 @@ pub(super) fn put_item_in_bag(model: &mut Model, live: u32) -> bool {
     true
 }
 
-/// `PutItemInBackpack()` — module doc, finding 1: the same worker with the destination fixed to
-/// the player's own guid, which makes the empty-slot and swap legs unreachable. Everything that
-/// lands here auto-stores into the backpack.
+/// `PutItemInBackpack()`, a thunk to `PutItemInBag(0xFF)` (`0x4c7ed0`) whose target is the
+/// player's own guid: the empty-slot leg is unreachable and `0x4c7d3e` skips the swap, so even a
+/// bag is stored into the backpack.
 pub(super) fn put_item_in_backpack(model: &mut Model) -> bool {
     let Some(CursorPayload::Item(held)) = model.cursor.clone() else {
         return false;
@@ -207,23 +142,10 @@ pub(super) fn put_item_in_backpack(model: &mut Model) -> bool {
     true
 }
 
-/// `PickupBagFromSlot(inventorySlot)` — a **destructive** pickup, not a restricted
-/// `PickupInventoryItem` (`0x4c7b00`). Returns nothing.
-///
-/// Three things it does that the doll pickup does not:
-///
-/// · **`ClearCursor(1, 1)` unconditionally, before it looks at anything** (`0x4c7b79`) — whatever
-///   was held is dropped and unlocked, even if the slot then turns out to be empty.
-/// · Resolves the occupant with **`TYPEMASK_CONTAINER`** (`0x4c7bb3 mov ecx,4`, where
-///   `PickupInventoryItem` uses `ecx = 2`). This is what makes it silently no-op at the bank item
-///   slots and the keyring that its floor-only gate still admits: those hold ordinary items.
-/// · Has **no place/swap path at all**, and none of `0x4c7300`'s targeting reroute, repair-cursor
-///   leg or slot-`−1` ammo leg.
-///
-/// There is **no client-side "a bag must be empty to be moved" rule** — both workers were read end
-/// to end and neither inspects container occupancy. That refusal is the server's
-/// `Player::CanUnequipItem` (`EQUIP_ERR_CAN_ONLY_DO_WITH_EMPTY_BAGS`), arriving as
-/// `SMSG_INVENTORY_CHANGE_FAILURE`.
+/// `PickupBagFromSlot(inventorySlot)` (`0x4c7b00`): clears the cursor before it looks at the slot,
+/// where the reference clears only a held item (`0x4c7b70`, `0x4c7b79`); takes only a container
+/// (`0x4c7bb3`), and never places or swaps. The client has no empty-bag rule: the server refuses
+/// with `EQUIP_ERR_CAN_ONLY_DO_WITH_EMPTY_BAGS`.
 pub(super) fn pickup_bag_from_slot(model: &mut Model, live: u32) {
     if !accepts(live) {
         return;
@@ -244,8 +166,6 @@ pub(super) fn pickup_bag_from_slot(model: &mut Model, live: u32) {
             bar_placeable: s.bar_placeable,
             equip_slots: s.equip_slots.clone(),
         })
-        // TYPEMASK_CONTAINER, applied after the view is built so the predicate reads off the same
-        // `equip_slots` every other bag decision here does ([`is_container`]).
         .filter(is_container);
     if let Some(item) = picked {
         model.cursor = Some(CursorPayload::Item(item));
@@ -254,14 +174,11 @@ pub(super) fn pickup_bag_from_slot(model: &mut Model, live: u32) {
     }
 }
 
-/// Register the three verbs — top-level globals, like every other cursor binding.
+/// Register the three verbs as globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // The number `1` or nil — `0x6f3810` writes Lua tag 3 (number) with the IEEE-754 double
-    // `0x3FF0000000000000`; tag 1 (boolean) appears in neither body. FrameXML only ever tests it
-    // for truthiness, but an addon that compares against `true` must see what the reference gives
-    // it.
+    // The number 1 or nil, never a boolean: `0x6f3810` pushes Lua tag 3, a number.
     fn consumed(yes: bool) -> mlua::Result<MultiValue> {
         Ok(MultiValue::from_vec(vec![if yes {
             Value::Number(1.0)
@@ -310,8 +227,7 @@ mod tests {
         InventorySlots, UiScript,
     };
 
-    /// An item that IS a bag — `equip_slots` is `find_equip_slot(INVTYPE_BAG)`, the only inventory
-    /// type in that table that names Bag0Slot, which is how [`super::is_container`] reads it.
+    /// An item that is a bag: `equip_slots` is `find_equip_slot(INVTYPE_BAG)`.
     fn bag_slot_view(item_id: u32) -> InvSlotView {
         InvSlotView {
             item_id,
@@ -359,9 +275,6 @@ mod tests {
         bags
     }
 
-    /// Finding 3, the one every caller depends on: an empty cursor answers **nil** and sends
-    /// nothing, which is what leaves `BagSlotButton_OnClick`'s `if ( not hadItem ) then
-    /// ToggleBag(...)` free to open the bag.
     #[test]
     fn an_empty_cursor_answers_nil_and_sends_nothing() {
         let mut s = UiScript::new().unwrap();
@@ -373,9 +286,7 @@ mod tests {
         assert!(s.take_bag_autostores().is_empty());
     }
 
-    /// Leg 1 — the EMPTY slot equips the held bag, and answers **nil** while doing it
-    /// (`0x4c7cae xor eax,eax` is unconditional). That pairing is the reference's, not a slip:
-    /// the click both puts the bag in and opens the window it just created.
+    /// The nil after the equip is the reference's (`0x4c7cae`), so the same click opens the bag.
     #[test]
     fn an_empty_bag_slot_equips_the_held_bag_and_still_answers_nil() {
         let mut s = UiScript::new().unwrap();
@@ -398,9 +309,6 @@ mod tests {
         assert!(s.take_bag_autostores().is_empty(), "an equip, not a store");
     }
 
-    /// Leg 1's fit rule: a bank bag slot takes a CONTAINER and nothing else. An ordinary item
-    /// dropped on an empty bank bag slot is refused and kept — the server's `CanBankItem` would
-    /// refuse it anyway, and there is nothing to auto-store into.
     #[test]
     fn an_empty_bag_slot_refuses_an_ordinary_item() {
         let mut s = UiScript::new().unwrap();
@@ -413,7 +321,6 @@ mod tests {
         assert!(s.take_bag_autostores().is_empty());
     }
 
-    /// Leg 2 — an OCCUPIED slot plus a held container is a bag↔bag swap, and answers `1`.
     #[test]
     fn an_occupied_bag_slot_swaps_with_a_held_bag_and_answers_one() {
         let mut s = UiScript::new().unwrap();
@@ -435,8 +342,6 @@ mod tests {
         );
     }
 
-    /// Leg 3 — an OCCUPIED slot plus an ORDINARY item auto-stores INTO that bag. The intent
-    /// carries no destination slot, because the wire has none.
     #[test]
     fn an_occupied_bag_slot_auto_stores_an_ordinary_item() {
         let mut s = UiScript::new().unwrap();
@@ -452,15 +357,13 @@ mod tests {
             vec![BagAutoStore {
                 src_bag: 0,
                 src_slot: 2,
-                // Live container id 5 — bank bag slot 1 (`ContainerIDToInventoryID(5) == 64`).
+                // Container 5 is bank bag slot 1 (`ContainerIDToInventoryID(5) == 64`).
                 dst_bag: 5,
                 count: None,
             }]
         );
     }
 
-    /// Finding 1 — `PutItemInBackpack()` skips both the empty-slot and the swap legs outright: a
-    /// held BAG dropped on the backpack button is auto-stored, never swapped with it.
     #[test]
     fn the_backpack_button_always_auto_stores_even_a_bag() {
         let mut s = UiScript::new().unwrap();
@@ -480,9 +383,6 @@ mod tests {
         );
     }
 
-    /// Finding 3's literal shape: the reference pushes the Lua **number** `1` (`0x6f3810` writes
-    /// tag 3 with the IEEE-754 double `0x3FF0…`), never the boolean `true`. FrameXML only tests
-    /// truthiness; an addon comparing against `true` must see what the reference gives it.
     #[test]
     fn the_answer_is_the_number_one_not_the_boolean_true() {
         let mut s = UiScript::new().unwrap();
@@ -494,8 +394,6 @@ mod tests {
             .unwrap());
     }
 
-    /// The floor gate (`cmp ecx,0x13; jl`): equipment slots and ammo are below it, so the verb
-    /// never reaches the paper-doll handler through them.
     #[test]
     fn equipment_slots_are_below_the_floor() {
         let mut s = UiScript::new().unwrap();
@@ -512,7 +410,6 @@ mod tests {
         assert!(s.take_bag_autostores().is_empty());
     }
 
-    /// `PickupBagFromSlot` picks a bank bag up, returns NOTHING, and locks the slot.
     #[test]
     fn pickup_bag_from_slot_takes_the_bag_and_returns_nothing() {
         let mut s = UiScript::new().unwrap();
@@ -530,9 +427,6 @@ mod tests {
         assert!(s.eval::<bool>("return IsInventoryItemLocked(64)").unwrap());
     }
 
-    /// **Destructive, and that is the finding**: `ClearCursor(1,1)` runs unconditionally before
-    /// the slot is even looked at (`0x4c7b79`), so a held payload is dropped even when the slot
-    /// turns out to hold nothing to pick up.
     #[test]
     fn pickup_bag_from_slot_drops_whatever_was_held_first() {
         let mut s = UiScript::new().unwrap();
@@ -546,13 +440,10 @@ mod tests {
         assert!(s.take_container_moves().is_empty(), "no place path exists");
     }
 
-    /// The `TYPEMASK_CONTAINER` resolve (`mov ecx,4`, where `PickupInventoryItem` uses 2): the
-    /// bank's own item slots are inside the gate's range and hold ordinary items, so the verb
-    /// silently no-ops there. A locked bag is refused too.
     #[test]
     fn pickup_bag_from_slot_only_takes_containers_and_never_a_locked_one() {
         let mut s = UiScript::new().unwrap();
-        // Bank vault slot 3 → live id 42, an ordinary item: inside the gate, not a container.
+        // Bank slot 3 is live id 42: inside the gate, but an ordinary item.
         let mut vault = std::collections::HashMap::new();
         vault.insert(
             3,
diff --git a/crates/benilla-ui/src/script/cursor/bar.rs b/crates/benilla-ui/src/script/cursor/bar.rs
index 5fdf2de4..38f1a16f 100644
--- a/crates/benilla-ui/src/script/cursor/bar.rs
+++ b/crates/benilla-ui/src/script/cursor/bar.rs
@@ -1,18 +1,7 @@
-//! The action bar (decision 0216 §7, slice 4; byte-verified 0218 §2/§4): `PickupAction`/
-//! `PlaceAction` join the ONE payload space as the [`CursorAction`] arm. Two things set this
-//! surface apart from bags/doll:
-//!
-//! - **The bar is client-authoritative and actions HOP** (0218 §4, `PlaceAction 0x4e62e0`) — the
-//!   opposite of the post-0218 item swap: placing onto an occupied slot puts the DISPLACED action
-//!   on the cursor rather than clearing, because there is no server round-trip to wait on (the
-//!   120-slot table is ours; [`place_action`] IS the mutation, not a request for one).
-//! - **The engine owns the payload + transition, the app owns the 120-table** (0216 §7's
-//!   ownership split): `model.actions` here is the engine's own OPTIMISTIC mirror of the app's
-//!   authoritative store, kept only so `HasAction`/`GetActionTexture`/&c. read right the instant a
-//!   local pickup/place happens, without waiting a frame for the app to re-feed. Every mutation
-//!   also queues `(lua id, packed)` onto [`Model::action_sets`] — the wire intent the app drains
-//!   into `CMSG_SET_ACTION_BUTTON`, one send per queued entry (0218 §4: a drag-swap is two sends,
-//!   never atomic — this module never coalesces them).
+//! The action-bar cursor verbs. The bar is client-authoritative: placing onto an occupied slot
+//! hops the displaced action onto the cursor (`PlaceAction`, `0x4e62e0`). `model.actions` is an
+//! optimistic mirror of the app's table; each change queues one `CMSG_SET_ACTION_BUTTON`, so a
+//! drag-swap is two sends.
 
 use mlua::Lua;
 
@@ -21,30 +10,18 @@ use crate::script::{ActionSlot, Model};
 
 use super::{queue_cursor_update, CursorAction, CursorPayload};
 
-/// The GlobalStrings key the reference's passive-spell refusal shows — errorId `0x9e`'s entry in
-/// the errorId→key table (`0xb4b498 + 0x9e*0x14 = 0xb4c0f0` ← key ptr `0x84133c`), i.e.
-/// `ERR_PASSIVE_ABILITY` = "You can't put a passive ability in the action bar.". Queued onto
-/// `Model::ui_errors` for the app's action feed to resolve and fire.
+/// The passive-spell refusal's error, errorId `0x9e`: entry `0xb4c0f0` of the table at `0xb4b498`
+/// (stride `0x14`) names this key (`0x84133c`).
 const PASSIVE_ON_BAR_ERROR: &str = "ERR_PASSIVE_ABILITY";
 
-/// Pack `(kind, action)` into the wire's `u32` slot word (`kind<<24 | action`, decision 0216 §1).
+/// The `CMSG_SET_ACTION_BUTTON` slot word.
 fn pack(kind: u8, action: u32) -> u32 {
     (u32::from(kind) << 24) | (action & 0x00FF_FFFF)
 }
 
-/// `PickupAction(id)` — the action-bar slot's shift-click/drag-start entry point (ref
-/// `ActionBarFrame.xml:12-38`'s `IsShiftKeyDown()` fork, `OnDragStart`).
-///
-/// - **A payload is already held** → falls through to [`place_action`] (the reference's own
-///   contract: a shift-click while carrying just places, `ActionButtonTemplate`'s `OnClick` never
-///   special-cases it).
-/// - **Empty cursor, an occupied slot** → picks it up: payload `Action { src_slot: id, kind,
-///   action, texture }`, the slot removed from `model.actions` (optimistic — the app re-pushes an
-///   agreeing snapshot once `action_sets` lands), and `action_sets.push((id, 0))` queued — picking
-///   an action OFF the bar empties it immediately on the wire too (the classic drag-off).
-/// - **Empty cursor, an empty slot** → no-op (nothing to pick up).
-///
-/// Returns whether the caller should repaint (mirrors the container/doll pickup contract).
+/// `PickupAction(id)`, the slot's shift-click and drag start (`ActionBarFrame.xml:12-38`). With a
+/// payload held it places instead; a pickup also clears the slot on the wire at once. Returns
+/// whether to repaint.
 pub(super) fn pickup_action(model: &mut Model, id: u32) -> bool {
     if model.cursor.is_some() {
         return place_action(model, id);
@@ -65,40 +42,14 @@ pub(super) fn pickup_action(model: &mut Model, id: u32) -> bool {
     true
 }
 
-/// `PlaceAction(id)` — the action-bar slot's click-with-payload/`OnReceiveDrag` entry point (ref
-/// `UseAction(id, checkCursor=1)`'s place fork, `ActionBarFrame.xml`'s `OnReceiveDrag`).
-///
-/// Every arm writes the held action into `model.actions[id]` optimistically and queues
-/// `action_sets.push((id, packed))`; what happens to the cursor afterward is the byte-verified
-/// divergence from every other surface (0218 §4): an OCCUPIED destination puts the DISPLACED
-/// action on the cursor (referencing `id` as its new `src_slot` — the slot it can now be placed
-/// FROM), an empty destination just clears.
-///
-/// - Payload **Action** → `(kind, action)` straight off the held payload.
-/// - Payload **Item** → `packed = item_id | ITEM<<24`; the item came from a BAG and STAYS there —
-///   a bar item action is a reference, not a move, so no container move is queued here (the app's
-///   `drain_action_sets` never touches `container_moves` either).
-/// - Payload **Spell** → `packed = spell_id | SPELL<<24` (the producer, `PickupSpell`, lands in
-///   slice 5 — this arm already works once something populates the payload).
-/// - **Empty cursor** → no-op.
-///
-/// Returns whether the caller should repaint.
+/// `PlaceAction(id)`, the slot's `OnReceiveDrag` and `UseAction(id, 1)`'s place fork. An occupied
+/// slot's action hops onto the cursor with `id` as its source; an item stays in its bag, since a
+/// bar item is a reference, not a move. Returns whether to repaint.
 pub(crate) fn place_action(model: &mut Model, id: u32) -> bool {
-    // The two accept filters, byte-read (`PlaceAction 0x4e62e0` — decision 0666). Both
-    // reject with a **bare return**: no store, no clear, no packet — mechanically identical to
-    // clicking with an empty cursor, and the refused payload STAYS on the cursor.
-    //
-    // - ITEM: placeable iff it has an on-use spell OR is equippable (`4e6571`–`4e6598`). There is
-    //   no quality, bind, class/subclass, container or level test anywhere on that path — a BAG
-    //   is placeable; a grey trade good with neither is silently refused.
-    // - SPELL: a passive (`Attributes & 0x40`) is refused (`4e63ad`), and — unlike the ITEM
-    //   refusal, which is mute — it ALSO raises errorId `0x9e` through `CGGameUI::DisplayError`
-    //   (`4e63ad: push 0x9e; call 0x496720`). That id resolves through the errorId→key table at
-    //   base `0xb4b498`, stride `0x14`: entry `0xb4b498 + 0x9e*0x14 = 0xb4c0f0`, whose static-init
-    //   `4861ff: mov [0xb4c0f0], 0x84133c` names [`PASSIVE_ON_BAR_ERROR`] — "You can't put a
-    //   passive ability in the action bar." (The same arithmetic reproduces the independently
-    //   recorded `ERR_ATTACK_MOUNTED` anchor: `0xa4` → `0xb4c168`.) Closes 0666's named
-    //   divergence, which refused silently while the key was unpinned.
+    // The two accept filters (`0x4e62e0`) refuse with a bare return: nothing stored or sent, and
+    // the payload stays held. An item needs an on-use spell or an equip slot (`0x4e6571`), so a
+    // bag is placeable; a passive spell (`Attributes & 0x40`) also raises errorId `0x9e` through
+    // `DisplayError` (`0x4e63ad`, `0x496720`), where the item refusal is mute.
     match &model.cursor {
         Some(CursorPayload::Item(i)) if !i.bar_placeable => return false,
         Some(CursorPayload::Spell(s)) if s.passive => {
@@ -114,24 +65,13 @@ pub(crate) fn place_action(model: &mut Model, id: u32) -> bool {
         CursorPayload::Action(a) => Some((a.kind, a.action, a.texture.clone())),
         CursorPayload::Item(i) => Some((ACTION_KIND_ITEM, i.item_id, i.texture.clone())),
         CursorPayload::Spell(s) => Some((ACTION_KIND_SPELL, s.spell_id, s.texture.clone())),
-        // Mode 8 — the one non-item/non-spell payload the reference's `PlaceAction` accepts
-        // (`0x4e62e0`'s accept table: pet actions and class abilities are refused,
-        // macros are not). It packs the bare macro id under the MACRO tag, exactly as the SPELL
-        // and ITEM arms pack theirs.
+        // `PlaceAction` accepts modes 1, 3, 7 and 8 (`0x4e62e0`): a macro, mode 8, packs its id
+        // under the macro tag. Pet actions (4), coins (2), stabled pets (10) and vendor rows (5)
+        // are refused and stay held.
         CursorPayload::Macro(m) => Some((ACTION_KIND_MACRO, m.index, m.texture.clone())),
-        // Mode 4 — the other half of that same table's refusal (decision 1010). A pet action has
-        // no `CMSG_SET_ACTION_BUTTON` encoding at all, so there is nothing to pack: the payload
-        // goes straight back on the cursor, where the pet bar can still take it.
         CursorPayload::PetAction(_) => None,
-        // Mode 10 (decision 1677) — a stabled pet has no `CMSG_SET_ACTION_BUTTON` encoding either,
-        // so the action bar refuses it and it goes back on the cursor.
         CursorPayload::StablePet(_) => None,
-        // Mode 2 (1962) — `PlaceAction`'s table takes modes 1, 2 and 8 … where its mode 2 is the
-        // BAR-slot pickup, not coins; the money payload has no encoding and goes back.
         CursorPayload::Money(_) => None,
-        // Mode 5 — a vendor row is not a bar action. `PlaceAction`'s payload table takes modes
-        // 1, 2 and 8 only, and the merchant grab is none of them, so it goes back on the cursor
-        // where the vendor window can still take it.
         CursorPayload::Merchant(_) => None,
     };
     let Some((kind, action, texture)) = placeable else {
@@ -144,9 +84,7 @@ pub(crate) fn place_action(model: &mut Model, id: u32) -> bool {
             texture,
             kind,
             action,
-            // The engine holds no item knowledge, so neither half of the Count pair can be
-            // answered here: the app's next-frame re-feed resolves the real bag count and the
-            // `IsConsumableAction` gate together, off the item template (decision 1301).
+            // Count and consumable wait for the app's next-frame re-feed, which knows the item.
             count: 0,
             consumable: false,
         },
@@ -164,9 +102,7 @@ pub(crate) fn place_action(model: &mut Model, id: u32) -> bool {
     true
 }
 
-/// Register the action-bar's cursor globals — top-level, matching the reference
-/// (`PickupAction`/`PlaceAction` are not namespaced any more than `PickupContainerItem`'s cursor
-/// siblings are).
+/// Register `PickupAction` and `PlaceAction` as globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
@@ -249,9 +185,6 @@ mod tests {
         assert_eq!(s.take_action_sets(), vec![(7, 133)]);
     }
 
-    /// The byte-verified divergence from bags/doll (0218 §4): placing onto an OCCUPIED action
-    /// slot HOPS the displaced action onto the cursor — two `action_sets` entries across the
-    /// gesture (the pickup's clear, then the place's write), never a container move.
     #[test]
     fn place_action_onto_occupied_hops_the_displaced_action() {
         let mut s = UiScript::new().unwrap();
@@ -262,12 +195,10 @@ mod tests {
         assert_eq!(s.take_action_sets(), vec![(1, 0)]);
 
         assert!(s.eval::<bool>("return PlaceAction(2)").unwrap());
-        // Slot 2 now shows the placed action (111).
         assert_eq!(
             s.eval::<String>("return GetActionTexture(2)").unwrap(),
             "Interface\\Icons\\Spell_A"
         );
-        // The displaced action (222) is now the held payload, sourced from slot 2.
         let (kind, src) = s
             .eval::<(String, i64)>("local k, slot = GetCursorInfo() return k, slot")
             .unwrap();
@@ -282,9 +213,6 @@ mod tests {
             }))
         );
         assert_eq!(s.take_action_sets(), vec![(2, 111)]);
-
-        // A hop is Some→Some: no HIDE+SHOW churn out of one gesture.
-        // (Exercised directly by the SHOWGRID/HIDEGRID test below.)
     }
 
     #[test]
@@ -336,8 +264,6 @@ mod tests {
         assert!(s.take_action_sets().is_empty());
     }
 
-    /// Shift-click while ALREADY holding just places (the reference's own `OnClick` never
-    /// special-cases it): `PickupAction` on a held cursor routes straight to [`super::place_action`].
     #[test]
     fn pickup_action_with_a_payload_held_falls_through_to_place() {
         let mut s = UiScript::new().unwrap();
@@ -353,9 +279,6 @@ mod tests {
         assert_eq!(s.take_action_sets(), vec![(5, 111)]);
     }
 
-    /// `ACTIONBAR_SHOWGRID`/`ACTIONBAR_HIDEGRID` fire on the cursor's None↔Some edges (decision
-    /// 0216 §7) — a pickup shows the grid, a place-onto-empty hides it, and a HOP (Some→Some)
-    /// fires neither (no HIDE+SHOW churn out of one gesture).
     #[test]
     fn showgrid_hidegrid_fire_on_gain_and_loss_not_on_a_hop() {
         let mut s = UiScript::new().unwrap();
@@ -391,9 +314,6 @@ mod tests {
         assert_eq!(s.eval::<i64>("return hides").unwrap(), 1);
     }
 
-    /// `PlaceAction`'s ITEM filter (decision 0666): an item with neither an on-use spell nor an
-    /// equip slot — a grey trade good — is refused, and the refusal is a **bare return**: nothing
-    /// stored, nothing sent, and the payload is still on the cursor afterwards.
     #[test]
     fn a_non_usable_non_equippable_item_is_refused_and_stays_held() {
         let mut s = UiScript::new().unwrap();
@@ -423,10 +343,6 @@ mod tests {
         );
     }
 
-    /// The SPELL twin: a passive cannot go on the bar (`Attributes & 0x40`) — and unlike the item
-    /// arm this one SPEAKS, raising errorId `0x9e` = `ERR_PASSIVE_ABILITY` (see
-    /// [`super::place_action`]). The refusal and the toast are separate halves: the refusal is
-    /// still a bare return, so nothing is stored, nothing is sent, and the spell stays held.
     #[test]
     fn a_passive_spell_is_refused_with_the_refs_error_and_stays_held() {
         let mut s = UiScript::new().unwrap();
@@ -453,8 +369,6 @@ mod tests {
         );
     }
 
-    /// The other half of the same law: an ACTIVE spell places normally and raises nothing. Guards
-    /// the obvious over-correction — a toast on every spell drop.
     #[test]
     fn an_active_spell_places_without_an_error() {
         let mut s = UiScript::new().unwrap();
@@ -471,8 +385,6 @@ mod tests {
         assert!(s.take_ui_errors().is_empty());
     }
 
-    /// The positive control on the other side of both filters — a BAG (`InventoryType` 18, no
-    /// on-use spell) IS placeable, which is the one answer people find surprising.
     #[test]
     fn a_bag_is_placeable() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/cursor/doll.rs b/crates/benilla-ui/src/script/cursor/doll.rs
index 6347742e..477488e7 100644
--- a/crates/benilla-ui/src/script/cursor/doll.rs
+++ b/crates/benilla-ui/src/script/cursor/doll.rs
@@ -1,9 +1,5 @@
-//! The paper doll (decision 0208 phase 1b): equipment joins the ONE payload space via
-//! [`super::EQUIPMENT_BAG`]. One extra transition ([`pickup_inventory_item`]) plus four small
-//! satellites ([`equip_cursor_item`], [`cursor_can_go_in_slot`], [`auto_equip_cursor_item`],
-//! [`use_inventory_item`], [`is_inventory_item_locked`]) — everything else (cancel, clear, the
-//! world drop, `SplitContainerItem`) already generalizes from [`super`] because it only ever
-//! matches on the `CursorPayload` enum, never on `bag`.
+//! The paper-doll cursor verbs: an equipped slot is an item source under
+//! [`super::EQUIPMENT_BAG`], so the shared cursor code handles its cancel, clear and world drop.
 
 use mlua::Lua;
 
@@ -13,45 +9,18 @@ use crate::script::Model;
 
 use super::{queue_cursor_update, queue_lock_changed, CursorItem, CursorPayload, EQUIPMENT_BAG};
 
-/// `PickupInventoryItem(id)` — the paper-doll slot's left-click entry point (decision 0208 phase
-/// 1b). Mirrors `container::pickup_container_item`'s click model exactly, keyed on the sentinel
-/// [`EQUIPMENT_BAG`] rather than a real bag id (decision 0216 §1's ONE payload space, extended to
-/// equipment). `id` is the 1-based live-API inventory slot (`GetInventorySlotInfo`'s own
-/// numbering — HeadSlot=1 … TabardSlot=19, the four equipped-bag icons Bag0Slot=20 … Bag3Slot=23).
-/// The bag icons ride the SAME transition (a bag's `equip_slots` is `[20,21,22,23]` from
-/// `find_equip_slot(INVTYPE_BAG)`, so the fit rule already routes a bag onto any bag slot, and
-/// `wire_pos`'s `EQUIPMENT_BAG` arm maps live id 20..23 → the wire's equipped-bag inventory slots
-/// 19..22); ammo (0) stays a named deferral — refused outright, cursor untouched.
-///
-/// **The bank-bag band (64..=69) rides this too**, and only through one door: `PutItemInBag`'s
-/// empty-slot leg IS this function in the reference (`0x4c7c00` calls `0x4c7300` there), which is
-/// how a held bag reaches a bank bag slot at all. Its fit rule is one band wider than
-/// `equip_slots` alone — see [`super::bag_verbs::fits_slot`].
-///
-/// - empty cursor + an occupied, UNLOCKED doll slot → picks it up (payload `Item { bag:
-///   EQUIPMENT_BAG, slot: id, … }`), the same lock/event pair as a bag pickup.
-/// - holding + the SAME slot → cancel (mirrors `pickup_container_item`'s own same-slot branch).
-/// - holding an Item payload whose `equip_slots` contains `id` (the fit rule — `equip_slots` rides
-///   the payload from wherever it was picked up, doll or bag alike) → queues the move (dst =
-///   `(EQUIPMENT_BAG, id)`) and CLEARS (decision 0218: a plain clear, no hop) — UNLESS it's a
-///   split carry (`count: Some(_)`): refused outright, kept (you can't equip a partial stack).
-/// - holding a non-fitting Item, or any Spell/Action payload → no-op, kept (mirrors
-///   `pickup_container_item`'s own refusal of a payload a bag slot can't take).
-///
-/// Returns whether the caller should repaint (the source lock, or the held payload, changed).
+/// `PickupInventoryItem(id)` (`0x4c7300`), the doll slot's click, on the bag click's model: a
+/// fitting whole item moves in and the cursor clears, with no hop; a split or a misfit stays
+/// held. Returns whether to repaint.
 pub(super) fn pickup_inventory_item(model: &mut Model, id: u32) -> bool {
-    // Equipment slots (1..=19) + the four equipped-bag icons (20..=23) + the six BANK bag slots
-    // (64..=69, reached only through `PutItemInBag`); ammo (0) is out of scope.
+    // Head 1 to Tabard 19, the bag slots 20-23, and the bank bag slots, which only `PutItemInBag`
+    // reaches (`0x4c7c00` calls `0x4c7300`). Ammo (0) is refused; its leg is not built.
     if !(1..=23).contains(&id) && !super::bag_verbs::BANK_BAG_INV_SLOTS.contains(&id) {
         return false;
     }
-    // The targeting cursor's item half, on the doll (decision 0923). The reference's doll pickup
-    // `0x4c7300` carries the byte-IDENTICAL rung to the bag one — `4c76df: call 0x6e48a0`
-    // (IsTargeting), `4c76e8: call 0x6e6330` (TargetingWantsItem), `4c76fb: call 0x495d60` (bind
-    // this item), then return with nothing picked up — and it is what makes poisoning or
-    // sharpening the weapon you are *wearing* possible at all. Reported in the ONE bag space
-    // ([`EQUIPMENT_BAG`] + the 1-based slot), so the app's drain resolves both seams identically.
-    // A held payload wins, exactly as in the bag path (the ref's own `4c73af` pair precedes it).
+    // An item-targeting spell binds this slot instead of picking it up, as the bag click does
+    // (`0x4c76df`: `0x6e48a0` IsTargeting, `0x6e6330` TargetingWantsItem, `0x495d60` bind), so a
+    // worn weapon can be poisoned. A held payload wins: `0x4c73af` tests it first.
     if model.item_pick_armed && model.cursor.is_none() {
         model.item_picks.push((EQUIPMENT_BAG, id));
         return false;
@@ -88,9 +57,7 @@ pub(super) fn pickup_inventory_item(model: &mut Model, id: u32) -> bool {
             true
         }
         Some(CursorPayload::Item(held)) => {
-            // A split carry can't equip a partial stack, and a non-fitting item has nowhere to
-            // land on this slot — both refuse, kept exactly as picked up (no event: nothing
-            // transitioned).
+            // A split or a misfit stays held, with no event: nothing changed.
             if held.count.is_some() || !super::bag_verbs::fits_slot(&held, id) {
                 model.cursor = Some(CursorPayload::Item(held));
                 return false;
@@ -106,14 +73,9 @@ pub(super) fn pickup_inventory_item(model: &mut Model, id: u32) -> bool {
             queue_lock_changed(model, held.bag, held.slot);
             true
         }
-        // Mode 5 — the buy, aimed at an equipment slot. `0x4c78fd` tests `[0xb4d900] == 5` inside
-        // the paper-doll click and sends the same `CMSG_BUY_ITEM_IN_SLOT 0x1a3` the bag drop does;
-        // the server equips it or refuses. Reported in the ONE bag space ([`EQUIPMENT_BAG`] + the
-        // 1-based inventory slot), the seam this file already uses for every other doll intent.
-        //
-        // Of the reference's three drop consumers this is the one that handles a stale vendor row
-        // correctly — the other two dereference it (`0x4f9f35`, `0x4c7ea5`) — so its refusal is
-        // what we reproduce in all three.
+        // Mode 5, a buy into this slot: `0x4c78fd` sends `CMSG_BUY_ITEM_IN_SLOT` (`0x1a3`) and the
+        // server equips or refuses. A stale row buys nothing: of the reference's three drop sites
+        // only this one checks it; the other two (`0x4f9f35`, `0x4c7ea5`) dereference it.
         Some(CursorPayload::Merchant(held)) => {
             let entry = model
                 .merchant
@@ -132,10 +94,11 @@ pub(super) fn pickup_inventory_item(model: &mut Model, id: u32) -> bool {
             | CursorPayload::Action(_)
             | CursorPayload::Macro(_)
             | CursorPayload::PetAction(_)
-            // Mode 10 (decision 1677) — a stabled pet refuses a bag/doll slot exactly as the
-            // spell/action family does, and stays on the cursor for the stable window to take.
+            // Mode 10: a stabled pet stays held for the stable window.
             | CursorPayload::StablePet(_)
-            // Mode 2 (1962) — coins have no slot to land in; a money frame's DropFunc takes them.
+            // Mode 2: coins stay held for a money frame's drop. On an occupied slot the reference
+            // picks the item up over either, as it tests only for a held item (`0x4c769a`) or a
+            // preview row (`0x4c76a5`) before the pickup (`0x4c7838`).
             | CursorPayload::Money(_)),
         ) => {
             model.cursor = Some(other);
@@ -144,27 +107,15 @@ pub(super) fn pickup_inventory_item(model: &mut Model, id: u32) -> bool {
     }
 }
 
-/// `EquipCursorItem(id)` — the ref's item-context "Equip" popup entry (not built this slice: no
-/// context menu ships yet). Same transition as placing the held item directly onto doll slot
-/// `id` — [`pickup_inventory_item`]'s place arm already IS that transition, so this simply routes
-/// there (decision 0208 phase 1b: "route both through the same transition").
+/// `EquipCursorItem(id)`: placing the held item on doll slot `id`.
 pub(super) fn equip_cursor_item(model: &mut Model, id: u32) -> bool {
     pickup_inventory_item(model, id)
 }
 
-/// `CursorCanGoInSlot(id)` — whether the held payload could be dropped on doll slot `id`
-/// (decision 0208 phase 1b; the reference's `CURSOR_UPDATE` → `LockHighlight`/`UnlockHighlight`
-/// driver, `PaperDollFrame.lua:609-615`). An Item payload whose `equip_slots` contains `id`;
-/// empty cursor or a Spell/Action payload both answer `false` (the same fit-blind refusal
-/// [`pickup_inventory_item`] gives them — asking a hypothetical doesn't relax the rule).
-///
-/// INTERIM: the byte body's terminal equip-fit check (`0x5da1d0`) was left unresolved by 0216 §5
-/// (0218's own residual, §4 "confirmed as built" — everything else on that list is pinned, this
-/// one function wasn't among the byte-verified findings). `equip_slots` derives from the item
-/// template's `inventoryType` via the SERVER's own mapping instead (`ui_items::find_equip_slot`,
-/// transcribed from vmangos `Player::FindEquipSlot`/`ItemPrototype::GetAllowedEquipSlots`) — a
-/// verifiable authority `SMSG_INVENTORY_CHANGE_FAILURE` referees either way, corrected if a
-/// future pin disagrees with the client's own table.
+/// `CursorCanGoInSlot(id)`, the doll slot's highlight on `CURSOR_UPDATE`
+/// (`PaperDollFrame.lua:609-615`): `equip_slots`, which follows vmangos `Player::FindEquipSlot`,
+/// where the reference's `IsValidForSlot` (`0x5da1d0`) tests a static slot mask per
+/// `InventoryType`.
 pub(super) fn cursor_can_go_in_slot(model: &Model, id: u32) -> bool {
     match &model.cursor {
         Some(CursorPayload::Item(item)) => super::bag_verbs::fits_slot(item, id),
@@ -172,17 +123,10 @@ pub(super) fn cursor_can_go_in_slot(model: &Model, id: u32) -> bool {
     }
 }
 
-/// `AutoEquipCursorItem()` — the model-pane's click-with-payload path (decision 0208 phase 1b,
-/// ref `PaperDollFrame.xml`'s frame-level `OnReceiveDrag`/`OnMouseUp`): an Item payload picked up
-/// from a CONTAINER (`bag >= 0`, a whole stack) queues its `(bag, slot)` source as a NEW
-/// `container_autoequips` intent (the app sends `CMSG_AUTOEQUIP_ITEM` — the server picks the
-/// destination slot itself and swaps any displaced piece back, vmangos `ItemHandler.cpp:138-228`)
-/// and clears the cursor — a plain clear, the same contract as every other placement since
-/// decision 0218. A payload already carried FROM the equipment (`bag == EQUIPMENT_BAG` — a
-/// doll→doll re-drop has nothing for the server to "auto" pick) or a split carry (can't
-/// auto-equip a partial stack) is a no-op, kept; so is any Spell/Action payload.
-///
-/// Returns whether the caller should repaint.
+/// `AutoEquipCursorItem()`, a click or drop on the doll's model (`PaperDollFrame.lua:31-35`): a
+/// whole stack from a bag becomes `CMSG_AUTOEQUIP_ITEM`: the server picks the slot and swaps
+/// the displaced piece back (`ItemHandler.cpp:138-228`); an equipped item or a split stays held.
+/// Returns whether to repaint.
 pub(super) fn auto_equip_cursor_item(model: &mut Model) -> bool {
     match model.cursor.take() {
         Some(CursorPayload::Item(item)) if item.bag >= 0 && item.count.is_none() => {
@@ -198,25 +142,15 @@ pub(super) fn auto_equip_cursor_item(model: &mut Model) -> bool {
     }
 }
 
-/// `UseInventoryItem(id)` — the doll slot's right-click entry point (ref
-/// `PaperDollItemSlotButton_OnClick`, `PaperDollFrame.lua:658-659`): queues `id` for the app to
-/// resolve to the equipped item's guid and send (`CMSG_USE_ITEM`, bag 255 + the 0-based wire slot
-/// — vmangos `HandleUseItemOpcode` takes equipped positions the same as bag ones). No engine-side
-/// refusal — an empty/out-of-range slot is a harmless no-op the app's drain silently drops
-/// (mirrors `UseContainerItem`'s own contract: it never checks the slot either).
+/// `UseInventoryItem(id)`, the doll slot's right-click (`PaperDollFrame.lua:658-659`): the app
+/// sends `CMSG_USE_ITEM` with bag 255 and the 0-based slot, and drops an empty slot unsent.
 pub(super) fn use_inventory_item(model: &mut Model, id: u32) {
     model.inventory_uses.push(id);
 }
 
-/// `IsInventoryItemLocked(id)` — true while `id` is the ACTIVE cursor payload's source (the
-/// picked-up slot dims immediately, no server round-trip — the doll twin of
-/// `GetContainerItemInfo`'s `held_here` derivation) OR the app's fed `InvSlotView.locked` says so
-/// (an outstanding pending op the app's `PendingItemOps` tracks, decision 0216 §4/0218 §3).
-///
-/// Reads through [`Model::inv_slot`], not the doll array, so it answers over the WHOLE live-id
-/// space that binding covers — the reference's `BankFrameItemButton_UpdateLock` calls it with
-/// `BankButtonIDToInvSlotID(...)` for every bank slot, and a lock the vault feed reports has to
-/// dim the button the same as an equipped one.
+/// `IsInventoryItemLocked(id)`: true while `id` is the held item's source or the app reports a
+/// pending operation on it. Reads [`Model::inv_slot`], since `BankFrameItemButton_UpdateLock`
+/// asks about bank slots too.
 pub(super) fn is_inventory_item_locked(model: &Model, id: u32) -> bool {
     let held_here = matches!(&model.cursor, Some(CursorPayload::Item(c)) if c.bag == EQUIPMENT_BAG && c.slot == id);
     let fed = usize::try_from(id)
@@ -226,9 +160,7 @@ pub(super) fn is_inventory_item_locked(model: &Model, id: u32) -> bool {
     held_here || fed
 }
 
-/// Register the paper-doll's cursor globals — all top-level, matching the reference
-/// (`PickupInventoryItem` &c. are not namespaced any more than `PickupContainerItem`'s cursor
-/// siblings are).
+/// Register the paper-doll verbs as globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
@@ -284,8 +216,7 @@ mod tests {
     use crate::script::cursor::{CursorAction, CursorPayload, CursorSpell, EQUIPMENT_BAG};
     use crate::script::{ContainerMove, ContainerSlot, ContainerState, InvSlotView, UiScript};
 
-    /// Slots 1 (Head) and 19 (Tabard) occupied, plus the two finger rings (11/12) — a doll
-    /// fixture wide enough to exercise the fit rule, the same-slot cancel, and a doll↔doll swap.
+    /// Head (1), a ring in finger slot 11 that also fits 12, and Tabard (19).
     fn doll_slots() -> crate::script::InventorySlots {
         let mut slots: crate::script::InventorySlots = Default::default();
         slots[1] = Some(InvSlotView {
@@ -320,7 +251,7 @@ mod tests {
             name: Some("Test Ring".into()),
             link: Some("|cffffffff|Hitem:555:0:0:0|h[Test Ring]|h|r".into()),
             locked: false,
-            equip_slots: vec![11, 12], // FINGER1|FINGER2 — the doll↔doll swap fixture
+            equip_slots: vec![11, 12], // either finger: the doll-to-doll swap
             creator: None,
             enchants: Vec::new(),
         });
@@ -513,7 +444,7 @@ mod tests {
         });
         s.set_inventory_slots(slots);
 
-        // Ammo (0) is still refused; the bag icon (20) now picks up the equipped bag.
+        // Ammo (0) is refused; Bag0Slot (20) picks up the equipped bag.
         assert!(!s.eval::<bool>("return PickupInventoryItem(0)").unwrap());
         assert!(s.eval::<bool>("return PickupInventoryItem(20)").unwrap());
         let held = s.cursor_item().expect("bag picked up from the bar");
@@ -523,9 +454,6 @@ mod tests {
         );
     }
 
-    /// Drag-to-equip: a bag carried from the backpack drops onto an empty bag slot (id 21), queuing
-    /// the move to `(EQUIPMENT_BAG, 21)` — the same transition the paper doll uses, and the wire the
-    /// app maps onto equipped-bag inventory slot 20.
     #[test]
     fn place_a_bag_onto_a_bag_slot_queues_the_equip_move() {
         let mut s = UiScript::new().unwrap();
@@ -583,17 +511,14 @@ mod tests {
         let mut s = UiScript::new().unwrap();
         s.set_inventory_slots(doll_slots());
 
-        // Empty cursor: false everywhere.
         assert!(!s.eval::<bool>("return CursorCanGoInSlot(1)").unwrap());
 
-        // Item arm: true only for a slot its equip_slots names.
         s.set_container(0, Some(one_fitting_bag_item()));
         s.run("PickupContainerItem(0, 1)").unwrap();
         assert!(s.eval::<bool>("return CursorCanGoInSlot(1)").unwrap());
         assert!(!s.eval::<bool>("return CursorCanGoInSlot(2)").unwrap());
         s.run("ClearCursor()").unwrap();
 
-        // Spell/Action arms: always false (the fit-blind refusal).
         s.set_cursor_for_test(CursorPayload::Spell(CursorSpell {
             passive: false,
             book_slot: 1,
@@ -627,14 +552,12 @@ mod tests {
         let mut s = UiScript::new().unwrap();
         s.set_inventory_slots(doll_slots());
 
-        // From the doll itself: nothing for the server to "auto" pick.
         s.run("PickupInventoryItem(1)").unwrap();
         assert!(!s.eval::<bool>("return AutoEquipCursorItem()").unwrap());
         assert!(s.cursor_item().is_some(), "kept");
         assert!(s.take_container_autoequips().is_empty());
         s.run("ClearCursor()").unwrap();
 
-        // A split carry: can't auto-equip a partial stack.
         let mut state = one_fitting_bag_item();
         state.slots.get_mut(&1).unwrap().count = 5;
         s.set_container(0, Some(state));
@@ -694,11 +617,8 @@ mod tests {
         );
     }
 
-    /// The targeting cursor's item half reroutes BOTH pickup seams (decision 0923), and the
-    /// held-payload check precedes it in both — the reference's own order (`4f9c38` before
-    /// `4f9c54`; `4c73af` before `4c76df`). Without the doll seam a rogue could not poison the
-    /// weapon they are wearing; without the payload gate, dragging an item across a bag while a
-    /// poison is armed would silently fire the cast at whatever you dropped it on.
+    /// The held-payload test runs first in both seams: `0x4f9c38` before `0x4f9c54` in the bag,
+    /// `0x4c73af` before `0x4c76df` on the doll.
     #[test]
     fn the_armed_item_half_reroutes_bag_and_doll_clicks() {
         let mut s = UiScript::new().unwrap();
@@ -710,7 +630,7 @@ mod tests {
         assert!(s.cursor_item().is_some());
         assert!(s.take_item_picks().is_empty());
 
-        // Armed but HOLDING: the payload wins, exactly as the reference orders it.
+        // Armed but holding: the payload wins.
         s.set_item_pick_armed(true);
         s.run("PickupContainerItem(0, 1)").unwrap();
         assert!(
@@ -718,8 +638,7 @@ mod tests {
             "a click while carrying an item is a place, not a bind"
         );
 
-        // Armed with an empty cursor: both seams bind instead of picking up, and neither
-        // disturbs the cursor.
+        // Armed with an empty cursor: both seams bind and leave the cursor empty.
         s.run("ClearCursor()").unwrap();
         assert!(s.cursor_item().is_none());
         assert!(!s.eval::<bool>("return PickupInventoryItem(1)").unwrap());
diff --git a/crates/benilla-ui/src/script/cursor/drag.rs b/crates/benilla-ui/src/script/cursor/drag.rs
index a479263f..de883c71 100644
--- a/crates/benilla-ui/src/script/cursor/drag.rs
+++ b/crates/benilla-ui/src/script/cursor/drag.rs
@@ -1,19 +1,13 @@
-//! The drag gesture (decision 0216 §3) — `RegisterForDrag`/`OnDragStart`/`OnDragStop`/
-//! `OnReceiveDrag`'s mechanics: arm on press, start past a threshold, resolve on release. Split
-//! out of [`super`] purely for size — [`super::pointer`](crate::script::pointer) is the only
-//! external caller (via [`super`]'s re-exports), and the payload types/transition seam this
-//! drives live one level up.
+//! The `RegisterForDrag` gesture: armed on a press, started past a threshold, ended on release.
 
 use crate::script::Model;
 use crate::widget::FrameHandle;
 
-/// INTERIM pixel drag-start threshold (0216 §5 (d) is the byte-verified trigger; the reference
-/// almost certainly uses a small OS/engine drag-distance constant, not this one). Compared with
-/// **strict** `>` — a move exactly at the threshold does not start the gesture.
+/// The drag-start distance in pixels, exceeded strictly; the reference starts at 0.01 frame units
+/// or more from the press (`0x81c468`, squared by `0x76b300`).
 pub(crate) const DRAG_START_THRESHOLD: f32 = 4.0;
 
-/// An in-flight drag gesture: armed at mouse-down on a [`Model::drag_registered`] frame,
-/// `started` once the cursor has moved past [`DRAG_START_THRESHOLD`] from the press point.
+/// A drag armed at a press on a [`Model::drag_registered`] frame, `started` past the threshold.
 #[derive(Clone, Debug, PartialEq)]
 pub(crate) struct DragGesture {
     pub(crate) button: String,
@@ -22,22 +16,15 @@ pub(crate) struct DragGesture {
     pub(crate) started: bool,
 }
 
-/// A resolved drag release (a gesture whose button matched the release) — [`Model::drag`] is
-/// always cleared alongside this, win or lose.
+/// A gesture whose button matched the release; [`Model::drag`] is cleared either way.
 pub(crate) struct DragRelease {
-    /// Whether the gesture crossed [`DRAG_START_THRESHOLD`] (so `OnDragStart` fired). A released
-    /// gesture that never started fires nothing — the normal click path proceeds untouched.
+    /// `OnDragStart` fired; an unstarted release fires nothing and the click proceeds.
     pub(crate) started: bool,
     pub(crate) source: FrameHandle,
 }
 
-/// Arm (or clear) the drag gesture on a mouse-DOWN. `hit` is the pressed frame (`None` = the
-/// press hit nothing); a press always REPLACES any leftover in-flight gesture — its matching
-/// release should already have cleared it, but a press is the one moment we know for certain no
-/// gesture should still be armed against a *different* earlier press.
-///
-/// **The replaced gesture is abandoned, not forgotten**: the caller runs [`abandon_drag`] first
-/// and fires `OnDragStop` for a started one. See that function for why a silent drop is the bug.
+/// Arm or clear the gesture on a press, replacing any leftover one; the caller runs
+/// [`abandon_drag`] first so a started gesture still gets its `OnDragStop`.
 pub(crate) fn arm_drag(model: &mut Model, hit: Option<FrameHandle>, button: &str, pos: (f32, f32)) {
     model.drag = hit
         .filter(|&h| {
@@ -54,10 +41,8 @@ pub(crate) fn arm_drag(model: &mut Model, hit: Option<FrameHandle>, button: &str
         });
 }
 
-/// Advance the armed gesture on a mouse-move: once the cursor has moved past
-/// [`DRAG_START_THRESHOLD`] from the press point, mark it started. Returns `(source id, button)`
-/// to fire `OnDragStart` with, exactly once per gesture (already-started and no-gesture both
-/// answer `None`); a source that died before starting fires nothing.
+/// Start the armed gesture once the cursor passes the threshold, returning the `OnDragStart`
+/// source id and button once per gesture; a source that died fires nothing.
 pub(crate) fn maybe_start_drag(model: &mut Model, pos: (f32, f32)) -> Option<(u32, String)> {
     let (source, button) = {
         let g = model.drag.as_ref()?;
@@ -72,11 +57,8 @@ pub(crate) fn maybe_start_drag(model: &mut Model, pos: (f32, f32)) -> Option<(u3
         (g.source, g.button.clone())
     };
     model.drag.as_mut().expect("checked Some above").started = true;
-    // **The button's drag-start edge** — `CSimpleButton` overrides `+0x74` with `0x7793f0`, which
-    // un-presses (`0x779410`, guarded on `locked == 0 && state != DISABLED`) and then forwards to
-    // the base notify that fires `<OnDragStart>`. So a button you drag off releases its pushed art
-    // at the THRESHOLD crossing, which is here — not when the cursor leaves its rect, and not for
-    // a frame that never registered for drag (decision 2134).
+    // A dragged button un-presses at the threshold, not on leaving its rect: `CSimpleButton`'s
+    // `+0x74` override (`0x7793f0`) un-presses (`0x779410`) before firing `OnDragStart`.
     super::super::button::edge(model, source, crate::widget::ButtonState::on_drag_start);
     let id = model
         .arena
@@ -86,26 +68,14 @@ pub(crate) fn maybe_start_drag(model: &mut Model, pos: (f32, f32)) -> Option<(u3
     Some((id, button))
 }
 
-/// **Abandon** an in-flight gesture that will never see its release, and report whether anything
-/// has to be told. Returns the source of a gesture that had **started**, so the caller fires the
-/// same `OnDragStop` a real release would; an armed-but-unstarted press answers `None`, exactly as
-/// releasing one does.
-///
-/// Two callers, and both are situations the reference simply cannot be in: the OS captures the
-/// pointer for the whole of a button-held drag there, so the release always arrives. Ours does
-/// not — the cursor can walk out of the window, and a second button can be pressed mid-gesture —
-/// and dropping the gesture *silently* in either case is what leaves the UI stuck rather than
-/// merely cancelled: the addon's `OnDragStop → StopMovingOrSizing` never runs, so the engine's
-/// single [`Model::moving`] slot stays taken, [`super::super::object::movable::advance_move`]
-/// keeps gluing that frame to the cursor for the rest of the session, and it swallows every press
-/// aimed at anything underneath. (B310 — the raid grid, where one drag off the window edge cost
-/// every later drag.)
+/// Drop a gesture whose release will never come, because the pointer left the window or a second
+/// button was pressed; the reference cannot lose one, as the OS captures the pointer. Returns a
+/// started one's source, which must get `OnDragStop` or a frame it is moving follows the cursor.
 pub(crate) fn abandon_drag(model: &mut Model) -> Option<FrameHandle> {
     model.drag.take().filter(|g| g.started).map(|g| g.source)
 }
 
-/// Resolve (and clear) the in-flight drag gesture matching a mouse-button release's `button`, if
-/// any (case-insensitive, the `RegisterForClicks` precedent).
+/// Take the gesture whose button matches the release.
 pub(crate) fn take_drag(model: &mut Model, button: &str) -> Option<DragRelease> {
     let g = model
         .drag
@@ -151,10 +121,10 @@ mod tests {
         s.resolve();
 
         s.mouse_button(100.0, 300.0, "LeftButton", true); // press inside A
-        s.mouse_move(102.0, 300.0); // 2px — under the threshold
+        s.mouse_move(102.0, 300.0); // 2px: under the threshold
         assert_eq!(s.eval::<i64>("return drag_starts").unwrap(), 0);
 
-        s.mouse_move(110.0, 300.0); // 10px from the press point — starts
+        s.mouse_move(110.0, 300.0); // 10px from the press: starts
         assert_eq!(s.eval::<i64>("return drag_starts").unwrap(), 1);
         assert_eq!(
             s.eval::<String>("return drag_button").unwrap(),
@@ -192,9 +162,7 @@ mod tests {
 
     #[test]
     fn drag_release_on_the_source_still_suppresses_onclick() {
-        // Without the suppression, a same-frame press+release Up would normally fire OnClick
-        // (a plain Frame's OnClick fires on any same-frame release — see `input.rs`'s click
-        // tests) — proving the drag path takes precedence over that default.
+        // A plain Frame fires OnClick on a same-frame release; a started drag suppresses it.
         let mut s = drag_script();
         s.run(
             r#"
@@ -231,7 +199,7 @@ mod tests {
         s.resolve();
 
         s.mouse_button(100.0, 300.0, "LeftButton", true);
-        s.mouse_move(101.0, 300.0); // 1px — never starts
+        s.mouse_move(101.0, 300.0); // 1px: never starts
         s.mouse_button(100.0, 300.0, "LeftButton", false);
         assert_eq!(
             s.eval::<i64>("return clicks").unwrap(),
@@ -241,9 +209,7 @@ mod tests {
         assert!(s.errors().is_empty(), "{:?}", s.errors());
     }
 
-    /// A drag released over the world does NOTHING to the payload — no popup, no clear (decision
-    /// 0218, byte-verified: `0x495300` runs on the WorldFrame click release only; a drag release
-    /// routes as a drag, never a click — the director's "it should require an outside up+down").
+    /// The world drop (`0x495300`) runs on a world click's release, never on a drag release.
     #[test]
     fn drag_release_over_nothing_keeps_carrying_no_popup() {
         let mut s = drag_script();
@@ -279,7 +245,7 @@ mod tests {
         assert_eq!(s.eval::<i64>("return heard").unwrap(), 0, "no popup");
         assert!(s.cursor_item().is_some(), "the payload keeps carrying");
 
-        // The follow-up CLICK on the world (down + up, both over nothing) is the trigger.
+        // The trigger is a full click on the world, down and up over nothing.
         s.mouse_button(-50.0, -50.0, "LeftButton", true);
         assert_eq!(
             s.eval::<i64>("return heard").unwrap(),
@@ -332,17 +298,8 @@ mod tests {
         assert!(s.cursor_item().is_some(), "the payload stays held");
     }
 
-    /// **The world frame IS the world** — B380 / decision 2089, the regression this file's
-    /// other world-drop tests were structurally blind to.
-    ///
-    /// Every one of them clicks at `(-50, -50)`, where the hit test answers `None`, and the gate
-    /// used to be spelled `hit_id.is_none() && pressed.is_none()`. Decision 1983 put the stock
-    /// `WorldFrame` on the manifest — full-screen, mouse-enabled, `SetAllPoints` — so from that
-    /// day every click a player makes on the world hits a frame, the gate went permanently false
-    /// and dropping an item on the ground stopped doing anything at all. It is exactly the
-    /// reference's own click target for a world click (1984: "the press runs the frame's Lua
-    /// `OnMouseDown` (never consuming), then the `BUTTON1`/`BUTTON2` binding — which **is** the
-    /// world click"), so it belongs on the yes side of the predicate.
+    /// A click on the full-screen stock `WorldFrame` is a world click: in the reference, its press
+    /// runs the frame's `OnMouseDown` without consuming, then the `BUTTON1`/`BUTTON2` binding.
     #[test]
     fn a_click_on_the_world_frame_is_a_world_drop() {
         let mut s = drag_script();
@@ -369,7 +326,7 @@ mod tests {
             equip_slots: Vec::new(),
         }));
 
-        // The fixture's own premise: the click really does land on the world frame.
+        // The premise: the click lands on the world frame.
         let hit = s
             .hit_test(400.0, 300.0)
             .expect("the world frame is full-screen");
@@ -383,9 +340,6 @@ mod tests {
         assert!(s.cursor_item().is_some(), "the payload stays held");
     }
 
-    /// …and a UI frame ON TOP of the world frame is still the UI: press and release both land on
-    /// the plate, so no drop — the other half of [`super::over_world`]'s gate, which a predicate
-    /// that merely asked "is a world frame anywhere under the cursor" would get wrong.
     #[test]
     fn a_click_on_a_frame_above_the_world_frame_is_not_a_world_drop() {
         let mut s = drag_script();
@@ -424,8 +378,7 @@ mod tests {
             "the plate ate the click — that IS the UI consuming it"
         );
 
-        // The mixed pair, both ways round: a press on the plate released over the world, and a
-        // press on the world released over the plate. Neither is a completed world click.
+        // A press and release split across the plate and the world, either way: no world click.
         s.mouse_button(100.0, 300.0, "LeftButton", true);
         s.mouse_button(600.0, 300.0, "LeftButton", false);
         s.mouse_button(600.0, 300.0, "LeftButton", true);
@@ -435,9 +388,6 @@ mod tests {
         assert!(s.cursor_item().is_some());
     }
 
-    /// A click on the world frame with an EMPTY cursor is not the UI consuming anything — the
-    /// return the app's arbiter would read if it ever asked. 1984: the world frame's press
-    /// "never consum[es]".
     #[test]
     fn a_world_frame_click_with_no_payload_consumes_nothing() {
         let mut s = drag_script();
@@ -451,10 +401,7 @@ mod tests {
         );
     }
 
-    /// A world object (unit/GameObject) under the cursor suppresses the world drop entirely
-    /// (decisions 0571 + 0574): the reference's object-leg dispatcher (`0x492ce0`) keeps every
-    /// real payload and runs SELECT — no `DELETE_ITEM_CONFIRM`, payload untouched. The app
-    /// feeds the pick (`set_world_pick`); tests/captures default `Nothing`.
+    /// Over a world object the reference's object leg (`0x492ce0`) selects and keeps the payload.
     #[test]
     fn world_click_over_a_world_object_is_not_a_world_drop() {
         let mut s = drag_script();
@@ -492,8 +439,6 @@ mod tests {
         assert!(s.cursor_item().is_some(), "the item payload survives");
     }
 
-    /// A press over a FRAME whose release lands on the world is neither a click on the frame nor
-    /// a world click — the payload is untouched.
     #[test]
     fn frame_press_world_release_is_not_a_world_drop() {
         let mut s = drag_script();
@@ -528,8 +473,7 @@ mod tests {
         assert!(s.cursor_item().is_some());
     }
 
-    /// A spell/action payload world-CLICK clears silently (`0x495300`'s non-item arms); a drag
-    /// release over the world keeps it carrying, same as an item.
+    /// A non-item payload's world click clears it silently (`0x495300`); a drag release keeps it.
     #[test]
     fn world_click_with_a_spell_payload_clears_silently() {
         let mut s = drag_script();
@@ -570,15 +514,6 @@ mod tests {
         assert!(s.cursor_payload().is_none(), "cleared silently");
     }
 
-    /// **A drag the pointer carries out of the window ENDS, and the frame it was moving stops
-    /// following the cursor** (B310).
-    ///
-    /// The reference cannot reach this state — the OS holds the pointer for a button-held drag, so
-    /// the release always arrives — which is exactly why nothing in FrameXML defends against it and
-    /// why the engine has to. Abandoning the gesture *silently* (what this used to do) skips the
-    /// canonical `OnDragStop → StopMovingOrSizing`, so the single move slot stays taken and
-    /// `advance_move` glues the frame to the cursor for the rest of the session, on top of whatever
-    /// the player is trying to click next.
     #[test]
     fn a_gesture_the_pointer_carries_out_of_the_window_still_fires_its_stop() {
         let mut s = drag_script();
@@ -597,10 +532,8 @@ mod tests {
         s.resolve();
 
         s.mouse_button(150.0, 150.0, "LeftButton", true);
-        s.mouse_move(200.0, 200.0); // past the threshold ⇒ OnDragStart ⇒ StartMoving
-                                    // `StartMoving` samples the cursor where it is CALLED, so the starting move moves nothing
-                                    // (`tests::movable`'s own note) — this is the one that carries the frame.
-        s.mouse_move(250.0, 250.0);
+        s.mouse_move(200.0, 200.0); // past the threshold: OnDragStart, StartMoving
+        s.mouse_move(250.0, 250.0); // StartMoving anchors on its call; this move carries
         s.resolve();
         let carried: f32 = s.eval("return A:GetLeft()").unwrap();
         assert_eq!(carried, 150.0, "the frame followed the cursor's 50px");
@@ -612,7 +545,7 @@ mod tests {
             "the abandon fires the same OnDragStop a release would"
         );
 
-        // …and the move slot is free, so nothing follows the cursor any more.
+        // The move slot is free: nothing follows the cursor.
         s.mouse_move(600.0, 500.0);
         s.resolve();
         assert_eq!(
@@ -626,9 +559,6 @@ mod tests {
         assert_eq!(s.eval::<i64>("return stops").unwrap(), 1);
     }
 
-    /// The same abandon, by the other door: a fresh press REPLACES an in-flight gesture, and a
-    /// started one has to be told. Pressing a second button mid-drag is an ordinary slip of the
-    /// hand, and it used to leave the same stuck move slot.
     #[test]
     fn a_press_that_replaces_an_in_flight_gesture_stops_it_first() {
         let mut s = drag_script();
@@ -657,8 +587,7 @@ mod tests {
             "the left drag the right press displaced was stopped, not forgotten"
         );
 
-        // An armed-but-UNSTARTED press fires nothing when it is replaced — the same silence a
-        // release of one gets.
+        // Replacing an unstarted press fires nothing, as releasing it would not.
         s.mouse_button(150.0, 150.0, "LeftButton", true);
         s.mouse_button(150.0, 150.0, "MiddleButton", true);
         assert_eq!(s.eval::<i64>("return stops").unwrap(), 1);
diff --git a/crates/benilla-ui/src/script/cursor/money.rs b/crates/benilla-ui/src/script/cursor/money.rs
index 0167e0bf..e70fbf63 100644
--- a/crates/benilla-ui/src/script/cursor/money.rs
+++ b/crates/benilla-ui/src/script/cursor/money.rs
@@ -1,28 +1,6 @@
-//! The money cursor — payload mode 2 (decisions 1962, 1965): coins picked up off a money frame,
-//! and everything the reference does with them. VERIFIED at the bytes throughout:
-//!
-//! * **The purse is never debited.** Nothing on this path writes `PLAYER_FIELD_COINAGE`; the
-//!   backpack's figure is `GetMoney() − GetCursorMoney() − GetPlayerTradeMoney()`, FrameXML
-//!   arithmetic. Dropping credits nothing back because nothing was taken.
-//! * `PickupPlayerMoney(amount)` raises on a non-number, truncates, and refuses SILENTLY on a zero
-//!   amount, on lost player control, and on more than the purse holds (unsigned). It clears the
-//!   cursor first — whose tail fires `CURSOR_UPDATE` before the money lands — then installs mode 2,
-//!   plays `LOOTWINDOWCOINSOUND`, sets the coin bitmap by magnitude and fires `PLAYER_MONEY`.
-//! * `DropCursorMoney()` is an absolute no-op without money on the cursor; otherwise the coin
-//!   sound, `PLAYER_MONEY`, then mode 0 and `CURSOR_UPDATE`. No drop kit, no packet.
-//! * `CursorHasMoney()` answers the number `1` or `nil`, never a boolean.
-//! * `AddTradeMoney()` (0 args) folds the coins into the trade offer as an ABSOLUTE
-//!   `CMSG_SET_TRADE_GOLD` of `offer + cursor`, gated on the purse covering the total; a refusal
-//!   leaves the money held. Success clears the cursor with no `PLAYER_MONEY`.
-//! * `PickupTradeMoney(amount)` raises on a non-number; `amount <= 0` or `> offer` (both SIGNED)
-//!   refuse silently; else `0x11F` with `offer − amount`, then the coins onto the cursor with
-//!   `PLAYER_MONEY`.
-//! * `GetCoinIcon(amount)` raises on a non-number and answers `INV_Misc_Coin_0N` by the signed
-//!   thresholds of [`coin_icon`] — the cursor's own bitmap goes by the same table.
-//!
-//! One thing this engine's deferred event lane cannot reproduce: the reference's `CURSOR_UPDATE`
-//! handler runs synchronously inside the clear, before the coins land, so `CursorHasMoney()` is
-//! nil there; ours runs at the next dispatch and sees the coins. Named, not hidden.
+//! The money cursor, payload mode 2: coins taken off a money frame; the purse is never debited.
+//! Deviation: a `CURSOR_UPDATE` handler already sees the coins, because events are queued; the
+//! reference runs it inside the clear, before they land.
 
 use mlua::{Lua, Value};
 
@@ -30,9 +8,8 @@ use super::{queue_cursor_update, CursorMoney, CursorPayload};
 use crate::script::binding_abi::{flag, number_arg};
 use crate::script::Model;
 
-/// The coin icon for an amount of copper — `GetCoinIcon 0x48d4e0`'s table, SIGNED thresholds
-/// (a negative amount reads as the smallest coin). The loot window's coin slot and the money
-/// cursor's bitmap use the same table.
+/// The coin icon for an amount of copper: `GetCoinIcon`'s table (`0x48d4e0`), thresholds signed.
+/// The loot window's coin slot and the money cursor use it too.
 pub fn coin_icon(copper: i64) -> &'static str {
     if copper < 10 {
         "Interface\\Icons\\INV_Misc_Coin_05"
@@ -49,7 +26,6 @@ pub fn coin_icon(copper: i64) -> &'static str {
     }
 }
 
-/// The copper on the cursor, `0` when it holds anything else or nothing.
 pub(crate) fn cursor_money(model: &Model) -> u32 {
     match &model.cursor {
         Some(CursorPayload::Money(m)) => m.copper,
@@ -57,17 +33,15 @@ pub(crate) fn cursor_money(model: &Model) -> u32 {
     }
 }
 
-/// Queue `PLAYER_MONEY` — the purse frames' repaint, which is how the held coins leave the
-/// backpack's figure without the purse moving.
+/// Queue `PLAYER_MONEY`, which repaints the money frames less the held coins.
 fn queue_player_money(model: &mut Model) {
     model
         .pending_events
         .push(("PLAYER_MONEY".to_string(), Vec::new()));
 }
 
-/// Put `copper` on the cursor the way `0x494cc0` does: the inner clear (whose tail fires
-/// `CURSOR_UPDATE`, and which fires a `PLAYER_MONEY` of its own when the cursor already held
-/// coins), then the payload, then `PLAYER_MONEY`.
+/// Put coins on the cursor as `0x494cc0` does: the inner clear's `CURSOR_UPDATE`, after its own
+/// `PLAYER_MONEY` if coins were already held, then the payload and `PLAYER_MONEY`.
 fn install_money(model: &mut Model, copper: u32) {
     if matches!(model.cursor, Some(CursorPayload::Money(_))) {
         queue_player_money(model);
@@ -78,7 +52,7 @@ fn install_money(model: &mut Model, copper: u32) {
     queue_player_money(model);
 }
 
-/// `PickupPlayerMoney`'s body after the argument gate.
+/// `PickupPlayerMoney` after the argument gate; each refusal is silent.
 pub(crate) fn pickup_player_money(model: &mut Model, copper: u32) -> bool {
     if copper == 0 || !model.player_control || u64::from(copper) > model.money {
         return false;
@@ -87,7 +61,7 @@ pub(crate) fn pickup_player_money(model: &mut Model, copper: u32) -> bool {
     true
 }
 
-/// `DropCursorMoney`'s body.
+/// `DropCursorMoney`: `PLAYER_MONEY`, then the clear's `CURSOR_UPDATE`, and no packet.
 pub(crate) fn drop_cursor_money(model: &mut Model) -> bool {
     if !matches!(model.cursor, Some(CursorPayload::Money(_))) || !model.player_control {
         return false;
@@ -98,9 +72,8 @@ pub(crate) fn drop_cursor_money(model: &mut Model) -> bool {
     true
 }
 
-/// `AddTradeMoney`'s body, and the money arm `ClickTradeButton` / `ClickTargetTradeButton` and
-/// the trade window's open leg run first: the coins into the offer as an absolute total, gated
-/// on the purse covering it; a refusal leaves them held. Returns whether the coins moved.
+/// `AddTradeMoney`, also run first by `ClickTradeButton`, `ClickTargetTradeButton` and the trade
+/// window's open: the offer becomes offer plus cursor, if the purse covers it.
 pub(crate) fn add_trade_money(model: &mut Model) -> bool {
     let copper = cursor_money(model);
     if copper == 0 {
@@ -122,8 +95,8 @@ pub(crate) fn add_trade_money(model: &mut Model) -> bool {
     true
 }
 
-/// `PickupTradeMoney`'s body after the argument gate: signed gates, the trimmed offer on the
-/// wire first, then the coins onto the cursor.
+/// `PickupTradeMoney` after the argument gate: signed gates, then `CMSG_SET_TRADE_GOLD` (`0x11F`)
+/// with the trimmed offer, then the coins onto the cursor.
 pub(crate) fn pickup_trade_money(model: &mut Model, amount: i32) -> bool {
     let offer = model.trade.as_ref().map_or(0, |t| t.player.gold) as i32;
     if amount <= 0 || amount > offer {
@@ -139,8 +112,7 @@ pub(crate) fn pickup_trade_money(model: &mut Model, amount: i32) -> bool {
 }
 
 impl crate::script::UiScript {
-    /// The trade window's open leg (`SetTradePartner 0x4bf4e0`): coins held on the cursor
-    /// fold into the offer before anything else. Answers the new offer when they did.
+    /// The trade window's open (`SetTradePartner`, `0x4bf4e0`) folds held coins into the offer.
     pub fn fold_cursor_money_into_trade(&mut self) -> Option<u32> {
         let mut model = self.model_mut();
         add_trade_money(&mut model).then(|| model.trade.as_ref().map_or(0, |t| t.player.gold))
@@ -238,7 +210,6 @@ mod tests {
         );
         assert_eq!(s.eval::<i64>("return GetMoney()").unwrap(), 12_345);
         assert!(s.cursor_item().is_none(), "coins are not an item cursor");
-        // The drop: coin sound and PLAYER_MONEY (the app's), mode 0, CURSOR_UPDATE — no packet.
         s.run("DropCursorMoney()").unwrap();
         assert_eq!(s.eval::<i64>("return GetCursorMoney()").unwrap(), 0);
         assert_eq!(s.eval::<i64>("return GetMoney()").unwrap(), 12_345);
diff --git a/crates/benilla-ui/src/script/cursor/pet.rs b/crates/benilla-ui/src/script/cursor/pet.rs
index f8da0966..96216381 100644
--- a/crates/benilla-ui/src/script/cursor/pet.rs
+++ b/crates/benilla-ui/src/script/cursor/pet.rs
@@ -1,35 +1,8 @@
-//! The pet bar's drag (decision 1010) — **one** Lua verb, `PickupPetAction`, which forks on
-//! whether the cursor is already carrying a pet payload. The reference's own bar calls it from all
-//! three gestures (`PetActionButton_OnClick`
-//! under shift, `OnDragStart`, and `OnReceiveDrag` — `PetActionBarFrame.lua:252-283`), so "pick up"
-//! and "drop" are the same binding seen from either side of an empty cursor.
-//!
-//! **Three things set this surface apart from [`super::bar`]'s**, and each is why this is its own
-//! module rather than an arm of that one:
-//!
-//! - **The payload is a WORD, forwarded verbatim.** `0x4bce00` hands the cursor's dword straight to
-//!   the assign core without reading a field of it, and the core's only write is
-//!   `bar[target] = *source`. There is no drop-time encoding — see [`CursorPetAction`].
-//! - **The bar's contents are the SERVER's.** Nothing but a pet slot can produce this payload and
-//!   nothing but a pet slot accepts it, so the drag can only ever *rearrange* ten words the last
-//!   `SMSG_PET_SPELLS` delivered. That is the opposite of the action bar, where the 120-slot table
-//!   is ours and a drag populates it.
-//! - **A displaced occupant is RELOCATED inside the bar before it is handed back.** The action bar
-//!   hops the displaced action onto the cursor unconditionally; here the core first tries to keep
-//!   it on the bar (a duplicate's slot, or an empty non-token slot), and only a target that was
-//!   *not* a token hands its occupant to the cursor.
-//!
-//! **A drop always empties the cursor first** (`0x495190 ClearCursor(1,1)`, run by all three of
-//! `0x4bce00`'s callers *before* the accept decision), and only a write that relocated nothing
-//! re-fills it, with the displaced occupant (`0x4bce38 test eax,eax; je`). So every refusal loses
-//! the payload — read at the bytes, all six of `0x4bc9a0`'s exits: the no-op on an equal dword
-//! (`0x4bc9ed xor eax,eax`), the passive-source reject (`0x4bca28`), the token abort, and both
-//! never-blocking front gates all return `EAX = 0`. 1010 shipped the inverse of this as a named
-//! divergence — a refused drop kept its payload — and the director retired it (1016): the case it
-//! was protecting against is a drop the reference simply does not make, and dropping a pet spell
-//! *away* from the bar is how you take it off the bar in the first place.
-//!
-//! (The **clamp** on slot 11 is still ours, and still deliberate — see [`PET_SLOTS`].)
+//! The pet bar's one drag verb, `PickupPetAction`: a pickup with an empty cursor, a drop with a
+//! pet payload held (`PetActionBarFrame.lua:252-283`). Only a pet slot makes or takes the
+//! payload, a word carried verbatim (`0x4bce00`), so a drag only rearranges the bar the server
+//! sent. A drop clears the cursor before deciding (`0x495190`) and only a write that relocated
+//! nothing refills it (`0x4bce38`), so a refused drop loses the payload, as in the reference.
 
 use mlua::Lua;
 
@@ -37,51 +10,39 @@ use crate::script::Model;
 
 use super::{queue_cursor_update, CursorPayload, CursorPetAction};
 
-/// Pet bar slots — the reference's `NUM_PET_ACTION_SLOTS` and vmangos's
-/// `MAX_UNIT_ACTION_BAR_INDEX`, the same 10.
-///
-/// **The clamp lives here**, and it is a deliberate divergence from the reference's own arithmetic:
-/// its callers gate `cmp esi,0xa; jbe`, which admits index 10 (Lua argument 11), and neither
-/// `0x4bce00` nor `0x4bc9a0` bounds-checks again — so a real client writes one dword *past* the
-/// ten-slot array. Not reproduced.
+/// Pet bar slots (`NUM_PET_ACTION_SLOTS`, vmangos `MAX_UNIT_ACTION_BAR_INDEX`). Deviation: slot
+/// 11 is refused, because the reference's gate (`cmp esi,0xa; jbe`) admits it and neither
+/// `0x4bce00` nor `0x4bc9a0` bounds-checks again, so it writes one dword past the array.
 const PET_SLOTS: u32 = 10;
 
-/// The client's slot type, masked as it masks it (`(packed >> 24) & 0x3F`).
+/// The slot type as the client masks it.
 fn kind(packed: u32) -> u8 {
     ((packed >> 24) & 0x3F) as u8
 }
 
-/// A **token** slot — a command (7) or a reaction (6). The core treats the two identically
-/// everywhere it asks the question: a token occupant is what forces the relocation search, and a
-/// token is what disqualifies a slot from being a relocation candidate.
+/// A command (7) or reaction (6) word, which the core treats alike.
 fn is_token(packed: u32) -> bool {
     matches!(kind(packed), 6 | 7)
 }
 
-/// Can this word ride the cursor at all? `0x494e20`'s own jump table (`0x494f40`) routes types
-/// 1–5 / 6 / 7 and **bails on type 0 or ≥ 8** — so an empty or nonsense word produces no payload,
-/// which is what makes "displaced an empty slot" hand back nothing rather than a blank carry.
+/// The word as a payload, if it can be one: `0x494e20`'s jump table (`0x494f40`) takes types 1-7
+/// only, so displacing an empty slot carries nothing.
 fn payload_word(packed: u32) -> Option<u32> {
     (1..=7).contains(&kind(packed)).then_some(packed)
 }
 
-/// The duplicate scan's comparison key (`0x4bca44`/`0x4bca57`, mask `0x3FFFFFFF`) — everything but
-/// the two autocast bits. **Not** type-1-only: the mask covers the whole type+action field for
-/// any source type.
+/// The duplicate scan's compare (`0x4bca44`, `0x4bca57`): all but the autocast bits, any type.
 fn same_action(a: u32, b: u32) -> bool {
     a & 0x3FFF_FFFF == b & 0x3FFF_FFFF
 }
 
-/// The blanked-spell shape `PickupPetAction` writes back into a picked-from slot: type 1 with a
-/// zero id. The duplicate scan is skipped for exactly this source (`0x4bca34`–`0x4bca3e`) — it
-/// would otherwise match every other blanked slot on the bar.
+/// The word a spell pickup leaves in its slot: type 1, id 0. The duplicate scan skips this
+/// source (`0x4bca34`), which would otherwise match every other blanked slot.
 fn is_blanked_spell(packed: u32) -> bool {
     kind(packed) == 1 && packed & 0xFFFF == 0
 }
 
-/// A relocation **candidate** (`0x4bca8b`–`0x4bcab0`): not a token, and its low 16 bits zero. So an
-/// all-zero slot qualifies and so does a blanked type-1 slot — not simply "token-or-empty" in
-/// either direction.
+/// A slot a token occupant may move to (`0x4bca8b`), such as an empty or blanked-spell slot.
 fn is_relocation_candidate(packed: u32) -> bool {
     !is_token(packed) && packed & 0xFFFF == 0
 }
@@ -90,31 +51,15 @@ fn is_relocation_candidate(packed: u32) -> bool {
 struct Assigned {
     /// The slot the target's previous occupant was moved to, if it was moved.
     reloc: Option<usize>,
-    /// The occupant left with nowhere to go — the cursor's new load. `None` when it was relocated,
-    /// and `None` when the target was empty (nothing to carry).
+    /// The occupant with nowhere to go, for the cursor; `None` if it was relocated or empty.
     displaced: Option<u32>,
 }
 
-/// The assign core `0x4bc9a0(target, source, sendFlag = 1)` — "set a pet action", and the whole of
-/// what a drop does. `None` = nothing was written and nothing should be sent.
-///
-/// The gates, in the binary's order:
-///
-/// 1. **no-op** when the source equals the target's current word, compared as the **full unmasked
-///    dword** (`0x4bc9e2`) — autocast bits included, so re-dropping a slot on itself is inert.
-/// 2. **silent reject** of a passive spell source (`0x4bc9f8`–`0x4bca2e`). No error id, unlike the
-///    player bar's `PlaceAction`, which raises `0x9e` for the same test.
-/// 3. **duplicate scan**, slots ascending: the first slot that carries the same action (and is not
-///    the target) becomes the relocation slot, and the token search is **short-circuited entirely**
-///    (`0x4bca78`). This is what makes the ordinary drag a swap.
-/// 4. otherwise, if the target's occupant **is a token**, search for a candidate slot to move it
-///    to; **no candidate ⇒ abort**, nothing written and nothing sent.
-/// 5. write `bar[reloc] = old occupant` (when there is one) and `bar[target] = source`.
-///
-/// The reference's return value is `EAX = 1` iff **no** relocation happened (`0x4bcb92 setl`) —
-/// so an abort and a successful relocation are indistinguishable at the call. That is the one thing
-/// a re-implementation must not read as "did the write happen", which is why this returns
-/// [`Assigned`] and never a bool.
+/// The assign core (`0x4bc9a0`), the whole of a drop; `None` is no write and no send. In order:
+/// an identical dword is a no-op (`0x4bc9e2`), a passive spell is refused silently (`0x4bc9f8`),
+/// a duplicate's slot takes the occupant, which makes a drag a swap (`0x4bca78`), else a token
+/// occupant needs a candidate slot or the drop aborts. The reference's return (`0x4bcb92`), 1
+/// only when nothing was relocated, cannot tell an abort from a relocation; this one can.
 fn assign(slots: &mut [u32], target: usize, source: u32, passive: bool) -> Option<Assigned> {
     let occupant = *slots.get(target)?;
     if occupant == source {
@@ -129,11 +74,9 @@ fn assign(slots: &mut [u32], target: usize, source: u32, passive: bool) -> Optio
         reloc = (0..slots.len()).find(|&i| i != target && same_action(slots[i], source));
     }
     if reloc.is_none() && is_token(occupant) {
-        // No `j != target` guard, and none is needed: this branch only runs when the target's own
-        // occupant IS a token, which disqualifies it as a candidate. The bytes have no guard here
-        // either.
+        // No `j != target` guard, as in the reference: the target's token is never a candidate.
         reloc = (0..slots.len()).find(|&j| is_relocation_candidate(slots[j]));
-        reloc?; // the abort — a token occupant with nowhere to go writes and sends nothing
+        reloc?; // the abort: a token with nowhere to go writes and sends nothing
     }
 
     if let Some(j) = reloc {
@@ -146,21 +89,10 @@ fn assign(slots: &mut [u32], target: usize, source: u32, passive: bool) -> Optio
     })
 }
 
-/// `PickupPetAction(slot)` — the pet bar's one drag verb, 1-based (ref
-/// `PetActionBarFrame.lua:252-283`; the binding `0x4be180`).
-///
-/// - **`UNIT_FLAG_POSSESSED` set** ⇒ nothing at all. The gate sits above the cursor fork
-///   (`0x4be1c1`), so it blocks the drop as well as the pick-up.
-/// - **carrying a pet payload** ⇒ [`place_pet_action`].
-/// - **carrying anything else** ⇒ nothing. The reference only enters its drop trampoline when the
-///   *pet* payload global is non-empty; a held spell or item is not that global and simply stays
-///   held. (Which is the same fact as "a pet bar cannot be populated, only rearranged".)
-/// - **empty cursor** ⇒ pick the slot up: the payload is its word verbatim, and — **for a spell
-///   slot only** (`0x4be268 cmp cl,1`) — the slot is written back with its id zeroed, through the
-///   same assign core and with the same send. A token slot keeps its contents while its word rides
-///   the cursor, which is how a command ends up *copied* onto another slot rather than moved.
-///
-/// Returns whether the caller should repaint.
+/// `PickupPetAction(slot)` (`0x4be180`), 1-based. `UNIT_FLAG_POSSESSED` blocks both ends, its
+/// gate sitting above the cursor fork (`0x4be20a`). Another payload stays held here, where the
+/// reference clears it (`0x4be220`) and picks the slot up. A pickup blanks only a spell slot
+/// (`0x4be268`), so a dragged token is copied, not moved.
 pub(super) fn pickup_pet_action(model: &mut Model, slot: u32) -> bool {
     if !model.pet_bar.pickup_allowed {
         return false;
@@ -184,13 +116,8 @@ pub(super) fn pickup_pet_action(model: &mut Model, slot: u32) -> bool {
         passive: view.passive,
         texture: view.texture.clone(),
     }));
-    // A SPELL slot empties as it is picked up — id zeroed, type and autocast bits kept — and the
-    // server is told. Everything else keeps its slot.
-    //
-    // `passive: false` is not a shortcut: the assign core's passive gate reads the record of the
-    // **source word's own spell id**, and the blanked word's id is 0, which resolves to no record
-    // at all. So a passive spell still empties its slot when picked up — the refusal comes later,
-    // when the payload is dropped somewhere.
+    // A spell slot keeps its type and autocast bits with id 0, and the server is told. `false` is
+    // right: the passive gate reads the source's spell record, and id 0 has none.
     if kind(packed) == 1 {
         write_slot(model, index, packed & 0xFFFF_0000, false);
     }
@@ -198,31 +125,19 @@ pub(super) fn pickup_pet_action(model: &mut Model, slot: u32) -> bool {
     true
 }
 
-/// The drop half. Runs the assign core against the engine's optimistic mirror of the ten words,
-/// queues the resulting `(0-based position, word)` pairs for the app to send as one
-/// `CMSG_PET_SET_ACTION`, and disposes of the cursor:
-///
-/// - **write, occupant homeless** ⇒ the occupant goes onto the cursor (the trampoline's
-///   `0x4bce3d`, reached only on the core's `EAX = 1`) — the familiar swap-in-hand.
-/// - **write, occupant relocated** ⇒ the cursor empties; the displaced word is still on the bar.
-/// - **no write** (self-drop, passive source, or the token abort) ⇒ the cursor empties too, and
-///   the payload is gone. `ClearCursor` ran before the decision and `EAX = 0` never re-fills.
-///
-/// The cursor is therefore emptied on **every** path out of here, including the ones that return
-/// `false` — `false` is "nothing was written", not "nothing happened".
+/// The drop: the cursor always empties, and only a homeless occupant refills it (`0x4bce3d`).
+/// Returns whether anything was written; the cursor empties on `false` too.
 fn place_pet_action(model: &mut Model, slot: u32) -> bool {
     let Some(CursorPayload::PetAction(held)) = model.cursor.clone() else {
         return false;
     };
-    // `ClearCursor(1,1)` — unconditional, and *before* anything is decided. Past the possessed
-    // gate in `PickupPetAction` there is no way back out of here still holding the payload.
+    // `ClearCursor(1,1)`, unconditionally, before anything is decided.
     model.cursor = None;
     let Some(index) = slot_index(model, slot) else {
         queue_cursor_update(model);
         return false;
     };
-    // The target's own view, read BEFORE the write — a displaced word's passive bit and icon are
-    // its slot's, not the payload's we are about to consume.
+    // Read before the write: a displaced word's passive bit and icon are its slot's.
     let occupant_view = model.pet_bar.slots[index].view.clone();
     let Some(assigned) = write_slot(model, index, held.packed, held.passive) else {
         queue_cursor_update(model);
@@ -241,7 +156,7 @@ fn place_pet_action(model: &mut Model, slot: u32) -> bool {
     true
 }
 
-/// The 1-based button index → an in-range slot of a bar that exists.
+/// The 0-based index of a 1-based slot on a bar that exists.
 fn slot_index(model: &Model, slot: u32) -> Option<usize> {
     if !model.pet_bar.has_bar || slot == 0 || slot > PET_SLOTS {
         return None;
@@ -250,20 +165,14 @@ fn slot_index(model: &Model, slot: u32) -> Option<usize> {
     (index < model.pet_bar.slots.len()).then_some(index)
 }
 
-/// Run [`assign`] against the engine's mirror and queue what changed. Split out because the pickup
-/// path needs it too — the reference routes its own slot-blanking through the same core, with the
-/// same send (`0x4be268`+).
-///
-/// The mirror is optimistic in exactly [`super::bar`]'s sense: the app owns the authoritative ten
-/// words and re-pushes them, but a drag must read right in the same frame it happens.
+/// Run [`assign`] on the engine's optimistic mirror of the ten words and queue the send; the
+/// pickup's blank goes through it too, as in the reference (`0x4be268`).
 fn write_slot(model: &mut Model, target: usize, source: u32, passive: bool) -> Option<Assigned> {
     let mut words: Vec<u32> = model.pet_bar.slots.iter().map(|s| s.view.packed).collect();
     let assigned = assign(&mut words, target, source, passive)?;
 
-    // One send carrying one or two `(position, data)` pairs — the optional relocation pair FIRST,
-    // then the mandatory target pair, exactly the order `0x4bcad4`+ builds them and exactly what
-    // `CMSG_PET_SET_ACTION` accepts. The relocation pair goes out whenever there was a relocation,
-    // without re-testing whether the word changed: that is the binary's own `if (relocSlot >= 0)`.
+    // One `CMSG_PET_SET_ACTION`: the relocation pair first whenever there was one, changed or
+    // not, then the target pair (`0x4bcad4`).
     let mut entries: Vec<(u32, u32)> = Vec::with_capacity(2);
     if let Some(j) = assigned.reloc {
         entries.push((j as u32, words[j]));
@@ -277,14 +186,8 @@ fn write_slot(model: &mut Model, target: usize, source: u32, passive: bool) -> O
     Some(assigned)
 }
 
-/// A **token** word's `texture` is the NAME of a global, not a path — `GetPetActionInfo 0x4bdc50`'s
-/// own convention: the two `char[32]` tables hand back `PET_ATTACK_TEXTURE`, and the bar paints
-/// with `getglobal(texture)`. The cursor takes a PATH, so a command or reaction word that reaches
-/// the cursor has to carry one, or the drag is invisible — you pick Attack up and nothing sticks
-/// to the pointer. Resolved here, the one place a slot's view becomes a cursor payload, exactly as
-/// `PetActionBar.xml` resolves it in the one place a slot's view becomes a button.
-///
-/// A spell word already carries a real `Interface\Icons\…` path and is left alone.
+/// A token's texture is a global's name (`GetPetActionInfo`, `0x4bdc50`), which the bar resolves
+/// with `getglobal` (`PetActionBarFrame.lua:102`); the cursor needs the path, resolved here.
 fn resolve_token_icon(lua: &Lua) {
     let name = {
         let model = lua.app_data_ref::<Model>().expect("model app_data");
@@ -312,8 +215,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 let mut model = lua.app_data_mut::<Model>().expect("model app_data");
                 pickup_pet_action(&mut model, slot)
             };
-            // Both halves can leave a TOKEN on the cursor — the pick-up directly, the drop through
-            // its displaced occupant — so the resolution hangs off the binding, not off either arm.
+            // Both the pickup and a drop's displaced occupant can put a token on the cursor.
             resolve_token_icon(lua);
             Ok(took)
         })?,
@@ -326,9 +228,8 @@ mod tests {
     use super::*;
     use crate::script::{PetActionView, UiScript};
 
-    /// The words a hunter's bar actually carries. `FILLER` is vmangos's own unused-slot shape
-    /// (`ACT_DISABLED` + spell id 0) — masked type 1 with a zero low word, which is exactly the
-    /// relocation candidate the core hunts for, and the reason it must not be flattened to 0.
+    /// A hunter's bar words. `FILLER` is vmangos's unused slot, `ACT_DISABLED` with spell 0: type
+    /// 1, not a zero word, so it must stay as sent.
     const ATTACK: u32 = 0x0700_0002;
     const FOLLOW: u32 = 0x0700_0001;
     const DEFENSIVE: u32 = 0x0600_0001;
@@ -337,9 +238,7 @@ mod tests {
     const BITE: u32 = 0x8100_0EC1;
     const FILLER: u32 = 0x8100_0000;
 
-    /// A source that is **still on the bar** swaps with its destination: the duplicate scan finds
-    /// the copy, that slot takes the occupant, and the cursor comes away empty. This is the path a
-    /// TOKEN drag always takes, because a token pickup does not blank its source slot.
+    /// A token drag always takes this path: a token pickup leaves its slot as it was.
     #[test]
     fn a_source_still_on_the_bar_swaps_with_its_destination() {
         let mut bar = [CLAW, GROWL, FILLER, ATTACK];
@@ -350,9 +249,7 @@ mod tests {
         assert_eq!(a.displaced, None, "nothing left over to carry");
     }
 
-    /// A SPELL drag is the other shape, and the pickup's blank is what makes it so: a blanked
-    /// source is the one thing the duplicate scan skips (`0x4bca34`), so nothing matches and the
-    /// occupant is displaced onto the cursor instead.
+    /// The pickup's blank (the duplicate scan skips it, `0x4bca34`) leaves no copy to swap with.
     #[test]
     fn a_blanked_source_displaces_the_occupant_instead_of_swapping() {
         let mut bar = [CLAW, GROWL, FILLER, ATTACK];
@@ -364,8 +261,6 @@ mod tests {
         assert_eq!(a.displaced, Some(GROWL));
     }
 
-    /// A TOKEN occupant is never displaced onto the cursor: the core relocates it to the first
-    /// candidate (not a token, low 16 zero) and the cursor comes away empty.
     #[test]
     fn a_token_occupant_is_relocated_not_displaced() {
         let mut bar = [CLAW, ATTACK, FILLER, DEFENSIVE];
@@ -376,9 +271,6 @@ mod tests {
         assert_eq!(a.displaced, None, "nothing is left over to carry");
     }
 
-    /// …and with nowhere to put it, the whole assignment ABORTS: no write, no send. The reference
-    /// reports this identically to a successful relocation (`EAX = 0`), which is why the outcome
-    /// here is an `Option` and never a bool.
     #[test]
     fn a_token_occupant_with_no_candidate_aborts_entirely() {
         let mut bar = [CLAW, ATTACK, GROWL, DEFENSIVE];
@@ -387,15 +279,12 @@ mod tests {
         assert_eq!(bar, before, "nothing written");
     }
 
-    /// The two silent refusals: dropping a word onto the slot it already occupies (compared as the
-    /// FULL dword, autocast bits and all), and a passive spell source.
     #[test]
     fn the_self_drop_and_the_passive_source_are_no_ops() {
         let mut bar = [CLAW, GROWL, FILLER, ATTACK];
         assert!(assign(&mut bar, 0, CLAW, false).is_none());
         assert!(assign(&mut bar, 1, CLAW, true).is_none(), "passive source");
-        // The autocast bit is part of the compare — the same spell with its ring flipped is a
-        // different word and DOES write.
+        // The autocast bit is part of the compare: flipped, the same spell writes.
         assert!(assign(&mut bar, 0, CLAW & !0x4000_0000, false).is_some());
     }
 
@@ -407,8 +296,7 @@ mod tests {
         }
     }
 
-    /// A token slot as the feed really pushes it: `name` and `texture` are both the NAMES OF
-    /// GLOBALS, which is `GetPetActionInfo`'s own convention for types 6 and 7.
+    /// A token slot as fed: `name` and `texture` are global names, as from `GetPetActionInfo`.
     fn token_view(packed: u32, name: &str, texture: &str) -> PetActionView {
         PetActionView {
             is_token: true,
@@ -417,8 +305,7 @@ mod tests {
         }
     }
 
-    /// A hunter's default bar: three commands, four spell slots (two known, two filler), three
-    /// reactions — the arrangement `CharmInfo::InitPetActionBar` writes.
+    /// A hunter's default bar, as vmangos `CharmInfo::InitPetActionBar` lays it out.
     fn hunter_bar() -> Vec<PetActionView> {
         vec![
             token_view(ATTACK, "PET_ACTION_ATTACK", "PET_ATTACK_TEXTURE"),
@@ -440,8 +327,6 @@ mod tests {
         s
     }
 
-    /// Picking a SPELL slot up empties it — id zeroed, type and autocast bits kept — and tells the
-    /// server in the same breath. The payload is the word verbatim.
     #[test]
     fn picking_up_a_spell_blanks_its_slot_and_sends() {
         let mut s = bar_script();
@@ -458,12 +343,6 @@ mod tests {
         );
     }
 
-    /// A dragged TOKEN carries a real icon PATH, not the name of the global that holds one.
-    ///
-    /// `GetPetActionInfo` hands a token slot `("PET_ACTION_ATTACK", …, "PET_ATTACK_TEXTURE")` —
-    /// two global names — and the bar paints with `getglobal`. The cursor cannot: it needs a path
-    /// to decode, so an unresolved name means dragging Attack, Follow or Stay sticks *nothing* to
-    /// the pointer, which is what the director saw. A spell slot's path is left exactly as it is.
     #[test]
     fn a_dragged_token_carries_a_resolved_icon_path() {
         let mut s = UiScript::new().unwrap();
@@ -481,8 +360,7 @@ mod tests {
             "the global was resolved, not carried as a name"
         );
 
-        // An unset global resolves to nothing rather than to its own name — better a missing icon
-        // than a path that cannot exist.
+        // An unset global resolves to no icon, not to its own name.
         s.run("ClearCursor() PET_ATTACK_TEXTURE = nil PickupPetAction(1)")
             .unwrap();
         let Some(CursorPayload::PetAction(p)) = s.cursor_payload() else {
@@ -491,8 +369,6 @@ mod tests {
         assert_eq!(p.texture, None);
     }
 
-    /// A TOKEN slot keeps its contents while its word rides the cursor (`0x4be268 cmp cl,1` — the
-    /// blank is type-1-only), so a command ends up COPIED onto its destination rather than moved.
     #[test]
     fn picking_up_a_token_leaves_the_slot_alone() {
         let mut s = bar_script();
@@ -503,9 +379,6 @@ mod tests {
         );
     }
 
-    /// The whole gesture, end to end: pick a spell up and drop it two slots along. The pickup's
-    /// blank and the drop's write are two separate sends, and the displaced spell comes back on
-    /// the cursor.
     #[test]
     fn a_drag_between_two_spell_slots_sends_twice_and_carries_the_occupant() {
         let mut s = bar_script();
@@ -522,9 +395,8 @@ mod tests {
         );
     }
 
-    /// Dropping onto a COMMAND relocates that command to a filler slot instead of handing it back
-    /// — the cursor comes away empty, and ONE send carries both pairs (the server tells the two
-    /// forms apart by body size, so they must not be split).
+    /// The relocation and the write share one send: the server counts the pairs by body size
+    /// (vmangos `Server/Packets/Pet.cpp:56`).
     #[test]
     fn dropping_onto_a_token_relocates_it_in_one_send() {
         let mut s = bar_script();
@@ -540,13 +412,8 @@ mod tests {
         assert!(s.eval::<bool>("return GetCursorInfo() == nil").unwrap());
     }
 
-    /// A refused drop **eats** the payload — `ClearCursor` ran before the decision and `EAX = 0`
-    /// never re-fills. 1010 shipped the inverse as a named divergence; 1016 retired it.
-    ///
-    /// The reachable refusal is the passive-spell source: the pickup has no passive gate, so a
-    /// passive slot picks up fine and is then refused everywhere it is dropped. Losing it is not
-    /// the data loss it looks like — the pickup's blank already went to the server, which is
-    /// exactly how a pet spell is taken off the bar.
+    /// The reachable refusal is a passive spell, which the pickup does not gate; its blank
+    /// already went to the server, which is how a pet spell is taken off the bar.
     #[test]
     fn a_refused_drop_eats_the_payload() {
         let mut s = UiScript::new().unwrap();
@@ -569,8 +436,6 @@ mod tests {
         );
     }
 
-    /// The clamp. The reference's callers admit Lua argument 11 and its assign core never bounds
-    /// again, so a real client writes one dword past the array; we refuse instead.
     #[test]
     fn slot_eleven_is_refused_rather_than_written_past_the_array() {
         let mut s = bar_script();
@@ -580,8 +445,7 @@ mod tests {
         assert!(s.eval::<bool>("return GetCursorInfo() == nil").unwrap());
     }
 
-    /// `UNIT_FLAG_POSSESSED` blocks BOTH ends, because the reference's gate sits above the cursor
-    /// fork: you cannot pick a possessed unit's slot up, and you cannot drop onto its bar either.
+    /// The third flag, `pickup_allowed`, is false under `UNIT_FLAG_POSSESSED`.
     #[test]
     fn a_possessed_bar_takes_no_drag_at_all() {
         let mut s = UiScript::new().unwrap();
@@ -590,9 +454,6 @@ mod tests {
         assert!(s.take_pet_set_actions().is_empty());
     }
 
-    /// The two payload spaces do not overlap in either direction, and the two grids follow them:
-    /// a held spell lights the ACTION bar's grid and cannot land on a pet slot; a held pet action
-    /// lights the PET bar's and cannot land on an action slot.
     #[test]
     fn the_pet_payload_and_the_action_bar_refuse_each_other() {
         let mut s = bar_script();
diff --git a/crates/benilla-ui/src/script/cvars.rs b/crates/benilla-ui/src/script/cvars.rs
index e8d37e63..5a976354 100644
--- a/crates/benilla-ui/src/script/cvars.rs
+++ b/crates/benilla-ui/src/script/cvars.rs
@@ -1,55 +1,34 @@
-//! The **CVar table** — the client's named-console-variable store, engine side (decision 0954).
+//! The CVar table: the reference's store of case-insensitively named string settings with
+//! registered defaults, behind `GetCVar`/`SetCVar`/`GetCVarDefault`/`RegisterCVar`.
 //!
-//! In the reference every player setting is a CVar: a case-insensitively named string value with
-//! a registered default, read and written from Lua through `GetCVar`/`SetCVar`/`GetCVarDefault`
-//! (the 1.12 options panels are thin UI over this table). benilla keeps the same shape at the
-//! same seam: the **host registers** the vars it implements
-//! ([`super::UiScript::register_cvars`] — most backed by an engine knob, a few consumed by Lua
-//! alone), Lua reads/writes them synchronously, and each Lua write lands on the **change queue** the host
-//! drains per frame ([`super::UiScript::take_cvar_changes`]) to sync its resources and mark the
-//! config file dirty. Host-side writes ([`super::UiScript::set_cvar_host`] — the loaded config,
-//! an env override) do NOT ride the queue: the host already knows, and an echo would re-dirty
-//! the file it just loaded.
-//!
-//! Values are **strings**, like the client's (`GetCVar` returns a string; consumers parse and
-//! clamp at their own edge). An unknown name warns once and no-ops — a benilla CVar is either
-//! host-registered or addon-declared through `RegisterCVar` (decision 1195), so an unknown key
-//! is a typo or an unshipped feature, never a storage slot.
-//!
-//! **The table dies with the VM, so persistence bridges it** (decision 1291): in the reference
-//! this store is engine memory and survives every `ReloadUI`; ours is per-VM state, replaced at
-//! every login and reload (1290/1291). The host hands each fresh VM the config file's values
-//! ([`super::UiScript::set_cvar_saved_base`]) before anything registers, and registration —
-//! either kind — starts a key at its saved value. The host folds the dying VM's table back into
-//! its persist state on the session edge, so the two halves meet.
+//! The host registers the vars it backs and drains Lua's writes from a change queue; its own
+//! writes do not queue. The table dies with the VM, where the reference's outlives every
+//! `ReloadUI`, so the host seeds each new VM with the saved values before anything registers.
+//! An unknown name warns once and is ignored (`GetCVar` answers nil), where the reference's
+//! `GetCVar`, `SetCVar` and `GetCVarDefault` raise `Couldn't find CVar named '%s'` (`0x842310`).
 
 use mlua::{Lua, Value};
 
 use super::{Model, ScriptValue};
 
-/// One registered CVar: the host's spelling (for change events and the config file), the live
-/// value, and the registered default (`GetCVarDefault`, and the saver's "only write what moved").
+/// One registered CVar.
 #[derive(Clone, Debug)]
 pub(crate) struct CvarSlot {
-    /// The registered spelling (`MasterVolume`), reported on change events and in snapshots;
-    /// the table key is the lowercase form (the client's lookups are case-insensitive).
+    /// The registered spelling, reported on change events and in snapshots; the table key is
+    /// its lowercase form.
     pub name: String,
     pub value: String,
     pub default: String,
-    /// The reference's flag bit1 (`rec+0x1c & 0x2`, decision 2303): a write lands in
-    /// [`Self::pending`] instead of [`Self::value`], so `GetCVar` keeps answering the applied
-    /// value until the host commits the latch (`CVar::Update 0x63e060` — for the `gx*` rows,
-    /// inside `RestartGx`). Seeded by the host ([`super::UiScript::seed_cvars`]); a row the VM
-    /// registers on its own is never latched, exactly like the console `set` command's create
-    /// path in the reference.
+    /// The reference's flag bit1 (`rec+0x1c & 0x2`): a write goes to [`Self::pending`] and
+    /// `GetCVar` answers the applied value until the host commits it (`CVar::Update 0x63e060`).
+    /// Host-seeded only; a VM-registered row is never latched, like a console-created one.
     pub latched: bool,
-    /// The staged value of a latched row — what the host will commit at the boundary, and what
-    /// it is told about through the change queue the moment it is written.
+    /// A latched row's staged value, reported to the host through the change queue when written.
     pub pending: Option<String>,
 }
 
-/// One row of the host's registry, as the VM's mirror is seeded from it (decision 2303): the
-/// registered spelling, the **applied** value, the registered default, and the latch flag.
+/// One row of the host's registry as the VM's mirror is seeded from it; `value` is the applied
+/// value.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct SeededCvar {
     pub name: String,
@@ -58,16 +37,9 @@ pub struct SeededCvar {
     pub latched: bool,
 }
 
-/// One device-supported multisample format, as the Video options dropdown shows it.
-///
-/// The reference's distilled triple (`[0xb4b444]`, count `[0xb4b440]`, built by `0x48c3e0`), and
-/// the shape `MULTISAMPLING_FORMAT_STRING` formats: `"%d-bit color %d-bit depth %dx multisample"`.
-///
-/// `samples == 1` is the encoding of **no multisampling**, not "one sample of it" — the convention
-/// both of the reference's enumerators normalise to (`0x58b8b1`'s jump table maps
-/// `D3DMULTISAMPLE_NONE → 1`; the GL path at `0x58d5fa`/`0x58d5fe`/`0x58d605` turns a failed
-/// `WGL_SAMPLES_ARB` query or a value of 0 into 1), and the same convention the device paths test
-/// with `> 1`.
+/// One multisample format the device supports, the reference's triple (`[0xb4b444]`, count
+/// `[0xb4b440]`, built by `0x48c3e0`). `samples == 1` means no multisampling, as both reference
+/// enumerators normalise it (D3D `0x58b8b1`, GL `0x58d5fa`) and the device paths test `> 1`.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct MultisampleFormat {
     pub color_bits: u32,
@@ -75,18 +47,10 @@ pub struct MultisampleFormat {
     pub samples: u32,
 }
 
-/// One screen resolution the Video options dropdown offers, in **physical pixels**.
-///
-/// The reference enumerates the graphics device's own display modes; benilla has no exclusive
-/// mode-set to make (`benilla_app::video`'s module doc: Wayland has no client-side mode-setting,
-/// X11's is XRandR on the *desktop*, macOS has none, and WoW itself deleted exclusive fullscreen in
-/// 8.0.1), so the list is the sizes this client can actually present a window at. Either way it is
-/// a fact about the display that the VM cannot ask for itself, so the host pushes it.
-///
-/// **The `"WxH"` spelling is the contract, not a convenience.** `OptionsFrame.lua:281-284` finds
-/// the `x`, `strsub`s both sides and evaluates `width/height > 4/3` for the WIDESCREEN tag, and
-/// `CT_Viewport.lua:107` re-reads it with `string.find(currRes, "(%d+)x(%d+)")`. Two independent
-/// consumers, both of which fail silently on a space, a suffix, or an `X`.
+/// One screen resolution the Video options dropdown offers, in physical pixels. Deviation: the
+/// list is the window sizes this client can present, not the device's display modes, because
+/// benilla makes no exclusive mode-set. `"WxH"` is a contract: `OptionsFrame.lua:281-284` splits
+/// on the `x` and `CT_Viewport.lua:107` matches `"(%d+)x(%d+)"`, both failing silently.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct ScreenResolution {
     pub width: u32,
@@ -94,9 +58,9 @@ pub struct ScreenResolution {
 }
 
 impl ScreenResolution {
-    /// The reference's ordering key, made total: **pixel area first** (`0x58be40`'s whole body is
-    /// `a.h*a.w - b.h*b.w`), then width, then height. The tie-break is ours — see
-    /// [`super::UiScript::set_screen_resolutions`].
+    /// Pixel area first, the reference's whole comparator (`0x58be40`), then width, then height.
+    /// Deviation: the tie-break is ours, because area alone with the reference's adjacent-only
+    /// dedupe can leave a duplicate `"WxH"` when two modes share an area (1280x960, 1600x768).
     pub(crate) fn sort_key(&self) -> (u64, u32, u32) {
         (
             u64::from(self.width) * u64::from(self.height),
@@ -112,52 +76,29 @@ impl std::fmt::Display for ScreenResolution {
     }
 }
 
-/// What `GetVideoCaps` answers with — the seven values `OptionsFrame_Load` destructures at
-/// `OptionsFrame.lua:59`, in that order.
-///
-/// ```lua
-/// local hasAnisotropic, hasPixelShaders, hasVertexShaders, hasTrilinear,
-///       hasTripleBuffering, maxAnisotropy, hasHardwareCursor = GetVideoCaps();
-/// ```
-///
-/// In the reference these are the D3D/GL device's own answers, cached at start-up. Here they are
-/// what wgpu and this client's own presentation path really do — pushed by the host, which is the
-/// only side that holds a `RenderAdapter`.
+/// What `GetVideoCaps` answers, in `OptionsFrame.lua:59`'s order: anisotropic, pixel shaders,
+/// vertex shaders, trilinear, triple buffering, max anisotropy, hardware cursor. The host pushes
+/// what wgpu and this client's presentation path really offer.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
 pub struct VideoCaps {
     pub anisotropic: bool,
     pub pixel_shaders: bool,
     pub vertex_shaders: bool,
     pub trilinear: bool,
-    /// **A BACKEND constant, not a device capability** — `caps+0x20` is written by the two device
-    /// constructors only (1 under Direct3D, 0 under OpenGL) and read by `GetVideoCaps` alone, so
-    /// `hasTripleBuffering == 1` means "the backend is Direct3D". Its name is the one INFERRED
-    /// label in the seven (`GetVideoCaps 0x48db40`).
-    ///
-    /// `false` here, and it is pushed as the **number 0**, never nil: benilla is not Direct3D and
-    /// exposes no buffering knob, so check button 13 is hidden and button 6 re-seated
-    /// (`OptionsFrame.lua:168-175`) — while the file's two `not hasTripleBuffering` clauses stay
-    /// dead, which is what the reference does in both backends.
+    /// A backend constant, not a device capability: 1 under Direct3D, 0 under OpenGL
+    /// (`caps+0x20`, read only by `GetVideoCaps 0x48db40`). False here, pushed as the number 0.
     pub triple_buffering: bool,
-    /// The raw maximum sample count, matched against `ANISOTROPIC_VALUES = {"1","2","4","8","16"}`
-    /// with `tonumber` (`OptionsFrame.lua:124`) — so it must be one of those numbers to move the
-    /// slider's ceiling, and anything else leaves `value.maxValue` where it was. Pushed raw, or
-    /// **nil iff 0**; the reference is effectively never nil here (its base ctor seeds the field
-    /// to 1), which is why its consumers gate on slot 1 or on `< 2` rather than on nil.
+    /// The raw maximum: `OptionsFrame.lua:122-127` makes a value in `ANISOTROPIC_VALUES` the
+    /// slider's ceiling as its index, and any other number the ceiling as is. Pushed as nil when 0.
     pub max_anisotropy: u32,
     pub hardware_cursor: bool,
 }
 
 impl super::UiScript {
-    /// Hand registration the config file's persisted values (decision 1291): name → value, keys
-    /// lowercased here. Set **before** any `register_cvars` / addon `RegisterCVar` runs in this
-    /// VM; a name registered while present here starts at the saved value instead of its default.
-    ///
-    /// This is the bridge that makes the per-VM table behave like the reference's engine-side
-    /// one (where the store outlives every `ReloadUI`): a CVar with no host knob
-    /// (`statusBarText`) and a CVar only an addon declares would otherwise revert to default on
-    /// every VM replacement — and the saver, seeing value == default, would then *strip the
-    /// player's setting from the file*.
+    /// Hand registration the config file's saved values (keys lowercased), before any
+    /// `register_cvars` or `RegisterCVar` runs in this VM: a name registered while present here
+    /// starts at its saved value. Without it a knobless or addon-declared CVar would revert to its
+    /// default in every new VM, and the saver would then drop the player's setting from the file.
     pub fn set_cvar_saved_base(&mut self, entries: impl IntoIterator<Item = (String, String)>) {
         self.model_mut().cvars_saved_base = entries
             .into_iter()
@@ -165,16 +106,10 @@ impl super::UiScript {
             .collect();
     }
 
-    /// Register the host-backed CVars (name, default) — boot-time, idempotent. A re-register of
-    /// a live table refreshes defaults but never clobbers a value someone already set. A fresh
-    /// registration starts at the saved-base value when the config file carries one
-    /// ([`Self::set_cvar_saved_base`]), else at the default.
-    ///
-    /// Takes `&self` rather than `&mut self` because the table lives behind the VM's app-data
-    /// (interior mutability), and the interface loader has to be able to guarantee it from a
-    /// `&UiScript` — the stock `UIOptionsFrame.xml` reads CVars in its own `OnLoad`, so a VM that
-    /// loads the client's interface without the client's CVar table is not the client
-    /// (decision 2115).
+    /// Register the host-backed CVars as `(name, default)`, idempotently: a re-register refreshes
+    /// the default and keeps a live value, and a new row starts at its saved value if the config
+    /// file has one. `&self` so the interface loader can register from a `&UiScript`: the stock
+    /// `UIOptionsFrame.xml` reads CVars in its own `OnLoad`.
     pub fn register_cvars<'a>(&self, vars: impl IntoIterator<Item = (&'a str, &'a str)>) {
         let mut model = self.model_mut();
         for (name, default) in vars {
@@ -202,15 +137,9 @@ impl super::UiScript {
         }
     }
 
-    /// Seed the mirror from the host's registry (decision 2303): every row's spelling, applied
-    /// value, default and latch flag, creating or overwriting the slot. This is what a fresh VM
-    /// gets at claim time and at the world-entry edge — the host's table is the store that
-    /// outlives the VM, so the mirror starts wherever it stands, and a re-seed of a live table
-    /// is the host re-asserting its truth (a staged value is dropped with it: the host holds
-    /// the pending copy and pushes it back through the outbox if it still stands).
-    ///
-    /// `&self` for [`Self::register_cvars`]'s reason — the interface loader seeds from a
-    /// `&UiScript` before the stock files read their first CVar (decision 2115).
+    /// Seed the mirror from the host's registry, creating or overwriting each row. The host's
+    /// table outlives the VM, so a re-seed re-asserts it and drops any staged value (the host
+    /// holds the pending copy). `&self` for [`Self::register_cvars`]'s reason.
     pub fn seed_cvars(&self, rows: impl IntoIterator<Item = SeededCvar>) {
         let mut model = self.model_mut();
         for row in rows {
@@ -228,10 +157,9 @@ impl super::UiScript {
         }
     }
 
-    /// Host-side write (a loaded value, a committed latch, the host registry's outbox): sets
-    /// the value WITHOUT queueing a change event — the host is the caller, an echo would
-    /// re-dirty the file it just read — and clears a staged value, because a host write IS the
-    /// commit. Unknown names warn once, same posture as the Lua side.
+    /// Host-side write (a loaded value, a committed latch): sets the value and clears any staged
+    /// one without queueing a change, since an echo would re-dirty the file the host just read.
+    /// An unknown name warns once.
     pub fn set_cvar_host(&mut self, name: &str, value: &str) {
         let mut model = self.model_mut();
         let key = name.to_ascii_lowercase();
@@ -252,8 +180,8 @@ impl super::UiScript {
             .map(|s| s.value.clone())
     }
 
-    /// Snapshot the whole table as `(name, value, default)` — the saver writes the entries whose
-    /// value moved off the default, and nothing else (the config file stays a diff, not a dump).
+    /// Snapshot the table as `(name, value, default)`; the saver writes only rows off their
+    /// default, so the config file stays a diff.
     pub fn cvars_snapshot(&self) -> Vec<(String, String, String)> {
         self.model_mut()
             .cvars
@@ -262,59 +190,35 @@ impl super::UiScript {
             .collect()
     }
 
-    /// Drain the `(name, new_value)` changes Lua `SetCVar` queued since the last call — the
-    /// host's cue to sync its resources and mark the config dirty. Names are the registered
-    /// spelling regardless of the caller's casing.
+    /// Drain the `(name, new_value)` changes queued since the last call, under the registered
+    /// spelling: the host's cue to sync its resources and mark the config dirty.
     pub fn take_cvar_changes(&mut self) -> Vec<(String, String)> {
         std::mem::take(&mut self.model_mut().cvar_changes)
     }
 
-    /// Drain the `(name, default)` rows an addon's `RegisterCVar` created since the last call
-    /// (decision 2303) — the host's cue to give each one a row in its own registry, which is the
-    /// store that survives this VM. In the reference an addon's registration lands in the same
-    /// engine-side table as the client's own; this is how ours does.
+    /// Drain the `(name, default)` rows an addon's `RegisterCVar` created since the last call; the
+    /// host's registry keeps them beside its own, as the reference's one table does.
     pub fn take_cvar_registrations(&mut self) -> Vec<(String, String)> {
         std::mem::take(&mut self.model_mut().cvar_registrations)
     }
 
-    /// A native surface's write — [`set_from_engine`]'s public face: sets the value AND queues
-    /// the change like a Lua `SetCVar`, so the host's sync dirties the config file. The glue
-    /// AddOns screen's *Load out of date AddOns* checkbox is the caller (decision 1293): a
-    /// native widget editing a CVar is the minimap-zoom pattern, reached from outside the crate.
+    /// A native widget's write (the glue AddOns screen's "Load out of date AddOns" checkbox): sets
+    /// the value and queues the change like a Lua `SetCVar`, so the config file is dirtied.
     pub fn set_cvar_engine(&mut self, name: &str, value: &str) {
         set_from_engine(&mut self.model_mut(), name, value.to_string());
     }
 
-    /// Publish the multisample formats this run's device actually accepts — what the Video
-    /// options dropdown offers, in the order it offers them.
-    ///
-    /// The host's half of the reference's `0x48c3e0`: there, a D3D `CheckDeviceMultiSampleType`
-    /// sweep over the nine-entry candidate table `0x85a83c` or a GL `wglGetPixelFormatAttribivARB`
-    /// sweep over every pixel format; here, `benilla_world::view::supported_sample_counts` asking
-    /// wgpu the same question. Pushed rather than pulled because the VM lives in `benilla-ui`,
-    /// which has no render adapter and should not grow one.
+    /// Publish the multisample formats this run's device accepts, in dropdown order. The
+    /// reference's `0x48c3e0` sweeps its candidate table `0x85a83c` (D3D) or every pixel format
+    /// (GL); here the host asks wgpu.
     pub fn set_multisample_formats(&mut self, formats: Vec<MultisampleFormat>) {
         self.model_mut().multisample_formats = formats;
     }
 
-    /// Publish the screen resolutions the Video options dropdown offers, and which one the client
-    /// is currently at.
-    ///
-    /// **`current` is a promise, not a hint.** `CT_Viewport.lua:201` reads its own screen size as
-    /// `arg[GetCurrentResolution()]` over `GetScreenResolutions()`'s varargs and silently falls
-    /// back to 4:3 on a miss, so a current size that is not in the list is a wrong answer that
-    /// succeeds. The host therefore hands the live size here and this pushes it INTO the list if
-    /// the display's own mode table does not carry it — a windowed client at 1600×900 on a 4K
-    /// panel is exactly that case, and it is the common one.
-    ///
-    /// Both halves land together because they are one fact: a list without its index cannot be
-    /// read, and an index into a list that moved is worse than none.
-    ///
-    /// **Ordered by pixel AREA**, which is the reference's own key (`0x58be40`: `a.w*a.h - b.w*b.h`,
-    /// with no tie-break at all). Ours breaks ties on width then height, deliberately: the
-    /// reference's comparator plus its adjacent-only dedupe can leak a duplicate `"WxH"` when two
-    /// distinct modes share an area — 1280×960 and 1600×768 are both 1 228 800 — and reproducing an
-    /// unstable sort is aping a quirk, not implementing the mechanism.
+    /// Publish the dropdown's resolutions and the client's current one, sorted by
+    /// [`ScreenResolution::sort_key`] and deduplicated. `current` is inserted when the list lacks
+    /// it (a 1600x900 window on a 4K panel): `CT_Viewport.lua:201` reads
+    /// `arg[GetCurrentResolution()]` and silently falls back to 4:3 on a miss.
     pub fn set_screen_resolutions(
         &mut self,
         mut offered: Vec<ScreenResolution>,
@@ -334,41 +238,28 @@ impl super::UiScript {
         model.current_resolution = current;
     }
 
-    /// Publish what this run's device and presentation path really offer, behind `GetVideoCaps`.
+    /// Publish what this run's device and presentation path offer, behind `GetVideoCaps`.
     pub fn set_video_caps(&mut self, caps: VideoCaps) {
         self.model_mut().video_caps = caps;
     }
 
-    /// Drain the `RestartGx()` calls queued since the last call — each is one "apply the staged
-    /// video settings now", and the host answers by re-asserting them against the window.
+    /// Drain the `RestartGx()` calls queued since the last call; the host answers each by
+    /// re-asserting the staged video settings against the window.
     pub fn take_restart_gx_asks(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().restart_gx_asks)
     }
 }
 
-/// An **engine-side** write: a value the engine owns moved, and the CVar table mirrors it. The
-/// minimap's zoom is the case that needs it — the client's `set_zoom` (`0x6da8e0`) writes the live
-/// index *and* `CVar::Set`s `minimapZoom`/`minimapInsideZoom` in the same breath, which is exactly
-/// why the level survives a restart. So this queues the change like a Lua `SetCVar` would (the host
-/// must hear it and dirty the config file), unlike [`super::UiScript::set_cvar_host`], whose whole
-/// point is *not* to echo the value it just loaded.
-///
-/// A name the host never registered is a **silent** no-op here, not a warning: engine writes are
-/// code, not UI content, so a miss means this build's host doesn't back the var (a bare test VM) —
-/// and the registered set is welded to the code truths by `crate::cvars`'s own test.
+/// An engine-side write, for a value the engine owns: queued like a Lua `SetCVar` so the config
+/// file is dirtied, as the reference's minimap `set_zoom` (`0x6da8e0`) also `CVar::Set`s
+/// `minimapZoom`/`minimapInsideZoom`. An unregistered name is a silent no-op (a bare VM).
 pub(super) fn set_from_engine(model: &mut Model, name: &str, value: String) {
     store(model, &name.to_ascii_lowercase(), value);
 }
 
-/// **The one store every write goes through** — Lua's `SetCVar`, `ConsoleExec`, and the engine
-/// writes above. Returns the registered spelling when the write moved something (and queued it
-/// for the host), `None` for an unknown key or a write that changed nothing.
-///
-/// A **latched** slot (decision 2303) takes the write as its staged value and leaves `value`
-/// alone, which is the reference's `Set 0x63df50`: `latchedValue` gets the string, `InternalSet`
-/// does not run, and `GetCVar` keeps answering what is applied. Writing a latched slot back to
-/// its applied value clears the stage instead of staging a no-op. Either way the host hears it
-/// through the change queue — it holds the pending copy and commits it at the boundary.
+/// The one store every write goes through; returns the registered spelling when the value moved
+/// and the change was queued. A latched slot stages the write, as the reference's `Set 0x63df50`
+/// stores `latchedValue` and skips `InternalSet`; writing back the applied value unstages it.
 fn store(model: &mut Model, key: &str, value: String) -> Option<String> {
     let slot = model.cvars.get_mut(key)?;
     if slot.latched {
@@ -391,10 +282,8 @@ fn store(model: &mut Model, key: &str, value: String) -> Option<String> {
     Some(registered)
 }
 
-/// Push the warn-once for an unknown CVar name into the model's warning stream.
-/// The `SetCVar` write, shared with `ConsoleExec` (which is `/console name value`): the slot
-/// matched case-insensitively, the change queued for the host only when the value moved, and
-/// `CVAR_UPDATE` fired only when a token was passed. `false` = no such CVar (warned once).
+/// The `SetCVar` write, shared with `ConsoleExec`: the change is queued only when the value
+/// moved, and `CVAR_UPDATE` fires only when a token was passed. `false` for an unknown name.
 pub(super) fn write_cvar(
     model: &mut Model,
     name: &str,
@@ -426,8 +315,10 @@ fn warn_unknown(model: &mut Model, name: &str) {
     }
 }
 
-/// Coerce the Lua argument to the string the table stores: the client stringifies numbers and
-/// booleans the same way (`SetCVar("MusicVolume", 0.4)` is the common call shape).
+/// Coerce a Lua argument to the stored string; the client takes a number too
+/// (`SetCVar("MusicVolume", 0.4)` is the common call). A boolean becomes "1" or "0", where the
+/// reference's `SetCVar` and `RegisterCVar` store "0" for anything but a string or a number
+/// (`0x488c98`, `0x488b6f`).
 fn value_to_string(v: &Value) -> Option<String> {
     match v {
         Value::String(s) => s.to_str().ok().map(|s| s.to_owned()),
@@ -438,44 +329,29 @@ fn value_to_string(v: &Value) -> Option<String> {
     }
 }
 
-/// Register the `GetCVar`/`SetCVar`/`GetCVarDefault`/`RegisterCVar` globals.
-/// The two nameplate toggles' registered CVar names — **defined here, in the crate that publishes
-/// the four verbs that write them**, so the binding and the name cannot drift apart. The app reads
-/// these consts rather than re-spelling the strings, and welds them to its registered table with
-/// its own test.
-///
-/// They are the LATER era's names: 1.12 registers no nameplate CVar at all (censused — see
-/// [`install_nameplate_verbs`]), so benilla's persistence takes the era spelling rather than
-/// inventing one, the same posture as `autoLootDefault`.
+/// The enemy-plate toggle's CVar, which the app reads rather than re-spelling. Deviation: 1.12
+/// registers no nameplate CVar; the toggles persist under the later clients' names rather than
+/// invented ones.
 pub const CVAR_NAMEPLATE_ENEMIES: &str = "nameplateShowEnemies";
 /// The friendly-plate half of [`CVAR_NAMEPLATE_ENEMIES`].
 pub const CVAR_NAMEPLATE_FRIENDS: &str = "nameplateShowFriends";
 
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
-    // `RegisterCVar(name, value)` — declare a CVar the client does not ship (decision 1195).
-    //
-    // This is how an addon gets a persisted setting without a saved-variables file, and it is why
-    // `GetCVar` on an unknown name is a *warning* rather than an error: an addon that calls
-    // `RegisterCVar` at load and `GetCVar` after expects the second to answer. Registering an
-    // existing name is a **no-op, not an overwrite** — the reference will not let an addon reset a
-    // client CVar's live value by re-declaring it, and a re-run of the addon's own load must not
-    // wipe the player's setting either.
+    // `RegisterCVar(name, value)` declares a CVar the client does not ship, which is how an addon
+    // persists a setting. Re-declaring a live name is a no-op: the reference never resets a live
+    // value on re-registration.
     lua.globals().set(
         "RegisterCVar",
         lua.create_function(|lua, (name, value): (String, Option<Value>)| {
             let value = value.as_ref().and_then(value_to_string).unwrap_or_default();
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
             let key = name.to_ascii_lowercase();
-            // The saved base outranks the declared default (decision 1291): an addon-declared
-            // CVar the player has set persists in the config file, and this lookup is how the
-            // saved value survives the VM being replaced — the declared value stays the DEFAULT,
-            // so the saver still knows what "moved off default" means for this key.
+            // A saved value outranks the declared one, which stays the default for the saver.
             let saved = model.cvars_saved_base.get(&key).cloned();
             if model.cvars.contains_key(&key) {
                 return Ok(());
             }
-            // The host learns the row through its own queue (decision 2303): an addon-declared
-            // CVar gets a row in the host's registry, which is the store that survives this VM.
+            // The host gives the row a place in its registry, which outlives this VM.
             model.cvar_registrations.push((name.clone(), value.clone()));
             model.cvars.insert(
                 key,
@@ -518,18 +394,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
     // ── The Video options Multisampling dropdown ──────────────────────────────────────────────
-    // Three bindings over one list, exactly as `OptionsFrame.lua` consumes them: `_OnLoad` seeds
-    // the selection with `GetCurrentMultisampleFormat()`, `_Initialize` walks
-    // `GetMultisampleFormats()` three varargs at a time building the menu, and the Okay handler
-    // (l.240) calls `SetMultisampleFormat(UIDropDownMenu_GetSelectedID(...))`. Identities and
-    // behaviour from the registration table `0x83de68`, records `0x83e2c0`/`0x83e2c8`/`0x83e2d0`.
+    // As `OptionsFrame.lua` drives it: `_OnLoad` seeds the selection from
+    // `GetCurrentMultisampleFormat()`, `_Initialize` walks `GetMultisampleFormats()` three values
+    // at a time, and the Okay handler (l.240) calls `SetMultisampleFormat`. Registration table
+    // `0x83de68`, records `0x83e2c0`/`0x83e2c8`/`0x83e2d0`.
     lua.globals().set(
         "GetMultisampleFormats",
         lua.create_function(|lua, ()| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
-            // Flat, three per entry — `0x48c360` "pushes all three fields of every entry", and the
-            // Lua walks `for i=1, arg.n, 3`. A device with nothing to offer returns nothing, and
-            // the loop runs zero times: an empty dropdown, not a fabricated one.
+            // Flat, three per entry (`0x48c360`); no formats is no values and an empty menu.
             let mut out = mlua::MultiValue::new();
             for f in &model.multisample_formats {
                 out.push_back(Value::Number(f.color_bits as f64));
@@ -551,9 +424,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             ) else {
                 return Ok(1.0f64);
             };
-            // **1-based, and 1.0 on no match** — `0x48c580` "returns the 1-based index of the
-            // matching triple, or 1.0 on no match". Not 0 and not nil: `_OnLoad` feeds this
-            // straight to `UIDropDownMenu_SetSelectedID`, so a miss has to name a real row.
+            // 1-based, and 1.0 on no match (`0x48c580`): `_OnLoad` hands it straight to
+            // `UIDropDownMenu_SetSelectedID`, so a miss must still name a real row.
             let idx = model
                 .multisample_formats
                 .iter()
@@ -568,24 +440,23 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "SetMultisampleFormat",
         lua.create_function(|lua, id: Option<f64>| {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // 1-based from `UIDropDownMenu_GetSelectedID`; anything off the end is ignored rather
-            // than clamped, because a clamp would silently apply a format the player did not pick.
+            // 1-based from `UIDropDownMenu_GetSelectedID`. Deviation: an id out of range is
+            // ignored, because the reference reads one entry past the last (`0x48c67c`) and a
+            // clamp would apply a format the player did not pick. A missing id is ignored too,
+            // where the reference takes the first entry (`0x48c657`).
             let Some(f) = id
                 .filter(|v| *v >= 1.0)
                 .and_then(|v| model.multisample_formats.get(v as usize - 1).copied())
             else {
                 return Ok(());
             };
-            // All three, from the chosen entry — `0x48c640` "writes those three CVars from the
-            // chosen entry". Through `set_from_engine` so each ride the host's change queue and
-            // the config file is marked dirty, the same route a Lua `SetCVar` takes.
+            // All three from the chosen entry, as `0x48c640` writes them, through the change queue.
             set_from_engine(&mut model, "gxColorBits", f.color_bits.to_string());
             set_from_engine(&mut model, "gxDepthBits", f.depth_bits.to_string());
             set_from_engine(&mut model, "gxMultisample", f.samples.to_string());
-            // The reference then sets `gxRestart` (`0x842978`, `0x63ce00`). We deliberately do not
-            // register that CVar: `gxMultisample` is latched here too (decision 1629 — the camera
-            // reads its sample count once, at spawn), so "applies at next launch" is already the
-            // behaviour and a second flag saying so would be a flag nothing reads.
+            // Deviation: the reference then runs the console command `gxRestart` (`0x842978`
+            // through `0x63ce00`); none is queued here, because `gxMultisample` applies at next
+            // launch anyway: the camera reads its sample count once, at spawn.
             Ok(())
         })?,
     )?;
@@ -603,19 +474,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             let Some(value) = value_to_string(v) else {
                 return Err(mlua::Error::runtime("Usage: SetCVar(\"name\", value)"));
             };
-            // The THIRD argument is the `CVAR_UPDATE` token, and it is the whole mechanism behind
-            // that event (decision 1140). 1.12's own callers are its two options panels —
-            // `SetCVar(value.cvar, value.value, index)` (UIOptionsFrame.lua l.335/343/345,
-            // OptionsFrame.lua l.192) — where `index` is the CheckButtons table's KEY, an
-            // uppercase display name like "STATUS_BAR_TEXT". The engine passes it straight through
-            // as arg1, which is why `UIOptionsFrame_OnEvent` can look the row up with
-            // `UIOptionsFrameCheckButtons[arg1]`, and why `TextStatusBar_OnEvent` compares against
-            // "STATUS_BAR_TEXT" rather than "statusBarText".
-            //
-            // A caller that omits it fires nothing — the event is opt-in per write, not a
-            // property of the variable. (Which means `ReputationFrame.xml`'s
-            // `arg1 == "statusBarText"` arm is dead code in shipped 1.12: nothing ever passes the
-            // CVar's own name as the token. Transcribed as found, not repaired.)
+            // The third argument is the `CVAR_UPDATE` token, passed through as arg1; without one
+            // nothing fires. The 1.12 options panels pass their CheckButtons key, such as
+            // "STATUS_BAR_TEXT" (`UIOptionsFrame.lua` l.335, `OptionsFrame.lua` l.192), which is
+            // how `UIOptionsFrame_OnEvent` finds its row.
             let token = it.next().and_then(value_to_string);
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
             write_cvar(&mut model, &name, value, token);
@@ -627,89 +489,41 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     install_world_detail_verbs(lua)
 }
 
-/// **What `RestoreVideoDefaults` puts back** — the settings this client's video path backs that the
-/// reference's own verb writes, each named by the row it is.
+/// What `RestoreVideoDefaults` puts back: the CVars among the reference verb's writes that benilla
+/// registers, each at its registered default. The verb writes no `uiScale`, `useUiScale` or
+/// `anisotropic`.
 ///
-/// **The reference does NOT restore registered defaults, and this list is not a guess at which it
-/// does.** `0x48dad0` → `0x639a20` maps the already-matched `VideoHardware.dbc` row through
-/// nine lookup tables into a hardware-recommended settings struct, copies the `CGxFormat` **preset**
-/// that row names for this adapter (`[0xc4e6ac]` → `0xc518e0 + 0x38·n`) into the working device
-/// record, writes that record into twelve `gx*` CVars, performs a full synchronous `RestartGx`, and
-/// then writes sixteen further graphics CVars from the recommendations. The registered strings
-/// (`"640x480"`, `"75"`, `"16"`…) are never consulted.
-///
-/// **benilla has no such pass, and that is why its registered defaults ARE its recommended
-/// configuration.** There is no `VideoHardware.dbc` matching here and no preset table: what a fresh
-/// install runs is each `REGISTERED` row's own value, clamped by the device where the device has a
-/// say (`MsaaFormats::clamp`, `tex_filter`'s aniso ceiling). So this restores each row to its
-/// registered default — the same *meaning*, reached the way this client reaches it — and that is a
-/// stated divergence rather than a transcription.
-///
-/// The membership, though, is the reference's: these are the names in its twelve-plus-sixteen that
-/// benilla registers. It does **not** touch `uiScale`, `useUiScale` or `anisotropic` — an earlier
-/// draft of this list did, reasoning from the video window's Lua tables instead of from the verb.
-///
-/// **`WorldDetail` is ours and rides with `frillDensity`**: 2163 welded the panel stop to the
-/// reference's own clutter CVar, so restoring one without the other would leave the pair describing
-/// two different detail levels.
-///
-/// `benilla_app::cvars` holds the matching test that every name here is registered — the weld that
-/// keeps a rename or a retirement from turning a row into a silent no-op.
+/// Deviation: the reference (`0x48dad0` into `0x639a20`) writes hardware-recommended values from
+/// its matched `VideoHardware.dbc` row and the `CGxFormat` preset it names (`[0xc4e6ac]`): twelve
+/// `gx*` CVars, a synchronous `RestartGx`, then sixteen more. benilla has no such matching, so its
+/// registered defaults are its recommended configuration.
 pub const VIDEO_DEFAULT_CVARS: &[&str] = &[
-    // of the twelve `gx*` the device record writes (`0x639c40`), the six benilla registers
+    // Of the twelve `gx*` the device record writes (`0x639c40`), the six benilla registers.
     "gxWindow",
     "gxResolution",
     "gxVSync",
     "gxColorBits",
     "gxDepthBits",
     "gxMultisample",
-    // of the sixteen further graphics CVars (`0x639a60`), the three benilla registers
+    // Of the sixteen further graphics CVars (`0x639a60`), the three benilla registers.
     "farclip",
     "frillDensity",
     "trilinear",
-    // ours, welded to `frillDensity` (2163)
+    // Ours, restored with `frillDensity` so the pair keeps describing one detail level.
     "WorldDetail",
 ];
 
-/// **The Video options window's own engine verbs** — the nine `OptionsFrame.xml` needs that
-/// nothing else in this client provides.
+/// The Video options window's engine verbs that nothing else here provides. Three run at load,
+/// as `UIDropDownMenu_Initialize` calls its initializer at once (`UIDropDownMenu.lua:48-50`):
+/// `GetScreenResolutions`, `GetCurrentResolution` and `GetRefreshRates`.
 ///
-/// The window is loaded off the player's chain and kept hidden (decision 2177, the shape 2115 and
-/// 2147 set for the Interface and Sound windows): nothing of ours shows it, and it exists so that
-/// an addon reaching for the reference's video-options names finds real frames and real functions
-/// instead of an alias onto a window of ours.
-///
-/// **Three of the nine run at LOAD** — `GetScreenResolutions`, `GetCurrentResolution` and
-/// `GetRefreshRates`, from the resolution and refresh dropdowns' `<OnLoad>`, because
-/// `UIDropDownMenu_Initialize` calls the initializer it is handed *immediately*
-/// (`UIDropDownMenu.lua:48-50`). The file cannot load at all without them, and the window being
-/// `hidden="true"` is precisely what keeps the other four out of that set: they hang off `OnShow`
-/// and the three buttons. The **tenth** name that load reaches, which benilla's own census of this
-/// window missed, is plain `GetCVar` (`OptionsFrame.lua:300`, `GetCVar("gxRefresh")`).
-///
-/// The three multisample verbs the same window needs are above; `GetWorldDetail`/`SetWorldDetail`
-/// are in [`install_world_detail_verbs`]. `GetGamma`/`SetGamma` are the last two: 2177 shipped
-/// seven and left that pair **loudly absent** under 1203, because a byte-faithful copy would have
-/// driven a hardware ramp this client never uploads. 2182 built the render feature behind them, so
-/// they have a real reader now and the window's engine verbs are nine of nine.
-///
-/// **What must NOT be defined, which is as load-bearing as what is.** `OptionsFrame_Load:110` does
-/// `getglobal("Get"..value.func)` over the nine slider rows and branches on the result; of the
-/// eighteen composed names, six resolve to real bindings in the reference
-/// (`Get/SetWorldDetail`, `Get/SetTerrainMip`, `Get/SetBaseMip`) and **ten must resolve to nil** —
-/// `Getuiscale`, `Getfarclip`, `Getanisotropic`, `GetspellEffectLevel`, `GetweatherDensity` and
-/// their five setters — so those rows fall through to `GetCVar`/`SetCVar`. Defining any of them
-/// changes this window's behaviour without erroring. The trap is `GetFarclip`/`SetFarclip`, which
-/// DO exist at `0x488f00`/`0x488f30` with a capital F while `value.func` is `"farclip"`: the stock
-/// client takes the CVar path only because `getglobal` is case-sensitive. Pinned by
-/// `benilla_app`'s `the_video_windows_ten_composed_names_stay_nil`.
+/// Ten names must stay nil so their slider rows fall back to `GetCVar`/`SetCVar`
+/// (`OptionsFrame_Load:110` tries `getglobal("Get"..value.func)`): `Getuiscale`, `Getfarclip`,
+/// `Getanisotropic`, `GetspellEffectLevel`, `GetweatherDensity` and their setters.
+/// `GetFarclip`/`SetFarclip` do exist (`0x488f00`/`0x488f30`); `getglobal` is case-sensitive.
 fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
     // ── GetScreenResolutions ─────────────────────────────────────────────────────────────────
-    // A vararg of `"WxH"` strings. The format is pinned by two independent consumers, neither of
-    // which raises on a wrong one: `OptionsFrame.lua:281-284` splits on the `x` and evaluates
-    // `width/height > 4/3` to decide the WIDESCREEN tag, and `CT_Viewport.lua:107` re-parses with
-    // `string.find(currRes, "(%d+)x(%d+)")` to size its viewport. A space, an `X`, or a trailing
-    // suffix silently gives one of them the wrong answer.
+    // A vararg of `"WxH"` strings, the spelling `ScreenResolution` pins.
     lua.globals().set(
         "GetScreenResolutions",
         lua.create_function(|lua, ()| {
@@ -722,25 +536,12 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
     // ── GetCurrentResolution ─────────────────────────────────────────────────────────────────
-    // The **1-based index** into that list — `0x48bfa2 inc eax` over the same array, which is the
-    // only reading `arg[GetCurrentResolution()]` (`CT_Viewport.lua:105`) can have.
+    // The 1-based index into that list (`0x48bfa2`), and 1.0 on any miss, never nil or 0
+    // (`0x48bf88`), so a 1 does not prove a match.
     //
-    // **`1.0` on a miss, never nil and never 0** (`0x48bf88 push 0x3ff00000` — the f64 `1.0`), and
-    // the reference takes that path on every failure: no CVar record, a NULL string, an empty
-    // list, or a value simply not in it. It is the family idiom — `GetCurrentMultisampleFormat`
-    // `0x48c580` answers `1.0` the same way, and `SetMultisampleFormat` above already does. A `1`
-    // is therefore not proof of a match, which is exactly the trap the reference walks into: its
-    // `gxResolution` registers at `"640x480"`, below its own list's 800×600 floor, so a fresh
-    // config reports index 1 while running 640×480.
-    //
-    // **Where ours reads from is a stated divergence.** The reference parses the `gxResolution`
-    // CVar (`0x48bf20`), which on a mode-setting client IS the live mode. benilla ships no
-    // exclusive mode-set: `gxResolution` is the WINDOWED size, and while the client is borderless
-    // fullscreen the two differ. The host therefore pushes the live window size, because "what
-    // resolution am I at" is what every consumer means — `CT_Viewport` scales its viewport by it —
-    // and reporting a windowed size while filling a 4K panel would be a wrong answer that
-    // succeeds. A pick made while fullscreen still lands in `gxResolution` and takes effect on the
-    // way out, which is the honest reading of a windowed-size setting.
+    // Deviation: the index is of the live window size, not of the `gxResolution` CVar the
+    // reference parses (`0x48bf20`), because without an exclusive mode-set `gxResolution` is the
+    // windowed size, not the live one in borderless fullscreen, which `CT_Viewport` scales by.
     lua.globals().set(
         "GetCurrentResolution",
         lua.create_function(|lua, ()| {
@@ -749,30 +550,16 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
     // ── SetScreenResolution ──────────────────────────────────────────────────────────────────
-    // 1-based, from `UIDropDownMenu_GetSelectedID(OptionsFrameResolutionDropDown)`
-    // (`OptionsFrame.lua:239`). Three things about the argument, all carved at `0x48bfd0`:
+    // 1-based (`OptionsFrame.lua:239`), and `0x48bfd0` never raises: a missing or non-numeric
+    // argument selects the first entry, a numeric string counts (`0x6f7c20`), and a number
+    // truncates toward zero (`0x40a2b0`).
     //
-    // * **The TOLERANT family, not the raising one.** `0x48bfe6 xor esi,esi` seats a default index
-    //   of 0 and there is no `0x6f4940` anywhere in the body, so a missing, nil or non-numeric
-    //   argument silently selects **the first entry** rather than erroring. A numeric string is
-    //   accepted (the `0x6f7c20` coercion).
-    // * **Truncated toward zero** — `0x40a2b0 __ftol` with RC=11, so `2.7` is entry 2.
-    // * **Out of range is where we deliberately diverge.** `0x48c008 dec eax` / `0x48c009 cmp` /
-    //   the failure block at `0x48c00d` converge index 0, negatives and anything past the count on
-    //   `list[count]` — one element past the last, read unguarded. It does not fault only because
-    //   the array keeps a spare slot. We clamp to the last entry instead: reproducing an
-    //   out-of-bounds read to apply an uninitialised resolution is not fidelity.
+    // Deviation: 0, a negative or an index past the count clamps to the nearer end, because the
+    // reference reads one element past the last there (`0x48c00d`), uninitialised memory.
     //
-    // **The same-value guard is real behaviour and is reproduced** (`0x48c081 je 0x48c0c1`): if the
-    // requested size equals the one `gxResolution` already holds, the reference returns having done
-    // nothing at all — no write, no restart — and so does this. `set_from_engine` would swallow the
-    // write anyway; the restart below is what makes the guard observable.
-    //
-    // **And it issues its own `gxRestart`** (`0x48c0b7 mov ecx,0x842978` → the console executor),
-    // which is why `OptionsFrame_Save` calling `RestartGx()` afterwards restarts a resolution
-    // change twice. Ours does the same, through the same counted request the host drains — benilla
-    // applies the size live, so the restart is a re-assertion rather than a device rebuild, but the
-    // CALL is the reference's and belongs here rather than only at the Okay button.
+    // A size equal to `gxResolution`'s does nothing, no write and no restart (`0x48c081`);
+    // otherwise it issues its own `gxRestart` (`0x48c0b7`), so `OptionsFrame_Save`'s later
+    // `RestartGx()` restarts a resolution change twice, here as in the reference.
     lua.globals().set(
         "SetScreenResolution",
         lua.create_function(|lua, id: Option<f64>| {
@@ -780,7 +567,8 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
             if model.screen_resolutions.is_empty() {
                 return Ok(());
             }
-            // nil / non-numeric → 0 → entry 1. Truncate, then clamp both ends.
+            // nil selects entry 1; a non-numeric argument has already raised in the conversion,
+            // where the reference takes entry 1. Truncate, then clamp both ends.
             let idx = id.map_or(0.0, f64::trunc);
             let last = model.screen_resolutions.len() - 1;
             let r = model.screen_resolutions[if idx < 1.0 {
@@ -802,51 +590,19 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
     // ── GetRefreshRates ─────────────────────────────────────────────────────────────────────
-    // **Zero return values, and that IS the reference's "nothing to offer" answer** —
-    // `0x48c136 xor eax,eax; ret`. It was written here as a single `0` first, from
-    // `OptionsFrame_GetRefreshRates`'s `if ( arg.n == 1 and arg[1] == 0 )` opening; the binary
-    // contains **no `push 0` path at all**. That FrameXML branch is reachable only when the OS
-    // reports `dmDisplayFrequency == 0` for every matching mode — Win32's encoding for "the
-    // hardware default" — which the adjacent dedupe collapses to one `0`. It does not special-case
-    // the empty answer: `for i = 1, 0` runs zero times and the dropdown is left **empty but
-    // enabled**, which is what the reference does on a device with nothing to say.
-    //
-    // benilla's answer is always the empty one, because a refresh rate is only selectable through
-    // an exclusive mode-set and this client ships none on any target (`benilla_app::video`'s
-    // module doc walks each). Pushing the monitor's rates would be a dropdown whose every pick did
-    // nothing — 2115 §2's wrong answer that succeeds — and pushing a lone `0` to grey the control
-    // would be inventing a value the binary never produces.
-    //
-    // **The optional index argument is tolerated and ignored**, which is the reference's own shape
-    // (`0x48c0ec xor esi,esi`): with no argument it asks for the rates of the FIRST — smallest —
-    // resolution in the list, never the selected one, and the stock caller passes nothing.
+    // No values is the reference's "nothing to offer" (`0x48c136`), an empty but enabled
+    // dropdown. Any argument is accepted; in the reference it picks the resolution, the first
+    // when absent (`0x48c0ec`). Deviation: always empty, because a refresh rate is only
+    // selectable through an exclusive mode-set and benilla has none.
     lua.globals().set(
         "GetRefreshRates",
         lua.create_function(|_, _: mlua::MultiValue| Ok(mlua::MultiValue::new()))?,
     )?;
     // ── GetVideoCaps ─────────────────────────────────────────────────────────────────────────
-    // Seven values in `OptionsFrame.lua:59`'s own order, and **THREE push shapes, not two**
-    // (`0x48db40`, each polarity read through to `lua_pushnil 0x6f37f0`):
-    //
-    // * slots 1,2,3,4,7 — **nil, or the number 1**. `caps+0xa8/0x98/0x94/0xa4/0xc4`. Two of them
-    //   test against `-1` rather than 0, because D3D maps ps_1_1 and vs_1_1 to the *value* 0 and a
-    //   `!= 0` test would report "no shaders" on hardware that has them.
-    // * slot 5 `hasTripleBuffering` — **`0x48dbcb fild dword [edi+0x20]`, straight-line, NO
-    //   branch**: always a number, never nil.
-    // * slot 6 `maxAnisotropy` — **nil iff 0**, else the raw value.
-    //
-    // No `lua_pushboolean` anywhere; the `1` is the f64 `1.0`.
-    //
-    // **Slot 5 is a backend constant, and getting its TYPE right is what reproduces a stock
-    // defect.** `caps+0x20` has two writers image-wide (the two device constructors: 1 under
-    // Direct3D, 0 under OpenGL) and one reader, this verb — so `== 1` means "the backend is
-    // Direct3D", independent of GPU, driver and the `gxTripleBuffer` CVar. `OptionsFrame_Load`
-    // tests `not hasTripleBuffering` twice and `hasTripleBuffering == 1` once; `0` is TRUTHY in
-    // Lua and slot 5 is never nil, so **the two `not` tests can never fire in either backend** and
-    // only the `== 1` one works. benilla is not Direct3D and exposes no buffering knob, so it
-    // answers the number **0**: check button 13 is hidden and button 6 re-seated
-    // (`OptionsFrame.lua:168-175`), and the two dead clauses stay dead, which is correct.
-    // Answering nil instead would *revive* them — a branch the reference cannot reach.
+    // Seven values in `OptionsFrame.lua:59`'s order, never a boolean (`0x48db40`): slots 1-4 and
+    // 7 are nil or the number 1, slot 5 is always a number, slot 6 is nil iff 0. Slot 5 is 0
+    // under OpenGL and 1 under Direct3D; 0 is truthy, so `OptionsFrame_Load`'s two
+    // `not hasTripleBuffering` tests never fire in the reference, and a nil would revive them.
     lua.globals().set(
         "GetVideoCaps",
         lua.create_function(|lua, ()| {
@@ -860,10 +616,9 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
             out.push_back(flag(caps.pixel_shaders));
             out.push_back(flag(caps.vertex_shaders));
             out.push_back(flag(caps.trilinear));
-            // Slot 5: unconditional number, per the straight-line `fild` above.
+            // Slot 5: always a number, a straight-line `fild` (`0x48dbcb`).
             out.push_back(Value::Number(if caps.triple_buffering { 1.0 } else { 0.0 }));
-            // Slot 6: nil iff 0. The reference is effectively never nil here — its base ctor seeds
-            // `caps+0xac = 1` — so a consumer gates on slot 1 or on `< 2`, never on nil.
+            // Slot 6: nil iff 0; the reference's is seeded to 1 (`caps+0xac`), so never nil there.
             out.push_back(if caps.max_anisotropy == 0 {
                 Value::Nil
             } else {
@@ -874,24 +629,12 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
     // ── RestartGx ────────────────────────────────────────────────────────────────────────────
-    // "Apply the staged video settings now." `0x48dab0` is three instructions — it hands the line
-    // `"gxRestart"` to the CONSOLE COMMAND EXECUTOR `0x63ce00`, which looks the action up and calls
-    // its handler `0x639f60` **synchronously**. That handler reads no CVar by name: the staging was
-    // done at `SetCVar` time by each gx CVar's own change callback, which writes the pending device
-    // format record and can veto the write outright; the handler validates that record, applies it
-    // with `DeviceSetFormat`, and then COMMITS the fourteen latched CVars so `GetCVar` catches up.
-    //
-    // **benilla's latch is the host's** (decision 2303): a gx write stages in the host's CVar
-    // registry, and this verb is the host's cue to commit the gx stages (the fourteen-record
-    // commit, `Cvars::commit_latched`) and re-assert them against the window. The one difference
-    // left is when a change callback runs — the reference's at `SetCVar`, ours at the commit.
-    //
-    // A counted request the host drains (`take_restart_gx_asks`), the shape `Screenshot()` uses and
-    // for the same reason: no payload, and two calls in a frame are two requests. **It is not a
-    // stub** — a stub would be an empty body pretending the settings had been applied.
-    // `gxMultisample` is the one setting no restart can deliver here, and none can in the reference
-    // either: 1629 latches the sample count at camera spawn, which is what `SetMultisampleFormat`
-    // above already documents as "applies at next launch".
+    // "Apply the staged video settings now": `0x48dab0` runs the console command `gxRestart`
+    // (`0x63ce00`), whose handler `0x639f60` applies the staged device format and commits the
+    // fourteen latched CVars. Here it queues a counted request, as `Screenshot()` does; the host
+    // commits its gx stages (`Cvars::commit_latched`) and re-asserts them against the window.
+    // The reference runs each gx change callback at `SetCVar`, where it can veto the write; the
+    // host runs it at the commit. No restart applies `gxMultisample`: the camera reads it once.
     lua.globals().set(
         "RestartGx",
         lua.create_function(|lua, ()| {
@@ -902,22 +645,9 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
     // ── RestoreVideoDefaults ─────────────────────────────────────────────────────────────────
-    // **The Defaults button's whole effect, and the FrameXML proves it.** `OptionsFrame_SetDefaults`
-    // sets every check button and slider from `GetCVarDefault` — and then the button's own
-    // `<OnClick>` calls `HideUIPanel(OptionsFrame)` (`OptionsFrame.xml:688-690`), throwing those
-    // widget values away without ever running `_Save`. So the widgets are cosmetic; this verb is
-    // what actually moves the settings, and it must, or Defaults would do nothing at all.
-    //
-    // What it restores, and why that is not the reference's own values, is
-    // [`VIDEO_DEFAULT_CVARS`]'s doc. Each row rides the ordinary change queue, so the host's knob
-    // sync applies it and the config file is marked dirty — the same route a Lua `SetCVar` takes.
-    // `set_from_engine`, not `write_cvar`, because this is the engine moving a value it owns rather
-    // than a script asking: no `CVAR_UPDATE` token, the minimap-zoom shape.
-    //
-    // **The restart is the reference's own, in the reference's own place** — `0x639a51` calls the
-    // `gxRestart` handler directly and synchronously, between the twelve gx writes and the sixteen
-    // quality ones, and it destroys and recreates the device *and the OS window*. Ours issues the
-    // same counted request; here it is a re-assertion rather than a rebuild, but the call belongs.
+    // The Defaults button's whole effect: `OptionsFrame_SetDefaults` only sets the widgets, which
+    // the button's `OnClick` then hides without `_Save` (`OptionsFrame.xml:688-690`). Ends with a
+    // restart, as the reference calls the `gxRestart` handler between its two passes (`0x639a51`).
     lua.globals().set(
         "RestoreVideoDefaults",
         lua.create_function(|lua, ()| {
@@ -928,8 +658,7 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
                     .get(&name.to_ascii_lowercase())
                     .map(|slot| slot.default.clone())
                 else {
-                    // A bare VM with no host behind it registers none of these; there is nothing to
-                    // restore and nothing to warn about, exactly as `set_from_engine` reasons.
+                    // Unregistered in a bare VM: nothing to restore, nothing to warn about.
                     continue;
                 };
                 set_from_engine(&mut model, name, default);
@@ -939,36 +668,22 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
     // ── GetGamma / SetGamma ──────────────────────────────────────────────────────────────────
-    // **The display-brightness pair** (2182) — `GetGamma 0x4891c0` and `SetGamma 0x4891f0`, carved
-    // end to end.
-    //
-    // The one thing about them that is not obvious from the name: **the unit is the SLIDER's
-    // offset, not the CVar's.** `0x4891d0` is `dc 2d`, ModRM reg field 5 = **FSUBR** (`mem − ST(0)`,
-    // not `FSUB`), over `[0x8015b8]` = the f64 `1.0`. So `GetGamma()` answers `1.0 − gamma` and
-    // `SetGamma(v)` writes `gamma := 1.0 − v` — the two compose to the identity, and with the
-    // registered `gamma = "1.0"` the getter answers **0.0**, the exact centre of the stock
-    // slider's `[-0.5, 0.5]`. Reading the pair as "gamma in, gamma out" would put a 1.0 through
-    // `SetGamma` and write `gamma = 0`, i.e. `pow(x, 0) = 1`, a fully white ramp.
-    //
-    // **No clamp exists anywhere in the reference** — not in the binding, not in `CVar::Set`, not
-    // in the change callback, not in the ramp builder — and the absence is earned rather than
-    // assumed: the positive control is `baseMip`'s own callback `0x689090`, which *does* reject
-    // out-of-`[0,1]` with `al = 0`. `SetGamma(5)` is accepted and writes `gamma = "-4.000000"`.
-    // benilla's clamp is at the consumer (`ui_gamma::GAMMA_RANGE`), which is this crate's standing
-    // posture and leaves the store's truth alone.
+    // `GetGamma 0x4891c0` and `SetGamma 0x4891f0` work in the slider's offset, not the CVar's
+    // unit: `0x4891d0` is FSUBR over the f64 1.0 at `[0x8015b8]`, so `GetGamma()` answers
+    // `1.0 - gamma` and `SetGamma(v)` writes `gamma = 1.0 - v`; the registered `"1.0"` reads as
+    // 0.0, the slider's centre. The reference clamps nowhere (`SetGamma(5)` writes
+    // `"-4.000000"`); the clamp is the consumer's (`ui_gamma::GAMMA_RANGE`).
     lua.globals().set(
         "GetGamma",
-        // No argument is read (the getter never calls `lua_gettop`), and one number comes back.
+        // Any argument is ignored (the getter never calls `lua_gettop`); one number comes back.
         lua.create_function(|lua, _: mlua::MultiValue| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             let gamma = model
                 .cvars
                 .get(&CVAR_GAMMA.to_ascii_lowercase())
                 .and_then(|slot| slot.value.parse::<f64>().ok())
-                // A VM whose host registered nothing (a bare test kit) answers as if the
-                // registered default were in place, which is 0.0 — the slider's centre. The
-                // reference has no such arm: its `0x63de30` lookup CREATES the record on a miss,
-                // so `[eax+0x24]` is always readable.
+                // A bare VM with no `gamma` row answers as if the default stood; the reference
+                // always finds its record (`0x63de30`).
                 .unwrap_or(1.0);
             Ok(1.0 - gamma)
         })?,
@@ -976,9 +691,8 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
     lua.globals().set(
         "SetGamma",
         lua.create_function(|lua, value: Value| {
-            // `lua_isnumber` (`0x4891fe`): a number, or a string Lua can convert to one. Anything
-            // else raises through `0x6f4940`, which does not return — the trailing `xor eax,eax`
-            // at `0x489215` is dead code.
+            // `lua_isnumber` (`0x4891fe`): a number or a numeric string; anything else raises
+            // (`0x6f4940`).
             let v = match &value {
                 Value::Integer(i) => *i as f64,
                 Value::Number(n) => *n,
@@ -990,9 +704,8 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
                 }
                 _ => return Err(mlua::Error::runtime(USAGE_SET_GAMMA)),
             };
-            // `SStrPrintf(buf, 0x10, "%f", 1.0 - v)` — six decimals into a SIXTEEN-byte buffer, so
-            // a long value is truncated to 15 characters rather than rejected. Reproduced because
-            // the truncated string is what the CVar then holds and what `GetCVar("gamma")` answers.
+            // `SStrPrintf(buf, 0x10, "%f", 1.0 - v)`: a 16-byte buffer, so the stored string, and
+            // what `GetCVar("gamma")` answers, is cut at 15 characters.
             let mut written = format!("{:.6}", 1.0 - v);
             written.truncate(15);
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -1004,88 +717,38 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// The reference's own display-gamma CVar — `0x402d70`, name string `0x82e924`, registered `"1.0"`,
-/// flags 0. Defined in the crate that publishes the two verbs that read and write it, so the
-/// binding and the name cannot drift apart; the app welds it to its own table.
+/// The reference's display-gamma CVar: registered at `0x402d70` as `"1.0"`, flags 0, name
+/// string `0x82e924`.
 pub const CVAR_GAMMA: &str = "gamma";
 
 /// `0x8424cc`, verbatim.
 const USAGE_SET_GAMMA: &str = "Usage: SetGamma(value)";
 
-/// The `WorldDetail` slider's **stop**, benilla's spelling — the panel position `0`/`1`/`2`, held as
-/// a CVar because 1.12 has no such CVar and our own Graphics page needs somewhere to keep it (the
-/// `autoLootDefault` posture; the app's table carries the reasoning and the `Same` row).
-///
-/// Defined here, in the crate that publishes the two verbs that read and write it, so the binding
-/// and the name cannot drift apart — as for [`CVAR_NAMEPLATE_ENEMIES`]. The app welds both with its
-/// own test.
+/// The `WorldDetail` slider's stop, 0, 1 or 2. Deviation: 1.12 has no such CVar; it exists because
+/// our Graphics page needs somewhere to keep the stop, and takes the API's name.
 pub const CVAR_WORLD_DETAIL: &str = "WorldDetail";
 
-/// The reference's own Environment Detail CVar — cells visited per chunk by the detail-doodad
-/// scatter. [`WORLD_DETAIL_STOPS`] is what the slider writes into it.
+/// The reference's Environment Detail CVar: cells visited per chunk by the detail-doodad scatter.
 pub const CVAR_FRILL_DENSITY: &str = "frillDensity";
 
-/// **`SetWorldDetail`'s preset table, verbatim** — the three dwords at `0x804518`, `{0x10, 0x20,
-/// 0x30}`. Read out of `WoW.exe` rather than transcribed from a note.
+/// `SetWorldDetail`'s `frillDensity` per stop, the three dwords at `0x804518`.
 pub const WORLD_DETAIL_STOPS: [u32; 3] = [16, 32, 48];
 
-/// **The Environment Detail pair** — `SetWorldDetail 0x488dd0` and `GetWorldDetail 0x488d70`, the
-/// two engine bindings 1.12's own options panel drives that slider through (`OptionsFrame.lua`'s
-/// row 3 is `func = "WorldDetail"`, and `OptionsFrame_Save`/`_Load` prefer `getglobal("Set"..func)`
-/// / `getglobal("Get"..func)` over `SetCVar`/`GetCVar`). Decision 2163.
+/// The Environment Detail pair, `SetWorldDetail 0x488dd0` and `GetWorldDetail 0x488d70`, which
+/// `OptionsFrame.lua` row 3 (`func = "WorldDetail"`) drives in place of `SetCVar`/`GetCVar`. The
+/// setter truncates toward zero (`0x40a2b0`), raises outside 0..=2, and writes `frillDensity` from
+/// [`WORLD_DETAIL_STOPS`] and `smallCull` from `{0.07, 0.04, 0.01}` (`0x804524`).
 ///
-/// **The setter, carved end to end** (own decode):
-///
-/// ```text
-/// 488ddf  call 0x6f34d0             ; lua_isnumber(L,1)? else error 0x8423e8
-/// 488e05  call 0x6f3620             ; lua_tonumber(L,1)
-/// 488e0a  call 0x40a2b0             ; -> int, RC forced to CHOP (`or ah,0x0c`): TRUNCATE toward zero
-/// 488e11  test esi,esi; jl  0x488e9b ; n < 0  -> error 0x8423b8
-/// 488e19  cmp  esi,3;   jge 0x488e9b ; n >= 3 -> error 0x8423b8
-/// 488e1e  mov eax,[esi*4 + 0x804518] ; {16,32,48}      -> "%d"  -> CVar::Set "frillDensity"
-/// 488e56  fld dword [esi*4+0x804524] ; {0.07,0.04,0.01} -> "%f" -> CVar::Set "smallCull"
-/// ```
-///
-/// The two error strings are `0x8423e8` `"Usage: SetWorldDetail(value)"` and `0x8423b8` `"value
-/// must be in the range 0, 2"` — both read out of the image, lowercase `v` and all. Every path
-/// returns **zero** Lua values.
-///
-/// Three shapes worth stating because the obvious reading is wrong on each:
-///
-/// - **The truncation is toward zero, not a floor.** `0x40a2b0` saves the FPU control word, ORs
-///   `0x0c` into the high byte (rounding-control = chop) and `fistp`s. So `SetWorldDetail(2.9)`
-///   is stop 2 and `SetWorldDetail(-0.5)` is stop **0** — a negative that truncates to zero is
-///   accepted, and only `<= -1` raises.
-/// - **`lua_isnumber` accepts a numeric string**, so `SetWorldDetail("2")` works there and here.
-/// - **The getter is not the setter's inverse.** `0x488d70` reads only `smallCull`, seeds its
-///   result at **2**, and runs `for i in 0..3 { if v <= tbl[i] { result = i } }` over the
-///   *descending* `{0.07, 0.04, 0.01}` with **no break** — so the last match wins, and any
-///   `smallCull` above `0.07` (legal to 2.0) saturates to 2, i.e. the least detail reads back as
-///   the most. A shipped defect, and one of two: `OptionsFrame_SetDefaults` tests that same
-///   descending table with ascending `elseif`s, so Restore Defaults always parks the slider at 0.
-///
-/// **Where benilla diverges, and why it is not the smallCull ladder.** `SmallCull` is a dead knob
-/// in the reference — `[0x868620]` has one writer and no reader image-wide — so its *only*
-/// consumer there is this getter,
-/// which makes it storage for a stop the client keeps nowhere else. benilla keeps the stop:
-/// [`CVAR_WORLD_DETAIL`] is it, and `frillDensity` is the same knob in the reference's unit. So the
-/// getter reads the stop directly and `SmallCull` is not registered, because registering a CVar
-/// whose only purpose is to hold a number we already hold is the silent pretence 1203 forbids.
-///
-/// The observable consequence is **nil at boot and nil for every consumer we know**: a fresh
-/// reference client has `frillDensity 16` with `smallCull 0.04` — stop 0's frill with stop 1's cull
-/// — so its getter answers **1**, and benilla's `WorldDetail` registers at `"1"` for exactly that
-/// reason. The one input that separates them is a bare `frillDensity` write with no stop write,
-/// which there leaves the getter on the stale stop and here moves it; pfUI's `hdgraphic` is the
-/// only known caller and its own replacement short-circuits above 48, so it never reaches the
-/// difference.
+/// Deviation: the getter reads [`CVAR_WORLD_DETAIL`] and `smallCull` is not registered, because
+/// the reference's getter is `smallCull`'s only reader (`[0x868620]` is never read). A fresh
+/// reference client reads stop 1 (`frillDensity 16` with `smallCull 0.04`), hence
+/// `WorldDetail`'s `"1"`; only a bare `frillDensity` write moves ours and not the reference's.
 fn install_world_detail_verbs(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
     g.set(
         "SetWorldDetail",
         lua.create_function(|lua, value: Value| {
-            // `lua_isnumber`: a number, or a string Lua can convert to one. Anything else is the
-            // usage error — NOT a silent no-op.
+            // `lua_isnumber`: a number or a numeric string; anything else is the usage error.
             let n = match &value {
                 Value::Integer(i) => *i as f64,
                 Value::Number(n) => *n,
@@ -1097,9 +760,8 @@ fn install_world_detail_verbs(lua: &Lua) -> mlua::Result<()> {
                 }
                 _ => return Err(mlua::Error::runtime(USAGE_SET_WORLD_DETAIL)),
             };
-            // Truncate toward zero (`0x40a2b0`'s chop), then the reference's own two bounds. NaN
-            // has no truncation — the reference's `fistp` yields the integer indefinite, which is
-            // negative and raises, so raising here is the same answer by the same door.
+            // Truncate toward zero, then the reference's bounds: -0.5 is stop 0 and only <= -1
+            // raises. NaN raises too, as the reference's `fistp` gives the negative indefinite.
             if n.is_nan() {
                 return Err(mlua::Error::runtime(RANGE_SET_WORLD_DETAIL));
             }
@@ -1109,11 +771,8 @@ fn install_world_detail_verbs(lua: &Lua) -> mlua::Result<()> {
             }
             let stop = stop as usize;
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // TWO CVars per stop, as `0x488dd0` writes two: there it is `frillDensity` + the dead
-            // `smallCull`; here it is `frillDensity` + the stop the panel keeps. Both land on one
-            // clutter knob in the host, so applying both is idempotent — and writing only one
-            // would leave the other stale for a `GetWorldDetail` in the same Lua tick, since the
-            // host does not drain the change queue until the end of the frame.
+            // Two CVars per stop, as `0x488dd0` writes two: `frillDensity` and, here, the stop.
+            // Writing only one would leave `GetWorldDetail` stale until the host drains the queue.
             write_cvar(
                 &mut model,
                 CVAR_FRILL_DENSITY,
@@ -1127,19 +786,16 @@ fn install_world_detail_verbs(lua: &Lua) -> mlua::Result<()> {
     )?;
     g.set(
         "GetWorldDetail",
-        // `MultiValue` in: the reference reads argument 1 for the SETTER only; the getter never
-        // calls `lua_gettop`, so an argument is accepted and ignored — and pfUI's replacement is
-        // declared `function _G.GetWorldDetail(arg)`, so it is passed one in practice.
+        // `MultiValue`: an argument is accepted and ignored, as the getter never calls
+        // `lua_gettop`.
         lua.create_function(|lua, _: mlua::MultiValue| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             let stop = model
                 .cvars
                 .get(&CVAR_WORLD_DETAIL.to_ascii_lowercase())
                 .and_then(|slot| slot.value.parse::<f64>().ok())
-                // The reference can only ever answer 0, 1 or 2 (its result is an index into a
-                // three-entry table), so an off-grid stop — which ours can hold, because a console
-                // `frillDensity 200` moves the same knob — reports the nearest one rather than a
-                // number no caller has a branch for.
+                // The reference only answers 0, 1 or 2, so an off-grid stop (a console
+                // `frillDensity 200` moves it) reports the nearest.
                 .map_or(0, |v| v.round().clamp(0.0, 2.0) as i64);
             Ok(stop)
         })?,
@@ -1150,36 +806,17 @@ fn install_world_detail_verbs(lua: &Lua) -> mlua::Result<()> {
 /// `0x8423e8`, verbatim.
 const USAGE_SET_WORLD_DETAIL: &str = "Usage: SetWorldDetail(value)";
 
-/// `0x8423b8`, verbatim — lowercase `v`, and the odd comma is the reference's own.
+/// `0x8423b8`, verbatim: the lowercase `v` and the odd comma are the reference's.
 const RANGE_SET_WORLD_DETAIL: &str = "value must be in the range 0, 2";
 
-/// **The four nameplate verbs** — `ShowNameplates 0x489450`, `HideNameplates 0x489460`,
-/// `ShowFriendNameplates 0x489470`, `HideFriendNameplates 0x489480`.
+/// The four nameplate verbs: `ShowNameplates 0x489450`, `HideNameplates 0x489460`,
+/// `ShowFriendNameplates 0x489470`, `HideFriendNameplates 0x489480`. Each ignores its arguments
+/// (`ShowNameplates(false)` still shows) and returns zero values, and there is no getter; the
+/// state is bits `0x1` (enemy) and `0x8` (friend) of `[0xc4da34]`.
 ///
-/// Each is a **10-byte body** over one of two setters, and the reference's shape is worth stating
-/// because two obvious readings are wrong:
-///
-/// - **They read NO argument.** `ShowNameplates(false)` still shows. There is no `lua_gettop`, no
-///   `lua_toboolean`, nothing — the verb *is* the value, which is why there are four of them
-///   rather than two taking a flag.
-/// - **They return ZERO Lua values** — not `nil`, nothing. (`eax` at the `ret` is the return
-///   count, read off the VM's own C arm `0x6f61a8`.)
-/// - They are **four separate bodies**, not a masked pair like `UnitIsTapped`/`ByPlayer`:
-///   `0x489450` and `0x489470` are literally identical byte strings, rel32 included, over setters
-///   that differ only in their `or`/`and` masks.
-///
-/// The engine state is bits `0x1` (enemy) and `0x8` (friend) of one runtime dword `[0xc4da34]`.
-/// **There is no getter** — 15 references image-wide, all `.text`, and the 1153 `{name, fn}`
-/// records across all 54 registrar tables intersect the readers in the empty set — so an addon can
-/// set the state and never read it back, and neither can we.
-///
-/// **Where benilla diverges, deliberately and now knowingly.** 1.12 registers no nameplate CVar
-/// (censused: `0x63db90`'s 214 sites, 207 literal names, zero matching `/plate/i`), and the engine
-/// clears **both bits on every `EnterWorld`** — not once at boot. FrameXML replays them from its
-/// own `NAMEPLATES_ON`/`FRIENDNAMEPLATES_ON` saved variables. Our two CVars reproduce *FrameXML's
-/// replay*, not the engine's state model: a benilla player's plates survive a zone-in because the
-/// CVar store outlives it. That is a divergence in favour of the player, recorded here rather than
-/// mistaken for fidelity.
+/// Deviation: the state lives in two CVars, so a player's plates survive a zone-in; the reference
+/// registers no nameplate CVar (none of `0x63db90`'s sites), clears both bits on every
+/// `EnterWorld`, and FrameXML replays its `NAMEPLATES_ON`/`FRIENDNAMEPLATES_ON` saved variables.
 fn install_nameplate_verbs(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
     for (name, cvar, on) in [
@@ -1190,9 +827,8 @@ fn install_nameplate_verbs(lua: &Lua) -> mlua::Result<()> {
     ] {
         g.set(
             name,
-            // `MultiValue` and not `()`: mlua would otherwise reject a call that passes anything,
-            // and the reference accepts and ignores every argument. Returning `MultiValue::new()`
-            // is the zero-value return, which is NOT the same as pushing nil.
+            // Any arguments are ignored, as the reference reads none; the empty `MultiValue`
+            // returns zero values, which is not nil.
             lua.create_function(move |lua, _: mlua::MultiValue| {
                 let mut model = lua.app_data_mut::<Model>().expect("model app_data");
                 let key = cvar.to_ascii_lowercase();
@@ -1225,37 +861,29 @@ mod tests {
     #[test]
     fn the_table_round_trips_and_queues_changes_case_insensitively() {
         let mut s = script_with_volume();
-        // Registration seeds value = default; reads are case-insensitive.
         assert_eq!(
             s.eval::<String>(r#"return GetCVar("musicvolume")"#)
                 .unwrap(),
             "0.4"
         );
-        // A Lua write queues ONE change under the REGISTERED spelling; the number stringifies.
         s.run(r#"SetCVar("MUSICVOLUME", 0.7)"#).unwrap();
         assert_eq!(
             s.take_cvar_changes(),
             vec![("MusicVolume".to_string(), "0.7".to_string())]
         );
         assert!(s.take_cvar_changes().is_empty(), "drained");
-        // The default is unmoved and separately readable.
         assert_eq!(
             s.eval::<String>(r#"return GetCVarDefault("MusicVolume")"#)
                 .unwrap(),
             "0.4"
         );
         assert_eq!(s.cvar("MusicVolume").as_deref(), Some("0.7"));
-        // A write to the same value queues nothing (quiet frames stay quiet).
         s.run(r#"SetCVar("MusicVolume", "0.7")"#).unwrap();
         assert!(s.take_cvar_changes().is_empty());
     }
 
-    /// **A latched row stages the write and keeps answering the applied value** (decision 2303)
-    /// — the reference's `Set 0x63df50` on flag bit1: `latchedValue` takes the string, `InternalSet`
-    /// never runs, so `GetCVar` (which reads `rec+0x20`) answers the old value until
-    /// `CVar::Update 0x63e060` commits it. The host still hears every staged write through the
-    /// change queue (it holds the pending copy), and its commit arrives as a host write, which
-    /// clears the stage. Writing the applied value back over a stage clears the stage too.
+    /// The reference's `Set 0x63df50` on flag bit1: `GetCVar` (`rec+0x20`) answers the old value
+    /// until `CVar::Update 0x63e060` commits, which here arrives as a host write.
     #[test]
     fn a_latched_row_stages_the_write_until_the_host_commits_it() {
         let mut s = UiScript::new().unwrap();
@@ -1285,7 +913,7 @@ mod tests {
             "the host hears the staged write"
         );
         // Staging the same value again is quiet; staging the applied value back clears the stage
-        // and is reported, so the host can drop its pending copy too.
+        // and is reported, so the host drops its pending copy too.
         s.run(r#"SetCVar("gxVSync", "0")"#).unwrap();
         assert!(s.take_cvar_changes().is_empty());
         s.run(r#"SetCVar("gxVSync", "1")"#).unwrap();
@@ -1306,7 +934,6 @@ mod tests {
             "0"
         );
         assert!(s.take_cvar_changes().is_empty());
-        // An unlatched sibling is untouched by any of this.
         s.run(r#"SetCVar("MusicVolume", 0.7)"#).unwrap();
         assert_eq!(
             s.eval::<String>(r#"return GetCVar("MusicVolume")"#)
@@ -1315,10 +942,6 @@ mod tests {
         );
     }
 
-    /// **An addon's `RegisterCVar` reaches the host** (decision 2303): the row it creates is
-    /// reported once, with the declared default, so the host's registry — the store that
-    /// outlives this VM — can carry it. A re-declaration of a live name is the no-op it always
-    /// was, and reports nothing.
     #[test]
     fn an_addon_registration_is_reported_to_the_host_once() {
         let mut s = UiScript::new().unwrap();
@@ -1336,10 +959,8 @@ mod tests {
         );
     }
 
-    /// **A bare CVar name through `ConsoleExec` is the host's to answer** (decision 2303): the
-    /// reference's per-CVar console command prints `CVar "%s" is "%s"` on an empty argument
-    /// (`0x63dde0`), and that printing lives host-side with the rest of the command registry.
-    /// A name WITH a value is still written synchronously, so the next Lua line reads it back.
+    /// The reference prints `CVar "%s" is "%s"` for a bare name (`0x63dde0`); that printing is the
+    /// host's, while a valued write lands here at once.
     #[test]
     fn console_exec_writes_a_valued_cvar_and_hands_a_bare_name_to_the_host() {
         let mut s = script_with_volume();
@@ -1357,12 +978,6 @@ mod tests {
         assert_eq!(s.take_console_lines(), vec!["MusicVolume".to_string()]);
     }
 
-    /// **`SetCVar`'s third argument is the `CVAR_UPDATE` token** (decision 1140) — the whole
-    /// mechanism behind that event. 1.12's options panels pass their CheckButtons table KEY
-    /// (`SetCVar(value.cvar, value.value, index)`), an uppercase display name, and the engine
-    /// hands it back verbatim as arg1 — which is what lets `UIOptionsFrame_OnEvent` do
-    /// `UIOptionsFrameCheckButtons[arg1]`. Omit it and nothing fires: the event is opt-in per
-    /// write. A write that changes nothing fires nothing either, like the change queue.
     #[test]
     fn the_third_argument_is_the_cvar_update_token() {
         let mut s = script_with_volume();
@@ -1374,13 +989,11 @@ mod tests {
         )
         .unwrap();
 
-        // No token: the value moves, the change queues, the event does not fire.
         s.run(r#"SetCVar("MusicVolume", "0.5")"#).unwrap();
         s.tick(0.0);
         assert_eq!(s.eval::<f64>("return getn(SEEN)").unwrap(), 0.0);
 
-        // With one: arg1 is the token verbatim (the display name, NOT the CVar's own name),
-        // arg2 the new value.
+        // With one: arg1 is the token verbatim, not the CVar's name, and arg2 the new value.
         s.run(r#"SetCVar("MusicVolume", "0.6", "MUSIC_VOLUME")"#)
             .unwrap();
         s.tick(0.0);
@@ -1389,7 +1002,6 @@ mod tests {
             "MUSIC_VOLUME=0.6"
         );
 
-        // A no-op write is silent on both channels.
         s.run(r#"SetCVar("MusicVolume", "0.6", "MUSIC_VOLUME")"#)
             .unwrap();
         s.tick(0.0);
@@ -1432,14 +1044,6 @@ mod tests {
         s.register_cvars([("MusicVolume", "0.4")]);
         assert_eq!(s.cvar("MusicVolume").as_deref(), Some("0.9"));
     }
-    /// **`GetCVar("realmName")` answers the session's realm, set by the one seam that owns it.**
-    ///
-    /// It is a real 1.12 CVar (`0x83f2d0`, persisted — the client builds its SavedVariables path
-    /// from it) and it had no value here at all. `Ace/AceState.lua:27` is
-    /// **Registration honors the saved base** (decision 1291) — the bridge that makes the
-    /// per-VM table behave like the reference's engine-side store: a knobless CVar keeps the
-    /// player's persisted value across a VM replacement, and the default stays the DEFAULT so
-    /// "moved off default" still means something to the saver.
     #[test]
     fn registration_starts_at_the_saved_value_not_the_default() {
         let mut s = UiScript::new().unwrap();
@@ -1465,8 +1069,6 @@ mod tests {
         );
     }
 
-    /// The same law through the Lua half: an addon's `RegisterCVar` (decision 1195) starts at
-    /// the persisted value, so its setting survives the VM being replaced (1290/1291).
     #[test]
     fn an_addon_registered_cvar_starts_at_its_saved_value() {
         let mut s = UiScript::new().unwrap();
@@ -1485,10 +1087,6 @@ mod tests {
         );
     }
 
-    /// The Video options Multisampling dropdown, driven exactly as `OptionsFrame.lua` drives it:
-    /// `_Initialize` walks `GetMultisampleFormats()` three varargs at a time, `_OnLoad` seeds the
-    /// selection from `GetCurrentMultisampleFormat()`, and the Okay handler (l.240) writes back
-    /// through `SetMultisampleFormat(id)`.
     #[test]
     fn the_multisample_dropdown_round_trips_through_the_three_bindings() {
         let mut s = UiScript::new().unwrap();
@@ -1515,7 +1113,6 @@ mod tests {
             },
         ]);
 
-        // Flat triples, in order — the shape `for i=1, arg.n, 3` walks.
         let flat: Vec<f64> = s.eval(r#"return { GetMultisampleFormats() }"#).unwrap();
         assert_eq!(
             flat,
@@ -1523,14 +1120,14 @@ mod tests {
             "three fields per entry, entries in offer order"
         );
 
-        // 1-BASED: the default `gxMultisample "1"` is the FIRST row, not the zeroth.
+        // 1-based: the default `gxMultisample "1"` is the first row.
         assert_eq!(
             s.eval::<f64>("return GetCurrentMultisampleFormat()")
                 .unwrap(),
             1.0
         );
 
-        // Pick 4x — the third row — and all three CVars move together, as `0x48c640` writes them.
+        // Pick 4x, the third row: all three CVars move together, as `0x48c640` writes them.
         s.eval::<()>("SetMultisampleFormat(3)").unwrap();
         assert_eq!(
             s.eval::<String>(r#"return GetCVar("gxMultisample")"#)
@@ -1549,8 +1146,6 @@ mod tests {
             "the selection round-trips: what Set wrote, GetCurrent finds"
         );
 
-        // The host sees the write, so the config file is dirtied — the same route a Lua SetCVar
-        // takes. Without this the player's choice would live only until they quit.
         let changed: Vec<String> = s
             .take_cvar_changes()
             .into_iter()
@@ -1561,8 +1156,6 @@ mod tests {
             "expected gxMultisample on the change queue, got {changed:?}"
         );
 
-        // Off the end is ignored, never clamped: a clamp would silently apply a format the player
-        // did not choose.
         s.eval::<()>("SetMultisampleFormat(99)").unwrap();
         assert_eq!(
             s.eval::<String>(r#"return GetCVar("gxMultisample")"#)
@@ -1572,17 +1165,14 @@ mod tests {
         );
     }
 
-    /// `ace.trim(GetCVar("realmName"))` inside `SetGameState`, which EVERY Ace addon runs at
-    /// PLAYER_ENTERING_WORLD, so nil became `gsub(nil, ...)` and took the whole family down.
-    ///
-    /// Asserted through `set_realm_name` rather than by writing the CVar directly, because that is
-    /// the point: the CVar and `GetRealmName()` are the SAME fact and must not be settable apart.
+    /// `realmName` is a real 1.12 CVar (`0x83f2d0`) and must be a string: every Ace addon runs
+    /// `ace.trim(GetCVar("realmName"))` at `PLAYER_ENTERING_WORLD` (`Ace/AceState.lua:28`). Set
+    /// through `set_realm_name`, the seam `GetRealmName()` also reads.
     #[test]
     fn the_realm_name_cvar_and_get_realm_name_are_one_fact() {
         let mut s = UiScript::new().unwrap();
         s.register_cvars([("realmName", "")]);
 
-        // Before a session: empty, never nil — `ace.trim` must have a string to gsub.
         assert_eq!(
             s.eval::<String>(r#"return GetCVar("realmName")"#).unwrap(),
             ""
diff --git a/crates/benilla-ui/src/script/death.rs b/crates/benilla-ui/src/script/death.rs
index 3079378c..5330a4d0 100644
--- a/crates/benilla-ui/src/script/death.rs
+++ b/crates/benilla-ui/src/script/death.rs
@@ -1,87 +1,63 @@
-//! The death-arc Lua surface (decisions 0308, 1746): the release/reclaim/resurrect/self-res verbs
-//! and the state getters the reference's DEATH / RECOVER_CORPSE / RESURRECT* / XP_LOSS dialogs
-//! call.
-//!
-//! Engine-free seam like [`super::unit`]: the app pushes a [`DeathUiState`] snapshot per frame
-//! (the countdowns + offer bits it computes from the wire) and drains the queued
-//! [`DeathAction`]s into `ClientCommand`s. The predicates return Lua booleans rather than the
-//! client's `1`/nil — truthy either way, the branch shape callers use is identical (the
-//! [`super::unit`] convention).
+//! The release, reclaim, resurrect and self-res verbs and the getters the `DEATH`,
+//! `RECOVER_CORPSE`, `RESURRECT` and `XP_LOSS` dialogs call, over a snapshot the app pushes.
+//! The three predicates answer Lua booleans where the reference answers `1` or nil
+//! (`ResurrectHasSickness` `0x48aa00`, `ResurrectHasTimer` `0x48aa30`, `CheckSpiritHealerDist`
+//! `0x48d120`).
 
 use mlua::{Lua, Value};
 
 use super::Model;
 
-/// The death snapshot the app pushes each frame ([`super::UiScript::set_death`]). Plain data —
-/// no mlua handles, no ECS types.
+/// The death snapshot the app pushes each frame.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct DeathUiState {
-    /// Seconds until the server force-releases — the client-side mirror of the 6:00
-    /// `CORPSE_REPOP_TIME` the wire never carries (decision 0308 §4), counted from the death
-    /// edge. `None` = no release timer (`PLAYER_FIELD_BYTES` bit 0x08 clear — an instanceable
-    /// map): `GetReleaseTimeRemaining` returns **−1** and the DEATH dialog shows the no-timer
-    /// text.
+    /// Seconds until the server force-releases, counted from death against the 6-minute
+    /// `CORPSE_REPOP_TIME` the wire never carries. `None` (`PLAYER_FIELD_BYTES` bit `0x08` clear,
+    /// an instanceable map) answers -1, which picks the no-timer text (`StaticPopup.lua:380-387`).
     pub release_remaining: Option<f32>,
-    /// Seconds until the corpse becomes reclaimable (`SMSG_CORPSE_RECLAIM_DELAY` anchored at
-    /// arrival; `0` = reclaimable now). `GetCorpseRecoveryDelay`'s value — the RECOVER_CORPSE /
-    /// RESURRECT StartDelay gate.
+    /// Seconds until the corpse is reclaimable, from `SMSG_CORPSE_RECLAIM_DELAY` at arrival; the
+    /// `StartDelay` gate of `RECOVER_CORPSE` and `RESURRECT`.
     pub recovery_delay: f32,
     /// The pending resurrect offer warns of resurrection sickness (`ResurrectHasSickness`).
     pub resurrect_sickness: bool,
     /// The pending offer still honors the reclaim-delay gate (`ResurrectHasTimer`).
     pub resurrect_has_timer: bool,
-    /// The confirm-owning spirit healer is within dialog range (`CheckSpiritHealerDist` — the
-    /// XP_LOSS dialogs' OnUpdate auto-hide).
+    /// The confirming spirit healer is in dialog range (`CheckSpiritHealerDist`).
     pub spirit_healer_in_range: bool,
-    /// The "N minutes"/"N seconds" sickness-duration string a spirit-healer res would apply, or
-    /// `None` below the sickness level (`GetResSicknessDuration` → nil — picks XP_LOSS vs
-    /// XP_LOSS_NO_SICKNESS, ref UIParent.lua's CONFIRM_XP_LOSS arm).
+    /// The sickness duration a spirit-healer res would apply ("N minutes"); `None` below the
+    /// sickness level picks `XP_LOSS_NO_SICKNESS` (`UIParent.lua:399-408`).
     pub sickness_duration: Option<String>,
-    /// What `HasSoulstone()` answers: the **label** of the self-resurrect available right now, or
-    /// `None` for nil (`HasSoulstone 0x48ac80`; decision 1746).
-    ///
-    /// A string, not an id, because that is the whole of what the API returns: the DEATH dialog
-    /// stamps it straight onto its second button (`Button2:SetText(HasSoulstone())`) and uses the
-    /// same call as `DisplayButton2`. The app resolves it, because the script VM has no
-    /// spell-catalog or item-cache binding (the `ui_cast`/`ui_mirror` idiom, decision 0107).
-    ///
-    /// Two sources, and the client's own fork picks between them
-    /// ([`crate::script::death`]'s app-side resolver): `PLAYER_SELF_RES_SPELL` named through
-    /// `Spell.dbc` (3026/20758-20761 are all literally **"Use Soulstone"**, 21169
-    /// **"Reincarnation"**, 23700 **"Twisting Nether"** — Blizzard named those effect spells *as
-    /// button labels*), else a carried item whose on-use spell self-resurrects, named by the
-    /// **item**.
+    /// `HasSoulstone()`'s label (`0x48ac80`), stamped on the DEATH dialog's second button:
+    /// `PLAYER_SELF_RES_SPELL`'s `Spell.dbc` name (3026 and 20758-20761 "Use Soulstone", 21169
+    /// "Reincarnation", 23700 "Twisting Nether"), else a carried self-resurrect item's name.
     pub self_res_label: Option<String>,
 }
 
-/// One drained death intent (the app's [`super::UiScript::take_death_actions`] maps each to its
-/// `ClientCommand`).
+/// One drained death intent.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum DeathAction {
-    /// `RepopMe()` — release the spirit (`CMSG_REPOP_REQUEST`).
+    /// `RepopMe()`: `CMSG_REPOP_REQUEST`.
     Repop,
-    /// `RetrieveCorpse()` — reclaim the corpse (`CMSG_RECLAIM_CORPSE`).
+    /// `RetrieveCorpse()`: `CMSG_RECLAIM_CORPSE`.
     RetrieveCorpse,
-    /// `AcceptResurrect()` — accept the pending offer (`CMSG_RESURRECT_RESPONSE` accept).
+    /// `AcceptResurrect()`: `CMSG_RESURRECT_RESPONSE`, accepting.
     AcceptResurrect,
-    /// `DeclineResurrect()` — decline it (`CMSG_RESURRECT_RESPONSE` decline).
+    /// `DeclineResurrect()`: `CMSG_RESURRECT_RESPONSE`, declining.
     DeclineResurrect,
-    /// `AcceptXPLoss()` — take the spirit healer's res (`CMSG_SPIRIT_HEALER_ACTIVATE`).
+    /// `AcceptXPLoss()`: `CMSG_SPIRIT_HEALER_ACTIVATE`.
     AcceptXpLoss,
-    /// `UseSoulstone()` — spend the self-resurrect. **Which wire that is, is the app's to decide
-    /// at drain time**, exactly as the binding decides it at call time: a non-zero
-    /// `PLAYER_SELF_RES_SPELL` sends `CMSG_SELF_RES`, and a zero one falls through to using the
-    /// carried item instead (decision 1746).
+    /// `UseSoulstone()`: `CMSG_SELF_RES` when `PLAYER_SELF_RES_SPELL` is non-zero, else a use of
+    /// the carried item, decided at drain time as the reference decides it at call time.
     UseSoulstone,
 }
 
 impl super::UiScript {
-    /// Push this frame's death snapshot (the app's per-frame feed, before the event dispatch).
+    /// Push this frame's death snapshot, before the event dispatch.
     pub fn set_death(&mut self, state: DeathUiState) {
         self.model_mut().death = state;
     }
 
-    /// Drain the queued death intents (the app's per-frame drain).
+    /// Drain the queued death intents.
     pub fn take_death_actions(&mut self) -> Vec<DeathAction> {
         std::mem::take(&mut self.model_mut().death_actions)
     }
@@ -107,8 +83,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     install_action(lua, "AcceptXPLoss", DeathAction::AcceptXpLoss)?;
     install_action(lua, "UseSoulstone", DeathAction::UseSoulstone)?;
 
-    // GetReleaseTimeRemaining() → seconds until the forced release, or −1 = no timer (the DEATH
-    // dialog's no-timer text pick, ref StaticPopup.lua:380-387).
     g.set(
         "GetReleaseTimeRemaining",
         lua.create_function(|lua, ()| {
@@ -120,7 +94,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCorpseRecoveryDelay() → whole seconds until reclaimable (0 = now) — the StartDelay gate.
     g.set(
         "GetCorpseRecoveryDelay",
         lua.create_function(|lua, ()| {
@@ -151,8 +124,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetResSicknessDuration() → the duration string, or nil below the sickness level (the
-    // CONFIRM_XP_LOSS variant pick, ref UIParent.lua:399-408).
     g.set(
         "GetResSicknessDuration",
         lua.create_function(|lua, ()| {
@@ -164,12 +135,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // HasSoulstone() → the self-resurrect's label, or nil (decision 1746). The DEATH dialog
-    // uses the one call three ways — `DisplayButton2` (show the button at all), `OnShow`
-    // (`Button2:SetText(text)`) and `OnCancel`'s clicked arm (soulstone vs release) — so the
-    // falsey return has to be **nil** and not `0`: Lua's `0` is truthy, and a `0` here would both
-    // show the button forever and stamp "0" on it. The whole answer is computed app-side; this is
-    // a pure read of the pushed snapshot.
+    // Nil, never `0`, when there is none: the DEATH dialog shows its second button on any truthy
+    // answer, stamps the answer on it and picks soulstone over release by it.
     g.set(
         "HasSoulstone",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/diagnostics.rs b/crates/benilla-ui/src/script/diagnostics.rs
index a38b2ed9..5ce47a31 100644
--- a/crates/benilla-ui/src/script/diagnostics.rs
+++ b/crates/benilla-ui/src/script/diagnostics.rs
@@ -1,61 +1,12 @@
-//! The **script error log** — what went wrong, kept where the player can read it (decision 1495).
+//! The script error log: this session's script errors, addon load failures and warnings, kept
+//! for the player to read. The reference has no such log: its `_ERRORMESSAGE` shows only the first
+//! message of a burst, and a load failure that never raises reaches no screen. Dispatch and
+//! `_ERRORMESSAGE` are unchanged by it.
 //!
-//! ## Why this exists
-//!
-//! 1305 gave script errors a *screen*: the engine dispatches every caught error to
-//! `geterrorhandler()`, and FrameXML's `_ERRORMESSAGE` puts the red `ScriptErrors` dialog up. That
-//! is the reference's behaviour and it stays exactly as it is. It is also, on its own, not enough,
-//! and it leaves two asks: a Lua error frame that says which addons still fail, and a
-//! BugGrabber-style collector that keeps their stack traces for a bug report.
-//!
-//! Both asks are the same three gaps, and all three are about *memory*:
-//!
-//! 1. **`_ERRORMESSAGE` shows a burst's FIRST message only** — its own `ScriptErrors:IsVisible()`
-//!    guard, faithfully transcribed. A world entry that raises 1,113 times (1305 measured exactly
-//!    that) shows one string. This is precisely why BugGrabber exists in the real world.
-//! 2. **An addon can fail to load without ever raising**, and those failures had no channel at all
-//!    — a manifest entry the package does not ship, a document that will not parse, a dependency
-//!    cycle, a missing hard dependency, a broken `Bindings.xml`. They logged to the terminal and
-//!    stopped; the addon simply was not there and the client said nothing.
-//! 3. **Nothing retained anything.** [`super::UiScript::take_errors`] drains to the host log every
-//!    frame, so once a frame passed, the terminal held the only copy. A player cannot read a
-//!    terminal, and a bug report written from one is what B271 was debugged off.
-//!
-//! ## What this is, and what it deliberately is not
-//!
-//! A bounded, deduplicating, ordered log of everything that went wrong this session, written at
-//! the two choke points every failure already passes ([`super::model::Model::record_script_error`]
-//! and [`super::UiScript::report_load_failure`]) and read by whatever wants to show it.
-//!
-//! **"Session" means one world session, not one process.** The log lives on the `Model`, and the
-//! in-game UI is rebuilt onto a fresh VM at every world entry (1290) — so a logout or a `ReloadUI`
-//! starts an empty log. That is the right boundary and it self-heals: the load walk runs again on
-//! the way back in and re-records whatever is still broken. What it is *not* is a place to look for
-//! what happened before the reload you just did.
-//!
-//! It is **purely additive**: no dispatch changes, no `_ERRORMESSAGE` change, no divergence from
-//! the reference's own behaviour. The reference simply never had this instrument, and *"a modern,
-//! idiomatic client"* covers building one.
-//!
-//! It is **not** a transcription of BugGrabber, which is somebody else's addon (and not Blizzard's
-//! either). It is our own equivalent, and an addon that installs its own `seterrorhandler` still
-//! wins outright for the dispatch half exactly as 1195/1305 leave it.
-//!
-//! ## Dedupe, order, and the bound
-//!
-//! **Repeats collapse onto the first occurrence and bump a count.** An `OnUpdate` that raises
-//! every frame is one row reading `×1113`, not 1,113 rows — without that the log is useless within
-//! seconds, and unbounded besides.
-//!
-//! **Order is first-occurrence, oldest first.** The load-time failures are the causes and the
-//! later runtime errors are usually their consequences, so a chronological read is the one that
-//! explains itself. A repeat does *not* move its row to the end: a row that jumps around while you
-//! read it is worse than a stale position.
-//!
-//! **[`DIAGNOSTIC_LOG_CAP`] distinct rows**, evicting oldest-first. `seq` is monotonic and never
-//! reused, so an evicted prefix is visible as a gap rather than silently rewriting history — a
-//! surface can say "showing #251-#500" honestly. The cap binds *distinct* messages, which after
-//! dedupe is a much higher ceiling than it looks: 1305's 1,113-raise run produces **one** row.
+//! A repeat bumps its row's count and keeps its place, rows are oldest first, and past
+//! [`DIAGNOSTIC_LOG_CAP`] distinct messages the oldest is evicted; `seq` is never reused, so an
+//! eviction shows as a gap. The log lives on the `Model`, and every world entry and `ReloadUI`
+//! builds a fresh VM, so each starts an empty log.
 
 use std::collections::VecDeque;
 
@@ -63,43 +14,25 @@ use mlua::{IntoLua, Lua, MultiValue, Value};
 
 use super::Model;
 
-/// How many **distinct** messages the log retains before evicting the oldest.
-///
-/// Sized against the worst real load we have measured rather than a round number: the 218-addon
-/// corpus behind 1306, loaded at once, is the widest set of distinct failures this client has ever
-/// produced. Dedupe means repeats cost nothing, so this bounds *kinds* of problem, not events.
+/// Distinct messages retained before the oldest is evicted, sized for the whole 218-addon corpus
+/// loaded at once.
 pub const DIAGNOSTIC_LOG_CAP: usize = 256;
 
-/// What a retained row *is* — and the split is by **consequence**, not by where it was caught,
-/// because that is the only distinction the player can act on.
+/// What a row reports, split by its consequence to the player.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum DiagnosticKind {
-    /// **Code ran and raised.** The addon is loaded and working apart from this; the failure may
-    /// be harmless, may be one frame's bad luck, may be constant. This is the class that already
-    /// reaches the red dialog.
+    /// Code ran and raised; the addon is otherwise loaded.
     Error,
-    /// **An addon did not load.** Definitely broken, definitely worth telling somebody about, and
-    /// before 1495 invisible unless you were reading the terminal. Both the raising kind (a file
-    /// scope that blew up) and the silent kind (a missing file, an unparseable document, a
-    /// dependency that isn't there) land here — from the player's side they are one thing: *the
-    /// addon isn't running*.
+    /// An addon did not load, whether its file scope raised or a file, document or dependency
+    /// was missing or broken.
     Load,
-    /// **The call was accepted and did not do what it said.** Nothing raised and nothing failed to
-    /// load: an `inherits=` argument that was not a template name and got dropped, a `SetPoint`
-    /// whose `relativeTo` did not resolve and re-anchored to the owner, a `SetCVar` on a name
-    /// nothing registered, a saved variable that could not be serialised, a `CreateMacro` that
-    /// was refused. The addon runs on, believing it got what it asked for.
-    ///
-    /// **This kind exists because the channel was a dead end** (decision 2135). These messages had
-    /// one consumer — a `warn!` line in the host's terminal, drained and discarded every frame —
-    /// so they reached neither the player (who cannot read a terminal, which is the whole
-    /// argument of 1495 above) nor the addon survey (whose columns read `errors`). A warning is
-    /// exactly the class an instrument is *for*: it is the failure that does not announce itself.
+    /// A call was accepted and did not do what it said (a dropped `inherits=`, an unresolved
+    /// `SetPoint` target, a `SetCVar` on an unregistered name, a refused `CreateMacro`).
     Warning,
 }
 
 impl DiagnosticKind {
-    /// The one-word tag a surface prints. Stable — a surface may key colour off it.
+    /// The one-word tag a surface prints; stable, as a surface may key colour off it.
     pub fn tag(self) -> &'static str {
         match self {
             Self::Error => "error",
@@ -112,41 +45,31 @@ impl DiagnosticKind {
 /// One retained row.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Diagnostic {
-    /// Monotonic, 1-based, **never reused** — the "#N" a surface shows. Survives eviction, so a
-    /// gap in the numbers is an honest report that older rows were dropped.
+    /// The "#N" a surface shows: 1-based, monotonic and never reused.
     pub seq: u64,
     pub kind: DiagnosticKind,
-    /// The message exactly as the host logged it — same string, same spelling, so a player's
-    /// screenshot and our terminal line are greppable against each other.
+    /// The message exactly as the host logged it.
     pub message: String,
-    /// How many times this exact `(kind, message)` has occurred. Starts at 1.
+    /// Occurrences of this `(kind, message)`, from 1.
     pub count: u32,
 }
 
-/// The log itself. Lives on the model; see the module header for the shape and the why.
+/// The log, held on the model.
 #[derive(Debug, Default)]
 pub(crate) struct DiagnosticLog {
     rows: VecDeque<Diagnostic>,
-    /// The last `seq` handed out. Kept separately from `rows.len()` precisely so eviction cannot
-    /// renumber anything.
+    /// The last `seq` handed out; kept apart from `rows.len()` so eviction never renumbers.
     seq: u64,
 }
 
 impl DiagnosticLog {
-    /// Record one failure, collapsing it onto an existing identical row if there is one.
-    ///
-    /// The dedupe scan is linear over at most [`DIAGNOSTIC_LOG_CAP`] rows and runs on the failure
-    /// path only. The pathological caller is an `OnUpdate` raising at frame rate, where the scan
-    /// hits its row and returns — cheaper by far than the `String` allocation it saves, and
-    /// arithmetic beside the `mlua` error formatting that produced the message in the first place.
+    /// Record one failure, or bump the count of its identical row.
     pub(crate) fn record(&mut self, kind: DiagnosticKind, message: &str) {
         if let Some(row) = self
             .rows
             .iter_mut()
             .find(|r| r.kind == kind && r.message == message)
         {
-            // Saturating rather than wrapping: a count that rolls over to 0 reads as "this never
-            // happened", which is the one answer that is never true here.
             row.count = row.count.saturating_add(1);
             return;
         }
@@ -172,83 +95,54 @@ impl DiagnosticLog {
         self.rows.len()
     }
 
-    /// Distinct failures **ever** recorded this session, including rows since evicted. The
-    /// difference from [`Self::len`] is how many the cap ate.
+    /// Distinct failures recorded this session, evicted and cleared rows included.
     pub(crate) fn total(&self) -> u64 {
         self.seq
     }
 
-    /// Forget everything — the player's own "I've read these" act. Deliberately does **not** reset
-    /// `seq`: after a clear, the next row is still #N+1, so a screenshot taken before the clear and
-    /// one taken after cannot claim the same number for different failures.
+    /// Forget the rows but not the numbering, so no `#N` ever names two failures.
     pub(crate) fn clear(&mut self) {
         self.rows.clear();
     }
 }
 
 impl super::UiScript {
-    /// Every retained row, oldest first — a clone, because the caller is the app's UI and the
-    /// model is behind `app_data`. The log is capped at [`DIAGNOSTIC_LOG_CAP`] rows, so this is a
-    /// bounded copy of a list nothing reads at frame rate.
+    /// Every retained row, oldest first, cloned out of the model.
     pub fn diagnostics(&self) -> Vec<Diagnostic> {
         self.model_ref().diagnostics.rows().cloned().collect()
     }
 
-    /// `(retained rows, distinct failures ever recorded)`. The two differ once the cap has evicted.
+    /// `(retained rows, distinct failures ever recorded)`.
     pub fn diagnostic_counts(&self) -> (usize, u64) {
         let m = self.model_ref();
         (m.diagnostics.len(), m.diagnostics.total())
     }
 
-    /// Forget the retained rows (the player's "I've read these"). See [`DiagnosticLog::clear`] for
-    /// why the numbering is deliberately *not* reset.
+    /// Forget the retained rows; the numbering carries on.
     pub fn clear_diagnostics(&self) {
         self.model_mut().diagnostics.clear();
     }
 
-    /// Record an addon that **did not load** for a reason that never raised — a manifest entry the
-    /// package does not ship, a document that will not parse, a dependency cycle, a hard
-    /// dependency that is missing, a broken `Bindings.xml`.
-    ///
-    /// **Deliberately does not dispatch.** These are not Lua errors: nothing raised, there is no
-    /// traceback, and handing them to `geterrorhandler()` would put non-errors through
-    /// `_ERRORMESSAGE` and through every addon handler that ever replaces it — a divergence from
-    /// the reference for no gain, since the reference's own answer to an unparseable document is a
-    /// line in `FrameXML.log` and silence on screen. What 1495 changes is that the silence is no
-    /// longer *total*: the failure is retained and readable, it just does not seize the screen.
-    ///
-    /// The caller still logs its own line; this is the retention half, not a replacement for it.
+    /// Retain an addon load failure that never raised (a missing file, an unparseable document, a
+    /// dependency cycle or missing dependency, a broken `Bindings.xml`). It is not dispatched to
+    /// `geterrorhandler()`: the reference logs such a failure and shows nothing. The caller still
+    /// writes its own log line.
     pub fn report_load_failure(&self, msg: &str) {
         record_load_failure(&self.lua, msg);
     }
 
-    /// Retain one non-fatal warning the HOST caught and has already logged — a loader warning off
-    /// an addon's XML, carrying the `<Addon>/<file>` prefix only the caller knows (decision 2135).
-    ///
-    /// The retention half alone, exactly like [`Self::report_script_error`]: the caller writes its
-    /// own `warn!` line, and putting the message on [`Model::warnings`] as well would double it at
-    /// the app's next per-frame drain. For a warning the ENGINE raises, the door is
-    /// [`Model::record_warning`], which owns both halves.
+    /// Retain a warning the host has already logged (a loader warning with its `<Addon>/<file>`
+    /// prefix). Queuing it on `Model::warnings` too would log it twice; an engine-raised warning
+    /// goes through `Model::record_warning`, which does both.
     pub fn report_warning(&self, msg: &str) {
         record_warning(&self.lua, msg);
     }
 }
 
-/// **THE rule for "an addon file did not load"** — one implementation, both loaders (decision
-/// 2107).
-///
-/// The startup walk reaches it through [`super::UiScript::report_load_failure`]; `LoadAddOn`'s
-/// demand load reaches it directly, because it runs inside a Lua binding and holds only `&Lua`
-/// (1191 §4). That was the whole defect 2107 fixes: the two paths had **two copies** of the rule
-/// and the demand-load copy classified a missing manifest entry as a script error, so an addon the
-/// reference loads (logging `Couldn't open %s` and continuing) came back as a session failure here.
-///
-/// The reference's own shape: a failed open is **non-fatal** — `0x6edaa0` logs
-/// `"Couldn't open %s"` (`0x846ff4`) to the log sink at severity 2 and returns null; every failure
-/// leg "reports through the sink and returns normally, with no throw, no `longjmp` and no abort",
-/// and the enclosing `.toc`/document keeps loading. Nothing on that path reaches the Lua error
-/// handler, which is why this never dispatches (1495) and why 1450 made it a WARN: a broken
-/// package is the *package's* defect, and ERROR means "the client is broken".
+/// Retain an addon file that did not load: the one rule for the startup walk and for `LoadAddOn`,
+/// which holds only `&Lua`. The reference's failed open is non-fatal: `0x6edaa0` logs
+/// `Couldn't open %s` (`0x846ff4`) at severity 2 and loading goes on, never reaching the Lua
+/// error handler.
 pub(crate) fn record_load_failure(lua: &Lua, msg: &str) {
     lua.app_data_mut::<Model>()
         .expect("model app_data set")
@@ -256,13 +150,8 @@ pub(crate) fn record_load_failure(lua: &Lua, msg: &str) {
         .record(DiagnosticKind::Load, msg);
 }
 
-/// **THE rule for "something was accepted and did not do what it said"** — the retention half of
-/// the warning channel, for a caller that holds `&Lua` (decision 2135).
-///
-/// Its `&UiScript` face is [`super::UiScript::report_warning`] and its engine-internal sibling is
-/// [`Model::record_warning`]; the difference is only which of the two channels the caller still
-/// owes. A host caller has already written its own log line and wants retention only; an engine
-/// caller wants both.
+/// Retain a warning its caller, holding `&Lua`, has already logged; `Model::record_warning` also
+/// queues it for the host log.
 pub(crate) fn record_warning(lua: &Lua, msg: &str) {
     lua.app_data_mut::<Model>()
         .expect("model app_data set")
@@ -270,14 +159,10 @@ pub(crate) fn record_warning(lua: &Lua, msg: &str) {
         .record(DiagnosticKind::Warning, msg);
 }
 
-/// Register the error-log reads the `BenillaScriptLogFrame` polls.
-///
-/// **`Benilla`-prefixed because they are ours**, not 1.12's — the prefix rule as
-/// `tests::reference_surface` enforces it (1254: a name we invent must not collide, a name the
-/// reference owns must not be hidden). 1.12 has no error-log API to shadow, so there is nothing
-/// here an addon could have meant by a bare name.
+/// Register the error-log reads `BenillaScriptLogFrame` polls, `Benilla`-prefixed as they are not
+/// 1.12 API (`tests::reference_surface` enforces the prefix).
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
-    // BenillaGetNumScriptErrors() -> retained, totalEverRecorded
+    // BenillaGetNumScriptErrors() → retained, totalEverRecorded
     lua.globals().set(
         "BenillaGetNumScriptErrors",
         lua.create_function(|lua, ()| {
@@ -285,9 +170,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok((model.diagnostics.len(), model.diagnostics.total()))
         })?,
     )?;
-    // BenillaGetScriptErrorInfo(index) -> seq, kind, message, count   (1-based, oldest first;
-    // nil for an out-of-range index, so a stale row index during a repaint reads as "gone"
-    // rather than erroring inside the very frame that lists errors.)
+    // BenillaGetScriptErrorInfo(index) → seq, kind, message, count; 1-based, oldest first, and
+    // nothing for an out-of-range index, so a row gone mid-repaint reads as gone.
     lua.globals().set(
         "BenillaGetScriptErrorInfo",
         lua.create_function(|lua, index: i64| {
@@ -307,7 +191,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             ]))
         })?,
     )?;
-    // BenillaClearScriptErrors()
     lua.globals().set(
         "BenillaClearScriptErrors",
         lua.create_function(|lua, ()| {
@@ -339,9 +222,6 @@ mod tests {
 
     #[test]
     fn a_warning_reaches_the_retained_log_and_the_host_drain() {
-        // 2135's whole subject. Before it, a warning existed for exactly as long as one terminal
-        // line: `take_warnings` drained it and nothing kept a copy, so neither the player's
-        // `/errors` window nor the addon survey could see one.
         let mut s = crate::script::UiScript::new().expect("vm");
         s.run(r#"SetCVar("thisCVarDoesNotExist", "1")"#).unwrap();
 
@@ -357,7 +237,6 @@ mod tests {
             .unwrap_or_else(|| panic!("…and it is RETAINED: {kept:#?}"));
         assert_eq!(row.kind, DiagnosticKind::Warning, "under its own kind");
 
-        // The drain is a drain; the log is a memory. A second frame does not lose the row.
         assert!(s.take_warnings().is_empty());
         assert!(s
             .diagnostics()
@@ -367,10 +246,8 @@ mod tests {
 
     #[test]
     fn a_text_sink_takes_bytes_rather_than_raising_on_them() {
-        // Decision 2138, and 1193's rule finally applied at the boundary 1193 named. `strsub` is
-        // byte-indexed by design, so a slice through a multi-byte character is a string an addon
-        // really does hand to `SetText` — and mlua's `String` conversion raised on it, killing the
-        // handler. A stray byte costs a glyph.
+        // `strsub` is byte-indexed, so an addon can hand `SetText` half a UTF-8 character; that
+        // costs a glyph, never a raise.
         let s = crate::script::UiScript::new().expect("vm");
         s.run(
             r#"
diff --git a/crates/benilla-ui/src/script/dialog_verbs.rs b/crates/benilla-ui/src/script/dialog_verbs.rs
index 199f27ba..c5f5d40d 100644
--- a/crates/benilla-ui/src/script/dialog_verbs.rs
+++ b/crates/benilla-ui/src/script/dialog_verbs.rs
@@ -1,31 +1,13 @@
-//! The dialog engine's own verbs (decision 1963) — the bindings the stock `StaticPopup.lua`
-//! bodies call that no window of ours had ever needed, each built to the reference's own shape
-//! (VERIFIED at the bytes unless a line here says INFERRED):
-//!
-//! | binding | args → returns | here |
-//! |---|---|---|
-//! | `GetInstanceBootTimeRemaining()` | 0 → 1 number, whole seconds, 0 idle | reads the app's deadline |
-//! | `AcceptAreaSpiritHeal()` | 0 → 0 | queues the cached healer for the app to send `0x2E3`; SILENT with none cached |
-//! | `CancelAreaSpiritHeal()` | 0 → 0 | the generic cancel-aura of spell 2584 plus `AREA_SPIRIT_HEALER_OUT_OF_RANGE` |
-//! | `GetAreaSpiritHealerTime()` | 0 → 1 number, whole seconds | reads the app's deadline |
-//! | `AcceptBattlefieldPort(index, accept)` | 2 → 0 | raises on a non-number index, silent off 1..3; the optional-bool answer |
-//! | `CancelMeetingStoneRequest()` | 0 → 0 | queued; the app applies the leadership gate |
-//! | `IsInMeetingStoneQueue()` | 0 → the number `1` or `nil`, one value always | `[0xb72038] != 0` (1974) |
-//! | `GetMeetingStoneStatusText()` | 0 → string or `nil` | the cached text `[0xb7203c]`, `nil` while empty |
-//! | `CheckPetUntrainerDist()` | 0 → `1` or `nil` | the app's latch-and-range flag |
-//! | `ConfirmPetUnlearn()` | 0 → 0 | counted; the app holds the latch and the money gate |
-//!
-//! The pet pair is the talent-wipe pair's twin (`talent.rs`), latch for latch. `ForceLogout` is
-//! `session.rs`'s. `ReplaceTradeEnchant` is not here: it rides the trade-slot enchant targeting
-//! this engine does not build yet, and stays a named gap.
+//! The verbs the stock `StaticPopup.lua` dialogs call: the instance-boot and area spirit healer
+//! clocks, the battlefield port answer, the meeting stone pair and the pet untrain pair.
 
 use mlua::{Lua, Value};
 
 use super::binding_abi::{bool_or_default, coerced_number, flag};
 use super::Model;
 
-/// The area spirit healer's aura, `0xA18` — the one spell id `CancelAreaSpiritHeal` cancels, and
-/// the only cancel-aura argument that also fires `AREA_SPIRIT_HEALER_OUT_OF_RANGE` (`0x6e70b6`).
+/// The area spirit healer's aura (`0xA18`), the only cancel-aura spell that also fires
+/// `AREA_SPIRIT_HEALER_OUT_OF_RANGE` (`0x6e70b6`).
 pub const AREA_SPIRIT_HEALER_SPELL: u32 = 2584;
 
 impl super::UiScript {
@@ -51,7 +33,7 @@ impl super::UiScript {
         model.area_spirit_secs = secs;
     }
 
-    /// `AcceptAreaSpiritHeal()` calls since the last drain (each one a `0x2E3` to send).
+    /// `AcceptAreaSpiritHeal()` calls since the last drain, each a `0x2E3` to send.
     pub fn take_area_spirit_accepts(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().area_spirit_accepts)
     }
@@ -66,9 +48,8 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().meeting_stone_cancels)
     }
 
-    /// The meeting stone's two globals (1974): the queued area id (`[0xb72038]`, `0` = none) and
-    /// the cached status text (`[0xb7203c]`, `None` from process start to world enter and after
-    /// world leave). The app rebuilds the text; the VM only hands it back.
+    /// The meeting stone's two globals: the queued area id (`0xb72038`, 0 for none) and the
+    /// cached status text (`0xb7203c`, `None` outside the world), which the app rebuilds.
     pub fn set_meeting_stone(&mut self, area: u32, status_text: Option<String>) {
         let mut model = self.model_mut();
         model.meeting_stone_area = area;
@@ -79,8 +60,7 @@ impl super::UiScript {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // 0 args → 1 number: `max(deadline − now, 0) / 1000`, truncated (`GetInstanceBootTimeRemaining
-    // 0x48b620`).
+    // `0x48b620`: `max(deadline - now, 0) / 1000`, truncated.
     g.set(
         "GetInstanceBootTimeRemaining",
         lua.create_function(|lua, ()| {
@@ -89,8 +69,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `AcceptAreaSpiritHeal 0x48df20`: `if (cached healer == 0:0) return;` — SILENT — else `0x2E3`
-    // + the cached guid.
+    // `0x48df20`: silent with no healer cached, else `0x2E3` with the cached guid.
     g.set(
         "AcceptAreaSpiritHeal",
         lua.create_function(|lua, ()| {
@@ -101,11 +80,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // `CancelAreaSpiritHeal 0x48df30`: `0x6e7040(0xA18)` — the generic cancel-aura routine: the
-    // event fires (only for this spell), then `0x136` + `u32 2584`, no guid. The routine's refusal
-    // — AttributesEx bit 13 set, bit 2 clear, and `0x5ee290(player)` — never reaches its third leg
-    // for spell 2584: the shipped Spell.dbc fails the first two, checked against the data by the
-    // app's `spell_2584_never_trips_the_cancel_gate`. So the send is unconditional here.
+    // `0x48df30` runs the generic cancel-aura (`0x6e7040`): the event, then `0x136` with
+    // `u32 2584`, no guid. Its refusal gate (`AttributesEx` bit 13 set, bit 2 clear, then
+    // `0x5ee290`) never trips for 2584 in the shipped `Spell.dbc` (the app's
+    // `spell_2584_never_trips_the_cancel_gate`), so the send is unconditional.
     g.set(
         "CancelAreaSpiritHeal",
         lua.create_function(|lua, ()| {
@@ -117,7 +95,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // 0 → 1 number, whole seconds: `max(0, [0xb4e338] − now) / 1000`.
+    // Whole seconds: `max(0, [0xb4e338] - now) / 1000`.
     g.set(
         "GetAreaSpiritHealerTime",
         lua.create_function(|lua, ()| {
@@ -126,9 +104,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `AcceptBattlefieldPort 0x4ab3b0`: arg 1 must satisfy `lua_isnumber` (a number or a numeric
-    // string) or the binding RAISES `Usage:`; truncated, 1-based, off 1..=3 SILENT. Arg 2 is the
-    // reference's optional-boolean coercion (`0x6f1c10`, default 0), normalised to one byte.
+    // `0x4ab3b0`: an index failing `lua_isnumber` raises, one off 1..=3 is silent; the answer takes
+    // the reference's optional-boolean coercion (`0x6f1c10`, default no).
     g.set(
         "AcceptBattlefieldPort",
         lua.create_function(|lua, (index, accept): (Value, Value)| {
@@ -156,8 +133,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `CancelMeetingStoneRequest 0x4ca5a0`: `0x293`, empty; gated only on party leadership (the
-    // app's, which holds the party) — it clears nothing, the server's reply does.
+    // `0x4ca5a0`: an empty `0x293` gated on party leadership (the app's); only the reply clears.
     g.set(
         "CancelMeetingStoneRequest",
         lua.create_function(|lua, ()| {
@@ -167,9 +143,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `IsInMeetingStoneQueue()` (`0x4ca570`): `mov eax,1` on BOTH legs — the number `1` when the
-    // queued area is non-zero, else nil; never `0` (truthy in Lua — it would pin the icon shown),
-    // never a boolean.
+    // `0x4ca570`: the number `1` or nil, never `0` (truthy, it would pin the icon) or a boolean.
     g.set(
         "IsInMeetingStoneQueue",
         lua.create_function(|lua, ()| {
@@ -178,8 +152,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetMeetingStoneStatusText()` (`0x4ca5b0`): `lua_pushstring([0xb7203c])`, whose NULL leg
-    // tail-jumps to `lua_pushnil` — a string or nil, one value, never `""` for "nothing".
+    // `0x4ca5b0`: a string or nil, never `""` for nothing.
     g.set(
         "GetMeetingStoneStatusText",
         lua.create_function(|lua, ()| {
@@ -191,8 +164,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `CheckPetUntrainerDist 0x48d1c0`: `1` or `nil` — never `0`. The range test
-    // (`d² <= INTERACT_DISTANCE²`, a NaN OUT) is the app's, on the latched trainer.
+    // `0x48d1c0`: `1` or nil, never `0`; the app tests the range to the latched trainer.
     g.set(
         "CheckPetUntrainerDist",
         lua.create_function(|lua, ()| {
@@ -200,8 +172,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(flag(model.pet_untrainer_pending))
         })?,
     )?;
-    // `ConfirmPetUnlearn 0x48dca0`: the confirm arm — the latch's guid, the money gate
-    // (`ERR_NOT_ENOUGH_MONEY`, no packet) and `0x2F0`, all the app's; here the call is counted.
+    // `0x48dca0`: the app holds the latch and the money gate, and sends `0x2F0`.
     g.set(
         "ConfirmPetUnlearn",
         lua.create_function(|lua, ()| {
@@ -300,7 +271,6 @@ mod tests {
         );
     }
 
-    /// The meeting stone pair: `1`/nil on the area, string/nil on the text — one value each.
     #[test]
     fn the_meeting_stone_pair_answers_one_or_nil_and_string_or_nil() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/dressup.rs b/crates/benilla-ui/src/script/dressup.rs
index aa24faf8..2e787af6 100644
--- a/crates/benilla-ui/src/script/dressup.rs
+++ b/crates/benilla-ui/src/script/dressup.rs
@@ -1,31 +1,8 @@
-//! The **dressing room** surface (decisions 1060, 1969) — the `DressUpModel` widget's own three
-//! verbs (table `0x84f190`: `Undress 0x504c00` · `Dress 0x504cd0` · `TryOn 0x504d90`) and the
-//! ordered intent queue behind them and behind `PlayerModel`'s `SetUnit`/`RefreshUnit` when the
-//! pane is a dressing room.
-//!
-//! ## Why a queue, and why the state is the app's
-//!
-//! In the client the widget clones the unit's live model on `SetUnit`/`Dress` (`0x5059a0`, the
-//! attachment tree deep-copied) and `TryOn` overwrites one bodyslot or one of two hand lanes of
-//! that clone (`0x504350`). benilla renders no FrameXML model:
-//! every model pane is a booth bake the app composes from a look — the player's own visible items
-//! with the tried-on ones substituted in — and the VM holds neither item templates nor the
-//! player's equipment. So the verbs record *intents*, in order, and the app applies them
-//! (`take_dressup_intents`): `DressUpItem` resets *then* tries on in one breath when the window
-//! was closed (ref `DressUpFrame.lua:3-7`), and applying those two out of order would show the
-//! player's own gear instead of the item they clicked.
-//!
-//! ## What each verb means, off the bytes
-//!
-//! - `SetUnit(unit)` / `RefreshUnit()` / `Dress()` all funnel into the same rebuild-from-the-unit
-//!   worker (`0x505b50`): every substitution is gone and the model is what the player shows in
-//!   the world. One intent, [`DressUpIntent::Dress`].
-//! - `Undress()` → `0x504490`: clears components bodyslots `0..0xb` — every worn piece, base and
-//!   tried-on alike — and touches no hand lane, so a held weapon stays. [`DressUpIntent::Undress`].
-//! - `TryOn(item)`: the argument is `trunc(tonumber(arg))` (`__ftol 0x40a2b0`) handed to the item
-//!   cache, so a numeric string is an id and anything else is item 0, which previews nothing. The
-//!   stock `DressUpItemLink` hands it the digits it `gsub`bed out of the `|Hitem:` link. It gates
-//!   on nothing — no class, level or proficiency check anywhere in the path (`DressUpFrame.lua:2-16`).
+//! The dressing room: the `DressUpModel` verbs (table `0x84f190`) and the intent queue behind them
+//! and behind `SetUnit`/`RefreshUnit` on a dressing-room pane. The reference edits a clone of the
+//! unit's model (`0x5059a0`, `0x504350`); here the app composes the look from the intents in
+//! order, which matters: on a closed window `DressUpItem` resets, then tries on
+//! (`DressUpFrame.lua:3-7`).
 
 use mlua::{Lua, Table, Value};
 
@@ -33,32 +10,28 @@ use super::object::frame_handle_of;
 use super::Model;
 use crate::widget::FrameKind;
 
-/// Registry key of the `DressUpModel` method table — its **own three** entries. `PlayerModel`'s
-/// three and `Model`'s 23 come through the dispatcher's chain (`object.rs`).
+/// Registry key of the `DressUpModel` method table, its own three; the rest come by the chain.
 pub(super) const REG_DRESSUPMODEL_METHODS: &str = "__benilla_dressupmodel_methods";
 
-/// One queued dressing-room intent (see the module doc on ordering).
+/// One queued dressing-room intent, applied in order.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum DressUpIntent {
-    /// `DressUpModel:SetUnit("player")` (the open), `RefreshUnit()` and `Dress()` (the Reset
-    /// button) — "wear what the player is actually wearing", dropping every substitution.
+    /// `SetUnit`, `RefreshUnit` and `Dress` (the Reset button): the reference's rebuild from the
+    /// unit (`0x505b50`), dropping every substitution.
     Dress,
-    /// `DressUpModel:Undress()` — every worn piece off, base and tried-on; the hands keep what
-    /// they hold.
+    /// `Undress()`: bodyslots `0..0xb` cleared, worn and tried-on alike; the hands keep what they
+    /// hold (`0x504490`).
     Undress,
-    /// `DressUpModel:TryOn(item)` — substitute this item id into whichever slot its
-    /// `InventoryType` belongs to.
+    /// `TryOn(item)`: the item in its `InventoryType`'s slot, with no class, level or proficiency
+    /// check (`DressUpFrame.lua:2-16`).
     TryOn(u32),
-    /// The window was hidden — the app's own intent, derived from the frame going invisible
-    /// (`UiScript::frame_visible`): there is nothing to show, so the booth empties (and stops
-    /// rendering). The reference's widget keeps its state while hidden, but its next `DressUpItem`
-    /// re-issues `SetUnit("player")` precisely *because* the frame was not visible, so the state it
-    /// kept is never observable — dropping it is behaviour-identical and saves the bake.
+    /// The window was hidden, so the booth empties. The reference keeps its state while hidden,
+    /// but the next `DressUpItem` re-issues `SetUnit("player")`, so that state is never seen.
     Close,
 }
 
 impl super::UiScript {
-    /// Drain the dressing room's queued intents, oldest first — the app applies them in order.
+    /// Drain the dressing room's intents, oldest first; the app applies them in order.
     pub fn take_dressup_intents(&mut self) -> Vec<DressUpIntent> {
         std::mem::take(&mut self.model_mut().dressup_intents)
     }
@@ -71,8 +44,7 @@ fn queue(lua: &Lua, intent: DressUpIntent) {
         .push(intent);
 }
 
-/// `PlayerModel`'s `SetUnit`/`RefreshUnit` on a pane that is a `DressUpModel`: the rebuild that
-/// drops every substitution (the module doc). A no-op on any other pane.
+/// Queue the rebuild when `PlayerModel`'s `SetUnit`/`RefreshUnit` lands on a `DressUpModel`.
 pub(super) fn redress_if_dressup(lua: &Lua, this: &Table) -> mlua::Result<()> {
     let h = frame_handle_of(lua, this)?;
     let is_dressup = lua
@@ -87,8 +59,8 @@ pub(super) fn redress_if_dressup(lua: &Lua, this: &Table) -> mlua::Result<()> {
     Ok(())
 }
 
-/// `trunc(tonumber(arg))` — `__ftol 0x40a2b0` over `lua_tonumber`: a number or numeric string
-/// truncates toward zero; anything else is 0.
+/// `trunc(tonumber(arg))`, the reference's `__ftol` (`0x40a2b0`) over `lua_tonumber`; anything
+/// else is 0.
 fn item_arg(v: &Value) -> i64 {
     match v {
         Value::Integer(i) => *i,
@@ -105,7 +77,7 @@ fn item_arg(v: &Value) -> i64 {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let m = lua.create_table()?;
 
-    // `Undress()` — `0x84f190` -> `0x504c00` -> `0x504490`.
+    // `0x504c00`.
     m.set(
         "Undress",
         lua.create_function(|lua, this: Table| {
@@ -115,7 +87,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `Dress()` — `0x504cd0`, the Reset button (`DressUpFrame.xml:182`).
+    // `0x504cd0`, the Reset button (`DressUpFrame.xml:182`).
     m.set(
         "Dress",
         lua.create_function(|lua, this: Table| {
@@ -125,8 +97,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `TryOn(item)` — `0x504d90` -> `0x504540(itemId)`. Item 0 (a non-number, a link string) looks
-    // up nothing in the client's cache and previews nothing; so does a negative one here.
+    // `0x504d90` calls `0x504540(itemId)`; item 0 (a non-number or a link) previews nothing, and
+    // so does a negative id here.
     m.set(
         "TryOn",
         lua.create_function(|lua, (this, item): (Table, Value)| {
@@ -156,8 +128,6 @@ mod tests {
         s
     }
 
-    /// The widget answers its own three, PlayerModel's three and Model's, in a chain five deep —
-    /// and a plain PlayerModel does not answer the three (the chain runs derived → base only).
     #[test]
     fn a_dress_up_model_is_a_player_model_plus_three_and_the_chain_runs_one_way() {
         let s = room();
@@ -200,9 +170,7 @@ mod tests {
         }
     }
 
-    /// The verbs queue intents in call order; `SetUnit`/`RefreshUnit` re-dress on THIS kind only;
-    /// `TryOn`'s argument is `trunc(tonumber(arg))`, so the stock file's digit string is an id and
-    /// a link string is item 0, which queues nothing.
+    /// The stock `DressUpItemLink` passes the link's digits: a digit string is an id, a link is 0.
     #[test]
     fn the_verbs_queue_intents_in_order_and_try_on_reads_its_argument_like_the_client() {
         let mut s = room();
diff --git a/crates/benilla-ui/src/script/duel.rs b/crates/benilla-ui/src/script/duel.rs
index 47183195..ecfb02c0 100644
--- a/crates/benilla-ui/src/script/duel.rs
+++ b/crates/benilla-ui/src/script/duel.rs
@@ -1,37 +1,26 @@
-//! The duel **Era API surface** (decision 0633) — four globals, no state.
-//!
-//! Duels are the smallest possible shape of the [`super::party`] seam: everything the UI needs to
-//! *read* arrives as event arguments (the challenger's name on `DUEL_REQUESTED`), so there is no
-//! snapshot to push — only the outbound half. Each call queues a [`DuelRequest`] the app drains
-//! ([`UiScript::take_duel_requests`]) and turns into its send, keeping the engine free of ECS/net
-//! reach (decision 0068 §3).
-//!
-//! The four are exactly the reference's own duel bindings, registered adjacent in its Lua API
-//! table (`0x849fc8`..`0x849ff0`) and each a one-liner over the same TU: `AcceptDuel` `0x4d4ce0`
-//! → `0x4d4830`, `CancelDuel` `0x4d4cf0` → `0x4d48b0`, `StartDuelUnit` `0x4d4c40` (unit token →
-//! guid, gated on typemask `0x10` = player), `StartDuel` `0x4d4c90` (name → guid). The two
-//! `StartDuel*` calls do **not** send a duel opcode — they cast the duel spell at the guid; the
-//! app owns that resolution.
+//! The four duel globals, registered together at `0x849fa8`. What the UI reads arrives as event
+//! arguments, so each call only queues a [`DuelRequest`] for the app to send. `AcceptDuel`
+//! (`0x4d4ce0`) and `CancelDuel` (`0x4d4cf0`) call `0x4d4830` and `0x4d48b0`; `StartDuel`
+//! (`0x4d4c40`) and `StartDuelUnit` (`0x4d4c90`) send no duel opcode but cast the duel spell at
+//! the guid they resolve (`0x4d4810`).
 
 use mlua::Lua;
 
 use super::Model;
 
-/// Outbound duel intents queued by the Era API calls, drained by the app
-/// ([`UiScript::take_duel_requests`]). Plain data — [`super::party::PartyRequest`]'s twin.
+/// A duel intent queued by the globals, drained by `UiScript::take_duel_requests`.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum DuelRequest {
-    /// `AcceptDuel()` — accept the pending challenge (`CMSG_DUEL_ACCEPTED`).
+    /// `AcceptDuel()`, the `DUEL_REQUESTED` popup's Accept: `CMSG_DUEL_ACCEPTED`.
     Accept,
-    /// `CancelDuel()` — decline, cancel, or forfeit (`CMSG_DUEL_CANCELLED`); which one it means
-    /// is the server's read of the duel state, not ours.
+    /// `CancelDuel()`: `CMSG_DUEL_CANCELLED`, which the server reads by duel state as a decline,
+    /// a cancel or a forfeit.
     Cancel,
-    /// `StartDuel(name)` — challenge a player found by name. The app resolves the name to a guid
-    /// and casts the duel spell at it; an unresolvable name is dropped (the reference errors the
-    /// Lua call instead — the deviation is noted in the app-side drain).
+    /// `StartDuel(name)`: the reference resolves the name through `0x493aa0`, players only, and
+    /// does nothing on a miss.
     StartByName(String),
-    /// `StartDuelUnit(unit)` — challenge whoever a unit token points at. The app resolves the
-    /// token to a guid and rejects a non-player (the reference's typemask `0x10` gate).
+    /// `StartDuelUnit(unit)`, the unit popup's Duel row. The app casts only at a player; the
+    /// reference resolves the token (`0x515970`) with no player gate of its own.
     StartByUnit(String),
 }
 
@@ -41,20 +30,17 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().duel_requests)
     }
 
-    /// Queue an intent from the app side — the slash commands. In the reference these ARE Lua
-    /// (`SlashCmdList["DUEL"]` calls `StartDuel`, `SlashCmdList["DUEL_CANCEL"]` calls
-    /// `CancelDuel`); benilla parses slash lines in Rust, so the same intents enter the same
-    /// queue here rather than through the globals.
+    /// Queue an intent from the app's Rust slash parser: `/duel` and `/forfeit`, which the
+    /// reference's `SlashCmdList` handlers send through `StartDuel` and `CancelDuel`.
     pub fn queue_duel_request(&mut self, request: DuelRequest) {
         self.model_mut().duel_requests.push(request);
     }
 }
 
-/// Register the duel globals (the same style/place [`super::party`] registers its actions).
+/// Register the duel globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // AcceptDuel() — the DUEL_REQUESTED popup's Accept.
     g.set(
         "AcceptDuel",
         lua.create_function(|lua, ()| {
@@ -64,7 +50,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CancelDuel() — the popup's Decline, and /forfeit //concede //yield once under way.
+    // `CancelDuel()`: the popup's Decline, and `/forfeit` (`/concede`, `/yield`) once under way.
     g.set(
         "CancelDuel",
         lua.create_function(|lua, ()| {
@@ -74,7 +60,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // StartDuel(name) — /duel <name>.
     g.set(
         "StartDuel",
         lua.create_function(|lua, name: String| {
@@ -84,7 +69,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // StartDuelUnit(unit) — the unit popup's Duel row.
     g.set(
         "StartDuelUnit",
         lua.create_function(|lua, unit: String| {
diff --git a/crates/benilla-ui/src/script/editbox.rs b/crates/benilla-ui/src/script/editbox.rs
index 30cf6c43..857e136d 100644
--- a/crates/benilla-ui/src/script/editbox.rs
+++ b/crates/benilla-ui/src/script/editbox.rs
@@ -1,50 +1,22 @@
-//! The `EditBox` runtime — keyboard focus, the text buffer + cursor + selection, editing, and the
-//! key/char dispatch (`CSimpleEditBox`, factory `0x6eec70`).
+//! The `EditBox` runtime (`CSimpleEditBox`, factory `0x6eec70`): keyboard focus, the text buffer,
+//! cursor and selection, editing, and key and char dispatch.
 //!
-//! Byte-verified against the reference client:
+//! - Focus: one owner ([`Model::focused_editbox`], the client's `DAT_00cf4dc8`). A left click
+//!   focuses and collapses the selection to the clicked byte (`0x77b86f call 0x77ccf0`, before
+//!   `SetFocus` at `0x77b881`), so it never selects all. An `autoFocus` box takes the focus on show
+//!   when none is held and on the first key, and a hidden box drops it ([`visibility_focus`]).
+//! - Routing: a focused box consumes every key and char and fires only its specialized scripts
+//!   (Enter, Escape, Space, Tab, TextChanged, TextSet, focus), never a generic `OnKeyDown`; an
+//!   unfocused box that is not `autoFocus` ignores input.
+//! - Editing: an insert replaces the selection; `numeric` aborts a whole insert on any non-digit;
+//!   caps trim from the end (`maxBytes`, then `maxLetters`).
 //!
-//! - **Focus:** a single class-owned focus owner ([`Model::focused_editbox`], the client's
-//!   `DAT_00cf4dc8`). `SetFocus` gates on effective-visibility, is a no-op if already focused, and
-//!   fires `OnEditFocusLost` on the old box then `OnEditFocusGained` on the new. A LeftButton click
-//!   focuses UNCONDITIONALLY — and **collapses the selection to the clicked byte index** on its way
-//!   (`0x77b86f call 0x77ccf0`, immediately before `0x77b881 SetFocus`), so a fresh click-focus leaves
-//!   an EMPTY selection at the click point, never a select-all. `SetFocus` itself writes no selection
-//!   field, and `0x77e3f6` is the only instruction image-wide that gives a box focus — so *every*
-//!   focus gain, whatever triggers it, is selection-neutral.
+//! Mouse, selection and caret (click to index `0x77d0d0`, drag `0x77a860`) live in [`interact`]
+//! and [`seam`]; the OS clipboard is host-side, [`paste`] in and `UiScript::editbox_copy` or
+//! `editbox_cut` out. The host's per-OS keymap sends editing keys as [`EditAction`]s ([`action`]).
 //!
-//!   **`autoFocus` DOES focus on show** (corrected 2026-08-29, `0x81c910` slot +0x30 `0x77a750`):
-//!   the OnShow override tail-jumps `SetFocus` when nothing else holds focus, and the OnHide
-//!   mirror tail-jumps `ClearFocus`. The old "verified by absence" negative came from a `call`-only
-//!   census that could not see a tail-`jmp`. Both overrides are [`visibility_focus`] here, and the
-//!   construction default is `true` off the bytes (see
-//!   [`EditBoxState::auto_focus`](crate::widget::EditBoxState::auto_focus)). The
-//!   self-acquire-on-first-key half stands beside it.
-//! - **Routing:** a focused box processes and CONSUMES every key/char (`return 1` past the
-//!   guard); an unfocused non-autoFocus box ignores input. The override fires ONLY the specialized
-//!   scripts (Enter/Escape/Space/Tab/TextChanged/TextSet/focus), never generic `OnKeyDown`/`OnChar`.
-//! - **Text/editing:** every insert replaces the selection first; `numeric` aborts an insert
-//!   wholesale on any non-digit; caps trim from the end (`maxBytes` then `maxLetters`); `SetText`
-//!   short-circuits when unchanged; `HighlightText(0,-1)` selects all with the client's clamp.
-//!
-//! The mouse/selection/caret half (click→index `0x77d0d0`, drag `0x77a860`, the clipboard pair,
-//! the 0.5 s blink, the char-granular scroll window) lives in [`interact`]/[`seam`] over the
-//! host-answered advance table — decision 0298. The OS clipboard itself stays host-side (this
-//! crate is engine-free): paste text arrives via [`paste`], copy/cut strings return through
-//! `UiScript::editbox_copy`/`editbox_cut`; Ctrl+A arrives as the SOH control char.
-//!
-//! Editing keys reach the box as semantic [`EditAction`]s ([`action`]) — the *host's* per-OS
-//! keymap decides which physical chord means which action (decision 0301), while the effect of
-//! each action stays this module's byte-verified law. [`key_input`] keeps only the three
-//! box-event keys (ENTER/ESCAPE/TAB).
-//!
-//! ## Stated divergences / gaps
-//! - **`OnCursorChanged`** (the 4-float caret-pos fire) is not fired — no shipped XML consumes it.
-//! - Small INFERRED corners (click rounding, word classes, no shift+click, the password-copy
-//!   placeholder literal) are flagged where they live — decision 0298's list.
-//! - **Word/edge deletes** (`Delete{Word,Edge}`) have no 1.12 counterpart at all — they exist for
-//!   the host's OS-native keymaps (Option/Cmd+Backspace on macOS, Ctrl+Backspace/Delete on
-//!   Windows/Linux; decision 0301) and reuse the byte-verified word classes + selection-first
-//!   delete law.
+//! Deviation: word and edge deletes (`Delete{Word,Edge}`), which 1.12 does not have, exist because
+//! the host's OS-native chords (Option/Cmd+Backspace, Ctrl+Backspace/Delete) expect them.
 
 use mlua::{Lua, Table, Value};
 
@@ -59,43 +31,32 @@ use crate::widget::{EditBoxState, FrameHandle, FrameKind, KindState, RegionHandl
 pub(super) const REG_EDITBOX_METHODS: &str = "__benilla_editbox_methods";
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
-// Public entry points (called from UiScript::char_input / key_input / mouse_button)
+// Public entry points
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
-/// A typed character. Routed per the focus/routing rules above; on a focused box, Ctrl+A
-/// (delivered as the SOH control char) selects all, other C0 control chars are consumed-but-inert,
-/// and printable text is inserted. Always consumes when a box is (or becomes) focused.
+/// A typed character: Ctrl+A (arriving as SOH) selects all, other C0 controls are consumed inert,
+/// printable text is inserted.
 pub(super) fn char_input(lua: &Lua, text: &str) -> bool {
     let Some(h) = route(lua) else {
         return false;
     };
     if text == "\u{1}" {
-        // Ctrl+A → select-all (the client's keydown case 0x41/0x61; here via char_input since a
-        // Ctrl-modified letter arrives as its control code).
+        // Ctrl+A selects all (the client's keydown case 0x41/0x61).
         highlight_text(lua, h, 0, -1);
     } else if text.chars().any(|c| (c as u32) >= 0x20) {
-        // A printable char (or string); pure control input is consumed but not inserted.
-        //
-        // A typed `|` goes in as `||` — OnChar `0x77c200` pushes the literal at `0x879cac`, which
-        // is `"||"` (decision 1077). That is why real markup can only enter a box through
-        // `SetText`, `Insert`, a paste or the C++ link-insert path: you cannot type an escape, and
-        // the doubled form draws as one `|` and counts as one letter.
+        // A typed `|` goes in as `||` (`0x77c200` pushes the literal `"||"` at `0x879cac`), so
+        // markup cannot be typed; the pair draws as one `|` and counts as one letter.
         insert(lua, h, &text.replace('|', "||"), true);
     }
     true
 }
 
-/// Paste an OS-clipboard string into the focused box. The engine-free runtime can't reach the OS
-/// clipboard itself, so the host reads it and hands the text here. Sanitized
-/// the same way a typed char is gated — every C0 control char is dropped, except a newline in a
-/// `multiLine` box — then inserted as one edit (selection-replace + numeric/caps rules via [`insert`],
-/// no `OnSpacePressed` fire: a paste is not a typed space). Always consumes when a box is focused.
+/// Paste host clipboard text into the focused box as one edit: C0 controls are dropped, except a
+/// newline in a `multiLine` box, and no `OnSpacePressed` fires.
 pub(super) fn paste(lua: &Lua, text: &str) -> bool {
     let Some(h) = route(lua) else {
         return false;
     };
-    // The sanitation + insert is the shared law ([`EditBoxState::paste`]); only the event fire is
-    // this layer's.
     if with_eb(lua, h, |eb| eb.paste(text)).is_some_and(|o| o.text_changed) {
         sync_text_region(lua, h);
         mark_text_changed(lua, h);
@@ -103,9 +64,7 @@ pub(super) fn paste(lua: &Lua, text: &str) -> bool {
     true
 }
 
-/// A non-character key by name — only the three *box-event* keys act (their FrameXML scripts);
-/// every editing key reaches the box as a semantic [`EditAction`] via [`action`] instead. Follows
-/// the same focus/routing rules; a focused box consumes the key even when it does nothing with it.
+/// A named key: only Enter, Escape and Tab act, and a focused box consumes every key.
 pub(super) fn key_input(lua: &Lua, key: &str) -> bool {
     let Some(h) = route(lua) else {
         return false;
@@ -120,31 +79,25 @@ pub(super) fn key_input(lua: &Lua, key: &str) -> bool {
                 fire_script(lua, id, "OnEnterPressed");
             }
         }
-        // Escape fires the script but does NOT release focus (FrameXML calls ClearFocus itself).
+        // Escape does not release focus: FrameXML calls ClearFocus itself.
         "ESCAPE" => fire_script(lua, id, "OnEscapePressed"),
         "TAB" => fire_script(lua, id, "OnTabPressed"),
-        // Any other named key: a focused box still consumes it (past the guard), doing nothing.
         _ => {}
     }
     true
 }
 
-/// One semantic editing operation — the host's per-OS keymap output (decision 0301). Same
-/// routing/consumption law as [`key_input`]: the focused (or self-acquiring if needed) box
-/// processes it; no box → not consumed.
+/// One semantic editing operation from the host's per-OS keymap, routed like [`key_input`].
 pub(super) fn action(lua: &Lua, a: EditAction) -> bool {
     let Some(h) = route(lua) else {
         return false;
     };
     match a {
         EditAction::Move { unit, back, extend } => match unit {
-            // No alt-arrow test here: the gate is on the KEY and lives in the host, which declines
-            // the four arrow codes before the chord is ever built (`editbox_alt_arrow_mode`).
-            // Anything reaching this arm was Alt-held or was not an arrow, and the reference moves
-            // the caret for both.
+            // The alt-arrow gate lives in the host (`editbox_alt_arrow_mode`), which declines the
+            // arrow codes before a chord is built.
             EditUnit::Char => move_horizontal(lua, h, !back, extend),
-            // Ctrl/Option picks the word-granular cursor helper (the client's Ctrl check,
-            // `0x41f8f0(1)`).
+            // Ctrl (Option on macOS) moves by word (the client's Ctrl check, `0x41f8f0(1)`).
             EditUnit::Word => interact::move_word(lua, h, !back, extend),
             EditUnit::Edge => move_to_edge(lua, h, !back, extend),
         },
@@ -154,15 +107,9 @@ pub(super) fn action(lua: &Lua, a: EditAction) -> bool {
             EditUnit::Edge => delete_span(lua, h, |eb| if back { 0 } else { eb.text.len() }),
         },
         EditAction::SelectAll => highlight_text(lua, h, 0, -1),
-        // History recall (the chat box's `historyLines`): prev = older, next = newer, live draft
-        // restored past the newest. Single-line only (benilla's multiLine box has no vertical
-        // caret nav — survey gap — a multiLine box consumes the step inert). The recall chords
-        // are the host keymap's plain Up/Down (the reference's own history controller is
-        // untraced; decision 0301). The alt-arrow gate DOES cover them, upstream: UP and DOWN are
-        // two of the four codes it declines, so on a flagged box — which the reference's own chat
-        // box is — history recall is **Alt**+Up/Down and a plain Up/Down turns the camera. This
-        // file used to say the opposite ("`ignoreArrows` does not gate them"), which followed
-        // from reading the flag as consume-but-inert; both halves above are now corrected.
+        // History recall (`historyLines`): older, newer, then back to the live draft. A multiLine
+        // box consumes it inert (it has no vertical caret movement). On an alt-arrow box, as the
+        // stock chat box is, recall is Alt+Up/Down; the reference's history controller is untraced.
         EditAction::HistoryPrev | EditAction::HistoryNext => {
             if !with_eb(lua, h, |eb| eb.multi_line).unwrap_or(false) {
                 history_step_key(lua, h, a == EditAction::HistoryPrev);
@@ -172,9 +119,8 @@ pub(super) fn action(lua: &Lua, a: EditAction) -> bool {
     true
 }
 
-// The mouse/selection interaction law (click→index, drag-select, clipboard, blink) — a child
-// module over this file's focus/editing primitives — and the host-facing seam (`impl UiScript`:
-// the advance round trip + text-UI geometry).
+// Mouse, selection, clipboard and blink (`interact`); the host's advance round trip and text
+// geometry (`seam`).
 mod interact;
 mod seam;
 pub(super) use interact::{
@@ -185,14 +131,9 @@ pub(super) use interact::{
 // Focus model
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
-/// Resolve the box that should process this key/char event, self-acquiring if needed.
-///
-/// - A live, effectively-visible focused box → process it.
-/// - A focused box that is hidden (still alive) → `None`: the client's guard returns 0 and the focus
-///   global stays set, so no other box self-acquires while it "holds" focus.
-/// - A focused handle that went stale → cleared, then fall through to self-acquire.
-/// - No focus → the topmost effectively-visible `autoFocus` EditBox self-acquires (firing
-///   `OnEditFocusGained`) and processes this same event; otherwise `None` (not consumed).
+/// The box that processes a key or char. A hidden focused box blocks self-acquire (the client's
+/// guard returns 0 with the focus still set); with no focus, the topmost visible `autoFocus` box
+/// takes it and processes this same event.
 fn route(lua: &Lua) -> Option<FrameHandle> {
     {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -209,8 +150,7 @@ fn route(lua: &Lua) -> Option<FrameHandle> {
     Some(h)
 }
 
-/// The topmost-drawn effectively-visible `autoFocus` EditBox (the keyboard self-acquire target), or
-/// `None`. Walks the draw order top-down like [`crate::order::hit_test`].
+/// The topmost-drawn visible `autoFocus` EditBox, the keyboard self-acquire target.
 fn topmost_autofocus(lua: &Lua) -> Option<FrameHandle> {
     let model = lua.app_data_ref::<Model>().expect("model app_data");
     let sorted = order::traversal(&model.arena);
@@ -226,12 +166,9 @@ fn topmost_autofocus(lua: &Lua) -> Option<FrameHandle> {
     None
 }
 
-/// `SetFocus` (`0x77e3d0`): gate on effective-visibility, no-op if already focused; else fire
-/// `OnEditFocusLost` on the old box, move focus, fire `OnEditFocusGained` on the new.
-///
-/// `0x77e3f6` (inside this) is the ONLY instruction image-wide that grants a box the focus, and it
-/// writes no selection field — so every focus gain in the client, whatever triggers it, is
-/// selection-neutral.
+/// `SetFocus` (`0x77e3d0`): needs effective visibility, a no-op when already focused; fires
+/// `OnEditFocusLost` on the old box, then `OnEditFocusGained`. Its store at `0x77e3f6` is the
+/// client's only focus grant and writes no selection, so no focus gain changes the selection.
 fn set_focus_handle(lua: &Lua, h: FrameHandle) {
     let (old_id, new_id) = {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -244,9 +181,7 @@ fn set_focus_handle(lua: &Lua, h: FrameHandle) {
         }
         let old = model.focused_editbox;
         model.focused_editbox = Some(h);
-        // A fresh focus starts a fresh history session: the browse position must not leak from
-        // the box's previous open (programmatic SetText deliberately preserves it — the chat
-        // live parse's recall rewrite — so this is where a stale walk gets dropped).
+        // A focus gain ends history browsing (`SetText` keeps it for the chat parser's rewrite).
         if let Some(KindState::EditBox(eb)) = model.arena.frame_mut(h).map(|f| &mut f.kind_state) {
             eb.end_history_browse();
         }
@@ -258,21 +193,13 @@ fn set_focus_handle(lua: &Lua, h: FrameHandle) {
     fire_script(lua, new_id, "OnEditFocusGained");
 }
 
-/// The EditBox's own **OnShow/OnHide vtable overrides** (`0x81c910` slots +0x30/+0x34), run by
-/// [`crate::script::event::fire_visibility_changes`] after the frame's Lua handler — the order the
-/// reference has, since both overrides call the base notify *first* and only then act.
-///
-/// - **Show** (`0x77a750`): `if ([0xcf4dc8] == 0 && (flags & 1)) SetFocus(this)` — an `autoFocus`
-///   box grabs the keyboard when it appears, **iff nothing else holds it**. Not a
-///   "topmost/best" choice: whichever box's show runs first while the focus is free takes it.
-/// - **Hide** (`0x77a780`): tail-jumps `ClearFocus`, whose own guard makes it per-box — hiding a
-///   box that does not hold the keyboard writes nothing and fires nothing.
-///
-/// Both were missing until 2026-08-29 (decision 1686).
+/// The EditBox's OnShow/OnHide vtable overrides (`0x81c910` slots +0x30/+0x34), run after the
+/// frame's Lua handler, since both call the base notify first. Show (`0x77a750`) focuses an
+/// `autoFocus` box when nothing holds the focus, first come first served; hide (`0x77a780`)
+/// tail-jumps `ClearFocus`.
 pub(super) fn visibility_focus(lua: &Lua, h: FrameHandle, visible: bool) {
     if !visible {
-        // The guard lives in `clear_focus_handle`, exactly as it does in `0x77e410` — so this is
-        // called unconditionally here, like the reference's own unconditional tail-jmp.
+        // Unconditional, like the reference's tail-jump: the guard is in `clear_focus_handle`.
         clear_focus_handle(lua, h);
         return;
     }
@@ -285,14 +212,13 @@ pub(super) fn visibility_focus(lua: &Lua, h: FrameHandle, visible: bool) {
             )
     };
     if wants {
-        // `SetFocus` re-checks effective-visibility itself, which is the reference's gate too.
+        // `SetFocus` checks effective visibility itself.
         set_focus_handle(lua, h);
     }
 }
 
-/// `ClearFocus` (`0x77e410`): only if this box holds focus; fire `OnEditFocusLost`. The guard is
-/// `mov eax,ecx; mov ecx,[0xcf4dc8]; cmp ecx,eax; jne ret` — verified per-box, which is what makes
-/// the OnHide override's *unconditional* tail-jmp into it harmless.
+/// `ClearFocus` (`0x77e410`): only when this box holds the focus (`[0xcf4dc8]`), then fires
+/// `OnEditFocusLost`.
 fn clear_focus_handle(lua: &Lua, h: FrameHandle) {
     let id = {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -306,12 +232,11 @@ fn clear_focus_handle(lua: &Lua, h: FrameHandle) {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
-// Editing primitives — mutate state under one borrow, then sync + fire
+// Editing primitives: mutate under one borrow, then sync and fire
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
-/// Insert `ins` at the cursor (`0x77bee0`): replace any selection first; `numeric` aborts wholesale on
-/// a non-digit; splice + advance; enforce caps; fire `OnTextChanged`, and (when `fire_space`) one
-/// `OnSpacePressed` per space in `ins`.
+/// `Insert` (`0x77bee0`): replace the selection, abort on a non-digit when `numeric`, splice,
+/// enforce caps, mark `OnTextChanged`, and with `fire_space` fire one `OnSpacePressed` per space.
 fn insert(lua: &Lua, h: FrameHandle, ins: &str, fire_space: bool) {
     let Some(out) = with_eb(lua, h, |eb| eb.insert(ins)) else {
         return; // not an EditBox
@@ -321,14 +246,8 @@ fn insert(lua: &Lua, h: FrameHandle, ins: &str, fire_space: bool) {
     }
     sync_text_region(lua, h);
     let id = frame_id_of(lua, h);
-    // **The EditBox DOES fire generic `OnChar`** — with the spliced string as `arg1`, from inside
-    // Insert itself (`0x77c13c`, the varargs firer `0x7026f0` with fmt `"%s"`), before the dirty
-    // flush gets round to `OnTextChanged`. The "never generic `OnKeyDown`/`OnChar`" rule holds
-    // only for `OnKeyDown` (`+0x188`, corrected 2026-08-29) — it missed `OnChar`'s varargs-firer
-    // path, distinct from the sibling fixed-arity firer `0x702690`. It rides the one choke point
-    // every insert path goes through — typed char, the `|`→`||` escape, the multiLine Enter
-    // newline, the Lua `Insert` — and so is absent from `SetText`, which is where the reference
-    // has it absent too.
+    // Insert fires the generic `OnChar` with the spliced string as `arg1` (`0x77c13c`, through the
+    // varargs firer `0x7026f0`), before the deferred `OnTextChanged`; `SetText` does not.
     let on_char = lua
         .create_string(ins)
         .and_then(|s| event::fire_widget_handler(lua, id, "OnChar", vec![mlua::Value::String(s)]));
@@ -345,8 +264,8 @@ fn insert(lua: &Lua, h: FrameHandle, ins: &str, fire_space: bool) {
     }
 }
 
-/// `SetText` (`0x77be00`): short-circuit when unchanged (no events); else clear selection, replace,
-/// cursor to end, enforce caps, fire `OnTextSet` then `OnTextChanged`.
+/// `SetText` (`0x77be00`): nothing when unchanged; else clear the selection, replace, cursor to
+/// the end, enforce caps, fire `OnTextSet` and mark `OnTextChanged`.
 fn set_text(lua: &Lua, h: FrameHandle, s: &str) {
     let changed = with_eb(lua, h, |eb| eb.set_text(s));
     if changed == Some(true) {
@@ -357,9 +276,8 @@ fn set_text(lua: &Lua, h: FrameHandle, s: &str) {
     }
 }
 
-/// Word/edge deletes (`Delete{Word,Edge}` — no 1.12 counterpart; the OS-native keymap family):
-/// the selection first when one exists, else the span from the cursor to `target_of(eb)`; sync +
-/// `OnTextChanged` when anything was removed.
+/// Word and edge deletes (no 1.12 counterpart): the selection if any, else the cursor to
+/// `target_of(eb)`.
 fn delete_span(lua: &Lua, h: FrameHandle, target_of: impl FnOnce(&EditBoxState) -> usize) {
     let changed = with_eb(lua, h, |eb| {
         let t = target_of(eb);
@@ -371,8 +289,7 @@ fn delete_span(lua: &Lua, h: FrameHandle, target_of: impl FnOnce(&EditBoxState)
     }
 }
 
-/// BACKSPACE / DELETE: delete the selection if non-empty, else the char before (`forward=false`) or
-/// after (`forward=true`) the cursor; fire `OnTextChanged` if anything was removed.
+/// Backspace and Delete: the selection if any, else one char before or after the cursor.
 fn delete_dir(lua: &Lua, h: FrameHandle, forward: bool) {
     let changed = with_eb(lua, h, |eb| eb.delete_dir(forward));
     if changed == Some(true) {
@@ -381,10 +298,8 @@ fn delete_dir(lua: &Lua, h: FrameHandle, forward: bool) {
     }
 }
 
-/// One UP/DOWN history-recall step: ask the state for the line to show and route it through the
-/// internal `set_text` path (region sync + `OnTextSet`/`OnTextChanged` — a recall resets FrameXML
-/// tab-complete state exactly like any other text change). `set_text` (internal AND Lua) leaves
-/// the browse position intact; typed edits, `AddHistoryLine`, and focus gain end browsing.
+/// One history-recall step through `set_text`, so a recall fires `OnTextSet` like any text change.
+/// `set_text` keeps the browse position; typing, `AddHistoryLine` and a focus gain end it.
 fn history_step_key(lua: &Lua, h: FrameHandle, older: bool) {
     let recalled = with_eb(lua, h, |eb| eb.history_step(older)).flatten();
     if let Some(text) = recalled {
@@ -392,30 +307,26 @@ fn history_step_key(lua: &Lua, h: FrameHandle, older: bool) {
     }
 }
 
-/// LEFT/RIGHT one char: `shift` extends the selection from the fixed anchor; otherwise the caret
-/// collapses to the selection edge (if any) or moves one char. Fires no script (a cursor/selection
-/// move; `OnCursorChanged` geometry is out of scope).
+/// Left/Right: `shift` extends from the anchor, else collapse the selection or move one char.
 fn move_horizontal(lua: &Lua, h: FrameHandle, right: bool, shift: bool) {
     with_eb(lua, h, |eb| eb.move_by_char(right, shift));
 }
 
-/// HOME/END: move the caret to 0 / `len`; `shift` extends from the fixed anchor.
+/// Home/End; `shift` extends from the anchor.
 fn move_to_edge(lua: &Lua, h: FrameHandle, end: bool, shift: bool) {
     with_eb(lua, h, |eb| eb.move_to_edge(end, shift));
 }
 
-/// `HighlightText` (`0x77cca0`), the client's exact clamp: `start = clamp(start, 0..=len)`;
-/// `end = (end < 0 || end > len) ? len : end`; then `if end < start { end = len }` — so `(0, -1)`
-/// selects all. Offsets are bytes, snapped to char boundaries.
+/// `HighlightText` (`0x77cca0`): `start = clamp(start, 0..=len)`; `end = (end < 0 || end > len) ?
+/// len : end`; then `if end < start { end = len }`, so `(0, -1)` selects all. Offsets are bytes,
+/// snapped to char boundaries.
 fn highlight_text(lua: &Lua, h: FrameHandle, start: i64, end: i64) {
     with_eb(lua, h, |eb| eb.highlight_text(start, end));
 }
 
-// ── text-region sync (the '*' mask lives here) ────────────────────────────────────────────────
+// ── text-region sync ─────────────────────────────────────────────────────────────────────────
 
-/// Write the *display* string into the text region's [`RegionData::text`], creating the region lazily
-/// (the implicit FontString) if none exists. `password` shows one `'*'` per **character** (the mask,
-/// never the real text).
+/// Write the display string into the text region; a `password` box shows one `*` per character.
 fn sync_text_region(lua: &Lua, h: FrameHandle) {
     let Some(rh) = ensure_text_region(lua, h) else {
         return;
@@ -434,10 +345,7 @@ fn sync_text_region(lua: &Lua, h: FrameHandle) {
     }
 }
 
-/// `SetTextInsets(l, r, t, b)`: store the insets and re-anchor the text region inside the box by
-/// them (y-up: the top inset pulls the region's top DOWN, the bottom inset pulls its bottom UP).
-/// The chat edit box calls this per header change (`ChatEdit_UpdateHeader`'s
-/// `SetTextInsets(15 + headerWidth, 13, 0, 0)`), so typed text starts past the "Say:" header.
+/// `SetTextInsets(l, r, t, b)`: store the insets and re-anchor the text region by them.
 fn set_text_insets(lua: &Lua, h: FrameHandle, l: f32, r: f32, t: f32, b: f32) {
     if with_eb(lua, h, |eb| eb.text_insets = [l, r, t, b]).is_none() {
         return;
@@ -448,8 +356,8 @@ fn set_text_insets(lua: &Lua, h: FrameHandle, l: f32, r: f32, t: f32, b: f32) {
     write_inset_anchors(lua, h, rh, [l, r, t, b]);
 }
 
-/// Anchor the text region inside its box by the insets — the two corner anchors that pin its rect
-/// (y-up: the top inset pulls the region's top DOWN, the bottom inset pulls its bottom UP).
+/// Pin the text region's corners inside the box by the insets (y-up: the top inset moves its top
+/// down, the bottom inset its bottom up).
 fn write_inset_anchors(lua: &Lua, h: FrameHandle, rh: RegionHandle, [l, r, t, b]: [f32; 4]) {
     let owner = frame_id_of(lua, h);
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -470,15 +378,9 @@ fn write_inset_anchors(lua: &Lua, h: FrameHandle, rh: RegionHandle, [l, r, t, b]
     }
 }
 
-/// The wrapper for an EditBox's **embedded** text FontString — the region its ctor built at
-/// `0x779bee` (`Arena::build_editbox_engine_regions`). `None` when `frame` is not a live EditBox.
-///
-/// The loader's special-`<FontString>` pass uses this instead of `CreateFontString`: the
-/// reference's EditBox LoadXML (`0x779fb0`) treats `<FontString>` as the box's *embedded* font
-/// string (its `bytes` attr writes the box's own `maxBytes`), so the element DECLARES the ctor's
-/// object rather than adding a region. Creating a second one would leave an orphan on the frame
-/// and push the authored `<Layers>` regions one place down the creation-ordered list `GetRegions`
-/// walks.
+/// The wrapper for an EditBox's embedded text FontString, built by its ctor (`0x779bee`). The
+/// loader uses it for `<FontString>`: the reference's EditBox LoadXML (`0x779fb0`) declares the
+/// ctor's font string rather than adding a region (its `bytes` sets the box's `maxBytes`).
 pub(crate) fn editbox_text_region_wrapper(lua: &Lua, frame: &Table) -> Option<Table> {
     let h = frame_handle_of(lua, frame).ok()?;
     let rh = ensure_text_region(lua, h)?;
@@ -489,10 +391,8 @@ pub(crate) fn editbox_text_region_wrapper(lua: &Lua, frame: &Table) -> Option<Ta
     super::region::region_wrapper(lua, id).ok()
 }
 
-/// The loader's special-`<FontString>` slot assignment: adopt `region` as `frame`'s text region,
-/// anchored by the current insets. The engine ASSIGNS an EditBox's font string at LoadXML — it
-/// never searches the region list (a find-first here once grabbed a `<Layers>` FontString, the
-/// chat header, so typing overwrote "Say:" and the insets clobbered the header's anchor).
+/// Adopt `region` as `frame`'s text region, anchored by the current insets: LoadXML assigns an
+/// EditBox's font string, never searching the region list.
 pub(crate) fn adopt_text_region(lua: &Lua, frame: &Table, region: &Table) -> mlua::Result<()> {
     let h = frame_handle_of(lua, frame)?;
     let rh = super::region::region_handle_of(lua, region)?;
@@ -500,11 +400,10 @@ pub(crate) fn adopt_text_region(lua: &Lua, frame: &Table, region: &Table) -> mlu
         eb.text_region = Some(rh);
         (eb.text_insets, eb.multi_line)
     }) else {
-        return Ok(()); // not an EditBox — the loader guards on the tag, but stay safe
+        return Ok(()); // not an EditBox
     };
     write_inset_anchors(lua, h, rh, insets);
-    // A live text region always carries Some(text) — an empty box still emits its Text quad, so
-    // the host's caret has a styled quad to ride before the first keystroke.
+    // Always `Some` text: an empty box still emits its Text quad for the host's caret.
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
     let data = model.region_data.entry(rh).or_default();
     data.text.get_or_insert_with(String::new);
@@ -512,36 +411,31 @@ pub(crate) fn adopt_text_region(lua: &Lua, frame: &Table, region: &Table) -> mlu
     Ok(())
 }
 
-/// Get-or-create the implicit text FontString (the EditBox's ButtonText analogue). Returns `None` if
-/// `h` is not a live EditBox. An XML-declared `<FontString>` is wired explicitly by the loader's
-/// special pass ([`adopt_text_region`]); the lazy create covers CreateFrame'd boxes.
+/// Get or create the box's text FontString; an XML-declared one is wired by [`adopt_text_region`].
 pub(super) fn ensure_text_region(lua: &Lua, h: FrameHandle) -> Option<RegionHandle> {
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
     let (existing, multi_line) = match model.arena.frame(h).map(|f| &f.kind_state) {
         Some(KindState::EditBox(eb)) => (eb.text_region, eb.multi_line),
         _ => return None,
     };
-    // The ctor already built it (`Arena::build_editbox_engine_regions` — the client's own
-    // `0x779bee`, the first of the five regions a CSimpleEditBox is born with). The REGION exists
-    // from birth; its `RegionData` does not, because the arena has no access to it — so seed that
-    // here, once, on whichever call arrives first.
+    // The ctor built the region (`0x779bee`, the first of a CSimpleEditBox's five regions); its
+    // `RegionData` is seeded here, on the first call.
     let rh = match existing {
         Some(rh) => rh,
-        // A box whose ctor pass could not run (a dead handle, or a non-EditBox that slipped the
-        // guard above) still gets a region rather than silently rendering nothing.
+        // A box whose ctor pass did not run still gets a region.
         None => model
             .arena
             .create_region(h, RegionKind::FontString, DrawLayer::Overlay, 0)?,
     };
     if let std::collections::hash_map::Entry::Vacant(slot) = model.region_data.entry(rh) {
         let mut data = RegionData {
-            // Some("") from birth — the empty box still emits its Text quad for the host caret.
+            // Some("") from birth: the empty box still emits its Text quad for the host caret.
             text: Some(String::new()),
             ..RegionData::default()
         };
         apply_text_region_justify(&mut data, multi_line);
         slot.insert(data);
-        model.touch_layout(); // a region entered the layout gate's read set (decision 0740)
+        model.touch_layout(); // a region entered the layout gate's read set
     }
     if let Some(KindState::EditBox(eb)) = model.arena.frame_mut(h).map(|f| &mut f.kind_state) {
         eb.text_region = Some(rh);
@@ -549,10 +443,8 @@ pub(super) fn ensure_text_region(lua: &Lua, h: FrameHandle) -> Option<RegionHand
     Some(rh)
 }
 
-/// Re-seat an already-wired text region's justify by the box's CURRENT multiLine flag — the
-/// `SetMultiLine` rider: the loader adopts the declared `<FontString>` (LoadXML step 5·b) before
-/// it applies the editbox flags (5b), so `multiLine="true"` must re-run the law or the body box
-/// keeps the single-line MIDDLE seat.
+/// Re-apply the text region's justify for the current `multiLine` flag: LoadXML adopts the
+/// `<FontString>` before it applies the box's flags.
 pub(super) fn refresh_text_region_justify(lua: &Lua, this: &Table) -> mlua::Result<()> {
     let h = frame_handle_of(lua, this)?;
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -566,12 +458,8 @@ pub(super) fn refresh_text_region_justify(lua: &Lua, this: &Table) -> mlua::Resu
     Ok(())
 }
 
-/// The EditBox text-anchoring law: the box's text region lays out LEFT-justified (the client's
-/// editbox draw `0x77da80` is left-anchored at the insets rect regardless of the font string's
-/// declared justification — focused or not), from the TOP for a multiline box, vertically
-/// centered for a single-line one. Without this, a bare
-/// `<FontString inherits="ChatFontNormal"/>` inherits the FontString CENTER/MIDDLE defaults and
-/// an empty focused box parks its caret mid-box (the mail send tab's original sin).
+/// Left-justified whatever the font string declares (the draw `0x77da80` anchors left at the
+/// insets), from the top in a multiLine box and vertically centered otherwise.
 fn apply_text_region_justify(data: &mut RegionData, multi_line: bool) {
     data.justify.set_h(crate::script::JustifyH::Left);
     data.justify.set_v(if multi_line {
@@ -592,7 +480,6 @@ fn with_eb<T>(lua: &Lua, h: FrameHandle, f: impl FnOnce(&mut EditBoxState) -> T)
     }
 }
 
-/// The stable id of a frame handle (minting one if needed).
 fn frame_id_of(lua: &Lua, h: FrameHandle) -> u32 {
     lua.app_data_mut::<Model>()
         .expect("model app_data")
@@ -608,35 +495,16 @@ fn fire_script(lua: &Lua, id: u32, name: &str) {
     }
 }
 
-/// **The caret flush's fire — `OnCursorChanged(x, y, w, h)`** (`0x77da80`).
+/// `OnCursorChanged(x, y, w, h)` from the caret flush (`0x77da80`, in UI units via `0x77dd5f`): `x`
+/// is the caret's advance along its line, `y` minus the row index times the row pitch, `w` the
+/// constant 4.0 and `h` the line height. It fires only when the caret moved: the flush's one
+/// caller, `0x77d475`, is gated on dirty bit 2.
 ///
-/// The reference recomputes the caret's anchor inside `0x77da80` and, having done so, fires this
-/// with four floats, each scaled by `f` so all four are in FrameXML UI units (`0x77dd5f`):
+/// Deviation: `h` is the row pitch, which is taller than the line height only for a font with
+/// extra spacing (none in the stock UI), because the host's advance answer carries one measure.
 ///
-/// * `x` — the caret's advance from its line's start, the same number the paint anchors by
-///   ([`EditBoxState::caret_row_x`]).
-/// * `y` — `−lineIndex · (snap(H·scale) + snap(spacing·scale))/scale`, i.e. minus the row index
-///   times the row pitch. **Negative-downward**, which is what `ScrollingEdit_OnCursorChanged`'s
-///   `cursorOffset = y` then `-this.cursorOffset` reads as a positive distance down the page.
-/// * `w` — **`≡ 4.0`**, a constant in the reference (the caret texture's own width, read through
-///   its layout vtable `+0x1c`).
-/// * `h` — the font line height, read through `+0x20`.
-///
-/// Ours takes the row pitch [`EditBoxState::cell_h`] for both the `y` factor and `h`. The two are
-/// the same number whenever the font declares no extra `spacing`, which is every box in the
-/// shipped 1.12 UI; a box that *does* set spacing would report an `h` a little tall. Named rather
-/// than guessed at — the alternative is carrying a second measured number through the advance
-/// answer for a case nothing in the corpus produces.
-///
-/// **The edge is a CHANGE, not a frame.** `0x77da80` has exactly one caller, `0x77d475`, gated on
-/// dirty bit 2, so the handler runs when the caret has actually moved — which is what makes
-/// `ScrollingEdit_OnUpdate`'s `if (this.cursorOffset)` idiom terminate. [`EditBoxState::cursor_fired`]
-/// is that bit's memory here.
-///
-/// **Scoped to the focused box**, because the caret geometry rides the advance table and only the
-/// focused box asks the host for one ([`super::editbox::seam`]). The reference flushes any dirty
-/// box; the difference is invisible for the customer this exists for — you are typing in the box
-/// you are looking at — and an unfocused box's caret is never drawn either way.
+/// Deviation: only the focused box fires, where the reference flushes any dirty box, because only
+/// the focused box gets an advance table from the host.
 pub(in crate::script) fn drain_cursor_changed(lua: &Lua) {
     let fire = {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -651,8 +519,7 @@ pub(in crate::script) fn drain_cursor_changed(lua: &Lua) {
         else {
             return;
         };
-        // No answered advance table yet ⇒ no caret geometry to report. The next tick after the
-        // host answers carries it, exactly as the reference's next flush would.
+        // No advance table yet: the tick after the host answers reports it.
         let display = eb.display();
         if eb.advances.len() != display.len() + 1 {
             return;
@@ -688,28 +555,19 @@ pub(in crate::script) fn drain_cursor_changed(lua: &Lua) {
     }
 }
 
-/// The caret's width as `OnCursorChanged` reports it — **a constant in the reference**, not a
-/// measurement: `w ≡ 4.0` (`+0x1c` in the layout vtable).
+/// The caret width `OnCursorChanged` reports, a constant in the reference.
 const CARET_WIDTH: f32 = 4.0;
 
-// The Lua method surface (SetText/GetText/HighlightText/SetFocus/…, consulted before the shared
-// frame table only for EditBox frames) — a child module over this file's focus/editing
-// primitives, like `interact`/`seam`.
+// The EditBox Lua methods, consulted before the shared frame table for EditBox frames.
 mod methods;
 pub(super) use methods::install;
 
 #[cfg(test)]
 mod tests;
 
-/// Raise the `textChanged` dirty bit (`[E+0x31c]` bit 0) rather than firing — **`OnTextChanged` is
-/// deferred**, and this is the whole of decision 1831's second half.
-///
-/// The reference never fires it from an edit. `SetText 0x77be00`, `Insert 0x77bee0` and the deletes
-/// all only OR the bit; the single fire site is `0x77d498`, inside the dirty-word drain `0x77d3e0`,
-/// whose three callers are the box's own `OnUpdate` (`0x77a790`), its `OnKeyDown` (`0x77b160`) and
-/// its `OnMouseDown` (`0x77b800`). So a Lua caller gets control back with the handler still
-/// unrun, and repeated changes **coalesce**: the box appears once on the pending list however many
-/// times it is written, and the one fire carries the final text.
+/// Raise the `textChanged` dirty bit (`[E+0x31c]` bit 0): the reference's edits only mark it, and
+/// its one fire site (`0x77d498`) is in the drain `0x77d3e0`, so a Lua caller gets control back
+/// before the handler runs and repeated changes coalesce into one fire with the final text.
 pub(super) fn mark_text_changed(lua: &Lua, h: FrameHandle) {
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
     if !model.dirty_editboxes.contains(&h) {
@@ -717,21 +575,14 @@ pub(super) fn mark_text_changed(lua: &Lua, h: FrameHandle) {
     }
 }
 
-/// The dirty-word drain (`0x77d3e0`): fire the pending `OnTextChanged`s.
+/// The dirty-word drain (`0x77d3e0`): fire the pending `OnTextChanged`s from the frame tick, as the
+/// box's `OnUpdate` (`0x77a790`) does. A hidden box stays pending until shown: `Hide` unlinks it
+/// from the update chain (that it then gets no `OnUpdate` is inferred). The list is taken before
+/// any Lua runs, so a box a handler re-marks fires on the next drain, as the reference clears its
+/// bit before the fire.
 ///
-/// Called from the frame tick — the first of the reference's three callers (`0x77a7a1`, inside the
-/// box's own `OnUpdate` `0x77a790`, which is also where our caret blink lives). Its other two, the
-/// box's `OnKeyDown` and `OnMouseDown`, are **not** wired: they only make a pending fire arrive
-/// sooner within a frame, and our key and mouse paths reach the tick anyway. Decision 1831 says so
-/// out loud rather than leaving it to be discovered.
-///
-/// A box that is **not effectively visible stays pending**: `Hide`
-/// splices it out of the chain the update walk follows, so its fire waits for a `Show` (verified
-/// chain mechanics; the "hidden ⇒ no OnUpdate" step is inferred, not confirmed in the binary).
-///
-/// A handler may itself write to a box — including this one — so the list is taken before any Lua
-/// runs and anything re-marked during the sweep lands on the NEXT drain rather than extending this
-/// one. That is the reference's shape too: its bit is cleared before its fire.
+/// Deviation: not drained from `OnKeyDown` (`0x77b160`) or `OnMouseDown` (`0x77b800`), because
+/// those only bring the fire sooner within a frame and our key and mouse paths reach the tick.
 pub(in crate::script) fn drain_text_changed(lua: &Lua) {
     let pending = {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
diff --git a/crates/benilla-ui/src/script/editbox/interact.rs b/crates/benilla-ui/src/script/editbox/interact.rs
index a5315670..c1b4b093 100644
--- a/crates/benilla-ui/src/script/editbox/interact.rs
+++ b/crates/benilla-ui/src/script/editbox/interact.rs
@@ -1,20 +1,4 @@
-//! The EditBox mouse/selection interaction law — click→char-index, drag-select, the clipboard
-//! pair, and the caret blink — a child module over the mother's focus/editing primitives.
-//!
-//! Byte law:
-//!
-//! - **Click `0x77b800`**: on a hit — blink reset, click→index (`0x77d0d0`) places the cursor and
-//!   collapses the selection, the drag flag raises (`E+0x364 = 1`), then `SetFocus`
-//!   UNCONDITIONALLY. No shift+click branch exists in the handler (INFERRED by absence — 1.12
-//!   predates extend-on-click).
-//! - **Drag `0x77a860`** (mouse move while `+0x364`): map x→index, extend the selection there via
-//!   the same helper Shift+arrow uses (`0x77cd10`), cursor following.
-//! - **Release** (`0x77afc0` case 1): `+0x364 = 0`.
-//! - **Clipboard**: Ctrl+C/X act only with a non-empty selection (`0x77e1d0`); X then
-//!   deletes = cut. A password box copies a FIXED placeholder (`0x882748`, runtime literal
-//!   unresolved — flagged live-capture), never the real text; benilla stands in the mask run.
-//! - **Blink `0x77a790`**: the focused box's accumulator (`E+0x374`) advances by dt; crossing the
-//!   period (`E+0x370`, ctor default 0.5 s) toggles the caret and zeroes the accumulator.
+//! EditBox mouse and clipboard interaction: click, drag-select, copy, cut and the caret blink.
 
 use mlua::Lua;
 
@@ -22,13 +6,10 @@ use super::{set_focus_handle, sync_text_region, with_eb};
 use crate::script::Model;
 use crate::widget::{FrameHandle, FrameKind, KindState};
 
-/// Map a screen point (the engine's y-up UI space — the same space resolved rects and the
-/// pointer API live in) to the box's TEXT byte index: x relative to the text region's left edge,
-/// shifted into advance space by the scroll window's origin, nearest char boundary (`0x77d0d0`;
-/// the rounding is INFERRED nearest). A multiline box also reads y — px down from the region's
-/// top pick the wrapped row ([`crate::widget::EditBoxState::index_at_pos`]). Ends up at
-/// end-of-text while the advance table is unanswered — the pre-seam behavior, degrading
-/// gracefully.
+/// A UI-space point (y up) to the box's text byte index at the nearest cursor stop (`0x77d0d0`,
+/// whose own rounding is untraced): x from the text region's left edge plus the scroll origin, and
+/// in a multi-line box y from its top picks the wrapped row. The end of the text until the advance
+/// table is answered.
 fn index_at_screen_pos(lua: &Lua, h: FrameHandle, x: f32, y: f32) -> usize {
     let corner = {
         let model = lua.app_data_ref::<Model>().expect("model app_data");
@@ -36,8 +17,7 @@ fn index_at_screen_pos(lua: &Lua, h: FrameHandle, x: f32, y: f32) -> usize {
             Some(KindState::EditBox(eb)) => eb.text_region,
             _ => None,
         };
-        // The text region's resolved corner; an unanchored region (no insets) draws over its
-        // owner, so the frame's own edges stand in.
+        // An unanchored text region draws over its owner, so the frame's own corner stands in.
         rh.and_then(|rh| model.region_resolved.get(&rh))
             .or_else(|| model.resolved.get(&h))
             .map(|r| (r.left, r.top))
@@ -53,8 +33,8 @@ fn index_at_screen_pos(lua: &Lua, h: FrameHandle, x: f32, y: f32) -> usize {
     .unwrap_or(0)
 }
 
-/// A LeftButton press landed on frame `id` (`0x77b800`): if it is an EditBox — blink reset, the
-/// cursor to the clicked char (collapsing any selection), drag begins, focus UNCONDITIONALLY.
+/// A LeftButton press on EditBox `id` (`0x77b800`) places the cursor at the clicked char,
+/// collapsing the selection, starts a drag and takes focus unconditionally; no shift+click branch.
 pub(in crate::script) fn click(lua: &Lua, id: u32, x: f32, y: f32) {
     let Some(h) = editbox_of(lua, id) else { return };
     let idx = index_at_screen_pos(lua, h, x, y);
@@ -65,8 +45,8 @@ pub(in crate::script) fn click(lua: &Lua, id: u32, x: f32, y: f32) {
     set_focus_handle(lua, h);
 }
 
-/// Mouse move while the press is held (`0x77a860`): the focused, drag-active box extends its
-/// selection to the hovered index; the cursor follows.
+/// Mouse move with the button held (`0x77a860`): a dragging focused box extends its selection to
+/// the hovered index through the Shift+arrow helper (`0x77cd10`).
 pub(in crate::script) fn drag_update(lua: &Lua, x: f32, y: f32) {
     let Some(h) = focused(lua) else { return };
     if with_eb(lua, h, |eb| eb.drag_active) != Some(true) {
@@ -80,30 +60,27 @@ pub(in crate::script) fn drag_update(lua: &Lua, x: f32, y: f32) {
     });
 }
 
-/// The press released (`0x77afc0` case 1): the drag ends. Fires for any release — a box that
-/// never started a drag ignores it.
+/// Any button release ends the drag (`0x77afc0` case 1).
 pub(in crate::script) fn drag_end(lua: &Lua) {
     if let Some(h) = focused(lua) {
         with_eb(lua, h, |eb| eb.drag_active = false);
     }
 }
 
-/// Ctrl+LEFT/RIGHT — the word-granular cursor move (the client walks its per-byte class array on
-/// the Ctrl branch, `0x41f8f0(1)`; benilla's alnum-run approximation is INFERRED): `shift` extends
-/// the selection from the fixed anchor like the char move; else the caret collapses there.
+/// Ctrl+Left/Right, the word move: the client walks its per-byte class array (`0x41f8f0(1)`),
+/// benilla stops at alphanumeric runs. `shift` extends the selection from its anchor.
 pub(in crate::script) fn move_word(lua: &Lua, h: FrameHandle, right: bool, shift: bool) {
     with_eb(lua, h, |eb| eb.move_by_word(right, shift));
 }
 
-/// Ctrl+C (`0x77e1d0`): the focused box's selected substring, `None` with no selection. A
-/// password box yields the mask run — the client copies a fixed placeholder, NEVER the text.
+/// Ctrl+C (`0x77e1d0`): the focused box's selection. A password box never yields its text: the
+/// client copies the image's empty string (`0x882748`), benilla the mask run.
 pub(in crate::script) fn copy_selection(lua: &Lua) -> Option<String> {
     let h = focused(lua)?;
     with_eb(lua, h, |eb| eb.selected_text()).flatten()
 }
 
-/// Ctrl+X: copy, then delete the selection (an ordinary edit — the region syncs and
-/// `OnTextChanged` fires).
+/// Ctrl+X (`0x77e1d0`): copy, then delete the selection as an ordinary edit.
 pub(in crate::script) fn cut_selection(lua: &Lua) -> Option<String> {
     let h = focused(lua)?;
     let copied = with_eb(lua, h, |eb| eb.cut_selection()).flatten()?;
@@ -112,9 +89,8 @@ pub(in crate::script) fn cut_selection(lua: &Lua) -> Option<String> {
     Some(copied)
 }
 
-/// The blink tick (`0x77a790`, run from the host's frame tick): the focused box's accumulator
-/// advances; crossing the period toggles the caret and resets. Non-positive period never blinks
-/// (a solid caret).
+/// The caret blink (`0x77a790`), each frame: past the period (0.5 s by default) the focused box's
+/// caret toggles and the accumulator resets; a non-positive period keeps the caret solid.
 pub(in crate::script) fn tick_blink(lua: &Lua, dt: f32) {
     if let Some(h) = focused(lua) {
         with_eb(lua, h, |eb| {
@@ -129,14 +105,12 @@ pub(in crate::script) fn tick_blink(lua: &Lua, dt: f32) {
     }
 }
 
-/// The focused EditBox handle, if any.
 fn focused(lua: &Lua) -> Option<FrameHandle> {
     lua.app_data_ref::<Model>()
         .expect("model app_data")
         .focused_editbox
 }
 
-/// Resolve a frame id to a live EditBox handle.
 fn editbox_of(lua: &Lua, id: u32) -> Option<FrameHandle> {
     let model = lua.app_data_ref::<Model>().expect("model app_data");
     let h = model.id_to_frame.get(&id).copied()?;
diff --git a/crates/benilla-ui/src/script/editbox/methods.rs b/crates/benilla-ui/src/script/editbox/methods.rs
index 3cb773c9..056a492f 100644
--- a/crates/benilla-ui/src/script/editbox/methods.rs
+++ b/crates/benilla-ui/src/script/editbox/methods.rs
@@ -1,8 +1,5 @@
-//! The EditBox Lua method surface — `install` builds the method table
-//! (`REG_EDITBOX_METHODS`) the dispatcher consults before the shared frame table for EditBox
-//! frames: text/cursor/selection accessors, focus, history, the config setters, and the blink
-//! dial. Every method routes through the mother module's primitives (`set_text`,
-//! `highlight_text`, …), so the byte-verified law lives exactly once.
+//! The EditBox Lua method table (`REG_EDITBOX_METHODS`), consulted before the shared frame
+//! table; each method routes through the parent module's primitives.
 
 use mlua::{Lua, Table, Value};
 
@@ -14,7 +11,6 @@ use super::{
     with_eb, REG_EDITBOX_METHODS,
 };
 
-/// Run `f` over a frame's EditBox state for a Lua method call; errors if `this` is not a live EditBox.
 fn with_editbox<T>(
     lua: &Lua,
     this: &Table,
@@ -32,11 +28,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, (this, s): (Table, Option<mlua::Value>)| {
             let s = crate::script::binding_abi::text_arg(lua, s)?;
             let h = frame_handle_of(lua, &this)?;
-            // Programmatic SetText KEEPS a history browse in progress: the chat live parse
-            // rewrites the box on every recalled slash line ("/s hi" → Say + "hi"), and ending
-            // the browse there reset every UP to the newest entry — "history only goes back 1"
-            // (director's report, 2026-07-26). The browse ends on typed edits, AddHistoryLine,
-            // and focus gain (`set_focus_handle`) — the fresh-session reset.
+            // SetText keeps a history browse going: the chat parser rewrites each recalled slash
+            // line, and ending the browse there would send every Up back to the newest entry.
+            // Typed edits, AddHistoryLine and focus gain end it.
             set_text(lua, h, &s.unwrap_or_default());
             Ok(())
         })?,
@@ -45,30 +39,16 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         "GetText",
         lua.create_function(|lua, this: Table| with_editbox(lua, &this, |eb| eb.text.clone()))?,
     )?;
-    // SetNumber(v) — **the same function as SetText**. `0x798690` and `0x7984c0` are byte-identical
-    // (245 bytes each, zero differences after masking rel32 and absolute-VA operands; only the
-    // usage string differs), so this does no numeric work of its own: it hands the argument to the
-    // shared `lua_tostring` marshalling and sets the result as text. Decision 1831.
-    //
-    // The GATE is `lua_isstring 0x6f3510`, a pure type test over {number, string} — NOT
-    // `lua_isnumber` and NOT `luaL_checknumber`. So a STRING is accepted and passed through
-    // VERBATIM, never parsed: `SetNumber("abc")` sets the text "abc" and does not raise. Anything
-    // else — nil, boolean, table, or an ABSENT argument — raises the usage string and abandons the
-    // caller's statement.
-    //
-    // The live consumer is `MoneyInputFrame.lua:47/52/57`, on the chain since 1751, whose three
-    // boxes are `numeric="true"`. Our numeric filter already models the reference's wholesale
-    // abort, which matters here: on such a box `SetNumber(-5)` or `SetNumber(0.8)` leaves the box
-    // EMPTY rather than partially filled, because the sign or the point fails the digit test after
-    // the clear-all has already run. The money path only ever passes non-negative integers
-    // (`floor`/`mod` results), so it never takes that branch.
+    // SetNumber is SetText: `0x798690` and `0x7984c0` are byte-identical but for the usage
+    // string. Its gate is `lua_isstring` (`0x6f3510`), so a string is set verbatim, never parsed,
+    // and nil, a boolean, a table or no argument raises the usage string. On a numeric box `-5` or
+    // `0.8` leaves it empty: the sign or point fails the digit test after the clear has run.
     m.set(
         "SetNumber",
         lua.create_function(|lua, (this, v): (Table, Value)| {
             let text = match &v {
                 Value::Integer(i) => crate::script::binding_abi::lua_number_text(*i as f64),
                 Value::Number(n) => crate::script::binding_abi::lua_number_text(*n),
-                // A string is not parsed — it is the text.
                 Value::String(s) => s.to_str()?.to_string(),
                 _ => return Err(mlua::Error::runtime("Usage: EditBox:SetNumber(number)")),
             };
@@ -77,7 +57,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // GetNumber: atof of the real text (0 on failure), matching `0x798790`.
+    // GetNumber: the real text as a number, else 0. The reference (`0x798790`) is atof, which also
+    // reads the leading number of a text like "12abc".
     m.set(
         "GetNumber",
         lua.create_function(|lua, this: Table| {
@@ -85,19 +66,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(text.trim().parse::<f64>().unwrap_or(0.0))
         })?,
     )?;
-    // Insert(text) — **a nil is a no-op, not an error.** The reference's C `Insert` reads its
-    // argument through `lua_tostring`, which answers NULL for a nil and leaves the buffer alone;
-    // stock FrameXML relies on that. `LootFrame.lua:152` is the plain case:
-    //
-    //     ChatFrameEditBox:Insert(GetLootSlotLink(this.slot));
-    //
-    // with no guard, on a coin row whose `GetLootSlotLink` is nil. Typed as `String`, this raised
-    // — which the loot window only survived while we owned the file and could add a guard the
-    // reference does not have. It bit the moment `LootFrame.xml` came off the player's chain
-    // (1751), and it would bite any addon writing the same unguarded line.
-    //
-    // A NUMBER still inserts its digits: `lua_tostring` converts one in place, and mlua's
-    // `Option<String>` coercion follows it.
+    // Insert: a nil is a no-op, not an error, since the reference reads the argument through
+    // `lua_tostring`, which answers NULL for nil; stock `LootFrame.lua:152` inserts a coin row's
+    // nil link unguarded. A number inserts its digits.
     m.set(
         "Insert",
         lua.create_function(|lua, (this, s): (Table, Option<mlua::Value>)| {
@@ -126,18 +97,11 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // **No `HasFocus`.** 1.12's EditBox table registers the two setters above and no getter at
-    // all, and an addon that wants the answer keeps its own flag around `SetFocus`/`ClearFocus` —
-    // `pfQuest/browser.lua:760` documents exactly that and ships the workaround. Ours was an
-    // unexplained superset a feature-detecting addon would take the wrong branch on (1188, and
-    // the census that removed it, 2142). Host-side, the focus cell reads back through
-    // [`crate::script::UiScript::focused_editbox_name`].
+    // No `HasFocus`: 1.12's EditBox table has these two setters and no getter, and addons keep
+    // their own flag.
 
-    // GetInputLanguage() / ToggleInputLanguage() — `0x799550` / `0x799610`, the edit box's
-    // **IME** language, not the chat language: `ChatEdit_OnInputLanguageChanged` shows
-    // `INPUT_<name>` on the box's language button, and the toggle is what a Korean client
-    // flips between its two input modes. On a client with no IME the answer is the Roman
-    // alphabet and the toggle moves nothing; benilla has no IME.
+    // GetInputLanguage/ToggleInputLanguage (`0x799550`/`0x799610`): the IME's input language, not
+    // the chat language. With no IME, as here, the answer is "ROMAN" and the toggle does nothing.
     m.set(
         "GetInputLanguage",
         lua.create_function(|lua, this: Table| {
@@ -153,7 +117,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // HighlightText([start [, end]]) — defaults (0, -1) = select-all.
+    // HighlightText([start [, end]]): the defaults (0, -1) select all.
     m.set(
         "HighlightText",
         lua.create_function(
@@ -166,24 +130,16 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     m.set(
-        // `GetMaxLetters 0x79929f` — the read half, which we were missing. Not published off the
-        // `strings` hit alone (that is what put `SetUnit` on the wrong widget earlier today):
-        // `0x79929f` is the GETTER of `[widget+0x340]`, the same field the setter below writes,
-        // which is table-level evidence rather than a name that happens to be in the image.
-        //
+        // `GetMaxLetters` (`0x79929f`) reads the field `SetMaxLetters` writes.
         "GetMaxLetters",
         lua.create_function(|lua, this: Table| {
             with_editbox(lua, &this, |eb| eb.max_letters as i64)
         })?,
     )?;
     m.set(
-        // `SetMaxBytes 0x798f30` — `SetMaxLetters`'s sibling in every respect but the sentinel:
-        // the same EXACT count gate (`0x798fbc cmp eax,2`, the second of the four `lua_gettop`
-        // callers), the same raw coerce of the value, and a field of its own at `+0x33c` whose
-        // no-limit value is **-1** where `maxLetters`'s is 0 (`0x799012 jle` → `0x799022`; the
-        // ctor writes -1 at `0x7799df`). So a non-positive argument is unlimited, a positive one
-        // caps the buffer's BYTES. The stock StaticPopup_Show calls it for any entry carrying
-        // `maxBytes` — none of the reference's own 76 does, so the reach is an addon's (1960).
+        // `SetMaxBytes` (`0x798f30`) has `SetMaxLetters`'s exact count gate (`0x798fbc`) and raw
+        // coercion, but its no-limit value is -1 (`0x799012`; the ctor writes -1 at `0x7799df`):
+        // a non-positive argument is unlimited, a positive one caps the bytes.
         "SetMaxBytes",
         lua.create_function(|lua, (this, args): (Table, mlua::MultiValue)| {
             let args: Vec<Value> = args.into_iter().collect();
@@ -200,30 +156,16 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
     m.set(
-        // The read half: -1 while unlimited, the reference's own stored sentinel.
+        // -1 while unlimited, the reference's stored sentinel.
         "GetMaxBytes",
         lua.create_function(|lua, this: Table| {
             with_editbox(lua, &this, |eb| eb.max_bytes.map_or(-1, |n| n as i64))
         })?,
     )?;
     m.set(
-        // `SetMaxLetters 0x799110` — one of only FOUR widget bindings in the whole registrar that
-        // calls `lua_gettop` (`0x6f3070`), and its gate is EXACT: `cmp eax,2` (`0x79919c`). So the
-        // count is checked and the type is not, which is the opposite of the usual pairing and the
-        // reason this needs its own body:
-        //
-        //   SetMaxLetters()           -> RAISES `Usage:` (too few)
-        //   SetMaxLetters(50, 60)     -> RAISES `Usage:` (too MANY — an exact gate, not a minimum)
-        //   SetMaxLetters(nil)        -> completes, stores 0
-        //   SetMaxLetters("12")       -> completes, stores 12 (a numeric string coerces)
-        //   SetMaxLetters({})         -> completes, stores 0
-        //
-        // and **0 is "no limit"**, not "no letters": the insert path's trim block is skipped
-        // whole on zero (`0x77c085 test edi,edi; je`), which is what `max_letters == 0` already
-        // means here. So `SetMaxLetters(nil)` is `SetMaxLetters(0)` is unlimited — aux-addon's
-        // `gui/core.lua:288` writes exactly that, and benilla raised on it and killed the addon at
-        // load. (Its neighbour `SetMaxBytes` uses **-1** for the same idea; two adjacent fields,
-        // two different sentinels.)
+        // `SetMaxLetters` (`0x799110`) checks the count exactly, `lua_gettop` (`0x6f3070`) against
+        // 2 at `0x79919c`, and not the type: no argument or two raise `Usage:`, nil or `{}` store
+        // 0, `"12"` stores 12. 0 is no limit: the insert skips its trim on zero (`0x77c085`).
         "SetMaxLetters",
         lua.create_function(|lua, (this, args): (Table, mlua::MultiValue)| {
             let args: Vec<Value> = args.into_iter().collect();
@@ -233,14 +175,13 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                 ));
             }
             let n = crate::script::binding_abi::coerced_number(lua, args.first().cloned());
-            // `__ftol` truncates toward zero; a negative stores as itself there, but our field is
-            // a `usize` and the trim only ever tests `> 0`, so the two agree on every value that
-            // can change behaviour.
+            // Truncated toward zero like `__ftol`; the reference stores a negative as is, but its
+            // trim only acts above 0, so the clamp changes nothing.
             with_editbox(lua, &this, |eb| eb.max_letters = (n as i64).max(0) as usize)
         })?,
     )?;
-    // The submitted-line history (`historyLines`): FrameXML pushes each sent line
-    // (ChatEdit_AddHistory), UP/DOWN recall it (see `key_input`).
+    // The sent-line history (`historyLines`): `ChatEdit_AddHistory` pushes each line, Up and Down
+    // recall them.
     m.set(
         "AddHistoryLine",
         lua.create_function(|lua, (this, line): (Table, Option<String>)| {
@@ -267,7 +208,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             with_editbox(lua, &this, |eb| eb.history_max as i64)
         })?,
     )?;
-    // SetBlinkSpeed/GetBlinkSpeed — the caret half-period (`E+0x370`, XML `blinkSpeed`; ctor 0.5).
+    // SetBlinkSpeed/GetBlinkSpeed: the caret half-period (XML `blinkSpeed`, 0.5 s by default).
     m.set(
         "SetBlinkSpeed",
         lua.create_function(|lua, (this, s): (Table, f32)| {
@@ -309,9 +250,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok((ins[0], ins[1], ins[2], ins[3]))
         })?,
     )?;
-    // GetNumLetters: the LETTER count — `0x7992c0` walks the class array (`0x77bc80`), which
-    // counts classes 2, 3 and 6 only, so escapes are free and a 43-byte item link reports 9
-    // (decision 1077). Not bytes, and not chars either.
+    // GetNumLetters (`0x7992c0`): the class array's letters (`0x77bc80`), classes 2, 3 and 6 only,
+    // so escapes are free and a 43-byte item link counts 9.
     m.set(
         "GetNumLetters",
         lua.create_function(|lua, this: Table| {
@@ -321,33 +261,17 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The config flags. All four mirror the live API. The fifth flag — bit4, the XML's
-    // `ignoreArrows` — is NOT here: its Lua surface is `SetAltArrowKeyMode`/`GetAltArrowKeyMode`
-    // below, which take a different argument coercion and answer a number rather than a boolean,
-    // so it cannot share this loop. benilla used to register a `SetIgnoreArrows` "convenience"
-    // for the loader to drive; 5875 has no such method (the 48-entry table
-    // `[0x87bb68, 0x87bce8)` carries no entry whose name contains "Ignore"), so publishing it was
-    // exactly the error decision 1189 names — and it stood in for the two real names, which were
-    // missing. The loader drives the XML attribute through `SetAltArrowKeyMode` now.
-    // ── SetAltArrowKeyMode / GetAltArrowKeyMode (`0x7996e0` / `0x799790`) ────────────────────
+    // The XML's fifth flag, `ignoreArrows`, is `SetAltArrowKeyMode` in Lua; 1.12 has no
+    // `SetIgnoreArrows` (the 48-entry table `[0x87bb68, 0x87bce8)`).
     //
-    // **The setter's argument is `GetBoolOrDefault(L, 2, default = 1)`** (`0x6f1c10`), not Lua
-    // truthiness and not a plain numeric coercion — `0x7996e0` pushes the default `1` before the
-    // call, so **an absent argument ENABLES** the mode. `nil` disables; a number goes through
-    // `__ftol` so `0` and `0.5` are false and `-1` is true; `""` matches nothing in the
-    // off/disabled/on/enabled chain and falls to the default, so it ENABLES; `"0"` disables.
-    // [`crate::script::binding_abi::bool_or_default`] already models every arm.
-    //
-    // **The getter answers the NUMBER 1 or nil**, never a boolean (`0x799815`: the set arm pushes
-    // the double 1.0 via `0x6f3810`, the clear arm pushes nil via `0x6f37f0`) — the same idiom as
-    // `IsShiftKeyDown`. An addon writing `if box:GetAltArrowKeyMode() then` reads either the same;
-    // one writing `== 1` only reads the number.
+    // SetAltArrowKeyMode (`0x7996e0`) reads `GetBoolOrDefault` (`0x6f1c10`) with default 1: no
+    // argument enables, nil disables, a number truncates (0 and 0.5 off, -1 on), `""` takes the
+    // default and `"0"` disables. GetAltArrowKeyMode (`0x799790`) answers the number 1 or nil,
+    // never a boolean (`0x799815`).
     m.set(
         "SetAltArrowKeyMode",
         lua.create_function(|lua, (this, args): (Table, mlua::MultiValue)| {
-            // `MultiValue`, not `Value`, because the reference DISTINGUISHES absent from nil here
-            // and mlua's `Value` cannot: `0x7996e0` pushes the default `1` before the call, so
-            // `SetAltArrowKeyMode()` enables while `SetAltArrowKeyMode(nil)` disables.
+            // `MultiValue`, since a `Value` cannot tell no argument (on) from nil (off).
             let args: Vec<Value> = args.into_iter().collect();
             let on = crate::script::binding_abi::bool_or_default(args.first(), true);
             with_editbox(lua, &this, |eb| eb.alt_arrow_key_mode = on)?;
@@ -370,9 +294,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                 let on = !matches!(v, Value::Nil | Value::Boolean(false));
                 with_editbox(lua, &this, |eb| set(eb, on))?;
                 if refresh_justify {
-                    // The text-anchoring law reads multiLine (TOP vs MIDDLE), and the loader
-                    // wires the declared `<FontString>` BEFORE the editbox flags (LoadXML order
-                    // 5·b vs 5b) — re-seat an already-wired region so `multiLine="true"` lands.
+                    // A multi-line box anchors its text TOP, else MIDDLE, and the loader wires the
+                    // `<FontString>` before the flags, so re-seat it.
                     super::refresh_text_region_justify(lua, &this)?;
                 }
                 Ok(())
@@ -386,43 +309,14 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// **The font block — entries #0–#15 of the EditBox method table**, and the largest single gap the
-/// per-kind widget-method census found in the 218-addon corpus (decision 1229).
-///
-/// `EditBox` is one of the six text-bearing types, so it re-declares the whole font block in its own
-/// flat table (`.data 0x87bb68`, 48 entries, count read from `mov edx,0x30` at `0x799ab5`; there is
-/// no `FontInstance` class in the 1.12 Lua chain). We had written every one of these verbs already —
-/// on `FontString` and on the `<Font>` object — and never wired them to the kind that wanted them.
-/// The census row is `63 EditBox:SetFontObject (on Texture, FontString)`, and its `(on …)` tail is
-/// exactly that: *a verb we have, on the wrong kinds*.
-///
-/// **The 63 is one library, not 63 independent addons.** Every one of those call sites is the same
-/// three lines of an embedded `Dewdrop-2.0.lua` —
-/// ```lua
-/// local editBox = CreateFrame("EditBox", nil, editBoxFrame)
-/// editBoxFrame.editBox = editBox
-/// editBox:SetFontObject(ChatFontNormal)
-/// ```
-/// — vendored into 63 addon folders (65 copies of the file: `FuBar` and its ~50 plugins, `BigWigs`,
-/// `AtlasLoot`, `oRA2`, …). One library replicated, so 63 chances to hit the *same* next wall
-/// (decision 1207).
-///
-/// Ten of the sixteen are the shared block and come from [`super::super::font_block`], which carries
-/// the per-verb byte evidence and the return-shape traps. Two are deliberately absent and four are
-/// installed here:
-///
-/// - **`SetSpacing`/`GetSpacing` (#10–#11) are NOT installed.** Nothing in this client models line
-///   spacing, so they could only store a number no renderer reads — the silently-ignored-setter
-///   failure of 1203/1205/1211 — while their absence raises a nil-value call that names itself.
-///   Corpus demand is zero: `:SetSpacing(`/`:GetSpacing(` appear in **0** of 218 addons.
-///   `script::font` withholds the same pair for the same reason.
-/// - **The justify four (#12–#15) are installed here**, against the box's own
-///   [`EditBoxState::justify`] word rather than its text region — the field's doc has the why (our
-///   editbox draw law seats that region LEFT unconditionally) and states the divergence.
+/// The font block, entries #0-#15 of the EditBox's own 48-entry method table (`0x87bb68`, count
+/// at `0x799ab5`); 1.12 has no `FontInstance` class, so each text-bearing kind declares it. Ten
+/// come from [`super::super::font_block`]. `SetSpacing`/`GetSpacing` (#10-#11) are not installed:
+/// nothing renders line spacing, and a missing method raises by name. The justify four (#12-#15)
+/// act on the box's own [`EditBoxState::justify`] word, not its text region.
 fn install_font_block(lua: &Lua, m: &Table) -> mlua::Result<()> {
-    // Every font method acts on the box's implicit FontString: each binding's shim loads
-    // `[this+0x324]` and hands it to the shared implementation, and that offset is
-    // `EditBoxState::text_region`. Created on demand, exactly like every other text-touching path.
+    // Every font method acts on the box's implicit FontString (`[this+0x324]`, our
+    // `text_region`), created on demand.
     crate::script::font_block::install(
         lua,
         m,
@@ -433,18 +327,9 @@ fn install_font_block(lua: &Lua, m: &Table) -> mlua::Result<()> {
         "EditBox",
     )?;
 
-    // SetJustifyH("LEFT"|"CENTER"|"RIGHT") / SetJustifyV("TOP"|"MIDDLE"|"BOTTOM") → 0 values.
-    //
-    // Two verified traps, both of which a plausible implementation gets wrong. This table was the
-    // only one that got them right; the FontString and `<Font>` copies coerced anything unknown to
-    // CENTER/MIDDLE until 1237 lifted this law into [`crate::justify`], which all three now share:
-    //  · an **unrecognised token RAISES** `Usage: %s:SetJustifyH("justify")` (`0x87c77c`), rather
-    //    than falling back to a default;
-    //  · a token from the **other axis** parses fine and then masks to nothing — `SetJustifyH("TOP")`
-    //    yields 0x08, `0x08 & 0x07 == 0`, so it CLEARS justifyH and `GetJustifyH()` answers
-    //    `"UNKNOWN"`. No error either way.
-    //
-    // `AceGUIWidget-Slider.lua:210` (`editbox:SetJustifyH("CENTER")`, three addons) is the demand.
+    // SetJustifyH/SetJustifyV return nothing. An unknown token raises `Usage:` (`0x87c77c`); a
+    // token of the other axis parses and masks to nothing, so `SetJustifyH("TOP")` clears justifyH
+    // and `GetJustifyH()` answers "UNKNOWN".
     for (name, mask) in [
         ("SetJustifyH", EditBoxState::JUSTIFY_H_MASK),
         ("SetJustifyV", EditBoxState::JUSTIFY_V_MASK),
@@ -459,8 +344,8 @@ fn install_font_block(lua: &Lua, m: &Table) -> mlua::Result<()> {
             })?,
         )?;
     }
-    // GetJustifyH()/GetJustifyV() → exactly 1 string, the first set bit's token in the reference's
-    // own table order, or the literal "UNKNOWN".
+    // GetJustifyH/GetJustifyV: one string, the first set bit's token in the reference's table
+    // order, else "UNKNOWN".
     for (name, mask) in [
         ("GetJustifyH", EditBoxState::JUSTIFY_H_MASK),
         ("GetJustifyV", EditBoxState::JUSTIFY_V_MASK),
@@ -475,10 +360,10 @@ fn install_font_block(lua: &Lua, m: &Table) -> mlua::Result<()> {
     Ok(())
 }
 
-/// A `Set<Flag>` name paired with the EditBoxState mutator it drives (Lua truthiness).
+/// A `Set<Flag>` method name and the field write it drives.
 type FlagSetter = (&'static str, fn(&mut EditBoxState, bool));
 
-/// The config-flag setters, in one place so the loader and the Lua surface share the list.
+/// The four config-flag setters, each taking Lua truthiness.
 fn flag_setters() -> [FlagSetter; 4] {
     [
         ("SetAutoFocus", |eb, on| eb.auto_focus = on),
diff --git a/crates/benilla-ui/src/script/editbox/seam.rs b/crates/benilla-ui/src/script/editbox/seam.rs
index 7926c997..c9147761 100644
--- a/crates/benilla-ui/src/script/editbox/seam.rs
+++ b/crates/benilla-ui/src/script/editbox/seam.rs
@@ -1,21 +1,17 @@
-//! The EditBox text-UI seam — the `impl UiScript` surface the host drives each frame: the
-//! advance-table round trip (request → host measures → answer), the caret/selection/scroll
-//! geometry derived from it, and the clipboard pair. Split beside its concern per the layout.rs
-//! pattern (the measure-seam siblings live there).
+//! The EditBox seam the host drives each frame: the advance-table round trip, the caret,
+//! selection and scroll geometry derived from it, and the clipboard pair.
 
 use crate::script::{types, UiScript};
 use crate::widget::KindState;
 
 impl UiScript {
-    /// The focused EditBox's advance-table request (the metrics half of the mouse/selection law):
-    /// `Some` when the box's DISPLAY string needs its per-byte cumulative widths measured (text or
-    /// font changed since the last answer). Answer via [`Self::set_editbox_advances`] before
-    /// [`Self::focused_editbox_text_ui`] — an empty display settles engine-side without a trip.
+    /// The focused EditBox's request to measure its display string's per-byte cumulative widths,
+    /// when its text, font, scale or wrap width changed; an empty display needs no trip. Answer it
+    /// with [`Self::set_editbox_advances`] before [`Self::focused_editbox_text_ui`].
     pub fn editbox_advances_request(&mut self) -> Option<types::EditBoxAdvanceRequest> {
         use std::hash::{Hash, Hasher};
         let h = self.model_mut().focused_editbox?;
-        // Materialize the lazy text region first — its resolved font is the table's identity
-        // (a just-focused CreateFrame'd box has none until here).
+        // The lazy text region first: its font keys the table, and a new box has none until now.
         let rh = super::ensure_text_region(self.lua(), h)?;
         let mut model = self.model_mut();
         let (display, multi_line) = match model.arena.frame(h).map(|f| &f.kind_state) {
@@ -26,15 +22,13 @@ impl UiScript {
         let font = d.and_then(|d| d.font_path.clone());
         let height = d.and_then(|d| d.font_height);
         let outline = d.map(|d| d.outline).unwrap_or_default();
-        // The box's effective_scale rides the request ([`types::EditBoxAdvanceRequest::scale`]):
-        // the host measures at the drawn raster size so the advances land on the drawn glyphs.
+        // The host measures at the drawn raster size, so the advances land on the drawn glyphs.
         let scale = model
             .arena
             .frame(h)
             .map(|f| f.effective_scale)
             .unwrap_or(1.0);
-        // A multiline box also needs its wrap rows — at the text region's resolved width, the
-        // same width the draw wraps at. Folded into the cache key: a resize re-wraps.
+        // A multi-line box wraps at the text region's width, as the draw does; a resize re-keys.
         let wrap_width = multi_line
             .then(|| {
                 model
@@ -79,10 +73,8 @@ impl UiScript {
         })
     }
 
-    /// Answer an [`Self::editbox_advances_request`]: the per-byte cumulative laid-out widths of
-    /// the requested display string (len+1 entries, `[0] = 0`), plus the wrapped-row starts and
-    /// row pitch (single-line: `rows = [0]`, `cell_h` the line em — only a multiline box reads
-    /// them, but the answer is uniform).
+    /// Answer an [`Self::editbox_advances_request`]: the cumulative widths (len+1 entries from 0),
+    /// the wrapped-row starts and the row pitch, which only a multi-line box reads.
     pub fn set_editbox_advances(
         &mut self,
         id: u32,
@@ -103,13 +95,9 @@ impl UiScript {
         }
     }
 
-    /// The focused EditBox's text-UI geometry for this frame (caret/highlight geometry is left to
-    /// the host): which Text quad is the box's (`target`), the scroll window to draw
-    /// (`display_from`), and the caret/selection x-spans within it — all advance-table-derived.
-    /// Clamps the scroll window against the text region's resolved width first (the
-    /// scroll-into-view invariant, `0x77da80`). `None` when nothing is focused, the box is
-    /// off-screen, or the advance table hasn't been answered yet (text still draws; the caret and
-    /// highlight sit that frame out).
+    /// The focused EditBox's text geometry this frame: its text quad, the scroll window and the
+    /// caret and selection spans in it, after scrolling the caret into view (`0x77da80`). `None`
+    /// until the advance table is answered: the text draws, without caret or highlight.
     pub fn focused_editbox_text_ui(&mut self) -> Option<types::EditBoxTextUi> {
         let h = {
             let model = self.model_mut();
@@ -120,12 +108,10 @@ impl UiScript {
             }
             h
         };
-        // Focus means "about to type": materialize the lazy text region (the same lazy
-        // constructor `sync_text_region` uses), so an empty just-focused box has a caret home.
+        // Materialize the lazy text region, so an empty, just-focused box has a caret home.
         let rh = super::ensure_text_region(self.lua(), h)?;
         let mut model = self.model_mut();
-        // The text region's resolved width; an unanchored region (a CreateFrame'd box without
-        // insets) draws over its owner, so the frame's own rect is its width.
+        // An unanchored text region draws over its owner, so the frame's own width stands in.
         let avail = model
             .region_resolved
             .get(&rh)
@@ -141,12 +127,11 @@ impl UiScript {
             return None;
         }
         if display.is_empty() {
-            // Trivial table — no host trip needed for an empty box.
             eb.advances = vec![0.0];
             eb.rows = vec![0];
         }
-        // Keep the caret inside the window, leaving it a pixel to stand in at the right edge
-        // (multiline: pins the window to 0 — the box wraps instead).
+        // Keep the caret inside the window with room at the right edge; a multi-line box wraps
+        // instead, its window pinned at 0.
         eb.clamp_scroll((avail - 2.0).max(0.0));
         let from = eb.scroll_start.min(display.len());
         let origin = eb.advances[from];
@@ -158,8 +143,7 @@ impl UiScript {
         );
         let (caret_row, caret_x, selection) = if eb.multi_line {
             let (row, x) = eb.caret_row_x(cursor_d);
-            // The selection as per-row spans: each touched row contributes the intersection of
-            // its byte range with [da, db), x-measured from the row's own origin.
+            // One span per touched row, its overlap with [da, db), measured from the row's origin.
             let mut spans = Vec::new();
             if da != db {
                 for i in 0..eb.rows.len() {
@@ -197,9 +181,8 @@ impl UiScript {
         })
     }
 
-    /// Ctrl/Cmd+C for the focused EditBox: the selected substring for the OS clipboard (`None` =
-    /// no selection; a password box yields its mask run, never the real text — the client's fixed
-    /// placeholder `0x882748`).
+    /// Ctrl/Cmd+C: the focused EditBox's selection for the OS clipboard; a password box yields its
+    /// mask run, never the text, where the client copies the empty string (`0x882748`).
     pub fn editbox_copy(&mut self) -> Option<String> {
         super::copy_selection(self.lua())
     }
@@ -209,11 +192,9 @@ impl UiScript {
         super::cut_selection(self.lua())
     }
 
-    /// Push one submitted line into the named box's recall history — the ref's
-    /// `ChatEdit_AddHistory` slot (the canonical slash line, added by the app's router AFTER it
-    /// parses the send; decision 0301). By name, not focus: the submit pipeline is asynchronous,
-    /// so by the time the router runs, the box has already cleared and dropped focus. Returns
-    /// `false` when `box_name` names no live EditBox.
+    /// Push a sent line, as its canonical slash line, into the named box's history where the
+    /// reference calls `ChatEdit_AddHistory`. By name: the router runs after the box has cleared
+    /// and lost focus. `false` when `box_name` is no live EditBox.
     pub fn editbox_add_history(&mut self, box_name: &str, line: &str) -> bool {
         let lua = self.lua();
         let Ok(t) = lua.globals().get::<mlua::Table>(box_name) else {
diff --git a/crates/benilla-ui/src/script/editbox/tests.rs b/crates/benilla-ui/src/script/editbox/tests.rs
index 9c2a571b..b4601a17 100644
--- a/crates/benilla-ui/src/script/editbox/tests.rs
+++ b/crates/benilla-ui/src/script/editbox/tests.rs
@@ -1,8 +1,4 @@
-//! Rust-driven tests of the EditBox runtime: focus acquisition + routing, text/cursor/
-//! selection editing, the specialized script fires, caps, numeric/password, and text-region sync.
-//! Frames are built programmatically via `CreateFrame("EditBox", …)` and driven through the public
-//! keyboard API (`char_input`/`key_input`/`editbox_action`/`has_keyboard_focus`) and the Lua
-//! method surface.
+//! EditBox runtime tests, driven through the public keyboard API and the Lua methods.
 
 use crate::script::{EditAction, EditUnit, QuadContent, UiScript};
 
@@ -10,7 +6,6 @@ fn script() -> UiScript {
     UiScript::new().expect("construct UiScript")
 }
 
-/// The display text of the (single) text quad an extract produces, if any.
 fn text_quad(s: &UiScript) -> Option<String> {
     s.extract().into_iter().find_map(|q| match q.content {
         QuadContent::Text { text, .. } => text,
@@ -20,21 +15,16 @@ fn text_quad(s: &UiScript) -> Option<String> {
 
 // ── focus acquisition + routing ─────────────────────────────────────────────────────────────
 
-/// **The self-acquire path**, path 2 of the two: a box that has had no show TRANSITION (created
-/// already visible, so `visibility_focus` never runs for it) still takes the keyboard on the first
-/// key or char event, and processes that same event. Path 1, focus-on-show, is
-/// [`an_autofocus_box_takes_the_keyboard_when_it_is_shown`] below — this test's name used to assert
-/// its absence, which stopped being true at decision 1686.
+/// A box created visible has had no show transition, yet with autoFocus it takes the keyboard on
+/// the first key or char and processes that event.
 #[test]
 fn an_autofocus_box_self_acquires_on_the_first_event() {
     let mut s = script();
     s.run(r#"E = CreateFrame("EditBox", "E"); E:SetAutoFocus(true)"#)
         .unwrap();
-    // No show transition has run for this box, so nothing owns the keyboard yet.
     assert!(!s.has_keyboard_focus());
     assert_eq!(s.focused_editbox_name(), None);
 
-    // The first char self-acquires focus AND processes that same event.
     assert!(
         s.char_input("a"),
         "an autoFocus box consumes the acquiring event"
@@ -44,9 +34,8 @@ fn an_autofocus_box_self_acquires_on_the_first_event() {
     assert_eq!(s.eval::<String>("return E:GetText()").unwrap(), "a");
 }
 
-/// **An `autoFocus` box takes the keyboard when it is shown** — the OnShow vtable override
-/// (`0x81c910` slot +0x30, `0x77a750`), missing here until decision 1686. Gated on nothing else
-/// holding focus, and the gate is the whole of it — no topmost/best choice.
+/// The OnShow override (`0x77a750`, vtable `0x81c910` slot +0x30) focuses an autoFocus box when
+/// nothing holds focus; there is no topmost or best choice.
 #[test]
 fn an_autofocus_box_takes_the_keyboard_when_it_is_shown() {
     let s = script();
@@ -67,7 +56,7 @@ fn an_autofocus_box_takes_the_keyboard_when_it_is_shown() {
         "showing an autoFocus box focuses it",
     );
 
-    // Hiding the box that holds the keyboard releases it (the mirror override, slot +0x34).
+    // Hiding the focused box releases the keyboard (the mirror override, slot +0x34).
     s.run("E:Hide()").unwrap();
     assert!(
         !s.has_keyboard_focus(),
@@ -76,9 +65,8 @@ fn an_autofocus_box_takes_the_keyboard_when_it_is_shown() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The two gates, each shown to bite. A box that opted out does not take the keyboard on show; and
-/// a box that would have is refused while another still holds it — the reference's
-/// `if ([0xcf4dc8] == 0 && (flags & 1))`, both halves.
+/// Focus on show takes both halves of `[0xcf4dc8] == 0 && (flags & 1)`: no focus held, and
+/// autoFocus.
 #[test]
 fn the_show_focus_is_refused_without_autofocus_or_with_the_keyboard_taken() {
     let s = script();
@@ -97,7 +85,6 @@ fn the_show_focus_is_refused_without_autofocus_or_with_the_keyboard_taken() {
         "autoFocus=false is an opt-out that holds on show",
     );
 
-    // Now give the keyboard away, and show an autoFocus box into an occupied focus.
     s.run(
         r#"
         HOLDER = CreateFrame("EditBox", "Holder")
@@ -114,9 +101,7 @@ fn the_show_focus_is_refused_without_autofocus_or_with_the_keyboard_taken() {
         "a shown autoFocus box does not steal a focus that is already held",
     );
 
-    // And hiding a box that does NOT hold the keyboard leaves it where it is — `0x77e410`'s own
-    // per-box guard (`cmp ecx,eax; jne ret`), which is what makes the override's unconditional
-    // tail-jmp harmless.
+    // Hiding a box without the keyboard leaves focus alone (`0x77e410`'s per-box guard).
     s.run("LATE:Hide()").unwrap();
     assert_eq!(
         s.focused_editbox_name().as_deref(),
@@ -129,9 +114,7 @@ fn the_show_focus_is_refused_without_autofocus_or_with_the_keyboard_taken() {
 #[test]
 fn non_autofocus_unfocused_box_ignores_input() {
     let mut s = script();
-    // `SetAutoFocus(false)` explicitly: the ctor's `flags = 1` leaves autoFocus **ON** by default
-    // (`0x779a29`/`0x779a2e`, decision 1686), so a bare `CreateFrame("EditBox")` is an autoFocus
-    // box and would self-acquire on the first char. This test is about the other kind.
+    // The ctor leaves autoFocus on (`0x779a29`/`0x779a2e`), so a bare box would self-acquire.
     s.run(r#"E = CreateFrame("EditBox", "E"); E:SetAutoFocus(false)"#)
         .unwrap();
     assert!(!s.char_input("a"), "no focus, no autoFocus → not consumed");
@@ -149,7 +132,6 @@ fn focused_box_consumes_everything() {
     let mut s = script();
     s.run(r#"E = CreateFrame("EditBox", "E"); E:SetFocus()"#)
         .unwrap();
-    // Empty text: these do nothing, but a focused box still consumes them.
     assert!(s.editbox_action(EditAction::Move {
         unit: EditUnit::Char,
         back: true,
@@ -210,7 +192,6 @@ fn click_focuses_regardless_of_autofocus_and_transition_order_is_lost_then_gaine
     .unwrap();
     s.resolve();
 
-    // Neither box has autoFocus, yet a click focuses each.
     s.mouse_button(50.0, 10.0, "LeftButton", true);
     s.mouse_button(50.0, 10.0, "LeftButton", false);
     assert_eq!(s.focused_editbox_name().as_deref(), Some("A"));
@@ -226,10 +207,8 @@ fn click_focuses_regardless_of_autofocus_and_transition_order_is_lost_then_gaine
 
 // ── text buffer + editing + OnTextChanged/OnTextSet ─────────────────────────────────────────
 
-/// **`OnTextChanged` is deferred and coalesced** (decision 1831). An edit only raises the
-/// `textChanged` dirty bit; the fire belongs to the drain (`0x77d3e0`) that the box's own OnUpdate
-/// runs. So three typed characters are three marks on ONE box and produce exactly ONE fire — this
-/// test asserted three before the law was checked.
+/// An edit only raises the box's `textChanged` bit; `OnTextChanged` fires once, at the drain its
+/// OnUpdate runs (`0x77d3e0`).
 #[test]
 fn typing_coalesces_into_one_deferred_ontextchanged() {
     let mut s = script();
@@ -261,15 +240,12 @@ fn typing_coalesces_into_one_deferred_ontextchanged() {
     );
     assert_eq!(s.eval::<String>("return seen").unwrap(), "abc");
 
-    // Nothing is pending now, so a second drain fires nothing.
     s.tick(0.0);
     assert_eq!(s.eval::<i64>("return changed").unwrap(), 1);
 }
 
-/// The two fires part company (decision 1831): **`OnTextSet` is synchronous, inside `SetText`
-/// itself** (`0x77be6b`), while `OnTextChanged` waits for the drain. The equality short-circuit
-/// still suppresses both. So writing "hi", "hi", "bye" before any drain logs two `set`s and then a
-/// SINGLE `changed` carrying only the last value — `A → B` coalesces.
+/// `OnTextSet` fires inside `SetText` (`0x77be6b`), `OnTextChanged` at the drain; an unchanged
+/// text fires neither.
 #[test]
 fn set_text_fires_ontextset_at_once_and_ontextchanged_at_the_drain() {
     let mut s = script();
@@ -356,14 +332,13 @@ fn paste_inserts_at_the_cursor_and_replaces_the_selection() {
     "#,
     )
     .unwrap();
-    // Cursor sits at end after SetText → paste appends.
+    // SetText leaves the cursor at the end, so the paste appends.
     assert!(s.paste("CD"), "focused box consumes the paste");
     assert_eq!(s.eval::<String>("return E:GetText()").unwrap(), "abCD");
-    // Select-all then paste replaces the whole selection.
     s.run("E:HighlightText(0, -1)").unwrap();
     assert!(s.paste("xyz"));
     assert_eq!(s.eval::<String>("return E:GetText()").unwrap(), "xyz");
-    // Both pastes marked the same box, so the drain owes exactly one fire — not one per paste.
+    // Both pastes marked the one box, so the drain fires once.
     assert_eq!(s.eval::<i64>("return changed").unwrap(), 0);
     s.tick(0.0);
     assert_eq!(s.eval::<i64>("return changed").unwrap(), 1);
@@ -390,7 +365,6 @@ fn paste_strips_newlines_in_a_single_line_box_but_keeps_them_when_multiline() {
         "onetwothree"
     );
 
-    // Multi-line box: the newline survives (a tab is still a dropped control char).
     let mut s = script();
     s.run(r#"E = CreateFrame("EditBox", "E"); E:SetMultiLine(true); E:SetFocus()"#)
         .unwrap();
@@ -400,14 +374,12 @@ fn paste_strips_newlines_in_a_single_line_box_but_keeps_them_when_multiline() {
 
 #[test]
 fn paste_honors_max_letters_and_numeric() {
-    // maxLetters trims the paste from the end.
     let mut s = script();
     s.run(r#"E = CreateFrame("EditBox", "E"); E:SetMaxLetters(3); E:SetFocus()"#)
         .unwrap();
     assert!(s.paste("abcdef"));
     assert_eq!(s.eval::<String>("return E:GetText()").unwrap(), "abc");
 
-    // numeric aborts a paste that carries any non-digit (matching the typed-insert rule).
     let mut s = script();
     s.run(r#"E = CreateFrame("EditBox", "E"); E:SetNumeric(true); E:SetFocus()"#)
         .unwrap();
@@ -473,7 +445,7 @@ fn enter_escape_tab_space_fire_their_slots() {
     )
     .unwrap();
     assert!(s.key_input("ENTER")); // single-line → OnEnterPressed
-    assert!(s.key_input("ESCAPE")); // fires, does NOT release focus
+    assert!(s.key_input("ESCAPE"));
     assert_eq!(
         s.focused_editbox_name().as_deref(),
         Some("E"),
@@ -484,7 +456,7 @@ fn enter_escape_tab_space_fire_their_slots() {
 
     let log: Vec<String> = s.eval("return log").unwrap();
     assert_eq!(log, vec!["enter", "escape", "tab", "space"]);
-    // ENTER on a single-line box must NOT insert; only the space landed.
+    // Enter on a single-line box inserts nothing; only the space landed.
     assert_eq!(s.eval::<String>("return E:GetText()").unwrap(), " ");
 }
 
@@ -506,23 +478,10 @@ fn multiline_enter_inserts_a_newline_without_onspacepressed() {
     assert_eq!(s.eval::<i64>("return spaces").unwrap(), 0);
 }
 
-/// **Alt-arrow mode: the two real verbs, and the flag they share with the XML attribute.**
-///
-/// The reference settles four things this pins:
-///
-///  · 5875 has **no `SetIgnoreArrows`** — the 48-entry EditBox method table
-///    `[0x87bb68, 0x87bce8)` carries `SetAltArrowKeyMode`/`GetAltArrowKeyMode` at 46/47 and no
-///    entry whose name contains "Ignore". benilla published the invented name for two rounds and
-///    was missing both real ones.
-///  · The XML attribute `ignoreArrows` and the Lua verbs drive **one** flag (`[E+0x318] & 0x10`).
-///  · The setter's argument is `GetBoolOrDefault(L, 2, default = 1)` (`0x6f1c10`), not Lua
-///    truthiness — an **absent** argument ENABLES, `""` ENABLES, `0` and `"0"` disable.
-///  · The getter answers the **number 1 or nil**, never a boolean.
-///
-/// And the negative that matters: the engine core no longer swallows anything. The gate is on the
-/// KEY and lives in the host (`UiKeyboardCapture::arrows_fall_through`), so an `EditAction` that
-/// arrives here moves the caret whatever the flag says — it only ever arrives when ALT was held or
-/// the key was not an arrow.
+/// The method table `[0x87bb68, 0x87bce8)` has `SetAltArrowKeyMode`/`GetAltArrowKeyMode` at 46/47
+/// and no `SetIgnoreArrows`; the XML `ignoreArrows` is the same flag (`[E+0x318] & 0x10`). The
+/// gate is on the key, in the host (`UiKeyboardCapture::arrows_fall_through`), so an `EditAction`
+/// that arrives here acts whatever the flag says.
 #[test]
 fn alt_arrow_key_mode_is_the_flag_and_the_engine_core_no_longer_swallows_moves() {
     let mut s = script();
@@ -535,13 +494,11 @@ fn alt_arrow_key_mode_is_the_flag_and_the_engine_core_no_longer_swallows_moves()
     )
     .unwrap();
 
-    // The invented name is gone.
     assert!(
         s.eval::<bool>("return E.SetIgnoreArrows == nil").unwrap(),
         "5875 has no SetIgnoreArrows — publishing it was decision 1189's error"
     );
 
-    // The getter: a number or nil, never a boolean.
     assert_eq!(
         s.eval::<Option<i64>>("return E:GetAltArrowKeyMode()")
             .unwrap(),
@@ -559,10 +516,10 @@ fn alt_arrow_key_mode_is_the_flag_and_the_engine_core_no_longer_swallows_moves()
         "the set arm pushes the double 1.0 (0x6f3810), not a boolean"
     );
 
-    // `GetBoolOrDefault(default = 1)`, arm by arm — three of these are backwards under Lua
-    // truthiness, which is why the coercion has its own helper.
+    // `GetBoolOrDefault` (`0x6f1c10`, default 1), arm by arm; three are backwards under Lua
+    // truthiness.
     for (arg, want) in [
-        ("", Some(1)),      // ABSENT -> the default 1 -> enabled
+        ("", Some(1)),      // absent -> the default 1 -> enabled
         ("nil", None),      // nil -> 0
         ("0", None),        // __ftol(0) -> false
         ("-1", Some(1)),    // __ftol(-1) != 0 -> true
@@ -579,8 +536,8 @@ fn alt_arrow_key_mode_is_the_flag_and_the_engine_core_no_longer_swallows_moves()
         );
     }
 
-    // The engine core does NOT swallow a Char move any more — the gate is on the key, upstream.
-    // `SetText` leaves the caret at the end, so one back-Char move puts it between 'b' and 'c'.
+    // A flagged box still acts on a Char move. `SetText` leaves the caret at the end, so one back
+    // move puts it between 'b' and 'c'.
     s.run(r#"E:SetAltArrowKeyMode(1) E:SetText("abc")"#)
         .unwrap();
     assert!(s.editbox_action(EditAction::Move {
@@ -599,8 +556,8 @@ fn alt_arrow_key_mode_is_the_flag_and_the_engine_core_no_longer_swallows_moves()
     );
 }
 
-/// The XML attribute is the same flag under its other name (`ignoreArrows` occurs once in the
-/// image, at `0x879b78`, with one xref: the attribute push at `0x77a13a`).
+/// The XML `ignoreArrows` is the same flag: its string (`0x879b78`) has one use, the attribute
+/// read at `0x77a13a`.
 #[test]
 fn the_ignore_arrows_xml_attribute_is_alt_arrow_key_mode() {
     let s = script();
@@ -640,20 +597,17 @@ fn get_number_parses_the_text() {
     s.run(r#"E = CreateFrame("EditBox", "E"); E:SetText("12.5")"#)
         .unwrap();
     assert_eq!(s.eval::<f64>("return E:GetNumber()").unwrap(), 12.5);
-    // Non-numeric text → 0.
     s.run(r#"E:SetText("hello")"#).unwrap();
     assert_eq!(s.eval::<f64>("return E:GetNumber()").unwrap(), 0.0);
 }
 
-// ── the EditBox override never fires generic OnChar/OnKeyDown ─────────────────────────────────
+// ── the generic OnChar and OnKeyDown ─────────────────────────────────────────────────────────
 
 #[test]
 fn typing_fires_the_generic_on_char_with_what_was_inserted() {
-    // **The half of the old law that was wrong** (corrected 2026-08-29; decision 1686).
-    // `CSimpleEditBox` has its own input vtable which does not chain to the base — but Insert
-    // itself fires the generic `OnChar` slot (`+0x180`) at `0x77c13c`, through the **varargs**
-    // firer `0x7026f0` with fmt `"%s"` and the spliced string as the argument; the family's
-    // other member is the fixed-arity firer `0x702690`.
+    // The box's input vtable does not chain to the base, but Insert fires the generic `OnChar`
+    // (`+0x180`) at `0x77c13c`, through the varargs firer `0x7026f0` (not the fixed-arity
+    // `0x702690`) with the inserted string.
     let mut s = script();
     s.run(
         r#"
@@ -673,7 +627,7 @@ fn typing_fires_the_generic_on_char_with_what_was_inserted() {
         "OnChar fires once, with the inserted string",
     );
 
-    // `SetText` is NOT an insert path and fires nothing — the seam the reference has too.
+    // `SetText` is not an insert and fires no `OnChar`, as in the reference.
     s.run(r#"E:SetText("zzz")"#).unwrap();
     assert_eq!(
         s.eval::<String>("return table.concat(got, ',')").unwrap(),
@@ -685,10 +639,8 @@ fn typing_fires_the_generic_on_char_with_what_was_inserted() {
 
 #[test]
 fn key_paths_never_fire_the_generic_on_key_down() {
-    // The surviving half: the box's own key-down vtable (`0x77b160`) handles the event and never
-    // chains to the base, so a focused box's typing does not also run a generic `OnKeyDown` bound
-    // on that same box. Only the `OnChar` half of the original claim was corrected — this one
-    // stands.
+    // The box's key-down handler (`0x77b160`) never chains to the base, so a generic `OnKeyDown`
+    // on the focused box does not fire.
     let mut s = script();
     s.run(
         r#"
@@ -710,7 +662,7 @@ fn key_paths_never_fire_the_generic_on_key_down() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-// ── history recall (`historyLines` / AddHistoryLine — decision 0288 P2) ──────────────────────
+// ── history recall (`historyLines`, AddHistoryLine) ──────────────────────────────────────────
 
 #[test]
 fn history_recall_walks_up_and_down_and_restores_the_draft() {
@@ -758,8 +710,8 @@ fn typing_ends_the_history_browse() {
     .unwrap();
     s.editbox_action(EditAction::HistoryPrev);
     assert_eq!(s.eval::<String>("return E:GetText()").unwrap(), "newer");
-    // A typed char turns the recalled line into an ordinary draft: the next UP starts a FRESH
-    // browse from the newest entry (stashing the edited line as the new draft).
+    // A typed char turns the recalled line into a draft: the next UP starts a fresh browse from
+    // the newest entry, stashing the edited line as the draft.
     s.char_input("!");
     assert_eq!(s.eval::<String>("return E:GetText()").unwrap(), "newer!");
     s.editbox_action(EditAction::HistoryPrev);
@@ -781,9 +733,8 @@ fn programmatic_set_text_keeps_the_browse_and_focus_gain_resets_it() {
     "#,
     )
     .unwrap();
-    // Recall the newest, then rewrite the box the way the chat live parse does on a slash
-    // recall ("/g two" → Guild + "two"). The browse walk must survive: the next UP lands on
-    // the OLDER entry, not back on the newest (the "history only goes back 1" bug).
+    // Rewrite the recalled line as the chat parser does ("/g two" → Guild + "two"); the next UP
+    // must reach the older entry, not the newest again.
     s.editbox_action(EditAction::HistoryPrev);
     assert_eq!(s.eval::<String>("return E:GetText()").unwrap(), "/g two");
     s.run(r#"E:SetText("two")"#).unwrap();
@@ -824,14 +775,14 @@ fn history_off_by_default_and_up_is_still_consumed() {
     let mut s = script();
     s.run(r#"E = CreateFrame("EditBox", "E"); E:SetText("t"); E:SetFocus()"#)
         .unwrap();
-    // No historyLines: AddHistoryLine is a no-op, UP consumed but inert (a focused box eats every
-    // key — both handlers `return 1` past the guard, `0x77a900`/`0x77b160`).
+    // No historyLines: AddHistoryLine does nothing, and UP is consumed but inert, since a focused
+    // box eats every key (both handlers return 1, `0x77a900`/`0x77b160`).
     s.run(r#"E:AddHistoryLine("x")"#).unwrap();
     assert!(s.editbox_action(EditAction::HistoryPrev));
     assert_eq!(s.eval::<String>("return E:GetText()").unwrap(), "t");
 }
 
-// ── SetTextInsets (0288 P2 — the header-driven text-rect shrink) ─────────────────────────────
+// ── SetTextInsets ────────────────────────────────────────────────────────────────────────────
 
 #[test]
 fn text_insets_shrink_the_text_region_rect() {
@@ -869,16 +820,13 @@ fn text_insets_shrink_the_text_region_rect() {
         (rect.bottom - 53.0).abs() < 0.01,
         "bottom inset 3: {rect:?}"
     );
-    // The getter echoes.
     let (l, r_, t, b) = s
         .eval::<(f32, f32, f32, f32)>("return E:GetTextInsets()")
         .unwrap();
     assert_eq!((l, r_, t, b), (15.0, 13.0, 2.0, 3.0));
 }
 
-// The FontInstance half an EditBox inherits in the client: SetTextColor tints the box's text
-// region (`ChatEdit_UpdateHeader` colors the typed text this way — its absence killed the chat
-// header chunk mid-run and left the /w insets stale, the caret-in-the-header bug).
+// SetTextColor tints the box's text region, as `ChatEdit_UpdateHeader` colours the typed text.
 #[test]
 fn set_text_color_tints_the_text_region() {
     let mut s = script();
@@ -912,8 +860,8 @@ fn set_text_color_tints_the_text_region() {
 
 // ── the host text-UI seam: advances, caret/selection geometry, mouse, clipboard ─────────────
 
-/// Build a focused 200×32 box at BOTTOMLEFT(100,50), resolve it, type `text`, and answer its
-/// advance table with a synthetic monospace 7 px/byte — the standard rig for the geometry tests.
+/// A focused 200×32 box at BOTTOMLEFT(100, 50) holding `text`, its advances answered at 7 px per
+/// byte.
 fn seam_rig(s: &mut UiScript, text: &str) {
     s.set_screen_size(800.0, 600.0);
     s.run(
@@ -940,8 +888,7 @@ fn answer_advances(s: &mut UiScript) {
     }
 }
 
-/// The seam reports caret geometry from the advance table, and vanishes with focus or
-/// visibility — the old prefix-string seam's laws, now in pixels.
+/// Caret geometry comes from the advance table, and there is none without focus or visibility.
 #[test]
 fn text_ui_reports_caret_geometry_and_focus() {
     let mut s = script();
@@ -953,7 +900,6 @@ fn text_ui_reports_caret_geometry_and_focus() {
     assert_eq!(ui.caret_x, 0.0);
     assert_eq!(ui.display_from, 0);
     assert!(ui.selection.is_empty());
-    // The empty box still emits its Text quad (Some("")) — the caret's ride-along.
     assert!(
         s.extract().iter().any(|q| matches!(
             (&q.target, &q.content),
@@ -996,11 +942,10 @@ fn click_places_cursor_and_drag_selects() {
     let ui = s.focused_editbox_text_ui().unwrap();
     assert_eq!(ui.selection, vec![(0, 21.0, 49.0)]);
     assert_eq!(ui.caret_x, 49.0);
-    // Drag back LEFT past the anchor to x=107 (byte 1): the selection flips to 1..3.
+    // Drag back left past the anchor to x=107 (byte 1): the selection flips to 1..3.
     s.mouse_move(107.0, 60.0);
     let ui = s.focused_editbox_text_ui().unwrap();
     assert_eq!(ui.selection, vec![(0, 7.0, 21.0)]);
-    // Release ends the drag: further moves change nothing.
     s.mouse_button(107.0, 60.0, "LeftButton", false);
     s.mouse_move(170.0, 60.0);
     assert_eq!(
@@ -1065,8 +1010,8 @@ fn ctrl_arrows_jump_words() {
     );
 }
 
-/// Copy needs a selection; cut copies then deletes; the password box yields the mask run, never
-/// the real text (the client's fixed placeholder `0x882748`, mask stand-in).
+/// Copy needs a selection, cut copies then deletes, and a password box copies its mask run, never
+/// the text (the client copies the empty string, `0x882748`).
 #[test]
 fn copy_cut_and_the_password_placeholder() {
     let mut s = script();
@@ -1090,15 +1035,13 @@ fn copy_cut_and_the_password_placeholder() {
     );
 }
 
-/// The OS-native delete family (no 1.12 counterpart — the host keymap's Option/Cmd/Ctrl
-/// Backspace-Delete chords): a word delete takes the adjacent alnum run (+ the separators toward
-/// it), an edge delete clears to the line end — and both collapse to "delete the selection" when
-/// one exists, like every deletion gesture.
+/// Word and edge deletes, the host's OS-native chords with no 1.12 counterpart: a word delete
+/// takes the adjacent alphanumeric run and the separators toward it, an edge delete clears to the
+/// line's end, and either deletes a live selection instead.
 #[test]
 fn word_and_edge_deletes() {
     let mut s = script();
     seam_rig(&mut s, "abc def ghi");
-    // Word-delete back from the end: "ghi" goes (boundary at 8).
     s.editbox_action(EditAction::Delete {
         unit: EditUnit::Word,
         back: true,
@@ -1122,7 +1065,6 @@ fn word_and_edge_deletes() {
     });
     assert_eq!(s.eval::<String>("return E:GetText()").unwrap(), " ");
 
-    // Selection-first: with a live selection, a word delete removes exactly it.
     s.run(r#"E:SetText("hello world"); E:HighlightText(2, 5)"#)
         .unwrap();
     s.editbox_action(EditAction::Delete {
@@ -1131,7 +1073,7 @@ fn word_and_edge_deletes() {
     });
     assert_eq!(s.eval::<String>("return E:GetText()").unwrap(), "he world");
 
-    // Edge-delete back (macOS Cmd+Backspace): clears to the start — the whole line from the end.
+    // Edge-delete back (macOS Cmd+Backspace) from the end clears the whole line.
     s.run(r#"E:SetText("clear me")"#).unwrap();
     s.editbox_action(EditAction::Delete {
         unit: EditUnit::Edge,
@@ -1148,8 +1090,8 @@ fn word_and_edge_deletes() {
     assert_eq!(s.eval::<i64>("return n").unwrap(), 0);
 }
 
-/// SelectAll (the ref's Ctrl+A → `HighlightText(0, -1)` law): whole text selected, caret to the
-/// end; typing replaces the lot.
+/// SelectAll, the reference's Ctrl+A (`HighlightText(0, -1)`): the whole text selected, the caret
+/// at the end, and typing replaces it all.
 #[test]
 fn select_all_action() {
     let mut s = script();
@@ -1166,9 +1108,8 @@ fn select_all_action() {
     );
 }
 
-/// The scroll window follows the cursor: typing past the box edge advances `display_from`
-/// (whole chars); HOME snaps it back (`0x77da80`'s stay-visible invariant, the char-granular
-/// `E+0x348` window).
+/// The scroll window keeps the cursor visible (`0x77da80`) in whole chars: typing past the edge
+/// advances `display_from`, HOME snaps it back.
 #[test]
 fn scroll_window_keeps_the_cursor_visible() {
     let mut s = script();
@@ -1182,7 +1123,6 @@ fn scroll_window_keeps_the_cursor_visible() {
         (40 - ui.display_from) as f32 * 7.0,
         "caret x measures from the window origin"
     );
-    // HOME: the window snaps back to 0.
     s.editbox_action(EditAction::Move {
         unit: EditUnit::Edge,
         back: true,
@@ -1193,7 +1133,7 @@ fn scroll_window_keeps_the_cursor_visible() {
     assert_eq!(ui.caret_x, 0.0);
 }
 
-/// The blink law (`0x77a790`): 0.5 s half-period toggle, reset shown by every edit.
+/// The caret blink (`0x77a790`): a 0.5 s half-period, reset to shown by every edit.
 #[test]
 fn caret_blinks_on_tick_and_resets_on_edit() {
     let mut s = script();
@@ -1205,19 +1145,15 @@ fn caret_blinks_on_tick_and_resets_on_edit() {
     assert!(s.focused_editbox_text_ui().unwrap().caret_on);
     s.tick(0.6);
     assert!(!s.focused_editbox_text_ui().unwrap().caret_on);
-    // An edit shows the caret immediately (blink reset).
     s.char_input("b");
     answer_advances(&mut s);
     assert!(s.focused_editbox_text_ui().unwrap().caret_on);
 }
 
-// ── A hyperlink is ONE keypress (`AdvanceTokens 0x77bb30`, decision 1077) ─────────────────────
+// ── a hyperlink is one keypress (`AdvanceTokens 0x77bb30`) ─────────────────────
 //
-// The engine-level law lives in `markup`; these drive it the way a player does — through the
-// focused box's public keyboard API — because that is the level the reported defect lived at:
-// backspacing a shift-clicked item link chewed it one invisible byte at a time, and the byte that
-// went first was the `r` of its trailing `|r`, which turned everything typed afterwards the item's
-// colour.
+// Driven through the keyboard API: a Backspace that took only the link's trailing `|r` would
+// colour everything typed after it.
 
 /// An epic link exactly as the client's own builder formats one (`0x52adb0`).
 const LINK: &str = "|cffa335ee|Hitem:11684:0:0:0|h[Ironfoe]|h|r";
@@ -1243,8 +1179,7 @@ fn one_backspace_deletes_a_whole_item_link() {
     }));
     assert_eq!(text_of(&s), "", "colour prefix and trailing |r go with it");
 
-    // And from the far side of following text: the link survives until the text is gone, then goes
-    // whole — never half-eaten, which is what left a dangling `|c` colouring the rest of the line.
+    // Behind following text: the text goes first, then the whole link, never leaving a `|c`.
     let mut s = box_with_link("ab");
     for expected in ["|cffa335ee|Hitem:11684:0:0:0|h[Ironfoe]|h|ra", LINK, ""] {
         s.editbox_action(EditAction::Delete {
@@ -1271,8 +1206,7 @@ fn one_arrow_crosses_a_whole_item_link() {
         });
     };
     cursor(&mut s);
-    // One RIGHT from the start lands past the entire link — so typing there appends, and does not
-    // land between the `]` and its `|h`.
+    // One RIGHT from the start passes the whole link, so typing there appends.
     s.char_input("x");
     assert_eq!(text_of(&s), format!("{LINK}x"));
 }
@@ -1305,8 +1239,7 @@ fn typing_strictly_inside_a_link_is_refused() {
         LINK,
         "the client swallows it rather than splitting the link"
     );
-    // The same keystroke at the link's leading edge is allowed — the guard tests the PREVIOUS
-    // token too, which is what keeps the boundary usable.
+    // At the link's leading edge the keystroke lands: the guard also tests the previous token.
     s.run("E:HighlightText(0, 0)").unwrap();
     s.char_input("x");
     assert_eq!(text_of(&s), format!("x{LINK}"));
@@ -1332,20 +1265,13 @@ fn max_letters_counts_visible_letters_not_escape_bytes() {
     s.run(r#"E = CreateFrame("EditBox", "E"); E:SetFocus(); E:SetMaxLetters(20)"#)
         .unwrap();
     s.run(&format!("E:Insert(\"{LINK}\")")).unwrap();
-    // 43 bytes, but "[Ironfoe]" is 9 letters — comfortably under a 20-letter cap that a raw char
-    // count would have blown through, trimming the link's own tail off.
+    // 43 bytes, but "[Ironfoe]" is 9 letters, under the 20-letter cap.
     assert_eq!(text_of(&s), LINK);
     assert_eq!(s.eval::<i64>("return E:GetNumLetters()").unwrap(), 9);
 }
 
-/// **Creating a box is not showing it** — and that is what keeps the on-show self-focus safe now
-/// that autoFocus defaults ON (decision 1686). A frame born visible is not an effective-visibility
-/// *transition*, so it never runs the OnShow override; only a real `Show()` does. Without this,
-/// loading the shipped chain would hand the keyboard to whichever edit box happened to be
-/// constructed first, and typing would go into it instead of to the game.
-///
-/// Pinned because it is load-bearing by *absence*: nothing in the on-show path mentions creation,
-/// so the day frame construction starts firing OnShow, this is the test that says what it costs.
+/// A box born visible has had no show transition, so the OnShow focus never runs for it; if it
+/// did, loading the UI would hand the keyboard to the first edit box built.
 #[test]
 fn creating_a_box_does_not_focus_it_the_way_showing_one_does() {
     let s = script();
@@ -1358,16 +1284,8 @@ fn creating_a_box_does_not_focus_it_the_way_showing_one_does() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **`SetMaxLetters` gates the COUNT and not the type** — one of four widget bindings in the whole
-/// registrar that calls `lua_gettop` (`0x6f3070`), and its gate is exact (`cmp eax,2`), while the
-/// value goes through a bare `lua_tonumber` (`0x6f3620`) with no `isnumber` guard.
-///
-/// That pairing is the opposite of the usual one, which is why it earns a test: benilla typed the
-/// argument `i64` and so raised on `SetMaxLetters(nil)` — aux-addon's `gui/core.lua:288` writes
-/// exactly that, and died at load on it — while accepting the wrong *number* of arguments
-/// silently.
-///
-/// And `0` is **no limit**, not "no letters".
+/// `SetMaxLetters` gates the exact count (`lua_gettop`, `0x6f3070`) and reads the value with a bare
+/// `lua_tonumber` (`0x6f3620`); 0 is no limit.
 #[test]
 fn set_max_letters_gates_the_argument_count_and_coerces_the_value() {
     let s = script();
@@ -1378,7 +1296,7 @@ fn set_max_letters_gates_the_argument_count_and_coerces_the_value() {
     s.run("E:SetMaxLetters(12)").unwrap();
     assert_eq!(max(&s), 12);
 
-    // nil is 0 is UNLIMITED — the call completes, which is the whole point.
+    // nil stores 0, which is unlimited.
     s.run("E:SetMaxLetters(nil)").unwrap();
     assert_eq!(max(&s), 0);
     s.run(r#"E:SetMaxLetters(5) E:SetText("abcdefgh")"#)
@@ -1398,7 +1316,6 @@ fn set_max_letters_gates_the_argument_count_and_coerces_the_value() {
     s.run("E:SetMaxLetters({})").unwrap();
     assert_eq!(max(&s), 0);
 
-    // The COUNT is exact — too few AND too many both raise.
     assert!(s.run("E:SetMaxLetters()").is_err(), "too few raises");
     assert!(
         s.run("E:SetMaxLetters(50, 60)").is_err(),
@@ -1406,17 +1323,9 @@ fn set_max_letters_gates_the_argument_count_and_coerces_the_value() {
     );
 }
 
-/// **A `CSimpleEditBox` is born with FIVE regions, and `GetRegions` hands them to Lua before any
-/// authored one.** The ctor builds the text FontString (`E+0x328`, `0x779bee`), three
-/// selection-highlight `CSimpleTexture`s (`E+0x350/0x354/0x358`, loop `0x779c41`–`0x779c72`) and
-/// the caret (`E+0x368`, `0x779c86`) — in that order. `GetRegions 0x773f60` walks
-/// `[frame+0x1b8]`, one flat creation-ordered list, oldest first, no filter, and insertion is at
-/// the TAIL. So the authored `<Layers>` regions start at index 6.
-///
-/// The report is pfUI's `skins/blizzard/friends.lua` l.379 —
-/// `local _,_,_,_,_,left,right = GuildControlPopupFrameEditBox:GetRegions()` — which skips exactly
-/// those five and takes the box's two border textures. It died on a nil `left` for as long as
-/// benilla returned only the authored regions.
+/// The ctor builds five regions in order, the text FontString (`0x779bee`), three selection
+/// textures (`0x779c41`-`0x779c72`) and the caret (`0x779c86`), and `GetRegions` (`0x773f60`)
+/// walks one creation-ordered list, so authored regions start at index 6.
 #[test]
 fn an_editbox_is_born_with_the_ctors_five_regions_ahead_of_its_authored_ones() {
     let s = script();
@@ -1439,9 +1348,7 @@ fn an_editbox_is_born_with_the_ctors_five_regions_ahead_of_its_authored_ones() {
     let report = crate::loader::load(&s, &doc, &|_| None);
     assert!(report.errors.is_empty(), "errors: {:?}", report.errors);
 
-    // Five engine regions, then the two authored textures — and NOT a sixth from the embedded
-    // `<FontString>`, which declares the ctor's object rather than adding one (the reference's
-    // EditBox LoadXML, `0x779fb0`).
+    // The embedded `<FontString>` declares the ctor's text region, not a sixth (`0x779fb0`).
     assert_eq!(
         s.eval::<i64>("return Box:GetNumRegions()").unwrap(),
         7,
@@ -1453,7 +1360,6 @@ fn an_editbox_is_born_with_the_ctors_five_regions_ahead_of_its_authored_ones() {
         "GetNumRegions is exactly the length GetRegions enumerates"
     );
 
-    // pfUI's own read, verbatim in shape: skip five, take the authored pair.
     let (left, right) = s
         .eval::<(String, String)>(
             "local _,_,_,_,_,l,r = Box:GetRegions() return l:GetTexture(), r:GetTexture()",
@@ -1465,7 +1371,6 @@ fn an_editbox_is_born_with_the_ctors_five_regions_ahead_of_its_authored_ones() {
     );
     assert_eq!(right, r"Interface\Right", "region 7 is the second");
 
-    // The first is the text FontString the box actually types into.
     s.run(r#"Box:SetText("typed")"#).unwrap();
     assert_eq!(
         s.eval::<String>("local t = Box:GetRegions() return t:GetText()")
@@ -1473,8 +1378,7 @@ fn an_editbox_is_born_with_the_ctors_five_regions_ahead_of_its_authored_ones() {
         "typed",
         "region 1 is the ctor's embedded text FontString"
     );
-    // 2..5 are the three selection quads and the caret: real regions, carrying no art of their own
-    // (benilla paints both host-side — the gap named on EditBoxState).
+    // 2..5, the selection quads and the caret, carry no art: benilla paints both host-side.
     assert!(
         s.eval::<bool>(
             "local a,b,c,d,e = Box:GetRegions() \
@@ -1486,9 +1390,8 @@ fn an_editbox_is_born_with_the_ctors_five_regions_ahead_of_its_authored_ones() {
     );
 }
 
-/// `SetNumber` is `SetText` with Lua's own `%.14g` in front of it — the two bindings are
-/// byte-identical in the reference (`0x798690` / `0x7984c0`), so the numeric verb does no numeric
-/// work of its own. Decision 1831; the expected strings are the reference's executed output.
+/// `SetNumber` is `SetText` (`0x798690` and `0x7984c0` are byte-identical), so a number arrives
+/// through Lua's `%.14g`; the expected strings are the reference's own output.
 #[test]
 fn set_number_formats_like_the_references_printf() {
     let s = UiScript::new().unwrap();
@@ -1519,12 +1422,11 @@ fn set_number_formats_like_the_references_printf() {
         );
     }
 
-    // A STRING is accepted and passed through verbatim — the gate is `lua_isstring`, so the
-    // argument is never parsed as a number.
+    // A string passes verbatim: the gate is `lua_isstring`, and nothing parses it.
     s.run(r#"box:SetNumber("abc")"#).unwrap();
     assert_eq!(s.eval::<String>("return box:GetText()").unwrap(), "abc");
 
-    // Everything else raises, including an ABSENT argument. `luaL_error` does not return.
+    // Anything else raises, no argument included.
     for bad in [
         "box:SetNumber()",
         "box:SetNumber(nil)",
@@ -1534,10 +1436,8 @@ fn set_number_formats_like_the_references_printf() {
     }
 }
 
-/// A `numeric` box takes the reference's wholesale abort: the clear-all has already run when the
-/// insert fails the digit test, so the box is left EMPTY rather than partly filled. The money
-/// boxes (`MoneyInputFrame.xml`) are numeric, which is why this matters — though the money path
-/// itself only ever passes non-negative integers.
+/// A numeric box aborts the whole insert after the clear has run, so text that fails the digit
+/// test leaves it empty, not partly filled.
 #[test]
 fn set_number_on_a_numeric_box_empties_it_when_the_text_is_not_all_digits() {
     let s = UiScript::new().unwrap();
@@ -1547,7 +1447,6 @@ fn set_number_on_a_numeric_box_empties_it_when_the_text_is_not_all_digits() {
     s.run("box:SetNumber(1234)").unwrap();
     assert_eq!(s.eval::<String>("return box:GetText()").unwrap(), "1234");
 
-    // The minus sign fails the digit test, and the abort is wholesale.
     s.run("box:SetNumber(-5)").unwrap();
     assert_eq!(
         s.eval::<String>("return box:GetText()").unwrap(),
@@ -1556,8 +1455,8 @@ fn set_number_on_a_numeric_box_empties_it_when_the_text_is_not_all_digits() {
     );
 }
 
-/// `SetMaxBytes` (1960): the exact count gate and raw coerce of its sibling, a BYTE cap on the
-/// buffer, and -1 as the no-limit sentinel where `SetMaxLetters` reads 0.
+/// `SetMaxBytes`: `SetMaxLetters`'s exact count gate and raw coercion, a byte cap, and -1 as the
+/// no-limit sentinel.
 #[test]
 fn set_max_bytes_caps_the_buffer_in_bytes_with_minus_one_unlimited() {
     let s = script();
@@ -1585,14 +1484,10 @@ fn set_max_bytes_caps_the_buffer_in_bytes_with_minus_one_unlimited() {
     assert!(s.run("E:SetMaxBytes(1, 2)").is_err(), "too many raises");
 }
 
-/// **`OnCursorChanged(x, y, w, h)` fires when the caret moves** — the edge the shipped
-/// `MailFrame.xml` and `HelpFrame.xml` wire `ScrollingEdit_OnCursorChanged` to, and the reason a
-/// multiline box follows its caret as you type past the bottom (decision 2141).
-///
-/// The four args are the reference's (`0x77dd5f`, each scaled by `f`): `x` the caret's
-/// advance along its line, `y` **negative-downward** by row (which is what
-/// `ScrollingEdit_OnCursorChanged`'s `cursorOffset = y` then `-this.cursorOffset` reads back as a
-/// positive distance), `w` the constant `4.0`, `h` the line height.
+/// `OnCursorChanged(x, y, w, h)` fires when the caret moves, with the reference's args
+/// (`0x77dd5f`, each scaled): `x` the advance along the line, `y` negative downward by row, `w`
+/// the constant 4, `h` the line height. Stock `ScrollingEdit_OnCursorChanged` reads `-y` as the
+/// distance down.
 #[test]
 fn the_caret_flush_fires_on_cursor_changed_with_the_references_four_args() {
     let mut s = script();
@@ -1612,14 +1507,13 @@ fn the_caret_flush_fires_on_cursor_changed_with_the_references_four_args() {
     )
     .unwrap();
     s.resolve();
-    // Three bytes on row 0, then a wrap onto row 1 — the host answers the rows and the pitch.
+    // Three bytes on row 0, then a wrap onto row 1; the host answers the rows and the pitch.
     for ch in "abcdef".chars() {
         s.char_input(&ch.to_string());
     }
     s.resolve();
     if let Some(req) = s.editbox_advances_request() {
-        // A plain monotonic 7 px/byte table (the rig's own), wrapped into two rows at byte 3 —
-        // `caret_row_x` subtracts the row start's cumulative advance, which is the whole point.
+        // 7 px per byte, wrapped into two rows at byte 3: `x` must count from the row's start.
         let cum: Vec<f32> = (0..=req.text.len()).map(|i| i as f32 * 7.0).collect();
         s.set_editbox_advances(req.id, req.key, cum, vec![0, 3], 12.0);
     }
@@ -1643,9 +1537,8 @@ fn the_caret_flush_fires_on_cursor_changed_with_the_references_four_args() {
     assert_eq!(w, 4.0, "w is the reference's constant, not a measurement");
     assert_eq!(h, 12.0, "h is the line height");
 
-    // **The edge is a CHANGE.** A tick that moves nothing fires nothing — which is what makes
-    // `ScrollingEdit_OnUpdate`'s `if (this.cursorOffset)` loop terminate instead of re-scrolling
-    // every frame.
+    // It fires on a change only, which lets `ScrollingEdit_OnUpdate`'s `if (this.cursorOffset)`
+    // settle instead of scrolling every frame.
     let before: i64 = s.eval("return table.getn(fires)").unwrap();
     s.tick(0.016);
     s.tick(0.016);
@@ -1655,7 +1548,6 @@ fn the_caret_flush_fires_on_cursor_changed_with_the_references_four_args() {
         "two quiet ticks fire nothing"
     );
 
-    // …and a caret move fires again.
     s.editbox_action(EditAction::Move {
         unit: EditUnit::Char,
         back: true,
diff --git a/crates/benilla-ui/src/script/event.rs b/crates/benilla-ui/src/script/event.rs
index bf4621dd..854788fd 100644
--- a/crates/benilla-ui/src/script/event.rs
+++ b/crates/benilla-ui/src/script/event.rs
@@ -1,22 +1,8 @@
-//! Handler firing — the FrameScript calling convention, for events, ticks, and
-//! show/hide transitions.
-//!
-//! Every handler is invoked through the *same* protected path, which reproduces both calling
-//! conventions the transition-era client supported (decision 0068):
-//!
-//! - **Legacy globals (byte-verified):** `this` (`0x872e64`) = the firing frame's wrapper, `event`
-//!   (`0x84b648`) = the event name (OnEvent only), `arg1..argN` (`0x8722dc`) = the args — each
-//!   **set then restored** around the call (`luaL_ref` saves the prior value; restored after), so
-//!   nested fires are safe. The handler reads its inputs as globals; the client `pcall`s with
-//!   **nargs = 0**.
-//! - **Modern args:** the same values are *also* passed positionally as `(self, event, ...)` for
-//!   OnEvent (`(self, elapsed)` for OnUpdate, `(self)` for OnShow/OnHide/OnLoad) — the form Era
-//!   addons are written against.
-//!
-//! So inside one OnEvent handler `this == self` and `arg1` is the first positional argument (5.0's
-//! own `arg[1]`; `...` as a value, and `select` with it, are not in this dialect). Handler errors are
-//! caught (mlua's `Function::call` is a protected call) and returned to the caller, which records
-//! them in [`super::Model::errors`] — never a panic, never a print.
+//! Handler firing: the FrameScript calling convention for events, ticks and show/hide. The
+//! reference sets `this` (`0x872e64`), `event` (`0x84b648`) and `arg1..argN` (`0x8722dc`) around
+//! the call, restoring each after, and `pcall`s with no arguments; the handler here also gets the
+//! same values as `(self, event, ...)` arguments, which 1.12 does not pass.
+//! Handler errors return to the caller, which records them in [`super::Model::errors`].
 
 use std::borrow::Cow;
 
@@ -26,29 +12,14 @@ use super::{Model, ScriptValue, REG_SCRIPTS};
 use crate::script::object::frame_wrapper;
 use crate::widget::{ButtonState, FrameHandle};
 
-/// Fire `event` at every frame registered for it (the engine-internal twin of
-/// `UiScript::fire_event`, for engine code holding only the Lua context — the compare drive's
-/// `SHOW_COMPARE_TOOLTIP`), in registration order. **The same walk, not a second one**: this was
-/// an index walk over the live list, so a handler that unregistered *itself* (the hook-once idiom
-/// on `ADDON_LOADED`) shifted its successor into the slot the walk had just left, and that
-/// listener never heard the event — the 1324 bug, fixed in [`super::tick::fire_event_into`] and
-/// left standing here.
+/// `UiScript::fire_event` for engine code that holds only the Lua context.
 pub(super) fn fire_global(lua: &Lua, event: &str, args: &[ScriptValue]) {
     super::tick::fire_event_into(lua, event, args.to_vec());
 }
 
-/// The `RegisterAllEvents()` half of one dispatch: every frame that asked for the whole stream,
-/// after the event's own listeners and skipping any frame that was already visited as one of them.
-///
-/// **After, and de-duplicated, because that is where such a frame would sit if the registration
-/// were expanded.** A frame joins the all-events set later than the frames already listening for a
-/// given event, so it takes the tail of that event's list; and a frame holding both an all-events
-/// registration and a `RegisterEvent` for *this* event is one listener, not two — `RegisterEvent`'s
-/// own `if !list.contains(&h)` is the same rule one level down.
-///
-/// Same mid-dispatch discipline as the walk above (`0x703ee8`, decision 1324): the next frame is
-/// re-found by position each step, so a handler that unregisters the walk's successor stops the
-/// dispatch there rather than robbing it.
+/// The `RegisterAllEvents()` half of a dispatch: the all-events frames, after the event's own
+/// listeners and skipping any already visited. The next frame is re-found by position each step
+/// (`0x703ee8`), so a handler that unregisters the walk's successor ends the dispatch there.
 pub(super) fn fire_all_event_listeners(lua: &Lua, event: &str, args: &[ScriptValue]) {
     let model_mut = || lua.app_data_mut::<Model>().expect("model app_data set");
     let mut at = model_mut().all_event_frames.first().copied();
@@ -90,7 +61,7 @@ pub(super) fn fire_event_handler(
     fire(lua, id, "OnEvent", Some(event), extra)
 }
 
-/// Fire a frame's `OnUpdate` (`this` + `arg1 = elapsed`; modern `(self, elapsed)`).
+/// Fire a frame's `OnUpdate` with `arg1 = elapsed`.
 pub(super) fn fire_update_handler(lua: &Lua, id: u32, elapsed: f32) -> mlua::Result<()> {
     fire(
         lua,
@@ -101,12 +72,8 @@ pub(super) fn fire_update_handler(lua: &Lua, id: u32, elapsed: f32) -> mlua::Res
     )
 }
 
-/// Fire a plain widget handler — one that carries no `event` name: the mouse set
-/// (`OnEnter`/`OnLeave(self, motion)`, `OnMouseDown`/`OnMouseUp(self, button)`,
-/// `OnClick(self, button, down)`, `OnMouseWheel(self, delta)`) and the per-kind slots
-/// (`OnValueChanged(self, value)`). `extra` is the handler's arguments (the `arg1..argN` legacy
-/// globals plus the trailing modern positionals after `self`). Reuses the one [`fire`] path (so the
-/// wrapper lookup + set/restore convention stay in a single home); a no-op if no such script is set.
+/// Fire a handler that carries no `event` name (`OnEnter`, `OnClick`, `OnValueChanged`, ...), with
+/// `extra` as its `arg1..argN`; a no-op when the frame has no such script.
 pub(super) fn fire_widget_handler(
     lua: &Lua,
     id: u32,
@@ -116,20 +83,9 @@ pub(super) fn fire_widget_handler(
     fire(lua, id, script, None, extra)
 }
 
-/// Drain [`Model::pending_size_changed`] and fire `OnSizeChanged(self, width, height)` for each.
-///
-/// The resolve pass ([`super::UiScript::resolve_layout`]) only ever holds a `&mut Model` — three of
-/// its callers reach it that way — so it *queues* the frames whose resolved size moved and this
-/// runs at the next `&Lua` seam. Errors are recorded, never propagated: a handler blowing up must
-/// not abort a layout pass.
-///
-/// **Drains exactly once, deliberately.** A handler is free to resize things, `Show()` something,
-/// or call `UpdateScrollChildRect` — each of which can re-enter the resolver and queue *more*
-/// entries. Looping until the queue empties would let a handler that grows its own frame spin the
-/// engine forever inside one call; taking one batch instead leaves the next batch for the next
-/// resolve, which is exactly the reference's shape (its `ApplyRect` fires, the handler dirties the
-/// layout, and the *next* layout pass fires again). A genuinely oscillating handler oscillates at
-/// one fire per frame, visibly, instead of hanging the client.
+/// Drain [`Model::pending_size_changed`], queued by the resolve pass, and fire `OnSizeChanged` for
+/// each, recording errors. It drains once: a size a handler changes fires on the next resolve, as
+/// the reference's `ApplyRect` does, so a handler that grows its own frame cannot spin forever.
 pub(super) fn fire_size_changes(lua: &Lua) {
     let pending = std::mem::take(
         &mut lua
@@ -152,18 +108,10 @@ pub(super) fn fire_size_changes(lua: &Lua) {
     }
 }
 
-/// Fire `OnShow`/`OnHide` for a set of frames whose effective visibility just changed (from
-/// [`crate::widget::WidgetArena::set_shown`]/`set_parent`'s changed-list). Errors are recorded in
-/// [`Model::errors`] rather than propagated — a handler error must not abort the `Show()` call.
-///
-/// **This is also where the `toplevel` raise fires** (the Show trigger `0x76ae10` @`0x76aee0`):
-/// the binary tests the toplevel bit and raises *after* the subtree's visibility has propagated
-/// and *before* that node's OnShow notify — which is exactly this seam, since the arena has
-/// finished propagating by the time it hands back the changed list.
-/// Per node and in list order, so a handler reading `GetFrameLevel()` sees the raised value the way
-/// it would in the reference. It lives here rather than at the Lua `Show` binding because *every*
-/// visibility transition this engine performs runs `0x76ae10` — an arena-level show from the
-/// tooltip path (or a future host one) must raise too, and a second seam is how that gets forgotten.
+/// Fire `OnShow`/`OnHide` for the frames whose effective visibility just changed, recording
+/// errors in [`Model::errors`]. A shown `toplevel` frame raises here, after the subtree has
+/// propagated and before its `OnShow` (`0x76ae10` at `0x76aee0`), so a show that does not come
+/// through Lua `Show` raises too.
 pub(super) fn fire_visibility_changes(lua: &Lua, changed: Vec<FrameHandle>) {
     // Resolve (handle, id, now-visible?) under one short borrow, then fire with no borrow held.
     let items: Vec<(FrameHandle, u32, bool)> = {
@@ -176,27 +124,17 @@ pub(super) fn fire_visibility_changes(lua: &Lua, changed: Vec<FrameHandle>) {
             })
             .collect()
     };
-    // **The hover-hide law**: hiding the hovered frame — directly or through an ancestor's
-    // cascade — fires its `OnLeave` SYNCHRONOUSLY, inside the hide and **before that frame's
-    // `OnHide`** (`0x764ba0`'s kind-2 tail runs mid-`0x76ad50`, the leave at `0x764cce`; the
-    // only silent case is destruction). It clears the hover cache and the drag-arm on that frame
-    // (`+0x100/+0x104`, the arg-1 flavor), and schedules the re-pick — the pump re-hovers
-    // whatever is now topmost at the unchanged cursor next tick ([`Model::hover_repick`]).
-    // A SHOW arms the re-pick too (`0x764b8d`: any mouse-bucket insert): a window opening under
-    // a stationary cursor gets hovered without a mouse move. This is what makes a slot button's
-    // FrameXML `OnLeave → GameTooltip:Hide()` actually run when its window closes under the
-    // cursor — the reference has NO engine-side owner-visibility fallback for the tooltip
-    // (byte-censused negative), so the leave firing here is the whole mechanism.
+    // Hiding the hovered frame, directly or by an ancestor, fires its `OnLeave` inside the hide and
+    // before its `OnHide` (`0x764ba0`'s tail in `0x76ad50`, the leave at `0x764cce`), clears the
+    // hover and the drag-arm (`+0x100`/`+0x104`) and arms the re-pick; a show arms it too
+    // (`0x764b8d`). This leave is how a tooltip closes with its window; the reference has no other.
     let left: Option<(FrameHandle, u32)> = {
         let mut model = lua.app_data_mut::<Model>().expect("model");
         let hidden_hover = model
             .mouseover
             .filter(|&m| items.iter().any(|&(h, _, vis)| h == m && !vis));
-        // The removal tail is a VIRTUAL dispatch — `0x764cce mov edx,[edi]; push 1;
-        // call [edx+0x50]` — so a Button reaches its own `0x7794e0`, whose DISABLED guard skips
-        // the base leave and with it the `<OnLeave>` script. Hiding a disabled hovered button is
-        // therefore as silent as walking off one ([`super::button::hover_notify_runs`]); the
-        // hover cache and the drag-arm still clear, because those are the *caller's* half.
+        // The leave is a virtual call (`0x764cce`, `[vtable+0x50]`): a disabled Button's own
+        // `0x7794e0` skips its `OnLeave`, while the hover and the drag-arm still clear.
         let notified = super::button::hover_notify_runs(&model, hidden_hover);
         if let Some(m) = hidden_hover {
             model.mouseover = None;
@@ -221,15 +159,8 @@ pub(super) fn fire_visibility_changes(lua: &Lua, changed: Vec<FrameHandle>) {
             let mut model = lua.app_data_mut::<Model>().expect("model");
             super::object::toplevel::raise_on_show(&mut model, h);
         } else {
-            // **The button's HIDE edge** — `CSimpleButton` overrides the hide notify (`+0x34`,
-            // `0x7791e0`) to un-press itself before tail-jumping the base, so a button hidden
-            // while held does not come back up wearing its pushed art (the guard is
-            // `state != DISABLED && locked == 0`).
-            //
-            // It hangs off the VISIBILITY transition, not off the hover, which is what it is in
-            // the reference — a button hidden nowhere near the cursor un-presses too, and one
-            // hidden under the cursor no longer needs the hover-drop above to notice
-            // (decision 2134).
+            // `CSimpleButton`'s hide notify (`+0x34`, `0x7791e0`) un-presses it, unless disabled
+            // or locked, before the base notify, so a button hidden while held comes back unpushed.
             let mut model = lua.app_data_mut::<Model>().expect("model");
             super::button::edge(&mut model, h, ButtonState::on_hide);
         }
@@ -239,24 +170,15 @@ pub(super) fn fire_visibility_changes(lua: &Lua, changed: Vec<FrameHandle>) {
                 .expect("model")
                 .record_script_error(e.to_string());
         }
-        // **And the EditBox's own OnShow/OnHide vtable overrides** (`0x81c910` +0x30/+0x34): an
-        // `autoFocus` box grabs the keyboard when it appears if nothing else holds it, and hiding
-        // the box that holds it releases it. Both overrides call the base notify FIRST and act
-        // after, which is why this sits below the `fire` and not above it. A no-op for every frame
-        // that is not an EditBox. Here rather than at the Lua `Show`/`Hide` bindings for the same
-        // reason the toplevel raise is: every visibility transition this engine performs runs
-        // through this seam, and a second one is how a path gets forgotten.
+        // The EditBox show/hide overrides (`0x81c910` `+0x30`/`+0x34`) call the base notify first,
+        // so this runs after the `fire`: an `autoFocus` box takes a free focus, a hidden box
+        // releases its own.
         super::editbox::visibility_focus(lua, h, visible);
     }
 }
 
-/// Is a handler bound under `script` for this frame id? — the **existence** question, asked
-/// without firing anything.
-///
-/// It exists for the keyboard walk ([`super::keyboard`]), where the reference's consumption gate is
-/// the presence of the slot rather than anything the handler does: `0x76b7d0` reads `[+0x188]`/
-/// `[+0x190]`, consumes on either, and fires only the first. A lookup failure reads as "absent" —
-/// the gate must never be able to raise out of the middle of a walk.
+/// Whether a handler is bound under `script`, without firing it: the keyboard walk consumes on
+/// the slot's presence (`0x76b7d0`). A failed lookup reads absent, so the gate never raises.
 pub(super) fn has_widget_handler(lua: &Lua, id: u32, script: &str) -> bool {
     let Ok(scripts) = lua.named_registry_value::<Table>(REG_SCRIPTS) else {
         return false;
@@ -267,9 +189,8 @@ pub(super) fn has_widget_handler(lua: &Lua, id: u32, script: &str) -> bool {
     }
 }
 
-/// The one firing path. `event_name` is the `event` global + first modern positional (OnEvent only);
-/// `extra` are the `arg1..argN` globals + the trailing modern positionals. Globals are saved before
-/// and restored after (even on error) — nesting-safe. Holds no model borrow across the call.
+/// The one firing path: `event_name` is `OnEvent`'s, `extra` the `arg1..argN`. Holds no model
+/// borrow across the call.
 fn fire(
     lua: &Lua,
     id: u32,
@@ -277,7 +198,6 @@ fn fire(
     event_name: Option<&str>,
     extra: Vec<Value>,
 ) -> mlua::Result<()> {
-    // Look up the handler (Lua-side, transient handle). Absent ⇒ nothing to do.
     let scripts: Table = lua.named_registry_value(REG_SCRIPTS)?;
     let func: Function = match scripts.get::<Value>(id)? {
         Value::Table(per) => match per.get::<Value>(script)? {
@@ -288,24 +208,20 @@ fn fire(
     };
 
     let wrapper = frame_wrapper(lua, id)?;
-    // The attribution seam (decision 1395). Tight around the call and *after* `frame_wrapper` —
-    // which documents that callers hold no model borrow here, so the profiler's own borrow cannot
-    // land in the middle of one. Off, it is a relaxed load and a not-taken branch; the guard closes
-    // the fire on the way out of this scope, including an unwind.
+    // The profiler's fire opens after `frame_wrapper`, where no model borrow is held, and closes
+    // when the guard drops, unwinds included.
     let _fire =
         super::handler_prof::armed().then(|| super::handler_prof::Fire::open(lua, id, script));
     invoke_with_globals(lua, wrapper, &func, event_name, extra)
 }
 
-/// The legacy `argN` global names, pre-spelled through the arities that occur in practice so the
-/// per-arg save/set/restore below allocates nothing.
+/// The `argN` global names, spelled out so the common arities allocate nothing.
 const ARG_NAMES: [&str; 16] = [
     "arg1", "arg2", "arg3", "arg4", "arg5", "arg6", "arg7", "arg8", "arg9", "arg10", "arg11",
     "arg12", "arg13", "arg14", "arg15", "arg16",
 ];
 
-/// The global name for arg `i` — **1-based**, matching the globals themselves (`arg1..`). Past
-/// [`ARG_NAMES`] it falls back to allocating.
+/// The global name for arg `i`, 1-based like the globals.
 fn arg_name(i: usize) -> Cow<'static, str> {
     match ARG_NAMES.get(i - 1) {
         Some(&name) => Cow::Borrowed(name),
@@ -313,11 +229,9 @@ fn arg_name(i: usize) -> Cow<'static, str> {
     }
 }
 
-/// The calling convention itself — the single home for it, shared by [`fire`] (registry
-/// handlers: events, OnUpdate, OnShow/OnHide) and the loader's bottom-up `OnLoad` (which holds the
-/// compiled `Function` directly). Sets the legacy `this`/`event`/`arg1..argN` globals and passes the
-/// modern `(self[, event], extra…)` positionals, saving and restoring the globals around the call
-/// (even on error) so nested handler firing is safe.
+/// The calling convention, shared by [`fire`] and the loader's `OnLoad`: sets `this`, `event` and
+/// `arg1..argN`, passes `(self[, event], extra...)`, and restores the globals after the call, even
+/// on error, so nested fires are safe.
 pub(crate) fn invoke_with_globals(
     lua: &Lua,
     wrapper: Table,
@@ -350,7 +264,7 @@ pub(crate) fn invoke_with_globals(
     }
     modern.extend(extra.iter().cloned());
 
-    // Protected call. Capture the outcome, but restore globals first regardless.
+    // A protected call; the globals are restored before its outcome returns.
     let outcome = func.call::<()>(MultiValue::from_vec(modern));
 
     g.set("this", saved_this)?;
diff --git a/crates/benilla-ui/src/script/extract.rs b/crates/benilla-ui/src/script/extract.rs
index 69f461b0..a8e6a946 100644
--- a/crates/benilla-ui/src/script/extract.rs
+++ b/crates/benilla-ui/src/script/extract.rs
@@ -1,7 +1,5 @@
-//! [`UiScript::extract`] — the render-list builder (decision 0068): the visible-tree
-//! [`crate::order::traversal`] zipped with the resolved rects and per-kind region visuals, in the
-//! client's painter order. An `impl UiScript` block beside its concern (the `layout.rs` pattern);
-//! the shared ScrollFrame clip it walks lives in [`super::clip`].
+//! [`UiScript::extract`], the render list: the visible-tree [`crate::order::traversal`] zipped
+//! with the resolved rects and region visuals, in the client's painter order.
 
 use crate::layout::Rect;
 use crate::order::{self, ZTarget};
@@ -11,20 +9,8 @@ use super::clip::{effective_clip, scroll_clip_sources};
 use super::{colorselect, slider, ExtractedQuad, FontObject, QuadContent, TexCoords, UiScript};
 
 impl UiScript {
-    /// **Every live draw target in the VM**, whether or not it is currently visible — each frame's
-    /// own slot followed by its region leaves, in arena order.
-    ///
-    /// [`Self::extract`] answers *what is being drawn*; this answers *what exists*, and the two
-    /// together are what let an instrument say **who drew a quad**. Diff this across a load and the
-    /// new targets are exactly the ones that load created: no name prefixes, no heuristics, and no
-    /// dependence on an addon naming anything at all. That is the oracle behind the addon
-    /// harness's render column, and it is written this way because the obvious alternatives are
-    /// both wrong — a with/without **quad-count diff** reads zero for an addon that *replaces* a
-    /// window rather than adding one (Bagnon takes the bags over), and a **name-prefix** match
-    /// cannot see an anonymous frame or a region an addon hangs off one of ours.
-    ///
-    /// Handles are generational, so a destroyed-and-reused slot can never be mistaken for a
-    /// survivor of the baseline.
+    /// Every live draw target, visible or not: each frame's slot then its regions, in arena order.
+    /// Handles are generational, so a diff across a load names exactly what the load created.
     pub fn live_targets(&self) -> Vec<ZTarget> {
         let model = self.model_ref();
         let mut out = Vec::new();
@@ -35,12 +21,7 @@ impl UiScript {
         out
     }
 
-    /// The frame a draw target belongs to — itself for a frame slot, the owner for a region.
-    ///
-    /// The half of the attribution that separates *created a window of its own* from *painted onto
-    /// one of ours*: a new `Region` whose owner frame is **not** new is an addon hooking an
-    /// existing frame, which is precisely what `!OmniCC` does to a cooldown and what a check built
-    /// only on new frames would score as "drew nothing".
+    /// The frame a draw target belongs to: itself for a frame slot, the owner for a region.
     pub fn target_frame(&self, target: ZTarget) -> Option<FrameHandle> {
         match target {
             ZTarget::Frame(fh) => self.model_ref().arena.frame(fh).map(|_| fh),
@@ -48,29 +29,17 @@ impl UiScript {
         }
     }
 
-    /// A frame's parent, or `None` for a top-level frame (or a stale handle).
-    ///
-    /// The other half of the attribution walk: a frame being **new** does not make it the addon's
-    /// own window — `!OmniCC` creates a brand-new anonymous frame *parented to one of our action
-    /// buttons*, and only the chain tells an overlay from a window.
+    /// A frame's parent, or `None` for a top-level frame or a stale handle.
     pub fn frame_parent(&self, frame: FrameHandle) -> Option<FrameHandle> {
         self.model_ref().arena.frame(frame)?.parent
     }
 
-    /// A frame's name, or `None` — it is anonymous, or the handle is stale.
-    ///
-    /// For reporting only. Nothing above depends on a frame being named; this is what turns an
-    /// attributed handle into a row a human can act on.
+    /// A frame's name, or `None` for an anonymous frame or a stale handle.
     pub fn frame_name(&self, frame: FrameHandle) -> Option<String> {
         self.model_ref().arena.frame(frame)?.name.clone()
     }
 
-    /// The nearest **named** frame at or above `target` — its own frame's name, else the closest
-    /// named ancestor.
-    ///
-    /// An addon's slot buttons are usually named and its inner art usually is not, so a bare
-    /// [`Self::frame_name`] would report a hole exactly where the interesting quads are. Walking up
-    /// answers "which window is this part of", which is the question a report is asking.
+    /// The name of the nearest named frame at or above `target`.
     pub fn target_owner_name(&self, target: ZTarget) -> Option<String> {
         let model = self.model_ref();
         let mut frame = match target {
@@ -87,17 +56,12 @@ impl UiScript {
         None
     }
 
-    /// The render list in the client's painter order (decision 0068): the visible-tree
-    /// [`crate::order::traversal`] zipped with the resolved rects and region visuals. Already sorted
-    /// ascending by `ZKey`. Call [`UiScript::resolve`] first for populated rects.
+    /// The render list in painter order, ascending by `ZKey`; call [`UiScript::resolve`] first.
     pub fn extract(&self) -> Vec<ExtractedQuad> {
         let model = self.model_ref();
         let list = order::traversal(&model.arena);
         let mut out = Vec::with_capacity(list.len());
-        // The ScrollFrame clip sources (decision 0112): every live ScrollFrame with a resolved rect
-        // and a live child, `child handle → the scrollframe's resolved rect`. Built once per extract;
-        // [`effective_clip`] walks a quad's owner up through this to find every ancestor ScrollFrame
-        // it is clipped by (nested ScrollFrames intersect).
+        // Scroll child → its ScrollFrame's rect; a quad clips to every ancestor ScrollFrame's.
         let scroll_sources = scroll_clip_sources(&model);
         for &(target, zkey) in list.iter() {
             let (rect, alpha, content, clip, scale) = match target {
@@ -106,18 +70,14 @@ impl UiScript {
                     let alpha = frame.map(|f| f.effective_alpha).unwrap_or(1.0);
                     let scale = frame.map(|f| f.effective_scale).unwrap_or(1.0);
                     let clip = effective_clip(&model, &scroll_sources, fh);
-                    // A Minimap widget's own slot carries its zoom out to the app renderer (the
-                    // tile/mask/arrow draw — decision 0203); every other frame slot is bare.
                     let content = match frame.map(|f| &f.kind_state) {
                         Some(crate::widget::KindState::Minimap(m)) => QuadContent::Minimap {
                             zoom: m.zoom,
                             inside_zoom: m.inside_zoom,
                         },
-                        // A `<Model>`/`<PlayerModel>` pane's content hole, carrying the pane's own
-                        // name so the app can join it to the bake that window keeps (see
-                        // [`QuadContent::ModelPane`]). Both widget kinds share `KindState::Model`
-                        // because the client's `CGCharacterModelBase` extends `CSimpleModel`, and
-                        // both draw the same way here.
+                        // A `<Model>`/`<PlayerModel>` pane's content hole, named so the app can
+                        // join it to that window's bake. Both kinds share `KindState::Model`, as
+                        // the client's `CGCharacterModelBase` extends `CSimpleModel`.
                         Some(crate::widget::KindState::Model(m)) => QuadContent::ModelPane {
                             handle: fh,
                             name: frame.and_then(|f| f.name.clone()),
@@ -145,22 +105,16 @@ impl UiScript {
                     let region = model.arena.region(rh);
                     let owner = region.map(|r| r.owner);
                     let owner_frame = owner.and_then(|o| model.arena.frame(o));
-                    // A draw layer switched off with `Frame:DisableDrawLayer` hides every region
-                    // the frame owns in it. Skipped HERE rather than by touching the regions
-                    // themselves, so each one keeps its own shown state and re-enabling the layer
-                    // restores exactly what was visible before.
+                    // A layer switched off by `Frame:DisableDrawLayer` hides its regions; skipped
+                    // here so each region keeps its own shown state for when the layer returns.
                     if let (Some(r), Some(f)) = (region, owner_frame) {
                         if f.disabled_layers & (1 << r.draw_layer.index()) != 0 {
                             continue;
                         }
                     }
-                    // Regions clip with their owner frame (decision 0112 §4).
                     let clip = owner.and_then(|o| effective_clip(&model, &scroll_sources, o));
                     let mut rect = owner.and_then(|o| model.resolved.get(&o).copied());
-                    // A StatusBar's bar-fill region draws at the value fraction of the frame's rect,
-                    // along the orientation axis (horizontal grows rightward, vertical bottom-up). The
-                    // bar owns its geometry — it never carries anchors, so it skips the region-rect
-                    // precedence below. It also CROPS: see `bar_fill_uv`.
+                    // A StatusBar's fill has no anchors: `bar_fill_rect` places it.
                     let mut bar_fill: Option<&crate::widget::StatusBarState> = None;
                     if let Some(crate::widget::KindState::StatusBar(sb)) =
                         owner_frame.map(|f| &f.kind_state)
@@ -170,30 +124,22 @@ impl UiScript {
                             bar_fill = Some(sb);
                         }
                     }
-                    // A Slider's thumb draws at the value fraction along the track (decision 0250 §4),
-                    // centered on the cross-axis — like the bar-fill, it owns its geometry and skips
-                    // the region-rect precedence below.
+                    // A Slider's thumb likewise: at the value fraction along the track.
                     let mut thumb_fill = false;
                     if let Some(crate::widget::KindState::Slider(sl)) =
                         owner_frame.map(|f| &f.kind_state)
                     {
                         if sl.thumb == Some(rh) {
-                            // The thumb's OWN size getters, not its authored `<Size>` — the same
-                            // `CSimpleTexture::GetWidth`/`GetHeight` fallback the drag law reads
-                            // (`slider::thumb_extent`), so a Lua-built `SetThumbTexture(path)` knob
-                            // draws at its art's texel span instead of smeared over the whole track.
+                            // The thumb's own `CSimpleTexture::GetWidth`/`GetHeight`, as the drag
+                            // reads them (`slider::thumb_extent`), not its authored `<Size>`.
                             let tsize = super::region::virtual_span(&model, rh);
                             rect = rect
                                 .map(|r| slider::thumb_rect(r, tsize, sl.vertical, sl.fraction()));
                             thumb_fill = true;
                         }
                     }
-                    // The colour picker's four sub-textures. The wheel and the strip are ordinary
-                    // authored regions — they keep their own anchors and resolve normally; all
-                    // they need from here is a content kind that says "the app paints this one".
-                    // The two markers are the opposite: their rects are DERIVED from the widget's
-                    // HSV, so the pixel you clicked is the pixel the marker lands on
-                    // (`colorselect::wheel_thumb_rect` is the exact inverse of the pick law).
+                    // The colour picker: the wheel and strip resolve like any region and the app
+                    // paints them; the markers' rects derive from the HSV, inverting the pick.
                     let mut color_art: Option<QuadContent> = None;
                     let mut color_thumb = false;
                     if let Some(crate::widget::KindState::ColorSelect(cs)) =
@@ -207,8 +153,8 @@ impl UiScript {
                                 .map(|w| colorselect::wheel_thumb_rect(w, tsize, cs.hsv));
                             color_thumb = true;
                         } else if cs.value_thumb == Some(rh) {
-                            // The strip anchors it; the WHEEL scales it (the client's own
-                            // unguarded `[this+0x318]` read — `colorselect::value_thumb_rect`).
+                            // The strip anchors it and the wheel scales it: the client's unguarded
+                            // `[this+0x318]` read.
                             let wheel = cs
                                 .wheel
                                 .and_then(|w| model.region_resolved.get(&w).copied());
@@ -226,65 +172,28 @@ impl UiScript {
                             });
                         }
                     }
-                    // A Button's state textures show by interaction state (the texture-array
-                    // "current" pointer): a non-current state texture emits no quad this frame.
-                    // The ButtonText additionally re-points to the current STATE's font instance
-                    // (disabled > highlighted > normal) — the client's per-state label font swap
-                    // (UIPanelButtonTemplate's gold/white/gray trio).
+                    // A Button's non-current state textures emit no quad, and its ButtonText takes
+                    // the current state's font instance (disabled > highlighted > normal).
                     let mut state_font: Option<&FontObject> = None;
                     let mut state_color: Option<[f32; 4]> = None;
-                    // The current instance's OWN justify (`<…Font justifyH=>`, a local write on
-                    // the embedded font — [`crate::widget::ButtonState::normal_justify_h`]).
                     let mut state_justify: Option<super::JustifyH> = None;
-                    // `Button:SetFont` — the face/size/flags written on the button's own embedded
-                    // fonts rather than on any object they inherit.
                     let mut button_font: Option<&crate::widget::ButtonFont> = None;
                     if let Some(crate::widget::KindState::Button(bs)) =
                         owner_frame.map(|f| &f.kind_state)
                     {
                         let hovered = owner.is_some() && model.mouseover == owner;
-                        // The PRESS is not read here. Which state texture shows is latched on the
-                        // transition (`ButtonState::set_state`), so the press reaches the paint
-                        // through the press EDGE at the moment the button goes down — not by
-                        // being re-derived every frame. `hovered` survives because the Highlight
-                        // is not a state texture and carries no latch.
+                        // The press is not read here: the state texture latches on the transition
+                        // (`ButtonState::set_state`). Only the Highlight, unlatched, reads hover.
                         if !bs.region_visible(rh, hovered) {
                             continue;
                         }
                         if bs.text == Some(rh) {
-                            // The label inherits ONE of the button's three embedded font instances
-                            // WHOLE (normal `+0x33c` / highlight `+0x3b8` / disabled `+0x434`): the
-                            // client swaps which instance the label reads, it does not merge axes
-                            // across them. So the object and the colour are picked as a PAIR, and a
-                            // state with no font object of its own is not in force at all — the
-                            // label stays on the normal instance, face and colour together.
-                            //
-                            // The pairing is the load-bearing half, and it is what this used to get
-                            // wrong (the colour fell back to `normal_color` while the font did not).
-                            // `UIDropDownMenu.lua` sets every row colour through `SetTextColor`
-                            // **and** `SetHighlightTextColor` with the same values (l.216-220,
-                            // l.829-830) — a second call it would never need if the first reached
-                            // the hovered state. The tradeskill list leans on the other direction:
-                            // its rows are `SetTextColor`'d to the recipe's difficulty and still
-                            // turn white under the cursor, because `<HighlightFont
-                            // inherits="GameFontHighlight">` is the instance in force there
-                            // (`ClassTrainerFrameTemplates.xml` l.74) and a normal-instance colour
-                            // cannot reach it.
-                            //
-                            // `LockHighlight()` counts as highlighted HERE too, not only for the
-                            // HighlightTexture in `region_visible`. `TradeSkillFrame_Update` blanks
-                            // a recipe row's highlight texture to `""` and *then* locks the row it
-                            // selected (Blizzard_TradeSkillUI.lua l.131/144) — with no texture left
-                            // to pin, the lock's only possible effect on that row is this label
-                            // swap, which is the white text on the selected recipe. Craft
-                            // (l.234) and the class trainer (l.183) lock the same way.
-                            //
-                            // INFERRED, not byte-verified: that an unset state instance leaves the
-                            // label on the normal one. A null slot in the *texture* array draws
-                            // nothing (decision 0227) and a font instance with no object cannot
-                            // work that way — a disabled button with no `<DisabledFont>` still
-                            // shows its label. Every state-colour caller in our own UI ships the
-                            // matching font object, so the two readings agree on all of them.
+                            // The label takes one embedded font instance whole (normal `+0x33c`,
+                            // highlight `+0x3b8`, disabled `+0x434`), so font and colour pair up;
+                            // a state lacking a font object stays on normal (inferred, not traced).
+                            // A locked highlight counts: the trade-skill list blanks the highlight
+                            // texture and locks the selected row (`Blizzard_TradeSkillUI.lua:133`,
+                            // `:144`), so this swap is its white text.
                             let highlighted = hovered || bs.locked_highlight;
                             let (name, color, justify) = if !bs.enabled()
                                 && bs.disabled_font.is_some()
@@ -313,88 +222,50 @@ impl UiScript {
                             state_justify = justify;
                         }
                     }
-                    // A TITLE REGION NEVER DRAWS. It is a hit rectangle, not a visual:
-                    // `CreateTitleRegion 0x773910` builds it as a plain Region with no textures at
-                    // all. Falling through here would emit the
-                    // texture quad the `else` branch below builds — invisible on screen, but the
-                    // render report counts quads, so every addon that makes one would read as
-                    // "drew something" (1246's lesson about what an instrument is told).
+                    // A title region never draws: `CreateTitleRegion 0x773910` builds a plain
+                    // Region with no textures, a hit rectangle only.
                     if region.map(|r| r.kind) == Some(crate::widget::RegionKind::Title) {
                         continue;
                     }
-                    // Region-level Hide (the VisibleRegion bit): no quad at all — checked on the
-                    // borrow, BEFORE the clone below. `RegionData` is a fat row (text `String`,
-                    // paths, the anchors `Vec`), and paying its clone for a row whose next line
-                    // discards it was a per-hidden-region-per-frame allocation tax the extract
-                    // walk never noticed it was paying.
+                    // Hidden (the VisibleRegion bit): no quad; tested before the clone below.
                     let data_ref = model.region_data.get(&rh);
                     if data_ref.is_some_and(|d| d.hidden) {
                         continue;
                     }
-                    // THE NAMEPLATE GLOW IS SHOWN AND NOT DRAWN — the one region in the engine
-                    // whose paint the director replaced with something else (decision 0184: the
-                    // lit plate brightens its bar instead of wearing the additive rim). It has to
-                    // stay a real, shown, ADD-blended `Nameplate-Glow` region because
-                    // `glow:IsShown()` IS the mouseover signal every 1.12 nameplate addon reads —
-                    // so the deviation lives here, at the paint, and nowhere in the model.
+                    // Deviation: the nameplate glow is shown but never drawn, because its additive
+                    // rim reads as hard edge lines in our linear-blending pipeline; the lit plate
+                    // brightens its bar instead. It stays a real shown ADD region, as
+                    // `glow:IsShown()` is the mouseover signal 1.12 nameplate addons read.
                     if data_ref.is_some_and(super::nameplate::is_unpainted_glow) {
                         continue;
                     }
                     let mut data = data_ref.cloned().unwrap_or_default();
-                    // The single-hop draw multiply (region-combine `0x772180`): the region's own
-                    // alpha times its immediate owner's — never a product up the tree, because the
-                    // owner's own `effective_alpha` was already overwritten by any ancestor's
-                    // `SetAlpha 0x76a690`.
+                    // One hop (region combine `0x772180`): the region's alpha times its owner's
+                    // `effective_alpha`, which `SetAlpha 0x76a690` already carries down the tree.
                     let alpha = owner_frame.map(|f| f.effective_alpha).unwrap_or(1.0)
                         * data.alpha.unwrap_or(1.0);
                     if let Some(fo) = state_font {
-                        // The font object's paint, **behind the severance mask on every axis** —
-                        // the same `font_explicit` gate `font::repaint` applies and the
-                        // `button_font` block below names as the law ("it loses to a face the
-                        // label FontString set for *itself*, which severs one level further
-                        // down"). Three of these six axes did not have it: face and height were
-                        // `fo.x.or(data.x)`, which makes the OBJECT outrank an explicit
-                        // `SetFont`, and the outline was written unconditionally — so a label
-                        // that called `SetFont(path, h, "OUTLINE")` for itself had all three put
-                        // back from the object on the very next extract, every frame, forever.
-                        // That is the *shape* of the report this was found under (decision 2112:
-                        // an addon's `SetFont` silently not taking); MSBT's own strings are not
-                        // a button's label and never met it, but any addon that restyles a
-                        // `<ButtonText>` did.
+                        // The font object's paint, behind the severance mask (`font_explicit`) on
+                        // every axis as in `font::repaint`: an axis the label set itself stays.
                         if !data.font_explicit.face {
                             data.font_path = fo.font.clone().or(data.font_path);
                         }
                         if !data.font_explicit.height {
                             data.font_height = fo.height.or(data.font_height);
                         }
-                        // Same severance as the colour below: a region that called
-                        // `SetShadowColor`/`SetShadowOffset` keeps its own, or the font object it
-                        // inherits would silently overwrite the value the addon just set.
                         if !data.font_explicit.shadow {
                             data.font_shadow = fo.shadow.or(data.font_shadow);
                         }
                         if !data.font_explicit.outline {
                             data.outline = fo.outline;
                         }
-                        // Test the severance MASK, which is what the sentence above claims and what
-                        // the reference pins, not `vertex_color.is_none()`. The nil-check was an
-                        // equivalent proxy for exactly as long as an explicit `SetTextColor` was the
-                        // only way a button label's colour could be populated at all; the moment
-                        // `SetTextFontObject` began linking the label to its font object (so
-                        // `GetFont`/`GetFontObject` stop answering nil), a label carried the NORMAL
-                        // object's colour and the disabled state's gray silently stopped applying.
-                        // Caught by `button_label_repaints_by_state_font_object`, which is the test
-                        // that exists for this.
+                        // The mask, not `vertex_color.is_none()`: a label linked to its font object
+                        // already carries the normal object's colour.
                         if !data.font_explicit.color {
                             data.vertex_color = fo.color.or(data.vertex_color);
                         }
-                        // The instance's justify: its own `<…Font justifyH=>` (a local write on
-                        // the embedded font, decision 1996), else the object's. Between frames
-                        // the label's own word carries the NORMAL instance's value
-                        // (`button::apply_normal_font`, the live link); a hover or a disable swaps
-                        // it here the way the client re-links the label to another instance
-                        // (`0x779810`) — behind the severance mask like every other axis, so a
-                        // label that `SetJustifyH`'d for itself keeps its own.
+                        // The instance's own `justifyH`, else the object's; a hover or disable
+                        // swaps it here, as the client re-links the label (`0x779810`).
                         if !data.font_explicit.justify_h {
                             if let Some(j) = state_justify.or(fo.justify_h) {
                                 data.justify.set_h(j);
@@ -406,12 +277,9 @@ impl UiScript {
                             }
                         }
                     }
-                    // `Button:SetFont` sits BETWEEN the two: it is a local set on the button's own
-                    // embedded font, so it outranks the font object that font inherits (a locally
-                    // set axis clears the font's `inheritMask` bit, `CSimpleFontString+0xD4`, and
-                    // is never restored), but it loses to a face the label FontString set for
-                    // *itself*, which severs one level further down. That is what `font_explicit`
-                    // is, so it is the gate here too.
+                    // `Button:SetFont` sits between: a local set on the embedded font outranks its
+                    // object (clearing the `inheritMask` bit, `CSimpleFontString+0xD4`, for good)
+                    // but loses to the label's own, so `font_explicit` gates it too.
                     if let Some(bf) = button_font {
                         if !data.font_explicit.face {
                             data.font_path = Some(bf.path.clone());
@@ -423,26 +291,14 @@ impl UiScript {
                             data.outline = super::Outline::flags(&bf.flags);
                         }
                     }
-                    // The button-level state color wins over the font object AND the region's own
-                    // explicit color — the client's Button color slots repaint the label outright.
+                    // The state colour repaints the label outright, even over its own colour.
                     if let Some(c) = state_color {
                         data.vertex_color = Some(c);
                     }
-                    // A region draws at its RESOLVED rect, and nothing else (decision 1310,
-                    // superseding 0068 v1's centered/fill-the-owner fallbacks): every drawable
-                    // region carries real anchors — authored, or the creation-path implicit anchor
-                    // (`region::implicit_creation_anchor`) — and the real resolver has no
-                    // zero-anchor fallback (a failed resolve latches unresolvable, `0x768d55`). A
-                    // region with no rect here is a templateless Lua region nobody anchored, and
-                    // the reference draws it nowhere. The bar-fill/thumb regions keep their own
-                    // fraction geometry (computed off the owner rect above) — they never carry
-                    // anchors and skip the resolver entirely, like the reference's own bar path.
-                    // The bar-fill CROPS its texture (`SetValue 0x7cc450`→`0x7833c0` drives
-                    // `0x770410`): every `SetValue` rewrites the region's 4-corner UV block with
-                    // `u1 = fraction` and recomputes the quad as `right = left + frac·width`. So
-                    // the art is sliced, never squeezed — a bar texture with a horizontal ramp
-                    // (`UI-StatusBar` brightens 124→166 left-to-right) keeps its true gradient at
-                    // every fill level.
+                    // A region draws at its resolved rect only: drawable regions carry anchors
+                    // (authored, or `region::implicit_creation_anchor`) and a failed resolve
+                    // latches unresolvable (`0x768d55`), so an unanchored Lua region draws nowhere,
+                    // as in the reference. The bar fill and thumbs keep their fraction geometry.
                     if let Some(sb) = bar_fill {
                         data.tex_coords = Some(bar_fill_uv(data.tex_coords, sb));
                     }
@@ -453,9 +309,7 @@ impl UiScript {
                         region.map(|r| r.kind),
                         Some(crate::widget::RegionKind::FontString)
                     );
-                    // The generated art wins only over an EMPTY slot: an addon that sets a real
-                    // texture on the wheel region gets its texture, the way it would on any other
-                    // region. (`ColorPickerFrame.xml` sets none, which is the whole point.)
+                    // Generated art fills only an empty slot (`ColorPickerFrame.xml` sets none).
                     let content = if let Some(art) =
                         color_art.filter(|_| data.texture.is_none() && data.fill.is_none())
                     {
@@ -474,27 +328,14 @@ impl UiScript {
                             shadow: data.font_shadow,
                             outline: data.outline,
                             alpha_gradient: data.alpha_gradient,
-                            // A property of the OWNER, not of the string: the plate's own name
-                            // and level and an addon's replacements for them are all drawn
-                            // inside the same sliding rect.
+                            // The owner's property: an addon's strings on a plate slide with it.
                             world_seat: owner
                                 .is_some_and(|o| super::nameplate::is_world_seated(&model, o)),
                         }
                     } else {
-                        // The draw gate is the TEXTURE slot, never the colour (`0x7706e0`: `+0xcc`
-                        // empty -> emit NOTHING). A
-                        // vertex colour is a tint on whatever texture exists; alone it is not
-                        // drawable content — it survives `SetTexture(nil)` by design ("a tint
-                        // outlives the art it was tinting") and used to leak out of here as a
-                        // solid plate the moment the art was cleared (the white action buttons on
-                        // a character switch; the 2026-07-10 grey wells were the same class).
-                        // A GRADIENT is drawable content in its own right — the client generates it
-                        // into the same texture slot the colour form of `SetTexture` fills, so a
-                        // region carrying only a gradient still paints. Folded to its midpoint here
-                        // because a quad carries ONE tint; the whole gradient stays on the region
-                        // (`RegionData::gradient`) so a renderer that grows a second stop needs no
-                        // API change. The approximation is visible, and it is stated there and here
-                        // rather than discovered later.
+                        // The draw gate is the texture slot, never the colour (`0x7706e0`: empty
+                        // `+0xcc` emits nothing); a vertex colour alone is a tint. A gradient fills
+                        // the texture slot, so it draws, at its midpoint since a quad has one tint.
                         let fill = data.fill.or_else(|| data.gradient.map(|g| g.midpoint()));
                         let has_path = data.texture.is_some();
                         let has_texture = has_path || fill.is_some();
@@ -503,43 +344,28 @@ impl UiScript {
                             color: has_texture
                                 .then(|| texture_color(fill, data.vertex_color))
                                 .flatten(),
-                            // ADD is the one blend mode the renderer acts on; the other four of
-                            // the client's `alphaMode` enum are carried on `RegionData::blend`
-                            // (and answered by `GetBlendMode`) but drawn as straight alpha — the
-                            // stated v1 gap, see [`crate::script::BlendMode`].
+                            // The renderer acts on ADD only: the other four `alphaMode` values
+                            // answer `GetBlendMode` but draw as straight alpha.
                             additive: data.blend == crate::script::BlendMode::Add,
                             tex_coords: data.tex_coords,
                             circular: data.circular,
                             portrait_unit: data.portrait_unit,
                             rotation: data.rotation,
-                            // Only ever set against real ART. A pathless solid has its colour
-                            // FOLDED into `color` two lines up (the renderer draws it as a tint on
-                            // a 1x1 white texel), so a shader that greys the *texel* would grey
-                            // white and change nothing — the flag would read as honoured while
-                            // doing nothing at all. No reference consumer desaturates a solid;
-                            // every one of them is an icon. Stated here rather than discovered.
+                            // Real art only: a solid here is a tint on a white texel, where the
+                            // reference's is a texel block it would grey. No stock caller
+                            // desaturates a solid.
                             desaturated: data.desaturated && has_path,
                         }
                     };
-                    // A region draws at its owner's scale — same single hop as alpha (a region
-                    // has no scale of its own; the effective-scale product (`0x76ac90`) lives on
-                    // frames).
+                    // A region draws at its owner's scale: only frames carry one (`0x76ac90`).
                     let scale = owner_frame.map(|f| f.effective_scale).unwrap_or(1.0);
                     (rect, alpha, content, clip, scale)
                 }
             };
-            // **A `Model` frame's scene draws out of its bucket's ARTWORK batch, last:** the batch
-            // object carries a third sub-array beside the quads and the text, a render-callback
-            // list, and `0x76fb00` drains the three in that order; `0x76d160` registers the model's
-            // callback only for `layer == 2` (`0x76d17f cmp ebx,2`). So a model is neither a
-            // separate pass nor the frame's own layer-0 slot — it is ARTWORK content, after that
-            // layer's quads.
-            // This is what puts the world map's player arrow over the zone overlays: both frames
-            // sit at `WorldMapFrame.level + 1`, the overlays are ARTWORK quads there, and the
-            // arrow's callback drains after them (the director's report). A model's own
-            // OVERLAY/HIGHLIGHT regions still draw over it. The
-            // CALLBACK rank (1995) is what puts the scene after that layer's font strings too,
-            // whatever their link stamps — the content key alone sat at the text rank.
+            // A `Model` frame's scene draws in its bucket's ARTWORK batch, last: `0x76fb00` drains
+            // quads, text, then render callbacks, and `0x76d160` registers the model's callback
+            // for layer 2 only (`0x76d17f cmp ebx,2`). So the world map's player arrow draws over
+            // the zone overlays at the same level, below its own OVERLAY and HIGHLIGHT regions.
             let z = match &content {
                 QuadContent::ModelPane { .. } => zkey.callback(order::DrawLayer::Artwork).raw(),
                 _ => zkey.raw(),
@@ -553,18 +379,11 @@ impl UiScript {
                 clip,
                 scale,
             });
-            // A ScrollingMessageFrame emits, on top of its own (empty) frame slot, one Text quad per
-            // visible ring line — stacked bottom-up (newest at the frame's bottom edge), each carrying
-            // its live fade alpha in the text color. The generic region path can't do this (the lines
-            // aren't declared FontStrings); the ring lives in the frame's kind state.
+            // A ScrollingMessageFrame adds one Text quad per visible ring line, stacked bottom-up
+            // with each line's fade alpha; the ring lives in its kind state, not in FontStrings.
             if let (ZTarget::Frame(fh), Some(fr)) = (target, rect) {
-                // The frame's own draw slot carries its Backdrop, behind its regions (which sort
-                // after the frame slot). A ScrollingMessageFrame's ring lines do NOT: they take the
-                // slot's ARTWORK *content* key ([`crate::order::ZKey::content`]) — the layer the
-                // client's own message font strings live in — so the frame's BACKGROUND textures
-                // stay behind them. At the bare slot the chat window's hover box painted over its
-                // own messages. Both clip like the frame's own slot (the frame IS the clipped owner
-                // when it's a scroll child).
+                // The Backdrop draws at the frame slot; the lines take the ARTWORK content key,
+                // where the client's message strings live, over the BACKGROUND (hover box) art.
                 let paint = super::layout::FramePaint { alpha, scale };
                 Self::emit_backdrop(&model, fh, fr, zkey.raw(), paint, clip, &mut out);
                 Self::emit_message_lines(
@@ -582,24 +401,11 @@ impl UiScript {
     }
 }
 
-/// The single colour a Texture region draws with: **`texel × vertexColour`**, per channel and
-/// **alpha included** (the stage-0 combine preset live at submit, `.data 0x85c250` index 1:
-/// `MODULATE(TEXTURE, DIFFUSE)` for both colour and alpha).
-///
-/// **That law is scoped to a region with no pixel shader bound** (`+0x128 == 0`). A DESATURATED
-/// region takes the fragment program instead, which supersedes the whole stage chain and reads
-/// the vertex colour's ALPHA only; its RGB never reaches the pixel. The colour computed here
-/// still travels — the renderer needs the alpha, and the RGB is simply unread on that branch
-/// (`ui_quad.wgsl`) — so nothing changes here.
-///
-/// `fill` is the region's own solid-colour texture ([`RegionData::fill`] — the client generates a
-/// real 8×8 texel block from it), so where it is set it IS the texel and the product is the drawn
-/// colour. Where it isn't, the texel comes from `path`'s art and this returns the tint alone for the
-/// renderer to modulate the sample by; `None` means untinted.
-///
-/// The correction this encodes: a `<Color 1,1,1,0.2>` trough later `SetVertexColor(0,0,0.75,0.5)`'d
-/// draws at alpha **0.1**. benilla used to store one colour slot and let the second call *replace*
-/// the first, which drew it at 0.5.
+/// The colour a Texture region draws with: texel × vertex colour per channel, alpha included (the
+/// stage-0 combine preset at submit, `.data 0x85c250` index 1: `MODULATE(TEXTURE, DIFFUSE)`). A
+/// desaturated region's pixel shader (`+0x128`) reads only the vertex alpha. `fill`, the region's
+/// solid colour, is a real 8×8 texel block in the client, so where set the product is the drawn
+/// colour; otherwise this is the tint the renderer modulates the art by, `None` for untinted.
 fn texture_color(fill: Option<[f32; 4]>, vertex: Option<[f32; 4]>) -> Option<[f32; 4]> {
     match (fill, vertex) {
         (Some(f), Some(v)) => Some([f[0] * v[0], f[1] * v[1], f[2] * v[2], f[3] * v[3]]),
@@ -608,9 +414,8 @@ fn texture_color(fill: Option<[f32; 4]>, vertex: Option<[f32; 4]>) -> Option<[f3
     }
 }
 
-/// A StatusBar's bar-fill rect: the frame rect scaled by the value fraction — rightward from the
-/// left edge (horizontal) or upward from the bottom (vertical), the documented fill directions
-/// (reverse-fill is an Era extension, not modeled yet).
+/// A StatusBar's fill rect: the frame rect scaled by the value fraction, rightward from the left
+/// edge or upward from the bottom (1.12 has no reverse fill).
 fn bar_fill_rect(r: Rect, sb: &crate::widget::StatusBarState) -> Rect {
     let f = sb.fraction();
     if sb.vertical {
@@ -620,18 +425,13 @@ fn bar_fill_rect(r: Rect, sb: &crate::widget::StatusBarState) -> Rect {
     }
 }
 
-/// A StatusBar's bar-fill UV sub-rect: `base` (its `<TexCoords>`/`SetTexCoord`, or the full texture)
-/// sliced to the value fraction along the fill axis — `[left, right, top, bottom]`, 0..1, top-left
-/// origin.
-///
-/// The client CROPS rather than scales: `SetValue`
-/// (`0x7cc450`→`0x7833c0`) drives `0x770410`, which writes the 4-corner UV block (`+0x104..+0x120`)
-/// with `u1 = GetValue()` and recomputes `right = left + frac·width`. Horizontal is the verified
-/// case; VERTICAL mirrors it up the `v` axis (bottom-up fill ⇒ the *bottom* edge of the art is
-/// pinned) — inferred from the same block, not separately pinned.
+/// A StatusBar's fill UVs: `base` (its `<TexCoords>`/`SetTexCoord`, or the full texture) cut to
+/// the value fraction along the fill axis, `[left, right, top, bottom]` in 0..1 from top-left. The
+/// client crops rather than scales: `SetValue` (`0x7cc450` → `0x7833c0`) drives `0x770410`, which
+/// writes the 4-corner UV block (`+0x104..+0x120`) with `u1` set to the fill fraction. Vertical
+/// mirrors it up `v`, pinning the art's bottom edge (inferred, not traced).
 fn bar_fill_uv(base: Option<TexCoords>, sb: &crate::widget::StatusBarState) -> TexCoords {
-    // The fill crop is inherently the 4-edge form; an affine base (no live StatusBar uses one)
-    // contributes its bounding edges.
+    // An affine base contributes its bounding edges (no live StatusBar uses one).
     let [l, r, t, b] = base.map(|tc| tc.edges()).unwrap_or([0.0, 1.0, 0.0, 1.0]);
     let f = sb.fraction();
     TexCoords::Rect(if sb.vertical {
diff --git a/crates/benilla-ui/src/script/follow.rs b/crates/benilla-ui/src/script/follow.rs
index 8d90692c..4fc33bbf 100644
--- a/crates/benilla-ui/src/script/follow.rs
+++ b/crates/benilla-ui/src/script/follow.rs
@@ -1,44 +1,22 @@
-//! The auto-follow **Era API surface** — two globals, no state.
-//!
-//! [`super::duel`]'s shape exactly: everything the UI *reads* about a follow arrives as an event
-//! argument (`AUTOFOLLOW_BEGIN`'s name), so there is no snapshot to push — only the outbound half.
-//! Each call queues a [`FollowRequest`] the app drains ([`super::UiScript::take_follow_requests`])
-//! and turns into its own follow start, keeping the engine free of ECS reach (decision 0068 §3).
-//!
-//! The two are the reference's own follow bindings, and between them they cover every shipped call
-//! site in the 1.12 FrameXML:
-//!
-//! | binding | called by | subject |
-//! |---|---|---|
-//! | `FollowUnit(unit)` | `SlashCmdList["FOLLOW"]` with no argument | a unit token |
-//! | `FollowByName(name, exactMatch)` | `SlashCmdList["FOLLOW"]` with one; `UnitPopup_OnClick`'s FOLLOW row | a name |
-//!
-//! `FollowByName` is `0x489ec0`, one more caller of the shared by-name resolver `0x493aa0` —
-//! typemask `0x10` (players only) and filter mode 2 (`CanAssist` + alive), with **the second Lua
-//! argument steering exact-only matching** (decision 0886's table). That argument is what makes the
-//! popup row different from the slash command: `UnitPopup.lua` passes `FollowByName(name, 1)`, so
-//! clicking *Follow* on a menu that already names the unit exactly must not prefix-match its way
-//! onto somebody else standing nearby, while `/follow rag` still may.
-//!
-//! benilla parses slash lines in Rust rather than in Lua (decision 0881), so the chat half of that
-//! table enters the app's follow funnel directly; these globals are the *other* half — the shipped
-//! UI's, and any addon's.
+//! `FollowUnit` and `FollowByName`; each call queues a [`FollowRequest`] the app drains.
+//! `FollowUnit("target")` is a bare `/follow` and the `FOLLOWTARGET` binding. `FollowByName`
+//! (`0x489ec0`) calls the by-name resolver `0x493aa0` for players (`0x10`) who `CanAssist` and are
+//! alive, with its second argument as the exact-only flag: `UnitPopup.lua:623` passes 1, so the
+//! menu never prefix-matches someone else, while `/follow rag` may. benilla parses `/follow` in
+//! Rust, so these globals serve the stock UI and addons.
 
 use mlua::Lua;
 
 use super::Model;
 
-/// Outbound follow intents queued by the Era API calls, drained by the app
-/// ([`super::UiScript::take_follow_requests`]). Plain data — [`super::duel::DuelRequest`]'s twin.
+/// A follow intent queued by the globals.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum FollowRequest {
-    /// `FollowUnit(unit)` — follow whoever a unit token points at. The app resolves the token;
-    /// `"target"` is the bare `/follow`, and takes the selection **whatever it is** (the reference
-    /// applies no typemask on this path — decision 0890).
+    /// `FollowUnit(unit)`: whoever the token names, of any type; the reference applies no
+    /// typemask here.
     ByUnit(String),
-    /// `FollowByName(name, exactMatch)` — follow a player found by name. `exact` is the second Lua
-    /// argument: set, it skips the resolver's longest-common-prefix tier and admits only a
-    /// whole-string (case-insensitive) hit.
+    /// `FollowByName(name, exactMatch)`: with `exact`, the resolver skips its longest-prefix tier
+    /// and takes only a whole-name, case-insensitive match.
     ByName { name: String, exact: bool },
 }
 
@@ -49,11 +27,10 @@ impl super::UiScript {
     }
 }
 
-/// Register the follow globals (the same style/place [`super::duel`] registers its own).
+/// Register the follow globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // FollowUnit(unit) — `SlashCmdList["FOLLOW"]`'s no-argument arm, `FollowUnit("target")`.
     g.set(
         "FollowUnit",
         lua.create_function(|lua, unit: String| {
@@ -63,16 +40,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // FollowByName(name, exactMatch) — the unit popup's Follow row passes `1`; the slash command
-    // passes nothing, which is the prefix-matching case (`nil` is false here, as in the ref, where
-    // the argument reaches `0x493aa0` as a plain zero).
     g.set(
         "FollowByName",
         lua.create_function(|lua, (name, exact): (String, Option<mlua::Value>)| {
-            // Absent is the slash command's case; the popup row passes `1`. A numeric zero counts
-            // as false as well — no shipped caller passes one, and treating it that way is the
-            // reading both plausible arg-2 fetches on the C side (`lua_toboolean` vs a number
-            // compare) agree on for every value that can actually arrive here.
+            // The reference reads this with `GetBoolOrDefault` (`0x6f1c10`), default false; here
+            // nil, false and 0 are false and any other value is true.
             let exact = match exact {
                 None | Some(mlua::Value::Nil) | Some(mlua::Value::Boolean(false)) => false,
                 Some(mlua::Value::Integer(n)) => n != 0,
diff --git a/crates/benilla-ui/src/script/font.rs b/crates/benilla-ui/src/script/font.rs
index b5e3179c..cd68b0a2 100644
--- a/crates/benilla-ui/src/script/font.rs
+++ b/crates/benilla-ui/src/script/font.rs
@@ -1,73 +1,25 @@
-//! **Font objects as first-class Lua objects** — a `<Font name="GameFontNormal">` is not merely a
-//! style record the loader flattens, it is an *object* the client publishes as the global
-//! `GameFontNormal`, with its own method table.
+//! Font objects: a `<Font name=…>` or a `CreateFont` font is a Lua object, published as the global
+//! of its name with its own method table. Stock FrameXML never calls this API; addons do.
 //!
-//! ## Why this exists
+//! The reference's class is `CSimpleFont` (`0x87a454`). Its method table (`0x87c7c8`) has 22
+//! entries (`mov edx,0x16` at `0x7a10d5`), and its lookup `0x7a1100` has no base-class fallback.
+//! All are here but the `SetSpacing` pair ([`install`]); `CopyFontObject` is the one a FontString
+//! lacks. A named font is published by `0x783870` through `SetName 0x784150` and `CreateLuaHandle
+//! 0x701bd0`, which leaves a non-nil `_G[name]` alone (`0x701cb8`).
 //!
-//! 1.12's own FrameXML never touches the API — `grep -c FontObject` over the reference
-//! FrameXML's own `.lua` is **0** — so the whole surface is addon-facing, and
-//! the addon corpus (`benilla_formats::addon_corpus`, 218 addons) is where the demand is:
+//! A setter repaints every FontString that inherits the font. The reference links dependents into
+//! the font's list (`+0x74`/`+0x78`) and each setter ends in `NotifyDependents 0x784180`, calling
+//! `OnFontChanged` (`0x77e4b0` on a font, `0x773530` then `0x770800` on a FontString); here each
+//! setter writes the [`FontObject`] and calls [`propagate`]. A local setter clears its property's
+//! bit in the dependent's inherit mask (`+0x2c`, FontString `+0xd4`) and nothing restores it, so a
+//! colour set on a FontString survives a later `SetFontObject`: [`RegionData::font_explicit`] is
+//! that mask. `+0x38` is not it; its high bits mark a held value, which the inheriting merge also
+//! sets (`0x7709d3`).
 //!
-//! | call shape | sites | note |
-//! |---|---|---|
-//! | `x:SetFontObject(GameFontNormal)` (bare global) | 3,180 | the form we did **not** accept |
-//! | `x:SetFontObject("GameFontNormal")` (string) | 6 | the only form we did accept |
-//! | `x:GetFontObject():GetTextColor()` | 65 | needs an OBJECT back, not a name |
-//! | `GameTooltipHeaderText:GetFont()` and kin | 268 | `Tablet-2.0`'s header-size probe |
-//! | `GameFont*:GetTextColor/GetShadowOffset/GetShadowColor` | 13 | |
-//! | `CreateFont(name)` | 3 | `_Nameplates`, `!OmniCC`, `FonzAppraiser` |
-//! | `f:CopyFontObject(GameFontHighlightSmall)` | 1 | Font-on-Font |
-//!
-//! ## The method surface, and where it came from
-//!
-//! The Font method table is `.data 0x87c7c8` with **22 entries** — the count read from `mov
-//! edx,0x16` at `0x7a10d5`, not from a run-length scan, which merges neighbouring tables and
-//! reports a bogus 54. Its lookup `0x7a1100` has **no base-class fallback**, so 22 is the entire
-//! surface:
-//! `GetObjectType · IsObjectType · GetName · SetFontObject · GetFontObject · CopyFontObject ·
-//! SetFont · GetFont · SetAlpha · GetAlpha · SetTextColor · GetTextColor · SetShadowColor ·
-//! GetShadowColor · SetShadowOffset · GetShadowOffset · SetSpacing · GetSpacing · SetJustifyH ·
-//! GetJustifyH · SetJustifyV · GetJustifyV`. All implemented here **except the `Spacing` pair** —
-//! see [`install`]. `CopyFontObject` is the only one of the 22 a FontString does not also have.
-//!
-//! The class is **`CSimpleFont`** (`__FILE__` `0x87a454`), and a named font is published by
-//! `0x783870` → `SetName 0x784150` → `CreateLuaHandle 0x701bd0` → `_G[name] = handle` at
-//! `0x701cb8`, **skipped when the global is already non-nil** — the same non-overwriting rule
-//! [`publish_global`] applies on the frame side.
-//!
-//! ## Mutability — the deliberate part
-//!
-//! `GameFontNormal:SetFont(…)` on the real client repaints every FontString that inherits it, and
-//! the mechanism is not a copy: `SetFontObject` stores a parent pointer (`+0x28`, FontString
-//! `+0xd0`) **and** links the instance into the parent's intrusive dependents list (`+0x74`/`+0x78`,
-//! link offset `+0x70`). Every setter ends in `vtable[+0x14]` = `NotifyDependents 0x784180`, which
-//! walks that list and calls each dependent's `OnFontChanged` — `0x77e4b0` for a font (which
-//! cascades) and `0x773530`→`0x770800` for a FontString (which re-drives its real setters).
-//!
-//! We model that with an eager push instead of an intrusive list, so no reader changes: every
-//! setter here writes the [`FontObject`] record and then calls [`propagate`], which re-paints every
-//! region whose [`RegionData::font_object`] names it.
-//!
-//! **The severance rule, corrected by the bytes.** Our first cut read `FONTINSTANCE+0x038` as an
-//! "explicitly set" mask and reset it on every `SetFontObject`. Both halves were wrong. `+0x38`'s
-//! low bits are a transient broadcast flag and its high bits mean "has a resolved value" — set by
-//! the *inheriting* merge too (`0x7709d3`). The real "stop inheriting this property" signal is a
-//! **cleared** bit in the previously-unrecorded **inheritMask at `+0x2c`** (FontString `+0xd4`,
-//! per-axis justify at `+0x124`), cleared by each local setter and **never restored** — so a
-//! FontString that set its own colour stays severed *across a later `SetFontObject`*.
-//! [`RegionData::font_explicit`] is that mask, and nothing resets it.
-//!
-//! The source side gates too: a merge only copies properties the source actually holds, so a font
-//! freshly minted by [`create_font`] (`mask == 0`) copies **nothing** — see [`repaint`].
-//!
-//! **What we deliberately do not model, now a verified divergence rather than an unknown:** a
-//! `<Font inherits="OtherFont">` chain stays flattened at load (`Loader::do_font`), so mutating
-//! `MasterFont` does not walk down to `GameFontNormal`. The reference links these live as well —
-//! `LoadXML 0x783c30` calls the *same* `0x770c60` link function `SetFontObject` calls
-//! (`0x783ce6`), and `font=` likewise (`0x783d22`). Flattening is what this arc was scoped to keep;
-//! the cost is bounded and measured: **0 corpus addons mutate a declared font object at all** —
-//! every mutation in 218 addons is of the addon's own [`create_font`] object — so the Font→Font
-//! half has no demand behind it and the Font→FontString half has all of it.
+//! Not built: a `<Font inherits=…>` chain is flattened at load (`Loader::do_font`), so mutating
+//! `MasterFont` does not reach `GameFontNormal`, where the reference links it live: `LoadXML
+//! 0x783c30` calls the `SetFontObject` link `0x770c60` for `inherits=` (`0x783ce6`) and `font=`
+//! (`0x783d22`). No corpus addon mutates a declared font object.
 
 use mlua::{Lua, Table, Value};
 
@@ -79,25 +31,18 @@ use super::{FontObject, FontShadow, Model, Outline, RegionData};
 
 /// The shared metatable of every font-object handle.
 const REG_FONT_META: &str = "__benilla_font_meta";
-/// The font-object method table the metatable's `__index` dispatches through.
+/// The font-object method table, which is the metatable's `__index`.
 const REG_FONT_METHODS: &str = "__benilla_font_methods";
 /// name → handle, so `GameFontNormal == GameFontNormal` and a re-declared `<Font>` keeps identity.
 const REG_FONT_WRAPPERS: &str = "__benilla_font_wrappers";
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The handle
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The handle ───────────────────────────────────────────────────────────────────────────────
 
-/// Get-or-create the Lua handle for a named font object.
+/// Get or create the Lua handle for a named font object. Keyed by name, which every font has (an
+/// unnamed `<Font>` is dropped at parse), so a re-declared `<Font>` updates its record in place.
 ///
-/// Identity is the **name**, not a minted id: every font object in 1.12 has one (an unnamed
-/// `<Font>` is warned and dropped at parse time, and [`create_font`] requires one), and keying by
-/// name is what makes a re-declared `<Font name="GameFontNormal">` update the record *in place*
-/// while every `SetFontObject(GameFontNormal)` already taken keeps pointing at the same object.
-///
-/// `T[0]` is the name string rather than the frame/region wrapper's `LightUserData` id, so
-/// [`super::object::decode_id`] rejects a font handle passed where a frame is wanted, with its own
-/// message, instead of decoding a garbage id.
+/// `T[0]` holds the name, not a frame id, so a font handle passed where a frame is wanted is
+/// rejected rather than decoded.
 pub(crate) fn wrapper(lua: &Lua, name: &str) -> mlua::Result<Table> {
     let wrappers: Table = lua.named_registry_value(REG_FONT_WRAPPERS)?;
     if let Value::Table(t) = wrappers.get::<Value>(name)? {
@@ -111,16 +56,13 @@ pub(crate) fn wrapper(lua: &Lua, name: &str) -> mlua::Result<Table> {
     Ok(t)
 }
 
-/// Publish `_G[name]` as this font object's handle — what makes `fs:SetFontObject(GameFontNormal)`
-/// resolve to anything at all. Non-overwriting, exactly like the frame side's [`publish_global`].
-///
-/// Called by `Loader::do_font` for every top-level `<Font name=…>`, and by [`create_font`].
+/// Publish the handle as `_G[name]`, leaving a non-nil global alone as [`publish_global`] does.
 pub(crate) fn publish(lua: &Lua, name: &str) -> mlua::Result<()> {
     let t = wrapper(lua, name)?;
     publish_global(lua, name, &t)
 }
 
-/// The name behind a font handle, or an error naming what was actually passed.
+/// The name a font handle holds in `T[0]`.
 fn name_of(this: &Table) -> mlua::Result<String> {
     match this.raw_get::<Value>(0)? {
         Value::String(s) => Ok(s.to_str()?.to_string()),
@@ -130,17 +72,9 @@ fn name_of(this: &Table) -> mlua::Result<String> {
     }
 }
 
-/// Accept any of the **three** forms the real binding takes and return the registry name, with
-/// `None` for the nil form (clear the link).
-///
-/// The reference's own usage string settles the shape — `.rdata 0x87c5cc` reads verbatim
-/// `Usage: %s:SetFontObject(font or "font" or nil)`. So all three are real: the object
-/// (3,180 of the corpus's 3,186 sites), the name string (our own shipped `assets/ui` plus 6 corpus
-/// sites), and nil.
-///
-/// Anything else — a frame, a number, a missing argument — is an **error**, and in the reference
-/// too: every rejection there is `luaL_error 0x6f4940`, which longjmps and aborts the call rather
-/// than no-opping. A font that quietly fails to apply is the silent-drop class of 1203/1205/1211.
+/// A font argument as a registry name, `None` for nil: an object, a name or nil, the three forms of
+/// the reference's usage `SetFontObject(font or "font" or nil)` (`0x87c5cc`). Anything else
+/// raises, as the reference's `luaL_error 0x6f4940` does.
 pub(super) fn resolve(verb: &str, v: &Value) -> mlua::Result<Option<String>> {
     match v {
         Value::Nil => Ok(None),
@@ -158,8 +92,7 @@ pub(super) fn resolve(verb: &str, v: &Value) -> mlua::Result<Option<String>> {
     }
 }
 
-/// [`resolve`] for the verbs that genuinely refuse nil — `CopyFontObject` is the one
-/// (`0x7a01b0`: it value-copies and re-parents, so there is nothing to copy *from*).
+/// [`resolve`] refusing nil, for `CopyFontObject`, which has nothing to copy from (`0x7a01b0`).
 fn resolve_required(verb: &str, v: &Value) -> mlua::Result<String> {
     resolve(verb, v)?.ok_or_else(|| {
         mlua::Error::runtime(format!(
@@ -168,23 +101,15 @@ fn resolve_required(verb: &str, v: &Value) -> mlua::Result<String> {
     })
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The live link: font object → the regions that inherit it
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The live link: a font object to the regions that inherit it ──────────────────────────────
 
-/// Copy a font object's paint onto one region, **skipping every property that region severed by
-/// setting for itself** ([`RegionData::font_explicit`]).
+/// Copy a font object's paint onto one region, skipping each property the region set itself
+/// ([`RegionData::font_explicit`]) and each the font does not hold: the reference gates every merge
+/// on the source's held-value bits (`+0x38`, the merge `0x770910`), so an empty `CreateFont` font
+/// changes nothing.
 ///
-/// **A property the source does not hold copies nothing.** The reference gates every merge on the
-/// source's own has-a-value mask (`+0x38`'s high bits, set by the merge `0x770910`): a font freshly
-/// minted by `CreateFont` has `mask == 0`, so `SetFontObject`-ing it onto a FontString leaves that
-/// string exactly as it was — no blanking, no fallback to a default. `_Nameplates` relies on
-/// nothing here, but `!OmniCC`'s probe font would otherwise wipe a label it was pointed at.
-///
-/// Residue: [`Outline`] has no "unset" state distinct from `NONE`, so an outline is still written
-/// unconditionally. Every shipped `<Font>` flattens from `MasterFont`, which declares no outline,
-/// so the two readings coincide for all of them; a `CreateFont` object pointed at an outlined
-/// FontString is the one case that differs, and it has no caller.
+/// The outline is always copied, as [`Outline`] has no unset state; only an empty `CreateFont` font
+/// on an outlined FontString differs from the reference, clearing the outline.
 pub(crate) fn repaint(d: &mut RegionData, fo: &FontObject) {
     let ex = d.font_explicit;
     if !ex.face {
@@ -222,12 +147,9 @@ pub(crate) fn repaint(d: &mut RegionData, fo: &FontObject) {
     }
 }
 
-/// Re-paint every region that inherits `name` — the `SetFont`/`SetTextColor`/… propagation the real
-/// client gets for free from its live `parentFontObject`. Linear in regions, on a human-rate path
-/// (a font-object setter is an addon config action, never a frame path).
-///
-/// Per-state **button** label fonts need no equivalent: they are stored as names and re-resolved at
-/// every `extract`, so a mutated font object reaches them on the next frame by construction.
+/// Repaint every region that inherits `name`, as the reference's live parent link does. Linear in
+/// regions: font-object setters are addon configuration, never per frame. Button state fonts are
+/// stored by name and re-resolved at every `extract`, so they need no push.
 pub(crate) fn propagate(model: &mut Model, name: &str) {
     let Some(fo) = model.font_object(name).cloned() else {
         return;
@@ -237,14 +159,11 @@ pub(crate) fn propagate(model: &mut Model, name: &str) {
             repaint(d, &fo);
         }
     }
-    // A fan-out cannot name its regions one by one without a second pass; a font-object edit is
-    // a human-rate action, so the measure ledger goes conservative and the next sweep walks the
-    // roster once, exactly as every sweep did before the ledger existed.
+    // A fan-out cannot name its regions without a second pass, so every region is re-measured.
     model.touch_measure_all();
 }
 
-/// Run `f` over the named font object's record, then propagate the change to its dependants.
-/// The one write path every setter below goes through.
+/// Run `f` on the named font object's record, then [`propagate`]: every setter's one write path.
 fn edit<R>(lua: &Lua, this: &Table, f: impl FnOnce(&mut FontObject) -> R) -> mlua::Result<R> {
     let name = name_of(this)?;
     let mut model = lua.app_data_mut::<Model>().expect("model");
@@ -256,33 +175,20 @@ fn edit<R>(lua: &Lua, this: &Table, f: impl FnOnce(&mut FontObject) -> R) -> mlu
     Ok(out)
 }
 
-/// Read the named font object's record (a clone — the records are small and this is human-rate).
+/// A copy of the named font object's record.
 fn read(lua: &Lua, this: &Table) -> mlua::Result<FontObject> {
     let name = name_of(this)?;
     let model = lua.app_data_ref::<Model>().expect("model");
     Ok(model.font_object(&name).cloned().unwrap_or_default())
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// install — the method table, the metatable, and CreateFont
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── install: the method table, the metatable and CreateFont ──────────────────────────────────
 
-/// Build the font-object method table and metatable, and register the `CreateFont` global.
+/// Build the font-object method table and metatable, and register `CreateFont`.
 ///
-/// **Implemented** (20 of the reference table's 22): `GetObjectType`, `IsObjectType`, `GetName`,
-/// `SetFontObject`, `GetFontObject`, `CopyFontObject`, `SetFont`, `GetFont`, `SetAlpha`,
-/// `GetAlpha`, `SetTextColor`, `GetTextColor`, `SetShadowColor`, `GetShadowColor`,
-/// `SetShadowOffset`, `GetShadowOffset`, `SetJustifyH`, `GetJustifyH`, `SetJustifyV`,
-/// `GetJustifyV`.
-///
-/// **Deliberately absent: `SetSpacing`/`GetSpacing`.** We model no line spacing anywhere — neither
-/// [`RegionData`] nor the text layout has the field, and the line pitch is the font height — so a
-/// `SetSpacing` here could only store a number nobody draws. That is precisely the silently-ignored
-/// setter this codebase keeps being bitten by (1203, 1205, 1211), and the alternative failure is
-/// the good one: a missing method raises `attempt to call method 'SetSpacing' (a nil value)`, which
-/// names itself. Demand behind it is **zero** — no call on any font-object global anywhere in the
-/// 218-addon corpus, and 1.12's own FrameXML never calls the font API at all. When spacing becomes
-/// a thing the renderer honours, the pair lands with it.
+/// Deviation: `SetSpacing`/`GetSpacing` are absent, because nothing renders line spacing (the line
+/// pitch is the font height): a missing method raises and names itself, where a stored, undrawn
+/// value would fail silently.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     lua.set_named_registry_value(REG_FONT_WRAPPERS, lua.create_table()?)?;
 
@@ -293,17 +199,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "GetObjectType",
         lua.create_function(|_, _this: Table| Ok("Font"))?,
     )?;
-    // **`1`/`nil`, never a Lua boolean** (decision 2118's law; 2142 found this copy). The
-    // reference's Font object has its OWN `IsObjectType` (`0x79fe60`, table `0x87c7c8`) distinct
-    // from the Region base's (`0x7a1290`, `0x87c9b8`), and the shapes table types both
-    // `(nil) | (number)`. This one answered a Rust `bool` — the fourth copy of a house rule that
-    // three neighbours got right, which is exactly the drift 2118 consolidated `flag` to stop, and
-    // it was invisible until the shape gate learned to probe the Font object at all.
-    //
-    // The ARGUMENT contract is a separate question and is not claimed here: `region.rs`'s twin
-    // documents the reference's `Usage: %s:IsObjectType("TYPE")` raise and its number-stringifying
-    // arm from a byte read of `0x7a1290`; nobody has read `0x79fe60`'s, so this copy keeps mlua's
-    // own coercion rather than pretending to that finding.
+    // `1` or nil, never a boolean, like the Region's (`0x7a1290`): the Font's own `IsObjectType`
+    // (`0x79fe60`) answers a number. Its argument handling is untraced; mlua's coercion applies.
     m.set(
         "IsObjectType",
         lua.create_function(|_, (_this, ty): (Table, String)| {
@@ -316,11 +213,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── the font-object-on-font-object pair ─────────────────────────────────────────────────
-    // SetFontObject(other) — adopt another object's whole paint. On a Font (rather than a
-    // FontString) the reference's live-parent distinction is invisible to us because we flatten
-    // Font→Font chains at load (module doc); this is therefore the same copy CopyFontObject makes,
-    // and both are spelled out separately so a later Font→Font link has two named places to land.
-    // It takes nil like its FontString twin — with no Font→Font link to sever, that is a no-op.
+    // SetFontObject(other): on a Font, the same copy as CopyFontObject, since Font chains are
+    // flattened (module doc); nil is a no-op, with no link to sever.
     m.set(
         "SetFontObject",
         lua.create_function(|lua, (this, other): (Table, Value)| {
@@ -330,9 +224,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             }
         })?,
     )?;
-    // CopyFontObject(other) — `FonzAppraiser`'s pattern: mint with CreateFont, copy a shipped
-    // object's paint, then override the face (`gui.lua:27-30`). Unlike `SetFontObject` it
-    // **rejects nil** (`0x7a01b0` value-copies and re-parents, so there is nothing to copy from).
+    // CopyFontObject(other): refuses nil (`0x7a01b0` value-copies and re-parents).
     m.set(
         "CopyFontObject",
         lua.create_function(|lua, (this, other): (Table, Value)| {
@@ -340,28 +232,22 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             copy_from(lua, &this, &other, "CopyFontObject")
         })?,
     )?;
-    // GetFontObject() — a Font object has no parent link in our model (chains are flattened at
-    // load), so this is honestly nil rather than a self-reference that would read as a link.
+    // GetFontObject(): always nil; with Font chains flattened, a Font has no parent link.
     m.set(
         "GetFontObject",
         lua.create_function(|_, _this: Table| Ok(Value::Nil))?,
     )?;
 
     // ── face ────────────────────────────────────────────────────────────────────────────────
-    // SetFont(path, height [, flags]) → **the number 1, or nil** — the reference's exact return
-    // shape (1 value either way; a font file that fails to load yields nil, never an error).
-    // `!OmniCC/main.lua:41` uses it as a *font-file validity probe* (`if not
-    // OmniCCFont:SetFont(saved, size) then revert end`), so it is not decorative. We answer 1 for
-    // any non-empty path — face availability is the renderer's concern here, the atlas falls back
-    // per face — and nil for an empty/absent one, so a probe with a blank saved variable reverts.
+    // SetFont(path, height [, flags]) → 1, or nil when the font file fails to load, which does not
+    // raise. Deviation: any non-empty path answers 1, because the atlas falls back per face and no
+    // load fails; an empty one answers nil.
     m.set(
         "SetFont",
         lua.create_function(
             |lua, (this, file, height, flags): (Table, Value, Value, Option<String>)| {
-                // The same gate the FontString and EditBox tables enter — one `0x79f210`, three
-                // entry points. This side used to take `Option`s, so `SetFont()` answered **nil**
-                // where the reference raises `0x87c69c`; the FontString's copy answered the boolean
-                // `true` for everything. Neither was the shared routine's contract.
+                // The argument gate the FontString and EditBox tables share (`0x79f210`); a
+                // missing argument raises (`0x87c69c`).
                 let (path, height) = super::font_block::set_font_args(&file, &height, "Font")?;
                 let ok = !path.is_empty();
                 edit(lua, &this, |fo| {
@@ -370,9 +256,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     }
                     fo.height = Some(height);
                     if let Some(f) = flags {
-                        // The LUA flags spelling ("OUTLINE"/"THICKOUTLINE"), not the XML
-                        // attribute's ("NORMAL"/"THICK") — this read the XML one, so every
-                        // `GameFontNormal:SetFont(f, h, "OUTLINE")` silently cleared the outline.
+                        // The Lua flag spelling (`OUTLINE`, `THICKOUTLINE`), not the XML
+                        // attribute's (`NORMAL`, `THICK`).
                         fo.outline = Outline::flags(&f);
                     }
                 })?;
@@ -380,14 +265,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             },
         )?,
     )?;
-    // GetFont() → path, height, flags. `Tablet-2.0.lua:289`'s `_, headerSize =
-    // GameTooltipHeaderText:GetFont()` is the corpus's single biggest font-object read (268 sites),
-    // and it does arithmetic on the second value.
-    //
-    // **An unset Font answers `(nil, 0, "")`, all three ctor-determined** — `0x783a40` writes
-    // `[esi+0x48]` and `[esi+0x4c]` from a zeroed register, and its `0x41e3a0(NULL)` stores the
-    // shared empty record whose `char*` is NULL, which `lua_pushstring` turns into nil. So the
-    // height is the NUMBER zero, not nil (decision 2129).
+    // GetFont() → path, height, flags. An unset Font answers nil, 0, "": the constructor
+    // `0x783a40` zeroes the height and stores a NULL path (`0x41e3a0`), which pushes as nil.
     m.set(
         "GetFont",
         lua.create_function(|lua, this: Table| {
@@ -401,8 +280,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── colour, and the alpha that is its fourth channel ────────────────────────────────────
-    // Shape C on the three channels (`SetTextColor 0x79f4d0`, `2=C 3=C 4=C 5=B`): a nil or
-    // non-number is 0.0, never a raise (1973).
+    // Shape C on r, g, b (`SetTextColor 0x79f4d0`): nil or a non-number is 0, never a raise.
     m.set(
         "SetTextColor",
         lua.create_function(
@@ -426,11 +304,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok((c[0], c[1], c[2], c[3]))
         })?,
     )?;
-    // SetAlpha/GetAlpha on a FontInstance are its text colour's alpha channel, not a separate slot:
-    // a FontInstance has exactly one colour word (`FONTINSTANCE+0x058 textColor`, a packed
-    // CImVector) and no alpha field of its own, so there is nowhere else for an alpha to live. Zero
-    // corpus sites; implemented because a duck-typed `if f.SetAlpha` should find it and because the
-    // semantics follow from the storage rather than from a guess.
+    // SetAlpha/GetAlpha are the text colour's alpha: a FontInstance has one packed colour
+    // (`+0x58`) and no alpha of its own.
     m.set(
         "SetAlpha",
         lua.create_function(|lua, (this, a): (Table, f32)| {
@@ -446,13 +321,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── shadow ──────────────────────────────────────────────────────────────────────────────
-    // Either half may be set before the other, so both start from whatever is there (or a zero
-    // offset / opaque black) rather than refusing a shadow that is only half-declared.
     m.set(
         "SetShadowColor",
         lua.create_function(
-            // Shape C on r, g, b (`Font:SetShadowColor 0x79f730`, `2=C 3=C 4=C 5=B`) — bare
-            // `lua_tonumber`, no gate, never raises.
+            // Shape C on r, g, b (`Font:SetShadowColor 0x79f730`): never raises.
             |lua, (this, r, g, b, a): (Table, Value, Value, Value, Option<f32>)| {
                 let (r, g, b) = (
                     crate::script::object::as_f32(&r),
@@ -499,16 +371,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── justification ───────────────────────────────────────────────────────────────────────
-    //
-    // The token table, the whole-string match, the raise on a miss and the cross-axis clear are
-    // [`crate::justify`]'s, shared with the FontString table's identical pair. This side used to
-    // `.trim()` its argument and the other did not — one law, two transcriptions, and at most one
-    // of them could be right (the bytes say no trim: `SStrCmpI` compares the whole string).
-    //
-    // `justify_h`'s `Option` here is *inheritance*, not the reference's cleared axis: `None` means
-    // "this font object does not specify justification", which is what the resolve at
-    // [`resolve_font_object`] and `extract.rs` test. A fresh object therefore reads CENTER/MIDDLE
-    // through `unwrap_or_default`, which is also the client's ctor default `0x212`.
+    // Parsing is [`crate::justify`]'s, shared with the FontString pair: `SStrCmpI` over the whole
+    // string, no trim. `None` means the font does not specify the axis (inheritance), not a
+    // cleared axis; a fresh object reads CENTER/MIDDLE, the constructor default `0x212`.
     m.set(
         "SetJustifyH",
         lua.create_function(|lua, (this, j): (Table, String)| {
@@ -549,11 +414,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     let meta = lua.create_table()?;
-    // **`__index` is the method TABLE, not a dispatcher function** (decision 2310). A Rust
-    // `__index` turns every `fo.GetFont` — a plain table index in the source — into a Lua→Rust→Lua
-    // round trip plus a named-registry string lookup; measured at ~200 ns against ~9 ns for the
-    // table form, on a path every widget call in the client begins with. The table is mutated in
-    // place by nothing after this point, so pointing at it cannot go stale.
+    // `__index` is the method table itself, not a function: a table index costs ~9 ns against
+    // ~200 ns through a Rust dispatcher, and nothing mutates the table after this point.
     meta.set("__index", m.clone())?;
     lua.set_named_registry_value(REG_FONT_METHODS, m)?;
     lua.set_named_registry_value(REG_FONT_META, meta)?;
@@ -563,8 +425,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// The body behind `SetFontObject`/`CopyFontObject` on a Font: take the *other* object's resolved
-/// paint wholesale.
+/// `SetFontObject`/`CopyFontObject` on a Font: take the other object's paint wholesale.
 fn copy_from(lua: &Lua, this: &Table, other: &Value, verb: &str) -> mlua::Result<()> {
     let src = resolve_required(verb, other)?;
     let paint = {
@@ -578,20 +439,11 @@ fn copy_from(lua: &Lua, this: &Table, other: &Value, verb: &str) -> mlua::Result
     edit(lua, this, |fo| *fo = paint)
 }
 
-/// `CreateFont(name)` — mint a font object at runtime and publish it as the global `name`, the
-/// twin of a `<Font name=…>` declaration. Returns the handle.
+/// `CreateFont(name)`: mint a font object, publish it as the global `name` and return it; addons
+/// use both. An existing name returns that object unchanged and unrepublished (`0x7839ab`).
 ///
-/// Both halves are load-bearing in the corpus and neither can be dropped: `_Nameplates.lua:149` and
-/// `FonzAppraiser/mods/gui/gui.lua:27` keep the **return**, while `!OmniCC/main.lua:40-41` throws it
-/// away and reads the **global** on the very next line.
-///
-/// A name that already names a font object returns the existing one **unchanged, silently** — no
-/// error, no re-publication (`0x7839ab`). We had chosen that as the non-destructive reading before
-/// the bytes were asked; they agree.
-///
-/// The empty string is accepted (the reference's `lua_isstring` gate takes strings *and* numbers,
-/// and unlike the XML path does not require a non-empty name); only a missing/nil argument is an
-/// error. A fresh object holds nothing, so `SetFontObject`-ing it copies nothing — see [`repaint`].
+/// The reference's gate (`0x706048`) takes a number or any string, the empty one included, and
+/// raises on anything else. A fresh object holds nothing, so it copies nothing ([`repaint`]).
 fn create_font(lua: &Lua, name: Option<String>) -> mlua::Result<Table> {
     let name = name.ok_or_else(|| {
         mlua::Error::runtime("CreateFont: a font name is required (it becomes a global)")
diff --git a/crates/benilla-ui/src/script/font_block.rs b/crates/benilla-ui/src/script/font_block.rs
index 4ed4290a..fd4cb984 100644
--- a/crates/benilla-ui/src/script/font_block.rs
+++ b/crates/benilla-ui/src/script/font_block.rs
@@ -1,107 +1,18 @@
-//! **The font block** — the ten font methods a text-bearing widget re-declares in its own method
-//! table, implemented once over the [`RegionData`](super::RegionData) the glyphs actually paint
-//! from, and installed onto any widget's table by [`install`].
+//! The font block: the ten font methods a text-bearing widget's own method table declares,
+//! implemented once over the [`RegionData`](super::RegionData) its glyphs paint from.
 //!
-//! ## Why this is a module and not a base class
+//! The 1.12 client has no `FontInstance` class: each text type re-declares the font names in its
+//! own flat method table, and each binding is a shim that tail-calls one shared implementation.
+//! This module is that shared layer, installed by the FontString, EditBox, MessageFrame and
+//! ScrollingMessageFrame tables; the `<Font>` object and `SimpleHTML` write their own records and
+//! share only [`set_font_args`].
 //!
-//! **There is no `FontInstance` class in the 1.12.1 Lua chain.** The registrar map shows 23 flat
-//! `{const char* name, void* fn}` `.data` tables and a per-class `vtable[+0x8]` lookup
-//! (`0x7020b0`'s dispatch) that tail-calls **exactly one** base class's lookup on a miss.
-//! The six text-bearing types each *re-declare* the same font names in their own flat table; the
-//! sharing happens one level **down**, in C++, where every binding is a thin type-guard shim that
-//! tail-calls one shared implementation (`0x79f210` SetFont · `0x79f3b0` GetFont · `0x79f4d0` /
-//! `0x79f680` Set/GetTextColor · `0x79f730` / `0x79f910` Set/GetShadowColor · `0x79f9c0` /
-//! `0x79fad0` Set/GetShadowOffset · `0x79ef10` / `0x79f090` Set/GetFontObject).
-//!
-//! So: **which font methods a type has is a per-table fact, never derivable from "it draws text"** —
-//! and this module is that shared C++ layer, with each widget's own table naming the subset it
-//! really carries. Adding a name a table does not carry is exactly as wrong as missing one.
-//!
-//! ## The membership, read off the binary rather than assumed
-//!
-//! `EditBox`'s table is `.data 0x87bb68`, **48 entries** — the count read from the `mov edx,0x30` at
-//! the registering site `0x799ab5`, never from a run-length scan (adjacent tables are contiguous and
-//! a scan merges them into a bogus blob). Its **first sixteen entries are the font block**, in this
-//! order, and each one is a shim that `call`s the shared implementation and returns **without
-//! touching `eax`** — so every return arity below is the shared implementation's, verbatim:
-//!
-//! | # | EditBox entry | binding | tail-calls | returns |
-//! |---|---|---|---|---|
-//! | 0 | `SetFontObject`   | `0x797090` | `0x79ef10` | **0 values** |
-//! | 1 | `GetFontObject`   | `0x797150` | `0x79f090` | **1 value** (the handle, or nil) |
-//! | 2 | `SetFont`         | `0x797210` | `0x79f210` | **1 value: the NUMBER 1, or nil** |
-//! | 3 | `GetFont`         | `0x7972d0` | `0x79f3b0` | **3 values** (path, height, flags) |
-//! | 4 | `SetTextColor`    | `0x797390` | `0x79f4d0` | **0 values** |
-//! | 5 | `GetTextColor`    | `0x797450` | `0x79f680` | **4 values** |
-//! | 6 | `SetShadowColor`  | `0x797510` | `0x79f730` | **0 values** |
-//! | 7 | `GetShadowColor`  | `0x7975d0` | `0x79f910` | **4 values** (`0x79f9b3 mov eax,0x4`) |
-//! | 8 | `SetShadowOffset` | `0x797690` | `0x79f9c0` | **0 values** |
-//! | 9 | `GetShadowOffset` | `0x797750` | `0x79fad0` | **2 values** |
-//! | 10–11 | `Set/GetSpacing` | `0x797810` / `0x7978d0` | `0x79fb40` / `0x79fbe0` | *not installed — below* |
-//! | 12–15 | `Set/GetJustifyH`, `Set/GetJustifyV` | `0x797990`… | `0x79fc20`… | *EditBox-side — below* |
-//!
-//! **`SetFont` is the trap here, and it points the opposite way to the one this codebase already
-//! pinned.** `Button:SetFont` (`0x780880`) ends `xor eax,eax` and returns **nothing** — that
-//! divergence has its own test. `EditBox:SetFont` does **not**: `0x7972b2 call 0x79f210` is followed
-//! by `pop edi; pop esi; pop ebx; ret` with no `eax` write, so the shared implementation's single
-//! value (`lua_pushnumber(1.0)` at `0x79f345`, or `lua_pushnil` at `0x79f361`) passes straight
-//! through. It is the number `1`, not `true`, and not zero values.
-//!
-//! The table above was read off the PE `.data` section directly (with Font's 22-entry table as a
-//! positive control), covering all 48 names, all 48 binding addresses and all 16 arities. The
-//! control for the "nothing is discarded" claim is `SetMultiLine`'s binding, which *does*
-//! emit `xor eax,eax` (`0x797e9d`) and returns 0.
-//! Entry 47 ends at `0x87bce8`, the first byte of the string `"GetAltArrowKeyMode"` — the table
-//! abuts its own string pool, which pins the count at 48 a second way.
-//!
-//! **A stated divergence, verified and deliberately left consistent rather than fixed on one table:**
-//! the reference's `SetTextColor` and `SetShadowColor` read r, g and b with a **bare `lua_tonumber`**
-//! (a non-number silently becomes `0.0`) and carry **no usage string at all**, so they *cannot
-//! raise* — `SetTextColor()` sets opaque black. Ours take `f32`, so a missing or non-numeric channel
-//! errors instead. Alpha matches (`lua_isnumber`-gated, default 1.0).
-//!
-//! **The collapse below has now landed, which is what was blocking this**: the FontString and
-//! EditBox tables both reach these two verbs *here*, so the correction is a one-place change rather
-//! than three copies drifting. It is deliberately still not made, for a reason of its own: it turns
-//! a loud error into a silent opaque black, which is faithful but is a real behaviour change and
-//! belongs in its own landing with its own corpus A/B. No corpus site is known to depend on it.
-//!
-//! ## Where it lands, and why that is the mechanism rather than an approximation
-//!
-//! Each shim loads **`[this+0x324]`** and hands it to the shared implementation as the target. On a
-//! `CSimpleEditBox` that offset is the box's implicit FontString — the same field
-//! [`EditBoxState::text_region`](crate::widget::EditBoxState::text_region) models (the EditBox's
-//! analogue of `ButtonText`). So `editBox:SetFontObject(ChatFontNormal)` really does
-//! paint *the box's font string*, which is exactly what this module writes: resolve the widget to
-//! the region its glyphs come from, then set the same [`RegionData`](super::RegionData) fields a
-//! `FontString` sets for itself.
-//!
-//! ## Not installed here, and the reason is not laziness
-//!
-//! - **`SetSpacing` / `GetSpacing`.** We model no line spacing anywhere — neither `RegionData` nor
-//!   the text layout carries the field, and the line pitch is the font height — so a setter here
-//!   could only store a number nobody draws. That is the silently-ignored-setter failure this
-//!   codebase keeps being bitten by (1203, 1205, 1211), and the alternative failure is the good one:
-//!   a missing method raises `attempt to call method 'SetSpacing' (a nil value)`, which names itself.
-//!   Demand is **zero** — `grep -r ':SetSpacing(\|:GetSpacing('` over the 218-addon corpus finds
-//!   nothing at all. `script::font`'s own table withholds the pair for the same reason; when spacing
-//!   becomes something the renderer honours, both land together.
-//! - **The justify four.** They are real EditBox entries and they *are* wired — but on the EditBox's
-//!   own state rather than on its text region, because our EditBox draw law forces the region's
-//!   justification (see `script::editbox::methods`). They live there for that reason, not here.
-//!
-//! ## Who installs this, and the duplicates it replaced
-//!
-//! Two tables: the `EditBox`'s (`script::editbox::methods`) and the **`FontString`'s**
-//! (`script::region::text`). The FontString's used to hand-write its own copy of all ten; 1238
-//! collapsed them, deleting 226 lines and carrying the correction that copy had been hiding — its
-//! `SetFont` answered the boolean `true`, where the bytes above say the number `1` or nil.
-//!
-//! The `<Font>` object's table (`script::font`) is **not** installed from here, and that is not an
-//! oversight: it writes a [`FontObject`](super::FontObject) record rather than a
-//! [`RegionData`](super::RegionData), so it shares the *marshalling* ([`set_font_args`]) rather
-//! than the body. Its `SetFont` had drifted the other way — `Option` arguments, so `SetFont()`
-//! answered nil where `0x87c69c` raises — which is why the gate is one function now.
+//! `EditBox`'s table (`0x87bb68`, 48 entries) opens with these ten, then `Set/GetSpacing` and the
+//! four justify methods. Its shims (`0x797090` on) leave `eax` alone, so each returns what the
+//! shared implementation pushes, and act on `[this+0x324]`, the box's implicit FontString
+//! ([`EditBoxState::text_region`](crate::widget::EditBoxState::text_region)). The justify four are
+//! installed by `script::editbox::methods`. `SetSpacing`/`GetSpacing` (`0x79fb40`/`0x79fbe0`) are
+//! not installed: no line spacing is modelled, so a call raises.
 
 use mlua::{Lua, Table, Value};
 
@@ -109,28 +20,14 @@ use super::object::as_f32;
 use super::{FontShadow, Model, Outline};
 use crate::widget::RegionHandle;
 
-/// How a widget's method table resolves `this` to the region its glyphs are painted from.
-///
-/// A `FontString` *is* that region; an `EditBox` owns one and creates it on demand. A resolver
-/// returning an error is how a method called on the wrong receiver reports it.
+/// How a widget's method table finds the region its glyphs paint from: a `FontString` is one, an
+/// `EditBox` creates its own on demand. An error means the wrong receiver.
 pub(super) type ResolveRegion = fn(&Lua, &Table) -> mlua::Result<RegionHandle>;
 
-/// `SetFont(path, fontHeight [, flags])`'s shared **argument gate** — the entry of `0x79f210`,
-/// which Font `0x7a0270`, FontString `0x79d4f0` and EditBox `0x797210` all reach.
-///
-/// arg 2 must pass `lua_isstring` and arg 3 `lua_isnumber` — both of which coerce, so a numeric
-/// string is accepted for either — else `Usage: %s:SetFont("font", fontHeight [, flags])`
-/// (`.rdata 0x87c69c`). That arm is `luaL_error`, which longjmps, so it is an `Err` here and
-/// **never** a nil answer (`super::binding_abi`).
-///
-/// The returned path may be **empty**, which is the caller's *load-failure* edge rather than an
-/// argument error: it answers nil with nothing raised, because `!OmniCC/main.lua:41`'s
-/// `if not f:SetFont(saved, size) then revert end` is a font-file validity probe. The height is
-/// still applied on that edge — only the face is rejected.
-///
-/// Shared because it was not: the `<Font>` table took `Option<String>, Option<f32>` and so answered
-/// nil for `SetFont()` where the reference raises, while the FontString's copy answered the boolean
-/// `true` for everything. One gate is the only way three entry points stay one routine.
+/// `SetFont`'s shared argument gate (`0x79f210`, reached from Font `0x7a0270`, FontString
+/// `0x79d4f0` and EditBox `0x797210`): arg 2 must pass `lua_isstring` and arg 3 `lua_isnumber`,
+/// both coercing, else it raises `Usage: %s:SetFont("font", fontHeight [, flags])` (`0x87c69c`).
+/// An empty path is not an argument error but a failed load, which the caller answers with nil.
 pub(super) fn set_font_args(
     file: &Value,
     height: &Value,
@@ -154,34 +51,24 @@ pub(super) fn set_font_args(
     Ok((path, height))
 }
 
-/// Install the ten shared font-block methods onto `m`, reading `this` through `resolve`.
-///
-/// The caller names the subset: this installs exactly the ten the module doc tabulates, and a
-/// widget whose real table lacks one of them must not use this installer for it.
+/// Install the ten font-block methods onto `m`, reading `this` through `resolve`; only for a
+/// widget whose reference method table carries all ten.
 pub(super) fn install(
     lua: &Lua,
     m: &Table,
     resolve: ResolveRegion,
     widget: &'static str,
 ) -> mlua::Result<()> {
-    // ── the font object, and the live link to it ────────────────────────────────────────────
-    // SetFontObject(font | "font" | nil) → 0 values. All three argument forms the reference's own
-    // usage string names (`.rdata 0x87c5cc`: `Usage: %s:SetFontObject(font or "font" or nil)`).
-    // `Dewdrop-2.0.lua:1675` — `editBox:SetFontObject(ChatFontNormal)`, two lines after
-    // `CreateFrame("EditBox", nil, editBoxFrame)` — passes the OBJECT, and that one line is
-    // replicated into 63 of the corpus's 218 addons.
-    //
-    // A frame, a number, or an unknown name is an ERROR, never a silent no-op: every rejection in
-    // the reference is `luaL_error 0x6f4940`, which longjmps and aborts the call (1203/1205/1211's
-    // silent-drop class).
+    // ── the font object ──
+    // SetFontObject(font | "font" | nil) → nothing (`0x79ef10`, usage string `0x87c5cc`). Any
+    // other argument or an unknown name raises: every rejection is `luaL_error` (`0x6f4940`).
     m.set(
         "SetFontObject",
         lua.create_function(move |lua, (this, font): (Table, Value)| {
             let name = super::font::resolve("SetFontObject", &font)?;
             let rh = resolve(lua, &this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
-            // The nil form severs the link and leaves the paint standing — the reference stores a
-            // null parent, and nothing re-reads or clears the resolved values.
+            // nil severs the link and keeps the paint; the reference only nulls the parent.
             let Some(name) = name else {
                 model.region_data.entry(rh).or_default().font_object = None;
                 return Ok(());
@@ -193,17 +80,14 @@ pub(super) fn install(
             };
             let d = model.region_data.entry(rh).or_default();
             d.font_object = Some(name);
-            // The severance mask is deliberately NOT reset. The real "stop inheriting
-            // this property" signal is a CLEARED bit in the inheritMask (`FONTINSTANCE+0x2c`),
-            // cleared by each local setter and never restored — so a property the widget set for
-            // itself stays severed across a later `SetFontObject`.
+            // The inherit mask stays: each local setter clears its bit (`FONTINSTANCE+0x2c`) and
+            // nothing restores it, so a property set locally survives a later `SetFontObject`.
             super::font::repaint(d, &fo);
             model.touch_measure(rh);
             Ok(())
         })?,
     )?;
-    // GetFontObject() → exactly 1 value: the font OBJECT last resolved, or nil. The object, never
-    // its name — `Dewdrop-2.0.lua:2181` indexes the result immediately.
+    // GetFontObject() → the font object last set, never its name, or nil (`0x79f090`).
     m.set(
         "GetFontObject",
         lua.create_function(move |lua, this: Table| {
@@ -223,16 +107,10 @@ pub(super) fn install(
         })?,
     )?;
 
-    // ── the face ────────────────────────────────────────────────────────────────────────────
-    // SetFont(path, height [, flags]) → **the NUMBER 1, or nil** — one value either way, never a
-    // boolean and never zero values (the module doc's table; `0x7972b2` does not clobber `eax` the
-    // way `Button:SetFont` does). The shared impl gates arg2 on `lua_isstring` and arg3 on
-    // `lua_isnumber`, raising `Usage: %s:SetFont("font", fontHeight [, flags])` (`0x87c69c`)
-    // otherwise — both accept a numeric string, since `lua_isstring`/`lua_isnumber` coerce.
-    //
-    // nil is the *load-failure* answer, not an argument error: `!OmniCC/main.lua:41`'s
-    // `if not Font:SetFont(saved, size) then revert end` is a font-file validity probe, so an empty
-    // path must come back falsey rather than raising.
+    // ── the face ──
+    // SetFont(path, height [, flags]) → the number 1 (`0x79f345`), or nil on a failed load
+    // (`0x79f361`), never a boolean. The EditBox shim passes it through (`0x7972b2` leaves `eax`
+    // alone), unlike `Button:SetFont` (`0x780880`), which returns nothing.
     m.set(
         "SetFont",
         lua.create_function(
@@ -240,16 +118,13 @@ pub(super) fn install(
                 let (path, height) = set_font_args(&file, &height, widget)?;
                 let rh = resolve(lua, &this)?;
                 let mut model = lua.app_data_mut::<Model>().expect("model");
-                // The verdict is the host's when there is a host: nil is a *load* failure
-                // (`0x5c1ae0` under the `0x44d040` font-factory cache), so a path naming no file
-                // — an addon's TTF the AddOns folder does not hold — has to come back falsey, and
-                // only the store knows. With no probe installed, a non-empty path is 1: a VM with
-                // no font backend has nothing for a load to fail against (decision 2103).
+                // A failed load (`0x5c1ae0` under the `0x44d040` font cache) is the host's probe to
+                // judge, as only the store knows the files; with no probe, a non-empty path loads.
                 let ok =
                     !path.is_empty() && model.font_probe.as_ref().is_none_or(|probe| probe(&path));
                 let d = model.region_data.entry(rh).or_default();
-                // Every argument supplied is an EXPLICIT set: it must survive a later mutation of
-                // the font object this region inherits.
+                // Each supplied argument is an explicit set, kept through a later font-object
+                // change; the height applies even when the face fails to load.
                 if ok {
                     d.font_path = Some(path);
                     d.font_explicit.face = true;
@@ -257,9 +132,8 @@ pub(super) fn install(
                 d.font_height = Some(height);
                 d.font_explicit.height = true;
                 if let Some(f) = flags {
-                    // The LUA flags spelling ("OUTLINE"/"THICKOUTLINE"), not the XML attribute's
-                    // ("NORMAL"/"THICK") — the shared parse `0x6f1a90` is a case-insensitive
-                    // SUBSTRING scan, which is why "THICKOUTLINE" yields both bits.
+                    // The Lua spelling (`OUTLINE`, `THICKOUTLINE`), not the XML one, parsed like
+                    // `0x6f1a90`: a case-insensitive substring scan, so `THICKOUTLINE` sets both.
                     d.outline = Outline::flags(&f);
                     d.font_explicit.outline = true;
                 }
@@ -268,22 +142,11 @@ pub(super) fn install(
             },
         )?,
     )?;
-    // GetFont() → 3 values: path, height, flagsString (`mov eax,3` at `0x79f407`). The flags string
-    // is `""` when there are none — built into a zeroed static buffer at `0xceea60` — never nil.
-    //
-    // **The HEIGHT slot is a number even on a FontString that was never given a font**, and that is
-    // not the obvious reading: the FontString reads back *through* its resolved `CGxFont`, so it
-    // looks as though a NULL one should nil all three. It does not. `0x7727b0`'s fifth instruction
-    // is an *unconditional* `fld [esi+0xe4]`, and its `+0xe0` test sits behind a branch `GetFont`
-    // never takes (`0x79d499 push 0`) — so slot 2 never touches the `CGxFont` at all and always
-    // pushes a double. We answer 0 there: `+0xe4` has **no constructor writer** in the reference,
-    // so its value on this path is a recycled float that nothing can reproduce, and 0 is what the
-    // Font object's own ctor-determined `+0x48` gives (decision 2129).
-    //
-    // A nil here is not a cosmetic difference. `aux-addon/tabs/search/frame.lua:481` computes
-    // `aux.select(2, child:GetFont()) + arg1*2` in its font-resize wheel handler — `aux.select`,
-    // the addon's own (`util.lua:26`), which is why that line survives 2171 taking the global
-    // `select` away.
+    // GetFont() → path, height, flags (`0x79f3b0`, `mov eax,3` at `0x79f407`); flags is "" when
+    // none (a zeroed buffer at `0xceea60`), never nil. The height is a number even with no font:
+    // `0x7727b0` loads `[esi+0xe4]` unconditionally (`0x79d499` skips its `+0xe0` test). That
+    // field has no constructor writer, so an unset height reads 0 here, like the Font object's
+    // `+0x48`.
     m.set(
         "GetFont",
         lua.create_function(move |lua, this: Table| {
@@ -300,14 +163,11 @@ pub(super) fn install(
         })?,
     )?;
 
-    // ── the text colour ─────────────────────────────────────────────────────────────────────
-    // SetTextColor(r, g, b [, a]) → 0 values; alpha defaults to 1.0 (`lua_isnumber(L,5)`-gated,
-    // `0x3f800000`). A FontString has no texel of its own, so its vertex colour IS the colour it
-    // draws — the same `+0xb8` slot `SetVertexColor` writes. The three channels are SHAPE C
-    // (`FontString:SetTextColor 0x79d9c0`, `2=C 3=C 4=C 5=B`):
-    // a bare `lua_tonumber`, so a nil or a non-number is 0.0 and the call never raises — the stock
-    // trainer/trade-skill rows' OnLeave hands it `this.r, this.g, this.b` before anything set them
-    // (1973).
+    // ── the text colour ──
+    // SetTextColor(r, g, b [, a]) → nothing (`0x79f4d0`). r, g and b are a bare `lua_tonumber`
+    // (`0x79d9c0`), so nil reads 0.0 and the call never raises; alpha defaults to 1.0
+    // (`lua_isnumber`-gated). The colour is the region's vertex colour, the `+0xb8` slot
+    // `SetVertexColor` writes.
     m.set(
         "SetTextColor",
         lua.create_function(
@@ -321,15 +181,13 @@ pub(super) fn install(
                 let mut model = lua.app_data_mut::<Model>().expect("model");
                 let d = model.region_data.entry(rh).or_default();
                 d.vertex_color = Some([r, g, b, a.unwrap_or(1.0)]);
-                // The shared impl clears the inheritMask's colour bit on whatever instance it ran
-                // on (`0x79dbd0`'s `and [edi+0xd4],0xfffffffb`), so an explicit colour survives a
-                // later repaint from the font object.
+                // Clears the colour inherit bit (`0x79dbd0`): it survives a font-object repaint.
                 d.font_explicit.color = true;
                 Ok(())
             },
         )?,
     )?;
-    // GetTextColor() → 4 values, r, g, b, a. Never set = the white every region draws at.
+    // GetTextColor() → r, g, b, a (`0x79f680`); white when never set.
     m.set(
         "GetTextColor",
         lua.create_function(move |lua, this: Table| {
@@ -344,20 +202,14 @@ pub(super) fn install(
         })?,
     )?;
 
-    // ── the shadow ──────────────────────────────────────────────────────────────────────────
-    // **`GetShadowColor` returns FOUR values, not three** (`0x79f9b3`, `mov eax,0x4`). Three is the
-    // plausible wrong answer and it silently drops the alpha that
-    // `FuBar_NavigatorFu/NavigatorFu.lua:31` round-trips. `GetShadowOffset` returns two, in UI
-    // units (the same units as `SetWidth`/`SetPoint`), not device pixels.
-    //
-    // Either half may be set before the other, so each starts from whatever is already there —
-    // shadow colour and offset share one inherit slot in the reference too.
+    // ── the shadow ──
+    // `SetShadowColor` `0x79f730`, `GetShadowColor` `0x79f910` (four values, not three: `0x79f9b3`
+    // `mov eax,0x4`), `SetShadowOffset` `0x79f9c0`, `GetShadowOffset` `0x79fad0` (two, in UI
+    // units). Colour and offset share one inherit slot, so each setter keeps the other half.
     m.set(
         "SetShadowColor",
         lua.create_function(
-            // Shape C on r, g, b (`FontString:SetShadowColor 0x79dd40`, `2=C 3=C 4=C 5=B`) — the
-            // same law this module's header already states for its `SetTextColor` sibling, which
-            // 1973 closed there and not here.
+            // r, g and b are a bare `lua_tonumber` (`0x79dd40`), as in `SetTextColor`.
             move |lua, (this, r, g, b, a): (Table, Value, Value, Value, Option<f32>)| {
                 let (r, g, b) = (
                     super::object::as_f32(&r),
@@ -390,8 +242,7 @@ pub(super) fn install(
             Ok((c[0], c[1], c[2], c[3]))
         })?,
     )?;
-    // SetShadowOffset(x, y) → 0 values, and **both arguments are required** — the shared impl
-    // raises `Usage: %s:SetShadowOffset(x, y)` (`0x87c6e8`) rather than defaulting the missing one.
+    // SetShadowOffset(x, y): both required, else `Usage: %s:SetShadowOffset(x, y)` (`0x87c6e8`).
     m.set(
         "SetShadowOffset",
         lua.create_function(move |lua, (this, x, y): (Table, f32, f32)| {
diff --git a/crates/benilla-ui/src/script/gm_ticket.rs b/crates/benilla-ui/src/script/gm_ticket.rs
index bb9b2330..7850e12d 100644
--- a/crates/benilla-ui/src/script/gm_ticket.rs
+++ b/crates/benilla-ui/src/script/gm_ticket.rs
@@ -1,96 +1,60 @@
-//! The GM trouble-ticket **Era API surface** (decision 1673) — the seven globals `HelpFrame.lua`
-//! is written against, and nothing else.
-//!
-//! All seven are engine bindings in 1.12 (`reference/1.12-globals.tsv` lists each as
-//! `function`/`engine`), and the set is closed: the shipped Help window calls exactly
-//! `GetGMTicketCategories`, `GetGMStatus`, `GetGMTicket`, `NewGMTicket`, `UpdateGMTicket`,
-//! `DeleteGMTicket` and `Stuck`, and nothing else in the shipped UI calls any of them.
-//!
-//! **The five ticket verbs share ONE ordered queue** ([`GmTicketIntent`]), rather than a counter
-//! each. Call order is the wire order in the real client, and a per-verb drain cannot preserve it:
-//! with separate queues, `DeleteGMTicket(); GetGMTicket()` in a single chunk puts the *get* on the
-//! wire first and the answer then describes the state before the delete. The shipped Help window
-//! never issues two in one frame, so nothing on screen would ever have shown it — which is exactly
-//! why it is worth getting right rather than leaving as a latent trap for the next addon, or for
-//! our own probe (which hit it).
-//!
-//! A queue, not a set: **two calls are two sends**. That matters more here than for
-//! [`super::binder`], because the ticket toast **re-polls `GetGMTicket()` every 10 minutes** — a
-//! deduplicating drain would silently stop the poll. `Stuck()` keeps its own counter, because it
-//! is not a ticket verb at all (see its registration below) and shares no ordering with them.
-//!
-//! **The category list is DBC data, pushed once.** `GetGMTicketCategories()` returns a flat
-//! `id1, name1, id2, name2, …` vararg list, which `HelpFrameGM_UpdateCategories(...)` walks with
-//! Lua 5.0's `arg`/`arg.n`. The ids are `GMTicketCategory.dbc`'s own and they are the values that
-//! go on the wire, so this is an ordered list of pairs rather than an indexable table — see
-//! [`benilla_formats::gm_ticket_category`] for why renumbering would misfile every ticket.
-//!
-//! **There is no `GetGMTicket` *getter*.** The reference's `GetGMTicket()` is a SEND, not a read:
-//! the answer comes back as the `UPDATE_TICKET` event's arguments, and the window keeps whatever
-//! it needs in its own frame fields. So nothing here holds a ticket snapshot — the same shape as
-//! [`super::duel`] and [`super::binder`], and for the same reason.
+//! The seven GM ticket globals `HelpFrame.lua` calls. The five ticket verbs share one ordered
+//! queue, because call order is the reference's wire order, and two calls are two sends: the
+//! ticket toast re-polls `GetGMTicket()` every 10 minutes. `GetGMTicket()` is a send, answered by
+//! the `UPDATE_TICKET` event, so nothing here holds a ticket.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// One ticket verb the window called, in call order — the queue [`super::UiScript::take_gm_ticket_intents`]
-/// drains. Ordered rather than counted so the wire sees what Lua did, in the order Lua did it.
+/// One ticket verb the window called, drained in call order.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum GmTicketIntent {
-    /// `GetGMTicket()` — `CMSG_GMTICKET_GETTICKET`.
+    /// `GetGMTicket()`: `CMSG_GMTICKET_GETTICKET`.
     Ask,
-    /// `GetGMStatus()` — `CMSG_GMTICKET_SYSTEMSTATUS`.
+    /// `GetGMStatus()`: `CMSG_GMTICKET_SYSTEMSTATUS`.
     AskStatus,
-    /// `DeleteGMTicket()` — `CMSG_GMTICKET_DELETETICKET`.
+    /// `DeleteGMTicket()`: `CMSG_GMTICKET_DELETETICKET`.
     Delete,
-    /// `NewGMTicket`/`UpdateGMTicket` — create or edit.
+    /// `NewGMTicket` or `UpdateGMTicket`.
     Write(GmTicketWrite),
 }
 
-/// One `NewGMTicket` / `UpdateGMTicket` call, drained by the app.
+/// One `NewGMTicket` or `UpdateGMTicket` call.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct GmTicketWrite {
-    /// The `GMTicketCategory.dbc` id the window had selected — `HelpFrameOpenTicket.ticketType`,
-    /// which is the clicked category row's own id.
+    /// The selected `GMTicketCategory.dbc` id (`HelpFrameOpenTicket.ticketType`).
     pub category: u32,
-    /// The text as typed. The window's EditBox caps it at 500 letters; the engine's own cap is
-    /// 1999, so nothing here truncates what the UI allowed.
+    /// The text as typed; the EditBox caps it at 500, under the reference's 1999.
     pub text: String,
-    /// `true` for `NewGMTicket` (file), `false` for `UpdateGMTicket` (edit). Two different
-    /// opcodes with two different answers, so the distinction survives to the app rather than
-    /// being re-derived from whether a ticket is believed to exist — the reference picks the verb
-    /// from its own `HelpFrameOpenTicket.hasTicket` flag and we must not second-guess it.
+    /// `NewGMTicket` or `UpdateGMTicket`, two opcodes: the window picks by its own `hasTicket`
+    /// flag, and the app must not re-derive it.
     pub is_new: bool,
 }
 
 impl super::UiScript {
-    /// Publish the ticket categories `GetGMTicketCategories()` returns — the `GMTicketCategory.dbc`
-    /// rows, in file order. Pushed once at load; the table is static client data.
+    /// The `GMTicketCategory.dbc` rows in file order, pushed once; the ids are the wire's values,
+    /// so renumbering them would misfile every ticket.
     pub fn set_gm_ticket_categories(&mut self, categories: Vec<(u32, String)>) {
         self.model_mut().gm_ticket_categories = categories;
     }
 
-    /// Drain every ticket verb the window called since the last drain, **in call order** — the
-    /// module doc's reason. Each entry is exactly one packet.
+    /// Drain the ticket verbs in call order, one packet each.
     pub fn take_gm_ticket_intents(&mut self) -> Vec<GmTicketIntent> {
         std::mem::take(&mut self.model_mut().gm_ticket_intents)
     }
 
-    /// Drain the `Stuck()` calls — each is one cast of spell 7355.
+    /// Drain the `Stuck()` calls, each one cast of spell 7355.
     pub fn take_stuck_casts(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().stuck_casts)
     }
 }
 
-/// Register the seven Help-window globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetGMTicketCategories() — the flat (id, name) vararg list, consumed by
-    // `HelpFrameGM_UpdateCategories` as `arg[i]`/`arg[i+1]` pairs. Empty until the app has pushed
-    // the DBC (a bare-XML harness, or a run with no client data): the window then simply paints no
-    // category rows, which is the honest rendering of "we have no catalog" and cannot error.
+    // A flat `id, name, ...` vararg list, walked in pairs by `HelpFrameGM_UpdateCategories`;
+    // empty until the app pushes the DBC.
     g.set(
         "GetGMTicketCategories",
         lua.create_function(|lua, ()| {
@@ -104,11 +68,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The three payload-free verbs. Each pushes onto the ONE ordered queue, so a chunk that calls
-    // two of them sends two packets in the order it called them.
-    //   GetGMTicket()    — "send me my ticket"; a send, answered as UPDATE_TICKET.
-    //   GetGMStatus()    — "is the petition queue up?"; answered as UPDATE_GM_STATUS.
-    //   DeleteGMTicket() — the HELP_TICKET_ABANDON_CONFIRM dialog's Yes.
+    // Sends: `GetGMTicket` is answered by `UPDATE_TICKET`, `GetGMStatus` by `UPDATE_GM_STATUS`.
     for (name, intent) in [
         ("GetGMTicket", GmTicketIntent::Ask),
         ("GetGMStatus", GmTicketIntent::AskStatus),
@@ -126,9 +86,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // NewGMTicket(category, text) / UpdateGMTicket(category, text) — the window's Submit and its
-    // Save Changes. Same signature, different opcode; the reference's own usage string is
-    // `Usage: UpdateGMTicket(type, text)`, so (number, string) is the declared arity for both.
+    // Submit and Save Changes: one signature, `(type, text)` in the reference's usage string.
     for (name, is_new) in [("NewGMTicket", true), ("UpdateGMTicket", false)] {
         g.set(
             name,
@@ -146,10 +104,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // Stuck() — the Help window's "Auto-Unstuck". NOT a ticket verb despite living only in this
-    // window: it casts spell 7355 "Stuck", whose SPELL_EFFECT_STUCK teleports the player to their
-    // last safe position server-side. It is registered here because HelpFrame is its only caller
-    // in the whole shipped UI, and a module for one binding would be worse than this note.
+    // The Help window's Auto-Unstuck, not a ticket verb: it casts spell 7355, whose
+    // `SPELL_EFFECT_STUCK` moves the player to a safe position server-side.
     g.set(
         "Stuck",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/gossip.rs b/crates/benilla-ui/src/script/gossip.rs
index 90cb5b6f..0dddf537 100644
--- a/crates/benilla-ui/src/script/gossip.rs
+++ b/crates/benilla-ui/src/script/gossip.rs
@@ -1,72 +1,49 @@
-//! The gossip bindings (decision 0081 phase 3) — the Era-shaped NPC-dialog surface, the same
-//! two-way seam as [`super::container`]: the app pushes a **gossip menu snapshot**
-//! ([`UiScript::set_gossip`] — the greeting + option rows already resolved from the wire), and the
-//! Lua `SelectGossipOption`/`CloseGossip` calls queue outbound **intents** the app drains
-//! ([`UiScript::take_gossip_selects`] / [`UiScript::take_gossip_close`]). The engine holds no NPC
-//! knowledge — an option is "a label, an icon type, and whether it's coded".
+//! The gossip bindings: the app pushes the open menu ([`UiScript::set_gossip`]), and
+//! `SelectGossipOption` and `CloseGossip` queue intents it drains.
 //!
-//! ## The Era API shape
+//! `GetGossipOptions()` returns flat `(text, type)` pairs, `type` the lowercase icon name the app
+//! maps from the wire `GOSSIP_ICON`. A coded option is not built: the app drops its select, where
+//! the reference opens a password box (`UIParent.lua:563`). `IsGossipOptionCoded(i)` is benilla's
+//! own, not a 1.12 global, and no stock file calls it.
 //!
-//! 1.12's `GetGossipOptions()` returns a flat vararg of `(text, type)` pairs — the FrameXML's
-//! `GossipFrameUpdate` walks it two-at-a-time, `SetText`ing each `GossipTitleButton` and mapping the
-//! `type` string to an `Interface\GossipFrame\<Type>GossipIcon` texture. Benilla keeps that exact
-//! shape: `GetGossipOptions()` returns `label1, type1, label2, type2, …`, where `type` is the
-//! lowercase Era icon name (`"gossip"`/`"vendor"`/`"taxi"`/`"trainer"`/…) the app derived from the
-//! wire `GOSSIP_ICON` byte. The one addition is `IsGossipOptionCoded(i)` — a benilla-local
-//! predicate the XML uses to grey password-gated options (decision 0081 v1: coded options are
-//! parsed and greyed, never selected; the real client pops a password box, out of scope here).
-//! `GetGossipText()` returns the greeting body (`SMSG_NPC_TEXT_UPDATE`), `nil` when no menu is
-//! open. There is no "menu open, text pending" state: while a greeting is in flight the app
-//! pushes nothing and fires nothing — the VM keeps its last menu (or none), exactly as the
-//! reference's frame keeps its last paint (its handler returns on a cache miss without an event,
-//! and its greeting write and `GOSSIP_SHOW` are adjacent and unconditional on one success path —
-//! `0x4e2010`, `0x4e22b0`; B292, benilla decisions 1508/1994), which is why
-//! [`GossipMenu::greeting`] is a plain `String`.
+//! A menu is pushed only once its greeting (`SMSG_NPC_TEXT_UPDATE`) has arrived; until then the
+//! VM keeps its last menu, as the reference's frame keeps its last paint: its handler returns on a
+//! cache miss without an event, and the greeting write and `GOSSIP_SHOW` share one success path
+//! (`0x4e2010`, `0x4e22b0`).
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// One gossip menu option, resolved by the app from the wire `GossipOption` (decision 0081). Plain
-/// data — 1-based order in the menu is its position in [`GossipMenu::options`].
+/// One gossip option; its 1-based index is its place in [`GossipMenu::options`].
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct GossipOptionView {
-    /// The option label (`SetText` on its row button).
+    /// The option's label.
     pub label: String,
-    /// The Era `GetGossipOptions()` second value — the lowercase icon *type* the app mapped from
-    /// the wire `GOSSIP_ICON` byte (`"gossip"`/`"vendor"`/`"taxi"`/`"trainer"`/…). The XML resolves
-    /// it to a `Interface\GossipFrame\<Type>GossipIcon` texture.
+    /// The lowercase icon type (`"gossip"`, `"vendor"`, `"taxi"`, …); `GossipFrame.lua:123` draws
+    /// `Interface\GossipFrame\<Type>GossipIcon`.
     pub icon_type: String,
-    /// A password-gated (`coded`) option — greyed and unselectable in v1 (decision 0081).
+    /// A password-gated option, which the app never selects.
     pub coded: bool,
 }
 
-/// One quest row riding a gossip menu (`SMSG_GOSSIP_MESSAGE`'s quest-option block). A gossip NPC
-/// that also gives quests lists them above the gossip options; a click sends
-/// `CMSG_QUESTGIVER_QUERY_QUEST` (decision 0088). `active` splits the row into the "current quests"
-/// vs "available quests" headers (the app derives it from the wire dialog-status icon); the app maps
-/// the clicked 1-based row back to its quest id.
+/// One quest row of `SMSG_GOSSIP_MESSAGE`; a click sends `CMSG_QUESTGIVER_QUERY_QUEST`. `active`,
+/// from the wire icon, puts it under current quests rather than available ones.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct GossipQuestRow {
     pub title: String,
-    /// The quest's level — `SMSG_GOSSIP_MESSAGE`'s own third field per quest row.
-    ///
-    /// The app parsed it and dropped it until 1751's twenty-first window, because the invented
-    /// `GetGossipQuestInfo` had nowhere to put it. The reference's two verbs return the rows as
-    /// `(title, level)` PAIRS, and stock `GossipFrame.lua` strides its walk by 2 over them — so
-    /// the level is load-bearing for the stride even though 1.12's own FrameXML never reads it.
+    /// The row's third wire field. 1.12 never shows it, but the verbs return `(title, level)` pairs
+    /// and `GossipFrame.lua:66` strides by 2 over them.
     pub level: u32,
     pub active: bool,
 }
 
-/// One open gossip menu: the greeting body, the quest rows, and the option rows. Pushed whole by
-/// the app; `None` means no menu is open.
+/// One open gossip menu, pushed whole by the app.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct GossipMenu {
-    /// The NPC greeting, always resolved: a menu is only pushed once its `SMSG_NPC_TEXT_UPDATE`
-    /// answered — an open gossip frame with a blank page is not a reachable state (module doc).
+    /// The NPC greeting, always resolved.
     pub greeting: String,
-    /// Quest rows the NPC offers/has active, riding the same packet (decision 0088).
+    /// Quest rows from the same packet.
     pub quests: Vec<GossipQuestRow>,
     pub options: Vec<GossipOptionView>,
 }
@@ -82,14 +59,12 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().gossip_selects)
     }
 
-    /// Whether `CloseGossip` was called since the last drain (and clear the flag). vanilla's
-    /// client-side close sends no packet — the app just clears its local menu state.
+    /// Whether `CloseGossip` was called since the last drain; the 1.12 close sends no packet.
     pub fn take_gossip_close(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().gossip_close)
     }
 
-    /// Drain the 1-based quest-row positions queued by `SelectGossipQuest` since the last call. The
-    /// app maps each to the row's quest id + the open NPC and sends `CMSG_QUESTGIVER_QUERY_QUEST`.
+    /// Drain the queued 1-based whole-menu quest-row positions.
     pub fn take_gossip_quest_selects(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().gossip_quest_selects)
     }
@@ -99,8 +74,6 @@ impl super::UiScript {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // → the greeting body, or nil while there is no menu (an open menu always has one — the
-    // app-side hold, module doc).
     g.set(
         "GetGossipText",
         lua.create_function(|lua, ()| {
@@ -115,11 +88,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // → flat (label, type) pairs, the Era `GetGossipOptions()` vararg shape.
     g.set(
         "GetGossipOptions",
         lua.create_function(|lua, ()| {
-            // Collect owned data under one short borrow, then build the Lua values with none held.
+            // Copy out under one short borrow; build the Lua values with none held.
             let pairs: Vec<(String, String)> = {
                 let model = lua.app_data_ref::<Model>().expect("model app_data");
                 model.gossip.as_ref().map_or_else(Vec::new, |m| {
@@ -138,8 +110,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsGossipOptionCoded(i) — benilla-local: the XML greys a coded (password) option (decision
-    // 0081). `i` is 1-based; an out-of-range index is `false`.
     g.set(
         "IsGossipOptionCoded",
         lua.create_function(|lua, i: usize| {
@@ -152,9 +122,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SelectGossipOption(i [, ...]) — queue the 1-based option position; the app maps it to the
-    // wire option index + guid. Extra Era args (the code / a confirm flag) are ignored: v1 never
-    // sends a code (decision 0081).
+    // SelectGossipOption(i [, ...]): queue the 1-based position. Further arguments, a code among
+    // them, are ignored: coded options are not built, so no code is ever sent.
     g.set(
         "SelectGossipOption",
         lua.create_function(|lua, (i, _rest): (u32, mlua::MultiValue)| {
@@ -164,7 +133,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CloseGossip() — client-side close (no packet, vanilla): flag it so the app clears its menu.
     g.set(
         "CloseGossip",
         lua.create_function(|lua, ()| {
@@ -174,22 +142,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ══ THE TWO QUEST LISTS, and why there are two ══════════════════════════════════════════
-    //
-    // 1.12 splits the gossip packet's quest rows by their WIRE ICON — `{3,4}` are "active", every
-    // other value "available" (decision 0758) — and publishes each list through its own vararg
-    // verb. The reference runs that same test lazily behind these two bindings
-    // (`0x4e2430`/`0x4e2580`); we run it at parse time and keep the answer on the row.
-    //
-    // **Each row is a PAIR: `(title, level)`.** Stock `GossipFrameAvailableQuestsUpdate` /
-    // `…ActiveQuestsUpdate` walk `for i = 1, arg.n, 2` and read only `arg[i]`, so the level is
-    // never displayed in 1.12 — but it is what makes the stride land, and an addon reading the
-    // second slot gets the number the server sent rather than a nil.
-    //
-    // These four REPLACE `GetNumGossipQuests` / `GetGossipQuestInfo` / `SelectGossipQuest`, which
-    // were benilla's own single-list shape and appear nowhere in `reference/1.12-globals.tsv`.
-    // 1189's rule: a superset is not free — an addon that feature-detects on a name the client
-    // does not have takes a branch we cannot honour.
+    // ══ The two quest lists ══
+    // The reference splits the quest rows by wire icon, 3 and 4 active and the rest available,
+    // behind two vararg verbs (`0x4e2430`, `0x4e2580`); the app splits them at parse time.
     fn quest_rows(lua: &Lua, active: bool) -> mlua::Result<MultiValue> {
         let rows: Vec<(String, u32)> = {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
@@ -218,14 +173,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, ()| quest_rows(lua, true))?,
     )?;
 
-    // The two selects. Each index is 1-based **within its own list**, which is what
-    // `GossipTitleButton_OnClick` passes: the reference re-numbers the rows per list as it lays
-    // them out (`titleIndex`), so a menu with two available and one active quest hands the active
-    // row a 1, not a 3.
-    //
-    // The queue the app drains is one list, so the index is mapped back to the WHOLE row order
-    // here — the app's own `take_gossip_quest_selects` contract is unchanged, and the two verbs
-    // stay a pure re-expression of it rather than a second drain to wire up.
+    // A select's index is 1-based within its own list, as `GossipFrame.lua:73` numbers the
+    // buttons; it maps back to the whole-menu position the app's queue holds.
     fn select_quest(lua: &Lua, active: bool, index: usize) {
         let whole = {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
@@ -291,7 +240,6 @@ mod tests {
     #[test]
     fn gossip_snapshot_reads_and_selects_queue() {
         let mut s = UiScript::new().unwrap();
-        // No menu: text nil, no options.
         assert!(s.eval::<bool>("return GetGossipText() == nil").unwrap());
         assert_eq!(s.arity("GetGossipOptions()").unwrap(), 0);
 
@@ -300,7 +248,6 @@ mod tests {
             s.eval::<String>("return GetGossipText()").unwrap(),
             "Greetings, traveler."
         );
-        // Flat (label, type) pairs: 2 options → 4 return values.
         let (l1, t1, l2, t2) = s
             .eval::<(String, String, String, String)>(
                 "local a,b,c,d = GetGossipOptions()\n\
@@ -314,12 +261,10 @@ mod tests {
         );
         assert_eq!(l2, "I would like to sign the petition.");
         assert_eq!(t2, "gossip");
-        // The coded (petition) option is flagged for greying; the vendor one isn't.
         assert!(!s.eval::<bool>("return IsGossipOptionCoded(1)").unwrap());
         assert!(s.eval::<bool>("return IsGossipOptionCoded(2)").unwrap());
         assert!(!s.eval::<bool>("return IsGossipOptionCoded(9)").unwrap()); // out of range
 
-        // Selecting queues the 1-based position; closing flags the intent.
         s.run("SelectGossipOption(1)").unwrap();
         s.run("SelectGossipOption(2, 'unused-code')").unwrap(); // extra arg ignored
         assert_eq!(s.take_gossip_selects(), vec![1, 2]);
@@ -331,22 +276,11 @@ mod tests {
         assert!(!s.take_gossip_close(), "drained");
     }
 
-    /// **The two quest lists the reference publishes, and the two selects that index INTO them.**
-    ///
-    /// This replaces a test of `GetNumGossipQuests`/`GetGossipQuestInfo`/`SelectGossipQuest` —
-    /// benilla's own single-list shape, and three names that appear nowhere in
-    /// `reference/1.12-globals.tsv`. 1189's rule is why they had to go rather than sit beside the
-    /// real four: an addon that feature-detects on a name this client does not have takes a branch
-    /// we cannot honour.
-    ///
-    /// The row shape is a `(title, level)` PAIR because stock `GossipFrameAvailableQuestsUpdate`
-    /// walks `for i = 1, arg.n, 2` and reads `arg[i]`. 1.12 never displays the level; it is the
-    /// stride that needs it, and an addon reading the second slot should get the server's number.
     #[test]
     fn the_two_gossip_quest_lists_split_by_active_and_select_within_themselves() {
         use super::GossipQuestRow;
         let mut s = UiScript::new().unwrap();
-        // No menu → both lists are empty, and that is `arg.n == 0`, not a nil.
+        // No menu: `arg.n == 0`, not a nil.
         assert_eq!(s.arity("GetGossipAvailableQuests()").unwrap(), 0);
         assert_eq!(s.arity("GetGossipActiveQuests()").unwrap(), 0);
 
@@ -370,7 +304,6 @@ mod tests {
         ];
         s.set_gossip(Some(m));
 
-        // Two available, in menu order, each a pair.
         assert_eq!(
             s.eval::<(String, i64, String, i64)>("return GetGossipAvailableQuests()")
                 .unwrap(),
@@ -381,24 +314,18 @@ mod tests {
                 9
             )
         );
-        // One active, and the active row does NOT appear in the available list even though it
-        // comes first in the menu — the split is the wire icon, not the position.
+        // The active row comes first in the menu but splits by icon, not position.
         assert_eq!(
             s.eval::<(String, i64)>("return GetGossipActiveQuests()")
                 .unwrap(),
             ("Report to Goldshire".to_string(), 5)
         );
 
-        // **Each select is 1-based within its OWN list**, which is what
-        // `GossipTitleButton_OnClick` passes (the reference re-numbers per list as it lays the
-        // rows out). Available #2 is "Kobold Camp Cleanup", the THIRD row of the menu — and the
-        // queue the app drains is still whole-menu positions, so it must come back as 3.
+        // Available #2 is the menu's third row.
         s.run("SelectGossipAvailableQuest(2)").unwrap();
         assert_eq!(s.take_gossip_quest_selects(), vec![3]);
-        // …and the single active row is #1 in its list, the FIRST of the menu.
         s.run("SelectGossipActiveQuest(1)").unwrap();
         assert_eq!(s.take_gossip_quest_selects(), vec![1]);
-        // Out of range queues nothing rather than a wrong row.
         s.run("SelectGossipAvailableQuest(9) SelectGossipActiveQuest(0)")
             .unwrap();
         assert!(s.take_gossip_quest_selects().is_empty(), "drained");
diff --git a/crates/benilla-ui/src/script/guild.rs b/crates/benilla-ui/src/script/guild.rs
index 56687ddf..b53b4e6b 100644
--- a/crates/benilla-ui/src/script/guild.rs
+++ b/crates/benilla-ui/src/script/guild.rs
@@ -1,76 +1,25 @@
-//! The guild **Era API surface** — roster, ranks, notes, MOTD, and the membership verbs
-//! (decision 1257).
+//! The guild bindings: roster, ranks, notes, MOTD and the membership verbs. The app pushes a
+//! display-ready [`GuildState`] ([`UiScript::set_guild`]) that joins two caches: the roster (MOTD,
+//! info text, rank rights, members) and the guild query (the name and ten rank names). Each verb
+//! queues a [`GuildRequest`] the app drains ([`UiScript::take_guild_requests`]).
 //!
-//! [`super::social`]'s shape exactly: the app pushes a [`GuildState`] snapshot built from its own
-//! wire mirror ([`UiScript::set_guild`]) and the getters here read that plain data; every verb
-//! queues a [`GuildRequest`] the app drains ([`UiScript::take_guild_requests`]) into the matching
-//! `CMSG_*` send. No ECS or net reach from the engine (decision 0068 §3).
-//!
-//! **The snapshot is already display-ready** — member names, localized class names, zone names,
-//! rank names, and the last-online decomposition — because every one of those is a *lookup the
-//! engine owns* in the real client too. Unlike the friend list and `/who`, the guild roster
-//! carries level/class/zone for **offline** members as well (the server keeps them in the guild
-//! table), which is why those columns stay populated and merely grey out.
-//!
-//! **Guild identity and guild roster are two different caches, and this file joins them.**
-//! `SMSG_GUILD_ROSTER` carries the MOTD, the info text, the rank *rights* and the members — but
-//! **not** the guild's name and **not** the rank *names*. Those come only from
-//! `SMSG_GUILD_QUERY_RESPONSE`, which answers a `CMSG_GUILD_QUERY(guildId)` with the name plus a
-//! fixed array of ten rank names. The app does the joining before it pushes; [`GuildState`] is
-//! the joined result.
-//!
-//! **Two index bases coexist, and callers must convert.** A roster row's `rankIndex` (from
-//! `GetGuildRosterInfo`) is **0-based**, `0` = guild master — the reference computes
-//! `maxRankIndex = GuildControlGetNumRanks() - 1` and compares roster indices against it
-//! (`FriendsFrame.lua:338`, `:393-398`). The whole `GuildControl*` family is **1-based**, driven
-//! straight off dropdown IDs `1..GuildControlGetNumRanks()` (`:820-822`, `:855-857`, `:866-868`).
-//! Mixing them silently promotes the wrong rank, so every conversion here is spelled out.
-//!
-//! **Rank-control edits are staged, and the staging is write-only.** `GuildControlSetRank(i)`
-//! loads rank `i` into [`GuildRankEdit`], `GuildControlSetRankFlag(idx, on)` writes one staged
-//! slot, and `GuildControlSaveRank(name)` folds the thirteen slots over a freshly re-read *live*
-//! baseline and queues one intent. The buffer is deliberately *not* part of the pushed snapshot:
-//! it is scratch the popup owns between open and Accept, and a snapshot push mid-edit would
-//! otherwise discard the user's unsaved checkbox clicks.
-//!
-//! The counter-intuitive half, and it is verified: **`GuildControlGetRankFlags` reads the LIVE
-//! rights, never the staging buffer.** A checkbox click is invisible through the getter until the
-//! save round-trips and a fresh roster lands. Reading the buffer back would feel more responsive
-//! and would be a different client.
-//!
-//! **The roster is never filtered.** `GetGuildRosterInfo`, `GetGuildRosterLastOnline` and
-//! `SetGuildRosterSelection` all address the *whole* member list; only `GetNumGuildMembers`
-//! respects the show-offline toggle, and indices past it are valid and return real offline
-//! members. See [`GuildState::num_members`] — this is the opposite of the obvious design, and
-//! collapsing the two is the mistake it exists to prevent.
-//!
-//! **Era booleans are `1`/`nil`, never `true`/`false`** — `IsInGuild`, `IsGuildLeader` and every
-//! `Can*` predicate below. The FrameXML branches on truthiness and stores the result, so a
-//! `false` where the reference gives `nil` survives into places a `nil` would not.
+//! Two index bases: a roster `rankIndex` is 0-based with 0 the guild master
+//! (`FriendsFrame.lua:338`, `:393-398`), while the `GuildControl*` family is 1-based, driven by
+//! the dropdown IDs (`FriendsFrame.lua:820-822`, `:855-857`, `:866-868`).
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// The thirteen guild rank permissions, **in `GuildControlGetRankFlags`' return order** — which is
-/// also `GuildControlPopupFrameCheckbox1..13`'s order and the index `GuildControlSetRankFlag`
-/// takes. That ordering *is* the API contract: `GuildControlCheckboxUpdate` loops
-/// `for i=1, arg.n` over the returns and drives `getglobal("GuildControlPopupFrameCheckbox"..i)`
-/// (`FriendsFrame.lua:874-884`), so nothing but position connects a flag to its checkbox.
+/// The thirteen rank rights in `GuildControlGetRankFlags`' return order, which is also the
+/// checkbox order and `GuildControlSetRankFlag`'s index: only position ties a flag to its checkbox
+/// (`FriendsFrame.lua:874-884`). The labels are `GUILDCONTROL_OPTION1..13`
+/// (`GlobalStrings.lua:2036-2048`).
 ///
-/// The labels, in this order, are `GUILDCONTROL_OPTION1..13`
-/// (`GlobalStrings.lua:2036-2048`): Guildchat Listen · Guildchat Speak · Officerchat Listen ·
-/// Officerchat Speak · Promote · Demote · Invite Member · Remove Member · Set MOTD ·
-/// Edit Public Note · View Officer Note · Edit Officer Note · Modify Guild Info.
-///
-/// **The map is not monotonic, and that is the whole reason it is a table rather than a shift.**
-/// Promote (index 5) is `0x80` and Demote (6) is `0x100`, both *above* Invite (7) `0x10` and
-/// Remove (8) `0x20` in bit value while *below* them in checkbox order. `1 << (i - 1)` is wrong
-/// for nine of the thirteen. Bits `0x40`, `0x400` and `0x800` are unused.
-///
-/// Bits from vmangos `src/game/Guild/Guild.h:56-74` (`GuildRankRights`), with that enum's
-/// `GR_RIGHT_EMPTY` (`0x40`) stripped — it is OR'd into every one of its entries, so it carries no
-/// per-permission information.
+/// Not bit order: Promote and Demote (5, 6) are `0x80` and `0x100`, above Invite and Remove
+/// (7, 8) at `0x10` and `0x20`, so `1 << (i - 1)` is wrong for nine of the thirteen. The bits are
+/// vmangos `GuildRankRights` (`Guild/Guild.h:56-74`) without the `GR_RIGHT_EMPTY` `0x40` it ORs
+/// into each; `0x40`, `0x400` and `0x800` are none of the thirteen.
 pub const RANK_RIGHT_BITS: [u32; 13] = [
     0x0000_0001, // 1  Guildchat Listen
     0x0000_0002, // 2  Guildchat Speak
@@ -87,9 +36,7 @@ pub const RANK_RIGHT_BITS: [u32; 13] = [
     0x0001_0000, // 13 Modify Guild Info
 ];
 
-/// Named indices into [`RANK_RIGHT_BITS`], for the `Can*` predicates. One-based, matching the
-/// checkbox numbering the reference's strings use, so a reader can check them against
-/// `GUILDCONTROL_OPTION<n>` without arithmetic.
+/// One-based indices into [`RANK_RIGHT_BITS`], numbered as `GUILDCONTROL_OPTION<n>`.
 mod right {
     pub(super) const PROMOTE: usize = 5;
     pub(super) const DEMOTE: usize = 6;
@@ -102,24 +49,16 @@ mod right {
     pub(super) const MODIFY_GUILD_INFO: usize = 13;
 }
 
-/// The lowest and highest rank counts a guild can have — the reference's own guard rails, which
-/// it enforces client-side before the server ever sees the request:
-/// `GuildControlPopupFrameAddRankButton_OnUpdate` disables Add at `>= 10`
-/// (`FriendsFrame.lua:887`) and `..RemoveRankButton_OnUpdate` only shows Remove when the selected
-/// rank is the last *and* the count exceeds 5 (`:908`). Same numbers as vmangos'
-/// `GUILD_RANKS_MIN_COUNT` / `GUILD_RANKS_MAX_COUNT` (`Guild.h:31-32`).
+/// The fewest ranks: `GuildControlDelRank` refuses at it and the Remove button shows only above it
+/// (`FriendsFrame.lua:908`); vmangos `GUILD_RANKS_MIN_COUNT` (`Guild/Guild.h:31`).
 pub const MIN_RANKS: usize = 5;
-/// See [`MIN_RANKS`].
+/// The most ranks: `GuildControlAddRank` refuses at it and the Add button disables there
+/// (`FriendsFrame.lua:887`); vmangos `GUILD_RANKS_MAX_COUNT` (`Guild/Guild.h:32`).
 pub const MAX_RANKS: usize = 10;
 
-/// How long ago a member was last seen, already decomposed into the four units
-/// `GetGuildRosterLastOnline` returns. The wire carries one `f32` — days since last login, sent
-/// only for *offline* members — and the decomposition is engine math, so the app does it once and
-/// the VM just reports it.
-///
-/// The reference reads these largest-unit-first and stops at the first non-zero
-/// (`GuildFrame_GetLastOnline`, `FriendsFrame.lua:957-978`), so the contract that matters is that
-/// exactly the largest applicable unit is non-zero.
+/// `GetGuildRosterLastOnline`'s four units, decomposed by the app from the wire's one `f32` of
+/// days offline. `GuildFrame_GetLastOnline` shows the largest non-zero unit, reading nil as 0
+/// (`FriendsFrame.lua:957-978`).
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub struct LastOnline {
     pub years: u32,
@@ -128,190 +67,139 @@ pub struct LastOnline {
     pub hours: u32,
 }
 
-/// A unit's guild membership, as `GetGuildInfo(unit)` reports it — hung off
-/// [`super::unit::UnitState`] because the binding is per-unit and the descriptor is public.
-///
-/// `PLAYER_GUILDID` (field 191) and `PLAYER_GUILDRANK` (field 192) are PUBLIC, so these arrive
-/// for *every visible player*, not just us (vmangos `Objects/UpdateFields_1_12_1.h:121-122`;
-/// UNIT_END = 188, the same arithmetic that pins `PLAYER_FLAGS` = 190). The app turns the id into
-/// a name through its guild-identity cache and the rank field into a rank name through that
-/// identity's ten rank names — which is exactly why the query response carries a fixed ten.
+/// A unit's guild as `GetGuildInfo(unit)` reports it. `PLAYER_GUILDID` (191) and
+/// `PLAYER_GUILDRANK` (192) are public descriptor fields (vmangos
+/// `Objects/UpdateFields_1_12_1.h:121-122`), so every visible player carries one; the app names
+/// them through its guild query cache.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct UnitGuild {
-    /// The guild's name — **never empty**.
-    ///
-    /// A cache miss does not produce a blank-named `UnitGuild`: it produces `None`. The binding
-    /// takes the *same* nil path on the cache-miss leg (`0x4c93d7 je 0x4c943c`) as on the
-    /// guildless leg, so "we have not resolved this id yet" and "this unit has no guild" are
-    /// indistinguishable to Lua by design. That matters — `UnitPopup.lua:575` passes the result
-    /// straight into a StaticPopup format, and an empty name would render `<>` there.
+    /// Never empty: an unresolved guild is `None`, as the binding takes the same nil path on a
+    /// cache miss as for no guild (`0x4c93d7 je 0x4c943c`).
     pub name: String,
-    /// The unit's rank name within that guild.
     pub rank_name: String,
-    /// The unit's rank, **0-based**, `0` = guild master.
+    /// 0-based, 0 the guild master.
     pub rank_index: u32,
 }
 
-/// One guild rank: its name (from the query response) and its rights word (from the roster).
+/// One guild rank: its name from the guild query, its rights from the roster.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct GuildRankInfo {
-    /// The rank's display name, e.g. "Guild Master". Empty for a rank the query response has not
-    /// named yet.
+    /// Empty until the guild query names it.
     pub name: String,
-    /// The rank's permission bits — test with [`RANK_RIGHT_BITS`].
+    /// Tested with [`RANK_RIGHT_BITS`].
     pub rights: u32,
 }
 
-/// One roster row, already resolved for display. Mirrors `GetGuildRosterInfo`'s nine returns in
-/// field order, which is how `FriendsFrame.lua` destructures them (`:344`, `:447`, `:479`).
+/// One roster row resolved for display: `GetGuildRosterInfo`'s ten returns in order, then the
+/// last-online time.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct GuildMemberInfo {
-    /// The character's name. Carried on the wire in the roster itself, so unlike a friend row
-    /// this never waits on a name query.
+    /// On the wire in the roster itself, so it never waits on a name query.
     pub name: String,
-    /// The member's rank *name*, e.g. "Officer" — `GetGuildRosterInfo`'s second return.
+    /// The rank's name.
     pub rank: String,
-    /// The member's rank as a **0-based** index, `0` = guild master. See the module doc: this is
-    /// the opposite base from the `GuildControl*` family.
+    /// 0-based, 0 the guild master; the `GuildControl*` family is 1-based.
     pub rank_index: u32,
     pub level: u32,
-    /// Localized class name ("Warrior"). Populated for offline members too.
+    /// The localized class name. The roster carries class, level and zone for offline members too.
     pub class: String,
-    /// Zone name ("Elwynn Forest"), empty when the id has no `AreaTable` row.
+    /// The zone name, empty when the id has no `AreaTable` row.
     pub zone: String,
     /// The public note.
     pub note: String,
-    /// The officer note. The server sends this empty when the *viewer* lacks
-    /// `View Officer Note`, so an empty string here is "not permitted" and "not set" alike —
-    /// which is exactly what the reference can distinguish too (it gates on `CanViewOfficerNote`
-    /// separately rather than on emptiness).
+    /// Empty both when unset and when the server blanks it for a viewer without View Officer
+    /// Note; the frame gates on `CanViewOfficerNote` instead.
     pub officer_note: String,
     pub online: bool,
-    /// The away tag, exactly as the friends list spells it: `""`, `"<AFK>"` or `"<DND>"` —
-    /// `GetGuildRosterInfo`'s **tenth** return.
-    ///
-    /// It is easy to miss that there is a tenth. Six of the reference's seven call sites
-    /// destructure only nine (`FriendsFrame.lua:344`, `:447`, `:479`, `:709`,
-    /// `StaticPopup.lua:1008`, `:1045`) — but the player-status view takes ten
-    /// (`FriendsFrame.lua:541`) and then branches on `status == ""` to choose between the
-    /// "Online" label and the tag itself (`:548-551`). An engine that answered nil there would
-    /// blank that column silently, and every nine-value call site would keep working.
-    ///
-    /// This is also what the wire's presence byte is *for*: `GRF_ONLINE`/`GRF_AFK`/`GRF_DND`
-    /// (0x01/0x02/0x04) would not need three bits if the API only exposed a boolean.
+    /// The tenth return: `""`, `"<AFK>"` or `"<DND>"`. Only the status view reads it, to choose
+    /// between the Online label and the tag (`FriendsFrame.lua:541`, `:548-551`).
     pub status: String,
-    /// How long since this member was last seen — meaningful only when `online` is false. The
-    /// wire omits it entirely for online members.
+    /// Meaningful only offline; the wire omits it for online members.
     pub last_online: LastOnline,
 }
 
-/// The guild snapshot, pushed whole by the app whenever it changes ([`UiScript::set_guild`]).
-/// `default()` is the guildless shape, which is also the fresh-login shape.
+/// The guild snapshot the app pushes whole when it changes ([`UiScript::set_guild`]); the default
+/// is guildless.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct GuildState {
-    /// Whether the player is in a guild at all — `IsInGuild`. Driven by the player's own
-    /// `PLAYER_GUILDID` descriptor field (191), so it is true from the moment the descriptor
-    /// streams, *before* any roster has arrived.
+    /// `IsInGuild`, from the player's own `PLAYER_GUILDID` (191), so true before any roster.
     pub in_guild: bool,
-    /// The guild's name. Only `SMSG_GUILD_QUERY_RESPONSE` carries it, so it stays empty in the
-    /// window between `in_guild` going true and that query answering.
+    /// Only `SMSG_GUILD_QUERY_RESPONSE` carries it, so it is empty until that query answers.
     pub name: String,
-    /// The player's own rank name.
     pub rank_name: String,
-    /// The player's own rank, **0-based**, `0` = guild master.
+    /// The player's own rank, 0-based, 0 the guild master.
     pub rank_index: u32,
-    /// Whether the player is the guild master — `IsGuildLeader`.
+    /// `IsGuildLeader`: the player is the guild master.
     pub is_leader: bool,
-    /// The player's own rank's rights word, which every `Can*` predicate tests.
+    /// The player's own rank's rights, which every `Can*` predicate tests.
     pub rights: u32,
-    /// The message of the day.
     pub motd: String,
-    /// The guild info text (the `GuildInfoFrame` body).
+    /// The `GuildInfoFrame` body.
     pub info_text: String,
-    /// The **whole** roster, sorted — never filtered. `GetGuildRosterInfo` indexes this directly,
-    /// 1-based, and so do `GetGuildRosterLastOnline` and `SetGuildRosterSelection`.
-    ///
-    /// **It is NOT filtered by [`Self::show_offline`], and its length is NOT
-    /// `GetNumGuildMembers()`.** See [`Self::num_members`] — this asymmetry is verified and it is
-    /// the opposite of what the obvious design would do.
+    /// The whole roster, sorted and never filtered: `GetGuildRosterInfo`,
+    /// `GetGuildRosterLastOnline` and `SetGuildRosterSelection` index it 1-based.
     pub roster: Vec<GuildMemberInfo>,
-    /// What `GetNumGuildMembers()` reports: the count the UI loops to, which **does** respect
-    /// [`Self::show_offline`].
-    ///
-    /// **This is an advisory loop bound, not the addressable range.** In the real client the three
-    /// index-taking bindings all bound against the *full* member count (`[0xb73118]`) and never
-    /// read the show-offline flag at all, while `GetNumGuildMembers` answers a different number
-    /// entirely — so **indices past it are valid and return real offline members**.
-    ///
-    /// Collapsing the two — filtering the vector and reporting its length — is the natural design
-    /// and it is wrong: it would make a selection that survives a show-offline toggle address a
-    /// different member, or none.
+    /// `GetNumGuildMembers()`, the UI's loop bound, which respects [`Self::show_offline`]. The
+    /// index-taking bindings bound against the full count (`[0xb73118]`) and never read the flag,
+    /// so an index past this still returns a real offline member.
     pub num_members: usize,
-    /// Every rank, index 0 = guild master. Length is the guild's real rank count, which is what
-    /// `GuildControlGetNumRanks` reports.
+    /// Every rank, 0 the guild master; the length is `GuildControlGetNumRanks`.
     pub ranks: Vec<GuildRankInfo>,
-    /// The selected roster row as a **1-based** index into [`Self::roster`], `0` = none — the
-    /// scale `GetGuildRosterSelection` reports and `FriendsFrame.lua:347` tests with `> 0`.
+    /// The selected row, 1-based into [`Self::roster`], 0 for none (`FriendsFrame.lua:347` tests
+    /// `> 0`).
     pub selection: u32,
-    /// Whether the UI is showing offline members. Affects [`Self::num_members`] only — never
-    /// [`Self::roster`]'s contents.
+    /// Changes [`Self::num_members`] only, never [`Self::roster`].
     pub show_offline: bool,
 }
 
-/// The rank-control popup's staging buffer — the rank it has loaded and the rights word it has
-/// been editing. See the module doc on why this is not part of the pushed snapshot.
+/// The rank-control popup's staging buffer, kept out of [`GuildState`] so a push mid-edit does not
+/// discard unsaved checkbox clicks.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct GuildRankEdit {
-    /// The **1-based** rank `GuildControlSetRank` last loaded; `0` = none loaded yet.
+    /// The 1-based rank `GuildControlSetRank` last loaded, 0 for none.
     pub rank: u32,
-    /// The thirteen staged checkbox states, positionally matching [`RANK_RIGHT_BITS`].
-    ///
-    /// Held per-flag rather than as a packed word because that is what the binding does — it
-    /// stages `mask[k] & rights` into thirteen separate slots and `SetRankFlag` writes exactly
-    /// one of them. Keeping a word here instead would work only as long as nothing outside the
-    /// thirteen bits mattered, and `0x40` is precisely such a bit.
+    /// The thirteen staged checkboxes in [`RANK_RIGHT_BITS`] order, one slot per flag as the
+    /// binding stages them, so the save leaves every other bit of the live rights alone.
     pub staged: [bool; 13],
 }
 
-/// Outbound guild intents queued by the Era API, drained by the app
-/// ([`UiScript::take_guild_requests`]). Plain data — [`super::social::SocialRequest`]'s twin.
+/// Outbound guild intents, drained by the app ([`UiScript::take_guild_requests`]).
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum GuildRequest {
-    /// `GuildRoster()` — ask the server for a fresh roster (`CMSG_GUILD_ROSTER`). Throttled
-    /// app-side to one per 10 s, as the reference is; the `GUILD_ROSTER_UPDATE` arg1 path clears
-    /// that throttle first so the FrameXML's response request is never the one swallowed.
+    /// `GuildRoster()` (`CMSG_GUILD_ROSTER`). The app throttles it to one per 10 s as the reference
+    /// does; the `GUILD_ROSTER_UPDATE` arg1 path clears the throttle first, so the FrameXML's own
+    /// request is never the one dropped.
     Roster,
-    /// `GuildInfo()` — the `/ginfo` query (`CMSG_GUILD_INFO`), whose answer is a chat line.
+    /// `GuildInfo()`, the `/ginfo` query (`CMSG_GUILD_INFO`), answered as a chat line.
     Info,
     /// `GuildInviteByName(name)`.
     Invite(String),
-    /// `GuildUninviteByName(name)` — remove a member (`CMSG_GUILD_REMOVE`).
+    /// `GuildUninviteByName(name)` (`CMSG_GUILD_REMOVE`).
     Uninvite(String),
     /// `GuildPromoteByName(name)`.
     Promote(String),
     /// `GuildDemoteByName(name)`.
     Demote(String),
-    /// `GuildSetLeaderByName(name)` — hand over the guild.
+    /// `GuildSetLeaderByName(name)`.
     SetLeader(String),
-    /// `AcceptGuild()` — the `GUILD_INVITE` popup's Accept.
+    /// `AcceptGuild()`.
     Accept,
-    /// `DeclineGuild()` — its Decline.
+    /// `DeclineGuild()`.
     Decline,
     /// `GuildLeave()`.
     Leave,
     /// `GuildDisband()`.
     Disband,
-    /// `GuildSetMOTD(text)`. An empty string is a real value meaning "clear it".
+    /// `GuildSetMOTD(text)`; an empty string clears it.
     SetMotd(String),
     /// `SetGuildInfoText(text)`.
     SetInfoText(String),
-    /// `GuildRosterSetPublicNote(index, note)` — the index is the 1-based display row, which the
-    /// app resolves to the name the wire wants.
+    /// `GuildRosterSetPublicNote(index, note)`: a 1-based display row the app resolves to the name
+    /// the wire takes.
     SetPublicNote { index: u32, note: String },
     /// `GuildRosterSetOfficerNote(index, note)`.
     SetOfficerNote { index: u32, note: String },
-    /// `GuildControlSaveRank(name)` — the staged buffer flushed as one `CMSG_GUILD_RANK`. The
-    /// rank is carried **0-based**, converted here once, because that is the base the wire uses.
+    /// `GuildControlSaveRank(name)` as one `CMSG_GUILD_RANK`; the rank is 0-based, as on the wire.
     SaveRank {
         rank_index: u32,
         rights: u32,
@@ -319,23 +207,21 @@ pub enum GuildRequest {
     },
     /// `GuildControlAddRank(name)`.
     AddRank(String),
-    /// `GuildControlDelRank()` — delete the last rank. **Carries nothing**: the binding reads no
-    /// argument and the packet (`0x233`) is body-less; the server infers which rank.
+    /// `GuildControlDelRank()`: no argument and an empty `0x233`; the server deletes the last rank.
     DelRank,
-    /// `SetGuildRosterSelection(index)` — mirrored into the app so the next push agrees.
+    /// `SetGuildRosterSelection(index)`, mirrored so the next push agrees.
     Select(u32),
-    /// `SetGuildRosterShowOffline(flag)` — the app re-filters and pushes back.
+    /// `SetGuildRosterShowOffline(flag)`, mirrored so the next push agrees.
     SetShowOffline(bool),
-    /// `SortGuildRoster(field)` — one of `"name"`, `"zone"`, `"level"`, `"class"`, `"rank"`,
-    /// `"note"`, `"online"` (the seven the reference's two column sets set as `this.sortType`,
-    /// `FriendsFrame.xml:1895-1940` and `:2086-2131`). Sorting is client-side; the app re-orders
-    /// its own roster and pushes it back.
+    /// `SortGuildRoster(field)`: `"name"`, `"zone"`, `"level"`, `"class"`, `"rank"`, `"note"` or
+    /// `"online"`, the headers' `sortType`s (`FriendsFrame.xml:1895-1940`, `:2086-2131`). Sorting
+    /// is client-side: the app re-orders its roster and pushes it back.
     Sort(String),
 }
 
 impl super::UiScript {
-    /// Push the guild snapshot, replacing whatever was there. A bare setter — firing
-    /// `GUILD_ROSTER_UPDATE`/`PLAYER_GUILD_UPDATE`/`GUILD_MOTD` on the edges is the app's job.
+    /// Push the guild snapshot, replacing it. The app fires `GUILD_ROSTER_UPDATE`,
+    /// `PLAYER_GUILD_UPDATE` and `GUILD_MOTD` on the edges.
     pub fn set_guild(&mut self, state: GuildState) {
         self.model_mut().guild = state;
     }
@@ -345,16 +231,14 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().guild_requests)
     }
 
-    /// Queue an intent from the app side — the slash commands (`/ginvite`, `/gquit`, `/gpromote`,
-    /// …). In the reference these ARE Lua (`SlashCmdList["GUILDINVITE"]` calls
-    /// `GuildInviteByName`); benilla parses slash lines in Rust, so the same intents enter the
-    /// same queue here. [`super::social::SocialRequest`]'s `queue_social_request` twin.
+    /// Queue an intent from a slash command (`/ginvite`, `/gquit`, `/gpromote`, ...). The
+    /// reference's slash commands are Lua calling the same bindings; benilla parses them in Rust.
     pub fn queue_guild_request(&mut self, request: GuildRequest) {
         self.model_mut().guild_requests.push(request);
     }
 }
 
-/// A roster row by 1-based display index, or `None` past the end.
+/// A roster row by 1-based index.
 fn member_at(roster: &[GuildMemberInfo], index: i64) -> Option<&GuildMemberInfo> {
     usize::try_from(index)
         .ok()
@@ -362,9 +246,9 @@ fn member_at(roster: &[GuildMemberInfo], index: i64) -> Option<&GuildMemberInfo>
         .and_then(|i| roster.get(i))
 }
 
-/// The Era truthiness coercion for a flag argument — `nil`, `false` and `0` are off, everything
-/// else is on. [`super::social`]'s `SetWhoToUI` does the same, and for the same reason: the
-/// FrameXML passes a checkbox's `GetChecked()`, which is `1`/`nil`, but addons pass booleans.
+/// A flag argument: `nil`, `false` and `0` are off, anything else on. The reference reads both
+/// flags with `GetBoolOrDefault` (`0x6f1c10`, `binding_abi::bool_or_default`), which differs on
+/// strings and fractions; the FrameXML's checkbox states, `1` or `nil`, read the same in both.
 fn truthy(value: &Value) -> bool {
     match value {
         Value::Nil | Value::Boolean(false) => false,
@@ -374,7 +258,8 @@ fn truthy(value: &Value) -> bool {
     }
 }
 
-/// The Era boolean: `1` for true, `nil` for false. See the module doc — this is not `Boolean`.
+/// The 1.12 boolean, `1` or `nil`: the FrameXML stores what it tests, so a `false` would survive
+/// where the reference's `nil` does not.
 fn era_bool(on: bool) -> Value {
     if on {
         Value::Integer(1)
@@ -383,17 +268,13 @@ fn era_bool(on: bool) -> Value {
     }
 }
 
-/// Whether the player's own rank holds the permission at `index` (1-based into
-/// [`RANK_RIGHT_BITS`]).
+/// Whether the player's own rank holds right `index`, 1-based into [`RANK_RIGHT_BITS`].
 fn has_right(model: &Model, index: usize) -> bool {
     model.guild.in_guild && model.guild.rights & RANK_RIGHT_BITS[index - 1] != 0
 }
 
-/// The **live** rights word of a 1-based rank, `0` for "no rank loaded" or out of range.
-///
-/// The rank editor reads live rights, never its own staging buffer — see
-/// `GuildControlGetRankFlags`. Factored out because `GuildControlSaveRank` needs the same value as
-/// its fold baseline, and the two reading different things is exactly how a save would drop bits.
+/// The live rights of a 1-based rank, 0 for none or out of range. `GuildControlGetRankFlags` and
+/// `GuildControlSaveRank`'s fold both read this, never the staging buffer.
 fn live_rights(model: &Model, rank_one_based: u32) -> u32 {
     (rank_one_based as usize)
         .checked_sub(1)
@@ -403,11 +284,9 @@ fn live_rights(model: &Model, rank_one_based: u32) -> u32 {
 }
 
 /// The rank-name gate `GuildControlSaveRank` (`0x4d20d0`) and `GuildControlAddRank` (`0x4d2210`)
-/// both run before any packet, byte-for-byte the same: the C string (so up to the first NUL) must
-/// be non-empty and `0x65b250(name) - 1` — its UTF-16 code-unit count — must lie in `1..=16`.
-/// Nothing else: no trim, so a whitespace name passes. The name the gate measured is the name
-/// sent. vmangos's own cap is 15 code points and it kicks over it; that server-side limit is the
-/// app's to enforce at the send (`ui_guild::feed::capped_rank_name`), not the binding's.
+/// run before any packet: the name up to the first NUL must be 1 to 16 UTF-16 code units
+/// (`0x65b250`), untrimmed, and is sent as measured. vmangos kicks a name over 15 code points; the
+/// app caps that at the send (`ui_guild::feed::capped_rank_name`).
 fn gated_rank_name(name: &str) -> Option<&str> {
     let c_name = name.split('\0').next().unwrap_or_default();
     (1..=16)
@@ -415,13 +294,13 @@ fn gated_rank_name(name: &str) -> Option<&str> {
         .then_some(c_name)
 }
 
-/// Register the guild globals against the snapshot store.
+/// Register the guild globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
     // ── Membership and identity ──────────────────────────────────────────────────────────────
-    // IsInGuild() (`0x516de0`) — reads the player's own PLAYER_GUILDID, so it is answerable
-    // before any roster arrives. `InGuildCheck` gates the whole tab on it.
+    // IsInGuild() (`0x516de0`) reads the player's own `PLAYER_GUILDID`, so it answers before any
+    // roster arrives.
     g.set(
         "IsInGuild",
         lua.create_function(|lua, ()| {
@@ -430,8 +309,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsGuildLeader() (`0x516e40`) — takes no argument; it reports whether the PLAYER is the
-    // guild master, which is rank 0.
+    // IsGuildLeader() (`0x516e40`) takes no argument: whether the player is the guild master.
     g.set(
         "IsGuildLeader",
         lua.create_function(|lua, ()| {
@@ -440,30 +318,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetGuildInfo(unit) → guildName, rankName, rankIndex (`0x4c9330`). Every call site in 1.12's
-    // FrameXML passes "player" (`FriendsFrame.lua:114`, `:337`, `PaperDollFrame.lua:117`,
-    // `TabardFrame.lua:96`, `UnitPopup.lua:575`), but the binding is per-unit and the wire
-    // supports it: PLAYER_GUILDID (191) and PLAYER_GUILDRANK (192) are PUBLIC descriptor fields,
-    // and the query response's fixed ten rank names exist precisely so another unit's rank field
-    // can be turned into a rank name. So it reads the unit snapshot, not the player's guild.
-    //
-    // A guildless unit answers `nil, nil, 0` — three values, and the third is the NUMBER zero, not
-    // nil. The binding pushes 3 on both legs (`mov eax,3`), so a caller destructuring the third
-    // gets `0`. Returning nil there would be a different contract.
-    //
-    // **RECOGNISED and UNRESOLVABLE are two different things**, and this binding conflated them
-    // until the stock character sheet came off the chain (decision 1751). It resolves its argument
-    // through the GENERAL unit-token resolver `0x515940`, so an *unrecognised* token raises via the
-    // L-less `luaL_error 0x7040e0` at `0x515c1a` — but "a recognised-but-unresolvable token, a
-    // non-player, a guildless player and a not-yet-arrived cache record ALL return (nil, nil, 0)"
-    // (`0x4c9330`).
-    //
-    // Ours raised on any token the model held no unit for, which includes `"player"` before the
-    // app has pushed the first snapshot. Stock `PaperDollFrame_SetGuild` calls
-    // `GetGuildInfo("player")` UNGUARDED out of `PaperDollFrame_OnShow` (`PaperDollFrame.lua:117`,
-    // reached from `:569`), so opening the character window in the frames before that push raised
-    // where the reference prints an empty guild line. [`check_unit_token`] is the resolver's own
-    // three-way split and every other unit binding already goes through it.
+    // GetGuildInfo(unit) → guildName, rankName, rankIndex (`0x4c9330`), per unit because the rank
+    // fields are public: it reads the unit snapshot, not the player's guild. The general resolver
+    // (`0x515940`) raises on an unrecognised token (`0x515c1a`); a recognised but unresolvable
+    // token, a non-player, a guildless player and an unarrived guild record all answer
+    // `nil, nil, 0`, the third the number 0 (`mov eax,3` on both legs). Stock
+    // `PaperDollFrame_SetGuild` calls it for `"player"` unguarded (`PaperDollFrame.lua:117`).
     g.set(
         "GetGuildInfo",
         lua.create_function(|lua, unit: Option<String>| {
@@ -484,9 +344,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── The roster ───────────────────────────────────────────────────────────────────────────
-    // GetNumGuildMembers() (`0x4d1190`) — the loop bound `GuildStatus_Update` iterates to
-    // (`FriendsFrame.lua:446`), NOT the addressable range. It respects show-offline;
-    // GetGuildRosterInfo does not. See `GuildState::num_members` for why the two differ.
+    // GetNumGuildMembers() (`0x4d1190`): the loop bound (`FriendsFrame.lua:446`), which respects
+    // show-offline, not the addressable range (`GuildState::num_members`).
     g.set(
         "GetNumGuildMembers",
         lua.create_function(|lua, ()| {
@@ -496,17 +355,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // GetGuildRosterInfo(index) → name, rank, rankIndex, level, class, zone, note, officernote,
-    // online, status (`0x4d1200`). TEN returns, in that order.
-    //
-    // The tenth is easy to miss and expensive to miss: six of the reference's seven call sites
-    // take only nine (`FriendsFrame.lua:344`, `:447`, `:479`, `:709`, `StaticPopup.lua:1008`,
-    // `:1045`), and only the player-status view takes `status` (`:541`) to choose between the
-    // "Online" label and the `<AFK>`/`<DND>` tag (`:548-551`). Answering nine would leave that one
-    // column permanently blank while every other caller looked correct.
-    //
-    // An out-of-range index answers all-nils rather than erroring: the reference calls it with
-    // `GetGuildRosterSelection()`, which is 0 when nothing is selected, on every single
-    // `GuildStatus_Update` (`:344`) and only afterwards checks `> 0`.
+    // online, status (`0x4d1200`). Ten returns: only the status view takes the tenth
+    // (`FriendsFrame.lua:541`), every other call site nine. Out of range answers ten nils rather
+    // than raising: `GuildStatus_Update` passes the selection, 0 when none, before testing it
+    // (`FriendsFrame.lua:344`, `:347`).
     g.set(
         "GetGuildRosterInfo",
         lua.create_function(|lua, index: i64| {
@@ -529,10 +381,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetGuildRosterLastOnline(index) → years, months, days, hours (`0x4d14a0`). The reference
-    // reads them largest-first and stops at the first non-zero (`GuildFrame_GetLastOnline`,
-    // `FriendsFrame.lua:957-978`), and treats nil exactly as 0, so an online member — for whom
-    // the wire sends no value at all — correctly falls through to "online now".
+    // GetGuildRosterLastOnline(index) → years, months, days, hours (`0x4d14a0`), all 0 for an
+    // online member, whom the wire sends no time for.
     g.set(
         "GetGuildRosterLastOnline",
         lua.create_function(|lua, index: i64| {
@@ -550,7 +400,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetGuildRosterMOTD() / GetGuildInfoText() — the two free-text blocks the roster carries.
+    // GetGuildRosterMOTD() / GetGuildInfoText(): the two free-text blocks the roster carries.
     g.set(
         "GetGuildRosterMOTD",
         lua.create_function(|lua, ()| {
@@ -566,11 +416,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetGuildRosterSelection() (`0x4d1890`) / SetGuildRosterSelection(index) (`0x4d1820`).
-    // 1-based, 0 = nothing selected. The setter mutates the snapshot in place *and* queues the
-    // intent, for [`super::social`]'s stated reason: the same Lua tick reads the new value back —
-    // `GuildStatus_Update` calls `GetGuildRosterSelection()` four times in one pass — and the
-    // app's own state has to follow so the next push agrees.
+    // GetGuildRosterSelection() (`0x4d1890`) / SetGuildRosterSelection(index) (`0x4d1820`):
+    // 1-based, 0 for none. The setter writes the snapshot and queues the intent: the same Lua pass
+    // reads it back, and the app's state must follow so the next push agrees.
     g.set(
         "GetGuildRosterSelection",
         lua.create_function(|lua, ()| {
@@ -590,8 +438,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetGuildRosterShowOffline() (`0x4d1e30`) / SetGuildRosterShowOffline(flag). Same
-    // mutate-and-mirror shape: the checkbox reads its own state back through the getter.
+    // GetGuildRosterShowOffline() (`0x4d1e30`) / SetGuildRosterShowOffline(flag): written in
+    // place and mirrored, as the selection is.
     g.set(
         "GetGuildRosterShowOffline",
         lua.create_function(|lua, ()| {
@@ -599,10 +447,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(era_bool(model.guild.show_offline))
         })?,
     )?;
-    //
-    // **Called with NO argument it defaults to TRUE**, not false — verified, and the opposite of
-    // what `truthy(nil)` would give. So an absent argument and an explicit `nil` differ here, and
-    // the binding must be able to tell them apart: hence `MultiValue` rather than `Value`.
+    // With no argument it turns show-offline on, unlike an explicit `nil`, hence `MultiValue`.
     g.set(
         "SetGuildRosterShowOffline",
         lua.create_function(|lua, args: MultiValue| {
@@ -617,11 +462,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SortGuildRoster(field) (`0x4d1cb0`) — the column headers' only action: their OnClick is
-    // `if (this.sortType) then SortGuildRoster(this.sortType) end` and nothing else
-    // (`FriendsFrame.xml:442-446`). No GuildStatus_Update, no GuildRoster — so the engine both
-    // re-orders and fires GUILD_ROSTER_UPDATE itself, and plainly must not re-request the roster
-    // from the server because a user clicked a header. The app does both on the drain.
+    // SortGuildRoster(field) (`0x4d1cb0`): the header's OnClick calls no `GuildStatus_Update` and
+    // no `GuildRoster` (`FriendsFrame.xml:442-446`), so the app re-orders and fires
+    // `GUILD_ROSTER_UPDATE` on the drain, without asking the server.
     g.set(
         "SortGuildRoster",
         lua.create_function(|lua, field: String| {
@@ -631,14 +474,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CloseGuildRoster() is `xor eax,eax; ret` in the real client — a TOTAL no-op that sends
-    // nothing and touches nothing. It exists as a symbol and does not do anything. Wiring it to a
-    // packet would invent traffic 1.12 never sends, so it is registered and does nothing here too.
+    // CloseGuildRoster() is `xor eax,eax; ret` in the reference: a no-op that sends nothing.
     g.set("CloseGuildRoster", lua.create_function(|_, ()| Ok(()))?)?;
 
-    // GuildRoster() — ask the server for a fresh roster. Note the app throttles this to one
-    // request per 10 s, as the reference does, and the `GUILD_ROSTER_UPDATE` arg1 path clears that
-    // throttle so the FrameXML's own response request is never the one swallowed.
+    // The argument-less verbs; the app throttles `GuildRoster()` (`GuildRequest::Roster`).
     for (global, request) in [
         ("GuildRoster", GuildRequest::Roster),
         ("GuildInfo", GuildRequest::Info),
@@ -658,10 +497,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     }
 
     // ── The by-name verbs ────────────────────────────────────────────────────────────────────
-    // Five globals of one shape (`0x48aef0`, `0x48afb0`, `0x48b050`, `0x48b0f0`, `0x48b190`): take
-    // a character name, queue the matching CMSG. An empty name is dropped rather than sent — the
-    // server answers a blank lookup with nothing at all, so it would look like a hang
-    // ([`super::social`]'s `AddFriend` note).
+    // Five name-taking verbs (`0x48aef0`, `0x48afb0`, `0x48b050`, `0x48b0f0`, `0x48b190`). An empty
+    // or whitespace name is not sent. vmangos ignores an empty one without a reply, except an
+    // invite, which it answers with `ERR_GUILD_PLAYER_NOT_FOUND_S`
+    // (`Handlers/GuildHandler.cpp:77-83`).
     for (global, make) in [
         ("GuildInviteByName", GuildRequest::Invite as fn(String) -> _),
         (
@@ -690,9 +529,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // GuildSetMOTD(text) (`0x48b270`) / SetGuildInfoText(text) (`0x4d2380`). Unlike the by-name
-    // verbs, an EMPTY string is a real value here: it clears the block, and the wire has an
-    // explicit empty-body case for it. So these do not drop empties.
+    // GuildSetMOTD(text) (`0x48b270`) / SetGuildInfoText(text) (`0x4d2380`): an empty string is
+    // sent, and clears the text.
     for (global, make) in [
         ("GuildSetMOTD", GuildRequest::SetMotd as fn(String) -> _),
         (
@@ -710,9 +548,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // GuildRosterSetPublicNote(index, note) (`0x4d15e0`) / ...SetOfficerNote (`0x4d1700`) — the
-    // note dialogs address the roster ROW, not a name; the app resolves the row to the name the
-    // wire carries, because only it knows the display order the index refers to.
+    // GuildRosterSetPublicNote(index, note) (`0x4d15e0`) / GuildRosterSetOfficerNote (`0x4d1700`)
+    // take a roster row, which the app resolves to the name the wire carries.
     for (global, make) in [
         (
             "GuildRosterSetPublicNote",
@@ -739,10 +576,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     }
 
     // ── The permission predicates ────────────────────────────────────────────────────────────
-    // Nine one-line globals, each testing one bit of the player's own rank's rights word
-    // (`0x4d18c0`, `0x4d1930`, `0x4d19a0`, `0x4d1a10`, `0x4d1c40` and the four whose names lack
-    // "Guild"). CanEditMOTD/CanEditPublicNote/CanViewOfficerNote/CanEditOfficerNote are called at
-    // `FriendsFrame.lua:427`, `:359`, `:370`, `:371`.
+    // Nine predicates, each one bit of the player's own rank's rights (`0x4d18c0`, `0x4d1930`,
+    // `0x4d19a0`, `0x4d1a10`, `0x4d1c40` among them).
     for (global, index) in [
         ("CanGuildPromote", right::PROMOTE),
         ("CanGuildDemote", right::DEMOTE),
@@ -764,9 +599,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     }
 
     // ── The rank-control popup ───────────────────────────────────────────────────────────────
-    // GuildControlGetNumRanks() (`0x4d1e60`) — the guild's real rank count, which is what
-    // `maxRankIndex = GuildControlGetNumRanks() - 1` turns into the 0-based bottom rank
-    // (`FriendsFrame.lua:338`).
+    // GuildControlGetNumRanks() (`0x4d1e60`): the guild's rank count.
     g.set(
         "GuildControlGetNumRanks",
         lua.create_function(|lua, ()| {
@@ -775,8 +608,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GuildControlGetRankName(index) (`0x4d1e90`) — ONE-BASED, straight off the dropdown's ID
-    // (`FriendsFrame.lua:857`, `:868`, `:895`, `:899`). See the module doc on the two bases.
+    // GuildControlGetRankName(index) (`0x4d1e90`): 1-based, the dropdown's ID.
     g.set(
         "GuildControlGetRankName",
         lua.create_function(|lua, index: i64| {
@@ -791,14 +623,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GuildControlSetRank(index) (`0x4d1fa0`) — load a rank into the staging buffer. ONE-based;
-    // it stores `index - 1` internally and seeds each of the thirteen staged slots from that
-    // rank's live rights.
-    //
-    // Passing 0 computes -1 and **silently clears the staged selection** — verified, and the
-    // reason this is `checked_sub` rather than a clamp: a caller that handed a raw 0-based roster
-    // `rankIndex` straight in (the standing trap, see the module doc) gets nothing loaded rather
-    // than rank 1 quietly loaded in its place.
+    // GuildControlSetRank(index) (`0x4d1fa0`): load a 1-based rank into the staging buffer, each
+    // slot seeded from its live rights. 0 clears the selection rather than loading rank 1, so a
+    // 0-based `rankIndex` passed by mistake loads nothing.
     g.set(
         "GuildControlSetRank",
         lua.create_function(|lua, index: i64| {
@@ -814,20 +641,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GuildControlGetRankFlags() (`0x4d1fe0`) — THIRTEEN returns, one per checkbox, in
-    // RANK_RIGHT_BITS order. `GuildControlCheckboxUpdate` loops `for i=1, arg.n` over them
-    // (`FriendsFrame.lua:874-884`), so both the count and the order are load-bearing.
-    //
-    // It is called at `GuildControlPopupFrame_OnLoad` (`:801`) — BEFORE `_OnShow` ever calls
-    // `GuildControlSetRank`, so it must answer thirteen well-formed values with nothing loaded.
-    // An unloaded buffer reads as all-off, which leaves every checkbox unchecked: the same thing
-    // the reference shows on a popup that has not selected a rank yet.
-    //
-    // **It reads the LIVE rank's rights, NOT the staging buffer** — verified. A checkbox click
-    // stages a change that is invisible through this getter until `GuildControlSaveRank`
-    // round-trips through the server and a fresh roster lands. Reading the buffer here would look
-    // more responsive and would be a different client: the reference's checkboxes genuinely do
-    // not "stick" until the save comes back.
+    // GuildControlGetRankFlags() (`0x4d1fe0`): thirteen returns in `RANK_RIGHT_BITS` order, from
+    // the loaded rank's live rights, never the staging buffer, so a click shows only once the save
+    // round-trips and a new roster lands. `GuildControlPopupFrame_OnLoad` calls it before any rank
+    // is loaded (`FriendsFrame.lua:801`), when all thirteen are nil.
     g.set(
         "GuildControlGetRankFlags",
         lua.create_function(|lua, ()| {
@@ -842,9 +659,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GuildControlSetRankFlag(index, enabled) (`0x4d2070`) — toggle one bit in the staging
-    // buffer. The index is the checkbox's, 1..13, and RANK_RIGHT_BITS maps it to the bit. This is
-    // the mapping that a `1 << (index - 1)` would get wrong for nine of the thirteen.
+    // GuildControlSetRankFlag(index, enabled) (`0x4d2070`): stage one checkbox, 1 to 13.
     g.set(
         "GuildControlSetRankFlag",
         lua.create_function(|lua, (index, enabled): (i64, Value)| {
@@ -861,21 +676,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GuildControlSaveRank(name) (`0x4d20d0`) — flush the staged edits as one CMSG_GUILD_RANK.
-    // The argument is the rank's (possibly renamed) NAME, taken from the popup's edit box
-    // (`FriendsFrame.lua:839`); the rank it applies to is whichever GuildControlSetRank loaded.
-    // Converted to the wire's 0-based rank id here, once. A name that fails
-    // [`gated_rank_name`] — empty above all, which vmangos would otherwise persist as the rank's
-    // name guild-wide — is a silent no-op, before any packet.
-    //
-    // **The fold is a masked set-or-clear over a freshly re-read LIVE baseline** — verified: the
-    // binding does `or mask[k]` / `and ~mask[k]` per flag against the current rights, never a
-    // plain OR of a staged word. Two consequences, both of which a naive "send the staged word"
-    // implementation gets wrong:
-    //   · a plain OR could never turn a permission OFF, only on;
-    //   · bits outside the thirteen — notably `0x40`, which is tested NOWHERE in the image and is
-    //     a genuine gap rather than an always-set flag — must ride through untouched from whatever
-    //     the server last sent. Sending the staged word wholesale would clear them.
+    // GuildControlSaveRank(name) (`0x4d20d0`): the edit box's name (`FriendsFrame.lua:839`) and the
+    // staged flags as one `CMSG_GUILD_RANK` for the loaded rank. A name failing `gated_rank_name`
+    // is a silent no-op; vmangos stores an empty one (`Handlers/GuildHandler.cpp:586`). The fold
+    // sets or clears each staged bit over the freshly read live rights (`or mask[k]` /
+    // `and ~mask[k]`), so a right can be turned off and bits outside the thirteen, such as `0x40`,
+    // which the reference never tests, ride through as the server sent them.
     g.set(
         "GuildControlSaveRank",
         lua.create_function(|lua, name: String| {
@@ -884,7 +690,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             };
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
             let edit = model.guild_control.clone();
-            // `[0x84966c] >= [0xb73120]`: no rank loaded (the reference's -1, our 0) or one at or
+            // The reference's `[0x84966c] >= [0xb73120]`: no rank loaded (its -1, our 0) or one
             // past the rank count.
             if edit.rank >= 1 && (edit.rank as usize) <= model.guild.ranks.len() {
                 let mut rights = live_rights(&model, edit.rank);
@@ -905,10 +711,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GuildControlAddRank(name) (`0x4d2210`) — append a rank, behind the same silent name gate
-    // as SaveRank ([`gated_rank_name`]). The client refuses at
-    // `numRanks >= MAX_RANKS` **silently**, before any packet, which is why the reference's Add
-    // button greys itself at ten (`FriendsFrame.lua:887`) rather than relying on a refusal.
+    // GuildControlAddRank(name) (`0x4d2210`): the same name gate, and a silent refusal at
+    // `MAX_RANKS`, both before any packet.
     g.set(
         "GuildControlAddRank",
         lua.create_function(|lua, name: String| {
@@ -923,15 +727,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GuildControlDelRank() (`0x4d22e0`) — **reads no Lua argument at all**, and its packet
-    // (`0x233`) is body-less: the server deletes the LAST rank and infers which that is. The
-    // reference passes a name (`FriendsFrame.lua:895`) and the binding discards it, which is why
-    // the reference only offers the button when the selected rank IS the last (`:908`).
-    //
-    // Accepting-and-ignoring is the faithful shape. Taking the name and sending it would invent a
-    // wire field; refusing to compile against the reference's call would be worse.
-    //
-    // The client also refuses at `numRanks <= MIN_RANKS`, silently, before any packet.
+    // GuildControlDelRank() (`0x4d22e0`) reads no argument and sends an empty `0x233`: the server
+    // deletes the last rank. The FrameXML passes a name (`FriendsFrame.lua:895`), which is ignored.
+    // It refuses silently at `MIN_RANKS`, before any packet.
     g.set(
         "GuildControlDelRank",
         lua.create_function(|lua, _ignored: MultiValue| {
@@ -950,37 +748,24 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 mod tests {
     use super::*;
 
-    /// **`GetGuildInfo` splits three ways, not two** — `0x4c9330`: only an *unrecognised* token
-    /// raises; a **recognised** token that resolves to nothing answers `(nil, nil, 0)` like a
-    /// guildless player does.
-    ///
-    /// The distinction is not academic. Stock `PaperDollFrame_SetGuild` calls
-    /// `GetGuildInfo("player")` unguarded from `PaperDollFrame_OnShow`, so before this split
-    /// existed, opening the character window in the frames before the app pushed its first player
-    /// snapshot raised — found by putting the reference's own `PaperDollFrame.xml` on the chain
-    /// (decision 1751). `"player"` with no unit behind it is the whole test.
+    /// `0x4c9330`: only an unrecognised token raises; `"player"` with no unit behind it, the paper
+    /// doll's case at world entry, answers `nil, nil, 0`.
     #[test]
     fn a_recognised_but_unresolved_unit_answers_nils_and_only_an_unknown_token_raises() {
         let s = crate::script::UiScript::new().unwrap();
-        // Recognised, resolves to nothing — the paper doll's own case at world entry.
         let (name, rank, idx): (Option<String>, Option<String>, i64) = s
             .eval(r#"return GetGuildInfo("player")"#)
             .expect("a recognised token must not raise");
         assert_eq!((name, rank, idx), (None, None, 0));
-        // …and the third value is the NUMBER zero on that leg, not nil (`mov eax,3` on both).
+        // The third value is the number 0, not nil (`mov eax,3` on both legs).
         assert!(s
             .eval::<bool>(r#"local a,b,c = GetGuildInfo("party3") return c == 0"#)
             .unwrap());
-        // Unrecognised: the resolver's own raise, unchanged.
         assert!(s
             .eval::<i64>(r#"return GetGuildInfo("nosuchunit")"#)
             .is_err());
     }
 
-    /// The thirteen-bit table is the API contract, and its non-monotonicity is the trap: Promote
-    /// and Demote sit at indices 5 and 6 with bits ABOVE Invite and Remove at 7 and 8. A
-    /// `1 << (i - 1)` implementation passes indices 1-4 and fails the other nine, so this asserts
-    /// the whole table rather than a property of it.
     #[test]
     fn the_rank_right_table_is_not_a_shift() {
         assert_eq!(RANK_RIGHT_BITS.len(), 13, "one bit per GUILDCONTROL_OPTION");
@@ -1003,15 +788,8 @@ mod tests {
         }
     }
 
-    /// **`SaveRank` folds over the live baseline, so bits outside the thirteen survive.**
-    ///
-    /// `0x40` is tested nowhere in the 1.12 image — it is a genuine gap in the bit space, not an
-    /// always-set flag — and `SaveRank`'s fold neither sets nor clears it, so whatever the server
-    /// last sent rides through. An implementation that sent the staged word wholesale would clear
-    /// it (and any other unknown bit) on the first rank edit, silently, forever.
-    ///
-    /// The fold must also be able to turn a permission OFF, which a plain `OR` of a staged word
-    /// cannot.
+    /// `0x40`, vmangos's `GR_RIGHT_EMPTY`, is none of the thirteen and never tested by the
+    /// reference.
     #[test]
     fn saving_a_rank_preserves_bits_outside_the_thirteen_and_can_clear() {
         // Live: Invite (0x10) + Set MOTD (0x1000), plus the untouchable 0x40.
@@ -1043,7 +821,6 @@ mod tests {
         );
     }
 
-    /// A guild with `n` named ranks.
     fn guild_with_ranks(n: usize) -> crate::script::UiScript {
         let mut s = crate::script::UiScript::new().unwrap();
         s.set_guild(GuildState {
@@ -1059,10 +836,8 @@ mod tests {
         s
     }
 
-    /// **`0x4d20d0` refuses a bad name silently, before any packet** — NULL, empty, or a length
-    /// outside 1..16 UTF-16 code units (`0x65b250` counts units plus the terminator), and a rank
-    /// index at or past the rank count. vmangos persists whatever name arrives — an empty one
-    /// blanks the rank guild-wide — so this gate is the only thing standing in the way.
+    /// `0x4d20d0` refuses silently: a name outside 1 to 16 UTF-16 units (`0x65b250` counts them
+    /// plus the NUL), no rank loaded, or a rank past the count.
     #[test]
     fn saving_a_rank_refuses_what_the_reference_refuses() {
         let mut s = guild_with_ranks(5);
@@ -1093,8 +868,8 @@ mod tests {
             .unwrap();
         assert_eq!(saves(&mut s), 1);
 
-        // No rank loaded (a fresh popup — the selection persists across saves, as
-        // `[0x84966c]` does), or one past the ladder.
+        // No rank loaded in a fresh popup (the selection persists across saves, as `[0x84966c]`
+        // does), or one past the count.
         let mut fresh = guild_with_ranks(5);
         fresh.run(r#"GuildControlSaveRank("Officer")"#).unwrap();
         assert_eq!(saves(&mut fresh), 0, "nothing selected");
@@ -1103,8 +878,7 @@ mod tests {
         assert_eq!(saves(&mut s), 0, "rank index 5 >= 5 ranks");
     }
 
-    /// `0x4d2210` runs the same name gate as `SaveRank` — and nothing more: a whitespace name is
-    /// not empty to it.
+    /// `0x4d2210` runs the same name gate; a whitespace name passes it.
     #[test]
     fn adding_a_rank_runs_the_same_name_gate() {
         let mut s = guild_with_ranks(5);
@@ -1115,8 +889,7 @@ mod tests {
         assert_eq!(s.take_guild_requests().len(), 1);
     }
 
-    /// A 1-based index past the end, and the 0 the reference passes on every `GuildStatus_Update`
-    /// before it checks the selection, both have to answer `None` rather than panic.
+    /// `GuildStatus_Update` passes 0 before it tests the selection.
     #[test]
     fn member_lookup_is_one_based_and_tolerates_zero() {
         let roster = vec![
diff --git a/crates/benilla-ui/src/script/handler_prof.rs b/crates/benilla-ui/src/script/handler_prof.rs
index c2b74c6b..e124a6d1 100644
--- a/crates/benilla-ui/src/script/handler_prof.rs
+++ b/crates/benilla-ui/src/script/handler_prof.rs
@@ -1,42 +1,8 @@
-//! Per-handler cost attribution (`WOW_UI_HANDLERS=<secs>`) — *which* FrameXML handler is spending
-//! the frame. An `impl UiScript` block beside its concern, the `layout.rs` pattern.
-//!
-//! ## Why it exists (decision 1395)
-//!
-//! Three perf hunts in a row — 1383's autocast shine, 1385's cast bar, 1388's layout graph — each
-//! opened with the same question and each answered it **by hand**: read the shipped Lua, guess the
-//! busy handler, add a temporary print, re-run. `[ui-cost] tick=` is one aggregate over the whole
-//! `OnUpdate` sweep, so it can say *that* the sweep got expensive and never *who*. This is the
-//! missing decomposition, and it sits one layer below the one that landed beside it: 1389's HUD
-//! measures the frame's cost and latches its tail (`cpu`/`main` ms, the spike badge), which is
-//! **when** and **how much**; this is **who**, inside the UI's share of it.
-//!
-//! ## What it measures
-//!
-//! Every handler fired through [`super::event::fire`] — the single firing path for `OnUpdate`,
-//! `OnEvent`, `OnShow`/`OnHide`, `OnSizeChanged`, and the whole widget set (`OnClick`, `OnEnter`,
-//! `OnValueChanged`, …). Not just the tick's `OnUpdate` sweep, deliberately: an event storm (the
-//! combat log at 40 lines a second) costs frames the same way a hot `OnUpdate` does, and a `by
-//! script:` rollup on the report line is what tells the two apart at a glance.
-//!
-//! **Self and total, because handler firing nests.** A handler that calls `Show()` fires `OnShow`
-//! inside itself, and a handler that resizes something fires `OnSizeChanged`; charging the parent
-//! for its children would name the wrong frame, which is the one failure this instrument cannot
-//! afford. A stack of per-level child nanos gives both: `total` is what the call cost, `self` is
-//! what it cost *itself*. Sorted by `self`.
-//!
-//! Engine work a handler provokes synchronously **is** its self time, and that is the point — a
-//! geometry getter inside an `OnUpdate` calls `settle()`, which is a whole layout resolve
-//! (1388's opening finding: `OptionsScroll_Fit` does four per frame). That cost belongs to the
-//! handler that asked for it.
-//!
-//! ## What it costs when off
-//!
-//! One relaxed atomic load and a not-taken branch per handler fire ([`armed`]). The state lives in
-//! its own `app_data` slot rather than in [`super::Model`]: mlua keys `app_data` by `TypeId` with a
-//! **`RefCell` per entry** (`mlua-0.11.6`, `types/app_data.rs`), so the profiler's borrow can never
-//! collide with a model borrow held across a fire — a hazard that would otherwise be a panic in the
-//! hottest path in the client, armed only in the sessions where we are already chasing something.
+//! Per-handler cost attribution (`WOW_UI_HANDLERS=<secs>`): self and total time for every handler
+//! fired through [`super::event::fire`], since firing nests; engine work a handler provokes, such
+//! as a layout resolve, is its self time. Off, it costs a relaxed atomic load per fire ([`armed`]).
+//! Its state has its own `app_data` slot, not the model's: mlua keeps a `RefCell` per entry, so the
+//! profiler's borrow cannot collide with a model borrow held across a fire.
 
 use std::collections::HashMap;
 use std::sync::atomic::{AtomicBool, Ordering};
@@ -49,12 +15,8 @@ use super::UiScript;
 /// How many rows the periodic report prints before rolling the rest into a `… N more` line.
 const REPORT_ROWS: usize = 12;
 
-/// The fast gate: is *any* VM in this process profiling handlers?
-///
-/// Process-wide and not per-VM on purpose — the check runs per handler fire, and a per-VM answer
-/// would cost the `app_data` lookup this is here to avoid. A false positive (one VM armed, another
-/// not) costs the unarmed VM a hash lookup that finds `on == false`, which is the only case where
-/// the two answers differ and is not a case that ships.
+/// Whether any VM in the process profiles handlers: process-wide, so the per-fire check needs no
+/// `app_data` lookup.
 static ARMED: AtomicBool = AtomicBool::new(false);
 
 #[inline]
@@ -62,9 +24,7 @@ pub(super) fn armed() -> bool {
     ARMED.load(Ordering::Relaxed)
 }
 
-/// `WOW_UI_HANDLERS=<secs>` — the report period, read once. `WOW_UI_HANDLERS=3` reports every three
-/// seconds; anything unparseable or non-positive leaves the instrument off, the `[ui-cost]` /
-/// `[layout-prof]` posture.
+/// The report period from `WOW_UI_HANDLERS=<secs>`, read once; unparseable or non-positive is off.
 fn env_period() -> Option<f32> {
     static PERIOD: std::sync::OnceLock<Option<f32>> = std::sync::OnceLock::new();
     *PERIOD.get_or_init(|| {
@@ -83,37 +43,30 @@ struct Slot {
     self_ns: u64,
 }
 
-/// The profiler's state, one per VM, in its own `app_data` slot (see the module header).
-///
-/// Keyed by frame **id**, not by name: the name is a `String` clone and a two-map walk, so it is
-/// resolved once at report time rather than on every fire. A frame destroyed before the report
-/// reads back as `#<id>` — its cost still counted, which is what a churning pool of frames needs.
+/// The profiler's state, one per VM, keyed by frame id: names resolve at report time, and a frame
+/// destroyed before then still counts, as `#<id>`.
 #[derive(Default)]
 pub(crate) struct HandlerProf {
-    /// Is *this* VM recording? [`armed`] is the process-wide gate; this is the per-VM answer.
+    /// Whether this VM records; [`armed`] is the process-wide gate.
     on: bool,
-    /// Seconds between reports; `0.0` records forever and never prints (what a test wants).
+    /// Seconds between reports; `0.0` records and never prints.
     period: f32,
-    /// Wall seconds and frames since the last report — the window every printed rate divides by.
+    /// Wall seconds and frames since the last report, the divisor of every printed rate.
     window: f32,
     frames: u32,
-    /// Fires that had at least one nested fire inside them. Printed as the one-number answer to
-    /// "should I be reading `self` or `total` here?".
+    /// Fires that had a nested fire inside them.
     nested: u32,
-    /// Nanos already charged to *nested* fires, one entry per open fire. See the module header.
+    /// Nanos already charged to nested fires, one entry per open fire.
     stack: Vec<u64>,
     rows: HashMap<u32, Vec<Slot>>,
 }
 
-/// An open fire, closed by its `Drop` — the balance of the nesting stack is then a property of the
-/// borrow checker rather than of the call site remembering to close what it opened. It also holds
-/// under an unwind, which a hand-written enter/exit pair does not: a panic through a handler would
-/// otherwise leak a stack level and silently inflate every parent attribution after it.
+/// An open fire, closed by its `Drop`, so the nesting stack stays balanced through an unwind too.
 pub(super) struct Fire<'a> {
     lua: &'a Lua,
     id: u32,
     script: &'a str,
-    /// `None` while this VM is not recording — the whole guard is then a no-op.
+    /// `None` while this VM is not recording, which makes the guard a no-op.
     started: Option<Instant>,
 }
 
@@ -138,7 +91,7 @@ impl<'a> Fire<'a> {
 
 impl Drop for Fire<'_> {
     /// Charge `total` to `(id, script)`, `total - children` to its self time, and hand `total` up
-    /// to the enclosing fire as *its* child time.
+    /// to the enclosing fire as its child time.
     fn drop(&mut self) {
         let Some(started) = self.started else {
             return;
@@ -154,9 +107,7 @@ impl Drop for Fire<'_> {
         if children > 0 {
             prof.nested += 1;
         }
-        // `saturating_sub`: children are measured strictly inside this fire, so the subtraction
-        // cannot go negative by construction — but a construction argument is not a reason to hand
-        // a wrapped `u64` to a report if a clock ever disagrees.
+        // Children run inside this fire; saturating only matters if a clock disagrees.
         let self_ns = total.saturating_sub(children);
         let slots = prof.rows.entry(self.id).or_default();
         match slots.iter_mut().find(|s| s.script == self.script) {
@@ -165,8 +116,6 @@ impl Drop for Fire<'_> {
                 slot.total_ns += total;
                 slot.self_ns += self_ns;
             }
-            // The only allocation on this path, and only on a `(frame, script)` pair's first fire
-            // of the window — steady state is a linear scan over one frame's handful of slots.
             None => slots.push(Slot {
                 script: self.script.to_string(),
                 calls: 1,
@@ -180,23 +129,20 @@ impl Drop for Fire<'_> {
 /// One `(frame, script)` pair's cost over the profiler's current window.
 #[derive(Clone, Debug, PartialEq)]
 pub struct HandlerRow {
-    /// The frame's name, or `#<id>` for an anonymous or already-destroyed frame.
+    /// The frame's name, else where its handler was defined, else `#<id>`.
     pub frame: String,
     pub script: String,
     pub calls: u32,
-    /// Microseconds spent in this handler *excluding* handlers it fired — what to sort by.
+    /// Microseconds in this handler, excluding the handlers it fired.
     pub self_us: f64,
-    /// Microseconds spent in this handler *including* handlers it fired.
+    /// Microseconds in this handler, including the handlers it fired.
     pub total_us: f64,
 }
 
 impl UiScript {
-    /// Arm or disarm handler attribution for this VM, reporting every `period_secs` (`0.0` records
-    /// with no periodic report — read it with [`UiScript::handler_profile`] instead).
-    ///
-    /// Call it between ticks. An open [`Fire`] is inert either way (it decided once, at `open`),
-    /// but this clears the nesting stack, so a disarm from *inside* a handler would drop a level
-    /// its enclosing fires are still counting on.
+    /// Arm or disarm attribution for this VM, reporting every `period_secs` (`0.0`: no report, read
+    /// [`UiScript::handler_profile`]). Call it between ticks: it clears the nesting stack that open
+    /// fires count on.
     pub fn profile_handlers(&self, on: bool, period_secs: f32) {
         if on {
             ARMED.store(true, Ordering::Relaxed);
@@ -213,13 +159,9 @@ impl UiScript {
         prof.rows.clear();
     }
 
-    /// This VM's handler costs over the current window, heaviest **self** time first.
-    ///
-    /// Window totals, not per-frame rates — the frame count is [`UiScript::handler_profile_frames`],
-    /// so a caller that wants a rate divides by the number it also has to report.
+    /// This VM's handler costs over the current window as totals, heaviest self time first.
     pub fn handler_profile(&self) -> Vec<HandlerRow> {
-        // Snapshot under the profiler's borrow and then let it go: labelling reaches into the model
-        // *and* back into Lua, neither of which may be touched with a borrow of anything open.
+        // Snapshot, then release the borrow: labelling reaches into the model and back into Lua.
         let raw: Vec<(u32, String, u32, u64, u64)> = match self.lua.app_data_ref::<HandlerProf>() {
             Some(prof) => prof
                 .rows
@@ -257,15 +199,14 @@ impl UiScript {
         rows
     }
 
-    /// Frames ticked since the last report — [`UiScript::handler_profile`]'s denominator.
+    /// Frames ticked since the last report, [`UiScript::handler_profile`]'s denominator.
     pub fn handler_profile_frames(&self) -> u32 {
         self.lua
             .app_data_ref::<HandlerProf>()
             .map_or(0, |prof| prof.frames)
     }
 
-    /// Advance the profiler's window by one tick and print the report if it is due. Called at the
-    /// end of [`UiScript::tick`], so "a frame" means a ticked frame whatever else fired in it.
+    /// Count a ticked frame and print the report when due, at the end of [`UiScript::tick`].
     pub(super) fn report_handler_profile(&mut self, elapsed: f32) {
         if !armed() {
             return;
@@ -281,8 +222,7 @@ impl UiScript {
         if !due {
             return;
         }
-        // The rows first, so the model borrow the label walk takes is released before the profiler
-        // is borrowed mutably to reset it.
+        // The rows first: the label walk's model borrow must end before the profiler's mutable one.
         let rows = self.handler_profile();
         let mut prof = self
             .lua
@@ -297,14 +237,8 @@ impl UiScript {
 }
 
 impl UiScript {
-    /// A row's label: the frame's name, else **where the handler was written**, else `#<id>`.
-    ///
-    /// The definition site is not a nicety. `CreateFrame("Frame")` + `OnUpdate` with no name is
-    /// *the* addon timer idiom, so the anonymous case is not the rare one — it is exactly the set
-    /// of handlers an attribution table exists to catch, and `#4127` is not something anyone can
-    /// act on. `Function::info()` hands back the chunk and line, and every addon chunk is named
-    /// `@Interface\AddOns\<Folder>\<File>` (see [`super::addon_chunk_name`]), so the label reads as
-    /// the addon and the line to open.
+    /// A row's label: the frame's name, else the handler's `<file>:<line>` (an unnamed frame is the
+    /// common addon timer), else `#<id>`.
     fn handler_label(&self, id: u32, script: &str) -> String {
         let named = {
             let model = self.model_ref();
@@ -319,11 +253,9 @@ impl UiScript {
             .unwrap_or_else(|| format!("#{id}"))
     }
 
-    /// `<short_src>:<line>` for the function bound at `(id, script)`, or `None` if there is no such
-    /// binding or the VM cannot say (a C function, a stripped chunk).
+    /// `<short_src>:<line>` of the function bound at `(id, script)`, when the VM can say.
     fn handler_defined_at(&self, id: u32, script: &str) -> Option<String> {
-        // `raw_get` throughout: the registry's script tables are plain data, and a report must not
-        // be able to run a metamethod — that would re-enter Lua from inside an instrument.
+        // `raw_get`, so a report can never run a metamethod.
         let scripts: mlua::Table = self.lua.named_registry_value(super::REG_SCRIPTS).ok()?;
         let per: mlua::Table = scripts.raw_get(id).ok()?;
         let func: mlua::Function = per.raw_get(script).ok()?;
@@ -332,12 +264,8 @@ impl UiScript {
     }
 }
 
-/// The `[ui-handlers]` block: the window's shape, the per-script rollup, then the heaviest
-/// [`REPORT_ROWS`] handlers by self time with the remainder folded into one line.
-///
-/// Everything is **per frame**, because that is the unit every other cost in this client is quoted
-/// in (`[ui-cost] tick=`, the HUD's `cpu ms`) and the whole use of this instrument is comparing
-/// against those.
+/// The `[ui-handlers]` block, per frame like the client's other costs: the window, the per-script
+/// rollup, then the heaviest [`REPORT_ROWS`] handlers by self time and the rest in one line.
 fn print_report(rows: &[HandlerRow], window: f32, frames: u32, nested: u32) {
     let per_frame = f64::from(frames.max(1));
     let total_self: f64 = rows.iter().map(|r| r.self_us).sum();
@@ -379,11 +307,8 @@ fn print_report(rows: &[HandlerRow], window: f32, frames: u32, nested: u32) {
     }
 }
 
-/// Install the profiler's `app_data` slot, and arm it from the environment.
-///
-/// Unconditional (an empty `HandlerProf` is a few words) because mlua refuses to *insert* app data
-/// while any app data is borrowed — so the slot has to exist before the VM starts running, or
-/// [`UiScript::profile_handlers`] would carry a panic that only fires in the sessions using it.
+/// Install the profiler's `app_data` slot, armed from the environment. Unconditional: mlua refuses
+/// to insert app data while any is borrowed, so the slot must exist before the VM runs.
 pub(super) fn install(lua: &Lua) {
     let period = env_period();
     lua.set_app_data(HandlerProf {
diff --git a/crates/benilla-ui/src/script/inspect.rs b/crates/benilla-ui/src/script/inspect.rs
index 07e0cf44..8bdce4ec 100644
--- a/crates/benilla-ui/src/script/inspect.rs
+++ b/crates/benilla-ui/src/script/inspect.rs
@@ -1,38 +1,13 @@
-//! The **inspect** surface (decision 0631) — the intent queues behind the ref's
-//! `NotifyInspect`/`ClearInspectPlayer`, and the foreign-unit equipment view the unit-keyed
-//! `GetInventoryItem*` family reads through.
+//! The inspect bindings: `NotifyInspect` and `ClearInspectPlayer` queue intents, the app pushes
+//! the inspected unit's equipment ([`UiScript::set_inspect`]) for the unit-keyed
+//! `GetInventoryItem*` verbs, and `CanInspect` and `CheckInteractDistance` read a per-token
+//! distance map ([`UiScript::set_unit_reach`]).
 //!
-//! ## Why there is so little here
-//!
-//! Inspect is the thinnest of the item windows because **the data is already local**. A player's
-//! worn gear rides `PLAYER_VISIBLE_ITEM_<n>_0`, which is `UF_FLAG_PUBLIC` — the server streams it
-//! to every observer, and benilla already decodes it to render other players' equipment
-//! (`benilla::entities::equipment`). So the inspect window paints from a descriptor we hold, not
-//! from a reply we wait for; `SMSG_INSPECT` echoes the guid and nothing else, and no reference
-//! handler registers an inspect event. `InspectFrame_Show` calls `NotifyInspect(unit)` and
-//! `ShowUIPanel` in the same breath, and `InspectPaperDollFrame_OnShow` reads all 19 slots
-//! immediately (`Blizzard_InspectUI.lua:6-13`, `InspectPaperDollFrame.lua:57-79`).
-//!
-//! ## The seam
-//!
-//! - **Intents:** `NotifyInspect(unit)` queues the token (the app resolves it → player guid →
-//!   `CMSG_INSPECT`, which server-side also sets our selection); `ClearInspectPlayer()` flags the
-//!   drop, the ref's own `InspectFrame_OnHide` call.
-//! - **Push:** the app pushes an [`InspectView`] each frame the inspected unit's resolved slot
-//!   views change ([`UiScript::set_inspect`]), or `None` when nothing is being inspected.
-//! - **Read:** *no new item getters.* The reference's own `GetInventoryItemTexture(unit, slot)`
-//!   family is already unit-keyed; `super::char_stats::player_inv_slot` routes `"player"` to the
-//!   self feed and the inspected token here.
-//! - **Range:** the two verified d² predicates, `CanInspect` and `CheckInteractDistance`, over one
-//!   app-fed per-token distance map ([`UiScript::set_unit_reach`]) — the VM holds no positions. The
-//!   map itself is unit-general (every held unit, creature included) and is fed by
-//!   `benilla::ui_unit`; only `CanInspect`'s players-only leg is inspect's, and it rides in the
-//!   entry.
-//!
-//! The view is keyed by **unit token**, not guid — the ref stores `InspectFrame.unit` as a token
-//! and re-reads it on `PLAYER_TARGET_CHANGED`, so an inspect window follows a re-target exactly as
-//! the real one does. The `guid` rides along only so the app can tell "same token, different
-//! player" apart when it rebuilds.
+//! Worn gear is public descriptor state (`PLAYER_VISIBLE_ITEM_<n>_0`), so the window paints from
+//! what the client holds: `SMSG_INSPECT` echoes only the guid, `InspectFrame_Show` calls
+//! `NotifyInspect` and `ShowUIPanel` together (`Blizzard_InspectUI.lua:6-13`), and the paper doll
+//! reads all 19 slots on show (`InspectPaperDollFrame.lua:57-79`). The view is keyed by unit token,
+//! as the reference keeps `InspectFrame.unit`, so it follows a re-target.
 
 use std::cmp::Ordering;
 use std::collections::HashMap;
@@ -42,117 +17,71 @@ use mlua::{Lua, Value};
 use super::char_stats::InventorySlots;
 use super::Model;
 
-/// The `CheckInteractDistance` threshold table — `{10², 11.1111², 10², 30²}` for the live API's
-/// `type ∈ 1..4`, read straight out of the binary (`0x48ba00`, built from the static `.rdata` at
-/// `0x804498`/`0x804490`/`0x80448c`/`0x8044a4`). Type 1 is the *inspect* row's distance, and shares
-/// its 100.0 with [`super::inspect`]'s own `CanInspect` threshold.
+/// `CheckInteractDistance`'s squared thresholds for types 1..=4, `{10², 11.1111², 10², 30²}`
+/// (`0x48ba00`, from the `.rdata` at `0x804498`, `0x804490`, `0x80448c`, `0x8044a4`).
 pub const INTERACT_DIST_SQ: [f64; 4] = [100.0, 123.45678, 100.0, 900.0];
 
-/// The `CanInspect` threshold, **squared** — `DAT_00b4d918`, which the client's own writer builds
-/// by squaring the static `.rdata` `10.0` at `0x804498` (`0x48a1b0`). vmangos enforces the same 10
-/// yards as `INSPECT_DISTANCE` (`ObjectDefines.h:26`), so client and server agree exactly.
+/// `CanInspect`'s threshold squared (`0xb4d918`, the `.rdata` 10.0 at `0x804498` squared by
+/// `0x48a1b0`); vmangos checks the same 10 yards (`INSPECT_DISTANCE`, `ObjectDefines.h:26`).
 pub const CAN_INSPECT_DIST_SQ: f64 = 100.0;
 
-/// What the app resolved about one unit token's unit this frame — the input both range predicates
-/// read ([`UiScript::set_unit_reach`]).
-///
-/// An entry exists **iff the token resolved to a live unit object**, which is the distinction the
-/// reference's own bindings turn on: `0x515940` maps the token to a GUID and then asks the object
-/// manager for it, and a NULL there is answered `nil` without any distance being computed. A party
-/// member outside the local area is exactly that case — `0x4e81a0` reads their GUID straight out of
-/// the roster array, so the GUID is non-zero and the object lookup misses silently.
+/// One token's unit this frame, as the two range verbs read it. An entry exists only when the
+/// token resolved to a live unit object: the reference maps the token to a GUID (`0x515940`) and
+/// answers nil when the object manager has no such unit, as for a party member out of the area,
+/// whose GUID comes from the roster (`0x4e81a0`).
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct UnitReach {
-    /// Squared distance from the player, in the binary's own accumulation shape.
+    /// Squared distance from the player.
     pub dist_sq: f64,
-    /// The unit passes the two NON-distance refusals vmangos makes for an inspect
-    /// (`sObjectMgr.GetPlayer` and `!IsValidAttackTarget`, `MiscHandler.cpp:945-956`) — consulted
-    /// by `CanInspect` alone. `CheckInteractDistance` is a pure distance test in the binary and
-    /// must not read this, or following an enemy player would gray a row the reference leaves live.
-    ///
-    /// `sObjectMgr.GetPlayer` is the whole is-it-a-player leg, and it lives **here** rather than in
-    /// the map's membership: the map is fed for every held unit, creature included (B304), so a
-    /// boar 3 yards away is `inspectable: false` while still answering `CheckInteractDistance`
-    /// truthfully.
+    /// A player, and not a valid attack target: vmangos's inspect refusals besides distance
+    /// (`MiscHandler.cpp:945-956`). Only `CanInspect` reads it: `CheckInteractDistance` is a pure
+    /// distance test, so a creature or an enemy player still answers it.
     pub inspectable: bool,
 }
 
-/// What the app has resolved for the unit currently being inspected (decision 0631).
+/// What the app has resolved for the unit currently being inspected.
 #[derive(Clone, Debug, PartialEq)]
 pub struct InspectView {
-    /// The unit token the frame is inspecting — the ref's `InspectFrame.unit` (`"target"`,
-    /// `"party3"`, …). The inventory router matches a binding's `unit` argument against this.
+    /// The inspected unit token, the reference's `InspectFrame.unit`; the inventory verbs match
+    /// their `unit` argument against it.
     pub unit: String,
-    /// The player guid the token resolved to when these slots were read.
+    /// The player the token resolved to, so the app can tell a new player behind the same token.
     pub guid: u64,
-    /// The inspected player's equipment, indexed by live-API inventory slot id exactly like the
-    /// self feed (1..=19). Index 0 (ammo) and 20..=23 (bags) stay `None` — a foreign player
-    /// exposes neither, and the ref's inspect paper doll has no button for them.
+    /// Equipment by inventory slot id 1..=19, like the self feed; ammo (0) and bags (20..=23) stay
+    /// `None`, since another player's are not visible.
     pub slots: InventorySlots,
 }
 
 impl super::UiScript {
-    /// Push the per-token **unit reach** map: unit token → squared distance from the player to
-    /// that unit, for **every** token the app resolved to a live unit object this frame. Nothing
-    /// to do with `UNIT_FIELD_COMBATREACH` — this is where each token's unit *is*, not how far it
-    /// swings.
-    ///
-    /// One app-fed number serves both range predicates, because the binary uses the same d² for
-    /// both: `CanInspect` compares it against `100.0`, and `CheckInteractDistance(unit, type)`
-    /// against [`INTERACT_DIST_SQ`]`[type-1]`.
-    ///
-    /// **The map is unit-general, not a players-only or popup-only one.** It was both, and being
-    /// both was report B304: `CheckInteractDistance` is a pure distance test over any unit token in
-    /// the binary, so a creature `"target"` that never entered the map made Quiver's 30-yard rung
-    /// answer a constant for every mob at every distance. The one typemask that *is* real —
-    /// inspect's — rides in the entry as [`UnitReach::inspectable`], never at the token.
-    ///
-    /// It lives here rather than on [`super::UnitState`] because a distance changes **every
-    /// frame**: the unit snapshots are pushed on diff (1439) and fire `UNIT_*` transitions when
-    /// they move, so folding a moving number into them would re-push and re-fire every token every
-    /// frame. This map is re-pushed wholesale instead, and nothing keys an event off it.
-    ///
-    /// A token absent from the map is a token the object manager holds **no unit for**, and both
-    /// predicates answer `nil` there — the reference's own null-object arm
-    /// (`0x48babe test ecx,ecx; je` → `lua_pushnil`). It used to read as *in range*, on the
-    /// reasoning that missing data must not gray a row; the binary says the opposite, and that
-    /// default was report B316 — every distance row lit up for exactly the party member who was
-    /// too far away to have an object at all.
-    ///
-    /// **Keys are lowercase** — the resolver folds case (`_strnicmp`, 1247), so the lookup does
-    /// too, exactly as `Model::unit` does for the snapshots.
+    /// Push the squared distance of every token that resolved to a live unit this frame, creature
+    /// included; both range verbs read the same d². A token absent from the map answers nil from
+    /// both, the reference's null-object arm (`0x48babe`). It changes every frame, so it stays off
+    /// [`super::UnitState`], whose diffs fire `UNIT_*` events. Keys are lowercase: the token
+    /// resolver folds case (`_strnicmp`).
     pub fn set_unit_reach(&mut self, reach: HashMap<String, UnitReach>) {
         self.model_mut().unit_reach = reach;
     }
 
-    /// Push (or clear, with `None`) the inspected unit's resolved equipment view. The app calls
-    /// this whenever the view changes; it fires no event of its own — the app fires
-    /// `UNIT_INVENTORY_CHANGED` for the inspected token, which is the signal the ref's
-    /// `InspectPaperDollItemSlotButton_OnEvent` actually listens for.
+    /// Push (or clear, with `None`) the inspected unit's equipment. It fires nothing: the app fires
+    /// `UNIT_INVENTORY_CHANGED` for the token, which the stock slot buttons listen for.
     pub fn set_inspect(&mut self, view: Option<InspectView>) {
         self.model_mut().inspect = view;
     }
 
-    /// Drain the unit tokens `NotifyInspect` queued — the app resolves each to a player guid and
-    /// sends `CMSG_INSPECT`.
+    /// Drain the tokens `NotifyInspect` queued; the app sends `CMSG_INSPECT` for each, which also
+    /// sets the server-side selection (`MiscHandler.cpp:945`).
     pub fn take_inspect_notifies(&mut self) -> Vec<String> {
         std::mem::take(&mut self.model_mut().inspect_notifies)
     }
 
-    /// Whether `ClearInspectPlayer` was called since the last drain (and clear the flag) — the
-    /// app drops its inspect target, which stops the per-frame slot resolve.
+    /// Whether `ClearInspectPlayer` was called since the last drain; the app drops its target.
     pub fn take_inspect_clear(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().inspect_clear)
     }
 }
 
-/// What the app resolved for `token`, or `None` when it resolved to no live unit at all — the
-/// reference's NULL-object arm, which both predicates answer `nil` to.
-///
-/// Case-folded on the way in, the same shape `Model::unit` uses for the snapshot map: both
-/// predicates reach the unit through the one resolver `0x515970`, whose nine compares are
-/// `_strnicmp` (1247), so `CheckInteractDistance("Target", 4)` is the same question as
-/// `CheckInteractDistance("target", 4)`.
+/// The reach pushed for `token`, case-folded: both verbs resolve the token through `0x515970`,
+/// whose compares are `_strnicmp`.
 fn reach(lua: &Lua, token: &Option<String>) -> Option<UnitReach> {
     let token = token.as_deref()?;
     let model = lua.app_data_ref::<Model>().expect("model app_data");
@@ -166,17 +95,10 @@ fn reach(lua: &Lua, token: &Option<String>) -> Option<UnitReach> {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // CanInspect(unit) → 1/nil: the gate the ref's `InspectFrame_Show` opens on
-    // (`Blizzard_InspectUI.lua:8`). The real client's `0x48a1b0` is a d² range test: **out of range
-    // iff `threshold < d²`**, where
-    // `threshold = DAT_00b4d918 = 100.0` (10 yards, the same number vmangos enforces as
-    // `INSPECT_DISTANCE`). The operator is theirs too: `test ah,0x41; jne` skips the out-of-range
-    // action on `C0|C3` — Less, Equal, *or unordered* — so the three in-range arms below are that
-    // mask spelled out, and a NaN distance reads as in RANGE, not out. The is-a-player and
-    // not-attackable legs are resolved app-side and ride IN the entry
-    // ([`UnitReach::inspectable`]) — not by keeping the token out of the map, which is the map's
-    // own law (a creature `"target"` is in it, at its real distance, and is not inspectable).
-    // Decision 0631.
+    // CanInspect(unit) → 1/nil (`0x48a1b0`), the gate of `InspectFrame_Show`
+    // (`Blizzard_InspectUI.lua:8`): in range unless `100.0 < d²`, and `test ah,0x41; jne` counts an
+    // unordered compare as in range, so a NaN distance passes. The player and attackability legs
+    // ride in [`UnitReach::inspectable`].
     g.set(
         "CanInspect",
         lua.create_function(|lua, unit: Option<String>| {
@@ -188,33 +110,19 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                             Some(Ordering::Less | Ordering::Equal) | None
                         )
                 }
-                // No live unit object: the binary reaches its `lua_pushnil` tail through
-                // `0x4944a0`'s null-`this` guard rather than an early return, but the value it
-                // pushes is the same one — nothing to inspect.
+                // No live unit: nil, through `0x4944a0`'s null-`this` guard.
                 None => false,
             };
             Ok(if ok { Value::Integer(1) } else { Value::Nil })
         })?,
     )?;
 
-    // CheckInteractDistance(unit, type) → 1/nil, `type ∈ 1..4` (`0x48ba00`): **in range iff
-    // `d² < table[type-1]`** —
-    // note the STRICT `<` here against `CanInspect`'s non-strict gate above, which is the
-    // binary's own asymmetry (`test ah,0x5; jp` takes the out path unless `d² < thr` ordered), not
-    // a transcription slip. The UnitPopup rows' `dist` field indexes it.
-    //
-    // The three degenerate arms are the binary's too, and
-    // they are three DIFFERENT answers rather than one permissive default:
-    //
-    // - **No live unit for the token** → `nil` (`0x48babe test ecx,ecx; je`). This is the party
-    //   member outside the local area, and answering `1` here was report B316.
-    // - **`type` numeric but outside 1..4** → `nil`. The compare is UNSIGNED on `trunc(type) − 1`
-    //   (`0x48bac5 cmp esi,0x4; jae`), so `0`, negatives and `≥ 5` all take it, and a fractional
-    //   type truncates toward zero first (`__ftol`: `1.9 → 1`, `0.5 → 0 → nil`).
-    // - **`type` missing or not a number** → a **script error**, not `nil`
-    //   (`0x48bb48 call luaL_error`, which longjmps and never returns). Same for a non-string
-    //   unit. A caller that passes neither argument is not asking a question the reference
-    //   answers.
+    // CheckInteractDistance(unit, type) → 1/nil (`0x48ba00`): in range only when
+    // `d² < table[type-1]`, strictly, unlike `CanInspect` (`test ah,0x5; jp`). A token with no unit
+    // answers nil (`0x48babe`), as does a `type` outside 1..=4 once truncated toward zero, the
+    // compare being unsigned (`0x48bac5`); a missing or non-number `type` raises (`0x48bb48`).
+    // The reference also raises for a missing unit (`0x48ba18`) or an unknown token (`0x515c14`),
+    // where this answers nil.
     g.set(
         "CheckInteractDistance",
         lua.create_function(|lua, (unit, kind): (Option<String>, Option<f64>)| {
@@ -223,8 +131,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     "Usage: CheckInteractDistance(\"unit\", distIndex)".into(),
                 ));
             };
-            // `__ftol` chops toward zero; the index is then compared UNSIGNED, so anything that
-            // is not exactly 1..=4 falls out of the table lookup and answers nil.
             let thr = usize::try_from(kind.trunc() as i64)
                 .ok()
                 .and_then(|k| k.checked_sub(1))
@@ -237,9 +143,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // NotifyInspect(unit) — the ref's request verb (`Blizzard_InspectUI.lua:9`). Queues the token;
-    // the app resolves it → guid → CMSG_INSPECT. The window does NOT wait on the reply (see the
-    // module doc), so this is fire-and-forget by design, not an unfinished handshake.
+    // NotifyInspect(unit) (`Blizzard_InspectUI.lua:9`): fire-and-forget, as nothing waits on the
+    // reply.
     g.set(
         "NotifyInspect",
         lua.create_function(|lua, unit: String| {
@@ -251,8 +156,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ClearInspectPlayer() — the ref calls it from `InspectFrame_OnHide` (l.58) to drop the
-    // engine's inspected-player state. Ours stops the app's per-frame slot resolve.
+    // ClearInspectPlayer(): called from `InspectFrame_OnHide` (`Blizzard_InspectUI.lua:58`).
     g.set(
         "ClearInspectPlayer",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/instance.rs b/crates/benilla-ui/src/script/instance.rs
index bcea5d53..0b19fa1f 100644
--- a/crates/benilla-ui/src/script/instance.rs
+++ b/crates/benilla-ui/src/script/instance.rs
@@ -1,39 +1,26 @@
-//! The instance-lockout **Era API surface** (decision 1748) — three globals, no snapshot struct.
-//!
-//! `IsInInstance`, `CanShowResetInstances` and `ResetInstances` are all engine bindings in 1.12
-//! (`reference/1.12-globals.tsv` lists the three as `function`/`engine`), and between them they
-//! are the whole Lua side of the lockout family: everything else it does arrives as a
-//! `CHAT_MSG_SYSTEM` line the client composes itself, with no event and no getter.
-//!
-//! Both readers answer off state the app pushes, because both are `Map.dbc` questions and the DBC
-//! is the app's to read — the same split [`super::party::SavedInstanceInfo`] already makes.
-//!
-//! **`IsInInstance` returns a pair**: `1`/`nil` for "is this an instance at all", and the type as a
-//! string. The four strings are the reference's own table at `0x83de58`, indexed by
-//! `Map.dbc`'s `InstanceType` behind a `< 4` guard: `none` (0), `party` (1), `raid` (2),
-//! `pvp` (3) — `IsInInstance 0x48a750`.
+//! `IsInInstance`, `CanShowResetInstances` and `ResetInstances`, the whole Lua side of instance
+//! lockouts; the rest arrives as `CHAT_MSG_SYSTEM` lines. The readers answer off state the app
+//! pushes from `Map.dbc`.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// `Map.dbc`'s `InstanceType` → the word `IsInInstance()` returns for it — the reference's
-/// `0x83de58` string table, with its own out-of-range fallback (`cmp esi,4; jae` → `"none"`).
+/// `IsInInstance()`'s type word for a `Map.dbc` `InstanceType`: the reference's table at
+/// `0x83de58`, and `"none"` from 4 up.
 pub fn instance_type_name(instance_type: u32) -> &'static str {
     match instance_type {
         1 => "party",
         2 => "raid",
         3 => "pvp",
-        // 0 and anything the table cannot index.
         _ => "none",
     }
 }
 
 impl super::UiScript {
-    /// Push the current map's `Map.dbc` `InstanceType` — `IsInInstance()`'s whole input.
-    /// `None` = the map id has no DBC row, which the reference reaches by null-checking the record
-    /// pointer; it then returns without pushing anything at all (a real 1.12 stack bug). We answer
-    /// `nil, "none"` there, which is what every caller of it actually means to read.
+    /// Push the current map's `Map.dbc` `InstanceType`, `None` for a map with no row. Deviation:
+    /// `IsInInstance()` then answers `nil, "none"`, because the reference returns two results
+    /// without pushing either (`0x48a7a9`), a stack bug.
     pub fn set_instance_type(&mut self, instance_type: Option<u32>) {
         let mut model = self.model_mut();
         if model.instance_type != instance_type {
@@ -41,8 +28,8 @@ impl super::UiScript {
         }
     }
 
-    /// Push `CanShowResetInstances()`'s answer — the app owns every term of it (the ownership
-    /// latch, the last dungeon, its age, and the map we are standing on).
+    /// Push `CanShowResetInstances()`'s answer; the app owns its terms (the ownership latch, the
+    /// last dungeon, its age and the current map).
     pub fn set_can_reset_instances(&mut self, can: bool) {
         let mut model = self.model_mut();
         if model.can_reset_instances != can {
@@ -50,21 +37,17 @@ impl super::UiScript {
         }
     }
 
-    /// Drain the `ResetInstances()` calls queued since the last drain — each one is a
-    /// `CMSG_RESET_INSTANCES`. A count, like [`super::UiScript::take_binder_confirms`]: the intent
-    /// has no payload of its own.
+    /// `ResetInstances()` calls since the last drain, each a `CMSG_RESET_INSTANCES`.
     pub fn take_reset_instance_asks(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().reset_instance_asks)
     }
 }
 
-/// Register the three lockout globals ([`super::binder`]'s style).
+/// Register the three lockout globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // IsInInstance() → inInstance, instanceType. The first return is the NUMBER 1 rather than a
-    // boolean because the reference pushes 1.0 (`push 0x3ff00000; push 0` = the double 1.0), and
-    // 1.12 UI code compares it numerically.
+    // `IsInInstance()` (`0x48a750`): 1 if `InstanceType` is nonzero, else nil; then the type word.
     g.set(
         "IsInInstance",
         lua.create_function(|lua, ()| {
@@ -84,8 +67,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CanShowResetInstances() — UnitPopup's gate on the SELF menu's "Reset all instances" row.
-    // 1.0/nil for the same reason as above.
+    // `CanShowResetInstances()`: 1 or nil, the gate on the SELF menu's reset row.
     g.set(
         "CanShowResetInstances",
         lua.create_function(|lua, ()| {
@@ -98,7 +80,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ResetInstances() — the CONFIRM_RESET_INSTANCES dialog's Yes.
+    // `ResetInstances()`: the `CONFIRM_RESET_INSTANCES` dialog's Yes.
     g.set(
         "ResetInstances",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/item_stats.rs b/crates/benilla-ui/src/script/item_stats.rs
index 92e284ec..cbd3bc73 100644
--- a/crates/benilla-ui/src/script/item_stats.rs
+++ b/crates/benilla-ui/src/script/item_stats.rs
@@ -1,21 +1,9 @@
-//! The **shared item-template store** — one `item id → ItemTemplateView` table every item hover
-//! renders through (decision 0274 P1). In the real client every item tooltip is the same C++
-//! renderer (`0x52b650`, behind 8 of the 9 `Set*Item` bindings) over the same item-template cache;
-//! benilla mirrors that with
-//! one engine store the app feeds from its ask-once `ITEM_QUERY` template cache, and one engine
-//! renderer ([`super::tooltip_item`]).
+//! The shared item-template store every item tooltip renders through, as the reference's one
+//! renderer (`0x52b650`, behind 8 of the 9 `Set*Item` bindings) reads one template cache.
 //!
-//! Fill flow: the app **pushes** every item template the moment it lands in its cache
-//! ([`super::UiScript::set_item_template`]) — arrival-driven, so a first hover of an item whose
-//! name is already on screen always hits. A renderer read of an id the app never resolved
-//! additionally records the id ([`super::UiScript::take_item_stat_asks`] drains them), which
-//! makes the app send `CMSG_ITEM_QUERY` and push when the answer arrives — the real client's
-//! uncached-item early-out (cleared tooltip + query; the hover's re-enter loop repaints on
-//! arrival).
-//!
-//! The view carries the template's tooltip-relevant fields plus the strings only the app can
-//! resolve (skill/faction names from the DBC catalogs, trigger-spell display text) — the engine
-//! renders lines, it never reads DBCs.
+//! The app pushes each template as it lands; a read of an unknown id records an ask that the app
+//! turns into `CMSG_ITEM_QUERY`, the reference's uncached-item early-out. The app resolves every
+//! DBC string, as the engine reads no DBCs.
 
 use std::collections::HashMap;
 
@@ -23,176 +11,112 @@ use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// An item template's tooltip view (decision 0274 P1) — the fields the line law consumes, in
-/// wire terms (vmangos `SMSG_ITEM_QUERY_SINGLE_RESPONSE`), plus app-resolved display strings.
+/// An item template's tooltip view: the `SMSG_ITEM_QUERY_SINGLE_RESPONSE` fields the tooltip reads,
+/// plus app-resolved display strings.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct ItemTemplateView {
-    /// The name line (quality-colored).
     pub name: String,
     pub quality: u32,
-    /// Item class/subclass (the slot line's right column) + the equip slot (its left).
     pub class: u32,
     pub subclass: u32,
     pub inventory_type: u32,
-    /// `GetItemInfo`'s `itemType`: what [`Self::class`] is **called** — "Weapon", "Container",
-    /// "Trade Goods" — app-resolved from `ItemClass.dbc` (byte-verified: `0x48e070` pushes
-    /// `[classRow + 4*locale + 0xc]`). `None` for a class with no row, which the reference
-    /// renders as the empty string.
+    /// `GetItemInfo`'s `itemType`, the `ItemClass.dbc` name (`0x48e070`); `None` answers `""`.
     pub item_type: Option<String>,
-    /// `GetItemInfo`'s `itemSubType`: what `(class, subclass)` is **called** — app-resolved from
-    /// `ItemSubClass.dbc`, **VerboseName first with a DisplayName fallback**
-    /// ([`benilla_formats::ItemSubClassCatalog::name`]), which is the binding's own two-step at
-    /// `0x48e311`: read `[row + 4*locale + 0x4c]` and use it unless its first byte is 0, else
-    /// `[row + 4*locale + 0x28]`.
-    ///
-    /// **This is a different spelling from the tooltip's type cell**, which reads `+0x28`
-    /// (DisplayName) only — a one-handed sword is "One-Handed Swords" here and "Sword" there.
+    /// `GetItemInfo`'s `itemSubType`, "One-Handed Swords": `ItemSubClass.dbc`'s VerboseName
+    /// (`+0x4c`), or its DisplayName (`+0x28`) when that is empty (`0x48e311`).
     pub item_sub_type: Option<String>,
-    /// What `(class, subclass)` is called on the TOOLTIP's own type cell — `ItemSubClass.dbc`'s
-    /// **DisplayName** alone (`row + 4*locale + 0x28`, column 10: the read the builder makes at
-    /// `0x52c0xx` off the `0xc0db90` row cache), which is the SINGULAR spelling: "Sword", not
-    /// [`Self::item_sub_type`]'s "One-Handed Swords". App-resolved, because the engine reads no
-    /// DBCs — and it is the same string the bag line's `CONTAINER_SLOTS` second hole takes.
-    ///
-    /// This used to be a hand-typed `(class, subclass) → &str` table in the renderer, which is
-    /// the shape decision 2080 caught one file over: a stale copy of data the catalog already
-    /// held, missing every container family outright.
+    /// The tooltip's type cell and the bag line's `CONTAINER_SLOTS` name: `ItemSubClass.dbc`'s
+    /// DisplayName alone (`+0x28`, off the `0xc0db90` row cache), the singular "Sword".
     pub sub_class_display: Option<String>,
-    /// The alternate subclass whose proficiency also permits use (ItemSubClass.dbc
-    /// prerequisite/postrequisite, app-resolved with the builder's sentinel walk: prerequisite
-    /// wins, postrequisite only when prerequisite is −1). A weapon missing its own mask bit but
-    /// holding the alternate's reds the SLOT cell instead of the type cell.
+    /// The alternate subclass whose proficiency also permits use: `ItemSubClass.dbc`'s
+    /// prerequisite, or its postrequisite when the prerequisite is -1. A weapon with only the
+    /// alternate's bit reds the slot cell, not the type cell.
     pub proficiency_alt: Option<u32>,
-    /// ItemSubClass displayFlags bit 0 (app-resolved): the type cell never prints — the
-    /// "Miscellaneous" family (rings, trinkets, shirts, consumables, recipes).
+    /// `ItemSubClass.dbc` displayFlags bit 0: the type cell never prints (rings, trinkets, …).
     pub hide_subclass: bool,
-    /// Template flags — bit `0x2` = conjured ("Conjured Item").
+    /// Template flags; `0x2` prints "Conjured Item".
     pub flags: u32,
-    /// Bonding: 1 = binds on pickup, 2 = on equip, 3 = on use, 4/5 = quest item.
+    /// 1 binds on pickup, 2 on equip, 3 on use, 4 and 5 quest item.
     pub bonding: u32,
-    /// `MaxCount` — 1 = "Unique", N > 1 = "Unique (N)", 0 = no line. **Not the stack size**; see
-    /// [`Self::stackable`].
+    /// `MaxCount`: 1 prints "Unique", N > 1 "Unique (N)"; not the stack size.
     pub max_count: u32,
-    /// `Stackable` — the biggest stack one slot can hold (1 = doesn't stack). `GetItemInfo`'s
-    /// `itemStackCount`, read from the cache record's `+0x60` at `0x48e28b` — the dword *after*
-    /// `MaxCount` at `+0x5c`. Linen Cloth is `maxcount 0, stackable 20`, so the two are not
-    /// interchangeable in either direction.
+    /// `Stackable`, `GetItemInfo`'s `itemStackCount` (`+0x60`, `0x48e28b`); `MaxCount` is `+0x5c`.
     pub stackable: u32,
-    /// Nonzero = "This Item Begins a Quest".
     pub start_quest: u32,
-    /// Container size — "N Slot Bag".
     pub container_slots: u32,
-    /// Stat mods `(type, value)` in wire order (types: 0 mana, 1 health, 3 agi, 4 str, 5 int,
-    /// 6 spi, 7 stam — the `ITEM_MOD_*` GlobalStrings family).
+    /// `(ItemModType, value)` in wire order, the `ITEM_MOD_*` lines.
     pub stats: Vec<(u32, i32)>,
-    /// Damage blocks `(min, max, school)` in wire order; school 0 physical, 1..6 =
-    /// Holy/Fire/Nature/Frost/Shadow/Arcane.
+    /// `(min, max, school)` in wire order.
     pub damages: Vec<(f32, f32, u32)>,
     pub delay_ms: u32,
     pub armor: u32,
     pub block: u32,
-    /// Holy..Arcane (armor is its own field), the "+N X Resistance" lines.
+    /// Holy to Arcane.
     pub resistances: [i32; 6],
-    /// "Durability N / N" (a template hover shows full).
     pub max_durability: u32,
-    /// "Requires Level N" — printed only for N > 1 (the real builder's `0x52d2cf` gate); red
-    /// when the player is lower.
+    /// "Requires Level N", printed only for N > 1 (`0x52d2cf`).
     pub required_level: u32,
-    /// Class/race masks; `<= 0` = everyone (no line). Red when the player's bit is absent.
+    /// Class and race masks: `<= 0` prints no line, and a line missing the player's bit is red.
     pub allowable_class: i32,
     pub allowable_race: i32,
-    /// Skill requirement: the SkillLine id + rank, with the display name app-resolved
-    /// (`SkillLine.dbc`). `required_skill_name = None` = no skill line.
+    /// `SkillLine.dbc` id, with its rank and app-resolved name; a `None` name prints no line.
     pub required_skill: u32,
     pub required_skill_rank: u32,
     pub required_skill_name: Option<String>,
-    /// Spell requirement (nonzero = "Requires <name>") — red when the spellbook doesn't know it.
     pub required_spell: u32,
     pub required_spell_name: Option<String>,
-    /// `RequiredHonorRank` — no tooltip line in 1.12, but the item-usable gate (`0x5ea930`)
-    /// compares it against the player's highest honor rank; the merchant list reds on it.
+    /// No tooltip line in 1.12; only the usable gate (`0x5ea930`) reads it.
     pub required_honor_rank: u32,
-    /// `RequiredCityRank` — usable-gate only, like the honor rank. Vanilla data ships no nonzero
-    /// value and vmangos never writes the `PVP_MEDALS` bits the client would test, so a nonzero
-    /// requirement can only fail (see [`item_usable`]).
+    /// Usable gate only; nonzero always fails, as the `PVP_MEDALS` bits it tests are never set.
     pub required_city_rank: u32,
-    /// Reputation requirement, app-resolved to "Requires <Faction> - <Standing>"; the raw
-    /// faction id + rank ride along for the red check against [`PlayerReqState::rep_ranks`].
+    /// "Requires <Faction> - <Standing>", app-resolved; the raw faction and rank drive its red.
     pub required_rep_line: Option<String>,
     pub required_rep_faction: u32,
     pub required_rep_rank: u32,
-    /// Trigger-spell lines `(trigger, spell id, display text)` in wire order: trigger 0/5 =
-    /// "Use:", 1 = "Equip:", 2 = "Chance on hit:", 6 = a taught spell (the "Already known" red
-    /// check, no green line). The text is app-resolved (the spell's name in P1; its substituted
-    /// description in P2) — green lines.
+    /// Green trigger-spell lines `(trigger, spell id, text)` in wire order: 0 and 5 "Use:",
+    /// 1 "Equip:", 2 "Chance on hit:", 6 a taught spell (no line, only the "Already known" red).
     pub spell_triggers: Vec<(u32, u32, String)>,
-    /// `LockID` — nonzero prints the red "Locked" line (the key-item sub-line joins with the
-    /// Lock.dbc resolve, the GO-locks follow-up).
     pub lock_id: u32,
-    /// "N Charge(s)" — the app-resolved count for the first spell slot that survives the real
-    /// builder's charge gate (`0x52db51`: a slot whose value is 0 or the `-1` consume-on-use
-    /// sentinel prints nothing; else `abs`). 0 = no line.
+    /// "N Charge(s)" for the first spell slot past the builder's gate (`0x52db51`: 0 and -1
+    /// print nothing, else the absolute value); 0 prints no line.
     pub charges: i32,
-    /// The yellow quoted flavor text (wrapped).
     pub description: String,
-    /// Nonzero = "<Right Click to Read>" (green).
     pub page_text: u32,
-    /// Copper — the merchant-open money row (the engine fires `OnTooltipAddMoney`), and
-    /// `ITEM_UNSELLABLE` when 0 in a sell context.
+    /// Copper: the merchant money row, or `ITEM_UNSELLABLE` when 0 in a sell context.
     pub sell_price: u32,
-    /// `itemset` — nonzero renders the SET block ([`ItemSetView`], asked once by set id).
     pub item_set: u32,
-    /// The inventory icon as a ready `Interface\Icons\…` path — app-resolved through
-    /// `ItemDisplayInfo.dbc` off the template's `display_info_id`, the same lookup the bag slots
-    /// use. `GetItemInfo`'s `itemTexture`; the reference builds the identical string at
-    /// `0x48e2dd` (`"%s%s%s"` over the icon directory, `"\\"`, and the row's icon name).
-    /// `None` on the ~26% of display rows that carry no icon.
+    /// `GetItemInfo`'s `itemTexture`, the `Interface\Icons\…` path through `ItemDisplayInfo.dbc`
+    /// (`0x48e2dd`); `None` for a display row with no icon.
     pub icon: Option<String>,
-    /// `RandomProperty` (template `+0x1b8`) — the item CAN roll a "… of the Bear" suffix. Its one
-    /// consumer is the enchant family's third arm: with no instance to read a roll from, the
-    /// tooltip prints the `<Random enchantment>` placeholder instead of any per-slot line
-    /// (`0x52cc33`). Decision 0920.
+    /// `RandomProperty` (template `+0x1b8`): the item can roll a suffix, so a template tooltip
+    /// prints `<Random enchantment>` (`0x52cc33`).
     pub random_property: u32,
 }
 
-/// The player state the red-line law compares against (decision 0274 P1): pushed by the app
-/// whenever it changes. Level and class also ride the `"player"` unit feed; this carries the
-/// pieces that don't (the class/race IDS as mask bits, and the skill ranks).
+/// The player state the tooltip's red lines and the usable gate compare against.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct PlayerReqState {
     pub level: u32,
-    /// Class id (1 warrior … 11 druid) — the `allowable_class` mask bit is `1 << (id-1)`.
+    /// 1 warrior … 11 druid; the `allowable_class` bit is `1 << (id-1)`.
     pub class_id: u32,
-    /// Race id (1 human … 8 troll) — the `allowable_race` mask bit is `1 << (id-1)`.
+    /// 1 human … 8 troll; the `allowable_race` bit is `1 << (id-1)`.
     pub race_id: u32,
-    /// SkillLine id → current rank, for "Requires <skill> (N)" checks.
+    /// SkillLine id → value plus permanent bonus, what the gates compare.
     pub skills: HashMap<u32, u32>,
-    /// Item class (2 weapons / 4 armor) → allowed-subclass bitmask (`SMSG_SET_PROFICIENCY`,
-    /// the client's `0xc4d4a0[class]` store). The slot-line proficiency red: a class WITH an
-    /// entry here reds when the item's `1 << subclass` bit is absent; a class with no entry
-    /// (consumables etc.) never reds.
+    /// Item class → `SMSG_SET_PROFICIENCY` subclass mask (`0xc4d4a0[class]`); a class with no
+    /// entry never reds.
     pub proficiency: HashMap<u32, u32>,
-    /// Faction id → the player's reputation rank (0 hated … 7 exalted; DBC base + wire
-    /// standing, app-ranked) — the "Requires <Faction> - <Standing>" red check.
+    /// Faction id → reputation rank, 0 hated … 7 exalted.
     pub rep_ranks: HashMap<u32, u8>,
-    /// Whether the spellbook holds an effect-40 (SPELL_EFFECT_DUAL_WIELD) spell — the client's
-    /// `0xc4d770` global (stored on learn, cleared on unlearn; reader `0x5eab70`). An off-hand
-    /// weapon (InventoryType 22) reds its SLOT cell without it.
+    /// Whether the spellbook holds a `SPELL_EFFECT_DUAL_WIELD` (40) spell, the client's
+    /// `0xc4d770` (read at `0x5eab70`); without it an off-hand weapon reds its slot cell.
     pub can_dual_wield: bool,
-    /// The player's **highest lifetime honor rank** (`PLAYER_FIELD_BYTES` byte 3) — the
-    /// usable-gate's `RequiredHonorRank` comparand.
+    /// The highest lifetime honor rank (`PLAYER_FIELD_BYTES` byte 3).
     pub honor_rank: u8,
 }
 
-/// [`item_usable`] for an item the caller knows only by **entry** — the shape every window seam
-/// wants, since a row carries an id and the engine holds the templates.
-///
-/// Two conventions are folded in here rather than re-derived per caller: entry `0` (a row with no
-/// item at all) is usable, and a template the app has not answered for yet is usable, which is the
-/// getter's own null-record skip. It was four identical private copies across the merchant, mail,
-/// trade and auction seams before it was one — three had the `item_id == 0` leg and the fourth
-/// reached the same answer through `is_none_or`, which is exactly the kind of agreement that stops
-/// being reliable the moment someone edits one of them.
+/// [`item_usable`] by item entry: entry 0 and a template not yet answered are usable, as the
+/// merchant getter skips an uncached record (`0x4fb298`).
 pub(super) fn item_usable_by_id(model: &super::Model, item_id: u32) -> bool {
     item_id == 0
         || model.item_templates.get(&item_id).is_none_or(|v| {
@@ -201,30 +125,12 @@ pub(super) fn item_usable_by_id(model: &super::Model, item_id: u32) -> bool {
             })
         })
 }
-/// The client's item-usable predicate `0x5ea930(player; itemCacheRecord, &err)`. Both merchant
-/// getters call it (`GetMerchantItemInfo` `0x4fb2a3`, `GetBuybackItemInfo` `0x4fb4f7`) and push
-/// `1`/`nil` as `isUsable`; the FrameXML reds the row on `nil`. The legs, in the binary's order:
-///
-/// 1. `requiredLevel > player level` → unusable.
-/// 2. class mask: `allowableClass & 1<<(classId−1)` clear → unusable (−1 = every bit set).
-/// 3. race mask: same test against `allowableRace`.
-/// 4. proficiency: a mask exists for the item class AND the item's **own** subclass bit is clear
-///    → unusable. NO ItemSubClass alternate walk here — the alternate only chooses which tooltip
-///    CELL reds (0297); the usable gate is the raw bit.
-/// 5. `requiredSkill`: unknown skill → unusable; known → `value + permBonus ≥ requiredSkillRank`.
-/// 6. `requiredSpell`: not in the spellbook → unusable.
-/// 7. `requiredHonorRank`: player's highest honor rank (`PLAYER_FIELD_BYTES` byte 3) short →
-///    unusable.
-/// 8. `requiredCityRank`: tests `PLAYER_FIELD_PVP_MEDALS & 1<<(rank−1)` — vanilla never writes
-///    the medals field and ships no city-rank items, so a nonzero requirement always fails;
-///    mirrored as the constant result rather than plumbing a dead field.
-/// 9. reputation: player standing ≥ the required rank's threshold (`0x4d6370` +
-///    the `0x80928c` threshold table) — equivalently rank ≥ requiredRepRank, the tooltip red's
-///    exact compare; an unknown faction counts as rank 0.
-///
-/// A template the cache hasn't answered yet is USABLE (the getter skips the call on a null
-/// record — `0x4fb298`); the engine analog is an unpushed [`PlayerReqState`] (level 0, a state
-/// the real client can't reach), which also declines to judge.
+/// The client's item-usable predicate `0x5ea930`, whose answer the merchant getters push as
+/// `isUsable` (`0x4fb2a3`, `0x4fb4f7`), its legs in the reference's order. Proficiency tests the
+/// item's own subclass bit, with no alternate walk. A nonzero city rank always fails: it tests
+/// `PLAYER_FIELD_PVP_MEDALS`, which is never written. Reputation compares ranks, equivalent to the
+/// reference's standing threshold (`0x4d6370`, table `0x80928c`); an unknown faction is rank 0. An
+/// unpushed state (level 0) declines to judge, answering usable.
 pub fn item_usable(
     v: &ItemTemplateView,
     req: &PlayerReqState,
@@ -279,39 +185,32 @@ pub fn item_usable(
     true
 }
 
-/// An item set's tooltip view (`0x854b1c`'s SET block), app-resolved: the ItemSet.dbc row with
-/// member item NAMES joined from the template cache (a `None` name = the member's template is
-/// still in flight — its line waits; the app re-pushes as answers land) and the threshold
-/// bonuses' TEXT ($-substituted spell descriptions). The engine supplies the live half: the
-/// owned/equipped counts off its own inventory slots.
+/// An item set's tooltip block (`0x854b1c`), app-resolved from `ItemSet.dbc`: member names from
+/// the template cache and the bonuses' substituted text. The engine counts the equipped members.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct ItemSetView {
     pub name: String,
-    /// `(item id, resolved name)` per member, DBC order.
+    /// `(item id, name)` per member in DBC order; `None` while its template is uncached.
     pub members: Vec<(u32, Option<String>)>,
-    /// `(required equipped count, bonus text)` per bonus, in the DBC's stored slot order —
-    /// the renderer sorts threshold-ascending at print time, like the builder's qsort
-    /// (`0x52e5c0`; The Gladiator ships 3,2,5,4 and prints 2,3,4,5).
+    /// `(required equipped count, bonus text)` in DBC slot order; the renderer sorts by count, as
+    /// the builder's qsort does (`0x52e5c0`).
     pub bonuses: Vec<(u32, String)>,
-    /// The set-level skill requirement ("Requires <skill> (N)"), app-named; 0/None = no line.
+    /// The set's "Requires <skill> (N)"; 0 prints no line.
     pub required_skill: u32,
     pub required_skill_rank: u32,
     pub required_skill_name: Option<String>,
 }
 
 impl super::UiScript {
-    /// Store (or replace) an item's template view — the app's push half of the ask-once flow.
+    /// Stores or replaces an item's template view, clearing its ask.
     pub fn set_item_template(&mut self, item_id: u32, view: ItemTemplateView) {
         let mut model = self.model_mut();
         model.item_stat_asks.remove(&item_id);
         model.item_templates.insert(item_id, view);
     }
 
-    /// Drain the ids the renderer asked for that the store didn't have.
-    /// Ask the app for the templates of `ids` the store does not hold yet — the trade-skill and
-    /// craft feeds' pre-ask (1973): the client has every product's and reagent's template cached
-    /// by the time its list shows, and the link verbs never query, so the feeds ask on the app's
-    /// behalf when the list lands and the verbs read the answers.
+    /// Asks for the templates of `ids` the store lacks, for the trade-skill and craft lists,
+    /// whose link verbs never query: the reference has them cached before the list shows.
     pub fn ask_item_templates(&mut self, ids: impl IntoIterator<Item = u32>) {
         let mut model = self.model_mut();
         for id in ids {
@@ -321,26 +220,25 @@ impl super::UiScript {
         }
     }
 
+    /// Drains the ids read or asked for that the store did not hold.
     pub fn take_item_stat_asks(&mut self) -> Vec<u32> {
         self.model_mut().item_stat_asks.drain().collect()
     }
 
-    /// Store (or replace) a set's view — the SET block's push half (re-pushed as member names
-    /// resolve).
+    /// Stores or replaces a set's view, re-pushed as member names resolve.
     pub fn set_item_set(&mut self, set_id: u32, view: ItemSetView) {
         let mut model = self.model_mut();
         model.item_set_asks.remove(&set_id);
         model.item_sets.insert(set_id, view);
     }
 
-    /// Drain the set ids the renderer asked for that the store didn't have.
+    /// Drains the set ids the renderer asked for that the store did not hold.
     pub fn take_item_set_asks(&mut self) -> Vec<u32> {
         self.model_mut().item_set_asks.drain().collect()
     }
 
-    /// Push the **whole** random-suffix table (`ItemRandomProperties` id → its resolved view) —
-    /// once, at load. Not an ask-once store: see [`super::Model::random_properties`] for why the
-    /// roll table is pushed whole where the template store is asked for.
+    /// Pushes the whole `ItemRandomProperties` table once, at load: a clicked tooltip cannot
+    /// repaint on a late answer.
     pub fn set_random_properties(
         &mut self,
         rows: std::collections::HashMap<u32, super::RandomPropertyView>,
@@ -348,20 +246,15 @@ impl super::UiScript {
         self.model_mut().random_properties = rows;
     }
 
-    /// Push the red-line law's player state (level/class/race/skills). Cheap to call on change.
+    /// Pushes the player state the red lines compare against.
     pub fn set_player_req_state(&mut self, state: PlayerReqState) {
         self.model_mut().player_req = state;
     }
 }
 
-/// Register the shared item-stats global (the P0 Lua stat-head read — still the merchant
-/// sell-cursor's source and the compat surface while call sites finish moving to the engine
-/// renderer; the tooltip itself no longer routes through it).
-/// The 1.12 item-quality palette: the seven ARGB literals the static init `0x5291d0` writes into
-/// the BGRA array at `0xc0d3c8`, and the parallel escape strings at `0x854124`.
-///
-/// `Script::GetItemQualityColor 0x48dfb0` reads `[quality*4 + 0xc0d3c8]`, takes `[+2]=R`,
-/// `[+1]=G`, `[+0]=B`, multiplies each by `1/255`, and returns them with the escape string.
+/// The 1.12 item-quality palette: the ARGB literals the static init `0x5291d0` writes to the BGRA
+/// array `0xc0d3c8`, and the escape strings at `0x854124`. `GetItemQualityColor` (`0x48dfb0`)
+/// answers each channel times 1/255.
 const QUALITY_COLORS: [(u8, u8, u8, &str); 7] = [
     (0x9d, 0x9d, 0x9d, "|cff9d9d9d"), // 0 Poor
     (0xff, 0xff, 0xff, "|cffffffff"), // 1 Common
@@ -372,11 +265,9 @@ const QUALITY_COLORS: [(u8, u8, u8, &str); 7] = [
     (0xe6, 0xcc, 0x80, "|cffe6cc80"), // 6 Artifact
 ];
 
-/// The client's item-link builder `0x52adb0` as the trade-skill and craft link verbs call it
-/// (1973): `|c<rrggbb>|Hitem:<id>:0:0:0|h[<name>]|h|r`
-/// — the three tokens literal zeros at those call sites, the colour from `0x52ad90`'s table where
-/// `cmp ecx,7; jb` is UNSIGNED, so a quality of 7 or more, or a negative one, selects index 1
-/// (white): a fixed fallback, not a clamp. The `""`-suffix arm is dead, so every link ends `|h|r`.
+/// The client's item-link builder `0x52adb0` as the trade-skill and craft link verbs call it:
+/// `|c<rrggbb>|Hitem:<id>:0:0:0|h[<name>]|h|r`. A quality of 7 or more selects index 1, white,
+/// by `0x52ad90`'s unsigned `cmp ecx,7; jb`.
 pub(super) fn item_link(item_id: u32, name: &str, quality: u32) -> String {
     let hex = QUALITY_COLORS
         .get(quality as usize)
@@ -385,21 +276,9 @@ pub(super) fn item_link(item_id: u32, name: &str, quality: u32) -> String {
     format!("{hex}|Hitem:{item_id}:0:0:0|h[{name}]|h|r")
 }
 
-/// `InventoryType` → the `INVTYPE_*` token `GetItemInfo` returns as `itemEquipLoc`.
-///
-/// **The reference's own table, read out of the binary**: `0x48e29b` does
-/// `mov eax,[record+0x2c]` (the inventory type) then `mov edx,[eax*4 + 0x83ddb0]` and pushes the
-/// string — an unguarded index into a 30-pointer array at `0x83ddb0`. Its entries, decoded from
-/// the PE image, are exactly the 28 tokens below at 1..=28, with index **0 and 29 both pointing at
-/// the shared empty string `0x882748`**. So a non-equippable item answers `""`, not nil: an addon
-/// doing `getglobal(itemEquipLoc)` gets nil either way, but one doing `itemEquipLoc == ""` — or
-/// concatenating it — sees what the real client shows.
-///
-/// The spellings are the client's, and four of them (`AMMO`, `THROWN`, `RANGEDRIGHT`, `QUIVER`)
-/// have **no matching GlobalString** in the shipped 1.12 `GlobalStrings.lua`, which defines only
-/// 24 `INVTYPE_*` entries. That asymmetry is the reference's, not ours: the binding hands back a
-/// token the FrameXML cannot localize. Note also `SHOULDER`/`WRIST`/`HAND` are singular here where
-/// our numeric equip-slot map's comments say `SHOULDERS`/`WRISTS`/`HANDS`.
+/// `InventoryType` → `GetItemInfo`'s `itemEquipLoc`, the reference's 30-pointer table at
+/// `0x83ddb0` (`0x48e29b`): slots 0 and 29 are the shared `""` (`0x882748`), not nil, and four
+/// tokens (`AMMO`, `THROWN`, `RANGEDRIGHT`, `QUIVER`) have no `GlobalStrings.lua` entry.
 fn equip_loc_token(inventory_type: u32) -> &'static str {
     const TOKENS: [&str; 29] = [
         "",
@@ -432,15 +311,13 @@ fn equip_loc_token(inventory_type: u32) -> &'static str {
         "INVTYPE_QUIVER",
         "INVTYPE_RELIC",
     ];
-    // The reference does not bounds-check (the value always comes off its own cache record); we
-    // do, because a Lua-reachable path must not depend on that. 29 is the array's own trailing "".
+    // Deviation: bounds-checked where the reference indexes unguarded, so none reads past it.
     TOKENS.get(inventory_type as usize).copied().unwrap_or("")
 }
 
-/// The reference's `atoi` (`0x64ac60`), which is what parses each field of an `item:` string:
-/// an optional leading `-`, then decimal digits, stopping at the first byte that is not one.
-/// **No leading-whitespace skip, no `+`, no `0x`** — and no overflow check either, but a saturating
-/// accumulate is the sane read of a value that can only come from a script.
+/// The reference's `SStrToInt` (`0x64ac60`) over an `item:` field: an optional `-`, then digits up
+/// to the first non-digit, with no whitespace skip and no `+`. Deviation: an overflow saturates at
+/// `u32::MAX` where the reference wraps, because only a script can overflow it.
 fn reference_atoi(s: &str) -> i64 {
     let b = s.as_bytes();
     let (neg, mut i) = match b.first() {
@@ -465,25 +342,11 @@ fn reference_atoi(s: &str) -> i64 {
     }
 }
 
-/// `GetItemInfo`'s argument, resolved to the four `item:` fields — **the reference's parser**
-/// (`0x48e0a3`-`0x48e16d`), which is narrower than every later client's and narrower than the
-/// binding's own usage string suggests:
-///
-/// 1. `lua_isnumber` (`0x6f34d0` — LUA_TNUMBER **or a string Lua coerces to one**) → truncate to
-///    an int and that is the whole answer; enchant/random-property/suffix stay 0. This is the arm
-///    `GetItemInfo(2589)` and `GetItemInfo(tostring(id))` both take.
-/// 2. else `lua_isstring` (`0x6f3510`) → `strnicmp(s, "item:", 5)` (`0x64a4c0` → `0x414310`). On a
-///    match, `atoi` the four colon-separated fields; **on a miss the id stays 0** and the caller
-///    returns nothing.
-/// 3. else raise `Usage: GetItemInfo(itemID|"itemlink")` — the literal at `0x842d24`, pushed
-///    through `0x6f4940` (`luaL_where` + `lua_pushvfstring` + concat + `lua_error`: it raises).
-///
-/// **So a bare item NAME and a full `|cff…|Hitem:…|h[Name]|h|r` hyperlink both resolve to nothing**
-/// on the real 1.12 client — neither begins with `item:`. The "itemlink" the usage string means is
-/// the *item string*, which is also what the binding returns as its second value. Auctioneer builds
-/// exactly that (`AucItemDB.lua:333`: `string.format("item:%s:%s:%s:0", …)`) before calling this.
+/// `GetItemInfo`'s argument as the reference parses it (`0x48e0a3`-`0x48e16d`): a number, or a
+/// string `lua_isnumber` (`0x6f34d0`) coerces, is the id alone; another string (`0x6f3510`) must
+/// pass `strnicmp(s, "item:", 5)` (`0x64a4c0`) for its four fields, else it is id 0, so a name or
+/// a hyperlink finds nothing; anything else raises the usage error (`0x842d24`, via `0x6f4940`).
 fn parse_item_arg(v: &Value) -> mlua::Result<(i64, u32, u32, u32)> {
-    // Arm 1 — a number, or a string Lua's own coercion reads as one.
     let as_number = match v {
         Value::Integer(i) => Some(*i as f64),
         Value::Number(n) => Some(*n),
@@ -493,7 +356,7 @@ fn parse_item_arg(v: &Value) -> mlua::Result<(i64, u32, u32, u32)> {
     if let Some(n) = as_number {
         return Ok((n as i64, 0, 0, 0));
     }
-    // Arm 2 — a string. Anything that is not `item:`-prefixed leaves the id at 0.
+    // An `item:` string; any other string is id 0.
     let Value::String(s) = v else {
         return Err(mlua::Error::RuntimeError(
             "Usage: GetItemInfo(itemID|\"itemlink\")".into(),
@@ -516,32 +379,13 @@ fn parse_item_arg(v: &Value) -> mlua::Result<(i64, u32, u32, u32)> {
 }
 
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
-    // `GetItemQualityColor(quality)` → `r, g, b, escapeString` (decision 1199).
-    //
-    // A **C-registered** binding in the reference (`0x48dfb0`) and `function engine` in the
-    // captured `_G`, which is why it belongs here rather than in `assets/ui`: the shipped
-    // `UIParent.lua` *builds* `ITEM_QUALITY_COLORS` by calling it in a loop (`for i = -1, 6`), so
-    // the table is FrameXML's and the verb underneath is the engine's. 23 corpus addons call it,
-    // and three of our own XML files carry a private copy of the palette this replaces.
-    //
-    // **The clamp is the reference's, not a guess** — and it is ONE clamp, not two, because the
-    // comparison is UNSIGNED. `0x52ad70`/`0x52ad90` both do `cmp ecx,7` / `jb`, so anything at or
-    // above 7 selects index **1** (Common) — not 6, not an error — and a NEGATIVE quality takes the
-    // same branch, because as a `u32` it is at or above 7 too. `GetItemQualityColor(-1)` is
-    // therefore **white**, and so is `ITEM_QUALITY_COLORS[-1]`, the row `UIParent.lua`'s
-    // `for i = -1, 6` builds.
-    //
-    // This corrects 1199, which called the negative arm "the one place this binding is deliberately
-    // not bit-faithful … because the faithful answer is an out-of-bounds read" and answered Poor
-    // (grey). There is no out-of-bounds read: the unsigned compare catches it first. The value
-    // stopped being academic when the loot window went to the chain — `-1` is what
-    // `GetLootSlotInfo` answers for a row whose item template is not cached, and that row's text
-    // colour is this table's `-1` row (`0x4c2435`, decision 1805).
+    // GetItemQualityColor(quality) → r, g, b, escapeString (`0x48dfb0`). 7 and up, or a negative
+    // quality, answer Common (`0x52ad70`/`0x52ad90`: an unsigned `cmp ecx,7; jb`), so
+    // `ITEM_QUALITY_COLORS[-1]` is white, the colour of an uncached loot row (`0x4c2435`).
     lua.globals().set(
         "GetItemQualityColor",
         lua.create_function(|lua, quality: i64| {
-            // The reference reads its argument as a 32-bit int (`ftol`) and then compares it
-            // unsigned, which is exactly this pair of casts.
+            // A 32-bit int (`__ftol`), compared unsigned.
             let i = match quality as i32 as u32 {
                 q if q >= 7 => 1,
                 q => q as usize,
@@ -556,49 +400,20 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetItemInfo(itemID | "item:id:enchant:randomProperty:suffix")` →
-    //   itemName, itemLink, itemQuality, itemMinLevel, itemType, itemSubType,
-    //   itemStackCount, itemEquipLoc, itemTexture
-    //
-    // **Nine values, and every one of them confirmed** against the registered binding
-    // `0x48e070`, which ends `mov eax,0x9; ret`. The
-    // signature is the whole point of the verb (decision 1199): a later client inserts `itemLevel`
-    // at position 4 and pushes the required level to 5, and 36 corpus addons destructure this one
-    // positionally — `Informant/Informant.lua:268` reads all nine and stores position 4 as
-    // `['reqLevel']`, `Auctioneer/Database/AucItemDB.lua:288` as `useLevel`.
-    //
-    // Per value, with the instruction that pushes it:
-    //
-    //  1 `itemName`    `0x5d8b00(buf, 0x400, itemId, randomProperty)` — the template name with the
-    //                  `ItemRandomProperties.dbc` suffix appended. **We push the bare template
-    //                  name**: the suffix table is the same stated gap `ui_items::item_link`
-    //                  already carries, one random-suffix arc, not per-call-site drift.
-    //  2 `itemLink`    `0x48e1c9`: `SStrPrintf(buf, 0x400, "item:%d:%d:%d:%d", id, enchant,
-    //                  randomProperty, suffix)` — the literal at `0x842d4c`. In 1.12 this is the
-    //                  **item string**, NOT the coloured `|cff…|Hitem:…|h[Name]|h|r` hyperlink
-    //                  (that is `GetContainerItemLink`'s shape and stays there). Auctioneer's
-    //                  `getItemInfoFromBlizzard` names the return `itemString` and feeds it
-    //                  straight back in, which only works because both ends are this shape.
-    //  3 `itemQuality` `fild [record+0x1c]` — the same dword `0x495300` reads for the drag
-    //                  payload.
-    //  4 `itemMinLevel` `fild [record+0x3c]` — the **required** level. `ItemLevel` lives one dword
-    //                  earlier at `+0x38` and is never pushed here. This is the trap.
-    //  5 `itemType`    ItemClass.dbc's localized class name, or `""` (`0x48e236`).
-    //  6 `itemSubType` ItemSubClass.dbc, VerboseName then DisplayName (`0x48e311`), or `""`.
-    //  7 `itemStackCount` `fild [record+0x60]` — `Stackable`, not `MaxCount` (`+0x5c`).
-    //  8 `itemEquipLoc` `[invType*4 + 0x83ddb0]` — the `INVTYPE_*` token; `""` at index 0.
-    //  9 `itemTexture` `"%s%s%s"` over the icon dir, `"\\"` and the ItemDisplayInfo icon name.
-    //
-    // **A template the store has not seen yet returns nothing and records the ask**, exactly like
-    // `BenillaGetItemStats` — and exactly like the reference, whose cache lookup `0x55ba30` fires
-    // the query and returns null, taking the binding straight to `xor eax,eax; ret` (0 values).
-    // The first call comes back empty and the answer arrives later; we never block or fabricate.
+    // GetItemInfo(itemID | "item:id:enchant:randomProperty:suffix") → itemName, itemLink,
+    // itemQuality, itemMinLevel, itemType, itemSubType, itemStackCount, itemEquipLoc, itemTexture:
+    // nine values (`0x48e070` ends `mov eax,0x9`); later clients insert `itemLevel` at 4. The name
+    // is the bare template name, where the reference appends the random suffix (`0x5d8b00`); the
+    // link is the item string (`0x48e1c9`, literal `0x842d4c`), not a hyperlink; the level is the
+    // required one (`[record+0x3c]`; `ItemLevel` at `+0x38` is never pushed). An uncached
+    // template answers no values and records the ask, as the reference's lookup (`0x55ba30`)
+    // queries and returns null, sending the binding to `xor eax,eax; ret`.
     lua.globals().set(
         "GetItemInfo",
         lua.create_function(|lua, arg: Value| {
             let (id, enchant, random_property, suffix) = parse_item_arg(&arg)?;
             let Ok(item_id) = u32::try_from(id) else {
-                return Ok(MultiValue::new()); // negative / past u32: no record can hold it
+                return Ok(MultiValue::new()); // no record holds a negative or past-u32 id
             };
             let view = {
                 let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -623,9 +438,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 Value::String(lua.create_string(str_or_empty(&v.item_sub_type))?),
                 Value::Integer(i64::from(v.stackable)),
                 Value::String(lua.create_string(equip_loc_token(v.inventory_type))?),
-                // The one value that can be genuinely absent rather than empty: a display row
-                // with no icon column. `nil` rather than the reference's `Interface\Icons\`,
-                // which is a path that cannot load — both read as "no icon" to `SetTexture`.
+                // Deviation: nil for a display row with no icon, where the reference answers the
+                // unloadable `Interface\Icons\`, because `SetTexture` shows no icon for either.
                 match &v.icon {
                     Some(icon) => Value::String(lua.create_string(icon)?),
                     None => Value::Nil,
@@ -635,7 +449,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // BenillaGetItemStats(itemId) → name, quality, invType, class, subclass, dmgMin, dmgMax,
-    // dmgType, delayMs, armor, block, sellPrice — or nil (recording the ask).
+    // dmgType, delayMs, armor, block, sellPrice, or nil and an ask.
     lua.globals().set(
         "BenillaGetItemStats",
         lua.create_function(|lua, item_id: u32| {
@@ -674,7 +488,6 @@ mod tests {
     use super::{item_usable, ItemTemplateView, PlayerReqState};
     use crate::script::UiScript;
 
-    /// Every leg of the `0x5ea930` gate, one at a time against a passing baseline.
     #[test]
     fn item_usable_mirrors_the_gate_legs() {
         let base_item = ItemTemplateView {
@@ -691,7 +504,7 @@ mod tests {
         let knows_none = |_: u32| false;
         assert!(item_usable(&base_item, &base_req, knows_none));
 
-        // 1 · level: required 5 vs level 4 fails; exactly 5 passes (jg, not jge).
+        // Level 5 required: level 4 fails, 5 passes (`jg`).
         let mut v = base_item.clone();
         v.required_level = 5;
         assert!(!item_usable(&v, &base_req, knows_none));
@@ -699,7 +512,6 @@ mod tests {
         req.level = 5;
         assert!(item_usable(&v, &req, knows_none));
 
-        // 2/3 · class + race masks: the player's bit must be set; −1 has every bit.
         let mut v = base_item.clone();
         v.allowable_class = 1 << 3; // rogue-only (class 4)
         assert!(!item_usable(&v, &base_req, knows_none));
@@ -707,8 +519,7 @@ mod tests {
         v.allowable_race = 1 << 0; // human-only
         assert!(!item_usable(&v, &base_req, knows_none));
 
-        // 4 · proficiency: a mask for the item class with the subclass bit clear fails — and
-        // there is NO alternate walk here (a 2H axe reds even when the 1H bit is set).
+        // No alternate walk: a 2H axe fails with only the 1H bit set.
         let mut v = base_item.clone();
         (v.class, v.subclass) = (2, 1); // Two-Handed Axe
         let mut req = base_req.clone();
@@ -716,12 +527,12 @@ mod tests {
         assert!(!item_usable(&v, &req, knows_none));
         req.proficiency.insert(2, 1 << 1);
         assert!(item_usable(&v, &req, knows_none));
-        // No mask for the class at all (consumables): the leg never fires.
+        // No mask for the class: the leg never fires.
         let mut v = base_item.clone();
         (v.class, v.subclass) = (0, 0);
         assert!(item_usable(&v, &base_req, knows_none));
 
-        // 5 · skill: unknown skill fails even at rank 0; known compares value ≥ rank.
+        // An unknown skill fails even at rank 0.
         let mut v = base_item.clone();
         v.required_skill = 164; // Blacksmithing
         assert!(!item_usable(&v, &base_req, knows_none));
@@ -733,13 +544,11 @@ mod tests {
         req.skills.insert(164, 100);
         assert!(item_usable(&v, &req, knows_none));
 
-        // 6 · spell: required and not in the spellbook fails.
         let mut v = base_item.clone();
         v.required_spell = 9787; // Weaponsmith
         assert!(!item_usable(&v, &base_req, knows_none));
         assert!(item_usable(&v, &base_req, |id| id == 9787));
 
-        // 7 · honor rank: the player's highest rank must reach it.
         let mut v = base_item.clone();
         v.required_honor_rank = 3;
         assert!(!item_usable(&v, &base_req, knows_none));
@@ -747,14 +556,11 @@ mod tests {
         req.honor_rank = 3;
         assert!(item_usable(&v, &req, knows_none));
 
-        // 8 · city rank: no live data ever sets it, and the medals field it tests is never
-        // written — a nonzero requirement can only fail.
         let mut v = base_item.clone();
         v.required_city_rank = 1;
         assert!(!item_usable(&v, &base_req, knows_none));
 
-        // 9 · reputation: rank below the requirement fails; at it, passes; an unknown faction
-        // is rank 0 (fails any nonzero requirement, passes a zero one).
+        // An unknown faction is rank 0.
         let mut v = base_item.clone();
         (v.required_rep_faction, v.required_rep_rank) = (87, 5);
         assert!(!item_usable(&v, &base_req, knows_none));
@@ -765,14 +571,12 @@ mod tests {
         (v.required_rep_faction, v.required_rep_rank) = (87, 0);
         assert!(item_usable(&v, &base_req, knows_none));
 
-        // An unpushed player state (level 0 — unreachable in the real client) declines to judge.
+        // An unpushed state (level 0) declines to judge.
         let mut v = base_item.clone();
         v.required_level = 60;
         assert!(item_usable(&v, &PlayerReqState::default(), knows_none));
     }
 
-    /// The ask-once loop end-to-end: a miss answers nil AND records the ask; the app's push makes
-    /// the next read answer the stat head; the push clears the pending ask.
     #[test]
     fn miss_records_ask_and_push_serves_the_stats() {
         let mut s = UiScript::new().unwrap();
@@ -798,7 +602,7 @@ mod tests {
             s.eval("return BenillaGetItemStats(25)").unwrap();
         assert_eq!((name.as_str(), quality, inv), ("Worn Shortsword", 1, 21));
         assert!(s.take_item_stat_asks().is_empty(), "push cleared the ask");
-        // id 0 (an unresolved row) never records a junk ask.
+        // Id 0 records no ask.
         assert!(s
             .eval::<bool>("return BenillaGetItemStats(0) == nil")
             .unwrap());
@@ -811,11 +615,7 @@ mod get_item_info_tests {
     use super::{equip_loc_token, reference_atoi, ItemTemplateView};
     use crate::script::UiScript;
 
-    /// **Worn Shortsword (25)**, with every field taken from the live vmangos `item_template`
-    /// row so the assertions below are about real data:
-    /// `class 2, subclass 7, quality 1, inventory_type 21, required_level 1, item_level 2,
-    /// max_count 0, stackable 1`. The two app-resolved names are what the shipped
-    /// `ItemClass.dbc` / `ItemSubClass.dbc` rows hold for `(2, 7)`.
+    /// Worn Shortsword, item 25, as vmangos `item_template` holds it (item level 2).
     fn worn_shortsword() -> ItemTemplateView {
         ItemTemplateView {
             name: "Worn Shortsword".into(),
@@ -824,10 +624,9 @@ mod get_item_info_tests {
             subclass: 7,
             inventory_type: 21,
             item_type: Some("Weapon".into()),
-            // VerboseName, not the tooltip cell's "Sword" — the binding's `0x48e311` two-step.
+            // VerboseName, not the tooltip cell's "Sword" (`0x48e311`).
             item_sub_type: Some("One-Handed Swords".into()),
-            // The pair that makes position 4 falsifiable: this item's REQUIRED level is 1 and its
-            // ITEM level is 2. Ashbringer (13262) is the loud version — required 60, item 76.
+            // Required level 1 against item level 2 makes position 4 falsifiable.
             required_level: 1,
             stackable: 1,
             max_count: 0,
@@ -836,12 +635,7 @@ mod get_item_info_tests {
         }
     }
 
-    /// The whole signature, destructured in order exactly as `Informant/Informant.lua:268` and
-    /// `Auctioneer/Database/AucItemDB.lua:288` destructure it.
-    ///
-    /// **The arity assertion is half the test.** A regression to a later client's shape inserts
-    /// `itemLevel` at position 4 and makes this ten values; the COUNT is the only check that
-    /// notices, because every individual read still "works".
+    /// The arity catches a later client's shape, which inserts `itemLevel` at position 4.
     #[test]
     fn get_item_info_returns_the_1_12_nine_value_shape() {
         let mut s = UiScript::new().unwrap();
@@ -867,8 +661,7 @@ mod get_item_info_tests {
             .eval("local a,b,c,d,e,f,g,h,i = GetItemInfo(25) return a,b,c,d,e,f,g,h,i")
             .unwrap();
         assert_eq!(name, "Worn Shortsword");
-        // Return 2 is the ITEM STRING, not the coloured hyperlink (`"item:%d:%d:%d:%d"` at
-        // 0x842d4c). A number argument leaves the other three fields at 0.
+        // The item string (`0x842d4c`); a number argument leaves the other fields 0.
         assert_eq!(link, "item:25:0:0:0");
         assert_eq!(quality, 1);
         assert_eq!(min_level, 1);
@@ -879,11 +672,7 @@ mod get_item_info_tests {
         assert_eq!(texture.as_deref(), Some("Interface\\Icons\\INV_Sword_04"));
     }
 
-    /// **Position 4 is the REQUIRED level, and position 5 is a string.** This is the whole reason
-    /// decision 1199 exists, one verb later: every client after 1.12 inserts `itemLevel` at 4 and
-    /// pushes `itemMinLevel` to 5, so a regression makes position 5 a *number*. Both halves are
-    /// asserted, against a template whose two levels genuinely differ (Ashbringer: required 60,
-    /// item level 76 — verified in the live vmangos `item_template`).
+    /// Ashbringer, item 13262: required level 60, item level 76 in vmangos `item_template`.
     #[test]
     fn position_four_is_the_required_level_not_the_item_level() {
         let mut s = UiScript::new().unwrap();
@@ -897,7 +686,7 @@ mod get_item_info_tests {
                 inventory_type: 17,
                 item_type: Some("Weapon".into()),
                 item_sub_type: Some("Two-Handed Swords".into()),
-                required_level: 60, // item_level is 76 and is NEVER returned by 1.12
+                required_level: 60, // item level 76 is never returned
                 max_count: 1,
                 stackable: 1,
                 ..Default::default()
@@ -924,10 +713,7 @@ mod get_item_info_tests {
         );
     }
 
-    /// **Position 7 is `Stackable`, not `MaxCount`** — `[record+0x60]`, the dword *after*
-    /// `MaxCount` at `+0x5c`. The view carries both and they are not interchangeable: Linen Cloth
-    /// is `max_count 0, stackable 20` in the live `item_template`, so reading the wrong one gives
-    /// every reagent counter in the corpus a stack size of zero.
+    /// Linen Cloth, item 2589: `max_count 0, stackable 20` in vmangos `item_template`.
     #[test]
     fn position_seven_is_the_stack_size_not_the_unique_cap() {
         let mut s = UiScript::new().unwrap();
@@ -949,14 +735,10 @@ mod get_item_info_tests {
             .eval("local _,_,_,_,_,_,g,h = GetItemInfo(2589) return g,h")
             .unwrap();
         assert_eq!(stack, 20, "Stackable (+0x60), never MaxCount (+0x5c)");
-        // InventoryType 0 answers the EMPTY STRING, not nil — index 0 of the 0x83ddb0 table
-        // points at the shared "" at 0x882748.
+        // InventoryType 0 answers "", not nil.
         assert_eq!(equip, "");
     }
 
-    /// The ask-once loop, the reference's own uncached-item behaviour: the cache lookup
-    /// (`0x55ba30`) fires the query and returns null, and the binding falls to
-    /// `xor eax,eax; ret` — **no values at all**, not a nil.
     #[test]
     fn an_uncached_id_returns_nothing_and_records_the_ask() {
         let mut s = UiScript::new().unwrap();
@@ -983,23 +765,17 @@ mod get_item_info_tests {
         );
         assert!(s.take_item_stat_asks().is_empty(), "the push cleared it");
 
-        // Id 0 and a negative id are not askable — no junk query goes out for them.
+        // Id 0 and a negative id record no ask.
         assert_eq!(s.arity("GetItemInfo(0)").unwrap(), 0);
         assert_eq!(s.arity("GetItemInfo(-5)").unwrap(), 0);
         assert!(s.take_item_stat_asks().is_empty());
     }
 
-    /// **The argument forms, which are narrower than the documentation** (see `parse_item_arg`):
-    /// a number, a string Lua coerces to one, or an `item:`-prefixed *item string*. A bare item
-    /// NAME and a full `|cff…|Hitem:…` hyperlink both resolve to id 0 on the real client, because
-    /// `strnicmp(s, "item:", 5)` is the only string test there is.
     #[test]
     fn the_argument_forms_are_the_references_own() {
         let mut s = UiScript::new().unwrap();
         s.set_item_template(25, worn_shortsword());
 
-        // A number, and a string Lua's own coercion reads as one (`lua_isnumber`, 0x6f34d0) —
-        // `GetItemInfo(tostring(id))` is a real corpus call shape.
         for arg in ["25", "\"25\"", "25.7"] {
             assert_eq!(
                 s.eval::<String>(&format!("return (GetItemInfo({arg}))"))
@@ -1009,24 +785,20 @@ mod get_item_info_tests {
             );
         }
 
-        // The item string — the form Auctioneer builds (`AucItemDB.lua:333`). Its enchant /
-        // random-property / suffix fields are echoed back into return 2 verbatim, which is what
-        // makes Auctioneer's feed-the-answer-back-in round trip.
+        // An item string's other fields echo into return 2 verbatim.
         let (name, link): (String, String) = s
             .eval("local a,b = GetItemInfo(\"item:25:2564:7:0\") return a,b")
             .unwrap();
         assert_eq!(name, "Worn Shortsword");
         assert_eq!(link, "item:25:2564:7:0");
-        // Case-insensitive prefix, and a truncated string still parses (atoi stops at the NUL).
+        // A case-insensitive prefix, and a short string still parses.
         assert_eq!(
             s.eval::<String>("local _, link = GetItemInfo(\"ITEM:25\") return link")
                 .unwrap(),
             "item:25:0:0:0"
         );
 
-        // A bare NAME and a full hyperlink: no values. Neither begins with "item:", so the id
-        // stays 0 and the record lookup fails — the real client answers nothing here too, and
-        // neither records an ask.
+        // A bare name and a full hyperlink are id 0: no values and no ask.
         for arg in [
             "\"Worn Shortsword\"",
             "\"|cffffffff|Hitem:25:0:0:0|h[Worn Shortsword]|h|r\"",
@@ -1040,8 +812,7 @@ mod get_item_info_tests {
         }
         assert!(s.take_item_stat_asks().is_empty());
 
-        // Neither a number nor a string raises the binding's own usage error (`0x842d24`, pushed
-        // through the `luaL_error` shape at `0x6f4940`).
+        // Neither a number nor a string raises the usage error (`0x842d24`).
         let err = s
             .eval::<mlua::Value>("return GetItemInfo(nil)")
             .unwrap_err()
@@ -1052,8 +823,6 @@ mod get_item_info_tests {
         );
     }
 
-    /// The `INVTYPE_*` table, transcribed from the 30-pointer array at `0x83ddb0`: both ends,
-    /// the four tokens the shipped `GlobalStrings.lua` never defines, and the empty-string slots.
     #[test]
     fn the_equip_loc_tokens_are_the_binarys_table() {
         assert_eq!(equip_loc_token(0), "", "index 0 is the shared \"\"");
@@ -1063,7 +832,7 @@ mod get_item_info_tests {
         assert_eq!(equip_loc_token(10), "INVTYPE_HAND", "singular");
         assert_eq!(equip_loc_token(17), "INVTYPE_2HWEAPON");
         assert_eq!(equip_loc_token(20), "INVTYPE_ROBE");
-        // The four with no GlobalString to localize them — the reference's own asymmetry.
+        // The four with no `GlobalStrings.lua` entry.
         assert_eq!(equip_loc_token(24), "INVTYPE_AMMO");
         assert_eq!(equip_loc_token(25), "INVTYPE_THROWN");
         assert_eq!(equip_loc_token(26), "INVTYPE_RANGEDRIGHT");
@@ -1073,8 +842,6 @@ mod get_item_info_tests {
         assert_eq!(equip_loc_token(9999), "", "past the array");
     }
 
-    /// The reference's `atoi` (`0x64ac60`): no whitespace skip, no `+`, stop at the first
-    /// non-digit. The last two cases are why this is not `str::parse`.
     #[test]
     fn the_field_parser_is_the_references_atoi() {
         assert_eq!(reference_atoi("2589"), 2589);
@@ -1091,12 +858,6 @@ mod get_item_info_tests {
 mod quality_color_tests {
     use crate::script::UiScript;
 
-    /// The seven colours, confirmed against the reference's own table (`0x5291d0`) — and the
-    /// two edges, which are where every reimplementation of this goes wrong.
-    ///
-    /// The escape string matters as much as the floats: the reference returns it as the fourth
-    /// value and addons splice it straight into a link (`ITEM_QUALITY_COLORS[q].hex .. name`), so
-    /// a missing or differently-cased one shows as literal text in a chat line.
     #[test]
     fn get_item_quality_color_is_the_references_own_table() {
         let s = UiScript::new().unwrap();
@@ -1118,20 +879,16 @@ mod quality_color_tests {
             assert_eq!(hex(q), want, "quality {q}");
         }
 
-        // The floats are `byte / 255`, not a rounded approximation — Epic's red is 0xa3/255.
+        // The floats are byte / 255: Epic's red is 0xa3.
         let r = s
             .eval::<f64>("local r = GetItemQualityColor(4) return r")
             .unwrap();
         assert!((r - 163.0 / 255.0).abs() < 1e-9, "epic red was {r}");
 
-        // `>= 7` clamps to COMMON (index 1), the accessor `0x52ad70`'s own rule — not to Artifact,
-        // and never to nil, because the caller concatenates the result.
+        // 7 and up answer Common (`0x52ad70`).
         assert_eq!(hex(7), "|cffffffff");
         assert_eq!(hex(99), "|cffffffff");
-        // …and the compare is UNSIGNED, so every negative takes the SAME branch and reads Common.
-        // This is the row `UIParent.lua`'s `for i = -1, 6` builds, and the colour a loot row wears
-        // while its item template is uncached (`GetLootSlotInfo` answers -1 there). It read Poor
-        // until 1805; there is no out-of-bounds read to reproduce, the `jb` catches it first.
+        // The compare is unsigned, so a negative answers Common too.
         assert_eq!(hex(-1), "|cffffffff");
         assert_eq!(hex(-99), "|cffffffff");
     }
diff --git a/crates/benilla-ui/src/script/item_text.rs b/crates/benilla-ui/src/script/item_text.rs
index 2d28bfbb..36bc2466 100644
--- a/crates/benilla-ui/src/script/item_text.rs
+++ b/crates/benilla-ui/src/script/item_text.rs
@@ -1,45 +1,32 @@
-//! The item-text reader seam — the `ItemTextFrame` (letters, books, plaques) Lua surface.
-//!
-//! The app owns the read session (`crate::ui_item_text` on the benilla side): right-clicking a bag
-//! item whose `ITEM_FIELD_ITEM_TEXT_ID` is set opens a read instead of a `CMSG_USE_ITEM`, fetches
-//! the text over the ask-once `CMSG_ITEM_TEXT_QUERY` cache (the same wire mail letter bodies ride),
-//! then pushes an [`ItemTextState`] here and fires the reference event pair `ITEM_TEXT_BEGIN` →
-//! `ITEM_TEXT_READY` (ItemTextFrame.lua l.11/38). This module is only the Lua-facing mirror:
-//!
-//! - Getters over the pushed state: `ItemTextGetItem()` (the title), `ItemTextGetCreator()`,
-//!   `ItemTextGetText()`, `ItemTextGetPage()`, `ItemTextHasNextPage()`, `ItemTextGetMaterial()`
-//!   (`nil` → the Lua's own "Parchment" default, l.19-21).
-//! - Intents the app drains: `CloseItemText()` (the frame's OnHide, l.349 — the app clears the
-//!   session and fires `ITEM_TEXT_CLOSED`), `ItemTextPrevPage()`/`ItemTextNextPage()` (multi-page
-//!   `PageText` books — a named follow-up; single-page letters never show the buttons).
+//! The `ItemTextFrame` Lua surface (letters, books, plaques) over the read session the app owns:
+//! getters over the pushed [`ItemTextState`], and the close and page-turn intents. The app fires
+//! `ITEM_TEXT_BEGIN` then `ITEM_TEXT_READY` (`ItemTextFrame.lua:11`, `:38`), and `ITEM_TEXT_CLOSED`
+//! after `CloseItemText()`, the frame's OnHide (`ItemTextFrame.xml:349`).
 
 use mlua::{Lua, Value};
 
 use super::Model;
 
-/// The open read session's Lua-visible snapshot, pushed whole by the app.
+/// The open read session as Lua sees it, pushed whole by the app.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct ItemTextState {
-    /// The read item's name (`ItemTextGetItem()` — the window title, e.g. "Plain Letter").
+    /// `ItemTextGetItem()`: the item's name, the window title.
     pub item: String,
-    /// The letter's author (`ItemTextGetCreator()` — `ITEM_FIELD_CREATOR` resolved through the
-    /// name cache); `None` for an authorless text (books) — the Lua skips the "From," tail.
+    /// `ItemTextGetCreator()`: `ITEM_FIELD_CREATOR`'s name, `None` for an authorless text.
     pub creator: Option<String>,
-    /// The current page's text (`ItemTextGetText()`).
+    /// `ItemTextGetText()`: the current page's text.
     pub text: String,
     /// The 1-based page (`ItemTextGetPage()`); letters are always page 1.
     pub page: u32,
     /// Whether a next page exists (`ItemTextHasNextPage()`); always `false` for letters.
     pub has_next: bool,
-    /// The page material basename (`ItemTextGetMaterial()`, e.g. "Stone"); `None` = the default
-    /// parchment (the Lua substitutes "Parchment" and hides the material corners).
+    /// `ItemTextGetMaterial()`, e.g. "Stone"; `None` reads nil, which the frame shows as
+    /// parchment (`ItemTextFrame.lua:19-21`).
     pub material: Option<String>,
 }
 
 impl super::UiScript {
-    /// Push (or clear, with `None`) the open read session. The app pairs the push with the
-    /// reference event flow: set → `ITEM_TEXT_BEGIN` → (text fetched) → `ITEM_TEXT_READY`;
-    /// clear → `ITEM_TEXT_CLOSED`.
+    /// Push the open read session, or clear it with `None`.
     pub fn set_item_text(&mut self, state: Option<ItemTextState>) {
         self.model_mut().item_text = state;
     }
@@ -173,7 +160,7 @@ mod tests {
     #[test]
     fn getters_mirror_the_pushed_state() {
         let mut s = UiScript::new().unwrap();
-        // No session: benign defaults (the frame only reads these while shown anyway).
+        // No session: empty defaults; the frame reads these only while shown.
         assert_eq!(s.eval::<String>("return ItemTextGetItem()").unwrap(), "");
         assert!(s
             .eval::<bool>("return ItemTextGetCreator() == nil")
diff --git a/crates/benilla-ui/src/script/keybind.rs b/crates/benilla-ui/src/script/keybind.rs
index 2a7461b0..30b3f525 100644
--- a/crates/benilla-ui/src/script/keybind.rs
+++ b/crates/benilla-ui/src/script/keybind.rs
@@ -1,33 +1,7 @@
-//! The **key-binding table** — the client's chord→command store, engine side (decision 0997).
-//!
-//! In the reference every rebindable action is a *binding*: a command name (`MOVEFORWARD`)
-//! carrying a category header and up to two bound key chords, stored key→command and saved to
-//! `bindings-cache.wtf`. 1.12 exposes the whole system to Lua (`Blizzard_BindingUI` is plain
-//! FrameXML over it): `GetNumBindings`/`GetBinding(i)`, `SetBinding(key[, command])` with its
-//! steal-the-key law, `GetBindingKey`/`GetBindingAction`, and the three-set model —
-//! `LoadBindings(0 default | 1 account | 2 character)`, `SaveBindings(which)`,
-//! `GetCurrentBindingSet()`.
-//!
-//! benilla keeps the same shape at the same seam, split like the CVar table (0954): the **host
-//! registers** the commands it actually implements (honest-tree — no row without a real engine
-//! action) with their 1.12 default chords, **this table is the string-domain truth** the window's
-//! Lua reads and writes synchronously, and the app derives its dispatch view (parsed chords →
-//! latched commands) whenever [`super::UiScript::keybinds_generation`] moves, persisting on the
-//! queued [`KeybindRequest::Save`]. Chord strings are the reference's own canon —
-//! `[ALT-][CTRL-][SHIFT-]<TOKEN>` (`W`, `SPACE`, `NUMPAD0`, `BUTTON4`, `MOUSEWHEELUP`) — matched
-//! by string equality exactly as the client does (decision 0585's law, now engine-wide).
-//!
-//! The stored account/character sets live here too (seeded by the app from
-//! `benilla-config/bindings/…`, re-snapshotted on save), so `LoadBindings` is **synchronous** like the
-//! reference's — the window calls it and repaints in the same tick, no host round-trip.
-//!
-//! **Addons register into the same table** (decision 1188 phase 4). An addon's `Bindings.xml`
-//! ([`crate::bindings_xml`]) arrives through [`super::UiScript::register_addon_bindings`] and
-//! becomes ordinary rows: same names, same chords, same window, same save file. The one thing an
-//! addon row carries that a host row does not is a **body** — the Lua chunk the app's dispatch
-//! runs on the press (and, for `runOnUp`, again on the release with `keystate = "up"`) — because a
-//! host command's action is engine-side and has no Lua to hold. That body is the *only* asymmetry;
-//! everything downstream of registration treats the two identically.
+//! The key-binding table behind `GetBinding`, `SetBinding`, `LoadBindings` and their kin: per
+//! command, a category header and its chords, spelled `[ALT-][CTRL-][SHIFT-]<TOKEN>` and matched by
+//! string equality as the reference does. Host commands carry their 1.12 defaults; an addon's
+//! `Bindings.xml` adds ordinary rows that also carry a Lua body.
 
 use std::collections::HashMap;
 
@@ -37,10 +11,9 @@ use crate::bindings_xml::AddonBinding;
 
 use super::Model;
 
-/// One host-registered command: the 1.12 name, its category header's global-string key
-/// (`BINDING_HEADER_MOVEMENT`), whether it has press+release semantics (`runOnUp` — the
-/// release half of a press rides this — `RunCommand 0x4b7bf1`, and nothing else: it is NOT a
-/// bindability rule, see [`normalize_binding_key`]), and the 1.12 default chords.
+/// One host-registered command: the 1.12 name, its category header's global string
+/// (`BINDING_HEADER_MOVEMENT`), whether it also runs on release (`runOnUp`, read only by
+/// `RunCommand` at `0x4b7bf1`, never a bindability rule), and the 1.12 default chords.
 #[derive(Clone, Copy, Debug)]
 pub struct KeybindCommand {
     pub name: &'static str,
@@ -50,17 +23,10 @@ pub struct KeybindCommand {
     pub default2: Option<&'static str>,
 }
 
-/// One addon-declared binding's **runnable half** — what the app's dispatch needs to fire a row
-/// it cannot find in its own `SPECS` registry (decision 1188 phase 4).
-///
-/// The dispatch view is re-derived whenever [`super::UiScript::keybinds_generation`] moves, so
-/// this is a snapshot like [`super::UiScript::keybind_snapshot`] rather than a borrow — same
-/// reason: the app holds it across frames while Lua keeps editing the table underneath.
+/// An addon binding's runnable half: what the app's dispatch needs to fire it.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct AddonBindingBody {
-    /// The command name, exactly as registered — what a [`keybind_snapshot`] row is keyed by.
-    ///
-    /// [`keybind_snapshot`]: super::UiScript::keybind_snapshot
+    /// The command name as registered, the key of a `keybind_snapshot` row.
     pub name: String,
     /// Run the body a second time on the release, with `keystate = "up"` (`runOnUp="true"`).
     pub run_on_up: bool,
@@ -68,36 +34,22 @@ pub struct AddonBindingBody {
     pub body: String,
 }
 
-/// A host request queued by Lua: persist the live table as set `1`/`2` (`Save`), on which the
-/// app writes `benilla-config/bindings/…` — and, for `Save(1)` issued while the character set was
-/// active, deletes the character file (the reference's confirmed delete-on-switch); or fire a
-/// named binding's action outright (`Run`).
+/// A host request queued by Lua. `Save(set)` persists set 1 or 2 under `benilla-config/bindings/`;
+/// `Save(1)` also deletes the character set's file.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum KeybindRequest {
     Save(u32),
-    /// `RunBinding("SCREENSHOT")` — run the command's action as if its chord had been pressed.
-    /// It is a *request* rather than something the VM can do itself because a host command's
-    /// action is engine-side by construction (see this module's header): the VM holds the command
-    /// name and its chords, never its body.
+    /// `RunBinding(command)`: the app runs the command's action as if its chord were pressed.
     Run(String),
 }
 
-/// The reference's key-string gate — the whole of `SetBinding`'s refusal (decision 1295), in its
-/// two halves: the alias normalization at the head of `CBindings::SetBinding 0x4b7490`, and the
-/// validator `IsValidBindingKeyString 0x4b7890` it then calls.
-///
-/// `Some` is the string to STORE — upper-cased, because the table's hash and its bucket compare
-/// both fold case (`0x64b3f0` / `0x64a4c0`), so `"shift-w"` and `"SHIFT-W"` are one key. `None` is
-/// the refusal, and it is the *only* one the reference has: no command is ever consulted.
-///
-/// The two halves disagree about case on purpose, and that is verified, not a guess: the alias
-/// compare is case-insensitive, the validator is case-SENSITIVE at all three of its sites
-/// (`0x64a480` → `0x40de80`). So `SetBinding("mousewheelup", …)` answers nil while
-/// `SetBinding("MOUSEWHEELUP", …)` binds — and a *lookup* for either finds it.
+/// `SetBinding`'s only refusal: the alias step of `CBindings::SetBinding` (`0x4b7490`), then
+/// `IsValidBindingKeyString` (`0x4b7890`); no command is consulted. `Some` is the key to store,
+/// upper-cased because the table's hash and compare fold case (`0x64b3f0`, `0x64a4c0`). The alias
+/// step ignores case but the validator does not (`0x64a480`), so `"mousewheelup"` is refused.
 pub fn normalize_binding_key(key: &str) -> Option<String> {
-    // Eleven punctuation NAMES become their literal character. A WHOLE-STRING compare, so
-    // `SHIFT-LEFTBRACKET` is not normalized — and then fails the validator, where the accepted
-    // spelling `SHIFT-[` passes.
+    // Eleven punctuation names become their character on a whole-string match only, so
+    // `SHIFT-LEFTBRACKET` is refused where `SHIFT-[` passes.
     const ALIASES: [(&str, &str); 11] = [
         ("LEFTBRACKET", "["),
         ("RIGHTBRACKET", "]"),
@@ -120,9 +72,7 @@ pub fn normalize_binding_key(key: &str) -> Option<String> {
 
 /// `IsValidBindingKeyString 0x4b7890`, arm for arm.
 fn is_valid_binding_key(key: &str) -> bool {
-    // 1. Strip `SHIFT-`/`CTRL-`/`ALT-` repeatedly — the loop restarts while any matched
-    //    (`0x4b78a0`–`0x4b78d0`), so the validator takes modifiers in ANY order and REPEATED,
-    //    unlike the fixed ALT-CTRL-SHIFT order the chord builder emits.
+    // 1. Modifier prefixes, in any order and any number of times (`0x4b78a0`-`0x4b78d0`).
     let mut rest = key;
     while let Some(next) = ["SHIFT-", "CTRL-", "ALT-"]
         .iter()
@@ -130,14 +80,11 @@ fn is_valid_binding_key(key: &str) -> bool {
     {
         rest = next;
     }
-    // 2. One character passes (`0x41aab0` decode, `0x4b78e6`) — which is how every letter, digit
-    //    and punctuation key is bindable without being named anywhere. The empty string lands in
-    //    the same arm and passes too; `SHIFT-` alone is therefore a legal (unpressable) key.
+    // 2. One character or none passes (`0x4b78e6`): `SHIFT-` alone is a legal key.
     if rest.chars().count() <= 1 {
         return true;
     }
-    // 3. `F`/`NUMPAD`/`BUTTON` (the table at `0x846c04`) followed by digits and nothing else.
-    //    `NUMPADPLUS` falls through here to arm 4, its remainder not being digits.
+    // 3. `F`, `NUMPAD` or `BUTTON` (`0x846c04`) followed by digits only.
     for prefix in ["F", "NUMPAD", "BUTTON"] {
         if let Some(digits) = rest.strip_prefix(prefix) {
             if !digits.is_empty() && digits.bytes().all(|b| b.is_ascii_digit()) {
@@ -145,9 +92,7 @@ fn is_valid_binding_key(key: &str) -> bool {
             }
         }
     }
-    // 4. The 26 names at `0x846c20`…`0x846c84`. `SHIFT`/`CTRL`/`ALT`/`UNKNOWN` are in none of the
-    //    arms, which is why a lone modifier can never be bound — and `SCROLLLOCK`/`PAUSE` are in
-    //    none either, matching the namer that calls their key codes `UNKNOWN` (`0x210`/`0x211`).
+    // 4. The 26 names at `0x846c20`-`0x846c84`: no lone modifier, `SCROLLLOCK` or `PAUSE`.
     const NAMES: [&str; 26] = [
         "SPACE",
         "NUMPADPLUS",
@@ -185,83 +130,49 @@ struct Entry {
     category: String,
     run_on_up: bool,
     defaults: [Option<String>; 2],
-    /// The live bound chords, in bind order (the reference's per-command key list; the first two
-    /// are what `GetBindingKey` and the window's Key 1/Key 2 columns show).
+    /// The live chords in bind order; `GetBindingKey` and the window show the first two.
     keys: Vec<String>,
-    /// `hidden="true"` on an addon's `<Binding>` — bindable, saved and dispatched like any other
-    /// row, but absent from the window's enumeration ([`KeybindState::visible`]). Always `false`
-    /// for a host command: the registry is an honest tree, so there is nothing in it to hide.
+    /// An addon's `hidden="true"`: a full binding, left out of `GetNumBindings`/`GetBinding`.
     hidden: bool,
-    /// An addon binding's Lua chunk; `None` for a host command, whose action is engine-side. This
-    /// is what makes a row an addon's — see the module doc.
+    /// An addon binding's Lua chunk; `None` for a host command, whose action is engine-side.
     body: Option<String>,
 }
 
-/// The table + the stored sets + the Lua→host seams. Lives in [`Model`].
+/// The table, the stored sets and the queued host requests; lives in [`Model`].
 #[derive(Default)]
 pub(crate) struct KeybindState {
     entries: Vec<Entry>,
     by_name: HashMap<String, usize>,
-    /// Saved snapshots: `stored[0]` = account (set 1), `stored[1]` = character (set 2, `None`
-    /// when no character-specific bindings exist). Each is per-entry key lists, entry order.
+    /// Stored sets in entry order: `[0]` account (set 1), `[1]` character (set 2, if any).
     stored: [Option<Vec<Vec<String>>>; 2],
-    /// The same two stored sets **by command name** (decision 1201).
-    ///
-    /// [`Self::stored`] is positional over [`Self::entries`], which is exactly right for the
-    /// commands that exist when a set is seeded and useless for the ones that do not: an addon's
-    /// `Bindings.xml` registers at world entry, long after the account set was seeded at boot, so
-    /// its row in the stored file had no slot to land in and its chord was silently dropped. The
-    /// binding registered, listed in the window, dispatched — and forgot its key every restart
-    /// (the defect 1192 §4 recorded). Keyed by the UPPERCASED name, like `by_name`.
+    /// The same sets by uppercased name, for addon commands registered after the seed.
     stored_by_name: [HashMap<String, Vec<String>>; 2],
-    /// `1` account, `2` character — which set the live table edits (`GetCurrentBindingSet`).
+    /// The set the live table edits (`GetCurrentBindingSet`): 1 account, 2 character.
     current_set: u32,
-    /// Bumped by every live-table mutation and every seed — the app's re-derive-dispatch signal.
+    /// Bumped by every change to the live table: the app's signal to re-derive dispatch.
     generation: u64,
     requests: Vec<KeybindRequest>,
-    /// The Keybindings page's capture arm (`BenillaBindCapture(armed)`): while set, the host
-    /// swallows raw input and calls the page back with the canonical chord string.
+    /// Set by `BenillaBindCapture`: the host swallows raw input and hands the page the chord.
     capture_armed: bool,
 }
 
 impl KeybindState {
-    /// The rows the Key Bindings window enumerates — everything except the `hidden="true"` ones
-    /// (decision 1188 phase 4).
-    ///
-    /// The filter lives at the *Lua enumeration* (`GetNumBindings`/`GetBinding`) rather than at
-    /// registration, because a hidden binding is a real binding everywhere else: `SetBinding` can
-    /// bind it, `GetBindingAction` reports it, the app dispatches it, and the save file carries
-    /// it. That is 1.12's own split — the shipped `Blizzard_BindingUI.lua` filters on nothing but
-    /// the `HEADER` prefix (l.87), so `hidden` can only be the engine's own exclusion from the
-    /// enumeration it walks, and the twelve hidden rows (the debug toggles, `TURNORACTION`,
-    /// `CAMERAORSELECTORMOVE`…) are exactly the ones no 1.12 Key Bindings window shows.
-    ///
-    /// Inert for everything shipped today: no host command is hidden, so the enumeration is
-    /// entry-for-entry what it was before addons could register.
+    /// The rows `GetNumBindings`/`GetBinding` enumerate: all but `hidden="true"`, since the stock
+    /// window skips only `HEADER` rows (`Blizzard_BindingUI.lua:87`).
     fn visible(&self) -> impl Iterator<Item = &Entry> {
         self.entries.iter().filter(|e| !e.hidden)
     }
 
-    /// The reference's `SetBinding(key[, command])`: unbind `key` wherever it is, then (with a
-    /// command) append it to that command's key list.
-    ///
-    /// **The only thing it refuses is a key string that is not a key** (decision 1295). We used to
-    /// refuse a mousewheel chord on a press+release (`runOnUp`) command — the reading everyone
-    /// takes from `Blizzard_BindingUI`'s `if not SetBinding(…) then … KEYBINDINGFRAME_MOUSEWHEEL_
-    /// ERROR`. It is wrong: `CBindings::SetBinding 0x4b7490` never reads a command node at all
-    /// (neither the target's nor the incumbent's), and its one reachable falsey return is the
-    /// validator at `0x4b762c`. `"runOnUp"` has exactly one reader image-wide — `0x4b7bf1`, in
-    /// `RunCommand`, gating the up half. So 1.12 binds the wheel to an action button happily, and
-    /// B265 was ours.
+    /// `SetBinding(key[, command])`: unbind `key` everywhere, then append it to the command's
+    /// list. The reference refuses only an invalid key (`0x4b762c`) and never reads the command
+    /// (`0x4b7490`), so the wheel binds to a `runOnUp` command despite the stock window's
+    /// MOUSEWHEEL_ERROR branch.
     fn set_binding(&mut self, key: &str, command: Option<&str>) -> bool {
         let Some(key) = normalize_binding_key(key) else {
             return false;
         };
-        // The one divergence left here (1295): the reference stores the action string verbatim,
-        // so `SetBinding("K", "NOSUCHCOMMAND")` answers 1 there and nil here. Our table is
-        // command-centric — a key list per registered command — and has nowhere to put a binding
-        // whose command does not exist. Nothing reachable today can hit it: the window offers
-        // only registered rows, and an addon's own names register from its `Bindings.xml`.
+        // Deviation: an unregistered command answers nil where the reference stores the string
+        // and answers 1, because this table only holds key lists of registered commands.
         let cmd_idx = match command {
             Some(name) => match self.by_name.get(&name.to_ascii_uppercase()) {
                 Some(&i) => Some(i),
@@ -279,14 +190,12 @@ impl KeybindState {
         true
     }
 
-    /// Snapshot the live key lists (entry order) — the stored-set payload.
+    /// The live key lists in entry order, as a stored set holds them.
     fn snapshot(&self) -> Vec<Vec<String>> {
         self.entries.iter().map(|e| e.keys.clone()).collect()
     }
 
-    /// Replace the live key lists from a snapshot (entry-count mismatch pads/truncates — a
-    /// stored set from before a command was registered simply leaves the new command on its
-    /// live value).
+    /// Replace the live key lists from a snapshot; an entry past the snapshot's end keeps its keys.
     fn apply(&mut self, snap: &[Vec<String>]) {
         for (i, e) in self.entries.iter_mut().enumerate() {
             if let Some(keys) = snap.get(i) {
@@ -303,10 +212,9 @@ impl KeybindState {
             .collect()
     }
 
-    /// The reference's `LoadBindings(set)`: 0 = defaults, 1 = account, 2 = character (falling
-    /// back to the account snapshot when no character set exists — the reference's character
-    /// set starts as a copy). Loading 1/2 also moves `current_set`; loading defaults does not
-    /// (you are still *editing* the set you had, as in the window's Reset To Default).
+    /// `LoadBindings(set)`: 0 defaults, 1 account, 2 character, which falls back to the account
+    /// set (the reference's starts as a copy). Loading defaults keeps the current set, as the
+    /// window's Reset To Default does.
     fn load(&mut self, set: u32) {
         match set {
             0 => {
@@ -332,9 +240,8 @@ impl KeybindState {
         }
     }
 
-    /// The reference's `SaveBindings(which)`: snapshot live into set `which`, make it current,
-    /// and — saving account while character bindings exist — drop the character set (the
-    /// window's confirmed permanent delete). Queues the host persist.
+    /// `SaveBindings(which)`: store the live table as set `which` and make it current. Saving the
+    /// account set drops the character set, the window's confirmed delete.
     fn save(&mut self, which: u32) {
         if which != 1 && which != 2 {
             return;
@@ -347,45 +254,19 @@ impl KeybindState {
         self.requests.push(KeybindRequest::Save(which));
     }
 
-    /// Append one addon's parsed `Bindings.xml` (decision 1188 phase 4).
-    ///
-    /// **Append-only and idempotent per uppercased name**, exactly like [`super::UiScript::
-    /// register_bindings`] — which is also what makes a host command win outright: `MOVEFORWARD`
-    /// is already in the table when an addon declares it, so the addon's row is skipped and the
-    /// engine's real action keeps the name. Nothing is ever replaced, so an index handed out
-    /// earlier (the dispatch view's, the window's row) stays valid.
-    ///
-    /// **The section carry-forward** is applied here, where the addon's identity is known: a
-    /// `header` attribute opens a section that runs until the next one (the reference's list is
-    /// flat with `HEADER_*` pseudo-entries in it, so 13 headers cover its 228 bindings — and our
-    /// own `SPECS` table already encodes exactly that reading, giving `MOVEBACKWARD` the
-    /// `MOVEMENT` header its `<Binding>` never states).
-    ///
-    /// **A file whose first bindings declare no header at all gets the addon's own name** as
-    /// their section token, and that is a deliberate divergence: the reference would continue
-    /// whatever section the *previous file* ended in, which under our per-entry category (0997's
-    /// era-shaped `GetBinding`) would file an addon's keys under `BINDING_HEADER_CAMERA` and make
-    /// them unfindable. The window renders an unknown token literally
-    /// (`KeyBindings_String(token, token)`), so the section simply reads as the addon's name —
-    /// which is the honest answer to "where did these come from". A declared header keeps the
-    /// ecosystem's convention (`header="MYADDON"` → `BINDING_HEADER_MYADDON`, the global string
-    /// the addon defines in its own Lua).
+    /// Append one addon's parsed `Bindings.xml`, skipping a name already registered, so a host
+    /// command keeps it and no handed-out index moves. A `header` opens a section
+    /// (`BINDING_HEADER_<header>`) until the next one, as in the reference's flat list.
+    /// Deviation: rows before a file's first header take the addon's name as their section, not
+    /// the previous file's, because under a foreign header the player could not find them.
     fn register_addon(&mut self, addon: &str, bindings: &[AddonBinding]) {
         let mut section = addon.to_string();
         for b in bindings {
-            // **`platform` skips the whole NODE, header and all** — `0x4b70c3`-`0x4b70e5` bails
-            // out of the element before anything on it is read. It matters here and nowhere else:
-            // `header="ITUNES_REMOTE"` rides on `ITUNES_PLAYPAUSE`, the first of the five
-            // `platform="mac"` rows, so on a build that is not the Mac one that category does not
-            // merely come up empty — it never exists. Keeping the header of a skipped row would
-            // leave its section open over whatever followed.
+            // A foreign `platform` skips the whole node, header included (`0x4b70c3`-`0x4b70e5`).
             if b.platform.as_deref().is_some_and(|p| p != THIS_PLATFORM) {
                 continue;
             }
-            // Before the duplicate skip below: a duplicate name still *closes* a section the same
-            // way, because the header is a property of the file's order, not of the row that
-            // survived it. (Not the platform case above — a duplicate is a node the loader read
-            // and rejected; a foreign-platform node it never read at all.)
+            // Before the duplicate skip: a duplicate's header still opens its section.
             if let Some(h) = &b.header {
                 section = format!("BINDING_HEADER_{h}");
             }
@@ -394,9 +275,7 @@ impl KeybindState {
                 continue;
             }
             let idx = self.entries.len();
-            // The player's stored chord for this command, if they ever set one (decision 1201).
-            // The CURRENT set first, then the account set behind it — the same precedence `load`
-            // applies, so an addon binding restores exactly like a shipped one.
+            // The stored chord: the current set first, then the account set, as `load` falls back.
             let stored = {
                 let cur = if self.current_set == 2 { 1 } else { 0 };
                 self.stored_by_name[cur]
@@ -409,9 +288,7 @@ impl KeybindState {
                 name: b.name.clone(),
                 category: section.clone(),
                 run_on_up: b.run_on_up,
-                // 1.12's `<Binding>` carries no default chord — the shipped defaults live in the
-                // engine's own table, which is why every addon binding starts unbound and the
-                // player binds it in the window.
+                // 1.12's `<Binding>` carries no default chord.
                 defaults: [None, None],
                 keys: stored.unwrap_or_default(),
                 hidden: b.hidden,
@@ -422,11 +299,8 @@ impl KeybindState {
     }
 }
 
-/// What `platform="…"` has to equal for a binding to register here — the reference's own two
-/// spellings, read out of both binaries: the Windows build compares against `"windows"`
-/// (`0x846f98`, tested at `0x4b70c3`-`0x4b70e5`) and the Mac slice against `"mac"` (`0x4e28f8`).
-/// Every other OS benilla runs on takes the `"windows"` name rather than inventing a third — the
-/// only thing this attribute has ever distinguished is a 2006 Carbon app from everything else.
+/// The `platform="…"` value that registers here: the Windows client compares against `"windows"`
+/// (`0x846f98`), the Mac client against `"mac"` (`0x4e28f8`); every other OS takes `"windows"`.
 const THIS_PLATFORM: &str = if cfg!(target_os = "macos") {
     "mac"
 } else {
@@ -434,8 +308,7 @@ const THIS_PLATFORM: &str = if cfg!(target_os = "macos") {
 };
 
 impl super::UiScript {
-    /// Register the host-implemented commands (boot-time, order = the 1.12 `Bindings.xml`
-    /// order). Idempotent per name; live keys seed from the defaults.
+    /// Register the host's commands at boot, in 1.12 `Bindings.xml` order, keys from the defaults.
     pub fn register_bindings(&mut self, commands: &[KeybindCommand]) {
         let mut model = self.model_mut();
         for c in commands {
@@ -460,25 +333,13 @@ impl super::UiScript {
         model.keybinds.generation += 1;
     }
 
-    /// Register one addon's parsed `Bindings.xml` — the runtime-`String` sibling of
-    /// [`Self::register_bindings`] (decision 1188 phase 4), called at the reference's own position
-    /// in the addon load: after that addon's `.toc` files, before its saved variables
-    /// (`0x51f400`).
-    ///
-    /// Two methods rather than one because the two payloads are genuinely different: a host
-    /// command is `&'static str` all the way down (it names a Rust action and ships default
-    /// chords), an addon's is owned text read off disk this session (it names nothing and carries
-    /// a Lua body). The rules they register under are identical — see
-    /// [`KeybindState::register_addon`].
+    /// Register one addon's parsed `Bindings.xml`, at the reference's point in the addon load:
+    /// after its `.toc` files, before its saved variables (`0x51f400`).
     pub fn register_addon_bindings(&mut self, addon: &str, bindings: &[AddonBinding]) {
         self.model_mut().keybinds.register_addon(addon, bindings);
     }
 
-    /// Every addon-declared binding's runnable half, in registration order — the app's dispatch
-    /// derivation reads this beside [`Self::keybind_snapshot`] and indexes into it.
-    ///
-    /// Host commands are absent by construction (they have no body), which is what lets the app's
-    /// dispatch target be a two-armed enum rather than an index space with a sentinel in it.
+    /// Every addon binding's runnable half, in registration order; host commands have none.
     pub fn addon_binding_bodies(&self) -> Vec<AddonBindingBody> {
         self.model_mut()
             .keybinds
@@ -494,17 +355,12 @@ impl super::UiScript {
             .collect()
     }
 
-    /// Host-side seed of a stored set (`1` account / `2` character) — the loaded
-    /// `benilla-config/bindings/…` state, already resolved to full per-command key lists by the app's
-    /// diff layer. Passing the character set marks it existing (the window's checkbox state);
-    /// `seed_binding_set(2, None)` clears it. Does not touch the live table — call
-    /// [`Self::load_binding_set`] after seeding to activate one.
+    /// Seed stored set 1 (account) or 2 (character) from `benilla-config/bindings/`; `None` clears
+    /// it. The live table is untouched until [`Self::load_binding_set`].
     pub fn seed_binding_set(&mut self, set: u32, keys: Option<Vec<(String, Vec<String>)>>) {
         let mut model = self.model_mut();
         let kb = &mut model.keybinds;
-        // Keep the pairs BY NAME as well as positionally: a command that does not exist yet
-        // (an addon's, registered at world entry) has no position to occupy, and the by-name map
-        // is what `register_addon` consults when it finally does (decision 1201).
+        // By name as well: an addon command registered later has no position yet.
         let mut by_name_owned: HashMap<String, Vec<String>> = HashMap::new();
         let snap = keys.map(|pairs| {
             let by_name: HashMap<_, _> = pairs.into_iter().collect();
@@ -540,8 +396,7 @@ impl super::UiScript {
         self.model_mut().keybinds.load(set);
     }
 
-    /// The live table as `(command, bound chords)` in registration order — the app's dispatch
-    /// derivation and the save diff read this.
+    /// The live table as `(command, chords)` in registration order, for dispatch and the save.
     pub fn keybind_snapshot(&self) -> Vec<(String, Vec<String>)> {
         self.model_mut()
             .keybinds
@@ -551,13 +406,12 @@ impl super::UiScript {
             .collect()
     }
 
-    /// Bumped by every table mutation (Lua or host) — cheap to poll; re-derive dispatch when it
-    /// moves (the macros-generation pattern).
+    /// Bumped by every table change; re-derive dispatch when it moves.
     pub fn keybinds_generation(&self) -> u64 {
         self.model_mut().keybinds.generation
     }
 
-    /// Drain the queued host requests (persist-on-save).
+    /// Drain the queued host requests.
     pub fn take_keybind_requests(&mut self) -> Vec<KeybindRequest> {
         std::mem::take(&mut self.model_mut().keybinds.requests)
     }
@@ -567,23 +421,19 @@ impl super::UiScript {
         self.model_mut().keybinds.current_set
     }
 
-    /// Whether a character-specific stored set exists (the checkbox's persisted truth).
+    /// Whether a character-specific stored set exists (the window's checkbox).
     pub fn character_bindings_exist(&self) -> bool {
         self.model_mut().keybinds.stored[1].is_some()
     }
 
-    /// The Keybindings page's capture arm — while true, the host swallows raw input and
-    /// calls `KeyBindings_OnHostKey("<chord>")` instead of dispatching it.
+    /// While true, the host swallows raw input and calls `KeyBindings_OnHostKey("<chord>")`.
     pub fn bind_capture_armed(&self) -> bool {
         self.model_mut().keybinds.capture_armed
     }
 }
 
-/// Register one addon's parsed `Bindings.xml` from a bare `&Lua` — the `LoadAddOn` path
-/// ([`super::addon::load_addon`]) runs *inside* a Lua binding, synchronously, and has no
-/// [`super::UiScript`] to reach. The exact shape `load_saved_variables` already uses next door,
-/// and for the same reason: both halves of the addon load must do the same thing at the same
-/// position, whichever entered.
+/// Register one addon's `Bindings.xml` from a bare `&Lua`: `LoadAddOn` runs inside a Lua binding
+/// with no `UiScript` to reach.
 pub(crate) fn register_addon_bindings(lua: &Lua, addon: &str, bindings: &[AddonBinding]) {
     lua.app_data_mut::<Model>()
         .expect("model app_data")
@@ -591,12 +441,9 @@ pub(crate) fn register_addon_bindings(lua: &Lua, addon: &str, bindings: &[AddonB
         .register_addon(addon, bindings);
 }
 
-/// Register the binding globals (1.12 names; `GetBinding` returns the era 4-tuple —
-/// command, category token, key1, key2 — the categorized window's shape).
-///
-/// `GetNumBindings`/`GetBinding` walk [`KeybindState::visible`] — the table minus the
-/// `hidden="true"` rows — while every other verb here keys on name or chord and so sees the whole
-/// table (a hidden binding is bindable, saved and dispatched, just not listed).
+/// The binding globals. `GetBinding` returns command, category, key1, key2, which is not 1.12's
+/// shape: 1.12 returns command, key1, key2, with each header a `HEADER_*` row
+/// (`Blizzard_BindingUI.lua:84`). Only `GetNumBindings` and `GetBinding` skip hidden rows.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     lua.globals().set(
         "GetNumBindings",
@@ -633,11 +480,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(if ok { Some(1) } else { None })
         })?,
     )?;
-    // `RunBinding(command)` — the reference's own passthrough verb. Its live caller is
-    // `CinematicFrame`'s `OnKeyDown`, which hands the SCREENSHOT chord back to its binding while
-    // swallowing every other key, so a player can still photograph a fly-by. Anything the VM
-    // holds a body for it could run itself; a host command's action is engine-side, so this
-    // queues and the app fires it in the same frame.
+    // `RunBinding(command)`, as `CinematicFrame.xml:42` passes SCREENSHOT through: a host
+    // command's action is engine-side, so this queues it and the app runs it in the same frame.
     lua.globals().set(
         "RunBinding",
         lua.create_function(|lua, command: String| {
@@ -756,7 +600,7 @@ mod tests {
     fn the_table_reads_like_the_reference() {
         let s = script();
         assert_eq!(s.eval::<usize>("return GetNumBindings()").unwrap(), 3);
-        // Era 4-tuple: command, category token, key1, key2 — defaults seeded live.
+        // Command, category, key1, key2 (not 1.12's three values), the defaults seeded live.
         assert!(s
             .eval::<bool>(
                 r#"local c, cat, k1, k2 = GetBinding(1)
@@ -780,8 +624,7 @@ mod tests {
     fn set_binding_steals_and_refuses_only_a_key_string_that_is_not_a_key() {
         let s = script();
         let g0 = s.keybinds_generation();
-        // Bind W to JUMP: stolen from MOVEFORWARD (its slot 1 empties, UP slides up), appended
-        // to JUMP's list after its defaults.
+        // W leaves MOVEFORWARD (UP slides up) and joins the end of JUMP's list.
         assert!(s
             .eval::<bool>(r#"return SetBinding("W", "JUMP") == 1"#)
             .unwrap());
@@ -794,26 +637,20 @@ mod tests {
             s.eval::<String>(r#"return GetBindingAction("W")"#).unwrap(),
             "JUMP"
         );
-        // Unbind by key: SetBinding(key) with no command.
         s.run(r#"SetBinding("SPACE")"#).unwrap();
         assert_eq!(
             s.eval::<String>(r#"return GetBindingAction("SPACE")"#)
                 .unwrap(),
             ""
         );
-        // **The wheel binds to a press+release command** (B265, decision 1295). This assertion
-        // used to read `== nil`, on the universal misreading of `Blizzard_BindingUI`'s
-        // `if not SetBinding(…) then … KEYBINDINGFRAME_MOUSEWHEEL_ERROR`. `0x4b7490` never looks
-        // at a command node, so 1.12 takes it — and the notch runs both halves.
+        // The wheel binds to a `runOnUp` command: `0x4b7490` never reads the command.
         assert!(s
             .eval::<bool>(r#"return SetBinding("SHIFT-MOUSEWHEELUP", "MOVEFORWARD") == 1"#)
             .unwrap());
         assert!(s
             .eval::<bool>(r#"return SetBinding("MOUSEWHEELDOWN", "CAMERAZOOMIN") == 1"#)
             .unwrap());
-        // The refusal that IS there: `IsValidBindingKeyString 0x4b7890`. A lone modifier, a name
-        // in none of its four arms, and an alias that is not the whole string all fail; the
-        // pure unbind runs the same validator, so it fails on the same strings.
+        // Refused by `IsValidBindingKeyString` (`0x4b7890`), on the pure unbind too.
         for bad in ["SHIFT", "ALT", "UNKNOWN", "SCROLLLOCK", "SHIFT-LEFTBRACKET"] {
             assert!(
                 s.eval::<bool>(&format!(r#"return SetBinding("{bad}", "JUMP") == nil"#))
@@ -826,8 +663,6 @@ mod tests {
                 "{bad} fails the same validator on the pure unbind"
             );
         }
-        // …and the ones that pass: one character (with modifiers in any order and repeated),
-        // F/NUMPAD/BUTTON + digits, the 26 names, and a whole-string punctuation alias.
         for good in [
             "SHIFT-CTRL-ALT-K",
             "CTRL-SHIFT-K",
@@ -852,8 +687,7 @@ mod tests {
             "JUMP",
             "the alias is normalized to its literal character before it is stored"
         );
-        // The validator is case-SENSITIVE where the lookup behind it is not: a lower-case key
-        // string never reaches the table at all.
+        // The validator is case-sensitive: a lower-case key string is refused.
         assert!(s
             .eval::<bool>(r#"return SetBinding("shift-w", "JUMP") == nil"#)
             .unwrap());
@@ -868,52 +702,31 @@ mod tests {
         let mut s = script();
         assert_eq!(s.current_binding_set(), 1);
         assert!(!s.character_bindings_exist());
-        // Rebind, save as character: stored set 2 exists, current set moves.
         s.run(r#"SetBinding("F", "JUMP")"#).unwrap();
         s.run("SaveBindings(2)").unwrap();
         assert_eq!(s.current_binding_set(), 2);
         assert!(s.character_bindings_exist());
         assert_eq!(s.take_keybind_requests(), vec![KeybindRequest::Save(2)]);
-        // Reset To Default: LoadBindings(0) restores defaults but stays on the character set.
+        // Reset To Default keeps the character set current.
         s.run("LoadBindings(0)").unwrap();
         assert_eq!(
             s.eval::<String>(r#"return GetBindingAction("F")"#).unwrap(),
             ""
         );
         assert_eq!(s.current_binding_set(), 2);
-        // Cancel's revert: LoadBindings(current) restores the saved character set.
+        // Cancel reloads the saved character set.
         s.run("LoadBindings(2)").unwrap();
         assert_eq!(
             s.eval::<String>(r#"return GetBindingAction("F")"#).unwrap(),
             "JUMP"
         );
-        // Okay back to general: SaveBindings(1) drops the character set — the confirmed
-        // permanent delete — and the app is asked to persist (and unlink the character file).
+        // Saving the account set drops the character set, the confirmed delete.
         s.run("SaveBindings(1)").unwrap();
         assert_eq!(s.current_binding_set(), 1);
         assert!(!s.character_bindings_exist());
         assert_eq!(s.take_keybind_requests(), vec![KeybindRequest::Save(1)]);
     }
 
-    /// **An addon's `Bindings.xml` becomes ordinary rows** (decision 1188 phase 4) — same table,
-    /// same window, same `SetBinding` laws — with exactly two things that only an addon row has:
-    /// a Lua body, and the `hidden` bit.
-    ///
-    /// What each assertion would catch, since this is the seam a real addon's keys arrive
-    /// through:
-    /// - **the count and the tuple**: a registration that lands somewhere the window cannot see
-    ///   (the whole symptom 1188 phase 4 exists to remove);
-    /// - **the carried header**: a per-row reading of `header`, which would leave 215 of the
-    ///   reference's own 228 bindings in a nameless category, and a doubled `BINDING_HEADER_`
-    ///   prefix if the parser's job were done twice;
-    /// - **the addon-name fallback**: a header-less file whose rows land in whatever section
-    ///   happened to be last — unfindable in the window, which is why we diverge here;
-    /// - **`MOVEFORWARD`**: an addon quietly *replacing* a host command by declaring its name,
-    ///   which would swap a real engine action for a Lua body;
-    /// - **the hidden row**: `hidden="true"` read as "do not register" rather than "do not list",
-    ///   which would make the binding unbindable and undispatchable;
-    /// - **the bodies**: a host row leaking into [`super::UiScript::addon_binding_bodies`], which
-    ///   is what makes the app's dispatch target a two-armed enum instead of a sentinel index.
     #[test]
     fn an_addons_bindings_xml_registers_as_ordinary_rows() {
         let mut s = script();
@@ -935,8 +748,8 @@ mod tests {
             "registration must move the generation — it is the app's re-derive-dispatch signal"
         );
 
-        // Three host commands + the two listable addon rows. `MOVEFORWARD` did not register
-        // twice, and `PROBEHIDDEN` is registered but not listed.
+        // Three host rows and two addon rows: the addon's `MOVEFORWARD` is skipped and
+        // `PROBEHIDDEN` is not listed.
         assert_eq!(s.eval::<usize>("return GetNumBindings()").unwrap(), 5);
         assert!(s
             .eval::<bool>(
@@ -952,14 +765,13 @@ mod tests {
             .unwrap(),
             "a row with no header of its own belongs to the section the last header opened"
         );
-        // The host's own command kept its row, its keys and its engine action.
         assert!(s
             .eval::<bool>(
                 r#"local k1, k2 = GetBindingKey("MOVEFORWARD"); return k1 == "W" and k2 == "UP""#
             )
             .unwrap());
 
-        // The hidden row is absent from the enumeration…
+        // The hidden row is not enumerated, but binds and is found by key.
         assert!(s
             .eval::<bool>(
                 r#"for i = 1, GetNumBindings() do
@@ -968,7 +780,6 @@ mod tests {
                    return true"#
             )
             .unwrap());
-        // …and is a binding in every other respect: bindable, and found by key.
         assert!(s
             .eval::<bool>(r#"return SetBinding("H", "PROBEHIDDEN") == 1"#)
             .unwrap());
@@ -976,8 +787,7 @@ mod tests {
             s.eval::<String>(r#"return GetBindingAction("H")"#).unwrap(),
             "PROBEHIDDEN"
         );
-        // And it rides the same laws: `runOnUp` decides whether the body runs again on the
-        // release, never whether the row may take a wheel chord (1295) — so both bind.
+        // `runOnUp` never refuses a wheel chord.
         assert!(s
             .eval::<bool>(r#"return SetBinding("MOUSEWHEELUP", "PROBEHOLD") == 1"#)
             .unwrap());
@@ -985,7 +795,7 @@ mod tests {
             .eval::<bool>(r#"return SetBinding("MOUSEWHEELDOWN", "PROBEEDGE") == 1"#)
             .unwrap());
 
-        // A second addon, declaring no header at all: its rows are its own section, named for it.
+        // A file with no header: its rows' section is the addon's name.
         let parsed = crate::bindings_xml::parse(
             r#"<Bindings><Binding name="LIBKEY">Lib();</Binding></Bindings>"#,
         )
@@ -997,8 +807,7 @@ mod tests {
             )
             .unwrap());
 
-        // The runnable halves the app's dispatch indexes — addon rows only, in registration
-        // order, hidden included.
+        // Addon rows only, in registration order, hidden included.
         let bodies = s.addon_binding_bodies();
         let names: Vec<&str> = bodies.iter().map(|b| b.name.as_str()).collect();
         assert_eq!(names, ["PROBEHOLD", "PROBEEDGE", "PROBEHIDDEN", "LIBKEY"]);
@@ -1006,11 +815,6 @@ mod tests {
         assert!(bodies[0].body.contains(r#"keystate == "down""#));
     }
 
-    /// **The file's own OS gate.** `platform="mac"` is 1.12's one OS-specific device in
-    /// `Bindings.xml` — five `ITUNES_REMOTE` rows in the Mac build and nowhere else — and a row
-    /// for the other build is not registered at all. Not hidden, not registered-and-inert:
-    /// registering it would list a command in the Key Bindings window whose body calls functions
-    /// this build does not have, and let the player spend a key on it.
     #[test]
     fn a_binding_for_another_platform_does_not_register() {
         let mut s = script();
@@ -1033,7 +837,6 @@ mod tests {
             !names.iter().any(|n| n == "PROBEELSEWHERE"),
             "a foreign-platform row registered: {names:?}"
         );
-        // …and it is not merely hidden from the window either: nothing can bind it.
         assert!(!s
             .addon_binding_bodies()
             .iter()
@@ -1049,8 +852,7 @@ mod tests {
             s.eval::<String>(r#"return GetBindingAction("F")"#).unwrap(),
             "JUMP"
         );
-        // Commands absent from the seed keep their live keys (a stored set from before a
-        // command was registered leaves the new command alone).
+        // A command the seed lacks keeps its live keys.
         assert_eq!(
             s.eval::<String>(r#"return GetBindingAction("W")"#).unwrap(),
             "MOVEFORWARD"
@@ -1083,18 +885,11 @@ mod addon_persistence_tests {
         }
     }
 
-    /// **An addon's binding remembers its key across a restart** — the defect decision 1192 §4
-    /// recorded and left open: "the binding registers, lists, dispatches, and forgets its key."
-    ///
-    /// The shape is the whole point, so it is reproduced literally: at BOOT the stored set is
-    /// seeded while only the host's own commands exist, and the addon's `Bindings.xml` registers
-    /// hours later at world entry. The stored row therefore has no slot to land in, which is why
-    /// the positional snapshot alone could never carry it.
+    /// The stored set is seeded at boot, before the addon's `Bindings.xml` registers at world
+    /// entry, so its row has no position to land in.
     #[test]
     fn an_addon_binding_restores_its_stored_chord_registered_after_the_seed() {
         let mut s = UiScript::new().unwrap();
-        // Boot: the host's commands, then the account set off disk — which already carries the
-        // player's chord for a command that does not exist in this VM yet.
         s.register_bindings(&[KeybindCommand {
             name: "JUMP",
             category: "BINDING_HEADER_MOVEMENT",
@@ -1111,7 +906,6 @@ mod addon_persistence_tests {
         );
         s.load_binding_set(1);
 
-        // World entry: the addon's Bindings.xml registers.
         s.register_addon_bindings("MyAddon", &[binding("MYADDONTOGGLE")]);
 
         let bound = s
@@ -1126,8 +920,6 @@ mod addon_persistence_tests {
         );
     }
 
-    /// A command the stored set says nothing about still registers **unbound**, which is 1.12's
-    /// own rule for an addon binding (its `<Binding>` carries no default chord).
     #[test]
     fn an_addon_binding_with_no_stored_chord_registers_unbound() {
         let mut s = UiScript::new().unwrap();
@@ -1142,8 +934,6 @@ mod addon_persistence_tests {
         assert!(bound.1.is_empty());
     }
 
-    /// The character set wins over the account set for an addon command too — the same precedence
-    /// `load` applies to every other command, so an addon binding restores like a shipped one.
     #[test]
     fn the_character_set_wins_for_an_addon_command() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/keyboard.rs b/crates/benilla-ui/src/script/keyboard.rs
index fb45740e..67a6f303 100644
--- a/crates/benilla-ui/src/script/keyboard.rs
+++ b/crates/benilla-ui/src/script/keyboard.rs
@@ -1,86 +1,35 @@
-//! **Frame keyboard delivery** — the walk, the existence gate, and the key-name argument.
+//! Frame keyboard delivery. One dispatcher per [`Channel`] calls the keyboard-enabled frames in
+//! [`walk_order`] until one consumes. Consumption is the existence of a script slot, not what the
+//! handler does: a key-down consumes on `OnKeyDown` or `OnKeyUp` and fires only `OnKeyDown`, so a
+//! frame with only `OnKeyUp` swallows key-downs and runs nothing; a char consumes on `OnChar`.
+//! Membership is the keyboard-enabled flag (`0x76af00`), never a script: XML `enableKeyboard` and
+//! an XML `<Scripts>` handler set it, Lua `SetScript` does not.
 //!
-//! Until this module, keys went straight to the focused EditBox and a plain frame could not receive
-//! a key at all: `OnChar`/`OnKeyDown`/`OnKeyUp` were the three script names
-//! [`super::object::events_regions`] deliberately *raised* on, because accepting a name this engine
-//! never fires is the silent-drop class 1203/1205/1211 each recorded. This is the machinery that
-//! note was waiting on, so those three names are now accepted there.
+//! The focused EditBox is a frame in the same walk, consuming through its own vtable, so a
+//! keyboard frame in a higher stratum pre-empts it and one in a lower stratum does not. A key no
+//! frame consumes falls through to the editbox routing, focus acquisition included.
 //!
-//! ## The law
-//!
-//! An OS key event reaches **one dispatcher per channel**, and the dispatcher — not the frame — is
-//! what walks: `0x765f10` (key-down, kind-1 buckets, vtable `+0x60`) and `0x765df0` (char, kind-0
-//! buckets, `+0x5c`). Each walks **9 strata records, TOOLTIP (8) down to WORLD (0)**, and within a
-//! record the frame array **index 0 upward**, which the inserter `0x764aa0` keeps ordered by
-//! **level descending, ties oldest-registration-first**. Every frame in that order is *called*
-//! until one returns nonzero; that one **consumes** and both loops stop. So several frames may be
-//! called, at most one consumes.
-//!
-//! **The consumption gate is EXISTENCE, not handling** (`0x76b7d0`/`0x76bba0`/`0x76b760`):
-//!
-//! | slot state | key-down returns | fires |
-//! |---|---|---|
-//! | `OnKeyDown` set | **consume** | `OnKeyDown` |
-//! | only `OnKeyUp` set | **consume** | *nothing* |
-//! | neither | decline | nothing |
-//!
-//! That asymmetry is real and is transcribed below: a frame carrying only an `OnKeyUp` swallows
-//! every key-down and runs no script. `OnChar` gates on its own slot alone; `OnKeyUp` on `+0x190`
-//! alone (no `OnKeyDown` fallback). **A 1.12 handler cannot signal "handled"** — the fire's return
-//! is discarded at all three call sites (`0x7026f0`) — so a Lua handler never influences
-//! consumption.
-//!
-//! **Bucket membership is the keyboard-enabled flag**, never the presence of a script (`0x76af00`):
-//! `EnableKeyboard(true)` on a script-less frame puts it *in* the walk, where it is called and
-//! declines. XML `enableKeyboard` enables both kinds; an XML `<Scripts>` block auto-enables per
-//! handler; **Lua `SetScript` auto-enables nothing**, so a runtime-created frame needs an explicit
-//! `EnableKeyboard(true)` exactly as in the real client.
-//!
-//! ## Where the EditBox sits — it is a participant, not a separate stage
-//!
-//! The reference has no "editbox first" rule: `CSimpleEditBox` is a frame in the same buckets whose
-//! own vtable (`0x77b160` key-down / `0x77a900` char) consumes while focused and never chains to
-//! the base. Modelling it as a stage before or after the walk would get the order wrong whenever a
-//! keyboard frame and the focused box are in different strata — a TOOLTIP-strata frame really does
-//! pre-empt a focused HIGH-strata box, and a WORLD-strata one really does not. So [`walk`] visits
-//! the focused box **at its own strata/level**, handing it to the routing this crate already had
-//! ([`super::editbox`]) and taking a `true` as consumption.
-//!
-//! What is deliberately NOT re-derived here: the box's own focus acquisition (`autoFocus`
-//! self-acquire, click-to-focus, `SetFocus`) stays entirely in `editbox`, and an event no frame
-//! consumed still falls through to it — so every existing routing test holds unchanged.
-//!
-//! ## Not modelled, named
-//!
-//! The **sticky per-key-code key-up slot** (`0x765fd0` routes key-up to `[root+code*4+0x84]`,
-//! the last frame that consumed *some* down for that code, and does **not** clear it on delivery)
-//! is not built: this engine's host feeds no key-up at all today. `OnKeyUp` is therefore accepted,
-//! stored, gated in the table above — and never fired. That is stated rather than hidden, because
-//! its one observable consequence is live: a frame with only an `OnKeyUp` still consumes key-downs.
+//! `OnKeyUp` is stored and gates key-downs but never fires: the host feeds no key-up, so the
+//! reference's key-up gate (`0x76bba0`, `OnKeyUp` alone) and its sticky per-code target
+//! (`0x765fd0`, `[root+code*4+0x84]`, the last frame to consume that code's down) are not built.
 
 use mlua::Lua;
 
 use super::{event, Model};
 use crate::widget::{FrameHandle, FrameKind};
 
-/// Which channel a dispatch is on — the two walks the reference registers separately.
+/// The two walks the reference registers separately.
 #[derive(Clone, Copy, PartialEq, Eq)]
 enum Channel {
-    /// `0x765df0` — kind-0 buckets, vtable `+0x5c`, fires `OnChar` with the literal character.
+    /// `0x765df0`: kind-0 buckets, vtable `+0x5c`, fires `OnChar` with the literal character.
     Char,
-    /// `0x765f10` — kind-1 buckets, vtable `+0x60`, fires `OnKeyDown` with the key NAME.
+    /// `0x765f10`: kind-1 buckets, vtable `+0x60`, fires `OnKeyDown` with the key name.
     KeyDown,
 }
 
-/// The walk order (`0x765f10`): every keyboard-enabled, effectively-visible frame, **strata
-/// descending, then level descending, then oldest registration first**.
-///
-/// Built as a sorted `Vec` per dispatch rather than kept as nine live buckets. The reference
-/// maintains the buckets incrementally because it is walking them on every key at 1.12 frame
-/// budgets; here a key press is a human-rate event and the candidate set is the *keyboard-enabled*
-/// frames only — single digits in any real interface — so an index that must be kept coherent with
-/// every Show/Hide/SetFrameLevel/SetFrameStrata would be pure drift surface for no measurable win.
-/// The ORDER is the law; the storage is ours.
+/// The walk order (`0x765f10`): keyboard-enabled, effectively-visible frames, strata TOOLTIP down
+/// to WORLD, then level descending, ties oldest registration first as the inserter keeps them
+/// (`0x764aa0`).
 fn walk_order(model: &Model) -> Vec<FrameHandle> {
     let mut candidates: Vec<(FrameHandle, u8, u16, u32)> = model
         .arena
@@ -88,38 +37,21 @@ fn walk_order(model: &Model) -> Vec<FrameHandle> {
         .filter(|(_, f)| f.effective_visible && f.keyboard_enabled)
         .map(|(h, f)| (h, f.strata as u8, f.level, f.insertion_seq))
         .collect();
-    // strata DESC, level DESC, insertion ASC — the inserter's own ordering (`0x764aa0`), where a
-    // frame goes before the first entry of strictly lower level and equal levels keep registration
-    // order.
     candidates.sort_by(|a, b| b.1.cmp(&a.1).then(b.2.cmp(&a.2)).then(a.3.cmp(&b.3)));
     candidates.into_iter().map(|(h, ..)| h).collect()
 }
 
-/// Does `frame` have a script bound under `name`?
-///
-/// The existence test the C++ gate performs on `+0x180`/`+0x188`/`+0x190` — asked of the script
-/// registry, which is where this engine keeps those slots.
+/// The gate's existence test on slots `+0x180`/`+0x188`/`+0x190`, kept in the script registry.
 fn has_script(lua: &Lua, id: u32, name: &str) -> bool {
     event::has_widget_handler(lua, id, name)
 }
 
-/// Is `h` a `CSimpleEditBox`?
-///
-/// **A box in the walk is asked about FOCUS, never about a script slot.** Its ctor (`0x779ce8`)
-/// registers it in the kind-0 *and* kind-1 buckets, and its vtable `0x81c910` **replaces** the base
-/// input slots — `+0x5c` → `0x77a900` (char), `+0x60` → `0x77b160` (key-down) — and never chains to
-/// them: there is no `call 0x76b760` anywhere in it, so the generic `OnChar` slot `+0x180` is
-/// unreachable on an editbox. The override's own tail is the decline this predicate exists to
-/// reach:
-/// `0x77a952 cmp esi,eax` — I am the focus owner → insert and consume — else
-/// `0x77a956 xor eax,eax`, **return 0, and the walk continues past me**. `0x77b160` has the same
-/// shape at `0x77b1c7`/`0x77b21e`.
-///
-/// Without this, an unfocused box carrying an XML `<OnChar>` ran the base gate and **ate every
-/// keystroke aimed at its neighbours**: stock `SendMailNameEditBox` has one
-/// (`SendMailFrame_SendeeAutocomplete`) and is the first-registered keyboard frame in the mail
-/// window, so the send tab's subject, body and three money boxes took no input at all — the whole
-/// window typed dead except the one box the handler is on (decision 2145).
+/// Whether `h` is a `CSimpleEditBox`, which the walk asks about focus, never a script slot: its
+/// ctor (`0x779ce8`) puts it in both buckets, and its vtable `0x81c910` replaces the input slots
+/// (`+0x5c` with `0x77a900`, `+0x60` with `0x77b160`) without chaining to the base, consuming
+/// when focused and otherwise declining unless it takes a free focus as `autoFocus`
+/// (`0x77a952`/`0x77a956`, `0x77b1c7`/`0x77b21e`). So an unfocused box's `OnChar` (`+0x180`)
+/// never runs and never eats a neighbour's keys.
 fn is_editbox(lua: &Lua, h: FrameHandle) -> bool {
     let model = lua.app_data_ref::<Model>().expect("model app_data");
     model
@@ -128,19 +60,15 @@ fn is_editbox(lua: &Lua, h: FrameHandle) -> bool {
         .is_some_and(|f| f.kind == FrameKind::EditBox)
 }
 
-/// The dispatcher for one channel — [`Channel`]'s walk, gate and fire, in the reference's order.
-///
-/// Returns whether the event was **consumed**, which is what the caller must use to suppress the
-/// keybinding system: consumption is decided by the C++ existence gate alone, never by what the
-/// Lua handler did or returned (`0x7026f0`).
+/// One channel's walk, gate and fire. Returns whether a frame consumed the event, which is what
+/// suppresses the keybinding; a handler's own return is discarded (`0x7026f0`).
 fn walk(lua: &Lua, channel: Channel, arg: &str) -> bool {
     let order = {
         let model = lua.app_data_ref::<Model>().expect("model app_data");
         walk_order(&model)
     };
     for h in order {
-        // The focused EditBox consumes through its OWN vtable, never the base one — so it is asked
-        // in its walk position and its answer is final for this event.
+        // The focused box answers through its own vtable, at its walk position.
         let is_focused_box = {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             model.focused_editbox == Some(h)
@@ -155,10 +83,9 @@ fn walk(lua: &Lua, channel: Channel, arg: &str) -> bool {
             }
             continue;
         }
-        // Someone else holds the focus (or nothing does and this box is not `autoFocus`): the
-        // override returns 0 and the walk moves on. The base slot is unreachable here — see
-        // [`is_editbox`]. A no-focus self-acquire still happens, at [`super::editbox::route`],
-        // when the whole walk declines.
+        // An unfocused box declines here; the topmost `autoFocus` box takes a free focus in
+        // `super::editbox::route` once the whole walk declines, where the reference's takes it
+        // at its own walk position (`0x77a917`, `0x77b1c7`).
         if is_editbox(lua, h) {
             continue;
         }
@@ -174,7 +101,7 @@ fn walk(lua: &Lua, channel: Channel, arg: &str) -> bool {
                     return true;
                 }
             }
-            // `0x76b7d0`: the OR gate — either key slot consumes, only `OnKeyDown` fires.
+            // `0x76b7d0`: either key slot consumes, only `OnKeyDown` fires.
             Channel::KeyDown => {
                 let down = has_script(lua, id, "OnKeyDown");
                 if down || has_script(lua, id, "OnKeyUp") {
@@ -189,9 +116,8 @@ fn walk(lua: &Lua, channel: Channel, arg: &str) -> bool {
     false
 }
 
-/// Fire one key handler with its single string argument (`0x7026f0(frame, &slot, "%s", str)` — the
-/// argument is a string on all three channels). Errors land in [`Model::errors`] like every other
-/// widget handler; a raising handler must not eat the key press.
+/// Fire one key handler with its one argument, a string on all three channels (`0x7026f0`);
+/// errors are recorded in [`Model::errors`], never raised into the dispatch.
 fn fire(lua: &Lua, id: u32, script: &str, arg: &str) {
     let val = mlua::Value::String(match lua.create_string(arg) {
         Ok(s) => s,
@@ -209,31 +135,21 @@ fn fire(lua: &Lua, id: u32, script: &str, arg: &str) {
     }
 }
 
-/// The char channel (`0x765df0`) — `arg1` is the literal character, UTF-8 (`0x41abb0` encodes the
-/// code with no range guard, so a multi-byte codepoint arrives whole).
+/// The char channel (`0x765df0`): `arg1` is the character in UTF-8, a multi-byte codepoint whole
+/// (`0x41abb0` encodes with no range guard).
 pub(super) fn char_input(lua: &Lua, text: &str) -> bool {
     walk(lua, Channel::Char, text)
 }
 
-/// The key-down channel (`0x765f10`) — `arg1` is the key NAME, with no modifier prefix, from the
-/// same table the keybinding chord uses (`0x76b7d0`, byte-identical to the chord's own
-/// `0x4b66b0`). The host speaks those names already
-/// (`crate::script::UiScript::key_input`'s contract), so no decode happens here.
+/// The key-down channel (`0x765f10`): `arg1` is the key name without modifiers, from the same
+/// table as the keybinding chord (`0x76b7d0`, `0x4b66b0`); the host already speaks those names.
 pub(super) fn key_input(lua: &Lua, key: &str) -> bool {
     walk(lua, Channel::KeyDown, key)
 }
 
-/// The same key-down walk, for the keys this engine delivers to a **focused EditBox as a semantic
-/// [`crate::script::EditAction`] chord** rather than by name — BACKSPACE, DELETE, the arrows, HOME,
-/// END (decision 0301: the host's per-OS keymap owns which chord means what, so the box never sees
-/// these as names).
-///
-/// Those keys still have to reach a keyboard frame — a dialog you type into needs its BACKSPACE —
-/// and the ordering question that creates is real: whoever comes FIRST in the walk owns the key.
-/// So this runs the identical order and **declines at the focused box** rather than skipping past
-/// it: a frame above the box in walk order consumes and fires; a box above the frame ends the walk
-/// with `false`, and the caller then dispatches its chord exactly as before. The one thing this
-/// must never do is let a frame *below* the focused box steal the box's editing keys.
+/// The key-down walk for the editing keys a focused box takes as a [`crate::script::EditAction`]
+/// (BACKSPACE, DELETE, the arrows, HOME, END): a frame above the box consumes them, and the walk
+/// stops at the box with `false` for its chord path, so no frame below it takes them.
 pub(super) fn frame_key_input(lua: &Lua, key: &str) -> bool {
     let order = {
         let model = lua.app_data_ref::<Model>().expect("model app_data");
@@ -243,11 +159,10 @@ pub(super) fn frame_key_input(lua: &Lua, key: &str) -> bool {
         {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             if model.focused_editbox == Some(h) {
-                return false; // the box owns this key; its chord path handles it
+                return false; // the box's chord path owns this key
             }
         }
-        // …and an UNfocused box declines instead of gating on `+0x188`/`+0x190` ([`is_editbox`]),
-        // so it can never steal a neighbour's BACKSPACE either.
+        // An unfocused box declines rather than gating on `+0x188`/`+0x190`.
         if is_editbox(lua, h) {
             continue;
         }
diff --git a/crates/benilla-ui/src/script/layout.rs b/crates/benilla-ui/src/script/layout.rs
index db5a2f26..b8faa294 100644
--- a/crates/benilla-ui/src/script/layout.rs
+++ b/crates/benilla-ui/src/script/layout.rs
@@ -8,52 +8,22 @@ use super::backdrop;
 use super::types::RegionData;
 use super::{ExtractedQuad, MeasureRequest, Model, QuadContent, UiScript, SCREEN};
 
-/// The paint a frame slot's derived quads inherit — its `effective_alpha` and `effective_scale`
-/// travelling together (backdrop pieces and message-frame ring lines are emitted BY the frame,
-/// so they wear the frame's own factors exactly like [`ExtractedQuad::alpha`]/`scale` on the
-/// slot itself).
+/// A frame's `effective_alpha` and `effective_scale`, worn by the quads it emits itself.
 #[derive(Clone, Copy)]
 pub(super) struct FramePaint {
     pub(super) alpha: f32,
     pub(super) scale: f32,
 }
 
-/// A 128-bit rolling fingerprint of everything [`UiScript::resolve_layout`] *reads*, so a resolve
-/// whose inputs are byte-identical to the last one can be skipped outright.
-///
-/// ## Tier 2 of a two-tier gate (decision 0740)
-///
-/// This fingerprint began as the WHOLE gate, chosen over a dirty flag because a flag has sites to
-/// miss and a fingerprint is computed FROM the read set — any change moves it by construction.
-/// That safety cost ~0.6 ms *every idle frame* at a live pin (hashing ~2k inputs to conclude
-/// "quiet"), which is why the mutation epoch ([`Model::touch_layout`], tier 1) now sits in front:
-/// a frame with no layout-visible write skips at a `u64` compare and never reaches this hash. The
-/// fingerprint remains load-bearing where the flag is structurally weak — a *dirty* frame whose
-/// writes were idempotent (the bag-hover re-enter loop clears and rebuilds identical content
-/// every frame; the GameTooltip pre-pass rewrites tooltip sizes every call) hashes clean here and
-/// still skips the solve. And the flag's own failure mode — a missed touch site, a silently stale
-/// layout — is machine-checked: under [`layout_verify_enabled`] (forced on in this crate's tests)
-/// a tier-1-quiet frame asserts the fingerprint agrees, so the tiers police each other.
-///
-/// ## Why 128 bits
-///
-/// A collision here is not self-healing: the skip keeps the stored value, so a colliding change
-/// would stay unresolved until something *else* moved. Two independent lanes put that beyond
-/// physical concern (~2^-128 per frame) at the cost of one extra multiply per item.
-///
-/// ## Order sensitivity is safe
-///
-/// The accumulator is order-dependent, and it is fed by walking `HashMap`s whose iteration order
-/// is arbitrary. That order is nevertheless *stable for an unmutated map*, so an unchanged model
-/// reproduces the value; a mutated map may reorder and merely re-resolves. The failure mode is a
-/// false DIRTY (a wasted resolve), never a false CLEAN (a stale rect).
+/// A 128-bit fingerprint of what [`UiScript::resolve_layout`] reads: tier 2 of the change gate,
+/// behind the mutation epoch ([`Model::touch_layout`]). Two lanes, as a collision keeps a stale
+/// rect; fed in `HashMap` order, stable for an unmutated map, so a reorder only costs a resolve.
 #[derive(Clone, Copy, PartialEq, Eq)]
 pub(crate) struct InputFingerprint(u64, u64);
 
 impl Default for InputFingerprint {
     fn default() -> Self {
-        // Distinct non-zero bases (FNV-1a's, and a 64-bit mix constant) so leading zero-valued
-        // items still move both lanes.
+        // Non-zero bases (FNV-1a's and a mix constant), so leading zeros still move both lanes.
         InputFingerprint(0xcbf2_9ce4_8422_2325, 0x9e37_79b9_7f4a_7c15)
     }
 }
@@ -67,8 +37,7 @@ impl InputFingerprint {
 
     #[inline]
     fn f32(&mut self, v: f32) {
-        // Bit pattern, not value: `resolve` is bit-exact float math, so -0.0 and NaN payloads are
-        // distinctions that matter here even where `==` would call them equal (or unequal).
+        // Bit pattern, not value: the solve is bit-exact, so -0.0 and NaN payloads are distinct.
         self.feed(u64::from(v.to_bits()));
     }
 
@@ -95,9 +64,7 @@ impl InputFingerprint {
         self.f32(i.extent_y);
     }
 
-    /// Collapse to the single `u64` [`LayoutScope`] compares per node. Never [`NO_NODE`]: a
-    /// present node reading as *absent* would be a false CLEAN — the one direction that ships a
-    /// stale rect rather than a wasted resolve.
+    /// The per-node `u64`; never [`NO_NODE`], or a present node would read as absent.
     #[inline]
     fn finish(self) -> u64 {
         let h = self.0 ^ self.1.rotate_left(32);
@@ -117,18 +84,10 @@ impl InputFingerprint {
     }
 }
 
-/// The sentinel in [`LayoutScope::last`]/`now` for "this id was not in that pass's graph". A real
-/// hash colliding with it costs a spurious DIRTY (a node re-solved for nothing), never a stale
-/// rect — the same one-sided failure the fingerprint above is built on.
+/// The sentinel in [`LayoutScope::last`] and `now` for an id not in that pass's graph.
 const NO_NODE: u64 = 0;
 
-/// One FRAME's per-node input hash — [`LayoutScope::last`]'s currency.
-///
-/// Factored out (decision 1388) because two paths now compute it: the full derive, over every
-/// frame, and the incremental pass, over the handful a write named. They must agree *bit for bit* —
-/// a hash that differs by path would read as a change on the frame the paths swap, and (worse) as
-/// no-change on the frame they swap back. One function is the only way to make that true by
-/// construction rather than by matching two listings by eye.
+/// A frame's per-node hash; the full derive and the incremental pass must agree bit for bit.
 #[inline]
 fn frame_node_hash(input: &LayoutInput, over: Option<Anchor>) -> u64 {
     let mut node = InputFingerprint::default();
@@ -140,8 +99,7 @@ fn frame_node_hash(input: &LayoutInput, over: Option<Anchor>) -> u64 {
     node.finish()
 }
 
-/// One REGION's per-node input hash — [`frame_node_hash`]'s twin, over the three things the sweep
-/// reads out of `RegionData`: its anchors, its explicit size, and its measured text extent.
+/// A region's per-node input hash: its anchors, explicit size and measured text extent.
 #[inline]
 fn region_node_hash(data: &RegionData) -> u64 {
     let mut node = InputFingerprint::default();
@@ -160,11 +118,8 @@ fn region_node_hash(data: &RegionData) -> u64 {
         }
         None => node.feed(u64::MAX),
     }
-    // **The ART, on a region whose rect is derived from it** (decision 1349): an axis authored `0`
-    // takes its span from the content ([`content_span`]), so swapping the texture on such a region
-    // MOVES it and the node must re-hash. Fed only on that shape — a sized region's art cannot
-    // change its rect, and hashing every icon path would put a string walk in the derive's hot loop
-    // for a fact with no reader.
+    // The art, only where an axis authored 0 takes its span from it (`content_span`): a new
+    // texture moves such a region, while a sized region's art cannot move its rect.
     if !data.anchors.is_empty() && data.size.is_none_or(|(w, h)| w == 0.0 || h == 0.0) {
         node.feed(data.fill.is_some() as u64);
         match &data.texture {
@@ -180,24 +135,10 @@ fn region_node_hash(data: &RegionData) -> u64 {
     node.finish()
 }
 
-/// A region's **content-derived span**, in FrameXML units — the client's virtual size getters,
-/// which the resolver calls instead of reading a stored width/height (decision 1349).
-///
-/// `CSimpleTexture::GetWidth 0x770720` returns the authored value only when it is **not exactly
-/// `0.0`**; on `0.0` with a texture loaded it returns the texture's own texel extent, through
-/// bit-for-bit the same converter the `<AbsDimension>` attribute uses — so **one texel is one
-/// FrameXML unit, at every aspect ratio**. `0x770790` is the identical body for height. The
-/// colour form generates an **8×8** surface (`0x770360` → `0x44a900` stamps
-/// `[tex+0x144] = [tex+0x148] = 8`), so a `<Color>`-only texture spans 8 units.
-///
-/// `None` = nothing to measure (no art, or no host oracle to measure it with), and the caller
-/// leaves the axis at zero — which is the client's answer too when a texture has no `CGxTex*`
-/// at all.
-///
-/// This is the TEXTURE half. A `CSimpleFontString`'s span is derived the same way and lives in
-/// the sweep itself, because it needs the measure the sweep already folds in
-/// ([`FONTSTRING_MIN_SPAN`]). Between them they are what let the owner-edge fallback go
-/// (decision 1664): a region's span comes from its content, never from the frame it hangs on.
+/// A texture's content-derived span in FrameXML units. `CSimpleTexture::GetWidth` (`0x770720`,
+/// height `0x770790`) returns the authored value unless it is exactly 0.0, else the texel extent
+/// through the `<AbsDimension>` converter, so one texel is one unit; a `<Color>` texture spans 8.
+/// `None` when there is nothing to measure: the axis stays 0, as in the reference with no texture.
 pub(super) fn content_span(
     data: &RegionData,
     probe: Option<&crate::script::TextureSizeProbe>,
@@ -208,9 +149,7 @@ pub(super) fn content_span(
     texel_span(probe, data.texture.as_deref()?)
 }
 
-/// [`content_span`]'s texture arm, for a caller holding a path rather than a region — the
-/// SimpleHTML flow reservation, which asks the reference's `GetHeight` override the same way
-/// (`0x770790`).
+/// [`content_span`] for a path: SimpleHTML reserves an image's height the same way (`0x770790`).
 pub(super) fn texel_span(
     probe: Option<&crate::script::TextureSizeProbe>,
     path: &str,
@@ -219,116 +158,61 @@ pub(super) fn texel_span(
     Some((w as f32, h as f32))
 }
 
-/// The edge of the surface `CSimpleTexture::SetTexture(const CImVector*)` generates for the colour
-/// form — 64 texels, `0x44a900` stamping `[tex+0x144] = [tex+0x148] = 8` (decision 1349 §1).
+/// The edge of the 8×8 surface the colour `SetTexture` makes (`0x770360`, sized by `0x44a900`).
 const SOLID_TEXTURE_TEXELS: f32 = 8.0;
 
-/// The floor under a **FontString's** derived span, in FrameXML units —
-/// `CSimpleFontString::GetWidth 0x772930` / `GetHeight 0x772a60` end
-/// `fld 1-unit; fcomp candidate; test ah,0x5; jp` and return the floor when the candidate is
-/// smaller. One unit,
-/// not one line: the reference's own blank tooltip spacer is `" \n"` — a real one-line string —
-/// and this floor is what a *genuinely* empty string reads back as, never `0.0`.
+/// The floor under a FontString's derived span: `CSimpleFontString::GetWidth` (`0x772930`, height
+/// `0x772a60`) returns at least one FrameXML unit, not one line, so empty text reads back 1, not 0.
 pub(super) const FONTSTRING_MIN_SPAN: f32 = 1.0;
 
-/// [`LayoutScope::node_of`] holds one roster index per id, and the two rosters are separate
-/// (`plan` for frames, `regions` for regions) — this bit says which one. Node counts run in the
-/// thousands, so the top bit is free forever.
+/// Marks a [`LayoutScope::node_of`] index as one into `regions` rather than `plan`.
 const REGION_TAG: u32 = 0x8000_0000;
 
-/// Per-node layout scope — the state that lets a resolve touch only what MOVED (decision 1350,
-/// the phase 2 decision 0771 left open).
-///
-/// 0771 halved the per-content-change cost by folding two whole-UI solves into one; it also said
-/// plainly that halving it was not fixing it, because *one* solve is still a fixpoint over every
-/// frame and every region for a change that touches ten FontStrings inside one frame. Two later
-/// correctness fixes then tripled what a region costs — `0dd6a559a` (a region whose owner has no
-/// rect resolves from its own anchors) and 1310 (every anchor-less Texture/FontString gets
-/// implicit anchors at creation) each moved a large population out of the sweep's cheap
-/// `continue` and into full resolution. Neither is wrong; both are why the whole-UI shape had to
-/// go.
-///
-/// Everything here is indexed **densely by layout id** — frames and regions are minted from one
-/// monotonic counter (`Model::next_id`), so a single array covers both, and the solver's own rect
-/// array is indexed the same way.
-///
-/// Nothing in here allocates on a steady frame: every buffer is resized once and refilled.
+/// Per-node layout scope, so a resolve touches only what moved. Indexed densely by layout id, as
+/// frames and regions share one counter (`Model::next_id`); nothing allocates on a steady frame.
 #[derive(Default)]
 pub(crate) struct LayoutScope {
-    /// Per id: the input hash the last CONVERGED resolve saw, [`NO_NODE`] if the id was not in
-    /// that graph. A mismatch is a dirty SEED — and a birth is a mismatch for free.
+    /// Per id: the hash the last converged resolve saw, or [`NO_NODE`]; a mismatch seeds dirty.
     last: Vec<u64>,
-    /// How many ids `last` holds a real hash for. Compared against how many of THIS pass's nodes
-    /// were also in the last graph: a shortfall means a node DIED, whose dependents we can no
-    /// longer enumerate (its edges died with it), so that pass falls back to full scope.
+    /// How many ids `last` holds a hash for; a pass matching fewer lost a node: full scope.
     last_count: usize,
-    /// The screen rect the `last` set was hashed under. It is every clamped frame's extent and the
-    /// root of every chain, so a move is a full-scope event.
+    /// The screen `last` was hashed under, every chain's root, so a move is full scope.
     last_screen: Option<Rect>,
     /// This pass's hash per id (parallel to `last`); swapped into `last` on convergence.
     now: Vec<u64>,
     /// Per id: index into this pass's node roster, or [`u32::MAX`].
     node_of: Vec<u32>,
-    /// Per id: head index into `dep_to`/`dep_next` of the nodes that DEPEND on it, or
-    /// [`u32::MAX`]. An intrusive list rather than a CSR so the edges are built in one walk.
+    /// Per id: the head of its dependents' list in `dep_to`/`dep_next`, or [`u32::MAX`].
     dep_head: Vec<u32>,
     dep_to: Vec<u32>,
     dep_next: Vec<u32>,
-    /// Edge slots freed by [`Self::retarget`], for [`Self::edge`] to reuse. Without it a session
-    /// of hovers would grow `dep_to` by one entry per retarget forever — bounded only by the next
-    /// full derivation, which is exactly the event retargeting exists to avoid.
+    /// Edge slots [`Self::retarget`] freed, for [`Self::edge`] to reuse rather than grow `dep_to`.
     dep_free: Vec<u32>,
     /// Per id: in the dirty closure.
     dirty: Vec<bool>,
     /// The closure's worklist.
     stack: Vec<u32>,
-    /// The frame roster this cached graph describes: `(handle, id, ScrollFrame anchor override)`,
-    /// indexed by [`Self::node_of`] (decision 1388).
-    ///
-    /// It holds no borrow of `layout_inputs`, and that is the whole point. The borrowed form 1350
-    /// introduced had to be rebuilt every call, which forced the *derivation* — the ids walk, the
-    /// scroll map, the liveness retain, and the two hash sweeps — to be rebuilt with it: ~1.5 ms of
-    /// whole-roster work per mutated frame, whatever moved. Owning the row instead lets the roster
-    /// outlive the call, and the `layout_inputs` probe it replaces moves to the round loop, where it
-    /// is paid once per frame *this solve actually touches* instead of once per frame in the UI.
+    /// The cached frame roster, `(handle, id, ScrollFrame anchor override)`, kept across resolves.
     plan: Vec<(FrameHandle, u32, Option<Anchor>)>,
-    /// The anchored-region roster — [`Self::plan`]'s twin, and the bigger of the two by a factor of
-    /// three (10,438 anchored regions against 3,218 frames at the Stormwind pin).
+    /// The cached roster of live, anchored regions.
     regions: Vec<RegionRow>,
-    /// An incremental pass's staged [`Self::last`] writes, `(id, hash)`. Applied only on
-    /// convergence, for the reason [`Self::commit`] is: a pass left mid-flight describes a graph
-    /// that never settled, and adopting its hashes would seed the next pass's
-    /// "unchanged ⇒ unmoved" argument from a lie.
+    /// An incremental pass's `(id, hash)` writes to [`Self::last`], applied only on convergence.
     staged: Vec<(u32, u64)>,
 }
 
-/// One anchored, live region as the round loop consumes it — resolved ONCE per *derivation*
-/// instead of re-derived per call (decision 1350) or per round (before it). Before this list the
-/// sweep walked `region_data` itself every round and paid, per region per round, an `arena.region`
-/// probe for liveness/owner/kind and a `region_to_id` probe to publish the result — and it paid
-/// them for the anchor-less entries too, which it then `continue`d past.
-///
-/// It is also the addressable form the scope needs: a dirty set is a list of INDICES into this,
-/// and "sweep only what moved" is `for &i in sweep { … regions[i] … }`.
-///
-/// 1388 took the `&RegionData` borrow back out of it, which is what lets the roster outlive the
-/// call that built it. The sweep re-probes `region_data` for that half — one lookup per region
-/// *swept* rather than one per region in the UI.
+/// One live, anchored region as the round loop consumes it, built once per derivation.
 #[derive(Clone, Copy)]
 struct RegionRow {
     rh: RegionHandle,
-    /// The layout id — the solver's dense array index, and the scope's node key.
+    /// The layout id: the solver's array index and the scope's node key.
     id: u32,
-    /// The owning frame: supplies the fallback edges for the axes this region's own anchors do
-    /// not pin, and is therefore a layout DEPENDENCY of it.
+    /// The owning frame, which supplies the region's scale and so is a layout dependency.
     owner: FrameHandle,
     is_fontstring: bool,
 }
 
 impl LayoutScope {
-    /// Grow every per-id array to cover `n` ids and reset the per-pass ones, ahead of deriving the
-    /// graph from scratch. `last` keeps its contents (it is the memory of the previous converged
-    /// pass); everything else — the roster, the edges, `node_of` — is about to be rebuilt.
+    /// Size the per-id arrays for `n` ids and clear all but `last`, ahead of a full derivation.
     fn begin_full(&mut self, n: usize) {
         self.last.resize(n, NO_NODE);
         self.now.clear();
@@ -348,10 +232,7 @@ impl LayoutScope {
         self.staged.clear();
     }
 
-    /// The incremental entry (decision 1388): the roster, the edges and `node_of` ARE the cached
-    /// graph and must survive; only the per-pass dirty marks are scratch. This is the whole saving
-    /// — `begin_full`'s six resizes and the four whole-roster walks that refill them are what a
-    /// mutated frame used to pay to rediscover a graph that had not changed shape.
+    /// The incremental entry: the cached graph survives, and only the dirty marks reset.
     fn begin_incremental(&mut self) {
         self.dirty.clear();
         self.dirty.resize(self.node_of.len(), false);
@@ -359,21 +240,18 @@ impl LayoutScope {
         self.staged.clear();
     }
 
-    /// Is `id` a node of the cached graph? The precondition every precise touch site
-    /// ([`Model::touch_layout_region`]) has to satisfy before it may name a node instead of
-    /// invalidating the cache.
+    /// Whether `id` is a node of the cached graph, the only kind a precise touch may name.
     pub(crate) fn has_node(&self, id: u32) -> bool {
         self.node_of
             .get(id as usize)
             .is_some_and(|&n| n != u32::MAX)
     }
 
-    /// Record that node `from` reads `to`'s rect — so a change at `to` reaches `from`.
+    /// Record that node `from` reads `to`'s rect, so a change at `to` reaches `from`.
     #[inline]
     fn edge(&mut self, from: u32, to: u32) {
         let Some(head) = self.dep_head.get_mut(to as usize) else {
-            return; // an anchor to an id this pass has no node for (the screen root, a dead
-                    // target): it cannot become dirty, so it constrains nothing.
+            return; // an id with no slot can never turn dirty, so it constrains nothing
         };
         let e = match self.dep_free.pop() {
             Some(e) => {
@@ -391,31 +269,9 @@ impl LayoutScope {
         *head = e;
     }
 
-    /// Re-point node `id`'s outgoing edges after an anchor RETARGET — the write 1388 had to
-    /// classify as structural and answer with a whole-graph derivation.
-    ///
-    /// 1388's reasoning was that "an edge has to disappear and another to appear, and no per-node
-    /// hash can say so, so the cached graph must be thrown away". The first half is true and the
-    /// second does not follow: the write site knows both edge sets, because a node's outgoing
-    /// edges ARE its anchor targets (see the derive's two `scope.edge` loops). What it could not
-    /// do was *say* so — this is the vocabulary that was missing, not a cost that was unavoidable.
-    ///
-    /// It matters because the hottest retarget in the client is `GameTooltip:SetOwner`, which
-    /// re-points the plate at the button under the cursor: every bag slot and every spellbook
-    /// button crossed in a hover sweep was re-deriving the whole roster.
-    ///
-    /// `old`/`new` are the node's FULL anchor-target lists, before and after the write — not the
-    /// one that moved. That is what makes duplicates exact: a node with two anchors onto the same
-    /// target has two edges, and removing one per old entry leaves precisely the right count.
-    ///
-    /// Returns `false` when it cannot do this safely and the caller must fall back to the
-    /// conservative touch. Removing an edge is the only direction that can be WRONG (a missing
-    /// edge under-dirties, and under-dirtying ships a stale rect), so every uncertainty is
-    /// resolved by refusing: an id the cached graph has no node for, or a frame whose edges come
-    /// from a ScrollFrame override rather than from its own anchors (the derive does not consult
-    /// the authored anchors at all in that case). An old target with no edge to remove is NOT an
-    /// uncertainty — `edge` silently drops an anchor onto an id this pass has no node for, so its
-    /// absence is the expected shape, and skipping it removes nothing that exists.
+    /// Re-point node `id`'s outgoing edges after an anchor retarget. `old` and `new` are its full
+    /// anchor-target lists, so duplicate anchors stay exact. `false` means a conservative touch:
+    /// `id` has no node, or a ScrollFrame override, not its anchors, supplies its edges.
     pub(crate) fn retarget(&mut self, id: u32, old: &[u32], new: &[u32]) -> bool {
         let Some(&n) = self.node_of.get(id as usize) else {
             return false;
@@ -435,9 +291,7 @@ impl LayoutScope {
         true
     }
 
-    /// Unlink ONE `to → from` edge, if the list holds one. The lists are short by construction
-    /// (a node's dependents), and even a hub's is walked in microseconds against the ~1.3 ms
-    /// derivation this is replacing, so no bound is imposed on the walk.
+    /// Unlink one `to → from` edge, if the list holds one.
     fn unlink_edge(&mut self, to: u32, from: u32) {
         let Some(&head) = self.dep_head.get(to as usize) else {
             return;
@@ -471,8 +325,7 @@ impl LayoutScope {
         }
     }
 
-    /// Close the dirty set under "depends on": everything that reads a dirty node's rect, and
-    /// everything that reads *those*, must resolve again too.
+    /// Close the dirty set under "depends on": whatever reads a dirty rect, transitively.
     fn close(&mut self) {
         while let Some(id) = self.stack.pop() {
             let mut e = self.dep_head[id as usize];
@@ -484,8 +337,7 @@ impl LayoutScope {
         }
     }
 
-    /// Everything present is dirty — the fallback for the structural cases a per-node diff cannot
-    /// speak about (a death, a screen move, the first pass, a graph left mid-flight by a cycle).
+    /// Mark every node dirty, for what a per-node diff cannot see (a death, a screen move).
     fn dirty_all(&mut self) {
         for (id, &n) in self.node_of.iter().enumerate() {
             if n != u32::MAX {
@@ -501,11 +353,8 @@ impl LayoutScope {
         self.last_screen = Some(screen);
     }
 
-    /// [`Self::commit`] for an incremental pass: only the nodes it re-hashed moved, so only their
-    /// slots in `last` are rewritten. `last_count` and `last_screen` are untouched by
-    /// construction — a node entering or leaving the graph, and the screen moving, are structural
-    /// events, and a structural event never reaches this path (it lands in the conservative
-    /// `Model::layout_touched = None`).
+    /// [`Self::commit`] for an incremental pass: only the re-hashed slots. `last_count` and
+    /// `last_screen` stay, since a structural change always takes the full path.
     fn commit_incremental(&mut self) {
         for &(id, h) in &self.staged {
             self.last[id as usize] = h;
@@ -513,15 +362,12 @@ impl LayoutScope {
         self.staged.clear();
     }
 
-    /// Forget it: the next resolve must derive the graph and run in full scope. Called wherever a
-    /// pass leaves the rects mid-flight (the cycle bail), because the memory would then describe a
-    /// graph that never settled.
+    /// Forget the memory, so the next resolve derives the graph in full scope.
     pub(crate) fn invalidate(&mut self) {
         self.last_count = 0;
         self.last_screen = None;
         self.last.clear();
-        // The roster and `node_of` go with it: `has_node` is the precise touch sites' licence to
-        // name a node, and it must not outlive the memory that makes naming meaningful.
+        // The roster and `node_of` too: `has_node` must not vouch for a node the memory forgot.
         self.plan.clear();
         self.regions.clear();
         self.node_of.clear();
@@ -529,73 +375,45 @@ impl LayoutScope {
     }
 }
 
-/// `WOW_LAYOUT_VERIFY=1` — the change gate's self-check (decision 0022's instruments-first
-/// posture). When set, a resolve the gate wants to SKIP runs in full anyway and asserts it
-/// reproduced the previous rects exactly; a divergence means the fingerprint's read set is
-/// incomplete, and it fails loudly at the resolve that proves it rather than silently rendering a
-/// stale frame days later. It also checks tier 1 against tier 2: a frame the epoch judged quiet
-/// whose fingerprint nevertheless moved names a mutation path missing its `touch_layout()`.
-///
-/// This is what makes the gates' central claims — "the fingerprint covers everything the rounds
-/// read" and "every fingerprint-visible write bumps the epoch" — machine-checked instead of
-/// argued: it is FORCED ON for this crate's own tests, so every UI test (the shipped windows,
-/// driven through real FrameXML + Lua) is a standing probe for a missed input or a missed touch;
-/// set the env to extend that to a live run or another crate's suite. Read once; when off it
-/// costs a relaxed atomic load per resolve.
-/// `WOW_LAYOUT_PROF=1` — per-solve shape reporting (see the read site in [`UiScript::resolve_layout`]).
-/// Read once; off, it costs one relaxed atomic load per resolve and no clock reads at all.
+/// `WOW_LAYOUT_PROF=1`: the per-solve `[layout-prof]` and `[layout-pre]` lines on stderr.
 fn layout_prof_enabled() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var("WOW_LAYOUT_PROF").as_deref() == Ok("1"))
 }
 
+/// `WOW_LAYOUT_VERIFY=1`, on in this crate's tests: every shortcut of the resolve (a gate skip, a
+/// tier-1-quiet frame, an incremental pass, the measure ledger) is checked against the full answer.
 fn layout_verify_enabled() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| cfg!(test) || std::env::var("WOW_LAYOUT_VERIFY").as_deref() == Ok("1"))
 }
 
-/// `WOW_LAYOUT_PROF=1`'s **preamble** split — the `[layout-pre]` line, one per LET-THROUGH resolve.
-///
-/// `[layout-prof]` reports the rounds, which 1350 already made proportional to what moved. This
-/// reports everything *before* them: the fixed whole-roster work every let-through solve pays
-/// whatever moved, which 1383 priced at ~1.9 ms/solve at a live roster and named as the next cut
-/// without ever splitting it. A cut needs to know which of the eight walks it is buying back, so
-/// the split is the instrument that has to exist first.
-///
-/// Off (the default) it takes no clock reads at all — [`Self::lap`] returns on the `on` test, so an
-/// unprofiled resolve pays one bool check per phase.
+/// `WOW_LAYOUT_PROF=1`'s `[layout-pre]` line: µs per preamble phase, per resolve past tier 1.
 #[derive(Default)]
 struct PreambleProf {
     on: bool,
     last: Option<std::time::Instant>,
-    /// The GameTooltip auto-size pre-pass (`layout_tooltips`) — a whole-frame-roster filter.
+    /// The GameTooltip auto-size pre-pass (`layout_tooltips`).
     tooltip: u128,
-    /// `OnSizeChanged`'s "before" snapshot — a whole-`scripts`-map filter.
+    /// `OnSizeChanged`'s "before" snapshot.
     watched: u128,
-    /// The ids rebuild + the per-frame scale/clamp sync into `layout_inputs`.
+    /// The ids rebuild and the scale and clamp sync into `layout_inputs`.
     ids: u128,
-    /// The ScrollFrame override map — another whole-frame-roster walk.
+    /// The ScrollFrame override map.
     scroll: u128,
     /// `region_resolved`'s liveness retain.
     retain: u128,
-    /// The per-call solve plan rebuild.
+    /// Never set, so always 0: the frame roster is built inside `fp_frames`.
     plan: u128,
-    /// `LayoutScope::begin` — seven per-id `Vec`s cleared/resized.
+    /// `LayoutScope::begin_full`.
     begin: u128,
-    /// The fingerprint + scope walk over every live FRAME (double-hashed: aggregate + per-node).
+    /// The fingerprint and scope walk over every live frame.
     fp_frames: u128,
-    /// The same over every anchored REGION — the biggest roster (10,438 anchored at the SW pin,
-    /// and by far the biggest single phase: 0.45–1.0 ms of the ~1.0–1.4 ms walk).
+    /// The same over every anchored region.
     fp_regions: u128,
-    /// The INCREMENTAL pass's whole preamble (decision 1388): re-hash the nodes the ledger named,
-    /// seed the ones that moved, close. Every phase above is zero on such a pass, and this is what
-    /// replaced them — read the two side by side to see what a derivation costs.
+    /// An incremental pass's whole preamble: re-hash the named nodes, seed the moved ones, close.
     seed: u128,
-    /// Was this an incremental pass? Reported as its own flag rather than inferred from
-    /// `seed != 0`, which is what it was first written as — and which read `incr=0` on every
-    /// incremental frame of the shipped UI, because the work it times rounds to under a
-    /// microsecond. An instrument that says "this never happens" about the path it was built to
-    /// measure is worse than no instrument.
+    /// A flag of its own, since `seed` rounds to 0 µs on most incremental passes.
     incremental: bool,
 }
 
@@ -619,9 +437,7 @@ impl PreambleProf {
             .map_or(0, |t| now.duration_since(t).as_micros())
     }
 
-    /// One line per let-through resolve, printed once the gate's verdict is known — `skips=1` is
-    /// the walk that concluded "nothing moved" and returns without solving, which costs the same
-    /// preamble as one that does.
+    /// Print the line once the gate's verdict is known; `skips=1` returned without solving.
     fn report(&self, skips: bool, frames: usize, regions: usize) {
         if !self.on {
             return;
@@ -656,17 +472,10 @@ impl PreambleProf {
     }
 }
 
-/// `OnSizeChanged`'s "after": turn the entry-vs-now diff of the watched frames into queued
-/// `(id, width, height)` fires ([`Model::pending_size_changed`]).
-///
-/// The gate is [`crate::layout::size_changed`] — the byte-verified `ApplyRect 0x76b580` test
-/// (`|Δwidth| ≥ ε ∨ |Δheight| ≥ ε`, `ε = _DAT_008029d4`), not a plain `!=`, so a rect that merely
-/// *moved* never fires and a sub-ε float wobble never does either.
-///
-/// A frame with no rect at entry is compared against the ZERO rect, which is the client's own
-/// starting state (`CSimpleFrame`'s ctor zeroes the cached rect, so the first `ApplyRect` is a
-/// 0×0 → w×h change and does fire). A frame that LOSES its rect queues nothing: no rect was
-/// applied, so the reference had no `ApplyRect` to fire from.
+/// `OnSizeChanged`'s "after": queue `(id, width, height)` for each watched frame whose size moved
+/// by the `ApplyRect 0x76b580` test ([`crate::layout::size_changed`], `ε = _DAT_008029d4`), so a
+/// pure move never fires. A frame with no rect at entry compares against the zero rect
+/// `CSimpleFrame`'s ctor leaves; one that loses its rect had no `ApplyRect` and fires nothing.
 fn queue_size_changes(
     watched: &[(FrameHandle, Option<Rect>)],
     resolved: &HashMap<FrameHandle, Rect>,
@@ -689,40 +498,19 @@ fn queue_size_changes(
 }
 
 impl UiScript {
-    /// [`UiScript::resolve`]'s body, taking `&mut Model` directly rather than `&mut self` — so a
-    /// Lua binding holding only a `Model` borrow (via `lua.app_data_mut`, no `&Lua`-wrapping
-    /// `UiScript` in scope) can force a fresh resolve too. [`scrollframe`]'s `UpdateScrollChildRect`
-    /// is the motivating caller: it fires `OnScrollRangeChanged` with the CURRENT range, but
-    /// "current" was a lie for its own primary use (the Era idiom of resize-then-notify in one
-    /// script tick) as long as it only read the LAST full [`UiScript::resolve`]'s cached rects —
-    /// those don't yet reflect a `SetHeight` earlier in the SAME tick (Lua runs before the app's own
-    /// per-frame `resolve()`, `ui_script/mod.rs`'s drive loop), so the fired range was one tick
-    /// stale on every "just resized, tell the scrollbar" call — precisely when a caller most needs
-    /// it fresh. Cheap to call on demand: the fixpoint early-exits in one round on a quiet graph
-    /// (this function's own doc).
+    /// [`UiScript::resolve`]'s body on a bare `Model`, so a Lua binding can force a fresh resolve,
+    /// as `UpdateScrollChildRect` must report a range reflecting a same-tick `SetHeight`.
     pub(super) fn resolve_layout(model: &mut Model) {
         Self::resolve_layout_inner(model);
         if !model.layout_verify_recheck {
             return;
         }
-        // ── `WOW_LAYOUT_VERIFY`: the incremental pass's falsifier (decision 1388) ─────────────
-        // The pass just taken seeded its dirty closure from a LEDGER of named nodes rather than
-        // from a fresh derivation, and it reused a roster and an edge set built some frames ago.
-        // Two things can be wrong with that and neither is visible from inside it: a write that
-        // moved a node's inputs without naming it, and a write that changed an anchor's TARGET
-        // while claiming to be value-only (which leaves the edges describing a graph that no
-        // longer exists). Both ship a stale rect, silently, days later.
-        //
-        // So: re-run the same frame from scratch — no ledger, no cache, full scope — and require
-        // the rects to be identical. That subsumes both failure modes and every one we have not
-        // thought of, because it compares the ANSWER rather than the reasoning. It is forced on
-        // for this crate's tests, which drive the real shipped FrameXML, so every UI test is a
-        // standing probe for a mis-migrated touch site.
+        // ── `WOW_LAYOUT_VERIFY`: the incremental pass's falsifier ─────────────
+        // Re-run the frame from scratch and require identical rects: this catches a write that
+        // moved a node without naming it, or changed an anchor's target as if value-only.
         model.layout_verify_recheck = false;
         let before = (model.resolved.clone(), model.region_resolved.clone());
-        // The meters are the incremental pass's, not the re-run's: `layout_solves` is documented
-        // verify-independent and `layout_last_scope` is decision 1350's own gate. Counting the
-        // falsifier's work in either would make every assertion in the suite read the wrong pass.
+        // The meters keep the incremental pass's values, which tests assert on, not the re-run's.
         let meters = (
             model.layout_solves,
             model.layout_rounds,
@@ -760,44 +548,24 @@ impl UiScript {
 
     fn resolve_layout_inner(model: &mut Model) {
         // ── Tier 1: the mutation epoch ────────────────────────────────────────────────────────
-        // Nothing has called `touch_layout` since the last converged resolve ⇒ the read set the
-        // fingerprint below hashes cannot have moved ⇒ skip everything, including the tooltip
-        // pre-pass and the fingerprint itself (which was the whole idle cost of this function —
-        // ~0.6 ms/frame at the LBRS pin, hashing ~2k inputs per frame to decide "quiet"). Under
-        // verify, fall through: tier 2 then proves the claim (`gate_skips` must agree).
+        // No layout touch since the last converged resolve: nothing the fingerprint reads moved,
+        // so skip everything. Under verify, fall through so tier 2 checks the claim.
         let verify = layout_verify_enabled();
         let tier1_clean = model.layout_epoch_resolved == Some(model.layout_epoch);
         if tier1_clean && !verify {
             return;
         }
         let epoch_at_entry = model.layout_epoch;
-        // Past tier 1 ⇒ this call pays the whole-roster preamble, whatever the fingerprint goes on
-        // to decide. Counted here rather than at the solve, because the walk IS the cost (1385).
-        // Not gated on `verify`: a verify build re-walks skipped resolves and must say so.
+        // Every call past tier 1 counts, verify's re-walks included: the walk is the cost.
         model.layout_gate_walks = model.layout_gate_walks.wrapping_add(1);
-        // `WOW_LAYOUT_PROF=1`'s preamble split — see [`PreambleProf`]. Started here, so the clock
-        // covers everything the tier-1 gate above did NOT skip.
         let mut pre = PreambleProf::new(layout_prof_enabled());
-        // The GameTooltip auto-size + right-flush pre-pass (decision 0274): writes tooltip frame
-        // sizes + right-column anchor offsets from the measure round-trip's cached extents, so
-        // the graph below solves them like any other frame.
+        // The GameTooltip pre-pass writes tooltip sizes and offsets from cached measures.
         super::tooltip::layout_tooltips(model);
         pre.tooltip = pre.lap();
         // ── `OnSizeChanged`'s "before" ───────────────────────────────────────────────────────
-        // The client fires it from `ApplyRect 0x76b580`, per rect application. Ours is a batch
-        // fixpoint, so the faithful *mechanism* — "this frame's resolved size moved" — is the
-        // entry-vs-convergence diff, not a per-round one: an intermediate round's half-solved rect
-        // is an implementation detail of our solver, and firing on it would hand handlers sizes the
-        // reference never produces (and re-fire on the way to the same answer).
-        //
-        // Snapshotted only for frames that actually CARRY a handler (a handful, usually zero), and
-        // only past the tier-1 gate above — an idle frame returns before this line, so the change
-        // costs nothing on the quiet path decision 0740 exists to protect.
-        //
-        // Read off `SetScript`'s maintained list (1446's shape, extended in 1634), NOT by filtering
-        // the whole `scripts` map: "a handful, usually zero" was true of the RESULT and never of
-        // the search, which cost a string compare per frame in a 3,988-frame roster and was the
-        // preamble's biggest phase — larger than everything the graph does with the answer.
+        // The reference fires it per rect application (`ApplyRect 0x76b580`); our batch fixpoint
+        // fires on the entry-vs-convergence diff, never on a half-solved round. Only frames with
+        // a handler are snapshotted, from `SetScript`'s list.
         let watched: Vec<(FrameHandle, Option<Rect>)> = model
             .on_size_changed_frames
             .iter()
@@ -805,13 +573,8 @@ impl UiScript {
             .collect();
         pre.watched = pre.lap();
         // ── The graph: the ledger's cache, or a fresh derivation ─────────────────────────────
-        // `layout_touched` is tier 1's PRECISE form (decision 1388). `Some` carries the claim that
-        // every write since the cached graph was built named its node and left the graph's shape
-        // alone — so the roster, the edge set and the per-node hashes in `layout_scope` still
-        // describe the live model, and this resolve can seed its dirty closure straight from the
-        // list. That skips the derivation below entirely: 1.48 ms of whole-roster walking at the
-        // Stormwind pin (3,218 frames, 10,438 anchored regions), which a single moving castbar
-        // spark used to pay every frame. `None` derives, exactly as every resolve did before 1388.
+        // A `Some` ledger claims every write since the graph was built named its node and kept
+        // the graph's shape, so the cached roster, edges and hashes stand; `None` derives.
         let touched = model.layout_touched.take();
         let fp = touched
             .is_none()
@@ -840,21 +603,14 @@ impl UiScript {
             texture_size_probe,
             ..
         } = model;
-        // ── The incremental seed (decision 1388) ─────────────────────────────────────────────
-        // Re-hash only the nodes the ledger named, and seed the ones whose hash actually moved.
-        // This runs BEFORE the gate's verdict because on this path it IS the verdict: an empty
-        // seed set means no named write moved anything, which is the same conclusion tier 2
-        // reaches by hashing ten thousand nodes — reached here by hashing the handful that were
-        // written, and carrying the scope for the ones that did move as a side effect.
+        // ── The incremental seed ─────────────────────────────────────────────
+        // Re-hash only the named nodes and seed those whose hash moved. It runs before the gate
+        // because on this path it is the verdict: an empty seed set means nothing moved.
         let mut scope_nodes = 0usize;
         let mut full_scope = false;
         if let Some(touched) = &touched {
             scope.begin_incremental();
             for &id in touched {
-                // The node's roster row — which also says whether it is a frame or a region, and
-                // where to find the live inputs to re-hash. `has_node` was already true when the
-                // write named it; re-checking is a formality that costs one bounds check and
-                // survives a roster the ledger somehow outlived.
                 let Some(&n) = scope.node_of.get(id as usize) else {
                     continue;
                 };
@@ -874,9 +630,7 @@ impl UiScript {
                         None => continue,
                     }
                 };
-                // The same absorption the setters' bit-compares give, one level up: a write that
-                // named a node but did not move its hash (the tooltip pre-pass rewriting the same
-                // size, a re-`SetPoint` to the value already there) seeds nothing.
+                // A named write that did not move the hash (a same-value `SetPoint`) seeds nothing.
                 if now != scope.last.get(id as usize).copied().unwrap_or(NO_NODE) {
                     scope.staged.push((id, now));
                     scope.seed(id);
@@ -886,22 +640,14 @@ impl UiScript {
             pre.seed = pre.lap();
             pre.incremental = true;
         }
-        // Tier 2's verdict is a derivation's product, so an incremental pass answers with its own —
-        // and a strictly finer one. Where the fingerprint says "one of these ten thousand moved",
-        // the seed set says which; empty means nothing did, and last frame's rects still stand.
-        // `staged` is exactly the seed set (both are pushed on the same compare), so it is the
-        // question already answered.
+        // An incremental pass has no fingerprint; its verdict is `staged`, exactly the seed set.
         let gate_skips = match fp {
             Some(_) => *layout_fingerprint == fp,
             None => scope.staged.is_empty(),
         };
         pre.report(gate_skips, scope.plan.len(), scope.regions.len());
-        // The tier-1/tier-2 cross-check (only reachable under verify when tier 1 judged quiet):
-        // the epoch said nothing layout-visible was written, so the fingerprint must agree — a
-        // divergence is a mutation path missing its `Model::touch_layout()`, named here at the
-        // frame that proves it instead of shipping as a silently stale rect. An incremental pass
-        // has no fingerprint to cross-check; its own, stronger falsifier is the full re-derivation
-        // `resolve_layout` runs behind it under verify.
+        // Under verify, a frame tier 1 judged quiet must pass tier 2 too; a divergence is a write
+        // path missing its `touch_layout()`.
         if tier1_clean && fp.is_some() {
             assert!(
                 gate_skips,
@@ -909,60 +655,30 @@ impl UiScript {
                  fingerprint moved — a layout write path is missing its touch_layout()"
             );
         }
-        // Nothing in the read set moved since the last CONVERGED resolve, so the rects it left are
-        // still this frame's answer: close tier 1 and skip. (A converged solve closes it too — see
-        // the convergence arm below. This arm is the one that absorbs an epoch bump whose write
-        // changed no input: an id mint, an anchor-less region's creation, a re-`SetPoint` the
-        // setters' own compare let through.)
+        // Nothing read moved since the last converged resolve, whose rects stand: close tier 1.
         if gate_skips {
             *layout_epoch_resolved = Some(epoch_at_entry);
-            // Re-arm the ledger here too (decision 1388). A pass that found nothing to do left the
-            // graph exactly as it found it — derived a moment ago on one path, untouched on the
-            // other — so the cache is as trustworthy as it was. Dropping it here would make every
-            // named-but-idempotent write (the tooltip pre-pass, a re-`SetPoint` to the value
-            // already there) cost the NEXT real write a full derivation.
+            // Re-arm the ledger: the graph is as it was, so the cache is still trustworthy.
             *layout_touched = Some(Vec::new());
             if !verify {
                 return;
             }
         }
-        // Under `WOW_LAYOUT_VERIFY=1` a skippable resolve runs anyway, against a copy of the rects
-        // it is supposed to reproduce — see [`layout_verify_enabled`].
+        // Under verify a skippable resolve runs anyway, against the rects it must reproduce.
         let verify_against = gate_skips.then(|| (resolved.clone(), region_resolved.clone()));
-        // Cleared, not stored, until the fixpoint actually CONVERGES: a run that exhausts the
-        // round cap (a genuine anchor cycle) leaves its rects mid-flight, and the 0294 cross-frame
-        // seed is what lets the next frame carry them further. Storing here would freeze a
-        // pathological graph at whatever partial state it reached. The epoch mirror follows the
-        // same law: a cycle-bailed pass must re-enter tier 1 dirty next frame.
+        // Cleared until the fixpoint converges: a cycle-bailed pass leaves its rects mid-flight
+        // for the next frame to carry further, so it must re-enter both tiers dirty.
         *layout_fingerprint = None;
         *layout_epoch_resolved = None;
-        // Counted on the gate's DECISION, not on the fixpoint running: under
-        // `WOW_LAYOUT_VERIFY=1` a skipped resolve still runs below, and a counter that moved for
-        // it would mean something different in the two modes — exactly the ambiguity the tests
-        // asserting on it exist to remove.
+        // Counted on the gate's decision, so verify's forced runs leave it alone.
         if !gate_skips {
             *layout_solves += 1;
         }
-        // ── The scope: which nodes this solve is actually allowed to touch (decision 1350) ────
-        // A node whose own inputs are unchanged, and none of whose dependencies moved, recomputes
-        // to the rect it already holds — the 0294 seed property, stated per node instead of for
-        // the graph as a whole. So the solve below runs over the dirty CLOSURE and leaves every
-        // other rect at its cached value, feeding it to the solver as an external where a dirty
-        // node anchors to it.
-        //
-        // Four structural cases the per-node diff cannot speak about fall back to full scope,
-        // because getting them wrong ships a stale rect rather than a slow frame:
-        //   * no memory yet (the first resolve, or a pass invalidated below);
-        //   * the SCREEN moved — the root external and every clamped frame's extent;
-        //   * a node DIED: its reverse edges died with it, so its dependents are unreachable.
-        //     Counted, not searched: if fewer of this pass's nodes carry a `last` hash than the
-        //     last pass had nodes, something left;
-        //   * verify, which runs the scoped pass and then the full one and compares.
-        //
-        // An INCREMENTAL pass (decision 1388) reaches the same closure by the other end, and has
-        // already done so above — it re-hashes only the nodes the ledger named and seeds the ones
-        // whose hash moved. None of the four structural cases can reach it: each is a conservative
-        // touch, and a conservative touch is what leaves the ledger `None`.
+        // ── The scope: which nodes this solve may touch ────
+        // A node with unchanged inputs and no moved dependency recomputes to the rect it holds, so
+        // the solve runs over the dirty closure and feeds other rects in as externals. Full scope
+        // when there is no memory yet, the screen moved, a node died (fewer nodes match `last`
+        // than `last_count`), or under verify. The incremental pass seeded its closure above.
         if touched.is_none() {
             let mut matched = 0usize;
             for (id, &n) in scope.node_of.iter().enumerate() {
@@ -991,17 +707,13 @@ impl UiScript {
                 scope.close();
             }
         }
-        // The rosters the rounds walk. A frame in the closure is SOLVED; a region in it is SWEPT;
-        // anything a closure node anchors to is SEEDED as an external at its cached rect. A dirty
-        // REGION is seeded as well as swept: the frame pass runs before the sweep that refreshes
-        // it, so it needs last round's value in front of it — which is exactly what the whole-graph
-        // seeding did before.
+        // A dirty frame is solved, a dirty region swept, and whatever they read is seeded at its
+        // cached rect. A dirty region is seeded too, since the frame pass runs before the sweep.
         let mut solve_frames: Vec<u32> = Vec::new();
         let mut sweep_regions: Vec<u32> = Vec::new();
         let mut seed_frames: Vec<u32> = Vec::new();
         let mut seed_regions: Vec<u32> = Vec::new();
-        // Is any node that reads `id` in the closure? (Seeding is per-node work too, so a rect
-        // nothing dirty reads must not be seeded.)
+        // Whether a node in the closure reads `id`; a rect nothing dirty reads is not seeded.
         let read_by_dirty = |scope: &LayoutScope, id: u32| -> bool {
             let mut e = scope.dep_head[id as usize];
             while e != u32::MAX {
@@ -1033,15 +745,10 @@ impl UiScript {
                 seed_frames.push(idx);
             }
         }
-        // The meter: how WIDE this solve is, beside `layout_solves` (how often) and
-        // `layout_rounds` (how deep). The gate asserts on it, because a scope that tracks the
-        // graph is the regression and milliseconds are not evidence of it (decision 0735's lesson,
-        // paid for twice).
+        // This solve's width, beside `layout_solves` (how often) and `layout_rounds` (how deep).
         *layout_last_scope = (solve_frames.len(), sweep_regions.len());
         let round_cap = scope.plan.len() + region_data.len() + 2;
-        // `WOW_LAYOUT_PROF=1` — the per-solve shape: rounds, the graph's size, and the split
-        // between the frame solve and the region sweep. The numbers that say whether a solve is
-        // expensive because it runs too often or because each pass walks the whole UI.
+        // `WOW_LAYOUT_PROF=1`: rounds, graph size, and the frame-solve and region-sweep split.
         let prof = layout_prof_enabled();
         let mut t_frames = std::time::Duration::ZERO;
         let mut t_regions = std::time::Duration::ZERO;
@@ -1051,11 +758,7 @@ impl UiScript {
             let t_round = prof.then(std::time::Instant::now);
             let mut changed = false;
 
-            // Seed the solver: the screen root, then every rect this pass is NOT recomputing but
-            // something in it reads (regions are externals to the frame solve — the fixpoint is
-            // what closes the loop between them). Frame ids and region ids come from one monotonic
-            // counter, so both live in the solver's single dense rect array and every anchor-target
-            // lookup is an array index.
+            // Seed the screen root and every read rect this pass does not recompute.
             solver.begin();
             solver.set_external(SCREEN, *screen);
             for &i in &seed_regions {
@@ -1071,9 +774,6 @@ impl UiScript {
                 }
             }
             for &i in &solve_frames {
-                // The `layout_inputs` probe the borrowed plan used to hoist out of the round loop
-                // (decision 1350) is back — but paid per frame this solve TOUCHES, not per frame in
-                // the UI, which is what lets the roster itself outlive the call (1388).
                 let (h, id, over) = scope.plan[i as usize];
                 let Some(input) = layout_inputs.get(&h) else {
                     continue;
@@ -1101,17 +801,9 @@ impl UiScript {
                 }
             }
 
-            // Second pass — anchored regions. A region that carries `SetPoint` anchors resolves through
-            // the same [`crate::layout`] leaf math as frames; any edge the anchors + explicit size don't
-            // pin inherits the owner frame's edge (so a single-point FontString gets a real rect, not
-            // `+Inf`). Anchor targets may be frames OR **sibling regions by name** (the real XML does
-            // this everywhere — the merchant label plate anchors to its `$parentSlot` texture; the
-            // owner-fallback that stood in for this was the jutting-plates bug). One region sweep per
-            // outer round: a not-yet-resolved chain target leaves this region on its owner-edge
-            // fallback for now, the fixpoint re-sweeps until every link has settled.
-            //
-            // `scratch` is hoisted out of the loop so the per-region `LayoutInput` refills its
-            // anchors `Vec` in place instead of allocating one per region per round.
+            // Second pass: anchored regions, through the same `crate::layout` math as frames. An
+            // anchor may target a frame or a sibling region; one whose target has no rect yet pins
+            // nothing this round, and the fixpoint re-sweeps until every link settles.
             if let Some(t) = t_round {
                 t_frames += t.elapsed();
             }
@@ -1124,40 +816,19 @@ impl UiScript {
                     owner,
                     is_fontstring,
                 } = scope.regions[ri as usize];
-                // The roster's mutable half, re-probed here rather than borrowed into the row —
-                // once per region SWEPT instead of once per region in the UI (decision 1388). A
-                // row whose data has gone is a region the derive will drop on its next run; it
-                // resolves to nothing in the meantime, exactly as a dead one does.
+                // A row whose data has gone is skipped until the next derivation drops it.
                 let Some(data) = region_data.get(&rh) else {
                     continue;
                 };
                 if prof {
                     n_regions_swept += 1;
                 }
-                // The owner supplies the region's SCALE and nothing else. It used to supply
-                // fallback edges too; it does not any more (decision 1664) — see the `axis`
-                // closure below for why, and what the two shapes that leaned on it get instead.
+                // The owner supplies the region's scale and nothing else: no fallback edges.
                 let scale = arena.frame(owner).map(|f| f.effective_scale).unwrap_or(1.0);
-                // A FontString with no explicit height takes its host-measured wrapped size
-                // (the measure round-trip — the client's layout↔font-engine seam).
-                //
-                // The stored measure is honoured WITHOUT a key check on purpose
-                // ([`RegionData::measure_key`]): it is the LAST-KNOWN box, held so a line whose
-                // text just changed does not collapse for the one frame the re-measure is in
-                // flight. **Empty text is the case where that promise cannot be kept** — nothing
-                // ever measures an empty string (`fontstrings_needing_measure` and
-                // `stale_measure_key` both filter it out), so a cell that goes from text to `""`
-                // would hold its old box FOREVER. There is no round-trip to wait for: an empty
-                // string's extent is known, and it is zero.
-                //
-                // That forever-stale box is B309. Tooltip line cells are POOLED and reused across
-                // hovers (`clear_content` keeps `measured` deliberately, for the hover re-enter
-                // loop), so the item tooltip's two blank gold SET spacers (`render.rs`, `0x854b2c`)
-                // landed on cells that had carried real text on an earlier hover: each drew a full
-                // row out of the dead measure while the plate counted it as zero
-                // (`tooltip::cell` calls empty text `(0,0)`), and the set bonuses hung two rows
-                // below the backdrop. The Lua-visible getters never disagreed — they key-check
-                // (`region::measured_wh`) — which is why only the drawn geometry was wrong.
+                // An axis authored 0, width or height, takes the host-measured extent: the
+                // reference sizes a zero width to the unwrapped line. The measure is used without
+                // a key check, so changed text keeps its last box while the re-measure is in
+                // flight; empty text is never measured, so it counts as zero, never a stale box.
                 let measured = data
                     .measured
                     .filter(|_| data.text.as_deref().is_some_and(|t| !t.is_empty()));
@@ -1171,31 +842,16 @@ impl UiScript {
                         width = m.w;
                     }
                 }
-                // …and then the FLOOR. `CSimpleFontString::GetWidth 0x772930` takes the
-                // authored value when it is not exactly `0.0` and the measured extent otherwise,
-                // then returns `max(candidate, ONE FrameXML unit)` — the floor sits past the
-                // `jp 0x772957` that skips the measure, so it applies to BOTH legs. `0x772a60` is
-                // the identical body for height. **A FontString's span is therefore never `0.0`**,
-                // which is what makes a single-anchored FontString always resolve — and what
-                // retires the zero-span collapse this sweep
-                // used to apply in the `axis` closure below.
+                // Then the floor: `CSimpleFontString::GetWidth 0x772930` (height `0x772a60`)
+                // returns at least one unit on both legs, past the `jp 0x772957` that skips the
+                // measure, so a FontString's span is never 0 and a single anchor resolves it.
                 if is_fontstring {
                     width = width.max(FONTSTRING_MIN_SPAN);
                     height = height.max(FONTSTRING_MIN_SPAN);
                 }
-                // A TEXTURE's unset axis is the client's *other* content-derived span: the art's
-                // own texel extent ([`content_span`]). It is the same shape as the FontString
-                // measure above — the reference's size getter is virtual, and both region classes
-                // override it — and it has to be applied HERE, before the resolve, because
-                // `combine_edge` reads a zero span as "no size at all" and leaves the opposite edge
-                // unresolved.
-                //
-                // That vacuum is what B342 fell into. `page_text` 2654 (*A Treatise on Military
-                // Ranks*) carries `<IMG src="…\PvPRankAlliance" align="left"/>` — **no width=, no
-                // height=** — so SimpleHTML sized the block `0 × 0`, one TOPLEFT anchor pinned the
-                // corner, and the owner-edge fallback below stretched a 128×128 crest across the
-                // rest of the 270×304 page with the text over it. The reference draws it at 128×128
-                // units, because a texel is a FrameXML unit.
+                // A texture's unset axis takes its texel extent (`content_span`): the reference's
+                // size getter is virtual for both region classes. It must apply before the
+                // resolve, as `combine_edge` reads a zero span as no size and leaves an edge unset.
                 if !is_fontstring && (width == 0.0 || height == 0.0) {
                     if let Some((cw, ch)) = content_span(data, texture_size_probe.as_ref()) {
                         if width == 0.0 {
@@ -1212,38 +868,16 @@ impl UiScript {
                 scratch.height = height;
                 scratch.scale = scale;
                 let edges = layout::resolve_rect_edges(&scratch, |id| {
-                    // SCREEN is a FRAME-pass external only. The map-pair lookup this replaces
-                    // consulted `id_to_frame` and `id_to_region`, and neither can hold the
-                    // reserved id 0 (`next_id` starts at 1) — so a region anchor to the screen
-                    // root has always fallen through to the owner-edge fallback below. Preserved
-                    // deliberately: the solver's dense array DOES carry the screen rect at 0, and
-                    // quietly starting to resolve it here would be a behaviour change riding in
-                    // on a performance fix.
+                    // The screen root is a frame-pass external only: a region anchor to id 0 finds
+                    // no rect here, though the solver holds one.
                     (id != SCREEN).then(|| solver.rect(id)).flatten()
                 });
-                // **An axis resolves, or the region does not** — there is no owner-edge fallback
-                // and no zero-span collapse (decision 1664). A complete memory-operand enumeration
-                // of the real resolver core `[0x7671a0, 0x76761f)` finds no parent or owner pointer
-                // in it at all: the only fallbacks are the object's own nine anchor slots and
-                // `combineEdge`/`combineCenter` over its own opposite edge/centre ± its own size.
-                // `assemble 0x767a20` returns 0 the moment any edge is still UNSET, and
-                // `0x768d20` latches the region unresolvable.
-                //
-                // The two shapes that leaned on the fallback both have their own answer now, which
-                // is why deleting it is a fidelity fix and not a hole:
-                //
-                // * **No anchors at all.** The client anchors those at CREATION, per region type —
-                //   a texture gets `SetAllPoints(parent)`, a FontString one justify-selected
-                //   `SetPoint` — so by the time the resolver sees them they are pinned like
-                //   anything else ([`super::region::implicit_creation_anchor`], decision 1310).
-                //   The ones that reach here still unanchored are the shapes the reference leaves
-                //   rect-less too: a templateless `CreateTexture`, a title region, a plain frame.
-                // * **A pinned edge with a zero span.** The span is content-derived on both region
-                //   classes — the texture's texel extent above, the FontString's measured extent
-                //   floored at one unit — so `combineEdge`'s zero-span leg is nearly unreachable
-                //   for a region at all (`0x767440`). What is left is a texture
-                //   with no art whatever, which the reference resolves to nothing and draws as a
-                //   degenerate all-zero quad.
+                // An axis resolves, or the region does not. The reference resolver core
+                // `[0x7671a0, 0x76761f)` reads no parent or owner pointer, only the region's own
+                // anchors and `combineEdge`/`combineCenter` over its own size; `assemble 0x767a20`
+                // fails on any unset edge, and `0x768d20` latches the region unresolvable. An
+                // anchor-less region is anchored at creation (`region::implicit_creation_anchor`),
+                // and a texture with no art has a zero span and resolves to nothing (`0x767440`).
                 let axis = |lo: Option<f32>, hi: Option<f32>| -> Option<(f32, f32)> {
                     match (lo, hi) {
                         (Some(l), Some(h)) => Some((l, h)),
@@ -1253,17 +887,14 @@ impl UiScript {
                 let vertical = axis(edges[0], edges[2]);
                 let horizontal = axis(edges[1], edges[3]);
                 let (Some((bottom, top)), Some((left, right))) = (vertical, horizontal) else {
-                    // Unresolvable: drop any rect it used to have, the way the frame pass does —
-                    // a region that stops resolving must stop drawing, not keep a stale position.
+                    // Unresolvable: drop its rect, so it stops drawing instead of going stale.
                     if region_resolved.remove(&rh).is_some() {
                         changed = true;
                     }
                     continue;
                 };
                 let rect = Rect::new(bottom, left, top, right);
-                // Publish into the solver as well as the model: a later region in THIS same sweep
-                // that anchors to this one must see the fresh rect (the sweep has always worked
-                // that way — it read the same `region_resolved` map it was writing).
+                // Into the solver too: a later region in this sweep that anchors here needs it.
                 solver.set_external(region_id, rect);
                 if region_resolved.get(&rh) != Some(&rect) {
                     region_resolved.insert(rh, rect);
@@ -1276,12 +907,7 @@ impl UiScript {
             }
             if !changed {
                 if prof {
-                    // `anchored` (live + anchored regions) is reported beside `regions_total`
-                    // deliberately: the sweep never touched the difference, so a solve's real
-                    // population was invisible in this line — which is exactly why two commits
-                    // that moved a large batch of regions from "skipped" to "resolved" (1350's
-                    // pin) showed up as a cost with no counter behind it. `solved`/`swept` are
-                    // this pass's SCOPE: with the graph settled they should be a handful.
+                    // `anchored` is the sweep's roster, `solved` and `swept` this pass's scope.
                     eprintln!(
                         "[layout-prof] rounds={} frames={} regions_total={} anchored={} \
                          solved={} swept={} scope={} regions_swept={} frame_us={} region_us={}",
@@ -1310,55 +936,28 @@ impl UiScript {
                     );
                 }
                 *layout_fingerprint = fp;
-                // The scope's memory is adopted only HERE, on the converged path, for the same
-                // reason the fingerprint is: a pass left mid-flight describes a graph that never
-                // settled, and seeding the next pass's "unchanged ⇒ unmoved" argument from it
-                // would be seeding it from a lie.
-                //
-                // An incremental pass adopts only the nodes it re-hashed — the rest of `last` is
-                // already the memory of the derivation this pass is standing on (decision 1388).
+                // Adopted only on convergence; an incremental pass adopts only what it re-hashed.
                 if touched.is_some() {
                     scope.commit_incremental();
                 } else {
                     scope.commit(scope_nodes, *screen);
                 }
                 // ── Re-arm the ledger ─────────────────────────────────────────────────────────
-                // The graph in `scope` now describes a CONVERGED model, so the next frame's writes
-                // may name their nodes against it. Empty, not `None`: `None` is the standing claim
-                // that the cache is untrustworthy, and it has just been made trustworthy.
-                //
-                // Armed only on convergence, and only here — the cycle bail below leaves it `None`
-                // along with everything else, because a graph that never settled is exactly the
-                // one a ledger must not vouch for.
+                // The graph now describes a converged model, so writes may name nodes against it.
+                // Only here: the cycle bail below leaves it `None`.
                 *layout_touched = Some(Vec::new());
-                // Under verify, tell `resolve_layout` to re-derive this same frame from scratch and
-                // compare rects — the incremental pass's falsifier. Costs nothing in production,
-                // where `layout_verify_enabled` is false and nothing ever reads this.
+                // Under verify, `resolve_layout` re-derives this frame from scratch and compares.
                 *layout_verify_recheck = touched.is_some() && verify;
-                // **A CONVERGED SOLVE CLOSES TIER 1** (decision 1385) — unconditionally, not only
-                // on the `gate_skips` re-run. The fingerprint above is hashed over INPUTS alone,
-                // and the rounds just drove those inputs to their fixpoint, so the fp stored on
-                // the line above is exactly the one the next mutation-free resolve recomputes:
-                // there is nothing left for a settling pass to discover. Closing here is what
-                // makes a per-frame layout write cost ONE whole-roster walk instead of three
-                // (solve, settle, skip) — the castbar's spark, and every addon that animates a
-                // region, used to pay all three every frame.
-                //
-                // `epoch_at_entry` (not the live epoch) keeps it conservative: anything that
-                // touched the layout WHILE this pass ran — the tooltip pre-pass, a lazily minted
-                // region — leaves the epoch ahead of the stored value, so tier 1 re-opens next
-                // call exactly as it should. The cycle-bail path below never reaches here, so a
-                // graph left mid-flight still re-resolves.
+                // A converged solve closes tier 1, at `epoch_at_entry` rather than the live epoch,
+                // so a touch during this pass (the tooltip pre-pass, a minted id) re-opens it. The
+                // fingerprint hashes inputs only, so the next unmutated resolve would match it.
                 *layout_epoch_resolved = Some(epoch_at_entry);
                 queue_size_changes(&watched, resolved, frame_to_id, pending_size_changed);
                 return;
             }
             if round + 1 == round_cap {
-                // `Model::record_warning`'s two halves, spelled out because this pass holds the
-                // model destructured and cannot call it: the host drain, and the retained log
-                // (2135). `WOW_LAYOUT_VERIFY`'s falsifier re-run truncates `warnings` and does
-                // NOT roll the log back — the log dedupes, so a verify build reads `×2` on a row
-                // that happened once, and that build is not a production path.
+                // `Model::record_warning` inlined, as the model is destructured. Verify's re-run
+                // truncates `warnings` but not the log, so a verify build may count a row twice.
                 let msg = format!(
                     "layout: anchor graph did not converge in {round_cap} rounds — \
                      an anchor cycle? (rects left at their last pass)"
@@ -1367,23 +966,14 @@ impl UiScript {
                 warnings.push(msg);
             }
         }
-        // The cycle bail (the loop ran out of rounds and warned above): the rects it leaves are
-        // still the ones every reader will see this frame, so the sizes that moved get their
-        // `OnSizeChanged` here exactly as on the converged path — and the scope forgets, so the
-        // next resolve rebuilds the whole graph rather than trusting a half-solved one.
+        // The cycle bail: its rects are this frame's, so their size changes still fire, and the
+        // scope forgets a graph that never settled.
         scope.invalidate();
         queue_size_changes(&watched, resolved, frame_to_id, pending_size_changed);
     }
 
-    /// Derive the layout graph from scratch — the roster of live frames and anchored regions, the
-    /// reverse-edge set between them, the per-node input hashes, and the aggregate fingerprint
-    /// that is tier 2 of the change gate.
-    ///
-    /// Every resolve did this, until decision 1388. It is ~1.48 ms at the Stormwind pin, 79% of it
-    /// in two phases (`fp_regions` 919 µs, `retain` 255 µs) that rediscover a graph which had not
-    /// changed shape. It now runs only when the ledger cannot vouch for the cache: the first
-    /// resolve, a cycle-bailed one, and any frame in which a write moved the roster, retargeted an
-    /// anchor, or could not name what it touched.
+    /// Derive the layout graph from scratch: the roster, the reverse edges, the per-node hashes and
+    /// the tier-2 fingerprint. Runs only when the ledger cannot vouch for the cache.
     fn derive_layout_graph(model: &mut Model, pre: &mut PreambleProf) -> InputFingerprint {
         model.layout_derives = model.layout_derives.wrapping_add(1);
         let Model {
@@ -1400,9 +990,7 @@ impl UiScript {
             ..
         } = model;
 
-        // One id per live frame, and its layout input with scale synced from the arena. A flat
-        // `Vec`, not a map: this list is walked (never probed) by every round below, and it is
-        // rebuilt on each call anyway — a `HashMap` bought nothing and cost 1881 hashes per call.
+        // One id per live frame, its layout input's scale and clamp synced from the arena.
         let mut ids: Vec<(FrameHandle, u32)> = Vec::with_capacity(frame_to_id.len());
         for (&h, &id) in frame_to_id.iter() {
             if arena.frame(h).is_some() {
@@ -1416,10 +1004,8 @@ impl UiScript {
                 .unwrap_or((1.0, false));
             let input = layout_inputs.entry(h).or_default();
             input.scale = scale;
-            // Clamp-to-screen is a FRAME property (geometry flags bit4 — SetClampedToScreen, the
-            // XML attribute, the GameTooltip-kind default), synced like scale so EVERY placement
-            // path — SetOwner's anchor law, a caller's SetPoint, the cursor-seated world plates —
-            // resolves through the same clamp, with extents tracking the live window size.
+            // Clamp-to-screen is a frame property (geometry flags bit 4), so every placement path
+            // clamps alike, against the live window size.
             input.clamp = clamp;
             if clamp {
                 input.extent_x = screen.right;
@@ -1428,18 +1014,10 @@ impl UiScript {
         }
         pre.ids = pre.lap();
 
-        // The ScrollFrame mechanism (decision 0112): a live ScrollFrame with a live scroll child
-        // overrides the child's own anchors for this solve — `SetScrollChild` pins the child TOPLEFT
-        // to the scrollframe's TOPLEFT, offset by the two live scroll offsets
-        // (`(horizontal, vertical)`, both RAW and unnegated, exactly as the reference's re-anchor
-        // `0x787100` hands them to `SetPoint`). XML y-positive-up, so a positive vertical lifts the
-        // child, bringing content below the fold into view — `frame top 500, vertical 40 ⇒ child top
-        // 540`; x grows right, so a positive horizontal pushes the child right and it is a NEGATIVE
-        // horizontal that scrolls right (see `ScrollFrameState::horizontal`). This is a LOCAL map, consulted only
-        // while building each round's graph below — the child's authored `LayoutInput.anchors` are
-        // never touched, so `SetScrollChild(nil)` needs no restore: the override just stops being
-        // computed. The child's own width/height (from its own `LayoutInput`) stay whatever they are;
-        // only its anchors are replaced.
+        // A live ScrollFrame's live child is anchored, for this solve only, TOPLEFT to its TOPLEFT
+        // at the raw, unnegated `(horizontal, vertical)` offsets, as the reference's re-anchor
+        // `0x787100` passes them to `SetPoint`: y up, so a positive vertical lifts the child. Its
+        // authored anchors and size are untouched, so `SetScrollChild(nil)` needs no restore.
         let mut scroll_child_anchor: HashMap<FrameHandle, Anchor> = HashMap::new();
         for &(h, id) in &ids {
             let Some(frame) = arena.frame(h) else {
@@ -1468,28 +1046,11 @@ impl UiScript {
         }
         pre.scroll = pre.lap();
 
-        // Alternating frame/region rounds, run to a CHANGE-DRIVEN FIXPOINT: the real client
-        // resolves ONE layout graph in which frames and regions anchor each other freely (the
-        // gossip option rows anchor to the greeting FontString's laid-out bottom; the quest log's
-        // detail pane chains ~15 regions deep with item BUTTONS anchored to the tail). Our frame
-        // pass is a batch graph solve, so each round re-solves it with the latest REGION rects as
-        // externals, re-resolves the regions against the new frame rects, and stops when a full
-        // round changed nothing. The old fixed budget (2 frame rounds × 3 region rounds) silently
-        // left chain links past ~6 on owner-edge fallbacks and dropped tail-anchored frames to the
-        // screen origin — decision 0088 §2's finding, which forced windows into invented fixed
-        // offsets instead of ref-verbatim chains. The round cap is the node count (an honest round
-        // binds at least one new link), so only a genuine anchor CYCLE can exhaust it — warned,
-        // mirroring the client's resolving-flag cycle bail. Convergence compares exact rects: each
-        // pass recomputes from the same inputs through the same arithmetic, so stabilized values
-        // repeat bit-for-bit (no epsilon drift).
-        //
-        // The fixpoint CARRIES ACROSS FRAMES (decision 0294): every rect is recomputed purely from
-        // (inputs, externals), never from its own prior value, so last frame's converged rects are a
-        // legal seed — a quiet frame re-verifies in ONE round instead of re-propagating every anchor
-        // chain link-by-link (measured: the full default UI held 5–10 rounds × ~7 ms/round at
-        // opt-level 0, every frame, ~72 ms of a quiet frame — the director's 60→50 fps). Only
-        // regions that left the model (or lost their anchors) drop; a from-scratch resolve is just
-        // the empty-seed special case, so first-frame behavior is unchanged.
+        // The reference resolves one graph in which frames and regions anchor each other; ours
+        // alternates a frame solve and a region sweep until a round changes no rect, compared
+        // exactly. The round cap is the node count, so only a cycle exhausts it, warned like the
+        // reference's resolving-flag bail. Every rect is recomputed from inputs and externals, so
+        // last frame's rects are a legal seed: only dead or unanchored regions drop.
         region_resolved.retain(|rh, _| {
             arena.region(*rh).is_some()
                 && region_data.get(rh).is_some_and(|d| !d.anchors.is_empty())
@@ -1497,52 +1058,16 @@ impl UiScript {
         pre.retain = pre.lap();
 
         // ── The change gate ───────────────────────────────────────────────────────────────────
-        // Fingerprint exactly what the rounds below read, and skip them outright when nothing has
-        // moved since the last converged resolve. Measured on the shipped default UI: the layout
-        // inputs are byte-identical on 34 of 35 idle frames and 39 of 41 with three windows open,
-        // because almost all per-frame UI traffic (StatusBar values, cooldown sweeps, chat fades,
-        // colour changes) is read by EXTRACT, not by the anchor solve.
-        //
-        // The read set, in the order the rounds consume it:
-        //   * `screen`                      — the root external, and the clamp extents;
-        //   * `plan`                        — every live frame's id, its (already scale/clamp-
-        //                                     synced) `LayoutInput`, and its ScrollFrame override,
-        //                                     which together distil `frame_to_id`, frame liveness,
-        //                                     `effective_scale`, `clamped_to_screen`, and the
-        //                                     ScrollFrame child + vertical offset;
-        //   * `region_data`                 — each region's anchors, explicit size, and measured
-        //                                     text extent;
-        //   * `arena.region(rh)`            — liveness and owner (a dead region drops out of the
-        //                                     sweep; the owner supplies the fallback edges).
-        //
-        // **INPUTS ONLY — the 0294 seeds are deliberately NOT hashed** (decision 1385). They are
-        // the previous pass's OUTPUT, and 0294's own property ("every rect is recomputed purely
-        // from (inputs, externals), never from its own prior value") makes a converged pass's
-        // rects a pure function of the inputs: the seeds change how many ROUNDS convergence
-        // takes, never what it converges to. Hashing them therefore added no verdict the input
-        // half does not already give — and it cost two extra whole-roster walks per mutated
-        // frame, because a solve necessarily outgrows the seeds it hashed, so neither that pass
-        // nor the settling pass behind it could close tier 1. (`resolved`, the FRAME rects, was
-        // never in the read set at all — the seed half was asymmetric as well as redundant.)
-        //
-        // ── …and, in the same walk, the SCOPE (decision 1350) ─────────────────────────────────
-        // Each node's own inputs are hashed a second time on their own, into
-        // [`LayoutScope::now`], and its anchor targets are recorded as reverse edges. That turns
-        // the gate's one verdict ("something moved") into the far more useful one ("*these* moved,
-        // and here is everything downstream of them"), for the cost of a second accumulator over
-        // a read set we were walking anyway. Everything the aggregate `fp` feeds still feeds it,
-        // byte for byte, so tiers 1 and 2 are untouched.
-        // Sized past `next_id` because the region walk below MINTS ids (see there) — every id it
-        // can mint is one more than the anchored regions it walks.
+        // Fingerprint what the rounds read, to skip them when nothing moved since the last
+        // converged resolve: the screen; each live frame's id, synced `LayoutInput` and
+        // ScrollFrame override; each anchored region's anchors, explicit size, measured extent
+        // and liveness. Seeded rects are outputs, a pure function of these, so they are not hashed.
+        // The same walk hashes each node alone into `LayoutScope::now` and records its edges.
+        // Sized past `next_id` for the ids the region walk below may mint.
         scope.begin_full(*next_id as usize + region_data.len() + 1);
         pre.begin = pre.lap();
         let mut fp = InputFingerprint::default();
         fp.rect(*screen);
-        // The frame roster is built HERE rather than in a walk of its own (decision 1388): it is
-        // the same `ids` list, the same `layout_inputs` probe and the same `scroll_child_anchor`
-        // lookup this walk already needs, so a separate pass over every live frame bought nothing
-        // but a second traversal (77 µs of the old preamble) and a borrow that stopped the roster
-        // outliving the call.
         for &(h, id) in &ids {
             let Some(input) = layout_inputs.get(&h) else {
                 continue;
@@ -1561,9 +1086,8 @@ impl UiScript {
                 scope.node_of[id as usize] = i;
             }
             scope.plan.push((h, id, over));
-            // A frame reads the rect of every anchor target it has — its OVERRIDE's target when a
-            // ScrollFrame supplies one (the authored anchors are not consulted at all in that
-            // case, exactly as the round loop's `set_frame_anchored` does not consult them).
+            // A frame reads its anchor targets' rects, or only its ScrollFrame override's target,
+            // as the round loop's `set_frame_anchored` does.
             match over {
                 Some(a) => scope.edge(id, a.relative_to),
                 None => {
@@ -1579,16 +1103,11 @@ impl UiScript {
         }
         pre.fp_frames = pre.lap();
         let mut fed_regions = 0u64;
-        // The round loop's region roster, built in this same walk (decision 1350) — see
-        // [`RegionRow`]. Only LIVE, anchored regions: an anchor-less one is invisible to the
-        // rounds and a destroyed one has already been dropped from `region_resolved` by the retain
-        // above, so both are exactly what the sweep used to `continue` past.
+        // The region roster, built in the same walk: live, anchored regions only.
         scope.regions.reserve(region_data.len());
         for (&rh, data) in region_data.iter() {
-            // Anchor-less entries are invisible to the rounds — the sweep `continue`s on empty
-            // anchors and the seed retain drops them — so they are not inputs and must not be
-            // hashed: a paint-only setter creating a region's entry (`SetTexture`'s
-            // `or_default()`) would otherwise read as a layout change no touch site can own.
+            // Anchor-less entries are not layout inputs: hashing them would make a paint-only
+            // setter that creates one (`SetTexture`'s `or_default()`) read as a layout change.
             if data.anchors.is_empty() {
                 continue;
             }
@@ -1611,14 +1130,8 @@ impl UiScript {
                 None => fp.feed(u64::MAX),
             }
             if let Some(r) = live {
-                // Mint the layout id here if the region has never needed one. The sweep used to
-                // resolve an id-less region and simply not publish its rect (`if let Some(&id) =
-                // region_to_id.get(..)`) — an EditBox's implicit text FontString is exactly that
-                // shape, created and anchored by `SetTextInsets` and given an id only when extract
-                // or a measure first asks. The scope addresses nodes BY id, so it needs one; and
-                // minting it is pure addressing — it moves no rect, so unlike `Model::region_id`
-                // this does not touch the layout epoch (doing so would re-dirty the very resolve
-                // that is running).
+                // Mint an id for a region that never needed one, without `Model::region_id`'s
+                // epoch bump, which would re-dirty the running resolve.
                 let id = match region_to_id.get(&rh) {
                     Some(&id) => id,
                     None => {
@@ -1635,9 +1148,7 @@ impl UiScript {
                     *slot = region_node_hash(data);
                     scope.node_of[id as usize] = idx;
                 }
-                // A region reads its anchor targets' rects, and — for any axis its anchors do not
-                // pin — its OWNER's rect and scale. Both are dependencies; the owner one is the
-                // edge that carries a window moving to every unpinned texture inside it.
+                // A region reads its anchor targets' rects and its owner's scale.
                 for a in &data.anchors {
                     scope.edge(id, a.relative_to);
                 }
@@ -1651,47 +1162,23 @@ impl UiScript {
                     is_fontstring: matches!(r.kind, crate::widget::RegionKind::FontString),
                 });
             }
-            // Liveness only. The sweep also reads the region's `owner` and `kind`, but both are
-            // fixed at creation and can never change under a live handle; the owner's contribution
-            // to the result — its resolved rect and its `effective_scale` — rides the frame half
-            // (the scale is synced into `layout_inputs` by the preamble above, and the rect is the
-            // frame pass's own output). A DESTROYED region does still matter: `WidgetArena::destroy`
-            // drops the arena entry but leaves `region_data` behind, so membership alone would miss
-            // it and the sweep's `continue` would go unnoticed.
+            // Liveness only (`owner` and `kind` never change): `WidgetArena::destroy` leaves
+            // `region_data` behind, so membership alone would miss a destroyed region.
             fp.feed(u64::from(live.is_some()));
         }
-        // The count of FED entries (not the map's len — see the vacuous-entry skip above), so an
-        // entry leaving the anchored set is a change even if a sibling enters the same frame.
+        // The count of anchored entries fed, not the map's len.
         fp.feed(fed_regions);
         pre.fp_regions = pre.lap();
         fp
     }
 
-    /// FontStrings whose layout needs a host text measurement (an auto-sized axis — explicit
-    /// width and/or height of 0, the client's size-to-text idiom — text present, cache stale) —
-    /// the engine side of the measure round-trip. Call after [`UiScript::resolve`]; answer with
-    /// [`UiScript::set_measured_text`] and resolve again (the second solve is cheap and the cache
-    /// keys keep this empty on quiet frames). A zero WIDTH auto-sizes exactly like a zero height
-    /// (the real client sizes the rect to the unwrapped line — `<Size x="0" y="16"/>` labels like
-    /// the mail window's "From:" anchor their RIGHT edge and grow leftward); gating on height
-    /// alone left those rects zero-width and their anchored neighbours overlapping.
+    /// FontStrings with text whose stored measure is stale, for the host to measure: call after
+    /// [`UiScript::resolve`], answer with [`UiScript::set_measured_text`], and resolve again.
     pub fn fontstrings_needing_measure(&mut self) -> Vec<MeasureRequest> {
         let mut model = self.model_mut();
-        // ANY FontString with text — not only the auto-sized ones. A region with both axes
-        // declared needs no measure for its *layout*, but `GetStringWidth` still has to answer
-        // with the string's natural width, and only a measure can supply it (decision 0997: a
-        // kit that reads that number and then SETS a width on the string would otherwise stop
-        // receiving measures the instant it did so, and start reading its own box back).
-        //
-        // Asked off the MEASURE LEDGER, not the roster (the 1388 shape one lane over): the
-        // sweep existed to *discover* silent writes — `SetText` touches no layout until the
-        // extent moves — and discovery cost two whole-roster walks per frame at a city pin
-        // (~300 µs of the `resolve` lap, decision 1370) to conclude, almost always, that
-        // nothing was written. The write sites announce themselves now
-        // ([`Model::touch_measure`]); draining the ledger re-arms it, so the second ask of the
-        // same frame (`fill_measures`, inside `resolve`) sees only what was written *between*
-        // the asks — same-frame semantics unchanged. `None` (a fan-out that could not name its
-        // regions, or the initial state) is the old whole-roster walk, verbatim.
+        // Every FontString with text, sized or not: `GetStringWidth` answers the natural width.
+        // The ledger (`Model::touch_measure`) re-arms empty, so a second ask this frame sees only
+        // the writes since the first; `None` walks every region.
         let ledger = model.measure_dirty.take();
         model.measure_dirty = Some(Vec::new());
         let needy: Vec<RegionHandle> = match ledger {
@@ -1699,13 +1186,8 @@ impl UiScript {
                 dirty.sort_unstable_by_key(|rh| rh.fingerprint_bits());
                 dirty.dedup();
                 dirty.retain(|&rh| stale_measure_key(&model, rh).is_some());
-                // The completeness falsifier (on for every benilla-ui test): the ledger's whole
-                // correctness claim is that its enrolled sites cover every measure-key writer,
-                // and that claim is checked, not argued — the old discovery walk runs beside
-                // the drain and any row it finds that the ledger missed is a stale label
-                // waiting to ship, so it panics with the region named. The other direction is
-                // legal by construction (an enrolled same-value write drops out at the
-                // staleness check above).
+                // Under verify, the full walk runs beside the drain and panics on any stale region
+                // the ledger missed.
                 if layout_verify_enabled() {
                     let roster: Vec<RegionHandle> = model
                         .region_data
@@ -1734,12 +1216,7 @@ impl UiScript {
                 .filter(|&rh| stale_measure_key(&model, rh).is_some())
                 .collect(),
         };
-        // Re-enroll everything still stale: a request handed out is not an answer. The old
-        // discovery walk re-found an unanswered region every frame until `set_measured_text`
-        // landed (the no-measurer engine-test path answers a frame later; a dropped request
-        // would otherwise go stale FOREVER now that nothing walks the roster), so the ledger
-        // keeps asking too. With a synchronous measurer the answer lands before the next drain
-        // and the staleness check drops the re-enrolled handle for free.
+        // Re-enroll every stale region: a request is not an answer, and nothing else asks again.
         if let Some(list) = &mut model.measure_dirty {
             list.extend(needy.iter().copied());
         }
@@ -1752,11 +1229,8 @@ impl UiScript {
         out
     }
 
-    /// Push one [`QuadContent::Backdrop`] per piece of frame `fh`'s installed backdrop (no-op if the
-    /// frame has none). Pieces carry the frame slot's `z` — behind the frame's regions (which sort
-    /// after it) and, among themselves, bg-then-border in paint order (the stable z-sort keeps the
-    /// emission order). Each piece's rect is its screen bounding box; the app resolves the texture
-    /// from the piece path and multiplies the tint by the [`FramePaint`]'s alpha.
+    /// Push one [`QuadContent::Backdrop`] per piece of frame `fh`'s backdrop, at the frame slot's
+    /// `z`: behind its regions, and background before border by the stable sort.
     pub(super) fn emit_backdrop(
         model: &Model,
         fh: FrameHandle,
@@ -1770,8 +1244,8 @@ impl UiScript {
             return;
         };
         for piece in backdrop::pieces(fr, bd) {
-            // The piece's screen bounding box (the render is axis-aligned; the BR-inset bug's slant,
-            // invisible for the symmetric insets every shipping backdrop uses, collapses to the box).
+            // The piece's screen bounding box: the render is axis-aligned, so the reference's slant
+            // under unequal top and bottom insets is not drawn (stock insets are symmetric).
             let xs = piece.corners.map(|c| c[0]);
             let ys = piece.corners.map(|c| c[1]);
             let (left, right) = (
@@ -1811,13 +1285,8 @@ impl UiScript {
     }
 }
 
-/// The [`MeasureRequest`] region `rh` needs right now, or `None` if it needs none — it is not a
-/// FontString, it holds no text, or its stored measure is already this exact string's.
-///
-/// Hoisted out of [`UiScript::fontstrings_needing_measure`] so the **synchronous** measure
-/// ([`super::measure::ensure_measured`]) builds its request with the identical recipe. The two must
-/// agree byte for byte on the cache key, or a same-tick measure and the batch pass would each think
-/// the other's answer was stale and re-measure forever.
+/// The [`MeasureRequest`] region `rh` needs now, if any; shared with the synchronous measure
+/// ([`super::measure::ensure_measured`]), as both must build the same cache key.
 pub(super) fn measure_request_for(model: &mut Model, rh: RegionHandle) -> Option<MeasureRequest> {
     let (key, scale) = stale_measure_key(model, rh)?;
     let d = model.region_data.get(&rh)?;
@@ -1841,18 +1310,14 @@ pub(super) fn measure_request_for(model: &mut Model, rh: RegionHandle) -> Option
     })
 }
 
-/// The staleness half of [`measure_request_for`], allocation-free: `Some((key, scale))` iff `rh`
-/// is a FontString holding text whose stored measure no longer matches its current key. This is
-/// the ONE place the "does this region need a measure?" question is answered — the per-frame
-/// sweep ([`super::UiScript::fontstrings_needing_measure`]) asks it for every FontString, so it
-/// must not clone; the request build above pays the clones only after this says stale.
+/// `Some((key, scale))` iff `rh` is a FontString with text whose stored measure no longer matches
+/// its key: the one staleness test, allocation-free as the sweep asks it of every FontString.
 fn stale_measure_key(model: &Model, rh: RegionHandle) -> Option<(u64, f32)> {
     let region = model.arena.region(rh)?;
     if !matches!(region.kind, crate::widget::RegionKind::FontString) {
         return None;
     }
-    // The owner's effective_scale: the host measures at the drawn raster size
-    // ([`MeasureRequest::scale`]), and the key carries it so a SetScale re-measures.
+    // The host measures at the drawn size, so the key carries the owner's scale.
     let scale = model
         .arena
         .frame(region.owner)
@@ -1862,8 +1327,7 @@ fn stale_measure_key(model: &Model, rh: RegionHandle) -> Option<(u64, f32)> {
     if d.text.as_deref().is_none_or(|t| t.is_empty()) {
         return None;
     }
-    // The shared key recipe ([`RegionData::measure_key`]) — the metric reads (region.rs) check the
-    // stored measure against the same hash.
+    // The metric reads in `region.rs` check the stored measure against this same key.
     let key = d.measure_key(scale);
     if d.measured.map(|m| m.key) == Some(key) {
         return None;
diff --git a/crates/benilla-ui/src/script/layout_cache.rs b/crates/benilla-ui/src/script/layout_cache.rs
index b62bac21..44516c4b 100644
--- a/crates/benilla-ui/src/script/layout_cache.rs
+++ b/crates/benilla-ui/src/script/layout_cache.rs
@@ -1,54 +1,11 @@
-//! The **layout cache** — the consumer `Frame::user_placed` never had.
+//! The layout cache: the reference writes a per-character `layout-cache.txt` at logout and seats
+//! the user-placed frames from it at load (userPlaced is `frame+0xb4 & 0x1000`). This is the
+//! engine half, a snapshot out, a restore in and a dirty bit; the app owns the file
+//! (`benilla_app::ui_layout`).
 //!
-//! `SetUserPlaced` / the drag entries set the client's userPlaced bit (`frame+0xb4 & 0x1000`,
-//! [`super::object::movable`]), and together with the frame's own `movable`/`resizable` flags it
-//! means *"the player put this window here; put it back next time"*. The real client honours that
-//! by writing a per-character `layout-cache.txt` at logout and seating the frames from it at load;
-//! benilla had the bit and nothing that read it, so a dragged or resized window went back to its
-//! authored anchors on the next login.
-//!
-//! **The bit is not the whole gate**, at either end — see [`super::UiScript::user_placed_layouts`]
-//! and [`super::UiScript::restore_user_placed_layouts`] for the conjuncts and their byte sites.
-//! Reading it as the whole gate is what let one addon's stamp seat a stock frame forever
-//! (decision 2193).
-//!
-//! This module is the **engine half** of that: a snapshot out, a restore in, and a dirty bit for
-//! the host to debounce on. Where the file lives, when it is written and which character owns it
-//! are the app's ([`benilla_app::ui_layout`] — `benilla-config/layout/<realm>-<character>.txt`,
-//! through `local_state`, like every other resident of that folder).
-//!
-//! ## Why a host seam at all, when `GetPoint`/`SetPoint` exist
-//!
-//! Everything *about one frame* is already Lua-reachable — `GetNumPoints`, `GetPoint`, `GetWidth`,
-//! `GetHeight`, `IsUserPlaced`, `SetPoint`, `SetWidth`, `SetHeight` — and if the saver knew which
-//! frames to ask about, it would need nothing here. **Enumeration is the part Lua cannot do**:
-//! there is no `EnumerateFrames` in 1.12 and inventing one would be a far wider surface than the
-//! three functions below. The alternative — a hand-maintained list of names in FrameXML — is a
-//! list that goes stale the first time a window becomes movable and nobody remembers to add it,
-//! which is the failure mode the *bit* exists to prevent.
-//!
-//! So the seam is deliberately three calls wide and mirrors the chat-look seam next door
-//! (`chat_window_looks` / `set_chat_window_looks` / `take_chat_window_changes`, decision 1589):
-//! [`super::UiScript::user_placed_layouts`], [`super::UiScript::restore_user_placed_layouts`] and
-//! [`super::UiScript::take_user_placed_change`].
-//!
-//! ## What a saved frame carries
-//!
-//! Its **name**, its **width/height**, and its **whole anchor list** — point, target, relative
-//! point, offsets — because that is what `GetPoint` answers and what `SetPoint` takes. A frame is
-//! addressed by name in the file for the obvious reason: handles are minted per session and mean
-//! nothing across a relog.
-//!
-//! Two anchor targets survive the round trip and everything else drops the frame's row rather than
-//! guessing:
-//!
-//! - the **screen root** ([`super::SCREEN`]) — written as no target, which is exactly what
-//!   `GetPoint` answers there (`nil`, decision 0068's stated `UIParent` divergence);
-//! - a **named frame** — written by name.
-//!
-//! An anchor onto an unnamed frame or onto a *region* cannot be re-addressed at load, so a frame
-//! carrying one is skipped **whole**. Restoring half an anchor set would seat a window somewhere
-//! nobody put it, which is worse than leaving it on its authored anchors.
+//! A saved frame carries its name, size and whole anchor list. An anchor's target is the screen
+//! root (saved as no target, the `nil` `GetPoint` answers there) or a named frame; a frame anchored
+//! to anything else is skipped whole, never half-restored.
 
 use crate::layout::Anchor;
 use crate::widget::FrameHandle;
@@ -61,24 +18,22 @@ use super::{Model, SCREEN};
 pub struct LayoutPoint {
     /// The point on the saved frame (`"BOTTOMLEFT"`, …).
     pub point: String,
-    /// The frame this anchor is relative to, by name; `None` is the screen root, which is what
-    /// `GetPoint` reports as `nil`.
+    /// The target frame's name; `None` is the screen root, which `GetPoint` reports as `nil`.
     pub relative_to: Option<String>,
     /// The point on the target.
     pub relative_point: String,
-    /// The anchor's x offset, in the frame's own (pre-scale) units — `CAnchor+0x4`.
+    /// `CAnchor+0x4`, in the frame's own pre-scale units.
     pub x: f32,
-    /// The anchor's y offset — `CAnchor+0x8`.
+    /// `CAnchor+0x8`.
     pub y: f32,
 }
 
-/// One user-placed frame's persisted geometry: what a layout cache has to hold to put a window
-/// back exactly where the player left it.
+/// One user-placed frame's persisted geometry.
 #[derive(Clone, Debug, PartialEq)]
 pub struct FrameLayout {
-    /// The frame's global name — how the row is addressed across sessions.
+    /// The frame's global name, which addresses the row across sessions.
     pub name: String,
-    /// The frame's authored width (`LayoutInput::width`), which is what a resize drag writes.
+    /// The frame's authored width (`LayoutInput::width`), which a resize drag writes.
     pub width: f32,
     /// The frame's authored height.
     pub height: f32,
@@ -87,24 +42,11 @@ pub struct FrameLayout {
 }
 
 impl super::UiScript {
-    /// Snapshot every frame the reference's writer would write — the save path.
-    ///
-    /// Sorted by name so the file is stable: a rewrite that reorders its own lines makes every
-    /// diff useless and every "did this change?" check a false positive. Frames whose anchors
-    /// cannot be re-addressed by name are dropped (see the module doc), as are unnamed ones —
-    /// there is nothing to write them under.
-    ///
-    /// **The filter is `userPlaced AND (movable OR resizable)`, not the bit alone.** The
-    /// reference's per-frame writer `0x490e60` tests four conjuncts in a row: a non-NULL name
-    /// (`0x490e79`), a non-empty one (`0x490e82`), `userPlaced` (`0x490e8e test ah,0x10` =
-    /// `0x1000`) and **`movable|resizable`** (`0x490e97 test ah,0x3` = `0x100|0x200`). The bit
-    /// alone was benilla's whole filter until decision 2193, and the missing fourth conjunct is
-    /// what made this cache a one-way ratchet: **every** drag entry stamps `userPlaced`
-    /// (`0x7652b0` @`0x7652e5`, with no cursor-movement dependency), so an addon that windows a
-    /// stock frame and stamps it in passing — `Cartographer/Modules/LookNFeel.lua`'s
-    /// `StartMoving(); StopMovingOrSizing()` over `WorldMapFrame` — wrote a row that outlived
-    /// the addon on every character, forever. The reference drops that row at the first logout
-    /// the addon does not load, because the frame's own `movable`/`resizable` flags went with it.
+    /// Snapshot, sorted by name so the file is stable, every frame the reference's writer
+    /// (`0x490e60`) writes: a non-empty name (`0x490e79`, `0x490e82`), `userPlaced` (`0x490e8e`,
+    /// `0x1000`) and `movable` or `resizable` (`0x490e97`, `0x100|0x200`), with every anchor
+    /// nameable. Every drag stamps `userPlaced` (`0x7652b0` at `0x7652e5`), so the last test is
+    /// what drops the row of a stock frame an addon once moved, once that addon is gone.
     pub fn user_placed_layouts(&self) -> Vec<FrameLayout> {
         let model = self.model_ref();
         let mut out: Vec<FrameLayout> = model
@@ -131,40 +73,22 @@ impl super::UiScript {
         out
     }
 
-    /// Seat saved geometry back onto the frames that still exist — the load path.
-    ///
-    /// Each row is applied whole or not at all: a name this build has no frame for, a point name
-    /// that does not parse, or a target frame that is not loaded leaves the frame on its authored
-    /// anchors rather than half-seated. Restoring **sets the userPlaced bit**, which is what keeps
-    /// the position: `UIParent_ManageFramePositions` skips a user-placed frame, so the managed
-    /// bottom-stack pass does not re-seat the window the player moved.
-    ///
-    /// **The apply is gated per ARM, not per row** (`0x4905e0`, decision 2193): the position arm
-    /// is behind the frame's own `movable` bit (`0x490600 test ah,0x1`) and the size arm behind
-    /// `resizable` (`0x490689 test ah,0x2`) — a frame carrying neither is left entirely alone,
-    /// however old and however stamped its row is. The userPlaced stamp itself lives **inside**
-    /// each arm (`0x49067e` in the position arm, `0x490706` in the size one), after that arm's
-    /// own "the row carries no position" bail
-    /// (`0x490613`, the reference's `X == 0 && Y == 0`; the size arm's twin is `0x49069a`'s
-    /// `W == 0 && H == 0`). Both bails are spelled in this payload's own terms rather than the
-    /// reference's integer sentinels: a row that carries no anchors, and a row that carries no
-    /// size, are the same two states in a format that stores an anchor list instead of an X/Y
-    /// pair.
-    ///
-    /// It marks nothing dirty — the values came *from* the file, and an echo would re-dirty what
-    /// was just read (`set_chat_window_looks`' reasoning, one store over).
+    /// Seat saved geometry back onto the frames that exist, each row whole or not at all. The
+    /// apply is per arm (`0x4905e0`): the position needs `movable` (`0x490600`) and anchors (the
+    /// no-position bail, `0x490613`), the size needs `resizable` (`0x490689`) and a non-zero size
+    /// (`0x49069a`), and each arm that applies stamps `userPlaced` (`0x49067e`, `0x490706`), which
+    /// keeps `UIParent_ManageFramePositions` off the frame. Marks nothing dirty: the values came
+    /// from the file.
     pub fn restore_user_placed_layouts(&mut self, layouts: impl IntoIterator<Item = FrameLayout>) {
         let mut model = self.model_mut();
         for l in layouts {
             let Some(h) = model.arena.lookup(&l.name) else {
-                continue; // a window this build does not have — the file outlives a rename
+                continue; // a window this build does not have
             };
             let mut anchors: Vec<Anchor> = Vec::with_capacity(l.points.len());
             let mut usable = true;
             for p in &l.points {
-                // `frame_id`, not a `frame_to_id` read: ids are minted lazily, so a target frame
-                // that nothing has anchored to yet has none — and refusing the row for that would
-                // make the restore depend on load order.
+                // `frame_id` mints the id lazily, so a target nothing has anchored to yet resolves.
                 let rel = match &p.relative_to {
                     None => Some(SCREEN),
                     Some(n) => model.arena.lookup(n).map(|t| model.frame_id(t)),
@@ -210,32 +134,26 @@ impl super::UiScript {
                 input.width = l.width;
                 input.height = l.height;
             }
-            // The stamp is EACH arm's, not the row's: the position arm's is `0x49067e` and the
-            // size arm's `0x490706`, both inside their own gate. A frame that took neither is
-            // left un-stamped, which is what lets its row fall out of the file.
+            // Only an arm that applied stamps, so a row neither arm took falls out of the file.
             if seat_position || seat_size {
                 if let Some(f) = model.arena.frame_mut(h) {
                     f.user_placed = true;
                 }
             }
             if changed {
-                // The whole graph, not the frame alone: a restore REPOINTS anchors (a saved row
-                // may name a different target than the authored one), and decision 1388's
-                // frame-scoped touch is only valid while every anchor keeps its target.
+                // The whole graph, not the frame: a restored row may repoint an anchor.
                 model.touch_layout();
             }
         }
     }
 
-    /// Has a user-placed frame moved or resized since the last call? The host's cue to persist —
-    /// a single bit rather than a set, because the file is written whole either way.
+    /// Whether a user-placed frame moved or resized since the last call: the host's cue to persist.
     pub fn take_user_placed_change(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().user_placed_changed)
     }
 }
 
-/// One live anchor → its saved form, or `None` when the target cannot be named across a session
-/// (an unnamed frame, or a region — see the module doc).
+/// An anchor's saved form, or `None` when its target is an unnamed frame or a region.
 fn saved_point(model: &Model, a: &Anchor) -> Option<LayoutPoint> {
     let relative_to = if a.relative_to == SCREEN {
         None
diff --git a/crates/benilla-ui/src/script/loot.rs b/crates/benilla-ui/src/script/loot.rs
index 97387028..89fa132d 100644
--- a/crates/benilla-ui/src/script/loot.rs
+++ b/crates/benilla-ui/src/script/loot.rs
@@ -1,199 +1,104 @@
-//! The loot bindings (decision 0084) — the Era-shaped loot-window surface, the same two-way seam as
-//! [`super::merchant`]/[`super::container`]/[`super::gossip`]: the app pushes a **loot snapshot**
-//! ([`UiScript::set_loot`] — the rows already resolved from the wire to name/icon/quantity/quality by
-//! the app's item stores, with the synthesized coin row first) and the Lua `LootSlot`/`CloseLoot`
-//! calls queue outbound **intents** the app drains ([`UiScript::take_loot_picks`] /
-//! [`UiScript::take_loot_close`]). The engine holds no loot knowledge — a row is "a name, an icon
-//! path, a quantity, a quality, and whether it's the coin pile".
+//! The loot-window bindings: the app pushes the open loot ([`UiScript::set_loot`]), a coin row
+//! first when there is gold, and the Lua verbs queue intents it drains. `slot` is 1-based; the app
+//! maps a row to the money intent or the item's wire slot, which Lua never sees.
 //!
-//! ## The Era API shape
-//!
-//! 1.12's loot API is a flat set of globals the FrameXML `LootFrame.lua` drives (VERIFIED against the
-//! extracted `LootFrame.lua`, scratchpad): `GetNumLootItems()`, `GetLootSlotInfo(slot)` →
-//! `texture, item, quantity, quality` (`LootFrame.lua:81`), `LootSlotIsItem(slot)` /
-//! `LootSlotIsCoin(slot)` (`LootFrame.lua:80`), `GetLootSlotLink(slot)` → the row's item link (what
-//! the row click's ctrl/shift arms read, `LootFrame.lua:149`/`:152` — decision 1059),
-//! and `CloseLoot()` (fired from `OnHide`, `LootFrame.lua:143-145`). `slot` is **1-based**; an
-//! out-of-range slot answers `nil`.
-//!
-//! ## The take is TWO verbs, not one (decision 1744)
-//!
-//! `LootSlot(slot)` looks like "loot row n" and is not: in 1.12 it is the **LOOT_BIND confirmation
-//! continuation** alone. The C dispatcher `0x4c2790(slot, flag)` takes the row only on `flag == 0`,
-//! which no Lua binding reaches — the row click is the C `CLootButton`'s own behaviour — while
-//! `LootSlot 0x4c2e70` passes `flag = 1`, whose arm refuses every slot but the one a bind confirm
-//! is pending for. benilla builds that widget — [`crate::widget::FrameKind::LootButton`], decision
-//! 1799 — so the row click's take runs where the reference runs it, in `script::button`'s click
-//! path under the same no-modifier gate; `BenillaTakeLootSlot` is the Lua-reachable entry to the
-//! same queue, and `LootSlot` keeps the reference's meaning exactly.
-//!
-//! The **coin pile is a synthesized client-side row** (first in the list when the loot carries gold):
-//! `LootSlotIsCoin` is true for it, its `item` text is the formatted money amount, and `LootSlot(1)`
-//! on it queues the money intent. The app maps a clicked 1-based row to either the money intent or the
-//! wire loot slot the item lives at (`CMSG_AUTOSTORE_LOOT_ITEM` addresses the **wire** slot, which is
-//! *not* the 1-based display position once a coin row is prepended or a row is removed) — the Lua side
-//! never sees the wire slot, exactly as the merchant's Lua side never sees the item entry.
-//!
-//! ## Master loot (decision 1675)
-//!
-//! Two more globals ride the same seam when the group's loot method is master loot:
-//! `GetMasterLootCandidate(index)` reads [`LootState::master_candidates`] (names, 1-based, dense)
-//! and `GiveMasterLoot(slot, candidateIndex)` queues an assignment the app resolves to a wire slot
-//! and a recipient guid. The *decision* to open the dropdown is not Lua's: the app fires
-//! `OPEN_MASTER_LOOT_LIST` when a picked row's wire `slot_type` is `MASTER`, which is where the
-//! real client puts it too — its take dispatcher branches on the same byte before any Lua runs.
+//! `LootSlot` is only the LOOT_BIND confirmation: `0x4c2e70` passes flag 1 to the take dispatcher
+//! `0x4c2790`, which then refuses every slot but the pending one. The take itself is flag 0, the
+//! row click of [`crate::widget::FrameKind::LootButton`]. Master loot's dropdown opens from the
+//! app, on a picked row whose wire `slot_type` is `MASTER`, as the dispatcher branches on that byte
+//! before any Lua runs.
 
 use mlua::{Lua, MultiValue, Table, Value};
 
 use super::binding_abi::flag;
 use super::Model;
 
-/// `CLootButton`'s own Lua method table (`0x847ce4`) — see [`crate::widget::FrameKind::LootButton`].
-/// Exactly one entry, and the count is read off the registrar's `mov edx,1` rather than off a run
-/// length, so it cannot drift.
+/// `CLootButton`'s own Lua method table (`0x847ce4`): one entry, per the registrar's `mov edx,1`.
 pub(super) const REG_LOOTBUTTON_METHODS: &str = "__benilla_lootbutton_methods";
 
-/// The **item-cache miss** quality `GetLootSlotInfo` answers for a row whose item template has not
-/// landed yet — the reference's own sentinel, and emphatically **not** a nil. `0x4c23a0` reads the
-/// item-cache record's `[rec+0x1c]` and hands back `-1` when the cache has no record for the id.
-///
-/// It is why stock `UIParent.lua` builds `ITEM_QUALITY_COLORS` over **`for i = -1, 6`** (l.66):
-/// index `-1` exists *for this value*. `LootFrame_Update` indexes the table with the raw return and
-/// no guard — `color = ITEM_QUALITY_COLORS[quality]` (`LootFrame.lua:82`), dereferenced one line
-/// later at `color.r` (`:85`) — so a nil here is a Lua runtime error on every loot opened before
-/// its templates arrive, which is every loot on a cold item cache (decision 1805).
+/// The quality `GetLootSlotInfo` answers on an item-cache miss: the reference's -1 (`0x4c23a0`),
+/// never nil. Stock `UIParent.lua:66` builds `ITEM_QUALITY_COLORS` from -1, and `LootFrame_Update`
+/// indexes it unguarded (`LootFrame.lua:82`), so a nil would raise on a cold cache.
 const CACHE_MISS_QUALITY: i64 = -1;
 
-/// The row text on that same miss. The reference composes every loot row's name through `0x5d8b00`,
-/// which leaves its destination buffer **empty** when the item cache has no record (`0x5d8b25`
-/// stores the terminator and returns); the binding then pushes that empty string. Four values, one
-/// of them `""` — never three values, and never a nil.
+/// The row text on that miss: `0x5d8b00` leaves its buffer empty with no cache record
+/// (`0x5d8b25`), and the binding pushes that empty string.
 const CACHE_MISS_NAME: &str = "";
 
-/// The icon on an `ItemDisplayInfo` miss — a row that HAS an item, whose display id the catalog has
-/// no icon for. The reference appends the literal `INV_Misc_QuestionMark` (`0x847fe4`, `0x4c252b`)
-/// to the same `StringLookups.dbc` row-3 prefix (`Interface\\Icons`) a hit uses.
-///
-/// It is deliberately **not** the answer for a slot with no item: `0x4c2460` returns NULL on each of
-/// its three guards (`0x4c2470` no window, `0x4c24a6` out of range, `0x4c24b7` itemId == 0) and
-/// `lua_pushstring 0x6f3890` tail-jumps a NULL to `lua_pushnil`. The question mark needs a live
-/// itemId to be reached at all.
+/// The icon for a row with an item but no display icon: `INV_Misc_QuestionMark` (`0x847fe4`,
+/// `0x4c252b`). A slot with no item gets nil instead: `0x4c2460` returns NULL on its three guards
+/// (`0x4c2470`, `0x4c24a6`, `0x4c24b7`), which `lua_pushstring 0x6f3890` pushes as nil.
 const MISSING_ICON: &str = "Interface\\Icons\\INV_Misc_QuestionMark";
 
-/// The quality a slot with **no item at all** answers — a slot past the end, Lua slot 0, or any slot
-/// while no loot window is open. `0x4c23a0` returns 0 on each of its three guards, and the binding
-/// `fild`s that. Distinct from [`CACHE_MISS_QUALITY`]: a **cleared** slot still has a record, whose
-/// itemId is now 0, and `0x55ba30` short-circuits an entryId of 0 to a NULL record
-/// (`0x55ba3d`/`0x55ba42`) — a guaranteed cache miss, so it takes the `-1` arm at `0x4c2435`.
+/// The quality of a slot with no item (past the end, slot 0, no window): `0x4c23a0`'s guards
+/// return 0. A cleared slot takes -1 instead: its itemId is 0, which `0x55ba30` turns into a NULL
+/// record (`0x55ba3d`/`0x55ba42`), the cache-miss arm at `0x4c2435`.
 const NO_SLOT_QUALITY: i64 = 0;
 
-/// One loot-window row, resolved by the app (decision 0084). Plain data — its 1-based order in the
-/// window is its position in [`LootState::rows`]; the coin row (when present) is always position 1.
+/// One loot-window row, resolved by the app; its 1-based slot is its place in [`LootState::rows`].
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct LootRow {
-    /// The row text (`GetLootSlotInfo`'s `item` return): an item's name, or the coin row's formatted
-    /// money amount. `None` while the ask-once item-template query is still in flight (items only —
-    /// the coin row's text is always set), and the API reports [`CACHE_MISS_NAME`] — the empty
-    /// string the reference's own name formatter leaves behind on a cache miss — never a nil.
+    /// Item name or the coin's money text; `None` while in flight, answered as [`CACHE_MISS_NAME`].
     pub name: Option<String>,
-    /// Icon texture path (`Interface\Icons\…` — from the wire `display_info_id`, or the coin
-    /// texture). `None` only if the display catalog had no icon for the id, which the API reports as
-    /// [`MISSING_ICON`], the reference's own `INV_Misc_QuestionMark`.
+    /// Icon path; `None` without a display icon, answered as [`MISSING_ICON`].
     pub texture: Option<String>,
-    /// The stack size looted (`GetLootSlotInfo`'s `quantity`); the coin row is always `1`.
+    /// Stack size looted; 1 for the coin row.
     pub quantity: u32,
-    /// Item quality 0..6, for the quality-coloured row text; `None` while the template is in flight,
-    /// which the API reports as [`CACHE_MISS_QUALITY`] (`-1`, the reference's cache-miss sentinel and
-    /// a real row of `ITEM_QUALITY_COLORS`) — never a nil, which is what raised in the stock
-    /// `LootFrame_Update` (decision 1805). The coin row carries a fixed quality.
+    /// Quality 0..6; `None` while the template is in flight, answered as [`CACHE_MISS_QUALITY`].
     pub quality: Option<u32>,
-    /// Whether this is the synthesized coin pile (`LootSlotIsCoin` true, `LootSlotIsItem` false).
+    /// The synthesized coin pile (`LootSlotIsCoin` true, `LootSlotIsItem` false).
     pub is_coin: bool,
-    /// The item id — the shared item-tooltip store's key (`BenillaGetItemStats`); `0` for the coin
-    /// row. A benilla extension riding as a TRAILING return of `GetLootSlotInfo` (the era 4-tuple
-    /// never carried it; tooltip content was C++'s alone), same idiom as the quest item getters.
+    /// The tooltip store's key, 0 for the coin row: `GetLootSlotInfo`'s fifth return, not 1.12's.
     pub item_id: u32,
-    /// The row's full escaped `|cff…|Hitem:…|h[Name]|h|r` link (`GetLootSlotLink`, decision 1059).
-    /// `None` for the synthesized coin row (there is no item to link) and while the ask-once
-    /// template answer is in flight — the link embeds the name, so it cannot exist before `name`
-    /// does; the same `Option` shape [`super::char_stats::InvSlotView::link`] carries. Both arms of
-    /// the STOCK row click take a nil in stride: `DressUpItemLink` returns on one (its own guard,
-    /// `DressUpFrame.lua:10-16`), and `ChatFrameEditBox:Insert` takes an `Option<String>`
-    /// ([`super::editbox`]) so the other drops it silently.
+    /// `GetLootSlotLink`'s answer; `None` for the coin row and while the template is in flight.
     pub link: Option<String>,
-    /// The wire's `randomPropertyId` — the drop's **random-suffix roll**, the id the tooltip
-    /// resolves against [`super::Model::random_properties`] for its enchant lines (decision 1547).
-    /// `0` = unrolled.
-    ///
-    /// The client keeps exactly this, at `+0x14` of its own 0x1c-byte loot record, and
-    /// `SetLootItem 0x533470` copies it into the tooltip's `+0x424` — a loot slot is **not** an
-    /// item object (that leg passes an all-zero item guid), so the roll is the only enchant source
-    /// a loot hover can have. [`Self::name`] already carries the suffix the same id joins on.
+    /// The drop's random-suffix roll (`randomPropertyId`, 0 unrolled), resolved by the tooltip
+    /// against [`super::Model::random_properties`]. A loot slot is no item object, so this is its
+    /// only enchant source (`SetLootItem 0x533470` copies it from the loot record's `+0x14`).
     pub random_property_id: u32,
 }
 
-/// One open loot window: its rows (coin first when present). Pushed whole by the app; `None` means no
-/// loot is open (the window is closed).
+/// One open loot window, pushed whole by the app; `None` means no loot is open.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct LootState {
-    /// The window's **fixed** slot list: positions never shift while the window is open. A looted
-    /// slot becomes `None` — still counted by `GetNumLootItems` (the reference's slot array keeps
-    /// cleared slots; `LootFrame.numLootItems` is captured once at `OnShow`, l.132) but neither
-    /// `LootSlotIsItem` nor `LootSlotIsCoin`, which is exactly how the reference's
-    /// `LootFrame_Update` leaves a cleared slot's button hidden in place (`LootFrame.lua:80`)
-    /// instead of collapsing the rows below it upward.
+    /// The fixed slot list. A looted slot becomes `None`: still counted by `GetNumLootItems`, read
+    /// once at `OnShow` (`LootFrame.lua:132`), but neither item nor coin, so `LootFrame_Update`
+    /// hides its button in place (`LootFrame.lua:80`).
     pub rows: Vec<Option<LootRow>>,
-    /// Whether this loot came from fishing (`IsFishingLoot()` — the wire `SMSG_LOOT_RESPONSE`
-    /// `loot_type == 3`, decision 1086). `LootFrame_OnShow` keys the "FISHING REEL IN" sound and
-    /// the FishingLoot portrait overlay on it (`LootFrame.lua:137-140`).
+    /// `IsFishingLoot` (wire `loot_type` 3): the reel-in sound and portrait (`LootFrame.lua:137`).
     pub fishing: bool,
-    /// The master-loot candidate slots — what `GetMasterLootCandidate(i)` answers for a 1-based
-    /// `i` (decision 1675). Empty unless the group's loot method is master loot and the server
-    /// sent `SMSG_LOOT_MASTER_LIST` for this window.
-    ///
-    /// **A `None` is a real slot that answers nil**, not padding, and the list is deliberately
-    /// not packed: in a raid the client files each candidate into its own subgroup's five-slot
-    /// block, so index `i` carries which raid group the candidate is in. That is what lets
-    /// `GroupLootDropDown_Initialize` walk `1..40` in blocks of five and label each block
-    /// "Group N" (`LootFrame.lua:186-212`). A `None` also covers a candidate whose name has not
-    /// resolved yet — the binding pushes nil for that too, and `UPDATE_MASTER_LOOT_LIST` exists
-    /// to repaint the menu when it lands.
-    ///
-    /// Names, not guids: the seam's standing division is that Lua speaks names and 1-based
-    /// indices while the app owns guids and wire slots, and `GroupLootDropDown_Initialize` puts
-    /// this string straight into `info.text` (`LootFrame.lua:181`/`:229`).
+    /// The names `GetMasterLootCandidate(i)` answers by 1-based slot, from `SMSG_LOOT_MASTER_LIST`.
+    /// Not packed: in a raid each candidate sits in their subgroup's five-slot block, which the
+    /// dropdown labels "Group N" (`LootFrame.lua:197-213`). A `None` (an empty slot, or a name not
+    /// yet resolved) answers nil.
     pub master_candidates: Vec<Option<String>>,
 }
 
 impl super::UiScript {
-    /// Push (or clear, with `None`) the open loot's row snapshot.
+    /// Push (or clear, with `None`) the open loot.
     pub fn set_loot(&mut self, state: Option<LootState>) {
         self.model_mut().loot = state;
     }
 
-    /// Drain the 1-based row indices queued by `BenillaTakeLootSlot` since the last call — the ROW
-    /// CLICK's take. The app maps each to either the coin (money) intent or the item's wire loot
-    /// slot, and applies the bind-on-pickup deferral (decision 1744).
+    /// Drain the 1-based rows the row click took; the app maps each to the coin or the item's wire
+    /// slot and applies the bind-on-pickup deferral.
     pub fn take_loot_picks(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().loot_picks)
     }
 
-    /// Drain the 1-based row indices queued by `LootSlot` — the LOOT_BIND confirmation
-    /// continuations. Each is honoured only if it names the row the app is actually holding a
-    /// confirm open for (the reference's `[0x847cec]` gate); anything else is dropped.
+    /// Drain the 1-based rows `LootSlot` queued; the app honours only the one a LOOT_BIND confirm
+    /// is pending for (the reference's `[0x847cec]` gate).
     pub fn take_loot_confirms(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().loot_confirms)
     }
 
-    /// Whether `CloseLoot` was called since the last drain (and clear the flag). The app maps this to
-    /// `CMSG_LOOT_RELEASE` when a loot is open.
+    /// Whether `CloseLoot` was called since the last drain; the app releases an open loot.
     pub fn take_loot_close(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().loot_close)
     }
 
-    /// Drain the `GiveMasterLoot(slot, candidateIndex)` assignments queued since the last call —
-    /// both 1-based display numbers. The app resolves the row to its wire slot and the candidate
-    /// to a guid, then sends `CMSG_LOOT_MASTER_GIVE` (decision 1675).
+    /// Drain the `GiveMasterLoot(slot, candidateIndex)` pairs, both 1-based; the app resolves them
+    /// to a wire slot and a guid for `CMSG_LOOT_MASTER_GIVE`.
     pub fn take_loot_master_gives(&mut self) -> Vec<(u32, u32)> {
         std::mem::take(&mut self.model_mut().loot_master_gives)
     }
@@ -203,9 +108,7 @@ impl super::UiScript {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetNumLootItems() → the number of slots the open loot has, cleared ones included (0 when none
-    // is open). Constant while a window is open — the reference reads it once at OnShow (l.132) and
-    // never again; ours is invariant by construction, so the live read is the same value.
+    // GetNumLootItems(): cleared slots included, so it holds still while a window is open.
     g.set(
         "GetNumLootItems",
         lua.create_function(|lua, ()| {
@@ -214,28 +117,14 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetLootSlotInfo(slot) → texture, item, quantity, quality — the reference's four, in its order
-    // (`0x4c2c60`, `mov eax,4` at `0x4c2d07`; `LootFrame.lua:81`). `slot` is 1-based.
-    //
-    // **It answers four values on every leg — never three, never a bare nil** (decision 1805).
-    // A slot with no item at all (past the end, slot 0, no window) is `nil, "", 0, 0`; a CLEARED
-    // slot is `nil, "", 0, -1`, because its record survives with a zeroed itemId and that is a
-    // guaranteed item-cache miss.
-    //
-    // A LIVE row is the same story one level down: each producer has a sentinel for the case where
-    // the value it wants is not resolved yet — [`CACHE_MISS_QUALITY`] (`-1`) and [`CACHE_MISS_NAME`]
-    // (`""`) while the item template is in flight, [`MISSING_ICON`] when the display catalog has no
-    // icon for the wire display id. The quality is the load-bearing one: the reference's
-    // `ITEM_QUALITY_COLORS` has a `-1` row precisely so this value can index it.
-    //
-    // The in-flight row is nonetheless one the REFERENCE never paints, because it does not open the
-    // window until every template has landed ([`crate::script`] has no say in that; the app's
-    // `ui_loot` holds `LOOT_OPENED` back). These sentinels are the floor under that, not the plan.
+    // GetLootSlotInfo(slot) → texture, item, quantity, quality (`0x4c2c60`, `LootFrame.lua:81`),
+    // four on every leg (`0x4c2d07 mov eax,4`): no item is `nil, "", 0, 0`, a cleared slot
+    // `nil, "", 0, -1`. The miss sentinels are a floor: the reference opens no window before every
+    // template lands, and the app holds `LOOT_OPENED` back likewise.
     g.set(
         "GetLootSlotInfo",
         lua.create_function(|lua, slot: usize| {
-            // `Some(Some(row))` is a live row; `Some(None)` is a CLEARED one (the slot survives with
-            // its record zeroed); `None` is no such slot at all.
+            // `Some(Some(row))` live, `Some(None)` cleared, `None` no such slot.
             let slot_state = {
                 let model = lua.app_data_ref::<Model>().expect("model app_data");
                 model
@@ -245,10 +134,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     .cloned()
             };
             let Some(Some(row)) = slot_state else {
-                // No row — and the reference still pushes four (`0x4c2d07 mov eax,4` is
-                // unconditional; there is no short-return path). A cleared slot's record has a
-                // zeroed itemId, which `0x55ba30` short-circuits to a NULL cache record, so it takes
-                // the cache-miss quality where a genuinely absent slot takes the guard's zero.
                 let cleared = slot_state.is_some();
                 return Ok(MultiValue::from_vec(vec![
                     Value::Nil,
@@ -259,7 +144,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     } else {
                         NO_SLOT_QUALITY
                     }),
-                    // Benilla's trailing item id: there is no item here.
+                    // The trailing item id: none here.
                     Value::Integer(0),
                 ]));
             };
@@ -273,19 +158,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 item,
                 Value::Integer(i64::from(row.quantity)),
                 quality,
-                // Benilla extension (5th): the item id, the shared tooltip store's key.
+                // The item id, a fifth return that is not a 1.12 value.
                 Value::Integer(i64::from(row.item_id)),
             ]))
         })?,
     )?;
 
-    // GetLootSlotLink(slot) → the row's full escaped `|cff…|Hitem:…|h[Name]|h|r` link | nil. 1-based
-    // like GetLootSlotInfo beside it; nil out of range, nil for the coin row, and nil while the
-    // item-template query is in flight (the link embeds the name). The reference's row click reads
-    // it for BOTH modifier arms — `DressUpItemLink(GetLootSlotLink(this.slot))` (`LootFrame.lua:149`)
-    // and `ChatFrameEditBox:Insert(GetLootSlotLink(this.slot))` (`:152`). Since 1751 put the stock
-    // file on the chain both of those are the live call sites — our own `BenillaChatEdit_InsertLink`
-    // detour is not on this path any more — and both survive the nil on their own. Decision 1059.
+    // GetLootSlotLink(slot): nil out of range, for the coin row and while the template is in
+    // flight. The stock row click hands it to `DressUpItemLink` (`LootFrame.lua:149`) and
+    // `ChatFrameEditBox:Insert` (`:152`), both of which take a nil.
     g.set(
         "GetLootSlotLink",
         lua.create_function(|lua, slot: usize| {
@@ -304,7 +185,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // LootSlotIsItem(slot) → true for a real item row (in range, not the coin pile, not cleared).
     g.set(
         "LootSlotIsItem",
         lua.create_function(|lua, slot: usize| {
@@ -316,8 +196,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // LootSlotIsCoin(slot) → true for the synthesized coin pile row (false once it's been looted —
-    // the cleared slot stays in the count but answers neither predicate, `LootFrame.lua:80`).
     g.set(
         "LootSlotIsCoin",
         lua.create_function(|lua, slot: usize| {
@@ -329,9 +207,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsFishingLoot() → 1/nil, whether the open loot came from fishing (nil when none is open).
-    // `LootFrame_OnShow` keys the reel-in sound + the fishing portrait overlay on it
-    // (`LootFrame.lua:137-140`; decision 1086).
     g.set(
         "IsFishingLoot",
         lua.create_function(|lua, ()| {
@@ -340,16 +215,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ── `LootButton`'s own method table — ONE entry, and this is it ─────────────────────────────
+    // ── `LootButton`'s own method table ──────────────────────────────────────────────────────
     //
-    // `SetSlot(index)` (`0x4c1880`, table `0x847ce4`, the registrar's own `mov edx,1` says count
-    // 1). 1-based in, **0-based stored** (`ftol` then `dec eax` into `[this+0x4dc]`), and it
-    // pushes nothing. `LootFrame.lua:94`'s `button:SetSlot(slot)` is its only caller in the
-    // shipped UI — the row's `id="N"` does NOT feed it.
-    //
-    // A non-number raises the client's own usage string. That is worth transcribing exactly: it
-    // is the one place this class talks to a caller, and `LootFrame.lua` would surface a typo'd
-    // call as this text.
+    // `SetSlot(index)` (`0x4c1880`): 1-based in, 0-based stored (`ftol`, `dec eax` into
+    // `[this+0x4dc]`), no returns; a non-number raises the client's usage string. Its one stock
+    // caller is `LootFrame.lua:94`; the row's `id` does not feed it.
     {
         let m = lua.create_table()?;
         m.set(
@@ -358,16 +228,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 let n = match &index {
                     Value::Integer(i) => *i as f64,
                     Value::Number(n) => *n,
-                    // `lua_isnumber` accepts a numeric string, as everywhere else in this image.
+                    // `lua_isnumber` accepts a numeric string.
                     Value::String(s) => match s.to_str().ok().and_then(|s| s.parse::<f64>().ok()) {
                         Some(n) => n,
                         None => return Err(mlua::Error::runtime("Usage: SetSlot(index)")),
                     },
                     _ => return Err(mlua::Error::runtime("Usage: SetSlot(index)")),
                 };
-                // `ftol` truncates toward zero, then `dec`. A slot below 1 leaves the row taking
-                // nothing rather than wrapping — the reference stores the decrement raw, but its
-                // consumer is a bounds-checked table walk and ours is an Option.
+                // `ftol` truncates toward zero, then `dec`; below 1 takes nothing, as the
+                // reference's bounds-checked consumer of the raw decrement does.
                 let slot = (n.trunc() >= 1.0).then(|| n.trunc() as u32 - 1);
                 super::button::set_loot_slot(lua, &this, slot)?;
                 Ok(())
@@ -376,16 +245,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.set_named_registry_value(REG_LOOTBUTTON_METHODS, m)?;
     }
 
-    // BenillaTakeLootSlot(slot) — the ROW CLICK's take, queued as a 1-based display row; the app
-    // maps it to the coin or the item's wire slot and applies the bind-on-pickup gate.
-    //
-    // Why this is not `LootSlot`, and why the name is ours (decision 1744): in 1.12 the plain take
-    // is **not a Lua binding at all**. The dispatcher `0x4c2790(slot, flag)` has exactly two
-    // callers — the C `CLootButton::OnClick 0x4c1820` with `flag = 0`, and the `LootSlot` binding
-    // `0x4c2e70` with `flag = 1` — and only the `flag = 0` arm reaches the take. benilla has no
-    // `CLootButton` widget type (our rows are ordinary XML buttons), so the click arm needs a verb,
-    // and giving it the 1.12 NAME would have handed `LootSlot` a second meaning the reference does
-    // not give it. `Benilla`-prefixed like the other seams the reference kept in C.
+    // BenillaTakeLootSlot(slot): not a 1.12 verb. It queues the row click's take by 1-based row,
+    // which has no Lua binding in the reference: only `CLootButton::OnClick 0x4c1820` reaches the
+    // dispatcher `0x4c2790` with flag 0.
     g.set(
         "BenillaTakeLootSlot",
         lua.create_function(|lua, slot: u32| {
@@ -395,11 +257,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // LootSlot(slot) — the LOOT_BIND **confirmation continuation**, and nothing else, exactly as
-    // 1.12 has it (`0x4c2e70`: `luaL_checknumber(1)`, `dec eax`, `0x4c2790(slot, flag = 1)`; the
-    // flag-1 arm at `0x4c27c0` starts `cmp edi, [0x847cec]` and returns unless the slot IS the
-    // pending confirm). So an addon calling `LootSlot(n)` on an ordinary row does nothing here,
-    // which is what it does on the real client; the app owns the pending-slot gate.
+    // LootSlot(slot): the LOOT_BIND confirmation only (`0x4c2e70`: `luaL_checknumber(1)`,
+    // `dec eax`, `0x4c2790(slot, 1)`, whose arm at `0x4c27c0` returns unless the slot is the
+    // pending confirm, `cmp edi, [0x847cec]`). On an ordinary row it does nothing.
     g.set(
         "LootSlot",
         lua.create_function(|lua, slot: u32| {
@@ -409,9 +269,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CloseLoot([failed]) — flag the release intent. The optional arg (the client's "couldn't open
-    // the UI" signal, `LootFrame.lua:18`) is accepted and ignored; the app decides whether to send a
-    // release (only when a loot is actually open).
+    // CloseLoot([failed]): the "unable to open the UI" argument (`LootFrame.lua:18`) is ignored.
     g.set(
         "CloseLoot",
         lua.create_function(|lua, _args: MultiValue| {
@@ -421,13 +279,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetMasterLootCandidate(index) → the 1-based candidate's NAME, or nil past the end.
-    //
-    // `GroupLootDropDown_Initialize` probes this sparsely and relies entirely on the nil:
-    // the party arm walks `1..MAX_PARTY_MEMBERS+1` and the raid arm walks `1..40` in blocks of
-    // five, keeping a "Group N" submenu only where the block's first probe answered non-nil
-    // (`LootFrame.lua:169-232`). So an out-of-range index must answer nil rather than raise, and
-    // the list must be DENSE — a hole would silently drop a candidate from the menu.
+    // GetMasterLootCandidate(index): nil, never an error, out of range or on an empty slot, since
+    // `GroupLootDropDown_Initialize` probes slots 1-5 in a party and 1-40 in a raid and reads nil
+    // as nobody (`LootFrame.lua:168-232`).
     g.set(
         "GetMasterLootCandidate",
         lua.create_function(|lua, index: u32| {
@@ -444,9 +298,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GiveMasterLoot(slot, candidateIndex) — queue the assignment; the app owns the wire slot and
-    // the recipient guid. Called from the dropdown's own handler for a below-threshold item and
-    // from the CONFIRM_LOOT_DISTRIBUTION popup's OnAccept above it (`LootFrame.lua:236-244`,
+    // GiveMasterLoot(slot, candidateIndex): from the dropdown below the quality threshold, and from
+    // the `CONFIRM_LOOT_DISTRIBUTION` popup above it (`LootFrame.lua:234-244`,
     // `StaticPopup.lua:85-94`).
     g.set(
         "GiveMasterLoot",
@@ -469,7 +322,6 @@ mod tests {
         LootState {
             master_candidates: Vec::new(),
             rows: vec![
-                // The coin pile, always first. No link: there is no item to link (decision 1059).
                 Some(LootRow {
                     item_id: 0,
                     name: Some("1g 23s 45c".into()),
@@ -480,7 +332,6 @@ mod tests {
                     link: None,
                     random_property_id: 0,
                 }),
-                // A resolved item — name, quality AND link all landed together (one template answer).
                 Some(LootRow {
                     item_id: 0,
                     name: Some("Wool Cloth".into()),
@@ -491,7 +342,7 @@ mod tests {
                     link: Some("|cffffffff|Hitem:2589:0:0:0|h[Wool Cloth]|h|r".into()),
                     random_property_id: 0,
                 }),
-                // An in-flight item: the loot arrived, the item-template answer hasn't.
+                // In flight: the loot arrived, its item template has not.
                 Some(LootRow {
                     item_id: 0,
                     name: None,
@@ -510,14 +361,12 @@ mod tests {
     #[test]
     fn loot_snapshot_reads() {
         let mut s = UiScript::new().unwrap();
-        // No loot open: count 0, info nil.
         assert_eq!(s.eval::<i64>("return GetNumLootItems()").unwrap(), 0);
         assert!(s.eval::<bool>("return GetLootSlotInfo(1) == nil").unwrap());
 
         s.set_loot(Some(loot()));
         assert_eq!(s.eval::<i64>("return GetNumLootItems()").unwrap(), 3);
 
-        // Row 1: the coin pile — IsCoin true, IsItem false, its text the money amount.
         assert!(s.eval::<bool>("return LootSlotIsCoin(1)").unwrap());
         assert!(s.eval::<bool>("return not LootSlotIsItem(1)").unwrap());
         let (texture, item, quantity, quality) = s
@@ -527,7 +376,6 @@ mod tests {
         assert_eq!(item, "1g 23s 45c");
         assert_eq!((quantity, quality), (1, 1));
 
-        // Row 2: a resolved item — IsItem true, IsCoin false, quantity + quality present.
         assert!(s.eval::<bool>("return LootSlotIsItem(2)").unwrap());
         assert!(s.eval::<bool>("return not LootSlotIsCoin(2)").unwrap());
         let (name, qty) = s
@@ -535,10 +383,7 @@ mod tests {
             .unwrap();
         assert_eq!((name.as_str(), qty), ("Wool Cloth", 3));
 
-        // Row 3: in flight — the reference's cache-miss SENTINELS, not nils (decision 1805). The
-        // quality is the load-bearing one: stock `LootFrame_Update` does
-        // `ITEM_QUALITY_COLORS[quality].r` with no guard, and `-1` is a real row of that table
-        // (`UIParent.lua` builds it `for i = -1, 6`) while a nil is a runtime error.
+        // Row 3 is in flight: the cache-miss sentinels, not nils.
         let (texture, item, quantity, quality) = s
             .eval::<(String, String, i64, i64)>("return GetLootSlotInfo(3)")
             .unwrap();
@@ -548,7 +393,6 @@ mod tests {
             "an in-flight row answers \"\" / -1, never nil"
         );
         assert_eq!(texture, "Interface\\Icons\\INV_Misc_QuestionMark");
-        // …and the same row with NO display-info icon either still answers a texture path.
         let mut iconless = loot();
         iconless.rows[2].as_mut().unwrap().texture = None;
         s.set_loot(Some(iconless));
@@ -559,8 +403,6 @@ mod tests {
         );
         s.set_loot(Some(loot()));
 
-        // GetLootSlotLink: the resolved item's link, nil for the coin row and for the in-flight one
-        // (both arms of the reference's row click hand this straight on — decision 1059).
         assert_eq!(
             s.eval::<String>("return GetLootSlotLink(2)").unwrap(),
             "|cffffffff|Hitem:2589:0:0:0|h[Wool Cloth]|h|r"
@@ -568,8 +410,6 @@ mod tests {
         assert!(s.eval::<bool>("return GetLootSlotLink(1) == nil").unwrap());
         assert!(s.eval::<bool>("return GetLootSlotLink(3) == nil").unwrap());
 
-        // IsFishingLoot: false on an ordinary loot, true when the snapshot says fishing, false
-        // again with no loot open (decision 1086).
         assert!(s.eval::<bool>("return not IsFishingLoot()").unwrap());
         let mut fished = loot();
         fished.fishing = true;
@@ -577,16 +417,13 @@ mod tests {
         assert!(s.eval::<bool>("return IsFishingLoot()").unwrap());
         s.set_loot(Some(loot()));
 
-        // Out of range → nil.
         assert!(s.eval::<bool>("return GetLootSlotInfo(9) == nil").unwrap());
         assert!(s.eval::<bool>("return GetLootSlotLink(9) == nil").unwrap());
         assert!(s.eval::<bool>("return not LootSlotIsItem(9)").unwrap());
         assert!(s.eval::<bool>("return not LootSlotIsCoin(9)").unwrap());
 
-        // A CLEARED slot (looted): still counted — the slot list is fixed while the window is open,
-        // the reference's own shape (`LootFrame.numLootItems` is read once at OnShow) — but it
-        // answers neither predicate and nil info/link, so the frame hides that button in place
-        // instead of collapsing the rows below it.
+        // A looted slot stays counted but answers neither predicate, and the rows below keep
+        // their slots.
         let mut cleared = loot();
         cleared.rows[0] = None;
         s.set_loot(Some(cleared));
@@ -595,23 +432,18 @@ mod tests {
         assert!(s.eval::<bool>("return GetLootSlotLink(1) == nil").unwrap());
         assert!(s.eval::<bool>("return not LootSlotIsItem(1)").unwrap());
         assert!(s.eval::<bool>("return not LootSlotIsCoin(1)").unwrap());
-        // …and the rows below keep their own slots.
         assert!(s.eval::<bool>("return LootSlotIsItem(2)").unwrap());
     }
 
-    /// The master-loot half of the seam (decision 1675). `GetMasterLootCandidate` must answer nil
-    /// past the end rather than raise — `GroupLootDropDown_Initialize` probes it sparsely (the
-    /// raid arm walks 1..40 in blocks of five) and reads the nil as "nobody here".
     #[test]
     fn master_loot_candidates_read_1_based_and_nil_past_the_end() {
         let mut s = UiScript::new().unwrap();
 
-        // No loot open at all: nil, not an error.
         assert!(s
             .eval::<bool>("return GetMasterLootCandidate(1) == nil")
             .unwrap());
 
-        // A window with no candidate list (any loot method but master): still nil everywhere.
+        // No candidate list: any loot method but master.
         s.set_loot(Some(loot()));
         assert!(s
             .eval::<bool>("return GetMasterLootCandidate(1) == nil")
@@ -640,7 +472,7 @@ mod tests {
                 .unwrap(),
             "0 is not a Lua index"
         );
-        // The raid arm's real sweep shape: 40 probes must all answer without raising.
+        // The raid arm's sweep: 40 probes, none raising.
         assert_eq!(
             s.eval::<i64>(
                 "local n = 0
@@ -651,9 +483,7 @@ mod tests {
             2
         );
 
-        // A HOLE in the middle answers nil without ending the list — the raid layout, where a
-        // candidate's index carries which subgroup they are in, so slot 6 can be occupied while
-        // slots 2-5 are empty. A list that stopped at the first nil would lose them.
+        // A raid's slot carries the subgroup, so slot 6 can be filled while 2-5 are empty.
         let mut raid = loot();
         raid.master_candidates = vec![
             Some("Thrall".into()),
@@ -694,7 +524,6 @@ mod tests {
         s.run("GiveMasterLoot(2, 1)").unwrap();
         assert_eq!(s.take_loot_master_gives(), vec![(2, 1)]);
         assert!(s.take_loot_master_gives().is_empty(), "drained");
-        // It is NOT a loot pick — the two intents must not cross wires.
         assert!(s.take_loot_picks().is_empty());
     }
 
@@ -708,9 +537,7 @@ mod tests {
         assert!(s.take_loot_picks().is_empty(), "drained");
     }
 
-    /// `LootSlot` is the confirmation continuation, so it rides its OWN queue — a client that let
-    /// it fall into the pick queue would loot any row an addon named, which the reference refuses
-    /// (decision 1744).
+    /// In the pick queue `LootSlot` would loot any row an addon named, which the reference refuses.
     #[test]
     fn loot_slot_queues_confirms_not_picks() {
         let mut s = UiScript::new().unwrap();
@@ -732,7 +559,6 @@ mod tests {
         s.run("CloseLoot()").unwrap();
         assert!(s.take_loot_close());
         assert!(!s.take_loot_close(), "drained");
-        // The client's failed-open form (CloseLoot(1)) is accepted and flags the same intent.
         s.run("CloseLoot(1)").unwrap();
         assert!(s.take_loot_close());
     }
@@ -746,9 +572,8 @@ mod tests {
         assert!(s.eval::<bool>("return GetLootSlotInfo(1) == nil").unwrap());
     }
 
-    /// A real HARDWARE click on a named frame — through the pointer path, so `scripted` is false
-    /// and the LootButton gate sees what it would see in play. Positions the frame first: the
-    /// input path is a hit test, and an unpositioned frame is nowhere.
+    /// A hardware click on a named frame through the pointer path, which hit-tests, so the frame
+    /// is positioned first.
     fn hardware_click(s: &mut UiScript, name: &str, button: &str) {
         s.set_screen_size(1024.0, 768.0);
         s.run(&format!(
@@ -761,7 +586,6 @@ mod tests {
         s.mouse_button(125.0, 125.0, button, false);
     }
 
-    /// `LootButton` is a real `CreateFrame` type with its own identity — not an alias for Button.
     #[test]
     fn loot_button_is_its_own_registered_type() {
         let s = UiScript::new().unwrap();
@@ -783,7 +607,6 @@ mod tests {
         assert!(!s
             .eval::<bool>(r#"return lb:IsObjectType("CheckButton") and true or false"#)
             .unwrap());
-        // Its one method of its own, plus all of Button's through the chain.
         assert_eq!(
             s.eval::<String>("return type(lb.SetSlot)").unwrap(),
             "function"
@@ -792,14 +615,12 @@ mod tests {
             s.eval::<String>("return type(lb.SetText)").unwrap(),
             "function"
         );
-        // …and the method is NOT on a plain Button — the chain runs derived → base only.
+        // A plain Button lacks it: the chain runs derived to base only.
         s.run(r#"b = CreateFrame("Button", "PlainB", UIParent)"#)
             .unwrap();
         assert_eq!(s.eval::<String>("return type(b.SetSlot)").unwrap(), "nil");
     }
 
-    /// An unmodified hardware click takes the row's slot. The Lua `OnClick` runs first and
-    /// unconditionally, and its outcome does not gate the take.
     #[test]
     fn an_unmodified_click_runs_the_handler_and_then_takes() {
         let mut s = UiScript::new().unwrap();
@@ -816,15 +637,14 @@ mod tests {
         assert_eq!(s.eval::<i64>("return ran").unwrap(), 1, "the handler ran");
         assert_eq!(s.take_loot_picks(), vec![3], "and then the take, 1-based");
 
-        // The handler erroring does not eat the loot — `0x4c1833`'s result is never tested.
+        // An erroring handler still loots: `0x4c1833`'s result is never tested.
         s.run(r#"lb:SetScript("OnClick", function() error("boom") end)"#)
             .unwrap();
         hardware_click(&mut s, "LB1", "LeftButton");
         assert_eq!(s.take_loot_picks(), vec![3], "a broken hook still loots");
     }
 
-    /// Right-click loots exactly like left-click: `0x4c1820` reads the button code once and
-    /// forwards it, with no `cmp` against it anywhere in the body.
+    /// `0x4c1820` forwards the button code without ever comparing it.
     #[test]
     fn right_click_loots_like_left_click() {
         let mut s = UiScript::new().unwrap();
@@ -840,9 +660,7 @@ mod tests {
         assert_eq!(s.take_loot_picks(), vec![2]);
     }
 
-    /// Any of the three modifiers suppresses the take — and only the take. The handler still runs,
-    /// which is exactly how the shipped `LootFrameItem_OnClick` gets to own the ctrl and shift
-    /// cases without the C take firing underneath it.
+    /// The handler still runs, so stock `LootFrameItem_OnClick` owns ctrl and shift alone.
     #[test]
     fn any_modifier_suppresses_the_take_but_not_the_handler() {
         for (i, (shift, ctrl, alt)) in [
@@ -874,9 +692,7 @@ mod tests {
         }
     }
 
-    /// **A scripted `:Click()` is a complete no-op** — it does not even run the row's `OnClick`.
-    /// `0x4c182b` returns before the base call. Surprising enough that it is asserted rather than
-    /// left to be rediscovered.
+    /// A scripted `:Click()` does not even run `OnClick`: `0x4c182b` returns before the base call.
     #[test]
     fn a_scripted_click_does_nothing_at_all() {
         let mut s = UiScript::new().unwrap();
@@ -896,7 +712,7 @@ mod tests {
             "the handler never ran"
         );
         assert!(s.take_loot_picks().is_empty(), "and nothing was taken");
-        // A plain Button's Click() is unaffected — the gate is this type's alone.
+        // A plain Button's Click() is unaffected.
         s.run(
             r#"
             b = CreateFrame("Button", "PlainB", UIParent)
@@ -909,8 +725,7 @@ mod tests {
         assert_eq!(s.eval::<i64>("return bran").unwrap(), 1);
     }
 
-    /// `SetSlot` is 1-based in and 0-based stored, takes a numeric string, and refuses `this` that
-    /// is not a LootButton (the reference's own `IsA` guard at `0x4c18ee`).
+    /// The `this` guard is the reference's `IsA` check at `0x4c18ee`.
     #[test]
     fn set_slot_converts_and_guards() {
         let mut s = UiScript::new().unwrap();
@@ -922,25 +737,21 @@ mod tests {
         hardware_click(&mut s, "LB1", "LeftButton");
         assert_eq!(s.take_loot_picks(), vec![4]);
 
-        // A numeric string is a number to `lua_isnumber`.
         s.run(r#"lb:SetSlot("2")"#).unwrap();
         hardware_click(&mut s, "LB1", "LeftButton");
         assert_eq!(s.take_loot_picks(), vec![2]);
 
-        // A non-number raises the client's own usage text.
         let e = s.run("lb:SetSlot('x')").unwrap_err().to_string();
         assert!(e.contains("Usage: SetSlot(index)"), "{e}");
 
-        // Never slotted → takes nothing, rather than silently taking row 1. `LB1` is still parked
-        // under the cursor from the clicks above and, being linked first, would win the tie for the
-        // point (decision 1816) and take row 2 again — get it out of the way first.
+        // Never slotted takes nothing. `LB1` still sits under the cursor and, linked first, would
+        // win the hit test, so it hides first.
         s.run("LB1:Hide()").unwrap();
         s.run(r#"fresh = CreateFrame("LootButton", "LB2", UIParent)"#)
             .unwrap();
         hardware_click(&mut s, "LB2", "LeftButton");
         assert!(s.take_loot_picks().is_empty());
 
-        // And it is a LootButton method, not a Button one.
         s.run(r#"b = CreateFrame("Button", "PlainB", UIParent)"#)
             .unwrap();
         let e = s.run("LB1.SetSlot(b, 1)").unwrap_err().to_string();
diff --git a/crates/benilla-ui/src/script/loot_roll.rs b/crates/benilla-ui/src/script/loot_roll.rs
index c410fe9c..65edc693 100644
--- a/crates/benilla-ui/src/script/loot_roll.rs
+++ b/crates/benilla-ui/src/script/loot_roll.rs
@@ -1,98 +1,52 @@
-//! The group-loot-roll bindings (decision 0591) — the `GroupLootFrame` half of the loot surface,
-//! the same two-way seam as [`super::loot`]: the app pushes a snapshot of the **open rolls**
-//! ([`UiScript::set_loot_rolls`] — each already resolved to name/icon/quantity/quality/bind and a
-//! live time-remaining) and the Lua `RollOnLoot` call queues an outbound **vote** the app drains
-//! ([`UiScript::take_loot_roll_votes`]). The engine holds no roll knowledge — a roll is "an id, an
-//! item's display fields, and how long is left".
-//!
-//! ## The Era API shape
-//!
-//! 1.12 drives four `GroupLootFrame`s (`NUM_GROUP_LOOT_FRAMES = 4`, `LootFrame.lua:2`) off a flat
-//! set of globals (VERIFIED against the extracted `LootFrame.lua`/`LootFrame.xml`/`UIParent.lua`):
-//!
-//! - `START_LOOT_ROLL` fires with `arg1 = rollID, arg2 = rollTime`; `UIParent.lua:513-515` hands it
-//!   to `GroupLootFrame_OpenNewFrame(id, rollTime)`, which claims the first non-visible frame,
-//!   stores `frame.rollID`, and sets its `Timer` StatusBar's max to `rollTime` (`LootFrame.lua:246-258`).
-//! - `GetLootRollItemInfo(rollID)` → `texture, name, count, quality, bindOnPickUp`
-//!   (`LootFrame.lua:261`) — `bindOnPickUp` swaps the frame to the gold BoP backdrop.
-//! - `GetLootRollTimeLeft(rollID)` → the milliseconds left, polled from the Timer's `OnUpdate`
-//!   (`LootFrame.lua:287-296`).
-//! - `GetLootRollItemLink(rollID)` → the rolled item's link, read by the icon button's ctrl/shift
-//!   arms (`LootFrame.xml:353-361` — decision 1059).
-//! - `RollOnLoot(rollID, rollType)` — `0` Pass, `1` Need, `2` Greed, wired to the frame's
-//!   PassButton/RollButton/GreedButton `OnClick` (`LootFrame.xml:375`/`:398`/`:425`).
-//! - `CANCEL_LOOT_ROLL` fires with `arg1 = rollID`; the matching frame hides (`LootFrame.lua:279-285`).
-//!
-//! `rollID` is **client-internal** — it never reaches the wire (`CMSG_LOOT_ROLL` addresses a roll by
-//! `(lootedTarget, itemSlot)` instead), so the app allocates its own monotonic id per open roll.
-//! An unknown `rollID` answers the reference's own miss values — `nil` for the strings, `0` for
-//! `GetLootRollTimeLeft`, and `GetLootRollItemInfo`'s five-value tail (`0x4c31a3`).
+//! The group loot roll bindings `GroupLootFrame` calls: the app pushes the open rolls and drains
+//! the votes `RollOnLoot` queues, 0 Pass, 1 Need, 2 Greed (`LootFrame.xml:374`/`:398`/`:425`).
+//! `START_LOOT_ROLL` carries `(rollID, rollTime)` and `CANCEL_LOOT_ROLL` the `rollID`
+//! (`UIParent.lua:513-515`, `LootFrame.lua:279-285`). The `rollID` is client-internal, as
+//! `CMSG_LOOT_ROLL` addresses `(lootedTarget, itemSlot)`, so the app allocates its own.
 
 use mlua::Lua;
 
 use super::Model;
 
-/// `rollType` 0 — the one vote the bind-on-pickup gate never intercepts (passing binds nothing).
+/// `rollType` 0, the one vote the bind-on-pickup gate never intercepts.
 const PASS: u8 = 0;
 
-/// What `GetLootRollItemInfo` answers for `count` and `quality` when the item-template cache has no
-/// record — the reference's own shared miss tail `nil, nil, 1.0, 1.0, nil` at `0x4c31a3`.
-/// `count` is a literal `1.0` on
-/// the hit path too (`0x4c3160` — a group roll is always one stack), so only the quality is really a
-/// sentinel, and it is **`1` (Common), not `GetLootSlotInfo`'s `-1`**: each accessor carries its own,
-/// and copying one to the other would be a guess.
-///
-/// It matters for the same reason 1805's did. Stock `GroupLootFrame_OnShow` reads this value straight
-/// into `ITEM_QUALITY_COLORS[quality]` and dereferences it on the next line (`LootFrame.lua:275-276`)
-/// with no guard; our `GroupLootFrame.xml` carries the `or ITEM_QUALITY_COLORS[1]` that the stock
-/// file does not, so the nil this used to answer is a raise waiting for that file's migration.
+/// The quality `GetLootRollItemInfo` answers on an item-template miss, from the reference's miss
+/// tail `nil, nil, 1.0, 1.0, nil` (`0x4c31a3`): 1, not `GetLootSlotInfo`'s -1. Stock
+/// `GroupLootFrame_OnShow` indexes `ITEM_QUALITY_COLORS` with it unguarded
+/// (`LootFrame.lua:275-276`).
 const CACHE_MISS_QUALITY: i64 = 1;
 
-/// One open group loot roll, resolved by the app (decision 0591). Plain data — the app rebuilds the
-/// whole list each frame, so `time_left_ms` is simply re-derived rather than ticked here.
+/// One open group loot roll, resolved by the app and pushed whole each frame.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct LootRollEntry {
-    /// The client-internal roll id the Lua side addresses this roll by — allocated by the app,
-    /// never on the wire. Stable for the life of the roll.
+    /// The client-internal `rollID`, allocated by the app and stable for the roll's life.
     pub roll_id: u32,
-    /// The item's name (`GetLootRollItemInfo`'s `name`). `None` while the ask-once item-template
-    /// query is still in flight; the API reports `nil` and the frame shows its placeholder.
+    /// `None`, answered as `nil`, while the item-template query is in flight.
     pub name: Option<String>,
     /// Icon texture path (`Interface\Icons\…`). `None` only if the display catalog had no icon.
     pub texture: Option<String>,
-    /// The stack size being rolled for (`GetLootRollItemInfo`'s `count`).
+    /// The stack size, answered as `GetLootRollItemInfo`'s `count`; the reference answers a literal
+    /// `1.0` there, a group roll being one stack (`0x4c3160`).
     pub quantity: u32,
-    /// Item quality 0..6, for the quality-coloured name; `None` while the template is in flight,
-    /// which the API reports as [`CACHE_MISS_QUALITY`] (`1`, Common) rather than a nil — the
-    /// reference's own miss tail, and a real row of `ITEM_QUALITY_COLORS`.
+    /// Item quality 0..6; `None` while the template is in flight, answered as `CACHE_MISS_QUALITY`.
     pub quality: Option<u32>,
-    /// Whether the item binds when picked up — the gold-backdrop swap in `GroupLootFrame_OnShow`.
-    /// `false` while the template is in flight (the plain backdrop is the safe default).
+    /// Bind on pickup, which swaps in the gold backdrop; `false` while the template is in flight.
     pub bind_on_pickup: bool,
-    /// Milliseconds left before the roll times out — re-derived by the app each frame from the
-    /// roll's start and `SMSG_LOOT_START_ROLL`'s countdown. Saturates at `0`.
+    /// Milliseconds left, from `SMSG_LOOT_START_ROLL`'s countdown; saturates at 0.
     pub time_left_ms: u32,
-    /// The item id — the shared item-tooltip store's key (`BenillaGetItemStats`). A benilla
-    /// extension riding as a TRAILING return of `GetLootRollItemInfo`, the same idiom
-    /// [`super::loot::LootRow::item_id`] uses on `GetLootSlotInfo`.
+    /// The item id, the key of the hover's item lookup; `GetLootRollItemInfo` also returns it as a
+    /// sixth value, which 1.12 does not.
     pub item_id: u32,
-    /// The rolled item's full escaped `|cff…|Hitem:…|h[Name]|h|r` link (`GetLootRollItemLink`,
-    /// decision 1059) — what the icon button's ctrl/shift arms hand to `DressUpItemLink` /
-    /// `ChatFrameEditBox:Insert` (`LootFrame.xml:353-361`). `None` while the item-template query is
-    /// in flight: the link embeds the name, so it lands with `name`/`quality`, not before. A roll
-    /// popup shows the instant `START_LOOT_ROLL` fires, so this nil is the common case for the first
-    /// frames of every roll — both click arms drop it rather than posting an empty link.
+    /// The link `GetLootRollItemLink` answers for the icon's ctrl/shift clicks
+    /// (`LootFrame.xml:353-361`); `None` until the item template lands, since it embeds the name.
     pub link: Option<String>,
-    /// `SMSG_LOOT_START_ROLL`'s `randomPropertyId` — the drop's **random-suffix roll**, which the
-    /// hover resolves against [`super::Model::random_properties`] for its enchant lines. `0` =
-    /// unrolled. The reference's `SetLootRollItem 0x5364a0` copies the same value into the
-    /// tooltip's `+0x424` and passes no item object, so the roll is the roll window's only enchant
-    /// source — the loot window's own shape (decision 1547). [`Self::name`] carries the suffix the
-    /// same id joins on.
+    /// `SMSG_LOOT_START_ROLL`'s random suffix, 0 for none: the hover's only enchant source, as
+    /// `SetLootRollItem` (`0x5364a0`) copies it to the tooltip's `+0x424` with no item object.
     pub random_property_id: u32,
 }
 
-/// Every group loot roll currently open, in the order the app opened them. Pushed whole each frame.
+/// Every open group loot roll, in the order the app opened them.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct LootRollsState {
     pub rolls: Vec<LootRollEntry>,
@@ -110,30 +64,22 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().loot_roll_votes)
     }
 
-    /// Drain the `(roll_id, roll_type)` **confirm requests** — a Need or Greed on a bind-on-pickup
-    /// roll, which sends nothing and instead asks for the `CONFIRM_LOOT_ROLL` popup (see
-    /// [`install`]'s `RollOnLoot`). The app fires the event; the popup's OnAccept calls
-    /// `ConfirmLootRoll`, which queues the real vote.
+    /// Drain the `(roll_id, roll_type)` Need or Greed calls on a bind-on-pickup roll: the app fires
+    /// `CONFIRM_LOOT_ROLL`, and the popup's `ConfirmLootRoll` queues the real vote.
     pub fn take_loot_roll_confirms(&mut self) -> Vec<(u32, u8)> {
         std::mem::take(&mut self.model_mut().loot_roll_confirms)
     }
 }
 
-/// Look one roll up by its client-internal id.
 fn find(model: &Model, roll_id: u32) -> Option<&LootRollEntry> {
     model.loot_rolls.rolls.iter().find(|r| r.roll_id == roll_id)
 }
 
-/// Register the group-loot-roll globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetLootRollItemInfo(rollID) → texture, name, count, quality, bindOnPickUp, itemID (`0x4c3050`;
-    // the sixth is ours). An unknown id — the frame is mid-teardown, or an addon asked for a stale
-    // roll — is the reference's own miss leg, and it does not return *nothing*: `0x4c31a3` pushes
-    // `nil, nil, 1.0, 1.0, nil`. So does a roll whose item template has not landed, because the
-    // reference reads every one of these off the item-template cache record and takes the same tail
-    // when it is absent. See [`CACHE_MISS_QUALITY`] — the quality is the one a stock caller indexes.
+    // `0x4c3050`, read at `LootFrame.lua:261`. An unknown id takes the reference's miss tail
+    // `nil, nil, 1.0, 1.0, nil` (`0x4c31a3`), as a roll with no item template does there.
     g.set(
         "GetLootRollItemInfo",
         lua.create_function(|lua, roll_id: u32| {
@@ -160,11 +106,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetLootRollItemLink(rollID) → the rolled item's full escaped link | nil. Unknown id → nil, and
-    // nil while the item template is in flight (the link embeds the name). The reference's icon
-    // button reads it for both modifier arms — `DressUpItemLink(GetLootRollItemLink(...))` and
-    // `ChatFrameEditBox:Insert(...)`, `LootFrame.xml:353-361`; ours routes the second through
-    // `BenillaChatEdit_InsertLink`, whose whole job is the nil this getter can answer. Decision 1059.
+    // `nil` for an unknown id or while the item template is in flight.
     g.set(
         "GetLootRollItemLink",
         lua.create_function(|lua, roll_id: u32| {
@@ -179,8 +121,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetLootRollTimeLeft(rollID) → milliseconds remaining; 0 for an unknown id (the reference
-    // OnUpdate clamps anything outside the bar's range to its minimum anyway, LootFrame.lua:290-293).
+    // 0 for an unknown id; the stock `OnUpdate` clamps it to the bar's minimum anyway
+    // (`LootFrame.lua:290-293`).
     g.set(
         "GetLootRollTimeLeft",
         lua.create_function(|lua, roll_id: u32| {
@@ -189,18 +131,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // RollOnLoot(rollID, rollType) — queue the vote. rollType is 0 Pass / 1 Need / 2 Greed; the
-    // server hard-rejects anything >= 3 (MAX_ROLL_FROM_CLIENT), so out-of-range votes are dropped
-    // here rather than sent. An unknown rollID is likewise dropped — the app couldn't map it back
-    // to a (lootedTarget, itemSlot) anyway.
-    //
-    // THE BoP GATE (decision 0594, VERIFIED in the 5875 binary at `0x61bdf0`): a Need or Greed on
-    // an item whose template binds on pickup sends **no packet at all** and leaves the dialog up —
-    // it fires `CONFIRM_LOOT_ROLL` and returns (`0x61be8b`). Only `ConfirmLootRoll` (below), which
-    // the popup's OnAccept calls, re-enters past the gate. Pass is never gated: passing binds
-    // nothing. This gate lives here, in the seam, because that is where the real client puts it —
-    // in the C function, not in the Lua — so a stock addon calling RollOnLoot on a BoP item gets
-    // the confirm rather than silently binding the item.
+    // The server ignores a `rollType` of 3 or more (`GroupHandler.cpp:376`), so those and unknown
+    // ids are dropped. Need or Greed on a bind-on-pickup item sends nothing and fires
+    // `CONFIRM_LOOT_ROLL` (`0x61bdf0`, `0x61be8b`); the gate is in the C function, so it holds for
+    // an addon's call too.
     g.set(
         "RollOnLoot",
         lua.create_function(|lua, (roll_id, roll_type): (u32, u8)| {
@@ -220,8 +154,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ConfirmLootRoll(rollID, rollType) — the BoP gate's bypass (`0x4c33e0`, which re-enters
-    // `0x61bdf0` with the third argument `1`). Same validation as RollOnLoot minus the bind check.
+    // The gate's bypass: `0x4c33e0` re-enters `0x61bdf0` with a third argument of 1.
     g.set(
         "ConfirmLootRoll",
         lua.create_function(|lua, (roll_id, roll_type): (u32, u8)| {
@@ -244,7 +177,7 @@ mod tests {
     fn rolls() -> LootRollsState {
         LootRollsState {
             rolls: vec![
-                // A resolved BoP item — name, quality and link land together (one template answer).
+                // A resolved BoP item: name, quality and link land together.
                 LootRollEntry {
                     roll_id: 7,
                     name: Some("Staff of Jordan".into()),
@@ -257,7 +190,7 @@ mod tests {
                     link: Some("|cffa335ee|Hitem:17182:0:0:0|h[Staff of Jordan]|h|r".into()),
                     random_property_id: 0,
                 },
-                // An in-flight item: the roll opened, the item-template answer hasn't landed.
+                // In flight: the roll opened, the item template has not landed.
                 LootRollEntry {
                     roll_id: 8,
                     name: None,
@@ -277,7 +210,6 @@ mod tests {
     #[test]
     fn roll_snapshot_reads() {
         let mut s = UiScript::new().unwrap();
-        // No roll open: info nil, time left 0.
         assert!(s
             .eval::<bool>("return GetLootRollItemInfo(7) == nil")
             .unwrap());
@@ -285,7 +217,6 @@ mod tests {
 
         s.set_loot_rolls(rolls());
 
-        // The resolved roll: the full 1.12 five-tuple, in LootFrame.lua's order.
         let (texture, name, count, quality, bop) = s
             .eval::<(String, String, i64, i64, bool)>("return GetLootRollItemInfo(7)")
             .unwrap();
@@ -296,16 +227,13 @@ mod tests {
             s.eval::<i64>("return GetLootRollTimeLeft(7)").unwrap(),
             42_000
         );
-        // The benilla item-id extension rides as the trailing return.
         assert_eq!(
             s.eval::<i64>("local _, _, _, _, _, id = GetLootRollItemInfo(7)\nreturn id")
                 .unwrap(),
             17182
         );
 
-        // The in-flight roll: name/texture nil as the reference's miss tail has them, but the
-        // QUALITY is its sentinel `1` and not a nil — stock `GroupLootFrame_OnShow` indexes it into
-        // `ITEM_QUALITY_COLORS` and dereferences the result with no guard (`LootFrame.lua:275-276`).
+        // In flight: the quality is the miss tail's 1, never nil.
         assert!(s
             .eval::<bool>(
                 "local t, n, c, q, b = GetLootRollItemInfo(8)\n\
@@ -313,8 +241,6 @@ mod tests {
             )
             .unwrap());
 
-        // GetLootRollItemLink: the resolved roll's link; nil while the template is in flight (the
-        // icon button's ctrl/shift arms hand this straight on — decision 1059).
         assert_eq!(
             s.eval::<String>("return GetLootRollItemLink(7)").unwrap(),
             "|cffa335ee|Hitem:17182:0:0:0|h[Staff of Jordan]|h|r"
@@ -323,9 +249,7 @@ mod tests {
             .eval::<bool>("return GetLootRollItemLink(8) == nil")
             .unwrap());
 
-        // An unknown id → the reference's five-value miss tail (`0x4c31a3`), never an error and
-        // never *nothing*: nil, nil, 1, 1, nil — so a stock caller that unpacks all five and indexes
-        // the quality still finds a colour.
+        // An unknown id: the reference's miss tail (`0x4c31a3`).
         assert!(s
             .eval::<bool>("return GetLootRollItemInfo(99) == nil")
             .unwrap());
@@ -348,7 +272,7 @@ mod tests {
     fn roll_on_loot_queues_votes() {
         let mut s = UiScript::new().unwrap();
         s.set_loot_rolls(rolls());
-        // Roll 8 is NOT bind-on-pickup, so every vote on it goes straight out.
+        // Roll 8 is not bind-on-pickup, so every vote goes straight out.
         s.run("RollOnLoot(8, 1)").unwrap(); // Need
         s.run("RollOnLoot(8, 2)").unwrap(); // Greed
         s.run("RollOnLoot(8, 0)").unwrap(); // Pass
@@ -357,10 +281,6 @@ mod tests {
         assert!(s.take_loot_roll_confirms().is_empty(), "nothing to confirm");
     }
 
-    /// The BoP gate (decision 0594): Need/Greed on a bind-on-pickup roll must send NOTHING and ask
-    /// for the confirm popup instead; Pass on the same roll goes straight out. This is the
-    /// behaviour benilla shipped wrong in 0591 — it sent the vote immediately, binding the item
-    /// with no prompt.
     #[test]
     fn need_or_greed_on_a_bop_roll_confirms_instead_of_voting() {
         let mut s = UiScript::new().unwrap();
@@ -373,19 +293,17 @@ mod tests {
         );
         assert_eq!(s.take_loot_roll_confirms(), vec![(7, 1), (7, 2)]);
 
-        // Pass is never gated — passing binds nothing.
+        // Pass is never gated.
         s.run("RollOnLoot(7, 0)").unwrap();
         assert_eq!(s.take_loot_roll_votes(), vec![(7, 0)]);
         assert!(s.take_loot_roll_confirms().is_empty());
 
-        // ConfirmLootRoll is the bypass: the popup's OnAccept lands the real vote.
+        // `ConfirmLootRoll`, the popup's accept, lands the real vote.
         s.run("ConfirmLootRoll(7, 1)").unwrap();
         assert_eq!(s.take_loot_roll_votes(), vec![(7, 1)]);
         assert!(s.take_loot_roll_confirms().is_empty(), "no second prompt");
     }
 
-    /// `ConfirmLootRoll` bypasses only the *bind* gate — it still validates id and range, or a
-    /// stale popup could push a vote the app cannot address.
     #[test]
     fn confirm_still_validates() {
         let mut s = UiScript::new().unwrap();
@@ -395,13 +313,11 @@ mod tests {
         assert!(s.take_loot_roll_votes().is_empty());
     }
 
-    /// The two votes that must never reach the wire: a rollType the server would reject outright
-    /// (`>= MAX_ROLL_FROM_CLIENT`), and an id no open roll owns (nothing to address it with).
     #[test]
     fn bad_votes_are_dropped() {
         let mut s = UiScript::new().unwrap();
         s.set_loot_rolls(rolls());
-        s.run("RollOnLoot(7, 3)").unwrap(); // ROLL_NOT_EMITED_YET — server-only
+        s.run("RollOnLoot(7, 3)").unwrap(); // ROLL_NOT_EMITED_YET, server-only
         s.run("RollOnLoot(7, 200)").unwrap();
         s.run("RollOnLoot(99, 1)").unwrap(); // no such roll
         assert!(s.take_loot_roll_votes().is_empty());
diff --git a/crates/benilla-ui/src/script/lua50.rs b/crates/benilla-ui/src/script/lua50.rs
index 70a30bed..3966af06 100644
--- a/crates/benilla-ui/src/script/lua50.rs
+++ b/crates/benilla-ui/src/script/lua50.rs
@@ -1,138 +1,38 @@
-//! **The Lua 5.0 dialect** — the layer that makes an mlua 5.1 VM answer the questions a 1.12 addon
-//! asks about its interpreter (decision 1194).
+//! The Lua 5.0 dialect: the 5.1 VM's libraries reshaped to answer as the 1.12 client's Lua 5.0.
 //!
-//! The 1.12.1 client embeds **Lua 5.0**; we embed mlua's `lua51`. Every prior decision in this
-//! crate treated that as a detail — 0068 called the target "stock Lua 5.1", and the WoW stdlib
-//! layer beside this one is written as aliases *onto* 5.1. It is not a detail. It is the single
-//! largest measured blocker in the whole addon arc:
+//! The reference embeds Lua 5.0 (`$Lua: Lua 5.0` at `0x811b30`), and `InitLua 0x7039e0` opens
+//! five libraries: base (`0x811e28`, 36 entries), `string` (`0x822d88`, 12), `table`
+//! (`0x822d40`, 8), `math` (`0x822c60`, 24) and `bit` (`0x822c18`, 8), with no `os`, `io`,
+//! `debug` or `coroutine`. The grammar is the Lua fork's, in `third_party/lua-src`.
 //!
-//! ```text
-//! what stopped them (addons whose FIRST load error was each):
-//!    61  error: 'X' is obsolete          <- table.setn, raised by Lua 5.1
-//! ```
-//!
-//! Sixty-one of 218 real vanilla addons, plus ~23 more that merely depend on one of them, stopped
-//! on their first chunk. The chain is worth spelling out because it is not obvious and because
-//! **we caused the last link ourselves**: `AceLibrary.lua` opens with
-//!
-//! ```lua
-//! local version = GetBuildInfo()
-//! if string.find(version, "^2%.") then
-//!     table_setn = function() end   -- TBC: Lua 5.1, setn is gone
-//! else
-//!     table_setn = table.setn       -- 1.12: Lua 5.0, setn is real
-//! end
-//! ```
-//!
-//! Ace asks the client which client it is and picks the right dialect. We started answering
-//! `"1.12.1"` truthfully (1192 phase 5, `GetBuildInfo`), Ace correctly took the 5.0 branch, and our
-//! 5.1 VM raised. The addon was right, the API was right, and the interpreter underneath was
-//! lying. That is what this module fixes.
-//!
-//! ## What it does, in three parts
-//!
-//! 1. **`table.setn`/`table.getn` get their 5.0 meaning back.** 5.0 remembers a table's size —
-//!    in a numeric `t.n` field if one already exists, otherwise in a private weak-keyed table
-//!    where nothing walking the table can see it. 5.1 removed the concept and made `setn` raise.
-//!    The exact mechanism matters more than it looks: see [`LUA_5_0_TABLE_SIZE`] for the draft
-//!    that got it wrong and the 39 addons that noticed.
-//! 2. **The 5.1-only members are removed.** `string.gmatch`/`match`/`reverse`, `table.maxn`,
-//!    `math.fmod`/`modf`/`huge`/`cosh`/`sinh`/`tanh`, and the whole `coroutine` table — none of
-//!    which 1.12 has. This is 1189's *"a superset is not free"* one level below `_G`: an addon
-//!    that writes `string.gmatch or string.gfind` (Ace does, on the very next line) picks the
-//!    branch we leave standing, so leaving both standing chooses the wrong one for it.
-//! 3. **The 5.0 compat globals the reference actually has get added** — `sort`, `foreach`,
-//!    `foreachi`. `reference/1.12-globals.tsv` lists all three; we had the other seventeen of that
-//!    family and not these.
-//!
-//! ## What this module does NOT have to do: the vararg `arg` table
-//!
-//! Lua 5.0 gives every vararg function an implicit `arg` table with an `n` field, and 1.12's
-//! FrameXML uses it directly — `QuestTimerFrame_Update(...)` walks `for i=1, arg.n`, and so do
-//! `FCFDropDown_LoadChannels`, `TradeSkill_OnEvent` and the GM-ticket and CVar families. Three of
-//! our own transcriptions carry a note saying they rewrote it "the 5.1-native way" with
-//! `select("#", ...)`, which reads as though the dialect demanded it.
-//!
-//! **It does not.** mlua's vendored 5.1 is built with `LUA_COMPAT_VARARG`, so `arg` and `arg.n`
-//! are already there — measured, not assumed: `local function f(...) return arg.n end; f('a','b')`
-//! answers 2 in this VM. That matters for 1751: a stock file using 5.0 varargs needs nothing from
-//! this module, and the rewrite was a precaution against a problem we did not have.
-//!
-//! **And the other half of that, which costs an hour to rediscover: `...` is a DECLARATION token
-//! here and nothing else.** This VM parses `function(x, ...)`, and then rejects every *use* of
-//! `...` as an expression — `return ...`, `f(x, ...)`, and `local a = ...` at chunk level — with
-//! `unexpected symbol near '...'`. `arg` and `unpack(arg)` are the only forwarding forms
-//! ([`vararg_is_a_declaration_only`] pins all six). That is 5.0's own shape and exactly right for
-//! the content we run, but it also binds anything WE write in Lua: an engine-side helper cannot
-//! forward an unknown argument list without a table, so a verb whose arity matters (`GetPoint()`
-//! vs `GetPoint(nil)`, `SetAllPoints()` vs `SetAllPoints(nil)`) has to stay on the Rust side.
-//! Decision 2310 is where that bit — a Lua dispatcher for the Region method map would have been
-//! ~4x cheaper than the Rust one and cannot be written in this dialect.
-//!
-//! ## The one known divergence, stated rather than hidden
-//!
-//! `table.insert`/`table.remove` stay on 5.1's `#t` border rather than consulting `getn`. **This
-//! is byte-confirmed as a real divergence, not a suspicion**: 1.12's whole table library is
-//! `n`-based — `luaL_getn 0x6f5050` is called by `insert`/`remove`/`concat`/`sort`/`foreachi` *and*
-//! base `unpack`, and `insert`/`remove` **update** the stored size (`luaL_setn 0x6f4ea0`). So
-//! `setn(t, 0)` on a non-empty table makes the next `insert` land at index 1 there and at
-//! `#t + 1` here.
-//!
-//! It stays, and the trade was measured before it was made. Over the 218-addon corpus there are
-//! 1,720 `setn` call sites; **1,471 pass 0** — always immediately after a
-//! `for k in pairs(t) do t[k] = nil end` wipe, where `#t` is already 0 and the two agree — and 290
-//! more pass `table.getn(source)` straight after copying that source, where they agree too. Fewer
-//! than 20 sites could observe the difference, and none of them is reached at load. Replacing
-//! `table.insert` with a Lua-level reimplementation to serve those would put an interpreted
-//! function on the hottest path in every addon in existence. Revisit it if a *runtime* failure is
-//! ever traced here — not before.
-//!
-//! ## Ground truth (decision 1196 — verified, no longer derived)
-//!
-//! This module first shipped with its member lists taken from Lua 5.0's published library
-//! registrations and cross-checked against two artifacts we hold. Every list here is now read
-//! straight off the array in the image:
-//!
-//! - **Lua 5.0**, on five independent discriminators — not just the `$Lua: Lua 5.0 …` blob at
-//!   `0x811b30` but `LUA_REGISTRYINDEX = -10000` (5.1 uses −10002), a `luaT_eventname[]` pool with
-//!   no `__mod`/`__len` (so **no `%` and no `#` operator**), and live `luaL_getn`/`luaL_setn`.
-//! - **Five libraries are opened** by `InitLua 0x7039e0` and no more: base (a 36-entry array at
-//!   `0x811e28` looped straight into `_G`), `string` (12, array `0x822d88`), `table` (8,
-//!   `0x822d40`), `math` (24, `0x822c60`), and **`bit`** (8, `0x822c18`). `luaL_openlib` has four
-//!   call sites image-wide, so `os`/`io`/`debug`/`coroutine` are absent by construction.
-//! - **The compat globals are a Lua chunk, not C macros** — a 1310-byte `compat.lua` compiled into
-//!   `.data` at `0x8722e8`, run last at init. That is why the set is a specific subset (`getn`
-//!   aliased, `setn` deliberately not) rather than "whatever `LUA_COMPAT_*` gives you", and it is
-//!   also where the **degree-based** bare `sin`/`cos`/`tan` come from — a convention this crate's
-//!   stdlib layer had already reached independently.
+//! `...` is a parameter-list token only: a vararg function reads its arguments through 5.0's
+//! `arg` table (`arg.n`, `unpack(arg)`). So Lua written here forwards an unknown argument list
+//! only through a table, and a verb whose arity matters (`GetPoint()` against `GetPoint(nil)`)
+//! stays in Rust.
 
 use mlua::{Lua, Table, Value};
 
-/// Members that exist in Lua 5.1 and **not** in Lua 5.0, by library.
-///
-/// Removed rather than left standing, per 1189: a feature-detecting addon branches on presence,
-/// and the branch it should take is the one 1.12 gives it.
+/// The Lua 5.1 library members 5.0 lacks, removed so an addon's feature test
+/// (`string.gmatch or string.gfind`) takes the branch 1.12 gives it.
 const REMOVED: &[(&str, &[&str])] = &[
-    // 5.1 added the new pattern-matching spellings; 5.0 has only `gfind` and no `reverse`.
+    // 5.0 has `gfind`, and no `gmatch`, `match` or `reverse`.
     ("string", &["gmatch", "match", "reverse"]),
-    // 5.1 added `maxn`; 5.0's table library is concat/foreach/foreachi/getn/setn/sort/insert/remove.
+    // 5.0's eight are concat, foreach, foreachi, getn, setn, sort, insert and remove.
     ("table", &["maxn"]),
-    // 5.1 renamed `mod`→`fmod` (we keep `mod`, which 1.12 has as a bare global too) and added
-    // `modf`, `huge`, and the hyperbolics.
+    // 5.0's `mod` is 5.1's `fmod` (and a bare global in 1.12); 5.0 has no `modf`, `huge` or
+    // hyperbolics.
     ("math", &["fmod", "modf", "huge", "cosh", "sinh", "tanh"]),
 ];
 
-/// Lua 5.0's remembered table size, and the whole `n`-based table library that rides it
-/// (decision 2102) — [`table_size`]'s own header is the mechanism, the byte census behind it, and
-/// the runtime failure that retired this module's "revisit if ever traced" note.
+/// Lua 5.0's remembered table size and the `n`-based table library that reads and updates it.
 mod table_size;
 
-/// Install the dialect. Runs **before** the WoW stdlib layer, so its aliases bind the 5.0-shaped
+/// Install the dialect. Runs before the WoW stdlib layer, so its aliases bind the 5.0-shaped
 /// functions rather than the 5.1 ones they replace.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // ── 1 · the `n`-based table library gets its 5.0 meaning back ─────────────────────────────
+    // ── 1 · the `n`-based table library ───────────────────────────────────────────────────────
     table_size::install(lua)?;
 
     // ── 2 · the 5.1-only members go ───────────────────────────────────────────────────────────
@@ -144,67 +44,23 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             t.set(*name, Value::Nil)?;
         }
     }
-    // `coroutine` is not in the 1.12 client's `_G` at all — not a member gap, a whole library the
-    // client does not open. It was on `reference_surface`'s beyond-1.12 exception list as
-    // "inherited rather than chosen"; it is now neither.
+    // `InitLua` never opens `coroutine`.
     g.set("coroutine", Value::Nil)?;
 
-    // `select` is 5.1's base library, not 5.0's, and the 1.12 client's `_G` has no row for it.
-    // It sat on `reference_surface`'s beyond-1.12 exception list under a reason that expired twice
-    // over: first "our transcribed FrameXML uses it in 16 files" — 1751's migration retired every
-    // one of those files, measured at zero by 2142 — then "it is mlua's, not ours to remove
-    // without the 5.1 varargs it comes with". 2101 deleted those varargs from the grammar, which
-    // is what turns this from a trade into a deletion: with `...`-as-a-value gone, `select`'s one
-    // idiomatic shape cannot be written at all, and what is left — `select(k, f())` — is a 5.1
-    // spelling of the multiple assignment 5.0 writes with commas.
-    //
-    // **Nothing of ours called it in production**: 177 sites in 55 files were our own TESTS asking
-    // a binding's arity, which is a host-side question and is now asked host-side
-    // ([`super::UiScript::arity`]). The handful that need the count *inside* Lua use 5.0's own
-    // answer, `arg.n` — which this VM hands every vararg function since 2101 deleted the arm that
-    // cleared `VARARG_NEEDSARG`.
+    // `select` is 5.1's base library and has no row in 1.12's `_G`. A vararg function counts its
+    // arguments with `arg.n`, and host code asks `UiScript::arity`.
     g.set("select", Value::Nil)?;
 
-    // **The string type has NO metatable in 1.12**, so `("x"):upper()` — and `s:sub(1, 2)` for a
-    // string `s` — raises `attempt to index a string value` there and quietly worked here. 5.1's
-    // `luaopen_string` ends in a `createmetatable` 5.0's does not have, and mlua runs 5.1.
-    //
-    // Read out of the client, and the claim is stronger than "nobody installs one": the type
-    // *cannot* carry one, on the **reader** side, so the writer side never has to be argued.
-    // `luaT_gettmbyobj 0x6f7bd0` is the one function the VM asks for any value's metamethod (7
-    // rel32 callers, covering TM_INDEX/TM_NEWINDEX/TM_CALL/order/arith). It loads `o->tt` at
-    // `0x6f7be2` and enumerates two tags — `sub ecx,5; je` (LUA_TTABLE), `sub ecx,2; je`
-    // (LUA_TUSERDATA) — then falls through at `0x6f7bee` to `mov eax,0x811bc0`, `&luaO_nilobject`
-    // in **`.rdata`**: sixteen zero bytes with no writers by construction. There is nothing to
-    // read, so a `__index` for a string cannot exist however it were installed. `G+0x80` is
-    // `tmname[15]`, the metamethod *name* strings, not a per-type metatable array; a ModRM/SIB
-    // census of every ×4-indexed operand across the text section finds no such read into writable
-    // `.data` at all.
-    //
-    // The writer agrees from the other end. `lua_setmetatable 0x6f4020` takes the same two arms
-    // (`0x6f409e`, `0x6f40a3`) into one `mov [edx+8], esi` — 5.0 puts `metatable` at offset 8 of
-    // both `Table` and `Udata` — and every other tag falls to `0x6f40a8`'s `xor eax,eax`: return
-    // 0, write nothing. `lua_getmetatable 0x6f3cf0` carries the identical `{5, 7}` switch. And the
-    // layout settles it a third way: `luaS_newlstr 0x6f9d00` puts a string's **hash** at `+8`
-    // (`0x6f9dbb`), the very offset the other two use for the metatable pointer.
-    //
-    // `luaopen_string 0x7fd810` is six instructions, `[0x7fd810, 0x7fd827)` — `push 0;
-    // push 0x822d88; mov edx,0x871938; call luaL_openlib; mov eax,1; ret` — with no
-    // `createmetatable` step, and `luaL_openlib` does not reach `0x6f4020` either.
-    //
-    // So this is not a policy choice about a superset — it is the type system. Note the reference
-    // also *raises* rather than no-ops if an addon tries it itself: base `setmetatable 0x702a40`'s
-    // first act is `luaL_checktype(L, 1, LUA_TTABLE)`, which mlua's 5.1 matches.
-    //
-    // Same rule as `coroutine` above, one layer below `_G`: an addon writing `s:gsub(...)` or
-    // testing `getmetatable("")` is asking which interpreter it is on, and the branch it should
-    // get is 1.12's.
+    // 1.12's string type has no metatable, so `("x"):upper()` raises `attempt to index a string
+    // value`. There it cannot carry one: `luaT_gettmbyobj 0x6f7bd0` finds metamethods only on
+    // tables and userdata, `lua_setmetatable 0x6f4020` writes only those two tags, and
+    // `luaopen_string 0x7fd810` installs none, where 5.1's does. Base `setmetatable` (`0x702a40`)
+    // rejects a non-table in both.
     lua.set_type_metatable::<mlua::String>(None);
 
-    // ── 3 · the 5.0 compat globals the reference has and we lacked ────────────────────────────
-    // `sort`/`foreach`/`foreachi` are in `reference/1.12-globals.tsv`; `setn` deliberately is not,
-    // so no bare `setn` is installed even though `table.setn` now works. The client's compat set
-    // is a specific subset, not "all of them".
+    // ── 3 · the 5.0 compat globals ────────────────────────────────────────────────────────────
+    // The client's compat chunk (`0x8722e8`) publishes these three bare, and no bare `setn`
+    // (`reference/1.12-globals.tsv`).
     let table: Table = g.get("table")?;
     for name in ["sort", "foreach", "foreachi"] {
         if let Ok(f) = table.get::<Value>(name) {
@@ -213,21 +69,16 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             }
         }
     }
-    // `getn` is re-bound here rather than left to the stdlib layer's `table.getn or …` fallback,
-    // so the bare global and the member are the same function and cannot drift apart.
+    // Bound here, not left to the stdlib layer, so the bare `getn` is `table.getn` itself.
     g.set("getn", table.get::<Value>("getn")?)?;
 
-    // ── 4 · what the binary said and nobody had asked (decision 1196) ─────────────────────────
-    // `print` and `_VERSION` are **not in 1.12's `_G`** — the captured table says so, and the base
-    // library's 36-entry array at `0x811e28` confirms why: neither is in it (`_VERSION`'s literal
-    // is not even in the image). Both were on `reference_surface`'s exception list as "inherited
-    // rather than chosen"; nothing of ours uses either.
+    // ── 4 · the base library's own shape ──────────────────────────────────────────────────────
+    // `print` and `_VERSION` are neither in the base array (`0x811e28`) nor in 1.12's `_G`.
     g.set("print", Value::Nil)?;
     g.set("_VERSION", Value::Nil)?;
 
-    // `__pow` is a **global** in 1.12 (`function engine` in the captured table) — Lua 5.0
-    // implements `^` by calling it, and 5.1 made the operator native, so the name simply
-    // disappeared. Present here because an addon can see it, not because anything calls it.
+    // `__pow` is a 1.12 global, which 5.0 calls to implement `^`; nothing here calls it, but an
+    // addon can see it.
     g.set(
         "__pow",
         lua.create_function(|_, (a, b): (f64, f64)| Ok(a.powf(b)))?,
@@ -240,22 +91,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// The **`bit` library** — 1.12 opens one, and it is not stock Lua (decision 1196).
-///
-/// `InitLua 0x7039e0` opens exactly five libraries: base, `string`, `table`, `math`, and **`bit`**
-/// (`0x7fadc0`, array `0x822c18`). The captured `_G` agrees — `bit` is there, attributed `engine`.
-/// We had assumed the opposite: `attempt to index global 'bit'` showed up in the corpus survey and
-/// was written off as an addon reaching for something 1.12 lacks. It was reaching for something
-/// **we** lacked.
-///
-/// Eight functions, the array's own order and its own names. Semantics are 32-bit two's
-/// complement, which is what every caller assumes (`band(flags, 0xFF)`); `arshift` is the
-/// sign-propagating shift `rshift` is not, which is the only pair anyone gets wrong.
+/// The `bit` library 1.12 opens (`0x7fadc0`, array `0x822c18`): its eight functions, in the
+/// array's order, on 32-bit two's complement.
 fn install_bit(lua: &Lua) -> mlua::Result<()> {
     let bit = lua.create_table()?;
-    // Lua numbers are doubles; the client's bit ops truncate to a 32-bit int and return a signed
-    // one. `as i64 as u32` is the C cast chain (`(unsigned)(int)x`) rather than a saturating one,
-    // so `bnot(0)` answers -1 exactly as it does there.
+    // The client truncates to a 32-bit int and answers signed. `as i64 as u32` is C's wrapping
+    // `(unsigned)(int)x`, not a saturating cast, so `bnot(0)` is -1 as there.
     fn u32_of(v: f64) -> u32 {
         v as i64 as u32
     }
@@ -278,9 +119,7 @@ fn install_bit(lua: &Lua) -> mlua::Result<()> {
         "bxor",
         lua.create_function(|_, (a, b): (f64, f64)| Ok(out(u32_of(a) ^ u32_of(b))))?,
     )?;
-    // The shifts mask their count to 5 bits, like the x86 shift instructions the client compiles
-    // to — `lshift(1, 32)` is `1`, not `0`, and an addon that shifts by a computed width relies on
-    // it not trapping.
+    // Shift counts mask to 5 bits, as the client's x86 shifts do: `lshift(1, 32)` is 1.
     bit.set(
         "lshift",
         lua.create_function(|_, (a, n): (f64, f64)| Ok(out(u32_of(a) << (u32_of(n) & 31))))?,
@@ -295,7 +134,7 @@ fn install_bit(lua: &Lua) -> mlua::Result<()> {
             Ok(out(((u32_of(a) as i32) >> (u32_of(n) & 31)) as u32))
         })?,
     )?;
-    // `bit.mod` — integer remainder, not `math.mod`'s float one. The library's own eighth entry.
+    // `bit.mod`: an integer remainder, unlike `math.mod`'s float one.
     bit.set(
         "mod",
         lua.create_function(|_, (a, b): (f64, f64)| {
@@ -309,50 +148,14 @@ fn install_bit(lua: &Lua) -> mlua::Result<()> {
     lua.globals().set("bit", bit)
 }
 
-/// The **garbage-collector pair** — `gcinfo` answers TWO numbers and `collectgarbage` answers
-/// NONE and takes a *number* (decision 2136).
-///
-/// Both are 5.0-shaped, and 5.1 changed both in ways that are observable from Lua — already
-/// carried in `reference/1.12-shapes.tsv` as `gcinfo … 2 exact (number,number) agree` and
-/// `collectgarbage … 0 exact () agree` — rows the return-shape gate never checked, because it
-/// filters to `table_kind = global` and these two are `baselib`.
-///
-/// **`gcinfo 0x703200`** — extent `[0x703200, 0x703243)`, reads no argument and cannot raise:
-/// `lua_getgccount 0x6f43f0` then `lua_getgcthreshold 0x6f43e0`, each shifted `>> 10`, then
-/// `mov eax, 2`. So it is `(count_KB, threshold_KB)` — 5.1 kept the name and dropped the second
-/// value, which is what we answered.
-///
-/// **`collectgarbage 0x703250`** — extent `[0x703250, 0x703273)`, `luaL_optnumber(L, 1, 0.0)` →
-/// `_ftol` → `lua_setgcthreshold 0x6f4400` → `xor eax,eax`. Zero values, and a **number** argument:
-/// 5.1's string options (`"count"`, `"collect"`, `"step"`, …) do not exist in the 35 bytes. The
-/// two dialects are therefore *inverted* on argument type — 5.1 rejects the number the reference
-/// requires, and accepts the strings the reference refuses:
-///
-/// | call | the reference | stock 5.1 (what we had) |
-/// |---|---|---|
-/// | `collectgarbage()` | threshold 0 → full collect, 0 values | 1 value |
-/// | `collectgarbage(0)` | the same, explicitly | **raises** ``invalid option `0'`` |
-/// | `collectgarbage("count")` | **raises** `number expected, got string` | returns a number |
-///
-/// **The threshold is modelled, and this is the one place a value is ours rather than the
-/// image's.** 5.1 replaced 5.0's stop-the-world collector with an incremental one and deleted
-/// `GCthreshold` outright, so there is no 5.1 counter to read. What a script *can* observe is the
-/// rule that moves it, and that rule is 5.0's own: `luaC_collectgarbage` ends
-/// `G->GCthreshold = 2*G->nblocks`, and `lua_setgcthreshold` writes `n << 10` then immediately
-/// collects if the live count has already reached it. Both are reproduced below against mlua's
-/// real heap, so `gcinfo()`'s second value tracks the first exactly as 5.0's does. The saturation
-/// is the image's: `0x6f4400` compares **unsigned** against `0x3fffff`, so a negative `n` — or one
-/// past 4194303 — saturates the threshold to `0xffffffff` bytes.
-///
-/// **The reach is measured, not assumed.** `local mem, threshold = gcinfo()` is
-/// `AceAddon-2.0.lua`'s memory report (36 copies in the 219-addon corpus), and the next line is
-/// `string.format("… %.3f MiB …", threshold / 1024)` — arithmetic on a nil, i.e. a raise inside
-/// the report. pfUI's `modules/panel.lua:170` reads the same slot as `gckb` and guards it, so it
-/// silently prints `UNAVAILABLE` where the reference prints the number. `collectgarbage` has 14
-/// corpus call sites and every one of them is a bare `collectgarbage()` whose result is
-/// discarded, so its arity has no reach today — the argument contract is what this fixes.
+/// `gcinfo` and `collectgarbage` in their 5.0 shapes. `gcinfo` (`0x703200`) takes nothing and
+/// answers `(count_KB, threshold_KB)` (`lua_getgccount 0x6f43f0`, `lua_getgcthreshold
+/// 0x6f43e0`); `collectgarbage` (`0x703250`) takes an optional number, sets the threshold to that
+/// many KB (`lua_setgcthreshold 0x6f4400`) and answers nothing, so 5.1's string options raise.
+/// 5.1's collector has no threshold, so it is kept here by 5.0's rules against mlua's heap: a
+/// live count that reaches it collects, and a collection resets it to twice the live count.
 fn install_gc(lua: &Lua) -> mlua::Result<()> {
-    /// 5.0's `GCthreshold`, in **bytes** — the registry cell standing in for `[G+0x24]`.
+    /// 5.0's `GCthreshold` (`[G+0x24]`), in bytes.
     const REG_GC_THRESHOLD: &str = "__benilla_gc_threshold";
     /// `lua_setgcthreshold 0x6f4400`'s unsigned bound, in kilobytes.
     const MAX_THRESHOLD_KB: i64 = 0x3f_ffff;
@@ -370,33 +173,30 @@ fn install_gc(lua: &Lua) -> mlua::Result<()> {
 
     settle(lua)?;
 
-    // `gcinfo()` — no argument, two numbers, cannot raise.
+    // `gcinfo()`: no argument, two numbers, never raises.
     lua.globals().set(
         "gcinfo",
         lua.create_function(|lua, ()| {
             let live = live_bytes(lua);
             let mut threshold: f64 = lua.named_registry_value(REG_GC_THRESHOLD).unwrap_or(0.0);
-            // **5.0's invariant, not just its arithmetic.** `luaC_checkGC` runs on allocation, so
-            // the instant `nblocks` reaches `GCthreshold` a collection fires and re-settles the
-            // threshold to `2 * nblocks`. A script therefore never observes a threshold at or
-            // below the live count. We have no allocation hook, so the same rule is applied on
-            // read: without it the cell set at construction goes stale as the heap grows and
-            // `gcinfo()` reports a threshold *under* its own count, a state 5.0 cannot hold.
+            // 5.0 collects the moment the live count reaches the threshold (`luaC_checkGC`), so a
+            // script never sees a threshold at or below the count. With no allocation hook here,
+            // the same rule runs on read.
             if (live as f64) >= threshold {
                 settle(lua)?;
                 threshold = lua.named_registry_value(REG_GC_THRESHOLD).unwrap_or(0.0);
             }
-            // Both shifts are the image's own `shr eax,0xa`.
+            // Both in KB, the reference's `shr eax,0xa`.
             Ok(((live >> 10) as f64, (threshold as u64 >> 10) as f64))
         })?,
     )?;
 
-    // `collectgarbage([n])` — a number, no return values, and a raise on anything that is not one.
+    // `collectgarbage([n])`: a number, no return values, and a raise on anything else.
     lua.globals().set(
         "collectgarbage",
         lua.create_function(|lua, arg: Value| {
-            // `luaL_optnumber(L, 1, 0.0)`: absent or nil takes the default; a numeric STRING is
-            // coerced (the image's `lua_tonumber` runs `strtod`); anything else is a type error.
+            // `luaL_optnumber(L, 1, 0.0)`: absent or nil is the default, a numeric string is
+            // coerced (`lua_tonumber` runs `strtod`), anything else is a type error.
             let n = match &arg {
                 Value::Nil => 0.0,
                 Value::Integer(i) => *i as f64,
@@ -428,8 +228,8 @@ fn install_gc(lua: &Lua) -> mlua::Result<()> {
                 kb * 1024.0
             };
             lua.set_named_registry_value(REG_GC_THRESHOLD, threshold_bytes)?;
-            // `luaC_checkGC`: collect when the live count has reached the threshold, and the
-            // collection then re-settles it to `2 * nblocks`.
+            // `luaC_checkGC`: a live count at the threshold collects, and the collection
+            // re-settles it to `2 * nblocks`.
             if (live_bytes(lua) as f64) >= threshold_bytes {
                 lua.gc_collect()?;
                 settle(lua)?;
@@ -440,37 +240,22 @@ fn install_gc(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// The type name `luaL_typerror` would print — `luaT_typenames 0x811cd0`'s spelling.
-/// **`assert` answers ONE value in 5.0, and all of its arguments in 5.1.**
-///
-/// `luaB_assert 0x7031a0` is five calls: `luaL_checkany 0x6f4bb0` on argument 1,
-/// `lua_toboolean 0x6f3660`, and on the truthy leg `0x7031e5 call 0x6f3080` — `lua_settop(L, 1)`
-/// — then `0x7031ea mov eax,1`. The false leg is
-/// `luaL_optlstring(L, 2, "assertion failed!" /*0x872bdc*/)` into `luaL_error 0x6f4940`, which
-/// longjmps. 5.1 replaced the settop/`mov eax,1` pair with `return lua_gettop(L)`, so
-/// `assert(a, b)` answers two values there and one here.
-///
-/// Found by the shape gate's base-library arm once it grew an argument ladder — the row
-/// (`arity 1 exact`) has been in `reference/1.12-shapes.tsv` since it was vendored, and a
-/// no-argument probe could never reach it because `assert()` raises.
-///
-/// **Reach, measured rather than assumed:** 5 647 `assert(` sites across the 219-addon corpus and
-/// 73 in the shipped FrameXML, and **zero** of them bind more than one name from the result. So
-/// this buys the contract, not a fixed addon — the same footing as `collectgarbage`'s argument
-/// (2136 §3). The next caller to write `local a, b = assert(f())` is the one that finds out.
+/// `assert` in its 5.0 shape (`luaB_assert 0x7031a0`): it answers only its first argument
+/// (`lua_settop(L, 1)` at `0x7031e5`) where 5.1 answers them all, and a false value raises
+/// argument 2 or `assertion failed!` (`0x872bdc`) through `luaL_error 0x6f4940`.
 fn install_assert(lua: &Lua) -> mlua::Result<()> {
     let f = lua.create_function(|lua, args: mlua::MultiValue| {
         let mut it = args.into_iter();
-        // `luaL_checkany 0x6f4bb0` — an ABSENT argument 1 raises; an explicit `nil` does not, it
-        // is the falsy leg below.
+        // `luaL_checkany 0x6f4bb0`: an absent argument 1 raises; an explicit `nil` takes the
+        // falsy leg below.
         let Some(v) = it.next() else {
             return Err(mlua::Error::RuntimeError(
                 "bad argument #1 to `assert' (value expected)".into(),
             ));
         };
         if matches!(v, Value::Nil | Value::Boolean(false)) {
-            // `luaL_optlstring` — a string or a number; anything else is its own bad-argument
-            // raise, in 5.0's own quoting (2122).
+            // `luaL_optlstring`: a string or a number; anything else raises its own bad
+            // argument, the type spelled as `luaT_typenames 0x811cd0` spells it.
             let msg = match it.next() {
                 None | Some(Value::Nil) => "assertion failed!".to_string(),
                 Some(other) => match lua.coerce_string(other.clone())? {
@@ -485,7 +270,7 @@ fn install_assert(lua: &Lua) -> mlua::Result<()> {
             };
             return Err(mlua::Error::RuntimeError(msg));
         }
-        // `lua_settop(L, 1)`: the first argument, alone, whatever else was passed.
+        // `lua_settop(L, 1)`: the first argument alone, whatever else was passed.
         Ok(v)
     })?;
     lua.globals().set("assert", f)
@@ -508,16 +293,7 @@ fn type_name(v: &Value) -> &'static str {
 mod tests {
     use crate::script::UiScript;
 
-    /// **`gcinfo()` answers TWO numbers, and the second one is what the corpus reads**
-    /// (decision 2136).
-    ///
-    /// `0x703200` is `lua_getgccount` + `lua_getgcthreshold`, each `>> 10`, then `mov eax, 2`.
-    /// 5.1 kept the name and dropped the second value, so we answered one — and the reach is not
-    /// hypothetical: `AceAddon-2.0.lua`'s memory report is
-    /// `local mem, threshold = gcinfo()` followed by `string.format("… %.3f MiB …",
-    /// threshold / 1024)`, which is arithmetic on a nil, i.e. a raise *inside* the report, in a
-    /// library 36 corpus addons embed. pfUI's `modules/panel.lua:170` reads the same slot as
-    /// `gckb`, guards it, and so prints `UNAVAILABLE` where the reference prints a number.
+    /// `0x703200`: `lua_getgccount` and `lua_getgcthreshold`, each `>> 10`, two values.
     #[test]
     fn gcinfo_answers_two_numbers_as_1_12_does() {
         let s = UiScript::new().unwrap();
@@ -532,15 +308,13 @@ mod tests {
             vec!["number".to_string(), "number".to_string()],
             "(number,number) — `1.12-shapes.tsv` types the row `agree`"
         );
-        // 5.0's collector keeps `GCthreshold` above `nblocks` (`luaC_checkGC` collects the moment
-        // they meet, and the collection re-settles the threshold to `2 * nblocks`), so a script
-        // cannot observe the pair inverted.
+        // `luaC_checkGC` keeps 5.0's threshold above the live count.
         assert!(
             s.eval::<bool>("local c, t = gcinfo() return t > c")
                 .unwrap(),
             "the threshold must sit above the live count, as 5.0's collector guarantees"
         );
-        // AceAddon-2.0's own line, verbatim in shape — this is the raise the fix removes.
+        // AceAddon-2.0's memory report divides the second value by 1024.
         assert!(
             s.eval::<String>(
                 "local mem, threshold = gcinfo() \
@@ -551,12 +325,8 @@ mod tests {
         );
     }
 
-    /// **`collectgarbage` answers NOTHING and takes a NUMBER** (decision 2136) — the two dialects
-    /// are inverted on the argument, so this is not a superset either way.
-    ///
-    /// `0x703250` is 35 bytes: `luaL_optnumber(L, 1, 0.0)` → `_ftol` → `lua_setgcthreshold` →
-    /// `xor eax,eax`. There is no string-option dispatch anywhere in it — that is 5.1's
-    /// `collectgarbage`, and on this client `gcinfo()` is the only way to read the counters.
+    /// `0x703250`: `luaL_optnumber(L, 1, 0.0)`, `_ftol`, `lua_setgcthreshold`, no values, and no
+    /// string options.
     #[test]
     fn collectgarbage_answers_nothing_and_takes_a_number() {
         let s = UiScript::new().unwrap();
@@ -565,12 +335,12 @@ mod tests {
             0,
             "`xor eax,eax` at 0x70326f — 5.1 returns one value here"
         );
-        // The reference's ONLY argument form, which stock 5.1 rejects as ``invalid option `0'``.
+        // The reference's only argument form, a number, which stock 5.1 rejects.
         assert_eq!(s.arity("collectgarbage(0)").unwrap(), 0);
         assert!(s.eval::<()>("collectgarbage(2048)").is_ok());
-        // `lua_tonumber` coerces a numeric string through `strtod`, so this one is accepted.
+        // `lua_tonumber` coerces a numeric string through `strtod`.
         assert!(s.eval::<()>(r#"collectgarbage("100")"#).is_ok());
-        // …and a non-numeric string is a type error, in 5.0's own words.
+        // A non-numeric string is a type error, in 5.0's words.
         let e = s
             .eval::<()>(r#"collectgarbage("count")"#)
             .unwrap_err()
@@ -579,7 +349,7 @@ mod tests {
             e.contains("bad argument #1 to `collectgarbage' (number expected, got string)"),
             "5.1's string options must not exist here: {e}"
         );
-        // An explicit threshold above the live count is what `gcinfo` then reports back.
+        // An explicit threshold above the live count is what `gcinfo` reports back.
         assert!(s
             .eval::<bool>(
                 "local c = gcinfo() collectgarbage(c * 4) local _, t = gcinfo() return t >= c"
@@ -587,15 +357,8 @@ mod tests {
             .unwrap());
     }
 
-    /// **A `loadstring` chunk is named by its own SOURCE, and an explicit name is used verbatim**
-    /// (decision 2136).
-    ///
-    /// `luaB_loadstring 0x703280` pushes the string `luaL_checklstring` just returned as
-    /// `luaL_optlstring`'s `def` (`0x70329a`), so the default chunk name is the source text and
-    /// `luaO_chunkid 0x6f5c40` renders it `[string "…"]`. We prepended `=` — chunkid's
-    /// "print verbatim, undecorated" marker — which stripped the wrapper off every explicit name,
-    /// left a literal `@` on a path-shaped one, and named a nameless chunk `(loadstring)`, a
-    /// literal the image does not contain. All four are the prefix of a player-visible error.
+    /// `luaB_loadstring 0x703280` names a chunk by its source unless given a name (`0x70329a`),
+    /// and `luaO_chunkid 0x6f5c40` renders each form.
     #[test]
     fn a_loadstring_chunk_is_named_by_its_own_source() {
         let s = UiScript::new().unwrap();
@@ -610,16 +373,15 @@ mod tests {
             "the default name is the source: {}",
             raised(r#""error('boom')""#)
         );
-        // `'='` — printed verbatim with the marker removed, exactly once.
+        // `=`: printed verbatim, the marker removed once.
         assert!(raised(r#""error('boom')", "=myname""#).starts_with("myname:1: boom"));
-        // `'@'` — the file branch; the path prints plainly, without the marker.
+        // `@`: the file form, the path printed plainly.
         assert!(raised(r#""error('boom')", "@a/b.lua""#).starts_with("a/b.lua:1: boom"));
-        // No marker — the third branch wraps it, which is what an unprefixed name gets. Four
-        // corpus sites pass one (`loadstring(code, "safecall Dispatcher["..n.."]")`).
+        // No marker: wrapped as a string chunk.
         assert!(raised(r#""error('boom')", "plain""#).starts_with(r#"[string "plain"]:1: boom"#));
 
-        // The failure leg returns Lua's message unchanged — `load_aux` pushes nil and the string
-        // and stops. mlua's `Display` prefixes a category word that the image never adds.
+        // The failure leg returns Lua's message unchanged (`load_aux`), without the category word
+        // mlua's `Display` adds.
         let e: String = s
             .eval(r#"local f, e = loadstring("return 1+") return tostring(e)"#)
             .unwrap();
@@ -629,13 +391,8 @@ mod tests {
         );
     }
 
-    /// **`assert` answers ONE value — 5.0's `lua_settop(L, 1); return 1`, not 5.1's
-    /// `return lua_gettop(L)`** (`luaB_assert 0x7031a0`, settop at `0x7031e5`, `mov eax,1` at
-    /// `0x7031ea`).
-    ///
-    /// Found by the shape gate's base-library arm once it grew an argument ladder; the row has
-    /// said `arity 1 exact` since the table was vendored, and only a call with MORE than one
-    /// argument can tell the two dialects apart.
+    /// `luaB_assert 0x7031a0`: `lua_settop(L, 1)` at `0x7031e5`, then `mov eax,1` at `0x7031ea`;
+    /// only a call with more than one argument tells 5.0 from 5.1.
     #[test]
     fn assert_answers_one_value_and_keeps_5_0_s_messages() {
         let s = UiScript::new().unwrap();
@@ -645,7 +402,7 @@ mod tests {
             "5.0 truncates to the first argument; 5.1 returns them all"
         );
         assert_eq!(s.eval::<i64>("return (assert(7, 'x'))").unwrap(), 7);
-        // A truthy `false`-adjacent value is still truthy: only nil and false take the raise.
+        // 0 is truthy: only nil and false raise.
         assert_eq!(s.arity("assert(0)").unwrap(), 1);
 
         let raised = |call: &str| -> String {
@@ -657,15 +414,14 @@ mod tests {
         // `luaL_optlstring(L, 2, "assertion failed!" /*0x872bdc*/)`, then `luaL_error`.
         assert!(raised("assert(false)").contains("assertion failed!"));
         assert!(raised("assert(nil, 'my message')").contains("my message"));
-        // A number is a string to `luaL_optlstring`; anything else is its own bad-argument raise,
-        // in 5.0's backtick quoting (2122).
+        // A number is a string to `luaL_optlstring`; anything else is a bad argument.
         assert!(raised("assert(false, 42)").contains("42"));
         assert!(
             raised("assert(false, {})").contains("bad argument #2 to `assert' (string expected"),
             "{}",
             raised("assert(false, {})")
         );
-        // `luaL_checkany 0x6f4bb0`: an ABSENT argument 1 raises, an explicit nil does not.
+        // `luaL_checkany 0x6f4bb0`: an absent argument 1 raises, an explicit nil does not.
         assert!(
             raised("assert()").contains("bad argument #1 to `assert' (value expected)"),
             "{}",
@@ -673,12 +429,8 @@ mod tests {
         );
     }
 
-    /// **The 61-addon fix, as the addon actually writes it.**
-    ///
-    /// This is `AceLibrary.lua`'s own opening, verbatim in shape: ask the client which client it
-    /// is, take the 5.0 branch, use `table.setn`. Under mlua's stock 5.1 the last line raises
-    /// `'setn' is obsolete` and the addon's first chunk dies — taking ~84 of 218 corpus addons
-    /// with it, because the Ace/FuBar half of the ecosystem embeds this file.
+    /// `AceLibrary.lua`'s opening: it takes the 5.0 branch from `GetBuildInfo()` and calls
+    /// `table.setn`, which stock 5.1 raises on.
     #[test]
     fn acelibrarys_own_dialect_probe_takes_the_5_0_branch_and_works() {
         let s = UiScript::new().unwrap();
@@ -701,16 +453,11 @@ mod tests {
         assert_eq!(s.eval::<i64>("return AceProbe").unwrap(), 0);
     }
 
-    /// `setn`/`getn` are 5.0's real pair — a remembered size that is **not** a no-op and **not** a
-    /// field the table's owner can see.
-    ///
-    /// Both halves have already been got wrong once each. A no-op passes the Ace probe above and
-    /// fails the round-trip here; an unconditional `rawset(t, "n", …)` passes both and breaks 39
-    /// addons that walk the table (see [`LUA_5_0_TABLE_SIZE`]).
+    /// The remembered size is neither a no-op nor a visible `n` key.
     #[test]
     fn getn_and_setn_remember_a_size_without_polluting_the_table() {
         let s = UiScript::new().unwrap();
-        // No remembered size: the border, exactly as 5.1 answers.
+        // No remembered size: a count from 1 to the first nil.
         assert_eq!(s.eval::<i64>("return table.getn({1,2,3})").unwrap(), 3);
         // The size round-trips...
         assert_eq!(
@@ -718,9 +465,8 @@ mod tests {
                 .unwrap(),
             7
         );
-        // ...and is INVISIBLE to anything walking the table. This is the assertion that would have
-        // caught the first draft: AceOO-2.0's `_Embed` walks a mixin's fields with `next` and
-        // errors on any the target already has.
+        // ...and is invisible to `pairs`: AceOO-2.0's `_Embed` errors on any field its target
+        // already has.
         assert_eq!(
             s.eval::<i64>(
                 "local t = {1,2,3} table.setn(t, 0) \
@@ -730,14 +476,13 @@ mod tests {
             3,
             "a remembered size must not appear as a key — 39 corpus addons died on a stray 'n'"
         );
-        // A table that ALREADY carries a numeric `n` keeps using it, which is 5.0's own branch and
-        // why `arg.n` behaves the way 5.0-era code expects.
+        // A table that already has a numeric `n` keeps its size there, 5.0's own branch.
         assert_eq!(
             s.eval::<i64>("local t = {1,2,3, n=3} table.setn(t, 7) return t.n")
                 .unwrap(),
             7
         );
-        // ...and the bare global is the same function, not a second implementation.
+        // ...and the bare global is the same function.
         assert!(
             s.eval::<bool>("return getn == table.getn").unwrap(),
             "a divergent `getn` global is how the two answers start disagreeing"
@@ -745,10 +490,6 @@ mod tests {
     }
 
     /// The 5.1-only members are gone, so an addon's feature detection picks 1.12's branch.
-    ///
-    /// `string.gmatch or string.gfind` is the line **directly below** Ace's `setn` probe: with
-    /// both present it takes `gmatch`, a function 1.12 does not have. That is 1189's superset
-    /// argument one level below `_G`, and this is the test that keeps it true.
     #[test]
     fn the_5_1_only_members_are_not_offered() {
         let s = UiScript::new().unwrap();
@@ -768,7 +509,7 @@ mod tests {
                 "{expr} is a Lua 5.1 addition — 1.12 does not have it"
             );
         }
-        // ...and the 5.0 spellings that replace them are present.
+        // ...and the 5.0 spellings are present.
         for expr in ["string.gfind", "math.mod", "table.setn", "table.foreach"] {
             assert!(
                 s.eval::<bool>(&format!("return {expr} ~= nil")).unwrap(),
@@ -777,7 +518,7 @@ mod tests {
         }
     }
 
-    /// `mod` still works after `math.fmod` is removed — the stdlib layer aliased the 5.1 name.
+    /// The bare `mod` is `math.mod`, so it survives `math.fmod`'s removal.
     #[test]
     fn the_bare_math_family_survives_the_removals() {
         let s = UiScript::new().unwrap();
@@ -785,21 +526,18 @@ mod tests {
         assert_eq!(s.eval::<f64>("return floor(2.7)").unwrap(), 2.0);
     }
 
-    /// **`...` declares a vararg function here and can never be read.** The six forms, together,
-    /// because the split between them is the whole surprise: the declaration parses, every use
-    /// does not, and `arg` carries what `...` cannot (the module header's second vararg note).
+    /// `...` parses in a parameter list and nowhere else; `arg` carries the arguments.
     #[test]
     fn vararg_is_a_declaration_only() {
         let s = UiScript::new().unwrap();
         let parses = |src: &str| s.run(src).is_ok();
-        // Declaration, and the 5.0 way to read what it captured.
+        // Declaration, and 5.0's way to read what it captured.
         assert!(parses("return function(x, ...) return x end"));
         assert!(parses("return function(x, ...) return arg.n end"));
         assert!(parses(
             "local f = tostring return function(x, ...) return f(x, unpack(arg)) end"
         ));
-        // Every use of `...` as an expression — including at chunk level, where 5.1 proper allows
-        // it and this build does not.
+        // Every use of `...` as an expression fails, at chunk level too, where 5.1 allows it.
         assert!(!parses("return function(x, ...) return ... end"));
         assert!(!parses(
             "local f = tostring return function(x, ...) return f(x, ...) end"
@@ -807,7 +545,6 @@ mod tests {
         assert!(!parses("local a = ... return a"));
     }
 
-    /// The three compat globals the reference has and we did not.
     #[test]
     fn sort_foreach_and_foreachi_are_bare_globals_like_the_reference() {
         let s = UiScript::new().unwrap();
@@ -828,11 +565,6 @@ mod tests {
         );
     }
 
-    /// The `bit` library exists in 1.12 and we did not have it (decision 1196).
-    ///
-    /// `InitLua 0x7039e0` opens exactly five libraries and `bit` is the fifth; the captured `_G`
-    /// lists it as `engine`. The corpus's `attempt to index global 'bit'` had been written off as
-    /// an addon reaching past 1.12 — it was reaching past *us*.
     #[test]
     fn the_bit_library_is_present_with_the_references_eight_functions() {
         let s = UiScript::new().unwrap();
@@ -845,7 +577,7 @@ mod tests {
                 "bit.{name} is one of the array's eight entries"
             );
         }
-        // Two's complement, signed out — `bnot(0)` is -1, not 4294967295.
+        // Two's complement, signed out: `bnot(0)` is -1, not 4294967295.
         assert_eq!(s.eval::<i64>("return bit.bnot(0)").unwrap(), -1);
         assert_eq!(
             s.eval::<i64>("return bit.band(0x1234, 0xFF)").unwrap(),
@@ -854,46 +586,26 @@ mod tests {
         assert_eq!(s.eval::<i64>("return bit.bor(0xF0, 0x0F)").unwrap(), 0xFF);
         assert_eq!(s.eval::<i64>("return bit.bxor(0xFF, 0x0F)").unwrap(), 0xF0);
         assert_eq!(s.eval::<i64>("return bit.lshift(1, 4)").unwrap(), 16);
-        // The pair everyone gets wrong: rshift is logical, arshift propagates the sign.
+        // `rshift` is logical, `arshift` propagates the sign.
         assert_eq!(s.eval::<i64>("return bit.rshift(-1, 28)").unwrap(), 15);
         assert_eq!(s.eval::<i64>("return bit.arshift(-1, 28)").unwrap(), -1);
-        // The shift count masks to 5 bits, like the x86 instruction it compiles to.
+        // The shift count masks to 5 bits, as the x86 instruction does.
         assert_eq!(s.eval::<i64>("return bit.lshift(1, 32)").unwrap(), 1);
         assert_eq!(s.eval::<i64>("return bit.mod(17, 5)").unwrap(), 2);
     }
 
-    /// `print` and `_VERSION` are **not** in 1.12's `_G`, and `__pow` is.
-    ///
-    /// All three are things a `_G`-shaped instrument could always have caught and nobody had
-    /// looked: the first two sat on the beyond-1.12 exception list as "inherited rather than
-    /// chosen", and the third was simply missing.
+    /// `print` and `_VERSION` are not in 1.12's `_G`, and `__pow` is.
     #[test]
     fn the_base_library_matches_the_captured_globals() {
         let s = UiScript::new().unwrap();
         assert!(s.eval::<bool>("return print == nil").unwrap());
         assert!(s.eval::<bool>("return _VERSION == nil").unwrap());
-        // 5.0 implements `^` by calling `__pow`; 5.1 made it native and the global vanished.
+        // 5.0 implements `^` by calling `__pow`.
         assert_eq!(s.eval::<f64>("return __pow(2, 10)").unwrap(), 1024.0);
     }
 
-    /// **The corpus's other dialect probe, answered the way 1.12's parser answers it** (2101,
-    /// closing 1208).
-    ///
-    /// Ace2 asks "am I on Lua 5.1?" by compiling a 5.1-only construct — the vararg *expression*,
-    /// which 5.0 has no grammar for (5.0 collects varargs into `arg`; the shipped 1.12 FrameXML
-    /// reads `arg`/`arg.n` 64 times across 177 files and never once writes `...` as a value):
-    ///
-    /// ```lua
-    /// local lua51 = loadstring("return function(...) return ... end") and true or false
-    /// ```
-    ///
-    /// 170 `loadstring` sites across the 219-addon corpus are that one question. Answering it
-    /// `true` puts every Ace-embedding addon on its client-2.0 branch — which is how Cartographer
-    /// came to hook `CloseSpecialWindows`, a name 1.12's `_G` does not have.
-    ///
-    /// The fix is the parser, not a library: `simpleexp` (client `0x6fd240`) has no `TK_DOTS`
-    /// arm, so `...` as a value falls to `prefixexp` and raises. The exact probe line is asserted
-    /// here in the shape the addons write it.
+    /// Ace2's `lua51` probe, `loadstring("return function(...) return ... end")`, fails as on
+    /// 1.12: the reference's `simpleexp` (`0x6fd240`) has no `...` arm.
     #[test]
     fn the_vararg_expression_is_a_syntax_error_as_it_is_on_1_12() {
         let s = UiScript::new().unwrap();
@@ -904,8 +616,7 @@ mod tests {
             .unwrap(),
             "the Ace2 lua51 probe must answer false, as it does on the 1.12 client"
         );
-        // ...and it fails the way 5.0 fails it: `simpleexp`'s default arm -> `prefixexp`, whose
-        // head accepts only `(` or a NAME. Same reject site, same words, as a stray `;`.
+        // `prefixexp` then accepts only `(` or a name, so this is 5.0's own `unexpected symbol`.
         let msg: String = s
             .eval(r#"local f, e = loadstring("return ...") return tostring(e)"#)
             .unwrap();
@@ -913,35 +624,29 @@ mod tests {
             msg.contains("unexpected symbol"),
             "5.0's own message for this, not a bespoke one: {msg}"
         );
-        // The 5.0 half of the same question, which we already answered correctly (1194): `arg`.
+        // The 5.0 half of the question: `arg`.
         assert_eq!(
             s.eval::<i64>("local f = function(...) return arg.n end return f(1, 2, 3)")
                 .unwrap(),
             3,
             "`arg` is 5.1's compat-vararg table, which is the form all of 1.12 FrameXML uses"
         );
-        // And now EVERY vararg function gets one. 5.1 cleared VARARG_NEEDSARG for any function
-        // that mentioned `...`; with the arm deleted nothing clears it, which is 5.0's rule.
+        // Every vararg function gets `arg`, 5.0's rule: without that arm nothing clears
+        // `VARARG_NEEDSARG`.
         assert_eq!(
             s.eval::<i64>("local f = function(a, ...) return arg.n end return f(1, 2, 3)")
                 .unwrap(),
             2
         );
-        // A `...` in a PARAMETER LIST is 5.0's own grammar and must still parse — the deletion is
-        // `simpleexp`'s arm, not `parlist`'s.
+        // A `...` in a parameter list still parses: the deletion is `simpleexp`'s arm, not
+        // `parlist`'s.
         assert!(s
             .eval::<bool>(r#"return loadstring("return function(...) return arg.n end") ~= nil"#)
             .unwrap());
     }
 
-    /// **`#` and `%` are not in 1.12's grammar either** (2101) — the same class, the same
-    /// byte evidence, gated in the same hunk-set.
-    ///
-    /// `getunopr` (`0x6fe0a0`) is a leaf testing exactly two tokens, `-` and `not`, so its
-    /// `OPR_NOUNOPR` is 2 — a three-member enum, 5.0's, not 5.1's four-member one with
-    /// `OPR_LEN`. `getbinopr` (`0x6fe0c0`) bases its switch at `'*'` (0x2A); `%` is 0x25, below
-    /// the range, and reaches `OPR_NOBINOPR` = 14 — a fifteen-member `BinOpr`, again 5.0's. The
-    /// metamethod-name pool at `0x871896` has neither `__len` nor `__mod`.
+    /// The reference's `getunopr` (`0x6fe0a0`) knows only `-` and `not`, its `getbinopr`
+    /// (`0x6fe0c0`) has no `%`, and its metamethod names (`0x871896`) have no `__len` or `__mod`.
     #[test]
     fn the_length_and_modulo_operators_are_not_in_the_grammar() {
         let s = UiScript::new().unwrap();
@@ -952,21 +657,16 @@ mod tests {
                 "{probe} is 5.1-only syntax; 1.12's parser rejects it"
             );
         }
-        // The 5.0 spellings of both, which the reference has and every 1.12-era addon uses.
+        // 5.0's spellings of both.
         assert_eq!(s.eval::<i64>("return table.getn({1,2,3})").unwrap(), 3);
         assert_eq!(s.eval::<i64>("return getn({1,2,3})").unwrap(), 3);
         assert_eq!(s.eval::<f64>("return math.mod(7, 3)").unwrap(), 1.0);
         assert_eq!(s.eval::<i64>("return string.len('abcd')").unwrap(), 4);
     }
 
-    /// **The shapes the reference's own files are written in still load** — the other half of the
-    /// gate, and the one that would make it a regression if it ever stopped being true.
-    ///
-    /// Measured, not assumed: the three constructs above appear **zero** times in the extracted
-    /// 1.12 FrameXML (177 files), GlueXML, Blizzard's own addons, and the director's installed
-    /// AddOns folder. This chunk is the 5.0 grammar those files actually use, including the three
-    /// 5.0-isms the fork restores (1215's iterator-less generic-for, `LUA_COMPAT_LSTR`'s nesting
-    /// long strings, 1315's constructor semicolon).
+    /// The 5.0 grammar the stock files use still parses, including the three constructs the fork
+    /// restores: the iterator-less generic-for, nested long strings (`LUA_COMPAT_LSTR`) and the
+    /// constructor's extra semicolon.
     #[test]
     fn the_5_0_grammar_the_reference_writes_still_parses() {
         let s = UiScript::new().unwrap();
@@ -993,20 +693,12 @@ mod tests {
         );
     }
 
-    /// **The six `debug*` stubs are the REFERENCE's no-ops, not ours** — and that distinction is
-    /// the whole reason they are allowed to exist under real 1.12 names.
-    ///
-    /// Six of the eight, `[0x7027e0, 0x702840)` — `debuginfo`, `debugload`, `debugprint`,
-    /// `debugdump`, `debugbreak` and `debugtimestamp` — are byte-identical `xor eax,eax; ret` —
-    /// three bytes, no call, no memory write, **zero Lua return values**. Only
-    /// `debugprofilestart`/`stop` are real. A no-op we invented would be the "capability absent
-    /// without a failure" class 1203 named;
-    /// a no-op the client itself ships is a transcription.
+    /// Six of the reference's eight `debug*` functions (`[0x7027e0, 0x702840)`) are
+    /// `xor eax,eax; ret`, returning nothing; only `debugprofilestart`/`stop` are real.
     #[test]
     fn the_debug_family_is_six_stubs_and_two_real_ones() {
         let s = UiScript::new().unwrap();
-        // Zero values, not nil — a count is the only check that can tell them apart, and
-        // `arity` is where it is taken now that `select` is gone (2171).
+        // Zero values, not one nil: only a count tells them apart.
         for name in [
             "debuginfo",
             "debugload",
@@ -1021,18 +713,14 @@ mod tests {
                 "{name} returns nothing at all"
             );
         }
-        // ...and the two that are real answer a number of milliseconds.
+        // ...and the two real ones answer milliseconds.
         let ms: f64 = s
             .eval("debugprofilestart() return debugprofilestop()")
             .unwrap();
         assert!(ms >= 0.0, "elapsed milliseconds, not nil: {ms}");
     }
 
-    /// The divergence that USED to be pinned here is gone (decision 2102): `table.insert` now
-    /// consults the remembered size, as `0x7fb6d8` does. The behaviour it asserted — an append
-    /// landing at the border after `setn(t, 0)` — was traced to a real addon failure, so the
-    /// mechanism moved to [`super::table_size`] and its tests moved with it. This is the one line
-    /// that used to say otherwise, kept as the shape a reader will look for.
+    /// `table.insert` appends after the remembered size (its `luaL_getn` call, `0x7fb6d8`).
     #[test]
     fn table_insert_consults_the_remembered_size() {
         let s = UiScript::new().unwrap();
@@ -1044,31 +732,15 @@ mod tests {
         );
     }
 
-    /// **`{ [1] = a, [2] = b, … }` is a LIST, and `pairs` walks it 1, 2, 3** — decision 2111, the
-    /// fourth "restore what 5.1 changed" hunk in `third_party/lua-src`.
-    ///
-    /// 1.12's `recfield` keeps `cc->nh++` **inside** its `TK_NAME` arm (`0x6fd5a4`'s
-    /// `cmp [edi+0x10],0x116` / `0x6fd5ad jne 0x6fd5d4` — 5.0's own placement), so a
-    /// `[expr] = value` field credits **neither** `OP_NEWTABLE` size hint. The table is born with
-    /// `B = C = 0`, i.e. on the shared dummy node, so the first store finds no free node, takes
-    /// `luaH_newkey`'s rehash tail, and `rehash` sizes an **array part** for the dense integer
-    /// keys; `luaH_next` walks the array part first, ascending by index, and the node part after.
-    /// Stock 5.1 moved that `cc->nh++` out of the arm, pre-sized a node vector big enough that no
-    /// rehash ever fires, and left all n keys in the hash — where `next` is slot order.
-    ///
-    /// This was measured by executing `WoW.exe`'s own bytes (`lua_open` → `luaL_loadbuffer` →
-    /// `lua_pcall` → `lua_next`), not merely derived from the disassembly — including the exact
-    /// `Bagnon_Core.lua` below; ascending holds for n = 1..24 and regardless of the order the
-    /// fields are written in.
-    ///
-    /// It matters because every saved-variables file we write is that constructor (decision 1128's
-    /// grammar, and the reference's own writer's — it never emits a bare positional entry), so
-    /// before this hunk every list an addon saved came back in hash order. Bagnon 6.10.22 walks
-    /// its saved bag order with `pairs` and drew the keyring first, ahead of the backpack.
+    /// A `{ [1] = a, [2] = b }` constructor builds an array part, so `pairs` walks it in index
+    /// order. The reference's `recfield` credits no size hint for a `[expr] =` field (its
+    /// `TK_NAME` test at `0x6fd5a4`), so the table starts on the dummy node and the first store's
+    /// rehash sizes an array part, which `luaH_next` walks before the hash. Saved variables are
+    /// written in this form, as the reference writes them, so a saved list reloads in order.
     #[test]
     fn a_bracketed_key_constructor_is_an_array_and_walks_in_index_order() {
         let s = UiScript::new().unwrap();
-        // Bagnon's own table, exactly as its saved-variables file spells it.
+        // Bagnon's own table, as its saved-variables file spells it.
         assert_eq!(
             s.eval::<String>(
                 "local t = { [1] = 0, [2] = 1, [3] = 2, [4] = 3, [5] = 4, [6] = -2 }
@@ -1078,7 +750,7 @@ mod tests {
             "0,1,2,3,4,-2,",
             "the keyring (-2) is LAST — this is the director's Bagnon grid"
         );
-        // …and the order the fields are written in does not change it.
+        // The order the fields are written in does not change it.
         assert_eq!(
             s.eval::<String>(
                 "local t = { [3] = 'c', [1] = 'a', [2] = 'b' }
@@ -1096,8 +768,7 @@ mod tests {
             .unwrap(),
             "1,2,3,a,"
         );
-        // The positional spelling was always an array and still is — the control that keeps the
-        // first assertion from reading as vacuous.
+        // Control: the positional spelling is an array too.
         assert_eq!(
             s.eval::<String>(
                 "local t = { 0, 1, 2, 3, 4, -2 }
@@ -1113,30 +784,9 @@ mod tests {
 mod error_quoting_tests {
     use crate::script::UiScript;
 
-    /// **Every error message quotes a program element the way 5.0 does — `` `x' ``, not `'x'``
-    /// (decision 2122).**
-    ///
-    /// 5.1 introduced `LUA_QL` and made it two apostrophes; the fork's `luaconf.h` puts 5.0's
-    /// backquote back. The five formats it feeds are all readable in `WoW.exe`'s own `.rdata`, and
-    /// the assertions below are those strings:
-    ///
-    /// ```text
-    /// bad argument #%d to `%s' (%s)          lauxlib.c luaL_argerror
-    /// calling `%s' on bad self (%s)          lauxlib.c luaL_argerror's method arm
-    /// attempt to %s %s `%s' (a %s value)     ldebug.c  luaG_typeerror
-    /// %s:%d: %s near `%s'                    llex.c    luaX_lexerror (the client's own 0x87217c)
-    ///  in function `%s'                      ldblib.c  the line debugstack renders
-    /// ```
-    ///
-    /// **The traceback line is the one this does NOT reach**, and it is the one with teeth.
-    /// `debugstack` delegates to mlua's own traceback, which is built in mlua's C shim rather than
-    /// in this fork, so `LUA_QL` does not reach it: it still renders `in function 'X'`. That
-    /// matters because AceLibrary — shipped inside ~80 corpus addons — reads its own caller back
-    /// out of `debugstack()` with `string.find(debugstack(), "`argCheck'.-([`<].-['>])")`, whose
-    /// two patterns both require the backquote; the nil it gets is then handed to a `%s`, so an
-    /// argument-check *diagnostic* raises inside the error path. Closing that means rendering the
-    /// traceback ourselves in the reference's own shape (`debugstack 0x703760`) rather than
-    /// copied from stock 5.0's `ldblib.c`.
+    /// Error messages quote a program element as the reference does, `` `x' ``: the fork's
+    /// `luaconf.h` restores 5.0's `LUA_QL`, and `debugstack` renders its own frames the same way
+    /// (`0x703760`).
     #[test]
     fn errors_quote_program_elements_the_way_lua_5_0_does() {
         let s = UiScript::new().unwrap();
@@ -1159,7 +809,7 @@ mod error_quoting_tests {
             e.contains("bad argument #1 to `rep'"),
             "argerror keeps 5.1's quoting: {e}"
         );
-        // luaX_lexerror — the client's own `0x87217c` format.
+        // luaX_lexerror, the client's `0x87217c` format.
         let e = s
             .eval::<String>(r#"local f, e = loadstring("return 1 +") return tostring(e)"#)
             .unwrap();
@@ -1167,10 +817,7 @@ mod error_quoting_tests {
             e.contains("near `<eof>'"),
             "the lexer keeps 5.1's quoting: {e}"
         );
-        // And no message anywhere OPENS a quote with an apostrophe — 5.1's spelling puts one
-        // where 5.0 puts the backquote, so the tell is a `'` right after a space or a paren.
-        // (The closing quote is an apostrophe in both dialects, which is why this looks for the
-        // opening one and not for the character.)
+        // No message opens a quote with an apostrophe; the closing quote is one in both dialects.
         for e in [
             err("local t = nil return t.x"),
             err("return nosuchfn()"),
@@ -1183,22 +830,9 @@ mod error_quoting_tests {
         }
     }
 
-    /// **`select` is not a 1.12 global** (decision 2171) — and 5.0's own answer to the same
-    /// question still is.
-    ///
-    /// The pair matters more than the removal. `select('#', …)` was how 177 of our own tests asked
-    /// a binding's arity, and the property those gates rest on is that **zero returns and one
-    /// `nil` are different answers** (`binding_abi` §2) — a distinction no `Option<T>` return type
-    /// can hold. 5.0 answers it with the implicit vararg table's `n`, which this VM hands every
-    /// vararg function since 2101 deleted the parser arm that cleared `VARARG_NEEDSARG`; the host
-    /// answers it with [`UiScript::arity`]. If either ever stops telling those apart, the arity
-    /// gates start silently passing a binding that returns nothing.
-    ///
-    /// The removal's own reach is in the corpus rather than here: `pfUI/libs/libpredict.lua:141`
-    /// gates its **TBC** HealComm parser on `select and UnitCastingInfo`, and pfUI supplies the
-    /// second name itself (`libs/libcast.lua:86`, loaded 3rd against libpredict's 10th), so
-    /// publishing `select` was the whole reason that branch ran. `BuffCheck2.lua:1157` is
-    /// `select = select or function(idx, ...)` — a 1.12 addon's own polyfill that ours suppressed.
+    /// `select` is 5.1's; 5.0 counts arguments with `arg.n`, and the host with
+    /// [`UiScript::arity`]. Both must tell zero returns from one `nil`, or an arity check passes a
+    /// binding that returns nothing.
     #[test]
     fn select_is_not_a_1_12_global_and_arg_n_answers_instead() {
         let s = UiScript::new().unwrap();
@@ -1207,7 +841,7 @@ mod error_quoting_tests {
             "`select` is 5.1's base library; `reference/1.12-globals.tsv` has no row for it"
         );
 
-        // 5.0's spelling, in the shape an addon writes it.
+        // 5.0's spelling, as an addon writes it.
         assert_eq!(
             s.eval::<Vec<i64>>(
                 "local function n(...) return arg.n end \
@@ -1220,28 +854,14 @@ mod error_quoting_tests {
             "arg.n must count trailing nils AND tell zero returns from one nil"
         );
 
-        // And the host's, which is what our own tests ask now.
+        // And the host's.
         assert_eq!(s.arity("nil").unwrap(), 1, "one nil is one value");
         assert_eq!(s.arity("ShowNameplates()").unwrap(), 0, "and zero is zero");
     }
 
-    /// **1.12 installs no metatable on the string type**, so method-call syntax on a string raises
-    /// there and quietly worked here (decision 2171).
-    ///
-    /// The claim is stronger than "nobody installs one": the reference's `lua_setmetatable
-    /// 0x6f4020` accepts exactly two type tags — `LUA_TTABLE` and `LUA_TUSERDATA`, sharing one
-    /// `mov [edx+8], esi` because 5.0 puts `metatable` at offset 8 of both structs — and returns 0
-    /// without writing for every other tag. 5.0 has no `G(L)->mt[]` array for a string to have a
-    /// slot in, so the type *cannot* carry one; `luaopen_string 0x7fd810`'s four instructions
-    /// are the same fact from the other end.
-    ///
-    /// The **wording** is asserted, not just the raise: it is what a player sees in a script
-    /// error, and 5.0's quoting convention is already load-bearing one file over — `sandbox`'s
-    /// `debugstack` emits 5.0 frames because `AceLibrary.lua:139`'s `argCheck` matches
-    /// ``"([`<].-['>])"`` and cannot see 5.4's `'name'` at all. Both strings are byte-verified
-    /// and executed on the reference: `.data 0x871c10` ``attempt to %s a %s value`` for the
-    /// anonymous form, `.data 0x871c2c` ``attempt to %s %s `%s' (a %s value)`` for the named one —
-    /// **backtick open, apostrophe close**.
+    /// 1.12's string type has no metatable, so a method call on a string raises, in the
+    /// reference's words: ``attempt to %s a %s value`` (`0x871c10`) and
+    /// ``attempt to %s %s `%s' (a %s value)`` (`0x871c2c`).
     #[test]
     fn the_string_type_has_no_metatable() {
         let s = UiScript::new().unwrap();
@@ -1270,9 +890,7 @@ mod error_quoting_tests {
             "the named form, with 5.0's backtick-apostrophe quoting: {named:?}"
         );
 
-        // The other direction, and the one that makes this a regression if it ever fails:
-        // removing the metatable removes a *dispatch*, never a function. The 12-member string
-        // library and the bare aliases the reference publishes over it are untouched.
+        // Only the method dispatch goes: the string library and its bare aliases still work.
         s.run(
             r#"assert(string.upper("ab") == "AB")
                assert(string.sub("hello", 2, 3) == "el")
diff --git a/crates/benilla-ui/src/script/lua50/table_size.rs b/crates/benilla-ui/src/script/lua50/table_size.rs
index ce7f132e..d666720b 100644
--- a/crates/benilla-ui/src/script/lua50/table_size.rs
+++ b/crates/benilla-ui/src/script/lua50/table_size.rs
@@ -1,54 +1,22 @@
-//! **Lua 5.0's remembered table size, and the whole library that rides it** (decision 2102).
+//! Lua 5.0's remembered table size, and the table library that reads it.
 //!
-//! 5.0 does **not** simply write `t.n`. `luaL_setn` (`0x6f4ea0`) writes `t.n` *only if a
-//! non-negative numeric `t.n` already exists*; otherwise it stores the size in a weak-keyed table
-//! kept in the registry (`getsizes 0x6f4fc0`, registry slot 2), so the size is invisible to
-//! anything walking the table. `luaL_getn` (`0x6f5050`) reads `t.n`, then `sizes[t]`, then counts
-//! `rawgeti` from 1 until the first nil.
+//! `luaL_setn` (`0x6f4ea0`) writes `t.n` only when a non-negative numeric `t.n` exists, else it
+//! stores the size in a weak-keyed registry table (`getsizes` `0x6f4fc0`, slot 2) no walk can see.
+//! `luaL_getn` (`0x6f5050`) reads `t.n`, then that table, then counts `rawgeti` from 1 to the
+//! first nil. `luaL_getn` serves `table.getn`, `insert`, `remove`, `concat`, `sort`, `foreachi`
+//! and base `unpack`; `luaL_setn` serves `table.setn`, `insert` and `remove`: the library is
+//! `n`-based end to end, where 5.1's is `#`-based.
 //!
-//! **And the size is not private to `getn`/`setn` — the whole table library rides it.** A
-//! whole-image call-site census lists every one:
-//! `luaL_getn` is called by `table.getn`, `table.insert`, `table.remove`, `table.concat`,
-//! `table.sort`, `table.foreachi` and **base `unpack`**; `luaL_setn` by `table.setn`,
-//! `table.insert` and `table.remove`. So `insert`/`remove` **update** the remembered size and the
-//! six readers read it — this library is `n`-based end to end, and a `#`-based (5.1) one is a
-//! different observable.
-//!
-//! **This module shipped for months with only `getn`/`setn` converted, and the divergence was
-//! recorded as knowingly-accepted "revisit if a runtime failure is ever traced here". One was.**
-//! Mik's Scrolling Battle Text 4.43 displays nothing at all in combat, because every combat line
-//! it parses runs through
-//!
-//! ```lua
-//! MikCEH.EraseTable(unorderedCaptureData)          -- wipe, then table.setn(t, 0)
-//! … table.insert(unorderedCaptureData, capture) …  -- 5.1: lands at #t+1, size NOT updated
-//! if (table.getn(tempCapturedData) ~= 0) then      -- reads the stale 0 → "no match"
-//! ```
-//!
-//! The captures were *there* (`t[1] = "Kobold Vermin"`, `t[2] = "12"`) and `getn` answered 0, so
-//! every parser returned nil and the addon drew nothing while scoring a clean load. That is the
-//! exact shape the note warned about, and it is why the readers are converted here too rather than
-//! left half-way: a library where the mutators maintain one size and the readers consult another
-//! is a worse place to stand than a uniformly wrong one.
-//!
-//! **The first draft of the `getn`/`setn` half wrote `t.n` unconditionally, and the corpus caught
-//! it inside an hour.** `AceOO-2.0`'s `_Embed` walks its mixin's exports with
-//! `next(state.export, field)` and errors on any field the target already has; a spurious `n` made
-//! that `Method conflict in attempt to mixin. Field "n"` — **39 addons**, a *bigger* wall than the
-//! `setn` gap it was meant to fix. The invisibility of the side store is load-bearing, and its
-//! test is below.
+//! The side store must stay invisible: a stray `n` key breaks mixin walks such as `AceOO-2.0`'s,
+//! which error on any field the target already has.
 
 use mlua::{Function, Lua, MultiValue, Table, Value};
 
-/// Where the weak-keyed side store lives. 5.0 keeps it in registry slot 2; mlua's registry is
-/// its own, so it gets a name instead — the property that matters is that it is reachable from
-/// nothing an addon can see.
+/// The side store's registry name; 5.0 uses slot 2, and either way no addon can reach it.
 const SIZES: &str = "benilla.lua50.sizes";
 
-/// `checkint 0x6f4f80` as `luaL_getn`/`luaL_setn` use it: a stored size counts only when it is
-/// a number **and** non-negative — a negative or absent one selects the next leg. (The
-/// reference coerces a numeric *string* here too, via `lua_tonumber`; we do not, and no corpus
-/// caller writes a string `n`.)
+/// `checkint` (`0x6f4f80`): a stored size counts only if numeric and non-negative. The reference
+/// also takes a numeric string through `lua_tonumber`; this does not.
 fn as_size(v: &Value) -> Option<i64> {
     match v {
         Value::Integer(i) => (*i >= 0).then_some(*i),
@@ -61,21 +29,12 @@ fn as_size(v: &Value) -> Option<i64> {
     }
 }
 
-/// The bound on how many elements one `insert`/`remove`/`unpack` may shift or push.
-///
-/// **Not the reference's** — 5.0 has no such limit, and this is the third knowing divergence in
-/// this module. It exists because a remembered size is an arbitrary number an addon wrote: after
-/// `table.setn(t, 2000000000)`, `table.remove(t, 1)` shifts two billion slots, and this runs in
-/// Rust, where the VM's instruction budget cannot interrupt it — a hung client rather than a slow
-/// one. A UI table never comes near a million entries; a runaway always exceeds it.
+/// The most elements one `insert`/`remove`/`unpack` may shift or push. Deviation: 5.0 has no
+/// bound, but a remembered size is whatever an addon wrote, and a Rust loop over two billion slots
+/// is beyond the VM's instruction budget: a hung client.
 const MAX_SHIFT: i64 = 1_000_000;
 
-/// `luaL_getn 0x6f5050` — `t.n`, then `sizes[t]`, then a linear count.
-///
-/// The count is `rawgeti` from 1 to the first nil, not the `#` border: 1.12's Lua has no length
-/// operator at all (decision 2101) and the two disagree on a table with holes, where `#` is
-/// explicitly undefined. It costs O(n) — exactly as it does in the reference, and only until
-/// the first `insert`/`setn` remembers a size for that table.
+/// `luaL_getn` (`0x6f5050`); its count to the first nil is not the `#` border on a holed table.
 fn get_n(sizes: &Table, t: &Table) -> mlua::Result<i64> {
     if let Some(n) = as_size(&t.raw_get::<Value>("n")?) {
         return Ok(n);
@@ -90,7 +49,7 @@ fn get_n(sizes: &Table, t: &Table) -> mlua::Result<i64> {
     Ok(i - 1)
 }
 
-/// `luaL_setn 0x6f4ea0` — into `t.n` when the table already carries one, else out of sight.
+/// `luaL_setn` (`0x6f4ea0`): into `t.n` when the table has one, else the side store.
 fn set_n(sizes: &Table, t: &Table, n: i64) -> mlua::Result<()> {
     if as_size(&t.raw_get::<Value>("n")?).is_some() {
         t.raw_set("n", n)
@@ -99,25 +58,16 @@ fn set_n(sizes: &Table, t: &Table, n: i64) -> mlua::Result<()> {
     }
 }
 
-/// Install the `n`-based table library over mlua's 5.1 one.
-///
-/// `concat` and `sort` **wrap** the C implementations rather than re-writing them: the only
-/// thing 5.0 changes about either is which number bounds the walk, and the C bodies carry the
-/// error messages (`invalid value (at index %d) in table for 'concat'`, `invalid order
-/// function for sorting`) and the sort algorithm that a Rust re-write would have to reproduce —
-/// including *not* handing a Lua comparator to Rust's `sort_by`, which panics on an
-/// inconsistent one.
+/// Install the `n`-based table library over mlua's 5.1 one. `concat` and `sort` wrap the C bodies
+/// for their error messages and algorithm (Rust's `sort_by` panics on an inconsistent comparator).
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
     let store = lua.create_table()?;
     let meta = lua.create_table()?;
-    // Weak KEYS: a table nobody else holds must still be collectable, and 5.0's own `getsizes`
-    // builds exactly this metatable.
+    // Weak keys, as 5.0's `getsizes` builds it: a table nobody else holds stays collectable.
     meta.set("__mode", "k")?;
     store.set_metatable(Some(meta))?;
-    // Kept in the registry so it survives for the VM's life and nothing an addon can reach
-    // names it — and captured by every closure below, so the hottest function in the whole UI
-    // (`table.insert`) costs two raw gets rather than a registry walk per call.
+    // Held by the registry for the VM's life; each closure below captures it.
     lua.set_named_registry_value(SIZES, store.clone())?;
     let sizes = store;
 
@@ -128,15 +78,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "getn",
         lua.create_function(move |_, t: Table| get_n(&getn_sizes, &t))?,
     )?;
-    // `table.setn 0x7fb670` — 0 results.
+    // `table.setn` (`0x7fb670`): no results.
     let setn_sizes = sizes.clone();
     t.set(
         "setn",
         lua.create_function(move |_, (t, n): (Table, i64)| set_n(&setn_sizes, &t, n))?,
     )?;
 
-    // `table.insert 0x7fb6a0` — `n = getn(t) + 1`; with a position argument the position may
-    // GROW n past it; `setn` first, then shift up from n down to pos, then store.
+    // `table.insert` (`0x7fb6a0`): `n = getn(t) + 1`, raised to a later position; `setn` first,
+    // then shift up from `n` down to `pos`, then store.
     let insert_sizes = sizes.clone();
     t.set(
         "insert",
@@ -182,8 +132,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `table.remove 0x7fb750` — an empty table (remembered size <= 0) returns NO value and
-    // touches nothing; otherwise `setn(n-1)`, take `t[pos]`, close the gap, nil the tail.
+    // `table.remove` (`0x7fb750`): at a size of 0 or less, no value and no change; else
+    // `setn(n - 1)`, take `t[pos]`, close the gap, nil the tail.
     let remove_sizes = sizes.clone();
     t.set(
         "remove",
@@ -207,7 +157,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `table.foreachi 0x7fb4e0` — 1..getn, stop and hand back the first non-nil result.
+    // `table.foreachi` (`0x7fb4e0`): `1..getn`, returning the first non-nil result.
     let foreachi_sizes = sizes.clone();
     t.set(
         "foreachi",
@@ -224,7 +174,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `table.concat 0x7fb860` — `j` defaults to getn, everything else is 5.1's own body.
+    // `table.concat` (`0x7fb860`): `j` defaults to getn; the rest is 5.1's body.
     let concat_sizes = sizes.clone();
     let concat: Function = t.get("concat")?;
     t.set(
@@ -240,12 +190,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?,
     )?;
 
-    // `table.sort 0x7fb900` — sorts `1..getn`, where 5.1's sorts `1..#t`. The two agree unless
-    // a remembered size is SHORTER than the array border, which is the only case that needs
-    // anything: lift the tail out, let the C sort run on exactly the elements 5.0 would have
-    // handed it, put the tail back. (A remembered size LONGER than the border would have 5.0
-    // comparing against nils and raising; we sort the border instead — a knowing divergence
-    // from an error path, not from a mechanism.)
+    // `table.sort` (`0x7fb900`) sorts `1..getn`, 5.1's `1..#t`: a shorter remembered size lifts
+    // the tail out around the C sort. Deviation: a longer one sorts only the border, where 5.0
+    // compares nils and raises: it departs from an error path, not from a mechanism.
     let sort_sizes = sizes.clone();
     let sort: Function = t.get("sort")?;
     t.set(
@@ -270,11 +217,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // Base `unpack 0x703080` — `1..getn(t)`, by `rawgeti`. The reference takes only the table
-    // and ignores anything after it, so no 1.12 caller can pass a range meaningfully; we keep
-    // 5.1's optional `i`/`j` because two of this crate's OWN stdlib helpers pass an explicit
-    // range to carry embedded nils (`tostringall`, the positional-`format` shim), and nothing
-    // an addon can write distinguishes the two.
+    // Base `unpack` (`0x703080`): `1..getn(t)` by `rawgeti`. Deviation: the reference ignores
+    // every argument after the table; `i`/`j` stay because the positional-`format` shim passes
+    // a range to carry embedded nils.
     g.set(
         "unpack",
         lua.create_function(move |_, (t, i, j): (Table, Option<i64>, Option<i64>)| {
@@ -283,8 +228,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 Some(j) => j,
                 None => get_n(&sizes, &t)?,
             };
-            // The reference's `luaL_checkstack(n, "table too big to unpack")`, at the same
-            // bound the shifts take.
+            // The reference's `luaL_checkstack(n, "table too big to unpack")`, at `MAX_SHIFT`.
             if j.saturating_sub(i) >= MAX_SHIFT {
                 return Err(mlua::Error::runtime("too many results to unpack"));
             }
@@ -303,13 +247,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 mod tests {
     use crate::script::UiScript;
 
-    /// **The failure that retired the "revisit if ever traced" note**, in the shape Mik's
-    /// Scrolling Battle Text 4.43 writes it (`MikCombatEventHelper.lua`'s `EraseTable` →
-    /// `GetUnorderedCaptureDataTable` → `GetCapturedData`).
-    ///
-    /// The captures are in the table and `getn` answered 0, so every combat line the addon parsed
-    /// came back "no match" and it drew nothing at all — through a clean load, a clean session and
-    /// a `drew=nothing(0)` harness row that read like an addon with nothing to draw.
+    /// Mik's Scrolling Battle Text 4.43's capture tables: wipe, `setn(t, 0)`, then insert.
     #[test]
     fn a_wipe_then_setn_zero_then_insert_is_countable_again() {
         let s = UiScript::new().unwrap();
@@ -330,11 +268,6 @@ mod tests {
         );
     }
 
-    /// `setn`/`getn` are 5.0's real pair, and the side store stays invisible.
-    ///
-    /// Both halves have been got wrong once each: a no-op `setn` fails the round-trip, and an
-    /// unconditional `rawset(t, "n", …)` passes it and breaks the 39 addons whose `AceOO-2.0`
-    /// mixin walk errors on a stray `n` (this module's header).
     #[test]
     fn the_remembered_size_round_trips_and_never_appears_as_a_key() {
         let s = UiScript::new().unwrap();
@@ -353,15 +286,13 @@ mod tests {
             3,
             "a remembered size must not appear as a key"
         );
-        // A table that already carries a numeric `n` keeps using it — 5.0's own first branch, and
-        // why `arg.n` behaves the way 5.0-era code expects.
+        // A table with a numeric `n` keeps using it: 5.0's first branch, which `arg.n` relies on.
         assert_eq!(
             s.eval::<i64>("local t = {1,2,3, n=3} table.setn(t, 7) return t.n")
                 .unwrap(),
             7
         );
-        // A NEGATIVE `n` is `checkint < 0`, which selects the side store rather than the field —
-        // `0x6f4ee4`'s `jl`.
+        // A negative `n` fails `checkint` and selects the side store (`0x6f4ee4`'s `jl`).
         assert_eq!(
             s.eval::<i64>("local t = {1,2, n=-1} table.setn(t, 5) return table.getn(t) + t.n")
                 .unwrap(),
@@ -369,11 +300,6 @@ mod tests {
         );
     }
 
-    /// The count of last resort is `rawgeti` to the first nil, not the `#` border — the two
-    /// disagree on a holed table, and `#` is not even in this VM's grammar (2101).
-    ///
-    /// This is the shape every `local t = { f() }` takes when `f` returns a nil in the middle, and
-    /// it is why `table.getn` is not a way to count returns on 1.12.
     #[test]
     fn the_fallback_count_stops_at_the_first_hole() {
         let s = UiScript::new().unwrap();
@@ -385,11 +311,10 @@ mod tests {
         assert_eq!(s.eval::<i64>("return table.getn({})").unwrap(), 0);
     }
 
-    /// `insert` with a position, and `remove` — the two that write the size back.
     #[test]
     fn insert_and_remove_maintain_the_size_the_way_the_reference_does() {
         let s = UiScript::new().unwrap();
-        // A position past the remembered size GROWS it (`if (pos > n) n = pos`).
+        // A position past the remembered size grows it (`if (pos > n) n = pos`).
         assert_eq!(
             s.eval::<String>(
                 "local t = {} table.insert(t, 3, 'c') \
@@ -398,7 +323,6 @@ mod tests {
             .unwrap(),
             "3:c"
         );
-        // Insert-at-position shifts up.
         assert_eq!(
             s.eval::<String>(
                 "local t = {'a','c'} table.insert(t, 2, 'b') \
@@ -407,7 +331,6 @@ mod tests {
             .unwrap(),
             "abc:3"
         );
-        // Remove returns the element, closes the gap, and shrinks the size.
         assert_eq!(
             s.eval::<String>(
                 "local t = {'a','b','c'} local got = table.remove(t, 1) \
@@ -416,7 +339,7 @@ mod tests {
             .unwrap(),
             "abc:2"
         );
-        // An empty table answers NO value at all and touches nothing (`if (n <= 0) return 0`).
+        // At size 0, no value and no change (`if (n <= 0) return 0`).
         assert_eq!(
             s.eval::<i64>(
                 "local t = {1,2,3} table.setn(t, 0) \
@@ -428,8 +351,6 @@ mod tests {
         );
     }
 
-    /// The four readers take the remembered size, not the border: `concat`, `sort`, `foreachi`,
-    /// and base `unpack` (the call-site census in this module's header).
     #[test]
     fn concat_sort_foreachi_and_unpack_all_read_the_remembered_size() {
         let s = UiScript::new().unwrap();
@@ -438,7 +359,6 @@ mod tests {
                 .unwrap(),
             "ab"
         );
-        // sort touches only 1..getn — the tail past it keeps both its values and its order.
         assert_eq!(
             s.eval::<String>(
                 "local t = {'c','a','z','y'} table.setn(t, 2) table.sort(t) \
@@ -463,9 +383,6 @@ mod tests {
             .unwrap(),
             "abnil"
         );
-        // The one superset this module keeps: an EXPLICIT range, which two of our own stdlib
-        // helpers pass to carry embedded nils. `tostringall`/the positional-`format` shim break
-        // without it, and no 1.12 caller can observe it (5.0's `unpack` ignores extra arguments).
         assert_eq!(
             s.eval::<String>(
                 "local t = {} t[1] = 'a' t[3] = 'c' \
@@ -475,7 +392,6 @@ mod tests {
             .unwrap(),
             "anilc"
         );
-        // ...and with nothing remembered they answer exactly what they always did.
         assert_eq!(
             s.eval::<String>("return table.concat({'a','b','c'}, '')")
                 .unwrap(),
@@ -488,8 +404,7 @@ mod tests {
         );
     }
 
-    /// The bare `getn` global and `table.getn` are one function, and `tinsert`/`tremove` — bound
-    /// by the stdlib layer, which runs after this one — are the new bodies rather than 5.1's.
+    /// `getn`, `tinsert` and `tremove`, bound by the stdlib layer after this one, are these bodies.
     #[test]
     fn the_bare_aliases_bind_the_5_0_bodies() {
         let s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/macros.rs b/crates/benilla-ui/src/script/macros.rs
index ae0ab661..9f5d2977 100644
--- a/crates/benilla-ui/src/script/macros.rs
+++ b/crates/benilla-ui/src/script/macros.rs
@@ -1,73 +1,42 @@
-//! Player **macros** (decision 0983) — the one seam in this crate that owns its game state
-//! outright, because the 1.12 macro system has no server side at all: there is no macro opcode on
-//! the wire (vmangos has none, and the client's own `UIMacros.cpp` persists to
-//! `WTF/…/macros-cache.txt`), so the macro table *is* client state. Contrast [`super::action`],
-//! whose 120-slot table the app owns because the server hands it back at login.
+//! Player macros. 1.12 keeps them client-side with no opcode (`macros-cache.txt`), and
+//! `CreateMacro` must return the new index at once, so the table lives here: the app seeds it
+//! ([`UiScript::set_macros`]), saves it when [`UiScript::take_macros_dirty`] says, and pushes the
+//! icon list ([`UiScript::set_macro_icons`]).
 //!
-//! That ownership is forced by the reference's own API shape, not chosen for convenience:
-//! `MacroPopupOkayButton_OnClick` does `index = CreateMacro(…)` and immediately selects `index`,
-//! so the mutation must be synchronous and must return the new slot — a queue-an-intent-and-wait
-//! seam cannot answer it. The app therefore **seeds** the table once ([`UiScript::set_macros`],
-//! from `benilla-config/macros/…`), **reads** it back to persist ([`UiScript::macros`]) whenever
-//! [`UiScript::take_macros_dirty`] says something moved, and pushes the icon-chooser list
-//! ([`UiScript::set_macro_icons`]) it builds off `SpellIcon.dbc`.
-//!
-//! ## The index space (VERIFIED, the shipped `Blizzard_MacroUI`)
-//!
-//! `MAX_MACROS = 18` per tab; `MacroFrame.macroBase` is `0` for the account tab and `18` for the
-//! character tab, and every binding takes `macroBase + i`. So **1..=18 are the account macros and
-//! 19..=36 the character macros**, each list dense from its base — `MacroFrame_Update` draws
-//! `i <= numMacros` and disables the rest, so a gap is not representable. [`MacroIndex`] is that
-//! split, made once at the boundary.
-//!
-//! ## What the engine does NOT know
-//!
-//! A macro's **bound spell** — the spell whose cooldown/usability/range a macro action-bar slot
-//! reports (`0x4e5a50`'s macro arm returns `[rec+0x564]`) — is the app's derivation, because
-//! resolving a name to a spell id needs the catalog and the player's book. The engine stores the
-//! body; `benilla::ui_macro` parses it. Same split as everywhere else in this crate: data and
-//! layout here, game knowledge
-//! there.
+//! Indices 1..=18 are the account macros and 19..=36 the character macros, each list dense from
+//! its base (`MacroFrame.macroBase`). A macro's bound spell (`0x4e5a50`'s macro arm returns
+//! `[rec+0x564]`) is the app's to derive: it needs the spell catalog and the player's book.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::cursor::{queue_cursor_update, CursorMacro, CursorPayload};
 use super::Model;
 
-/// Macros per tab — the shipped `Blizzard_MacroUI.lua`'s own `MAX_MACROS = 18`, and the account
-/// tab's size *and* the character tab's base (`MacroFrame_SetCharacterMacros` sets
-/// `macroBase = MAX_MACROS`).
+/// Macros per tab (`Blizzard_MacroUI.lua:1`), and so the character tab's base.
 pub const MAX_MACROS: usize = 18;
 
-/// The macro **name** length cap — `MacroPopupEditBox`'s `letters="16"` and its label
-/// `MACRO_POPUP_TEXT = "Enter Macro Name (Max 16 Characters):"`. Enforced here as well as in the
-/// box, because `CreateMacro`/`EditMacro` are callable from any script.
+/// The name cap, `MacroPopupEditBox`'s `letters="16"`.
 pub const MAX_MACRO_NAME: usize = 16;
 
-/// The macro **body** length cap — `MacroFrameText`'s `letters="255"` and its counter
-/// `MACROFRAME_CHAR_LIMIT = "%d/255 Characters Used"`.
+/// The body cap, `MacroFrameText`'s `letters="255"`.
 pub const MAX_MACRO_BODY: usize = 255;
 
 /// One macro, as `GetMacroInfo` reports it.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct MacroView {
-    /// The player's name for it (≤ [`MAX_MACRO_NAME`] characters).
     pub name: String,
-    /// The chosen icon's **texture path** (`Interface\Icons\Ability_Ambush`). Stored resolved
-    /// rather than as an index into the chooser list: the reference's own save format writes the
-    /// icon by NAME (`MACRO %d "%s" %s`, byte-verified at `0x44cb60`), so a name is what survives
-    /// a restart — an index would silently re-point if the list ever changed.
+    /// The icon's texture path, kept by name because the reference saves the icon by name
+    /// (`MACRO %d "%s" %s`, `0x44cb60`).
     pub texture: Option<String>,
-    /// The macro body: the lines run when the macro is used, `\n`-separated, ≤ [`MAX_MACRO_BODY`].
+    /// The macro's lines, `\n`-separated.
     pub body: String,
-    /// `GetMacroInfo`'s fourth return (`isLocal`) and `CreateMacro`/`EditMacro`'s `local`
-    /// argument. The 1.12 client keeps a second file for these (`macros-local.txt` beside
-    /// `macros-cache.txt`, both byte-verified strings at `0x45de74`/`0x45de88`); the shipped macro
-    /// UI never passes the flag, so it is carried faithfully and is otherwise inert.
+    /// `isLocal` and the `local` argument, carried but not saved here. The 1.12 client saves these
+    /// to `macros-local.txt` beside `macros-cache.txt` (`0x45de74`, `0x45de88`); the stock UI never
+    /// sets it.
     pub local_only: bool,
 }
 
-/// The whole macro table: the two dense lists behind the frame's two tabs (module docs).
+/// The macro table: the account and character lists.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct MacroState {
     /// Indices 1..=18.
@@ -76,19 +45,16 @@ pub struct MacroState {
     pub character: Vec<MacroView>,
 }
 
-/// A 1-based Lua macro index resolved into `(which list, position in it)` — the one place the
-/// 1..36 space is split, so no binding re-derives the base.
+/// A 1-based Lua macro index split into its list and 0-based position.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub(crate) struct MacroIndex {
-    /// True for 19..=36 (the character tab).
+    /// True for 19..=36.
     per_character: bool,
-    /// 0-based position within that tab's list.
     pos: usize,
 }
 
 impl MacroIndex {
-    /// Split a 1-based Lua index; `None` outside 1..=36. Deliberately NOT range-checked against
-    /// the live lists — callers that need an occupied slot go through [`MacroState::get`].
+    /// `None` outside 1..=36; not checked against the lists, which [`MacroState::get`] does.
     fn split(index: usize) -> Option<Self> {
         let zero = index.checked_sub(1)?;
         match zero {
@@ -104,14 +70,13 @@ impl MacroIndex {
         }
     }
 
-    /// The 1-based Lua index this position occupies.
     fn lua_index(self) -> usize {
         self.pos + 1 + if self.per_character { MAX_MACROS } else { 0 }
     }
 }
 
 impl MacroState {
-    /// The macro at a 1-based Lua index, or `None` for an empty/out-of-range slot.
+    /// The macro at a 1-based Lua index.
     pub fn get(&self, index: usize) -> Option<&MacroView> {
         let at = MacroIndex::split(index)?;
         self.list(at.per_character).get(at.pos)
@@ -133,10 +98,7 @@ impl MacroState {
         }
     }
 
-    /// `GetMacroIndexByName`'s search — case-insensitive, account list first (the reference walks
-    /// the one flat 1..36 space, and the account half is its low end). `0` when nothing matches,
-    /// which is the reference's own miss value (a number, never nil — the shipped
-    /// `Usage: GetMacroIndexByName(name)` binding pushes a number).
+    /// `GetMacroIndexByName`: case-insensitive, account list first; 0 on a miss, as in 1.12.
     pub fn index_by_name(&self, name: &str) -> usize {
         for per_character in [false, true] {
             for (i, m) in self.list(per_character).iter().enumerate() {
@@ -153,16 +115,14 @@ impl MacroState {
     }
 }
 
-/// Clamp a player-supplied string to a character (not byte) cap — the EditBox's own
-/// `max_letters` rule, applied again at the API so a script cannot store what the box refuses.
+/// Clamp to a count of characters, not bytes, as the edit boxes do, so a script cannot store more.
 fn clamp_chars(s: &str, max: usize) -> String {
     s.chars().take(max).collect()
 }
 
 impl super::UiScript {
-    /// Seed the whole macro table, replacing whatever was there — the app's load path
-    /// (`benilla-config/macros/…`). Does **not** mark the table dirty: the app already has what it just
-    /// handed over, and a save triggered by its own load would be a write-back loop.
+    /// Seed the whole table from the app's load. It does not mark the table dirty, or the load
+    /// would trigger a save.
     pub fn set_macros(&mut self, state: MacroState) {
         let mut model = self.model_mut();
         model.macros = state;
@@ -170,43 +130,33 @@ impl super::UiScript {
         model.macros_generation += 1;
     }
 
-    /// Read the live macro table — the app's save path, taken when [`Self::take_macros_dirty`]
-    /// reports a change.
+    /// The live table, for the app's save.
     pub fn macros(&self) -> MacroState {
         self.model_mut().macros.clone()
     }
 
-    /// Did a script mutate the table since the last call (`CreateMacro`/`EditMacro`/`DeleteMacro`)?
-    /// The app persists on a `true` and fires `UPDATE_MACROS` — the reference's own event for
-    /// exactly this transition (byte-verified string at `0x452460`).
+    /// Whether a script changed the table since the last call; the app then saves it and fires
+    /// `UPDATE_MACROS` (`0x452460`).
     pub fn take_macros_dirty(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().macros_dirty)
     }
 
-    /// Push the icon-chooser list — the full texture paths `GetMacroIconInfo` serves, in the order
-    /// the popup's grid shows them. Built by the app off `SpellIcon.dbc` (`benilla::ui_macro`).
+    /// Push the icon chooser's texture paths in grid order, built by the app from `SpellIcon.dbc`.
     pub fn set_macro_icons(&mut self, icons: Vec<String>) {
         self.model_mut().macro_icons = icons;
     }
 
-    /// The macro table's **generation** — bumped by every seed and every mutation, so a per-frame
-    /// consumer can gate an expensive re-resolve on a `u64` compare instead of cloning the table
-    /// to diff it. The action bar's identity feed reads it as a third input beside its `dirty`
-    /// flag and the item-template epoch (the same shape decision 0660 gave that one): a macro's
-    /// icon changes when the macro is edited, which touches neither of the other two.
-    ///
-    /// Distinct from [`Self::take_macros_dirty`] on purpose — that one is a *drained* edge with
-    /// exactly one owner (the save), and a second consumer draining it would silently eat the
-    /// other's save.
+    /// Bumped by every seed and every change, so a per-frame reader such as the action bar compares
+    /// a `u64` instead of diffing the table. Not [`Self::take_macros_dirty`]: that drain has one
+    /// owner, the save, and a second reader would steal its edge.
     pub fn macros_generation(&self) -> u64 {
         self.model_mut().macros_generation
     }
 }
 
-/// `CreateMacro(name, iconIndex, body, local, perCharacter)` — the shipped binding's own argument
-/// list (byte-verified usage string at `0x44cb74`). Returns the new macro's 1-based index, or
-/// `None` on the two failures the client names in its own log lines (`0x44cbb4`/`0x44cbdc`):
-/// an empty name, and a full tab.
+/// `CreateMacro(name, iconIndex, body, local, perCharacter)` (usage string `0x44cb74`): the new
+/// 1-based index, or `None` on the two failures the client logs (`0x44cbb4`, `0x44cbdc`), an empty
+/// name and a full tab.
 fn create_macro(
     model: &mut Model,
     name: &str,
@@ -239,11 +189,9 @@ fn create_macro(
     Some(MacroIndex { per_character, pos }.lua_index())
 }
 
-/// `EditMacro(index, name, icon, body, local)` — every argument is optional past the index, and an
-/// omitted one leaves that field alone. That is load-bearing, not defensive: the shipped UI calls
-/// it **twice with disjoint halves** — `EditMacro(sel, name, icon)` from the rename popup and
-/// `EditMacro(sel, nil, nil, text)` from `MacroFrame_SaveMacro` — so a nil that overwrote would
-/// blank the body every time the name changed.
+/// `EditMacro(index, name, icon, body, local)`: an omitted argument leaves its field alone, since
+/// the stock UI calls it with disjoint halves, `(sel, name, icon)` from the rename popup and
+/// `(sel, nil, nil, text)` from `MacroFrame_SaveMacro`.
 fn edit_macro(
     model: &mut Model,
     index: usize,
@@ -256,8 +204,7 @@ fn edit_macro(
     let entry = model.macros.list_mut(at.per_character).get_mut(at.pos)?;
     if let Some(name) = name {
         let name = clamp_chars(name.trim(), MAX_MACRO_NAME);
-        // An explicit blank is refused rather than stored: `MacroPopupOkayButton_Update` already
-        // keeps OKAY disabled on an empty box, so reaching here means a script did it.
+        // A blank name is ignored; the stock popup cannot send one (`MacroPopupOkayButton_Update`).
         if !name.is_empty() {
             entry.name = name;
         }
@@ -276,11 +223,8 @@ fn edit_macro(
     Some(index)
 }
 
-/// `DeleteMacro(index)` — removes the slot and **closes the gap**, which is why every action-bar
-/// slot holding a higher macro index would now point at the wrong macro. The reference has the
-/// same property (its own list is dense, and `MacroFrame_Update` draws it densely); the app's
-/// action feed re-resolves against the shifted table, so a bar button follows the slot, not the
-/// macro. Named in decision 0983 as faithful-and-surprising rather than fixed.
+/// `DeleteMacro(index)` closes the gap, as the reference's dense list does, so an action-bar
+/// button holding a higher index then shows the next macro.
 fn delete_macro(model: &mut Model, index: usize) -> bool {
     let Some(at) = MacroIndex::split(index) else {
         return false;
@@ -295,14 +239,9 @@ fn delete_macro(model: &mut Model, index: usize) -> bool {
     true
 }
 
-/// `PickupMacro(index)` — the macro button's `OnDragStart` and the selected-macro button's
-/// `OnClick` (both in the shipped `Blizzard_MacroUI.xml`). Loads the cursor with the macro
-/// payload (the client's mode **8**, `[0xb4e2fc]`), which `PlaceAction 0x4e62e0` then packs as
-/// `macroId | 0x40000000`.
-///
-/// Refuses while the cursor already holds something, matching `PickupSpell`'s precedent: a macro
-/// button is a SOURCE, never a fit-checked drop target, so silently discarding the held payload
-/// would be worse than doing nothing.
+/// `PickupMacro(index)`: the macro payload (cursor mode 8, `[0xb4e2fc]`), which `PlaceAction`
+/// (`0x4e62e0`) packs as `macroId | 0x40000000`. Refused while the cursor holds anything; the
+/// reference's setter (`0x494f80`) clears the cursor first instead.
 fn pickup_macro(model: &mut Model, index: usize) -> bool {
     if model.cursor.is_some() {
         return false;
@@ -319,7 +258,6 @@ fn pickup_macro(model: &mut Model, index: usize) -> bool {
     true
 }
 
-/// Coerce a Lua argument that the shipped UI passes as either a real value or `nil`/`false`.
 fn opt_string(v: Option<&Value>) -> Option<String> {
     match v {
         Some(Value::String(s)) => Some(s.to_string_lossy()),
@@ -327,10 +265,9 @@ fn opt_string(v: Option<&Value>) -> Option<String> {
     }
 }
 
-/// The reference's own truthiness for the `local`/`perCharacter` flags: `MacroPopupOkayButton_OnClick`
-/// passes the Lua boolean `(MacroFrame.macroBase > 0)`, and the shipped `local` argument is always
-/// `nil`. `0` reads falsy here (the numeric convention `UseAction`'s `checkCursor` established —
-/// `super::action::truthy_nonzero`'s law, shared so the two cannot drift).
+/// The `local` and `perCharacter` flags: `nil`, `false` and `0` are false, as in `UseAction`. The
+/// reference reads them with `GetBoolOrDefault` (`0x6f1c10`), which also takes `"0"` and any
+/// number that truncates to 0 as false; the stock popup passes a Lua boolean and never `local`.
 fn flag(v: Option<&Value>) -> bool {
     v.is_some_and(super::action::truthy_nonzero)
 }
@@ -339,7 +276,6 @@ fn flag(v: Option<&Value>) -> bool {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetNumMacros() -> numAccountMacros, numCharacterMacros.
     g.set(
         "GetNumMacros",
         lua.create_function(|lua, ()| {
@@ -351,8 +287,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetMacroInfo(index) -> name, texture, body, isLocal. An empty/out-of-range slot answers a
-    // single nil (the out-of-range shape every list binding in this crate uses).
     g.set(
         "GetMacroInfo",
         lua.create_function(|lua, index: usize| {
@@ -377,7 +311,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetMacroIndexByName(name) -> index (0 = no match).
     g.set(
         "GetMacroIndexByName",
         lua.create_function(|lua, name: String| {
@@ -386,7 +319,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetNumMacroIcons() -> the chooser list's length.
     g.set(
         "GetNumMacroIcons",
         lua.create_function(|lua, ()| {
@@ -395,7 +327,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetMacroIconInfo(index) -> texture path; 1-based, out of range -> nil.
     g.set(
         "GetMacroIconInfo",
         lua.create_function(|lua, index: usize| {
@@ -413,10 +344,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CreateMacro(name, iconIndex, body, local, perCharacter) -> index | nil.
-    // `iconIndex` is an index into the chooser list (the shipped popup passes
-    // `MacroPopupFrame.selectedIcon`), resolved to a path HERE so the stored macro keeps a name
-    // that survives a restart.
+    // CreateMacro stores `iconIndex`, an index into the chooser list, as its path.
     g.set(
         "CreateMacro",
         lua.create_function(|lua, args: MultiValue| {
@@ -435,8 +363,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // EditMacro(index, name, icon, body, local) -> index | nil. Absent arguments leave their
-    // field alone (see `edit_macro` — the shipped UI relies on it).
     g.set(
         "EditMacro",
         lua.create_function(|lua, args: MultiValue| {
@@ -445,8 +371,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 return Ok(Value::Nil);
             };
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // An icon argument that is present-and-resolvable replaces; an absent/nil one leaves
-            // the icon alone. (`MacroFrame_SaveMacro` passes nil here on every body-only save.)
+            // A nil icon leaves the icon alone: `MacroFrame_SaveMacro` passes nil on every save.
             let texture = match a.get(2) {
                 None | Some(Value::Nil) => None,
                 other => Some(icon_path(&model, other)),
@@ -485,8 +410,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Resolve a chooser-list **index** argument to a texture path. A string is taken as a path
-/// already (nothing shipped does that, but a script may, and the store holds paths anyway).
+/// Resolve a chooser-list index to its texture path; a string is taken as a path already.
 fn icon_path(model: &Model, v: Option<&Value>) -> Option<String> {
     match v {
         Some(Value::String(s)) => Some(s.to_string_lossy()),
@@ -514,8 +438,6 @@ mod tests {
         s
     }
 
-    /// The whole create → read → edit → delete round trip through the reference's own signatures,
-    /// including the index space's account/character split.
     #[test]
     fn the_macro_api_round_trip_over_the_two_tabs() {
         let s = seeded();
@@ -525,12 +447,10 @@ mod tests {
             (0, 0)
         );
 
-        // Account tab: perCharacter falsy -> index 1.
         let i = s
             .eval::<i64>(r#"return CreateMacro("Ambush", 1, "/cast Ambush", nil, nil)"#)
             .unwrap();
         assert_eq!(i, 1);
-        // Character tab: perCharacter truthy -> the 19 base.
         let j = s
             .eval::<i64>(r#"return CreateMacro("Bolt", 3, "/cast Fireball", nil, true)"#)
             .unwrap();
@@ -541,7 +461,6 @@ mod tests {
             (1, 1)
         );
 
-        // GetMacroInfo's four returns, with the icon index resolved to a path at create time.
         let (name, tex, body, is_local) = s
             .eval::<(String, String, String, Value)>(
                 "local n, t, b, l = GetMacroInfo(1) return n, t, b, l",
@@ -553,7 +472,6 @@ mod tests {
         );
         assert_eq!(is_local, Value::Nil);
 
-        // By-name is case-insensitive and searches the account list first; a miss is 0.
         assert_eq!(
             s.eval::<i64>(r#"return GetMacroIndexByName("ambush")"#)
                 .unwrap(),
@@ -570,7 +488,7 @@ mod tests {
             0
         );
 
-        // Delete closes the gap: the character macro keeps its own base.
+        // The character macro keeps its own base after the delete.
         assert!(s.eval::<bool>("return DeleteMacro(1)").unwrap());
         assert_eq!(
             s.eval::<(i64, i64)>("local a, c = GetNumMacros() return a, c")
@@ -581,14 +499,12 @@ mod tests {
         assert_eq!(s.eval::<String>("return GetMacroInfo(19)").unwrap(), "Bolt");
     }
 
-    /// `EditMacro`'s partial-update law — the shipped UI's two disjoint calls. A rename must not
-    /// blank the body, and a body save must not blank the name or icon.
     #[test]
     fn edit_macro_leaves_omitted_fields_alone() {
         let s = seeded();
         s.run(r#"CreateMacro("Old", 1, "/cast Ambush")"#).unwrap();
 
-        // MacroPopupOkayButton_OnClick's edit form: name + icon, no body.
+        // MacroPopupOkayButton_OnClick's form: name and icon.
         s.run(r#"EditMacro(1, "New", 2)"#).unwrap();
         let (name, tex, body) = s
             .eval::<(String, String, String)>("local n, t, b = GetMacroInfo(1) return n, t, b")
@@ -597,7 +513,7 @@ mod tests {
         assert_eq!(tex, "Interface\\Icons\\Ability_BackStab");
         assert_eq!(body, "/cast Ambush", "the body survives a rename");
 
-        // MacroFrame_SaveMacro's form: body only, name and icon nil.
+        // MacroFrame_SaveMacro's form: the body alone.
         s.run(r#"EditMacro(1, nil, nil, "/cast Backstab")"#)
             .unwrap();
         let (name, tex, body) = s
@@ -614,7 +530,6 @@ mod tests {
         );
     }
 
-    /// The two refusals the client names in its own log lines, and the caps the edit boxes carry.
     #[test]
     fn create_refuses_a_blank_name_and_a_full_tab_and_clamps_the_caps() {
         let s = seeded();
@@ -636,14 +551,13 @@ mod tests {
                 .unwrap(),
             "the 19th account macro is refused"
         );
-        // …and the character tab is a separate 18.
+        // The character tab is a separate 18.
         assert_eq!(
             s.eval::<i64>(r#"return CreateMacro("c", 1, "", nil, 1)"#)
                 .unwrap(),
             19
         );
 
-        // The caps are the shipped boxes' own letters= values, enforced at the API too.
         let s = seeded();
         s.run(&format!(
             r#"CreateMacro("{}", 1, "{}")"#,
@@ -658,8 +572,6 @@ mod tests {
         assert_eq!(body.chars().count(), MAX_MACRO_BODY);
     }
 
-    /// The dirty flag is the app's save trigger: every mutation raises it, a seed never does, and
-    /// the drain clears it.
     #[test]
     fn mutations_raise_the_dirty_flag_and_a_seed_does_not() {
         let mut s = seeded();
@@ -675,11 +587,9 @@ mod tests {
         s.run("DeleteMacro(1)").unwrap();
         assert!(s.take_macros_dirty());
 
-        // A no-op delete changes nothing and raises nothing.
         s.run("DeleteMacro(7)").unwrap();
         assert!(!s.take_macros_dirty());
 
-        // The app's own seed must not trigger a save (a write-back loop).
         s.set_macros(MacroState {
             account: vec![MacroView {
                 name: "loaded".into(),
@@ -691,7 +601,6 @@ mod tests {
         assert_eq!(s.macros().account.len(), 1);
     }
 
-    /// `PickupMacro` loads the cursor with the macro payload, and refuses while holding.
     #[test]
     fn pickup_macro_loads_the_cursor_and_refuses_while_holding() {
         use crate::script::cursor::CursorPayload;
@@ -712,7 +621,6 @@ mod tests {
                 texture: Some("Interface\\Icons\\Ability_Ambush".into()),
             }))
         );
-        // GetCursorInfo's Era shape for a macro: the kind word + the index.
         assert_eq!(
             s.eval::<(String, i64)>("local k, i = GetCursorInfo() return k, i")
                 .unwrap(),
@@ -724,8 +632,6 @@ mod tests {
         );
     }
 
-    /// The chooser list is the app's, served 1-based, and an out-of-range index is nil rather
-    /// than an error (`MacroPopupFrame_Update` indexes past the end on the last row every time).
     #[test]
     fn the_icon_chooser_list_is_one_based_with_a_nil_tail() {
         let s = seeded();
diff --git a/crates/benilla-ui/src/script/mail.rs b/crates/benilla-ui/src/script/mail.rs
index 38df8aa9..93d57078 100644
--- a/crates/benilla-ui/src/script/mail.rs
+++ b/crates/benilla-ui/src/script/mail.rs
@@ -1,32 +1,6 @@
-//! The mail bindings (decision 0544 P1/P2) — the Era-shaped mailbox surface, the same two-way seam
-//! as [`super::merchant`]/[`super::loot`]: the app pushes a **mail snapshot**
-//! ([`UiScript::set_mail`] — the inbox rows already resolved from the wire to
-//! name/icon/sender/body by the app's item-template + name caches) and the Lua
-//! `CheckInbox`/`TakeInboxItem`/`SendMail`/… calls queue outbound **intents** the app drains. The
-//! engine holds no mail knowledge — a row is a header (sender/subject/money/COD/expiry/flags), an
-//! optional enclosed item (id/name/icon/quality), an ask-once letter body, and a stationery
-//! basename.
-//!
-//! ## The 5875 API shape (VERIFIED against the extracted `MailFrame.lua`)
-//!
-//! `index` is **1-based** everywhere; an out-of-range index answers `nil`/`0`. The inbox getters:
-//! `GetInboxNumItems()`, `GetInboxHeaderInfo(index)` → the reference 13-tuple
-//! `packageIcon, stationeryIcon, sender, subject, money, CODAmount, daysLeft, hasItem(count|nil),
-//! wasRead, wasReturned, textCreated, canReply, isGM` (MailFrame.lua l.105/265/279),
-//! `GetInboxText(index)` → `body, stationeryTexture, isTakeable, isInvoice` (l.292 — a body cache
-//! miss queues the `CMSG_ITEM_TEXT_QUERY` fetch and returns `""`), `GetInboxItem(index)` →
-//! `name, texture, count, quality, canUse` (l.379), `InboxItemCanDelete(index)` → 1/nil (the
-//! delete-vs-return law, l.417/450). `HasNewMail()` reads the app-pushed login-scoped flag
-//! ([`UiScript::set_has_new_mail`], decision 0544 P3) — `nil` (false) until the app's first
-//! `MSG_QUERY_NEXT_MAIL_TIME` answer lands.
-//!
-//! The send tab: `GetSendMailItem()` → `name, texture, stackCount, quality` off the attached cursor
-//! item (l.511), `GetSendMailPrice()` → the flat **30c** postage (vmangos's fee), `SendMail(target,
-//! subject, body)` fires the send, `SetSendMailMoney`/`SetSendMailCOD(copper)` push the money/COD
-//! amounts the app reads at send time, `ClickSendMailItemButton()` attaches (or detaches) the
-//! cursor's held bag item as the send attachment (l.719). Intents `CheckInbox`, `TakeInboxItem`,
-//! `TakeInboxMoney`, `DeleteInboxItem`, `ReturnInboxItem`, `CloseMail` are 1-based row indices /
-//! flags the app maps to the wire.
+//! The mail bindings. The app pushes the open mailbox's inbox, already resolved from the wire
+//! (`UiScript::set_mail`), and the Lua verbs queue intents the app drains and sends. Indices are
+//! 1-based, as `MailFrame.lua` uses them.
 
 use mlua::{Lua, MultiValue, Value};
 
@@ -34,143 +8,107 @@ use super::binding_abi::flag;
 use super::cursor::{self, CursorPayload};
 use super::Model;
 
-/// One inbox row, resolved by the app from a wire `MailListEntry` (decision 0544). Plain data — its
-/// 1-based order in the window is its position in [`MailState::inbox`].
+/// One inbox row, resolved by the app from a wire `MailListEntry`; its 1-based index is its
+/// position in [`MailState::inbox`].
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct MailInboxRow {
-    /// The enclosed item's icon (`GetInboxHeaderInfo`'s `packageIcon`); `None` when the mail carries
-    /// no item, or while its template answer is in flight.
+    /// `packageIcon`, the enclosed item's icon; `None` with no item or while its template loads.
     pub package_icon: Option<String>,
-    /// The letter icon (`stationeryIcon`) — the app derives it from the stationery id/GM flag; the
-    /// row shows this when there's no package (or it's GM mail).
     pub stationery_icon: Option<String>,
-    /// The sender name (`sender`), resolved through the name cache; `None` while in flight or for a
-    /// non-player sender (the Lua shows `UNKNOWN`).
+    /// `sender`, from the name cache; `None` while in flight or for a non-player sender.
     pub sender: Option<String>,
     pub subject: String,
     pub money: u32,
     pub cod: u32,
-    /// Days remaining before the mail is deleted/returned (`daysLeft`, the wire `expire_days`).
     pub days_left: f32,
-    /// The enclosed item's stack count (`GetInboxHeaderInfo`'s `hasItem` returns this, or `nil` when
-    /// `0`). `0` = no item.
+    /// The enclosed stack's count, answered as `hasItem`; 0 (nil) is no item.
     pub item_count: u32,
     /// `checked & READ(0x1)`.
     pub was_read: bool,
     /// `checked & RETURNED(0x2)`.
     pub was_returned: bool,
-    /// `checked & COPIED(0x4)` — the letter body was materialized as a text item (`textCreated`).
+    /// `checked & COPIED(0x4)`: the letter was copied to an item (`textCreated`).
     pub text_created: bool,
-    /// `sender_guid.is_some() && !was_returned` — the Reply button gate (l.281).
+    /// `sender_guid.is_some() && !was_returned`, the Reply button's gate (`MailFrame.lua:281`).
     pub can_reply: bool,
-    /// `stationery == 61` — a GM mail (l.108).
+    /// `stationery == 61`: a GM mail (vmangos `MAIL_STATIONERY_GM`, `Mail.h:85`).
     pub is_gm: bool,
-    /// The letter body (`GetInboxText`'s first return); `None` = not fetched yet (the getter returns
-    /// `""` and queues the ask-once `CMSG_ITEM_TEXT_QUERY` when [`Self::has_body`]).
+    /// The letter body; `None` until fetched, while `GetInboxText` answers `""`.
     pub body: Option<String>,
-    /// The stationery texture basename (`GetInboxText`'s second return) — the Lua wraps it as
-    /// `Interface\Stationery\<basename>1`/`2` for the open-letter backdrop.
     pub stationery_texture: String,
-    /// `GetInboxText`'s fourth return. **Narrower than "an auction mail"**: the reference answers
-    /// `1` iff the record carries the three fields its subject parser persisted (`[rec+0x250] != 0`,
-    /// `0x4af2eb`), and the parser persists them *only* for result code 1 (won) or 2 (sold). An
-    /// outbid or expiry notice is an auction mail that is **not** an invoice (decision 1527).
+    /// `isInvoice`: only an auction won (result 1) or sold (2), not an outbid or expiry notice
+    /// (`0x4af2eb`).
     pub is_invoice: bool,
-    /// The auction invoice this mail carries, once it can be answered — `GetInboxInvoiceInfo`'s
-    /// seven values. `None` is the reference's **miss tail**, and it covers four different states
-    /// that all read the same from Lua: not an auction mail at all; an auction mail whose result
-    /// code is not won(1)/sold(2) (an outbid or expiry notice carries no body and no invoice); the
-    /// body not fetched yet; or the counterparty's name still in flight.
+    /// `GetInboxInvoiceInfo`'s answer; `None`, the reference's miss, also while the body or the
+    /// counterparty's name is in flight.
     pub invoice: Option<MailInvoice>,
-    /// The mail carries a fetchable letter body (`item_text_id != 0`) — gates the body ask.
+    /// `item_text_id != 0`: the mail has a letter body to fetch.
     pub has_body: bool,
-    /// The enclosed item's template entry (`0` = none) — the shared item-tooltip store's key
-    /// (`GameTooltip:SetInboxItem`) and `GetInboxItem`'s identity.
+    /// The enclosed item's template entry, 0 for none; the key `SetInboxItem`'s tooltip reads.
     pub item_id: u32,
-    /// The enclosed item's **random-suffix roll** (`SMSG_MAIL_LIST`'s per-item `randomPropId`) —
-    /// what the hover resolves its enchant lines from, and the id whose suffix
-    /// [`Self::item_name`] already carries. `0` = unrolled. The reference's `SetInboxItem` writes
-    /// exactly this into the tooltip's `+0x424` (decision 1547).
+    /// The enclosed item's random-suffix id (the wire `randomPropId`), 0 for none, which the
+    /// reference's `SetInboxItem` hands the tooltip (`+0x424`); `item_name` carries its suffix.
     pub item_random_property_id: u32,
-    /// The enclosed item's name (`GetInboxItem`'s first return); `None` while the template is in
-    /// flight.
+    /// The enclosed item's name; `None` while its template is in flight.
     pub item_name: Option<String>,
-    /// The enclosed item's icon; `None` while in flight.
     pub item_texture: Option<String>,
-    /// The enclosed item's quality (0..6); `None` while in flight.
     pub item_quality: Option<u32>,
-    /// `InboxItemCanDelete` — the delete-vs-return law (`!can_reply`: a not-yet-returned mail from a
-    /// player is returnable, everything else is deletable — l.417/450).
+    /// `InboxItemCanDelete`: `!can_reply`, as a player's unreturned mail is returned instead
+    /// (`MailFrame.lua:417`, `:450`).
     pub can_delete: bool,
 }
 
-/// One auction mail's invoice — what `GetInboxInvoiceInfo(index)` hands back, already parsed.
-///
-/// The invoice is **TEXT**, not wire data: the auction house writes the numbers into the mail's
-/// subject and body and the client `sscanf`s them back out (`GetInboxInvoiceInfo 0x4af360`).
-/// The app owns that parse; this is its result.
+/// One auction invoice, `GetInboxInvoiceInfo`'s answer, parsed by the app from the mail's subject
+/// and body text as the reference `sscanf`s them (`0x4af360`).
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct MailInvoice {
-    /// `true` → the literal token `"seller"` (your auction sold), `false` → `"buyer"` (you won).
-    /// A bare ASCII token in the reference too, not a GlobalString — the Lua compares it as one.
+    /// `"seller"` (your auction sold) or `"buyer"` (you won), literal tokens, not global strings.
     pub seller: bool,
-    /// The auctioned item's name, composed from the subject's item entry.
     pub item_name: String,
     /// The counterparty: who bought it (seller invoice) or who sold it (buyer invoice).
     pub player_name: String,
-    /// The winning bid. `bid == buyout` is how the window knows it was a buyout rather than a bid.
+    /// The winning bid; the window reads `bid == buyout` as a buyout (`MailFrame.lua:307`).
     pub bid: u32,
     pub buyout: u32,
-    /// Seller invoices only (`0` on a buyer invoice — the body carries three fields, not five).
+    /// Seller invoices only; 0 on a buyer's, whose body carries three fields, not five.
     pub deposit: u32,
     /// The auction house's cut, seller invoices only.
     pub consignment: u32,
 }
 
-/// The open mailbox's inbox snapshot. Pushed whole by the app; `None` means no mailbox is open (the
-/// window is closed).
+/// The open mailbox's inbox, pushed whole by the app; `set_mail(None)` means no mailbox is open.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct MailState {
     pub inbox: Vec<MailInboxRow>,
 }
 
-/// One usable stationery, as the send tab's picker lists it (`GetNumStationeries` /
-/// `GetStationeryInfo`, 1970) — the app computes the usable set off `Stationery.dbc` and the
-/// player's bags, sorted by price, and pushes it whole ([`super::UiScript::set_mail_stationeries`]).
+/// One usable stationery in the send tab's picker; the app builds the list from `Stationery.dbc`
+/// and the bags, sorted by price.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct StationeryView {
-    /// The `Stationery.dbc` row id — what `SelectStationery` stores and `CMSG_SEND_MAIL` carries.
+    /// The `Stationery.dbc` row id, which `SelectStationery` stores and `CMSG_SEND_MAIL` carries.
     pub id: u32,
-    /// The stationery item's name (`GetStationeryInfo`'s first return).
     pub name: String,
-    /// The item's icon as a FULL path (`Interface\Icons\…`) — `GetStationeryInfo`'s second
-    /// return is used raw by `SetTexture` (MailFrame.lua l.671), unlike the bare basename below.
+    /// The item's icon as a full `Interface\Icons\` path, which `MailFrame.lua:671` sets as is.
     pub icon: String,
-    /// The item's BuyPrice in copper, or `None` when the player already carries the item
-    /// (`GetStationeryInfo`'s third return is nil then).
+    /// The item's BuyPrice in copper; `None` (nil) when the player carries one.
     pub cost: Option<u32>,
-    /// The bare texture basename (`GetSelectedStationeryTexture`), wrapped by the Lua as
-    /// `STATIONERY_PATH..texture.."1"/"2"`.
+    /// The bare texture basename that `GetSelectedStationeryTexture` answers.
     pub texture: String,
 }
 
-/// A drained `SendMail` intent — the app resolves the attachment `(bag, slot)` to an item guid and
-/// builds `CMSG_SEND_MAIL` from this (decision 0544 P2).
+/// A drained `SendMail` intent, which the app turns into `CMSG_SEND_MAIL`.
 #[derive(Clone, Debug, PartialEq)]
 pub struct MailSendRequest {
     pub target: String,
     pub subject: String,
     pub body: String,
-    /// The selected `Stationery.dbc` id — `CMSG_SEND_MAIL`'s sixth field (never 0 here: a send with
-    /// no selection aborts before it is queued, `0x4ae8dd`).
+    /// The selected `Stationery.dbc` id; never 0, as a send with none aborts (`0x4ae8dd`).
     pub stationery: u32,
-    /// Money to enclose (copper) — `SetSendMailMoney`'s last value.
     pub money: u32,
-    /// COD amount (copper) — `SetSendMailCOD`'s last value; `0` when not a COD send.
     pub cod: u32,
-    /// The attached bag item's `(live-API bag, 1-based slot)`; `None` = no attachment. The app
-    /// resolves it to the wire's `u64 itemGuid` at send time (the reference re-reads the bag slot
-    /// when the send fires, so the resolve is lazy).
+    /// The attached item's `(bag, 1-based slot)`; the app resolves its guid when the send fires,
+    /// as the reference re-reads the slot then.
     pub item: Option<(i64, u32)>,
 }
 
@@ -180,14 +118,12 @@ impl super::UiScript {
         self.model_mut().mail = state;
     }
 
-    /// Whether `CheckInbox` was called since the last drain (and clear the flag) — the app maps it to
-    /// a fresh `CMSG_GET_MAIL_LIST`.
+    /// Take the `CheckInbox` flag; the app answers it with `CMSG_GET_MAIL_LIST`.
     pub fn take_mail_check_inbox(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().mail_check_inbox)
     }
 
-    /// Drain the 1-based indices of mails **opened** (`GetInboxText` was called on them) since the
-    /// last drain — the app marks each read and fetches its body ask-once.
+    /// Drain the 1-based indices `GetInboxText` opened; the app marks each read, fetches its body.
     pub fn take_mail_opens(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().mail_opens)
     }
@@ -212,22 +148,18 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().mail_returns)
     }
 
-    /// Drain the 1-based `TakeInboxTextItem` row picks — the letter button's "permanent copy"
-    /// verb; the app maps each to `CMSG_MAIL_CREATE_TEXT_ITEM`.
+    /// Drain the 1-based `TakeInboxTextItem` row picks, each a `CMSG_MAIL_CREATE_TEXT_ITEM`.
     pub fn take_mail_take_texts(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().mail_take_texts)
     }
 
-    /// Whether `CloseMail` was called since the last drain (and clear the flag). vanilla's
-    /// client-side close sends no packet — the app clears its local mail session.
+    /// Take the `CloseMail` flag; 1.12 has no close opcode, so the app only ends its mail session.
     pub fn take_mail_close(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().mail_close)
     }
 
-    /// Drain the `SendMail` intent, if one was queued since the last drain — folds in the last
-    /// `SetSendMailMoney`/`SetSendMailCOD` amounts and the attached item's `(bag, slot)`. The
-    /// attachment is left in place (a failed send keeps it; [`Self::reset_compose_tab`] drops it
-    /// on success).
+    /// Drain the `SendMail` intent with the current money, COD and attachment. The attachment
+    /// stays until [`Self::reset_compose_tab`], so a failed send keeps it.
     pub fn take_mail_send(&mut self) -> Option<MailSendRequest> {
         let mut model = self.model_mut();
         let (target, subject, body) = model.mail_send.take()?;
@@ -243,21 +175,10 @@ impl super::UiScript {
         })
     }
 
-    /// **`0x4acdc0(1)` — the client's compose-tab reset**, whole. Zeroes the send tab's attachment
-    /// (`0xb6ef90/94`), money (`0xb6efa4`) and COD (`0xb6efa8`) globals and then **tail-fires its
-    /// three events**, in this order: `SEND_MAIL_MONEY_CHANGED`, `SEND_MAIL_COD_CHANGED`,
-    /// `MAIL_SEND_SUCCESS` (`@0x4ace14/1e/28`).
-    ///
-    /// **The fire belongs to the reset, and that is the whole point of this shape.** Both call
-    /// sites used to fire `MAIL_SEND_SUCCESS` themselves, and the send-result one fired it
-    /// *before* clearing — so the stock `SendMailFrame_Reset` ran while `GetSendMailItem()` still
-    /// answered with the item that had just been sent, and its own `SendMailFrame_Update()` tail
-    /// put the item's name straight back into the subject box and its texture back on
-    /// `SendMailPackageButton`. Nothing re-ran the update after the clear landed, so a sent letter
-    /// left its subject and its icon sitting in the form (director's report, decision 2145).
-    ///
-    /// `MAIL_SEND_SUCCESS` is **overloaded** — it means "the compose form is now clean", not "a
-    /// mail was sent" — opening a mailbox fires it too.
+    /// The reference's compose-tab reset (`0x4acdc0`): clear the attachment, money and COD, then
+    /// fire `SEND_MAIL_MONEY_CHANGED`, `SEND_MAIL_COD_CHANGED` and `MAIL_SEND_SUCCESS` in that
+    /// order. The events must follow the clear, as `SendMailFrame_Reset` re-reads
+    /// `GetSendMailItem`. `MAIL_SEND_SUCCESS` means the form is clean: opening a mailbox fires it.
     pub fn reset_compose_tab(&mut self) {
         {
             let mut model = self.model_mut();
@@ -265,19 +186,15 @@ impl super::UiScript {
             model.mail_send_money = 0;
             model.mail_send_cod = 0;
         }
-        // Fired here, immediately, rather than queued on `pending_events`: this is a host-side
-        // edge (the mail system driving the VM), not a Lua binding queueing work for the next
-        // tick, and its order against the caller's own `MAIL_SHOW`/`MAIL_FAILED` is the law.
-        // Spelled out one call each — the three are a fixed sequence at three addresses, and the
-        // chain-file event census (`ui_script::reference_ui`) reads producers as literals.
+        // Fired now, not queued: the order against the caller's `MAIL_SHOW`/`MAIL_FAILED` matters.
+        // One literal call each, as the event census (`ui_script::reference_ui`) reads them.
         self.fire_event("SEND_MAIL_MONEY_CHANGED", Vec::new()); // 0x4ace14
         self.fire_event("SEND_MAIL_COD_CHANGED", Vec::new()); // 0x4ace1e
         self.fire_event("MAIL_SEND_SUCCESS", Vec::new()); // 0x4ace28
     }
 
-    /// Drop the attachment alone — `SendMail`'s attached-item-gone abort (`ERR_ITEM_NOT_FOUND`, no
-    /// packet, `MAIL_SEND_INFO_UPDATE` at `0x4ae98d`): the bag slot no longer holds the item the
-    /// send tab shows. The money and COD amounts stay, as the reference leaves them.
+    /// `SendMail`'s abort when the attached item left its slot (`ERR_ITEM_NOT_FOUND`, no packet,
+    /// `MAIL_SEND_INFO_UPDATE` at `0x4ae98d`): drop the attachment, keep the money and COD.
     pub fn drop_send_mail_item(&mut self) {
         let mut model = self.model_mut();
         if model.mail_send_item.take().is_some() {
@@ -287,28 +204,25 @@ impl super::UiScript {
         }
     }
 
-    /// Push the usable stationery list, in the picker's order (1970; see [`StationeryView`]).
+    /// Push the usable stationery list, in the picker's order.
     pub fn set_mail_stationeries(&mut self, list: Vec<StationeryView>) {
         self.model_mut().mail_stationeries = list;
     }
 
-    /// Clear the stationery selection — the client does it at `0x4ace07` on BOTH opening and
-    /// closing the mailbox, which is why the stock `SendMailFrame_Reset` re-selects row 1 on show.
+    /// Clear the stationery selection, as the reference does on mailbox open and close
+    /// (`0x4ace07`).
     pub fn clear_stationery(&mut self) {
         self.model_mut().mail_stationery = 0;
     }
 
-    /// Push `HasNewMail()`'s answer (decision 0544 P3) — login-scoped, independent of whether a
-    /// mailbox window is open. The app computes this off its `MSG_QUERY_NEXT_MAIL_TIME`/
-    /// `SMSG_RECEIVED_MAIL`-fed countdown and calls this on every value change, right before firing
-    /// `UPDATE_PENDING_MAIL` (the reference `MiniMapMailFrame`'s only listened event, Minimap.xml
-    /// l.278-289 — its `OnEvent` just re-reads `HasNewMail()` and shows/hides).
+    /// Push `HasNewMail()`'s answer, independent of any open mailbox. The app sets it before each
+    /// `UPDATE_PENDING_MAIL`, on which the minimap icon re-reads it (`Minimap.xml:278-289`).
     pub fn set_has_new_mail(&mut self, has: bool) {
         self.model_mut().has_new_mail = has;
     }
 }
 
-/// Fetch a cloned inbox row for a 1-based index, or `None` (out of range / no mailbox open).
+/// A clone of the inbox row at a 1-based index.
 fn row_at(model: &Model, index: usize) -> Option<MailInboxRow> {
     model
         .mail
@@ -321,7 +235,6 @@ fn row_at(model: &Model, index: usize) -> Option<MailInboxRow> {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetInboxNumItems() → the number of inbox rows (0 when no mailbox is open).
     g.set(
         "GetInboxNumItems",
         lua.create_function(|lua, ()| {
@@ -330,8 +243,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInboxHeaderInfo(index) → the 13-tuple (see the module doc). An out-of-range index answers
-    // nil (the reference callers only read within GetInboxNumItems, but the null shape is faithful).
+    // GetInboxHeaderInfo(index): the 13 values `MailFrame.lua:105` reads; nil out of range.
     g.set(
         "GetInboxHeaderInfo",
         lua.create_function(|lua, index: usize| {
@@ -348,7 +260,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     None => Value::Nil,
                 })
             };
-            // packageIcon shows only for a non-GM mail that carries an item (MailFrame.lua l.108).
+            // packageIcon only for a non-GM mail with an item (`MailFrame.lua:108`).
             let package_icon = if r.item_id != 0 && !r.is_gm {
                 opt_str(&r.package_icon)?
             } else {
@@ -362,7 +274,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 Value::Integer(i64::from(r.money)),
                 Value::Integer(i64::from(r.cod)),
                 Value::Number(f64::from(r.days_left)),
-                // hasItem: the stack count, or nil when there's no item.
                 if r.item_count > 0 {
                     Value::Integer(i64::from(r.item_count))
                 } else {
@@ -377,12 +288,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInboxText(index) → body, stationeryTexture, isTakeable, isInvoice (MailFrame.lua l.292).
-    // Opening a mail is the ask-once trigger: queue the open intent (the app marks it read + fetches
-    // the body when has_body). A cache miss returns "" until the body lands and a fresh snapshot
-    // arrives. isTakeable = the mail carries a fetchable body (`item_text_id != 0`) — with
-    // `not textCreated` it gates the letter button (the "permanent copy" verb, ref l.366; vmangos
-    // `HandleMailCreateTextItem` requires the same pair: an `itemTextId` and no COPIED bit).
+    // GetInboxText(index): body, stationeryTexture, isTakeable, isInvoice (`MailFrame.lua:292`);
+    // reading a mail queues its open. isTakeable with `not textCreated` gates the copy button
+    // (`MailFrame.lua:366`), the pair vmangos requires (`MailHandler.cpp:863`).
     g.set(
         "GetInboxText",
         lua.create_function(|lua, index: usize| {
@@ -390,7 +298,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 let mut model = lua.app_data_mut::<Model>().expect("model app_data");
                 let row = row_at(&model, index);
                 if row.is_some() {
-                    // Ask-once dedup: don't re-queue an already-pending open this drain window.
+                    // Queued once per drain.
                     let i = index as u32;
                     if !model.mail_opens.contains(&i) {
                         model.mail_opens.push(i);
@@ -402,13 +310,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 return Ok(MultiValue::from_vec(vec![Value::Nil]));
             };
             Ok(MultiValue::from_vec(vec![
-                // **An invoice's body is `nil`, and that is an explicit carve-out in the reference,
-                // not an accident** (`0x4af1cf cmp [esi+0x4],2` / `je` → `lua_pushnil`, decision
-                // 1527). The auction house's raw `<guid>:<n>:<n>:…` bookkeeping really does sit in
-                // the shared text cache — `GetInboxInvoiceInfo` `sscanf`s exactly that string — but
-                // this binding refuses to hand it back. Two bindings, one cache, opposite purposes.
-                // It is what lets MailFrame lay the invoice pane over the letter page without the
-                // bookkeeping showing through above it.
+                // An invoice's body is nil (`0x4af1cf`): its text is the auction house's
+                // bookkeeping, which only `GetInboxInvoiceInfo` parses.
                 if r.is_invoice {
                     Value::Nil
                 } else {
@@ -421,13 +324,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInboxInvoiceInfo(index) → invoiceType, itemName, playerName, bid, buyout, deposit,
-    // consignment (MailFrame.lua l.302). **SEVEN values, always** — the reference's own `mov eax,7`
-    // (`0x4af5a1`), with the miss tail `nil, nil, nil, 0, 0, 0, 0` (`0x4af559`): three nils then
-    // four zeros. MailFrame.lua guards on the third
-    // (`if playerName then`), so the shape of the miss is what keeps the invoice pane hidden —
-    // returning one bare nil instead would leave the four numeric destructures nil and the pane's
-    // arithmetic would run on them.
+    // GetInboxInvoiceInfo(index) (`MailFrame.lua:302`): always seven values (`0x4af5a1`), a miss
+    // being three nils and four zeros (`0x4af559`).
     g.set(
         "GetInboxInvoiceInfo",
         lua.create_function(|lua, index: usize| {
@@ -461,10 +359,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInboxItem(index) → name, texture, count, quality, canUse (MailFrame.lua l.379). name/quality
-    // are nil while the item-template answer is in flight; a mail with no item answers all-nil name.
-    // canUse is the shared item-usable gate over the enclosed item's template (merchant's isUsable
-    // path) — usable while the template is still in flight (the null-record skip).
+    // GetInboxItem(index): name, texture, count, quality, canUse (`MailFrame.lua:379`); canUse is
+    // the shared item-usable gate, true while the template is in flight.
     g.set(
         "GetInboxItem",
         lua.create_function(|lua, index: usize| {
@@ -476,11 +372,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     .is_none_or(|r| super::item_stats::item_usable_by_id(&model, r.item_id));
                 (row, usable)
             };
-            // **Five values on every path**, and the empty leg is `(nil, nil, 0, 0, nil)` —
-            // `GetInboxItem 0x4af5d0`, the sibling of the `GetSendMailItem` block above (decision
-            // 2129). This answered ONE value, which a caller
-            // destructuring five reads as four nils — and the reference's own row
-            // (`(nil,nil,number,number,nil) | …`) has no one-value alternative at all.
+            // Five values on every path; with no item, `nil, nil, 0, 0, nil` (`0x4af5d0`).
             let Some(r) = row.filter(|r| r.item_id != 0) else {
                 return Ok(MultiValue::from_vec(vec![
                     Value::Nil,
@@ -498,7 +390,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 Some(t) => Value::String(lua.create_string(t)?),
                 None => Value::Nil,
             };
-            // A number on every path, like the send tab's.
+            // A number on every path, as in `GetSendMailItem`.
             let quality = Value::Integer(i64::from(r.item_quality.unwrap_or(0)));
             Ok(MultiValue::from_vec(vec![
                 name,
@@ -510,7 +402,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // InboxItemCanDelete(index) → 1/nil (MailFrame.lua l.417/450): the delete-vs-return law.
     g.set(
         "InboxItemCanDelete",
         lua.create_function(|lua, index: usize| {
@@ -519,8 +410,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // HasNewMail() → 1/nil off the app's login-scoped countdown flag (decision 0544 P3; see
-    // `UiScript::set_has_new_mail`'s doc for the wire behind it).
     g.set(
         "HasNewMail",
         lua.create_function(|lua, ()| {
@@ -529,7 +418,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CheckInbox() — flag the inbox-refresh intent (the app sends CMSG_GET_MAIL_LIST).
     g.set(
         "CheckInbox",
         lua.create_function(|lua, ()| {
@@ -540,7 +428,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The five 1-based row-pick intents (take item / take money / delete / return / copy letter).
     for (name, field) in [
         ("TakeInboxItem", 0u8),
         ("TakeInboxMoney", 1),
@@ -564,7 +451,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // CloseMail() — client-side close (no packet): flag it so the app clears its mail session.
     g.set(
         "CloseMail",
         lua.create_function(|lua, ()| {
@@ -575,23 +461,19 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SendMail(target, subject, body) — queue the send; the app folds in money/COD + the attachment.
     g.set(
         "SendMail",
         lua.create_function(|lua, (target, subject, body): (String, String, String)| {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // `SendMail 0x4ae800` (decision 1965): money and COD are exclusive AT SEND TIME — both
-            // set is a silent abort, no packet — and a COD with no attached item aborts the same
-            // way. 0 returns on every path, so Lua cannot tell.
+            // `SendMail` (`0x4ae800`) aborts silently, no packet and no return value, on money
+            // with COD or on COD with no attached item.
             if model.mail_send_money != 0 && model.mail_send_cod != 0 {
                 return Ok(());
             }
             if model.mail_send_cod != 0 && model.mail_send_item.is_none() {
                 return Ok(());
             }
-            // No stationery selected — `0x4ae8dd je`: the send silently aborts, no packet, 0
-            // returns (1970). The selection is cleared on mailbox open and close, and the stock
-            // `SendMailFrame_Reset` re-selects row 1, so a send from the stock tab always has one.
+            // The same silent abort with no stationery selected (`0x4ae8dd`).
             if model.mail_stationery == 0 {
                 return Ok(());
             }
@@ -600,11 +482,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetSendMailMoney(copper) → 1 (the SEND_MONEY popup's OnAccept gates SendMail on the truthy
-    // return, StaticPopup.lua l.252). Stores the enclose-money amount the app reads at send time.
-    // SetSendMailMoney(copper) — `0x4ae0f0` → `0x4adbe0` (decision 1965): a non-number RAISES;
-    // more than the purse (unsigned) shows ERR_NOT_ENOUGH_MONEY and answers nil; else the store,
-    // SEND_MAIL_MONEY_CHANGED, and the number 1 — StaticPopup.lua l.257 branches on that value.
+    // SetSendMailMoney(copper) (`0x4ae0f0`): a non-number raises; more than the purse shows
+    // ERR_NOT_ENOUGH_MONEY and answers nil; else it stores, fires SEND_MAIL_MONEY_CHANGED and
+    // answers 1, which `StaticPopup.lua:257` branches on.
     g.set(
         "SetSendMailMoney",
         lua.create_function(|lua, copper: Value| {
@@ -626,9 +506,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSendMailMoney() / GetSendMailCOD() → the two amounts as stored (`0x4ae150` / `0x4ae1c0`,
-    // one number each — `reference/1.12-shapes.tsv`): what the stock money kit's SEND_MAIL and
-    // SEND_MAIL_COD types display (1962).
+    // GetSendMailMoney() and GetSendMailCOD() (`0x4ae150`, `0x4ae1c0`): the stored amounts.
     g.set(
         "GetSendMailMoney",
         lua.create_function(|lua, ()| {
@@ -650,10 +528,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetSendMailCOD(copper) — store the COD amount the app reads at send time (MailFrame.lua l.497).
-    // SetSendMailCOD(copper) — `0x4ae180` → `0x4adc70` (decision 1965): a non-number RAISES;
-    // without an attached item nothing happens at all — no store, no event, no message — and
-    // there is no affordability or sign check; 0 returns on every path.
+    // SetSendMailCOD(copper) (`0x4ae180`): a non-number raises; with no attached item nothing
+    // happens; there is no purse or sign check and no return value.
     g.set(
         "SetSendMailCOD",
         lua.create_function(|lua, copper: Value| {
@@ -674,27 +550,14 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSendMailItem() → name, texture, stackCount, quality off the attached cursor item
-    // (MailFrame.lua l.511).
-    //
-    // **The empty leg is `(nil, nil, 0, 0)`** — four values, and slots 3 and 4 are NUMBERS. Read at
-    // `0x4ae590`: `0x4ae6d3`/`0x4ae6da` push nil, then two `push 0; push 0; lua_pushnumber` pairs
-    // at `0x4ae6df`/`0x4ae6ea`, `eax = 4` (decision 2129). All three of the reference's failure
-    // guards share that one block, so "nothing attached" and "the item template has not loaded
-    // yet" are indistinguishable to a script.
-    //
-    // The `1` this used to push in slot 3 was borrowed from the wrong binding: it is
-    // `GetAuctionSellItemInfo 0x4ce590`'s empty leg (`1.0`/`-1.0`), not this one's.
-    //
-    // **Still not faithful, and stated rather than implied:** on the LOADED leg the reference reads
-    // quality from `[rec+0x1c]` gated on `[rec+0x2c] != 0` = InventoryType, so a **non-equippable**
-    // item answers quality `-1` (`0x4ae6bf`). We do not carry an inventory type here, so an item
-    // whose quality we have not cached answers 0 rather than -1.
+    // GetSendMailItem(): name, texture, stackCount, quality (`MailFrame.lua:511`). The reference
+    // answers `nil, nil, 0, 0` both with nothing attached and before the template loads
+    // (`0x4ae590`). It answers quality -1 for an item whose InventoryType is 0 (`0x4ae6bf`); this
+    // answers the cached quality, or 0.
     g.set(
         "GetSendMailItem",
         lua.create_function(|lua, ()| {
-            // The stack count is read while the model is borrowed: a whole-stack pickup records
-            // no count of its own, so the true size comes back from the source slot.
+            // A whole-stack pickup records no count, so the size comes from the source slot.
             let item = {
                 let model = lua.app_data_ref::<Model>().expect("model app_data");
                 model.mail_send_item.clone().map(|it| {
@@ -720,7 +583,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 Some(t) => Value::String(lua.create_string(t)?),
                 None => Value::Nil,
             };
-            // A number on every path — the reference's row has no nil alternative in this slot.
+            // A number on every path, as in the reference.
             let quality = Value::Integer(i64::from(it.quality.unwrap_or(0)));
             Ok(MultiValue::from_vec(vec![
                 name,
@@ -731,15 +594,14 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSendMailPrice() → the flat 30c postage (vmangos's fee; the reference reads a C constant).
+    // GetSendMailPrice(): 30 copper, vmangos's fee (`MailHandler.cpp:243`). The reference's is 30
+    // (`0x4ae756`) plus an uncarried stationery's price, the package's and the enclosed money
+    // (`0x4ae7a0`-`0x4ae7d2`); those are not added here.
     g.set(
         "GetSendMailPrice",
         lua.create_function(|_, ()| Ok(Value::Integer(30)))?,
     )?;
 
-    // ClickSendMailItemButton() — attach the cursor's held bag item as the send attachment, or, with
-    // an empty cursor and a filled slot, pick the attachment back onto the cursor (MailFrame.lua
-    // l.719, mirroring pickup_container_item's swap). A spell/action cursor is refused (no-op).
     g.set(
         "ClickSendMailItemButton",
         lua.create_function(|lua, ()| {
@@ -749,12 +611,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ── The stationery family (1970) ──
-    // The list is the app's (`Stationery.dbc` × the player's bags × the template cache); the
-    // client rebuilds it from `GetNumStationeries` (`0x4ae202` → `0x4ad970`), on world enter and
-    // on the last item-query answer — the app's per-frame recompute covers all three moments.
+    // ── The stationery family ──
+    // The reference rebuilds the list (`0x4ad970`) in `GetNumStationeries` (`0x4ae1f0`), on world
+    // entry and on the last item-query answer; the app recomputes it every frame.
 
-    // `GetNumStationeries()` — 0 args, 1 number: the usable count.
     g.set(
         "GetNumStationeries",
         lua.create_function(|lua, ()| {
@@ -763,9 +623,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetStationeryInfo(index)` — shape A (`lua_isnumber`, truncate), raising its Usage on a
-    // non-number; 1-based, unsigned bound; exactly 3 returns on every exit: name, the FULL icon
-    // path, BuyPrice in copper — cost nil when the player carries the item; 3 nils out of range.
+    // `GetStationeryInfo(index)` (`0x4ae230`): a non-number raises its Usage; three values
+    // always, three nils out of range.
     g.set(
         "GetStationeryInfo",
         lua.create_function(|lua, index: Value| {
@@ -795,8 +654,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `SelectStationery(index)` — shape A, raising its Usage on a non-number; 0 returns. In range
-    // it stores the row's DBC id; **out of range is not an error — it writes 0**, a deselect.
+    // `SelectStationery(index)` (`0x4ae380`): out of range is not an error, it stores 0.
     g.set(
         "SelectStationery",
         lua.create_function(|lua, index: Value| {
@@ -815,8 +673,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetSelectedStationeryTexture()` — 0 args, 1 return: the BARE `Stationery.dbc` texture name
-    // of the selection; nil for no selection (id 0) or an id the table does not carry.
+    // `GetSelectedStationeryTexture()` (`0x4ae3f0`): nil for no selection or an unknown id.
     g.set(
         "GetSelectedStationeryTexture",
         lua.create_function(|lua, ()| {
@@ -835,27 +692,22 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// The attach/detach swap of `ClickSendMailItemButton` — the mail send slot as a cursor drop
-/// target (decision 0216's payload rails). Every `model.cursor` mutation is followed by
-/// [`cursor::queue_cursor_update`]/[`cursor::queue_lock_changed`] so `CURSOR_UPDATE`/
-/// `ITEM_LOCK_CHANGED` fire, exactly like a bag slot.
+/// `ClickSendMailItemButton`: the send slot as a cursor drop target, firing `CURSOR_UPDATE` and
+/// `ITEM_LOCK_CHANGED` like a bag slot.
 fn click_send_mail_item(model: &mut Model) {
     match model.cursor.take() {
-        // Cursor holds a bag item → attach it (the item leaves nothing in the bag until send).
+        // A held bag item attaches; it stays in its bag slot until the send.
         Some(CursorPayload::Item(item)) => {
             let (bag, slot) = (item.bag, item.slot);
-            // If a different item was already attached, it returns to nowhere client-side (the
-            // reference simply overwrites); its slot was never locked, so nothing to unlock.
+            // An earlier attachment is overwritten, as in the reference; its slot has no lock.
             model.mail_send_item = Some(item);
             cursor::queue_cursor_update(model);
             cursor::queue_lock_changed(model, bag, slot);
-            // The attachment changed — `MAIL_SEND_INFO_UPDATE` at `0x4ae0de` (0 args, 1970); the
-            // stock tab re-reads `GetSendMailItem` and the postage on it.
+            // `MAIL_SEND_INFO_UPDATE` (`0x4ae0de`): the stock tab re-reads the item and postage.
             model
                 .pending_events
                 .push(("MAIL_SEND_INFO_UPDATE".to_string(), Vec::new()));
         }
-        // Empty cursor, a filled slot → pick the attachment back onto the cursor (detach).
         None => {
             if let Some(item) = model.mail_send_item.take() {
                 let (bag, slot) = (item.bag, item.slot);
@@ -867,7 +719,6 @@ fn click_send_mail_item(model: &mut Model) {
                     .push(("MAIL_SEND_INFO_UPDATE".to_string(), Vec::new()));
             }
         }
-        // A spell/action payload is refused — put it back untouched (container.rs's refuse arm).
         Some(other) => {
             model.cursor = Some(other);
         }
@@ -879,8 +730,7 @@ mod tests {
     use super::*;
     use crate::script::UiScript;
 
-    /// A send needs a stationery selected (1970): seat the default and select it, the way the
-    /// stock `SendMailFrame_Reset` does on MAIL_SHOW.
+    /// A send needs a stationery: select the default, as the stock `SendMailFrame_Reset` does.
     fn select_default_stationery(s: &mut UiScript) {
         s.set_mail_stationeries(vec![super::StationeryView {
             id: 41,
@@ -917,7 +767,7 @@ mod tests {
             item_texture: (item_id != 0)
                 .then(|| "Interface\\Icons\\INV_Fabric_Linen_01".to_string()),
             item_quality: (item_id != 0).then_some(1),
-            can_delete: false, // from a player, not returned → returnable (not deletable)
+            can_delete: false, // a player's unreturned mail is returned, not deleted
             item_random_property_id: 0,
         }
     }
@@ -928,10 +778,6 @@ mod tests {
         }
     }
 
-    /// `GetInboxInvoiceInfo` answers **seven values, always** — the reference's own `mov eax,7`.
-    /// The miss tail is the part that matters and the part that is easy to get wrong: three nils
-    /// then four ZEROS, not one bare nil. MailFrame.lua destructures all seven unguarded and only
-    /// then tests the third, so a short return leaves its arithmetic running on nils.
     #[test]
     fn the_invoice_answers_seven_values_or_a_three_nil_four_zero_miss() {
         let mut s = UiScript::new().unwrap();
@@ -972,7 +818,7 @@ mod tests {
             "a seller invoice, in the reference's own order"
         );
 
-        // Row 2 carries no invoice — and neither does an index off the end.
+        // Row 2 has no invoice, and index 99 is off the end.
         for idx in [2, 99] {
             assert_eq!(
                 s.arity(&format!("GetInboxInvoiceInfo({idx})")).unwrap(),
@@ -992,11 +838,6 @@ mod tests {
         }
     }
 
-    /// `GetInboxText` returns **four** values always, and for an INVOICE the first is `nil`.
-    /// That is the reference's own carve-out (`0x4af1cf cmp [esi+0x4],2` → `lua_pushnil`), and it
-    /// is what lets MailFrame lay the invoice pane over the letter page: the auction house's raw
-    /// bookkeeping is in the text cache — `GetInboxInvoiceInfo` parses exactly that string — and
-    /// this binding refuses to hand it back (decision 1527).
     #[test]
     fn an_invoice_has_no_letter_body() {
         let mut s = UiScript::new().unwrap();
@@ -1016,7 +857,6 @@ mod tests {
             "nil",
             "the bookkeeping is never handed back as a letter body"
         );
-        // Row 2 is an ordinary letter and keeps its text.
         assert_eq!(
             s.eval::<String>("return tostring((GetInboxText(2)))")
                 .unwrap(),
@@ -1024,8 +864,6 @@ mod tests {
         );
     }
 
-    /// A BUYER invoice says so with the bare ASCII token the Lua compares against — not a
-    /// GlobalString, not localized.
     #[test]
     fn a_buyer_invoice_is_the_literal_token_buyer() {
         let mut s = UiScript::new().unwrap();
@@ -1058,8 +896,6 @@ mod tests {
         s.set_mail(Some(state()));
         assert_eq!(s.eval::<i64>("return GetInboxNumItems()").unwrap(), 2);
 
-        // Row 1 (has item): the leading strings + money/COD/days, then the flags — asserted in two
-        // smaller evals so the harness never destructures the whole 13-tuple in one Rust type.
         let (pkg, sta, sender, subject, money, cod, days): (
             String,
             String,
@@ -1079,7 +915,6 @@ mod tests {
         );
         assert_eq!((money, cod), (5000, 0));
         assert!((days - 29.5).abs() < 1e-3);
-        // hasItem = count 3, wasRead nil, wasReturned nil, textCreated nil, canReply 1, isGM nil.
         assert!(s
             .eval::<bool>(
                 "local a,b,c,d,e,f,g, has, read, ret, tc, reply, gm = GetInboxHeaderInfo(1)\n\
@@ -1087,7 +922,6 @@ mod tests {
             )
             .unwrap());
 
-        // Row 2 (no item): hasItem nil, packageIcon nil.
         assert!(s
             .eval::<bool>(
                 "local pkg, sta, s, subj, m, c, d, has = GetInboxHeaderInfo(2)\n\
@@ -1104,9 +938,9 @@ mod tests {
             s.eval("return GetInboxText(1)").unwrap();
         assert_eq!(body, "Lok'tar.");
         assert_eq!(tex, "STATIONERYTEST");
-        assert_eq!(takeable, Value::Integer(1)); // has a fetchable body
+        assert_eq!(takeable, Value::Integer(1)); // has a body to fetch
         assert!(matches!(invoice, Value::Nil));
-        // Opening queued the row for the mark-read/body ask; deduped within the drain window.
+        // The open is queued once per drain.
         s.run("GetInboxText(1)").unwrap();
         assert_eq!(s.take_mail_opens(), vec![1]);
         assert!(s.take_mail_opens().is_empty(), "drained");
@@ -1122,9 +956,8 @@ mod tests {
             (name.as_str(), count, quality, canuse),
             ("Linen Cloth", 3, 1, 1)
         );
-        // Row 2 has no item → nil.
         assert!(s.eval::<bool>("return GetInboxItem(2) == nil").unwrap());
-        // Row 1 is from a player, not returned → returnable, NOT deletable.
+        // A player's unreturned mail is returnable, not deletable.
         assert!(s
             .eval::<bool>("return InboxItemCanDelete(1) == nil")
             .unwrap());
@@ -1156,7 +989,6 @@ mod tests {
         let mut s = UiScript::new().unwrap();
         s.set_money(5_000);
         assert!(s.take_mail_send().is_none());
-        // The purse gate (1965): more than the purse answers nil and names the refusal.
         assert!(s
             .eval::<bool>("return SetSendMailMoney(9999) == nil")
             .unwrap());
@@ -1164,7 +996,7 @@ mod tests {
         assert!(s
             .eval::<bool>("return SetSendMailMoney(1234) == 1")
             .unwrap());
-        // A COD with no attached item is completely silent: no store, no event (1965).
+        // COD with no attached item: no store, no event.
         s.run("SetSendMailCOD(50)").unwrap();
         assert_eq!(s.eval::<i64>("return GetSendMailCOD()").unwrap(), 0);
         select_default_stationery(&mut s);
@@ -1188,12 +1020,10 @@ mod tests {
     fn attach_from_cursor_and_get_send_item() {
         use crate::script::cursor::{CursorItem, CursorPayload};
         let mut s = UiScript::new().unwrap();
-        // Nothing attached → nil name, stack 1.
         assert!(s
             .eval::<bool>("local n = GetSendMailItem()\nreturn n == nil")
             .unwrap());
 
-        // Put a bag item on the cursor, then click the send slot: it attaches.
         s.model_mut().cursor = Some(CursorPayload::Item(CursorItem {
             bar_placeable: true,
             bag: 0,
@@ -1206,18 +1036,16 @@ mod tests {
             equip_slots: Vec::new(),
         }));
         s.run("ClickSendMailItemButton()").unwrap();
-        // Cursor is now empty; the send item reads the attachment.
         assert!(s.eval::<bool>("return not CursorHasItem()").unwrap());
         let (name, _tex, count, quality): (String, String, i64, i64) =
             s.eval("return GetSendMailItem()").unwrap();
         assert_eq!((name.as_str(), count, quality), ("Linen Cloth", 7, 1));
 
-        // A send folds in the attachment's (bag, slot).
         select_default_stationery(&mut s);
         s.run("SendMail('Alt', 'stuff', '')").unwrap();
         assert_eq!(s.take_mail_send().unwrap().item, Some((0, 5)));
 
-        // Clicking again with an empty cursor detaches (back onto the cursor).
+        // Clicking with an empty cursor detaches.
         s.run("ClickSendMailItemButton()").unwrap();
         assert!(s.eval::<bool>("return CursorHasItem()").unwrap());
         assert!(s
@@ -1295,11 +1123,6 @@ mod stationery_tests {
         s
     }
 
-    /// The four verbs, shape by shape (`GetNumStationeries 0x4ae1f0`, `GetStationeryInfo 0x4ae230`,
-    /// `SelectStationery 0x4ae380`, `GetSelectedStationeryTexture 0x4ae3f0`): the count; the info
-    /// triple with a nil cost for a carried paper and three nils past the end; a numeric string
-    /// passes the number gate and a non-number raises the Usage; the selection stores the DBC id,
-    /// out of range deselects, and the texture is the bare basename or nil.
     #[test]
     fn the_stationery_family_answers_like_the_client() {
         let s = seated();
@@ -1350,8 +1173,6 @@ mod stationery_tests {
         );
     }
 
-    /// A send with no stationery selected aborts silently — no request, no error; with one
-    /// selected the request carries the DBC id. Opening/closing the mailbox clears it.
     #[test]
     fn a_send_needs_a_stationery_and_carries_its_id() {
         let mut s = seated();
diff --git a/crates/benilla-ui/src/script/measure.rs b/crates/benilla-ui/src/script/measure.rs
index 91a9ae04..1662a9a0 100644
--- a/crates/benilla-ui/src/script/measure.rs
+++ b/crates/benilla-ui/src/script/measure.rs
@@ -1,81 +1,35 @@
-//! **The synchronous text measure** — the host's font engine, installed *into* the VM so a
-//! `GetStringWidth` answers during the Lua call that asked, not a frame later.
-//!
-//! ## Why this exists
-//!
-//! The real client's `GetStringWidth 0x79e510` calls straight through to its font engine
-//! (`0x772890`) and returns. Ours could not: measuring needs the baked glyph atlas, the atlas
-//! lives in the app, and the app only meets the VM at the frame boundary — so the metric was
-//! served from the [`MeasureRequest`](super::MeasureRequest) round-trip, which lands at **extract,
-//! one frame after the tick that set the text**. Every same-tick `SetText` → `GetStringWidth` pair
-//! read **0**.
-//!
-//! That is not a rounding difference, it is the difference between a laid-out UI and a broken one,
-//! and it is the shape the corpus actually writes:
-//!
-//! ```lua
-//! button:SetText(player)                      -- Bagnon_Forever/database/ui.lua:58
-//! if button:GetTextWidth() + 40 > width then   -- …:59, same tick
-//! ```
-//!
-//! With the answer 0, that dropdown sized itself to 40px and seven character names drew outside
-//! their own frame. The reference's own `SmallMoneyFrame` does the same thing (`MoneyFrame.lua`
-//! l.202), which is why `UiScript::set_digit_advances`
-//! existed: a digits-only stand-in for exactly this, built because the general answer was missing.
-//! This is the general answer, and it retires that special case.
-//!
-//! ## The seam
-//!
-//! [`TextMeasure`] is one method over the request type the round-trip already speaks, so the host
-//! answers a same-tick measure and a batch measure with the same code — there is no second
-//! measuring path to drift. The host owns the engine; the engine owns the *when*.
-//!
-//! **Absent by default, and that is a supported state.** A VM with no measurer installed (every
-//! engine test, every headless run without a font atlas) behaves exactly as it did: metrics stay
-//! 0 until the round-trip fills them. Nothing here is load-bearing for correctness of the
-//! round-trip; it only removes the latency.
+//! The synchronous text measure: the host's font engine installed into the VM, so
+//! `GetStringWidth` answers inside the Lua call that asked, as the reference's does (`0x79e510`
+//! calls its font engine, `0x772890`). UI code measures in the tick it sets text
+//! (`MoneyFrame.lua:202`). With no measurer installed, metrics stay 0 until the
+//! [`MeasureRequest`](super::MeasureRequest) round-trip fills them a frame later.
 
 use mlua::Lua;
 
 use super::{MeasureRequest, MeasuredText, Model};
 use crate::widget::RegionHandle;
 
-/// The host's font engine, as the VM sees it — installed with
-/// [`UiScript::set_text_measurer`](super::UiScript::set_text_measurer).
-///
-/// One method, taking the same [`MeasureRequest`] the batch round-trip carries: the host must
-/// answer a synchronous measure with the identical code that answers
-/// [`UiScript::fontstrings_needing_measure`](super::UiScript::fontstrings_needing_measure), or the
-/// two disagree and a string's width depends on *when* it was asked for.
+/// The host's font engine as the VM sees it. It must answer with the same code as the batch
+/// round-trip, or a string's width depends on when it was asked for.
 pub trait TextMeasure {
-    /// `(laid_out_w, laid_out_h, natural_w)` for `req`, in the region's own frame-local units.
-    ///
-    /// `laid_out_*` is the text wrapped inside `req.wrap_width` when it has one; `natural_w` is
-    /// the width it would take **unwrapped**, which is the number `GetStringWidth` reports (see
-    /// [`MeasuredText::natural_w`]). For a request with no wrap width the two are one number.
-    ///
-    /// Must be **pure with respect to the VM** — it is called with the model mutably borrowed and
-    /// must not re-enter Lua.
+    /// `(laid_out_w, laid_out_h, natural_w)` for `req` in frame-local units; `natural_w`, the
+    /// unwrapped width, is what `GetStringWidth` reports. It runs with the model mutably borrowed,
+    /// so it must not re-enter Lua.
     fn measure(&mut self, req: &MeasureRequest) -> (f32, f32, f32);
 }
 
-/// Measure region `rh` **now** if its stored measure is stale and a measurer is installed.
-///
-/// The one entry point for the metric reads (`GetStringWidth`, `GetWidth`/`GetHeight` on a
-/// FontString): they already treat a key-mismatched measure as absent, so filling the cache here
-/// is invisible to them beyond the answer arriving. A no-op without a measurer, and a no-op when
-/// the stored measure is already current — which is what keeps a per-frame poll from re-measuring.
+/// Measure region `rh` now if a measurer is installed and its stored measure is stale; a current
+/// one is left alone, so a per-frame poll does not re-measure.
 pub(super) fn ensure_measured(lua: &Lua, rh: RegionHandle) {
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
     if model.measurer.is_none() {
         return;
     }
     let Some(req) = super::layout::measure_request_for(&mut model, rh) else {
-        return; // not a FontString, no text, or the stored measure is already this string's
+        return; // not a FontString, no text, or already current
     };
-    // Taken out for the call and put straight back: the measurer needs `&mut self` (a font shaper
-    // is stateful) while the model is already mutably borrowed. Safe because the trait forbids
-    // re-entering the VM, so nothing can observe the gap.
+    // Taken out and put back: the measurer needs `&mut self` while the model is borrowed, and it
+    // cannot re-enter the VM, so nothing sees the gap.
     let mut engine = model.measurer.take().expect("checked above");
     let (w, h, natural_w) = engine.measure(&req);
     model.measurer = Some(engine);
@@ -88,44 +42,31 @@ pub(super) fn ensure_measured(lua: &Lua, rh: RegionHandle) {
     let mut moved = false;
     if let Some(d) = model.region_data.get_mut(&rh) {
         moved = super::types::MeasuredText::layout_moved(d.measured, new);
-        // The KEY always lands — this IS the measure cache, and a stale key re-requests forever.
+        // The key always lands: a stale key re-requests forever.
         d.measured = Some(new);
     }
     if moved {
-        // Measured extents are the auto-size axes' inputs — the layout gate's read set, the
-        // same touch `set_measured_text` does. Guarded on a change the LAYOUT can see: a
-        // re-measure that returns the same box (a same-width countdown tick) must not open
-        // tier 1, or it costs a whole-roster hash to conclude nothing moved (decision 1385).
-        // A new extent moves no edge and no roster membership, so it names its node (1388).
+        // Only a box that moved touches the layout, as in `set_measured_text`: a same-width
+        // re-measure (a countdown tick) must not cost a whole-roster hash.
         model.touch_layout_region(rh);
     }
 }
 
 impl super::UiScript {
-    /// Install the host's font engine, so metric reads answer inside the tick that asked.
-    ///
-    /// Call again to replace it — which the host must do whenever its **raster environment**
-    /// changes (window resize, `uiScale`), for the same reason
-    /// `UiScript::forget_text_metrics` exists: glyph
-    /// advances step to whole *physical* pixels, so a measurer built under one seam does not
-    /// answer for another.
+    /// Install the host's font engine, so metric reads answer inside the tick that asked. Replace
+    /// it whenever the window size or `uiScale` changes: glyph advances snap to whole physical
+    /// pixels.
     pub fn set_text_measurer(&mut self, measurer: Box<dyn TextMeasure>) {
         self.model_mut().measurer = Some(measurer);
     }
 
-    /// Whether a [`TextMeasure`] is installed — the host's gate for skipping its own batch measure
-    /// pass, which would find nothing to do anyway.
+    /// Whether a [`TextMeasure`] is installed; the host then skips its batch measure pass.
     pub fn has_text_measurer(&self) -> bool {
         self.model_mut().measurer.is_some()
     }
 
-    /// Answer every pending FontString measure inline. Returns whether anything changed (i.e.
-    /// whether the layout needs another solve). No-op without a measurer.
-    ///
-    /// This is [`UiScript::resolve`](super::UiScript::resolve)'s own half of the round-trip: with
-    /// an engine installed the VM closes the loop itself, so a FontString's box is right in the
-    /// frame its text was set rather than the frame after — and the host's batch pass finds an
-    /// empty request list and does nothing.
+    /// Answer every pending FontString measure inline, so a box is right in the frame its text
+    /// was set; returns whether anything changed.
     pub(super) fn fill_measures(&mut self) -> bool {
         if !self.has_text_measurer() {
             return false;
diff --git a/crates/benilla-ui/src/script/merchant.rs b/crates/benilla-ui/src/script/merchant.rs
index 12a707d6..0768e037 100644
--- a/crates/benilla-ui/src/script/merchant.rs
+++ b/crates/benilla-ui/src/script/merchant.rs
@@ -1,29 +1,11 @@
-//! The merchant bindings (decision 0081 phase 4) — the Era-shaped vendor surface, the same two-way
-//! seam as [`super::container`]/[`super::gossip`]: the app pushes a **merchant snapshot**
-//! ([`UiScript::set_merchant`] — the vendor rows already resolved from the wire to name/icon/price
-//! by the app's item stores), and the Lua `BuyMerchantItem`/`CloseMerchant` calls queue outbound
-//! **intents** the app drains ([`UiScript::take_merchant_buys`] / [`UiScript::take_merchant_close`]).
-//! The engine holds no vendor knowledge — a row is "a name, an icon path, a price, a stack size,
-//! how many are left, and the tooltip's stat head" ([`ItemStatsHead`], read by
-//! `BenillaGetMerchantItemStats`).
+//! The merchant bindings: the app pushes the open vendor ([`UiScript::set_merchant`]), and the
+//! Lua verbs queue intents it drains. A row is 1-based; the app maps it to the item entry
+//! `CMSG_BUY_ITEM` needs.
 //!
-//! ## The 5875 API shape
-//!
-//! 1.12's `GetMerchantItemInfo(index)` returns a flat **6-value** tuple the FrameXML reads
-//! positionally — `name, texture, price, quantity, numAvailable, isUsable` (byte-verified,
-//! `0x4fb150`; the ref's own `MerchantFrame_UpdateMerchantInfo` destructures exactly these six.
-//! The `isPurchasable`/`extendedCost` extras an earlier draft carried are TBC-era, not 5875).
-//! `index` is **1-based**; an invalid index answers the binding's fixed tuple
-//! `(nil, nil, 0, 1, 0, 1)` — same shape as `GetBuybackItemInfo`'s (`0x4fb2be`). `numAvailable`
-//! is `-1` for unlimited stock (the wire's `0xFFFF_FFFF` through `fild`, mapped by the app).
-//! `isUsable` is `1`/`nil` (the client pushes a number or nil, never a boolean): the
-//! [`super::item_stats::item_usable`] gate over the row's template — a template still in flight
-//! reads usable, the getter's null-record skip (`0x4fb298`).
-//!
-//! Buying addresses the row by its **1-based list position** here (`BuyMerchantItem(index)`); the app
-//! maps that position to the item *entry* the wire's `CMSG_BUY_ITEM` needs (buy is by entry, not the
-//! vendor `muid` — decision 0081). vanilla's client-side `CloseMerchant()` sends no packet, so it
-//! just flags the app to clear its local state (the gossip pattern).
+//! `GetMerchantItemInfo(index)` answers `name, texture, price, quantity, numAvailable, isUsable`
+//! (`0x4fb150`), or `(nil, nil, 0, 1, 0, 1)` for an invalid index (`0x4fb2be`). Unlimited stock is
+//! `numAvailable` -1; `isUsable` is 1 or nil, the [`super::item_stats::item_usable`] gate, and a
+//! template still in flight reads usable (`0x4fb298`).
 
 use mlua::{Lua, MultiValue, Value};
 
@@ -31,149 +13,116 @@ use super::container::UiCursorMode;
 use super::cursor::CursorPayload;
 use super::Model;
 
-/// One vendor row, resolved by the app from the wire `VendorItem` (decision 0081). Plain data —
-/// 1-based order in the window is its position in [`MerchantState::items`].
+/// One vendor row, resolved by the app; its 1-based index is its place in [`MerchantState::items`].
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct MerchantItem {
-    /// The item name (`GetMerchantItemInfo`'s first return); `None` while the ask-once item-template
-    /// query is still in flight (the API reports `nil`, the XML shows a placeholder).
+    /// The item name; `None` while its template is in flight, answered as nil.
     pub name: Option<String>,
-    /// Icon texture path (`Interface\Icons\…`); `None` while the template answer is in flight.
+    /// Icon path; `None` while the template is in flight.
     pub texture: Option<String>,
-    /// Buy price in copper (already reputation-discounted server-side).
+    /// Buy price in copper, already reputation-discounted by the server.
     pub price: u32,
-    /// Stack size delivered per purchase (`item_template.buy_count`, the wire's `buy_count`).
+    /// Stack size per purchase (`item_template.buy_count`).
     pub quantity: u32,
-    /// Remaining stock, or `-1` for unlimited (the app maps the wire's `0xFFFF_FFFF`).
+    /// Remaining stock, -1 for unlimited (the wire's `0xFFFF_FFFF`).
     pub num_available: i32,
-    /// The item's template **entry** — what `CMSG_BUY_ITEM` addresses (the app maps the clicked
-    /// 1-based row to this; the Lua side never sees it).
+    /// The template entry `CMSG_BUY_ITEM` addresses; Lua never sees it.
     pub item_id: u32,
-    /// The stat head the hover tooltip renders, from the same ask-once template answer as `name`
-    /// (`None` while it's in flight — the tooltip shows nothing it can't know yet). Still plain
-    /// data: the engine renders whatever numbers the app resolved, it holds no item model.
+    /// The hover tooltip's stat head; `None` while the template is in flight.
     pub stats: Option<ItemStatsHead>,
-    /// The row's full escaped `|cff…|Hitem:…|h[Name]|h|r` link (`GetMerchantItemLink`, decision
-    /// 1059) — what the row click's ctrl/shift arms hand to `DressUpItemLink` /
-    /// `ChatFrameEditBox:Insert` (`MerchantFrame.lua:303`/`:306`). `None` while the template answer
-    /// is in flight (the link embeds the name), and `None` on a **buyback** row: 1.12 has no
-    /// `GetBuybackItemLink` — the reference's buyback arm is an unmodified `BuybackItem(this:GetID())`
-    /// with no ctrl/shift branch at all (`MerchantFrame.lua:358-361`), so nothing would read it.
+    /// `GetMerchantItemLink`'s answer; `None` while in flight and on a buyback row, as 1.12 has no
+    /// `GetBuybackItemLink` and the buyback click takes no modifier (`MerchantFrame.lua:358-361`).
     pub link: Option<String>,
-    /// `Stackable` from the item's own template — what one slot can hold, `1` for an item that
-    /// does not stack. `None` while the ask-once template query is in flight, like `name`.
-    ///
-    /// This is `GetMerchantItemMaxStack`'s answer and it exists for one caller: the reference's
-    /// `MerchantItemButton_OnClick` asks it before a shift-click, and opens the stack-split
-    /// spinner only when it is above 1 (`MerchantFrame.lua:313-326`, and again at :340 for the
-    /// buy-in-bulk arm). The wire has carried it all along — `item_template.stackable`, parsed and
-    /// then dropped, because nothing on the Lua side could ask.
+    /// `GetMerchantItemMaxStack`: the template's `stackable`, 1 if it does not stack; `None` while
+    /// in flight.
     pub max_stack: Option<u32>,
 }
 
-/// An item template's tooltip stat head (the app's `ItemInfo` view, resolved per row): what the
-/// vendor hover tooltip needs beyond name/icon/price. The real client's `GameTooltip:SetMerchantItem`
-/// reads the same template fields C++-side; benilla feeds them to Lua through
-/// `BenillaGetMerchantItemStats(index)` (no 1.12 Lua API carries damage/armor — tooltip content was
-/// C++'s alone — so the feed is benilla-named, not Era-shaped).
+/// An item template's tooltip stat head, resolved per row by the app. The reference's
+/// `GameTooltip:SetMerchantItem` reads these in C++; no 1.12 Lua API carries them.
 #[derive(Clone, Copy, Debug, Default, PartialEq)]
 pub struct ItemStatsHead {
-    /// 0 poor … 6 artifact — colours the tooltip's name line.
+    /// 0 poor to 6 artifact; colours the tooltip's name line.
     pub quality: u32,
-    /// `InventoryType` — the tooltip's slot line ("Main Hand", "Chest", …); 0 = no slot line.
+    /// `InventoryType`, the tooltip's slot line ("Main Hand", "Chest"); 0 for none.
     pub inventory_type: u32,
-    /// Item class (2 weapon, 4 armor, 6 projectile) — with `subclass`, the slot line's right column.
+    /// Item class (2 weapon, 4 armor, 6 projectile); with `subclass`, the slot line's right side.
     pub class: u32,
     /// Item subclass within `class` (7 = sword, 1 = cloth, …).
     pub subclass: u32,
-    /// Damage block 0 per-hit minimum (0 for non-weapons).
+    /// Damage block 0's per-hit minimum, 0 for a non-weapon.
     pub dmg_min: f32,
-    /// Damage block 0 per-hit maximum.
+    /// Damage block 0's per-hit maximum.
     pub dmg_max: f32,
-    /// Damage block 0 school (0 physical, 1 Holy … 6 Arcane).
+    /// Damage block 0's school (0 physical, 1 Holy to 6 Arcane).
     pub dmg_type: u32,
-    /// Attack delay in milliseconds ("Speed" = delay / 1000).
+    /// Attack delay in milliseconds; the tooltip's "Speed" is delay / 1000.
     pub delay_ms: u32,
-    /// The armor line's value; 0 = no line.
+    /// The armor line's value; 0 for none.
     pub armor: u32,
-    /// A shield's block line; 0 = no line.
+    /// A shield's block line; 0 for none.
     pub block: u32,
-    /// `SellPrice` — what a vendor pays per unit (the bag tooltip's money row while a merchant is
-    /// open; 0 = the "No sell price" line).
+    /// What a vendor pays per unit; 0 shows the tooltip's "No sell price" line.
     pub sell_price: u32,
 }
 
-/// One open merchant window: the vendor's rows, the buyback slots, and the repair head. Pushed
-/// whole by the app; `None` means no vendor is open (the window is closed).
+/// One open merchant window, pushed whole by the app; `None` means no vendor is open.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct MerchantState {
     pub items: Vec<MerchantItem>,
-    /// The buyback slots, oldest-first (index 1 = the oldest; the LAST entry is the most recent
-    /// sale — the one the merchant page's single buyback slot shows, ref
-    /// `GetBuybackItemInfo(GetNumBuybackItems())`). Resolved by the app from the player's
-    /// VENDORBUYBACK descriptor fields + the item stores; `price` here is the buyback price
-    /// field, `quantity` the stored item's stack count.
+    /// Buyback slots, oldest first; the last, the latest sale, is the one the merchant page shows
+    /// (`MerchantFrame.lua:133`). From the player's VENDORBUYBACK fields: `price` is the buyback
+    /// price, `quantity` the stored stack.
     pub buyback: Vec<MerchantItem>,
-    /// Whether this vendor repairs (UNIT_NPC_FLAGS repair bit) — shows the repair buttons.
+    /// Whether this vendor repairs (the `UNIT_NPC_FLAGS` repair bit).
     pub can_repair: bool,
-    /// The repair-all cost in copper the app computed (0 = nothing to repair → the repair-all
-    /// button disables, ref MerchantFrame_OnShow).
+    /// The repair-all cost in copper; 0 disables the button (`MerchantFrame_OnShow`).
     pub repair_all_cost: u32,
 }
 
 impl super::UiScript {
-    /// Push (or clear, with `None`) the open merchant's stock snapshot.
+    /// Push (or clear, with `None`) the open vendor.
     pub fn set_merchant(&mut self, state: Option<MerchantState>) {
         self.model_mut().merchant = state;
     }
 
-    /// Drain the `(index, quantity)` buy intents queued by `BuyMerchantItem` since the last call.
-    /// `index` is the 1-based row position; the app maps it to the item entry the wire needs.
+    /// Drain the `(row, quantity)` buys `BuyMerchantItem` queued, the row 1-based.
     pub fn take_merchant_buys(&mut self) -> Vec<(u32, u32)> {
         std::mem::take(&mut self.model_mut().merchant_buys)
     }
 
-    /// Drain the `(bag, slot)` sells `PickupMerchantItem`'s cursor arm queued — the item the
-    /// cursor was holding when it was dropped on the vendor window. The app resolves the concrete
-    /// item guid from the pair and sends `CMSG_SELL_ITEM`, the same resolution the bag-click sell
-    /// route already does.
+    /// Drain the `(bag, slot)` of each cursor item dropped on the vendor; the app sells it.
     pub fn take_merchant_cursor_sells(&mut self) -> Vec<(i64, u32)> {
         std::mem::take(&mut self.model_mut().merchant_cursor_sells)
     }
 
-    /// Drain the `(bag, slot, item entry)` buys a held vendor row queued by being dropped into a
-    /// container slot — `CMSG_BUY_ITEM_IN_SLOT 0x1a3`.
+    /// Drain the `(bag, slot, entry)` of held rows dropped into bags (`CMSG_BUY_ITEM_IN_SLOT`).
     pub fn take_merchant_slot_buys(&mut self) -> Vec<(i64, u32, u32)> {
         std::mem::take(&mut self.model_mut().merchant_slot_buys)
     }
 
-    /// Whether `CloseMerchant` was called since the last drain (and clear the flag). vanilla's
-    /// client-side close sends no packet — the app just clears its local merchant state.
+    /// Whether `CloseMerchant` was called since the last drain; the close sends no packet.
     pub fn take_merchant_close(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().merchant_close)
     }
 
-    /// Drain the 1-based buyback-slot intents queued by `BuybackItem` since the last call. The app
-    /// maps each to the wire's absolute buyback inventory slot.
+    /// Drain the 1-based buyback slots `BuybackItem` queued.
     pub fn take_merchant_buybacks(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().merchant_buybacks)
     }
 
-    /// Whether `RepairAllItems` was called since the last drain (and clear the flag). The app
-    /// sends the repair-all wire message.
+    /// Whether `RepairAllItems` was called since the last drain.
     pub fn take_repair_all(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().repair_all)
     }
 
-    /// The client-side repair-mode latch (`ShowRepairCursor`/`HideRepairCursor`/`InRepairMode`):
-    /// while set, a bag/equipment click means "repair this item" — the app reads this to route
-    /// clicks and swap the hardware cursor.
+    /// The repair-mode latch: while set, a bag or equipment click repairs the item.
     pub fn repair_mode(&self) -> bool {
         self.model_ref().repair_mode
     }
 }
 
-/// `1`/`nil` — how the client pushes a usable flag (`pushnumber(1.0)` / `pushnil`).
+/// 1 or nil, as the client pushes a usable flag (`pushnumber(1.0)` / `pushnil`).
 fn usable_value(usable: bool) -> Value {
     if usable {
         Value::Integer(1)
@@ -182,8 +131,7 @@ fn usable_value(usable: bool) -> Value {
     }
 }
 
-/// The invalid-index tuple both getters answer (`0x4fb2be` / the buyback equivalent):
-/// `(nil, nil, 0, 1, 0, 1)` — still six values.
+/// Both getters' invalid-index six-tuple (`0x4fb2be`, and the buyback one).
 fn invalid_tuple() -> Vec<Value> {
     vec![
         Value::Nil,
@@ -199,7 +147,6 @@ fn invalid_tuple() -> Vec<Value> {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // → the number of rows the open vendor has (0 when no vendor is open).
     g.set(
         "GetMerchantNumItems",
         lua.create_function(|lua, ()| {
@@ -208,9 +155,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetMerchantItemInfo(index) → name, texture, price, quantity, numAvailable, isUsable — the
-    // byte-verified 5875 6-tuple (0x4fb150; see the module doc). `index` is 1-based; an invalid
-    // index answers the fixed tuple (nil, nil, 0, 1, 0, 1).
     g.set(
         "GetMerchantItemInfo",
         lua.create_function(|lua, index: usize| {
@@ -248,13 +192,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetMerchantItemLink(index) → the row's full escaped `|cff…|Hitem:…|h[Name]|h|r` link | nil.
-    // 1-based like GetMerchantItemInfo; nil out of range and nil while the row's template answer is
-    // in flight (the link embeds the name). The reference's row click reads it for both LEFT-button
-    // modifier arms — `DressUpItemLink(GetMerchantItemLink(this:GetID()))` (`MerchantFrame.lua:303`)
-    // and `ChatFrameEditBox:Insert(...)` (`:306`); ours routes the second through
-    // `BenillaChatEdit_InsertLink`, whose whole job is the nil this getter can answer. Merchant rows
-    // only: see [`MerchantItem::link`] for why a buyback row carries none. Decision 1059.
+    // GetMerchantItemLink(index): nil out of range and while in flight; both stock row-click
+    // arms accept a nil (`MerchantFrame.lua:303`, `:306`).
     g.set(
         "GetMerchantItemLink",
         lua.create_function(|lua, index: usize| {
@@ -273,18 +212,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetMerchantItemMaxStack(index) → the stack size ONE slot can hold for that row's item, or
-    // nil while its template answer is in flight / the index is out of range.
-    //
-    // Its only caller in 1.12 is the reference's own `MerchantItemButton_OnClick`, which asks it
-    // twice — once on the right-click arm (`MerchantFrame.lua:313`) and once on shift-click
-    // (`:340`) — and takes the plain single-buy path whenever the answer is `<= 1`, opening the
-    // stack-split spinner otherwise. So the number decides whether a vendor click asks "how many?"
-    // at all.
-    //
-    // The value was on the wire and parsed the whole time (`item_template.stackable`); nothing on
-    // the Lua side could reach it until now, which is why the reference's merchant window listed
-    // this as one of its two missing verbs.
+    // GetMerchantItemMaxStack(index): nil while in flight or out of range. A right shift-click, or
+    // a left one with the chat box closed, asks it and opens the stack-split spinner only above 1
+    // (`MerchantFrame.lua:313`, `:340`).
     g.set(
         "GetMerchantItemMaxStack",
         lua.create_function(|lua, index: usize| {
@@ -299,9 +229,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // BenillaGetMerchantItemStats(index) → quality, invType, class, subclass, dmgMin, dmgMax,
-    // dmgType, delayMs, armor, block — the tooltip stat head ([`ItemStatsHead`]), or nil while
-    // the row's template answer is in flight / the index is out of range. Benilla-named: 1.12's Lua
-    // API never carried these (item tooltip content was C++'s alone — `SetMerchantItem 0x534080`).
+    // dmgType, delayMs, armor, block, or nil. Not a 1.12 verb: the reference's tooltip reads the
+    // template in C++ (`SetMerchantItem 0x534080`).
     g.set(
         "BenillaGetMerchantItemStats",
         lua.create_function(|lua, index: usize| {
@@ -331,8 +260,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // BuyMerchantItem(index [, quantity]) — queue the 1-based row + stack count (default 1); the app
-    // maps the row to the item entry the wire addresses.
     g.set(
         "BuyMerchantItem",
         lua.create_function(|lua, (index, quantity): (u32, Option<u32>)| {
@@ -342,51 +269,32 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // PickupMerchantItem(index) — **two verbs behind one name** (`0x4fb760`). `0x4fb787` calls
-    // `GetCursorItem 0x494c60`, which answers for **mode 1 only**, and the result forks the whole
-    // function:
+    // PickupMerchantItem(index): two verbs in one (`0x4fb760`), forked at `0x4fb787` on
+    // `GetCursorItem 0x494c60`, which answers for mode 1 only; stock never checks
+    // `CursorHasItem()` first (`MerchantFrame.lua:329`). A bag item on the cursor is sold, index
+    // ignored and no merchant-open gate, which stock `MerchantFrame.xml:743`'s
+    // `PickupMerchantItem(0)` relies on; otherwise row `index - 1` is grabbed as cursor mode 5.
     //
-    //   * cursor holds a real bag item  → **SELL it** (`CMSG_SELL_ITEM 0x1a0`), then clear the
-    //     cursor. The index is IGNORED on this arm and there is no merchant-open gate on it. This
-    //     is what stock `MerchantFrame.xml:743`'s `<OnMouseUp>PickupMerchantItem(0)</OnMouseUp>`
-    //     is for: dropping a bag item anywhere on the vendor window sells it.
-    //   * otherwise                     → **grab** vendor row `index - 1` as cursor mode 5.
-    //
-    // Stock FrameXML never guards this call with `CursorHasItem()` — `MerchantFrame.lua:329`'s
-    // `else` is the else of the ctrl/shift modifier chain. An unmodified left-click calls it
-    // whatever the cursor holds, and the binding decides.
-    //
-    // **Every refusal is silent, and every refusal CLEARS THE CURSOR** — there is no `luaL_error`
-    // anywhere in the range, unlike its neighbour `BuyMerchantItem`. The ladder, in order:
-    // non-number argument (`0x4fb7cb`; a numeric *string* is accepted), `index < 1` (`0x4fb7e1`),
-    // `index > count` (`0x4fb7e9`), no merchant open (`0x4fb7f7`), a dead row (`0x4fb80b`), and a
-    // re-click on the row already held (`0x4fb818`, a toggle-off). Conversion is `_ftol` —
-    // **truncate toward zero**, then `-1`, bounded signed.
-    //
-    // It does **not** test stock and does **not** test the item cache: a sold-out row grabs fine
-    // and the buy still goes out, and the server refuses it. `numAvailable` is read exactly once
-    // image-wide, by `GetMerchantItemInfo`, for display.
+    // Every refusal is silent and clears the cursor: a non-number (`0x4fb7cb`; a numeric string
+    // passes), `index < 1` (`0x4fb7e1`), `index > count` (`0x4fb7e9`), no merchant (`0x4fb7f7`), a
+    // dead row (`0x4fb80b`), or the held row again (`0x4fb818`, the toggle-off). Neither stock nor
+    // the item cache is tested: a sold-out row grabs, and the server refuses the buy.
     g.set(
         "PickupMerchantItem",
         lua.create_function(|lua, index: Option<f64>| {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
 
-            // The sell fork, and it comes FIRST — before the argument is even looked at. The
-            // clear is the SELL clear, not `ClearCursor`: it fires `CURSOR_UPDATE` and leaves the
-            // source slot greyed until the server's inventory update
-            // (`cursor::take_cursor_item_for_sale`, shared with the interact ladder's vendor arm,
-            // which is the same `0x494b60` call — decision 1914).
+            // The sell fork comes first, before the argument is read. Its clear is the sale's, not
+            // `ClearCursor`: `CURSOR_UPDATE` fires and the source slot stays greyed until the
+            // server's inventory update (`0x494b60`).
             if let Some(item) = crate::script::cursor::take_cursor_item_for_sale(&mut model) {
                 model.merchant_cursor_sells.push((item.bag, item.slot));
                 return Ok(());
             }
 
-            // From here every leg clears the cursor and answers nothing. Holding a mode-5 payload
-            // and calling this again is the toggle-off, which is the same clear. It is the REAL
-            // `ClearCursor(1,1)` (`0x4fb82d`/`0x4fb83f` on a refusal, `0x49510b` inside the grab
-            // setter), not a bare payload drop: a spell
-            // or action dropped on the vendor window fires `CURSOR_UPDATE` and hides the bar's
-            // grid, and an armed gift wrap is cancelled (`0x5edf10`, `ClearCursor`'s opening act).
+            // Every other leg clears with the real `ClearCursor(1,1)` (`0x4fb82d`/`0x4fb83f` on a
+            // refusal, `0x49510b` in the grab), not a bare drop: a held spell fires `CURSOR_UPDATE`
+            // and hides the bar grid, and an armed gift wrap is cancelled (`0x5edf10`).
             let held = match &model.cursor {
                 Some(CursorPayload::Merchant(m)) => Some(m.row),
                 _ => None,
@@ -394,14 +302,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             crate::script::cursor::clear_cursor(&mut model);
 
             let Some(index) = index else { return Ok(()) };
-            // `_ftol` truncates toward zero; the bound is then applied signed, so a negative or
-            // a zero index falls out here rather than wrapping into a row. NaN is written as its
-            // own test rather than as a negated `>=` — same answer, and the intent is on the page.
-            //
-            // The upper bound is ours and it is load-bearing, not defensive: without it a Lua
-            // index of `2^32 + 1` truncates on the cast to row 0 and would grab the FIRST row.
-            // The reference cannot have that bug — its bound is against the vendor count, which
-            // it applies before any narrowing.
+            // `_ftol` truncates toward zero, then the bound applies signed. The upper bound is
+            // load-bearing: `2^32 + 1` would narrow to row 0, where the reference bounds against
+            // the vendor count before any narrowing.
             let row = index.trunc();
             if row.is_nan() || row < 1.0 || row > f64::from(u32::MAX) {
                 return Ok(());
@@ -414,7 +317,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             let Some(item) = merchant.items.get(row0 as usize) else {
                 return Ok(());
             };
-            // The toggle-off: naming the row already on the cursor puts nothing back.
+            // The toggle-off: naming the held row puts nothing back.
             if held == Some(row0) {
                 return Ok(());
             }
@@ -423,15 +326,14 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 row: row0,
                 texture: item.texture.clone(),
             });
-            // The grab's own transition (`0x495159` `SignalEvent(CURSOR_UPDATE)`); mode 5 skips
-            // the mode-7 `ACTIONBAR_SHOWGRID` branch, which the shared seam derives from the arm.
+            // The grab's `SignalEvent(CURSOR_UPDATE)` (`0x495159`); mode 5 skips the mode-7
+            // `ACTIONBAR_SHOWGRID` branch.
             model.cursor = Some(payload);
             crate::script::cursor::queue_cursor_update(&mut model);
             Ok(())
         })?,
     )?;
 
-    // CloseMerchant() — client-side close (no packet, vanilla): flag it so the app clears its state.
     g.set(
         "CloseMerchant",
         lua.create_function(|lua, ()| {
@@ -441,7 +343,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // → how many buyback slots are filled (ref GetNumBuybackItems; 0 with no vendor open).
     g.set(
         "GetNumBuybackItems",
         lua.create_function(|lua, ()| {
@@ -450,11 +351,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetBuybackItemInfo(index) → name, texture, price, quantity, numAvailable, isUsable (the
-    // same 6-tuple; 0x4fb310). `index` is 1-based
-    // oldest-first; an invalid index answers the fixed tuple (nil, nil, 0, 1, 0, 1). isUsable is
-    // the same 0x5ea930 gate over the sold item's template (0x4fb4f7) — yes, even a just-sold
-    // item reds if the seller can't use it (a mule selling a wrong-class drop).
+    // GetBuybackItemInfo(index): the same six-tuple (`0x4fb310`), oldest first. isUsable is the
+    // same `0x5ea930` gate over the sold item (`0x4fb4f7`): one its seller cannot use reads red.
     g.set(
         "GetBuybackItemInfo",
         lua.create_function(|lua, index: usize| {
@@ -492,8 +390,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // BenillaGetBuybackItemStats(index) — the buyback hover's tooltip stat head, same shape and
-    // reason as BenillaGetMerchantItemStats.
+    // BenillaGetBuybackItemStats(index): the buyback hover's stat head, as above.
     g.set(
         "BenillaGetBuybackItemStats",
         lua.create_function(|lua, index: usize| {
@@ -523,8 +420,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // BuybackItem(index) — queue the 1-based buyback slot; the app maps it to the wire's absolute
-    // inventory slot.
     g.set(
         "BuybackItem",
         lua.create_function(|lua, index: u32| {
@@ -534,7 +429,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CanMerchantRepair() → 1/nil (the Era boolean shape) — whether the open vendor repairs.
     g.set(
         "CanMerchantRepair",
         lua.create_function(|lua, ()| {
@@ -546,8 +440,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetRepairAllCost() → cost, canRepair — the app-computed repair-all total; canRepair is
-    // "there is damage to pay for" (ref MerchantFrame_OnShow enables the button on it).
+    // GetRepairAllCost() → cost, canRepair: whether there is damage to pay for, which enables the
+    // repair-all button (`MerchantFrame.lua:38`).
     g.set(
         "GetRepairAllCost",
         lua.create_function(|lua, ()| {
@@ -562,7 +456,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // RepairAllItems() — flag the repair-all intent for the app to send.
     g.set(
         "RepairAllItems",
         lua.create_function(|lua, ()| {
@@ -572,9 +465,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The repair-mode latch trio (ref MerchantRepairItemButton OnClick): ShowRepairCursor arms
-    // "next item click repairs", HideRepairCursor disarms, InRepairMode() → 1/nil reads it. The
-    // app reads UiScript::repair_mode to route clicks + swap the hardware cursor.
     g.set(
         "ShowRepairCursor",
         lua.create_function(|lua, ()| {
@@ -604,14 +494,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ShowMerchantSellCursor(index) (5875 `0x4fbab0`, "buying from vendor") and
-    // ShowBuybackSellCursor(index) (`0x4fbbb0`, "re-buying") — the vendor-item hover cursor.
-    // Despite the "Sell" in the names, these arm the BUY cursor with
-    // an affordability gate: player coin vs the row's price → Buy(3) if `coin >= price`, else the
-    // grayed UnableBuy(23). The merchant frame's OnUpdate re-arms this every frame while an item is
-    // hovered (Ctrl-hover swaps to `ShowInspectCursor` instead); OnLeave `ResetCursor`s it. An
-    // unresolvable index leaves the cursor unchanged — the binary's every-fail-path `ret` with no
-    // `CursorSetMode` (the in-flight item lock and base-mode-Point gates live app-side).
+    // ShowMerchantSellCursor(index) (`0x4fbab0`) and ShowBuybackSellCursor(index) (`0x4fbbb0`):
+    // despite the names, the buy cursor, re-armed each frame an item is hovered
+    // (`MerchantFrame.xml:726-733`). Every fail path returns without `CursorSetMode`; the
+    // in-flight item lock and base-mode Point gates live app-side.
     g.set(
         "ShowMerchantSellCursor",
         lua.create_function(|lua, index: usize| {
@@ -634,15 +520,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Arm the vendor-item hover cursor from a `price` picked out of the open merchant snapshot: Buy(3)
-/// if the player can afford it, UnableBuy(23) otherwise. Shared by `ShowMerchantSellCursor` and
-/// `ShowBuybackSellCursor` (which differ only in which price list they read). A `None` price (no
-/// vendor open, or the 1-based index out of range) leaves the cursor untouched — the binary bails
-/// without a `CursorSetMode` (`0x4fbab0`/`0x4fbbb0`).
+/// Arm the vendor hover cursor from a row's price: Buy(3) if the player can afford it, else the
+/// greyed UnableBuy(23); no price leaves the cursor untouched.
 fn arm_vendor_cursor(lua: &Lua, price_of: impl FnOnce(&MerchantState) -> Option<u32>) {
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-    // The sell-cursor family bails on `IsTargeting` at its first instruction (`0x6e48a0`) — an
-    // armed spell keeps its cast cursor.
+    // The family bails on `IsTargeting` first (`0x6e48a0`): an armed spell keeps its cursor.
     if model.spell_targeting {
         return;
     }
@@ -672,7 +554,6 @@ mod tests {
                     quantity: 1,
                     num_available: -1, // unlimited
                     item_id: 159,
-                    // A consumable's stat head: everything zero but the quality.
                     stats: Some(ItemStatsHead {
                         quality: 1,
                         ..Default::default()
@@ -680,7 +561,7 @@ mod tests {
                     link: Some("|cffffffff|Hitem:159:0:0:0|h[Refreshing Spring Water]|h|r".into()),
                     max_stack: Some(20),
                 },
-                // An in-flight row: the vendor list arrived, the item-template answer hasn't.
+                // In flight: the list arrived, its item template has not.
                 MerchantItem {
                     name: None,
                     texture: None,
@@ -700,7 +581,6 @@ mod tests {
     #[test]
     fn merchant_snapshot_reads() {
         let mut s = UiScript::new().unwrap();
-        // No vendor open: count 0, info nil.
         assert_eq!(s.eval::<i64>("return GetMerchantNumItems()").unwrap(), 0);
         assert!(s
             .eval::<bool>("return GetMerchantItemInfo(1) == nil")
@@ -708,7 +588,6 @@ mod tests {
 
         s.set_merchant(Some(stock()));
         assert_eq!(s.eval::<i64>("return GetMerchantNumItems()").unwrap(), 2);
-        // Row 1 (resolved): the byte-verified 6-tuple (0x4fb150) — isUsable is 1, not a boolean.
         let (name, texture, price, quantity, num, usable) = s
             .eval::<(String, String, i64, i64, i64, i64)>("return GetMerchantItemInfo(1)")
             .unwrap();
@@ -717,15 +596,13 @@ mod tests {
         assert_eq!((price, quantity, num), (25, 1, -1));
         assert_eq!(usable, 1);
 
-        // Row 2 (in flight): name + texture nil, the rest still present — and usable (the
-        // null-record skip: no template answer, nothing to judge).
+        // In flight: name and texture nil, and usable (the null-record skip).
         assert!(s
             .eval::<bool>(
                 "local n, t, p, q, a, u = GetMerchantItemInfo(2)\n\
                  return n == nil and t == nil and p == 1500 and u == 1",
             )
             .unwrap());
-        // An invalid index answers the fixed 6-tuple (nil, nil, 0, 1, 0, 1) — 0x4fb2be.
         assert!(s
             .eval::<bool>(
                 "local n, t, p, q, a, u = GetMerchantItemInfo(9)\n\
@@ -733,8 +610,6 @@ mod tests {
             )
             .unwrap());
 
-        // GetMerchantItemLink: the resolved row's link; nil while the template is in flight and nil
-        // out of range (the row click's ctrl/shift arms hand this straight on — decision 1059).
         assert_eq!(
             s.eval::<String>("return GetMerchantItemLink(1)").unwrap(),
             "|cffffffff|Hitem:159:0:0:0|h[Refreshing Spring Water]|h|r"
@@ -746,14 +621,6 @@ mod tests {
             .eval::<bool>("return GetMerchantItemLink(9) == nil")
             .unwrap());
 
-        // **GetMerchantItemMaxStack** — the one number that decides whether a vendor click asks
-        // "how many?". The reference's `MerchantItemButton_OnClick` reads it twice
-        // (`MerchantFrame.lua:313` on the right-click arm and `:340` on shift-click) and takes the
-        // plain single-buy path whenever it is `<= 1`, opening the stack-split spinner otherwise.
-        //
-        // Nil while the row's template answer is in flight, and nil out of range — the same two
-        // absences `GetMerchantItemLink` above has, and for the same reason: the value is the
-        // template's `stackable`, which the wire has carried all along.
         assert_eq!(
             s.eval::<i64>("return GetMerchantItemMaxStack(1)").unwrap(),
             20
@@ -766,9 +633,6 @@ mod tests {
             .unwrap());
     }
 
-    /// The isUsable leg end-to-end: the gate reads the shared template store + the player req
-    /// state, so a level-short player reds the row (nil), levelling past it whitens (1), and the
-    /// same flag drives the buyback tuple.
     #[test]
     fn merchant_usable_tracks_the_item_gate() {
         use crate::script::{ItemTemplateView, PlayerReqState};
@@ -784,7 +648,7 @@ mod tests {
         }];
         s.set_merchant(Some(state));
         s.set_item_template(
-            159, // row 1: the spring water becomes level-gated for the test
+            159, // row 1, level-gated for the test
             ItemTemplateView {
                 name: "Refreshing Spring Water".into(),
                 required_level: 5,
@@ -820,11 +684,10 @@ mod tests {
                 "local n, t, p, q, a, u = GetBuybackItemInfo(1)\nreturn u == nil and n ~= nil",
             )
             .unwrap());
-        // Row 2 has no template pushed → still usable, whatever the player state.
+        // Row 2 has no template, so it is usable whatever the player state.
         assert!(s
             .eval::<bool>("local n, t, p, q, a, u = GetMerchantItemInfo(2)\nreturn u == 1")
             .unwrap());
-        // Levelling past the requirement whitens both.
         s.set_player_req_state(req(5));
         assert!(s
             .eval::<bool>("local n, t, p, q, a, u = GetMerchantItemInfo(1)\nreturn u == 1")
@@ -838,7 +701,7 @@ mod tests {
     fn merchant_stats_feed_reads_the_tooltip_head() {
         let mut s = UiScript::new().unwrap();
         let mut stock = stock();
-        // Row 1 becomes a sword so every stat column is distinguishable.
+        // A sword, so every stat column is distinct.
         stock.items[0].stats = Some(ItemStatsHead {
             quality: 2,
             inventory_type: 21,
@@ -861,7 +724,6 @@ mod tests {
         assert_eq!((quality, inv, class, sub), (2, 21, 2, 7));
         assert_eq!((dmin, dmax, dtype, delay), (5.0, 9.0, 2, 2600));
         assert_eq!((armor, block), (0, 0));
-        // In flight (row 2) and out of range: nil.
         assert!(s
             .eval::<bool>("return BenillaGetMerchantItemStats(2) == nil")
             .unwrap());
@@ -890,8 +752,6 @@ mod tests {
         assert!(!s.take_merchant_close(), "drained");
     }
 
-    /// The buyback surface: count, the ref tuple (including the 5875 binding's exact empty tuple
-    /// `(nil,nil,0,1,0,1)` for an invalid index — 0x4fb310), and the BuybackItem intent drain.
     #[test]
     fn buyback_reads_and_intents() {
         let mut s = UiScript::new().unwrap();
@@ -929,8 +789,6 @@ mod tests {
         assert!(s.take_merchant_buybacks().is_empty(), "drained");
     }
 
-    /// The repair surface: CanMerchantRepair off the snapshot, GetRepairAllCost's (cost, canRepair)
-    /// pair, the RepairAllItems intent, and the client-side repair-mode latch trio.
     #[test]
     fn repair_reads_intents_and_mode_latch() {
         let mut s = UiScript::new().unwrap();
@@ -949,7 +807,6 @@ mod tests {
         assert!(s.take_repair_all());
         assert!(!s.take_repair_all(), "drained");
 
-        // ShowRepairCursor arms, InRepairMode reads (1/nil), HideRepairCursor disarms.
         assert!(s.eval::<bool>("return InRepairMode() == nil").unwrap());
         s.run("ShowRepairCursor()").unwrap();
         assert!(s.repair_mode());
@@ -969,16 +826,11 @@ mod tests {
             .unwrap());
     }
 
-    /// The vendor-item hover cursor (`ShowMerchantSellCursor`/`ShowBuybackSellCursor`, `0x4fbab0`/
-    /// `0x4fbbb0`): Buy(3) when the player can afford the row, the grayed UnableBuy(23) when they
-    /// can't; `ShowInspectCursor` arms the magnifier; `ResetCursor` clears the whole override; an
-    /// unresolvable index (or no vendor open) leaves the cursor unchanged.
     #[test]
     fn vendor_hover_cursor_gates_on_affordability() {
         use crate::script::UiCursorMode;
         let mut s = UiScript::new().unwrap();
 
-        // No vendor open: the Show* calls resolve nothing and leave the cursor untouched.
         s.run("ShowMerchantSellCursor(1)").unwrap();
         assert_eq!(s.ui_cursor(), None);
 
@@ -990,38 +842,30 @@ mod tests {
         s.set_merchant(Some(state));
         s.set_money(100); // affords row 1 (25) + buyback (47), not row 2 (1500)
 
-        // Row 1: coin ≥ price → Buy(3).
         s.run("ShowMerchantSellCursor(1)").unwrap();
         assert_eq!(s.ui_cursor(), Some(UiCursorMode::Buy));
-        // Row 2: coin < price → the grayed UnableBuy(23).
         s.run("ShowMerchantSellCursor(2)").unwrap();
         assert_eq!(s.ui_cursor(), Some(UiCursorMode::UnableBuy));
 
-        // The Ctrl-hover magnifier, then ResetCursor back to the base mode.
         s.run("ShowInspectCursor()").unwrap();
         assert_eq!(s.ui_cursor(), Some(UiCursorMode::Inspect));
         s.run("ResetCursor()").unwrap();
         assert_eq!(s.ui_cursor(), None);
 
-        // Buyback affords too → Buy(3).
         s.run("ShowBuybackSellCursor(1)").unwrap();
         assert_eq!(s.ui_cursor(), Some(UiCursorMode::Buy));
 
-        // An out-of-range index bails without touching the armed cursor (the binary's no-CursorSetMode
-        // fail path) — the Buy from the buyback hover above survives.
+        // Out of range leaves the armed cursor as it was.
         s.run("ShowMerchantSellCursor(99)").unwrap();
         assert_eq!(s.ui_cursor(), Some(UiCursorMode::Buy));
     }
-    /// `PickupMerchantItem` is TWO verbs, and which one runs is decided by the cursor, never by
-    /// the caller — stock FrameXML never guards it (`0x4fb760`).
     #[test]
     fn pickup_merchant_item_grabs_a_row_as_mode_5() {
         let mut s = UiScript::new().unwrap();
         s.set_merchant(Some(stock()));
 
         s.run("PickupMerchantItem(1)").unwrap();
-        // Mode 5 is INVISIBLE to Lua. This is the load-bearing assertion in the whole file: all
-        // thirteen stock `CursorHasItem()` gates stay closed while a vendor cursor is held.
+        // Mode 5 is invisible to Lua: every stock `CursorHasItem()` gate stays closed.
         assert!(
             s.eval::<bool>("return not CursorHasItem()").unwrap(),
             "CursorHasItem is nil for mode 5"
@@ -1032,15 +876,12 @@ mod tests {
             "GetCursorInfo reports nothing — no binding exposes mode 5"
         );
 
-        // …but it IS held: a second call naming the same row is the toggle-off (`0x4fb818`), and
-        // a third call re-grabs it. Nothing else can observe the difference from Lua, so the
-        // toggle is what the test reads it through.
+        // Yet it is held: a second call toggles it off (`0x4fb818`), a third re-grabs.
         s.run("PickupMerchantItem(1)").unwrap();
         s.run("PickupMerchantItem(1)").unwrap();
         assert!(s.take_merchant_slot_buys().is_empty(), "no drop yet");
     }
 
-    /// Every refusal is silent AND clears the cursor — there is no `luaL_error` in the range.
     #[test]
     fn pickup_merchant_item_refuses_silently_and_clears() {
         let mut s = UiScript::new().unwrap();
@@ -1059,11 +900,10 @@ mod tests {
                 "{bad} cleared the cursor"
             );
         }
-        // A missing argument is the same silent clear, not an error.
+        // A missing argument is the same silent clear.
         s.run("PickupMerchantItem(1)").unwrap();
         s.run("PickupMerchantItem()").unwrap();
-        // A wrapping index must not become a valid row: `2^32 + 1` narrows to 0 on a naive cast
-        // and would grab row 1. It refuses, and the cursor stays empty.
+        // `2^32 + 1` narrows to row 0 on a naive cast.
         s.run("PickupMerchantItem(4294967297)").unwrap();
         assert!(s.eval::<bool>("return GetCursorInfo() == nil").unwrap());
         s.run("PickupContainerItem(0, 3)").unwrap();
@@ -1071,17 +911,12 @@ mod tests {
             s.take_merchant_slot_buys().is_empty(),
             "the wrapping index grabbed nothing"
         );
-        // A numeric STRING is accepted (`_ftol` over a converted argument), and `1.9` truncates
-        // toward zero to row 1 — not rounds to 2.
+        // A numeric string is accepted, and 1.9 truncates to the held row 1, toggling it off.
         s.run(r#"PickupMerchantItem("1")"#).unwrap();
         s.run("PickupMerchantItem(1.9)").unwrap();
-        // …which the toggle proves: 1.9 named the row 1 already held, so it toggled off.
         assert!(s.eval::<bool>("return GetCursorInfo() == nil").unwrap());
     }
 
-    /// The sell arm: a bag item on the cursor makes this a sell, the index is ignored, and the
-    /// cursor empties. This is what stock `MerchantFrame.xml:743`'s `PickupMerchantItem(0)` is —
-    /// an index the grab arm would refuse outright.
     #[test]
     fn pickup_merchant_item_sells_what_the_cursor_holds() {
         use crate::script::cursor::{CursorItem, CursorPayload};
@@ -1109,7 +944,6 @@ mod tests {
         assert!(s.take_merchant_cursor_sells().is_empty(), "drained");
     }
 
-    /// The drop is the buy. A held row placed into a bag slot queues `CMSG_BUY_ITEM_IN_SLOT`.
     #[test]
     fn a_held_vendor_row_dropped_in_a_bag_is_a_buy() {
         let mut s = UiScript::new().unwrap();
@@ -1127,15 +961,15 @@ mod tests {
         );
     }
 
-    /// A stale row is a refusal, not a wrong buy. The reference has a latent null deref on two of
-    /// its three drop paths for exactly this case (a fresh `SMSG_LIST_INVENTORY` rewrites the
-    /// count without clearing the cursor); we take the third path's behaviour on all of them.
+    /// Deviation: a stale row drops without buying on all three drop paths, because two of the
+    /// reference's three dereference a null here (a fresh `SMSG_LIST_INVENTORY` rewrites the count
+    /// without clearing the cursor); we take the third path's behaviour.
     #[test]
     fn a_stale_vendor_row_drops_without_buying() {
         let mut s = UiScript::new().unwrap();
         s.set_merchant(Some(stock()));
         s.run("PickupMerchantItem(2)").unwrap();
-        // The vendor list is replaced while the cursor still holds row 2 of the old one.
+        // The list is replaced while the cursor holds row 2 of the old one.
         let mut shorter = stock();
         shorter.items.truncate(1);
         s.set_merchant(Some(shorter));
@@ -1147,16 +981,13 @@ mod tests {
         assert!(s.eval::<bool>("return GetCursorInfo() == nil").unwrap());
     }
 
-    /// A vendor cursor is not a bar action and not an equip: `PlaceAction` refuses it and hands it
-    /// back, exactly as it does the pet-action and stable-pet payloads.
     #[test]
     fn the_action_bar_refuses_a_vendor_row_and_keeps_it_held() {
         let mut s = UiScript::new().unwrap();
         s.set_merchant(Some(stock()));
         s.run("PickupMerchantItem(1)").unwrap();
         s.run("PlaceAction(1)").unwrap();
-        // Still held, proven positively: dropping it in a bag afterwards still buys. An asserted
-        // *absence* here would pass just as well if the bar had eaten the payload.
+        // Still held: dropping it in a bag afterwards buys.
         s.run("PickupContainerItem(0, 5)").unwrap();
         assert_eq!(s.take_merchant_slot_buys(), vec![(0, 5, 159)]);
     }
@@ -1187,9 +1018,8 @@ mod tests {
         (n("updates"), n("shows"), n("hides"))
     }
 
-    /// The grab writes through the real cursor setter (`0x4950f0`): `CURSOR_UPDATE` at
-    /// `0x495159`, and — mode 5 not being mode 7 — **no**
-    /// `ACTIONBAR_SHOWGRID`: a vendor row cannot land on the bar, so its empty slots stay dark.
+    /// The grab goes through the cursor setter (`0x4950f0`): `CURSOR_UPDATE` at `0x495159`, and
+    /// no `ACTIONBAR_SHOWGRID` since mode 5 is not mode 7.
     #[test]
     fn a_vendor_grab_fires_cursor_update_but_not_the_bar_grid() {
         let mut s = UiScript::new().unwrap();
@@ -1201,15 +1031,11 @@ mod tests {
             (1, 0, 0),
             "(CURSOR_UPDATE, ACTIONBAR_SHOWGRID, ACTIONBAR_HIDEGRID) after a vendor grab"
         );
-        // …and its toggle-off is a plain clear: one more CURSOR_UPDATE, and no HIDEGRID either.
+        // The toggle-off is a plain clear: one more CURSOR_UPDATE, no HIDEGRID.
         s.run("PickupMerchantItem(1)").unwrap();
         assert_eq!(cursor_event_counts(&mut s), (2, 0, 0));
     }
 
-    /// Every non-sell leg opens with `ClearCursor(1,1)` (`0x4fb82d`/`0x4fb83f` on a refusal,
-    /// `0x49510b` inside the grab), so a spell held over the
-    /// vendor window and dropped there — stock `MerchantFrame.xml`'s `OnMouseUp`,
-    /// `PickupMerchantItem(0)` — is a real clear: the bar's grid hides and `CURSOR_UPDATE` fires.
     #[test]
     fn a_spell_dropped_on_the_vendor_is_a_real_clear() {
         use crate::script::cursor::{self, CursorPayload, CursorSpell};
@@ -1235,8 +1061,8 @@ mod tests {
         );
     }
 
-    /// `ClearCursor 0x495190` opens with the gift-wrap cancel (`0x5edf10`, decision 1934), and the
-    /// grab's first act is that clear (`0x49510b`) — so taking a vendor row disarms a wrap.
+    /// `ClearCursor 0x495190` opens with the gift-wrap cancel (`0x5edf10`), and the grab opens
+    /// with that clear (`0x49510b`).
     #[test]
     fn a_vendor_grab_cancels_an_armed_gift_wrap() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/messageframe/mod.rs b/crates/benilla-ui/src/script/messageframe/mod.rs
index b3415930..f23c9419 100644
--- a/crates/benilla-ui/src/script/messageframe/mod.rs
+++ b/crates/benilla-ui/src/script/messageframe/mod.rs
@@ -1,22 +1,12 @@
-//! The two message-frame widget classes, and the display machinery they share.
+//! The two message-frame classes and the display code they share. In 1.12 they are siblings, not
+//! parent and child, each with its own method table, so a method only one carries is nil on the
+//! other:
 //!
-//! 1.12 ships **two** of them, and they are *siblings, not parent and child* (different ctors,
-//! different vtables, different Lua type tags, offsets that do not transfer):
+//! - [`scrolling`]: `CSimpleMessageScrollFrame` (ctor `0x787670`), the chat window's class.
+//! - [`plain`]: `CSimpleMessageFrame` (ctor `0x785640`), `UIErrorsFrame`'s class.
 //!
-//! - [`scrolling`] — `CSimpleMessageScrollFrame` (ctor `0x787670`), the chat window's class: a true
-//!   ring of `maxLines`, a scrollback cursor, `AddMessage(text[,r,g,b[,id]])` with alpha forced
-//!   opaque.
-//! - [`plain`] — `CSimpleMessageFrame` (ctor `0x785640`), `UIErrorsFrame`'s class: no ring, no
-//!   scrollback, `insertMode`, and `AddMessage(text[,r,g,b[,a]])` whose fourth numeric is a real
-//!   **alpha**.
-//!
-//! Each gets its **own** Lua method table, consulted by the frame `__index` dispatcher only for its
-//! own [`FrameKind`](crate::widget::FrameKind) — so a duck-typing addon (`if f.SetInsertMode then`)
-//! sees `nil` everywhere else, exactly as against the client's per-class registrar tables.
-//!
-//! What *is* shared sits here: both classes display a stack of [`MessageLine`] records, so the
-//! wrapped-row measure round-trip, the band emit, and the font/justification read are one code path
-//! over [`KindState::message_lines`]. Everything that actually differs stays on the two states.
+//! Both display a stack of [`MessageLine`] records, so the row measure, the band emit and the font
+//! read are shared here.
 
 use crate::layout::Rect;
 use crate::order::ZTarget;
@@ -34,62 +24,20 @@ mod scrolling;
 pub(super) use plain::REG_MESSAGEFRAME_METHODS;
 pub(super) use scrolling::REG_SCROLLINGMESSAGEFRAME_METHODS;
 
-/// Install both classes' method tables (and the chat input globals the scrolling one carries).
-/// **`AddMessage`'s text argument, and the three ways it silently swallows the whole call.**
-/// `None` means *do nothing at all* — no line, no record, no error.
-///
-/// `CSimpleMessageFrame::AddMessage 0x795590` fetches Lua index 2 through `lua_isstring 0x6f3510`
-/// and then `lua_tostring 0x6f3690`, and **three** results jump to the function's own epilogue at
-/// `0x79582b` (`pop edi / pop esi / xor eax,eax / pop ebx / leave / ret` — zero Lua values, no
-/// push, and the virtual enqueue at `0x795825 call [eax+0x90]` never reached):
-///
-/// ```text
-///   79561b  mov edx,2
-///   795625  call 0x6f3510      ; lua_isstring — tags 4 (string) and 3 (number) only
-///   79562c  je   0x79582b      ; nil / boolean / table / function  -> silent
-///   795642  je   0x79582b      ; lua_tostring returned NULL        -> silent
-///   79564b  je   0x79582b      ; cmp byte ptr [ebx],0 — EMPTY string -> silent
-/// ```
-///
-/// `ScrollingMessageFrame:AddMessage 0x792900` is the same shape (gate `0x79299c`, `je 0x792b81` =
-/// its own epilogue), so `DEFAULT_CHAT_FRAME:AddMessage(nil)` is silent too.
-///
-/// **This is not a general argument law and must not be read as one** (1717's rule: the shape is
-/// settled per binding). The *colour* arguments beside it behave the opposite way — a bad `r`/`g`/
-/// `b`/`a` jumps to `0x79581c`, which still calls the enqueue with the `0xffffffff` opaque white
-/// staged at `0x795658`. Only a bad **text** shows nothing. The three *receiver* guards
-/// (`0x847ef8` "used '.' instead of ':'", `0x847ec0`, `0x847e98`) do still raise, and they are
-/// upstream of this.
-///
-/// **Why it is load-bearing rather than pedantry.** Stock FrameXML takes this path: 1.12's
-/// `ContainerFrame.lua:753` reports a full keyring with
-/// `UIErrorsFrame:AddMessage(NO_EMPTY_KEYRING_SLOTS, 1.0, 0.1, 0.1, 1.0)` and **no such
-/// GlobalString exists** — the shipped `GlobalStrings.lua` defines only
-/// `NO_EMPTY_KEYRING_SLOTS_ERROR`, a rename that updated the definition and not the use. So a
-/// player dropping a key onto a full keyring gets a dead click on a real client. Taking a `String`
-/// here (which is what this did until 1751's fourth window swapped the bag bar in) raised instead,
-/// putting a script-error dialog on an ordinary player gesture that the reference never shows.
-///
-/// A **number** is accepted and rendered as its decimal text — `0x6f7c80` retags the slot in
-/// place — which is exactly [`super::binding_abi::optional_string`]'s coercion.
+/// `AddMessage`'s text; `None` means the whole call does nothing, no line and no error. Both
+/// bindings (`0x795590`, `0x792900`) jump to their epilogue (`0x79582b`, `0x792b81`) when
+/// `lua_isstring` (`0x6f3510`) fails, `lua_tostring` (`0x6f3690`) gives NULL or the string is empty
+/// (`0x79564b`). Stock `ContainerFrame.lua:753` passes the undefined `NO_EMPTY_KEYRING_SLOTS` on a
+/// full keyring and gets a silent click. Only the text is gated so: a bad colour still adds the
+/// line in white (`0x79581c`), and the receiver checks (`0x847ef8`) still raise. A number becomes
+/// its decimal text (`0x6f7c80`).
 pub(super) fn message_text(lua: &mlua::Lua, v: &mlua::Value) -> Option<String> {
     super::binding_abi::optional_string(lua, v).filter(|s| !s.is_empty())
 }
 
-/// Install `SetJustifyH`/`GetJustifyH`/`SetJustifyV`/`GetJustifyV` on a message-frame method
-/// table. Both classes carry all four (see [`crate::widget::ScrollingMessageState::justify`] for
-/// the method-table bytes that settled it), and the law they obey is
-/// [`crate::justify`]'s — shared with FontString, `<Font>` and EditBox since 1237, so the two
-/// verified traps cannot drift apart per widget:
-///
-///  · an **unrecognised token RAISES** `Usage: %s:SetJustifyH("justify")` rather than defaulting;
-///  · a token from the **other axis** parses and then masks to nothing — `SetJustifyH("TOP")`
-///    CLEARS the horizontal axis, and `GetJustifyH()` answers `"UNKNOWN"` while the glyphs keep
-///    drawing at the paint fallback.
-///
-/// `GetJustify*` reports the EFFECTIVE value — the frame's own once set, else the font object's —
-/// so an untouched frame answers what it actually draws with rather than a ctor constant its
-/// `<FontString>` may have overridden.
+/// Install `SetJustifyH`, `GetJustifyH`, `SetJustifyV` and `GetJustifyV`, which both classes carry,
+/// under [`crate::justify`]'s rules: an unknown token raises the usage line, and a token of the
+/// other axis clears this one, so `GetJustifyH()` then answers `"UNKNOWN"`.
 use crate::script::object::frame_handle_of;
 
 pub(super) fn install_justify(
@@ -146,13 +94,8 @@ pub(super) fn install_justify(
         )?;
     }
 
-    // The two getters differ ONLY in what an untouched frame falls back to, and the asymmetry is
-    // real rather than an oversight: horizontally there IS another source — the font object the
-    // lines actually draw with — so reporting anything else would have `GetJustifyH` disagree with
-    // the glyphs on our own chat window, which declares `justifyH="LEFT"` on its `<FontString>`.
-    // Vertically there is no such source: `emit_message_lines` pins each line to the top of its own
-    // band deliberately (the band, not a FontString rect, owns the vertical rhythm), so an untouched
-    // frame reports the ctor default rather than a value invented from our band math.
+    // On an untouched frame `GetJustifyH` answers its font's `justifyH`, what the lines draw with,
+    // and `GetJustifyV` the ctor default, as each line sits at the top of its own band.
     m.set(
         "GetJustifyH",
         lua.create_function(move |lua, this: mlua::Table| {
@@ -189,39 +132,21 @@ pub(super) fn install(lua: &mlua::Lua) -> mlua::Result<()> {
     plain::install(lua)
 }
 
-/// The font a message frame's lines draw with — its declared `<FontString>` child, which is exactly
-/// how both reference frames spell it (`<FontString inherits="ChatFontNormal" justifyH="LEFT"/>` on
-/// a chat frame, `<FontString inherits="ErrorFont" justifyH="CENTER"/>` on `UIErrorsFrame.xml`).
-/// Shared by the emit and the measure round-trip so bands, measures and glyphs agree. Missing ⇒ the
-/// renderer's default face at the ~14px chat default.
+/// The font a message frame's lines draw with: its declared `<FontString>` child, as the stock
+/// chat frames and `UIErrorsFrame.xml` declare it, else the default face at 14 px.
 #[derive(Clone)]
 pub(super) struct MessageFont {
     pub(super) path: Option<String>,
     pub(super) height: Option<f32>,
     pub(super) shadow: Option<FontShadow>,
     pub(super) outline: Outline,
-    /// The child's `justifyH`. **Load-bearing, not decoration**: it is the only reason the
-    /// reference's error toasts sit centred in their 512-wide frame while chat lines run flush
-    /// left, and the class draws its lines through that font instance. A frame with no declared
-    /// FontString falls back to LEFT (the chat shape), never to the FontString default of CENTER —
-    /// there is no region here whose own default could apply.
+    /// The child's `justifyH`, which centres `UIErrorsFrame`'s lines and keeps chat flush left;
+    /// LEFT without a declared FontString, not the FontString default of CENTER.
     pub(super) justify_h: JustifyH,
 }
 
-/// The FontString region a message frame's **style** lives on — found, or created on demand.
-///
-/// Both classes draw their lines through one font instance, and [`UiScript::message_frame_font`]
-/// reads it off the frame's first `FontString` region. That region normally comes from the
-/// declared direct-child `<FontString>` (LoadXML's "special" font string — our ChatFrame has one).
-/// A frame built by `CreateFrame("MessageFrame")` has none, so the ten shared font-block verbs
-/// need somewhere to write: this is that somewhere, and it is created **only** when one of them is
-/// actually called, so a frame nobody styles never grows a region.
-///
-/// **It is seated LEFT deliberately.** A frame with no declared FontString falls back to LEFT (the
-/// chat shape) per [`MessageFont::justify_h`]'s law — but a freshly created `RegionData` defaults
-/// to the *FontString* default of CENTER. Creating the region at the default would silently
-/// re-justify a frame the moment an addon touched its font, which is a visible change nobody
-/// asked for.
+/// The FontString region holding a message frame's font, made on the first font-block call when
+/// the frame declared none. It is made LEFT, not CENTER, so styling a frame never re-justifies it.
 pub(super) fn ensure_font_region(
     lua: &mlua::Lua,
     fh: FrameHandle,
@@ -288,11 +213,8 @@ impl UiScript {
             })
     }
 
-    /// How many display **rows** frame `fh`'s resolved rect holds at its line font's pitch — the
-    /// client's layout-derived `numLinesDisplayed`. `0` when the frame has no resolved rect.
-    ///
-    /// Both classes need it and neither can compute it from its own state: it is the page size for
-    /// the scrolling class's `PageUp`/`PageDown` and the whole capacity law for the plain one.
+    /// How many rows frame `fh`'s resolved rect holds at its font's pitch, the client's
+    /// `numLinesDisplayed`: the scrolling class's page size and the plain class's capacity.
     pub(super) fn message_viewport_rows(model: &Model, fh: FrameHandle) -> usize {
         let pitch = Self::message_frame_font(model, fh)
             .height
@@ -303,16 +225,12 @@ impl UiScript {
         })
     }
 
-    /// Message lines whose wrapped **row count** needs a host measurement (a new line, or the
-    /// frame's width/font changed under it) — the message-frame half of the measure round-trip.
-    /// Call after [`UiScript::resolve`] (widths must be resolved); answer with
-    /// [`UiScript::set_message_line_rows`] before extract. Cache keys keep this empty on quiet
-    /// frames.
+    /// Message lines whose wrapped row count needs a host measure. Call after
+    /// [`UiScript::resolve`]; answer with [`UiScript::set_message_line_rows`] before extract.
     pub fn message_lines_needing_measure(&mut self) -> Vec<LineMeasureRequest> {
         use std::hash::{Hash, Hasher};
         let mut model = self.model_mut();
-        // A plain reborrow so the arena borrow inside the loop and the sweep-token field writes
-        // split by FIELD instead of fighting over the RefMut.
+        // A plain reborrow, so the arena reads and the sweep-token writes borrow disjoint fields.
         let model = &mut *model;
         let mut out = Vec::new();
         let frames: Vec<(FrameHandle, Rect)> = model
@@ -329,7 +247,7 @@ impl UiScript {
         for (fh, fr) in frames {
             let wrap_width = fr.right - fr.left;
             if wrap_width <= 1.0 {
-                continue; // unresolved/degenerate width — nothing meaningful to wrap against
+                continue; // no width to wrap against
             }
             let scale = model
                 .arena
@@ -344,13 +262,9 @@ impl UiScript {
             let Some(lines) = frame.kind_state.message_lines() else {
                 continue;
             };
-            // The skip token (the W4 fix, 1410's lane one door over): a frame whose line set
-            // (lines_gen) and measure environment (font/wrap/scale/outline) both match its last
-            // CLEAN sweep can produce nothing — every line's rows_key was minted under exactly
-            // these inputs and matched then. Environment changes (a resize, a font swap, a
-            // SetScale) miss the env hash; text changes miss the generation. The token is only
-            // stored by a zero-request sweep (below), so an unanswered request keeps
-            // re-requesting — the same rule the region ledger runs under.
+            // Skip a frame whose line generation and measure environment match its last clean
+            // sweep. Only a sweep with no requests stores the token, so an unanswered request
+            // keeps re-requesting.
             let lines_gen = frame.kind_state.lines_gen().unwrap_or(0);
             let env = {
                 use std::hash::{Hash, Hasher};
@@ -400,9 +314,8 @@ impl UiScript {
         out
     }
 
-    /// Store host row-count answers for [`LineMeasureRequest`]s (`(frame, index, rows, key)` —
-    /// frame/index/key verbatim from the request). The key is stored beside the rows, so a line
-    /// whose width/font changed again since the request simply re-requests next frame.
+    /// Store host row counts, `(frame, index, rows, key)` echoed from each [`LineMeasureRequest`].
+    /// The key is stored beside the rows, so a line that changed since its request re-requests.
     pub fn set_message_line_rows(&mut self, rows: &[(u32, u32, u16, u64)]) {
         let mut model = self.model_mut();
         for &(frame_id, index, n, key) in rows {
@@ -422,31 +335,14 @@ impl UiScript {
         }
     }
 
-    /// Push one [`QuadContent::Text`] per visible message of either message-frame class (no-op for
-    /// any other kind). Each message occupies `rows × pitch` (its host-measured wrapped row count —
-    /// the message-line measure round-trip), so a long line pushes its neighbours by its real
-    /// height. The pitch is the **font height itself** — the client's own line-step law
-    /// (`LayoutLines` 0x5cdc20: step = px(size) + spacing, spacing 0), the same law the app's text
-    /// renderer lays wrapped rows at, so band grid and glyph rows coincide by construction. (The
-    /// msgframe's own relayout `0x788750/0x788c00` is not fully traced — if the look pass ever
-    /// shows the ref spacing chat lines wider than the font height, that residual is the place to
-    /// pin.)
-    ///
-    /// **Which edge the stack grows from is the one place the two classes diverge visibly.** A
-    /// ScrollingMessageFrame always stacks bottom-up with `scroll_offset` picking which message
-    /// sits on the bottom row. A MessageFrame has no scrollback and instead honours `insertMode`:
-    /// BOTTOM (the ctor default) is the same bottom-up stack, TOP hangs the newest message off the
-    /// frame's top edge with older ones stepping *down* — the shape `UIErrorsFrame.xml:4` asks for,
-    /// and the one every corpus `SetInsertMode` caller asks for. The growth *anchor* per mode is
-    /// not settled at the bytes, so this is the INFERRED half: it is the reading that reproduces
-    /// both shipped usages, and the place to
-    /// re-pin if a reference A/B ever disagrees.
-    ///
-    /// A message that only partially fits at the far edge still draws — clipped to the frame rect,
-    /// so its inner wrapped rows show, never inking outside the frame. A fully-faded scrolling line
-    /// draws nothing but still holds its rows (the reference's chat never re-packs as old lines
-    /// fade); a faded MessageFrame line is gone from the state entirely by then, because that class
-    /// frees its lines instead of holding slots.
+    /// Push one [`QuadContent::Text`] per visible message of either class, each `rows × pitch`
+    /// tall. The pitch is the font height, the client's line step (`LayoutLines` `0x5cdc20`: size
+    /// plus a spacing of 0); the message frame's own relayout (`0x788750`, `0x788c00`) is not fully
+    /// traced. A scrolling frame stacks up from the bottom, `scroll_offset` choosing the bottom
+    /// message. A MessageFrame does too for `insertMode` BOTTOM, and for TOP hangs the newest off
+    /// the top edge (`UIErrorsFrame.xml:4`); the reference's anchor per mode is untraced, and this
+    /// reading reproduces both stock uses. A message that partly fits draws clipped; a faded
+    /// scrolling line keeps its rows, as the reference never re-packs chat.
     pub(super) fn emit_message_lines(
         model: &Model,
         fh: FrameHandle,
@@ -483,23 +379,20 @@ impl UiScript {
             KindState::Message(s) => s.justify,
             _ => None,
         };
-        // The band grid lives in the frame's RESOLVED (scale-multiplied) rect, so the row pitch
-        // rides the frame scale exactly like the glyphs it must coincide with (the font height
-        // itself is frame-local).
+        // The resolved rect is scaled and the font height is frame-local, so the pitch scales.
         let pitch = font.height.unwrap_or(14.0) * paint.scale;
         if pitch <= 0.0 || fr.top <= fr.bottom {
             return;
         }
-        // Message text never inks outside its frame: a partially-fitting outermost message is
-        // scissored at the frame edge (intersected with any ScrollFrame ancestor clip).
+        // Clip to the frame, intersected with any ScrollFrame ancestor's clip.
         let line_clip = Some(match clip {
             Some(c) => super::clip::intersect_rect(c, fr),
             None => fr,
         });
-        let mut used = 0.0f32; // rows already consumed, in px in from the anchored edge
+        let mut used = 0.0f32; // px used from the anchored edge
         for idx in (0..=top_index).rev() {
             if used >= fr.top - fr.bottom {
-                break; // the next band would start outside the frame — nothing more can show
+                break; // the next band starts outside the frame
             }
             let line = &lines[idx];
             let band_h = f32::from(line.rows.max(1)) * pitch;
@@ -510,7 +403,7 @@ impl UiScript {
             };
             used += band_h;
             if line.alpha <= 0.0 {
-                continue; // fully faded — holds its place, draws nothing
+                continue; // faded: holds its rows, draws nothing
             }
             out.push(ExtractedQuad {
                 target: ZTarget::Frame(fh),
@@ -526,27 +419,21 @@ impl UiScript {
                         f32::from(line.color[2]) / 255.0,
                         line.alpha,
                     ]),
-                    // The frame's own justify wins once SetJustifyH has been called; until then
-                    // the font object's governs, which is what `justifyH=` on the frame's
-                    // `<FontString>` set and what this drew with before the verbs existed.
+                    // The frame's own justify once set, else its font's.
                     justify_h: match own_justify {
                         Some(j) => j.paint_h(),
                         None => font.justify_h,
                     },
-                    // The band is our own per-message construct (rows × pitch tall, not a
-                    // FontString rect) — keep the block at its top so the band math, not MIDDLE
-                    // centering, owns the vertical rhythm; the band height equals the wrapped
-                    // block height exactly, so Top means "fills the band".
+                    // The band is exactly the wrapped block's height, so Top fills it.
                     justify_v: JustifyV::Top,
                     font: font.path.clone(),
-                    // The font object's own drop shadow (ChatFontNormal's `(1,-1)` black) — what
-                    // makes the lines read against the world behind the transparent frame.
+                    // The font's own shadow, ChatFontNormal's black at `(1,-1)`.
                     shadow: font.shadow,
                     font_height: font.height,
-                    text_height: None, // message lines are never SetTextHeight'd
+                    text_height: None, // message lines have no SetTextHeight
                     outline: font.outline,
                     alpha_gradient: None,
-                    world_seat: false, // a chat frame is interface, on the interface's grid
+                    world_seat: false, // interface, not world
                 },
                 scale: paint.scale,
             });
diff --git a/crates/benilla-ui/src/script/messageframe/plain.rs b/crates/benilla-ui/src/script/messageframe/plain.rs
index c850d54a..dac122a5 100644
--- a/crates/benilla-ui/src/script/messageframe/plain.rs
+++ b/crates/benilla-ui/src/script/messageframe/plain.rs
@@ -1,25 +1,9 @@
-//! The `MessageFrame` method surface — `CSimpleMessageFrame` (ctor `0x785640`), the class
-//! `UIErrorsFrame` is and the one `CreateFrame("MessageFrame")` makes.
-//!
-//! Three facts decide this whole file, and each is one an implementation would otherwise get wrong
-//! in a way nothing would catch:
-//!
-//! 1. **`AddMessage(text [, r, g, b [, a]])` — the fifth argument is ALPHA and there is no sixth.**
-//!    Three corpus addons pass six (`EasyCopy.lua:12`, `QuestHistory.lua:1678`, `QuestItem.lua:300`,
-//!    all `UIErrorsFrame:AddMessage(msg, r, g, b, a, holdTime)`), and the real 1.12.1 binding
-//!    `0x795590` reads five and stops. Honouring that trailing number as a per-message hold time
-//!    would be **unfaithful, not generous** — the client shows the message for the *frame's*
-//!    `displayDuration` and nothing else. It is ignored here, deliberately.
-//! 2. **This `AddMessage` is not the scrolling class's.** `0x792900` takes an **id** in the same
-//!    slot and forces alpha `0xFF` (`792add: or edi,0xffffff00`); `0x795590` packs a real
-//!    `0xAARRGGBB` with a default of 1.0. Two bindings, two tables, no sharing.
-//! 3. **`SetInsertMode`/`GetInsertMode` (`0x794ed0`/`0x794ff0`) live on this class only** — the
-//!    scrolling class has neither, and no `insertMode` XML attribute either.
-//!
-//! The state (display lines, fade phases, the vertical cap) is
-//! [`MessageFrameState`](crate::widget::MessageFrameState) in `crate::widget`; this is the thin Lua
-//! binding over it. The band emit and the wrapped-row measure round-trip are shared with the
-//! scrolling class and live in [`super`].
+//! The `MessageFrame` methods over [`MessageFrameState`](crate::widget::MessageFrameState):
+//! `CSimpleMessageFrame` (ctor `0x785640`), `UIErrorsFrame`'s class and what
+//! `CreateFrame("MessageFrame")` makes. Its `AddMessage(text [, r, g, b [, a]])` (`0x795590`) takes
+//! a real alpha and reads nothing after it, where the scrolling class's (`0x792900`) takes an id
+//! there and forces alpha opaque. `SetInsertMode` and `GetInsertMode` (`0x794ed0`, `0x794ff0`)
+//! exist on this class only.
 
 use mlua::{Lua, Table, Value};
 
@@ -27,13 +11,11 @@ use crate::script::object::frame_handle_of;
 use crate::script::Model;
 use crate::widget::{InsertMode, KindState, MessageFrameState};
 
-/// Registry key of the MessageFrame method table (the MAXCSTACK discipline: Lua-side root, named
-/// key).
+/// Registry key of the MessageFrame method table (the MAXCSTACK discipline).
 pub(crate) const REG_MESSAGEFRAME_METHODS: &str = "__benilla_plain_messageframe_methods";
 
-/// Run `f` over a frame's MessageFrame state under one short write borrow. Errors if `this` is not
-/// a live MessageFrame (unreachable through the kind dispatcher, but the method table is a plain
-/// Lua value — a caller could fish it out and misapply it).
+/// Run `f` over a MessageFrame's state under one short borrow; any other frame, reachable only
+/// through a misapplied method table, is an error.
 fn with_mf<T>(
     lua: &Lua,
     this: &Table,
@@ -51,7 +33,7 @@ fn with_mf<T>(
     }
 }
 
-/// A Lua number-ish → f32 (nil/other → 0.0), for the colour args.
+/// A colour argument as f32, 0 for anything but a number.
 fn num_f32(v: &Value) -> f32 {
     match v {
         Value::Number(n) => *n as f32,
@@ -63,30 +45,14 @@ fn num_f32(v: &Value) -> f32 {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let m = lua.create_table()?;
 
-    // The justify quartet, shared with the sibling class — see [`super::install_justify`] for the
-    // method-table bytes that put all four on BOTH tables.
+    // The justify quartet, on both classes ([`super::install_justify`]).
     super::install_justify(lua, &m, "MessageFrame")?;
 
-    // AddMessage(text [, r, g, b [, a]]) — binding 0x795590.
-    //
-    // The TEXT is `super::message_text` — an `lua_isstring` gate whose failure is a silent jump to
-    // this function's own epilogue, not a raise, and the same for a NULL coercion and for the
-    // empty string. Its doc carries the bytes and the reason it matters; the short version is that
-    // stock `ContainerFrame.lua` really does reach `AddMessage(nil, …)` on a full keyring, and
-    // taking a `String` here (which this did until 1751's fourth window) put a script-error dialog
-    // on a gesture the reference answers with a dead click.
-    //
-    // r/g/b are required **as a trio** (three presence checks ANDed at 0x7956xx); absent ⇒ hard
-    // 0xFFFFFFFF white. The fourth numeric is a real alpha, `lua_isnumber`-gated with a default of
-    // 1.0 (`795752: mov [ebp-0x18],0x3f800000`). **Deliberately NOT the same shape as the text:** a
-    // bad colour jumps to `0x79581c`, which still enqueues the line in opaque white. Only a bad
-    // text shows nothing.
-    //
-    // **The signature stops there, and the closure's arity is the enforcement.** The corpus's three
-    // blocked callers all pass a sixth argument they believe is a hold time; mlua hands us the
-    // first five and drops the rest, exactly as the real binding does by reading five stack slots.
-    // Adding a `holdTime` parameter here would make benilla show those messages for a duration no
-    // 1.12 client ever showed them for.
+    // AddMessage(text [, r, g, b [, a]]) (`0x795590`). An unusable text is a silent no-op
+    // ([`super::message_text`]). r, g and b count only as a trio, else white, and a bad colour
+    // still adds the line in white (`0x79581c`); the alpha defaults to 1.0 (`0x795752`). The
+    // closure's arity drops a sixth argument, as the binding reads five: addons that pass a hold
+    // time there get the frame's `displayDuration`, as on the reference.
     m.set(
         "AddMessage",
         lua.create_function(
@@ -103,9 +69,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 } else {
                     (1.0, 1.0, 1.0)
                 };
-                // Alpha only counts when rgb came with it — the client reads arg 5 off the same
-                // parse that required the trio, and a lone `AddMessage(text, nil, nil, nil, 0.5)`
-                // has no colour to apply it to.
+                // The alpha counts only with the trio, read in the same parse.
                 let a = match (&a, has_rgb) {
                     (Value::Number(_) | Value::Integer(_), true) => num_f32(&a),
                     _ => 1.0,
@@ -120,9 +84,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, this: Table| with_mf(lua, &this, MessageFrameState::clear))?,
     )?;
 
-    // SetInsertMode("TOP"|"BOTTOM") / GetInsertMode — 0x794ed0 / 0x794ff0, THIS CLASS ONLY. The
-    // client compares the string against "BOTTOM" (0x871404) and stores `streq-BOTTOM`, so anything
-    // that is not literally BOTTOM lands on TOP; the ctor default is 1 = BOTTOM.
+    // SetInsertMode (`0x794ed0`) compares against "BOTTOM" (`0x871404`), so anything else is
+    // TOP; the ctor default is BOTTOM.
     m.set(
         "SetInsertMode",
         lua.create_function(|lua, (this, mode): (Table, Value)| {
@@ -134,8 +97,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                         InsertMode::Top
                     }
                 }
-                // A non-string argument fails the streq and therefore reads as TOP, like the
-                // client's own comparison against a string it never got.
+                // A non-string fails the compare too.
                 _ => InsertMode::Top,
             };
             with_mf(lua, &this, |mf| mf.insert_mode = mode)
@@ -151,8 +113,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The fade trio — the same names and the same field the scrolling class exposes (the XML attr
-    // is `displayDuration`, the Lua accessors call it `TimeVisible`), over this class's own state.
+    // The fade accessors, as on the scrolling class; XML's `displayDuration` is `TimeVisible`.
     m.set(
         "SetFading",
         lua.create_function(|lua, (this, on): (Table, Value)| {
@@ -160,8 +121,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             with_mf(lua, &this, |mf| mf.fading_enabled = on)
         })?,
     )?;
-    // 1/nil, the reference's predicate shape (`0x795170`): `(nil) | (number)`, like every other
-    // 1.12 predicate (decision 2118).
+    // 1 or nil, the 1.12 predicate shape (`0x795170`).
     m.set(
         "GetFading",
         lua.create_function(|lua, this: Table| {
@@ -192,19 +152,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── the shared font block ───────────────────────────────────────────────────────────────
-    //
-    // `Set/GetFontObject · Set/GetFont · Set/GetTextColor · Set/GetShadowColor ·
-    // Set/GetShadowOffset` are real entries on this class's table, not a courtesy. The
-    // registrar map is explicit about the membership — *"Exposed on: FontString, Font object,
-    // EditBox, MessageFrame, ScrollingMessageFrame, SimpleHTML. NOT on Button"* (table
-    // `0x879d00` has none) — and names this class's own shims calling the shared
-    // implementations (`GetShadowColor 0x794810`). All six carry the block now —
-    // `SimpleHTML`'s is its own copy rather than `font_block::install`'s
-    // (`script/simplehtml/mod.rs`), because that class computes its own inter-block step.
-    //
-    // Demand is observed, not counted: `BigWigs/Plugins/Messages.lua:212` is
-    // `self.msgframe:SetFontObject(GameFontNormalLarge)` on a frame it has just given
-    // `SetInsertMode("TOP")`, and BigWigs dies there every session.
+    // The ten font verbs are on this class's own table (`GetShadowColor` `0x794810`), as on
+    // FontString, Font, EditBox, ScrollingMessageFrame and SimpleHTML; Button's (`0x879d00`) has
+    // none.
     crate::script::font_block::install(
         lua,
         &m,
@@ -224,10 +174,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 mod tests {
     use crate::script::UiScript;
 
-    /// How many display lines a named message frame holds. Read off the state rather than through
-    /// Lua on purpose: `GetNumMessages` is a **ScrollingMessageFrame** binding, and inventing one
-    /// on this class to make its tests convenient is exactly the drift these tests are pinning
-    /// against.
+    /// A named frame's line count, off the state: `GetNumMessages` is not a MessageFrame method.
     fn num_messages(s: &UiScript, name: &str) -> usize {
         let m = s.model_ref();
         let h = m.arena.lookup(name).expect("named frame");
@@ -237,23 +184,18 @@ mod tests {
             .map_or(0, |l| l.len())
     }
 
-    /// The whole point of the arity, pinned: the sixth argument three corpus addons pass is a hold
-    /// time the real client never had, and it must change **nothing**. The frame's own
-    /// `displayDuration` is what governs, so the message with a "hold time" of 999 fades on exactly
-    /// the same tick as the one without.
+    /// A sixth argument, which some addons pass as a hold time, changes nothing.
     #[test]
     fn the_sixth_addmessage_argument_is_ignored_not_a_holdtime() {
         let mut s = UiScript::new().unwrap();
         s.run("CreateFrame('MessageFrame', 'MF')").unwrap();
         s.run("MF:SetTimeVisible(1)").unwrap();
         s.run("MF:SetFadeDuration(0)").unwrap();
-        // The exact shape of EasyCopy.lua:12 / QuestItem.lua:300 / QuestHistory.lua:1678.
         s.run("MF:AddMessage('held', 1.0, 1.0, 1.0, 1.0, 999)")
             .unwrap();
         s.run("MF:AddMessage('plain', 1.0, 1.0, 1.0, 1.0)").unwrap();
         assert_eq!(num_messages(&s, "MF"), 2);
-        // Past timeVisible with no ramp: both retire together. A honoured holdTime would keep the
-        // first alive here, which is exactly the divergence this test exists to catch.
+        // Past timeVisible with no ramp, both retire together.
         s.tick(1.1);
         s.tick(0.1);
         assert_eq!(
@@ -263,31 +205,19 @@ mod tests {
         );
     }
 
-    /// **A text `AddMessage` cannot use is swallowed whole — silently, with nothing added and
-    /// nothing raised** (`0x795590`'s three jumps to its own epilogue; see [`super::super`]'s
-    /// `message_text`).
-    ///
-    /// The defect this pins is not hypothetical and not ours to have guessed at: our binding took
-    /// its text as an mlua `String`, which raises on nil, and 1.12's own `ContainerFrame.lua:753`
-    /// reports a full keyring through `UIErrorsFrame:AddMessage(NO_EMPTY_KEYRING_SLOTS, …)` — a
-    /// GlobalString the shipped `GlobalStrings.lua` never defines. So dropping a key onto a full
-    /// keyring put a script-error dialog on screen where the reference gives a dead click. It
-    /// surfaced the moment 1751's third window made the bag bar the reference's own file.
-    ///
-    /// The three silent cases and the two that are NOT silent are pinned together, because the
-    /// pair is the finding: a bad **colour** still adds the line (opaque white), and the receiver
-    /// guards still raise. Reading the text gate as a general argument law is exactly 1717's error.
+    /// Only an unusable text is silent (`0x795590` jumps to its epilogue): a bad colour still adds
+    /// the line, and the receiver check still raises.
     #[test]
     fn addmessage_swallows_a_text_it_cannot_use_and_only_the_text() {
         let s = UiScript::new().unwrap();
         s.run("CreateFrame('MessageFrame', 'MF')").unwrap();
 
-        // `lua_isstring 0x6f3510` accepts tags 4 and 3 only — everything else jumps to 0x79582b.
+        // `lua_isstring` (`0x6f3510`) passes strings and numbers only; the rest jump to `0x79582b`.
         for bad in ["nil", "", "true", "{}", "print"] {
             s.run(&format!("MF:AddMessage({bad})"))
                 .unwrap_or_else(|e| panic!("AddMessage({bad}) must not raise: {e}"));
         }
-        // …and so does the empty string, on its own `cmp byte ptr [ebx],0` at 0x79564b.
+        // The empty string has its own check (`0x79564b`).
         s.run("MF:AddMessage('')").unwrap();
         assert_eq!(
             num_messages(&s, "MF"),
@@ -295,14 +225,12 @@ mod tests {
             "nil, absent, boolean, table, function and \"\" each add NOTHING"
         );
 
-        // A number IS a usable text — tag 3 passes the gate and `0x6f7c80` retags the slot in
-        // place, so it renders as its decimal form.
+        // A number is a text, retagged in place (`0x6f7c80`).
         s.run("MF:AddMessage(42)").unwrap();
         assert_eq!(num_messages(&s, "MF"), 1, "a number is a text");
 
-        // The colour arguments are the OPPOSITE shape and that is the load-bearing negative: a bad
-        // r/g/b jumps to 0x79581c, which still enqueues with the 0xffffffff white staged at
-        // 0x795658. Suppressing the line here would be the same over-generalisation in reverse.
+        // A bad colour jumps to `0x79581c`, which still adds the line in the white staged at
+        // `0x795658`.
         s.run("MF:AddMessage('kept', {}, nil, 'x')").unwrap();
         assert_eq!(
             num_messages(&s, "MF"),
@@ -310,16 +238,13 @@ mod tests {
             "a bad colour still adds the line"
         );
 
-        // The receiver guards are upstream of all of it and DO raise (0x847ef8 — "used '.' instead
-        // of ':'").
+        // The receiver check still raises (`0x847ef8`).
         assert!(
             s.run("MF.AddMessage('dot')").is_err(),
             "a '.'-instead-of-':' call still raises"
         );
     }
 
-    /// `SetInsertMode` is a MessageFrame method and **only** a MessageFrame method — a plain Frame
-    /// and a ScrollingMessageFrame both resolve it to nil, which is what a duck-typing addon reads.
     #[test]
     fn set_insert_mode_is_messageframe_only() {
         let s = UiScript::new().unwrap();
@@ -344,7 +269,6 @@ mod tests {
             "nil",
             "the scrolling class has no SetInsertMode binding at all"
         );
-        // Default BOTTOM (ctor 1), and the round trip.
         assert_eq!(
             s.eval::<String>("return MF:GetInsertMode()").unwrap(),
             "BOTTOM"
@@ -356,9 +280,7 @@ mod tests {
         );
     }
 
-    /// The two `AddMessage`s are different functions, and the observable tell is the fifth argument:
-    /// on a MessageFrame it is alpha (0.5 ⇒ a half-transparent line), on a ScrollingMessageFrame it
-    /// is an id and the line stays opaque.
+    /// The fifth argument is alpha on a MessageFrame and an id on a ScrollingMessageFrame.
     #[test]
     fn messageframe_addmessage_is_not_the_scrolling_ones() {
         let s = UiScript::new().unwrap();
@@ -398,8 +320,6 @@ mod tests {
         );
     }
 
-    /// `insertMode` decides which edge the stack grows from: TOP hangs the newest message off the
-    /// frame's top, BOTTOM (the default) stacks up from its bottom. Same three messages, mirrored.
     #[test]
     fn insert_mode_picks_the_growth_edge() {
         let bands = |mode: &str| {
@@ -450,8 +370,7 @@ mod tests {
         );
     }
 
-    /// The class has no `maxLines` — its cap is what fits vertically, applied at the tick. A frame
-    /// 3 rows tall holds 3 messages however many arrive.
+    /// No `maxLines`: the cap is what fits vertically, applied at the tick.
     #[test]
     fn the_cap_is_what_fits_vertically() {
         let mut s = UiScript::new().unwrap();
@@ -470,7 +389,6 @@ mod tests {
         s.resolve();
         s.tick(0.1);
         assert_eq!(num_messages(&s, "MF"), 3, "42px / 14px pitch = 3 rows");
-        // ...and it is the OLDEST that went.
         s.resolve();
         let texts: Vec<String> = s
             .extract()
@@ -483,8 +401,7 @@ mod tests {
         assert!(texts.contains(&"m8".to_string()) && !texts.contains(&"m0".to_string()));
     }
 
-    /// A faded line on this class is **freed**, not left blank holding its rows — the difference
-    /// from the scrolling class, whose ring slots persist. `Clear` is the immediate form.
+    /// A faded line is freed, where the scrolling class keeps its rows.
     #[test]
     fn a_finished_line_is_retired_and_clear_empties_now() {
         let mut s = UiScript::new().unwrap();
@@ -505,8 +422,7 @@ mod tests {
         assert_eq!(num_messages(&s, "MF"), 0);
     }
 
-    /// The ctor defaults (`0x81cc2c`/`0x81cc30`: timeVisible, fadeDuration), plus the setters'
-    /// round trip.
+    /// The ctor defaults: timeVisible (`0x81cc2c`) and fadeDuration (`0x81cc30`).
     #[test]
     fn ctor_defaults_and_the_fade_accessors() {
         let s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/messageframe/scrolling.rs b/crates/benilla-ui/src/script/messageframe/scrolling.rs
index 7d99d192..6060f4c1 100644
--- a/crates/benilla-ui/src/script/messageframe/scrolling.rs
+++ b/crates/benilla-ui/src/script/messageframe/scrolling.rs
@@ -1,22 +1,8 @@
-//! The `ScrollingMessageFrame` method surface — the chat window's per-kind widget behavior
-//! (`CSimpleMessageScrollFrame`, ctor `0x787670`).
-//!
-//! A **true ring** of `maxLines` (drop-oldest, `SetMaxLines` destructive),
-//! `AddMessage(text[,r,g,b[,id]])` with the `trunc(x*255+0.5)` color quantization + forced-opaque
-//! alpha, per-line fade snapshots ticked only while **AtBottom** (scrolled up freezes every alpha),
-//! 1-slot scrollback, and — the other half of that fade — **every scroll entry re-arming the
-//! displayed lines** (`0x788b80` direct when the scroll is refused at an end, `0x788af0` via the
-//! relayout when it moves), which is what brings a faded-out chat back. The heavy lifting
-//! (the ring, the fade phases, the scroll clamps) lives on [`ScrollingMessageState`]
-//! (`crate::widget`), unit-tested there; this module is the thin Lua binding over it, plus the
-//! host-facing [`UiScript::add_chat_message`]/fade advance the app drives.
-//!
-//! The methods live in their own registry table, consulted by the frame `__index` dispatcher only
-//! for ScrollingMessageFrame frames — so duck-typing addons (`if frame.AddMessage then …`) see `nil`
-//! on every other kind, exactly as against the client's per-class method sets. **Its sibling class
-//! `MessageFrame` has its own table next door** ([`super::plain`]) carrying a *different*
-//! `AddMessage`: merging the two would hand a chat frame a `SetInsertMode` it does not have, and a
-//! MessageFrame an id argument where its alpha belongs.
+//! The `ScrollingMessageFrame` methods over [`ScrollingMessageState`]: `CSimpleMessageScrollFrame`
+//! (ctor `0x787670`), the chat window's class. A ring of `maxLines` that drops the oldest, colours
+//! quantized `trunc(x*255+0.5)` with alpha forced opaque, a fade that ticks only at the bottom, and
+//! every scroll call re-arming the displayed lines' fade (`0x788b80` when refused at an end,
+//! `0x788af0` when it moves), which is what brings a faded chat back.
 
 use mlua::{Lua, Table, Value};
 
@@ -24,14 +10,12 @@ use crate::script::object::frame_handle_of;
 use crate::script::{Model, UiScript};
 use crate::widget::{KindState, ScrollingMessageState};
 
-/// Registry key of the ScrollingMessageFrame method table (the MAXCSTACK discipline: Lua-side root,
-/// named key).
+/// Registry key of the ScrollingMessageFrame method table (the MAXCSTACK discipline).
 pub(crate) const REG_SCROLLINGMESSAGEFRAME_METHODS: &str =
     "__benilla_scrollingmessageframe_methods";
 
-/// Run `f` over a frame's message-frame state under one short write borrow. Errors if `this` is not a
-/// live ScrollingMessageFrame (unreachable through the kind dispatcher, but the method table is a
-/// plain Lua value — a caller could fish it out and misapply it).
+/// Run `f` over a ScrollingMessageFrame's state under one short borrow; any other frame, reachable
+/// only through a misapplied method table, is an error.
 fn with_smf<T>(
     lua: &Lua,
     this: &Table,
@@ -49,9 +33,7 @@ fn with_smf<T>(
     }
 }
 
-/// `lua_isnumber` semantics — a number, or a string Lua would coerce to one. The rgb trio's
-/// presence test is three of these (decision 2125), so a caller passing `"1"` still colours the
-/// line and a caller passing `nil` or a table does not.
+/// `lua_isnumber`: a number or a numeric string. The rgb presence test is three of these.
 fn is_number(v: &Value) -> bool {
     match v {
         Value::Integer(_) | Value::Number(_) => true,
@@ -60,7 +42,7 @@ fn is_number(v: &Value) -> bool {
     }
 }
 
-/// A Lua number-ish → f32 (nil/other → 0.0), for the color args.
+/// A colour argument as f32, 0 for anything but a number.
 fn num_f32(v: &Value) -> f32 {
     match v {
         Value::Number(n) => *n as f32,
@@ -69,12 +51,8 @@ fn num_f32(v: &Value) -> f32 {
     }
 }
 
-/// Run a scroll entry over a frame's state with the viewport's row budget in hand.
-///
-/// Every scroll method needs it, not just the pages: each one re-arms the **displayed** lines'
-/// fade ([`ScrollingMessageState::reset_all_fade_times`]), and which lines those are depends on the
-/// row budget. It comes from the frame's last resolved rect at the ring font's pitch (the
-/// font-height line-step law, the emit pass's basis); an unresolved frame reads as one row.
+/// Run a scroll call with the viewport's row count, which every scroll needs: each re-arms the
+/// fade of the lines on display ([`ScrollingMessageState::reset_all_fade_times`]).
 fn scroll(
     lua: &Lua,
     this: &Table,
@@ -99,27 +77,16 @@ fn scroll(
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let m = lua.create_table()?;
 
-    // The justify quartet, shared with the sibling class — see [`super::install_justify`] for the
-    // method-table bytes that put all four on BOTH tables.
+    // The justify quartet, on both classes ([`super::install_justify`]).
     super::install_justify(lua, &m, "ScrollingMessageFrame")?;
 
-    // AddMessage(text [, r, g, b [, id]]) — binding 0x792900. rgb absent ⇒ white; the state
-    // quantizes round-half-up and forces the line opaque, then the fade drives its alpha.
-    //
-    // **The rgb gate is three separate `lua_isnumber` calls on indices 3/4/5, and the id's index
-    // is LEG-DEPENDENT** (decision 2125): 6 when rgb are
-    // present (`0x792b13 mov edx,6`), **3** when they are absent (`0x792b48 mov edx,3`) — which is
-    // what makes the documented `AddMessage(text, id)` shorthand work. So `AceConsole-2.0`'s
-    // `AddMessage(text, nil, nil, nil, nil, 5)` fails the R gate at index 3, takes the absent leg,
-    // re-reads index 3 as the id — still nil — and stores **0**; its trailing `5` sits at index 7
-    // and is never read at all.
-    //
-    // Absent or non-numeric is id 0, and 0 is a line `UpdateColorByID` can never find: that guard
-    // is the reference's own, at `0x788250`'s first branch.
-    //
-    // The TEXT gate is the sibling class's, verbatim — gate `0x79299c`, `je 0x792b81` = this
-    // function's own epilogue — so `DEFAULT_CHAT_FRAME:AddMessage(nil)` is silent too. See
-    // `super::message_text`.
+    // AddMessage(text [, r, g, b [, id]]) (`0x792900`): white without rgb; the state quantizes
+    // the colour and makes the line opaque. The rgb test is three `lua_isnumber` checks; the id
+    // is stack index 6 when they pass (`0x792b13`) and index 3, `r`'s, when they fail
+    // (`0x792b48`), which makes `AddMessage(text, id)` work and gives
+    // `AddMessage(text, nil, nil, nil, nil, 5)` id 0. A missing id is 0, which `UpdateColorByID`
+    // never matches (`0x788250`). The text gate (`0x79299c`) is the plain class's
+    // ([`super::message_text`]).
     m.set(
         "AddMessage",
         lua.create_function(
@@ -128,10 +95,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     return Ok(());
                 };
                 let has_rgb = is_number(&r) && is_number(&g) && is_number(&b);
-                // The id is the chat-type index (`GetChatTypeIndex`) the line is printed under —
-                // `ChatFrame.lua` passes `info.id` — read from the leg's OWN stack slot: the
-                // sixth argument when rgb are present, the third (i.e. where `r` would be) when
-                // they are not.
+                // The chat-type index (`ChatFrame.lua` passes `info.id`), stack index 6 or 3.
                 let id = match if has_rgb { &id } else { &r } {
                     Value::Integer(i) => u32::try_from(*i).unwrap_or(0),
                     Value::Number(n) if n.is_finite() && *n >= 0.0 => *n as u32,
@@ -147,9 +111,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?,
     )?;
 
-    // UpdateColorByID(id, r, g, b) — `0x7932b0`. `ChatFrame_OnEvent`'s UPDATE_CHAT_COLOR arm
-    // calls it with the type's index and the event's floats so the lines already in the
-    // window take the new colour; lines printed under another id are untouched.
+    // UpdateColorByID(id, r, g, b) (`0x7932b0`) recolours the lines printed under `id`; stock
+    // `ChatFrame_OnEvent` calls it on `UPDATE_CHAT_COLOR`.
     m.set(
         "UpdateColorByID",
         lua.create_function(
@@ -214,7 +177,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, this: Table| with_smf(lua, &this, |smf| smf.at_bottom()))?,
     )?;
 
-    // SetMaxLines is destructive (`0x7938a0`) — the state handles the wipe.
+    // SetMaxLines wipes the ring (`0x7938a0`).
     m.set(
         "SetMaxLines",
         lua.create_function(|lua, (this, n): (Table, i64)| {
@@ -237,8 +200,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             with_smf(lua, &this, |smf| smf.fading_enabled = on)
         })?,
     )?;
-    // 1/nil, the reference's predicate shape (`0x793a40`): `(nil) | (number)`, like every other
-    // 1.12 predicate (decision 2118).
+    // 1 or nil, the 1.12 predicate shape (`0x793a40`).
     m.set(
         "GetFading",
         lua.create_function(|lua, this: Table| {
@@ -247,8 +209,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             })
         })?,
     )?;
-    // The XML attr is `displayDuration`; the Lua accessors call the same field `TimeVisible`
-    // (`0x788090`).
+    // XML's `displayDuration` is the Lua `TimeVisible` (`0x788090`).
     m.set(
         "SetTimeVisible",
         lua.create_function(|lua, (this, s): (Table, f32)| {
@@ -271,19 +232,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── the shared font block ───────────────────────────────────────────────────────────────
-    //
-    // `Set/GetFontObject · Set/GetFont · Set/GetTextColor · Set/GetShadowColor ·
-    // Set/GetShadowOffset` are real entries on this class's table, not a courtesy. The
-    // registrar map is explicit about the membership — *"Exposed on: FontString, Font object,
-    // EditBox, MessageFrame, ScrollingMessageFrame, SimpleHTML. NOT on Button"* (table
-    // `0x879d00` has none) — and names this class's own shims calling the shared
-    // implementations (`GetShadowColor 0x792240`). All six carry the block now —
-    // `SimpleHTML`'s is its own copy rather than `font_block::install`'s
-    // (`script/simplehtml/mod.rs`), because that class computes its own inter-block step.
-    //
-    // Demand is observed, not counted: `BigWigs/Plugins/Messages.lua:212` is
-    // `self.msgframe:SetFontObject(GameFontNormalLarge)` on a frame it has just given
-    // `SetInsertMode("TOP")`, and BigWigs dies there every session.
+    // The ten font verbs are on this class's own table (`GetShadowColor` `0x792240`), as on
+    // FontString, Font, EditBox, MessageFrame and SimpleHTML; Button's (`0x879d00`) has none.
     crate::script::font_block::install(
         lua,
         &m,
@@ -297,12 +247,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 
     lua.set_named_registry_value(REG_SCROLLINGMESSAGEFRAME_METHODS, m)?;
 
-    // SubmitChatInput(text) — the chat input EditBox's OnEnterPressed hands the typed line here; it
-    // queues into the model for the app to parse into a chat command (the outbound Lua→app seam, the
-    // twin of loot's LootSlot). Empty/whitespace lines are queued as-is; the app treats them as a
-    // cancel. Not an EditBox method — a bare global, called with the line the handler read.
-    // BenillaChatTabPressed() — the chat edit box's OnTabPressed queues a flag the app's
-    // whisper-cycle system drains (UiScript::take_chat_tab), the SubmitChatInput pattern.
+    // BenillaChatTabPressed(): the chat edit box's OnTabPressed sets a flag for the app's whisper
+    // cycle (`UiScript::take_chat_tab`).
     lua.globals().set(
         "BenillaChatTabPressed",
         lua.create_function(|lua, ()| {
@@ -311,6 +257,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
+    // SubmitChatInput(text): the chat edit box's OnEnterPressed queues the line for the app to
+    // parse as a chat command; an empty line is queued too, and the app takes it as a cancel.
     lua.globals().set(
         "SubmitChatInput",
         lua.create_function(|lua, text: Option<String>| {
@@ -341,7 +289,6 @@ mod tests {
             let (t, r, g, b) = white(&format!("line {n}"));
             s.add(t, r, g, b);
         }
-        // Only the last 3 survive, oldest→newest.
         assert_eq!(s.lines.len(), 3);
         let texts: Vec<&str> = s.lines.iter().map(|l| l.text.as_str()).collect();
         assert_eq!(texts, ["line 2", "line 3", "line 4"]);
@@ -363,10 +310,10 @@ mod tests {
     #[test]
     fn color_is_quantized_round_half_up() {
         let mut s = ScrollingMessageState::default();
-        // 0.5*255 = 127.5 → +0.5 → 128.0 → trunc 128 (round-half-up); 1.0 → 255; clamp past 1.0.
+        // trunc(0.5 * 255 + 0.5) = 128; 1.0 is 255, and past 1.0 clamps.
         s.add("q".into(), 0.5, 1.0, 2.0);
         assert_eq!(s.lines[0].color, [128, 255, 255]);
-        // FF8040 (EMOTE) from 1.0, 0.5019.., 0.2509.. → 255,128,64 (spot the table's byte round-trip).
+        // EMOTE's FF8040 survives the byte round trip.
         s.add("e".into(), 1.0, 128.0 / 255.0, 64.0 / 255.0);
         assert_eq!(s.lines[1].color, [255, 128, 64]);
     }
@@ -382,7 +329,7 @@ mod tests {
         // Phase 1: full alpha while timeVisible remains.
         s.tick(0.5);
         assert_eq!(s.lines[0].alpha, 1.0);
-        // Cross into phase 2: 0.5 more spends the last of timeVisible; next ticks ramp fadeDuration.
+        // 0.5 more spends timeVisible; the ticks after ramp over fadeDuration.
         s.tick(0.5);
         assert_eq!(s.lines[0].alpha, 1.0, "phase 1 just expired, ramp not yet");
         s.tick(1.0); // fade_left 2.0 → 1.0 → alpha = trunc(1.0/2.0*255)/255 = 127/255
@@ -399,15 +346,13 @@ mod tests {
             ..Default::default()
         };
         s.add("x".into(), 1.0, 1.0, 1.0);
-        s.tick(0.6); // spends timeVisible (per-tick phase check: still full this tick)
+        s.tick(0.6); // spends timeVisible, still full this tick
         assert_eq!(s.lines[0].alpha, 1.0);
-        s.tick(0.1); // now past phase 1, no ramp ⇒ straight to 0
+        s.tick(0.1); // past phase 1 with no ramp: straight to 0
         assert_eq!(s.lines[0].alpha, 0.0);
     }
 
-    /// The tick's AtBottom gate, isolated from the scroll re-arm that now sits next to it: with a
-    /// one-row viewport only the newest displayed line is re-armed, so the two lines either side of
-    /// it are the ones that show the freeze.
+    /// With a one-row viewport the scroll re-arms one line; the lines either side show the freeze.
     #[test]
     fn scrolled_up_freezes_the_fade() {
         let mut s = ScrollingMessageState {
@@ -422,8 +367,7 @@ mod tests {
         s.tick(2.0); // half-way down the ramp: trunc(2.0/4.0*255) = 127
         let half = 127.0 / 255.0;
         assert_eq!(s.lines[0].alpha, half);
-        // Scroll up one line — no longer AtBottom, so ticks must not advance any alpha. The line
-        // that lands in the one-row viewport (l1) is re-armed by the scroll; l0 and l2 are not.
+        // Scrolled up, ticks stop; the scroll re-arms only l1, the line now in view.
         s.scroll_up(1);
         assert!(!s.at_bottom());
         assert_eq!(s.lines[1].alpha, 1.0, "the displayed line was re-armed");
@@ -431,15 +375,14 @@ mod tests {
         assert_eq!(s.lines[0].alpha, half, "frozen while scrolled up");
         assert_eq!(s.lines[2].alpha, half);
         assert_eq!(s.lines[1].alpha, 1.0);
-        // Back to bottom → the fade resumes (from the re-arm this scroll performs).
+        // Back at the bottom, the fade resumes.
         s.scroll_to_bottom(1);
         s.tick(2.0);
         assert!(s.lines[2].alpha < 1.0);
     }
 
-    /// **The director's bug (2026-08-29): a fully-faded chat could never be brought back.** Every
-    /// scroll entry re-arms the displayed lines — including the ones that move no cursor at all,
-    /// which is what clicking the arrows on an already-at-bottom chat does.
+    /// Every scroll call re-arms the displayed lines, even one that moves no cursor, as clicking
+    /// the arrows on a chat already at the bottom does.
     #[test]
     fn any_scroll_brings_faded_lines_back() {
         let armed = |op: fn(&mut ScrollingMessageState, usize)| {
@@ -453,7 +396,7 @@ mod tests {
                 s.add(format!("l{n}"), 1.0, 1.0, 1.0);
             }
             s.tick(1.5); // spend phase 1
-            s.tick(1.5); // spend phase 2 — everything is gone
+            s.tick(1.5); // spend phase 2: all gone
             assert!(s.lines.iter().all(|l| l.alpha == 0.0), "faded out first");
             op(&mut s, 8);
             s
@@ -470,8 +413,7 @@ mod tests {
             ("PageDown", ScrollingMessageState::page_down),
         ] {
             let s = armed(op);
-            // Whatever the op left in view is what the engine re-arms — `ScrollUp` carries the
-            // newest line off the bottom of the viewport, so the set is the op's, not the ring.
+            // The re-armed set is what the op left in view, not the whole ring.
             let shown = s.displayed_range(8);
             assert!(!shown.is_empty(), "{name} displayed nothing");
             for i in shown {
@@ -483,8 +425,7 @@ mod tests {
         }
     }
 
-    /// `0x788b80` walks the display vector, not the ring: a line scrolled out of view keeps
-    /// whatever fade state it had.
+    /// `0x788b80` walks the lines on display, not the ring.
     #[test]
     fn the_re_arm_reaches_only_the_displayed_lines() {
         let mut s = ScrollingMessageState {
@@ -514,7 +455,7 @@ mod tests {
             s.add(format!("l{n}"), 1.0, 1.0, 1.0);
         }
         assert!(s.at_bottom());
-        s.scroll_down(8); // already at bottom — no cursor move
+        s.scroll_down(8); // already at the bottom: no move
         assert!(s.at_bottom());
         // 3 lines → max_scroll = 2; scroll past it clamps.
         for _ in 0..10 {
@@ -537,7 +478,7 @@ mod tests {
         }
         s.scroll_up(8); // viewing one line back (bottom row = l2)
         let off = s.scroll_offset;
-        s.add("l4".into(), 1.0, 1.0, 1.0); // a new line arrives at the bottom
+        s.add("l4".into(), 1.0, 1.0, 1.0);
         assert_eq!(
             s.scroll_offset,
             off + 1,
@@ -554,14 +495,12 @@ mod tests {
         for n in 0..3 {
             s.add(format!("l{n}"), 1.0, 1.0, 1.0);
         }
-        // Middle line wraps into 3 rows.
         s.lines[1].rows = 3;
-        // Viewport of 4 rows from the bottom: newest (1 row) + middle (3 rows) fill it exactly —
-        // the oldest is off the top. A partially-fitting message counts (it draws, clipped).
+        // 4 rows: the newest (1) and the middle (3) fill it; a partly fitting message counts.
         assert_eq!(s.displayed_count(4), 2);
         assert_eq!(s.displayed_count(3), 2, "partial middle line still counts");
         assert_eq!(s.displayed_count(1), 1);
-        // Page = displayed − 1 (one message of overlap), never 0.
+        // A page is displayed − 1, one message of overlap, never 0.
         s.page_up(4);
         assert_eq!(s.scroll_offset, 1);
         s.page_up(1); // displayed 1 → page clamps to 1 message
@@ -587,11 +526,9 @@ mod tests {
         s.run("CF:AddMessage('wrapped', 1, 1, 1)").unwrap();
         s.run("CF:AddMessage('new', 1, 1, 1)").unwrap();
         s.resolve();
-        // The measure round-trip: every fresh line requests its row count at the resolved width.
         let reqs = s.message_lines_needing_measure();
         assert_eq!(reqs.len(), 3);
         assert!(reqs.iter().all(|r| (r.wrap_width - 430.0).abs() < 0.5));
-        // Host answers: the middle line wraps to 2 rows.
         let answers: Vec<(u32, u32, u16, u64)> = reqs
             .iter()
             .map(|r| (r.frame, r.index, if r.index == 1 { 2 } else { 1 }, r.key))
@@ -601,9 +538,8 @@ mod tests {
             s.message_lines_needing_measure().is_empty(),
             "answered keys satisfy the cache"
         );
-        // Default font (no FontString child) ⇒ pitch 14. Frame [90, 124): 'new' band [90,104),
-        // 'wrapped' 2-row band [104,132) — starts inside, overflows the top, still emitted
-        // (clipped); 'old' would start at 132 ≥ 124 — not emitted.
+        // Default font, pitch 14. Frame [90, 124): 'new' is [90, 104), 'wrapped' [104, 132)
+        // overflows and draws clipped, and 'old' would start at 132, outside, so does not draw.
         let quads = s.extract();
         let texts: Vec<(String, f32, f32)> = quads
             .iter()
@@ -623,7 +559,6 @@ mod tests {
         assert!((texts[0].1 - 90.0).abs() < 0.01 && (texts[0].2 - 104.0).abs() < 0.01);
         assert_eq!(texts[1].0, "wrapped");
         assert!((texts[1].1 - 104.0).abs() < 0.01 && (texts[1].2 - 132.0).abs() < 0.01);
-        // Both clip to the frame rect, so the overflow never inks outside it.
         let clip = quads
             .iter()
             .find_map(|q| match &q.content {
@@ -634,10 +569,8 @@ mod tests {
         assert!((clip.top - 124.0).abs() < 0.01 && (clip.bottom - 90.0).abs() < 0.01);
     }
 
-    /// The ring lines are the frame's ARTWORK content, not its bare draw slot: a BACKGROUND
-    /// texture of the same frame draws BEHIND them, an OVERLAY one in front. The chat window's
-    /// hover box is that background texture — at the bare slot it painted over the messages and
-    /// dimmed them (director, 2026-07-26).
+    /// The lines draw at the frame's ARTWORK layer: a BACKGROUND texture, such as the chat
+    /// window's hover box, behind them, an OVERLAY one in front.
     #[test]
     fn ring_lines_draw_above_the_frames_background_and_below_its_overlay() {
         let mut s = UiScript::new().unwrap();
@@ -732,7 +665,7 @@ mod tests {
         )
         .unwrap();
         s.run("CF:AddMessage('doomed', 1, 1, 1)").unwrap();
-        // Two ticks retire 'doomed' (phase-1 spend, then the no-ramp snap), then fresh lines land.
+        // Two ticks retire 'doomed' (phase 1, then the snap with no ramp); then fresh lines land.
         s.tick(0.1);
         s.tick(0.1);
         s.run("CF:SetTimeVisible(120)").unwrap();
@@ -749,8 +682,7 @@ mod tests {
                 _ => None,
             })
             .collect();
-        // 'doomed' draws nothing but its band (the oldest, topmost) still holds its place: the two
-        // live lines sit at the two bottom bands, nothing re-packs into the faded slot.
+        // 'doomed' draws nothing but keeps its band at the top; the live lines hold the bottom two.
         assert_eq!(texts.len(), 2);
         assert_eq!(texts[0].0, "b");
         assert!((texts[0].1 - 0.0).abs() < 0.01);
@@ -774,7 +706,6 @@ mod tests {
         .unwrap();
         s.run("CF:AddMessage('x', 1, 1, 1)").unwrap();
         s.resolve();
-        // Find the frame handle the extract loop would hand the app (the message line's target).
         let fh = s
             .extract()
             .iter()
@@ -786,8 +717,8 @@ mod tests {
                 _ => None,
             })
             .expect("the ring line extracts");
-        // The app feeds a span (y-up rect) covering [10..60]x[20..34]; a release inside fires the
-        // handler with (link, markup, button); one outside does not.
+        // The app feeds a span (a y-up rect) over [10..60]x[20..34]; a release inside fires the
+        // handler with (link, markup, button), one outside does not.
         s.set_link_spans(vec![(
             fh,
             crate::layout::Rect::new(20.0, 10.0, 34.0, 60.0),
@@ -826,14 +757,8 @@ mod tests {
         assert!(!s.add_chat_message("PlainFrame", "x", 1.0, 1.0, 1.0));
     }
 
-    /// **`AddMessage`'s id lives at a different stack index on each leg** (decision 2125): the
-    /// sixth argument when r,g,b are present, the THIRD when they are not — which is what makes
-    /// the `AddMessage(text, id)` shorthand work at all (`0x792b13 mov edx,6` /
-    /// `0x792b48 mov edx,3`).
-    ///
-    /// `AceConsole-2.0`'s `Print` is the case that matters: `AddMessage(text, nil, nil, nil, nil,
-    /// 5)` fails the R gate at index 3, takes the absent leg, re-reads index 3 as the id — still
-    /// nil — and stores 0. Its trailing `5` sits at index 7 and is never read.
+    /// The id is stack index 6 with rgb and index 3 without (`0x792b13`, `0x792b48`), so
+    /// `AceConsole-2.0`'s `AddMessage(text, nil, nil, nil, nil, 5)` stores 0.
     #[test]
     fn the_addmessage_id_index_follows_the_rgb_leg() {
         let s = UiScript::new().unwrap();
@@ -856,8 +781,6 @@ mod tests {
         );
     }
 
-    /// `UpdateColorByID` recolours exactly the lines printed under that id — the stock
-    /// `ChatFrame_OnEvent` repaints a type's history when its colour changes, and nothing else.
     #[test]
     fn update_color_by_id_recolours_only_that_ids_lines() {
         let mut smf = ScrollingMessageState::default();
@@ -880,10 +803,8 @@ mod tests {
         assert_ne!(smf.lines_gen, gen, "a recolour is a redraw");
         assert_eq!(smf.update_color_by_id(11, 0.0, 0.5, 1.0), 0, "idempotent");
         assert_eq!(smf.update_color_by_id(99, 0.0, 0.0, 0.0), 0, "no such id");
-        // **Id 0 matches nothing** — `0x788250`'s own opening guard (decision 2125). Line "d" was
-        // printed with no id, so it carries 0; so does `ChatTypeInfo["REPLY"]`, which the
-        // `UPDATE_CHAT_COLOR` handler mirrors WHISPER into. Without the guard that pair repainted
-        // every colourless line in the window whisper-pink at every login.
+        // Id 0 matches nothing (`0x788250`). REPLY's chat type has id 0 and `UPDATE_CHAT_COLOR`
+        // mirrors WHISPER into it, so without the guard every id-less line turns whisper pink.
         assert_eq!(
             smf.update_color_by_id(0, 1.0, 0.5, 1.0),
             0,
@@ -895,7 +816,7 @@ mod tests {
             "the colourless line stays the frame's own colour"
         );
 
-        // And the Lua surface: the fifth argument tags, the method recolours, silently.
+        // Through Lua: argument 5 tags the line, and a bad id is silent.
         let s = UiScript::new().unwrap();
         s.run(
             "local f = CreateFrame('ScrollingMessageFrame') \
@@ -923,11 +844,8 @@ mod tests {
         assert_eq!(s.eval::<i64>("return CF:GetNumMessages()").unwrap(), 0);
     }
 
-    /// The W4 skip token: a settled message frame's sweep hashes ZERO lines (the counter is the
-    /// claim — 0735's counts rule), and each side of the token catches its own change class:
-    /// text through the generation, the resolved width through the environment hash. The token
-    /// is only stored by a zero-request sweep, so an UNANSWERED request keeps re-requesting —
-    /// the region ledger's own rule (1410), inherited.
+    /// A settled frame's sweep hashes no lines; a text change reopens it through the line
+    /// generation, a width change through the environment hash.
     #[test]
     fn a_settled_message_frame_hashes_no_lines_until_something_moves() {
         let mut s = UiScript::new().unwrap();
@@ -951,7 +869,7 @@ mod tests {
             again.iter().map(|r| (r.frame, r.index, 1, r.key)).collect();
         s.set_message_line_rows(&answers);
         assert!(s.message_lines_needing_measure().is_empty());
-        // Settled: the NEXT sweep must skip the frame whole — zero lines hashed.
+        // Settled: the next sweep skips the frame whole.
         let hashed_before = s.model_mut().msg_lines_hashed;
         assert!(s.message_lines_needing_measure().is_empty());
         assert_eq!(
@@ -959,7 +877,7 @@ mod tests {
             hashed_before,
             "a settled frame's sweep must hash no lines"
         );
-        // Text change reopens through the GENERATION…
+        // A text change reopens through the generation.
         s.run("CF:AddMessage('three', 1, 1, 1)").unwrap();
         let reqs = s.message_lines_needing_measure();
         assert_eq!(reqs.len(), 1, "the new line re-surfaces");
@@ -968,7 +886,7 @@ mod tests {
             reqs.iter().map(|r| (r.frame, r.index, 1, r.key)).collect();
         s.set_message_line_rows(&answers);
         assert!(s.message_lines_needing_measure().is_empty());
-        // …and a resolved-width change reopens through the ENVIRONMENT: every line re-keys.
+        // A width change reopens through the environment: every line re-keys.
         s.run("CF:SetWidth(300)").unwrap();
         s.resolve();
         let reqs = s.message_lines_needing_measure();
diff --git a/crates/benilla-ui/src/script/minimap.rs b/crates/benilla-ui/src/script/minimap.rs
index 6184740f..c43a4169 100644
--- a/crates/benilla-ui/src/script/minimap.rs
+++ b/crates/benilla-ui/src/script/minimap.rs
@@ -1,30 +1,7 @@
-//! The `Minimap` method surface — the zoom API the FrameXML zoom buttons drive
-//! (`MinimapZoomIn`/`MinimapZoomOut` → `Minimap:SetZoom(Minimap:GetZoom() ± 1)`).
-//!
-//! `get_zoom_levels` (`0x6da9a0`) returns the constant 6, `set_zoom` clamps at 5 and marks the tile
-//! grid dirty, and the zoom index feeds the zoom-to-scale tables (`0x6da9b0`). The engine core
-//! carries only the index
-//! ([`MinimapState`]); the app renderer maps it to a world radius and draws the tiles
-//! (decision 0203). The two model attrs (`minimapArrowModel=`/`minimapPlayerModel=`) are modeled
-//! only as far as the Lua surface can see them: [`apply_model_attrs`] names the nine engine
-//! children the ctor built, and the app still draws every arrow from its own art.
-//!
-//! **The ping** (decision 1596) is the same split, one rung further out: the two methods here are
-//! pure seam — `PingLocation` parks a click and `GetPingPosition` reads back what the app
-//! published — because the ping's only stored form is a WORLD point the app pins it to, and the
-//! engine core has no world. Nothing here holds the ping's position, its lifetime, or its art;
-//! putting any of that in Lua is what made the first attempt flaky.
-//!
-//! **The level persists** (decision 1131). The client keeps two halves: the live indices
-//! (`0x86f698` outdoor / `0x86f69c` indoor — our [`MinimapState`]) and the two CVar objects
-//! `minimapZoom`/`minimapInsideZoom` (both registered default `"3"`), which are what `Config.wtf`
-//! actually stores. `set_zoom` writes *both*; the minimap reset path (`0x6d9008`–`0x6d901f`)
-//! re-seeds the live index from the CVar's parsed int. benilla runs the same two halves at the same
-//! seam: `SetZoom` below writes the index and the CVar, and the app seeds the widget from the CVar
-//! table once, when the in-game UI materializes ([`super::UiScript::set_minimap_zoom`]).
-//!
-//! The methods live in their own registry table, consulted by the frame `__index` dispatcher only
-//! for Minimap frames — the same duck-typing posture as StatusBar's.
+//! The `Minimap` methods: zoom, the mask, the ping and the model attributes. The reference has six
+//! levels (`0x6da9a0`), a live index per mode (`0x86f698` outdoor, `0x86f69c` indoor) and the
+//! `minimapZoom`/`minimapInsideZoom` CVars (default `"3"`) that re-seed it (`0x6d9008`); the app
+//! maps the index to a radius (`0x6da9b0`) and holds the ping as a world point.
 
 use mlua::{Lua, Table};
 
@@ -32,12 +9,11 @@ use super::object::frame_handle_of;
 use super::Model;
 use crate::widget::{KindState, MinimapState, MINIMAP_ZOOM_LEVELS};
 
-/// Registry key of the Minimap method table (the MAXCSTACK discipline: Lua-side root, named key).
+/// Registry key of the Minimap method table.
 pub(super) const REG_MINIMAP_METHODS: &str = "__benilla_minimap_methods";
 
-/// Run `f` over a frame's Minimap state under one short write borrow. Errors if `this` is not a
-/// live Minimap (unreachable through the kind dispatcher, but the method table is a plain Lua
-/// value — a caller can fish it out and misapply it).
+/// Run `f` over a frame's Minimap state; errors on any other receiver, since the method table is
+/// a plain Lua value a caller can misapply.
 fn with_minimap<T>(
     lua: &Lua,
     this: &Table,
@@ -55,18 +31,9 @@ fn with_minimap<T>(
     }
 }
 
-/// `CMinimap::LoadXML 0x4ee2b0`'s model half: assign the two `<Minimap>` model attributes to the
-/// nine engine children the ctor already built. `minimapArrowModel` (engine default
-/// [`crate::widget::MINIMAP_DEFAULT_ARROW_MODEL`]) goes to children **1–8** via `0x4ee170`'s two loops
-/// (`0x4ee1b7` over the five at `+0x320`, `0x4ee204` over the three at `+0x314`);
-/// `minimapPlayerModel` (default [`crate::widget::MINIMAP_DEFAULT_PLAYER_MODEL`]) goes to child **9 alone**, via
-/// `0x4ee260`.
-///
-/// The split is what makes the nine *distinguishable* from Lua: without it `GetModel()` is `""` on
-/// all nine and nothing in the tuple says which one is the player arrow.
-///
-/// Runs before the `<Frames>` descent, because `0x4ee2b0` does its own work and only then chains to
-/// `CSimpleFrame::LoadXML 0x76a2f0`, which is what recurses into the children.
+/// The model half of `CMinimap::LoadXML` (`0x4ee2b0`): `minimapArrowModel` to engine children 1
+/// to 8 (`0x4ee170`), `minimapPlayerModel` to child 9 alone (`0x4ee260`). Runs before the
+/// `<Frames>` descent, as the reference chains to `CSimpleFrame::LoadXML` (`0x76a2f0`) after.
 pub(crate) fn apply_model_attrs(
     lua: &Lua,
     this: &Table,
@@ -102,26 +69,20 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 
     m.set(
         "GetZoom",
-        // Reads whichever index is live — the indoor one (`0x86f69c`) while inside a WMO, else the
-        // outdoor one (`0x86f698`). The client's `get_zoom_index` routes on the same flag.
+        // The indoor index while inside a WMO, else the outdoor one, as the reference routes.
         lua.create_function(|lua, this: Table| with_minimap(lua, &this, |m| m.active_zoom()))?,
     )?;
     m.set(
         "SetZoom",
         lua.create_function(|lua, (this, zoom): (Table, f64)| {
-            // The client's set_zoom clamps into [0, levels-1] (`0x6daa10`: clamp at 5). A negative
-            // or fractional Lua number truncates like lua_tonumber → int. It writes the index the
-            // inside flag selects, so the +/- buttons zoom the map you're actually looking at and
-            // each mode keeps its own level.
+            // Truncated and clamped to 0..=5 (`0x6daa10`), into the current mode's index.
             let clamped = (zoom.max(0.0) as u8).min(MINIMAP_ZOOM_LEVELS - 1);
             let inside = with_minimap(lua, &this, |m| {
                 m.set_active_zoom(clamped);
                 m.inside
             })?;
-            // …and it persists the level in the same breath: `set_zoom` writes the live index AND
-            // `CVar::Set`s the matching CVar (`minimapInsideZoom` indoors, `minimapZoom` out), which
-            // is the whole reason a zoom level survives a restart. The borrow above is released
-            // before this one — both reach the same `Model` app_data.
+            // The reference also sets the mode's CVar, which is what survives a restart. The borrow
+            // above is released first: both reach the same `Model`.
             super::cvars::set_from_engine(
                 &mut lua.app_data_mut::<Model>().expect("model app_data"),
                 if inside {
@@ -135,13 +96,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
     m.set(
-        // SetMaskTexture(path) — the disc's mask art. A real 1.12 method (the name is in the 5875
-        // image) with no getter beside it, so this is write-only from Lua, exactly as there.
-        //
-        // An absent or empty path restores the engine default rather than leaving the map
-        // unmasked: `SetMaskTexture` is how a UI replaces the circle, never how it removes one,
-        // and a nil-means-square reading would hand every mistyped path a square minimap with no
-        // error. (pfUI passes a real path; this is about the failure mode, not about pfUI.)
+        // The disc's mask art, write-only as in the reference. An absent or empty path restores
+        // the default circle rather than unmasking the map; what the reference's `0x4ee4a0` does
+        // with one is untraced.
         "SetMaskTexture",
         lua.create_function(|lua, (this, path): (Table, Option<String>)| {
             let path = path.filter(|p| !p.is_empty());
@@ -151,21 +108,14 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     m.set(
         "GetZoomLevels",
         lua.create_function(|lua, this: Table| {
-            // Validate the receiver like every kind method (the constant is per the client's
-            // `get_zoom_levels`, but a non-Minimap receiver is still a caller bug).
+            // The reference's constant, with the receiver still validated.
             with_minimap(lua, &this, |_| MINIMAP_ZOOM_LEVELS)
         })?,
     )?;
     m.set(
         "PingLocation",
-        // The minimap click (our own `Minimap_OnClick`, and any addon that replaced it): centre-
-        // relative offsets in **UI units**, x right / y up — exactly `GetCursorPosition()` minus
-        // `Minimap:GetCenter()`, both of which are UI-space. Parked, not converted: the app owns
-        // the view scale, and it drains this in the SAME frame it draws the map so the click
-        // resolves against the geometry the player actually clicked on (decision 1596).
-        //
-        // The receiver is validated but the value lives on the model — one pending click, not one
-        // per Minimap widget.
+        // Centre-relative offsets in UI units, x right and y up, parked for the app to resolve in
+        // the frame it draws the map; one pending click, not one per widget.
         lua.create_function(|lua, (this, x, y): (Table, f32, f32)| {
             with_minimap(lua, &this, |_| ())?;
             lua.app_data_mut::<Model>()
@@ -176,16 +126,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
     m.set(
         "GetPingPosition",
-        // The ping's normalized offsets from the widget centre (fractions of the widget side,
-        // x right / y up — the `MINIMAP_PING` event's own arg2/arg3 space), recomputed by the app
-        // from the stored world point every frame. So a caller polling this while walking sees
-        // the value MOVE, which is the whole point: the ping is pinned to the world, not to the
-        // map.
-        //
-        // **Two numbers, always** (`0x4eefd0`): the reference
-        // recomputes from statics nothing ever clears, and the stock `Minimap_OnUpdate` feeds the
-        // answer straight into `x * Minimap:GetWidth()` for the whole of its 5 s timer — a nil
-        // here is a Lua error on every frame of that window (1974).
+        // Fractions of the widget side from its centre (`MINIMAP_PING`'s arg2/arg3 space), which
+        // the app recomputes from the world point each frame. Always two numbers (`0x4eefd0`): the
+        // stock `Minimap_OnUpdate` multiplies them for 5 s, so a nil would error every frame.
         lua.create_function(|lua, this: Table| {
             with_minimap(lua, &this, |_| ())?;
             let (x, y) = lua
diff --git a/crates/benilla-ui/src/script/mod.rs b/crates/benilla-ui/src/script/mod.rs
index 9be245ed..49379335 100644
--- a/crates/benilla-ui/src/script/mod.rs
+++ b/crates/benilla-ui/src/script/mod.rs
@@ -1,41 +1,16 @@
-//! The Lua scripting host — the engine-free VM that turns the arena/layout/order *model* into a
-//! live, addon-facing runtime (decision 0068). No Bevy, no GPU: this module embeds mlua's Lua 5.1
-//! (the Classic Era version) and wires it to [`crate::widget`]'s frame arena, [`crate::layout`]'s
-//! anchor resolver, and [`crate::order`]'s draw-order traversal, exposing the WoW FrameScript object
-//! model and the slice-of stdlib addons expect.
+//! The Lua scripting host: the engine-free VM that runs FrameXML and addons over the frame arena,
+//! the anchor resolver and the draw order. It embeds mlua's Lua 5.1, reshaped by [`lua50`] to
+//! answer as the 1.12 client's Lua 5.0.
 //!
-//! ## Ground truth
+//! A frame's Lua value is a table whose `T[0]` lightuserdata (`0x701bd0`) holds a `u32` id where
+//! the reference holds the `CScriptObject*`, with an `__index` metatable (`0x7020b0`). A handler
+//! is `pcall`ed with `this`, `event` and `arg1..argN` set as globals and restored after
+//! (`0x704d50`); it also gets `(self, event, ...)` as arguments, which 1.12 does not pass.
 //!
-//! - **The frame object model** (`0x701bd0`/`0x7020b0`): a frame's Lua value
-//!   is a table `T` with `T[0] = lightuserdata(handle)`, one *shared* metatable
-//!   `__framescript_meta` whose `__index` dispatches by method name; named frames auto-publish to
-//!   `_G` non-overwriting. See [`object`].
-//! - **The handler-firing context** (`0x704d50`): a handler is fired via `pcall`
-//!   with `this`/`event`/`arg1..argN` set as **globals**, saved-then-restored around the call
-//!   (nesting-safe). We also pass the *modern* `(self, event, ...)` arguments the Era addons expect
-//!   (the transition-era client did both). See [`event`].
-//!
-//! ## The `LUAI_MAXCSTACK` discipline (decision 0068, probe A)
-//!
-//! Probe A found the hard constraint that Rust must **never** hold thousands of persistent mlua
-//! handles (each owned `Table`/`Function` occupies a slot on mlua's reference thread, capped by the
-//! vendored build's `LUAI_MAXCSTACK = 8000`). So this host holds **zero** persistent Lua handles in
-//! Rust: every piece of Lua-side state — the two shared metatables, the two method tables, the
-//! wrapper cache (`id → wrapper table`), and every frame's script closures (`id → {name → fn}`) —
-//! lives in the Lua **registry** under named keys and is fetched transiently per call. The Rust-side
-//! [`Model`] is *plain data* (arena, layout inputs, id↔handle maps, region visuals, event
-//! registrations, errors) stored in `lua.app_data`, reachable from callbacks via `RefCell`-style
-//! dynamic borrows. Every callback takes a *short* borrow and drops it before re-entering Lua.
-//!
-//! ## Identity: ids, not handle bits
-//!
-//! `0x701bd0` stores the `CScriptObject*` in the lightuserdata. Benilla's
-//! [`crate::widget::FrameHandle`] is an opaque generational handle with private fields (no bit
-//! accessor), so we mint a stable `u32` **id** per handle and store *that* in the lightuserdata
-//! (`id as *mut c_void`); [`Model`] owns the `id ↔ handle` bijection. The id doubles as the
-//! [`crate::layout::Handle`] used by the layout graph (frames only; the screen root is the reserved
-//! id [`SCREEN`]). This is faithful to the reference's intent (an opaque identity in a
-//! lightuserdata) — only the *encoding* differs.
+//! The `LUAI_MAXCSTACK` discipline: Rust holds no persistent Lua handle, since each owned `Table`
+//! or `Function` takes a slot on mlua's reference thread, capped at the vendored 8000. Lua-side
+//! state lives in the registry under named keys, fetched per call; [`Model`] is plain data in
+//! `lua.app_data`, borrowed briefly and released before re-entering Lua.
 
 mod action;
 mod action_bar_toggles;
@@ -53,7 +28,7 @@ mod binding_abi;
 mod dialog_verbs;
 mod tutorial;
 mod worldmap_arrow;
-// The five camera views + FlipCameraYaw — the reference's `UIUtil\Camera.cpp` Lua surface.
+// `camera_view`: the five camera views and `FlipCameraYaw`, the reference's `UIUtil\Camera.cpp`.
 mod button;
 mod camera_view;
 mod channel;
@@ -91,8 +66,6 @@ mod screenshot;
 mod tabard;
 pub use handler_prof::HandlerRow;
 
-/// The widget-method surface measurement — shared by the `dump_widget_methods` example and the
-/// widget-surface gate (decision 2142).
 mod surface;
 pub use surface::widget_method_census;
 mod inspect;
@@ -126,8 +99,6 @@ mod pvp;
 mod quest;
 mod quest_log;
 pub(crate) mod region;
-/// The 19 Region-map methods, shared by frames and regions the way the reference shares them
-/// (decision 1501) — its header is the byte-verified chain and the bug that found the split.
 mod region_map;
 mod reputation;
 mod saved;
@@ -160,8 +131,6 @@ mod trainer;
 mod types;
 mod unit;
 mod weapon_enchant;
-/// The `/who` list's seven-key sort chain and its comparator — its header is the whole
-/// mechanism, including why a repeated header click reverses (decision 2030).
 mod who_sort;
 mod worldmap;
 mod worldstate;
@@ -298,40 +267,28 @@ use crate::layout::Rect;
 use crate::order::ZTarget;
 use crate::widget::{FrameHandle, KindState};
 
-// Registry key names — the only place Lua-side roots are kept alive (the MAXCSTACK discipline).
+// Registry keys, the only roots of Lua-side state (the `LUAI_MAXCSTACK` discipline).
 const REG_FRAME_META: &str = "__benilla_frame_meta";
 const REG_REGION_META: &str = "__benilla_region_meta";
 const REG_FRAME_METHODS: &str = "__benilla_frame_methods";
 const REG_REGION_METHODS: &str = "__benilla_region_methods";
-/// The full table's registry key, exposed for the exhaustiveness gate in `tests::reference_surface`
-/// — the split's correctness is a property of what the VM HOLDS, not of the source that builds it.
 #[cfg(test)]
 pub(crate) const REG_REGION_METHODS_FOR_TEST: &str = REG_REGION_METHODS;
-/// The **title region's** method table + metatable — the 19 Region methods and nothing else.
+/// The title region's method table and metatable: the 19 Region methods and nothing else.
 const REG_TITLE_METHODS: &str = "__benilla_title_methods";
 const REG_TITLE_META: &str = "__benilla_title_meta";
-/// The two region LEAF tables + metatables — Texture and FontString each answer their own map.
+/// The region leaf tables and metatables: Texture and FontString each answer their own map.
 const REG_TEXTURE_METHODS: &str = "__benilla_texture_methods";
 const REG_TEXTURE_META: &str = "__benilla_texture_meta";
 const REG_FONTSTRING_METHODS: &str = "__benilla_fontstring_methods";
 const REG_FONTSTRING_META: &str = "__benilla_fontstring_meta";
-/// The stdlib's out-of-the-box error handler, kept by identity so
-/// [`UiScript::dispatch_script_errors_to_handler`] can tell "nobody chose a handler" (skip — the
-/// default already reports into the host channel) from "FrameXML or an addon installed one"
-/// (dispatch — that is what the pair exists for). Stored at [`stdlib::install`] time, the one
-/// moment the default is known to be what `geterrorhandler()` answers.
+/// The stdlib's default error handler, kept by identity for
+/// [`UiScript::dispatch_script_errors_to_handler`] to skip; stored at [`stdlib::install`].
 const REG_DEFAULT_ERRORHANDLER: &str = "__benilla_default_errorhandler";
 
-/// The **Region method map** (`0xcf54b4`) — the 19 names every region leaf reaches through its own
-/// lookup's fallback, fixed and asserted as a SET by `tests::reference_surface`. Named here because
-/// two things need the same list: that test, and the title region's narrower method table (1250
-/// §5).
-/// Names on **both** region leaves — and each leaf registers its own copy (Texture's own
-/// `SetAlpha` `0x79b580`, FontString's `0x79cb70`), so these are NOT on the Region map and must
-/// not be hoisted into it.
-/// `GetDrawLayer` is the setter's pair on both leaves (Texture `0x79a6c0`, FontString `0x79c660`)
-/// and is here now — it was found absent, which was true and was a gap, not a decision; pfUI's
-/// `GetNoNameObject` reads it off every child of a frame it reskins.
+/// Names on both region leaves, each leaf registering its own copy (Texture's `SetAlpha`
+/// `0x79b580`, FontString's `0x79cb70`), so they are not on the Region map and must not be hoisted
+/// into it. `GetDrawLayer` is on both (Texture `0x79a6c0`, FontString `0x79c660`).
 pub(crate) const REGION_LEAF_SHARED: [&str; 9] = [
     "SetDrawLayer",
     "GetDrawLayer",
@@ -344,24 +301,9 @@ pub(crate) const REGION_LEAF_SHARED: [&str; 9] = [
     "IsShown",
 ];
 
-/// **Texture-only.** Note `GetVertexColor` sits here while `SetVertexColor` is shared — an asymmetry
-/// no reasonable partition invents, and the bytes call it out. Also note the client's Texture map
-/// has `SetGradientAlpha` where FontString has `SetAlphaGradient`: a near-miss pair, and we install
-/// only the FontString one.
-///
-/// **Every name here is the client's own now.** Three of ours were parked in this list pending a
-/// per-name check, and all three are gone: `SetRotation` (1.12 registers it only on PlayerModel,
-/// `0x84f1fc`/`0x505f00`, and the world-map arrow that justified it is a Model frame now — see
-/// `region/paint.rs` at its old site), `SetPortraitToTexture` (1.12 has it as an engine GLOBAL,
-/// never a Texture method — `region.rs` registers it there, and a test pins the absence), and
-/// `SetSize`, the Era geometry verb that was in neither client map and that nothing outside our
-/// own test scaffolding called (decision 2142's census). The 1244/1245 landing partitioned rather
-/// than pruned and said the pruning was a separate question per name; this is the answer to three
-/// of them.
-///
-/// Going the other way: `GetBlendMode`, `SetTexCoordModifiesRect` and `GetTexCoordModifiesRect`
-/// joined the list, all three of them in the client's Texture map `0x87c128` (`0x79a890` /
-/// `0x79c080` / `0x79c120`), and all three of them missing here until then.
+/// Texture-only, each in the client's Texture map (`0x87c128`): `GetVertexColor` though
+/// `SetVertexColor` is shared, and `SetGradientAlpha`, not FontString's `SetAlphaGradient`. 1.12
+/// has no Texture `SetSize` or `SetRotation` (PlayerModel's, `0x84f1fc`/`0x505f00`).
 pub(crate) const TEXTURE_ONLY_METHODS: [&str; 12] = [
     "SetGradient",
     "SetGradientAlpha",
@@ -377,14 +319,8 @@ pub(crate) const TEXTURE_ONLY_METHODS: [&str; 12] = [
     "GetVertexColor",
 ];
 
-/// **FontString-only** — the font/text/justify/shadow block plus the string metrics.
-///
-/// **Every name here is the client's own now.** Three of ours were parked in this list:
-/// `GetStringHeight` went first (1251 — byte-verified absent, and ours was a byte-identical
-/// duplicate of `GetHeight`), and `SetFormattedText` (not among the client's 32) and
-/// `SetSize` (the Era geometry verb the Texture list carried too) went with 2142's census, which
-/// found neither in the stock chain nor in either addon corpus. The era spelling of
-/// `SetFormattedText` is `SetText(format(fmt, ...))`; of `SetSize`, `SetWidth` + `SetHeight`.
+/// FontString-only: the font, text, justify and shadow block and the string metrics.
+/// `GetStringHeight`, `SetFormattedText` and `SetSize` are not 1.12 FontString methods.
 pub(crate) const FONTSTRING_ONLY_METHODS: [&str; 21] = [
     "SetFont",
     "GetFont",
@@ -409,6 +345,7 @@ pub(crate) const FONTSTRING_ONLY_METHODS: [&str; 21] = [
     "SetAlphaGradient",
 ];
 
+/// The Region method map (`0xcf54b4`): the 19 names every region leaf reaches on a miss.
 pub(crate) const REGION_MAP_METHODS: [&str; 19] = [
     "GetObjectType",
     "IsObjectType",
@@ -433,55 +370,25 @@ pub(crate) const REGION_MAP_METHODS: [&str; 19] = [
 const REG_WRAPPERS: &str = "__benilla_wrappers";
 const REG_SCRIPTS: &str = "__benilla_scripts";
 
-/// The reserved layout [`crate::layout::Handle`] of the screen root (the client's `CSimpleTop` /
-/// `UIParent`), whose rect is the physical screen. Top-level frames whose `SetPoint` omits a
-/// `relativeTo` anchor to it. Real frame ids are minted from `1` upward so they never collide.
+/// The layout handle of the screen root (the client's `CSimpleTop`, not the `UIParent` frame),
+/// which a top-level `SetPoint` without `relativeTo` anchors to; frame ids, from 1, are the rest.
 pub const SCREEN: crate::layout::Handle = 0;
 
-/// The FrameScript handler kinds this host models. The first five are the lifecycle/event set; the
-/// six mouse handlers are driven by the hit-testing API in [`pointer`] ([`UiScript::mouse_move`] /
-/// [`mouse_button`](UiScript::mouse_button) / [`mouse_wheel`](UiScript::mouse_wheel)) — the app-side
-/// event feed (net/window → these calls) is the Bevy side's job (decision 0068). `OnValueChanged`
-/// is shared by the StatusBar (`+0x32c`) and the Slider (`+0x330`; decision 0250) — one name,
-/// each kind dispatching to its own value-changed slot. The eight
-/// `On*Pressed`/text/focus slots are the EditBox's specialized scripts (vtable `0x81c910`): a
-/// focused EditBox fires ONLY these, never generic `OnKeyDown`/`OnChar` (its C++ override replaces
-/// those slots).
-/// `OnHorizontalScroll`/`OnVerticalScroll`/`OnScrollRangeChanged` are the ScrollFrame's own slots
-/// (decision 0112; the reference's `[+0x32c]`/`[+0x334]`/`[+0x33c]`, script-name map `0x786c40`).
-/// `OnHorizontalScroll` joined the other two with the horizontal offset pair — it is fired by
-/// `SetHorizontalScroll`, which is what earns it the row below.
-/// `OnDragStart`/`OnDragStop`/`OnReceiveDrag` are the drag trio (decision 0216 §3) — driven by
-/// `RegisterForDrag` + the same mouse path as the six mouse handlers above, not a separate one.
-/// `OnColorSelect` is the ColorSelect's own slot (`+0x338`), fired by its `SetColorRGB`.
+/// The FrameScript handler kinds `SetScript` accepts, each only with the code that fires it
+/// ([`crate::script::object::events_regions::set_script`]). The list is flat, where the reference
+/// resolves names per widget type (base map `0x76a0d0` plus the type's own; a `<Frame>` has no
+/// `OnClick`), so any widget accepts any kind here.
 ///
-/// **Every name here is FIRED by something.** A kind that the engine can accept but never raise is
-/// strictly worse than the `SetScript: unsupported script` error it replaces — the addon's handler
-/// silently never runs and nothing anywhere says so (the bug class decisions 1203/1205/1211 each
-/// record). So a script name earns its row here only together with the code that fires it, and the
-/// names the reference has that we do NOT fire stay OUT, with the reason recorded at
-/// [`crate::script::object::events_regions::set_script`].
-///
-/// **This list is FLAT; the reference's set is per widget type** (script-name→slot
-/// resolvers: base map `0x76a0d0` + the type's own additions — a `<Frame>` has no `OnClick`). That
-/// divergence is deliberate and measured, and the 1751 migration has been shrinking the debt it
-/// covers. Our own FrameXML used to rely on it in 9 places; seven of them were
-/// `PlayerFrame`/`TargetFrame`/`PetFrame`/`PartyMemberFrame1-4` declared as mouse-enabled
-/// `<Frame>`s carrying `OnClick` in our transcribed `UnitFrames.xml`, and that file is gone — the
-/// reference declares all seven as `<Button>`, which carries `OnClick` by type. What is left of
-/// ours is `ChatFrame1`/`ChatFrame2`, plus the corpus's 21 (20 `EditBox` + 1 `<Frame>`
-/// `OnEscapePressed`), all of which fire today ([`button::click_button`]'s "plain frames can carry
-/// one too" arm). Going per-type is the faithful shape and is what would give us `HasScript` (948
-/// corpus call sites across 91 addons); it removes working behaviour from the 23 sites that remain,
-/// so it is still a change to make deliberately rather than as a side effect of widening this list
-/// — but the FrameXML half of "with FrameXML fixed first" is most of the way there now.
+/// `OnValueChanged` is the StatusBar's (`+0x32c`) and the Slider's (`+0x330`) own slot; the
+/// ScrollFrame's three scroll kinds are `+0x32c`/`+0x334`/`+0x33c` (script-name map `0x786c40`).
+/// The EditBox's vtable (`0x81c910`) replaces the key and char slots: an EditBox never fires
+/// `OnKeyDown`, and fires `OnChar` only from `Insert`, with the inserted text (`0x77c13c`).
 const SCRIPT_KINDS: [&str; 39] = [
     "OnLoad",
     "OnEvent",
     "OnUpdate",
-    // The model pane's two: fired by the tick's model pass — `OnUpdateModel` at the top of every
-    // paint of a visible pane, `OnAnimFinished` when a clamped sequence completes (decision 2007;
-    // `object::events_regions::set_script`'s doc has the sites).
+    // The model pane's two, fired by the tick's model pass (`tick_model_panes`): `OnUpdateModel`
+    // at the top of a visible pane's paint, `OnAnimFinished` when the armed sequence completes.
     "OnUpdateModel",
     "OnAnimFinished",
     "OnShow",
@@ -500,9 +407,7 @@ const SCRIPT_KINDS: [&str; 39] = [
     "OnTextChanged",
     "OnTextSet",
     // The caret flush's own (`0x77da80`), fired by the tick's `drain_cursor_changed` when the
-    // caret has moved — the edge `ScrollingEdit_OnCursorChanged` + `ScrollingEdit_OnUpdate` scroll
-    // a multiline box by. It earns its row here the way this list's rule requires: together with
-    // the code that fires it (decisions 2135/2141).
+    // caret moved: the edge `ScrollingEdit_OnCursorChanged` scrolls a multiline box by.
     "OnCursorChanged",
     "OnEditFocusGained",
     "OnEditFocusLost",
@@ -512,94 +417,53 @@ const SCRIPT_KINDS: [&str; 39] = [
     "OnDragStart",
     "OnDragStop",
     "OnReceiveDrag",
-    // A release over a message-frame hyperlink span (`OnHyperlinkClick(link, text, button)` —
-    // the ChatFrameTemplate wires it to SetItemRef; decision 0288 P2).
+    // A release over a message-frame hyperlink span, `OnHyperlinkClick(link, text, button)`;
+    // `ChatFrameTemplate` passes it to `SetItemRef` (`ChatFrame.xml:15`, `ChatFrame.lua:1534`).
     "OnHyperlinkClick",
-    // The GameTooltip's engine-fired widget scripts (decision 0274; the real template wires all
-    // three: money render, money clear, world-hover default placement).
+    // The GameTooltip's engine-fired scripts: money render, money clear and world-hover default
+    // placement, all three wired by the stock template (`GameTooltipTemplate.xml:617-625`).
     "OnTooltipAddMoney",
     "OnTooltipCleared",
     "OnTooltipSetDefaultAnchor",
-    // The ColorSelect's own slot (`0x78b4f0` script-map, `+0x338`): `OnColorSelect(r, g, b)`
-    // — how the colour picker paints its preview swatch, and how TipBuddy's two private
-    // `<ColorSelect>` frames learn a colour changed.
+    // The ColorSelect's own slot (script map `0x78b4f0`, `+0x338`), fired by its `SetColorRGB`.
     "OnColorSelect",
-    // The Button/CheckButton double click (script-map `0x778c50`, `+0x4d4`) —
-    // `OnDoubleClick(self, button)`, fired by [`pointer`]'s release-edge detector *instead of* the
-    // second `OnClick`, 300 ms (`0x77937b`). **The corpus's
-    // single biggest script gap**: 250 call sites across 85 addons, and the *only* thing behind the
-    // harness's entire `SetScript: unsupported script` blocker row — 8 addons, 5 dying at load and
-    // 3 at session start, every one of them a FuBar plugin or a Titan panel button
-    // (`FuBarPlugin-2.0:CreateBasicPluginFrame` wires one, unguarded, on its panel Button).
+    // The Button/CheckButton double click (script map `0x778c50`, `+0x4d4`), fired by
+    // [`pointer`]'s release edge in place of the second `OnClick` within 300 ms (`0x77937b`).
     "OnDoubleClick",
-    // The layout event (base map `0x76a0d0` `+0x120`), fired from the resolve pass by
-    // [`crate::layout::size_changed`]'s byte-verified epsilon test — see
-    // [`UiScript::resolve_layout`]. `OnSizeChanged(self, width, height)`.
+    // The layout event (base map `0x76a0d0`, `+0x120`), fired by the resolve pass on a size change.
     "OnSizeChanged",
-    // The three KEY channels, unblocked by [`keyboard`]'s walk (`0x765f10`). They were the
-    // standing exception in
-    // [`object::events_regions`]'s note — accepted only once something fired them, which is that
-    // module's whole rule. `OnKeyUp` rides in with the other two deliberately: it is *gated* today
-    // (a frame carrying only an OnKeyUp consumes every key-down and runs nothing — the reference's
-    // own asymmetry) even though this engine's host feeds no key-up to fire it with, and accepting
-    // the name is what makes that consumption reachable.
+    // The key channels, fired by [`keyboard`]'s walk (`0x765f10`). `OnKeyUp` never fires, as the
+    // host feeds no key-up, but a frame carrying only `OnKeyUp` still consumes every key-down and
+    // runs nothing, the reference's own asymmetry.
     "OnChar",
     "OnKeyDown",
     "OnKeyUp",
 ];
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
-// UiScript — the public host
+// UiScript: the public host
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
-/// The Lua scripting host. Owns the mlua VM; the frame arena, layout store, and event registry live
-/// inside it (in `lua.app_data`, per the MAXCSTACK discipline) and are driven through this API.
-///
-/// Construction sandboxes the VM (removes `io`/`os`/`package`/`require`/`dofile`/`loadfile`/`debug`,
-/// text-only chunk loading — see [`stdlib`]), installs the WoW stdlib layer (the global aliases, the
-/// positional `format`, the `strsplit` family, `getglobal`/`setglobal`, `wipe`, …), and installs the
-/// FrameScript object model (`CreateFrame` + the widget/region method surface, the shared metatables).
-///
-/// The host surface is split, `impl UiScript` blocks beside their concern (the `layout.rs` pattern):
-/// the render-list builder in [`extract`], the per-frame runtime loop in [`tick`], the EditBox text
-/// seam in [`editbox::seam`], the layout resolve in [`layout`], and the pointer/hit-test in
-/// [`pointer`]. What stays here is construction and the small host-facing state pushes/queries.
+/// The Lua scripting host: owns the VM, whose `Model` lives in `lua.app_data`. Its `impl` blocks
+/// sit beside their concerns: [`extract`], [`tick`], [`editbox::seam`], [`layout`] and [`pointer`].
 pub struct UiScript {
     lua: Lua,
-    /// VM instructions executed, counted only while a budget is installed
-    /// ([`UiScript::set_instruction_budget`]). `Arc` because the hook callback outlives this
-    /// borrow; `Relaxed` because nothing orders against it — it is a bound, not a clock.
+    /// VM instructions counted while a budget is installed ([`UiScript::set_instruction_budget`]).
     instructions: std::sync::Arc<std::sync::atomic::AtomicU64>,
-    /// **This VM's identity** — see [`UiScript::session`].
     session: u64,
 }
 
-/// Hands out [`UiScript::session`] ids. Process-global and monotone, so an id is never reused and
-/// two of them can be compared without holding either VM.
+/// Hands out [`UiScript::session`] ids: process-global and monotone, so an id is never reused.
 static NEXT_SESSION: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(1);
 
-/// How often the instruction hook fires — the resolution of an instruction budget.
-///
-/// mlua's own documentation warns that a low value "can incur a very high overhead", and nothing
-/// wants a precise bound: the question a budget answers is "is this chunk ever going to stop?",
-/// where being out by a million instructions costs nothing and firing every instruction would cost
-/// the whole survey's runtime.
+/// How often the instruction hook fires: an instruction budget's resolution (low values cost).
 pub const INSTRUCTION_HOOK_STEP: u32 = 1_000_000;
 
-/// The chunk name the CLIENT gives an addon's file: `Interface\AddOns\<Folder>\<File>`.
-///
-/// Backslashes, and the `Interface\AddOns\` prefix, because addons PARSE this. `FuBarPlugin-2.0`
-/// derives each plugin's own folder from a stack trace —
-/// `string.find(debugstack(6, 1, 0), "\\AddOns\\(.*)\\")` (`FuBarPlugin-2.0.lua:752`) — and
-/// feeds the capture straight into `format("Interface\\AddOns\\%s\\icon", self.folderName)`.
-/// With no name set, mlua defaults the chunk to the Rust caller location, the pattern misses,
-/// `folderName` is nil, and every FuBar plugin dies formatting it. That was 20 addons.
-///
-/// The greedy `(.*)` in their pattern is why the FILE has to be in the name too: it captures up to
-/// the LAST backslash, so `…\AddOns\FuBar_BagFu\FuBar_BagFu.lua` yields `FuBar_BagFu`. A name
-/// stopping at the folder would capture the empty string.
+/// The chunk name the 1.12 client gives an addon's file, `Interface\AddOns\<Folder>\<File>`,
+/// backslashed and with the file, because addons parse it: `FuBarPlugin-2.0` finds its folder with
+/// the greedy `\\AddOns\\(.*)\\` over `debugstack`, which needs the file after the folder.
 pub fn addon_chunk_name(folder: &str, file: &str) -> String {
-    // `@` is Lua's "this chunk is a file" marker; the traceback then prints the path plainly.
+    // `@` marks the chunk as a file, so a traceback prints the path plainly.
     format!("@Interface\\AddOns\\{folder}\\{}", file.replace('/', "\\"))
 }
 
@@ -608,8 +472,8 @@ impl UiScript {
     pub fn new() -> mlua::Result<UiScript> {
         let lua = Lua::new();
         lua.set_app_data(Model::new());
-        // Before anything can fire a handler, and while nothing holds an app-data borrow — the two
-        // conditions the profiler's slot has to be installed under (decision 1395).
+        // Before anything can fire a handler and while no app-data borrow is held, as the
+        // profiler's slot requires.
         handler_prof::install(&lua);
 
         addon::install(&lua)?;
@@ -622,12 +486,12 @@ impl UiScript {
         client::install(&lua)?;
         screenshot::install(&lua)?;
         stdlib::sandbox(&lua)?;
-        // Before the stdlib layer, so its aliases bind the 5.0-shaped functions (decision 1194).
+        // Before the stdlib layer, so its aliases bind the 5.0-shaped functions.
         lua50::install(&lua)?;
         stdlib::install(&lua)?;
         object::install(&lua)?;
-        // After `object` (it reuses the frame side's `publish_global`), before any FrameXML is
-        // loaded — `Loader::do_font` publishes into the tables this builds.
+        // After `object`, whose `publish_global` it reuses, and before any FrameXML loads:
+        // `Loader::do_font` publishes into the tables this builds.
         font::install(&lua)?;
         unit::install(&lua)?;
         party::install(&lua)?;
@@ -713,66 +577,26 @@ impl UiScript {
         Ok(s)
     }
 
-    /// The embedded VM — for the Bevy plugin / TOC-XML loader to add the game-state API bindings
-    /// (decision 0068 §1: "the Bevy side owns … the API bindings that touch ECS/net") on top of the
-    /// object model this crate installs.
+    /// The embedded VM, for the app and the loader to add their bindings over this object model.
     pub fn lua(&self) -> &Lua {
         &self.lua
     }
 
-    /// **Which VM this is** — a fresh number for every [`UiScript::new`], never reused.
+    /// Which VM this is: a fresh number per [`UiScript::new`], never reused, so anything the host
+    /// seeded into a VM is valid only while this still matches.
     ///
-    /// The client destroys its Lua state and builds another several times over a login cycle, so a
-    /// host that remembers *what it last pushed into the VM* is remembering something that may no
-    /// longer exist. Anything the host seeded — a registry, a catalog, a change-detection memo — is
-    /// only valid for the session it was seeded into, and this number is what says so.
-    ///
-    /// **The addresses, corrected** (2226; this doc carried `0x490bd0` ↔ `0x48fbf0` from 1290 and
-    /// that pair is wrong). `ds:0xceef74` is a single global *slot* holding successive instances,
-    /// written at exactly two sites image-wide: `0x7039ed` opens, `0x703bab` closes. The reset
-    /// choke point `0x703b80` closes-if-present and then **tail-jmps** into the open — which is why
-    /// a `call`-only census of it reads "one state per process" and is wrong. Its three callers are
-    /// `0x48fe97` (inside `UI_Init 0x48fbf0`, unconditional), `0x491231` (`ShutdownGame`,
-    /// unconditional) and `0x46a87b` (the glue builder, gated on its arg). `0x490bd0` destroys the
-    /// frame-script *owner object* (`0x490c97`, vtable `0x81c380` slot+4 = `0x764360`) and nils the
-    /// 216 bindings; it never touches `ds:0xceef74`.
-    ///
-    /// So the boundary is `0x48fe97` ↔ `0x491231`/`0x46a87b`: **the rebuild replaces the state, the
-    /// teardown does not** — and the rebuild lives *inside* the function that loads FrameXML, which
-    /// is why benilla's world entry mints its VM at the top of its own load (2226) rather than
-    /// adopting the character screen's. GlueXML and FrameXML never share an instance.
-    ///
-    /// A host keying its memory on this cannot go stale by omission: a new VM simply does not
-    /// match, so the seed happens again. That is the property, and it is why this is a VM-side fact
-    /// rather than a host-side counter the host must remember to bump.
+    /// The reference keeps one Lua state (`0xceef74`), replaced only by the reset `0x703b80`: from
+    /// `UI_Init` (`0x48fbf0`, at `0x48fe97`) as it loads FrameXML, `ShutdownGame` (`0x491231`) and
+    /// the glue builder (`0x46a87b`), never the UI teardown `0x490bd0`. GlueXML and FrameXML never
+    /// share a state, so world entry mints its VM at the top of its load.
     pub fn session(&self) -> u64 {
         self.session
     }
 
-    /// **Bound how long a chunk may run, so an infinite loop reports instead of hanging.**
-    ///
-    /// A missing capability in this engine has always been a silently WRONG ANSWER — a setter that
-    /// ignores you, a getter that says nil (1203/1205/1211/1230). Decision 1247 met the other kind:
-    /// `date("*t")` returned a string where Lua returns a table, so `Accountant_WeekStart`'s
-    /// `while thisDay ~= weekstart` never terminated and the addon spun the VM forever. That is
-    /// invisible to every instrument we own, because an instrument that never returns produces no
-    /// roster to diff, no column to compare and no error row to read — the 218-addon survey simply
-    /// stopped finishing, and the cause was found by bisecting the corpus BY HAND.
-    ///
-    /// So a caller that runs untrusted chunks can bound them. Past `budget` VM instructions the
-    /// hook raises, and the raise propagates like any other Lua error: the addon reports as failed
-    /// with a distinctive message, and everything after it still runs.
-    ///
-    /// **This is opt-in, and the app arms it only on the world-entry load edge** (decision 1306;
-    /// it began harness-only, e463649e). A real session must not kill a player's addon for being
-    /// slow, so steady state — every OnUpdate, every event — runs unhooked; but a load walk that
-    /// never returns is a client frozen on the loading screen with zero diagnostics (B271's
-    /// class), so the entry edge is bounded and [`Self::clear_instruction_budget`] disarms before
-    /// the session's first frame.
-    ///
-    /// The hook fires every [`INSTRUCTION_HOOK_STEP`] instructions rather than every instruction:
-    /// mlua's own docs warn that a low value "can incur a very high overhead", and the step is the
-    /// resolution of the bound, which nothing here needs to be precise.
+    /// Bound how long a chunk may run: past `budget` VM instructions the hook raises a Lua error,
+    /// so a loop that never ends fails its addon and the rest still runs. The app arms it only for
+    /// the world-entry load, so a hung load reports instead of freezing the loading screen, and
+    /// disarms it ([`Self::clear_instruction_budget`]) before the session's first frame.
     pub fn set_instruction_budget(&self, budget: u64) {
         let used = self.instructions.clone();
         used.store(0, std::sync::atomic::Ordering::Relaxed);
@@ -797,36 +621,21 @@ impl UiScript {
         );
     }
 
-    /// Remove an installed instruction budget — the load edge's disarm (decision 1306): the bound
-    /// covers the world-entry walk, and a session's steady state runs unhooked exactly as before.
-    /// The counter keeps its last value, so [`Self::instructions_used`] still answers for the
-    /// phase that just ended.
+    /// Remove the instruction budget; the counter keeps its value for [`Self::instructions_used`].
     pub fn clear_instruction_budget(&self) {
         self.lua.remove_hook();
     }
 
-    /// VM instructions executed since the last [`Self::set_instruction_budget`], to the resolution
-    /// of [`INSTRUCTION_HOOK_STEP`]. Zero when no budget was ever set — the hook is what counts.
-    ///
-    /// Reported rather than merely used, because the budget has to be CHOSEN from the corpus and a
-    /// number nobody can read is a number nobody can revisit.
+    /// VM instructions since the last [`Self::set_instruction_budget`], to the resolution of
+    /// [`INSTRUCTION_HOOK_STEP`]; zero when no budget was ever set.
     pub fn instructions_used(&self) -> u64 {
         self.instructions.load(std::sync::atomic::Ordering::Relaxed)
     }
 
-    /// Set the screen-root rect from a pixel size (`[0,0]` origin, y-up). Top-level frames anchor to
-    /// it; changing it invalidates the next `resolve`. The app calls this every frame with an
-    /// almost-always-identical size — compared before writing so the per-frame idiom doesn't
-    /// dirty the layout gate's tier 1 (`Model::touch_layout`).
-    ///
-    /// **Returns whether the size actually changed.** Anchors follow the new rect on their own, so
-    /// most of the UI needs nothing; what does not follow is anything that *computed* a seat from
-    /// the old height and stored it — the open-bag stack wraps into a fresh column from
-    /// `GetScreenHeight()`, and that answer is stale the moment the window is resized. The 1.12
-    /// client never had to care (its resolution changed through a restart, and its own
-    /// `DISPLAY_SIZE_CHANGED` listeners are three model panes, none of them the manage pass), but
-    /// benilla runs in a freely resizable window, so the caller re-runs
-    /// `UIParent_ManageFramePositions()` on a true return. Decision 1499.
+    /// Set the screen-root rect from a pixel size (origin `[0,0]`, y-up), compared first so the
+    /// app's every-frame call leaves an unchanged layout clean. On a change (`true`) the caller
+    /// re-runs `UIParent_ManageFramePositions()`: the window resizes freely, and a seat computed
+    /// from `GetScreenHeight()`, like the open-bag stack's column wrap, does not follow anchors.
     pub fn set_screen_size(&mut self, width: f32, height: f32) -> bool {
         let new = Rect::new(0.0, 0.0, height, width);
         let mut model = self.model_mut();
@@ -836,36 +645,25 @@ impl UiScript {
         model.screen = new;
         model.touch_layout();
         drop(model);
-        // The implicit rects are measured in layout units, which follow the aspect (2015).
+        // The implicit rects are in layout units, which follow the aspect.
         self.reapply_implicit_rects();
         true
     }
 
-    /// Replace the Era atlas table (decision 0950) — pushed once at boot, before the XML loads.
-    /// Push the modifier-key state (shift, ctrl, alt) behind `IsShiftKeyDown`/`IsControlKeyDown`/
-    /// `IsAltKeyDown`. The app's input pass calls this BEFORE feeding the frame's mouse events, so
-    /// a click handler's modifier fork (the reference's shift-split / ctrl-dressup /
-    /// shift-pickup) reads the state as of the click.
+    /// Push the modifier state behind `IsShiftKeyDown`/`IsControlKeyDown`/`IsAltKeyDown`; the app
+    /// calls it before the frame's mouse events, so a click handler reads the state of its click.
     pub fn set_modifiers(&mut self, shift: bool, ctrl: bool, alt: bool) {
         let mut model = self.model_mut();
         model.modifiers = (shift, ctrl, alt);
     }
 
-    /// Push the player's WMO-containment state onto every Minimap widget (the client's `0xceaa60`).
-    /// It selects which of the two persisted zoom indices `GetZoom`/`SetZoom` act on, so the zoom
-    /// buttons drive the indoor level while indoors and the outdoor level while outside. The app
-    /// owns the containment test, so it owns this push — call it before the script tick. The
-    /// caller pushes on the inside↔outside edge and whenever [`Self::minimap_widgets_created`]
-    /// moved (a widget born after the last transition still gets told, without paying the arena
-    /// walk every frame).
+    /// Push the player's WMO-containment state (the client's `0xceaa60`) onto every Minimap: it
+    /// picks which persisted zoom index `GetZoom`/`SetZoom` act on. Call it before the script
+    /// tick, on each inside/outside edge and whenever [`Self::minimap_widgets_created`] moves.
     pub fn set_minimap_inside(&mut self, inside: bool) {
         self.for_each_minimap(|m| m.inside = inside);
     }
 
-    /// Run `f` over every live Minimap widget's state. Goes through the arena's Minimap registry
-    /// rather than a full `iter_frames_mut`, for the reason that registry exists: a corpus UI is
-    /// three to four thousand frames and there is normally exactly one Minimap, and one of these
-    /// feeds ([`Self::set_minimap_player_facing`]) runs every frame.
     fn for_each_minimap(&mut self, mut f: impl FnMut(&mut crate::widget::MinimapState)) {
         let mut model = self.model_mut();
         for h in model.arena.minimap_kinds().to_vec() {
@@ -877,17 +675,9 @@ impl UiScript {
         }
     }
 
-    /// Push the player's world facing (radians) onto every Minimap's **player-arrow** `Model` —
-    /// the client's `CMinimap::SetPlayerFacing 0x4eb8e0`, whose whole 34-byte body is
-    /// `[minimap+0x33c] = arg` then, guarded on non-null, `[[minimap+0x338]+0x39c] = arg`: a raw
-    /// dword copy into the same field `Model:SetFacing 0x76dce0` writes, with **no negation, offset
-    /// or unit change**. Its one caller (`0x4eb0a4`–`0x4eb0b1`) feeds it the player's `GetFacing()`
-    /// straight off the FPU stack, so what an addon reads back is the unit's orientation exactly.
-    ///
-    /// This is what makes `({Minimap:GetChildren()})[9]:GetFacing()` — Questie's `GetPlayerFacing`,
-    /// and pfQuest's `compat/client.lua` — return the truth rather than the ctor default `0`, which
-    /// is the difference between a waypoint arrow that points at the waypoint and one aimed
-    /// permanently north. Called every frame by the app, which owns the player.
+    /// Push the player's facing (radians) onto every Minimap's player-arrow `Model`, every frame,
+    /// raw: `CMinimap::SetPlayerFacing` (`0x4eb8e0`, fed at `0x4eb0a4`–`0x4eb0b1`) copies it into
+    /// the field `Model:SetFacing` (`0x76dce0`) writes, so the arrow's `GetFacing()` reads it.
     pub fn set_minimap_player_facing(&mut self, facing: f32) {
         let mut model = self.model_mut();
         let arrows: Vec<crate::widget::FrameHandle> = model
@@ -908,32 +698,19 @@ impl UiScript {
         }
     }
 
-    /// Publish the live minimap ping's **normalized** offsets from the widget centre (fractions
-    /// of the widget side, x right / y up), or `None` when no ping is live —
-    /// `Minimap:GetPingPosition()`'s source. The app recomputes this from the ping's WORLD point
-    /// every frame a ping is live, before the tick, so a poller sees it track the world as the
-    /// player walks.
-    ///
-    /// One field, not one per widget: there is exactly one ping (decision 1596), and the old
-    /// per-widget push walked the whole ~3k-frame arena every frame a ping was live.
+    /// Publish `Minimap:GetPingPosition()`'s offsets from the widget centre, as fractions of its
+    /// side (x right, y up); the app recomputes them from the ping's world point each frame.
     pub fn set_minimap_ping(&mut self, ping: (f32, f32)) {
         self.model_mut().minimap_ping = ping;
     }
 
-    /// Drain a `Minimap:PingLocation(x, y)` call — centre-relative offsets in **UI units**
-    /// (x right, y up). The app converts: UI units × the seam scale = window px, ÷ the live
-    /// `px_per_yd` = yards, and the click resolves against the geometry drawn in the same frame.
+    /// Drain a `Minimap:PingLocation(x, y)`: centre-relative offsets in UI units, x right, y up.
     pub fn take_minimap_ping_request(&mut self) -> Option<(f32, f32)> {
         self.model_mut().minimap_ping_request.take()
     }
 
-    /// The mask art the Minimap widget asks its renderer for — `Minimap:SetMaskTexture`'s value,
-    /// or `None` while no widget has set one (the app then keeps
-    /// [`crate::widget::MINIMAP_DEFAULT_MASK`]).
-    ///
-    /// The **first** Minimap in the registry answers, not every one: the mask is a property of the
-    /// map the app draws, and the app draws one. (Everything else in `MinimapState` is per widget
-    /// because the Lua API reads it back per widget; this has no getter in 1.12 to read back.)
+    /// `Minimap:SetMaskTexture`'s value from the first Minimap (the app draws one map), `None`
+    /// until one is set, while the app keeps [`crate::widget::MINIMAP_DEFAULT_MASK`].
     pub fn minimap_mask_texture(&self) -> Option<String> {
         let model = self.model_ref();
         model.arena.minimap_kinds().iter().find_map(|&h| {
@@ -944,20 +721,15 @@ impl UiScript {
         })
     }
 
-    /// Monotonic count of Minimap widgets ever created in this VM — the O(1) signal that a new
-    /// one exists and needs the containment state pushed.
+    /// Minimap widgets ever created in this VM: a move means a new one needs the containment state.
     pub fn minimap_widgets_created(&self) -> u64 {
         self.model_ref().arena.minimap_created()
     }
 
-    /// Seed every Minimap widget's two zoom indices from the persisted levels — the client's
-    /// minimap reset path copying each CVar object's parsed int into its live index
-    /// (`[0x86f698] ← [[0xb4b410]+0x28]`, `[0x86f69c] ← [[0xb4d90c]+0x28]`). Called **once**, when
-    /// the in-game UI materializes and
-    /// the widget exists — not per frame: from then on the widget's index is the live truth and
-    /// `Minimap:SetZoom` keeps the CVar following it, so a repeated push would fight the +/- buttons.
-    /// Both indices clamp into `[0, MINIMAP_ZOOM_LEVELS)` exactly like `set_zoom`, so a hand-edited
-    /// `config.toml` cannot seed an out-of-range level (decision 1131).
+    /// Seed every Minimap's two zoom indices from the persisted CVars, as the client's reset path
+    /// does (`[0x86f698] ← [[0xb4b410]+0x28]`, `[0x86f69c] ← [[0xb4d90c]+0x28]`). Call it once,
+    /// when the UI and the widget exist: from then on `Minimap:SetZoom` keeps the CVar following
+    /// the widget, and a repeated seed would fight the +/- buttons.
     pub fn set_minimap_zoom(&mut self, zoom: u8, inside_zoom: u8) {
         let top = crate::widget::MINIMAP_ZOOM_LEVELS - 1;
         let (zoom, inside_zoom) = (zoom.min(top), inside_zoom.min(top));
@@ -967,33 +739,19 @@ impl UiScript {
         });
     }
 
-    /// Load and run a Lua chunk (text-only; the sandbox rejects bytecode). Errors propagate to the
-    /// caller (a *load-time* error is the caller's to see; *handler* errors during events go to
-    /// [`UiScript::errors`]).
+    /// Load and run a text chunk; handler errors during events go to [`UiScript::errors`] instead.
     pub fn run(&self, chunk: &str) -> mlua::Result<()> {
         self.run_chunk(chunk.as_bytes())
     }
 
-    /// [`UiScript::run`] over a chunk that came off disk, which is **bytes** (decision 1193).
-    ///
-    /// The reference slurps the file (`0x704bc0`) and hands the buffer to `luaL_loadbuffer`
-    /// (`0x6f5690`) with no conversion, and Lua 5.0 strings are byte strings — so a cp1252 locale
-    /// file runs there and its literals carry the raw bytes. Reading such a file as `String` is
-    /// what made 76 of a real corpus's `.lua` files read as *absent* rather than as text with an
-    /// odd glyph. The two front-door transforms the reference's own compiler applies — the UTF-8
-    /// BOM strip and the `#`-line skip — are applied here ([`crate::source::chunk`]).
+    /// [`UiScript::run`] over a file's bytes: the reference hands the file (`0x704bc0`) to
+    /// `luaL_loadbuffer` (`0x6f5690`) unconverted, so a cp1252 file's literals keep their bytes.
+    /// Its compiler's UTF-8 BOM strip and `#`-line skip apply here ([`crate::source::chunk`]).
     pub fn run_chunk(&self, chunk: &[u8]) -> mlua::Result<()> {
         self.run_chunk_named(chunk, "(chunk)")
     }
 
-    /// Run a chunk under the name the CLIENT would give it — `Interface\AddOns\<Folder>\<File>`
-    /// for an addon file (build it with [`addon_chunk_name`]).
-    ///
-    /// The name is not cosmetic. Without `set_name`, mlua defaults a chunk to the **Rust** caller
-    /// location, so every error an addon raised was reported against `crates/benilla-ui/src/...`
-    /// — wrong in any error an addon shows a player, and load-bearing for the addons that PARSE a
-    /// traceback. `FuBarPlugin-2.0.lua:752` derives a plugin's own folder with
-    /// `string.find(debugstack(6, 1, 0), "\\AddOns\\(.*)\\")`, which cannot match a Rust path.
+    /// Run a chunk under the name the 1.12 client gives it ([`addon_chunk_name`] for addon files).
     pub fn run_chunk_named(&self, chunk: &[u8], name: &str) -> mlua::Result<()> {
         self.lua
             .load(crate::source::chunk(chunk))
@@ -1002,35 +760,20 @@ impl UiScript {
             .exec()
     }
 
-    /// Load and evaluate a Lua chunk, returning its result. Primarily for tests / one-shot queries.
+    /// Load and evaluate a Lua chunk, returning its result: for tests and one-shot queries.
     pub fn eval<T: mlua::FromLuaMulti>(&self, chunk: &str) -> mlua::Result<T> {
         self.lua.load(chunk).set_mode(mlua::ChunkMode::Text).eval()
     }
 
-    /// **How many values does `expr` return?** — the return-shape question, asked at the host
-    /// boundary instead of inside Lua.
-    ///
-    /// This is what `select('#', expr)` used to answer in ~170 of our own tests. `select` is not a
-    /// 1.12 global and is gone (`lua50::install`), and the replacement is not a workaround: a
-    /// binding's arity is a fact about the **binding ABI**, and on this side of it a multiple
-    /// return already *is* a `MultiValue` whose length nothing can round off. It keeps the property
-    /// the arity gates rest on — **zero values and one `nil` are different answers**, `0` and `1`
-    /// (`binding_abi`'s §2), which is exactly what a `Option<T>` return type cannot tell apart.
-    ///
-    /// `expr` is a Lua **expression**, not a chunk: pass `"GetItemInfo(1)"`, not `"return …"`.
-    /// A raise propagates — a call that errors has no arity, and swallowing that into `0` is how a
-    /// broken binding scores as a zero-return verb.
-    ///
-    /// The one place this cannot serve is a probe that has to hold the count *inside* Lua (a
-    /// `pcall` loop over generated calls, as `shape_gate` runs). There the 5.0 spelling is 1.12's
-    /// own and reads the same: `(function(...) return arg.n end)(expr)`.
+    /// How many values the Lua expression `expr` returns (`"GetItemInfo(1)"`, not a chunk), zero
+    /// values and one `nil` told apart; a raise propagates. `select` is not a 1.12 global, so
+    /// inside Lua the count is `(function(...) return arg.n end)(expr)`.
     pub fn arity(&self, expr: &str) -> mlua::Result<usize> {
         let values: mlua::Variadic<mlua::Value> = self.eval(&format!("return {expr}"))?;
         Ok(values.len())
     }
 
-    /// The owning frame's name for an [`ExtractedQuad`] target — a debugging affordance for
-    /// capture/probe tooling, which sees quads but not widgets ("whose quad is this?").
+    /// The owning frame's name for an [`ExtractedQuad`] target, for tooling that sees only quads.
     pub fn quad_owner_name(&self, target: ZTarget) -> Option<String> {
         let model = self.model_ref();
         let fh = match target {
@@ -1040,10 +783,8 @@ impl UiScript {
         model.arena.frame(fh)?.name.clone()
     }
 
-    /// Append a line to a named [`FrameKind::ScrollingMessageFrame`] (the app's chat feed → the seam,
-    /// the analogue of the loot/merchant snapshot pushes). `r`/`g`/`b` are `0..1`; the engine
-    /// byte-quantizes them round-half-up and drives the line's alpha via the fade. A missing frame,
-    /// or one of another kind, is a no-op (returns `false`) — the app decides whether that's a bug.
+    /// Append a line from the app's chat feed to the named ScrollingMessageFrame: `r`/`g`/`b` in
+    /// `0..1` are byte-quantized round-half-up, and the fade drives the line's alpha.
     pub fn add_chat_message(&mut self, frame: &str, text: &str, r: f32, g: f32, b: f32) -> bool {
         let mut model = self.model_mut();
         let Some(h) = model.arena.lookup(frame) else {
@@ -1058,10 +799,7 @@ impl UiScript {
         }
     }
 
-    /// Open the named EditBox for typing: show it and grab keyboard focus (so [`has_keyboard_focus`]
-    /// gates the world's keys). The app's chat-open key (ENTER) drives this; the box's own
-    /// `OnEnterPressed`/`OnEscapePressed` handlers hide + `ClearFocus` it on submit/cancel. A missing
-    /// frame, or one that isn't an EditBox, is a no-op (`false`).
+    /// Show the named EditBox and give it keyboard focus, for the app's chat-open key (ENTER).
     pub fn focus_editbox(&mut self, name: &str) -> bool {
         let mut model = self.model_mut();
         let Some(h) = model.arena.lookup(name) else {
@@ -1078,34 +816,23 @@ impl UiScript {
         true
     }
 
-    // The EditBox text-UI seam (advance table, caret/selection geometry, clipboard) lives in
-    // `editbox/seam.rs` — an `impl UiScript` block beside its concern, the layout.rs pattern.
-
-    /// Drain the chat lines submitted through the input EditBox since the last call (the
-    /// `SubmitChatInput` Lua binding queued them). The app parses each into an outbound chat command.
+    /// Drain the chat lines `SubmitChatInput` queued since the last call, for the app to parse.
     pub fn take_chat_input(&mut self) -> Vec<String> {
         std::mem::take(&mut self.model_mut().chat_input)
     }
 
-    /// Queue a line as if it had been typed into the chat EditBox and submitted — the headless
-    /// twin of `SubmitChatInput`, for scripted probes (`WOW_PROBE_CHAT`). Going through this seam
-    /// rather than straight to the wire is what lets a probe drive **client-side** slash commands
-    /// (`/duel`, `/reaction`); a plain line or a `.gm`-style server command still reaches the wire
-    /// exactly as before, because that is what the chat drain does with anything it doesn't own.
+    /// Queue a line as if typed into the chat EditBox and submitted, for probes (`WOW_PROBE_CHAT`).
     pub fn push_chat_input(&mut self, line: String) {
         self.model_mut().chat_input.push(line);
     }
 
-    /// Whether Tab was pressed in the chat edit box since the last call (`BenillaChatTabPressed`)
-    /// — the whisper-target cycle's trigger (decision 0288 P5).
+    /// Whether Tab was pressed in the chat edit box since the last call: the whisper cycle's cue.
     pub fn take_chat_tab(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().chat_tab)
     }
 
-    /// Replace the frame-keyed hyperlink spans (`(frame, rect, link, markup)`, rects in the
-    /// engine's y-up screen space) — the app feeds these each frame after rasterizing message
-    /// lines (it alone knows where the glyphs actually landed). A release inside a span fires
-    /// `OnHyperlinkClick(link, markup, button)` on the owning frame ([`pointer`]).
+    /// Replace the hyperlink spans `(frame, y-up rect, link, markup)` the app rasterized this
+    /// frame; a release inside one fires `OnHyperlinkClick` on its frame ([`pointer`]).
     pub fn set_link_spans(&mut self, spans: Vec<(FrameHandle, Rect, String, String)>) {
         let mut model = self.model_mut();
         model.link_spans.clear();
@@ -1118,17 +845,7 @@ impl UiScript {
         }
     }
 
-    /// Invoke a compiled handler `func` under the `0x704d50` frame-globals convention
-    /// (`this`/`self` = `wrapper`), the same set/restore path registry handlers use. For the
-    /// [`crate::loader`], which holds the `OnLoad` `Function` directly (to fire it bottom-up)
-    /// rather than through the registry: this keeps the convention in one home instead of
-    /// duplicating it. Errors are returned so the caller routes them (the loader records them in
-    /// its own report).
-    /// Whether the frame with this global name is effectively visible — shown, with every ancestor
-    /// shown (`IsVisible()`'s answer, read host-side). `false` for a name no live frame carries.
-    /// The read side of a window for a host that keeps state per window: the dressing-room feed
-    /// empties its booth when `DressUpFrame` hides, and the stock file has no hook of ours in its
-    /// OnHide to say so (1969). A linear scan, like [`Self::model_pane`], for the same reason.
+    /// Whether the frame with this global name is shown with every ancestor (`IsVisible()`).
     pub fn frame_visible(&self, name: &str) -> bool {
         self.model_ref()
             .arena
@@ -1136,12 +853,8 @@ impl UiScript {
             .any(|(_, f)| f.name.as_deref() == Some(name) && f.effective_visible)
     }
 
-    /// The effective alpha of the frame with this global name while it is effectively visible,
-    /// `None` when it is hidden or no live frame carries the name. The read side of a frame whose
-    /// pixels a host draws for the engine: the stock `MiniMapPing` is a `<Model>` this engine
-    /// renders nothing for, so the app's ping sprite follows the frame's own show/hide and alpha
-    /// — the lifetime the reference's `Minimap.lua` owns — instead of keeping a clock of its own
-    /// (1974). A linear scan, like [`Self::frame_visible`].
+    /// The named frame's effective alpha while it is effectively visible: the app's minimap ping
+    /// sprite follows the stock `MiniMapPing` `<Model>` this way.
     pub fn frame_effective_alpha(&self, name: &str) -> Option<f32> {
         self.model_ref()
             .arena
@@ -1150,22 +863,15 @@ impl UiScript {
             .map(|(_, f)| f.effective_alpha)
     }
 
-    /// Resolve every frame's rect: sync each frame's effective scale from the arena into its layout
-    /// input, run the [`crate::layout`] graph (screen root as the external base), and cache the
-    /// resolved rects. `GetWidth`/`GetHeight`/`extract` read this cache.
-    /// Frames whose size moved fire `OnSizeChanged` here, once the borrow is released
-    /// ([`event::fire_size_changes`]) — this is the drain the resolver's queue exists for, and the
-    /// one every per-frame host tick runs.
+    /// Resolve and cache every frame's rect, which `GetWidth`/`GetHeight`/`extract` read, then fire
+    /// `OnSizeChanged` for frames whose size moved ([`event::fire_size_changes`]).
     pub fn resolve(&mut self) {
         {
             let mut model = self.model_mut();
             Self::resolve_layout(&mut model);
         }
-        // With a font engine installed ([`Self::set_text_measurer`]) the VM closes the measure
-        // round-trip itself, right here — solve, measure what the solve revealed, solve again.
-        // That is the same two-solve shape the host's own drive loop already runs, moved inside so
-        // a FontString's box is right in the frame its text was set rather than the frame after.
-        // Without an engine this is a no-op and the host's batch pass stays the only answer.
+        // With a font engine installed ([`Self::set_text_measurer`]), measure what the solve
+        // revealed and solve again, so a FontString's box is right in the frame its text was set.
         if self.fill_measures() {
             let mut model = self.model_mut();
             Self::resolve_layout(&mut model);
@@ -1173,14 +879,9 @@ impl UiScript {
         event::fire_size_changes(&self.lua);
     }
 
-    /// Store host measurements for [`MeasureRequest`]s (`(id, w, h, natural_w, key)` — id/key
-    /// verbatim from the request). The next [`UiScript::resolve`] uses `w`/`h` as the FontStrings'
-    /// implicit size.
-    ///
-    /// `w`/`h` are the text **as laid out** (wrapped inside a declared width); `natural_w` is what
-    /// it would take **unwrapped**, and is what `GetStringWidth` reports — see [`MeasuredText`] for
-    /// why the two must not be conflated. For a region with no declared width they are the same
-    /// number, which is why [`Self::set_measured_text_unwrapped`] exists for tests.
+    /// Store host measurements `(id, w, h, natural_w, key)` for [`MeasureRequest`]s; the next
+    /// [`UiScript::resolve`] sizes the FontStrings by `w`/`h`, the text as laid out (wrapped in a
+    /// declared width), while `natural_w` is its unwrapped width, which `GetStringWidth` reports.
     pub fn set_measured_text(&mut self, measures: &[(u32, f32, f32, f32, u64)]) {
         let mut model = self.model_mut();
         for &(id, w, h, natural_w, key) in measures {
@@ -1195,25 +896,19 @@ impl UiScript {
                     natural_w,
                     key,
                 };
-                // The KEY always lands (or the region re-requests its own measure forever); the
-                // EPOCH moves only if the laid-out extent did — see `MeasuredText::layout_moved`.
+                // The key always lands, or the region re-requests forever; the epoch moves only
+                // with the laid-out extent.
                 moved = MeasuredText::layout_moved(d.measured, new);
                 d.measured = Some(new);
             }
             if moved {
-                // Measured extents are the auto-size axes' inputs — the layout gate's read set.
-                // Touched PER REGION rather than once for the batch (decision 1388): the batch
-                // touch could only say "some extent moved", which is exactly the whole-roster
-                // question the ledger exists to stop asking.
+                // Touched per region, so the layout gate need not re-walk the whole roster.
                 model.touch_layout_region(rh);
             }
         }
     }
 
-    /// [`Self::set_measured_text`] for text with **no wrap constraint**, where the laid-out and
-    /// natural widths are by definition the same number. Test-facing: a hand-fed measure for an
-    /// unconstrained string should not have to say `w` twice, and a test that DOES care about the
-    /// distinction (a declared-width region) should be forced to spell it out.
+    /// [`Self::set_measured_text`] for unwrapped text, whose two widths are one; for tests.
     pub fn set_measured_text_unwrapped(&mut self, measures: &[(u32, f32, f32, u64)]) {
         let widened: Vec<_> = measures
             .iter()
@@ -1222,28 +917,8 @@ impl UiScript {
         self.set_measured_text(&widened);
     }
 
-    /// Drop every cached host text metric — FontString measures, message-line row counts, editbox
-    /// advance tables. The host calls this when its **raster environment** changes (a window
-    /// resize / fullscreen toggle / uiScale move — anything that shifts the px-per-unit seam its
-    /// answers were taken under): glyph advances step to whole pixels at the drawn raster size,
-    /// so a metric measured under one environment does not rescale to another — the font-size
-    /// snap alone moves a string's unit width by several percent, which is exactly enough for a
-    /// boot-size measure to fail the post-resize ellipsis fit test and truncate text that fits
-    /// (the director's fullscreen "Contr..." rows). The environment is the host's to watch — the
-    /// engine deliberately never sees the seam scale — so staleness is the host's to declare; the
-    /// round-trips re-answer on the frames that follow (the same one-frame convergence every
-    /// measure already has).
-    /// Force the next [`UiScript::resolve`] to rebuild the **whole** layout graph rather than the
-    /// dirty closure a scoped resolve would (decision 1350) — and to run at all, rather than stop
-    /// at either change gate.
-    ///
-    /// This is the scoped resolve's own falsifier, and it exists so the claim the scope rests on —
-    /// *a node whose own inputs and whose dependencies did not move recomputes to the rect it
-    /// already holds* — is something a test can **disprove** rather than something the engine
-    /// argues. Drive a change, resolve, read the rects; call this, resolve again, read them again;
-    /// they must be identical. `WOW_LAYOUT_VERIFY` makes the same comparison automatically on every
-    /// SETTLED frame; this is for the frames that never settle, which is exactly the hover sweep
-    /// the scope was built for.
+    /// Force the next [`UiScript::resolve`] past both change gates to rebuild the whole layout
+    /// graph: the scoped resolve's falsifier, as a full rebuild must reach the same rects.
     pub fn force_full_layout_resolve(&mut self) {
         let mut model = self.model_mut();
         model.layout_scope.invalidate();
@@ -1252,14 +927,15 @@ impl UiScript {
         model.touch_layout();
     }
 
+    /// Drop every cached host text metric when the host's raster environment changes (resize,
+    /// fullscreen, uiScale): glyph advances snap to whole pixels at the drawn size, so a stale
+    /// measure can fail the ellipsis fit and truncate text that fits.
     pub fn invalidate_text_measures(&mut self) {
         let mut model = self.model_mut();
         for d in model.region_data.values_mut() {
             d.measured = None;
         }
-        // The frame-side caches key on content hashes; a bumped stored key can never equal the
-        // recomputed one, so the next needing-measure sweep re-requests without this method
-        // having to know what the keys hash.
+        // A bumped key never matches the recomputed content hash, so the next sweep re-requests.
         for (_, frame) in model.arena.iter_frames_mut() {
             match &mut frame.kind_state {
                 KindState::ScrollingMessage(smf) => {
@@ -1273,35 +949,20 @@ impl UiScript {
                 _ => {}
             }
         }
-        // Measured extents are auto-size inputs — the layout gate's read set, same as
-        // [`Self::set_measured_text`]'s.
+        // Measured extents are auto-size inputs, the layout gate's read set.
         model.touch_layout();
         // Every stored measure was just wiped; only the whole-roster sweep can re-request them.
         model.touch_measure_all();
     }
 
-    // ── Input: pointer-leaves-window cleanup (decision 0216 §3; the hit-test/mouse dispatch that
-    // used to sit here now lives in [`pointer`]) ─────────────────────────────────────────────────
+    // ── Input: the pointer leaving the window ────────────────────────────────────────────────────
 
-    /// The OS pointer left the window (decision 0216 §3's drag-gesture leak): clears
-    /// [`Model::drag`] AND [`Model::mouse_down_on`] — the two press-tracked states nothing else
-    /// clears when the pointer leaves the window mid-press, since the matching release is never
-    /// fed. Left uncleared, a stale armed [`Model::drag`] would fire a spurious `OnDragStart` the
-    /// instant the pointer re-enters and crosses the threshold against a press point that no
-    /// longer means anything; a stale [`Model::mouse_down_on`] entry would fire a same-frame
-    /// `OnClick` if the pointer re-enters and releases over the very frame it left from. The app
-    /// calls this from the same branch that fires the synthetic `OnLeave` (`ui_script/input.rs`).
+    /// The OS pointer left the window, so no release will be fed: clears [`Model::drag`], which
+    /// would start a drag on re-entry, and [`Model::mouse_down_on`], which would click the frame
+    /// it left. The app calls it where it fires the synthetic `OnLeave`.
     pub fn pointer_left_window(&mut self) {
-        // **A started drag ENDS here, it is not merely forgotten.** The reference cannot reach
-        // this state at all — the OS holds the pointer for the whole of a button-held drag, so its
-        // release always arrives and `OnDragStop` always runs. Ours has no such capture: walk the
-        // cursor off the window edge mid-drag and no release is ever fed. Dropping the gesture
-        // silently (what this did) leaves the addon's `OnDragStop → StopMovingOrSizing` unrun, so
-        // the engine's single `Model::moving` slot stays taken and `object::movable::advance_move`
-        // glues that frame to the cursor for the rest of the session — where it also swallows
-        // every press aimed at whatever is underneath. That is B310: one raid row dragged off the
-        // window edge, and no row could be dragged again. Firing the stop is the faithful end,
-        // because it is the same end the reference's own release gives the handler.
+        // A started drag ends with `OnDragStop`, as the reference's release always ends it; dropped
+        // silently, its `StopMovingOrSizing` never runs and the frame stays glued to the cursor.
         let abandoned = {
             let mut model = self.model_mut();
             cursor::abandon_drag(&mut model)
@@ -1312,95 +973,61 @@ impl UiScript {
         let mut model = self.model_mut();
         let held: Vec<crate::widget::FrameHandle> = model.mouse_down_on.values().copied().collect();
         model.mouse_down_on.clear();
-        // Every button that capture was holding down goes back to NORMAL — the release edge the
-        // OS never fed us (`0x7793de`), without which a button walked off the window edge
-        // mid-press keeps its pushed art for the rest of the session.
+        // Every held button gets the release edge never fed (`0x7793de`), else it stays pushed.
         for h in held {
             button::edge(&mut model, h, crate::widget::ButtonState::on_mouse_up);
         }
-        // …and its one-slot twin `root+0x80`, which the mouse-down raise reads: a capture left
-        // behind would aim the next press's raise at whatever the pointer was last holding.
+        // The capture slot (`root+0x80`) too: a stale one aims the next press's raise at it.
         model.mouse_capture = None;
-        // [`Model::last_click`] is deliberately NOT cleared here. It looks like it belongs in this
-        // list, and the binary says otherwise: `[CButton+0x334]` has exactly three writers
-        // image-wide (the ctor, the fired-double zero, the fired-single stamp) and none of them is
-        // a hide, a disable, or a mouse-leave — so a half-finished double click really does survive
-        // the cursor leaving the window and coming back inside the 300 ms.
-        // A thumb drag in progress when the pointer leaves is abandoned too (decision 0250 §5) —
-        // the release that would end it is never fed, same leak as the drag gesture above.
+        // [`Model::last_click`] stays: `[CButton+0x334]` has no writer on leave, hide or disable,
+        // so a double click survives the cursor leaving and returning within 300 ms.
+        // A slider thumb drag is abandoned too: its release is never fed either.
         model.slider_drag = None;
     }
 
-    // ── Keyboard entry (the EditBox focus + key/char routing law below) ──────────────────────────
+    // ── Keyboard entry ───────────────────────────────────────────────────────────────────────────
     //
-    // benilla speaks *key names*, not scancodes — the host maps its window keycodes to these. The
-    // routing is the client's exactly: if a box is focused it processes and CONSUMES every event; if
-    // none is focused, the topmost effectively-visible `autoFocus` box self-acquires focus and
-    // processes this same event; otherwise nothing is consumed. Today the ways a box gets focus here
-    // are this self-acquire path, a click, and Lua `SetFocus` — the reference has a fourth, an
-    // `autoFocus` box focusing itself on SHOW, which we do not implement yet (the flag's own doc
-    // carries the correction and what it waits on).
+    // Keys arrive by name; the host maps its keycodes. The box routing: a focused box consumes
+    // every event; with none focused, the topmost visible `autoFocus` box takes focus and
+    // processes that same event; otherwise nothing is consumed.
 
-    /// A typed character (may be multi-byte UTF-8) arriving from the host. Routes per that law and,
-    /// on a focused box, inserts it (numeric/cap/password rules apply) or — for the Ctrl+A control
-    /// code — selects all. Returns `true` if consumed (a focused box consumes every char).
+    /// A typed character (UTF-8) from the host: a focused box inserts it (numeric, cap and
+    /// password rules apply) or, for Ctrl+A's control code, selects all. `true` if consumed.
     pub fn char_input(&mut self, text: &str) -> bool {
-        // The frame walk first ([`keyboard`]): the focused box is a PARTICIPANT in it, at its own
-        // strata/level, so this is not "frames before boxes" — it is the reference's one dispatcher
-        // in the reference's order. An event no frame consumed still falls through to the box
-        // routing, which owns focus acquisition (`autoFocus` self-acquire and kin).
+        // The frame walk first ([`keyboard`]), the focused box a participant at its own strata and
+        // level, as in the reference's one dispatcher; an unconsumed event goes to the box routing.
         keyboard::char_input(&self.lua, text) || editbox::char_input(&self.lua, text)
     }
 
-    /// Paste text from the host OS clipboard into the focused EditBox. The engine-free runtime can't
-    /// reach the clipboard itself, so the app reads it (Cmd+V on macOS / Ctrl+V elsewhere) and hands
-    /// the string here; newlines survive only in a `multiLine` box, other control chars are dropped,
-    /// and the remainder inserts as one edit. Returns `true` if a box consumed it.
+    /// Paste host clipboard text into the focused EditBox as one edit: newlines survive only in a
+    /// `multiLine` box, other control characters drop. `true` if a box consumed it.
     pub fn paste(&mut self, text: &str) -> bool {
         editbox::paste(&self.lua, text)
     }
 
-    /// A non-character key press arriving from the host, by name — the three *box-event* keys
-    /// (`"ENTER"`, `"ESCAPE"`, `"TAB"`) fire their FrameXML scripts; editing keys arrive as
-    /// semantic [`EditAction`]s via [`Self::editbox_action`] instead (the host's per-OS keymap
-    /// owns which chord means what). Routes per that law; a focused box consumes the key even when
-    /// it does nothing with it. Returns `true` if consumed.
+    /// A non-character key by name (`"ENTER"`, `"ESCAPE"`, `"TAB"`); editing keys come through
+    /// [`Self::editbox_action`]. A focused box consumes a key even when it does nothing with it.
     pub fn key_input(&mut self, key: &str) -> bool {
-        // Same two-stage shape as `char_input` — see its note.
+        // The same two stages as `char_input`.
         keyboard::key_input(&self.lua, key) || editbox::key_input(&self.lua, key)
     }
 
-    /// A key the host delivers to a focused EditBox as an [`EditAction`] chord rather than by name
-    /// (BACKSPACE, DELETE, the arrows, HOME, END), offered to the **keyboard frames** first.
-    ///
-    /// Returns `true` if a frame consumed it, in which case the caller must NOT also dispatch the
-    /// chord — and the key's binding must not fire either (consumption suppresses it, `0x76b7d0`).
-    /// A `false` means either nothing wanted it or the focused box owns it; the caller proceeds
-    /// exactly as it did before this entry point existed. See [`keyboard::frame_key_input`] for
-    /// why declining at the box is the faithful answer rather than skipping it.
+    /// An editing key (BACKSPACE, DELETE, the arrows, HOME, END) offered to the keyboard frames
+    /// before the focused box gets it as an [`EditAction`]. On `true` the caller dispatches neither
+    /// the action nor the key's binding (consumption suppresses it, `0x76b7d0`).
     pub fn frame_key_input(&mut self, key: &str) -> bool {
         keyboard::frame_key_input(&self.lua, key)
     }
 
-    /// One semantic text-editing operation on the focused EditBox — the output of the host's
-    /// per-OS keymap (decision 0301). Same routing/consumption law as [`Self::key_input`].
-    /// Returns `true` if consumed.
+    /// One text-editing operation on the focused EditBox, from the host's per-OS keymap.
     pub fn editbox_action(&mut self, action: EditAction) -> bool {
         editbox::action(&self.lua, action)
     }
 
-    /// Is the focused EditBox in **alt-arrow mode** — the flag the XML spells `ignoreArrows` and
-    /// the Lua surface spells `SetAltArrowKeyMode` (`[editbox+0x318] & 0x10`)?
-    ///
-    /// The host asks this to decide whether an arrow key reaches the box at all. With the flag set
-    /// and ALT not held, the reference's key handler returns 0 at `0x77b1c4` for the four arrow
-    /// codes — **not consumed** — and the strata walk carries down to `CGWorldFrame`, which runs
-    /// the key's binding. That is what lets you turn while the chat box has focus, and it is why
-    /// the gate is on the key rather than on the [`EditAction`]: `Move { unit: Edge }` reaches the
-    /// box from HOME/END as well as from an arrow, and only the arrow is gated.
-    ///
-    /// `false` when nothing is focused, which is the same answer as an unflagged box: neither
-    /// declines the key.
+    /// Whether the focused EditBox is in alt-arrow mode (XML `ignoreArrows`, Lua
+    /// `SetAltArrowKeyMode`, `[editbox+0x318] & 0x10`): without ALT the reference declines the four
+    /// arrows (`0x77b1c4`), so they reach the world's bindings and turn the player while chat has
+    /// focus. The gate is on the key, not the [`EditAction`]: HOME and END also move to an edge.
     pub fn editbox_alt_arrow_mode(&self) -> bool {
         let model = self.model_ref();
         model.focused_editbox.is_some_and(|h| {
@@ -1412,8 +1039,8 @@ impl UiScript {
         })
     }
 
-    /// Whether an EditBox currently holds keyboard focus (and is effectively visible) — the app gates
-    /// world/player key input on this, matching the client's `DAT_00cf4dc8 != 0` test.
+    /// Whether a visible EditBox holds keyboard focus, which gates the world's keys as the client's
+    /// `0xcf4dc8 != 0` test does.
     pub fn has_keyboard_focus(&self) -> bool {
         let model = self.model_ref();
         model
@@ -1421,119 +1048,67 @@ impl UiScript {
             .is_some_and(|h| model.arena.frame(h).is_some_and(|f| f.effective_visible))
     }
 
-    /// **Which** EditBox holds the focus, by name — [`Self::has_keyboard_focus`] answers
-    /// *whether*. Unfiltered by visibility, because the focus cell itself is: a box that hides
-    /// while focused keeps the cell until something clears it, and the tests that watch the
-    /// hand-off between two boxes are watching exactly that cell.
-    ///
-    /// This is the host-side read of `Model::focused_editbox`. There is no Lua verb for it and
-    /// there must not be: 1.12's EditBox table has `SetFocus`/`ClearFocus` and no getter, which
-    /// is why `pfQuest/browser.lua:760` ships its own focus flag rather than asking (decision
-    /// 2142).
+    /// The focused EditBox's name, unfiltered by visibility, unlike [`Self::has_keyboard_focus`].
+    /// Host-side only: 1.12's EditBox table has `SetFocus`/`ClearFocus` and no getter.
     pub fn focused_editbox_name(&self) -> Option<String> {
         let model = self.model_ref();
         let h = model.focused_editbox?;
         model.arena.frame(h)?.name.clone()
     }
 
-    /// How many resolves the layout change gate has let through (`Model::layout_solves`) — the
-    /// gate's effectiveness, readable by tests and the app's cost meters (a per-frame delta of 0
-    /// means the fingerprint judged the frame quiet).
+    /// Resolves the layout change gate let through; a per-frame delta of 0 means a quiet frame.
     pub fn layout_solves(&self) -> u64 {
         self.model_ref().layout_solves
     }
 
-    /// How many resolves got past **tier 1** and paid the whole-roster preamble
-    /// ([`Model::layout_gate_walks`], decision 1385) — the gate's true cost counter, ≥
-    /// [`Self::layout_solves`] because a walk that concludes "nothing moved" pays the same
-    /// preamble and never reaches the solve counter.
+    /// Resolves past tier 1, which pay the whole-roster preamble ([`Model::layout_gate_walks`]):
+    /// the gate's true cost, at least [`Self::layout_solves`], since a walk may find nothing moved.
     pub fn layout_gate_walks(&self) -> u64 {
         self.model_ref().layout_gate_walks
     }
 
-    /// How many times a resolve DERIVED the layout graph from scratch ([`Model::layout_derives`])
-    /// — the whole-roster walk, and since decision 1388 the only expensive thing a resolve can do.
-    /// A UI that merely animates should hold this flat.
+    /// Whole-graph layout derivations, a resolve's one expensive step; flat while a UI animates.
     pub fn layout_derivations(&self) -> u64 {
         self.model_ref().layout_derives
     }
 
-    /// Total fixpoint ROUNDS across every solve ([`Model::layout_rounds`]) — a solve costs
-    /// rounds × the whole graph, so the ratio against [`Self::layout_solves`] is the per-pass
-    /// depth.
+    /// Fixpoint rounds across every solve; over [`Self::layout_solves`], the per-pass depth.
     pub fn layout_rounds(&self) -> u64 {
         self.model_ref().layout_rounds
     }
 
-    /// The last solve's SCOPE — `(frames solved, regions swept)`, decision 1350's meter.
-    ///
-    /// The third axis of a solve's cost, and the one that used to be "all of it": solves says how
-    /// OFTEN, rounds says how DEEP, this says how WIDE. A change that touches ten FontStrings must
-    /// read a handful here however large the UI grows; a scope that tracks the graph is the
-    /// regression, and it is asserted as a COUNT because milliseconds have twice failed to catch
-    /// this class (0735, 0771).
+    /// The last solve's scope, `(frames solved, regions swept)`: a change to ten FontStrings must
+    /// read a handful here however large the UI grows.
     pub fn layout_last_scope(&self) -> (usize, usize) {
         self.model_ref().layout_last_scope
     }
 
-    /// Is `name` a registered FrameXML template — one `CreateFrame`'s fourth argument or an
-    /// `inherits=` can resolve (decision 1203)?
-    ///
-    /// A pure query on the VM's live registry, for the corpus harness: an addon naming a template
-    /// we have not transcribed gets a bare frame and **no load error**, so nothing else can see it.
-    /// **Folded**, because the resolution it reports on is folded. An exact `contains_key` made this
-    /// census disagree with the loader the moment `inherits=` became case-insensitive: it went on
-    /// listing `UIDropdownMenuTemplate`, `CT_RaCheckButtonTemplate` and `MSBTColorSwatchTemplate` as
-    /// missing while the loader was resolving all three. An instrument that reports a gap the code
-    /// does not have is worse than no instrument — it is a build queue pointing at finished work
-    /// (1242/1246, and 1251 §3's rule that a source-derived answer be checked against the runtime
-    /// artefact).
+    /// Whether `name` is a registered FrameXML template, case-folded as the loader resolves it, for
+    /// the corpus harness: an addon naming a missing template gets a bare frame and no load error.
     pub fn has_framexml_template(&self, name: &str) -> bool {
         let model = self.model_ref();
         let templates = model.framexml_templates.borrow();
         templates.contains_key(name) || templates.keys().any(|k| k.eq_ignore_ascii_case(name))
     }
 
-    /// Is `name` a registered FONT object — the *other* thing an `inherits=` may legally name?
-    ///
-    /// [`Self::has_framexml_template`]'s twin, and only useful beside it: `inherits=` is one
-    /// attribute over two namespaces (`<FontString inherits="GameFontNormal">` names a font,
-    /// `<Button inherits="UIPanelButtonTemplate">` names a template — `loader::expand_region` is
-    /// where that fork lives). A census that asks only the template registry reports every font in
-    /// the corpus as a missing template.
+    /// Whether `name` is a registered font object, the other namespace an `inherits=` may name
+    /// (`loader::expand_region` forks on it), so a census counts no font as a missing template.
     pub fn has_font_object(&self, name: &str) -> bool {
         self.model_ref().font_object(name).is_some()
     }
 
-    /// The **widget kind of a published name** — `"MessageFrame"`, `"Button"`, `"Texture"`, … — or
-    /// `None` if nothing by that name is a live widget.
-    ///
-    /// [`Self::has_framexml_template`]'s sibling, and the same kind of thing: a pure Rust-side query
-    /// on the live model, for the corpus harness. The harness needs to know what `UIErrorsFrame` in
-    /// `UIErrorsFrame:AddMessage(…)` actually *is* in our object graph, because a widget-method
-    /// census that asks "does ANY kind answer this name" cannot see a verb wired to one class and
-    /// forgotten on its sibling (decision 1228). Attributing the call site to a kind is what makes
-    /// that question askable, and this is the only honest answer to "what kind is that global": the
-    /// arena's own record, not a name list.
-    ///
-    /// **Deliberately NOT a Lua binding.** The reference publishes this as `GetObjectType`, which we
-    /// do not implement outside font objects; adding it here would put a new verb in front of every
-    /// addon and move the very numbers the census is measured by. An instrument must be able to
-    /// claim it perturbed nothing, so it stays on the Rust side where no addon can observe it.
-    ///
-    /// The spellings are `CreateFrame`'s own (`SimpleHTML`, not `SimpleHtml`), so a caller can
-    /// compare a name here against a kind it passed to `CreateFrame`.
+    /// The widget kind of a published name, in `CreateFrame`'s spelling (`SimpleHTML`): host-side,
+    /// for the corpus harness to attribute a call site to a class unseen by any addon.
     pub fn widget_kind(&self, name: &str) -> Option<&'static str> {
         let model = self.model_ref();
         if let Some(h) = model.arena.lookup(name) {
             return model.arena.frame(h).map(|f| match f.kind {
                 crate::widget::FrameKind::Frame => "Frame",
-                // A `Frame` to Lua (1984): the registered name never becomes a class identity.
+                // A `Frame` to Lua: the registered name never becomes a class.
                 crate::widget::FrameKind::WorldFrame => "Frame",
                 crate::widget::FrameKind::Button => "Button",
                 crate::widget::FrameKind::CheckButton => "CheckButton",
-                // `GetObjectType 0x495b60` is two instructions and returns `"LootButton"`
-                // (`[0x847ce0]` → `0x843414`). It does NOT answer "Button".
+                // `GetObjectType` (`0x495b60`) says "LootButton" (`[0x847ce0]` → `0x843414`).
                 crate::widget::FrameKind::LootButton => "LootButton",
                 crate::widget::FrameKind::EditBox => "EditBox",
                 crate::widget::FrameKind::StatusBar => "StatusBar",
@@ -1552,16 +1127,13 @@ impl UiScript {
                 crate::widget::FrameKind::Minimap => "Minimap",
             });
         }
-        // The region leaves publish into their own name table (`region_names`), not the arena's —
-        // and they matter here: `GameTooltipTextLeft1:GetText()` is a FontString call, and the
-        // corpus scrapes those constantly.
+        // Region leaves publish into their own name table, not the arena's.
         let id = *model.region_names.get(name)?;
         let h = *model.id_to_region.get(&id)?;
         model.arena.region(h).map(|r| match r.kind {
             crate::widget::RegionKind::Texture => "Texture",
             crate::widget::RegionKind::FontString => "FontString",
-            // A title region is a plain Region and says so (`0x76c440`) — and it is unreachable by
-            // name anyway: `CreateTitleRegion` takes no name argument at all.
+            // A title region is a plain Region (`0x76c440`); `CreateTitleRegion` takes no name.
             crate::widget::RegionKind::Title => "Region",
         })
     }
@@ -1581,47 +1153,28 @@ impl UiScript {
         self.model_ref().warnings.clone()
     }
 
-    /// Drain the accumulated non-fatal host warnings (an ignored `CreateFrame` template, a layout
-    /// fixpoint that hit its round cap) — the host logs them; un-drained they pile up unseen.
+    /// Drain the non-fatal host warnings, for the host to log.
     pub fn take_warnings(&mut self) -> Vec<String> {
         std::mem::take(&mut self.model_mut().warnings)
     }
 
-    /// Report a script error the host caught **outside** the VM's own dispatch — an addon file
-    /// that failed to compile or raised at file scope during the load walk. It joins the
-    /// handler-dispatch queue and the retained log, but **not** `errors`: the caller has already
-    /// logged it (the load walk's per-file `error!` + `failures` contract), so putting it there too
-    /// would double-log at the app's per-frame drain.
-    ///
-    /// Its silent sibling is [`Self::report_load_failure`] (decision 1495) — same retention, no
-    /// dispatch, for the load failures that never raise at all.
+    /// Report a script error the host caught outside the VM's dispatch (an addon file that failed
+    /// to compile or raised at file scope): it joins the handler-dispatch queue and the retained
+    /// log, not `errors`, since the caller has already logged it.
     pub fn report_script_error(&self, msg: &str) {
-        // Retained as a **Load** row, not an Error one (decision 1495): every caller of this is
-        // the load walk, and from the player's side "the addon's file scope raised" and "the
-        // addon's file was missing" are the same fact — the addon is not running. The retention
-        // half is `diagnostics::record_load_failure`, shared with the demand-load path so the
-        // rule has one implementation (2107); the dispatch is what makes this the loud sibling.
+        // A Load row, not an Error one: to the player a file scope that raised and a missing file
+        // are the same fact, the addon is not running.
         diagnostics::record_load_failure(&self.lua, msg);
         self.model_mut()
             .pending_error_dispatch
             .push(msg.to_string());
     }
 
-    /// Hand every queued script error to the Lua-side error handler — the reference's own shape:
-    /// `seterrorhandler`/`geterrorhandler` are engine globals (`0x702900`/`0x702950`,
-    /// the captured `_G`), the engine invokes the registered handler on a caught script error
-    /// (that is the pair's contract — a handler nothing invokes would be two dead globals), and
-    /// FrameXML answers with `_ERRORMESSAGE` → the red ScriptErrors dialog (decision 1305).
-    ///
-    /// Called at a safe seam (the app's per-frame drain), never from inside the failed call.
-    /// Three guards keep it bounded and honest:
-    /// - **The stdlib default handler is skipped by identity.** It reports into
-    ///   [`UiScript::errors`] — where every queued message already is — so dispatching it would
-    ///   only duplicate. The queue still drains, so a handler installed later starts clean.
-    /// - **A handler that raises is recorded on the host channel only** and never re-queued:
-    ///   the error path cannot recurse by construction.
-    /// - **One failure stops the batch** — a broken handler fails the same way for every message,
-    ///   and one line names it.
+    /// Hand each queued script error to the Lua error handler, as the reference invokes the one
+    /// `seterrorhandler`/`geterrorhandler` (`0x702900`/`0x702950`) hold on a caught error;
+    /// FrameXML installs `_ERRORMESSAGE`, the ScriptErrors dialog (`BasicControls.xml:16`). The
+    /// stdlib default is skipped, as it already reported into [`UiScript::errors`]; a handler that
+    /// raises is recorded on the host channel only and stops the batch, so the path cannot recurse.
     pub fn dispatch_script_errors_to_handler(&mut self) {
         let pending = std::mem::take(&mut self.model_mut().pending_error_dispatch);
         if pending.is_empty() {
@@ -1652,30 +1205,23 @@ impl UiScript {
         }
     }
 
-    /// Register a named virtual [`FontObject`] (a resolved `<Font>`), overwriting any prior one of
-    /// the same name, **and publish it as the Lua global `name`** — the same pair
-    /// `Loader::do_font` performs, so a font registered from Rust is addressable from Lua exactly
-    /// like one declared in XML (`fs:SetFontObject(Name)`, `Name:GetFont()`). One registration act,
-    /// one outcome: the two paths cannot drift.
+    /// Register a named [`FontObject`] (a resolved `<Font>`), replacing any of that name, and
+    /// publish it as the Lua global `name`, the same pair `Loader::do_font` performs.
     pub fn register_font_object(&self, name: &str, font: FontObject) {
         self.model_mut()
             .font_objects_by_lower
             .insert(name.to_ascii_lowercase(), font);
-        // Publishing cannot fail for a fresh table + a string key; a registry hiccup is not worth
-        // an unwrap in a host-facing setter, and the record is already in place either way.
+        // Publishing a fresh table under a string key cannot fail; the record is in place anyway.
         let _ = font::publish(&self.lua, name);
     }
 
-    /// Look up a registered [`FontObject`] by name (the resolved paint), if any. Used by tests and by
-    /// the `SetFontObject` binding.
+    /// A registered [`FontObject`] by name: its resolved paint.
     pub fn font_object(&self, name: &str) -> Option<FontObject> {
         self.model_ref().font_object(name).cloned()
     }
 
-    /// Every registered [`FontObject`] (the resolved paints of all loaded `<Font>` nodes) — the
-    /// host's bake census: the glyph atlas reads the distinct `(font, height, outline)` triples
-    /// off this to know which outlined cell variants the shipped UI can actually request
-    /// (the outlined-glyph bake, the fade-composite fold-back record).
+    /// Every registered [`FontObject`]: the glyph atlas bakes outlined cells for the distinct
+    /// `(font, height, outline)` triples here.
     pub fn font_objects(&self) -> Vec<FontObject> {
         self.model_ref()
             .font_objects_by_lower
diff --git a/crates/benilla-ui/src/script/model.rs b/crates/benilla-ui/src/script/model.rs
index e924fd1e..f8e1761a 100644
--- a/crates/benilla-ui/src/script/model.rs
+++ b/crates/benilla-ui/src/script/model.rs
@@ -12,23 +12,18 @@ use super::{
     PlayerReqState, RegionData, ScriptValue, SoundRequest, UnitState,
 };
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The Rust-side model (plain data; lives in lua.app_data)
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The Rust-side model ──
 
-/// The host's texture-path resolvability oracle — see [`Model::texture_probe`].
+/// The host's answer to whether a texture path resolves to a file.
 pub type TextureProbe = Box<dyn Fn(&str) -> bool>;
 
-/// The host's texture **texel-size** oracle — see [`Model::texture_size_probe`].
+/// The host's answer to a texture path's size in texels.
 pub type TextureSizeProbe = Box<dyn Fn(&str) -> Option<(u32, u32)>>;
 
-/// The host's font-path resolvability oracle — see [`Model::font_probe`].
+/// The host's answer to whether a font path loads.
 pub type FontProbe = Box<dyn Fn(&str) -> bool>;
 
-/// A map from a minted object id to its handle, indexed directly: ids are dense (`next_id`
-/// counts from 1), and every scripted method call on a frame or region starts with this lookup
-/// — a few hundred a frame from the stock `OnUpdate` sweep alone (decision 1979's UI tick), so
-/// the hash a `HashMap` paid per call was the wrong price for a one-word index.
+/// Minted id to handle, indexed directly: ids are dense and every scripted call looks one up.
 #[derive(Debug, Clone)]
 pub(crate) struct IdMap<T>(Vec<Option<T>>);
 
@@ -57,1309 +52,645 @@ impl<T: Copy> IdMap<T> {
     }
 }
 
-/// The Rust-side model behind the Lua VM — the arena, the layout inputs + resolved rects, the
-/// id↔handle bijection, region visuals, and the event/script registrations. Held in `lua.app_data`
-/// (interior-mutable) so callbacks reach it; contains **no** mlua handles (the MAXCSTACK discipline).
+/// The Rust-side model behind the Lua VM, in `lua.app_data`. It holds no mlua handles, whose
+/// persistent count the vendored `LUAI_MAXCSTACK` caps.
 pub(crate) struct Model {
-    /// Every discovered addon, in load order — the AddOn API's registry, filled by the host at
-    /// world entry ([`super::UiScript::register_addons`]). See [`super::addon`].
+    /// Every discovered addon in load order: the AddOn API's registry, filled at world entry.
     pub(crate) addons: Vec<super::addon::AddOnInfo>,
-    /// **The Lua index space** — positions into [`Self::addons`], `## Title`-sorted and
-    /// hidden-filtered (decision 2175). NOT the registry: the reference keeps two structures and
-    /// they are different permutations of different sets (`0x51da70` rebuilds this one).
+    /// The Lua index space into `addons`, a title-sorted, hidden-filtered list (`0x51da70`).
     pub(crate) addon_index: Vec<usize>,
-    /// The lowercased names `SMSG_ADDON_INFO` marked `status = 2`, or **`None` when no reply has
-    /// arrived this session** — and `None` is why [`Self::addon_index`] can be legitimately empty
-    /// (decision 2175). `[0xbe1b90]` is zeroed by the registry reset `0x51fad1` and written
-    /// nowhere but the reply's own rebuild, so `GetNumAddOns()` really is 0 until the server
-    /// answers.
+    /// Lowercased names `SMSG_ADDON_INFO` marked `status = 2`; `None` until the reply arrives, and
+    /// until then `GetNumAddOns()` is 0, as in the reference (`[0xbe1b90]`, reset at `0x51fad1`).
     pub(crate) addon_info_hidden: Option<Vec<String>>,
     /// The AddOns folder, so `LoadAddOn` can read an addon's files from inside a Lua binding.
     pub(crate) addons_root: Option<std::path::PathBuf>,
-    /// The host's reader for a chain-sourced addon's files (`AddOnInfo::chain`), by
-    /// chain-internal path — `None` in a VM with no chain behind it, where such an addon
-    /// answers `MISSING`.
+    /// The host's reader for chain-sourced addon files; without one such an addon is `MISSING`.
     pub(crate) addons_chain_reader: Option<super::addon::SharedChainReader>,
-    /// The host's font engine ([`super::UiScript::set_text_measurer`]) — what lets a metric read
-    /// answer inside the Lua call that asked, instead of a frame later. `None` in every VM without
-    /// a font atlas, which is the measure round-trip's own world and behaves exactly as it did.
+    /// The host's font engine, so a metric answers inside the asking call, not a frame later.
     pub(crate) measurer: Option<Box<dyn super::TextMeasure>>,
-    /// The host's texture-path oracle ([`super::UiScript::set_texture_probe`]): does this sprite
-    /// reference resolve to a file — patch chain or loose addon folder? What lets the path form of
-    /// `SetTexture` return the reference's **1 | nil** load verdict inline (`0x79bb40` — Atlas
-    /// branches on it to pick its map art). `None` in an
-    /// engine-less VM (tests, the addon harness), where the path form keeps answering nil: no
-    /// backend, nothing loads — which is also exactly what those tests always saw.
+    /// Whether a texture path resolves (patch chain or loose addon file), so the path form of
+    /// `SetTexture` returns the reference's 1 or nil inline (`0x79bb40`). `None` answers nil.
     pub(crate) texture_probe: Option<TextureProbe>,
-    /// The host's texture **texel-size** oracle ([`super::UiScript::set_texture_size_probe`]): how
-    /// many texels wide and tall is the art at this path?
-    ///
-    /// What lets a region whose authored size on an axis is exactly `0` take its span from its
-    /// CONTENT, the way the real client's size getters do — `CSimpleTexture::GetWidth 0x770720` /
-    /// `GetHeight 0x770790` return the authored value only when it is not `0.0`, and otherwise read
-    /// the loaded texture's `[tex+0x144]`/`[tex+0x148]` through the same converter `<AbsDimension>`
-    /// uses, so **one texel is one FrameXML unit** (decision 1349). The host answers off the same
-    /// candidate walk the renderer decodes with and memoises,
-    /// so the size layout resolves with is the size the screen shows.
-    ///
-    /// `None` in an engine-less VM (tests, the addon harness), where a zero-size texture keeps the
-    /// rect it always had — there is no art to measure without a backend.
+    /// A path's texel size, which an axis authored as 0 takes, one texel per unit, as the client's
+    /// `GetWidth` (`0x770720`) and `GetHeight` (`0x770790`) do; `None` leaves it as authored.
     pub(crate) texture_size_probe: Option<TextureSizeProbe>,
-    /// The host's font-path oracle ([`super::UiScript::set_font_probe`]): does this font reference
-    /// load — patch chain or loose addon folder? What lets `SetFont`'s path form answer the
-    /// reference's **1 | nil**, whose nil is a *load failure* and not an argument error
-    /// (`0x79f345`/`0x79f361`, originating at `0x5c1ae0` under the `0x44d040`
-    /// font-factory cache) — `!OmniCC/main.lua:41`'s `if not Font:SetFont(saved, size) then
-    /// revert end` is exactly that probe.
-    ///
-    /// **`None` answers 1 for a non-empty path, which is where this differs from
-    /// [`Self::texture_probe`]** (decision 2103). A VM with no font backend has no font store to
-    /// fail against, so nil there would report a load failure that never happened — and it would
-    /// send `!OmniCC` down its revert branch in every harness run. The texture probe could take
-    /// the opposite default because nil was already what its engine-less callers observed; here 1
-    /// is.
+    /// Whether a font path loads: `SetFont`'s 1 or nil, nil meaning a load failure (`0x79f345`,
+    /// `0x79f361`, from `0x5c1ae0` in the `0x44d040` cache). Unlike `texture_probe`, `None` answers
+    /// 1 for a non-empty path: without a font backend nothing failed, and addons revert their font
+    /// on a nil.
     pub(crate) font_probe: Option<FontProbe>,
-    /// Where per-addon saved variables live: the account-scoped folder, then this character's.
-    /// Both are directories holding one `<Addon>.lua` per declaring addon.
+    /// Saved-variables folders, one `<Addon>.lua` each: the account's, then this character's.
     pub(crate) addons_saved_account: Option<std::path::PathBuf>,
     pub(crate) addons_saved_character: Option<std::path::PathBuf>,
-    /// The FrameXML **template registry**, persisted across [`crate::loader::load`] calls — the
-    /// client's template table is global (`0x6ee500`), so a file may `inherits=` a template
-    /// an *earlier file* registered (the real MerchantFrame.xml inherits
-    /// CharacterFrameTemplates.xml's tab template). Register-before-use in load order, exactly
-    /// the client's rule; a per-document registry silently dropped every cross-file inherit.
-    ///
-    /// **Here rather than on `UiScript`** so the loader can run from a bare `&Lua`: that is what
-    /// lets `LoadAddOn` load an addon from inside a Lua binding, synchronously, the way the
-    /// reference does (1188 phase 2). `font_objects` below was already here, and these two are
-    /// the same kind of thing — VM-global registries the loader fills.
+    /// FrameXML templates, global across files as the client's (`0x6ee500`); held here so the
+    /// loader runs from a bare `&Lua`, which lets `LoadAddOn` load inside a binding.
     pub(crate) framexml_templates:
         std::cell::RefCell<std::collections::HashMap<String, crate::framexml::Element>>,
-    /// **`FrameXML_Debug`'s flag** — the loader's own trace-severity switch (decision 2160).
-    ///
-    /// `0x488440` is a get-or-set over the single global `[0xceea30]`, which boots at 0 and is
-    /// read at six sites image-wide: the binding itself and five inside the XML loader, each
-    /// gating a severity-0 trace line behind `flag > 0` (`0x6ee298 jle` — **greater than**, not
-    /// non-zero, which is why this is signed). The one site walked to the bytes is
-    /// `Instantiate 0x6ee280`, whose gated line is `0x871154 "-- Creating %s named %s"`.
-    ///
-    /// Here rather than on `UiScript` for `framexml_templates`' reason: the loader runs from a
-    /// bare `&Lua`, and so does the binding that writes this.
+    /// `FrameXML_Debug`'s flag (`0x488440` over `[0xceea30]`, boots 0); the loader's trace lines
+    /// print while it is greater than 0 (`0x6ee298`), so it is signed.
     pub(crate) framexml_debug: std::cell::Cell<i32>,
-    /// The FrameXML **font-element registry** (a separate namespace — a font inherits a font,
-    /// never a frame template), persisted for the same cross-file reason.
+    /// The FrameXML font registry, a namespace apart from templates (a font inherits only a font).
     pub(crate) framexml_fonts:
         std::cell::RefCell<std::collections::HashMap<String, crate::framexml::Element>>,
-    /// The frame arena (create/destroy + show/hide/strata/level/scale/alpha propagation).
     pub(crate) arena: WidgetArena,
-    /// Per-frame layout input (anchors/size/scale). Every live frame has one (created at
-    /// `CreateFrame`); `SetPoint`/`SetWidth`/… mutate it; `resolve` runs the graph over them.
+    /// Per-frame anchors, size and scale; every live frame has one from creation on.
     pub(crate) layout_inputs: HashMap<FrameHandle, LayoutInput>,
-    /// The last [`UiScript::resolve`] result: each resolvable frame's rect. Empty until `resolve`.
+    /// Each resolvable frame's rect from the last resolve.
     pub(crate) resolved: HashMap<FrameHandle, Rect>,
-    /// The anchor-graph solver, kept alive across resolves so its per-handle arrays and the
-    /// per-frame anchor `Vec`s are reused — a steady round allocates nothing (see
-    /// [`LayoutSolver`]). Scratch only: it holds no state between rounds that `begin` doesn't
-    /// clear, and `resolved`/`region_resolved` remain the model's own answer.
+    /// The anchor solver, kept across resolves so a steady round allocates nothing; scratch only.
     pub(crate) solver: LayoutSolver,
-    /// The fingerprint of the input set the last CONVERGED resolve ran against — the change gate
-    /// (see `script::layout::InputFingerprint`). `None` forces the next resolve to run: the
-    /// initial state, and what a non-converging (cyclic) pass leaves behind so its progress can
-    /// carry into the next frame.
+    /// Tier 2 of the resolve gate, the last converged inputs' fingerprint; `None` forces a resolve.
     pub(crate) layout_fingerprint: Option<super::layout::InputFingerprint>,
-    /// The layout mutation epoch — tier 1 of the resolve change gate (the fingerprint is tier 2).
-    /// Bumped by [`Model::touch_layout`] at every write path that can move the anchor solve's
-    /// read set; `resolve` returns immediately while it still equals [`Self::layout_epoch_resolved`],
-    /// paying a `u64` compare instead of fingerprinting ~2k inputs. Tier 2 remains the correctness
-    /// backstop for a write that bumps this without moving anything; it is not a licence to bump
-    /// per frame, because *reaching* it costs the whole-UI hash. The bag-hover re-enter loop used
-    /// to do exactly that (~0.65 ms/frame at solves=0) until its wrap-pin round trip was made
-    /// change-gated — `tooltip::append_line`, and the gate
-    /// `layout_gate::the_hover_re_enter_loop_neither_re_measures_nor_re_solves`.
+    /// Tier 1 of the resolve gate: every layout write bumps it, and a resolve returns at once while
+    /// it equals `layout_epoch_resolved`. Never bump it per frame: tier 2 hashes the whole UI.
     pub(crate) layout_epoch: u64,
-    /// [`Self::layout_epoch`]'s **precise** form: the nodes a write actually NAMED since the last
-    /// converged resolve — tier 1 promoted from "something moved" to "*these* moved" (decision
-    /// 1388).
-    ///
-    /// `Some(nodes)` carries a second, stronger claim than its contents: **every** write since the
-    /// cached graph was built named its node *and* left the graph's SHAPE alone, so
-    /// [`super::layout::LayoutScope`]'s roster, edges and per-node hashes still describe the live
-    /// model and a resolve may seed the dirty closure straight from this list. `None` is the
-    /// conservative state — a write that could not name its node, or one that moved the roster or
-    /// an anchor's TARGET — and forces the next resolve to derive the graph from scratch, which is
-    /// exactly what every resolve did before 1388.
-    ///
-    /// That asymmetry is the safety argument. A site that keeps calling plain
-    /// [`Model::touch_layout`] is *correct by construction* (it lands in `None`, i.e. today's
-    /// behaviour); only a site that opts into [`Model::touch_layout_region`] /
-    /// [`Model::touch_layout_frame`] can be wrong, and `WOW_LAYOUT_VERIFY` re-resolves every
-    /// incremental pass in full scope and compares rects, so being wrong fails a test rather than
-    /// shipping a stale one.
-    /// The list holds **layout ids**, not handles: the touch sites below already have to prove the
-    /// node is in the cached roster before they may name it, and that proof is a `node_of[id]`
-    /// probe — which hands back the roster row, and with it the handle, for free at resolve time.
+    /// Layout ids named by writes since the last converged resolve, each write claiming it left the
+    /// cached graph's shape alone, so a resolve seeds its dirty closure from them. `None` derives
+    /// the graph in full; `WOW_LAYOUT_VERIFY` checks every incremental pass against a full one.
     pub(crate) layout_touched: Option<Vec<u32>>,
-    /// The MEASURE lane's ledger — [`Self::layout_touched`]'s twin for the text-measure sweep
-    /// (`UiScript::fontstrings_needing_measure`), which used to walk every `region_data` row
-    /// twice a frame to *discover* silent writes (`SetText` touches no layout until the extent
-    /// moves — that silence is the lane's defining property, decision 1370's ~300 µs standing
-    /// `resolve` lap at a city pin). `Some(handles)` = every write since the last sweep that
-    /// could move a region's measure key ([`crate::script::types::RegionData::measure_key`]:
-    /// text, font path/height, text height, outline, wrap width, owner scale) named its region
-    /// here, so the sweep asks exactly these. `None` = some write could not name one (a
-    /// font-object fan-out, a scale propagation, `invalidate_text_measures`) and the next sweep
-    /// walks the whole roster exactly as it always did — which is also the initial state.
-    ///
-    /// UNLIKE the layout ledger, `None` is not re-entered by unmigrated sites automatically:
-    /// nothing at a `region_data` field write *had* to announce itself before this existed, so
-    /// completeness of the enrolled sites is the correctness claim — and it is machine-checked,
-    /// not argued: with `WOW_LAYOUT_VERIFY` on (forced for every benilla-ui test) the sweep
-    /// re-runs the whole-roster walk beside the drained ledger and panics on any row the ledger
-    /// missed. A candidate the ledger names that the roster walk doesn't is fine (a same-value
-    /// write — the staleness check absorbs it); the reverse is a stale label waiting to ship.
+    /// Regions a write may have re-keyed for text measure (text, font, outline, wrap, scale) since
+    /// the last sweep, which asks only these; `None` walks all. A site that forgets to name its
+    /// region is caught by `WOW_LAYOUT_VERIFY`, on for every test here, which panics on the miss.
     pub(crate) measure_dirty: Option<Vec<crate::widget::RegionHandle>>,
-    /// The message-line sweep's clean tokens: frame → (lines_gen, env hash) at its last
-    /// ZERO-REQUEST sweep. A frame matching both is skipped whole (`message_lines_needing_measure`
-    /// hashes none of its lines); a sweep that produced requests stores nothing, so an unanswered
-    /// request re-requests forever exactly like the region lane's ledger (1410's rule). Stale
-    /// entries for destroyed frames are inert (generational handles never re-match) and the map
-    /// holds a handful of message frames, so no destroy hook.
+    /// Per message frame, `(lines_gen, env hash)` at its last request-free sweep; a match skips it.
+    /// A destroyed frame's entry is inert: generational handles never match again.
     pub(crate) msg_swept: std::collections::HashMap<crate::widget::FrameHandle, (u64, u64)>,
-    /// Lines actually hashed by the sweep — the skip's honest meter (tests assert 0 on a settled
-    /// second sweep; 0735's counts-never-milliseconds rule).
+    /// Lines the message sweep hashed; a settled second sweep hashes none.
     pub(crate) msg_lines_hashed: u64,
-    /// `WOW_LAYOUT_VERIFY`'s flag that the resolve just taken was the incremental one and owes a
-    /// full-derive re-run to prove it (see `layout::UiScript::resolve_layout`). Always `false` in
-    /// production — nothing reads it unless the verify build set it.
+    /// Under `WOW_LAYOUT_VERIFY`, the resolve just taken was incremental and owes a full re-run.
     pub(crate) layout_verify_recheck: bool,
-    /// Per-node input hashes + the dirty-closure scratch — what makes a resolve cost the nodes
-    /// that MOVED rather than the whole graph (decision 1350; see `script::layout::LayoutScope`).
-    /// Tiers 1 and 2 above decide *whether* to solve; this decides *what*.
+    /// Per-node input hashes and dirty-closure scratch: which nodes a let-through resolve solves.
     pub(crate) layout_scope: super::layout::LayoutScope,
-    /// The [`Self::layout_epoch`] value the last CONVERGED resolve closed on. `None` forces the
-    /// next resolve through tier 1: the initial state, a cycle-bailed pass, and
-    /// [`super::UiScript::force_full_layout_resolve`].
-    ///
-    /// **Every converged resolve closes tier 1** (decision 1385) — a real solve as much as a
-    /// skipping one. It could not, while the fingerprint was hashed over the 0294 seeds as well
-    /// as the inputs: a solve outgrew the value it had just stored, so a mutated frame paid three
-    /// whole-roster walks (solve, settle, skip) instead of one. Hashing inputs alone makes the
-    /// stored fingerprint exactly the one the next mutation-free resolve recomputes, so a
-    /// per-frame layout write — the castbar's spark, any addon that animates a region — costs one.
+    /// The epoch the last converged resolve closed on; `None` sends the next one past tier 1.
     pub(crate) layout_epoch_resolved: Option<u64>,
-    /// How many times the change gate has LET A RESOLVE THROUGH. `UiScript::resolve` is called
-    /// unconditionally every frame, so the gap between call count and this is the gate's whole
-    /// value; it is also what lets a test assert that a no-op resolve really was one, rather than
-    /// merely producing the same rects. Counts the gate's decision, so it reads the same with the
-    /// `WOW_LAYOUT_VERIFY` self-check on (which re-runs skipped resolves) as with it off.
+    /// Resolves the gate let through, counted at its decision, so verify mode reads the same.
     pub(crate) layout_solves: u64,
-    /// How many times a resolve got **past tier 1** — the count of whole-roster preamble WALKS
-    /// (decision 1385). This, not [`Self::layout_solves`], is the honest cost counter for the
-    /// gate: a walk that ends in `gate_skips` still rebuilt the ids/plan, re-synced every frame's
-    /// scale and re-hashed all ~10k anchored regions to conclude "nothing moved" — ~1.0 ms at the
-    /// Stormwind pin — and `layout_solves` cannot see it, because it counts only the walks that
-    /// went on to solve.
-    ///
-    /// The castbar pin is why it exists: one moving spark cost **three** walks per frame and only
-    /// two of them were solves, so the counter the tests asserted on under-reported the bug by a
-    /// third. `resolve_bench::a_region_moving_every_frame_costs_one_gate_walk_on_the_shipped_ui`
-    /// is the guard that reads it.
-    ///
-    /// **Unlike [`Self::layout_solves`], this is NOT verify-independent.** Under
-    /// `layout_verify_enabled` a tier-1-clean resolve falls through and walks anyway, so a verify
-    /// build counts walks production never pays — which is the honest reading (the walk happened)
-    /// but makes the number useless as an assertion there. Assert on it only from a crate that
-    /// consumes `benilla-ui` as a dependency, where `cfg!(test)` is false and the count is
-    /// production's; inside this crate's own tests, assert on `layout_solves`.
+    /// Resolves that got past tier 1, including those that then skipped: the whole-roster walk's
+    /// cost, which `layout_solves` misses. Verify mode walks anyway, so assert on this only from a
+    /// crate that depends on `benilla-ui`; inside this crate, assert on `layout_solves`.
     pub(crate) layout_gate_walks: u64,
-    /// How many times a resolve **derived the layout graph** — the whole-roster walk that rebuilds
-    /// the frame/region roster, the reverse edges and every per-node hash (decision 1388).
-    ///
-    /// This is the cost counter [`Self::layout_gate_walks`] used to be. 1385 got a moving castbar
-    /// spark down from three walks per frame to one; 1388 made that one walk *cheap* by seeding the
-    /// dirty closure from a ledger of named nodes instead of rediscovering it, so "walks" no longer
-    /// separates the 1.48 ms case from the 20 µs one and this does. A UI that animates anything
-    /// should hold this at **zero** frame after frame — a non-zero steady-state reading means some
-    /// write site is falling back to the conservative `touch_layout`, and that is the regression.
-    ///
-    /// Verify-independent in the direction that matters: the `WOW_LAYOUT_VERIFY` re-run's
-    /// derivation is counted, but `resolve_layout` restores the meter afterwards, so a test reads
-    /// the same number in both modes.
+    /// Full layout-graph derivations: 0 on a steady UI, so a rise means a write fell back to
+    /// `touch_layout`. The `WOW_LAYOUT_VERIFY` re-run's derivation is not counted.
     pub(crate) layout_derives: u64,
-    /// The SCOPE of the last solve that ran: `(frames solved, regions swept)` — decision 1350's
-    /// own meter, and the number its gate asserts on. `layout_solves` says how often the gate let
-    /// a solve through and `layout_rounds` how deep each went; this says how WIDE, which is the
-    /// axis that used to be "the whole UI" and is the one a growing UI silently inflates.
+    /// The last solve's width, `(frames solved, regions swept)`.
     pub(crate) layout_last_scope: (usize, usize),
-    /// How many fixpoint ROUNDS those solves ran in total. A solve's cost is rounds × the whole
-    /// graph, so this is what separates "the gate let too much through" from "each pass is doing
-    /// too much" — the two have different fixes.
+    /// Fixpoint rounds run across all solves.
     pub(crate) layout_rounds: u64,
-    /// Hyperlink spans per frame — `(rect, link payload, full |H…|h markup)`, rects in the
-    /// engine's y-up screen space. Fed by the app each frame after it rasterizes message lines
-    /// ([`super::UiScript::set_link_spans`]); consumed by the pointer's release dispatch
-    /// (`OnHyperlinkClick` — decision 0288 P2).
+    /// Per frame, rasterized links `(y-up rect, link, full |H…|h markup)` for `OnHyperlinkClick`.
     pub(crate) link_spans: HashMap<FrameHandle, Vec<(Rect, String, String)>>,
-    /// Tab was pressed in the chat edit box since the last drain (`BenillaChatTabPressed` →
-    /// [`super::UiScript::take_chat_tab`]) — the app's whisper-target cycle reads it.
+    /// Tab was pressed in the chat edit box (`BenillaChatTabPressed`), for the whisper cycle.
     pub(crate) chat_tab: bool,
-    /// Region visuals (texture path/color/text) + region layout (anchors/size/justify).
+    /// Region visuals (texture, colour, text) and layout (anchors, size, justify).
     pub(crate) region_data: HashMap<RegionHandle, RegionData>,
-    /// Per-frame installed [`Backdrop`] (the tooltip/dialog/panel plate — `<Backdrop>` or
-    /// `SetBackdrop`). Absent ⇒ the frame draws no plate. Stored beside the arena like `region_data`
-    /// (the arena models structure, not paint). The client's `frame+0x1ac` pointer.
+    /// Each frame's backdrop plate (`<Backdrop>` or `SetBackdrop`, the client's `frame+0x1ac`).
     pub(crate) backdrops: HashMap<FrameHandle, backdrop::Backdrop>,
-    /// Per-`SimpleHTML` widget state (decision-free transcription of `CSimpleHTML`'s own members):
-    /// the four element fonts `+0x350`, the hyperlink format `+0x360`, and the CONTENTNODE list
-    /// `+0x340` of blocks the last `SetText` built. Stored beside the arena, like `backdrops`,
-    /// because its contents are script-layer types and `widget::kinds` is the layer below.
+    /// `CSimpleHTML`'s state: element fonts `+0x350`, link format `+0x360`, content nodes `+0x340`.
     pub(crate) simple_html: simplehtml::SimpleHtmlStates,
-    /// The named virtual **Font object** registry (`<Font name=…>` → resolved paint), keyed by name.
-    /// Populated by the loader as it walks top-level `<Font>` nodes; read by `SetFontObject` and by
-    /// FontString `inherits=` resolution. Data only — no Lua handles (MAXCSTACK discipline).
-    /// The named `<Font>` objects, **keyed by the ASCII-LOWERCASED name**.
-    ///
-    /// 1.12's font registry hashes the name and compares keys with `SStrCmpI` — case-INSENSITIVE
-    /// (`0x783870`/`0x7838c7`: *"Font names
-    /// are matched case-insensitively"*), and a name string handed to `SetFontObject` folds the
-    /// same way. `Recap/RecapOptions.xml:32` inherits `GameFontHighLightSmall` — the shipped font
-    /// is `GameFontHighlightSmall`, one letter's case apart — and on the real client that resolves.
-    ///
-    /// Read it through [`Model::font_object`], never directly: that is where the fold lives, and
-    /// the name says so because nothing else guards the invariant (1247's shape).
+    /// Named `<Font>` objects by lowercased name, as 1.12 matches them with `SStrCmpI` (`0x783870`,
+    /// `0x7838c7`); read them only through `font_object`, where the fold lives.
     pub(crate) font_objects_by_lower: HashMap<String, FontObject>,
-    /// The last [`UiScript::resolve`] result for **anchored** regions (those with a non-empty
-    /// [`RegionData::anchors`]): the region's own resolved rect, owner-relative (see [`extract`]).
-    /// Regions with no anchors are absent here — they fall to the size-centered / fill-owner path.
+    /// Anchored regions' owner-relative rects from the last resolve; anchor-less ones are absent.
     pub(crate) region_resolved: HashMap<RegionHandle, Rect>,
 
-    /// Monotonic id source (starts at 1; `0` is [`SCREEN`]).
+    /// The next object id to mint; ids start at 1, since 0 is `SCREEN`.
     pub(crate) next_id: u32,
     pub(crate) id_to_frame: IdMap<FrameHandle>,
     pub(crate) frame_to_id: HashMap<FrameHandle, u32>,
     pub(crate) id_to_region: IdMap<RegionHandle>,
     pub(crate) region_to_id: HashMap<RegionHandle, u32>,
-    /// Region name → layout id — the region twin of the arena's frame-name publish (same
-    /// non-overwriting first-wins rule). `SetPoint`'s string `relativeTo` resolves through frames
-    /// first, then here — the real client anchors regions to *sibling regions* by name everywhere
-    /// (e.g. the merchant label plate to its `$parentSlot` texture), which owner-fallback silently
-    /// mis-anchored before (the jutting-plates bug the director's A/B caught).
+    /// Region name to id, first wins: `SetPoint` anchors to a sibling region by name, after frames.
     pub(crate) region_names: HashMap<String, u32>,
 
-    /// Which handler kinds each frame has a script for (presence mirror; the closures live Lua-side
-    /// in the `REG_SCRIPTS` table). Lets `tick` find OnUpdate frames without scanning Lua.
+    /// Which handlers each frame has; the closures themselves live in Lua's `REG_SCRIPTS` table.
     pub(crate) scripts: HashMap<FrameHandle, HashSet<&'static str>>,
-    /// The frames carrying an `OnUpdate` script, maintained by `SetScript` — `scripts`' one
-    /// writer — so the tick iterates exactly the OnUpdate population instead of re-filtering
-    /// (and re-allocating from) the whole scripts map every frame (decision 1446). Order is
-    /// irrelevant here: the tick sorts its visible subset by frame id every pass (the
-    /// deterministic-dispatch law stays where it was).
+    /// Frames with an `OnUpdate` script, kept by `SetScript`; the tick sorts them by frame id.
     pub(crate) on_update_frames: Vec<FrameHandle>,
-    /// The frames carrying an `OnSizeChanged` script — 1446's list, for the layout resolve's
-    /// "before" snapshot instead of the tick. Same one writer, same reason: that snapshot's own
-    /// comment says it covers "a handful, usually zero", and it found them by filtering the WHOLE
-    /// `scripts` map with a string compare per entry, on every let-through resolve — 36–72 µs a
-    /// resolve at a 3,988-frame roster, which made it the biggest phase left in the preamble
-    /// (decision 1634's `[layout-pre] watched=`).
+    /// Frames with an `OnSizeChanged` script, kept by `SetScript`, for the resolve's size snapshot.
     pub(crate) on_size_changed_frames: Vec<FrameHandle>,
-    /// The frames carrying an `OnUpdateModel` script — the list the tick fires at the top of
-    /// every paint of a visible model pane (`0x76d1a0`'s first act; decision 2007). Same one
-    /// writer as the two lists above.
+    /// Frames with an `OnUpdateModel` script, fired as a visible model pane paints (`0x76d1a0`).
     pub(crate) on_update_model_frames: Vec<FrameHandle>,
-    /// What the engine knows about each model **file** a pane has named — the sequences and
-    /// bounds a pane's clock needs ([`crate::widget::ModelFileFacts`]), handed over by the host
-    /// once the asset is resident, keyed by [`crate::widget::model_key`]. The reference reads
-    /// these off the loaded `MD20`; this engine parses no M2, so the facts arrive from the app's
-    /// loader through `UiScript::set_model_facts`.
+    /// Per model file, a pane clock's sequences and bounds, read by the host off the `MD20`.
     pub(crate) model_facts: HashMap<String, std::sync::Arc<crate::widget::ModelFileFacts>>,
-    /// Model files a pane named that no facts have arrived for yet — drained by the host
-    /// (`UiScript::model_facts_wanted`) to load them. Deduplicated on push.
+    /// Model files still waiting for their facts, for the host to load; deduplicated.
     pub(crate) model_facts_wanted: Vec<String>,
-    /// Edit boxes whose text changed and whose `OnTextChanged` has **not fired yet** — the
-    /// reference's `textChanged` dirty bit (`[E+0x31c]` bit 0), which `SetText`/`Insert` raise and
-    /// only the dirty-word drain `0x77d3e0` clears (decision 1831).
-    ///
-    /// The fire is deferred, not immediate: `SetText` returns to Lua before any handler runs, and N
-    /// changes to one box between two drains produce exactly ONE fire carrying the final text. The
-    /// reference's own FrameXML depends on both halves — `MoneyInputFrame_SetCopper` sets three
-    /// boxes while counting the fires it expects back, and errors if one arrives mid-loop.
-    ///
-    /// A hidden box stays on this list: `Hide` splices it out of the chain the update walk follows,
-    /// so its pending fire waits until it is shown again (or a key/mouse-down reaches it).
+    /// Edit boxes owed `OnTextChanged`: the reference's dirty bit (`[E+0x31c]` bit 0), set by
+    /// `SetText`/`Insert`, cleared only by `0x77d3e0`: one fire per drain, with the final text, as
+    /// `MoneyInputFrame_SetCopper` needs. A hidden box's fire waits for a show, key or mouse-down.
     pub(crate) dirty_editboxes: Vec<FrameHandle>,
-    /// `event name → frames registered for it` (RegisterEvent), in **registration order** — an
-    /// ordered Vec, never a set: the client's `SignalEvent 0x703e50` walks a per-event listener
-    /// LIST, so cross-frame dispatch order is a law, not an accident (the abbey territory-line
-    /// bug: two ZoneText frames write the same FontString on one event — last writer decides).
-    /// Re-registering is a no-op (position kept); Unregister removes. Data only — no Lua handles.
+    /// Event name to its frames in registration order, never a set: `SignalEvent` (`0x703e50`)
+    /// dispatches in that order across frames. Re-registering keeps a frame's position.
     pub(crate) event_to_frames: HashMap<String, Vec<FrameHandle>>,
-    /// `frame → its registered events` (for UnregisterEvent / cleanup).
     pub(crate) frame_events: HashMap<FrameHandle, HashSet<String>>,
-    /// The frames registered for **every** event (`RegisterAllEvents`), in registration order —
-    /// the same ordered-Vec-never-a-set discipline as [`Self::event_to_frames`], and dispatched
-    /// after it for the same reason: a frame that asks for all events asks *after* the frames
-    /// already listening for a given one, so it takes the tail of that event's list.
-    ///
-    /// **A flag rather than an expansion.** 1.12's event ids run to `0x225` = 549
-    /// (`FrameScript_InitEvents`), so writing the frame into every per-event list on registration
-    /// would mean 549 vector pushes per call and 549 scans per `UnregisterAllEvents` — and would
-    /// also invent a name list this engine has no business owning (ours registers by string, and
-    /// an event the server sends that no name list knows about would be silently excluded).
-    /// `UnregisterAllEvents` empties this alongside the per-event registrations, which is the half
-    /// AceEvent-2.0 depends on: it calls `frame:UnregisterAllEvents()` and then re-registers each
-    /// individual event it still wants.
+    /// `RegisterAllEvents` frames in registration order, dispatched after an event's own list and
+    /// cleared only by `UnregisterAllEvents`. Deviation: a flag, not the reference's append to
+    /// every event's list (`0x7023e0`, which orders by registration time and lets `UnregisterEvent`
+    /// drop one event), because events register here by name and no list of every name exists.
     pub(crate) all_event_frames: Vec<FrameHandle>,
 
-    /// The EditBox that currently owns keyboard focus — the engine's twin of the client's
-    /// class-owned focus global `DAT_00cf4dc8` (`CSimpleEditBox* E`, 0 = none). A focused
-    /// box consumes every key/char; `None` lets an `autoFocus` box self-acquire on the first event.
-    /// Gated on effective-visibility at read time (a box hidden while focused stops taking input).
+    /// The focused edit box (`0xcf4dc8`), taking all keys while visible; `None` admits `autoFocus`.
     pub(crate) focused_editbox: Option<FrameHandle>,
 
-    /// The frame currently under the cursor (the last [`UiScript::mouse_move`] capture), so the next
-    /// move knows whether to fire `OnLeave`/`OnEnter`. `None` = cursor over no mouse-enabled frame.
+    /// The mouse-enabled frame under the cursor, for the next move's `OnLeave`/`OnEnter`.
     pub(crate) mouseover: Option<FrameHandle>,
-    /// The hover **re-pick** is due: the world under a stationary cursor changed — the hovered
-    /// frame hid (its `OnLeave` already fired at hide time), or a frame was shown that may now
-    /// be the topmost under the cursor. The reference keeps exactly this flag on the frame
-    /// manager (`[root+0x1100]`) and its per-tick pump re-runs the hover walk at the **saved**
-    /// cursor position, explicitly bypassing the didn't-move coalesce — so the newly exposed
-    /// frame gets `OnEnter` with no physical mouse move (writers `0x764cbb`/`0x764b8d`, pump
-    /// tail `0x7657a1` → `0x7660d0` self-alias). [`UiScript::tick`] drains it the same way.
+    /// A frame under a still cursor hid or showed, so the tick re-runs the hover walk at the saved
+    /// position and a newly exposed frame gets `OnEnter` without a mouse move: the reference's
+    /// `[root+0x1100]` flag (set at `0x764cbb`/`0x764b8d`, pumped at `0x7657a1` into `0x7660d0`).
     pub(crate) hover_repick: bool,
-    /// Per-button, the frame a mouse-down last captured (`button name → frame`), for the `OnClick`
-    /// same-frame press+release test in [`UiScript::mouse_button`]. Keyed by button so a `LeftButton`
-    /// press is not cleared by a `RightButton` release.
+    /// Per button, the frame its press landed on, for `OnClick`'s same-frame release test.
     pub(crate) mouse_down_on: HashMap<String, FrameHandle>,
-    /// The client's single mouse-capture slot **`root+0x80`** — the frame a press captured, held
-    /// until every button is up. The same fact as [`Model::mouse_down_on`] in the one-slot form,
-    /// and the two differ only while more than one button is held; this is the form the
-    /// mouse-down **raise** reads, which is what needs the precedence to be unambiguous.
-    ///
-    /// Written at `0x7663e6` with the resolved target — capture-**else**-hover, so an existing
-    /// capture survives a chorded press over a different frame — and cleared at `0x7664bb` only
-    /// when the post-event button mask is empty, so a chorded release keeps it. A title-region
-    /// press never reaches `0x7663e6` and so captures nothing.
+    /// The client's one mouse-capture slot (`root+0x80`), read by the mouse-down raise. Set at
+    /// `0x7663e6` to the capture, else the hovered frame, so a chorded press keeps the capture;
+    /// cleared at `0x7664bb` once no button is down. A title-region press captures nothing.
     pub(crate) mouse_capture: Option<FrameHandle>,
-    /// Per **frame**, the [`UiScript::now`] second at which its last single `OnClick` fired — the
-    /// double-click detector's entire state, and the faithful stand-in for the client's per-widget
-    /// timestamp `[CButton+0x334]`.
-    ///
-    /// Three properties of that field are load-bearing, and are why this is keyed the way it is.
-    /// It lives on the **widget**, so two frames can never pair with each other. It carries **no
-    /// button identity** — the detector is button-agnostic, so a left release followed by a right
-    /// one on a button registered for both completes a double click (with `arg1` = the *second*
-    /// button); what normally confines double-clicks to the left button is `RegisterForClicks`'
-    /// `{"LeftButtonUp"}` default, not the detector. And it is written only when a single click
-    /// actually fires, then **zeroed** when a double completes — which is what makes four rapid
-    /// clicks read `Click · DoubleClick · Click · DoubleClick` rather than one click and three
-    /// doubles. Nothing else clears it: not hide, not disable, not the cursor leaving the frame
-    /// (`[+0x334]` has exactly three writers binary-wide — ctor, the fired-double zero, and the
-    /// fired-single stamp).
+    /// Per frame, when its last single `OnClick` fired: the client's `[CButton+0x334]`, the whole
+    /// double-click state. It has no button identity (left then right makes a double), is zeroed
+    /// when a double fires, and nothing else clears it, not hide, disable or the cursor leaving.
     pub(crate) last_click: HashMap<FrameHandle, f64>,
 
-    /// Frames whose resolved SIZE moved in the last [`UiScript::resolve_layout`], as
-    /// `(frame id, width, height)` — queued there (it holds only a `&mut Model`, so it cannot call
-    /// Lua) and drained by [`super::event::fire_size_changes`] at the next `&Lua` seam, which turns
-    /// each into `OnSizeChanged(self, width, height)`. Same compute-under-borrow / fire-outside
-    /// shape as the pointer path's `OnValueChanged`/`OnDragStart` hand-offs.
+    /// Frames the last resolve resized, `(id, width, height)`, owed `OnSizeChanged` outside it.
     pub(crate) pending_size_changed: Vec<(u32, f32, f32)>,
 
-    /// Script errors collected from `pcall`'d handlers (never panics, never prints — decision 0068).
+    /// Script errors caught from `pcall`'d handlers, drained by the host each frame.
     pub(crate) errors: Vec<String>,
-    /// Script errors awaiting dispatch to the **Lua-side** error handler (decision 1305) — the
-    /// reference calls `geterrorhandler()`'s function on every caught script error, which is how
-    /// FrameXML's `_ERRORMESSAGE` puts the red ScriptErrors dialog on the player's screen. Every
-    /// message recorded through [`Model::record_script_error`] lands here as well as in `errors`;
-    /// [`super::UiScript::dispatch_script_errors_to_handler`] drains it at a safe seam (never from
-    /// inside the failed call). A message produced *by* the handler itself goes to `errors` only —
-    /// that asymmetry is the recursion guard.
+    /// Errors owed to `geterrorhandler()`, which the reference calls on each caught error; one the
+    /// handler itself raises skips this queue, which stops the recursion.
     pub(crate) pending_error_dispatch: Vec<String>,
-    /// The **retained** script-error log — what [`errors`](Self::errors) and the load walk both
-    /// throw away once logged (decision 1495). `errors` is a per-frame drain for the host's
-    /// terminal; this is the session's memory, deduplicated and bounded, and the only thing a
-    /// player can actually read. See [`super::diagnostics`] for why the reference's own dialog is
-    /// not enough on its own.
+    /// The session's retained diagnostic log, deduplicated and bounded; `errors` drains each frame.
     pub(crate) diagnostics: super::diagnostics::DiagnosticLog,
-    /// Non-fatal warnings surfaced to the host (e.g. `CreateFrame`'s ignored `inherits=` template).
+    /// Non-fatal warnings for the host, such as a dropped `inherits=` template.
     pub(crate) warnings: Vec<String>,
     /// The screen-root rect (`[bottom, left, top, right]`), the anchor base for top-level frames.
     pub(crate) screen: Rect,
 
-    /// The per-unit-token game-state snapshot the app pushes in each frame (`"player"`, `"target"`,
-    /// …), read by the `Unit*` Lua bindings ([`unit`]). Plain data — the engine never touches the
-    /// ECS/net; the app's feed writes here via [`UiScript::set_unit`] (decision 0068 §3). A token
-    /// absent from the map is a non-existent unit (`UnitExists` false, numbers `0`/nil).
-    ///
-    /// **Keyed by the ASCII-LOWERCASED token, and the name says so because the invariant has no
-    /// other guard.** 1.12's shared token resolver `0x515970` compares every literal with
-    /// `SStrCmpI` → `_strnicmp`, which folds `'A'..'Z'` by `+0x20`; not one of its ten compares
-    /// reaches the case-sensitive sibling. So `"Player"`, `"PLAYER"` and `"player"` are the same
-    /// unit on the real client, and ~10 corpus addons rely on it — `Accountant.lua:107`'s
-    /// `UnitFactionGroup("Player")` is the one that cost an addon its session.
-    ///
-    /// Read it through [`Model::unit`], never directly: that is where the fold lives. The field was
-    /// called `units` until the fold landed, and it was renamed precisely so that every existing
-    /// reader had to come through here rather than be trusted to remember.
+    /// Each unit token's state as pushed this frame, keyed lowercased because 1.12's resolver
+    /// (`0x515970`) matches with `SStrCmpI`: read it only through `unit`, where the fold lives.
     pub(crate) units_by_lower: HashMap<String, UnitState>,
-    /// Per-unit-token aura list, **in display order**, pushed by the app's aura feed each frame and
-    /// read by the `UnitAura` family ([`super::aura`]). The order is the app's decision, not the
-    /// engine's: the local player's is a maintained insertion-order cache, every other unit's is
-    /// ascending aura slot (decision 0257). A token absent here has no auras.
+    /// Per unit token, auras in display order: the player's by insertion, the rest by aura slot.
     pub(crate) auras: HashMap<String, Vec<AuraState>>,
-    /// Spell ids `CancelUnitBuff` queued since the app's last drain — one `CMSG_CANCEL_AURA` each.
+    /// Spell ids the cancel verbs queued (`CancelPlayerBuff`, `CancelTrackingBuff`, …), one
+    /// `CMSG_CANCEL_AURA` each.
     pub(crate) cancel_aura_requests: Vec<u32>,
-    /// The player's active tracking aura (the reference's `GetTrackingTexture` global — see
-    /// [`super::aura::TrackingState`]), pushed by the app's aura feed beside `auras`. `None` =
-    /// no tracking active.
+    /// The player's active tracking aura, behind `GetTrackingTexture`.
     pub(crate) tracking: Option<super::aura::TrackingState>,
-    /// Selection asks queued since the app's last [`UiScript::take_selection_requests`] drain — the
-    /// outbound twin of `units` above, carrying `TargetUnit` / `AssistUnit` / `TargetLastEnemy` in
-    /// call order because the reference reaches selection through one helper for all three
-    /// ([`super::SelectionRequest`]). The app resolves each to a streamed entity and commits the
-    /// selection; one it can't resolve is a no-op, as the real client no-ops `TargetUnit` on a
-    /// nonexistent unit ([`unit`]).
+    /// `TargetUnit`, `AssistUnit` and `TargetLastEnemy` calls in call order, one queue as the
+    /// reference routes all three through one helper; an unresolvable one is a no-op, as there.
     pub(crate) selection_requests: Vec<super::SelectionRequest>,
-    /// `TargetNearestFriend([reverse])` presses queued since the app's last
-    /// [`UiScript::take_target_nearest_friend_requests`] drain — one entry per call, `true` for the
-    /// reverse (backward) cycle. The app runs the friendly half of the TAB scan ([`unit`]).
+    /// `TargetNearestFriend` calls, `true` for the reverse cycle.
     pub(crate) target_nearest_friend_requests: Vec<bool>,
-    /// `(name, exactMatch)` pairs `TargetByName` queued since the app's last
-    /// [`UiScript::take_target_by_name_requests`] drain — the by-NAME twin of
-    /// `Self::target_requests`, which takes unit tokens. The app runs the shared by-name
-    /// resolver (`crate::target::by_name`, decision 0886) and commits the selection ([`unit`]).
+    /// `TargetByName(name, exactMatch)` calls, for the app's by-name resolver.
     pub(crate) target_by_name_requests: Vec<(String, bool)>,
-    /// Set when `ClearTarget()` fired with a live target — the ESC chain's LAST leg
-    /// (`ToggleGameMenu`'s order: the clear runs only when nothing earlier ate the press).
-    /// Drained by [`super::UiScript::take_target_clear`]; the app commits the deselect ([`unit`]).
+    /// `ClearTarget()` fired with a live target, the last step of `ToggleGameMenu`'s ESC chain.
     pub(crate) target_clear: bool,
-    /// Unit tokens `DropItemOnUnit` queued since the app's last
-    /// [`UiScript::take_drop_item_on_unit`] drain — the cursor's held item being dropped onto a
-    /// unit (`0x48d960`). The binding queues the token only; **every gate is the app's**, because
-    /// all of them read state the VM does not hold (the pet's owner fields, the learned Feed-Pet
-    /// spell, the held item's guid). A token the app refuses is silent and keeps the payload,
-    /// which is the reference's own behaviour ([`super::cursor`]).
+    /// `DropItemOnUnit` tokens (`0x48d960`), gated by the app; a refusal silently keeps the item.
     pub(crate) drop_item_on_unit: Vec<String>,
 
-    /// The party/raid roster snapshot the app pushes (`GroupState`'s merged view, decision 0434
-    /// §2) — `GetNumPartyMembers`/`GetPartyLeaderIndex`/`GetLootMethod`/… read it ([`party`]).
-    /// `PartyState::default()` = not in a group (every getter reports the solo-player shape).
-    /// Per-member game state rides the `units` map above, under `"party1"`..`"party4"` tokens.
-    /// The channels this session has CONFIRMED joining, in join order — the client-side number
-    /// law `GetChannelName` answers with ([`super::channel`]). Mirrored from `ui_chat`'s
-    /// `ChannelState` by `set_joined_channels`; empty until the server's first YOU_JOINED.
+    /// Channels the server confirmed, in join order: the numbers `GetChannelName` answers.
     pub(crate) joined_channels: Vec<Option<String>>,
+    /// The party or raid roster the app pushes; the default is not in a group.
     pub(crate) party: party::PartyState,
-    /// Party/loot intents (`AcceptGroup`/`InviteToParty`/`SetLootMethod`/…) queued since the
-    /// app's last [`super::UiScript::take_party_requests`] drain — the outbound seam ([`party`]).
+    /// Party and loot-method calls (`AcceptGroup`, `InviteToParty`, `SetLootMethod`, …) queued.
     pub(crate) party_requests: Vec<party::PartyRequest>,
-    /// The ready-check deadline and the unanswered flags the timeout tick reads (decision 1989).
+    /// The ready-check deadline and the unanswered flags the timeout tick reads.
     pub(crate) ready_check: party::ReadyCheckState,
-    /// The saved raid lockouts the Raid tab's info panel reads (decision 1549), pushed by the app
-    /// from `SMSG_RAID_INSTANCE_INFO`. Its own field rather than a [`party::PartyState`] member
-    /// because it arrives on its own packet and survives every roster change.
+    /// Saved raid lockouts from `SMSG_RAID_INSTANCE_INFO`, which outlive any roster change.
     pub(crate) saved_instances: Vec<party::SavedInstanceInfo>,
-    /// `SetRaidRosterSelection`'s cursor — a client-side raid row index, never sent anywhere.
+    /// `SetRaidRosterSelection`'s raid row index, client-side only.
     pub(crate) raid_selection: i64,
-    /// The current map's `Map.dbc` `InstanceType`, pushed by the app — `IsInInstance()`'s whole
-    /// input ([`instance`]). `None` = the map id has no DBC row.
+    /// The current map's `Map.dbc` `InstanceType`, all `IsInInstance()` reads; `None` for no row.
     pub(crate) instance_type: Option<u32>,
-    /// `CanShowResetInstances()`'s answer, pushed by the app (decision 1748) — the four-term
-    /// predicate the reference computes at `0x495c90` over state only the app holds.
+    /// `CanShowResetInstances()`, the reference's four-term predicate (`0x495c90`), app-computed.
     pub(crate) can_reset_instances: bool,
-    /// `ResetInstances()` calls queued since the app's last
-    /// [`super::UiScript::take_reset_instance_asks`] drain — the outbound seam ([`instance`]).
+    /// `ResetInstances()` calls queued.
     pub(crate) reset_instance_asks: u32,
-    /// The social snapshot the app pushes (friends, ignores, the last `/who` — decision 0668):
-    /// `GetNumFriends`/`GetFriendInfo`/`GetWhoInfo`/… read it ([`social`]). Already
-    /// display-resolved (names, class/zone names) because the reference resolves them
-    /// engine-side too.
+    /// Friends, ignores and the last `/who`, display-resolved as the reference resolves them.
     pub(crate) social: social::SocialState,
-    /// Social intents (`AddFriend`/`RemoveFriend`/`SendWho`/…) queued since the app's last
-    /// [`super::UiScript::take_social_requests`] drain — the outbound seam ([`social`]).
+    /// Social calls (`AddFriend`, `RemoveFriend`, `SendWho`, …) queued.
     pub(crate) social_requests: Vec<social::SocialRequest>,
-    /// The client's three LFG slot words (`[0xbc70a0]`) and its comment (`[0xbc6e98]`, a
-    /// 0x80-byte buffer), the BSS `SetLookingForGroup` writes and `GetLookingForGroup` reads
-    /// back — never the server's (1961). The slots are always zero
-    /// in the reference: see [`social`].
+    /// The client-local LFG slot words (`[0xbc70a0]`) and comment (`[0xbc6e98]`, 0x80 bytes) that
+    /// `SetLookingForGroup` writes and `GetLookingForGroup` reads; the reference's slots stay 0.
     pub(crate) lfg_slots: [u32; 3],
     pub(crate) lfg_comment: String,
-    /// The guild snapshot the app pushes (roster, ranks, MOTD, info text — decision 1257):
-    /// `GetNumGuildMembers`/`GetGuildRosterInfo`/`GuildControlGetRankFlags`/… read it
-    /// ([`guild`]). Already display-resolved and already sorted + filtered, because the sort
-    /// field and the show-offline toggle live app-side where the roster does.
+    /// Guild roster, ranks, MOTD and info, sorted and filtered by the app, which holds the toggles.
     pub(crate) guild: guild::GuildState,
-    /// The rank-control popup's staging buffer ([`guild::GuildRankEdit`]) — deliberately NOT part
-    /// of [`Self::guild`], because a snapshot push mid-edit would discard the user's unsaved
-    /// checkbox clicks. Flushed by `GuildControlSaveRank`.
+    /// The rank editor's unsaved edits, apart from `guild` so a push cannot discard them.
     pub(crate) guild_control: guild::GuildRankEdit,
-    /// Guild intents (`GuildInviteByName`/`GuildSetMOTD`/`GuildControlSaveRank`/…) queued since
-    /// the app's last [`super::UiScript::take_guild_requests`] drain — the outbound seam
-    /// ([`guild`]).
+    /// Guild calls (`GuildInviteByName`, `GuildSetMOTD`, `GuildControlSaveRank`, …) queued.
     pub(crate) guild_requests: Vec<guild::GuildRequest>,
-    /// The guild-charter snapshot the app pushes (the registrar's price and the open petition —
-    /// decision 1672): `GetPetitionInfo`/`GetPetitionNameInfo`/`GetGuildCharterCost`/… read it
-    /// ([`petition`]). Names and the proposed guild's title are already resolved, because in the
-    /// real client too they come from caches the engine owns and not from the packet that opens
-    /// the window.
+    /// The charter price and open petition, names resolved from caches as the reference does.
     pub(crate) petition: petition::PetitionState,
-    /// Charter intents (`BuyGuildCharter`/`SignPetition`/`TurnInGuildCharter`/…) queued since the
-    /// app's last [`super::UiScript::take_petition_requests`] drain — the outbound seam
-    /// ([`petition`]).
+    /// Charter calls (`BuyGuildCharter`, `SignPetition`, `TurnInGuildCharter`, …) queued.
     pub(crate) petition_requests: Vec<petition::PetitionRequest>,
-    /// Whisper targets `ChatFrame_SendTell` queued since the app's last
-    /// [`super::UiScript::take_tell_requests`] drain — the app opens its chat edit box prefilled
-    /// `/w <name> ` (the unit popup's WHISPER action; [`party`] registers the global).
+    /// Names `ChatFrame_SendTell` queued; the app opens the chat box prefilled `/w <name> `.
     pub(crate) tell_requests: Vec<String>,
-    /// Prefill texts `ChatFrame_OpenChat` queued since the app's last
-    /// [`super::UiScript::take_open_chat_requests`] drain — `tell_requests`' sibling, one step
-    /// less resolved: a name there, a whole draft line here ([`chat_window`] registers the global).
+    /// Draft lines `ChatFrame_OpenChat` queued, for the app to prefill the chat box.
     pub(crate) open_chat_requests: Vec<String>,
-    /// Per-chat-window **look** — background tint, background alpha, font size — index 0 =
-    /// `ChatFrame1` (decision 1589, [`chat_window`]). The engine's own per-window record narrowed
-    /// to the three fields the tab menu's Display block can move; the host seeds it from the
-    /// player's saved file and persists what Lua writes back.
+    /// Per chat window from `ChatFrame1`, the tint, alpha and font size its tab menu can change.
     pub(crate) chat_window_looks: [chat_window::ChatWindowLook; chat_window::NUM_CHAT_WINDOWS],
-    /// The 0-based window indices whose look Lua moved since the app's last
-    /// [`super::UiScript::take_chat_window_changes`] drain — the persist cue. A set, so a slider
-    /// drag costs one entry however many steps it took.
+    /// 0-based windows whose look Lua changed, the persist cue.
     pub(crate) chat_window_changes: HashSet<usize>,
-    /// The chat-type colour registry (`0xb4e518`): 94 fixed entries + 10 `CHANNELn` extras
-    /// (`chat_types`). Seeded from the compiled defaults; the app overlays `chat-cache.txt`'s
-    /// `COLORS` block through [`super::UiScript::set_chat_colors`].
+    /// Chat-type colours (`0xb4e518`): 94 fixed and 10 `CHANNELn`, overlaid by `chat-cache.txt`.
     pub(crate) chat_colors: Vec<super::chat_types::ChatTypeColor>,
-    /// A Lua-side colour write landed — [`super::UiScript::take_chat_color_changes`].
     pub(crate) chat_colors_changed: bool,
-    /// The languages this character knows, `Languages.dbc` row order
-    /// ([`super::UiScript::set_known_languages`]).
+    /// The languages this character knows, in `Languages.dbc` row order.
     pub(crate) known_languages: Vec<String>,
-    /// The zone-channel rows for the current zone ([`super::UiScript::set_zone_channel_catalog`]).
     pub(crate) zone_channel_catalog: Vec<super::channel::ZoneChannelRow>,
-    /// Channel verbs since the last [`super::UiScript::take_channel_commands`] drain.
     pub(crate) channel_commands: Vec<super::channel::ChannelCommand>,
-    /// **The guild-recruitment auto-join latch** — the reference's int global `[0x843608]`, which
-    /// `GetGuildRecruitmentMode` returns and `SetGuildRecruitmentMode` writes (decision 2115).
-    ///
-    /// `0` = STANDARD, `1` = AUTO, and those two words are literally what the per-character chat
-    /// cache stores it as (`OPTION_GUILD_RECRUITMENT_CHANNEL STANDARD|AUTO`; `0x49ea70` maps
-    /// `STANDARD` to 0 and anything
-    /// else, `AUTO` included, to 1). It boots at **1**: every one of the 33 `chat-cache.txt` files
-    /// the reference client itself wrote in this repo's install says `AUTO`, on characters that
-    /// never opened the option.
+    /// The recruitment auto-join latch `[0x843608]`: 0 `STANDARD`, 1 `AUTO` (`0x49ea70` maps any
+    /// other word to 1). Boots at 1, as the reference writes `AUTO` for an untouched option.
     pub(crate) guild_recruitment_mode: u8,
-    /// A `SetGuildRecruitmentMode(1)` since the last drain — `0x49ea70`'s tail-jump into the
-    /// cascade `0x49ea90`, which the app runs (decision 2144). Keyed on the *new value alone*, not
-    /// on a change: the reference's store is unconditional and the jump reads only `ecx == 1`.
+    /// Any `SetGuildRecruitmentMode(1)`, even unchanged: the reference runs the cascade `0x49ea90`.
     pub(crate) guild_recruitment_cascade: bool,
-    /// Whether Lua has moved [`Self::guild_recruitment_mode`] since the last drain — the chat
-    /// cache's dirty signal, the peer of `chat_window_changes`.
+    /// Lua changed the recruitment mode: the chat cache's dirty signal.
     pub(crate) guild_recruitment_changed: bool,
-    /// `DoEmote` calls since the last drain.
+    /// `DoEmote` calls queued.
     pub(crate) emote_requests: Vec<super::chat_misc::EmoteRequest>,
-    /// `RandomRoll` calls since the last drain.
+    /// `RandomRoll` calls queued.
     pub(crate) roll_requests: Vec<(u32, u32)>,
-    /// `UninviteByName` calls since the last drain.
+    /// `UninviteByName` calls queued.
     pub(crate) uninvite_requests: Vec<String>,
     /// `ConsoleExec` lines that were not CVar writes.
     pub(crate) console_lines: Vec<String>,
-    /// `LoggingChat` / `LoggingCombat` — the two flags and their change cue.
+    /// `LoggingChat` and `LoggingCombat`'s flags, and their change cue.
     pub(crate) logging_chat: bool,
     pub(crate) logging_combat: bool,
     pub(crate) logging_changed: bool,
-    /// Whether a **user-placed** frame's geometry moved since the app's last
-    /// [`super::UiScript::take_user_placed_change`] drain — the layout cache's persist cue
-    /// ([`super::layout_cache`]). One bit rather than a set of handles, because the file is
-    /// rewritten whole either way; set by the move/resize pumps and by `SetUserPlaced` itself.
+    /// A user-placed frame moved or resized, or `SetUserPlaced` ran: the layout cache's save cue.
     pub(crate) user_placed_changed: bool,
-    /// The player's default chat language name, app-resolved from `ChrRaces.BaseLanguage` ×
-    /// `Languages.dbc` ([`super::UiScript::set_default_language`]). `None` = the reference's
-    /// no-player-object state, where `GetDefaultLanguage()` returns **zero Lua values**
-    /// ([`chat_send`]).
+    /// The default chat language; `None` is no player, so `GetDefaultLanguage()` returns nothing.
     pub(crate) default_language: Option<String>,
-    /// Duel intents (`AcceptDuel`/`CancelDuel`/`StartDuel*`) queued since the app's last
-    /// [`super::UiScript::take_duel_requests`] drain — the outbound seam ([`duel`]). There is no
-    /// duel *snapshot* beside it: everything the UI reads arrives as event arguments.
+    /// `AcceptDuel`, `CancelDuel` and `StartDuel*` calls; Lua sees duels only through events.
     pub(crate) duel_requests: Vec<duel::DuelRequest>,
-    /// Follow intents (`FollowUnit`/`FollowByName`) queued since the app's last
-    /// [`super::UiScript::take_follow_requests`] drain — the outbound seam ([`follow`]). The duel
-    /// queue's twin, snapshot-less for the same reason: the only thing the UI reads back is the
-    /// `AUTOFOLLOW_BEGIN`/`AUTOFOLLOW_END` pair the app fires, which carries its own argument.
+    /// `FollowUnit` and `FollowByName` calls; Lua sees following only as `AUTOFOLLOW_*` events.
     pub(crate) follow_requests: Vec<follow::FollowRequest>,
-    /// Camera-view intents (`SetView`/`SaveView`/`ResetView`/`NextView`/`PrevView`/
-    /// `FlipCameraYaw`) queued since the app's last
-    /// [`super::UiScript::take_camera_view_requests`] drain — the outbound seam
-    /// ([`camera_view`]). Snapshot-less like the follow queue: the five views live on the app's
-    /// camera rig, and they reach Lua the way the reference's do — as the
-    /// `cameraView` / `camera{Distance,Pitch,Yaw}{,A..D}` CVars — not as a second copy here.
+    /// `SetView`, `SaveView`, `ResetView`, `NextView`, `PrevView` and `FlipCameraYaw` calls; the
+    /// views reach Lua only as CVars, `cameraView` and `camera{Distance,Pitch,Yaw}{,A..D}`.
     pub(crate) camera_view_requests: Vec<camera_view::CameraViewRequest>,
-    /// Session-exit intents (`Logout`/`Quit`/`CancelLogout`/`ForceQuit`) queued since the app's
-    /// last [`super::UiScript::take_session_requests`] drain — the outbound seam ([`session`]).
-    /// Snapshot-less like the duel queue above: what the UI reads back (the camp/quit countdown)
-    /// arrives as the `PLAYER_CAMPING`/`PLAYER_QUITING`/`LOGOUT_CANCEL` events, not as state.
+    /// `Logout`, `Quit`, `CancelLogout`, `ForceQuit` calls; Lua sees the countdown only as events.
     pub(crate) session_requests: Vec<session::SessionRequest>,
-    /// PvP-flag toggles (`TogglePVP`) queued since the app's last
-    /// [`super::UiScript::take_pvp_toggles`] drain — the outbound seam ([`pvp`]). A count, not a
-    /// payload: `CMSG_TOGGLE_PVP` carries no body.
+    /// `TogglePVP` calls, a count because `CMSG_TOGGLE_PVP` has no body.
     pub(crate) pvp_toggles: u32,
-    /// The local player's honor snapshot ([`pvp::HonorState`], decision 1512) — the PRIVATE honor
-    /// descriptor fields the app decodes and pushes ([`super::UiScript::set_honor`]). `None`
-    /// before the first push, which the six self getters read as a zeroed snapshot (see
-    /// [`pvp`]'s module doc for why they never return short).
+    /// The player's private honor fields; before the first push the six self getters read zeros.
     pub(crate) honor: Option<pvp::HonorState>,
-    /// The last `MSG_INSPECT_HONOR_STATS` reply the app pushed ([`pvp::InspectHonorData`]). Its
-    /// PRESENCE is `HasInspectHonorData`'s answer — the latch the reference's inspect pane gates
-    /// its request on — so `None` is a state, not a gap.
+    /// The last `MSG_INSPECT_HONOR_STATS` reply; its presence is `HasInspectHonorData`'s answer.
     pub(crate) inspect_honor: Option<pvp::InspectHonorData>,
-    /// `RequestInspectHonorData` calls since the app's last
-    /// [`super::UiScript::take_inspect_honor_requests`] drain. A count for [`Self::pvp_toggles`]'s
-    /// reason: the binding takes no argument, and the guid the send needs is the app's own inspect
-    /// target. With [`Self::inspect_honor_pending`] gating the binding it can only ever drain `0`
-    /// or `1` — the engine has at most one query outstanding.
+    /// `RequestInspectHonorData` calls; the pending gate keeps this at 0 or 1.
     pub(crate) inspect_honor_requests: u32,
-    /// The engine's `pending` flag (`0xb71fcc`): a `MSG_INSPECT_HONOR_STATS` query is queued and
-    /// no reply has landed. `RequestInspectHonorData` (`0x4c80a0`) refuses while it is set, which
-    /// is what stops a pane shown/hidden/shown in quick succession sending duplicate queries.
-    /// Cleared by **either** arm of [`super::UiScript::set_inspect_honor`] — a reply landed
-    /// (`0x4c6f4c`), or the app invalidated the slot (`0x4c6f9d`).
+    /// An inspect-honor query is out (`0xb71fcc`); `RequestInspectHonorData` (`0x4c80a0`) refuses
+    /// while set. Cleared by a reply (`0x4c6f4c`) or by the app clearing the slot (`0x4c6f9d`).
     pub(crate) inspect_honor_pending: bool,
-    /// The two **equipment-display** preferences as the VM currently believes them —
-    /// `ShowingHelm()` / `ShowingCloak()` ([`worn_display`], decision 1472). Not a setting: the
-    /// truth is `PLAYER_FLAGS`' `HIDE_HELM`/`HIDE_CLOAK` bits, pushed here on the descriptor edge
-    /// by [`super::UiScript::set_worn_display`]. Both start **shown**, which is both the reference's
-    /// panel default and the zero-flags state a fresh character logs in with.
+    /// `ShowingHelm()`: `PLAYER_FLAGS`' `HIDE_HELM` bit as pushed, set ahead on `ShowHelm` because
+    /// the wire verb is a blind toggle. Starts shown, as a fresh character's flags are 0.
     pub(crate) helm_shown: bool,
-    /// The cloak half of [`Self::helm_shown`].
+    /// `ShowingCloak()`, the same for `HIDE_CLOAK`.
     pub(crate) cloak_shown: bool,
-    /// Worn-display flips (`ShowHelm`/`ShowCloak` asked for a state we were not in) queued since
-    /// the app's last [`super::UiScript::take_worn_display_toggles`] drain — one
-    /// `CMSG_TOGGLE_HELM`/`CMSG_TOGGLE_CLOAK` each. A list, not a count like [`Self::pvp_toggles`]:
-    /// the two slots are different packets.
+    /// Flips from `ShowHelm`/`ShowCloak`, one `CMSG_TOGGLE_HELM`/`CMSG_TOGGLE_CLOAK` each.
     pub(crate) worn_display_toggles: Vec<super::worn_display::WornDisplay>,
 
-    /// The server's `PLAYER_FIELD_BYTES` **byte 2** — which of the four extra action bars are on
-    /// ([`action_bar_toggles`], descriptor `+0x102a`). `None` until the
-    /// app pushes it ([`super::UiScript::set_action_bar_toggles`]), which is the ONLY thing that
-    /// moves it: the real client never writes this cell, so `SetActionBarToggles` deliberately
-    /// leaves it alone and the value lags the setter by a round trip. That is the opposite
-    /// arrangement to [`Self::helm_shown`] next door, and the difference is the wire verb's — a
-    /// blind flip has to be predicted, an absolute post does not.
+    /// `PLAYER_FIELD_BYTES` byte 2 (descriptor `+0x102a`), which extra action bars are on. Only
+    /// the server moves it, as in the reference: `SetActionBarToggles` leaves it a round trip late.
     pub(crate) action_bar_toggles: Option<u8>,
-    /// `CMSG_SET_ACTIONBAR_TOGGLES` payloads queued since the app's last
-    /// [`super::UiScript::take_action_bar_toggle_sends`] drain — one per `SetActionBarToggles`
-    /// call. A list, because the binding gates nothing: two calls in a frame are two packets.
+    /// One `CMSG_SET_ACTIONBAR_TOGGLES` payload per `SetActionBarToggles` call, ungated.
     pub(crate) action_bar_toggle_sends: Vec<u8>,
 
-    /// Sounds queued by the Lua `PlaySound`/`PlaySoundFile` bindings since the app's last
-    /// [`UiScript::take_sounds`] drain — the outbound Lua→app intent seam ([`sound`]).
+    /// `PlaySound` and `PlaySoundFile` calls queued.
     pub(crate) sound_queue: Vec<SoundRequest>,
 
-    /// `PlayMusic`/`StopMusic` intents queued since the app's last
-    /// [`UiScript::take_music`] drain — the same seam, a different *slot*: these drive the music
-    /// stream the reference gives the Lua caller (`[0xb06ccc]`), not the kit player ([`sound`]).
-    /// Order-bearing, so a start and a stop in one frame settle the slot the way they were called.
+    /// `PlayMusic` and `StopMusic` calls in call order, for the Lua music stream (`[0xb06ccc]`).
     pub(crate) music_queue: Vec<MusicRequest>,
 
-    /// **The UI-load sound-suppression depth** — `[0xb05fa0]` in the reference, a counted scope
-    /// with exactly three references image-wide: `0x458f50` (`inc`), `0x458f60` (`dec`), and one
-    /// reader at `0x458046`, inside `PlaySoundByName 0x458030`. The whole-UI load `0x48fbf0`
-    /// brackets ITSELF in it — `0x48fbfa` on entry, `0x49016d` on exit, spanning the TOC walk,
-    /// `Bindings.xml` and the AddOns — and both of its callers, login (`0x48f681`) and `/reloadui`
-    /// (`0x495669`), therefore load silently.
-    ///
-    /// The reader bails at `0x45804d` **before** the `MasterSoundEffects` CVar and the kit-hash
-    /// lookup, so a suppressed call is **dropped**: not muted, not queued, no Lua error, and the
-    /// binding still answers its usual `(willPlay, handle)`. Scoped to the NAME-keyed entry only —
-    /// id-keyed `PlaySound(kitId)` (`0x457fb0`/`0x457ff0`), `PlaySoundFile`, `PlayMusic` and
-    /// `StopMusic` all run normally inside the scope.
-    ///
-    /// This is what makes stock `TargetFrame_OnHide`'s `PlaySound("INTERFACESOUND_LOSTTARGETUNIT")`
-    /// inaudible at every login: the frame really is shown when its `OnLoad` hides it, the OnHide
-    /// really does fire, the call really is made — and the engine throws it away. Decision 1033's
-    /// "no sound during the load" is the client's own law, enforced here rather than by hoping no
-    /// handler rings.
+    /// The UI-load sound-suppression depth, the reference's `[0xb05fa0]` (`0x458f50` inc,
+    /// `0x458f60` dec), held across the whole UI load `0x48fbf0`, so login and `/reloadui` are
+    /// silent. Only name-keyed `PlaySound` (`0x458030`) reads it: the call is dropped before any
+    /// lookup yet answers `(willPlay, handle)` as usual. `PlaySound(kitId)` (`0x457fb0`),
+    /// `PlaySoundFile` and music play normally.
     pub(crate) sound_suppression: u32,
 
-    /// The CVar table (decision 0954, [`super::cvars`]): lowercase name → slot. Host-registered
-    /// only; Lua reads/writes through `GetCVar`/`SetCVar`/`GetCVarDefault`.
+    /// The CVar table, by lowercased name.
     pub(crate) cvars: HashMap<String, super::cvars::CvarSlot>,
-    /// The persisted values registration honors (decision 1291): lowercase name → the config
-    /// file's value, set by the host **before** any registration. A CVar registered while its
-    /// name is in here — host-registered or an addon's `RegisterCVar` — starts at the saved
-    /// value, not the default. This is what makes a knobless CVar (`statusBarText`) and an
-    /// addon-declared one survive the VM being replaced: in the reference the table is engine
-    /// memory and outlives every `ReloadUI`; ours is per-VM, so the file value is the bridge.
+    /// Saved CVar values, set before any registration so a CVar starts at its saved value: the
+    /// reference's table outlives `ReloadUI`, while ours is per VM.
     pub(crate) cvars_saved_base: HashMap<String, String>,
-    /// `(registered name, new value)` per Lua `SetCVar` since the app's last
-    /// [`super::UiScript::take_cvar_changes`] drain — the knob-sync + config-dirty cue.
+    /// `(registered name, new value)` per Lua `SetCVar`, the app's sync and save cue.
     pub(crate) cvar_changes: Vec<(String, String)>,
-    /// `(name, default)` per addon `RegisterCVar` that created a slot, since the host's last
-    /// [`super::UiScript::take_cvar_registrations`] drain (decision 2303).
+    /// `(name, default)` per addon `RegisterCVar` that created a slot.
     pub(crate) cvar_registrations: Vec<(String, String)>,
-    /// Unknown CVar names already warned about (warn-once, the era-atlas-miss posture).
     pub(crate) cvars_warned: HashSet<String>,
 
-    /// The device-enumerated multisample formats the Video options dropdown offers, in the order
-    /// it offers them — pushed by the host ([`super::UiScript::set_multisample_formats`]) from what
-    /// the render adapter actually accepts, and read by `GetMultisampleFormats` /
-    /// `GetCurrentMultisampleFormat` / `SetMultisampleFormat`.
-    ///
-    /// In the reference this is the distilled `{colorBits, depthBits, multisample}` triple list at
-    /// `[0xb4b444]` (count `[0xb4b440]`), built by `0x48c3e0` from the D3D
-    /// `CheckDeviceMultiSampleType` sweep or the GL `wglGetPixelFormatAttribivARB` sweep. Empty
-    /// until the host pushes it — a VM with no device behind it (every extract test) offers no
-    /// formats rather than inventing some.
+    /// The adapter's multisample formats in dropdown order, the reference's list `[0xb4b444]` of
+    /// `{colorBits, depthBits, multisample}` (count `[0xb4b440]`, built by `0x48c3e0`).
     pub(crate) multisample_formats: Vec<super::cvars::MultisampleFormat>,
 
-    /// The screen resolutions the Video options window's dropdown offers, ascending — pushed by
-    /// the host ([`super::UiScript::set_screen_resolutions`]) from the display this client is on,
-    /// and read by `GetScreenResolutions` / `GetCurrentResolution` / `SetScreenResolution`.
-    ///
-    /// Empty until the host pushes it. A VM with no window behind it (every extract test) offers
-    /// none rather than inventing a ladder, and the reference's own consumer walks it zero times.
+    /// This display's resolutions, ascending, behind `GetScreenResolutions`; empty until pushed.
     pub(crate) screen_resolutions: Vec<super::cvars::ScreenResolution>,
-    /// **Where in that list the client actually is** — the index `GetCurrentResolution` answers,
-    /// 0-based here and reported 1-based, which is the form `CT_Viewport.lua:105` indexes the
-    /// `GetScreenResolutions` varargs with (`arg[GetCurrentResolution()]`).
-    ///
-    /// Held as an index rather than a size so the two can never disagree: the host guarantees the
-    /// live size is IN the list when it pushes, which is what makes that addon's read total.
-    /// `None` while the list is empty.
+    /// The live size's index in that list, which the host always includes; `None` while the list
+    /// is empty. `GetCurrentResolution` answers it 1-based.
     pub(crate) current_resolution: Option<usize>,
-    /// What this run's device and presentation path really offer, behind `GetVideoCaps` — pushed
-    /// by the host, which is the only side holding a `RenderAdapter`.
+    /// What this device and presentation path offer, behind `GetVideoCaps`.
     pub(crate) video_caps: super::cvars::VideoCaps,
-    /// `RestartGx()` calls queued since the host last drained them — the video window's
-    /// "apply the staged settings now" button, counted like [`Self::screenshot_asks`] because the
-    /// request carries no payload.
+    /// `RestartGx()` calls, the video window's apply button.
     pub(crate) restart_gx_asks: u32,
 
-    /// The globals `RegisterForSave` declared, in registration order — the saved-variables set the
-    /// host writes out at logout/exit and re-executes at load (decision 1128, [`super::saved`]).
+    /// Globals `RegisterForSave` declared, in order: written at logout and re-run at load.
     pub(crate) saved_names: Vec<String>,
-    /// The saved-variables files that failed to load this session ([`super::saved`]'s
-    /// `hold_saved_file`) — the shutdown write leaves each one on disk rather than replacing a
-    /// settings file it never read with the defaults it ran on instead.
+    /// Saved-variables files that failed to load; the shutdown write leaves them untouched.
     pub(crate) held_saved_files: Vec<std::path::PathBuf>,
 
-    /// The key-binding table (decision 0997, [`super::keybind`]) — the chord→command store the
-    /// Key Bindings window edits, plus its stored account/character sets. The CVar table's twin:
-    /// host-registered commands, Lua reads/writes synchronously, the app re-derives dispatch when
-    /// [`super::UiScript::keybinds_generation`] moves and persists on the queued save requests.
+    /// The key-binding table the Key Bindings window edits, with its account and character sets.
     pub(crate) keybinds: super::keybind::KeybindState,
 
-    /// The action-slot snapshot (keyed by Lua action id 1..120) + the stance page offset the app
-    /// pushes, and the `UseAction` intents it drains — the action seam ([`action`]).
+    /// Action slots by Lua action id, 1..120.
     pub(crate) actions: HashMap<u32, ActionSlot>,
-    /// The per-action **dynamic** state (usable/range/current/cooldown — decision 0137 phase 4),
-    /// pushed beside `actions` by the app's feed; the `IsUsableAction`/`GetActionCooldown` family
-    /// reads it ([`action`]). Keyed like `actions`; an absent action reads cold/nil.
+    /// Per action, its usable, range, current and cooldown state; an absent one reads cold.
     pub(crate) action_states: HashMap<u32, super::action::StoredActionState>,
     pub(crate) bonus_bar_offset: u8,
     pub(crate) action_uses: Vec<super::action::ActionUse>,
-    /// `(lua action id, packed)` pairs queued by `PickupAction`/`PlaceAction` (decision 0216 §7,
-    /// slice 4) — one entry per local slot mutation, `packed == 0` clearing the slot. Drained by
-    /// the app into `CMSG_SET_ACTION_BUTTON`, one send per entry (client-authoritative, per-change
-    /// — 0218 §4: a drag-swap is two sends, never atomic).
+    /// `(action id, packed)` per slot `PickupAction`/`PlaceAction` changed, 0 clearing it: one
+    /// `CMSG_SET_ACTION_BUTTON` each, so a drag swap is two sends.
     pub(crate) action_sets: Vec<(u32, u32)>,
-    /// GlobalStrings keys for **client-local refusals the ENGINE raises** — the engine-free half
-    /// of the app's `ui_action::UiErrorKeys`, which cannot reach in here. The reference does this
-    /// inline (`push <errorId>; call CGGameUI::DisplayError 0x496720`) because its engine owns
-    /// both the refusal and the message; ours splits at the crate boundary, so the refusal queues
-    /// its key and the app's action feed resolves it against the VM's own GlobalStrings and fires
-    /// `UI_ERROR_MESSAGE`. Always `&'static str`: every tenant is a literal read out of the ref's
-    /// errorId table (`0xb4b498`, stride `0x14`), never runtime-built.
+    /// GlobalStrings keys of refusals this crate raises, fired by the app as `UI_ERROR_MESSAGE`
+    /// (the reference's `DisplayError` `0x496720`), each a literal from `0xb4b498` (stride `0x14`).
     pub(crate) ui_errors: Vec<&'static str>,
 
-    /// The player's known-spell book (decision 0216 §8, slice 5) — tabs + the flat slot list the
-    /// `GetSpellTabInfo`/`GetSpellName`/… bindings read ([`spellbook`]). Durable player state like
-    /// `actions` above, never `Option` — "no known spells yet" is simply empty vectors.
     pub(crate) spellbook: spellbook::SpellBookState,
-    /// The **pet's** book (decision 1032) — a second flat slot list, no tabs, with its own
-    /// add-gate and its own class token ([`spellbook::PetBookState`]). Held apart from
-    /// [`Self::spellbook`] because the reference holds two arrays too (`0xb700f0` / `0xb6f098`)
-    /// and every `bookType`-taking binding is a fork between them, never a filter over one.
+    /// The pet's spellbook, a second array as in the reference (`0xb700f0`, `0xb6f098`).
     pub(crate) pet_book: spellbook::PetBookState,
-    /// The player's **macros** (decision 0983) — the one game-state table this crate owns
-    /// outright, because 1.12 macros have no server side at all ([`macros`]'s module docs). The
-    /// app seeds it from `benilla-config/macros/…` and reads it back to persist.
+    /// The player's macros, owned here as 1.12 macros have no server side; the app persists them.
     pub(crate) macros: macros::MacroState,
-    /// A script mutated [`Self::macros`] since the app's last
-    /// [`super::UiScript::take_macros_dirty`] drain — the save + `UPDATE_MACROS` trigger.
+    /// A script changed the macros: the save and `UPDATE_MACROS` cue.
     pub(crate) macros_dirty: bool,
-    /// Bumped by every seed and every mutation — the *undrained* change signal per-frame
-    /// consumers gate on ([`super::UiScript::macros_generation`]), so the drained
-    /// [`Self::macros_dirty`] edge keeps its single owner.
+    /// Bumped by every seed and change, for readers that must not drain `macros_dirty`.
     pub(crate) macros_generation: u64,
-    /// The macro-icon chooser list (full texture paths, app-built off `SpellIcon.dbc`) —
-    /// `GetNumMacroIcons`/`GetMacroIconInfo`.
+    /// The macro icon paths from `SpellIcon.dbc`, behind `GetMacroIconInfo`.
     pub(crate) macro_icons: Vec<String>,
-    /// Spell ids `CastSpell` queued since the app's last [`super::UiScript::take_spell_casts`]
-    /// drain.
+    /// Spell ids `CastSpell` queued.
     pub(crate) spell_casts: Vec<u32>,
-    /// Pet spell ids `CastSpell(id, "pet")` queued — a separate list because the wire verb is a
-    /// separate opcode (`CMSG_PET_ACTION` with a synthesized type-1 word, `0x4b34ce`).
+    /// `CastSpell(id, "pet")` ids, sent as `CMSG_PET_ACTION` with a type-1 word (`0x4b34ce`).
     pub(crate) pet_spell_casts: Vec<u32>,
-    /// Pet spell ids `ToggleSpellAutocast` queued — `CMSG_PET_SPELL_AUTOCAST 0x2F3`, which names a
-    /// spell rather than the pet bar's slot ([`Self::pet_autocast_toggles`] is the bar's).
+    /// `ToggleSpellAutocast` ids for `CMSG_PET_SPELL_AUTOCAST` (`0x2F3`), which names a spell.
     pub(crate) pet_spell_autocasts: Vec<u32>,
-    /// Whether the app's own cast lifecycle holds something `SpellStopCasting()` can stop — a
-    /// running auto-repeat or an in-flight cast; a channel is NOT stoppable there (`0x6e6e80`;
-    /// pushed each frame by the app's cast feed,
-    /// [`super::UiScript::set_casting`]). The 1/nil return is load-bearing:
-    /// `ToggleGameMenu`'s ESC chain (`UIParent.lua:1489`) only falls through to
-    /// `CloseAllWindows()` on nil.
+    /// An auto-repeat or cast that `SpellStopCasting()` can stop, not a channel (`0x6e6e80`). Its
+    /// 1 or nil matters: the ESC chain (`UIParent.lua:1489`) reaches `CloseAllWindows()` on nil.
     pub(crate) casting: bool,
-    /// Set when `SpellStopCasting()` fired while [`Self::casting`] — the ESC local-cancel
-    /// trigger, drained by [`super::UiScript::take_spell_stop`] ([`spellbook`]).
+    /// `SpellStopCasting()` fired while casting: the ESC cancel.
     pub(crate) spell_stop: bool,
-    /// Whether the app's spell-targeting cursor mode is active — the `flag_word != 0` mirror
-    /// (`SpellIsTargeting 0x6e6cd0`, decision 0792). Pushed each frame by the app's targeting
-    /// feed ([`super::UiScript::set_spell_targeting`]); read by `SpellIsTargeting()` and gating
-    /// `SpellStopTargeting()`, whose 1/nil return the ESC chain's rung (`UIParent.lua:1490`)
-    /// falls through on, exactly like [`Self::casting`]'s.
+    /// Spell targeting is on (`SpellIsTargeting`, `0x6e6cd0`); it gates `SpellStopTargeting()`,
+    /// whose nil the ESC chain falls through on (`UIParent.lua:1490`).
     pub(crate) spell_targeting: bool,
-    /// Whether the standing targeting word could bind a UNIT — what `SpellCanTargetUnit` answers
-    /// (`0x6e6d00` → `0x6e6460`'s unit leg). Pushed by the app beside `spell_targeting`.
-    ///
-    /// Always `false` today, and *derived* rather than hardcoded so it stops being false the moment
-    /// that stops being true: benilla's targeting cursor models the location / item / gameobject
-    /// words (0792/0923/0939), and no unit satisfies any of them — a unit-target spell never enters
-    /// targeting mode at all, it resolves to `CastWireTarget::Unit` or refuses.
+    /// `SpellCanTargetUnit` (`0x6e6d00`, `0x6e6460`): false while targeting models only location,
+    /// item and object words; a unit-target spell resolves or refuses without entering targeting.
     pub(crate) spell_can_target_unit: bool,
-    /// Set when `SpellStopTargeting()` fired while [`Self::spell_targeting`] — the ESC-chain
-    /// targeting cancel, drained by [`super::UiScript::take_stop_targeting`] ([`spellbook`]).
+    /// `SpellStopTargeting()` fired while targeting: the ESC targeting cancel.
     pub(crate) spell_stop_targeting: bool,
 
-    /// The player's talent pages (decision 0304) — tabs + per-tab talents the
-    /// `GetNumTalentTabs`/`GetTalentInfo`/… bindings read ([`super::talent`]). Durable player
-    /// state like `spellbook`; "no talents yet" is simply empty.
     pub(crate) talents: super::talent::TalentUiState,
-    /// `LearnTalent(tab, index)` clicks queued since the app's last
-    /// [`super::UiScript::take_talent_learns`] drain.
+    /// `LearnTalent(tab, index)` calls queued.
     pub(crate) talent_learns: Vec<(u32, u32)>,
-    /// `ConfirmTalentWipe()` calls queued since the app last drained them — each is one outbound
-    /// `MSG_TALENT_WIPE_CONFIRM`. A COUNT for [`Self::binder_confirms`]'s reason: the app holds
-    /// the trainer's guid, so the intent carries no payload of its own (decision 1580).
+    /// `ConfirmTalentWipe()` calls, one `MSG_TALENT_WIPE_CONFIRM` each; the app holds the trainer.
     pub(crate) talent_wipe_confirms: u32,
-    /// Is a trainer's respec question still live and in range — the answer
-    /// `CheckTalentMasterDist()` gives, pushed by the app each frame
-    /// ([`super::UiScript::set_talent_master_pending`]). The CONFIRM_TALENT_WIPE dialog polls it
-    /// from OnUpdate and hides itself when it goes false; the binder question's twin, and the same
-    /// range gate stands behind both (decision 1580).
+    /// `CheckTalentMasterDist()`: the respec question is live and in range; false hides its dialog.
     pub(crate) talent_master_pending: bool,
-    // ── The dialog engine's verbs (decision 1963; `0x48dca0` is the first below) ──
-    /// `ConfirmPetUnlearn()` calls since the app's last drain — the pet trainer's twin of
-    /// [`Self::talent_wipe_confirms`]; the app holds the latched trainer and the money gate.
+    // ── The dialog engine's verbs (`0x48dca0` is the first below) ──
+    /// `ConfirmPetUnlearn()` calls; the app holds the trainer and the money gate.
     pub(crate) pet_unlearn_confirms: u32,
-    /// Whether the pet trainer's question is pending AND the trainer is in reach — what
-    /// `CheckPetUntrainerDist()` answers, pushed by the app each frame.
+    /// `CheckPetUntrainerDist()`: the pet trainer's question is pending and in reach.
     pub(crate) pet_untrainer_pending: bool,
-    /// `GetInstanceBootTimeRemaining()`'s answer in whole seconds, 0 when idle — the app derives
-    /// it from the `SMSG_RAID_GROUP_ONLY` deadline each frame.
+    /// `GetInstanceBootTimeRemaining()` in whole seconds, from the `SMSG_RAID_GROUP_ONLY` deadline.
     pub(crate) instance_boot_secs: u32,
-    /// Whether a battleground spirit healer is the cached current-area healer (a non-zero
-    /// `[0xb4e330/334]`), and the seconds to its next wave (`[0xb4e338]`), both the app's.
+    /// A cached area spirit healer (`[0xb4e330/334]`) and seconds to its wave (`[0xb4e338]`).
     pub(crate) area_spirit_healer_cached: bool,
     pub(crate) area_spirit_secs: u32,
-    /// `AcceptAreaSpiritHeal()` calls since the last drain (each one `CMSG_AREA_SPIRIT_HEALER_QUEUE`
-    /// with the cached healer — the app holds the guid).
+    /// `AcceptAreaSpiritHeal()` calls, one `CMSG_AREA_SPIRIT_HEALER_QUEUE` each.
     pub(crate) area_spirit_accepts: u32,
     /// `AcceptBattlefieldPort(index, accept)` calls: the 1-based slot and the normalised answer.
     pub(crate) battlefield_port_requests: Vec<(u8, bool)>,
-    /// The battleground scoreboard (1972): the pushed rows, the faction filter, the sorted order.
+    /// The battleground scoreboard: pushed rows, faction filter, sort order.
     pub(crate) battlefield_board: super::battlefield_score::ScoreBoard,
-    /// `GetBattlefieldInstanceRunTime()`'s answer, pushed each frame by the app's clock.
+    /// `GetBattlefieldInstanceRunTime()`, pushed each frame.
     pub(crate) battlefield_run_time_ms: u32,
-    /// `RequestBattlefieldScoreData()` calls since the last drain.
+    /// `RequestBattlefieldScoreData()` calls.
     pub(crate) battlefield_score_requests: u32,
-    /// `LeaveBattlefield()` calls that passed the "ended" gate since the last drain.
+    /// `LeaveBattlefield()` calls that passed the "ended" gate.
     pub(crate) battlefield_leave_requests: u32,
-    /// The battleground instance list and its scalars (1974), as the app last pushed them.
+    /// The battleground instance list and its scalars, as pushed.
     pub(crate) battlefield_list: super::battlefield_queue::BattlefieldListView,
-    /// `[0xb6eba0]` — the selected instance id (a VALUE; `SetSelectedBattlefield` writes it).
+    /// The selected instance id (`[0xb6eba0]`), not an index; written by `SetSelectedBattlefield`.
     pub(crate) battlefield_selected: u32,
-    /// The three queue slots (1974), pushed each frame with their clock-shaped values reduced.
+    /// The three queue slots, pushed each frame with their clocks reduced to values.
     pub(crate) battlefield_slots: Vec<super::battlefield_queue::BattlefieldQueueSlot>,
-    /// `GetBattlefieldInstanceExpiration()`'s answer, pushed each frame.
+    /// `GetBattlefieldInstanceExpiration()`, pushed each frame.
     pub(crate) battlefield_instance_expiration_ms: u32,
-    /// `JoinBattlefield` calls since the last drain: `(instance id, as group)`.
+    /// `JoinBattlefield` calls, `(instance id, as group)`.
     pub(crate) battlefield_join_requests: Vec<(u32, bool)>,
     /// `ShowBattlefieldList` calls that passed their gates: the queued slot's map id.
     pub(crate) battlefield_list_requests: Vec<u32>,
-    /// The battleground teammates' map positions as the app resolved them (1980), the flag
-    /// carrier, the active map's icon scale, and `RequestBattlefieldPositions()` calls.
+    /// Teammates' map positions, the flag carrier, the icon scale and position requests.
     pub(crate) battlefield_positions: Vec<super::battlefield_positions::BattlefieldPositionView>,
     pub(crate) battlefield_flag: Option<super::battlefield_positions::BattlefieldFlagView>,
     pub(crate) battlefield_icon_scale: f32,
     pub(crate) battlefield_position_requests: u32,
-    /// `CancelMeetingStoneRequest()` calls since the last drain — the app gates on leadership.
+    /// `CancelMeetingStoneRequest()` calls; the app gates on leadership.
     pub(crate) meeting_stone_cancels: u32,
-    /// The meeting stone's queued area (`[0xb72038]`) and cached status text (`[0xb7203c]`), as the
-    /// app last pushed them (1974).
+    /// The meeting stone's queued area (`[0xb72038]`) and status text (`[0xb7203c]`), as pushed.
     pub(crate) meeting_stone_area: u32,
     pub(crate) meeting_stone_status_text: Option<String>,
-    /// The tutorial system's acknowledged bank, as the app last pushed it (1976); `None` before
-    /// `SMSG_TUTORIAL_FLAGS` — `TutorialsEnabled()`'s only input.
+    /// Acknowledged tutorials, `None` before `SMSG_TUTORIAL_FLAGS`; all `TutorialsEnabled()` reads.
     pub(crate) tutorial_bank: Option<Vec<u8>>,
-    /// `FlagTutorial(n)` calls since the last drain (0-based, in range).
+    /// `FlagTutorial(n)` calls, 0-based and in range.
     pub(crate) tutorial_flag_requests: Vec<u32>,
     pub(crate) tutorial_clears: u32,
     pub(crate) tutorial_resets: u32,
 
-    /// The stance/shapeshift bar's form list (bar order) the app pushes — the
-    /// `GetNumShapeshiftForms`/`GetShapeshiftFormInfo` family reads it ([`super::shapeshift`]).
-    /// Durable player state like `spellbook`; "no forms" (a mage) is simply empty.
+    /// The stance bar's forms, in bar order.
     pub(crate) shapeshift_forms: Vec<super::shapeshift::StoredShapeshiftForm>,
-    /// Form spell ids `CastShapeshiftForm` queued since the app's last
-    /// [`super::UiScript::take_shapeshift_casts`] drain.
+    /// Form spell ids `CastShapeshiftForm` queued.
     pub(crate) shapeshift_casts: Vec<u32>,
 
-    /// The pet action bar the app pushes — the ten slots plus the two bar-wide bits the
-    /// `PetHasActionBar`/`GetPetActionsUsable`/`GetPetActionInfo` family reads ([`super::pet`],
-    /// decision 0982). Unlike the stance bar's, this state is **server-authoritative**: it is
-    /// replaced wholesale on every `SMSG_PET_SPELLS`, and is empty whenever there is no pet.
+    /// The pet bar's ten slots and two bar-wide bits, replaced whole by every `SMSG_PET_SPELLS`.
     pub(crate) pet_bar: super::pet::PetBarState,
-    /// 1-based slot indices `CastPetAction` queued since the app's last
-    /// [`super::UiScript::take_pet_actions`] drain.
+    /// 1-based slots `CastPetAction` queued.
     pub(crate) pet_actions_pressed: Vec<u32>,
     /// 1-based slot indices `TogglePetAutocast` queued.
     pub(crate) pet_autocast_toggles: Vec<u32>,
-    /// `PetStopAttack()` calls queued — a count, since the verb takes no argument.
+    /// `PetStopAttack()` calls.
     pub(crate) pet_stop_attacks: u32,
-    /// The pet one-shot orders (`PetAttack`, `PetFollow`, `PetWait`, the three modes), each the
-    /// packed slot word the bar's own command or reaction slot would carry — the app's drain
-    /// presses them exactly as a slot (1958).
+    /// `PetAttack`, `PetFollow`, `PetWait` and mode orders, as the packed word of their bar slot.
     pub(crate) pet_orders: Vec<u32>,
-    /// `HasFullControl`'s flag — the reference's `[0xb4b3e4]`, written by
-    /// `SMSG_CLIENT_CONTROL_UPDATE` naming the local player and read as "if zero, refuse" by
-    /// every cast, item and cursor gate. Boot value 1.
+    /// `HasFullControl`, the reference's `[0xb4b3e4]`: set by `SMSG_CLIENT_CONTROL_UPDATE` for the
+    /// player, boots 1, and every cast, item and cursor gate refuses at 0.
     pub(crate) player_control: bool,
-    /// Pet bar writes queued by the drag ([`cursor::pet`], decision 1010) — **one entry per
-    /// `CMSG_PET_SET_ACTION`**, each holding the one or two `(0-based position, packed word)` pairs
-    /// that send names. The nesting is the point: the server tells the one-pair form from the
-    /// two-pair form **by body size**, so a relocation and its write must travel together and must
-    /// not be flattened into a stream of singles.
+    /// One `CMSG_PET_SET_ACTION` per entry, its one or two `(position, packed word)` pairs: the
+    /// server tells the forms apart by body size, so a move's two pairs must not be flattened.
     pub(crate) pet_set_actions: Vec<Vec<(u32, u32)>>,
-    /// `PetAbandon()` and `PetDismiss()` calls queued — two counts, not one, even though both menu
-    /// rows end at the same opcode (decision 1066). They are two *bindings*, with two Lua names and
-    /// two menu rows the reference shows to different classes, so the seam keeps them apart and
-    /// lets the app decide each one's wire; folding them together here would bake a wire fact into
-    /// an engine that is supposed to hold none.
+    /// `PetAbandon()` and `PetDismiss()` calls, counted apart though both end at one opcode.
     pub(crate) pet_abandons: u32,
     pub(crate) pet_dismisses: u32,
-    /// Names `PetRename(name)` queued, in order — the `PETRENAMECONFIRM` popup's payload.
+    /// Names `PetRename` queued, from the `PETRENAMECONFIRM` popup.
     pub(crate) pet_renames: Vec<String>,
 
-    /// The per-bag container snapshot (keyed by live-API bag id, 0 = backpack) the app pushes,
-    /// and the `UseContainerItem` intents it drains — the container seam ([`container`]).
+    /// Bag contents by API bag id (0 is the backpack), and the queued `UseContainerItem` calls.
     pub(crate) containers: HashMap<i64, container::ContainerState>,
     pub(crate) container_uses: Vec<(i64, u32)>,
-    /// Per-(bag, slot) use-cooldowns in `GetTime` seconds `(start, duration, enabled)` — stamped
-    /// at `set_container` push time (the action-state pattern), read by
-    /// `GetContainerItemCooldown`.
+    /// Per `(bag, slot)`, `(start, duration, enabled)` in `GetTime` seconds, stamped at push.
     pub(crate) container_cooldowns: HashMap<(i64, u32), (f64, f64, bool)>,
-    /// `HasKey()` — whether the player owns any item of `BagFamily` KEYS, anywhere the reference's
-    /// own search reaches (equipment, bags, backpack, **bank**, keyring). App-resolved like every
-    /// other item fact; the engine holds no item knowledge of its own. Gates the whole keyring UI
-    /// (decision 0765).
+    /// `HasKey()`: a keys-family item in equipment, bags, bank or keyring; gates the keyring UI.
     pub(crate) has_key: bool,
-    /// What the cursor carries (`PickupContainerItem`/`SplitContainerItem`/… set it; `None` =
-    /// empty cursor) — the real client's transient drag state, typed by payload arm
-    /// ([`cursor::CursorPayload`], decision 0216). Purely visual + intent-routing: no item moves
-    /// locally, the server's field updates settle the bag ([`container`]). The app draws the
-    /// held icon at the mouse and reads `None`/`Some` to show/hide it.
+    /// What the cursor carries; nothing moves locally, the server's updates settle the bags.
     pub(crate) cursor: Option<cursor::CursorPayload>,
-    /// Mirrors "is `cursor` currently `Some`" across transitions — [`cursor::queue_cursor_update`]
-    /// compares it against the live state on every call to derive `ACTIONBAR_SHOWGRID`/
-    /// `ACTIONBAR_HIDEGRID` (decision 0216 §7): fires exactly on a None↔Some edge, any payload
-    /// arm, any surface (bags/doll/actions alike — the reference's own "any placeable payload
-    /// shows the bar's drop grid"). A Some→Some transition (the action hop) updates nothing here,
-    /// so no spurious HIDE+SHOW churns out of one gesture.
-    ///
-    /// The **pet** payload arm is excluded (decision 1010): `PlaceAction` refuses it, so lighting
-    /// the action bar's empty slots for a payload that cannot land there would be an invitation to
-    /// a no-op. It drives [`Self::pet_grid_shown`] instead. So is the **vendor row** (mode 5): its
-    /// grab setter `0x4950f0` fires `ACTIONBAR_SHOWGRID` for mode 7 alone.
+    /// The action bar's drop grid: shown on the cursor's empty-to-held edge for any payload but a
+    /// pet action or a vendor row (mode 5; the grab setter `0x4950f0` shows it for mode 7 only).
     pub(crate) cursor_grid_shown: bool,
-    /// The same mirror for the PET bar's grid — `PET_BAR_SHOWGRID`/`PET_BAR_HIDEGRID`, which the
-    /// reference fires from inside the pet-action pickup builder itself (`0x494f28`) rather than
-    /// from a shared cursor transition. So the two grids are disjoint: a spell lights the action
-    /// bar's, a pet action lights the pet bar's, and neither lights both.
+    /// The pet bar's grid, lit only by a pet-action pickup (`0x494f28`); never both grids at once.
     pub(crate) pet_grid_shown: bool,
-    /// The app's world pick under the cursor — the reference's click-time pick state
-    /// (`[this+0x350]`: nothing / terrain / object), fed once per frame
-    /// ([`super::UiScript::set_world_pick`]; stays `Nothing` in tests/captures). Routes
-    /// [`cursor::world_drop_click`]'s legs (decisions 0571 + 0574): an `Object` pick drops no
-    /// payload at all, `Terrain` drops items only (a spell/action survives the ground click),
-    /// `Nothing` drops any arm.
+    /// The world pick under the cursor (`[this+0x350]`): a world click drops no payload on an
+    /// object, only an item on terrain, and anything over nothing.
     pub(crate) world_pick: cursor::WorldPick,
-    /// Backpack pick/place/swap intents queued by `PickupContainerItem`/`SplitContainerItem` when
-    /// the cursor was holding (src bag/slot → dst bag/slot, live-API space, optional split count),
-    /// drained by the app into `CMSG_SWAP_INV_ITEM`/`CMSG_SPLIT_ITEM`.
+    /// Held-item bag moves, sent as `CMSG_SWAP_INV_ITEM` or `CMSG_SPLIT_ITEM`.
     pub(crate) container_moves: Vec<container::ContainerMove>,
-    /// Repair-mode clicks the pickup intercept queued (`(bag, slot)`; [`container`]).
+    /// `(bag, slot)` clicks made in repair mode.
     pub(crate) container_repairs: Vec<(i64, u32)>,
-    /// The targeting cursor's **item** half is up (`TargetingWantsItem 0x6e6330`, decision 0923;
-    /// first built for the CraftFrame enchant pick, 0437 phase 3): while set, a bag OR paper-doll
-    /// click queues into [`Self::item_picks`] instead of running the cursor gesture.
+    /// Targeting wants an item (`0x6e6330`): a bag or paper-doll click becomes a pick.
     pub(crate) item_pick_armed: bool,
-    /// `(bag, slot)` clicks consumed by the armed item pick, drained by the app. A doll click
-    /// reports as [`super::EQUIPMENT_BAG`] + its 1-based inventory slot, so both seams speak the
-    /// one bag space the drain already resolves.
+    /// Picked `(bag, slot)`s; a paper-doll click is `EQUIPMENT_BAG` and its 1-based inventory slot.
     pub(crate) item_picks: Vec<(i64, u32)>,
-    /// `BindEnchant()`/`ReplaceEnchant()` — the two enchant-confirm popups' answers to a pick the
-    /// app already parked, drained by it (decision 0928; [`cursor::EnchantConfirm`]).
+    /// `BindEnchant()` and `ReplaceEnchant()`, the enchant popups' answers.
     pub(crate) enchant_confirms: Vec<cursor::EnchantConfirm>,
-    /// `(bag, slot, count)` triples queued by `DeleteCursorItem` (`count == 0` = the whole
-    /// stack) — the popup-confirmed destroy (decision 0216 §3), drained by the app into
-    /// `CMSG_DESTROYITEM`.
+    /// `DeleteCursorItem`'s `(bag, slot, count)`, 0 for the whole stack, as `CMSG_DESTROYITEM`.
     pub(crate) container_destroys: Vec<(i64, u32, u32)>,
-    /// **The armed gift wrap** — the `(bag, slot)` of a piece of wrapping paper whose right-click
-    /// took the reference's begin-wrap arm (`0x5edea0`: lock the paper, cursor mode 2, no packet).
-    /// `None` = nothing armed, which is nearly always. Decision 1934.
-    ///
-    /// Deliberately **not** a [`cursor::CursorPayload`]: the reference writes no payload global at
-    /// all here, only the displayed-cursor mode, so `CursorHasItem()` stays nil and none of the
-    /// thirteen stock `CursorHasItem()` gates open. Making it a payload would silently open every
-    /// one of them — the same trap decision 1677's mode-5 note names for the vendor cursor.
+    /// The wrapping paper a right-click armed (`0x5edea0`: lock it, cursor mode 2, no packet). Not
+    /// a cursor payload: the reference sets only the cursor mode, so `CursorHasItem()` stays nil.
     pub(crate) pending_wrap: Option<container::PendingWrap>,
-    /// `(giftBag, giftSlot, itemBag, itemSlot)` quads a completed wrap queued, drained by the app
-    /// into `CMSG_WRAP_ITEM`. The paper's pair leads, as the wire does.
+    /// `(giftBag, giftSlot, itemBag, itemSlot)` per completed wrap, in `CMSG_WRAP_ITEM`'s order.
     pub(crate) container_wraps: Vec<(i64, u32, i64, u32)>,
-    /// The Lua-set **displayed-cursor override** (`ShowContainerSellCursor`/`ShowMerchantSellCursor`/
-    /// `ShowBuybackSellCursor`/`ShowInspectCursor` set it, `ResetCursor` clears it; [`container`] +
-    /// [`merchant`]) — the single "displayed mode" the real client keeps at `0xbe2c2c`, restored to
-    /// the base (world-classifier) mode by `ResetCursor`. `None` = no override (show the base mode).
+    /// The cursor mode Lua set (`0xbe2c2c`); `ResetCursor` returns it to the world's mode.
     pub(crate) ui_cursor: Option<container::UiCursorMode>,
-    /// Set by every FrameXML cursor call — `Show*SellCursor` / `ShowInspectCursor` / `SetCursor` /
-    /// `ResetCursor` — and drained by the app each frame ([`UiScript::take_cursor_write`]).
-    ///
-    /// **The cursor mode is a WRITE, not a level** (decision 1061), and that distinction is the
-    /// whole of B208's regression. The reference keeps one sticky global (`0xbe2c2c`): the world
-    /// classifier writes it while the pointer is over the world, FrameXML writes it from a hover
-    /// handler, and in between **nothing** writes it — so the last value simply stands. Reading
-    /// `ui_cursor` as a level made "no override" mean "show the base", which turned every UI
-    /// element with no cursor handler at all (a spellbook button, a panel) into a forced Point and
-    /// killed the armed cast cursor the moment the mouse left the world.
+    /// A FrameXML cursor call ran. The mode is a write, not a level: `0xbe2c2c` keeps its value
+    /// until the world or a hover handler writes it, so a handler-less frame leaves it be.
     pub(crate) ui_cursor_dirty: bool,
-    /// `(bag, slot)` sources queued by `AutoEquipCursorItem` (decision 0208 phase 1b, `cursor`'s
-    /// `doll` submodule) — drained by the app into `CMSG_AUTOEQUIP_ITEM`.
+    /// `AutoEquipCursorItem`'s `(bag, slot)` sources, sent as `CMSG_AUTOEQUIP_ITEM`.
     pub(crate) container_autoequips: Vec<(i64, u32)>,
-    /// Auto-stores queued by `PutItemInBag`/`PutItemInBackpack` (`cursor`'s `bag_verbs` submodule) —
-    /// drained by the app into `CMSG_AUTOSTORE_BAG_ITEM` (or `CMSG_SPLIT_ITEM` for a split carry).
+    /// `PutItemInBag` and `PutItemInBackpack` stores, sent as `CMSG_AUTOSTORE_BAG_ITEM`, or
+    /// `CMSG_SPLIT_ITEM` for a split stack.
     pub(crate) bag_autostores: Vec<container::BagAutoStore>,
 
-    /// Per-frame drag-button registrations (`RegisterForDrag`) — kind-independent (any Frame, not
-    /// just a Button), so it lives beside [`Model::mouse_down_on`] rather than inside a per-kind
-    /// state. Verbatim button-name sets (`"LeftButton"`, …); [`UiScript::mouse_button`]/
-    /// [`UiScript::mouse_move`] compare case-insensitively (RF's `RegisterForClicks` precedent).
-    /// Same destroy-cleanup status as [`Model::scripts`]/[`Model::frame_events`]: nothing in this
-    /// engine destroys a frame yet (no Lua `Destroy`, no call to `WidgetArena::destroy` outside
-    /// its own tests), so none of the three is pruned today — a future destroy path must prune
-    /// all three together.
+    /// `RegisterForDrag` buttons per frame, compared case-insensitively. Nothing destroys a frame,
+    /// so this, `scripts` and `frame_events` are never pruned; a destroy path must prune all three.
     pub(crate) drag_registered: HashMap<FrameHandle, HashSet<String>>,
-    /// The in-flight drag gesture: armed at mouse-down on a [`Model::drag_registered`] frame,
-    /// `started` once the cursor has moved past the drag-start threshold — `None` between
-    /// gestures ([`cursor::DragGesture`], decision 0216 §3).
+    /// The drag gesture, armed by a press on a drag-registered frame, started past the threshold.
     pub(crate) drag: Option<cursor::DragGesture>,
-    /// The one in-flight `StartMoving()` — the client's single root-side drag slot (`root+0xcfc`
-    /// and the cursor sample beside it), `None` between moves ([`super::object::FrameMove`]). Held
-    /// beside [`Model::drag`] because that gesture is what normally opens and closes it: the
-    /// canonical addon idiom is `OnDragStart → StartMoving`, `OnDragStop → StopMovingOrSizing`.
-    /// The two remain separate systems, exactly as in the reference — a drag can carry a payload
-    /// with nothing moving, and a move outlives the mouse button (the reference's mouse-up
-    /// auto-stop skips the Lua drag type).
+    /// The one `StartMoving()` in flight, the client's `root+0xcfc` slot, apart from `drag` as in
+    /// the reference: a move outlives the button, since mouse-up's auto-stop skips a Lua drag.
     pub(crate) moving: Option<super::object::FrameMove>,
-    /// The in-flight `StartSizing` drag — the resize twin of [`Self::moving`], cleared by the same
-    /// `StopMovingOrSizing` (`0x776990`).
+    /// The `StartSizing` in flight, cleared by `StopMovingOrSizing` (`0x776990`).
     pub(crate) sizing: Option<super::object::FrameSizing>,
-    /// The in-flight Slider thumb drag: set when a LeftButton press lands on a Slider's thumb, held
-    /// until release / pointer-leave (decision 0250 §5, the engine's C++-equivalent thumb drag —
-    /// like a scrollbar dragging in the real client, no Lua involved). `None` between drags
-    /// ([`slider::SliderDrag`]).
+    /// A Slider thumb drag, left press to release or pointer leave, handled here with no Lua.
     pub(crate) slider_drag: Option<slider::SliderDrag>,
-    /// The in-flight ColorSelect drag — the colour picker's wheel/value-strip twin of
-    /// [`Self::slider_drag`], held from press to release. The widget keeps two independent capture
-    /// flags rather than one target ([`colorselect::ColorDrag`]).
+    /// A ColorSelect wheel or value-bar drag, press to release.
     pub(crate) color_drag: Option<colorselect::ColorDrag>,
 
-    /// The open gossip menu the app pushes (`None` = no menu), the `SelectGossipOption` intents it
-    /// drains, and whether `CloseGossip` was called — the gossip seam ([`gossip`]).
+    /// The open gossip menu, the `SelectGossipOption` calls and whether `CloseGossip` ran.
     pub(crate) gossip: Option<gossip::GossipMenu>,
     pub(crate) gossip_selects: Vec<u32>,
     pub(crate) gossip_close: bool,
-    /// 1-based quest-row selects queued by `SelectGossipQuest` (decision 0088) — the app maps each
-    /// to the row's quest id and sends `CMSG_QUESTGIVER_QUERY_QUEST`.
+    /// `SelectGossipQuest` 1-based rows, each sent as `CMSG_QUESTGIVER_QUERY_QUEST` for its quest.
     pub(crate) gossip_quest_selects: Vec<u32>,
 
-    /// The open merchant's stock snapshot the app pushes (`None` = no vendor open), the
-    /// `BuyMerchantItem` intents it drains, and whether `CloseMerchant` was called — the merchant
-    /// seam ([`merchant`]).
+    /// The open vendor's stock, the `BuyMerchantItem` calls and whether `CloseMerchant` ran.
     pub(crate) merchant: Option<merchant::MerchantState>,
     pub(crate) merchant_buys: Vec<(u32, u32)>,
-    /// `PickupMerchantItem`'s SELL arm — the `(bag, slot)` the cursor was holding when it was
-    /// called over the vendor window. The app resolves the guid and sends `CMSG_SELL_ITEM`.
+    /// The held `(bag, slot)` when `PickupMerchantItem` sells, sent as `CMSG_SELL_ITEM`.
     pub(crate) merchant_cursor_sells: Vec<(i64, u32)>,
-    /// A held vendor row dropped into a bag — `(bag, slot, item entry)`, the app's
-    /// `CMSG_BUY_ITEM_IN_SLOT`.
+    /// A held vendor row dropped in a bag, `(bag, slot, item entry)`, for `CMSG_BUY_ITEM_IN_SLOT`.
     pub(crate) merchant_slot_buys: Vec<(i64, u32, u32)>,
     pub(crate) merchant_close: bool,
-    /// `BuybackItem` intents (1-based buyback slots), the `RepairAllItems` flag, and the
-    /// client-side repair-mode latch (`ShowRepairCursor`/`InRepairMode`) — the rest of the
-    /// merchant seam.
+    /// `BuybackItem` 1-based slots, the `RepairAllItems` flag and repair mode (`InRepairMode`).
     pub(crate) merchant_buybacks: Vec<u32>,
     pub(crate) repair_all: bool,
     pub(crate) repair_mode: bool,
 
-    /// The stable window's whole state — the pushed snapshot, the selection, the frame-local
-    /// drag, and the queued verbs (the stable seam, [`stable`], decision 1676). One sub-struct
-    /// rather than five loose fields because the close path resets several of them together.
+    /// The stable window: snapshot, selection, drag and queued calls, reset together on close.
     pub(crate) stable: stable::StableModel,
 
-    /// The open bank's purchase-row snapshot the app pushes (`None` = no bank open), the
-    /// `PurchaseSlot` intent, and whether `CloseBankFrame` was called — the bank seam ([`bank`],
-    /// decision 0604; the bank's *contents* ride the container seam as bags −1/5..=10).
+    /// The open bank's slot-purchase row and calls; its contents are bags -1 and 5..=10.
     pub(crate) bank: Option<bank::BankState>,
     pub(crate) bank_purchase: bool,
     pub(crate) bank_close: bool,
 
-    /// The open trainer's service snapshot the app pushes (`None` = no trainer open), the
-    /// `BuyTrainerService` intents it drains, the engine-held selection, and whether `CloseTrainer`
-    /// was called — the trainer seam ([`trainer`], decision 0237).
-    ///
-    /// The selection is the selected service's **spell id**, not its row number. A row number is a
-    /// coordinate in a list that three independent things move under it — the state filter, a
-    /// collapse, and a re-list — and `GetTrainerSelectionIndex` answering with a stale-but-in-range
-    /// one is what left the detail pane describing a spell that had already left the window.
+    /// The open trainer, its buys, selection and close. The selection is a spell id, since
+    /// filters, collapses and re-lists all move row numbers.
     pub(crate) trainer: Option<trainer::TrainerState>,
     pub(crate) trainer_buys: Vec<u32>,
     pub(crate) trainer_selection: Option<u32>,
     pub(crate) trainer_close: bool,
-    /// The three state filters (available / unavailable / used) — the real client hides filtered
-    /// service rows itself ([`trainer`]); all shown by default. A state filter hides *services*, never
-    /// headers (decision 0247).
+    /// Available, unavailable and used filters, all on by default; they hide services, not headers.
     pub(crate) trainer_filter: [bool; 3],
-    /// The skill lines the player has collapsed in the tree — their services hide, the header stays
-    /// (decision 0247). Keyed by skill-line id so it survives a content update (`set_trainer` keeps
-    /// only still-present lines); cleared when the trainer closes.
+    /// Collapsed skill-line ids, kept across a re-push and cleared when the trainer closes.
     pub(crate) trainer_collapsed: HashSet<u32>,
 
-    /// The open taxi map's snapshot the app pushes (`None` = closed), the `TakeTaxiNode` intents
-    /// it drains, whether `CloseTaxiMap` was called, and whether our own player is riding a
-    /// taxi — the taxi seam ([`taxi`], decision 0484).
+    /// The open taxi map, the `TakeTaxiNode` calls, whether `CloseTaxiMap` ran and whether we ride.
     pub(crate) taxi: Option<taxi::TaxiUiState>,
     pub(crate) taxi_takes: Vec<usize>,
     pub(crate) taxi_close: bool,
     pub(crate) taxi_riding: bool,
 
-    /// The open tradeskill window's recipe snapshot the app pushes (`None` = no window open) — the
-    /// tradeskill seam ([`tradeskill`], decision 0437 phase 2).
+    /// The open tradeskill window's recipes.
     pub(crate) trade_skill: Option<tradeskill::TradeSkillState>,
-    /// `(spell id, count)` intents `DoTradeSkill` queued since the app's last
-    /// [`super::UiScript::take_trade_skill_dos`] drain.
+    /// `DoTradeSkill` calls, `(spell id, count)`.
     pub(crate) trade_skill_dos: Vec<(u32, u32)>,
-    /// The engine-held 1-based selection (0 = none), preserved across a `set_trade_skill` re-push by
-    /// the recipe's spell id (see [`super::UiScript::set_trade_skill`]).
+    /// The 1-based selection, 0 for none, carried across a re-push by the recipe's spell id.
     pub(crate) trade_skill_selection: u32,
-    /// Whether `CloseTradeSkill` was called since the app's last
-    /// [`super::UiScript::take_trade_skill_close`] drain.
     pub(crate) trade_skill_close: bool,
-    /// The recipe groups the player has collapsed, by group key `(ItemClass, ItemSubClass)`
-    /// (`0x55ba30` resolves the key) — a group's recipes hide, its header stays (the
-    /// trainer/skills-pane precedent, [`Model::trainer_collapsed`]/[`Model::skills_collapsed`]).
-    /// Survives a `set_trade_skill` content re-push (pruned to the groups the fresh recipes still
-    /// produce) AND a same-profession close→reopen (the collapse
-    /// mask `0x84dd68` round-trips the rebuild by header key); reset on a profession switch
-    /// ([`Model::trade_skill_last_line`]).
+    /// Collapsed recipe groups by `(ItemClass, ItemSubClass)` (`0x55ba30`), kept across a re-push
+    /// and a same-profession reopen like the mask `0x84dd68`; a profession switch resets them.
     pub(crate) trade_skill_collapsed: HashSet<(u32, u32)>,
-    /// Group keys the SubClass filter dropdown has hidden (empty = "All Subclasses"). Keyed like
-    /// [`Model::trade_skill_collapsed`] — the real client's per-header shown flag (`header+0xc`)
-    /// survives a rebuild by exactly this `(ItemClass, ItemSubClass)` key match (`0x4fca20`'s
-    /// save→restore loop; the position mask `0x84dd60` is the derived form). Persists across a
-    /// same-profession close/reopen; reset on a profession switch
-    /// ([`Model::trade_skill_last_line`]).
+    /// Groups the SubClass filter hides, empty for all, kept by key like the client's header flag
+    /// (`header+0xc`, `0x4fca20`, mask `0x84dd60`); a profession switch resets them.
     pub(crate) trade_skill_subclass_hidden: HashSet<(u32, u32)>,
-    /// The InvSlot filter mask (`0x84dd64`): **bit set = slot shown**,
-    /// all-ones = "All Slots". The real client's build never touches this static — it is NOT
-    /// pruned on a re-push, and an exclusive pick therefore keeps every OTHER bit clear even for
-    /// slots that appear later. Reset (all-ones) only on a profession switch.
+    /// The InvSlot filter mask (`0x84dd64`), a set bit shown and all ones for all slots. Never
+    /// pruned on a re-push, as in the client, so a later slot stays hidden; a switch resets it.
     pub(crate) trade_skill_invslot_mask: u32,
-    /// The skill line the tradeskill state was last built for (`0xbde064`, the cache
-    /// key): a `set_trade_skill` push for a DIFFERENT line resets the two filters, the collapse
-    /// set, and the selection; the same line (including a close→reopen round trip) keeps them.
+    /// The skill line the state was last built for (`0xbde064`): a push for another line resets
+    /// the filters, collapses and selection; the same line keeps them, even across a reopen.
     pub(crate) trade_skill_last_line: u32,
-    /// The selected recipe's SPELL ID (`0xbde044` — the real client stores the selection by spell
-    /// id, not index), shadowing [`Model::trade_skill_selection`]'s flat position so the selection
-    /// survives a same-profession close→reopen (untouched on that path) and remaps across a
-    /// re-push.
+    /// The selected recipe's spell id (`0xbde044`), which carries it across reopen and re-push.
     pub(crate) trade_skill_selected_spell: u32,
-    /// Set by the engine-side mutators the real client answers with a `TRADE_SKILL_UPDATE` event
-    /// from inside the C call (`Set*Filter`/`Expand/CollapseTradeSkillSubClass` → the
-    /// `0x4fd710`/`0x4fd730`/`0x4fd750` writer trio → recompute+resort `0x4fd180` + event
-    /// **0x13a**); the app drains it ([`super::UiScript::take_trade_skill_touched`]) and fires
-    /// the event the same frame.
+    /// A filter or subclass collapse changed: `TRADE_SKILL_UPDATE` (`0x13a`) is owed this frame, as
+    /// the client fires it inside the call (`0x4fd710`/`0x4fd730`/`0x4fd750`, `0x4fd180`).
     pub(crate) trade_skill_touched: bool,
 
-    /// The open craft window's recipe snapshot the app pushes (`None` = no window open) — the craft
-    /// seam ([`craft`], decision 0437 phase 3), TradeSkill's exact twin.
+    /// The open craft window's recipes.
     pub(crate) craft: Option<craft::CraftState>,
-    /// Spell id intents `DoCraft` queued since the app's last [`super::UiScript::take_craft_dos`]
-    /// drain — no count (the 1.12 CraftFrame has no Create All, unlike `trade_skill_dos`).
+    /// `DoCraft` spell ids; no count, as the 1.12 CraftFrame has no Create All.
     pub(crate) craft_dos: Vec<u32>,
-    /// The engine-held 1-based selection (0 = none), preserved across a `set_craft` re-push by the
-    /// recipe's spell id (see [`super::UiScript::set_craft`]).
+    /// The 1-based selection, 0 for none, carried across a re-push by the recipe's spell id.
     pub(crate) craft_selection: u32,
-    /// Whether `CloseCraft` was called since the app's last [`super::UiScript::take_craft_close`]
-    /// drain.
     pub(crate) craft_close: bool,
 
-    /// The `EquipPendingItem`/`CancelPendingEquip` answers the app drains, in call order, and the
-    /// `ConfirmBindOnUse()` count — the non-loot soulbind confirmations' whole Lua side
-    /// ([`bind_confirm`], decision 1750). The pending records themselves are the app's.
+    /// `EquipPendingItem`/`CancelPendingEquip` answers in order, and `ConfirmBindOnUse()` calls.
     pub(crate) pending_equip_answers: Vec<bind_confirm::PendingEquipAnswer>,
     pub(crate) bind_on_use_confirms: u32,
 
-    /// The open loot's row snapshot the app pushes (`None` = no loot open), the row-pick intents it
-    /// drains, and whether `CloseLoot` was called — the loot seam ([`loot`]).
-    ///
-    /// **The picks come in two flavours, and the flavour is load-bearing** (decision 1744): the
-    /// reference's take dispatcher `0x4c2790(slot, flag)` is one function with two entries, and the
-    /// flag decides whether a bind-on-pickup row raises the LOOT_BIND confirm or is taken outright.
-    /// `flag == 0` is the row click, which in 1.12 is the C `CLootButton`'s own behaviour and here
-    /// is `BenillaTakeLootSlot`; `flag != 0` is the confirm continuation, which is the ONLY thing
-    /// the 1.12 Lua binding `LootSlot` does (`0x4c2e70` passes `edx = 1`, and its sole FrameXML
-    /// caller is `StaticPopupDialogs["LOOT_BIND"].OnAccept`).
+    /// The open loot, the row clicks and whether `CloseLoot` ran. A click is the reference's take
+    /// `0x4c2790` with flag 0, raising `LOOT_BIND` for a bind-on-pickup row (the C `CLootButton`,
+    /// here `BenillaTakeLootSlot`); `LootSlot` passes 1 (`0x4c2e70`), taking it after the confirm.
     pub(crate) loot: Option<loot::LootState>,
     pub(crate) loot_picks: Vec<u32>,
-    /// The `LootSlot(slot)` confirm continuations — 1-based display rows, drained separately from
-    /// [`Self::loot_picks`] so the app can honour the reference's pending-slot gate.
+    /// `LootSlot(slot)` rows, 1-based, apart from clicks for the reference's pending-slot gate.
     pub(crate) loot_confirms: Vec<u32>,
     pub(crate) loot_close: bool,
-    /// The `GiveMasterLoot(slot, candidateIndex)` assignments the app drains — both 1-based and
-    /// both display-side: the row as the window numbers it, and the candidate's position in
-    /// [`loot::LootState::master_candidates`]. The app owns the translation to the wire slot and
-    /// the recipient's guid (decision 1675).
+    /// `GiveMasterLoot(slot, candidateIndex)`, both 1-based display positions the app translates.
     pub(crate) loot_master_gives: Vec<(u32, u32)>,
 
-    /// The open group-loot rolls the app pushes (empty = none open) and the `RollOnLoot`
-    /// `(roll_id, roll_type)` votes it drains — the roll seam ([`loot_roll`], decision 0591).
+    /// The open group-loot rolls, and the `RollOnLoot` `(roll_id, roll_type)` votes.
     pub(crate) loot_rolls: loot_roll::LootRollsState,
     pub(crate) loot_roll_votes: Vec<(u32, u8)>,
-    /// Need/Greed on a **bind-on-pickup** roll: not a vote but a request for the
-    /// `CONFIRM_LOOT_ROLL` popup, which `ConfirmLootRoll` then re-enters past the gate
-    /// (decision 0594's binary correction).
+    /// Need or Greed on a bind-on-pickup roll: a `CONFIRM_LOOT_ROLL` popup ask, not a vote.
     pub(crate) loot_roll_confirms: Vec<(u32, u8)>,
 
-    /// The open mailbox's inbox snapshot the app pushes (`None` = no mailbox open) and the intents
-    /// the app drains — the mail seam ([`mail`], decision 0544). `mail_opens` are the 1-based rows
-    /// `GetInboxText` touched (the app marks each read + ask-once fetches its body); the take/delete/
-    /// return vecs are 1-based row picks; `mail_send` is the pending `SendMail(target,subject,body)`
-    /// the app folds `mail_send_money`/`mail_send_cod`/`mail_send_item` into at drain.
-    /// The item-text reader session ([`item_text`]): the pushed snapshot + the close/page-turn
-    /// intents the app drains.
+    /// The item-text reader: the pushed page, then the close and page-turn calls.
     pub(crate) item_text: Option<item_text::ItemTextState>,
     pub(crate) item_text_close: bool,
     pub(crate) item_text_page_turns: Vec<i32>,
+    /// The open inbox and mail calls, rows 1-based: `mail_opens` are rows `GetInboxText` read.
     pub(crate) mail: Option<mail::MailState>,
     pub(crate) mail_check_inbox: bool,
     pub(crate) mail_opens: Vec<u32>,
@@ -1372,30 +703,19 @@ pub(crate) struct Model {
     pub(crate) mail_send: Option<(String, String, String)>,
     pub(crate) mail_send_money: u32,
     pub(crate) mail_send_cod: u32,
-    /// The Send tab's attached bag item (a cursor drop, decision 0216) — carried until the send
-    /// fires; the app resolves its `(bag, slot)` to the wire item guid then.
+    /// The Send tab's attached item, resolved to its guid when the send fires.
     pub(crate) mail_send_item: Option<cursor::CursorItem>,
-    /// The usable stationery list the app pushes, in the picker's order (1970).
+    /// The usable stationery, in the picker's order.
     pub(crate) mail_stationeries: Vec<mail::StationeryView>,
-    /// `SelectStationery`'s stored `Stationery.dbc` id — 0 = none, which silences `SendMail`.
+    /// `SelectStationery`'s `Stationery.dbc` id; 0 is none, which silences `SendMail`.
     pub(crate) mail_stationery: u32,
-    /// `HasNewMail()` — login-scoped (survives the mailbox window closing, unlike [`Self::mail`]
-    /// above): the app's `MSG_QUERY_NEXT_MAIL_TIME`/`SMSG_RECEIVED_MAIL`-fed countdown reduced to
-    /// one flag (decision 0544 P3, `0x4afea0`). The reference minimap icon
-    /// (`MiniMapMailFrame`) reads this on `UPDATE_PENDING_MAIL`.
+    /// `HasNewMail()` (`0x4afea0`), from `MSG_QUERY_NEXT_MAIL_TIME` and `SMSG_RECEIVED_MAIL`.
     pub(crate) has_new_mail: bool,
 
-    /// The open auction house's snapshot the app pushes (`None` = no auctioneer session) and the
-    /// intents the app drains — the auction seam ([`auction`], decision 1511). `auction_selected`
-    /// is engine-local per list ([`auction::LIST`]/`BIDDER`/`OWNER`) and holds the selected
-    /// **auction id**, not a row position (`0x4cfda0`/`0x4cfec0`): an id follows its row through a
-    /// re-sort, where an index would quietly come to mean the auction that took its place. `0` =
-    /// nothing selected. It is engine-local because the reference reads the selection back
-    /// synchronously inside the same handler that sets it, so it cannot be a round trip. `auction_can_query` is the app's 5 s browse
-    /// throttle, pushed separately from the snapshot because the Search button polls it every
-    /// frame and it would otherwise churn the snapshot's diff.
+    /// The open auction house and the auction calls. `auction_selected` is each list's selected
+    /// auction id, 0 for none (`0x4cfda0`/`0x4cfec0`); `auction_can_query` is the 5 s throttle.
     pub(crate) auction: Option<auction::AuctionState>,
-    /// The Browse tab's class tree, login-scoped (`set_auction_item_classes`, 1971).
+    /// The Browse tab's class tree, pushed once per login.
     pub(crate) auction_item_classes: Vec<auction::AuctionCategory>,
     pub(crate) auction_selected: [u32; 3],
     pub(crate) auction_can_query: bool,
@@ -1407,410 +727,214 @@ pub(crate) struct Model {
     pub(crate) auction_start: Option<auction::AuctionStartRequest>,
     pub(crate) auction_sorts: Vec<(usize, String)>,
     pub(crate) auction_close: bool,
-    /// The sell slot's staged item (a cursor drop, decision 0216) — carried until `StartAuction`
-    /// fires, when the app resolves its `(bag, slot)` to the wire item guid.
+    /// The sell slot's item, resolved to its guid when `StartAuction` fires.
     pub(crate) auction_sell_item: Option<cursor::CursorItem>,
 
-    /// The open trade window's snapshot the app pushes (`None` = no trade open) and the intents the
-    /// app drains — the trade seam ([`trade`], decision 0592 P1). `trade_initiates` are the unit
-    /// tokens `InitiateTrade` queued (the app resolves each → guid → `CMSG_INITIATE_TRADE`); the
-    /// three flags are the accept / un-accept / cancel verbs (`CMSG_ACCEPT_TRADE` /
-    /// `CMSG_UNACCEPT_TRADE` / `CMSG_CANCEL_TRADE`). `trade_set_money` is the copper `SetTradeMoney`
-    /// offered (→ `CMSG_SET_TRADE_GOLD`, decision 0592 P2).
+    /// The open trade and its calls: `InitiateTrade` tokens, the accept, unaccept and cancel flags,
+    /// and `SetTradeMoney` copper (`CMSG_SET_TRADE_GOLD`).
     pub(crate) trade: Option<trade::TradeState>,
     pub(crate) trade_initiates: Vec<String>,
     pub(crate) trade_accept: bool,
     pub(crate) trade_unaccept: bool,
     pub(crate) trade_close: bool,
-    /// `BeginTrade()` / `CancelTrade()` since the last drain (decision 1963).
+    /// `BeginTrade()` and `CancelTrade()` calls.
     pub(crate) trade_begin: bool,
     pub(crate) trade_cancel: bool,
     pub(crate) trade_set_money: Option<u32>,
-    /// Cursor-drop placements onto our trade slots: `(trade_id 1-based, bag, slot)` → the app resolves
-    /// `(bag, slot)` → wire position → `CMSG_SET_TRADE_ITEM`. `trade_clear_items` are the 1-based ids
-    /// an empty-cursor click cleared (→ `CMSG_CLEAR_TRADE_ITEM`). Decision 0592 P2.
+    /// Items dropped on our slots, `(1-based trade slot, bag, slot)`, and the slots clicks cleared.
     pub(crate) trade_set_items: Vec<(u32, i64, u32)>,
     pub(crate) trade_clear_items: Vec<u32>,
 
-    /// The open questgiver panel the app pushes (`None` = no window), the greeting-row selects and
-    /// the button intents it drains — the questgiver seam ([`quest`]).
+    /// The open questgiver panel, its greeting-row selects and its button calls.
     pub(crate) quest: Option<quest::QuestState>,
     pub(crate) quest_selects: Vec<quest::QuestSelect>,
     pub(crate) quest_actions: Vec<quest::QuestAction>,
 
-    /// The death-arc seam ([`death`], decision 0308): the snapshot the app pushes (countdowns +
-    /// offer bits) and the drained release/reclaim/resurrect intents.
+    /// Death countdowns and offers, and the release, reclaim and resurrect calls.
     pub(crate) death: death::DeathUiState,
     pub(crate) death_actions: Vec<death::DeathAction>,
 
-    /// The quest-log seam ([`quest_log`]): the snapshot the app pushes, the engine-owned
-    /// synchronous selection (a 1-based entry index, `0` = none), the click-time abandon mark (a
-    /// QUEST ID, `0` = none — the reference's `0xbb7484`), and the drained abandon intents (quest
-    /// ids).
+    /// The quest log, selection (1-based), abandon mark (a quest id, `0xbb7484`) and abandons.
     pub(crate) quest_log: quest_log::QuestLogState,
     pub(crate) quest_log_selection: u32,
     pub(crate) quest_log_abandon_mark: u32,
     pub(crate) quest_log_abandons: Vec<u32>,
-    /// Quest ids `QuestLogPushQuest()` queued for the app to push to the party (decision 1733).
-    /// **Ids, not entry indices**, like the abandon mark above: the id is resolved at click time,
-    /// so a log shuffle between click and drain cannot retarget it.
+    /// `QuestLogPushQuest()` quest ids, resolved at the click so a log change cannot retarget one.
     pub(crate) quest_log_pushes: Vec<u32>,
-    /// How many times `ConfirmAcceptQuest()` was called — the escort confirm's Yes. A counter, not
-    /// a quest id: the reference's verb takes no argument and answers whatever confirm the client
-    /// is holding, so the id lives app-side with the pending confirm (decision 1733).
+    /// `ConfirmAcceptQuest()` calls, the escort confirm; the app holds the pending quest.
     pub(crate) quest_confirms: u32,
-    /// The shared item-template store: `item id → full tooltip view` ([`item_stats`] module doc,
-    /// decision 0274 P1).
+    /// Item id to its tooltip view.
     pub(crate) item_templates: HashMap<u32, ItemTemplateView>,
-    /// Item ids the renderer asked for that the store lacks — drained by the app
-    /// ([`UiScript::take_item_stat_asks`]), answered via [`UiScript::set_item_template`].
+    /// Item ids asked for and missing, for the app to answer.
     pub(crate) item_stat_asks: HashSet<u32>,
-    /// The item-set store (`set id → SET-block view`, the block `0x854b1c` heads) + its ask-once
-    /// misses — the same push/ask flow as the templates ([`item_stats`] module doc).
+    /// Set id to its tooltip set block (`0x854b1c`), and the misses asked for.
     pub(crate) item_sets: HashMap<u32, super::ItemSetView>,
     pub(crate) item_set_asks: HashSet<u32>,
-    /// The **random-suffix roll** store (`ItemRandomProperties` id → its resolved view) — pushed
-    /// WHOLE at startup, not asked for (decision 1547). It is a static DBC the app has in memory
-    /// from load, and its consumers are click-driven (a chat-link tooltip has no hover re-enter
-    /// loop to repaint on a late answer), so the ask-once shape the template store uses would
-    /// leave a first click showing an item with no lines. This mirrors the reference exactly: the
-    /// builder resolves its `+0x424` against the loaded DBC store `0xc0dbd4` at draw time, and
-    /// every source supplies only the id (the ENCHANT family, `0x52c991`).
+    /// `ItemRandomProperties` id to its view, pushed whole at startup: a clicked tooltip cannot
+    /// repaint on a late answer. The reference reads its loaded store `0xc0dbd4` (`0x52c991`).
     pub(crate) random_properties: HashMap<u32, super::RandomPropertyView>,
-    /// The red-line law's player state (level/class/race/skills — [`item_stats`] module doc).
+    /// The player's level, class, race and skills, for a tooltip's red requirement lines.
     pub(crate) player_req: PlayerReqState,
-    /// The spell-tooltip store: `spell id → resolved view` ([`tooltip_spell`] module doc,
-    /// decision 0274 P2) + the ask-once misses the app drains.
+    /// Spell id to its tooltip view, and the misses asked for.
     pub(crate) spell_tooltips: HashMap<u32, super::SpellTooltipView>,
     pub(crate) spell_tooltip_asks: HashSet<u32>,
-    /// Header collapse/expand intents `(1-based entry index, collapse)` — `CollapseQuestHeader`/
-    /// `ExpandQuestHeader` push, the app drains ([`UiScript::take_quest_log_collapses`]); index 0
-    /// = all headers.
+    /// `CollapseQuestHeader`/`ExpandQuestHeader` as `(1-based entry, collapse)`, entry 0 for all.
     pub(crate) quest_log_collapses: Vec<(u32, bool)>,
-    /// The watched (tracked) quests, by stable quest id in watch order — the tracker HUD's set
-    /// (engine-owned like the selection; pruned by `set_quest_log` when a quest leaves the log).
+    /// Watched quest ids in watch order, pruned when a quest leaves the log.
     pub(crate) quest_log_watched: Vec<u32>,
-    /// The server's wall clock in unix-epoch seconds, pushed by the app each frame it has one
-    /// ([`UiScript::set_server_unix_time`]); `None` before the first `SMSG_QUERY_TIME_RESPONSE`.
-    ///
-    /// Held here rather than folded into the quest-log snapshot because the *engine* owns every
-    /// countdown the Lua reads: a timed quest's deadline is an absolute stamp in this epoch, and
-    /// `GetQuestTimers` subtracts against it **per call**, exactly as the reference's C binding
-    /// does. That is what lets the reference `QuestTimerFrame` tick smoothly from its OnUpdate
-    /// while the log snapshot itself only changes when the log does (decision 1150).
+    /// The server's clock in Unix seconds, `None` before `SMSG_QUERY_TIME_RESPONSE`. A quest
+    /// deadline is a stamp in it, and `GetQuestTimers` subtracts per call, as the reference does.
     pub(crate) server_unix_time: Option<f64>,
-    /// The player's purse in copper (`GetMoney`), pushed each frame it changes by the app's
-    /// `PLAYER_FIELD_COINAGE` feed ([`UiScript::set_money`]). Plain data — the money display + the
-    /// merchant window's coin line read it.
+    /// `GetMoney()` in copper, from `PLAYER_FIELD_COINAGE`.
     pub(crate) money: u64,
 
-    /// The reported connection round trip in ms — `GetNetStats`'s third return, pushed by the app's
-    /// net feed ([`UiScript::set_latency_ms`]). The AVERAGE over the app's RTT ring, not the last
-    /// sample; `0` = nothing measured yet. See [`super::net_stats`].
+    /// `GetNetStats`'s third return, the average round trip in ms; 0 before any sample.
     pub(crate) net_latency_ms: u32,
 
-    /// The player's experience within the current level (`UnitXP("player")`) and the amount required
-    /// to level (`UnitXPMax("player")`), pushed each frame they change by the app's `PLAYER_XP` /
-    /// `PLAYER_NEXT_LEVEL_XP` feed ([`UiScript::set_player_xp`]). A player-level pair (like `money`),
-    /// not a per-unit-token field: PLAYER_XP is a PRIVATE descriptor field, only ever our own avatar's.
+    /// `UnitXP("player")` and `UnitXPMax("player")`, from the private `PLAYER_XP` fields.
     pub(crate) player_xp: u32,
     pub(crate) player_next_level_xp: u32,
 
-    /// The player's banked combo points and the unit they sit on — the raw `PLAYER_FIELD_BYTES`
-    /// byte 1 and `PLAYER_FIELD_COMBO_TARGET` GUID, pushed together each frame either moves
-    /// ([`UiScript::set_combo_points`]). Player-global PRIVATE fields, like `money`.
-    ///
-    /// **Raw wire values, deliberately ungated.** The server banks a point here for a *warrior*
-    /// too (the Overpower window), and the usable walk's leg 5 consumes exactly that. The two
-    /// gates the real `GetComboPoints 0x51a190` applies — rogue-or-druid only, and the banked
-    /// target must be the CURRENT target — live in the binding, where the binary puts them
-    /// (decision 0875). Read [`Self::combo_points`] directly and you are reading the wire, not
-    /// what the reference UI can see.
+    /// Raw combo points (`PLAYER_FIELD_BYTES` byte 1) and target, ungated: a warrior banks them too
+    /// (Overpower); `GetComboPoints` (`0x51a190`) applies the class and current-target gates.
     pub(crate) combo_points: u8,
     pub(crate) combo_target: u64,
 
-    /// The player's rest snapshot, pushed together each frame any part moves
-    /// ([`UiScript::set_rest_state`]) — player-globals like `money`. `rest_state` is the raw
-    /// `PLAYER_BYTES_2` byte 3 (1 = rested, 2 = normal — the server writes it with hysteresis
-    /// off the pool). **Defaults to 2, not 0**: every live 1.12 descriptor carries 2 from
-    /// character creation on, and the tick's faithful FrameXML compares `GetRestState() >= 3`
-    /// unguarded — a pre-feed 0 would render the binary's nil-triple fail path into an event
-    /// handler the real client can only ever run with the byte present. Byte 0 stays reachable
-    /// by explicit push, and the fail path stays faithful there. `rest_pool` is the raw
-    /// `PLAYER_REST_STATE_EXPERIENCE` value in **base kill-XP units**, `resting` the
-    /// `PLAYER_FLAGS_RESTING (0x20)` bit (inside an inn/city). `GetRestState`/`GetXPExhaustion`/
-    /// `IsResting` read these; the pool's display scaling is `exhaustion` row 1's factor,
-    /// applied in the `GetXPExhaustion` binding, where the real client applies it (decisions
-    /// 1082/1087).
+    /// `PLAYER_BYTES_2` byte 3 (1 rested, 2 normal), defaulting to 2 as every 1.12 character has
+    /// it: a 0 has no Exhaustion row, and `GetRestState()`'s nil would raise at the unguarded
+    /// `>= 3` of `MainMenuBar.lua:25`. `rest_pool` is in base kill-XP units, and `resting` is
+    /// `PLAYER_FLAGS_RESTING` (0x20).
     pub(crate) rest_state: u8,
     pub(crate) rest_pool: u32,
     pub(crate) resting: bool,
 
-    /// `PLAYER_FLAGS` bit 12 — **PARTIAL_PLAY_TIME**, what `PartialPlayTime()` answers
-    /// (`0x48eb70`, `shr eax,0xc` / `and al,1`; decision 1746 §"`PLAYER_FLAGS` bit `0x1000` is
-    /// read after all"). The play-time regime a realm with an anti-addiction policy puts an
-    /// account into; on a western realm it never sets.
+    /// `PLAYER_FLAGS` bit 12, `PartialPlayTime()` (`0x48eb70`), an anti-addiction regime's flag.
     pub(crate) partial_play_time: bool,
 
-    /// `PLAYER_FLAGS` bit 13 — what `NoPlayTime()` answers (`0x48ebe0`, the neighbour of the
-    /// above and the harsher half of the same regime).
+    /// `PLAYER_FLAGS` bit 13, `NoPlayTime()` (`0x48ebe0`), the same regime's harsher half.
     pub(crate) no_play_time: bool,
 
-    /// The account's accumulated **rested billing minutes**, from `SMSG_AUTH_RESPONSE` — what
-    /// `GetBillingTimeRested()` returns (decision 1820, binding `0x48ec50`). Minutes is the
-    /// server's convention and the engine converts nothing; stock `PlayerFrame.lua:246` divides by
-    /// 60 for hours. Reached only from inside the two play-time bits above, so with those clear
-    /// nothing in stock FrameXML ever reads it.
+    /// `GetBillingTimeRested()` (`0x48ec50`) in minutes from `SMSG_AUTH_RESPONSE`, unconverted.
     pub(crate) billing_time_rested: u32,
-    /// Is a cinematic playing? What `InCinematic()` reports, pushed by the cinematic plugin.
-    ///
-    /// Read by more than the letterbox: `StaticPopup_Show` refuses any dialog whose entry lacks
-    /// `interruptCinematic` while this is set, exactly as the reference's `StaticPopup.lua:1454`
-    /// does — which is what stops a "your character will be logged out" box from landing on top
-    /// of a first login's race intro.
+    /// `InCinematic()`. While set, `StaticPopup_Show` refuses any dialog without
+    /// `interruptCinematic` (`StaticPopup.lua:1454`).
     pub(crate) in_cinematic: bool,
-    /// Exhaustion.dbc as the rest bindings consume it — rest-state byte → (localized name,
-    /// factor), the table `GetRestState` indexes directly and whose row 1 scales
-    /// `GetXPExhaustion` (`0x48d3f0`; decision 1087). Seeded with the shipped
-    /// 5875 enUS rows so the engine tests and a failed DBC read behave like the shipped client
-    /// (the GlobalStrings-fallback posture); the app overwrites it with the install's real —
-    /// localized — rows at startup ([`UiScript::set_exhaustion_rows`]).
+    /// `Exhaustion.dbc` by rest byte, `(name, factor)`: `GetRestState` indexes it and row 1 scales
+    /// `GetXPExhaustion` (`0x48d3f0`). enUS rows seed it until the app loads the install's own.
     pub(crate) exhaustion: HashMap<u8, (String, f64)>,
 
-    /// The paper doll's combat-stats snapshot (`None` until the app's feed lands), the
-    /// equipment/ammo slot views, and the model pane's persistent bake yaw — the character-window
-    /// seam ([`char_stats`], decision 0208 §3).
+    /// The paper doll's combat stats, `None` until the first push.
     pub(crate) player_combat_stats: Option<char_stats::UnitCombatStats>,
-    /// The **pet's** combat-stats snapshot (decision 1057) — the same shape under the `"pet"`
-    /// token, because the reference's own pet sheet calls the very same `UnitStat`/`UnitResistance`/
-    /// `PaperDollFrame_Set*(unit, prefix)` family with `unit = "pet"` (ref
-    /// `PetPaperDollFrame.lua:73-81`). A second slot rather than a token map: exactly two units
-    /// ever have one, they are fed by two different systems on two different clocks, and every
-    /// binding's route is a fork between them (the [`Self::pet_book`] precedent).
+    /// The pet's combat stats, which the reference's pet sheet reads as `UnitStat("pet", …)`.
     pub(crate) pet_combat_stats: Option<char_stats::UnitCombatStats>,
     pub(crate) inventory_slots: char_stats::InventorySlots,
-    /// The six bank-bag slots (live ids 64..=69) — the third band of
-    /// [`char_stats::Model::inv_slot`], and a store rather than a view because a bank bag has no
-    /// container slot to be read out of: it IS the container. Fed beside
-    /// [`Self::inventory_slots`] off the player descriptor's own guids.
+    /// The six bank-bag slots, ids 64..=69, fed from the player descriptor's guids.
     pub(crate) bank_bag_slots: char_stats::BankBagSlots,
-    /// The 12 alert-region statuses (`GetInventoryAlertStatus`, DurabilityFrame's armor-guy
-    /// feed) in the client's own `0x806eb8` table order (11 equipment regions + the low-ammo
-    /// 12th) — recomputed on every inventory push, which fires `UPDATE_INVENTORY_ALERTS`
-    /// unconditionally, the client's own shape (see [`char_stats`]).
+    /// `GetInventoryAlertStatus` in `0x806eb8` order; every push fires `UPDATE_INVENTORY_ALERTS`.
     pub(crate) inventory_alerts: [u8; 12],
-    /// Inventory-slot ids queued by `UseInventoryItem` (decision 0208 phase 1b, `cursor`'s `doll`
-    /// submodule) — drained by the app into `CMSG_USE_ITEM` against the equipped position.
+    /// `UseInventoryItem` slot ids, sent as `CMSG_USE_ITEM` on the equipped item.
     pub(crate) inventory_uses: Vec<u32>,
-    /// The two weapons' **temporary** enchantments — `[0]` main hand, `[1]` off hand, in the order
-    /// `GetWeaponEnchantInfo` pushes them ([`weapon_enchant`]). A separate slot from
-    /// [`Self::inventory_slots`] on purpose: this one carries a live countdown and is pushed every
-    /// frame, where the slot snapshot is change-gated and fires an event.
+    /// Main- and off-hand temporary enchants in `GetWeaponEnchantInfo`'s order, pushed each frame.
     pub(crate) weapon_enchants: [Option<weapon_enchant::WeaponEnchant>; 2],
 
-    /// The inspected unit's equipment view, keyed by unit token ([`inspect`], decision 0631) —
-    /// the *second* source behind the unit-keyed `GetInventoryItem*` family. Unlike
-    /// [`Self::inventory_slots`] this is PUBLIC descriptor data (`PLAYER_VISIBLE_ITEM_*`), which
-    /// is the whole reason a foreign player's gear can be read at all. `None` = nothing inspected.
+    /// The inspected unit's gear, from its public `PLAYER_VISIBLE_ITEM_*` fields.
     pub(crate) inspect: Option<inspect::InspectView>,
-    /// Unit tokens queued by `NotifyInspect` — drained by the app into `CMSG_INSPECT`.
+    /// `NotifyInspect` unit tokens, sent as `CMSG_INSPECT`.
     pub(crate) inspect_notifies: Vec<String>,
-    /// `ClearInspectPlayer` was called — drained by the app, which drops its inspect target.
+    /// `ClearInspectPlayer` ran; the app drops its inspect target.
     pub(crate) inspect_clear: bool,
-    /// The dressing room's queued intents (decision 1060) — the `DressUpModel` widget's
-    /// `SetUnit`/`Dress`/`Undress`/`TryOn`, drained by the app in order (see [`super::dressup`] on
-    /// why order matters). The pane's yaw is its own `ModelState` facing, like every migrated
-    /// window's (`UiScript::model_pane_facing`, 1751/1969).
+    /// `DressUpModel` `SetUnit`, `Dress`, `Undress` and `TryOn` calls, applied in call order.
     pub(crate) dressup_intents: Vec<super::dressup::DressUpIntent>,
-    /// The tabard designer (1977): each `TabardModel`'s five values, the last seeded/cycled five
-    /// (the app's body preview), the host facts, and the queued intents.
+    /// Tabard designs per `TabardModel`, the app's preview five, the host facts and queued calls.
     pub(crate) tabard_designs: HashMap<crate::widget::FrameHandle, [i32; 5]>,
     pub(crate) tabard_preview: Option<[i32; 5]>,
     pub(crate) tabard_host: super::tabard::TabardHost,
     pub(crate) tabard_intents: Vec<super::tabard::TabardIntent>,
-    /// The WorldFrame type's one-shot registry record (1984): `true` once the first is made.
+    /// The `WorldFrame` type's one-shot record: true once the first is made.
     pub(crate) world_frame_made: bool,
-    /// Unit token (lowercase) → what the app resolved about it this frame, for **every** token
-    /// that named a **live unit object**, creature as readily as player — the input to both
-    /// verified range predicates (`CanInspect`, `CheckInteractDistance`). An absent token is one
-    /// the object manager holds nothing for, and both answer `nil` there (see
-    /// [`UiScript::set_unit_reach`] and [`super::UnitReach`]).
+    /// Per lowercased live-unit token, reach for `CanInspect`/`CheckInteractDistance`; absent: nil.
     pub(crate) unit_reach: HashMap<String, super::UnitReach>,
 
-    /// The skills-pane snapshot the app pushes ([`skills::SkillsState`], decision 0437 phase 4) and
-    /// the synthesized display tree built from it ([`skills::UiScript::set_skills`]) — the skills
-    /// seam ([`skills`]).
+    /// The skills pane's snapshot and the display tree built from it.
     pub(crate) skills: skills::SkillsState,
     pub(crate) skills_groups: Vec<skills::SkillGroup>,
-    /// The categories the player has collapsed (by `category_id`) — survives a content update the
-    /// same way [`Model::trainer_collapsed`] does.
+    /// Collapsed skill categories by id, kept across a re-push.
     pub(crate) skills_collapsed: HashSet<u32>,
-    /// The engine-held selection, by SKILL ID (not visible index — see [`skills`]'s module doc).
+    /// The selection as a skill id, not a row.
     pub(crate) skills_selected: Option<u32>,
-    /// Skill line ids the `AbandonSkill` Lua binding queued since the app's last
-    /// [`UiScript::take_skill_abandons`] drain — the outbound unlearn seam (the app sends each as
-    /// a `CMSG_UNLEARN_SKILL`; the engine mutates NOTHING locally — the real client waits for the
-    /// server's skill-field update, vmangos `SkillHandler.cpp`'s `SetSkill(id, 0, 0)` round trip).
+    /// `AbandonSkill` ids for `CMSG_UNLEARN_SKILL`; nothing changes until the server's update.
     pub(crate) skill_abandons: Vec<u32>,
 
-    /// The reputation-pane snapshot the app pushes ([`reputation::ReputationState`]) and the
-    /// synthesized display tree built from it ([`reputation::UiScript::set_reputation`]) — the
-    /// reputation seam ([`reputation`]).
+    /// The reputation pane's snapshot and the display tree built from it.
     pub(crate) reputation: reputation::ReputationState,
     pub(crate) reputation_groups: Vec<reputation::FactionGroup>,
-    /// The header groups the player has folded, by HEADER KEY (a `Faction.dbc` id, or the
-    /// synthetic `0` "Other" / `-1` "Inactive") — an identity a re-push cannot move, unlike a row
-    /// index. Reset to all-expanded-but-Inactive on every push, exactly as
-    /// [`Model::skills_collapsed`] is: the client's own rebuild does the same.
+    /// Folded headers by key (a `Faction.dbc` id, 0 "Other", -1 "Inactive"), reset on every push
+    /// to all open but Inactive, as the client's rebuild does.
     pub(crate) reputation_collapsed: HashSet<i64>,
-    /// The engine-held selection, by REPUTATION-LIST SLOT (not visible index — see
-    /// [`reputation`]'s module doc).
+    /// The selection as a reputation-list slot, not a row.
     pub(crate) reputation_selected: Option<u32>,
-    /// Reputation verbs the pane's bindings queued since the app's last
-    /// [`UiScript::take_reputation_sends`] drain — the outbound seam. Unlike the skills abandon
-    /// above, the engine DOES mutate locally first: none of the three sends is acked.
+    /// Reputation calls queued, applied locally first because none of the three sends is acked.
     pub(crate) reputation_sends: Vec<reputation::ReputationSend>,
 
-    /// Chat lines the input EditBox submitted (its `OnEnterPressed` → the `SubmitChatInput` Lua
-    /// binding) since the app's last [`UiScript::take_chat_input`] drain — the outbound Lua→app seam
-    /// for the chat input (the twin of `loot_picks`). The app routes each through its slash-command
-    /// parser into a `CMSG_MESSAGECHAT`/`CMSG_TEXT_EMOTE`.
+    /// Lines the chat box submitted (`SubmitChatInput`), for the app's slash-command parser.
     pub(crate) chat_input: Vec<String>,
 
-    /// The world-map seam ([`worldmap`](super::worldmap)): the pushed catalog/feed + the
-    /// engine-owned selection.
+    /// The world map's pushed catalog and feed, and its selection.
     pub(crate) worldmap: super::worldmap::WorldMapState,
-    /// The V-key nameplate pool — engine-owned `Button` widgets under the `WorldFrame`, grown on
-    /// demand and never shrunk, in creation order (decision 2148). Lives here rather than on
-    /// [`super::UiScript`] because it IS model state: the plates are arena frames, and an addon
-    /// walking `WorldFrame:GetChildren()` reaches them like any other.
+    /// Nameplate `Button`s under `WorldFrame`, never shrunk, visible to `GetChildren()`.
     pub(crate) nameplates: super::nameplate::NamePlates,
-    /// The always-up world-state readout's rows ([`worldstate`](super::worldstate)), already
-    /// gated and resolved app-side.
+    /// The world-state readout's rows, gated and resolved by the app.
     pub(crate) worldstate: super::worldstate::WorldStateUiState,
-    /// Events (name + args) queued by Lua bindings (`SetMapZoom` → `WORLD_MAP_UPDATE`;
-    /// `PickupContainerItem`/`ClearCursor`/… → `CURSOR_UPDATE`/`ITEM_LOCK_CHANGED`/
-    /// `DELETE_ITEM_CONFIRM`, decision 0216 §4/§5) to fire at the next
-    /// [`UiScript::tick`](super::UiScript::tick) — a binding executes *inside* Lua, so it can't
-    /// re-enter the handler dispatch synchronously; one tick of deferral is invisible at frame
-    /// rate (the reference fires these synchronously as pure repaint triggers).
+    /// Events bindings raise. Deviation: fired at the next tick, not synchronously as in the
+    /// reference, because a binding runs inside Lua and cannot re-enter handler dispatch.
     pub(crate) pending_events: Vec<(String, Vec<ScriptValue>)>,
-    /// The last cursor position [`UiScript::mouse_move`](super::UiScript::mouse_move)/`mouse_button`
-    /// saw (UI space: logical px, y-up — the same frame `resolve` rects live in). Behind Lua's
-    /// `GetCursorPosition()`; the reference world map polls it every OnUpdate for hover/click math.
+    /// The last cursor position in UI space (logical px, y-up), behind `GetCursorPosition()`.
     pub(crate) cursor_pos: (f32, f32),
 
-    /// A `Minimap:PingLocation(x, y)` call, parked for the app to drain **in the same frame**
-    /// ([`UiScript::take_minimap_ping_request`]): centre-relative offsets in **UI units**
-    /// (x right, y up — `GetCursorPosition`'s own space, which is NOT the window-pixel space
-    /// the app's minimap geometry lives in; the app applies the 0582 seam scale on the way in,
-    /// and getting that wrong is decision 1596's first root cause).
+    /// A `Minimap:PingLocation(x, y)`, drained the same frame: centre-relative offsets in UI units,
+    /// `GetCursorPosition`'s space, not the window pixels of the app's minimap geometry.
     pub(crate) minimap_ping_request: Option<(f32, f32)>,
-    /// The minimap ping's **normalized** offsets from the widget centre (fractions of the widget
-    /// side, x right / y up — the `MINIMAP_PING` event's arg2/arg3 space), republished by the app
-    /// every frame from the stored world point against the player's live position. Behind
-    /// `Minimap:GetPingPosition()`, which answers **two numbers always** — the reference
-    /// recomputes them per call from a pair of statics nothing ever clears (`0x4eefd0`), and the
-    /// stock `Minimap_OnUpdate` multiplies the answer without a
-    /// nil test for the whole of its 5 s timer (1974; 1596's nil answer stood until then). There
-    /// is exactly one ping, so it lives here rather than on each Minimap widget's
-    /// [`KindState`](crate::widget::KindState) — one write, one read, no arena walk.
+    /// The ping's offsets as fractions of the minimap's side, updated by the app every frame.
+    /// `GetPingPosition()` always answers both, from statics never cleared (`0x4eefd0`).
     pub(crate) minimap_ping: (f32, f32),
-    /// The realm this session is on, behind `GetRealmName()` (decision 1195). `""` until the app
-    /// pushes one — the glue screen's own answer, and never `nil`, because the corpus idiom is
-    /// `db[GetRealmName()] = …` at file scope and a nil index errors one call deeper.
-    /// Lines an addon queued with `SendChatMessage`, drained by the app into the wire
-    /// (decision 1199). Deliberately a different queue from the chat box's input: the box's drain
-    /// runs the slash grammar and this one must not.
+    /// `SendChatMessage` lines, apart from chat-box input, whose drain runs the slash grammar.
     pub(crate) chat_sends: Vec<super::chat_send::ChatSend>,
-    /// Broadcasts an addon queued with `SendAddonMessage`, drained by the app into the wire
-    /// (decision 1235). Its own queue rather than [`Self::chat_sends`] because it is a different
-    /// wire: `LANG_ADDON` in the language field, a four-value distribution set, and a payload the
-    /// binding already composed as `prefix` TAB `message`.
+    /// `SendAddonMessage` broadcasts: `LANG_ADDON`, four distributions, `prefix` TAB `message`.
     pub(crate) addon_sends: Vec<super::addon_message::AddonSend>,
-    /// `RequestTimePlayed()` asks queued since the app last drained them — each is one
-    /// `CMSG_PLAYED_TIME`. A COUNT, not a payload, for [`super::pvp`]'s reason: the packet is
-    /// empty, so two asks in a frame are two sends rather than one collapsed intent.
+    /// `RequestTimePlayed()` calls, one empty `CMSG_PLAYED_TIME` each.
     pub(crate) played_time_asks: u32,
-    /// `Screenshot()` calls queued since the app last drained them — each is one capture
-    /// (decision 1487). A COUNT for [`Self::played_time_asks`]'s reason: the request carries no
-    /// payload, so two calls in a frame are two captures.
+    /// `Screenshot()` calls, one capture each.
     pub(crate) screenshot_asks: u32,
+    /// `GetRealmName()`: `""` until pushed, never nil, since addons index tables with it at load.
     pub(crate) realm_name: String,
-    /// **The local player record — `0xc27d80`, ours** (decisions 2261 and 2263).
-    ///
-    /// The bytes, the four verbs that read it and why `UnitLevel` is not among them are on
-    /// [`super::PlayerRecord`] itself; what belongs here is the *lifetime*, because that is what
-    /// this field's position in the `Model` decides.
-    ///
-    /// **Two writers, and the asymmetry between them is the mechanism.** The world-entry UI load
-    /// seeds it from the roster row of the pick in flight — our copy of the same char-enum record
-    /// — beside [`Self::realm_name`] and before the addon walk (1195's slot, 1230's source); and
-    /// [`super::UiScript::set_unit`] keeps it in step for any `"player"` push that **carries** the
-    /// field. A push that does not carry it leaves it standing. So the record can be corrected but
-    /// never blanked, which is the reference's never-cleared property expressed where it can be
-    /// relied on — and decision 2260 is why that matters: a name-cache miss for our own guid
-    /// reached Lua as a nameless player snapshot and took KLHThreatMeter down with it.
-    ///
-    /// Our VM is rebuilt per login (1290) where the reference's record simply persists, so each new
-    /// VM is told once. That is the whole of the difference, and it is unobservable: the four verbs
-    /// do not exist between logins either — they live only in the in-game table `0x850438`, which
-    /// `UI_Init` installs and the teardown nils, and `GlueScript_RegisterBindings 0x46abb0` skips.
+    /// The local player record (`0xc27d80`), seeded at world entry before addons load, then kept by
+    /// `"player"` pushes that carry it: corrected, never blanked. A per-login rebuild is unseen, as
+    /// its verbs exist only in game (`0x850438`), not at the glue screen (`0x46abb0`).
     pub(crate) player_record: super::PlayerRecord,
-    /// The hearthstone bind location's NAME, behind `GetBindLocation()` — the app resolves the
-    /// `SMSG_BINDPOINTUPDATE` area id through the same AreaTable catalog the hearthstone's `$z`
-    /// token already uses, and pushes the resolved string here.
-    ///
-    /// Empty only before that packet has landed — `""`, never nil, matching [`Self::realm_name`]
-    /// beside it: a consumer concatenates this (`Necrosis.lua:1089`), so nil would be a raise.
+    /// `GetBindLocation()`, the bind point's area name: `""` before it lands, never nil.
     pub(crate) bind_location: String,
-    /// `ConfirmBinder()` calls queued since the app last drained them — each is one
-    /// `CMSG_BINDER_ACTIVATE`. A COUNT for [`Self::played_time_asks`]'s reason: the intent carries
-    /// no payload (the app holds the innkeeper's guid), so two calls are two sends.
-    /// The `GMTicketCategory.dbc` rows behind `GetGMTicketCategories()` — `(id, name)` in file
-    /// order, pushed once by the app ([`super::UiScript::set_gm_ticket_categories`]). The ids are
-    /// the wire values, so this is an ordered pair list rather than an indexable table
-    /// (decision 1673).
+    /// `GMTicketCategory.dbc` `(id, name)` rows in file order; the ids are wire values.
     pub(crate) gm_ticket_categories: Vec<(u32, String)>,
-    /// Every ticket verb the window called since the app's last drain, **in call order** — ask,
-    /// status-ask, delete, create, edit, one packet each. ONE queue rather than a counter per verb
-    /// so that `DeleteGMTicket(); GetGMTicket()` in a single chunk reaches the wire in that order;
-    /// per-verb drains cannot express it, and the get would answer with the pre-delete state
-    /// (decision 1673).
+    /// GM ticket calls in call order, so a delete then a get reach the wire in that order.
     pub(crate) gm_ticket_intents: Vec<super::gm_ticket::GmTicketIntent>,
-    /// `Stuck()` calls queued — each is one cast of spell 7355, the Help window's Auto-Unstuck.
+    /// `Stuck()` calls, each a cast of spell 7355, the Help window's Auto-Unstuck.
     pub(crate) stuck_casts: u32,
+    /// `ConfirmBinder()` calls, one `CMSG_BINDER_ACTIVATE` each; the app holds the innkeeper.
     pub(crate) binder_confirms: u32,
-    /// Is an innkeeper's bind question still live and in range — the answer `CheckBinderDist()`
-    /// gives, pushed by the app each frame ([`super::UiScript::set_binder_pending`]). The
-    /// CONFIRM_BINDER dialog polls it from OnUpdate and hides itself when it goes false, which is
-    /// how walking away from the innkeeper takes the question off screen (decision 1331).
+    /// `CheckBinderDist()`: the innkeeper's question is live and in range; false hides its dialog.
     pub(crate) binder_pending: bool,
-    /// The summon question's three resolved reads, pushed by the app each frame
-    /// ([`super::UiScript::set_summon_confirm`]) — what `GetSummonConfirmSummoner`,
-    /// `GetSummonConfirmAreaName` and `GetSummonConfirmTimeLeft` answer ([`super::summon`]).
-    /// Default (two empty strings and a zero) is exactly what the reference's getters answer with
-    /// nothing pending, so the pre-push window behaves like the post-expiry one (decision 1747).
+    /// The summon getters' answers, defaulting to the reference's `""`, `""`, 0 with none pending.
     pub(crate) summon_confirm: super::summon::SummonConfirmUiState,
-    /// `ConfirmSummon()` calls queued since the app's last drain — each is one outbound
-    /// `CMSG_SUMMON_RESPONSE`. A COUNT for [`Self::binder_confirms`]'s reason: the app holds the
-    /// summoner's guid, so the intent carries no payload of its own.
+    /// `ConfirmSummon()` calls, one `CMSG_SUMMON_RESPONSE` each; the app holds the summoner.
     pub(crate) summon_confirms: u32,
-    /// Frames per second, behind `GetFramerate()`. Pushed per tick by the app, which owns the
-    /// clock this crate does not have.
+    /// `GetFramerate()`, pushed each tick.
     pub(crate) framerate: f64,
-    /// The modifier-key mirror `(shift, ctrl, alt)` behind `IsShiftKeyDown`/`IsControlKeyDown`/
-    /// `IsAltKeyDown` — pushed by the app's input pass ([`UiScript::set_modifiers`]) BEFORE the
-    /// frame's mouse events, so a click handler's fork reads the state at click time.
+    /// `(shift, ctrl, alt)` for `Is*KeyDown`, pushed before the frame's mouse events.
     pub(crate) modifiers: (bool, bool, bool),
 }
 
 impl Model {
-    /// The detail pane of the row `SelectQuestLogEntry` currently names — resolved HERE, per call,
-    /// never baked into the pushed snapshot (decision 2247). The reference's detail bindings read
-    /// the selection variable and peek the quest cache inside the same call, so a select-then-read
-    /// pair within one frame answers about the row just selected; the app's push only supplies the
-    /// per-row data those reads land on. `None` for no selection, an out-of-range one, or a header.
+    /// The selected quest-log row's detail, resolved per call as the reference's bindings do.
     pub(crate) fn selected_quest_detail(&self) -> Option<&quest_log::QuestLogDetail> {
         let index = usize::try_from(self.quest_log_selection.checked_sub(1)?).ok()?;
         self.quest_log.entries.get(index)?.detail.as_ref()
@@ -1818,19 +942,7 @@ impl Model {
 }
 
 impl Model {
-    /// A unit token's snapshot, **case-folded the way the client folds it**.
-    ///
-    /// 1.12's resolver `0x515970` compares each of its literals with `SStrCmpI` → `_strnicmp`,
-    /// whose fold is `'A'..'Z' += 0x20` and nothing else: the `jb`/`ja` bounds are unsigned, so a
-    /// byte ≥ 0x80 is never folded. `to_ascii_lowercase` is exactly that rule, and the reason this
-    /// does not use `to_lowercase()` — a locale-aware fold would map bytes the client leaves alone.
-    ///
-    /// The uppercase scan is a fast path, not an optimisation for its own sake: every internal
-    /// caller passes a lowercase literal (`"player"`, `"target"`), so the common case allocates
-    /// nothing and only an addon's `"Player"` pays for a `String`.
-    /// A named font object, **case-folded the way the client folds it** — `SStrCmpI` over the font
-    /// registry's keys. ASCII only, and the uppercase scan is a fast path: every internal caller
-    /// passes an exact shipped name, so only an addon's odd spelling pays for a `String`.
+    /// A named font object, matched case-insensitively (ASCII) as the client's `SStrCmpI` does.
     pub(crate) fn font_object(&self, name: &str) -> Option<&FontObject> {
         if name.bytes().any(|b| b.is_ascii_uppercase()) {
             self.font_objects_by_lower.get(&name.to_ascii_lowercase())
@@ -1839,34 +951,16 @@ impl Model {
         }
     }
 
-    /// Record one script error on **both** channels: the host's `errors` vec (the instruments'
-    /// channel — the harness blocker tables, the app's log drain) and the handler-dispatch queue
-    /// (the player's channel — decision 1305). Every engine-caught script error goes through here;
-    /// a failure raised by the error handler *itself* is pushed to `errors` directly instead,
-    /// which is what keeps the dispatch from recursing.
+    /// Records a caught script error for the host, the retained log and the Lua error handler; an
+    /// error raised by the handler itself goes to `errors` directly, which stops the recursion.
     pub(crate) fn record_script_error(&mut self, msg: String) {
-        // Three channels now, and the third is the one with a memory (decision 1495): the dialog
-        // shows a burst's first message and the host drain empties every frame, so without this
-        // the 1,112 raises after the first exist nowhere a player can reach.
         self.diagnostics
             .record(super::diagnostics::DiagnosticKind::Error, &msg);
         self.pending_error_dispatch.push(msg.clone());
         self.errors.push(msg);
     }
 
-    /// **Record one non-fatal warning — the channel's one door** (decision 2135). Both halves:
-    /// the host's per-frame `warnings` drain (a `warn!` line in the terminal, for whoever is
-    /// running the client), and the retained diagnostic log, which is the only copy a player or an
-    /// instrument can read after the frame that produced it.
-    ///
-    /// Before this there was only the first half, and it was a dead end: `take_warnings` empties
-    /// every frame, so a warning existed for the length of one terminal line and then nowhere at
-    /// all. The messages it carries are the failures that never announce themselves — a dropped
-    /// `inherits=`, an unresolved anchor, an unregistered CVar — which is precisely the class the
-    /// diagnostic log was built for.
-    ///
-    /// Its sibling is [`Self::warn_host_only`], for the one message already retained under a
-    /// truer kind.
+    /// Records a non-fatal warning for the host's terminal and the retained diagnostic log.
     pub(crate) fn record_warning(&mut self, msg: impl Into<String>) {
         let msg = msg.into();
         self.diagnostics
@@ -1874,15 +968,13 @@ impl Model {
         self.warnings.push(msg);
     }
 
-    /// The host channel **alone** — for a message that is already retained under a kind that says
-    /// more than `Warning` does. Exactly one caller: `LoadAddOn`'s failure line, which
-    /// `record_load_failure` has already filed as a [`Load`](super::diagnostics::DiagnosticKind)
-    /// row ("the addon isn't running", which is the fact worth keeping) and which still wants its
-    /// terminal line. Retaining it twice would put the same sentence in the log under two kinds.
+    /// A warning for the host's terminal only, for a message already retained under another kind.
     pub(crate) fn warn_host_only(&mut self, msg: String) {
         self.warnings.push(msg);
     }
 
+    /// A unit token's state, folded as 1.12's resolver `0x515970` folds (`_strnicmp`: `A`..`Z`
+    /// only, never a byte of 0x80 or more), so `to_ascii_lowercase`, never `to_lowercase`.
     pub(crate) fn unit(&self, token: &str) -> Option<&UnitState> {
         if token.bytes().any(|b| b.is_ascii_uppercase()) {
             self.units_by_lower.get(&token.to_ascii_lowercase())
@@ -1959,8 +1051,7 @@ impl Model {
             pending_error_dispatch: Vec::new(),
             diagnostics: Default::default(),
             warnings: Vec::new(),
-            // Classic Era's UIParent virtual space is 1024×768-ish; a sensible default the host can
-            // override with `set_screen_size`. y-up: [bottom, left, top, right].
+            // 1024x768 until the host calls `set_screen_size`; y-up `[bottom, left, top, right]`.
             screen: Rect::new(0.0, 0.0, 768.0, 1024.0),
             units_by_lower: HashMap::new(),
             auras: HashMap::new(),
@@ -1991,8 +1082,7 @@ impl Model {
             petition_requests: Vec::new(),
             tell_requests: Vec::new(),
             open_chat_requests: Vec::new(),
-            // Seeded per window, because the stock `DOCKED` position is not the same for all
-            // seven (`ChatWindowLook::stock`): 1 and 2 are the dock, 3..7 are undocked.
+            // Per window, as the stock dock differs: 1 and 2 are the dock, the rest undocked.
             chat_window_looks: std::array::from_fn(chat_window::ChatWindowLook::stock),
             chat_window_changes: HashSet::new(),
             chat_colors: super::chat_types::seed(),
@@ -2331,9 +1421,7 @@ impl Model {
         self.next_id += 1;
         self.frame_to_id.insert(h, id);
         self.id_to_frame.insert(id, h);
-        // A fresh id means a frame just entered the layout graph (`frame_to_id` is the resolve's
-        // roster) — the mint is the one chokepoint every creation path funnels through (bindings,
-        // the XML loader, anchor-target resolution), so the tier-1 gate can't miss a birth.
+        // Every creation path mints here, so a new frame always opens the layout gate.
         self.touch_layout();
         id
     }
@@ -2347,39 +1435,21 @@ impl Model {
         self.next_id += 1;
         self.region_to_id.insert(h, id);
         self.id_to_region.insert(id, h);
-        // A fresh region id can seat the region in the resolve's external set — same birth
-        // chokepoint as `frame_id`'s.
+        // A new region can join the resolve's external set, so it opens the gate too.
         self.touch_layout();
         id
     }
 
-    /// A write that can move [`UiScript::resolve_layout`]'s read set happened: anchors, sizes,
-    /// measured text, scale, clamp, scroll state, frame/region births, or the screen rect. Every
-    /// mutating BINDING (and app-facing setter) on that set calls this — tier 1 of the resolve
-    /// change gate. The resolve's own pre-pass (`tooltip::layout_tooltips`) deliberately does NOT:
-    /// its writes are derived from state that already arrived through touched paths, and a
-    /// self-touch would pin the gate open forever. A missed site is a silently stale layout —
-    /// exactly the failure `WOW_LAYOUT_VERIFY` (on for every benilla-ui test) exists to catch
-    /// loudly, by proving the fingerprint still matches whenever tier 1 claims quiet.
+    /// A layout write that names no node. The resolve's tooltip pre-pass must not call this, or
+    /// the gate never closes; a missed call is caught by `WOW_LAYOUT_VERIFY`.
     pub(crate) fn touch_layout(&mut self) {
-        // The conservative half of the tier-1 ledger (decision 1388): this write did not name a
-        // node, so the cached graph can no longer be trusted to describe the live model and the
-        // next resolve must derive it in full. Every site that has NOT been migrated to a precise
-        // touch lands here, which is why migration can be incremental and a missed one is slow
-        // rather than wrong.
+        // Naming nothing, the next resolve derives the graph in full: slow, never wrong.
         self.give_up_naming();
         self.bump_layout_epoch();
     }
 
-    /// A write that moved **one region's** layout inputs and changed nothing else about the graph:
-    /// its anchor OFFSETS, its explicit size, its measured extent. Not its anchor targets, not its
-    /// membership, not its liveness — those move edges or the roster, and belong on
-    /// [`Self::touch_layout`].
-    ///
-    /// Falls back to the conservative touch whenever it cannot prove the region is a node of the
-    /// **cached** graph: no minted id, an id past the roster's arrays, or an id the last derive
-    /// left unmapped (an anchor-less region, a region born since). That fallback is what makes the
-    /// call safe to reach for — the worst a mistaken one can do is derive the graph again.
+    /// A write that moved one region's offsets, size or measured extent, not its targets or
+    /// liveness; a region missing from the cached graph falls back to `touch_layout`.
     pub(crate) fn touch_layout_region(&mut self, rh: RegionHandle) {
         match self.region_to_id.get(&rh) {
             Some(&id) => self.touch_layout_node(id),
@@ -2387,8 +1457,7 @@ impl Model {
         }
     }
 
-    /// [`Self::touch_layout_region`]'s frame twin — an anchor offset, a width/height, and nothing
-    /// that moves an edge or the roster.
+    /// The same for a frame: an anchor offset or size, nothing that moves an edge or the roster.
     pub(crate) fn touch_layout_frame(&mut self, h: FrameHandle) {
         match self.frame_to_id.get(&h) {
             Some(&id) => self.touch_layout_node(id),
@@ -2396,37 +1465,9 @@ impl Model {
         }
     }
 
-    /// A **REPARENT** that names its nodes: `SetParent` moved the effective scale of every frame
-    /// in the subtree rooted at `root`, and moved nothing else the layout graph is made of
-    /// (decision 2314, extending 1388).
-    ///
-    /// ## Why a reparent is a value-only write here
-    ///
-    /// `LayoutInput.scale` is the only layout input a reparent touches: the arena recomputes the
-    /// subtree's `effective_scale` and the derive syncs it per frame. Nothing else moves —
-    /// **an anchor's target is an id resolved at `SetPoint` time** ([`super::object::anchor_args::
-    /// resolve_rel_target`]), not a live "my parent" link, so no edge is retargeted; no node is
-    /// born or dies, so the roster is unchanged; and visibility, strata and level are not layout
-    /// inputs at all (the derive walks liveness, not `effective_visible`). A region carries no
-    /// scale of its own — it reads its owner frame's — so naming the frames is enough: the dirty
-    /// closure pulls the regions that read them.
-    ///
-    /// ## Why it is worth naming a whole subtree
-    ///
-    /// `SetParent` used to take [`Self::touch_layout`], on the reading that a reparent is
-    /// human-rate. **It is not.** A pooled widget's recycle is a reparent, and an addon's map-note
-    /// pool recycles hundreds per redraw: with the director's addon set, every quest-log change
-    /// cost two frames of ~160 ms, of which `WOW_LAYOUT_PROF` attributed **128 ms to 58 full
-    /// graph derivations** — 5,267 frames and 16,124 anchored regions walked and hashed, ~3.2 ms
-    /// each, and `WOW_LAYOUT_DERIVE_TRACE` put all fourteen sampled give-ups on this one call.
-    /// A subtree is a handful of nodes; the roster is twenty thousand.
-    ///
-    /// Falls back to the conservative touch the moment a node of the subtree is not a node of the
-    /// cached graph — [`Self::touch_layout_frame`]'s own rule, and the same "worst case is a
-    /// derivation" safety every precise touch has.
+    /// A `SetParent` under `root`: only the subtree's scale moves, as anchor targets are ids fixed
+    /// at `SetPoint`. Addon pools reparent hundreds of frames a redraw, so this stays precise.
     pub(crate) fn touch_layout_reparent(&mut self, root: FrameHandle) {
-        // The walk first, then the writing: `touch_layout_frame` takes `&mut self` and the arena
-        // walk holds `&self`.
         let mut subtree = vec![root];
         let mut at = 0;
         while at < subtree.len() {
@@ -2436,12 +1477,7 @@ impl Model {
                 subtree.extend(f.children.iter().copied());
             }
         }
-        // **The write itself, not only its name.** `LayoutInput.scale` was synced from the arena
-        // inside [`super::UiScript::resolve_layout`]'s DERIVATION — so a pass that skips the
-        // derivation never learned the new scale, and a named-but-unwritten node is the one shape
-        // that ships a stale rect. `WOW_LAYOUT_VERIFY` caught exactly that on the first run of
-        // `setparent::a_reparent_under_a_scale_change_moves_the_childs_rect`; naming is a claim
-        // about what moved, and this is what makes the claim true.
+        // Write the new scale here: only a full derivation syncs it, and a named node skips that.
         let Model {
             arena,
             layout_inputs,
@@ -2457,17 +1493,11 @@ impl Model {
         }
     }
 
-    /// An anchor RETARGET that names its node: the write moved node `h`'s (or `rh`'s) set of
-    /// anchor TARGETS, and hands over both target lists so the cached graph's edges can be
-    /// re-pointed instead of thrown away (decision 1625, extending 1388).
-    ///
-    /// `old`/`new` are the node's FULL anchor-target lists either side of the write. Falls back to
-    /// the conservative touch whenever the scope refuses the patch — the same "worst case is a
-    /// derivation" safety the other precise touches have.
+    /// A write changed frame `h`'s anchor targets; `old` and `new` are its full target lists, so
+    /// the cached edges are re-pointed. Falls back to `touch_layout` when the scope refuses.
     pub(crate) fn touch_layout_retarget_frame(&mut self, h: FrameHandle, old: &[u32], new: &[u32]) {
         match self.frame_to_id.get(&h).copied() {
-            // Already conservative ⇒ the next resolve rebuilds every edge from scratch anyway, so
-            // patching them would be work with no reader.
+            // Already conservative: the next resolve rebuilds every edge, so patching is wasted.
             Some(id)
                 if self.layout_touched.is_some() && self.layout_scope.retarget(id, old, new) =>
             {
@@ -2477,7 +1507,7 @@ impl Model {
         }
     }
 
-    /// [`Self::touch_layout_retarget_frame`]'s region twin.
+    /// `touch_layout_retarget_frame` for a region.
     pub(crate) fn touch_layout_retarget_region(
         &mut self,
         rh: RegionHandle,
@@ -2494,36 +1524,20 @@ impl Model {
         }
     }
 
-    /// A write that could move region `rh`'s measure key — its text, its font face/height/
-    /// outline, its text height, its explicit size (the wrap width) — names the region on the
-    /// measure ledger ([`Self::measure_dirty`]). Push-only and unfiltered: non-FontStrings and
-    /// same-value writes cost one `Vec` push here and one staleness probe at the next sweep,
-    /// which is the price of keeping every enrolled site a one-liner.
+    /// Names `rh` on the measure ledger for a write that may move its measure key.
     pub(crate) fn touch_measure(&mut self, rh: RegionHandle) {
         if let Some(list) = &mut self.measure_dirty {
             list.push(rh);
         }
     }
 
-    /// A write that moves measure keys WITHOUT being able to name the regions — a font-object
-    /// edit fanning out to every inheriting region, a scale change propagating down a subtree,
-    /// [`super::UiScript::invalidate_text_measures`]. The next sweep walks the whole roster,
-    /// exactly as every sweep did before the ledger existed. All human-rate paths.
+    /// A measure-key write that names no region, such as a font object: the next sweep walks all.
     pub(crate) fn touch_measure_all(&mut self) {
         self.measure_dirty = None;
     }
 
-    /// Name a node **without opening tier 1** — for the resolve's own pre-pass
-    /// (`tooltip::layout_tooltips`), which writes layout inputs derived from state that already
-    /// arrived through touched paths.
-    ///
-    /// It deliberately does not call [`Self::touch_layout`]: bumping the epoch from inside a
-    /// resolve would pin the gate open forever (the pre-pass runs on every let-through resolve, so
-    /// it would re-dirty the very resolve it is running in). But the ledger still has to hear about
-    /// it, or an incremental pass would inherit a node whose hash the pre-pass moved and no write
-    /// site named — the one shape that could ship a stale rect. Naming it is free: the hash it
-    /// recomputes is unchanged on the frames the pre-pass writes idempotently, which is nearly all
-    /// of them, so no dirty seed comes of it.
+    /// Names a frame without bumping the epoch, for the resolve's own tooltip pre-pass: a bump
+    /// inside a resolve would hold the gate open for good, yet an unnamed write could go stale.
     pub(crate) fn note_layout_frame_write(&mut self, h: FrameHandle) {
         if self.layout_touched.is_some() {
             match self.frame_to_id.get(&h) {
@@ -2538,7 +1552,7 @@ impl Model {
         }
     }
 
-    /// [`Self::note_layout_frame_write`]'s region twin.
+    /// `note_layout_frame_write` for a region.
     pub(crate) fn note_layout_region_write(&mut self, rh: RegionHandle) {
         if self.layout_touched.is_some() {
             match self.region_to_id.get(&rh) {
@@ -2553,8 +1567,7 @@ impl Model {
         }
     }
 
-    /// Name `id` as the only thing this write moved — if the cached graph has a node for it and no
-    /// earlier write in this frame already gave up on naming.
+    /// Names `id` as what this write moved, if the cached graph has it and naming is still on.
     fn touch_layout_node(&mut self, id: u32) {
         let in_graph = self.layout_scope.has_node(id);
         match &mut self.layout_touched {
@@ -2566,17 +1579,8 @@ impl Model {
         self.bump_layout_epoch();
     }
 
-    /// Give up naming what this write moved: the cached graph can no longer be trusted, so the
-    /// next resolve derives it in full. **Every** site that sets [`Self::layout_touched`] to
-    /// `None` goes through here, because that transition is the only event worth a name.
-    ///
-    /// `WOW_LAYOUT_DERIVE_TRACE=<secs>:<n>` — backtrace the first `n` of them after `secs`. 1388
-    /// left `layout_derivations` as "the counter to watch", and a non-zero reading as the proof
-    /// that "a write site somewhere fell back to the conservative touch" — but gave nobody a way
-    /// to find out WHICH, and `WOW_LAYOUT_TOUCH_TRACE` cannot answer it: it fires on every touch,
-    /// and the precise ones outnumber the poisoning one by hundreds to one. Only the Some → None
-    /// EDGE is printed: once a frame has given up, the fallbacks behind it are consequences, not
-    /// causes, and printing them buries the one line that matters.
+    /// Every write that gives up naming comes through here, so the next resolve derives in full.
+    /// `WOW_LAYOUT_DERIVE_TRACE=<secs>:<n>` backtraces the first `n` of these after `secs`.
     fn give_up_naming(&mut self) {
         if self.layout_touched.is_some() && derive_trace_armed() {
             eprintln!(
@@ -2587,20 +1591,12 @@ impl Model {
         self.layout_touched = None;
     }
 
-    /// Tier 1's counter, shared by every touch above. Bumping it is what re-opens the gate; which
-    /// of [`Self::layout_touched`]'s two states the caller leaves behind is what decides how much
-    /// the re-opened resolve has to derive.
+    /// Bumps tier 1's counter, reopening the gate; `layout_touched` decides how much it derives.
     fn bump_layout_epoch(&mut self) {
         self.layout_epoch = self.layout_epoch.wrapping_add(1);
-        // `WOW_LAYOUT_TOUCH_TRACE=<n>` — name the epoch's per-frame toucher: print a backtrace
-        // for the first n touches (a mechanism probe, meaningful in a debuginfo build). Built
-        // because the SW meters read `resolve≈240 µs, solves=0` on every steady frame: the
-        // tier-1 gate is being defeated by a toucher whose writes never move a fingerprint,
-        // and 48 call sites is too many to tag by hand.
+        // `WOW_LAYOUT_TOUCH_TRACE=<secs>:<n>`: backtraces the first `n` touches after `secs`.
         use std::sync::atomic::{AtomicU32, Ordering};
         use std::sync::OnceLock;
-        // Spec `<secs>:<n>`: arm after `secs` (past UI load + settle, so the trace names the
-        // STEADY toucher, not the thousands of legitimate load-time touches), then print `n`.
         static SPEC: OnceLock<Option<(std::time::Instant, f64, AtomicU32)>> = OnceLock::new();
         let spec = SPEC.get_or_init(|| {
             let v = std::env::var("WOW_LAYOUT_TOUCH_TRACE").ok()?;
@@ -2627,9 +1623,7 @@ impl Model {
     }
 }
 
-/// `WOW_LAYOUT_DERIVE_TRACE=<secs>:<n>`'s latch — arm after `secs` (past UI load, whose thousands
-/// of legitimate births are all conservative by construction and would eat the budget), then allow
-/// `n` prints. Same spec shape as `WOW_LAYOUT_TOUCH_TRACE`, deliberately: one thing to remember.
+/// `WOW_LAYOUT_DERIVE_TRACE=<secs>:<n>`: armed after `secs`, past the UI load, then `n` prints.
 fn derive_trace_armed() -> bool {
     use std::sync::atomic::{AtomicU32, Ordering};
     use std::sync::OnceLock;
diff --git a/crates/benilla-ui/src/script/modelframe.rs b/crates/benilla-ui/src/script/modelframe.rs
index a5b7dc1f..d35c32ab 100644
--- a/crates/benilla-ui/src/script/modelframe.rs
+++ b/crates/benilla-ui/src/script/modelframe.rs
@@ -1,87 +1,21 @@
-//! The model-pane family's method surfaces — `Model` and `PlayerModel`, the 3D panes an addon or a
-//! FrameXML frame parks a model in.
+//! The model-pane widgets' Lua methods, `Model` and `PlayerModel`. The engine holds the scene the
+//! Lua API reads and writes ([`ModelState`]); the app draws it.
 //!
-//! **The same split as [`super::minimap`] and [`super::cooldown`], and for the same reason.** The
-//! engine core holds exactly the scene the Lua API reads and writes ([`ModelState`]); the pixels
-//! are the app renderer's job. That is the posture the `<Minimap>` and cooldown widgets already
-//! run under — a sized hole the game layer draws into.
-//!
-//! ## Two tables, chained — not one table with everything in it
-//!
-//! 1.12 registers **four** model-pane types, and each has its own Lua method table that **never
-//! repeats its base's entries**; a derived pane reaches its base's verbs through the miss leg of
-//! `vtable+0x8` (`__index` meta `0x7020b0`):
+//! Each 1.12 model-pane class has its own method table that never repeats its base's entries; a
+//! derived pane reaches its base's methods on a miss (`__index` meta `0x7020b0`), never the
+//! reverse, so a plain `<Model>` has no `SetUnit`:
 //!
 //! ```text
 //! CSimpleFrame 0x778590
-//! └─ CSimpleModel          0x76f870   table 0x878948 (23)   <Model>          ← built here
-//!    └─ CGCharacterModelBase 0x506260  table 0x84f1fc (3)   <PlayerModel>    ← built here
-//!       ├─ DressUpModelFrame 0x5050d0  table 0x84f190 (3)   <DressUpModel>   ← `dressup` (1969)
-//!       └─ TabardModel       0x503bd0  table 0x84ee40 (10)  <TabardModel>    ← `tabard` (1977)
+//! └─ CSimpleModel          0x76f870   table 0x878948 (23)   <Model>          ← here
+//!    └─ CGCharacterModelBase 0x506260  table 0x84f1fc (3)   <PlayerModel>    ← here
+//!       ├─ DressUpModelFrame 0x5050d0  table 0x84f190 (3)   <DressUpModel>   ← `dressup`
+//!       └─ TabardModel       0x503bd0  table 0x84ee40 (10)  <TabardModel>    ← `tabard`
 //! ```
 //!
-//! Our `__index` dispatcher already walks a *slice* of registry keys per kind, so the chain is
-//! `&[REG_PLAYERMODEL_METHODS, REG_MODEL_METHODS]` and neither table duplicates the other. The
-//! direction is derived → base **only**: a plain `<Model>` does not acquire `SetUnit`.
-//!
-//! `DressUpModel` (`Undress`/`Dress`/`TryOn`) is `super::dressup` (1969) and `TabardModel` (the ten
-//! tabard verbs) `super::tabard` (1977) — each built the day its stock window came onto the chain,
-//! as 1134 §4 said they would be.
-//!
-//! ## Why this surface, in this order
-//!
-//! It is the wall four of the twenty most-installed 1.12 addons hit at once. pfUI's action-bar
-//! module builds the pet bar's autocast shine as
-//!
-//! ```lua
-//! f.autocast = CreateFrame("Model", nil, f)
-//! f.autocast:SetModel("Interface\\Buttons\\UI-AutoCastButton.mdx")
-//! f.autocast:SetSequence(0)
-//! ```
-//!
-//! and its unit frames build portraits as `CreateFrame("PlayerModel", …)` driven by `SetUnit` +
-//! `SetCamera`. pfUI is embedded in pfQuest, pfQuest-turtle and ShaguDPS as well, so one missing
-//! type stopped all four dead, each of them *after* the whole rest of the UI had built.
-//!
-//! ## Ownership is read off the registrar, never off a string scan
-//!
-//! This module published `SetUnit`, `RefreshUnit` and `SetRotation` on `Model` until 2026-08-30,
-//! on the strength of an isolated-string scan of `WoW.exe` finding one occurrence of each. **A
-//! `strings` hit cannot settle ownership** — it answers *whether a name exists*, and `SetUnit`'s
-//! single pooled string `0x84f22c` is referenced by **two** method-table entries in two different
-//! tables (`PlayerModel 0x84f1fc[0]` and `GameTooltip 0x854290`). All three are `PlayerModel`'s.
-//!
-//! Ownership is settled by the enumeration recipe, not a `strings` hit: census `(call|jmp)
-//! 0x701d80`, read the count from the registering `mov edx`, read the pairs at `base + 8*i`, and
-//! settle "which table owns method M" by counting image-wide dword references to M's name VA.
-//!
-//! ## The clock is the engine's; the pixels are the host's (decision 2007)
-//!
-//! A pane's animation state is not "a sequence index the host interprets": the reference widget
-//! owns a private `CM2Scene` whose clock its own `OnUpdate` advances, arms sequences through
-//! `0x7121a0` with an anchor the sampler re-reads, fires `OnUpdateModel` at the top of every
-//! paint (`0x76d1bc`) and `OnAnimFinished` from the completion callback (`0x76cdc0`). All of that
-//! is Lua-observable — the shipped cooldown is nothing but those two handlers scrubbing
-//! `SetSequenceTime` — so it lives here:
-//! [`ModelState::clock_ms`] / [`ModelState::armed`], the tick's model pass, and the bindings
-//! below. What the engine does NOT have is the file: which ids it owns, how long each sequence
-//! runs, whether it loops. Those are the file's **facts** ([`crate::widget::ModelFileFacts`]),
-//! handed over by the host once the asset is resident ([`crate::script::UiScript::set_model_facts`])
-//! — the reference's own "asset ready" edge, on which the loader's Stand seed runs.
-//!
-//! ## What is deliberately NOT here
-//!
-//! Nothing of `Model`'s own 23 — the fog near/far/clear set was the last hold-out and 2027 closed
-//! it (`ClearFog 0x76f540` is `76f5c5 and [edi+0x3a4],-2`, bit 0 and nothing else, so the guess
-//! that kept it out is gone; see the install below).
-//!
-//! Absent, and correctly so: `SetCreature` and `SetCustomRace`. Neither string exists in
-//! 5875 in any form (substring scan of the whole mapped image returns 0, against a positive
-//! control of 27 hits for `Creature`) — they are later-expansion names, and publishing one would
-//! be decision 1189's error.
-//!
-//! And any interpretation of `SetLight`'s numbers — the engine core has no lighting model, so the
-//! tuple is stored verbatim rather than typed into a scene semantics nobody has verified.
+//! The pane's clock is the engine's, since Lua sees it through `OnUpdateModel`, fired at the top of
+//! every paint (`0x76d1bc`), and `OnAnimFinished` (`0x76cdc0`). What only the file knows arrives
+//! from the host once the asset is resident ([`crate::script::UiScript::set_model_facts`]).
 
 use std::sync::Arc;
 
@@ -92,21 +26,17 @@ use super::Model;
 use crate::widget::{model_key, FrameHandle, KindState, ModelFileFacts, ModelLight, ModelState};
 
 impl Model {
-    /// FrameXML units per **layout unit** — `768 · √(a²+1)` for the screen's aspect `a`
-    /// (`G48` [`0x832a48`] = `1/√(a²+1)`, the root scale against the `768`-tall FrameXML
-    /// space). `SetPosition`'s space, and the unit a size-less pane's implicit rect is measured
-    /// in. `4/3` before a screen exists.
+    /// FrameXML units per layout unit, `768 · √(a²+1)` for the screen aspect `a` (`[0x832a48]`
+    /// holds `1/√(a²+1)`): the unit of `SetPosition` and of the implicit rect. `a` is 4/3 before a
+    /// screen exists.
     pub(crate) fn layout_unit(&self) -> f32 {
         let (w, h) = (self.screen.width(), self.screen.height());
         let a = if h > 0.0 && w > 0.0 { w / h } else { 4.0 / 3.0 };
         768.0 * (a * a + 1.0).sqrt()
     }
 
-    /// The **implicit rect** (decision 2015): a model pane that authored no size takes its
-    /// file's bounding-box extent, in layout units, as its size — the reference's geometry
-    /// overrides (`0x76d080`/`0x76d0d0`) answer the bbox whenever no size is authored, and its
-    /// layout consumes them like any size. Written into the layout input when the facts are
-    /// known; a pane with an authored size, or no file, or no facts yet, is left alone.
+    /// The implicit rect: a pane with no authored size takes its file's bounding-box extent, in
+    /// layout units, as the reference's geometry overrides answer it (`0x76d080`, `0x76d0d0`).
     pub(crate) fn apply_implicit_rect(&mut self, h: FrameHandle) {
         let unit = self.layout_unit();
         let extent = {
@@ -144,17 +74,15 @@ impl Model {
         }
     }
 
-    /// A size was AUTHORED on `h` (`SetWidth`/`SetHeight`, the XML `<Size>` through
-    /// them): an implicit rect no longer applies to it, for good — the reference's override
-    /// yields to any authored size.
+    /// A size was authored on `h` (`SetWidth`, `SetHeight`, or XML `<Size>` through them): the
+    /// implicit rect yields to it for good, as the reference's override does.
     pub(crate) fn note_authored_size(&mut self, h: FrameHandle) {
         if let Some(KindState::Model(m)) = self.arena.frame_mut(h).map(|f| &mut f.kind_state) {
             m.implicit_size = false;
         }
     }
 
-    /// The facts the host has handed over for `path`, or `None` — in which case the path is
-    /// queued for the host to load ([`crate::script::UiScript::model_facts_wanted`]), once.
+    /// The host's facts for `path`; on a miss the path is queued, once, for the host to load.
     pub(crate) fn model_facts_for(&mut self, path: &str) -> Option<Arc<ModelFileFacts>> {
         let key = model_key(path);
         match self.model_facts.get(&key) {
@@ -169,8 +97,7 @@ impl Model {
     }
 }
 
-/// The facts of the file `this` pane currently holds (`None` for an empty pane or a file the
-/// host has not loaded yet).
+/// The facts of the file `this` pane holds, if it holds one the host has loaded.
 fn facts_of_pane(lua: &Lua, this: &Table) -> mlua::Result<Option<Arc<ModelFileFacts>>> {
     let path = with_model(lua, this, |m| m.path.clone())?;
     Ok(path.and_then(|p| {
@@ -180,17 +107,15 @@ fn facts_of_pane(lua: &Lua, this: &Table) -> mlua::Result<Option<Arc<ModelFileFa
     }))
 }
 
-/// Registry key of the `Model` method table (the MAXCSTACK discipline: Lua-side root, named key).
+/// Registry key of the `Model` method table (the MAXCSTACK discipline: a Lua-side root).
 pub(super) const REG_MODEL_METHODS: &str = "__benilla_model_methods";
 
-/// Registry key of the `PlayerModel` method table — its **own three** entries only. The other 23
-/// names a `<PlayerModel>` answers come from [`REG_MODEL_METHODS`] through the dispatcher's chain,
-/// exactly as the client's `0x506260` reaches `0x76f870` on a miss.
+/// Registry key of the `PlayerModel` table, its own three methods only: `Model`'s 23 are reached
+/// on a miss, as `0x506260` falls through to `0x76f870`.
 pub(super) const REG_PLAYERMODEL_METHODS: &str = "__benilla_playermodel_methods";
 
-/// Run `f` over a frame's Model state under one short write borrow. Errors if `this` is not a live
-/// Model (unreachable through the kind dispatcher, but the method table is a plain Lua value — a
-/// caller can fish it out and misapply it).
+/// Run `f` on a frame's Model state under one short write borrow. Errors on a receiver that is not
+/// a live Model: a method taken off the table can be called on anything.
 pub(super) fn with_model<T>(
     lua: &Lua,
     this: &Table,
@@ -208,11 +133,8 @@ pub(super) fn with_model<T>(
     }
 }
 
-/// A Lua number-ish → f32, `nil` and non-numbers → 0.0.
-///
-/// The widget's setters are all coordinates and angles, and the corpus passes them through
-/// arithmetic that can produce a nil (`C.bars[...].icon_size / 25` when the config key is absent).
-/// The reference marshals through `lua_tonumber`, which is this.
+/// `lua_tonumber`, which the reference's coordinate and angle setters read through: a number or a
+/// numeric string, anything else 0.0.
 fn num(v: &Value) -> f32 {
     match v {
         Value::Number(n) => *n as f32,
@@ -227,9 +149,8 @@ fn int(v: &Value) -> i32 {
     num(v) as i32
 }
 
-/// `lua_isnumber` — a number, or a string that converts, and **nothing else**. Distinct from
-/// [`num`] on purpose: `SetLight` *raises* on a non-number where the coordinate setters coerce,
-/// so the two questions cannot share one helper.
+/// `lua_isnumber`: a number or a string that converts. Separate from [`num`] because `SetLight`
+/// raises on a non-number where the coordinate setters read 0.
 fn number(v: &Value) -> Option<f32> {
     match v {
         Value::Number(n) => Some(*n as f32),
@@ -239,36 +160,31 @@ fn number(v: &Value) -> Option<f32> {
     }
 }
 
-/// `[0x8029d4]` — the client's "is this float zero" epsilon, shared by `SetLight`'s intensity
-/// gate, `0x71b6a0`'s direction normalise and the paint's degenerate-rect test.
+/// `[0x8029d4]`, the client's float-zero epsilon: `SetLight`'s intensity gate, `0x71b6a0`'s
+/// direction normalise and the paint's degenerate-rect test.
 const FLOAT_EPS: f32 = 2.384_185_8e-7;
 
-/// `Model:SetLight`'s usage string (`0x878c00`), which the binding raises verbatim.
+/// `Model:SetLight`'s usage error. The reference's (`0x878c00`) names the receiver through `%s`
+/// and ends in `)`; this one names `Model` and drops the `)`.
 const SET_LIGHT_USAGE: &str = "Usage: Model:SetLight(enabled[, omni, dirX, dirY, dirZ, \
      ambIntensity[, ambR, ambG, ambB], dirIntensity[, dirR, dirG, dirB]]";
 
 /// What [`parse_set_light`] decided.
 enum SetLight {
-    /// A non-number where the binding requires one — `luaL_error(SET_LIGHT_USAGE)`.
+    /// A non-number where one is required: `luaL_error(SET_LIGHT_USAGE)`.
     Raise,
-    /// **Trap 1.** `enabled == 0` returns at `76e2cb` *before* the local light is copied into the
-    /// widget, so the call writes nothing at all: it neither disables a light nor edits one.
+    /// `enabled == 0` returns (`0x76e2cb`) before the copy, so the call neither disables nor
+    /// edits the light.
     NoOp,
-    /// The light to copy wholesale over the widget's (`76e777 0x76cf30`, `rep movsd 0x1b`).
+    /// The light, copied whole over the widget's (`0x76cf30` at `0x76e777`).
     Set(ModelLight),
 }
 
-/// `Model:SetLight` `0x76e1e0`'s argument walk, over the arguments **after
-/// `self`** — so `a[0]` is the reference's Lua index 2.
-///
-/// The binding builds a **local** `CGLight` from `0x71b4a0` — type 1, every colour ZERO, which is
-/// not the widget ctor's white — fills it, and copies the whole thing over the widget's at the
-/// end. So an omitted colour block lands the *binding's* black, never the ctor's white.
-///
-/// **Trap 2** is the walking cursor: the ambient colour triple is read only when its intensity is
-/// nonzero **and** all three components are numbers; when either fails, the colour stays white
-/// and the cursor does *not* advance past it — so the second intensity is read at index 8 rather
-/// than 11, and `SetLight(1, 0, x, y, z, ambI, dirI)` is a legal seven-argument form.
+/// `Model:SetLight`'s argument walk (`0x76e1e0`) over the arguments after `self` (`a[0]` is Lua
+/// index 2), into a local light whose colours start black (`0x71b4a0`), not the widget's white.
+/// A colour triple is read only when its intensity is nonzero and all three are numbers; otherwise
+/// it is white and the cursor does not advance, so `SetLight(1, 0, x, y, z, ambI, dirI)` reads the
+/// second intensity at index 8, not 11.
 fn parse_set_light(a: &[Value]) -> SetLight {
     let Some(enabled) = a.first().and_then(number) else {
         return SetLight::Raise;
@@ -276,7 +192,7 @@ fn parse_set_light(a: &[Value]) -> SetLight {
     if enabled as i32 == 0 {
         return SetLight::NoOp;
     }
-    // Indices 3..=7 — omni, x, y, z, ambIntensity — are all mandatory once the light is enabled.
+    // Lua indices 3..=7 (omni, x, y, z, ambient intensity) are required once enabled.
     let mut head = [0.0f32; 5];
     for (i, slot) in head.iter_mut().enumerate() {
         match a.get(i + 1).and_then(number) {
@@ -287,15 +203,13 @@ fn parse_set_light(a: &[Value]) -> SetLight {
     let omni = head[0] as i32 != 0;
     let mut vector = [head[1], head[2], head[3]];
     if !omni {
-        // `0x71b6a0` normalises a DIRECTION on write (`71b6c5`-`71b705`); the position setter
-        // `0x71b650` stores raw.
+        // A direction is normalised on write (`0x71b6a0`); a position is stored raw (`0x71b650`).
         let len = (vector[0] * vector[0] + vector[1] * vector[1] + vector[2] * vector[2]).sqrt();
         if len > FLOAT_EPS {
             vector = vector.map(|v| v / len);
         }
     }
-    // The colour blocks: each packed to 8 bits per channel and unpacked again (`0x76f900`), so a
-    // Set→Get round trip is lossy exactly the way `SetFogColor`'s is.
+    // Each colour is packed to 8 bits a channel and back (`0x76f900`), so a round trip is lossy.
     let quantize = |v: f32| ((v.clamp(0.0, 1.0) * 255.0).round()) / 255.0;
     let block = |at: usize| -> Option<[f32; 3]> {
         let c: Vec<f32> = (at..at + 3)
@@ -324,10 +238,8 @@ fn parse_set_light(a: &[Value]) -> SetLight {
     SetLight::Set(light)
 }
 
-/// **Shape A's gate** (decision 1717's taxonomy, for a *string* position): the client's
-/// `lua_isstring` accepts tags 3|4 — a string **or a number** — and nothing else. A number is
-/// rendered to decimal text and used as the path, which is why this coerces rather than matching
-/// `Value::String` alone.
+/// A string argument as `lua_isstring` gates it: a string or a number (tags 3 and 4), the number
+/// rendered as decimal text.
 fn string_arg(v: &Value) -> Option<std::borrow::Cow<'_, str>> {
     match v {
         Value::String(s) => s
@@ -340,8 +252,7 @@ fn string_arg(v: &Value) -> Option<std::borrow::Cow<'_, str>> {
     }
 }
 
-/// The client's own `Usage:` error, with the receiver's name interpolated the way it interpolates
-/// it — `GetName()`, or `<unnamed>` when the widget has none (`0x84c7f0`).
+/// The client's `Usage:` error, naming the receiver by `GetName()` or `<unnamed>` (`0x84c7f0`).
 fn usage(lua: &Lua, this: &Table, call: &str) -> mlua::Error {
     let name = this
         .get::<mlua::Function>("GetName")
@@ -358,39 +269,27 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 
     // ── Content: the model, and clearing ────────────────────────────────────────────────────
     //
-    // `SetModel` and `PlayerModel:SetUnit` are the two ways a pane gets content and they are
-    // alternatives, not layers: setting one clears the other, so `GetModel` after a `SetUnit`
-    // cannot answer a stale path from three frames ago. Only the `SetModel` arm is a `Model` verb —
-    // the unit arm is `PlayerModel`'s (`playermodel_install` below), which is why the paper-doll
-    // and dress-up panes are `<PlayerModel>`s and every corpus `<Model>` drives the path arm.
-    // **`SetModel(nil)` RAISES. It is not a clear** — `ClearModel` is the clear, and it is a
-    // separate entry in the same table. This binding said the opposite until 2026-08-30 ("the
-    // documented clear, and how the corpus writes 'no model'"), which was invented: the byte read
-    // (`0x76d950`, shape A) gates the argument with `lua_isstring` and raises
-    // `Usage: %s:SetModel("file")` on nil, absent, boolean, table, function, userdata and thread.
-    // Measured before changing it — all 5 corpus call sites pass a string literal and our own
-    // FrameXML never calls it — so nothing was relying on the leniency.
+    // `SetModel` and `PlayerModel:SetUnit` are alternative contents: setting one clears the other.
+    // `SetModel` raises `Usage: %s:SetModel("file")` on anything `lua_isstring` refuses, nil
+    // included (`0x76d950`); `ClearModel` is the clear.
     //
-    // **What is NOT reproduced, deliberately:** the reference's *second* raise,
-    // `Invalid model file: %s` (`0x878b44`), for a path that does not resolve — its model load is
-    // synchronous, so it knows. We render no FrameXML models at all, so we cannot evaluate that
-    // condition, and a raise whose predicate we have to guess is worse than a named omission
-    // (1134 §4). A path that would be invalid is simply stored.
+    // Deviation: a path that does not resolve is stored, where the reference raises
+    // `Invalid model file: %s` (`0x878b44`), because the file loads asynchronously here and the
+    // call cannot know yet.
     m.set(
         "SetModel",
         lua.create_function(|lua, (this, path): (Table, Value)| {
             let path = string_arg(&path)
                 .ok_or_else(|| usage(lua, &this, "SetModel(\"file\")"))?
                 .to_string();
-            // The file's facts, if the host has handed them over — the reference's "asset
-            // resident" test (`71d5a3`), which decides whether the loader's Stand seed runs
-            // now or when the file lands ([`ModelState::set_file`]).
+            // The reference's asset-resident test (`0x71d5a3`): the loader's Stand seed runs now,
+            // or when the file lands.
             let facts = lua
                 .app_data_mut::<Model>()
                 .expect("model app_data")
                 .model_facts_for(&path);
             with_model(lua, &this, |m| m.set_file(path, facts.as_deref()))?;
-            // A size-less pane takes the file's rect the moment the file is known (2015).
+            // A size-less pane takes the file's rect as soon as the file is known.
             let h = frame_handle_of(lua, &this)?;
             lua.app_data_mut::<Model>()
                 .expect("model app_data")
@@ -406,14 +305,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "ClearModel",
         lua.create_function(|lua, this: Table| with_model(lua, &this, ModelState::clear_file))?,
     )?;
-    // ── Animation (decision 2007) ───────────────────────────────────────────────────────────
+    // ── Animation ───────────────────────────────────────────────────────────
     //
-    // Both verbs are the same arm, `0x7121a0(model, -1, id, 0, ms, 1.0f, 0, 1)` — `SetSequence`
-    // with `ms = 0` (`0x76dec0` → `0x76cf50`), `SetSequenceTime` with the caller's `ms`
-    // (`0x76dfc0` → `0x76cf80`). The arm interrupts whatever plays, resolves the id through the
-    // file's `animationLookup`, and bakes the anchor `cursor_lo = sceneClock − trunc(ms)` that
-    // the sampler re-reads every frame (`0x71273d`). The id is an `AnimationData` id, not a
-    // file slot; one the file does not own stops the playing track and arms nothing.
+    // Both verbs are one arm, `0x7121a0(model, -1, id, 0, ms, 1.0f, 0, 1)`: `SetSequence` with
+    // `ms = 0` (`0x76dec0` → `0x76cf50`), `SetSequenceTime` with the caller's (`0x76dfc0` →
+    // `0x76cf80`). It anchors the play head at `clock − trunc(ms)`, re-read every frame
+    // (`0x71273d`). The id is an `AnimationData` id, not a file slot.
     m.set(
         "SetSequence",
         lua.create_function(|lua, (this, seq): (Table, Value)| {
@@ -433,9 +330,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 
     // ── The pane's view: yaw, scale, camera, position ───────────────────────────────────────
     //
-    // `SetFacing` is `Model`'s yaw setter (`0x878948[4]` -> `0x76dce0`, writing `+0x39c`).
-    // `SetRotation` writes THE SAME FIELD but is `PlayerModel`'s, not a second name here — see
-    // `playermodel_install`. A `<Model>` that wants its pane turned calls this one.
+    // `SetFacing` (`0x878948[4]` → `0x76dce0`) writes the yaw at `+0x39c`, the field
+    // `PlayerModel:SetRotation` also writes.
     m.set(
         "SetFacing",
         lua.create_function(|lua, (this, rad): (Table, Value)| {
@@ -458,10 +354,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "GetModelScale",
         lua.create_function(|lua, this: Table| with_model(lua, &this, |m| m.scale))?,
     )?;
-    // `SetCamera(n)` = `0x76e0e0` -> `0x76cec0`: select the file's camera by **RAW table index**
-    // (`cameraLookup` is not on this path). With the file's facts in hand the index is resolved
-    // now — an index past the table's count installs the NULL camera, which is the orthographic
-    // leg; without them it is deferred, and the pane draws nothing until it resolves.
+    // `SetCamera(n)` (`0x76e0e0` → `0x76cec0`) picks a camera by raw table index, not through
+    // `cameraLookup`; past the table it installs the NULL (orthographic) camera, and until the
+    // facts arrive the pane draws nothing.
     m.set(
         "SetCamera",
         lua.create_function(|lua, (this, c): (Table, Value)| {
@@ -486,9 +381,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── The scene: light and fog ────────────────────────────────────────────────────────────
-    //
-    // Typed since decision 2027, after the reference: the widget's embedded `CGLight` and the four
-    // fog fields, with `SetLight`'s argument walk (`0x76e1e0`) and both of its traps.
     m.set(
         "SetLight",
         lua.create_function(|lua, args: MultiValue| {
@@ -516,9 +408,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 Value::Number(f64::from(l.vector[1])),
                 Value::Number(f64::from(l.vector[2])),
             ];
-            // Each colour block comes back as `1.0, r, g, b` when ANY component is `> 0`, and as
-            // a lone `0` otherwise (`76e91f`/`76e92f`/`76e93f je 0x76e953` -> `push 1.0`) — which
-            // is what makes the arity 7 | 10 | 13 rather than a fixed 13.
+            // A colour comes back as `1.0, r, g, b` if any component is above 0, else as a lone 0
+            // (`0x76e953`), so the arity is 7, 10 or 13.
             for c in [l.ambient, l.diffuse] {
                 if c.iter().any(|&v| v > 0.0) {
                     out.push(Value::Number(1.0));
@@ -534,16 +425,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "SetFogColor",
         lua.create_function(
             |lua, (this, r, g, b, a): (Table, Value, Value, Value, Option<Value>)| {
-                // FIVE arguments, and the fifth is the alpha — the same numeric path and the same
-                // `[0,1]` clamp as the components, not a flag. It is **guarded with a default of
-                // `1.0`** where r/g/b are read unconditionally and yield `0.0` when absent, so
-                // `SetFogColor(r, g, b)` sets alpha 1.0. Getting that backwards renders the fog
-                // invisible. Decision 1845.
+                // The fifth argument is alpha, clamped like the rest but 1.0 when absent, where an
+                // absent r, g or b reads 0.0: `SetFogColor(r, g, b)` is opaque.
                 let q = |v: f32| (v.clamp(0.0, 1.0) * 255.0).round() as u32;
                 let a = a.as_ref().map_or(1.0, num);
                 let packed = (q(a) << 24) | (q(num(&r)) << 16) | (q(num(&g)) << 8) | q(num(&b));
-                // `76f059 or [edi+0x3a4],1` — setting the colour ARMS the fog. That is the only
-                // arming verb (with the XML `<FogColor>` child); there is no `SetFogEnabled`.
+                // Setting the colour arms the fog (`0x76f059`), the only verb that does.
                 with_model(lua, &this, |m| {
                     m.fog_color = packed;
                     m.fog = true;
@@ -554,17 +441,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     m.set(
         "GetFogColor",
         lua.create_function(|lua, this: Table| {
-            // FOUR values, always — the packed dword unpacked. Never set reads `1, 1, 1, 1`,
-            // because the `CSimpleModel` ctor's terminal write is `0xffffffff` (decision 1845).
+            // Always four values; never set reads `1, 1, 1, 1`, the ctor's `0xffffffff`.
             let packed = with_model(lua, &this, |m| m.fog_color)?;
             let ch = |shift: u32| f64::from((packed >> shift) & 0xff) / 255.0;
             Ok((ch(16), ch(8), ch(0), ch(24)))
         })?,
     )?;
 
-    // `SetFogNear 0x76f1e0` / `SetFogFar 0x76f390` store the number RAW — no clamp, no ordering
-    // check (`76f282`/`76f432 fstp`); the `≥ 0` clamp exists only on the XML attribute path. The
-    // getters read the same fields back. Nothing here arms the fog.
+    // `SetFogNear` (`0x76f1e0`) and `SetFogFar` (`0x76f390`) store raw, with no clamp or order
+    // check (the `≥ 0` clamp is XML-only), and do not arm the fog.
     m.set(
         "SetFogNear",
         lua.create_function(|lua, (this, v): (Table, Value)| {
@@ -587,49 +472,26 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "GetFogFar",
         lua.create_function(|lua, this: Table| with_model(lua, &this, |m| m.fog_far))?,
     )?;
-    // `ClearFog 0x76f540`: `76f5c5 and [edi+0x3a4],-2` — **bit 0 and nothing else**. The colour,
-    // the near and the far all survive, so a later `SetFogColor` re-arms the same ramp. A clear
-    // that also reset them would read as knowledge and be wrong.
+    // `ClearFog` (`0x76f540`) clears the armed bit alone (`0x76f5c5`): colour, near and far stay.
     m.set(
         "ClearFog",
         lua.create_function(|lua, this: Table| with_model(lua, &this, |m| m.fog = false))?,
     )?;
 
-    // ── The two verbs that touch no pane state ──────────────────────────────────────────────
+    // ── AdvanceTime and ReplaceIconTexture ─────────────────────────────────────────────────
 
-    // `AdvanceTime()` — `0x878948[14]` -> `0x76eca0`. **It does nothing, and that is the verified
-    // behaviour, not a stub.** The function takes no Lua argument (no `lua_gettop`, no `tonumber`,
-    // no `tostring` anywhere in `[0x76eca0, 0x76ed65)`), returns no value, and its one reachable
-    // call is `0x76cfb0`, whose entire body is `mov eax,1; ret`. It writes no `CSimpleModel` field
-    // and no global. So there is no clock to advance here and no omission to name: a receiver
-    // check and zero returns IS the reference.
-    //
-    // Present because the shipped chain calls it three times — `Cooldown.lua`, and the glue
-    // character screens' `<OnUpdateModel>` on `<ModelFFX>`, which inherits this very table — and
-    // an addon that hooks one of those will call it too.
+    // `AdvanceTime()` (`0x878948[14]` → `0x76eca0`) does nothing: it reads no argument, returns
+    // nothing, writes no field, and its one call, `0x76cfb0`, is `mov eax,1; ret`.
     m.set(
         "AdvanceTime",
         lua.create_function(|lua, this: Table| with_model(lua, &this, |_| ()))?,
     )?;
 
-    // `ReplaceIconTexture(path)` — `0x878948[15]` -> `0x76ed70`. **A material swap, not a content
-    // setter**: `0x76cfe0(0xe, path)` -> `0x710ec0` replaces the refcounted handle in
-    // `[CM2Model+0xa4][i]` for every M2 texture whose `type == 14`, plus the same-typed slots on
-    // the ribbon (`0x7b7950`) and particle (`0x7b4d20`) emitters. It sets no pane content, clears
-    // no unit, and stores nothing on the `0x3dc`-byte widget — the override lives on the CM2Model
-    // and dies with it when `SetModel`/`ClearModel` releases the instance.
-    //
-    // The reference's two "not ready" cases behave OPPOSITELY: with a `CM2Model` present but its
-    // data not resident the call is queued on `[cm2+0x3c]` and replayed; with **no CM2Model at
-    // all** (`[widget+0x318] == 0`) it is **dropped and never replayed**. Since decision 2007 a
-    // pane with a file has an instance the host renders, so the override is STORED on the pane
-    // (`ModelState::icon`, the queued-and-replayed case — the host applies it whenever the file
-    // is resident) and a pane with no file drops it, as the client does. The stock
-    // `MainMenuBarBagButtons.lua` is the caller: `ItemAnim_OnEvent` puts the pushed item's icon
-    // on `ForcedBackpackItem.mdx`, whose one batch carries no texture of its own.
-    //
-    // The argument gate is shape A: `lua_isstring` (tags 3|4) then `lua_tostring`, raising
-    // `Usage: %s:ReplaceIconTexture("texture")` on anything else.
+    // `ReplaceIconTexture(path)` (`0x878948[15]` → `0x76ed70`): `0x76cfe0(0xe, path)` → `0x710ec0`
+    // retextures every type-14 texture of the model instance and of its ribbon (`0x7b7950`) and
+    // particle (`0x7b4d20`) emitters, so `SetModel` and `ClearModel` drop it with the instance.
+    // With no instance (`[widget+0x318] == 0`) the call is dropped; with one not yet resident it is
+    // replayed on load, so the pane stores the override for the host to apply.
     m.set(
         "ReplaceIconTexture",
         lua.create_function(|lua, (this, path): (Table, Value)| {
@@ -649,14 +511,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     playermodel_install(lua)
 }
 
-/// `PlayerModel`'s **own three** verbs (table `0x84f1fc`) — nothing else. Everything a
-/// `<PlayerModel>` else answers is `Model`'s, reached through the dispatcher's chain.
+/// `PlayerModel`'s own three methods (table `0x84f1fc`); the rest are `Model`'s, reached on a miss.
 fn playermodel_install(lua: &Lua) -> mlua::Result<()> {
     let m = lua.create_table()?;
 
-    // `SetUnit(unit)` — `0x84f1fc[0]` -> `0x505d70`. The pane's other content arm, and `SetModel`'s
-    // alternative: each clears the other, so `GetModel` after a `SetUnit` cannot answer a stale
-    // path. Ours stores the unit TOKEN and resolves it at render.
+    // `SetUnit(unit)` (`0x84f1fc[0]` → `0x505d70`) clears the `SetModel` path; the unit token is
+    // resolved at render.
     m.set(
         "SetUnit",
         lua.create_function(|lua, (this, unit): (Table, Value)| {
@@ -668,41 +528,27 @@ fn playermodel_install(lua: &Lua) -> mlua::Result<()> {
                 m.unit = unit;
                 m.path = None;
             })?;
-            // On the dressing room's pane the same call rebuilds the model from the unit — the
-            // reference's `0x5059a0` duplicates the live model, substitutions and all gone — which
-            // is app state here (`super::dressup`, 1969).
+            // A dress-up pane rebuilds from the unit's live model, dropping try-ons (`0x5059a0`).
             super::dressup::redress_if_dressup(lua, &this)
         })?,
     )?;
 
-    // `RefreshUnit()` — `0x84f1fc[1]` -> `0x505e40`. Re-reads the unit the pane already shows; for
-    // us a no-op with a live receiver check, because the pane holds the TOKEN and resolves it at
-    // render, so there is no cached appearance here to invalidate. Present because the reference's
-    // own `DressUpFrame`/`PaperDollFrame` call it (3 sites) and addons that hook them will too.
+    // `RefreshUnit()` (`0x84f1fc[1]` → `0x505e40`) re-reads the pane's unit; the token already
+    // resolves at render, so only a dress-up pane has work to do.
     m.set(
         "RefreshUnit",
         lua.create_function(|lua, this: Table| {
             with_model(lua, &this, |_| ())?;
-            // the same worker as SetUnit's (`0x505b50`)
+            // The same worker as `SetUnit`'s (`0x505b50`).
             super::dressup::redress_if_dressup(lua, &this)
         })?,
     )?;
 
-    // `SetRotation(rad)` — `0x84f1fc[2]` -> the Lua glue `0x505f00` -> the worker `0x505bb0`, whose
-    // final instruction is `0x505c44 mov [esi+0x39c], eax`: **the same yaw field `SetFacing`
-    // writes**, so the Lua-observable effect of the two verbs is identical and `GetFacing` reads
-    // either back. That equality is the whole reason this can be one line.
-    //
-    // What `0x505bb0` does BESIDES the yaw write is deliberately not modeled, and is worth naming
-    // because it is real: it picks a turn animation from the sign of the change (`0xc`
-    // ShuffleRight when the current facing is **<** the argument, `0xb` ShuffleLeft when **>**,
-    // `0` Stand on equality or NaN), plays it unless that id is already armed on bone slot 0,
-    // and then
-    // UNCONDITIONALLY sets `[+0x3e8] = 1` and `[+0x3ec] = now_ms + 100` — a 100 ms turn hold that
-    // the per-paint `0x505c50` expires. Every one of those is invisible to Lua (no getter reads
-    // them). The app's `<Model>` renderer (`benilla-app` `ui_models`, 2013/2019/2027) draws its
-    // pane off the file's own clock and does not model a turn hold, so storing the pair here
-    // would be state nobody writes and nobody reads. The addresses are the pin if it ever does.
+    // `SetRotation(rad)` (`0x84f1fc[2]` → `0x505f00` → `0x505bb0`) writes the yaw `SetFacing`
+    // writes (`0x505c44`). Not built: the reference also plays a turn animation, ShuffleRight
+    // (`0xc`) when the facing grows, ShuffleLeft (`0xb`) when it shrinks, else Stand (0), unless
+    // already armed on bone slot 0, and holds the turn 100 ms (`[+0x3e8]`, `[+0x3ec]`, expired by
+    // `0x505c50`).
     m.set(
         "SetRotation",
         lua.create_function(|lua, (this, rad): (Table, Value)| {
@@ -715,22 +561,8 @@ fn playermodel_install(lua: &Lua) -> mlua::Result<()> {
 }
 
 impl crate::script::UiScript {
-    /// A named model pane's scene state, or `None` if no live frame carries that name as a
-    /// `Model`/`PlayerModel`.
-    ///
-    /// **The read side of the pane, for a host that draws it.** The app keeps one off-screen body
-    /// bake per window (this module's header: the scene is ours, the pixels are the host's), and
-    /// every frame it has to ask the pane the reference drives which way it is turned. Before
-    /// decision 1751 that came from benilla-named globals a file of ours called
-    /// (`BenillaPaperDollModel_SetFacing` and its four siblings, one scalar per window on
-    /// [`Model`]); the stock FrameXML instead calls
-    /// `Model_OnLoad`/`Model_RotateLeft`/`Model_RotateRight`/`Model_OnUpdate`, which write
-    /// `PlayerModel:SetRotation` — i.e. this state, on the pane itself. So the host reads the pane.
-    ///
-    /// By NAME rather than by handle because that is what the host knows: the character sheet's
-    /// bake belongs to `CharacterModelFrame`, and since 1751 that name is the reference's own. A
-    /// linear scan, because a name index would be a second store to keep true and a loaded
-    /// interface holds single-digit model panes.
+    /// The scene state of the model pane named `name`, for the host that draws it, which knows the
+    /// pane by its stock name (`CharacterModelFrame`).
     pub fn model_pane(&self, name: &str) -> Option<ModelState> {
         self.model_ref()
             .arena
@@ -741,30 +573,22 @@ impl crate::script::UiScript {
             })
     }
 
-    /// A named model pane's yaw in radians — [`Self::model_pane`]'s one hot field, and `0.0` for a
-    /// pane that does not exist yet (its window's file not loaded, or its `OnLoad` not run).
-    ///
-    /// `0.0` rather than an `Option` because every caller is a per-frame booth mirror whose only
-    /// other answer would be "keep the last one", and a pane that has not loaded has no last one.
-    /// The reference's own default, 0.61, is authored in `Model_OnLoad`, so a real pane only reads
-    /// 0.0 before it loads.
+    /// A named pane's yaw in radians, 0.0 before the pane exists; the stock `Model_OnLoad` sets
+    /// 0.61 (`UIParent.lua:1422`).
     pub fn model_pane_facing(&self, name: &str) -> f32 {
         self.model_pane(name).map_or(0.0, |m| m.facing)
     }
 
-    /// The host hands over what it knows about a model **file** (decision 2007): its sequences
-    /// and bounds, read off the loaded asset. Every pane holding that file then runs the
-    /// reference's residency completion — the loader's Stand seed for a pane that was waiting,
-    /// the ownership check for an arm that was queued ([`ModelState::seed_from_facts`]) — and
-    /// its clock starts answering ([`ModelState::play_head`]).
+    /// The host's facts for a model file, read off the loaded asset: every pane holding it runs the
+    /// reference's load completion ([`ModelState::seed_from_facts`]) and takes its implicit rect.
     pub fn set_model_facts(&mut self, path: &str, facts: ModelFileFacts) {
         let key = model_key(path);
         let facts = Arc::new(facts);
         let mut model = self.model_mut();
         model.model_facts.insert(key.clone(), facts.clone());
         model.model_facts_wanted.retain(|k| *k != key);
-        // A one-off walk per file, not per frame: the panes that named this file are the
-        // waiters the reference links on the streaming drain (`0x71d640`).
+        // The panes holding this file: the waiters the reference links on its streaming drain
+        // (`0x71d640`).
         let handles: Vec<_> = model
             .arena
             .iter_frames()
@@ -783,8 +607,7 @@ impl crate::script::UiScript {
         }
     }
 
-    /// The screen's aspect moved: every implicit rect is measured in layout units, which scale
-    /// with `√(a²+1)`, so each one is re-derived (decision 2015). An authored size is untouched.
+    /// The screen aspect changed: re-derive every implicit rect, whose unit scales with `√(a²+1)`.
     pub(crate) fn reapply_implicit_rects(&mut self) {
         let mut model = self.model_mut();
         let panes: Vec<FrameHandle> = model
@@ -803,23 +626,19 @@ impl crate::script::UiScript {
         }
     }
 
-    /// The model files panes have named that no facts have arrived for — drained: the host
-    /// loads each once and answers through [`Self::set_model_facts`]. Keys are
-    /// [`crate::widget::model_key`]s (case-folded, `/`-separated, no extension).
+    /// Drain the model files panes named with no facts yet, as [`crate::widget::model_key`]s; the
+    /// host loads each once and answers through [`Self::set_model_facts`].
     pub fn model_facts_wanted(&mut self) -> Vec<String> {
         std::mem::take(&mut self.model_mut().model_facts_wanted)
     }
 
-    /// Does the engine hold facts for `path`'s file — the host's "already answered" test.
+    /// Whether the engine holds facts for `path`'s file.
     pub fn has_model_facts(&self, path: &str) -> bool {
         self.model_ref().model_facts.contains_key(&model_key(path))
     }
 
-    /// **The paint list**: every effectively-visible model pane holding a file whose facts the
-    /// engine has — with its scene clock and, when something is armed, its play head. The host's
-    /// renderer reads this once per frame (decision 2008) instead of the extract carrying a
-    /// cursor that moves every tick (`QuadContent::ModelPane`'s doc says why). Handle order —
-    /// the arena's registry order, stable across frames.
+    /// The paint list: every visible model pane whose file's facts are known, with its clock and
+    /// play head, in the arena's registry order, which is stable across frames.
     pub fn visible_model_panes(&self) -> Vec<ModelPaneFrame> {
         let model = self.model_ref();
         model
@@ -836,10 +655,8 @@ impl crate::script::UiScript {
                 };
                 let path = m.path.as_deref()?;
                 let facts = model.model_facts.get(&model_key(path))?;
-                // The reference's draw gate (`76d5f0 cmp [this+0x320],-1 ; jne`): a pane whose
-                // camera question is still open paints NOTHING — not the model, not its
-                // `OnUpdateModel`. Reachable from Lua by `SetCamera(n)` on a pane whose file has
-                // not landed yet (decision 2027).
+                // A pane whose camera is still pending paints nothing, not even its
+                // `OnUpdateModel` (`0x76d5f0`).
                 if m.camera_pending.is_some() {
                     return None;
                 }
@@ -853,15 +670,12 @@ impl crate::script::UiScript {
     }
 }
 
-/// One visible model pane as the host's renderer sees it this frame —
-/// [`UiScript::visible_model_panes`]'s row.
+/// One row of [`UiScript::visible_model_panes`].
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct ModelPaneFrame {
     pub handle: crate::widget::FrameHandle,
-    /// The pane's private scene clock, ms ([`ModelState::clock_ms`]) — the global-sequence
-    /// clock of everything the pane draws.
+    /// The pane's scene clock in ms, which also drives the file's global sequences.
     pub clock_ms: u64,
-    /// Where the armed sequence stands, or `None` while nothing is armed (the file draws at its
-    /// rest pose).
+    /// The armed sequence's play head; `None` draws the rest pose.
     pub play: Option<crate::widget::ModelPlayHead>,
 }
diff --git a/crates/benilla-ui/src/script/nameplate.rs b/crates/benilla-ui/src/script/nameplate.rs
index 3aa561e3..de8eb154 100644
--- a/crates/benilla-ui/src/script/nameplate.rs
+++ b/crates/benilla-ui/src/script/nameplate.rs
@@ -1,71 +1,9 @@
-//! **The nameplate widgets** — `CGNamePlateFrame` as the frame-system object it actually is
-//! (decision 2148).
-//!
-//! benilla drew V-plates for a year as quads pushed straight into the UI pass, which made them
-//! invisible to Lua: a live run's `WorldFrame:GetChildren()` returned the two named FrameXML
-//! frames and nothing else, and every 1.12 nameplate addon — all of which find plates by walking
-//! exactly that list — found nothing to work with. The reference does the opposite, and this
-//! module is that difference closed.
-//!
-//! ## What the reference builds, byte for byte
-//!
-//! The plate is a `CSimpleButton` subclass (ctor `0x7cb250`, `…\Ui\NamePlateFrame.cpp`, vtable
-//! `0x81de50`, size `0x518`) whose **base constructor parents it to the `CGWorldFrame` singleton**
-//! `ds:0xb4b2bc` (`0x7786a3` → `0x769318` → `SetParent 0x76ab10`, tail-appending at `0x76abdb`) —
-//! so it is a real member of `[worldframe+0x300]`, returned by `GetChildren` and counted by
-//! `GetNumChildren`, inheriting strata **0 (WORLD)** and taking level **1**.
-//!
-//! - **Identity:** `GetObjectType()` = `"Button"`, `IsObjectType` accepts Button/Frame/Region, and
-//!   `GetName()` is **nil** — `[this+0x98]` is zeroed at `0x76c50b` and only XML `name=` ever
-//!   writes it. Anonymity is load-bearing: `_Nameplates` and pfUI both reject a *named*
-//!   `WorldFrame` child.
-//! - **Six regions, in creation order**: Border `0x7cb2c2`, Glow `0x7cb361`, Name `0x7cb3d7`,
-//!   Level `0x7cb479`, Skull `0x7cb512`, RaidIcon `0x7cb5b4`.
-//! - **One child**, the health bar (`GetObjectType()` = `"StatusBar"`), whose own single region is
-//!   the BarFill texture `GetStatusBarTexture()` returns. **No cast bar exists in 1.12** — a second
-//!   child would be blanked by pfUI, which destructures `healthbar, castbar`.
-//! - **Real anchors.** The ctor writes them through `0x767c70` — the *same* primitive and the same
-//!   `[layoutObj + 4 + 4·point]` storage the Lua `SetPoint` binding ends in — so `GetPoint`,
-//!   `GetLeft` and `GetWidth` answer truthfully. Name = `("BOTTOM", plate, "CENTER", 0, 0)`
-//!   (`0x7cb456`), Level = `("CENTER", plate, "BOTTOMRIGHT", …)` (`0x7cb7f5`); `_Nameplates`
-//!   *validates* both pairs and rejects a plate that fails them.
-//! - **Levels, and this is the surprise:** the bar is put **below** the plate, not above it —
-//!   `0x7cb32e mov edx,[plate+0xc4]` (=1) · `0x7cb33c dec edx` · `0x7cb33e call 0x76a4f0(bar,0,0)`,
-//!   an absolute level that overrides what `SetParent` had just given it. Plate level 1, **bar
-//!   level 0**. Since the draw walk's layer loop is *outer* and its frame walk *inner* (`0x765920`:
-//!   layer counter `0x76593c`, frame walk `0x7659d0`–`0x7659f8`, `cmp eax,5` at `0x765a63`), the
-//!   whole bar frame drains before any plate layer — which is why the border's bevels cap the
-//!   fill's ends.
-//! - **Layers** (`GetDrawLayer 0x79a6c0`, table `0x811a80`): Border ARTWORK, Glow **HIGHLIGHT**,
-//!   Name/Level/Skull OVERLAY (the ctor re-layers Name and Level off ARTWORK at `0x7cb438`/
-//!   `0x7cb4ea`), RaidIcon ARTWORK, BarFill ARTWORK on the bar. **No sub-level exists in 5875**;
-//!   within a layer it is creation order.
-//! - **Scripts:** the engine installs none, and every C++ override tails into the base
-//!   unconditionally, so an addon's `SetScript` on OnShow/OnHide/OnUpdate/OnEnter/OnLeave/
-//!   OnMouseDown/OnMouseUp/OnClick fires. `RegisterForClicks(0x500)` = Left/Right on mouse-**up**.
-//! - **Pooling:** destroy (`0x608a10`) never unparents — it hides and pushes onto a free list, and
-//!   reuse re-runs neither the ctor nor `SetParent`. So **the child-list index is stable for the
-//!   session**, and a retired plate is still returned *and counted* (the list walk has no
-//!   visibility filter). Every corpus addon's `registry[plate]` identity map rests on that.
-//!
-//! ## The consumer contract this has to keep
-//!
-//! Four independent 1.12 addons (`_Nameplates`, `CustomNameplates`, pfUI's vanilla branch,
-//! ShaguTweaks' vanilla branch — all `## Interface: 11200`) destructure the two tuples
-//! *positionally* and identify a plate by `regions[1]:GetTexture()` being exactly
-//! `Interface\Tooltips\Nameplate-Border`. The byte-derived order and the corpus's agree element for
-//! element — an independent empirical control on a byte derivation. So the composition is not ours
-//! to choose; it is an ABI, and the tests transcribe each addon's own walk.
-//!
-//! **An addon takes the plate over**, which is the half a painter never had to respect: pfUI blanks
-//! all six regions and paints its own, sets `SetAlpha(.95)` on non-targets itself, and ShaguTweaks
-//! reparents the raid icon. So [`Plate::create`] writes the static properties (paths, fonts,
-//! layers) exactly **once**, [`Plate::lay_out`] rewrites the window-derived anchors only when the
-//! window moves, and [`Plate::drive`] writes only what actually changed this frame. The one
-//! deliberate exception is the plate's own anchor, which the reference itself re-issues every dirty
-//! frame from the seat `0x509ec0` (`ClearAllPoints` + `SetPoint`), wiping an addon anchor *on the
-//! plate* there too — which is why every corpus addon anchors its overlay **to** the plate and
-//! re-anchors the **bar**, never the plate.
+//! The nameplate widgets: the reference's `CGNamePlateFrame` (ctor `0x7cb250`), an anonymous
+//! `Button` parented to the `WorldFrame` (`0x7786a3`) at strata WORLD, level 1. Plate addons
+//! (`_Nameplates`, `CustomNameplates`, pfUI, ShaguTweaks) find it in `WorldFrame:GetChildren()`
+//! and read it positionally: six regions in creation order, then one child, the health bar (1.12
+//! has no cast bar). Addons take plates over, so static properties are written once, anchors
+//! when the window changes and state when it moves.
 
 use crate::layout::{Anchor, Point};
 use crate::order::DrawLayer;
@@ -75,34 +13,29 @@ use super::model::Model;
 use super::UiScript;
 use super::{BlendMode, FontShadow, JustifyV, RegionData, TexCoords};
 
-/// Region 1's art — and the identification test every corpus addon runs, which is why it is a
-/// constant here rather than a caller's argument.
+/// Region 1's art, and the path plate addons identify a plate by.
 pub const BORDER_TEXTURE: &str = "Interface\\Tooltips\\Nameplate-Border";
-/// Region 2's. `glow:IsShown()` is how pfUI reads *mouseover* (`nameplates.lua:601`).
+/// Region 2's art; pfUI reads mouseover from `glow:IsShown()` (`nameplates.lua:601`).
 pub const GLOW_TEXTURE: &str = "Interface\\Tooltips\\Nameplate-Glow";
-/// Region 5's — the boss / out-of-range skull (`levelicon` to pfUI, `Boss` to CustomNameplates).
+/// Region 5's art, the boss and out-of-range skull.
 pub const SKULL_TEXTURE: &str = "Interface\\TargetingFrame\\UI-TargetingFrame-Skull";
-/// Region 6's 4-column atlas.
+/// Region 6's art, a 4-column atlas.
 pub const RAID_ICON_TEXTURE: &str = "Interface\\TargetingFrame\\UI-RaidTargetingIcons";
-/// The health bar's fill — what `healthbar:GetStatusBarTexture()` hands back.
+/// The health bar's fill, which `GetStatusBarTexture()` returns.
 pub const BAR_FILL_TEXTURE: &str = "Interface\\TargetingFrame\\UI-TargetingFrame-BarFill";
-/// `NAMEPLATE_FONT` — Friz Quadrata, the plate's own face.
+/// `NAMEPLATE_FONT`: Friz Quadrata.
 pub const PLATE_FONT: &str = "Fonts\\FRIZQT__.TTF";
 
-/// The plate's frame level, and the bar's — `plate.level − 1`, absolute and clamped ≥ 0
-/// (`0x7cb32e`/`0x7cb33c`/`0x7cb33e` → `0x76a4f0`). The pair is what puts the border over the fill.
+/// The plate's level; the bar's is one less, set absolutely (`0x7cb33e` → `0x76a4f0`). The draw
+/// walks levels outermost and each level's layers inside (`0x765920`), so the whole bar draws
+/// before the border that caps it.
 const PLATE_LEVEL: u16 = 1;
 const BAR_LEVEL: u16 = 0;
 
-/// Everything about a plate's geometry that follows from the *window* rather than from the unit,
-/// in FrameXML units (the driver has already divided out the seam scale).
-///
-/// Applied to every pooled plate at once, and only when it changes — these are exactly the writes
-/// that must not happen per frame, because an addon that re-anchors the bar would otherwise have
-/// its anchor stamped over at 60 Hz.
+/// The plate geometry that follows from the window rather than the unit, in FrameXML units with
+/// the seam scale divided out. Written only when it changes, so an addon's bar anchor survives.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct PlateGeometry {
-    /// The plate frame's own size.
     pub width: f32,
     pub height: f32,
     /// The health bar, from the plate's BOTTOMLEFT.
@@ -110,74 +43,47 @@ pub struct PlateGeometry {
     pub bar_off_y: f32,
     pub bar_width: f32,
     pub bar_height: f32,
-    /// The level text / skull seat, from the plate's BOTTOMRIGHT (x is subtracted, y added).
+    /// The level text and skull seat, from the plate's BOTTOMRIGHT (x is subtracted, y added).
     pub level_off_x: f32,
     pub level_off_y: f32,
-    /// The skull's square side.
     pub skull_size: f32,
-    /// The raid icon's square side; it hangs off the plate's LEFT edge, vertically centred.
     pub raid_size: f32,
-    /// Font heights for the name and the level.
     pub name_height: f32,
     pub level_height: f32,
-    /// The plate text's drop-shadow step, in the same FrameXML units — **the driver divides the
-    /// seam out of it like everything else here**, because the director tuned it as a constant
-    /// ONE LOGICAL PIXEL (2026-07-07) and the shared text arm multiplies whatever it finds by the
-    /// seam on the way out.
-    ///
-    /// Left as a bare `1.0` unit by the widget port, it became `round(windowH/768 × uiScale)`
-    /// drawn px — 2 px from a 1152-tall window up, 3 px at 2160 — which is exactly the "chunky"
-    /// the recorded ±0.001 gx law was tuned away from, and it made the shadow the one part of a
-    /// plate that was not uiScale-blind.
+    /// The text's drop-shadow step, seam divided out like the rest: one logical pixel at any
+    /// window size, since the text path multiplies it by the seam.
     pub shadow_offset: f32,
 }
 
-/// One plate's per-frame state, as the app hands it over: everything that can move while a plate is
-/// alive. Anything that cannot is written once, at creation.
+/// One plate's per-frame state: everything that can move while the plate is alive.
 #[derive(Clone, Debug, PartialEq)]
 pub struct PlateState {
-    /// The unit this plate belongs to — its GUID, and **the plate's identity**.
-    ///
-    /// The reference binds a plate to its unit for as long as the plate lives (`[unit+0xe60]`
-    /// holds the pointer; the free list hands out a plate at create and takes it back at destroy),
-    /// and every corpus addon depends on that: pfUI caches the name, level, colour and its own
-    /// overlay ON the frame (`registry[plate]`, `nameplate.original.*`) and only refreshes what
-    /// its `OnDataChanged` says moved. Handing widget *i* to whichever unit happens to sort i-th
-    /// this frame would make every plate's cached state wrong on the frame two units swap places —
-    /// which is why the pool is keyed by this rather than indexed by the driver's sort order.
+    /// The unit's GUID and the plate's identity: a plate is bound to its unit for its life
+    /// (`[unit+0xe60]`), and addons cache per-plate state on the frame.
     pub key: u64,
-    /// Where the plate's **TOP-CENTRE** lands, in FrameXML units from the screen's bottom-left —
-    /// the reference's own seat (`0x509ec0`: the plate hangs below the point).
+    /// Where the plate's top centre lands, in FrameXML units from the screen's bottom-left; the
+    /// plate hangs below it (`0x509ec0`).
     pub top_centre: (f32, f32),
-    /// `UNIT_FIELD_HEALTH` and `UNIT_FIELD_MAXHEALTH`, **raw**: `healthbar:GetValue()` is
-    /// `[bar+0x320]` (`0x78f5d0`), not a fraction, and `GetMinMaxValues()` answers `(0, max)`.
-    /// pfUI and CustomNameplates both divide, so a fraction here would read as 1 hp out of 1.
+    /// `UNIT_FIELD_HEALTH` and `UNIT_FIELD_MAXHEALTH`, raw: `GetValue()` is the health, not a
+    /// fraction (`0x78f5d0`), and `GetMinMaxValues()` is `(0, max)`; plate addons divide.
     pub health: f32,
     pub max_health: f32,
-    /// The bar's reaction colour — the four confirmed dwords. Addons reverse-engineer the unit's
-    /// faction from `GetStatusBarColor`, so these have to be exact.
+    /// The bar's reaction colour, exact: addons read the unit's reaction from `GetStatusBarColor`.
     pub bar_colour: [f32; 3],
-    /// The unit's name.
     pub name: String,
-    /// The level number to show, or `None` when the unit has no `UNIT_FIELD_LEVEL` yet.
-    ///
-    /// **`None` is not the skull** — that is [`Self::skull`], and conflating them is what made a
-    /// unit whose level had not arrived wear a world boss's skull. The old painter kept the whole
-    /// level/skull block inside `if let Some(level)`, so no level meant neither.
+    /// The level to show, or `None` before `UNIT_FIELD_LEVEL` arrives: an empty seat, not a skull.
     pub level: Option<u32>,
-    /// Show the SKULL in the level's seat instead of a number — the boss / far-out-of-range mark.
+    /// Show the skull in the level's seat instead of a number.
     pub skull: bool,
-    /// The level text's con colour.
     pub level_colour: [f32; 3],
-    /// The raid-target mark, 0-based (`col = idx & 3`, `row = idx >> 2`), or `None`.
+    /// The raid-target mark, 0-based, or `None`.
     pub raid_icon: Option<u8>,
-    /// The plate's own alpha: **exactly 1.0 for the target**, dimmed otherwise. `GetAlpha() == 1`
-    /// is how pfUI and CustomNameplates detect the target plate — a contract, not a look.
+    /// The plate's alpha: exactly 1.0 for the target, dimmed otherwise. Addons find the target
+    /// plate by `GetAlpha() == 1`.
     pub alpha: f32,
-    /// Mouseover ∪ target: the bar's brighten.
+    /// Mouseover or target: the bar brightens.
     pub lit: bool,
-    /// The plate rect is hovered right now — the name goes yellow (`0x7cb850` OnEnter, name-only)
-    /// and the glow region is shown, which is the mouseover signal addons read.
+    /// The pointer is on the plate: the name goes yellow (`0x7cb850`) and the glow region shows.
     pub hovered: bool,
 }
 
@@ -193,85 +99,55 @@ struct Plate {
     raid: RegionHandle,
     bar: FrameHandle,
     fill: RegionHandle,
-    /// Last frame's state, so [`Plate::drive`] writes only what moved. `None` = retired.
+    /// Last frame's state, so [`Plate::drive`] writes only what moved; `None` while retired.
     last: Option<PlateState>,
-    /// **The geometry this plate's anchors were written under**, or `None` while it has never been
-    /// laid out — the fix for a plate that was born invisible.
-    ///
-    /// [`Plate::lay_out`] used to be driven by one per-frame `relayout` flag ("did the window
-    /// move?"), which is true exactly once per window size. A plate the pool grew on any LATER
-    /// frame — a unit walking into range with no free slot — therefore kept `width: 0`, `height: 0`
-    /// and no region anchors, resolved to nothing, and drew nothing for the rest of the session.
-    /// The number of plates on screen was capped at however many were up on the frame V was first
-    /// pressed. Per-plate state instead of a per-frame flag makes the condition unfalsifiable: a
-    /// plate whose anchors are not the current geometry's gets them, whatever the reason.
+    /// The geometry its anchors were written under, `None` before the first lay-out. Kept per
+    /// plate, so a plate the pool grows later is laid out too.
     laid_out: Option<PlateGeometry>,
 }
 
 impl Plate {
-    /// The unit this plate is currently bound to, or `None` while it sits in the pool.
     fn key(&self) -> Option<u64> {
         self.last.as_ref().map(|s| s.key)
     }
 }
 
-/// The plate pool — grown on demand, **never shrunk**, in creation order.
-///
-/// The reference's pool is unbounded and its free list FIFO; what matters to an addon is only that
-/// an index, once handed out, keeps meaning the same Lua object, and that a retired plate stays in
-/// the child list (hidden). pfUI and ShaguTweaks scan `initialized + 1 .. GetNumChildren()` and
-/// never reset `initialized`, so a client that reordered or compacted this list would make them
-/// miss every plate created afterwards — permanently, and silently.
+/// The plate pool, grown on demand and never shrunk or reordered: addons scan only the children
+/// past the count they last saw, so a compacted list would hide every later plate from them.
 #[derive(Debug, Default)]
 pub(crate) struct NamePlates {
     plates: Vec<Plate>,
-    /// Which pool slot each live unit holds, by [`PlateState::key`] — the reference's
-    /// `[unit+0xe60]`, from this side. A slot leaves this map only when its unit's plate is
-    /// retired, and the slot itself never moves.
+    /// Each live unit's pool slot, by [`PlateState::key`]: the reference's `[unit+0xe60]`.
     assigned: std::collections::HashMap<u64, usize>,
-    /// The reverse of the arena's own structure: which slot a frame handle is. Filled at
-    /// creation and never removed (plates are never destroyed), so the pointer boundary and the
-    /// click funnel can ask "is this frame a plate, and whose?" in one lookup.
+    /// Frame to pool slot, never removed: plates are never destroyed.
     by_frame: std::collections::HashMap<FrameHandle, usize>,
-    /// Completed clicks on plates, drained by the app each frame
-    /// ([`UiScript::take_nameplate_clicks`]).
+    /// Completed clicks, drained by [`UiScript::take_nameplate_clicks`].
     clicks: Vec<NamePlateClick>,
-    /// **The plate's own hit-test veto** — `0x7cba30`, the `+0x3c` override, set while a
-    /// ground-targeted spell is armed ([`UiScript::set_nameplate_hit_test_veto`]).
-    ///
-    /// Deliberately NOT the mouse-enabled bit: the reference has two distinct mechanisms here and
-    /// only one of them is visible from Lua. `0x60f830` (freelook) toggles input kind 2 on every
-    /// plate, so `IsMouseEnabled()` answers `false` — while `0x7cba30` refuses the *hit test*
-    /// before testing the rect and never touches the bit, so an addon asking a plate whether it
-    /// takes the mouse during ground targeting is told `true`, truthfully. Folding the two into
-    /// one flag would have been simpler here and wrong there.
+    /// The hit-test veto (`0x7cba30`). Not the mouse-enabled bit: it leaves `IsMouseEnabled()`
+    /// true, where freelook (`0x60f830`) clears the bit.
     hit_test_vetoed: bool,
-    /// The geometry every live plate is currently laid out under.
     geometry: Option<PlateGeometry>,
 }
 
 impl NamePlates {
-    /// Does the `0x7cba30` veto refuse `frame` this point? True only for a plate, and only while
-    /// the veto stands.
+    /// Whether the `0x7cba30` veto refuses `frame`: only a plate, only while the veto stands.
     pub(crate) fn vetoes(&self, frame: FrameHandle) -> bool {
         self.hit_test_vetoed && self.by_frame.contains_key(&frame)
     }
 }
 
-/// A completed click on a plate — what the reference's own `CGNamePlateFrame` click slot
-/// (`0x7cb910`) turns into a selection.
+/// A completed click on a plate. The reference's click slot (`0x7cb910`) selects the unit on the
+/// left button (`0x4925d0`) and selects and interacts on the right (`0x492820`).
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct NamePlateClick {
     /// The unit whose plate was clicked ([`PlateState::key`]).
     pub key: u64,
-    /// `"LeftButton"` / `"RightButton"` — the plate registers for both, on mouse-UP only
-    /// (`RegisterForClicks(0x500)` at `0x7cb637`).
+    /// `"LeftButton"` or `"RightButton"`.
     pub button: String,
 }
 
-/// What a sync produced that has to be fired **outside** the model borrow: the frames whose
-/// effective visibility flipped (their `OnShow`/`OnHide`), and the bars whose value moved (their
-/// `OnValueChanged`, which pfUI hooks — `nameplates.lua:393` — and reads `this:GetParent()` in).
+/// What a sync fires outside the model borrow: `OnShow`/`OnHide` for frames whose visibility
+/// flipped and `OnValueChanged` for moved bars (pfUI hooks it, `nameplates.lua:393`).
 #[derive(Default)]
 struct SyncEffects {
     visibility: Vec<FrameHandle>,
@@ -279,17 +155,13 @@ struct SyncEffects {
 }
 
 impl UiScript {
-    /// Drive the plate pool from the app's per-frame verdict: `states[i]` is the i-th **shown**
-    /// plate, and every pooled plate past `states.len()` is retired (hidden, never destroyed).
-    ///
-    /// `geometry` is the window-derived half; passing an unchanged value costs nothing.
+    /// Drive the pool from the app's per-frame states, one per shown plate; a unit with no state
+    /// has its plate retired (hidden, never destroyed). An unchanged `geometry` costs nothing.
     pub fn sync_nameplates(&mut self, geometry: PlateGeometry, states: &[PlateState]) {
         let lua = self.lua();
         let effects = {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // No WorldFrame, no plates: a VM with no interface loaded (a bare test app, the addon
-            // harness) has nowhere to parent them, and inventing a root would put plates somewhere
-            // an addon's walk could never find them anyway.
+            // No WorldFrame (no interface loaded), no plates: no addon walks an invented root.
             let Some(world) = model.arena.lookup("WorldFrame") else {
                 return;
             };
@@ -301,15 +173,8 @@ impl UiScript {
         }
     }
 
-    /// **The unit whose plate the pointer is inside**, or `None` — the reference's plate OnEnter
-    /// (`0x7cb850`) publishing the mouseover global `[0xb4e2c8]`, read from the app's side instead
-    /// of pushed.
-    ///
-    /// The app needs this because a plate is real UI here: with the plate mouse-enabled, the UI
-    /// pointer pass owns the cursor over it and `target::hover`'s world pick correctly stands
-    /// down — so the mouseover has to come from the frame that took it. Exactly the hovered frame,
-    /// never an ancestor: an addon frame parented to a plate takes the hover in the reference too,
-    /// and its OnEnter is the one that fires.
+    /// The unit whose plate is the hovered frame, the mouseover its OnEnter publishes (`0x7cb850`
+    /// → `0x492890`, `[0xb4e2c8]`); an addon frame on a plate takes the hover from it.
     pub fn hovered_nameplate(&self) -> Option<u64> {
         let lua = self.lua();
         let model = lua.app_data_ref::<Model>().expect("model app_data");
@@ -318,21 +183,15 @@ impl UiScript {
         model.nameplates.plates.get(slot)?.key()
     }
 
-    /// Drain the completed plate clicks — the app turns each into a selection, which is what the
-    /// reference's own click slot does. Both a physical click and Lua's `plate:Click("LeftButton")`
-    /// arrive here, because both go through the one click funnel.
+    /// Drain the completed plate clicks, physical or `plate:Click()`, for the app to select from.
     pub fn take_nameplate_clicks(&mut self) -> Vec<NamePlateClick> {
         let lua = self.lua();
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
         std::mem::take(&mut model.nameplates.clicks)
     }
 
-    /// **The mouselook toggle** (`0x60f830`): entering camera freelook disables mouse input on
-    /// every plate, leaving re-enables it — the reference walks its own intrusive plate list at
-    /// `ds:0xc4d92c` doing exactly this, called from `0x483e80` (enter) and `0x483e70` (leave).
-    ///
-    /// Without it a right-drag that starts over a plate would be a plate click instead of a camera
-    /// turn, and the plates would keep taking a pointer that is no longer on screen.
+    /// The freelook toggle (`0x60f830`): entering camera freelook disables mouse input on every
+    /// plate and leaving re-enables it (called from `0x483e80` and `0x483e70`).
     pub fn set_nameplate_mouse(&mut self, enabled: bool) {
         let lua = self.lua();
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -342,32 +201,18 @@ impl UiScript {
         }
     }
 
-    /// **The plate hit-test veto** (`0x7cba30`, the plate's `+0x3c` override — the one of the six
-    /// that can refuse *before* testing the rect): while a ground-targeted spell is armed the
-    /// plates stop taking the mouse and the click falls through to the `WorldFrame`, so the reticle
-    /// can be placed through a plate.
-    ///
-    /// The reference's predicate is `IsTargeting() && TargetingWantsLocation(flag & 0x60) &&
-    /// !0x6e6180()`. The caller supplies the first two verbatim — benilla's `TargetingWants::
-    /// Location` **is** that `& 0x60` mask. The third is another mask predicate over the same
-    /// pending-spell word (`& 0x878e`) whose
-    /// meaning is not settled; a word that reaches our targeting cursor with location bits is a
-    /// pure ground target (the resolver binds or refuses a unit word before then), so it is left
-    /// unmodelled rather than guessed at.
+    /// The plate hit-test veto (`0x7cba30`): while a ground-targeted spell is armed, clicks fall
+    /// through plates to the `WorldFrame`. The caller supplies the first two terms of the
+    /// reference's `IsTargeting() && (flag & 0x60) && !0x6e6180()`; the third, a test of the same
+    /// word against `0x878e` whose meaning is unsettled, is not applied.
     pub fn set_nameplate_hit_test_veto(&mut self, vetoed: bool) {
         let lua = self.lua();
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
         model.nameplates.hit_test_vetoed = vetoed;
     }
 
-    /// **Retire every live plate** — hide them all and return them to the pool, without touching
-    /// the geometry they are laid out under.
-    ///
-    /// The app's every early return owes this: a painter that stopped drawing left no plates
-    /// behind, but widgets stay until something hides them, so a V press that turns plates off, a
-    /// frame with no camera, or a world exit would otherwise leave the last frame's plates standing
-    /// on screen. It is `0x608a10` applied to the whole active list, which is what the reference
-    /// does when the master toggle clears.
+    /// Retire every live plate (`0x608a10` over the active list, as when the master toggle
+    /// clears); the app's every early return owes this, since a widget stays up until hidden.
     pub fn retire_nameplates(&mut self) {
         let lua = self.lua();
         let effects = {
@@ -382,7 +227,7 @@ impl UiScript {
         super::event::fire_visibility_changes(lua, effects.visibility);
     }
 
-    /// How many plate widgets the pool holds — the plate driver's census, and the tests'.
+    /// How many plate widgets the pool holds.
     pub fn nameplate_pool_len(&self) -> usize {
         let lua = self.lua();
         let model = lua.app_data_ref::<Model>().expect("model app_data");
@@ -390,8 +235,7 @@ impl UiScript {
     }
 }
 
-/// Record a completed click on `id` if that frame is a live plate — [`super::button::click_button`]
-/// calls this for every button click, physical or scripted.
+/// Record a click on `id` if it is a live plate; every button click comes here.
 pub(super) fn note_click(lua: &mlua::Lua, id: u32, button: &str) {
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
     let Some(frame) = model.id_to_frame.get(&id).copied() else {
@@ -400,7 +244,6 @@ pub(super) fn note_click(lua: &mlua::Lua, id: u32, button: &str) {
     let Some(&slot) = model.nameplates.by_frame.get(&frame) else {
         return;
     };
-    // A pooled (retired) plate has no unit, and clicking one is not possible anyway — it is hidden.
     let Some(key) = model.nameplates.plates.get(slot).and_then(Plate::key) else {
         return;
     };
@@ -410,8 +253,7 @@ pub(super) fn note_click(lua: &mlua::Lua, id: u32, button: &str) {
     });
 }
 
-/// The whole per-frame drive: grow, re-lay-out if the window moved, write what changed, retire the
-/// tail.
+/// The per-frame drive: retire departed units, bind the rest, lay out, write what changed.
 fn sync(
     model: &mut Model,
     world: FrameHandle,
@@ -422,8 +264,8 @@ fn sync(
     let relayout = model.nameplates.geometry != Some(geometry);
     model.nameplates.geometry = Some(geometry);
 
-    // Retire first, so a unit that left this frame frees its slot for one that arrived — the
-    // reference's destroy-then-create through the same free list, in the same tick.
+    // Retire first, so a departing unit's slot is free for an arriving one, as the reference
+    // destroys then creates through one free list in the same tick.
     let gone: Vec<u64> = model
         .nameplates
         .assigned
@@ -441,9 +283,8 @@ fn sync(
         let slot = match model.nameplates.assigned.get(&state.key) {
             Some(&i) => i,
             None => {
-                // The lowest free slot, else a new one at the tail. Lowest-free rather than the
-                // reference's FIFO free list: both keep every existing index meaning what it did,
-                // which is the only property an addon can observe.
+                // The lowest free slot, else a new one at the tail. Deviation: the reference's
+                // free list is FIFO; either keeps every index stable, all an addon can observe.
                 let free = (0..model.nameplates.plates.len())
                     .find(|i| model.nameplates.plates[*i].last.is_none());
                 let i = free.unwrap_or_else(|| {
@@ -461,8 +302,7 @@ fn sync(
         Plate::drive(model, slot, world, state, &mut effects);
     }
 
-    // A geometry change reaches the retired plates too: they are still in the child list, an addon
-    // can still read them, and they must not come back next frame laid out for the old window.
+    // A geometry change reaches retired plates too: addons still read them in the child list.
     if relayout {
         for i in 0..model.nameplates.plates.len() {
             if model.nameplates.plates[i].laid_out != Some(geometry) {
@@ -474,13 +314,11 @@ fn sync(
 }
 
 impl Plate {
-    /// Build one plate: the Button under the WorldFrame, its six regions in the reference's
-    /// creation order, and the health-bar child with its fill.
-    ///
-    /// Everything here is written **once**. An addon that blanks a region (pfUI's `DisableObject`
-    /// does `SetTexture("")`) must find it still blank on the next frame.
+    /// Build one plate: the Button, its six regions in the reference's order, and the health bar.
+    /// Written once, so a region an addon blanks stays blank.
     fn create(model: &mut Model, world: FrameHandle, effects: &mut SyncEffects) -> Plate {
-        // Anonymous, and that is a requirement rather than an omission (module doc).
+        // Anonymous, as the reference's name is zeroed (`0x76c50b`): plate addons reject a named
+        // `WorldFrame` child.
         let frame = model.arena.create(FrameKind::Button, None, Some(world));
         let strata = model
             .arena
@@ -489,21 +327,9 @@ impl Plate {
             .unwrap_or_default();
         model.arena.set_frame_strata(frame, strata);
         model.arena.set_frame_level(frame, PLATE_LEVEL, true);
-        // The plate takes the mouse, which it is born with: `CSimpleButton`'s ctor writes
-        // `[+0xcc] = 0x4` (`0x7786a3`), so the reference's plate needs no `EnableMouse` of its own
-        // and neither does ours. Hovering it publishes the mouseover (`0x7cb850` → `0x492890`) and
-        // a completed click selects through the button's click slot (`0x7cb910`); both reach the
-        // app through [`UiScript::hovered_nameplate`] and [`UiScript::take_nameplate_clicks`].
-        // `EnableMouse`/`IsMouseEnabled` are in the corpus's own call set, and pfUI's vanilla
-        // click-through block drives them.
-        //
-        // **And it takes BOTH buttons, on the UP edge**: `RegisterForClicks(0x500)` at `0x7cb637`
-        // (`0x779730` → `[this+0x330] = 0x500` = LeftButtonUp | RightButtonUp). The arena's Button
-        // default is `{"LeftButtonUp"}` alone, so without this a physical right-click on a plate
-        // fired no click at all — [`super::button::wants_click`] refused the release, the funnel
-        // never ran, and since 2233 took the camera off a press that lands on a plate there was no
-        // other path left: right-clicking a nameplate did nothing. The reference's own slot
-        // (`0x7cb910`) takes mask 1 → `0x4925d0` select and mask 4 → `0x492820` select+interact.
+        // Mouse-enabled from birth by `CSimpleButton`'s ctor (`0x7786a3`), and registered for
+        // both buttons on the up edge (`RegisterForClicks(0x500)`, `0x7cb637`); the arena's
+        // Button default is the left alone.
         if let Some(KindState::Button(bs)) = model.arena.frame_mut(frame).map(|f| &mut f.kind_state)
         {
             bs.registered_clicks = ["LeftButtonUp", "RightButtonUp"]
@@ -512,9 +338,8 @@ impl Plate {
                 .collect();
         }
 
-        // The blend modes are the ctor's own, one `0x7703f0` call per texture: everything is
-        // BLEND(2) except the **glow, which is ADD(3)** (`push 3` at `0x7cb36a` → `0x7cb374`).
-        // Getting that one wrong is not a subtlety — see [`is_unpainted_glow`].
+        // The ctor's blend modes, one `0x7703f0` call per texture: BLEND, but the glow is ADD
+        // (`0x7cb36a`), which [`is_unpainted_glow`] depends on.
         let border = texture(
             model,
             frame,
@@ -545,9 +370,10 @@ impl Plate {
             RAID_ICON_TEXTURE,
             BlendMode::Blend,
         );
-        // ↑ THE ORDER. Six regions, and this sequence is the ABI (module doc).
+        // The order above is the ABI addons walk and, as 5875 has no sub-level, the draw order
+        // within a layer.
 
-        // The one child, below the plate's own level so the border draws over the fill.
+        // The one child, below the plate's level so the border draws over the fill.
         let bar = model.arena.create(FrameKind::StatusBar, None, Some(frame));
         model.arena.set_frame_strata(bar, strata);
         model.arena.set_frame_level(bar, BAR_LEVEL, true);
@@ -557,9 +383,7 @@ impl Plate {
             .expect("live bar");
         let fill_data = model.region_data.entry(fill).or_default();
         fill_data.texture = Some(BAR_FILL_TEXTURE.to_string());
-        // Not overridden by the ctor — the `CSimpleTexture` ctor's own `[+0xd0] = 2` stands
-        // (`0x76fc40`). Written explicitly because the default is a FACT here, not an
-        // omission.
+        // The fill keeps `CSimpleTexture`'s default BLEND (`0x76fc40`), written out as a fact.
         fill_data.blend = BlendMode::Blend;
         if let Some(KindState::StatusBar(sb)) =
             model.arena.frame_mut(bar).map(|f| &mut f.kind_state)
@@ -570,14 +394,11 @@ impl Plate {
             sb.value = 0.0;
         }
 
-        // The skull and the raid icon are the two regions that only sometimes show; the glow is
-        // shown on hover alone. The rest are always up while the plate is.
         for rh in [glow, skull, raid] {
             model.region_data.entry(rh).or_default().hidden = true;
         }
 
-        // Born retired: a fresh plate belongs to no unit yet, and `IsShown()` is what an addon
-        // reads to tell a live plate from a pooled one.
+        // Born retired and hidden: addons tell a live plate from a pooled one by `IsShown()`.
         effects
             .visibility
             .extend(model.arena.set_shown(frame, false));
@@ -602,8 +423,8 @@ impl Plate {
         }
     }
 
-    /// (Re)lay the static anchors — everything that follows from the window's size rather than the
-    /// unit. Called on the first drive and on a geometry change, never per frame.
+    /// Write the window-derived sizes and anchors, on the first drive and a geometry change. The
+    /// reference's are real anchors too, through `SetPoint`'s own store (`0x767c70`).
     fn lay_out(model: &mut Model, i: usize, g: PlateGeometry) {
         let p = &model.nameplates.plates[i];
         let (frame, bar) = (p.frame, p.bar);
@@ -611,12 +432,11 @@ impl Plate {
             (p.border, p.glow, p.name, p.level, p.skull, p.raid);
         let plate_id = model.frame_id(frame);
 
-        // The plate's own size; its position is per-frame and lives in `drive`.
+        // The plate's size; its position is per-frame, in `drive`.
         let input = model.layout_inputs.entry(frame).or_default();
         input.width = g.width;
         input.height = g.height;
 
-        // The border fills the plate, and so does the glow — a rim over the whole frame.
         for rh in [border, glow] {
             model.region_data.entry(rh).or_default().anchors = vec![
                 Anchor::new(Point::TopLeft, plate_id, Point::TopLeft, 0.0, 0.0),
@@ -624,7 +444,6 @@ impl Plate {
             ];
         }
 
-        // The health bar: BOTTOMLEFT + (off_x, off_y), explicit size.
         let bar_input = model.layout_inputs.entry(bar).or_default();
         bar_input.anchors = vec![Anchor::new(
             Point::BottomLeft,
@@ -636,7 +455,7 @@ impl Plate {
         bar_input.width = g.bar_width;
         bar_input.height = g.bar_height;
 
-        // The name — ("BOTTOM", plate, "CENTER", 0, 0), the pair `_Nameplates` validates.
+        // The name's (`0x7cb456`) and level's (`0x7cb7f5`) anchors, which `_Nameplates` checks.
         let name_data = model.region_data.entry(name).or_default();
         name_data.anchors = vec![Anchor::new(
             Point::Bottom,
@@ -647,7 +466,6 @@ impl Plate {
         )];
         name_data.font_height = Some(g.name_height);
 
-        // The level — ("CENTER", plate, "BOTTOMRIGHT", −x, +y), the other validated pair.
         for rh in [name, level] {
             model.region_data.entry(rh).or_default().font_shadow = Some(FontShadow {
                 offset: [g.shadow_offset, -g.shadow_offset],
@@ -667,7 +485,6 @@ impl Plate {
         level_data.font_explicit.height = true;
         model.touch_measure(level);
 
-        // The skull replaces the level number, in the level's own seat.
         let skull_data = model.region_data.entry(skull).or_default();
         skull_data.anchors = vec![Anchor::new(
             Point::Center,
@@ -678,19 +495,16 @@ impl Plate {
         )];
         skull_data.size = Some((g.skull_size, g.skull_size));
 
-        // The raid icon hangs off the LEFT edge, vertically centred.
         let raid_data = model.region_data.entry(raid).or_default();
         raid_data.anchors = vec![Anchor::new(Point::Right, plate_id, Point::Left, 0.0, 0.0)];
         raid_data.size = Some((g.raid_size, g.raid_size));
 
-        // Anchor TARGETS moved (from nothing to the plate) on the first lay-out, so this is the
-        // conservative touch — the only one in this module, and it runs once per geometry change.
+        // The first lay-out adds anchor targets, so the full touch; once per geometry change.
         model.touch_layout();
         model.nameplates.plates[i].laid_out = Some(g);
     }
 
-    /// The per-frame write: position, health, texts, colours, shown flags, alpha — **and nothing
-    /// else**, each only when it moved.
+    /// The per-frame write, each property only when it moved.
     fn drive(
         model: &mut Model,
         i: usize,
@@ -705,10 +519,8 @@ impl Plate {
         let last = p.last.clone();
         let world_id = model.frame_id(world);
 
-        // The seat, re-issued whenever it moves, exactly like the reference's own (`0x509ec0`:
-        // ClearAllPoints then SetPoint) — which is why an addon anchor on the plate does not
-        // survive there either. A moved OFFSET keeps the graph's edges, so the precise touch
-        // applies; the first seat adds an edge and takes the retarget.
+        // Re-seated whenever it moves, as the reference does (`0x509ec0`). A moved offset keeps
+        // the graph's edges, so the precise touch; the first seat adds an edge, so the retarget.
         if last
             .as_ref()
             .is_none_or(|l| l.top_centre != state.top_centre)
@@ -741,9 +553,7 @@ impl Plate {
             model.arena.set_alpha(frame, state.alpha);
         }
 
-        // The bar reports RAW health (module doc). Its fill carries the reaction colour, lifted by
-        // a uniform brighten while the unit is the mouseover or the target — 0184's form of the
-        // highlight, in place of the additive `Nameplate-Glow` rim.
+        // Raw health on the bar; the fill's reaction colour brightens while lit (`LIT_BOOST`).
         if last
             .as_ref()
             .is_none_or(|l| l.health != state.health || l.max_health != state.max_health)
@@ -767,7 +577,6 @@ impl Plate {
                 Some([c[0] * boost, c[1] * boost, c[2] * boost, 1.0]);
         }
 
-        // The name: white, yellow while the plate itself is hovered.
         if last.as_ref().is_none_or(|l| l.name != state.name) {
             model.region_data.entry(name).or_default().text = Some(state.name.clone());
             model.touch_measure(name);
@@ -780,17 +589,15 @@ impl Plate {
                 [1.0, 1.0, 1.0, 1.0]
             };
             model.region_data.entry(name).or_default().vertex_color = Some(c);
-            // `glow:IsShown()` IS the mouseover signal (pfUI `nameplates.lua:601`). The region is
-            // shown for real; that it paints nothing is 0184's deviation, not a missing region.
+            // The glow really shows, as addons read mouseover from it; it only paints nothing.
             model.region_data.entry(glow).or_default().hidden = !state.hovered;
         }
 
-        // Level text and skull are mutually exclusive, in one seat.
         if last.as_ref().is_none_or(|l| {
             l.level != state.level || l.skull != state.skull || l.level_colour != state.level_colour
         }) {
             match (state.level, state.skull) {
-                // The skull wins the seat, and it is the SKULL FLAG that puts it there.
+                // The skull flag wins the seat, whatever the level.
                 (_, true) => {
                     model.region_data.entry(level).or_default().hidden = true;
                     model.region_data.entry(skull).or_default().hidden = false;
@@ -805,7 +612,7 @@ impl Plate {
                     model.touch_measure(level);
                     model.touch_layout_region(level);
                 }
-                // No level yet and no skull: the seat stays EMPTY, the old painter's behaviour.
+                // No level yet and no skull: the seat stays empty.
                 (None, false) => {
                     model.region_data.entry(level).or_default().hidden = true;
                     model.region_data.entry(skull).or_default().hidden = true;
@@ -813,7 +620,6 @@ impl Plate {
             }
         }
 
-        // The raid mark: the 4-column atlas cell, shown only while the unit carries one.
         if last.as_ref().is_none_or(|l| l.raid_icon != state.raid_icon) {
             match state.raid_icon {
                 Some(idx) => {
@@ -829,10 +635,8 @@ impl Plate {
         model.nameplates.plates[i].last = Some(state.clone());
     }
 
-    /// Retire a plate: **hide it, never destroy it** (`0x608a10` — unlink from the active list,
-    /// push onto the free list, `Hide`). It keeps its slot in `WorldFrame`'s child list, keeps its
-    /// index, and comes back as the same Lua object, which is the contract every addon's
-    /// `registry[plate]` identity map rests on.
+    /// Retire a plate: hide it, never destroy it (`0x608a10`), so it keeps its child-list index and
+    /// comes back as the same Lua object addons key their per-plate state by.
     fn retire(model: &mut Model, i: usize, effects: &mut SyncEffects) {
         if model.nameplates.plates[i].last.is_none() {
             return;
@@ -845,10 +649,7 @@ impl Plate {
     }
 }
 
-/// One of the plate's texture regions, with its path and its blend mode — created in the ABI's
-/// order by the caller. The mode is not decoration: the ctor sets one on every texture it makes
-/// (`0x7703f0`, storing `[texture+0xd0]`), and the glow's is the one that differs — see
-/// [`is_unpainted_glow`].
+/// One of the plate's textures, with its path and the blend mode the ctor sets (`0x7703f0`).
 fn texture(
     model: &mut Model,
     frame: FrameHandle,
@@ -866,18 +667,9 @@ fn texture(
     rh
 }
 
-/// One of the plate's two FontStrings. Both are OVERLAY — the ctor re-layers them off ARTWORK
-/// (`0x7cb438`, `0x7cb4ea`) — and both take `NAMEPLATE_FONT` with the plate's black 1 px drop
-/// shadow; the heights arrive with the geometry.
-///
-/// The black drop shadow is written in [`Plate::lay_out`] instead of here: its step is a
-/// WINDOW-derived number ([`PlateGeometry::shadow_offset`]), not a create-time constant.
-///
-/// `justify_v` is the one benilla-side compensation here, and it is the old painter's, kept: the
-/// plate's name is seated by its **ink**, not by the line box. Our shaper's box is ascent-heavy
-/// for Friz, so a box-seated `BOTTOM` anchor drops the name ~8 px — half of it over the plate —
-/// which is the director's old "the level is not aligned" in its other half. `Bottom` puts the
-/// text where the reference's own metrics put it.
+/// One of the plate's two FontStrings, OVERLAY as the ctor re-layers them (`0x7cb438`,
+/// `0x7cb4ea`). `justify_v` seats the name by its ink: our shaper's Friz line box is ascent-heavy
+/// and would drop it ~8 px below where the reference's metrics put it.
 fn font_string(model: &mut Model, frame: FrameHandle, justify_v: JustifyV) -> RegionHandle {
     let rh = model
         .arena
@@ -890,60 +682,21 @@ fn font_string(model: &mut Model, frame: FrameHandle, justify_v: JustifyV) -> Re
     rh
 }
 
-/// **Is this frame a V-plate?** — the seat question, asked of the OWNER (decision 2172).
-///
-/// A plate is a WorldFrame overlay: the driver snaps its rect to the DEVICE pixel grid
-/// (`vplates::device_snap`, 0188/1398) because it slides continuously over the world, and
-/// everything drawn inside it has to be rigid to that rect. The renderer's UI seat snap quantizes
-/// a text block's top on the coarser LOGICAL grid, so with both laws in force a plate's name and
-/// level pop a whole logical pixel every second step the border takes — two quantizers on one
-/// sliding object, and the "janky text walking up to a mob" the director reported the day after
-/// decision 2148 moved these strings out of a painter that never snapped them (its host-measure
-/// rects were degenerate, and a degenerate rect skips the snap — the carve-out the port silently
-/// stopped selecting).
-///
-/// **Asked of the frame rather than written on our six regions**, because it is the frame that
-/// slides: pfUI and ShaguTweaks blank the stock regions and hang their *own* FontStrings on the
-/// plate, and those are drawn inside the same rect and want the same answer. (A string an addon
-/// puts on the plate's health-BAR child is one level further down and still takes the UI grid —
-/// the named residual, and the shape of the fix if it ever bites is an ancestor walk.)
+/// Whether a text's owner is a plate. A plate's rect snaps to device pixels as it slides, and its
+/// text must follow that rect, not the UI's coarser grid, or it jumps. Asked of the frame so an
+/// addon's strings on the plate get it too; a string on the plate's health bar does not.
 pub(super) fn is_world_seated(model: &Model, frame: FrameHandle) -> bool {
     model.nameplates.by_frame.contains_key(&frame)
 }
 
-/// **The plate's glow region paints nothing here** — the region is real, shown, textured and ADD,
-/// and the quad walk skips it ([`super::extract`]). Decision 0184, and it is the director's call
-/// rather than a gap we could close by trying harder.
-///
-/// The reference draws this region `(SRC_ALPHA, ONE)` over the health bar: an additive
-/// reaction-tinted lift of the bar's cavity. 0183 built exactly that and the director rejected it
-/// on sight — *"you should not change the gradient or anything — just make the color of the yellow
-/// bar brighter"* — so 0184 replaced the rim with [`LIT_BOOST`], and the paint has been the bar's
-/// own brighten ever since. That is what this predicate keeps true now that the plate is a widget
-/// and its regions go through the shared frame→quad path instead of a painter that simply never
-/// emitted a glow quad.
-///
-/// **Why the mode matters even though nothing is drawn.** `Nameplate-Glow.blp` is DXT1 with **no
-/// alpha channel** — every one of its 4096 texels is alpha 255 — and 80.5% of it is exactly
-/// `rgb(0,0,0)`, the surround; the signal is a grey rounded bar (rim 140, interior ~46) in rows
-/// 20-26 that only reads as a glow when it is *added*. Blitted with straight `BLEND` it is
-/// `dst·(1−1) + black·1` — **an opaque black rectangle over the whole plate**, which is precisely
-/// what shipped when the widget port left the mode at the ctor default (director report,
-/// 2026-09-10). So `GetBlendMode()` answers `"ADD"` truthfully, an addon that re-textures the
-/// region gets its own art painted normally, and only the reference's own glow art on an ADD
-/// region is the one thing this engine declines to draw.
+/// Whether this is the plate's own glow art on its ADD mode, which the quad walk
+/// ([`super::extract`]) skips. Deviation: the reference adds this rim over the bar; we brighten
+/// the bar ([`LIT_BOOST`]), because the rim reads as hard edge lines in our linear-blending
+/// pipeline. The art has no alpha and is mostly black, so as BLEND it would be an opaque box.
 pub(super) fn is_unpainted_glow(data: &RegionData) -> bool {
     data.blend == BlendMode::Add && data.texture.as_deref() == Some(GLOW_TEXTURE)
 }
 
-/// The LIT (mouseover ∪ target) bar brighten — a uniform multiplicative lift of the fill tint,
-/// gradient untouched (0184: the recorded additive `Nameplate-Glow` rim read as hard edge lines on
-/// our linear-blending pipeline, and the director pinned the brighten instead).
-///
-/// Quad colours are client-space sRGB (`srgb_quad_color` linearizes them), so this multiplies
-/// ENCODED texels ~1:1 — the gamma-space modulate the client's FFP would do. **255/215 is the
-/// largest clean value**: the fill texture's encoded peak (215) lands exactly on white, no row
-/// clips, and every row scales by the same visible factor. (A first cut of 1.45 assumed a
-/// linear-space multiply and flattened six rows against white — the very gradient change the
-/// director banned.)
+/// The lit bar's brighten, a multiply of the fill tint in encoded sRGB like the client's modulate:
+/// 255/215 takes the fill texture's encoded peak exactly to white, so no gradient row clips.
 const LIT_BOOST: f32 = 255.0 / 215.0;
diff --git a/crates/benilla-ui/src/script/net_stats.rs b/crates/benilla-ui/src/script/net_stats.rs
index c4fbc4c6..5732662c 100644
--- a/crates/benilla-ui/src/script/net_stats.rs
+++ b/crates/benilla-ui/src/script/net_stats.rs
@@ -1,27 +1,15 @@
-//! `GetNetStats()` — the connection-telemetry read the main bar's performance ("ping") meter polls.
-//!
-//! One global over one pushed number. The reference binding (`0x48b8b0`) returns `bandwidthIn,
-//! bandwidthOut, latency`; its latency is **not** the last round trip but the average over the
-//! connection's RTT ring — `HandlePong 0x537d60` puts the RTT into that ring (head/tail wrap 16),
-//! feeding `0x537f20`'s throughput/avg-RTT math (host telemetry; no wire bytes). The app owns
-//! that ring
-//! ([`crate`]'s consumer keeps it beside its ping clock) and pushes the average here; the engine
-//! stays free of ECS/net reach (decision 0068 §3), exactly as [`super::unit`]'s `GetMoney` does.
-//!
-//! **The two bandwidth returns are `0`.** benilla measures no throughput — its socket threads tally
-//! no bytes — and nothing in the 1.12 UI reads them: `MainMenuBarPerformanceBarFrame` is the whole
-//! shipped caller of `GetNetStats` and discards both. They stay in the signature (numbers, not
-//! `nil`, so arithmetic on them can't error) as a named gap, not a claim.
+//! `GetNetStats()` (`0x48b8b0`): `bandwidthIn, bandwidthOut, latency` for the main bar's latency
+//! meter. The latency is the average over the connection's 16-slot RTT ring (`HandlePong`
+//! `0x537d60`, `0x537f20`), which the app keeps and pushes here. Both bandwidths read 0: benilla
+//! measures no throughput, and the one stock caller, `MainMenuBarPerformanceBarFrame`, drops them.
 
 use mlua::Lua;
 
 use super::Model;
 
 impl super::UiScript {
-    /// Push the reported round trip (ms) — the app's average over its RTT ring. `None` = no sample
-    /// yet (before the connection's first pong, or after a disconnect), which reads as `0` through
-    /// `GetNetStats`: the reference reports 0 for an unmeasured connection too, and the bar's
-    /// thresholds put 0 in the green band, which is what the real client shows at login.
+    /// Push the average round trip in ms; `None`, before the first pong, reads 0, as the reference
+    /// reports an unmeasured connection.
     pub fn set_latency_ms(&mut self, ms: Option<u32>) {
         self.model_mut().net_latency_ms = ms.unwrap_or(0);
     }
@@ -29,7 +17,6 @@ impl super::UiScript {
 
 /// Register the net-stats globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
-    // GetNetStats() → bandwidthIn, bandwidthOut, latency (see the module doc for the two zeros).
     lua.globals().set(
         "GetNetStats",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/object.rs b/crates/benilla-ui/src/script/object.rs
index bb02e635..848cf82b 100644
--- a/crates/benilla-ui/src/script/object.rs
+++ b/crates/benilla-ui/src/script/object.rs
@@ -1,19 +1,10 @@
-//! The FrameScript object model, frame side — `CreateFrame`, the frame metatable +
-//! wrapper cache, and the shared frame method surface (decision 0068 v1). The region side lives in
-//! [`super::region`]; per-kind frame methods in their own modules ([`super::statusbar`], …),
-//! dispatched by [`kind_method_registries`] before the shared table.
+//! The FrameScript object model, frame side: `CreateFrame`, the frame wrappers and metatables, and
+//! the shared frame methods; the region side is [`super::region`].
 //!
-//! A frame's Lua value is a table `T` with `T[0] = lightuserdata(id)` (the id encoding stands in for
-//! the client's `CScriptObject*`; `0x701bd0` writes `T[0] = lightuserdata(this)` — see the module
-//! docs on ids) and one **shared** metatable whose `__index` is a Rust function that dispatches a
-//! method name to its implementation. Wrappers are cached in a Lua-side registry table keyed by id,
-//! so `GetParent()` (etc.) returns the *same* table every time (stable identity). Named frames
-//! auto-publish to `_G`, non-overwriting (`0x701bd0`). Region
-//! leaves (`Texture`/`FontString`) use the same `T[0]` scheme but a *distinct* metatable (the "tag"
-//! that separates their method surface from frames').
-//!
-//! The whole surface honors the MAXCSTACK discipline: the two metatables, the two method tables, and
-//! the wrapper cache live in the Lua registry (named keys); Rust holds none of them across calls.
+//! A frame's Lua value is a table `T` with `T[0] = lightuserdata(id)` (`0x701bd0`), cached by id
+//! and published to `_G` by name without overwriting; its metatable is its kind's
+//! ([`frame_meta_for`]). Every table lives in the Lua registry under a named key, and Rust holds
+//! none across calls (the MAXCSTACK discipline).
 
 use std::ffi::c_void;
 
@@ -25,8 +16,7 @@ use crate::layout::Point;
 use crate::order::{DrawLayer, Strata};
 use crate::widget::{FrameHandle, FrameKind};
 
-// The frame method-table clusters — split out purely for size (each module's own doc says what
-// lives there); this file keeps the shared id/handle plumbing, `install`, and `CreateFrame`.
+// The frame method clusters, split out for size.
 pub(crate) mod anchor_args;
 mod events_regions;
 mod frame_state;
@@ -67,12 +57,11 @@ pub(super) fn frame_handle_of(lua: &Lua, this: &Table) -> mlua::Result<FrameHand
 }
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
-// Wrapper cache (`0x701bd0`: lazy bind + named _G publish, non-overwriting)
+// Wrapper cache (`0x701bd0`)
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
-/// Get-or-create the wrapper table for a frame id, caching it and (if the frame is named and `_G`
-/// has no such global yet) publishing it to `_G`. Callers must hold **no** model borrow (this takes
-/// a short one to read the frame's name).
+/// The wrapper table for a frame id, created and cached on first use and published to `_G` under
+/// the frame's name if that global is free. Call it with no model borrow alive.
 pub(super) fn frame_wrapper(lua: &Lua, id: u32) -> mlua::Result<Table> {
     let wrappers: Table = lua.named_registry_value(REG_WRAPPERS)?;
     if let Value::Table(t) = wrappers.get::<Value>(id)? {
@@ -80,12 +69,8 @@ pub(super) fn frame_wrapper(lua: &Lua, id: u32) -> mlua::Result<Table> {
     }
     let t = lua.create_table()?;
     t.raw_set(0, Value::LightUserData(id_to_lud(id)))?;
-    // The frame's kind and name in one borrow. **The KIND picks the metatable, here rather than
-    // per lookup** — the region side's shape since its leaves split, and decision 2310's whole
-    // change on this side: a wrapper is built once per frame, so resolving the class chain at
-    // construction costs nothing, while resolving it inside `__index` put a Rust call, a model
-    // borrow and a registry lookup in front of EVERY widget method access in the client. A frame's
-    // kind never changes and `id_to_frame` never loses an entry, so the choice cannot go stale.
+    // The kind picks the metatable once, here: a frame's kind never changes and `id_to_frame`
+    // never loses an entry, so the choice cannot go stale.
     let (kind, name): (Option<FrameKind>, Option<String>) = {
         let model = lua.app_data_ref::<Model>().expect("model app_data");
         let frame = model
@@ -111,44 +96,21 @@ pub(super) fn publish_global(lua: &Lua, name: &str, wrapper: &Table) -> mlua::Re
     Ok(())
 }
 
-/// A widget **name string** argument, already looked up in `_G` — every Lua binding that takes
-/// "a frame or its name" resolves one of these ([`prefetch_named_target`] then
-/// [`resolve_named_target`]).
-///
-/// **The client has ONE widget namespace and it is the Lua globals table.** The wrapper binder
-/// `0x701bd0` publishes `_G[name] = T` for a named widget (non-overwriting, via `lua_settable`),
-/// and every by-name resolver reads that table back — `0x76c760` (globals index → Lua type 5 →
-/// **raw** `t[0]` → `lua_touserdata` → `IsA`; `SetParent`'s string arm `0x7a1550`, `SetScrollChild`
-/// `0x790fa0`, the XML `parent=` chain) and the layout-vtable `+0x28` entry `0x76c700`, which
-/// expands a leading `$parent` (`0x76c5b0`) and then calls `0x76c760`. There is no engine-side
-/// name→frame map behind either: for frames and regions a name's only effects are the copy into
-/// `[widget+0x98]` and that `_G` publish. (`CSimpleFont` names are the one exception — they key a
-/// Storm hash at `0xcf4e78` — and fonts are not anchor targets.) Full addresses:
-/// `0x76c5b0`/`0x76c700`/`0x76c760`/`0x7a2540`.
-///
-/// So the name is not a *frame name* — it is a **global**, and a frame's published name is only the
-/// commonest way one comes to exist. Resolving against a private registry instead makes an alias
-/// invisible: `Bar8Button1 = CharacterBag3Slot` at an addon's file scope is a global that is no
-/// frame's name, and Bartender2 anchors every bar's buttons through exactly those (decision 2105).
-///
-/// ## Why the lookup is its own phase
-///
-/// The reference's read is **`lua_gettable 0x6f3a40` → `luaV_index 0x6f7cf0`**, not `lua_rawget`
-/// (the binary holds both, 0xc0 apart; only the former walks `__index`, MAXTAGLOOP 100). So a
-/// metatable on `_G` is honoured — and a `__index` can be a *Lua* function that calls straight back
-/// into a widget binding. Running that under a live `Model` guard would take a second borrow and
-/// panic, so the `_G` read is done with **no guard alive** and the decode happens after.
+/// A widget name argument already looked up in `_G` ([`prefetch_named_target`], then
+/// [`resolve_named_target`]). The globals table is the client's only widget namespace (`0x701bd0`
+/// publishes there; `0x76c760` and the anchor resolver `0x76c700` read back), so a global alias
+/// of a frame (`Bar8Button1 = CharacterBag3Slot`) resolves like its name. The read is
+/// `lua_gettable` (`0x6f3a40` → `0x6f7cf0`), which honours an `__index` on `_G` that may call back
+/// into a widget binding, so it runs with no `Model` borrow alive and the decode comes after.
 pub(crate) struct NamedTarget {
-    /// The name as the client looked it up — after `$parent` expansion where the caller allows it.
-    /// This is the spelling a diagnostic must quote.
+    /// The name as looked up, after any `$parent` expansion: the spelling a diagnostic quotes.
     pub(crate) name: String,
-    /// `_G[name]`, kept only when it is a table (the Lua-type-5 gate). Identity is checked later.
+    /// `_G[name]` if it is a table (Lua type 5); its identity is decoded later.
     wrapper: Option<Table>,
 }
 
 impl NamedTarget {
-    /// A name argument we could not even read (a non-UTF-8 Lua string) — it names nothing, and the
-    /// caller's miss path quotes this placeholder the way it always has.
+    /// A name that is not UTF-8: it names nothing, and the miss path quotes `<non-utf8>`.
     pub(crate) fn unreadable() -> Self {
         Self {
             name: "<non-utf8>".into(),
@@ -157,14 +119,11 @@ impl NamedTarget {
     }
 }
 
-/// Read `_G[name]` for a name-string argument. **Call with no `Model` borrow alive** — see
-/// [`NamedTarget`].
-///
-/// `parent_base` is the name a leading `$parent` expands to, or `None` for the bindings that do not
-/// expand it. `0x76c5b0` has exactly two call sites — `SetName 0x76c691` and `0x76c71c` inside the
-/// layout resolver `0x76c700` — so `SetPoint`/`SetAllPoints`' `relativeTo` **is** expanded at
-/// runtime, and `SetParent`, `SetScrollChild` and the XML `parent=` chain (which call `0x76c760`
-/// directly) are **not**.
+/// Read `_G[name]` for a name argument, with no `Model` borrow alive. `parent_base` is what a
+/// leading `$parent` expands to, `None` where the binding does not expand: `0x76c5b0` is called
+/// only from `SetName` (`0x76c691`) and the anchor resolver (`0x76c71c` in `0x76c700`), so
+/// `SetPoint`/`SetAllPoints`' `relativeTo` expands, and `SetParent`, `SetScrollChild` and XML
+/// `parent=`, which call `0x76c760` directly, do not.
 pub(crate) fn prefetch_named_target(
     lua: &Lua,
     name: &str,
@@ -181,23 +140,17 @@ pub(crate) fn prefetch_named_target(
     NamedTarget { name, wrapper }
 }
 
-/// Decode a [`NamedTarget`] to the stable id of a live frame **or** region (the namespace is one —
-/// a Texture or FontString publishes into `_G` on the same rule a Frame does).
-///
-/// `SetPoint` type-checks against the **root** `CScriptRegion` id `[0xcf0c3c]`, which every widget
-/// accepts; `SetParent`/`SetScrollChild` use the narrower Frame id `[0xcf0c10]`, so those callers
-/// narrow the result to `id_to_frame` themselves.
+/// Decode a [`NamedTarget`] to a live frame's or region's id: `SetPoint` accepts any widget (the
+/// `CScriptRegion` type id `[0xcf0c3c]`), while `SetParent` and `SetScrollChild` check the Frame
+/// id `[0xcf0c10]` and narrow the result themselves.
 pub(crate) fn resolve_named_target(model: &Model, target: &NamedTarget) -> Option<u32> {
     let id = decode_id(target.wrapper.as_ref()?).ok()?;
     (model.id_to_frame.contains_key(&id) || model.id_to_region.contains_key(&id)).then_some(id)
 }
 
-/// The name a leading `$parent` expands to: the first widget at or above `start` with a non-empty
-/// name (`0x76c5b0`'s `+0x9c` walk, skipping an empty `GetName`), and
-/// [`crate::framexml::DEFAULT_PARENT_NAME`] (`"Top"`) when there is none (`0x76c5dd`).
-///
-/// `start` is the anchoring widget's **parent**: a frame's own anchors say `$parent` of its
-/// enclosing frame, and a region's say `$parent` of its owner — which is that region's `+0x9c`.
+/// What a leading `$parent` expands to: the first non-empty name at or above `start` (`0x76c5b0`'s
+/// `+0x9c` walk), else [`crate::framexml::DEFAULT_PARENT_NAME`] (`0x76c5dd`). `start` is the
+/// anchoring widget's parent: a frame's enclosing frame, a region's owner.
 pub(crate) fn parent_token_base(model: &Model, start: Option<FrameHandle>) -> String {
     let mut cur = start;
     while let Some(p) = cur {
@@ -210,13 +163,13 @@ pub(crate) fn parent_token_base(model: &Model, start: Option<FrameHandle>) -> St
     crate::framexml::DEFAULT_PARENT_NAME.to_string()
 }
 
-/// [`parent_token_base`] for a frame's own anchors — the walk starts at its parent.
+/// [`parent_token_base`] for a frame's own anchors: the walk starts at its parent.
 pub(crate) fn frame_parent_token_base(model: &Model, h: FrameHandle) -> String {
     parent_token_base(model, model.arena.frame(h).and_then(|f| f.parent))
 }
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
-// String → enum parsing (the client's tables, transcribed in order.rs / layout.rs)
+// String → enum parsing
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
 pub(super) fn point_from_str(s: &str) -> Option<Point> {
@@ -234,10 +187,7 @@ pub(super) fn point_from_str(s: &str) -> Option<Point> {
     })
 }
 
-/// The inverse of [`point_from_str`] (the client's point-id table `0x811a38`, names back out).
-///
-/// `pub(super)` because the REGION cluster reports the same names from the same table — one
-/// spelling of the point set, not two (`region/layout.rs`'s `GetPoint`).
+/// The inverse of [`point_from_str`]: the names of the client's point table `0x811a38`.
 pub(super) fn point_name(p: Point) -> &'static str {
     match p {
         Point::TopLeft => "TOPLEFT",
@@ -252,21 +202,16 @@ pub(super) fn point_name(p: Point) -> &'static str {
     }
 }
 
-/// Every closed-vocabulary attribute parser **trims** before it matches (decision 1204).
-///
-/// Not tidiness: `zBar.xml:146` — a shipped, working 1.12 addon — declares
-/// `frameStrata="BACKGROUND "` with a trailing space, and the real client took it. Ours refused,
-/// the frame's whole `<Frames>` subtree went with it, and the addon never loaded. Whitespace is
-/// never meaningful in an enum token, so trimming is both the lenient answer and the correct one;
-/// it is applied at the three parsers rather than at the attribute read, because a `text=`
-/// attribute's leading space IS meaningful and must not be touched.
+/// An enum token, trimmed and uppercased; trimmed here rather than at the attribute read, since a
+/// `text=` value's spaces count. The reference's strata lookup compares the whole token,
+/// case-insensitively (`0x6f17ee`), so a padded `"BACKGROUND "` misses there.
 fn enum_token(s: &str) -> String {
     s.trim().to_ascii_uppercase()
 }
 
-/// The reference's strata NAME table (`0x8119f8`) has eight rows, `BACKGROUND`..`TOOLTIP`; stratum
-/// 0 (`WORLD`) has no name and no XML or Lua can put a frame there — the WorldFrame's constructor
-/// is its only writer (decision 1984, `0x481aff`).
+/// A strata name. The reference's table (`0x8119f8`) holds the eight `BACKGROUND`..`TOOLTIP`;
+/// `BLIZZARD` is a later client's, not 1.12's. Stratum 0, `WORLD`, has no name: only the
+/// WorldFrame's constructor sets it (`0x481aff`).
 pub(crate) fn strata_from_str(s: &str) -> Option<Strata> {
     Some(match enum_token(s).as_str() {
         "BACKGROUND" => Strata::Background,
@@ -293,8 +238,7 @@ pub(super) fn draw_layer_from_str(s: &str) -> Option<DrawLayer> {
     })
 }
 
-/// The inverse of [`draw_layer_from_str`] — the token `GetDrawLayer` answers, in the client's own
-/// spelling (uppercase, the five `<Layer level=>` names).
+/// The inverse of [`draw_layer_from_str`]: the uppercase token `GetDrawLayer` answers.
 pub(super) fn draw_layer_name(l: DrawLayer) -> &'static str {
     match l {
         DrawLayer::Background => "BACKGROUND",
@@ -305,25 +249,16 @@ pub(super) fn draw_layer_name(l: DrawLayer) -> &'static str {
     }
 }
 
-/// A widget tag or `CreateFrame` type string → its [`FrameKind`], case- and separator-insensitive
-/// ([`enum_token`]). Public because it is the ONE mapping: `benilla-app`'s `frame_flag_gate` sweep
-/// needs it to ask the engine whether a tag is mouse-enabled by construction, and a second copy
-/// there is exactly what drifted.
+/// A widget tag or `CreateFrame` type → its [`FrameKind`] ([`enum_token`]). Public so the app asks
+/// this one mapping rather than keeping a copy.
 pub fn frame_kind_from_tag(s: &str) -> Option<FrameKind> {
     frame_kind_from_str(s)
 }
 
-/// **The type registry lookup both doors share** (`0x6ee280`'s table `[0xcee9d8]`, its only
-/// reader) — the tag's [`FrameKind`] if a factory is registered under it right now, else `None`.
-///
-/// "Right now" is the WorldFrame's one-shot: the reference unlinks and releases that record the
-/// moment the first `<WorldFrame>` is instantiated (`0x6ee439`), so a second one — from any XML, or
-/// `CreateFrame("WorldFrame")` — takes the lookup's miss leg (decision 1984).
-///
-/// One function because the two doors disagree only in what a MISS does, never in what a miss is
-/// (decision 2191): the Lua binding raises ([`create_frame`]), the XML loader logs
-/// `"Unknown frame type: %s"` and skips the node (`crate::loader`) — both legs off the same
-/// `0x6ee280`.
+/// The type registry lookup `CreateFrame` and the XML loader share (`0x6ee280`, table
+/// `[0xcee9d8]`): the tag's [`FrameKind`] if a factory is registered for it now. The WorldFrame's
+/// record is released once the first one is made (`0x6ee439`), so a second one misses. On a miss
+/// Lua raises and XML logs `Unknown frame type: %s` and skips the node.
 pub(crate) fn registered_frame_kind(lua: &Lua, kind: &str) -> Option<FrameKind> {
     let frame_kind = frame_kind_from_str(kind)?;
     let one_shot_spent = frame_kind == FrameKind::WorldFrame
@@ -337,33 +272,17 @@ pub(crate) fn registered_frame_kind(lua: &Lua, kind: &str) -> Option<FrameKind>
 fn frame_kind_from_str(s: &str) -> Option<FrameKind> {
     Some(match enum_token(s).as_str() {
         "FRAME" => FrameKind::Frame,
-        // The world frame's own registered type (decision 1983; `0x495948` in the registration
-        // batch, the one row passing `1` as its third argument).
+        // Registered at `0x495948`, the one row passing `1` as its third argument.
         "WORLDFRAME" => FrameKind::WorldFrame,
-        // `TaxiRouteFrame` — a registered `CreateFrame` type that is a `CSimpleFrame` and NOTHING
-        // else, so it maps to `Frame` rather than earning a kind (decision 1828). Factory
-        // `0x495ba0` allocates `0x314`, the same
-        // size the plain-`<Frame>` factory `0x6eec10` allocates for the same base ctor `0x769090`,
-        // and the ctor `0x506950` adds no field. Its vtables are the base's length exactly (36 + 11
-        // slots), so it declares no new virtual; it overrides four slots, of which two are lifetime
-        // plumbing and the other two — `EmitLayer 0x506a60` and a scale hook `0x506ac0` — are DEAD
-        // in 5875: the paint callback `0x506a90` tail-calls `0x506aa0`, which is a bare `ret`, and
-        // every module global it would fill is written by nothing.
-        //
-        // Mapping it to `Frame` is therefore the faithful answer, not a 1203 shortcut — and it is
-        // faithful in the strong sense that `GetObjectType()` must return **"Frame"** and
-        // `IsObjectType("TaxiRouteFrame")` must be **false**: `0x484800` is not overridden, so the
-        // name lives only in the 22-entry tag→factory registry and never becomes a class identity.
-        // The flight-path lines are plain `<Texture>` children the FrameXML creates and rotates
-        // with the 8-argument `SetTexCoord` we already support; `TaxiRouteFrame.cpp` is a vestigial
-        // C++ renderer that draws nothing.
+        // A plain `CSimpleFrame`: factory `0x495ba0` allocates `0x314` like `<Frame>`'s `0x6eec10`,
+        // the ctor `0x506950` adds no field, and its paint `0x506a90` does nothing, so
+        // `GetObjectType()` is "Frame" and `IsObjectType("TaxiRouteFrame")` false (`0x484800` is
+        // not overridden). The flight lines are the FrameXML's own rotated textures.
         "TAXIROUTEFRAME" => FrameKind::Frame,
         "BUTTON" => FrameKind::Button,
         "CHECKBUTTON" => FrameKind::CheckButton,
-        // A real registered type (`0x4959a6`), not an alias for Button — decision 1799. Registering
-        // it AS a Button would load `LootFrame.xml` and leave every row dead, because 1.12 has no
-        // Lua verb for "take slot N": `LootSlot` is the bind-confirm continuation, hard-wired to
-        // `flag = 1`.
+        // Its own registered type (`0x4959a6`), not a Button: 1.12 has no Lua verb to take loot
+        // slot N (`LootSlot` only continues a bind confirm), so a Button row could loot nothing.
         "LOOTBUTTON" => FrameKind::LootButton,
         "EDITBOX" => FrameKind::EditBox,
         "STATUSBAR" => FrameKind::StatusBar,
@@ -393,9 +312,8 @@ pub(super) fn as_f32(v: &Value) -> f32 {
     }
 }
 
-/// [`as_f32`]'s double-width sibling, for the shape-C positions whose store is `f64` — today only
-/// `ColorSelect:SetColorRGB`, whose channels go through a quantizer where a detour via `f32` could
-/// move a value across a rounding boundary (`colorselect`'s module doc).
+/// [`as_f32`] in `f64`, for `ColorSelect:SetColorRGB`, whose quantizer an `f32` detour could push
+/// across a rounding boundary.
 pub(super) fn as_f64(v: &Value) -> f64 {
     match v {
         Value::Number(n) => *n,
@@ -405,42 +323,37 @@ pub(super) fn as_f64(v: &Value) -> f64 {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
-// install — build the method tables, metatables, CreateFrame, and registry roots
+// install
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
-    // The wrapper cache + the per-frame script tables (Lua-side roots — the MAXCSTACK discipline).
+    // The wrapper cache and the per-frame script tables, as registry roots.
     lua.set_named_registry_value(REG_WRAPPERS, lua.create_table()?)?;
     lua.set_named_registry_value(REG_SCRIPTS, lua.create_table()?)?;
 
-    // The Region-map arm collection, opened before either method table is built and closed by
-    // `region_map::install` below (its [`super::region_map::Arms`] doc says why it is app_data).
+    // Opened before any method table is built; `region_map::install` below closes it.
     super::region_map::open_arms(lua);
     install_frame_methods(lua)?;
     super::region::install(lua)?;
     super::statusbar::install(lua)?;
     super::button::install(lua)?;
     super::editbox::install(lua)?;
-    // AFTER every table above exists: collapse the 19 Region-map names to one shared
-    // implementation each, so a method pulled off a frame works on a texture (decision 1501).
+    // After every table above exists: each of the 19 Region-map names gets one shared
+    // implementation, so a method taken off a frame works on a texture.
     super::region_map::install(lua)?;
 
-    // The per-kind metatable cache ([`frame_meta_for`]) and the base metatable in it: the one a
-    // plain `Frame` wears, whose `__index` is the shared frame method table itself.
+    // The per-kind metatable cache, holding the plain `Frame`'s, whose `__index` is the frame
+    // method table.
     lua.set_named_registry_value(REG_KIND_METAS, lua.create_table()?)?;
     let frame_meta = frame_meta_for(lua, None)?;
     lua.set_named_registry_value(REG_FRAME_META, frame_meta.clone())?;
-    // FrameScript init (`0x7039f7`) publishes the shared metatable as _G["__framescript_meta"].
+    // FrameScript init publishes it as `_G["__framescript_meta"]` (`0x7039f7`).
     lua.globals().set("__framescript_meta", frame_meta)?;
 
-    // CreateFrame(kind, name?, parent?, inherits?) — a global (the loader's factory is `0x6ee280`;
-    // this is the runtime one). `inherits` (4th) applies a registered template to the frame this
-    // call just made, through `crate::loader::apply_template`.
     let create_frame = lua.create_function(create_frame)?;
     lua.globals().set("CreateFrame", create_frame)?;
 
-    // GetScreenWidth/Height — the screen-root rect in UI units (the ref's tooltip side-pick reads
-    // them: ContainerFrameItemButton_OnEnter anchors LEFT when the slot sits in the right half).
+    // `GetScreenWidth`/`GetScreenHeight`: the screen root's size in UI units.
     lua.globals().set(
         "GetScreenWidth",
         lua.create_function(|lua, ()| {
@@ -456,14 +369,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetupFullscreenScale(frame) — the registered binding `0x48c270` the stock WorldMapFrame.xml,
-    // CinematicFrame.xml and UIOptionsFrame.xml call from OnShow (decision 1980): the frame's scale
-    // becomes `min(0.75 · a, 1.0)` for the CONFIGURED aspect `a` — the `gxResolution` width over
-    // height (the `widescreen` CVar's default of 1 selects it; at 0 the aspect is 4:3 and the
-    // scale 1) — and nothing else is written: no anchor, size or position, and `UIParent`'s
-    // scale never enters. It is the same `CSimpleFrame::SetScale` the Lua method calls. The
-    // window's aspect is the configured one here (the UI-unit rect keeps the pixel ratio); NaN
-    // takes the 1.0 leg as the reference's `fcomp` does. The three raises are the binding's own.
+    // `SetupFullscreenScale(frame)` (`0x48c270`) sets only the frame's scale, through `SetScale`:
+    // `min(0.75 · a, 1.0)` for the configured aspect `a`, the `gxResolution` width over height,
+    // which is the window's here (the reference's `widescreen` CVar at 0 would make it 4:3).
+    // `UIParent`'s scale does not enter.
     lua.globals().set(
         "SetupFullscreenScale",
         lua.create_function(|lua, frame: Value| {
@@ -488,12 +397,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCursorPosition() → x, y — the last cursor position the host fed (`mouse_move`/
-    // `mouse_button`), UI units y-up like every other coordinate read — the SCREEN's units, which
-    // is what the reference hands Lua too; a caller inside a scaled frame divides by its
-    // `GetEffectiveScale()` (the reference's own `MouseIsOver` does, and the stock world map at
-    // a scale under 1 is the case that made the division load-bearing here — decision 1985). The
-    // world map polls this every OnUpdate for hover/click math.
+    // `GetCursorPosition()`: the last cursor position the host fed, in screen UI units, y up, as
+    // the reference returns it; a caller in a scaled frame divides by its `GetEffectiveScale()`.
     lua.globals().set(
         "GetCursorPosition",
         lua.create_function(|lua, ()| {
@@ -502,15 +407,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The modifier-key mirror ([`UiScript::set_modifiers`], fed by the app's input pass before
-    // any mouse event each frame) — the reference handlers fork on these at click time
-    // (ContainerFrame.lua's shift-split / ctrl-dressup, ActionBarFrame.xml's shift-pickup,
-    // SpellBookFrame.lua's shift-pickup).
-    //
-    // **1/nil, not a Lua boolean.** These three shipped Era booleans on 0068's reasoning that
-    // "every transcribed `if IsShiftKeyDown()` reads both identically" — true while we wrote every
-    // caller, and false the day real 1.12 addons load (1188/1751). `ColorPickerPlus.lua:121` is
-    // `if IsShiftKeyDown() == 1 then`, and a `true` reads there as "not held" (decision 2118).
+    // The modifier keys the app feeds each frame before any mouse event
+    // ([`UiScript::set_modifiers`]), answered 1 or nil as in 1.12, never a boolean: an addon
+    // testing `IsShiftKeyDown() == 1` (`ColorPickerPlus.lua:121`) reads `true` as not held.
     for (name, pick) in [
         ("IsShiftKeyDown", 0usize),
         ("IsControlKeyDown", 1),
@@ -529,36 +428,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// The registry table of per-kind frame metatables, keyed by the head of the kind's method chain
-/// (`""` for a kind with none). Lua-side, like every other root here — the MAXCSTACK discipline.
+/// Registry key of the per-kind frame metatables, each keyed by its kind's first method-table key,
+/// `""` for a kind with none.
 const REG_KIND_METAS: &str = "__benilla_frame_meta_by_kind";
 
-/// The metatable a frame of `kind` wears — built once per kind, cached in [`REG_KIND_METAS`].
-///
-/// ## `__index` is a TABLE, and that is the whole point (decision 2310)
-///
-/// This used to be one shared metatable whose `__index` was a **Rust function** that resolved the
-/// receiver's kind and walked its registries per lookup. Every `frame:SetPoint(...)` — every plain
-/// `frame.Foo` read, including the `if frame.SetValue then` duck-type probe addons open with —
-/// therefore crossed into Rust, took a model borrow, resolved a handle and did one to three
-/// named-registry string lookups. Measured in a release build: **217 ns for a plain Frame, 320 ns
-/// for a Button, against 8.7 ns for a plain Lua table `__index`.** A live sample of a quest-accept
-/// spike with the director's addon set put ~20 % of the whole UI tick inside that metamethod
-/// before any method body ran — Questie redraws its map notes with ~19 widget calls per cluster
-/// over hundreds of clusters, and pays the tax on every one.
-///
-/// A table costs one `luaH_get` inside `luaV_gettable`, in C, with no call at all.
-///
-/// ## The chain is the reference's own, expressed as metatables
-///
-/// 1.12's widget classes are not a Lua metatable chain — each class owns a flat method map and its
-/// lookup tail-calls exactly one base's lookup ([`super::region_map`]'s header has the tables). But
-/// `luaV_gettable` follows a table `__index` iteratively, so a chain of metatables IS that probe
-/// sequence: `CheckButton`'s map, miss, `Button`'s map, miss, `Frame`'s map. So rather than merging
-/// each kind's methods into one flat copy, this links the existing tables — no copies to go stale
-/// when a method table is written after the fact, and the per-kind surface stays exactly what
-/// [`kind_method_registries`] declares. Duck typing is preserved by construction: a plain Frame's
-/// chain never reaches `StatusBar`'s map, so `frame.SetValue` is still nil.
+/// The metatable a frame of `kind` wears, built once per kind and cached in [`REG_KIND_METAS`].
+/// Its `__index` is a table, so a method lookup never leaves `luaV_gettable` for Rust. The kind's
+/// method tables are linked, not merged, in the reference's probe order, each class's lookup
+/// tail-calling its base's (`CheckButton`, `Button`, `Frame`): a later write to a table shows
+/// through, and a plain Frame never reaches `StatusBar`'s methods, so `frame.SetValue` stays nil.
 fn frame_meta_for(lua: &Lua, kind: Option<FrameKind>) -> mlua::Result<Table> {
     let chain = kind_method_registries(kind);
     let key = chain.first().copied().unwrap_or("");
@@ -566,8 +444,7 @@ fn frame_meta_for(lua: &Lua, kind: Option<FrameKind>) -> mlua::Result<Table> {
     if let Value::Table(meta) = metas.raw_get::<Value>(key)? {
         return Ok(meta);
     }
-    // Link `own -> base -> ... -> Frame`, idempotently: a base table shared by several kinds (every
-    // button kind reaches `Button`'s) is simply re-pointed at the same place.
+    // Link `own -> base -> ... -> Frame`; relinking a base several kinds share is idempotent.
     let frame_methods: Table = lua.named_registry_value(REG_FRAME_METHODS)?;
     let mut below = frame_methods.clone();
     for reg in chain.iter().rev() {
@@ -583,15 +460,9 @@ fn frame_meta_for(lua: &Lua, kind: Option<FrameKind>) -> mlua::Result<Table> {
     Ok(meta)
 }
 
-/// The registry keys of a frame's kind-specific method tables, **in resolution order** — the
-/// client's own class chain (CheckButton's lookup `0x79a5d0` tail-calls Button's). Empty for a
-/// plain kind, and for a wrapper whose frame is not live.
-///
-/// Every chain here is *its own table followed by its base's whole chain*, which is what lets
-/// [`frame_meta_for`] realize it as a metatable chain instead of a search: `CheckButton`'s table
-/// gets `Button`'s as its `__index`, `Button`'s gets `Frame`'s, and one `luaV_gettable` walks the
-/// lot in C. Keep that property when adding a kind — a chain that is not a suffix of its base's
-/// cannot be expressed this way.
+/// The registry keys of a kind's own method tables in the client's lookup order (`CheckButton`'s
+/// `0x79a5d0` tail-calls `Button`'s); empty for a plain kind or no live frame. Each chain must be
+/// its own table followed by its base's whole chain, or [`frame_meta_for`] cannot link it.
 fn kind_method_registries(kind: Option<FrameKind>) -> &'static [&'static str] {
     match kind {
         Some(FrameKind::StatusBar) => &[super::statusbar::REG_STATUSBAR_METHODS],
@@ -599,18 +470,14 @@ fn kind_method_registries(kind: Option<FrameKind>) -> &'static [&'static str] {
         Some(FrameKind::ScrollingMessageFrame) => {
             &[super::messageframe::REG_SCROLLINGMESSAGEFRAME_METHODS]
         }
-        // Its SIBLING, with its own table — not a fallthrough to the scrolling one. Until this arm
-        // existed a `<MessageFrame>` resolved no kind-specific method at all, which is what blocked
-        // `EasyCopy`, `QuestHistory` and `QuestItem` on `UIErrorsFrame:AddMessage` (three of the
-        // corpus's six method-class blockers) and made `SetInsertMode` unreachable.
+        // A sibling of `ScrollingMessageFrame` with its own table, not a fallthrough to it.
         Some(FrameKind::MessageFrame) => &[super::messageframe::REG_MESSAGEFRAME_METHODS],
         Some(FrameKind::ScrollFrame) => &[super::scrollframe::REG_SCROLLFRAME_METHODS],
         Some(FrameKind::SimpleHtml) => &[super::simplehtml::REG_SIMPLEHTML_METHODS],
         Some(FrameKind::Slider) => &[super::slider::REG_SLIDER_METHODS],
         Some(FrameKind::ColorSelect) => &[super::colorselect::REG_COLORSELECT_METHODS],
         Some(FrameKind::Button) => &[super::button::REG_BUTTON_METHODS],
-        // One method of its own, then all of Button's — the miss order of `0x4c1be0`, which probes
-        // its own 1-entry map `0xb71b64` and tail-calls `Button`'s `0x782c90`.
+        // Its one method, then `Button`'s: `0x4c1be0` probes its map `0xb71b64`, then `0x782c90`.
         Some(FrameKind::LootButton) => &[
             super::loot::REG_LOOTBUTTON_METHODS,
             super::button::REG_BUTTON_METHODS,
@@ -619,27 +486,20 @@ fn kind_method_registries(kind: Option<FrameKind>) -> &'static [&'static str] {
             super::button::REG_CHECKBUTTON_METHODS,
             super::button::REG_BUTTON_METHODS,
         ],
-        // The Model pane's own surface. Its absence is what stopped pfUI — and, through pfUI's
-        // embedded copies, pfQuest, pfQuest-turtle and ShaguDPS — on `SetModel` after the whole
-        // rest of their UI had already built (`super::modelframe`'s header).
         Some(FrameKind::Model) => &[super::modelframe::REG_MODEL_METHODS],
-        // The chain, not a repetition: `CGCharacterModelBase`'s lookup `0x506260` probes its own
-        // 3-entry map and on a miss tail-calls `CSimpleModel`'s `0x76f870`. Order is the miss
-        // order — three names of its own, then all 23 of `Model`'s.
+        // Its 3 methods, then `Model`'s 23: `0x506260` misses into `0x76f870`.
         Some(FrameKind::PlayerModel) => &[
             super::modelframe::REG_PLAYERMODEL_METHODS,
             super::modelframe::REG_MODEL_METHODS,
         ],
-        // Three of its own, then PlayerModel's three, then Model's 23: `CGDressUpModelFrame`'s
-        // lookup probes `0x84f190` and misses into `CGCharacterModelBase`'s `0x506260`, which
-        // misses into `CSimpleModel`'s `0x76f870` (1969).
+        // 3 of its own (`0x84f190`), then `PlayerModel`'s 3 (`0x506260`), then `Model`'s 23
+        // (`0x76f870`).
         Some(FrameKind::DressUpModel) => &[
             super::dressup::REG_DRESSUPMODEL_METHODS,
             super::modelframe::REG_PLAYERMODEL_METHODS,
             super::modelframe::REG_MODEL_METHODS,
         ],
-        // Ten of its own (`0x84ee40`), then PlayerModel's three, then Model's 23 — the same
-        // derived → base probe as its sibling (1977).
+        // 10 of its own (`0x84ee40`), then `PlayerModel`'s 3, then `Model`'s 23.
         Some(FrameKind::TabardModel) => &[
             super::tabard::REG_TABARDMODEL_METHODS,
             super::modelframe::REG_PLAYERMODEL_METHODS,
@@ -651,57 +511,30 @@ fn kind_method_registries(kind: Option<FrameKind>) -> &'static [&'static str] {
     }
 }
 
-/// `CreateFrame(kind, name?, parent?, inherits?)` — the runtime frame factory.
-///
-/// The fourth argument is a **template name list**, and honouring it is what makes
-/// `CreateFrame("Button", "MyButton", UIParent, "UIPanelButtonTemplate")` — the corpus's most
-/// common single line — produce a button with art, regions, scripts and a fired `OnLoad` rather
-/// than an empty frame. The frame is created first and decorated second
-/// ([`crate::loader::apply_template`]), in that order and never the other way: the template's own
-/// `OnLoad` must be able to see the frame's real name, and `$parent` inside the template must
-/// resolve against **the caller's** name, not the template's.
-///
-/// An **unresolvable** template name raises `CreateFrame(): Couldn't find inherited node "%s"` and
-/// creates nothing — the reference's own behaviour, byte-verified (`0x7061dd` → `luaL_error`, which
-/// never returns). A template that resolves but is *unusable in some other way* — declared without
-/// `virtual="true"`, or of a shape that does not fit the kind asked for — is still a warning plus a
-/// working frame, because the registry lookup itself succeeded and that is the only thing the miss
-/// branch tests.
+/// `CreateFrame(kind, name?, parent?, inherits?)` (`0x7060b0`), the runtime frame factory.
+/// `inherits` names one template, applied after the frame is made
+/// ([`crate::loader::apply_template`]) so its `OnLoad` sees the frame's real name and its `$parent`
+/// resolves against the caller's name. An unknown template raises `Couldn't find inherited node`
+/// and creates nothing (`0x7061dd`); a known but unusable one (not virtual, or the wrong shape)
+/// only warns, since the lookup itself succeeded.
 pub(super) fn create_frame(
     lua: &Lua,
     (kind, name, parent, inherits): (String, Option<Value>, Option<Value>, Option<Value>),
 ) -> mlua::Result<Table> {
-    // The Lua door's miss RAISES: `0x7060b0` reaches `"CreateFrame: Unknown frame type '%s'"`
-    // (`0x872fa8`) through `luaL_error 0x6f4940`, which never returns. The XML door's does not —
-    // see [`registered_frame_kind`].
+    // An unknown type raises. The reference's message (`0x872fa8`) capitalises `Unknown`, and it
+    // tests the template first (`0x7061dd`), raising for the type only at `0x7062a0`.
     let frame_kind = registered_frame_kind(lua, &kind)
         .ok_or_else(|| mlua::Error::runtime(format!("CreateFrame: unknown frame type '{kind}'")))?;
-    // **`name` and `inherits` are `lua_tostring` positions, and a NUMBER is a string to it.**
-    // `0x7060b0` reads both through `0x6f3690` with no type guard at all, so `CreateFrame("Frame",
-    // 5)` names the frame `"5"` — a `Value::String`-only match drops it.
-    //
-    // The fourth argument's quirk, which is real and reads like a bug in the client: `lua_tostring`
-    // runs at `0x70613f` **before** the `cmp 4` gate, and `0x6f7cb1 mov dword ptr [esi],0x4`
-    // retags the number's stack slot **in place** — so by the time the tag is tested it IS a
-    // string. `CreateFrame("Frame", nil, nil, 5)` therefore raises `Couldn't find inherited node
-    // "5"`, while `f:CreateTexture(nil, nil, 5)` silently ignores the 5, because the region
-    // constructors ask `lua_type` first and never coerce. Same value, opposite outcome, decided by
-    // argument order alone — which is why this is spelled out rather than shared with them.
+    // `name` and `inherits` go through `lua_tostring` (`0x6f3690`) unguarded, so a number is a
+    // string: `CreateFrame("Frame", 5)` names the frame "5". For `inherits` the conversion runs
+    // before the string-type gate and retags the slot (`0x70613f`, `0x6f7cb1`), so a number there
+    // raises as a missing template, where `CreateTexture` ignores one.
     let name: Option<String> = name.as_ref().and_then(|v| optional_string(lua, v));
     let template: Option<String> = inherits.as_ref().and_then(|v| optional_string(lua, v));
 
-    // Resolve the parent handle (a wrapper table, or a name string) under a short read borrow.
-    //
-    // **The name-string arm is OURS, and the reference RAISES on it** — `0x7060b0` asks
-    // `lua_type` three times and `cmp eax,5`: a table is the parent, nil/absent means no parent,
-    // and a string takes the error leg.
-    //
-    // It is **parked, not pruned**, on the same footing as `TEXTURE_ONLY_METHODS`' tail three: it
-    // is known to raise, but the exact message was never quoted, and inventing the text of a
-    // client error is exactly what decision 1721 was written about — a plausible string in the
-    // voice of a finding. Measured meanwhile: **zero** call sites pass a string parent, in the
-    // 109-folder corpus or in our own FrameXML, so the superset is unreachable in practice and
-    // removing it blind would buy nothing. Pruning it needs the message, not more confidence.
+    // A table is the parent and a name string is looked up; anything else is no parent. The
+    // reference raises `Usage: CreateFrame(...)` (`0x872f60`) for anything but a table or nil
+    // (`0x706112`).
     let parent_handle: Option<FrameHandle> = {
         let model = lua.app_data_ref::<Model>().expect("model app_data");
         match &parent {
@@ -713,10 +546,8 @@ pub(super) fn create_frame(
         }
     };
 
-    // A 4th argument that is present but neither a string nor a number is **silently ignored by
-    // the reference** — `lua_tostring` returns NULL for it and the `cmp 4` gate then falls into
-    // the ordinary construction path. So this is a benilla-only diagnostic and stays a WARNING,
-    // never a raise: it tells a reader something was dropped without changing what runs.
+    // The reference silently ignores a fourth argument that is neither string nor number
+    // (`0x7061cb`); the warning is ours and changes nothing.
     if template.is_none() {
         if let Some(v) = inherits.as_ref().filter(|v| !v.is_nil()) {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -729,30 +560,15 @@ pub(super) fn create_frame(
         }
     }
 
-    // ── THE TEMPLATE LOOKUP HAPPENS HERE — before anything is constructed or published ──────────
-    //
-    // `0x7061dd` calls the registry lookup `0x6ee6f0` and, on NULL, falls into
-    // `luaL_error(L, "CreateFrame(): Couldn't find inherited node \"%s\"")` at `0x7061ed`. That
-    // never returns — `luaG_errormsg`/`luaD_throw` contain no `ret` at all and end in `longjmp`, so
-    // the `xor eax,eax; ret` after the call is dead code. The frame is **not created**, no global
-    // is published, and the calling statement is abandoned; the error is ordinary Lua propagation
-    // and `pcall`-catchable, which is how the widget dispatcher (`0x704f10`, every handler under
-    // `lua_pcall`) turns it into one dead handler rather than a dead client.
-    //
-    // We used to warn and hand back a usable bare frame, and the doc above said the reference
-    // "creates the frame anyway". That claim is refuted at the bytes. It is the same class as 1249:
-    // a failure the client reports and we swallowed — and swallowing is the worse half, because the
-    // addon then runs on a frame with none of the art, regions or scripts it asked for and fails
-    // later, somewhere unrelated.
-    //
-    // Ordering is the pinned part, not a detail: the miss branch precedes the synthetic-node build
-    // (`0x706208`) and the `name` store (`0x70622d`), so a miss leaves no partial widget and no
-    // orphan global behind. Doing this after construction would leave both.
+    // The template lookup comes before anything is built: a miss (`0x7061dd` → `0x6ee6f0`) raises
+    // at `0x7061ed`, before the node build (`0x706208`) and the name store (`0x70622d`), so it
+    // leaves no partial widget and no global. The raise never returns and `pcall` catches it, as
+    // the widget dispatcher (`0x704f10`) does for every handler.
     if let Some(t) = template.as_deref().filter(|t| !t.is_empty()) {
         let known = {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             let templates = model.framexml_templates.borrow();
-            // One name, verbatim, folded — the law `framexml::expand` resolves under.
+            // One name, verbatim, case-folded, as `framexml::expand` resolves it.
             templates.contains_key(t) || templates.keys().any(|k| k.eq_ignore_ascii_case(t))
         };
         if !known {
@@ -762,19 +578,9 @@ pub(super) fn create_frame(
         }
     }
 
-    // **A leading `$parent` in the NAME is expanded, here as in XML.** `CreateFrame 0x7060b0`
-    // does not store the name itself: it builds a synthetic node, sets `name=` on it
-    // (`0x706225 push 0x838090 "name"` → `0x70622d` SetAttribute) alongside `parent=` and
-    // `inherits=`, and hands it to the XML frame builder `0x6ee280` with the parent object in
-    // `edx` — so the name reaches `CScriptRegion::SetName 0x76c650` by exactly the route an XML
-    // `name=` does, and `0x76c691` is one of the expander's two call sites.
-    //
-    // The base is the frame's **parent's** first named ancestor — the same walk `$parent` in a
-    // `relativeTo` takes, one link higher than the anchoring frame's own.
-    //
-    // Not academic: `FonzAppraiser` names every widget it builds this way (`"$parentDropdown"..n`,
-    // `"$parentCloseButton"`, ~30 sites), and until decision 2176 made an unresolvable anchor
-    // raise, the unexpanded name only showed up as a warning nobody read.
+    // A leading `$parent` in the name expands as in XML: `CreateFrame` sets `name=` on a synthetic
+    // node (`0x70622d`) for the XML builder `0x6ee280`, so the name reaches `SetName` (`0x76c650`),
+    // whose `0x76c691` call expands it against the parent's first named ancestor.
     let name = name.map(|n| {
         let model = lua.app_data_ref::<Model>().expect("model app_data");
         crate::framexml::resolve_name(&n, &parent_token_base(&model, parent_handle))
@@ -787,12 +593,8 @@ pub(super) fn create_frame(
         if frame_kind == FrameKind::WorldFrame {
             model.world_frame_made = true;
         }
-        // The client's CreateFrame inheritance (the ctor doc's "loader/CreateFrame concern" —
-        // widget/mod.rs `create`): a child enters its PARENT's stratum at the parent's level + 1.
-        // The ctor's bare MEDIUM/0 left a DIALOG-strata popup drawing its own translucent
-        // backdrop OVER its buttons (the children stayed in MEDIUM — the abandon dialog's dark
-        // buttons, pixel-diffed against the raw art). An explicit frameStrata/frameLevel attr
-        // still overrides right after (apply_attrs).
+        // A child enters its parent's stratum at the parent's level + 1; an explicit
+        // `frameStrata` or `frameLevel` still overrides it afterwards.
         if let Some(p) = parent_handle {
             if let Some((pstrata, plevel)) = model.arena.frame(p).map(|f| (f.strata, f.level)) {
                 model.arena.set_frame_strata(h, pstrata);
@@ -804,10 +606,8 @@ pub(super) fn create_frame(
         id
     };
 
-    // The wrapper exists (and, if named, is published to `_G`) BEFORE the template runs — a
-    // template's `OnLoad` fires inside this call, and the reference's addons rely on both facts:
-    // `local b = CreateFrame(...)` hands back a frame whose OnLoad has already run, and that
-    // handler can reach itself by name.
+    // The wrapper exists, published under its name, before the template's `OnLoad` runs inside
+    // this call, so the handler can reach the frame by name.
     let wrapper = frame_wrapper(lua, id)?;
     if let Some(template) = template {
         let messages = crate::loader::apply_template(lua, &wrapper, &kind, &template);
@@ -822,11 +622,10 @@ pub(super) fn create_frame(
 }
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
-// Frame method surface — the table itself is built by the three clusters above
+// Frame method surface
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
-/// Build the shared frame method table from the five clusters ([`frame_state`], [`layout_methods`],
-/// [`events_regions`], [`movable`], [`toplevel`]) and publish it to the registry.
+/// Build the shared frame method table from its five clusters and publish it to the registry.
 fn install_frame_methods(lua: &Lua) -> mlua::Result<()> {
     let m = lua.create_table()?;
     frame_state::install(lua, &m)?;
@@ -838,8 +637,8 @@ fn install_frame_methods(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// `0x48c270`'s law: `g = 0.75 · aspect`, and the scale is `g` below 1.0, else 1.0 — NaN lands on
-/// the 1.0 leg (the `fcomp` compare fails every ordered test).
+/// `0x48c270`'s scale: `0.75 · aspect` below 1.0, else 1.0; NaN takes the 1.0 leg, as the
+/// reference's `fcomp` fails every ordered test.
 pub(crate) fn fullscreen_scale(aspect: f32) -> f32 {
     let g = 0.75 * aspect;
     if g < 1.0 {
diff --git a/crates/benilla-ui/src/script/object/anchor_args.rs b/crates/benilla-ui/src/script/object/anchor_args.rs
index e39526a7..fade7e05 100644
--- a/crates/benilla-ui/src/script/object/anchor_args.rs
+++ b/crates/benilla-ui/src/script/object/anchor_args.rs
@@ -1,22 +1,6 @@
-//! `SetPoint`/`SetAllPoints`' argument ladder — **one** transcription of `0x7a2540` / `0x7a2940`.
-//!
-//! The two bindings are `CScriptRegion` methods registered **once**, at `.data 0x87ca38` and
-//! `0x87ca40` inside the 19-record table `[0x87c9b8, 0x87ca50)` whose registrar `0x7a2e70` supplies
-//! base and count — so Frame, Texture, FontString and Model all run the *same* function
-//! (`0x7a2540`/`0x7a2940`). This module is that single function's argument half; what each caller
-//! keeps for itself is only the thing the reference reads off the receiver — the layout parent's
-//! default id, and where the anchor is stored.
-//!
-//! **Every failure leg RAISES**, which is the point of the module (decision 2176, closing 2105's
-//! "Named, not done"). `luaL_error` does not return: `luaG_errormsg [0x6fc780,0x6fc861)` and
-//! `luaD_throw [0x6f5d80,0x6f5da5)` hold zero `ret`s, and `luaD_throw`'s *elided* epilogue is the
-//! positive control that says so. There is no fallback and no silent no-op on any of them.
-//!
-//! The **XML** `<Anchor relativeTo=>` path is a different function and a different law — it
-//! resolves through the same `0x76c700` but reports `"Couldn't find relative frame: %s"` at
-//! severity 1 and **skips the anchor** (`0x767969 test ebx,ebx` → `0x76796d` → `jmp 0x7679dd`,
-//! past the `0x7679c8 call 0x767c70`). That half lives in `crate::loader::geometry`, which
-//! therefore resolves its own names and never reaches the ladder here.
+//! The argument ladder of `SetPoint` (`0x7a2540`) and `SetAllPoints` (`0x7a2940`): the reference
+//! registers both once, in the Region method table (`0x87c9b8`), so every widget type runs the
+//! same function. Every failure leg raises; none falls back to the parent or does nothing.
 
 use mlua::{Lua, MultiValue, Table, Value};
 
@@ -25,30 +9,19 @@ use crate::script::{Model, SCREEN};
 
 use super::{decode_id, point_from_str, prefetch_named_target, resolve_named_target, NamedTarget};
 
-/// What the reference prints where a widget has no name — the literal `0x84c7f0`, reached from
-/// `call [primary_vt+0x4]` (`GetName` → `[widget+0x98]`) returning NULL.
+/// The name the reference prints for a widget that has none (the literal at `0x84c7f0`).
 pub(crate) const UNNAMED: &str = "<unnamed>";
 
-/// `relativeTo`, decoded — the four tags `lua_type(L,3)` accepts (`0x7a25e6`–`0x7a2620`); anything
-/// else, **absent included** (`TNONE` = −1), is a Usage raise on the `SetPoint` side.
+/// `relativeTo` by the four tags `lua_type(L,3)` accepts (`0x7a25e6`..`0x7a2620`); any other tag,
+/// absent included, raises Usage in `SetPoint`.
 pub(crate) enum RelTarget {
-    /// A widget wrapper table (`0x7a26c9`: `rawgeti(3,0)` → `touserdata` → `+0x24`).
-    ///
-    /// **The reference runs no `IsA` check on this arm** — unlike the `this` ladder and unlike the
-    /// string arm, whose check lives inside `0x76c760` — so `add eax,0x24` is applied to whatever
-    /// `lua_touserdata` returned and a table carrying any light userdata at `[0]` is accepted as a
-    /// widget. That is a wild pointer, not a behaviour: [`resolve_rel_target`] takes the layout
-    /// parent for a table that decodes to no live widget, and says so there.
+    /// A widget wrapper table (`0x7a26c9`); the reference runs no `IsA` check on it.
     Wrapper(Table),
     /// A name string, already read out of `_G` with no `Model` guard alive ([`NamedTarget`]).
     Named(NamedTarget),
-    /// An explicit `nil` — the **screen root** `ds:[0xcf0bd8]` (`0x7a2710`), *not* the parent. One
-    /// stock site takes it (`UIParent.lua:1549`) and fourteen corpus sites do, every one of them
-    /// meaning "the screen" (`pfUI`'s screenshot caption, `FixCTGroups`' cursor-space plate).
+    /// An explicit `nil`: the screen root `ds:[0xcf0bd8]` (`0x7a2710`), not the parent.
     Screen,
-    /// A NUMBER in the `relativeTo` slot: `edi` stays 3 and the number is `offsetX` — the
-    /// `SetPoint(point, x, y)` shorthand (`0x7a270e`). `relativeTo` keeps the layout parent's
-    /// default (`0x76c6e0`: `[+0x9c]`'s layout sub-object, else the screen root).
+    /// A number: the `SetPoint(point, x, y)` shorthand (`0x7a270e`), against the default parent.
     DefaultParent,
 }
 
@@ -61,7 +34,7 @@ pub(crate) struct PointArgs {
     pub(crate) y: f32,
 }
 
-/// `Usage: %s:SetPoint(…)` — `luaL_error(0x87cc28)`, the string read out of the reference image.
+/// The reference's `Usage:` raise (`0x87cc28`).
 fn usage(who: &str) -> mlua::Error {
     mlua::Error::runtime(format!(
         "Usage: {who}:SetPoint(\"point\" [, region or nil] [, \"relativePoint\"] \
@@ -69,28 +42,24 @@ fn usage(who: &str) -> mlua::Error {
     ))
 }
 
-/// `%s:SetPoint(): Unknown region point` — `0x87cd04`, raised by the 9-entry name scan `0x6f1840`
-/// for either the `point` or a `relativePoint` that is a string it rejects.
+/// `0x87cd04`: the point-name scan `0x6f1840` rejected `point` or a string `relativePoint`.
 fn unknown_point(who: &str) -> mlua::Error {
     mlua::Error::runtime(format!("{who}:SetPoint(): Unknown region point"))
 }
 
-/// `%s:%s(): Couldn't find region named '%s'` — `0x87ccd4` for `SetPoint`, `0x87cd84` for
-/// `SetAllPoints`. **No fallback and no no-op**: this is the leg benilla answered with the parent
-/// plus a warning until 2176.
+/// `0x87ccd4` for `SetPoint`, `0x87cd84` for `SetAllPoints`: a raise, never a fallback.
 pub(crate) fn no_such_region(who: &str, verb: &str, name: &str) -> mlua::Error {
     mlua::Error::runtime(format!(
         "{who}:{verb}(): Couldn't find region named '{name}'"
     ))
 }
 
-/// `%s:%s(): trying to anchor to itself` — `0x87cca8` / `0x87cd54`, the `[ebp-4] == this+0x24`
-/// compare at `0x7a2764` / `0x7a2aa8`.
+/// `0x87cca8` / `0x87cd54`, from the self compare at `0x7a2764` / `0x7a2aa8`.
 fn anchor_to_self(who: &str, verb: &str) -> mlua::Error {
     mlua::Error::runtime(format!("{who}:{verb}(): trying to anchor to itself"))
 }
 
-/// `lua_isnumber 0x6f34d0` — a number, or a string Lua can read as one.
+/// `lua_isnumber` (`0x6f34d0`): a number, or a string Lua reads as one.
 fn as_number(lua: &Lua, v: &Value) -> Option<f32> {
     lua.coerce_number(v.clone())
         .ok()
@@ -98,7 +67,7 @@ fn as_number(lua: &Lua, v: &Value) -> Option<f32> {
         .map(|n| n as f32)
 }
 
-/// `lua_isstring 0x6f3510` — tag 4 **or** 3, so a number is a string here.
+/// `lua_isstring` (`0x6f3510`): a string or a number.
 fn as_string(lua: &Lua, v: &Value) -> Option<String> {
     match v {
         Value::String(_) | Value::Number(_) | Value::Integer(_) => lua
@@ -110,29 +79,20 @@ fn as_string(lua: &Lua, v: &Value) -> Option<String> {
     }
 }
 
-/// Parse `SetPoint(point [, relativeTo [, relativePoint]] [, x, y])` in the reference's own order:
-/// the two tag gates first (both Usage), then the point-name scan, then `relativePoint`, then the
-/// offsets. The order is observable — an unknown point with an *absent* `relativeTo` raises Usage,
-/// not "Unknown region point".
-///
-/// `who` names the receiver for the error strings, and `parent_base` is what a leading `$parent`
-/// expands to. Both are the caller's to compute, under a short `Model` borrow, **before** this
-/// runs: the `_G` read here is a `lua_gettable` and an `__index` on `_G` can call straight back
-/// into a binding ([`NamedTarget`]).
+/// Parse `SetPoint` in the reference's order: both tag gates (Usage), the point-name scan,
+/// `relativePoint`, the offsets; so an unknown point with no `relativeTo` raises Usage. The caller
+/// computes `who` and `parent_base` first, since an `__index` on `_G` can call back into a binding.
 pub(crate) fn parse_set_point(
     lua: &Lua,
     args: &MultiValue,
     who: &str,
     parent_base: &str,
 ) -> mlua::Result<PointArgs> {
-    // arg 2 = point. `lua_isstring(L,2)` false → `0x7a290d` Usage (`0x7a25d2`).
     let point_str = args.front().and_then(|v| as_string(lua, v));
     let Some(point_str) = point_str else {
         return Err(usage(who));
     };
 
-    // arg 3 = relativeTo. `lua_type(L,3)` ∈ {4 STRING, 5 TABLE, 0 NIL, 3 NUMBER}, else Usage —
-    // and an **absent** argument is `TNONE` = −1, which fails all four (`0x7a25e6`–`0x7a2620`).
     let Some(rel_arg) = args.get(1) else {
         return Err(usage(who));
     };
@@ -147,13 +107,10 @@ pub(crate) fn parse_set_point(
         _ => return Err(usage(who)),
     };
 
-    // The point name, scanned by `0x6f1840` only now (`0x7a264a`) — after both tag gates.
     let point = point_from_str(&point_str).ok_or_else(|| unknown_point(who))?;
 
-    // `relativePoint` is seeded from `point` (`0x7a2697`) and read at index `edi`, which the
-    // number arm above left at 3 and every other arm advanced to 4. **Only a STRING is consumed**
-    // (`0x7a2810 lua_type == 4`, strictly — not `lua_isstring`); anything else leaves the seed and
-    // the offsets are taken from here.
+    // `relativePoint` defaults to `point` (`0x7a2697`) and is consumed only when strictly a string
+    // (`0x7a2810`), else the offsets start here; the number arm reads one slot earlier.
     let mut cur = if matches!(target, RelTarget::DefaultParent) {
         1
     } else {
@@ -166,8 +123,7 @@ pub(crate) fn parse_set_point(
         cur += 1;
     }
 
-    // **Both offsets, or neither** (`0x7a2888 je 0x7a28e6`): each is gated on `lua_isnumber`, and
-    // one failing zeroes the pair rather than only itself.
+    // Both offsets or neither: one failing `lua_isnumber` zeroes both (`0x7a2888` → `0x7a28e6`).
     let (x, y) = match (
         args.get(cur).and_then(|v| as_number(lua, v)),
         args.get(cur + 1).and_then(|v| as_number(lua, v)),
@@ -185,20 +141,13 @@ pub(crate) fn parse_set_point(
     })
 }
 
-/// Parse `SetAllPoints([relativeTo])` (`0x7a2940`) — **the same resolver, a different argument
-/// law**, and the three differences are per-binding facts rather than a family rule:
-///
-/// 1. An **omitted** argument is legal: it falls through to the layout parent with no raise, where
-///    `SetPoint` raises Usage.
-/// 2. The name path is gated on **`lua_isstring`** (`0x7a29ea`), tag 4 **or** 3 — so
-///    `f:SetAllPoints(42)` stringifies and looks up `_G["42"]`, where `SetPoint` tests
-///    `lua_type == 4` strictly and routes a number to the offset shorthand.
-/// 3. There is no `relativePoint` or offset parsing at all.
+/// Parse `SetAllPoints([relativeTo])` (`0x7a2940`). Unlike `SetPoint`, an omitted argument takes
+/// the layout parent, and a number is a name (`lua_isstring`, `0x7a29ea`): `SetAllPoints(42)`
+/// looks up `_G["42"]`.
 pub(crate) fn parse_set_all_points(lua: &Lua, arg: Option<&Value>, parent_base: &str) -> RelTarget {
     match arg {
         Some(Value::Table(t)) => RelTarget::Wrapper(t.clone()),
         Some(Value::Nil) => RelTarget::Screen,
-        // `lua_isstring` — a NUMBER takes the name path here, unlike `SetPoint`.
         Some(v) => match as_string(lua, v) {
             Some(n) => RelTarget::Named(prefetch_named_target(lua, &n, Some(parent_base))),
             None => RelTarget::DefaultParent,
@@ -207,11 +156,9 @@ pub(crate) fn parse_set_all_points(lua: &Lua, arg: Option<&Value>, parent_base:
     }
 }
 
-/// Turn a parsed [`RelTarget`] into the layout id to anchor against, raising the reference's own
-/// errors. `me` is the receiver's own id — the self-anchor compare (`0x7a2764` / `0x7a2aa8`).
-///
-/// The **wrapper** arm takes `default_parent` where the reference would take a wild pointer (see
-/// [`RelTarget::Wrapper`]); every other arm is the reference's.
+/// Resolve a [`RelTarget`] to the layout id to anchor to, raising the reference's errors; `me` is
+/// the receiver, for the self-anchor check. Deviation: a wrapper that decodes to no live widget
+/// takes `default_parent`, because the reference, with no `IsA` check, reads a wild pointer.
 pub(crate) fn resolve_rel_target(
     model: &Model,
     target: &RelTarget,
@@ -237,25 +184,14 @@ pub(crate) fn resolve_rel_target(
     Ok(id)
 }
 
-/// The **XML** `<Anchor relativeTo="name">` resolution — `CLayoutFrame::LoadXML 0x767800`'s own,
-/// which is a different law from the Lua ladder above and belongs to `crate::loader`.
-///
-/// `0x767964 call [eax+0x28]` is the same `0x76c700` the Lua string arm uses, so the *lookup* is
-/// identical; what differs is the miss. `0x767969 test ebx,ebx` → `0x76796d` pushes
-/// `0x878440 "Couldn't find relative frame: %s"` at severity 1 through the XML report's
-/// `[ecx+0xc]` and then `jmp 0x7679dd`, which lands **past** the `0x7679c8 call 0x767c70` — the
-/// anchor is reported and SKIPPED. It does not raise (there is no Lua state to unwind here) and it
-/// does not fall back to the parent, which is what benilla did until 2176.
-///
-/// `$parent` is already expanded by the caller, so no base is taken.
+/// The XML `<Anchor relativeTo>` lookup (`CLayoutFrame::LoadXML 0x767800`), `$parent` already
+/// expanded: the Lua string arm's resolver (`0x76c700`), but a miss reports "Couldn't find
+/// relative frame" (`0x878440`) and skips the anchor (`0x767969`) without raising or falling back.
 pub(crate) fn resolve_xml_relative_to(lua: &Lua, name: &str) -> Option<Table> {
-    // ONE `_G` read, and the wrapper it produced is the one handed back — re-reading `_G` to fetch
-    // the table again would be a second `lua_gettable`, and an `__index` is allowed to answer
-    // twice differently.
+    // One `_G` read, its wrapper returned: an `__index` may answer a second read differently.
     let nt = prefetch_named_target(lua, name, None);
     let model = lua.app_data_ref::<Model>().expect("model");
     resolve_named_target(&model, &nt)?;
-    // The wrapper the ladder's TABLE arm takes — resolved here so the binding never sees a name
-    // from the XML path and so its raise can never reach a loading document.
+    // A wrapper, not a name, so the Lua ladder's raise can never reach a loading document.
     nt.wrapper.clone()
 }
diff --git a/crates/benilla-ui/src/script/object/events_regions.rs b/crates/benilla-ui/src/script/object/events_regions.rs
index 06894d38..750d880f 100644
--- a/crates/benilla-ui/src/script/object/events_regions.rs
+++ b/crates/benilla-ui/src/script/object/events_regions.rs
@@ -1,8 +1,4 @@
-//! Frame method-table cluster: event registration + script handlers (`RegisterEvent`/
-//! `UnregisterEvent`/`SetScript`/`GetScript`), the drag-gesture registration (`RegisterForDrag`,
-//! decision 0216 §3), and region creation (`CreateTexture`/`CreateFontString`). Split out of
-//! [`super`] purely for size — see its module doc for the shared id/handle plumbing and
-//! method-table wiring.
+//! Frame methods: event registration, script handlers, drag registration and region creation.
 
 use std::collections::HashSet;
 
@@ -15,7 +11,7 @@ use crate::widget::RegionKind;
 
 use super::{decode_id, draw_layer_from_str, frame_handle_of, publish_global};
 
-/// Populate `m`'s event/script and region-creation methods (see the module doc).
+/// Populate `m`'s event, script and region-creation methods.
 pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
     // Events + scripts
     m.set(
@@ -23,8 +19,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         lua.create_function(|lua, (this, event): (Table, String)| {
             let h = frame_handle_of(lua, &this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
-            // Ordered listener list (the client's SignalEvent walks a LIST — order is law);
-            // re-register keeps the original position (no duplicate fire).
+            // Dispatch follows registration order, as the reference's listener list does; a
+            // re-register keeps its place and never fires twice.
             let list = model.event_to_frames.entry(event.clone()).or_default();
             if !list.contains(&h) {
                 list.push(h);
@@ -47,59 +43,32 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // `RegisterAllEvents()` — this frame's `OnEvent` receives EVERY event that is dispatched
-    // (`0x774c20`, table `0x878ec0`, argc 1, arity 0). Cleared by `UnregisterAllEvents` below, and
-    // by nothing else: there is no `UnregisterAllEvents`-less way back out, which is exactly how
-    // the reference's pair reads.
-    //
-    // **Latent, not live, and the widest-carried gap the corpus census found.** Nothing in either
-    // addon corpus calls it *today*, but 63 vanilla addons and 6 of the top 20 ship
-    // **AceEvent-2.0**, whose `AceEvent:RegisterAllEvents(handler)` runs
-    // `AceEvent.frame:RegisterAllEvents()` the first time any addon asks for all events — so the
-    // first one that does raised here. AceEvent is also why the *clearing* half is load-bearing
-    // rather than tidy: while all-events is on it deliberately stops calling
-    // `frame:UnregisterEvent(event)` at all, and `AceEvent:UnregisterAllEvents()` gets back to a
-    // per-event registration by calling `frame:UnregisterAllEvents()` and then re-registering each
-    // event it still wants. A `RegisterAllEvents` that outlived that call would leave every Ace2
-    // addon on the whole event stream forever.
-    //
-    // Registered as a FLAG (the frame joins `Model::all_event_frames`), never as an expansion into
-    // a name list — see that field for why, and `tick::fire_event_into` for the dispatch.
+    // `RegisterAllEvents()` (`0x774c20`): the frame's `OnEvent` receives every event until
+    // `UnregisterAllEvents`, the only way out. A flag (`Model::all_event_frames`), not a name list.
     m.set(
         "RegisterAllEvents",
         lua.create_function(|lua, this: Table| {
             let h = frame_handle_of(lua, &this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
-            // Registration order, and re-registering keeps the original position — the same law
-            // `RegisterEvent` above holds, for the same reason.
             if !model.all_event_frames.contains(&h) {
                 model.all_event_frames.push(h);
             }
             Ok(())
         })?,
     )?;
-    // `UnregisterAllEvents()` — drop every registration this frame holds, in one call.
-    //
-    // 10 corpus addons stop on it (decision 1195), and the idiom is why: an addon's "disable me"
-    // path is `self.frame:UnregisterAllEvents()`, and a library that pools frames calls it before
-    // handing one out. Unregistering them one by one is not equivalent — the caller does not know
-    // what it registered, which is the whole point of the verb.
+    // `UnregisterAllEvents()`: drops every registration the frame holds.
     m.set(
         "UnregisterAllEvents",
         lua.create_function(|lua, this: Table| {
             let h = frame_handle_of(lua, &this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
-            // Take the frame's OWN set first, then walk only the events it actually held — the
-            // alternative (sweeping every listener list in the model) is O(all events) per call,
-            // and libraries call this in loops over a frame pool.
             let events = model.frame_events.remove(&h).unwrap_or_default();
             for event in events {
                 if let Some(list) = model.event_to_frames.get_mut(&event) {
                     list.retain(|x| x != &h);
                 }
             }
-            // …and the all-events registration, which is a registration like any other. See
-            // `RegisterAllEvents` above: AceEvent-2.0's own re-registration path depends on this.
+            // All-events mode too: AceEvent-2.0 leaves it through this call.
             model.all_event_frames.retain(|x| x != &h);
             Ok(())
         })?,
@@ -116,33 +85,9 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         "GetScript",
         lua.create_function(|lua, (this, name): (Table, String)| get_script(lua, &this, &name))?,
     )?;
-    // HasScript(name) — "can this widget carry that script kind at all", NOT "does it have one
-    // set". The distinction is the whole point of the verb: every caller in the corpus uses it to
-    // decide whether it is safe to hook, then reads the current handler separately.
-    //
-    //     if parent:HasScript("OnMouseDown") then                    -- Tablet-2.0.lua:2409
-    //         local script = parent:GetScript("OnMouseDown")         -- FuBar-compat:2422
-    //         parent:SetScript("OnMouseDown", function() … end)
-    //     end
-    //
-    // It was the top session-start blocker: 32 of the 39 `attempt to call method` failures were
-    // this one name, across the Tablet/FuBar/oRA2 stack.
-    //
-    // ANSWERED FROM THE FLAT `SCRIPT_KINDS`, and that is a deliberate, stated approximation rather
-    // than the full answer. The reference's table is PER WIDGET TYPE — a plain Frame really does
-    // answer false for `OnClick` — so ours is over-permissive for the type-specific kinds. It is
-    // exactly right for the base kinds, which is what every corpus caller asks about
-    // (`OnMouseDown` here; a Frame genuinely has it). The cost of the over-permission is small and
-    // worth naming: an addon that asks about a type-specific kind installs a handler that never
-    // fires, where the reference would have had it skip. That is the same latitude `SetScript`
-    // already takes — this verb does not widen it, it just stops lying about its existence.
-    //
-    // Making it exact means per-type SCRIPT_KINDS, which newly RAISES on 30 sites that work today
-    // (9 in our own FrameXML). That is behaviour removal and belongs in its own change, with its
-    // own measurement; it is not a tail on this one.
-    //
-    // 1/nil, not a Lua boolean: the reference's row is `(nil) | (number)` like every other
-    // predicate (decision 2118).
+    // `HasScript(name)`: 1 if the widget can carry that script kind, else nil, whether or not one
+    // is set. Answered from the flat `SCRIPT_KINDS`, so another type's kind reads 1 too, where the
+    // reference's tables are per widget type (base `0x76a0d0`; a plain Frame has no `OnClick`).
     m.set(
         "HasScript",
         lua.create_function(|_, (_this, name): (Table, String)| {
@@ -151,13 +96,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             ))
         })?,
     )?;
-    // RegisterForDrag(...varargs of button names) — the drag-gesture twin of `RegisterForClicks`
-    // (decision 0216 §3), but on the SHARED table: any Frame can be a drag source, not just a
-    // Button. Replace-the-set semantics (empty varargs clears); `crate::script::cursor`'s
-    // arm/start/release path consults the set case-insensitively (the `RegisterForClicks`
-    // precedent). Pruning on frame destroy: see [`Model::drag_registered`]'s doc — nothing in
-    // this engine destroys a frame yet, so this map is in the same boat as `scripts`/
-    // `frame_events`.
+    // `RegisterForDrag(button, ...)` (`0x776d60`): on the shared table, since any frame can be a
+    // drag source; each call replaces the set (none clears it), matched case-insensitively.
     m.set(
         "RegisterForDrag",
         lua.create_function(|lua, (this, args): (Table, MultiValue)| {
@@ -174,27 +114,10 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
     // Regions
-    // `CreateTexture(name, layer, inheritsFrom)` — the third argument accepted for the same reason
-    // and with the same resolver, though the demand is a rounding error beside FontString's: of
-    // 1329 corpus call sites exactly TWO pass a third argument, and one of those passes `nil`
-    // (CustomNameplates:437, a four-argument later-client form). Accepted rather than skipped
-    // because dropping it silently is the very class this fixes, and one real site is still a site.
+    // `CreateTexture(name, layer, inherits)` (`0x773a20`).
     m.set(
-        // **The three argument positions are NOT one rule, and the fourth is the odd one:**
-        //
-        //  · `name` and `layer` go through `0x6f3510` (is-number-**or**-string) then `0x6f3690`, and
-        //    **the result is never tested** — so a table is simply absent (unnamed / the pre-staged
-        //    default layer), and a NUMBER is accepted and stringified.
-        //  · `inherits` is gated by a raw `lua_type(L, 4) == LUA_TSTRING` (`0x773d28` / `0x773b06`)
-        //    asked BEFORE anything reads the slot — so a table AND a number are both ignored, and the
-        //    non-string leg jumps to the very block the two template-HIT legs jump to, with both
-        //    template handles NULL. It is the success path, not a bolted-on case.
-        //
-        // **Nothing here raises.** This mattered: benilla typed all three `Option<String>`, so mlua
-        // raised `bad argument #4: error converting Lua table to String` — and pfUI, the most-installed
-        // 1.12 addon, builds every buff-stack label as
-        // `f.buffs[i]:CreateFontString(nil, "OVERLAY", f.buffs[i])`, passing the BUTTON as the third
-        // argument. The real client constructs it, ignores the argument, and logs nothing.
+        // `name` and `layer` pass `lua_isstring` (`0x6f3510`, then `0x6f3690`) with the result
+        // unchecked, so a table is absent and a number is stringified: no argument type raises.
         "CreateTexture",
         lua.create_function(
             |lua, (this, name, layer, inherits): (Table, Value, Value, Value)| {
@@ -208,32 +131,12 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             },
         )?,
     )?;
-    // ── The title region: Frame:CreateTitleRegion() / GetTitleRegion() ──────────────────────────
+    // ── Title region: CreateTitleRegion / GetTitleRegion ──
     //
-    // The byte read (`0x773910` / `0x773820`). Four details, each one a coin-flip a
-    // reimplementation loses:
-    //
-    //  · **It reads NO argument at all** — nothing in `0x773910`-`0x773a1f` touches Lua index 2. So
-    //    `CustomNameplates/options.lua:73`'s `CreateTitleRegion(optionsFrame)` is harmless and
-    //    identical to the no-arg call, rather than an error or a differently-parented region.
-    //  · **It is IDEMPOTENT, destructively.** One region per frame (`CSimpleFrame+0xA8`): a second
-    //    call runs ClearAllPoints on the existing one and returns THE SAME OBJECT — so calling it
-    //    on an XML-declared `<TitleRegion>` silently wipes that region's anchors. Returning a
-    //    fresh region instead would leave the first one hit-testing forever.
-    //  · **A fresh one has NO anchors** and does nothing until `SetPoint`/`SetAllPoints`. Both
-    //    corpus consumers immediately call `SetAllPoints`, which is the whole-window drag idiom.
-    //  · **`GetTitleRegion` answers 1 value (nil)** when there is none — note the asymmetry with
-    //    `GetBackdrop`, which answers 0 values; both are reproduced here.
-    // **ONE NAMED DIVERGENCE, because it is a superset and 1189 is what a superset costs.** The
-    // object answers *exactly* the 19 Region methods (`0x7a2ea0`, no own table) — no Show/Hide, no
-    // scripts, no textures.
-    // Ours answers the whole shared region table, because Texture/FontString/Title use one
-    // metatable here, so `titleRegion:SetTexture(…)` is accepted where the reference would raise
-    // `attempt to call method`. It is inert rather than wrong — a title region never draws (the
-    // extract skips its kind outright), so a texture or a Hide set on one changes nothing — but an
-    // addon that FEATURE-DETECTS would see a method the real client does not have. Splitting the
-    // metatable is the fix; it is not free, and nothing in the corpus asks, so this is recorded
-    // rather than hidden.
+    // `CreateTitleRegion` (`0x773910`) reads no argument and keeps one region per frame
+    // (`CSimpleFrame+0xA8`): a second call clears that region's anchors and returns it, and a new
+    // one has none. The reference's region answers only the 19 Region methods (`0x7a2ea0`); ours
+    // shares the region metatable, so it also accepts the texture methods, inertly.
     m.set(
         "CreateTitleRegion",
         lua.create_function(|lua, this: Table| {
@@ -282,27 +185,13 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             };
             match found {
                 Some(id) => Ok(Value::Table(region_wrapper(lua, id)?)),
-                // ONE value, and it is nil — not zero values. See the `GetBackdrop` asymmetry above.
+                // One nil value (`0x773820`), where `GetBackdrop` answers none.
                 None => Ok(Value::Nil),
             }
         })?,
     )?;
 
-    // The THIRD argument is `inheritsFrom`, and we were dropping it on the floor.
-    //
-    // 49 corpus call sites across 5 distinct addons pass one — AckisRecipeList (28),
-    // CustomNameplates (10), _LazyPig (6), LibAboutPanel (4), ColorPickerPlus (1) — and **every one
-    // of them names a FONT OBJECT**: GameFontNormalSmall (15), GameFontNormal (11),
-    // GameFontHighlightSmall (10), GameFontHighlight (9), GameFontNormalLarge (3), GameFontDisable.
-    // Five separate addons, so this is not one library file replicated (1207 checked, not assumed).
-    // Ignoring it is 1203's class exactly: the addon asks for a font, we accept the call, and the
-    // string comes out in whatever the default is with no failure anywhere.
-    //
-    // The resolution order is fixed (`0x773c30`): the FONT-object registry FIRST (`0x773d39`,
-    // create=0), and only on a font miss the template registry (`0x773d47`). This routes through
-    // the `SetFontObject` binding rather than reaching into the model, which is the same call the
-    // XML `<FontString inherits=>` path makes — one implementation of "apply a font object", not
-    // two that can drift.
+    // `CreateFontString(name, layer, inherits)` (`0x773c30`), with the same argument rules.
     m.set(
         "CreateFontString",
         lua.create_function(
@@ -321,52 +210,10 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
     Ok(())
 }
 
-/// `SetScript(name, func)` — store the closure against one of [`SCRIPT_KINDS`], or **raise**.
-///
-/// ## Why raising is the right answer for a script we cannot fire
-///
-/// The error is loud and it blocks the addon at load, which looks like the worse outcome and is
-/// not: a script name this host *accepts* and never *fires* is a handler that silently never runs,
-/// with nothing anywhere saying so. That is the failure mode decisions 1203, 1205 and 1211 each
-/// recorded from a different direction, and it is strictly harder to find than a load error naming
-/// the exact call. So the rule for this list is one line long: **a name is accepted only once
-/// something fires it.**
-///
-/// The 1.12 script set is fully mapped (the base table `0x76a0d0`, plus each widget's own
-/// per-type additions), so what is missing here is never a mystery — it is a
-/// deliberate not-yet. What the corpus actually asks for, and why each answer is what it is:
-///
-/// * **`OnKeyDown` / `OnKeyUp` / `OnChar`** (14 + 1 + 4 corpus sites over 13 addons) — **accepted**
-///   since decision 1319 built the delivery walk ([`crate::script::keyboard`], whose module doc is
-///   the mechanism: the kind buckets, the strata 8→0 order, the key-name table, and the
-///   existence-not-handling consumption gate). They were this list's standing exception; the rule
-///   above let them in the moment something fired them.
-/// * **`OnCursorChanged`** (4 sites over 3 addons, plus two in the SHIPPED FrameXML — all of them
-///   the `ScrollingEdit_OnCursorChanged` auto-scroll idiom) — **accepted since decision 2141**,
-///   which built the edge this entry said was missing. The EditBox's own slot (`+0x428`),
-///   fired by the caret flush `0x77da80` with four float caret-position args in UI units;
-///   `editbox::drain_cursor_changed` is our counterpart, on the tick, gated on the caret having
-///   actually moved. The stock `MailFrame.xml` and `HelpFrame.xml` declare it, so until 2141 the
-///   mail body and the GM ticket box did not scroll as you typed past their bottom — a bug nobody
-///   could see, because the load-time refusal only reached a terminal (decision 2135).
-/// * **`OnAttributeChanged`** (1 site, `Roid-Macros`) — **raising, permanently.** It is 2.0's secure
-///   frame/attribute system; there is no such slot in any 1.12 resolver. That addon is asking for a
-///   later client and should hear so.
-/// * **`OnHyperlinkEnter` · `OnHyperlinkLeave` · `OnMessageScrollChanged` ·
-///   `OnMovieFinished`/`ShowSubtitle`/`HideSubtitle` · `OnInputLanguageChanged`** — **raising.**
-///   Real 1.12 slots that we do not fire, and measured at **zero** call sites across the
-///   218-addon corpus, so there is nothing to weigh against the trap: they land when their
-///   mechanism does.
-/// * **`OnHorizontalScroll`** — **accepted, because `SetHorizontalScroll` fires it.** It was on
-///   the line above while "horizontal scroll isn't modeled at all", which stopped being true when
-///   the ScrollFrame's horizontal offset pair landed beside the vertical one
-///   ([`crate::script::scrollframe`]); `aux-addon` reads and writes both axes.
-/// * **`OnUpdateModel` · `OnAnimFinished`** — **accepted since decision 2007**, because the tick
-///   fires them: the model pane's scene clock runs in this engine now (`tick.rs`), `OnUpdateModel`
-///   at the top of every paint of a visible pane with a file (`0x76d1a0`) and `OnAnimFinished`
-///   from a sequence's natural completion (`0x76cdc0`, mode 0 — once per arm, a loop's first
-///   pass included). The shipped
-///   `Cooldown.xml` and `MainMenuBarBagButtons.xml` declare both.
+/// `SetScript(name, func)`: stores the closure under one of [`SCRIPT_KINDS`], else raises.
+/// Deviation: real 1.12 kinds nothing fires yet raise too (`OnHyperlinkEnter`, `OnHyperlinkLeave`,
+/// `OnMessageScrollChanged`, `OnInputLanguageChanged`, the movie frame's), because an accepted
+/// handler that never runs fails silently. `OnAttributeChanged` is 2.0's, with no 1.12 slot.
 fn set_script(lua: &Lua, this: &Table, name: &str, func: Option<Function>) -> mlua::Result<()> {
     let kind = SCRIPT_KINDS
         .iter()
@@ -376,7 +223,7 @@ fn set_script(lua: &Lua, this: &Table, name: &str, func: Option<Function>) -> ml
     let h = frame_handle_of(lua, this)?;
     let id = lua.app_data_mut::<Model>().expect("model").frame_id(h);
 
-    // Store the closure Lua-side (REG_SCRIPTS[id][kind]); update the Rust presence mirror.
+    // The closure lives Lua-side in `REG_SCRIPTS[id][kind]`; Rust keeps a presence mirror.
     let scripts: Table = lua.named_registry_value(REG_SCRIPTS)?;
     let per: Table = match scripts.get::<Value>(id)? {
         Value::Table(t) => t,
@@ -390,8 +237,7 @@ fn set_script(lua: &Lua, this: &Table, name: &str, func: Option<Function>) -> ml
         Some(f) => {
             per.set(kind, f)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
-            // `insert` answering true = this frame did not have the kind before — the tick's
-            // OnUpdate list rides that edge (decision 1446; `scripts` has no other writer).
+            // The first handler of a kind joins that kind's list; nothing else writes `scripts`.
             if model.scripts.entry(h).or_default().insert(kind) {
                 match kind {
                     "OnUpdate" => model.on_update_frames.push(h),
@@ -438,24 +284,12 @@ fn get_script(lua: &Lua, this: &Table, name: &str) -> mlua::Result<Value> {
     }
 }
 
-/// `CreateTexture`/`CreateFontString`'s third argument — `inheritsFrom` — in the fixed order.
-///
-/// **Font-object registry first, template registry second** (`0x773d39` then `0x773d47`). That
-/// order is not cosmetic: `inherits=` is one attribute over two namespaces, and every corpus caller
-/// of this argument names a font object, so a template-first resolver would miss all 49 of them.
-///
-/// A name in NEITHER registry raises, which is the same contract 1253 established for `CreateFrame`
-/// and the same bytes (`luaL_error`, `0x87957c` / `0x879544`, which never returns).
-///
-/// A name that IS a registered template but not a font object is a deliberate gap rather than a
-/// silent one: the lookup succeeded, so the reference would not raise, and re-interpreting a
-/// template node onto an existing region is a different mechanism from applying a font object. It
-/// warns and leaves the region usable — the distinction 1253 drew between *the lookup missing* and
-/// *the result being unusable*. Zero corpus callers reach it.
+/// Apply the `inherits` argument: the font-object registry first (`0x773d39`), then the template
+/// registry (`0x773d47`); a name in neither raises (`0x87957c` / `0x879544`). A template that is
+/// not a font object only warns: the reference applies the template, which is not built here.
 fn apply_region_inherits(lua: &Lua, wrapper: &Table, from: &str) -> mlua::Result<()> {
     use mlua::ObjectLike;
-    // The font object is applied through the binding the XML path uses, so there is one
-    // implementation of "apply a font object" rather than two that can drift apart.
+    // Through `SetFontObject`, the binding the XML `inherits=` path uses.
     if wrapper.call_method::<()>("SetFontObject", from).is_ok() {
         return Ok(());
     }
@@ -476,16 +310,9 @@ fn apply_region_inherits(lua: &Lua, wrapper: &Table, from: &str) -> mlua::Result
     )))
 }
 
-/// **The `lua_type(L, idx) == LUA_TSTRING` gate, asked before anything reads the slot** — the
-/// region constructors' `inherits` argument and nowhere else (`0x773d28` for `CreateFontString`,
-/// `0x773b06` for `CreateTexture`).
-///
-/// Strictly narrower than [`optional_string`]: a **number is refused here**, because the tag is
-/// tested raw with no coercion. That one-argument difference is the whole reason
-/// `f:CreateTexture(nil, nil, 5)` silently ignores the 5 while `CreateFrame("Frame", nil, nil, 5)`
-/// **raises** `Couldn't find inherited node "5"` — `CreateFrame` runs `lua_tostring(L, 4)` BEFORE
-/// its own `cmp 4`, and that retags the number's stack slot in place, so it arrives as a string.
-/// Same value, opposite outcome, from argument order alone.
+/// The region constructors' strict `lua_type == LUA_TSTRING` gate on `inherits` (`0x773d28`
+/// `CreateFontString`, `0x773b06` `CreateTexture`): unlike [`optional_string`], a number is
+/// ignored, where `CreateFrame` stringifies it first and looks it up as a name.
 fn strict_string_arg(v: &Value) -> Option<String> {
     match v {
         Value::String(s) => s.to_str().ok().map(|s| s.to_owned()),
@@ -518,22 +345,15 @@ fn create_region(
 
     let wrapper = region_wrapper(lua, id)?;
     if let Some(name) = name {
-        // **A leading `$parent` in the NAME is expanded, here as in XML** — `CreateTexture
-        // 0x773a20` and `CreateFontString 0x773c30` build a synthetic node carrying
-        // `name=<the Lua string>` and read it back through the same `GetAttribute(node, "name")` →
-        // `CScriptRegion::SetName 0x76c650` the XML path uses, and `0x76c691` is one of that
-        // expander's two call sites — `0x773ba1` and `0x773dc4` are the addresses *inside* these
-        // two bindings. A region's `$parent` is its OWNER frame, so the walk starts there.
-        //
-        // `pfQuest/browser.lua:723` is `pfBrowser.input:CreateTexture("$parentSearchIcon",
-        // "OVERLAY")`, and every named widget FonzAppraiser builds is this idiom.
+        // A leading `$parent` expands as in XML, its walk to a named frame starting at the owner:
+        // both bindings name the region through `CScriptRegion::SetName 0x76c650` (`0x773ba1`,
+        // `0x773dc4`).
         let name = {
             let model = lua.app_data_ref::<Model>().expect("model");
             crate::framexml::resolve_name(&name, &super::parent_token_base(&model, Some(owner)))
         };
         publish_global(lua, &name, &wrapper)?;
-        // Publish into the region-name registry too (first-wins, the frame rule) — this is what
-        // lets a sibling region's SetPoint name us as its `relativeTo` (see `resolve_target`).
+        // First name wins, as for frames; a sibling's `SetPoint` can then name this region.
         let mut model = lua.app_data_mut::<Model>().expect("model");
         model.region_names.entry(name).or_insert(id);
     }
@@ -544,12 +364,7 @@ fn create_region(
 mod tests {
     use crate::script::UiScript;
 
-    /// `UnregisterAllEvents` drops every registration the frame holds and leaves every other
-    /// frame's alone — the "disable me" path 10 corpus addons stop on (decision 1195).
-    ///
-    /// The second half is the one worth asserting: the cheap implementation (sweep every listener
-    /// list) and the correct one differ only when a *second* frame shares an event, which is the
-    /// normal case for `PLAYER_ENTERING_WORLD`.
+    /// Both frames share both events, so clearing one must leave the other's registrations.
     #[test]
     fn unregister_all_events_clears_one_frame_and_only_that_frame() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/object/frame_state.rs b/crates/benilla-ui/src/script/object/frame_state.rs
index 8692a62a..6238f280 100644
--- a/crates/benilla-ui/src/script/object/frame_state.rs
+++ b/crates/benilla-ui/src/script/object/frame_state.rs
@@ -1,8 +1,4 @@
-//! Frame method-table cluster: Show/Hide/visibility, identity/hierarchy (`GetName`/`GetParent`/
-//! `SetParent`), strata/level/scale/alpha, the Backdrop mechanism (`SetBackdrop`/`SetBackdropColor`/
-//! `SetBackdropBorderColor`), and mouse-enable. Split out of [`super`] purely for size — the shared
-//! id/handle plumbing, `CreateFrame`, and the method-table wiring stay there; this module's
-//! [`install`] just populates its share of the one shared method table.
+//! Frame methods: visibility, hierarchy, strata, level, scale, alpha, backdrop and input flags.
 
 use mlua::{Lua, Table, Value};
 
@@ -14,12 +10,9 @@ use crate::widget::FrameKind;
 
 use super::{decode_id, draw_layer_from_str, frame_handle_of, frame_wrapper, strata_from_str};
 
-/// Populate `m`'s visibility/hierarchy/strata/backdrop/mouse methods (see the module doc).
+/// Populate `m`'s visibility, hierarchy, strata, backdrop and input methods.
 pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
-    // Show / Hide / visibility. **`SetShown` is not here and must not come back**: the branchless
-    // setter belongs to a later expansion — no 1.12 method table registers it, and neither the
-    // stock chain nor either addon corpus calls it (decision 2142's census). A frame is shown or
-    // hidden by the two verbs the era has.
+    // Show / Hide / visibility. No `SetShown`: no 1.12 method table registers it.
     m.set(
         "Show",
         lua.create_function(|lua, this: Table| set_shown(lua, &this, true))?,
@@ -64,8 +57,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             None => Ok(Value::Nil),
         }
     })?;
-    // GetID/SetID — the app-meaning-free numeric label (XML `id=`, the client's `+0xb4`): a
-    // dropdown row's list position, a tab index. Default 0 (see `Frame::wow_id`).
+    // GetID/SetID (`0x775280`/`0x775340`): a plain numeric label at `+0xb0` (XML `id=`), default 0.
     m.set(
         "GetID",
         lua.create_function(|lua, this: Table| {
@@ -85,47 +77,24 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // ── GetObjectType / IsObjectType, frame side (`0x7a11d0`/`0x7a1290`) ─────────────────────────
+    // ── GetObjectType / IsObjectType, frame side (`0x7a11d0`/`0x7a1290`) ──
     //
-    // The region side landed first because a FontString found it; `_Nameplates` is why this half
-    // exists too — `_Nameplates.lua:164` tests `Nameplate:GetObjectType() ~= "Button"` and `:191`
-    // tests `== "StatusBar"`, on FRAMES, in the same file whose `Region:GetObjectType()` calls the
-    // region verbs answer.
-    //
-    // The chains are a hardcoded straight-line list per class in the binary, not a runtime parent
-    // walk, so they are a table here too. Three of them are things a reasonable person invents
-    // wrongly:
-    //
-    //  · **`ScrollingMessageFrame` derives from `Frame`, NOT from `MessageFrame`.** The name says
-    //    otherwise and the roster is explicit (`0x787940`).
-    //  · **`SimpleHTML` is spelled with a capitalised HTML.** Our enum variant is `SimpleHtml`, so
-    //    anything derived from the variant name — `format!("{:?}")` and friends — would hand
-    //    addons `"SimpleHtml"`, and `GetObjectType` is compared with `==` (`IsObjectType`'s
-    //    case-folding would hide it; the getter's would not).
-    //  · **There is no `Cooldown` type.** 1.12.1's census finds 23 type-name globals and none is
-    //    that: the reference builds its cooldown as a `Model` playing `UI-Cooldown-Indicator.mdx`
-    //    (`CooldownFrameTemplate`), and since decision 2019 so does this engine — the Era-shaped
-    //    `FrameKind::Cooldown` that modelled the mechanism first-class (0137 phase 4) is gone, so
-    //    `CreateFrame("Cooldown")` is the reference's own unknown-type refusal, never an announced
-    //    Era type to a Lua ecosystem that branches on presence (the superset 1189 took back out).
+    // Each class's chain is a fixed list in the reference, so a table here. `ScrollingMessageFrame`
+    // derives from `Frame`, not `MessageFrame` (`0x787940`); `SimpleHTML` keeps its capitals,
+    // unlike the `SimpleHtml` variant; there is no `Cooldown` type (the reference's is a `Model`).
     fn type_chain(kind: FrameKind) -> &'static [&'static str] {
         match kind {
             FrameKind::Frame => &["Frame", "Region"],
             FrameKind::WorldFrame => &["Frame", "Region"],
             FrameKind::Button => &["Button", "Frame", "Region"],
             FrameKind::CheckButton => &["CheckButton", "Button", "Frame", "Region"],
-            // `CLootButton::IsObjectType 0x495af0` prepends its own name to the base's three
-            // (`"Button"` `[0x879954]`, `"Frame"` `[0x878560]`, `"Region"` `[0x878870]`) — read
-            // off the function, not assumed from the class hierarchy.
+            // `CLootButton::IsObjectType` (`0x495af0`) prepends its name to `Button`'s chain.
             FrameKind::LootButton => &["LootButton", "Button", "Frame", "Region"],
             FrameKind::EditBox => &["EditBox", "Frame", "Region"],
             FrameKind::StatusBar => &["StatusBar", "Frame", "Region"],
             FrameKind::Slider => &["Slider", "Frame", "Region"],
             FrameKind::ScrollFrame => &["ScrollFrame", "Frame", "Region"],
             FrameKind::Model => &["Model", "Frame", "Region"],
-            // 4 deep: `PlayerModel` derives from `Model`, and `DressUpModel` (1969) and
-            // `TabardModel` (1977) derive from it in turn, for the roster's maximum depth of 5
-            // (the reference's full 23-class roster).
             FrameKind::PlayerModel => &["PlayerModel", "Model", "Frame", "Region"],
             FrameKind::DressUpModel => &["DressUpModel", "PlayerModel", "Model", "Frame", "Region"],
             FrameKind::TabardModel => &["TabardModel", "PlayerModel", "Model", "Frame", "Region"],
@@ -151,9 +120,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         Ok(Value::String(lua.create_string(chain_of(lua, &this)?[0])?))
     })?;
 
-    // Same four traps as the region twin (see `script::region`): case-insensitive whole-string,
-    // number 1 on a hit and nil on a miss, exactly one value either way, and a non-string
-    // non-number argument raises the reference's own `Usage:` text.
+    // A case-insensitive whole-string match answering 1 or nil; a non-string, non-number argument
+    // raises the reference's `Usage:`.
     set_shared(
         lua,
         m,
@@ -186,38 +154,11 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         },
     )?;
 
-    // ── GetFrameType / IsFrameType: the FRAME-side spellings of the pair above (decision 2106) ──
+    // ── GetFrameType / IsFrameType ──
     //
-    // 1.12 registers the type-identity pair **twice, under two names**. The Region script
-    // (`CScriptRegion`) publishes `GetObjectType`/`IsObjectType` — that is the pair above, and its
-    // `IsObjectType` binding is `0x7a1290`. The *frame* script (`CSimpleFrameScript.cpp`,
-    // `__FILE__` `0x879504`) publishes `GetFrameType 0x773640` and `IsFrameType 0x773700` as well.
-    // `GetObjectType`/`IsObjectType` are what LATER
-    // clients kept; `GetFrameType`/`IsFrameType` are 1.12's own, and we shipped only the first
-    // pair. That is 1189's superset argument inverted — not an extra name we invented, a real one
-    // we were missing — and it cost the world map:
-    //
-    //     Cartographer 2.02, LookNFeel.lua:368, inside OnEnable:
-    //         if v:GetFrameType() == "Model" and not v:GetName() then self.playerModel = v end
-    //
-    // With the verb nil that line raised, AceAddon swallowed it, `self.playerModel` stayed nil,
-    // and the next `Cartographer_ChangeZone` → `SetAlpha` put a red script error on screen from
-    // `LookNFeel.lua:737` every time the map opened. FuBar's own `FuBar.lua:576`
-    // (`type(frame:GetFrameType()) ~= "string"`) is the same call.
-    //
-    // Both delegate to the same `type_chain` the `Object` pair reads: `GetFrameType` is
-    // `call [edx+0x1c]` — the identical per-class type-name slot `GetObjectType` reads — then
-    // `lua_pushstring`, one value, extra arguments ignored. `IsFrameType` walks the chain through
-    // `[eax+0x18]`, the same case-insensitive whole-string compare, and answers the NUMBER 1 or
-    // nil.
-    //
-    // **One edge is INFERRED and named rather than guessed silently:** the one description of
-    // `IsFrameType`'s *absent-argument* branch reads "pushes the frame's own typename (`call
-    // [eax+4]` GetName)", which is self-contradictory — a typename and a name are different slots —
-    // so the branch is not settled. We take the sibling's behaviour (the `Usage:` raise) pending a
-    // byte read. No caller in the 219-addon corpus, the director's AddOns, or the shipped FrameXML
-    // ever omits the argument: `JIM_toolbox/Config2/Pulse_Config.lua:118` is the corpus's only
-    // `IsFrameType` site and it passes `"Slider"`.
+    // The frame script's own spellings of the pair above (`GetFrameType 0x773640`, `IsFrameType
+    // 0x773700`), reading the same per-class type slot: one name, or 1 or nil. An absent argument
+    // raises `Usage:` like `IsObjectType`; the reference's absent-argument branch is untraced.
     m.set(
         "GetFrameType",
         lua.create_function(|lua, this: Table| {
@@ -268,67 +209,11 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             None => Ok(Value::Nil),
         }
     })?;
-    // ── The four structure queries: GetChildren / GetNumChildren / GetRegions / GetNumRegions ──
+    // ── GetChildren / GetNumChildren / GetRegions / GetNumRegions ──
     //
-    // Registered bindings in 1.12 (`GetNumRegions 0x773e60`, `GetRegions 0x773f60`,
-    // `GetNumChildren 0x774080`, `GetChildren 0x774180`): each marshals and delegates, with no
-    // fidelity math of its own).
-    //
-    // **Why these four are worth more than their size.** They are how an addon walks a frame it did
-    // not build, which is the whole basis of the "reskin the default UI" genre — and that genre is
-    // the top of the 1.12 popularity list. `pfUI.api.StripTextures` is the canonical shape:
-    //
-    //     for _, v in ipairs({ frame:GetRegions() }) do
-    //       if v.SetTexture then ... v:SetTexture(nil) end
-    //     end
-    //
-    // With `GetRegions` absent that is `attempt to call method 'GetRegions' (a nil value)`, raised
-    // out of a library file every one of pfUI, pfQuest, pfQuest-turtle and ShaguDPS embeds — four
-    // separate top-20 addons dying on one missing verb, plus Questie on `GetChildren`.
-    //
-    // **Two lists, one walk each, in the arena's own order.** `Frame::children` is insertion order,
-    // which our own arena documents as the client's `+0x300` child-list order; `Frame::regions` is
-    // creation order. Neither is re-sorted here — a structure query reports the structure, and the
-    // draw order is `crate::order`'s separate concern.
-    //
-    // **A detached region is not in the list.** `Region:SetParent(nil)` sets `Region::detached`
-    // rather than removing the entry, because the owner's `Vec` is what `WidgetArena::destroy`
-    // frees from — but the client's re-link virtual `0x77fd10` with a null parent genuinely
-    // **unlinks from the old parent's draw layer and region list**, so a detached region must be
-    // invisible to both region verbs. Our flag is a representation choice; the list these
-    // report is the client's.
-    //
-    // **The count and the list come from ONE function** ([`regions_of`] / [`children_of`]), never
-    // two walks with the same filter written twice. `GetNumRegions` disagreeing with
-    // `#{GetRegions()}` is a bug an addon would hit as an off-by-one deep inside a loop it did not
-    // write, and the only way to make it impossible is to have one of them BE the other.
-    //
-    // **The order and inclusion rules below — one of them a correction:**
-    //
-    //  · **The order is link order, oldest first, and no reversal.** `CSimpleFrame` embeds a punned
-    //    `TSList` header whose ctor sets `tail = &header`, `head = (&header)|1`, and BOTH linkers
-    //    append at the TAIL (`0x76a750` for regions, `0x76aa20` for children — one caller each).
-    //    Our insertion-order `Vec` is the same order.
-    //  · **Hidden children and regions are returned and counted** — a VERIFIED negative: the
-    //    counting loops never load the visibility word at all.
-    //  · **The TITLE REGION IS NOT RETURNED**, and that one corrected us. Both creation paths
-    //    (`0x773910`, `0x769b79`) dispatch a vtable slot that is a bare `[this+0x9c] = parent` and
-    //    never reach the linker `0x77fd10`, so a title region is not in the list this walks —
-    //    corroborated by `Hide`/`Show` carrying an explicit extra `[frame+0xa8]` case *because* the
-    //    list walk misses it. Ours is in `Frame::regions` (so the arena can free it), so
-    //    [`regions_of`] filters it out.
-    //  · **A Button's label (`+0x338`) and its four state textures ARE in the list** — they link
-    //    through `0x77fd10` like any region, which is what ours do too.
-    //  · **The return shape**: N separate values, never a table; a frame with none returns ZERO
-    //    values (no `lua_newtable` in either body), and `GetNum*` returns one number — `0` when
-    //    empty, never nil.
-    //
-    // The one thing still out of reach is not these bindings': Questie reads
-    // `({Minimap:GetChildren()})[9]` for the player arrow; here is why that index works —
-    // `CMinimap`'s ctor `0x4edbc0` builds NINE engine-owned `Model` children before the XML
-    // `<Frames>` descent, the ninth (`[Minimap+0x338]`) being the arrow `SetPlayerFacing 0x4eb8e0`
-    // writes. We create none of them, so index 9 is nil here until the minimap grows its engine
-    // children.
+    // `0x774180` / `0x774080` / `0x773f60` / `0x773e60`: link order, oldest first (both linkers,
+    // `0x76a750` and `0x76aa20`, append at the tail), hidden ones included; the list as separate
+    // values, none when empty, the count as one number. Each count shares its list's walk.
     m.set(
         "GetChildren",
         lua.create_function(|lua, this: Table| {
@@ -361,15 +246,10 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         "GetNumRegions",
         lua.create_function(|lua, this: Table| Ok(regions_of(lua, &this)?.len()))?,
     )?;
-    // SetParent — the runtime reparent (decision 1323). The binding half
-    // (`0x7a1550`): the parent argument is a frame table, a NAME string (`0x76c760`), or an
-    // explicit nil — an ABSENT argument is NOT the nil path (`0x6f3400` returns −1) and raises
-    // like an unresolvable name; the cycle guard is the binding's own inline ancestor walk and
-    // RAISES (`0x87cb14`), it does not silently no-op. The arena half is
-    // `reparent_begin`/`reparent_finish`, split so `OnHide` fires between them the way the
-    // reference's hide→show round-trip does — `fire_visibility_changes` reads each frame's live
-    // state for direction, so hide and show must be fired from their own phase, never one
-    // combined list.
+    // `SetParent` (`0x7a1550`): a frame, a name (`0x76c760`) or an explicit nil; an absent argument
+    // raises like an unknown name (`0x6f3400` gives -1), and so does a cycle (`0x87cb14`). As in
+    // the reference, hide fires before show, between `reparent_begin` and `reparent_finish`,
+    // since `fire_visibility_changes` reads each frame's live state for the direction.
     set_shared(
         lua,
         m,
@@ -391,9 +271,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                     .unwrap_or_else(|| "<unnamed>".to_string())
             };
             let parent_arg = it.next();
-            // `_G[name]` is read with no guard alive (`object::NamedTarget`), and **without**
-            // `$parent` expansion: `0x7a1550` calls `0x76c760` directly, and only the layout
-            // vtable's `0x76c700` runs the token.
+            // `_G[name]` is read with no guard alive and no `$parent` expansion: `0x7a1550` calls
+            // `0x76c760` directly, and only the layout path's `0x76c700` expands the token.
             let named = match &parent_arg {
                 Some(Value::String(s)) => Some(match s.to_str() {
                     Ok(n) => super::prefetch_named_target(lua, n.as_ref(), None),
@@ -404,7 +283,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             let new_parent = {
                 let model = lua.app_data_ref::<Model>().expect("model");
                 match &parent_arg {
-                    // Explicit nil reparents to the screen root (the strata/level RESET path).
+                    // An explicit nil reparents to the screen root, resetting strata and level.
                     Some(Value::Nil) => None,
                     Some(Value::Table(t)) => Some(
                         decode_id(t)
@@ -417,10 +296,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                             })?,
                     ),
                     Some(Value::String(_)) => {
-                        // `_G[name]` + the **Frame** tag check — the reference's `0x76c760`
-                        // (`0x7a1550`'s NAME-string path) type-guards against `[0xcf0c10]`, the
-                        // narrow Frame id, not `SetPoint`'s root `[0xcf0c3c]`. So a global naming
-                        // a REGION fails here exactly as an absent one does.
+                        // `0x76c760` accepts only a frame (`[0xcf0c10]`), not any region
+                        // (`[0xcf0c3c]`), so a region's name fails like an absent one.
                         let nt = named.as_ref().expect("a String argument is prefetched");
                         let hit = super::resolve_named_target(&model, nt)
                             .and_then(|id| model.id_to_frame.get(&id).copied());
@@ -431,8 +308,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                             ))
                         })?)
                     }
-                    // Absent argument, or any other type: the reference never reaches the
-                    // reparent slot (`0x87cb48` raise).
+                    // Absent, or any other type: the reference raises first (`0x87cb48`).
                     _ => {
                         return Err(mlua::Error::runtime(format!(
                             "{who}:SetParent(): Couldn't find region named ''"
@@ -440,8 +316,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                     }
                 }
             };
-            // The cycle guard raises — `"%s:SetParent(): Would create a loop parenting to %s"`
-            // (`0x7a177f`'s inline `+0x9c` walk, `newParent == self` included).
+            // The cycle guard raises (`0x7a177f`'s ancestor walk, the frame itself included).
             if let Some(np) = new_parent {
                 let model = lua.app_data_ref::<Model>().expect("model");
                 if np == h || model.arena.is_ancestor(h, np) {
@@ -459,24 +334,15 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 let mut model = lua.app_data_mut::<Model>().expect("model");
                 model.arena.reparent_begin(h, new_parent)
             };
-            // None = the verified total no-op (same parent, `0x76ab20`): nothing runs, not even
-            // the layout touch.
+            // None: the same parent, a total no-op (`0x76ab20`), not even a layout touch.
             let Some(hidden) = hidden else { return Ok(()) };
             let was_visible = !hidden.is_empty();
             event::fire_visibility_changes(lua, hidden);
             let shown = {
                 let mut model = lua.app_data_mut::<Model>().expect("model");
                 let shown = model.arena.reparent_finish(h, new_parent, was_visible);
-                // A real reparent moves the subtree's effective scale — a layout-gate input,
-                // and a measure-key input the subtree's FontStrings cannot name one by one.
-                //
-                // **The layout half NAMES its nodes** (decision 2314). This was the conservative
-                // touch, on the reading that a reparent is human-rate; a pooled widget's recycle
-                // is a reparent, and `WOW_LAYOUT_DERIVE_TRACE` put every sampled give-up in a
-                // quest-accept spike on this one line — 58 whole-graph derivations in one frame,
-                // 128 ms of a 161 ms hitch. `touch_layout_reparent`'s doc has why the subtree is
-                // the whole of what moved. The measure sweep keeps the wide form: a measure key
-                // is not a layout input and its sweep is a different cost.
+                // A reparent moves the subtree's effective scale, a layout input and part of every
+                // descendant FontString's measure key.
                 model.touch_layout_reparent(h);
                 model.touch_measure_all();
                 shown
@@ -513,12 +379,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         lua.create_function(|lua, (this, level): (Table, i64)| {
             let h = frame_handle_of(lua, &this)?;
             let lvl = level.clamp(0, i64::from(u16::MAX)) as u16;
-            // **A script level change carries no children** — the binding `0x774560` calls
-            // `set_frame_level 0x76a4f0` with `propagate=0`.
-            // Only the toplevel raise shifts a subtree. Stock `BonusActionButtonTemplate` is written
-            // for this: it raises the button +2 and then its cooldown +2 by hand, landing the sweep
-            // one level over the button — carrying the children made it three, over the
-            // cooldown-count text an addon hangs at button + 2 (decision 2189).
+            // A script level change moves no children: `0x774560` calls `set_frame_level 0x76a4f0`
+            // with `propagate = 0`, which stock `BonusActionButtonTemplate` relies on.
             lua.app_data_mut::<Model>()
                 .expect("model")
                 .arena
@@ -541,8 +403,6 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         lua.create_function(|lua, (this, scale): (Table, f32)| {
             let h = frame_handle_of(lua, &this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
-            // Effective-scale changes ride the propagation's own eps gate; the own-scale compare
-            // is the cheap superset (same own scale => no effective change is possible).
             let changed = model.arena.frame(h).is_some_and(|f| f.scale != scale);
             model.arena.set_scale(h, scale);
             if changed {
@@ -565,8 +425,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         "SetAlpha",
         lua.create_function(|lua, (this, alpha): (Table, f32)| {
             let h = frame_handle_of(lua, &this)?;
-            // The 1.12 API clamps to 0..1 — ref Lua leans on it (fade code that passes a 0..255
-            // alpha stays fully opaque until the value falls below 1/255).
+            // The reference clamps to 0..1; stock fade code passing a 0..255 alpha relies on it.
             lua.app_data_mut::<Model>()
                 .expect("model")
                 .arena
@@ -582,11 +441,9 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             Ok(model.arena.frame(h).map(|f| f.alpha).unwrap_or(1.0))
         })?,
     )?;
-    // Backdrop (`0x7776e0` → `0x76a5d0`): SetBackdrop(table|nil) installs (or, with nil, tears
-    // down) the frame's tiled bg + 8-piece border plate. The two color setters tint the bg / all 8
-    // border pieces (never the reverse — `0x77f410`/`0x77f440`). The Lua-table SetBackdrop defaults
-    // both colors to WHITE
-    // (the ctor), so a caller must SetBackdropColor after to tint (the tooltip's OnLoad does).
+    // `SetBackdrop(table|nil)` (`0x7776e0` → `0x76a5d0`) installs or removes the tiled background
+    // and 8-piece border, both white until tinted; the two colour setters tint the background and
+    // the border respectively (`0x77f410`/`0x77f440`).
     m.set(
         "SetBackdrop",
         lua.create_function(|lua, (this, arg): (Table, Value)| {
@@ -613,50 +470,22 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // `GetBackdrop()` (`0x777370`) — five things
-    // a plausible implementation gets wrong, so each is spelled out with its reason:
-    //
-    // 1. It is a **reconstruction from the struct**, never the caller's table. The reference stores
-    //    no Lua reference anywhere: `SetBackdrop` reads six keys into a fresh 0x68-byte struct at
-    //    `frame+0x1ac` and drops the table, so `0x777426`–`0x7776b9` re-push every key from those
-    //    fields. Handing back a stored clone would leak keys the reader never accepted and would
-    //    keep stale values a later `SetBackdropColor` changed.
-    // 2. **No backdrop ⇒ ZERO Lua values, not `nil`** — the early bail is `xor eax,eax; ret`, which
-    //    for a *return* path really is "no values" (contrast `binding_abi`'s note: the same two
-    //    bytes after a `luaL_error` are unreachable boilerplate). Observable through the count,
-    //    and it is the shape our `GetTitleRegion` will *not* have when it lands — that one pushes
-    //    nil, i.e. one value. The client cannot distinguish "never set" from `SetBackdrop(nil)`.
-    // 3. **A partial `SetBackdrop` omits nothing on the way out.** Every `SetBackdrop` allocates a
-    //    fresh struct (`0x777801`, ctor `0x77e5f0`), so a key the caller left out is a *ctor
-    //    default* here, not an absent key and not the previous backdrop's value: `bgFile`/`edgeFile`
-    //    `""`, `tileSize` 0, `edgeSize` **32**. Our `backdrop_from_table` already builds on
-    //    `Backdrop::default()`, so this falls out — but only because `None` maps to `""` below
-    //    rather than to nil.
-    // 4. **`tile` is the NUMBER `1`, or the key is ABSENT — never `true`/`false`.** The push is
-    //    `0x3ff00000` (the double 1.0) on true and `lua_pushnil` on false, and `lua_settable` with a
-    //    nil value creates no key (and *erases* one from a recycled table, which is why the nil is
-    //    written rather than skipped). An addon reading `if backdrop.tile then` sees the same truth
-    //    either way; one that round-trips the table into `SetBackdrop` is why the number matters,
-    //    since `tile` there goes through a coercer that takes numbers.
-    // 5. The undocumented **in-place form** (`0x77740e`): `lua_type(L,2) == LUA_TTABLE` skips
-    //    `lua_newtable` and fills arg 2, reusing an existing `insets` subtable rather than replacing
-    //    it. Implemented — it is four lines, and an addon caching one table across frames would
-    //    otherwise silently get a new one each call. A non-table arg 2 is ignored, not an error.
-    //
-    // No `bgColor`/`edgeColor`/`alpha` key exists: the two colors live in the struct but the reader
-    // never pushes them (`GetBackdropColor`/`GetBackdropBorderColor` are their only accessors).
+    // `GetBackdrop([table])` (`0x777370`) rebuilds the table from the stored struct: no backdrop is
+    // zero values, not nil; an omitted key reads its ctor default (files `""`, `tileSize` 0,
+    // `edgeSize` 32; `0x77e5f0`); `tile` is 1 or absent, never a boolean; a table argument is
+    // filled in place, its `insets` reused (`0x77740e`). No colour keys.
     m.set(
         "GetBackdrop",
         lua.create_function(|lua, (this, target): (Table, Value)| {
             let h = frame_handle_of(lua, &this)?;
-            // Copied out before a single Lua write: filling a *caller-supplied* table can run a
-            // `__newindex` metamethod, which can re-enter us and would panic on the app-data borrow.
+            // Copied out before any Lua write: filling a caller's table can run a `__newindex` that
+            // re-enters and would panic on the app-data borrow.
             let bd = {
                 let model = lua.app_data_ref::<Model>().expect("model");
                 model.backdrops.get(&h).cloned()
             };
             let Some(bd) = bd else {
-                return Ok(mlua::MultiValue::new()); // trap 2 — zero values, not nil
+                return Ok(mlua::MultiValue::new());
             };
             let t = match target {
                 Value::Table(t) => t,
@@ -667,15 +496,15 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             t.set(
                 "tile",
                 if bd.tile {
-                    Value::Number(1.0) // trap 4
+                    Value::Number(1.0)
                 } else {
-                    Value::Nil // trap 4 — erases the key from a recycled table
+                    Value::Nil // erases the key from a reused table
                 },
             )?;
             t.set("tileSize", f64::from(bd.tile_size))?;
             t.set("edgeSize", f64::from(bd.edge_size))?;
             let insets = match t.get::<Value>("insets") {
-                Ok(Value::Table(existing)) => existing, // trap 5 — reuse, don't replace
+                Ok(Value::Table(existing)) => existing,
                 _ => {
                     let fresh = lua.create_table()?;
                     t.set("insets", &fresh)?;
@@ -745,7 +574,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             }
         })?,
     )?;
-    // Mouse interaction (EnableMouse gates hit-testing; keyboard focus is out of scope)
+    // Mouse interaction: `EnableMouse` gates hit-testing.
     m.set(
         "EnableMouse",
         lua.create_function(|lua, (this, enable): (Table, bool)| {
@@ -767,21 +596,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             ))
         })?,
     )?;
-    // EnableKeyboard(flag) / IsKeyboardEnabled() — `0x776f90` / `0x776ff0`, real Frame entries,
-    // beside the mouse pair above.
-    //
-    // 8 corpus addons call this and were RAISING on it (`ColorPickerPlus:258`,
-    // `Dewdrop-2.0.lua:2021-2022` — which is in ~65 addons — `AckisRecipeList/ARLFrame.lua:1650`).
-    // The flag round-trips; **key delivery is not gated on it**, exactly as the wheel's flag
-    // shipped in 1198, because the machinery it would gate does not exist here yet.
-    //
-    // Why that is the right half rather than a silent stub, which this codebase has been bitten by
-    // three times (1203/1205/1211): the majority of the corpus calls pass **false**, and for those
-    // our behaviour is already the reference's — we deliver no keys to arbitrary frames either. The
-    // `true` callers want delivery we do not do, but they did not get it before this landed; they
-    // got a raise that killed the enclosing function. And being enabled genuinely is separable
-    // from having a handler (`0x76af00` never touches the handler slots), so the flag is a real
-    // piece of the model, not a placeholder for one.
+    // EnableKeyboard / IsKeyboardEnabled (`0x776ec0`/`0x776f90`): the flag key delivery gates on
+    // (`script::keyboard`), separate from having a handler (`0x76af00`).
     m.set(
         "EnableKeyboard",
         lua.create_function(|lua, (this, enable): (Table, bool)| {
@@ -803,29 +619,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             ))
         })?,
     )?;
-    // `EnableMouseWheel(flag)` / `IsMouseWheelEnabled()` — the wheel's own gate, a separate flag
-    // from `EnableMouse` in the reference and separate here (decision 1198).
-    //
-    // The flag is real and round-trips. **The dispatch is NOT gated on it yet, deliberately.**
-    // Our wheel dispatch keys off "does this frame carry an `OnMouseWheel` handler", walking up to
-    // the nearest ancestor that does — more permissive than the reference, which also requires the
-    // frame to be wheel-enabled so a scroll region can hand the wheel to the window behind it
-    // without tearing its handler out.
-    //
-    // Gating it today would break our own UI: 44 `OnMouseWheel` sites across 14 shipped files and
-    // **not one of them declares `enableMouseWheel`**, because the loader has never read that
-    // attribute. The condition to flip it is concrete rather than someday — teach the loader the
-    // attribute, declare it on those 44 sites, then gate. Until then this is a disclosed superset
-    // (1189's argument, pointed the other way), and the two corpus addons that stopped on the
-    // missing *method* are unblocked either way.
-    // EnableDrawLayer(layer) / DisableDrawLayer(layer) — Frame method table `0x878ec0`, entries
-    // `0x7755b0` / `0x775680`, between `IsToplevel` and `Show`. See [`crate::widget::Frame`]'s
-    // `disabled_layers` for what was read and why the mask lives on the frame.
-    //
-    // An unknown layer name is a NO-OP here rather than a raise. That is the honest state, not a
-    // decision: `draw_layer_from_str` is the same parser `SetDrawLayer` and `CreateTexture` use,
-    // and what the reference does with an unparseable name in THIS pair has not been read out of
-    // the binary. Both corpus callers (pfUI, MoveAnything) pass literals from the five-name set.
+    // EnableDrawLayer / DisableDrawLayer (`0x7755b0`/`0x775680`): the frame's layer mask. An
+    // unknown layer name is a no-op here; the reference's handling of one is untraced.
     for (name, disable) in [("EnableDrawLayer", false), ("DisableDrawLayer", true)] {
         m.set(
             name,
@@ -850,6 +645,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             })?,
         )?;
     }
+    // EnableMouseWheel / IsMouseWheelEnabled: the wheel's own flag, separate from `EnableMouse` as
+    // in the reference, and the one the wheel hit test gates on.
     m.set(
         "EnableMouseWheel",
         lua.create_function(|lua, (this, enable): (Table, bool)| {
@@ -871,9 +668,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             ))
         })?,
     )?;
-    // Clamp-to-screen (`0x776c00`/`0x776cb0`, geometry flags bit4): the layout resolve
-    // keeps the frame's assembled rect inside the window, size preserved. GameTooltip frames
-    // default true by construction (widget::Frame::clamped_to_screen — decision 0352).
+    // Clamp-to-screen (`0x776c00`/`0x776cb0`, geometry flags bit 4): the layout resolve keeps the
+    // frame's rect inside the window, size preserved.
     m.set(
         "SetClampedToScreen",
         lua.create_function(|lua, (this, clamp): (Table, bool)| {
@@ -897,10 +693,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             ))
         })?,
     )?;
-    // Hit-rect insets — the MOUSE rect only (widget::Frame::hit_rect_insets): the hit test shrinks
-    // the resolved rect by these four before testing the cursor, and nothing else reads them, so a
-    // frame's geometry/draw/anchor answers are unchanged. The ref sets them wherever a button's
-    // frame is larger than its art (the micro buttons' 18 px empty header).
+    // Hit-rect insets shrink only the mouse hit rect; geometry, drawing and anchors ignore them.
     m.set(
         "SetHitRectInsets",
         lua.create_function(
@@ -926,12 +719,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Parse a Lua `SetBackdrop` table into a [`Backdrop`] (`0x7776e0`'s key reads). The keys read —
-/// exactly the compiled reader's set — are `bgFile`/`edgeFile` (strings), `tile` (boolean, default
-/// false), `tileSize`/`edgeSize` (numbers; a missing number leaves the ctor default: tileSize 0,
-/// edgeSize 32), and `insets{left,right,top,bottom}` (numbers, each default 0). A non-string file or
-/// non-number size is treated as absent (the client's per-key type gate). Colors stay the ctor
-/// white — SetBackdrop never reads a color key; the color setters do that.
+/// Parse a `SetBackdrop` table (`0x7776e0`): exactly the reference's keys, a wrong-typed one read
+/// as absent and a missing one left at the ctor default (`edgeSize` 32); no colour keys.
 fn backdrop_from_table(t: &Table) -> mlua::Result<Backdrop> {
     let mut bd = Backdrop::default();
     if let Ok(Value::String(s)) = t.get::<Value>("bgFile") {
@@ -940,7 +729,6 @@ fn backdrop_from_table(t: &Table) -> mlua::Result<Backdrop> {
     if let Ok(Value::String(s)) = t.get::<Value>("edgeFile") {
         bd.edge_file = Some(s.to_str()?.to_string());
     }
-    // `tile` — Lua truthiness (nil/false ⇒ false; a missing key reads as Nil).
     bd.tile = !matches!(
         t.get::<Value>("tile").unwrap_or(Value::Nil),
         Value::Nil | Value::Boolean(false)
@@ -998,8 +786,7 @@ fn set_shown(lua: &Lua, this: &Table, shown: bool) -> mlua::Result<()> {
     Ok(())
 }
 
-/// This frame's child frames as stable ids, in the arena's insertion order — the one walk
-/// `GetChildren` and `GetNumChildren` share (see their comment on why they must share it).
+/// The frame's child ids in link order, the one walk `GetChildren` and `GetNumChildren` share.
 fn children_of(lua: &Lua, this: &Table) -> mlua::Result<Vec<u32>> {
     let h = frame_handle_of(lua, this)?;
     let mut model = lua.app_data_mut::<Model>().expect("model");
@@ -1009,25 +796,10 @@ fn children_of(lua: &Lua, this: &Table) -> mlua::Result<Vec<u32>> {
     Ok(children.into_iter().map(|c| model.frame_id(c)).collect())
 }
 
-/// This frame's live regions as stable ids, in creation order — **the title region and detached
-/// ones excluded** — the one walk `GetRegions` and `GetNumRegions` share.
-///
-/// Both exclusions are the client's list, not tidiness:
-///
-/// - **Detached.** `SetParent(nil)` reaches `0x77fd55` → the removal virtual `0x76a7f0`, which
-///   unlinks the node and frees it, and then skips every re-link. We keep the entry only so the
-///   arena can still free the slot; reporting it would hand an addon an object the reference never
-///   would, and `StripTextures`-shaped code would "strip" a region already off the screen.
-/// - **The title region.** Its two creation paths (`0x773910`, `0x769b79`) dispatch a vtable slot
-///   that is a bare `[this+0x9c] = parent` and never reach the linker at all, so it was never in
-///   this list — corroborated by `Hide`/`Show` needing an explicit extra `[frame+0xa8]` case
-///   *because* the walk misses it. Ours is in [`crate::widget::Frame::regions`] so that
-///   `WidgetArena::destroy` still frees it, which makes that a representation detail this walk
-///   must not leak.
-///
-/// A Button's label and its four state textures are deliberately NOT excluded: they link through
-/// `0x77fd10` like any other region in the reference, and ours go through `create_region` like any
-/// other region here.
+/// The frame's region ids in link order, the one walk `GetRegions` and `GetNumRegions` share. A
+/// detached region is left out (`SetParent(nil)` unlinks it, `0x76a7f0`), and so is the title
+/// region, which never reaches the linker `0x77fd10` (`0x773910`, `0x769b79`); a Button's label
+/// and state textures are in.
 fn regions_of(lua: &Lua, this: &Table) -> mlua::Result<Vec<u32>> {
     let h = frame_handle_of(lua, this)?;
     let mut model = lua.app_data_mut::<Model>().expect("model");
@@ -1046,42 +818,23 @@ fn regions_of(lua: &Lua, this: &Table) -> mlua::Result<Vec<u32>> {
     Ok(live.into_iter().map(|r| model.region_id(r)).collect())
 }
 
-/// One backdrop colour channel, the reference's own conversion (`SetBackdropColor 0x777d30` /
-/// `SetBackdropBorderColor 0x7780d0` — instruction-identical bar the delegate).
-///
-/// **r/g/b are UNGATED and alpha is not**, and that asymmetry is the whole of this function:
-///
-///  · r/g/b (`lua` indices 2/3/4) go through a bare `lua_tonumber`, so a `nil` channel is `0.0`
-///    and the call completes — no raise. ShaguTweaks `helpers.lua:248` passes `color.r` from a
-///    table that does not always have one, and benilla raised on it, killing the addon.
-///  · alpha (index 5) is `lua_isnumber`-gated at `0x778227` with `1.0f` staged at `0x778220`, so a
-///    **missing or nil** alpha is OPAQUE. Reading the asymmetry the other way — nil alpha as `0.0`
-///    like its neighbours — would turn every one of those borders transparent, which is a worse
-///    bug than the raise it replaced and would look like a rendering fault.
-///
-/// Then the reference clamps to `[0,1]` with **NaN landing on 1.0** (the compare's unordered arm
-/// takes the high clamp), and quantizes `×255 + 0.5` through `__ftol` — round-half-up, not the
-/// bare truncate `SetChatWindowColor 0x4a14f0`'s colour path uses. The field is a packed
-/// `0xAARRGGBB`
-/// byte quad, so nothing finer survives the store and we quantize on the way in rather than
-/// pretend to a precision `GetBackdropColor` could not read back.
+/// One backdrop colour channel as `SetBackdropColor` (`0x777d30`) and `SetBackdropBorderColor`
+/// (`0x7780d0`) convert it: r, g, b through a bare `lua_tonumber` (nil is 0), alpha gated by
+/// `lua_isnumber` with 1.0 staged (`0x778220`, `0x778227`); clamped to 0..1 with NaN at 1, then
+/// stored as a byte, rounded half up (`×255 + 0.5`, `__ftol`).
 fn backdrop_channel(lua: &Lua, v: Option<Value>, gated: bool) -> f32 {
     let x = if gated {
-        // `lua_isnumber` — a number or a numeric string; anything else takes the staged default.
         v.and_then(|v| lua.coerce_number(v).ok().flatten())
             .unwrap_or(1.0)
     } else {
         crate::script::binding_abi::coerced_number(lua, v)
     };
     let clamped = if x.is_nan() { 1.0 } else { x.clamp(0.0, 1.0) };
-    // `×255 + 0.5` then `__ftol` (truncate toward zero) = round-half-up over `[0,1]`.
     let byte = (clamped * 255.0 + 0.5) as u8;
     f32::from(byte) / 255.0
 }
 
-/// The four channels of a backdrop colour setter, in the reference's own gating (see
-/// [`backdrop_channel`]). Takes the raw stack so a missing argument and an explicit `nil` reach
-/// the same place they do there.
+/// A backdrop colour setter's four channels; a missing argument and an explicit nil read alike.
 fn backdrop_color(lua: &Lua, args: mlua::MultiValue) -> [f32; 4] {
     let a: Vec<Value> = args.into_iter().collect();
     [
diff --git a/crates/benilla-ui/src/script/object/layout_methods.rs b/crates/benilla-ui/src/script/object/layout_methods.rs
index 9fde3ee1..b646c2fe 100644
--- a/crates/benilla-ui/src/script/object/layout_methods.rs
+++ b/crates/benilla-ui/src/script/object/layout_methods.rs
@@ -1,7 +1,4 @@
-//! Frame method-table cluster: anchoring and size — `SetPoint`/`ClearAllPoints`/`GetPoint`/
-//! `SetAllPoints`/`SetWidth`/`SetHeight`/`GetWidth`/`GetHeight` and the resolved-edge readers
-//! (`GetLeft`/`GetRight`/`GetTop`/`GetBottom`). Split out of [`super`] purely for size — see
-//! its module doc for the shared id/handle plumbing and method-table wiring.
+//! Frame methods: anchors, size, and the resolved geometry readers.
 
 use mlua::{Lua, MultiValue, Table, Value};
 
@@ -13,9 +10,8 @@ use crate::widget::FrameHandle;
 use super::anchor_args::{parse_set_all_points, parse_set_point, resolve_rel_target, UNNAMED};
 use super::{frame_handle_of, frame_parent_token_base, frame_wrapper, point_name};
 
-/// The two things the shared ladder needs off the receiver, read under **one short** `Model`
-/// borrow that is dropped before the `_G` read: the name the reference puts in its error strings
-/// (`GetName`, else the literal `"<unnamed>"`), and the name a leading `$parent` expands to.
+/// The receiver's name for the error strings and its `$parent` base, read under one short `Model`
+/// borrow that ends before the ladder's `_G` read.
 fn frame_ladder_context(lua: &Lua, h: FrameHandle) -> (String, String) {
     let model = lua.app_data_ref::<Model>().expect("model");
     let who = model
@@ -26,7 +22,7 @@ fn frame_ladder_context(lua: &Lua, h: FrameHandle) -> (String, String) {
     (who, frame_parent_token_base(&model, h))
 }
 
-/// Populate `m`'s layout (anchor/size) methods (see the module doc).
+/// Populate `m`'s anchor and size methods.
 pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
     // Layout: SetPoint / ClearAllPoints / SetWidth / SetHeight / GetWidth / GetHeight
     set_shared(
@@ -39,19 +35,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
     set_shared(lua, m, Side::Frame, "ClearAllPoints", |lua, this: Table| {
         let h = frame_handle_of(lua, &this)?;
         let mut model = lua.app_data_mut::<Model>().expect("model");
-        // Every layout setter here follows one law: mutate ONLY on an actual value change,
-        // and report the change to the tier-1 epoch (`touch_layout`). The compare is what
-        // keeps an idempotent per-frame caller (the classic OnUpdate re-SetPoint idiom) from
-        // pinning the gate open — the same absorption the fingerprint gives, paid once at
-        // the write instead of per-frame over the whole model.
-        //
-        // **And it NAMES its node** (decision 2114, completing 1625's migration). Dropping
-        // every anchor is a retarget whose NEW target list is empty, and both lists are right
-        // here — so the cached graph's edges get unlinked instead of thrown away. Left on the
-        // conservative touch, this was the one recurring `[layout-derive]` site in a live
-        // hover sweep: `Bagnon_AnchorTooltip` opens with `GameTooltip:ClearAllPoints()` and
-        // then asks `frame:GetLeft()`, so the whole graph was re-derived INSIDE the handler,
-        // once per hovered item, and billed to `[ui-handlers]`' `OnEnter`.
+        // Every layout setter mutates only on a real change, so a per-frame caller setting the
+        // same value never reopens the layout gate. Clearing is a retarget to no targets.
         let old: Option<Vec<u32>> = match model.layout_inputs.get_mut(&h) {
             Some(input) if !input.anchors.is_empty() => {
                 let old = input.anchors.iter().map(|a| a.relative_to).collect();
@@ -65,10 +50,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         }
         Ok(())
     })?;
-    // GetPoint([n]) → point, relativeTo, relativePoint, xOfs, yOfs — the n-th (1-based, default
-    // first) anchor. relativeTo is nil when the target is the screen root (the client returns
-    // UIParent there; ours is the distinct `script::SCREEN` sentinel, which has no wrapper of its
-    // own — the arena's `UIParent` frame is a different handle — stated, a consensus-list call).
+    // GetPoint([n]) → point, relativeTo, relativePoint, x, y of the n-th anchor (default 1);
+    // relativeTo is nil for a screen-root anchor, since `SCREEN` has no wrapper.
     set_shared(
         lua,
         m,
@@ -102,10 +85,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             ))
         },
     )?;
-    // GetNumPoints() → how many anchors this frame carries. On the Region map (`0x87c9b8`), so
-    // every widget answers it — the region twin shipped first and noted this side was missing;
-    // collapsing the map to one implementation each (decision 1501) is what made the gap fatal
-    // rather than merely absent, and this is the arm it was missing.
+    // GetNumPoints(): on the Region method table (`0x87c9b8`), so every widget answers it.
     set_shared(lua, m, Side::Frame, "GetNumPoints", |lua, this: Table| {
         let h = frame_handle_of(lua, &this)?;
         let model = lua.app_data_ref::<Model>().expect("model");
@@ -114,8 +94,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             .get(&h)
             .map_or(0, |i| i.anchors.len() as i64))
     })?;
-    // SetAllPoints([relativeTo]) — pin TOPLEFT+BOTTOMRIGHT to the target (default: the parent),
-    // the XML `setAllPoints="true"` behavior as a method (`0x767800`'s SetAllPoints path).
+    // SetAllPoints([relativeTo]): pins TOPLEFT and BOTTOMRIGHT to the target, default the parent,
+    // as XML `setAllPoints="true"` does (`0x767800`).
     set_shared(
         lua,
         m,
@@ -123,8 +103,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         "SetAllPoints",
         |lua, (this, rest): (Table, MultiValue)| {
             let h = frame_handle_of(lua, &this)?;
-            // `who`/`$parent` first, then the `_G` read, then the guard — see `set_point` and
-            // `object::NamedTarget`.
+            // `who` and `$parent`, then the `_G` read, then the model guard, as in `set_point`.
             let (who, base) = frame_ladder_context(lua, h);
             let target = parse_set_all_points(lua, rest.front(), &base);
             let mut model = lua.app_data_mut::<Model>().expect("model");
@@ -163,7 +142,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             let changed = input.width.to_bits() != w.to_bits();
             input.width = w;
             if changed {
-                // A size write moves no edge and no roster membership (decision 1388).
+                // A size write moves no edge and no roster membership.
                 model.touch_layout_frame(h);
             }
             model.note_authored_size(h);
@@ -188,9 +167,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             Ok(())
         },
     )?;
-    // **No `SetSize`.** It is an Era geometry verb, in neither the Frame nor the Region method
-    // table of 1.12 — and neither the stock chain nor either addon corpus writes it (decision
-    // 2142's census). The two setters above are the era's whole size surface.
+    // No `SetSize`: neither 1.12 method table has it.
     set_shared(lua, m, Side::Frame, "GetWidth", |lua, this: Table| {
         let h = frame_handle_of(lua, &this)?;
         settle(lua);
@@ -204,11 +181,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         Ok(size_read(&model, h, false))
     })?;
 
-    // GetCenter() → centerX, centerY — the resolved rect's center in LOCAL units (y-up; screen ÷
-    // the frame's effective scale — the client's convention: coordinate getters report the frame's
-    // own scaled space, and callers divide GetCursorPosition (screen px) by GetEffectiveScale to
-    // meet them there; the ref world map's hover math does exactly that). nil pair before the
-    // first resolve, like the edge readers.
+    // GetCenter(): the resolved rect's centre in the frame's own units (screen ÷ effective scale,
+    // y-up), as the reference's coordinate getters report; nil before the first resolve.
     set_shared(lua, m, Side::Frame, "GetCenter", |lua, this: Table| {
         let h = frame_handle_of(lua, &this)?;
         settle(lua);
@@ -223,14 +197,11 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })
     })?;
 
-    // GetEffectiveScale() — the frame's real effective scale (parentScale · ownScale, the arena's
-    // propagated product). The ROOT factor is 1, and that is not because benilla lacks a `uiScale`
-    // CVar (it has one, `cvars.rs`, default 0.9): the dial is applied at the RASTER seam — it sets
-    // how many UI units tall the virtual screen is, `768/uiScale` (`ui_script::seam_scale`, 0584) —
-    // rather than as a scale on UIParent. So every coordinate the VM hands Lua is already in those
-    // units, `GetCursorPosition()` included, and the reference's
-    // `GetCursorPosition()/GetEffectiveScale()` transcriptions convert screen→local correctly with
-    // a root of 1; a SetScale'd subtree (the windowed world map) still reports its true factor.
+    // GetEffectiveScale(): parent scale times own scale, from a root of 1: `uiScale` is applied at
+    // the raster seam (a screen `768/uiScale` units tall), so every coordinate Lua sees,
+    // `GetCursorPosition()` included, is already in UI units. The reference instead makes
+    // `uiScale` `UIParent`'s own scale (`0x494550` calls `SetScale`), so there
+    // `UIParent:GetEffectiveScale()` answers it.
     m.set(
         "GetEffectiveScale",
         lua.create_function(|lua, this: Table| {
@@ -240,11 +211,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetLeft/GetRight/GetTop/GetBottom — the frame's RESOLVED edges in LOCAL units (y-up, so
-    // GetBottom is height-from-screen-bottom, the era semantics; `GetRect 0x768320`'s Lua faces,
-    // layout.rs's module doc; screen ÷ effective scale like GetCenter). `nil` before the first
-    // resolve — callers treat that as "not laid out yet" (the ref's own FauxScrollFrame code
-    // nil-checks these too).
+    // GetLeft/GetRight/GetTop/GetBottom: the resolved edges in the frame's own units, y-up from
+    // the screen bottom (`GetRect 0x768320`); nil before the first resolve.
     for (name, pick) in [
         ("GetLeft", 0u8),
         ("GetRight", 1u8),
@@ -269,39 +237,10 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
     Ok(())
 }
 
-/// The frame's effective scale, ε-guarded (a zero would poison the local-unit division).
-/// **Resolve the layout graph NOW if anything has moved since the last pass.**
-///
-/// The client answers a geometry query against current layout; ours cached rects in a per-frame
-/// `resolve()` pass, so a query made EARLIER IN THE SAME CALL STACK than that pass read nil. That
-/// is not an edge case — it is what every menu does. `Dewdrop-2.0.lua` (embedded in ~65 corpus
-/// addons) creates its menu frame, anchors it, shows it and then measures it inside one `OnClick`:
-///
-/// ```lua
-/// local left = frame:GetLeft()                                              -- l.1942, nil for us
-/// frame:SetPoint(point, parent, relativePoint, curX - left - width / 2, 0)  -- l.1960, dies
-/// ```
-///
-/// **97 of the 108 addons that drew and then raised on being touched died on that one line.** No
-/// missing verb: `GetLeft` was always there, and always answered nil.
-///
-/// Cheap on a SETTLED tree: `resolve_layout`'s tier-1 gate is one epoch comparison that returns
-/// immediately when nothing has been touched, so a run of getters pays a compare each.
-///
-/// **The interleaved case is not, and this is measured rather than asserted.** A write bumps the
-/// epoch, so `SetPoint; GetLeft; SetPoint; GetLeft; …` resolves the whole graph once per iteration.
-/// Timed on a 200-frame tree: 30 alternating pairs cost **1.41 ms** against **54 µs** for the same
-/// writes with a single read at the end — ~26x, about 47 µs per settle, and the per-settle half
-/// scales with the GRAPH, not the loop.
-///
-/// That is exactly the shape Dewdrop's menu builder has, so opening a menu pays it once. It buys a
-/// menu that works at all, which is the trade taken here. If it ever reads as a hitch, the fix is a
-/// narrower resolve (the queried frame's subtree), not a return to the stale cache.
-///
-/// **It deliberately does NOT fire `OnSizeChanged`.** That drain runs Lua handlers, and re-entering
-/// Lua from inside a binding is how a borrow panic or an unbounded recursion happens. The
-/// size-change queue is drained by the next real `UiScript::resolve`, one tick later than the
-/// reference's per-rect-application fire (`ApplyRect 0x76b580`). Stated rather than hidden.
+/// Resolve the layout now if anything moved, as the reference answers a geometry query against
+/// current layout; a settled tree costs one epoch compare. Deviation: `OnSizeChanged` fires at the
+/// next `UiScript::resolve`, a tick after the reference's (`ApplyRect 0x76b580`), because running
+/// Lua handlers inside a binding risks a borrow panic or unbounded recursion.
 fn settle(lua: &Lua) {
     let mut model = lua.app_data_mut::<Model>().expect("model");
     crate::script::UiScript::resolve_layout(&mut model);
@@ -320,10 +259,8 @@ pub(crate) fn eff_scale(model: &Model, h: FrameHandle) -> f32 {
     }
 }
 
-/// `GetWidth`/`GetHeight`: the resolved rect's span in LOCAL units (screen ÷ effective scale — the
-/// client returns the value as authored, and `SetWidth(w)` on a scaled frame resolves to `w·scale`
-/// screen px) if `resolve` has produced one, else the explicit size the frame was given
-/// (`SetWidth`/`SetHeight`, already local) — matching the client's "0 = derive".
+/// `GetWidth`/`GetHeight`: the resolved span in the frame's own units (screen ÷ effective scale),
+/// else the size it was given, where 0 means derived, as in the reference.
 fn size_read(model: &Model, h: FrameHandle, width: bool) -> f32 {
     if let Some(r) = model.resolved.get(&h) {
         let span = if width { r.width() } else { r.height() };
@@ -336,15 +273,13 @@ fn size_read(model: &Model, h: FrameHandle, width: bool) -> f32 {
         .unwrap_or(0.0)
 }
 
-/// `SetPoint(point [, relativeTo [, relativePoint]] [, x, y])` — `0x7a2540`, whose argument ladder
-/// (and whose five raises) live in [`super::anchor_args`] because the reference runs **one**
-/// function for frames and regions alike. What is this side's own is only what the reference reads
-/// off a *frame*: the layout parent's default id, and the anchor list the commit writes.
+/// `SetPoint` (`0x7a2540`) for a frame: the argument ladder is [`super::anchor_args`], shared with
+/// regions; this side supplies the default parent and commits the anchor.
 fn set_point(lua: &Lua, this: &Table, args: &MultiValue) -> mlua::Result<()> {
     let h = frame_handle_of(lua, this)?;
     let (who, base) = frame_ladder_context(lua, h);
-    // The `_G` read inside the ladder runs with NO model guard alive — the reference's read is a
-    // gettable, so an `__index` on `_G` can run Lua that calls back in (`object::NamedTarget`).
+    // No model guard is alive across the ladder: its `_G` read is a `lua_gettable`, and an
+    // `__index` can call back in.
     let p = parse_set_point(lua, args, &who, &base)?;
 
     let mut model = lua.app_data_mut::<Model>().expect("model");
@@ -355,12 +290,8 @@ fn set_point(lua: &Lua, this: &Table, args: &MultiValue) -> mlua::Result<()> {
 
     let input = model.layout_inputs.entry(h).or_default();
     let new = Anchor::new(point, rel_to_id, rel_point, x, y);
-    // No-op detection must mirror the retain+push below EXACTLY (the fingerprint hashes the vec
-    // in order, so a same-anchor call that would still REORDER the vec is a real change): a call
-    // is idempotent only when the identical anchor already sits at the tail and no earlier entry
-    // carries this point. Anchor's derived PartialEq compares f32 by value, which calls -0.0 ==
-    // 0.0 where the fingerprint's bit-compare would not — compare bits, or the verify assert
-    // trips on that (authored-XML-real) edge.
+    // A no-op only when the identical anchor is already last and no earlier one has this point,
+    // mirroring the retain and push below; bits compared, as the fingerprint tells -0.0 from 0.0.
     let same_at_tail = input
         .anchors
         .last()
@@ -369,14 +300,8 @@ fn set_point(lua: &Lua, this: &Table, args: &MultiValue) -> mlua::Result<()> {
             .iter()
             .any(|a| a.point == point);
     if !same_at_tail {
-        // Value-only unless the target moved (decision 1388) — the per-frame `SetPoint` idiom
-        // (a dragged window, a moving spark) re-points the SAME anchor at the SAME target with new
-        // offsets, so it names its node and the cached graph survives the frame.
-        //
-        // A retarget names its node too now (decision 1625): the edge set is not derivable from a
-        // per-node hash, but it IS derivable from the anchors, and both lists are right here. The
-        // target lists are collected only on the structural path — the value-only one is the hot
-        // idiom and must stay allocation-free.
+        // Target lists are collected only for a retarget: the value-only change is the per-frame
+        // idiom (a dragged window) and must stay allocation-free.
         let structural = anchor_retarget_is_structural(&input.anchors, &new);
         let old_targets: Option<Vec<u32>> =
             structural.then(|| input.anchors.iter().map(|a| a.relative_to).collect());
@@ -397,24 +322,8 @@ fn set_point(lua: &Lua, this: &Table, args: &MultiValue) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Would this `SetPoint` change the node's set of anchor TARGETS — i.e. is it structural?
-///
-/// The layout scope's reverse edges are built from `Anchor::relative_to` (decision 1350): "this
-/// node reads that node's rect". An anchor whose OFFSETS moved is a value change — the node
-/// re-solves and nothing else does, which is exactly what a precise touch claims. An anchor whose
-/// TARGET moved is not: an edge has to disappear and another to appear, and no per-node hash can
-/// say so.
-///
-/// 1388 answered that by throwing the cached graph away. **Since decision 1625 it does not have
-/// to be**: the write site holds both target lists, so the node's edges are re-pointed in place
-/// (`Model::touch_layout_retarget_frame`) and the roster and every other node's hash survive.
-/// What this predicate decides is therefore no longer "value change or catastrophe" but which of
-/// two precise touches to use — and it still earns its place, because the value-only answer is
-/// the hot per-frame idiom and must stay allocation-free.
-///
-/// Mirrors the `retain(point) + push` the setters do. It is value-only in exactly one shape — one
-/// existing anchor carries this point and keeps the same target. Zero (an edge appears) and two or
-/// more (edges disappear) are both structural, and so is any change of target.
+/// Whether this `SetPoint` changes the node's anchor targets, mirroring the setters' retain and
+/// push: value-only exactly when one existing anchor has this point and keeps its target.
 pub(crate) fn anchor_retarget_is_structural(anchors: &[Anchor], new: &Anchor) -> bool {
     let mut same_point = anchors.iter().filter(|a| a.point == new.point);
     match (same_point.next(), same_point.next()) {
@@ -423,9 +332,7 @@ pub(crate) fn anchor_retarget_is_structural(anchors: &[Anchor], new: &Anchor) ->
     }
 }
 
-/// Bit-exact anchor equality — the same lens the layout gate's fingerprint reads anchors through
-/// (`InputFingerprint::anchors` feeds `f32::to_bits`), so the setters' no-op detection and the
-/// gate can never disagree about whether a write "changed" something.
+/// Bit-exact anchor equality, as the layout gate's fingerprint compares, so the two always agree.
 pub(crate) fn anchor_bits_eq(a: &Anchor, b: &Anchor) -> bool {
     a.point == b.point
         && a.relative_to == b.relative_to
@@ -434,8 +341,7 @@ pub(crate) fn anchor_bits_eq(a: &Anchor, b: &Anchor) -> bool {
         && a.y_off.to_bits() == b.y_off.to_bits()
 }
 
-/// The default `relativeTo` id for a `SetPoint` with no explicit target: the frame's parent id, or
-/// [`SCREEN`] if it is top-level (the client anchors top-level frames to `UIParent`/the screen root).
+/// The default `relativeTo`: the parent, or [`SCREEN`] for a top-level frame (`0x76c6e0`).
 fn default_parent_id(model: &mut Model, h: FrameHandle) -> u32 {
     match model.arena.frame(h).and_then(|f| f.parent) {
         Some(p) => model.frame_id(p),
diff --git a/crates/benilla-ui/src/script/object/movable.rs b/crates/benilla-ui/src/script/object/movable.rs
index c3ac0ce5..fbfa6ff8 100644
--- a/crates/benilla-ui/src/script/object/movable.rs
+++ b/crates/benilla-ui/src/script/object/movable.rs
@@ -1,82 +1,14 @@
-//! Frame method-table cluster: the movable/resizable window family — `SetMovable`/`IsMovable`,
-//! `StartMoving`/`StopMovingOrSizing`, `SetUserPlaced`/`IsUserPlaced`, `SetResizable`/
-//! `IsResizable`. Split out of [`super`] purely for size — see its module doc for the shared
-//! id/handle plumbing and method-table wiring.
+//! Frame methods: movable and resizable windows, and the drag pumps behind `StartMoving` and
+//! `StartSizing`. The gesture that usually calls them, `OnDragStart`/`OnDragStop` (`0x76bf70`/
+//! `0x76c040`), is [`crate::script::cursor`]'s.
 //!
-//! This is "drag this bar somewhere", and after events it is the most-used addon frame feature.
-//! The canonical idiom is four lines, of which only the two engine verbs were missing here:
+//! The flags are bits of `[frame+0xb4]`, set by `0x76a3c0`: movable `0x100`, resizable `0x200`,
+//! userPlaced `0x1000`. A drag (`0x7652b0`) re-anchors the frame to one TOPLEFT against the screen
+//! root at its current rect (`0x768430`), raises it, sets userPlaced and takes the one drag slot
+//! (`root+0xcfc`). The pump (`0x7655b0`) adds each cursor delta, over the frame's scale, straight
+//! into that anchor's offsets (`0x768710` case 4), so stopping (`0x765640`) writes nothing.
 //!
-//! ```lua
-//! f:SetMovable(true)
-//! f:RegisterForDrag("LeftButton")
-//! f:SetScript("OnDragStart", function() this:StartMoving() end)
-//! f:SetScript("OnDragStop",  function() this:StopMovingOrSizing() end)
-//! ```
-//!
-//! and that layering is the reference's own: `RegisterForDrag 0x776d60` + the threshold-gated
-//! `OnDragStart`/`OnDragStop` pair (`0x76bf70`/`0x76c040`, our decision 0216 §3 —
-//! [`crate::script::cursor`], dispatched from [`crate::script::pointer`]) are a **separate**
-//! system from the engine move below. The gesture decides *when* the handlers run; this module
-//! owns only what happens between `StartMoving` and `StopMovingOrSizing`.
-//!
-//! ## The mechanism
-//!
-//! The three flags are bits of the frame's flag word `[frame+0xb4]`, all written by the one
-//! generic setter `0x76a3c0` (`if (v) flags |= mask; else flags &= ~mask;` — no calls, no side
-//! effects): **movable `0x100`** (`SetMovable 0x776420` / `IsMovable 0x7764d0`), **resizable
-//! `0x200`** (`SetResizable 0x776590` / `IsResizable 0x776640`), **userPlaced `0x1000`**
-//! (`SetUserPlaced 0x776a50` / `IsUserPlaced 0x776b40`). The XML attributes land on the same
-//! setter (`movable="true"` → `0x76a3c0(0x100)`, `resizable="true"` → `0x200`), which is why the
-//! loader now *calls* these instead of warning.
-//!
-//! `StartMoving 0x776700` tests the movable bit and raises when it is clear, then enters the drag
-//! at `0x7652b0`, which `Raise()`s the frame, **sets the userPlaced bit itself**, and records the
-//! whole drag in ONE root-side slot: `root+0xcfc` = the dragged frame, `+0xd00` = the drag type
-//! (Lua `StartMoving` passes **3**), `+0xd08/+0xd0c` = the cursor at the last sample. One slot
-//! means one drag: there is no second frame to move, which is why `StartMoving` carries a
-//! `root+0xcfc != 0` guard at `7767e8` and why `StopMovingOrSizing 0x776990` compares
-//! `[root+0xcfc] == self` before clearing.
-//!
-//! Movement is a **pump**, run from the mouse-move handler: `0x7655b0` (a diffed-bit-exact
-//! PRIMITIVE) takes `dx = x − root+0xd08`, `dy = y − root+0xd0c`, and — only if either is
-//! non-zero — applies them and re-centers the sample. The application (`0x76a660` → the 9-case
-//! `0x768710`, also a diffed-bit-exact PRIMITIVE) selects on the 3×3 region the drag grabbed:
-//! the eight edge/corner cases resize, and **case 4, the plain move, accumulates the scaled delta
-//! straight into the anchor's offsets in place** — `xOffset += dx/scale`, `yOffset += dy/scale`
-//! (`CAnchor+0x4`/`+0x8`) — then invalidates the layout (`0x7680e0`).
-//!
-//! Two consequences worth stating, because both are easy to get wrong:
-//!
-//! - **Nothing is written at stop.** `0x765640` is a fifteen-byte state clear (`root+0xcfc = 0;
-//!   root+0xd00 = 0`) — there is no `SetPoint`, no `ClearAllPoints`, no rewrite of the anchor set
-//!   to a single point. The frame keeps where it was dragged to because the *anchors themselves*
-//!   were being moved the whole time, so `GetPoint()` afterwards reports the frame's own point
-//!   with the dragged offsets — exactly what an addon then saves.
-//! - **The mouse button does not end a Lua move.** The mouse-up handler `0x766420` auto-stops
-//!   only drag types 1 and 2 (the built-in title-bar/edge drags); type 3 — the one `StartMoving`
-//!   starts — must be stopped by an explicit `StopMovingOrSizing`. That is why the idiom above
-//!   wires `OnDragStop` at all.
-//!
-//! ## What benilla does NOT take from that, and why
-//!
-//! - **All anchors translate, not just one.** The case-4 accumulate could be read as hitting a
-//!   single anchor record; that reading is a composition of verified pieces, not a recorded
-//!   finding, and a one-anchor translation would *deform* a frame stretched between two anchors
-//!   instead of moving it. Every movable frame in practice carries exactly one anchor, where the
-//!   two readings are identical, so translating the whole set is the same behaviour everywhere it
-//!   is observable and the sane behaviour where it is not.
-//! - **No clamp rebate.** `0x768710` rebates the residual delta when the clamp pushes back
-//!   (`SetClampedToScreen`); we do not, so dragging a clamped frame into the screen edge and back
-//!   out can lag the cursor. Named, not hidden — the rebate is one of the two halves of that
-//!   primitive we have not transcribed (the other is the eight resize cases).
-//! - **The `Raise()` is wired** (it used to be listed here as a deferral): `0x7652b0` raises the
-//!   dragged frame before it takes the drag slot, and [`start_moving`] does the same through
-//!   [`super::toplevel::raise`]. Like every raise it is occlusion-gated and confined to the frame's
-//!   own stratum, so grabbing a movable window that overlaps nothing still changes no draw order.
-//! - **The resize drag is built** (`StartSizing 0x776830` + [`advance_size`]), including the
-//!   min/max clamp and its rebate; what is *not* transcribed is which edges travel — the reference
-//!   collapses the frame to one planted TOPLEFT anchor at `StartSizing` and we keep the authored
-//!   anchor set, which [`advance_size`]'s own note states rather than hides.
+//! Here nothing re-anchors: a move translates every authored anchor, and a resize keeps the set.
 
 use mlua::{Lua, MultiValue, Table, Value};
 
@@ -86,29 +18,15 @@ use crate::widget::FrameHandle;
 use super::frame_handle_of;
 use super::layout_methods::eff_scale;
 
-/// The one in-flight `StartMoving` — the client's `root+0xcfc`/`+0xd08`/`+0xd0c` drag slot, held
-/// in [`Model::moving`] beside the drag gesture that normally drives it.
-///
-/// `sample` is the cursor at the last pump, not at the grab: [`advance_move`] applies the
-/// *difference* and re-centers, which is `0x7655b0`'s own shape. Nothing else is needed, because
-/// the position being edited lives in the frame's anchors rather than here.
-///
-/// Pruning on frame destroy: the same boat as [`Model::drag_registered`] — nothing in this engine
-/// destroys a frame yet; [`advance_move`] ends a move whose frame went away regardless.
+/// The one in-flight move, the reference's drag slot, held in [`Model::moving`].
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub(crate) struct FrameMove {
     /// The frame being moved (`root+0xcfc`).
     frame: FrameHandle,
     /// The cursor position at the last pump (`root+0xd08`/`+0xd0c`), UI px, y-up.
     sample: (f32, f32),
-    /// Whether releasing the mouse ends this move on its own.
-    ///
-    /// **The reference's drag MODE, reduced to the one bit that is observable from Lua.** The
-    /// mouse-up handler `0x766420` auto-cancels modes 1 (modifier-drag) and 2 (title region) and
-    /// leaves mode 3 (`StartMoving`) running until `StopMovingOrSizing`. So a title drag ends on
-    /// release while a scripted
-    /// one outlives the button — which is exactly the distinction this module's own doc already
-    /// records for the drag/move split.
+    /// Whether mouse-up ends the move, the drag mode as Lua sees it: `0x766420` ends modes 1
+    /// (modifier drag) and 2 (title region), never 3 (`StartMoving`).
     pub(crate) auto_stop: bool,
 }
 
@@ -116,8 +34,7 @@ pub(crate) struct FrameMove {
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub(crate) struct FrameSizing {
     frame: FrameHandle,
-    /// The grip the caller named — the EDGES this drag moves. `LEFT` moves the left edge and
-    /// leaves the right where it is, `BOTTOMRIGHT` moves both of those, and so on.
+    /// The edges the named grip moves: `LEFT` the left edge, `BOTTOMRIGHT` the bottom and right.
     left: bool,
     right: bool,
     top: bool,
@@ -125,14 +42,10 @@ pub(crate) struct FrameSizing {
     sample: (f32, f32),
 }
 
-/// Populate `m`'s movable/resizable methods (see the module doc).
+/// Populate `m`'s movable and resizable methods.
 pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
-    // SetMovable(flag) / IsMovable() — flag word bit 0x100 (`0x776420`/`0x7764d0` through the
-    // generic setter `0x76a3c0`). A pure flag write: it moves nothing, and clearing it mid-drag
-    // stops nothing either (the setter has no side effects — `0x76a3c0`); it is the
-    // guard `StartMoving` tests, and the XML `movable="true"` attribute writes the same bit.
-    // mlua's bool conversion is Lua truthiness, so the corpus's `SetMovable(1)` reads as true —
-    // matching the reference binding's own `toboolean` marshal.
+    // SetMovable / IsMovable (`0x776420`/`0x7764d0`): a pure flag write, so clearing it mid-drag
+    // stops nothing. The argument is Lua truthiness, as the reference's `toboolean`.
     m.set(
         "SetMovable",
         lua.create_function(|lua, (this, flag): (Table, bool)| {
@@ -143,8 +56,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         "IsMovable",
         lua.create_function(|lua, this: Table| get_flag(lua, &this, Flag::Movable))?,
     )?;
-    // SetResizable(flag) / IsResizable() — bit 0x200 (`0x776590`/`0x776640`), `SetMovable`'s exact
-    // shape. Stored and reported; no resize DRAG is built (see the module doc).
+    // SetResizable / IsResizable (`0x776590`/`0x776640`): the same pure flag write.
     m.set(
         "SetResizable",
         lua.create_function(|lua, (this, flag): (Table, bool)| {
@@ -155,26 +67,12 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         "IsResizable",
         lua.create_function(|lua, this: Table| get_flag(lua, &this, Flag::Resizable))?,
     )?;
-    // ── The resize-bounds quad — `Set/GetMinResize`, `Set/GetMaxResize` ────────────────────────
+    // ── Resize bounds ──
     //
-    // Frame method table `0x878ec0`: `GetMinResize 0x775f20` · `SetMinResize 0x776020` ·
-    // `GetMaxResize 0x7761a0` · `SetMaxResize 0x7762a0`. Every clause below is from the bytes,
-    // not from the shape of the name:
-    //
-    //  · **The argument gate is `lua_isnumber`, not a strict number** (`0x6f34d0` on BOTH slots 2
-    //    and 3), so a numeric STRING passes and is coerced — while a missing argument, an explicit
-    //    `nil`, a boolean, a table or a non-numeric string fails. Either slot failing raises
-    //    `Usage: %s:SetMinResize(minWidth, minHeight)` (`0x8797b8`) / the `MaxResize` twin
-    //    (`0x8797e4`), with `%s` the frame's name or `<unnamed>`. Arguments past slot 3 are
-    //    ignored; there is no upper arity check.
-    //  · **Stored RAW, and nothing else happens.** After the store-backs each setter is
-    //    `pop/pop/xor eax,eax/pop/…/ret` — no layout invalidate, no dirty mark, no `min > max`
-    //    reconciliation, and the frame's current size is never read. Setting a bound a frame
-    //    already violates does nothing at all until the next drag tick.
-    //  · **Zero return values from the setters; TWO from the getters, always** — `(width, height)`
-    //    as plain numbers, `0, 0` on a frame nobody bounded. Never `nil`: `0.0` is the client's
-    //    unbounded sentinel, so the "unset" answer and the "explicitly unbounded" answer are the
-    //    same answer, by construction.
+    // `SetMinResize 0x776020`, `GetMinResize 0x775f20`, `SetMaxResize 0x7762a0`,
+    // `GetMaxResize 0x7761a0`. Both arguments must pass `lua_isnumber` (`0x6f34d0`), else `Usage:`
+    // (`0x8797b8`/`0x8797e4`); the pair is stored raw, with no layout touch and no `min > max`
+    // check. The getters always answer two numbers, 0 meaning unbounded.
     for (name, upper) in [("MinResize", false), ("MaxResize", true)] {
         m.set(
             format!("Set{name}"),
@@ -186,7 +84,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 };
                 let h = frame_handle_of(lua, &this)?;
                 let pair = (it.next(), it.next());
-                // `lua_isnumber`'s own set: a number, or a string 5.0's `luaV_tonumber` converts.
+                // `lua_isnumber`: a number, or a string Lua 5.0's `luaV_tonumber` converts.
                 let num = |v: &Option<Value>| match v {
                     Some(Value::Number(n)) => Some(*n as f32),
                     Some(Value::Integer(i)) => Some(*i as f32),
@@ -237,17 +135,9 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         )?;
     }
 
-    // SetUserPlaced(flag) / IsUserPlaced() — bit 0x1000 (`0x776a50`/`0x776b40`), the client's "the
-    // user placed this frame; persist its position across sessions" bit, and the one setter of the
-    // three that is GUARDED: `776adb: test ah,0x3` refuses unless the frame is movable OR
-    // resizable, raising the third of this family's error strings.
-    //
-    // **The consumer is [`crate::script::layout_cache`]**, which is where it belongs: persisting a
-    // frame's position is the layout cache's job, not the drag's, and a private position store
-    // here would have put a second one beside the one that should own it. The bit is what that
-    // module enumerates on, so setting it is how a frame opts into being remembered — and the
-    // overwhelmingly common addon shape (set the bit, then save your own coordinates) still works
-    // either way.
+    // SetUserPlaced / IsUserPlaced (`0x776a50`/`0x776b40`): the bit that makes the layout cache
+    // save the frame's position; the one guarded setter, refusing a frame that is neither movable
+    // nor resizable (`0x776adb`).
     m.set(
         "SetUserPlaced",
         lua.create_function(|lua, (this, flag): (Table, bool)| {
@@ -263,9 +153,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             if let Some(f) = model.arena.frame_mut(h) {
                 if f.user_placed != flag {
                     f.user_placed = flag;
-                    // The layout cache's persist cue ([`crate::script::layout_cache`]): a frame
-                    // that has just BECOME user-placed owes the file a row, and one that stopped
-                    // owes it the row's removal. Both are the same "rewrite it" bit.
+                    // Either transition owes the layout cache a rewrite: a row added or removed.
                     model.user_placed_changed = true;
                 }
             }
@@ -276,10 +164,6 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         "IsUserPlaced",
         lua.create_function(|lua, this: Table| get_flag(lua, &this, Flag::UserPlaced))?,
     )?;
-    // StartMoving() — enter the drag (`0x776700` → `0x7652b0`). Raises on a frame that is not
-    // movable, sets the userPlaced bit like the reference's drag-start does, and takes the one
-    // drag slot; a second call while a move is in flight is refused, since there is only ever one
-    // slot to take.
     m.set(
         "StartMoving",
         lua.create_function(|lua, this: Table| {
@@ -288,21 +172,9 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             start_moving(&mut model, h)
         })?,
     )?;
-    // StartSizing(point) — begin a resize drag from a named grip (`0x776830`; the reference's own
-    // caller is `FloatingChatFrame.lua:600`,
-    // `this:GetParent():StartSizing(anchorPoint)`).
-    //
-    // **What is verified and what is read, kept apart on purpose.** Verified: the verb exists, it
-    // takes the grip name, it returns nothing, and `StopMovingOrSizing` ends it (the same slot
-    // clear as a move). Not settled anywhere — the verb only orchestrates, with no inline math — is
-    // WHICH EDGES a given grip moves. Taken here as the plain meaning of an anchor point, which is
-    // how the reference's own caller uses it (its resize grips pass the corner they sit in): the
-    // named edges follow the cursor and the opposite ones stay put. If the bytes ever contradict
-    // that, this comment is where to correct it.
-    //
-    // Four corpus addons reach it through ONE line — `FuBar_Panel.lua:980`, replicated into
-    // FuBar_CorkFu, FuBar_FuXPFu, FuBar_SpellStatusFu and oRA2 — which is 1207's rule and why the
-    // count is not four independent votes.
+    // StartSizing(point) (`0x776830`; stock caller `FloatingChatFrame.lua:600`): a resize from the
+    // named grip, ended by `StopMovingOrSizing`. The reference's per-grip switch (`0x768710`)
+    // moves the named edges with the cursor and keeps the opposite ones.
     m.set(
         "StartSizing",
         lua.create_function(|lua, (this, point): (Table, Option<String>)| {
@@ -318,33 +190,22 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             let p = point.unwrap_or_default().to_ascii_uppercase();
             let (left, right) = (p.contains("LEFT"), p.contains("RIGHT"));
             let (top, bottom) = (p.contains("TOP"), p.contains("BOTTOM"));
-            // The raise and the userPlaced bit are the ENTRY's, not the grip's: `0x7652b0` runs
-            // for every `StartSizing` whatever it was handed, and only the pump's per-grip switch
-            // is selective. So both happen before the grip is looked at.
+            // The raise and userPlaced belong to the drag entry `0x7652b0`, whatever the grip.
             super::toplevel::raise(&mut model, h);
             set_user_placed(&mut model, h);
             let sample = model.cursor_pos;
-            // **`StartSizing("CENTER")` is a MOVE, not a resize** — and it is a real case, not a
-            // caller error. The pump's switch is on the anchor point-id, and case 4 (CENTER) is the
-            // one arm that never touches width or height: it shifts the frame's anchor offsets and
-            // returns before the clamp is ever reached, so a CENTER grip is unbounded by
-            // construction (`0x768bfb`). This file used
-            // to say *"a grip naming no edge would resize nothing; the reference has no such call
-            // and we refuse rather than invent one"* — the bytes have since answered that, and the
-            // answer is the translate below, which is exactly what [`advance_move`] already does.
+            // A CENTER grip is a move: the pump's case 4 shifts the anchor offsets and returns
+            // before the size clamp (`0x768bfb`).
             if p == "CENTER" {
                 model.moving = Some(FrameMove {
                     frame: h,
                     sample,
-                    // `StartSizing` enters at `0x7652b0(frame, 3, …)` — drag mode 3, the one the
-                    // mouse-up handler does NOT auto-cancel — whatever grip it was handed. So a
-                    // CENTER grip outlives the button release, like `StartMoving`'s.
+                    // `StartSizing` enters as drag mode 3 (`0x7652b0`), which mouse-up never ends.
                     auto_stop: false,
                 });
                 return Ok(());
             }
-            // Any other name resolves to no point-id at all, so the pump falls to its default tail
-            // and the drag is inert — started (raised, userPlaced) but moving nothing.
+            // A name that is no point starts an inert drag: raised and userPlaced, moving nothing.
             model.sizing = Some(FrameSizing {
                 frame: h,
                 left,
@@ -356,11 +217,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // StopMovingOrSizing() — leave the drag (`0x776990` → `0x765640`): a state clear, and only
-    // when `self` IS the frame in the slot. Nothing is written back — the pump has been moving the
-    // anchors all along, so the frame simply keeps the last position it was dragged to. Harmless
-    // when nothing is moving, or when something else is (a double call, an addon that also wires
-    // it to OnMouseUp, an OnDragStop that never had a StartMoving).
+    // StopMovingOrSizing (`0x776990` → `0x765640`): clears the slot only when it holds this frame.
     m.set(
         "StopMovingOrSizing",
         lua.create_function(|lua, this: Table| {
@@ -378,8 +235,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Which bit of the frame's flag word a `Set*`/`Is*` pair addresses (`[frame+0xb4]`, written by
-/// `0x76a3c0`) — the three benilla models, as arena fields rather than a packed word.
+/// A bit of the frame's flag word (`[frame+0xb4]`), kept here as an arena field.
 #[derive(Clone, Copy)]
 enum Flag {
     /// `0x100`.
@@ -403,8 +259,7 @@ fn set_flag(lua: &Lua, this: &Table, which: Flag, value: bool) -> mlua::Result<(
     Ok(())
 }
 
-/// `IsMovable`/`IsResizable`/`IsUserPlaced` — the NUMBER 1 or nil, never a boolean (1830,
-/// [`crate::script::binding_abi::flag`]).
+/// `IsMovable`/`IsResizable`/`IsUserPlaced`: 1 or nil, never a boolean.
 fn get_flag(lua: &Lua, this: &Table, which: Flag) -> mlua::Result<Value> {
     let h = frame_handle_of(lua, this)?;
     let model = lua.app_data_ref::<Model>().expect("model");
@@ -417,13 +272,8 @@ fn get_flag(lua: &Lua, this: &Table, which: Flag) -> mlua::Result<Value> {
     ))
 }
 
-/// The family's refusal, named frame and all — the reference's own shape (it formats the frame's
-/// `GetName()`, substituting a literal when the frame is anonymous).
-///
-/// **The text is OURS.** The three `.rdata` addresses are known (`0x879810` StartMoving,
-/// `0x879828` StartSizing, `0x879844` SetUserPlaced) but not the strings
-/// at them — only the truncated IDA symbol stubs `aFrameSIsNotMov` / `aFrameSIsNotRes` /
-/// `aFrameSIsNotM_0`, which is what this wording is shaped after. Nothing should match on it.
+/// The family's refusal, naming the frame as the reference does. The wording is ours: the strings
+/// at `0x879810`, `0x879828` and `0x879844` are unread, known only by their symbol names.
 fn not_flagged(model: &Model, h: FrameHandle, want: &str) -> mlua::Error {
     let who = model
         .arena
@@ -433,46 +283,31 @@ fn not_flagged(model: &Model, h: FrameHandle, want: &str) -> mlua::Error {
     mlua::Error::runtime(format!("Frame {who} is not {want}"))
 }
 
-/// `StartMoving()`'s body (`0x776700` → `0x7652b0`): refuse a frame that is not movable, refuse a
-/// second move while one is in flight (there is one drag slot), **raise**, then take the slot —
-/// setting the userPlaced bit, which the reference's drag-start does itself rather than leaving to
-/// `SetUserPlaced`.
+/// `StartMoving` (`0x776700` → `0x7652b0`): errors on a frame that is not movable (`0x77678b`),
+/// ignores a second move, then raises the frame, sets userPlaced and takes the slot, in that order.
 fn start_moving(model: &mut Model, h: FrameHandle) -> mlua::Result<()> {
     if !model.arena.frame(h).is_some_and(|f| f.movable) {
         return Err(not_flagged(model, h, "movable"));
     }
-    // `7767e8`'s `root+0xcfc != 0` guard. What the reference does past *not starting a second
-    // move* is not recorded; refusing silently is the reading that cannot invent behaviour.
+    // The `root+0xcfc != 0` guard (`0x7767e8`); what the reference does beyond not starting a
+    // second move is untraced.
     if model.moving.is_some() {
         return Ok(());
     }
-    // The drag-start raise — `0x7652b0` @`0x7652d7`, before it sets the userPlaced bit and records
-    // the drag slot, which is the order kept here. Grabbing a window brings it forward; the worker
-    // supplies the toplevel gate (a non-toplevel movable frame raises nothing).
+    // The drag-start raise (`0x7652d7`); the worker applies the toplevel gate.
     super::toplevel::raise(model, h);
     set_user_placed(model, h);
     model.moving = Some(FrameMove {
         frame: h,
         sample: model.cursor_pos,
-        // Lua `StartMoving` is mode 3: it survives the button and ends only at
-        // `StopMovingOrSizing`.
+        // Mode 3: only `StopMovingOrSizing` ends it.
         auto_stop: false,
     });
     Ok(())
 }
 
-/// Begin a **title-region** move — mode 2, the drag a mouse-down inside `frame:GetTitleRegion()`
-/// starts (`0x7662c0` → `0x765320(frame, mode=2, …)` → `0x7652b0`).
-///
-/// [`start_moving`]'s body **minus the movable gate**, and that omission is the settled part
-/// rather than a shortcut: the movable bit is `frame+0xb4 & 0x100`, tested by `StartMoving`
-/// (`0x77678b`, else `"Frame %s is not movable"`) and by the modifier-drag path — and **not read
-/// anywhere** on `0x7662c0`→`0x765320`→`0x7652b0`→`0x768430`. The no-gate reading is settled; the
-/// observable claim is INFERRED, because both FrameXML users happen to be `movable="true"`; a title
-/// region on a non-movable frame is the case that would tell them apart, and it drags here.
-///
-/// Returns whether a move actually started — `false` when one was already in flight, which is
-/// `0x7767e8`'s `root+0xcfc != 0` guard and the same refusal [`start_moving`] makes.
+/// Begin a title-region move, drag mode 2 (`0x7662c0` → `0x765320` → `0x7652b0`), with no movable
+/// check, since nothing on that path reads the bit. False when a move is already in flight.
 pub(crate) fn start_title_move(model: &mut Model, h: FrameHandle) -> bool {
     if model.moving.is_some() {
         return false;
@@ -487,9 +322,8 @@ pub(crate) fn start_title_move(model: &mut Model, h: FrameHandle) -> bool {
     true
 }
 
-/// Set the userPlaced bit the way the client's drag entry `0x7652b0` does, and dirty the layout
-/// cache **only on the transition** — a press inside a title region runs this on every click, and
-/// dirtying on each would put the saver's debounce back to work for a frame nothing moved.
+/// Set userPlaced as the drag entry `0x7652b0` does; the layout cache is dirtied only on the
+/// transition, since every title-region click runs this.
 fn set_user_placed(model: &mut Model, h: FrameHandle) {
     if let Some(f) = model.arena.frame_mut(h) {
         if !f.user_placed {
@@ -499,40 +333,16 @@ fn set_user_placed(model: &mut Model, h: FrameHandle) {
     }
 }
 
-/// A drag pump moved a frame; if that frame is **user-placed**, the layout cache owes the player's
-/// file a rewrite ([`crate::script::layout_cache`]).
-///
-/// The gate is the bit rather than "any drag" on purpose: `StartMoving`/`StartSizing` set the bit
-/// themselves, so the only frames this can miss are ones an addon moves with `SetPoint` — and those
-/// are the frames whose position the addon is saving itself, which is the reference's own division
-/// of labour (the engine's layout cache holds userPlaced frames; addons hold their own).
+/// A drag moved the frame: if it is user-placed, the layout cache owes its file a rewrite.
 fn mark_user_placed_change(model: &mut Model, h: FrameHandle) {
     if model.arena.frame(h).is_some_and(|f| f.user_placed) {
         model.user_placed_changed = true;
     }
 }
 
-/// Apply a frame's `SetMinResize`/`SetMaxResize` bounds to a proposed size, per axis.
-///
-/// The reference's predicate, transcribed (decision 1505 — decoded from `0x768710`'s **emitted**
-/// `jcc`, not from the FPU status mask, and deliberately not from the dead `0x768550` copy whose
-/// operand order differs):
-///
-/// ```text
-/// if (min != 0.0) and (v < min):  v = min
-/// if (max != 0.0) and (v > max):  v = max
-/// ```
-///
-/// Three things a plausible implementation gets wrong, all VERIFIED:
-///
-///  · **There is NO floor when no bound is set.** benilla had a hardcoded `1.0` here (inherited
-///    from the drag pump before the bounds existed) and the client has nothing of the kind — a
-///    drag can carry an unbounded frame to zero and through it into negative extents.
-///  · **Only an exactly-`0.0` bound is the sentinel**, so a *negative* bound clamps normally.
-///  · **min first, then max — so when `min > max`, MAX wins.** Nothing in the client warns,
-///    rejects or reconciles the pair.
-///
-/// The returned residual per axis is what the caller rebates out of the drag delta ([`advance_size`]).
+/// Apply the `SetMinResize`/`SetMaxResize` bounds to a proposed size per axis, as `0x768710`
+/// does: only an exact 0.0 is unbounded, min applies before max so max wins a crossed pair, and
+/// with no bound there is no floor, so a size can go negative.
 fn clamp_resize(model: &Model, h: FrameHandle, w: f32, hgt: f32) -> (f32, f32) {
     let (min, max) = model
         .arena
@@ -549,13 +359,7 @@ fn clamp_resize(model: &Model, h: FrameHandle, w: f32, hgt: f32) -> (f32, f32) {
     (axis(w, min.0, max.0), axis(hgt, min.1, max.1))
 }
 
-/// Pump an in-flight `StartSizing`: move the gripped edges to the cursor, leave the others.
-///
-/// The mirror of [`advance_move`] — same sample-and-recentre, same dead-frame bail, same
-/// local-unit scaling (offsets are pre-scale, so a cursor delta divides by the frame's own scale on
-/// the way in). Where a move translates every anchor, a resize moves the gripped edges only: the
-/// width/height change, and the anchor offsets follow only for the edges that actually moved, which
-/// is what keeps the OPPOSITE edge planted.
+/// Pump an in-flight `StartSizing`: the gripped edges follow the cursor, the opposite ones stay.
 pub(crate) fn advance_size(model: &mut Model, pos: (f32, f32)) {
     let Some(sz) = model.sizing else { return };
     if model.arena.frame(sz.frame).is_none() {
@@ -568,8 +372,6 @@ pub(crate) fn advance_size(model: &mut Model, pos: (f32, f32)) {
     }
     let inv = 1.0 / eff_scale(model, sz.frame);
     let (dx, dy) = (dx * inv, dy * inv);
-    // Width grows when the RIGHT grip goes right, or the LEFT grip goes left. Height likewise with
-    // y-up: the TOP grip going up grows it, the BOTTOM grip going down grows it.
     let dw = if sz.right {
         dx
     } else if sz.left {
@@ -591,23 +393,11 @@ pub(crate) fn advance_size(model: &mut Model, pos: (f32, f32)) {
     else {
         return;
     };
-    // The frame's own `SetMinResize`/`SetMaxResize` bounds — read before the mutable borrow, and
-    // the only path in the client that consults them at all (`clamp_resize`, reached only through
-    // `0x76a660`).
+    // The resize bounds are read only here, as only `0x76a660` reads them in the reference.
     let (new_w, new_h) = clamp_resize(model, sz.frame, w0 + dw, h0 + dh);
-    // **The rebate.** A saturated clamp is not a bare `max`/`min` in the reference: the residual
-    // it swallowed is subtracted back out of the drag delta before the delta reaches the anchors
-    // (`0x768770`/`0x7687a2` — `dx := dx ∓ residual·scale`). Without it the size pins at the bound
-    // while the anchor keeps sliding, so a window held past its minimum stops shrinking and starts
-    // *walking* across the screen. With it the moving edge lands exactly on the bound and stays.
-    //
-    // Both are already in LOCAL units here (`dx`/`dy` were divided by the effective scale above,
-    // and the anchor offsets they feed are pre-scale), so the rebate is a plain subtraction — the
-    // reference's `·layoutScale` is its own conversion back out of cursor units, not part of the
-    // rule. The sign follows the grip: a growing edge (`dw = +dx`) adds the residual, a shrinking
-    // one (`dw = -dx`) subtracts it, so the delta always agrees with the size the clamp allowed.
-    // An axis nobody gripped is left alone rather than rebated against a bound the frame was
-    // already outside of — that frame stays put until a drag touches its axis.
+    // The rebate (`0x768770`/`0x7687a2`): the residual a clamp swallowed comes back out of the
+    // drag delta, so the moving edge stops at the bound instead of the window walking. The delta
+    // is already in local units, and an ungripped axis is not rebated.
     let rebate = |d: f32, want: f32, got: f32, grew: bool, gripped: bool| {
         if !gripped {
             return d;
@@ -627,15 +417,9 @@ pub(crate) fn advance_size(model: &mut Model, pos: (f32, f32)) {
     input.width = new_w;
     input.height = new_h;
     let mut moved = input.width.to_bits() != w0.to_bits() || input.height.to_bits() != h0.to_bits();
-    // The planted edge: a frame anchored by its LEFT that is gripped on the LEFT has to move too,
-    // or the resize would push the right edge instead. Only the gripped axis shifts.
-    //
-    // **Which edges travel is OURS, and the bytes do not settle it** — stated rather than
-    // quietly aligned. The reference collapses the frame to a single planted TOPLEFT anchor at
-    // `StartSizing` (`0x768430`), so *its* travelling edges are necessarily LEFT and TOP; we keep
-    // the authored anchor set intact and shift every anchor's offsets, which is a different model
-    // with a different answer. The rebate above is the part the bytes do settle, and it applies
-    // either way.
+    // A LEFT or BOTTOM grip also shifts the anchors on its axis, so a frame anchored by that side
+    // keeps its opposite edge. The reference instead re-anchors the frame to one TOPLEFT point at
+    // `StartSizing` (`0x768430`).
     if !input.anchors.is_empty() && (sz.left || sz.bottom) {
         for a in &mut input.anchors {
             if sz.left {
@@ -647,31 +431,19 @@ pub(crate) fn advance_size(model: &mut Model, pos: (f32, f32)) {
         }
         moved |= (sz.left && dx != 0.0) || (sz.bottom && dy != 0.0);
     }
-    // The zero-delta return above is on the RAW cursor delta, which is not the same question: a
-    // single-axis grip dragged purely across its axis gives `dw == dh == 0`, and so does a grip
-    // held against a bound. Both used to bump the epoch and then hash all ~10k anchored regions to
-    // conclude nothing had moved — the castbar's bug class in miniature, for every frame of such a
-    // drag (decision 1385).
+    // A nonzero cursor delta can still move nothing (a grip dragged across its axis, or held at a
+    // bound), so the layout is touched only on a real change.
     if moved {
-        // Offsets only — a resize grip never repoints an anchor, so the frame names itself and the
-        // cached graph survives the drag (decision 1388). A drag is per-frame by nature: this is
-        // the difference between a smooth window resize and one that re-derives 13,656 nodes on
-        // every mouse-move.
+        // No anchor is retargeted, so only this node is touched.
         model.touch_layout_frame(sz.frame);
         mark_user_placed_change(model, sz.frame);
     }
     model.sizing = Some(FrameSizing { sample: pos, ..sz });
 }
 
-/// Pump an in-flight move to the cursor at `pos` — the engine half of `0x7655b0`, run from
-/// [`crate::script::UiScript::mouse_move`] beside [`crate::script::cursor::maybe_start_drag`] and,
-/// like it, BEFORE the hover-boundary early return (a frame dragged around underneath the cursor
-/// crosses no boundary at all, so a move parked behind that return would only advance when the
-/// cursor happened to leave the frame).
-///
-/// Applies `(pos − sample)` scaled into the frame's anchor offsets and re-centers the sample; a
-/// zero delta does nothing at all, and a frame that died mid-move ends the move rather than
-/// writing to a dead handle.
+/// Pump an in-flight move to the cursor at `pos` (`0x7655b0`). Called from
+/// [`crate::script::UiScript::mouse_move`] before its hover-boundary early return, since a frame
+/// dragged under the cursor crosses no boundary.
 pub(crate) fn advance_move(model: &mut Model, pos: (f32, f32)) {
     let Some(mv) = model.moving else { return };
     if model.arena.frame(mv.frame).is_none() {
@@ -682,23 +454,17 @@ pub(crate) fn advance_move(model: &mut Model, pos: (f32, f32)) {
     if dx == 0.0 && dy == 0.0 {
         return;
     }
-    // Offsets are LOCAL units — the resolver multiplies them by the frame's own layoutScale
-    // (`anchor_resolve_x`), so the cursor's screen delta divides by it on the way in, exactly the
-    // `dx/scale` of `0x768710`'s case 4.
+    // Anchor offsets are in the frame's own units, so the screen delta divides by its scale, as
+    // `0x768710`'s case 4 does.
     let inv = 1.0 / eff_scale(model, mv.frame);
     let (dx, dy) = (dx * inv, dy * inv);
     if let Some(input) = model.layout_inputs.get_mut(&mv.frame) {
-        // Translating the whole set, not slot 0 — see the module doc. An anchorless frame is not
-        // resolvable and so is not on screen to drag; it simply does not move.
         if !input.anchors.is_empty() {
             for a in &mut input.anchors {
                 a.x_off += dx;
                 a.y_off += dy;
             }
-            // The one mutation path every layout setter shares — the tier-1 epoch, never the
-            // solver's arrays (see [`super::layout_methods`]'s mutate-only-on-change law; a zero
-            // delta returned above, so this write always moved something). Translating every
-            // anchor moves no TARGET, so the frame names itself (decision 1388).
+            // No target moves, so only this node is touched; a zero delta already returned above.
             model.touch_layout_frame(mv.frame);
             mark_user_placed_change(model, mv.frame);
         }
diff --git a/crates/benilla-ui/src/script/object/toplevel.rs b/crates/benilla-ui/src/script/object/toplevel.rs
index 5c606dbe..7d58fe3a 100644
--- a/crates/benilla-ui/src/script/object/toplevel.rs
+++ b/crates/benilla-ui/src/script/object/toplevel.rs
@@ -1,102 +1,18 @@
-//! Frame method-table cluster: the `toplevel` flag and the **raise law** — `SetToplevel`/
-//! `IsToplevel`, `Raise`/`Lower`, and the engine-side worker every raise trigger runs. Split out of
-//! [`super`] beside [`super::movable`], whose flag word this shares.
+//! Frame methods: the `toplevel` flag, `Raise` and `Lower`, and the raise every trigger runs.
 //!
-//! This is "bring the window I just opened to the front". 82 corpus addons declare `toplevel=` in
-//! XML and eleven call `SetToplevel` from Lua; our own shipped windows declare it on thirteen
-//! frames. Until this module it was parsed and thrown away with a warn-once, so a benilla dialog
-//! opened behind another one stayed behind it.
+//! The flag is bit `0x1` of `[frame+0xb4]`, set by `0x76a3c0` from XML (`0x7698ec`) or
+//! `SetToplevel` (`0x775440`), and setting it raises nothing. `CSimpleTop::Raise` (`0x7650f0`):
 //!
-//! ## The law
+//! 1. Walks up `+0x9c` to the nearest toplevel self-or-ancestor; with none it does nothing.
+//! 2. With `force`, resolves the frame's layout and tests whether it is overlapped: a visible frame
+//!    of its stratum at its level or above, neither itself nor a descendant, meets its rect.
+//! 3. Only then compacts the stratum's levels, hidden frames included (`0x764eb0`), and sets its
+//!    level to the top plus one, moving same-stratum children by the same delta (`0x76a4f0`).
 //!
-//! The flag is **`[frame+0xb4]` bit `0x1`**, written by the same pure bit-setter `0x76a3c0` as
-//! `movable` (`0x100`) and `resizable` (`0x200`): `if (v) flags |= mask; else flags &= ~mask;`, no
-//! calls, no list touch. XML `toplevel` lands there at `0x7698ec`; Lua `SetToplevel 0x775440` at
-//! `0x7754d4`. **Setting the flag raises nothing** — it only marks the frame.
-//!
-//! The raise itself is `CSimpleTop::Raise(frame, force) 0x7650f0`, reached from
-//! `CSimpleFrame::Raise 0x76a5b0` = `this->root->Raise(this, force = 1)`:
-//!
-//! 1. **Resolve to the nearest TOPLEVEL self-or-ancestor** up `+0x9c` (`0x7650fb..0x765135`).
-//!    No toplevel in the chain ⇒ **total no-op**. So the gate lives in the worker, not the callers:
-//!    every trigger may hand it an arbitrary frame, and the frame that visibly moves may be an
-//!    *ancestor* of the one that was clicked or shown.
-//! 2. **`force != 0` ⇒ recompute the OVERLAPPED bit** (`0x76513e..0x765290`): resolve the frame's
-//!    pending layout, then scan its stratum bucket from **its own level upward** for a frame that is
-//!    not itself, is not one of its descendants (`0x767010`), and whose screen rect
-//!    intersects non-emptily. The answer is stored as `+0xb4` bit `0x10`.
-//! 3. **The raise, gated on that bit** (`0x7651ac..0x7651e7`): level compaction (`0x764eb0`)
-//!    squeezes the free levels out of the stratum — over **every live frame of it, hidden
-//!    included** — then `set_frame_level(bucket->count, propagate = 1)`.
-//!
-//! Three consequences the tests pin: a raise is **`level := top occupied level + 1`**, not a list
-//! reshuffle; it is **occlusion-gated** — `Raise()` on a frame that overlaps nothing changes nothing
-//! at all; and it **never changes the stratum** (`0x7650f0` never writes `+0xc0`), so a LOW frame can
-//! never be lifted over a MEDIUM one by any number of raises. `propagate = 1` shifts same-strata
-//! children by the **same delta** (`0x76a4f0` @`0x76a58a`–`0x76a595`), so the raised subtree keeps
-//! its internal order; cross-strata children are untouched.
-//!
-//! ## How that maps onto benilla's order model, clause by clause
-//!
-//! Our draw order is a derived total order over the arena ([`crate::order`]), not a materialized
-//! array of per-stratum buckets of intrusive level lists. Every clause above still lands, but two
-//! of them land as *derivations* and one is deliberately not stored:
-//!
-//! - **"the stratum bucket"** = the effective-visible frames whose `strata` matches. Bucket
-//!   membership is exactly the client's link-gate: a frame is in a level list only while
-//!   effectively visible, which is the same condition [`crate::widget::WidgetArena::resequence_to_tail`]
-//!   already mirrors for the link stamp.
-//! - **"raise within the strata"** = a **frame-level bump**, and it is the honest mapping rather
-//!   than a re-stamp: the binary writes `+0xc4` through `set_frame_level 0x76a4f0`, and level is the
-//!   term *above* the link stamp in our key, so a bump lifts the frame over every same-strata frame
-//!   regardless of when each was last shown. The arithmetic is pinned in
-//!   `tests/toplevel.rs::a_raise_is_top_occupied_level_plus_one_after_compaction`.
-//! - **Level compaction** is [`crate::widget::WidgetArena::compact_levels`] — an order-preserving
-//!   renumber of **every frame** in one stratum, hidden ones included: `0x764eb0` walks the client's
-//!   master frame list filtering on strata and level alone, and never reads `+0xd4`
-//!   (decision 2104). It changes no draw order by itself; it is
-//!   what keeps `level := max + 1` from ratcheting upward for the length of a session. Renumbering
-//!   only the *bucket* (the visible half) is the one shape it may not have: the raise's `propagate`
-//!   delta is computed in the new numbering and applied to levels that are still in the old one, so
-//!   a squeeze taken out of a visible child and not out of its hidden sibling inverts a pair that
-//!   `parent.level + 1` made equal — see that method's own doc for the window it broke, and for the
-//!   two places ours is deliberately simpler than the bytes.
-//! - **The OVERLAPPED bit is computed, never stored** — and that is *exact*, not a shortcut. The bit
-//!   is written only by `0x7650f0` and the per-tick pass `0x7657d0`, and read only by `0x7650f0`,
-//!   which with `force = 1` recomputes it immediately before reading it. The stored value is
-//!   therefore observable **only** through the one `force = 0` call site, `0x764a20`
-//!   (bucket-invalidate), which rides an already-computed bit. benilla has no bucket-invalidate
-//!   call — every trigger we have is a `force = 1` one — so the per-tick maintenance `0x7657d0`
-//!   would be state nothing could read. A local `bool` per raise is bit-for-bit what `force = 1`
-//!   does. **If a `force = 0` trigger is ever built, the bit has to become a field and `0x7657d0` a
-//!   per-tick pass; there is no other clause of this law that is unmodelled.**
-//!
-//! ## The screen rects the gate reads
-//!
-//! Step 2 needs rects, which live on [`Model::resolved`], not on the arena. `0x7650f0` starts by
-//! resolving the frame's *own* pending layout (`0x76513e`: `if (T->+0x60 & 1) …0x7680e0`) and then
-//! reads every other frame's cached rect as-is; [`raise`] does the same thing with the one resolve
-//! we have — [`crate::script::UiScript::resolve_layout`], whose epoch gate makes it a `u64` compare
-//! on the overwhelmingly common quiet call (showing a frame writes no layout input, so a Show-driven
-//! raise never pays a solve unless the caller moved something in the same tick). Our solve covers
-//! hidden frames too, so a frame being shown for the first time already has a rect to test. A frame
-//! with **no** resolved rect (anchorless, so not on screen) overlaps nothing and raises nothing.
-//!
-//! ## Triggers — the census, and which ones benilla wires
-//!
-//! A complete rel32 + absolute-dword census finds six call sites. Ours:
-//!
-//! | site | what it is | benilla |
-//! |---|---|---|
-//! | `0x775b0a` (Lua `Frame:Raise()`) | the explicit script call | [`install`] |
-//! | `0x76aeec` in `0x76ae10` | **the Show trigger** | [`raise_on_show`], run from [`crate::script::event::fire_visibility_changes`] |
-//! | `0x7652d7` in begin-move `0x7652b0` | drag start | [`super::movable`]'s `start_moving` |
-//! | `0x766392` in the mouse-down handler `0x7662c0` | **the click trigger** | [`crate::script::UiScript::mouse_button`]'s down arm, first thing — capture-else-hover, unguarded, ahead of the title-region swallow |
-//! | `0x764a4c` (`force = 0`) | re-applies an already-computed bit `0x10` | no counterpart (see the OVERLAPPED note above) |
-//! | `0x7650d6` | dead — zero references binary-wide | — |
-//!
-//! **`Frame:Lower()` is inert in build 5875** and inert here: `0x775b20` → `0x76a5c0` → `0x7652a0`,
-//! which is `xor eax,eax; ret 4` — a verified no-op stub whose frame argument is never read.
+//! The stratum never changes. The overlapped bit is recomputed per raise, never stored: only the
+//! `force = 0` trigger (`0x764a4c`) reads a stored bit, and it is not wired, so neither is the
+//! per-tick pass that keeps it (`0x7657d0`). The wired triggers are `Raise` (`0x775b0a`), Show
+//! (`0x76aeec`), drag start (`0x7652d7`) and mouse-down (`0x766392`).
 
 use mlua::{Lua, Table, Value};
 
@@ -106,12 +22,9 @@ use crate::widget::FrameHandle;
 
 use super::frame_handle_of;
 
-/// Populate `m`'s toplevel/raise methods (see the module doc).
+/// Populate `m`'s toplevel and raise methods.
 pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
-    // SetToplevel(flag) / IsToplevel() — flag word bit 0x1 (`0x775440`/`0x76a3c0`). A pure flag
-    // write; the raise is entirely separate. The argument is an **optional** boolean defaulting to
-    // TRUE (`0x775440` marshals it that way) — unlike `SetMovable`'s, so this takes a `Value` and
-    // reads absence as true rather than leaning on mlua's nil-is-false bool conversion.
+    // SetToplevel's argument is optional and defaults to true (`0x775440`), unlike `SetMovable`'s.
     m.set(
         "SetToplevel",
         lua.create_function(|lua, (this, flag): (Table, Option<Value>)| {
@@ -135,10 +48,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             Ok(crate::script::binding_abi::flag(model.arena.is_toplevel(h)))
         })?,
     )?;
-    // Raise() — `0x775a50` → `0x76a5b0` → `0x7650f0(this, force = 1)`. Note it is legal on any
-    // frame: the worker substitutes the nearest toplevel self-or-ancestor and does nothing at all
-    // when there is none, so an addon calling it on a plain frame gets the reference's silence, not
-    // an error.
+    // Raise() (`0x775a50` → `0x76a5b0` → `0x7650f0`, `force = 1`): legal on any frame, and silent
+    // when no toplevel self-or-ancestor exists.
     m.set(
         "Raise",
         lua.create_function(|lua, this: Table| {
@@ -148,30 +59,22 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // Lower() — `0x775b20` → `0x76a5c0` → `0x7652a0` = `xor eax,eax; ret 4`. A VERIFIED no-op stub
-    // in build 5875 (the frame argument is never read, and the call is direct, so this is
-    // unconditionally what runs). Present because absence is a different behaviour — a nil-call
-    // error where the reference silently does nothing.
+    // Lower() does nothing in the reference: `0x775b20` → `0x76a5c0` → `0x7652a0`, which is
+    // `xor eax,eax; ret 4`.
     m.set("Lower", lua.create_function(|_, _this: Table| Ok(()))?)?;
     Ok(())
 }
 
-/// `CSimpleTop::Raise(frame, force = 1)` — `0x7650f0`, the worker every trigger runs. Returns
-/// whether a toplevel self-or-ancestor was found at all (the binary's `bool` return); a `true` with
-/// nothing moved is the occlusion gate declining, which is the common and correct case.
-///
-/// The three numbered steps of the module doc, in order.
+/// `CSimpleTop::Raise(frame, force = 1)` (`0x7650f0`), the module doc's three steps; true, as in
+/// the reference, when a toplevel self-or-ancestor was found, whether or not it moved.
 pub(in crate::script) fn raise(model: &mut Model, frame: FrameHandle) -> bool {
-    // 1. The nearest TOPLEVEL self-or-ancestor. None ⇒ total no-op.
+    // 1. The nearest toplevel self-or-ancestor, else nothing.
     let Some(t) = nearest_toplevel(model, frame) else {
         return false;
     };
-    // 2. force = 1: resolve the pending layout, then recompute OVERLAPPED (a local — see the
-    //    module doc's note on why storing the bit would be unobservable state).
-    //    Any `OnSizeChanged` that resolve produces is QUEUED, not fired: this path holds a bare
-    //    `&mut Model` (no Lua reachable from a raise), so the host's next `UiScript::resolve` —
-    //    which runs every frame — drains it one tick later. The alternative, threading a `&Lua`
-    //    through the raise, would put a Lua handler in the middle of a strata compaction.
+    // 2. Resolve the pending layout (`0x76513e`), then test for overlap. Deviation: an
+    //    `OnSizeChanged` that resolve produces fires at the next `UiScript::resolve`, because a
+    //    Lua handler must not run in the middle of a level compaction.
     UiScript::resolve_layout(model);
     if !overlapped(model, t) {
         return true;
@@ -185,25 +88,17 @@ pub(in crate::script) fn raise(model: &mut Model, frame: FrameHandle) -> bool {
     true
 }
 
-/// The Show trigger — `0x76ae10` @`0x76aee0`: on a genuine `+0xd4`
-/// false→true transition, **test the frame's own toplevel bit** and raise if it is set.
-///
-/// The own-bit test is load-bearing and is why this is not just [`raise`]: the worker would walk up
-/// to a toplevel *ancestor*, so calling it unconditionally would lift a whole window every time any
-/// non-toplevel child of it became visible. The binary tests `[esi+0xb4], 0x1` first, and only then
-/// calls `0x76a5b0`.
+/// The Show trigger (`0x76ae10` at `0x76aee0`): on becoming visible, raise only if the frame's own
+/// toplevel bit is set, so showing a child never lifts its window.
 pub(in crate::script) fn raise_on_show(model: &mut Model, h: FrameHandle) {
     if model.arena.is_toplevel(h) {
         raise(model, h);
     }
 }
 
-/// Step 1 — walk `+0x9c` from the frame up, returning the first node with the toplevel bit
-/// (`0x7650fb..0x765135`). Loop-guarded like the arena's own ancestry walk; a well-formed tree
-/// never loops.
+/// Step 1: the first frame up `+0x9c` with the toplevel bit (`0x7650fb..0x765135`).
 fn nearest_toplevel(model: &Model, frame: FrameHandle) -> Option<FrameHandle> {
-    // The bound is read once, not per hop: a chain longer than the frame count is a cycle, which
-    // `set_parent`'s own guard already makes unreachable — this is defence, not a hot path.
+    // A chain longer than the frame count is a cycle, which `SetParent` already refuses.
     let bound = model.arena.iter_frames().count();
     let mut cur = Some(frame);
     let mut guard = 0usize;
@@ -221,24 +116,15 @@ fn nearest_toplevel(model: &Model, frame: FrameHandle) -> Option<FrameHandle> {
     None
 }
 
-/// Step 2's predicate — the scan `0x7650f0` runs inline and `0x765a90` runs standalone: within `t`'s
-/// own stratum bucket, from **`t`'s own level upward**, is there a frame that is not `t`, is not one
-/// of `t`'s descendants, and whose screen rect meets `t`'s?
-///
-/// Every clause matters, and each is a separate test:
-/// - **`level >= t.level` only.** A toplevel frame that overlaps solely something *below* it is
-///   already on top of it, so there is nothing to raise over.
-/// - **Excludes descendants (`0x767010`).** A window overlaps its own children by construction;
-///   without this every toplevel frame with content would raise on every trigger.
-/// - **non-empty intersection.** Frames that merely share an edge do not overlap — the intersection
-///   has to have positive width *and* height, so a zero-area touch is not an occlusion.
+/// Step 2 (`0x7650f0` inline, `0x765a90` standalone): a visible frame of `t`'s stratum at `t`'s
+/// level or above, neither `t` nor its descendant (`0x767010`), whose rect meets `t`'s with area.
 fn overlapped(model: &Model, t: FrameHandle) -> bool {
     let Some(tf) = model.arena.frame(t) else {
         return false;
     };
     let (strata, level) = (tf.strata, tf.level);
     let Some(t_rect) = model.resolved.get(&t).copied() else {
-        // No resolved rect ⇒ the frame is not on screen ⇒ it occludes nothing.
+        // No resolved rect: not on screen, so nothing overlaps it.
         return false;
     };
     model.arena.iter_frames().any(|(h, f)| {
@@ -254,8 +140,8 @@ fn overlapped(model: &Model, t: FrameHandle) -> bool {
     })
 }
 
-/// `rect_intersect_nonempty` (`0x768320` / `0x766c70` / `0x766bc0`) — reusing the one axis-aligned
-/// intersection this crate already has and asking whether what comes out has area.
+/// Whether two rects intersect with area: the reference reads both (`0x768320`), intersects them
+/// (`0x766c70`) and tests the result (`0x766bc0`).
 fn rects_overlap(a: Rect, b: Rect) -> bool {
     let i = crate::script::clip::intersect_rect(a, b);
     i.width() > 0.0 && i.height() > 0.0
diff --git a/crates/benilla-ui/src/script/party.rs b/crates/benilla-ui/src/script/party.rs
index fdd49822..3c3200de 100644
--- a/crates/benilla-ui/src/script/party.rs
+++ b/crates/benilla-ui/src/script/party.rs
@@ -1,257 +1,167 @@
-//! The party/raid **Era API surface** (decision 0434 §2, phase 2) — the engine-free seam mirroring
-//! [`super::unit`]: the app pushes a roster **snapshot** ([`UiScript::set_party`]) built from its own
-//! `GroupState` wire mirror, and the `GetNumPartyMembers`/`GetPartyLeaderIndex`/`GetLootMethod`/…
-//! globals here read that plain data. The invite/uninvite/promote/loot-config calls are the outbound
-//! half: they queue a [`PartyRequest`] the app drains ([`UiScript::take_party_requests`]) and turns
-//! into the matching `CMSG_GROUP_*`/`CMSG_LOOT_METHOD` send — no ECS/net reach from the engine
-//! (decision 0068 §3), exactly [`super::unit`]'s split.
+//! The party and raid bindings. The app pushes a roster snapshot ([`UiScript::set_party`]) that
+//! the getters read; the verbs queue a [`PartyRequest`] the app drains
+//! ([`UiScript::take_party_requests`]) into the send. Per-member game state is the unit snapshot
+//! under `party1`..`party4` ([`super::unit::UnitState`]).
 //!
-//! Per-member game state (health/mana/level/reaction/…) does **not** live here — it rides the
-//! existing per-unit snapshots under the `"party1"`..`"party4"` tokens (decision 0434 §3), the same
-//! feed `"player"`/`"target"` use ([`super::unit::UnitState`]). This module owns only the
-//! roster-level facts a unit snapshot can't carry: how many members, who leads, the loot
-//! configuration. `PartyState::default()` is "not in a group" — every getter then answers the
-//! solo-player shape a fresh client reports (`GetNumPartyMembers()` `0`, `GetLootMethod()`
-//! `("group", nil)`, …).
-//!
-//! The **raid roster** ([`PartyState::raid`]) is the same shape one level out: the app pushes the
-//! whole array — the player included, which is why `UnitInRaid("player")` needs no token special
-//! case the way `UnitInParty` does — and `GetNumRaidMembers`/`GetRaidRosterInfo`/`UnitInRaid` read
-//! it. It is deliberately ONE list rather than a count beside a list: the reference indexes the
-//! array `0xb712a8` bounded by the count `0xb713e0`, and two of the three bindings walk exactly
-//! that pair, so a client whose count and array can disagree hands an addon looping
-//! `for i = 1, GetNumRaidMembers()` a miss tuple it will then index. The per-member grid/UI is
-//! the RaidFrame (decision 1549), which reads exactly this array.
-//!
-//! The **raid management verbs** (decision 1549) are the outbound half again, and they address
-//! members three different ways because the reference's own bindings do: by **raid index**
-//! (`SetRaidSubgroup`, `SwapRaidSubgroup`, `UninviteFromRaid` — the RaidFrame has the index in
-//! hand), by **name** (`PromoteByName`, `PromoteToAssistant`, `DemoteAssistant` — UnitPopup
-//! carries a name, never an index), and by **nothing at all** (`ConvertToRaid`, `DoReadyCheck`,
-//! `RequestRaidInfo`). Resolving index/name to whatever the wire wants is the app's job at the
-//! drain, exactly as `InviteToParty`'s token resolution already is: this side stays plain data.
-//!
-//! The **saved-instance list** ([`SavedInstanceInfo`]) is a second app-pushed snapshot, separate
-//! from [`PartyState`] because it arrives on its own packet (`SMSG_RAID_INSTANCE_INFO`) and
-//! outlives every roster change — folding it into the roster push would clear it every time the
-//! group moved.
+//! The raid roster ([`PartyState::raid`]) is one list, the player included, because the
+//! reference's count (`0xb713e0`) bounds the very array `GetRaidRosterInfo` indexes (`0xb712a8`).
+//! The saved-instance list ([`SavedInstanceInfo`]) is a separate push, as a roster push replaces
+//! [`PartyState`] whole.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::binding_abi::number_arg;
 use super::Model;
 
-/// One roster member's engine-owned facts (decision 0434 §2/§3) — deliberately thin: everything else
-/// (health, class, reaction, …) is the unit snapshot under its `"partyN"` token.
+/// One party member; everything else about them is the unit snapshot under their `partyN` token.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct PartyMemberInfo {
     pub name: String,
-    /// The member's GUID — the identity `UnitInParty` matches arbitrary tokens (the target)
-    /// against (decision 0434 §5's popup menu pick). `0` = unknown, never matches.
+    /// The identity `UnitInParty` matches any token against; `0` never matches.
     pub guid: u64,
 }
 
-/// One saved raid lockout — `GetSavedInstanceInfo`'s three returns (decision 1549). Pushed whole
-/// by the app ([`UiScript::set_saved_instances`]) from `SMSG_RAID_INSTANCE_INFO`, with the map
-/// **name** already resolved: the wire carries a `Map.dbc` id and the DBC is the app's to read.
+/// One saved raid lockout, `GetSavedInstanceInfo`'s three returns, from `SMSG_RAID_INSTANCE_INFO`
+/// with the `Map.dbc` name resolved by the app ([`UiScript::set_saved_instances`]).
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct SavedInstanceInfo {
-    /// The instance's display name (`Map.dbc`'s own), e.g. `"Molten Core"`.
+    /// The `Map.dbc` name, e.g. `"Molten Core"`.
     pub name: String,
-    /// The instance id — what the panel prints in its ID column.
     pub instance: u32,
-    /// Seconds remaining until the lockout resets; the panel runs it through `SecondsToTime`.
+    /// Seconds until the lockout resets.
     pub reset: u32,
 }
 
-/// One **raid roster** row — `GetRaidRosterInfo`'s nine returns, as the app resolved them
-/// (`0x4bb560`). Field order is the push order of the reference's success tuple.
-///
-/// The row is the *record*, not the answer: two of the nine are computed at the binding
-/// ([`Self::subgroup`]'s 1-based exposure, [`Self::zone`]'s offline substitution), because both
-/// adjustments live in the binding's own bytes and doing them at the feed would put a Lua-facing
-/// convention in the app.
+/// One raid roster row, `GetRaidRosterInfo`'s nine returns in push order (`0x4bb560`). The
+/// binding, not the row, applies the subgroup's +1 and the offline zone.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct RaidMemberInfo {
-    /// Return 1 — the member's name, from the guid-keyed name cache (`0x4bb5ee`).
-    ///
-    /// **Empty means "not cached yet", and that is not a cosmetic difference**: the reference
-    /// sends a cache miss to the *same* arm an out-of-range index takes (`0x4bb5f8 je 0x4bb7b9`),
-    /// so an occupied slot whose name has not arrived is indistinguishable from no slot at all.
-    /// Reproduced — [`raid_roster_info`] answers the miss tuple for an empty name.
+    /// Return 1, from the name cache (`0x4bb5ee`). Empty means not cached, which the reference
+    /// answers with the miss tuple, as for an empty slot (`0x4bb5f8 je 0x4bb7b9`).
     pub name: String,
-    /// The member's GUID — what `UnitInRaid` matches an arbitrary token against. `0` = unknown,
-    /// never matches (the reference's membership helper `0x4baee0` short-circuits GUID `0:0` to
-    /// false at its entry).
+    /// The identity `UnitInRaid` matches a token against; `0` never matches, as the reference's
+    /// membership test rejects a zero guid (`0x4baee0`).
     pub guid: u64,
-    /// Return 2 — the rank, **exposed exactly as stored** (`0x4bb607 fild [edi+0xc]`, no
-    /// adjustment). The numeric convention is not derivable from the binding alone; the corpus
-    /// does, consistently: `ChatLog.lua:351-353` prints `@` for `2` and `*`
-    /// for `1`, i.e. **0 member · 1 assistant · 2 leader**, which is what the app fills.
+    /// Return 2, exposed as stored (`0x4bb607 fild [edi+0xc]`): 0 member, 1 assistant, 2 leader,
+    /// the convention addons read (`ChatLog.lua:351-353`).
     pub rank: u32,
-    /// Return 3 — the subgroup **as stored, 0-based**. The binding exposes `subgroup + 1`
-    /// (`0x4bb61a inc eax`, a VERIFIED adjustment); keeping the record 0-based means the wire's
-    /// own value (`GroupMemberEntry::flags` bits 0-2) lands here unconverted and the +1 has one
-    /// home.
+    /// Return 3, stored 0-based as the wire's `GroupMemberEntry::flags` bits 0-2 carry it; the
+    /// binding exposes it 1-based (`0x4bb61a inc eax`).
     pub subgroup: u32,
-    /// Return 4 — the member's level. `0` when neither a streamed object nor a stats packet has
-    /// carried one (the reference's own third arm pushes `0` there too).
+    /// Return 4, `0` until an object or a stats packet carries it, as in the reference's third arm.
     pub level: u32,
-    /// Return 5 — the **localized** class name ("Warrior"), `None` → `nil`.
+    /// Return 5, the localized class name.
     pub class: Option<String>,
-    /// Return 6 — the class file/token ("WARRIOR"), the one non-localized string in the tuple.
+    /// Return 6, the class token (`"WARRIOR"`), the one unlocalized string.
     pub class_file: Option<String>,
-    /// Return 7 — the member's zone name while [`Self::online`]; `None` → `nil`. **When offline
-    /// this field is not read at all**: the reference's third arm pushes the localized global
-    /// `PLAYER_OFFLINE` in the zone slot rather than `nil`, and the binding does that itself.
+    /// Return 7 while [`Self::online`]; offline, the binding pushes the `PLAYER_OFFLINE` global
+    /// instead and never reads this.
     pub zone: Option<String>,
-    /// Return 8 — connected. Also the switch for return 7's two arms, because it is in the
-    /// reference: return 8 is `1` on exactly the two arms that produced a real zone and `nil` on
-    /// the `PLAYER_OFFLINE` one.
+    /// Return 8, which also picks return 7's offline arm.
     pub online: bool,
-    /// Return 9 — **deliberately unlabelled.** The mechanism is confirmed: a streamed member
-    /// answers `1` iff `[obj+0x110 +0x40] <= 0` (UNIT_FIELD_HEALTH by the descriptor line this
-    /// repo already anchors), and an unstreamed one iff the roster record's `[+0x18]` carries
-    /// **both** bits `0x4` and `0x1`. The name itself is a guess, not settled: two independent
-    /// reads proposed "isDead" positionally, but it is not adopted here.
-    ///
-    /// Three things corroborate that guess without settling it, recorded here so whoever settles
-    /// it starts ahead: the whole corpus destructures position 9 as `isDead`
-    /// (`ChatLog.lua:347`, `CT_RaidAssist/CT_RAOptions.lua:89`, `oRA2/Leader/Ready.lua:241`);
-    /// health ≤ 0 is this client's own dead test; and our wire's status byte —
-    /// `benilla_protocol::messages::member_status`, from vmangos `Group.cpp:45-63` — spells
-    /// `ONLINE = 0x01` and `DEAD = 0x04`, which is *exactly* the bit pair the second arm tests.
-    /// The app fills this from that pair, so we reproduce the mechanism whatever it turns out to
-    /// be called.
+    /// Return 9, unnamed: `1` for a streamed member whose health (`[obj+0x110 +0x40]`) is 0 or
+    /// below, or an unstreamed one whose roster status (`[+0x18]`) has both `0x1` and `0x4`,
+    /// vmangos's `ONLINE` and `DEAD`, from which the app fills it. Addons read it as `isDead`.
     pub ninth: bool,
 }
 
-/// The party/raid roster snapshot, pushed whole by the app each frame it changes
-/// ([`UiScript::set_party`]) — the `GroupState` merged view's roster-level facts (decision 0434 §2).
-/// `PartyState::default()` = not in a group.
+/// The party and raid roster snapshot the app pushes whole when it changes
+/// ([`UiScript::set_party`]); the default is ungrouped.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct PartyState {
-    /// The other party members, `"party1"`..`"party4"` order (the recipient never appears in its own
-    /// list, matching `SMSG_GROUP_LIST`); empty = not in a group. Never more than 4 — in a raid
-    /// this is our own subgroup's slice and the whole roster is [`Self::raid`].
+    /// The other party members in `party1`..`party4` order, empty when ungrouped. The player is
+    /// never in it, as in `SMSG_GROUP_LIST`; in a raid it is our own subgroup's slice.
     pub members: Vec<PartyMemberInfo>,
-    /// The party leader, on the Lua `GetPartyLeaderIndex` scale: `0` the player leads, `1..=4` that
-    /// `members` slot (1-based) leads.
+    /// `GetPartyLeaderIndex`: `0` the player, `1..=4` that `members` slot.
     pub leader_index: u32,
-    /// **The cached group-leader GUID** — the reference's `[0xbc75f8]:[0xbc75fc]` pair, `0` when
-    /// ungrouped. Fed straight from the wire's leader GUID, not derived from
-    /// [`Self::leader_index`].
-    ///
-    /// It exists because `UnitIsPartyLeader`'s second leg is a GUID compare and an index cannot
-    /// stand in for it: the leg has to answer for a member whose object the client does **not**
-    /// hold — an out-of-range `party3`, any `raidN` — where there is no descriptor to read the
-    /// flag from, and it has to answer for the *resolved token's* GUID rather than for a slot.
-    ///
-    /// **Compared WITHOUT a zero guard**, which is the load-bearing part and reads like a bug:
-    /// `IsPartyLeader 0x4e9130` short-circuits on a `0:0` cached leader, and
-    /// `UnitIsPartyLeader 0x516210` does not. So an unresolvable-but-non-raising argument (none,
-    /// `nil`, `""`, `"target"` with no target) resolves to `0:0`, matches the zeroed leader, and
-    /// the reference answers **`1` while solo**. A client that answers `nil` there is not
-    /// reproducing 1.12.
+    /// The cached group-leader guid (the reference's `[0xbc75f8]:[0xbc75fc]`), `0` when
+    /// ungrouped, fed from the wire rather than derived from [`Self::leader_index`].
+    /// `UnitIsPartyLeader` (`0x516210`) compares a resolved token's guid with it and, unlike
+    /// `IsPartyLeader` (`0x4e9130`), has no zero guard, so an unresolvable token answers `1` while
+    /// solo.
     pub leader_guid: u64,
-    /// **The active player's own GUID** — the reference's `0x468550` read (`[0xb41414]+0xc0`),
-    /// `0` out of world. Fed by the app beside the leader; the pair is the leader gate the
-    /// ready-check timeout runs on (`CheckReadyCheckTime`, decision 1989): the reference compares
-    /// the two guids and nothing else, so a solo player (leader `0`, own non-zero) never matches.
+    /// The player's own guid (`0x468550`, `[0xb41414]+0xc0`), `0` out of world. With
+    /// [`Self::leader_guid`] it is the ready-check timeout's leader gate, a bare guid compare, so a
+    /// solo player never matches.
     pub own_guid: u64,
-    /// The **whole raid roster**, `GetRaidRosterInfo`'s 1-based array — empty outside a raid,
-    /// and **including the player** (the reference's array does; it is why `UnitInRaid("player")`
-    /// answers `1` in a raid and why this list is not `members`'s recipient-excluded shape).
-    /// `GetNumRaidMembers()` is its length: one list, no count beside it (module doc).
+    /// The whole raid roster, 1-based for `GetRaidRosterInfo`, empty outside a raid. It includes
+    /// the player, as the reference's array does, so `UnitInRaid("player")` answers `1`;
+    /// `GetNumRaidMembers()` is its length.
     pub raid: Vec<RaidMemberInfo>,
-    /// `GetLootMethod`'s method string: `"freeforall"` | `"roundrobin"` | `"master"` | `"group"` |
-    /// `"needbeforegreed"`. `Default::default()` is `""` — the *native* reports it as `"group"` (the
-    /// live shape for a solo/fresh player) when empty; the app is expected to always push a real
-    /// method once grouped.
+    /// `GetLootMethod`'s method: `"freeforall"`, `"roundrobin"`, `"master"`, `"group"` or
+    /// `"needbeforegreed"`. Empty, the default, reads as `"freeforall"`, the reference's answer
+    /// before any group.
     pub loot_method: String,
-    /// The master looter, as a party index (`0` the player, `1..=4` that `members` slot) — the loot
-    /// method's second return, `masterlooterPartyID`. `None` = no master looter (any method but
-    /// `"master"`, or a master-loot group with none assigned yet).
+    /// The master looter as a party index (`0` the player, `1..=4` a `members` slot),
+    /// `GetLootMethod`'s second return.
     pub master_looter: Option<u32>,
-    /// `GetLootThreshold`'s quality floor (`2..=4`) below which non-leader loot isn't round-robin/
-    /// master gated. `0` (the default) is fine while ungrouped — the getter has nothing to floor.
+    /// `GetLootThreshold`'s item quality, `2..=4` once grouped.
     pub loot_threshold: u32,
 }
 
-/// Outbound party/loot intents queued by the Era API's action calls, drained by the app
-/// ([`UiScript::take_party_requests`]) into the matching `CMSG_*` send. Plain data — no mlua/ECS
-/// types, [`super::unit::UnitState`]'s `TargetUnit` seam's twin.
+/// Outbound party and raid intents, drained by the app ([`UiScript::take_party_requests`]) into
+/// the matching send.
 #[derive(Clone, Debug, PartialEq)]
 pub enum PartyRequest {
-    /// `AcceptGroup()` — accept the pending invite.
+    /// `AcceptGroup()`.
     Accept,
-    /// `DeclineGroup()` — decline the pending invite.
+    /// `DeclineGroup()`.
     Decline,
-    /// `LeaveParty()` — leave the current group (no confirmation popup, decision 0434 §4).
+    /// `LeaveParty()`.
     Leave,
-    /// `InviteByName(name)` — invite by character name.
+    /// `InviteByName(name)`.
     InviteName(String),
-    /// `InviteToParty(unit)` — invite by unit TOKEN (e.g. `"target"`); the app resolves it to a name.
+    /// `InviteToParty(unit)`, by unit token; the app resolves it to a name.
     InviteUnit(String),
-    /// `UninviteFromParty(unit)` — kick a roster member, addressed by unit token (e.g. `"party2"`).
+    /// `UninviteFromParty(unit)`, by unit token.
     UninviteUnit(String),
-    /// `PromoteToPartyLeader(unit)` — hand leadership to a roster member, by unit token.
+    /// `PromoteToPartyLeader(unit)`, by unit token.
     PromoteUnit(String),
-    /// `SetLootMethod(method[, masterName])` — the master-looter argument is a character NAME (the
-    /// reference's own shape); the app resolves it to a roster member for the send.
+    /// `SetLootMethod(method[, masterName][, threshold])`; the app resolves the master looter's
+    /// name to a roster member.
     LootMethod {
         method: String,
         master_name: Option<String>,
-        /// `SetLootMethod`'s optional THIRD argument. The binding reads it whatever the method is
-        /// (`0x4e92a0`, presence-checked via `0x6f34d0`), unlike the master-looter argument, which
-        /// it reads only for `"master"` (decision 1675).
+        /// The reference reads it for every method (`0x4e92a0`, presence-checked by `0x6f34d0`),
+        /// the master looter's name only for `"master"`.
         threshold: Option<u32>,
     },
-    /// `SetLootThreshold(n)` — the new quality floor.
+    /// `SetLootThreshold(n)`.
     LootThreshold(u32),
-    /// `SetRaidTarget(unit, index)` — mark (1..=8) or clear (0) the raid-target icon on a
-    /// unit, addressed by token; the app resolves the token to a guid for the
-    /// `MSG_RAID_TARGET_UPDATE` send (decision 0434 §5's submenu, §6's board law).
+    /// `SetRaidTarget(unit, index)`: icon 1 to 8, or 0 to clear; the app resolves the token to a
+    /// guid for `MSG_RAID_TARGET_UPDATE`.
     SetRaidTarget { unit: String, index: u8 },
-    // ── The raid-management verbs (decision 1549's RaidFrame) ───────────────────────────────
-    /// `ConvertToRaid()` — the Raid tab's own button (`CMSG_GROUP_RAID_CONVERT`, leader only).
+    // ── The raid-management verbs ───────────────────────────────────────────────────────────
+    /// `ConvertToRaid()`, leader only (`CMSG_GROUP_RAID_CONVERT`).
     ConvertToRaid,
-    /// `SetRaidSubgroup(index, group)` — move raid row `index` (1-based) into subgroup `group`
-    /// (1-based). The wire (`CMSG_GROUP_CHANGE_SUB_GROUP`) takes a NAME and a 0-based subgroup;
-    /// resolving both is the app's, because only it holds the roster the index means.
+    /// `SetRaidSubgroup(index, group)`, both 1-based. The wire (`CMSG_GROUP_CHANGE_SUB_GROUP`)
+    /// takes a name and a 0-based subgroup, which the app resolves.
     SetSubgroup { index: u32, group: u32 },
-    /// `SwapRaidSubgroup(index, other)` — trade two raid rows' subgroups
-    /// (`CMSG_GROUP_SWAP_SUB_GROUP`, two names on the wire). The drag's "dropped on an occupied
-    /// slot" arm; [`Self::SetSubgroup`] is its "dropped on an empty one".
+    /// `SwapRaidSubgroup(index, other)`: trade two raid rows' subgroups
+    /// (`CMSG_GROUP_SWAP_SUB_GROUP`, two names on the wire).
     SwapSubgroup { index: u32, other: u32 },
-    /// `PromoteByName(name)` — hand leadership over, addressed by name rather than by token
-    /// (`CMSG_GROUP_SET_LEADER`, whose body is a guid — the app resolves it). UnitPopup's
-    /// RAID_LEADER row; [`Self::PromoteUnit`] is the same send from a party token.
+    /// `PromoteByName(name)` (`CMSG_GROUP_SET_LEADER`, whose guid the app resolves).
     PromoteName(String),
-    /// `PromoteToAssistant(name)` / `DemoteAssistant(name)` — the raid assistant flag
-    /// (`CMSG_GROUP_ASSISTANT_LEADER`: guid + grant byte).
+    /// `PromoteToAssistant(name)` / `DemoteAssistant(name)` (`CMSG_GROUP_ASSISTANT_LEADER`).
     AssistantLeader { name: String, grant: bool },
-    /// `UninviteFromRaid(index)` — kick raid row `index` (1-based). The reference's own row-index
-    /// form; `CMSG_GROUP_UNINVITE` takes a name, which the app resolves from the same roster the
-    /// index addresses.
+    /// `UninviteFromRaid(index)`: a 1-based raid row the app resolves to the name
+    /// `CMSG_GROUP_UNINVITE` takes.
     UninviteRaid(u32),
-    /// `DoReadyCheck()` — start one (`MSG_RAID_READY_CHECK`, empty body; leader only).
+    /// `DoReadyCheck()`, leader only (`MSG_RAID_READY_CHECK`, empty body).
     ReadyCheckStart,
-    /// `ConfirmReadyCheck(ready)` — answer one (`MSG_RAID_READY_CHECK`, one byte).
+    /// `ConfirmReadyCheck(ready)` (`MSG_RAID_READY_CHECK`, one byte).
     ReadyCheckAnswer(bool),
-    /// `RequestRaidInfo()` — ask for the saved-instance list (`CMSG_REQUEST_RAID_INFO`).
+    /// `RequestRaidInfo()` (`CMSG_REQUEST_RAID_INFO`).
     RequestRaidInfo,
 }
 
 impl super::UiScript {
-    /// Push the roster snapshot, replacing whatever was there. A bare setter (the `spellbook`/
-    /// `action` shape) — firing any `PARTY_*`/roster-changed event is the app's own diff-and-fire
-    /// job, never auto-fired here.
+    /// Push the roster snapshot, replacing it, and run `SMSG_GROUP_LIST`'s ready-check leg over the
+    /// new roster. The app fires the `PARTY_*` events.
     pub fn set_party(&mut self, state: PartyState) {
         self.model_mut().party = state;
-        // `SMSG_GROUP_LIST`'s ready-check leg (`0x4ba5f0`, reached only from the `0x7d` handler):
-        // the roster scan over the NEW roster — a member who left took their pending flag with
-        // them — and when nobody is left pending, a forced close (decision 1989).
+        // The ready-check leg (`0x4ba5f0`, from the `0x7d` handler): a member who left drops their
+        // pending flag, and nobody left pending force-closes the check.
         let lua = self.lua();
         let mut model = self.model_mut();
         if model.ready_check.deadline.is_some() {
@@ -263,12 +173,9 @@ impl super::UiScript {
         }
     }
 
-    /// The `MSG_RAID_READY_CHECK` open form arrived (decision 1989). The handler `0x4ba360` splits
-    /// on the leader guid: the **leader** takes the response-collection arm — reads the per-member
-    /// records the body carries (none, on vmangos) and force-closes if nobody is left pending;
-    /// everyone **else** arms the 30 s deadline (`0x4ba535`) that the leader-gated tick never
-    /// acts on for them, and gets the `READY_CHECK` popup — which the app fires on its own
-    /// ticket edge, so this method carries only the state half.
+    /// The `MSG_RAID_READY_CHECK` open form arrived (handler `0x4ba360`). The leader force-closes
+    /// if nobody is left pending; anyone else arms the 30 s deadline (`0x4ba535`), which their
+    /// leader-gated tick never acts on. The app fires the `READY_CHECK` popup.
     pub fn ready_check_request(&mut self, we_lead: bool) {
         let lua = self.lua();
         let now = clock(lua);
@@ -282,17 +189,11 @@ impl super::UiScript {
         }
     }
 
-    /// One member's answer, forwarded to the leader (`{guid, status}`, decisions 1989/1997).
-    /// The handler's leader arm (`0x4ba360`): the record's guid is matched against the roster
-    /// entry in full (`0x4ba3f9`/`0x4ba405`),
-    /// and a match stores **the constant 0** into the "has not answered" flag whatever the status
-    /// byte says (`0x4ba40e`; `ecx` is zeroed before the loop and never written) — so any answer,
-    /// ready or not, clears the member. The status byte gates one thing: a `0` prints
-    /// `RAID_MEMBER_NOT_READY` ("%s is not ready") for that member at arrival (`0x4ba414`), the
-    /// same raw-`_G` → format → `CHAT_MSG_SYSTEM` path as the summary. Then the close test: once
-    /// no member is both pending and ONLINE the check closes at once (`0x4ba4ce` → the worker)
-    /// rather than at the deadline — an offline member who never answered does not hold the
-    /// check open, and is still listed as AFK when it closes.
+    /// One member's answer, relayed to the leader (handler `0x4ba360`, guid matched in full at
+    /// `0x4ba3f9`/`0x4ba405`). Any answer clears the member's pending flag, as the handler stores a
+    /// constant 0 whatever the status byte (`0x4ba40e`); a `0` also prints `RAID_MEMBER_NOT_READY`
+    /// for them (`0x4ba414`). Once no member is both pending and online the check closes at once
+    /// (`0x4ba4ce`), so an offline member never holds it open but is still listed as AFK.
     pub fn ready_check_answered(&mut self, guid: u64, ready: bool) {
         let lua = self.lua();
         let mut model = self.model_mut();
@@ -316,9 +217,8 @@ impl super::UiScript {
         }
     }
 
-    /// The summary lines the timeout worker composed since the last drain — the reference's
-    /// `0x49a870(text, 10)` = a `CHAT_MSG_SYSTEM` line the client prints itself; the app pushes
-    /// them into the chat log the way every other client-composed system line goes.
+    /// Drain the ready-check lines composed since the last call; the reference prints each as a
+    /// `CHAT_MSG_SYSTEM` line (`0x49a870(text, 10)`).
     pub fn take_ready_check_lines(&mut self) -> Vec<String> {
         std::mem::take(&mut self.model_mut().ready_check.lines)
     }
@@ -328,54 +228,33 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().party_requests)
     }
 
-    /// Push the saved raid-lockout list, replacing whatever was there (decision 1549). A bare
-    /// setter like [`Self::set_party`] — firing `UPDATE_INSTANCE_INFO` is the app's diff-and-fire
-    /// job, never auto-fired here.
+    /// Push the saved raid-lockout list, replacing it; the app fires `UPDATE_INSTANCE_INFO`.
     pub fn set_saved_instances(&mut self, saved: Vec<SavedInstanceInfo>) {
         self.model_mut().saved_instances = saved;
     }
 
-    /// Drain the whisper targets `ChatFrame_SendTell` queued since the last call — the app opens
-    /// its chat edit box prefilled `/w <name> ` for each (in practice the popup queues one).
+    /// Drain the names `ChatFrame_SendTell` queued; the app opens the chat edit box on
+    /// `/w <name> ` for each.
     pub fn take_tell_requests(&mut self) -> Vec<String> {
         std::mem::take(&mut self.model_mut().tell_requests)
     }
 }
 
-/// **The leader predicate — ONE function, because the reference has one.**
-///
-/// `IsRaidLeader 0x4bb8c0` opens `mov esi,[0xbc75f8]` · `mov edi,[0xbc75fc]` and compares the pair
-/// against the local player's own GUID (`0x468550`). `IsPartyLeader 0x4e9130` opens
-/// `mov eax,[0xbc75fc]` · `mov esi,[0xbc75f8]` and compares **the same two globals** against the
-/// same GUID; its only extra instruction is an `or ecx,eax; je` short-circuit on a `0:0` cached
-/// leader, which is behaviourally inert (a zero GUID can never equal a live player's), and both
-/// prologues are byte-identical in the globals they load.
-///
-/// **So `IsRaidLeader()` is TRUE for an ordinary 5-man party leader**, and its body reads no
-/// raid-vs-party flag and never touches the roster array/count the other two raid bindings use.
-/// Stubbing it `nil` "because there is no raid" would be a divergence — which is exactly why the
-/// two registrations below share this function rather than each growing their own rule.
+/// Whether the player leads the group. `IsRaidLeader` (`0x4bb8c0`) and `IsPartyLeader`
+/// (`0x4e9130`) both compare the cached leader guid (`[0xbc75f8]`, `[0xbc75fc]`) with the player's
+/// own (`0x468550`) and read no raid flag, so `IsRaidLeader()` is true for a party leader.
 fn leads_the_group(model: &Model) -> bool {
-    // Our stand-in for "the cached leader GUID equals mine": the app's leader index is `0` when
-    // the player leads. The `members.is_empty()` guard is the reference's `0:0` case — ungrouped,
-    // the cached pair is zero and matches nobody, whereas our `leader_index` defaults to `0`.
+    // Stand-in for that compare: `leader_index` is `0` when we lead but also when ungrouped, where
+    // the reference's zero leader guid matches nobody, hence the empty-roster guard. In a raid both
+    // cover only our subgroup: a leader elsewhere also reads `0`, and a leader alone in theirs has
+    // no `members`, so there it can differ from the guid compare.
     !model.party.members.is_empty() && model.party.leader_index == 0
 }
 
-/// `GetRaidRosterInfo`'s nine values for a **1-based** index — the whole binding's behaviour,
-/// pulled out of the registration so the arity and the miss tuple are testable as one unit.
-///
-/// **Nine values on every path** (`0x4bb560`, every return site `mov eax,9`): there is no arm that
-/// returns fewer and none that returns nothing. Out of range, index ≤ 0, a null slot and a
-/// name-cache miss all converge on `0x4bb7b9`, which pushes — in order — `nil`, the number `0`,
-/// the number `1`, the number `1`, then five `nil`s. A client that models "no such member" as zero
-/// values breaks `local name = GetRaidRosterInfo(i)` differently from the real client, and one
-/// that models it as `nil, nil, …` breaks `ChatLog.lua:346`'s `for i = 1, MAX_RAID_MEMBERS` sweep
-/// in the subgroup slot.
-///
-/// Takes the row **by value**, not the model: every arm below re-enters Lua (`create_string`, and
-/// the `PLAYER_OFFLINE` global read), and this crate's rule is that a callback drops its `app_data`
-/// borrow before it does (the module doc's MAXCSTACK/borrow discipline).
+/// `GetRaidRosterInfo`'s values for one row, or the miss tuple for `None`. Nine on every path
+/// (`0x4bb560`, every return `mov eax,9`): out of range, an empty slot and a name-cache miss all
+/// reach `0x4bb7b9`, which pushes `nil, 0, 1, 1` and five `nil`s. Takes the row by value because
+/// every arm re-enters Lua, and a callback drops its `app_data` borrow before that.
 fn raid_roster_info(lua: &Lua, row: Option<RaidMemberInfo>) -> mlua::Result<MultiValue> {
     let Some(m) = row else {
         return Ok(MultiValue::from_vec(vec![
@@ -394,10 +273,9 @@ fn raid_roster_info(lua: &Lua, row: Option<RaidMemberInfo>) -> mlua::Result<Mult
         Some(s) => lua.create_string(s).map(Value::String),
         None => Ok(Value::Nil),
     };
-    // Return 7: a real zone while online, else the **localized global** `PLAYER_OFFLINE` — read
-    // out of the VM exactly as `0x703bf0` reads it, so a translated GlobalStrings.lua translates
-    // this too. A missing global lands on `0x6f3890`'s NULL guard, which pushes `nil` and still
-    // reports one value; `Value::Nil` here is that.
+    // Return 7: the zone while online, else the `PLAYER_OFFLINE` global read from the VM
+    // (`0x703bf0`), so a translated GlobalStrings.lua translates it; a missing global pushes `nil`
+    // (`0x6f3890`).
     let zone = if m.online {
         opt_str(&m.zone)?
     } else {
@@ -410,7 +288,7 @@ fn raid_roster_info(lua: &Lua, row: Option<RaidMemberInfo>) -> mlua::Result<Mult
     Ok(MultiValue::from_vec(vec![
         lua.create_string(&m.name).map(Value::String)?,
         Value::Integer(i64::from(m.rank)),
-        // `0x4bb61a inc eax` — stored 0-based, exposed 1-based (VERIFIED adjustment).
+        // Stored 0-based, exposed 1-based (`0x4bb61a inc eax`).
         Value::Integer(i64::from(m.subgroup) + 1),
         Value::Integer(i64::from(m.level)),
         opt_str(&m.class)?,
@@ -421,13 +299,11 @@ fn raid_roster_info(lua: &Lua, row: Option<RaidMemberInfo>) -> mlua::Result<Mult
     ]))
 }
 
-/// Register the party/raid globals reading the roster snapshot store (the same style/place `unit`
-/// registers the `Unit*` globals).
+/// Register the party and raid globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetNumPartyMembers() → the roster's member count (0 = not in a group; never counts the player
-    // themself, matching SMSG_GROUP_LIST's recipient-excluded array).
+    // GetNumPartyMembers() → the other members, never counting the player; 0 when ungrouped.
     g.set(
         "GetNumPartyMembers",
         lua.create_function(|lua, ()| {
@@ -436,9 +312,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetNumRaidMembers() → the raid roster's length (0 outside a raid). The count the reference
-    // reads (`0xb713e0`) bounds the very array `GetRaidRosterInfo` indexes (`0xb712a8`), so it is
-    // the same list here, not a number beside one.
+    // GetNumRaidMembers() → the raid roster's length, 0 outside a raid.
     g.set(
         "GetNumRaidMembers",
         lua.create_function(|lua, ()| {
@@ -447,21 +321,18 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetRaidRosterInfo(index) → name, rank, subgroup, level, class, fileName, zone, online, <9th>
-    //
-    // 1-BASED, and **exactly nine values on every path** — see [`raid_roster_info`] for the arity
-    // law and the fixed miss tuple. The ONLY raise in `0x4bb560` is a non-number argument
-    // (`0x4bb582 call 0x6f34d0` → `0x4bb591 call 0x6f4940`, usage string `0x8474a0`); an index of
-    // 0, of −1, of 500, or of a live-but-uncached member all return the tuple.
+    // GetRaidRosterInfo(index) → name, rank, subgroup, level, class, fileName, zone, online and an
+    // unnamed ninth, 1-based. Its only raise is a non-number argument (`0x4bb582 call 0x6f34d0`,
+    // `0x4bb591 call 0x6f4940`, usage string `0x8474a0`).
     g.set(
         "GetRaidRosterInfo",
         lua.create_function(|lua, index: Value| {
             let index = number_arg(lua, index, "Usage: GetRaidRosterInfo(index)")?;
             let row = {
                 let model = lua.app_data_ref::<Model>().expect("model app_data");
-                // `0x4bb5bb dec eax` then `0x4bb5be jae` — an UNSIGNED compare after the
-                // decrement, so ONE branch catches index ≤ 0 and index > count together (and the
-                // `dec` wraps rather than trapping, which `wrapping_sub` keeps true of `i32::MIN`).
+                // One unsigned compare after the decrement (`0x4bb5bb dec eax`, `0x4bb5be jae`)
+                // catches an index of 0 or below and one past the count; `dec` wraps, and
+                // `wrapping_sub` keeps that true of `i32::MIN`.
                 usize::try_from(index.wrapping_sub(1))
                     .ok()
                     .and_then(|i| model.party.raid.get(i))
@@ -473,8 +344,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsRaidLeader() → 1 / nil, and TRUE FOR A PARTY LEADER — the shared predicate's whole point
-    // ([`leads_the_group`]). No arguments, never raises.
+    // IsRaidLeader() → 1 or nil, true for a party leader too (`leads_the_group`).
     g.set(
         "IsRaidLeader",
         lua.create_function(|lua, ()| {
@@ -487,7 +357,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPartyMember(id) → 1 if id is a live 1-based roster slot, else nil (era 1/nil shape).
+    // GetPartyMember(id) → 1 for a filled 1-based slot, else nil.
     g.set(
         "GetPartyMember",
         lua.create_function(|lua, id: i64| {
@@ -510,8 +380,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsPartyLeader() → 1 iff we're grouped AND lead it, else nil (a solo player doesn't "lead").
-    // Shares [`leads_the_group`] with `IsRaidLeader` because the reference shares the globals.
+    // IsPartyLeader() → 1 when grouped and leading, else nil; the same predicate as IsRaidLeader.
     g.set(
         "IsPartyLeader",
         lua.create_function(|lua, ()| {
@@ -524,16 +393,13 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetLootMethod() → lootmethod, masterlooterPartyID (the era 2-tuple return; later clients add
-    // a raid index third return we don't carry). An unset method (never pushed) reports the
-    // fresh-player shape: "group", nil.
+    // GetLootMethod() → lootmethod, masterlooterPartyID: two returns in 1.12.
     g.set(
         "GetLootMethod",
         lua.create_function(|lua, ()| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
-            // **`freeforall`, not `group`.** The three cells this reads sit past `.data`'s raw end
-            // in the zero-filled tail, so a client that has never been in a group answers the
-            // zeroth method — which is `freeforall`. Decision 1840.
+            // Never grouped, the reference reads zero-filled cells past `.data`'s end, and method
+            // 0 is `freeforall`.
             let method = if model.party.loot_method.is_empty() {
                 "freeforall"
             } else {
@@ -547,7 +413,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetLootThreshold() → the quality floor (0 while ungrouped is fine — nothing to floor).
+    // GetLootThreshold() → the loot quality threshold.
     g.set(
         "GetLootThreshold",
         lua.create_function(|lua, ()| {
@@ -556,8 +422,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The outbound half: each call queues a PartyRequest, the app drains and sends. No-return, era
-    // shape (fire-and-forget, like TargetUnit/CastSpell).
+    // The party verbs queue a `PartyRequest` and return nothing.
     g.set(
         "AcceptGroup",
         lua.create_function(|lua, ()| {
@@ -614,9 +479,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // SetLootMethod("method" [,master] [,threshold]) — the reference's own usage string
-    // (`0x84c42c`). The master-looter argument is read ONLY for "master"; the threshold argument
-    // is optional for every method (decision 1675).
+    // SetLootMethod("method" [,master] [,threshold]), the reference's usage string (`0x84c42c`).
     g.set(
         "SetLootMethod",
         lua.create_function(
@@ -639,13 +502,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // SetRaidTarget(unit, index) — the ENGINE verb. `SetRaidTargetIcon` is NOT one: it is FrameXML,
-    // `function SetRaidTargetIcon(unit, index)` at `TargetFrame.lua:486`, a toggle wrapper that
-    // calls this with 0 when the unit already wears `index`. We had registered the wrapper's name on
-    // this body, which behaved correctly and so never showed — until 1751 put `TargetFrame.lua` on
-    // the chain and the wrapper started calling a `SetRaidTarget` that did not exist. Proof both
-    // ways: no `function SetRaidTarget(` anywhere in the reference's FrameXML, and both
-    // `TargetFrame.lua:488`/`:490` and `Bindings.xml:1160` call it bare.
+    // SetRaidTarget(unit, index) is the engine verb. `SetRaidTargetIcon` is FrameXML's toggle
+    // around it (`TargetFrame.lua:486`), and `TargetFrame.lua:488`, `:490` and `Bindings.xml:1160`
+    // call it bare.
     g.set(
         "SetRaidTarget",
         lua.create_function(|lua, (unit, index): (String, u8)| {
@@ -657,28 +516,19 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsRaidOfficer() → nil, always: a 1.12 PARTY has no officer rank (the assistant flag is a
-    // raid concept). The popup's leader-or-assistant gates read this and fall back to the leader
-    // half. The roster now carries the assistant rank ([`RaidMemberInfo::rank`], `1`), so the
-    // *data* to answer this exists — what does not is a reading of `IsRaidOfficer`'s own body,
-    // and "it is probably rank ≥ 1 for the player's row" is a guess, not a mechanism. Left nil
-    // until someone reads the bytes.
+    // IsRaidOfficer() → always nil: its reference body (`0x4bb910`) is untraced. So the RaidFrame
+    // enables its add-member button for the leader only, where the reference also enables it for
+    // an assistant.
     g.set(
         "IsRaidOfficer",
         lua.create_function(|_, ()| Ok(Value::Nil))?,
     )?;
 
-    // ── The raid-management verbs (decision 1549) ────────────────────────────────────────────
-    //
-    // All nine share the same shape (`ConvertToRaid 0x4bbc90`, `SetRaidSubgroup 0x4bb990`,
-    // `SwapRaidSubgroup 0x4bbb00`, `PromoteToAssistant 0x4bbd20`, `RequestRaidInfo 0x4a1850`,
-    // `GetSavedInstanceInfo 0x4a1920`, `UninviteFromRaid 0x48a580`, `SetRaidRosterSelection
-    // 0x4bb820`): each marshals and delegates to a C++ method or net-send, with no inline
-    // fidelity math. So the *binding* has no law of its own to reproduce: the law is the wire's,
-    // which `benilla-protocol`'s `group` family already carries byte-golden, and the marshalling
-    // is the queue below. Nothing here is a guess about a body nobody has read.
-    //
-    // They queue rather than send for the module doc's reason: this crate cannot reach the net.
+    // ── The raid-management verbs ────────────────────────────────────────────
+    // Each only marshals its arguments into a client call or a send (`ConvertToRaid 0x4bbc90`,
+    // `SetRaidSubgroup 0x4bb990`, `SwapRaidSubgroup 0x4bbb00`, `PromoteToAssistant 0x4bbd20`,
+    // `RequestRaidInfo 0x4a1850`, `GetSavedInstanceInfo 0x4a1920`, `UninviteFromRaid 0x48a580`,
+    // `SetRaidRosterSelection 0x4bb820`), so the verbs here queue a request.
     g.set(
         "ConvertToRaid",
         lua.create_function(|lua, ()| {
@@ -687,9 +537,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // SetRaidSubgroup(index, group) / SwapRaidSubgroup(index, other) — the drag's two landings.
-    // Both take numbers through the shared argument gate, so a non-number raises the reference's
-    // usage error rather than silently queueing a zero.
+    // SetRaidSubgroup(index, group) / SwapRaidSubgroup(index, other), the drag's two drops: a
+    // non-number raises the usage error rather than queueing a zero.
     g.set(
         "SetRaidSubgroup",
         lua.create_function(|lua, (index, group): (Value, Value)| {
@@ -752,10 +601,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, ()| {
             let now = clock(lua);
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // The worker `0x4bb1d0` (decision 1989): every roster member except the caller is
-            // flagged "has not answered" (`0x4bb24c`), the caller cleared (`0x4bb258`), the 30 s
-            // deadline armed (`0x4bb2b6`) — then the packet. A party has no raid roster, so the
-            // flags are empty there and the leader's own echo closes the check at once.
+            // The worker `0x4bb1d0` flags every roster member but the caller as pending
+            // (`0x4bb24c`, `0x4bb258`) and arms the 30 s deadline (`0x4bb2b6`), then sends. A
+            // party has no raid roster, so nothing is flagged and the leader's echo closes it.
             let own = model.party.own_guid;
             model.ready_check.unanswered = model
                 .party
@@ -769,16 +617,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // `CheckReadyCheckTime` (`0x4bc120` → `0x4bb310`) — the ready-check timeout tick, called from
-    // the stock `UIParent.xml`'s `<OnUpdate>` every frame and driving the 30-second expiry alone
-    // (nothing in the engine polls it). Four conjuncts, any failure writing nothing: a deadline is
-    // armed, it has been reached, and the active player's guid equals the group leader's — a
-    // LEADER gate, so it is observably inert for anyone else. On expiry it disarms the deadline
-    // (the only clear-to-zero outside module init), lists every roster member still flagged as
-    // unanswered, and prints `RAID_MEMBERS_AFK` with the `", "`-joined names — or
-    // `READY_CHECK_NO_AFK` — as a `CHAT_MSG_SYSTEM` line. Both keys are read raw off `_G`
-    // (`0x704350`: `lua_gettable` on GLOBALSINDEX, empty-string default), never through
-    // `GetText`. Sends no packet, raises nothing, returns nothing (decision 1989).
+    // CheckReadyCheckTime() (`0x4bc120` → `0x4bb310`), called every frame from stock
+    // `UIParent.xml`'s `OnUpdate`, alone drives the 30 s expiry. Once an armed deadline passes, and
+    // only on the leader's client, it disarms and prints `RAID_MEMBERS_AFK` with the pending names
+    // joined by `", "`, or `READY_CHECK_NO_AFK`, as a `CHAT_MSG_SYSTEM` line. Both strings are read
+    // raw from `_G` with an empty default (`0x704350`), not through `GetText`; nothing is sent.
     g.set(
         "CheckReadyCheckTime",
         lua.create_function(|lua, ()| {
@@ -788,9 +631,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // ConfirmReadyCheck(ready) — the popup's two buttons, and the argument is read for TRUTH, not
-    // for a number: the reference's own No button calls it with no argument at all
-    // (`ConfirmReadyCheck()`) while Yes passes `1`, so "absent" has to mean "not ready".
+    // ConfirmReadyCheck(ready) reads its argument as truth: the reference's No button passes no
+    // argument, Yes passes `1`.
     g.set(
         "ConfirmReadyCheck",
         lua.create_function(|lua, ready: Value| {
@@ -811,9 +653,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetNumSavedInstances() / GetSavedInstanceInfo(index) — the Raid Info panel's pair, over the
-    // app-pushed list. 1-based like every other indexed getter here, and a miss answers a plain
-    // `nil` (the panel's own loop only ever indexes inside the count it just read).
+    // GetNumSavedInstances() / GetSavedInstanceInfo(index), 1-based over the pushed list; a miss
+    // returns nothing.
     g.set(
         "GetNumSavedInstances",
         lua.create_function(|lua, ()| {
@@ -843,9 +684,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetRaidRosterSelection(index) / GetRaidRosterSelection() — a purely CLIENT-SIDE cursor (the
-    // reference's `0x4bb820` writes a global; nothing is sent). The RaidFrame sets it when a row
-    // is picked up so the menu and the drag agree on who is being acted on.
+    // SetRaidRosterSelection(index) / GetRaidRosterSelection(): a client-side cursor; the
+    // reference's `0x4bb820` writes a global and sends nothing.
     g.set(
         "SetRaidRosterSelection",
         lua.create_function(|lua, index: Value| {
@@ -863,10 +703,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ChatFrame_SendTell(name) — the popup's WHISPER action. In the ref this is ChatFrame.lua
-    // filling the edit box with "/w name "; our chat edit is app-side (ui_chat), so the call
-    // queues the name for the app to open the edit box prefilled (UiScript::take_tell_requests
-    // drains — the PartyRequest seam's chat sibling).
+    // ChatFrame_SendTell(name) is FrameXML in the reference (`ChatFrame.lua:1606`, opening the
+    // edit box on `/w name `); the chat edit box is app-side here, so this queues the name for
+    // `UiScript::take_tell_requests`.
     g.set(
         "ChatFrame_SendTell",
         lua.create_function(|lua, name: String| {
@@ -882,11 +721,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 /// The ready-check deadline, `0x7530` ms after the arm (`0x4ba535`, `0x4bb2b6`).
 const READY_CHECK_SECONDS: f64 = 30.0;
 
-/// The client's ready-check state (`RaidInfo.cpp`, decision 1989): the armed deadline
-/// (`[0xb713f4]`, `None` = disarmed) and the roster members whose "has not answered yet" flag
-/// (`[entry+0x158]`) is set, plus the summary lines the timeout worker composed and the app has
-/// not yet pushed into chat. Outside [`PartyState`] because a roster push replaces that whole
-/// snapshot and this survives one — the reference keeps the two in different tables too.
+/// The ready-check state: the armed deadline (`[0xb713f4]`), the members whose pending flag
+/// (`[entry+0x158]`) is set, and summary lines not yet pushed to chat. Outside [`PartyState`]
+/// because a roster push replaces that and this survives it.
 #[derive(Debug, Default)]
 pub(crate) struct ReadyCheckState {
     pub(crate) deadline: Option<f64>,
@@ -894,12 +731,12 @@ pub(crate) struct ReadyCheckState {
     pub(crate) lines: Vec<String>,
 }
 
-/// `GetTime()`'s clock — the session seconds `UiScript::tick` advances.
+/// `GetTime()`'s clock, the session seconds `UiScript::tick` advances.
 fn clock(lua: &Lua) -> f64 {
     lua.globals().get("__benilla_now").unwrap_or(0.0)
 }
 
-/// The timeout worker `0x4bb310` — see `CheckReadyCheckTime`'s note for the contract.
+/// The timeout worker `0x4bb310`.
 fn ready_check_tick(lua: &Lua, model: &mut Model, now: f64) {
     let Some(deadline) = model.ready_check.deadline else {
         return;
@@ -911,8 +748,7 @@ fn ready_check_tick(lua: &Lua, model: &mut Model, now: f64) {
         return;
     }
     model.ready_check.deadline = None;
-    // The roster walk: an unresolved name is silently skipped (`0x55f080` with its query arm
-    // off), so a flagged member the roster cannot name contributes nothing to the list.
+    // A pending member the roster cannot name is skipped (`0x55f080`, its query arm off).
     let names: Vec<&str> = model
         .ready_check
         .unanswered
@@ -930,9 +766,9 @@ fn ready_check_tick(lua: &Lua, model: &mut Model, now: f64) {
     model.ready_check.lines.push(text);
 }
 
-/// The `0x322` handler's close predicate (`0x4ba498`–`0x4ba4cc`, decision 1997): a member still
-/// holds the check open only while they are BOTH flagged unanswered AND online (`[entry+0x18]`
-/// bit 0, the `SMSG_GROUP_LIST` online byte). An empty roster closes at once (`0x4ba3ea`).
+/// The `0x322` handler's close test (`0x4ba498`-`0x4ba4cc`): a member holds the check open only
+/// while pending and online (`[entry+0x18]` bit 0, `SMSG_GROUP_LIST`'s online bit). An empty
+/// roster closes at once (`0x4ba3ea`).
 fn ready_check_pending_online(model: &Model) -> bool {
     model
         .ready_check
@@ -941,8 +777,8 @@ fn ready_check_pending_online(model: &Model) -> bool {
         .any(|g| model.party.raid.iter().any(|m| m.guid == *g && m.online))
 }
 
-/// The two C-side force-close sites (`0x4ba4d4`, `0x4bacb4`): the deadline is set to `now − 1`
-/// and the worker runs at once. The arm test is theirs too — both force only an armed check.
+/// The force-close sites (`0x4ba4d4`, `0x4bacb4`): an armed deadline becomes `now - 1` and the
+/// worker runs at once.
 fn ready_check_force_close(lua: &Lua, model: &mut Model) {
     if model.ready_check.deadline.is_none() {
         return;
@@ -990,7 +826,6 @@ mod tests {
         assert!(s.eval::<bool>("return GetPartyMember(3) == nil").unwrap());
         assert!(s.eval::<bool>("return GetPartyMember(0) == nil").unwrap());
         assert_eq!(s.eval::<i64>("return GetPartyLeaderIndex()").unwrap(), 1);
-        // Alice (party1) leads, not us.
         assert!(s.eval::<bool>("return IsPartyLeader() == nil").unwrap());
         let (method, master) = s
             .eval::<(String, Option<i64>)>("return GetLootMethod()")
@@ -1030,18 +865,12 @@ mod tests {
         let (method, master) = s
             .eval::<(String, Option<i64>)>("return GetLootMethod()")
             .unwrap();
-        // **`freeforall` is the UNGROUPED answer**, not `group`: the cells the reference reads
-        // sit in `.data`'s zero-filled tail, so a client that has never been in a group reports
-        // the zeroth method (decision 1840). The `group` above is a real party's, and stays.
+        // Never grouped reads method 0, `freeforall`; the `group` above is a real party's.
         assert_eq!(method, "freeforall");
         assert_eq!(master, None);
     }
 
     // ── The raid trio (`UnitInRaid`, `GetRaidRosterInfo`, `IsRaidLeader`) ────────────────────
-    //
-    // One test per return-shape trap, in `item_stats`'s `get_item_info_tests` style: the ARITY
-    // assertion is half of each, because a signature regression is the failure every individual
-    // read still survives.
 
     fn raider(name: &str, guid: u64) -> crate::script::RaidMemberInfo {
         crate::script::RaidMemberInfo {
@@ -1064,16 +893,14 @@ mod tests {
             .collect();
         raid[0].rank = 2; // the leader
         raid[0].name = "Me".into();
-        raid[3].subgroup = 1; // stored 0-based — the binding exposes 2
+        raid[3].subgroup = 1; // stored 0-based, exposed 2
         PartyState {
             raid,
             ..Default::default()
         }
     }
 
-    /// **Nine values on every path**, including the paths that have no member to describe. Every
-    /// return site in `0x4bb560` is `mov eax,9`; the out-of-range arm `0x4bb7b9` pushes nine
-    /// values of its own rather than returning nothing.
+    /// Every return site in `0x4bb560` is `mov eax,9`, the miss arm `0x4bb7b9` included.
     #[test]
     fn get_raid_roster_info_returns_nine_values_on_every_path() {
         let mut s = UiScript::new().unwrap();
@@ -1086,13 +913,11 @@ mod tests {
                 "index {index} must still be a nine-value answer"
             );
         }
-        // And with no raid at all — the shape does not depend on being in one.
         let s = UiScript::new().unwrap();
         assert_eq!(s.arity("GetRaidRosterInfo(1)").unwrap(), 9);
     }
 
-    /// The miss tuple is `(nil, 0, 1, 1, nil, nil, nil, nil, nil)` — **not** nine nils, and not
-    /// nothing. `0x4bb7b9` pushes nil, then the number 0, then 1, then 1, then five nils.
+    /// `0x4bb7b9` pushes `nil, 0, 1, 1` and five nils.
     #[test]
     fn get_raid_roster_info_misses_with_the_fixed_tuple() {
         let mut s = UiScript::new().unwrap();
@@ -1109,8 +934,7 @@ mod tests {
         );
         assert!(e && f && g && h && i, "the last five are nil");
 
-        // An in-range member whose NAME has not been cached takes the same arm — the reference's
-        // `0x4bb5f8 je 0x4bb7b9`, which is why a client must not model this as "returns nothing".
+        // An in-range member with no cached name takes the same arm (`0x4bb5f8 je 0x4bb7b9`).
         let mut party = ten_player_raid();
         party.raid[1].name = String::new();
         s.set_party(party);
@@ -1120,8 +944,6 @@ mod tests {
         assert!(name_nil && rank == 0, "an uncached name is a full miss");
     }
 
-    /// The success tuple, destructured positionally exactly as `ChatLog.lua:347` and
-    /// `oRA2/Leader/Ready.lua:241` destructure it.
     #[test]
     fn get_raid_roster_info_reports_the_pushed_row() {
         let mut s = UiScript::new().unwrap();
@@ -1155,8 +977,7 @@ mod tests {
         );
     }
 
-    /// An OFFLINE member's zone slot carries the localized `PLAYER_OFFLINE` global, never nil —
-    /// and return 8 goes nil on that same arm (`0x4bb705`).
+    /// Return 8 goes nil on the same arm (`0x4bb705`).
     #[test]
     fn get_raid_roster_info_puts_player_offline_in_the_zone_slot() {
         let mut s = UiScript::new().unwrap();
@@ -1164,7 +985,7 @@ mod tests {
         party.raid[1].online = false;
         party.raid[1].zone = Some("Molten Core".into()); // ignored on the offline arm
         s.set_party(party);
-        // GlobalStrings.lua is the app's to load; the binding reads whatever the VM has.
+        // The binding reads whatever `PLAYER_OFFLINE` the VM holds.
         s.run(r#"PLAYER_OFFLINE = "Offline""#).unwrap();
         let (zone, online): (String, Option<i64>) = s
             .eval("local _,_,_,_,_,_,g,h = GetRaidRosterInfo(2) return g, h")
@@ -1173,8 +994,7 @@ mod tests {
         assert_eq!(online, None);
     }
 
-    /// A non-number argument is the ONLY raise in the whole function (`0x4bb591`), and it raises
-    /// rather than returning nil or nothing — `0x6f4940` never returns.
+    /// The raise at `0x4bb591` goes through `0x6f4940`, which never returns.
     #[test]
     fn get_raid_roster_info_raises_only_on_a_non_number() {
         let s = UiScript::new().unwrap();
@@ -1183,12 +1003,11 @@ mod tests {
             format!("{err}").contains("Usage: GetRaidRosterInfo(index)"),
             "got {err}"
         );
-        // A numeric string coerces (Lua 5.1's `lua_isnumber`) and does NOT raise.
+        // A numeric string coerces (`lua_isnumber`) and does not raise.
         assert_eq!(s.arity(r#"GetRaidRosterInfo("3")"#).unwrap(), 9);
     }
 
-    /// `UnitInRaid` answers the **constant 1**, not a roster index — the value is the hard-coded
-    /// double at `0x51637e`, and the helper underneath never exposes a counter.
+    /// The 1 is the constant double at `0x51637e`.
     #[test]
     fn unit_in_raid_answers_one_not_an_index() {
         let mut s = UiScript::new().unwrap();
@@ -1206,21 +1025,16 @@ mod tests {
         assert!(s
             .eval::<bool>(r#"return UnitInRaid("mouseover") == nil"#)
             .unwrap());
-        // **The input partition, and it is NOT "never raises".** A quiet nil covers a missing,
-        // wrong-typed, or a recognised-but-unmatched token; a token matching none of the
-        // resolver's prefixes raises instead.
-        //
-        // Quiet nil: `0x6f3690` returns NULL for a missing or uncoercible argument, `0x515970` maps
-        // NULL/empty to GUID `0:0`, and `0x4baee0` short-circuits `0:0` to false at entry.
+        // Nil for a missing, wrong-typed or unmatched token: `0x6f3690` gives NULL, `0x515970` maps
+        // it to guid 0, and `0x4baee0` rejects guid 0.
         for call in ["UnitInRaid()", "UnitInRaid(nil)", r#"UnitInRaid("party3")"#] {
             assert!(
                 s.eval::<bool>(&format!("return {call} == nil")).unwrap(),
                 "{call} must answer nil"
             );
         }
-        // Raise: a token matching none of the nine prefixes reaches
-        // `luaL_error("Unknown unit name: %s")` and longjmps — and a NUMBER is coerced to a string
-        // first, so it raises too. `UnitInRaid("bogus")` never returns on the real client.
+        // A token matching none of the nine prefixes raises `Unknown unit name: %s`, and a number
+        // is coerced to a string first.
         for call in ["UnitInRaid(7)", r#"UnitInRaid("nosuchtoken")"#] {
             assert!(
                 s.run(call).is_err(),
@@ -1229,15 +1043,12 @@ mod tests {
         }
     }
 
-    /// **`IsRaidLeader()` is true for an ordinary 5-man party leader.** Its body reads the same
-    /// two leader-GUID globals `IsPartyLeader` does and carries no raid-vs-party flag at all
-    /// (`0x4bb8c0` vs `0x4e9130`). Answering nil
-    /// "because there is no raid" would be the divergence.
+    /// `0x4bb8c0` reads the same leader guid as `0x4e9130`, and no raid flag.
     #[test]
     fn is_raid_leader_is_true_for_a_party_leader() {
         let mut s = UiScript::new().unwrap();
         let mut party = two_member_party();
-        party.leader_index = 0; // we lead — a PARTY, with an empty raid roster
+        party.leader_index = 0; // we lead a party, with no raid roster
         s.set_party(party);
         assert!(
             s.eval::<i64>("return GetNumRaidMembers()").unwrap() == 0,
@@ -1246,18 +1057,15 @@ mod tests {
         assert_eq!(s.eval::<i64>("return IsRaidLeader()").unwrap(), 1);
         assert_eq!(s.eval::<i64>("return IsPartyLeader()").unwrap(), 1);
 
-        // Somebody else leads: both go nil, together.
         s.set_party(two_member_party()); // leader_index 1 = Alice
         assert!(s.eval::<bool>("return IsRaidLeader() == nil").unwrap());
         assert!(s.eval::<bool>("return IsPartyLeader() == nil").unwrap());
 
-        // Ungrouped: nil (the reference's cached leader pair is `0:0` and matches nobody).
+        // Ungrouped: the cached leader guid is 0 and matches nobody.
         let s = UiScript::new().unwrap();
         assert!(s.eval::<bool>("return IsRaidLeader() == nil").unwrap());
     }
 
-    /// One list, not a count beside one: `GetNumRaidMembers` and `GetRaidRosterInfo` cannot
-    /// disagree about how many members there are.
     #[test]
     fn get_num_raid_members_bounds_the_roster_it_indexes() {
         let mut s = UiScript::new().unwrap();
@@ -1274,7 +1082,6 @@ mod tests {
     #[test]
     fn intent_natives_queue_the_exact_request_sequence() {
         let mut s = UiScript::new().unwrap();
-        // Nothing queued until a call lands.
         assert!(s.take_party_requests().is_empty());
 
         s.run("AcceptGroup()").unwrap();
@@ -1305,7 +1112,6 @@ mod tests {
                 PartyRequest::LootThreshold(3),
             ]
         );
-        // The drain is a take — a second read is empty.
         assert!(s.take_party_requests().is_empty());
     }
 
@@ -1322,8 +1128,7 @@ mod tests {
             }]
         );
 
-        // The optional THIRD argument, which the real binding reads for every method — not only
-        // for "master", the way the master-looter argument is read (decision 1675).
+        // The third argument is read for every method.
         s.run(r#"SetLootMethod("group", nil, 4)"#).unwrap();
         assert_eq!(
             s.take_party_requests(),
@@ -1355,13 +1160,7 @@ mod tests {
         );
     }
 
-    /// `IsRaidOfficer()` still answers nil, and the raid arc landing (decision 1549) did NOT
-    /// change that — it is not waiting on a feature, it is waiting on a reading of `0x4bb910`'s
-    /// own body. The binding's doc carries the refusal; this pins the behaviour so a later
-    /// "surely it is just rank >= 1" edit has to argue with a test.
-    ///
-    /// What it costs today, stated where someone will find it: `RaidFrameAddMemberButton` is
-    /// enabled for the raid LEADER only, where the reference also enables it for an assistant.
+    /// Nil until `0x4bb910`'s body is traced; "rank >= 1" would be a guess.
     #[test]
     fn is_raid_officer_is_still_nil_and_that_is_a_missing_carve_not_a_missing_feature() {
         let s = UiScript::new().unwrap();
@@ -1377,7 +1176,7 @@ mod tests {
         assert!(s.take_tell_requests().is_empty());
     }
 
-    // ── The identity predicates (decision 0434 §5 — the popup's menu pick + gating) ─────────────
+    // ── The identity predicates ─────────────────────────────────────────────
 
     fn unit(exists: bool, guid: u64) -> crate::script::UnitState {
         crate::script::UnitState {
@@ -1393,7 +1192,6 @@ mod tests {
         s.set_unit("player", Some(unit(true, 0x10)));
         s.set_unit("target", Some(unit(true, 0x10)));
         s.set_unit("party1", Some(unit(true, 0x20)));
-        // Same guid across tokens; same token trivially; different guids nil.
         assert_eq!(
             s.eval::<i64>(r#"return UnitIsUnit("target", "player")"#)
                 .unwrap(),
@@ -1407,21 +1205,19 @@ mod tests {
         assert!(s
             .eval::<bool>(r#"return UnitIsUnit("party1", "player") == nil"#)
             .unwrap());
-        // Zero guids never match across tokens (unknown identity is not identity).
+        // Zero guids never match across tokens.
         s.set_unit("target", Some(unit(true, 0)));
         s.set_unit("mouseover", Some(unit(true, 0)));
         assert!(s
             .eval::<bool>(r#"return UnitIsUnit("target", "mouseover") == nil"#)
             .unwrap());
-        // A missing token is nil.
         assert!(s
             .eval::<bool>(r#"return UnitIsUnit("pet", "player") == nil"#)
             .unwrap());
     }
 
-    /// `UnitPlayerOrPetInParty`/`InRaid` (1958): a member's own guid, or a unit whose OWNER is a
-    /// member — the party's for the one, the raid roster's for the other; a stranger's pet is
-    /// nobody's; ungrouped is nil.
+    /// A member's own guid, or a unit whose owner is a member: the party's for
+    /// `UnitPlayerOrPetInParty`, the raid roster's for `UnitPlayerOrPetInRaid`.
     #[test]
     fn unit_player_or_pet_in_party_reads_the_owner() {
         let mut s = UiScript::new().unwrap();
@@ -1454,7 +1250,6 @@ mod tests {
                 .unwrap(),
             1
         );
-        // The raid twin over the raid roster.
         s.set_party(ten_player_raid());
         let mut raiders_pet = unit(true, 0xC0FFEE);
         raiders_pet.owner = ten_player_raid().raid[0].guid;
@@ -1476,11 +1271,9 @@ mod tests {
         s.set_party(two_member_party());
         s.set_unit("player", Some(unit(true, 0x10)));
         s.set_unit("party1", Some(unit(true, 0xA11CE)));
-        // The target IS Alice (guid match through an arbitrary token).
         s.set_unit("target", Some(unit(true, 0xA11CE)));
         assert_eq!(s.eval::<i64>(r#"return UnitInParty("target")"#).unwrap(), 1);
         assert_eq!(s.eval::<i64>(r#"return UnitInParty("party1")"#).unwrap(), 1);
-        // A stranger's guid is nil.
         s.set_unit("target", Some(unit(true, 0xDEAD)));
         assert!(s
             .eval::<bool>(r#"return UnitInParty("target") == nil"#)
@@ -1504,7 +1297,6 @@ mod tests {
                 .unwrap(),
             1
         );
-        // A hostile player, and a friendly NPC, both fail the gate.
         let mut hostile = friendly.clone();
         hostile.reaction = 2;
         s.set_unit("target", Some(hostile));
@@ -1519,8 +1311,6 @@ mod tests {
             .unwrap());
     }
 
-    /// Every raid-management verb queues the request it names, with its arguments in the order
-    /// the reference's binding takes them — the seam the whole pane acts through (decision 1549).
     #[test]
     fn the_raid_verbs_queue_what_they_name() {
         let mut s = UiScript::new().unwrap();
@@ -1564,9 +1354,7 @@ mod tests {
         assert!(s.take_party_requests().is_empty(), "the drain empties");
     }
 
-    /// `ConfirmReadyCheck` reads its argument for TRUTH, not for a number — the reference's No
-    /// button calls it with **no argument at all** while Yes passes `1`, so "absent" has to be the
-    /// not-ready answer or every declined ready check reads as accepted.
+    /// The reference's No button passes no argument, Yes passes `1`.
     #[test]
     fn confirm_ready_check_treats_an_absent_argument_as_not_ready() {
         let mut s = UiScript::new().unwrap();
@@ -1578,14 +1366,12 @@ mod tests {
                 PartyRequest::ReadyCheckAnswer(true),
                 PartyRequest::ReadyCheckAnswer(false),
                 PartyRequest::ReadyCheckAnswer(false),
-                // `0` is TRUTHY in Lua, and the binding is a truth test — so this is ready.
+                // `0` is true in Lua.
                 PartyRequest::ReadyCheckAnswer(true),
             ]
         );
     }
 
-    /// The saved-lockout pair: 1-based, three returns, and a miss is a plain nothing (the panel's
-    /// own loop only ever indexes inside the count it just read).
     #[test]
     fn saved_instance_info_reads_the_pushed_list() {
         use crate::script::SavedInstanceInfo;
@@ -1619,13 +1405,11 @@ mod tests {
                 "index {miss} is a miss"
             );
         }
-        // A non-number still raises, like every other indexed getter here.
         assert!(s
             .eval::<i64>(r#"return GetSavedInstanceInfo("x")"#)
             .is_err());
     }
 
-    /// `SetRaidRosterSelection` is purely client-side: it moves a cursor and sends nothing.
     #[test]
     fn the_raid_roster_selection_is_a_local_cursor() {
         let mut s = UiScript::new().unwrap();
@@ -1658,9 +1442,9 @@ mod tests {
             .unwrap());
     }
 
-    // ── The ready-check timeout (decision 1989) ─────────────────────────────────────────────
+    // ── The ready-check timeout ─────────────────────────────────────────────
 
-    /// A raid we lead: us, Alice and Bob on the roster; the two strings the summary reads raw.
+    /// Us, Alice and Bob, with the two summary strings set.
     fn raid_we_lead(s: &UiScript) -> PartyState {
         s.run(
             r#"RAID_MEMBERS_AFK = "The following players are AFK: %s"
@@ -1698,9 +1482,6 @@ mod tests {
         }
     }
 
-    /// `DoReadyCheck` flags every roster member but the caller and arms 30 s; the tick is a no-op
-    /// before the deadline, prints the `", "`-joined unanswered names on it, and — the only
-    /// clear-to-zero — disarms, so the next tick prints nothing.
     #[test]
     fn the_leaders_check_times_out_into_the_afk_list_and_disarms() {
         let mut s = UiScript::new().unwrap();
@@ -1727,9 +1508,7 @@ mod tests {
         );
     }
 
-    /// An answer clears its member's flag; the answer that leaves nobody pending (and online)
-    /// closes the check at once (`0x4ba4d9`), well before the deadline. (A "not ready" answer
-    /// does the same and prints its line first — the test below.)
+    /// The answer that leaves nobody pending closes the check at once (`0x4ba4d9`).
     #[test]
     fn an_answer_clears_its_member_and_the_last_one_closes_the_check_at_once() {
         let mut s = UiScript::new().unwrap();
@@ -1751,10 +1530,7 @@ mod tests {
         assert!(s.take_ready_check_lines().is_empty());
     }
 
-    /// A "not ready" answer prints `RAID_MEMBER_NOT_READY` for that member the moment it arrives —
-    /// and clears their flag all the same, because the leader arm stores the constant 0 whatever
-    /// the byte says (`0x4ba40e`). A guid the roster does
-    /// not hold writes nothing.
+    /// The leader arm stores a constant 0 whatever the status byte (`0x4ba40e`).
     #[test]
     fn a_not_ready_answer_prints_its_line_and_still_clears_the_member() {
         let mut s = UiScript::new().unwrap();
@@ -1781,9 +1557,8 @@ mod tests {
         );
     }
 
-    /// An OFFLINE member who never answers does not hold the check open (`0x4ba4a7 test byte
-    /// [eax+0x18],dl`), but the summary that closes it still lists them: the worker walks the
-    /// flags with no online test (`0x4bb3a8`).
+    /// The close tests online (`0x4ba4a7 test byte [eax+0x18],dl`); the summary's walk does not
+    /// (`0x4bb3a8`).
     #[test]
     fn an_offline_member_never_blocks_the_close_but_is_still_listed() {
         let mut s = UiScript::new().unwrap();
@@ -1802,9 +1577,7 @@ mod tests {
         );
     }
 
-    /// The tick is leader-gated: a member's client arms the same 30 s on the open form and the
-    /// four conjuncts fail on the guid compare, every frame, forever — the deadline stays armed
-    /// (nothing on the member's side ever clears it) and nothing is ever printed.
+    /// A member's client arms the deadline, never clears it, and never prints.
     #[test]
     fn the_tick_is_inert_for_a_non_leader() {
         let mut s = UiScript::new().unwrap();
@@ -1818,8 +1591,6 @@ mod tests {
         assert_eq!(s.model_mut().ready_check.deadline, Some(130.0));
     }
 
-    /// `SMSG_GROUP_LIST`'s leg: a member who left took their pending flag with them, and a roster
-    /// scan that finds nobody pending force-closes the check.
     #[test]
     fn a_roster_change_with_nobody_left_pending_closes_the_check() {
         let mut s = UiScript::new().unwrap();
@@ -1827,7 +1598,6 @@ mod tests {
         s.set_party(party.clone());
         s.run("__benilla_now = 100 DoReadyCheck()").unwrap();
         s.ready_check_answered(0xA11CE, true);
-        // Bob leaves: the roster without him.
         let mut without_bob = party;
         without_bob.raid.retain(|m| m.guid != 0xB0B);
         without_bob.members.retain(|m| m.guid != 0xB0B);
@@ -1838,8 +1608,7 @@ mod tests {
         );
     }
 
-    /// A plain party has no raid roster, so `DoReadyCheck` flags nobody — and the leader's own
-    /// echo of the open form, taking the response-collection arm, closes it on the spot.
+    /// A party has no raid roster, so `DoReadyCheck` flags nobody.
     #[test]
     fn the_leaders_own_echo_closes_an_empty_check_at_once() {
         let mut s = UiScript::new().unwrap();
@@ -1854,8 +1623,7 @@ mod tests {
         );
     }
 
-    /// The two keys are read raw off `_G` with an empty-string default — a missing GlobalStrings
-    /// prints an empty line and never raises.
+    /// Both keys are read raw from `_G` with an empty default.
     #[test]
     fn a_missing_summary_string_prints_an_empty_line() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/pet.rs b/crates/benilla-ui/src/script/pet.rs
index 048695c8..3310515c 100644
--- a/crates/benilla-ui/src/script/pet.rs
+++ b/crates/benilla-ui/src/script/pet.rs
@@ -1,33 +1,16 @@
-//! The pet action bar seam (decision 0982) — the eight bindings `PetActionBarFrame.lua` consumes
-//! (`GetPetActionInfo`/`GetPetActionsUsable`/`GetPetActionCooldown`/`PetHasActionBar`/
-//! `CastPetAction`/`TogglePetAutocast`/`IsPetAttackActive`/`PetStopAttack`) over an app-pushed
-//! slot snapshot, in [`super::shapeshift`]'s two-way shape: the app resolves everything (which
-//! slot is a command, a reaction or a spell; its icon, name, checked and autocast bits; its
-//! cooldown) and pushes it ([`super::UiScript::set_pet_actions`]); the engine drains the click
-//! intents ([`super::UiScript::take_pet_actions`] and kin) back out.
-//!
-//! **The engine holds no pet knowledge**: a slot here is "a name, a subtext, a texture, four bits
-//! and a cooldown triple". In particular it does not know that a token slot's `name`/`texture` are
-//! *the names of globals* rather than values — that convention belongs to the reference's own
-//! `GetPetActionInfo` and is reproduced faithfully by the app, which sets `is_token` and lets the
-//! Lua do the `getglobal` (the shipped `PetActionBarFrame.lua:98-104` fork).
-//!
-//! Return conventions are the 1.12 API's own, matching [`super::action`]: 1/nil booleans, and the
-//! cooldown as `(start_s on the GetTime clock, duration_s, enable)` with the same
-//! elapsed-goes-cold rule `GetActionCooldown` uses.
-//!
-//! Two later families joined the bar's eight through the same two-way seam, because they are about
-//! the same unit and move on the same push: the **hunter stat block** ([`PetStats`], decision 1005)
-//! that the pet paper doll and the happiness icon read, and the **right-click menu**
-//! (`PetCanBeAbandoned`/`PetCanBeRenamed`/`PetAbandon`/`PetDismiss`/`PetRename`, decision 1066).
+//! The pet bindings: the action bar `PetActionBarFrame.lua` drives, the stat block the pet frames
+//! read, and the pet menu's predicates and verbs. The app resolves every slot and pushes it
+//! ([`super::UiScript::set_pet_actions`]); presses queue back out for the app to send. A token
+//! slot's name and texture are the names of globals, which the stock Lua resolves
+//! (`PetActionBarFrame.lua:98-104`). Booleans are 1/nil and cooldowns go cold once elapsed, as in
+//! [`super::action`].
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-// The slot-word bytes the one-shot orders synthesize — the same values
-// `benilla_protocol::messages::pet` names for the wire (the engine stays protocol-free, 0068 §3,
-// so they are restated here rather than imported): the type byte, then the command / reaction.
+// The slot-word values the one-shot orders synthesize, restated from
+// `benilla_protocol::messages::pet` because this crate does not depend on the protocol.
 const PET_ACT_COMMAND: u8 = 0x07;
 const PET_ACT_REACTION: u8 = 0x06;
 const PET_COMMAND_STAY: u32 = 0;
@@ -37,184 +20,110 @@ const PET_REACT_PASSIVE: u32 = 0;
 const PET_REACT_DEFENSIVE: u32 = 1;
 const PET_REACT_AGGRESSIVE: u32 = 2;
 
-/// A synthesized slot word: the type byte in the top byte, the action in the low bits — the
-/// server's own packing (`PetActionEntry`).
+/// A slot word as the server packs it: the type in the top byte, the action in the low bits.
 const fn order(kind: u8, action: u32) -> u32 {
     (kind as u32) << 24 | action
 }
 
-/// One pet bar slot, fully resolved by the app before pushing.
+/// One pet bar slot, resolved by the app.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct PetActionView {
-    /// `GetPetActionInfo`'s first return, and the slot's OCCUPANCY test — `None` hides the button
-    /// (`PetActionBarFrame.lua:122-128`). For a spell slot this is the spell's name; for a token
-    /// slot it is **the name of a global** (`"PET_ACTION_ATTACK"`), which the Lua resolves.
+    /// `GetPetActionInfo`'s first return and the occupancy test: `None` hides the button
+    /// (`PetActionBarFrame.lua:122-128`). The spell's name, or for a token the name of a global.
     pub name: Option<String>,
-    /// The second return — the spell's rank line, or `None` for a token.
+    /// The second return: the spell's rank line, `None` for a token.
     pub subtext: Option<String>,
-    /// The third return: an icon path for a spell, **the name of a global**
-    /// (`"PET_ATTACK_TEXTURE"`) for a token. `None` leaves the button art empty and swaps its
-    /// NormalTexture to the unfilled `UI-Quickslot`.
+    /// The third return: an icon path, or for a token the name of a global.
     pub texture: Option<String>,
-    /// Is this a command/reaction token (so `name`/`texture` are global names)?
+    /// A command or reaction token, whose `name` and `texture` are global names.
     pub is_token: bool,
-    /// The slot's spell, when it has one — what `GameTooltip:SetPetAction` renders. `None` for a
-    /// token and for an empty slot. Not a `GetPetActionInfo` return: the reference's tooltip
-    /// channel reaches the pet spellbook itself, and this is that reach.
+    /// The slot's spell, for `GameTooltip:SetPetAction`; not a `GetPetActionInfo` return.
     pub spell_id: Option<u32>,
     /// The checked ring.
     pub active: bool,
-    /// This slot CAN autocast — the static `UI-AutoCastableOverlay` ring.
+    /// The slot can autocast: the static `UI-AutoCastableOverlay` ring.
     pub autocast_allowed: bool,
-    /// …and it currently does — the sparkle trail.
+    /// Autocast is on: the sparkle trail.
     pub autocast_enabled: bool,
-    /// Whether a left click on this slot means "call the pet off" rather than "do this"
-    /// (`IsPetAttackActive`, the Attack button's second press).
+    /// `IsPetAttackActive`: a left click calls the pet off instead of running the slot.
     pub attack_active: bool,
-    /// `(start_ms on the GetTime clock, duration_ms, enabled)` — [`super::action::ActionState`]'s
-    /// exact shape; `None` = no cooldown.
+    /// `(start_ms on the GetTime clock, duration_ms, enabled)`, as [`super::action::ActionState`].
     pub cooldown: Option<(i64, u32, bool)>,
-    /// **The slot's packed word, verbatim** — the one place this seam's "the engine holds no pet
-    /// knowledge" rule bends, and deliberately (decision 1010).
-    ///
-    /// The drag ([`super::cursor::pet`]) is word arithmetic in the reference and cannot be
-    /// anything else: `0x4bc9a0` compares occupants under `& 0x3FFFFFFF`, tests a candidate's low
-    /// 16 bits, and **writes the source word through unchanged** — `0x4bce00` forwards the cursor's
-    /// payload dword without reading a field of it, and the payload itself is only ever a verbatim
-    /// copy of a word that already existed in a slot. There is no drop-time encoding to model, so
-    /// re-deriving a word from `(kind, action, bits)` at the engine boundary would be inventing one.
-    ///
-    /// `0` is the empty slot, which is also the reference's own test (the zero dword).
+    /// The slot's packed word, verbatim, for the drag ([`super::cursor::pet`]): the reference
+    /// compares occupants under `& 0x3FFFFFFF` and writes the source word through unchanged
+    /// (`0x4bc9a0`, `0x4bce00`). `0` is the empty slot.
     pub packed: u32,
-    /// `Attributes & 0x40` (`SPELL_ATTR_PASSIVE`) for a spell slot — the drop core's one source
-    /// filter (`0x4bc9f8`–`0x4bca2e`: a type-1 source whose `SpellRec+0x18 & 0x40` is set is
-    /// refused, silently). False for a token and for an empty slot.
+    /// `SPELL_ATTR_PASSIVE` (`Attributes & 0x40`) on a spell slot: the drop silently refuses a
+    /// passive source (`0x4bc9f8`-`0x4bca2e`).
     pub passive: bool,
 }
 
-/// [`PetActionView`] as stored: the cooldown converted to the `GetTime` clock at push time (the
-/// [`super::shapeshift::StoredShapeshiftForm`] pattern).
+/// [`PetActionView`] as stored, its cooldown converted to `GetTime` seconds at push time.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub(crate) struct StoredPetAction {
     pub(crate) view: PetActionView,
-    /// `(start_s, duration_s, enabled)` in `GetTime` seconds; `None` = no cooldown.
     pub(crate) cooldown: Option<(f64, f64, bool)>,
 }
 
-/// The hunter-pet stat block behind `GetPetHappiness`/`GetPetLoyalty`/`GetPetTrainingPoints`/
-/// `GetPetExperience` and `HasPetUI`'s second return (`0x4be670`; decision 1005), plus the two
-/// **family**-derived answers `UnitCreatureFamily("pet")` and `GetPetFoodTypes()` (decision 1062).
-///
-/// **The four stat bindings share one gate** — `0x6116e0(pet)`, "is this a hunter's pet" — which is
-/// why they share one pushed struct: a warlock's imp resolves perfectly well and still answers
-/// nothing, because happiness, loyalty and training points are hunter machinery.
-///
-/// **The two family fields sit on OPPOSITE sides of that gate.**
-/// [`Self::family`] is outside it — `UnitCreatureFamily 0x51a310` has no class test, so a warlock
-/// minion shows "Imp" and gating it would blank a line the reference fills. [`Self::food_types`] is
-/// inside it — `GetPetFoodTypes 0x4bea10` shares `0x6116e0` with the four stats.
-///
-/// **The stat failure conventions differ, and the difference is the API.** `GetPetLoyalty` fails to
-/// **nil**; the two pairs fail to **`(0, 0)` — numbers, not nil**; `GetPetHappiness` fails to
-/// **`(nil, 100.0, 0.0)`**, nil in the first slot and numbers in the other two. `PetFrame.lua`
-/// hides the happiness icon on `not happiness` alone, so collapsing any of these into a uniform
-/// nil-everything would hide the frame in cases the reference shows it.
+/// The pet stat block: the four hunter stat bindings and `HasPetUI`'s second return
+/// (`0x4be670`), plus the family word, icon and diet. The stats share one hunter-pet gate
+/// (`0x6116e0`) and fail their own ways: loyalty to nil, the pairs to `(0, 0)`, happiness to
+/// `(nil, 100.0, 0.0)`. The family word has no gate (`0x51a310`); the diet shares the stats'.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct PetStats {
-    /// `HasPetUI`'s second return — the hunter-pet discriminator. False makes every field below
-    /// answer its own failure convention regardless of what is in it.
+    /// `HasPetUI`'s second return; false makes every gated binding answer its failure form.
     pub hunter_pet: bool,
-    /// `GetPetHappiness`'s first return: the **pre-bucketed** `0..=3`. `None` is the gate
-    /// failure's nil; `Some(0)` is a real answer and must stay distinguishable from it.
+    /// `GetPetHappiness`'s first return, bucketed `0..=3` by the client; `Some(0)` is not nil.
     pub happiness: Option<u32>,
-    /// Return 2 — the damage percentage, already scaled by the client's own `100.0f`.
+    /// Return 2: the damage percentage, already scaled by 100.
     pub damage_percentage: f32,
-    /// Return 3 — the loyalty rate, unscaled and possibly negative.
+    /// Return 3: the loyalty rate, unscaled and possibly negative.
     pub loyalty_rate: f32,
-    /// `GetPetLoyalty`'s single return — the `PetLoyalty.dbc` name, verbatim including the shipped
-    /// `"(Loyalty Level N) "` prefix. `None` = nil (level 0, or off the table).
+    /// `GetPetLoyalty`: the `PetLoyalty.dbc` name verbatim, `"(Loyalty Level N) "` prefix included.
     pub loyalty: Option<String>,
-    /// `GetPetTrainingPoints` → `(totalPoints, spent)`, high word first.
+    /// `GetPetTrainingPoints`: `(totalPoints, spent)`, high word first.
     pub training_points: (u16, u16),
-    /// `GetPetExperience` → `(currXP, nextXP)`.
+    /// `GetPetExperience`: `(currXP, nextXP)`.
     pub experience: (u32, u32),
-    /// `UnitCreatureFamily("pet")` — the localized `CreatureFamily.dbc` word ("Imp", "Wind
-    /// Serpent"), read from the cached creature-query record (`0x51a310`: `[[unit+0xb30]+0x1c]` →
-    /// column `8 + locale`). Exactly **one** return on every path.
-    ///
-    /// `None` is the binding's **nil**, and the reference reaches it four ways that all mean "no
-    /// word to print": no cached record yet (the creature query is still in flight), family id `0`,
-    /// an id past the table, and — the one nobody guesses — **a null row in the middle of the id
-    /// space**: 10/13/14/18/22 have no row in the shipped file, so this is a lookup miss, never a
-    /// bounds check. The page guards its whole level-line `SetText` on this
-    /// (ref `PetPaperDollFrame.lua:68-70`), so nil renders no line rather than a half one.
+    /// `UnitCreatureFamily("pet")`: the localized `CreatureFamily.dbc` word off the cached creature
+    /// record (`0x51a310`). `None` is nil: no record yet, id 0, or an id with no row (10, 13, 14,
+    /// 18 and 22 have none). `PetPaperDollFrame.lua:68-70` guards its level line on it.
     pub family: Option<String>,
-    /// `GetPetIcon()` — the pet's icon path, from the family row's own `CreatureFamily.dbc` icon
-    /// column (`Interface\\Icons\\Ability_Hunter_Pet_<Family>` for all 22 shipped families). A pet
-    /// has no item behind it, so this column is the only icon there is. `None` = nil, on the same
-    /// four lookup-miss paths as [`Self::family`], which is why it sits beside it.
-    ///
-    /// **Outside the hunter gate, like [`Self::family`] and unlike [`Self::food_types`] — and that
-    /// placement is INFERRED** (decision 1676). `GetPetIcon 0x4beb10` is registered adjacent to
-    /// both in the same table and has not been read.
-    /// It is grouped with the family word because it is a pure family-row lookup like that one,
-    /// where the diet's gate is shared with the four *stat* bindings. The choice is unobservable
-    /// in the reference's own call sites — every one of them (`PetStable.lua:51`, `161-162`) sits
-    /// downstream of the window's own warlock early-return — so a warlock can never reach it there
-    /// either way; only an addon could tell the difference.
+    /// `GetPetIcon()`: the family row's `CreatureFamily.dbc` icon, `None` on the family word's
+    /// misses. Ungated like the family word; whether the reference gates it (`0x4beb10`) is
+    /// untraced, and no warlock reaches its stock callers (`PetStable.lua:51`, `161-162`).
     pub icon: Option<String>,
-    /// `GetPetFoodTypes()` — the localized diet names the family's pet-food mask selects, in
-    /// **record order** (`0x4bea10`: bit `1 << (recordID - 1)` against `CreatureFamily` column 7,
-    /// the name from `ItemPetFood` column `1 + locale`). Varargs; the client returns the count and
-    /// **never a nil**, so empty is zero values rather than one nil.
-    ///
-    /// **Empty is a real answer**, and it has two independent causes: a family whose mask is `0`
-    /// (every warlock minion), and the binding's own `0x6116e0` gate — owner-is-me *and* the local
-    /// player is a Hunter — which a charmed beast under a non-hunter fails even though its family
-    /// row has a mask. The app applies that gate; this field is what it produced.
+    /// `GetPetFoodTypes()`: the diet names the family's food mask selects, in record order
+    /// (`0x4bea10`: bit `1 << (id - 1)` of `CreatureFamily` column 7, names from `ItemPetFood`).
+    /// Empty for a zero mask (every warlock minion) or a failed hunter gate, which the app applies.
     pub food_types: Vec<String>,
 }
 
-/// The pet bar's pushed state: the slots plus the two bar-wide bits the reference exposes
-/// separately from them.
+/// The pushed pet state: the bar's slots and bar-wide bits, the stat block, the menu predicates.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub(crate) struct PetBarState {
-    /// `PetHasActionBar()` — is there a bar at all. Distinct from "the slot list is empty": a
-    /// possessed minion has a bar of pure commands, and a bar of ten empty slots is still a bar.
+    /// `PetHasActionBar()`: there is a bar, even one of ten empty slots.
     pub(crate) has_bar: bool,
-    /// `GetPetActionsUsable()` — false desaturates every icon on the bar at once.
+    /// `GetPetActionsUsable()`: false desaturates the whole bar.
     pub(crate) actions_usable: bool,
     pub(crate) slots: Vec<StoredPetAction>,
-    /// `HasPetUI`'s FIRST return — "there is a pet with a UI at all", which the reference derives
-    /// from the pet resolving plus its `UNIT_FIELD_PETNUMBER` being nonzero (`0x4be697`). Separate
-    /// from `has_bar`: the action bar's gate is the cached guid alone, with no pet-number test.
+    /// `HasPetUI`'s first return: a pet with a nonzero `UNIT_FIELD_PETNUMBER` (`0x4be697`). Not
+    /// `has_bar`, whose gate is the cached guid alone.
     pub(crate) has_ui: bool,
     pub(crate) stats: PetStats,
-    /// May the bar be **rearranged** — `PickupPetAction`'s own gate, and nobody else's
-    /// (`0x4be1c1`: `[[pet+0x110]+0xA3] & 1 == 0`, i.e. `UNIT_FLAG_POSSESSED` clear).
-    ///
-    /// A third bar-wide bit rather than a fold into `actions_usable`, because the reference is
-    /// deliberate about keeping them apart: possession is expressly **not** among the flags that
-    /// grey the bar (a possessed unit is exactly the case where the buttons must still work), and
-    /// the crowd-control flags that do grey it do **not** block a drag. Two gates, two questions.
-    ///
-    /// It sits before the cursor fork, so it blocks the DROP as well as the pick-up.
+    /// `PickupPetAction`'s gate, `UNIT_FLAG_POSSESSED` clear (`0x4be1c1`), which blocks the drop
+    /// as well as the pick-up. Not `actions_usable`: possession does not grey the bar, and the
+    /// flags that grey it do not block a drag.
     pub(crate) pickup_allowed: bool,
-    /// `PetCanBeAbandoned()` — **the pet right-click menu's whole fork** (decision 1066).
-    ///
-    /// Three of the PET menu's four rows show only when this is true (paperdoll, rename, abandon)
-    /// and the fourth — Dismiss — shows only when it is *false* (`UnitPopup.lua:402-417`). So it is
-    /// not "am I allowed to abandon"; it is "is this a pet I keep rather than a summon I called",
-    /// and it is what makes one menu read *Abandon* on a hunter's pet and *Dismiss* on a demon.
+    /// `PetCanBeAbandoned()`: a kept pet rather than a summon. It forks the pet menu: paperdoll,
+    /// rename and abandon show when true, dismiss only when false (`UnitPopup.lua:402-417`).
     pub(crate) can_be_abandoned: bool,
-    /// `PetCanBeRenamed()` — an independent predicate, ANDed with the one above for the rename row
-    /// alone. One-shot server-side: a hunter pet carries it only until its first rename.
+    /// `PetCanBeRenamed()`, ANDed with the above for the rename row; set until the first rename.
     pub(crate) can_be_renamed: bool,
 }
 
 impl super::UiScript {
-    /// Push the whole pet bar, replacing whatever was there. A bare setter — firing
-    /// `PET_BAR_UPDATE` is the app's diff-and-fire job, mirroring `set_shapeshift_forms`.
+    /// Push the whole pet bar; the app diffs and fires `PET_BAR_UPDATE`.
     pub fn set_pet_actions(
         &mut self,
         has_bar: bool,
@@ -222,10 +131,7 @@ impl super::UiScript {
         pickup_allowed: bool,
         slots: Vec<PetActionView>,
     ) {
-        // Field-by-field, never `pet_bar = PetBarState { .. }`: the struct also holds state that
-        // moves on OTHER clocks (the stat block, the menu predicates), and rebuilding it wholesale
-        // meant every one of those had to be hand-carried across this assignment or be silently
-        // reset once a frame. Assigning what this setter owns cannot forget them.
+        // Field by field: the stat block and the menu predicates beside them move on other clocks.
         let bar = &mut self.model_mut().pet_bar;
         bar.has_bar = has_bar;
         bar.actions_usable = actions_usable;
@@ -233,8 +139,7 @@ impl super::UiScript {
         bar.slots = slots
             .into_iter()
             .map(|view| {
-                // The cooldown arrives with its absolute start already on the `GetTime` clock
-                // (ms) — storing is a pure unit conversion, `set_shapeshift_forms`' seam.
+                // The start is already on the `GetTime` clock, in ms.
                 let cooldown = view.cooldown.map(|(start_ms, duration_ms, enabled)| {
                     (
                         start_ms as f64 / 1000.0,
@@ -247,28 +152,22 @@ impl super::UiScript {
             .collect();
     }
 
-    /// Push the hunter-pet stat block ([`PetStats`]) — the four paper-doll bindings plus
-    /// `HasPetUI`. Separate from [`Self::set_pet_actions`] because it changes on a different clock:
-    /// `SMSG_PET_SPELLS` replaces the bar wholesale, but happiness moves every few seconds off a
-    /// plain descriptor field, so tying the two together would make the bar's diff-and-fire churn
-    /// on a number no button draws.
+    /// Push the stat block and `HasPetUI`'s first return, which move on descriptor updates rather
+    /// than with the bar.
     pub fn set_pet_stats(&mut self, has_ui: bool, stats: PetStats) {
         let bar = &mut self.model_mut().pet_bar;
         bar.has_ui = has_ui;
         bar.stats = stats;
     }
 
-    /// Push the right-click menu's two predicates (decision 1066) — a third clock again, the pet's
-    /// own `UNIT_FIELD_FLAGS`, which the rename's one-shot bit moves independently of both.
+    /// Push the menu's two predicates, which move with the pet's `UNIT_FIELD_FLAGS`.
     pub fn set_pet_menu(&mut self, can_be_abandoned: bool, can_be_renamed: bool) {
         let bar = &mut self.model_mut().pet_bar;
         bar.can_be_abandoned = can_be_abandoned;
         bar.can_be_renamed = can_be_renamed;
     }
 
-    /// Drain the 1-based slot indices `CastPetAction` queued since the last call. What each index
-    /// *means* on the wire (a command, a reaction, a cast) is the app's to decide at drain time
-    /// from the slot it still owns.
+    /// Drain the 1-based slots `CastPetAction` queued; the app decides what each one sends.
     pub fn take_pet_actions(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().pet_actions_pressed)
     }
@@ -278,34 +177,29 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().pet_autocast_toggles)
     }
 
-    /// Drain the `PetStopAttack()` calls queued (a count — the verb carries no argument).
+    /// Drain the count of `PetStopAttack()` calls.
     pub fn take_pet_stop_attacks(&mut self) -> u32 {
         std::mem::replace(&mut self.model_mut().pet_stop_attacks, 0)
     }
 
-    /// Drain the pet one-shot orders (`PetAttack` & co.), each a packed slot word (1958).
+    /// Drain the one-shot orders (`PetAttack` and the rest), each a packed slot word.
     pub fn take_pet_orders(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().pet_orders)
     }
 
-    /// `HasFullControl`'s flag, from the host's control edge (`ui_unit::feed_player_control`).
+    /// Set the flag `HasFullControl` answers.
     pub fn set_player_control(&mut self, in_control: bool) {
         self.model_mut().player_control = in_control;
     }
 
-    /// Drain the pet bar writes the drag queued (decision 1010) — **one `Vec` per
-    /// `CMSG_PET_SET_ACTION`**, each of one or two `(0-based position, packed word)` pairs.
-    ///
-    /// Already-applied on the engine's side: the app's job is to mirror each pair into its own
-    /// authoritative ten words and put the batch on the wire whole. Flattening the batches would
-    /// break the server's body-size fork between the one- and two-entry forms.
+    /// Drain the drag's bar writes, already applied here: one `Vec` per `CMSG_PET_SET_ACTION` of
+    /// one or two `(0-based position, packed word)` pairs. Send each whole: the server tells the
+    /// two forms apart by body size.
     pub fn take_pet_set_actions(&mut self) -> Vec<Vec<(u32, u32)>> {
         std::mem::take(&mut self.model_mut().pet_set_actions)
     }
 
-    /// Drain the `PetAbandon()` and `PetDismiss()` calls queued, as `(abandons, dismisses)` —
-    /// counts, since neither verb carries an argument. Kept apart for the reason on the model's
-    /// fields: two bindings, not one, whatever they end up sharing on the wire.
+    /// Drain the `PetAbandon()` and `PetDismiss()` call counts, as `(abandons, dismisses)`.
     pub fn take_pet_gives_up(&mut self) -> (u32, u32) {
         let m = &mut *self.model_mut();
         (
@@ -320,7 +214,7 @@ impl super::UiScript {
     }
 }
 
-/// The 1-based button index → stored slot, the reference's own indexing.
+/// The stored slot at a 1-based button index.
 fn slot_at(model: &Model, i: u32) -> Option<&StoredPetAction> {
     usize::try_from(i.checked_sub(1)?)
         .ok()
@@ -333,7 +227,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 
     let flag = |b: bool| if b { Value::Integer(1) } else { Value::Nil };
 
-    // PetHasActionBar() → 1/nil. The bar frame's whole show/hide gate.
     g.set(
         "PetHasActionBar",
         lua.create_function(move |lua, ()| {
@@ -342,7 +235,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPetActionsUsable() → 1/nil — one answer for the whole bar (the SetDesaturation sweep).
     g.set(
         "GetPetActionsUsable",
         lua.create_function(move |lua, ()| {
@@ -351,9 +243,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPetActionInfo(i) → name, subtext, texture, isToken, isActive, autoCastAllowed,
-    // autoCastEnabled. An out-of-range index answers a single nil, which the Lua's `if (name)`
-    // occupancy test reads exactly as an empty slot (the spellbook bindings' shape).
+    // An out-of-range index answers a single nil, which the Lua reads as an empty slot.
     g.set(
         "GetPetActionInfo",
         lua.create_function(move |lua, i: u32| {
@@ -378,9 +268,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPetActionCooldown(i) → start, duration, enable — GetActionCooldown's triple and its
-    // elapsed-goes-cold rule (an elapsed/absent cooldown answers (0, 0, 1) so a re-feed never
-    // replays the sweep).
+    // An elapsed or absent cooldown answers (0, 0, 1), so a re-feed never replays the sweep.
     g.set(
         "GetPetActionCooldown",
         lua.create_function(|lua, i: u32| {
@@ -395,14 +283,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsPetAttackActive(i) → a BOOLEAN — the left-click fork: true means the press should call
-    // the pet OFF (`PetStopAttack`) instead of running the slot.
-    //
-    // The odd one out of this file's returns, and deliberately so: it is the single pet binding
-    // that pushes a real Lua boolean (`0x6f39f0`) rather than the 1/nil the rest use, so it
-    // answers `false`, never nil, even out of range. Consumers only ever test it for truth, so
-    // the difference is invisible in use — but a seam that quietly upgraded it to the house
-    // convention would be lying about the API.
+    // The one pet binding that answers a real boolean (`0x6f39f0`), `false` even out of range.
     g.set(
         "IsPetAttackActive",
         lua.create_function(move |lua, i: u32| {
@@ -411,9 +292,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CastPetAction(i) — queue the press. An EMPTY slot queues nothing: the reference's bar hides
-    // an unnamed button, so a press on one can only come from the show-grid state, where it must
-    // be inert.
+    // An empty slot, whose button shows only under show-grid, queues nothing; the reference sends
+    // its zero word (`0x4bd230` falls to the send at `0x4bd444`), which vmangos ignores
+    // (`PetHandler.cpp:178`).
     g.set(
         "CastPetAction",
         lua.create_function(|lua, i: u32| {
@@ -425,8 +306,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // TogglePetAutocast(i) — queue the right-click. Only a slot that CAN autocast queues: the
-    // wire verb names a spell id, and a command token has none.
+    // Only a slot that can autocast queues: the wire verb names a spell, and a token has none.
     g.set(
         "TogglePetAutocast",
         lua.create_function(|lua, i: u32| {
@@ -438,9 +318,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // HasPetUI() → hasUI, isHunterPet — ALWAYS exactly two returns (`EAX=2` on every path of
-    // `0x4be670`), with `(nil, nil)` when there is no pet with a UI. The second return is the
-    // gate every stat binding below shares.
+    // Two returns on every path (`0x4be670`), `(nil, nil)` with no pet UI.
     g.set(
         "HasPetUI",
         lua.create_function(move |lua, ()| {
@@ -450,13 +328,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPetHappiness() → happiness, damagePercentage, loyaltyRate.
-    //
-    // The client thresholds; Lua does not. Return 1 is a PRE-BUCKETED 0..3 read off
-    // PetPersonality.dbc's three columns, and `0` is a real bucket that answers the NUMBER 0 —
-    // `PetFrame.lua` hides the icon on `not happiness`, and a 0 leaves it showing with whatever
-    // texcoords it had. Only the gate failure is nil, and even then returns 2 and 3 are the
-    // numbers (100.0, 0.0), never nil.
+    // The client buckets return 1 off `PetPersonality.dbc` (`0x4be900`), and bucket 0 is the
+    // number 0; only the gate failure is nil, and even then returns 2 and 3 are `(100.0, 0.0)`.
     g.set(
         "GetPetHappiness",
         lua.create_function(move |lua, ()| {
@@ -479,8 +352,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPetLoyalty() → the localized level name, or NIL. The one stat binding whose failure is
-    // nil rather than a number — level 0 (no loyalty yet) included.
+    // The one stat binding that fails to nil, level 0 included.
     g.set(
         "GetPetLoyalty",
         lua.create_function(move |lua, ()| {
@@ -493,8 +365,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPetTrainingPoints() → totalPoints, spent — the two halves of one packed dword, HIGH word
-    // first. Numbers on every path: a gate failure is (0, 0), not nil.
+    // The high then low word of one packed dword; a gate failure is (0, 0), not nil.
     g.set(
         "GetPetTrainingPoints",
         lua.create_function(move |lua, ()| {
@@ -509,8 +380,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPetExperience() → currXP, nextXP. Numbers on every path, like the pair above; the client
-    // converts both `fild qword` off a zero-extended dword, so neither can arrive negative.
+    // Numbers on every path; the client reads both unsigned, so neither is negative.
     g.set(
         "GetPetExperience",
         lua.create_function(move |lua, ()| {
@@ -521,25 +391,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitCreatureFamily(unit) → the localized family word, or NIL. Exactly ONE return on every
-    // path (`0x51a310`) — decision 1062.
-    //
-    // **Scoped to the `"pet"` token, and that narrowing is stated rather than hidden.** The real
-    // binding resolves any unit and reads `[[unit+0xb30]+0x1c]` off its cached creature-query
-    // record, so `UnitCreatureFamily("target")` on a wild boar answers "Boar" there and nil here —
-    // INTERIM, exactly the shape `UnitDefense`'s non-player answer took in 1057. The pet page is
-    // the only consumer in the shipped FrameXML, and a pet is the one unit whose record we cannot
-    // reach through `guid::entry` (its guid slot holds a pet number, not a template id), so the pet
-    // feed resolves it explicitly and the other tokens wait for a second consumer — at which point
-    // this moves onto `UnitState` beside `creature_type_name`.
-    //
-    // Note there is NO class gate here: a warlock's imp answers "Imp". That is the shape, and it
-    // is what makes the family word and `GetPetFoodTypes` below behave differently for the same
-    // pet.
-    //
-    // All four of the reference's nil paths arrive as one pushed `None` — no cached record, id 0,
-    // id past the table, and a null row (ids 10/13/14/18/22 are absent from the shipped file). A
-    // missing or absent token is nil too, through the same match.
+    // One return on every path, with no class gate (`0x51a310`). Answers the `"pet"` token only:
+    // the reference resolves any unit off its cached creature record (`[[unit+0xb30]+0x1c]`), so
+    // a wild boar's `"target"` answers "Boar" there and nil here. The pet page is the only stock
+    // caller.
     g.set(
         "UnitCreatureFamily",
         lua.create_function(move |lua, token: Option<String>| {
@@ -554,10 +409,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPetIcon() → the pet's icon path, or NIL. One return. The stable window reads it both as a
-    // predicate ("is there a current pet?", `PetStable.lua:51`) and as the texture itself (`161`),
-    // so the nil must be a real nil rather than an empty string — `SetItemButtonTexture` would
-    // happily take "" and a path resolving to nothing draws WHITE (decision 1046).
+    // A real nil, never "": the stable reads it as a predicate and as a texture
+    // (`PetStable.lua:51`, `161-162`), and an empty path would draw white.
     g.set(
         "GetPetIcon",
         lua.create_function(move |lua, ()| {
@@ -569,16 +422,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPetFoodTypes() → the diet names as VARARGS, one Lua return per food type, in record
-    // order — the shape `BuildListString(GetPetFoodTypes())` needs (ref
-    // `PetPaperDollFrame.xml:269`). `0x4bea10` returns the pushed COUNT and never a nil, so the
-    // empty case is zero values.
-    //
-    // An empty diet returns NOTHING, not an empty string: the reference's `BuildListString` then
-    // reads `arg[1]` as nil and returns nil, which is the behaviour a single empty-string return
-    // would silently break. It is reachable two ways, both real — a family whose mask is 0 (every
-    // warlock minion), and the binding's own `0x6116e0` hunter gate, which the app applies before
-    // filling this list.
+    // One return per diet and never a nil (`0x4bea10`): an empty diet is zero values, for which
+    // `BuildListString` answers nil (`PetPaperDollFrame.xml:269`).
     g.set(
         "GetPetFoodTypes",
         lua.create_function(move |lua, ()| {
@@ -594,16 +439,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // PetStopAttack() — queue the call-off. No argument: the wire carries only the pet's guid.
-    // The six one-shot orders (`0x4be450`…`0x4be4a0`): each writes the literal slot word the
-    // bar's own reaction or command slot carries — `0x06000000`/1/2 PASSIVE/DEFENSIVE/AGGRESSIVE,
-    // `0x07000000`/1/2 WAIT/FOLLOW/ATTACK — and re-enters `0x4bd1d0`, the identical call a
-    // `CastPetAction` press
-    // makes, PetAttack with the current selection's guid as a bar ATTACK click would. No
-    // arguments, no returns; the no-pet gate is silent, so a session without a pet bar has
-    // nothing to order and drops it, as the bar's own press would (1958; §10.9 confirmed the
-    // reading, including that a target-less PetAttack raises the bar press's own `ERR_ATTACK_*`
-    // after its auto-acquire — that leg is the drain's, shared with the press).
+    // The six one-shot orders (`0x4be450`..`0x4be4a0`) each write the slot word the bar's own
+    // reaction or command slot carries and re-enter `0x4bd1d0`, as a `CastPetAction` press does;
+    // PetAttack takes the current selection. With no pet bar the order is silently dropped.
     for (name, packed) in [
         ("PetPassiveMode", order(PET_ACT_REACTION, PET_REACT_PASSIVE)),
         (
@@ -639,12 +477,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ── The right-click menu (decision 1066) ─────────────────────────────────────────────────
-    // Two predicates that decide what the PET menu SHOWS, and three verbs it can pick. The
-    // predicates are 1/nil like the rest of this file, which is all `UnitPopup.lua` needs — every
-    // one of its four uses is a bare `not PetCanBeAbandoned()` or an AND of the two.
+    // ── The pet menu ─────────────────────────────────────────────────────────
 
-    // PetCanBeAbandoned() → 1/nil. Do not read this as "may I abandon": it forks the whole menu.
     g.set(
         "PetCanBeAbandoned",
         lua.create_function(move |lua, ()| {
@@ -653,7 +487,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // PetCanBeRenamed() → 1/nil. Independent of the above; the rename row wants both.
     g.set(
         "PetCanBeRenamed",
         lua.create_function(move |lua, ()| {
@@ -662,7 +495,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // PetAbandon() — the ABANDON_PET popup's OnAccept, i.e. the confirmed permanent one.
+    // The `ABANDON_PET` popup's OnAccept, after its confirm.
     g.set(
         "PetAbandon",
         lua.create_function(|lua, ()| {
@@ -672,8 +505,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // PetDismiss() — the menu row itself, with NO confirm in front of it (`UnitPopup.lua:590`
-    // calls it directly, unlike abandon). Nothing is lost when a summon is sent away.
+    // The menu row itself, with no confirm (`UnitPopup.lua:591`).
     g.set(
         "PetDismiss",
         lua.create_function(|lua, ()| {
@@ -683,14 +515,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // PetRename(name) — the PETRENAMECONFIRM popup's OnAccept, carrying the text the RENAME_PET
-    // edit box collected.
-    //
-    // The argument reaches `lua_tostring 0x6f3690`, which coerces a NUMBER via `0x6f7c80` —
-    // `mlua::String` accepts one the same way. What the reference does with the RESULT is the
-    // app's business and is queued for it rather than dropped here: an empty name raises
-    // `ERR_NULL_PETNAME` and an over-long one is truncated, both at the send. Only a missing or
-    // unconvertible argument dies here, because there is nothing to queue.
+    // A number coerces, as `lua_tostring` does (`0x6f3690` → `0x6f7c80`); an empty or over-long
+    // name is still queued, since the reference raises `ERR_NULL_PETNAME` or truncates at send.
     g.set(
         "PetRename",
         lua.create_function(|lua, name: Option<mlua::String>| {
@@ -712,9 +538,7 @@ mod tests {
     use super::{PetActionView, PetStats};
     use crate::script::UiScript;
 
-    /// A hunter's bar, cut down to the three slot classes that matter: the Attack command (a
-    /// token, currently attacking), Claw (a spell with autocast ON and a running cooldown), and an
-    /// empty middle slot.
+    /// Attack (a token, attacking), Claw (a spell, autocasting, cooling down), an empty slot.
     fn slots() -> Vec<PetActionView> {
         vec![
             PetActionView {
@@ -748,7 +572,6 @@ mod tests {
         assert_eq!(s.eval::<i64>("return PetHasActionBar()").unwrap(), 1);
         assert_eq!(s.eval::<i64>("return GetPetActionsUsable()").unwrap(), 1);
 
-        // The token slot returns GLOBAL NAMES, and says so with isToken.
         let (name, subtext, texture, is_token, active, allowed, enabled) = s
             .eval::<(
                 String,
@@ -781,7 +604,6 @@ mod tests {
             )
         );
 
-        // The spell slot returns a real name, a rank line and an icon PATH, and is not a token.
         assert!(s
             .eval::<bool>(
                 "local n, sub, tex, tok, act, allow, on = GetPetActionInfo(2) \
@@ -790,8 +612,7 @@ mod tests {
             )
             .unwrap());
 
-        // The empty slot exists (so it is not the out-of-range single nil) but has no name — the
-        // reference's own "hide this button" test.
+        // The empty slot has returns, unlike the out-of-range single nil, but no name.
         assert!(s
             .eval::<bool>("local n, _, tex = GetPetActionInfo(3) return n == nil and tex == nil")
             .unwrap());
@@ -825,9 +646,6 @@ mod tests {
         );
     }
 
-    /// The three intent queues, and the two gates that keep a meaningless intent off the wire: an
-    /// empty slot cannot be pressed, and a slot with no autocast cannot be toggled (its wire verb
-    /// names a spell id, which a command token has not got).
     #[test]
     fn intents_queue_and_the_meaningless_ones_are_dropped() {
         let mut s = UiScript::new().unwrap();
@@ -855,11 +673,6 @@ mod tests {
         assert_eq!(s.take_pet_stop_attacks(), 0, "drain empties");
     }
 
-    /// `IsPetAttackActive` is per-slot, and it is what turns the Attack button's second press into
-    /// a call-off — the reference's `PetActionButton_OnClick` fork.
-    ///
-    /// It answers a **boolean** on every path, including out of range — the one binding here that
-    /// does not use the 1/nil convention.
     #[test]
     fn attack_active_is_a_per_slot_boolean() {
         let mut s = UiScript::new().unwrap();
@@ -871,21 +684,17 @@ mod tests {
             .unwrap());
     }
 
-    /// The right-click menu's two predicates and three verbs (decision 1066).
-    ///
-    /// The predicate half is checked the way `UnitPopup.lua` actually reads them — as the four
-    /// row conditions — because that is the only thing they are for, and getting the Dismiss row's
-    /// **inverted** sense wrong would show a hunter both Abandon and Dismiss.
+    /// The predicates are checked the way `UnitPopup.lua`'s row conditions read them.
     #[test]
     fn the_menu_predicates_fork_the_rows_and_the_verbs_queue() {
         let mut s = UiScript::new().unwrap();
 
-        // No pet pushed: every row is off, which is what keeps a menu of dead rows from opening.
+        // No pet pushed: every row is off.
         assert!(s
             .eval::<bool>("return PetCanBeAbandoned() == nil and PetCanBeRenamed() == nil")
             .unwrap());
 
-        // A hunter's freshly tamed pet: abandon/rename/paperdoll show, dismiss hides.
+        // A hunter's freshly tamed pet.
         s.set_pet_menu(true, true);
         assert_eq!(s.eval::<i64>("return PetCanBeAbandoned()").unwrap(), 1);
         assert!(
@@ -895,24 +704,21 @@ mod tests {
         );
         assert!(!s.eval::<bool>("return not PetCanBeAbandoned()").unwrap());
 
-        // The same pet after one rename — the bit is one-shot, so only the rename row goes.
+        // The same pet after one rename.
         s.set_pet_menu(true, false);
         assert!(s.eval::<bool>("return PetCanBeAbandoned() ~= nil").unwrap());
         assert!(s.eval::<bool>("return PetCanBeRenamed() == nil").unwrap());
 
-        // A warlock's demon: the fork flips whole. Dismiss is the row that shows.
+        // A warlock's demon: only Dismiss shows.
         s.set_pet_menu(false, false);
         assert!(s.eval::<bool>("return not PetCanBeAbandoned()").unwrap());
 
-        // The verbs. Abandon and dismiss are counted apart; rename carries its text.
         assert_eq!(s.take_pet_gives_up(), (0, 0));
         s.run("PetAbandon() PetDismiss() PetDismiss()").unwrap();
         assert_eq!(s.take_pet_gives_up(), (1, 2));
         assert_eq!(s.take_pet_gives_up(), (0, 0), "drain empties");
 
-        // An empty name IS queued — the reference's empty check raises `ERR_NULL_PETNAME` at the
-        // send, so swallowing it here would swallow the error with it. A number coerces
-        // (`lua_tostring`); a missing argument has nothing to queue.
+        // An empty name is queued for the send's error, a number coerces, no argument queues none.
         s.run("PetRename(\"Bruce\") PetRename(\"\") PetRename(7) PetRename()")
             .unwrap();
         assert_eq!(
@@ -922,9 +728,6 @@ mod tests {
         assert!(s.take_pet_renames().is_empty(), "drain empties");
     }
 
-    /// A bar push must not wipe the state that rides other clocks — the trap the old wholesale
-    /// `pet_bar = PetBarState { .. }` assignment set, and the reason [`UiScript::set_pet_actions`]
-    /// assigns field by field.
     #[test]
     fn pushing_the_bar_leaves_the_stats_and_the_menu_alone() {
         let mut s = UiScript::new().unwrap();
@@ -946,8 +749,6 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetPetHappiness()").unwrap(), 3);
     }
 
-    /// A disabled bar still EXISTS — `PetHasActionBar` stays true while `GetPetActionsUsable`
-    /// goes false. The pair is what greys every icon without taking the bar off screen.
     #[test]
     fn a_disabled_bar_is_still_a_bar() {
         let mut s = UiScript::new().unwrap();
@@ -958,14 +759,7 @@ mod tests {
             .unwrap());
     }
 
-    /// `GetPetIcon` — one return, a real nil when there is no pet. The stable window reads it BOTH
-    /// as a predicate and as the texture it passes to `SetItemButtonTexture`, so an empty string
-    /// standing in for the nil would draw a white square rather than the empty-slot art
-    /// (decision 1046's law, decision 1676's consumer).
-    /// The six one-shot orders synthesize the bar's own slot words (1958): the three reactions
-    /// as type 6 with the react byte, the three commands as type 7 with the command byte — the
-    /// same words `CastPetAction` on those slots would send. Without a bar there is nothing to
-    /// order, and none is queued.
+    /// Reactions are type 6 and commands type 7, each with its state in the low byte.
     #[test]
     fn the_pet_one_shots_synthesize_the_bars_slot_words() {
         let mut s = UiScript::new().unwrap();
@@ -992,8 +786,6 @@ mod tests {
         assert!(s.take_pet_orders().is_empty(), "drained");
     }
 
-    /// `HasFullControl()` is the host's control flag — 1 at boot, nil while a possession or fear
-    /// holds the body, 1 again after (1958).
     #[test]
     fn has_full_control_follows_the_hosts_flag() {
         let mut s = UiScript::new().unwrap();
@@ -1015,7 +807,6 @@ mod tests {
             "Interface\\Icons\\Ability_Hunter_Pet_Boar"
         );
 
-        // Exactly one return — the reference assigns it straight into a single local.
         assert_eq!(s.arity("GetPetIcon()").unwrap(), 1);
     }
 
@@ -1041,8 +832,6 @@ mod tests {
         }
     }
 
-    /// The four stat bindings on a hunter's pet — arities and values, including the pair ORDER
-    /// (`total` before `spent`, `curr` before `next`), which is the half a swap makes invisible.
     #[test]
     fn a_hunters_pet_answers_every_stat_binding() {
         let mut s = UiScript::new().unwrap();
@@ -1070,13 +859,6 @@ mod tests {
             .unwrap());
     }
 
-    /// **The failure conventions are three different shapes and the API is those shapes.** A
-    /// warlock's imp has a pet UI and is not a hunter pet: loyalty goes nil, both pairs go to
-    /// `(0, 0)` as NUMBERS, and happiness goes `(nil, 100, 0)` — nil in the first slot only.
-    ///
-    /// Flattening any of these to nil-everything breaks a different consumer: `PetFrame.lua` hides
-    /// its happiness icon on `not happiness`, but `PetPaperDollFrame` does arithmetic on the pairs
-    /// and would error on a nil.
     #[test]
     fn a_non_hunter_pet_fails_three_different_ways() {
         let mut s = UiScript::new().unwrap();
@@ -1103,15 +885,11 @@ mod tests {
         assert!(s
             .eval::<bool>("local c, n = GetPetExperience() return c == 0 and n == 0")
             .unwrap());
-        // HasPetUI still reports the UI — it is the SECOND return that discriminates.
         assert!(s
             .eval::<bool>("local ui, hunter = HasPetUI() return ui == 1 and hunter == nil")
             .unwrap());
     }
 
-    /// **Bucket 0 is a number, not nil** (`GetPetHappiness 0x4be900`): the shipped `PetFrame.lua`
-    /// branches on 1/2/3 and hides only on `not happiness`, so a 0 must leave the icon up.
-    /// Collapsing it into the failure path hides a frame the reference shows.
     #[test]
     fn happiness_bucket_zero_is_not_the_failure_case() {
         let mut s = UiScript::new().unwrap();
@@ -1134,8 +912,6 @@ mod tests {
         );
     }
 
-    /// With no pet at all every binding takes its failure path and `HasPetUI` answers `(nil, nil)`
-    /// — two returns on every path, never zero.
     #[test]
     fn no_pet_still_answers_two_values_from_has_pet_ui() {
         let s = UiScript::new().unwrap();
@@ -1148,21 +924,15 @@ mod tests {
             .unwrap());
     }
 
-    /// **`UnitCreatureFamily`'s nil paths — all four of them** (decision 1062). The reference
-    /// guards its whole level-line `SetText` on this binding, so an accidental `""` in place of
-    /// nil would print a bare "Level 58 " with a trailing space instead of nothing at all.
     #[test]
     fn unit_creature_family_is_nil_on_every_absent_path() {
         let mut s = UiScript::new().unwrap();
-        // 1. No pet at all — nothing has ever been pushed.
+        // No pet pushed.
         assert!(s
             .eval::<bool>(r#"return UnitCreatureFamily("pet") == nil"#)
             .unwrap());
 
-        // 2. A pet whose template carries family 0, and 3. a pet whose creature query has not
-        //    answered yet. Both arrive here as the same pushed `None` (the app resolves which is
-        //    which); what matters at this seam is that a live pet with no family word is nil and
-        //    not an empty string.
+        // Family 0 and an unanswered creature query both arrive as `None`.
         s.set_pet_stats(
             true,
             PetStats {
@@ -1180,7 +950,7 @@ mod tests {
              and print a bare 'Level 58 ' with a trailing space"
         );
 
-        // 4. Any other token: the INTERIM narrowing, stated in the binding's own comment.
+        // With a family: `"pet"` answers it, any other token nil.
         s.set_pet_stats(true, hunter_stats());
         assert_eq!(
             s.eval::<String>(r#"return UnitCreatureFamily("pet")"#)
@@ -1196,13 +966,9 @@ mod tests {
         }
     }
 
-    /// `GetPetFoodTypes` returns **varargs**, one value per diet — the shape
-    /// `BuildListString(GetPetFoodTypes())` depends on. A single comma-joined string would read
-    /// identically in the tooltip and be wrong for every other caller.
     #[test]
     fn get_pet_food_types_returns_one_value_per_diet() {
         let mut s = UiScript::new().unwrap();
-        // No pet: ZERO returns, which is what makes the ref's `BuildListString` answer nil.
         assert_eq!(s.arity("GetPetFoodTypes()").unwrap(), 0);
 
         s.set_pet_stats(true, hunter_stats());
@@ -1218,8 +984,6 @@ mod tests {
             )
             .unwrap());
 
-        // An empty diet is a real answer (every warlock family ships a zero food mask) and is
-        // still zero returns, not one empty string.
         s.set_pet_stats(
             true,
             PetStats {
@@ -1230,12 +994,7 @@ mod tests {
         assert_eq!(s.arity("GetPetFoodTypes()").unwrap(), 0);
     }
 
-    /// The family **word** answers regardless of the hunter gate — `UnitCreatureFamily 0x51a310`
-    /// has no class test at all, so a warlock's minion shows "Imp" on the page's level line while
-    /// every hunter-gated binding beside it says nothing.
-    ///
-    /// (The **diet** is the other way round — it shares `0x6116e0` — but that gate is the app's to
-    /// apply, so at this seam it is simply an empty list. `ui_pet_stats` pins the gate itself.)
+    /// The diet's hunter gate is the app's to apply, so here a non-hunter's diet is just empty.
     #[test]
     fn the_family_word_answers_for_a_non_hunter_pet() {
         let mut s = UiScript::new().unwrap();
@@ -1253,7 +1012,6 @@ mod tests {
                 .unwrap(),
             "Imp"
         );
-        // …while every hunter-gated binding still says nothing.
         assert!(s.eval::<bool>("return GetPetLoyalty() == nil").unwrap());
         assert_eq!(s.arity("GetPetFoodTypes()").unwrap(), 0);
     }
diff --git a/crates/benilla-ui/src/script/petition.rs b/crates/benilla-ui/src/script/petition.rs
index ad6b01ca..03a8e0c6 100644
--- a/crates/benilla-ui/src/script/petition.rs
+++ b/crates/benilla-ui/src/script/petition.rs
@@ -1,141 +1,86 @@
-//! The guild-charter **Era API surface** — the guild registrar and the petition window
-//! (decision 1672, **re-derived against the byte law in 1678**).
-//!
-//! [`super::guild`] is *being* in a guild; this is *founding* one, which 1257 §2 deliberately left
-//! out and named as the next slice. Fifteen registered globals across two windows (the three tabard
-//! ones are the adjacent family and are not built), and the same shape as every other domain here:
-//! the app pushes a [`PetitionState`] snapshot ([`UiScript::set_petition`]) and the getters read
-//! that plain data; every verb queues a [`PetitionRequest`] the app drains
-//! ([`UiScript::take_petition_requests`]). No ECS or net reach from the engine (decision 0068 §3).
-//!
-//! Every contract below is byte-verified against the whole `PetitionInfo.cpp` TU (`0x84cfb8`).
-//! Where it corrected what this file first shipped, the correction is named on the binding.
-//!
-//! **The snapshot mirrors the module's own `.data` state, and that is why it looks split.** The
-//! real client keeps the signature list (`[0xbdce20]` + the `0x10`-stride signer array) and the
-//! cached `CGPetition` record (`[0xbdce28]`) as two independent things, because the bindings read
-//! them independently: `GetNumPetitionNames`/`GetPetitionNameInfo` answer off the *packet's* list
-//! while `GetPetitionInfo` answers off the *record*, and either can exist without the other. So
-//! [`PetitionState`] carries them separately rather than as one "is the window open" struct — a
-//! collapsed model cannot express `CanSignPetition`'s no-record leg below, and gets it wrong.
-//!
-//! **This client has no `lua_pushboolean`.** Every predicate is the number `1` or `nil`
-//! (`0x6f3810` / `0x6f37f0`), and a name the `NameCache` has not resolved is **`nil`**, not `""`.
-//!
-//! **`PETITION_SHOW` is deferred, which is what makes the partial states below unreachable in
-//! practice.** The event fires only when no signer name is still resolving *and* the record has
-//! arrived (`0x4f419b`-`0x4f41ad`), so the window never paints a blank title or a blank row. The
-//! deferral lives app-side in `crate::ui_petition`; the getters here still answer honestly at any
-//! moment, because an addon may call them whenever it likes.
+//! The guild-charter globals of the guild registrar and the petition window. The snapshot keeps
+//! the signer list (`[0xbdce20]`) and the cached `CGPetition` record (`[0xbdce28]`) apart, as the
+//! reference does, since the bindings read them independently. Predicates are `1` or nil (no
+//! `lua_pushboolean`: `0x6f3810`, `0x6f37f0`) and an unresolved name is nil. `PETITION_SHOW` waits
+//! for every signer name and the record (`0x4f419b`), a deferral `crate::ui_petition` owns.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// `GetPetitionInfo`'s first return when the record's `"charter"` bit is SET — `0x84cf8c`, selected
-/// by `0x4f43fb test BYTE PTR [edi+0x1110],0x1`. The literal the reference compares against
-/// (`PetitionFrame.lua:22`).
+/// `GetPetitionInfo`'s first return when the record's charter bit is set (`0x84cf8c`, selected at
+/// `0x4f43fb`): the literal `PetitionFrame.lua:21` compares against.
 pub const PETITION_TYPE_CHARTER: &str = "charter";
 
-/// …and when it is clear — `0x84b8f8`. **Reachable**, not dead: the bit is the record's own, so a
-/// server that sent a non-charter petition would land here, and `CanSignPetition`'s guild-membership
-/// and full-charter refusals are *both* gated on the same bit. 1.12 servers only ever send charters,
-/// which is why the reference's `else` arm merely writes the bare word.
+/// `GetPetitionInfo`'s first return when the charter bit is clear (`0x84b8f8`). 1.12 servers send
+/// only charters, but `CanSignPetition`'s guild and full-charter refusals test the same bit.
 pub const PETITION_TYPE_PETITION: &str = "petition";
 
-/// The cached `CGPetition` record, as [`GetPetitionInfo`] reads it — `[0xbdce28]`'s six fields.
-///
-/// `None` on [`PetitionState::record`] is the no-record leg, which is a real state with its own
-/// return tuple; see [`GetPetitionInfo`].
+/// The cached `CGPetition` record `[0xbdce28]`, as `GetPetitionInfo` reads it; `None` in
+/// [`PetitionState::record`] is the no-record leg.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct PetitionRecordView {
-    /// [`PETITION_TYPE_CHARTER`] or [`PETITION_TYPE_PETITION`] — the record's `+0x1110` bit 0.
+    /// [`PETITION_TYPE_CHARTER`] or [`PETITION_TYPE_PETITION`], from the record's `+0x1110` bit 0.
     pub petition_type: String,
-    /// The record's inline `char[0x100]` title (`+0x10`) — the proposed guild's name.
+    /// The proposed guild's name, the record's `char[0x100]` at `+0x10`.
     pub title: String,
-    /// The record's inline `char[0x1000]` body text (`+0x110`). Empty on every 1.12 server.
+    /// The record's `char[0x1000]` body at `+0x110`; empty on every 1.12 server.
     pub body_text: String,
-    /// The record's `+0x1118`, pushed as a **signed** i32 (`fild DWORD`, not the zero-extending
-    /// `fild QWORD` the two counters use).
-    ///
-    /// **That this field is the signature cap is settled inside the binary rather than inferred
-    /// from the packet's field order**: `CanSignPetition` refuses at `0x4f4634 cmp ecx,[esi+0x1118]`
-    /// against the live signature count. It is *not* the nine name rows — see the module doc of
-    /// `crate::ui_petition`.
+    /// The record's signature cap (`+0x1118`), which `CanSignPetition` tests (`0x4f4634`), not the
+    /// nine name rows; pushed signed (`fild DWORD`).
     pub max_signatures: i32,
-    /// The owner's name through the `NameCache` — **`nil` when uncached** (`0x4f446d`), never `""`.
+    /// The owner's name from the `NameCache`, nil while uncached (`0x4f446d`), never `""`.
     pub originator: Option<String>,
-    /// Whether the active player's guid equals the record's owner (`0x4f447a`/`0x4f4481`).
+    /// Whether the active player owns the record (`0x4f447a`, `0x4f4481`).
     pub is_originator: bool,
 }
 
-/// What the two charter windows read — the module's `.data` state, in the same three pieces.
+/// What the two charter windows read, mirroring the reference module's `.data` state.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct PetitionState {
-    /// `GetGuildCharterCost()` — showlist **entry\[0\]**'s fourth dword (`[0xbdce50]`), in copper.
-    ///
-    /// **Unsigned**, because the binding pushes it through the `fild QWORD` idiom with the high
-    /// dword forced to zero (`0x4f5245`): a negative `charterCost` on the wire surfaces in Lua as
-    /// ~4.29e9, not as a negative number. `0` before any showlist has arrived, and after the
-    /// world-enter clear.
-    ///
-    /// That it is **copper** is settled without going through the UI: `0x4f50ed` compares this cell
-    /// directly against `PLAYER_FIELD_COINAGE` and refuses with `ERR_NOT_ENOUGH_MONEY`.
+    /// `GetGuildCharterCost()`: showlist entry 0's cost (`[0xbdce50]`) in copper, which `0x4f50ed`
+    /// compares against `PLAYER_FIELD_COINAGE`. Unsigned, as the binding zero-extends it
+    /// (`0x4f5245`), so a negative wire cost reads ~4.29e9; 0 before any showlist.
     pub charter_cost: u32,
-    /// The open petition's signers in wire order, each resolved through the `NameCache` — `None`
-    /// where the name has not landed. Its length is `GetNumPetitionNames()`, which counts
-    /// **signatures only**: the petition's owner is not among them.
-    ///
-    /// Independent of [`Self::record`] on purpose (module doc): the packet fills this, the cache
-    /// fills that, and the bindings read one each.
+    /// The signers in wire order, `None` until the `NameCache` resolves one; filled by the packet,
+    /// apart from [`Self::record`]. `GetNumPetitionNames()` counts these, never the owner.
     pub signers: Vec<Option<String>>,
-    /// The cached record, or `None` — the no-record leg.
+    /// The cached record; `None` is the no-record leg.
     pub record: Option<PetitionRecordView>,
-    /// `CanSignPetition()`, computed app-side because three of its four refusals need state the
-    /// engine does not hold. See [`PetitionState::can_sign`]'s own note in `crate::ui_petition`;
-    /// the shape to remember here is that **it is `1` when nothing is open at all**.
+    /// `CanSignPetition()`, computed app-side as three of its four refusals need state the engine
+    /// lacks; it is `1` with nothing open, as in the reference.
     pub can_sign: bool,
 }
 
-/// A charter intent queued from Lua, drained by the app into its send.
-///
-/// **Almost every one is fire-and-forget, and that is the wire's shape**: buying is answered only by
-/// the item appearing, offering is answered to the *target*, and a refusal comes back on the guild
-/// family's own error channel. Nothing here may update local state optimistically.
+/// A charter intent queued from Lua for the app to send. Most get no answer of their own (a
+/// purchase shows only as the item, an offer answers the target, a refusal comes on the guild error
+/// channel), so none may update local state optimistically.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum PetitionRequest {
-    /// `BuyGuildCharter(name)` — the registrar's Purchase button, **after** the name passed
-    /// [`validate_guild_name`]. The app supplies the NPC guid from the latched registrar, which is
-    /// the petition module's own `[0xbdceb0]` and *not* `CGGameUI`'s interaction pair.
+    /// `BuyGuildCharter(name)`, after [`validate_guild_name`]; the app adds the registrar NPC
+    /// latched at `[0xbdceb0]`, not `CGGameUI`'s interaction pair.
     Buy(String),
-    /// `TurnInGuildCharter()` — no argument. The app scans the bags, because the real client does
-    /// (`0x5ef2b0`, and it latches nothing: it re-scans on every call).
+    /// `TurnInGuildCharter()`: the app scans the bags on every call, as the reference does
+    /// (`0x5ef2b0`).
     TurnIn,
-    /// `CloseGuildRegistrar()` — **sends nothing of its own**, VERIFIED by a closure walk over
-    /// `0x4f5010` that finds no `CDataStore` build and no send, with this TU's own four sends as
-    /// the positive control.
+    /// `CloseGuildRegistrar()`: sends nothing (`0x4f5010`).
     CloseRegistrar,
-    /// `SignPetition([n])` — the optional argument is a **byte on the wire** and defaults to `1`
-    /// (`0x4f46d9`), not to `0`. vmangos skips it, so only a golden can tell the difference.
+    /// `SignPetition([n])`: a wire byte defaulting to 1, not 0 (`0x4f46d9`); vmangos skips it.
     Sign(i8),
-    /// `OfferPetition()` — no argument; the app resolves the **current target** (`CGGameUI`'s
-    /// *selection* pair, not its interaction pair) and runs the eight guards.
+    /// `OfferPetition()`: the app resolves the current target (`CGGameUI`'s selection pair, not its
+    /// interaction pair) and runs the eight guards.
     Offer,
-    /// `RenamePetition(name)` — after [`validate_guild_name`].
+    /// `RenamePetition(name)`, after [`validate_guild_name`].
     Rename(String),
-    /// `ClosePetition()` — **and this one can put bytes on the wire.** `0x4f3f60`'s decline leg
-    /// sends `MSG_PETITION_DECLINE` whenever a petition was open, no sign is in flight, a record is
-    /// cached, and we are **not** its owner. The app decides that; the verb just says "close".
+    /// `ClosePetition()`: `0x4f3f60` sends `MSG_PETITION_DECLINE` when a petition was open, no sign
+    /// is in flight, a record is cached and we do not own it; the app decides.
     ClosePetition,
-    /// A name the client itself refused ([`validate_guild_name`]) — carries the GlobalStrings key
-    /// of the message to show. **No packet is built**: the real client's validator runs before the
-    /// send and emits through the message catalog on its own.
+    /// A name [`validate_guild_name`] refused, with the GlobalStrings key to show; no packet.
     NameRefused(&'static str),
 }
 
 impl super::UiScript {
-    /// Push the charter snapshot, replacing whatever was there. A bare setter — firing the four
-    /// events on their edges (and *deferring* `PETITION_SHOW`) is the app's job.
+    /// Replace the charter snapshot; the app fires the four events and defers `PETITION_SHOW`.
     pub fn set_petition(&mut self, state: PetitionState) {
         self.model_mut().petition = state;
     }
@@ -145,19 +90,10 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().petition_requests)
     }
 
-    /// Drop any queued close intent, reporting how many went — **the close-intent consumption
-    /// decision 0096 named**, and the one thing a window switch cannot work without.
-    ///
-    /// Firing `PETITION_CLOSED` runs the frame's `OnHide` synchronously, and that handler calls
-    /// `ClosePetition()`, which queues a close. On a *switch* — a charter offered to us while ours
-    /// is open — the feed fires `PETITION_CLOSED` then `PETITION_SHOW` for the new charter, and the
-    /// close queued by the first would be drained onto the session the second just opened: the new
-    /// charter's window flashes and shuts. **And here it would also put a `MSG_PETITION_DECLINE` on
-    /// the wire for a charter we did not decline**, which is the sharper reason it must go.
-    ///
-    /// It cannot eat a *user's* close by mistake, and the ordering is what guarantees that rather
-    /// than a flag: the feed runs `before(UiInput)`, so a click's own `OnHide` queues its close
-    /// after this has already run.
+    /// Drop the queued close intents, returning how many. Firing `PETITION_CLOSED` runs `OnHide`,
+    /// whose `ClosePetition()` queues a close; on a switch to a newly offered charter that close
+    /// would shut the new window and decline it on the wire. A user's close survives, as the feed
+    /// runs `before(UiInput)` and a click's `OnHide` queues after this.
     pub fn drop_petition_close_intents(&mut self) -> usize {
         let requests = &mut self.model_mut().petition_requests;
         let before = requests.len();
@@ -170,40 +106,18 @@ impl super::UiScript {
         before - requests.len()
     }
 
-    /// Queue one charter intent directly — the test seam.
+    /// Queue one charter intent directly: the test seam.
     #[cfg(test)]
     pub fn queue_petition_request(&mut self, request: PetitionRequest) {
         self.model_mut().petition_requests.push(request);
     }
 }
 
-/// The client-side guild-name check `BuyGuildCharter` and `RenamePetition` **share** — `0x4f5160`,
-/// which runs the name through the locale-aware string checker `0x6c9b70` and maps its code to one
-/// of seven messages, accepting **only** code `0xd`. `Ok(())` is that acceptance; `Err(key)` is the
-/// GlobalStrings key of the line to show, and **no packet is built**.
-///
-/// **Partial, deliberately, and here is exactly how far it goes.** The code space belongs to
-/// `0x6c9b70`, which is not read in full, so only the checks whose meaning is unambiguous from
-/// the message keys are implemented — empty, a leading or trailing space, and consecutive spaces.
-/// The three that need data we do not have (`ERR_GUILD_NAME_TOO_SHORT`'s minimum,
-/// `ERR_GUILD_NAME_PROFANE`'s word list, `ERR_GUILD_NAME_MIXED_LANGUAGES`' script rules) **pass**
-/// rather than guess: refusing a name the server would have accepted is the worse failure, and the
-/// server re-checks every one of them anyway (`ObjectMgr::IsValidCharterName`). What this buys over
-/// sending blindly is the case the reference makes loudest and the server answers with silence —
-/// clicking Purchase with an empty box.
-///
-/// The reference's full table of codes, with what each maps to:
-///
-/// | code | key | implemented |
-/// |---|---|---|
-/// | 0 | `ERR_GUILD_ENTER_NAME` | **yes** — the empty string |
-/// | 1 | `ERR_GUILD_NAME_TOO_SHORT` | no — the minimum is inside `0x6c9b70` |
-/// | 4 | `ERR_GUILD_NAME_MIXED_LANGUAGES` | no |
-/// | 5 | `ERR_GUILD_NAME_PROFANE` | no |
-/// | 6 | `ERR_GUILD_NAME_RESERVED` | no |
-/// | 10 | `ERR_GUILD_NAME_INVALID_SPACE` | **yes** — a leading or trailing space |
-/// | 11 | `ERR_GUILD_NAME_NAME_CONSECUTIVE_SPACES` | **yes** |
-/// | 2,3,7,8,9,>0xb | `ERR_GUILD_NAME_INVALID` | no |
+/// The guild-name check `BuyGuildCharter` and `RenamePetition` share (`0x4f5160`), which maps the
+/// checker `0x6c9b70`'s code to a message and accepts only `0xd`; `Err` carries the GlobalStrings
+/// key to show, and no packet is built. Only codes 0 (empty), 10 (an edge space) and 11
+/// (consecutive spaces) are built; the rest pass, as the checker's rules are untraced and the
+/// server re-checks every name (`ObjectMgr::IsValidCharterName`).
 pub fn validate_guild_name(name: &str) -> Result<(), &'static str> {
     if name.is_empty() {
         return Err("ERR_GUILD_ENTER_NAME");
@@ -217,7 +131,7 @@ pub fn validate_guild_name(name: &str) -> Result<(), &'static str> {
     Ok(())
 }
 
-/// 1.12's `1`/`nil`, never `true`/`false` — this client has no `lua_pushboolean`.
+/// 1.12's `1` or nil, never `true`/`false`: this client has no `lua_pushboolean`.
 fn era_bool(on: bool) -> Value {
     if on {
         Value::Integer(1)
@@ -226,7 +140,7 @@ fn era_bool(on: bool) -> Value {
     }
 }
 
-/// A cached name pushes as a string; an uncached one pushes **nil**.
+/// A cached name as a string, an uncached one as nil.
 fn name_value(lua: &Lua, name: Option<&String>) -> mlua::Result<Value> {
     match name {
         Some(n) => Ok(Value::String(lua.create_string(n)?)),
@@ -239,14 +153,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
     // ── The petition window ──────────────────────────────────────────────────────────────────
-    // GetPetitionInfo() (`0x4f43d0`) — **exactly six values on BOTH legs** (`mov eax,0x6` at
-    // `0x4f4493` and `0x4f44d4`), in the order the reference destructures them
-    // (`PetitionFrame.lua:10`).
-    //
-    // The no-record leg is NOT "return nothing": it is `nil, nil, nil, 0, nil, nil`, with the
-    // fourth pushed as the *number* zero (`0x4f44b4 push 0; push 0; call 0x6f3810`). This file
-    // first shipped an empty return, which reads identically through the reference's own
-    // destructure and differently to anything that counts its arguments.
+    // GetPetitionInfo() (`0x4f43d0`): six values on both legs (`0x4f4493`, `0x4f44d4`), in the
+    // order `PetitionFrame.lua:9` destructures them; with no record, `nil, nil, nil, 0, nil, nil`,
+    // the fourth the number 0 (`0x4f44b4`).
     g.set(
         "GetPetitionInfo",
         lua.create_function(|lua, ()| {
@@ -272,9 +181,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetNumPetitionNames() (`0x4f44e0`, 44 bytes — one field read) — `[0xbdce20]`, pushed
-    // UNSIGNED. It counts **signatures only**; the owner is painted separately by the window and is
-    // never in this list.
+    // GetNumPetitionNames() (`0x4f44e0`): `[0xbdce20]`, unsigned; signatures only, never the owner.
     g.set(
         "GetNumPetitionNames",
         lua.create_function(|lua, ()| {
@@ -283,13 +190,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPetitionNameInfo(index) (`0x4f4510`) — **1-based** (`0x4f4569 dec eax`), one value on
-    // every leg. The bound test `0x4f456c jae` is UNSIGNED, so index `< 1` wraps to `0xffffffff`
-    // and fails the same comparison — which is why a zero or negative index answers nil rather
-    // than the last row. An uncached name is **nil**, not `""`.
-    //
-    // A non-numeric argument is `luaL_error("Usage: GetPetitionNameInfo(index)")`, which longjmps;
-    // mlua's coercion raises for us on the same input, so the shape is preserved.
+    // GetPetitionNameInfo(index) (`0x4f4510`): 1-based, one value on every leg. The bound test is
+    // unsigned (`0x4f456c`), so 0 or a negative index wraps and answers nil. A non-numeric
+    // argument raises, through mlua's coercion as through the reference's `Usage:`.
     g.set(
         "GetPetitionNameInfo",
         lua.create_function(|lua, index: i64| {
@@ -305,13 +208,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CanSignPetition() (`0x4f45e0`) — the Sign button's only gate.
-    //
-    // **It returns `1` with NO petition open**, and that is the reference's own asymmetry rather
-    // than a reading error: `0x4f45f7 je 0x4f4655` jumps past the three record-dependent refusals
-    // straight into the signer scan, over an array the close path has already zeroed. A client that
-    // treats this as a sufficient precondition lets the user click Sign with nothing to sign — so
-    // the window's own `isOriginator` branch is what actually keeps the button off screen.
+    // CanSignPetition() (`0x4f45e0`), the Sign button's only gate, is `1` with no petition open:
+    // `0x4f45f7` jumps past the three record refusals into a scan of the zeroed signer array. The
+    // window's `isOriginator` branch is what hides the button.
     g.set(
         "CanSignPetition",
         lua.create_function(|lua, ()| {
@@ -321,7 +220,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── The registrar window ─────────────────────────────────────────────────────────────────
-    // GetGuildCharterCost() (`0x4f5230`) — copper, unsigned, `0` before any showlist.
+    // GetGuildCharterCost() (`0x4f5230`): copper, unsigned, 0 before any showlist.
     g.set(
         "GetGuildCharterCost",
         lua.create_function(|lua, ()| {
@@ -331,8 +230,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── The verbs ────────────────────────────────────────────────────────────────────────────
-    // The four that carry nothing and push nothing. None may touch the snapshot: none of them is
-    // acknowledged, so a local update would show a charter as signed that the server refused.
+    // The four that carry and push nothing; none may touch the snapshot, which the server owns.
     for (global, request) in [
         ("TurnInGuildCharter", PetitionRequest::TurnIn),
         ("CloseGuildRegistrar", PetitionRequest::CloseRegistrar),
@@ -349,10 +247,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // SignPetition([n]) (`0x4f46d0`) — the argument is OPTIONAL and rides the wire as a byte,
-    // defaulting to **1**, not 0 (`0x4f46d9 edi = 1`, `0x4f4749 Put8`). The server skips the byte,
-    // so nothing observable depends on it — which is exactly why it is easy to ship as 0 and never
-    // find out.
+    // SignPetition([n]) (`0x4f46d0`): the optional argument rides the wire as a byte defaulting to
+    // 1, not 0 (`0x4f46d9`, `0x4f4749 Put8`); the server skips it.
     g.set(
         "SignPetition",
         lua.create_function(|lua, n: Option<f64>| {
@@ -364,10 +260,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // BuyGuildCharter(guildName) (`0x4f5260`) — **returns the number `1` or `nil`**, and what it
-    // reports is NAME VALIDITY, not that a packet was sent: `0x4f5294` runs the shared validator and
-    // only its non-zero return reaches the action, which then has five silent refusals of its own.
-    // Nothing in the shipped FrameXML reads the return; an addon can.
+    // BuyGuildCharter(guildName) (`0x4f5260`) returns 1 or nil for name validity, not for a send:
+    // `0x4f5294` runs the shared validator, and the action behind it has five silent refusals.
     g.set(
         "BuyGuildCharter",
         lua.create_function(|lua, name: String| {
@@ -387,11 +281,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // RenamePetition(name) (`0x4f4930`) — **0 values**, the SAME validator, and silent on refusal
-    // beyond the validator's own message. (Its usage string is literally
-    // `Usage(RenamePetition("name")` in the binary — Blizzard's own unbalanced parenthesis. It is
-    // unreachable from our binding, which raises through mlua's coercion instead, and is recorded
-    // here rather than reproduced.)
+    // RenamePetition(name) (`0x4f4930`): zero values, the same validator, silent beyond its
+    // message. A bad argument raises mlua's coercion error; the reference's usage string is
+    // `Usage(RenamePetition("name")`, unbalanced.
     g.set(
         "RenamePetition",
         lua.create_function(|lua, name: String| {
@@ -465,13 +357,6 @@ mod tests {
         );
     }
 
-    /// **The no-record leg is six values, not none** — `nil, nil, nil, 0, nil, nil`, with the
-    /// fourth the *number* zero.
-    ///
-    /// This file first shipped an empty return, which the reference's own six-way destructure
-    /// cannot tell apart (both give six nils… except the fourth, which is `0` here and `nil`
-    /// there). The COUNT is what separates them — [`UiScript::arity`] — and it is the whole point
-    /// of the test.
     #[test]
     fn the_no_record_leg_is_six_values_with_a_numeric_zero() {
         let s = UiScript::new().unwrap();
@@ -494,8 +379,7 @@ mod tests {
         );
     }
 
-    /// The name list is 1-based and bounded, an uncached name is **nil**, and the count excludes
-    /// the owner. The zero/negative cases matter because the binary's bound test is *unsigned*.
+    /// The zero and negative indices matter because the reference's bound test is unsigned.
     #[test]
     fn petition_names_are_one_based_and_uncached_reads_nil() {
         let mut s = UiScript::new().unwrap();
@@ -534,8 +418,7 @@ mod tests {
         }
     }
 
-    /// `CanSignPetition()` is era-boolean **and answers `1` with nothing open** — the reference's
-    /// own asymmetry, pinned so nobody "fixes" it into a nil.
+    /// The `1` with nothing open is the reference's own asymmetry, not a bug to fix.
     #[test]
     fn can_sign_petition_answers_one_with_nothing_open() {
         let s = UiScript::new().unwrap();
@@ -557,7 +440,6 @@ mod tests {
         );
     }
 
-    /// The cost is copper, unsigned, and belongs to the registrar rather than to any petition.
     #[test]
     fn charter_cost_is_unsigned_copper_and_the_registrars() {
         let mut s = UiScript::new().unwrap();
@@ -567,7 +449,7 @@ mod tests {
         });
         assert_eq!(s.eval::<i64>("return GetGuildCharterCost()").unwrap(), 1000);
 
-        // A negative wire cost surfaces as ~4.29e9, not as a negative — the `fild QWORD` idiom.
+        // A negative wire cost reads ~4.29e9: the binding zero-extends it (`fild QWORD`).
         s.set_petition(PetitionState {
             charter_cost: (-1i32) as u32,
             ..PetitionState::default()
@@ -581,7 +463,6 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetGuildCharterCost()").unwrap(), 0);
     }
 
-    /// `SignPetition`'s optional argument rides the wire as a byte and **defaults to 1**.
     #[test]
     fn sign_petition_defaults_its_wire_byte_to_one() {
         let mut s = UiScript::new().unwrap();
@@ -598,8 +479,7 @@ mod tests {
         );
     }
 
-    /// `BuyGuildCharter` reports **name validity** as `1`/`nil`, and a refused name queues its
-    /// message instead of a packet. `RenamePetition` shares the validator and returns nothing.
+    /// A refused name queues its message instead of a packet.
     #[test]
     fn the_name_validator_gates_both_verbs_and_only_buy_reports_it() {
         let mut s = UiScript::new().unwrap();
@@ -631,8 +511,6 @@ mod tests {
         );
     }
 
-    /// The validator's three implemented codes, and — just as load-bearing — the names it lets
-    /// through rather than guessing at.
     #[test]
     fn the_validator_refuses_only_what_it_can_prove() {
         assert_eq!(validate_guild_name(""), Err("ERR_GUILD_ENTER_NAME"));
@@ -648,9 +526,8 @@ mod tests {
             validate_guild_name("Legacy  of Steel"),
             Err("ERR_GUILD_NAME_NAME_CONSECUTIVE_SPACES")
         );
-        // Passed through on purpose: the minimum length, the profanity list and the script rules
-        // all live inside `0x6c9b70`, which is not read in full, and refusing a name the server
-        // would accept is the worse failure. The server re-checks every one of them.
+        // Passed through: the length, profanity and script rules live in the untraced `0x6c9b70`,
+        // and the server re-checks them.
         for ok in ["Legacy of Steel", "A", "Ab", "Éclair", "x y z"] {
             assert_eq!(
                 validate_guild_name(ok),
@@ -660,8 +537,6 @@ mod tests {
         }
     }
 
-    /// The close-intent consumption removes exactly the two close verbs and preserves the order of
-    /// everything else.
     #[test]
     fn dropping_close_intents_leaves_the_other_verbs_untouched() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/pointer.rs b/crates/benilla-ui/src/script/pointer.rs
index fde9cc7a..3239e0af 100644
--- a/crates/benilla-ui/src/script/pointer.rs
+++ b/crates/benilla-ui/src/script/pointer.rs
@@ -1,49 +1,11 @@
-//! Pointer input dispatch: hit-testing and the mouse-move/-button/-wheel entry points that turn
-//! host pointer events into FrameScript handler calls (decision 0068). The pipeline is
-//! **hit-test → hover → click/drag**:
+//! Pointer input dispatch: the hit test, and the mouse move, button and wheel entry points that
+//! turn host pointer events into FrameScript handler calls. [`cursor`] owns the payload and
+//! gesture state; this file dispatches.
 //!
-//! - [`UiScript::hit_test`] answers "what's under `(x, y)`" — the topmost-drawn, mouse-enabled,
-//!   effective-visible frame whose resolved rect (and effective ScrollFrame clip, decision 0112
-//!   §5) contains the point. Pure query; fires nothing, mutates nothing.
-//! - [`UiScript::mouse_move`] hit-tests every move and, on a captured-frame **change**, fires the
-//!   `OnLeave`/`OnEnter` pair (the reference's own `motion=true` hover-boundary argument) — and,
-//!   before that, advances an armed drag gesture, an in-flight **Slider thumb drag**, and an
-//!   in-flight **frame move** (`StartMoving`, [`super::object`]'s `movable` cluster). All three
-//!   move within one frame, crossing no hover boundary, so they must run before the boundary
-//!   test.
-//! - [`UiScript::mouse_button`] resolves `OnMouseDown`/`OnMouseUp`, the `OnClick`
-//!   press/release-registration rules ([`button::wants_click`]), the **drag trio** + **world
-//!   drop** below, the **Slider thumb-drag** capture (a left press on a thumb, decision 0250 §5),
-//!   and EditBox click-to-focus — all keyed off the same hit-test. The **double-click detector**
-//!   ([`DOUBLE_CLICK_SECS`]) rides the release edge here too: a click on a frame whose previous
-//!   click landed within 300 ms fires `OnDoubleClick` **instead of** that second `OnClick`.
-//! - [`UiScript::mouse_wheel`] fires `OnMouseWheel`, bubbling to the nearest ancestor with a
-//!   handler when the hit frame has none (a ScrollFrame under a non-scrolling child).
-//!
-//! ## The drag trio + world drop (decisions 0216 §3, corrected by 0218)
-//!
-//! A press on a [`super::Model::drag_registered`] frame **arms** a gesture ([`cursor::arm_drag`]); once
-//! the cursor crosses the drag-start threshold it **starts** (firing `OnDragStart`) — that
-//! threshold check is [`cursor::maybe_start_drag`], run from `mouse_move` on every move. A
-//! release **resolves** the gesture ([`cursor::take_drag`]): a STARTED gesture fires
-//! `OnDragStop` on the source and `OnReceiveDrag` on whatever the release hit (a no-op if that
-//! frame carries no such script), and SUPPRESSES `OnClick` for that release — an un-started
-//! gesture leaves the ordinary click path untouched. The **world drop**
-//! ([`cursor::world_drop_click`]) fires only on a completed left CLICK over the game world:
-//! press AND release both landed on **the world** ([`over_world`] — the world frame, or no frame
-//! at all where none is loaded), no drag started (the byte-verified trigger — the client's
-//! `0x495300` runs on the WorldFrame click release; a drag release routes as a drag, never a
-//! click), routed by the app-fed pick ([`super::Model::world_pick`], decisions 0571 + 0574 — an
-//! object pick keeps everything, terrain drops items only, nothing drops any arm).
-//!
-//! ## Division of labor with [`cursor`]
-//!
-//! [`cursor`] owns the payload/gesture **STATE**: [`super::Model::cursor`] (what the cursor
-//! carries), [`super::Model::drag`] (the in-flight gesture), and the pure functions that
-//! arm/advance/resolve them. This file owns the input **DISPATCH** — turning raw
-//! `(x, y, button, down)` host events into a hit-test plus the right sequence of Lua handler
-//! calls, calling into `cursor`'s state machine at the right points rather than touching
-//! [`super::Model::drag`]/[`super::Model::cursor`] directly.
+//! A frame captures the cursor when it is mouse-enabled and effective-visible and its rect and
+//! effective ScrollFrame clip hold the point (the reference's probe `0x76b020`), taking the first
+//! in the order of the hover walk (`0x7661cd` in `0x7660d0`), which [`crate::order::hit_test`]
+//! implements.
 
 use mlua::Value;
 
@@ -54,40 +16,14 @@ use crate::widget::{ButtonState, FrameHandle};
 use super::clip::{effective_clip, scroll_clip_sources};
 use super::{button, cursor, editbox, event, Model, UiScript};
 
-/// The double-click interval — **300 ms, VERIFIED off the bytes**, a hardcoded instruction
-/// immediate: `0x77937b  81 f9 2c 01 00 00  cmp ecx, 0x12c`, comparing `now − [this+0x334]` inside
-/// the Button mouse-UP dispatcher `0x7792d0`.
-///
-/// The units are verified too, not assumed: `now` comes from `0x42c010` → `0x42b790`, whose
-/// scale is stored as `1.0/freq × 1000.0` and whose counter is `KERNEL32!GetTickCount` (import
-/// `[0x7ff310]`) — milliseconds either way.
-///
-/// **What it is NOT**, because all three were live hypotheses and each is closed at the bytes:
-/// it is not the OS setting (`CS_DBLCLKS` is never requested — all four `RegisterClassExA` sites
-/// pass `style = 0x20` = `CS_OWNDC` alone — and `GetDoubleClickTime` is not imported), it is not a
-/// CVar (no such `.rdata` string; nothing near the compare reaches `CVar::Register 0x63db90`), and
-/// there is **no position gate** (the `0x766122`–`0x766140` "double-click detector" this was first
-/// chased through is really the zero-motion cursor-move coalescing filter). The only spatial
-/// constraint
-/// is that each release hit-tests inside the frame, applied independently; the two clicks may land
-/// arbitrarily far apart.
-///
-/// So the interval does not follow the host OS double-click speed and the player cannot change it.
+/// The double-click interval, 300 ms, a constant in the Button mouse-up dispatcher `0x7792d0`
+/// (`0x77937b cmp ecx, 0x12c` on the `0x42c010` millisecond clock). It is not the OS double-click
+/// time (`GetDoubleClickTime` is not imported) and not a CVar, and there is no distance limit:
+/// each release only has to hit the frame.
 pub(super) const DOUBLE_CLICK_SECS: f64 = 0.300;
 
-// ── Input / hit-testing (decision 0068; spec-faithful, not byte-pinned) ─────────────────────
-//
-// The reference's mouse-focus model: focus walks frames top-down in reverse draw order; the
-// first mouse-enabled, effective-visible frame whose resolved rect contains the cursor
-// captures. This is faithful to the *documented model*, **not** bit-exact — the real hit-test
-// leaf is not byte-pinned (see [`crate::order::hit_test`]).
-// Coordinates are WoW UI space (y-up, pixels) — the same space [`resolve`]/[`extract`] use.
-// Call [`resolve`] first so rects are populated; a frame with no resolved rect never captures.
-
-/// Install the pointer-adjacent Lua globals: `GetCursorPosition()` → the model's live cursor in
-/// the engine's y-up UI space (fed by the host's mouse_move/mouse_button) — what the ref's
-/// `MouseIsOver`/FCF hover logic reads (1.12 returns UI-scaled coords; benilla's UI space is
-/// 1:1 logical px, so no scale factor applies).
+/// Install `GetCursorPosition()` and `GetMouseFocus()`. The cursor is in UI units, as 1.12
+/// answers it; the engine's y-up UI space is 1:1 logical pixels, so no scale factor applies.
 pub(super) fn install(lua: &mlua::Lua) -> mlua::Result<()> {
     lua.globals().set(
         "GetCursorPosition",
@@ -97,23 +33,14 @@ pub(super) fn install(lua: &mlua::Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetMouseFocus()` — the frame the mouse is over, or nil.
-    //
-    // **The corpus's most-wanted engine verb**: 78 of 218 addons call it (decision 1195). Every
-    // tooltip scanner, every "what am I hovering" helper and every mouseover-macro library is this
-    // one call. It is a pure read of the hover state [`UiScript::mouse_move`] already maintains —
-    // `Model::mouseover`, the frame that owns the `OnEnter`/`OnLeave` boundary — so the answer is
-    // exactly the frame whose `OnEnter` last fired, which is what an addon means by "focus".
-    //
-    // Returns the frame's **wrapper table**, not its name: the reference returns a frame object and
-    // callers immediately write `GetMouseFocus():GetName()`.
+    // `GetMouseFocus()` (`0x48df40`): the hover frame `[root+0x7c]`, a disabled Button included, as
+    // its frame object (not its name), or nil.
     lua.globals().set(
         "GetMouseFocus",
         lua.create_function(|lua, ()| {
             let id = {
                 let mut model = lua.app_data_mut::<super::Model>().expect("model app_data");
-                // Re-check liveness: a frame can be destroyed between the hover and this call, and
-                // handing back a wrapper for a dead handle is worse than answering nil.
+                // A frame destroyed since the hover answers nil.
                 model
                     .mouseover
                     .filter(|&h| model.arena.frame(h).is_some())
@@ -128,11 +55,8 @@ pub(super) fn install(lua: &mlua::Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Whether `h` is the world frame — the one frame whose mouse hits belong to the 3D world
-/// (decisions 1983/1984: the hover walk `0x7661cd` inside `0x7660d0` probes strata 8→0, and the
-/// world frame wins exactly when nothing else mouse-enabled is under the cursor; the press runs
-/// the frame's Lua `OnMouseDown` — never consuming (`0x483c40`) — then the `BUTTON1`/`BUTTON2`
-/// binding, which **is** the world click; the release mirrors it).
+/// Whether `h` is the world frame, whose mouse hits belong to the 3D world; it wins the hover walk
+/// only when nothing else mouse-enabled is under the cursor.
 fn is_world_handle(model: &Model, h: FrameHandle) -> bool {
     model
         .arena
@@ -140,21 +64,13 @@ fn is_world_handle(model: &Model, h: FrameHandle) -> bool {
         .is_some_and(|f| f.kind == crate::widget::FrameKind::WorldFrame)
 }
 
-/// Whether a press/release target is **the world** rather than the UI — the predicate the world
-/// drop is gated on, and the one thing decision 1983 silently changed the meaning of.
-///
-/// Before the stock `WorldFrame` joined the manifest (1983, 2026-09-04) the world was simply
-/// *where no frame is*, and this was spelled `hit.is_none()` throughout. The stock file anchors a
-/// mouse-enabled frame over the whole screen, so from that day every world click hit a frame and
-/// the world drop stopped firing — B380 (decision 2089). The world frame IS the reference's click
-/// target for a world click, so it answers **yes** here; `None` still answers yes too, because a
-/// harness with no `WorldFrame.xml` loaded (most tests, an install-less checkout) has nothing
-/// under the cursor at all and means the same thing by it.
+/// Whether a press or release target is the world: the world frame, the reference's world click
+/// target, or no frame where `WorldFrame.xml` is not loaded (most tests).
 fn over_world(model: &Model, target: Option<FrameHandle>) -> bool {
     target.is_none_or(|h| is_world_handle(model, h))
 }
 
-/// Whether `(x, y)` falls inside one of this frame's hyperlink spans — the engine half of the
+/// Whether `(x, y)` falls inside one of this frame's hyperlink spans, the engine half of the
 /// reference's per-span `CSimpleHyperlinkButton` children.
 fn link_span_hit(model: &Model, fh: FrameHandle, x: f32, y: f32) -> bool {
     model
@@ -164,24 +80,8 @@ fn link_span_hit(model: &Model, fh: FrameHandle, x: f32, y: f32) -> bool {
 }
 
 impl UiScript {
-    /// Hit-test the cursor at `(x, y)` and return the **handle** of the captured frame (the
-    /// topmost-drawn mouse-enabled, effective-visible frame whose rect contains the point **and**
-    /// whose effective ScrollFrame clip, if any, also contains it — decision 0112 §5: a button
-    /// scrolled out of its ScrollFrame's rect must not hit), or `None`. Pure query — fires nothing,
-    /// mutates nothing. Call [`Self::resolve`] first; a frame with no resolved rect never captures.
-    ///
-    /// **The handle form exists because a name is not always available and an id is not always
-    /// comparable.** [`Self::hit_test`] answers in ids (what the app and the Lua bindings speak) and
-    /// [`Self::hit_test_name`] answers in names (what a human reads). An instrument that has to ask
-    /// *whose* frame ate a click needs neither: the frame may be **anonymous**, and the only set it
-    /// can be checked against is a handle set snapshotted earlier ([`Self::live_targets`]'s). The
-    /// addon harness's use probe asks exactly that — a pointer event is only an addon's to be
-    /// judged by when the frame under the cursor is one the addon itself created.
-    /// Whether a frame id names a [`FrameKind::WorldFrame`] — the reference's world frame, whose
-    /// mouse hits belong to the 3D world (decisions 1983/1984). The hit test still answers it (it
-    /// is mouse-enabled by construction, so an addon's `OnEnter`/`OnMouseDown` on it fire — the
-    /// reference runs those, then the click's `BUTTON1`/`BUTTON2` binding, which IS the world
-    /// click), but the app's pointer arbiter does not count it as being over the UI.
+    /// Whether a frame id names the world frame: hit-tested like any frame, so scripts on it fire,
+    /// but not counted by the app as over the UI.
     pub fn is_world_frame(&self, id: u32) -> bool {
         let model = self.model_ref();
         model
@@ -190,33 +90,21 @@ impl UiScript {
             .is_some_and(|h| is_world_handle(&model, *h))
     }
 
+    /// The handle of the frame that captures `(x, y)`, for a caller that checks it against a
+    /// handle set taken earlier (an anonymous frame has no name). Needs [`Self::resolve`] first.
     pub fn hit_test_frame(&self, x: f32, y: f32) -> Option<FrameHandle> {
         let model = self.model_ref();
         let sorted = order::traversal(&model.arena);
         let scroll_sources = scroll_clip_sources(&model);
         order::hit_test(&sorted, |fh| {
-            // Mouse-enabled, **or inside one of this frame's hyperlink spans**.
-            //
-            // That second half is how the reference makes a chat link clickable on a frame that
-            // takes no mouse at all. `CSimpleMessageScrollFrame`'s ctor leaves `[+0xcc] = 0`, so
-            // `ChatFrame1` is never in the hit-test index — instead the engine synthesises one
-            // mouse-enabled `CSimpleHyperlinkButton` child PER SPAN (`0x7a3240`, born through the
-            // `CSimpleButton` ctor) and routes the three hyperlink scripts back to the parent
-            // through vtable slots `+0x90`/`+0x94`/`+0x98`.
-            //
-            // We hold the spans as rects on the parent rather than as child frames, so the same
-            // law expresses as a disjunct here. What it buys is everything the reference gets from
-            // the split: the chat window is a hit candidate only over a LINK, so `GetMouseFocus()`
-            // answers what is behind it elsewhere, its `movable="true"` +
-            // `<TitleRegion setAllPoints="true"/>` stay inert so it drags by its tab and not its
-            // body, and a hover over plain text reassigns to whatever is underneath.
+            // Mouse-enabled, or over one of the frame's hyperlink spans. The chat frame takes no
+            // mouse (`[+0xcc] = 0`); the reference gives each span a mouse-enabled
+            // `CSimpleHyperlinkButton` child (`0x7a3240`) that routes its scripts to the parent, so
+            // a chat window hits only over a link and drags by its tab, not its body.
             (model.arena.is_mouse_enabled(fh) || link_span_hit(&model, fh, x, y))
-                // **The nameplate's own `+0x3c` veto** (`0x7cba30`): while a ground-targeted spell
-                // is armed a plate refuses the hit test *before* the rect is tested, and the point
-                // falls through to the `WorldFrame` behind it so the reticle can be placed through
-                // a plate. It is not the mouse-enabled bit — see
-                // [`super::UiScript::set_nameplate_hit_test_veto`] for why that distinction is
-                // load-bearing rather than pedantic.
+                // The nameplate's `+0x3c` veto (`0x7cba30`), not its mouse-enabled bit: while a
+                // ground-targeted spell is armed a plate refuses the hit before its rect is
+                // tested, so the reticle is placed through it.
                 && !model.nameplates.vetoes(fh)
                 && model.resolved.get(&fh).is_some_and(|r| {
                     point_in_rect(inset_rect(*r, model.arena.hit_rect_insets(fh)), x, y)
@@ -226,23 +114,15 @@ impl UiScript {
         })
     }
 
-    /// [`Self::hit_test`] over the frames that take the WHEEL — either bit, since a mouse-enabled
-    /// frame with an `<OnMouseWheel>` is a candidate for both. Same rect and clip rules; only the
-    /// enable predicate differs.
+    /// [`Self::hit_test`] over the frames that take the wheel: the same rect and clip rules, gated
+    /// on the wheel flag alone.
     fn hit_test_wheel(&self, x: f32, y: f32) -> Option<u32> {
         let model = self.model_ref();
         let sorted = order::traversal(&model.arena);
         let scroll_sources = scroll_clip_sources(&model);
         let fh = order::hit_test(&sorted, |fh| {
-            // **The wheel gates on the handler and CONTINUES** — the one genuine fall-through in
-            // the engine (`0x76c180`, gated on `[frame+0x160]`'s OnMouseWheel chunk being
-            // present). Down/up deliberately do not use the idiom; the wheel does. So this asks
-            // for the WHEEL flag alone and lets the sweep walk past a frame that merely takes the
-            // mouse, which is what puts the wheel through a scroll pane's chrome and into the
-            // pane.
-            //
-            // It used to also accept `is_mouse_enabled` as a stand-in, because the loader did not
-            // arm the wheel kind and no frame ever carried the flag. The loader arms it now.
+            // The wheel flag alone: the wheel index is separate from the mouse's, so the wheel
+            // passes a frame that only takes the mouse, as a scroll pane's chrome does.
             model.arena.is_mouse_wheel_enabled(fh)
                 && model.resolved.get(&fh).is_some_and(|r| {
                     point_in_rect(inset_rect(*r, model.arena.hit_rect_insets(fh)), x, y)
@@ -253,18 +133,13 @@ impl UiScript {
         model.frame_to_id.get(&fh).copied()
     }
 
-    /// Hit-test the cursor at `(x, y)` and return the **id** of the captured frame, or `None` —
-    /// [`Self::hit_test_frame`] with the id lookup every caller in the input path wants. The id is
-    /// the same one used across this host (e.g. the layout [`crate::layout::Handle`]); the app can
-    /// hand it back or map it as it likes.
+    /// [`Self::hit_test_frame`] as a frame id, the id the app and the Lua bindings use.
     pub fn hit_test(&self, x: f32, y: f32) -> Option<u32> {
         let hit = self.hit_test_frame(x, y)?;
         self.model_ref().frame_to_id.get(&hit).copied()
     }
 
-    /// The NAME of the frame [`Self::hit_test`] captures at `(x, y)` — the pointer twin of
-    /// [`super::UiScript::quad_owner_name`] ("who eats a click here?"), for tests and probe
-    /// tooling. `None` when nothing captures the point or the captured frame is anonymous.
+    /// The name of the frame [`Self::hit_test`] captures at `(x, y)`, for tests and probes.
     pub fn hit_test_name(&self, x: f32, y: f32) -> Option<String> {
         let id = self.hit_test(x, y)?;
         let model = self.model_ref();
@@ -272,18 +147,12 @@ impl UiScript {
         model.arena.frame(fh)?.name.clone()
     }
 
-    /// Move the cursor to `(x, y)`: hit-test, and if the captured frame **changed** since the last
-    /// move, fire `OnLeave(self, motion=true)` on the frame being left (if any and still live) and
-    /// `OnEnter(self, motion=true)` on the newly-captured frame (if any). Tracks the current
-    /// mouseover in the model. Also advances an armed [`super::Model::drag`] gesture (decision 0216 §3)
-    /// and an in-flight [`super::Model::moving`] frame ([`super::object`]'s `movable` cluster):
-    /// both run BEFORE the boundary test below, since dragging within one frame crosses no hover
-    /// boundary at all. A **DISABLED Button** takes the hover — `GetMouseFocus()` answers it — but
-    /// fires neither script ([`button::hover_notify_runs`]). Returns the captured frame id (so the app can drive
-    /// `PointerOverUi`). Handler errors are collected into [`UiScript::errors`], never panicking.
+    /// Move the cursor to `(x, y)`. When the hovered frame changes, fires `OnLeave(self, true)` on
+    /// the old one if still live and `OnEnter(self, true)` on the new; a disabled Button takes the
+    /// hover but fires neither ([`button::hover_notify_runs`]). Drags and frame moves advance
+    /// first. Returns the hovered frame id.
     pub fn mouse_move(&mut self, x: f32, y: f32) -> Option<u32> {
-        // A drag-active EditBox tracks every move (`0x77a860`): extend the selection to the
-        // hovered char, cursor following — before any hover-boundary early return.
+        // A drag-active EditBox extends its selection on every move (`0x77a860`).
         editbox::drag_update(&self.lua, x, y);
         let new_id = self.hit_test(x, y);
         #[allow(clippy::type_complexity)]
@@ -296,25 +165,18 @@ impl UiScript {
         ) = {
             let mut model = self.model_mut();
             model.cursor_pos = (x, y);
-            // Advance an in-flight Slider thumb drag first — dragging within one frame crosses no
-            // hover boundary, so this must run before the early return below (decision 0250 §5).
+            // Drags advance on every move, before the hover test: a drag within one frame crosses
+            // no hover boundary.
             let slider_change = super::slider::drag_move(&mut model, x, y);
-            // The colour picker's wheel/strip drag, for the identical reason — and it fires on
-            // every move, not only on a change (the widget has no change-gate).
+            // The colour picker fires on every move, not only on a change: it has no change gate.
             let color_change = super::colorselect::drag_move(&mut model, x, y);
-            // A frame in flight from `StartMoving()` follows the cursor here for the same reason
-            // (`object::movable`): the frame moves *under* the cursor, so the hover boundary never
-            // crosses and a pump behind the early return would only ever advance when the cursor
-            // left the frame it is dragging.
             super::object::advance_move(&mut model, (x, y));
             super::object::advance_size(&mut model, (x, y));
             let drag_start = cursor::maybe_start_drag(&mut model, (x, y));
             let new_handle = new_id.and_then(|id| model.id_to_frame.get(&id).copied());
             if new_handle == model.mouseover {
-                // no boundary crossed
                 (None, drag_start, None, slider_change, color_change)
             } else {
-                // Fire OnLeave only if the frame we're leaving is still live.
                 let old_id = model.mouseover.and_then(|h| {
                     model
                         .arena
@@ -325,31 +187,17 @@ impl UiScript {
                 });
                 let old_handle = model.mouseover;
                 model.mouseover = new_handle;
-                // **Crossing a button's boundary moves NO button state**, and the comment that
-                // used to sit here claimed the opposite off two mis-attributed addresses:
-                // `0x7793f0` is the drag-start override, not a leave, and `0x7791e0` is the hide
-                // override, not an enter. The real enter/leave notifies `0x779490`/`0x7794e0`
-                // read `[+0x328]` only as a DISABLED guard and never write it.
-                //
-                // So a press held over a button and walked off it stays PUSHED in the reference —
-                // it is the *drag threshold* (below) that un-presses one, and only for a frame
-                // that registered for drag. Decision 2134.
-                //
-                // **A DISABLED Button swallows its own hover notify** and so runs neither script:
-                // both `0x779490` and `0x7794e0` open `mov eax,[esi+0x328]; test eax,eax; je`,
-                // branching past the base notify that owns the `<OnEnter>`/`<OnLeave>` slots
-                // ([`button::hover_notify_runs`]). The gate is per-side — leaving a button that
-                // was disabled *while* hovered is as silent as entering one — and it is applied
-                // AFTER `model.mouseover` moves, because the reference reassigns the hover target
-                // `[root+0x7c]` before it fires either notify: a disabled button is still the
-                // mouse focus, it just says nothing.
+                // Crossing a button's boundary changes no button state: the enter/leave notifies
+                // (`0x779490`/`0x7794e0`) read `[+0x328]` only as a disabled guard, so a press
+                // walked off a button stays pushed until the drag start (`0x7793f0`) un-presses a
+                // drag-registered one. A disabled Button runs neither script, on either side, and
+                // is still the hover: the reference moves `[root+0x7c]` before either notify.
                 let old_id = old_id.filter(|_| button::hover_notify_runs(&model, old_handle));
                 let enter_id = new_id.filter(|_| button::hover_notify_runs(&model, new_handle));
                 (old_id, drag_start, enter_id, slider_change, color_change)
             }
         };
-        // The thumb-drag value change fires OnValueChanged (outside the borrow) — the scrollbar's
-        // OnValueChanged→SetVerticalScroll wiring runs here, exactly as the arrow buttons drive it.
+        // A thumb drag fires `OnValueChanged`, outside the borrow.
         if let Some((id, value)) = slider_change {
             if let Err(e) = event::fire_widget_handler(
                 &self.lua,
@@ -394,13 +242,8 @@ impl UiScript {
         new_id
     }
 
-    /// Is `(x, y)` inside this frame's title region?
-    ///
-    /// **False whenever the region has no resolved rect**, which is the common case and the correct
-    /// one: a freshly created title region has NO anchors at all and does nothing until
-    /// `SetPoint`/`SetAllPoints` (`CreateTitleRegion 0x773910`). Both corpus consumers call
-    /// `SetAllPoints` immediately, so
-    /// theirs covers the whole window — the whole-window-as-drag-handle idiom.
+    /// Whether `(x, y)` is inside the frame's title region. A new title region has no anchors and
+    /// hits nothing until `SetPoint`/`SetAllPoints` (`CreateTitleRegion 0x773910`).
     fn title_region_hit(&self, h: crate::widget::FrameHandle, x: f32, y: f32) -> bool {
         let model = self.model_ref();
         model
@@ -411,65 +254,20 @@ impl UiScript {
             .is_some_and(|r| point_in_rect(*r, x, y))
     }
 
-    /// A mouse button transition at `(x, y)`: `button` is the WoW name (`"LeftButton"`,
-    /// `"RightButton"`, …), `down` is press vs release. Fires `OnMouseDown(self, button)` on press or
-    /// `OnMouseUp(self, button)` on release. **The press fires on the hit frame and the release on
-    /// the frame that took the press** — the client's mouse capture (`root+0x80`); see the dispatch
-    /// itself for the bytes and for the stuck-resize it prevents.
-    ///
-    /// Separately, `OnClick` fires per the hit frame's `RegisterForClicks` set
-    /// ([`button::wants_click`]): a **press** fires immediately when the frame registered
-    /// `"<Button>ButtonDown"` (`OnClick(self, button, down=true)`); a **release** whose matching
-    /// **press** captured the *same* frame fires when the frame registered `"<Button>ButtonUp"`
-    /// (`OnClick(self, button, down=false)` — the Era signature,
-    /// `warcraft.wiki.gg/wiki/UIHANDLER_OnClick`). The default set is `{"LeftButtonUp"}`, so
-    /// unregistered buttons (a bare right-click, say) reach neither. Press targets are tracked per
-    /// button.
-    ///
-    /// The drag trio + world drop (decision 0216 §3, corrected by 0218) ride the same
-    /// transition: a press ARMS a [`super::Model::drag`] gesture on a [`super::Model::drag_registered`] frame
-    /// ([`cursor::arm_drag`]); a release RESOLVES it ([`cursor::take_drag`]) — a STARTED gesture
-    /// fires `OnDragStop` on the source and `OnReceiveDrag` on whatever the release hit (a no-op
-    /// if that frame carries no such script), and SUPPRESSES `OnClick` for this release (an
-    /// un-started gesture leaves the ordinary click path untouched). The **world drop**
-    /// ([`cursor::world_drop_click`]) fires ONLY on a completed left CLICK over the world —
-    /// press AND release both [`over_world`], no started drag (the byte-verified trigger: the
-    /// client's `0x495300` runs on the WorldFrame click release; a drag release routes as a
-    /// drag, never a click — and the director's report confirmed it) — routed by the app-fed
-    /// pick (decisions 0571 + 0574): over an object nothing
-    /// drops (the reference keeps an item payload and selects); over terrain an item fires
-    /// `DELETE_ITEM_CONFIRM` and stays held while a spell/action survives; over nothing the
-    /// item pops and any other payload clears silently. A drag released over nothing keeps its
-    /// payload untouched.
-    ///
-    /// Handler errors are collected into [`UiScript::errors`]. Returns whether the UI consumed
-    /// the event (`hit_id.is_some()` or a world drop was handled) — a new public return; existing
-    /// statement-position calls (`script.mouse_button(...);`) are unaffected.
+    /// A mouse button press or release at `(x, y)`; `button` is the WoW name (`"LeftButton"`, …).
+    /// `OnClick` follows `RegisterForClicks` ([`button::wants_click`], default `{"LeftButtonUp"}`):
+    /// a press fires it for `"<Button>ButtonDown"`, a release on the pressed frame for
+    /// `"<Button>ButtonUp"`. Its `down` argument is not 1.12, whose firer (`0x779540`) passes only
+    /// the button name. Returns whether the UI consumed the event.
     pub fn mouse_button(&mut self, x: f32, y: f32, button: &str, down: bool) -> bool {
         let hit_id = self.hit_test(x, y);
-        // ── The RAISE, and it happens FIRST ─────────────────────────────────────────────────────
+        // ── The raise, first ────────────────────────────────────────────────────────────────────
         //
-        // `0x7662c0`: the mouse-button-DOWN handler resolves target = root+0x80 (existing
-        // capture) else root+0x7c (hover frame), calls `0x76a5b0` Raise() **UNGUARDED**
-        // @`0x766392` (the toplevel gate is inside `0x7650f0`, so the raised frame may be an
-        // ancestor of the clicked one), then title-region drag or capture+OnMouseDown.
-        //
-        // Four clauses, each load-bearing and each visible:
-        //
-        //  · **DOWN only.** The sibling category-`0xe` handler `0x766420` never raises — a window
-        //    comes forward on the press, not on the release.
-        //  · **Before the title-region swallow below**, so grabbing a window by its title bar
-        //    raises it too, even though that path dispatches no `OnMouseDown` at all.
-        //  · **Unguarded** — no toplevel test out here. [`toplevel::raise`] walks to the nearest
-        //    toplevel self-or-ancestor and does nothing when there is none, which is exactly what
-        //    makes a click on a *child* (a button, a tab, the window's own background texture)
-        //    bring the whole window forward.
-        //  · **Capture else hover.** [`Model::mouse_capture`] is `root+0x80`; while a button is
-        //    held it wins, so a chorded press over a different window raises the one being
-        //    dragged, not the one under the cursor.
-        //
-        // Nothing here is gated on the frame being mouse-enabled: the "hover frame" is the
-        // hit-test result, which already applies that gate.
+        // The press handler `0x7662c0` raises the capture (`root+0x80`) else the hover frame
+        // (`root+0x7c`) through `0x76a5b0`, called unguarded at `0x766392` (the toplevel walk is
+        // inside `0x7650f0`), before the title-region test: a click on a child or a title bar
+        // brings its window forward, and a chorded press raises the window being dragged. The
+        // release handler `0x766420` never raises.
         if down {
             let target = self.model_ref().mouse_capture;
             if let Some(t) = target.or_else(|| self.hit_test_frame(x, y)) {
@@ -477,16 +275,11 @@ impl UiScript {
                 super::object::toplevel::raise(&mut model, t);
             }
         }
-        // ── The title region, and it SWALLOWS the press ─────────────────────────────────────────
+        // ── The title region swallows the press ─────────────────────────────────────────────────
         //
-        // A mouse-down inside `frame:GetTitleRegion()` starts a mode-2 move and never reaches the
-        // ordinary path: the reference's `0x7662c0` tests `titleRegion+0x24` point-in-rect FIRST
-        // and only a MISS falls through to `0x7663e6`, which sets the captured frame and dispatches
-        // `vtable[0x68]` — the OnMouseDown script. So a hit takes `OnMouseDown`/`OnMouseUp` and
-        // `RegisterForDrag`'s `OnDragStart` with it.
-        //
-        // Returning early is what implements that swallow: no OnMouseDown, no drag arm, no OnClick,
-        // no double-click bookkeeping. It reports the event CONSUMED, because it was.
+        // A press inside the title region starts a mode-2 move and ends there: `0x7662c0` tests
+        // the region first and only a miss reaches `0x7663e6`, the capture and `OnMouseDown`. So
+        // no `OnMouseDown`, drag arm, `OnClick` or double-click stamp, and the event is consumed.
         if down {
             if let Some(h) = self.hit_test_frame(x, y) {
                 if self.title_region_hit(h, x, y) {
@@ -496,13 +289,11 @@ impl UiScript {
                 }
             }
         }
-        // ── …and the release ends it, where a scripted move would survive ───────────────────────
+        // ── The release ends a title move ───────────────────────────────────────────────────────
         //
-        // `0x766420` auto-cancels modes 1 (modifier-drag) and 2 (title region) and leaves mode 3
-        // (`StartMoving`) alone — so a window grabbed by its title bar stops when the button comes
-        // up, while `OnDragStart → StartMoving` keeps moving until the addon's
-        // `StopMovingOrSizing`. Reduced to [`FrameMove::auto_stop`], because that one bit is all
-        // of the mode that is observable from Lua.
+        // `0x766420` cancels move modes 1 (modifier drag) and 2 (title region) on release and
+        // leaves mode 3 (`StartMoving`) to the addon's `StopMovingOrSizing`;
+        // `FrameMove::auto_stop` is that distinction.
         if !down
             && self
                 .model_ref()
@@ -512,9 +303,7 @@ impl UiScript {
         {
             self.model_mut().moving = None;
         }
-        // The capture this release belongs to — read HERE because the borrow below *drains*
-        // `mouse_down_on` for this button. See the `OnMouseUp` dispatch further down for why the
-        // press target rather than the hit frame.
+        // The press this release belongs to, read before the borrow below drains `mouse_down_on`.
         let captured_id: Option<u32> = if down {
             None
         } else {
@@ -524,8 +313,7 @@ impl UiScript {
                 .get(button)
                 .and_then(|h| model.frame_to_id.get(h).copied())
         };
-        // The session clock, read before the borrow below — the double-click detector's only input
-        // beyond the hit ([`Model::last_click`]). Same `GetTime()` seconds every script sees.
+        // The `GetTime()` clock for the double-click detector, read before the borrow.
         let now = self.now();
         self.model_mut().cursor_pos = (x, y);
         let btn = match self.lua.create_string(button) {
@@ -535,10 +323,6 @@ impl UiScript {
                 return hit_id.is_some();
             }
         };
-        // Resolve the OnClick target (if any), arm/resolve the drag gesture, and handle a world
-        // drop — all under one short borrow. A press fires OnClick when the hit frame registered
-        // "<Button>ButtonDown"; a release fires it when press+release landed on the same frame AND
-        // it registered "<Button>ButtonUp" — UNLESS a started drag is being resolved instead.
         #[allow(clippy::type_complexity)]
         let (
             click_id,
@@ -564,50 +348,34 @@ impl UiScript {
                     Some(h) => model.mouse_down_on.insert(button.to_string(), h),
                     None => model.mouse_down_on.remove(button),
                 };
-                // `0x7792b1`: the press edge, `SetButtonState(PUSHED, 0)`.
-                //
-                // It is unconditional *past* `0x779210`'s own two gates, and the first of them is
-                // the registration mask `[this+0x330]` tested as `m | m << 8` at `0x77924b` —
-                // "registered for this mouse button EITHER WAY, up or down". That is
-                // [`button::wants_press_visual`], and it is why a right-click lights up an action
-                // slot (it registers `RightButtonUp`) and does nothing at all to a plain
-                // `LeftButtonUp` button. Past it the edge is gated only on the button's own
-                // `locked == 0 && state != DISABLED`.
+                // The press edge, `SetButtonState(PUSHED)` (`0x7792b1`), for a button registered
+                // for this mouse button up or down (`0x779210` tests `m | m << 8` at `0x77924b`).
                 if let Some(h) = hit_handle.filter(|&h| button::wants_press_visual(&model, h, button))
                 {
                     button::edge(&mut model, h, ButtonState::on_mouse_down);
                 }
-                // A press arriving while this same mouse button was already holding another
-                // frame is a release we never got (the OS ate it — a focus loss, a modal). Give
-                // the displaced frame that release rather than leaving it pushed forever; the
-                // reference never reaches this because its capture guarantees the release.
+                // A press while this mouse button still holds another frame means a release was
+                // lost (a focus loss); that frame gets it so it does not stay pushed. The
+                // reference's capture never loses one.
                 if let Some(h) = displaced {
                     button::edge(&mut model, h, ButtonState::on_mouse_up);
                 }
-                // `0x7663e6` writes the resolved target into `root+0x80` — capture-else-hover, so
-                // this is an `or`, not an assignment: an existing capture is not displaced by a
-                // second button pressed elsewhere. (This is the point the reference reaches only
-                // on a title-region MISS, which is why the swallow above returns before it.)
+                // `0x7663e6` sets the capture `root+0x80` only when none is held: a second button
+                // pressed elsewhere does not displace it.
                 model.mouse_capture = model.mouse_capture.or(hit_handle);
-                // A press REPLACES any in-flight gesture, so a started one has to be ended first
-                // — `abandon_drag`'s own doc carries why a silent drop is a stuck UI rather than a
-                // cancelled drag. Its `OnDragStop` fires below, outside this borrow.
+                // A press replaces any in-flight gesture; a started one gets its `OnDragStop`
+                // below, outside this borrow.
                 let abandoned = cursor::abandon_drag(&mut model);
                 cursor::arm_drag(&mut model, hit_handle, button, (x, y));
-                // A left press on a Slider begins the engine drag (0250 §5): a thumb press grabs
-                // it in place; a track press seats the thumb under the cursor first (the returned
-                // value jump — 0989), independent of the click/drag-trio path above (a Slider
-                // isn't drag_registered).
+                // A left press on a Slider grabs the thumb, or on the track seats the thumb under
+                // the cursor first (the returned value jump).
                 let jump = if button == "LeftButton" {
                     super::slider::begin_drag(&mut model, hit_handle, x, y)
                 } else {
                     None
                 };
-                // A left press inside a ColorSelect's wheel or value strip captures the colour
-                // drag AND jumps the colour to the click point in the same call — the widget's
-                // press handler invokes its own cursor-position handler before returning
-                // (`0x78bf70 call [eax+0x3c]`), so there is no such thing as a press that only
-                // arms.
+                // A left press in a ColorSelect's wheel or value strip also jumps the colour to the
+                // click point: its press handler calls its cursor handler (`0x78bf70`).
                 let color_jump = if button == "LeftButton" {
                     super::colorselect::begin_drag(&mut model, hit_handle, x, y)
                 } else {
@@ -620,13 +388,11 @@ impl UiScript {
                 (click, None, false, jump, None, abandoned, color_jump)
             } else {
                 let pressed = model.mouse_down_on.remove(button);
-                // `root+0x80` is cleared at `0x7664bb` **only when the post-event button mask is
-                // zero** — a chorded release keeps the capture for the button still held. With the
-                // per-button map already drained above, "mask is zero" is "the map is empty".
+                // `0x7664bb` clears the capture only when no button is still held, so a chorded
+                // release keeps it.
                 if model.mouse_down_on.is_empty() {
                     model.mouse_capture = None;
                 }
-                // A left release ends any in-flight thumb drag (decision 0250 §5).
                 if button == "LeftButton" {
                     super::slider::end_drag(&mut model);
                     super::colorselect::end_drag(&mut model);
@@ -637,27 +403,15 @@ impl UiScript {
                 );
                 let release = cursor::take_drag(&mut model, button);
                 let started = release.as_ref().is_some_and(|r| r.started);
-                // **The release edge** — `0x7793de`'s `SetButtonState(NORMAL, 0)`, on the frame
-                // the PRESS captured and regardless of where the cursor now is (`0x7792d0` runs
-                // no hit test of its own). It is guarded on the button's own `locked == 0` and on
-                // the state actually being PUSHED, and it is **skipped when the base finalized a
-                // drag** — `0x7792df`'s `0x76c040` test, which is this `started` (the button
-                // already un-pressed at the drag-start edge below, and un-pressing again would
-                // fire nothing but would be a second transition the reference does not make).
+                // The release edge, `SetButtonState(NORMAL)` (`0x7793de`), on the pressed frame
+                // wherever the cursor is, skipped after a started drag (`0x7792df` tests
+                // `0x76c040`), which already un-pressed it.
                 if let (Some(h), false) = (pressed, started) {
                     button::edge(&mut model, h, ButtonState::on_mouse_up);
                 }
-                // The world drop: press AND release both over THE WORLD, no drag started —
-                // a completed left click on the game world (never a drag release, which just
-                // keeps carrying; decision 0218's byte-verified trigger). What actually drops
-                // is routed inside `world_drop_click` by the app-fed world pick (decisions
-                // 0571 + 0574): an object pick keeps everything, terrain drops items only,
-                // nothing drops any arm.
-                //
-                // "Over the world" is [`over_world`], not `is_none()`: since 1983 the stock
-                // `WorldFrame` is a real mouse-enabled frame covering the screen, so a world
-                // click hits IT — which is exactly what the reference's own world click is
-                // (1984). Spelling this as "no frame" is what B380 was (decision 2089).
+                // The world drop: a completed left click on the world, never a drag release, which
+                // keeps carrying (`0x495300` runs on the WorldFrame click release). The world is
+                // `over_world`, not "no frame": the stock `WorldFrame` covers the screen.
                 let dropped = button == "LeftButton"
                     && !started
                     && over_world(&model, hit_handle)
@@ -671,22 +425,11 @@ impl UiScript {
                         .filter(|&h| same_frame && button::wants_click(&model, h, &wants))
                         .and(hit_id)
                 };
-                // ── The double-click adjudication — on the RELEASE edge, on the click that just
-                // qualified, and STRICTLY EXCLUSIVE with it.
-                //
-                // All three of those are byte-verified: the only site that fires the `+0x4d4`
-                // slot is `0x77938d`, inside the mouse-UP
-                // dispatcher `0x7792d0` — the mouse-DOWN dispatcher `0x779210` has no double-click
-                // leg at all — and `0x77939d jmp 0x7793b5` skips *past* the single leg's
-                // `call [edx+0x94]`, so **`OnDoubleClick` REPLACES the second `OnClick`; it is not
-                // additive**. Whatever suppresses the click (a resolved drag, a release on another
-                // frame, a button this widget never registered) suppresses this too, by
-                // construction: it hangs off `click`.
-                //
-                // The handler-presence test is load-bearing, not an optimisation. The binary's
-                // chain includes `[+0x4d4] != 0`, so a widget with no `OnDoubleClick` script takes
-                // the ordinary single leg every time — without that gate, rattling any button in
-                // the UI would silently swallow every second `OnClick`.
+                // The double click, on the release that qualified as a click: `0x77938d` in the
+                // mouse-up dispatcher `0x7792d0` fires `OnDoubleClick` instead of the second
+                // `OnClick` (`0x77939d jmp 0x7793b5` skips the single leg), only for a frame with
+                // an `OnDoubleClick` script (`[+0x4d4] != 0`). What suppresses the click
+                // suppresses it too.
                 let target = click.and(hit_handle);
                 let double = target.filter(|&h| {
                     model
@@ -699,24 +442,20 @@ impl UiScript {
                             .is_some_and(|&t| now - t <= DOUBLE_CLICK_SECS)
                 });
                 if let Some(h) = double {
-                    // A completed double ZEROES the stamp (`0x779393`), so clicks PAIR: four fast
-                    // clicks are Click · DoubleClick · Click · DoubleClick, never one click and
-                    // three doubles.
+                    // A double clears the stamp (`0x779393`), so clicks pair: four fast clicks are
+                    // click, double, click, double.
                     model.last_click.remove(&h);
                 } else if let Some(h) = target {
-                    // A fired single ARMS the detector (`0x7793af`) — on the click *predicate*,
-                    // not on an `OnClick` handler existing: the binary stamps after calling the
-                    // firer, which is itself a no-op when no script is bound.
+                    // A single stamps the detector (`0x7793af`) whether or not an `OnClick` script
+                    // is bound.
                     model.last_click.insert(h, now);
                 }
                 let double_id = double.and_then(|h| model.frame_to_id.get(&h).copied());
-                // Exclusive, not additive — the double leg is taken *instead of* the single one.
                 let click = if double_id.is_some() { None } else { click };
                 (click, release, dropped, None, double_id, None, None)
             }
         };
-        // A track press's value jump fires OnValueChanged first (outside the borrow), the same
-        // seam as `mouse_move`'s in-drag changes — the press IS the first move of the gesture.
+        // A track press's value jump fires `OnValueChanged` first, outside the borrow.
         if let Some((id, value)) = slider_jump {
             if let Err(e) = event::fire_widget_handler(
                 &self.lua,
@@ -727,59 +466,25 @@ impl UiScript {
                 self.push_error(e);
             }
         }
-        // The press's colour jump fires OnColorSelect the same way.
         if let Some((id, r, g, b)) = color_jump {
             if let Err(e) = super::colorselect::fire_by_id(&self.lua, id, r, g, b) {
                 self.push_error(e);
             }
         }
-        // ── `OnMouseUp` goes to the frame that took the PRESS, not to whatever is under the
-        // cursor now — the mouse CAPTURE (`root+0x80`).
+        // ── `OnMouseUp` goes to the capture ─────────────────────────────────────────────────────
         //
-        // The client's mouse-DOWN handler `0x7662c0` takes the pointer: resolves target =
-        // root+0x80 (existing capture) else root+0x7c (hover frame) … then title-region drag or
-        // **capture**+OnMouseDown (`0x7662c0`).
-        //
-        // The **release** half is `0x766420` (decision 1599). It reads the capture
-        // and **nothing else**: `[mgr+0x80]` is snapshotted into `ebx` at entry (`0x76642b`),
-        // before anything, and `[mgr+0x7c]` — the hover frame — is **never read** anywhere in
-        // `[0x766420, 0x7664f0)`. One dispatch, `0x7664a4 call [eax+0x6c]`.
-        //
-        // So a press on A released over B fires `OnMouseUp` on **A**, and B gets nothing on the
-        // release edge. We already track exactly that capture — [`Model::mouse_down_on`], the press
-        // target per button, which `OnClick`'s same-frame rule reads — and firing `OnMouseUp` at
-        // the *hit* frame was the one place it went unused. This function's doc always said "on the
-        // captured frame"; the code did not.
-        //
-        // It is not a nicety: a chat window's resize grip is a 16×16 button that the drag pulls
-        // out from under the cursor the moment the size clamps at `SetMinResize`/`SetMaxResize`
-        // (the rebate plants the edge on the bound while the cursor keeps going). Its
-        // `OnMouseUp → FCF_StopResize` then never ran, and `Model::sizing` stayed held for the
-        // rest of the session — the stuck-drag failure `cursor::abandon_drag` exists to prevent on
-        // the other path.
-        //
-        // **A press that captured NOTHING fires nothing**, and this is the half the first version
-        // of this code got wrong: it fell back to the frame under the cursor, reading the DOWN
-        // handler's `+0x80`-else-`+0x7c` precedence as if the UP handler shared it. It does not —
-        // `0x766498 test ebx,ebx / je 0x7664cd` returns with no virtual call at all. The fallback
-        // was a divergence that let a press over open space deliver a release to whatever the
-        // cursor had wandered onto.
-        //
-        // (Two more facts about this dispatch, invisible from here: the capture is cleared at
-        // `0x7664bb`, **after** the dispatch — so a C++ consumer inside `OnMouseUp` still sees it,
-        // though no Lua binding reads it, `GetMouseFocus 0x48df40` being `+0x7c`; and the clear is
-        // gated on `evt+0x18 == 0`, the button mask *after* the event, so a **chorded** release
-        // fires `OnMouseUp` and keeps the capture for the button still held.)
+        // The release handler `0x766420` reads only the capture `[mgr+0x80]` (`0x76642b`), never
+        // the hover frame, so a press on A released over B fires `OnMouseUp` on A, and a press
+        // that captured nothing fires nothing (`0x766498`). A resize grip dragged out from under
+        // the cursor still gets its `OnMouseUp`, so its resize ends.
         let script = if down { "OnMouseDown" } else { "OnMouseUp" };
         if let Some(id) = if down { hit_id } else { captured_id } {
             if let Err(e) = event::fire_widget_handler(&self.lua, id, script, vec![btn.clone()]) {
                 self.push_error(e);
             }
         }
-        // A release inside a hyperlink span fires `OnHyperlinkClick(link, markup, button)` on the
-        // owning frame — the ChatFrameTemplate wires it to `SetItemRef` (decision 0288 P2). Never
-        // on a drag resolution (same suppression as OnClick); spans were fed by the app after the
-        // last rasterize (`UiScript::set_link_spans`), so they match what's on screen.
+        // A release in a hyperlink span fires `OnHyperlinkClick(link, markup, button)` on the
+        // owning frame, except after a started drag.
         if !down && !drag_release.as_ref().is_some_and(|r| r.started) {
             if let Some(id) = hit_id {
                 let span = {
@@ -815,9 +520,8 @@ impl UiScript {
                 }
             }
         }
-        // The EditBox click law (`0x77b800`): a LeftButton press inside an EditBox places the
-        // cursor at the clicked char, starts the drag, and focuses it UNCONDITIONALLY
-        // (independent of autoFocus), before any OnClick fires. A release ends any drag.
+        // A left press in an EditBox places the cursor, starts a selection drag and focuses it
+        // whatever its `autoFocus`, before any `OnClick` (`0x77b800`).
         if button == "LeftButton" {
             if down {
                 if let Some(id) = hit_id {
@@ -827,14 +531,11 @@ impl UiScript {
                 editbox::drag_end(&self.lua);
             }
         }
-        // A gesture this press REPLACED gets its `OnDragStop` too, before anything the new press
-        // does: the handler on the other end has a `StopMovingOrSizing` in it, and until that runs
-        // the engine's one move slot is still held (see `cursor::abandon_drag`).
+        // A gesture this press replaced gets its `OnDragStop` first: its handler's
+        // `StopMovingOrSizing` frees the engine's one move slot.
         if let Some(source) = abandoned {
             self.fire_drag_stop(source);
         }
-        // The drag trio's stop/receive pair, fired outside the model borrow above (only for a
-        // gesture that actually started — see `cursor::DragRelease::started`).
         if let Some(release) = drag_release.filter(|r| r.started) {
             self.fire_drag_stop(release.source);
             if let Some(id) = hit_id {
@@ -846,34 +547,26 @@ impl UiScript {
             }
         }
         if let Some(id) = click_id {
-            // One click home for the physical and programmatic (`Click()`) paths: gated on a
-            // Button's enabled flag, a CheckButton toggles before OnClick fires (button.rs).
+            // Shared with `Click()`: gated on the Button being enabled; a CheckButton toggles
+            // before `OnClick` fires.
             button::click_button(&self.lua, id, button, down, false);
         }
-        // `OnDoubleClick(self, button)` — fired where `OnClick` would have been and instead of it
-        // (`0x77938d call [edx+0x98]`, the mouse-UP dispatcher's exclusive second leg). One
-        // argument, the button name of the *completing* release, and it plays the same click sound
-        // as a single: the base firer `0x779650` is the byte-twin of the single leg's `0x779540`.
-        //
-        // `arg2` is 0 in both legs; we pass it only for `OnClick`, where our binding already spells
-        // it as the documented `down` flag, and drop it here to match the Era-facing
-        // `OnDoubleClick(self, button)` signature the corpus is written against.
+        // `OnDoubleClick(self, button)` in place of `OnClick` (`0x77938d call [edx+0x98]`), with
+        // the same click sound: its firer `0x779650` is the twin of `OnClick`'s `0x779540` and
+        // passes only the button name of the completing release.
         if let Some(id) = double_id {
             if let Err(e) = event::fire_widget_handler(&self.lua, id, "OnDoubleClick", vec![btn]) {
                 self.push_error(e);
             }
         }
-        // Whether the **UI** consumed the event. A hit on the world frame is not the UI
-        // consuming anything — "the press runs the frame's Lua `OnMouseDown` (never consuming),
-        // then the `BUTTON1`/`BUTTON2` binding" (1984) — so it answers no unless the click was
-        // itself the world drop. Without that clause the stock `WorldFrame` would report every
-        // click in the game as eaten by the interface.
+        // A world-frame hit is not the UI consuming the event: the reference runs its
+        // `OnMouseDown` without consuming (`0x483c40`), then the `BUTTON1`/`BUTTON2` binding, the
+        // world click. Only a world drop counts.
         hit_id.is_some_and(|id| !self.is_world_frame(id)) || world_dropped
     }
 
-    /// Fire `OnDragStop` on a gesture's source — the ONE place that ends a started drag, so the
-    /// release path and the two abandon paths ([`cursor::abandon_drag`]) cannot drift apart.
-    /// A source that died between the press and here fires nothing.
+    /// Fire `OnDragStop` on a gesture's source, the one place a started drag ends; a source that
+    /// died since the press fires nothing.
     pub(super) fn fire_drag_stop(&mut self, source: crate::widget::FrameHandle) {
         let id = {
             let model = self.model_ref();
@@ -891,21 +584,14 @@ impl UiScript {
         }
     }
 
-    /// A mouse-wheel spin at `(x, y)`: fires `OnMouseWheel(self, delta)` on the hit frame — or,
-    /// when the hit frame carries no OnMouseWheel handler, on its NEAREST ANCESTOR that does (the
-    /// client's bubbling: a reward-row Button inside a ScrollFrame doesn't eat the wheel, the
-    /// pane keeps scrolling under the cursor). WoW's convention is `+1` per notch up / `-1` down
-    /// (`warcraft.wiki.gg/wiki/UIHANDLER_OnMouseWheel`); `delta` is passed through as given, so
-    /// the app-side feed picks the magnitude/sign. Handler errors are collected into
-    /// [`UiScript::errors`].
+    /// A wheel spin at `(x, y)`: fires `OnMouseWheel(self, delta)` on the hit frame, or on its
+    /// nearest ancestor with the script when it has none; the reference instead lets its wheel
+    /// sweep continue past a frame with no script (`0x76c180`). `delta` passes through as given;
+    /// the reference passes only its sign, `+1` or `-1` (`0x76c1a2`).
     pub fn mouse_wheel(&mut self, x: f32, y: f32, delta: f32) {
         let target: Option<u32> = {
-            // **Wheel-enabled OR mouse-enabled**, not mouse-enabled alone. The reference's wheel
-            // dispatcher `0x7664f0` walks its OWN index and calls the hit probe directly, ignoring
-            // hover, capture and the mouse bit — `EnableMouse` is not a prerequisite. Ours went
-            // through the mouse hit test, which
-            // coupled the two: correcting the ctor list to the reference's (ScrollFrame is inert
-            // on the mouse bit) silently stopped every scroll pane from taking the wheel.
+            // The wheel flag, not the mouse bit: the reference's wheel dispatcher `0x7664f0` walks
+            // its own index and ignores hover, capture and `EnableMouse`.
             let hit = self.hit_test_wheel(x, y);
             let model = self.model_ref();
             hit.and_then(|id| {
@@ -936,19 +622,14 @@ impl UiScript {
     }
 }
 
-/// Point-in-rect for hit-testing, in WoW UI coords (**y-up**): the cursor `(x, y)` is inside `r` when
-/// it lies within `[left, right] × [bottom, top]` (edges inclusive). This is the same space
-/// [`UiScript::resolve`]/[`UiScript::extract`] produce rects in — the verified `point_in_rect
-/// 0x76b020` primitive, modeled on our [`Rect`] convention.
+/// Point-in-rect in UI space (y-up), inclusive on all four edges, as the reference's probe
+/// `0x76b020` tests it.
 pub(super) fn point_in_rect(r: Rect, x: f32, y: f32) -> bool {
     x >= r.left && x <= r.right && y >= r.bottom && y <= r.top
 }
 
-/// A frame's **mouse** rect: its resolved rect shrunk by `[left, right, top, bottom]`
-/// ([`crate::widget::Frame::hit_rect_insets`]). y-up, so a `top` inset lowers `top` and a `bottom`
-/// inset raises `bottom`. Insets that over-shrink collapse the rect rather than inverting it — an
-/// empty rect simply captures nothing, which is what the API's own "inset past the far edge" case
-/// means.
+/// A frame's mouse rect: its resolved rect shrunk by its `[left, right, top, bottom]` hit-rect
+/// insets (y-up); an over-shrunk rect collapses to empty rather than inverting.
 fn inset_rect(r: Rect, [left, right, top, bottom]: [f32; 4]) -> Rect {
     Rect {
         left: r.left + left,
diff --git a/crates/benilla-ui/src/script/pvp/mod.rs b/crates/benilla-ui/src/script/pvp/mod.rs
index 59955df3..53c9734b 100644
--- a/crates/benilla-ui/src/script/pvp/mod.rs
+++ b/crates/benilla-ui/src/script/pvp/mod.rs
@@ -1,108 +1,20 @@
-//! The **PvP + honor** surface — `TogglePVP` (decision 0646) and the vanilla honor system's
-//! thirteen bindings (decision 1512): the character window's Honor tab, the inspect window's Honor
-//! tab, and the rank every unit frame can read off a *foreign* player.
+//! `TogglePVP` and the thirteen honor bindings: the character and inspect windows' Honor tabs and
+//! the rank any unit frame can read off another player.
 //!
-//! ## The three seams
+//! The local player's counters are private descriptor fields the app pushes as a [`HonorState`];
+//! another player's arrive as a `MSG_INSPECT_HONOR_STATS` reply ([`InspectHonorData`]), whose
+//! presence is `HasInspectHonorData`. With nothing held every getter answers zeros at full width,
+//! as the reference reads zero-initialised slots ungated. A foreign player's current rank is
+//! public (`PLAYER_BYTES_3` byte 3) and rides [`UnitState::pvp_rank`](super::UnitState::pvp_rank).
 //!
-//! The crate's usual split (decision 0068 §3 — no ECS, no wire, no DBC in here):
+//! The internal rank (0 none, 1..=4 dishonorable, 5..=18 Scout or Private to High Warlord or
+//! Grand Marshal, 19 the racial "Leader") is what the wire carries and what keys the
+//! `PVP_RANK_<rank>_<team>` GlobalStrings; the visual rank indexes the badge texture, and every
+//! conversion goes through [`visual_rank`].
 //!
-//! - **Pushed state.** The local player's honor counters are PRIVATE descriptor fields
-//!   (`PLAYER_FIELD_SESSION_KILLS` … `PLAYER_FIELD_BYTES2`), so the app decodes them and pushes a
-//!   [`HonorState`] ([`UiScript::set_honor`]); the six self getters read it and nothing else.
-//!   The inspect pane's numbers are **not** a descriptor: `MSG_INSPECT_HONOR_STATS` (`0x2D6`) is a
-//!   request/reply pair, so they arrive separately as an [`InspectHonorData`]
-//!   ([`UiScript::set_inspect_honor`]) — and *whether one is held* is exactly what
-//!   `HasInspectHonorData` reports, which is the latch the reference's `OnShow` gates its request
-//!   on. That is why the inspect half is an `Option`, and the self half too — but the `Option` is
-//!   the **latch only**: the engine's data slots are zero-initialised BSS that every getter reads
-//!   ungated, so "nothing held" answers **zeros at full width**, never nils and never a short
-//!   return. The one thing an empty slot changes is `HasInspectHonorData`.
-//! - **Intents.** `TogglePVP` queues a `CMSG_TOGGLE_PVP` ([`UiScript::take_pvp_toggles`]) and
-//!   `RequestInspectHonorData` queues the honor query
-//!   ([`UiScript::take_inspect_honor_requests`]) — both counts rather than payloads, because
-//!   neither packet carries anything the VM knows: the toggle has an empty body, and the honor
-//!   query's body is the *inspected player's* guid, which the app already holds
-//!   ([`super::inspect`]'s target). Same reasoning as `NotifyInspect`, one argument smaller.
-//!   The honor query carries a second piece of engine state with it — the **`pending` latch**
-//!   (`0xb71fcc`), which refuses a second query while one is in flight; see the binding.
-//! - **The unit snapshot.** A *foreign* player's rank is knowable at all because `PLAYER_BYTES_3`
-//!   is a PUBLIC field — byte 3 of it is the CURRENT rank — so it rides
-//!   [`UnitState::pvp_rank`](super::UnitState::pvp_rank) with the other public per-unit facts and
-//!   `UnitPVPRank("target")` answers for the inspect pane exactly as the reference's does.
-//!
-//! ## Two ranks, and neither is the other
-//!
-//! - **Internal rank**, `0..=19`: the byte on the wire, and the number `GetPVPRankInfo` keys its
-//!   title lookup on. `0` is "no rank"; `1..=4` are the dishonorable ranks; `5..=18` are
-//!   Scout/Private through High Warlord/Grand Marshal; `19` is the racial-leader "Leader", which
-//!   the server sends in `SMSG_PVP_CREDIT` and **`GetPVPRankInfo` refuses** (see below).
-//! - **Visual rank**, `-4..=14`: `rank >= 5 ? rank - 4 : rank - 5` (`0x51aa31`) — what
-//!   `GetPVPRankInfo` *returns* as its second value, and what FrameXML indexes the badge texture by
-//!   (`"…PvPRank"..format("%02d", rankNumber)`, drawn only when it is positive).
-//!
-//! **The negative half runs the other way from the server's.** vmangos's `HonorMgr.cpp:991`
-//! computes `visualRank = rank > 4 ? rank - 4 : rank * -1`, which gives rank 1 → −1 and rank 4 →
-//! −4; the *binding* subtracts 5 instead of negating, so it gives rank 1 → **−4** and rank 4 →
-//! **−1**. They genuinely disagree, and the client is the authority for what the client's binding
-//! returns — [`visual_rank`] implements the binding. Nothing here reads the server's form, and a
-//! reader "fixing" this back to `-rank` would be undoing a verified read of [`visual_rank`]'s own
-//! bytes.
-//!
-//! Conflating the two scales puts Sergeant's badge on a Corporal, so [`visual_rank`] is the one
-//! place the conversion happens and every caller goes through it. The trap is that both numbers
-//! travel: the badge and `GetPVPRankInfo`'s second return are **visual**, while the wire —
-//! `PLAYER_BYTES_3` byte 3, `GetInspectHonorData`'s `lifetimeRank`, and `SMSG_PVP_CREDIT`'s
-//! `victimRank` (decision 1512 §2's second-pass correction: `HonorMgr::SendPVPCredit` sends
-//! `GetRank().rank`) — is **internal** throughout, which is what lets a rank byte index a
-//! `PVP_RANK_*` GlobalString with no conversion at all.
-//!
-//! ## Why the rank titles come out of the VM's own globals
-//!
-//! A rank's name is the GlobalString `PVP_RANK_<internal>_<team>` — the engine's one format string
-//! (`"PVP_RANK_%d_%d"` @ `0x8445b4`), team `0` Horde and `1` Alliance (VERIFIED against the shipped
-//! `FactionGroup.dbc` *and* `GlobalStrings.lua`: `PVP_RANK_5_0` is "Scout", `PVP_RANK_5_1` is
-//! "Private"). The real `GlobalStrings.lua` is executed off the player's own install at boot, so
-//! those keys are already sitting on `_G` when `GetPVPRankInfo` runs, and reading them there is the
-//! only correct answer: a table of titles shipped in this repo would be Blizzard text we may not
-//! carry (docs/METHOD.md's install-content rule) *and* wrong in every non-enUS locale. There is **no
-//! `PVP_RANK_0_*`** — internal rank 0 names nothing, and both reference panes lean on that nil to
-//! fall back to the `NONE` GlobalString, so a missing key answers nil here rather than an empty
-//! string or a raise.
-//!
-//! The team digit is a **tri-state**, not a bool: `0x5efe00` answers `0` Horde, `1` Alliance, or
-//! **`-1`** for a unit with no side, and −1 is not special-cased anywhere — it is formatted into
-//! the key, `PVP_RANK_9_-1` matches no GlobalString, and the miss *is* the "no title" answer.
-//!
-//! ## `_FEMALE` is real, and the honor pane never sees it
-//!
-//! The `_FEMALE` twins ship in `GlobalStrings.lua`, and the engine cannot build their keys: the
-//! byte sequence `FEMALE` does not occur anywhere in `WoW.exe`. It reaches them by asking
-//! **FrameXML** — `0x703bf0(key, ordinal, gender)` takes a Lua path whenever `gender != 0`, calling
-//! `GetText(token, gender, ordinal)`, which appends the suffix for gender 3. So the *suffix* is
-//! Lua's and the *request* is the engine's, per call site:
-//!
-//! - **`GetPVPRankInfo` passes gender 0** (`0x51aa0f`) and takes the fast path — so the character
-//!   and inspect honor panes render the **male/default title even for a female character**.
-//! - **`UnitPVPName`'s title is gendered** by the subject unit (`0x612bf0`), and
-//!   **`SMSG_PVP_CREDIT`'s is gendered by the LOCAL PLAYER** even though the *team* digit is the
-//!   victim's (`0x625374`) — the app's chat line owns that asymmetry, through
-//!   [`UiScript::pvp_rank_title`].
-//!
-//! So [`rank_title_ungendered`] and [`rank_title_gendered`] are two functions on purpose, and
-//! `GetPVPRankInfo` calls the first. **A client that gendered the pane's title would be more
-//! "correct" than the reference and would diverge from it**, which is not what we build.
-//!
-//! ## The counter-intuitive four
-//!
-//! Everything below is byte law, and every one of them looks like a bug:
-//!
-//! 1. `GetPVPRankProgress` **multiplies by a slightly-wrong f32 reciprocal** and does not clamp —
-//!    [`rank_progress`].
-//! 2. The four dishonorable ranks' visual numbers run **backwards** from the server's — see "Two
-//!    ranks" above.
-//! 3. `GetPVPRankInfo` **rejects rank 19**, whose GlobalString exists and which the credit line and
-//!    `UnitPVPName` both render.
-//! 4. `GetPVPLifetimeStats` **suppresses a highest-lifetime rank below 5**, reporting `0`.
+//! Rank titles are read off the VM's globals, which the install's `GlobalStrings.lua` fills: the
+//! key is `"PVP_RANK_%d_%d"` (`0x8445b4`) with team 0 Horde and 1 Alliance. There is no
+//! `PVP_RANK_0_*`, and both panes fall back to `NONE` on its nil.
 
 use mlua::{Lua, MultiValue, Value};
 
@@ -110,26 +22,20 @@ use super::binding_abi::{number_arg, string_arg};
 use super::unit::{check_unit_token, is_civilian_kill};
 use super::Model;
 
-/// The local player's honor snapshot — every number the character window's Honor tab shows, as the
-/// app decoded it from the PRIVATE honor descriptor fields (decision 1512 §1). EXACT shape the app
-/// feed is written against; do not rename.
-///
-/// The kill counters are `u16` because their fields are `TWO_SHORT` descriptors read as halves
-/// (`PLAYER_FIELD_SESSION_KILLS` low = honorable, high = dishonorable); the honor totals are the
-/// whole-dword `*_CONTRIBUTION` fields.
+/// The local player's honor snapshot, decoded by the app from the private honor descriptor
+/// fields. Kill counts are halves of `TWO_SHORT` fields, low honorable and high dishonorable.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub struct HonorState {
-    /// `PLAYER_FIELD_SESSION_KILLS` low half — honorable kills this session.
+    /// `PLAYER_FIELD_SESSION_KILLS` low half.
     pub session_hk: u16,
-    /// `PLAYER_FIELD_SESSION_KILLS` high half — dishonorable kills this session.
+    /// `PLAYER_FIELD_SESSION_KILLS` high half.
     pub session_dk: u16,
     /// `PLAYER_FIELD_YESTERDAY_KILLS` halves.
     pub yesterday_hk: u16,
     pub yesterday_dk: u16,
-    /// `PLAYER_FIELD_YESTERDAY_CONTRIBUTION` — yesterday's honor.
+    /// `PLAYER_FIELD_YESTERDAY_CONTRIBUTION`.
     pub yesterday_honor: u32,
-    /// `PLAYER_FIELD_THIS_WEEK_KILLS` low half. There is no this-week DK getter: the reference
-    /// destructures exactly two values from `GetPVPThisWeekStats`.
+    /// `PLAYER_FIELD_THIS_WEEK_KILLS` low half; `GetPVPThisWeekStats` has no dishonorable count.
     pub this_week_hk: u16,
     /// `PLAYER_FIELD_THIS_WEEK_CONTRIBUTION`.
     pub this_week_honor: u32,
@@ -138,37 +44,26 @@ pub struct HonorState {
     pub last_week_dk: u16,
     /// `PLAYER_FIELD_LAST_WEEK_CONTRIBUTION`.
     pub last_week_honor: u32,
-    /// `PLAYER_FIELD_LAST_WEEK_RANK` — last week's **standing** (the ladder position), which is
-    /// `GetPVPLastWeekStats`'s fourth return and is not a rank at all.
+    /// `PLAYER_FIELD_LAST_WEEK_RANK`: last week's ladder standing, not a rank.
     pub last_week_standing: u32,
     /// `PLAYER_FIELD_LIFETIME_HONORBALE_KILLS` / `…_DISHONORBALE_KILLS` (the server's spellings).
     pub lifetime_hk: u32,
     pub lifetime_dk: u32,
-    /// `PLAYER_FIELD_BYTES` byte 3 — the HIGHEST LIFETIME rank, internal scale. PRIVATE, and
-    /// already decoded elsewhere in the app as the honor-rank byte.
-    ///
-    /// **Carried raw.** `GetPVPLifetimeStats` suppresses a value below 5 to `0` (`0x51a843`), and
-    /// that suppression is the *binding's*, not the feed's — push the true byte and let the
-    /// binding hide it, because the same field read through any other door is not hidden.
+    /// `PLAYER_FIELD_BYTES` byte 3: the highest lifetime rank, internal scale. Carried raw: only
+    /// `GetPVPLifetimeStats` hides a value below 5 (`0x51a843`).
     pub highest_rank: u8,
-    /// `PLAYER_BYTES_3` byte 3 — the **current** rank, internal scale, `0` = no rank. The same
-    /// PUBLIC byte that reaches every observer as [`UnitState::pvp_rank`](super::UnitState).
+    /// `PLAYER_BYTES_3` byte 3: the current rank, internal scale, 0 for none; the same public
+    /// byte as [`UnitState::pvp_rank`](super::UnitState).
     pub rank: u8,
-    /// `PLAYER_FIELD_BYTES2` byte 0 — progress through the current rank, `0..=255`. Carried as the
-    /// raw byte: the fraction is [`rank_progress`]'s business, not the feed's.
+    /// `PLAYER_FIELD_BYTES2` byte 0: progress through the current rank, the raw byte.
     pub rank_bar: u8,
 }
 
-/// One `MSG_INSPECT_HONOR_STATS` reply (decision 1512 §2), as the app decoded its 50-byte body.
-///
-/// Fourteen numbers and the guid they were about. **There is no per-period DK here** — the reply
-/// carries a session HK/DK pair and then bare HK counts for yesterday/last week/this week (the
-/// three `unknownOld` shorts between them are written as zero by the server), which is why
-/// `GetInspectHonorData` returns twelve values while the self getters together return more.
+/// One `MSG_INSPECT_HONOR_STATS` reply as the app decoded it. It has no dishonorable counts past
+/// the session pair (the server writes zeros there), so `GetInspectHonorData` returns twelve.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub struct InspectHonorData {
-    /// The player guid the reply was for — the app's key for "is this still the player we are
-    /// looking at?". Never returned to Lua; the reference's pane is keyed by its own unit token.
+    /// The player the reply was for, the app's key; never returned to Lua.
     pub guid: u64,
     pub session_hk: u16,
     pub session_dk: u16,
@@ -178,119 +73,70 @@ pub struct InspectHonorData {
     pub this_week_honor: u32,
     pub last_week_hk: u16,
     pub last_week_honor: u32,
-    /// The ladder position, the reply's `lastWeekRank` — `GetInspectHonorData`'s ninth return.
+    /// The reply's `lastWeekRank`, the ladder standing: `GetInspectHonorData`'s ninth return.
     pub last_week_standing: u32,
     pub lifetime_hk: u32,
     pub lifetime_dk: u32,
-    /// The reply's `highestRank` byte — `GetInspectHonorData`'s twelfth return, which the
-    /// reference names `lifetimeRank`. Internal scale, like every other rank here.
-    ///
-    /// **Passed through, where its self-side twin is suppressed below 5.** This pins
-    /// `GetPVPLifetimeStats`'s `cmp al,5; jb` at `0x51a843` and records `0x4c9620` as twelve plain
-    /// pushes with no such gate, so this one is not filtered here. That is a *recorded absence*
-    /// rather than an asserted negative: if a re-read of `0x4c9620` ever turns up the same
-    /// compare, this field's getter is the one place it belongs — and nothing else should be
-    /// harmonised to match it in the meantime.
+    /// The reply's `highestRank`, internal scale: `GetInspectHonorData`'s twelfth return
+    /// (`lifetimeRank`), unfiltered, as `0x4c9620` pushes it with no below-5 gate.
     pub highest_rank: u8,
-    /// The reply's trailing `rankBar` byte — read only by `GetInspectPVPRankProgress`.
+    /// The reply's trailing `rankBar`, read only by `GetInspectPVPRankProgress`.
     pub rank_bar: u8,
 }
 
 impl super::UiScript {
-    /// Drain the PvP-flag toggles queued since the last call — each one is a `CMSG_TOGGLE_PVP`.
-    /// A count rather than a payload: the packet is empty, so two toggles in a frame are two
-    /// sends, not one collapsed intent.
+    /// Drain the queued `TogglePVP` calls, one `CMSG_TOGGLE_PVP` each; the packet is empty, so
+    /// two toggles in a frame are two sends.
     pub fn take_pvp_toggles(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().pvp_toggles)
     }
 
-    /// Queue a toggle from the app side — the `/pvp` slash command. In the reference that slash
-    /// handler *is* Lua (a one-liner over `TogglePVP`); benilla parses slash lines in Rust, so the
-    /// same intent enters the same queue here rather than through the global ([`super::duel`]'s
-    /// `queue_duel_request` reasoning, verbatim).
+    /// Queue a toggle for `/pvp`, which benilla parses in Rust; the reference's `/pvp` is Lua over
+    /// `TogglePVP`.
     pub fn queue_pvp_toggle(&mut self) {
         self.model_mut().pvp_toggles += 1;
     }
 
-    /// Push (or clear, with `None`) the local player's honor snapshot — the six self getters'
-    /// only source. Pushed on the honor descriptor edge, not per frame; it fires no event of its
-    /// own, because the events the reference's pane listens for (`PLAYER_PVP_KILLS_CHANGED`,
-    /// `PLAYER_PVP_RANK_CHANGED`) are the app's to fire alongside the push.
+    /// Push or clear the local player's honor snapshot, the self getters' only source. It fires
+    /// no event: the app fires `PLAYER_PVP_KILLS_CHANGED`/`PLAYER_PVP_RANK_CHANGED` alongside.
     pub fn set_honor(&mut self, honor: Option<HonorState>) {
         self.model_mut().honor = honor;
     }
 
-    /// Push (or clear, with `None`) the last `MSG_INSPECT_HONOR_STATS` reply.
-    ///
-    /// **The presence of this is `HasInspectHonorData`'s answer**, so clearing it is as
-    /// load-bearing as pushing it: the app clears when it drops the inspected player
-    /// (`ClearInspectPlayer`), which is what makes the reference's `OnShow` re-request for the
-    /// next one instead of painting the previous player's numbers. Pair it with the pane's
-    /// `INSPECT_HONOR_UPDATE` event.
-    ///
-    /// **Both arms clear the in-flight latch**, exactly as the engine's two writers do: a reply
-    /// landing zeroes `pending` at `0x4c6f4c`, and re-keying or clearing the slot zeroes it at
-    /// `0x4c6f9d`. So an invalidation also says "whatever was in flight is no longer wanted",
-    /// which is what lets the *next* `RequestInspectHonorData` through.
+    /// Push or clear the last `MSG_INSPECT_HONOR_STATS` reply, paired with the pane's
+    /// `INSPECT_HONOR_UPDATE`. Its presence is `HasInspectHonorData`, so the app clears it on
+    /// `ClearInspectPlayer` and the pane's `OnShow` asks again for the next player. Either way
+    /// the in-flight latch clears, as the engine's reply (`0x4c6f4c`) and re-key (`0x4c6f9d`) do.
     pub fn set_inspect_honor(&mut self, data: Option<InspectHonorData>) {
         let mut model = self.model_mut();
         model.inspect_honor = data;
         model.inspect_honor_pending = false;
     }
 
-    /// Drain the `RequestInspectHonorData` calls queued since the last call — each one is a
-    /// `MSG_INSPECT_HONOR_STATS` send carrying the app's current inspect target guid.
-    ///
-    /// A count, for [`Self::take_pvp_toggles`]'s reason: the binding takes no argument, so there
-    /// is no payload to carry, and the request the *app* addresses is its own inspect target. It
-    /// drains **0 or 1** and never more, because the binding's `pending` latch (`0x4c80b6`)
-    /// refuses a second query until [`Self::set_inspect_honor`] resolves the first — a count kept
-    /// rather than a `bool` because that latch is the engine's, not this signature's, and the app
-    /// loop over it is identical either way.
+    /// Drain the queued `RequestInspectHonorData` calls, each a `MSG_INSPECT_HONOR_STATS` send for
+    /// the app's inspect target. At most 1: the `pending` latch (`0x4c80b6`) refuses another until
+    /// [`Self::set_inspect_honor`] resolves the first.
     pub fn take_inspect_honor_requests(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().inspect_honor_requests)
     }
 
-    /// A PvP rank's localized title for the app's `SMSG_PVP_CREDIT` chat line — the
-    /// `PVP_RANK_<rank>_<team>` GlobalString off the VM's own globals (`team` `0` Horde, `1`
-    /// Alliance), **gendered**: the `_FEMALE` twin when `female`, falling back to the base key.
-    /// A missing or empty key is `None`, never an empty string.
+    /// A rank's localized title for the app's `SMSG_PVP_CREDIT` chat line, `None` if missing or
+    /// empty. Gendered, unlike the pane's: the credit formatter resolves through `0x612bf0`. No
+    /// range check, so rank 19 names "Leader"; `rank` is the internal rank the credit carries
+    /// (`HonorMgr::SendPVPCredit` sends `GetRank().rank`).
     ///
-    /// **Gendered is right *here* and wrong in the pane**, which is the whole reason this is not
-    /// simply `GetPVPRankInfo`'s lookup: the credit formatter resolves through `0x612bf0`
-    /// while `GetPVPRankInfo` passes gender 0. It shares [`rank_title_gendered`]
-    /// with `UnitPVPName`, the engine's other gendered caller.
-    ///
-    /// The number `SMSG_PVP_CREDIT` carries is the **INTERNAL** rank — the GlobalString index
-    /// itself, which is precisely why it can be passed straight in — and NOT the visual rank the
-    /// badge indexes; see the module doc's "Two ranks". Unlike the pane's binding this path applies
-    /// **no range check**, so rank 19 legitimately names "Leader" here.
-    ///
-    /// Two facts the caller owns, neither expressible in this signature: the gender is the
-    /// **local player's** while the team is the **victim's**
-    /// (`0x625374` hands `0x612bf0` the entry `this`, still the local player), and a victim whose
-    /// team resolves to **−1 emits no line at all** (`0x625321 js` bails the whole formatter) —
-    /// which is a `u8` here precisely so that decision cannot be smuggled into a key that misses.
+    /// The caller owns two facts: the gender is the local player's while the team is the
+    /// victim's (`0x625374`), and a victim whose team is -1 gets no line at all (`0x625321`),
+    /// hence `team: u8`.
     pub fn pvp_rank_title(&self, rank: u8, team: u8, female: bool) -> Option<String> {
         rank_title_gendered(self.lua(), i64::from(rank), i64::from(team), female)
     }
 }
 
-/// Internal rank → **visual** rank, `0x51aa31`'s two-legged subtraction:
-///
-/// ```text
-/// 51aa31  cmp edi,0x5
-/// 51aa36  jge 0x51aa55        ; SIGNED
-/// 51aa38  edi += -5           ; ranks 1..4  -> -4 .. -1
-/// 51aa55  edi += -4           ; ranks 5..18 ->  1 .. 14
-/// ```
-///
-/// Defined on `1..=18` only, because that is the whole domain that reaches it: `GetPVPRankInfo`
-/// range-gates first and answers `0` for everything outside, so there is no "rank 0 maps to 0" case
-/// to write here — the badge stays off an unranked player through the gate, not through this.
-///
-/// The negative leg **subtracts 5**; it does not negate. See the module doc — the server's
-/// `visualRank` negates and the two therefore disagree for exactly ranks 1..4.
+/// Internal rank to visual rank (`0x51aa31`): 5..=18 subtract 4, and 1..=4 subtract 5 to give
+/// -4..=-1 (`0x51aa38`). The server's `visualRank` negates instead (`HonorMgr.cpp:991`), so the
+/// two disagree on ranks 1..=4; this is the client's. Only 1..=18 reach it, as `GetPVPRankInfo`
+/// gates first.
 fn visual_rank(rank: i64) -> i64 {
     if rank >= 5 {
         rank - 4
@@ -299,47 +145,29 @@ fn visual_rank(rank: i64) -> i64 {
     }
 }
 
-/// The f32 constant at `0x8026c8` — the four bytes `81 80 80 3b` — that `GetPVPRankProgress` and
-/// `GetInspectPVPRankProgress` multiply the rank-bar byte by. It is the f32 *nearest* `1/255`
-/// (`0.003921568859368563`, against `1/255`'s `0.00392156862745098`) and it is **not** `1/255`.
+/// The f32 at `0x8026c8` (bytes `81 80 80 3b`) that both rank-progress getters multiply the bar
+/// byte by: the f32 nearest 1/255, `0.003921568859368563`, and not 1/255.
 const RANK_BAR_SCALE: f64 = f32::from_bits(0x3B80_8081) as f64;
 
-/// The rank progress bar's byte → the fraction the reference feeds straight to a `StatusBar` whose
-/// `minValue`/`maxValue` are `0`/`1`.
-///
-/// **A multiply by [`RANK_BAR_SCALE`], not a division by 255, and no clamp** — both halves are
-/// verified at the bytes, correcting the natural reading, and both are deliberate:
-///
-/// - `0x51aace` is `fild DWORD` then `fmul DWORD PTR ds:0x8026c8`. Under the client's PC_53 x87
-///   invariant `(double)b * (double)K` and `(double)b / 255.0` differ for **255 of the 256** byte
-///   values (all but 0), so `bar as f64 / 255.0` is bit-wrong on every non-zero input. A byte of
-///   255 comes out as `1.0000000091389835`, *above* 1.0, and a byte of 51 is not exactly 0.2.
-/// - There is no `fcom`, no min/max and no compare anywhere in either function. The value is
-///   `byte * K` and nothing else. Clamping would be tidier and would be a divergence — and it
-///   would hide precisely the >1.0 overshoot that proves the multiply.
-///
-/// A full bar therefore hands `StatusBar:SetValue` a number a hair over its `maxValue`. That is
-/// what the real client does; how our `StatusBar` treats an out-of-range value is that widget's
-/// business, not this binding's.
+/// The rank bar's byte as the fraction the reference feeds a 0..1 `StatusBar`: `fild` then `fmul`
+/// by [`RANK_BAR_SCALE`] (`0x51aace`), with no clamp. It differs from `bar / 255.0` for every byte
+/// but 0, and a full bar gives `1.0000000091389835`, over the bar's maximum.
 fn rank_progress(bar: u8) -> f64 {
     f64::from(bar) * RANK_BAR_SCALE
 }
 
-/// The local player's honor snapshot, or `None` before the first push.
 fn honor(lua: &Lua) -> Option<HonorState> {
     lua.app_data_ref::<Model>().expect("model app_data").honor
 }
 
-/// The last inspect-honor reply, or `None` when none is held.
 fn inspect_honor(lua: &Lua) -> Option<InspectHonorData> {
     lua.app_data_ref::<Model>()
         .expect("model app_data")
         .inspect_honor
 }
 
-/// A GlobalString off the VM's own globals, `None` when it is absent **or empty** — the
-/// no-install / bare-VM path. (`GetPVPRankInfo` tests both explicitly: `0x51aa1c` NULL,
-/// `0x51aa20` empty first byte.)
+/// A GlobalString off the VM's globals, `None` when absent or empty, as `GetPVPRankInfo` tests
+/// both (`0x51aa1c` NULL, `0x51aa20` empty).
 fn global_string(lua: &Lua, key: &str) -> Option<String> {
     lua.globals()
         .get::<Option<String>>(key)
@@ -348,47 +176,26 @@ fn global_string(lua: &Lua, key: &str) -> Option<String> {
         .filter(|s| !s.is_empty())
 }
 
-/// A unit's PvP **team digit** — `0x5efe00`'s tri-state: `0` Horde, `1` Alliance, `-1` for a unit
-/// whose race resolves to no side.
-///
-/// The engine walks race → `ChrRaces` → `FactionTemplate` and tests `[rec+0xc]`'s factionGroupMask
-/// `& 4` → 0, `& 2` → 1, else −1. This crate holds no DBC (decision 0068 §3), so the walk is the
-/// app's and the answer arrives pre-resolved as [`UnitState::pvp_team`](super::UnitState).
-///
-/// **It is not [`UnitState::faction_group`](super::UnitState), which this used to read.** That
-/// field is `UnitFactionGroup`'s — the unit's LIVE `UNIT_FIELD_FACTIONTEMPLATE` — and the two
-/// part company the moment anything moves a unit off its racial faction. A vmangos GM is forced
-/// to template 35 (group mask 0), so every rank title in the Honor tab read `NONE` for a Grand
-/// Marshal while the 1.12 client on the same server read "Grand Marshal" off his unchanged race:
-/// report B378, decision 2227.
-///
-/// −1 needs no special case: it formats into the key, and `PVP_RANK_9_-1` matches no GlobalString.
+/// A unit's PvP team digit, `0x5efe00`'s tri-state from its race (`ChrRaces` to `FactionTemplate`,
+/// group mask `& 4` then `& 2`): 0 Horde, 1 Alliance, -1 no side; resolved by the app as
+/// [`UnitState::pvp_team`](super::UnitState). Not `faction_group`, the live faction template: a
+/// vmangos GM's template 35 has no side while his race keeps one. -1 misses every key.
 fn team_of(u: &super::UnitState) -> i64 {
     i64::from(u.pvp_team)
 }
 
-/// `GetPVPRankInfo`'s **second argument** → the team digit, the engine's three-way dispatch
-/// (`0x51a98c` / `0x51a9af` / `0x51a9c8`, converging on `0x51a9ee mov ebx,eax`):
-///
-/// | argument | team |
-/// |---|---|
-/// | a **number** | the number itself, truncated toward zero — no unit is resolved at all |
-/// | a **string** | that unit token's [`team_of`], or **0** if the token names nothing or names a non-player |
-/// | absent / anything else | the local player's [`team_of`], or **0** if there is no player |
-///
-/// The 0 on the two "not found" edges is the team register's initial value, not a decision — so a
-/// rank asked for on a client with no player snapshot is named off the HORDE list. That is the
-/// engine's behaviour and it is deliberately reproduced; a unit that *is* found but has no side
-/// answers −1 instead, and −1 misses the key ([`team_of`]).
-///
-/// An unrecognised token raises `Unknown unit name`, as `0x515970` does for every unit binding.
+/// `GetPVPRankInfo`'s second argument as a team digit, the engine's three-way dispatch
+/// (`0x51a98c`/`0x51a9af`/`0x51a9c8`): a number is the digit itself, truncated; a string is that
+/// unit's [`team_of`], or 0 if it names nothing or a non-player; anything else is the local
+/// player's, or 0 with no player. That 0 is the team register's initial value, so a miss names
+/// off the Horde list, as in the reference. An unknown token raises, as `0x515970` does.
 fn team_arg(lua: &Lua, v: Value) -> mlua::Result<i64> {
     // `lua_isnumber` before `lua_isstring`, which is what puts a numeric string on the number arm.
     if let Some(n) = lua.coerce_number(v.clone())? {
         return Ok(i64::from(n as i64 as i32));
     }
     let Some(token) = lua.coerce_string(v)? else {
-        // Absent, boolean, table — the local-player preamble.
+        // Absent, boolean or table: the local player.
         let model = lua.app_data_ref::<Model>().expect("model app_data");
         return Ok(model.unit("player").map_or(0, team_of));
     };
@@ -398,35 +205,22 @@ fn team_arg(lua: &Lua, v: Value) -> mlua::Result<i64> {
     Ok(token
         .as_ref()
         .and_then(|t| model.unit(t))
-        // `0x51a9af`'s `shr edx,4; test dl,1` player gate. Applied here, unlike in `UnitPVPRank`
-        // (see there), because on this arm nothing else can tell a creature from a player: a
-        // creature carries a race byte and a faction template like anything else, and the two
-        // misses are different numbers anyway (this gate's 0 against `0x5efe00`'s −1) — it is
-        // this gate the engine reaches first. The cost is the mirror-image miss — an un-enriched player snapshot reads as a non-player — which
-        // lands on a different title rather than on none, and this arm is addon surface: neither
-        // pane passes a second argument at all.
+        // `0x51a9af`'s player gate (`shr edx,4; test dl,1`), applied here unlike in `UnitPVPRank`:
+        // on this arm nothing else tells a creature, which has a race too, from a player.
         .filter(|u| u.is_player)
         .map_or(0, team_of))
 }
 
-/// A rank's localized title, read out of the VM's own globals (see the module doc):
-/// `PVP_RANK_<internal>_<team>`, **ungendered** — `0x703bf0(key, -1, 0)`, the fast path that never
-/// enters Lua.
-///
-/// This is `GetPVPRankInfo`'s lookup (`0x51aa0f push 0`), and the reason the honor panes show a
-/// male/default title to a female character. Do not "fix" it; see the module doc's `_FEMALE`
-/// section.
+/// `PVP_RANK_<internal>_<team>`, ungendered: `GetPVPRankInfo`'s lookup, `0x703bf0(key, -1, 0)`
+/// (`0x51aa0f` pushes gender 0), so the panes show a female character the default title. Do not
+/// gender it: that would diverge from the reference.
 fn rank_title_ungendered(lua: &Lua, rank: i64, team: i64) -> Option<String> {
     global_string(lua, &format!("PVP_RANK_{rank}_{team}"))
 }
 
-/// The same title, **gendered** by the subject — `0x612bf0`: it hands the gender selector (2 male /
-/// 3 female) to `0x703bf0`, which routes into FrameXML's `GetText` and gets `_FEMALE` appended for
-/// 3, then **retries ungendered** when that misses (`0x612c2d`).
-///
-/// Two callers, both verified to be gendered: `UnitPVPName`'s decoration (by the *subject unit*)
-/// and [`UiScript::pvp_rank_title`], the app's `SMSG_PVP_CREDIT` line (by the *local player*, even
-/// though the team digit is the victim's — `0x625374`).
+/// The same title gendered, `0x612bf0`: it passes 2 (male) or 3 (female) to `0x703bf0`, which
+/// asks FrameXML's `GetText` to append `_FEMALE` for 3 (the engine never builds that key), and
+/// retries ungendered on a miss (`0x612c2d`). Used by `UnitPVPName` and the credit line.
 fn rank_title_gendered(lua: &Lua, rank: i64, team: i64, female: bool) -> Option<String> {
     female
         .then(|| global_string(lua, &format!("PVP_RANK_{rank}_{team}_FEMALE")))
@@ -434,14 +228,10 @@ fn rank_title_gendered(lua: &Lua, rank: i64, team: i64, female: bool) -> Option<
         .or_else(|| rank_title_ungendered(lua, rank, team))
 }
 
-/// Fill a **two-`%s` C format string** — the shape `snprintf(buf, size, GlobalString(...), a, b)`
-/// needs, and no more than that shape: the engine pushes exactly two varargs (`0x6093f2 add
-/// esp,0x14`), so any further specifier in a locale's template would read uninitialised stack
-/// there and is simply dropped here.
-///
-/// It substitutes rather than hardcoding `"{a} {b}"` because the template is *install data*: enUS
-/// ships `UNIT_PVP_NAME = "%s %s"`, and a locale that punctuates or spaces it differently must come
-/// out differently. `%%` is a literal `%`; anything else after a `%` is passed through untouched.
+/// Fill a two-`%s` C format string, the install's template (enUS `UNIT_PVP_NAME` is `"%s %s"`);
+/// `%%` is a literal `%` and any other specifier passes through. Deviation: a third `%s` gets an
+/// empty string, because the reference pushes two varargs (`0x6093f2 add esp,0x14`) and would
+/// read uninitialised stack.
 fn format_two_strings(fmt: &str, a: &str, b: &str) -> String {
     let mut out = String::with_capacity(fmt.len() + a.len() + b.len());
     let mut args = [a, b].into_iter();
@@ -464,10 +254,10 @@ fn format_two_strings(fmt: &str, a: &str, b: &str) -> String {
     out
 }
 
-/// `0x609370` — the name builder behind `UnitPVPName`, called with its flag set. `name` is the
-/// unit's plain `UnitName`; see the binding for the three legs and the two divergences.
+/// `0x609370`, the name builder behind `UnitPVPName` (its legs are at the binding); `name` is the
+/// plain `UnitName`.
 fn pvp_name(lua: &Lua, u: &super::UnitState, name: &str, player_level: u32) -> String {
-    // Leg A: a player with a rank. The title is gendered by THIS unit and range-unchecked.
+    // Leg A: a ranked player; the title is gendered by this unit and range-unchecked.
     if u.is_player && u.pvp_rank != 0 {
         let title = rank_title_gendered(lua, i64::from(u.pvp_rank), team_of(u), u.sex == 3);
         if let (Some(fmt), Some(title)) = (global_string(lua, "UNIT_PVP_NAME"), title) {
@@ -497,11 +287,8 @@ fn pvp_name(lua: &Lua, u: &super::UnitState, name: &str, player_level: u32) -> S
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // TogglePVP() — /pvp and the unit popup's PvP row. Takes no argument in 1.12: the *state*
-    // form of the opcode (a one-byte body) has no binding, so there is nothing to pass. The
-    // reference registers it at `0x48d700` and calls it from exactly one place in the whole
-    // shipped 1.12 UI: `SlashCmdList["PVP"]` (ChatFrame.lua); benilla's popup row is a deliberate
-    // second caller — decision 0646 §3.
+    // TogglePVP(): no argument in 1.12, as the opcode's one-byte state form has no binding.
+    // Registered at `0x48d700`; the shipped UI calls it only from `SlashCmdList["PVP"]`.
     g.set(
         "TogglePVP",
         lua.create_function(|lua, ()| {
@@ -512,10 +299,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── The self getters ─────────────────────────────────────────────────────────────────────
-    // Every one of them answers at full arity on every path, zeros included: the reference
-    // destructures the return straight into `format()` arguments, so a short return would leave a
-    // pane painting nils where the real client paints `0`. Before the first push (`None`) they
-    // therefore read as a zeroed snapshot — which is also exactly what a fresh character has.
+    // Full arity on every path: the panes destructure straight into `format()` arguments, so
+    // before the first push they read as a zeroed snapshot, as a new character's would.
 
     // GetPVPSessionStats() → hk, dk.
     g.set(
@@ -526,7 +311,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPVPYesterdayStats() → hk, dk, contribution (THREE — the weekly pair below is different).
+    // GetPVPYesterdayStats() → hk, dk, contribution.
     g.set(
         "GetPVPYesterdayStats",
         lua.create_function(|lua, ()| {
@@ -539,8 +324,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPVPThisWeekStats() → hk, contribution. **Two, not three**: the reference destructures
-    // `local hk, contribution = GetPVPThisWeekStats()` and shows no this-week DK column at all.
+    // GetPVPThisWeekStats() → hk, contribution: two, with no this-week dishonorable count.
     g.set(
         "GetPVPThisWeekStats",
         lua.create_function(|lua, ()| {
@@ -549,9 +333,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPVPLastWeekStats() → hk, dk, contribution, standing. **Four**: the fourth is
-    // `PLAYER_FIELD_LAST_WEEK_RANK`, which is the ladder STANDING, not a rank — the pane prints it
-    // through `format(PVP_RANK_LAST_WEEK, standing)` and never looks a title up for it.
+    // GetPVPLastWeekStats() → hk, dk, contribution, standing: the ladder standing, which the pane
+    // prints through `PVP_RANK_LAST_WEEK`, not a rank.
     g.set(
         "GetPVPLastWeekStats",
         lua.create_function(|lua, ()| {
@@ -565,15 +348,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPVPLifetimeStats() → hk, dk, highestRank. The third is the HIGHEST LIFETIME rank
-    // (`PLAYER_FIELD_BYTES` byte 3), internal scale — not the current one `UnitPVPRank` answers.
-    //
-    // **A highest rank below 5 is reported as 0, not as itself** (`0x51a843 cmp al,5; jb`,
-    // UNSIGNED, falling into the same `0.0` push the absent-player tail uses). Ranks 1..4 are the
-    // dishonorable titles, and this is why the reference pane shows NONE for a character whose
-    // best was one of them: the suppression is here, in the binding, not in the pane's Lua.
-    // Suppressed to 0 — not to nil — so the pane's `GetPVPRankInfo(highestRank)` still gets a
-    // number.
+    // GetPVPLifetimeStats() → hk, dk, highestRank, the highest lifetime rank (internal). One
+    // below 5 answers 0 (`0x51a843 cmp al,5; jb`, unsigned), so the pane shows NONE for a
+    // dishonorable best; 0, not nil, so its `GetPVPRankInfo(highestRank)` still gets a number.
     g.set(
         "GetPVPLifetimeStats",
         lua.create_function(|lua, ()| {
@@ -591,37 +368,17 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPVPRankProgress() → the bar fraction. A multiply, and unclamped — see `rank_progress`,
-    // which is the whole law of this binding. Absent player → `0.0`, still one value.
+    // GetPVPRankProgress() → the bar fraction (`rank_progress`), 0.0 before the first push.
     g.set(
         "GetPVPRankProgress",
         lua.create_function(|lua, ()| Ok(rank_progress(honor(lua).unwrap_or_default().rank_bar)))?,
     )?;
 
-    // GetPVPRankInfo(rank [, unit]) → rankName, rankNumber — the title off the VM's globals
-    // (module doc) and the VISUAL rank. **Always two values**: every failure edge answers
-    // `nil, 0`, and that nil is what both reference panes branch on to substitute the `NONE`
-    // GlobalString. The first argument is the INTERNAL rank, which is what `UnitPVPRank` and the
-    // `*LifetimeStats`/`InspectHonorData` rank returns all carry.
-    //
-    // Three things the name gives no hint of, all `0x51a930`:
-    //
-    //  * **The accepted range is [1, 18], SIGNED** (`0x51a9f0 cmp edi,1; jl` / `0x51a9f5 cmp
-    //    edi,0x12; jg`). Rank 0 fails it, and so does **rank 19** — the racial-leader "Leader",
-    //    whose `PVP_RANK_19_*` GlobalStrings exist and which the server really does send in
-    //    `SMSG_PVP_CREDIT`. The pane simply cannot name it. That rejection is why the engine's own
-    //    badge table has fifteen entries while FrameXML only ever indexes fourteen: rank 19 →
-    //    `PvPRank15` is reachable from the world-text kill toast (`0x6c7f10`, badge index
-    //    `rank − 5`) and from nowhere on this path.
-    //  * **The second argument exists**, and it is a three-way dispatch, not a unit token: a
-    //    NUMBER is the team digit itself (no unit resolution at all), a STRING is a unit token, and
-    //    absent-or-anything-else means the local player. Lua's own `isnumber` accepts a numeric
-    //    string, so `"1"` takes the number arm and `"player"` the token arm — `coerce_number`
-    //    first is that same order.
-    //  * **A team the engine cannot resolve is 0, not a failure.** An unresolvable token, a
-    //    non-player unit, or no local player leaves the team register at its initial 0 — the HORDE
-    //    list — while a unit that resolves but has no *side* gets −1 and misses the key. The two
-    //    are different answers and this reproduces both.
+    // GetPVPRankInfo(rank [, unit]) → rankName, rankNumber: the title and the visual rank for an
+    // internal rank, always two values; every failure answers `nil, 0`, which both panes turn
+    // into `NONE`. `0x51a930` accepts [1, 18], signed (`0x51a9f0`/`0x51a9f5`), so rank 19,
+    // "Leader", is refused although its GlobalStrings exist and the server sends it. The second
+    // argument is `team_arg`'s three-way dispatch.
     g.set(
         "GetPVPRankInfo",
         lua.create_function(|lua, (rank, unit): (Value, Value)| {
@@ -647,28 +404,14 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitPVPRank(unit) → the unit's CURRENT rank, internal scale, 0 for no rank.
+    // UnitPVPRank(unit) → the unit's current rank, internal, 0 for none. `0x51a8a0` reads the
+    // named object's own byte (`[+0xe68]+0x1f`, in public `PLAYER_BYTES_3`), which is how the
+    // inspect pane reads a foreign rank. Anything unresolved reads 0, never nil (`0x51a916`); a
+    // non-string argument raises (`0x51a8ac`).
     //
-    // It answers for a FOREIGN unit on purpose: `0x51a8a0` resolves the named token and reads
-    // **that object's own** `[+0xe68]+0x1f` — no cache, no local-player special case — and the byte
-    // lives in `PLAYER_BYTES_3`, a PUBLIC descriptor field the server streams to every observer.
-    // That is why the reference's inspect pane can call `UnitPVPRank("target")` at all, and why a
-    // foreign rank never comes from the inspect reply.
-    //
-    // A creature, a non-player, and an unresolvable token all read **0 — a number, never nil**
-    // (`0x51a916`), so a genuine rank-0 player and an unknown token are indistinguishable to
-    // script. A **non-string argument raises** (`0x51a8ac`), which is why this takes its token
-    // through `string_arg` rather than an `Option`: `UnitPVPRank()` abandons the caller's
-    // statement, it does not answer 0.
-    //
-    // **The engine's player gate (`0x51a8e1 shr edx,4; test dl,1`) is deliberately NOT re-applied
-    // here**, and the reason is a real one rather than laziness: the engine gates on the object's
-    // TYPE MASK, and our nearest equivalent — `UnitState::is_player` — is not that. It is filled by
-    // the app's *guid-keyed enrichment* step, one hop after the descriptor snapshot the rank byte
-    // itself rides on, so a snapshot pushed without enrichment would read as a non-player and
-    // silently zero a real player's rank in a pane that repaints every event. The creature case
-    // needs no gate anyway: a creature has no PLAYER descriptor block, so the byte the app decodes
-    // is already 0 — the reference's own answer for one, by its own path.
+    // The engine's player gate (`0x51a8e1`) is not re-applied: it tests the type mask, while our
+    // `is_player` comes from the app's later guid-keyed enrichment, so a snapshot pushed before
+    // it would zero a real player's rank. A creature has no player block, so its byte is 0.
     g.set(
         "UnitPVPRank",
         lua.create_function(|lua, token: Value| {
@@ -682,31 +425,20 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitPVPName(unit) → the unit's name, rank-title-decorated — `0x5172b0` into the builder
-    // `0x609370`, whose three legs are:
+    // UnitPVPName(unit) → the name decorated by rank, `0x5172b0` into the builder `0x609370`:
+    //   A  a ranked player: `UNIT_PVP_NAME` filled title first, then name; the title is gendered
+    //      by this unit (`0x5efe60`, `0x612bf0`) with no range check, so rank 19 renders "Leader".
+    //   A′ and, if `PLAYER_BYTES_3` byte 2 (the city-protector title) is set, a second line with
+    //      `PVP_MEDAL<n>`, ungendered.
+    //   B  else a unit passing the civilian predicate (`0x612550`): `PVP_RANK_CIVILIAN`, a space
+    //      and the name. Only creatures reach it.
+    //   C  else the plain name.
+    // No snapshot or an unresolved name answers nil, and so does a token resolving to guid 0,
+    // where the reference returns one value it never pushed (`0x517343`).
     //
-    //   A  a PLAYER with a non-zero rank byte → snprintf(GlobalString("UNIT_PVP_NAME"),
-    //      rankName, plainName). The `add esp,0x14` at `0x6093f2` proves exactly two varargs, and
-    //      the shipped template is "%s %s" — RANK FIRST. The title is `0x5efe60` → `0x612bf0`, so
-    //      it is GENDERED by this unit (unlike the pane's, module doc) and has NO range check, so
-    //      a rank-19 racial leader really does render as "Leader Whoever".
-    //   A′ …and if PLAYER_BYTES_3 byte 2 (the city-protector title) is non-zero, a second line:
-    //      "\n" + GlobalString("PVP_MEDAL<n>"), ungendered.
-    //   B  otherwise, a unit that passes the CIVILIAN predicate `0x612550` →
-    //      GlobalString("PVP_RANK_CIVILIAN") + " " + plainName. Reached by creatures: leg A takes
-    //      every ranked player first, and our snapshot only ever flags creatures civilian.
-    //   C  otherwise the plain name.
-    //
-    // Two edges answer **nil**: no snapshot for the token, and a snapshot whose name has not
-    // resolved. The engine distinguishes a third — a token resolving to GUID 0 returns one value
-    // having pushed nothing (`0x517343`), i.e. non-nil and unspecified. That is an INFERRED
-    // reading of a `luaD_poscall` detail, not a fact about this function, and reproducing an
-    // unspecified value is not something a client can honestly do: we answer nil there too.
-    //
-    // The no-install divergence, stated rather than hidden: with `UNIT_PVP_NAME` or the rank title
-    // missing from `_G`, the engine would snprintf through an empty format and hand back an empty
-    // string. We answer the plain name instead — the decoration is install data, and without the
-    // data there is no decoration.
+    // Deviation: with `UNIT_PVP_NAME` or the title missing from `_G` (no install) this answers
+    // the plain name, where the reference would format an empty string, because the decoration
+    // is install data.
     g.set(
         "UnitPVPName",
         lua.create_function(|lua, token: Value| {
@@ -732,26 +464,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 
     // ── The inspect half ─────────────────────────────────────────────────────────────────────
 
-    // RequestInspectHonorData() — the reference's `InspectHonorFrame_OnShow` calls it iff
-    // `HasInspectHonorData()` is false. Queues the intent; the app pairs it with the guid it is
-    // already inspecting and sends `MSG_INSPECT_HONOR_STATS` (see `NotifyInspect`, which is the
-    // same shape with a token to carry). Zero Lua return values on every path (`0x4c9610`).
+    // RequestInspectHonorData(): `InspectHonorFrame_OnShow` calls it while
+    // `HasInspectHonorData()` is false; the app sends `MSG_INSPECT_HONOR_STATS` for its inspect
+    // target. Zero return values (`0x4c9610`).
     //
-    // **`0x4c80a0` has three silent gates**, and they are the binding's, not the pane's: bail if
-    // data is already held (`0x4c80a6`), bail if a query is already in flight (`0x4c80b6`), bail
-    // if the target guid is zero (`0x4c80c2`). Two of the three are ours to keep:
-    //
-    //  * `hasData` — modelled here even though the reference's own `OnShow` tests it first,
-    //    because it is the engine that refuses; a pane (or addon) that asks anyway must get the
-    //    engine's silence, not a second query.
-    //  * `pending` — modelled here, and this is the one that earns its keep: it is what stops a
-    //    pane shown/hidden/shown before the reply lands sending duplicates.
-    //  * the guid — **not** modelled here and it cannot be: this crate never sees a guid
-    //    (decision 0068 §3). The app drops a queued request with no inspect target, which is the
-    //    same outcome one seam further out. The cost is that our `pending` latches on *queue*
-    //    where the engine's latches on *send*, so a request the app drops leaves the latch set
-    //    until the next `set_inspect_honor` — which the app's own `ClearInspectPlayer` path
-    //    calls, exactly as `0x4c6f70` clears the engine's.
+    // `0x4c80a0` bails silently if data is held (`0x4c80a6`), if a query is in flight (`pending`,
+    // `0x4c80b6`, `[0xb71fcc]`) or if the target guid is 0 (`0x4c80c2`). The first two are here;
+    // the guid is the app's, which drops a request with no target. Our `pending` latches on
+    // queue, not send, so a dropped request holds it until the next `set_inspect_honor`, which
+    // `ClearInspectPlayer` calls as `0x4c6f70` clears the engine's.
     g.set(
         "RequestInspectHonorData",
         lua.create_function(|lua, ()| {
@@ -765,9 +486,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // HasInspectHonorData() → 1/nil. The latch the request above is gated on: true exactly while a
-    // reply is held, so dropping the inspected player (which clears the push) makes the next
-    // `OnShow` re-request instead of repainting the last player's numbers.
+    // HasInspectHonorData() → 1 or nil: whether a reply is held.
     g.set(
         "HasInspectHonorData",
         lua.create_function(|lua, ()| {
@@ -779,19 +498,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInspectHonorData() → the reference's twelve, in its own order:
+    // GetInspectHonorData() → the reference's twelve, in its order:
     //   sessionHK, sessionDK, yesterdayHK, yesterdayHonor, thisweekHK, thisweekHonor,
     //   lastweekHK, lastweekHonor, lastweekStanding, lifetimeHK, lifetimeDK, lifetimeRank
-    // Note there is no per-period DK past the session pair — the reply carries yesterday/last
-    // week/this week DK halves (vmangos's `unknownOld1/2/3`) and the client surfaces none of them.
-    //
-    // **Twelve on every path, zeros included.** `0x4c9620` is UNGATED — it never consults the
-    // has-data flag; it reads sixteen zero-initialised BSS globals, so a client with no reply held
-    // answers twelve zeros, not nils and not a short return. (The engine's slots are also never
-    // *cleared*: re-keying the cache zeroes the two flags and leaves the data, so the real client
-    // can answer a previous target's numbers here while `HasInspectHonorData` says no. We cannot —
-    // our data and our latch are one `Option` — and that is the one place this pair diverges: it
-    // needs the app to own the flag separately, which is a seam change, not a fix here.)
+    // Twelve on every path: `0x4c9620` never checks for data and reads zero-initialised slots.
+    // Clearing drops the data here, while the reference's re-key zeroes only the flags and can
+    // still answer the previous target's numbers; matching that needs a latch apart from the data.
     g.set(
         "GetInspectHonorData",
         lua.create_function(|lua, ()| {
@@ -815,11 +527,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInspectPVPRankProgress() → the same bar fraction as GetPVPRankProgress, off the reply's
-    // trailing `rankBar` byte. `0x51ab00` is the same three-instruction kernel over the cached
-    // byte — the `fild`/`fmul ds:0x8026c8`/`fstp` at `0x51ab04` is byte-identical to `0x51aace` —
-    // with no object lookup, no gate and no clamp, so it too reads 0.0 from an empty slot rather
-    // than nil ([`rank_progress`]).
+    // GetInspectPVPRankProgress() → the reply's `rankBar` through `rank_progress`: `0x51ab00`'s
+    // kernel at `0x51ab04` is byte-identical to `0x51aace`, so it too reads 0.0 when empty.
     g.set(
         "GetInspectPVPRankProgress",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/pvp/tests.rs b/crates/benilla-ui/src/script/pvp/tests.rs
index 433826c0..3d71138c 100644
--- a/crates/benilla-ui/src/script/pvp/tests.rs
+++ b/crates/benilla-ui/src/script/pvp/tests.rs
@@ -1,16 +1,11 @@
-//! The PvP + honor binding tests (the parent module is the unit under test).
-//!
-//! Several of these pin facts that look like bugs — the multiply-not-divide rank bar, the
-//! backwards negative visual ranks, rank 19's rejection, the ungendered pane title, the suppressed
-//! sub-5 lifetime rank. Each is verified at the bytes, and each one would pass just as happily
-//! against the wrong reading if it were written loosely, so they are written tightly on purpose.
+//! Tests for the PvP and honor bindings. Several pin reference facts that look like bugs, so each
+//! is written to fail against the natural reading.
 
 use super::*;
 use crate::script::{UiScript, UnitState};
 
-/// A snapshot whose every number is distinct, so a swapped return order cannot pass: the tens
-/// digit is the block (session 1x, yesterday 2x, this week 3x, last week 4x, lifetime 5x) and
-/// the units digit is the position within it.
+/// Every number distinct, so a swapped return cannot pass: the tens digit is the block (session
+/// 1x to lifetime 5x), the units digit the position in it.
 fn honor_state() -> HonorState {
     HonorState {
         session_hk: 11,
@@ -28,14 +23,13 @@ fn honor_state() -> HonorState {
         lifetime_dk: 52,
         highest_rank: 11,
         rank: 9,
-        // 51 is 0.2 of 255 exactly — which the engine's multiply does NOT produce, and that
-        // near-miss is the whole point of the byte chosen here.
+        // 51/255 is exactly 0.2, which the engine's multiply does not produce.
         rank_bar: 51,
     }
 }
 
-/// The inspect reply's twelve, same trick: 6x is the session block, then one number per return
-/// so the ninth (the standing) cannot hide behind the eighth.
+/// The inspect reply's twelve, distinct in return order, so the ninth (the standing) cannot hide
+/// behind the eighth.
 fn inspect_state() -> InspectHonorData {
     InspectHonorData {
         guid: 0xDEAD_BEEF,
@@ -55,18 +49,15 @@ fn inspect_state() -> InspectHonorData {
     }
 }
 
-/// A female Alliance player carrying rank 9 (visual 5) — the snapshot `UnitPVPRank("player")`
-/// and every title lookup read.
+/// A female Alliance player at rank 9 (visual 5).
 fn player() -> UnitState {
     UnitState {
         exists: true,
         name: Some("Benilla".into()),
         sex: 3, // female
         is_player: true,
-        // Both, because a real Alliance player has both — and they are not the same field.
-        // `faction_group` is `UnitFactionGroup`'s live faction template; `pvp_team` is
-        // `0x5efe00`'s race walk, which is what every rank title is keyed by. The GM-mode test
-        // below is the one that drives them apart.
+        // Both, and they differ: `faction_group` is the live faction template, `pvp_team` the
+        // race walk (`0x5efe00`) that keys every rank title.
         faction_group: Some("Alliance".into()),
         pvp_team: 1,
         pvp_rank: 9,
@@ -81,12 +72,8 @@ fn seated() -> UiScript {
     s
 }
 
-/// Install the rank titles the real `GlobalStrings.lua` puts on `_G` at boot — the only place
-/// `GetPVPRankInfo` reads names from (see the module doc). Both teams, one female twin, the
-/// dishonorable end and rank 19, so the key construction is pinned rather than assumed.
-///
-/// Rank **17** is deliberately left unseated: it is the "the key exists in no locale" case the nil
-/// tests need, now that 19 is a real title here.
+/// The rank titles `GlobalStrings.lua` puts on `_G`: both teams, one female twin, the dishonorable
+/// end and rank 19. Rank 17 is left out as the key no locale has.
 fn seat_rank_globals(s: &UiScript) {
     let g = s.lua().globals();
     for (key, value) in [
@@ -98,7 +85,6 @@ fn seat_rank_globals(s: &UiScript) {
         ("PVP_RANK_9_1", "Sergeant Major"),
         ("PVP_RANK_9_1_FEMALE", "Sergeant Major (f)"),
         ("PVP_RANK_18_1", "Grand Marshal"),
-        // The racial-leader rank: a real GlobalString the pane's binding still refuses.
         ("PVP_RANK_19_1", "Leader"),
         ("PVP_RANK_19_1_FEMALE", "Leader (f)"),
     ] {
@@ -106,8 +92,7 @@ fn seat_rank_globals(s: &UiScript) {
     }
 }
 
-/// The GlobalStrings `UnitPVPName`'s decoration reads — the enUS templates, which is what makes
-/// the two-`%s` substitution testable at all (see [`format_two_strings`]).
+/// The enUS GlobalStrings `UnitPVPName`'s decoration reads.
 fn seat_name_globals(s: &UiScript) {
     let g = s.lua().globals();
     for (key, value) in [
@@ -119,10 +104,7 @@ fn seat_name_globals(s: &UiScript) {
     }
 }
 
-/// **The reference's own destructuring**, line for line — the highest-value assertion
-/// available, because it is the exact code `HonorFrame.lua` runs. Four from last week, three
-/// from yesterday, two from this week: the arities are not symmetric and getting one wrong
-/// shifts a whole pane by a column.
+/// `HonorFrame.lua`'s own destructuring, line for line; the arities differ per period.
 #[test]
 fn the_reference_destructuring_lands_every_value_in_the_right_slot() {
     let s = seated();
@@ -164,10 +146,7 @@ fn the_reference_destructuring_lands_every_value_in_the_right_slot() {
     );
 }
 
-/// **`GetPVPLifetimeStats` suppresses a highest-lifetime rank below 5** (`0x51a843 cmp al,5; jb`),
-/// reporting `0` instead of the true byte — which is why the reference pane shows NONE for a
-/// character whose best rank was one of the four dishonorable ones. The boundary is the whole test:
-/// 4 vanishes, 5 survives.
+/// `0x51a843 cmp al,5; jb`: 4 vanishes, 5 survives.
 #[test]
 fn a_lifetime_rank_below_five_is_reported_as_zero() {
     let mut s = seated();
@@ -183,8 +162,7 @@ fn a_lifetime_rank_below_five_is_reported_as_zero() {
         assert_eq!(third(&s), reported, "highest lifetime rank {highest}");
     }
 
-    // Suppressed to a NUMBER, not to nil: the pane feeds it straight to `GetPVPRankInfo`, which
-    // raises on a non-number.
+    // A number, not nil: the pane passes it to `GetPVPRankInfo`, which raises on a non-number.
     s.set_honor(Some(HonorState {
         highest_rank: 3,
         ..honor_state()
@@ -197,8 +175,7 @@ fn a_lifetime_rank_below_five_is_reported_as_zero() {
         .unwrap());
 }
 
-/// Arity, measured at the host boundary ([`UiScript::arity`]). A getter that returned one value
-/// too many would still pass the destructuring test above; the count is what catches it.
+/// A getter returning one value too many passes the destructuring test; the count catches it.
 #[test]
 fn every_getter_returns_exactly_the_reference_arity() {
     let s = seated();
@@ -217,8 +194,7 @@ fn every_getter_returns_exactly_the_reference_arity() {
     }
 }
 
-/// Before the first push every self getter still answers at full width, with zeros — the
-/// reference feeds these straight into `format()`, so a nil would raise inside its pane.
+/// The reference feeds these straight into `format()`, where a nil would raise.
 #[test]
 fn the_self_getters_answer_zeroed_before_the_first_push() {
     let s = UiScript::new().expect("VM");
@@ -230,22 +206,17 @@ fn the_self_getters_answer_zeroed_before_the_first_push() {
     assert_eq!(s.eval::<f64>("return GetPVPRankProgress()").unwrap(), 0.0);
 }
 
-/// **The rank bar is a MULTIPLY by a slightly-wrong f32 reciprocal, and it does not clamp.**
-///
-/// Written to fail against the natural `byte / 255.0` reading rather than to describe the shape:
-/// the constant is asserted at its bits, every byte is compared to the exact product, and the two
-/// values a divisor would round prettier (51 → 0.2, 255 → 1.0) are asserted **not** to be those
-/// numbers. A full bar comes out *above* 1.0, which is the clamp's absence made visible.
+/// Written to fail against `byte / 255.0`: the constant is checked at its bits, and 51 and 255
+/// must not land on 0.2 and 1.0.
 #[test]
 fn the_rank_bar_multiplies_by_the_f32_reciprocal_and_never_clamps() {
-    // The four bytes at `0x8026c8`, and the fact that makes this test necessary at all.
+    // The four bytes at `0x8026c8`.
     assert_eq!(f64::from(f32::from_bits(0x3B80_8081)), RANK_BAR_SCALE);
     assert_ne!(RANK_BAR_SCALE, 1.0 / 255.0, "the f32 is NOT 1/255");
 
     let mut s = seated();
     let bar = |s: &UiScript| s.eval::<f64>("return GetPVPRankProgress()").unwrap();
 
-    // 51 is the fixture's byte, and 51/255 would be exactly 0.2. The multiply is not.
     assert_eq!(bar(&s), 51.0 * RANK_BAR_SCALE);
     assert_ne!(bar(&s), 0.2, "a divisor would land exactly on 0.2");
     assert_ne!(bar(&s), 51.0 / 255.0);
@@ -258,8 +229,6 @@ fn the_rank_bar_multiplies_by_the_f32_reciprocal_and_never_clamps() {
         assert_eq!(bar(&s), f64::from(byte) * RANK_BAR_SCALE, "byte {byte}");
     }
 
-    // The ends. Zero is the one input the two readings agree on; a full bar OVERSHOOTS, and
-    // nothing clamps it back.
     s.set_honor(Some(HonorState {
         rank_bar: 0,
         ..honor_state()
@@ -280,9 +249,7 @@ fn the_rank_bar_multiplies_by_the_f32_reciprocal_and_never_clamps() {
     );
 }
 
-/// **Rank 0 names nothing.** There is no `PVP_RANK_0_*` GlobalString, and both reference panes
-/// depend on that nil to fall back to `NONE` — so this runs the fallback the way the pane
-/// writes it, not just the nil.
+/// Runs the panes' own `NONE` fallback, not just the nil.
 #[test]
 fn rank_zero_names_nothing_and_the_pane_falls_back_to_none() {
     let s = seated();
@@ -304,19 +271,13 @@ fn rank_zero_names_nothing_and_the_pane_falls_back_to_none() {
     );
 }
 
-/// The title key: the team digit (0 Horde / 1 Alliance) off the player's faction group — and
-/// **the pane's title is NOT gendered**, which is the half a plausible implementation gets wrong.
-///
-/// `GetPVPRankInfo` hands `0x703bf0` gender 0 (`0x51aa0f`) and takes the fast path, so a female
-/// character sees the male/default title in her own honor pane while the `_FEMALE` twin sits right
-/// there on `_G`. The seated player is female and a twin exists for rank 9 precisely so that this
-/// test fails the moment somebody "fixes" the resolver to prefer it.
+/// `GetPVPRankInfo` passes gender 0 (`0x51aa0f`), so a female character gets the default title
+/// with the `_FEMALE` twin right there on `_G`.
 #[test]
 fn the_pane_title_is_keyed_by_team_and_is_never_gendered() {
     let mut s = seated();
     seat_rank_globals(&s);
 
-    // Female Alliance → the BASE key, with `PVP_RANK_9_1_FEMALE` seated and ignored.
     assert_eq!(
         s.eval::<String>("return (GetPVPRankInfo(9))").unwrap(),
         "Sergeant Major"
@@ -327,15 +288,12 @@ fn the_pane_title_is_keyed_by_team_and_is_never_gendered() {
         "the twin is on _G — the binding declines it, it does not miss it"
     );
 
-    // Male Alliance → the same answer, which is the point.
     s.set_unit("player", Some(UnitState { sex: 2, ..player() }));
     assert_eq!(
         s.eval::<String>("return (GetPVPRankInfo(9))").unwrap(),
         "Sergeant Major"
     );
 
-    // Horde is team 0 — an entirely different word list, which is why an unknown side must
-    // not be guessed at.
     s.set_unit(
         "player",
         Some(UnitState {
@@ -351,21 +309,13 @@ fn the_pane_title_is_keyed_by_team_and_is_never_gendered() {
     );
 }
 
-/// The **Rust-side** title lookup the app's `SMSG_PVP_CREDIT` line uses shares the key
-/// construction with the binding and **deliberately differs on gender**: the credit formatter
-/// resolves through `0x612bf0` with the local player's gender selector, the pane's binding passes
-/// 0. One function each, and the pair of them is asserted apart here so neither drifts into the
-/// other.
-///
-/// The credit packet carries the INTERNAL rank, which is why its number goes straight in with no
-/// visual conversion — and unlike the binding this path applies **no range check**, so rank 19
-/// names "Leader" here and `(nil, 0)` there.
+/// The credit line's lookup resolves through `0x612bf0` with the local player's gender, where the
+/// binding passes 0, and has no range check, so rank 19 names "Leader" here.
 #[test]
 fn the_rust_side_title_lookup_is_gendered_where_the_binding_is_not() {
     let s = seated();
     seat_rank_globals(&s);
 
-    // The app names a side and a sex outright — no player snapshot involved.
     assert_eq!(
         s.pvp_rank_title(9, 0, false).as_deref(),
         Some("Senior Sergeant")
@@ -388,15 +338,13 @@ fn the_rust_side_title_lookup_is_gendered_where_the_binding_is_not() {
         "same key construction once the gender is out of it"
     );
 
-    // Gendered means PREFERRED, not required: a rank with no twin falls back to the base key.
+    // Gendered means preferred: a rank with no twin falls back to the base key.
     assert_eq!(s.pvp_rank_title(5, 1, true).as_deref(), Some("Private"));
 
-    // No range check on this path — rank 19 is a name here and a refusal in the binding.
     assert_eq!(s.pvp_rank_title(19, 1, false).as_deref(), Some("Leader"));
     assert_eq!(s.pvp_rank_title(19, 1, true).as_deref(), Some("Leader (f)"));
     assert!(s.eval::<bool>("return GetPVPRankInfo(19) == nil").unwrap());
 
-    // Same nil semantics either side: rank 0, an absent key, and an empty one.
     assert_eq!(s.pvp_rank_title(0, 1, false), None);
     assert_eq!(s.pvp_rank_title(17, 1, false), None, "no PVP_RANK_17_1");
     s.lua().globals().set("PVP_RANK_17_1", "").expect("global");
@@ -407,14 +355,11 @@ fn the_rust_side_title_lookup_is_gendered_where_the_binding_is_not() {
     );
 }
 
-/// A missing GlobalString — the bare VM with no install behind it — reads as **nil**, never as
-/// an empty string and never as a raise: the panes' `if not rankName` fallback is the only
-/// thing standing between that and a blank title.
+/// The panes' `if not rankName` fallback needs a nil, not an empty string or a raise.
 #[test]
 fn a_missing_rank_global_reads_nil_not_empty() {
     let s = seated(); // no rank globals seated at all
     assert!(s.eval::<bool>("return GetPVPRankInfo(9) == nil").unwrap());
-    // …and so does an empty one.
     s.lua().globals().set("PVP_RANK_9_1", "").expect("global");
     assert!(s.eval::<bool>("return GetPVPRankInfo(9) == nil").unwrap());
     // A player with no side names nothing either, rather than picking a list.
@@ -430,12 +375,9 @@ fn a_missing_rank_global_reads_nil_not_empty() {
     assert!(s.eval::<bool>("return GetPVPRankInfo(9) == nil").unwrap());
 }
 
-/// **The team digit is NOT the faction group** — report B378 at the binding level (decision 2227).
-///
-/// `UnitFactionGroup` reads the unit's live `UNIT_FIELD_FACTIONTEMPLATE` (`0x516630`) and the rank
-/// title's team digit reads the unit's RACE (`0x5efe00`), so a vmangos GM — template 35, group
-/// mask 0 — has no side and keeps his rank. Both `0x5efe00` surfaces are asserted here: the
-/// binding's key and `UnitPVPName`'s decoration (`0x5efe60`, the same walk).
+/// `UnitFactionGroup` reads the live faction template (`0x516630`) and the title's team digit the
+/// race (`0x5efe00`), so a vmangos GM (template 35, no side) keeps his title, in both the key and
+/// `UnitPVPName`'s decoration (`0x5efe60`).
 #[test]
 fn a_sideless_player_still_has_a_team_digit_because_his_race_has_one() {
     let mut s = seated();
@@ -447,10 +389,10 @@ fn a_sideless_player_still_has_a_team_digit_because_his_race_has_one() {
     s.set_unit(
         "player",
         Some(UnitState {
-            // `.gm on` — the template names nothing …
+            // `.gm on`: the template names nothing…
             faction_group: None,
             faction_group_localized: None,
-            // … and the race still names Alliance.
+            // …and the race still names Alliance.
             pvp_team: 1,
             sex: 2,
             pvp_rank: 18,
@@ -467,7 +409,7 @@ fn a_sideless_player_still_has_a_team_digit_because_his_race_has_one() {
         "Grand Marshal Benilla",
         "and the name decoration reads the same digit"
     );
-    // The control: a unit whose RACE resolves to nothing is still −1, and −1 still misses.
+    // The control: a unit whose race has no side is -1, and -1 misses.
     s.set_unit(
         "player",
         Some(UnitState {
@@ -483,11 +425,8 @@ fn a_sideless_player_still_has_a_team_digit_because_his_race_has_one() {
     );
 }
 
-/// The internal→visual conversion across its whole range — **and the negative half runs the
-/// opposite way from the server's `visualRank`**, which is the assertion that matters: rank 1 is
-/// −4 and rank 4 is −1, because `0x51aa38` subtracts 5 rather than negating. vmangos's
-/// `HonorMgr.cpp:991` gives 1 → −1 and 4 → −4; the binding's second return is the client's, and
-/// this pins it so nobody restores the server's arithmetic here.
+/// `0x51aa38` subtracts 5 rather than negating, so rank 1 is -4 and rank 4 is -1, the opposite of
+/// vmangos's `visualRank` (`HonorMgr.cpp:991`).
 #[test]
 fn the_visual_rank_arithmetic_runs_backwards_through_the_dishonorable_ranks() {
     for (internal, visual) in [
@@ -500,7 +439,7 @@ fn the_visual_rank_arithmetic_runs_backwards_through_the_dishonorable_ranks() {
         (18, 14),
     ] {
         assert_eq!(visual_rank(internal), visual, "internal {internal}");
-        // The server's form, stated as the thing this is NOT.
+        // The server's form, which this is not.
         let servers = if internal > 4 {
             internal - 4
         } else {
@@ -513,8 +452,6 @@ fn the_visual_rank_arithmetic_runs_backwards_through_the_dishonorable_ranks() {
         );
     }
 
-    // …and the binding reports the same number, which is what indexes the badge texture: only a
-    // positive one is drawn, so all four dishonorable ranks hide it.
     let s = seated();
     seat_rank_globals(&s);
     for (internal, visual) in [(1i64, -4i64), (4, -1), (5, 1), (18, 14)] {
@@ -529,14 +466,7 @@ fn the_visual_rank_arithmetic_runs_backwards_through_the_dishonorable_ranks() {
     }
 }
 
-/// **The range gate is `[1, 18]`, so rank 19 — "Leader" — is refused**, GlobalString and all.
-///
-/// The consequence is real and visible: the engine's own badge table has fifteen entries because
-/// rank 19 → `PvPRank15` is reachable from the world-text kill toast (`0x6c7f10`, index
-/// `rank − 5`), never from this binding, which is why FrameXML only ever names fourteen.
-///
-/// Both failure edges answer `(nil, 0)` — **two** values, never one — because the panes destructure
-/// a pair and then branch on the nil.
+/// Both failure edges answer two values, `(nil, 0)`, since the panes destructure a pair.
 #[test]
 fn the_range_gate_refuses_rank_zero_and_rank_nineteen_alike() {
     let s = seated();
@@ -557,19 +487,15 @@ fn the_range_gate_refuses_rank_zero_and_rank_nineteen_alike() {
         );
     }
 
-    // The refusal is the GATE, not a missing key: `PVP_RANK_19_1` is right there.
+    // The refusal is the gate, not a missing key: `PVP_RANK_19_1` is seated.
     assert_eq!(s.eval::<String>("return PVP_RANK_19_1").unwrap(), "Leader");
-    // …and the ends of the accepted range do answer.
     assert!(s.eval::<bool>("return GetPVPRankInfo(1) ~= nil").unwrap());
     assert!(s.eval::<bool>("return GetPVPRankInfo(18) ~= nil").unwrap());
 }
 
-/// **The second argument**, which the reference's own panes never pass and which is therefore easy
-/// to miss entirely: a NUMBER is the team digit itself, a STRING is a unit token, and absent means
-/// the local player.
 #[test]
 fn get_pvp_rank_info_takes_a_second_argument_three_different_ways() {
-    let mut s = seated(); // an ALLIANCE player
+    let mut s = seated(); // an Alliance player
     seat_rank_globals(&s);
     s.set_unit(
         "target",
@@ -584,12 +510,12 @@ fn get_pvp_rank_info_takes_a_second_argument_three_different_ways() {
         }),
     );
 
-    // Absent → the local player's side.
+    // Absent: the local player's side.
     assert_eq!(
         s.eval::<String>("return (GetPVPRankInfo(9))").unwrap(),
         "Sergeant Major"
     );
-    // A NUMBER is the digit, with no unit resolved at all — including a digit the player is not.
+    // A number is the digit, with no unit resolved, even one the player is not.
     assert_eq!(
         s.eval::<String>("return (GetPVPRankInfo(9, 0))").unwrap(),
         "Senior Sergeant"
@@ -598,7 +524,7 @@ fn get_pvp_rank_info_takes_a_second_argument_three_different_ways() {
         s.eval::<String>("return (GetPVPRankInfo(9, 1))").unwrap(),
         "Sergeant Major"
     );
-    // Lua's `isnumber` accepts a numeric string, so "0" is a DIGIT and not a token.
+    // `lua_isnumber` accepts a numeric string, so "0" is a digit, not a token.
     assert_eq!(
         s.eval::<String>(r#"return (GetPVPRankInfo(9, "0"))"#)
             .unwrap(),
@@ -609,12 +535,11 @@ fn get_pvp_rank_info_takes_a_second_argument_three_different_ways() {
         s.eval::<String>("return (GetPVPRankInfo(9, 0.9))").unwrap(),
         "Senior Sergeant"
     );
-    // A team digit no GlobalString matches simply misses.
     assert!(s
         .eval::<bool>("return GetPVPRankInfo(9, 7) == nil")
         .unwrap());
 
-    // A STRING is a unit token — the FOREIGN unit's side, not the player's.
+    // A string is a unit token: the foreign unit's side, not the player's.
     assert_eq!(
         s.eval::<String>(r#"return (GetPVPRankInfo(9, "target"))"#)
             .unwrap(),
@@ -622,8 +547,7 @@ fn get_pvp_rank_info_takes_a_second_argument_three_different_ways() {
         "Thrall is Horde, so his ladder names rank 9"
     );
 
-    // A token that names nothing, and a token naming a non-player, both fall to team 0 — the
-    // engine's uninitialised team register, not a failure.
+    // A token naming nothing or a non-player falls to team 0, the register's initial value.
     assert_eq!(
         s.eval::<String>(r#"return (GetPVPRankInfo(9, "mouseover"))"#)
             .unwrap(),
@@ -645,8 +569,7 @@ fn get_pvp_rank_info_takes_a_second_argument_three_different_ways() {
         "a non-player is gated out before its side is read"
     );
 
-    // A unit that resolves but has NO side is −1, which misses the key — a different answer from
-    // the not-found 0 above, and the one the panes render as NONE.
+    // A unit that resolves with no side is -1 and misses the key, unlike the not-found 0 above.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -660,14 +583,12 @@ fn get_pvp_rank_info_takes_a_second_argument_three_different_ways() {
         .eval::<bool>(r#"return GetPVPRankInfo(9, "target") == nil"#)
         .unwrap());
 
-    // An unrecognised token raises, as it does for every unit binding.
     assert!(s
         .eval::<Option<String>>(r#"return (GetPVPRankInfo(9, "wombat"))"#)
         .is_err());
 }
 
-/// The first argument's `Usage:` gate — `0x51a930` tests `lua_isnumber` and **raises**, abandoning
-/// the caller's statement. It is not a `(nil, 0)` edge, and the two are not interchangeable.
+/// `0x51a930` tests `lua_isnumber` and raises: not a `(nil, 0)` edge.
 #[test]
 fn get_pvp_rank_info_raises_without_a_numeric_first_argument() {
     let s = seated();
@@ -684,14 +605,13 @@ fn get_pvp_rank_info_raises_without_a_numeric_first_argument() {
             "{call}: {err}"
         );
     }
-    // A numeric string is a number to Lua, so it does NOT raise.
+    // A numeric string is a number to Lua, so it does not raise.
     assert!(s
         .eval::<Option<String>>(r#"return (GetPVPRankInfo("9"))"#)
         .is_ok());
 }
 
-/// `UnitPVPRank` must answer for a **foreign** unit: `PLAYER_BYTES_3` is PUBLIC, and the
-/// reference's inspect pane calls it as `UnitPVPRank("target")`. An unknown token reads 0.
+/// `PLAYER_BYTES_3` is public, and the reference's inspect pane calls `UnitPVPRank("target")`.
 #[test]
 fn unit_pvp_rank_answers_for_a_foreign_unit() {
     let mut s = seated();
@@ -712,9 +632,8 @@ fn unit_pvp_rank_answers_for_a_foreign_unit() {
         14
     );
     assert_eq!(s.eval::<i64>(r#"return UnitPVPRank("player")"#).unwrap(), 9);
-    // A creature reads 0 because it has no PLAYER descriptor block to decode a rank byte from —
-    // the engine's own path to the same answer. The binding does NOT re-gate on `is_player`; see
-    // the binding for why our `is_player` is not the engine's type mask.
+    // A creature reads 0 because it has no player descriptor block to decode a rank from; the
+    // binding does not re-gate on `is_player`.
     s.set_unit(
         "mouseover",
         Some(UnitState {
@@ -734,37 +653,30 @@ fn unit_pvp_rank_answers_for_a_foreign_unit() {
         0,
         "no snapshot reads 0, like every other numeric Unit* getter"
     );
-    // A non-string argument RAISES (`0x51a8ac`) — it does not answer 0. A number is a string to
-    // Lua, so it resolves the token "5" and raises for a different reason: an unknown token.
+    // A non-string argument raises (`0x51a8ac`) rather than answering 0.
     assert!(s.eval::<i64>("return UnitPVPRank()").is_err());
     assert!(s.eval::<i64>("return UnitPVPRank({})").is_err());
 }
 
-/// **`UnitPVPName`'s three legs** (`0x609370`), which is the whole binding: the decorated player
-/// name, the civilian prefix, and the plain name.
-///
-/// The template is `UNIT_PVP_NAME` off `_G` and it is filled rank-FIRST — `add esp,0x14` proves two
-/// varargs and enUS ships `"%s %s"`. The title here **is** gendered (by this unit), which is the
-/// opposite of the pane's and the reason the two lookups are separate functions.
+/// `UnitPVPName`'s three legs (`0x609370`); the title fills `UNIT_PVP_NAME` rank first and is
+/// gendered by this unit, unlike the pane's.
 #[test]
 fn unit_pvp_name_decorates_a_ranked_player_and_falls_back_three_ways() {
     let mut s = seated();
     seat_rank_globals(&s);
     seat_name_globals(&s);
 
-    // Leg A — the seated player is a female Alliance rank 9, so the FEMALE twin wins here.
+    // Leg A: the seated player is a female Alliance rank 9, so the `_FEMALE` twin wins.
     assert_eq!(
         s.eval::<String>(r#"return UnitPVPName("player")"#).unwrap(),
         "Sergeant Major (f) Benilla"
     );
-    // …male takes the base key, and the order is rank then name either way.
     s.set_unit("player", Some(UnitState { sex: 2, ..player() }));
     assert_eq!(
         s.eval::<String>(r#"return UnitPVPName("player")"#).unwrap(),
         "Sergeant Major Benilla"
     );
 
-    // No range check on this path: the racial-leader rank really does render.
     s.set_unit(
         "player",
         Some(UnitState {
@@ -779,7 +691,7 @@ fn unit_pvp_name_decorates_a_ranked_player_and_falls_back_three_ways() {
         "rank 19 names here and is refused by GetPVPRankInfo"
     );
 
-    // Leg A′ — the city-protector medal, appended on its own line.
+    // Leg A′: the city-protector medal, on its own line.
     s.set_unit(
         "player",
         Some(UnitState {
@@ -793,7 +705,7 @@ fn unit_pvp_name_decorates_a_ranked_player_and_falls_back_three_ways() {
         "Sergeant Major Benilla\nGuardian of Stormwind"
     );
 
-    // Leg C — an unranked player is just a name, and so is a plain creature.
+    // Leg C: an unranked player is just a name, and so is a plain creature.
     s.set_unit(
         "player",
         Some(UnitState {
@@ -819,8 +731,8 @@ fn unit_pvp_name_decorates_a_ranked_player_and_falls_back_three_ways() {
         "Timber Wolf"
     );
 
-    // Leg B — the civilian prefix, on the same `0x612550` gate the tooltip's CIVILIAN line uses:
-    // PvP-flagged, hostile and grey to the player. A friendly civilian is still just a name.
+    // Leg B: the civilian prefix, on the tooltip's `0x612550` gate: PvP-flagged, hostile and grey
+    // to the player.
     s.set_player_req_state(crate::script::PlayerReqState {
         level: 30,
         ..Default::default()
@@ -852,7 +764,6 @@ fn unit_pvp_name_decorates_a_ranked_player_and_falls_back_three_ways() {
         "…nor an unflagged one"
     );
 
-    // The two nil edges, and the raise.
     assert!(s
         .eval::<bool>(r#"return UnitPVPName("mouseover") == nil"#)
         .unwrap());
@@ -872,9 +783,7 @@ fn unit_pvp_name_decorates_a_ranked_player_and_falls_back_three_ways() {
     assert!(s.eval::<String>("return UnitPVPName()").is_err());
 }
 
-/// With no install behind the VM there is no template and no title, and the decoration is install
-/// data: we answer the **plain name**. (The engine would snprintf through an empty format and hand
-/// back an empty string — a stated divergence, not an oversight.)
+/// No install: the plain name, where the reference would format an empty string.
 #[test]
 fn unit_pvp_name_without_the_globalstrings_answers_the_plain_name() {
     let s = seated(); // nothing seated on _G
@@ -882,7 +791,7 @@ fn unit_pvp_name_without_the_globalstrings_answers_the_plain_name() {
         s.eval::<String>(r#"return UnitPVPName("player")"#).unwrap(),
         "Benilla"
     );
-    // The template alone is not enough — the title has to resolve too.
+    // The template alone is not enough: the title has to resolve too.
     s.lua()
         .globals()
         .set("UNIT_PVP_NAME", "%s %s")
@@ -893,9 +802,7 @@ fn unit_pvp_name_without_the_globalstrings_answers_the_plain_name() {
     );
 }
 
-/// The template is *filled*, not assumed: a locale that punctuates `UNIT_PVP_NAME` differently
-/// comes out differently, and a `%%` is a literal per cent. Two varargs is the engine's own limit
-/// (`add esp,0x14`), so a third specifier has nothing to consume.
+/// Two varargs is the engine's limit (`add esp,0x14`), so a third `%s` has nothing to consume.
 #[test]
 fn the_two_string_template_is_substituted_not_hardcoded() {
     assert_eq!(format_two_strings("%s %s", "Rank", "Name"), "Rank Name");
@@ -923,8 +830,6 @@ fn the_two_string_template_is_substituted_not_hardcoded() {
     );
 }
 
-/// The inspect latch: false before any reply, true while one is held, false again once the app
-/// clears it — which is what makes the reference's `OnShow` re-request for the next player.
 #[test]
 fn has_inspect_honor_data_latches_on_the_push_and_clears_with_it() {
     let mut s = seated();
@@ -934,9 +839,7 @@ fn has_inspect_honor_data_latches_on_the_push_and_clears_with_it() {
     s.set_inspect_honor(Some(inspect_state()));
     assert!(s.eval::<bool>(held()).unwrap());
 
-    // `0x4c95e0` pushes the NUMBER 1, not a boolean — one value either way, and the truthy arm is
-    // `1` rather than `true`. (It is `lua_pushnumber(1.0)`; in a VM whose numbers are all
-    // doubles there is no observable integer/float distinction, and `tostring` proves it.)
+    // `0x4c95e0` pushes the number 1 (`lua_pushnumber(1.0)`), not a boolean.
     assert_eq!(
         s.eval::<String>("return type(HasInspectHonorData())")
             .unwrap(),
@@ -978,10 +881,8 @@ fn get_inspect_honor_data_returns_the_twelve_in_the_reference_order() {
     );
 }
 
-/// **With no reply held `GetInspectHonorData` still answers twelve — zeros.** `0x4c9620` is
-/// UNGATED: it never consults the has-data flag, and the sixteen globals it reads are
-/// zero-initialised BSS. A short return would leave the pane painting `SetText(nil)` — a blank row
-/// — where the real client paints a `0` row, and the two look different on screen.
+/// `0x4c9620` is ungated and reads zero-initialised slots; a short return would paint blank rows
+/// where the reference paints zeros.
 #[test]
 fn get_inspect_honor_data_answers_twelve_zeros_when_no_reply_is_held() {
     let mut s = seated();
@@ -998,15 +899,13 @@ fn get_inspect_honor_data_answers_twelve_zeros_when_no_reply_is_held() {
     assert!(s
         .eval::<bool>("return (GetInspectHonorData()) == 0")
         .unwrap());
-    // The bar reads its own zeroed byte, for the same reason.
     assert_eq!(
         s.eval::<f64>("return GetInspectPVPRankProgress()").unwrap(),
         0.0
     );
 
-    // And after the app drops the reply it is zeros again — our `Option` is the latch AND the
-    // data, where the engine keeps them apart and would answer the previous target's numbers
-    // here (`0x4c6f70` re-keying zeroes the two flags and leaves the sixteen slots alone).
+    // Zeros again after a clear; the reference would still hold the previous target's numbers
+    // (`0x4c6f70` zeroes only the flags).
     s.set_inspect_honor(Some(inspect_state()));
     s.set_inspect_honor(None);
     assert_eq!(
@@ -1016,27 +915,24 @@ fn get_inspect_honor_data_answers_twelve_zeros_when_no_reply_is_held() {
     );
 }
 
-/// The two intent queues drain to the app and reset — and the honor query **does not queue twice**:
-/// `0x4c80a0` bails while one is in flight (`pending`) and bails again once data is held
-/// (`hasData`), which is what stops a pane shown/hidden/shown sending duplicates. The PvP toggle
-/// has no such latch and genuinely does send twice.
+/// `0x4c80a0` refuses a query while one is in flight and once data is held; `TogglePVP` has no
+/// latch.
 #[test]
 fn the_intent_queues_drain_and_the_honor_query_refuses_to_double_up() {
     let mut s = seated();
     assert_eq!(s.take_inspect_honor_requests(), 0);
 
-    // Two calls, ONE query: the second sees `pending`.
+    // Two calls, one query: the second sees `pending`.
     s.eval::<()>("RequestInspectHonorData() RequestInspectHonorData()")
         .unwrap();
     assert_eq!(s.take_inspect_honor_requests(), 1);
     assert_eq!(s.take_inspect_honor_requests(), 0);
 
-    // Still latched after the drain — the app has sent, nothing has replied.
+    // Still latched after the drain: sent, not yet answered.
     s.eval::<()>("RequestInspectHonorData()").unwrap();
     assert_eq!(s.take_inspect_honor_requests(), 0, "still in flight");
 
-    // The reply clears `pending` — and immediately sets `hasData`, so the next ask is refused for
-    // the *other* reason.
+    // The reply clears `pending` and sets `hasData`, which refuses the next ask instead.
     s.set_inspect_honor(Some(inspect_state()));
     s.eval::<()>("RequestInspectHonorData()").unwrap();
     assert_eq!(s.take_inspect_honor_requests(), 0, "data already held");
diff --git a/crates/benilla-ui/src/script/quest.rs b/crates/benilla-ui/src/script/quest.rs
index 4cde5a79..456dce4a 100644
--- a/crates/benilla-ui/src/script/quest.rs
+++ b/crates/benilla-ui/src/script/quest.rs
@@ -1,80 +1,48 @@
-//! The questgiver bindings (decision 0088) — the Era-shaped quest-dialog surface, the same two-way
-//! seam as [`super::gossip`]/[`super::merchant`]: the app pushes a **quest panel snapshot**
-//! ([`UiScript::set_quest`] — the greeting/detail/progress/reward text + item rows already resolved
-//! from the wire), and the Lua `AcceptQuest`/`CompleteQuest`/`GetQuestReward`/`SelectActiveQuest`/…
-//! calls queue outbound **intents** the app drains ([`UiScript::take_quest_selects`] /
-//! [`UiScript::take_quest_actions`]). The engine holds no quest knowledge — a row is "a name, an
-//! icon, a count, a quality, and whether it's usable"; a button press is a bare intent the app maps
-//! to `(npc, questId)` from its own live state.
-//!
-//! ## The Era API shape
-//!
-//! 1.12's `QuestFrame.lua` reads flat getters positionally, one panel at a time: the greeting panel
-//! walks `GetNumActiveQuests()`/`GetActiveTitle(i)` (+ the available twins), the detail panel reads
-//! `GetTitleText()`/`GetQuestText()`/`GetObjectiveText()`, the progress panel reads
-//! `GetProgressText()`/`IsQuestCompletable()`/`GetNumQuestItems()`/`GetQuestItemInfo("required",i)`,
-//! the reward panel reads `GetRewardText()`/`GetNumQuestChoices()`/`GetNumQuestRewards()`/
-//! `GetRewardMoney()`/`GetQuestItemInfo("choice"|"reward",i)`. Benilla keeps those exact names on a
-//! single pushed [`QuestState`]; which panel is live is [`QuestState::panel`], surfaced to the XML
-//! through the `QUEST_GREETING`/`QUEST_DETAIL`/`QUEST_PROGRESS`/`QUEST_COMPLETE` events the app
-//! fires. `GetRewardSpell()` returns `nil` in v1 (spell-reward rows are out of scope, decision 0088).
+//! The questgiver bindings: the app pushes the open panel ([`UiScript::set_quest`]), and the panel
+//! verbs queue selects and button intents it drains. One [`QuestState`] serves the flat getters
+//! `QuestFrame.lua` reads on each panel; the app fires `QUEST_GREETING`, `QUEST_DETAIL`,
+//! `QUEST_PROGRESS` or `QUEST_COMPLETE` for the live one.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::binding_abi::flag;
 use super::Model;
 
-/// Which of the four questgiver sub-panels a [`QuestState`] is for (the app sets it from the wire
-/// packet; the XML's event routing mirrors it).
+/// Which questgiver panel a [`QuestState`] is for, set from the wire packet.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum QuestPanel {
-    /// `SMSG_QUESTGIVER_QUEST_LIST` — the multi-quest greeting (active + available lists).
+    /// `SMSG_QUESTGIVER_QUEST_LIST`: the greeting, with the active and available lists.
     Greeting,
-    /// `SMSG_QUESTGIVER_QUEST_DETAILS` — the accept panel.
+    /// `SMSG_QUESTGIVER_QUEST_DETAILS`: the accept panel.
     Detail,
-    /// `SMSG_QUESTGIVER_REQUEST_ITEMS` — the turn-in progress panel.
+    /// `SMSG_QUESTGIVER_REQUEST_ITEMS`: the turn-in progress panel.
     Progress,
-    /// `SMSG_QUESTGIVER_OFFER_REWARD` — the reward panel.
+    /// `SMSG_QUESTGIVER_OFFER_REWARD`: the reward panel.
     Reward,
 }
 
-/// One quest item row (choice reward / fixed reward / required item), resolved by the app from the
-/// wire triple + its item stores. Plain data — 1-based order is its position in the owning vector.
+/// One choice, reward or required item row; its 1-based index is its place in its list.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct QuestItemView {
-    /// Item name (`GetQuestItemInfo`'s first return); `None` while the ask-once template query is in
-    /// flight (the API reports `nil`, the XML shows a placeholder).
+    /// `None`, answered as nil, while the item template is in flight.
     pub name: Option<String>,
-    /// Icon texture path (`Interface\Icons\…`); `None` while the template answer is in flight (the
-    /// icon comes from the wire display id, so it's usually present immediately).
     pub texture: Option<String>,
-    /// Stack count for the row (`numItems`).
     pub count: u32,
-    /// Item quality (0 poor .. 5 legendary); colours the reward name. `1` (common/white) when the
-    /// template hasn't landed.
+    /// 0 poor to 5 legendary; 1 until the template lands.
     pub quality: u32,
-    /// The item id — the shared item-tooltip store's key (`BenillaGetItemStats`); `0` while the
-    /// wire row hasn't resolved. A benilla extension: the era 5-tuple never carried it (tooltip
-    /// content was C++'s alone), so it rides as a TRAILING 6th return, invisible to era callers.
+    /// The item id the quest tooltips render by; 0 until the wire row resolves.
     pub item_id: u32,
-    /// Whether the reward is usable by the player's class/race — v1 always `true` (soft gray only,
-    /// the server stays authoritative).
+    /// Whether the player can use the item; stock tints the row red when not
+    /// (`QuestFrame.lua:393`). The app always sends `true`.
     pub usable: bool,
-    /// The full escaped `|cff…|Hitem:…|h[Name]|h|r` link (`GetQuestItemLink` /
-    /// `GetQuestLogItemLink` serve it) — the ctrl/shift click arms' payload (decisions 1059/1060).
-    /// `None` until the ask-once item template lands: the link is built from the name **and** the
-    /// quality, and neither is known before then, exactly like [`super::InvSlotView::link`].
+    /// The escaped item link `GetQuestItemLink` and `GetQuestLogItemLink` serve; `None` until the
+    /// template lands, since it embeds the name and the quality.
     pub link: Option<String>,
 }
 
-/// One open questgiver panel: the active sub-panel plus every field the four panels might read.
-/// Pushed whole by the app; `None` means no quest window is open.
-/// The quest's reward spell — `rewSpell` on `SMSG_QUESTGIVER_QUEST_DETAILS` /
-/// `SMSG_QUESTGIVER_OFFER_REWARD` and on `SMSG_QUEST_QUERY_RESPONSE` — resolved by the app to
-/// the name and icon `GetRewardSpell` / `GetQuestLogRewardSpell` answer (stock
-/// `QuestFrameItems_Update` counts it as one more reward slot, `rewardType = "spell"`, and the
-/// slot's hover is `GameTooltip:SetQuestRewardSpell()`). `tradeskill` is the third return the
-/// reference derives from the spell itself (1944 — the derivation is not yet pinned).
+/// The reward spell, `rewSpell` on the giver packets and `SMSG_QUEST_QUERY_RESPONSE`, as
+/// `GetRewardSpell` and `GetQuestLogRewardSpell` answer it; stock counts it as one more reward slot
+/// (`QuestFrame.lua:332`). `tradeskill` is the third return, `isTradeskillSpell`.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct QuestRewardSpell {
     pub spell_id: u32,
@@ -83,6 +51,7 @@ pub struct QuestRewardSpell {
     pub tradeskill: bool,
 }
 
+/// One open questgiver panel, with every field the four panels read; pushed whole by the app.
 #[derive(Clone, Debug, PartialEq)]
 pub struct QuestState {
     pub panel: QuestPanel,
@@ -90,31 +59,25 @@ pub struct QuestState {
     pub greeting: String,
     pub active_titles: Vec<String>,
     pub available_titles: Vec<String>,
-    // Detail / progress / reward.
-    /// The quest title (`GetTitleText`).
+    // Detail, progress and reward panels.
     pub title: String,
-    /// The panel body text: quest description (detail), request text (progress), or reward text
-    /// (reward). One field — only one of the three panels is live at a time.
+    /// The text of whichever panel is live: quest, progress or reward.
     pub body: String,
-    /// The quest objectives line (`GetObjectiveText`, detail panel only).
     pub objectives: String,
-    /// Choice rewards (the player picks one) — reward/detail panel.
+    /// Rewards the player picks one of.
     pub choices: Vec<QuestItemView>,
-    /// Fixed rewards (all granted) — reward/detail panel.
+    /// Rewards all granted.
     pub rewards: Vec<QuestItemView>,
-    /// Required items — progress panel.
+    /// Items the progress panel asks for.
     pub required: Vec<QuestItemView>,
-    /// Reward money in copper (`GetRewardMoney`, detail/reward panels).
+    /// In copper.
     pub reward_money: u32,
-    /// Required money in copper (`GetQuestMoneyToGet`, progress panel).
+    /// In copper.
     pub required_money: u32,
-    /// Whether the turn-in is completable (`IsQuestCompletable`, progress panel).
     pub completable: bool,
-    /// The reward spell, if the quest teaches one (`GetRewardSpell`; detail/reward panels).
     pub reward_spell: Option<QuestRewardSpell>,
-    /// The panel's background material (`GetQuestBackgroundMaterial` — nil is the reference's own
-    /// "Parchment" fallback in `QuestFrame_GetMaterial`). What fills it on the wire is 1944's
-    /// open question; until the binary says, nothing does, and the verb answers nil honestly.
+    /// `GetQuestBackgroundMaterial`, which the app fills from an item or GameObject source, never
+    /// from the wire; nil reads as "Parchment" (`QuestFrame.lua:598-604`).
     pub background_material: Option<String>,
 }
 
@@ -140,45 +103,31 @@ impl Default for QuestState {
     }
 }
 
-/// A greeting-panel row click queued by `SelectActiveQuest`/`SelectAvailableQuest`: the 1-based row
-/// in its list. `active` picks between the active and available lists (the app maps the index to the
-/// quest id).
+/// A greeting row picked by `SelectActiveQuest` or `SelectAvailableQuest`, 1-based in its list.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct QuestSelect {
     pub active: bool,
     pub index: u32,
 }
 
-/// A questgiver button intent queued by the Lua panel verbs; the app maps each to `(npc, questId)`
-/// from its own live state and the matching `CMSG_QUESTGIVER_*`.
+/// A questgiver button intent; the app sends the matching message for its NPC and quest.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum QuestAction {
     /// Detail panel Accept → `CMSG_QUESTGIVER_ACCEPT_QUEST`.
     Accept,
-    /// Progress panel Continue → `CMSG_QUESTGIVER_REQUEST_REWARD` (advance to the reward panel).
+    /// Progress panel Continue → `CMSG_QUESTGIVER_REQUEST_REWARD`.
     Continue,
-    /// Reward panel Complete → `CMSG_QUESTGIVER_CHOOSE_REWARD` with the chosen choice index (0 when
-    /// the quest has no choice rewards).
+    /// Reward panel Complete → `CMSG_QUESTGIVER_CHOOSE_REWARD` with the 0-based choice.
     Reward(u32),
-    /// `DeclineQuest()` — the detail panel's Decline and the progress/reward panels' Cancel
-    /// (stock `QuestFrame.lua`: `QuestDetailDeclineButton_OnClick`, `QuestGoodbyeButton_OnClick`,
-    /// `QuestRewardCancelButton_OnClick`). Its binding `0x501d30` calls `0x5013f0`, the ONLY
-    /// routine that re-opens the giver: a four-way fork on the source's object type — a
-    /// gossip-flagged unit → `CMSG_GOSSIP_HELLO`, a plain unit → `CMSG_QUESTGIVER_HELLO`, an
-    /// item/player (or the `0xbe0824` latch set) → the teardown `0x501130(0,1)`, a GameObject →
-    /// its interact virtual. The app owns the fork, because only it knows the giver.
+    /// `DeclineQuest()`: the detail panel's Decline and the progress and reward panels' Cancel.
+    /// Its binding (`0x501d30`) re-opens the giver through `0x5013f0`: `CMSG_GOSSIP_HELLO` for a
+    /// gossip unit, `CMSG_QUESTGIVER_HELLO` for another unit, the teardown `0x501130(0,1)` for an
+    /// item or a player (or with `0xbe0824` set), a GameObject's interact call. The app owns this.
     Decline,
-    /// `CloseQuest()` — the window's own `QuestFrame_OnHide`: ESC, the close button, the
-    /// greeting's Goodbye (`HideUIPanel(QuestFrame)`), a UIPanel eviction. Its binding `0x501a10`
-    /// calls the teardown `0x501130(0,1)` and **nothing else**; that routine's one send is
-    /// `MSG_QUEST_PUSH_RESULT{DECLINE}` for a PLAYER source, so closing an NPC's window is
-    /// network-silent.
-    ///
-    /// **Two actions, because the reference has two routines.** 1738 merged this into
-    /// `DeclineQuest`'s action on the reading that both verbs are one routine; the reference's
-    /// callers show they share only the teardown, and the HELLO re-open lives in `DeclineQuest`'s
-    /// fork alone. The merge made ESC on an NPC re-open its list — a multi-quest greeting could
-    /// not be closed.
+    /// `CloseQuest()`, from `QuestFrame_OnHide`: ESC, the close button, the greeting's Goodbye, a
+    /// panel eviction. Its binding (`0x501a10`) calls only the teardown `0x501130(0,1)`, whose one
+    /// send is `MSG_QUEST_PUSH_RESULT` DECLINE for a player source, so closing an NPC's window
+    /// sends nothing. It stays apart from `Decline`: the re-open is `DeclineQuest`'s alone.
     Close,
 }
 
@@ -199,9 +148,7 @@ impl super::UiScript {
     }
 }
 
-/// `GetQuestItemInfo(type, index)` reads from this vector by `type`; unknown types → `None`.
-/// The three returns of `GetRewardSpell` / `GetQuestLogRewardSpell`: `texture, name,
-/// isTradeskillSpell` — the third a 1/nil boolean in the reference's convention.
+/// `GetRewardSpell`'s three returns: `texture, name, isTradeskillSpell`, the third 1 or nil.
 pub(super) fn reward_spell_returns(
     lua: &Lua,
     spell: Option<QuestRewardSpell>,
@@ -229,6 +176,7 @@ pub(super) fn reward_spell_returns(
     Ok(MultiValue::from_vec(vec![texture, name, tradeskill]))
 }
 
+/// The list `GetQuestItemInfo(type, index)` reads for `type`.
 pub(super) fn item_vec<'a>(state: &'a QuestState, kind: &str) -> Option<&'a Vec<QuestItemView>> {
     match kind {
         "choice" => Some(&state.choices),
@@ -242,7 +190,7 @@ pub(super) fn item_vec<'a>(state: &'a QuestState, kind: &str) -> Option<&'a Vec<
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // ── Text getters (one per panel field; nil/"" when no window is open) ─────────────────────────
+    // ── Text getters ──
     fn install_text(lua: &Lua, name: &str, pick: fn(&QuestState) -> String) -> mlua::Result<()> {
         lua.globals().set(
             name,
@@ -262,7 +210,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     install_text(lua, "GetRewardText", |q| q.body.clone())?;
     install_text(lua, "GetObjectiveText", |q| q.objectives.clone())?;
 
-    // ── Count + money getters ─────────────────────────────────────────────────────────────────────
+    // ── Count and money getters ──
     fn install_count(lua: &Lua, name: &str, pick: fn(&QuestState) -> i64) -> mlua::Result<()> {
         lua.globals().set(
             name,
@@ -282,7 +230,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     install_count(lua, "GetRewardMoney", |q| i64::from(q.reward_money))?;
     install_count(lua, "GetQuestMoneyToGet", |q| i64::from(q.required_money))?;
 
-    // IsQuestCompletable() → 1/nil (progress panel gate for the Continue button).
     g.set(
         "IsQuestCompletable",
         lua.create_function(|lua, ()| {
@@ -291,7 +238,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetActiveTitle(i) / GetAvailableTitle(i) — 1-based; "" when out of range.
     fn install_title(lua: &Lua, name: &str, active: bool) -> mlua::Result<()> {
         lua.globals().set(
             name,
@@ -314,8 +260,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     install_title(lua, "GetActiveTitle", true)?;
     install_title(lua, "GetAvailableTitle", false)?;
 
-    // GetQuestItemInfo(type, index) → name, texture, numItems, quality, isUsable (the Era tuple).
-    // `type` is "choice" / "reward" / "required"; `index` 1-based; out of range → nil.
+    // GetQuestItemInfo(type, index) → name, texture, numItems, quality, isUsable.
     g.set(
         "GetQuestItemInfo",
         lua.create_function(|lua, (kind, index): (String, usize)| {
@@ -344,18 +289,13 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 Value::Integer(i64::from(it.count)),
                 Value::Integer(i64::from(it.quality)),
                 Value::Boolean(it.usable),
-                // Benilla extension (6th): the item id, the shared tooltip store's key.
+                // Not 1.12's: a sixth return, the item id, after its five; nothing reads it.
                 Value::Integer(i64::from(it.item_id)),
             ]))
         })?,
     )?;
 
-    // GetQuestItemLink(type, index) → the full escaped `|cff…|Hitem:…|h[Name]|h|r` | nil. The
-    // questgiver panels' ctrl/shift click arms read it — `DressUpItemLink(GetQuestItemLink(
-    // this.type, this:GetID()))` (ref QuestFrame.lua:118/130) and the shift-click
-    // `ChatFrameEditBox:Insert(...)` beside it (l.122/134). Same `type`/`index` addressing as
-    // `GetQuestItemInfo` above; nil for an out-of-range row, an unknown type, or a row whose
-    // template answer is still in flight (see [`QuestItemView::link`]). Decisions 1059/1060.
+    // GetQuestItemLink(type, index), for a row's ctrl and shift clicks (`QuestFrame.lua:118`).
     g.set(
         "GetQuestItemLink",
         lua.create_function(|lua, (kind, index): (String, usize)| {
@@ -374,10 +314,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetRewardSpell() → texture, name, isTradeskillSpell (three returns, 0x501df0; three nils on
-    // every empty path, the reference's own `(nil,nil,nil)` kind — 1842). Real since 1944: the
-    // app resolves `rewSpell` off the giver packets; stock's `if ( GetRewardSpell() ) then` counts
-    // the slot.
+    // GetRewardSpell() (`0x501df0`): three nils without a spell.
     g.set(
         "GetRewardSpell",
         lua.create_function(|lua, ()| {
@@ -389,8 +326,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ── Intents ───────────────────────────────────────────────────────────────────────────────────
-    // SelectActiveQuest(i) / SelectAvailableQuest(i) — queue a greeting-row select (1-based).
+    // ── Intents ──
     fn install_select(lua: &Lua, name: &str, active: bool) -> mlua::Result<()> {
         lua.globals().set(
             name,
@@ -416,18 +352,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             })?,
         )
     }
-    // AcceptQuest → Accept; DeclineQuest → Decline (the re-opening fork `0x5013f0`); CloseQuest →
-    // Close (the teardown `0x501130` alone — see `QuestAction::Close`); CompleteQuest (the
-    // progress panel's Continue) → Continue.
     install_action(lua, "AcceptQuest", super::QuestAction::Accept)?;
     install_action(lua, "DeclineQuest", super::QuestAction::Decline)?;
     install_action(lua, "CloseQuest", super::QuestAction::Close)?;
     install_action(lua, "CompleteQuest", super::QuestAction::Continue)?;
 
-    // GetQuestBackgroundMaterial() → nil | string (0x502230; 0 args, 1 return). The reference's
-    // `QuestFrame_GetMaterial` (QuestFrame.lua:597-603) treats nil as "Parchment" and any string
-    // as the name of a material whose four `$parentMaterial*` quadrants and text colours
-    // (`GetMaterialTextColors`) the panel switches to. Answered from the pushed panel state.
+    // GetQuestBackgroundMaterial() → nil or a material name (`0x502230`).
     g.set(
         "GetQuestBackgroundMaterial",
         lua.create_function(|lua, ()| {
@@ -445,14 +375,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // QuestChooseRewardError() — 0x5021a0, 0 args, 0 returns: the Complete button pressed with
-    // choices on offer and none picked (stock `QuestRewardCompleteButton_OnClick`,
-    // QuestFrame.lua:96-100). Sixteen bytes — `push 0x98; call 0x496720` — the game-error row
-    // `ERR_QUEST_MUST_CHOOSE`: the row's sound
-    // cue `igQuestFailed` plays first, then kind 2 routes the GlobalStrings text through
-    // `UI_ERROR_MESSAGE` — synchronously, as SignalEvent is — and UIErrorsFrame prints it. The
-    // text is read from the same global the FrameXML shows, so a localised chain shows its own
-    // string; the shipped English is the fallback when no GlobalStrings is loaded.
+    // QuestChooseRewardError() (`0x5021a0`), no returns: Complete pressed with choices and none
+    // picked (`QuestFrame.lua:98`). It shows game error `0x98` through `0x496720`: the sound
+    // `igQuestFailed`, then `ERR_QUEST_MUST_CHOOSE` through `UI_ERROR_MESSAGE`, synchronously.
     g.set(
         "QuestChooseRewardError",
         lua.create_function(|lua, ()| {
@@ -475,9 +400,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ConfirmAcceptQuest() — the escort confirm's Yes (ref StaticPopup.lua:731-733, raised by
-    // QUEST_ACCEPT_CONFIRM). No argument and no quest id: the client answers whichever confirm it
-    // is holding, so the engine counts the calls and the app supplies the id (decision 1733).
+    // ConfirmAcceptQuest(): the escort confirm's Yes (`StaticPopup.lua:731-733`). It takes no quest
+    // id, as the client answers the confirm it holds, so calls are counted and the app adds the id.
     g.set(
         "ConfirmAcceptQuest",
         lua.create_function(|lua, ()| {
@@ -487,12 +411,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetQuestReward(choice) — the reward panel's Complete button. FrameXML passes the 1-based row
-    // (`QuestFrameRewardPanel.itemChoice = this:GetID()`, stock QuestFrame.lua:97-101) and the
-    // wire wants the 0-based choice (`CMSG_QUESTGIVER_CHOOSE_REWARD`'s reward index — vmangos
-    // indexes `RewChoiceItemId[reward]` with it), so the conversion is the binding's, as it is the
-    // client's; our own Lua used to do the -1 itself (1944). A quest with no choice rewards
-    // passes 0, which stays 0.
+    // GetQuestReward(choice): stock passes the 1-based row (`QuestFrame.lua:100`), and the wire
+    // takes it less one, floored at 0, as in the reference (`0x501d80`); vmangos indexes
+    // `RewChoiceItemId` with it.
     g.set(
         "GetQuestReward",
         lua.create_function(|lua, choice: Option<u32>| {
@@ -609,7 +530,6 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetNumQuestRewards()").unwrap(), 1);
         assert_eq!(s.eval::<i64>("return GetRewardMoney()").unwrap(), 1234);
 
-        // Row 1 (resolved): the Era tuple.
         let (name, texture, count, quality, usable) = s
             .eval::<(String, String, i64, i64, bool)>("return GetQuestItemInfo(\"reward\", 1)")
             .unwrap();
@@ -617,14 +537,14 @@ mod tests {
         assert_eq!(texture, "Interface\\Icons\\INV_Boots_01");
         assert_eq!((count, quality, usable), (1, 2, true));
 
-        // Choice row 2 (in flight): name + texture nil, the rest present.
+        // Choice row 2 is in flight: name and texture nil, the rest present.
         assert!(s
             .eval::<bool>(
                 "local n, t, c = GetQuestItemInfo(\"choice\", 2)\n\
                  return n == nil and t == nil and c == 1"
             )
             .unwrap());
-        // Out of range / unknown type → nil.
+        // Out of range, and an unknown type: nil.
         assert!(s
             .eval::<bool>("return GetQuestItemInfo(\"reward\", 9) == nil")
             .unwrap());
@@ -632,9 +552,7 @@ mod tests {
             .eval::<bool>("return GetQuestItemInfo(\"bogus\", 1) == nil")
             .unwrap());
 
-        // GetQuestItemLink: the resolved row's full escaped link; nil for a row still waiting on
-        // its template (choice 2 has no name yet, so no link either), and nil out of range /
-        // unknown type — the three nils the ref's ctrl/shift arms hand to DressUpItemLink.
+        // The link is nil for the in-flight row, out of range, and for an unknown type.
         assert_eq!(
             s.eval::<String>("return GetQuestItemLink(\"reward\", 1)")
                 .unwrap(),
@@ -755,9 +673,6 @@ mod tests {
         assert!(s.eval::<bool>("return GetRewardSpell() == nil").unwrap());
     }
 
-    /// `DeclineQuest` and `CloseQuest` are TWO intents — two reference routines (`0x5013f0` and
-    /// `0x501a10`) that share only the teardown `0x501130`; the giver re-open is `DeclineQuest`'s
-    /// alone.
     #[test]
     fn decline_and_close_are_two_intents() {
         let mut s = UiScript::new().unwrap();
@@ -770,8 +685,6 @@ mod tests {
         );
     }
 
-    /// `ConfirmAcceptQuest` counts rather than carrying a quest id — the reference's verb takes no
-    /// argument and answers whichever confirm the client holds (decision 1733).
     #[test]
     fn confirm_accept_quest_counts_and_drains() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/quest_log.rs b/crates/benilla-ui/src/script/quest_log.rs
index 4ee0679e..e0e91efa 100644
--- a/crates/benilla-ui/src/script/quest_log.rs
+++ b/crates/benilla-ui/src/script/quest_log.rs
@@ -1,47 +1,13 @@
-//! The quest-**log** bindings (the 0088 arc's second slice) — the Era-shaped `GetQuestLog*` surface
-//! the reference `QuestLogFrame.lua` reads, over the same two-way seam as the questgiver panels
-//! ([`super::quest`]): the app pushes a whole [`QuestLogState`] snapshot (entries from the
-//! `PLAYER_QUEST_LOG` descriptor slots, the selected quest's detail resolved from the
-//! `SMSG_QUEST_QUERY_RESPONSE` template cache), and the Lua drains back the **abandon** intent.
+//! The quest-log verbs the stock `QuestLogFrame.lua` calls, over a [`QuestLogState`] the app
+//! pushes (rows from the `PLAYER_QUEST_LOG` descriptor slots, text from the quest template cache),
+//! with the abandon, share and fold intents drained back. The selection lives in the engine, as
+//! `QuestLog_SetSelection` sets and re-reads it in one call (`QuestLogFrame.lua:318`, `:342`). The
+//! abandon mark and the share hold the quest id selected at the click, as the reference's mark
+//! does (`0x4dfb50` copies the selection `0xbb7480`, a quest id, to `0xbb7484`), so a re-index
+//! before the popup's Yes cannot retarget them.
 //!
-//! Two engine-owned bits deliberately live *in the model*, not the pushed state:
-//!
-//! - **The selection** (`SelectQuestLogEntry`/`GetQuestLogSelection`). In the reference client the
-//!   selection is native and *synchronous* — `QuestLogTitleButton_OnClick` calls
-//!   `SelectQuestLogEntry(i)` then immediately re-reads `GetQuestLogSelection()` in the same click
-//!   (ref `QuestLogFrame.lua:318,308-346`); a drain-next-frame intent would read stale. The app
-//!   reads it back each frame ([`super::UiScript::quest_log_selection`]) only to RE-POINT it across
-//!   a rebuild. The **detail that selection names is resolved at call time**, off the row's own
-//!   [`QuestLogEntryView::detail`] — never from a selection baked into the push (decision 2247).
-//!   The reference's detail bindings peek its quest cache inside the same call, so
-//!   `SelectQuestLogEntry(i)` immediately changes what `GetQuestLogQuestText()` answers; resolving
-//!   one detail per push instead made a whole log walk answer with a single row's text.
-//! - **The abandon mark** (`SetAbandonQuest`/`GetAbandonQuestName`/`AbandonQuest`) — the ref's
-//!   two-step confirm (mark on button click, act on the popup's Yes — ref `QuestLogFrame.xml:463-472`,
-//!   `StaticPopup.lua:749-761`). The mark is the selected **quest id** at click time, as the
-//!   reference's is (`0x4dfb50` copies the selection `0xbb7480`, which holds a quest id, into
-//!   `0xbb7484`), so a log that re-indexes between click and confirm — a fold, a quest arriving
-//!   or leaving — can't retarget the abandon.
-//!
-//! A third engine-owned bit joined later: the **watch set** (`IsQuestWatched`/`AddQuestWatch`/
-//! `RemoveQuestWatch`/`GetNumQuestWatches`/`GetQuestIndexForWatch`) — keyed by the entries' stable
-//! [`QuestLogEntryView::quest_id`] under the index-based Era API, pruned on push, cap 5.
-//!
-//! A fourth engine-owned bit is the **countdown** (`GetQuestTimers`/`GetQuestIndexForTimer`/
-//! `GetQuestLogTimeLeft`, decision 1150): the snapshot carries each row's absolute deadline and the
-//! bindings subtract the live server clock per call, so the reference's `QuestTimerFrame` can tick
-//! from its OnUpdate without the log snapshot changing under it. [`seconds_left`] carries the
-//! reference's byte-verified formula and the ways a row has no timer to show (decision 1154).
-//!
-//! A fifth is the **share** (`GetQuestLogPushable`/`QuestLogPushQuest`, decision 1733): the
-//! pushable bit rides each entry (from the app's template cache) and the click resolves the
-//! selection to a quest id before it queues, so a log shuffle cannot retarget it.
-//!
-//! v1 scope (the deliberate `nil`/false stubs, each a later slice): the party quest-log tooltip
-//! (`IsUnitOnQuest` — it needs the party members' own logs, which is a different wire),
-//! reward spells (`GetQuestLogRewardSpell`), and zone
-//! **headers** ([`QuestLogEntryView::is_header`] is plumbed but the app pushes a flat list —
-//! headers need the QuestSort/AreaTable DBC join).
+//! Not built: `IsUnitOnQuest` and `GetAbandonQuestItems` answer nil; the first needs the party
+//! members' quest logs.
 
 use mlua::{Lua, MultiValue, Value};
 
@@ -49,143 +15,99 @@ use super::binding_abi::{flag, number_arg};
 use super::quest::QuestItemView;
 use super::Model;
 
-/// One quest-log list row — the `GetQuestLogTitle` tuple's data half. Plain data; its 1-based
-/// position in [`QuestLogState::entries`] is the quest-log index the whole API keys on.
+/// One quest-log row; its 1-based position in [`QuestLogState::entries`] is the index every verb
+/// takes.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct QuestLogEntryView {
-    /// The quest id occupying the row's descriptor slot. Never surfaced to Lua (no Era API returns
-    /// it) — it is the engine's *stable identity* for the watch set ([`install`]'s
-    /// `AddQuestWatch`/…): watching by id survives the log shuffling under the index-based API
-    /// (an abandon compacts the rows; a watched *index* would silently retarget).
+    /// The slot's quest id, never returned to Lua; watches, marks and shares key on it, as
+    /// indexes shift.
     pub quest_id: u32,
-    /// The quest title (row label).
     pub title: String,
-    /// The quest's display level (`GetQuestLogTitle` return 2; the ref colors the row by it).
+    /// `GetQuestLogTitle`'s return 2, which colors the stock row.
     pub level: u32,
-    /// The quest tag suffix — the bare word, no parentheses: `Elite`, `Dungeon`, `Raid`, `PvP`,
-    /// `Life`, `World Event`, `Legendary`. `None` for a plain quest, which is most of them, and
-    /// always `None` on a header row. The app resolves it from the cached
-    /// `SMSG_QUEST_QUERY_RESPONSE` template's `Type` through `QuestInfo.dbc`
-    /// ([`benilla_formats::QuestTagNames`]); `Type` 0 names no row and takes no tag.
-    ///
-    /// `None`, never `Some("")` — the reference's row Lua branches on the tag's PRESENCE
-    /// (`if ( questTag )`, ref `QuestLogFrame.lua:194`) to decide whether to shrink the title and
-    /// reseat the watch check, so an empty string would take the wrong branch.
+    /// The bare tag word (`Elite`, `Dungeon`, `Raid`, …) from the template's `Type` through
+    /// `QuestInfo.dbc`; the stock row adds the parentheses (`QuestLogFrame.lua:195`). `None`,
+    /// never `Some("")`, for no tag: the row branches on its presence (`QuestLogFrame.lua:194`).
     pub tag: Option<String>,
-    /// A zone header row (the app synthesizes these from each quest's ZoneOrSort).
+    /// A zone header row, which the app builds from each quest's `ZoneOrSort`.
     pub is_header: bool,
-    /// Whether this quest may be SHARED with the party — `GetQuestLogPushable`'s answer for the
-    /// row (decision 1733). Computed app-side from the cached `SMSG_QUEST_QUERY_RESPONSE`
-    /// template's `QUEST_FLAGS_SHARABLE` (`0x8`), so a row whose template has not answered yet is
-    /// `false` and turns true when it lands — the reference's own shape, since it reads the same
-    /// cache. Never surfaced as a per-index Lua getter: the Era API asks only about the current
-    /// selection.
+    /// `GetQuestLogPushable`: the template's `QUEST_FLAGS_SHARABLE` (`0x8`), false until the
+    /// template arrives, as the reference reads the same cache.
     pub pushable: bool,
-    /// A COLLAPSED header (`GetQuestLogTitle`'s isCollapsed; meaningless on quest rows). The app
-    /// owns the collapse set and omits a collapsed header's quests from `entries` — the engine
-    /// only reports the flag and drains the toggle intents ([`super::UiScript::take_quest_log_collapses`]).
+    /// A collapsed header (`isCollapsed`), whose quests the app leaves out of `entries`.
     pub collapsed: bool,
-    /// Whole-quest state from the descriptor slot's state byte: `1` complete, `-1` failed, `0`
-    /// in progress (`GetQuestLogTitle`'s `isComplete` is `1`/`-1`/`nil` off this).
+    /// The slot state: `1` complete, `-1` failed, `0` in progress (`isComplete` 1, -1 or nil).
     pub complete: i32,
-    /// A timed quest's **deadline**, as the descriptor slot carries it: absolute unix-epoch
-    /// seconds (`time(nullptr) + limitTime`, vmangos `Player::AddQuest`), `0` when the quest is
-    /// untimed. Deliberately the raw stamp and not a remaining-seconds count: a remaining count
-    /// would change every second, and this snapshot is diffed by the app to decide whether to fire
-    /// `QUEST_LOG_UPDATE` — a live number in here would rebuild the whole quest log every frame.
-    /// The countdown is subtracted per call instead, against [`super::Model::server_unix_time`]
-    /// (decision 1150).
+    /// The slot's deadline in unix seconds (`time(nullptr) + limitTime`, vmangos
+    /// `Player::AddQuest`), 0 when untimed. A stamp, not a countdown: the app diffs this snapshot
+    /// to fire `QUEST_LOG_UPDATE`, so a live number here would rebuild the log every frame.
     pub timer: u32,
-    /// The formatted objective lines for THIS entry (`GetNumQuestLeaderBoards(i)` /
-    /// `GetQuestLogLeaderBoard(j, i)` serve any index off these — the watch tracker HUD reads
-    /// non-selected quests' lines). The selection's no-arg reads come from here too; the
-    /// [`QuestLogDetail`] carries only what exists for the selection alone
-    /// (description/rewards/money).
+    /// This row's objective lines; the leaderboard verbs serve any row, selected or not.
     pub objectives: Vec<QuestLogObjectiveView>,
-    /// This row's detail pane — description, money, rewards, reward spell. **Per row, not per
-    /// selection** (decision 2247): the reference's detail bindings read `ds:0xbb7480` (what
-    /// `SelectQuestLogEntry 0x4dfae0` wrote, synchronously) and then PEEK the quest cache in the
-    /// same call (`0x4e1130` -> `0xc0e1b0`/`0x562a40`), so a
-    /// select-then-read pair inside ONE frame answers about the row just selected. Carrying one
-    /// detail for "the selection" instead made `SelectQuestLogEntry` inert until the next push:
-    /// every entry of an addon's log walk answered with whichever row the snapshot happened to be
-    /// built against. `None` on a header row.
+    /// This row's detail pane, `None` on a header. Per row, not per selection: the reference's
+    /// detail verbs read the selection `0xbb7480` that `SelectQuestLogEntry` (`0x4dfae0`) wrote and
+    /// look the quest up in the same call (`0x4e1130` to `0xc0e1b0`, `0x562a40`), so a
+    /// select-then-read answers about the row just selected.
     pub detail: Option<QuestLogDetail>,
 }
 
-/// One objective ("leaderboard") line of the selected quest — the `GetQuestLogLeaderBoard` tuple.
-/// The app pre-formats `text` ("Kobold Vermin slain: 3/10") from the template + slot counters.
+/// One objective line (`GetQuestLogLeaderBoard`), `text` formatted by the app, as
+/// "Kobold Vermin slain: 3/10".
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct QuestLogObjectiveView {
-    /// The display line, fully formatted.
     pub text: String,
-    /// The objective kind (`"monster"` / `"item"` / `"object"` — the Era type string).
+    /// The type string: `"monster"`, `"item"` or `"object"`.
     pub kind: String,
-    /// Whether this objective is done (darkens the line + `(Complete)` suffix in the ref).
+    /// Done: the stock log greys the line and appends `(Complete)` (`QuestLogFrame.lua:389`).
     pub finished: bool,
-    /// The progress numbers `text` was formatted from — the `%d/%d` of the line (`cur` already
-    /// clamped to `req`). Not exposed to Lua (`GetQuestLogLeaderBoard` returns text/type/finished
-    /// only); they exist so the app's progress announce can ask *"did this ADVANCE?"* instead of
-    /// *"did the rendered line change?"*. A text-only diff cannot tell progress from a regression,
-    /// and a quest turn-in produces exactly that regression — the required items are destroyed a
-    /// frame or two before the log slot clears, so the line dips to `0/req` while the quest is
-    /// still in the log (decision 1152 / B237).
+    /// The line's `%d/%d`, `cur` clamped to `req`, not returned to Lua. The app's progress
+    /// announce compares these, as a turn-in destroys the items a frame or two before the slot
+    /// clears and the line dips to `0/req`, which text alone cannot tell from progress.
     pub cur: u32,
     /// See [`Self::cur`].
     pub req: u32,
 }
 
-/// The selected quest's detail pane — resolved by the app from the `QUEST_QUERY_RESPONSE` template
-/// cache (+ item/creature name caches). `None` while the template is still in flight.
+/// A quest's detail pane, from the app's template and name caches.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct QuestLogDetail {
-    /// The long description (`GetQuestLogQuestText` return 1).
+    /// `GetQuestLogQuestText`'s return 1.
     pub description: String,
-    /// The objectives flavor paragraph (`GetQuestLogQuestText` return 2) — *not* the leaderboard
-    /// lines (those live on every [`QuestLogEntryView::objectives`], selection or not).
+    /// `GetQuestLogQuestText`'s return 2, the objectives paragraph, not the leaderboard lines.
     pub objectives_text: String,
-    /// Money the turn-in demands (`GetQuestLogRequiredMoney`), copper.
+    /// `GetQuestLogRequiredMoney`, in copper.
     pub required_money: u32,
-    /// Reward money (`GetQuestLogRewardMoney`), copper.
+    /// `GetQuestLogRewardMoney`, in copper.
     pub reward_money: u32,
-    /// Choice rewards (`GetNumQuestLogChoices`/`GetQuestLogChoiceInfo`).
+    /// `GetNumQuestLogChoices`/`GetQuestLogChoiceInfo`.
     pub choices: Vec<QuestItemView>,
-    /// Fixed rewards (`GetNumQuestLogRewards`/`GetQuestLogRewardInfo`).
+    /// `GetNumQuestLogRewards`/`GetQuestLogRewardInfo`.
     pub rewards: Vec<QuestLogQuestItem>,
-    /// The selected quest's reward spell (`rewSpell` on `SMSG_QUEST_QUERY_RESPONSE`), as
-    /// `GetQuestLogRewardSpell` answers it.
+    /// The template's `rewSpell`, as `GetQuestLogRewardSpell` answers it.
     pub reward_spell: Option<super::quest::QuestRewardSpell>,
 }
 
 /// A quest-log reward row is the same shape as a questgiver panel row.
 pub type QuestLogQuestItem = QuestItemView;
 
-/// The whole quest-log snapshot the app pushes each time it changes. Unlike the questgiver panels
-/// this is durable state, not a window session — an empty log is `entries: []`, never `None`.
+/// The quest-log snapshot the app pushes on each change; an empty log is empty `entries`.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct QuestLogState {
-    /// The list rows, in quest-log (descriptor slot) order. 1-based indexing on the Lua side.
-    /// A collapsed header's quests are OMITTED here (the app filters) — indexes are visible rows;
-    /// their ids ride [`Self::hidden_quest_ids`].
+    /// The visible rows, in log order; a collapsed header's quests are left out.
     pub entries: Vec<QuestLogEntryView>,
-    /// The total quest count INCLUDING quests hidden under collapsed headers — the "Quests: N/20"
-    /// pill must not shrink when a header collapses (`GetNumQuestLogEntries` return 2).
+    /// `GetNumQuestLogEntries`'s return 2: every quest, folded ones included, for the
+    /// "Quests: N/20" count (`QuestLogFrame.lua:290`).
     pub num_quests: u32,
-    /// The ids of the quests folded under a collapsed header — in the log, absent from
-    /// [`Self::entries`]. No getter indexes them; they exist for the **watch prune** alone, which
-    /// in the reference scans the whole row array, hidden rows included (`0x4de7a7`–`0x4de80f`;
-    /// a collapsed-group quest is still a row there, sorted past the visible window). Without them
-    /// a collapse would read as the
-    /// quest leaving the log and silently drop its watch.
+    /// Quests folded under a collapsed header: in the log, not in `entries`. Their watches and
+    /// abandon marks hold, as the reference's watch prune (`0x4de7a7` to `0x4de80f`) and abandon
+    /// search (`0xbb71c0`) cover every row, folded ones included.
     pub hidden_quest_ids: Vec<u32>,
 }
 
 impl super::UiScript {
-    /// Push the quest-log snapshot (the app calls this whenever slots/templates/selection change).
-    /// Also prunes the watch set: a watched quest that left the log (abandon/turn-in) drops its
-    /// watch — the rebuild's prune `0x4de7a7`–`0x4de80f`, which keeps a watch while ANY non-header
-    /// row carries its id, visible or [hidden](QuestLogState::hidden_quest_ids). A collapse is
-    /// not a removal: the reference's `0x4ded30` re-sorts and recounts and never prunes.
+    /// Push the quest-log snapshot, dropping the watch of a quest that left the log: the
+    /// reference's prune (`0x4de7a7` to `0x4de80f`) keeps a watch while any quest row, visible or
+    /// folded, carries its id, and a collapse (`0x4ded30`) never prunes.
     pub fn set_quest_log(&mut self, state: QuestLogState) {
         let mut model = self.model_mut();
         model.quest_log_watched.retain(|id| {
@@ -198,100 +120,63 @@ impl super::UiScript {
         model.quest_log = state;
     }
 
-    /// The watched quest ids, in watch order — the app fires `QUEST_WATCH_UPDATE` when a watched
-    /// quest's objectives change, and this is how it knows which those are.
+    /// The watched quest ids, in watch order.
     pub fn quest_log_watched(&self) -> Vec<u32> {
         self.model_ref().quest_log_watched.clone()
     }
 
-    /// The engine-owned 1-based selection (`SelectQuestLogEntry`'s last value; `0` = none) — the
-    /// app reads it each frame to know which quest's detail to resolve and push.
+    /// The 1-based selection, 0 for none; the app reads it to re-point it across a rebuild.
     pub fn quest_log_selection(&self) -> u32 {
         self.model_ref().quest_log_selection
     }
 
-    /// Drain the abandon intents: the QUEST ID `SetAbandonQuest` marked at click time, confirmed
-    /// by the popup's `AbandonQuest()`. The app maps id → descriptor slot →
-    /// `CMSG_QUESTLOG_REMOVE_QUEST`.
+    /// Drain the abandons, quest ids marked by `SetAbandonQuest` and confirmed by
+    /// `AbandonQuest()`; the app sends each slot's `CMSG_QUESTLOG_REMOVE_QUEST`.
     pub fn take_quest_log_abandons(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().quest_log_abandons)
     }
 
-    /// Drain the share intents: the quest ids `QuestLogPushQuest()` queued, already resolved from
-    /// the selection at click time. The app sends one `CMSG_PUSHQUESTTOPARTY` per id.
+    /// Drain the shares `QuestLogPushQuest()` queued, as quest ids; the app sends one
+    /// `CMSG_PUSHQUESTTOPARTY` each.
     pub fn take_quest_log_pushes(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().quest_log_pushes)
     }
 
-    /// Drain the escort-confirm answers: how many times `ConfirmAcceptQuest()` was called. A
-    /// count, because the verb carries no quest id (decision 1733) — the app answers the confirm
-    /// it is holding.
+    /// Drain the `ConfirmAcceptQuest()` calls as a count: the verb carries no quest id, so the app
+    /// answers the confirm it holds.
     pub fn take_quest_confirms(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().quest_confirms)
     }
 
-    /// Drain the header collapse/expand intents: `(1-based entry index, collapse)` from
-    /// `CollapseQuestHeader`/`ExpandQuestHeader` — index `0` = ALL headers (the ref's
-    /// collapse-all button passes 0, QuestLogFrame.lua:557/:561). The app owns the collapse
-    /// set and re-feeds the filtered list (same intent pattern as the abandons above).
+    /// Drain `CollapseQuestHeader`/`ExpandQuestHeader` as `(1-based index, collapse)`; index 0
+    /// is every header, as the collapse-all button passes (`QuestLogFrame.lua:557`, `:561`).
     pub fn take_quest_log_collapses(&mut self) -> Vec<(u32, bool)> {
         std::mem::take(&mut self.model_mut().quest_log_collapses)
     }
 
-    /// Set the engine-owned 1-based selection from the app side — the collapse/expand rebuild
-    /// shifts entry indexes, and the app re-points the selection at the SAME quest's new index
-    /// (selection is an index to the Era API, but an identity to the player).
+    /// Set the selection, re-pointed by the app at the same quest when a rebuild shifts the rows.
     pub fn set_quest_log_selection(&mut self, i: u32) {
         self.model_mut().quest_log_selection = i;
     }
 
-    /// Push the server's wall clock (unix-epoch seconds) — the app's `SMSG_QUERY_TIME_RESPONSE`
-    /// sample, advanced monotonically. Every countdown the engine answers is subtracted against
-    /// this, so it is pushed each frame rather than on change (decision 1150).
-    ///
-    /// This is the reference's `G` in a different frame of reference, and it is worth naming the
-    /// equivalence because the two look nothing alike. The client stores only an **offset**
-    /// `G = local_epoch@sync − server_epoch@sync` and computes `deadline + G − localNow()`; we
-    /// store the server stamp and advance it monotonically, i.e. `deadline − serverNow()`.
-    /// Expand either and both reduce to `remaining_at_sync − elapsed`. The one behavioural
-    /// difference is deliberate and in our favour: a local wall-clock step mid-session (an NTP
-    /// correction, a manual change) jumps the reference's countdown and cannot move ours
-    /// (decision 1154).
+    /// Push the server clock in unix seconds each frame: the app's `SMSG_QUERY_TIME_RESPONSE`
+    /// sample, advanced monotonically. The reference keeps an offset `G = local - server` from the
+    /// sync and computes `deadline + G - localNow()`, the same value. Deviation: a local clock
+    /// step mid-session (an NTP correction) jumps the reference's countdown but not ours, because
+    /// the step changes no time the quest has left.
     pub fn set_server_unix_time(&mut self, unix_secs: f64) {
         self.model_mut().server_unix_time = Some(unix_secs);
     }
 }
 
-/// The signed seconds remaining on a quest-log row's timer, or `None` when the row has no timer at
-/// all. **This is the reference's own formula**, byte-verified (decision 1154):
-///
-/// ```text
-/// value = slot.timer + G − now − 1
-/// ```
-///
-/// — computed identically by all four of its consumers (`0x4e0905`, `0x4e14b9`, `0x4e16c9`,
-/// `0x4de6b6`). Our `now` already carries `G` folded in (see [`super::UiScript::set_server_unix_time`]),
-/// so what is left here is the deadline, the clock, and **the `−1`**.
-///
-/// That `−1` is not a rounding artefact to tidy away: a quest expiring exactly `N` seconds after
-/// the sampled clock reads `N − 1`, and its last second reads `0`. The bias is downward by
-/// construction — the reference never overstates the time a player has left, and neither do we.
-///
-/// Three ways there is nothing to show, each a deliberate answer rather than a fallthrough:
-///
-/// - `timer == 0` — the quest is untimed. The overwhelming majority of rows, and header rows too
-///   (the app pushes them with no timer, matching the reference's own header skip at `0x4e1460`).
-/// - The row is **failed** (`complete < 0`). vmangos writes the slot timer to the literal `1` and
-///   sets the state's FAIL bit when a timed quest runs out (`Player::FailQuest`,
-///   `Player.cpp:13430`), and the row *stays in the log* until the player abandons it. The
-///   reference tests the same bit **before** the arithmetic (`test byte [slot+0x7],0x2` at each of
-///   the four sites), so that `1` never reaches a subtraction there either.
-/// - No server clock yet — the deadline is an absolute stamp in the server's epoch and there is
-///   nothing honest to subtract from it. The reference agrees exactly: its `G == 0` is the
-///   never-synced sentinel and `GetQuestLogTimeLeft` answers nil on it.
-///
-/// A **negative** result is returned as such: the two list bindings drop the row (the reference's
-/// `js` at `0x4e14c5`), while `GetQuestLogTimeLeft` clamps it at 0. Same split, same reason.
+/// Signed seconds left on a row's timer, by the reference's formula at all four of its sites
+/// (`0x4e0905`, `0x4e14b9`, `0x4e16c9`, `0x4de6b6`): `slot.timer + G - now - 1`, `G` folded into
+/// `now`, so a quest's last second reads 0. A negative value drops the row from the lists (`js` at
+/// `0x4e14c5`) and clamps to 0 in `GetQuestLogTimeLeft`. `None` when there is nothing to show:
+/// - an untimed row, or a header (skipped at `0x4e1460`);
+/// - a failed row: vmangos sets its timer to 1 (`Player.cpp:13430`), and the reference tests the
+///   fail bit `[slot+0x7] & 0x2` first;
+/// - no server clock yet, the reference's never-synced `G == 0`.
 fn seconds_left(entry: &QuestLogEntryView, now: Option<f64>) -> Option<i64> {
     if entry.timer == 0 || entry.complete < 0 {
         return None;
@@ -300,8 +185,7 @@ fn seconds_left(entry: &QuestLogEntryView, now: Option<f64>) -> Option<i64> {
     Some((f64::from(entry.timer) - now - 1.0).floor() as i64)
 }
 
-/// The list bindings' view: seconds remaining, and only for a row that still has some. Drops the
-/// expired rows the reference's `js` drops.
+/// [`seconds_left`] for the list verbs, which drop an expired row as the reference's `js` does.
 fn live_seconds_left(entry: &QuestLogEntryView, now: Option<f64>) -> Option<i64> {
     seconds_left(entry, now).filter(|&s| s >= 0)
 }
@@ -310,8 +194,7 @@ fn live_seconds_left(entry: &QuestLogEntryView, now: Option<f64>) -> Option<i64>
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetNumQuestLogEntries() → numEntries, numQuests (headers count toward the first only —
-    // ref QuestLogFrame.lua:108; flat v1 pushes no headers so the two are equal).
+    // `numEntries` counts header rows, `numQuests` only quests (`QuestLogFrame.lua:108`).
     g.set(
         "GetNumQuestLogEntries",
         lua.create_function(|lua, ()| {
@@ -321,20 +204,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetQuestLogTitle(i) → title, level, tag, isHeader, isCollapsed, isComplete
-    // (the load-bearing 6-tuple — ref QuestLogFrame.lua:144/:272/:321/:571).
-    // `tag` is the bare word (`Elite`, `Raid`, …) or nil — the ref's Lua wraps it in the
-    // parentheses itself (`"("..questTag..")"`, ref l.195). isComplete is 1 / -1 / nil.
-    //
-    // **The arity is always SIX, and the two failure shapes are different** (`0x4df930`): a
-    // MISSING or non-number
-    // argument raises `Usage:` (shape A — [`number_arg`], truncating toward zero like the
-    // reference's `_ftol`), while an out-of-range NUMBER is not an error at all — it returns
-    // `nil, 0, nil, nil, nil, nil` off `mov eax,6` at all three exits. Return 2 is the NUMBER
-    // `0` there, never nil, and it is `0` for a header row too. We used to answer a single
-    // `Nil` for both, which reads the same through the reference's own
-    // `local t, l, … = GetQuestLogTitle(i)` (Lua pads with nil) but hands an addon doing
-    // arithmetic on the level a nil where the client gives it a zero.
+    // `title, level, tag, isHeader, isCollapsed, isComplete`, always six (`0x4df930`). The index
+    // truncates as `_ftol` does, and a missing or non-number one raises `Usage:`; out of range it
+    // answers `nil, 0, nil, nil, nil, nil`, and a header's level is 0 too.
     g.set(
         "GetQuestLogTitle",
         lua.create_function(|lua, i: Value| {
@@ -365,12 +237,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 0 => Value::Nil,
                 c => Value::Integer(i64::from(c.signum())),
             };
-            // **Returns 4 and 5 are `1`/`nil`, NOT booleans**: `isHeader` is `1` on a header row
-            // and `nil` on a quest; `isCollapsed` is `1` only for a header whose bit in
-            // `[0xbb748c]` is clear — a quest row and an EXPANDED header both answer `nil`. We
-            // pushed `true`/`false`, which every `if ( isHeader )` in FrameXML reads the same and
-            // which `isHeader == false` or a `type()` test does not. The two are one expression
-            // here because `collapsed` is meaningless off a header (the field's own doc).
+            // Returns 4 and 5 are 1 or nil, never booleans; `isCollapsed` is 1 only on a header
+            // whose bit in `[0xbb748c]` is clear.
             let flag = |b: bool| if b { Value::Integer(1) } else { Value::Nil };
             Ok(MultiValue::from_vec(vec![
                 Value::String(lua.create_string(&e.title)?),
@@ -383,7 +251,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SelectQuestLogEntry(i) — the synchronous, engine-owned selection (see module doc).
     g.set(
         "SelectQuestLogEntry",
         lua.create_function(|lua, i: u32| {
@@ -393,7 +260,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetQuestLogSelection() → the 1-based selection, 0 = none.
+    // The 1-based selection, 0 for none.
     g.set(
         "GetQuestLogSelection",
         lua.create_function(|lua, ()| {
@@ -402,8 +269,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetQuestLogQuestText() → description, objectivesText (for the selection — the app already
-    // resolved `detail` against it).
     g.set(
         "GetQuestLogQuestText",
         lua.create_function(|lua, ()| {
@@ -421,9 +286,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetNumQuestLeaderBoards([questIndex]) — objective-line count for the given entry (1-based),
-    // defaulting to the selection. Any index answers (the watch tracker HUD reads non-selected
-    // quests' lines — ref QuestLogFrame.lua:613-663).
+    // Any row's line count, the selection's by default: the watch tracker reads unselected quests
+    // (`QuestLogFrame.lua:616`).
     g.set(
         "GetNumQuestLeaderBoards",
         lua.create_function(|lua, i: Option<u32>| {
@@ -437,7 +301,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetQuestLogLeaderBoard(i[, questIndex]) → text, type, finished — same any-index rule.
+    // `text, type, finished` of line `i`, for any row as above (`QuestLogFrame.lua:635`).
     g.set(
         "GetQuestLogLeaderBoard",
         lua.create_function(|lua, (i, quest): (usize, Option<u32>)| {
@@ -461,7 +325,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ── Detail counts + money ─────────────────────────────────────────────────────────────────────
+    // ── Detail counts + money ────────────────────────────────────────────────────────────────────
     fn install_detail_count(
         lua: &Lua,
         name: &str,
@@ -482,9 +346,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         i64::from(d.required_money)
     })?;
 
-    // GetQuestLogChoiceInfo(i) / GetQuestLogRewardInfo(i) → name, texture, numItems, quality,
-    // isUsable — the same 5-tuple as the giver panels' GetQuestItemInfo (they share one layout
-    // routine in the ref — QuestFrame.lua:311-522).
+    // `name, texture, numItems, quality, isUsable`, the giver panels' shape, as one stock routine
+    // lays out both (`QuestFrameItems_Update`, `QuestFrame.lua:311`).
     fn install_detail_item(
         lua: &Lua,
         name: &str,
@@ -516,7 +379,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     Value::Integer(i64::from(it.count)),
                     Value::Integer(i64::from(it.quality)),
                     Value::Boolean(it.usable),
-                    // Benilla extension (6th): the item id, the shared tooltip store's key.
+                    // The item id, `BenillaGetItemStats`'s key, a sixth return that is not 1.12's.
                     Value::Integer(i64::from(it.item_id)),
                 ]))
             })?,
@@ -525,14 +388,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     install_detail_item(lua, "GetQuestLogChoiceInfo", |d| &d.choices)?;
     install_detail_item(lua, "GetQuestLogRewardInfo", |d| &d.rewards)?;
 
-    // GetQuestLogItemLink(type, index) → the full escaped `|cff…|Hitem:…|h[Name]|h|r` | nil — the
-    // quest log's twin of `GetQuestItemLink` ([`super::quest`]), read by the reward rows' ctrl/shift
-    // click arms: `DressUpItemLink(GetQuestLogItemLink(this.type, this:GetID()))` (ref
-    // QuestLogFrame.lua:545) and the `ChatFrameEditBox:Insert(...)` beside it (l.549). Unlike the
-    // *Info* pair above this one is kind-DISPATCHED, because that is the shape the reference's own
-    // handler calls it with (`this.type` is "choice"/"reward", set by the shared
-    // `QuestFrameItems_Update`); an unknown type, an out-of-range index, or a row whose template
-    // answer is still in flight all read nil. Decisions 1059/1060.
+    // The item's escaped link, for the reward rows' ctrl and shift clicks (`QuestLogFrame.lua:545`,
+    // `:549`), keyed by `this.type`, "choice" or "reward" (set by `QuestFrameItems_Update`). An
+    // unknown type, an index out of range or a template not yet arrived answers nil.
     g.set(
         "GetQuestLogItemLink",
         lua.create_function(|lua, (kind, index): (String, usize)| {
@@ -557,8 +415,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsCurrentQuestFailed() → 1/nil: the selection's slot state is FAIL (ref appends
-    // " - (Failed)").
+    // 1 or nil, whether the selected slot has failed; the stock title then appends " - (Failed)"
+    // (`QuestLogFrame.lua:354`).
     g.set(
         "IsCurrentQuestFailed",
         lua.create_function(|lua, ()| {
@@ -572,10 +430,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ── The abandon two-step (mark → confirm) ─────────────────────────────────────────────────────
-    // CollapseQuestHeader(i)/ExpandQuestHeader(i) — header fold intents, drained by the app
-    // (which owns the collapse set and re-feeds the filtered list). Index 0 = ALL headers (the
-    // ref's collapse-all button, QuestLogFrame.lua:557/:561). Same intent pattern as the abandons.
+    // Header folds, drained by the app, which owns the collapse set; index 0 is every header.
     g.set(
         "CollapseQuestHeader",
         lua.create_function(|lua, i: u32| {
@@ -593,11 +448,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetAbandonQuest() — mark the selected QUEST as the abandon target (ref
-    // QuestLogFrame.xml:464). The reference's `0x4dfb50` is `mov eax,[0xbb7480]; mov [0xbb7484],eax`:
-    // it copies the selection, and the selection is a quest id (`0x4def30` stores the row's +0x0
-    // at `0x4def5d`). Ours holds the selection as a row index, so the id is resolved here, at the
-    // click — never at the confirm, when the rows may have moved.
+    // ── The abandon two-step (mark → confirm) ────────────────────────────────────────────────────
+    // Marks the selected quest (`QuestLogFrame.xml:464`). The reference's `0x4dfb50` copies the
+    // selection, which there is a quest id (`0x4def30` stores it at `0x4def5d`); ours is a row
+    // index, so the id is resolved here, at the click, before the rows can move.
     g.set(
         "SetAbandonQuest",
         lua.create_function(|lua, ()| {
@@ -611,9 +465,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // GetAbandonQuestName() → the marked quest's title ("" when none — the popup shows it). The
-    // reference (`0x4dfb60`) peeks its quest cache by the marked id; the rows carry the same
-    // cached title.
+    // The marked quest's title, "" for none; the reference (`0x4dfb60`) reads the quest cache by
+    // id, the source of the rows' titles too.
     g.set(
         "GetAbandonQuestName",
         lua.create_function(|lua, ()| {
@@ -631,17 +484,13 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(Value::String(lua.create_string(&title)?))
         })?,
     )?;
-    // GetAbandonQuestItems() → nil in v1 (the "you will also lose these quest items" list needs
-    // the template's SrcItem/required-item join against the bags — a dressing follow-up).
+    // Not built: nil, so the popup never lists the quest items an abandon destroys.
     g.set(
         "GetAbandonQuestItems",
         lua.create_function(|_, ()| Ok(Value::Nil))?,
     )?;
-    // AbandonQuest() — the popup's Yes (`0x4dfe00` → `0x4df070`). The reference searches its
-    // whole row table `0xbb71c0` (folded quests included) for a quest row carrying the marked id;
-    // a hit sends that row's slot and clears the mark, a miss does nothing and KEEPS the mark.
-    // Ours checks the same membership — a visible quest row, or one folded under a collapsed
-    // header — and queues the id; the app resolves it to the slot.
+    // The popup's Yes (`0x4dfe00` to `0x4df070`): the reference searches every row, folded ones
+    // included (`0xbb71c0`), for the marked id; a hit sends and clears the mark, a miss keeps it.
     g.set(
         "AbandonQuest",
         lua.create_function(|lua, ()| {
@@ -662,16 +511,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ── Timed quests (decision 1150) ─────────────────────────────────────────────────────────────
-    // The engine owns the countdown, as the reference's C bindings do: the pushed snapshot carries
-    // each row's absolute DEADLINE, and these subtract the live server clock per call. That split
-    // is what lets the ref's QuestTimerFrame re-read GetQuestTimers() every OnUpdate and paint a
-    // ticking number, while `set_quest_log` only fires QUEST_LOG_UPDATE when the log really moves.
+    // ── Timed quests ─────────────────────────────────────────────────────────────
 
-    // GetQuestTimers() → seconds remaining, ONE RETURN PER TIMED QUEST, in quest-log order — a
-    // genuine vararg return (the ref reads it as `QuestTimerFrame_Update(GetQuestTimers())` and
-    // walks `arg.n`, QuestTimerFrame.lua:11/:19). No timed quests → no values at all, which is the
-    // ref's own "hide the frame" signal.
+    // One return per live timer, in log order, re-read every OnUpdate: `QuestTimerFrame_Update`
+    // takes them as varargs and hides on none (`QuestTimerFrame.lua:11`, `:26`, `:37`).
     g.set(
         "GetQuestTimers",
         lua.create_function(|lua, ()| {
@@ -689,11 +532,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetQuestIndexForTimer(timerIndex) → the 1-based QUEST-LOG index that timer belongs to (the
-    // same index space GetQuestLogTitle takes — headers included, since the app pushes them into
-    // the same list). The ref's timer buttons carry their 1-based ordinal as the frame id and map
-    // back through this for the click and the hover tooltip (QuestTimerFrame.lua:43,
-    // QuestTimerFrame.xml:20). Out of range → nil.
+    // A timer's 1-based row, headers counted, for the timer buttons' click and tooltip
+    // (`QuestTimerFrame.lua:43`, `QuestTimerFrame.xml:20`).
     g.set(
         "GetQuestIndexForTimer",
         lua.create_function(|lua, t: usize| {
@@ -716,9 +556,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetQuestLogTimeLeft() → the SELECTION's seconds remaining, or nil when it has no timer —
-    // the ref branches on exactly that nil to show or hide its "Time Remaining:" row and to
-    // re-anchor the objectives beneath it (QuestLogFrame.lua:364-374).
+    // The selection's seconds left, nil without a timer, which hides the stock "Time Remaining:"
+    // row (`QuestLogFrame.lua:364`).
     g.set(
         "GetQuestLogTimeLeft",
         lua.create_function(|lua, ()| {
@@ -728,17 +567,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 .and_then(|n| model.quest_log.entries.get(n))
                 .and_then(|e| seconds_left(e, model.server_unix_time));
             Ok(match left {
-                // Clamped, not dropped — the reference's own asymmetry against the two list
-                // bindings above (decision 1154).
+                // Clamped where the lists drop the row, as in the reference.
                 Some(s) => Value::Integer(s.max(0)),
                 None => Value::Nil,
             })
         })?,
     )?;
 
-    // ── v1 stubs (each the seam of a named later slice — see the module doc) ─────────────────────
-    // GetQuestLogRewardSpell() → texture, name, isTradeskillSpell (0x4e1130): the selected
-    // quest's reward spell, three nils when it has none.
+    // ── Reward spell and party ───────────────────────────────────────────────────────────────────
+    // `texture, name, isTradeskillSpell` (`0x4e1130`), three nils without a reward spell.
     g.set(
         "GetQuestLogRewardSpell",
         lua.create_function(|lua, ()| {
@@ -755,15 +592,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "IsUnitOnQuest",
         lua.create_function(|_, (_q, _unit): (Value, Value)| Ok(flag(false)))?,
     )?;
-    // ── The quest watch (the on-screen tracker's state — ref QuestLogFrame.lua:469-505 shift-click
-    // toggle, :613-663 QuestWatch_Update). The set lives engine-side, keyed by the entries' stable
-    // quest ids (see QuestLogEntryView::quest_id) while the whole Era API speaks 1-based log
-    // indices; set_quest_log prunes watches whose quest left the log. MAX_WATCHABLE_QUESTS = 5
-    // (ref QuestLogFrame.lua:494) — AddQuestWatch past the cap is a no-op (the Lua shows the
-    // QUEST_WATCH_TOO_MANY error itself, mirroring the ref's guard order).
-    /// The entry the current selection points at — what every no-argument getter on this surface
-    /// reads (`GetQuestLogPushable`, and the C side of `QuestLogPushQuest`). `None` when nothing
-    /// is selected or the selection is out of range.
+    // ── The party share and the quest watch ──────────────────────────────────────────────────────
+    /// The selected row, which the share verbs read.
     fn selected_quest(model: &Model) -> Option<&QuestLogEntryView> {
         (model.quest_log_selection as usize)
             .checked_sub(1)
@@ -776,14 +606,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             .and_then(|n| model.quest_log.entries.get(n))
             .map(|e| e.quest_id)
     }
-    // ── The party share (decision 1733) — the ref's `QuestFramePushQuestButton`, whose enable
-    // predicate is `GetQuestLogPushable() and GetNumPartyMembers() > 0` (QuestLogFrame.lua:299-305)
-    // and whose OnClick is `QuestLogPushQuest()` (QuestLogFrame.xml:511-513). Both speak about the
-    // CURRENT SELECTION and take no argument, exactly as the reference declares them.
-    // `GetQuestLogPushable` returns `1` or **nil**, never `false` (`0x4e12b0` tail-calls
-    // `0x6f3810`/`0x6f37f0`, decision 1738). Both are falsy to the `and` in the reference's own
-    // predicate, so the button reads the same either way — but an addon testing `== nil` would
-    // not, and this is the Era idiom the rest of this surface already speaks (`GetPartyMember`).
+    // The share button enables on `GetQuestLogPushable() and GetNumPartyMembers() > 0`
+    // (`QuestLogFrame.lua:301`) and clicks `QuestLogPushQuest()` (`QuestLogFrame.xml:512`), both
+    // about the selection. `GetQuestLogPushable` answers 1 or nil, never false (`0x4e12b0`).
     g.set(
         "GetQuestLogPushable",
         lua.create_function(|lua, ()| {
@@ -798,12 +623,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "QuestLogPushQuest",
         lua.create_function(|lua, ()| {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // The C verb re-tests everything the Lua predicate tests **and one thing it does not**:
-            // a party check of its own (`0x4e13a6`, decision 1738). The reference does not trust
-            // its own button — an addon or a macro can call this solo, and the send is refused
-            // here rather than reaching the server. Resolve the id HERE rather than queueing the
-            // index (see `Model::quest_log_pushes`); a HEADER row carries `quest_id` 0, so an
-            // unguarded resolve would queue a push for quest 0.
+            // The verb checks the party and the sharable bit itself (`0x4e13a6`), as a macro can
+            // call it solo. The id is resolved now; a header's `quest_id` is 0 and never queues.
             if model.party.members.is_empty() {
                 return Ok(());
             }
@@ -816,6 +637,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
+    // The watch tracker's set (`QuestLogFrame.lua:469`, `:613`), keyed by quest id. At most
+    // `MAX_WATCHABLE_QUESTS`, 5 (`QuestLogFrame.lua:8`), which the stock Lua checks before adding
+    // (`:494`); an add past it is a no-op.
     g.set(
         "GetNumQuestWatches",
         lua.create_function(|lua, ()| {
@@ -854,8 +678,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // GetQuestIndexForWatch(watchSlot) → the watched quest's CURRENT 1-based log index (nil if it
-    // somehow isn't in the log — pruning makes that transient at worst).
+    // The watched quest's current 1-based row, nil when it is not a visible row.
     g.set(
         "GetQuestIndexForWatch",
         lua.create_function(|lua, w: usize| {
@@ -952,7 +775,6 @@ mod tests {
     #[test]
     fn entries_and_title_tuple() {
         let mut s = UiScript::new().unwrap();
-        // Empty log: 0, 0; out-of-range title is nil.
         assert_eq!(
             s.eval::<(i64, i64)>("return GetNumQuestLogEntries()")
                 .unwrap(),
@@ -966,7 +788,6 @@ mod tests {
                 .unwrap(),
             (2, 2)
         );
-        // The 6-tuple, in order; complete=0 → nil, complete=1 → 1.
         assert!(s
             .eval::<bool>(
                 "local t, l, tag, h, c, done = GetQuestLogTitle(1)\n\
@@ -982,21 +803,16 @@ mod tests {
             .unwrap());
     }
 
-    /// The arity contract (`0x4df930`): six values ALWAYS, an out-of-range number is not an
-    /// error, and return 2 is the number `0`
-    /// — while a missing or non-number argument raises `Usage:`.
+    /// The shape of `0x4df930`.
     #[test]
     fn out_of_range_is_six_values_with_a_zero_level_and_a_bad_arg_raises() {
         let mut s = UiScript::new().unwrap();
-        // Empty log: the first return is still nil (so the ref's `if ( questLogTitleText )`
-        // reads the same), but the tuple is full and the level is a NUMBER.
         assert_eq!(s.arity("GetQuestLogTitle(1)").unwrap(), 6);
         assert!(s
             .eval::<bool>("local t, l = GetQuestLogTitle(1) return t == nil and l == 0")
             .unwrap());
 
         s.set_quest_log(two_quests());
-        // Index 0 and a negative index are out of range, not errors — same six values.
         for i in ["0", "-1", "99"] {
             assert!(
                 s.eval::<bool>(&format!(
@@ -1006,12 +822,11 @@ mod tests {
                 "index {i} is out of range, not an error"
             );
         }
-        // `_ftol` truncates toward zero, so 1.9 addresses entry 1.
+        // `_ftol` truncates toward zero: 1.9 is entry 1.
         assert!(s
             .eval::<bool>("return GetQuestLogTitle(1.9) == 'A Threat Within'")
             .unwrap());
 
-        // A missing / non-number argument is the other shape.
         for bad in ["", "nil", "{}", "print"] {
             let e = format!(
                 "{:?}",
@@ -1025,8 +840,6 @@ mod tests {
         }
     }
 
-    /// `isHeader`/`isCollapsed`, returns 4 and 5: `1` on a header, `nil` on a quest; `isCollapsed`
-    /// is `1` only for a COLLAPSED header — an expanded one and every quest row answer `nil`.
     #[test]
     fn is_header_and_is_collapsed_are_one_or_nil_never_booleans() {
         let mut s = UiScript::new().unwrap();
@@ -1051,17 +864,14 @@ mod tests {
         );
         s.set_quest_log(state);
 
-        // A collapsed header: both flags are the number 1.
         assert!(s
             .eval::<bool>(
                 "local _, l, _, h, c = GetQuestLogTitle(1) return h == 1 and c == 1 and l == 0"
             )
             .unwrap());
-        // An EXPANDED header: isHeader 1, isCollapsed nil.
         assert!(s
             .eval::<bool>("local _, _, _, h, c = GetQuestLogTitle(2) return h == 1 and c == nil")
             .unwrap());
-        // A quest row: both nil — and `false` would be wrong, so pin the type too.
         assert!(s
             .eval::<bool>(
                 "local _, _, _, h, c = GetQuestLogTitle(3)\n\
@@ -1072,10 +882,6 @@ mod tests {
 
     #[test]
     fn tag_is_the_bare_word_and_nil_when_absent() {
-        // The third return is the BARE word — the ref's own Lua adds the parentheses
-        // (`"("..questTag..")"`, ref QuestLogFrame.lua:195), so pushing "(Elite)" here would
-        // paint "((Elite))". An untagged quest pushes nil, not "", because the ref branches on
-        // presence (`if ( questTag )`, ref l.194).
         let mut s = UiScript::new().unwrap();
         let mut state = two_quests();
         state.entries[1].tag = Some("Elite".into());
@@ -1093,7 +899,6 @@ mod tests {
         let mut s = UiScript::new().unwrap();
         s.set_quest_log(two_quests());
         assert_eq!(s.eval::<i64>("return GetQuestLogSelection()").unwrap(), 0);
-        // The ref's click flow: select then immediately re-read in the same chunk.
         assert_eq!(
             s.eval::<i64>("SelectQuestLogEntry(2); return GetQuestLogSelection()")
                 .unwrap(),
@@ -1102,13 +907,6 @@ mod tests {
         assert_eq!(s.quest_log_selection(), 2);
     }
 
-    /// **The bug decision 2247 fixes, in the shape every addon hits it.** The classic quest-log
-    /// walk — `SelectQuestLogEntry(i)` then `GetQuestLogQuestText()`, once per entry, all inside
-    /// ONE frame with no push between — must answer about the row just selected. It used to answer
-    /// with whichever row the snapshot had been built against, for every entry: Questie 3.7.1 fed
-    /// that text to its `getQuestHash` Levenshtein match and wrote the WRONG same-name chain step
-    /// into a character's saved history (two of the director's Tirisfal quests, both resolved to
-    /// the shortest sibling — the signature of matching against an unrelated string).
     #[test]
     fn a_log_walk_answers_per_entry_without_a_push_between() {
         let mut s = UiScript::new().unwrap();
@@ -1130,7 +928,6 @@ mod tests {
         );
     }
 
-    /// The same seam for the money/reward getters, which read the detail through their own path.
     #[test]
     fn the_detail_counts_follow_the_selection_too() {
         let mut s = UiScript::new().unwrap();
@@ -1152,8 +949,6 @@ mod tests {
         );
     }
 
-    /// A header row has no quest under it, so its detail reads as nothing at all rather than as
-    /// the previous selection's — the same staleness, one row over.
     #[test]
     fn a_header_selection_has_no_detail() {
         let mut s = UiScript::new().unwrap();
@@ -1189,7 +984,6 @@ mod tests {
             s.eval::<i64>("return GetNumQuestLeaderBoards()").unwrap(),
             1
         );
-        // The optional-arg form answers for ANY entry (the tracker HUD's path).
         assert_eq!(
             s.eval::<i64>("return GetNumQuestLeaderBoards(1)").unwrap(),
             1
@@ -1225,9 +1019,6 @@ mod tests {
             .eval::<bool>("return GetQuestLogChoiceInfo(1) == nil")
             .unwrap());
 
-        // GetQuestLogItemLink: kind-dispatched (the shape the ref's QuestLogRewardItem_OnClick
-        // calls it with — `this.type`), nil for the empty choice list, an out-of-range index and
-        // an unknown type.
         assert_eq!(
             s.eval::<String>("return GetQuestLogItemLink(\"reward\", 1)")
                 .unwrap(),
@@ -1253,12 +1044,10 @@ mod tests {
             s.eval::<String>("return GetAbandonQuestName()").unwrap(),
             "Kobold Camp Cleanup"
         );
-        // Selection moves before the confirm — the mark must not follow it. What queues is the
-        // marked QUEST ID (entry 2 is quest 7), never a row index (0x4dfb50).
+        // The mark is the quest id (`0x4dfb50`), not the selection: entry 2 is quest 7.
         s.run("SelectQuestLogEntry(1); AbandonQuest()").unwrap();
         assert_eq!(s.take_quest_log_abandons(), vec![7]);
         assert!(s.take_quest_log_abandons().is_empty(), "drained");
-        // A bare AbandonQuest with no mark queues nothing.
         s.run("AbandonQuest()").unwrap();
         assert!(s.take_quest_log_abandons().is_empty());
     }
@@ -1282,16 +1071,14 @@ mod tests {
     fn watch_set_is_id_keyed_and_survives_a_log_shuffle() {
         let mut s = UiScript::new().unwrap();
         s.set_quest_log(two_quests());
-        // Watch entry 2 (quest 7); the index-based API reads it back.
-        s.run("AddQuestWatch(2)").unwrap();
+        s.run("AddQuestWatch(2)").unwrap(); // quest 7
         assert_eq!(s.eval::<i64>("return GetNumQuestWatches()").unwrap(), 1);
         assert!(s.eval::<bool>("return IsQuestWatched(2)").unwrap());
         assert!(!s.eval::<bool>("return IsQuestWatched(1)").unwrap());
         assert_eq!(s.eval::<i64>("return GetQuestIndexForWatch(1)").unwrap(), 2);
         assert_eq!(s.quest_log_watched(), vec![7]);
 
-        // The log shuffles: entry 1 (quest 783) is abandoned, quest 7 compacts to index 1 — the
-        // watch FOLLOWS THE QUEST, not the index.
+        // Quest 783 leaves and quest 7 moves to row 1, keeping its watch.
         let mut shuffled = two_quests();
         shuffled.entries.remove(0);
         s.set_quest_log(shuffled);
@@ -1299,7 +1086,6 @@ mod tests {
         assert!(s.eval::<bool>("return IsQuestWatched(1)").unwrap());
         assert_eq!(s.eval::<i64>("return GetQuestIndexForWatch(1)").unwrap(), 1);
 
-        // Unwatch by the new index; and a watched quest leaving the log prunes its watch.
         s.run("RemoveQuestWatch(1)").unwrap();
         assert_eq!(s.eval::<i64>("return GetNumQuestWatches()").unwrap(), 0);
         s.run("AddQuestWatch(1)").unwrap();
@@ -1307,12 +1093,7 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetNumQuestWatches()").unwrap(), 0);
     }
 
-    /// A header's collapse folds its quests out of the visible list but NOT out of the log, and
-    /// the watch prune counts them — the reference's prune (`0x4de7a7`–`0x4de80f`) scans the whole
-    /// row array for a non-header row with the watched id, and a collapsed-group quest is still a
-    /// row there, just sorted past the visible window; the collapse itself (`0x4ded30`) re-sorts
-    /// and recounts only. So watch →
-    /// collapse → expand keeps the watch, and a quest that genuinely LEFT the log still drops it.
+    /// The prune (`0x4de7a7` to `0x4de80f`) counts folded quests; a collapse never prunes.
     #[test]
     fn a_collapsed_header_keeps_its_quests_watched() {
         let header = |collapsed| QuestLogEntryView {
@@ -1331,7 +1112,7 @@ mod tests {
         s.run("AddQuestWatch(3)").unwrap(); // quest 7
         assert_eq!(s.quest_log_watched(), vec![7]);
 
-        // The app's collapsed push: the header alone is visible, both quests are hidden under it.
+        // Collapsed: only the header is visible.
         s.set_quest_log(QuestLogState {
             entries: vec![header(true)],
             num_quests: 2,
@@ -1346,7 +1127,7 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetNumQuestWatches()").unwrap(), 1);
         assert_eq!(s.eval::<i64>("return GetQuestIndexForWatch(1)").unwrap(), 3);
 
-        // Quest 7 leaves the log (turn-in) — neither visible nor hidden — and its watch goes.
+        // Quest 7 leaves the log, neither visible nor folded.
         let mut gone = expanded();
         gone.entries.retain(|e| e.quest_id != 7);
         gone.num_quests = 1;
@@ -1354,39 +1135,28 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetNumQuestWatches()").unwrap(), 0);
     }
 
-    /// The countdown trio (decisions 1150/1154). One deadline stamp in the snapshot, one clock
-    /// pushed beside it, and every read is a live subtraction — so advancing the clock alone (no
-    /// re-push of the log) makes the number fall, which is precisely what the reference's
-    /// per-OnUpdate `GetQuestTimers()` depends on.
-    ///
-    /// Every number below carries the reference's `−1` (`value = deadline + G − now − 1`,
-    /// byte-verified at all four of its consumers): 500 seconds of wall gap reads 499.
+    /// Every value carries the reference's `-1`: 500 seconds to the deadline reads 499.
     #[test]
     fn timers_count_down_against_the_pushed_server_clock() {
         let mut s = UiScript::new().unwrap();
         let mut state = two_quests();
-        // Quest 2 is on a 15-minute leash that ends at unix 1_000_900; quest 1 is untimed.
         state.entries[1].timer = 1_000_900;
         s.set_quest_log(state);
 
-        // No clock sample yet: nothing to subtract from, so nothing is claimed.
+        // No server clock yet.
         assert_eq!(s.arity("GetQuestTimers()").unwrap(), 0);
         assert!(s
             .eval::<bool>("return GetQuestLogTimeLeft() == nil")
             .unwrap());
 
-        // 400 s in.
         s.set_server_unix_time(1_000_400.0);
         assert_eq!(s.arity("GetQuestTimers()").unwrap(), 1);
         assert_eq!(s.eval::<i64>("return (GetQuestTimers())").unwrap(), 499);
-        // The timer maps back to entry 2 — the untimed row 1 does not shift the mapping.
         assert_eq!(s.eval::<i64>("return GetQuestIndexForTimer(1)").unwrap(), 2);
         assert!(s
             .eval::<bool>("return GetQuestIndexForTimer(2) == nil")
             .unwrap());
 
-        // The selection's own reading: nil on the untimed row, the count on the timed one — the
-        // exact branch the ref's "Time Remaining:" row keys on.
         s.run("SelectQuestLogEntry(1)").unwrap();
         assert!(s
             .eval::<bool>("return GetQuestLogTimeLeft() == nil")
@@ -1394,16 +1164,15 @@ mod tests {
         s.run("SelectQuestLogEntry(2)").unwrap();
         assert_eq!(s.eval::<i64>("return GetQuestLogTimeLeft()").unwrap(), 499);
 
-        // Only the CLOCK moves — no set_quest_log — and the number falls anyway.
+        // Only the clock moves, and the number falls.
         s.set_server_unix_time(1_000_880.0);
         assert_eq!(s.eval::<i64>("return GetQuestLogTimeLeft()").unwrap(), 19);
 
-        // The last second reads 0, not 1 — the `−1`'s downward bias at the very end of the window.
+        // The last second reads 0.
         s.set_server_unix_time(1_000_899.0);
         assert_eq!(s.eval::<i64>("return GetQuestLogTimeLeft()").unwrap(), 0);
 
-        // Past the deadline the two bindings SPLIT, exactly as the reference's do: the list drops
-        // the row (its `js`), while GetQuestLogTimeLeft clamps at 0 and keeps answering.
+        // Past the deadline the lists drop the row and `GetQuestLogTimeLeft` clamps to 0.
         s.set_server_unix_time(1_000_910.0);
         assert_eq!(s.eval::<i64>("return GetQuestLogTimeLeft()").unwrap(), 0);
         assert_eq!(s.arity("GetQuestTimers()").unwrap(), 0);
@@ -1412,15 +1181,13 @@ mod tests {
             .unwrap());
     }
 
-    /// A FAILED timed quest shows no timer. vmangos writes the slot timer to the literal `1` and
-    /// sets the FAIL state bit (`Player::FailQuest`), leaving the row in the log until the player
-    /// abandons it — so without the state test the frame would show a clamped "0" for ever.
+    /// vmangos sets a failed quest's timer to 1 and leaves it in the log (`Player::FailQuest`).
     #[test]
     fn a_failed_timed_quest_drops_out_of_the_timer_list() {
         let mut s = UiScript::new().unwrap();
         let mut state = two_quests();
         state.entries[0].timer = 1_000_900;
-        state.entries[1].timer = 1; // failed: the server's own sentinel
+        state.entries[1].timer = 1; // failed: the server's sentinel
         state.entries[1].complete = -1;
         s.set_quest_log(state);
         s.set_server_unix_time(1_000_400.0);
@@ -1450,16 +1217,13 @@ mod tests {
         for i in 1..=6 {
             s.run(&format!("AddQuestWatch({i})")).unwrap();
         }
-        // The sixth add is a no-op (MAX_WATCHABLE_QUESTS = 5, ref QuestLogFrame.lua:494).
+        // `MAX_WATCHABLE_QUESTS` is 5 (`QuestLogFrame.lua:8`).
         assert_eq!(s.eval::<i64>("return GetNumQuestWatches()").unwrap(), 5);
-        // A duplicate add neither grows nor reorders.
         s.run("AddQuestWatch(1)").unwrap();
         assert_eq!(s.eval::<i64>("return GetNumQuestWatches()").unwrap(), 5);
         assert_eq!(s.quest_log_watched(), vec![1, 2, 3, 4, 5]);
     }
 
-    /// `GetQuestLogPushable` answers about the SELECTION, and only about the selection — the Era
-    /// API has no per-index form (decision 1733). Selecting the other quest changes the answer.
     #[test]
     fn pushable_follows_the_selection() {
         let mut s = UiScript::new().unwrap();
@@ -1467,8 +1231,6 @@ mod tests {
         state.entries[0].pushable = true; // 783 is sharable, 7 is not
         s.set_quest_log(state);
 
-        // `1` or nil, never true/false (`0x4e12b0`, decision 1738) — an addon testing `== nil`
-        // sees the reference's own shape.
         assert_eq!(
             s.eval::<Option<i64>>("return GetQuestLogPushable()")
                 .unwrap(),
@@ -1489,16 +1251,14 @@ mod tests {
         );
     }
 
-    /// The abandon mark follows its QUEST across a re-index, and a mark whose quest has left the
-    /// log is a no-op that is KEPT, as `0x4df070`'s miss path is (`ret` before the clear at
-    /// `0x4df0cf`). A quest folded under a collapsed header is still in the log.
+    /// A miss keeps the mark, as `0x4df070` returns before the clear at `0x4df0cf`.
     #[test]
     fn abandon_mark_is_a_quest_id_that_survives_a_reindex() {
         let mut s = UiScript::new().unwrap();
         s.set_quest_log(two_quests());
         s.run("SelectQuestLogEntry(2); SetAbandonQuest()").unwrap(); // quest 7
 
-        // The log re-indexes under the popup: quest 7 is now row 1, and a stranger takes row 2.
+        // Quest 7 moves to row 1 and a stranger takes row 2.
         let mut moved = two_quests();
         moved.entries.swap(0, 1);
         moved.entries[1].quest_id = 999;
@@ -1519,7 +1279,7 @@ mod tests {
         s.run("AbandonQuest()").unwrap();
         assert_eq!(s.take_quest_log_abandons(), vec![7]);
 
-        // Gone from the log: nothing queues, and the mark stays for the quest's return.
+        // Gone from the log: nothing queues, and the mark stays.
         s.set_quest_log(moved.clone());
         s.run("SelectQuestLogEntry(1); SetAbandonQuest()").unwrap();
         let mut gone = moved.clone();
@@ -1536,10 +1296,7 @@ mod tests {
         );
     }
 
-    /// `QuestLogPushQuest` queues the selected entry's **quest id**, resolved at click time — not
-    /// its index, so a log that reshuffles between the click and the app's drain cannot retarget
-    /// the push — the same keying as the abandon mark.
-    /// A party of one other, so the C verb's own party check (below) passes.
+    /// A party of one other, so `QuestLogPushQuest`'s party check passes.
     fn in_a_party(s: &mut UiScript) {
         s.set_party(crate::script::PartyState {
             members: vec![crate::script::PartyMemberInfo {
@@ -1563,9 +1320,6 @@ mod tests {
         assert!(s.take_quest_log_pushes().is_empty(), "drained");
     }
 
-    /// A push with nothing selected is silently nothing — the window's button is disabled in that
-    /// state, so this is only reachable from a macro or an addon, and the client has no quest id
-    /// to send.
     #[test]
     fn push_without_a_selection_queues_nothing() {
         let mut s = UiScript::new().unwrap();
@@ -1575,9 +1329,7 @@ mod tests {
         assert!(s.take_quest_log_pushes().is_empty());
     }
 
-    /// **The C verb re-tests the party and the sharable bit itself** (`0x4e13a6`, decision 1738) —
-    /// the reference does not trust its own button, because a macro or an addon can call this with
-    /// the window shut. Each guard is moved alone, against an otherwise-valid push.
+    /// `0x4e13a6` checks the party and the sharable bit itself; each guard is tested alone.
     #[test]
     fn push_refuses_solo_and_refuses_an_unsharable_quest() {
         let sharable = || {
@@ -1586,19 +1338,16 @@ mod tests {
             state
         };
 
-        // Solo: everything else is right and it still sends nothing.
         let mut s = UiScript::new().unwrap();
         s.set_quest_log(sharable());
         s.run("SelectQuestLogEntry(1)").unwrap();
         s.run("QuestLogPushQuest()").unwrap();
         assert!(s.take_quest_log_pushes().is_empty(), "solo pushes nothing");
 
-        // In a party, the same call goes.
         in_a_party(&mut s);
         s.run("QuestLogPushQuest()").unwrap();
         assert_eq!(s.take_quest_log_pushes(), vec![783]);
 
-        // In a party, on a quest without the sharable bit: nothing again.
         s.run("SelectQuestLogEntry(2)").unwrap();
         s.run("QuestLogPushQuest()").unwrap();
         assert!(
@@ -1607,9 +1356,6 @@ mod tests {
         );
     }
 
-    /// A HEADER row carries `quest_id` 0, so pushing one must queue nothing at all — an unguarded
-    /// id resolve would send `CMSG_PUSHQUESTTOPARTY{0}`. The window's button is disabled on a
-    /// header, so only a macro or an addon can get here.
     #[test]
     fn push_on_a_header_row_queues_nothing() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/region.rs b/crates/benilla-ui/src/script/region.rs
index 6e5e9608..db7c064c 100644
--- a/crates/benilla-ui/src/script/region.rs
+++ b/crates/benilla-ui/src/script/region.rs
@@ -1,8 +1,5 @@
-//! The **region** side of the object model (each leaf carries the reference's own type tag): the
-//! `Texture`/`FontString` wrapper cache, their shared metatable, and the region method surface.
-//! Split from [`super::object`] (which keeps the frame side + `CreateFrame`) so each grows along
-//! its own axis — frames grow per-kind method tables ([`super::statusbar`], [`super::button`]),
-//! regions grow paint/coords methods here.
+//! The region side of the object model ([`super::object`] is the frame side): the region wrapper
+//! cache, the Region, Texture, FontString and title-region method tables, and the portrait globals.
 
 use mlua::{Lua, MultiValue, Table, Value};
 
@@ -29,21 +26,10 @@ pub(super) fn region_handle_of(lua: &Lua, this: &Table) -> mlua::Result<RegionHa
         .ok_or_else(|| mlua::Error::runtime("stale or invalid region handle"))
 }
 
-/// Apply the font parts an **XML element** supplies — `font=`, `<FontHeight>`, `outline=` — any
-/// subset of which may be absent.
-///
-/// **This is deliberately not the `SetFont` binding, and that separation is the point.** The
-/// reference applies XML font attributes in C++ (`LoadXML`), never through the Lua method, and its
-/// `SetFont` therefore *requires* both a path and a height, raising
-/// `Usage: %s:SetFont("font", fontHeight [, flags])` (`0x87c69c`) without them. Our loader used to
-/// call the binding with three `Option`s — `SetFont(nil, nil, "OUTLINE")` for an outline-only
-/// `<FontString>` — which is why that binding could not be made faithful: one name was doing two
-/// jobs, and the more lenient job won. Splitting them lets `SetFont` be the reference's `SetFont`
-/// and lets the loader keep the partial application XML actually needs.
-///
-/// Each part supplied is an **explicit** set (`FontExplicit`), so it survives a later mutation of
-/// the font object this region inherits. An empty `font=` is treated as absent — it keeps the
-/// inherited face, rather than being the binding's load-failure edge.
+/// Apply the font parts an XML element supplies (`font=`, `<FontHeight>`, `outline=`), any of
+/// which may be absent. Not the `SetFont` binding: the reference applies XML fonts in `LoadXML`,
+/// and its `SetFont` requires a path and a height (`0x87c69c`). Each part is an explicit set, so it
+/// survives a change to the inherited font object; an empty `font=` keeps the inherited face.
 pub(crate) fn apply_font_parts(
     lua: &Lua,
     this: &Table,
@@ -70,7 +56,7 @@ pub(crate) fn apply_font_parts(
     Ok(())
 }
 
-/// Get-or-create the wrapper table for a region id (distinct metatable — the region "tag").
+/// Get or create the wrapper table for a region id, with its kind's metatable.
 pub(super) fn region_wrapper(lua: &Lua, id: u32) -> mlua::Result<Table> {
     let wrappers: Table = lua.named_registry_value(REG_WRAPPERS)?;
     if let Value::Table(t) = wrappers.get::<Value>(id)? {
@@ -78,11 +64,8 @@ pub(super) fn region_wrapper(lua: &Lua, id: u32) -> mlua::Result<Table> {
     }
     let t = lua.create_table()?;
     t.raw_set(0, Value::LightUserData(id_to_lud(id)))?;
-    // **A title region gets a NARROWER metatable, chosen here rather than per lookup.**
-    // `CreateTitleRegion 0x773910`'s object answers *exactly* the 19 Region methods — no
-    // Show/Hide, no textures, no text — and this cache is created once per region, so picking the
-    // table at construction costs nothing on the call path (dispatching inside `__index` would
-    // put a model borrow and a kind lookup in front of EVERY region method call in the UI).
+    // The metatable is chosen once, here, not per call: a title region
+    // (`CreateTitleRegion 0x773910`) answers only the 19 Region methods.
     let kind = {
         let model = lua.app_data_ref::<Model>().expect("model");
         model
@@ -95,9 +78,7 @@ pub(super) fn region_wrapper(lua: &Lua, id: u32) -> mlua::Result<Table> {
         Some(RegionKind::Texture) => REG_TEXTURE_META,
         Some(RegionKind::FontString) => REG_FONTSTRING_META,
         Some(RegionKind::Title) => REG_TITLE_META,
-        // A wrapper for an id with no live region: the full table, which is what this cache did for
-        // every region before the leaves were split. Nothing can call through it — every method
-        // resolves the handle first and raises on a dead one.
+        // No live region: the full table, harmless since every method raises on a dead handle.
         None => REG_REGION_META,
     })?;
     t.set_metatable(Some(meta))?;
@@ -105,27 +86,19 @@ pub(super) fn region_wrapper(lua: &Lua, id: u32) -> mlua::Result<Table> {
     Ok(t)
 }
 
-/// Install the region method table + the shared region metatable.
+/// Install the region method tables and the region globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     install_region_methods(lua)?;
 
-    // SetPortraitTexture(textureRegion, unit) — the live API's **global** (ref-UnitFrame.lua:
-    // `SetPortraitTexture(this.portrait, this.unit)`), distinct from the region-method
-    // `SetPortraitToTexture(path)` icon crop. It binds a Texture region to a unit token; the app
-    // renders that unit's model off-screen and feeds the bake back through the region's
-    // [`super::QuadContent::Texture::portrait_unit`], with `circular` marking the round stencil
-    // (the bake is square with an opaque backdrop; the frame-ring portraits cut the inscribed
-    // circle, exactly what the app's quad shader does with the flag). `texture`/`color` drop —
-    // the bake replaces them. A later `SetTexture`/`SetPortraitToTexture` clears the binding.
+    // SetPortraitTexture(texture, unit) (`UnitFrame.lua:26`): binds the region to a unit whose
+    // model the app bakes off-screen, drawn masked to its inscribed circle; a later `SetTexture`
+    // or `SetPortraitToTexture` clears it.
     lua.globals().set(
         "SetPortraitTexture",
         lua.create_function(|lua, (region, unit): (Table, Value)| {
-            // `0x519ef0` gates its unit argument at `0x519fb4` with `lua_isstring` and fails into
-            // `luaL_error` with this exact string (`0x8513b8`); `luaL_error` does not return, so
-            // nil/absent/boolean/table abandon the caller's statement. Stock
-            // `Blizzard_InspectUI.lua:49` reaches it on a re-open, which is how it was found.
-            // A token that RESOLVES to nothing is a different, quiet case — it blanks the portrait
-            // and returns no values. Decision 1834.
+            // A non-string unit raises this exact error (`0x519fb4`, `0x8513b8`), which stock
+            // `Blizzard_InspectUI.lua:49` hits on a re-open; a token that resolves to nothing only
+            // blanks the portrait.
             let unit = crate::script::binding_abi::string_arg(
                 lua,
                 unit,
@@ -134,14 +107,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             let rh = region_handle_of(lua, &region)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
             let data = model.region_data.entry(rh).or_default();
-            // CANONICAL (lowercase) on the way in, like `set_unit`'s map key: the binding
-            // resolves its token through the one resolver every `Unit*` binding shares
-            // (`0x519ef0` → `0x515970`), whose every compare is `_strnicmp` — so the stock
-            // `MerchantFrame.lua:68`, `GuildRegistrarFrame.lua:4` and `TradeFrame.lua:41` all
-            // write `"NPC"` and mean `"npc"`. The app samples the booth by this string
-            // (`portrait::PortraitImages`, keyed by the lowercase slot names), and a raw `"NPC"`
-            // reached it and matched nothing: an empty portrait ring on all three windows
-            // (decision 2022).
+            // Lowercased: the reference resolves the token case-insensitively (`0x519ef0` →
+            // `0x515970`), stock `MerchantFrame.lua:68` passes `"NPC"`, and the app's bakes are
+            // keyed lowercase.
             data.portrait_unit = Some(unit.to_ascii_lowercase());
             data.texture = None;
             data.fill = None;
@@ -150,25 +118,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetPortraitToTexture(textureName, path) — the ENGINE GLOBAL, which is what 1.12 has.
-    //
-    // `reference/1.12-globals.tsv` marks it `engine`, and the reference's own two call sites both
-    // pass a texture NAME: `ContainerFrame.lua:419` writes
-    // `SetPortraitToTexture(frame:GetName().."Portrait", "…KeyRing-Bag-Icon")` and
-    // `MailFrame.lua:174` writes `SetPortraitToTexture("OpenMailFrameIcon", stationeryIcon)`.
-    // **That first one matters here: we SOURCE `ContainerFrame.lua` off the patch chain, so the
-    // client's own file calls this global inside our VM.**
-    //
-    // A NAME, not a region handle — strictly what the reference's callers are attested to pass.
-    // Whether the real binding also accepts a texture object has not been read from the bytes, so
-    // it is not accepted here: inventing the wider signature is how a superset starts (1189), and
-    // nothing needs it — both of our own callers already hold the name.
-    //
-    // The behaviour is the crop it was always: set the texture AND mark the region a portrait, so
-    // it draws masked to its inscribed circle. The client's portraits are circular and the frame
-    // ring is a thin band whose transparent corners would otherwise show the square texture's
-    // edges. Distinct from `SetPortraitTexture(region, unit)`'s live model bake, so it drops any
-    // live-unit binding; a later `SetTexture` clears the flag again.
+    // SetPortraitToTexture(textureName, path), an engine global: sets the texture, drawn masked
+    // to its inscribed circle, and drops any unit binding. It takes the name, as both stock
+    // callers pass (`ContainerFrame.lua:419`, `MailFrame.lua:174`); whether the reference also
+    // takes a region object is untraced.
     lua.globals().set(
         "SetPortraitToTexture",
         lua.create_function(|lua, (name, path): (String, String)| {
@@ -187,17 +140,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // BenillaSetBoothTexture(textureRegion, slotToken) — the **square** twin of
-    // SetPortraitTexture (decision 0208 §5): the same `portrait_unit` booth-image binding
-    // WITHOUT the circular mask, for a body pane whose texture region samples the booth's bake
-    // edge to edge (no frame ring to mask for). Benilla-named because it is not the live API: it
-    // is the pane→booth join written in Lua.
-    //
-    // **RETIRING.** A migrated window's file is the reference's, which declares a bare
-    // `<PlayerModel>` and no texture at all, so the join moved app-side
-    // (`portrait::MODEL_PANE_BOOTHS`) and the widget draws itself (decision 1810). Two callers are
-    // left — the dressing room and the inspect window, both still our own files — and this goes
-    // with the later of them.
+    // BenillaSetBoothTexture(texture, slotToken): `SetPortraitTexture` without the circular mask;
+    // not a 1.12 global.
     lua.globals().set(
         "BenillaSetBoothTexture",
         lua.create_function(|lua, (region, token): (Table, String)| {
@@ -212,12 +156,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // **`__index` is the method TABLE, not a dispatcher function** (decision 2310) — here and at
-    // the three leaf metatables below. A Rust `__index` makes every `t.SetTexture` a Lua→Rust→Lua
-    // round trip plus a named-registry string lookup; measured at ~195 ns against ~9 ns for the
-    // table form, paid by every widget method access in the client. Nothing mutates these tables
-    // after install (`super::region_map::install` writes into them in place, and runs inside
-    // `super::object::install`), so holding the table itself cannot go stale.
+    // `__index` is the method table itself, here and on the leaf metatables, not a function
+    // (~9 ns against ~195 ns per method access); sound while nothing replaces these tables.
     let region_meta = lua.create_table()?;
     region_meta.set(
         "__index",
@@ -234,14 +174,7 @@ mod text;
 fn install_region_methods(lua: &Lua) -> mlua::Result<()> {
     let m = lua.create_table()?;
 
-    // GetName() → this region's global name, or nil when it was declared anonymously — the pair
-    // the frame side already answers. Real FrameXML round-trips a region through its name wherever
-    // it can't hold a reference to itself: `ComboFrame.lua`'s shine chain hands `frame:GetName()`
-    // to a fade `finishedFunc` and `getglobal`s it back ("hack since a frame can't have a
-    // reference to itself in it" — its own comment).
-    //
-    // Resolution is [`region_name_of`], shared with `IsObjectType`'s `Usage:` text so the two can
-    // never disagree about what this region is called.
+    // GetName(): the global name, or nil for an anonymous region.
     set_shared(lua, &m, Side::Region, "GetName", |lua, this: Table| {
         let id = decode_id(&this)?;
         let model = lua.app_data_ref::<Model>().expect("model app_data");
@@ -251,15 +184,10 @@ fn install_region_methods(lua: &Lua) -> mlua::Result<()> {
         }
     })?;
 
-    // ── GetObjectType / IsObjectType: the last two of the Region map (1244 §4 closed) ───────────
+    // ── GetObjectType / IsObjectType ─────────────────────────────────────────────────────────
     //
-    // 1244 shipped four of the six missing Region-map members and deliberately left these two
-    // DISPATCHED rather than guessed, because every interesting detail is one a plausible
-    // implementation gets wrong. Every one of those details is below, verified at the bytes.
-    //
-    // `GetObjectType` is a per-class `.data` `const char*` read through `vtable[+0x1c]` — Texture
-    // `0x773480` → `"Texture"`, FontString `0x7735d0` → `"FontString"` — pushed with
-    // `lua_pushstring`, exactly one value, extra arguments ignored with no arity check.
+    // GetObjectType: a per-class string through `vtable[+0x1c]` (Texture `0x773480`, FontString
+    // `0x7735d0`), one value, extra arguments ignored.
     set_shared(
         lua,
         &m,
@@ -272,27 +200,10 @@ fn install_region_methods(lua: &Lua) -> mlua::Result<()> {
         },
     )?;
 
-    // `IsObjectType(name)` — binding `0x7a1290`. Four traps, all verified, all here:
-    //
-    //  · **Case-INSENSITIVE, whole-string.** `vtable[+0x18]` → `SStrCmpI 0x64a4c0` → `_strnicmp`,
-    //    which folds both operands before comparing and breaks at the first NUL on either side —
-    //    so no prefix or substring match either. (The *method-name* lookup `0x702000` uses the
-    //    case-SENSITIVE sibling; the two are easy to conflate and behave differently.)
-    //  · **A short, hardcoded chain — and there is no root type.** Texture answers `"Texture"` and
-    //    `"Region"`; FontString answers `"FontString"` and `"Region"`. **1.12.1 has no
-    //    `"LayoutFrame"`, `"ScriptObject"` or `"Object"` type at all** — those strings exist only
-    //    inside `__FILE__` paths and allocator tags — so `tex:IsObjectType("LayoutFrame")` is nil.
-    //    That is the single most likely thing to invent from knowing later clients.
-    //  · **A hit is the NUMBER 1 and a miss is nil — never a boolean**, read off the pushed tags
-    //    (`lua_pushnumber` tag 3 vs `lua_pushnil` tag 0; tag 1 is never written), and exactly one
-    //    value on both paths.
-    //  · **A bad argument RAISES.** The gate is `lua_isstring`, which accepts strings and NUMBERS
-    //    only; anything else (missing, nil, boolean, table, function, userdata) hits
-    //    `luaL_error(L, "Usage: %s:IsObjectType(\"TYPE\")")` with `%s` the region's name or
-    //    `<unnamed>`, and that longjmps rather than returning. A number is ACCEPTED and stringified
-    //    in place, so `tex:IsObjectType(5)` compares against `"5"` and quietly answers nil — we
-    //    format it and compare for real rather than short-circuiting, though no type name is
-    //    numeric so the answer is nil either way.
+    // IsObjectType(name) (`0x7a1290`): a case-insensitive whole-string match (`0x64a4c0`) against
+    // the leaf or "Region" only, as 1.12 has no LayoutFrame, ScriptObject or Object type; a hit is
+    // the number 1, a miss nil. A number is stringified and compared; anything else raises the
+    // usage error, naming the region or `<unnamed>`.
     set_shared(
         lua,
         &m,
@@ -319,29 +230,10 @@ fn install_region_methods(lua: &Lua) -> mlua::Result<()> {
         },
     )?;
 
-    // SetParent(frame) — **a Texture/FontString really does have this**, and we were the ones
-    // missing it. `SetParent` lives in the REGION method table (`0x7a1550`); Texture's class lookup
-    // falls back to Region's at `0x79c650` and FontString's at `0x79ee50`, so both reach it.
-    // `FuBar_FuXPFu.lua:210`'s `self.Spark:SetParent(self.XPBar)` is not a broken addon.
-    //
-    // Four contract traps, each spelled out because each is a plausible implementation's silent
-    // divergence:
-    //
-    //  · **The argument must be a FRAME.** `0x7a16ea` runs `IsA(FrameTag)` on it, and a Texture or
-    //    Region argument raises `"…Wrong parent object type, expected frame"` (`0x87cb78`). Ours
-    //    raises too — a re-parent that quietly did nothing is the silent-drop class of 1203/1205.
-    //  · **A missing argument is NOT the nil form.** TNONE fails the `== LUA_TNIL` test and falls
-    //    through to `"…Couldn't find region named '%s'"` (`0x87cb48`), so `tex:SetParent()` raises
-    //    while `tex:SetParent(nil)` detaches. That is why this reads a `MultiValue`: mlua cannot
-    //    tell an absent argument from an explicit nil any other way.
-    //  · **Anchors are untouched.** The re-link moves draw-layer/region-list membership only; a
-    //    re-parented Texture still anchors to whatever `SetPoint` named — which is why FuXPFu
-    //    re-points its spark afterwards, and why our anchors (which store the resolved target id)
-    //    need no fixing up at all.
-    //  · **Zero return values**, on every path.
-    //
-    // The mechanism half — full re-link, layer and sub-level preserved, `nil` = orphaned but not
-    // destroyed — is [`crate::widget::WidgetArena::set_region_owner`]'s doc.
+    // SetParent(frame) lives in the Region table (`0x7a1550`), which Texture and FontString
+    // lookups fall back to (`0x79c650`, `0x79ee50`); `FuBar_FuXPFu.lua:210` calls it on a texture.
+    // A non-frame raises (`0x7a16ea`, `0x87cb78`); no argument raises (`0x87cb48`) where nil
+    // detaches, hence the `MultiValue`. Anchors are untouched, and nothing is returned.
     set_shared(
         lua,
         &m,
@@ -360,8 +252,7 @@ fn install_region_methods(lua: &Lua) -> mlua::Result<()> {
             };
             let wrong_type =
                 || mlua::Error::runtime("SetParent(): Wrong parent object type, expected frame");
-            // `_G[name]` before the guard, and **without** `$parent` expansion — the reparent
-            // bindings call `0x76c760` directly (`super::object::NamedTarget`).
+            // `_G[name]` is read before the model borrow, with no `$parent` expansion (`0x76c760`).
             let named = match &parent {
                 Value::String(s) => Some(match s.to_str() {
                     Ok(n) => super::object::prefetch_named_target(lua, n.as_ref(), None),
@@ -372,17 +263,14 @@ fn install_region_methods(lua: &Lua) -> mlua::Result<()> {
             let mut model = lua.app_data_mut::<Model>().expect("model");
             let new_owner = match &parent {
                 Value::Nil => None,
-                // A region/font-object wrapper decodes to an id that is not a frame's (or to no id
-                // at all) — both land on the same "expected frame" the reference raises.
+                // A region or font-object wrapper is no frame: the same "expected frame" raise.
                 Value::Table(t) => Some(
                     decode_id(t)
                         .ok()
                         .and_then(|id| model.id_to_frame.get(&id).copied())
                         .ok_or_else(wrong_type)?,
                 ),
-                // A name resolves through `_G[name]` + the narrow **Frame** tag check
-                // (`[0xcf0c10]`), as every other frame-target argument does — the reference's
-                // `0x76c760`; see `object::NamedTarget`.
+                // A name resolves through `_G[name]` and the Frame tag check (`[0xcf0c10]`).
                 Value::String(_) => {
                     let nt = named.as_ref().expect("a String argument is prefetched");
                     let hit = super::object::resolve_named_target(&model, nt)
@@ -397,19 +285,14 @@ fn install_region_methods(lua: &Lua) -> mlua::Result<()> {
                 _ => return Err(wrong_type()),
             };
             if model.arena.set_region_owner(rh, new_owner) {
-                // An un-anchored region draws relative to its owner, and an anchored one resolves
-                // against the owner's rect and effective scale (`layout.rs`'s region sweep) — the
-                // owner is a layout input, so a re-link is a layout change.
+                // The owner supplies the region's scale to layout, so a re-link is a layout change.
                 model.touch_layout();
             }
             Ok(())
         },
     )?;
 
-    // Region-level visibility — the real VisibleRegion Show/Hide on Textures/FontStrings (the
-    // ref kit hides tab slices, cooldown swipes, money coins…). A hidden region draws nothing;
-    // IsVisible additionally requires the owner frame's effective visibility, mirroring the
-    // frame-side pair.
+    // A hidden region draws nothing; `IsVisible` also needs the owner frame visible.
     m.set(
         "Show",
         lua.create_function(|lua, this: Table| {
@@ -459,53 +342,26 @@ fn install_region_methods(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The three clusters this file was split into (0716's budget). Order is immaterial —
-    // every one of them only writes into the same method table.
+    // In any order: each only adds to the same method table.
     paint::install(lua, &m)?;
     text::install(lua, &m)?;
     layout::install(lua, &m)?;
 
-    // ── The title region's own, narrower table ──────────────────────────────────────────────────
+    // ── The title region's table ─────────────────────────────────────────────────────────────
     //
-    // 1250 §5 recorded this as a named divergence: our region metatable was shared, so a title
-    // region answered `SetTexture`/`Show`/`Hide` where the reference raises `attempt to call
-    // method`. Inert — the kind never draws — but a **superset in PRESENCE**, and 1189 is the
-    // record of what a superset costs when an addon feature-detects.
-    //
-    // Closed by copying exactly the Region map (the 19 names 1244/1245 landed and assert as a set)
-    // out of the full table. It is a copy rather than a second install because the two must never
-    // disagree about what, say, `GetPoint` does — one implementation, two visibilities.
-    //
-    // **The Texture/FontString superset is NOT closed here, deliberately.** They still share one
-    // table, so a Texture answers `SetText` and a FontString answers `SetTexture`. Splitting those
-    // needs the per-table membership facts, and the naive partition is WRONG: `paint.rs` installs
-    // `SetDrawLayer`/`SetVertexColor`/`SetAlpha`/`SetAlphaGradient`, all of which FontString's own
-    // method table (`0xcf5400`) legitimately has. A wrong split REMOVES verbs addons use, which is
-    // worse than the superset it fixes — so that half waits for the membership read (1238's shape).
+    // Exactly the Region map, copied from the full table so both share one implementation; the
+    // reference's title region has no `Show`, `Hide` or texture methods.
     let title = lua.create_table()?;
     for name in super::REGION_MAP_METHODS {
         let f: Value = m.get(name)?;
         title.set(name, f)?;
     }
-    // ── The two LEAF tables ──────────────────────────────────────────────────────────────────
+    // ── The leaf tables ──────────────────────────────────────────────────────────────────────
     //
-    // Texture's map is `0x87c128` (22 entries, lookup `0x79c620`), FontString's is `0xcf5400` (32,
-    // lookup `0x79ee20`); both tail-call the Region map and stop there — no third table. Until now
-    // ours was ONE table for both, so a Texture answered `SetText` and a FontString answered
-    // `SetTexture`: a superset in both directions.
-    //
-    // **Partitioned first, then pruned name by name.** The 1244/1245 split only decided which
-    // leaf could SEE each name, because getting a split wrong REMOVES verbs addons use, which is
-    // worse than the superset it fixes. The five that were in NEITHER client map were left in
-    // place as a separate question per name, and all five have since been answered:
-    // `GetStringHeight` (1251), `SetRotation` and `SetPortraitToTexture` (the latter a 1.12
-    // GLOBAL, and it lives there now), and `SetFormattedText` and `SetSize` (2142). Both leaves
-    // are the client's own lists now.
-    //
-    // Copied out of the full table rather than installed twice, so one implementation stands behind
-    // both visibilities — and note that the shared names use the IDENTICAL `const char*` in the
-    // client's two tables (e.g. `GetDrawLayer` at `0x87c41c`), so de-duplicating by name would
-    // drop one side.
+    // Texture's map (`0x87c128`, 22 entries, lookup `0x79c620`) and FontString's (`0xcf5400`, 32,
+    // lookup `0x79ee20`) each fall back to the Region map and nothing else. Copied from the full
+    // table; a name both leaves list (one `const char*` in the client, e.g. `GetDrawLayer` at
+    // `0x87c41c`) goes into both.
     for (key, extra) in [
         (REG_TEXTURE_METHODS, &super::TEXTURE_ONLY_METHODS[..]),
         (REG_FONTSTRING_METHODS, &super::FONTSTRING_ONLY_METHODS[..]),
@@ -539,13 +395,8 @@ fn install_region_methods(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// The layout [`super::layout::Handle`] a region anchors to by default: its **owner frame**'s id
-/// (minted if needed), or [`SCREEN`] if the region has somehow lost its owner.
-/// This region's global name, or `None` when it was declared anonymously.
-///
-/// Scans the region-name registry rather than mirroring the name onto the region: that registry is
-/// the single authority (the widget arena deliberately holds none), and a second copy is one more
-/// thing to drift. Linear in NAMED regions, and every caller is human-rate.
+/// This region's global name, or `None` when anonymous: a scan of the region-name registry, the
+/// one authority, linear in named regions.
 pub(super) fn region_name_of(model: &Model, id: u32) -> Option<String> {
     model
         .region_names
@@ -554,16 +405,9 @@ pub(super) fn region_name_of(model: &Model, id: u32) -> Option<String> {
         .map(|(k, _)| k.clone())
 }
 
-/// Publish a region's global name into the **region-name registry** — the table a sibling's
-/// `SetPoint`/`SetAllPoints` resolves a named `relativeTo` through
-/// ([`super::object::layout_methods`]). First-wins, the same rule frames follow.
-///
-/// `CreateTexture(name)` does this for itself; the paths that *don't* are the typed widgets' own
-/// sub-textures, which are created by a setter (`SetThumbTexture`, `SetColorWheelTexture`, …) and
-/// named afterwards by the XML loader. Without this they land in `_G` and nowhere else, and a
-/// `relativeTo="ColorPickerWheel"` on a sibling silently falls back to the parent frame — which is
-/// exactly how the colour picker's value strip first ended up 224 px to the right of where the
-/// reference puts it, anchored to the window instead of to the wheel.
+/// Publish a region's name into the registry a named `relativeTo` resolves through, first name
+/// winning as for frames. For sub-textures a setter creates and the XML loader names later
+/// (`SetThumbTexture`, `SetColorWheelTexture`); `CreateTexture(name)` publishes its own.
 pub(crate) fn publish_region_name(lua: &Lua, name: &str, region: &Table) {
     let Ok(id) = super::object::decode_id(region) else {
         return;
@@ -572,49 +416,29 @@ pub(crate) fn publish_region_name(lua: &Lua, name: &str, region: &Table) {
     model.region_names.entry(name.to_string()).or_insert(id);
 }
 
-/// The string `GetObjectType()` answers for this region, and the leaf `IsObjectType` matches.
-///
-/// The reference reads a per-class `.data` `const char*` through `vtable[+0x1c]`; ours reads the
-/// arena's [`RegionKind`], which is the same fact stored once. A handle whose region has been
-/// destroyed answers `"Region"` — the base every leaf also matches, so an identity question about
-/// a dead handle degrades to the truthful half rather than naming a leaf it no longer is.
+/// The type `GetObjectType()` answers and `IsObjectType` matches; `"Region"` for a dead handle.
 pub(super) fn region_type_name(model: &Model, rh: RegionHandle) -> &'static str {
     match model.arena.region(rh).map(|r| r.kind) {
         Some(RegionKind::Texture) => "Texture",
         Some(RegionKind::FontString) => "FontString",
-        // The title region's own type name — it is a Region and nothing more (`CreateTitleRegion
-        // 0x773910`).
+        // A title region is a bare Region (`CreateTitleRegion 0x773910`).
         Some(RegionKind::Title) => "Region",
         None => "Region",
     }
 }
 
-/// Free one region and **every trace of its identity** — the arena slot, its paint, its resolved
-/// rect, its name registration, and the stable id both directions.
-///
-/// Anything that had fetched its wrapper now resolves to a stale-handle error, which is the honest
-/// answer for an object the widget destroyed. That matters because the client really does destroy:
-/// `CSimpleButton::SetFontString 0x778d20` runs the *scalar deleting* destructor on the label it
-/// replaces (`old->vtable[0](1)`, returning the storage to the FontString pool), so a caller
-/// holding the old string is holding a freed object — orphaning it instead would leave a live,
-/// parentless label that still answers every getter, which is a different and quieter bug.
-///
-/// One law, two callers ([`super::simplehtml`]'s block free and the button's label swap); it lives
-/// here because the region side owns region lifetime, and because two hand-written copies of a
-/// five-map teardown is how one of them ends up forgetting a map.
+/// Free a region and every trace of its identity (arena slot, paint, rect, name, id), so a held
+/// wrapper raises as stale; the reference frees too, as `CSimpleButton::SetFontString 0x778d20`
+/// deletes the label it replaces.
 pub(crate) fn free_region(model: &mut Model, rh: RegionHandle) {
     model.region_data.remove(&rh);
     model.region_resolved.remove(&rh);
     if let Some(id) = model.region_to_id.remove(&rh) {
         model.id_to_region.remove(&id);
-        // A NAMED region also holds a slot in the name registry — anonymous ones (every SimpleHTML
-        // block, most labels) do not, which is why the first caller of this law never needed it.
         model.region_names.retain(|_, v| *v != id);
     }
     model.arena.destroy_region(rh);
-    // A death is the archetypal STRUCTURAL change — it takes a node out of the layout roster and
-    // its reverse edges with it, which is exactly what a per-node ledger cannot describe
-    // (decision 1388).
+    // A removed node takes its edges with it: a structural change, so the full touch.
     model.touch_layout();
 }
 
@@ -625,29 +449,12 @@ pub(super) fn region_owner_id(model: &mut Model, rh: RegionHandle) -> u32 {
     }
 }
 
-/// The client's **creation-path implicit anchor** (decision 1310): a per-region-type post-step
-/// the real engine runs immediately after a region's LoadXML returns (`0x7701c0` texture /
-/// `0x771480` fontstring — the same two fire from the Button state-texture and ButtonText paths,
-/// and from Lua `CreateTexture`/`CreateFontString` only on a template-registry hit). Condition:
-/// the region has a parent AND every one of its nine anchor slots is empty — any anchor from any
-/// source suppresses it. Then:
-///
-/// - a **Texture** gets `SetAllPoints(parent)` — two corner anchors, TOPLEFT→TOPLEFT and
-///   BOTTOMRIGHT→BOTTOMRIGHT at (0,0). Two opposing corners pin all four edges, so an authored
-///   `<Size>` is **structurally unread** (the resolver law) — which is why the reference's
-///   stack-split plate authors a vestigial 256×32 and renders 172×96 (B180).
-/// - a **FontString** gets ONE middle-row `SetPoint` chosen by its live justify word
-///   (`[this+0x120] & 7`: 1 → LEFT→LEFT, 4 → RIGHT→RIGHT, else CENTER→CENTER, offsets (0,0)) —
-///   and its `<Size>` stays live (single anchor + W/H sizes the opposite edges).
-///   [`RegionData::justify`] *is* that word — `SetJustifyH` writes it and a font-object link
-///   merges into it behind the explicit mask — so reading it here is reading `+0x120`.
-/// - a **Title region** gets nothing (verified negative), and a templateless Lua region is never
-///   routed here at all: it stays rect-less and does not render.
-///
-/// These are ordinary anchors once installed: a later same-point `SetPoint` replaces only its own
-/// slot and the other implicit corner survives (verified) — callers that re-apply authored anchors
-/// over a materialized region must `ClearAllPoints` first, exactly as the reference's XML path
-/// avoids the mix by running this step *after* `<Anchors>` load.
+/// The reference's implicit anchor for a region with a parent and no anchors, run after its XML
+/// loads (texture `0x7701c0`, fontstring `0x771480`), and from Lua `CreateTexture` or
+/// `CreateFontString` only on a template hit. A Texture gets `SetAllPoints(parent)`, so an
+/// authored `<Size>` goes unread; a FontString gets one middle-row point picked by its justify
+/// word (`[+0x120]`, our [`RegionData::justify`]) and keeps its size; a title region gets none.
+/// They are ordinary anchors after: re-applying authored ones needs `ClearAllPoints` first.
 pub(crate) fn implicit_creation_anchor(model: &mut Model, rh: RegionHandle) {
     let Some((kind, owner)) = model.arena.region(rh).map(|r| (r.kind, r.owner)) else {
         return;
@@ -674,12 +481,8 @@ pub(crate) fn implicit_creation_anchor(model: &mut Model, rh: RegionHandle) {
     model.touch_layout();
 }
 
-/// The middle-row point a justify word selects — the compare chain the FontString creation
-/// post-step (`0x771480`) and the Button label adopter (`CSimpleButton::SetFontString 0x778d20`)
-/// share: `& 7`, then equality against LEFT (1) and RIGHT (4); every other value — the CENTER bit
-/// and a cleared axis alike — falls to CENTER. What differs between the two callers is only WHOSE
-/// word is read: the post-step reads the string's own (`+0x120`), the adopter reads the button's
-/// normal font's (`+0x390`) — see [`super::button`]'s `adopt_label` (decision 1996).
+/// The middle-row point a justify word selects, as the FontString post-step (`0x771480`) and the
+/// button label adopter (`0x778d20`) both compute it: LEFT for 1, RIGHT for 4, else CENTER.
 pub(crate) fn justify_anchor_point(word: u32) -> crate::layout::Point {
     use crate::layout::Point;
     match word & crate::justify::H_MASK {
@@ -689,10 +492,7 @@ pub(crate) fn justify_anchor_point(word: u32) -> crate::layout::Point {
     }
 }
 
-/// One middle-row anchor `point → the owner's same point, (0,0)`, installed only when the region
-/// has no anchor of its own — the nine-slot scan every implicit-anchor site runs first, so any
-/// anchor from any source suppresses it. [`implicit_creation_anchor`]'s FontString arm is this
-/// with the region's own justify word; the Button adopter is this with the button's.
+/// Anchor `point` to the owner's same point at (0, 0), only when the region has no anchor at all.
 pub(crate) fn anchor_unanchored_at(
     model: &mut Model,
     rh: RegionHandle,
@@ -710,8 +510,7 @@ pub(crate) fn anchor_unanchored_at(
     model.touch_layout();
 }
 
-/// [`implicit_creation_anchor`] behind a wrapper table — the loader-facing form (the loader holds
-/// region wrappers, not handles), same seam as [`apply_font_parts`].
+/// [`implicit_creation_anchor`] for the loader, which holds region wrappers.
 pub(crate) fn implicit_creation_anchor_lua(lua: &Lua, wrapper: &Table) -> mlua::Result<()> {
     let rh = region_handle_of(lua, wrapper)?;
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -719,15 +518,8 @@ pub(crate) fn implicit_creation_anchor_lua(lua: &Lua, wrapper: &Table) -> mlua::
     Ok(())
 }
 
-/// The two things the shared ladder needs off a **region** receiver, read under one short `Model`
-/// borrow that is dropped before the `_G` read (`super::object::anchor_args`'s contract, and the
-/// frame twin's `frame_ladder_context`): the name the reference puts in its error strings, and the
-/// name a leading `$parent` expands to.
-///
-/// A region's `$parent` is its **owner** frame (the region's own `+0x9c`), so the walk starts
-/// there rather than one link higher. Its own name comes back out of `Model::region_names` — the
-/// registry is name→id, and this is the only place that wants the inverse, so it is a scan on the
-/// **error path** rather than a second map kept in step.
+/// The receiver's name for error strings and what a leading `$parent` expands to, the owner frame
+/// (`+0x9c`), read under a borrow dropped before the ladder reads `_G`.
 pub(super) fn region_ladder_context(lua: &Lua, rh: RegionHandle) -> (String, String) {
     let mut model = lua.app_data_mut::<Model>().expect("model");
     let id = model.region_id(rh);
@@ -742,9 +534,7 @@ pub(super) fn region_ladder_context(lua: &Lua, rh: RegionHandle) -> (String, Str
     (who, base)
 }
 
-/// Bit-exact equality for a region's explicit size — the layout gate's own lens
-/// (`InputFingerprint::input` feeds `f32::to_bits`), so a setter's no-op detection and the gate
-/// can never disagree; see [`anchor_bits_eq`].
+/// Bit-exact size equality, the layout gate's own test, so a setter's no-op check agrees with it.
 pub(super) fn size_bits_eq(a: Option<(f32, f32)>, b: Option<(f32, f32)>) -> bool {
     match (a, b) {
         (None, None) => true,
@@ -755,15 +545,12 @@ pub(super) fn size_bits_eq(a: Option<(f32, f32)>, b: Option<(f32, f32)>) -> bool
     }
 }
 
-/// `Region:SetPoint(point [, relativeTo [, relativePoint]] [, x, y])` — the *same* binding as the
-/// frame's (`0x7a2540` is registered once, on `CScriptRegion`), so the argument ladder and every
-/// one of its raises come from [`super::object::anchor_args`]; this side supplies only what the
-/// reference reads off a region — the owner as the layout parent, and
-/// [`super::RegionData::anchors`] as the store.
+/// `Region:SetPoint`, the same binding as the frame's (`0x7a2540`, on `CScriptRegion`): the shared
+/// argument ladder ([`super::object::anchor_args`]), with the owner as layout parent.
 pub(super) fn region_set_point(lua: &Lua, this: &Table, args: &MultiValue) -> mlua::Result<()> {
     let rh = region_handle_of(lua, this)?;
     let (who, base) = region_ladder_context(lua, rh);
-    // The `_G` read inside the ladder runs with no model guard alive — see `region_ladder_context`.
+    // No model borrow is alive across the ladder's `_G` read.
     let p = parse_set_point(lua, args, &who, &base)?;
 
     let mut model = lua.app_data_mut::<Model>().expect("model");
@@ -774,17 +561,14 @@ pub(super) fn region_set_point(lua: &Lua, this: &Table, args: &MultiValue) -> ml
 
     let data = model.region_data.entry(rh).or_default();
     let new = Anchor::new(point, rel_to_id, rel_point, x, y);
-    // Same no-op law as the frame twin (`layout_methods::set_point`): idempotent only when the
-    // bit-identical anchor already holds the tail and no earlier entry carries this point.
+    // A no-op only when the bit-identical anchor is already the tail and no earlier entry has
+    // this point, as for frames.
     let same_at_tail = data.anchors.last().is_some_and(|a| anchor_bits_eq(a, &new))
         && !data.anchors[..data.anchors.len() - 1]
             .iter()
             .any(|a| a.point == point);
     if !same_at_tail {
-        // The frame twin's law (decision 1388): re-pointing the same anchor at the same target is
-        // a VALUE change and names its node; anything that moves the target set is structural.
-        // This is the castbar spark's and every combat-text string's per-frame write.
-        // …and a retarget names its node too (decision 1625) — see the frame twin.
+        // The same targets are a value change on this node; a moved target set is a retarget.
         let structural = anchor_retarget_is_structural(&data.anchors, &new);
         let old_targets: Option<Vec<u32>> =
             structural.then(|| data.anchors.iter().map(|a| a.relative_to).collect());
@@ -805,45 +589,23 @@ pub(super) fn region_set_point(lua: &Lua, this: &Table, args: &MultiValue) -> ml
     Ok(())
 }
 
-/// `Region:GetWidth()`/`GetHeight()` — **the virtual size getters**, per region class.
-///
-/// The Lua bindings are not field reads. `GetWidth 0x7a1e00` ends `ff 52 1c` and
-/// `GetHeight 0x7a2030` ends `ff 52 20`: both dispatch through the
-/// receiver's own **geometry vtable** — slots `+0x1c`/`+0x20` — which is the identical call the
-/// rect resolver makes (`0x767579`). So a region's Lua-visible size and the size its rect is built
-/// from are one number BY CONSTRUCTION on the reference, and this function is how they are one
-/// number here (decision 1670; the resolver half is `layout::content_span` +
-/// `layout::FONTSTRING_MIN_SPAN`, and both are read from here).
-///
-/// | class | law |
-/// |---|---|
-/// | plain frame / title region | the flat authored field, `0x768420` / `0x768410`. No content. |
-/// | `CSimpleTexture` | `0x770720` / `0x770790`: authored when **not exactly `0.0`**, else the art's own texel extent, else `0.0`. |
-/// | `CSimpleFontString` | `0x772930` / `0x772a60`: authored when not `0.0`, else the cached measure — and then **floored at one FrameXML unit**. |
-///
-/// Two details of the FontString row are worth spelling out, because both were wrong here before
-/// and neither is guessable from the name:
-///
-/// * **The authored value WINS.** The old code preferred the measure and fell back to the
-///   authored size;
-///   the reference's `jp` at `0x77294a` skips the measure entirely when the authored value is
-///   non-zero. Per axis, not per region — `<Size x="290" y="0"/>` takes 290 from the author and
-///   the height from the text.
-/// * **The width is the NATURAL, unwrapped extent** — `0x772890`'s `[fs+0xfc]`, measured with no
-///   wrap constraint, the very cell `GetStringWidth 0x79e510` returns. The *height* is the other
-///   cell, `0x7729b0`'s `[fs+0x100]`, which IS the wrapped line count × line height. So a wrapped
-///   string reports a width wider than its own box and a height taller than one line, and that
-///   asymmetry is the client's.
+/// `Region:GetWidth()`/`GetHeight()` (`0x7a1e00`, `0x7a2030`): the geometry-vtable call the rect
+/// resolver also makes (`0x767579`), so the Lua size is the rect's. Per axis, a Texture answers
+/// its authored size unless exactly 0, else its texel extent (`0x770720`, `0x770790`). A
+/// FontString answers its authored size unless 0 (`0x77294a`), else its measure, either floored
+/// at one unit (`0x772930`, `0x772a60`); the width is unwrapped, as `GetStringWidth` gives it
+/// (`0x772890`, `0x79e510`), the height wrapped (`0x7729b0`). A title region answers its field
+/// (`0x768420`, `0x768410`).
 pub(super) fn measured_wh(lua: &Lua, this: &Table) -> mlua::Result<(f32, f32)> {
     let rh = region_handle_of(lua, this)?;
-    // Same-tick measure when a host font engine is installed — see `region::text`'s `natural_w`.
-    // A no-op for a Texture (not a FontString) and for an already-current measure.
+    // Measures this tick when a host font engine is installed; a no-op for a Texture or a
+    // current measure.
     super::measure::ensure_measured(lua, rh);
     let model = lua.app_data_ref::<Model>().expect("model");
     Ok(virtual_span(&model, rh))
 }
 
-/// [`measured_wh`]'s body, on a borrowed model — the form the engine's own callers want.
+/// [`measured_wh`]'s body on a borrowed model, for the engine's own callers.
 pub(super) fn virtual_span(model: &Model, rh: RegionHandle) -> (f32, f32) {
     let Some(d) = model.region_data.get(&rh) else {
         return (0.0, 0.0);
@@ -851,12 +613,9 @@ pub(super) fn virtual_span(model: &Model, rh: RegionHandle) -> (f32, f32) {
     let (aw, ah) = d.size.unwrap_or((0.0, 0.0));
     match model.arena.region(rh).map(|r| r.kind) {
         Some(RegionKind::FontString) => {
-            // The key carries the owner's effective_scale ([`RegionData::measure_key`]) — the same
-            // recipe the request loop stamps, or every read under a SetScale'd owner reports
-            // stale. Unlike the layout sweep, the getter DOES key-check: the sweep holds a
-            // last-known box so a line whose text just changed does not flicker for the frame the
-            // re-measure is in flight, and a getter that did the same would hand a caller the
-            // previous string's metric (the whisper header's latched inset).
+            // The measure key carries the owner's effective scale, as the request loop stamps it.
+            // Unlike the layout sweep, which keeps the last box, the getter refuses a stale
+            // measure rather than answer with the previous string's.
             let scale = model
                 .arena
                 .region(rh)
@@ -864,29 +623,9 @@ pub(super) fn virtual_span(model: &Model, rh: RegionHandle) -> (f32, f32) {
                 .map(|f| f.effective_scale)
                 .unwrap_or(1.0);
             let m = d.measured.filter(|m| m.key == d.measure_key(scale));
-            // **The floor applies to a KNOWN extent, and a pending measure is not one.** On the
-            // reference every extent is known — the getter measures inline — so `0.0` never comes
-            // back and the question never arises. Ours can be *waiting*, which is not a size but
-            // the absence of an answer. **Where that state still lives is a VM with no measurer
-            // installed** (`script::measure`'s is optional): the app seats one at the load edge
-            // (2028), so no in-app caller observes a pending measure any more, and the three
-            // convergence drivers this used to name went with their windows —
-            // `BenillaGossipRow_Resize` (gossip, 1751), our tab fit (1993/2028) and our quest
-            // panel (1944). Flooring a pending measure to one unit hands a measurer-less caller a
-            // number where it should read "not yet"; the surviving `OnUpdate` fits
-            // (`OptionsScroll_Fit`, `BenillaScroll_ResizeChild`) guard on RECTS, not on this.
-            //
-            // A genuinely EMPTY string is a different thing: its extent is known and it is zero, so
-            // it floors — which is the case the reference's floor exists for. The layout sweep
-            // floors unconditionally because a rect has to exist on every frame and nothing reads
-            // it as a sentinel (decision 1664); the difference between the two is exactly this
-            // pending state, which the reference does not have.
-            //
-            // "Known" is the same test the layout sweep applies: **empty text needs no
-            // round-trip** — nothing ever measures an empty string, and its extent is known
-            // without asking. So `""` is a known zero (⇒ one unit) while a pending measure on real
-            // text is no answer at all (⇒ `0.0`), and the two are only indistinguishable if you
-            // look at `measured` alone.
+            // The floor applies to a known extent. Empty text is a known zero and floors; a pending
+            // measure, possible only in a VM with no measurer installed, answers 0, where the
+            // reference measures inline and always knows.
             let floor = super::layout::FONTSTRING_MIN_SPAN;
             let known = |from_measure: fn(&crate::script::types::MeasuredText) -> f32| {
                 if d.text.as_deref().is_none_or(str::is_empty) {
@@ -924,8 +663,7 @@ pub(super) fn virtual_span(model: &Model, rh: RegionHandle) -> (f32, f32) {
                 },
             )
         }
-        // A title region is a bare `CScriptRegion` — geometry vtable `0x81c9c8`, whose `+0x1c`
-        // is the unoverridden `0x768420`. The flat field, like a frame.
+        // A title region: the flat field, like a frame (vtable `0x81c9c8`, `+0x1c` = `0x768420`).
         _ => (aw, ah),
     }
 }
diff --git a/crates/benilla-ui/src/script/region/layout.rs b/crates/benilla-ui/src/script/region/layout.rs
index 21161dc4..9f27a217 100644
--- a/crates/benilla-ui/src/script/region/layout.rs
+++ b/crates/benilla-ui/src/script/region/layout.rs
@@ -1,5 +1,4 @@
-//! Region method-table cluster: **layout** — size, anchors and the resolved-rect readers.
-//! Split out of `region.rs` at the 0716 file-size budget.
+//! The Region layout methods: size, anchors and the resolved-rect readers.
 
 use mlua::{Lua, MultiValue, Table, Value};
 
@@ -9,16 +8,15 @@ use crate::script::object::{anchor_bits_eq, frame_wrapper, point_name};
 use crate::script::region_map::{set_shared, Side};
 use crate::script::{Model, SCREEN};
 
-/// Resolve `self` (a region wrapper) to its live [`RegionHandle`].
 use super::{
     measured_wh, region_handle_of, region_ladder_context, region_owner_id, region_set_point,
     size_bits_eq,
 };
 
-/// Populate `m`'s layout methods (see the module doc).
+/// Install the layout methods into `m`.
 pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
-    // Region explicit size — fills the axes the region's anchors don't pin (unread under an
-    // implicit SetAllPoints's two corners; decision 1310).
+    // The explicit size fills the axes the anchors do not pin, so SetAllPoints's two corners
+    // leave it unread.
     set_shared(
         lua,
         m,
@@ -32,9 +30,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             let changed = !size_bits_eq(d.size, new);
             d.size = new;
             if changed {
-                // A size write moves no edge and no roster membership (decision 1388) — and on
-                // a FontString the width is the WRAP width, a measure-key input, so it names
-                // itself on the measure ledger too.
+                // No edge or roster change; the width, as wrap width, keys a FontString's measure.
                 model.touch_layout_region(rh);
                 model.touch_measure(rh);
             }
@@ -55,9 +51,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             let changed = !size_bits_eq(d.size, new);
             d.size = new;
             if changed {
-                // A size write moves no edge and no roster membership (decision 1388) — and on
-                // a FontString the width is the WRAP width, a measure-key input, so it names
-                // itself on the measure ledger too.
+                // No edge or roster change; the width, as wrap width, keys a FontString's measure.
                 model.touch_layout_region(rh);
                 model.touch_measure(rh);
             }
@@ -65,8 +59,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         },
     )?;
 
-    // **No `SetSize`** — the frame twin's note in `object/layout_methods.rs` applies here
-    // unchanged: an Era verb 1.12's Region map does not carry (decision 2142).
+    // No `SetSize`: not a 1.12 verb.
 
     set_shared(lua, m, Side::Region, "GetWidth", |lua, this: Table| {
         Ok(measured_wh(lua, &this)?.0)
@@ -76,13 +69,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         Ok(measured_wh(lua, &this)?.1)
     })?;
 
-    // GetLeft/GetRight/GetTop/GetBottom — the region's RESOLVED edges in its OWNER's units (y-up;
-    // screen ÷ the owner's effective scale, the frame twin's law in `object/layout_methods.rs` —
-    // a region shares its owner's scale, and a texture inside the scaled world map answered
-    // screen units here while its owner answered local ones, decision 1985). Every drawable
-    // region carries anchors (authored or the creation-path implicit anchor, decision 1310) and
-    // reads its resolved rect; a templateless Lua region nobody anchored never resolves → nil,
-    // same as pre-resolve.
+    // GetLeft/GetRight/GetTop/GetBottom: the resolved edges in the owner's units (y up, screen
+    // over the owner's effective scale, which a region shares); nil for a region never resolved.
     for (name, pick) in [
         ("GetLeft", 0u8),
         ("GetRight", 1u8),
@@ -104,10 +92,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?;
     }
 
-    // Region anchors: SetPoint/ClearAllPoints/SetAllPoints mirror the frame versions
-    // ([`super::object`]) but write [`super::RegionData::anchors`]. An unspecified `relativeTo`
-    // defaults to the **owner frame**; a named one may be a frame or a sibling region (the real
-    // XML anchors regions to sibling regions everywhere — merchant label plate → `$parentSlot`).
+    // SetPoint, ClearAllPoints and SetAllPoints write the region's anchors. `relativeTo` defaults
+    // to the owner frame, and a named one may be a frame or a sibling region, as stock XML uses.
     set_shared(
         lua,
         m,
@@ -125,9 +111,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             let rh = region_handle_of(lua, &this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
             let d = model.region_data.entry(rh).or_default();
-            // Names its node, the frame twin's rule and for the frame twin's reason (decision
-            // 2114): clearing every anchor is a retarget onto an EMPTY target list, so the cached
-            // graph's edges are unlinked rather than the whole graph re-derived.
+            // A retarget onto no targets: the cached graph unlinks the edges, no re-derive.
             let old: Option<Vec<u32>> =
                 (!d.anchors.is_empty()).then(|| d.anchors.iter().map(|a| a.relative_to).collect());
             d.anchors.clear();
@@ -145,7 +129,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         "SetAllPoints",
         |lua, (this, rest): (Table, MultiValue)| {
             let rh = region_handle_of(lua, &this)?;
-            // `who`/`$parent` first, then the `_G` read, then the guard — `region_ladder_context`.
+            // `who` and `$parent` first, then the `_G` read, then the guard.
             let (who, base) = region_ladder_context(lua, rh);
             let target = parse_set_all_points(lua, rest.front(), &base);
             let mut model = lua.app_data_mut::<Model>().expect("model");
@@ -172,17 +156,11 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         },
     )?;
 
-    // ── The rest of the Region map `0xcf54b4` ───────────────────────────────────────────────────
+    // ── the rest of the Region map (`0xcf54b4`) ─────────────────────────────────────────────────
     //
-    // These four landed together because the MAP is the unit, not the name. `SetParent` shipped
-    // alone when one addon line named it, and its own getter stayed missing for months — which is
-    // how `TheoryCraft\TheoryCraftUI.lua:720` (`buttontext:GetParent()`, a FontString) died every
-    // session, and how the per-kind census came to read `115 GetParent (missing on Texture,
-    // FontString)`. The set is closed and byte-verified, so it is asserted as a set in
-    // `tests/reference_surface.rs` rather than grown a name at a time.
+    // The map is a closed set, `script::REGION_MAP_METHODS`, and a test asserts it whole.
 
-    // GetParent() → the OWNER frame's wrapper. A region always has one (`region_owner_id` falls
-    // back to the owner for every unresolved case), so unlike the frame twin this never answers nil.
+    // GetParent: the owner frame, which a region always has, so never nil.
     set_shared(lua, m, Side::Region, "GetParent", |lua, this: Table| {
         let rh = region_handle_of(lua, &this)?;
         let owner = {
@@ -192,13 +170,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         frame_wrapper(lua, owner)
     })?;
 
-    // GetCenter() → the resolved rect's midpoint, or a nil PAIR before the first resolve — the same
-    // contract, and the same source, as the GetLeft/GetRight/GetTop/GetBottom readers above.
-    //
-    // **Deliberately unscaled, where the frame twin divides by GetEffectiveScale.** The region edge
-    // readers report raw resolved units; scaling only the centre would make `GetCenter()` disagree
-    // with `(GetLeft() + GetRight()) / 2` on any scaled subtree — a contradiction inside one method
-    // table is worse than a missing division, and regions have no scale of their own to divide by.
+    // GetCenter: the resolved rect's midpoint in the owner's units, as the edge readers answer, or
+    // two nils before the first resolve.
     set_shared(lua, m, Side::Region, "GetCenter", |lua, this: Table| {
         let rh = region_handle_of(lua, &this)?;
         let model = lua.app_data_ref::<Model>().expect("model");
@@ -212,8 +185,6 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })
     })?;
 
-    // GetNumPoints() → how many anchors this region carries. Absent on our FRAMES too, which is the
-    // same drift one table up; this side is what the corpus named.
     set_shared(lua, m, Side::Region, "GetNumPoints", |lua, this: Table| {
         let rh = region_handle_of(lua, &this)?;
         let model = lua.app_data_ref::<Model>().expect("model");
@@ -223,14 +194,9 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             .map_or(0, |d| d.anchors.len() as i64))
     })?;
 
-    // GetPoint([n]) → point, relativeTo, relativePoint, xOfs, yOfs — the n-th (1-based, default
-    // first) anchor, mirroring the frame twin including its out-of-range answer (five nils).
-    //
-    // **The relativeTo dispatch is the part a frame-shaped copy gets wrong.** Region anchors live in
-    // ONE id space with frames and may target a sibling REGION — the real XML does it everywhere
-    // (`region.rs`'s `resolve_target`: frames first, then the region-name registry). So the id is
-    // matched against both tables and answered with the matching wrapper kind; handing back a frame
-    // wrapper for a region id would be a working-looking handle onto the wrong object.
+    // GetPoint([n]): the n-th anchor (1-based, default 1) as point, relativeTo, relativePoint, x
+    // and y, or five nils. Frames and regions share one id space and a region may anchor to a
+    // sibling region, so relativeTo is answered with the matching wrapper kind.
     set_shared(
         lua,
         m,
@@ -275,8 +241,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
     Ok(())
 }
 
-/// The region's owner frame's effective scale (1 for an orphan) — the divisor that turns a
-/// resolved screen rect into the owner's units, the space every region getter answers in.
+/// The owner frame's effective scale (1 for an orphan), the divisor from a resolved screen rect to
+/// the owner's units every region getter answers in.
 fn owner_scale(model: &Model, rh: crate::widget::RegionHandle) -> f32 {
     model
         .arena
diff --git a/crates/benilla-ui/src/script/region/paint.rs b/crates/benilla-ui/src/script/region/paint.rs
index 6a238788..6c6691a2 100644
--- a/crates/benilla-ui/src/script/region/paint.rs
+++ b/crates/benilla-ui/src/script/region/paint.rs
@@ -1,20 +1,17 @@
-//! Region method-table cluster: **paint** — what a Texture shows and how it is tinted,
-//! blended, cropped and layered. Split out of `region.rs` at the 0716 file-size budget.
+//! The region paint methods: what a Texture shows and how it is tinted, blended, cropped and
+//! layered.
 
 use mlua::{Lua, MultiValue, Table, Value};
 
 use crate::script::object::{as_f32, draw_layer_from_str, draw_layer_name};
 use crate::script::{BlendMode, Model, TexCoords};
 
-/// Resolve `self` (a region wrapper) to its live [`RegionHandle`].
 use super::region_handle_of;
 
-/// Populate `m`'s paint methods (see the module doc).
+/// Install the paint methods into `m`.
 pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
-    // SetAlpha/GetAlpha — the region's own alpha, distinct from the owner frame's. The ref kit reads
-    // it back to ramp a texture (CastingBarFrame's completion flash does
-    // `CastingBarFlash:SetAlpha(GetAlpha() + CASTING_BAR_FLASH_STEP)`), so the getter must return the
-    // region's value, never the frame's. Draw law + the open question: [`RegionData::alpha`].
+    // SetAlpha/GetAlpha: the region's own alpha, not the owner frame's; stock
+    // `CastingBarFrame.lua:133` reads it back to ramp its flash. `RegionData::alpha` has the draw.
     m.set(
         "SetAlpha",
         lua.create_function(|lua, (this, alpha): (Table, f32)| {
@@ -38,28 +35,10 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // **KNOWN DIVERGENCE, byte-pinned and deliberately not closed here (decision 1782).** An
-    // ABSENT alpha argument is 1.0 below; in the reference it is *the alpha already on the region*.
-    // `0x79abd0` reads the current colour back (`0x79ac81` -> `0x77f8c0`), packs the caller's rgb
-    // against an `a` default of 1.0 (`0x79ad43`), and then asks a SECOND time whether argument 5
-    // was present — when it was not, it copies byte 3 of the read-back colour over the packed
-    // alpha (`0x79adfe`/`0x79ae0a`) before the store. So `SetVertexColor(r, g, b)` on 1.12.1 is
-    // `SetVertexColor(r, g, b, currentAlpha)`, and a three-argument call CANNOT restore opacity.
-    //
-    // Why it still says 1.0: the fix is one line, but its blast radius is every three-argument
-    // call in FrameXML and in the addon corpus, and it only bites where a region already carries
-    // alpha < 1 — where it would surface as art going permanently translucent, which is a LOOK and
-    // therefore the director's call, not a quiet correction to fold into an unrelated slice. The
-    // known live case is the action bar's grid ring: stock `ActionButton_ShowGrid` passes the
-    // fourth argument explicitly (`SetVertexColor(1.0, 1.0, 1.0, 0.5)`), so closing this cannot
-    // silently change that file.
-    //
-    // **Shape C on r, g, b** (`Texture:SetVertexColor `0x79abd0``, `2=C 3=C 4=C 5=B`): a bare
-    // `lua_tonumber` with no `lua_isnumber` gate, so a nil,
-    // a table or a string is **0.0** and the call never raises. Taking them as `f32` made mlua's
-    // converter the gate instead — the 2176 class — and the stock
-    // `QuestLogFrame.lua:337` idiom hands three nils (`titleButton.r/g/b` are only assigned in
-    // `QuestLog_Update`) on any path that selects a quest-log entry before the window has painted.
+    // SetVertexColor (`0x79abd0`) reads r, g and b with a bare `lua_tonumber`, so nil or a table is
+    // 0 and never raises; stock `QuestLogFrame.lua:337` can pass three nils. A missing alpha is 1
+    // here; the reference keeps the region's current alpha (read back at `0x79ac81`, copied over
+    // at `0x79adfe`/`0x79ae0a`), so there a three-argument call cannot restore opacity.
     m.set(
         "SetVertexColor",
         lua.create_function(
@@ -69,17 +48,14 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 let mut model = lua.app_data_mut::<Model>().expect("model");
                 let d = model.region_data.entry(rh).or_default();
                 d.vertex_color = Some([r, g, b, a.unwrap_or(1.0)]);
-                // The same slot `SetTextColor` writes on a FontString, so it is the same explicit
-                // colour set as far as font-object inheritance is concerned.
+                // The slot `SetTextColor` writes on a FontString, so it overrides the font object.
                 d.font_explicit.color = true;
                 Ok(())
             },
         )?,
     )?;
 
-    // GetVertexColor — the setter's own pair, a real 5875 binding (`0x79aa50`; it sits directly
-    // above `SetVertexColor 0x79abd0` in the same region method family). Never set = the untinted
-    // white every region draws at by default.
+    // GetVertexColor (`0x79aa50`): white when never set.
     m.set(
         "GetVertexColor",
         lua.create_function(|lua, this: Table| {
@@ -94,19 +70,10 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetGradientAlpha(orientation, r1,g1,b1,a1, r2,g2,b2,a2) and its alpha-less twin
-    // SetGradient(orientation, r1,g1,b1, r2,g2,b2) — the two-stop linear gradient the client
-    // generates into the same `+0xcc` texture slot the colour form of SetTexture fills.
-    //
-    // These were missing, and they were the single wall in front of the corpus's largest family:
-    // `FuBar\FuBar_Panel.lua:144` calls SetGradientAlpha while building the bar, so all 20 FuBar
-    // plugins died there — after the debugstack/chunk-name fix got them that far.
-    //
-    // The orientation token is matched case-insensitively and anything that is not "VERTICAL" is
-    // horizontal, which is the client's own leniency and matters because addons spell it both ways.
-    // The gradient is stored WHOLE (see `RegionData::gradient`); the paint folds it to its midpoint
-    // because a quad carries one tint today. That approximation is visible and is recorded at the
-    // field, not hidden here.
+    // SetGradientAlpha(orientation, r1, g1, b1, a1, r2, g2, b2, a2) and SetGradient without the
+    // alphas: a two-stop gradient the client generates into the texture slot (`+0xcc`); here it is
+    // stored whole and drawn as its midpoint. Any orientation but "VERTICAL", in any case, is
+    // horizontal.
     for (name, with_alpha) in [("SetGradientAlpha", true), ("SetGradient", false)] {
         m.set(
             name,
@@ -118,7 +85,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 };
                 let orientation = match it.next() {
                     Some(Value::String(s)) => s.to_str()?.to_string(),
-                    // A missing/!string orientation is horizontal, like any non-"VERTICAL" token.
+                    // A missing or non-string orientation is horizontal.
                     _ => String::new(),
                 };
                 let n = if with_alpha { 8 } else { 6 };
@@ -147,101 +114,50 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
 
     m.set(
         "SetTexture",
-        // The trailing three are `Value`, not `Option<f32>`, and that is a fidelity fix rather than
-        // laxity. The path form reads ONE argument (`0x770200`); only the colour form
-        // (`0x770360`) reads up to four. A C function takes what it wants off the Lua stack and
-        // ignores the rest, so `SetTexture(path, true)` is fine on the real client — and typing
-        // these as `Option<f32>` made us raise on it, `bad argument #3: error converting Lua
-        // boolean to f32`, in a call the client accepts silently.
-        //
-        // Found by `_LazyPig/LazyPigMenu.lua:182`
-        // (`texture_title:SetTexture("Interface\DialogFrame\UI-DialogBox-Header", true)`), which
-        // reached us only once the survey started seating the addon registry — the whole point of
-        // that instrument fix. The stray `true` is meaningless in 1.12 and the addon author
-        // presumably meant a later client's second parameter; either way the client shrugs.
-        // The RETURN is part of the contract (`SetTexture 0x79bb40`): the path form answers
-        // **1 | nil — nil meaning the file did not load** — and the colour
-        // and clear forms answer 1. Atlas is the load-bearing caller: `Atlas_Refresh` does
-        // `local builtIn = AtlasMap:SetTexture("…\Images\Maps\"..zoneID)` and walks its plugin
-        // fallback chain on nil, so a binding that returns nothing draws no map at all whatever
-        // the file resolver does. The load verdict comes from the host's [`Model::texture_probe`]
-        // (existence across patch chain + loose addon folder — the same candidate walk the
-        // renderer resolves with); a VM with no probe installed has no backend, so its path form
-        // stays nil, which is both literally true and what every engine-less test always observed.
+        // The path form reads one argument (`0x770200`), the colour form (`0x770360`) up to four,
+        // and extras such as `SetTexture(path, true)` are ignored. `SetTexture` (`0x79bb40`)
+        // answers 1, or nil when the path form's file does not load, as the host's
+        // `Model::texture_probe` judges; with no probe the path form answers nil.
         lua.create_function(
             |lua, (this, arg, g, b, a): (Table, Value, Value, Value, Value)| {
                 let rh = region_handle_of(lua, &this)?;
-                // Scoped, so the model borrow is provably gone before the layout touch below —
-                // the path arm hands it back mid-way (to call the host probe without holding a
-                // mutable borrow across a host callback) and the others do not.
+                // Scoped so the model borrow ends before the layout touch; the path arm drops it
+                // mid-way to call the host probe.
                 let (loaded, derived) = {
                     let mut model = lua.app_data_mut::<Model>().expect("model");
-                    // A plain SetTexture makes the region ordinary again — drop any portrait circular mask
-                    // and any live-unit-portrait binding.
+                    // SetTexture drops any portrait mask and live-unit binding.
                     let data = model.region_data.entry(rh).or_default();
                     data.circular = false;
                     data.portrait_unit = None;
-                    // **`SetTexture` CLEARS the desaturation**: `+0x128` is a `CGxShader*`, and
-                    // `CSimpleTexture::SetTexture` (`0x770200`) writes it from its 4th stack arg,
-                    // for which the Lua binding
-                    // (`0x79bb40`) pushes slot 0 — permanently NULL — on both of its legs. A
-                    // re-implementation that keeps a desaturate boolean independent of the texture
-                    // handle diverges on every `icon:SetDesaturated(1)` followed by `icon:SetTexture(t)`.
-                    //
-                    // Scoped exactly as the binary scopes it:
-                    //  · the **same path** is inert — `0x770225` returns before ever reaching the write,
-                    //    so a repaint that re-sets the icon it already shows keeps its grey;
-                    //  · `nil`/`""` DO clear — the `test esi,esi` leg falls through to the write;
-                    //  · the **colour form** does NOT — that is `0x770360`, which is not among the four
-                    //    writers of the field.
+                    // SetTexture clears the desaturation: `0x770200` writes the shader slot
+                    // (`+0x128`) from an argument the binding (`0x79bb40`) always passes NULL. The
+                    // same path returns first (`0x770225`) and keeps it, nil or "" clear it, and
+                    // the colour form (`0x770360`) never writes it.
                     let same_path = matches!((&arg, &data.texture),
                     (Value::String(s), Some(cur)) if s.to_str().is_ok_and(|s| *s == **cur));
                     let colour_form = matches!(&arg, Value::Number(_) | Value::Integer(_));
                     if !same_path && !colour_form {
                         data.desaturated = false;
                     }
-                    // Does this region's rect come from its ART? An axis authored `0` takes its span
-                    // from the content (decision 1349, `script::layout::content_span`), so on that
-                    // shape — and only there — swapping the texture MOVES the region and the resolve
-                    // has to hear about it. Read before the match, which writes the art and never the
-                    // size.
-                    //
-                    // **An ANCHOR-LESS region is not that shape**, whatever its size: with no
-                    // pinned edge and no center there is nothing for a span to be added to
-                    // (`combine_edge` needs one), so every edge stays unset — which is why the
-                    // resolve sweep skips such regions outright. Painting one is a paint, not a
-                    // layout change, and saying otherwise would re-open the change gate on every
-                    // `CreateTexture(…):SetTexture(…)` in the UI (decisions 0740/1385/1388).
+                    // An anchored region with an axis sized 0 takes that span from its art, so a
+                    // new texture moves it; an anchorless region never resolves, so for it this
+                    // is only a paint.
                     let derived = !data.anchors.is_empty()
                         && data.size.is_none_or(|(w, h)| w == 0.0 || h == 0.0);
-                    // Both forms write the SAME `+0xcc` texture slot — the path form loads a file
-                    // there (`0x770200`), the colour form generates an 8×8 solid into it
-                    // (`0x770360`) — so each clears the other. NEITHER touches the vertex colour at
-                    // `+0xb8`: a tint outlives the art it was tinting.
+                    // Both forms write the one texture slot (`+0xcc`), a file or an 8×8 solid, so
+                    // each clears the other; neither touches the vertex colour (`+0xb8`), so a
+                    // tint outlives its art.
                     let loaded = match &arg {
-                        // SetTexture("") clears, same as SetTexture(nil) — the ref lua blanks state
-                        // art with the empty string (QuestLogFrame.lua:165-166). The return for ""
-                        // is read as the path form's failure (nothing loads from an empty name);
-                        // INFERRED — no corpus caller reads it.
+                        // "" clears, as nil does (stock `QuestLogFrame.lua:166`), and answers nil
+                        // like a failed load; the reference's answer for "" is untraced.
                         Value::String(s) if s.to_str()?.is_empty() => {
                             data.texture = None;
                             data.fill = None;
                             false
                         }
-                        // **Ask the probe BEFORE writing the slot.** The reference's load-FAILURE
-                        // arm (`cmp [ebp-4],2; jl` at `0x770288` → `0x77028e`–`0x7702b2`) releases
-                        // the handle it just built and returns 0 **leaving `+0xcc` and `+0x128` as
-                        // they were** — the widget keeps whatever texture it already had. Storing
-                        // the path first and letting the verdict drive only the *return value*
-                        // meant a mistyped or not-yet-shipped path ERASED the art it failed to
-                        // replace, and did it silently: `GetTexture()` echoed the missing path and
-                        // the quad was dropped, so the region went blank with nothing said
-                        // (decision 2124).
-                        //
-                        // The store and the return ask deliberately different questions. A VM with
-                        // **no probe installed** has no backend to ask, so it stores — that is
-                        // every engine-less test's world, and the module head already states that
-                        // such a VM's path form "stays nil", which is the return, not the slot.
+                        // Ask the probe before writing: on a failed load the reference returns 0
+                        // and keeps the texture it had (`0x770288`, `0x77028e`-`0x7702b2`). With
+                        // no probe the path is stored, though the answer is nil.
                         Value::String(s) => {
                             let path = s.to_str()?.to_string();
                             drop(model);
@@ -261,9 +177,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                             }
                             resolvable && had_probe
                         }
-                        // The colour form, and the ONLY branch that looks at the trailing three. A
-                        // non-numeric there takes the same default a missing one does, which is what
-                        // reading off a C stack does: `lua_tonumber` on a non-number yields 0.
+                        // The colour form, the only one to read the trailing three; a non-number
+                        // there takes the default a missing one does.
                         Value::Number(_) | Value::Integer(_) => {
                             let chan = |v: &Value, dflt: f32| match v {
                                 Value::Number(_) | Value::Integer(_) => as_f32(v),
@@ -279,9 +194,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                             data.texture = None;
                             true
                         }
-                        // SetTexture(nil) clears (the live API's blank-the-region form); a cleared
-                        // texture region draws nothing. Returns 1 (`SetTexture 0x79bb40`'s
-                        // `SetTexture(nil) / ()` row).
+                        // nil clears, so the region draws nothing, and answers 1 (`0x79bb40`).
                         Value::Nil => {
                             data.texture = None;
                             data.fill = None;
@@ -291,10 +204,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                     };
                     (loaded, derived)
                 };
-                // Named precisely, and only on the content-derived shape: an ordinary sized icon's
-                // rect cannot move here, and touching the layout on every icon repaint would
-                // re-open the resolve's change gate every frame for a rect nobody moved
-                // (decisions 0740/1385/1388).
+                // Only the art-sized shape can move; touching the layout on every repaint would
+                // reopen the resolve's change gate each frame.
                 if derived {
                     lua.app_data_mut::<Model>()
                         .expect("model")
@@ -309,41 +220,12 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         )?,
     )?;
 
-    // SetDesaturated(flag) -> shaderSupported — Texture only (`0x79c1e0`; the reference's own
-    // `ItemButtonTemplate.lua:69` is `local shaderSupported =
-    // icon:SetDesaturated(desaturated)`).
-    //
-    // **The RETURN is the whole design, and it is the half a plausible implementation drops.**
-    // 1.12 ran on cards that could not do the shader, so the verb reports whether it took effect
-    // and FrameXML falls back by hand:
-    //
-    //     if ( not desaturated ) then r,g,b = 1,1,1
-    //     elseif ( not r or not shaderSupported ) then r,g,b = 0.5,0.5,0.5 end
-    //     icon:SetVertexColor(r, g, b)
-    //
-    // The renderer now greys the texel (decision 1327 — `ui_quad.wgsl`'s luminance fold), so we
-    // answer **1 — supported**, and the branch above takes its shader arm: the icon goes greyscale
-    // AND wears the caller's own dim tint. Until 1327 this answered nil, which is a real 1.12
-    // card's answer and was the honest one while nothing greyed — but it costs the *look*: a 0.65
-    // grey multiply on colourful art is a dimmer, still-colourful icon, which is precisely what
-    // B162 reported against the talent tree.
-    //
-    // Why it matters far past one verb: **98 of the 109 addons that draw and then raise on being
-    // used, raise here** — `FuBar_Panel.lua:43`'s right-click reaches Dewdrop's `AddLine`
-    // (`Dewdrop-2.0.lua:2172`), which calls `button.arrow:SetDesaturated(true)` unguarded. A
-    // static scan costed this at 61 addons and it was declined; the use-probe costed it at 98 the
-    // moment anyone right-clicks.
-    //
-    // **The argument's truth table is not `if flag then`** (`0x6f1c10(L, 2, default=1)`,
-    // dispatched through the jump table at `0x6f1ce8`). Two
-    // of its arms are the opposite of the obvious reading, and both are reachable:
-    //  · **no argument at all is ON**, not off — `LUA_TNONE` takes the `ja` default arm, so
-    //    `tex:SetDesaturated()` greys. This is why the flag arrives as a `MultiValue`: mlua hands a
-    //    missing `Value` parameter through as `Nil`, which is the one arm that means OFF.
-    //  · **a number truncating to 0 is OFF** (`0x6f3620`+`0x40a2b0`), so `SetDesaturated(0)` clears.
-    //  · a table/function/userdata is ON (same default arm as absent).
-    // The string arm (`0x6f1c51`, comparing against `0x871460`/`0x853758`) is NOT modelled — no
-    // corpus caller passes one, and the comparands were not read; a string takes the ON arm here.
+    // SetDesaturated(flag) (`0x79c1e0`), Texture only, answers shaderSupported, which stock
+    // `ItemButtonTemplate.lua:69` reads to fall back to a grey tint; the renderer greys the texel,
+    // so this answers 1. The flag is `GetBoolOrDefault` (`0x6f1c10`, default 1, jump table
+    // `0x6f1ce8`): no argument is on, hence the `MultiValue`, nil is off, a number truncating to 0
+    // is off (`0x6f3620`, `0x40a2b0`), and a table, function or userdata is on. Every string is on
+    // here; the reference's string arm (`0x6f1c51`, against `0x871460` and `0x853758`) is not.
     m.set(
         "SetDesaturated",
         lua.create_function(|lua, args: MultiValue| {
@@ -363,28 +245,14 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             let rh = region_handle_of(lua, &this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
             model.region_data.entry(rh).or_default().desaturated = on;
-            // 1, not true: the reference's `shaderSupported` is a 1|nil C answer (byte-verified —
-            // `0x6f3810 lua_pushnumber(L, 1.0)`, never `false`, never zero values) and callers
-            // write `not shaderSupported`.
+            // 1, not true: the reference pushes the number 1 (`0x6f3810`).
             Ok(Value::Number(1.0))
         })?,
     )?;
 
-    // GetTexture() — Texture only (`0x79ba70`). Three contract details are each the kind a
-    // plausible implementation gets silently wrong, so each is spelled out:
-    //
-    //  · **Exactly ONE return value**, never a multi-return.
-    //  · **The colour form returns the literal string `"Solid Texture"`** (`0x835708`), NOT nil.
-    //    `SetTexture(r,g,b)` synthesizes an 8x8 solid, and the getter reports that name — so an
-    //    addon's `if not tex then` passes straight through on a colour-filled region. Returning nil
-    //    here would look tidier and would be wrong in the one direction callers test for.
-    //  · **The path is stripped at the LAST `.`** (`0x79baf0`): the loader appends `.blp`/`.tga` to
-    //    what was set and the getter strips an extension back off. Taken verbatim rather than
-    //    "strip only a real extension" — a directory containing a dot is mangled by the real client
-    //    too, and this surface is a transcription, not an improvement.
-    //
-    // Four corpus addons: `AtlasQuest.lua:228` (`AQATLASMAP = AtlasMap:GetTexture()`) and
-    // `FuBarPlugin-2.0.lua:343` (`return self.iconFrame:GetTexture()`), each reached by two addons.
+    // GetTexture (`0x79ba70`), Texture only, answers one value: "Solid Texture" for the colour
+    // form (`0x835708`), not nil, and a path cut at its last `.` (`0x79baf0`), even a dot in a
+    // directory name, as the client cuts it.
     m.set(
         "GetTexture",
         lua.create_function(|lua, this: Table| {
@@ -403,9 +271,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetAlphaGradient(start, length) — the per-character write-on reveal (CSimpleFontString;
-    // the quest-description machinery, ref QuestFrame.lua:548/558). Returns whether `start` is
-    // still inside the text (chars) — the ref's OnUpdate loop advances until this goes false.
+    // SetAlphaGradient(start, length), a FontString's write-on reveal: answers whether `start` is
+    // still inside the text in chars, and stock `QuestFrame.lua:558` advances until it is not.
     m.set(
         "SetAlphaGradient",
         lua.create_function(|lua, (this, start, length): (Table, f32, f32)| {
@@ -418,14 +285,9 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetBlendMode("DISABLE"|"ALPHAKEY"|"BLEND"|"ADD"|"MOD") — `0x79a950`, the shared alphaMode
-    // enum `0x811aa8`. Only ADD changes draw behavior in v1 (DISABLE/ALPHAKEY/MOD are accepted as
-    // straight alpha, a stated gap — see [`BlendMode`]); an unrecognised name leaves the mode
-    // alone, which is what the enum-table lookup does with a string it cannot match.
-    //
-    // The mode is STORED as the mode. It used to collapse to `additive = (mode == "ADD")` on the
-    // way in, which is everything the renderer needs and strictly less than `GetBlendMode` has to
-    // answer — a texture set to `"MOD"` would have read back as `"BLEND"`.
+    // SetBlendMode (`0x79a950`, the alphaMode enum `0x811aa8`) stores the mode as given; an
+    // unknown name leaves it alone, as the enum lookup does. Only ADD draws differently here, the
+    // others as straight alpha.
     m.set(
         "SetBlendMode",
         lua.create_function(|lua, (this, mode): (Table, String)| {
@@ -437,18 +299,9 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // GetBlendMode() — ONE string, the enum's own spelling (`0x79a890`, table `0x87c128`, argc 1,
-    // arity 1, kinds `(string?)`). A Texture nothing has called the setter on answers `"BLEND"`,
-    // the CSimpleTexture ctor's `[+0xd0] = 2` (`0x76fc64`).
-    //
-    // **This one was answering nil, and nil is not an error here — it is a wrong picture.**
-    // `ShaguTweaks/mods/dark-ui-elements.lua:169` reads
-    // `elseif region.GetBlendMode and region:GetBlendMode() == "ADD" then` while recolouring a
-    // Blizzard frame's children: the `and` guard means a missing method never raised, it just took
-    // the other branch, so every additive texture in the frame got the dark recolour the reference
-    // leaves alone. The kinds column's `string?` is the reference's own nil leg (the name pointer
-    // can be NULL for a mode outside the table); the five modes are all this engine can hold, so
-    // nothing here reaches it.
+    // GetBlendMode (`0x79a890`, table `0x87c128`): one string, the enum's spelling, "BLEND" when
+    // never set (the ctor's `[+0xd0] = 2`, `0x76fc64`). The reference's nil, for a mode outside
+    // its table, cannot arise from the five modes here.
     m.set(
         "GetBlendMode",
         lua.create_function(|lua, this: Table| {
@@ -462,30 +315,16 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetTexCoordModifiesRect(flag) / GetTexCoordModifiesRect() — `0x79c080` / `0x79c120`, table
-    // `0x87c128`. The setter writes the reference's `[texture+0x124]` and is its only writer; the
-    // getter answers `1`/`nil` (kinds `(nil) | (number)`, the predicate law — decision 2118 — not a
-    // Lua boolean).
-    //
-    // **The flag's GEOMETRY effect is not wired, and that is stated rather than implied.** In the
-    // reference the flag gates a rect-recompute leg (`0x770462`): with it set, a
-    // `SetTexCoord` re-derives the region's own rect from the UV quad instead of leaving the rect
-    // where the anchors put it and resampling inside it. Wiring that means the region resolve in
-    // `region::layout` reading this flag and taking the rect from `RegionData::tex_coords` — a
-    // resolve-order change. Nothing in the stock UI or in either addon corpus calls the SETTER, so
-    // there is no measured case to build it against; what has a caller is the GETTER —
-    // `pfUI/modules/thirdparty-tbc.lua:319` does a bare `if icon:GetTexCoordModifiesRect() then` on
-    // a Texture to choose between two `SetTexCoord` rectangles, and against this VM that raised.
-    // So: the flag is stored, answered truthfully, and read by nothing. See
-    // [`RegionData::tex_coord_modifies_rect`].
+    // SetTexCoordModifiesRect/GetTexCoordModifiesRect (`0x79c080`/`0x79c120`, table `0x87c128`):
+    // the setter is the only writer of `[texture+0x124]`, the getter answers 1 or nil. Stored, not
+    // applied: there a set flag makes `SetTexCoord` re-derive the rect from the UV quad
+    // (`0x770462`).
     m.set(
         "SetTexCoordModifiesRect",
         lua.create_function(|lua, (this, arg): (Table, Value)| {
             let rh = region_handle_of(lua, &this)?;
-            // The reference's shared flag-argument truth table (`0x6f1c10(L, 2, default)`), whose
-            // DEFAULT byte for this binding is unread — no corpus site calls the setter at all, so
-            // the no-argument leg is doubly unreachable and `false` is the conservative pick rather
-            // than a claim about `0x79c080`.
+            // `GetBoolOrDefault` (`0x6f1c10`) with default 1 (`0x79c105`), but a missing argument
+            // arrives here as nil and reads false, where the reference sets the flag.
             let on = crate::script::binding_abi::bool_or_default(Some(&arg), false);
             let mut model = lua.app_data_mut::<Model>().expect("model");
             model
@@ -527,17 +366,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetDrawLayer() — the setter's pair, present on BOTH region leaves in the client (Texture
-    // `0x79a6c0`, FontString `0x79c660`, each its own copy — read off the method-table pair bytes).
-    //
-    // This module's own note used to end "GetDrawLayer is in the client's pair and absent here;
-    // absent is absent" — accurate, and a gap rather than a decision. pfUI's `GetNoNameObject`
-    // (api/api.lua:1342) reads it off every child while reskinning a Blizzard frame, and died
-    // there; that is the measurement (1719).
-    //
-    // Returns the layer NAME alone. The sub-level we store beside it is not a second return here:
-    // 1.12's pair is layer-only, and `SetDrawLayer`'s optional sub-level argument above is already
-    // marked as this engine's extension point.
+    // GetDrawLayer (Texture `0x79a6c0`, FontString `0x79c660`): the layer name alone, since
+    // 1.12's pair is layer-only; the sub-level `SetDrawLayer` accepts is not 1.12's.
     m.set(
         "GetDrawLayer",
         lua.create_function(|lua, this: Table| {
@@ -551,49 +381,30 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `SetRotation` WAS here, on the Texture leaf, and is GONE. 1.12 registers the name once, in
-    // the **PlayerModel** table `0x84f1fc` (`0x505f00`, argc 2 — the paper doll's rotate arrows),
-    // which we already answer through `modelframe`; it is in neither region map, and the complete
-    // membership census (`0x87c128`/`0xcf5400`) lists it among the five names that are in NEITHER.
-    // Ours was a later-era Texture verb shipped early for the world-map player arrow's stand-in
-    // rotation — and that arrow has since become a real Model frame driven by `ModelState::facing`
-    // (`script::worldmap_arrow`), so the verb's own reason went with it.
-    //
-    // Removal is safe by census, not by assumption: every `SetRotation` in this repo, in
-    // `assets/ui`, in the stock FrameXML/GlueXML and in both addon corpora has a MODEL receiver —
-    // `pfUI/api/ui-widgets.lua:580`'s `EnableClickRotate` hooks a modelframe's OnUpdate, and
-    // `CustomNameplates/options.lua:308` is `optionsFrame.preview.model:SetRotation(0.61)`. Not one
-    // texture receiver anywhere.
-    //
-    // `RegionData::rotation` and `QuadContent::Texture::rotation` now have no writer left. They are
-    // deliberately NOT pruned in the same change: that plumbing runs into the app's quad emit and
-    // its removal is a wider prune with its own review, not a tail on a method-surface fix.
+    // No Texture `SetRotation`: 1.12 registers it only on PlayerModel (`0x505f00`, table
+    // `0x84f1fc`), in neither region map (`0x87c128`, `0xcf5400`).
 
-    // SetTexCoord(left, right, top, bottom) — the 4-edge form (XML `<TexCoords>`): a UV sub-rect in
-    // 0..1 texture space (top-left origin) the Texture region samples, slicing quadrant/atlas art
-    // (decision 0084). SetTexCoord(ULx,ULy, LLx,LLy, URx,URy, LRx,LRy) — the 8-arg affine form: an
-    // arbitrary UV quad (rotation/shear — the reference's `DrawRouteLine` route lines), stored per
-    // corner in the renderer's screen winding.
+    // SetTexCoord(left, right, top, bottom), XML `<TexCoords>`: a UV sub-rect in 0..1, origin top
+    // left. SetTexCoord(ULx, ULy, LLx, LLy, URx, URy, LRx, LRy): any UV quad, as stock
+    // `TaxiFrame.lua:223` draws route lines, stored per corner in screen winding.
     m.set(
         "SetTexCoord",
-        // Every coordinate is **shape C** (`Texture:SetTexCoord 0x79beb0`, all positions C): bare
-        // `lua_tonumber`, nil/table/string → 0.0. Only
-        // the ARITY raises (`0x79bf5d dec eax ; cmp eax,4 ; je ; cmp eax,8 ; je`), which is the
-        // match below. `Variadic<f32>` made mlua the per-coordinate gate; it is not one.
+        // Each coordinate is a bare `lua_tonumber` (`0x79beb0`), so nil or a table is 0; only the
+        // count is gated, 4 or 8 (`0x79bf5d`).
         lua.create_function(|lua, (this, args): (Table, mlua::Variadic<Value>)| {
             let rest: Vec<f32> = args.iter().map(as_f32).collect();
             let rh = region_handle_of(lua, &this)?;
             let coords = match rest.len() {
                 4 => Some(TexCoords::Rect([rest[0], rest[1], rest[2], rest[3]])),
-                // The live arg order is UL, LL, UR, LR (corner pairs); [`TexCoords::Corners`]
-                // stores screen order [TL, TR, BR, BL].
+                // The arguments come UL, LL, UR, LR; `TexCoords::Corners` stores TL, TR, BR, BL.
                 8 => Some(TexCoords::Corners([
                     [rest[0], rest[1]], // UL → TL
                     [rest[4], rest[5]], // UR → TR
                     [rest[6], rest[7]], // LR → BR
                     [rest[2], rest[3]], // LL → BL
                 ])),
-                // No args resets to the full texture (the live API's clear form).
+                // No arguments resets to the full texture, which is not 1.12's: its gate takes 4
+                // or 8.
                 0 => None,
                 n => {
                     return Err(mlua::Error::runtime(format!(
@@ -611,29 +422,21 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTexCoord() → left, right, top, bottom (the 4-edge form; full texture if never set; an
-    // affine mapping reports its bounding edges).
+    // GetTexCoord: the four corners, the full texture when never set.
     m.set(
         "GetTexCoord",
         lua.create_function(|lua, this: Table| {
             let rh = region_handle_of(lua, &this)?;
             let model = lua.app_data_ref::<Model>().expect("model");
-            // EIGHT values — a 4-iteration loop of 2 pushes, `mov eax,8`. There is no 4-value
-            // getter in this API at all: the 4-argument `(minX, maxX, minY, maxY)` min/max rect is
-            // **setter-only**, and returning it here was a shape that exists nowhere in the client.
-            // Order is `SetTexCoord`'s own usage string (`0x87c538`):
-            // `ULx, ULy, LLx, LLy, URx, URy, LRx, LRy`. Decision 1840.
-            //
-            // `GetTexCoord` has zero call sites in 1.12 FrameXML, so nothing on the chain could
-            // ever have caught this — only the binary could.
+            // Eight values in the order of `SetTexCoord`'s usage string (`0x87c538`): ULx, ULy,
+            // LLx, LLy, URx, URy, LRx, LRy. The four-edge form is setter-only.
             let corners = model
                 .region_data
                 .get(&rh)
                 .and_then(|d| d.tex_coords)
                 .map_or([[0.0, 0.0], [0.0, 1.0], [1.0, 0.0], [1.0, 1.0]], |tc| {
                     match tc {
-                        // Stored per corner in SCREEN order `[TL, TR, BR, BL]`; Lua wants
-                        // UL, LL, UR, LR.
+                        // Stored as TL, TR, BR, BL; Lua wants UL, LL, UR, LR.
                         crate::script::types::TexCoords::Corners(c) => [c[0], c[3], c[1], c[2]],
                         crate::script::types::TexCoords::Rect(_) => {
                             let [l, r, t, b] = tc.edges();
@@ -657,26 +460,21 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
 }
 
 impl crate::script::UiScript {
-    /// Install the host's texture-path oracle — the resolver behind the path form of
-    /// `SetTexture`'s **1 | nil** return ([`Model::texture_probe`]). The host hands in existence
-    /// over its real stores (patch chain + loose addon folder); a VM that never gets one keeps
-    /// answering nil for every path, the engine-less truth.
+    /// Install the host's texture-path check behind the path form of `SetTexture`'s 1-or-nil
+    /// answer; without one every path answers nil.
     pub fn set_texture_probe(&mut self, probe: crate::script::TextureProbe) {
         self.model_mut().texture_probe = Some(probe);
     }
 
-    /// Install the host's font-path oracle — the resolver behind `SetFont`'s **1 | nil** return
-    /// ([`Model::font_probe`], decision 2103). The host hands in load-ability over its real stores
-    /// (patch chain + the one AddOns folder); a VM that never gets one keeps answering 1 for every
-    /// non-empty path, because it has no font store a load could fail against.
+    /// Install the host's font-path check behind `SetFont`'s 1-or-nil answer; without one every
+    /// non-empty path answers 1.
     pub fn set_font_probe(&mut self, probe: crate::script::FontProbe) {
         self.model_mut().font_probe = Some(probe);
     }
 
-    /// Install the host's texture **texel-size** oracle — what lets a region with an authored size
-    /// of `0` on an axis take that span from its art, as the client's virtual size getters do
-    /// ([`Model::texture_size_probe`], decision 1349; `CSimpleTexture::GetWidth 0x770720`'s
-    /// native-texel fallback). A VM that never gets one leaves such a region exactly where it was.
+    /// Install the host's texel-size check, which lets an axis sized 0 take its span from the art
+    /// as `CSimpleTexture::GetWidth` (`0x770720`) falls back to the texels; without one such a
+    /// region stays where it was.
     pub fn set_texture_size_probe(&mut self, probe: crate::script::TextureSizeProbe) {
         self.model_mut().texture_size_probe = Some(probe);
     }
diff --git a/crates/benilla-ui/src/script/region/text.rs b/crates/benilla-ui/src/script/region/text.rs
index 17bbc240..0fea2769 100644
--- a/crates/benilla-ui/src/script/region/text.rs
+++ b/crates/benilla-ui/src/script/region/text.rs
@@ -1,84 +1,39 @@
-//! Region method-table cluster: **text** — what a `FontString` carries that other text-bearing
-//! widgets do not. Split out of `region.rs` at the 0716 file-size budget.
-//!
-//! **This file is now the FontString-only half.** The ten names it used to hand-write a second copy
-//! of — `Set/GetFontObject`, `Set/GetFont`, `Set/GetTextColor`, `Set/GetShadowColor`,
-//! `Set/GetShadowOffset` — are not FontString-specific at all: in the binary each is a thin
-//! type-guard shim tail-calling one shared implementation, so they come from
-//! [`crate::script::font_block`] via one `install` at the bottom of this file, exactly as the
-//! EditBox's table gets them. The justify law likewise lives once in [`crate::justify`].
-//!
-//! What legitimately stays here is the surface a FontString alone has: the string itself
-//! (`SetText`/`GetText`), the measured extents, `Set/GetJustifyH`/`V`, `SetNonSpaceWrap`/
-//! `CanNonSpaceWrap`, and `SetTextHeight`.
-//!
-//! The per-property override a region has over its inherited font object is unaffected — that is
-//! the severance mask (`FontExplicit`), which the shared block writes the same way this file did.
+//! The FontString-only methods: the string, its measured width, justification, non-space wrap and
+//! text height. The font block it shares with EditBox comes from [`crate::script::font_block`].
 
 use mlua::{Lua, Table, Value};
 
 use crate::justify;
 use crate::script::Model;
 
-/// Resolve `self` (a region wrapper) to its live [`RegionHandle`].
 use super::region_handle_of;
 
-/// Populate `m`'s text methods (see the module doc).
+/// Install the FontString methods into `m`.
 pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
     m.set(
         "SetText",
         lua.create_function(|lua, (this, text): (Table, Option<mlua::Value>)| {
-            // `text_arg`, not `Option<String>`: a Lua string is bytes and a sliced one need not be
-            // valid UTF-8 (decision 2138 — this raise took the whole handler down).
+            // `text_arg`, since a Lua string is bytes and a slice of one need not be valid UTF-8.
             let text = crate::script::binding_abi::text_arg(lua, text)?;
             let rh = region_handle_of(lua, &this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
             let data = model.region_data.entry(rh).or_default();
             data.text = text;
-            // Fresh text draws whole — an armed write-on gradient belongs to the old string.
+            // Fresh text draws whole: an armed write-on gradient belongs to the old string.
             data.alpha_gradient = None;
-            // SetText is the measure lane's canonical SILENT write (it must not touch the
-            // layout — the extent hasn't moved yet), so it names itself on the measure ledger.
+            // SetText must not touch the layout, since the extent has not moved yet; it names
+            // itself on the measure ledger.
             model.touch_measure(rh);
             Ok(())
         })?,
     )?;
 
-    // **No `SetFormattedText`.** A later-expansion name: absent from the client's 32-entry
-    // FontString map, from the stock 1.12 chain, and from both addon corpora (2142's census). The
-    // era spelling is `SetText(format(fmt, ...))`, and `format` here is already the
-    // positional-aware one ([`crate::strings`]), so `%N$s` behaves at the call site the same way
-    // it behaved inside this shim.
+    // No `SetFormattedText`: not a 1.12 verb; 1.12 writes `SetText(format(fmt, ...))`.
 
-    // GetText — **an EMPTY string comes back as `nil`, and that substitution is the getter's own**
-    // (`FontString:GetText 0x79d690`):
-    //
-    // ```text
-    // 79d72f  mov  eax,[eax+0xf0]        ; the text cell
-    // 79d735  test eax,eax
-    // 79d739  je   0x79d740              ; NULL      -> substitute
-    // 79d73b  cmp  byte ptr [eax],0x0    ; the FIRST-BYTE test
-    // 79d73e  jne  0x79d742              ; non-empty -> keep
-    // 79d740  xor  eax,eax               ; EMPTY     -> NULL
-    // 79d746  call 0x6f3890              ; pushstring; NULL -> pushnil
-    // ```
-    //
-    // So `FontString:GetText` **cannot return `""`**. Not the setter's doing: `SetText 0x771d80`
-    // never writes NULL to `+0xf0` on any leg — NULL and `""` share one leg that truncates the
-    // buffer in place (`0x771e7e mov byte ptr [eax],0x0`, the pointer surviving) — so the cell
-    // really does hold a non-NULL empty string and this getter is what collapses it.
-    //
-    // The law is **per binding, not per family**, and the two neighbours differ:
-    // `Button:GetText 0x780e10` carries the same substitution (`0x780ec5`, three nil conditions —
-    // see `button.rs`), while `EditBox:GetText 0x7985c0` carries **none** (`0x79867b` reads
-    // `[edit+0x32c]` straight through), which is what stock `MailFrame.lua`'s
-    // `GetText() == ""`/`strlen(GetText())` is written against. Do not hoist this.
-    //
-    // What it costs to get wrong (decision 2110): the stock world map blanks
-    // `WorldMapFrameAreaDescription` with `SetText("")` on every POI hover, and Cartographer 2.02
-    // reads `if WorldMapFrameAreaDescription:GetText() then` as "this POI has a status line" —
-    // answering `""` there put the zone's level range on the description's own line under a
-    // whitened label and left it on screen forever.
+    // GetText answers nil for "" (`0x79d690`, its first-byte test at `0x79d73b`), though `SetText`
+    // (`0x771d80`) keeps a non-NULL empty buffer (`0x771e7e`). The rule is per binding, not per
+    // family: `Button:GetText` (`0x780e10`, `0x780ec5`) does the same, `EditBox:GetText`
+    // (`0x7985c0`, `0x79867b`) does not, and stock `MailFrame.lua:521` compares that one with "".
     m.set(
         "GetText",
         lua.create_function(|lua, this: Table| {
@@ -98,41 +53,15 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetStringWidth (FontString): the host-measured text extent from the measure
-    //
-    // **There is no `GetStringHeight` beside it, and that asymmetry is the client's.** 1.12 has no
-    // such method on any table — byte-verified absent in every encoding, with `GetStringWidth`
-    // itself as the positive control — and Blizzard's own FrameXML calls it zero times. Ours was a
-    // byte-identical duplicate of `GetHeight`, which is what the reference uses for this
-    // (`0x7a2030` falls through to the same cached measurement), so it was pruned rather than
-    // reimplemented (1251).
-    // round-trip ([`super::UiScript::set_measured_text`]) — the client asks its font engine for the
-    // laid-out string's metrics exactly here, and the tooltip's auto-size sums
-    // these to fit its lines. `0` until the string has been measured (a frame's latency; converges).
-    // The stored measure only counts while its key matches the CURRENT text/font/wrap
-    // ([`RegionData::measure_key`]): after a SetText the old string's width is not this string's
-    // metric — serving it is how the whisper header's `GetWidth()` latched the edit-box insets on
-    // the previous header's width. A poll-until-nonzero caller (the chat header machine) now
-    // converges on the RIGHT measure instead of settling on a stale one.
-    // `GetWidth`/`GetHeight` are the neighbouring law and NOT this one ([`super::virtual_span`]):
-    // they take the authored size first and the measure only on an axis authored `0` — and on that
-    // axis the width they return is *this* number, because the reference reads both getters out of
-    // the one cell `[fs+0xfc]` (`0x772890` is `0x79e510`'s callee). So the two agree exactly where
-    // the reference makes them agree, and differ exactly where a width was declared.
-    // GetStringWidth is the **natural, unwrapped** extent — never the declared box, and never the
-    // wrapped one (the reference's getter re-measures the raw text with NO wrap constraint).
-    // Unlike `GetWidth` below it deliberately
-    // does NOT fall back to a declared `SetWidth`: that width is the very thing a caller
-    // asks this to be independent of. A kit that sizes a box from this number and then sets a width
-    // on the string — which is what the reference's own `PanelTemplates_TabResize` does — would
-    // otherwise read its own output back as its next input and never settle (decision 0997, the
-    // macro window's character tab changing width every frame). `0` until measured, as ever.
+    // GetStringWidth (`0x79e510`): the natural, unwrapped width of the current text, 0 until
+    // measured. Never the declared width, which `PanelTemplates_TabResize` sets from this; on an
+    // axis sized 0, `GetWidth` reads the same cell (`[fs+0xfc]`, `0x772890`). 1.12 has no
+    // `GetStringHeight`; `GetHeight` (`0x7a2030`) serves.
     fn natural_w(lua: &Lua, this: &Table) -> mlua::Result<f32> {
         let rh = region_handle_of(lua, this)?;
-        // Measure NOW if a host font engine is installed — the reference answers this getter from
-        // its font engine inline (`0x79e510` → `0x772890`), and a same-tick `SetText` →
-        // `GetStringWidth` is the corpus's own idiom (`Bagnon_Forever/database/ui.lua:58-59`).
-        // Without an engine this is a no-op and the number below stays 0 until the round-trip.
+        // Measure now when a host font engine is installed, as the reference measures inline, so
+        // `SetText` then `GetStringWidth` works in one tick; without one it is 0 until the host
+        // answers.
         crate::script::measure::ensure_measured(lua, rh);
         let model = lua.app_data_ref::<Model>().expect("model");
         let Some(d) = model.region_data.get(&rh) else {
@@ -154,10 +83,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         lua.create_function(|lua, this: Table| natural_w(lua, &this))?,
     )?;
 
-    // SetJustifyH("LEFT"|"CENTER"|"RIGHT") — a FontString's horizontal justification (XML
-    // `justifyH`). The token table, the whole-string match, the raise on a miss and the cross-axis
-    // clear are all [`crate::justify`]'s, shared with the `<Font>` object's identical pair
-    // so the two cannot drift apart again.
+    // SetJustifyH (XML `justifyH`): the parse, the raise on a miss and the cross-axis clear are
+    // `crate::justify`'s, shared with the `<Font>` object.
     m.set(
         "SetJustifyH",
         lua.create_function(|lua, (this, j): (Table, String)| {
@@ -170,20 +97,19 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             let d = model.region_data.entry(rh).or_default();
             match parsed {
                 justify::Set::To(jh) => d.justify.set_h(jh),
-                // A cross-axis token erases the axis. `GetJustifyH()` then answers "UNKNOWN"
-                // while the glyphs draw centred — `0x44d420`'s pre-set `1`.
+                // A cross-axis token erases the axis: `GetJustifyH()` answers "UNKNOWN" while the
+                // glyphs draw centred (`0x44d420` presets 1).
                 justify::Set::Clears => d.justify.clear_h(),
                 justify::Set::NoMatch => unreachable!("returned above"),
             }
-            // Severance is UNCONDITIONAL on a successful parse — the FontString's own setter
-            // `0x79e6b0` stores the per-axis mask `+0x124` at `0x79e780`, *before* the `je`, so
-            // the erasing path severs too. Only a failed parse escapes, and that raised already.
+            // Every successful parse overrides the font object, the erasing one too: `0x79e6b0`
+            // sets the per-axis mask (`+0x124`) at `0x79e780`, before the branch.
             d.font_explicit.justify_h = true;
             Ok(())
         })?,
     )?;
 
-    // SetJustifyV("TOP"|"MIDDLE"|"BOTTOM") — a FontString's vertical justification (XML `justifyV`).
+    // SetJustifyV (XML `justifyV`), as SetJustifyH.
     m.set(
         "SetJustifyV",
         lua.create_function(|lua, (this, j): (Table, String)| {
@@ -196,7 +122,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             let d = model.region_data.entry(rh).or_default();
             match parsed {
                 justify::Set::To(jv) => d.justify.set_v(jv),
-                // 13 corpus sites reach this arm: `SetJustifyV("CENTER")` meaning "middle".
+                // Addons reach this arm with `SetJustifyV("CENTER")`, meaning middle.
                 justify::Set::Clears => d.justify.clear_v(),
                 justify::Set::NoMatch => unreachable!("returned above"),
             }
@@ -205,13 +131,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetJustifyH()/GetJustifyV() → **1 string**. Real entries on the reference's FontString table
-    // (`0x79e5f0` / `0x79e7f0`, the FontString column of a two-column accessor table) that
-    // this side had simply never grown: a FontString could set its justification and not read it
-    // back, while the `<Font>` object — the same law, transcribed separately — could do both.
-    //
-    // An untouched FontString answers CENTER/MIDDLE, which is `RegionData`'s default *and* the
-    // client's ctor default `0x212` (`CENTER | MIDDLE | 0x200`) read through each axis mask.
+    // GetJustifyH/GetJustifyV (`0x79e5f0`/`0x79e7f0`): one string; CENTER and MIDDLE when
+    // untouched, the ctor's `0x212` read through each axis mask.
     fn justify_of(lua: &Lua, this: &Table) -> mlua::Result<justify::Justify> {
         let rh = region_handle_of(lua, this)?;
         let model = lua.app_data_ref::<Model>().expect("model");
@@ -230,14 +151,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         lua.create_function(|lua, this: Table| Ok(justify_of(lua, &this)?.name_v()))?,
     )?;
 
-    // SetNonSpaceWrap(enable) / CanNonSpaceWrap() — FontString only (`0x79e9f0` / `0x79ead0`).
-    //
-    // Two contract details, both easy to get wrong:
-    //  · the getter is **`CanNonSpaceWrap`**, not `GetNonSpaceWrap`, and it answers **`1` or nil**,
-    //    not a boolean — 1.12 predates that convention and an addon may compare against 1.
-    //  · a **no-argument call ENABLES** it (the default is on), rather than being a query.
-    //
-    // `oRA2/Leader/Item.lua:561` is `f.textname:SetNonSpaceWrap(false)`, reached by two addons.
+    // SetNonSpaceWrap/CanNonSpaceWrap (`0x79e9f0`/`0x79ead0`), FontString only: the getter
+    // answers 1 or nil, and a call with no argument enables.
     m.set(
         "SetNonSpaceWrap",
         lua.create_function(|lua, (this, enable): (Table, Value)| {
@@ -267,11 +182,9 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetTextHeight(height) — switch the FontString to the scaled-string regime (`0x771600` is the
-    // ONLY clearer of the one-to-one bit `0x200`; the literal size then flows through UNCAPPED,
-    // magnified from the raster). Stored
-    // as the distinct [`RegionData::text_height`] — the font object is untouched, so GetFont
-    // keeps reporting the face's own height like the real API.
+    // SetTextHeight: the scaled-string mode (`0x771600` alone clears the one-to-one bit `0x200`),
+    // the size magnified from the raster, uncapped. The font is untouched, so GetFont keeps the
+    // face's own height.
     m.set(
         "SetTextHeight",
         lua.create_function(|lua, (this, height): (Table, f32)| {
@@ -285,14 +198,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
 
     // ── the shared font block ───────────────────────────────────────────────────────────────
     //
-    // `SetFontObject · GetFontObject · SetFont · GetFont · Set/GetTextColor · Set/GetShadowColor ·
-    // Set/GetShadowOffset` are **not** FontString-specific. In the binary each is a thin type-guard
-    // shim that tail-calls one shared implementation (`0x79f210` SetFont, `0x79f3b0` GetFont, …),
-    // which is what [`super::super::font_block`] models — so a FontString and an EditBox are two
-    // entry points to one routine, not two routines that happen to agree.
-    //
-    // They lived here as a hand-written second copy because `region.rs` was over the file-size
-    // budget when the block was written; that split has since landed, and `font_block`'s own doc
-    // named this collapse as the follow-on. 226 lines of duplicate go with it.
+    // The font object, font, text colour and shadow getters and setters are type-guard shims over
+    // one implementation each (`0x79f210` SetFont, `0x79f3b0` GetFont), shared with EditBox.
     super::super::font_block::install(lua, m, region_handle_of, "FontString")
 }
diff --git a/crates/benilla-ui/src/script/region_map.rs b/crates/benilla-ui/src/script/region_map.rs
index cb3fa178..2fce44ce 100644
--- a/crates/benilla-ui/src/script/region_map.rs
+++ b/crates/benilla-ui/src/script/region_map.rs
@@ -1,60 +1,23 @@
-//! **The Region method map, reached by frames and regions alike** — the 19 names of the client's
-//! `0x87c9b8` table, each ONE callable that works on a Frame, a Texture or a FontString.
+//! The Region method map: the 19 names of the reference's `0x87c9b8` table, each one callable
+//! that works on a Frame, a Texture or a FontString.
 //!
-//! ## The fact this exists for (byte-verified in `WoW.exe`, decision 1501)
-//!
-//! 1.12.1's widget inheritance is not a Lua metatable chain: every class owns a flat
-//! `{name, lua_CFunction}` `.data` table, and its lookup probes that table and, on a miss,
-//! **tail-calls exactly one base class's lookup**:
+//! Each widget class owns a flat method table whose lookup, on a miss, tail-calls its base's:
 //!
 //! ```text
-//! Region   0x87c9b8 (19)  lookup 0x7a2ea0  → TERMINAL (root)
-//! ├─ Frame        0x878ec0 (68)  lookup 0x778590 → 0x7a2ea0
-//! ├─ Texture      0x87c128 (22)  lookup 0x79c620 → 0x7a2ea0
-//! └─ FontString   0x87c1d8 (32)  lookup 0x79ee20 → 0x7a2ea0
+//! Region      0x87c9b8 (19)  lookup 0x7a2ea0, the root
+//! Frame       0x878ec0 (68)  lookup 0x778590 → 0x7a2ea0
+//! Texture     0x87c128 (22)  lookup 0x79c620 → 0x7a2ea0
+//! FontString  0x87c1d8 (32)  lookup 0x79ee20 → 0x7a2ea0
 //! ```
 //!
-//! Parsing the two tables out of the image directly, **`Frame ∩ Region = ∅`**: not one of the 19
-//! is re-registered by Frame, so every Frame-derived class reaches the *same* function a Texture
-//! does. `WorldFrame.GetHeight` **is** `0x7a2030`, byte-for-byte the function
-//! `someTexture:GetHeight()` resolves to.
+//! Frame re-registers none of the 19, so `WorldFrame.GetHeight` is the function
+//! `someTexture:GetHeight()` resolves to (`0x7a2030`), and addons pull a method off one widget to
+//! apply to another. Each name is one function that resolves the receiver and hands the call to
+//! that kind's arm, as `0x7a2030` calls a vtable slot `CSimpleFontString` overrides; it goes into
+//! every table the chain reaches, so `WorldFrame.GetHeight == someTexture.GetHeight` holds.
 //!
-//! That is why this is not a curiosity. The idiom
-//!
-//! ```lua
-//! local _Height = WorldFrame.GetHeight     -- pull the method off ANY widget, once
-//! …
-//! local h = _Height(someTexture)           -- and apply it to ANY other
-//! ```
-//!
-//! is ordinary, correct 1.12 Lua. Quiver's `Api/Index.wow.lua` is built on it
-//! (`_Height = WorldFrame.GetHeight`, `_Width = WorldFrame.GetWidth`), and benilla raised
-//! `stale or invalid frame handle` on it, from inside the addon's `VARIABLES_LOADED` handler,
-//! **before** the handler's last line got to publish `Quiver.CastPetAction` — which is the whole
-//! of bug B267. One split method surface, one nil field, one dead addon.
-//!
-//! ## Why it is a bridge rather than a merge
-//!
-//! Our two implementations of each name are not redundant: a frame's size reads `layout_inputs`
-//! and divides its edges by `GetEffectiveScale`, a region's reads `region_data` and does not; a
-//! frame's `GetParent` can answer nil, a region's never can; a region's `GetPoint` resolves a
-//! `relativeTo` that may be a sibling *region*. Those differences are correct, and they are the
-//! same shape the reference has: `Region:GetHeight 0x7a2030` reads the receiver's layout
-//! sub-object and calls `[vtable+0x20]`, which `CSimpleFontString` **overrides**. One name, one
-//! entry point, per-kind behaviour behind it.
-//!
-//! So each of the 19 becomes one function that resolves the receiver *first* and then hands the
-//! whole argument list to the arm that owns that kind — and that single function is written into
-//! every method table the reference's chain would reach: the frame table, the region table, the
-//! Texture and FontString leaf tables, and the title region's narrower copy. Identity holds the
-//! way the binary's does — `WorldFrame.GetHeight == someTexture.GetHeight` is true here too.
-//!
-//! **Exactly the 19, and no more.** `Show`/`Hide`/`IsShown`/`IsVisible`/`SetAlpha`/`GetAlpha` look
-//! like they belong and do not: Frame and Texture each register their *own* — `SetAlpha`, for
-//! instance, is `0x774e90` on Frame and `0x79b580` on Texture — so `WorldFrame.Show(someTexture)`
-//! fails on the real client and must keep failing here. (`SetSize` used to sit outside the 19 for
-//! the opposite reason — in neither table because 1.12 has no such verb at all; decision 2142
-//! removed it rather than filing it.) The map is the unit.
+//! Exactly the 19: `Show`, `Hide`, `SetAlpha` and the like are per class (`SetAlpha` is `0x774e90`
+//! on Frame, `0x79b580` on Texture), so `WorldFrame.Show(someTexture)` fails, as in the reference.
 
 use std::collections::HashMap;
 use std::rc::Rc;
@@ -67,16 +30,15 @@ use super::{
     REG_TEXTURE_METHODS, REG_TITLE_METHODS,
 };
 
-/// Which side of the object model a wrapper's `T[0]` id names. Ids come from one counter
-/// ([`Model::next_id`]), so a region id can never be mistaken for a frame's.
+/// Which side of the object model a wrapper's `T[0]` id names; ids share one counter
+/// ([`Model::next_id`]), so a region id is never a frame's.
 #[derive(Clone, Copy, PartialEq, Eq, Hash)]
 pub(super) enum Side {
     Frame,
     Region,
 }
 
-/// `Err` when the table is not a widget wrapper at all (that error names the real problem and is
-/// worth keeping); `Ok(None)` when it *is* one whose widget no longer exists.
+/// `Err` for a table that is no widget wrapper; `Ok(None)` for a wrapper whose widget is gone.
 fn side_of(lua: &Lua, this: &Table) -> mlua::Result<Option<Side>> {
     let id = decode_id(this)?;
     let model = lua.app_data_ref::<Model>().expect("model app_data");
@@ -89,38 +51,19 @@ fn side_of(lua: &Lua, this: &Table) -> mlua::Result<Option<Side>> {
     })
 }
 
-/// One side's implementation of one of the 19, type-erased to the variadic ABI.
-///
-/// **The erasure is the point** (decision 2310). The dispatcher used to hold each side as an
-/// `mlua::Function` and reach it with `Function::call`, which re-enters Lua: every argument and
-/// every return value round-trips through mlua's ref thread twice, and the whole call is wrapped
-/// in a `lua_pcall`. Measured in a release build, a `MultiValue` relay costs **~420 ns** against
-/// ~40 ns for a scalar one, and a bridged `GetWidth()` measured **~750 ns against ~99 ns** for an
-/// unbridged frame method — a 7x tax on `SetPoint`, `GetWidth`, `ClearAllPoints`, `GetParent`, the
-/// verbs every UI calls most. An `Rc<dyn Fn>` is one ordinary Rust call.
-///
-/// The ABI is exactly what `Lua::create_function` builds internally for a typed body — see
-/// [`shared`], which is the only thing that makes one — so nothing about argument conversion,
-/// arity or coercion changes by going through it.
+/// One side's implementation of one of the 19, erased to the variadic ABI so dispatch is a plain
+/// Rust call: a `Function::call` would re-enter Lua through a `lua_pcall` on the hottest verbs.
+/// Built only by [`set_shared`], it converts arguments exactly as `create_function` does.
 pub(super) type Arm = Rc<dyn Fn(&Lua, MultiValue) -> mlua::Result<MultiValue>>;
 
-/// The arms the two method-table installers register, collected for [`install`].
-///
-/// It lives in the VM's `app_data` rather than being threaded through four `install` signatures:
-/// the installers are deep (`object::install` → `layout_methods::install`, `region::install` →
-/// `region::layout::install`) and the collection is install-time scaffolding, removed by
-/// [`install`] the moment it has been consumed.
+/// The arms the method-table installers register, held in `app_data` from [`open_arms`] until
+/// [`install`] consumes them.
 #[derive(Default)]
 pub(super) struct Arms(HashMap<(Side, &'static str), Arm>);
 
-/// Register one of the [`REGION_MAP_METHODS`] into its side's method table **and** record its arm.
-///
-/// Every one of the 38 (19 names x 2 sides) goes through here instead of
-/// `m.set(name, lua.create_function(body)?)?`, and [`install`] fails loudly if one did not — so a
-/// name added to the map without both arms cannot reach an addon as a half-registered method.
-/// The table entry it writes is transient: [`install`] replaces all 19 in every table with the
-/// shared dispatcher. It exists so the pre-bridge tables are still complete for anything that
-/// reads them in between (the leaf tables are *copied* out of the region table, mid-install).
+/// Register one of the [`REGION_MAP_METHODS`] into its side's table and record its arm; [`install`]
+/// fails if a name lacks either arm. The entry written here keeps the tables complete until
+/// [`install`] replaces it, since the leaf tables are copied from the region table meanwhile.
 pub(super) fn set_shared<A, R, F>(
     lua: &Lua,
     m: &Table,
@@ -147,17 +90,13 @@ where
     Ok(())
 }
 
-/// Open the arm collection. Called once, at the top of [`super::object::install`], before either
-/// method table is built; [`install`] closes it.
+/// Open the arm collection, before either method table is built.
 pub(super) fn open_arms(lua: &Lua) {
     lua.set_app_data(Arms::default());
 }
 
-/// Replace each of the 19 Region-map entries in every table the chain reaches with one shared
-/// function that dispatches on the receiver.
-///
-/// Runs **after** `region::install` (which is what builds the region, leaf and title tables) and
-/// after `install_frame_methods`; every table it names is already populated by then.
+/// Replace each of the 19 in every table the chain reaches with one function that dispatches on
+/// the receiver. Runs after `region::install` and `install_frame_methods` have built the tables.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let frame: Table = lua.named_registry_value(REG_FRAME_METHODS)?;
     let region: Table = lua.named_registry_value(REG_REGION_METHODS)?;
@@ -175,10 +114,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         .expect("Region-map arms — opened by `open_arms`");
 
     for name in REGION_MAP_METHODS {
-        // Both arms must exist. A missing one is not a thing to paper over with a one-sided shared
-        // function: the reference gives every widget all 19, so a gap on either side is a hole in
-        // the surface and says so here rather than at some addon's call site. (`GetNumPoints` was
-        // exactly that hole on the frame side until this module went in.)
+        // The reference gives every widget all 19, so a missing arm fails here, not at an addon.
         let arm = |side: Side, which: &str| -> mlua::Result<Arm> {
             arms.0.get(&(side, name)).cloned().ok_or_else(|| {
                 mlua::Error::runtime(format!(
@@ -189,11 +125,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         let on_frame = arm(Side::Frame, "FRAME")?;
         let on_region = arm(Side::Region, "REGION")?;
         let shared = lua.create_function(move |lua, args: MultiValue| {
-            // The receiver is argument 1 on every one of the 19 — a method call always passes it,
-            // and a pulled-off `Api._Height(x)` call passes it as the only argument. Borrowed
-            // rather than cloned: an mlua `Value::Table` clone registers a second reference in the
-            // ref thread, and this is the entry point for the verbs a map-note redraw calls
-            // thousands of times.
+            // The receiver is argument 1, borrowed: a `Value::Table` clone would register a second
+            // ref-thread reference on the hottest verbs.
             let side = {
                 let Some(Value::Table(this)) = args.iter().next() else {
                     return Err(mlua::Error::runtime(
@@ -203,12 +136,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 side_of(lua, this)?
             };
             match side {
-                // One ordinary Rust call, not a re-entry into Lua — see [`Arm`].
                 Some(Side::Frame) => on_frame(lua, args),
                 Some(Side::Region) => on_region(lua, args),
-                // A wrapper whose widget is gone. Deliberately ONE message for both sides — at
-                // this point the receiver's kind is exactly what could not be established, and
-                // each side's own wording claimed it.
+                // A wrapper whose widget is gone: one message, since its kind is unknown.
                 None => Err(mlua::Error::runtime("stale or invalid widget handle")),
             }
         })?;
diff --git a/crates/benilla-ui/src/script/reputation.rs b/crates/benilla-ui/src/script/reputation.rs
index 3b3650c6..6da59f20 100644
--- a/crates/benilla-ui/src/script/reputation.rs
+++ b/crates/benilla-ui/src/script/reputation.rs
@@ -1,74 +1,12 @@
-//! The reputation-pane bindings — the twelve `ReputationFrame` globals, driving a faithful port of
-//! the real 1.12 Reputation tab (reference FrameXML `ReputationFrame.{xml,lua}`).
-//!
-//! **The display law here is byte-pinned**, not inferred, across the client's whole reputation TU
-//! (`[0x4d5200, 0x4d6d80)`).
-//!
-//! Same split as [`super::skills`]: the app pushes a flat, unordered snapshot
-//! ([`UiScript::set_reputation`], each row already resolved from `Faction.dbc` + the player's live
-//! wire slot) and the ENGINE groups, sorts and folds. Every index the Lua API takes or returns is
-//! 1-based into the resulting visible row list.
-//!
-//! ## The tree: a header is a FLAG, the parent pointer is only the key
-//!
-//! Two separate facts, and conflating them is what this module was written wrong for once:
-//!
-//! - **A row is a header because the server said so** — flag bit `0x08`, tested as
-//!   `entry.isHeader = (flags >> 3) & 1` at `0x4d5acb`. Every emulator names that bit
-//!   `INVISIBLE_FORCED`; the binary disagrees, and the binary wins. The two readings select the
-//!   *same five factions* on 1.12's data (Alliance, Horde, Steamwheedle Cartel and the two
-//!   battleground blocs all carry it), which is exactly why the wrong one survives a screenshot.
-//! - **`Faction.dbc`'s `team` is the grouping key** — which header a row files under. An `INACTIVE`
-//!   row (flag `0x20`) is re-parented under the key `-1` instead of its own.
-//!
-//! A key whose header row is absent gets one **synthesized** (`0x4d5a70`) carrying that faction's
-//! real id, so `GetFactionInfo` names it the ordinary way. Two keys name no faction at all and take
-//! their text from global strings: `0` → `FACTION_OTHER`, `-1` → `FACTION_INACTIVE`.
-//!
-//! **A childless header is not drawn.** `GetNumFactions` (`ds:0xb73764`) is the total minus each
-//! collapsed child *and each empty header*, over an array re-sorted so `[0, visible)` is exactly the
-//! visible prefix — a flattened materialized view, not a skip.
-//!
-//! ## Ordering (the two real `qsort`s in `0x4d5c40`)
-//!
-//! Headers (`0x4d5dc0`): localized name ascending, with the two unresolved keys last and the
-//! **larger raw key first**, so `0` "Other" precedes `-1` "Inactive". Rows (`0x4d5e70`): within a
-//! header, the header row itself, then its children by localized name ascending.
-//!
-//! ## Collapse
-//!
-//! Client-side only — no opcode carries it, and it is persisted nowhere. The client's mask
-//! (`ds:0x84a0a4`) stores **expanded** bits, so `isCollapsed` is its negation. **Every rebuild
-//! resets it to all-expanded and then collapses the "Inactive" header**, which is why a fold here
-//! does not survive a push (the skills pane's `expandedMask = 0xFFFFFFFF`, one door along).
-//! `CollapseFactionHeader`/`ExpandFactionHeader` given `0` — or any non-header row — act on **every**
-//! header.
-//!
-//! ## Where the numbers come from — all of them, the app
-//!
-//! This crate is engine-free by design (decision 0068: roxmltree + mlua, no DBC, no wire), so every
-//! fidelity number arrives already computed, the same division [`super::skills`] draws.
-//! `crates/benilla-app/src/ui_reputation.rs` owns: the race/class slot pick that gates membership,
-//! adding `Faction.dbc`'s base to the wire standing (`wire + base` at `0x4d6370`), ranking the
-//! total, and the rank's absolute window (`.rdata 0x80928c` — the same nine edges
-//! `benilla_formats::reputation_rank` thresholds against).
-//!
-//! `standing_id` is `rank + 1`, 1..=8 (`FACTION_STANDING_LABEL<n>`, `FACTION_BAR_COLORS[1..8]`).
-//! `barMin`/`barMax`/`barValue` are **absolute**; the reference normalizes them itself (ref l.80-82).
-//! `GetWatchedFactionInfo`'s `reaction` is that **same** 1..8 scale (`0x4d68a0` is `0x4d658a`'s
-//! instruction), not the three-way unit-reaction one.
-//!
-//! ## The three sends, and which are optimistic
-//!
-//! `FactionToggleAtWar` (`0x4d6950` → `CMSG 0x125`) and `SetFactionInactive`/`SetFactionActive`
-//! (`0x4d69b0`/`0x4d6a00` → `CMSG 0x317`) write the local flag **first** and then send; the inactive
-//! pair also re-sorts locally, since the row changes header. `SetWatchedFactionIndex` (`0x4d6b60` →
-//! `CMSG 0x318`) is **not** optimistic: the watched slot is `PLAYER_FIELD_WATCHED_FACTION_INDEX`, a
-//! server field with no client mirror, so the bar moves only once the descriptor update lands.
-//!
-//! The at-war *toggle* enforces more than `canToggleAtWar` reports (`0x4d5fd0`): it also refuses
-//! while the player is in combat, and applies the −3000 floor only when moving toward peace. Only
-//! the reported predicate lives here; the combat half needs state this crate cannot see.
+//! The reputation pane's twelve `ReputationFrame` globals: the app pushes a flat snapshot, and
+//! the engine groups, sorts and folds it as the reference does (`[0x4d5200, 0x4d6d80)`); every
+//! index the API takes or returns is 1-based into the visible rows. A row is a header by flag
+//! `0x08` (`0x4d5acb`), which emulators name `INVISIBLE_FORCED`, and files under its
+//! `Faction.dbc` `team`, or under `-1` while inactive (flag `0x20`); key `0` reads `FACTION_OTHER`
+//! and `-1` `FACTION_INACTIVE`. A childless header is not a row (`GetNumFactions`, `0xb73764`).
+//! Headers sort by name with the synthetic keys last, `0` first (`0x4d5dc0`); children sort by
+//! name (`0x4d5e70`). The at-war toggle also refuses in combat and applies the -3000 floor only
+//! toward peace (`0x4d5fd0`); only `canToggleAtWar`, what the pane reports, lives here.
 
 use std::collections::HashMap;
 
@@ -78,55 +16,51 @@ use super::Model;
 
 /// The synthetic header key for factions the player moved to the inactive bucket.
 const KEY_INACTIVE: i64 = -1;
-/// The synthetic header key for factions with no parent — the "Other" bucket.
+/// The synthetic header key for factions with no parent, the "Other" bucket.
 const KEY_OTHER: i64 = 0;
 
-/// One reputation faction, app-resolved from `Faction.dbc` plus the player's live wire slot.
-/// EXACT shape the app feed (`crates/benilla-app/src/ui_reputation.rs`) is written against — do not
-/// rename.
+/// One reputation faction, resolved app-side from `Faction.dbc` and the player's wire slot.
 #[derive(Clone, Debug, PartialEq)]
 pub struct FactionEntry {
-    /// `Faction.dbc` id — the row's identity, and what a child's [`Self::parent_id`] names.
+    /// `Faction.dbc` id: the row's identity, and what a child's [`Self::parent_id`] names.
     pub faction_id: u32,
-    /// `reputationIndex` — the slot every send addresses and the selection is held by.
+    /// `reputationIndex`: the slot every send addresses and the selection is held by.
     pub rep_list_id: u32,
-    /// `Faction.dbc`'s `team`: the header key this row files under, `0` being the "Other" bucket.
-    /// Overridden to the "Inactive" bucket while [`Self::inactive`] is set.
+    /// `Faction.dbc`'s `team`: the header key this row files under, `0` the "Other" bucket, and
+    /// "Inactive" instead while [`Self::inactive`] is set.
     pub parent_id: u32,
-    /// The localized `Faction.dbc` name — the bar's left-hand label, or a header's text.
+    /// The localized name: the bar's label, or a header's text.
     pub name: String,
-    /// The localized `Faction.dbc` description — the detail popup's paragraph. Often empty.
+    /// The localized description, for the detail popup; often empty.
     pub description: String,
-    /// Total standing: the DBC race/class base plus the wire standing (the app adds them) —
-    /// `GetFactionInfo`'s `barValue`, absolute.
+    /// The DBC race/class base plus the wire standing (`0x4d6370`): `barValue`, absolute.
     pub standing: i32,
-    /// The 1-based standing rank, `1`..=`8` (`FACTION_STANDING_LABEL<n>`), app-ranked.
+    /// The rank, 1..=8 (`FACTION_STANDING_LABEL<n>`); `GetWatchedFactionInfo`'s `reaction` is this
+    /// same scale (`0x4d68a0`), not the unit-reaction one.
     pub standing_id: u8,
-    /// The rank's absolute floor and ceiling — `GetFactionInfo`'s `barMin`/`barMax`.
+    /// The rank's absolute bounds (`.rdata 0x80928c`), `barMin`/`barMax`; the stock pane
+    /// normalizes them itself (`ReputationFrame.lua:80-82`).
     pub bar_min: i32,
     pub bar_max: i32,
-    /// Flag `0x01` — whether the pane lists this faction at all. The **only** flag gating list
-    /// membership; off until the player first meets them.
+    /// Flag `0x01`, the only flag gating list membership: off until the player meets the faction.
     pub visible: bool,
-    /// Flag `0x08` — **this row is a header**, not "force-invisible" (see the module doc).
+    /// Flag `0x08`: this row is a header.
     pub is_header: bool,
-    /// Flag `0x02`. **Engine-mutable**: the toggle flips it here, optimistically, unacked.
+    /// Flag `0x02`; the toggle flips it here, unacked.
     pub at_war: bool,
-    /// Flag `0x10` clear **and** `standing >= -3000` — what `GetFactionInfo` reports. The toggle
-    /// itself is stricter; see the module doc.
+    /// Flag `0x10` clear and `standing >= -3000`: what `GetFactionInfo` reports.
     pub can_toggle_at_war: bool,
-    /// Flag `0x20`. **Engine-mutable**, same reason as [`Self::at_war`]; it re-parents the row under
-    /// the "Inactive" header rather than hiding it.
+    /// Flag `0x20`; flipped here like [`Self::at_war`], it moves the row under "Inactive" rather
+    /// than hiding it.
     pub inactive: bool,
 }
 
-/// A flat, unordered push of every reputation faction the player has a slot for — the ENGINE groups
-/// and sorts (see the module doc). EXACT shape the app feed is written against.
+/// A flat, unordered push of every faction the player has a slot for; the engine groups and sorts.
 #[derive(Clone, Debug, PartialEq, Default)]
 pub struct ReputationState {
     pub entries: Vec<FactionEntry>,
-    /// `PLAYER_FIELD_WATCHED_FACTION_INDEX` as a reputation-list slot, or `None` for none. A server
-    /// field with no client mirror, so it rides the push and is never written here.
+    /// `PLAYER_FIELD_WATCHED_FACTION_INDEX` as a slot, `None` for none: a server field with no
+    /// client mirror, never written here.
     pub watched: Option<u32>,
 }
 
@@ -137,25 +71,24 @@ pub enum ReputationSend {
     AtWar { rep_list_id: u32, at_war: bool },
     /// `CMSG_SET_FACTION_INACTIVE`.
     Inactive { rep_list_id: u32, inactive: bool },
-    /// `CMSG_SET_WATCHED_FACTION`; `None` is the wire's `-1`, NOT slot 0.
+    /// `CMSG_SET_WATCHED_FACTION`; `None` is the wire's `-1`, not slot 0.
     Watch(Option<u32>),
 }
 
-/// One header group: its key, its header text, and the positions of its children.
-/// Engine-internal; `pub(crate)` only because [`super::model::Model`] stores a `Vec` of them.
+/// One header group; `pub(crate)` only because [`super::model::Model`] stores them.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub(crate) struct FactionGroup {
-    /// The header key — a `Faction.dbc` id, or [`KEY_OTHER`] / [`KEY_INACTIVE`].
+    /// A `Faction.dbc` id, or [`KEY_OTHER`] or [`KEY_INACTIVE`].
     key: i64,
-    /// The header row's text. Empty for the two synthetic keys, whose text is resolved against the
-    /// VM's own global strings when read.
+    /// The header row's text; empty for the two synthetic keys, resolved against the VM's global
+    /// strings when read.
     name: String,
     /// Positions into [`ReputationState::entries`], sorted by [`collate`]d name.
     entries: Vec<usize>,
 }
 
-/// One visible row: a **header** (carrying its group index) or a faction **bar** (carrying its
-/// position into [`ReputationState::entries`]).
+/// One visible row: a header (its group index) or a faction bar (its position in
+/// [`ReputationState::entries`]).
 #[derive(Clone, Copy)]
 enum Row {
     Header(usize),
@@ -163,11 +96,9 @@ enum Row {
 }
 
 impl super::UiScript {
-    /// Push the player's reputation snapshot, rebuilding the display tree.
-    ///
-    /// A rebuild resets the folds to **all expanded** and then collapses the "Inactive" header — the
-    /// client's own behaviour, and the reason a fold does not survive a standing tick. The selection
-    /// is re-anchored by reputation-list slot, dropped only if that faction left the push.
+    /// Push the reputation snapshot and rebuild the tree: as in the reference, whose fold mask
+    /// (`0x84a0a4`) holds expanded bits, every header expands and then "Inactive" collapses, so a
+    /// fold does not survive a standing tick. The selection is kept by slot.
     pub fn set_reputation(&mut self, state: ReputationState) {
         let mut model = self.model_mut();
         let groups = build_groups(&state.entries);
@@ -182,13 +113,12 @@ impl super::UiScript {
         model.reputation = state;
     }
 
-    /// Drain the reputation verbs the pane queued since the last call — the app's outbound seam.
+    /// Drain the reputation verbs the pane queued since the last call.
     pub fn take_reputation_sends(&mut self) -> Vec<ReputationSend> {
         std::mem::take(&mut self.model_mut().reputation_sends)
     }
 }
 
-/// The header key a row files under: its parent, or the inactive bucket while that flag is set.
 fn header_key(e: &FactionEntry) -> i64 {
     if e.inactive {
         KEY_INACTIVE
@@ -197,8 +127,7 @@ fn header_key(e: &FactionEntry) -> i64 {
     }
 }
 
-/// The VM's own text for a synthetic header key, so a localized client gets its own word. Falls back
-/// to the enUS literals when the strings are absent (a bare test VM).
+/// The VM's text for a synthetic header key; the enUS literal in a bare test VM.
 fn synthetic_header(lua: &Lua, key: i64) -> String {
     let (global, fallback) = if key == KEY_INACTIVE {
         ("FACTION_INACTIVE", "Inactive")
@@ -210,16 +139,14 @@ fn synthetic_header(lua: &Lua, key: i64) -> String {
         .unwrap_or_else(|_| fallback.into())
 }
 
-/// Case-insensitive name ordering, raw bytes breaking a tie — the client's own `stricmp`.
-/// Per-module copy, as every seam module here keeps one.
+/// Case-insensitive name order, raw bytes breaking a tie: the client's `stricmp`.
 fn collate(a: &str, b: &str) -> std::cmp::Ordering {
     a.to_lowercase()
         .cmp(&b.to_lowercase())
         .then_with(|| a.as_bytes().cmp(b.as_bytes()))
 }
 
-/// Era booleans: `1` / `nil`, never `0` — `0` is truthy in Lua and every ref branch here is a bare
-/// `if ( atWarWith )`. Per-module copy, as every seam module here keeps one.
+/// `1` or nil, never `0`: `0` is truthy in Lua, and the stock pane tests `if ( atWarWith )`.
 fn era_bool(b: bool) -> Value {
     if b {
         Value::Integer(1)
@@ -228,15 +155,9 @@ fn era_bool(b: bool) -> Value {
     }
 }
 
-/// Build the header groups (the module doc's law).
-///
-/// Children are the **visible, non-header** rows, grouped by [`header_key`] and sorted by collated
-/// name. A group's text comes from the header ROW carrying that key when there is one, and is left
-/// empty for the two synthetic keys, resolved against the VM's global strings at read time.
-/// **A childless header is not a group at all** — the client's own count drops it.
-///
-/// Group order: named headers by collated name ascending, then the synthetic keys last with the
-/// larger raw key first, so "Other" (`0`) precedes "Inactive" (`-1`).
+/// Build the header groups: the visible non-header rows by [`header_key`], sorted by name. A group
+/// is named by its pushed header row (the reference synthesizes a missing one, `0x4d5a70`), or left
+/// empty for a synthetic key; a childless header is no group, as the client's count drops it.
 fn build_groups(entries: &[FactionEntry]) -> Vec<FactionGroup> {
     let name_of: HashMap<i64, &str> = entries
         .iter()
@@ -275,7 +196,6 @@ fn build_groups(entries: &[FactionEntry]) -> Vec<FactionGroup> {
     groups
 }
 
-/// The visible row list: every group's header, plus the children of the expanded ones.
 fn rows(model: &Model) -> Vec<Row> {
     let mut out = Vec::new();
     for (gi, g) in model.reputation_groups.iter().enumerate() {
@@ -293,7 +213,6 @@ fn num_rows(model: &Model) -> usize {
     rows(model).len()
 }
 
-/// The entry at a 1-based visible index, or `None` on a header or out of range.
 fn entry_at(model: &Model, index: usize) -> Option<&FactionEntry> {
     match rows(model).get(index.checked_sub(1)?)? {
         Row::Entry(ei) => model.reputation.entries.get(*ei),
@@ -301,7 +220,6 @@ fn entry_at(model: &Model, index: usize) -> Option<&FactionEntry> {
     }
 }
 
-/// The mutable twin of [`entry_at`] — the at-war/inactive flips write through it.
 fn entry_at_mut(model: &mut Model, index: usize) -> Option<&mut FactionEntry> {
     let row = *rows(model).get(index.checked_sub(1)?)?;
     match row {
@@ -310,9 +228,8 @@ fn entry_at_mut(model: &mut Model, index: usize) -> Option<&mut FactionEntry> {
     }
 }
 
-/// Fold or unfold by 1-based visible index. Index `0` — **or any index that is not a header** — acts
-/// on every header, which is the client's own fall-through (`0x4d6a50`/`0x4d6aa0`), not a tolerance
-/// invented here.
+/// Fold or unfold by 1-based visible index; `0` or any non-header index acts on every header, the
+/// reference's own fall-through (`0x4d6a50`, `0x4d6aa0`).
 fn set_collapsed(model: &mut Model, index: usize, collapse: bool) {
     let one = index
         .checked_sub(1)
@@ -334,10 +251,8 @@ fn set_collapsed(model: &mut Model, index: usize, collapse: bool) {
     }
 }
 
-/// `GetFactionInfo`'s out-of-range answer — **eleven values, not one nil** (`0x4d5fa0`'s miss path):
-/// `nil, nil, 1, 0, 0, 0, nil, nil, nil, nil, nil`. The `1` in the `standingID` slot is the
-/// client's, and it is load-bearing: the reference indexes `FACTION_BAR_COLORS[standingID]`
-/// unguarded, so a `nil` there would be an error rather than a blank row.
+/// `GetFactionInfo`'s miss (`0x4d5fa0`): eleven values, standingID 1, which the stock pane indexes
+/// `FACTION_BAR_COLORS` with unguarded.
 fn unknown_faction() -> MultiValue {
     let mut out = vec![Value::Nil, Value::Nil, Value::Integer(1)];
     out.extend(std::iter::repeat_n(Value::Integer(0), 3));
@@ -346,7 +261,6 @@ fn unknown_faction() -> MultiValue {
     MultiValue::from_vec(out)
 }
 
-/// Register the reputation-pane globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
@@ -359,9 +273,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetFactionInfo(index) → the ref's own eleven (ref-ReputationFrame.lua l.51):
-    // name, description, standingID, barMin, barMax, barValue, atWarWith, canToggleAtWar,
-    // isHeader, isCollapsed, isWatched. 1-based; ELEVEN wide on every path, a miss included.
+    // GetFactionInfo(index) → the stock pane's eleven (`ReputationFrame.lua:51`): name,
+    // description, standingID, barMin, barMax, barValue, atWarWith, canToggleAtWar, isHeader,
+    // isCollapsed, isWatched; eleven wide on every path, a miss included.
     g.set(
         "GetFactionInfo",
         lua.create_function(|lua, index: usize| {
@@ -415,8 +329,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSelectedFaction() → the selected row's VISIBLE index, or 0 for none (the ref compares
-    // against 0 outright). The selection is HELD by slot, so this re-finds the row each call.
+    // GetSelectedFaction() → the selected row's visible index, or 0 for none, as
+    // `ReputationFrame.lua:146` tests; re-found each call, since the selection is held by slot.
     g.set(
         "GetSelectedFaction",
         lua.create_function(|lua, ()| {
@@ -432,7 +346,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetSelectedFaction(index) — a VISIBLE index; a header or an out-of-range index clears it.
+    // SetSelectedFaction(index): a visible index; a header or an out-of-range index clears it.
     g.set(
         "SetSelectedFaction",
         lua.create_function(|lua, index: usize| {
@@ -442,16 +356,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CollapseFactionHeader(index) / ExpandFactionHeader(index) — a VISIBLE header index; `0` or a
-    // non-header row acts on EVERY header (the client's own fall-through).
-    // **Both fire `UPDATE_FACTION`, and that is the engine's own doing, not a convenience.**
-    // `CollapseFactionHeader 0x4d6a50` and `ExpandFactionHeader 0x4d6aa0` both reach `0x4d6400`,
-    // which tail-jumps to `0x4d5c40` — and `0x4d5dab`, inside that function, is one of the FOUR
-    // whole-image fire sites of `UPDATE_FACTION`. The stock pane has no other repaint path after a
-    // fold: its header `<OnClick>`
-    // calls the binding and nothing else (ReputationFrame.xml:9-15), and `ReputationFrame_OnEvent`
-    // repaints on `UPDATE_FACTION` alone. Our own retired file repainted itself, which is why this
-    // was invisible until the pane went stock (1875).
+    // CollapseFactionHeader(index) / ExpandFactionHeader(index): a visible header index. Both fire
+    // `UPDATE_FACTION`, as the reference's do (`0x4d6a50`, `0x4d6aa0` → `0x4d6400` → `0x4d5c40`,
+    // fire site `0x4d5dab`): the stock header's `OnClick` only calls the binding
+    // (`ReputationFrame.xml:9-15`), and the pane repaints on `UPDATE_FACTION` alone.
     g.set(
         "CollapseFactionHeader",
         lua.create_function(|lua, index: usize| {
@@ -475,8 +383,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // FactionToggleAtWar(index) — flip our own AT_WAR bit and queue the send, optimistically
-    // (`0x4d6950` writes locally first, and nothing acks it).
+    // FactionToggleAtWar(index): flip the at-war bit and queue the send; `0x4d6950` writes locally
+    // first, and nothing acks it.
     g.set(
         "FactionToggleAtWar",
         lua.create_function(|lua, index: usize| {
@@ -497,10 +405,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsFactionInactive(index) / SetFactionInactive(index) / SetFactionActive(index) — optimistic
-    // too, and the flip RE-PARENTS the row under the "Inactive" header, so the tree is rebuilt
-    // locally (`0x4d69b0`'s own `0x4d5c40` call). The folds are kept across that regroup: it is not
-    // a server rebuild, which is the thing that resets them.
+    // IsFactionInactive / SetFactionInactive / SetFactionActive (`0x4d69b0`, `0x4d6a00`): the flip
+    // is local first too, and moves the row under "Inactive", so the tree regroups here
+    // (`0x4d69b0` calls `0x4d5c40`); the folds survive, as only a server rebuild resets them.
     g.set(
         "IsFactionInactive",
         lua.create_function(|lua, index: usize| {
@@ -531,8 +438,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // GetWatchedFactionInfo() → name, reaction, min, max, value — or a single nil when nothing is
-    // watched (the ref's `if ( name )` gate). `reaction` is the SAME 1-based standingID scale.
+    // GetWatchedFactionInfo() → name, reaction, min, max, value; `reaction` is the standingID
+    // scale, and a nil name is `ReputationFrame.lua:167`'s nothing-watched gate.
     g.set(
         "GetWatchedFactionInfo",
         lua.create_function(|lua, ()| {
@@ -545,14 +452,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     .find(|e| e.rep_list_id == slot)
             });
             let Some(e) = watched else {
-                // FIVE values on the nothing-watched branch too — `0x4d6820` has four guards onto
-                // one label and no raise, so the shape is `nil, 0, 0, 0, 0` (decision 1845).
-                //
-                // Worth carrying with it: the `[0, 64)` bound is **not in the binding**.
-                // `0x4d5620` maps an out-of-range index to `0`, so the "nothing watched" sentinel
-                // passes the `< 0` and `> max` guards and dies at the NULL-DBC-row guard instead.
-                // A port that range-checks inside the binding implements a branch the reference
-                // does not have.
+                // Five values here too, `nil, 0, 0, 0, 0`: `0x4d6820`'s four guards share one exit
+                // and none raises. `0x4d5620` maps the out-of-range sentinel to 0, so it is refused
+                // at the null-row guard, not by a range check.
                 return Ok(MultiValue::from_vec(vec![
                     Value::Nil,
                     Value::Integer(0),
@@ -571,10 +473,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetWatchedFactionIndex(index) — a VISIBLE index, `0` meaning "stop watching". **Not
-    // optimistic** (`0x4d6b60`): the watched slot lives in PLAYER_FIELD_WATCHED_FACTION_INDEX with
-    // no client mirror, so the bar only moves once the descriptor update comes back. The `0` → `-1`
-    // translation happens at the app's wire edge, since slot 0 is a real faction.
+    // SetWatchedFactionIndex(index): a visible index, 0 to stop watching. Not local first
+    // (`0x4d6b60`): the watched slot is a server field with no client mirror, so the bar moves when
+    // the descriptor update returns. The app sends none as `-1`, since slot 0 is a real faction.
     g.set(
         "SetWatchedFactionIndex",
         lua.create_function(|lua, index: usize| {
@@ -613,9 +514,8 @@ mod tests {
         }
     }
 
-    /// A header row as the real wire delivers one: flag `0x08` set, and **not** `VISIBLE` — the
-    /// Steamwheedle Cartel's actual byte is `0x08` alone. A header is used for its name, never
-    /// drawn as a bar, so its own visibility is irrelevant and this fixture proves it.
+    /// A header row as the wire delivers one: flag `0x08` without `VISIBLE`, as the Steamwheedle
+    /// Cartel's byte is; a header is never drawn as a bar, so its own visibility is irrelevant.
     fn header(faction_id: u32, rep_list_id: u32, name: &str) -> FactionEntry {
         FactionEntry {
             visible: false,
@@ -624,10 +524,9 @@ mod tests {
         }
     }
 
-    /// Two named groups and the bucket, pushed OUT of order so the engine's own sort is what shows:
-    /// Alliance (469) over Stormwind + Ironforge, Steamwheedle (169) over Booty Bay, and two
-    /// parentless factions. Bloodsail Buccaneers is here because it really does hold slot **0** —
-    /// the value that must never be confused with "watch nothing".
+    /// Pushed out of order so the engine's sort shows: Alliance (469) over Stormwind and Ironforge,
+    /// Steamwheedle (169) over Booty Bay, and two parentless factions. Bloodsail Buccaneers holds
+    /// slot 0, which must never read as "watch nothing".
     fn state() -> ReputationState {
         ReputationState {
             entries: vec![
@@ -649,7 +548,6 @@ mod tests {
         s
     }
 
-    /// Every visible row's name, in order — the shape assertion the rest lean on.
     fn names(s: &UiScript) -> Vec<String> {
         s.eval::<Vec<String>>(
             "local t = {} for i = 1, GetNumFactions() do t[i] = (GetFactionInfo(i)) end return t",
@@ -657,12 +555,8 @@ mod tests {
         .expect("names")
     }
 
-    /// **The tree.** Headers are the rows the server FLAGGED as headers (`0x08`), grouped by the
-    /// children's `team`; a header is never also a bar; groups and children sort by name; and the
-    /// parentless bucket comes last under `FACTION_OTHER`.
-    ///
-    /// The fixture's headers are pushed WITHOUT the visible flag, which is what the real wire
-    /// sends — so this also pins that a header's own visibility does not gate its group.
+    /// The fixture's headers lack the visible flag, as on the wire, so this also pins that a
+    /// header's own visibility does not gate its group.
     #[test]
     fn the_header_flag_builds_the_tree_and_other_comes_last() {
         let s = seated();
@@ -692,8 +586,6 @@ mod tests {
         assert!(s.errors().is_empty(), "{:#?}", s.errors());
     }
 
-    /// **A childless header is not a row at all** — the client's own count drops it, so a header
-    /// whose children are all unmet must not leave an empty group behind.
     #[test]
     fn a_header_with_no_visible_children_is_dropped() {
         let mut s = UiScript::new().expect("VM");
@@ -714,9 +606,6 @@ mod tests {
         assert!(s.errors().is_empty(), "{:#?}", s.errors());
     }
 
-    /// **`GetFactionInfo`'s eleven, on a bar** — and eleven on a MISS too, which is the client's own
-    /// shape (`nil, nil, 1, 0, 0, 0, nil×5`). The `1` matters: the reference indexes
-    /// `FACTION_BAR_COLORS[standingID]` unguarded, so a nil there would raise rather than blank.
     #[test]
     fn a_bar_row_returns_the_references_eleven_and_so_does_a_miss() {
         let s = seated();
@@ -755,8 +644,6 @@ mod tests {
         assert!(s.errors().is_empty(), "{:#?}", s.errors());
     }
 
-    /// **Folding hides a group's children and shrinks the count**, and index `0` (or any non-header
-    /// row) acts on EVERY header — the client's own fall-through, not a tolerance invented here.
     #[test]
     fn folding_shrinks_the_list_and_index_zero_folds_everything() {
         let s = seated();
@@ -781,14 +668,14 @@ mod tests {
         s.run("ExpandFactionHeader(1)").unwrap();
         assert_eq!(names(&s).len(), 8, "expanded again");
 
-        // A BAR row is not a header, so it takes the same fall-through: index 2 is Ironforge.
+        // A bar row is not a header, so it takes the same fall-through: index 2 is Ironforge.
         s.run("CollapseFactionHeader(2)").unwrap();
         assert_eq!(
             names(&s),
             ["Alliance", "Steamwheedle Cartel", "Other"],
             "a non-header index folds every header"
         );
-        // …and so does index 0, and so does an index off the end of the list.
+        // So do index 0 and an index past the end.
         s.run("ExpandFactionHeader(0)").unwrap();
         assert_eq!(names(&s).len(), 8, "index 0 unfolds every header");
         s.run("CollapseFactionHeader(99)").unwrap();
@@ -796,8 +683,6 @@ mod tests {
         assert!(s.errors().is_empty(), "{:#?}", s.errors());
     }
 
-    /// **A push RESETS the folds** — all expanded, then "Inactive" collapsed. The client rebuilds
-    /// its expand mask on every server refresh, so a fold cannot survive a standing tick.
     #[test]
     fn a_push_resets_the_folds() {
         let mut s = seated();
@@ -810,8 +695,6 @@ mod tests {
         assert!(s.errors().is_empty(), "{:#?}", s.errors());
     }
 
-    /// **Inactive re-parents a row under the synthetic "Inactive" header, which starts collapsed.**
-    /// It does not hide the faction, and it does not touch the bucket the row came from.
     #[test]
     fn an_inactive_faction_moves_under_the_inactive_header() {
         let mut s = UiScript::new().expect("VM");
@@ -838,8 +721,6 @@ mod tests {
         assert!(s.errors().is_empty(), "{:#?}", s.errors());
     }
 
-    /// **Selection is held by reputation slot, not by row.** `GetSelectedFaction` answers `0` for
-    /// none — what the ref's own teardown compares against — and re-finds the row after a reorder.
     #[test]
     fn selection_follows_the_faction_not_the_row_index() {
         let mut s = seated();
@@ -851,7 +732,7 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetSelectedFaction()").unwrap(), 0);
         s.run("ExpandFactionHeader(1)").unwrap();
         assert_eq!(s.eval::<i64>("return GetSelectedFaction()").unwrap(), 3);
-        // Selecting a HEADER clears the selection rather than selecting the group.
+        // Selecting a header clears the selection rather than selecting the group.
         s.run("SetSelectedFaction(1)").unwrap();
         assert_eq!(s.eval::<i64>("return GetSelectedFaction()").unwrap(), 0);
         // A push that drops the faction entirely drops the selection with it.
@@ -863,9 +744,8 @@ mod tests {
         assert!(s.errors().is_empty(), "{:#?}", s.errors());
     }
 
-    /// **The two unacked toggles flip locally and queue their sends**; a peace-forced faction
-    /// refuses (the ref disables the box, but an addon can still call the global), and going
-    /// inactive re-groups on the spot without waiting for a server rebuild.
+    /// A peace-forced faction refuses: the stock pane disables the box, but an addon can still call
+    /// the global.
     #[test]
     fn the_war_and_inactive_toggles_flip_locally_and_queue_their_sends() {
         let mut s = seated();
@@ -910,10 +790,6 @@ mod tests {
         assert!(s.errors().is_empty(), "{:#?}", s.errors());
     }
 
-    /// **The watch bar's five, the `0` that means "nothing", and the fact that watching is NOT
-    /// optimistic.** The watched slot is a server field with no client mirror, so the pane shows a
-    /// new bar only after the descriptor update comes back as a fresh push — clicking alone must
-    /// change nothing on screen.
     #[test]
     fn watching_queues_a_send_but_does_not_move_the_bar_itself() {
         let mut s = seated();
@@ -933,7 +809,7 @@ mod tests {
         );
         assert_eq!(s.take_reputation_sends(), [ReputationSend::Watch(Some(19))]);
 
-        // The descriptor update arrives as the next push, and NOW the bar reads.
+        // The descriptor update arrives as the next push, and now the bar reads.
         let mut watched = state();
         watched.watched = Some(19);
         s.set_reputation(watched);
@@ -949,7 +825,7 @@ mod tests {
             "and the row reports itself watched"
         );
 
-        // Watching the row that IS slot 0, then clearing — the two must not collapse together.
+        // Watching slot 0, then clearing: the two must stay distinct.
         s.run("SetWatchedFactionIndex(8)").unwrap(); // Bloodsail Buccaneers, rep slot 0
         assert_eq!(s.take_reputation_sends(), [ReputationSend::Watch(Some(0))]);
         s.run("SetWatchedFactionIndex(0)").unwrap();
diff --git a/crates/benilla-ui/src/script/saved.rs b/crates/benilla-ui/src/script/saved.rs
index 7bdff5ab..f19409f4 100644
--- a/crates/benilla-ui/src/script/saved.rs
+++ b/crates/benilla-ui/src/script/saved.rs
@@ -1,31 +1,15 @@
-//! **Saved variables** — the Lua-level settings that survive a restart (decision 1128).
+//! Saved variables: the Lua settings that survive a restart. The reference saves FrameXML's
+//! `RegisterForSave` globals to one file read back by a line parser (`0x4913b0`, strings and
+//! numbers only), and an addon's `## SavedVariables` to its own file, executed as a chunk before
+//! `ADDON_LOADED` (`AddOn_Load` `0x51f240`). Deviation: the `RegisterForSave` file is executed as a
+//! chunk too, because the line parser cannot carry a table. The app owns the files (`ui_saved`).
 //!
-//! The reference client has *two* mechanisms for this, byte-verified:
-//!
-//! 1. **`RegisterForSave("NAME")`** — the Lua API FrameXML uses for its **38** globals
-//!    (`LOCK_ACTIONBAR`, `CHAT_LOCKED`, the eleven `COMBAT_TEXT_*`, …), written to the flat
-//!    `WTF/Account/<ACC>/SavedVariables.lua` and read back by a hand-rolled line parser
-//!    (`0x4913b0`, strings and numbers only) before `VARIABLES_LOADED` fires.
-//! 2. **`## SavedVariables` in a `.toc`** — one file per addon, *executed as a Lua chunk*
-//!    (`AddOn_Load 0x51f240` step 4, before `ADDON_LOADED` at step 6). Exactly one stock addon
-//!    uses it: `Blizzard_TrainerUI`, for the trainer window's three filter globals.
-//!
-//! benilla's ported UI is **one FrameXML tree, not addons** ([`crate::script`]'s manifest), so the
-//! two collapse into one here: the *declaration* API is (1) — the one our XML can call — and the
-//! *load* is (2)'s, a real chunk, because we already have a Lua VM and executing beats a line
-//! parser that cannot carry a table. One file, install-scoped (the `benilla/` folder is already
-//! per-install, so it IS the reference's account scope — decision 0954). The host side — path,
-//! load seam, write triggers — is the app's `ui_saved` module's.
-//!
-//! **Deliberate divergences from the reference's serializer**, all recorded in 1128: LF and no
-//! leading blank line (its `"\r\n"`-per-variable prefix means every file it writes *starts* with a
-//! blank line); Rust's shortest round-tripping float formatting instead of `%.16g` (which loses a
-//! double needing 17 digits); table entries emitted in a **sorted** order instead of raw `pairs`
-//! order, so a settings file diffs cleanly; `\r` escaped rather than written raw (raw CR inside a
-//! quoted string is what the reference emits and it does not re-parse); and a cycle is dropped
-//! rather than cut by writing a lightuserdata sentinel *into the caller's table*. What is faithful
-//! is the grammar — `NAME = value`, `nil` written out, bracketed keys, TAB indent, trailing comma —
-//! so a file is readable by, and swappable with, the reference's own.
+//! The grammar is the reference's: `NAME = value`, `nil` written out, bracketed keys, tab indent,
+//! trailing comma. Deviations, so a file diffs cleanly and reloads exactly: LF line ends with no
+//! leading blank line, the shortest round-tripping float where the reference's `%.16g` can lose a
+//! digit, entries sorted rather than in `pairs` order, `\r` escaped where the reference writes it
+//! raw and cannot read it back, and a cycle dropped where the reference writes a sentinel into the
+//! caller's table.
 
 use std::collections::HashSet;
 use std::ffi::c_void;
@@ -34,21 +18,14 @@ use mlua::{Lua, Table, Value};
 
 use super::Model;
 
-/// How deep a table may nest before the serializer gives up. The reference recurses uncapped (only
-/// its indent saturates at `0x80`); a settings file is not a place where 32 levels is anything but
-/// a bug, and a bound is what keeps a hostile or accidental structure from eating the stack.
+/// Deviation: nesting stops at 32 where the reference recurses uncapped (its indent saturates at
+/// `0x80`), so a hostile structure cannot exhaust the stack.
 const MAX_DEPTH: usize = 32;
 
 impl super::UiScript {
-    /// **Hold a saved-variables file that did not load** — the shutdown write must leave it alone.
-    ///
-    /// A file that fails as a chunk (a hand edit with a typo; a database past Lua's 262,143
-    /// constants per chunk) leaves its globals at the defaults the code assigned, and the write at
-    /// logout would then replace the player's whole file with those defaults. The reference does
-    /// exactly that — it discards an unparseable file and writes whole from live values
-    /// (`0x51f865`–`0x51f970`) — and both load sites here already promised otherwise ("left on
-    /// disk untouched"); this is what makes the promise true. The cost is this
-    /// session's changes to that one file, which is the trade the promise named.
+    /// Hold a saved-variables file that failed to load, so the shutdown write leaves it alone.
+    /// Deviation: the reference rewrites it from the live defaults (`0x51f865`–`0x51f970`), which
+    /// would cost the player the whole file for one typo in a hand edit.
     pub fn hold_saved_file(&self, path: &std::path::Path) {
         let mut model = self.model_mut();
         if !model.held_saved_files.iter().any(|p| p == path) {
@@ -56,38 +33,26 @@ impl super::UiScript {
         }
     }
 
-    /// Did this session's load fail on `path`? ([`Self::hold_saved_file`].)
+    /// Whether this session's load failed on `path`.
     pub fn saved_file_held(&self, path: &std::path::Path) -> bool {
         self.model_ref().held_saved_files.iter().any(|p| p == path)
     }
 
-    /// The registered names, in registration order — what the host writes out (the reference's
-    /// own emission order, and stable across runs because the load order is).
+    /// The registered names in registration order, the reference's own write order.
     pub fn saved_variable_names(&self) -> Vec<String> {
         self.model_mut().saved_names.clone()
     }
 
-    /// Serialize every registered global into the settings file's body, `NAME = value` per line.
-    ///
-    /// A name whose value cannot round-trip through a Lua chunk (a function, a widget reference,
-    /// any userdata — and `inf`/`NaN`, which are not Lua literals) is **skipped with a warning**
-    /// rather than written as something that would fail to load; the reference loses the same set,
-    /// silently. `nil` IS written (`NAME = nil`), which is how the reference records a toggle that
-    /// has never been touched.
-    ///
-    /// **Bytes, not text**: a Lua string is a byte string, and the file is executed as a chunk
-    /// that reads bytes (1193), so the writer is the one place that could change a value — and it
-    /// did. Values and keys went through `to_string_lossy`, so a string an addon cut mid-codepoint
-    /// or packed with high bytes (a compression library's output) came back from the next login as
-    /// U+FFFD, and two such keys could fold into one entry. The reference writes the bytes raw.
+    /// Serialize every registered global as `NAME = value` lines, in bytes, since a Lua string is
+    /// bytes and the reference writes them raw. A value with no literal (a function, userdata,
+    /// `inf`, `NaN`) is skipped with a warning where the reference drops it silently; `nil` is
+    /// written, as the reference records an untouched toggle.
     pub fn saved_variables_bytes(&self) -> Vec<u8> {
         self.saved_variables_bytes_for(&self.saved_variable_names())
     }
 
-    /// [`UiScript::saved_variables_bytes`] over an explicit name list — an addon's own
-    /// `## SavedVariables` set (1188 phase 3), which is declared in its manifest rather than
-    /// through `RegisterForSave`. Same grammar, same skip rules; only the source of the names
-    /// differs, which is exactly the difference between the reference's two mechanisms.
+    /// [`UiScript::saved_variables_bytes`] over an explicit name list, an addon's own
+    /// `## SavedVariables` set.
     pub fn saved_variables_bytes_for(&self, names: &[String]) -> Vec<u8> {
         let mut out = Vec::new();
         let mut unwritable = Vec::new();
@@ -120,12 +85,9 @@ impl super::UiScript {
     }
 }
 
-/// One Lua value as the text of a Lua expression, or `None` when it cannot be one.
-///
-/// `depth` is the indent level of the *contents* of a table at this position (so a top-level value
-/// starts at 1); `seen` carries the table identities on the current path — a repeat is a cycle and
-/// drops that entry. Note it is the *path*, not every table ever visited: a shared subtable is
-/// legitimately written twice (as it must be, since the file has no way to express aliasing).
+/// One Lua value as Lua expression text, or `None` when it has none. `depth` is the indent of a
+/// table's contents here (1 at top level); `seen` holds the tables on the current path, so a repeat
+/// is a cycle and drops, while a shared subtable is written each time it appears.
 fn serialize(v: &Value, depth: usize, seen: &mut HashSet<*const c_void>) -> Option<Vec<u8>> {
     match v {
         Value::Nil => Some(b"nil".to_vec()),
@@ -134,16 +96,14 @@ fn serialize(v: &Value, depth: usize, seen: &mut HashSet<*const c_void>) -> Opti
         Value::Number(n) => number(*n).map(String::into_bytes),
         Value::String(s) => Some(quote(&s.as_bytes())),
         Value::Table(t) => table(t, depth, seen),
-        // Functions, threads, userdata (every widget reference is one — a frame's Lua value is a
-        // table whose `[0]` is a lightuserdata handle, written at `0x701bd0`) cannot be written as
-        // a literal.
+        // Functions, threads and userdata have no literal; a frame's `[0]` handle is a
+        // lightuserdata (`0x701bd0`).
         _ => None,
     }
 }
 
-/// A Lua number literal. Integral values print without a fractional part (`1`, not `1.0` — the
-/// reference's `%.16g` does the same, and our XML compares these against integers); everything
-/// else takes Rust's shortest form that round-trips exactly. `inf`/`NaN` have no literal at all.
+/// A Lua number literal: integral values bare, as the reference's `%.16g` prints them, others in
+/// the shortest form that round-trips; `inf` and `NaN` have none.
 fn number(n: f64) -> Option<String> {
     if !n.is_finite() {
         return None;
@@ -154,10 +114,8 @@ fn number(n: f64) -> Option<String> {
     Some(format!("{n}"))
 }
 
-/// A quoted Lua string. The reference escapes exactly four characters (`\000`, `\n`, `\"`, `\\`)
-/// and writes CR and every high byte raw; we add `\r` (raw CR in a quoted string is not something
-/// its own loader could read back) and keep every other byte raw, so localized text stays legible
-/// and a byte string that is not UTF-8 round-trips unchanged.
+/// A quoted Lua string: the reference's four escapes (`\000`, `\n`, `\"`, `\\`) plus `\r`, every
+/// other byte raw.
 fn quote(s: &[u8]) -> Vec<u8> {
     let mut out = Vec::with_capacity(s.len() + 2);
     out.push(b'"');
@@ -175,20 +133,10 @@ fn quote(s: &[u8]) -> Vec<u8> {
     out
 }
 
-/// A table constructor: `{\n<tabs>[key] = value,\n<tabs-1>}`. Keys are always bracketed (the
-/// reference's shape — its writer emits `[key] = value` for **every** table shape and never a bare
-/// positional entry, byte-verified (no branch in `[0x704607, 0x704989)` writes a value without a
-/// bracketed key, for any table shape — and it sidesteps every reserved-word and non-identifier
-/// question); entries are **sorted**
-/// — integer keys ascending, then strings alphabetically — so the file is stable across runs
-/// instead of following Lua's hash order.
-///
-/// **A list written this way still reloads as a list**, and that is a property of the *parser*, not
-/// of this emitter: 1.12's `recfield` gives a `[expr] = v` field neither size hint, so the table is
-/// born on the dummy node, the first store rehashes, and the dense integer keys land in an array
-/// part that `next` walks ascending. Our vendored parser was restored to that placement in decision
-/// 2111 — before it, this exact file shape came back keyed 1..n in the *hash* part and Bagnon's
-/// keyring drew first.
+/// A table constructor, `{\n<tabs>[key] = value,\n<tabs-1>}`: every key bracketed, as the
+/// reference writes for every table shape (`[0x704607, 0x704989)`), integer keys ascending, then
+/// strings. It reloads a list as a list through the 1.12 parser: `recfield` gives a `[k] = v` field
+/// no size hint, so dense integer keys land in the array part, which `next` walks in order.
 fn table(t: &Table, depth: usize, seen: &mut HashSet<*const c_void>) -> Option<Vec<u8>> {
     if depth > MAX_DEPTH || !seen.insert(t.to_pointer()) {
         return None;
@@ -210,7 +158,7 @@ fn table(t: &Table, depth: usize, seen: &mut HashSet<*const c_void>) -> Option<V
     }
     seen.remove(&t.to_pointer());
     ints.sort_by_key(|(k, _)| *k);
-    // Byte order — the same order `str`'s `Ord` gave every UTF-8 key before.
+    // Byte order, the same as `str` order for UTF-8 keys.
     strs.sort_by(|a, b| a.0.cmp(&b.0));
 
     let indent = "\t".repeat(depth);
@@ -235,14 +183,8 @@ fn table(t: &Table, depth: usize, seen: &mut HashSet<*const c_void>) -> Option<V
     Some(out)
 }
 
-/// Register the `RegisterForSave` global.
-///
-/// Divergence, disclosed: the reference's binding is **taint-gated to Blizzard code**
-/// (`0x4884e0`), because a third-party addon writing into the shared account file would be a
-/// security surface. benilla has no taint model yet and loads no third-party addons, so the gate
-/// has nothing to gate; when addon loading lands, this is one of the bindings that needs it (and
-/// an addon's own `## SavedVariables` file is the mechanism it should use instead — the `.toc`
-/// directive [`crate::toc::Toc::list`] already parses).
+/// Register `RegisterForSave`, with no taint gate: the reference refuses it outside Blizzard code
+/// (`0x4884e0`), and benilla has no taint model.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     lua.globals().set(
         "RegisterForSave",
@@ -260,17 +202,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 mod tests {
     use crate::script::UiScript;
 
-    /// **A saved LIST comes back a list** — Bagnon's inventory grid, at 1:1 scale, and the
-    /// round-trip half of decision 2111 (the dialect half is `lua50`'s own tests).
-    ///
-    /// `Bagnon_Core` keeps its frame's bag order in a saved table, sorts it so the keyring
-    /// (`KEYRING_CONTAINER` = -2) lands last, and then lays the grid out by walking it with
-    /// **`pairs`** (`BagnonFrame_Generate`'s `for _, bagID in pairs(BagnonSets[frameName].bags)`).
-    /// Session one has no file: the table is the literal `{-2,0,1,2,3,4}`, an array table, and
-    /// `pairs` walks it 1..6 — keyring last, as the reference shows it. Session two reads the
-    /// serializer's `[k] = v` form back, and before 2111 that came back keyed 1..6 in the **hash**
-    /// part, walked in slot order, with key 6 — the keyring — **first**, ahead of the backpack.
-    /// That is the director's report; the writer is unchanged and the parser is what was wrong.
+    /// Bagnon's shape: a saved bag list sorted with the keyring (-2) last, laid out by `pairs`.
     #[test]
     fn a_saved_list_still_walks_in_index_order_after_a_restart() {
         let s = UiScript::new().unwrap();
@@ -305,8 +237,6 @@ mod tests {
         );
     }
 
-    /// The round trip that is the whole point: what the writer emits, the loader's own chunk
-    /// restores — through a fresh VM, exactly as a restart does.
     #[test]
     fn the_declared_globals_round_trip_through_a_fresh_vm() {
         let mut s = UiScript::new().unwrap();
@@ -342,8 +272,6 @@ mod tests {
         );
         let bytes = s.saved_variables_bytes();
         let text = String::from_utf8(bytes).expect("every value here is UTF-8");
-        // The grammar: one statement per line, `nil` written out, integral numbers bare, keys
-        // bracketed and SORTED (integers ascending, then strings), tab-indented, trailing comma.
         assert_eq!(
             text,
             "TRAINER_FILTER_AVAILABLE = 1\n\
@@ -362,7 +290,6 @@ mod tests {
         );
         assert!(s.take_warnings().is_empty(), "nothing was unserializable");
 
-        // A fresh VM (the restart), the file's chunk, and every value is back.
         let fresh = UiScript::new().unwrap();
         fresh.run(&text).unwrap();
         assert_eq!(
@@ -388,8 +315,6 @@ mod tests {
             .unwrap());
     }
 
-    /// A value with no Lua literal is skipped and named, never written as something that would
-    /// break the next load — the one place we improve on the reference, which loses these silently.
     #[test]
     fn unserializable_values_are_skipped_with_one_warning() {
         let mut s = UiScript::new().unwrap();
@@ -413,14 +338,9 @@ mod tests {
         let warns = s.take_warnings();
         assert_eq!(warns.len(), 1, "one line, not one per name: {warns:?}");
         assert!(warns[0].contains("A_FUNCTION") && warns[0].contains("NOT_A_NUMBER"));
-        // And what it wrote is loadable.
         UiScript::new().unwrap().run_chunk(&text).unwrap();
     }
 
-    /// **A byte string comes back as the same bytes.** A Lua string is bytes; an addon that cuts
-    /// a UTF-8 name mid-codepoint with `string.sub`, or packs data with `string.char(≥128)` (a
-    /// compression library's output), stores something that is not UTF-8. The writer used to
-    /// decode lossily, so the next login read U+FFFD — and two such keys folded into one entry.
     #[test]
     fn a_byte_string_that_is_not_utf8_round_trips_unchanged() {
         let s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/screenshot.rs b/crates/benilla-ui/src/script/screenshot.rs
index 7a69c3ee..091d0330 100644
--- a/crates/benilla-ui/src/script/screenshot.rs
+++ b/crates/benilla-ui/src/script/screenshot.rs
@@ -1,25 +1,13 @@
-//! **`Screenshot()`** — the engine verb behind the print-screen key (decision 1487).
-//!
-//! One global and one counter. The reference's binding is `SCREENSHOT` → `TakeScreenshot()`
-//! (FrameXML `Bindings.xml`), whose body hides the status text and then calls this engine
-//! function; the engine answers later with `SCREENSHOT_SUCCEEDED` or `SCREENSHOT_FAILED`, which
-//! is what puts "Screen Captured" on screen. **The answer is an EVENT, never a return value** —
-//! and that is the whole mechanism that keeps the message out of the file it announces: the
-//! capture is already taken by the time anything can say so.
-//!
-//! A **count**, like [`super::client`]'s `RequestTimePlayed` and `ConfirmBinder`: the request
-//! carries no payload (the app owns the window, the folder and the clock), so two calls in a frame
-//! are two captures rather than one collapsed intent. The app drains it in
-//! [`crate::script::UiScript::take_screenshot_asks`].
+//! `Screenshot()`, the engine verb behind the print-screen key: the `SCREENSHOT` binding calls
+//! `TakeScreenshot()` (`WorldFrame.lua:46`), which hides the status text and calls this. It
+//! returns nothing; the outcome arrives later as `SCREENSHOT_SUCCEEDED` or `SCREENSHOT_FAILED`,
+//! so the "Screen Captured" message never lands in the capture.
 
 use mlua::Lua;
 
 use super::Model;
 
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
-    // `Screenshot()` — take one. Returns nothing: the reference's does not either, because the
-    // capture completes after the frame that asked for it and the outcome arrives as
-    // SCREENSHOT_SUCCEEDED / SCREENSHOT_FAILED.
     lua.globals().set(
         "Screenshot",
         lua.create_function(|lua, ()| {
@@ -33,8 +21,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 }
 
 impl super::UiScript {
-    /// Drain the `Screenshot()` calls queued since the last call — each one is one capture.
-    /// [`super::UiScript::take_played_time_asks`]'s shape, for the same reason.
+    /// `Screenshot()` calls since the last drain, each one capture.
     pub fn take_screenshot_asks(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().screenshot_asks)
     }
diff --git a/crates/benilla-ui/src/script/scrollframe.rs b/crates/benilla-ui/src/script/scrollframe.rs
index 35d10f85..c4470781 100644
--- a/crates/benilla-ui/src/script/scrollframe.rs
+++ b/crates/benilla-ui/src/script/scrollframe.rs
@@ -1,32 +1,9 @@
-//! The `ScrollFrame` method surface (`CSimpleScrollFrame`) — the ScrollFrame mechanism (decision
-//! 0112, the engine's last structural gap): `SetScrollChild`/`GetScrollChild`, the two scroll
-//! offsets (`Set`/`GetVerticalScroll`, `Set`/`GetHorizontalScroll`), and the live ranges
-//! (`Get{Vertical,Horizontal}ScrollRange`/`UpdateScrollChildRect`). The offset setters and the
-//! ranges are byte-pinned (decisions 1338, 2017): `0x786db0` stores the offset VERBATIM — the
-//! engine never clamps it — and `0x786e30` measures both ranges off the scroll child's subtree. The
-//! rest is spec-faithful to the documented widget contract (the Era `ScrollFrameTemplate` Lua
-//! drives its scrollbar off exactly these), same posture as StatusBar's fill.
-//!
-//! **The two axes are one mechanism, not a mechanism and a special case.** The reference's nine
-//! ScrollFrame bindings are four symmetric pairs plus `UpdateScrollChildRect`, and the C++ under
-//! them is literally cloned: `0x786d30` (horizontal) is the byte-clone of `0x786db0` (vertical)
-//! against `[+0x324]`/`[+0x32c]` instead of `[+0x328]`/`[+0x334]`, and one `0x786e30` computes
-//! both ranges out of one subtree union. This module
-//! is written that way too — one helper per concept, taken on the axis asked for. That the
-//! horizontal half went unwritten until the corpus asked for it (`aux-addon` reads and writes both
-//! axes in one function) is why this doc used to say horizontal scroll "is out of scope: no 1.12
-//! template drives it" — true of the stock templates, and never true of the addons.
-//!
-//! The actual geometry — the scroll child's anchors pinned to the frame + the scroll offsets, and
-//! the clip every descendant of the child draws/hits within — lives in [`super::mod@super`]'s
-//! `resolve`/`extract`/`hit_test` (the layout-graph override + the ancestor-walk clip helper); this
-//! module is the thin Lua binding over the per-frame [`ScrollFrameState`], plus the three script
-//! hooks (`OnVerticalScroll`/`OnHorizontalScroll`/`OnScrollRangeChanged`) a scrollbar's
-//! `OnValueChanged`/`OnLoad` wires to.
-//!
-//! The methods live in their own registry table, consulted by the frame `__index` dispatcher only
-//! for ScrollFrame frames — so duck-typing addons (`if frame.SetScrollChild then …`) see `nil` on
-//! every other kind, exactly as against the client's per-class method sets.
+//! The `ScrollFrame` methods (`CSimpleScrollFrame`): the scroll child, the two offsets, the two
+//! ranges and `UpdateScrollChildRect`, over [`ScrollFrameState`]; the layout's `resolve`,
+//! `extract` and `hit_test` place and clip the child. The axes are one mechanism: `0x786d30`
+//! (horizontal) is a byte-clone of `0x786db0` (vertical) on `[+0x324]`/`[+0x32c]` for
+//! `[+0x328]`/`[+0x334]`, and `0x786e30` measures both ranges in one pass. The methods sit in
+//! their own table, so on every other frame kind `SetScrollChild` is nil, as in the client.
 
 use mlua::{Lua, Table, Value};
 
@@ -34,12 +11,11 @@ use super::object::{decode_id, frame_handle_of, frame_wrapper};
 use super::{event, Model};
 use crate::widget::{FrameHandle, KindState, ScrollFrameState};
 
-/// Registry key of the ScrollFrame method table (the MAXCSTACK discipline: Lua-side root, named key).
+/// Registry key of the ScrollFrame method table.
 pub(super) const REG_SCROLLFRAME_METHODS: &str = "__benilla_scrollframe_methods";
 
-/// Run `f` over a frame's ScrollFrame state under one short write borrow. Errors if `this` is not a
-/// live ScrollFrame (unreachable through the kind dispatcher, but the method table is a plain Lua
-/// value — a caller could fish it out and misapply it).
+/// Run `f` over a frame's ScrollFrame state; errors when `this` is not a live ScrollFrame, which a
+/// script reaches only by applying a method taken off the table to another frame.
 fn with_scroll<T>(
     lua: &Lua,
     this: &Table,
@@ -57,47 +33,21 @@ fn with_scroll<T>(
     }
 }
 
-/// Which axis a scroll offset, span or range is taken on.
-///
-/// One type rather than two code paths, because the reference computes both ranges in ONE pass
-/// over ONE subtree union (`0x786e30`: `[+0x31c] = max(0, maxRIGHT − minLEFT − width) / scale`,
-/// `[+0x320] = max(0, maxTOP − minBOTTOM − height) / scale`) — the axes differ only in which pair
-/// of edges the union tracks and which frame dimension is subtracted.
+/// The axis of an offset or a range. `0x786e30` computes both ranges in one pass over one subtree
+/// union: `[+0x31c] = max(0, maxRIGHT − minLEFT − width) / scale`, and `[+0x320]` the same with
+/// top, bottom and height.
 #[derive(Clone, Copy, PartialEq, Eq)]
 enum Axis {
-    /// `maxRIGHT − minLEFT` against the frame's width — `GetHorizontalScrollRange`, `[+0x31c]`.
     Horizontal,
-    /// `maxTOP − minBOTTOM` against the frame's height — `GetVerticalScrollRange`, `[+0x320]`.
     Vertical,
 }
 
-/// `Get{Vertical,Horizontal}ScrollRange()`'s live computation: `max(0, contentExtent − frameExtent)`
-/// from the **resolved** rects — `0.0` when the frame is unresolved or there is no child. Never
-/// cached: the scroll offset always clamps against the current layout, not a stale snapshot.
-///
-/// **The content extent is the scroll child's whole SUBTREE, not the child frame's own height**
-/// (decision 1338 corrects what 0112 shipped). `0x786e30` seeds a bounding box
-/// `{FLT_MAX, FLT_MAX, 0, 0}` and calls the **recursive** `0x786f80(scrollChild, &bbox)`, which
-/// unions the frame's REGION list (head `+0x1b4`, link `+0x1b8`, guard `[entry+8]+0xc4`) and
-/// re-enters itself for every CHILD FRAME (head `+0x2fc`, link `+0x300`, guard `[entry+8]+0xd0`);
-/// the range stored at `[+0x31c]` is `max(0, bboxExtent − viewportExtent)`.
-///
-/// The distinction is not academic: stock `ItemTextPageScrollChild` is declared **10×10**
-/// (`ItemTextFrame.xml` l.198) around a 270×304 SimpleHTML whose blocks extend well past it.
-/// Measured as the child's own height the range is zero and a book cannot be scrolled at all;
-/// measured as the subtree box it tracks the rendered text. Every ScrollFrame whose child is sized
-/// directly — the guild-info EditBox, the options panes, every faux list — is unchanged, because
-/// there its own rect already IS its subtree.
-///
-/// In **LOCAL units**, each extent divided by the owning frame's effective scale — i.e. exactly
-/// `child:GetHeight() - self:GetHeight()`, the widget contract this method states. The resolved
-/// rects are screen px, and the scroll offset is NOT: `SetVerticalScroll` becomes the scroll
-/// child's anchor y-offset, which the solver multiplies by that child's scale (`resolve`'s
-/// override; `anchor_resolve_y`). Reporting a screen-px range against a local-unit offset makes
-/// every SCALED ScrollFrame under-scroll by exactly its scale — the bar's max is the range, so it
-/// stops short of the end and the tail of the content is unreachable. Invisible at scale 1.0,
-/// which is every 1.12-native window; the era-scaled options window (ERA_WINDOW_SCALE 0.78) is the
-/// first real-scroll customer that isn't, and it lost 22% of its travel.
+/// `Get{Vertical,Horizontal}ScrollRange()`: `max(0, content − frame)` from the resolved rects,
+/// computed on every call, where the reference caches both (`[+0x31c]`, `[+0x320]`) and recomputes
+/// them only once marked dirty. The content is the scroll child's whole subtree, not its own rect
+/// (`0x786e30` calls the recursive `0x786f80`): stock `ItemTextPageScrollChild` is 10×10 around a
+/// 270×304 SimpleHTML (`ItemTextFrame.xml:198`). Each extent is divided by its frame's effective
+/// scale, since the offset is in local units; a range in screen px under-scrolls a scaled frame.
 fn scroll_range(model: &Model, h: FrameHandle, axis: Axis) -> f32 {
     let child = match model.arena.frame(h).map(|f| &f.kind_state) {
         Some(KindState::Scroll(s)) => s.child,
@@ -127,13 +77,9 @@ fn scroll_range(model: &Model, h: FrameHandle, axis: Axis) -> f32 {
     ((far - near) / scale_of(child) - viewport).max(0.0)
 }
 
-/// The span of `f`'s subtree along `axis`, in SCREEN px, as `(far, near)` — `(top, bottom)`
-/// vertically, `(right, left)` horizontally — its own resolved rect unioned with every VISIBLE
-/// descendant region and child frame, recursively (`0x786f80`). `None` when nothing in the subtree
-/// resolved.
-///
-/// Visibility is the client's own guard on both lists: a hidden block contributes no scroll range,
-/// which is what stops a window's parked art from inventing travel nobody can use.
+/// The span of `f`'s subtree along `axis` in screen px, as `(far, near)`: its own rect unioned with
+/// its shown regions and visible child frames, recursively (`0x786f80`). Hidden parts add no range:
+/// the client guards both lists on visibility.
 fn subtree_span(model: &Model, f: FrameHandle, axis: Axis) -> Option<(f32, f32)> {
     let edges = |r: &crate::layout::Rect| match axis {
         Axis::Horizontal => (r.right, r.left),
@@ -193,14 +139,12 @@ fn subtree_font_strings(model: &Model, f: FrameHandle) -> Vec<crate::widget::Reg
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let m = lua.create_table()?;
 
-    // SetScrollChild(frame|name|nil) — a wrapper table or a name string resolves like every other
-    // frame-target arg (SetParent, SetPoint's relativeTo); nil (or an unresolvable target) clears.
+    // SetScrollChild(frame | name | nil): nil or an unresolvable target clears.
     m.set(
         "SetScrollChild",
         lua.create_function(|lua, (this, target): (Table, Value)| {
-            // `_G[name]` before the guard, no `$parent` — `0x790fa0`'s string arm calls `0x76c760`
-            // directly, the same narrow-Frame-tag resolver `SetParent` uses
-            // (`object::NamedTarget`).
+            // A name is `_G[name]` with no `$parent`: `0x790fa0` calls `SetParent`'s resolver
+            // `0x76c760`.
             let named = match &target {
                 Value::String(s) => s
                     .to_str()
@@ -227,8 +171,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 changed
             })?;
             if changed {
-                // The child override is part of the resolve's read set (decision 0112's local
-                // anchor map — a fingerprint input), so a real re-target dirties tier 1.
+                // The child is an input of the layout resolve, so a real change dirties it.
                 lua.app_data_mut::<Model>().expect("model").touch_layout();
             }
             Ok(())
@@ -251,20 +194,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetVerticalScroll(px) — stores the offset VERBATIM and, only when it actually changed,
-    // re-lays the child out and fires OnVerticalScroll(self, offset) — the scrollbar's
-    // OnValueChanged wiring's other half.
-    //
-    // **No clamp** (decision 2017). The reference's `0x786db0` compares the new value against the
-    // OLD one alone (an epsilon change-gate: unchanged → nothing happens, not even the script),
-    // writes it to `[+0x328]`, re-anchors the scroll child off it (`0x787100` →
-    // `SetPoint(child, self, hScroll, vScroll)`) and fires the handler. `[+0x320]` — the range —
-    // is never read on this path. Every clamp the reference exhibits is FrameXML's own, through
-    // the scroll bar's `[min, max]` (`ScrollFrameTemplate_OnMouseWheel`,
-    // `ScrollFrame_OnScrollRangeChanged`). The clamp this carried from 07-05 (a3fce6a76) to 2017
-    // cost every faux list whose frame is taller than `rows × step` its last rows (B370): the
-    // reference's `FauxScrollFrame_Update` drives the bar to `(n − rows) × step`, which is past
-    // `n × step − frameHeight` whenever the frame has slack under its last row.
+    // SetVerticalScroll(px) (`0x786db0`): stores the offset unclamped (`[+0x328]`), re-anchors the
+    // child (`0x787100`) and fires `OnVerticalScroll(self, offset)`, all only on a change; the
+    // reference skips a change under 2⁻²² from the old offset, where this compares bits. The range
+    // is never read here: every clamp is FrameXML's, through the scroll bar's min and max.
     m.set(
         "SetVerticalScroll",
         lua.create_function(|lua, (this, px): (Table, f32)| {
@@ -293,22 +226,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ── The horizontal axis: the same three verbs on `[+0x324]`/`[+0x31c]` ─────────────────────
-    //
-    // `SetHorizontalScroll(px)` `0x7912f0` → `0x786d30`, which is the BYTE-CLONE of
-    // `SetVerticalScroll`'s `0x786db0` against the horizontal fields.
-    // So every law stated above holds verbatim on this axis: no clamp, the same 2⁻²² change-gate
-    // against the OLD offset alone, the same re-anchor, and `OnHorizontalScroll(self, offset)`
-    // fired only on a real change. Nothing here is a horizontal special case.
-    //
-    // The one thing that IS specific to this axis is the SIGN, and it is the reference's:
-    // `0x787100` passes both offsets to `SetPoint(TOPLEFT, self, TOPLEFT, +hScroll, +vScroll)`
-    // unnegated, so positive x pushes the child right (revealing nothing) where positive y lifts it
-    // (revealing content below). `aux-addon/tabs/search/filter.lua:315-322` — the corpus caller
-    // that made this pair worth writing, reading both axes in one line and writing both in the next
-    // — bounds x into `[min(0, frameWidth - contentWidth - 10), 0]` and y into
-    // `[0, contentHeight - frameHeight]`, which is the same asymmetry read off the other side of
-    // the API. See [`ScrollFrameState::horizontal`].
+    // ── The horizontal axis ──
+    // SetHorizontalScroll(px) (`0x7912f0` → `0x786d30`) is the vertical setter's byte-clone on
+    // `[+0x324]`, firing `OnHorizontalScroll`. The sign is the reference's: `0x787100` anchors the
+    // child at `(+hScroll, +vScroll)`, so a positive x moves it right, where a positive y lifts it.
     m.set(
         "SetHorizontalScroll",
         lua.create_function(|lua, (this, px): (Table, f32)| {
@@ -336,28 +257,17 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(scroll_range(&model, h, Axis::Horizontal))
         })?,
     )?;
-    // UpdateScrollChildRect() — the Era template calls this after resizing its content to re-drive
-    // its scrollbar. Our range is always live (never cached) against the RESOLVED rects — but a
-    // script resize (`child:SetHeight(...)`) lands in `LayoutInput` immediately, while `resolved`
-    // only catches up on the app's own next `resolve()` call (Lua runs before that each tick,
-    // `ui_script/mod.rs`'s drive loop). This is precisely the Era idiom this method exists to
-    // serve — resize the content, then immediately ask for the new range — so a stale `resolved`
-    // would make its very own primary caller see a one-tick-old (often wrong-by-a-lot, e.g. still
-    // "nothing to scroll") answer. Force a fresh resolve first: cheap on a quiet graph (the
-    // fixpoint's own doc — an unrelated resize elsewhere converges in one round), and correctness
-    // here matters more than dodging a resolve pass a caller who wants nothing stale already asked
-    // for by name.
+    // UpdateScrollChildRect(): recomputes both ranges and fires `OnScrollRangeChanged` at once,
+    // where the reference only marks them dirty (`0x791943`) for its next pump, which fires on a
+    // change. A script resize reaches the resolved rects only at the app's next resolve, so this
+    // resolves first.
     m.set(
         "UpdateScrollChildRect",
         lua.create_function(|lua, this: Table| {
             let h = frame_handle_of(lua, &this)?;
-            // The reference derives the range from a child whose text is already laid out — its
-            // measure is synchronous. Ours measures on the metric reads and on the host's
-            // round-trip, which lands a frame later; stock `QuestLog_UpdateQuestDetails` calls
-            // this right after the SetTexts that fill the pane, and read a range of 0 (1944). So
-            // the child's FontStrings are measured here, through the installed measurer, before
-            // the layout that the range reads; with no measurer installed the round-trip fills
-            // them as before.
+            // The reference measures text synchronously and ours lands a frame later, so the
+            // child's FontStrings are measured first: `QuestLog_UpdateQuestDetails` calls this
+            // right after its SetTexts (`QuestLogFrame.lua:458`).
             let strings: Vec<crate::widget::RegionHandle> = {
                 let model = lua.app_data_ref::<Model>().expect("model app_data");
                 match model.arena.frame(h).map(|f| &f.kind_state) {
@@ -378,17 +288,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 let y_range = scroll_range(&model, h, Axis::Vertical);
                 (model.frame_id(h), x_range, y_range)
             };
-            // That forced resolve can have MOVED sizes — this method exists precisely because the
-            // caller just resized its content — so drain the queue before the range notify: the
-            // reference fires `OnSizeChanged` from `ApplyRect`, i.e. during the layout, not after.
+            // The resolve can move sizes, and the reference fires `OnSizeChanged` during layout, so
+            // those fire before the range notify.
             event::fire_size_changes(lua);
-            // `OnScrollRangeChanged(self, xRange, yRange)` — **horizontal first**, and that order is
-            // byte-derived rather than assumed: at `0x786eff` the vertical result is on top of the
-            // x87 stack, is `fstp`'d first and therefore pushed DEEPEST, so it lands as `arg2`. It
-            // is why stock `UIPanelScrollFrameTemplate` hands `arg2` to
-            // `ScrollFrame_OnScrollRangeChanged`.
-            // `arg1` was a hardcoded `0.0` here for as long as there was no horizontal range to
-            // put in it.
+            // `OnScrollRangeChanged(self, xRange, yRange)`: horizontal first (`0x786eff`), which is
+            // why stock passes `arg2` on as the vertical range (`UIPanelTemplates.xml:188`).
             if let Err(e) = event::fire_widget_handler(
                 lua,
                 id,
@@ -410,9 +314,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Fire `On{Vertical,Horizontal}Scroll(self, offset)` (the ScrollFrame's own script slots — the
-/// reference's `[+0x334]`/`[+0x32c]`, fired from the setter clones `0x786db0`/`0x786d30`). Fired
-/// outside any model borrow; errors go to [`Model::errors`] like every other widget handler.
+/// Fire `On{Vertical,Horizontal}Scroll(self, offset)`, the reference's script slots `[+0x334]` and
+/// `[+0x32c]`, outside any model borrow.
 fn fire_scroll(lua: &Lua, this: &Table, script: &str, value: f32) -> mlua::Result<()> {
     let id = {
         let h = frame_handle_of(lua, this)?;
diff --git a/crates/benilla-ui/src/script/session.rs b/crates/benilla-ui/src/script/session.rs
index a73d8ce5..4b1a7f82 100644
--- a/crates/benilla-ui/src/script/session.rs
+++ b/crates/benilla-ui/src/script/session.rs
@@ -1,82 +1,48 @@
-//! The **session API** (decisions 0674, 1291) — the four exit globals the game menu's Logout and
-//! Exit Game buttons call, the two dialogs' answers to them, and `ReloadUI()`.
-//!
-//! The shape is [`super::duel`]'s: nothing to read, only the outbound half. Each call queues a
-//! [`SessionRequest`] the app drains ([`super::UiScript::take_session_requests`]) and turns into a
-//! packet or a process exit, so the engine keeps no reach into ECS/net (decision 0068 §3).
-//!
-//! What each one means, and where the reference puts it:
-//!
-//! - `Logout()` — ask to leave the world (`CMSG_LOGOUT_REQUEST`; the client's own
-//!   `ClientServices::SendLogout 0x5ab000`). The **server** decides
-//!   whether that is instant or a 20-second countdown, and says so in `SMSG_LOGOUT_RESPONSE`; the
-//!   client's whole job is to narrate the answer, which is the CAMP dialog.
-//! - `Quit()` — the same request, plus a standing intent to end the *process* rather than return to
-//!   character select when the logout completes. That is why Exit Game shows the same countdown
-//!   under a different name (QUIT_TIMER "%d %s until exit").
-//! - `CancelLogout()` — call off either one (`CMSG_LOGOUT_CANCEL`); the server acks with
-//!   `SMSG_LOGOUT_CANCEL_ACK`, which is what fires `LOGOUT_CANCEL` and takes the dialog down.
-//! - `ForceQuit()` — the QUIT dialog's "Exit now": end the process immediately, without waiting out
-//!   the server's clock. (Its logout sibling `ForceLogout()` is deliberately absent: the reference's
-//!   own CAMP dialog has the force button commented out — "uncomment once forced logouts are
-//!   completely implemented (they currently have a failure case)" — so 1.12 ships no way to call it
-//!   from the UI, and neither do we.)
+//! The session verbs: the game menu's Logout and Exit Game, their dialogs' answers, `ReloadUI`
+//! and the cinematic pair. Each queues a [`SessionRequest`] the app turns into a packet or an
+//! exit; the server decides whether a logout is instant or a 20-second countdown.
 
 use mlua::Lua;
 
 use super::Model;
 
-/// Outbound session-exit intents queued by the Era API calls, drained by the app
-/// ([`super::UiScript::take_session_requests`]). Plain data — [`super::DuelRequest`]'s twin.
+/// A session intent queued by a Lua call, drained by the app.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum SessionRequest {
-    /// `Logout()` — leave the world back to character select.
+    /// `Logout()`: `CMSG_LOGOUT_REQUEST` (`0x5ab000`), back to character select.
     Logout,
-    /// `Quit()` — leave the world and end the process once it completes.
+    /// `Quit()`: the same request, then the process ends once the logout completes.
     Quit,
-    /// `CancelLogout()` — call off a pending logout or quit.
+    /// `CancelLogout()`: `CMSG_LOGOUT_CANCEL`; the server's ack fires `LOGOUT_CANCEL`.
     CancelLogout,
-    /// `ForceQuit()` — end the process now, no server round trip.
+    /// `ForceQuit()`: end the process now, with no server round trip.
     ForceQuit,
-    /// `ForceLogout()` — the session dispatcher with `force = 1`: `CMSG_PLAYER_LOGOUT` (`0x4A`,
-    /// empty) instead of `Logout`'s `0x4B`, the pending-logout latch bypassed, and nothing at all
-    /// without a live in-world session (decision 1963; `ForceLogout 0x48ab50`'s `0x5ab020` gate).
+    /// `ForceLogout()` (`0x48ab50`): an empty `CMSG_PLAYER_LOGOUT` (`0x4A`), bypassing the
+    /// pending-logout latch, and nothing without a live in-world session (`0x5ab020`).
     ForceLogout,
-    /// `ReloadUI()` — tear this VM down and build a fresh one, without leaving the world.
-    ///
-    /// The reference's `ReloadUI 0x4884d0` reads no arguments and returns no values; it only sets
-    /// `ds:0xb4b3f4`, and the per-frame callback `0x495590` runs the teardown/rebuild pair
-    /// (`0x490bd0` → `0x48fbf0`) on the NEXT frame — a deferral that doubles as the reentrancy
-    /// guard: the Lua state being destroyed is never the one mid-way through executing the call.
-    /// Queuing an intent the app runs outside any VM call is that same guard in this engine's
-    /// shape.
+    /// `ReloadUI()` (`0x4884d0`) only sets `0xb4b3f4`; the next frame's `0x495590` tears the VM
+    /// down and rebuilds it, so it is never destroyed mid-call. The app's drain, outside any call,
+    /// is the same guard.
     ReloadUi,
-    /// `StopCinematic()` — skip the cinematic that is playing.
-    ///
-    /// **The only skip path there is.** In the reference this binding (`0x48b970`) has *zero*
-    /// native callers: nothing in the engine calls it, and it is absent from `Bindings.xml`, so
-    /// ESC reaches it purely through `CinematicFrame`'s own `OnKeyDown` handler while that
-    /// fullscreen frame holds keyboard focus. A cinematic with no `CinematicFrame` on screen is
-    /// therefore un-skippable — which is why benilla starts playback only once the in-game UI
-    /// exists.
+    /// `StopCinematic()` (`0x48b970`), the only skip: no native caller and no binding, so ESC
+    /// reaches it only through `CinematicFrame`'s `OnKeyDown`; playback therefore waits for the
+    /// in-game UI.
     StopCinematic,
 }
 
 impl super::UiScript {
-    /// Drain the session-exit intents queued since the last call.
+    /// Drain the session intents queued since the last call.
     pub fn take_session_requests(&mut self) -> Vec<SessionRequest> {
         std::mem::take(&mut self.model_mut().session_requests)
     }
 
-    /// Queue an intent from the app side — the `/logout` and `/camp` slash commands, which benilla
-    /// parses in Rust rather than through `SlashCmdList` (the [`super::UiScript::queue_duel_request`]
-    /// posture), so they enter the same queue and get the same dialog.
+    /// Queue an intent from the app: `/logout`, `/camp`, `/quit` and `/reload`, which benilla
+    /// parses in Rust rather than through `SlashCmdList`, take their Lua verbs' route this way.
     pub fn queue_session_request(&mut self, request: SessionRequest) {
         self.model_mut().session_requests.push(request);
     }
 }
 
-/// Register the session globals — the four exit verbs, `ReloadUI`, and the cinematic skip.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
@@ -99,9 +65,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // `InCinematic()` — the reference's `0x48c930`: reads the "a cinematic is playing" global and
-    // answers the **number 1** while one is, `nil` otherwise (both legs push exactly one result).
-    // Era convention, not `true`/`false`.
+    // `0x48c930`: the number 1 while a cinematic plays, else nil, one result either way.
     g.set(
         "InCinematic",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/shapeshift.rs b/crates/benilla-ui/src/script/shapeshift.rs
index 673e3a16..6a5b2c9c 100644
--- a/crates/benilla-ui/src/script/shapeshift.rs
+++ b/crates/benilla-ui/src/script/shapeshift.rs
@@ -1,58 +1,40 @@
-//! The shapeshift/stance bar seam — the ref's four bindings
-//! (`GetNumShapeshiftForms`/`GetShapeshiftFormInfo`/`GetShapeshiftFormCooldown`/
-//! `CastShapeshiftForm`, consumed by `BonusActionBarFrame.lua`'s `ShapeshiftBar_*` family) over
-//! an app-pushed form list, the [`super::spellbook`]/[`super::action`] two-way shape: the app
-//! resolves everything (which known spells are forms, their icon/name/active/castable/cooldown —
-//! the mechanism lives app-side), pushes a snapshot
-//! ([`super::UiScript::set_shapeshift_forms`]), and drains the click intents
-//! ([`super::UiScript::take_shapeshift_casts`]) onto the wire. The engine holds no form
-//! KNOWLEDGE — a form is "a spell id, a texture, a name, two bits, and a cooldown triple".
-//!
-//! Return conventions are the 1.12 API's own, matching [`super::action`]: 1/nil booleans, and
-//! the cooldown pushed as `(start_ms on the GetTime clock, duration_ms, enabled)` (the
-//! [`super::action::ActionState::cooldown`] pattern — absolute start, app-converted at feed
-//! time) so `GetShapeshiftFormCooldown` answers the ref's `(start, duration, enable)`.
+//! The stance bar's four bindings, which `BonusActionBarFrame.lua`'s `ShapeshiftBar_*` calls, over
+//! a form list the app resolves and pushes; flags answer 1/nil and the cooldown is the reference's
+//! `(start, duration, enable)`.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// One stance-bar button, fully resolved by the app before pushing.
+/// One stance-bar button, resolved by the app.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct ShapeshiftFormView {
-    /// The form spell (the app resolves a queued cast/cancel from it at drain time).
+    /// The form spell a click queues.
     pub spell_id: u32,
     /// The icon texture path; `None` shows the slot's fallback.
     pub texture: Option<String>,
-    /// The spell name (`GetShapeshiftFormInfo`'s second return — the ref's tooltip/debug read).
+    /// The spell name, `GetShapeshiftFormInfo`'s second return.
     pub name: String,
-    /// This form is the player's CURRENT form (the checked ring).
+    /// The player's current form (the checked ring).
     pub active: bool,
-    /// Castable right now (the ref greys the icon 0.4 when not).
+    /// Castable now; the reference greys the icon to 0.4 when not.
     pub castable: bool,
-    /// The form spell's cooldown as `(start_ms on the GetTime clock, duration_ms, enabled)`
-    /// ([`super::action::ActionState::cooldown`]'s exact shape); `None` = no cooldown.
+    /// `(start_ms on the GetTime clock, duration_ms, enabled)`, as an action's cooldown.
     pub cooldown: Option<(i64, u32, bool)>,
 }
 
-/// [`ShapeshiftFormView`] as stored: the cooldown converted to the `GetTime` clock at push time
-/// (the [`super::action::StoredActionState`] pattern).
+/// A pushed form with its cooldown in `GetTime` seconds.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub(crate) struct StoredShapeshiftForm {
     pub(crate) view: ShapeshiftFormView,
-    /// `(start_s, duration_s, enabled)` in `GetTime` seconds; `None` = no cooldown.
+    /// `(start_s, duration_s, enabled)`.
     pub(crate) cooldown: Option<(f64, f64, bool)>,
 }
 
 impl super::UiScript {
-    /// Push the whole form list (bar order = list order), replacing whatever was there. A bare
-    /// setter — firing `UPDATE_SHAPESHIFT_FORMS` (and the state-refresh events the transcribed
-    /// bar listens to) is the app's own diff-and-fire job, mirroring `set_spellbook`.
+    /// Replace the form list, in bar order; the app fires `UPDATE_SHAPESHIFT_FORMS` itself.
     pub fn set_shapeshift_forms(&mut self, forms: Vec<ShapeshiftFormView>) {
         let mut model = self.model_mut();
-        // The cooldown arrives with its absolute start already on the `GetTime` clock (ms) —
-        // storing is a pure unit conversion, the same seam shape as
-        // [`super::UiScript::set_action_state`].
         model.shapeshift_forms = forms
             .into_iter()
             .map(|view| {
@@ -68,21 +50,20 @@ impl super::UiScript {
             .collect();
     }
 
-    /// Drain the form spell ids `CastShapeshiftForm` queued since the last call. Whether a queued
-    /// id becomes a cast or a cancel (clicking the ACTIVE form) is the app's call at drain time.
+    /// Drain the form spells `CastShapeshiftForm` queued; the app casts each, or cancels it when it
+    /// is the active form.
     pub fn take_shapeshift_casts(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().shapeshift_casts)
     }
 }
 
-/// The 1-based button index → stored form, the ref's own indexing.
+/// A 1-based button index, as the reference indexes.
 fn form_at(model: &Model, i: u32) -> Option<&StoredShapeshiftForm> {
     usize::try_from(i.checked_sub(1)?)
         .ok()
         .and_then(|n| model.shapeshift_forms.get(n))
 }
 
-/// Register the shapeshift globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
@@ -94,8 +75,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetShapeshiftFormInfo(i) → texture, name, isActive (1/nil), isCastable (1/nil); out of
-    // range → a single nil (the spellbook bindings' out-of-range shape).
     g.set(
         "GetShapeshiftFormInfo",
         lua.create_function(|lua, i: u32| {
@@ -117,9 +96,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetShapeshiftFormCooldown(i) → start, duration, enable — GetActionCooldown's exact triple
-    // and elapsed-goes-cold rule (an elapsed/absent cooldown answers (0, 0, 1) so a re-feed never
-    // replays the sweep).
+    // As `GetActionCooldown`: an elapsed or absent cooldown answers `(0, 0, 1)`, so a re-feed never
+    // replays the sweep.
     g.set(
         "GetShapeshiftFormCooldown",
         lua.create_function(|lua, i: u32| {
@@ -134,7 +112,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CastShapeshiftForm(i) — queues the form's spell id; an out-of-range index is a no-op.
     g.set(
         "CastShapeshiftForm",
         lua.create_function(|lua, i: u32| {
@@ -154,8 +131,6 @@ mod tests {
     use super::ShapeshiftFormView;
     use crate::script::UiScript;
 
-    /// A warrior mid-career: Battle Stance (active, castable), Defensive Stance (castable, on a
-    /// 1.5 s cooldown started at GetTime 9.4 s).
     fn forms() -> Vec<ShapeshiftFormView> {
         vec![
             ShapeshiftFormView {
@@ -200,7 +175,6 @@ mod tests {
                 Some(1)
             )
         );
-        // Form 2: not active (nil), castable (1).
         assert!(s
             .eval::<bool>("local _, _, a, c = GetShapeshiftFormInfo(2) return a == nil and c == 1")
             .unwrap());
@@ -215,13 +189,11 @@ mod tests {
         s.tick(10.0); // GetTime == 10
         s.set_shapeshift_forms(forms());
 
-        // No cooldown → the cold (0, 0, 1).
         assert_eq!(
             s.eval::<(f64, f64, i32)>("return GetShapeshiftFormCooldown(1)")
                 .unwrap(),
             (0.0, 0.0, 1)
         );
-        // The pushed absolute start (9400 ms) reads back verbatim in seconds.
         let (start, duration, enable) = s
             .eval::<(f64, f64, i32)>("return GetShapeshiftFormCooldown(2)")
             .unwrap();
@@ -229,7 +201,6 @@ mod tests {
         assert!((duration - 1.5).abs() < 1e-9);
         assert_eq!(enable, 1);
 
-        // Past the end the read goes cold.
         s.tick(2.0); // now == 12 > 9.4 + 1.5
         assert_eq!(
             s.eval::<(f64, f64, i32)>("return GetShapeshiftFormCooldown(2)")
diff --git a/crates/benilla-ui/src/script/simplehtml/mod.rs b/crates/benilla-ui/src/script/simplehtml/mod.rs
index 5a8cc7da..af8870f6 100644
--- a/crates/benilla-ui/src/script/simplehtml/mod.rs
+++ b/crates/benilla-ui/src/script/simplehtml/mod.rs
@@ -1,64 +1,23 @@
-//! The **`SimpleHTML` widget** (`CSimpleHTML`, class size `0x374`, ctor `0x789dd0`) — its markup
-//! engine, its block layout, its four element fonts, and its 19-entry Lua method table.
+//! The `SimpleHTML` widget (`CSimpleHTML`, size `0x374`, ctor `0x789dd0`): the blocks [`parse`]
+//! produces, built as regions, its four element fonts, and its Lua method table.
 //!
-//! Ground truth: byte-verified against `WoW.exe`. The parse itself is [`parse`]; this module is
-//! the half that touches the model — turning a block list into real FontString/Texture regions
-//! anchored bottom-to-top, and exposing the widget's Lua surface.
+//! `SetText` drops the previous blocks and builds the parsed ones. A text block is a FontString at
+//! the frame's declared width with no height; block 0 hangs from the frame's TOPLEFT and block N
+//! from block N-1's BOTTOMLEFT, `spacing` lower (0 by default).
 //!
-//! ## What the widget is, in one paragraph
+//! A block is LEFT unless its `align` says otherwise, never the FontString ctor's CENTER
+//! (`0x78a7c8`, `0x78ae78`). An element font starts empty, and `H1` to `H3` use `P`'s while their
+//! path is empty (`0x78ae30`), with no header scaling. There is no `GetContentHeight`: the hosting
+//! ScrollFrame measures the blocks as regions (`0x786e30`).
 //!
-//! `SetText(s)` throws away every block of the previous parse, runs `s` through a **strict XML**
-//! parser, and — if and only if the document is well-formed, rooted at `HTML`, and has a `BODY`
-//! child — walks that BODY emitting one block per `<H1>`/`<H2>`/`<H3>`/`<P>`/`<BR/>`/`<IMG>`.
-//! Anything else falls to the plain-text path: the **raw** string as one `P` block, left-aligned,
-//! whitespace intact. Each text block is one `CSimpleFontString` at the frame's declared width
-//! with **no height set**, so its rect is the intrinsic height of the wrapped text; block 0 hangs
-//! from the frame's TOPLEFT and block *N* from block *N−1*'s BOTTOMLEFT at `−spacing`. Spacing
-//! defaults to 0, so blocks are flush.
+//! Deviation: the block step is not pixel-snapped (`0x766750`), because layout here is in logical
+//! units; the two differ by under a pixel, and not at all at the default spacing of 0. Line spacing
+//! inside a block is not applied, as nothing here models line spacing; `SetSpacing` sets the step
+//! between blocks. Deviation: a block of width 0, in a frame sized by anchors, gets its text's
+//! natural width where the reference keeps 0, because every width-less FontString here does.
 //!
-//! ## Three defaults a re-implementation gets wrong, and this one does not
-//!
-//! - **Block justifyH is LEFT**, never the `CSimpleFontString` ctor's CENTER: `align` is
-//!   pre-loaded with `1` before the attribute is read (`0x78a7c8`) and `0x78ae78` writes it into
-//!   the block after `SetFontObject`, so the element font's own `justifyH` can never reappear.
-//! - **Element fonts start with no font at all**, and `H1`/`H2`/`H3` fall back to `P`'s whenever
-//!   their own resolved path is empty (`0x78ae30` measures `SStr::Length(&font->path)`). **Nothing
-//!   in this TU scales a header** — no height multiply, no size table — so an `<H1>` under a
-//!   single `<FontString>` declaration renders at exactly the `<P>` size. That is the reference
-//!   `ItemTextFrame` render, not an approximation of it.
-//! - **`GetContentHeight` does not exist in 1.12.1.** The method table has no height getter and
-//!   nothing in the TU aggregates one; the hosting ScrollFrame measures the subtree generically
-//!   instead (`0x786e30`'s subtree union), which is what ours does too — the blocks are real
-//!   regions of the SimpleHTML, so `GetVerticalScrollRange` sees them without SimpleHTML
-//!   publishing anything.
-//!
-//! ## Where this diverges from the reference, deliberately
-//!
-//! - **`nextYOffset` is not pixel-snapped.** The reference stores
-//!   `−pixelSnap(spacing)` (`0x766750`, quantising to whole *device* pixels). Our layout is in
-//!   logical units and the solver has no device-pixel quantiser to reach for; at the default
-//!   spacing of 0 the two agree exactly, and at any other value they differ by under a pixel.
-//! - **Intra-block line spacing is not modelled**, because nothing in this engine models line
-//!   spacing at all (see `script::font_block`'s own note on the withheld `Set/GetSpacing`). What
-//!   `SimpleHTML:SetSpacing` *does* honour here is the half SimpleHTML itself owns and computes:
-//!   the inter-block step. That is a real, drawn effect rather than a stored-and-ignored number,
-//!   which is why this pair ships where the FontString/Font ones do not.
-//! - **A block's wrap width of 0** (a SimpleHTML sized only by anchors) lets the measure
-//!   round-trip supply the natural text width, where the reference leaves the block at width 0.
-//!   That is this engine's standing law for every height-less/width-less FontString, and inverting
-//!   it here would make a SimpleHTML the one widget whose text vanishes when it is anchor-sized.
-//!
-//! ## The Lua table, and the one name that is NOT on it
-//!
-//! The method table `.data 0x87ba80` dumps as **19 `{name, fn}` pairs**, and all 19 are installed
-//! here. The first sixteen take an **optional leading element-name string** resolved by
-//! `0x795d80`; the last
-//! three (`SetText`, `SetHyperlinkFormat`, `GetHyperlinkFormat`) do not.
-//!
-//! **There is no `GetText`.** Later clients grew one; build 5875's table does not have it, and
-//! adding a name a table does not carry is exactly as wrong as missing one (`script::font_block`'s
-//! module doc states the same law for the font block). A caller that wants the source string keeps
-//! it — the reference's own `ItemTextFrame` calls `ItemTextGetText()`.
+//! The method table (`0x87ba80`) has 19 entries, all installed; the first sixteen take an optional
+//! leading element name (`0x795d80`). Build 5875 has no `GetText`.
 
 use std::collections::HashMap;
 
@@ -76,30 +35,22 @@ mod parse;
 pub(crate) use parse::Block;
 use parse::{ELEMENT_NAMES, ELEM_P};
 
-/// Registry key of the SimpleHTML method table (the MAXCSTACK discipline: Lua-side root, named key).
+/// Registry key of the SimpleHTML method table (the MAXCSTACK discipline).
 pub(super) const REG_SIMPLEHTML_METHODS: &str = "__benilla_simplehtml_methods";
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// State
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── State ────────────────────────────────────────────────────────────────────────────────────
 
-/// One of the four **element fonts** (`CSimpleHTML+0x350`…`+0x35c`, index `0 = P, 1 = H1, 2 = H2,
-/// 3 = H3`), each a `0x80`-byte subclass of `CSimpleFont` the ctor loop `0x789e61`–`0x789ea3`
-/// allocates.
-///
-/// Modelled as "the named object it points at, plus the properties it set for itself" rather than
-/// as a flattened snapshot, so a later `GameFontNormal:SetFont(…)` reaches the *next* parse — the
-/// live `parentFontObject` link the real `CFontInstance` carries. The explicit mask is the same
-/// `FONTINSTANCE+0x038` severance record a region keeps ([`super::FontExplicit`]); reusing it is
-/// what lets a block inherit the mask and stay correct under `script::font::propagate`.
+/// One of the four element fonts (`CSimpleHTML+0x350`, P, H1, H2, H3; made at
+/// `0x789e61`-`0x789ea3`): the font object it inherits, a live link as the reference's
+/// `parentFontObject` is, plus what it set itself.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub(crate) struct ElementFont {
-    /// `inherits=` / `SetFontObject(elem, obj)` — the object this element resolves through.
+    /// `inherits=` or `SetFontObject`: the object this element resolves through.
     pub(crate) font_object: Option<String>,
-    /// Which properties this element set for **itself** (and so must survive a re-read of the
-    /// object above).
+    /// What this element set itself, the region's severance mask (`FONTINSTANCE+0x038`), which a
+    /// block inherits.
     pub(crate) explicit: super::FontExplicit,
-    /// `FieldBlock.path +0x3c`, ctor `""` — the field `0x78ae30` measures for the H1→P fallback.
+    /// `+0x3c`, empty at the ctor: the path `0x78ae30` tests for the fallback to `P`.
     pub(crate) font_path: Option<String>,
     /// `FieldBlock` height.
     pub(crate) font_height: Option<f32>,
@@ -109,26 +60,21 @@ pub(crate) struct ElementFont {
     pub(crate) color: Option<[f32; 4]>,
     /// `SetShadowColor`/`SetShadowOffset` / `<Shadow>`.
     pub(crate) shadow: Option<FontShadow>,
-    /// `CSimpleFont+0x54`, ctor `0x212` (`0x783a98`) — CENTER | MIDDLE | the one-to-one bit.
+    /// `CSimpleFont+0x54`, ctor `0x212` (`0x783a98`): CENTER, MIDDLE and the one-to-one bit.
     pub(crate) justify: Justify,
-    /// `FieldBlock.spacing +0x50`, ctor **0** (`0x783a81`). Both the inter-block step
-    /// (`nextYOffset = −pixelSnap(spacing)`) and, in the reference, the intra-block line gap.
+    /// `+0x50`, ctor 0 (`0x783a81`): the step between blocks and, in the reference, the line gap.
     pub(crate) spacing: f32,
 }
 
-/// A `SimpleHTML` frame's runtime state — the members `CSimpleHTML` adds over `CSimpleFrame`.
-///
-/// Held in a [`Model`]-side map rather than in [`crate::widget::KindState`] for the reason
-/// `Model::backdrops` is: its contents are script-layer types ([`FontObject`], [`FontShadow`],
-/// [`Outline`]), and `widget::kinds` is the layer *below* `script` and does not depend on it.
+/// A `SimpleHTML` frame's state, the members `CSimpleHTML` adds; in a [`Model`] map, not
+/// [`crate::widget::KindState`], because it holds script-layer types.
 #[derive(Clone, Debug, PartialEq)]
 pub(crate) struct SimpleHtmlState {
-    /// `+0x350`…`+0x35c`.
+    /// `+0x350` to `+0x35c`.
     pub(crate) fonts: [ElementFont; 4],
     /// `+0x360`, ctor `"|H%s|h%s|h"` (`0x87a838`).
     pub(crate) hyperlink_format: String,
-    /// The CONTENTNODE list `+0x340` — every region the last `SetText` built, in emission order,
-    /// text blocks and images alike. This is the free list the next `SetText` walks.
+    /// The content list (`+0x340`): every region the last `SetText` built, freed by the next.
     pub(crate) blocks: Vec<RegionHandle>,
 }
 
@@ -142,9 +88,8 @@ impl Default for SimpleHtmlState {
     }
 }
 
-/// The paint one block copies out of its element font — the result of `CFontInstance::
-/// SetFontObject 0x770c60`, which forces all five property groups changed (`0x770d06 or …,0x1F`)
-/// and pulls immediately, with the element's own explicit sets layered back on top.
+/// The paint a block copies from its element font: `SetFontObject` (`0x770c60`) pulls all five
+/// property groups at once (`0x770d06`), with the element's own sets on top.
 #[derive(Clone, Debug, Default)]
 struct BlockPaint {
     font_object: Option<String>,
@@ -209,17 +154,13 @@ fn resolve_font(model: &Model, ef: &ElementFont) -> BlockPaint {
     p
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// SetText — the rebuild
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── SetText, the rebuild ─────────────────────────────────────────────────────────────────────
 
-/// `CSimpleHTML::SetText 0x78a3a0`, whole: free the old blocks, parse, and build the new ones.
-///
-/// Returns `usedMarkup` (`0x78a519`'s `al`) — the Lua shim discards it, our tests do not.
+/// `CSimpleHTML::SetText` (`0x78a3a0`): free the old blocks, parse, build. Returns `usedMarkup`
+/// (`0x78a519`), which the Lua shim drops.
 pub(crate) fn set_text(model: &mut Model, fh: FrameHandle, raw: &str) -> bool {
-    // `0x78a3a0`'s first step. The reference pool-frees the previous parse's widgets; ours must
-    // too, or a second `SetText` leaves the first one's FontStrings standing behind the new
-    // ones — the failure a book with a "next page" button hits on its very first turn.
+    // Free the previous parse's regions first, as the reference does, or a book's next page
+    // draws over the last.
     let old = model
         .simple_html
         .get_mut(&fh)
@@ -243,8 +184,8 @@ pub(crate) fn set_text(model: &mut Model, fh: FrameHandle, raw: &str) -> bool {
         (name, fmt)
     };
     let parsed = parse::parse_markup(raw, &frame_name, &hyperlink_format);
-    // The reference pushes these through the frame's error sink to the console. Ours are host
-    // warnings: a malformed page is the player's content being wrong, not a script raising.
+    // Deviation: the reference prints these to the console; here they are host warnings, because
+    // a malformed page is bad content, not a script error.
     for e in &parsed.errors {
         model.record_warning(e.clone());
     }
@@ -253,20 +194,18 @@ pub(crate) fn set_text(model: &mut Model, fh: FrameHandle, raw: &str) -> bool {
     parsed.used_markup
 }
 
-/// `AddTextBlock 0x78adb0`/the `<IMG>` handler `0x78ab40`'s loop — the anchor chain, the fonts,
-/// and the `nextY` bookkeeping.
+/// The block loop of `AddTextBlock` (`0x78adb0`) and the `<IMG>` handler (`0x78ab40`): anchors,
+/// fonts and the running `nextY`.
 fn build(model: &mut Model, fh: FrameHandle, blocks: &[Block]) {
     let frame_id = model.frame_id(fh);
-    // `0x78ae19 call [CLayoutFrame vtbl + 0x1c]` = `0x768420`, `fld [ecx+0x50]` — the frame's
-    // **declared** width, not its resolved rect. Every block is exactly that wide, which is what
-    // makes each one word-wrap at the frame width; `OnRectChanged 0x78a320`'s corollary is that a
-    // later resize does NOT re-wrap, because each block snapshotted the width at creation.
+    // The frame's declared width, not its resolved rect (`0x78ae19`, `0x768420`); a later resize
+    // does not re-wrap (`OnRectChanged` `0x78a320`), as each block keeps the width it was built at.
     let width = model
         .layout_inputs
         .get(&fh)
         .map_or(0.0, |input| input.width);
 
-    // `+0x348 prevBlock` — the last **text** block, and `+0x34c nextYOffset` (always <= 0).
+    // `prevBlock` (`+0x348`), the last text block, and `nextYOffset` (`+0x34c`), never positive.
     let mut prev_block: Option<u32> = None;
     let mut next_y = 0.0f32;
     let mut made: Vec<RegionHandle> = Vec::with_capacity(blocks.len());
@@ -274,10 +213,8 @@ fn build(model: &mut Model, fh: FrameHandle, blocks: &[Block]) {
     for block in blocks {
         match block {
             Block::Text { text, elem, align } => {
-                // The empty-path fallback (`0x78ae29`–`0x78ae54`): `elementFont[elem]`, unless its
-                // resolved path is empty, in which case `elementFont[0]` — so a declaration that
-                // supplies only `<FontString>` supplies the font for every element, headers
-                // included.
+                // An element with an empty path uses `P`'s font (`0x78ae29`-`0x78ae54`), so a
+                // lone `<FontString>` serves every element.
                 let paint = {
                     let st = model.simple_html.entry(fh).or_default().clone();
                     let own = resolve_font(model, &st.fonts[*elem]);
@@ -292,18 +229,14 @@ fn build(model: &mut Model, fh: FrameHandle, blocks: &[Block]) {
                         .arena
                         .create_region(fh, RegionKind::FontString, DrawLayer::Artwork, 0)
                 else {
-                    // The frame died under us — unreachable (we hold its handle and just made
-                    // regions on it), but stop rather than orphan what is already built: the
-                    // blocks so far are still recorded below, so the next `SetText` frees them.
+                    // Unreachable; stop, keeping what was built recorded for the next `SetText`.
                     break;
                 };
                 let id = model.region_id(rh);
                 let mut d = RegionData {
                     anchors: vec![anchor_for(prev_block, frame_id, Point::TopLeft, next_y)],
-                    // `SetWidth(frame.GetWidth())` and **no height** — the block's rect height is
-                    // the FontString's intrinsic wrapped height, which the engine's measure
-                    // round-trip supplies exactly as the client's font engine supplies
-                    // `0x7729b0` → `0x5c2070`.
+                    // No height: the rect takes the wrapped text's height from the measure round
+                    // trip, as the client's font engine gives it (`0x7729b0`, `0x5c2070`).
                     size: Some((width, 0.0)),
                     text: Some(text.clone()),
                     font_object: paint.font_object.clone(),
@@ -315,21 +248,15 @@ fn build(model: &mut Model, fh: FrameHandle, blocks: &[Block]) {
                     font_shadow: paint.shadow,
                     ..RegionData::default()
                 };
-                // `block->+0x120 = (block->+0x120 & ~7) | (align & 7)` (`0x78ae78`), written
-                // AFTER `SetFontObject`, so the tag's `align` always wins over the element font's
-                // own justifyH. justifyV is left alone and keeps whatever the element font
-                // supplied (ctor MIDDLE) — visually inert here, because the block's rect height IS
-                // its text height.
+                // The tag's `align` is written after `SetFontObject` (`0x78ae78`), so it beats
+                // the font's justifyH; justifyV stays the font's, inert in a rect its text fills.
                 d.justify = Justify(justify::set_axis(paint.justify.0, justify::H_MASK, *align));
-                // …and it can never be RE-inherited: `0x78ae68` clears the per-bit justifyH
-                // inherit mask (`+0x124 &= ~7`) and `0x78ae95` the whole CFontInstance justify
-                // group bit (`+0xd4 &= ~2`). Marking both axes explicit is what that pair means
-                // here — it is what stops `script::font::propagate` from re-centering a built
-                // block the moment somebody mutates the font object it drew from.
+                // Neither axis is inherited again (`0x78ae68`, `0x78ae95` clear the inherit bits),
+                // so a later font-object change never re-justifies a built block.
                 d.font_explicit.justify_h = true;
                 d.font_explicit.justify_v = true;
                 model.region_data.insert(rh, d);
-                model.touch_measure(rh); // a text block arrives text-in-hand
+                model.touch_measure(rh); // a text block arrives with its text
                 prev_block = Some(id);
                 next_y = -paint.spacing;
                 made.push(rh);
@@ -346,15 +273,12 @@ fn build(model: &mut Model, fh: FrameHandle, blocks: &[Block]) {
                         .arena
                         .create_region(fh, RegionKind::Texture, DrawLayer::Artwork, 0)
                 else {
-                    break; // as above
+                    break; // unreachable, as above
                 };
-                // Minted even though nothing anchors TO an image (`prevBlock` is never written by
-                // the image path): the id is what the resolve seats the region's rect under, and
-                // what `free_block` unmaps on the next `SetText`.
+                // Minted though nothing anchors to an image; the resolve and `free_block` use it.
                 model.region_id(rh);
-                // The anchor corner is selected by `align`, and 8/16/32 get **no
-                // `SetPoint` at all** (`0x78ac61 jne 0x78ace8`). An anchorless region never
-                // resolves here either, so it draws nothing, which is the same outcome.
+                // `align` picks the corner; 8, 16 and 32 get no anchor at all (`0x78ac61`, a jump
+                // to `0x78ace8`), so the image draws nothing, here as there.
                 let point = match *align {
                     parse::ALIGN_LEFT => Some(Point::TopLeft),
                     parse::ALIGN_CENTER => Some(Point::Top),
@@ -373,16 +297,10 @@ fn build(model: &mut Model, fh: FrameHandle, blocks: &[Block]) {
                         ..RegionData::default()
                     },
                 );
-                // An unfloated image reserves its own height in the flow (`0x78ad07`–`0x78ad1b`),
-                // and `prevBlock` is **never** written by the image path (three reads of `+0x348`
-                // in the whole function, zero writes) — the next block still hangs off the last
-                // TEXT block, only lower.
-                //
-                // The height it reserves is `texture.GetHeight()`, which is `CSimpleTexture`'s
-                // **override**: a `<IMG>` with no `height=` reserves its art's own texel height,
-                // not nothing (decision 1349 — one texel is one FrameXML unit). Asked of the same
-                // host oracle the resolve derives the region's rect from, so the space the flow
-                // leaves and the space the image fills are one number.
+                // An unfloated image moves the flow down by its height (`0x78ad07`-`0x78ad1b`), but
+                // the next block still hangs off the last text block: the image path never writes
+                // `prevBlock`. Without `height=` it reserves its texture's texel height
+                // (`CSimpleTexture`'s `GetHeight`), from the probe the resolve sizes it by.
                 if !*floated {
                     let reserved = if *h == 0.0 {
                         src.as_deref()
@@ -404,8 +322,8 @@ fn build(model: &mut Model, fh: FrameHandle, blocks: &[Block]) {
     model.touch_layout();
 }
 
-/// The two anchor forms of `AddTextBlock 0x78adb0`'s `SetPoint 0x767c70` step: block 0 pins to the
-/// frame, block *N* to its predecessor's bottom edge at `nextYOffset` (negative, i.e. downward).
+/// A block's anchor (`SetPoint` `0x767c70`): block 0 to the frame, block N to the previous text
+/// block's bottom edge, `nextYOffset` lower.
 fn anchor_for(prev_block: Option<u32>, frame_id: u32, point: Point, next_y: f32) -> Anchor {
     match prev_block {
         None => Anchor::new(point, frame_id, point, 0.0, 0.0),
@@ -421,26 +339,15 @@ fn anchor_for(prev_block: Option<u32>, frame_id: u32, point: Point, next_y: f32)
     }
 }
 
-/// Free one block region — [`crate::script::region::free_region`], which is where this function's
-/// body went when the button's label swap needed the same five-map teardown. Kept as a name
-/// because `set_text`'s call sites read better with it, and because the doc that explains *why* a
-/// destroyed region must answer stale rather than linger lives on the shared law now.
 fn free_block(model: &mut Model, rh: RegionHandle) {
     crate::script::region::free_region(model, rh);
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The loader's seam
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The loader's seam ────────────────────────────────────────────────────────────────────────
 
-/// Apply the font parts an **XML** `<FontString>`/`<FontStringHeaderN>` child of a `<SimpleHTML>`
-/// supplies — `font=`, `<FontHeight>`, `outline=` — any subset of which may be absent.
-///
-/// The region-side twin of this is [`super::apply_font_parts`], and it exists for the same reason:
-/// the reference applies XML font attributes in C++ (`CSimpleFont::LoadXML 0x783c30`, reached from
-/// `0x78a1fe`…`0x78a26e`), never through the Lua `SetFont`, whose usage string *requires* both a
-/// path and a height. Routing the loader through the binding is what forces the binding to be
-/// lenient; keeping them separate lets each be right.
+/// Apply the `font=`, `<FontHeight>` and `outline=` an XML `<FontString>` or `<FontStringHeaderN>`
+/// child supplies, any of them absent. The reference applies these in C++ (`CSimpleFont::LoadXML`
+/// `0x783c30`, from `0x78a1fe`), not through `SetFont`, which requires both path and height.
 pub(crate) fn apply_element_font_parts(
     lua: &Lua,
     this: &Table,
@@ -467,8 +374,9 @@ pub(crate) fn apply_element_font_parts(
     Ok(())
 }
 
-/// The element index an XML child tag names: `<FontString>` → `P`, `<FontStringHeader1|2|3>` →
-/// `H1`/`H2`/`H3` (`0x8786cc`, `0x87a8b4`/`0x87a8a0`/`0x87a88c`; assigned at `0x78a1fe`…`0x78a26e`).
+/// The element index an XML child tag names: `<FontString>` is `P`, `<FontStringHeader1|2|3>`
+/// `H1`, `H2`, `H3` (names `0x8786cc`, `0x87a8b4`, `0x87a8a0`, `0x87a88c`; read at `0x78a1fe` to
+/// `0x78a26e`).
 pub(crate) fn element_of_xml_tag(tag: &str) -> Option<usize> {
     if tag.eq_ignore_ascii_case("FontString") {
         Some(0)
@@ -483,13 +391,9 @@ pub(crate) fn element_of_xml_tag(tag: &str) -> Option<usize> {
     }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The Lua surface
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The Lua surface ──────────────────────────────────────────────────────────────────────────
 
-/// Resolve `this` to a live `SimpleHTML` frame. Reached through the kind dispatcher, so the guard
-/// only fires when a caller fishes the method table out and misapplies it — the same posture
-/// `script::scrollframe`'s `with_scroll` takes.
+/// Resolve `this` to a live `SimpleHTML` frame; only a misapplied method table fails.
 fn html_handle(lua: &Lua, this: &Table) -> mlua::Result<FrameHandle> {
     let h = frame_handle_of(lua, this)?;
     let model = lua.app_data_ref::<Model>().expect("model");
@@ -499,22 +403,9 @@ fn html_handle(lua: &Lua, this: &Table) -> mlua::Result<FrameHandle> {
     }
 }
 
-/// `0x795d80` — the **optional leading element-name string**, consumed by the first sixteen
-/// methods.
-///
-/// ```text
-/// if (lua_type(L, 2) != LUA_TSTRING)      return 0;          ; 0x795d91
-/// if (SStrCmpI(s,"P" )==0) { lua_remove(L,2); return 0; }    ; 0x795db3
-/// if (SStrCmpI(s,"H1")==0) { lua_remove(L,2); return 1; }    ; 0x795ddb
-/// if (SStrCmpI(s,"H2")==0) { lua_remove(L,2); return 2; }    ; 0x795e06
-/// if (SStrCmpI(s,"H3")==0) { lua_remove(L,2); return 3; }    ; 0x795e2e
-/// return 0;                                                   ; 0x795e50 (NO lua_remove)
-/// ```
-///
-/// Two silent behaviours fall out and are reproduced exactly: omitting the name addresses **`P`**,
-/// and a *string* first argument that is not one of the four is **not** an error and is **not**
-/// removed — it stays and is consumed as the shared implementation's first real argument, so
-/// `SetFont("h4", path, 15)` targets `P` and hands `"h4"` to `SetFont` as the path.
+/// The optional leading element name of the first sixteen methods (`0x795d80`). `P`, `H1`, `H2`
+/// or `H3`, in any case, is removed and selects that element; anything else selects `P` and stays
+/// (`0x795e50`), so `SetFont("h4", path, 15)` sets `P`'s font with `"h4"` as the path.
 fn take_element(args: &mut MultiValue) -> usize {
     let matched = match args.front() {
         Some(Value::String(s)) => s.to_str().ok().and_then(|s| {
@@ -538,8 +429,7 @@ fn arg(args: &MultiValue, i: usize) -> Value {
     args.get(i).cloned().unwrap_or(Value::Nil)
 }
 
-/// Run `f` over one element font under a short write borrow, then dirty the layout — every one of
-/// these can change what the *next* `SetText` draws with, and several change nothing until then.
+/// Run `f` over one element font under a short borrow; it shapes the next `SetText`'s blocks.
 fn edit_font<T>(
     lua: &Lua,
     this: &Table,
@@ -551,8 +441,7 @@ fn edit_font<T>(
     Ok(f(&mut model.simple_html.entry(h).or_default().fonts[elem]))
 }
 
-/// Read one element font's **resolved** paint (the object it inherits, with its own sets on top) —
-/// what the getters answer and what a block would be built with.
+/// One element font's resolved paint: what the getters answer and a block would be built with.
 fn read_font(lua: &Lua, this: &Table, elem: usize) -> mlua::Result<BlockPaint> {
     let h = html_handle(lua, this)?;
     let model = lua.app_data_ref::<Model>().expect("model");
@@ -566,10 +455,9 @@ fn read_font(lua: &Lua, this: &Table, elem: usize) -> mlua::Result<BlockPaint> {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let m = lua.create_table()?;
 
-    // ── 0/1 · the font object, and the live link to it ──────────────────────────────────────
-    // `SetFontObject([element,] font | "font" | nil)` → 0 values. Unlike a region's, this cannot
-    // repaint anything already on screen: the element fonts are prototypes, and only the next
-    // `SetText` copies them into blocks (a built block is never re-fonted, `0x795d3e`).
+    // ── 0/1 · the font object ────────────────────────────────────────────────────────────────
+    // SetFontObject([element,] font | "font" | nil) returns nothing and changes only the next
+    // `SetText`'s blocks; a built block is never re-fonted (`0x795d3e`).
     m.set(
         "SetFontObject",
         lua.create_function(|lua, (this, mut rest): (Table, MultiValue)| {
@@ -583,11 +471,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     )));
                 }
             }
-            // The **nil form severs the link and leaves the paint standing** — the reference
-            // stores a null parent and nothing re-reads or clears the resolved values. A region
-            // gets that for free (its paint was copied into `RegionData`); an element font
-            // resolves its object lazily, so the standing paint has to be pinned down here or the
-            // sever would blank the element instead.
+            // nil severs the link and keeps the paint, as the reference stores a null parent; an
+            // element font resolves its object lazily, so the standing paint is pinned here.
             let standing = name
                 .is_none()
                 .then(|| read_font(lua, &this, elem))
@@ -610,12 +495,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                         justify_v: true,
                     };
                 }
-                // The severance mask is deliberately **not** reset on a re-point — true for
-                // the region side too (`script::font_block`'s `SetFontObject`): the real "stop
-                // inheriting this property" signal is a CLEARED bit in the inheritMask
-                // (`FONTINSTANCE+0x2c`), cleared by each local setter and never restored — so a
-                // property this element set for itself stays severed across a later
-                // `SetFontObject`. The two sides of one law must not disagree.
+                // A re-point keeps the severance mask, as on a region: each local setter clears
+                // its bit of the inherit mask (`FONTINSTANCE+0x2c`) for good.
                 ef.font_object = name;
             })
         })?,
@@ -641,9 +522,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── 2/3 · the face ──────────────────────────────────────────────────────────────────────
-    // `SetFont([element,] file, height [, flags])` → the NUMBER 1, or nil on an empty path (the
-    // load-failure probe shape); the argument gate is the shared `0x79f210` entry, so a numeric
-    // string is accepted for either and anything else raises `0x87c69c`'s usage string.
+    // SetFont([element,] file, height [, flags]) returns 1, or nil on an empty path; the shared
+    // gate (`0x79f210`) takes numeric strings and raises `0x87c69c`'s usage line on anything else.
     m.set(
         "SetFont",
         lua.create_function(|lua, (this, mut rest): (Table, MultiValue)| {
@@ -663,8 +543,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 ef.font_height = Some(height);
                 ef.explicit.height = true;
                 if let Some(f) = flags {
-                    // The **Lua** flags spelling ("OUTLINE"/"THICKOUTLINE"), a different
-                    // vocabulary from the XML `outline=` attribute — see [`Outline::flags`].
+                    // The Lua flags spelling, not XML's `outline=` ([`Outline::flags`]).
                     ef.outline = Outline::flags(&f);
                     ef.explicit.outline = true;
                 }
@@ -672,7 +551,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(if ok { Value::Number(1.0) } else { Value::Nil })
         })?,
     )?;
-    // `GetFont([element])` → 3 values: path, height, flags string (`""`, never nil).
+    // GetFont([element]): path, height and a flags string, `""` rather than nil.
     m.set(
         "GetFont",
         lua.create_function(|lua, (this, mut rest): (Table, MultiValue)| {
@@ -710,8 +589,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── 6..9 · the shadow ───────────────────────────────────────────────────────────────────
-    // `GetShadowColor` returns **four** values (`0x79f9b3 mov eax,0x4`), `GetShadowOffset` two.
-    // Either half may be set before the other, so each starts from whatever is already there.
+    // `GetShadowColor` returns four values (`0x79f9b3`), `GetShadowOffset` two; each setter keeps
+    // the other half.
     m.set(
         "SetShadowColor",
         lua.create_function(|lua, (this, mut rest): (Table, MultiValue)| {
@@ -734,8 +613,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok((c[0], c[1], c[2], c[3]))
         })?,
     )?;
-    // Both arguments are required — the shared impl raises `Usage: %s:SetShadowOffset(x, y)`
-    // (`0x87c6e8`) rather than defaulting the missing one.
+    // Both arguments are required: the shared code raises its usage line (`0x87c6e8`).
     m.set(
         "SetShadowOffset",
         lua.create_function(|lua, (this, mut rest): (Table, MultiValue)| {
@@ -764,10 +642,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── 10/11 · spacing ─────────────────────────────────────────────────────────────────────
-    // `SetSpacing([element,] n)` — `0x772240` clamps a negative argument to 0 before storing
-    // (`0x772246 fcomp [0x7ffd74 = 0.0]`). This is the ONE way to open a gap between blocks: the
-    // ctor default is 0, so out of the box they stack perfectly flush, with no per-element
-    // constant, no half-line and no margin anywhere.
+    // SetSpacing([element,] n) clamps a negative to 0 (`0x772240`, `0x772246`); it is the only gap
+    // between blocks, which stack flush at the ctor default of 0.
     m.set(
         "SetSpacing",
         lua.create_function(|lua, (this, mut rest): (Table, MultiValue)| {
@@ -785,13 +661,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── 12..15 · justification ──────────────────────────────────────────────────────────────
-    // Both resolve through the same `0x811ad0` table as `align`, masked `&7` / `&0x38`, so a
-    // cross-axis token CLEARS its axis and a non-token raises (see [`crate::justify`]).
-    //
-    // **`SetJustifyH` is inert for rendered text**, and that is the byte law rather than a gap:
-    // it writes the element font's justify, which `0x78adb0` overwrites on every block it builds
-    // with the tag's own `align`. It is installed because the table has it and `GetJustifyH` must
-    // answer what was stored.
+    // Both parse through `align`'s table (`0x811ad0`), masked `&7` or `&0x38` ([`crate::justify`]).
+    // `SetJustifyH` never shows: `0x78adb0` overwrites it with each block's `align`.
     m.set(
         "SetJustifyH",
         lua.create_function(|lua, (this, mut rest): (Table, MultiValue)| {
@@ -833,15 +704,14 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ── 16..18 · the three with NO element argument ─────────────────────────────────────────
-    // `SetText(s)` → 0 values (`0x796a90` discards the shared implementation's `usedMarkup`).
-    // A nil argument reaches `lua_tostring` as NULL; an empty string is the closest thing to that
-    // this engine can hand a parser, and it takes the same fallback route a NULL would.
+    // ── 16..18 · the three without an element argument ──────────────────────────────────────
+    // SetText(s) returns nothing (`0x796a90` drops `usedMarkup`); nil parses as an empty string,
+    // which takes the fallback a NULL takes.
     m.set(
         "SetText",
         lua.create_function(|lua, (this, text): (Table, Value)| {
             let raw = match &text {
-                // Bytes, lossily — never a raise (2138).
+                // Bytes, lossily; never a raise.
                 Value::String(s) => s.to_string_lossy(),
                 Value::Number(_) | Value::Integer(_) => super::object::as_f32(&text).to_string(),
                 _ => String::new(),
@@ -852,8 +722,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // `SetHyperlinkFormat(s)` raises `Usage: %s:SetHyperlinkFormat("format")` (`0x87bb40`) if
-    // argument 2 is not a string (`0x796bcc`–`0x796c29`). It takes effect on the NEXT parse.
+    // SetHyperlinkFormat(s) raises its usage line (`0x87bb40`) on a non-string
+    // (`0x796bcc`-`0x796c29`); it applies from the next parse.
     m.set(
         "SetHyperlinkFormat",
         lua.create_function(|lua, (this, fmt): (Table, Value)| {
@@ -886,8 +756,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// `(r, g, b [, a])` off the post-element argument list — alpha `lua_isnumber`-gated with the
-/// default `1.0`, r/g/b required, exactly as the shared colour setters take them.
+/// `(r, g, b [, a])` after the element argument, as the shared colour setters take it: r, g and b
+/// required, alpha 1 unless a number.
 fn rgba(lua: &Lua, rest: &MultiValue) -> mlua::Result<[f32; 4]> {
     let r = f32::from_lua(arg(rest, 0), lua)?;
     let g = f32::from_lua(arg(rest, 1), lua)?;
@@ -899,5 +769,5 @@ fn rgba(lua: &Lua, rest: &MultiValue) -> mlua::Result<[f32; 4]> {
     Ok([r, g, b, a])
 }
 
-/// The per-frame state store — `Model`'s side of this module (see [`SimpleHtmlState`]).
+/// The per-frame [`SimpleHtmlState`] store `Model` holds.
 pub(crate) type SimpleHtmlStates = HashMap<FrameHandle, SimpleHtmlState>;
diff --git a/crates/benilla-ui/src/script/simplehtml/parse.rs b/crates/benilla-ui/src/script/simplehtml/parse.rs
index c79ddb73..236df3dd 100644
--- a/crates/benilla-ui/src/script/simplehtml/parse.rs
+++ b/crates/benilla-ui/src/script/simplehtml/parse.rs
@@ -1,71 +1,42 @@
-//! The **markup parse** half of `CSimpleHTML::SetText` — `&str` in, a block list out.
+//! The markup parse of `CSimpleHTML::SetText`: a string in, a block list out, with no Lua or model.
 //!
-//! Pure: no Lua, no model, no arena. Everything here is one transcription of the reference's
-//! `SetText`/`WALK_BODY`/`ADD_PARAGRAPH` algorithm and the byte derivations behind it; [`super`]
-//! does the materialization (regions, anchors, fonts).
-//!
-//! ## The one fact everything else follows from
-//!
-//! **The markup is parsed as strict XML, not as lenient HTML.** `0x78a422` calls
-//! `XMLTree::Parse 0x6f2a30`, which is embedded **expat 1.95.5** (version string `0x882094`,
-//! wrapper `__FILE__` `…\FrameXML\XMLTree.cpp` at `0x8715ec`). So an unclosed `<BR>`, a `</p>`
-//! closing a `<P>` (XML open/close matching is case-SENSITIVE, even though *SimpleHTML's own*
-//! name compares are not — `SStrCmpI 0x414310`), a bare `&`, a non-predefined entity such
-//! as `&nbsp;`, a duplicate attribute, or any non-whitespace after `</HTML>` all fail the parse
-//! outright, and the widget renders the **raw** string instead (`0x78a501`).
-//!
-//! [`roxmltree`] stands in for expat here, and it is the right stand-in rather than a convenient
-//! one: it is a well-formedness-checking XML parser with exactly the five XML predefined entities
-//! plus numeric character references, and it was checked case by case against the reference's parse
-//! outcomes before this module was written — plain prose, a bare `&`, a bare `<`, an unclosed
-//! `<BR>`, a case-mismatched close tag, `&nbsp;`, junk after the root and a duplicate attribute are
-//! each an `Err` (expat codes 4/4/4/7/7/11/9/8), while trailing whitespace after `</HTML>`, a
-//! leading newline, numeric refs, comments and CDATA are each an `Ok`. Its interleaved text/element
-//! child order also hands us the `<A>`/`<BR>` splice positions directly, so none of the reference's
-//! `offsetInParentText` arithmetic (`XMLTree` node `+0x18`) is needed.
-//!
-//! **The one behavioural difference found**, stated rather than hidden: roxmltree refuses a
-//! document carrying an internal DTD subset (`XML with DTD detected`) where expat 1.95.5 may
-//! accept one and honour its `<!ENTITY>` declarations. Expat's build options are unread for
-//! exactly this case, and no `page_text` body carries a DOCTYPE; for us a DOCTYPE simply takes
-//! the plain-text fallback, which is the same place a rejected parse lands.
+//! The markup is strict XML: `0x78a422` calls `XMLTree::Parse` (`0x6f2a30`), an embedded expat
+//! 1.95.5 (`0x882094`). An unclosed `<BR>`, a `</p>` closing a `<P>` (XML matching is
+//! case-sensitive, SimpleHTML's own name compares are not), a bare `&`, an entity such as `&nbsp;`,
+//! a duplicate attribute or text after `</HTML>` fails the parse, and the widget renders the raw
+//! string (`0x78a501`). [`roxmltree`] gives expat's outcome on each of those and on what passes
+//! (trailing whitespace, numeric references, comments, CDATA), and its interleaved children give
+//! the `<A>` and `<BR>` splice points directly. A DOCTYPE takes the fallback here; whether the
+//! reference's expat accepts one is untraced, and no `page_text` body carries one.
 
 use crate::justify;
 
-/// The four block elements, indexed as the client indexes `elementFont[4]` at `+0x350`:
-/// `0 = P, 1 = H1, 2 = H2, 3 = H3` (`0x789e3e` creates them in that order, `0x78ae29` reads them,
-/// and the Lua element-name resolver `0x795d80` answers the same four numbers).
+/// The four block elements in the client's `elementFont` order (`+0x350`), the numbering the ctor
+/// (`0x789e3e`), the block builder (`0x78ae29`) and the Lua resolver (`0x795d80`) share.
 pub(crate) const ELEMENT_NAMES: [&str; 4] = ["P", "H1", "H2", "H3"];
 
-/// `P` — the element every unqualified path addresses: the plain-text fallback's block (`0x78a503
-/// push 0`), the `<BR/>` block, and the element a missing or unrecognised Lua element-name
-/// argument resolves to (`0x795e50`).
+/// `P`: the element of the fallback block (`0x78a503`), of `<BR/>`, and of a Lua call without a
+/// known element name (`0x795e50`).
 pub(crate) const ELEM_P: usize = 0;
 
-/// The `align` default, pre-loaded into the local before the attribute is even looked at
-/// (`0x78a7c8 mov [ebp-0xc],1` for a block, `0x78ab59 mov [ebp-8],1` for an `<IMG>`): **LEFT**,
-/// and emphatically *not* the `CSimpleFontString` ctor's CENTER, which `0x78ae78` overwrites on
-/// every block it builds.
+/// The `align` default, set before the attribute is read (`0x78a7c8` for a block, `0x78ab59` for
+/// an `<IMG>`): LEFT, which `0x78ae78` writes over the FontString ctor's CENTER.
 pub(crate) const ALIGN_LEFT: u32 = 0x01;
-/// `align="center"` — the value `0x6f1990` writes from the shared enum table `.rdata 0x811ad0`.
+/// `align="center"`: the value `0x6f1990` writes from the shared enum table (`0x811ad0`).
 pub(crate) const ALIGN_CENTER: u32 = 0x02;
 /// `align="right"`.
 pub(crate) const ALIGN_RIGHT: u32 = 0x04;
 
-/// The ctor default of `hyperlinkFormat` (`+0x360`, string `0x87a838`, installed by
-/// `0x789ea7`→`0x78a540`): `<A href="X">Y</A>` becomes `|HX|hY|h`, which the font engine then
-/// parses as an ordinary hyperlink (`SetText 0x771d80` never touches `+0x120` — nothing disables
-/// `|H` on a `CSimpleFontString`).
+/// The ctor's `hyperlinkFormat` (`0x87a838`, set at `0x789ea7` and `0x78a540`): `<A href="X">Y</A>`
+/// becomes `|HX|hY|h`, a hyperlink to the FontString, which never disables `|H` (`0x771d80`).
 pub(crate) const DEFAULT_HYPERLINK_FORMAT: &str = "|H%s|h%s|h";
 
-/// One block the walk produced — the arguments of `AddTextBlock 0x78adb0` / `AddImage 0x78ab40`,
-/// in the order the BODY walker emitted them.
+/// One block, the arguments of `AddTextBlock` (`0x78adb0`) or `AddImage` (`0x78ab40`).
 #[derive(Clone, Debug, PartialEq)]
 pub(crate) enum Block {
     /// A text block: one `CSimpleFontString`, `SetWidth(frame width)`, no height.
     Text {
-        /// The already-spliced, already-collapsed string handed to `SetText` — except on the
-        /// plain-text fallback path, which hands over the **raw** input (`0x78a501`).
+        /// The spliced, collapsed string, or the raw input on the fallback path (`0x78a501`).
         text: String,
         /// The `elementFont[]` index this block draws with, before the empty-path fallback.
         elem: usize,
@@ -74,19 +45,17 @@ pub(crate) enum Block {
     },
     /// An `<IMG>`: one `CSimpleTexture`, sized by `width`/`height` and anchored by `align`.
     Image {
-        /// `src=`, used **verbatim** as a texture path — no prefix, no extension fix-up, no
-        /// validation in this TU (`0x78ad02`).
+        /// `src=`, used verbatim as the texture path (`0x78ad02`).
         src: Option<String>,
-        /// `width=`/`height=` in logical UI pixels (`0x78ab9e`/`0x78abd6` — the same units as
-        /// `<AbsDimension>`); `0` when the attribute is absent.
+        /// `width=` and `height=` in UI units, as `<AbsDimension>` (`0x78ab9e`, `0x78abd6`); 0
+        /// when absent.
         width: f32,
         height: f32,
         /// The `align` bits; selects which corner anchors to the previous block.
         align: u32,
-        /// The **separate** float byte `[ebp-1]` (zeroed at `0x78ab55`): a floated image reserves
-        /// no height in the flow, so the following text overlaps it. Set only inside the
-        /// attribute-present branch, which is why a bare `<IMG src=…/>` and
-        /// `<IMG align="left" src=…/>` anchor identically and flow differently.
+        /// Reserves no height, so the text after overlaps it (`0x78ab55`). Set only when `align`
+        /// is present, so `<IMG src=…/>` and `<IMG align="left" src=…/>` anchor alike but flow
+        /// differently.
         floated: bool,
     },
 }
@@ -94,36 +63,29 @@ pub(crate) enum Block {
 /// The outcome of one `SetText` parse.
 #[derive(Clone, Debug, PartialEq)]
 pub(crate) struct Parse {
-    /// The blocks to build, in order.
     pub(crate) blocks: Vec<Block>,
-    /// `SetText`'s own return value in `al` (`0x78a519`): whether the markup path ran. The Lua
-    /// shim `0x796a90` discards it; we keep it because it is exactly "did this render as markup
-    /// or as raw text", which is the thing a reader of a `page_text` body wants to know.
+    /// `SetText`'s return (`0x78a519`): whether the markup path ran. The Lua shim (`0x796a90`)
+    /// drops it.
     pub(crate) used_markup: bool,
-    /// The console lines the error sink received (`"Frame %s: Unknown element type: %s"` and its
-    /// two `(expected …)` variants), already formatted with the frame's name.
+    /// The console lines the error sink received, formatted with the frame's name.
     pub(crate) errors: Vec<String>,
 }
 
-/// `CSimpleHTML::SetText 0x78a3a0`'s parse half — its `WALK_BODY`/`ADD_PARAGRAPH` algorithm.
-///
-/// `frame` is the widget's name, the `%s` of the error strings. `hyperlink_format` is
-/// `+0x360`'s current value, used by the `<A>` splice.
+/// The parse half of `SetText` (`0x78a3a0`). `frame` names the widget in error lines;
+/// `hyperlink_format` is the current `+0x360`.
 pub(crate) fn parse_markup(raw: &str, frame: &str, hyperlink_format: &str) -> Parse {
     let mut out = Parse {
         blocks: Vec::new(),
         used_markup: false,
         errors: Vec::new(),
     };
-    // `usedMarkup` is `[ebp+0xf]`, zeroed at `0x78a415` and raised at exactly ONE site,
-    // `0x78a4b6` — immediately BEFORE the BODY walker runs. That ordering is the whole reason an
-    // empty `<BODY/>` renders nothing at all rather than falling back to the raw string.
+    // `usedMarkup` is raised before the BODY walk (`0x78a4b6`), so an empty `<BODY/>` renders
+    // nothing rather than the raw string.
     if let Ok(doc) = roxmltree::Document::parse(raw) {
         let root = doc.root_element();
         if root.tag_name().name().eq_ignore_ascii_case("HTML") {
-            // Only the FIRST `BODY` is walked: `0x78a4ba call 0x78a660` is followed by
-            // `0x78a4bf jmp 0x78a4ef`, which leaves the sibling loop — a second `<BODY>` is never
-            // visited and never even errors.
+            // Only the first `BODY` is walked, and a second never errors (`0x78a4bf` leaves the
+            // loop after `0x78a660` returns).
             for child in root.children().filter(roxmltree::Node::is_element) {
                 if child.tag_name().name().eq_ignore_ascii_case("BODY") {
                     out.used_markup = true;
@@ -143,12 +105,9 @@ pub(crate) fn parse_markup(raw: &str, frame: &str, hyperlink_format: &str) -> Pa
         }
     }
     if !out.used_markup {
-        // The three routes here — a failed parse, a non-`HTML` root, an `HTML` with no `BODY`
-        // child — all land on `0x78a501`: the ORIGINAL, unmodified string as ONE block, element
-        // `P`, justifyH LEFT. **Without the whitespace collapse**, because the collapse lives in
-        // the paragraph builder `0x78a7b0` which this path never enters — so embedded `\n` stay
-        // real line breaks. Stock `ItemTextFrame.lua` depends on exactly that, padding its page
-        // with `SetText("\n" .. ItemTextGetText() .. "\n")`.
+        // A failed parse, a non-`HTML` root or no `BODY` all land on `0x78a501`: the raw string
+        // as one LEFT `P` block, without the collapse, as `0x78a7b0` is never entered, so its `\n`
+        // stay line breaks, which stock `ItemTextFrame.lua` relies on.
         out.blocks.push(Block::Text {
             text: raw.to_string(),
             elem: ELEM_P,
@@ -158,11 +117,8 @@ pub(crate) fn parse_markup(raw: &str, frame: &str, hyperlink_format: &str) -> Pa
     out
 }
 
-/// The BODY walker `0x78a660` — dispatch by child element name, case-insensitively.
-///
-/// **`BODY`'s own character data is DROPPED**: the walker reads only `firstChild`/`nextSibling`
-/// and nothing ever reads `body->+0x0c`. The inter-tag newlines of a typical `page_text` body are
-/// exactly that, which is why they contribute no blank lines.
+/// The BODY walker (`0x78a660`), by child name, case-insensitively. BODY's own text is dropped, as
+/// nothing reads it (`+0x0c`), so the newlines between a `page_text` body's tags add nothing.
 fn walk_body(body: roxmltree::Node, frame: &str, hyperlink_format: &str, out: &mut Parse) {
     for node in body.children().filter(roxmltree::Node::is_element) {
         let tag = node.tag_name().name();
@@ -173,10 +129,7 @@ fn walk_body(body: roxmltree::Node, frame: &str, hyperlink_format: &str, out: &m
             let block = paragraph(node, elem, frame, hyperlink_format, &mut out.errors);
             out.blocks.push(block);
         } else if tag.eq_ignore_ascii_case("BR") {
-            // `0x78a726` → `0x78adb0("\n" @0x835144, elem 0, align 1)`: a block of its own whose
-            // text is the single byte `\n`. The height kernel `0x5c2070` takes the class-2 arm
-            // once and exits with `lines == 1`, so it is **exactly one blank line** — not two,
-            // not a paragraph gap.
+            // A `\n` block of its own (`0x78a726`), one blank line tall (`0x5c2070`).
             out.blocks.push(Block::Text {
                 text: "\n".to_string(),
                 elem: ELEM_P,
@@ -185,16 +138,14 @@ fn walk_body(body: roxmltree::Node, frame: &str, hyperlink_format: &str, out: &m
         } else if tag.eq_ignore_ascii_case("IMG") {
             out.blocks.push(image(node));
         } else {
-            // `0x78a762`–`0x78a793`: the name is formatted into `"Frame %s: Unknown element type:
-            // %s"` (`0x87a95c`), pushed through the sink, and the node contributes NOTHING; the
-            // sibling walk continues at `0x78a796`.
+            // Logged (`0x87a95c`) and skipped; the walk goes on (`0x78a762`-`0x78a796`).
             out.errors
                 .push(format!("Frame {frame}: Unknown element type: {tag}"));
         }
     }
 }
 
-/// `0x78a7b0(node, elem, sink)` — one `<P>`/`<H1>`/`<H2>`/`<H3>` into one block.
+/// One `<P>`, `<H1>`, `<H2>` or `<H3>` into one block (`0x78a7b0`).
 fn paragraph(
     node: roxmltree::Node,
     elem: usize,
@@ -203,12 +154,8 @@ fn paragraph(
     errors: &mut Vec<String>,
 ) -> Block {
     let align = align_of(node);
-    // `0x78a7b0` does this in one pass. The reference seeds the buffer with the node's whole
-    // accumulated character data (expat concatenates the text either side of an inline child
-    // into the SAME `+0x0c`) and then splices each child in at its recorded `+0x18` offset plus
-    // the running `extra`. roxmltree hands us text and elements interleaved in document order
-    // instead, so appending as we walk lands every splice exactly where the tag was, with no
-    // offset arithmetic to get wrong.
+    // The reference splices each inline child into the node's text at its recorded offset
+    // (`+0x18`); appending roxmltree's interleaved children in order puts each at the same place.
     let mut buf = String::new();
     for child in node.children() {
         if child.is_text() {
@@ -216,27 +163,24 @@ fn paragraph(
             continue;
         }
         if !child.is_element() {
-            // A comment or PI: expat never delivers it as character data either.
+            // A comment or PI, which expat does not deliver as text either.
             continue;
         }
         let tag = child.tag_name().name();
         if tag.eq_ignore_ascii_case("BR") {
-            // `0x78a86b` appends the two literal bytes `|n` (`0x87a9a0`) — a real line break
-            // WITHIN this block, not a block of its own, and `extra += 2`.
+            // An inline `<BR/>` is `|n`, a break inside this block (`0x78a86b`, `0x87a9a0`).
             buf.push_str("|n");
         } else if tag.eq_ignore_ascii_case("A") {
-            // `0x78a8f0` requires **both** a non-empty `href` and non-empty inner text
-            // (`0x78a914`–`0x78a922`); otherwise the whole `<A>` contributes nothing at all.
+            // `<A>` needs a non-empty `href` and text, or adds nothing (`0x78a8f0`,
+            // `0x78a914`-`0x78a922`).
             let href = attr_ci(child, "href").unwrap_or("");
             let inner = direct_text(child);
             if !href.is_empty() && !inner.is_empty() {
                 buf.push_str(&sprintf_two(hyperlink_format, href, &inner));
             }
         } else {
-            // `0x78a9f9`–`0x78aa2c`: the same message and the same outcome as at BODY level. The
-            // child's own character data went into the CHILD's `+0x0c`, never the parent's, so
-            // the text of an unknown inline element is silently lost while the text either side
-            // of it is kept — which is what dropping the node here reproduces.
+            // Logged as at BODY level (`0x78a9f9`-`0x78aa2c`); its own text, which expat keeps on
+            // the child, is lost and the text around it kept.
             errors.push(format!("Frame {frame}: Unknown element type: {tag}"));
         }
     }
@@ -247,17 +191,14 @@ fn paragraph(
     }
 }
 
-/// `0x78ab40(node, sink)` — one `<IMG>`.
+/// One `<IMG>` (`0x78ab40`).
 fn image(node: roxmltree::Node) -> Block {
     let mut align = ALIGN_LEFT;
     let mut floated = false;
-    // The float byte `[ebp-1]` is zeroed at `0x78ab55`
-    // and set only INSIDE the attribute-present branch (`0x78ab67`/`0x78ab6c` both skip past it),
-    // so it is a property of *the attribute being written*, not of the value:
-    //
-    //   absent / empty  → align 1, floated 0        `left`/`right` → 1 / 4, floated 1
-    //   `center`        → 2, floated 0              `top`/`middle`/`bottom` → 8/16/32, floated 0
-    //   anything else   → align stays 1, floated **1** (`0x6f1990` left the local at its default)
+    // Floating is decided only when `align` is present and non-empty (`0x78ab55`-`0x78ab6c`):
+    //   absent or empty: align 1, not floated     `left`, `right`: 1, 4, floated
+    //   `center`: 2, not floated                  `top`, `middle`, `bottom`: 8, 16, 32, not floated
+    //   anything else: align stays 1, floated (`0x6f1990` leaves the default)
     if let Some(v) = attr_ci(node, "align").filter(|v| !v.is_empty()) {
         if let Some(bits) = justify::parse_bits(v) {
             align = bits;
@@ -273,13 +214,9 @@ fn image(node: roxmltree::Node) -> Block {
     }
 }
 
-/// `align` on a `<P>`/`<H1>`/`<H2>`/`<H3>` (`0x78a7cf`): the shared 6-entry enum at
-/// `.rdata 0x811ad0`, which [`justify::parse_bits`] already owns one transcription of.
-///
-/// `0x6f1990` writes `*out` only on a hit, and the local was pre-loaded with `1`, so an **absent,
-/// empty or unrecognised** `align` leaves the block at LEFT. `top`/`middle`/`bottom` are accepted
-/// and yield 8/16/32, which mask to `& 7 == 0` — a block with no justifyH bit set at all. That is
-/// a degenerate state the binary really reaches, not a rejection.
+/// A block's `align` (`0x78a7cf`) through the shared enum (`0x811ad0`, [`justify::parse_bits`]):
+/// absent, empty or unknown stays LEFT, as `0x6f1990` writes only on a hit. `top`, `middle` and
+/// `bottom` give 8, 16 and 32, which leave no justifyH bit, in the reference too.
 fn align_of(node: roxmltree::Node) -> u32 {
     attr_ci(node, "align")
         .filter(|v| !v.is_empty())
@@ -287,18 +224,16 @@ fn align_of(node: roxmltree::Node) -> u32 {
         .unwrap_or(ALIGN_LEFT)
 }
 
-/// Attribute lookup, **case-insensitively** — every attribute-name compare in this engine goes
-/// through `0x64a4c0` → `SStrCmpI 0x414310`, so `ALIGN`/`Align`/`align` are one attribute.
-/// roxmltree's own `Node::attribute` is case-sensitive, which is why this scan exists.
+/// Case-insensitive attribute lookup, as the reference compares names (`0x64a4c0`, `SStrCmpI`
+/// `0x414310`); roxmltree's own lookup is case-sensitive.
 fn attr_ci<'a>(node: roxmltree::Node<'a, '_>, name: &str) -> Option<&'a str> {
     node.attributes()
         .find(|a| a.name().eq_ignore_ascii_case(name))
         .map(|a| a.value())
 }
 
-/// An element's own direct character data, concatenated in document order — the `<A>`'s inner
-/// text. roxmltree's `Node::text` answers only the FIRST text child, which a comment or an entity
-/// boundary is enough to split.
+/// An element's direct text, all of it: roxmltree's `Node::text` gives only the first text child,
+/// which a comment splits.
 fn direct_text(node: roxmltree::Node) -> String {
     node.children()
         .filter(roxmltree::Node::is_text)
@@ -306,14 +241,9 @@ fn direct_text(node: roxmltree::Node) -> String {
         .collect()
 }
 
-/// `SStrPrintf(tmp, len, hyperlinkFormat, href, innerText)` (`0x78a97b` → `0x64a7f0`) — a C
-/// `printf` with exactly two arguments, both strings.
-///
-/// Only `%s` and `%%` are honoured; any other spec is copied through verbatim rather than
-/// consuming an argument. A real `printf` given `%d` and a `char*` would read the pointer as an
-/// integer, which is not behaviour worth reproducing, and `SetHyperlinkFormat` is a
-/// player-reachable string — the ctor default `"|H%s|h%s|h"` and every format an addon writes are
-/// two-`%s` templates.
+/// `SStrPrintf` of the format with `href` and the inner text (`0x78a97b`, `0x64a7f0`). Deviation:
+/// only `%s` and `%%` are expanded and other specs copied, because the real `printf` would read the
+/// string pointers as other types.
 fn sprintf_two(fmt: &str, a: &str, b: &str) -> String {
     let mut out = String::with_capacity(fmt.len() + a.len() + b.len());
     let mut used = 0usize;
@@ -343,10 +273,8 @@ fn sprintf_two(fmt: &str, a: &str, b: &str) -> String {
     out
 }
 
-/// C's `atof` (`0x64aaa0`), as `<IMG width=>`/`height=` reach it: leading whitespace skipped, the
-/// longest valid numeric prefix parsed, **0 on no parse at all** — `"12px"` is 12, `"px"` is 0.
-/// Rust's `str::parse` rejects a trailing suffix outright, which would turn a sloppy but working
-/// `width="100 "` into a zero-width image.
+/// C's `atof` (`0x64aaa0`) for `width=` and `height=`: the longest numeric prefix after leading
+/// whitespace, 0 when there is none, so `"12px"` is 12.
 fn atof(s: &str) -> f32 {
     let b = s.as_bytes();
     let mut i = 0;
@@ -366,7 +294,7 @@ fn atof(s: &str) -> f32 {
             i += 1;
         }
     }
-    // An exponent counts only when it is complete — `"1e"` is 1, matching strtod's own backtrack.
+    // An exponent counts only when complete: `"1e"` is 1, as `strtod` backtracks.
     if i < b.len() && (b[i] | 0x20) == b'e' {
         let mut j = i + 1;
         if j < b.len() && (b[j] == b'+' || b[j] == b'-') {
@@ -382,31 +310,16 @@ fn atof(s: &str) -> f32 {
     s[start..i].parse::<f32>().unwrap_or(0.0)
 }
 
-/// The HTML-style whitespace collapse — `0x78a8af`–`0x78aa87`, a three-arm dispatch through
-/// the jump table at `.text 0x78aab8` with the byte remap at `.text 0x78aac4`.
-///
-/// | arm | characters | behaviour |
-/// |---|---|---|
-/// | 0 `0x78aa34` | `\t` `\n` `\r` ` ` | suppress-leading → drop; a space already pending → drop; else emit one `0x20` and set pending |
-/// | 1 `0x78aa46` | `\|` followed by `n` | un-emit a pending space (`0x78aa54 dec eax`), clear pending, emit `\|n`, set suppress-leading, skip both bytes |
-/// | 2 `0x78aa66` | everything else, `\|` **not** followed by `n` included | clear suppress-leading and pending, emit the byte verbatim |
-///
-/// Tail `0x78aa7b` removes a trailing pending space. Net: **leading and trailing whitespace
-/// trimmed, every internal run of tabs/newlines/CRs/spaces collapsed to one space, and a space
-/// immediately before a `|n` removed** — exactly HTML's rule.
-///
-/// It is byte-wise and can still never split a UTF-8 sequence: the index is computed with the
-/// **signed** widening `0x78a8c5 movsx edi,bl`, so every byte `>= 0x80` goes negative and the
-/// unsigned `cmp edi,0x73; ja` sends it to arm 2 — lead and continuation bytes alike are copied
-/// verbatim. Operating on `&[u8]` here reproduces that exactly, and the result is valid UTF-8 by
-/// construction because only ASCII whitespace is ever dropped.
-///
-/// **This applies to markup blocks only.** The plain-text path (`0x78a501`) bypasses it entirely.
+/// The whitespace collapse of markup blocks (`0x78a8af`-`0x78aa87`; the fallback at `0x78a501`
+/// skips it): leading and trailing whitespace dropped, each run of tabs, newlines, CRs and spaces
+/// made one space, and whitespace on either side of `|n` removed. Its arms: whitespace
+/// (`0x78aa34`), `|n` (`0x78aa46`, `0x78aa54`), any other byte (`0x78aa66`), and a tail that drops
+/// a pending space (`0x78aa7b`). A byte from `0x80` up widens negative (`0x78a8c5`) and takes the
+/// verbatim arm, so UTF-8 is never split.
 fn collapse(buf: &str) -> String {
     let src = buf.as_bytes();
     let mut out: Vec<u8> = Vec::with_capacity(src.len());
-    // `dl` — "a space is already pending" — and `[ebp+0xb]`, "suppress leading whitespace",
-    // initialised to **1** so a block never starts with a space.
+    // Suppression starts on, so a block never starts with a space.
     let mut pending_space = false;
     let mut suppress_leading = true;
     let mut i = 0;
@@ -459,14 +372,13 @@ mod tests {
     fn collapse_is_htmls_rule() {
         assert_eq!(collapse("  a \t\n b  "), "a b");
         assert_eq!(collapse("a \n\n b"), "a b");
-        // A space immediately before a `|n` is removed; whitespace right after one is suppressed.
+        // A space right before `|n` is removed; whitespace right after one is suppressed.
         assert_eq!(collapse("a |n b"), "a|nb");
-        // A `|` not followed by `n` is verbatim — colour spans and hyperlinks survive.
+        // A `|` not before `n` is verbatim, so colour codes survive.
         assert_eq!(
             collapse("  |cffff0000red|r  text  "),
             "|cffff0000red|r text"
         );
-        // Multi-byte sequences are never split (the signed-widening arm-2 fall-through).
         assert_eq!(collapse("  héllo  wörld "), "héllo wörld");
         assert_eq!(collapse("   "), "");
     }
@@ -531,7 +443,7 @@ mod tests {
 
     #[test]
     fn an_empty_body_renders_nothing_at_all() {
-        // `usedMarkup` is raised BEFORE the walker runs (`0x78a4b6`), so this does NOT fall back.
+        // `usedMarkup` rises before the walk (`0x78a4b6`), so this does not fall back.
         let p = parse_markup("<HTML><BODY/></HTML>", "F", DEFAULT_HYPERLINK_FORMAT);
         assert!(p.used_markup);
         assert!(p.blocks.is_empty());
@@ -671,8 +583,7 @@ mod tests {
         }
     }
 
-    /// The stock `ItemTextFrame`'s `page_text` shape, end to end: an `<H1>` title, a `<BR/>`, and
-    /// centred paragraphs, with the body's own inter-tag newlines contributing nothing.
+    /// A stock `page_text` body: an `<H1>` title, `<BR/>`s and centred paragraphs.
     #[test]
     fn the_page_text_shape_walks_to_the_block_list_a_reader_would_draw() {
         let p = parse_markup(
@@ -704,10 +615,8 @@ mod tests {
         assert!(p.errors.is_empty());
     }
 
-    /// The signed-page consequence: `ItemTextFrame.lua` appends `From: <creator>` **after**
-    /// `</HTML>`, which is expat error 9 (`0x881fec`) — so a signed HTML page renders as raw
-    /// markup on the reference client too. Our fallback must reach the same place rather than
-    /// "fixing" it.
+    /// Stock `ItemTextFrame.lua` appends `From: <creator>` after `</HTML>`, expat error 9
+    /// (`0x881fec`), so a signed page renders as raw markup on the reference too.
     #[test]
     fn a_signed_html_page_falls_back_exactly_as_the_reference_does() {
         let raw = "\n<HTML><BODY><P>The letter body.</P></BODY></HTML>\n\nFrom:\nMankrik\n\n";
diff --git a/crates/benilla-ui/src/script/skills.rs b/crates/benilla-ui/src/script/skills.rs
index e5eba256..9f639f6a 100644
--- a/crates/benilla-ui/src/script/skills.rs
+++ b/crates/benilla-ui/src/script/skills.rs
@@ -1,78 +1,16 @@
-//! The skills-pane bindings (decision 0437 phase 4) — the Era-shaped `SkillFrame` surface driving
-//! a faithful port of the real 1.12 Skills tab (extracted from `interface.MPQ`: FrameXML
-//! `SkillFrame.{xml,lua}`). Unlike [`super::tradeskill`]'s deliberately FLAT v1 recipe list, this
-//! pane needs the trainer's own GROUP/TREE machinery ([`super::trainer`], decision 0247): the app
-//! pushes a flat, unordered snapshot ([`UiScript::set_skills`] — [`SkillsState::entries`], each
-//! already resolved to name/category by the app from `SkillLine.dbc`/`SkillLineCategory.dbc`), and
-//! the ENGINE groups by category, sorts, and folds — the trainer's synthesized-tree pattern, minus
-//! the state filter (a skill line carries no green/red/gray category) and minus the wire skill-line
-//! id doing double duty as both the row's identity and the group key (here the GROUP key is the
-//! category, the row's identity is the skill id).
+//! The skills-pane bindings behind the stock `SkillFrame`. The app pushes a flat snapshot of known
+//! skill lines, resolved from `SkillLine.dbc` and `SkillLineCategory.dbc`, and the engine groups,
+//! sorts and folds it as the client's list build (`0x4d2cb0`, comparator `0x4d3070`) does: one
+//! header per category, by `category_order` (category id breaks a tie), and within a category the
+//! untrained lines (rank 0) after the trained ones, each by name. A push re-expands every group.
+//! Every Lua index is 1-based into the visible rows, headers plus the entries of expanded groups;
+//! the selection is held by skill id, so it survives a re-push, and selecting a header clears it.
+//! Which lines reach the engine at all is the app's half (`feed_skills`).
 //!
-//! ## The engine grouping law (PINNED at the bytes — decision 1091; the list build `0x4d2cb0` +
-//! its comparator `0x4d3070`. The 0530 follow-up this once carried is closed.)
-//!
-//! Groups ordered by `category_order` ascending (`category_id` breaks a tie, for determinism);
-//! one header row per non-empty group (text = `category_name`); within a group, **untrained lines
-//! (rank 0) sink below trained ones**, then name ascending ([`collate`] — case-insensitive,
-//! raw-byte tie-break; the client's own `stricmp`). Every group starts EXPANDED and is **re-expanded
-//! on every push** ([`UiScript::set_skills`] — the client's own `expandedMask = 0xFFFFFFFF`).
-//! Visible rows are headers always, plus the entries of expanded groups; every index the Lua API
-//! takes/returns is 1-based into that visible list.
-//!
-//! **Which lines reach the engine at all is the app's half** of the same law (`ui_char.rs`'s
-//! `feed_skills`): the client's list build drops a line with no `SkillLine`/`SkillRaceClassInfo`/
-//! `SkillLineCategory` row, one whose `SkillRaceClassInfo.flags` carries `0x2`, and an untrained
-//! one that no flag admits. The engine sorts what survives.
-//!
-//! ## The Era API shape (matched to the real `SkillFrame.lua`, transcribed onto this engine)
-//!
-//! `GetNumSkillLines()` → the visible row count. `GetSkillLineInfo(i)` → the ref's own tuple
-//! (`name, isHeader, isExpanded, skillRank, numTempPoints, skillModifier, skillMaxRank,
-//! isAbandonable, stepCost, rankCost, minLevel, skillCostType, skillDescription`) — **13 values on
-//! a skill row, 12 on a header** (`0x4d3a20` vs `0x4d3768`; a header stops after `skillCostType`
-//! and carries no description slot at all). A header shapes
-//! `(category_name, 1, expanded, 0, 0, 0, 0, nil, nil, nil, 0, 0)`, an entry
-//! `(name, nil, nil, rank, 0, tempBonus, max, abandonable, nil, nil, minLevel, costIndex+1,
-//! description)`, with `rank`/`max` computed by [`displayed_ranks`] — the permanent bonus folded
-//! in, then `max` forced to `1` on a **single-rank** line whatever the server said
-//! ([`SkillEntry::mono`]; the pane's proficiency gate is `skillMaxRank == 1`).
-//!
-//! `numTempPoints` is a **REAL FIELD** (`entry->+0x10`) that this client answers as `0`. The
-//! distinction matters and this comment used to blur it (decision 1919): the field has four writers
-//! in the real client — zeroed per list rebuild (`0x4d2e2e`), incremented by `AddSkillUp`'s worker
-//! (`0x4d345b`), decremented at `0x4d358a`, reset by `CancelSkillUps` (`0x4d35c9`) — and
-//! `SkillFrame.xml:697` wires `AddSkillUp` for real. What is true is a **data-reachability** verdict
-//! about the shipped tables, not a property of the field: the `rankCost or numTempPoints > 0` guard
-//! never opens on 1.12's data, so nothing a player can hold moves it off `0`. Say `0` because the
-//! model carries no temp points, never because the field is fictional — the day we model training
-//! points this is a value to push, not a constant to keep. `stepCost`/`rankCost` are always **nil** —
-//! for DATA reasons, not code ones (`SkillLine.skillCostsID` is 0 in all 123 rows, and the
-//! step-cost gate's flag bits are set on no line a player can hold) — and nil, not `0`, is what
-//! the ref's `if (stepCost)` / `elseif (rankCost or …)` branches read, since `0` is truthy in Lua.
-//! `minLevel` and `skillCostType` are REAL numbers off the `SkillRaceClassInfo` row (visually inert
-//! on this build: every branch they colour is repainted by the normal-skill/proficiency branches
-//! after it). `skillDescription` is REAL (`SkillLine.dbc` col 12 through the app feed — the detail
-//! pane's body text); `isAbandonable` is REAL too ([`SkillEntry::abandonable`], the unlearn
-//! button's gate — and `AbandonSkill(i)` is its outbound half, a VISIBLE index queued out by skill
-//! id for the app's `CMSG_UNLEARN_SKILL`, [`UiScript::take_skill_abandons`]).
-//!
-//! `ExpandSkillHeader(i)`/`CollapseSkillHeader(i)` take a header's VISIBLE index (`0` = all
-//! groups, the trainer's own collapse-all shape). `SetSelectedSkill(i)`/`GetSelectedSkill()` are a
-//! VISIBLE index too, but the engine holds the selection BY SKILL ID internally (the tradeskill's
-//! own by-spell-id persistence pattern, [`super::tradeskill::UiScript::set_trade_skill`]) so it
-//! survives a re-push that reorders or regroups; selecting a header (or an out-of-range index)
-//! clears it. `GetAdjustedSkillPoints()` is a vestigial 1.12 leftover the ref reads; it always
-//! returns `0` — there is no training-point economy behind a skill line in this client.
-//!
-//! `CancelSkillUps()` is bound (the page's Close button calls it, 1956): the temp-point reset
-//! over a table this model keeps empty.
-//!
-//! The ref Lua's other globals (`SkillBar_OnClick`'s `RemoveSkillUp`/`AddSkillUp`/`BuySkillTier`,
-//! `UnitCharacterPoints`) back the training-up machinery this pane doesn't ship (0437's named
-//! out-of-scope) — none are transcribed, engine-side or XML-side, rather than stubbing dead call
-//! sites nothing in [`SkillFrame.xml`] ever reaches. (The `UNLEARN_SKILL` popup, once in that
-//! list, ships for real now — the abandon slice above.)
+//! `numTempPoints` answers 0: the model carries no temp points, and on 1.12's data nothing a player
+//! holds moves the reference's field (`+0x10`), which only `AddSkillUp` increments (`0x4d345b`).
+//! `stepCost` and `rankCost` are always nil, by the data: `SkillLine.skillCostsID` is 0 in every
+//! row and no line a player holds carries the step-cost flags.
 
 use std::collections::HashMap;
 
@@ -80,94 +18,64 @@ use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// One known skill line off the player's `PLAYER_SKILL_INFO` block, app-resolved (0437 phase 4).
-/// EXACT shape the app feed (`crates/benilla/src/ui_char.rs`) is written against — do not rename.
+/// One known skill line off the player's `PLAYER_SKILL_INFO` block, resolved by the app.
 #[derive(Clone, Debug, PartialEq)]
 pub struct SkillEntry {
     pub skill_id: u32,
-    /// `SkillLine.dbc` name ("First Aid").
+    /// The `SkillLine.dbc` name.
     pub name: String,
-    /// Current rank, raw off the descriptor. `0` = **untrained**, which is a sort key of its own
-    /// (untrained lines sink under their category's trained ones — the client's comparator
-    /// `0x4d3070`).
+    /// The raw rank off the descriptor; 0 is untrained, which sorts below the trained lines.
     pub value: u32,
-    /// Max rank, as the server's own `PLAYER_SKILL_INFO` descriptor holds it — see [`Self::mono`]
-    /// for the DBC override the API return goes through.
+    /// The raw max rank off the descriptor; [`Self::mono`] overrides it at the API return.
     pub max: u32,
-    /// `SkillRaceClassInfo.flags & 0x400` (`SKILL_FLAG_MONO_VALUE`) for the player's race/class:
-    /// a **single-rank** line. The real client's `GetSkillLineInfo` overrides `skillMaxRank` to
-    /// `1` for these, whatever the descriptor says (`0x4d3610`, `4d38b1 test ah,0x4`) —
-    /// so a hunter's `Beast Mastery`, which vmangos happily reports as `300/300`, reads as a
-    /// proficiency and `SkillFrame.lua`'s `skillMaxRank == 1` branch draws it gray with no rank
-    /// text. The raw [`Self::max`] stays untouched here; the override lives at the API return,
-    /// exactly where the binary puts it.
+    /// `SkillRaceClassInfo.flags & 0x400` (`SKILL_FLAG_MONO_VALUE`): a single-rank line, whose
+    /// `skillMaxRank` the client reports as 1 whatever the descriptor says (`0x4d3610`), so
+    /// vmangos's 300/300 Beast Mastery reads as a proficiency.
     pub mono: bool,
-    /// The **temporary** bonus (auras/consumables/enchants; negative possible) — and only that:
-    /// `GetSkillLineInfo`'s `skillModifier` is a signed read of the descriptor's temp half alone
-    /// (`+0x850`), the green "+n" in the rank text. The permanent half is [`Self::perm_bonus`],
-    /// which the client folds into the numbers instead.
+    /// The temporary bonus, possibly negative: `skillModifier`, a signed read of the descriptor's
+    /// temp half alone (`+0x850`).
     pub temp_bonus: i32,
-    /// The **permanent** bonus (talents; `+0x852`, negative possible). Not a return of its own:
-    /// the client adds it into BOTH `skillRank` and `skillMaxRank` before the mono override
-    /// (`0x4d380c`/`0x4d385d`), and only when the raw value is nonzero — so a line the player
-    /// doesn't have stays at a flat `0`, never `0 + bonus`.
+    /// The permanent bonus (`+0x852`), possibly negative, folded into both ranks when they are
+    /// nonzero (`0x4d380c`/`0x4d385d`).
     pub perm_bonus: i32,
-    /// `SkillRaceClassInfo.reqLevel` — `GetSkillLineInfo`'s 11th return, pushed as a real number
-    /// (`0x4d39ef`; nonzero in practice: Mail 40, Dual Wield 20).
+    /// `SkillRaceClassInfo.reqLevel`, `GetSkillLineInfo`'s 11th return (`0x4d39ef`).
     pub min_level: u32,
-    /// `SkillRaceClassInfo.skillCostID` — `GetSkillLineInfo`'s 12th return is this **plus one**
-    /// (`0x4d3a06`), which is why the engine adds the 1, not the feed.
+    /// `SkillRaceClassInfo.skillCostID`; the 12th return is this plus one (`0x4d3a06`), added by
+    /// the engine.
     pub cost_index: u32,
     /// `SkillLine.dbc` categoryId.
     pub category_id: u32,
-    /// Resolved category name ("Professions") — the header text.
+    /// The category name, the header text.
     pub category_name: String,
-    /// `SkillLineCategory` displayOrder — the group sort key.
+    /// `SkillLineCategory` displayOrder, the group sort key.
     pub category_order: u32,
-    /// `SkillLine.dbc` description (enUS column 12) — `GetSkillLineInfo`'s 13th return, the
-    /// detail pane's body text (empty when the row carries none; the XML's `SKILL_DESCRIPTION`
-    /// format renders it verbatim).
+    /// `SkillLine.dbc` description (enUS column 12), `GetSkillLineInfo`'s 13th return.
     pub description: String,
-    /// Whether the line can be unlearned — `GetSkillLineInfo`'s 8th return (`isAbandonable`), the
-    /// detail pane's unlearn-button gate. App-resolved, and a **conjunction**: the descriptor's
-    /// skill **step** must be nonzero AND `SkillRaceClassInfo.flags & 0x20` must be set
-    /// (`SKILL_FLAG_UNLEARNABLE` — the server's own `CMSG_UNLEARN_SKILL` gate, vmangos
-    /// `SkillHandler.cpp`). Both halves are the client's (`0x4d3953`–`0x4d3975`).
+    /// `isAbandonable`, the 8th return: a nonzero skill step and `SkillRaceClassInfo.flags & 0x20`
+    /// (`SKILL_FLAG_UNLEARNABLE`), both checked by the client (`0x4d3953`–`0x4d3975`).
     pub abandonable: bool,
 }
 
-/// A flat, unordered push of every known skill line (0437 phase 4) — the ENGINE groups and sorts
-/// (see the module doc's grouping law). EXACT shape the app feed is written against — do not
-/// rename.
+/// A flat, unordered push of every known skill line; the engine groups and sorts it.
 #[derive(Clone, Debug, PartialEq, Default)]
 pub struct SkillsState {
     pub entries: Vec<SkillEntry>,
 }
 
-/// One category group in the synthesized display tree: the header's id/name/sort key and the
-/// positions (into [`SkillsState::entries`]) of the category's lines, pre-sorted by name —
-/// mirrors [`super::trainer::TrainerGroup`], but the group key is a *category*, never the wire
-/// skill line itself. Engine-internal (never crosses the app seam, unlike [`SkillsState`]);
-/// `pub(crate)` only because [`super::model::Model`] stores a `Vec` of them.
+/// One category of the display tree, with its lines' positions in [`SkillsState::entries`].
 #[derive(Clone, Debug, Default, PartialEq)]
 pub(crate) struct SkillGroup {
     category_id: u32,
     name: String,
     order: u32,
-    /// Positions into [`SkillsState::entries`], sorted by [`collate`]d name.
+    /// Positions into [`SkillsState::entries`], in display order.
     entries: Vec<usize>,
 }
 
 impl super::UiScript {
-    /// Replace the skills snapshot (0437 phase 4). Builds the display tree ([`build_groups`]) from
-    /// the flat entries, **re-expands every group**, and re-anchors the selection to the SAME
-    /// skill id if it's still present — else clears it (the tradeskill's own by-spell-id
-    /// selection-persistence precedent).
-    ///
-    /// The re-expand is the client's, not a convenience: its list rebuild writes
-    /// `expandedMask = 0xFFFFFFFF` unconditionally (`0x4d2cb0`, store at `0x4d2ce2`), so a fold
-    /// survives only until the next skill-field change — the trainer's collapse-survives-an-update
-    /// rule this pane once borrowed is simply a different window's law (decision 1091).
+    /// Replace the skills snapshot: rebuild the tree, re-expand every group (the client's rebuild
+    /// stores `expandedMask = 0xFFFFFFFF` at `0x4d2ce2`) and keep the selection if its skill is
+    /// still present.
     pub fn set_skills(&mut self, state: SkillsState) {
         let mut model = self.model_mut();
         let groups = build_groups(&state.entries);
@@ -181,34 +89,29 @@ impl super::UiScript {
         model.skills = state;
     }
 
-    /// Drain the skill line ids `AbandonSkill` queued (the unlearn seam) — the app sends each as
-    /// one `CMSG_UNLEARN_SKILL` and otherwise does nothing: the removal arrives back as a server
-    /// skill-field update, never a local mutation ([`Model::skill_abandons`]).
+    /// Drain the skill ids `AbandonSkill` queued, one `CMSG_UNLEARN_SKILL` each; the removal comes
+    /// back as a skill-field update.
     pub fn take_skill_abandons(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().skill_abandons)
     }
 }
 
-/// One visible row of the display tree: a category **header** (carrying its group index) or an
-/// **entry** (carrying its position into [`SkillsState::entries`]).
+/// One visible row: a header (its group index) or an entry (its position in
+/// [`SkillsState::entries`]).
 #[derive(Clone, Copy)]
 enum Row {
     Header(usize),
     Entry(usize),
 }
 
-/// The WoW enUS collator, approximated (the trainer's own [`super::trainer`] helper, duplicated
-/// here rather than shared — each seam module keeps its own copy, the established local
-/// convention): case-insensitive alphabetical, raw bytes as a stable tie-break.
+/// The client's `stricmp`, approximated: case-insensitive, raw bytes as the tie-break.
 fn collate(a: &str, b: &str) -> std::cmp::Ordering {
     a.to_lowercase()
         .cmp(&b.to_lowercase())
         .then_with(|| a.cmp(b))
 }
 
-/// Build the display tree from the flat entries (the module doc's grouping law): group by
-/// category, sort each group's entries by name, sort the groups by `category_order` (category id
-/// breaks a tie). Entry positions index back into the unchanged `entries` slice.
+/// Build the display tree by the module doc's grouping rule.
 fn build_groups(entries: &[SkillEntry]) -> Vec<SkillGroup> {
     let mut map: HashMap<u32, SkillGroup> = HashMap::new();
     for (i, e) in entries.iter().enumerate() {
@@ -224,9 +127,8 @@ fn build_groups(entries: &[SkillEntry]) -> Vec<SkillGroup> {
     }
     let mut groups: Vec<SkillGroup> = map.into_values().collect();
     for g in &mut groups {
-        // Within a category the client sorts UNTRAINED (rank 0) lines below trained ones, then by
-        // name (`0x4d3070`: the `untrained` byte set at build time, `0x4d2e19 sete`, compared
-        // before the `stricmp` at `0x4d318d`).
+        // Untrained below trained, then by name (`0x4d3070` compares the untrained byte, set at
+        // `0x4d2e19`, before the `stricmp` at `0x4d318d`).
         g.entries.sort_by(|&a, &b| {
             (entries[a].value == 0)
                 .cmp(&(entries[b].value == 0))
@@ -241,8 +143,7 @@ fn build_groups(entries: &[SkillEntry]) -> Vec<SkillGroup> {
     groups
 }
 
-/// The visible rows in display order: each group's header (always shown), then — when the group
-/// isn't collapsed — its entries. The Lua's 1-based `index` is a position in *this* list.
+/// The visible rows; the Lua's 1-based index is a position in this list.
 fn rows(model: &Model) -> Vec<Row> {
     let mut out = Vec::new();
     for (gi, g) in model.skills_groups.iter().enumerate() {
@@ -256,13 +157,11 @@ fn rows(model: &Model) -> Vec<Row> {
     out
 }
 
-/// The count of visible rows (headers + the entries of expanded groups).
 fn num_rows(model: &Model) -> usize {
     rows(model).len()
 }
 
-/// The entry at a 1-based VISIBLE index, or `None` when that row is a header (or OOB) — so the
-/// selection/info getters that read an entry safely no-op on a header row.
+/// The entry at a 1-based visible index; `None` for a header.
 fn entry_at(model: &Model, index: usize) -> Option<&SkillEntry> {
     let n = index.checked_sub(1)?;
     match rows(model).get(n)? {
@@ -271,10 +170,8 @@ fn entry_at(model: &Model, index: usize) -> Option<&SkillEntry> {
     }
 }
 
-/// Collapse (`collapse = true`) or expand a category by the **display index of its header row**
-/// (the trainer's own `Collapse/ExpandTrainerSkillLine` shape). `id == 0` targets ALL groups (the
-/// collapse-all button); `id > 0` resolves the header at that visible index to its category. A
-/// non-header (or OOB) index is a no-op.
+/// Collapse or expand the category whose header is at visible index `id`; 0 is every group, and a
+/// non-header index does nothing.
 fn set_collapsed(model: &mut Model, id: usize, collapse: bool) {
     if id == 0 && !collapse {
         model.skills_collapsed.clear();
@@ -302,18 +199,10 @@ fn set_collapsed(model: &mut Model, id: usize, collapse: bool) {
     }
 }
 
-/// `SetSelectedSkill(index)` — resolve the 1-based VISIBLE index to a skill id and hold THAT (the
-/// module doc's by-id persistence); a header row or an out-of-range index clears the selection.
-/// `GetSkillLineInfo`'s **out-of-range tuple** — thirteen values, four of them numeric zeros.
-///
-/// Byte-verified (pushes `0x4d3a2c`…`0x4d3a98`, `mov eax,0xd` at `0x4d3a9f`); decision 1919. One
-/// shape serves five distinct conditions — index 0, a negative index, an index past the end, no
-/// active player, and an in-range row whose DBC record is missing — because the reference's
-/// bounds test (`0x4d3675`) is a single UNSIGNED compare that funnels them all to the same exit.
-///
-/// The numeric slots are 4 (`skillRank`), 5 (`numTempPoints`), 6 (`skillModifier`), 7
-/// (`skillMaxRank`), 11 (`minLevel`) and 12 (`skillCostType`). Slots 4 and 5 must be numbers or the
-/// reference's own unguarded `skillRank + numTempPoints` raises.
+/// `GetSkillLineInfo`'s out-of-range answer, thirteen values (`0x4d3a2c`…`0x4d3a98`): the
+/// reference's one unsigned bounds test (`0x4d3675`) sends index 0, a negative or past-the-end
+/// index, no player and a missing DBC row here. Slots 4 and 5 must be numbers: stock
+/// `SkillFrame.lua:194` adds them unguarded, and `SkillFrame_OnLoad` calls `SetSelectedSkill(0)`.
 fn out_of_range_tuple(_lua: &Lua) -> mlua::Result<MultiValue> {
     Ok(MultiValue::from_vec(vec![
         Value::Nil,        // 1  skillName
@@ -336,8 +225,7 @@ fn set_selected(model: &mut Model, index: u32) {
     model.skills_selected = entry_at(model, index as usize).map(|e| e.skill_id);
 }
 
-/// `GetSelectedSkill()` — the selection's CURRENT visible index (`0` when nothing is selected, or
-/// the selected id isn't visible right now, e.g. its group just got collapsed).
+/// `GetSelectedSkill()`: the selection's current visible index, 0 when none or folded away.
 fn selected_index(model: &Model) -> u32 {
     let Some(sid) = model.skills_selected else {
         return 0;
@@ -348,19 +236,15 @@ fn selected_index(model: &Model) -> u32 {
         .map_or(0, |p| (p + 1) as u32)
 }
 
-/// `GetSkillLineInfo`'s `(skillRank, skillMaxRank)` pair for one entry — the client's own
-/// arithmetic, in its own order (`0x4d380c`–`0x4d38cb`):
+/// `GetSkillLineInfo`'s `(skillRank, skillMaxRank)`, in the client's order (`0x4d380c`–`0x4d38cb`):
 ///
 /// ```text
-/// skillRank    = rank > 0 ? rank + permBonus : rank        // a line at 0 stays flat 0
+/// skillRank    = rank > 0 ? rank + permBonus : rank
 /// skillMaxRank = max  > 0 ? max  + permBonus : max
-/// if mono { skillMaxRank = 1; if skillRank > 1 { skillRank = 1 } }   // override, then a MIN
+/// if mono { skillMaxRank = 1; if skillRank > 1 { skillRank = 1 } }
 /// ```
 ///
-/// The mono arm is an unconditional **override** of the max (not a clamp) and a **min** on the
-/// rank — the asymmetry is the binary's, and it is what makes a `300/300` class line read as the
-/// `1/1` proficiency `SkillFrame.lua` draws gray. Saturating at 0 keeps a negative permanent
-/// malus from wrapping the unsigned descriptor values.
+/// Saturating at 0 keeps a negative permanent bonus from wrapping.
 fn displayed_ranks(e: &SkillEntry) -> (i64, i64) {
     let fold = |v: u32| {
         if v > 0 {
@@ -377,8 +261,7 @@ fn displayed_ranks(e: &SkillEntry) -> (i64, i64) {
     (rank, max)
 }
 
-/// A `bool` as the Era `1`/`nil` shape (the trainer/tradeskill's own helper, duplicated per the
-/// established per-module convention).
+/// A `bool` as the 1.12 `1`/nil shape.
 fn era_bool(b: bool) -> Value {
     if b {
         Value::Integer(1)
@@ -400,23 +283,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSkillLineInfo(index) → the ref's own tuple: 13 values on a skill row (`0x4d3a20`), 12 on
-    // a header (`0x4d3768`). `index` 1-based.
-    //
-    // **OUT OF RANGE IS THE 13-VALUE FALLBACK, NOT A SINGLE NIL.** This comment used to say the
-    // opposite and it was wrong; the correction is decision 1919. `0x4d3675`'s bounds test is
-    // UNSIGNED against the total row count, so index 0, a negative index, an index past the end, no
-    // active player, and an in-range row whose DBC record is missing all fall to `0x4d3a2a` and push
-    // the same thirteen: `nil, nil, nil, 0, 0, 0, 0, nil, nil, nil, 0, 0, nil` (`0x4d3a2c`…
-    // `0x4d3a98`, then `mov eax,0xd`).
-    //
-    // **Slots 4 and 5 being NUMBERS is the whole point.** The reference's own
-    // `SkillDetailFrame_SetStatusBar` does `skillRank = skillRank + numTempPoints`
-    // (`SkillFrame.lua:193-194`) with NO guard, straight off `SkillFrame_OnLoad`'s
-    // `SetSelectedSkill(0)` — so a single nil here raises "attempt to perform arithmetic on a nil
-    // value" the moment the stock file drives us. Slot 1 being nil is what drives its
-    // `if (not skillName …) then … return` at l.211. The selection verbs are NOT the divergence:
-    // `GetSelectedSkill 0x4d4090` always pushes exactly one number and legitimately answers 0.
+    // GetSkillLineInfo(index) → 13 values on a skill row (`0x4d3a20`), 12 on a header
+    // (`0x4d3768`); out of range, the 13-value tuple (`0x4d3a2a`), whose nil first slot drives
+    // stock `SkillFrame.lua:211`'s early return.
     g.set(
         "GetSkillLineInfo",
         lua.create_function(|lua, index: usize| {
@@ -436,14 +305,14 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                         Value::Integer(1), // isHeader
                         era_bool(expanded),
                         Value::Integer(0), // skillRank
-                        Value::Integer(0), // numTempPoints — a real field; 0 because we model no temp points (1919)
+                        Value::Integer(0), // numTempPoints
                         Value::Integer(0), // skillModifier
                         Value::Integer(0), // skillMaxRank
                         Value::Nil,        // isAbandonable
                         Value::Nil,        // stepCost
                         Value::Nil,        // rankCost
                         Value::Integer(0), // minLevel
-                        Value::Integer(0), // skillCostType — the 12th and LAST header return
+                        Value::Integer(0), // skillCostType, the last header return
                     ]))
                 }
                 Row::Entry(ei) => {
@@ -454,18 +323,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                         Value::Nil, // isHeader
                         Value::Nil, // isExpanded
                         Value::Integer(rank),
-                        Value::Integer(0), // numTempPoints — a real field; 0 because we model no temp points (1919)
-                        Value::Integer(i64::from(e.temp_bonus)), // skillModifier — TEMP only
+                        Value::Integer(0),                       // numTempPoints
+                        Value::Integer(i64::from(e.temp_bonus)), // skillModifier: temp only
                         Value::Integer(max),
                         era_bool(e.abandonable), // isAbandonable
-                        // stepCost/rankCost are nil on this build for DATA reasons, not code
-                        // ones (module doc) — and nil is load-bearing: `0` is truthy in Lua, so
-                        // returning it would send SkillFrame.lua down its "learnable skill"
-                        // branch on every row.
+                        // stepCost, rankCost: nil, since Lua reads `0` as true.
                         Value::Nil,
                         Value::Nil,
-                        Value::Integer(i64::from(e.min_level)), // minLevel — a real number
-                        // skillCostType — SkillCostIndex + 1, the client's own `0x4d3a06`.
+                        Value::Integer(i64::from(e.min_level)), // minLevel
+                        // skillCostType: the cost index plus one (`0x4d3a06`).
                         Value::Integer(i64::from(e.cost_index) + 1),
                         Value::String(lua.create_string(&e.description)?), // skillDescription
                     ]))
@@ -474,8 +340,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // Collapse/ExpandSkillHeader(id) — fold a category by the display index of its header row (id
-    // 0 = all groups); a non-header (or OOB) index no-ops.
+    // Collapse/ExpandSkillHeader(id): by the header's visible index, 0 for every group.
     g.set(
         "CollapseSkillHeader",
         lua.create_function(|lua, id: usize| {
@@ -493,8 +358,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetSelectedSkill(index) / GetSelectedSkill() — the engine-held selection, VISIBLE index in,
-    // VISIBLE index out, held BY SKILL ID internally (module doc).
+    // SetSelectedSkill(index) / GetSelectedSkill(): visible indices, held by skill id;
+    // `GetSelectedSkill` (`0x4d4090`) always answers one number, 0 included.
     g.set(
         "SetSelectedSkill",
         lua.create_function(|lua, index: u32| {
@@ -511,18 +376,16 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetAdjustedSkillPoints() → 0 — a vestigial 1.12 leftover the ref reads (module doc); this
-    // client has no training-point economy behind a skill line.
+    // GetAdjustedSkillPoints() → 0 here; the reference answers `PLAYER_CHARACTER_POINTS2` less the
+    // points `AddSkillUp` has pending (`0x4d3cb0`). The stock pane reads it only under its
+    // `stepCost` and `rankCost` branches, which 1.12 data never opens.
     g.set(
         "GetAdjustedSkillPoints",
         lua.create_function(|_, ()| Ok(0i64))?,
     )?;
 
-    // AbandonSkill(index) — VISIBLE index in (the ref's UNLEARN_SKILL popup passes the row it was
-    // opened for), queued out BY SKILL ID for the app's CMSG_UNLEARN_SKILL send. Mutates NOTHING
-    // locally: the real client waits for the server's skill-field update (vmangos SetSkill(id,0,0)
-    // → our descriptor watcher → a fresh set_skills push → SKILL_LINES_CHANGED). A header or
-    // out-of-range index no-ops (only entries carry the unlearn button).
+    // AbandonSkill(index): queue the entry's skill id for `CMSG_UNLEARN_SKILL`, changing nothing
+    // locally: the reference waits for the skill-field update (vmangos `SetSkill(id,0,0)`).
     g.set(
         "AbandonSkill",
         lua.create_function(|lua, index: usize| {
@@ -534,14 +397,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CancelSkillUps() — `0x4d3e30` → `0x4d35c9` (reference `1.12-shapes.tsv`: no arguments, no
-    // returns): the reset leg of the temp-point table, zeroing every entry's `numTempPoints` and
-    // giving the points back to the pool. The stock page's LIVE Close button calls it before
-    // hiding (`SkillFrame.xml`'s SkillFrameCancelButton, decision 1496), so it is reached on
-    // every close. This model carries no temp points (module docs, 1919): the table it resets is
-    // empty by construction, so the reset moves nothing — the binding's whole effect on this
-    // client's data, not a stand-in for it. The day temp points are modelled, this is where
-    // they are cleared.
+    // CancelSkillUps() (`0x4d3e30`): zeroes every `numTempPoints` (`0x4d35c9`); the stock Close
+    // button calls it (`SkillFrame.xml:352`). No temp points are modelled, so nothing resets.
     g.set("CancelSkillUps", lua.create_function(|_, ()| Ok(()))?)?;
 
     Ok(())
@@ -575,18 +432,14 @@ mod tests {
             category_name: category_name.into(),
             category_order,
             description: format!("About {name}."),
-            // Fixture rule: the Professions category (id 2) is abandonable, weapons are not —
-            // the real SkillRaceClassInfo 0x20 split's shape.
+            // Fixture rule: Professions (id 2) is abandonable, as the 0x20 flag splits it.
             abandonable: category_id == 2,
-            // Fixture rule: the Class Skills category (id 3) is single-rank, the real 0x400
-            // split's shape (a hunter's Beast Mastery).
+            // Fixture rule: Class Skills (id 3) is single-rank, as the 0x400 flag splits it.
             mono: category_id == 3,
         }
     }
 
-    /// Two categories: "Weapon Skills" (order 1: Defense, Swords) and "Professions" (order 2:
-    /// First Aid, Fishing) — a flat, unordered push (Swords precedes Defense in push order; the
-    /// engine's own name sort must still show Defense first).
+    /// Weapon Skills (order 1) and Professions (order 2), pushed unordered: Swords before Defense.
     fn state() -> SkillsState {
         SkillsState {
             entries: vec![
@@ -612,7 +465,7 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetNumSkillLines()").unwrap(), 0);
 
         s.set_skills(state());
-        // 2 headers + 4 entries = 6 visible rows, category_order ascending, name ascending within.
+        // 2 headers + 4 entries, category_order ascending, name ascending within.
         assert_eq!(s.eval::<i64>("return GetNumSkillLines()").unwrap(), 6);
         assert_eq!(
             row_kind(&mut s, 1),
@@ -624,7 +477,7 @@ mod tests {
         assert_eq!(row_kind(&mut s, 5), ("First Aid".into(), "entry".into()));
         assert_eq!(row_kind(&mut s, 6), ("Fishing".into(), "entry".into()));
 
-        // Every group starts EXPANDED (the module doc's default rule).
+        // Every group starts expanded.
         let (_, h1, e1) = s
             .eval::<(String, i64, Option<i64>)>("local n,h,e = GetSkillLineInfo(1) return n,h,e")
             .unwrap();
@@ -635,8 +488,7 @@ mod tests {
     fn abandon_skill_queues_the_entrys_skill_id_and_mutates_nothing() {
         let mut s = UiScript::new().unwrap();
         s.set_skills(state());
-        // The 8th return: Professions rows are abandonable (fixture rule), weapon rows and
-        // headers are not — 1/nil, the 1.12 boolean shape.
+        // The 8th return, 1/nil: only Professions rows are abandonable (fixture rule).
         let ab = |s: &mut UiScript, i: i64| {
             s.eval::<Option<i64>>(&format!(
                 "local _,_,_,_,_,_,_,ab = GetSkillLineInfo({i}) return ab"
@@ -647,8 +499,7 @@ mod tests {
         assert_eq!(ab(&mut s, 5), Some(1), "First Aid is abandonable");
         assert_eq!(ab(&mut s, 1), None, "a header never is");
 
-        // AbandonSkill queues BY SKILL ID; headers and out-of-range indices no-op; the list
-        // itself is untouched (the server round trip owns the removal).
+        // Queued by skill id; a header or an out-of-range index does nothing; the list stays.
         s.run("AbandonSkill(5)").unwrap();
         s.run("AbandonSkill(1)").unwrap();
         s.run("AbandonSkill(99)").unwrap();
@@ -669,8 +520,7 @@ mod tests {
         let mut s = UiScript::new().unwrap();
         s.set_skills(state());
 
-        // Fold "Weapon Skills" (header at visible index 1): its two entries vanish, the header
-        // stays and now reports isExpanded=nil. 6 → 4.
+        // Fold Weapon Skills (row 1): its two entries go, the header stays with isExpanded nil.
         s.run("CollapseSkillHeader(1)").unwrap();
         assert_eq!(s.eval::<i64>("return GetNumSkillLines()").unwrap(), 4);
         let (name, _, expanded) = s
@@ -694,14 +544,12 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetNumSkillLines()").unwrap(), 6);
     }
 
-    /// A re-push keeps the SELECTION (by skill id) but throws every fold away — the client's list
-    /// rebuild re-expands unconditionally (`expandedMask = 0xFFFFFFFF`, decision 1091).
     #[test]
     fn a_repush_keeps_the_selection_and_re_expands_every_group() {
         let mut s = UiScript::new().unwrap();
         s.set_skills(state());
 
-        // Selecting a HEADER clears the selection (module doc).
+        // Selecting a header clears the selection.
         s.run("SetSelectedSkill(1)").unwrap();
         assert_eq!(s.eval::<i64>("return GetSelectedSkill()").unwrap(), 0);
 
@@ -711,8 +559,7 @@ mod tests {
         s.run("CollapseSkillHeader(4)").unwrap();
         assert_eq!(s.eval::<i64>("return GetNumSkillLines()").unwrap(), 4);
 
-        // A re-push (values ticked up): the fold is GONE — all 6 rows are back — while the
-        // selection still points at Swords, which is still row 3.
+        // A re-push unfolds every group and keeps Swords selected at row 3.
         let mut ticked = state();
         ticked.entries[0].value = 201; // Swords
         s.set_skills(ticked);
@@ -735,8 +582,7 @@ mod tests {
         let mut s = UiScript::new().unwrap();
         s.set_skills(state());
 
-        // Header row 1 ("Weapon Skills"): 12 values — (name, 1, expanded, 0, 0, 0, 0, nil, nil,
-        // nil, 0, 0), and NO 13th (the client's header path pushes 12, `0x4d3768`).
+        // Header row 1: twelve values, no description (`0x4d3768`).
         let (name, is_header, is_expanded, rank, temp, modifier, max) = s
             .eval::<(String, i64, Option<i64>, i64, i64, i64, i64)>(
                 "local n,h,e,r,t,m,mx = GetSkillLineInfo(1) return n,h,e,r,t,m,mx",
@@ -769,8 +615,7 @@ mod tests {
         assert_eq!((min_level, cost_type), (0, 0));
         assert_eq!(count, 12, "a header row returns 12 values, not 13");
 
-        // Entry row 2 ("Defense", value 180, max 300, temp bonus +5): (name, nil, nil, 180, 0, 5,
-        // 300, nil, nil, nil, 0, 1, description) — 13 values.
+        // Entry row 2 (Defense 180/300, temp +5): thirteen values.
         let (name, is_header, is_expanded, rank, temp, modifier, max) = s
             .eval::<(String, Option<i64>, Option<i64>, i64, i64, i64, i64)>(
                 "local n,h,e,r,t,m,mx = GetSkillLineInfo(2) return n,h,e,r,t,m,mx",
@@ -788,15 +633,12 @@ mod tests {
             ),
             ("Defense", None, None, 180, 0, 5, 300)
         );
-        // The 13th return is the REAL description (SkillLine.dbc col 12 through the feed) — an
-        // entry row's alone: a header stops at 12 (asserted above).
         let count = s.arity("GetSkillLineInfo(2)").unwrap();
         let desc = s
             .eval::<String>("local _,_,_,_,_,_,_,_,_,_,_,_,d = GetSkillLineInfo(2) return d")
             .unwrap();
         assert_eq!((count, desc.as_str()), (13, "About Defense."));
-        // minLevel and skillCostType are real NUMBERS on an entry — and the cost type is the
-        // row's index PLUS ONE (the client's own `0x4d3a06`), so a fixture at index 0 reads 1.
+        // The cost type is the cost index plus one, so index 0 reads 1.
         let (min_level, cost_type) = s
             .eval::<(i64, i64)>(
                 "local _,_,_,_,_,_,_,_,_,_,ml,ct = GetSkillLineInfo(2) return ml,ct",
@@ -805,8 +647,6 @@ mod tests {
         assert_eq!((min_level, cost_type), (0, 1));
     }
 
-    /// The permanent bonus folds into BOTH numbers, the temporary one is the `skillModifier`
-    /// return on its own, and a line at 0 stays flat 0 (the client's `rank > 0 ?` guard).
     #[test]
     fn the_permanent_bonus_folds_into_the_numbers_and_the_temporary_one_does_not() {
         let mut s = UiScript::new().unwrap();
@@ -817,22 +657,19 @@ mod tests {
         st.entries.last_mut().unwrap().perm_bonus = 10;
         s.set_skills(st);
 
-        // Defense (row 2): 190/310, modifier still the temp +5 alone.
+        // Defense (row 2): 190/310, the modifier still the temp +5 alone.
         let (rank, modifier, max) = s
             .eval::<(i64, i64, i64)>("local _,_,_,r,_,m,mx = GetSkillLineInfo(2) return r,m,mx")
             .unwrap();
         assert_eq!((rank, modifier, max), (190, 5, 310));
 
-        // Herbalism 0/0 (row 7, an untrained line sorted under the trained ones): a flat 0/0 —
-        // the bonus is not added to a zero.
+        // Herbalism 0/0 (row 7, untrained so last): the bonus is not added to a zero.
         let (name, rank, max) = s
             .eval::<(String, i64, i64)>("local n,_,_,r,_,_,mx = GetSkillLineInfo(7) return n,r,mx")
             .unwrap();
         assert_eq!((name.as_str(), rank, max), ("Herbalism", 0, 0));
     }
 
-    /// Within a category, untrained (rank 0) lines sink below the trained ones, whatever their
-    /// name — the client's comparator (`0x4d3070`), which tests `untrained` before `stricmp`.
     #[test]
     fn untrained_lines_sort_under_the_trained_ones_of_their_category() {
         let mut s = UiScript::new().unwrap();
@@ -850,14 +687,11 @@ mod tests {
         assert_eq!(names, ["First Aid", "Fishing", "Alchemy"]);
     }
 
-    /// A single-rank line reports `1/1` however high the server's descriptor is (the client's own
-    /// `SkillRaceClassInfo.flags & 0x400` arm: an override on the max, a min on the rank) — the
-    /// pane's proficiency gate. A normal line is unaffected.
     #[test]
     fn a_mono_line_reports_max_rank_one_whatever_the_server_said() {
         let mut s = UiScript::new().unwrap();
         let mut st = state();
-        // Beast Mastery: category 3 ⇒ mono by the fixture rule, server-side 300/300.
+        // Beast Mastery: category 3, so mono by the fixture rule; 300/300 from the server.
         st.entries.push(entry(
             50,
             "Beast Mastery",
@@ -870,7 +704,7 @@ mod tests {
         ));
         s.set_skills(st);
 
-        // Row 1/2 = the Class Skills header + its single entry (category_order 0 sorts first).
+        // Rows 1 and 2: the Class Skills header and its entry (category_order 0 sorts first).
         let (name, rank, modifier, max) = s
             .eval::<(String, i64, i64, i64)>(
                 "local n,_,_,r,_,m,mx = GetSkillLineInfo(2) return n,r,m,mx",
@@ -881,7 +715,7 @@ mod tests {
             ("Beast Mastery", 1, 0, 1),
             "the descriptor's 300/300 reads 1/1 — max overridden, rank clamped under it"
         );
-        // Defense (a weapon line, not mono) still reports its real 300.
+        // Defense, not mono, still reports its real 300.
         assert_eq!(
             s.eval::<i64>("local _,_,_,_,_,_,mx = GetSkillLineInfo(4) return mx")
                 .unwrap(),
@@ -889,17 +723,8 @@ mod tests {
         );
     }
 
-    /// **Out of range answers the reference's THIRTEEN-value tuple, not a bare nil** — decision
-    /// 1919, byte-verified (`0x4d3675`'s bounds test, `0x4d3a2c`…`0x4d3a98`).
-    ///
-    /// The COUNT is the whole assertion. `GetSkillLineInfo(0) == nil` reads true either way,
-    /// because Lua compares only the first returned value — which is precisely how the old
-    /// one-nil shape passed for as long as it did. What breaks a caller is slots 4 and 5: the
-    /// reference's own `SkillDetailFrame_SetStatusBar` does `skillRank = skillRank + numTempPoints`
-    /// with NO guard, straight off `SkillFrame_OnLoad`'s `SetSelectedSkill(0)`, so those two must be
-    /// NUMBERS or the stock file raises the moment it loads. One shape serves index 0, a negative
-    /// index, past-the-end, no active player and a DBC miss — the reference funnels all five
-    /// through one unsigned bounds test (`0x4d3675`).
+    /// The count is the assertion: `GetSkillLineInfo(0) == nil` holds for a single nil too, since
+    /// Lua compares only the first value.
     #[test]
     fn out_of_range_answers_the_thirteen_value_tuple() {
         let s = UiScript::new().unwrap();
@@ -929,14 +754,13 @@ mod tests {
     fn no_push_reports_zero_rows() {
         let s = UiScript::new().unwrap();
         assert_eq!(s.eval::<i64>("return GetNumSkillLines()").unwrap(), 0);
-        // The empty pane answers the out-of-range tuple; the test above holds its ARITY, which is
-        // the load-bearing half. This line only pins slot 1.
+        // The empty pane answers the out-of-range tuple; this pins slot 1.
         assert!(s
             .eval::<bool>("return (GetSkillLineInfo(1)) == nil")
             .unwrap());
         assert_eq!(s.eval::<i64>("return GetSelectedSkill()").unwrap(), 0);
         assert_eq!(s.eval::<i64>("return GetAdjustedSkillPoints()").unwrap(), 0);
-        // Collapse/expand/select on an empty pane are harmless no-ops.
+        // Collapse, expand and select on an empty pane do nothing.
         s.run("CollapseSkillHeader(0) ExpandSkillHeader(1) SetSelectedSkill(1)")
             .unwrap();
         assert_eq!(s.eval::<i64>("return GetNumSkillLines()").unwrap(), 0);
diff --git a/crates/benilla-ui/src/script/slash.rs b/crates/benilla-ui/src/script/slash.rs
index c7f8025d..46f8d6a0 100644
--- a/crates/benilla-ui/src/script/slash.rs
+++ b/crates/benilla-ui/src/script/slash.rs
@@ -1,87 +1,39 @@
-//! **`SlashCmdList` dispatch** — how an addon gets a `/command` (decision 1195).
-//!
-//! The single most-wanted *table* in the corpus. 26 of 218 addons stop on
-//! `attempt to index global 'SlashCmdList'` — the top runtime wall after the dialect gap — because
-//! the registration idiom is three lines at file scope:
-//!
-//! ```lua
-//! SLASH_MYADDON1 = "/myaddon"
-//! SLASH_MYADDON2 = "/ma"
-//! SlashCmdList["MYADDON"] = function(msg) … end
-//! ```
-//!
-//! …and the third line raises the moment the table is missing.
-//!
-//! ## The resolution is the reference's own, transcribed
-//!
-//! `ChatEdit_ParseText` (ChatFrame.lua) walks **`SlashCmdList`'s keys**, not a name list: for each
-//! `index` it reads `SLASH_<index>1`, `SLASH_<index>2`, … until the first gap, comparing each
-//! against the typed command case-insensitively. The aliases are data and the handlers are code,
-//! joined by the index name — decision 0881 built our own table on exactly that shape, and this is
-//! the same walk over the half addons own.
-//!
-//! Two details of that walk are load-bearing and both are easy to get wrong:
-//!
-//! - **The handler's argument is the rest of the line, not the rest of the *word*.** The reference
-//!   passes `strsub(text, strlen(cmdString) + 2)` — everything after the alias and one space — so
-//!   `/myaddon set foo 3` hands the handler `"set foo 3"`, spaces intact. An addon's own parser
-//!   starts there.
-//! - **The walk stops at the first gap.** `SLASH_X1` and `SLASH_X3` with no `SLASH_X2` means `X3`
-//!   is unreachable, in the reference and here. That is a property of the data format, not a bug
-//!   to repair.
-//!
-//! ## Where the table lives, and the divergence that comes with it
-//!
-//! `SlashCmdList` is **FrameXML's**, not the engine's (`reference/1.12-globals.tsv` says
-//! `table framexml`), so ours is declared in our transcribed `ChatFrame.xml` exactly as the
-//! reference declares it in `ChatFrame.lua` — 1190's engine/FrameXML split applied to a table
-//! rather than a function.
-//!
-//! **The divergence, stated:** benilla's *own* commands (`/who`, `/invite`, `/cast`, …) are
-//! dispatched in Rust ([`crate`]'s host owns them) and are **not** entries in `SlashCmdList`. In
-//! the reference they are, so an addon that tests `if SlashCmdList["WHO"] then` or hooks one by
-//! wrapping the entry sees an empty table here and does nothing. That is a real, observable gap;
-//! it is bounded (nothing in the corpus does it) and the fix is to move our command handlers into
-//! transcribed FrameXML, which is a much larger piece of work than this one.
+//! `SlashCmdList` dispatch from the host, for a line that reaches it without passing the stock
+//! `ChatEdit_ParseText` (`ChatFrame.lua`): the same walk, over the table the stock `ChatFrame.lua`
+//! declares, where the stock commands and benilla's own are entries.
 
 use mlua::{Table, Value};
 
 impl super::UiScript {
-    /// Try to dispatch `/cmd args` through `SlashCmdList`. Returns whether a handler ran.
-    ///
-    /// The host calls this **after** its own command table misses, so a shipped command can never
-    /// be shadowed by an addon — which is also the reference's precedence, since its own commands
-    /// are registered in the same table before any addon loads.
-    ///
-    /// A handler that raises is collected into [`super::UiScript::errors`] like any other script
-    /// error rather than propagated: a broken `/command` must not take down the chat drain that
-    /// invoked it. It still counts as *handled* — the command existed and was called.
+    /// Dispatch `/cmd args` through `SlashCmdList`, returning whether a handler ran. The host calls
+    /// this after its own commands miss, so an addon never shadows one; a handler that raises is
+    /// recorded as a script error, not propagated, and still counts as handled.
     pub fn run_slash_command(&mut self, cmd: &str, args: &str) -> bool {
         let Some(handler) = self.find_slash_handler(cmd) else {
             return false;
         };
-        // The reference passes `strsub(text, strlen(cmdString) + 2)` — everything after the alias
-        // and one space. The host has already made that split, so `args` IS that string.
+        // The rest of the line after the alias and one space, spaces intact: the reference's
+        // `strsub(text, strlen(cmdString) + 2)`.
         if let Err(e) = handler.call::<()>(args.to_string()) {
             self.model_mut().record_script_error(format!("/{cmd}: {e}"));
         }
         true
     }
 
-    /// Is `cmd` a command some `SlashCmdList` entry claims? Pure query, fires nothing — the
-    /// completion/echo paths want to know without running anything.
+    /// Whether a `SlashCmdList` entry claims `cmd`, without running it.
     pub fn has_slash_command(&self, cmd: &str) -> bool {
         self.find_slash_handler(cmd).is_some()
     }
 
-    /// The reference's walk: over `SlashCmdList`'s keys, then `SLASH_<key><n>` until a gap.
+    /// The reference's walk: over `SlashCmdList`'s keys, then `SLASH_<key><n>` to the first gap,
+    /// case-insensitive.
     fn find_slash_handler(&self, cmd: &str) -> Option<mlua::Function> {
         let globals = self.lua.globals();
         let list: Table = globals.get("SlashCmdList").ok()?;
         let want = cmd.to_ascii_uppercase();
         for pair in list.pairs::<String, Value>() {
             let Ok((index, Value::Function(handler))) = pair else {
-                continue; // a non-function entry is not a command; the reference would error on it
+                continue; // Deviation: skipped because it is no command; the reference raises
             };
             for n in 1.. {
                 let alias: Option<String> = globals.get(format!("SLASH_{index}{n}")).ok().flatten();
@@ -100,13 +52,10 @@ impl super::UiScript {
 mod tests {
     use crate::script::UiScript;
 
-    /// **The registration idiom, exactly as an addon writes it** — and the reason 26 corpus addons
-    /// died at file scope before this landed.
     #[test]
     fn an_addon_registers_a_slash_command_and_it_dispatches() {
         let mut s = UiScript::new().unwrap();
-        // Our shipped ChatFrame.xml declares the table; a bare VM has to stand it up itself, which
-        // is also the smallest possible statement of what an addon depends on.
+        // A bare VM has no `ChatFrame.xml`, so the test declares the table itself.
         s.run("SlashCmdList = {}").unwrap();
         s.run(
             r#"
@@ -132,8 +81,7 @@ mod tests {
         assert!(!s.run_slash_command("nosuchthing", ""));
     }
 
-    /// The alias walk stops at the first gap — the reference's `while cmdString` loop, and a
-    /// property of the data format rather than a bug to repair.
+    /// The reference's `while cmdString` loop.
     #[test]
     fn the_alias_walk_stops_at_the_first_gap() {
         let s = UiScript::new().unwrap();
@@ -153,8 +101,6 @@ mod tests {
         );
     }
 
-    /// A handler that raises is collected, not propagated: a broken addon command must not take
-    /// down the chat drain that invoked it.
     #[test]
     fn a_raising_handler_is_collected_and_still_counts_as_handled() {
         let mut s = UiScript::new().unwrap();
@@ -176,7 +122,6 @@ mod tests {
         );
     }
 
-    /// A `SlashCmdList` entry that is not a function is skipped rather than called.
     #[test]
     fn a_non_function_entry_is_not_a_command() {
         let s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/slider.rs b/crates/benilla-ui/src/script/slider.rs
index 81b8e111..ac2a4299 100644
--- a/crates/benilla-ui/src/script/slider.rs
+++ b/crates/benilla-ui/src/script/slider.rs
@@ -1,28 +1,10 @@
-//! The `Slider` method surface — the `CSimpleSlider` widget behavior over the kind tag (factory
-//! `0x6eee40`). A value in `[min, max]` with a step and orientation, driving a thumb texture along
-//! the track.
-//!
-//! Grounded in the byte-verified LoadXML table (`Slider::LoadXML 0x789580`): the
-//! `<ThumbTexture>` sub-element (default layer OVERLAY=3), `minValue`/`maxValue`/`valueStep`/
-//! `defaultValue`, the `orientation` shared enum (HORIZONTAL=0/VERTICAL=1, `0x811b00`), and the
-//! widget's own `OnValueChanged` script slot (`+0x330`). The **thumb-position** mechanism — the
-//! thumb's rect placed at the value fraction along the orientation axis, applied at extract — is
-//! faithful to the *documented* widget model, not byte-pinned (same posture as StatusBar's fill and
-//! ScrollFrame's scroll; decisions 0112/0250).
-//!
-//! `SetValue` fires `OnValueChanged` on the **first-ever** value and after that **only on an
-//! actual change** ([`SliderState::store_value`] — the client's `+0x314` bit2, `SetValue
-//! 0x789930`'s `0x789a06 test bl,4` gate). The change-gate is load-bearing, not an optimization:
-//! the real scrollbar template wires `OnValueChanged →
-//! this:GetParent():SetVerticalScroll(arg1)` and the ScrollFrame's `OnVerticalScroll →
-//! scrollbar:SetValue(arg1)` back the other way, so a fire-always `SetValue` would recurse
-//! forever (`UIPanelTemplates.xml`); the gate breaks the loop after one hop. `SetMinMaxValues`
-//! re-clamps through the same gate only once a value exists, so a range set from `<OnLoad>` never
-//! runs a handler the addon has not armed yet.
-//!
-//! The methods live in their own registry table, consulted by the frame `__index` dispatcher only
-//! for Slider frames — so duck-typing addons (`if frame:GetThumbTexture() then …`) see `nil` on
-//! every other kind, exactly as against the client's per-class method sets.
+//! The `Slider` methods of `CSimpleSlider` (factory `0x6eee40`, `Slider::LoadXML` `0x789580`): a
+//! value in `[min, max]` with a step and an orientation (`0x811b00`), driving a thumb texture along
+//! the track, whose placement follows the documented widget model, untraced in the reference.
+//! `SetValue` fires `OnValueChanged` (slot `+0x330`) on the first value and then only on a change
+//! (`+0x314` bit 2, `0x789a06` in `SetValue` `0x789930`), which ends the loop between the stock
+//! scrollbar's `OnValueChanged` and its ScrollFrame's `OnVerticalScroll`. The methods exist only on
+//! Slider frames, as in the client's per-class method sets.
 
 use mlua::{Lua, Table, Value};
 
@@ -36,12 +18,10 @@ use crate::widget::{
     slider_fraction, slider_grab, FrameHandle, KindState, RegionKind, SliderState,
 };
 
-/// Registry key of the Slider method table (the MAXCSTACK discipline: Lua-side root, named key).
 pub(super) const REG_SLIDER_METHODS: &str = "__benilla_slider_methods";
 
-/// Run `f` over a frame's Slider state under one short write borrow. Errors if `this` is not a live
-/// Slider (unreachable through the kind dispatcher, but the method table is a plain Lua value — a
-/// caller could fish it out and misapply it).
+/// Run `f` over a frame's Slider state under one short write borrow; errors unless `this` is a live
+/// Slider, since a caller can lift the method table onto another frame.
 fn with_slider<T>(
     lua: &Lua,
     this: &Table,
@@ -59,10 +39,8 @@ fn with_slider<T>(
     }
 }
 
-/// Get-or-create the thumb texture region (`SetThumbTexture`/`<ThumbTexture>`); `layer` re-layers an
-/// existing thumb. Returns the region's id (for wrapper lookup). The widget default layer is OVERLAY
-/// (`Slider::LoadXML 0x789580` — the Slider's `drawLayer` attr defaults OVERLAY=3, unlike
-/// StatusBar's ARTWORK bar).
+/// Get or create the thumb texture region and return its id; `layer` re-layers an existing thumb,
+/// and a new one defaults to OVERLAY (`0x789580`).
 fn ensure_thumb(lua: &Lua, this: &Table, layer: Option<DrawLayer>) -> mlua::Result<u32> {
     let h = frame_handle_of(lua, this)?;
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -95,7 +73,7 @@ fn ensure_thumb(lua: &Lua, this: &Table, layer: Option<DrawLayer>) -> mlua::Resu
                 )
                 .ok_or_else(|| mlua::Error::runtime("stale frame handle"))?;
             model.region_data.insert(rh, RegionData::default());
-            model.touch_layout(); // a region entered the layout gate's read set (decision 0740)
+            model.touch_layout(); // a region entered the layout gate's read set
             if let Some(frame) = model.arena.frame_mut(h) {
                 if let KindState::Slider(s) = &mut frame.kind_state {
                     s.thumb = Some(rh);
@@ -113,11 +91,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     m.set(
         "SetMinMaxValues",
         lua.create_function(|lua, (this, min, max): (Table, f32, f32)| {
-            // Unlike StatusBar, a reversed pair is NOT swapped (the Slider LoadXML `0x789580`
-            // stores min + (max−min) and does no swap). A held value re-clamps into the new
-            // range and a move fires OnValueChanged — but only once a value EXISTS
-            // (`SliderState::set_min_max`, the client's bit2): on a fresh slider this sets the
-            // range and fires nothing.
+            // A reversed pair is kept, not swapped (`0x789580`). A held value re-clamps and fires
+            // on a move; a fresh slider with no value yet fires nothing (bit 2).
             let changed = with_slider(lua, &this, |s| s.set_min_max(min, max))?;
             fire_value_changed(lua, &this, changed)
         })?,
@@ -139,9 +114,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
     m.set(
         "SetValueStep",
-        // Not a field write (2143): past the step store it re-pushes the range through
-        // `SetMinMaxValues`, which re-clamps and re-quantises the held value onto the new lattice
-        // and fires `OnValueChanged` if it moved — so this binding fires like the other two.
+        // Stores the step, then re-pushes the range as `SetMinMaxValues` does, so a held value
+        // moved onto the new step fires `OnValueChanged`.
         lua.create_function(|lua, (this, step): (Table, f32)| {
             let changed = with_slider(lua, &this, |s| s.set_value_step(step))?;
             fire_value_changed(lua, &this, changed)
@@ -174,27 +148,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `Enable`/`Disable`/`IsEnabled` WERE here and are GONE, with the `enabled` state they drove.
-    // **A 1.12 Slider has no enabled state at all**: the three names are registered once each, in
-    // the BUTTON table `0x879d00` (`0x77fef0`/`0x77ffd0`/`0x7800b0`), and the Slider's own LoadXML
-    // `0x789580` takes `drawLayer`/`minValue`/`maxValue`/`valueStep`/`defaultValue`/`orientation`
-    // and nothing else — so there was no way in
-    // from Lua *or* from XML, and the flag could only ever read `true`.
-    //
-    // They were a superset in PRESENCE, which is what 1189 records the cost of: a duck-typing addon
-    // that branches on `if widget.IsEnabled then` reads a Slider as a Button. Ours also answered a
-    // Lua BOOLEAN, which the reference has no query that does (decision 2118) — `IsEnabled 0x7800b0`
-    // is number-1/number-0 and never even nil.
-    //
-    // Removed rather than corrected because nothing calls them on a Slider receiver: a
-    // receiver-typed grep over this repo, `assets/ui`, the stock FrameXML/GlueXML and both addon
-    // corpora (110 top-20 + 219 vanilla) finds zero `slider*:Enable/Disable/IsEnabled` sites.
-    // `begin_drag` below lost its `enabled` gate with them — behaviour-neutral, since no caller
-    // could clear the flag.
+    // A 1.12 Slider has no enabled state: `Enable`/`Disable`/`IsEnabled` exist only in the Button
+    // table (`0x879d00`: `0x77fef0`, `0x77ffd0`, `0x7800b0`), so a Slider must not answer them.
 
-    // SetThumbTexture(path [, drawLayer]) | SetThumbTexture(r, g, b [, a]) — the same two forms as a
-    // region's SetTexture, targeting the thumb region (created on first use). Mirrors
-    // SetStatusBarTexture; the thumb defaults to the OVERLAY layer.
+    // `SetThumbTexture(path [, layer])` or `(r, g, b [, a])`, a region's two `SetTexture` forms, on
+    // the thumb region, created on first use.
     m.set(
         "SetThumbTexture",
         lua.create_function(
@@ -215,7 +173,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                         data.texture = Some(s.to_str()?.to_string());
                         data.fill = None;
                     }
-                    // A solid thumb writes the same slot the path form does — each clears the other.
+                    // A solid thumb and a path share one slot; each clears the other.
                     Value::Number(_) | Value::Integer(_) => {
                         data.texture = None;
                         data.fill = Some([
@@ -253,9 +211,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Fire `OnValueChanged(self, value)` if `changed` carries the new value (`Slider::LoadXML
-/// 0x789580`: the Slider's own script slot `+0x330`). Fired outside any model borrow; errors go
-/// to [`Model::errors`].
+/// Fire `OnValueChanged` (slot `+0x330`) when `changed` carries a new value, outside any model
+/// borrow; errors are recorded in [`Model::errors`].
 fn fire_value_changed(lua: &Lua, this: &Table, changed: Option<f32>) -> mlua::Result<()> {
     let Some(value) = changed else { return Ok(()) };
     let id = {
@@ -276,7 +233,6 @@ fn fire_value_changed(lua: &Lua, this: &Table, changed: Option<f32>) -> mlua::Re
     Ok(())
 }
 
-/// A Lua number-ish → f32 (nil/other → 0.0), for the color-form arguments.
 fn num_f32(v: &Value) -> f32 {
     match v {
         Value::Number(n) => *n as f32,
@@ -285,18 +241,11 @@ fn num_f32(v: &Value) -> f32 {
     }
 }
 
-// ── Thumb geometry + drag (decision 0250 §4/§5) ──────────────────────────────────────────────
+// ── Thumb geometry and drag ──────────────────────────────────────────────────────────────────
 
-/// A Slider's thumb rect: the thumb of size `thumb_size` placed at `fraction` along the slider `r`'s
-/// track and centered on the cross-axis. The thumb stays **inset** within the track (travel =
-/// trackLen − thumbLen), the way WoW scrollbar knobs visibly do. VERTICAL runs y-up-inverted —
-/// `fraction` 0 (value=min) sits the thumb flush at the **top** (a scrollbar at 0 is scrolled to the
-/// top), `fraction` 1 flush at the bottom. This is the single geometry source shared by `extract`
-/// (render) and [`begin_drag`] (hit-test), so render and input never disagree. Returns a [`Rect`] as
-/// `(bottom, left, top, right)`.
-///
-/// `thumb_size` is [`thumb_extent`]'s — the thumb region's OWN size getters, never its authored
-/// `<Size>` alone.
+/// The thumb's rect at `fraction` along the track, centred across it and inset so it travels
+/// `trackLen - thumbLen`; vertical puts fraction 0 at the top. Render and [`begin_drag`] both use
+/// it, so they never disagree. `thumb_size` is [`thumb_extent`]'s.
 pub(super) fn thumb_rect(r: Rect, thumb_size: (f32, f32), vertical: bool, fraction: f32) -> Rect {
     let (tw, th) = thumb_size;
     if vertical {
@@ -312,51 +261,27 @@ pub(super) fn thumb_rect(r: Rect, thumb_size: (f32, f32), vertical: bool, fracti
     }
 }
 
-/// The thumb's extent along both axes — **the thumb region's own `GetWidth`/`GetHeight`**, which
-/// is what the client asks for and is not the same thing as its authored `<Size>`.
-///
-/// `CSimpleSlider`'s pixel→value law reads the thumb through its geometry vtable
-/// (`0x789ba0`: `ff 50 1c call [eax+0x1c]` for the horizontal branch, `+0x20` for the vertical), and
-/// on a `CSimpleTexture` those slots are `0x770720`/`0x770790` — the **native-texel fallback**:
-/// authored span when it is non-zero on that axis, else the art's own texel span through the same
-/// `<AbsDimension>` converter, else `0.0` when there is no art at all (ours is
-/// [`super::region::virtual_span`], decision 1349).
-///
-/// Reading `RegionData::size` instead is what broke every Lua-built slider: `SetThumbTexture(path)`
-/// authors no size, all four stock `<ThumbTexture>`s declare one, and the old fallback — *the thumb
-/// fills the track* — is not a client behaviour at all. It smeared the knob over the whole bar and
-/// left `trackLen − thumbLen == 0`, i.e. a slider that cannot move (Dewdrop-2.0's popout, B-report).
-/// A thumb with **no region at all** is `None`: `0x789ba0` gates the value math on `+0x328` being
-/// non-null, so a thumbless slider takes the press and the capture but never warps.
+/// The thumb region's own width and height, as `0x789ba0` reads them through the texture's
+/// geometry slots (`[vtable+0x1c]`/`+0x20`, `0x770720`/`0x770790`): the authored span, else the
+/// art's texel span, else 0. `None` without a thumb region: `0x789ba0` gates the value math on
+/// `+0x328`, so a thumbless slider captures a press but never moves.
 fn thumb_extent(model: &Model, thumb: Option<crate::widget::RegionHandle>) -> Option<(f32, f32)> {
     Some(super::region::virtual_span(model, thumb?))
 }
 
-/// The in-flight thumb drag (decision 0250 §5): the slider being dragged + the grab offset
-/// [`slider_grab`] returned, so the thumb tracks the cursor without jumping. Engine C++-equivalent
-/// — no Lua, like the real client's scrollbar.
+/// The in-flight thumb drag and the grab offset [`slider_grab`] returned, so the thumb tracks the
+/// cursor without jumping.
 #[derive(Clone, Copy)]
 pub(crate) struct SliderDrag {
     pub(crate) slider: FrameHandle,
-    /// The grab, in **distance from the track's leading edge** — the axis-neutral frame
-    /// [`slider_grab`]/[`slider_fraction`] are stated in, so this arena's y-up rects and the glue
-    /// screens' y-down nodes run the identical arithmetic.
+    /// The grab as distance from the track's leading edge, the axis-neutral frame [`slider_grab`]
+    /// and [`slider_fraction`] share with the glue screens.
     pub(crate) grab_offset: f32,
 }
 
-/// On a LeftButton press at `(x, y)` whose hit frame is `hit`: if that frame is a Slider with a
-/// resolved rect, begin a drag capture (records [`Model::slider_drag`]). Where the press grabs is
-/// [`slider_grab`]'s to say — one law, shared with the glue lane's scrollbars, so an in-game bar
-/// and a character-screen bar cannot drift apart on feel.
-///
-/// There is no enabled gate: 1.12 gives a Slider no enabled state to gate on (see `install`'s note
-/// where `Enable`/`Disable`/`IsEnabled` used to be). A slider that should not take the press is
-/// kept off it the way the reference keeps anything off it — `EnableMouse(false)`, upstream of here
-/// in the hit test.
-///
-/// Returns `Some((frame id, new value))` when the press itself changed the value (the track jump)
-/// — the caller fires `OnValueChanged` outside the model borrow, exactly like [`drag_move`]'s
-/// changes — else `None`.
+/// On a LeftButton press on a Slider `hit`, capture a drag at the [`slider_grab`] offset, with no
+/// enabled gate since a 1.12 Slider has no enabled state. Returns `(frame id, new value)` when the
+/// press jumps the value, for the caller to fire `OnValueChanged` outside the model borrow.
 pub(super) fn begin_drag(
     model: &mut Model,
     hit: Option<FrameHandle>,
@@ -369,8 +294,8 @@ pub(super) fn begin_drag(
         Some(KindState::Slider(s)) => (s.vertical, s.fraction(), s.thumb),
         _ => return None,
     };
-    // No thumb region → `0x789ba0`'s `+0x328` gate: the press still captures (the dispatcher's
-    // `mov [ebx+0x80],esi` is unconditional), the value never moves.
+    // No thumb region: the press still captures, the dispatcher's store being unconditional, but
+    // the value never moves (`0x789ba0`, `+0x328`).
     let Some(size) = thumb_extent(model, thumb) else {
         model.slider_drag = Some(SliderDrag {
             slider: h,
@@ -380,9 +305,8 @@ pub(super) fn begin_drag(
     };
     let trect = thumb_rect(r, size, vertical, fraction);
     let on_thumb = point_in_rect(trect, x, y);
-    // Everything below is stated as distance from the TRACK'S LEADING EDGE — the end the thumb
-    // sits at when the value is `min`. Vertical tracks run downward from `r.top` in this y-up
-    // arena, so that distance is `top − y`; horizontal ones run rightward from `r.left`.
+    // Distances from the track's leading edge, where the thumb sits at `min`: `top - y` on a
+    // vertical track in this y-up arena, `x - left` on a horizontal one.
     let (cursor, thumb_lead, thumb_len) = if vertical {
         (r.top - y, r.top - trect.top, trect.top - trect.bottom)
     } else {
@@ -398,11 +322,8 @@ pub(super) fn begin_drag(
     drag_move(model, x, y)
 }
 
-/// On a pointer move at `(x, y)` while a thumb is captured: recompute the value from the cursor
-/// position via [`slider_fraction`] (absolute, drift-free — the grab offset keeps the same thumb
-/// point under the cursor) and store it. Returns `Some((frame id, new value))` if the value
-/// actually changed — the caller fires `OnValueChanged` outside the model borrow — else `None` (no
-/// capture, no travel, or no change).
+/// On a pointer move during a capture, set the value from the cursor through [`slider_fraction`];
+/// returns `(frame id, new value)` when it changed, for the caller to fire.
 pub(super) fn drag_move(model: &mut Model, x: f32, y: f32) -> Option<(u32, f32)> {
     let SliderDrag {
         slider,
@@ -414,13 +335,13 @@ pub(super) fn drag_move(model: &mut Model, x: f32, y: f32) -> Option<(u32, f32)>
         _ => return None, // slider destroyed mid-drag
     };
     let (tw, th) = thumb_extent(model, thumb)?;
-    // The same leading-edge frame [`begin_drag`] stored the grab in.
+    // The leading-edge frame `begin_drag` stored the grab in.
     let (cursor, track_extent, thumb_len) = if vertical {
         (r.top - y, r.height(), th)
     } else {
         (x - r.left, r.width(), tw)
     };
-    // `None` = nothing to scroll (a thumb as long as its track).
+    // `None` when the thumb is as long as its track.
     let fraction = slider_fraction(cursor, grab_offset, track_extent, thumb_len)?;
     let value = min + fraction * (max - min);
     let changed = match model.arena.frame_mut(slider).map(|f| &mut f.kind_state) {
diff --git a/crates/benilla-ui/src/script/social.rs b/crates/benilla-ui/src/script/social.rs
index 8e5473a5..8b58504a 100644
--- a/crates/benilla-ui/src/script/social.rs
+++ b/crates/benilla-ui/src/script/social.rs
@@ -1,23 +1,8 @@
-//! The social **Era API surface** — friends, ignores, and `/who` (decision 0668).
-//!
-//! The [`super::party`] shape exactly: the app pushes a [`SocialState`] snapshot built from its
-//! own wire mirror ([`UiScript::set_social`]) and the getters here read that plain data; every
-//! verb queues a [`SocialRequest`] the app drains ([`UiScript::take_social_requests`]) into the
-//! matching `CMSG_*` send. No ECS or net reach from the engine (decision 0068 §3).
-//!
-//! **The snapshot is already display-ready** — names, class name, zone name, the `<AFK>` tag —
-//! because every one of those is a *lookup the engine owns* in the real client too: the friend
-//! slot on the wire holds a bare guid + class/area **ids**, and `FriendList`'s formatter
-//! (`0x5ae160`) resolves them through the ObjectMgr name cache and the race/class/area GameTables
-//! before Lua ever sees them. Pushing ids here and resolving in Lua would invent a client the
-//! reference isn't.
-//!
-//! **Selection lives in the engine, not in Lua** — the reference keeps the selected friend and
-//! ignore as *guids* on the FriendList object (`+0x648` / `+0x720`, read back by
-//! `GetSelectedFriend` `0x5ad260` / `0x5ae510`), which is why `SetSelectedFriend(i)` here mutates
-//! the snapshot in place *and* queues the intent: the same Lua tick reads the new value back
-//! (`FriendsList_Update` does exactly that), and the app's own state follows so the next push
-//! agrees.
+//! The social API: friends, ignores and `/who`. The app pushes a display-ready [`SocialState`]
+//! (the reference's formatter `0x5ae160` also resolves names engine-side) and drains the queued
+//! [`SocialRequest`]s. Selection is engine state in the reference (guids at FriendList `+0x648` and
+//! `+0x720`, read back by `0x5ad260` and `0x5ae510`), so a set changes the snapshot at once and
+//! queues the change for the app.
 
 use mlua::{Lua, Value};
 
@@ -25,114 +10,83 @@ use super::binding_abi::string_arg;
 use super::who_sort::WhoSortChain;
 use super::Model;
 
-/// One friend row, already resolved for display — see the module doc on why the app resolves
-/// rather than the VM. Mirrors `GetFriendInfo`'s six returns in field order.
+/// One friend row in `GetFriendInfo`'s order; offline, the level is 0 and class and area empty.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct FriendInfo {
-    /// The character's name, from the name cache. Empty while the `CMSG_NAME_QUERY` is still in
-    /// flight — the FrameXML's own `if ( not name ) then name = UNKNOWN` covers that frame, so
-    /// the row shows "Unknown" rather than vanishing.
+    /// From the name cache; empty while the name query is in flight.
     pub name: String,
-    /// Level, `0` when offline (the wire sends no level for an offline friend).
     pub level: u32,
-    /// Localized class name ("Warrior"), empty when offline.
     pub class: String,
-    /// Zone name ("Elwynn Forest"), empty when offline or when the id has no `AreaTable` row.
+    /// The zone name, also empty when the id has no `AreaTable` row.
     pub area: String,
-    /// Online at all — `GetFriendInfo`'s fifth return, and what enables the Send Message /
-    /// Group Invite buttons.
     pub connected: bool,
-    /// The away tag as the friends-list template wants it: `""`, `"<AFK>"`, or `"<DND>"`.
+    /// The away tag the friends-list template takes: `""`, `"<AFK>"` or `"<DND>"`.
     pub status: String,
 }
 
-/// One `/who` row — `GetWhoInfo`'s six returns in order (note the wire's class/race order is
-/// swapped relative to this Lua-facing one: the API returns race *before* class).
+/// One `/who` row in `GetWhoInfo`'s order, names localized; race comes before class, where the
+/// wire has class first.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct WhoInfo {
     pub name: String,
     pub guild: String,
     pub level: u32,
-    /// Localized race name ("Night Elf").
     pub race: String,
-    /// Localized class name ("Druid").
     pub class: String,
-    /// Zone name.
     pub zone: String,
 }
 
-/// The social snapshot, pushed whole by the app whenever it changes ([`UiScript::set_social`]).
-/// `default()` is the fresh-login shape: no friends, no ignores, no `/who` run yet.
+/// The social snapshot the app pushes whole; the default is a fresh login's.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct SocialState {
-    /// The friend list, in the order the list frame shows it (the app sorts — the reference's
-    /// own `FriendList` comparator `0x5ada00` does the same engine-side).
+    /// In display order: the app sorts, as the reference's comparator `0x5ada00` does.
     pub friends: Vec<FriendInfo>,
-    /// The selected friend as a **1-based** index, `0` = none — `GetSelectedFriend`'s scale
-    /// (`0x5ad260` returns the stored slot + 1).
+    /// The selected friend, 1-based, 0 for none (`0x5ad260` returns the stored slot + 1).
     pub selected_friend: u32,
-    /// The ignore list: names only, which is all `GetIgnoreName` returns.
     pub ignores: Vec<String>,
-    /// The selected ignore, same 1-based scale.
+    /// The selected ignore, on the same scale.
     pub selected_ignore: u32,
-    /// The last `/who` answer's rows (≤ 49).
+    /// The last `/who` answer's rows, at most 49.
     pub who: Vec<WhoInfo>,
-    /// The last `/who` answer's *total* match count — `GetNumWhoResults`'s second return, which
-    /// can exceed `who.len()` and is what drives the "(50 displayed)" suffix.
+    /// The total match count, `GetNumWhoResults`'s second return; it can exceed `who.len()`.
     pub who_total: u32,
-    /// The `/who` sort chain ([`WhoSortChain`]) as the app holds it. Pushed with the rows because
-    /// `SortWho` has to promote it and re-sort **inside the binding** — the reference's
-    /// `WHO_LIST_UPDATE` is synchronous, so the redraw it triggers reads the new order before the
-    /// click script returns, a tick before the app's own copy could have pushed it back.
-    /// [`super::SocialRequest::SortWho`] carries the same click to the app, whose next push then
-    /// agrees. Same shape as `SetSelectedFriend`'s (module doc).
+    /// The `/who` sort chain, pushed so `SortWho` can re-sort before its synchronous redraw.
     pub who_sort: WhoSortChain,
 }
 
-/// Outbound social intents queued by the Era API, drained by the app
-/// ([`UiScript::take_social_requests`]). Plain data — [`super::party::PartyRequest`]'s twin.
+/// Outbound social intents, drained by the app.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum SocialRequest {
-    /// `ShowFriends()` — refresh the list (`CMSG_FRIEND_LIST`).
+    /// `ShowFriends()`: `CMSG_FRIEND_LIST`.
     RefreshFriends,
     /// `AddFriend(name)`.
     AddFriend(String),
-    /// `RemoveFriend(index)` — the friends frame's button, which addresses the *row*.
+    /// `RemoveFriend(index)`, from the friends frame's button.
     RemoveFriendIndex(u32),
-    /// `RemoveFriend(name)` — `/removefriend`, which addresses a name. One Era global takes
-    /// either, so the queue carries both shapes and the app resolves each to the guid the wire
-    /// wants.
+    /// `RemoveFriend(name)`, from `/removefriend`; the app resolves either shape to the guid.
     RemoveFriendName(String),
     /// `AddIgnore(name)`.
     AddIgnore(String),
     /// `DelIgnore(name)`.
     DelIgnore(String),
-    /// `AddOrDelIgnore(name)` — `/ignore`'s toggle: ignore if not ignored, un-ignore if it is.
-    /// The app decides which, because only it holds the list.
+    /// `AddOrDelIgnore(name)`, `/ignore`'s toggle; the app decides which, as it holds the list.
     ToggleIgnore(String),
-    /// `SetLookingForGroup(...)` committed a change: the slots as stored and the comment, for
-    /// `CMSG_SET_LOOKING_FOR_GROUP` (1961).
+    /// A changed `SetLookingForGroup`: slots and comment for `CMSG_SET_LOOKING_FOR_GROUP`.
     SetLookingForGroup { slots: [u32; 3], comment: String },
-    /// `SetSelectedFriend(index)` — mirrored into the app so the next push agrees.
+    /// `SetSelectedFriend(index)`, mirrored so the next push agrees.
     SelectFriend(u32),
     /// `SetSelectedIgnore(index)`.
     SelectIgnore(u32),
-    /// `SendWho(filter)` — the raw filter string as typed; parsing it into wire fields needs the
-    /// DBCs, so it happens app-side.
+    /// `SendWho(filter)`, the raw filter; parsing it needs the DBCs, so the app does it.
     Who(String),
-    /// `SortWho(sortType)` — `"name"`/`"level"`/`"class"`/`"zone"`/`"guild"`/`"race"`, the raw
-    /// argument as the click passed it. Sorting is client-side and the binding has **already**
-    /// done it to the snapshot ([`SocialState::who_sort`]); this carries the same click to the
-    /// app so its authoritative chain promotes identically and the next push agrees.
+    /// `SortWho(sortType)`, the raw argument; the binding has already sorted the snapshot.
     SortWho(String),
-    /// `SetWhoToUI(flag)` — where the *next* `/who` answer goes: the Who frame (true) or the chat
-    /// frame (false). The WhoFrame's own OnShow/OnHide drive it.
+    /// `SetWhoToUI(flag)`: the next `/who` answer goes to the Who frame (true) or chat (false).
     SetWhoToUi(bool),
 }
 
 impl super::UiScript {
-    /// Push the social snapshot, replacing whatever was there. A bare setter — firing
-    /// `FRIENDLIST_UPDATE`/`IGNORELIST_UPDATE`/`WHO_LIST_UPDATE` on the edges is the app's job.
+    /// Replace the social snapshot; firing `FRIENDLIST_UPDATE` and kin is the app's job.
     pub fn set_social(&mut self, state: SocialState) {
         self.model_mut().social = state;
     }
@@ -142,9 +96,7 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().social_requests)
     }
 
-    /// Queue an intent from the app side — the slash commands. In the reference these ARE Lua
-    /// (`SlashCmdList["FRIENDS"]` calls `AddFriend`, …); benilla parses slash lines in Rust, so
-    /// the same intents enter the same queue here. [`super::duel`]'s `queue_duel_request` twin.
+    /// Queue an intent from the app side.
     pub fn queue_social_request(&mut self, request: SocialRequest) {
         self.model_mut().social_requests.push(request);
     }
@@ -154,8 +106,8 @@ impl super::UiScript {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // ── The friend list ──────────────────────────────────────────────────────────────────────
-    // GetNumFriends() → how many friends are listed (`0x5ad000` over CountFriends `0x5ae490`).
+    // ── The friend list ──
+    // GetNumFriends(): `0x5ad000` over CountFriends `0x5ae490`.
     g.set(
         "GetNumFriends",
         lua.create_function(|lua, ()| {
@@ -164,9 +116,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetFriendInfo(index) → name, level, class, area, connected, status (`0x5ad060`). An index
-    // past the end returns nothing at all — the FrameXML tests `if ( not name )`, so nil-per-
-    // return is the shape it expects, not an error.
+    // GetFriendInfo(index) (`0x5ad060`): an index past the end answers nils, not an error;
+    // FrameXML tests `if ( not name )`.
     g.set(
         "GetFriendInfo",
         lua.create_function(|lua, index: i64| {
@@ -186,7 +137,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 Value::Integer(i64::from(friend.level)),
                 Value::String(lua.create_string(&friend.class)?),
                 Value::String(lua.create_string(&friend.area)?),
-                // `connected` is the era 1/nil boolean the list frame branches on.
                 if friend.connected {
                     Value::Integer(1)
                 } else {
@@ -197,7 +147,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSelectedFriend() → the 1-based selected row, 0 when nothing is selected.
     g.set(
         "GetSelectedFriend",
         lua.create_function(|lua, ()| {
@@ -206,8 +155,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetSelectedFriend(index) — mutate now (the caller reads it back this tick) and mirror the
-    // intent to the app (module doc: selection is engine state in the reference too).
+    // SetSelectedFriend(index): set now, since `FriendsList_Update` reads it back in the same
+    // call, and queue it for the app.
     g.set(
         "SetSelectedFriend",
         lua.create_function(|lua, index: i64| {
@@ -221,15 +170,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The LFG pair, as the bytes define it (`GetLookingForGroup 0x4e95d0` / `SetLookingForGroup
-    // 0x4e96b0`; decision 1961 — which corrects 1959's flag): the stock 1.12.1 FrameXML never
-    // calls either (FriendsFrame.xml's two call sites sit inside its l.1212-1301 XML comment), so
-    // this is an addon surface.
-    //
-    // `GetLookingForGroup()` → FOUR values: the three slot NAMES — each nil for a slot word whose
-    // id maps to nothing, and the reference's own pack (below) leaves every slot word 0, so nil
-    // is the only value a name can take here — then the comment, always a string. Never a
-    // number, never `1|nil`.
+    // The LFG pair (`0x4e95d0`, `0x4e96b0`) is for addons: stock FrameXML's only calls sit inside
+    // an XML comment. GetLookingForGroup() → the three slot names, each nil as the pack below
+    // always stores 0, then the comment string.
     g.set(
         "GetLookingForGroup",
         lua.create_function(|lua, ()| {
@@ -242,17 +185,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             ]))
         })?,
     )?;
-    // `SetLookingForGroup(type1, entry1, type2, entry2, type3, entry3, comment)` → nothing. Up to
-    // three pairs, read at arguments 1/3/5 and 2/4/6; the loop ENDS (it does not skip a pair) on
-    // a non-number type, a type >= 6, or an entry at or past the per-type eligible count, and the
-    // word it stores is `(type << 24) & entry` — an AND where every consumer decodes an OR
-    // (`0x4e9713`), so the stored word is 0 for every admissible input. Which is why the
-    // eligible-count table is not modelled: with the pack as it is, no admissible pair can store
-    // anything but 0, and an inadmissible one ends the loop leaving 0 — the slots never change.
-    // The comment is gated on argument 4 being a number or a string (`lua_isstring(L, 4)`) and
-    // read from argument 7 (`lua_tostring(L, 7)`, nil for an absent one); both immediates raw.
-    // The commit stores what changed and sends `CMSG_SET_LOOKING_FOR_GROUP` only then — so only a
-    // changed comment ever sends. `SStrCopy(…, 0x80)`: the comment keeps 127 bytes.
+    // SetLookingForGroup(type1, entry1, type2, entry2, type3, entry3, comment): the loop over the
+    // pairs ends at a non-number type or one >= 6. The stored word is `(type << 24) & entry`
+    // (`0x4e9713`), an AND every reader decodes as an OR, so an admissible pair stores 0; the
+    // per-type eligible-count check that also ends the reference's loop is not modelled. The
+    // comment is argument 7, read only when argument 4 passes `lua_isstring`, and keeps 127 bytes
+    // (`SStrCopy(…, 0x80)`). `CMSG_SET_LOOKING_FOR_GROUP` goes out only on a change.
     g.set(
         "SetLookingForGroup",
         lua.create_function(|lua, args: mlua::MultiValue| {
@@ -272,7 +210,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     break;
                 }
                 let entry = number(&arg(i + 1)).unwrap_or(0.0).trunc();
-                // `(type << 24) & entry`, the reference's own pack.
+                // `&`, not `|`: the reference's own pack.
                 *slot = ((ty as u32) << 24) & (entry as i64 as u32);
             }
             let comment = match arg(4) {
@@ -318,7 +256,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ShowFriends() — ask the server for the list again.
     g.set(
         "ShowFriends",
         lua.create_function(|lua, ()| {
@@ -328,8 +265,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // AddFriend(name) — an empty name is dropped here rather than sent: the server answers a
-    // blank lookup with nothing at all, so it would look like a hang.
+    // AddFriend(name): a blank name is not sent, as vmangos drops it without a reply
+    // (`MiscHandler.cpp:468`).
     g.set(
         "AddFriend",
         lua.create_function(|lua, name: String| {
@@ -341,8 +278,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // RemoveFriend(indexOrName) — the one global with two callers of different shapes (the
-    // frame's button passes a row index, /removefriend a name).
+    // RemoveFriend(indexOrName): the friends frame passes a row, `/removefriend` a name.
     g.set(
         "RemoveFriend",
         lua.create_function(|lua, who: Value| {
@@ -363,8 +299,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ── The ignore list ──────────────────────────────────────────────────────────────────────
-    // GetNumIgnores() → CountIgnores `0x5ae550` (the 25 slots at +0x650).
+    // ── The ignore list ──
+    // GetNumIgnores(): CountIgnores `0x5ae550`, over the 25 slots at `+0x650`.
     g.set(
         "GetNumIgnores",
         lua.create_function(|lua, ()| {
@@ -373,9 +309,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetIgnoreName(index) → the name, or nil past the end. The ignore list frame calls this for
-    // all 20 of its rows every update, most of them empty — nil is the ordinary case, not an
-    // error.
     g.set(
         "GetIgnoreName",
         lua.create_function(|lua, index: i64| {
@@ -390,8 +323,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSelectedIgnore() / SetSelectedIgnore(index) — the friend pair's twin (`0x5ae630` /
-    // `0x5ae5f0`).
+    // GetSelectedIgnore / SetSelectedIgnore (`0x5ae630` / `0x5ae5f0`), as the friend pair.
     g.set(
         "GetSelectedIgnore",
         lua.create_function(|lua, ()| {
@@ -412,7 +344,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // AddIgnore / DelIgnore / AddOrDelIgnore(name).
     for (global, make) in [
         ("AddIgnore", SocialRequest::AddIgnore as fn(String) -> _),
         ("DelIgnore", SocialRequest::DelIgnore as fn(String) -> _),
@@ -433,9 +364,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // ── /who ─────────────────────────────────────────────────────────────────────────────────
-    // GetNumWhoResults() → displayed, total. The second return is the server's true match count,
-    // which is why the frame can say "132 players total (50 displayed)".
+    // ── /who ──
+    // GetNumWhoResults() → displayed, total, the server's full match count.
     g.set(
         "GetNumWhoResults",
         lua.create_function(|lua, ()| {
@@ -447,7 +377,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetWhoInfo(index) → name, guild, level, race, class, zone.
     g.set(
         "GetWhoInfo",
         lua.create_function(|lua, index: i64| {
@@ -476,7 +405,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SendWho(filter) — the filter string as typed, parsed app-side.
     g.set(
         "SendWho",
         lua.create_function(|lua, filter: Option<String>| {
@@ -488,24 +416,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `SortWho(sortType) 0x5ad890` — the column-header and dropdown sorts, and three things at
-    // once (decision 2030):
-    //
-    //  1. **promote** the key into the seven-slot chain, flipping its direction only if it was
-    //     already at the front — so a repeated click on the same header REVERSES;
-    //  2. **sort right here**, through the chain-walking comparator; and
-    //  3. fire `WHO_LIST_UPDATE` **synchronously**, inside the binding (`0x5ad9ed
-    //     mov ecx,0x184; call SignalEvent 0x703e50`), so `FriendsFrame_OnEvent` has already
-    //     re-read the list through `GetWhoInfo` by the time the header's OnClick plays its sound.
-    //     Queueing it would redraw a tick late — the visible half of B365.
-    //
-    // The intent still goes to the app, which owns the same chain and re-sorts the answers it
-    // receives; sorting the snapshot here is what makes the synchronous redraw show the new
-    // order, exactly as `SetSelectedFriend` mutates the snapshot it also queues (module doc).
-    //
-    // Zero return values, and a non-string/number argument RAISES with the client's own typo
-    // (`.rdata 0x85db88`) rather than answering nil — `0x5ad898`'s `0x6f3510` guard into
-    // `luaL_error`, [`super::binding_abi`]'s shape A.
+    // SortWho(sortType) (`0x5ad890`): promotes the key in the seven-slot chain, reversing it if
+    // it is already in front, sorts the list, and fires `WHO_LIST_UPDATE` synchronously
+    // (`0x5ad9ed`, `SignalEvent` `0x703e50`), so the list redraws before the click's sound. The
+    // app gets the same click for its own chain. Returns nothing; an argument neither string nor
+    // number raises with the client's own typo (`0x85db88`, `0x5ad898`'s `0x6f3510` guard).
     g.set(
         "SortWho",
         lua.create_function(|lua, sort_type: Value| {
@@ -524,8 +439,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetWhoToUI(flag) — the WhoFrame's OnShow/OnHide. Era passes 0/1, so anything but a falsey
-    // 0/nil is "the frame wants them".
+    // SetWhoToUI(flag): the Who frame passes 1 on show and 0 on hide; nil, false and 0 are off.
     g.set(
         "SetWhoToUI",
         lua.create_function(|lua, flag: Value| {
@@ -549,8 +463,7 @@ fn friend_at(friends: &[FriendInfo], index: i64) -> Option<&FriendInfo> {
     usize::try_from(index - 1).ok().and_then(|i| friends.get(i))
 }
 
-/// Clamp a selection index to `0..=len` — `0` means "nothing selected", and a row past the end
-/// selects nothing rather than a phantom.
+/// A selection index in `1..=len`, else 0, nothing selected.
 fn clamp_index(index: i64, len: usize) -> u32 {
     if index >= 1 && index <= len as i64 {
         index as u32
@@ -575,9 +488,7 @@ mod tests {
         }
     }
 
-    /// A VM seeded with two hits and a watcher that records the order it can SEE from inside the
-    /// `WHO_LIST_UPDATE` handler — which is the only vantage point that can tell a synchronous
-    /// fire from a queued one.
+    /// Two `/who` hits and a `WHO_LIST_UPDATE` handler that records the order it sees.
     fn seated() -> UiScript {
         let mut s = UiScript::new().unwrap();
         s.run(
@@ -607,10 +518,7 @@ mod tests {
         s
     }
 
-    /// **B365.** `SortWho` sorts the list it already holds, fires `WHO_LIST_UPDATE`
-    /// **synchronously** so the handler reads the NEW order (`0x5ad9ed`, `SignalEvent 0x703e50`
-    /// running every listener inline), and queues the same click for the app. A queued event
-    /// would leave `order` one click stale here — which is exactly what the bug looked like.
+    /// A queued event would leave `order` one click stale.
     #[test]
     fn sort_who_sorts_in_place_and_fires_the_event_synchronously() {
         let mut s = seated();
@@ -628,14 +536,11 @@ mod tests {
             vec![SocialRequest::SortWho("name".into())],
             "and the app hears the same click, so its copy of the chain follows"
         );
-        // Zero return values (`0x5ad9f8 xor eax,eax; ret`).
+        // Returns nothing (`0x5ad9f8`, `xor eax,eax; ret`).
         assert_eq!(s.arity(r#"SortWho("name")"#).unwrap(), 0);
         assert!(s.errors().is_empty(), "{:?}", s.errors());
     }
 
-    /// The visible half of the report: **clicking the same header twice reverses**, and clicking
-    /// a different one in between does not undo that — the direction is remembered per key and
-    /// flipped only when the key was already at the front of the chain.
     #[test]
     fn a_repeated_header_click_reverses_and_the_direction_is_remembered() {
         let s = seated();
@@ -653,8 +558,7 @@ mod tests {
         s.run(r#"SortWho("level")"#).unwrap();
         assert_eq!(s.eval::<String>("return order").unwrap(), "Erdrin,Galas,");
 
-        // Back to name: promoted from slot 1, so it CARRIES its descending direction rather than
-        // flipping to ascending.
+        // Back to name, promoted from slot 1: it keeps its descending direction.
         s.run(r#"SortWho("name")"#).unwrap();
         assert_eq!(
             s.eval::<String>("return order").unwrap(),
@@ -668,9 +572,8 @@ mod tests {
         );
     }
 
-    /// The argument ABI: a number is stringified and falls through to the name key; anything that
-    /// is neither number nor string RAISES with the client's own misspelt usage string
-    /// (`.rdata 0x85db88`), abandoning the caller's statement rather than answering nil.
+    /// A number is stringified and falls to the name key; anything else raises with the client's
+    /// misspelt usage string (`0x85db88`).
     #[test]
     fn sort_who_takes_the_reference_argument_abi() {
         let mut s = seated();
@@ -694,9 +597,6 @@ mod tests {
         );
     }
 
-    /// The LFG pair as the bytes define it (1961, correcting 1959): four string-or-nil returns,
-    /// the slots zeroed by the reference's own pack, the comment from argument 7 behind the gate
-    /// on argument 4, and the wire only on a change.
     #[test]
     fn the_lfg_pair_stores_the_comment_and_sends_only_on_a_change() {
         let mut s = UiScript::new().unwrap();
@@ -706,7 +606,7 @@ mod tests {
                 "local a, b, c, d = GetLookingForGroup() return a == nil and b == nil and c == nil and d == \"\""
             )
             .unwrap());
-        // Three admissible pairs: every word packs to 0, nothing changed, nothing sent.
+        // Three admissible pairs: every word packs to 0, so nothing changes or sends.
         s.run("SetLookingForGroup(1, 3, 3, 12, 5, 0)").unwrap();
         assert!(
             s.take_social_requests().is_empty(),
@@ -727,11 +627,10 @@ mod tests {
                 .unwrap(),
             "LF2M UBRS"
         );
-        // The same comment again: no change, no send.
         s.run(r#"SetLookingForGroup(1, 3, 3, 12, 5, 0, "LF2M UBRS")"#)
             .unwrap();
         assert!(s.take_social_requests().is_empty());
-        // Fewer than four arguments: the comment at 7 is never read.
+        // Argument 4 nil: the comment at 7 is not read.
         s.run(r#"SetLookingForGroup(1, 3, nil, nil, nil, nil, "ignored")"#)
             .unwrap();
         assert!(s.take_social_requests().is_empty());
diff --git a/crates/benilla-ui/src/script/sound.rs b/crates/benilla-ui/src/script/sound.rs
index 6158e701..1883d433 100644
--- a/crates/benilla-ui/src/script/sound.rs
+++ b/crates/benilla-ui/src/script/sound.rs
@@ -1,95 +1,63 @@
-//! The `PlaySound`/`PlaySoundFile` bindings — the first **Lua→app intent queue** (decisions
-//! 0068 §3 / 0070 §4).
+//! The sound bindings: `PlaySound`, `PlaySoundFile`, `PlayMusic` and `StopMusic` each queue a
+//! plain request for the app to drain, since the engine does not touch the app's mixer.
 //!
-//! The engine must not touch the app's systems (the same seam that keeps [`super::unit`]'s
-//! bindings reading a pushed snapshot), so an outbound *action* can't call the mixer either:
-//! `PlaySound` pushes a plain [`SoundRequest`] onto a queue in [`super::Model`], and the app
-//! drains it each frame via [`UiScript::take_sounds`](super::UiScript::take_sounds) into its kit
-//! player. This queue-drain shape is the pattern every Lua→app intent follows (`CastSpell`,
-//! `UseAction`, … ride the same seam as they land).
+//! `PlaySound` takes a kit name, as the reference's binding does (`0x4586d0` reaches only
+//! `PlaySoundByName`, `0x458030`), and also Era's numeric kit id, which 1.12's binding does not
+//! take (the client plays a kit id internally through `0x458850`). Both verbs answer Era's
+//! `willPlay, soundHandle`, true and nil, not 1.12's shapes: the reference's `PlaySound` answers
+//! nothing and its `PlaySoundFile` one value (`reference/1.12-shapes.tsv`).
 //!
-//! Surface: the Era signature `PlaySound(soundKitID[, channel, forceNoDuplicates])` (addons pass
-//! numeric `SOUNDKIT.*` ids), plus the 1.12-native by-name form `PlaySound("KitName")` — the
-//! client resolved both (`PlaySoundById 0x458850` / `PlaySoundByName 0x458030`), and our kit
-//! player keeps both entries. Returns `willPlay, soundHandle`: `willPlay` reports "queued" —
-//! whether the kit actually plays is decided at drain time by the kit player's own gates
-//! (audibility, duplicate suppression), which the client also treats as silent non-errors; the
-//! handle is nil (no stop-by-handle surface yet). The `channel`/`forceNoDuplicates` extras are
-//! accepted and ignored for now — the kit's own `SoundType`/flags decide category and dedup.
-//!
-//! `PlaySoundFile("Sound\\...\\file.wav")` is the sibling by-path form (the 1.12 client resolves
-//! it through the same file layer as kit entries — MPQ chain, loose files shadowing): no kit, so
-//! no gates and no variation; same queue, same returns.
-//!
-//! `PlayMusic("Sound\\Music\\...\\track.mp3")` / `StopMusic()` are the **music** pair, and what
-//! makes them their own queue ([`MusicRequest`]) rather than two more [`SoundRequest`]s is that
-//! they are a different *slot*, not a different sound: the reference hands the Lua caller a music
-//! stream of its own (`[0xb06ccc]`, opened inside `0x460450` at `0x4604a7`) beside the zone
-//! track's (`[0xb06cc4]`), and it is one of the client's only two infinitely-looping streams
-//! (`SetLoopCount(-1)`, the single call site `0x7a5592`; the other is the glue theme). The app
-//! drains this queue into that slot, never into the kit player. Both bindings answer **nothing**
-//! — `reference/1.12-shapes.tsv` types the pair at arity 0, `exact` — so neither returns the
-//! `willPlay, soundHandle` pair `PlaySound` does.
-//!
-//! **They are one engine verb with one branch, which is why this queue carries an `Option`.**
-//! `StopMusic 0x458770` is four instructions — `xor ecx,ecx; call 0x460450; xor eax,eax; ret` —
-//! so *stopping is playing a NULL name*, and `0x460450` (two callers image-wide, no
-//! address-takes) is the whole of both verbs. What that shared head does before the branch, and
-//! what only the play arm does after it, is the app side's business (`sound::zone`'s
-//! `set_lua_music`) — the point here is that the two bindings are not independent, and a
-//! `MusicRequest` is the argument, not the verb.
+//! The music pair drives its own slot: the reference gives Lua a stream of its own (`[0xb06ccc]`,
+//! opened in `0x460450` at `0x4604a7`) beside the zone track's (`[0xb06cc4]`), one of the client's
+//! two endlessly looping streams (`0x7a5592`). `StopMusic` (`0x458770`) is `0x460450` with a null
+//! name, so a [`MusicRequest`] is the argument, not the verb. Neither answers anything.
 
 use mlua::{Lua, Value};
 
 use super::Model;
 
-/// One queued `PlaySound` intent, drained by the app (plain data — the engine-free seam).
+/// One queued sound for the app's kit player.
 #[derive(Clone, Debug, PartialEq)]
 pub enum SoundRequest {
-    /// `PlaySound(id)` — a `SoundEntries` kit id (the Era `SOUNDKIT.*` form).
+    /// `PlaySound(id)`: a `SoundEntries` kit id, Era's form.
     KitId(u32),
-    /// `PlaySound("name")` — a kit name (the 1.12 `PlaySoundByName` form).
+    /// `PlaySound("name")`: a kit name, the 1.12 form.
     KitName(String),
-    /// `PlaySoundFile("path")` — a raw file path, no kit.
+    /// `PlaySoundFile("path")`: a file path, no kit.
     File(String),
 }
 
-/// One queued Lua **music** intent — the `PlayMusic`/`StopMusic` pair, drained by the app's music
-/// slot (module docs: a different slot, not a different sound, and **one verb with a NULL arm**).
+/// One queued `PlayMusic` or `StopMusic`, for the app's Lua music slot.
 #[derive(Clone, Debug, PartialEq)]
 pub enum MusicRequest {
-    /// `PlayMusic("path")` — the name arm: start the caller's own looping stream on the slot.
+    /// `PlayMusic("path")`: start the caller's looping stream.
     Play(String),
-    /// `StopMusic()` — `0x460450`'s NULL arm, the same call with no name.
+    /// `StopMusic()`: `0x460450` with no name.
     Stop,
 }
 
 impl super::UiScript {
-    /// Drain the sounds queued by `PlaySound` since the last call. The app plays each through its
-    /// kit player (2D — UI sounds have no world position).
-    /// Queue a kit play from the APP side (the client's C++-fired UI sounds — QUESTADDED on a
-    /// log add, QUESTCOMPLETED on the turn-in packet — which no Lua handler owns). Drained by the
-    /// same [`UiScript::take_sounds`] as every Lua `PlaySound`.
+    /// Queue a kit play from the app side, for the UI sounds the client fires from C++
+    /// (`QUESTADDED` on a log add, `QUESTCOMPLETED` on the turn-in) that no Lua handler owns.
     pub fn queue_sound_kit(&mut self, name: &str) {
         self.model_mut()
             .sound_queue
             .push(SoundRequest::KitName(name.to_string()));
     }
 
+    /// Drain the queued sounds; the app plays each in 2D, as UI sounds have no world position.
     pub fn take_sounds(&mut self) -> Vec<SoundRequest> {
         std::mem::take(&mut self.model_mut().sound_queue)
     }
 
-    /// Drain the `PlayMusic`/`StopMusic` intents queued since the last call, **in call order** —
-    /// which this queue has to preserve in a way the kit one does not: two calls in a frame are a
-    /// start and a stop of the same slot, and the order is the difference between a track and
-    /// silence.
+    /// Drain the music intents in call order: a play and a stop in one frame are a track or
+    /// silence by their order.
     pub fn take_music(&mut self) -> Vec<MusicRequest> {
         std::mem::take(&mut self.model_mut().music_queue)
     }
 }
 
-/// Register the `PlaySound` and `PlaySoundFile` globals.
+/// Register the sound and music globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     lua.globals().set(
         "PlaySoundFile",
@@ -114,36 +82,29 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 _ => None,
             };
             let Some(req) = req else {
-                // The client raises a usage error on a bad argument; in a handler this lands in
-                // the host's collected script errors, never a panic.
+                // A bad argument raises a usage error, as the reference's does.
                 return Err(mlua::Error::runtime(
                     "Usage: PlaySound(soundKitID or \"KitName\")",
                 ));
             };
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // `PlaySoundByName 0x458030`'s first act: read the UI-load suppression depth
-            // (`0x458046`) and bail at `0x45804d` if it is non-zero — BEFORE the
-            // `MasterSoundEffects` CVar and before the kit-hash lookup. So the call is dropped
-            // rather than muted or queued, and the binding still answers as if it had played.
-            // NAME-keyed only: the id-keyed entry (`0x457fb0`) has no such gate, which is why the
-            // arm above pushes unconditionally.
+            // During the UI load a by-name play is dropped before any other gate (`0x458046`,
+            // `0x45804d`), while the binding still answers; the id entry (`0x457fb0`) has no
+            // such gate.
             let suppressed = matches!(req, SoundRequest::KitName(_)) && model.sound_suppression > 0;
             if !suppressed {
                 model.sound_queue.push(req);
             }
             drop(model);
-            // willPlay (queued), soundHandle (nil — module docs).
             Ok((true, Value::Nil))
         })?,
     )?;
     lua.globals().set(
         "PlayMusic",
         lua.create_function(|lua, args: mlua::MultiValue| {
-            // `0x458720`'s own argument shape, byte for byte: `lua_isstring 0x6f3510` then
-            // `lua_tostring 0x6f3690` — so a **number is accepted and stringified**
-            // (`PlayMusic(42)` asks for the file `"42"`), and everything else, *absent included*,
-            // raises this exact literal (`0x835f7c`) through `lua_error 0x458758`. No
-            // normalisation, no extension appended: the pointer goes verbatim to the file layer.
+            // `0x458720`: `lua_isstring` (`0x6f3510`), then `lua_tostring` (`0x6f3690`), so a
+            // number becomes a file name and anything else raises this literal (`0x835f7c`,
+            // `0x458758`); the path goes to the file layer verbatim.
             let path = super::binding_abi::string_arg(
                 lua,
                 args.front().cloned().unwrap_or(Value::Nil),
@@ -158,8 +119,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
     lua.globals().set(
         "StopMusic",
-        // Takes no argument at all (`0x458770`, arity and argc both 0), so an extra one is
-        // ignored rather than refused — `()` reads a bare call and any call alike.
+        // Reads no argument (`0x458770`), so an extra one is ignored.
         lua.create_function(|lua, ()| {
             lua.app_data_mut::<Model>()
                 .expect("model app_data")
@@ -182,7 +142,7 @@ mod tests {
             .eval("local w, h = PlaySound(1234) return w, h == nil")
             .unwrap();
         assert!(will_play && handle_is_nil);
-        // Era extras accepted and ignored; the by-name 1.12 form works too.
+        // Era's extra arguments are ignored.
         s.run(r#"PlaySound(841, "SFX", true)"#).unwrap();
         s.run(r#"PlaySound("GAMEOBJECT_DOOROPEN")"#).unwrap();
         s.run(r#"PlaySoundFile("Sound\\Doodad\\BellTollHorde.wav")"#)
@@ -197,16 +157,13 @@ mod tests {
                 SoundRequest::File("Sound\\Doodad\\BellTollHorde.wav".into()),
             ]
         );
-        // Drained: the queue is empty until the next PlaySound.
         assert!(s.take_sounds().is_empty());
     }
 
     #[test]
     fn the_music_pair_queues_in_call_order_and_answers_nothing() {
         let mut s = UiScript::new().unwrap();
-        // Arity 0 for both (`reference/1.12-shapes.tsv`, `exact`) — not `PlaySound`'s pair.
-        // Counted with `table.getn` over a table constructor: this VM is 1.12's Lua **5.0**
-        // surface, which has no `select`.
+        // Counted with `table.getn`: Lua 5.0 has no `select`.
         let (played, stopped): (usize, usize) = s
             .eval(
                 r#"return table.getn({PlayMusic("Sound\\Music\\x.mp3")}),
@@ -226,15 +183,10 @@ mod tests {
                 MusicRequest::Stop,
             ]
         );
-        // Drained: the queue is empty until the next call.
         assert!(s.take_music().is_empty());
-        // And it is its own queue — the kit player never sees a music intent.
         assert!(s.take_sounds().is_empty());
     }
 
-    /// `PlayMusic`'s argument is `lua_isstring` → `lua_tostring` (`0x6f3510`/`0x6f3690`), so a
-    /// **number is a filename** and everything else — absent included — raises the binding's own
-    /// literal. `StopMusic` reads no argument at all, so an extra one cannot be a usage error.
     #[test]
     fn playmusic_takes_a_string_or_a_number_and_stopmusic_takes_anything() {
         let mut s = UiScript::new().unwrap();
@@ -244,7 +196,7 @@ mod tests {
         assert!(s.run("PlayMusic({})").is_err());
         assert!(s.take_music().is_empty(), "a raise queues nothing");
 
-        // Coerced, not refused: the reference asks the file layer for `"42"` and gets silence.
+        // The reference asks the file layer for `"42"` and plays nothing.
         s.run("PlayMusic(42)").unwrap();
         s.run("StopMusic(1, 2)").unwrap();
         assert_eq!(
diff --git a/crates/benilla-ui/src/script/spellbook.rs b/crates/benilla-ui/src/script/spellbook.rs
index 13f0f621..0fdf347a 100644
--- a/crates/benilla-ui/src/script/spellbook.rs
+++ b/crates/benilla-ui/src/script/spellbook.rs
@@ -1,52 +1,13 @@
-//! The spellbook (decision 0216 §8, slice 5) — the spell **source** for the cursor payload
-//! system: a read-only book model the app builds from `PlayerActions.spells`
-//! (`SMSG_INITIAL_SPELLS`), the same two-way seam shape as [`super::merchant`]/[`super::action`]:
-//! the app pushes a **book snapshot** ([`UiScript::set_spellbook`] — tabs + the flat slot list,
-//! already resolved to name/rank/icon/passive by the app's `benilla_formats::SpellCatalog` ×
-//! skill-line join), and `CastSpell`/`PickupSpell` queue outbound intents the app drains
-//! ([`UiScript::take_spell_casts`] / the cursor seam's own `CursorPayload::Spell` arm — decision
-//! 0216 §1). The engine holds no spell KNOWLEDGE (icons/ranks/skill lines are the app's job) — a
-//! slot is "a spell id, a name, a rank, a texture, and a passive bit".
+//! The spellbook bindings, over a book the app pushes (tabs and a flat slot list, already resolved
+//! to name, rank, icon and passive); `CastSpell` and `PickupSpell` queue intents the app drains.
 //!
-//! ## The book-id seam (decision 0218 §4's byte-verified 0-based book slot)
+//! FrameXML passes every binding a 1-based book id (`SpellBook_GetSpellID`), and the reference's
+//! marshaller (`0x4b3ec0`) subtracts 1, as [`slot_index`] does. `BOOKTYPE_PET` selects the pet's
+//! slot list, fed from `SMSG_PET_SPELLS`, where `PickupSpell` and `CastSpell` produce a pet action
+//! word and a `CMSG_PET_ACTION` instead.
 //!
-//! The ref's own FrameXML computes a **1-based, per-tab-cumulative "book id"**
-//! (`SpellBookFrame.lua`'s `SpellBook_GetSpellID`: `buttonId + tabOffset + 12*(page-1)`, where
-//! `buttonId` is a spell button's own 1..12 `id=` attribute and `tabOffset` is
-//! `GetSpellTabInfo`'s own `offset` return) and passes that SAME id, unmodified, to every one of
-//! `GetSpellName`/`GetSpellTexture`/`IsSpellPassive`/`CastSpell`/`PickupSpell`. 0218 §4 byte-read
-//! `PickupSpell`'s own argument as a **0-based book slot** — so the real client's Lua↔C++ glue
-//! does the `-1` itself, invisibly to FrameXML. This engine keeps the ref's exact Lua-facing
-//! convention (every binding below takes the SAME 1-based-cumulative `id` a transcribed
-//! `SpellBookFrame.xml` computes and passes verbatim, so the transcription needs no special
-//! casing) and does the byte-verified `-1` at THIS one seam ([`slot_index`]) before indexing
-//! [`SpellBookState::slots`] (0-based, flat, tab order). `GetSpellTabInfo`'s pushed `offset` is
-//! therefore exactly each tab's 0-based START index into `slots` — the app computes it as the
-//! running sum of every earlier tab's `num_spells` (tab 1's is `0`, so its first spell's book id
-//! is `1`, matching the ref's own "first tab's first spell is id 1").
-//!
-//! ## The pet book (decision 1032 — live; 0216 §8's deferral is retired)
-//!
-//! `BOOKTYPE_PET` selects a **second slot list** ([`PetBookState`]), fed from `SMSG_PET_SPELLS`'
-//! own spell tail. Every `bookType`-taking binding is a two-way fork ([`book_slot`]) exactly as the
-//! reference's are — `isPet ? [0xb6f098 + 4*i] : [0xb700f0 + 4*i]`, written out once per binding —
-//! and the three pet-only bindings (`HasPetSpells`, `GetSpellAutocast`, `ToggleSpellAutocast`) live
-//! here with them.
-//!
-//! Two asymmetries are the API and not tidiable away:
-//!
-//! - `GetNumSpellTabs`/`GetSpellTabInfo` take **no** `bookType` and only ever answer the player's
-//!   skill lines. That is the reference's own signature: the pet book has no tabs, and
-//!   `SpellBookFrame_Update` hides the whole skill-line strip while it is up.
-//! - `PickupSpell` and `CastSpell` produce a **different kind of thing** on the pet side — a pet
-//!   action word on the cursor (`0x494e20`, cursor modes 1-7) and a `CMSG_PET_ACTION` on the wire
-//!   (`0x4b34ce`) — rather than a spell payload and a player cast. See each binding.
-//!
-//! `BOOKTYPE_SPELL`/`BOOKTYPE_PET` are installed as plain Lua globals here rather than left to the
-//! transcribed XML's own `<Script>` block (the ref's actual home for them, `SpellBookFrame.lua:
-//! 5-6`, and this crate's usual house rule for Era top-level constants) — the one deliberate
-//! exception, so this module's OWN engine-level tests can drive the pet-deferral path without
-//! loading a real `SpellBookFrame.xml`.
+//! Deviation: `BOOKTYPE_SPELL`/`BOOKTYPE_PET` are engine globals here, where the reference defines
+//! them in `SpellBookFrame.lua:5-6`, so this module's tests run without the stock file.
 
 use mlua::{Lua, MultiValue, Value};
 
@@ -57,14 +18,13 @@ use super::Model;
 const BOOKTYPE_SPELL: &str = "spell";
 const BOOKTYPE_PET: &str = "pet";
 
-/// `HasPetSpells`' second return when the app has not resolved a token — the reference's own
-/// literal at `0x846a40`, pushed by `0x4b44a6` whenever the player object fails to resolve. Never
-/// nil: FrameXML concatenates it (`"PET_TYPE_"..token`), which would error on one.
+/// `HasPetSpells`' second return when no token is resolved: the reference's literal (`0x846a40`),
+/// pushed at `0x4b44a6` when the player object does not resolve. FrameXML concatenates it, so
+/// never nil.
 const PET_TOKEN_FALLBACK: &str = "PET";
 
-/// One skill-line tab (`GetSpellTabInfo`'s own Era tuple shape). `offset` is the tab's 0-based
-/// START index into [`SpellBookState::slots`] (module docs' book-id seam) — pushed by the app,
-/// trusted here (the engine holds no spell knowledge to derive it from itself).
+/// One skill-line tab as `GetSpellTabInfo` returns it; `offset` is the tab's 0-based start in
+/// [`SpellBookState::slots`], computed by the app.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct SpellTabView {
     pub name: String,
@@ -73,72 +33,49 @@ pub struct SpellTabView {
     pub num_spells: u32,
 }
 
-/// One spell in the flat book (0-based [`SpellBookState::slots`] index; module docs' book-id
-/// seam). Every field is pre-resolved by the app — the engine draws whatever it's given.
+/// One spell in the flat book, every field resolved by the app.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct SpellSlotView {
     pub spell_id: u32,
     pub name: String,
-    /// The rank/subtext line (`Spell.dbc`'s `NameSubtext`, `benilla-formats`' own pin); `None`
-    /// shows no second line.
+    /// The rank line, `Spell.dbc`'s `NameSubtext`; `None` shows no second line.
     pub rank: Option<String>,
     pub texture: Option<String>,
-    /// `SPELL_ATTR_PASSIVE` (`benilla-formats`' `SpellDisplay::passive`) — grays the name in the
-    /// transcribed XML and refuses both [`CastSpell`]-family casts (this module) and, faithfully,
-    /// nothing else: a passive can still be picked up/placed on a bar (the ref never blocks that).
+    /// `SPELL_ATTR_PASSIVE`: grays the name and refuses `CastSpell` and `CastSpellByName`, never
+    /// a pickup (the reference does not block one).
     pub passive: bool,
-    /// The `IsCurrentCast` verdict for this slot — the checked ring (`SpellButton_UpdateSelection`'s
-    /// gold glow). The delegate `0x4b3600` has exactly two arms: a shapeshift spell whose form is
-    /// the player's current form byte, or the open trade-skill window's own spell — never an
-    /// ordinary in-flight cast.
-    /// App-resolved (`benilla::ui_spellbook`), pushed with the book; the app fires
-    /// `CURRENT_SPELL_CAST_CHANGED` on its edges.
+    /// `IsCurrentCast`, the checked ring: the reference (`0x4b3600`) answers it only for a
+    /// shapeshift into the player's current form or the open trade-skill window's spell, never an
+    /// ordinary cast.
     pub current: bool,
-    /// The spell's running cooldown as `(start_ms on the GetTime clock, duration_ms, enabled)` —
-    /// the same app-computed triple [`super::ActionState::cooldown`] and the container slots
-    /// carry, resolved by the ONE cooldown store (`benilla::cooldowns::Cooldowns::info` — id,
-    /// category and GCD reads alike); `GetSpellCooldown` answers the reference's
-    /// `(start, duration, enable)`. `None` = cold. Frame-stable per arm (the absolute start), so
-    /// a running cooldown never churns the book diff.
+    /// `(start_ms on the GetTime clock, duration_ms, enabled)`, the triple the action bar carries;
+    /// `None` is cold. The start is absolute, so a running cooldown never churns the book diff.
     pub cooldown: Option<(i64, u32, bool)>,
-    /// `GetSpellAutocast`'s `(allowed, enabled)` pair — **pet-book only**, and `None` is not
-    /// "neither": it is the reference's own player-book answer, `(nil, nil)`, because `0x4b4180`
-    /// short-circuits on the book flag (`0x4b41cb`/`0x4b41d6`) before it looks a spell up at all.
-    /// Read off the pet's **raw** word (`0x4bd160` → bits 31/30), never off the filtered book.
+    /// `GetSpellAutocast`'s `(allowed, enabled)`, pet book only, read off the pet's raw word
+    /// (`0x4bd160`, bits 31 and 30).
     pub autocast: Option<(bool, bool)>,
-    /// The pet slot's packed word **verbatim** — what `PickupSpell(id, "pet")` puts on the cursor.
-    /// `0x4b3260`'s pet arm hands `0x494e20` a *pointer* to this very word, so the payload is the
-    /// server's own dword, type byte and autocast bits included, not a synthesized one. `0` for a
-    /// player-book slot, which has no word.
+    /// The pet slot's packed word as the server sent it, which `PickupSpell(id, "pet")` puts on the
+    /// cursor (`0x4b3260` hands `0x494e20` a pointer to it); 0 in the player book.
     pub packed: u32,
 }
 
-/// The **pet's** book — the reference's second flat array (`0xb6f098`, count `0xb71174`), which is
-/// a genuinely different object from the player's rather than a variant of it:
+/// The pet's book, the reference's second flat array (`0xb6f098`, count `0xb71174`):
 ///
-/// - **no tabs.** `GetNumSpellTabs`/`GetSpellTabInfo` take no `bookType` and only ever answer the
-///   player's skill lines; `SpellBookFrame_Update` hides every skill-line tab while the pet book is
-///   up (`SpellBookFrame.lua:124`), and `SpellBook_GetSpellID` returns the button's own 1..12 id
-///   with no tab offset at all (`l.460-462`).
-/// - **a different add-gate.** `0x4b2f90` admits a spell iff it resolves in `Spell.dbc` **and**
-///   `Attributes & 0x80` (DO_NOT_DISPLAY) is clear — `0x4b2fa8 mov dl,[rec+0x18]; test dl,dl; js`.
-///   That is *one* of the three tests the player book's own gate makes: no `IS_TRADESKILL` leg and
-///   no `castUI == 0` leg. Reusing the player book's gate here would be the same class of mistake
-///   as reusing its tab routing.
-/// - **the same order.** `0x4b2fd0(ecx = 0, edx = 1)` sorts it with `0x4b30c0`, the player book's
-///   own comparator (name, then parsed rank), and tail-jumps `SPELLS_CHANGED`.
+/// - no tabs, so `GetNumSpellTabs` and `GetSpellTabInfo` take no book type: `SpellBookFrame_Update`
+///   hides the skill-line tabs for it (`SpellBookFrame.lua:124`) and `SpellBook_GetSpellID` adds
+///   no tab offset (`SpellBookFrame.lua:460-462`);
+/// - its own add gate (`0x4b2f90`): in `Spell.dbc` with `Attributes & 0x80` (DO_NOT_DISPLAY)
+///   clear, without the player book's tradeskill and `castUI` tests;
+/// - the player book's order: `0x4b2fd0` sorts it with `0x4b30c0` (spell-line group, name, rank).
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct PetBookState {
-    /// `HasPetSpells`'s second return: `ChrClasses.dbc` field 4 for the player's class — `"PET"`
-    /// or `"DEMON"` (`benilla_formats::PetNameTokens`). A **key**, not display text: FrameXML does
-    /// `getglobal("PET_TYPE_"..token)`. `None` only while there is no book at all.
+    /// `HasPetSpells`' second return, `ChrClasses.dbc` field 4 (`"PET"` or `"DEMON"`), a key
+    /// FrameXML looks up as `PET_TYPE_<token>`; `None` only while there is no book.
     pub token: Option<String>,
     pub slots: Vec<SpellSlotView>,
 }
 
-/// The player's known-spell book: tabs (skill lines) + the flat slot list every tab indexes into
-/// (module docs). Durable player state, not a session window (like [`super::action`]'s
-/// `actions` map) — never `Option`; "no known spells yet" is simply empty vectors.
+/// The player's book: the skill-line tabs and the flat slot list they index into.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct SpellBookState {
     pub tabs: Vec<SpellTabView>,
@@ -146,99 +83,75 @@ pub struct SpellBookState {
 }
 
 impl super::UiScript {
-    /// Push the whole book snapshot (tabs + flat slots), replacing whatever was there. A bare
-    /// setter — firing `SPELLS_CHANGED` is the app's own diff-and-fire job (mirroring
-    /// `set_action`/`set_container`; never auto-fired here).
+    /// Replace the book; the app fires `SPELLS_CHANGED` on its own diff.
     pub fn set_spellbook(&mut self, state: SpellBookState) {
         self.model_mut().spellbook = state;
     }
 
-    /// Push the pet's book ([`PetBookState`]), replacing whatever was there. A bare setter for the
-    /// same reason as its sibling: the reference fires `SPELLS_CHANGED` for **both** books off the
-    /// one re-sort (`0x4b2fd0` → `SignalEvent(0x104)`), and whose diff moved is the app's to know.
+    /// Replace the pet's book; the app fires `SPELLS_CHANGED`, which the reference fires for both
+    /// books off one re-sort (`0x4b2fd0`).
     pub fn set_pet_book(&mut self, state: PetBookState) {
         self.model_mut().pet_book = state;
     }
 
-    /// Drain the pet spell ids `CastSpell(id, "pet")` queued. Separate from
-    /// [`Self::take_spell_casts`] because the wire verb is different in kind: the dispatcher's pet
-    /// arm sends **`CMSG_PET_ACTION`** with a synthesized type-1 word (`0x4b34ce`), not a player
-    /// cast, so folding them into one queue would lose which end of the leash the cast came from.
+    /// Drain the pet spell ids `CastSpell(id, "pet")` queued: each is a `CMSG_PET_ACTION` with a
+    /// type-1 word (`0x4b34ce`), not a player cast.
     pub fn take_pet_spell_casts(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().pet_spell_casts)
     }
 
-    /// Drain the pet spell ids `ToggleSpellAutocast` queued — the pet **book**'s autocast verb,
-    /// which is a different opcode from the pet **bar**'s ([`super::pet::UiScript::…`]'s
-    /// `take_pet_autocast_toggles` → `CMSG_PET_SET_ACTION`): this one is
-    /// `CMSG_PET_SPELL_AUTOCAST 0x2F3` and names a spell id rather than a bar slot
-    /// (`0x4b4291` → `0x4bccb0`).
+    /// Drain the spell ids `ToggleSpellAutocast` queued: `CMSG_PET_SPELL_AUTOCAST` (0x2F3, sent by
+    /// `0x4bccb0`) names a spell id, where the pet bar's toggle sends `CMSG_PET_SET_ACTION`.
     pub fn take_pet_spell_autocasts(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().pet_spell_autocasts)
     }
 
-    /// Read the book back — for the ONE app-side consumer that must resolve a spell name by the
-    /// same law `CastSpellByName` does: a macro's bound spell (`benilla::ui_macro`, decision
-    /// 0983). Going through the pushed book rather than re-deriving from the catalog is what
-    /// stops the bar's cooldown swirl and the macro's own cast disagreeing about which rank a
-    /// bare `/cast Fireball` means.
+    /// The pushed book, for resolving a macro's spell by the rule `CastSpellByName` uses, so the
+    /// bar and the cast agree on which rank a bare `/cast` means.
     pub fn spellbook(&self) -> SpellBookState {
         self.model_mut().spellbook.clone()
     }
 
-    /// Drain the spell ids `CastSpell` queued since the last call.
+    /// Drain the spell ids `CastSpell` and `CastSpellByName` queued.
     pub fn take_spell_casts(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().spell_casts)
     }
 
-    /// Push whether the app's cast lifecycle holds something `SpellStopCasting()` can stop — a
-    /// running auto-repeat or an in-flight cast, but NOT a channel (the ref's `0x6e6e80` reads
-    /// only the auto-repeat key `0xceac30` and the inflight id `0xceca88`, and the inflight id
-    /// is already 0 during a channel). Pushed each frame by the
-    /// app's cast feed (`benilla::ui_cast`), before the input pass runs the ESC chain.
+    /// Whether `SpellStopCasting()` has something to stop: an auto-repeat or an in-flight cast,
+    /// never a channel (`0x6e6e80` reads only the auto-repeat key `0xceac30` and the in-flight
+    /// id `0xceca88`, which is 0 mid-channel). Pushed each frame before the ESC chain runs.
     pub fn set_casting(&mut self, casting: bool) {
         self.model_mut().casting = casting;
     }
 
-    /// Drain the `SpellStopCasting()` trigger: `true` if it fired on a stoppable state since
-    /// the last call — the ESC leg of the local self-cancel (`benilla::ui_cast` resolves WHICH
-    /// thing dies: auto-repeat first, else the in-flight cast — the ref's branch order).
+    /// Drain the `SpellStopCasting()` trigger; the app stops the auto-repeat first, else the
+    /// in-flight cast, the reference's order.
     pub fn take_spell_stop(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().spell_stop)
     }
 
-    /// Push whether the app's spell-targeting cursor mode is active (decision 0792) — what
-    /// `SpellIsTargeting()` reads and `SpellStopTargeting()` gates on. Pushed each frame by the
-    /// app's targeting feed (`benilla::ui_action`), before the input pass runs the ESC chain.
+    /// Whether the spell-targeting cursor is up, for `SpellIsTargeting()` and
+    /// `SpellStopTargeting()`; pushed each frame before the input pass runs the ESC chain.
     pub fn set_spell_targeting(&mut self, targeting: bool) {
         self.model_mut().spell_targeting = targeting;
     }
 
-    /// Drain the `SpellStopTargeting()` trigger: `true` if it fired while targeting since the
-    /// last call — the ESC-chain rung (`UIParent.lua:1490`); the app clears its targeting mode.
+    /// Drain the `SpellStopTargeting()` trigger, the ESC chain's rung (`UIParent.lua:1490`); the
+    /// app clears its targeting mode.
     pub fn take_stop_targeting(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().spell_stop_targeting)
     }
 }
 
-/// Which book a `bookType` argument names — the reference's own one-line test, and it is a
-/// **case-insensitive compare against `"pet"` alone** (`0x4b3f27` → `SStrCmpI(arg2, "pet")`), so
-/// every other string, `"spell"` included, is the player's book. Reproduced rather than tightened:
-/// the shared parser also *requires* a string second argument (`0x4b3ee8 lua_isstring(2)`), which
-/// is why these bindings take `String` and not `Option<String>`.
+/// Whether `bookType` names the pet book: a case-insensitive compare with `"pet"` alone
+/// (`0x4b3f27`), so any other string, `"spell"` included, is the player's book.
 fn is_pet_book(book_type: &str) -> bool {
     book_type.eq_ignore_ascii_case(BOOKTYPE_PET)
 }
 
-/// The shared argument marshaller of the reference's spell-slot bindings (`0x4b3ec0` —
-/// `GetSpellName`, `GetSpellTexture`, `IsCurrentCast`,
-/// `GetSpellCooldown`, `IsSpellPassive`, `CastSpell`, `PickupSpell` and the two autocast verbs all
-/// call it): arg 1 must be a number and arg 2 a number or string — the book type is **not**
-/// optional; the index is `trunc(arg1 - 1)` and must land in `[0, 0x400)`, else the binding
-/// raises `Invalid spell slot in <Verb>` and abandons the caller's statement. `"pet"`
-/// (case-insensitively) selects the pet list; any other book type, `"spell"` included, reads the
-/// player's. Answers the 1-based id the rest of this module indexes by ([`slot_index`]), and the
-/// book type normalised to the two names the model knows.
+/// The reference's shared spell-slot marshaller (`0x4b3ec0`): arg 1 a number, arg 2 a number or
+/// string (`0x4b3ee8`), and the index `trunc(arg1 - 1)` in `[0, 0x400)`, else the binding raises
+/// `Invalid spell slot in <Verb>`. Answers the 1-based id and the normalised book type.
 fn spell_slot_args(id: Value, book_type: Value, verb: &str) -> mlua::Result<(u32, String)> {
     let invalid = || mlua::Error::runtime(format!("Invalid spell slot in {verb}"));
     // `lua_isnumber` + `lua_tonumber` (`0x6f34d0`/`0x6f3620`): a numeric string is a number.
@@ -269,18 +182,14 @@ fn spell_slot_args(id: Value, book_type: Value, verb: &str) -> mlua::Result<(u32
     Ok((index as u32 + 1, book.to_string()))
 }
 
-/// The book-id → 0-based slot-list index seam (module docs).
+/// The 1-based book id as a 0-based slot index.
 fn slot_index(id: u32) -> Option<usize> {
     usize::try_from(id.checked_sub(1)?).ok()
 }
 
-/// The one lookup every `bookType`-taking binding shares: pick the book, then the slot. This is
-/// literally the reference's shape — `isPet ? [0xb6f098 + 4*i] : [0xb700f0 + 4*i]`, one fork
-/// repeated verbatim inside each binding (`0x4b3f5d`, `0x4b40e6`, `0x4b3735`, `0x4b3339`, …).
-///
-/// Shared with the tooltip channel (`super::tooltip_spell`'s `SetSpell`), which is a `GameTooltip`
-/// method rather than a global but repeats the identical fork at `0x532e1c`/`0x532e2a` — and which
-/// read the player's book for a pet hover until 1050, because it took the argument and dropped it.
+/// The slot a `bookType` binding reads. The reference forks `isPet ? [0xb6f098 + 4*i] :
+/// [0xb700f0 + 4*i]` in each binding (`0x4b3f5d`, `0x4b40e6`, `0x4b3735`, `0x4b3339`) and in
+/// `GameTooltip:SetSpell` (`0x532e1c`/`0x532e2a`), which shares this.
 pub(super) fn book_slot<'a>(
     model: &'a Model,
     id: u32,
@@ -294,28 +203,17 @@ pub(super) fn book_slot<'a>(
     slots.get(slot_index(id)?)
 }
 
-/// Resolve a spell **by name** against the player's book — the law behind `CastSpellByName` and,
-/// through it, `/cast` and every macro's `/cast` line (decision 0983).
+/// Resolve a spell by name against the player's book, for `CastSpellByName` and so `/cast`, whose
+/// grammar the client's help text gives as `/cast <name> (<subtext>)` (`MACRO_HELP_TEXT_LINE4`):
 ///
-/// The grammar is the one the client documents in its own help text:
-/// `MACRO_HELP_TEXT_LINE4 = "- To cast a spell from a macro use the following syntax:
-/// /cast <name> (<subtext>)"`. So:
+/// - `Fireball`: the highest known rank, by the subtext's leading number (unranked is 0, and a tie
+///   goes to the later slot, the order the book lists ranks in);
+/// - `Fireball(Rank 1)` or `Fireball (Rank 1)`: that subtext, case-insensitively.
 ///
-/// - **`Fireball`** — the highest-ranked *known* Fireball. Rank order is the book's own
-///   `NameSubtext` number (`"Rank 8"` → 8) through the reference's own leading-number parse
-///   ([`super::super::…`]'s twin lives in `benilla::ui_spellbook`); an unranked subtext sorts as 0,
-///   and ties fall to the later book slot, which is the order the book itself lists ranks in.
-/// - **`Fireball(Rank 1)`** / **`Fireball (Rank 1)`** — that exact subtext, case-insensitively.
-///   Both spacings, because vanilla macros in the wild are written both ways and the reference's
-///   own help text prints the spaced form while its FrameXML never re-spaces the argument.
-///
-/// Name matching is case-insensitive and whole-name — a *prefix* rule would silently cast
-/// "Frostbolt" for "Frost" and there is nothing in the reference suggesting one. A spell the
-/// player does not know resolves to `None` and the cast simply does not happen: the reference has
-/// no error line for it either (`SlashCmdList["CAST"]` discards the binding's result).
-///
-/// Passives are skipped, matching [`pickup_spell`]'s sibling rule in `CastSpell`: a passive is
-/// permanent player state, never something a macro casts.
+/// Names match whole and case-insensitively; passives never match. An unknown spell casts nothing
+/// and prints no error, as in the reference (`SlashCmdList["CAST"]` discards the result). The
+/// reference cuts the name at `(` untrimmed (`0x4b3950`), so its spaced form keeps a trailing space
+/// and misses, and it matches name and rank alone, across the pet's book too (`0x4b3a10`).
 pub fn resolve_spell_by_name<'a>(
     book: &'a SpellBookState,
     query: &str,
@@ -334,15 +232,13 @@ pub fn resolve_spell_by_name<'a>(
                 .is_some_and(|r| r.eq_ignore_ascii_case(want)),
             None => true,
         })
-        // Highest rank wins when no subtext pinned one; the book's own later slot breaks a tie.
         .enumerate()
         .max_by_key(|(i, s)| (rank_number(s.rank.as_deref()), *i))
         .map(|(_, s)| s)
 }
 
-/// `Name(Subtext)` / `Name (Subtext)` → `("Name", Some("Subtext"))`; a bare name → `(name, None)`.
-/// An unclosed parenthesis is not a subtext — the whole string stays the name, so a spell whose
-/// own name holds a `(` cannot be silently truncated.
+/// `Name(Subtext)` or `Name (Subtext)` to `("Name", Some("Subtext"))`; without a closing
+/// parenthesis after the opening one, the whole string is the name.
 fn split_subtext(query: &str) -> (&str, Option<&str>) {
     let q = query.trim();
     let Some(open) = q.find('(') else {
@@ -357,9 +253,8 @@ fn split_subtext(query: &str) -> (&str, Option<&str>) {
     (q[..open].trim(), Some(q[open + 1..close].trim()))
 }
 
-/// The rank number inside a `NameSubtext` (`"Rank 8"` → 8), by the reference's own leading-number
-/// parse: skip to the first digit, fold the digit run. A subtext with no digits (`"Racial"`,
-/// `"Passive"`) and an absent one both read 0.
+/// The rank in a `NameSubtext` (`"Rank 8"` is 8) by the reference's parse, the first digit run;
+/// a subtext without digits, or none, reads 0.
 fn rank_number(subtext: Option<&str>) -> u32 {
     subtext
         .unwrap_or("")
@@ -369,13 +264,9 @@ fn rank_number(subtext: Option<&str>) -> u32 {
         .fold(0u32, |acc, c| acc * 10 + c.to_digit(10).unwrap_or(0))
 }
 
-/// `PickupSpell(id, bookType)` — the drag/shift-click entry point (ref `SpellButton_OnClick`'s
-/// other two forks, `SpellBookFrame.lua:263-290`). The book is a SOURCE, never a placement
-/// target — the ref's plain click always casts unconditionally, never checking `GetCursorInfo`
-/// first (unlike `UseAction`'s `checkCursor` fork) — so this refuses outright when the cursor
-/// already holds ANYTHING rather than silently discarding it: the doll's own refusal precedent
-/// (`cursor::doll::pickup_inventory_item`) for a payload with nowhere faithful to go, since a
-/// spell button is not a fit-checked drop target the way a doll slot or bar button is.
+/// `PickupSpell(id, bookType)`, the spell button's drag and shift-click
+/// (`SpellBookFrame.lua:266-290`). It refuses while the cursor holds anything, where the
+/// reference's setters clear the cursor first (`0x495190`, called at `0x494dab` and `0x494f00`).
 fn pickup_spell(model: &mut Model, id: u32, book_type: &str) -> bool {
     if model.cursor.is_some() {
         return false;
@@ -383,22 +274,16 @@ fn pickup_spell(model: &mut Model, id: u32, book_type: &str) -> bool {
     let Some(slot) = book_slot(model, id, book_type) else {
         return false;
     };
-    // **The pet book's payload is a different KIND**, not a Spell payload with a flag on it: the
-    // pet arm of `0x4b3260` calls `0x494e20` with a pointer to the pet's raw word (cursor modes
-    // 1-7), while the player arm calls `0x494d20` with a spell id (mode 9). That is why a pet
-    // spell can be dropped onto the pet bar and a player spell cannot — the bar's drop accepts
-    // exactly one payload kind, and the book is the *second* place that kind is produced.
+    // The pet arm of `0x4b3260` puts the pet's raw word on the cursor (`0x494e20`, cursor mode 4),
+    // the player arm a spell id (`0x494d20`, mode 3); only the pet word drops on the pet bar.
     let payload = if is_pet_book(book_type) {
-        // `0x494e20`'s own jump table refuses type 0 and type >= 8, so a word that could not sit
-        // on the bar cannot ride the cursor either (`cursor::pet::payload_word`, same rule).
+        // `0x494e20` refuses type 0 and types 8 and up.
         let packed = slot.packed;
         if !(1..=7).contains(&((packed >> 24) & 0x3F)) {
             return false;
         }
         CursorPayload::PetAction(super::cursor::CursorPetAction {
-            // No source slot: this word came out of the BOOK, not off the bar, so there is
-            // nothing to blank behind it and nothing to swap back to. The reference is the same
-            // shape — its cursor holds a pointer into the raw spell array, not into the bar.
+            // No source slot: the word comes from the book, not the bar.
             src_slot: 0,
             packed,
             passive: slot.passive,
@@ -425,31 +310,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     g.set("BOOKTYPE_SPELL", BOOKTYPE_SPELL)?;
     g.set("BOOKTYPE_PET", BOOKTYPE_PET)?;
 
-    // `UpdateSpells()` — twelve bytes in the reference (`[0x4b43e0,0x4b43ec)`), and its entire
-    // content is a bare `SignalEvent(SPELLS_CHANGED)`: event 260, **no arguments**, and NO state
-    // mutation whatsoever (decision 1924). Entered with both sort flags zero the worker
-    // performs exactly one memory write — a `push esi` undone nine instructions later — and
-    // `0x4b302f` is the sole fire site for event 260 image-wide.
-    //
-    // **`argc = 0` is PROVEN, not observed**: the binding overwrites `ecx` at its second
-    // instruction, so an extra argument is structurally unobservable. Zero return values.
-    //
-    // **It is NOT a no-op, and it is not a repaint.** Two readings were tried and both are wrong.
-    // A no-op breaks the five stock call sites (`ToggleSpellBook`, `SpellBookFrame_Update`'s
-    // showing leg, both page-turn OnClicks, `SpellBookSkillLineTab_OnClick`). And our old
-    // `BenillaUpdateSpells` stand-in — a loop repainting `SpellButton1..N` — was wrong in BOTH
-    // directions: narrower (it missed the skill-line tab strip, the pet/spell tab buttons,
-    // `SpellBook_UpdatePageArrows` and every other registrant) and wider (the reference gates the
-    // frame update on `IsVisible()`). The repaint is FrameXML's, reached through the event; there
-    // is no native listener mechanism at all.
-    //
-    // Fired SYNCHRONOUSLY, through [`super::tick::fire_event_into`] — the reference's
-    // `SignalEvent` is synchronous, so queueing it for the next tick would be a real divergence.
-    //
-    // Firing `SPELLS_CHANGED` from the other six reference sites (spell learned/removed/
-    // superseded, `SMSG_PET_SPELLS`, the bring-up rebuild, two UpdateFields reflexes) is a
-    // SEPARATE obligation and is where the spell-list re-sort lives; `UpdateSpells` is the one
-    // caller of the seven that never performed that recompute.
+    // `UpdateSpells()` (`[0x4b43e0,0x4b43ec)`) only signals `SPELLS_CHANGED` (event 260, whose one
+    // fire site is `0x4b302f`): no arguments read, no returns, no state change, and no re-sort,
+    // which the other `SPELLS_CHANGED` sites do. The repaint is FrameXML's, through the event.
+    // `SignalEvent` is synchronous, so this fires now, not on the next tick.
     g.set(
         "UpdateSpells",
         lua.create_function(|lua, ()| {
@@ -458,10 +322,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `PlayerHasSpells()` — a hard-coded `1` in the reference: `push 0x3ff00000; push 0;
-    // lua_pushnumber; mov eax,1; ret`. No branch, no store read, so it cannot answer anything else
-    // (1924, found by the same dispatch). `MainMenuBarMicroButtons.lua` gates the spellbook micro
-    // button on it, which is the only reason it exists here.
+    // `PlayerHasSpells()` is a constant 1 in the reference (it pushes 1.0 with no branch);
+    // `MainMenuBarMicroButtons.xml:80` picks the spellbook micro button's tooltip by it.
     g.set("PlayerHasSpells", lua.create_function(|_, ()| Ok(1_i64))?)?;
 
     g.set(
@@ -472,41 +334,19 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSpellTabInfo(i) -> name, texture, offset, numSpells. **FOUR values on every path that
-    // returns** — `0x4b3ce0` has two live `ret`s and both `mov eax,4`; the `eax=0` one at `0x4b3d0d`
-    // is dead code after `luaL_error` longjmps (decision 1931).
-    //
-    // **OUT OF RANGE IS `nil, nil, 0, 0` — LITERAL zeros, not a single nil.** This comment used to say
-    // "out of range -> a single nil (GetMerchantItemInfo's own out-of-range shape)", i.e. one
-    // binding's shape copied onto another on the assumption that they generalise. They do not
-    // (1919 proved it for GetSkillLineInfo; this is the same bug one verb over). Leg `0x4b3e12`
-    // pushes nil, nil, then `push 0; push 0; lua_pushnumber` twice — `0x6f3810` copies its two
-    // stack dwords VERBATIM, so that is exactly +0.0, not a stale offset and nothing off the array
-    // base. Index 0, a negative, past-the-count and the empty/no-player registry all reach it via
-    // ONE unsigned branch (`0x4b3d26 dec ebx / cmp ebx,eax / jae`).
-    //
-    // Why the zeros are load-bearing rather than cosmetic: `SpellBookFrame_OnLoad` runs
-    // `SpellBookSkillLineTab_OnClick(1)` -> `GetSpellTabInfo(1)` UNCONDITIONALLY at load, and
-    // `SpellBookFrame_Update` can pass `SpellBookFrame:GetID()`, which is 0. The stock file then
-    // does `id > (offset + numSpells)` unguarded (l.295) — a nil there raises, and `(0+0)` makes it
-    // true, so the reference HIDES EVERY BUTTON ON THE PAGE. That is the behaviour to match.
-    //
-    // **The argument RAISES when absent or not number-coercible** — `luaL_error(L, "Usage:
-    // GetSpellTabInfo(index)")`, a numeric string accepted. [`number_arg`] is that exact shape
-    // (coerce, truncate toward zero, raise the usage string), and the decrement happens AFTER it.
-    // Do NOT share `GetSpellName`'s marshaller: `0x4b3ec0` does `fsub 1.0` BEFORE truncating, and
-    // the two disagree below 1 (`0.5` is out-of-range here and index 0 there).
-    //
-    // Slot 1 is also nil on an IN-RANGE tab whose skillLineId has no DBC row (`0x4b3dbd`), and
-    // `(string?, nil, num, num)` is live in shipped data (SkillLine.dbc 733/753/754 have
-    // spellIconID 0) — both already the shape the in-range arm below produces.
+    // GetSpellTabInfo(i) -> name, texture, offset, numSpells, four values on every path
+    // (`0x4b3ce0`). Out of range, 0 and negatives included (`0x4b3d26`), is `nil, nil, 0, 0`
+    // (`0x4b3e12`): `SpellBookFrame.lua:295` and `:328` compare `id > (offset + numSpells)`
+    // unguarded, so the zeros hide every button where a nil would raise. In range, the reference
+    // answers a nil name and texture for a skill line with no DBC row (`0x4b3dbd`) and a nil
+    // texture for one with no icon (SkillLine 733, 753, 754); here the name is always a string.
+    // The index is truncated before the decrement, unlike in `0x4b3ec0`, so 0.5 is out of range.
     g.set(
         "GetSpellTabInfo",
         lua.create_function(|lua, i: Value| {
             let i = super::binding_abi::number_arg(lua, i, "Usage: GetSpellTabInfo(index)")?;
             let model = lua.app_data_ref::<Model>().expect("model app_data");
-            // Truncate (done), THEN decrement, then the unsigned compare: a negative or zero
-            // index lands below 0 and `usize::try_from` refuses it — the `jae` leg.
+            // Zero or a negative fails `usize::try_from`, as the unsigned compare fails it.
             let tab = usize::try_from(i64::from(i) - 1)
                 .ok()
                 .and_then(|n| model.spellbook.tabs.get(n));
@@ -531,42 +371,19 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSpellName(id, bookType) -> name, rank. **Always TWO values, never one, and the rank of a
-    // rankless spell is the EMPTY STRING, never nil** — derived from the bytes alone, below.
-    //
-    // Both returns go through the same push helper with **no rank-specific branch anywhere in the
-    // binding** — a ranked and a rankless spell run byte-identical code: `0x4b4063 call 0x6f3890`
-    // pushes `SpellRec.Name[locale]`, `0x4b4076` pushes `NameSubtext[locale]`, and the single
-    // DBC-resolved exit is `mov eax,0x2` at `0x4b407c`. `0x6f3890` decides on **pointer nullity
-    // alone** (`test edx,edx`), and the DBC pointer is never NULL: `SpellRec::Read 0x583750` fixes
-    // up every string column with an unconditional `add offset, stringBlockBase`, so an on-disk
-    // offset of 0 materializes as a pointer to the string block's own byte 0 — a NUL. `0x6f3840`
-    // then writes tag 4 (`LUA_TSTRING`) unconditionally; `len == 0` is not a special case. So the
-    // rankless rank is a real, interned, zero-length Lua string.
-    //
-    // This is not an edge case: **14,403 of the shipped Spell.dbc's 22,357 rows carry NameSubtext
-    // offset 0** — 64%, `Attack` (6603) among them. Our `Option<String>::None` pushed nil there,
-    // and two 1.12 corpus addons walking the whole book die on it in two different idioms:
-    // `Roid-Macros/Generic.lua:35` uses the rank as a TABLE KEY (nil is illegal), and
-    // `CT_MasterMod/CT_Master.lua:16` passes it straight to `string.find` (nil raises). Both were
-    // invisible until the survey seated a spellbook.
-    //
-    // The `Option` is still the right shape for the MODEL — it records "this spell has no
-    // NameSubtext", which is a fact about the DBC row. What was wrong was rendering that absence
-    // as nil at the Lua boundary; the reference renders it as the empty string the pointer targets.
+    // GetSpellName(id, bookType) -> name, rank, always two values; a rankless spell's rank is "",
+    // never nil: `0x4b4076` pushes `NameSubtext` through `0x6f3890`, which tests only pointer
+    // nullity, and `SpellRec::Read` (`0x583750`) makes every string offset a pointer. 14,403 of
+    // the 22,357 `Spell.dbc` rows have an empty one, `Attack` (spell 6603) among them.
     g.set(
         "GetSpellName",
         lua.create_function(|lua, (id, book_type): (Value, Value)| {
             let (id, book_type) = spell_slot_args(id, book_type, "GetSpellName")?;
-            // An out-of-range index RAISES rather than answering nil (`spell_slot_args`); the
-            // in-binding bound check at `0x4b4018` is unreachable-as-taken. This file previously
-            // assumed the bound was "enforced by our slot lists being shorter than that anyway" —
-            // a short list answers nil, which is a different thing entirely.
+            // Out of `[0, 0x400)` already raised in `spell_slot_args`; the binding's own bound
+            // check (`0x4b4018`) is never taken.
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             let Some(slot) = book_slot(&model, id, &book_type) else {
-                // An unfilled slot inside the range answers **two** nils (`0x4b4086` → `mov eax,0x2`
-                // at `0x4b4095`), not one — which a return-list count and a two-name assignment can
-                // both tell apart.
+                // An empty slot inside the range answers two nils (`0x4b4086`).
                 return Ok(MultiValue::from_vec(vec![Value::Nil, Value::Nil]));
             };
             Ok(MultiValue::from_vec(vec![
@@ -589,17 +406,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsCurrentCast(id, bookType) — the spellbook button's checked ring (binding `0x4b4370` →
-    // delegate `0x4b3600`; ref
-    // `SpellButton_UpdateSelection` SetChecks on it). The verdict itself is app-resolved per slot
-    // ([`SpellSlotView::current`]); this only reads it back.
+    // IsCurrentCast(id, bookType) (`0x4b4370`) reads back the app's per-slot verdict,
+    // `SpellSlotView::current`.
     g.set(
         "IsCurrentCast",
         lua.create_function(|lua, (id, book_type): (Value, Value)| {
             let (id, book_type) = spell_slot_args(id, book_type, "IsCurrentCast")?;
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             let current = book_slot(&model, id, &book_type).is_some_and(|s| s.current);
-            // The ref's binding convention: 1 or nil, never false.
+            // 1 or nil, never false, as the reference's bindings answer.
             match current {
                 true => Ok(Value::Integer(1)),
                 false => Ok(Value::Nil),
@@ -607,11 +422,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSpellCooldown(id, bookType) → start, duration, enable — the book twin of
-    // `GetActionCooldown`/`GetContainerItemCooldown`, identical conventions: `GetTime`-clock
-    // `(seconds, seconds, 0/1)`, enable 0 = an on-hold record (parked, full duration), and the
-    // cold-at-expiry guard so an event-driven re-feed can never replay the finish flash. Pet or
-    // out-of-range answers the cold `(0, 0, 1)` — the ref's own no-cooldown shape.
+    // GetSpellCooldown(id, bookType) -> start, duration, enable in `GetTime` seconds, as
+    // `GetActionCooldown`: enable 0 for an on-hold cooldown; an expired or empty one answers the
+    // reference's no-cooldown `(0, 0, 1)`, so a re-feed cannot replay the finish flash.
     g.set(
         "GetSpellCooldown",
         lua.create_function(|lua, (id, book_type): (Value, Value)| {
@@ -645,17 +458,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CastSpell(id, bookType) — the plain click (ref SpellButton_OnClick's `else` branch): queues
-    // the resolved spell id UNLESS the slot is passive (module doc: a passive is permanent player
-    // state, never something the player casts) or bookType/id resolve to nothing.
-    //
-    // **The pet arm is a different verb, not a flag.** `0x4b3300`'s tail forks on the book byte
-    // one instruction before the send (`0x4b34c8 cmp ecx, 0; je` → the player's own cast
-    // `0x6e5a90`), and the pet side builds `CMSG_PET_ACTION 0x175` by hand:
-    // `{ u64 [0xb714a0], u32 (spellId & 0xFFFF) | 0x01000000, u64 target }` (`0x4b34ce`-`0x4b3524`)
-    // — a **synthesized type-1 word**, which is why the pet book can cast a spell that is not on
-    // the bar at all. The target is the passed one, falling back to the current selection
-    // (`0x4b34af`-`0x4b34bb`), exactly as `CastPetAction` does; the app supplies it at the drain.
+    // CastSpell(id, bookType), the plain click, queues the slot's spell unless it is passive. On
+    // the pet book `0x4b3300` forks at `0x4b34c8` (the player's cast is `0x6e5a90`) to send
+    // `CMSG_PET_ACTION` (0x175), `{ u64 [0xb714a0], u32 (spellId & 0xFFFF) | 0x01000000, u64
+    // target }` (`0x4b34ce`), so the pet book casts a spell not on the bar; the target falls back
+    // to the selection (`0x4b34af`), as in `CastPetAction`. The app sends both at the drain.
     g.set(
         "CastSpell",
         lua.create_function(|lua, (id, book_type): (Value, Value)| {
@@ -675,12 +482,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // HasPetSpells() → numPetSpells, petToken — no arguments, and **always exactly two returns**
-    // (`0x4b4410`, `EAX = 2` on every path). Zero spells answers `(nil, nil)` (`0x4b4420`), which
-    // is the gate `ToggleSpellBook` and `SpellBookFrame_Update` both read: no pet book, no tab row.
-    //
-    // Return 1 is the **count as a number**, not a boolean — `SpellBook_GetCurrentPage` divides by
-    // it (`ceil(numPetSpells/12)`), so answering 1/nil would silently pin the pet book to one page.
+    // HasPetSpells() -> numPetSpells, petToken: always two returns (`0x4b4410`), `(nil, nil)` with
+    // no pet spells (`0x4b4420`). The count is a number: `SpellBook_GetCurrentPage` divides by it.
     g.set(
         "HasPetSpells",
         lua.create_function(|lua, ()| {
@@ -691,20 +494,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             }
             let token = match &model.pet_book.token {
                 Some(t) => Value::String(lua.create_string(t)?),
-                // The reference's own unresolved-player arm pushes the literal "PET"
-                // (`0x4b44a6`), never nil — a nil here would make `"PET_TYPE_"..token` error.
                 None => Value::String(lua.create_string(PET_TOKEN_FALLBACK)?),
             };
             Ok(MultiValue::from_vec(vec![Value::Integer(n as i64), token]))
         })?,
     )?;
 
-    // GetSpellAutocast(id, bookType) → autoCastAllowed, autoCastEnabled (1/nil each) — the
-    // AutoCastable overlay and the sparkle model on a pet book button.
-    //
-    // **Pet-only, and it fails to (nil, nil) rather than (nil) for the player book**: `0x4b4180`
-    // tests the book flag twice (`0x4b41cb`, `0x4b41d6`) and falls into the same two nil pushes the
-    // no-record path uses, so the arity is 2 on every path including a bad index.
+    // GetSpellAutocast(id, bookType) -> autoCastAllowed, autoCastEnabled, 1 or nil each: always
+    // two returns, `(nil, nil)` for the player book (`0x4b4180` tests the book at `0x4b41cb` and
+    // `0x4b41d6`) and for an empty slot.
     g.set(
         "GetSpellAutocast",
         lua.create_function(move |lua, (id, book_type): (Value, Value)| {
@@ -718,16 +516,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ToggleSpellAutocast(id, bookType) — the pet book's right click (ref `SpellButton_OnClick`'s
-    // `arg1 ~= "LeftButton"` fork). **A different binding and a different opcode from the pet
-    // BAR's `TogglePetAutocast`**: `0x4b4240` indexes the pet spellbook and calls `0x4bccb0`, which
-    // sends `CMSG_PET_SPELL_AUTOCAST 0x2F3` naming a **spell id**, where the bar's verb sends
-    // `CMSG_PET_SET_ACTION` naming a slot. Confusing them is a wire bug that looks like a UI one.
-    //
-    // The gate here is the same one `0x4bccb0` applies before it sends: the word must be
-    // autocast-ALLOWED (`0x4bccf5 test cl,1`). Everything else the sender does — flipping bit 30
-    // in place and mirroring it onto every bar slot carrying the same action — is state the app
-    // owns, so it happens at the drain.
+    // ToggleSpellAutocast(id, bookType), the pet book's right click (`0x4b4240`): queued only for
+    // an autocast-allowed word, the gate `0x4bccb0` applies before sending (`0x4bccf5`). The app
+    // sends `CMSG_PET_SPELL_AUTOCAST` and flips bit 30 on the book and the bar at the drain.
     g.set(
         "ToggleSpellAutocast",
         lua.create_function(|lua, (id, book_type): (Value, Value)| {
@@ -744,14 +535,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CastSpellByName(name [, onSelf]) — the reference binding `0x4b4ab0`, whose only two callers
-    // share the `0x4b3300` dispatcher with `CastSpell` above, so this queues onto
-    // the same `spell_casts` list and the app's one cast tail handles both. `SlashCmdList["CAST"]`
-    // is literally `CastSpellByName(msg)`, which is why `/cast` needs nothing else, and it is the
-    // command the whole macro system is built to run.
-    //
-    // `onSelf` is accepted and carried no further (benilla has no self-cast modifier yet — the
-    // same named gap `UseAction`'s third argument already has).
+    // CastSpellByName(name [, onSelf]) (`0x4b4ab0`) shares the dispatcher `0x4b3300` with
+    // `CastSpell`, so it queues on the same list; `SlashCmdList["CAST"]` calls it. `onSelf` is
+    // accepted and ignored: self-cast is not built.
     g.set(
         "CastSpellByName",
         lua.create_function(|lua, (name, _on_self): (String, MultiValue)| {
@@ -773,18 +559,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SpellStopCasting() — the ref's Script::SpellStopCasting (`0x6e6e80`): stop the FIRST of
-    // {running auto-repeat (`0x6ea080`,
-    // CMSG_CANCEL_AUTO_REPEAT_SPELL), in-flight cast (`AbortCast` → CMSG_CANCEL_CAST)} and
-    // return 1; nil when neither runs. A CHANNEL is nil — the body's whole callee closure
-    // never reaches the channel canceler `0x6e9b70`, and the inflight id `0xceca88` it gates
-    // on is already 0 mid-channel (the launch CAST_RESULT(OKAY) clears it at `0x6e7408`) —
-    // the vanilla "/stopcasting can't stop a channel" quirk, kept faithfully. The falsy leg is
-    // load-bearing ground truth from the artifact: `ToggleGameMenu`'s ESC chain (extracted
-    // `UIParent.lua:1489`, `elseif ( SpellStopCasting() ) then`) only reaches
-    // `CloseAllWindows()`/the game menu through nil, so an unconditional true would eat every
-    // ESC press forever. The host feeds the stoppable mirror (`set_casting`) and resolves the
-    // branch order at the drain (`benilla::ui_cast::local_self_cancel`).
+    // SpellStopCasting() (`0x6e6e80`) stops the first of a running auto-repeat (`0x6ea080`,
+    // `CMSG_CANCEL_AUTO_REPEAT_SPELL`) or an in-flight cast (`CMSG_CANCEL_CAST`) and answers 1,
+    // else nil. A channel answers nil: the channel canceler `0x6e9b70` is never reached, and the
+    // in-flight id `0xceca88` is 0 mid-channel (cleared at `0x6e7408`). The nil matters: the ESC
+    // chain (`UIParent.lua:1489`) reaches the game menu only through it.
     g.set(
         "SpellStopCasting",
         lua.create_function(|lua, ()| {
@@ -798,9 +577,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SpellIsTargeting() — the ref's Script::SpellIsTargeting (`0x6e6cd0`): true while the
-    // targeting cursor is up (`flag_word != 0`), nil otherwise.
-    // Read by FrameXML (PetFrame's right-click bind fork) and by the ESC chain's callers.
+    // SpellIsTargeting() (`0x6e6cd0`): true while the targeting cursor is up, else nil.
     g.set(
         "SpellIsTargeting",
         lua.create_function(|lua, ()| {
@@ -813,16 +590,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SpellCanTargetUnit("unit") — the ref's `0x6e6d00`: resolve the token, then ask `0x6e6460`'s
-    // UNIT leg whether the standing word can bind it. Its one shipped caller is
-    // `UnitFrame_OnEnter`, and it is what picks CAST_CURSOR over CAST_ERROR_CURSOR — the only
-    // lit/grey cursor split over a UI element in 1.12.
-    //
-    // The token is not consulted yet, and that is honest rather than lazy: the answer is `false`
-    // for **every** unit while any word benilla can arm is standing (location / item / gameobject —
-    // no unit satisfies those), so no token can change it. The app derives the flag from the word
-    // itself, so this starts discriminating by unit the moment the residual unit-word machine
-    // lands rather than silently staying wrong.
+    // SpellCanTargetUnit("unit") (`0x6e6d00`) asks `0x6e6460`'s unit leg whether the targeting
+    // word can take the unit. The token is not read: no word benilla can arm (location, item,
+    // gameobject) takes a unit, and unit words are not built.
     g.set(
         "SpellCanTargetUnit",
         lua.create_function(|lua, _unit: Option<String>| {
@@ -835,12 +605,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SpellStopTargeting() — the ref's Script::SpellStopTargeting (`0x6e6e30`: if IsTargeting →
-    // StopTargeting `0x6e4900` → AbortCast(0x1c), which in targeting mode just clears the word,
-    // no packet). The 1/nil return is load-bearing exactly like SpellStopCasting's above: the
-    // ESC chain's rung (`UIParent.lua:1490`, `elseif ( SpellStopTargeting() ) then`) must fall
-    // through to the game menu when nothing was targeting. The host drains the trigger
-    // (`benilla::spell::targeting`) and clears its mode.
+    // SpellStopTargeting() (`0x6e6e30`): while targeting, `0x6e4900` clears the word with no
+    // packet and the binding answers 1, else nil, so the ESC chain (`UIParent.lua:1490`) falls
+    // through to the game menu.
     g.set(
         "SpellStopTargeting",
         lua.create_function(|lua, ()| {
@@ -863,8 +630,7 @@ mod tests {
     use crate::script::cursor::{CursorAction, CursorPayload};
     use crate::script::UiScript;
 
-    /// Two tabs: "Fire" (2 spells: Fireball rank1 active, Fire Blast PASSIVE — an artificial
-    /// fixture just to exercise the gray/refuse gate) and "Frost" (1 spell).
+    /// Two tabs: Fire (Fireball, and Fire Blast marked passive) and Frost (Frost Armor).
     fn book() -> SpellBookState {
         SpellBookState {
             tabs: vec![
@@ -897,7 +663,7 @@ mod tests {
                     name: "Fire Blast".into(),
                     rank: Some("Rank 1".into()),
                     texture: Some("Interface\\Icons\\Spell_Fire_FireBolt02".into()),
-                    passive: true, // artificial: exercises the refusal gate
+                    passive: true, // not really passive: exercises the refusal
                     current: false,
                     cooldown: None,
                     ..Default::default()
@@ -916,7 +682,6 @@ mod tests {
         }
     }
 
-    /// `IsCurrentCast` reads the app-resolved per-slot verdict back as the ref's 1-or-nil.
     #[test]
     fn is_current_cast_reads_the_slot_verdict() {
         let mut s = UiScript::new().unwrap();
@@ -942,17 +707,13 @@ mod tests {
             .unwrap());
     }
 
-    /// `GetSpellCooldown` reads the app-pushed per-slot triple back as the ref's GetTime-clock
-    /// `(start, duration, enable)` — cold `(0, 0, 1)` for absent/pet/out-of-range, enable 0 for
-    /// an on-hold record regardless of expiry, and the cold-at-expiry guard once
-    /// `start + duration` passes (`GetActionCooldown`'s own conventions, the book twin).
     #[test]
     fn get_spell_cooldown_reads_the_slot_triple() {
         let mut s = UiScript::new().unwrap();
         s.set_spellbook(book());
         s.tick(20.0); // GetTime = 20
 
-        // Cold slot: the ref's no-cooldown shape.
+        // Cold slot: the reference's no-cooldown shape.
         assert_eq!(
             s.eval::<(f64, f64, i64)>("return GetSpellCooldown(1, BOOKTYPE_SPELL)")
                 .unwrap(),
@@ -962,26 +723,26 @@ mod tests {
         let mut b = book();
         b.slots[0].cooldown = Some((14_000, 10_000, true)); // running: 4 s elapsed of 10
         b.slots[1].cooldown = Some((2_000, 8_000, false)); // on hold: parked since t=2
-        b.slots[2].cooldown = Some((5_000, 10_000, true)); // elapsed at t=15 — cold
+        b.slots[2].cooldown = Some((5_000, 10_000, true)); // elapsed at t=15: cold
         s.set_spellbook(b);
         assert_eq!(
             s.eval::<(f64, f64, i64)>("return GetSpellCooldown(1, BOOKTYPE_SPELL)")
                 .unwrap(),
             (14.0, 10.0, 1)
         );
-        // On hold survives the expiry guard (enable 0 = the parked "hasn't begun").
+        // On hold survives the expiry guard.
         assert_eq!(
             s.eval::<(f64, f64, i64)>("return GetSpellCooldown(2, BOOKTYPE_SPELL)")
                 .unwrap(),
             (2.0, 8.0, 0)
         );
-        // Elapsed goes cold — an event-driven re-feed can never replay the finish flash.
+        // Elapsed goes cold.
         assert_eq!(
             s.eval::<(f64, f64, i64)>("return GetSpellCooldown(3, BOOKTYPE_SPELL)")
                 .unwrap(),
             (0.0, 0.0, 1)
         );
-        // The pet deferral and out-of-range answer cold too.
+        // No pet book, and past the book, answer cold too.
         assert_eq!(
             s.eval::<(f64, f64, i64)>("return GetSpellCooldown(1, BOOKTYPE_PET)")
                 .unwrap(),
@@ -998,8 +759,7 @@ mod tests {
     fn tab_info_shapes_and_book_id_offsets() {
         let mut s = UiScript::new().unwrap();
         assert_eq!(s.eval::<i64>("return GetNumSpellTabs()").unwrap(), 0);
-        // `== nil` reads true either way — Lua compares only the first value. The ARITY is the
-        // load-bearing half and lives in `out_of_range_answers_four_values` below (1931).
+        // Lua compares only the first value; `out_of_range_answers_four_values` checks the arity.
         assert!(s
             .eval::<bool>("return (GetSpellTabInfo(1)) == nil")
             .unwrap());
@@ -1019,13 +779,11 @@ mod tests {
             .unwrap();
         assert_eq!((name2.as_str(), offset2, num2), ("Frost", 2, 1));
 
-        // Out of range -> nil.
+        // Out of range: nil first.
         assert!(s.eval::<bool>("return GetSpellTabInfo(3) == nil").unwrap());
     }
 
-    /// The shared marshaller's law (`0x4b3ec0`): the index is `trunc(arg - 1)` gated to
-    /// `[0, 0x400)` and a miss RAISES; the book type is mandatory and `"pet"` is matched without
-    /// case; anything else is the player's book.
+    /// The reference's marshaller, `0x4b3ec0`.
     #[test]
     fn the_slot_marshaller_gates_the_index_and_names_the_book() {
         let mut s = UiScript::new().unwrap();
@@ -1048,8 +806,7 @@ mod tests {
                 .contains("Invalid spell slot in GetSpellTexture"),
             "the book type is not optional"
         );
-        // Inside the range but past the book: nil, not an error — the bound is the marshaller's,
-        // the emptiness is the slot's.
+        // Inside the range but past the book: nil, not an error.
         assert!(s
             .eval::<bool>("return GetSpellTexture(1024, BOOKTYPE_SPELL) == nil")
             .unwrap());
@@ -1102,7 +859,7 @@ mod tests {
             .unwrap();
         assert_eq!(name3, "Frost Armor");
 
-        // Out of range and the pet deferral both answer nil.
+        // Past the book, and an absent pet book, answer nil.
         assert!(s
             .eval::<bool>(r#"return GetSpellName(99, BOOKTYPE_SPELL) == nil"#)
             .unwrap());
@@ -1129,9 +886,8 @@ mod tests {
             ("spell", 1, "spell", 133)
         );
 
-        // CURSOR_UPDATE fired (the shared cursor seam, not duplicated here) — a listener sees it.
-        // Tick first to flush the FIRST pickup's already-queued CURSOR_UPDATE before the listener
-        // registers, so the count below is purely about the second (refused) call.
+        // Tick first to flush the first pickup's `CURSOR_UPDATE`, so the count below is the
+        // refused call's alone.
         s.tick(0.0);
         s.run(
             r#"
@@ -1149,8 +905,7 @@ mod tests {
             0,
             "refused pickup fires no CURSOR_UPDATE"
         );
-        // Still holding spell 133 (book slot 1) from the first pickup — a refusal never clobbers
-        // it (GetCursorInfo's Spell arm: kind, book_slot, book_type, spell_id).
+        // Still holding the first pickup: a refusal never clobbers it.
         assert_eq!(
             s.eval::<(String, i64, String, i64)>(
                 "local k, slot, book, id = GetCursorInfo() return k, slot, book, id"
@@ -1201,9 +956,8 @@ mod tests {
             .unwrap());
     }
 
-    /// **With no pet book fed, every pet arm answers nothing** — the old deferral's behaviour,
-    /// which is also the reference's whenever `[0xb71174] == 0`. Kept as its own case so the
-    /// pet-book tests below can never pass by the player book leaking into them.
+    /// With no pet book, as when the reference's count `[0xb71174]` is 0, every pet arm answers
+    /// nothing.
     #[test]
     fn an_absent_pet_book_answers_empty_everywhere() {
         let mut s = UiScript::new().unwrap();
@@ -1232,8 +986,8 @@ mod tests {
         assert!(s.cursor_payload().is_none(), "pet pickup is a no-op");
     }
 
-    /// A hunter's pet book: Growl (autocastable, ON, on cooldown), Claw (autocastable, OFF) and
-    /// Avoidance (a passive — no autocast, `ACT_PASSIVE 0x01`).
+    /// A hunter's pet book: Growl (autocastable, on, cooling down), Claw (autocastable, off) and
+    /// Avoidance (a passive, no autocast, `ACT_PASSIVE` 0x01).
     fn pet_book() -> PetBookState {
         PetBookState {
             token: Some("PET".into()),
@@ -1270,8 +1024,6 @@ mod tests {
         }
     }
 
-    /// `HasPetSpells` is **the count and a token**, always two returns, and the count is a NUMBER
-    /// — `SpellBook_GetCurrentPage` divides by it, so a 1/nil boolean would pin the page count.
     #[test]
     fn has_pet_spells_answers_a_count_and_a_class_token() {
         let mut s = UiScript::new().unwrap();
@@ -1280,8 +1032,7 @@ mod tests {
             .eval::<bool>(r#"local n, t = HasPetSpells() return n == 3 and t == "PET""#)
             .unwrap());
 
-        // A warlock's book carries the other token, which is the whole of what makes the tab read
-        // "Demon" — FrameXML does `getglobal("PET_TYPE_"..token)`.
+        // A warlock's token, which FrameXML reads as `PET_TYPE_DEMON`.
         let mut demon = pet_book();
         demon.token = Some("DEMON".into());
         s.set_pet_book(demon);
@@ -1291,8 +1042,7 @@ mod tests {
             "DEMON"
         );
 
-        // No token resolved (no ChrClasses.dbc) still answers a STRING, never nil — a nil would
-        // make the reference's own concatenation error.
+        // No token resolved (no `ChrClasses.dbc`) still answers a string.
         let mut untokened = pet_book();
         untokened.token = None;
         s.set_pet_book(untokened);
@@ -1303,8 +1053,6 @@ mod tests {
         );
     }
 
-    /// The two books are separate lists reached by the SAME id — the reference's `isPet ? petArray
-    /// : playerArray` fork. Book id 1 means Fireball in one and Growl in the other.
     #[test]
     fn one_id_reads_two_different_books() {
         let mut s = UiScript::new().unwrap();
@@ -1321,8 +1069,7 @@ mod tests {
                 .unwrap(),
             "Growl"
         );
-        // The book type is a case-insensitive compare against "pet" ALONE (`0x4b3f27`), so every
-        // other string is the player's book — including a typo'd one.
+        // `"pet"` alone, without case (`0x4b3f27`); any other string, a typo too, is the player's.
         assert_eq!(
             s.eval::<String>(r#"return GetSpellName(1, "PeT")"#)
                 .unwrap(),
@@ -1333,15 +1080,12 @@ mod tests {
                 .unwrap(),
             "Fireball"
         );
-        // Past the pet book's end: one nil, the out-of-range shape.
+        // Past the pet book's end: nil.
         assert!(s
             .eval::<bool>(r#"return GetSpellName(4, BOOKTYPE_PET) == nil"#)
             .unwrap());
     }
 
-    /// `GetSpellAutocast` is **pet-only and always two returns**: the player book short-circuits
-    /// to `(nil, nil)` before it looks anything up (`0x4b41cb`/`0x4b41d6`), and so does an
-    /// out-of-range pet index.
     #[test]
     fn autocast_is_a_pet_only_pair() {
         let mut s = UiScript::new().unwrap();
@@ -1381,9 +1125,6 @@ mod tests {
         );
     }
 
-    /// `ToggleSpellAutocast` queues only what `0x4bccb0` would actually send: a pet-book slot whose
-    /// word is autocast-ALLOWED. A passive, a player-book id and an out-of-range id all queue
-    /// nothing — and none of them may leak into the player's cast queue.
     #[test]
     fn only_an_autocastable_pet_slot_queues_a_toggle() {
         let mut s = UiScript::new().unwrap();
@@ -1402,8 +1143,6 @@ mod tests {
         assert!(s.take_spell_casts().is_empty());
     }
 
-    /// A pet cast is a **different queue** from a player cast, because it is a different opcode at
-    /// the far end (`CMSG_PET_ACTION`, not a player cast). A passive still refuses on both.
     #[test]
     fn a_pet_cast_queues_apart_from_a_player_cast() {
         let mut s = UiScript::new().unwrap();
@@ -1421,9 +1160,6 @@ mod tests {
         assert!(s.take_pet_spell_casts().is_empty(), "drain empties");
     }
 
-    /// A pet-book pickup puts a **pet action word** on the cursor, not a spell payload — which is
-    /// exactly what makes it droppable on the pet bar (`cursor::pet`'s payload). The word is the
-    /// server's own, autocast bits and all.
     #[test]
     fn a_pet_book_pickup_carries_the_packed_word() {
         let mut s = UiScript::new().unwrap();
@@ -1442,7 +1178,7 @@ mod tests {
         assert_eq!(p.packed, 0xC100_0000 | 2649);
         assert_eq!(p.src_slot, 0, "it came out of the book, not off the bar");
 
-        // The player book still produces a SPELL payload — the two are not interchangeable.
+        // The player book still produces a spell payload.
         s.run("ClearCursor()").unwrap();
         assert!(s
             .eval::<bool>(r#"return PickupSpell(1, BOOKTYPE_SPELL)"#)
@@ -1450,9 +1186,8 @@ mod tests {
         assert!(matches!(s.cursor_payload(), Some(CursorPayload::Spell(_))));
     }
 
-    /// `GetSpellCooldown(id, "pet")` reads the PET's slot — the reference reaches bank 1 with the
-    /// same `0x6e2ea0(edx = isPet)` `GetPetActionCooldown` uses, so a spell on the bar and the same
-    /// spell in the book must never disagree. The elapsed-goes-cold rule is the player book's.
+    /// The reference reads a pet book cooldown through `0x6e2ea0` (`edx = isPet`), as
+    /// `GetPetActionCooldown` does, so the book and the bar agree.
     #[test]
     fn the_pet_books_cooldown_is_the_pets_own() {
         let mut s = UiScript::new().unwrap();
@@ -1466,7 +1201,7 @@ mod tests {
         assert!((start - 9.4).abs() < 1e-9, "start {start}");
         assert!((duration - 5.0).abs() < 1e-9);
         assert_eq!(enable, 1);
-        // The player book's slot 1 has none — proof the fork reached the right list.
+        // The player book's slot 1 has none.
         assert_eq!(
             s.eval::<(f64, f64, i32)>(r#"return GetSpellCooldown(1, BOOKTYPE_SPELL)"#)
                 .unwrap(),
@@ -1481,16 +1216,6 @@ mod tests {
         );
     }
 
-    /// **A rankless spell's rank is the empty string, not nil** — and the arity is always two.
-    ///
-    /// Both returns go through one push helper with no rank-specific branch (`0x4b4063`/`0x4b4076`,
-    /// single exit `mov eax,0x2` at `0x4b407c`), and the DBC pointer is never NULL, so an on-disk
-    /// NameSubtext offset of 0 becomes a pointer to the string block's byte 0 — a real zero-length
-    /// Lua string. 64% of the shipped Spell.dbc's rows are in that state, `Attack` among them.
-    ///
-    /// The two corpus idioms this was breaking are both asserted here, because "falsey either way"
-    /// is exactly the reasoning that made nil look acceptable: a nil is an ILLEGAL TABLE KEY
-    /// (Roid-Macros) and an ILLEGAL `string.find` argument (CT_MasterMod), while `""` is neither.
     #[test]
     fn a_rankless_spell_answers_an_empty_rank_and_still_two_values() {
         let mut s = UiScript::new().unwrap();
@@ -1522,7 +1247,7 @@ mod tests {
                 .unwrap(),
             "the rankless rank must be a STRING, not nil"
         );
-        // Roid-Macros/Generic.lua:35 and CT_MasterMod/CT_Master.lua:16, in miniature.
+        // Two addon idioms that a nil rank breaks: a table key and a `string.find` argument.
         s.run(r#"local _, r = GetSpellName(1, "spell") local t = {} t[r] = 1"#)
             .expect("a rankless rank must be a legal table key");
         s.run(r#"local _, r = GetSpellName(1, "spell") string.find(r, "(%d+)")"#)
@@ -1534,14 +1259,13 @@ mod tests {
             ("Heroic Strike".to_string(), "Rank 1".to_string())
         );
 
-        // An unfilled slot INSIDE the range is two nils, not one — distinguishable by the count.
+        // An empty slot inside the range is two nils.
         assert_eq!(s.arity(r#"GetSpellName(9, "spell")"#).unwrap(), 2);
         assert!(s
             .eval::<bool>(r#"local a, b = GetSpellName(9, "spell") return a == nil and b == nil"#)
             .unwrap());
 
-        // Past the reference's [0, 0x400) gate — an id of 1025 is index 1024 — it RAISES rather
-        // than answering nil.
+        // Id 1025 is index 1024, past the `[0, 0x400)` gate: it raises.
         let err = s
             .run(r#"GetSpellName(1025, "spell")"#)
             .expect_err("an out-of-range slot must raise");
@@ -1549,18 +1273,11 @@ mod tests {
             format!("{err}").contains("Invalid spell slot in GetSpellName"),
             "got {err}"
         );
-        // ...and 1023 is inside it, so it answers rather than raising.
+        // Id 1023 is inside it and answers.
         assert_eq!(s.arity(r#"GetSpellName(1023, "spell")"#).unwrap(), 2);
     }
 
-    /// **`UpdateSpells()` fires `SPELLS_CHANGED` and does nothing else** — decision 1924, from a
-    /// byte read of `[0x4b43e0,0x4b43ec)`.
-    ///
-    /// The assertion is that a registered handler RAN, not that any frame repainted: the reference
-    /// verb mutates no state at all, and the repaint is FrameXML's, reached only through the event.
-    /// Asserting a repaint here would re-encode the `BenillaUpdateSpells` guess this replaces —
-    /// which was both narrower than the reference (it repainted `SpellButton1..N` and nothing else)
-    /// and wider (the reference gates its frame update on `IsVisible()`).
+    /// The assertion is that a handler ran, not that a frame repainted: the repaint is FrameXML's.
     #[test]
     fn update_spells_fires_spells_changed_and_touches_nothing() {
         let s = UiScript::new().unwrap();
@@ -1580,16 +1297,12 @@ mod tests {
             1,
             "UpdateSpells must fire SPELLS_CHANGED synchronously, as SignalEvent does"
         );
-        // Zero return values — `arity = 0 (exact)` in `reference/1.12-shapes.tsv`.
+        // Zero returns, `reference/1.12-shapes.tsv`'s `arity = 0 (exact)`.
         assert_eq!(s.arity("UpdateSpells()").unwrap(), 0);
         assert!(s.errors().is_empty(), "errors: {:?}", s.errors());
     }
 
-    /// **`PlayerHasSpells()` is a hard-coded `1`** (1924): `push 0x3ff00000; push 0;
-    /// lua_pushnumber; mov eax,1; ret` — no branch and no store read, so it cannot answer anything
-    /// else. Asserted on an EMPTY spellbook precisely because that is the state where a
-    /// plausible-looking "does the player have any spells?" implementation would answer 0 and
-    /// diverge silently.
+    /// On an empty book, where a "has any spells" reading would answer 0.
     #[test]
     fn player_has_spells_is_one_even_with_an_empty_book() {
         let s = UiScript::new().unwrap();
@@ -1598,11 +1311,7 @@ mod tests {
         assert_eq!(s.arity("PlayerHasSpells()").unwrap(), 1);
     }
 
-    /// **Out of range answers `nil, nil, 0, 0` — four values, the last two NUMBERS** (1931). The
-    /// count is the assertion: `GetSpellTabInfo(0) == nil` is true either way, which is exactly how
-    /// the old one-nil shape passed. Stock `SpellBookFrame.lua:295` does `id > (offset + numSpells)`
-    /// unguarded straight off `SpellBookFrame_OnLoad`, so slots 3+4 nil is a raise on load, and
-    /// `(0+0)` is what makes the reference hide every button — the behaviour this pins.
+    /// The count is the assertion: `(GetSpellTabInfo(0)) == nil` holds for a single nil too.
     #[test]
     fn out_of_range_answers_four_values() {
         let s = UiScript::new().unwrap();
@@ -1626,9 +1335,6 @@ mod tests {
         }
     }
 
-    /// The argument is shape A (1931): absent or non-numeric RAISES the reference's own usage
-    /// string; a numeric STRING is coerced; a negative is truncated and falls to the fallback
-    /// rather than raising. `-1` and `0.5` are covered by the test above.
     #[test]
     fn tab_index_raises_when_absent_and_coerces_a_numeric_string() {
         let mut s = UiScript::new().unwrap();
@@ -1645,7 +1351,7 @@ mod tests {
             );
         }
         s.set_spellbook(book());
-        // "1" coerces exactly as 1 does — same name comes back.
+        // "1" coerces as 1 does.
         assert_eq!(
             s.eval::<String>("return (GetSpellTabInfo('1'))").unwrap(),
             s.eval::<String>("return (GetSpellTabInfo(1))").unwrap()
diff --git a/crates/benilla-ui/src/script/stable.rs b/crates/benilla-ui/src/script/stable.rs
index 7e7a0eb5..72d07a57 100644
--- a/crates/benilla-ui/src/script/stable.rs
+++ b/crates/benilla-ui/src/script/stable.rs
@@ -1,159 +1,99 @@
-//! The stable-master bindings (decision 1676) — the hunter stable window's Lua surface, the same
-//! two-way seam as [`super::bank`] and [`super::trainer`]: the app pushes a **stable snapshot**
-//! ([`UiScript::set_stable`] — the wire's pet rows already resolved to icon/family/loyalty/diet
-//! strings), and the Lua's click/purchase/close calls queue outbound **intents** the app drains.
+//! The stable-master bindings: the app pushes a snapshot of the hunter's stable
+//! ([`UiScript::set_stable`], every wire row resolved to strings) and the Lua's clicks queue verbs
+//! the app drains.
 //!
-//! ## Three slots, and the current pet is one of them
+//! The window shows slots 0..=2: 0 is the current pet, 1 and 2 the stable slots a hunter buys
+//! (`NUM_PET_STABLE_SLOTS` 2, two `StableSlotPrices.dbc` rows, vmangos `MAX_PET_STABLES` 2). The
+//! wire's 1-based slot arrives rebased ([`benilla_protocol::messages::StabledPet::slot`]). Slot 0
+//! can hold a row with no pet out: a dismissed or distant pet still comes from the server's
+//! character-pet cache, and the stock window falls back to `GetStablePetInfo(0)` when
+//! `UnitExists("pet")` is false (`PetStable.lua:138`).
 //!
-//! The window shows **`0..=2`**: slot `0` is the pet at the player's side, slots `1` and `2` are the
-//! two stable slots a hunter buys (5875 ships exactly two — `StableSlotPrices.dbc` has two rows,
-//! vmangos's `MAX_PET_STABLES` is 2, and the reference's `NUM_PET_STABLE_SLOTS` is 2). The wire is
-//! 1-based over these; [`benilla_protocol::messages::StabledPet::slot`] already rebased it, so
-//! everything here speaks the reference UI's own indices.
-//!
-//! **Slot 0 can be occupied while the player has no pet out.** A hunter whose pet is dismissed (or
-//! merely too far away to be summoned) still gets a slot-0 row from the server, read off the
-//! character-pet cache — which is exactly why the reference falls back to `GetStablePetInfo(0)`
-//! when `UnitExists("pet")` is false (`PetStable.lua:131-146`) instead of showing an empty slot.
-//!
-//! ## What the snapshot resolves, and why the app does it
-//!
-//! The wire names a `creature_template` entry and a loyalty *level*; the window wants an icon, a
-//! localized family word, a loyalty *name* and a diet list. Every one of those is a catalog join
-//! the app already owns for the live pet ([`super::pet`], decisions 1005/1062), so the app does the
-//! join once and pushes strings — this module never sees a DBC. The one join with no live-pet twin
-//! is the icon of a pet that is *not* summoned: it comes from the creature query's display id,
-//! which is why that field stopped being discarded (decision 1676).
-//!
-//! ## The drag rides the cursor at mode 10
-//!
-//! `PickupStablePet` puts the pet on the **global cursor** under payload mode 10
-//! ([`super::cursor::CursorPayload::StablePet`]), carrying the stable index the grab recorded.
-//!
-//! This corrects what benilla shipped first. The original build made the drag frame-local, reading
-//! payload mode 10 as a class/talent-ability id rather than the stabled-pet grab. `0x495020` **is**
-//! the stabled-pet grab, and `[0xb4d900] = 10` is written at exactly one site image-wide, inside
-//! it. Decision 1677.
-//!
-//! ## Two return conventions that are the API, not details
-//!
-//! `ClickStablePet` returns **exactly one value, always**, and which one is keyed *solely* on
-//! whether the cursor was holding a pet — never on whether a packet went out:
-//!
-//! - **a plain click** (no payload) is a pure select and pushes the number `1.0` on all three of
-//!   its legs, so it is **always truthy** and the reference always repaints;
-//! - **a drop** pushes **nil** on every leg, including the ones that send a packet, so the
-//!   reference never repaints from the drop — the repaint comes from the server's next list.
-//!
-//! Getting this backwards is invisible in a test that only checks the packets and very visible in
-//! play: the window would repaint off a stale snapshot on every drag and skip the repaint on every
-//! click.
+//! `PickupStablePet` puts the pet on the global cursor as payload mode 10
+//! ([`super::cursor::CursorPayload::StablePet`]): `[0xb4d900] = 10` is written at one site,
+//! `0x4950ae`, in the stabled-pet grab `0x495010`.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// Window slots: the current pet (`0`) plus the two stable slots — the reference's
-/// `NUM_PET_STABLE_SLOTS = 2` counted inclusively from zero (`PetStable.lua:1`).
+/// The current pet plus the `NUM_PET_STABLE_SLOTS` (2) stable slots (`PetStable.lua:1`).
 pub const NUM_STABLE_SLOTS: usize = 3;
 
-/// One row of the stable window, with every wire field already resolved to what the Lua renders.
-/// `None` in [`StableState::slots`] is an empty slot — which the window draws differently from an
-/// *unbought* one (that distinction is [`StableState::num_stable_slots`]'s).
+/// One stable window row, every wire field resolved to what the Lua renders. An empty slot is
+/// `None` in [`StableState::slots`]; an unbought one lies past [`StableState::num_stable_slots`].
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct StablePetSlot {
-    /// The pet's own id — what [`StableIntent::Unstable`]/[`StableIntent::Swap`] name on the wire.
-    /// Never its slot: the two disagree for any hunter whose stable is not in id order.
+    /// The pet's id, which the unstable and swap verbs name; never its slot.
     pub pet_number: u32,
-    /// `Interface\Icons\…` for the pet's family, or `None` while the creature query is in flight.
-    /// The reference passes this straight to `SetItemButtonTexture`, which takes an empty texture
-    /// for a missing icon — so `None` renders the empty-slot art, not a white square (decision
-    /// 1046's sweep).
+    /// The family icon path, `None` while the creature query is in flight; the stock window passes
+    /// it to `SetItemButtonTexture`, which draws the empty-slot art for nil.
     pub icon: Option<String>,
     /// The name the hunter gave the pet, not the creature template's.
     pub name: String,
     pub level: u32,
-    /// The localized `CreatureFamily.dbc` word ("Wolf", "Cat"). `None` when the creature query has
-    /// not landed — the reference concatenates it into the level line unguarded, so the binding
-    /// substitutes an empty string rather than handing Lua a nil to concatenate.
+    /// The localized `CreatureFamily.dbc` word ("Wolf"), `None` until the creature query lands.
     pub family: Option<String>,
     /// The localized `PetLoyalty.dbc` name for the wire's loyalty level.
     pub loyalty: Option<String>,
-    /// The localized pet-food names this pet's family eats — `GetStablePetFoodTypes`'s returns,
-    /// which the reference joins with `BuildListString` into the diet tooltip.
+    /// The localized food names the pet's family eats: `GetStablePetFoodTypes`'s returns.
     pub diet: Vec<String>,
 }
 
-/// The open stable window's snapshot. Pushed whole while a stable session is open; `None` = no
-/// stable open (the window is closed).
+/// The open stable's snapshot, pushed whole; `None` when no stable is open.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct StableState {
-    /// Stable slots **purchased**, `0..=2` (the wire's `numStableSlots`). Not a count of occupied
-    /// ones: it is what enables slot buttons `1..=num` and greys the rest, and what prices the next
-    /// purchase.
+    /// Stable slots bought, 0..=2 (the wire's `numStableSlots`), not occupied: it enables buttons
+    /// `1..=n` and prices the next slot.
     pub num_stable_slots: u32,
-    /// The next slot's price in copper (`StableSlotPrices.dbc` row `num_stable_slots + 1`), or `0`
-    /// past the table — a state in which the reference has already hidden the purchase row.
+    /// The next slot's price in copper (`StableSlotPrices.dbc` row `num_stable_slots + 1`), 0 past
+    /// the table, where the stock window has hidden the purchase row.
     pub next_slot_cost: u32,
-    /// The three window slots; index `0` is the current pet.
+    /// The three window slots; index 0 is the current pet.
     pub slots: [Option<StablePetSlot>; NUM_STABLE_SLOTS],
-    /// The player has a **live** pet out — the client's own `[0xb714a0]|[0xb714a4]` guid test, the
-    /// gate that forks a stabled pet's drop between swap and unstable.
-    ///
-    /// **Deliberately not `slots[0].is_some()`.** A dismissed pet, or one left out of range, still
-    /// has a slot-0 row from the server's character-pet cache while the live guid is zero — so the
-    /// two disagree exactly there, and the client follows the guid.
+    /// A live pet is out: the client's pet-guid test (`[0xb714a0]|[0xb714a4]`), which forks a
+    /// stabled pet's drop between swap and unstable. Not `slots[0].is_some()`: a dismissed or
+    /// distant pet keeps its slot-0 row with no live guid.
     pub has_live_pet: bool,
 }
 
 impl StableState {
-    /// How many of the three slots hold a pet — `GetNumStablePets()`.
+    /// `GetNumStablePets()`: how many of the three slots hold a pet.
     fn num_pets(&self) -> u32 {
         self.slots.iter().filter(|s| s.is_some()).count() as u32
     }
 }
 
-/// An outbound stable verb the Lua asked for, drained by the app (which addresses it to the open
-/// session's NPC — the guid is the app's, never Lua's).
+/// An outbound stable verb, drained by the app, which addresses it to the open stable master.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum StableIntent {
-    /// `CMSG_STABLE_PET` — put the current pet away. **Carries no destination**: the server takes
-    /// the first free bought slot itself, so there is no "stable into slot 2" to express.
+    /// `CMSG_STABLE_PET`: stable the current pet; the server picks the first free bought slot.
     Stable,
-    /// `CMSG_UNSTABLE_PET` — summon this pet number, valid only with no current pet.
+    /// `CMSG_UNSTABLE_PET`: summon this pet number, valid only with no current pet.
     Unstable(u32),
-    /// `CMSG_STABLE_SWAP_PET` — trade the current pet for this pet number, in one step.
+    /// `CMSG_STABLE_SWAP_PET`: trade the current pet for this pet number in one step.
     Swap(u32),
-    /// `CMSG_BUY_STABLE_SLOT` — buy the next slot; the *which* is implicit, as with the bank's.
+    /// `CMSG_BUY_STABLE_SLOT`: buy the next slot.
     BuySlot,
 }
 
-/// The window's own transient state — selection and the frame-local drag (module doc: the cursor is
-/// not involved). Lives beside the snapshot rather than inside it because the app *replaces* the
-/// snapshot on every list packet, and a repaint must not drop what the player has selected.
+/// The window's own state beside the snapshot: the selection, the queued verbs and the close flag.
 #[derive(Debug)]
 pub(crate) struct StableModel {
     pub(crate) state: Option<StableState>,
-    /// The selection, held **as the client holds it** (`[0xb72250]`): `-1` = the summoned pet,
-    /// `0` = nothing, otherwise a **petNumber**.
-    ///
-    /// A petNumber rather than a slot index because that is what the binary stores, and it is what
-    /// makes a *stale* selection degrade correctly: `GetSelectedStablePet` searches the array for
-    /// the number and answers `-1` when the pet is no longer there (fall-through `0x4cb84c`).
+    /// The selection as the client holds it (`[0xb72250]`): -1 the summoned pet, 0 nothing, else
+    /// a pet number, so a pet no longer listed reads back as nothing (`0x4cb84c`).
     pub(crate) selected: i32,
     pub(crate) intents: Vec<StableIntent>,
     pub(crate) close: bool,
 }
 
-/// The zero state is the client's `0` — "nothing selected" — not `-1`, which is its encoding for
-/// *the summoned pet*. The Lua-facing `-1` that `PetStable.lua:44` tests is
-/// [`super::UiScript::stable_selection`]'s translation of this, not this field.
+/// Nothing selected, the client's reset (`0x4caad3`); Lua reads it as -1 through
+/// [`super::UiScript::stable_selection`] (`PetStable.lua:50`).
 impl Default for StableModel {
     fn default() -> Self {
         Self {
             state: None,
-            // `0` is "nothing selected" in the client's own encoding — NOT `-1`, which means the
-            // summoned pet. The window's zero state is the reset `0x4caad3` writes.
             selected: 0,
             intents: Vec::new(),
             close: false,
@@ -162,46 +102,36 @@ impl Default for StableModel {
 }
 
 impl super::UiScript {
-    /// Push (or clear, with `None`) the open stable's snapshot.
-    ///
-    /// **Every list message clears the selection**, and that is the client's own behaviour
-    /// (`0x4cadf8` writes `[0xb72250] = 0` on each one), not a simplification. The first build kept
-    /// it across a refresh on the reasoning that benilla re-lists after every action and a reset
-    /// would "fight the player" — but the reference re-lists on exactly the same
-    /// successes and clears every time. It does not fight anything, because `PetStable_Update`
-    /// immediately re-picks: the current pet if there is one, else the first occupied slot
-    /// (`PetStable.lua:44-59`). Keeping a selection across a list is what would be wrong — it can
-    /// name a pet the new list no longer contains.
+    /// Push the open stable's snapshot, or clear it with `None`. Every push clears the selection,
+    /// as each list does in the client (`0x4cadf8`); the stock window then re-picks the current pet
+    /// or the first occupied slot (`PetStable.lua:49-62`).
     pub fn set_stable(&mut self, state: Option<StableState>) {
         let mut model = self.model_mut();
         model.stable.selected = 0;
-        // The held payload is NOT dropped here: closing the window clears only the stable-master
-        // guid in the reference (`0x4cae10`), and a picked-up pet lives on the shared cursor, whose
-        // own ClearCursor arms own it.
+        // A held pet stays on the cursor: the reference's close clears only the stable-master
+        // guid (`0x4cae10`).
         model.stable.state = state;
     }
 
-    /// Drain the queued stable verbs (module doc: the app addresses them to the open NPC).
+    /// Drain the queued stable verbs.
     pub fn take_stable_intents(&mut self) -> Vec<StableIntent> {
         std::mem::take(&mut self.model_mut().stable.intents)
     }
 
-    /// Whether `ClosePetStables()` was called since the last drain (and clear the flag). No packet
-    /// exists for it — the app just clears its local session, the bank/merchant pattern.
+    /// Whether `ClosePetStables()` was called since the last drain; no packet exists for it.
     pub fn take_stable_close(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().stable.close)
     }
 
-    /// `GetSelectedStablePet()`'s answer — **`0` = the summoned pet, `1..=2` a stable slot, `-1`
-    /// nothing** — translated out of the petNumber the model holds, exactly as `0x4cb800` does
-    /// (find the number in the array, `inc eax`; a number no longer present falls through to `-1`).
+    /// `GetSelectedStablePet()`'s answer, translated from the held pet number: 0 the summoned
+    /// pet, 1..=2 a stable slot, -1 nothing.
     pub fn stable_selection(&mut self) -> i32 {
         let model = self.model_mut();
         selected_slot(&model.stable)
     }
 }
 
-/// The petNumber→slot translation behind `GetSelectedStablePet` (`0x4cb810`).
+/// The pet number to slot translation behind `GetSelectedStablePet` (`0x4cb810`).
 fn selected_slot(m: &StableModel) -> i32 {
     match m.selected {
         -1 => 0,
@@ -220,52 +150,31 @@ fn selected_slot(m: &StableModel) -> i32 {
                     })
                     .map(|(i, _)| i as i32)
             })
-            // A selection whose pet is gone after a refresh degrades to "nothing", never to a
-            // wrong slot — the loop's own fall-through at `0x4cb84c`.
+            // A pet no longer listed reads as nothing, the loop's fall-through at `0x4cb84c`.
             .unwrap_or(-1),
     }
 }
 
-/// Read a slot argument into an index into [`StableState::slots`]. Out-of-range answers `None`, so
-/// every binding below degrades to the reference's empty-slot behaviour rather than panicking on a
-/// stray addon call.
+/// A slot argument as an index into [`StableState::slots`], `None` out of range.
 fn slot_index(i: i64) -> Option<usize> {
     usize::try_from(i).ok().filter(|&i| i < NUM_STABLE_SLOTS)
 }
 
-/// Commit a drag from slot `from` onto slot `to` — the **one** place the stable's move law lives,
-/// now read off the binary (`ClickStablePet 0x4cb420` regime B; decision 1677).
-///
-/// The first build inferred this from the server's constraint set and got the shape right and the
-/// **three edges wrong**. Each of them is a real case:
-///
-/// 1. **The summoned pet onto an OCCUPIED stable slot sends `SWAP`, not `STABLE`.** "Drag out ⇒
-///    stable it" only holds when the target slot is empty. The inferred version sent `STABLE` for
-///    both, which vmangos then refuses whenever both bought slots are full — the pet stays put and
-///    nothing says why.
-/// 2. **A drop onto an UNPURCHASED slot sends nothing**, and is still a completed drop (cursor
-///    cleared, falsy return).
-/// 3. **A stabled pet onto the summoned slot forks on the LIVE PET GUID**, not on whether slot 0
-///    has a row. A dismissed pet has a row and no guid, and the client sends `UNSTABLE` there —
-///    the inferred version read the row and sent `SWAP`.
-///
-/// Stable→stable remains a no-op: 5875 has no opcode for it, which the first build did get right.
+/// The verb a drop from slot `from` onto slot `to` sends (`ClickStablePet 0x4cb420`): the summoned
+/// pet onto an occupied slot swaps, onto an empty bought slot stables, onto an unbought slot sends
+/// nothing; a stabled pet onto slot 0 swaps when a live pet is out, else unstables. Stable to
+/// stable has no opcode.
 fn drag_verb(from: u8, to: u8, state: &StableState) -> Option<StableIntent> {
     if from == to {
         return None;
     }
     let occupied = |i: u8| state.slots.get(usize::from(i)).and_then(|s| s.as_ref());
     match (from, to) {
-        // The summoned pet is held.
         (0, _) => match occupied(to) {
-            // …onto an occupied stable slot: trade places.
             Some(target) => Some(StableIntent::Swap(target.pet_number)),
-            // …onto an empty slot the player owns: stable it (the server picks the destination).
             None if u32::from(to) <= state.num_stable_slots => Some(StableIntent::Stable),
-            // …onto a slot they have not bought: nothing.
             None => None,
         },
-        // A stabled pet is held, dropped on the summoned slot.
         (_, 0) => occupied(from).map(|held| {
             if state.has_live_pet {
                 StableIntent::Swap(held.pet_number)
@@ -273,7 +182,6 @@ fn drag_verb(from: u8, to: u8, state: &StableState) -> Option<StableIntent> {
                 StableIntent::Unstable(held.pet_number)
             }
         }),
-        // Stable slot → stable slot: no opcode exists in 5875.
         _ => None,
     }
 }
@@ -282,10 +190,8 @@ fn drag_verb(from: u8, to: u8, state: &StableState) -> Option<StableIntent> {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetStablePetInfo(i) → icon, name, level, family, loyalty — **5 values on every reachable
-    // exit** (`0x4cb280`: `eax = 5` at both returns). A miss pushes `nil, nil, 0.0, nil, nil`, NOT
-    // nothing: the reference both tests the call for truthiness and destructures all five, and a
-    // bare nil would make `level` nil where the client answers 0.
+    // GetStablePetInfo(i) → icon, name, level, family, loyalty: five values on every exit
+    // (`0x4cb280`), a miss answering nil, nil, 0, nil, nil.
     g.set(
         "GetStablePetInfo",
         lua.create_function(|lua, i: i64| {
@@ -321,9 +227,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetStablePetFoodTypes(i) → the localized diet names, one return each (the reference feeds the
-    // lot to BuildListString). Nothing at all for an empty slot or a pet whose family has no diet —
-    // the reference guards with `if ( GetStablePetFoodTypes(i) )` before formatting the tooltip.
+    // GetStablePetFoodTypes(i) → one localized diet name per value; none for an empty slot or a
+    // family with no diet.
     g.set(
         "GetStablePetFoodTypes",
         lua.create_function(|lua, i: i64| {
@@ -343,8 +248,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetNumStableSlots() → slots PURCHASED (0..=2). The reference both enables buttons `i <= n`
-    // and hides the purchase row at `n == NUM_PET_STABLE_SLOTS` off this one number.
+    // GetNumStableSlots() → slots bought, 0..=2.
     g.set(
         "GetNumStableSlots",
         lua.create_function(|lua, ()| {
@@ -370,9 +274,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetNextStableSlotCost() → the next slot's price in copper (the app read it from
-    // StableSlotPrices.dbc). 0 with no stable open, and 0 past the table — where the reference has
-    // already hidden the row that would show it.
+    // GetNextStableSlotCost() → the next slot's price in copper, 0 with no stable open or past the
+    // table.
     g.set(
         "GetNextStableSlotCost",
         lua.create_function(|lua, ()| {
@@ -383,34 +286,25 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSelectedStablePet() → the selected slot, or -1. The sentinel is the API: the reference
-    // tests `selectedPet == -1` to decide whether to pick a slot for the player.
+    // GetSelectedStablePet() → the selected slot, or -1, on which the stock window picks one itself
+    // (`PetStable.lua:50`).
     g.set(
         "GetSelectedStablePet",
         lua.create_function(|lua, ()| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
-            // NOT the raw field: the model holds the client's petNumber encoding, and this binding
-            // is its translation to slot indices (`selected_slot`).
             Ok(i64::from(selected_slot(&model.stable)))
         })?,
     )?;
 
-    // ClickStablePet(i) → **exactly one value, always**, and which one is keyed SOLELY on whether
-    // the cursor held a pet — never on whether a packet went out (`0x4cb420`).
-    //
-    //   plain click  -> pure select, no packet, pushes 1.0 on ALL THREE legs  => always TRUTHY
-    //   drop         -> clears the cursor, pushes nil on EVERY leg            => always FALSY
-    //
-    // So the reference repaints on every click and on NO drop; a drop's repaint arrives with the
-    // server's next list. The first build had this inverted (true on a committed drag, false on a
-    // no-op) — invisible to a packet-only test, and in play a window that repaints off a stale
-    // snapshot on every drag and skips the repaint on every click.
+    // ClickStablePet(i) → one value (`0x4cb420`), keyed only on whether the cursor held a pet: a
+    // plain click selects and answers 1, so the stock window repaints; a drop answers nil, packet
+    // or not, and the repaint comes with the server's next list.
     g.set(
         "ClickStablePet",
         lua.create_function(|lua, i: i64| {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
             let Some(to) = slot_index(i) else {
-                // Out of range still takes the select leg's "nothing" arm below.
+                // Out of range: a click selects nothing, a drop clears the cursor.
                 if !matches!(
                     model.cursor,
                     Some(super::cursor::CursorPayload::StablePet(_))
@@ -423,7 +317,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             };
             let to = to as u8;
 
-            // Regime B — a drop.
+            // A drop.
             if let Some(super::cursor::CursorPayload::StablePet(held)) = model.cursor.clone() {
                 let from = held.slot;
                 let intent = model
@@ -438,7 +332,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 return Ok(Value::Nil);
             }
 
-            // Regime A — a plain click: pure select, always truthy.
+            // A plain click: select only.
             let pet_number = model
                 .stable
                 .state
@@ -446,21 +340,18 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 .and_then(|s| s.slots[usize::from(to)].as_ref())
                 .map(|p| p.pet_number);
             model.stable.selected = match (to, pet_number) {
-                // Slot 0 selects the summoned pet by its own sentinel, not by a petNumber.
+                // Slot 0 selects the summoned pet by its sentinel, not a pet number.
                 (0, _) => -1,
                 (_, Some(n)) => n as i32,
-                // An empty (or unowned) slot selects NOTHING, rather than the slot itself.
+                // An empty slot selects nothing.
                 (_, None) => 0,
             };
             Ok(Value::Number(1.0))
         })?,
     )?;
 
-    // PickupStablePet(i) — the mode-10 grab. **0 Lua values, always.**
-    //
-    // The client's gate is the family ICON path, not occupancy (`0x495010`: resolve the record,
-    // require a non-empty `CreatureFamily` icon, then set the payload). Ours is the resolved icon,
-    // which is the same test one step later: no icon, no grab.
+    // PickupStablePet(i): the mode-10 cursor grab, returning nothing. The gate is the family icon,
+    // not occupancy (`0x495010`): no icon, no grab.
     g.set(
         "PickupStablePet",
         lua.create_function(|lua, i: i64| {
@@ -481,9 +372,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // StablePet() — 0 args, and it makes no Lua call at all in the reference: its only gate is a
-    // stable master being open, which for us is the snapshot's existence. Not called by the shipped
-    // FrameXML (the drag path sends this verb); it exists because the binding does.
+    // StablePet(): no arguments, gated only on an open stable; stock FrameXML stables by drag.
     g.set(
         "StablePet",
         lua.create_function(|lua, ()| {
@@ -495,10 +384,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnstablePet(i) — carries a gate the drag path does NOT: it requires no charmed unit and **no
-    // pet out** (`0x468550`), and bails SILENTLY otherwise, with no packet and no error. Its
-    // unsigned bound also rejects index 0 outright, where the drag path treats 0 as the summoned
-    // pet.
+    // UnstablePet(i): silently refused with a pet out (`0x468550`), a gate the drag path lacks; its
+    // unsigned bound rejects slot 0. The reference's other gate, no charmed unit, is not built.
     g.set(
         "UnstablePet",
         lua.create_function(|lua, i: i64| {
@@ -524,28 +411,20 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetPetStablePaperdoll(model) — inert here, deliberately, and this is the same divergence
-    // PetPaperDollFrame.xml records for `PetModelFrame:SetUnit("pet")`: benilla's model panes are
-    // app-side booths that follow the selection every frame, so there is no VM-side unit to point.
-    // The binding still exists because the reference calls it (four sites) and an addon may.
+    // Deviation: SetPetStablePaperdoll(model) is inert, because the model pane is an app-side
+    // booth that follows the selection every frame, with no VM-side unit to point.
     g.set(
         "SetPetStablePaperdoll",
         lua.create_function(|_, _model: Value| Ok(()))?,
     )?;
 
-    // BuyStableSlot() — 0 args, with the client's own **silent** local gates in order: a stable
-    // master open · the hard cap `slots != 2` (`0x4cb0c4`) · a price row exists · **affordability**
-    // (`0x4cb122`). None of them shows a message; the reference disables the button instead.
-    // Applying them here rather than trusting the button matters because an addon can call the
-    // binding directly, and the server's refusal for the cap is the same indistinguishable
-    // ERR_STABLE as everything else.
+    // BuyStableSlot(): the client's silent gates, in order: an open stable, fewer than 2 slots
+    // (`0x4cb0c4`), a price row and affordability (`0x4cb122`).
     g.set(
         "BuyStableSlot",
         lua.create_function(|lua, ()| {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // Affordability reads the VM's own purse — the same `model.money` the reference's
-            // `GetMoney()` returns and its own button-state ladder compares (`PetStable.lua:203`),
-            // rather than a second copy of the number in the stable snapshot.
+            // Affordability reads `model.money`, the purse `GetMoney()` answers.
             let money = model.money;
             let allowed = model.stable.state.as_ref().is_some_and(|s| {
                 s.num_stable_slots as usize != NUM_STABLE_SLOTS - 1
@@ -559,8 +438,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ClosePetStables() — client-side close, no packet exists (vmangos has no close opcode): flag
-    // the app to clear its session.
+    // ClosePetStables(): no packet exists; the flag tells the app to clear its session.
     g.set(
         "ClosePetStables",
         lua.create_function(|lua, ()| {
@@ -608,7 +486,6 @@ mod tests {
         ])));
     }
 
-    /// The read surface, through the reference's own destructuring.
     #[test]
     fn the_read_surface_answers_the_reference_calls() {
         let mut s = UiScript::new().unwrap();
@@ -625,7 +502,7 @@ mod tests {
             50_000
         );
 
-        // `PetStable.lua:76` — the exact five-value destructuring the window renders from.
+        // `PetStable.lua:77`'s five-value destructuring.
         assert_eq!(
             s.eval::<(String, String, i64, String, String)>(
                 "local i, n, l, f, loy = GetStablePetInfo(1) return i, n, l, f, loy"
@@ -650,17 +527,13 @@ mod tests {
             .unwrap());
     }
 
-    /// **`GetStablePetInfo` returns five values on EVERY exit** (`eax = 5` at both returns), with a
-    /// miss pushing `nil, nil, 0, nil, nil`. The reference both tests the call for truthiness and
-    /// destructures all five, so a bare nil would leave `level` nil where the client answers 0 —
-    /// and would silently change the arity an addon sees.
     #[test]
     fn a_missing_pet_still_answers_five_values() {
         let mut s = UiScript::new().unwrap();
         open(&mut s);
         for call in ["GetStablePetInfo(2)", "GetStablePetInfo(9)"] {
             assert_eq!(s.arity(call).unwrap(), 5, "{call} arity");
-            // Still falsy on the reference's own `if ( GetStablePetInfo(i) )` test.
+            // Still falsy for the stock window's `if ( GetStablePetInfo(i) )`.
             assert!(s.eval::<bool>(&format!("return not {call}")).unwrap());
             assert_eq!(
                 s.eval::<i64>(&format!("local _, _, l = {call} return l"))
@@ -671,9 +544,6 @@ mod tests {
         }
     }
 
-    /// **A plain click always returns truthy**, on all three of its legs — including a re-click of
-    /// the same slot and a click on an empty one. The reference repaints on the return, so a
-    /// falsy answer anywhere here is a window that stops repainting on click.
     #[test]
     fn every_plain_click_returns_truthy() {
         let mut s = UiScript::new().unwrap();
@@ -696,9 +566,6 @@ mod tests {
         );
     }
 
-    /// The selection's three encodings, read back through `GetSelectedStablePet`'s translation:
-    /// slot 0 answers 0, an occupied stable slot answers its index, and an **empty** slot selects
-    /// nothing (`-1`) rather than itself.
     #[test]
     fn the_selection_translates_back_to_slot_indices() {
         let mut s = UiScript::new().unwrap();
@@ -715,8 +582,6 @@ mod tests {
         );
     }
 
-    /// A selection is held as a **petNumber**, so a refresh that no longer contains that pet
-    /// degrades to "nothing" rather than to a wrong slot — and every list clears it anyway.
     #[test]
     fn a_list_clears_the_selection_and_a_stale_pet_degrades() {
         let mut s = UiScript::new().unwrap();
@@ -724,34 +589,28 @@ mod tests {
         s.eval::<()>("ClickStablePet(1)").unwrap();
         assert_eq!(s.stable_selection(), 1);
 
-        // Every list message clears it (`0x4cadf8`) — the reference re-picks in PetStable_Update.
+        // Every list clears it (`0x4cadf8`).
         open(&mut s);
         assert_eq!(s.stable_selection(), -1, "a list clears the selection");
     }
 
-    /// **A drop always returns nil**, on every leg — the ones that send a packet included. The
-    /// reference therefore never repaints from a drop; the repaint arrives with the server's next
-    /// list. This is the convention the first build had inverted.
     #[test]
     fn every_drop_returns_falsy_even_when_it_sends() {
         let mut s = UiScript::new().unwrap();
         open(&mut s);
-        // A drop that DOES send.
+        // A drop that sends.
         assert!(s
             .eval::<bool>("PickupStablePet(1) return ClickStablePet(0) == nil")
             .unwrap());
         assert_eq!(s.take_stable_intents(), vec![StableIntent::Swap(8)]);
 
-        // A drop that sends nothing is equally falsy.
+        // A drop that sends nothing.
         assert!(s
             .eval::<bool>("PickupStablePet(1) return ClickStablePet(1) == nil")
             .unwrap());
         assert!(s.take_stable_intents().is_empty());
     }
 
-    /// **The summoned pet onto an OCCUPIED stable slot is a SWAP, not a STABLE** — the first of the
-    /// three edges the inferred law got wrong. Sending STABLE there is refused by the server
-    /// whenever both bought slots are full, and nothing says why.
     #[test]
     fn dropping_onto_an_occupied_slot_swaps() {
         let mut s = UiScript::new().unwrap();
@@ -761,8 +620,6 @@ mod tests {
         assert_eq!(s.take_stable_intents(), vec![StableIntent::Swap(8)]);
     }
 
-    /// …and onto an EMPTY slot the player owns it is a STABLE, whose destination the wire cannot
-    /// carry; onto one they have **not bought**, nothing at all — but the cursor still clears.
     #[test]
     fn an_unpurchased_slot_takes_the_drop_and_sends_nothing() {
         let mut s = UiScript::new().unwrap();
@@ -775,14 +632,11 @@ mod tests {
         s.eval::<()>("PickupStablePet(0) ClickStablePet(2)")
             .unwrap();
         assert!(s.take_stable_intents().is_empty(), "slot 2 is not bought");
-        // The drop completed: the cursor is empty, so the next click SELECTS.
+        // The drop completed: the cursor is empty, so the next click selects.
         assert!(s.eval::<bool>("return ClickStablePet(1) and true").unwrap());
         assert!(s.take_stable_intents().is_empty());
     }
 
-    /// **The stabled→summoned fork reads the LIVE PET GUID, not slot 0's row** — the third edge.
-    /// A dismissed pet still has a row from the server's character-pet cache while the guid is
-    /// zero, and the client sends UNSTABLE there.
     #[test]
     fn the_fork_follows_the_live_pet_not_the_row() {
         let mut s = UiScript::new().unwrap();
@@ -804,7 +658,6 @@ mod tests {
         );
     }
 
-    /// Stable→stable has no opcode in 5875, and an empty slot carries nothing to grab.
     #[test]
     fn stable_to_stable_is_a_no_op_and_empty_slots_do_not_grab() {
         let mut s = UiScript::new().unwrap();
@@ -823,8 +676,6 @@ mod tests {
         assert!(s.take_stable_intents().is_empty());
     }
 
-    /// `BuyStableSlot`'s gates are the client's own, and all silent: the hard cap, and
-    /// affordability.
     #[test]
     fn buy_stable_slot_gates_locally_and_silently() {
         let mut s = UiScript::new().unwrap();
@@ -839,7 +690,7 @@ mod tests {
         s.eval::<()>("BuyStableSlot()").unwrap();
         assert!(s.take_stable_intents().is_empty(), "unaffordable is silent");
 
-        // Both slots owned — the hard cap (and money restored, so only the cap can refuse).
+        // Both slots owned, with money restored so only the cap refuses.
         s.set_money(1_000_000);
         let mut full = state([None, None, None]);
         full.num_stable_slots = 2;
@@ -848,8 +699,6 @@ mod tests {
         assert!(s.take_stable_intents().is_empty(), "the cap is silent");
     }
 
-    /// `UnstablePet` carries a gate the drag path does not: no pet out, else silence. And its
-    /// unsigned bound rejects index 0, where the drag path reads 0 as the summoned pet.
     #[test]
     fn the_unstable_binding_gates_where_the_drag_path_does_not() {
         let mut s = UiScript::new().unwrap();
@@ -866,8 +715,6 @@ mod tests {
         assert_eq!(s.take_stable_intents(), vec![StableIntent::Unstable(8)]);
     }
 
-    /// The close intent, and that closing does NOT drop a held pet — the reference's close clears
-    /// only the stable-master guid.
     #[test]
     fn close_drains_and_leaves_the_cursor_alone() {
         let mut s = UiScript::new().unwrap();
@@ -878,7 +725,6 @@ mod tests {
         assert!(!s.take_stable_close(), "drain clears");
     }
 
-    /// `SetPetStablePaperdoll` exists and is harmless — the reference calls it at four sites.
     #[test]
     fn the_paperdoll_setter_is_callable() {
         let s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/statusbar.rs b/crates/benilla-ui/src/script/statusbar.rs
index 070dc9d0..d7047bd4 100644
--- a/crates/benilla-ui/src/script/statusbar.rs
+++ b/crates/benilla-ui/src/script/statusbar.rs
@@ -1,17 +1,8 @@
-//! The `StatusBar` method surface — the first *per-kind* widget behavior over the kind tag
-//! (`CSimpleStatusBar`, factory `0x6eef20`).
-//!
-//! Grounded in the reference's StatusBar `LoadXML 0x782ef0`:
-//! a reversed `min > max` pair is swapped, `defaultValue` routes through SetValue, orientation is
-//! the shared enum HORIZONTAL=0/VERTICAL=1 (`0x811b00`), the bar texture's layer defaults ARTWORK,
-//! and the widget adds the `OnValueChanged` script slot (`+0x32c`). The **fill** mechanism is
-//! byte-pinned too (`0x770410`): `SetValue` writes the bar region's 4-corner UV block with
-//! `u1 = GetValue()` *and* recomputes `right = left + frac·width`, so the fill is a left-anchored
-//! **crop** — the art is sliced, never squeezed. Applied at extract (`bar_fill_rect`/`bar_fill_uv`).
-//!
-//! The methods live in their own registry table, consulted by the frame `__index` dispatcher only
-//! for StatusBar frames — so duck-typing addons (`if frame.SetValue then …`) see `nil` on every
-//! other kind, exactly as against the client's per-class method sets.
+//! The `StatusBar` methods (`CSimpleStatusBar`, factory `0x6eef20`, `LoadXML` `0x782ef0`,
+//! orientations `0x811b00`). The fill is a left-anchored crop, the art sliced and never squeezed:
+//! `SetValue` sets the UV's `u1` to the fill fraction and the right edge with it (`0x770410`),
+//! applied at extract.
+//! Only StatusBar frames answer these, so a duck-typing addon sees nil on every other kind.
 
 use mlua::{Lua, Table, Value};
 
@@ -21,12 +12,11 @@ use super::{event, Model, RegionData};
 use crate::order::DrawLayer;
 use crate::widget::{KindState, RegionKind, StatusBarState};
 
-/// Registry key of the StatusBar method table (the MAXCSTACK discipline: Lua-side root, named key).
+/// Registry key of the StatusBar method table.
 pub(super) const REG_STATUSBAR_METHODS: &str = "__benilla_statusbar_methods";
 
-/// Run `f` over a frame's StatusBar state under one short write borrow. Errors if `this` is not a
-/// live StatusBar (unreachable through the kind dispatcher, but the method table is a plain Lua
-/// value — a caller can fish it out and misapply it).
+/// Run `f` over a frame's StatusBar state; errors on any other receiver, since the method table
+/// is a plain Lua value a caller can misapply.
 fn with_bar<T>(
     lua: &Lua,
     this: &Table,
@@ -44,8 +34,8 @@ fn with_bar<T>(
     }
 }
 
-/// Store a (clamped) value; returns `Some(new_value)` if it actually changed — the caller fires
-/// `OnValueChanged`. Degenerate range (`max <= min`) pins to `min` (zero-init members).
+/// Store the value clamped to the range, `Some` when it changed (the caller fires
+/// `OnValueChanged`); a degenerate range pins to `min`.
 fn store_value(sb: &mut StatusBarState, v: f32) -> Option<f32> {
     let clamped = v.clamp(sb.min, sb.max.max(sb.min));
     (clamped != sb.value).then(|| {
@@ -54,8 +44,8 @@ fn store_value(sb: &mut StatusBarState, v: f32) -> Option<f32> {
     })
 }
 
-/// Get-or-create the bar-fill texture region (`SetStatusBarTexture`/`<BarTexture>`); `layer`
-/// re-layers an existing bar. Returns the region's id (for wrapper lookup).
+/// Get or create the bar texture region, `ARTWORK` by default as in the reference; `layer`
+/// re-layers an existing one.
 fn ensure_bar(lua: &Lua, this: &Table, layer: Option<DrawLayer>) -> mlua::Result<u32> {
     let h = frame_handle_of(lua, this)?;
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -88,7 +78,7 @@ fn ensure_bar(lua: &Lua, this: &Table, layer: Option<DrawLayer>) -> mlua::Result
                 )
                 .ok_or_else(|| mlua::Error::runtime("stale frame handle"))?;
             model.region_data.insert(rh, RegionData::default());
-            model.touch_layout(); // a region entered the layout gate's read set (decision 0740)
+            model.touch_layout(); // a region entered the layout gate's read set
             if let Some(frame) = model.arena.frame_mut(h) {
                 if let KindState::StatusBar(sb) = &mut frame.kind_state {
                     sb.bar = Some(rh);
@@ -106,9 +96,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     m.set(
         "SetMinMaxValues",
         lua.create_function(|lua, (this, min, max): (Table, f32, f32)| {
-            // A reversed pair is swapped (`LoadXML 0x782ef0` does the same) — one behavior for the
-            // XML and API paths. The held value re-clamps into the new range; a move fires
-            // OnValueChanged, as a value change the caller didn't make explicitly is still a change.
+            // A reversed pair is swapped, as `LoadXML` does; the held value re-clamps, and a move
+            // fires `OnValueChanged`.
             let changed = with_bar(lua, &this, |sb| {
                 (sb.min, sb.max) = if min <= max { (min, max) } else { (max, min) };
                 store_value(sb, sb.value)
@@ -154,8 +143,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetStatusBarTexture(path [, drawLayer]) | SetStatusBarTexture(r, g, b [, a]) — the same two
-    // forms as a region's SetTexture, targeting the bar region (created on first use).
+    // A region's two `SetTexture` forms, `(path [, layer])` and `(r, g, b [, a])`, on the bar.
     m.set(
         "SetStatusBarTexture",
         lua.create_function(
@@ -176,9 +164,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                         data.texture = Some(s.to_str()?.to_string());
                         data.fill = None;
                     }
-                    // A solid bar writes the same slot the path form does — each clears the other.
-                    // `SetStatusBarColor` is the TINT (the fill region's vertex colour) and is a
-                    // separate slot entirely: a bar can carry art AND a colour, and they multiply.
+                    // A solid fill and a path clear each other; `SetStatusBarColor` is a separate
+                    // tint that multiplies either.
                     Value::Number(_) | Value::Integer(_) => {
                         data.texture = None;
                         data.fill = Some([
@@ -211,12 +198,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             }
         })?,
     )?;
-    // **Shape C on r, g, b** (`StatusBar:SetStatusBarColor `0x78fc20``, `2=C 3=C 4=C 5=B`): a bare
-    // `lua_tonumber` with no `lua_isnumber` gate, so a nil, a table or a string is **0.0** and the
-    // call never raises. Taking them as `f32` made mlua's
-    // converter the gate instead — the 2176 class — and the stock
-    // `QuestLogFrame.lua:337` idiom hands three nils (`titleButton.r/g/b` are only assigned in
-    // `QuestLog_Update`) on any path that selects a quest-log entry before the window has painted.
+    // `0x78fc20` reads r, g, b by a bare `lua_tonumber`, so nil, a table or a non-numeric string
+    // is 0.0 and the call never raises (a numeric string also reads 0.0 here). Stock hands colour
+    // setters nils: `QuestLogFrame.lua:337` passes three to `SetVertexColor`.
     m.set(
         "SetStatusBarColor",
         lua.create_function(
@@ -252,8 +236,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Fire `OnValueChanged(self, value)` if `changed` carries the new value (the StatusBar's own
-/// script slot `+0x32c`). Fired outside any model borrow; errors go to [`Model::errors`].
+/// Fire `OnValueChanged` (the StatusBar's script slot, `+0x32c`) for a changed value, outside any
+/// model borrow.
 fn fire_value_changed(lua: &Lua, this: &Table, changed: Option<f32>) -> mlua::Result<()> {
     let Some(value) = changed else { return Ok(()) };
     let id = {
@@ -274,14 +258,9 @@ fn fire_value_changed(lua: &Lua, this: &Table, changed: Option<f32>) -> mlua::Re
     Ok(())
 }
 
-/// `OnValueChanged` for a bar the ENGINE moved rather than Lua — the nameplate health bars, whose
-/// value the plate driver re-sets from the unit's descriptor each time it changes (decision 2148).
-///
-/// The reference fires the same script from the same place: the plate's bar is driven by a
-/// GUID-watch callback (`0x7cc570`, registered `0x467e70`) that re-reads health and re-sets the bar
-/// synchronously on every server update, and `SetValue` is `SetValue`. pfUI hooks this
-/// (`nameplates.lua:393` `HookScript(healthbar, "OnValueChanged", …)`) and reads `this:GetParent()`
-/// inside the handler, so a driver that moved the value silently would leave it blind.
+/// `OnValueChanged` for a bar the engine moved, the nameplate health bars: the reference re-sets
+/// them from a GUID-watch callback (`0x7cc570`, registered at `0x467e70`) on every server update,
+/// and that `SetValue` fires the script as any other does.
 pub(super) fn fire_engine_value_changed(lua: &Lua, bar: crate::widget::FrameHandle, value: f32) {
     let id = {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -299,7 +278,6 @@ pub(super) fn fire_engine_value_changed(lua: &Lua, bar: crate::widget::FrameHand
     }
 }
 
-/// A Lua number-ish → f32 (nil/other → 0.0), for the color-form arguments.
 fn num_f32(v: &Value) -> f32 {
     match v {
         Value::Number(n) => *n as f32,
diff --git a/crates/benilla-ui/src/script/stdlib.rs b/crates/benilla-ui/src/script/stdlib.rs
index e36ad791..86f5cb75 100644
--- a/crates/benilla-ui/src/script/stdlib.rs
+++ b/crates/benilla-ui/src/script/stdlib.rs
@@ -1,32 +1,18 @@
-//! The sandbox + the WoW stdlib layer — the global aliases and helpers FrameXML/addon Lua assumes
-//! exist on top of stock Lua 5.1 (decision 0068).
+//! The sandbox and the 1.12 stdlib layer on top of stock Lua 5.1.
 //!
-//! - **Sandbox** ([`sandbox`]): remove `io`/`os`/`package`/`require`/`dofile`/`loadfile`/`debug`
-//!   (keeping a `debugstack` stub returning `""`), and replace chunk loading with a **text-only**
-//!   `loadstring` (bytecode rejected). Decision 0068's threat model is "addon-observable behavior",
-//!   not anti-automation, but running untrusted addon Lua still means no filesystem/OS/native reach.
-//! - **Stdlib** ([`install`]): the nine bare-global aliases probe A found in the real corpus
-//!   (`format`/`strlen`/`gsub`/`strsub`/`strupper`/`tinsert`/`getn`/`tremove`/`strfind`), plus
-//!   `strlower`/`strrep`, `getglobal`/`setglobal`, and — the one non-trivial piece — a
-//!   `string.format` replacement
-//!   that supports Blizzard's positional `%N$` extension (probe A confirmed stock 5.1 rejects it).
-//!
-//! ## The positional `format` (`%N$`)
-//!
-//! Blizzard patched `string.format` to accept `printf`-style positional specs (`"%2$s %1$s"`) for
-//! localization. Stock Lua 5.1 does not (probe A, `semantics.rs` check (b)). We reimplement the
-//! reordering in Lua: scan the format, and if any spec carries `N$`, rewrite it into a plain
-//! sequential format with the arguments reordered, then delegate to the real `string.format`.
-//! **Mixing** positional and sequential specs in one string is an error — and it is in Blizzard's
-//! build too (their patch tracks a single "arg cursor" that a positional spec desyncs), so we match
-//! by erroring rather than guessing a blend. The wrapper is installed as both `string.format` and
-//! the bare global `format`.
+//! - [`sandbox`]: no filesystem, OS or native reach (`io`, `os`, `package`, `require`, `dofile`,
+//!   `loadfile`, `load`, `module`, `newproxy` and `debug` removed), the reference's `debugstack`,
+//!   and a text-only `loadstring`.
+//! - [`install`]: the 1.12 bare globals (string, table and math aliases, the `debug*` family, the
+//!   error-handler pair, the clock and zone getters), `time` and `date`, and a `string.format`
+//!   that accepts positional `%N$` specs as the 1.12 client's does, rewriting them into a
+//!   sequential format. Mixing positional and sequential specs raises, as in the reference,
+//!   whose single argument cursor a positional spec desyncs.
 
 use mlua::{Lua, Value, Variadic};
 
-/// The Lua-level message inside an mlua error — mlua decorates its `Display` with a category
-/// word (`syntax error: `, `runtime error: `) that the reference's own `lua_pushstring` leg never
-/// adds. `loadstring`'s second return is that message verbatim, so the decoration is stripped.
+/// An mlua error's bare Lua message, as `loadstring` returns it: without the `syntax error: ` or
+/// `runtime error: ` word mlua's `Display` adds and the reference never does.
 pub(super) fn lua_message(e: &mlua::Error) -> String {
     match e {
         mlua::Error::SyntaxError { message, .. } => message.clone(),
@@ -35,13 +21,12 @@ pub(super) fn lua_message(e: &mlua::Error) -> String {
     }
 }
 
-/// Sandbox the VM: strip filesystem/OS/native reach, keep a `debugstack` stub, and make chunk
-/// loading text-only.
+/// Sandbox the VM: no filesystem, OS or native reach, the reference's `debugstack`, and text-only
+/// chunk loading.
 pub(super) fn sandbox(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // Remove the dangerous surface. (Some may already be absent under mlua's safe stdlib; setting
-    // nil is idempotent and makes the guarantee explicit rather than mlua-version-dependent.)
+    // Set to nil explicitly, whatever mlua's safe stdlib already leaves out.
     for name in [
         "io", "os", "package", "require", "dofile", "loadfile", "load", "module", "newproxy",
         "debug",
@@ -49,46 +34,12 @@ pub(super) fn sandbox(lua: &Lua) -> mlua::Result<()> {
         g.set(name, Value::Nil)?;
     }
 
-    // `debugstack([start [, count1 [, count2]]])` — the client's own traceback, **frames only**.
-    //
-    // The stub this replaced returned `""`, which was justified as "real addons only display it".
-    // False: the corpus PARSES it, three different ways, and every one of them reads the string's
-    // shape rather than its contents.
-    //
-    // **There is no `stack traceback:` header, and line 1 is the caller's frame** (decision 2121).
-    // mlua's `Lua::traceback` is `luaL_traceback`, which emits that header — and the header cost a
-    // whole addon family its saved variables. `AceDB-2.0:RegisterDB` (`AceDB-2.0.lua:742`) does
-    //
-    //     local addonName = string.gsub(debugstack(), ".-\n.-\\AddOns\\(.-)\\.*", "%1")
-    //
-    // — skip exactly ONE line (its own frame), read the folder out of the NEXT one (its caller's).
-    // With a header in front, the "next" line is AceDB's own chunk, so every Ace2 addon resolved to
-    // whichever addon happened to ship the winning copy of the library. `AceDB.addonsLoaded` has
-    // that one flagged already, so `RegisterDB` took its *immediate* branch and bound `db.raw` to a
-    // fresh table at the addon's FILE SCOPE — before the SavedVariables chunk runs. The chunk then
-    // rebound the global and `db.raw` kept pointing at the orphan, so Bartender2 printed
-    // `Creating new DB` at every login and its file was frozen at what a first-run reset writes.
-    // Measured live: `Bartender.db.raw == BarDB` was **false**.
-    //
-    // Two more corpus readers pin the same shape independently, and they are the reason this emits
-    // Lua 5.0's frame wording rather than 5.4's:
-    //   - `AceLibrary.lua:70` takes the FIRST line whole (`string.gsub(stack, "\n.*", "")`) and
-    //     matches it against `".*\\(.*).lua:%d+: .*"` — so line 1 is a frame, `<src>:<line>: …`,
-    //     with no leading newline and no header above it.
-    //   - `AceLibrary.lua:139`'s `argCheck` reads the function name with `"([`<].-['>])"` — a
-    //     BACKTICK or `<` opening it. 5.0 writes ``in function `name'``; 5.4 writes
-    //     `in function 'name'`, which that pattern cannot match at all.
-    //
-    // So the body is `db_errorfb`'s (Lua 5.0 `ldblib.c`) with its header line removed: per frame
-    // `short_src`, then `:line` when there is one, then one of ``  in function `name' ``,
-    // `" in main chunk"`, `" ?"` (a C function) or `" in function <src:linedefined>"`.
-    //
-    // `start` is the level to begin at, default 1 = the caller (level 0 is this binding itself).
-    // `count1`/`count2` are 5.0's `LEVELS1`/`LEVELS2`: show `count1` frames from the top, then
-    // `...`, then the last `count2`. They are honoured rather than ignored because
-    // `FuBarPlugin-2.0.lua:752` passes `debugstack(6, 1, 0)` and reads the capture with a GREEDY
-    // `"\\AddOns\\(.*)\\"` — extra frames would hand it the LAST addon on the stack instead
-    // of its own.
+    // debugstack([start [, count1 [, count2]]]): the reference's traceback, frames only, in Lua
+    // 5.0's wording. There is no `stack traceback:` header and line 1 is the caller's frame:
+    // `AceDB-2.0.lua:742` skips one line to read its caller's addon folder, and `AceLibrary.lua:70`
+    // reads line 1 as a frame. `AceLibrary.lua:139` needs 5.0's ``in function `name'`` quoting,
+    // not later Luas' `'name'`. `start` defaults to 1, the caller; `count1`/`count2` are 5.0's
+    // `LEVELS1`/`LEVELS2`, which `FuBarPlugin-2.0.lua:752` relies on with `debugstack(6, 1, 0)`.
     g.set(
         "debugstack",
         lua.create_function(|lua, args: Variadic<Value>| {
@@ -104,33 +55,16 @@ pub(super) fn sandbox(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // Text-only `loadstring`: compile a *source* string (never bytecode). Returns `function` on
-    // success or `(nil, errmsg)` on failure — the stock `loadstring` contract. `set_mode(Text)`
-    // makes mlua reject a binary chunk (the `\27Lua` signature), the "loadstring of bytecode
-    // rejected" guarantee.
-    // The BOM strip and the `#`-line skip ride along, because in the reference they live *inside*
-    // `luaL_loadbuffer`/`luaX_setinput` — the same door `loadstring` goes through (decision 1193).
+    // Text-only `loadstring`: a binary chunk is rejected. The BOM strip and `#`-line skip apply,
+    // as in the reference they live inside `luaL_loadbuffer`/`luaX_setinput`.
     let loadstring = lua.create_function(
         |lua, (src, chunkname): (mlua::String, Option<mlua::String>)| {
             let raw = src.as_bytes();
             let bytes = crate::source::chunk(&raw).to_vec();
-            // **The chunk name is the caller's string VERBATIM, and it defaults to the SOURCE.**
-            // `luaB_loadstring 0x703280` is stock 5.0: `0x70329a` pushes `edi` — the pointer
-            // `luaL_checklstring` just returned — as `luaL_optlstring`'s `def`, so a nameless
-            // chunk is named by its own text and `luaO_chunkid 0x6f5c40` renders it by its third
-            // rule, `[string "…"]`, cut at the first newline and at the budget. There is no
-            // `.rdata` literal on that path at all (measured too, by running `0x703280` itself).
-            //
-            // We used to prepend `=`, which is `luaO_chunkid`'s "print this verbatim, undecorated"
-            // marker — so an explicit name lost its `[string "…"]` wrapper and a `@path` name kept
-            // a literal `@`, and a nameless chunk answered to `(loadstring)`, a literal the image
-            // does not contain. Both are player-visible: they are the prefix of every error a
-            // `loadstring` chunk raises.
-            //
-            // The name is taken from the **un-advanced** bytes on purpose: `luaL_loadbuffer
-            // 0x6f5690` strips a UTF-8 BOM from the buffer, but `0x703296` computed the name
-            // before that, so a BOM'd source compiles without its BOM while its chunk name still
-            // begins with one.
+            // The chunk name is the caller's string verbatim, defaulting to the source itself
+            // (`luaB_loadstring` `0x703280`, `0x70329a`), which `luaO_chunkid` `0x6f5c40` renders
+            // as `[string "…"]`. It comes from the raw bytes: `luaL_loadbuffer` `0x6f5690` strips
+            // a BOM only after `0x703296` took the name.
             let name = match &chunkname {
                 Some(n) => String::from_utf8_lossy(&n.as_bytes()).into_owned(),
                 None => String::from_utf8_lossy(&raw).into_owned(),
@@ -141,10 +75,8 @@ pub(super) fn sandbox(lua: &Lua) -> mlua::Result<()> {
                 .set_mode(mlua::ChunkMode::Text);
             match chunk.into_function() {
                 Ok(f) => Ok((Value::Function(f), Value::Nil)),
-                // `load_aux`'s failure leg pushes Lua's own message unchanged (`0x7032c6` nil,
-                // `0x7032d2` insert, `mov eax,2`). mlua's `Display` prefixes it with
-                // `syntax error: `, which is mlua's word and not the image's — an addon that shows
-                // the second return to a player would show that prefix too.
+                // The failure leg returns nil and Lua's own message, unprefixed (`0x7032c6`,
+                // `0x7032d2`).
                 Err(e) => Ok((
                     Value::Nil,
                     Value::String(lua.create_string(lua_message(&e))?),
@@ -157,12 +89,10 @@ pub(super) fn sandbox(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Install the WoW stdlib layer (the bare-global aliases, positional `format`, …).
+/// Install the stdlib layer: the bare globals, `time`/`date` and the positional `format`.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
-    // The default `geterrorhandler()` reports into the same channel a failed handler uses, so an
-    // addon's `geterrorhandler()(msg)` surfaces where every other script error does rather than
-    // vanishing (decision 1195). Named with the `__benilla_` prefix because it is host plumbing,
-    // not a 1.12 global — the reference's default handler is FrameXML's `_ERRORMESSAGE`.
+    // The default `geterrorhandler()` reports into the host's script-error channel; the
+    // `__benilla_` prefix marks host plumbing, not a 1.12 global.
     lua.globals().set(
         "__benilla_script_error",
         lua.create_function(|lua, msg: mlua::Value| {
@@ -183,17 +113,14 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         .set_name("=[benilla wow stdlib]")
         .set_mode(mlua::ChunkMode::Text)
         .exec()?;
-    // Remember the default handler BY IDENTITY, right after installing it — the engine-side
-    // dispatch (decision 1305) skips it (it reports into the host channel, where every dispatched
-    // message already is) and fires only a handler somebody *chose*: FrameXML's `_ERRORMESSAGE`
-    // or an addon's own.
+    // Kept by identity: dispatch skips the default handler, whose channel already has the
+    // message, and fires only one that FrameXML or an addon set.
     let default: mlua::Function = lua.load("return geterrorhandler()").eval()?;
     lua.set_named_registry_value(super::REG_DEFAULT_ERRORHANDLER, default)?;
     Ok(())
 }
 
-/// The stdlib layer, in Lua. One place, so each alias is the one-liner the task calls for and the
-/// `format` logic is readable. Runs once at construction.
+/// The stdlib layer in Lua, run once at construction.
 const WOW_STDLIB: &str = r#"
 -- ── the bare string family ─────────────────────────────────────────────────────────────────────
 -- Every name here is present in the REAL 1.12 client's global table — the in-world `_G` captured
@@ -446,21 +373,12 @@ do
 end
 "#;
 
-/// `time()` and `date([format [, when]])` — engine globals in the 1.12 client's own `_G`, slots 34
-/// and 33 of its base registry (`0x7035a0` / `0x7033a0`).
+/// `time()` and `date([format [, when]])`: 1.12 engine globals (`0x7035a0`, `0x7033a0`), Lua 5.0's
+/// `os.time`/`os.date` hoisted. `time` is wall-clock epoch seconds, as addons persist it across
+/// sessions.
 ///
-/// They are Lua 5.0's `os.time`/`os.date` hoisted to globals, and we lacked both because the
-/// sandbox strips `os` wholesale. `time` was the top name in the session-start
-/// `attempt to call global` row (6 addons); `date` is a handful more. Every corpus `time()` site is
-/// the same shape — an epoch stamp persisted into SavedVariables and compared across sessions
-/// (`FTC_Save[k].LastCheck = time()`) — so it has to be real wall-clock seconds, not a
-/// session-relative clock like `GetTime`.
-///
-/// **UTC, and that is a stated divergence.** `os.date` uses LOCAL time and this uses UTC, because
-/// resolving a local offset needs a timezone database and this tree has no date dependency at all
-/// (deliberately — the format crates here are all in-repo). The corpus's uses are a debug
-/// timestamp, a "last scanned" string, and `%M:%S` over a DURATION; only the first two shift, and
-/// they shift by a constant. Fixing it means a tz source, not a different algorithm.
+/// Deviation: `date` formats UTC where the reference uses local time, because the tree has no
+/// timezone database.
 fn install_time(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
     g.set(
@@ -470,23 +388,13 @@ fn install_time(lua: &Lua) -> mlua::Result<()> {
     g.set(
         "date",
         lua.create_function(|lua, (fmt, when): (Option<String>, Option<i64>)| {
-            // Bare `date()` is `%c`, as in Lua — `Recap.lua:2690` calls it with no arguments.
+            // Bare `date()` is `%c`, as in Lua.
             let fmt = fmt.unwrap_or_else(|| "%c".to_string());
             let secs = when.unwrap_or_else(crate::civil::unix_seconds);
-            // A leading `!` selects UTC. Every timestamp this engine holds is already UTC — there
-            // is no local-time conversion anywhere here — so the flag only has to be CONSUMED, not
-            // acted on. Left in the format string it would print as a literal `!`.
+            // A leading `!` selects UTC, which every time here already is, so it is only consumed.
             let body = fmt.strip_prefix('!').unwrap_or(&fmt);
-            // `date("*t")` returns a TABLE, not a string, and leaving it unimplemented was not a
-            // missing feature — it was a HANG. `Accountant_WeekStart` walks a day at a time until
-            // the weekday matches its stored `weekstart`:
-            //
-            //     dt = date("*t", ct); thisDay = dt["wday"]
-            //     while thisDay ~= …weekstart do ct = ct - 86400; … end
-            //
-            // Against a string return, `dt["wday"]` is nil, `nil ~= 3` forever, and the addon spins
-            // the client — which is exactly what it did to the survey the moment a separate fix let
-            // Accountant reach this function at all.
+            // `*t` answers a table, as in Lua: an addon that loops until its `wday` matches
+            // (`Accountant_WeekStart`) spins forever on anything else.
             if body == "*t" {
                 let c = crate::civil::from_unix(secs);
                 let t = lua.create_table()?;
@@ -496,12 +404,11 @@ fn install_time(lua: &Lua) -> mlua::Result<()> {
                 t.set("hour", c.hour)?;
                 t.set("min", c.min)?;
                 t.set("sec", c.sec)?;
-                // Lua counts weekdays 1..7 from SUNDAY; ours is the 0-based index into `DAYS`.
+                // Lua counts weekdays 1..7 from Sunday; ours is the 0-based index into `DAYS`.
                 t.set("wday", c.weekday + 1)?;
-                // `yday` is already 1-based out of the conversion, which is Lua's convention too.
+                // Already 1-based, as in Lua.
                 t.set("yday", c.yearday)?;
-                // No timezone and no DST rules here, and `false` is the honest answer rather than
-                // the nil an absent field would give: this clock never observes daylight saving.
+                // UTC has no daylight saving.
                 t.set("isdst", false)?;
                 return Ok(mlua::Value::Table(t));
             }
@@ -537,12 +444,7 @@ const MONTHS: [&str; 12] = [
     "December",
 ];
 
-/// The `strftime` subset the corpus actually uses, plus the obvious neighbours.
-///
-/// Bounded on purpose: the specifiers here are the ones read off real call sites —
-/// `%H:%M:%S` (AceDebug), `%A, %B %d, %Y - %H:%M` (FuBar_PotHerbFu), `%M:%S` (FuBar_AnkhTimerFu),
-/// `%c` (bare `date()`). An unknown specifier is emitted VERBATIM rather than swallowed, so a
-/// format this does not know shows up in the output instead of silently vanishing.
+/// The `strftime` subset addons use; an unknown specifier is emitted verbatim.
 fn format_epoch(secs: i64, fmt: &str) -> String {
     let crate::civil::Civil {
         year,
@@ -598,7 +500,6 @@ fn format_epoch(secs: i64, fmt: &str) -> String {
             'y' => out.push_str(&format!("{:02}", year.rem_euclid(100))),
             'Y' => out.push_str(&format!("{year}")),
             '%' => out.push('%'),
-            // Unknown: verbatim, so it is visible rather than swallowed.
             other => {
                 out.push('%');
                 out.push(other);
@@ -607,15 +508,9 @@ fn format_epoch(secs: i64, fmt: &str) -> String {
     }
     out
 }
-/// `luaO_chunkid` (`0x6f5c40`), the reference's own — because `debugstack`'s frames carry
-/// `short_src`, and **it truncates from the FRONT** (decision 2121).
-///
-/// An `@`-named chunk longer than [`CHUNKID_KEEP`] characters after the `@` becomes `"..."` plus
-/// its LAST [`CHUNKID_KEEP`], so the head of the path is what is lost. That is not a detail: over a
-/// 2189-file vanilla corpus, 60% of addon `.lua` chunk names truncate and **38% lose `\AddOns\`
-/// entirely**, which is exactly the substring three different corpus libraries search for. A client
-/// that keeps the whole name matches at a different frame than the reference for a third of library
-/// frames — silently, and in the addon's favour, which is worse than failing the same way.
+/// `luaO_chunkid` (`0x6f5c40`), for `debugstack`'s `short_src`. An `@` name longer than
+/// [`CHUNKID_KEEP`] keeps only its tail behind `"..."`, so a long addon path loses the `\AddOns\`
+/// that corpus libraries search for.
 fn chunk_id(source: &str) -> String {
     if let Some(rest) = source.strip_prefix('=') {
         // A `=name` chunk is taken verbatim, clipped to the buffer from the front.
@@ -640,24 +535,19 @@ fn chunk_id(source: &str) -> String {
     }
 }
 
-/// `LUA_IDSIZE` — the `short_src` buffer, 60 bytes including the terminator.
+/// `LUA_IDSIZE`: the `short_src` buffer, 60 bytes with the terminator.
 const LUA_IDSIZE: usize = 60;
 
-/// How many characters of an `@`-named chunk survive truncation, tail-first: the reference keeps
-/// the last 52 behind a `"..."` (measured off `0x6f5c40`).
+/// Characters an `@` name keeps, tail-first, behind `"..."` (`0x6f5c40`).
 const CHUNKID_KEEP: usize = 52;
 
 /// What `[string "…"]` costs the budget in the third `luaO_chunkid` arm.
 const STRING_CHUNK_OVERHEAD: usize = 17;
 
-/// One `debugstack` frame, in the reference's own wording (decision 2121):
-/// `short_src ":" [currentline ":"] DESC`, with the `\n` pushed **after** it by the caller.
-///
-/// `DESC` is the `*namewhat` switch at `0x7038fa`: a `f`/`g`/`l`/`m` name renders
-/// `` in function `%s' `` (`0x872c98`) — Lua **5.0**'s backtick quoting, which is what
-/// `AceLibrary.lua:139`'s `"([`<].-['>])"` needs and what 5.4's `'%s'` cannot satisfy — and
-/// otherwise the `*what` arms decide: `m` → `" in main chunk"` (`0x872c88`), `C` or `t` → `" ?"`
-/// (`0x872c6c`), else `" in function <%s:%d>"` (`0x872c70`).
+/// One `debugstack` frame, `short_src ":" [currentline ":"] DESC`, the caller pushing its `\n`.
+/// DESC (`0x7038fa`) is `` in function `%s' `` for a named frame (`0x872c98`), else by `what`:
+/// `" in main chunk"` (`0x872c88`), `" ?"` for C or a tail call (`0x872c6c`), or
+/// `" in function <%s:%d>"` (`0x872c70`).
 fn traceback_frame(d: &mlua::Debug) -> String {
     let src = d.source();
     let names = d.names();
@@ -674,9 +564,8 @@ fn traceback_frame(d: &mlua::Debug) -> String {
         line.push_str(&n.to_string());
         line.push(':');
     }
-    // A tail call has no calling instruction to name it from. 5.0 gave that frame `what == "tail"`
-    // and the `" ?"` arm; 5.4 hands us a `(tail call)` pseudo-frame instead, which lands in the
-    // same arm by the same rule.
+    // A tail call has nothing to name it from and takes the `" ?"` arm, known by its `what` or as
+    // the `(tail call)` pseudo-frame.
     let tail_call = src.what == "t" || short == "(tail call)";
     match names.name.as_deref() {
         Some(name) if !name.is_empty() && !tail_call => {
@@ -697,18 +586,11 @@ fn traceback_frame(d: &mlua::Debug) -> String {
     line
 }
 
-/// `debugstack`'s body — `0x703760`'s walk, which is stock Lua 5.0's `db_errorfb` with its header
-/// and its `"\n\t"` prefix replaced by a `"\n"` pushed **after** each frame (`0x703971`). That one
-/// substitution is the whole difference in shape, and it is why line 1 is a frame and why
-/// `AceDB-2.0`'s skip-one-line lands on its caller (decision 2121).
-///
-/// **`count1` bounds nothing on its own.** The loop formats while the level is `<= start + count1`
-/// (`0x703857` is `jbe`, unsigned ≤), and past that it probes `getstack(level + count2)`: a probe
-/// that FAILS steps back and prints that level as an ordinary frame, so `count1 = 1` returns *two*
-/// frames on a two-deep stack and one frame plus `"...\n"` on a three-deep one. Clamping to
-/// `count1` instead would diverge from the reference at exactly `depth == count1 + 1` — which is
-/// `FuBarPlugin-2.0.lua:752`'s `debugstack(6, 1, 0)`, whose greedy `"\\AddOns\\(.*)\\"` reads the
-/// LAST path in the string.
+/// `debugstack`'s walk (`0x703760`): Lua 5.0's `db_errorfb` without its header, each frame
+/// followed by `"\n"` (`0x703971`) rather than preceded by `"\n\t"`, so line 1 is a frame.
+/// Frames print while the level is `<= start + count1` (`0x703857`, `jbe`); then a failed
+/// `getstack(level + count2)` probe prints that level as an ordinary frame, else `"...\n"` and
+/// the last `count2` follow. So `count1 = 1` gives two frames on a two-deep stack, not one.
 fn traceback_frames(lua: &Lua, start: usize, count1: usize, count2: usize) -> String {
     let mut out = String::new();
     let mut level = start;
@@ -718,7 +600,7 @@ fn traceback_frames(lua: &Lua, start: usize, count1: usize, count2: usize) -> St
         if level > start + count1 && first_part {
             first_part = false;
             if lua.inspect_stack(level + count2, |_| ()).is_none() {
-                level -= 1; // the probe found nothing to elide — print this level after all
+                level -= 1; // nothing to elide: print this level after all
             } else {
                 out.push_str("...\n");
                 while lua.inspect_stack(level + count2, |_| ()).is_some() {
@@ -739,15 +621,12 @@ fn traceback_frames(lua: &Lua, start: usize, count1: usize, count2: usize) -> St
 mod date_table_tests {
     use crate::script::UiScript;
 
-    /// **`date("*t")` returns a TABLE, and the reason this test exists is that its absence HUNG the
-    /// client.** `Accountant_WeekStart` (`Accountant.lua:364-375`) walks backwards a day at a time
-    /// until the weekday matches its stored `weekstart`; with a string return `dt["wday"]` is nil,
-    /// `nil ~= 3` never becomes false, and the loop never ends.
+    /// `Accountant.lua:364-375` steps back a day until `date("*t", ct).wday` matches, which a
+    /// string return never does.
     #[test]
     fn date_star_t_answers_a_table_that_walks_with_its_argument() {
         let s = UiScript::new().unwrap();
-        // 2026-08-12 00:00:00 UTC is a Wednesday. Lua counts wday from SUNDAY = 1, so Wednesday
-        // is 4 — the off-by-one a 0-based weekday index would get wrong.
+        // A Wednesday at 00:00 UTC: wday 4, counting from Sunday = 1.
         let t: i64 = 1_786_492_800;
         assert_eq!(
             s.eval::<(i64, i64, i64, i64, bool)>(&format!(
@@ -756,7 +635,6 @@ mod date_table_tests {
             .unwrap(),
             (2026, 8, 12, 4, false)
         );
-        // hour/min/sec and yday come through too — an addon reading any of them must not get nil.
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(&format!(
                 "local d = date(\"*t\", {t} + 3661) return d.hour, d.min, d.sec, d.yday"
@@ -765,8 +643,7 @@ mod date_table_tests {
             (1, 1, 1, 224)
         );
 
-        // **The loop Accountant actually runs.** Stepping back a day must move `wday`, and the walk
-        // must terminate — this is the hang, expressed as the addon expresses it.
+        // Accountant's loop: one step back from Wednesday reaches Tuesday.
         assert_eq!(
             s.eval::<i64>(&format!(
                 "local ct = {t} local n = 0 \
@@ -778,8 +655,7 @@ mod date_table_tests {
             "Wednesday(4) back to Tuesday(3) is exactly one step; a constant wday would spin"
         );
 
-        // A `!` prefix selects UTC, which every timestamp here already is — it must be CONSUMED
-        // rather than printed, and it works on the table form as well as the string form.
+        // `!` is consumed, in the table form and the string form.
         assert_eq!(
             s.eval::<i64>(&format!("return date(\"!*t\", {t}).wday"))
                 .unwrap(),
@@ -791,7 +667,6 @@ mod date_table_tests {
                 .contains('!'),
             "the UTC flag is consumed, not printed"
         );
-        // …and an ordinary format still answers a string.
         assert_eq!(
             s.eval::<String>(&format!("return date(\"%A\", {t})"))
                 .unwrap(),
diff --git a/crates/benilla-ui/src/script/summon.rs b/crates/benilla-ui/src/script/summon.rs
index 8c6d48bf..b3fe993b 100644
--- a/crates/benilla-ui/src/script/summon.rs
+++ b/crates/benilla-ui/src/script/summon.rs
@@ -1,53 +1,27 @@
-//! The player-summon **Era API surface** (decision 1747) — four globals, one snapshot.
-//!
-//! These are the whole Lua side of being summoned, and they exist because the reference's
-//! `CONFIRM_SUMMON` dialog is written against exactly them (`StaticPopup.lua:1336-1357` +
-//! `UIParent.lua:551-552`): the `CONFIRM_SUMMON` event raises the dialog with **no arguments at
-//! all**, `OnShow` seeds its countdown from [`GetSummonConfirmTimeLeft`], the popup engine's
-//! per-tick text re-reads [`GetSummonConfirmSummoner`] and [`GetSummonConfirmAreaName`], and
-//! `OnAccept` calls [`ConfirmSummon`]. `reference/1.12-globals.tsv` lists all four as
-//! `function`/`engine`, and there is **no fifth**: 1.12 has no `CancelSummon`, because declining
-//! sends no packet.
-//!
-//! **Why the three getters read a pushed snapshot rather than arguments.** The reference keeps the
-//! request in four engine globals — `[0xb4e358]/[0xb4e35c]` the summoner guid, `[0xb4e354]` the
-//! zone id, `[0xb4e350]` the deadline — and each getter resolves *at call time*: the summoner
-//! through the name cache (`DBCache::NameCache::GetRecord 0x55f080`, `""` on a miss), the area
-//! through `AreaTable.dbc` (`""` when the row is missing), the time left as
-//! `(deadline − now) / 1000`. Both resolves need host state this crate does not have, so the app
-//! does them and pushes the answers every frame ([`super::UiScript::set_summon_confirm`]). The
-//! observable is identical, including the one that matters: a summoner whose name has not arrived
-//! yet renders `""` and then fills itself in on a later tick, because the dialog re-reads the
-//! getter every OnUpdate.
-//!
-//! `ConfirmSummon()` takes no arguments and queues only a count, [`super::binder`]'s shape and for
-//! its reason: the app holds the guid that goes on the wire.
+//! The four summon globals the `CONFIRM_SUMMON` dialog calls (`StaticPopup.lua:1336-1357`); 1.12
+//! has no `CancelSummon`, as declining sends nothing. The reference resolves the summoner
+//! (`0xb4e358`), zone (`0xb4e354`) and deadline (`0xb4e350`) at call time; the app pushes the
+//! answers each frame, so a name still in flight reads `""` and fills in on a later tick.
 
 use mlua::Lua;
 
 use super::Model;
 
-/// The `CONFIRM_SUMMON` dialog's three reads, resolved by the app and pushed each frame.
-///
-/// All three are the *reference's* fallbacks when nothing is pending or nothing resolves — two
-/// empty strings and a zero — because every one of its getters pushes a value on every path
-/// (`""` is the shared static `0x882748`; the time-left reader returns 0 for a zeroed deadline).
-/// Nothing here is ever nil, which is what lets the dialog's `format` run unguarded.
+/// The dialog's three reads, never nil: with nothing pending or resolved they are `""`, `""` and
+/// 0, as the reference's getters answer (`0x882748` is its shared `""`).
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct SummonConfirmUiState {
-    /// The summoner's resolved name, or `""` while the name query is still out.
+    /// The summoner's name from the name cache (`0x55f080`), `""` while the query is out.
     pub summoner: String,
     /// The summoner's zone name out of `AreaTable.dbc`, or `""` if the id names no row.
     pub area: String,
-    /// Milliseconds left before the offer expires — `0` when nothing is pending or the window has
-    /// already run out. **Milliseconds, not seconds**, because the reference's truncation to whole
-    /// seconds happens inside the binding (`0x48b660`'s `/1000`), and that is where it happens
-    /// here too: the floor is part of the API's contract, not part of the host's bookkeeping.
+    /// Milliseconds left, 0 when nothing is pending or it ran out; the binding truncates to
+    /// seconds, as `0x48b660` does.
     pub time_left_ms: u32,
 }
 
 impl super::UiScript {
-    /// Push the summon question's three resolved reads (the app's per-frame feed).
+    /// Push the three resolved reads, each frame.
     pub fn set_summon_confirm(&mut self, state: SummonConfirmUiState) {
         let mut model = self.model_mut();
         if model.summon_confirm != state {
@@ -55,19 +29,16 @@ impl super::UiScript {
         }
     }
 
-    /// Drain the `ConfirmSummon()` calls queued since the last drain — each one is a
-    /// `CMSG_SUMMON_RESPONSE`. [`Self::take_binder_confirms`]'s shape, and a count for the same
-    /// reason: the intent has no payload of its own.
+    /// Drain the `ConfirmSummon()` calls, each a `CMSG_SUMMON_RESPONSE`.
     pub fn take_summon_confirms(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().summon_confirms)
     }
 }
 
-/// Register the four summon globals (the style [`super::binder`] registers its two).
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetSummonConfirmSummoner() — who is summoning you (`0x48b6a0`). A string on every path.
+    // `0x48b6a0`: a string on every path.
     g.set(
         "GetSummonConfirmSummoner",
         lua.create_function(|lua, ()| {
@@ -76,9 +47,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSummonConfirmAreaName() — where to (`0x48b720`). The **summoner's** zone, straight out of
-    // `AreaTable.dbc` with no parent walk and no GlobalString tail: unlike the innkeeper question's
-    // three-step chain (`0x5dfe5e`), an id this table cannot name renders as `""`.
+    // `0x48b720`: the summoner's zone straight from `AreaTable.dbc`, with no parent walk and no
+    // GlobalString fallback, unlike the innkeeper question's chain (`0x5dfe5e`).
     g.set(
         "GetSummonConfirmAreaName",
         lua.create_function(|lua, ()| {
@@ -87,10 +57,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSummonConfirmTimeLeft() — whole SECONDS left, truncated (`0x48b660`: the `0x10624dd3`
-    // magic multiply is an integer `/1000` over the millisecond remainder, then `lua_pushnumber`).
-    // The dialog seeds `this.timeleft` from it in OnShow and the popup engine counts down locally
-    // from there, so the floor lands once, at open.
+    // Whole seconds, truncated (`0x48b660`); the dialog reads it once in `OnShow` and counts down
+    // locally from there.
     g.set(
         "GetSummonConfirmTimeLeft",
         lua.create_function(|lua, ()| {
@@ -99,7 +67,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ConfirmSummon() — the CONFIRM_SUMMON dialog's Accept, and the only packet in the whole flow.
+    // The dialog's Accept, the only packet in the flow.
     g.set(
         "ConfirmSummon",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/surface.rs b/crates/benilla-ui/src/script/surface.rs
index 746dfeb8..a6e4ae9f 100644
--- a/crates/benilla-ui/src/script/surface.rs
+++ b/crates/benilla-ui/src/script/surface.rs
@@ -1,36 +1,16 @@
-//! **benilla's widget METHOD surface, asked of a running VM** — the shared measurement behind
-//! the `dump_widget_methods` example and the widget-surface gate
-//! (`script::tests::widget_surface`, decision 2142).
-//!
-//! It exists for the same reason `dump_globals` does (decisions 1188, 1189): **it is a run, not a
-//! grep**. `_G` is not the whole surface an addon can tell apart — most of what an addon touches
-//! is reached through a *widget*, and an addon's test for "does this client have X" is
-//! `if frame.SetBackdrop then`, i.e. what the `__index` chain answers on a live instance. A regex
-//! over `m.set("Name", …)` cannot answer that: it cannot see which registry table a kind actually
-//! chains to, it cannot see the Texture/FontString leaf split ([`super::region`]), and it reads a
-//! name registered under a `format!` family as one method.
-//!
-//! So every row is one live object being asked `type(obj.Name) == "function"`, exactly as an addon
-//! asks it. The only thing **not** asked of the VM is the *candidate name list* — a metatable whose
-//! `__index` is a Rust dispatcher is not enumerable from Lua, so the candidates are the union of
-//! the keys of the VM's own method tables ([`METHOD_TABLES`]), read out of the Lua registry at
-//! runtime rather than out of the source. A key that no longer resolves to a table is a hard error
-//! rather than a silent loss of candidates: a quietly-missing candidate source would under-report
-//! the surface, which is the exact failure this measurement exists to prevent.
+//! benilla's widget method surface asked of a running VM, shared by the `dump_widget_methods`
+//! example and the widget-surface gate (`script::tests::widget_surface`). Each row is a live
+//! instance asked `type(obj.Name) == "function"`, as an addon asks it; only the candidate names
+//! come from elsewhere, the keys of the VM's method tables ([`METHOD_TABLES`]), since a Rust
+//! `__index` dispatcher cannot be enumerated from Lua.
 use std::collections::BTreeSet;
 
 use mlua::{Table, Value};
 
 use super::UiScript;
 
-/// The named-registry method tables the VM installs — the **candidate name source**, read from the
-/// live registry.
-///
-/// This is not the class chain (the chain is `object::kind_method_registries`' business and this
-/// instrument deliberately does not model it — it asks the instance instead). It is only the
-/// universe of names worth probing: every name benilla registers on any widget appears as a key in
-/// one of these, so the union is a superset of our surface and the per-instance probe decides
-/// membership.
+/// The VM's named-registry method tables: every widget method benilla registers is a key in one,
+/// and the per-instance probe decides which a class answers.
 const METHOD_TABLES: &[&str] = &[
     "__benilla_frame_methods",
     "__benilla_region_methods",
@@ -57,14 +37,9 @@ const METHOD_TABLES: &[&str] = &[
     "__benilla_tooltip_methods",
 ];
 
-/// Every widget/region/font class benilla can hand an addon, and one Lua expression that makes one.
-///
-/// **Ordered, and the order is load-bearing**: the region and font rows are made *by* the plain
-/// frame the first row creates, so `Frame` comes first. Each instance is published as the global
-/// `DW_<Class>`; the frame kinds also publish their own `CreateFrame` name, which is harmless.
-///
-/// `TaxiRouteFrame` is absent on purpose — it is a registered `CreateFrame` type that *is* a
-/// `Frame` and nothing else (decision 1828), so it would be the `Frame` row twice.
+/// Every class benilla can hand an addon, with a Lua expression making one, published as
+/// `DW_<Class>`. `Frame` must come first: the region and font rows are made by it.
+/// `TaxiRouteFrame` is left out, being a plain `Frame` to Lua.
 const CLASSES: &[(&str, &str)] = &[
     ("Frame", r#"CreateFrame("Frame", "DWFrameN", UIParent)"#),
     (
@@ -137,12 +112,8 @@ const CLASSES: &[(&str, &str)] = &[
     ("Font", r#"CreateFont("DWFontN")"#),
 ];
 
-/// Every `(class, method)` pair this VM answers — one live instance per class, probed with the
-/// membership test an addon writes.
-///
-/// **A class that cannot be instantiated is REPORTED, never skipped**: its row is
-/// `(class, "!NOT-INSTANTIABLE")`. A census that silently drops a class reads as "that class has
-/// no methods", which is the wrong answer to a different question.
+/// Every `(class, method)` pair this VM answers, one live instance per class. A class that cannot
+/// be made reports `(class, "!NOT-INSTANTIABLE")` rather than dropping out.
 pub fn widget_method_census(script: &UiScript) -> mlua::Result<Vec<(String, String)>> {
     let mut candidates: BTreeSet<String> = BTreeSet::new();
     for key in METHOD_TABLES {
diff --git a/crates/benilla-ui/src/script/tabard.rs b/crates/benilla-ui/src/script/tabard.rs
index ed3c8b3e..9c9a3116 100644
--- a/crates/benilla-ui/src/script/tabard.rs
+++ b/crates/benilla-ui/src/script/tabard.rs
@@ -1,22 +1,7 @@
-//! The guild tabard designer's engine surface (decision 1977): the `TabardModel` kind's own method
-//! table (`0x84ee40`, ten verbs) and the window's two globals.
-//!
-//! **The designer's whole state is five ints on the frame** — emblem style, emblem colour,
-//! border style, border colour, background colour — bounded by a `.rdata` constant table
-//! (`0x808220`: 170 · 17 · 6 · 17 · 51) that no DBC feeds. A `TabardModel` is well-defined only
-//! once `InitializeTabardColors()` has run: the constructor writes nothing.
-//!
-//! **What is the app's.** The guild record the seed reads and the save-in-flight latch
-//! `CanSaveTabardNow` tests are pushed by the app ([`TabardHost`]); `Save()` and
-//! `CloseTabardCreation()` queue [`TabardIntent`]s the app drains — the fourteen pre-flight checks
-//! of the save (`0x5e03f0`) need the purse, the guild rank and the interaction target, none of
-//! which this crate holds. The two `…EmblemTexture(texture)` methods are **setters**: the reference
-//! decodes the emblem BLP and installs a white-carrying-its-alpha 128×64 / 128×32 texture into the
-//! passed Texture widget. Here they set the region's texture to an [`EMBLEM_MASK_TOKEN`] path the
-//! app resolves to exactly that image (`ui_script::extract`).
-//!
-//! `GetTabardCreationCost()` is a **hard-coded constant**: `0x6d6de0` is `mov eax,0x186a0; ret`
-//! — 100 000 copper, ten gold, no `.data` cell and no server input.
+//! The guild tabard designer: the `TabardModel` method table (`0x84ee40`) and the window's two
+//! globals. Its state is five ints on the frame, which the constructor leaves unwritten until
+//! `InitializeTabardColors()` seeds them; the app pushes the guild record and save latch and runs
+//! the save's fourteen checks (`0x5e03f0`).
 
 use mlua::{Lua, Value};
 
@@ -26,21 +11,18 @@ use super::region::region_handle_of;
 use super::Model;
 use crate::widget::{FrameHandle, FrameKind, RegionKind};
 
-/// Registry key of the TabardModel method table — probed before PlayerModel's and Model's
-/// (`object.rs`'s kind chain).
+/// Registry key of the TabardModel method table, probed before PlayerModel's and Model's.
 pub(super) const REG_TABARDMODEL_METHODS: &str = "__benilla_tabardmodel_methods";
 
-/// `0x6d6de0`: the designer's price, in copper.
+/// The designer's price in copper, a constant in the reference (`0x6d6de0`).
 pub const TABARD_CREATION_COST: u32 = 100_000;
 
-/// `0x808220`, the five slot counts in `CycleVariation` order: emblem style, emblem colour, border
-/// style, border colour, background colour. A constant — the client consults no DBC.
+/// The five slot counts in `CycleVariation` order (emblem style and colour, border style and
+/// colour, background colour): the reference's constant table at `0x808220`, not a DBC.
 pub const TABARD_COUNTS: [i32; 5] = [170, 17, 6, 17, 51];
 
-/// The token a Texture region carries after `Get{Upper,Lower}EmblemTexture(texture)`: the prefix
-/// plus the emblem path (`Textures\GuildEmblems\Emblem_%02d_%02d_T{U,L}_U`). The app draws
-/// it as the reference's generated image — white RGB carrying the emblem's own alpha, a tintable
-/// mask (`0x503431`: `(a << 24) | 0x00FFFFFF`).
+/// The prefix a Texture carries before the emblem path after `Get{Upper,Lower}EmblemTexture`; the
+/// app draws the reference's generated mask, white carrying the emblem's alpha (`0x503431`).
 pub const EMBLEM_MASK_TOKEN: &str = "benilla:emblem-mask:";
 
 /// The BLP path inside an [`EMBLEM_MASK_TOKEN`] texture, or `None` for an ordinary path.
@@ -48,21 +30,19 @@ pub fn emblem_mask_path(texture: &str) -> Option<&str> {
     texture.strip_prefix(EMBLEM_MASK_TOKEN)
 }
 
-/// What the app pushes for the designer's two host-side facts.
+/// The designer's two host-side facts, pushed by the app.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
 pub struct TabardHost {
-    /// The local player's guild record as the DBCache holds it — `Some` once cached (its five
-    /// emblem fields, `-1` each for an undesigned tabard), `None` while it has not arrived or the
-    /// player has no guild.
+    /// The cached guild record's emblem fields, `-1` each when undesigned; `None` until cached.
     pub guild_record: Option<[i32; 5]>,
-    /// `[0xc4d780]`, the save-in-flight latch: set when the save is sent, cleared by the reply.
+    /// The save-in-flight latch (`0xc4d780`): set when the save is sent, cleared by the reply.
     pub save_pending: bool,
 }
 
 /// What the designer asks the app to do.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum TabardIntent {
-    /// `TabardModel:Save()` — the five values, for the fourteen pre-flight checks and the send.
+    /// `Save()`: the five values, for the checks and the send.
     Save([i32; 5]),
     /// `CloseTabardCreation()`.
     Close,
@@ -74,8 +54,7 @@ impl super::UiScript {
         self.model_mut().tabard_host = host;
     }
 
-    /// The designer's current five values — the preview the app dresses the player's body in
-    /// while the frame is up — or `None` before `InitializeTabardColors()` has seeded them.
+    /// The design the app previews on the player's body, `None` before the seed.
     pub fn tabard_design(&self) -> Option<[i32; 5]> {
         self.model_ref().tabard_preview
     }
@@ -86,8 +65,7 @@ impl super::UiScript {
     }
 }
 
-/// The three `this` raises every method shares (`0x847ef8` / `0x847ec0` / `0x847e98`), then the
-/// frame handle of a `TabardModel`.
+/// The three `this` raises every method shares (`0x847ef8`, `0x847ec0`, `0x847e98`).
 fn this_tabard(lua: &Lua, this: &Value) -> mlua::Result<FrameHandle> {
     let Value::Table(t) = this else {
         return Err(mlua::Error::runtime(
@@ -113,9 +91,8 @@ fn this_tabard(lua: &Lua, this: &Value) -> mlua::Result<FrameHandle> {
     Ok(h)
 }
 
-/// The five values of a designer that has been seeded, else nothing — the file-name getters and
-/// the texture setters read the raw fields, which the reference leaves uninitialised before the
-/// seed; here an unseeded designer reads as all zeros, the first legal design.
+/// The seeded design, or all zeros. Deviation: the reference reads uninitialised fields before
+/// the seed; we answer the first legal design because that value is undefined.
 fn design(model: &Model, h: FrameHandle) -> [i32; 5] {
     model.tabard_designs.get(&h).copied().unwrap_or([0; 5])
 }
@@ -126,12 +103,12 @@ fn store(lua: &Lua, h: FrameHandle, five: [i32; 5]) {
     model.tabard_preview = Some(five);
 }
 
-/// `0x455c70`: `(count · rand) >> 32` — a draw in `[0, count)` (INFERRED uniform, VERIFIED scaling).
+/// `(count * rand) >> 32`, a draw in `[0, count)` (`0x455c70`).
 fn draw(rand: u32, count: i32) -> i32 {
     ((u64::from(count as u32) * u64::from(rand)) >> 32) as i32
 }
 
-/// A clock-seeded generator standing in for the client's table-driven one (`0x4531e0`); only the
+/// A clock-seeded generator in place of the reference's table-driven one (`0x4531e0`); only the
 /// range law above is the reference's.
 fn random_words() -> impl Iterator<Item = u32> {
     let nanos = std::time::SystemTime::now()
@@ -147,8 +124,8 @@ fn random_words() -> impl Iterator<Item = u32> {
     })
 }
 
-/// `InitializeTabardColors()`'s worker `0x5028e0`: the guild record's five when the record is
-/// cached and none is `-1`, else five random draws — never zeros.
+/// `InitializeTabardColors()`'s worker (`0x5028e0`): the cached guild record unless a field is
+/// `-1`, else five random draws.
 fn seed(host: TabardHost) -> [i32; 5] {
     match host.guild_record {
         Some(rec) if rec.iter().all(|v| *v != -1) => rec,
@@ -159,8 +136,8 @@ fn seed(host: TabardHost) -> [i32; 5] {
     }
 }
 
-/// `0x502ac0`: `v ← (v + count + delta) mod count`, a signed `idiv`; `|delta| ≥ count` is a silent
-/// no-op (no repaint either). Returns whether anything changed.
+/// `(v + count + delta) mod count`, a signed `idiv` (`0x502ac0`); `|delta| >= count` is a silent
+/// no-op, with no repaint.
 fn cycle(five: &mut [i32; 5], slot: usize, delta: i32) -> bool {
     let count = TABARD_COUNTS[slot];
     if delta.wrapping_abs() >= count {
@@ -170,9 +147,8 @@ fn cycle(five: &mut [i32; 5], slot: usize, delta: i32) -> bool {
     true
 }
 
-/// The emblem path for a half (`TU` upper, `TL` lower) — `0x47a520`'s format. The reference's
-/// setters append `.BLP` before decoding (`0x503396`); here the path stays extensionless, the
-/// form every region texture carries and the app's resolver completes.
+/// The emblem path for a half (`TU` upper, `TL` lower) in `0x47a520`'s format, left without the
+/// `.BLP` the reference appends (`0x503396`), as every region texture path is.
 fn emblem_path(five: [i32; 5], half: &str) -> String {
     format!(
         "Textures\\GuildEmblems\\Emblem_{:02}_{:02}_{half}_U",
@@ -180,8 +156,8 @@ fn emblem_path(five: [i32; 5], half: &str) -> String {
     )
 }
 
-/// `Get{Upper,Lower}EmblemTexture(texture)` — the Texture-widget argument's three raises
-/// (`0x84efc8` / `0x84f050` / `0x84f010` and the lower twins), then the install.
+/// `Get{Upper,Lower}EmblemTexture(texture)`: the argument's three raises (`0x84efc8`,
+/// `0x84f050`, `0x84f010` for the upper), then the install.
 fn emblem_texture(lua: &Lua, this: Value, texture: Value, upper: bool) -> mlua::Result<()> {
     let h = this_tabard(lua, &this)?;
     let (name, half) = if upper {
@@ -225,7 +201,7 @@ fn emblem_texture(lua: &Lua, this: Value, texture: Value, upper: bool) -> mlua::
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let m = lua.create_table()?;
 
-    // `InitializeTabardColors()` — `0x502b10`: the active player gates the seed; zero returns.
+    // `0x502b10`: the seed needs an active player.
     m.set(
         "InitializeTabardColors",
         lua.create_function(|lua, this: Value| {
@@ -242,7 +218,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `Save()` — `0x502bd0`: the intent carries the five; the app does the fourteen checks.
+    // `0x502bd0`: the app runs the fourteen checks on the queued five.
     m.set(
         "Save",
         lua.create_function(|lua, this: Value| {
@@ -257,9 +233,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `CycleVariation(variationIndex, delta)` — `0x502ca0`: both args `lua_isnumber` else the
-    // usage raise; the index 1..5 (unsigned-checked, so 0 is out) else its own raise; both
-    // `ftol`-truncated; the worker's silent no-op for a delta past the count.
+    // `0x502ca0`: a non-number raises the usage, an index off 1..=5 its own error; both truncate.
     m.set(
         "CycleVariation",
         lua.create_function(|lua, (this, index, delta): (Value, Value, Value)| {
@@ -283,8 +257,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The four `…FileName` getters (`0x502dc0` / `0x502ea0` / `0x502f80` / `0x503070`): one
-    // string each, no extension — the loader appends `.blp`.
+    // `0x502dc0`, `0x502ea0`, `0x502f80`, `0x503070`: one string each, without `.blp`.
     for (name, upper, background) in [
         ("GetUpperBackgroundFileName", true, true),
         ("GetLowerBackgroundFileName", false, true),
@@ -312,7 +285,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // The two texture SETTERS (`0x503160` / `0x503540`), zero returns.
+    // Setters despite their names (`0x503160`, `0x503540`): the reference installs a 128x64 or
+    // 128x32 mask into the passed texture.
     m.set(
         "GetUpperEmblemTexture",
         lua.create_function(|lua, (this, texture): (Value, Value)| {
@@ -326,8 +300,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `CanSaveTabardNow()` — `0x503910` never resolves `this`: the number 1, or nil, from
-    // `player && guildRecordCached && !savePending` (`0x5f0800`). Not a would-it-succeed test.
+    // `0x503910` never resolves `this`: the number 1 or nil, from a player, a cached record and
+    // no save pending (`0x5f0800`), not a would-it-succeed test.
     m.set(
         "CanSaveTabardNow",
         lua.create_function(|lua, _: mlua::MultiValue| {
@@ -342,13 +316,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     lua.set_named_registry_value(REG_TABARDMODEL_METHODS, m)?;
 
     let g = lua.globals();
-    // `GetTabardCreationCost()` — 0 args, one number, the constant.
     g.set(
         "GetTabardCreationCost",
         lua.create_function(|_, ()| Ok(i64::from(TABARD_CREATION_COST)))?,
     )?;
-    // `CloseTabardCreation()` — `0x4f5900`: zero args, zero returns, no packet; the close core
-    // (`0x4f58a0`) and its `CLOSE_TABARD_FRAME` are the app's, gated on a stored vendor.
+    // `0x4f5900`, no packet: the app runs the close (`0x4f58a0`) and its `CLOSE_TABARD_FRAME`,
+    // gated on a stored vendor.
     g.set(
         "CloseTabardCreation",
         lua.create_function(|lua, _: mlua::MultiValue| {
diff --git a/crates/benilla-ui/src/script/talent.rs b/crates/benilla-ui/src/script/talent.rs
index 732e8f73..0d3f3038 100644
--- a/crates/benilla-ui/src/script/talent.rs
+++ b/crates/benilla-ui/src/script/talent.rs
@@ -1,126 +1,98 @@
-//! The talent window's engine seam (decision 0304) — the same two-way shape as
-//! [`super::spellbook`]: the app pushes a **talent snapshot** ([`UiScript::set_talents`] — the
-//! class's tabs + each tab's talents, already resolved to name/icon/rank/availability by the
-//! app's `Talent.dbc` × `Spell.dbc` join), the Era bindings below read it verbatim, and
-//! `LearnTalent(tab, index)` queues outbound intents the app drains
-//! ([`UiScript::take_talent_learns`]) into `CMSG_LEARN_TALENT`. The engine holds no talent
-//! KNOWLEDGE — grid seats, ranks, prerequisites, and availability are the app's resolve.
+//! The talent bindings: the app pushes the class's pages and talents, resolved from `Talent.dbc`
+//! and `Spell.dbc` ([`UiScript::set_talents`]), and `LearnTalent(tab, index)` queues clicks for
+//! `CMSG_LEARN_TALENT`. Grid seats, ranks, prerequisites and availability are the app's.
 //!
-//! The **respec** pair rides here too (decision 1580) and is the binder question's twin, not a
-//! talent-window affordance: `ConfirmTalentWipe()` answers a class trainer's
-//! `CONFIRM_TALENT_WIPE`, and `CheckTalentMasterDist()` is the range poll that takes the dialog
-//! away when you walk off. Both are 1.12 engine bindings (`reference/1.12-globals.tsv`), and
-//! neither reads the snapshot above — the question arrives as the event's argument.
+//! The tuples are what `Blizzard_TalentUI.lua` reads (`:154`, `:180`): `GetTalentTabInfo(i)` gives
+//! name, texture, pointsSpent, fileName; `GetTalentInfo(tab, i)` name, icon, tier, column, rank,
+//! maxRank, isExceptional, meetsPrereq. Tiers and columns are 1-based, as the stock frame indexes
+//! `TALENT_BRANCH_ARRAY[tier][column]`. The respec pair answers a class trainer's
+//! `CONFIRM_TALENT_WIPE` and reads no snapshot.
 //!
-//! The Era tuple shapes are the 1.12 addon's own reads (`Blizzard_TalentUI.lua`, extracted from
-//! the patch chain — decision 0304's pin §3):
-//! `GetTalentTabInfo(i) → name, texture, pointsSpent, fileName`;
-//! `GetTalentInfo(tab, i) → name, icon, tier, column, rank, maxRank, isExceptional, meetsPrereq`;
-//! `GetTalentPrereqs(tab, i) → tier, column, isLearnable, …` (flat triplets);
-//! `UnitCharacterPoints(unit) → cp1, cp2`. Tiers/columns are **1-based** Lua-facing (the
-//! reference indexes `TALENT_BRANCH_ARRAY[tier][column]` directly) — the app pushes them
-//! 1-based; `isExceptional` is pushed but unused by the reference frame's own render.
-//!
-//! ## The tooltip (`GameTooltip:SetTalent(tab, index)`)
-//!
-//! The 1.12 talent tooltip IS the spell builder `0x52e610` with the talent params: line 2
-//! `TOOLTIP_TALENT_RANK 0x854a2c` "Rank %d/%d" white iff `param7≠0 && param8==0`; line 13
-//! `TOOLTIP_TALENT_LEARN 0x8549f8` "Click to learn" green on a learnable higher rank — so
-//! `SetTalent` renders THROUGH the spell channel: the talent's display-rank
-//! spell view comes from the same ask-once store `SetSpell` uses (a miss queues the id for the
-//! app's resolver), interleaved with the talent lines ([`TalentLines`]). The red requirement
-//! lines' position (here: after the rank line) is CONFIRMED — decision 0305's residue: it
-//! matches the builder law. Still open: the "Next rank:" block's composition (here:
-//! `TOOLTIP_TALENT_NEXT_RANK` white + the next rank spell's description gold — its view from the
-//! same store) — 0305 didn't walk it.
+//! `GameTooltip:SetTalent` is the spell builder (`0x52e610`) with talent lines: the rank line
+//! (`TOOLTIP_TALENT_RANK`, `0x854a2c`), the red requirement lines after it, and "Click to learn"
+//! (`TOOLTIP_TALENT_LEARN`, `0x8549f8`) in green on a learnable rank. The "Next rank:" block,
+//! `TOOLTIP_TALENT_NEXT_RANK` in white and the next rank's description in gold, is untraced in
+//! the reference.
 
 use mlua::{Lua, MultiValue, Table, Value};
 
 use super::tooltip_spell::{spell_view_of, TalentLines};
 use super::Model;
 
-/// One talent page (`TalentTab.dbc` row, app-resolved) — `GetTalentTabInfo`'s source.
+/// One talent page, a `TalentTab.dbc` row: `GetTalentTabInfo`'s source.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TalentTabView {
     pub name: String,
-    /// The `Interface\TalentFrame\<base>-` art base (`fileName` in the Era tuple).
+    /// The `Interface\TalentFrame\<base>-` art base, the tuple's `fileName`.
     pub background: String,
-    /// Points spent across this page's talents (the app's sum of ranks).
     pub points_spent: u32,
 }
 
-/// One prerequisite edge for the branch drawing — `GetTalentPrereqs`' triplet.
+/// One prerequisite edge, a `GetTalentPrereqs` triplet.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub struct TalentPrereqView {
-    /// 1-based, Lua-facing (module doc).
     pub tier: u32,
     pub column: u32,
-    /// The prereq is learned to its required rank (drives arrow color + availability).
+    /// The prerequisite is learned to its required rank.
     pub learnable: bool,
 }
 
-/// One talent button's full render state — `GetTalentInfo`'s source plus the tooltip context.
+/// One talent button: `GetTalentInfo`'s source and the tooltip's context.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TalentView {
     pub name: String,
     pub texture: Option<String>,
-    /// 1-based, Lua-facing (module doc).
     pub tier: u32,
     pub column: u32,
-    /// Current rank (0 = unlearned) / the talent's own rank count.
+    /// Current rank, 0 when unlearned.
     pub rank: u32,
     pub max_rank: u32,
-    /// `Talent.dbc` flags bit 0 — the Era tuple's `isExceptional` (byte-verified
-    /// `TalentRec+0x4c` bit0; the reference frame reads and ignores it).
+    /// `Talent.dbc` flags bit 0 (`TalentRec+0x4c`), the tuple's `isExceptional`; the stock frame
+    /// ignores it.
     pub exceptional: bool,
-    /// The non-prereq requirements hold — the required-spell known-check only, prereqs live in
-    /// the triplets (decision 0305: `meetsPrereq`'s derivation, confirmed as built).
+    /// The required spell is known; prerequisite talents live in the triplets.
     pub meets_prereq: bool,
     pub prereqs: Vec<TalentPrereqView>,
-    /// The tooltip's spell part: the display rank's spell id (rank max(1, rank)) — its view
-    /// rides the spell channel's ask-once store.
+    /// The spell id of rank `max(1, rank)`, the tooltip's spell part.
     pub display_spell: u32,
-    /// The next rank's spell id when `0 < rank < max_rank` (the "Next rank:" block); 0 = none.
+    /// The next rank's spell id when `0 < rank < max_rank`, else 0.
     pub next_spell: u32,
-    /// App-composed red requirement lines (`TOOLTIP_TALENT_TIER_POINTS`/`_PREREQ[_P1]`), shown
-    /// while the talent is locked.
+    /// Red requirement lines (`TOOLTIP_TALENT_TIER_POINTS`, `TOOLTIP_TALENT_PREREQ`), shown while
+    /// the talent is locked.
     pub req_lines: Vec<String>,
-    /// The green `TOOLTIP_TALENT_LEARN` hint: a learnable higher rank (tier unlocked, prereqs
-    /// met, points available) — the same gate the frame's green border wears.
+    /// A higher rank is learnable now: the green `TOOLTIP_TALENT_LEARN` line and border.
     pub learnable: bool,
 }
 
-/// The pushed snapshot: the player's own pages + unspent points.
+/// The pushed snapshot: the player's own pages and unspent points.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TalentUiState {
     pub tabs: Vec<TalentTabView>,
-    /// `talents[t]` = tab `t+1`'s talents, in the enumeration order the app pinned.
+    /// `talents[t]` holds tab `t+1`'s talents, in the app's enumeration order.
     pub talents: Vec<Vec<TalentView>>,
-    /// `UnitCharacterPoints("player")`: (unspent talent points, free primary professions).
+    /// `UnitCharacterPoints("player")`: unspent talent points, free primary professions.
     pub points: (u32, u32),
 }
 
 impl super::UiScript {
-    /// Push the whole talent snapshot (the app's feed on SPELLS_CHANGED/points change).
+    /// Push the whole talent snapshot.
     pub fn set_talents(&mut self, state: TalentUiState) {
         self.model_mut().talents = state;
     }
 
-    /// Drain the queued `LearnTalent(tab, index)` clicks (both 1-based, as the Lua passed them).
+    /// Drain the queued `LearnTalent(tab, index)` clicks, both 1-based.
     pub fn take_talent_learns(&mut self) -> Vec<(u32, u32)> {
         std::mem::take(&mut self.model_mut().talent_learns)
     }
 
-    /// Drain the `ConfirmTalentWipe()` calls queued since the last drain — each one is an outbound
-    /// `MSG_TALENT_WIPE_CONFIRM` ([`Self::take_binder_confirms`]'s shape, and a count for the same
-    /// reason: the app holds the trainer's guid).
+    /// Drain the count of `ConfirmTalentWipe()` calls, each an outbound `MSG_TALENT_WIPE_CONFIRM`;
+    /// a count, since the app holds the trainer's guid.
     pub fn take_talent_wipe_confirms(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().talent_wipe_confirms)
     }
 
-    /// Push whether a trainer's respec question is live and still in range — the host's half of
-    /// `CheckTalentMasterDist()`. Idempotent; `false` covers both "no question pending" and "you
-    /// walked away", which is all the dialog's OnUpdate needs in order to decide to hide.
+    /// Push whether a trainer's respec question is live and in range, which
+    /// `CheckTalentMasterDist()` answers; false for none pending or walked away.
     pub fn set_talent_master_pending(&mut self, pending: bool) {
         let mut model = self.model_mut();
         if model.talent_master_pending != pending {
@@ -129,7 +101,7 @@ impl super::UiScript {
     }
 }
 
-/// Look up one talent by the Lua-facing (tab, index) pair (both 1-based).
+/// One talent by its 1-based (tab, index).
 fn talent_at(model: &Model, tab: usize, index: usize) -> Option<&TalentView> {
     model
         .talents
@@ -150,8 +122,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTalentTabInfo(i) -> name, texture, pointsSpent, fileName. `texture` is nil — the
-    // reference frame never reads it (module doc); out of range -> a single nil.
+    // `texture` is nil: the stock frame never reads it. Out of range answers a single nil.
     g.set(
         "GetTalentTabInfo",
         lua.create_function(|lua, i: usize| {
@@ -180,8 +151,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTalentInfo(tab, i) -> name, icon, tier, column, rank, maxRank, isExceptional,
-    // meetsPrereq. `isExceptional` is 0 (pushed nowhere; the reference render ignores it).
     g.set(
         "GetTalentInfo",
         lua.create_function(|lua, (tab, i): (usize, usize)| {
@@ -206,8 +175,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTalentPrereqs(tab, i) -> tier, column, isLearnable per prerequisite, flattened (the
-    // reference walks `for i=5, arg.n, 3`); none -> empty.
+    // Flat (tier, column, isLearnable) triplets, as `Blizzard_TalentUI.lua:385` walks them.
     g.set(
         "GetTalentPrereqs",
         lua.create_function(|lua, (tab, i): (usize, usize)| {
@@ -224,9 +192,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // LearnTalent(tab, i): queue the click for the app's wire drain. The availability gate is
-    // the app's at send time (mirroring its own pushed `learnable`) — the server re-validates
-    // regardless (vmangos Player::LearnTalent).
+    // The app gates the send on its own `learnable`; the server re-validates
+    // (vmangos `Player::LearnTalent`).
     g.set(
         "LearnTalent",
         lua.create_function(|lua, (tab, i): (u32, u32)| {
@@ -236,10 +203,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ConfirmTalentWipe() — the CONFIRM_TALENT_WIPE dialog's Accept, and the one call in the
-    // client that unlearns talents: the trainer's question changed nothing (decision 1580).
-    // Zero-arg because the guid it sends is one the client latched from that question — the
-    // reference's own `0xc4d7a0`; here the app holds it.
+    // ConfirmTalentWipe(): the `CONFIRM_TALENT_WIPE` Accept, the one call that unlearns talents.
+    // No argument: the reference sends the trainer guid it latched (`0xc4d7a0`); the app holds it.
     g.set(
         "ConfirmTalentWipe",
         lua.create_function(|lua, ()| {
@@ -249,10 +214,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CheckTalentMasterDist() — polled from that dialog's OnUpdate; false hides it. The reference
-    // re-runs its interact-range test against the latched trainer (`0x5df980`, the same
-    // `d² <= [0xc4c28c]` gate `CheckBinderDist` runs), so walking away takes the question off
-    // screen with no packet either way.
+    // CheckTalentMasterDist(): polled by that dialog's OnUpdate, false hides it. The reference
+    // re-runs its interact-range test on the latched trainer (`0x5df980`, `d² <= [0xc4c28c]`);
+    // no packet either way.
     g.set(
         "CheckTalentMasterDist",
         lua.create_function(|lua, ()| {
@@ -261,9 +225,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitCharacterPoints(unit) -> cp1 (unspent talent points), cp2 (free professions). The
-    // pair is our own player's (PLAYER_CHARACTER_POINTS1/2 are PRIVATE fields) — any other
-    // unit token answers the same store, matching the fields only we ever receive.
+    // Every unit token answers the player's own pair: `PLAYER_CHARACTER_POINTS1/2` are private
+    // fields only we receive.
     g.set(
         "UnitCharacterPoints",
         lua.create_function(|lua, _unit: String| {
@@ -276,8 +239,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Register `GameTooltip:SetTalent(tab, index)` into the tooltip kind method table (module doc:
-/// the spell builder with talent lines).
+/// Register `GameTooltip:SetTalent(tab, index)` into the tooltip method table.
 pub(super) fn install_tooltip_method(lua: &Lua, m: &Table) -> mlua::Result<()> {
     m.set(
         "SetTalent",
@@ -287,8 +249,7 @@ pub(super) fn install_tooltip_method(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 let Some(t) = talent_at(&model, tab, i) else {
                     return Ok(());
                 };
-                // The "Next rank:" block needs the next rank's description — from the same
-                // ask-once spell store (a miss shows the block on the hover's re-enter).
+                // From the ask-once spell store; a miss shows on the next hover.
                 let next_desc = (t.next_spell != 0)
                     .then(|| {
                         model
@@ -297,9 +258,8 @@ pub(super) fn install_tooltip_method(lua: &Lua, m: &Table) -> mlua::Result<()> {
                             .map(|v| v.description.clone())
                     })
                     .flatten();
-                // `TOOLTIP_TALENT_RANK` = "Rank %d/%d" (`0x854a2c`, pushed at `0x52b213`) —
-                // the key, filled with the two counts, never a sentence of ours (decision 2045).
-                // An install whose string table lacks it shows no rank line at all.
+                // `TOOLTIP_TALENT_RANK`, "Rank %d/%d" (`0x854a2c`, pushed at `0x52b213`); an
+                // install without it shows no rank line.
                 let rank_line = crate::strings::global(lua, "TOOLTIP_TALENT_RANK").map(|tmpl| {
                     crate::strings::fill(
                         &tmpl,
@@ -326,9 +286,7 @@ pub(super) fn install_tooltip_method(lua: &Lua, m: &Table) -> mlua::Result<()> {
     Ok(())
 }
 
-/// The spell-store ask for the next-rank description (kept beside [`install_tooltip_method`] so
-/// the ask-once discipline stays in one place): a `SetTalent` render whose next-rank view is
-/// missing queues it exactly like a primary-view miss.
+/// Ask the spell store for the next rank's description; a miss queues it as a primary view's does.
 pub(super) fn ask_next_rank(lua: &Lua, next_spell: u32) {
     if next_spell != 0 {
         let _ = spell_view_of(lua, next_spell); // a miss records the ask as a side effect
diff --git a/crates/benilla-ui/src/script/taxi.rs b/crates/benilla-ui/src/script/taxi.rs
index da64dd32..32f5b55a 100644
--- a/crates/benilla-ui/src/script/taxi.rs
+++ b/crates/benilla-ui/src/script/taxi.rs
@@ -1,52 +1,28 @@
-//! The taxi-map bindings (decision 0484) — the Era-shaped flight-master surface driving a faithful
-//! port of the real 1.12 `TaxiFrame` (extracted from the patch chain:
-//! `Interface\FrameXML\TaxiFrame.{xml,lua}`). Same two-way seam as [`super::trainer`]: the app
-//! pushes a **taxi snapshot** ([`UiScript::set_taxi`] — the known-node mask, DBC positions, route
-//! and cost computation already resolved app-side to a flat node list), and the Lua
-//! `TakeTaxiNode`/`CloseTaxiMap` calls queue outbound **intents** the app drains
-//! ([`UiScript::take_taxi_node`] / [`UiScript::take_taxi_close`]). The engine holds no taxi
-//! knowledge — a node is name/type/position/cost/route-segments, all app-resolved.
-//!
-//! ## The Era API shape (matched to the real `TaxiFrame.lua`)
-//!
-//! The reference window's `.lua` runs verbatim on these bindings: `NumTaxiNodes`,
-//! `TaxiNodeGetType(i) → "CURRENT"/"REACHABLE"/"DISTANT"/"NONE"`, `TaxiNodePosition(i) → x, y`
-//! (normalized 0..1, **BOTTOMLEFT** origin — the Lua multiplies by the 316×352 map size and anchors
-//! from the map's BOTTOMLEFT), `TaxiNodeName(i)`, `TaxiNodeCost(i)` (copper),
-//! `GetNumRoutes(i)` + `TaxiGetSrcX/Y(i, hop)`/`TaxiGetDestX/Y(i, hop)` (the hover route's
-//! per-hop segment endpoints, same normalized space), `TakeTaxiNode(i)`, `CloseTaxiMap()`,
-//! `SetTaxiMap(texture)` (assigns the continent art onto the given Texture region),
-//! `TaxiNodeSetCurrent(i)` (a no-op here: the real client computes the hovered node's route arrays
-//! behind it; the app precomputes every node's route, so there is nothing to arm), and
-//! `UnitOnTaxi(unit)`. Indices are 1-based into the pushed node list.
-//!
-//! Node classification, projection, and the route metric are the app's job — and are INTERIM
-//! behind decision 0484's in-flight §5 (I1/I2); this seam only carries the results.
+//! The taxi-map bindings the stock `TaxiFrame.lua` runs on, over a node list the app resolves
+//! and pushes (types, positions, fares and routes); `TakeTaxiNode` and `CloseTaxiMap` queue
+//! intents the app drains. Positions are normalized 0..1 from the map's bottom-left, which the Lua
+//! scales by the 316x352 map.
 
 use mlua::{Lua, Table};
 
 use super::region::region_handle_of;
 use super::Model;
 
-/// A visible node's icon state (`TaxiNodeGetType`) — the reference maps these to the green
-/// (current) / white (reachable) / yellow (distant) icons.
+/// A visible node's icon state (`TaxiNodeGetType`): green, white or yellow in the reference.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub enum TaxiNodeType {
-    /// The flight master's own node ("You are here" — green).
+    /// The flight master's own node, "You are here".
     Current,
-    /// Known, and a route from the current node exists (white; clickable).
+    /// Known and routable from the current node; clickable.
     #[default]
     Reachable,
-    /// Known, but no route connects it to the current node (yellow). **Never produced**: the real
-    /// client's DISTANT classification is a dead branch (byte-verified — decision 0496 §TU-3; an
-    /// unroutable node simply doesn't render), so the app drops such nodes instead. The variant
-    /// stays because the reference Lua's `TaxiButtonTypes` table names it — a faithful surface
-    /// with no live writer.
+    /// Known but unroutable. Never produced: the reference's DISTANT branch is dead and an
+    /// unroutable node does not render; the variant stays because `TaxiButtonTypes` names it.
     Distant,
 }
 
 impl TaxiNodeType {
-    /// The Era type string (`TaxiFrame.lua`'s `TaxiButtonTypes` keys).
+    /// The type string, a `TaxiButtonTypes` key.
     fn era_str(self) -> &'static str {
         match self {
             TaxiNodeType::Current => "CURRENT",
@@ -56,24 +32,23 @@ impl TaxiNodeType {
     }
 }
 
-/// One node on the open taxi map — everything the window shows for it, app-resolved.
+/// One node on the open taxi map, resolved by the app.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TaxiUiNode {
-    /// `TaxiNodeName` (the DBC's localized name, e.g. `"Stormwind, Elwynn"`).
+    /// `TaxiNodeName`, the DBC's localized name.
     pub name: String,
-    /// `TaxiNodeGetType`. A node the reference would type `"NONE"` (hidden) is simply not pushed.
+    /// `TaxiNodeGetType`; a node the reference types `"NONE"` is not pushed.
     pub node_type: TaxiNodeType,
-    /// `TaxiNodePosition` — normalized `(x, y)` on the map art, 0..1, BOTTOMLEFT origin.
+    /// `TaxiNodePosition`: normalized `(x, y)` on the map art, from the bottom-left.
     pub pos: (f32, f32),
-    /// `TaxiNodeCost` — the route's fare in copper (0 for the current node / an unroutable one).
+    /// `TaxiNodeCost`: the fare in copper, 0 for the current node.
     pub cost: u32,
-    /// The hover route's per-hop segments, `[src_x, src_y, dest_x, dest_y]` each, in the same
-    /// normalized space (`GetNumRoutes` / `TaxiGetSrcX…DestY`). Empty for current/distant nodes.
+    /// The hover route's hops as `[src_x, src_y, dest_x, dest_y]` in the same space, for
+    /// `GetNumRoutes` and `TaxiGetSrcX` to `TaxiGetDestY`; empty for the current node.
     pub routes: Vec<[f32; 4]>,
 }
 
-/// The open taxi map: the continent art and the visible nodes. Pushed whole by the app; `None`
-/// means no taxi map is open.
+/// The open taxi map: the continent art and the visible nodes.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TaxiUiState {
     /// The map art `SetTaxiMap` assigns (e.g. `Interface\TaxiFrame\TAXIMAP1`).
@@ -88,21 +63,18 @@ impl super::UiScript {
         self.model_mut().taxi = state;
     }
 
-    /// Whether our own player is currently riding a taxi (`UnitOnTaxi("player")` — the action-bar
-    /// dim and the reference's flight-state checks read it).
+    /// Whether the player is riding a taxi, for `UnitOnTaxi("player")`.
     pub fn set_on_taxi(&mut self, riding: bool) {
         self.model_mut().taxi_riding = riding;
     }
 
-    /// Drain the **1-based node indices** `TakeTaxiNode` queued since the last call (the app maps
-    /// each back to its node id and sends the activate packet).
+    /// Drain the 1-based indices `TakeTaxiNode` queued; the app sends the activate for each.
     pub fn take_taxi_node(&mut self) -> Vec<usize> {
         std::mem::take(&mut self.model_mut().taxi_takes)
     }
 
-    /// Whether `CloseTaxiMap` was called since the last drain (and clear the flag). The window
-    /// closed client-side; the app clears its taxi state (no packet — the server holds no
-    /// open-window session for the map).
+    /// Whether `CloseTaxiMap` was called since the last drain; it sends no packet, as the server
+    /// holds no window session for the map.
     pub fn take_taxi_close(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().taxi_close)
     }
@@ -117,11 +89,9 @@ fn node(model: &Model, i: i64) -> Option<&TaxiUiNode> {
         .and_then(|i| nodes.get(i))
 }
 
-/// Register the taxi globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // → how many nodes the open map shows (0 when closed).
     g.set(
         "NumTaxiNodes",
         lua.create_function(|lua, ()| {
@@ -130,7 +100,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // → the node's icon-state string; "NONE" out of range (the reference hides that button).
+    // "NONE" out of range, a button the reference hides.
     g.set(
         "TaxiNodeGetType",
         lua.create_function(|lua, i: i64| {
@@ -139,7 +109,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // → the node's normalized map position (x, y; BOTTOMLEFT origin).
     g.set(
         "TaxiNodePosition",
         lua.create_function(|lua, i: i64| {
@@ -157,7 +126,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // → the fare to fly there, in copper (`SetTooltipMoney` renders it).
     g.set(
         "TaxiNodeCost",
         lua.create_function(|lua, i: i64| {
@@ -166,14 +134,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The real client arms the hovered node's route computation here; the app pushes every node's
-    // route precomputed, so this is a faithful no-op (kept so the reference Lua runs verbatim).
+    // The reference computes the hovered node's route here; the app precomputes every route.
     g.set(
         "TaxiNodeSetCurrent",
         lua.create_function(|_, _: i64| Ok(()))?,
     )?;
 
-    // → the hover route's hop count for node `i`.
     g.set(
         "GetNumRoutes",
         lua.create_function(|lua, i: i64| {
@@ -182,8 +148,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // → one endpoint coordinate of route hop `hop` (1-based) of node `i` — the four accessors the
-    // reference's `DrawRouteLine` loop reads.
+    // One coordinate of 1-based hop `hop`, for the reference's `DrawRouteLine` loop.
     for (name, pick) in [
         ("TaxiGetSrcX", 0usize),
         ("TaxiGetSrcY", 1),
@@ -203,7 +168,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // Queue the click — the app maps the index to a node id and sends the activate packet.
     g.set(
         "TakeTaxiNode",
         lua.create_function(|lua, i: i64| {
@@ -225,8 +189,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetTaxiMap(textureRegion) — assign the open map's continent art onto the given Texture
-    // region (the engine picked `TAXIMAP<map>`, app-side; the region draws it like any SetTexture).
+    // The open map's continent art (`TAXIMAP<map>`, the app's pick) onto the given texture.
     g.set(
         "SetTaxiMap",
         lua.create_function(|lua, this: Table| {
@@ -240,19 +203,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `UnitOnTaxi(unit)` (`0x517a40`) → **the number 1 or nil**, never a Lua boolean — the unit
-    // predicate family's one return shape (decisions 1830, 2043; the push law is
-    // `crate::script::binding_abi::flag`). It lives here rather than beside its 22 siblings
-    // because the ride flag it reads is this module's, not `UnitState`'s — which is exactly how it
-    // came to be the one predicate still answering a `bool` after the family was fixed.
-    //
-    // Only our own player is tracked (the reference UI only ever asks about `"player"`); any other
-    // token reads nil.
-    //
-    // The token argument is `Value`, not `String`, so the miss is the reference's own message: the
-    // binding carries an `lua_isstring` gate at `0x517a48` whose failure arm is
-    // `luaL_error("Usage: UnitOnTaxi(\"unit\")")`. A Rust `String` parameter raised mlua's
-    // own type-conversion error there instead.
+    // `0x517a40`: the number 1 or nil, never a boolean; an argument neither string nor number
+    // raises the reference's usage (`0x517a48`). Only the player is tracked, as the stock UI asks
+    // about no other unit.
     g.set(
         "UnitOnTaxi",
         lua.create_function(|lua, unit: mlua::Value| {
diff --git a/crates/benilla-ui/src/script/tests/addon_argument_abi.rs b/crates/benilla-ui/src/script/tests/addon_argument_abi.rs
index b9c1ed10..283a148b 100644
--- a/crates/benilla-ui/src/script/tests/addon_argument_abi.rs
+++ b/crates/benilla-ui/src/script/tests/addon_argument_abi.rs
@@ -1,11 +1,7 @@
-//! **The `index or "name"` prologue every in-game addon verb opens with, and its two raises**
-//! (2139's "left open", closed at the bytes).
-//!
-//! Eight bindings — `GetAddOnInfo 0x48e390`, `GetAddOnMetadata 0x48e530`,
+//! The `index or "name"` prologue of `GetAddOnInfo 0x48e390`, `GetAddOnMetadata 0x48e530`,
 //! `GetAddOnDependencies 0x48e5e0`, `EnableAddOn 0x48e690`, `DisableAddOn 0x48e760`,
-//! `IsAddOnLoadOnDemand 0x48e840`, `IsAddOnLoaded 0x48e8e0`, `LoadAddOn 0x48e980` — share one
-//! eleven-instruction prologue, and `luaL_error 0x6f4940` does not return from either of its
-//! failure arms. We answered a placeholder, a `nil` or a silent no-op for all of them.
+//! `IsAddOnLoadOnDemand 0x48e840`, `IsAddOnLoaded 0x48e8e0` and `LoadAddOn 0x48e980`; both its
+//! raises are `luaL_error` (`0x6f4940`), which does not return.
 
 use crate::script::{AddOnInfo, UiScript};
 
@@ -31,15 +27,11 @@ fn seeded() -> UiScript {
         None,
         None,
     );
-    // **The index space exists only once the server has answered** (decision 2175). These tests
-    // are about the prologue's bounds and raises, and a bound of zero would make every one of
-    // them pass vacuously — so the fixture seats the reply an in-world VM has always had, hiding
-    // nothing.
+    // The index space exists only once the server answers; with no reply every bound is zero.
     s.note_addon_info_reply(&[]);
     s
 }
 
-/// The message of a raise, or `"<no raise>"` if the call completed.
 fn raised(s: &UiScript, call: &str) -> String {
     s.eval::<String>(&format!(
         "local ok, e = pcall(function() {call} end) \
@@ -48,9 +40,7 @@ fn raised(s: &UiScript, call: &str) -> String {
     .unwrap()
 }
 
-/// **Every verb raises its own `Usage:` literal on a non-number, non-string argument.** Read out
-/// of `.data` (`0x842d68` … `0x842e98`) rather than reconstructed: the message reaches an addon's
-/// error handler, so the spelling is the contract.
+/// The client's own literals (`.data` `0x842d68` to `0x842e98`); addons see the spelling.
 #[test]
 fn a_bad_argument_type_raises_each_verbs_own_usage_string() {
     let s = seeded();
@@ -82,8 +72,7 @@ fn a_bad_argument_type_raises_each_verbs_own_usage_string() {
             "{call} must raise `{usage}`, got: {got}"
         );
     }
-    // `nil` and a missing argument fail the same two tests a table does — `lua_isnumber` reports
-    // NULL past `L->top` as "not a number" — so they take the same raise.
+    // `lua_isnumber` reports a slot past `L->top` as not a number, so nil or no argument raises.
     for call in ["LoadAddOn(nil)", "LoadAddOn()", "IsAddOnLoaded(true)"] {
         assert!(
             raised(&s, call).contains("index or \"name\""),
@@ -91,16 +80,12 @@ fn a_bad_argument_type_raises_each_verbs_own_usage_string() {
             raised(&s, call)
         );
     }
-    // The second argument has its own `lua_isstring` (`0x48e59c`) onto the SAME raise.
+    // The second argument's own `lua_isstring` (`0x48e59c`) fails onto the same raise.
     assert!(raised(&s, "GetAddOnMetadata(1)").contains("Usage: GetAddOnMetadata"));
 }
 
-/// **An out-of-range numeric index raises, on every verb, with the count in the message** —
-/// `"AddOn index must be in the range of 1 to %d"` (`0x837d70`), `%d` from `0x51def0()`.
-///
-/// The bound is **unsigned** (`0x51df00 cmp ecx,[0xbe1b90]; jb`), so `f(0)` decrements to
-/// `0xFFFFFFFF` and raises by the same route as `f(count+1)`. Only three of the eight raised at
-/// all before this, and those three said something the image does not.
+/// `"AddOn index must be in the range of 1 to %d"` (`0x837d70`, `%d` from `0x51def0()`). The
+/// bound is unsigned (`0x51df00 cmp ecx,[0xbe1b90]; jb`): 0 wraps to `0xFFFFFFFF` and raises.
 #[test]
 fn an_out_of_range_index_raises_with_the_registrys_own_count() {
     let s = seeded();
@@ -115,8 +100,7 @@ fn an_out_of_range_index_raises_with_the_registrys_own_count() {
         "LoadAddOn",
     ] {
         for arg in ["0", "3", "-1", "2.9"] {
-            // 2.9 truncates toward zero (`_ftol 0x40a2b0` chops) to 2, which is IN range — the
-            // one of the four that must NOT raise.
+            // 2.9 truncates to 2 (`_ftol 0x40a2b0`), which is in range.
             let got = raised(&s, &format!("{verb}({arg})"));
             if arg == "2.9" {
                 assert!(!got.contains("must be in the range"), "{verb}(2.9): {got}");
@@ -128,8 +112,7 @@ fn an_out_of_range_index_raises_with_the_registrys_own_count() {
     assert!(raised(&s, "GetAddOnMetadata(3, \"Version\")").contains(want));
 }
 
-/// **A numeric STRING is an index, not a name** — `lua_isnumber 0x6f34d0` coerces one, so the
-/// number arm claims it before `lua_isstring` is ever reached.
+/// `lua_isnumber` (`0x6f34d0`) coerces a numeric string, so the index arm claims it first.
 #[test]
 fn a_numeric_string_takes_the_index_arm() {
     let s = seeded();
@@ -141,11 +124,7 @@ fn a_numeric_string_takes_the_index_arm() {
     assert!(raised(&s, r#"GetAddOnInfo("9")"#).contains("must be in the range"));
 }
 
-/// **`GetAddOnInfo`'s string miss echoes the caller's own name back** (`0x48e401`, non-NULL by
-/// `lua_isstring`), then five metadata misses, `"MISSING"` and `"INSECURE"`. We answered the
-/// literal `"NoSuchAddon"` — an arbitrary choice, not a constant in the image.
-///
-/// The name form is never existence-checked by the prologue; only the numeric one is.
+/// A name miss echoes the caller's string (`0x48e401`); only an index is existence-checked.
 #[test]
 fn an_unknown_name_echoes_itself_rather_than_a_placeholder_literal() {
     let s = seeded();
@@ -165,7 +144,7 @@ fn an_unknown_name_echoes_itself_rather_than_a_placeholder_literal() {
             "INSECURE".into(),
         ]
     );
-    // The other name-miss answers are each verb's own, and they do not agree with GetAddOnInfo's.
+    // Each verb has its own name-miss answer.
     assert_eq!(
         s.eval::<String>(r#"return tostring(IsAddOnLoaded("Nope"))"#)
             .unwrap(),
diff --git a/crates/benilla-ui/src/script/tests/addon_index_space.rs b/crates/benilla-ui/src/script/tests/addon_index_space.rs
index 09d2c8c7..5e0d39f8 100644
--- a/crates/benilla-ui/src/script/tests/addon_index_space.rs
+++ b/crates/benilla-ui/src/script/tests/addon_index_space.rs
@@ -1,20 +1,11 @@
-//! **The Lua index space is not the registry** (decision 2175) — a different order, over a
-//! different set, that does not exist until the server answers.
-//!
-//! `GetNumAddOns` and the *index* form of every AddOn verb address a flat array the client
-//! rebuilds in exactly one place: the tail of `AddOn_ReadAddonInfoReply 0x51da70`
-//! (`[0x51dc30, 0x51dcdf)`), driven by `SMSG_ADDON_INFO`. It is `## Title`-sorted with
-//! `SStrCmpI`, filtered by `[rec+0x29]`, and empty before the reply — three properties benilla had
-//! none of, because it indexed the registry list directly (the binary's own `qsort 0x73f727` and
-//! comparator `0x51deb0`).
+//! The addon index space that `GetNumAddOns` and every verb's index form address: an array, not
+//! the registry, rebuilt only by `SMSG_ADDON_INFO` (`AddOn_ReadAddonInfoReply 0x51da70`,
+//! `[0x51dc30, 0x51dcdf)`). It is `## Title`-sorted with `SStrCmpI` (`qsort 0x73f727`, comparator
+//! `0x51deb0`), filtered by `[rec+0x29]`, and empty before the reply.
 
 use crate::script::{AddOnInfo, UiScript};
 
-/// Three addons whose FOLDER order and TITLE order are deliberately different permutations, so a
-/// test cannot pass by accident on a registry that happens to be sorted.
-///
-/// Folder order (registration): `Zulu`, `Alpha`, `Mike`.
-/// Title order: `Zulu` (`"aardvark"`), `Mike` (`"Middle"`), `Alpha` (`"zebra"`).
+/// Folder order `Zulu`, `Alpha`, `Mike`; title order `Zulu`, `Mike`, `Alpha`.
 fn seeded() -> UiScript {
     let mut s = UiScript::new().unwrap();
     let row = |name: &str, title: Option<&str>| AddOnInfo {
@@ -37,7 +28,6 @@ fn seeded() -> UiScript {
     s
 }
 
-/// The names `GetAddOnInfo(i)` answers, in index order.
 fn by_index(s: &UiScript) -> Vec<String> {
     s.eval::<Vec<String>>(
         "local t = {} for i = 1, GetNumAddOns() do t[i] = (GetAddOnInfo(i)) end return t",
@@ -45,14 +35,8 @@ fn by_index(s: &UiScript) -> Vec<String> {
     .unwrap()
 }
 
-/// **The index space is `## Title`-sorted, case-insensitively — not folder order.**
-///
-/// Comparator `0x51deb0` resolves both sides through `AddOn_GetTitle 0x51df20` and compares with
-/// `SStrCmpI` (`0x64a4c0` → `_strnicmp 0x414310`, which folds `'A'..'Z'` by `+0x20` on both
-/// operands — ASCII only, which is what `to_ascii_lowercase` is).
-///
-/// `"Middle"` is the case control: a byte-wise sort would put every capital before every
-/// lowercase and answer `Middle, aardvark, zebra`.
+/// Comparator `0x51deb0` compares `AddOn_GetTitle` (`0x51df20`) with `SStrCmpI` (`0x64a4c0`,
+/// `_strnicmp 0x414310`), folding ASCII only; a byte-wise sort would put `"Middle"` first.
 #[test]
 fn the_index_space_is_title_sorted_case_insensitively_and_not_registry_order() {
     let mut s = seeded();
@@ -60,9 +44,8 @@ fn the_index_space_is_title_sorted_case_insensitively_and_not_registry_order() {
     assert_eq!(by_index(&s), vec!["Zulu", "Mike", "Alpha"]);
 }
 
-/// **A record with no `## Title` sorts under its FOLDER name**, which is the comparator's
-/// fallback: `AddOn_GetTitle` misses (`0x51e046` returns 0) and `0x51ded0`/`0x51ded6` substitute
-/// the name the array holds.
+/// The comparator's fallback: `AddOn_GetTitle` misses (`0x51e046`) and `0x51ded0`/`0x51ded6`
+/// substitute the folder name.
 #[test]
 fn a_titleless_addon_sorts_under_its_folder_name() {
     let mut s = UiScript::new().unwrap();
@@ -75,7 +58,6 @@ fn a_titleless_addon_sorts_under_its_folder_name() {
                 enabled: true,
                 ..Default::default()
             },
-            // No title at all — sorts as "bravo", between nothing and "zzz".
             AddOnInfo {
                 name: "bravo".into(),
                 interface: 11200,
@@ -91,11 +73,8 @@ fn a_titleless_addon_sorts_under_its_folder_name() {
     assert_eq!(by_index(&s), vec!["bravo", "Yankee"]);
 }
 
-/// **There is no index space until `SMSG_ADDON_INFO` arrives** — `[0xbe1b90]` is zeroed by the
-/// registry reset `0x51fad1` and written nowhere but the reply's own rebuild.
-///
-/// The registry is fully populated here; only the array is absent. The raise is the same one an
-/// out-of-range index takes, because it *is* the same unsigned bound against a count of zero.
+/// The count `[0xbe1b90]` is zeroed by the registry reset (`0x51fad1`) and written only by the
+/// reply's rebuild, so before it an index raises the ordinary range error against 0.
 #[test]
 fn there_is_no_index_space_until_the_server_answers() {
     let s = seeded();
@@ -110,25 +89,19 @@ fn there_is_no_index_space_until_the_server_answers() {
         raised.contains("AddOn index must be in the range of 1 to 0"),
         "{raised}"
     );
-    // The registry is there all along — the NAME form never went through the array, it probes the
-    // master registry hash (`0x51df20`'s own lookup), so it answers for an addon the index space
-    // cannot reach.
+    // The name form probes the registry hash (`0x51df20`), not the array.
     assert_eq!(
         s.eval::<String>("return (GetAddOnInfo('Alpha'))").ok(),
         Some("Alpha".into())
     );
 }
 
-/// **A record the server hid is gone from the index space and still answers by name.**
-///
-/// `status = 2` sets `[rec+0x29] = 1` (`0x51db84`) and the rebuild's `0x51dc4f`/`0x51dc54` drops
-/// it. On a stock install that is all twelve `Blizzard_*` addons, which is why the reference's own
-/// AddOns list shows the player's addons and none of Blizzard's — and it is why the name form has
-/// to keep working, since `LoadAddOn("Blizzard_TalentUI")` is how the talent window opens.
+/// `status = 2` sets `[rec+0x29]` (`0x51db84`) and the rebuild drops it (`0x51dc4f`/`0x51dc54`);
+/// a stock install hides the twelve `Blizzard_*` addons this way, and they still load by name.
 #[test]
 fn a_hidden_addon_leaves_the_index_space_but_still_answers_by_name() {
     let mut s = seeded();
-    s.note_addon_info_reply(&["mike".into()]); // case-insensitive, as every name compare here is
+    s.note_addon_info_reply(&["mike".into()]); // names match case-insensitively
     assert_eq!(s.eval::<i64>("return GetNumAddOns()").ok(), Some(2));
     assert_eq!(by_index(&s), vec!["Zulu", "Alpha"]);
     assert_eq!(
@@ -137,8 +110,6 @@ fn a_hidden_addon_leaves_the_index_space_but_still_answers_by_name() {
     );
 }
 
-/// **An empty reply is not the same as no reply.** A server that hides nothing still brings the
-/// array into existence; only silence leaves it at zero.
 #[test]
 fn a_reply_that_hides_nothing_still_builds_the_array() {
     let mut s = seeded();
diff --git a/crates/benilla-ui/src/script/tests/anchors.rs b/crates/benilla-ui/src/script/tests/anchors.rs
index 12068c1e..63394d14 100644
--- a/crates/benilla-ui/src/script/tests/anchors.rs
+++ b/crates/benilla-ui/src/script/tests/anchors.rs
@@ -1,12 +1,10 @@
-//! SetPoint + resolve → GetWidth/GetHeight + rect.
+//! `SetPoint` and the anchor resolve: sizes, rects, and the reference's `SetPoint` raises.
 
 use super::common::script;
 use crate::layout::Rect;
 
-// Regression: an *explicit* `nil` relativeTo must still consume its argument slot, so the
-// relativePoint + offsets that follow line up. The `SetPoint("P", nil, "P", x, y)` form is the
-// common FrameXML idiom for "anchor to the screen at an offset"; a leading nil that failed to
-// advance the cursor silently dropped the offsets (screen-anchored frames pinned to the corner).
+// FrameXML's anchor-to-the-screen idiom, `SetPoint("P", nil, "P", x, y)`: the explicit `nil`
+// still takes its argument slot, so the offsets after it apply.
 #[test]
 fn setpoint_explicit_nil_relative_to_keeps_offsets() {
     let mut s = script();
@@ -68,22 +66,16 @@ fn setpoint_resolve_size_and_rect() {
 #[test]
 fn getwidth_falls_back_to_explicit_size_before_resolve() {
     let s = script();
-    // No SetPoint ⇒ unresolvable; GetWidth returns the explicit SetWidth value.
     let w: f32 = s
         .eval(r#"local f = CreateFrame("Frame"); f:SetWidth(123); return f:GetWidth()"#)
         .unwrap();
     assert_eq!(w, 123.0);
 }
 
-/// A *named* `relativeTo` that does not resolve **RAISES** and abandons the call — the reference's
-/// `luaL_error(0x87ccd4, "%s:SetPoint(): Couldn't find region named '%s'")`, with no fallback and
-/// no no-op (decision 2176; 2105 pinned the bytes and deferred the change until the addon survey
-/// could see engine warnings). The region path is the same registered function, so it raises the
-/// same way — and both quote the receiver's own name, `<unnamed>` (`0x84c7f0`) when it has none.
-///
-/// **This replaces a parent/owner fallback plus a warning.** That fallback is what misdirected
-/// ItemTextFrame's scrollbar track onto the parchment; the XML half of the same miss is a
-/// different law and keeps its warning (`Loader::apply_anchor`, `0x767800`).
+/// A named `relativeTo` that does not resolve raises and abandons the call, with no fallback
+/// (`0x87ccd4`); the region path raises the same, both quoting the receiver's name, `<unnamed>`
+/// (`0x84c7f0`) when it has none. An XML anchor's miss warns instead (`Loader::apply_anchor`,
+/// `0x767800`).
 #[test]
 fn setpoint_unresolved_name_raises() {
     let mut s = script();
@@ -110,12 +102,11 @@ fn setpoint_unresolved_name_raises() {
         "region path (anonymous receiver): {e}"
     );
 
-    // The anchor was ABANDONED, not applied to the parent: the frame still has none.
     let n: i64 = s.eval("return Orphan:GetNumPoints()").unwrap();
     assert_eq!(n, 0, "the raise must leave no anchor behind");
 
-    // `SetAllPoints` has its own string, and a NUMBER takes the name path there (`lua_isstring`)
-    // where `SetPoint` would read it as an offset.
+    // `SetAllPoints` has its own message, and a number takes the name path there (`lua_isstring`)
+    // where `SetPoint` reads it as an offset.
     let e = s
         .run(r#"Orphan:SetAllPoints("NoSuchFrame")"#)
         .unwrap_err()
@@ -130,22 +121,16 @@ fn setpoint_unresolved_name_raises() {
         "a number is a string to `lua_isstring`, so it is looked up as `_G[\"42\"]`: {e}"
     );
 
-    // A resolvable name still works, and warns about nothing.
     s.run(r#"CreateFrame("Frame", "Target"); Orphan:SetPoint("BOTTOMLEFT", "Target", "TOPLEFT")"#)
         .unwrap();
     assert!(s.take_warnings().is_empty());
 }
 
-/// The other four raises of the same ladder, each read out of the reference image.
-///
-/// * **Usage** `0x87cc28` — an absent `relativeTo` is `TNONE` and fails the `lua_type(L,3)` gate
-///   (`0x7a25e6`–`0x7a2620`), so a one-argument `SetPoint` is an error on a 1.12 client. Stock
-///   content makes none (349 call sites, arity histogram `{3:5, 4:1, 5:343}`); five sites in the
-///   219-addon vanilla corpus do, all of them in multi-client code.
-/// * **Unknown region point** `0x87cd04`, from the 9-entry scan `0x6f1840`.
-/// * **trying to anchor to itself** `0x87cca8` / `0x87cd54`.
-/// * And the ORDER is observable: the two tag gates run before the point-name scan, so an unknown
-///   point with an absent `relativeTo` answers Usage, not "Unknown region point".
+/// The reference's other `SetPoint` raises: Usage (`0x87cc28`) when `relativeTo` is absent, since
+/// `lua_type(L,3)` is `TNONE` at the gate (`0x7a25e6-0x7a2620`); "Unknown region point"
+/// (`0x87cd04`, the 9-entry scan `0x6f1840`); "trying to anchor to itself" (`0x87cca8`,
+/// `0x87cd54`). The type gates run before the point scan, so an unknown point with no
+/// `relativeTo` answers Usage.
 #[test]
 fn the_other_setpoint_raises() {
     let s = script();
@@ -163,7 +148,6 @@ fn the_other_setpoint_raises() {
         .to_string();
     assert!(e.contains("Ladder:SetPoint(): Unknown region point"), "{e}");
 
-    // Unknown point AND absent relativeTo: the tag gate is first, so this is Usage.
     let e = s
         .run(r#"Ladder:SetPoint("MIDDLE")"#)
         .unwrap_err()
@@ -180,18 +164,14 @@ fn the_other_setpoint_raises() {
     );
 }
 
-/// **A trailing explicit `nil` is PRESENT, and absent is absent** — the one thing that would make
-/// the Usage raise over-fire. `lua_type(L,3)` distinguishes `LUA_TNIL` (0, the screen-root arm)
-/// from `LUA_TNONE` (−1, which fails the gate), so the ladder must see the argument count Lua saw
-/// and not a tuple padded or trimmed on the way in.
+/// `lua_type(L,3)` tells `LUA_TNIL` (0, the screen root) from `LUA_TNONE` (-1, Usage), so the
+/// raise ladder must see the argument count Lua saw, not a padded or trimmed tuple.
 #[test]
 fn a_trailing_nil_relative_to_is_present_where_an_absent_one_is_not() {
     let s = script();
     s.run(r#"f = CreateFrame("Frame", "Trail")"#).unwrap();
-    // Present-and-nil: legal, the screen root, no offsets.
     s.run(r#"Trail:SetPoint("CENTER", nil)"#).unwrap();
     assert_eq!(s.eval::<i64>("return Trail:GetNumPoints()").unwrap(), 1);
-    // Absent: Usage.
     let e = s
         .run(r#"Trail:SetPoint("CENTER")"#)
         .unwrap_err()
@@ -199,10 +179,8 @@ fn a_trailing_nil_relative_to_is_present_where_an_absent_one_is_not() {
     assert!(e.contains("Usage:"), "{e}");
 }
 
-/// An explicit `nil` `relativeTo` is the **SCREEN ROOT** (`0x7a2710 mov eax,ds:0xcf0bd8`), not the
-/// parent — the arm benilla answered with the parent until 2176. `UIParent.lua:1549` is the one
-/// stock site; fourteen corpus sites take it, every one of them meaning "the screen"
-/// (`pfUI`'s screenshot caption, `FixCTGroups`' cursor-space plate).
+/// An explicit `nil` `relativeTo` is the screen root, not the parent (`0x7a2710` loads it from
+/// `0xcf0bd8`); the one stock site is `UIParent.lua:1549`.
 #[test]
 fn an_explicit_nil_relative_to_is_the_screen_not_the_parent() {
     let mut s = script();
@@ -226,21 +204,8 @@ fn an_explicit_nil_relative_to_is_the_screen_not_the_parent() {
     );
 }
 
-/// **A region whose OWNER has no rect still resolves from its own anchors.**
-///
-/// `layout.rs`'s region pass used to `continue` when `resolved` held nothing for the owner frame.
-/// But the owner's rect is only the *fallback* for axes the region's own anchors do not pin — a
-/// region anchored fully to some other frame needs nothing from its owner, and the reference
-/// resolves it. Skipping made an ordinary addon shape silently invisible: a bare container frame
-/// (`CreateFrame("Frame", n, parent)` with no size and no `SetPoint`) holding a region anchored
-/// elsewhere.
-///
-/// Found by reproducing the director's MapCoords report. Its world-map readout computed the right
-/// string every single frame — `Cursor Coords: … Player Coords: …` — and was never given a
-/// position, with no error raised anywhere. Three of its four frames are this shape.
-///
-/// The control matters as much as the subject: a SIZED owner must be unaffected, or the fix has
-/// traded one wrong layout for another.
+/// A region resolves from its own anchors and size; its owner supplies only the scale, so a region
+/// anchored elsewhere resolves under an unpositioned owner. A sized owner is the control.
 #[test]
 fn a_region_resolves_even_when_its_owner_frame_has_no_rect() {
     let mut s = crate::script::UiScript::new().unwrap();
@@ -268,14 +233,13 @@ fn a_region_resolves_even_when_its_owner_frame_has_no_rect() {
     .unwrap();
     s.resolve();
 
-    // The owner genuinely has no rect — that part is correct and must stay true.
     assert_eq!(
         s.eval::<Option<f32>>("return BareOwner:GetLeft()").unwrap(),
         None,
         "an unpositioned frame has no rect; the fix must not invent one for it"
     );
 
-    // ...and its region resolves anyway, from its own anchor: host's BOTTOMLEFT (100,50) + (5,7).
+    // Host's BOTTOMLEFT (100,50) plus the (5,7) offset.
     assert_eq!(
         s.eval::<Option<f32>>("return BareMark:GetLeft()").unwrap(),
         Some(105.0),
@@ -286,7 +250,6 @@ fn a_region_resolves_even_when_its_owner_frame_has_no_rect() {
             .unwrap(),
         Some(57.0)
     );
-    // The control is unmoved.
     assert_eq!(
         s.eval::<Option<f32>>("return SizedMark:GetLeft()").unwrap(),
         Some(105.0),
@@ -294,19 +257,10 @@ fn a_region_resolves_even_when_its_owner_frame_has_no_rect() {
     );
 }
 
-/// **…but a region the owner's rect is the ONLY candidate for stays unresolved with it.**
-///
-/// The other half of the law above, and the half that shipped wrong: an unpinned axis on an
-/// unpositioned owner has nothing to fall back to, so standing a zero rect in for the missing owner
-/// puts the region at the **screen origin** instead of nowhere. That is not a degenerate rect, it is
-/// a wrong position — and a template whose textures chain off each other turns it into real,
-/// visible geometry a few links down.
-///
-/// The symptom: opening the social pane draws a stray dropdown capsule at
-/// the bottom of the screen next to the action bar. `FriendsDropDown` carries no anchors —
-/// *exactly* as the reference's own `FriendsDropDown` does (`FriendsFrame.xml` l.598), and the
-/// reference draws nothing — so every texture of `UIDropDownMenuTemplate` hung off a phantom rect
-/// at (0,0). The shape below is that template's first two textures verbatim.
+/// A region anchored to an unpositioned owner has no rect, nor does the chain off it; a zero rect
+/// in its place would draw at the screen origin. The shape is `UIDropDownMenuTemplate`'s first two
+/// textures under the anchorless `FriendsDropDown` (`FriendsFrame.xml:598`), which the reference
+/// does not draw.
 #[test]
 fn an_unanchored_owners_region_chain_resolves_nowhere() {
     let mut s = crate::script::UiScript::new().unwrap();
@@ -349,24 +303,14 @@ fn an_unanchored_owners_region_chain_resolves_nowhere() {
     );
 }
 
-/// **Geometry answers inside the same call stack that moved it** — the seam that killed 97 addons.
-///
-/// A handler creates a frame, anchors it, shows it and then measures it, all before any resolve
-/// pass can run. `Dewdrop-2.0.lua` — embedded in ~65 corpus addons — does exactly this in its menu
-/// `Open`: `local left = frame:GetLeft()` (l.1942) then `curX - left - width/2` (l.1960). Our
-/// getters read a cache filled by the per-frame `resolve()`, so `left` was nil and the arithmetic
-/// died. **97 of the 108 addons that drew and then raised on being touched died on that one line**,
-/// with no missing verb anywhere.
-///
-/// The readers settle the graph on demand now. The second half of the test is the one that keeps
-/// it honest: a *further* move inside the same stack must also be visible, or the fix is just a
-/// one-shot warm-up.
+/// The geometry readers settle the layout on demand, so a frame moved inside a call stack reports
+/// its new rect in that stack, again after a second move.
 #[test]
 fn geometry_answers_within_the_call_stack_that_moved_it() {
     let mut s = crate::script::UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
 
-    // Dewdrop's shape, in one eval — no resolve() between the writes and the read.
+    // Dewdrop-2.0's menu `Open` in one eval: no `resolve()` between the writes and the read.
     let (left, bottom): (Option<f32>, Option<f32>) = s
         .eval(
             r#"
@@ -384,7 +328,6 @@ fn geometry_answers_within_the_call_stack_that_moved_it() {
         "a frame must report its geometry in the stack that anchored it"
     );
 
-    // ...and a LATER move in the same stack is visible too — not a stale first answer.
     let moved: Option<f32> = s
         .eval(
             r#"
@@ -396,7 +339,6 @@ fn geometry_answers_within_the_call_stack_that_moved_it() {
         .unwrap();
     assert_eq!(moved, Some(200.0), "the settle must re-run after each move");
 
-    // Width/height and the centre reader take the same path.
     assert_eq!(
         s.eval::<(f32, f32)>("return MenuLike:GetWidth(), MenuLike:GetHeight()")
             .unwrap(),
diff --git a/crates/benilla-ui/src/script/tests/backdrop.rs b/crates/benilla-ui/src/script/tests/backdrop.rs
index f82ef0bf..5a4a8d1d 100644
--- a/crates/benilla-ui/src/script/tests/backdrop.rs
+++ b/crates/benilla-ui/src/script/tests/backdrop.rs
@@ -1,10 +1,9 @@
-//! Backdrop: Lua verbs + extract emission (the reference's Backdrop object, `0x77e5f0`).
+//! The backdrop Lua verbs and extract emission (the reference's Backdrop object, `0x77e5f0`).
 
 use super::common::script;
 use crate::script::*;
 
-// SetBackdrop installs the plate; SetBackdropColor tints the bg only, SetBackdropBorderColor all 8
-// border pieces; extract emits bg-then-border at the frame's own slot with those colors.
+// SetBackdropColor tints only the bg, SetBackdropBorderColor the 8 border pieces.
 #[test]
 fn backdrop_installs_and_extracts_pieces_with_colors() {
     let mut s = script();
@@ -35,24 +34,17 @@ fn backdrop_installs_and_extracts_pieces_with_colors() {
         .collect();
     // bg (1) + 8 border pieces.
     assert_eq!(pieces.len(), 9);
-    // First is the bg, tinted the tooltip background color — QUANTIZED. The reference's colour
-    // field is a packed `0xAARRGGBB` byte quad and the setter converts `×255 + 0.5` through
-    // `__ftol` (`SetBackdropColor 0x777d30`), so `0.09` stores as 23 and reads back
-    // as `23/255`. This assertion used to hold `0.09` exactly, which was our lossless `[f32; 4]`
-    // showing through a store the client cannot make.
+    // The colour is a packed `0xAARRGGBB` byte quad, stored as `×255 + 0.5` through `__ftol`
+    // (`SetBackdropColor 0x777d30`), so 0.09 reads back as 23/255.
     assert_eq!(pieces[0].0, "bg");
     let q = |x: f32| f32::from((x * 255.0 + 0.5) as u8) / 255.0;
     assert_eq!(pieces[0].1, [q(0.09), q(0.09), q(0.19), 1.0]);
-    // The remaining 8 are the border, white, from the edge file.
     assert!(pieces[1..]
         .iter()
         .all(|(p, c)| p == "edge" && *c == [1.0, 1.0, 1.0, 1.0]));
 }
 
-// `GetBackdrop()` — the four traps of `0x777370`, pinned
-// where an addon can observe them. The corpus caller is `BuffCheck2.lua:448`, which reads the table
-// back, edits `insets`, and feeds it straight to `SetBackdrop` — so a wrong `tile` type or a missing
-// ctor default does not just read wrong, it round-trips wrong.
+// The four traps of `GetBackdrop()` (`0x777370`), as an addon observes them.
 #[test]
 fn get_backdrop_reconstructs_from_the_struct() {
     let s = script();
@@ -123,8 +115,7 @@ fn get_backdrop_reconstructs_from_the_struct() {
     .unwrap();
 }
 
-// BuffCheck2.lua:448's exact shape: read the plate back, edit `insets`, push it straight back in.
-// It is the whole reason this method exists in our client, so it is the test that must not rot.
+// The shape of `BuffCheck2.lua:448`: read the plate back, edit `insets`, set it again.
 #[test]
 fn get_backdrop_round_trips_through_set_backdrop() {
     let mut s = script();
@@ -151,7 +142,7 @@ fn get_backdrop_round_trips_through_set_backdrop() {
     )
     .unwrap();
     s.resolve();
-    // The plate still draws: bg + 8 border pieces, unchanged by the round trip.
+    // bg (1) + 8 border pieces.
     assert_eq!(
         s.extract()
             .iter()
@@ -161,7 +152,6 @@ fn get_backdrop_round_trips_through_set_backdrop() {
     );
 }
 
-// SetBackdrop(nil) tears the plate down (no pieces after).
 #[test]
 fn set_backdrop_nil_tears_down() {
     let mut s = script();
@@ -183,17 +173,8 @@ fn set_backdrop_nil_tears_down() {
         .all(|q| !matches!(q.content, QuadContent::Backdrop { .. })));
 }
 
-/// **The colour setters' argument gating is asymmetric, and getting it backwards is worse than
-/// the bug it replaces** (`0x777d30` / `0x7780d0`).
-///
-/// r/g/b go through a bare `lua_tonumber` — a `nil` channel is `0.0` and the call COMPLETES.
-/// benilla typed them `f32` and raised, which killed ShaguTweaks at `helpers.lua:248`, where
-/// `color.r` comes off a table that does not always have one.
-///
-/// Alpha is different: `lua_isnumber`-gated at `0x778227` with `1.0f` staged at `0x778220`, so a
-/// missing **or nil** alpha is OPAQUE. The tempting blanket fix — "treat every nil as 0.0, like
-/// its neighbours" — would have turned every one of those borders transparent, which reads as a
-/// rendering fault rather than an API bug and is the reason this test names both halves.
+/// The colour setters (`0x777d30`, `0x7780d0`) read r/g/b with a bare `lua_tonumber` (nil is 0.0)
+/// and gate alpha on `lua_isnumber` (`0x778227`) over a staged 1.0 (`0x778220`).
 #[test]
 fn backdrop_colors_coerce_rgb_but_default_alpha_opaque() {
     let s = script();
@@ -205,7 +186,6 @@ fn backdrop_colors_coerce_rgb_but_default_alpha_opaque() {
     )
     .unwrap();
 
-    // A nil channel is 0.0 and the call completes — no raise.
     s.run("f:SetBackdropBorderColor(nil, 1, 1, 1)").unwrap();
     assert_eq!(
         s.eval::<(f32, f32, f32, f32)>("return f:GetBackdropBorderColor()")
@@ -213,7 +193,6 @@ fn backdrop_colors_coerce_rgb_but_default_alpha_opaque() {
         (0.0, 1.0, 1.0, 1.0)
     );
 
-    // A missing alpha is 1.0, and so is an explicit nil one — NOT 0.0.
     s.run("f:SetBackdropColor(0.2, 0.4, 0.6)").unwrap();
     let (_, _, _, a) = s
         .eval::<(f32, f32, f32, f32)>("return f:GetBackdropColor()")
@@ -234,7 +213,6 @@ fn backdrop_colors_coerce_rgb_but_default_alpha_opaque() {
         .eval::<(f32, f32, f32, f32)>("return f:GetBackdropColor()")
         .unwrap();
     assert_eq!((r, g, b), (1.0, 0.0, 0.0));
-    // Quantized `×255 + 0.5` through `__ftol`: 0.5 -> 128/255, not 0.5 exactly. The field is a
-    // packed 0xAARRGGBB byte quad and nothing finer survives the store.
+    // Stored as a byte: 0.5 reads back as 128/255.
     assert_eq!(a, 128.0 / 255.0);
 }
diff --git a/crates/benilla-ui/src/script/tests/button.rs b/crates/benilla-ui/src/script/tests/button.rs
index 5559c893..4ebf3132 100644
--- a/crates/benilla-ui/src/script/tests/button.rs
+++ b/crates/benilla-ui/src/script/tests/button.rs
@@ -14,7 +14,6 @@ fn button_methods_exist_only_on_buttons() {
     "#,
     )
     .unwrap();
-    // Duck-typing honesty across the class chain (the reference's per-type method sets).
     assert!(s.eval::<bool>("return f.SetText == nil").unwrap());
     assert!(s.eval::<bool>("return f.SetChecked == nil").unwrap());
     assert!(s.eval::<bool>("return b.SetText ~= nil").unwrap());
@@ -22,7 +21,7 @@ fn button_methods_exist_only_on_buttons() {
     assert!(s.eval::<bool>("return b.SetValue == nil").unwrap());
     assert!(s.eval::<bool>("return cb.SetChecked ~= nil").unwrap());
     assert!(s.eval::<bool>("return cb.SetNormalTexture ~= nil").unwrap());
-    // Buttons are mouse-enabled by construction (the client ctor enables input).
+    // The 1.12 client's Button constructor enables mouse input; a Frame's does not.
     assert!(s.eval::<bool>("return b:IsMouseEnabled()").unwrap());
     assert!(!s.eval::<bool>("return f:IsMouseEnabled()").unwrap());
 }
@@ -55,22 +54,18 @@ fn button_state_textures_switch_with_interaction() {
             .collect()
     };
 
-    // Idle: normal only (pushed/disabled suppressed; not hovered ⇒ no highlight).
     assert_eq!(visible(&s), vec!["Interface\\N.blp".to_string()]);
-    // The ButtonText always draws.
     assert!(s
         .extract()
         .iter()
         .any(|q| matches!(&q.content, QuadContent::Text { text: Some(t), .. } if t == "Go")));
 
-    // Hover: normal + additive highlight.
     s.mouse_move(50.0, 50.0);
     let v = visible(&s);
     assert!(
         v.contains(&"Interface\\N.blp".to_string()) && v.contains(&"Interface\\H.blp".to_string())
     );
 
-    // Held down over it: pushed replaces normal (highlight still hovering).
     s.mouse_button(50.0, 50.0, "LeftButton", true);
     let v = visible(&s);
     assert!(
@@ -78,31 +73,18 @@ fn button_state_textures_switch_with_interaction() {
     );
     s.mouse_button(50.0, 50.0, "LeftButton", false);
 
-    // Disabled: disabled texture only, and no highlight even under the cursor.
     s.run("StateBtn:Disable()").unwrap();
     assert_eq!(visible(&s), vec!["Interface\\D.blp".to_string()]);
-    // 0, not false, and not nil — the number the real client answers.
+    // The 1.12 client answers the number 0, not false or nil.
     assert_eq!(s.eval::<i64>("return StateBtn:IsEnabled()").unwrap(), 0);
     s.run("StateBtn:Enable()").unwrap();
     assert_eq!(s.eval::<String>("return StateBtn:GetText()").unwrap(), "Go");
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **The shown texture is STICKY: a state with no art of its own changes nothing.**
-///
-/// `SetState 0x779790` gates the hide-old step *and* the show-new step on the NEW state's slot
-/// being non-null, so the shown pointer `+0x4c4`
-/// only ever moves onto a real texture — it is never cleared, and there is no fallback path in the
-/// function at all. Three consequences, and they are one mechanism seen from three sides:
-///
-/// - a press with no `<PushedTexture>` keeps the normal art (which our old model hard-coded as a
-///   `pushed.or(normal)` fallback — the special case *was* this rule, seen from one side);
-/// - **`Disable()` with no `<DisabledTexture>` keeps the normal art** — B369, where the reference's
-///   `ReputationDetailAtWarCheckBox` stays a visible box for a faction whose war flag is locked
-///   while ours went to a bare grey label;
-/// - a state texture assigned while the button is in a *different* state is not displayed
-///   (`0x778fd0`'s `idx == [this+0x328]` gate), so a button disabled *before* it is given normal
-///   art draws nothing — the two disabled cases differ only in whether anything was ever shown.
+/// `SetState 0x779790` moves the shown texture (`+0x4c4`) only onto a non-null slot, so a press or
+/// a disable with no art of its own keeps what was shown; art written into another state's slot
+/// is stored, not shown (`0x778fd0`'s `idx == [this+0x328]` gate).
 #[test]
 fn a_state_with_no_texture_leaves_the_shown_one_standing() {
     let mut s = script();
@@ -131,22 +113,18 @@ fn a_state_with_no_texture_leaves_the_shown_one_standing() {
 
     assert_eq!(visible(&s, "StickyBtn"), n, "resting on its normal art");
 
-    // Pressed with no PushedTexture: SetState(2) finds a null slot, so nothing moves.
     s.mouse_move(50.0, 50.0);
     s.mouse_button(50.0, 50.0, "LeftButton", true);
     assert_eq!(visible(&s, "StickyBtn"), n, "a press with no pushed art");
     s.mouse_button(50.0, 50.0, "LeftButton", false);
     s.mouse_move(400.0, 400.0);
 
-    // Disabled with no DisabledTexture: the same null slot, the same nothing. **B369.**
     s.run("StickyBtn:Disable()").unwrap();
     assert_eq!(
         visible(&s, "StickyBtn"),
         n,
         "a disable with no disabled art leaves the box on screen"
     );
-    // Giving it disabled art NOW does show it — `0x778fd0` pushes to `+0x4c4` because the slot
-    // being written IS the current state's.
     s.run("StickyBtn:SetDisabledTexture(\"Interface\\\\D.blp\")")
         .unwrap();
     assert_eq!(
@@ -157,8 +135,6 @@ fn a_state_with_no_texture_leaves_the_shown_one_standing() {
     s.run("StickyBtn:Enable()").unwrap();
     assert_eq!(visible(&s, "StickyBtn"), n, "back to normal on Enable");
 
-    // The other side of the same gate: a button disabled BEFORE it has normal art shows nothing,
-    // because the write lands in a slot that is not the current state's.
     s.run(
         r#"
         local b = CreateFrame("Button", "BornDeadBtn")
@@ -176,14 +152,9 @@ fn a_state_with_no_texture_leaves_the_shown_one_standing() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **`Disable()` switches off the HIGHLIGHT draw LAYER, not just the HighlightTexture.**
-///
-/// The helper both `Enable`/`Disable` and the constructor reach (`0x779160`) does two things: the
-/// `SetState` above, and `0x7791bb push 4; call 0x76a730` — the per-layer enable for layer 4,
-/// written into the same `[frame+0x198]` array `Enable/DisableDrawLayer` writes. So a region the
-/// button owns in HIGHLIGHT that is not its HighlightTexture goes dark with it, and an explicit
-/// `EnableDrawLayer` brings the whole layer back on a still-disabled button. Our old rule gated
-/// the HighlightTexture alone on `enabled`, which agreed on the common case and not on this one.
+/// The enable helper `0x779160` (reached by `Enable`, `Disable` and the constructor) also writes
+/// layer 4, HIGHLIGHT, into the array `Enable/DisableDrawLayer` write (`[frame+0x198]`, `0x7791bb`
+/// → `0x76a730`), so a disable darkens every HIGHLIGHT region and `EnableDrawLayer` relights them.
 #[test]
 fn disabling_a_button_takes_its_whole_highlight_layer() {
     let mut s = script();
@@ -213,7 +184,6 @@ fn disabling_a_button_takes_its_whole_highlight_layer() {
             .collect()
     };
 
-    // Hovered and enabled: normal art, the button's own HIGHLIGHT region, and the HighlightTexture.
     s.mouse_move(50.0, 50.0);
     let v = art(&s);
     for want in ["Interface\\N.blp", "Interface\\Own.blp", "Interface\\H.blp"] {
@@ -223,8 +193,6 @@ fn disabling_a_button_takes_its_whole_highlight_layer() {
         );
     }
 
-    // Disabled under the same cursor: the layer is off, so BOTH highlight-layer regions go — and
-    // the normal art stays, because no state texture moved (the sticky rule).
     s.run("LayerBtn:Disable()").unwrap();
     assert_eq!(
         art(&s),
@@ -232,7 +200,6 @@ fn disabling_a_button_takes_its_whole_highlight_layer() {
         "the whole HIGHLIGHT layer goes with the disable"
     );
 
-    // The layer is a layer: turning it back on lights both again, disabled or not.
     s.run(r#"LayerBtn:EnableDrawLayer("HIGHLIGHT")"#).unwrap();
     let v = art(&s);
     assert!(
@@ -246,7 +213,6 @@ fn disabling_a_button_takes_its_whole_highlight_layer() {
         "and it really is still disabled"
     );
 
-    // …and Enable() writes the same one array, so it undoes an addon's DisableDrawLayer.
     s.run(r#"LayerBtn:DisableDrawLayer("HIGHLIGHT") LayerBtn:Enable()"#)
         .unwrap();
     let v = art(&s);
@@ -257,12 +223,8 @@ fn disabling_a_button_takes_its_whole_highlight_layer() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **A right-click lights a button up too** — the director's report, and `0x77924b`'s law.
-///
-/// `CButton::OnMouseDown` gates the PushedTexture on `[this+0x330] & (m | m << 8)`: the button
-/// registered for that mouse button in **either** variant. Not on the click firing, not on the
-/// handler doing anything — which is why right-clicking an action, spellbook or pet slot flashes,
-/// while right-clicking a default `LeftButtonUp` button does not.
+/// `CButton::OnMouseDown` shows the pushed texture when the button is registered for that mouse
+/// button, up or down (`0x77924b`: `[this+0x330] & (m | m << 8)`), whether or not a click fires.
 #[test]
 fn any_registered_mouse_button_shows_the_pushed_texture() {
     let mut s = script();
@@ -290,7 +252,6 @@ fn any_registered_mouse_button_shows_the_pushed_texture() {
             .any(|q| matches!(&q.content, QuadContent::Texture { path: Some(p), .. } if p == path))
     };
 
-    // The bar slot lights under EITHER button.
     for button in ["LeftButton", "RightButton"] {
         s.mouse_move(50.0, 50.0);
         s.mouse_button(50.0, 50.0, button, true);
@@ -307,7 +268,6 @@ fn any_registered_mouse_button_shows_the_pushed_texture() {
         assert!(shows(&s, "Interface\\BarN.blp"), "the release restores it");
     }
 
-    // The plain button lights under the left only — `0x77924b` is a real gate, not a formality.
     s.mouse_move(250.0, 50.0);
     s.mouse_button(250.0, 50.0, "RightButton", true);
     assert!(
@@ -321,9 +281,8 @@ fn any_registered_mouse_button_shows_the_pushed_texture() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// `SetButtonState`/`GetButtonState` (`0x780270`/`0x780180`) — the scripted press state the ref's
-/// `ActionButtonDown/Up` keybind pair drives: PUSHED shows the pushed texture with no mouse
-/// involved, NORMAL restores, unknown states error, and a disabled button answers DISABLED.
+/// `SetButtonState`/`GetButtonState` (`0x780270`/`0x780180`), the press state stock
+/// `ActionButtonDown`/`Up` drive; an unknown state raises, a disabled button reads DISABLED.
 #[test]
 fn set_button_state_drives_the_pushed_visual() {
     let mut s = script();
@@ -356,9 +315,7 @@ fn set_button_state_drives_the_pushed_visual() {
     assert!(shows(&s, "Interface\\P.blp") && !shows(&s, "Interface\\N.blp"));
     s.run(r#"PushBtn:SetButtonState("NORMAL")"#).unwrap();
     assert!(shows(&s, "Interface\\N.blp") && !shows(&s, "Interface\\P.blp"));
-    // Unknown state: a runtime error, not a silent no-op.
     assert!(s.run(r#"PushBtn:SetButtonState("SIDEWAYS")"#).is_err());
-    // Disabled wins the read (Enable/Disable owns that state, not SetButtonState).
     s.run("PushBtn:Disable()").unwrap();
     assert_eq!(
         s.eval::<String>("return PushBtn:GetButtonState()").unwrap(),
@@ -385,20 +342,17 @@ fn disabled_button_swallows_clicks_checkbutton_toggles_before_onclick() {
     .unwrap();
     s.resolve();
 
-    // Physical click: the checked state flips BEFORE OnClick (the documented contract).
     s.mouse_button(50.0, 50.0, "LeftButton", true);
     s.mouse_button(50.0, 50.0, "LeftButton", false);
     assert_eq!(s.eval::<i64>("return clicks").unwrap(), 1);
-    // `seen_checked` is whatever `GetChecked()` handed the handler — the NUMBER 1 (1830).
+    // `GetChecked()` answers the number 1, not true.
     assert!(s.eval::<bool>("return seen_checked == 1").unwrap());
     assert!(s.eval::<bool>("return Toggler:GetChecked()").unwrap());
 
-    // Programmatic Click() rides the same path: toggles back off.
     s.run("Toggler:Click()").unwrap();
     assert_eq!(s.eval::<i64>("return clicks").unwrap(), 2);
     assert!(!s.eval::<bool>("return Toggler:GetChecked()").unwrap());
 
-    // Disabled: the click is swallowed — no OnClick, no toggle.
     s.run("Toggler:Disable()").unwrap();
     s.mouse_button(50.0, 50.0, "LeftButton", true);
     s.mouse_button(50.0, 50.0, "LeftButton", false);
@@ -406,7 +360,6 @@ fn disabled_button_swallows_clicks_checkbutton_toggles_before_onclick() {
     assert_eq!(s.eval::<i64>("return clicks").unwrap(), 2);
     assert!(!s.eval::<bool>("return Toggler:GetChecked()").unwrap());
 
-    // SetChecked takes 1/true/nil (1.12 and Era forms).
     s.run("Toggler:SetChecked(1)").unwrap();
     assert!(s.eval::<bool>("return Toggler:GetChecked()").unwrap());
     s.run("Toggler:SetChecked(nil)").unwrap();
@@ -429,8 +382,7 @@ fn default_registration_is_left_click_only_right_click_reaches_nothing() {
     .unwrap();
     s.resolve();
 
-    // A right-click (press+release, same frame) reaches OnMouseDown/OnMouseUp but never OnClick —
-    // the client's own default registered-click set is {"LeftButtonUp"} only.
+    // The 1.12 client's default registered-click set is {"LeftButtonUp"} alone.
     s.mouse_button(50.0, 50.0, "RightButton", true);
     s.mouse_button(50.0, 50.0, "RightButton", false);
     assert_eq!(s.eval::<i64>("return clicks").unwrap(), 0);
@@ -463,7 +415,6 @@ fn register_for_clicks_grows_right_click_and_carries_the_button_name() {
     assert_eq!(s.eval::<String>("return click_btn").unwrap(), "RightButton");
     assert_eq!(s.eval::<String>("return arg1_btn").unwrap(), "RightButton");
 
-    // RegisterForClicks replaces the set with its whole vararg list — LeftButtonUp still fires.
     s.mouse_button(50.0, 50.0, "LeftButton", true);
     s.mouse_button(50.0, 50.0, "LeftButton", false);
     assert_eq!(s.eval::<i64>("return clicks").unwrap(), 2);
@@ -489,14 +440,12 @@ fn down_registration_fires_on_press_and_toggles_checked_once() {
     .unwrap();
     s.resolve();
 
-    // The press alone fires OnClick (down=true) and toggles Checked exactly once.
     s.mouse_button(50.0, 50.0, "LeftButton", true);
     assert_eq!(s.eval::<i64>("return clicks").unwrap(), 1);
     assert!(s.eval::<bool>("return seen_down == true").unwrap());
     assert!(s.eval::<bool>("return QuickSell:GetChecked()").unwrap());
 
-    // The release does not fire again — "LeftButtonUp" is no longer in the registered set
-    // (RegisterForClicks replaced it, it did not add to it).
+    // `RegisterForClicks` replaced the set, so "LeftButtonUp" no longer fires.
     s.mouse_button(50.0, 50.0, "LeftButton", false);
     assert_eq!(s.eval::<i64>("return clicks").unwrap(), 1);
     assert!(s.errors().is_empty(), "{:?}", s.errors());
@@ -526,24 +475,20 @@ fn highlight_is_additive_and_state_textures_fill_then_anchor() {
             .find(|q| matches!(&q.content, QuadContent::Texture { path: Some(p), .. } if p == path))
             .expect(path)
     };
-    // The highlight carries the ADD contract (the client's SetHighlightTexture default).
+    // The 1.12 client's `SetHighlightTexture` defaults the texture to ADD.
     assert!(matches!(
         &find("Interface\\Hi.blp").content,
         QuadContent::Texture { additive: true, .. }
     ));
-    // A fresh state texture gets the creation-path implicit SetAllPoints (decision 1310 — the
-    // reference's string setters anchor a freshly built texture to the button outright), whose
-    // two corners pin all four edges: the later 64px size is structurally unread and the ring
-    // FILLS the 36px button.
+    // The reference's string setter anchors a texture it builds with `SetAllPoints`, so the later
+    // 64px size is unread and the ring fills the 36px button.
     let r = find("Interface\\Ring.blp").rect.unwrap();
     assert_eq!(
         (r.left, r.right, r.bottom, r.top),
         (100.0, 136.0, 100.0, 136.0)
     );
-    // The real quickslot-overhang idiom is an ANCHOR, not an anchorless size (ActionButton's
-    // 66×66 UI-Quickslot2 authors `<Anchor point="CENTER">`): one CENTER point replaces only its
-    // own slot, but clearing first leaves the single anchor + the 64px size → the centered
-    // overhang, 100..136 → 86..150.
+    // The quickslot overhang is an anchor (`ActionButtonTemplate.xml`'s 66x66 UI-Quickslot2 is
+    // `<Anchor point="CENTER">`): cleared, then one CENTER point and the 64px size give 86..150.
     s.run(
         r#"
         local n = AddBtn:GetNormalTexture()
@@ -563,7 +508,6 @@ fn highlight_is_additive_and_state_textures_fill_then_anchor() {
         (r.left, r.right, r.bottom, r.top),
         (86.0, 150.0, 86.0, 150.0)
     );
-    // SetBlendMode overrides back to straight alpha.
     s.run(r#"AddBtn:GetHighlightTexture():SetBlendMode("BLEND")"#)
         .unwrap();
     let quads = s.extract();
@@ -581,10 +525,8 @@ fn highlight_is_additive_and_state_textures_fill_then_anchor() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The per-state label fonts (`SetTextFontObject`/`SetDisabledFontObject`, XML `<NormalFont>` etc.):
-/// the ButtonText re-points to the CURRENT state's font object at extract — gold while enabled,
-/// gray after Disable() — with no Lua repaint (the client's UIPanelButtonTemplate label behavior).
-/// An explicit SetTextColor survives the re-point (the client's explicitly-set mask).
+/// The label wears the current state's font object (`SetTextFontObject`, `SetDisabledFontObject`)
+/// with no Lua repaint; its own `SetTextColor` clears the colour's inherit bit and survives that.
 #[test]
 fn button_label_repaints_by_state_font_object() {
     let mut s = script();
@@ -649,30 +591,16 @@ fn button_label_repaints_by_state_font_object() {
         "re-enabled: gold again"
     );
 
-    // An explicit SetTextColor wins over the state font's color (explicitly-set mask).
     s.run("b:GetFontString():SetTextColor(0.1, 0.2, 0.3)")
         .unwrap();
     let c = label_color(&mut s).expect("colored");
     assert!((c[0] - 0.1).abs() < 1e-6 && (c[1] - 0.2).abs() < 1e-6);
 }
 
-/// **The highlighted label is its own font instance — and `LockHighlight` enters it.** The two
-/// halves of the recipe-list look the director asked for: a row turns white under the cursor, and
-/// the SELECTED row stays white with the cursor elsewhere.
-///
-/// Both are one mechanism in the reference. `ClassTrainerSkillButtonTemplate` (the base under
-/// TradeSkill's, Craft's and the class trainer's rows) declares
-/// `<HighlightFont inherits="GameFontHighlight">`, and each window paints its rows by difficulty
-/// with `skillButton:SetTextColor(...)` — orange, yellow, green, gray. If a `SetTextColor` reached
-/// the highlighted state, hovering a row would leave it orange; it does not, because the highlight
-/// instance is a different font instance and the normal one's colour cannot reach it. That is the
-/// first assertion below.
-///
-/// The second is `LockHighlight`. `TradeSkillFrame_Update` blanks a recipe row's highlight texture
-/// (`getglobal("TradeSkillSkill"..i.."Highlight"):SetTexture("")`, Blizzard_TradeSkillUI.lua l.131)
-/// and *then* locks the row it selected (l.144) — with no texture left to pin, the lock can only be
-/// reaching the label. Craft (Blizzard_CraftUI.lua l.234) and the trainer
-/// (Blizzard_TrainerUI.lua l.183) do the same.
+/// The highlight label is its own font instance, put in force by a hover or `LockHighlight`, so the
+/// normal instance's `SetTextColor` cannot reach it: `ClassTrainerSkillButtonTemplate`'s recipe
+/// rows (`<HighlightFont inherits="GameFontHighlight">`) turn white, and
+/// `Blizzard_TradeSkillUI.lua:144` locks the selected row after blanking its highlight texture.
 #[test]
 fn a_locked_or_hovered_button_wears_its_highlight_font_over_its_normal_color() {
     let mut s = script();
@@ -737,7 +665,6 @@ fn a_locked_or_hovered_button_wears_its_highlight_font_over_its_normal_color() {
         "hovered: the HIGHLIGHT instance is in force, and the normal colour cannot reach it"
     );
 
-    // Cursor away again, but the row is the selected one.
     s.resolve();
     s.mouse_move(400.0, 300.0);
     s.run("b:LockHighlight()").unwrap();
@@ -753,8 +680,6 @@ fn a_locked_or_hovered_button_wears_its_highlight_font_over_its_normal_color() {
         "unlocked: back to the difficulty colour"
     );
 
-    // A button with no highlight instance keeps the normal one whole, hover or not — the shape
-    // every plain labelled Button in the corpus has.
     s.run(r#"b:SetHighlightFontObject(nil); b:SetText("Rough Copper Vest")"#)
         .unwrap();
     s.resolve();
@@ -767,14 +692,8 @@ fn a_locked_or_hovered_button_wears_its_highlight_font_over_its_normal_color() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **`Button:GetTextWidth` / `GetTextHeight`** — the reference's own Button text-extent readers
-/// (`0x782290` / `0x782390`; present on Button, and `GetStringWidth` **absent**). Both forward to
-/// the label FontString's own extent slots, which is what this asserts: answer a host measure for
-/// the label, and the BUTTON must report it.
-///
-/// `Bagnon_Forever/database/ui.lua:61` sizes its character-switch dropdown from
-/// `button:GetTextWidth() + 40`, so a nil method took the whole dropdown down — the director could
-/// not switch characters in Bagnon at all.
+/// `Button:GetTextWidth`/`GetTextHeight` (`0x782290`/`0x782390`; Button has no `GetStringWidth`)
+/// forward to the label FontString's extent.
 #[test]
 fn a_button_reports_its_labels_extent() {
     let mut s = script();
@@ -791,7 +710,7 @@ fn a_button_reports_its_labels_extent() {
     .unwrap();
     s.resolve();
 
-    // Unmeasured is 0 — the same "converges next frame" contract every other metric read has.
+    // 0 until the host's measure lands, like every metric read here.
     assert_eq!(
         s.eval::<f64>("return WidthBtn:GetTextWidth()").unwrap(),
         0.0
@@ -814,15 +733,13 @@ fn a_button_reports_its_labels_extent() {
         14.0
     );
 
-    // A Button with no label at all answers 0 rather than raising: the reference dereferences a
-    // FontString pointer (`+0x338`) here that a bare CreateFrame("Button") leaves null, and what it
-    // does then is not byte-read — so this takes the harmless number instead of guessing a crash.
+    // A label-less Button answers 0; the reference reads the label pointer (`+0x338`), null here,
+    // and what it does then is untraced.
     assert_eq!(
         s.eval::<f64>("return LabellessBtn:GetTextWidth()").unwrap(),
         0.0
     );
 
-    // …and it is a BUTTON method: a plain Frame must not have grown one.
     assert!(
         s.eval::<bool>(r#"return CreateFrame("Frame").GetTextWidth == nil"#)
             .unwrap(),
@@ -830,10 +747,8 @@ fn a_button_reports_its_labels_extent() {
     );
 }
 
-/// **`Button:SetFontString` adopts aggressively, and it RAISES** — `0x780a60`.
-///
-/// The first cut of this binding was a lenient no-op on a bad argument and a bare pointer swap on
-/// a good one. Every line below is a clause of that binding that the plausible reading got wrong.
+/// `Button:SetFontString` (`0x780a60`) re-parents the string, adopts it as the label and destroys
+/// the old one, and raises on anything but a FontString.
 #[test]
 fn set_font_string_adopts_the_label_and_raises_on_anything_else() {
     let mut s = crate::script::UiScript::new().unwrap();
@@ -848,28 +763,20 @@ fn set_font_string_adopts_the_label_and_raises_on_anything_else() {
     )
     .unwrap();
 
-    // Adoption binds the string as the label the whole rest of the surface reads.
     s.run("b:SetFontString(fs)").unwrap();
     assert!(s.eval::<bool>("return b:GetFontString() == fs").unwrap());
     s.run("b:SetText(\"Okay\")").unwrap();
     assert_eq!(s.eval::<String>("return fs:GetText()").unwrap(), "Okay");
     assert_eq!(s.eval::<String>("return b:GetText()").unwrap(), "Okay");
 
-    // Re-parented — always, whatever it was parented to before.
     assert!(s.eval::<bool>("return fs:GetParent() == b").unwrap());
-    // The draw layer is forced to ARTWORK on the same call (`0x77fd10(parent, 2, 1)`), and that
-    // half is NOT asserted here for a stated reason: `GetDrawLayer` is one of the client's nine
-    // per-leaf verbs we deliberately do not install (`script::REGION_LEAF_SHARED`'s own note —
-    // "absent is absent"), so there is no Lua way to read it back yet. The binding does it; when
-    // that verb lands, this is where it gets pinned.
+    // It also forces the draw layer to ARTWORK (`0x77fd10(parent, 2, 1)`); not asserted here.
 
-    // Adopting the SAME string again is a total no-op — the first compare in the client, and the
-    // one path that must not run the destroy below.
+    // The same string again is a no-op, the client's first compare, so it is not destroyed.
     s.run("b:SetFontString(fs)").unwrap();
     assert!(s.eval::<bool>("return b:GetFontString() == fs").unwrap());
     assert_eq!(s.eval::<String>("return fs:GetText()").unwrap(), "Okay");
 
-    // A SECOND adoption DESTROYS the first label rather than orphaning it.
     s.run("fs2 = b:CreateFontString(\"MyLabel2\", \"OVERLAY\") b:SetFontString(fs2)")
         .unwrap();
     assert!(s.eval::<bool>("return b:GetFontString() == fs2").unwrap());
@@ -879,8 +786,7 @@ fn set_font_string_adopts_the_label_and_raises_on_anything_else() {
         "the replaced label must be destroyed, not left live: {err}"
     );
 
-    // Three distinct raises, all naming the BUTTON — never a silent no-op, and `nil` cannot clear
-    // the label from Lua at all.
+    // Three distinct raises, each naming the button; `nil` cannot clear the label from Lua.
     for (call, want) in [
         ("b:SetFontString()", "Usage: Btn:SetFontString(fontstring)"),
         (
@@ -904,19 +810,16 @@ fn set_font_string_adopts_the_label_and_raises_on_anything_else() {
         let err = s.run(call).unwrap_err().to_string();
         assert!(err.contains(want), "`{call}` → {err}");
     }
-    // A TEXTURE is the near-miss the type gate exists for: it is a Region, and it still fails.
+    // A Texture is a Region and still fails the FontString type gate.
     s.run("tex = b:CreateTexture(nil, \"ARTWORK\")").unwrap();
     let err = s.run("b:SetFontString(tex)").unwrap_err().to_string();
     assert!(
         err.contains("Wrong object type, expected fontstring"),
         "{err}"
     );
-    // …and none of that changed the label.
     assert!(s.eval::<bool>("return b:GetFontString() == fs2").unwrap());
 }
 
-/// Adoption anchors the string **only when it has none of its own** — and leaves an already
-/// anchored one exactly where the caller put it.
 #[test]
 fn set_font_string_anchors_only_an_unanchored_label() {
     let mut s = crate::script::UiScript::new().unwrap();
@@ -946,7 +849,7 @@ fn set_font_string_anchors_only_an_unanchored_label() {
     );
     assert_eq!(s.eval::<i64>("return placed:GetNumPoints()").unwrap(), 1);
 
-    // The unanchored one gets the justify-derived point, to the matching point on the button.
+    // With no normal-font justify, the unanchored one is anchored CENTER to CENTER.
     s.run("b:SetFontString(bare)").unwrap();
     assert_eq!(s.eval::<i64>("return bare:GetNumPoints()").unwrap(), 1);
     let (p, _rel, rp, x, y): (String, mlua::Value, String, f64, f64) =
@@ -957,15 +860,10 @@ fn set_font_string_anchors_only_an_unanchored_label() {
     );
 }
 
-/// A label the button makes for itself (`SetText`'s lazy creator `0x778dc0`) or adopts
-/// (`SetFontString`) is anchored by the BUTTON's normal font justify, not by the fresh string's
-/// own ctor-default word: both funnel through `CSimpleButton::SetFontString 0x778d20`, whose
-/// unanchored-label leg reads `[button+0x390]` — the NORMAL embedded `CSimpleFont`'s justify —
-/// LEFT→LEFT / RIGHT→RIGHT / else CENTER, then links the label to that font (`0x779810`).
-/// Decision 1996.
-///
-/// `<NormalFont justifyH=>` is what writes that word in FrameXML (`UIMenuButtonTemplate`,
-/// `MailFrame.xml`'s RIGHT money button), so this is the chat menu's "Macro/macro" in miniature.
+/// A label made lazily (`SetText`, `0x778dc0`) or adopted goes through
+/// `CSimpleButton::SetFontString 0x778d20`, which anchors it by the button's normal font justify
+/// (`[button+0x390]`: LEFT, RIGHT, else CENTER), not the string's own, then links it to that font
+/// (`0x779810`). FrameXML writes that justify with `<NormalFont justifyH=>`.
 #[test]
 fn a_lazily_made_label_is_anchored_by_the_normal_fonts_justify() {
     let mut s = script();
@@ -1006,8 +904,8 @@ fn a_lazily_made_label_is_anchored_by_the_normal_fonts_justify() {
         "#,
     )
     .unwrap();
-    // `<NormalFont>` alone creates no label — the reference's LoadXML never touches `+0x338` on
-    // that leg — so `GetFontString()` is nil until something sets text.
+    // `<NormalFont>` alone creates no label (the reference's LoadXML leaves `+0x338` null), so
+    // `GetFontString()` is nil until text is set.
     assert!(s
         .eval::<bool>("return left:GetFontString() == nil")
         .unwrap());
@@ -1042,7 +940,6 @@ fn a_lazily_made_label_is_anchored_by_the_normal_fonts_justify() {
             1
         );
     }
-    // The link is applied on the spot: the label's own word and object answer the normal font's.
     assert_eq!(
         s.eval::<String>("return left:GetFontString():GetJustifyH()")
             .unwrap(),
@@ -1052,7 +949,6 @@ fn a_lazily_made_label_is_anchored_by_the_normal_fonts_justify() {
         .eval::<bool>("return left:GetFontString():GetFontObject() == ProbeFont")
         .unwrap());
 
-    // Adoption reads the same word: an unanchored string handed to the LEFT button seats LEFT.
     s.run(
         r#"
         bare = left:CreateFontString(nil, "OVERLAY")
@@ -1067,24 +963,14 @@ fn a_lazily_made_label_is_anchored_by_the_normal_fonts_justify() {
         "SetFontString anchors by the normal font's justify too"
     );
 
-    // A later `SetTextFontObject` re-links the normal font but does NOT re-anchor — the anchor
-    // was decided at adoption and is an ordinary anchor from then on.
+    // A later `SetTextFontObject` re-links the normal font but does not re-anchor.
     s.run("left:SetTextFontObject(ProbeFontRight)").unwrap();
     assert_eq!(point(&s, "left"), ("LEFT".into(), "LEFT".into(), 0.0, 0.0));
 }
 
-/// **A label that set its own face keeps it — the severance mask covers every axis, not three of
-/// six** (decision 2112).
-///
-/// `font_explicit` is the client's explicitly-set mask (`FONTINSTANCE+0x38`): an axis a widget
-/// writes for *itself* severs inheritance from the font instance it reads, and is never restored
-/// (see the `button_font` block in `script::extract`). `font::repaint` honours it on all seven
-/// axes. The extract's per-state re-point honoured it on shadow, colour and both justifies — and
-/// not on **face, height or outline**: the face and height read `fo.x.or(data.x)`, which makes the
-/// object outrank an explicit `SetFont`, and the outline was written unconditionally. A
-/// `<ButtonText>` that called `SetFont(path, h, "OUTLINE")` for itself therefore had all three
-/// silently put back from the button's font object on the very next extract — every frame, so no
-/// Lua could win the race.
+/// A label's own `SetFont` clears its font inherit bit (the reference's `FONTINSTANCE+0x2c`
+/// inherit mask, a FontString's `+0xd4`), and nothing sets it back, so its face, height and
+/// outline outlast every state font re-point while its other axes still inherit.
 #[test]
 fn a_button_labels_own_setfont_survives_the_state_font_repoint() {
     let mut s = script();
@@ -1134,7 +1020,6 @@ fn a_button_labels_own_setfont_survives_the_state_font_repoint() {
         ),
         "the label's own SetFont severs face, height AND outline from the state font object"
     );
-    // …and it survives a state change, which is what re-runs the re-point.
     s.run("b:Disable()").unwrap();
     assert_eq!(
         painted(&mut s),
@@ -1145,7 +1030,6 @@ fn a_button_labels_own_setfont_survives_the_state_font_repoint() {
         ),
         "…and a disable re-points the instance without restoring what the label severed"
     );
-    // The axes the label did NOT set still follow the object: the colour is the template's gold.
     s.resolve();
     let color = s
         .extract()
@@ -1166,21 +1050,9 @@ fn a_button_labels_own_setfont_survives_the_state_font_repoint() {
     );
 }
 
-/// **A state-texture setter takes an OBJECT and takes nil**, not only a path — the reference's
-/// `0x781970` forks on `lua_type(L, 2)` into four legs and benilla honoured one of them
-/// (decision 2124).
-///
-/// Both missing legs are silent no-ops rather than errors, which is why nothing caught them:
-///
-/// * **the object leg** (`0x781b0b` → `0x778fd0`) installs the handed Texture *into the slot*.
-///   Three corpus addons build a highlight this way and every one of them drew nothing —
-///   `Bongos/bar.lua:64-71`, `_Nameplates/_Nameplates.lua:217-222`,
-///   `Quiver/Quiver.bundle.lua:8949-8953`. The idiom below is Bongos', verbatim in shape.
-/// * **the nil leg** (`0x781b5a` → `0x778fd0` with 0) clears the slot and dtors what was in it.
-///   `TheoryCraft/TheoryCraftUI.lua:215-217` strips a talent-rank button with three of these.
-///   Clearing the *pointer* alone would be worse than the no-op: `region_visible` draws any region
-///   that is not one of the button's slots unconditionally, so a merely unhooked state texture
-///   would appear in every state instead of none — which is what this test's last assertion pins.
+/// A state-texture setter forks on `lua_type(L, 2)` (`0x781970`): a Texture object is installed
+/// into the slot (`0x781b0b` → `0x778fd0`), and nil clears the slot and destroys its texture
+/// (`0x781b5a`), which merely unhooked would draw in every state.
 #[test]
 fn a_state_texture_slot_takes_an_object_and_a_nil() {
     let mut s = script();
@@ -1210,8 +1082,6 @@ fn a_state_texture_slot_takes_an_object_and_a_nil() {
             .collect()
     };
 
-    // The handed object IS the slot now: it draws on hover and only on hover, exactly as a
-    // path-loaded highlight does.
     assert_eq!(drawn(&s), vec!["Interface\\N.blp".to_string()]);
     assert!(
         s.eval::<bool>("return b:GetHighlightTexture() == hl")
@@ -1228,7 +1098,6 @@ fn a_state_texture_slot_takes_an_object_and_a_nil() {
         ]
     );
 
-    // nil clears — and the cleared art is gone from every state, not merely unhooked.
     s.run("b:SetHighlightTexture(nil) b:SetNormalTexture(nil)")
         .unwrap();
     s.resolve();
@@ -1244,14 +1113,9 @@ fn a_state_texture_slot_takes_an_object_and_a_nil() {
     );
 }
 
-/// **The unlocked scripted push is released by the next mouse release — Tablet-2.0's rows**
-/// (decision 2134).
-///
-/// `SetButtonState(state[, lock])` writes `[+0x32c]` unconditionally, and the mouse-up edge
-/// `0x7793de` un-presses whenever `locked == 0`. Tablet-2.0 (`Tablet-2.0.lua:1645`) pushes a row it
-/// finds `clicked` and calls `SetButtonState("NORMAL")` *nowhere in the library* — it relies on
-/// exactly this. Ours kept a scripted push until Lua cleared it, so a Questie/FuBar/oRA2 row stayed
-/// depressed for the rest of the session.
+/// `SetButtonState(state[, lock])` always writes the lock (`[+0x32c]`), and the mouse-up edge
+/// (`0x7793de`) un-presses an unlocked button; `Tablet-2.0.lua:1645` pushes a row and never
+/// releases it itself.
 #[test]
 fn an_unlocked_scripted_push_is_released_by_the_next_mouse_release() {
     let mut s = script();
@@ -1273,7 +1137,6 @@ fn an_unlocked_scripted_push_is_released_by_the_next_mouse_release() {
         "PUSHED"
     );
 
-    // A press and release over the row: the release edge finds it PUSHED and unlocked.
     s.mouse_move(50.0, 50.0);
     s.mouse_button(50.0, 50.0, "LeftButton", true);
     s.mouse_button(50.0, 50.0, "LeftButton", false);
@@ -1286,13 +1149,8 @@ fn an_unlocked_scripted_push_is_released_by_the_next_mouse_release() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **`lock` pins the state against the mouse — the micro buttons** (`0x780270`'s third index,
-/// `GetBoolOrDefault` with default 0).
-///
-/// `MainMenuBarMicroButtons.lua` calls `SetButtonState("PUSHED", 1)` when its panel opens, and the
-/// button must stay depressed through every press and release until the panel closes. The same
-/// flag pins a NORMAL button *against* being pushed, which is the half a "sticky push" model
-/// cannot express at all.
+/// `SetButtonState`'s third argument (`0x780270`, default 0) locks the state against the mouse,
+/// PUSHED or NORMAL; `MainMenuBarMicroButtons.lua:22` holds a micro button PUSHED this way.
 #[test]
 fn a_locked_state_ignores_the_mouse_and_enable_disable_clears_the_lock() {
     let mut s = script();
@@ -1330,8 +1188,7 @@ fn a_locked_state_ignores_the_mouse_and_enable_disable_clears_the_lock() {
     );
     s.mouse_button(250.0, 50.0, "LeftButton", false);
 
-    // `0x779160` passes `locked = 0` on both arms, so Enable/Disable UNLOCK. The panel closing
-    // with a plain `SetButtonState("NORMAL")` (flag defaulting to 0) does the same.
+    // `0x779160` passes `locked = 0` on both arms, so Enable and Disable unlock.
     s.run("MicroButton:Disable() MicroButton:Enable()").unwrap();
     assert_eq!(
         s.eval::<String>("return MicroButton:GetButtonState()")
@@ -1351,14 +1208,9 @@ fn a_locked_state_ignores_the_mouse_and_enable_disable_clears_the_lock() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **Walking off a held button does NOT un-press it, and walking back on does not re-press it.**
-///
-/// The correction decision 2134 is built on. Our old model derived the press as
-/// `(held && hovered) || pushed_state` and re-evaluated it whenever the hover moved; the
-/// reference's enter and leave notifies (`0x779490`/`0x7794e0`) read `[+0x328]` only as a DISABLED
-/// guard and **never write it** — proved by a census of every store to the field image-wide.
-/// The only thing that un-presses a held button before its release is the drag-threshold crossing,
-/// and only for a frame that registered for drag.
+/// The enter and leave notifies (`0x779490`/`0x7794e0`) read the button state (`[+0x328]`) only as
+/// a DISABLED guard and never write it; before the release, only a drag-threshold crossing on a
+/// drag-registered frame un-presses a held button.
 #[test]
 fn the_hover_is_not_an_input_to_the_press_state() {
     let mut s = script();
@@ -1383,7 +1235,6 @@ fn the_hover_is_not_an_input_to_the_press_state() {
     s.mouse_button(50.0, 50.0, "LeftButton", true);
     assert!(shows(&s, "Interface\\HeldP.blp"), "the press pushed it");
 
-    // Walk the cursor right off it, still holding.
     s.mouse_move(500.0, 400.0);
     assert!(
         shows(&s, "Interface\\HeldP.blp"),
@@ -1395,7 +1246,7 @@ fn the_hover_is_not_an_input_to_the_press_state() {
         "PUSHED"
     );
 
-    // The release, off the button, still un-presses it — `0x7792d0` runs no hit test of its own.
+    // The release un-presses it off the button too: `0x7792d0` runs no hit test.
     s.mouse_button(500.0, 400.0, "LeftButton", false);
     assert!(
         shows(&s, "Interface\\HeldN.blp"),
@@ -1404,10 +1255,8 @@ fn the_hover_is_not_an_input_to_the_press_state() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **A button hidden while held comes back NORMAL** — `CSimpleButton`'s hide override
-/// (`+0x34` = `0x7791e0`), which un-presses and then tail-jumps the base notify so `<OnHide>`
-/// still fires. It hangs off the visibility transition, not off the hover, so it reaches a button
-/// hidden nowhere near the cursor too.
+/// `CSimpleButton`'s hide override (`+0x34` = `0x7791e0`) un-presses the button, then runs the
+/// base notify so `<OnHide>` still fires.
 #[test]
 fn hiding_a_held_button_un_presses_it() {
     let mut s = script();
@@ -1438,14 +1287,7 @@ fn hiding_a_held_button_un_presses_it() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// `Button:GetTextColor()` — **FOUR** values, r/g/b/a (`0x781100`, table `0x879d00`, argc 1,
-/// arity 4, kinds `(number,number,number,number)`). Three is the plausible wrong answer, and the
-/// shapes table flags the name `name-not-unique` because seven tables register it — this asserts
-/// the BUTTON one, on a Button, and its two inheritance legs.
-///
-/// Completeness rather than a live break: no corpus site has a Button receiver today (every
-/// measured `GetTextColor` is on a FontString or a font object). It is here because the reference
-/// registers it, so the widget shape gate can cover it from now on.
+/// `Button:GetTextColor()` returns four values, r, g, b, a (`0x781100`, table `0x879d00`).
 #[test]
 fn button_get_text_color_answers_four_values_through_the_state_font() {
     let s = script();
@@ -1479,8 +1321,7 @@ fn button_get_text_color_answers_four_values_through_the_state_font() {
         .unwrap();
     assert_eq!(kinds, "number,number,number,number");
 
-    // A button with nothing set anywhere is the untinted white every other colour getter here
-    // (`GetVertexColor`, `FontString:GetTextColor`) answers.
+    // Nothing set: the untinted white the other colour getters here answer.
     let plain: Vec<f32> = (1..=4)
         .map(|i| {
             let discards = "_, ".repeat(i - 1);
@@ -1492,8 +1333,7 @@ fn button_get_text_color_answers_four_values_through_the_state_font() {
         .collect();
     assert_eq!(plain, vec![1.0, 1.0, 1.0, 1.0]);
 
-    // With no local colour it reads THROUGH what the normal state inherits — the same leg
-    // `Button:GetFont` takes, and the one a stock `GameMenuButtonTemplate` button relies on.
+    // Unset locally, it reads through the normal state's font object, as `Button:GetFont` does.
     let themed: Vec<f32> = (1..=4)
         .map(|i| {
             let discards = "_, ".repeat(i - 1);
@@ -1505,7 +1345,6 @@ fn button_get_text_color_answers_four_values_through_the_state_font() {
         .collect();
     assert_eq!(themed, vec![1.0, 0.82, 0.0, 1.0]);
 
-    // A local SetTextColor wins, alpha included, and round-trips.
     s.run("ThemedBtn:SetTextColor(0.1, 0.2, 0.3, 0.4)").unwrap();
     let set: Vec<f32> = (1..=4)
         .map(|i| {
@@ -1518,7 +1357,7 @@ fn button_get_text_color_answers_four_values_through_the_state_font() {
         .collect();
     assert_eq!(set, vec![0.1, 0.2, 0.3, 0.4]);
 
-    // A CheckButton reaches it through Button's table, as it does the rest of the trio.
+    // A CheckButton reaches it through Button's table.
     s.run(r#"CreateFrame("CheckButton", "ChkColorBtn")"#)
         .unwrap();
     assert_eq!(s.arity("ChkColorBtn:GetTextColor()").unwrap(), 4);
diff --git a/crates/benilla-ui/src/script/tests/channel.rs b/crates/benilla-ui/src/script/tests/channel.rs
index 58affea1..1561afcd 100644
--- a/crates/benilla-ui/src/script/tests/channel.rs
+++ b/crates/benilla-ui/src/script/tests/channel.rs
@@ -1,22 +1,16 @@
-//! `GetChannelName` — the joined-channel lookup ([`crate::script::channel`]).
-//!
-//! The verb is small; the contract around it is not, and every test here is named after one claim.
-//! The load-bearing one is [`a_channel_that_is_not_joined_answers_the_number_zero_never_nil`]: the
-//! reference's own callers and the corpus both compare the first return numerically, so a nil there
-//! does not degrade — it raises, at four call sites that work today.
+//! The joined-channel verbs `GetChannelName` and `GetChannelList` ([`crate::script::channel`])
+//! and the guild-recruitment latch.
 
 use super::common::script;
 
-/// Two channels joined in order, the way `ui_chat::feed` mirrors them after the server's
-/// YOU_JOINED. Join ORDER is the whole numbering law, so the fixture is deliberately not sorted.
+/// Two channels in join order, which is the numbering; deliberately not sorted.
 fn joined() -> crate::script::UiScript {
     let mut s = script();
     s.set_joined_channels(vec![Some("World".into()), Some("Trade - City".into())]);
     s
 }
 
-/// **A joined channel answers its 1-based slot, its name, and an instanceID.** The slot is the
-/// position in JOIN order — not a DBC id, not an alphabetical rank.
+/// The slot is the 1-based position in join order, not a DBC id or an alphabetical rank.
 #[test]
 fn a_joined_channel_answers_its_slot_name_and_instance() {
     let s = joined();
@@ -29,9 +23,7 @@ fn a_joined_channel_answers_its_slot_name_and_instance() {
     );
 }
 
-/// **The name form resolves, case-insensitively, and yields the same slot as the index form.**
-/// Half the corpus sites look up by name (`GetChannelName("world")`, `GetChannelName("Trade -
-/// City")`), and `_LazyPig` passes `"world"` for a channel the server names `"World"`.
+/// Addons look up by name in any case: `_LazyPig` passes `"world"` for the server's `"World"`.
 #[test]
 fn the_name_form_resolves_case_insensitively_to_the_same_slot() {
     let s = joined();
@@ -49,16 +41,7 @@ fn the_name_form_resolves_case_insensitively_to_the_same_slot() {
     );
 }
 
-/// **Not joined ⇒ the NUMBER 0. Never nil.** This is the trap, and it is the only way this verb can
-/// break working code rather than merely fail to help it.
-///
-/// Verified from both sides. The reference compares it numerically at `ChatFrame.lua:2114`
-/// (`if ( channelNum > 0 )`) and `l.2232` (`if ( channelNum <= 0 ) then return end`); so does the
-/// corpus at `_LazyPig/LazyPig.lua:1996` (`if id > 0 then`). A nil first return turns every one of
-/// those into "attempt to compare nil with number" — a loud failure in code that works today.
-///
-/// Asserted by DOING the comparison, not by inspecting the type, because the comparison is the
-/// thing that must not raise.
+/// Stock callers compare the first return numerically (`ChatFrame.lua:2114`, `:2232`).
 #[test]
 fn a_channel_that_is_not_joined_answers_the_number_zero_never_nil() {
     let s = joined();
@@ -66,7 +49,6 @@ fn a_channel_that_is_not_joined_answers_the_number_zero_never_nil() {
     let id: i64 = s.eval("return GetChannelName('NoSuchChannel')").unwrap();
     assert_eq!(id, 0);
 
-    // The reference's own guard shape, run for real: it must evaluate, not raise.
     let guard: bool = s
         .eval("local id = GetChannelName('NoSuchChannel') return id > 0")
         .unwrap();
@@ -89,9 +71,7 @@ fn a_channel_that_is_not_joined_answers_the_number_zero_never_nil() {
     );
 }
 
-/// **A numeric STRING resolves as a number**, because `ChatFrame.lua:2113` hands one straight in:
-/// it `gsub`s `/1` down to `"1"` and calls `GetChannelName(channel)`. On the real client Lua's own
-/// coercion makes that work; ours must not treat it as a channel literally named "1".
+/// `ChatFrame.lua:2113` passes the `"1"` it cuts out of `/1`, which Lua coerces to a number.
 #[test]
 fn a_numeric_string_resolves_as_an_index_not_as_a_name() {
     let s = joined();
@@ -99,9 +79,7 @@ fn a_numeric_string_resolves_as_an_index_not_as_a_name() {
     assert_eq!(id, 2, "the `/2` slash-command path depends on this");
 }
 
-/// **Empty until the server confirms a join.** `ui_chat::feed` appends on the server's YOU_JOINED
-/// notice, never on the request, so a session that has asked and not been answered has no slots —
-/// and the verb must still answer 0 rather than raise on an empty list.
+/// `ui_chat::feed` appends on the server's YOU_JOINED notice, never on the request.
 #[test]
 fn nothing_is_joined_before_the_server_confirms_it() {
     let s = script();
@@ -109,30 +87,22 @@ fn nothing_is_joined_before_the_server_confirms_it() {
     assert_eq!(id, 0);
 }
 
-/// **`GetChannelList()` is a FLAT vararg of (slot, name) pairs in join order** — not a table, and
-/// not name-first.
-///
-/// No single reference address pins the shape; two independent consumers do, and the
-/// test asserts what each of them relies on. The reference's `FCFDropDown_LoadChannels` walks
-/// `for i=1, arg.n, 2` and reads `arg[i+1]` as the name, so the pair order is (slot, name) and the
-/// stride is 2. `ChatLog.lua:424` packs it with `{ GetChannelList() }` and tests
-/// `type(value) == "number"` to spot an id, so the values must interleave rather than nest.
+/// The shape its consumers pin: `FCFDropDown_LoadChannels` walks `for i=1, arg.n, 2` reading
+/// `arg[i+1]` as the name, and `ChatLog.lua:424` packs it and spots an id by `type == "number"`.
 #[test]
 fn get_channel_list_is_a_flat_slot_name_vararg_in_join_order() {
     let s = joined();
 
-    // Exactly two pairs for two joined channels — the arity `FCFDropDown_LoadChannels` steps over.
+    // Two pairs for two joined channels.
     assert_eq!(s.arity("GetChannelList()").unwrap(), 4);
 
-    // Pair order and join order, both at once: slot 1 is the FIRST joined, not the alphabetical
-    // first ("Trade - City" would sort ahead of "World").
+    // Slot 1 is the first joined; alphabetically "Trade - City" would come first.
     let (s1, n1, s2, n2) = s
         .eval::<(i64, String, i64, String)>("return GetChannelList()")
         .unwrap();
     assert_eq!((s1, n1.as_str()), (1, "World"));
     assert_eq!((s2, n2.as_str()), (2, "Trade - City"));
 
-    // ChatLog's own walk: packed, the odd entries are numbers and the even ones are names.
     assert!(s
         .eval::<bool>(
             "local t = { GetChannelList() } \
@@ -140,25 +110,16 @@ fn get_channel_list_is_a_flat_slot_name_vararg_in_join_order() {
         )
         .unwrap());
 
-    // The slot agrees with GetChannelName's, which is the point of sharing the numbering.
     assert!(s
         .eval::<bool>("local i = GetChannelName('Trade - City') return i == 2")
         .unwrap());
 
-    // No channels joined is ZERO returns, so `{ GetChannelList() }` is an empty table rather than
-    // a table of nils — every consumer above already handles that shape.
     let empty = crate::script::tests::common::script();
     assert_eq!(empty.arity("GetChannelList()").unwrap(), 0);
 }
 
-/// **The guild-recruitment latch boots at AUTO and round-trips as a NUMBER** (decision 2115).
-///
-/// `GetGuildRecruitmentMode 0x4a0040` is 23 bytes and one path — `fild` the int global,
-/// `lua_pushnumber`, `mov eax,1`, `ret` — so it has no nil leg at all, and
-/// `UIOptionsFrame_Load`'s `== 1` would read a nil as a silent "not auto". The boot value is 1
-/// from a `.data` initialiser (`raw 0x443608` = `01 00 00 00`), corroborated by
-/// `UIOptionsFrame_SetDefaults`'s `SetGuildRecruitmentMode(1)` and by all 33 `chat-cache.txt`
-/// files the reference client itself wrote in this repo's install.
+/// `GetGuildRecruitmentMode` (`0x4a0040`) always pushes its int global as a number; it boots at 1
+/// from a `.data` initialiser (`raw 0x443608`), the value `UIOptionsFrame_SetDefaults` sets.
 #[test]
 fn the_guild_recruitment_mode_boots_auto_and_answers_a_number() {
     let s = script();
@@ -177,28 +138,19 @@ fn the_guild_recruitment_mode_boots_auto_and_answers_a_number() {
     );
 }
 
-/// **The setter is shape A — it RAISES rather than swallowing a bad argument** (decision 2115).
-///
-/// `0x4a0060` gates on `lua_isnumber 0x6f34d0` (so a numeric STRING passes) and otherwise
-/// `luaL_error`s `Usage: SetGuildRecruitmentMode(mode)`; it then truncates toward zero through
-/// `__ftol 0x40a2b0` and range-gates `0 <= mode < 2`, raising
-/// `SetGuildRecruitmentMode: invalid mode` outside it. Most 1.12 numeric bindings swallow a nil
-/// as 0.0 — this one does not, and a client that guessed the common shape would turn an addon's
-/// own bug into silence.
-///
-/// Success pushes **0 values**, not nil.
+/// `0x4a0060` raises `Usage:` unless `lua_isnumber` (`0x6f34d0`), truncates through `__ftol`
+/// (`0x40a2b0`), and raises `invalid mode` outside `0 <= mode < 2`; success pushes no values.
 #[test]
 fn the_guild_recruitment_setter_gates_its_argument_the_way_the_reference_does() {
     let s = script();
 
-    // A numeric string is a number to `lua_isnumber`.
     s.run(r#"SetGuildRecruitmentMode("0")"#).unwrap();
     assert_eq!(
         s.eval::<f64>("return GetGuildRecruitmentMode()").unwrap(),
         0.0
     );
 
-    // Truncation toward zero, not rounding: 1.7 is a legal 1.
+    // 1.7 truncates to a legal 1.
     s.run("SetGuildRecruitmentMode(1.7)").unwrap();
     assert_eq!(
         s.eval::<f64>("return GetGuildRecruitmentMode()").unwrap(),
@@ -221,7 +173,7 @@ fn the_guild_recruitment_setter_gates_its_argument_the_way_the_reference_does()
         assert!(e.to_string().contains("invalid mode"), "{bad}: {e}");
     }
 
-    // …and none of the refused calls moved the latch.
+    // None of the refused calls moved the latch.
     assert_eq!(
         s.eval::<f64>("return GetGuildRecruitmentMode()").unwrap(),
         1.0
@@ -233,10 +185,8 @@ fn the_guild_recruitment_setter_gates_its_argument_the_way_the_reference_does()
     );
 }
 
-/// **The setter is not inert** (decision 2144). `0x49ea70` stores the latch and tail-jumps into
-/// the cascade `0x49ea90` on the new value alone — `Set(1)` raises the app's cue whether or not
-/// the value moved; `Set(0)` never does — and `0x4a00a4`/`0x4a00a9` fire `UPDATE_CHAT_WINDOWS`
-/// on every successful call, before any cascade fires it again.
+/// `0x49ea70` stores the latch and jumps into the cascade `0x49ea90` whenever the new value is 1,
+/// moved or not; `0x4a00a4`/`0x4a00a9` fire `UPDATE_CHAT_WINDOWS` on every successful call.
 #[test]
 fn the_setter_asks_for_the_cascade_on_one_and_fires_update_chat_windows() {
     let mut s = script();
@@ -251,8 +201,7 @@ fn the_setter_asks_for_the_cascade_on_one_and_fires_update_chat_windows() {
     .unwrap();
     assert!(!s.take_guild_recruitment_cascade(), "nothing asked yet");
 
-    // Boots at 1; a Set(1) that moves nothing still asks — the reference's store is
-    // unconditional and the jump reads only `ecx == 1`.
+    // Boots at 1; a Set(1) that moves nothing still asks for the cascade.
     s.run("SetGuildRecruitmentMode(1)").unwrap();
     assert!(s.take_guild_recruitment_cascade());
     assert!(!s.take_guild_recruitment_cascade(), "drained");
@@ -281,9 +230,8 @@ fn the_setter_asks_for_the_cascade_on_one_and_fires_update_chat_windows() {
     );
 }
 
-/// **A manual join or leave of `GuildRecruitment` forces the latch to 0** — `0x49ed3d`/
-/// `0x49ef8f`, `call 0x49ea70(0)`. A player gesture, so it dirties the file; and mode 0 is the
-/// latch alone, so it asks for no cascade.
+/// A manual join or leave of `GuildRecruitment` calls `0x49ea70(0)` (`0x49ed3d`, `0x49ef8f`): it
+/// dirties the file and, as mode 0, asks for no cascade.
 #[test]
 fn a_manual_guild_recruitment_verb_resets_the_latch() {
     let mut s = script();
diff --git a/crates/benilla-ui/src/script/tests/cooldown.rs b/crates/benilla-ui/src/script/tests/cooldown.rs
index be3003b5..b2581398 100644
--- a/crates/benilla-ui/src/script/tests/cooldown.rs
+++ b/crates/benilla-ui/src/script/tests/cooldown.rs
@@ -1,17 +1,14 @@
-//! The cooldown **bindings**: the per-action dynamic-state read API and the `GetTime`-space
-//! cooldown triples the stock `Cooldown.lua` machine consumes (the widget itself is the
-//! reference's own `<Model>` since decision 2019 — `tests::model_clock` runs that file verbatim).
+//! The cooldown bindings: per-action state and the `GetTime`-space triples stock `Cooldown.lua`
+//! consumes (its `<Model>` widget runs in `tests::model_clock`).
 
 use super::common::script;
 use crate::script::*;
 
-/// The per-action dynamic-state API: the 1/nil conventions, IsActionInRange's tri-state, and
-/// GetActionCooldown's GetTime-space triple that goes cold at expiry.
+/// The 1/nil conventions, `IsActionInRange`'s tri-state, and a cooldown that goes cold at expiry.
 #[test]
 fn action_state_bindings_answer_the_reference_conventions() {
     let mut s = script();
 
-    // No state pushed: everything nil / cold.
     assert!(s.eval::<bool>("return IsUsableAction(3) == nil").unwrap());
     assert!(s.eval::<bool>("return IsActionInRange(3) == nil").unwrap());
     assert!(s
@@ -35,7 +32,6 @@ fn action_state_bindings_answer_the_reference_conventions() {
         }),
     );
 
-    // The 1/nil pairs, exactly as the transcribed `if` reads them.
     assert!(s
         .eval::<bool>("local u, oom = IsUsableAction(3); return u == nil and oom == 1")
         .unwrap());
@@ -45,8 +41,7 @@ fn action_state_bindings_answer_the_reference_conventions() {
     assert!(s
         .eval::<bool>("return IsAutoRepeatAction(3) == nil")
         .unwrap());
-    // IsConsumableAction reads the SLOT, not this map (decision 1301) — it is a pure query over
-    // the item template, so it arrives with the icon it gates the count beside.
+    // `IsConsumableAction` reads the slot, not this state: it arrives with the icon.
     assert!(s
         .eval::<bool>("return IsConsumableAction(3) == nil")
         .unwrap());
@@ -62,7 +57,6 @@ fn action_state_bindings_answer_the_reference_conventions() {
     );
     assert!(s.eval::<bool>("return IsConsumableAction(3) == 1").unwrap());
 
-    // GetActionCooldown: the pushed absolute start, verbatim in seconds.
     assert!(s
         .eval::<bool>(
             "local st, d, e = GetActionCooldown(3); \
@@ -70,9 +64,8 @@ fn action_state_bindings_answer_the_reference_conventions() {
         )
         .unwrap());
 
-    // 5 s later the same stored pair still answers (4 s window has 0 left → but 100+? no: it
-    // expires at start+10 = now+4) …after the remaining 4 s pass, the read goes cold — the
-    // stale-refeed guard (a re-fed finished pair must not replay the sweep/flash).
+    // It ends at 94 + 10 = 104: live at 103.9 and cold after, so a re-fed finished pair cannot
+    // replay the sweep.
     s.tick(3.9);
     assert!(s
         .eval::<bool>("local st, d = GetActionCooldown(3); return d == 10")
@@ -82,7 +75,7 @@ fn action_state_bindings_answer_the_reference_conventions() {
         .eval::<bool>("local st, d, e = GetActionCooldown(3); return st == 0 and d == 0 and e == 1")
         .unwrap());
 
-    // An on-hold (enable == 0) cooldown never goes cold on its own — parked until the event.
+    // An on-hold cooldown (enable 0) never goes cold on its own; it waits for the event.
     s.set_action_state(
         3,
         Some(ActionState {
@@ -95,17 +88,12 @@ fn action_state_bindings_answer_the_reference_conventions() {
         .eval::<bool>("local st, d, e = GetActionCooldown(3); return d == 30 and e == 0")
         .unwrap());
 
-    // Clearing the state clears the reads.
     s.set_action_state(3, None);
     assert!(s.eval::<bool>("return IsCurrentAction(3) == nil").unwrap());
 }
 
-/// The absolute-start triple is the anchor — both director regressions pin here. Reset-on-kill
-/// ("the cooldown indicator resets when you kill a mob"): an unrelated field flip re-pushes the
-/// same running cooldown, whose triple carries the SAME start, so the sweep holds. The vanished
-/// GCD pie ("spamming Rend during Charge never shows the pie"): a fail-clear + re-arm between
-/// feeds pushes a triple with a NEW start — under the old `(remaining, duration)` shape the two
-/// arms read byte-identical and the seam kept the first, long-elapsed anchor.
+/// The absolute start anchors the sweep: re-pushing a running cooldown (a kill flipping `usable`)
+/// keeps it, so the sweep does not reset, and a re-arm moves it even at the same duration.
 #[test]
 fn the_absolute_start_triple_holds_the_anchor_and_a_rearm_moves_it() {
     let mut s = script();
@@ -120,8 +108,6 @@ fn the_absolute_start_triple_holds_the_anchor_and_a_rearm_moves_it() {
         .eval::<bool>("local st = GetActionCooldown(3); return math.abs(st - 100) < 1e-3")
         .unwrap());
 
-    // 8 s later the kill drops combat and `usable` flips; the re-push carries the same start.
-    // The anchor holds at 100 — the sweep never restarts (the reset-on-kill invariant).
     s.tick(8.0);
     s.set_action_state(3, Some(cooling(true)));
     assert!(s
@@ -131,8 +117,6 @@ fn the_absolute_start_triple_holds_the_anchor_and_a_rearm_moves_it() {
         )
         .unwrap());
 
-    // A RE-ARM carries a fresh start and moves the anchor — even with the same duration (the
-    // vanished-pie shape: same spell, same 15 s, armed again at t=107).
     s.set_action_state(
         3,
         Some(ActionState {
@@ -145,8 +129,6 @@ fn the_absolute_start_triple_holds_the_anchor_and_a_rearm_moves_it() {
         .unwrap());
 }
 
-/// The same absolute-start law on the other two converters: the stance bar's form cooldown and
-/// the bag slot's item cooldown hold their anchors across unchanged re-pushes.
 #[test]
 fn shapeshift_and_container_cooldowns_keep_their_anchors_too() {
     let mut s = script();
@@ -177,7 +159,7 @@ fn shapeshift_and_container_cooldowns_keep_their_anchors_too() {
         .eval::<bool>("local st = GetContainerItemCooldown(0, 1); return math.abs(st - 50) < 1e-3")
         .unwrap());
 
-    // Re-push both with the SAME raw triples 5 s later: the anchors hold at 50.
+    // The same triples re-pushed 5 s later: the anchors hold at 50.
     s.tick(5.0);
     s.set_shapeshift_forms(vec![form()]);
     s.set_container(0, Some(bag()));
diff --git a/crates/benilla-ui/src/script/tests/create_frame_template.rs b/crates/benilla-ui/src/script/tests/create_frame_template.rs
index dd88ca2d..15b954e4 100644
--- a/crates/benilla-ui/src/script/tests/create_frame_template.rs
+++ b/crates/benilla-ui/src/script/tests/create_frame_template.rs
@@ -1,20 +1,10 @@
-//! `CreateFrame(kind, name, parent, inherits)` — the **runtime** template path
-//! ([`crate::loader::apply_template`]).
-//!
-//! `local b = CreateFrame("Button", "MyButton", UIParent, "UIPanelButtonTemplate")` is the single
-//! most common line in the addon corpus, and until the loader's post-`CreateFrame` steps were
-//! factored into `Loader::decorate` the fourth argument was dropped on the floor: the addon got a
-//! bare frame with no art, no regions, no scripts, and a warning on a channel it never reads.
-//!
-//! The load-bearing property every test here turns on is that **the caller's own name wins** — a
-//! template instantiated as `Mine` publishes `MineTexture`, never `ThatTemplateTexture`, because
-//! `getglobal("MineTexture")` is what the addon's next line calls.
+//! The runtime template path, `CreateFrame`'s fourth argument ([`crate::loader::apply_template`]),
+//! and `<ScrollChild>`. The caller's name wins: a template made as `Mine` publishes `MineTexture`.
 
 use super::common::script;
 use crate::script::UiScript;
 
-/// Register templates by loading a small FrameXML document — the same door an addon's own `.xml`
-/// comes through, so nothing here is a test-only shortcut into the registry.
+/// Registers templates by loading a FrameXML document, the path an addon's own `.xml` takes.
 fn register(s: &UiScript, xml: &str) {
     let doc = crate::framexml::parse(xml).expect("valid FrameXML");
     let report = crate::loader::load(s, &doc, &|_| None);
@@ -25,9 +15,6 @@ fn register(s: &UiScript, xml: &str) {
     );
 }
 
-/// The whole shape at once: a virtual template's `<Size>`, `<Anchors>`, `<Layers>` texture and
-/// `<Scripts><OnLoad>` all reach a frame built by `CreateFrame`'s fourth argument — and the region
-/// is named against **the instance**, not the template.
 #[test]
 fn a_runtime_template_brings_size_anchors_regions_and_a_fired_onload() {
     let mut s = script();
@@ -65,8 +52,8 @@ fn a_runtime_template_brings_size_anchors_regions_and_a_fired_onload() {
         "the template's <Size>"
     );
 
-    // The template's own <Anchors> substitute `$parent` against the frame's PARENT (`0x76c5b0`) —
-    // the instance's enclosing frame, not the instance itself.
+    // A template's `$parent` in `<Anchors>` is the frame's first named ancestor, not the frame
+    // (`0x76c5b0`).
     let (point, rel, rel_point, x, y): (String, String, String, f32, f32) = s
         .eval(
             "local p, r, rp, ox, oy = Mine:GetPoint(1) \
@@ -78,8 +65,6 @@ fn a_runtime_template_brings_size_anchors_regions_and_a_fired_onload() {
         ("TOPLEFT", "Host", "BOTTOMLEFT", 7.0, -3.0)
     );
 
-    // The region carries the INSTANCE's name. This is the whole point: `MineTexture` is what an
-    // addon reaches for, and `ProbeTemplateTexture` would be useless to it.
     assert!(
         s.eval::<bool>(r#"return getglobal("MineTexture") ~= nil"#)
             .unwrap(),
@@ -91,8 +76,7 @@ fn a_runtime_template_brings_size_anchors_regions_and_a_fired_onload() {
         "nothing may be named after the template"
     );
 
-    // OnLoad fired inside CreateFrame, after the frame was decorated — the reference's ordering,
-    // and what `local f = CreateFrame(...); f:Foo()` on the next line assumes.
+    // The reference fires OnLoad inside `CreateFrame`, after the template is applied.
     assert_eq!(s.eval::<String>("return ProbeLoadedAs").unwrap(), "Mine");
     assert_eq!(s.eval::<f32>("return ProbeLoadWidth").unwrap(), 160.0);
 
@@ -100,8 +84,7 @@ fn a_runtime_template_brings_size_anchors_regions_and_a_fired_onload() {
     assert!(s.take_warnings().is_empty());
 }
 
-/// A template's nested `<Frames>` child is named against the caller too, and is really parented to
-/// the new frame — the `$parent` chain composes through `CreateFrame` exactly as through XML.
+/// A nested child is parented to the new frame, and `$parent` composes as it does through XML.
 #[test]
 fn a_nested_frames_child_is_named_against_the_caller() {
     let mut s = script();
@@ -146,15 +129,8 @@ fn a_nested_frames_child_is_named_against_the_caller() {
     assert!(s.take_warnings().is_empty());
 }
 
-/// The template argument is **one name**, on this path exactly as on the XML one — and a chain
-/// through a single name still resolves.
-///
-/// This asserted the opposite until the registry lookup was read at the bytes. `"TemplA, TemplB"`
-/// is not a list, it is a literal name nothing declared: 1.12's `CreateFrame` reaches the same
-/// `0x6ee6f0` the XML loader does (call site `0x7061dd`) with the string Lua handed it, and the
-/// loader has no splitter anywhere — comma lists are a **later**-client feature. Corroborated by
-/// the corpus: 6842 `inherits=` across 282 vanilla XML files contain **zero** comma lists, while
-/// the modern Blizzard UI source is full of them.
+/// The template argument is one name: 1.12's `CreateFrame` hands the string to the XML loader's
+/// lookup (`0x6ee6f0`, called at `0x7061dd`), which has no splitter; comma lists came later.
 #[test]
 fn a_comma_list_is_one_name_and_a_single_name_still_chains() {
     let mut s = script();
@@ -175,8 +151,6 @@ fn a_comma_list_is_one_name_and_a_single_name_still_chains() {
            </Ui>"#,
     );
 
-    // A single name still walks its whole chain. This is what keeps the narrowing honest: it
-    // removes the list, not the inheritance.
     s.run(r#"One = CreateFrame("Frame", "One", nil, "TemplA")"#)
         .unwrap();
     assert_eq!(
@@ -188,8 +162,6 @@ fn a_comma_list_is_one_name_and_a_single_name_still_chains() {
     assert!(s.take_errors().is_empty());
     assert!(s.take_warnings().is_empty());
 
-    // The comma form is one literal name, nothing declared it, so it RAISES — naming the whole
-    // unsplit string, which is the proof it was never split.
     let err = s
         .run(r#"Both = CreateFrame("Frame", "Both", nil, "TemplA, TemplB")"#)
         .expect_err("a comma list is one name, and it misses");
@@ -205,12 +177,8 @@ fn a_comma_list_is_one_name_and_a_single_name_still_chains() {
     );
 }
 
-/// The case fold, with the four names the corpus actually mis-cases.
-///
-/// The compare is `SStrCmpI` → `_strnicmp`, and the trap that decides it is the bucket hash:
-/// `SStrHash 0x64b3f0` uppercases before mixing, so a mis-cased name lands in the same bucket and
-/// the stored-hash pre-check passes rather than short-circuiting. ASCII-only, like every other fold
-/// in this engine.
+/// The lookup folds ASCII case: `SStrHash` (`0x64b3f0`) uppercases before hashing, so a mis-cased
+/// name lands in the same bucket, and the compare is `SStrCmpI`.
 #[test]
 fn a_template_name_is_matched_case_insensitively() {
     let mut s = script();
@@ -222,7 +190,7 @@ fn a_template_name_is_matched_case_insensitively() {
              </Frame>
            </Ui>"#,
     );
-    // Exactly the shape `CT_RaidAssist/CT_RAOptions.xml` ships: `RA` written `Ra`.
+    // The mis-casing `CT_RaidAssist/CT_RAOptions.xml` ships: `RA` written `Ra`.
     s.run(r#"Cased = CreateFrame("Frame", "Cased", nil, "CT_RaCheckButtonTemplate")"#)
         .unwrap();
     assert_eq!(
@@ -234,21 +202,9 @@ fn a_template_name_is_matched_case_insensitively() {
     assert!(s.take_warnings().is_empty());
 }
 
-/// An unresolvable template name **raises, and creates nothing**.
-///
-/// This test asserted the exact opposite — *"the reference creates the frame anyway, and an addon's
-/// next line already assumes it did"* — until the bytes were read. `0x7061dd` looks the name up and
-/// on NULL falls into `luaL_error(L, "CreateFrame(): Couldn't find inherited node \"%s\"")`, which
-/// **never returns**: `luaG_errormsg` and `luaD_throw` contain no `ret` between them and end in
-/// `longjmp`, so the `xor eax,eax; ret` that follows the call is dead code. (That trailing `ret` is
-/// a fact about `luaL_error`'s `int` return type in C, not about reachability — which is exactly
-/// how the old claim was arrived at.)
-///
-/// Both flavours of "unusable" raise, because the registry only ever holds `virtual="true"`
-/// elements, so a name declared without it misses the lookup identically to a name nothing declared.
-///
-/// The ordering is asserted too: the miss precedes construction and name publication (`0x706208` /
-/// `0x70622d`), so nothing partial is left behind — no frame, and no global.
+/// A template name that misses the lookup raises at `0x7061dd`, before the frame is built or its
+/// name published (`0x706208`, `0x70622d`). The registry holds only `virtual="true"` elements, so
+/// a non-virtual name misses like an undeclared one.
 #[test]
 fn an_unresolvable_template_raises_and_creates_nothing() {
     let s = script();
@@ -266,7 +222,6 @@ fn an_unresolvable_template_raises_and_creates_nothing() {
             "the raise must carry the reference's message and the name: {text}"
         );
 
-        // Nothing partial: no global published, and the name never reached the arena.
         assert!(
             s.eval::<bool>(&format!(r#"return getglobal("{frame}") == nil"#))
                 .unwrap(),
@@ -274,9 +229,7 @@ fn an_unresolvable_template_raises_and_creates_nothing() {
         );
     }
 
-    // And it is ordinary Lua propagation — `pcall` catches it, which is what keeps one bad
-    // CreateFrame inside a handler from taking the client down (the widget dispatcher runs every
-    // handler under `lua_pcall`).
+    // An ordinary Lua error: `pcall` catches it, as the widget dispatcher's `lua_pcall` does.
     assert!(
         !s.eval::<bool>(
             r#"return (pcall(CreateFrame, "Button", "Caught", nil, "NoSuchTemplate"))"#
@@ -286,15 +239,8 @@ fn an_unresolvable_template_raises_and_creates_nothing() {
     );
 }
 
-/// The two shape mismatches, neither of which may panic or drop the frame.
-///
-/// A **region** template (a virtual `<Texture>`) asked for as a frame: its frame-shaped content
-/// still lands, its region-only content cannot, and the message says which.
-///
-/// A **kind that disagrees with the template's tag**: the frame keeps the kind `CreateFrame` was
-/// given — no template can retype a frame that already exists — so the `<Button>`-only parts of a
-/// Button template simply do not apply to a Frame, and, crucially, are not *attempted* (calling
-/// `SetNormalTexture` on a plain Frame would be an error, not a warning).
+/// A region template on a frame applies its frame-shaped content and warns; a template whose tag
+/// disagrees with the kind keeps the kind, and its tag-only parts are skipped, not attempted.
 #[test]
 fn a_region_template_or_a_mismatched_kind_is_named_never_fatal() {
     let mut s = script();
@@ -355,7 +301,7 @@ fn a_region_template_or_a_mismatched_kind_is_named_never_fatal() {
         "the Button-only steps are SKIPPED, not attempted and failed"
     );
 
-    // 3 · the same template, asked for as the kind it was written as — the control.
+    // 3 · the control: the same template, asked for as the kind it was written as.
     s.run(r#"AsButton = CreateFrame("Button", "AsButton", nil, "ProbeButtonTemplate")"#)
         .unwrap();
     assert_eq!(s.eval::<f32>("return AsButton:GetWidth()").unwrap(), 90.0);
@@ -371,13 +317,8 @@ fn a_region_template_or_a_mismatched_kind_is_named_never_fatal() {
     );
 }
 
-/// **`<ScrollChild>` gives a ScrollFrame its range** — the loader element that was missing, and
-/// the whole remaining distance for an addon's scrolling list (decision 1205).
-///
-/// The single child is instantiated via the same `0x6ee280` path `<Frames>` uses, then stored as
-/// the scroll child. Without it a `ScrollFrame` has nothing to pan, so `GetVerticalScrollRange()`
-/// is 0, `SetVerticalScroll` clamps to 0, and `OnVerticalScroll` fires with 0 forever — the list
-/// never moves and nothing errors, which is why no instrument could see it.
+/// `<ScrollChild>` builds its one child through the `<Frames>` path (`0x6ee280`) and stores it as
+/// the scroll child, which gives the frame its range.
 #[test]
 fn a_scroll_child_element_gives_the_frame_a_real_scroll_range() {
     let mut s = script();
@@ -398,19 +339,18 @@ fn a_scroll_child_element_gives_the_frame_a_real_scroll_range() {
     );
     s.resolve();
 
-    // The child exists, is named against the FRAME (`$parent` `0x76c5b0`), and is the scroll child.
+    // `$parent` names the child against the scroll frame (`0x76c5b0`).
     assert!(s.eval::<bool>("return RollerChild ~= nil").unwrap());
     assert!(s
         .eval::<bool>("return Roller:GetScrollChild() == RollerChild")
         .unwrap());
-    // ...and the range is the overhang: a 400-tall child in a 100-tall window scrolls 300.
+    // The range is the overhang: a 400-tall child in a 100-tall window scrolls 300.
     assert_eq!(
         s.eval::<f64>("return Roller:GetVerticalScrollRange()")
             .unwrap(),
         300.0,
         "no child means range 0, which is the silent failure this element fixes"
     );
-    // The scroll actually takes, rather than clamping to zero.
     s.run("Roller:SetVerticalScroll(120)").unwrap();
     assert_eq!(
         s.eval::<f64>("return Roller:GetVerticalScroll()").unwrap(),
@@ -419,14 +359,9 @@ fn a_scroll_child_element_gives_the_frame_a_real_scroll_range() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **The scroll range is the child's SUBTREE, not the child frame's own height** (decision 1338:
-/// `0x786e30` seeds a bbox and walks `0x786f80` recursively over the child's region and child-frame
-/// lists).
-///
-/// The geometry is the reference reader's own: `ItemTextPageScrollChild` is declared **10×10**
-/// around a 270×304 page. Measured as the child's height that is range 0 — a book that cannot be
-/// scrolled — which is exactly what shipped before this. The second assertion is the mutation
-/// check welded in: it is the number the old law returned.
+/// The scroll range is the child's whole subtree, not its own height: `0x786e30` seeds a box and
+/// `0x786f80` walks the child's regions and child frames. The shape is `ItemTextPageScrollChild`,
+/// 10×10 around a 270×304 page (`ItemTextFrame.xml:198`).
 #[test]
 fn the_scroll_range_is_the_childs_whole_subtree() {
     let mut s = script();
@@ -459,16 +394,13 @@ fn the_scroll_range_is_the_childs_whole_subtree() {
         204.0,
         "the 304-tall page inside the 10-tall child, less the 100-tall window"
     );
-    // The mutation check: under the old law the child's own 10 never reaches the window's 100, so
-    // the range clamps to zero and the reader's scrollbar has nowhere to go.
     assert_eq!(
         s.eval::<f64>("return ReaderChild:GetHeight()").unwrap(),
         10.0,
         "and the child itself really is the reference's 10 — the range does not come from it"
     );
 
-    // A hidden branch contributes nothing: the client guards both list walks on visibility, which
-    // is what stops a window's parked art from inventing travel nobody can use.
+    // A hidden branch adds nothing: the reference guards both list walks on visibility.
     s.run("Page:Hide()").unwrap();
     s.resolve();
     assert_eq!(
@@ -479,8 +411,7 @@ fn the_scroll_range_is_the_childs_whole_subtree() {
     );
 }
 
-/// An empty `<ScrollChild>` is an error (`0x786bc0`) — the reference's own behaviour, and the
-/// honest one: a ScrollFrame that declares a child and has none is a typo, not a design.
+/// The reference reports an empty `<ScrollChild>` as an error (`0x786bc0`) and keeps the frame.
 #[test]
 fn an_empty_scroll_child_is_reported() {
     let s = script();
@@ -497,6 +428,5 @@ fn an_empty_scroll_child_is_reported() {
         "errors: {:?}",
         report.errors
     );
-    // ...and the frame still exists — the client logs and carries on (decision 0068).
     assert!(s.eval::<bool>("return Hollow ~= nil").unwrap());
 }
diff --git a/crates/benilla-ui/src/script/tests/dispatch_bench.rs b/crates/benilla-ui/src/script/tests/dispatch_bench.rs
index b7234a3f..a4fcb08e 100644
--- a/crates/benilla-ui/src/script/tests/dispatch_bench.rs
+++ b/crates/benilla-ui/src/script/tests/dispatch_bench.rs
@@ -1,17 +1,5 @@
-//! **What one widget method lookup costs** — the bench behind the `__index` table (decision 2310).
-//!
-//! Every `frame:SetPoint(...)` in FrameXML and in every addon begins with a table index on the
-//! wrapper, which misses and falls to the metatable's `__index`. That path is on the hottest edge
-//! this engine has: Questie redraws its map notes with ~19 widget calls per cluster over hundreds
-//! of clusters, and a live sample of a quest-accept spike put **20 % of the whole UI tick** inside
-//! the metamethod dispatch alone — before any method body ran.
-//!
-//! The two rows below are the measurement that claim rests on, and the regression guard for it:
-//!
-//! - `miss` — `local m = f.NoSuchMethod`, the duck-type probe addons use (`if f.SetValue then`).
-//!   It is the WORST case: a dispatcher walks every registry in the kind chain and then the shared
-//!   table before answering nil.
-//! - `hit` — `local m = f.GetWidth`, the lookup every real call pays.
+//! What one widget method lookup through the wrapper's `__index` costs: every call pays a hit,
+//! and a miss (the duck-type probe `if f.SetValue then`) walks every registry in the kind chain.
 //!
 //! Run: `cargo test --release -p benilla-ui --lib -- --ignored --nocapture dispatch_bench`.
 
@@ -19,11 +7,10 @@ use std::time::Instant;
 
 use super::common::script;
 
-/// Lookups per timed loop — big enough that the loop's own overhead is a rounding error at the
-/// nanosecond scale these rows live at.
+/// Lookups per timed loop, enough that the loop's own overhead is noise at nanosecond scale.
 const N: usize = 400_000;
 
-/// Timed repeats per row; the reported number is the fastest (see [`dispatch_bench`]'s `floor`).
+/// Timed repeats per row; each row reports the fastest.
 const ROUNDS: usize = 5;
 
 fn ns_per(t: Instant, n: usize) -> f64 {
@@ -44,12 +31,7 @@ fn dispatch_bench() {
     )
     .expect("fixtures");
 
-    // A plain Lua table with a table `__index` — the floor this path could reach, and what the
-    // reference client's flat `{name, lua_CFunction}` probe costs in C.
-    // **The MINIMUM of [`ROUNDS`] runs, never the mean.** This machine builds while it measures —
-    // another build on the same machine saturates ten cores — and a mean of a contended loop reads
-    // whatever else was running. The minimum is the closest thing to the uncontended cost that a
-    // shared machine can report, and it is what makes two rows of one run comparable at all.
+    // The minimum of `ROUNDS` runs: a mean would measure whatever else was running.
     let floor = |what: &str, chunk: &str| {
         let mut best = f64::INFINITY;
         for _ in 0..ROUNDS {
@@ -60,6 +42,7 @@ fn dispatch_bench() {
         println!("[dispatch] {what:>26}  {best:7.1} ns");
     };
 
+    // The floor: a plain table with a table `__index`, like the reference's flat C method probe.
     floor(
         "baseline (table meta)",
         &format!(
@@ -101,10 +84,8 @@ fn dispatch_bench() {
         &format!("for _ = 1, {N} do local m = S.GetWidth end"),
     );
 
-    // The whole call, not just the lookup — what an addon's `f:GetWidth()` actually costs, split
-    // so the two taxes are separable: `GetFrameLevel` is a frame-only binding and measures one
-    // Rust hop, while `GetWidth` is one of [`crate::script::region_map`]'s 19 shared names and
-    // pays a SECOND hop — the bridge re-enters Lua to call the per-side arm.
+    // Whole calls: `GetFrameLevel` is a frame-only binding (one Rust hop); `GetWidth` is one of
+    // `region_map`'s shared names, whose bridge re-enters Lua for the per-side arm.
     floor(
         "GetFrameLevel() call",
         &format!("for _ = 1, {N} do local l = F:GetFrameLevel() end"),
@@ -118,16 +99,8 @@ fn dispatch_bench() {
         &format!("for _ = 1, {N} do F:SetPoint(\"CENTER\", 0, 0) end"),
     );
 
-    // **The settle tax.** Every geometry GETTER (`GetWidth`, `GetHeight`, `GetLeft`, `GetPoint`,
-    // `GetCenter`) calls `layout_methods::settle`, i.e. a whole `resolve_layout`. The tier-1 epoch
-    // gate makes that free while nothing has moved — which is what the `GetWidth() call` row above
-    // measures — but ANY layout write in between reopens it, so the read-after-write idiom pays a
-    // resolve per read. That idiom is not exotic: Astrolabe repositions a minimap icon with
-    // `GetWidth` → `ClearAllPoints` → `SetPoint`, per icon, and Questie places dozens.
-    //
-    // Here the model holds four frames, so a resolve is nearly free and the gap is the mechanism
-    // alone. In a live client the roster is thousands of frames and ten thousand anchored regions
-    // — the same gap, three orders of magnitude wider.
+    // Every geometry getter runs `layout_methods::settle`: free while nothing has moved, a whole
+    // `resolve_layout` after any layout write, so read-after-write pays one per read.
     floor(
         "write only",
         &format!("for i = 1, {N} do F:SetPoint(\"CENTER\", i, 0) end"),
@@ -143,12 +116,8 @@ fn dispatch_bench() {
         ),
     );
 
-    // **The control that says WHERE the bridged calls' extra microsecond goes.** `__direct` is one
-    // mlua closure; `__wrapped` is one mlua closure that calls another through `Function::call` —
-    // the exact shape `region_map`'s shared arm has. The gap between these two rows is what a
-    // re-entrant Lua call costs, and it is the number that decides whether those 19 names are worth
-    // restructuring into a single Rust body with an internal branch (the reference's own shape: one
-    // C function doing a virtual dispatch on the receiver).
+    // Controls: `__direct` is one mlua closure, `__wrapped` one that calls another through
+    // `Function::call` as `region_map`'s shared arm does; their gap is one re-entrant Lua call.
     {
         let lua = s.lua();
         let direct = lua
@@ -160,9 +129,7 @@ fn dispatch_bench() {
             .expect("wrapped fn");
         lua.globals().set("__wrapped", wrapped).expect("set");
 
-        // The same pair again in the SHAPE the bridge actually has: a variadic `MultiValue` whose
-        // first value is the receiver table. `Table` and `MultiValue` are the two conversions the
-        // scalar controls above leave out, and between them they are most of the gap.
+        // The same pair in the bridge's shape: a variadic `MultiValue` led by the receiver table.
         let mv_direct = lua
             .create_function(|_, args: mlua::MultiValue| Ok(args.len() as i64))
             .expect("mv direct");
diff --git a/crates/benilla-ui/src/script/tests/end_to_end.rs b/crates/benilla-ui/src/script/tests/end_to_end.rs
index b2d5ee21..566e7499 100644
--- a/crates/benilla-ui/src/script/tests/end_to_end.rs
+++ b/crates/benilla-ui/src/script/tests/end_to_end.rs
@@ -37,9 +37,8 @@ fn end_to_end_two_frame_tree_extracts_in_zkey_order() {
     s.resolve();
     let quads = s.extract();
 
-    // The renderable content, in painter order: parent's bg, child's bg, child's text — parent frame
-    // draws before child (earlier insertion, same strata/level), each frame's regions grouped behind
-    // it (order.rs ZKey).
+    // Painter order: the parent draws before the child (earlier insertion, same strata and level),
+    // each frame's regions with it.
     let content: Vec<String> = quads
         .iter()
         .filter_map(|q| match &q.content {
@@ -57,14 +56,13 @@ fn end_to_end_two_frame_tree_extracts_in_zkey_order() {
         ]
     );
 
-    // SetAllPoints resolves each region to its owner frame's rect. Parent → Rect(300,0,600,400);
-    // child (TOPLEFT+10,-10 of parent, 100×50) → Rect(540,10,590,110).
+    // `SetAllPoints` gives each region its frame's rect: the parent Rect(300, 0, 600, 400), the
+    // child (TOPLEFT +10, -10 of the parent, 100×50) Rect(540, 10, 590, 110).
     let child_text = quads
         .iter()
         .find(|q| matches!(&q.content, QuadContent::Text { text: Some(t), .. } if t == "Hello"))
         .unwrap();
     assert_eq!(child_text.rect, Some(Rect::new(540.0, 10.0, 590.0, 110.0)));
-    // The fontstring got a red vertex color via SetVertexColor(1,0,0,1).
     assert!(
         matches!(&child_text.content, QuadContent::Text { color: Some(c), .. } if *c == [1.0, 0.0, 0.0, 1.0])
     );
@@ -75,7 +73,6 @@ fn end_to_end_two_frame_tree_extracts_in_zkey_order() {
         .unwrap();
     assert_eq!(parent_bg.rect, Some(Rect::new(300.0, 0.0, 600.0, 400.0)));
 
-    // ZKey order is ascending and strictly increasing across the emitted list.
     let zs: Vec<u64> = quads.iter().map(|q| q.z).collect();
     let mut sorted = zs.clone();
     sorted.sort_unstable();
diff --git a/crates/benilla-ui/src/script/tests/events.rs b/crates/benilla-ui/src/script/tests/events.rs
index 7bceaff0..2a244eee 100644
--- a/crates/benilla-ui/src/script/tests/events.rs
+++ b/crates/benilla-ui/src/script/tests/events.rs
@@ -1,9 +1,5 @@
-//! RegisterEvent + fire_event via BOTH conventions (`0x704d50` / `0x704f10`).
-//!
-//! The handler's extra arguments are read through 5.0's implicit `arg` table, not `select(n, ...)`:
-//! `...` as a value is not in this VM's grammar (decision 2101), because it is not in the 1.12
-//! client's. The point of the test is unchanged — the same handler sees the legacy globals
-//! (`this`, `event`, `arg1`) AND the positional arguments.
+//! Event registration and dispatch (`0x704d50`, `0x704f10`). Handlers read varargs through Lua
+//! 5.0's implicit `arg` table: `...` is not a value in the 1.12 client's grammar.
 
 use super::common::script;
 use crate::script::*;
@@ -57,7 +53,7 @@ fn globals_are_restored_after_firing_nesting_safe() {
     )
     .unwrap();
     s.fire_event("E", vec![ScriptValue::Str("x".into())]);
-    // After firing, the prior global values must be restored (`0x704f10`'s set-then-restore).
+    // `0x704f10` sets the globals for the handler and restores the prior values after.
     let (t, e, a): (String, String, String) = s.eval("return this, event, arg1").unwrap();
     assert_eq!(
         (t.as_str(), e.as_str(), a.as_str()),
@@ -82,11 +78,8 @@ fn handler_errors_are_collected_not_panicked() {
     assert!(errs[0].contains("boom"), "{errs:?}");
 }
 
-/// The cross-frame dispatch ORDER law: the client's
-/// per-event listener list is tail-appended (`0x7052d0`) and walked head-first (`0x703e50`) —
-/// **FIFO: registration order = firing order**. Duplicate registration keeps the original
-/// position (`0x702264` dup ret); unregister+re-register moves to the tail. The ZoneText frames
-/// depend on this: both write PVPInfoTextString on one event — the last writer decides.
+/// Each event's listener list is tail-appended (`0x7052d0`) and walked head-first (`0x703e50`);
+/// a duplicate registration returns early (`0x702264`).
 #[test]
 fn events_fire_in_registration_order_fifo() {
     let mut s = script();
@@ -106,43 +99,26 @@ fn events_fire_in_registration_order_fifo() {
     s.fire_event("E", vec![]);
     assert_eq!(s.eval::<String>("return order").unwrap(), "ABC");
 
-    // Duplicate registration keeps A's position (the client's dup early-ret).
+    // A duplicate registration keeps A's position.
     s.run("FA:RegisterEvent('E'); order = ''").unwrap();
     s.fire_event("E", vec![]);
     assert_eq!(s.eval::<String>("return order").unwrap(), "ABC");
 
-    // Unregister + re-register moves B to the TAIL (the node is freed, the re-add appends).
+    // Unregistering frees B's node, so re-registering appends it at the tail.
     s.run("FB:UnregisterEvent('E'); FB:RegisterEvent('E'); order = ''")
         .unwrap();
     s.fire_event("E", vec![]);
     assert_eq!(s.eval::<String>("return order").unwrap(), "ACB");
 }
 
-/// **`HasScript` answers "can this widget CARRY that kind", not "does it have one set".**
-///
-/// That distinction is the verb's whole purpose, and every corpus caller depends on it: they ask
-/// before hooking, precisely when nothing is set yet.
-///
-/// ```lua
-/// if parent:HasScript("OnMouseDown") then          -- Tablet-2.0.lua:2409
-///     local script = parent:GetScript("OnMouseDown")
-///     parent:SetScript("OnMouseDown", function() … end)
-/// end
-/// ```
-///
-/// It was the top session-start blocker — 32 of 39 `attempt to call method` failures were this one
-/// name — and implementing it took survivors from 41 to 69.
-///
-/// The known over-permission is asserted too, so it is a recorded divergence rather than a
-/// discovery: our table is flat where the reference's is per widget type, so a plain Frame answers
-/// true for a Button-only kind. Exact for the base kinds, which is what the corpus asks about.
+/// Callers ask before hooking, when nothing is set yet (`Tablet-2.0.lua:2409`). Our kind table is
+/// flat where the reference's is per widget type, so a Frame also answers true for `OnClick`.
 #[test]
 fn has_script_reports_the_kind_is_supported_not_that_one_is_set() {
     let s = script();
     s.run(r#"f = CreateFrame("Frame", "HasScriptProbe")"#)
         .unwrap();
 
-    // True with NOTHING set — the case every caller is actually in.
     assert!(
         s.eval::<bool>(r#"return f:HasScript("OnMouseDown")"#)
             .unwrap(),
@@ -154,7 +130,7 @@ fn has_script_reports_the_kind_is_supported_not_that_one_is_set() {
         "an unknown kind is false, not true"
     );
 
-    // Tablet's exact idiom, run end to end: guard, read the (absent) handler, install one, fire it.
+    // Tablet's idiom, end to end.
     let fired: bool = s
         .eval(
             r#"
@@ -170,19 +146,15 @@ fn has_script_reports_the_kind_is_supported_not_that_one_is_set() {
         .unwrap();
     assert!(fired, "the guarded hook must install and run");
 
-    // The recorded divergence: flat table, so a Frame says true for a Button-only kind. The
-    // reference says false. Pinned so making SCRIPT_KINDS per-type has to come here and decide.
+    // The flat table: a Frame says true for a Button-only kind, where the reference says false.
     assert!(
         s.eval::<bool>(r#"return f:HasScript("OnClick")"#).unwrap(),
         "over-permissive by design today — see the comment at the binding"
     );
 }
 
-/// **The walk steps by a next saved BEFORE the handler runs** (`0x703ee8`; decision 1324): a
-/// handler that unregisters ITSELF mid-dispatch cannot rob its successor. This is AceEvent-2.0's
-/// fire-once idiom for `PLAYER_LOGIN`/`VARIABLES_LOADED` — its frame unregisters inside the
-/// handler, and the index-walk this replaces skipped whichever addon registered right after it
-/// (Bagnon_Forever's DB never initialized; the director's SaveBagData error dialogs).
+/// The walk saves the next node before the handler runs (`0x703ee8`); AceEvent-2.0's fire-once
+/// idiom unregisters inside its own handler.
 #[test]
 fn a_self_unregistering_handler_does_not_rob_its_successor() {
     let mut s = script();
@@ -208,15 +180,13 @@ fn a_self_unregistering_handler_does_not_rob_its_successor() {
         vec!["WalkA", "WalkB", "WalkC"],
         "the once-idiom's self-removal must not skip the next listener"
     );
-    // The removal held: a second fire reaches only A and C.
     s.fire_event("E", vec![]);
     let log: Vec<String> = s.eval("return log").unwrap();
     assert_eq!(log, vec!["WalkA", "WalkB", "WalkC", "WalkA", "WalkC"]);
 }
 
-/// A handler that unregisters the walk's SAVED next ends the dispatch there — the reference frees
-/// that node and walks into zeroed links (an accident we render as a deterministic stop) — while a
-/// frame registered mid-dispatch tail-appends and is still visited.
+/// Unregistering the walk's saved next ends the dispatch, as the reference frees that node and
+/// walks into its zeroed links; a frame registered mid-dispatch tail-appends and is still visited.
 #[test]
 fn mid_dispatch_removal_of_the_next_stops_and_append_is_visited() {
     let mut s = script();
@@ -271,16 +241,9 @@ fn mid_dispatch_removal_of_the_next_stops_and_append_is_visited() {
     );
 }
 
-/// `Frame:RegisterAllEvents()` — the frame's `OnEvent` receives every event dispatched
-/// (`0x774c20`, table `0x878ec0`, argc 1, arity 0), and `UnregisterAllEvents` clears that state
-/// along with the per-event ones.
-///
-/// **The clearing half is the load-bearing one.** AceEvent-2.0 — shipped by 63 vanilla addons and
-/// 6 of the top 20 — turns all-events on once (`AceEvent.frame:RegisterAllEvents()`), deliberately
-/// stops calling `frame:UnregisterEvent(event)` while it is on, and gets back to per-event
-/// registration by calling `frame:UnregisterAllEvents()` and then re-registering each event it
-/// still wants. A `RegisterAllEvents` that survived that call would leave every Ace2 addon on the
-/// whole event stream for the session.
+/// `RegisterAllEvents` (`0x774c20`, table `0x878ec0`, argc 1, arity 0) sends every event to the
+/// frame's `OnEvent`; `UnregisterAllEvents` clears it too, which is how AceEvent-2.0 gets back to
+/// per-event registration.
 #[test]
 fn register_all_events_takes_every_event_and_unregister_all_clears_it() {
     let mut s = script();
@@ -293,10 +256,8 @@ fn register_all_events_takes_every_event_and_unregister_all_clears_it() {
     )
     .unwrap();
 
-    // Arity 0 — the verb answers nothing.
     assert_eq!(s.arity("All:RegisterAllEvents()").unwrap(), 0);
 
-    // Anything dispatched now reaches it, including an event no name list could have enumerated.
     for ev in [
         "PLAYER_LOGIN",
         "UNIT_HEALTH",
@@ -314,9 +275,7 @@ fn register_all_events_takes_every_event_and_unregister_all_clears_it() {
         "SOME_SERVER_EVENT_NOBODY_LISTED"
     );
 
-    // Registering twice is a no-op, and a frame holding BOTH an all-events registration and a
-    // RegisterEvent for the same event is one listener, not two — the same rule `RegisterEvent`'s
-    // own `if not already in the list` holds one level down.
+    // All-events plus an explicit registration of the same event is still one listener.
     s.run(r#"seen = {}; All:RegisterAllEvents(); All:RegisterEvent("UNIT_HEALTH")"#)
         .unwrap();
     s.fire_event("UNIT_HEALTH", vec![]);
@@ -326,7 +285,7 @@ fn register_all_events_takes_every_event_and_unregister_all_clears_it() {
         "fired once, not twice"
     );
 
-    // UnregisterAllEvents clears BOTH: the explicit UNIT_HEALTH registration and the all-events one.
+    // UnregisterAllEvents clears both registrations.
     s.run("seen = {}; All:UnregisterAllEvents()").unwrap();
     for ev in ["UNIT_HEALTH", "PLAYER_LOGIN"] {
         s.fire_event(ev, vec![]);
@@ -337,7 +296,7 @@ fn register_all_events_takes_every_event_and_unregister_all_clears_it() {
         "the all-events registration does not outlive UnregisterAllEvents"
     );
 
-    // …and the AceEvent path back: re-register the individual events it still wants.
+    // AceEvent's way back: re-register the events it still wants.
     s.run(r#"All:RegisterEvent("UNIT_HEALTH")"#).unwrap();
     for ev in ["UNIT_HEALTH", "PLAYER_LOGIN"] {
         s.fire_event(ev, vec![]);
@@ -350,10 +309,6 @@ fn register_all_events_takes_every_event_and_unregister_all_clears_it() {
     assert!(s.take_errors().is_empty());
 }
 
-/// An all-events frame dispatches AFTER the event's own listeners — where it would sit if the
-/// registration were expanded into every per-event list, since it joined later than they did.
-/// Cross-frame order is a law consumers depend on (the two ZoneText frames writing one FontString);
-/// it does not stop being one because a listener asked for everything.
 #[test]
 fn an_all_events_listener_runs_after_the_events_own() {
     let mut s = script();
diff --git a/crates/benilla-ui/src/script/tests/font_object.rs b/crates/benilla-ui/src/script/tests/font_object.rs
index d71f8c56..695f5909 100644
--- a/crates/benilla-ui/src/script/tests/font_object.rs
+++ b/crates/benilla-ui/src/script/tests/font_object.rs
@@ -1,9 +1,5 @@
-//! Font objects as first-class Lua objects ([`crate::script::font`]).
-//!
-//! Every test here is driven **the way the 218-addon corpus drives it** — the bare-global argument,
-//! the no-arg `CreateFontString`, `CreateFont` — rather than the way our own shipped XML does,
-//! because the string-name form our XML uses was the only one we accepted and it is the form
-//! almost nobody writes (6 corpus sites against 3,180).
+//! Font objects as first-class Lua objects ([`crate::script::font`]), driven as addons drive them:
+//! the bare global, the no-argument `CreateFontString`, `CreateFont`.
 
 use super::common::script;
 use crate::script::{FontObject, JustifyH, JustifyV, Outline, QuadContent, UiScript};
@@ -36,14 +32,8 @@ fn painted(s: &UiScript, text: &str) -> (Option<String>, Option<f32>, Option<[f3
         .unwrap_or_else(|| panic!("no text quad reading {text:?}"))
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Publication
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Publication ──
 
-/// A `<Font name="X">` in FrameXML becomes the **global `X`**, an object of type `Font`.
-///
-/// This is the whole gap: we registered the resolved record and never named it, so every
-/// `SetFontObject(GameFontNormal)` in the ecosystem was handed nil.
 #[test]
 fn a_declared_font_is_published_as_a_global_object() {
     let s = script();
@@ -69,13 +59,11 @@ fn a_declared_font_is_published_as_a_global_object() {
         s.eval::<String>("return GameFontNormal:GetName()").unwrap(),
         "GameFontNormal"
     );
-    // Object identity is stable: two reads of the global are the same object, which is what makes
-    // `if fs:GetFontObject() == GameFontNormal` work at all.
+    // Two reads of the global are one object, which `fs:GetFontObject() == GameFontNormal` needs.
     assert!(s
         .eval::<bool>("return GameFontNormal == GameFontNormal")
         .unwrap());
 
-    // The declared paint reads back through the FontInstance getters.
     assert_eq!(
         s.eval::<(String, f32, String)>("return GameFontNormal:GetFont()")
             .unwrap(),
@@ -102,9 +90,7 @@ fn a_declared_font_is_published_as_a_global_object() {
     );
 }
 
-/// **`Tablet-2.0.lua:289`, verbatim.** `_, headerSize = GameTooltipHeaderText:GetFont()` — the
-/// single most-called font-object read in the corpus (268 sites across the four embedded Ace
-/// libraries). Until the global existed, Tablet fell to its hardcoded 14/12 guard branch.
+/// The header-size read at `Tablet-2.0.lua:289`, verbatim.
 #[test]
 fn tablet_reads_the_tooltip_header_size_off_the_global() {
     let s = script();
@@ -140,9 +126,8 @@ fn tablet_reads_the_tooltip_header_size_off_the_global() {
     assert_eq!((header, normal), (14.0, 12.0));
 }
 
-/// **Requirement 5: publishing must not change what `inherits=` resolves to.** The chain is still
-/// flattened once, at load, and the published object carries the *flattened* values — the derived
-/// font sees the parent's face and its own height override.
+/// `inherits=` is flattened once, at load, where the reference links it live (`0x770c60`), and
+/// the published object carries the flattened values.
 #[test]
 fn an_inheriting_font_still_flattens_to_the_same_values() {
     let s = script();
@@ -159,7 +144,6 @@ fn an_inheriting_font_still_flattens_to_the_same_values() {
              </Font>
            </Ui>"#,
     );
-    // The Rust-side record — unchanged by publication.
     let derived = s.font_object("DerivedFont").expect("registered");
     assert_eq!(derived.font.as_deref(), Some("Fonts\\FRIZQT__.TTF"));
     assert_eq!(derived.height, Some(18.0));
@@ -167,7 +151,6 @@ fn an_inheriting_font_still_flattens_to_the_same_values() {
     assert_eq!(derived.outline, Outline::Normal);
     assert_eq!(derived.justify_h, Some(JustifyH::Center));
     assert!(derived.shadow.is_some(), "the shadow inherits too");
-    // …and the same values through the published object.
     assert_eq!(
         s.eval::<(String, f32, String)>("return DerivedFont:GetFont()")
             .unwrap(),
@@ -179,16 +162,10 @@ fn an_inheriting_font_still_flattens_to_the_same_values() {
     );
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// SetFontObject / GetFontObject
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── SetFontObject and GetFontObject ──
 
-/// **`Gratuity-2.0.lua:47-59`, verbatim** — the block that took five corpus addons down at load
-/// with `bad argument #2: error converting Lua nil to String`.
-///
-/// Three separate things have to hold for it: `CreateFontString()` with **no arguments**,
-/// `SetFontObject` taking the **object**, and `AddFontStrings` existing at all (fixing only the
-/// first two moves the death one line down).
+/// The tooltip build at `Gratuity-2.0.lua:47-59`: it needs a no-argument `CreateFontString`,
+/// `SetFontObject` taking the object, and `AddFontStrings`.
 #[test]
 fn gratuity_builds_its_thirty_line_scan_tooltip() {
     let s = script();
@@ -218,7 +195,6 @@ fn gratuity_builds_its_thirty_line_scan_tooltip() {
     .expect("Gratuity's CreateTooltip must not raise");
     assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
 
-    // The font object actually landed on the lines it made.
     assert_eq!(
         s.eval::<(String, f32)>("return vars.Llines[7]:GetFont()")
             .unwrap(),
@@ -229,13 +205,10 @@ fn gratuity_builds_its_thirty_line_scan_tooltip() {
             .unwrap(),
         "GameFontNormal"
     );
-    // And Gratuity's own next move — `ClearLines` over the grown stack — still works.
+    // Gratuity's next call: `ClearLines` over the grown line stack.
     s.run("vars.tooltip:ClearLines()").unwrap();
 }
 
-/// The object form and the string form must resolve to **the same paint**. Both are kept: the
-/// object is what 3,180 of 3,186 corpus sites pass, the string is what our own `assets/ui` and 6
-/// corpus sites pass.
 #[test]
 fn set_font_object_takes_the_object_or_the_name() {
     let mut s = script();
@@ -275,14 +248,12 @@ fn set_font_object_takes_the_object_or_the_name() {
             Some([0.25, 0.5, 0.75, 1.0])
         )
     );
-    // …and both name the same object back.
     assert!(s
         .eval::<bool>("return byObject:GetFontObject() == byName:GetFontObject()")
         .unwrap());
 
-    // nil is the THIRD form the reference's own usage string names
-    // (`SetFontObject(font or "font" or nil)`, `.rdata 0x87c5cc`): it severs the link and leaves
-    // the paint standing.
+    // nil, the third form in the reference's usage string (`.rdata 0x87c5cc`), unlinks the object
+    // and leaves the paint.
     s.run("byName:SetFontObject(nil)").unwrap();
     assert!(s
         .eval::<bool>("return byName:GetFontObject() == nil")
@@ -293,14 +264,11 @@ fn set_font_object_takes_the_object_or_the_name() {
         Some(11.0),
         "unlinking must not repaint"
     );
-    // A frame or an unknown name is still an ERROR, never a silent no-op (1203/1205/1211's class).
     assert!(s.run("byName:SetFontObject(f)").is_err());
     assert!(s.run("byName:SetFontObject('NoSuchFont')").is_err());
 }
 
-/// `GetFontObject` returns the **object**, not a name — because `Dewdrop-2.0.lua:2181` indexes the
-/// result immediately: `button.text:SetTextColor(button.text:GetFontObject():GetTextColor())`.
-/// 65 sites across 62 corpus addons do exactly this.
+/// `GetFontObject` returns the object, not a name, which `Dewdrop-2.0.lua:2181` indexes at once.
 #[test]
 fn dewdrop_recolors_a_row_from_its_own_font_object() {
     let mut s = script();
@@ -332,17 +300,10 @@ fn dewdrop_recolors_a_row_from_its_own_font_object() {
     assert_eq!(painted(&s, "row").2, Some([1.0, 1.0, 1.0, 1.0]));
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Mutability — the decision, pinned
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Mutability ──
 
-/// **The mutability decision.** A font object is a shared record with a **live** link: mutating it
-/// re-paints every FontString that inherits it, which is why addons mutate one at all. What a
-/// FontString set *for itself* since its own `SetFontObject` survives that re-paint — our
-/// `FONTINSTANCE+0x038 explicitlySetMask`.
-///
-/// If this ever regresses to a one-shot copy, `inherited` stops moving and the test says so; if the
-/// mask is dropped, `overridden` loses its red.
+/// A font object is a live link: mutating it repaints every FontString that inherits it, except
+/// what a FontString set for itself, whose setter cleared that property's inherit-mask bit.
 #[test]
 fn mutating_a_font_object_repaints_everything_that_inherits_it() {
     let mut s = script();
@@ -375,7 +336,6 @@ fn mutating_a_font_object_repaints_everything_that_inherits_it() {
     assert_eq!(painted(&s, "inherited").1, Some(12.0));
     assert_eq!(painted(&s, "overridden").2, Some([1.0, 0.0, 0.0, 1.0]));
 
-    // The mutation the whole feature exists for.
     s.run(
         r#"
         ThemeFont:SetFont("Fonts\\MORPHEUS.TTF", 20)
@@ -385,7 +345,6 @@ fn mutating_a_font_object_repaints_everything_that_inherits_it() {
     .unwrap();
     s.resolve();
 
-    // Both followed the face and size…
     assert_eq!(
         painted(&s, "inherited"),
         (
@@ -399,17 +358,14 @@ fn mutating_a_font_object_repaints_everything_that_inherits_it() {
         Some("Fonts\\MORPHEUS.TTF".into())
     );
     assert_eq!(painted(&s, "overridden").1, Some(20.0));
-    // …but the one that had set its own colour kept it.
     assert_eq!(
         painted(&s, "overridden").2,
         Some([1.0, 0.0, 0.0, 1.0]),
         "an explicitly-set property must survive a font-object mutation"
     );
 
-    // Severance SURVIVES a re-point. The reference's inheritMask bit (`+0x2c`,
-    // FontString `+0xd4`) is cleared by the local setter and never restored, so "a FontString that
-    // set its own colour stays severed even across a later SetFontObject". Our first cut reset the
-    // mask here and this assertion was its inverse.
+    // Severance survives a re-point: the local setter clears the reference's inheritMask bit
+    // (`+0x2c`, FontString `+0xd4`) and nothing restores it.
     s.run("b:SetFontObject(ThemeFont)").unwrap();
     s.resolve();
     assert_eq!(
@@ -417,16 +373,13 @@ fn mutating_a_font_object_repaints_everything_that_inherits_it() {
         Some([1.0, 0.0, 0.0, 1.0]),
         "a re-point must not restore inheritance of a severed property"
     );
-    // Dewdrop still works, because it re-reads the colour off the new object explicitly every
-    // refresh (`Dewdrop-2.0.lua:2181`) rather than relying on inheritance.
+    // Dewdrop re-reads the colour off the object every refresh (`Dewdrop-2.0.lua:2181`).
     s.run("b:SetTextColor(b:GetFontObject():GetTextColor())")
         .unwrap();
     s.resolve();
     assert_eq!(painted(&s, "overridden").2, Some([0.0, 1.0, 0.0, 1.0]));
 }
 
-/// A mutation of a font object nobody inherits touches nothing, and a FontString that inherits a
-/// *different* object is not caught in the sweep.
 #[test]
 fn propagation_is_scoped_to_the_object_that_changed() {
     let mut s = script();
@@ -458,14 +411,10 @@ fn propagation_is_scoped_to_the_object_that_changed() {
     assert_eq!(painted(&s, "two").1, Some(12.0));
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// CreateFont
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── CreateFont ──
 
-/// **`_Nameplates.lua:149` + `:129` + `:212`, end to end** — mint a font object at runtime, set it
-/// up, then paint a FontString with it. Plus `!OmniCC/main.lua:40-41`'s half: the name is published
-/// as a global even when the return value is thrown away, and `SetFont`'s return is the font-file
-/// validity probe OmniCC uses it as.
+/// `_Nameplates.lua:149`, `:129` and `:212`, then `!OmniCC/main.lua:40-41`: the name is published
+/// even when the return is dropped, and `SetFont`'s return says whether the face loaded.
 #[test]
 fn create_font_mints_publishes_and_paints() {
     let mut s = script();
@@ -494,7 +443,6 @@ fn create_font_mints_publishes_and_paints() {
         )
     );
 
-    // The return value and the published global are the SAME object — OmniCC reads only the global.
     assert!(s
         .eval::<bool>("return _NameplatesNameplateFont == Nameplate.Font")
         .unwrap());
@@ -504,8 +452,7 @@ fn create_font_mints_publishes_and_paints() {
         "Font"
     );
 
-    // `!OmniCC/main.lua:40-41` verbatim: create, discard the return, use the global, and branch on
-    // SetFont's return to detect a saved font path that is no longer usable.
+    // `!OmniCC/main.lua:40-41`: create, drop the return, then branch on the global's `SetFont`.
     let reverted = s
         .eval::<bool>(
             r#"
@@ -528,9 +475,7 @@ fn create_font_mints_publishes_and_paints() {
         ("Fonts\\FRIZQT__.TTF".to_string(), 20.0, String::new())
     );
 
-    // A name that already names a font object hands the existing one back UNCHANGED — the
-    // non-destructive reading (see `create_font`'s doc). The alternative would let
-    // `CreateFont("GameFontNormal")` blank the shipped registry entry the whole UI inherits.
+    // A name that already names a font object returns that object unchanged (`0x7839ab`).
     s.run("again = CreateFont('_NameplatesNameplateFont')")
         .unwrap();
     assert!(s.eval::<bool>("return again == Nameplate.Font").unwrap());
@@ -540,14 +485,12 @@ fn create_font_mints_publishes_and_paints() {
         ("Fonts\\SKURRI.TTF".to_string(), 10.0, String::new())
     );
 
-    // A nameless CreateFont is an error: the name IS the publication. The EMPTY name is not —
-    // the reference's `lua_isstring` gate takes it (unlike the XML path), so we do too.
+    // A nameless `CreateFont` raises; the empty name passes the reference's `lua_isstring` gate.
     assert!(s.run("CreateFont()").is_err());
     s.run("CreateFont('')").unwrap();
 }
 
-/// **`FonzAppraiser/mods/gui/gui.lua:27-30`** — `CreateFont` then `CopyFontObject(<a shipped
-/// object>)` then override the face. The corpus's only Font-on-Font call.
+/// The sequence at `FonzAppraiser/mods/gui/gui.lua:27-30`.
 #[test]
 fn fonz_appraiser_copies_a_shipped_object_then_overrides_the_face() {
     let s = script();
@@ -571,7 +514,6 @@ fn fonz_appraiser_copies_a_shipped_object_then_overrides_the_face() {
     "#,
     )
     .expect("FonzAppraiser's font setup must not raise");
-    // The copy brought the colour and justification over; the SetFont replaced the face and size.
     assert_eq!(
         s.eval::<(String, f32, String)>("return small_number_font:GetFont()")
             .unwrap(),
@@ -587,7 +529,6 @@ fn fonz_appraiser_copies_a_shipped_object_then_overrides_the_face() {
             .unwrap(),
         "RIGHT"
     );
-    // …and the object it copied FROM is untouched.
     assert_eq!(
         s.eval::<(String, f32, String)>("return GameFontHighlightSmall:GetFont()")
             .unwrap(),
@@ -595,10 +536,8 @@ fn fonz_appraiser_copies_a_shipped_object_then_overrides_the_face() {
     );
 }
 
-/// The `Spacing` pair is **deliberately absent** (we model no line spacing, and a stored-but-never
-/// drawn setter is this codebase's recurring silent-drop bug). It must fail LOUDLY rather than
-/// quietly accept a number nobody honours — this test is the tripwire on that choice, and it flips
-/// the day spacing becomes real.
+/// Line spacing is not built: the reference's `SetSpacing` is absent here, so a call raises rather
+/// than store a number nothing draws.
 #[test]
 fn the_unmodelled_spacing_pair_fails_loudly() {
     let s = script();
@@ -607,9 +546,8 @@ fn the_unmodelled_spacing_pair_fails_loudly() {
     assert!(s.eval::<bool>("return SomeFont.SetSpacing == nil").unwrap());
 }
 
-/// A button's per-state label fonts take the object or the name too (the corpus splits 5 to 4
-/// across the trio), and — because they are stored as NAMES and re-resolved at every extract — a
-/// later mutation of that font object reaches the label with no further call.
+/// A button's state fonts take the object or the name; they are stored as names and re-resolved at
+/// every extract, so a later mutation of the object reaches the label.
 #[test]
 fn button_state_fonts_take_the_object_and_follow_its_mutation() {
     let mut s = script();
@@ -647,15 +585,11 @@ fn button_state_fonts_take_the_object_and_follow_its_mutation() {
         )
     );
 
-    // The string form still works alongside it.
     s.run("b:SetHighlightFontObject('GameFontNormal')").unwrap();
 }
 
-/// **A `CreateFont` object holds nothing, so pointing a FontString at it copies nothing.**
-/// The reference gates every merge (`0x770910`/`0x770800`) on the source's own has-a-value mask,
-/// and a fresh font has `mask == 0` — the FontString keeps exactly what it had, no blanking and no
-/// fallback to a default. Our first cut wrote face/height through unconditionally and would have
-/// wiped it.
+/// The reference gates every merge (`0x770910`/`0x770800`) on the source's has-a-value mask, and a
+/// fresh `CreateFont` object's mask is 0, so the FontString keeps what it had.
 #[test]
 fn an_empty_font_object_copies_nothing_onto_a_fontstring() {
     let mut s = script();
@@ -691,7 +625,7 @@ fn an_empty_font_object_copies_nothing_onto_a_fontstring() {
         ),
         "an unset property must copy nothing, not blank the region"
     );
-    // The link still moved, so once the blank font is dressed the string follows it.
+    // The link still moves: once the blank font is dressed, the string follows it.
     assert_eq!(
         s.eval::<String>("return fs:GetFontObject():GetName()")
             .unwrap(),
@@ -702,8 +636,7 @@ fn an_empty_font_object_copies_nothing_onto_a_fontstring() {
     assert_eq!(painted(&s, "keep").0, Some("Fonts\\MORPHEUS.TTF".into()));
 }
 
-/// `SetFont` returns **1 or nil**, not a boolean — the reference's exact return shape, and what
-/// `!OmniCC/main.lua:41` branches on.
+/// The reference's return shape, not a boolean; `!OmniCC/main.lua:41` branches on it.
 #[test]
 fn set_font_returns_one_or_nil() {
     let s = script();
@@ -716,15 +649,8 @@ fn set_font_returns_one_or_nil() {
     assert!(s.eval::<bool>("return f:SetFont('', 12) == nil").unwrap());
 }
 
-/// The justify law is **one** table in the binary (`.rdata 0x811ad0`) and must be one
-/// transcription here: a `FontString` and a `<Font>` object have to answer identically, token for
-/// token and raise for raise.
-///
-/// They did not. Both sides were written separately from the same law and each drifted its own
-/// way — the FontString had no `GetJustifyH`/`GetJustifyV` at all (real entries `0x79e5f0` /
-/// `0x79e7f0`), the Font object silently `.trim()`ed its argument where `SStrCmpI` compares the
-/// whole string, and both quietly answered CENTER for a string the reference raises on. Every
-/// test on both sides passed throughout. This is the net that makes the next drift fail.
+/// The justify tokens are one reference table (`.rdata 0x811ad0`) matched whole and case-blind by
+/// `SStrCmpI`; a FontString (getters `0x79e5f0`/`0x79e7f0`) and a `<Font>` object answer alike.
 #[test]
 fn both_tables_speak_one_justify_law() {
     let s = script();
@@ -736,7 +662,7 @@ fn both_tables_speak_one_justify_law() {
     .unwrap();
 
     for obj in ["fs", "fo"] {
-        // The client's ctor default `0x212` = CENTER | MIDDLE | 0x200, read through each mask.
+        // The reference's constructor default `0x212`, CENTER | MIDDLE | 0x200, read per axis.
         let h = s
             .eval::<String>(&format!("return {obj}:GetJustifyH()"))
             .unwrap();
@@ -759,7 +685,7 @@ fn both_tables_speak_one_justify_law() {
             }
         }
 
-        // A non-token raises the reference's own usage string rather than coercing to CENTER.
+        // A non-token raises the reference's usage string rather than coercing to CENTER.
         for verb in ["SetJustifyH", "SetJustifyV"] {
             let err = s
                 .run(&format!("{obj}:{verb}('MIDDLE_LEFT')"))
@@ -771,27 +697,21 @@ fn both_tables_speak_one_justify_law() {
             );
         }
 
-        // Whole-string: a trailing space is a miss. The Font object used to trim it away.
+        // The match is whole-string: a trailing space is a miss.
         assert!(
             s.run(&format!("{obj}:SetJustifyH('LEFT ')")).is_err(),
             "{obj}:SetJustifyH must not trim its argument"
         );
 
-        // A cross-axis token matches the table, so it is accepted with no error — the one place
-        // we knowingly stop short of the law (the reference clears the axis; see `script::justify`).
+        // A cross-axis token is in the table and raises nothing. The reference then clears the
+        // axis; the FontString does too, the `<Font>` object leaves it as it was.
         s.run(&format!("{obj}:SetJustifyH('TOP')")).unwrap();
         s.run(&format!("{obj}:SetJustifyV('LEFT')")).unwrap();
     }
 }
 
-/// `SetFont` is one routine (`0x79f210`) with three entry points — Font `0x7a0270`, FontString
-/// `0x79d4f0`, EditBox `0x797210` — so all three must answer identically, and none of them did.
-///
-/// The FontString's hand-written copy answered the boolean `true` for *everything*, including the
-/// empty-path load failure that `!OmniCC/main.lua:41`'s `if not f:SetFont(saved, size)` probes;
-/// the `<Font>` object's took `Option` arguments and so answered **nil** for `SetFont()` where the
-/// reference raises `Usage: %s:SetFont("font", fontHeight [, flags])` (`0x87c69c`). A behavioural
-/// differential across both tables is what surfaced it — arity alone had matched.
+/// `SetFont` is one routine (`0x79f210`) behind three entries, Font `0x7a0270`, FontString
+/// `0x79d4f0` and EditBox `0x797210`; a bad argument raises its usage string (`0x87c69c`).
 #[test]
 fn set_font_is_one_routine_on_both_tables() {
     let s = script();
@@ -799,7 +719,6 @@ fn set_font_is_one_routine_on_both_tables() {
         .unwrap();
 
     for obj in ["fs", "fo"] {
-        // Success is the NUMBER 1 — never a boolean, and never zero values.
         let n = s
             .eval::<f32>(&format!(
                 "return {obj}:SetFont('Fonts\\\\FRIZQT__.TTF', 12)"
@@ -814,15 +733,14 @@ fn set_font_is_one_routine_on_both_tables() {
             "{obj}:SetFont must answer the number 1, not true"
         );
 
-        // An empty path is the LOAD FAILURE edge: nil, falsey, and nothing raised.
+        // An empty path is a load failure: nil, and nothing raised.
         assert!(
             s.eval::<bool>(&format!("return {obj}:SetFont('', 12) == nil"))
                 .unwrap(),
             "{obj}:SetFont('') must answer nil"
         );
 
-        // A missing or non-string path, or a missing height, is an ARGUMENT error — it raises,
-        // which is a different thing from the nil above and used to be conflated with it.
+        // A missing or non-string path, or a missing height, is an argument error and raises.
         for bad in ["", "'Fonts\\\\FRIZQT__.TTF'", "nil, 12", "{}, 12"] {
             let err = s
                 .run(&format!("{obj}:SetFont({bad})"))
@@ -833,7 +751,7 @@ fn set_font_is_one_routine_on_both_tables() {
             );
         }
 
-        // Both `lua_isstring` and `lua_isnumber` coerce, so a numeric string is accepted for either.
+        // Both `lua_isstring` and `lua_isnumber` coerce, so either accepts a numeric string.
         assert!(
             s.eval::<bool>(&format!(
                 "return {obj}:SetFont('Fonts\\\\FRIZQT__.TTF', '14') == 1"
@@ -844,17 +762,9 @@ fn set_font_is_one_routine_on_both_tables() {
     }
 }
 
-/// A cross-axis token **erases** its axis, and the two readers then disagree — faithfully.
-///
-/// `SetJustifyH("TOP")` parses (`0x08`), contributes nothing to mask `0x07`, and raises nothing.
-/// `GetJustifyH()` afterwards answers the literal `"UNKNOWN"` (`0x6f1a00` → `.data 0x838044`),
-/// while the glyphs keep drawing **centred**: the ui→gx translator `0x44d420` is a priority ladder
-/// whose per-axis register is pre-set to `1` between the `test` and the `jcc`, so an all-clear axis
-/// exits with CENTER still in it. Reading the getter's answer into the draw path — or mapping the
-/// bitmask onto the gx enum with a `0` default — inverts the axis to LEFT.
-///
-/// Reached by 13 corpus sites (`FonzAppraiser` ×12, `Roid-Macros`) writing
-/// `SetJustifyV("CENTER")` when they mean MIDDLE.
+/// `SetJustifyH("TOP")` parses (`0x08`), sets nothing in the axis mask `0x07` and raises nothing;
+/// `GetJustifyH` then answers `"UNKNOWN"` (`0x6f1a00`, `.data 0x838044`), yet the ui-to-gx
+/// translator `0x44d420` pre-sets each axis to 1, so the text still draws centred, not LEFT.
 #[test]
 fn a_cross_axis_token_erases_the_axis_but_still_draws_centred() {
     let mut s = script();
@@ -867,13 +777,13 @@ fn a_cross_axis_token_erases_the_axis_but_still_draws_centred() {
     )
     .unwrap();
 
-    // A real token lands, so the erase below is visibly an erase and not a no-op.
+    // A real token first, so the erase below is not a no-op.
     s.run("fs:SetJustifyH('LEFT') fs:SetJustifyV('TOP')")
         .unwrap();
     assert_eq!(s.eval::<String>("return fs:GetJustifyH()").unwrap(), "LEFT");
     assert_eq!(s.eval::<String>("return fs:GetJustifyV()").unwrap(), "TOP");
 
-    // The cross-axis pair: each erases the OTHER axis it was aimed at, raising nothing.
+    // Each setter gets the other axis's token: it clears its own axis and raises nothing.
     s.run("fs:SetJustifyH('TOP')").unwrap();
     s.run("fs:SetJustifyV('CENTER')").unwrap();
     assert_eq!(
@@ -886,7 +796,6 @@ fn a_cross_axis_token_erases_the_axis_but_still_draws_centred() {
         "UNKNOWN"
     );
 
-    // ...and the draw path answers CENTER/MIDDLE for that same state.
     s.resolve();
     let (h, v) = s
         .extract()
@@ -908,17 +817,9 @@ fn a_cross_axis_token_erases_the_axis_but_still_draws_centred() {
     );
 }
 
-/// The font block is a **per-table membership fact**, and the shared shadow-accessor (`0x79f910`,
-/// FontString's own `0x79dbe0`) names the six: *"Exposed on: FontString, Font object, EditBox,
-/// MessageFrame, ScrollingMessageFrame, SimpleHTML. NOT on Button."* We shipped it on two; these
-/// are the third and fourth.
-///
-/// `BigWigs/Plugins/Messages.lua:212` — `self.msgframe:SetFontObject(GameFontNormalLarge)` on a
-/// frame it has just given `SetInsertMode("TOP")` — died there every session.
-///
-/// The second assertion is the trap: a message frame's lines fall back to **LEFT** when it has no
-/// declared `<FontString>`, while a freshly created `RegionData` defaults to the FontString's own
-/// CENTER. Creating the style region on demand must not silently re-justify the frame.
+/// The shared font block (`0x79f910`, FontString's `0x79dbe0`) is on six tables: FontString, Font,
+/// EditBox, MessageFrame, ScrollingMessageFrame and SimpleHTML, not Button. A message frame with no
+/// `<FontString>` draws LEFT, and creating its style region (CENTER by default) must keep it LEFT.
 #[test]
 fn the_font_block_reaches_both_message_frame_tables() {
     let mut s = script();
@@ -940,7 +841,7 @@ fn the_font_block_reaches_both_message_frame_tables() {
             "MsgBlockFont",
             "{obj}:GetFontObject must answer the OBJECT it was given"
         );
-        // The shared `0x79f210` contract, same as every other table that carries it.
+        // The shared `SetFont` contract (`0x79f210`).
         assert!(
             s.eval::<bool>(&format!(
                 "return {obj}:SetFont('Fonts\\\\MORPHEUS.TTF', 16) == 1"
@@ -952,11 +853,10 @@ fn the_font_block_reaches_both_message_frame_tables() {
             .eval::<(mlua::Value, f32, String)>(&format!("return {obj}:GetFont()"))
             .unwrap();
         assert_eq!(height, 16.0, "{obj}:GetFont reads back what SetFont wrote");
-        // The four-value getters pin at 4 for every one of the six tables (`0x79f9b3`).
+        // The four-value getters return four values on all six tables (`0x79f9b3`).
         assert_eq!(s.arity(&format!("{obj}:GetShadowColor()")).unwrap(), 4);
     }
 
-    // Styling the frame must not move its text: the lines still run flush LEFT.
     s.run("mf:AddMessage('flush left please')").unwrap();
     s.resolve();
     let j = s
@@ -978,18 +878,8 @@ fn the_font_block_reaches_both_message_frame_tables() {
     );
 }
 
-/// `CreateFontString`'s **third argument** applies a font object — the argument we accepted and
-/// then dropped on the floor (decision 1255).
-///
-/// 49 corpus call sites across 5 distinct addons pass one, and every one names a font object:
-/// AckisRecipeList (28), CustomNameplates (10), _LazyPig (6), LibAboutPanel (4), ColorPickerPlus.
-/// Five separate addons, so this is not one library file replicated. Ignoring it was 1203's class —
-/// the addon asks for a font, the call succeeds, and the text comes out in the default with no
-/// failure anywhere to point at.
-///
-/// The **order** is the part a reimplementation loses: the font-object registry is tried FIRST and
-/// the template registry only on a font miss (`0x773d39` then `0x773d47`). A template-first
-/// resolver would miss all 49 of these, because `inherits=` is one argument over two namespaces.
+/// The third argument is looked up as a font object first, and as a template only on a miss
+/// (`0x773d39`, then `0x773d47`).
 #[test]
 fn create_font_string_applies_the_font_object_named_by_its_third_argument() {
     let s = script();
@@ -1004,7 +894,7 @@ fn create_font_string_applies_the_font_object_named_by_its_third_argument() {
            </Ui>"#,
     );
 
-    // Exactly `_LazyPig/LazyPigMenu.lua:88`'s line.
+    // The call at `_LazyPig/LazyPigMenu.lua:88`.
     s.run(r#"FS = Host:CreateFontString(nil, "ARTWORK", "GameFontNormalSmall")"#)
         .expect("the font-object form must be accepted");
     let (face, height, _flags) = s
@@ -1013,8 +903,7 @@ fn create_font_string_applies_the_font_object_named_by_its_third_argument() {
     assert_eq!(face, "Fonts\\FRIZQT__.TTF");
     assert_eq!(height, 12.0);
 
-    // A name in NEITHER registry raises — the same contract 1253 set for CreateFrame, and the same
-    // bytes (`luaL_error`, which never returns).
+    // A name in neither registry raises (`luaL_error`), as an unknown `CreateFrame` template does.
     let err = s
         .run(r#"Bad = Host:CreateFontString(nil, "ARTWORK", "NoSuchFontOrTemplate")"#)
         .expect_err("a name in neither registry must raise");
@@ -1023,22 +912,13 @@ fn create_font_string_applies_the_font_object_named_by_its_third_argument() {
         "the raise must name what was looked up: {err}"
     );
 
-    // Texture takes the same argument through the same resolver (1 real corpus site).
+    // `CreateTexture` takes the same third argument through the same resolver.
     s.run(r#"TX = Host:CreateTexture(nil, "OVERLAY")"#)
         .expect("the two-argument form still works");
 }
 
-/// **`SetFont`'s nil is a LOAD failure, and only the host knows** (decision 2103).
-///
-/// The reference answers the number 1 or nil (`0x79f345`/`0x79f361`), and the nil originates in
-/// the font factory at `0x5c1ae0` — a path that names no readable file. `!OmniCC/main.lua:41`
-/// reads it exactly that way (`if not Font:SetFont(saved, size) then revert end`), and an addon
-/// that ships its own faces (MSBT ships thirty-one, under `Interface\Addons\…\Fonts\`) is the
-/// case that makes the answer depend on a store rather than on the string.
-///
-/// The engine-less default is the other half: with no probe a non-empty path answers 1, because a
-/// VM with no font backend has nothing for a load to fail against. That is the opposite default to
-/// `SetTexture`'s (1322) and the reason is in `Model::font_probe`.
+/// The reference answers 1 or nil (`0x79f345`/`0x79f361`), nil when the font factory (`0x5c1ae0`)
+/// finds no readable file; with no host probe, any non-empty path answers 1.
 #[test]
 fn set_font_answers_the_hosts_load_verdict_when_there_is_a_host() {
     let mut s = script();
@@ -1051,8 +931,7 @@ fn set_font_answers_the_hosts_load_verdict_when_there_is_a_host() {
         .unwrap());
     assert!(s.eval::<bool>("return FS:SetFont('', 12) == nil").unwrap());
 
-    // With one, the store decides — and the face it refused is NOT adopted, so the region keeps
-    // the last font that did load.
+    // With a probe the store decides, and a refused face is not adopted.
     s.set_font_probe(Box::new(|path| {
         path.eq_ignore_ascii_case("interface\\addons\\msbt\\fonts\\porky.ttf")
             || path.eq_ignore_ascii_case("fonts\\frizqt__.ttf")
@@ -1080,20 +959,8 @@ fn set_font_answers_the_hosts_load_verdict_when_there_is_a_host() {
     assert_eq!(height, 18.0, "…while the height, which never fails, is set");
 }
 
-/// **Mik's Scrolling Battle Text, end to end** — the exact sequence the addon runs per event,
-/// pinned because it is the shape a whole class of "the addon's font did not take" reports wears
-/// (decisions 2103, 2112).
-///
-/// MSBT's twenty scroll-area FontStrings are declared `inherits="MasterFont"` — the reference's
-/// root font object, which carries a `<Shadow>` and **nothing else**: no face, no height, no
-/// outline. Each animation then does, in this order, on the string it recycles:
-/// `ClearAllPoints · SetFont(<its own TTF>, 18, "OUTLINE") · SetTextColor · SetText · SetAlpha ·
-/// SetPoint`. Every one of those five paint axes has to reach the extracted quad *unmodified* by
-/// the object the string inherits — the addon's face over the object's absent one, the addon's
-/// height over the renderer default, the addon's outline over the object's `NONE` (which is
-/// indistinguishable from "unset", see [`Outline`]), its colour over the object's absent one, and
-/// the animation's fade as the quad's own alpha. The `<Shadow>` is the one thing that IS inherited,
-/// and it must still be there.
+/// MSBT's per-event sequence over the stock `MasterFont` (`Fonts.xml:55`, a `<Shadow>` only): its
+/// own face, size, outline, colour and fade reach the quad, and the shadow is inherited.
 #[test]
 fn msbt_paints_its_own_face_size_outline_and_fade_over_the_font_object_it_inherits() {
     let mut s = script();
@@ -1161,7 +1028,6 @@ fn msbt_paints_its_own_face_size_outline_and_fade_over_the_font_object_it_inheri
         }
         ref other => panic!("expected a Text quad, got {other:?}"),
     }
-    // The Lua-visible echo agrees with the quad — the readback an addon branches on.
     assert_eq!(
         s.eval::<(String, f32, String)>("return MSBTFrameIncomingText1:GetFont()")
             .unwrap(),
diff --git a/crates/benilla-ui/src/script/tests/frame_api.rs b/crates/benilla-ui/src/script/tests/frame_api.rs
index c1ce8bfc..fc9c20c5 100644
--- a/crates/benilla-ui/src/script/tests/frame_api.rs
+++ b/crates/benilla-ui/src/script/tests/frame_api.rs
@@ -1,18 +1,12 @@
-//! Small frame-API wins: GetLocale, SetAllPoints, and GetPoint readback.
+//! Frame-API basics: `GetLocale`, `SetAllPoints` and `GetPoint` readback.
 
 use super::common::script;
 
-/// Two era names, asserted together because neither earns a file of its own.
-///
-/// This test carried two more legs until decision 2142, `SetFormattedText` and `SetShown`, and
-/// both went with the verbs: neither is in a 1.12 method table. What the first of them actually
-/// proved — that `%N$s` reorders rather than consumes — is `string.format`'s own behaviour and is
-/// pinned where it lives, in [`crate::strings`].
 #[test]
 fn get_locale_and_set_all_points() {
     let mut s = script();
     s.set_screen_size(800.0, 600.0);
-    // GetLocale — benilla is enUS-data-only.
+    // `GetLocale`: benilla is enUS-only.
     assert_eq!(s.eval::<String>("return GetLocale()").unwrap(), "enUS");
 
     s.run(
@@ -28,7 +22,6 @@ fn get_locale_and_set_all_points() {
     .unwrap();
     s.resolve();
 
-    // SetAllPoints pins the full target rect, parent-default and by-name forms alike.
     let ok: bool = s
         .eval(
             r#"
@@ -53,7 +46,7 @@ fn getpoint_reads_back_anchors() {
     "#,
     )
     .unwrap();
-    // Screen-anchored: relativeTo is nil (no UIParent wrapper yet — stated).
+    // Screen-anchored: `relativeTo` reads nil.
     let ok: bool = s
         .eval(
             r#"
@@ -63,7 +56,7 @@ fn getpoint_reads_back_anchors() {
         )
         .unwrap();
     assert!(ok, "screen anchor reads back");
-    // Frame-anchored: relativeTo is the same wrapper table (stable identity).
+    // Frame-anchored: `relativeTo` is the same wrapper table.
     let ok: bool = s
         .eval(
             r#"
diff --git a/crates/benilla-ui/src/script/tests/generic_for.rs b/crates/benilla-ui/src/script/tests/generic_for.rs
index 0906b684..1b8051ff 100644
--- a/crates/benilla-ui/src/script/tests/generic_for.rs
+++ b/crates/benilla-ui/src/script/tests/generic_for.rs
@@ -1,21 +1,9 @@
-//! Lua 5.0's iterator-less generic-for, restored in the vendored VM (decision 1215).
-//!
-//! `for k, v in someTable do` is Lua 5.0 syntax that 5.1 removed at the OPCODE level. 183 of 218
-//! corpus addons are reached by it and it is the first session-start error for 60 of them — three
-//! quarters of everything that breaks in a running session. The fix is 5.0's `OP_TFORPREP` folded
-//! into `OP_TFORLOOP` in `third_party/lua-src/lua-5.1.5/lvm.c`.
-//!
-//! Each test below pins one detail that was byte-verified in the real 1.12.1 client, because each
-//! is a place where a *reasonable* guess diverges from what the client does. The `__call` case is
-//! the sharpest: two of the three conditions somebody would naturally write for this behave
-//! differently there.
+//! The Lua 5.0 dialect the vendored 5.1 VM restores: the iterator-less generic-for (5.0's
+//! `OP_TFORPREP` folded into `OP_TFORLOOP` in `third_party/lua-src/lua-5.1.5/lvm.c`), long-string
+//! nesting and the constructor compat-semicolon.
 
 use super::common::script;
 
-/// **The construct works at all** — the whole point, in the shape the corpus uses.
-///
-/// `Ace.lua`'s is the canonical one and Ace is embedded across half the ecosystem:
-/// `for _, lang in self.langs do … end`, with no `pairs` and no iterator function.
 #[test]
 fn a_table_generator_iterates_like_lua_50() {
     let s = script();
@@ -31,7 +19,7 @@ fn a_table_generator_iterates_like_lua_50() {
         .unwrap();
     assert_eq!(seen, 6, "every pair must be visited exactly once");
 
-    // The array shape too, and the KEY must be the real key rather than a counter.
+    // The array shape: the key is the real key, not a counter.
     let keys: String = s
         .eval(
             r#"
@@ -45,12 +33,7 @@ fn a_table_generator_iterates_like_lua_50() {
     assert_eq!(keys, "1x2y");
 }
 
-/// **The condition is a bare type-tag test, so a table carrying `__call` STILL gets `next`.**
-///
-/// This is the discriminating case, and the reason the patch does not test "is not callable" or
-/// "has no `__call`" — both of those are reasonable readings and both diverge from the client here.
-/// The 1.12 handler makes **no** metatable access whatsoever (no `luaT_gettmbyobj`, no
-/// `tryfuncTM`), so the `__call` is never consulted and the table is iterated.
+/// The 1.12 handler tests only the type tag, never the metatable, so `__call` is not consulted.
 #[test]
 fn a_table_with_a_call_metamethod_is_still_iterated_not_called() {
     let s = script();
@@ -72,11 +55,7 @@ fn a_table_with_a_call_metamethod_is_still_iterated_not_called() {
     );
 }
 
-/// **The callee is the global `next`, read fresh at each loop entry — so an addon can replace it.**
-///
-/// Observable behaviour of the real client, not an accident: the lookup is a raw read of the
-/// thread's globals table, performed once per loop entry. An addon that assigns `next = myfn`
-/// changes every later generic-for in the session. Reproduced rather than improved on.
+/// The callee is a raw read of the global `next` at each loop entry, so an addon can replace it.
 #[test]
 fn the_substituted_generator_is_the_live_global_next() {
     let s = script();
@@ -100,14 +79,11 @@ fn the_substituted_generator_is_the_live_global_next() {
     );
 }
 
-/// **Only a table is substituted.** A function generator is untouched (the ordinary 5.1 path), and
-/// a non-table, non-function generator still raises on the FIRST ITERATION rather than at entry —
-/// the client's tag mismatch falls through to the normal call path.
+/// Any other generator takes the normal call path, so a number raises on the first iteration.
 #[test]
 fn only_a_table_is_substituted_and_other_types_still_raise() {
     let s = script();
 
-    // The ordinary iterator form is completely unaffected.
     let via_pairs: i64 = s
         .eval(
             r#"
@@ -120,7 +96,6 @@ fn only_a_table_is_substituted_and_other_types_still_raise() {
         .unwrap();
     assert_eq!(via_pairs, 3);
 
-    // A custom iterator function still drives its own loop.
     let custom: i64 = s
         .eval(
             r#"
@@ -139,7 +114,6 @@ fn only_a_table_is_substituted_and_other_types_still_raise() {
         "an explicit generator/state/control triple is untouched"
     );
 
-    // A number generator is not a table: it must still raise, and say so.
     let err = s
         .eval::<i64>("local n = 0 for k, v in 42 do n = n + 1 end return n")
         .unwrap_err()
@@ -150,8 +124,6 @@ fn only_a_table_is_substituted_and_other_types_still_raise() {
     );
 }
 
-/// **An empty table terminates immediately** rather than looping — `next(t, nil)` on an empty table
-/// returns nil, and the loop's own continue test is unchanged by the substitution.
 #[test]
 fn an_empty_table_generator_terminates() {
     let s = script();
@@ -161,9 +133,7 @@ fn an_empty_table_generator_terminates() {
     assert_eq!(n, 0);
 }
 
-/// **Nested and repeated loops each get their own substitution.** The patch rewrites the loop's own
-/// registers, so an inner loop must not disturb an outer one, and a loop entered twice must
-/// substitute twice (the registers are reloaded from the expression each entry).
+/// The patch rewrites the loop's own registers, reloaded from the expression at each entry.
 #[test]
 fn nested_and_repeated_loops_each_substitute_independently() {
     let s = script();
@@ -184,7 +154,6 @@ fn nested_and_repeated_loops_each_substitute_independently() {
     // Each of the 2 outer pairs runs the full inner loop (30) plus its own value.
     assert_eq!(out, 30 + 30 + 1 + 2);
 
-    // Entering the same loop a second time must work identically.
     let twice: i64 = s
         .eval(
             r#"
@@ -197,15 +166,8 @@ fn nested_and_repeated_loops_each_substitute_independently() {
     assert_eq!(twice, 4);
 }
 
-/// **5.0's long-string NESTING, restored** — the second dialect divergence in this file's family.
-///
-/// `[[ ... [[ ... ]] ... ]]` nests in Lua 5.0, which is what 1.12.1 ships. 5.1 kept the machinery
-/// (`llex.c` `read_long_string`'s `cont` counter, guarded by `LUA_COMPAT_LSTR == 2`) and put an
-/// advisory error in front of it — *"nesting of [[...]] is deprecated"* — which is a 5.1 opinion
-/// about a dialect we are not targeting. Two corpus addons stopped LOADING on it.
-///
-/// The fix is Lua's own documented switch, `LUA_COMPAT_LSTR` 1 -> 2 in our vendored `luaconf.h`,
-/// not a patch to the lexer: the code path was already there and already correct.
+/// `[[ ... [[ ... ]] ... ]]` nests in Lua 5.0, as 1.12.1 ships it; the vendored `luaconf.h` sets
+/// `LUA_COMPAT_LSTR` to 2, which enables 5.1's own nesting path in `read_long_string`.
 #[test]
 fn a_nested_long_string_parses_as_lua_50_does() {
     let s = crate::script::UiScript::new().unwrap();
@@ -214,27 +176,19 @@ fn a_nested_long_string_parses_as_lua_50_does() {
         .unwrap();
     assert_eq!(s.eval::<i64>("return NESTED_OK").unwrap(), 1);
 
-    // And a nested long STRING keeps its inner brackets, 5.0's own semantics: the outer runs to
-    // the matching close, so the inner `]]` does not terminate it.
+    // A nested long string keeps its inner brackets: the inner `]]` does not close it.
     let v = s
         .eval::<String>("return [[a [[b]] c]]")
         .expect("nested long string must parse");
     assert_eq!(v, "a [[b]] c");
 }
 
-/// **5.0's constructor compat-semicolon, restored** — the third dialect divergence (decision 1315).
-///
-/// Lua 5.0's `constructor()` opens its field loop with `testnext(ls, ';')  /* compatibility
-/// only */` — a Lua 4.0 leftover (4.0 separated a constructor's list part from its record part
-/// with `;`) that silently eats ONE extra `;` per separator position inside a table constructor.
-/// 5.1 deleted the line. AtlasLoot's `ButtonRegistry.lua` writes `Back_Title = AL["Factions"];;`
-/// twenty times; the real client loads it (director-verified on the live 1.12.1 client), stock
-/// 5.1 answered "unexpected symbol near ';'" and the addon's registry global never existed (B266).
+/// Lua 5.0's `constructor()` opens its field loop with `testnext(ls, ';')`, eating one extra `;`
+/// per separator position; 5.1 deleted the line, and AtlasLoot's `ButtonRegistry.lua` writes `;;`.
 #[test]
 fn a_double_semicolon_inside_a_constructor_parses_as_lua_50_does() {
     let s = script();
 
-    // The exact corpus shape: a record field, its `;` separator, and the compat extra.
     let out: String = s
         .eval(
             r#"
@@ -248,19 +202,15 @@ fn a_double_semicolon_inside_a_constructor_parses_as_lua_50_does() {
         .expect("the ButtonRegistry shape must parse");
     assert_eq!(out, "Factions");
 
-    // The compat skip runs at loop TOP, so a lone `;` before `}` — legal 5.0, an empty record
-    // part in 4.0 terms — is eaten the same way.
+    // The skip runs at the loop's top, so the lone `;` in `{;}` is eaten too.
     assert_eq!(s.eval::<i64>("local t = {;} return 1").unwrap(), 1);
 
-    // List context too: the separator may be `;` and the extra one is still absorbed.
     let n: i64 = s.eval("local t = { 1;; 2 } return t[1] + t[2]").unwrap();
     assert_eq!(n, 3);
 }
 
-/// **The restoration is exactly one semicolon wide, and constructor-only.** Both halves of the
-/// boundary are the client's: 5.0 eats ONE extra `;` per position (a third dies in `listfield`),
-/// and statement-level `;;` is rejected by 5.0 and 5.1 alike — confirmed by the client's own parser
-/// (`luaL_loadbuffer` → `chunk 0x6fcc90`).
+/// A third `;` dies in `listfield`, and statement-level `;;` is rejected by the client's own parser
+/// too (`luaL_loadbuffer`, `chunk 0x6fcc90`).
 #[test]
 fn the_compat_semicolon_is_one_wide_and_statement_level_stays_rejected() {
     let s = script();
diff --git a/crates/benilla-ui/src/script/tests/gm_ticket.rs b/crates/benilla-ui/src/script/tests/gm_ticket.rs
index 6a3d7277..d2a4f909 100644
--- a/crates/benilla-ui/src/script/tests/gm_ticket.rs
+++ b/crates/benilla-ui/src/script/tests/gm_ticket.rs
@@ -1,9 +1,4 @@
-//! The Help window's seven engine globals ([`crate::script::gm_ticket`], decision 1673).
-//!
-//! Two claims carry the whole feature and each has a test named after it: the category list is
-//! **flat pairs consumed by Lua 5.0 varargs** (that is what `HelpFrameGM_UpdateCategories` reads),
-//! and the four payload-free verbs **count** rather than latch (that is what keeps the window's
-//! 10-minute ticket poll alive).
+//! The Help window's seven engine globals ([`crate::script::gm_ticket`]).
 
 use super::common::script;
 use crate::script::{GmTicketIntent, GmTicketWrite, UiScript};
@@ -19,9 +14,7 @@ fn with_categories() -> UiScript {
     s
 }
 
-/// **`GetGMTicketCategories()` returns a FLAT (id, name) vararg list**, which the shipped window
-/// walks as `arg[i]` / `arg[i+1]` pairs with `arg.n` — the Lua 5.0 convention. A table here, or a
-/// list of names alone, would leave every category button unlabelled or unclickable.
+/// The stock window walks it as `arg[i]`, `arg[i+1]` pairs up to `arg.n`.
 #[test]
 fn the_categories_come_back_as_a_flat_id_name_vararg_list() {
     let s = with_categories();
@@ -37,17 +30,14 @@ fn the_categories_come_back_as_a_flat_id_name_vararg_list() {
         )
         .unwrap();
     assert_eq!((id1, name1.as_str()), (1, "Stuck"));
-    // The THIRD pair is at 5/6 — pairs, not a parallel pair of lists.
     assert_eq!((id3, name3.as_str()), (3, "Guild"));
 }
 
-/// **The ids are the DBC's, not indices.** `HelpFrameGM_UpdateCategories` stores `arg[index]` as
-/// both `button.key` (an index into `HELPFRAME_FRAMES`) and `button.ticketType` (what goes on the
-/// wire), so a renumbered list would misfile every ticket under the wrong heading.
+/// `HelpFrameGM_UpdateCategories` stores the id as `button.key` and as the wire `ticketType`.
 #[test]
 fn the_ids_are_the_dbc_ids_not_list_positions() {
     let mut s = script();
-    // A deliberately gappy, unsorted catalog — nothing may re-index it.
+    // Gappy and unsorted on purpose.
     s.set_gm_ticket_categories(vec![(10, "Character".into()), (4, "Item".into())]);
     let (a, b): (i64, i64) = s
         .eval("local f = function(...) return arg[1], arg[3] end return f(GetGMTicketCategories())")
@@ -55,8 +45,7 @@ fn the_ids_are_the_dbc_ids_not_list_positions() {
     assert_eq!((a, b), (10, 4), "ids and order pass through untouched");
 }
 
-/// No catalog is not an error: the window paints no category rows and cannot raise. This is the
-/// bare-XML harness, and a run with no client data.
+/// The bare-XML harness and a run with no client data have no catalog.
 #[test]
 fn an_absent_catalog_returns_nothing_rather_than_erroring() {
     let s = script();
@@ -66,9 +55,7 @@ fn an_absent_catalog_returns_nothing_rather_than_erroring() {
     assert_eq!(n, 0);
 }
 
-/// **The verbs queue, they do not latch.** Two `GetGMTicket()` calls are two packets, because the
-/// ticket toast re-polls every 10 minutes from `TicketStatus_OnUpdate` — a latch would collapse the
-/// second poll into the first and the window would look hung.
+/// Two `GetGMTicket()` calls are two packets: `TicketStatus_OnUpdate` re-polls every 10 minutes.
 #[test]
 fn the_payload_free_verbs_queue_rather_than_latch() {
     let mut s = script();
@@ -84,15 +71,11 @@ fn the_payload_free_verbs_queue_rather_than_latch() {
         ]
     );
     assert_eq!(s.take_stuck_casts(), 3, "Stuck is not a ticket verb");
-    // Drained means drained — the next frame must not re-send.
     assert!(s.take_gm_ticket_intents().is_empty());
     assert_eq!(s.take_stuck_casts(), 0);
 }
 
-/// **Call order is wire order.** A chunk that abandons and then re-asks must reach the server in
-/// that order — reversed, the get answers with the state *before* the delete and the window is
-/// told it still has the ticket it just abandoned. Per-verb drains cannot express this, which is
-/// why there is one queue (decision 1673).
+/// Call order is wire order: reversed, the get would answer with the ticket just deleted.
 #[test]
 fn the_queue_preserves_call_order_across_different_verbs() {
     let mut s = script();
@@ -103,15 +86,13 @@ fn the_queue_preserves_call_order_across_different_verbs() {
         "delete first, exactly as Lua called them"
     );
 
-    // And the other way round, so the test cannot pass on a fixed per-verb ordering that merely
-    // happens to match one of the two cases.
+    // The other way round, so a fixed per-verb order cannot pass.
     s.run("GetGMTicket() DeleteGMTicket()").unwrap();
     assert_eq!(
         s.take_gm_ticket_intents(),
         vec![GmTicketIntent::Ask, GmTicketIntent::Delete]
     );
 
-    // Writes interleave with the bare verbs on the same queue.
     s.run("NewGMTicket(1, \"a\") GetGMTicket()").unwrap();
     assert!(matches!(
         s.take_gm_ticket_intents().as_slice(),
@@ -119,9 +100,7 @@ fn the_queue_preserves_call_order_across_different_verbs() {
     ));
 }
 
-/// **The window's verb survives to the app.** `NewGMTicket` and `UpdateGMTicket` share a signature
-/// but not an opcode, and the shipped window picks between them from its own `hasTicket` flag —
-/// so the choice is carried, never re-derived from what the client believes.
+/// Same signature, different opcodes; the stock window picks one from its own `hasTicket` flag.
 #[test]
 fn new_and_update_are_distinguishable_and_keep_their_order() {
     let mut s = script();
@@ -144,10 +123,9 @@ fn new_and_update_are_distinguishable_and_keep_their_order() {
     );
 }
 
-/// The Era arity is `(number, string)` — the reference's own usage string is
-/// `Usage: UpdateGMTicket(type, text)`. An empty ticket is the *window's* refusal to make, not
-/// ours: the binding queues whatever it is handed, and the engine's own emptiness check sits
-/// upstream of the send.
+/// The reference's usage string is `Usage: UpdateGMTicket(type, text)`. The binding queues any
+/// text; the reference refuses an empty one before the send (`ERR_TICKET_NO_TEXT`, `0x5ef808`,
+/// `0x5efae7`).
 #[test]
 fn an_empty_ticket_body_is_queued_not_swallowed() {
     let mut s = script();
diff --git a/crates/benilla-ui/src/script/tests/handler_prof.rs b/crates/benilla-ui/src/script/tests/handler_prof.rs
index 171daf99..3e741447 100644
--- a/crates/benilla-ui/src/script/tests/handler_prof.rs
+++ b/crates/benilla-ui/src/script/tests/handler_prof.rs
@@ -1,22 +1,16 @@
-//! Per-handler cost attribution (decision 1395) — the instrument that answers *which* handler.
-//!
-//! These assert on **names, call counts, and the self/total relation**, never on a duration
-//! (0735): "this handler cost 2 ms" is not a fact a test can own. The one relational assertion
-//! (`self < total` under nesting) carries its own exact control — the same shape with nothing
-//! nested inside it must report `self == total` to the last nanosecond, which is what proves the
-//! difference came from the subtraction rather than from the clock.
+//! Per-handler cost attribution. The tests assert names, call counts and the self/total relation,
+//! never a duration; `self == total` with nothing nested is the control for `self < total`.
 
 use super::common::script;
 use crate::script::{HandlerRow, ScriptValue, UiScript};
 
-/// The row for `frame:script`, or `None`.
 fn row(rows: &[HandlerRow], frame: &str, script: &str) -> Option<HandlerRow> {
     rows.iter()
         .find(|r| r.frame == frame && r.script == script)
         .cloned()
 }
 
-/// Recording, with no periodic report — the tests read the window directly.
+/// Recording, with no periodic report: the tests read the window directly.
 fn armed() -> UiScript {
     let s = script();
     s.profile_handlers(true, 0.0);
@@ -69,8 +63,7 @@ fn every_fired_handler_is_attributed_to_its_own_frame_and_script() {
 
 #[test]
 fn a_handler_with_nothing_nested_inside_it_is_all_self_time() {
-    // The control for the nesting test below: with no nested fire, the subtraction is by zero and
-    // the two numbers must be *identical*, not merely close.
+    // The control for the nesting test: nothing nested subtracts zero, so the two are identical.
     let mut s = armed();
     s.run(
         r#"
@@ -122,14 +115,13 @@ fn a_handler_that_fires_another_is_not_charged_for_its_child() {
         outer.self_us < outer.total_us,
         "the child's cost must come off the parent's self time: {outer:#?}"
     );
-    // And the nested row must be the one holding it — the whole point is naming Inner, not Outer.
     assert!(
         inner.self_us > 0.0,
         "the child's own cost lands on the child: {inner:#?}"
     );
 
-    // A second tick must behave like the first: a leaked stack level would start charging Outer's
-    // child time to a phantom parent and the relation above would quietly stop holding.
+    // A second tick behaves like the first: a leaked stack level would charge the child's time to
+    // a phantom parent.
     s.tick(0.016);
     let rows = s.handler_profile();
     let outer = row(&rows, "Outer", "OnUpdate").expect("outer");
@@ -140,8 +132,7 @@ fn a_handler_that_fires_another_is_not_charged_for_its_child() {
 
 #[test]
 fn an_anonymous_frames_handler_is_labelled_by_where_it_was_written() {
-    // `CreateFrame("Frame")` + OnUpdate with no name is the addon timer idiom, so this is the
-    // common case, not the exotic one — and `#4127` would be an unusable row.
+    // An unnamed frame's OnUpdate is the addon timer idiom, and `#4127` would be a useless label.
     let mut s = armed();
     s.run(
         r#"
@@ -164,9 +155,8 @@ fn an_anonymous_frames_handler_is_labelled_by_where_it_was_written() {
 
 #[test]
 fn an_unarmed_vm_records_nothing() {
-    // The off-state is the shipped state, so it gets a guard of its own: a VM that was never armed
-    // must report an empty profile even while another VM in this process is recording (the gate is
-    // process-wide, the state is per-VM — see `handler_prof::ARMED`).
+    // An unarmed VM records nothing while another records: the gate (`handler_prof::ARMED`) is
+    // process-wide, the state per VM.
     let _recording = armed();
     let mut s = script();
     s.run(
diff --git a/crates/benilla-ui/src/script/tests/input.rs b/crates/benilla-ui/src/script/tests/input.rs
index f38b04d9..6f94e00a 100644
--- a/crates/benilla-ui/src/script/tests/input.rs
+++ b/crates/benilla-ui/src/script/tests/input.rs
@@ -1,4 +1,4 @@
-//! Input / hit-testing (decision 0068; spec-faithful, not byte-pinned).
+//! Mouse input: hit order, hover, clicks, double clicks and the release capture.
 
 use super::common::script;
 
@@ -38,11 +38,8 @@ fn enable_mouse_gates_hit_testing() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The hit sweep's key, all three terms: strata, then level, then — at a tie — the **earlier-linked**
-/// frame, NOT the later one that draws on top (decision 1816; `0x764aa0`'s strict `ja` appending
-/// equal keys and `0x7660d0` sweeping from index 0). This test used to assert the opposite at the
-/// tie and was named for it — draw order and hit order agree on strata and level and disagree on
-/// exactly this.
+/// At a strata and level tie the earlier-linked frame takes the hit, though the later one draws on
+/// top: `0x764aa0` appends equal keys after (strict `ja`) and `0x7660d0` sweeps from index 0.
 #[test]
 fn hit_order_is_strata_then_level_then_the_earlier_linked_frame() {
     let mut s = script();
@@ -61,24 +58,21 @@ fn hit_order_is_strata_then_level_then_the_earlier_linked_frame() {
     .unwrap();
     s.resolve();
 
-    // Same strata/level: A was linked FIRST, so the sweep reaches it first and it captures —
-    // even though B, linked later, draws on top of it.
+    // Same strata and level: A, linked first, captures though B draws on top.
     s.mouse_move(400.0, 300.0);
     assert_eq!(s.eval::<String>("return who").unwrap(), "A");
 
     // Move off everything to clear the mouseover (fires OnLeave, resets focus) before re-testing.
     s.mouse_move(-10.0, -10.0);
 
-    // Raise A above B by strata (no rect change ⇒ no re-resolve needed): strata outranks the tie,
-    // and A keeps the point for the stronger reason.
+    // Strata outranks the tie; no rect changes, so no re-resolve.
     s.run("A:SetFrameStrata('DIALOG')").unwrap();
     s.mouse_move(400.0, 300.0);
     assert_eq!(s.eval::<String>("return who").unwrap(), "A");
 
     s.mouse_move(-10.0, -10.0);
 
-    // Put B in the same (DIALOG) strata but a higher frame level: level outranks link order, so
-    // B takes it back — the tie rule only decides frames that are equal on both.
+    // Same strata, higher level: level outranks link order, so B captures.
 
     s.run("B:SetFrameStrata('DIALOG'); B:SetFrameLevel(10)")
         .unwrap();
@@ -137,13 +131,11 @@ fn onclick_fires_on_press_release_same_frame_not_when_release_lands_elsewhere()
     .unwrap();
     s.resolve();
 
-    // Press + release both on A ⇒ OnClick on A (button arg == "LeftButton").
     s.mouse_button(200.0, 300.0, "LeftButton", true);
     s.mouse_button(200.0, 300.0, "LeftButton", false);
     assert_eq!(s.eval::<i64>("return clicks_a").unwrap(), 1);
     assert_eq!(s.eval::<String>("return click_btn").unwrap(), "LeftButton");
 
-    // Press on A, release on B ⇒ no OnClick on either frame.
     s.mouse_button(200.0, 300.0, "LeftButton", true);
     s.mouse_button(600.0, 300.0, "LeftButton", false);
     assert_eq!(
@@ -225,8 +217,8 @@ fn mouse_wheel_passes_delta_to_the_captured_frame() {
 fn hit_rect_insets_shrink_the_mouse_rect_only() {
     let mut s = script();
     s.set_screen_size(800.0, 600.0);
-    // A 100×100 frame at the origin with the micro-button shape: an 18-unit dead header at the
-    // top, and 5 off each other side.
+    // A 100×100 frame at the origin; the top inset is the micro buttons' 18
+    // (`MainMenuBarMicroButtons.xml:9`), with 5 off each other side.
     s.run(
         r#"
         entered = false
@@ -241,24 +233,20 @@ fn hit_rect_insets_shrink_the_mouse_rect_only() {
     .unwrap();
     s.resolve();
 
-    // Geometry is untouched — insets move the MOUSE rect, never the frame.
     assert_eq!(s.eval::<f64>("return A:GetHeight()").unwrap(), 100.0);
     assert_eq!(s.eval::<f64>("return A:GetTop()").unwrap(), 100.0);
 
-    // Inside the frame but inside the dead header ⇒ no capture (the case the ref's top=18 buys:
-    // the empty band above a micro button's art must not eat the click).
     assert!(
         s.hit_test(50.0, 90.0).is_none(),
         "a point in the inset header is outside the hit rect"
     );
     assert!(s.mouse_move(50.0, 90.0).is_none());
     assert!(!s.eval::<bool>("return entered").unwrap());
-    // …and each of the other three insets bites too.
     assert!(s.hit_test(2.0, 50.0).is_none(), "left inset");
     assert!(s.hit_test(98.0, 50.0).is_none(), "right inset");
     assert!(s.hit_test(50.0, 2.0).is_none(), "bottom inset");
 
-    // Just below the header, still inside the shrunken rect ⇒ captures.
+    // Just below the header, inside the shrunken rect: captures.
     assert!(s.hit_test(50.0, 80.0).is_some());
     assert!(s.mouse_move(50.0, 80.0).is_some());
     assert!(s.eval::<bool>("return entered").unwrap());
@@ -277,13 +265,6 @@ fn hit_rect_insets_default_to_zero() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// `EnableMouseWheel`/`IsMouseWheelEnabled` round-trip, and the two kinds born wheel-enabled
-/// (decision 1198).
-///
-/// The flag is real and settable; **the dispatch is deliberately not gated on it yet** — see
-/// `object::frame_state`'s note for the 44 shipped `OnMouseWheel` sites that declare no
-/// `enableMouseWheel` and the concrete condition for flipping it. This test pins the flag's own
-/// behaviour so that flip is a one-line change with a test already standing behind it.
 #[test]
 fn the_mouse_wheel_flag_round_trips_and_the_scrolling_kinds_are_born_enabled() {
     let s = script();
@@ -296,12 +277,11 @@ fn the_mouse_wheel_flag_round_trips_and_the_scrolling_kinds_are_born_enabled() {
     )
     .unwrap();
 
-    // A plain frame is born wheel-deaf, like WoW's own default.
+    // A plain frame is born wheel-disabled, as in the reference; the two scrolling kinds' own
+    // constructors enable it.
     assert!(!s
         .eval::<bool>("return Plain:IsMouseWheelEnabled()")
         .unwrap());
-    // ...and the two kinds whose ctor takes the wheel are born enabled, the same by-construction
-    // argument `mouse_enabled` already makes for a Button.
     assert!(s
         .eval::<bool>("return Scroll:IsMouseWheelEnabled()")
         .unwrap());
@@ -323,14 +303,8 @@ fn the_mouse_wheel_flag_round_trips_and_the_scrolling_kinds_are_born_enabled() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// A closed-vocabulary attribute survives stray whitespace (decision 1204).
-///
-/// The corpus case: `zBar.xml:146` — a shipped, working 1.12 addon — declares
-/// `frameStrata="BACKGROUND "` with a trailing space. The real client took it; we refused, and the
-/// refusal took the frame's whole `<Frames>` subtree with it, so the addon never loaded at all.
-///
-/// The three parsers are covered together because the next one to meet a stray space should not
-/// need its own bug report.
+/// The reference takes a closed-vocabulary value with stray whitespace: the zBar addon ships
+/// `frameStrata="BACKGROUND "` (`zBar.xml:146`). Frame kind, strata and draw layer all trim.
 #[test]
 fn an_enum_attribute_tolerates_the_whitespace_a_real_addon_ships() {
     let s = script();
@@ -348,24 +322,19 @@ fn an_enum_attribute_tolerates_the_whitespace_a_real_addon_ships() {
         "BACKGROUND",
         "the frame took the strata, and reports it in the canonical spelling"
     );
-    // ...and the padded frame KIND resolved too — an unknown kind raises from CreateFrame, so
-    // reaching this line at all is the assertion.
+    // The padded kind resolved: an unknown kind would have raised from `CreateFrame`.
     assert!(s.eval::<bool>("return PaddedKind ~= nil").unwrap());
     assert!(s.eval::<bool>("return PaddedTex ~= nil").unwrap());
 }
 
-// ── OnDoubleClick — the corpus's biggest script gap (250 sites / 85 addons) ───────────────────
+// ── OnDoubleClick ──
 //
-// Every rule below is byte-verified: the interval is a hardcoded **300 ms**
-// (`0x77937b cmp ecx, 0x12c`), the fire site is the mouse-**UP** dispatcher `0x7792d0` alone, the
-// double leg **replaces** the second `OnClick` (`0x77939d jmp` past `call [edx+0x94]`), a completed
-// double **zeroes** the stamp so clicks pair up, the detector is armed only when the frame carries
-// an `OnDoubleClick` script (`[+0x4d4] != 0`), and it carries **no button identity** — what
-// normally confines it to the left button is `RegisterForClicks`, not the detector.
+// The interval is a fixed 300 ms (`0x77937b`, `cmp ecx, 0x12c`) and the only fire site is the
+// mouse-up dispatcher `0x7792d0`. The double replaces the second `OnClick` (`0x77939d` jumps past
+// it), a completed double zeroes the stamp so clicks pair up, the detector arms only when the frame
+// has an `OnDoubleClick` script (`[+0x4d4] != 0`), and it keys on no button: `RegisterForClicks`
+// is what confines it to the left button.
 
-/// Two fast clicks fire `OnDoubleClick(self, button)` — and the second `OnClick` does **not** fire,
-/// because the two legs are exclusive. (This was the interim implementation's mistake: it fired
-/// both, on the press edge, at 500 ms. All three were corrected at the bytes.)
 #[test]
 fn a_second_fast_click_fires_on_double_click_instead_of_the_second_on_click() {
     let mut s = script();
@@ -382,7 +351,6 @@ fn a_second_fast_click_fires_on_double_click_instead_of_the_second_on_click() {
     .unwrap();
     s.resolve();
 
-    // Click one. Note the press alone does nothing: the fire site is the mouse-UP dispatcher.
     s.mouse_button(50.0, 50.0, "LeftButton", true);
     assert_eq!(
         s.eval::<i64>("return clicks").unwrap(),
@@ -419,10 +387,8 @@ fn a_second_fast_click_fires_on_double_click_instead_of_the_second_on_click() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **The gate that keeps rapid clicking from breaking every button in the UI.** The binary's chain
-/// tests `[+0x4d4] != 0`, so a widget with no `OnDoubleClick` script takes the single leg every
-/// time. Without that test, the exclusivity above would silently swallow every second `OnClick` on
-/// every frame in the game.
+/// The detector tests `[+0x4d4] != 0`, so a widget with no `OnDoubleClick` script always takes
+/// the single-click leg.
 #[test]
 fn a_frame_with_no_double_click_handler_keeps_every_rapid_on_click() {
     let mut s = script();
@@ -449,9 +415,6 @@ fn a_frame_with_no_double_click_handler_keeps_every_rapid_on_click() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The boundary: too slow, a different frame, and the PAIRING rule (a completed double zeroes the
-/// stamp, so four rapid clicks read Click · Double · Click · Double — there is no triple-click and
-/// no run of doubles).
 #[test]
 fn the_double_click_boundary_is_time_and_frame_and_clicks_pair_up() {
     let mut s = script();
@@ -476,14 +439,14 @@ fn the_double_click_boundary_is_time_and_frame_and_clicks_pair_up() {
         s.mouse_button(x, 50.0, "LeftButton", false);
     };
 
-    // (1) TOO SLOW — 0.35 s > 300 ms, so the second click is a fresh first half.
+    // (1) Too slow: 0.35 s is past the 300 ms, so the second click starts afresh.
     click(&mut s, 50.0);
     s.tick(0.35);
     click(&mut s, 50.0);
     assert_eq!(s.eval::<i64>("return doubles").unwrap(), 0);
     assert_eq!(s.eval::<i64>("return clicks").unwrap(), 2);
 
-    // (2) A DIFFERENT FRAME — fast, but the timestamp lives on the WIDGET, so B has its own.
+    // (2) A different frame: the stamp lives on the widget, so B has its own.
     s.run("clicks, doubles = 0, 0").unwrap();
     s.tick(1.0);
     click(&mut s, 50.0);
@@ -491,7 +454,7 @@ fn the_double_click_boundary_is_time_and_frame_and_clicks_pair_up() {
     assert_eq!(s.eval::<i64>("return doubles").unwrap(), 0);
     assert_eq!(s.eval::<i64>("return clicks").unwrap(), 2);
 
-    // (3) PAIRING — four rapid clicks on one frame are Click · Double · Click · Double.
+    // (3) Pairing: four rapid clicks on one frame are click, double, click, double.
     s.run("clicks, doubles = 0, 0").unwrap();
     s.tick(1.0);
     for _ in 0..4 {
@@ -508,11 +471,8 @@ fn the_double_click_boundary_is_time_and_frame_and_clicks_pair_up() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **The detector carries no button identity** — the surprising half of the law, and the one an
-/// implementation keyed by mouse button would get wrong. `[CButton+0x334]` is a bare timestamp, so
-/// a widget registered for two `…Up` types completes a double click across them, with `arg1` = the
-/// button of the SECOND click. A stock button never sees this only because `RegisterForClicks`
-/// defaults to `{"LeftButtonUp"}`.
+/// `[CButton+0x334]` is a bare timestamp, so a button registered for two `…Up` types completes a
+/// double click across them, and `arg1` is the second click's button.
 #[test]
 fn a_multi_registered_button_pairs_a_left_click_with_a_right_one() {
     let mut s = script();
@@ -542,10 +502,9 @@ fn a_multi_registered_button_pairs_a_left_click_with_a_right_one() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **Nothing clears a half-finished double click** — not hide, not disable, not the cursor leaving
-/// the window. `[+0x334]` has three writers image-wide and none of them is any of those, so this
-/// pins the *absence* of the tidy-up that looks like it belongs in
-/// [`crate::script::UiScript::pointer_left_window`].
+/// Nothing clears a half-finished double click, not hide, disable or the cursor leaving the
+/// window: none of `[+0x334]`'s three writers is one of those, so
+/// [`crate::script::UiScript::pointer_left_window`] must not reset it.
 #[test]
 fn a_half_finished_double_click_survives_the_cursor_leaving_the_window() {
     let mut s = script();
@@ -573,9 +532,7 @@ fn a_half_finished_double_click_survives_the_cursor_leaving_the_window() {
     );
 }
 
-/// The load-bearing regression guard for the whole job: accepting `OnDoubleClick` in
-/// `SCRIPT_KINDS` without wiring the detector would make this test's `SetScript` succeed and its
-/// handler never run — the silent-capability trap. Asserting the *fire* is what makes the row real.
+/// A name in `SCRIPT_KINDS` must have something that fires it, so this asserts the fire.
 #[test]
 fn set_script_on_double_click_is_accepted_because_something_fires_it() {
     let mut s = script();
@@ -602,30 +559,16 @@ fn set_script_on_double_click_is_accepted_because_something_fires_it() {
     assert!(s.eval::<bool>("return ran").unwrap(), "…and it FIRED");
 }
 
-/// The script names that deliberately still raise, and why each is out (the reasons live at
-/// `object::events_regions::set_script`). This is the other half of the rule "a name is accepted
-/// only once something fires it": a future widening has to delete a line here, which is exactly
-/// the moment to check something fires it.
+/// Script names nothing fires still raise; a name leaves this list only when something fires it.
 #[test]
 fn the_unfired_script_kinds_still_raise_rather_than_silently_accepting() {
     let s = script();
     s.run(r#"Raiser = CreateFrame("EditBox", "RaiserBox")"#)
         .unwrap();
     for name in [
-        // `OnKeyDown`/`OnKeyUp`/`OnChar` are NOT in this list any more: decision 1319 built the
-        // delivery walk, so they are fired and therefore accepted — the rule this test enforces,
-        // applied in the other direction. Their law lives in `script::tests::keyboard`.
-        //
-        // `OnCursorChanged` left this list with decision 2141: the tick's caret flush fires it
-        // (`editbox::drain_cursor_changed`), which is the rule applied in the other direction
-        // again — its law lives in `script::editbox::tests`.
-        //
-        // 2.0's secure-frame system — no such slot exists in any 1.12 resolver.
+        // A 2.0 secure-frame slot; no 1.12 resolver has it.
         "OnAttributeChanged",
-        // Real 1.12 slots we do not fire, and zero corpus call sites. (`OnUpdateModel` and
-        // `OnAnimFinished` left this list with decision 2007: the tick's model pass fires
-        // them — `script::tests::model_clock`. `OnHorizontalScroll` left it with the ScrollFrame's
-        // horizontal offset pair, which fires it — `script::tests::scrollframe`.)
+        // Real 1.12 slots that benilla does not fire.
         "OnHyperlinkEnter",
         "OnMessageScrollChanged",
         "OnInputLanguageChanged",
@@ -640,10 +583,8 @@ fn the_unfired_script_kinds_still_raise_rather_than_silently_accepting() {
     }
 }
 
-/// The hover-hide law: hiding the hovered frame fires its `OnLeave` synchronously, BEFORE its own
-/// `OnHide` (`0x764ba0`'s kind-2 tail runs mid-hide, the leave at `0x764cce`; OnHide fires at the
-/// hide body's tail) — and an ancestor's `Hide()` reaches the hovered descendant through the
-/// cascade.
+/// Hiding the hovered frame fires its `OnLeave` inside the hide, before its `OnHide` (`0x764ba0`'s
+/// removal tail, the leave at `0x764cce`), and an ancestor's `Hide()` reaches it by the cascade.
 #[test]
 fn hiding_the_hovered_frame_fires_its_onleave_before_onhide() {
     let mut s = script();
@@ -662,7 +603,7 @@ fn hiding_the_hovered_frame_fires_its_onleave_before_onhide() {
     .unwrap();
     s.resolve();
     s.mouse_move(150.0, 150.0); // hover the slot
-    s.run("Win:Hide()").unwrap(); // the ANCESTOR hides — the cascade reaches the slot
+    s.run("Win:Hide()").unwrap(); // the ancestor hides; the cascade reaches the slot
     assert_eq!(
         s.eval::<String>("return table.concat(log, ',')").unwrap(),
         "leave,hide",
@@ -671,9 +612,8 @@ fn hiding_the_hovered_frame_fires_its_onleave_before_onhide() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The removal tail's own DISABLED case: `0x764cce` dispatches `[edx+0x50]` **virtually**, so a
-/// Button lands in `0x7794e0` and the guard swallows the leave there too. The `OnHide` half is the
-/// control — that one is not the hover notify and fires either way.
+/// `0x764cce` dispatches the leave virtually (`[edx+0x50]`), so a disabled Button's own guard
+/// (`0x7794e0`) swallows it; `OnHide` is not the hover notify and fires either way.
 #[test]
 fn hiding_a_hovered_disabled_button_fires_onhide_but_no_onleave() {
     let mut s = script();
@@ -700,8 +640,7 @@ fn hiding_a_hovered_disabled_button_fires_onhide_but_no_onleave() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The negative: hiding a frame the cursor is NOT over fires no OnLeave (the reference's removal
-/// tail acts only when the removed frame IS the cached hover).
+/// The reference's removal tail acts only when the removed frame is the cached hover.
 #[test]
 fn hiding_an_unhovered_frame_fires_no_onleave() {
     let mut s = script();
@@ -722,10 +661,9 @@ fn hiding_an_unhovered_frame_fires_no_onleave() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The re-pick (`[root+0x1100]` + the pump tail `0x7660d0` on the SAVED event): after the hovered
-/// frame hides, the next tick re-hovers whatever is now topmost at the unchanged cursor — OnEnter
-/// with no physical mouse move. And the symmetric insert law: a frame SHOWN under a stationary
-/// cursor gets hovered on the next tick too (`0x764b8d`).
+/// After the hovered frame hides, the next tick re-hovers what is topmost at the unmoved cursor
+/// (`[root+0x1100]`, the pump tail `0x7660d0` on the saved event); a frame shown under the cursor
+/// is hovered the same way (`0x764b8d`).
 #[test]
 fn the_repick_re_hovers_without_a_mouse_move() {
     let mut s = script();
@@ -748,14 +686,13 @@ fn the_repick_re_hovers_without_a_mouse_move() {
     s.resolve();
     s.mouse_move(150.0, 150.0); // hovers Over (topmost)
     s.run("Over:Hide()").unwrap();
-    s.tick(0.016); // the pump's re-pick — cursor has not moved
+    s.tick(0.016); // the pump's re-pick; the cursor has not moved
     assert_eq!(
         s.eval::<String>("return table.concat(entered, ',')")
             .unwrap(),
         "over,under",
         "the frame beneath is entered on the next tick with no mouse move"
     );
-    // The insert half: re-showing the top frame under the stationary cursor re-hovers it.
     s.run("Over:Show()").unwrap();
     s.tick(0.016);
     assert_eq!(
@@ -767,9 +704,7 @@ fn the_repick_re_hovers_without_a_mouse_move() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The mouse-UP dispatch law (decision 1599) — byte-verified at `0x766420`
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The mouse-up dispatch (`0x766420`) ──
 
 /// Two side-by-side frames, each recording every `OnMouseDown`/`OnMouseUp` it gets.
 fn two_frames() -> crate::script::UiScript {
@@ -798,14 +733,9 @@ fn log_of(s: &mut crate::script::UiScript) -> String {
     s.eval::<String>("return table.concat(log, ' ')").unwrap()
 }
 
-/// **The release goes to the frame that took the press, wherever the cursor has got to.** The
-/// client's `0x766420` snapshots `[mgr+0x80]` — the capture — at entry (`0x76642b`) and dispatches
-/// through it alone; `[mgr+0x7c]`, the hover frame, is never read in the whole function. So B, which
-/// the cursor is over at release, gets nothing on that edge.
-///
-/// The concrete thing this buys: a chat window's 16×16 resize grip is pulled out from under the
-/// cursor the instant the size clamps at a resize bound, and its `OnMouseUp → FCF_StopResize` has
-/// to run anyway or the sizing drag is held for the rest of the session.
+/// `0x766420` reads the capture `[mgr+0x80]` at entry (`0x76642b`) and never the hover
+/// `[mgr+0x7c]`, so the release reaches the pressed frame wherever the cursor is; a chat resize
+/// grip's `FCF_StopResize` relies on it (`FloatingChatFrame.xml:292`).
 #[test]
 fn the_release_goes_to_the_frame_that_took_the_press() {
     let mut s = two_frames();
@@ -819,13 +749,8 @@ fn the_release_goes_to_the_frame_that_took_the_press() {
     );
 }
 
-/// **A press that captured nothing fires nothing on release** — and this is the half that is easy
-/// to get wrong, because the DOWN handler *does* have a hover fallback (`root+0x80` else
-/// `root+0x7c`) and the UP handler does **not** share it: `0x766498 test ebx,ebx / je 0x7664cd`
-/// returns with no virtual call at all.
-///
-/// This shipped briefly as `captured.or(hit)` — a press over open space then delivered its release
-/// to whatever the cursor had wandered onto, which is a frame that never saw the press.
+/// The down handler falls back to the hover (`root+0x80` else `root+0x7c`), the up handler does
+/// not: with no capture, `0x766498` jumps to `0x7664cd` and dispatches nothing.
 #[test]
 fn a_press_that_captured_nothing_delivers_no_release() {
     let mut s = two_frames();
@@ -839,7 +764,6 @@ fn a_press_that_captured_nothing_delivers_no_release() {
     );
 }
 
-/// The ordinary case still behaves: press and release on the same frame is down-then-up on it.
 #[test]
 fn a_press_and_release_on_one_frame_is_unchanged() {
     let mut s = two_frames();
@@ -848,15 +772,13 @@ fn a_press_and_release_on_one_frame_is_unchanged() {
     assert_eq!(log_of(&mut s), "A:down A:up");
 }
 
-/// The capture is **per button**, so a right-button release cannot be answered by a left-button
-/// press's capture — `Model::mouse_down_on` is keyed by button name, which is what makes this fall
-/// out rather than needing its own arm.
+/// `Model::mouse_down_on` is keyed by button name, so the capture is per button.
 #[test]
 fn the_capture_is_per_button() {
     let mut s = two_frames();
-    s.mouse_button(200.0, 300.0, "LeftButton", true); // A holds the LEFT button
+    s.mouse_button(200.0, 300.0, "LeftButton", true); // A holds the left button
     s.mouse_move(500.0, 300.0);
-    s.mouse_button(500.0, 300.0, "RightButton", false); // a RIGHT release, never pressed
+    s.mouse_button(500.0, 300.0, "RightButton", false); // a right release, never pressed
     assert_eq!(
         log_of(&mut s),
         "A:down",
@@ -864,16 +786,9 @@ fn the_capture_is_per_button() {
     );
 }
 
-/// **A DISABLED Button runs neither `<OnEnter>` nor `<OnLeave>`** — `CSimpleButton::OnEnter
-/// 0x779490` / `OnLeave 0x7794e0` open `mov eax,[esi+0x328]; test eax,eax; je`, branching past the
-/// base notify that owns both script slots (`0x76b6a0`/`0x76b6f0`). It
-/// still TAKES the hover, because the walk reassigns `[root+0x7c]` before it fires the notify.
-///
-/// The customer is every 1.12 addon that wrote `if this:IsEnabled() then` at the top of an
-/// `<OnEnter>` and expected it to be false: `IsEnabled()` is the NUMBER `1`/`0`, always truthy, so
-/// the body runs unless the ENGINE holds it back. AtlasLoot's four QuickLook buttons are the live
-/// case — unset, they disable themselves in `<OnShow>` and their `<OnEnter>` indexes a nil
-/// `AtlasLootCharDB.QuickLooks[n]`.
+/// A disabled Button fires neither `OnEnter` nor `OnLeave`: `CSimpleButton::OnEnter` (`0x779490`)
+/// and `OnLeave` (`0x7794e0`) test `[esi+0x328]` and skip the base notify (`0x76b6a0`,
+/// `0x76b6f0`). It still takes the hover: the walk sets `[root+0x7c]` before the notify.
 #[test]
 fn a_disabled_button_takes_the_hover_but_fires_no_enter_or_leave() {
     let mut s = script();
@@ -912,7 +827,6 @@ fn a_disabled_button_takes_the_hover_but_fires_no_enter_or_leave() {
         "entering a disabled button fires nothing"
     );
 
-    // Leaving it is as silent as entering it, and the enabled neighbour is the control.
     s.mouse_move(250.0, 50.0);
     assert_eq!(
         s.eval::<String>("return table.concat(log, ',')").unwrap(),
@@ -920,7 +834,7 @@ fn a_disabled_button_takes_the_hover_but_fires_no_enter_or_leave() {
         "no leave from the disabled button; the enabled one notifies normally"
     );
 
-    // Disabled WHILE hovered: the leave is gated on the state at leave time, not at enter time.
+    // Disabled while hovered: the leave is gated on the state at leave time.
     s.run("On:Disable()").unwrap();
     s.mouse_move(400.0, 50.0);
     assert_eq!(
diff --git a/crates/benilla-ui/src/script/tests/keyboard.rs b/crates/benilla-ui/src/script/tests/keyboard.rs
index f3e2eed9..e1d2571a 100644
--- a/crates/benilla-ui/src/script/tests/keyboard.rs
+++ b/crates/benilla-ui/src/script/tests/keyboard.rs
@@ -1,13 +1,8 @@
-//! The frame keyboard delivery law (decision 1319; the walk `0x765f10`, the existence gate
-//! `0x76b7d0`).
-//!
-//! Each test pins one clause that a plausible-but-wrong implementation gets backwards.
+//! Frame keyboard delivery: the walk (`0x765f10`) and its existence gate (`0x76b7d0`).
 
 use super::common::script;
 
-/// The bucket gate (`0x76af00`): membership is the **keyboard-enabled flag**, not the presence of a
-/// script. A Lua-created frame auto-enables nothing (the reference's `SetScript` doesn't either),
-/// so its handler is unreachable until `EnableKeyboard(true)` puts it in the walk.
+/// Bucket membership (`0x76af00`) is the keyboard-enabled flag, which `SetScript` never sets.
 #[test]
 fn a_key_script_alone_does_not_put_a_frame_in_the_walk() {
     let mut s = script();
@@ -37,9 +32,8 @@ fn a_key_script_alone_does_not_put_a_frame_in_the_walk() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The existence gate's asymmetry (`0x76b7d0`): a frame carrying **only** an `OnKeyUp` consumes
-/// every key-down and runs nothing. This is the clause an implementation "tidies away" — and doing
-/// so silently un-suppresses that frame's keybindings.
+/// The existence gate (`0x76b7d0`) takes either key slot, so a frame with only an `OnKeyUp`
+/// consumes every key-down and runs nothing.
 #[test]
 fn only_an_onkeyup_still_swallows_the_key_down() {
     let mut s = script();
@@ -59,15 +53,12 @@ fn only_an_onkeyup_still_swallows_the_key_down() {
         "…and fires nothing"
     );
 
-    // Neither slot: declines outright.
     s.run("f:SetScript(\"OnKeyUp\", nil)").unwrap();
     assert!(!s.key_input("ESCAPE"), "no key slot at all: declines");
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The walk order (`0x765f10`, `0x764ae2`): **strata descending first**, and only then level. A LOW
-/// frame can never take a key from a HIGH one, however high its level — the same "a raise never
-/// changes stratum" shape the toplevel law has.
+/// The walk (`0x765f10`, `0x764ae2`) runs strata descending, then level, then registration order.
 #[test]
 fn the_walk_is_strata_then_level_then_registration() {
     let mut s = script();
@@ -95,7 +86,6 @@ fn the_walk_is_strata_then_level_then_registration() {
         "strata beats level"
     );
 
-    // Within one stratum: higher level wins, and equal levels keep registration order.
     s.run(
         r#"
         winner = nil
@@ -113,8 +103,7 @@ fn the_walk_is_strata_then_level_then_registration() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **At most one frame consumes** (`0x765f10`): the walk stops at the first consumer, so a second
-/// keyboard frame below it never sees the key.
+/// The walk stops at the first consumer (`0x765f10`).
 #[test]
 fn the_first_consumer_ends_the_walk() {
     let mut s = script();
@@ -138,8 +127,7 @@ fn the_first_consumer_ends_the_walk() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// A hidden frame is in no bucket (the link gate the walk shares with the draw order), so it
-/// neither fires nor consumes — and the frame below it gets the key instead.
+/// The walk shares the draw order's link gate, so a hidden frame is in no bucket.
 #[test]
 fn a_hidden_frame_is_not_in_the_walk() {
     let mut s = script();
@@ -164,8 +152,7 @@ fn a_hidden_frame_is_not_in_the_walk() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// A raising handler must not eat the key or abort the walk's caller: the error is recorded, the
-/// frame still consumed (consumption is the C++ gate's, never the handler's — `0x7026f0`).
+/// Consumption is the gate's decision, never the handler's (`0x7026f0`).
 #[test]
 fn a_raising_handler_still_consumes_and_is_recorded() {
     let mut s = script();
@@ -185,16 +172,9 @@ fn a_raising_handler_still_consumes_and_is_recorded() {
     );
 }
 
-/// **A `CSimpleEditBox` in the walk is asked about FOCUS, never about a script slot** (the vtable
-/// slot `0x77a900`). Its ctor registers it in both key buckets, and vtable `0x81c910` replaces
-/// `+0x5c`/`+0x60` with overrides that *never chain to the base* — "there is no `call 0x76b760`
-/// anywhere in it, so the generic `OnChar` slot `+0x180` is unreachable on an editbox". An
-/// unfocused box therefore takes the `0x77a956 xor eax,eax` leg: decline, walk continues.
-///
-/// Modelling the box as a plain frame here is not a subtle divergence. Stock
-/// `SendMailNameEditBox` carries an XML `<OnChar>` (`SendMailFrame_SendeeAutocomplete`), which
-/// auto-enables it, and it registers first in the mail window — so it consumed every keystroke and
-/// the send tab's other four boxes took no input at all (decision 2145).
+/// An editbox in the walk is asked about focus, never a script slot (`0x77a900`): vtable
+/// `0x81c910` overrides `+0x5c`/`+0x60` without calling the base gate `0x76b760`, so an unfocused
+/// box declines at `0x77a956` and the walk continues.
 #[test]
 fn an_unfocused_editbox_declines_rather_than_eating_its_neighbours_keys() {
     let mut s = script();
@@ -223,8 +203,7 @@ fn an_unfocused_editbox_declines_rather_than_eating_its_neighbours_keys() {
         "the unfocused box's own OnChar is unreachable from the walk — it declines"
     );
 
-    // Give the decoy the focus and its handler is reachable again — through the INSERT, which is
-    // where an editbox's `OnChar` is fired from (`0x77c200`), not through the walk's base gate.
+    // Focused, the decoy's `OnChar` fires from the insert (`0x77c200`), not from the walk's gate.
     s.run("KbDecoyBox:SetFocus()").unwrap();
     assert!(s.char_input("j"), "…and now it is the one that consumes");
     assert_eq!(s.eval::<i64>("return decoyChars").unwrap(), 1);
@@ -240,10 +219,8 @@ fn an_unfocused_editbox_declines_rather_than_eating_its_neighbours_keys() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The same clause on the key-down channel (`+0x60` → `0x77b160`, focus guard at `0x77b1c7`), which
-/// is the [`super::super::keyboard::frame_key_input`] walk: an unfocused box carrying only an
-/// `OnKeyUp` must not swallow a BACKSPACE the focused box is waiting for. The plain-frame
-/// asymmetry above is real *for plain frames*; on a box the base gate is not reached at all.
+/// The same on the key-down channel (`+0x60` is `0x77b160`, focus guard at `0x77b1c7`): an
+/// editbox never reaches the base gate, so an `OnKeyUp` alone does not make it consume.
 #[test]
 fn an_unfocused_editbox_does_not_swallow_a_focused_boxs_editing_key() {
     let mut s = script();
diff --git a/crates/benilla-ui/src/script/tests/layout_gate.rs b/crates/benilla-ui/src/script/tests/layout_gate.rs
index 73ec05b7..cb409817 100644
--- a/crates/benilla-ui/src/script/tests/layout_gate.rs
+++ b/crates/benilla-ui/src/script/tests/layout_gate.rs
@@ -1,9 +1,6 @@
-//! The layout change gate: a resolve whose inputs are byte-identical to the last converged one is
-//! skipped outright (`script::layout::InputFingerprint`).
-//!
-//! These assert on `Model::layout_solves` — the count of times the fixpoint actually ran — rather
-//! than on the rects, because rect equality alone cannot distinguish "the gate skipped" from "the
-//! gate re-solved and got the same answer". The value of the gate is precisely the difference.
+//! The layout change gate: a resolve whose inputs match the last converged one is skipped
+//! (`script::layout::InputFingerprint`). The tests count solves (`Model::layout_solves`), since
+//! equal rects cannot tell a skip from a re-solve.
 
 use super::common::script;
 use crate::script::{Model, UiScript};
@@ -24,8 +21,7 @@ fn solves(s: &UiScript) -> u64 {
         .layout_solves
 }
 
-/// A frame anchored to the screen, plus a child hanging off it — enough that a move has to
-/// propagate, so a wrongly-skipped resolve would be visible in the child too.
+/// A screen-anchored frame and a child off it, so a move has to propagate.
 fn setup(s: &UiScript) {
     s.run(
         r#"
@@ -50,7 +46,6 @@ fn an_unchanged_resolve_does_not_run_the_fixpoint() {
     let after_first = solves(&s);
     assert_eq!(after_first, 1, "the first resolve must run");
 
-    // Nothing touched in between: every further resolve is a no-op.
     for _ in 0..5 {
         s.resolve();
     }
@@ -84,7 +79,6 @@ fn moving_a_frame_reopens_the_gate_and_propagates() {
         child_left(&s)
     );
 
-    // And it closes again once the move has settled.
     let after = solves(&s);
     s.resolve();
     assert_eq!(
@@ -94,7 +88,6 @@ fn moving_a_frame_reopens_the_gate_and_propagates() {
     );
 }
 
-/// Resizing the window moves every top-level frame — the gate must never swallow it.
 #[test]
 fn a_screen_resize_reopens_the_gate() {
     let mut s = script();
@@ -113,8 +106,7 @@ fn a_screen_resize_reopens_the_gate() {
     );
 }
 
-/// A region's own `SetPoint` writes `region_data`, not `layout_inputs` — the half of the read set
-/// that is easiest to leave out of a change gate, and the one the region sweep consumes.
+/// A region's `SetPoint` writes `region_data`, not `layout_inputs`; the region sweep reads it.
 #[test]
 fn moving_a_region_reopens_the_gate() {
     let mut s = script();
@@ -142,10 +134,8 @@ fn moving_a_region_reopens_the_gate() {
     );
 }
 
-/// Hiding a frame does NOT move any rect (the client resolves hidden frames too — visibility is an
-/// extract-time filter), so the gate is right to stay closed. Pinned deliberately: it is the one
-/// place where "nothing to re-solve" is surprising, and a future reader tempted to dirty on
-/// show/hide should see that the current model does not need it.
+/// Hidden frames still resolve (visibility is an extract-time filter), so a hide moves no rect and
+/// the gate stays closed.
 #[test]
 fn hiding_a_frame_does_not_reopen_the_gate() {
     let mut s = script();
@@ -164,22 +154,9 @@ fn hiding_a_frame_does_not_reopen_the_gate() {
     );
 }
 
-/// The hover re-enter loop must be FREE while the content is unchanged.
-///
 /// `ContainerFrameItemButton_OnUpdate` re-runs `OnEnter` every frame while the tooltip is the
-/// button's own — faithful, and UNTHROTTLED in 1.12 (its `updateTooltip` throttle is commented
-/// out; the reference's `ContainerFrameItemButton_OnUpdate` ships the same loop). So a bag hover clears and
-/// rebuilds the SAME tooltip 60×/sec, and the engine must absorb that: identical content re-derives
-/// an identical model, so the measure cache re-validates on its content key and the gate stays shut.
-///
-/// This is the regression gate for the live report (a bag hover cost +10 CPU ms/frame, ~2 full
-/// arena solves + a re-shape of every line, every frame): `clear_content` wiped
-/// `RegionData::measured` — an invalidation the content-hash key already performs — so every
-/// re-enter re-measured every line, and the non-empty measure list forced a second full resolve
-/// that the gate could never close over.
-///
-/// It drives the app's real per-frame order (`ui_script::extract::tick_script`): Lua tick →
-/// resolve → measure round-trip → resolve.
+/// button's, its throttle commented out (`ContainerFrame.lua:645`), so rebuilding identical
+/// tooltip content must neither re-measure nor re-solve.
 #[test]
 fn the_hover_re_enter_loop_neither_re_measures_nor_re_solves() {
     let mut s = script();
@@ -206,8 +183,7 @@ fn the_hover_re_enter_loop_neither_re_measures_nor_re_solves() {
     )
     .expect("setup");
 
-    // The host's font engine: every distinct string has one deterministic size. Counts every
-    // string it is asked to shape, so the test can assert on shaping work directly.
+    // The host's font engine: one fixed size per string.
     let sizes: &[(&str, f32, f32)] = &[
         ("Small Shield", 80.0, 14.0),
         ("Shield", 50.0, 12.0),
@@ -216,8 +192,8 @@ fn the_hover_re_enter_loop_neither_re_measures_nor_re_solves() {
         ("Restores 243 health over 21 sec.", 118.0, 24.0),
         ("Durability 45 / 45", 96.0, 12.0),
     ];
-    // One frame of `tick_script`: tick (the re-enter) → resolve → measure round-trip → resolve.
-    // Returns how many strings the font engine was asked to shape this frame.
+    // One frame in the app's order (`ui_script::extract::tick_script`): tick, resolve, measure
+    // round-trip, resolve. Returns how many strings were shaped.
     let frame = |s: &mut UiScript| -> usize {
         s.run("reenter()").expect("re-enter");
         s.resolve();
@@ -241,8 +217,7 @@ fn the_hover_re_enter_loop_neither_re_measures_nor_re_solves() {
         shaped
     };
 
-    // Settle: the first frames legitimately shape the five strings and re-solve as the auto-size
-    // pre-pass converges on the fresh measures.
+    // The first frames shape the strings and re-solve while the auto-size pre-pass converges.
     for _ in 0..4 {
         frame(&mut s);
     }
@@ -264,12 +239,7 @@ fn the_hover_re_enter_loop_neither_re_measures_nor_re_solves() {
         solves_before,
         "a re-enter with identical content must not reopen the layout gate"
     );
-    // …and it must not even reach tier 2. Tier 1 (the mutation epoch) is what makes a quiet frame
-    // FREE; tier 2 still hashes the whole UI's read set to decide "quiet" (~0.65 ms/frame measured
-    // with `WOW_UI_COST=1` on `WOW_CAPTURE=ui-tooltip`, at solves=0). The re-enter loop used to
-    // pay that on every single hover frame, because `clear_content` wiped each line's wrap pin and
-    // `append_line` re-pinned the same width — a round trip inside one frame, two epoch bumps.
-    // Idempotent content must be epoch-silent, not merely fingerprint-absorbed.
+    // Nor may it reach tier 2, which hashes the whole UI: identical content leaves the epoch alone.
     let epoch_before = epoch(&s);
     for _ in 0..10 {
         frame(&mut s);
@@ -281,9 +251,8 @@ fn the_hover_re_enter_loop_neither_re_measures_nor_re_solves() {
          hold, or every hover frame pays the whole-UI fingerprint"
     );
 
-    // The gate is shut because nothing MOVED — not because the tooltip went stale. Changed content
-    // must still re-measure exactly its own line, and a measure that resizes the auto-sized plate
-    // (this one overtakes the double line as the widest) must reopen the gate.
+    // Changed content re-measures only its own line, and a measure that widens the auto-sized
+    // plate reopens the gate.
     s.run(
         r#"function reenter()
             TT:SetOwner(Slot, "ANCHOR_RIGHT")
@@ -328,28 +297,16 @@ fn the_hover_re_enter_loop_neither_re_measures_nor_re_solves() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// Tier 1 of the gate (decision 0740): the mutation epoch. **Any CONVERGED resolve closes it**
-/// (decision 1385) — the fingerprint is hashed over inputs alone, so a solve cannot outgrow the
-/// value it stores — and from then on a quiet frame skips at a `u64` compare without computing
-/// the fingerprint at all.
+/// Whether tier 1, the mutation epoch, is closed: any converged resolve closes it, and a quiet
+/// frame then skips at a `u64` compare without hashing the fingerprint.
 fn tier_one_closed(s: &UiScript) -> bool {
     let m = s.lua().app_data_ref::<Model>().expect("model app_data");
     m.layout_epoch_resolved == Some(m.layout_epoch)
 }
 
-/// **The castbar law** (decision 1385, ledger B283): a region that MOVES every frame — the classic
-/// OnUpdate animation idiom, our own `CastingBarSpark:SetPoint`, and every addon that slides a
-/// texture — must cost exactly **one** let-through resolve per frame.
-///
-/// It used to cost three. The fingerprint was hashed over the 0294 SEEDS as well as the inputs, so
-/// a solve necessarily outgrew the fingerprint it had just stored: neither that pass nor the
-/// settling pass behind it could close tier 1, and the frame paid solve + settle + skip — three
-/// whole-roster walks at ~1.0–1.4 ms each. Measured live at the Stormwind pin: **+4.2 ms of CPU
-/// per frame for one 32×32 spark**, on a default UI with no addons loaded.
-///
-/// This is the regression guard for that whole bug class. `solves` is the honest counter — a
-/// wasted walk that concludes "nothing moved" still costs the full preamble — so the assertion is
-/// on the count, never on a duration (0735: milliseconds are not evidence of a scope regression).
+/// A region moved every frame, as `CastingBarSpark:SetPoint` does (`CastingBarFrame.lua:114`),
+/// costs exactly one solve per frame: the fingerprint hashes inputs alone, so that solve closes
+/// tier 1.
 #[test]
 fn a_region_moving_every_frame_costs_exactly_one_solve_per_frame() {
     let mut s = script();
@@ -366,13 +323,8 @@ fn a_region_moving_every_frame_costs_exactly_one_solve_per_frame() {
     s.resolve();
     assert!(tier_one_closed(&s), "the setup must settle in one resolve");
 
-    // Ten frames of the castbar's own inner loop: one region re-pointed to a NEW offset, then the
-    // host's per-frame resolve. Nothing else in the model moves.
-    //
-    // The offsets start at 1.7, not 0 — a `frame * 1.7` sequence opens with a re-write of the
-    // seed value, which the setters' bit-exact compare absorbs (no epoch bump, no solve at all).
-    // That is the *right* answer and `an_idempotent_setter_call_leaves_tier_one_closed` pins it;
-    // here it would have measured the guard instead of the gate.
+    // Ten castbar frames: the spark re-pointed to a new offset, then the per-frame resolve. The
+    // offsets start at 1.7, not 0, since the setters' compare absorbs a write of the seed value.
     for frame in 0..10 {
         let before = solves(&s);
         s.run(&format!(
@@ -396,8 +348,7 @@ fn a_region_moving_every_frame_costs_exactly_one_solve_per_frame() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The other half of the same law: once it has settled, an untouched frame costs NOTHING — no
-/// solve, and (tier 1) not even the fingerprint walk that would decide so.
+/// A settled, untouched frame costs no solve, and tier 1 spares it the fingerprint walk too.
 #[test]
 fn a_quiet_frame_after_a_move_costs_no_solve_at_all() {
     let mut s = script();
@@ -421,9 +372,7 @@ fn a_settled_resolve_closes_tier_one_and_a_real_write_reopens_it() {
     s.set_screen_size(800.0, 600.0);
     setup(&s);
 
-    // ONE resolve closes the epoch (decision 1385): the fingerprint is hashed over inputs alone,
-    // and the rounds just drove those inputs to their fixpoint, so there is nothing left for a
-    // settling pass to discover. This used to need two.
+    // One resolve closes the epoch: the fingerprint hashes inputs alone, now at their fixpoint.
     s.resolve();
     assert!(
         tier_one_closed(&s),
@@ -448,9 +397,7 @@ fn an_idempotent_setter_call_leaves_tier_one_closed() {
     s.resolve();
     assert!(tier_one_closed(&s));
 
-    // The classic per-frame OnUpdate idiom: re-assert the exact same geometry every frame. The
-    // setters' compare-before-write keeps the epoch untouched, so an idle UI never re-enters
-    // the fingerprint path at all.
+    // The OnUpdate idiom of re-setting the same geometry: the setters compare before writing.
     s.run(
         r#"
         parent:SetWidth(100); parent:SetHeight(40)
@@ -473,8 +420,8 @@ fn a_paint_only_write_leaves_tier_one_closed() {
     let mut s = script();
     s.set_screen_size(800.0, 600.0);
     setup(&s);
-    // A paint region with NO anchors: its region_data entry is created by a paint setter and
-    // must stay invisible to the layout gate (the resolve sweep skips anchor-less entries).
+    // A region with no anchors: a paint setter creates its `region_data` entry, which the resolve
+    // sweep skips, so the gate must ignore it.
     s.run(r#"tex = parent:CreateTexture(nil, "ARTWORK")"#)
         .expect("region");
     s.resolve();
@@ -491,17 +438,8 @@ fn a_paint_only_write_leaves_tier_one_closed() {
     assert_eq!(solves(&s), before);
 }
 
-/// **The retarget falsifier** (decision 1625): after a node is re-pointed from target A to target
-/// B, the cached graph's EDGES must describe the new shape — moving B must move the node.
-///
-/// This is the one direction that can be silently wrong. 1625 keeps the cached graph across an
-/// anchor retarget by patching one node's edges instead of re-deriving all of them, and a patch
-/// that dropped the *new* edge would under-dirty: the node would sit at a stale rect while the
-/// thing it is anchored to moved. (The other direction — a leftover edge to the OLD target — only
-/// costs a needless re-solve, so it is asserted second and separately.)
-///
-/// It asserts on RECTS, not on counts, because a wrong edge set is a wrong picture: the failure
-/// this guards against is a tooltip left behind at the last button's position.
+/// A retarget patches one node's edges in the cached graph instead of re-deriving it, so the new
+/// edge must land: moving the new target moves the node, and moving the old one does not.
 #[test]
 fn a_retargeted_anchor_follows_its_new_target() {
     let mut s = script();
@@ -521,8 +459,7 @@ fn a_retargeted_anchor_follows_its_new_target() {
     s.resolve();
     s.resolve();
 
-    // The retarget: the plate now hangs off B, exactly as `GameTooltip:SetOwner` re-points the
-    // plate at the next button under the cursor.
+    // The plate now hangs off B, as `GameTooltip:SetOwner` re-points it at the next button.
     s.run(r#"plate:SetPoint("TOPLEFT", b, "TOPRIGHT", 0, 0)"#)
         .expect("retarget");
     s.resolve();
@@ -532,9 +469,6 @@ fn a_retargeted_anchor_follows_its_new_target() {
         "the retargeted plate must sit at B's right edge (110), not {after_retarget}"
     );
 
-    // …and it must keep following B. This is the assertion the edge patch exists to satisfy: the
-    // graph was NOT re-derived across the retarget, so if the new edge never made it into the
-    // cached edge set, B moving reaches nothing and the plate stays put.
     s.run(r#"b:SetPoint("TOPLEFT", nil, "TOPLEFT", 300, 0)"#)
         .expect("move B");
     s.resolve();
@@ -545,7 +479,6 @@ fn a_retargeted_anchor_follows_its_new_target() {
          retarget's edge patch dropped the new edge and the node is under-dirtied (decision 1625)"
     );
 
-    // …and it must NOT follow the old one any more.
     s.run(r#"a:SetPoint("TOPLEFT", nil, "TOPLEFT", 0, -50)"#)
         .expect("move A");
     s.resolve();
diff --git a/crates/benilla-ui/src/script/tests/measure.rs b/crates/benilla-ui/src/script/tests/measure.rs
index fcccb953..b280da10 100644
--- a/crates/benilla-ui/src/script/tests/measure.rs
+++ b/crates/benilla-ui/src/script/tests/measure.rs
@@ -1,12 +1,11 @@
-//! The measure round-trip + frame→region anchors, end to end.
+//! Text measurement: the host round-trip, the same-tick font engine, and the layout they feed.
 
 use super::common::script;
 use crate::script::*;
 
-/// The measure round-trip + frame→region anchors, end to end: a height-less FontString reports a
-/// [`MeasureRequest`]; the host answer becomes its implicit size; and a FRAME anchored to that
-/// FontString by name binds to its measured bottom in resolve's second round — the real gossip
-/// structure (option rows hang off the greeting's laid-out height, ref-GossipFrame.xml l.258-261).
+/// A height-less FontString's [`MeasureRequest`] answer becomes its size, and a frame anchored to
+/// it binds to the measured bottom in resolve's second round, as gossip option rows hang off the
+/// greeting text (`GossipFrame.xml:258`).
 #[test]
 fn measured_fontstring_height_feeds_frame_anchors() {
     let mut s = script();
@@ -48,7 +47,7 @@ fn measured_fontstring_height_feeds_frame_anchors() {
         })
         .expect("greeting rect");
     assert_eq!((g.top, g.bottom, g.left), (409.0, 361.0, 33.0));
-    // Row1: TOPLEFT → Greeting BOTTOMLEFT +(-10,-20) ⇒ top 341, left 23 — bound in round 2.
+    // Row1: TOPLEFT → Greeting BOTTOMLEFT +(-10,-20) ⇒ top 341, left 23, bound in round 2.
     let row = quads
         .iter()
         .find_map(|q| match q.target {
@@ -60,13 +59,9 @@ fn measured_fontstring_height_feeds_frame_anchors() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// A stored measure serves ONLY the current text: after `SetText` to a DIFFERENT string, the old
-/// string's width must not leak through `GetWidth`/`GetStringWidth` — the whisper-header cursor
-/// bug: the chat edit box ran `SetTextInsets(15 + header:GetWidth(), …)` on a type switch
-/// (Say → "Tell Alice:") and its `w > 1` settle gate passed with the PREVIOUS header's measure,
-/// latching the caret inside the new header. The metric read is key-checked
-/// ([`crate::script::RegionData`]'s measure key): a changed string reads 0 until its own measure
-/// lands, so poll-until-nonzero callers converge on the RIGHT width.
+/// A stored measure serves only its own text: reads check [`crate::script::RegionData`]'s measure
+/// key, so a changed string reads 0 until its measure lands, never the old width. The chat header
+/// reads its width right after a `SetText` (`ChatFrame.lua:1912`).
 #[test]
 fn a_changed_text_reads_zero_until_its_own_measure_lands() {
     let mut s = script();
@@ -92,7 +87,7 @@ fn a_changed_text_reads_zero_until_its_own_measure_lands() {
             .unwrap(),
         30.0
     );
-    // The type switch: same region, new text. The old measure must NOT serve.
+    // The type switch: same region, new text.
     s.run(r#"getglobal("Header"):SetText("Tell Alice: ")"#)
         .unwrap();
     assert_eq!(
@@ -101,7 +96,6 @@ fn a_changed_text_reads_zero_until_its_own_measure_lands() {
         0.0,
         "a stale measure must not serve for changed text"
     );
-    // The round-trip re-measures the new string; the true width serves.
     s.resolve();
     let reqs = s.fontstrings_needing_measure();
     assert_eq!(reqs.len(), 1, "the changed text wants re-measuring");
@@ -117,11 +111,9 @@ fn a_changed_text_reads_zero_until_its_own_measure_lands() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// A zero-WIDTH FontString with an explicit height auto-sizes its width to the measured line —
-/// the reference label idiom (`<Size x="0" y="16"/>` anchored TOPRIGHT→TOPLEFT: MailFrame's
-/// "From:"/"Subject:" labels end at the anchor and grow leftward, and the value string anchored
-/// LEFT→label RIGHT starts past them, never overlapping). Gating the measure on height alone
-/// left these rects zero-width — "From" and the sender name painted on top of each other.
+/// A zero-width FontString with a height auto-sizes its width to the measured line: MailFrame's
+/// `OpenMailSenderLabel` (`MailFrame.xml:1391`) grows leftward from its anchor, and the sender
+/// name anchored to its right edge starts past it.
 #[test]
 fn zero_width_fontstring_autosizes_to_its_line() {
     let mut s = script();
@@ -163,17 +155,14 @@ fn zero_width_fontstring_autosizes_to_its_line() {
         .eval("return FromLabel:GetLeft(), FromLabel:GetRight(), FromLabel:GetStringWidth()")
         .unwrap();
     assert_eq!((l_left, l_right, l_w), (74.0, 114.0, 40.0));
-    // Value: starts 5 past the label's real right edge — no overlap.
+    // Value: 5 past the label's measured right edge.
     let v_left: f32 = s.eval("return FromValue:GetLeft()").unwrap();
     assert_eq!(v_left, 119.0);
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The frame-scale seam (0219 §2's divergence, closed): a `SetScale`'d frame's quads carry its
-/// `effective_scale` out to the renderer — the rect is already scale-multiplied by layout, and
-/// the renderer needs the same factor for the GLYPH raster size — and the measure round-trip
-/// rides it too: the request names the scale (the host measures at the drawn size), the cache
-/// key holds it (a re-scale re-measures), all before any quad draws stale text.
+/// A scaled frame's quads carry its effective scale for the glyph raster (layout already scaled
+/// the rect), and the measure request and its cache key carry it too.
 #[test]
 fn frame_scale_rides_the_quads_and_the_measure_key() {
     let mut s = script();
@@ -190,7 +179,6 @@ fn frame_scale_rides_the_quads_and_the_measure_key() {
     )
     .unwrap();
     s.resolve();
-    // The measure request carries the owner's effective scale.
     let reqs = s.fontstrings_needing_measure();
     assert_eq!(reqs.len(), 1);
     let r = &reqs[0];
@@ -200,18 +188,15 @@ fn frame_scale_rides_the_quads_and_the_measure_key() {
     s.set_measured_text_unwrapped(&[(id, 50.0, 16.0, key)]);
     s.resolve();
     assert!(s.fontstrings_needing_measure().is_empty(), "cache warm");
-    // Every quad of the scaled frame carries the scale — frame slot and region alike.
     let quads = s.extract();
     let label = quads
         .iter()
         .find(|q| matches!(&q.content, QuadContent::Text { text: Some(t), .. } if t == "Options"))
         .expect("label quad");
     assert_eq!(label.scale, 0.8);
-    // The label's rect is scale-multiplied by layout (width 50 × 0.8 = 40) — the quad's scale is
-    // for the glyph raster, not a second rect multiply.
+    // Layout already scaled the rect (50 × 0.8 = 40); the quad's scale is for the glyphs only.
     let lr = label.rect.expect("label rect");
     assert!((lr.width() - 40.0).abs() < 0.01, "width {}", lr.width());
-    // A re-scale invalidates the measure key: the same text re-measures at the new drawn size.
     s.run(r#"Win:SetScale(1.25)"#).unwrap();
     s.resolve();
     let reqs = s.fontstrings_needing_measure();
@@ -221,12 +206,9 @@ fn frame_scale_rides_the_quads_and_the_measure_key() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The host's raster-environment invalidation ([`UiScript::invalidate_text_measures`]): a warm
-/// FontString measure cache re-requests after the call — same content, same key (the key hashes
-/// content, not the host's seam scale; the STALENESS is the host's to declare, which is the whole
-/// seam). This is the engine half of the fullscreen-truncation fix: measures answered under one
-/// seam scale kept satisfying fit tests run under another, and the ellipsis ate fitting text
-/// ("Contr...", director 2026-08-04; reproduced end-to-end by `WOW_RESIZE`).
+/// [`UiScript::invalidate_text_measures`] re-requests every warm measure under the same key: the
+/// key hashes content, not the host's raster scale, so only the host knows when a measure is
+/// stale, and a stale one truncates text that fits.
 #[test]
 fn invalidate_text_measures_reopens_the_round_trip() {
     let mut s = script();
@@ -254,14 +236,11 @@ fn invalidate_text_measures_reopens_the_round_trip() {
     );
 
     s.invalidate_text_measures();
-    // The measured extent is gone (GetStringWidth back to its unmeasured 0)…
     assert_eq!(
         s.eval::<f64>("return Label:GetStringWidth()").unwrap(),
         0.0,
         "stale measure dropped, not served"
     );
-    // …and the round-trip reopens with the SAME content key — the request is the host's cue to
-    // re-measure under its new environment; nothing about the region itself changed.
     let reqs = s.fontstrings_needing_measure();
     assert_eq!(reqs.len(), 1, "re-requests after invalidation");
     assert_eq!(
@@ -271,20 +250,9 @@ fn invalidate_text_measures_reopens_the_round_trip() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **`GetStringWidth` is the NATURAL width — never the box, never the wrapped extent**
-/// (`0x79e510`→`0x772890`: the reference re-measures the raw text with no wrap constraint, so "Lua
-/// sees the natural, unwrapped, un-truncated width at the DRAWN size").
-///
-/// This is the distinction whose absence made the reference's own `PanelTemplates_TabResize` a
-/// feedback loop in this engine (decision 0997): the kit sized a tab from `GetStringWidth`, set that
-/// width on the label, and read its own output back next frame — a tab that changed width every
-/// single frame. Three separate things are pinned here because each one was wrong on its own:
-///
-/// 1. a region with a DECLARED width still gets a measure request (it used to be skipped: no
-///    auto-sized axis, no request — so a constrained label could never learn its natural width);
-/// 2. `GetStringWidth` answers with the natural width, while `GetWidth` keeps echoing the laid-out
-///    extent that auto-size depends on;
-/// 3. the answer does not move when the declared width does.
+/// `GetStringWidth` is the natural width, unwrapped and untruncated at the drawn size: the
+/// reference re-measures the raw text with no wrap (`0x79e510`, `0x772890`). `GetWidth` stays the
+/// laid-out box.
 #[test]
 fn get_string_width_is_the_natural_width_not_the_box() {
     let mut s = UiScript::new().unwrap();
@@ -303,8 +271,7 @@ fn get_string_width_is_the_natural_width_not_the_box() {
     .unwrap();
     s.resolve();
 
-    // 1 · Both axes are declared, so nothing about the LAYOUT needs a measure — and the request is
-    //     issued anyway, because `GetStringWidth` has no other way to learn the natural width.
+    // 1 · A fully declared box still requests a measure, for the natural width.
     let reqs = s.fontstrings_needing_measure();
     assert_eq!(reqs.len(), 1, "a fully-sized FontString still measures");
     let r = &reqs[0];
@@ -326,8 +293,7 @@ fn get_string_width_is_the_natural_width_not_the_box() {
         "GetWidth is the laid-out box the auto-size path depends on"
     );
 
-    // 3 · Narrowing the box re-opens the round trip (the key carries the wrap) and, once answered,
-    //     leaves the natural width exactly where it was. This is the loop that used to close.
+    // 3 · A narrower box re-measures (the key carries the wrap); the natural width stays put.
     s.run("Label:SetWidth(30)").unwrap();
     s.resolve();
     let reqs = s.fontstrings_needing_measure();
@@ -341,14 +307,10 @@ fn get_string_width_is_the_natural_width_not_the_box() {
     );
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The SYNCHRONOUS measure — a host font engine installed into the VM ([`TextMeasure`])
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The synchronous measure: a host font engine installed in the VM (`TextMeasure`) ──
 
-/// A stand-in font engine: every character is `PER_CHAR` wide and every line `LINE_H` tall, wrapped
-/// greedily at the request's wrap width. Deliberately not the real one — what these tests are about
-/// is *when* the answer arrives, and a fake with arithmetic anyone can do in their head is what
-/// makes the assertions readable. The real engine's own numbers are the app's to test.
+/// A stand-in font engine: each character is `PER_CHAR` wide and each line `LINE_H` tall, wrapped
+/// greedily at the request's wrap width.
 struct BlockFont;
 
 const PER_CHAR: f32 = 7.0;
@@ -367,13 +329,8 @@ impl TextMeasure for BlockFont {
     }
 }
 
-/// **The director's bug, at the engine.** `SetText` then `GetStringWidth` in ONE tick must answer
-/// with the string's width — the shape `Bagnon_Forever/database/ui.lua:58-59` writes over every
-/// saved character (`button:SetText(player)` then `button:GetTextWidth() + 40`), and the shape the
-/// reference's own `SmallMoneyFrame` writes (MoneyFrame.lua l.202).
-///
-/// Without an engine installed this is 0 until the host's round-trip lands at extract — a frame
-/// later. That is what sized Bagnon's character dropdown to 40px with seven names hanging out of it.
+/// With a font engine installed, `SetText` then a width read in the same tick gets the string's
+/// width, as the money frame's `SetText` then `GetTextWidth` expects (`MoneyFrame.lua:202`).
 #[test]
 fn a_width_read_in_the_tick_that_set_the_text_is_not_zero() {
     let mut s = script();
@@ -398,9 +355,8 @@ fn a_width_read_in_the_tick_that_set_the_text_is_not_zero() {
     );
 }
 
-/// The same read WITHOUT an engine stays 0 and stays served by the round-trip — the pre-existing
-/// behaviour, still exactly itself. Every engine test and every headless run is this VM, so the
-/// synchronous path may never be a correctness precondition for anything.
+/// Without an engine the read is 0 until the round-trip answers; headless runs and most tests have
+/// no engine, so nothing may depend on the synchronous path.
 #[test]
 fn with_no_engine_installed_the_round_trip_is_still_the_only_answer() {
     let mut s = script();
@@ -424,9 +380,8 @@ fn with_no_engine_installed_the_round_trip_is_still_the_only_answer() {
     );
 }
 
-/// A FontString's **box** is right in the frame its text was set, not the frame after: `resolve`
-/// closes the round-trip itself when an engine is installed, so a caller reading `GetWidth()` (the
-/// laid-out extent, not the natural one) gets this string's number and not the previous string's.
+/// With an engine installed, `resolve` answers its own measure requests, so `GetWidth()` is right
+/// in the frame the text was set.
 #[test]
 fn resolve_closes_the_round_trip_when_an_engine_is_installed() {
     let mut s = script();
@@ -458,9 +413,8 @@ fn resolve_closes_the_round_trip_when_an_engine_is_installed() {
     );
 }
 
-/// The same-tick measure and the batch round-trip write the **same cache**, so asking twice costs
-/// one measure — and a caller polling `GetStringWidth` every frame does not re-measure a string
-/// that has not changed.
+/// The same-tick measure and the batch round-trip share one cache, so an unchanged string is
+/// measured once however often it is read.
 #[test]
 fn a_synchronous_measure_satisfies_the_batch_request_too() {
     let mut s = script();
@@ -482,7 +436,6 @@ fn a_synchronous_measure_satisfies_the_batch_request_too() {
         s.fontstrings_needing_measure().is_empty(),
         "the Lua read already filled the cache the batch pass keys on"
     );
-    // …and a new string invalidates it exactly as it always did.
     s.run("Label:SetText('a longer label')").unwrap();
     assert_eq!(
         s.eval::<f32>("return Label:GetStringWidth()").unwrap(),
@@ -491,13 +444,8 @@ fn a_synchronous_measure_satisfies_the_batch_request_too() {
     );
 }
 
-/// The measure LEDGER's completeness guard: `fontstrings_needing_measure` no longer walks the
-/// roster on the armed path — a measure-input write the ledger never hears about is a label
-/// whose box silently never updates again. The exposing sequence is SETTLE (drain the ledger
-/// dry), then one silent write, then sweep: enrolled, the sweep names exactly that region;
-/// missed, it returns empty and this test is the red light. (Watched red with the `SetText`
-/// enrollment removed — the earlier tests in this file stay green through that removal, because
-/// their regions ride the ledger's own re-enrollment of still-unanswered requests.)
+/// `fontstrings_needing_measure` sweeps only the regions a write enrolled, so every measure-input
+/// write must enroll its region: settle, write once, and the sweep must name that region.
 #[test]
 fn a_settled_region_is_refound_after_each_measure_input_write() {
     let mut s = script();
@@ -514,17 +462,13 @@ fn a_settled_region_is_refound_after_each_measure_input_write() {
     .unwrap();
     let writes: &[(&str, &str)] = &[
         ("SetText", "Label:SetText('two')"),
-        // `SetFormattedText` was a second row here; it is gone (2142), and its era spelling
-        // `SetText(format(...))` is the row above's path exactly.
         (
             "SetFont",
             r#"Label:SetFont("Fonts\\FRIZQT__.TTF", 14, "OUTLINE")"#,
         ),
         ("SetTextHeight", "Label:SetTextHeight(20)"),
         ("SetWidth (the wrap width)", "Label:SetWidth(123)"),
-        // The conservative lane: a scale write cannot name descendants one by one, so it must
-        // put the ledger back on the whole-roster walk — which refinds Label (scale is in the
-        // measure key).
+        // A scale write cannot name its descendants, so it falls back to the whole-roster walk.
         ("SetScale (conservative)", "Host:SetScale(2.0)"),
     ];
     for (label, lua) in writes {
@@ -546,8 +490,7 @@ fn a_settled_region_is_refound_after_each_measure_input_write() {
             "{label}: a silent measure-input write must re-surface its region to the sweep"
         );
     }
-    // The button label lane writes through its own binding (`Button:SetText` routes to the
-    // ButtonText region) — same guard, second write path.
+    // `Button:SetText` writes its ButtonText region through its own binding.
     s.run(
         r#"
         local b = CreateFrame("Button", "Btn")
diff --git a/crates/benilla-ui/src/script/tests/minimap.rs b/crates/benilla-ui/src/script/tests/minimap.rs
index cd37439f..87e4dcb0 100644
--- a/crates/benilla-ui/src/script/tests/minimap.rs
+++ b/crates/benilla-ui/src/script/tests/minimap.rs
@@ -1,11 +1,10 @@
-//! The Minimap widget kind (decision 0203): zoom API + the extracted content hole.
+//! The Minimap widget kind: the zoom API and the extracted content hole.
 
 use super::common::script;
 use crate::script::*;
 use crate::widget::{MINIMAP_DEFAULT_ZOOM, MINIMAP_ENGINE_CHILDREN, MINIMAP_ZOOM_LEVELS};
 
-/// A `<Minimap>`-kind frame carries its zoom out through extraction as [`QuadContent::Minimap`]
-/// at the frame's own draw slot, and the zoom API clamps like the client's `set_zoom` (0..=5).
+/// The zoom rides extraction as [`QuadContent::Minimap`]; `SetZoom` clamps to 0..=5.
 #[test]
 fn minimap_zoom_api_and_extract() {
     let mut s = script();
@@ -18,7 +17,7 @@ fn minimap_zoom_api_and_extract() {
     )
     .unwrap();
 
-    // Defaults + the clamp law. Both indices seed from the CVar default "3", not 0.
+    // Both indices seed from the CVar default "3", not 0.
     assert_eq!(
         s.eval::<u8>("return m:GetZoom()").unwrap(),
         MINIMAP_DEFAULT_ZOOM
@@ -38,7 +37,6 @@ fn minimap_zoom_api_and_extract() {
     s.run("m:SetZoom(-2)").unwrap();
     assert_eq!(s.eval::<u8>("return m:GetZoom()").unwrap(), 0);
 
-    // The widget's own slot extracts as the Minimap content hole, carrying the zoom.
     s.resolve();
     let mm = s
         .extract()
@@ -62,7 +60,7 @@ fn minimap_zoom_api_and_extract() {
         "a sized+anchored Minimap resolves a rect"
     );
 
-    // Duck-typing: the zoom API must NOT leak onto other kinds (per-kind method registries).
+    // The zoom methods exist only on the Minimap kind; addons duck-type on them.
     s.run(r#"plain = CreateFrame("Frame", "PlainF")"#).unwrap();
     assert!(
         s.eval::<bool>("return plain.SetZoom == nil").unwrap(),
@@ -70,9 +68,8 @@ fn minimap_zoom_api_and_extract() {
     );
 }
 
-/// The client keeps **two** zoom indices and routes `GetZoom`/`SetZoom` on WMO containment (the
-/// inside flag `0xceaa60` → outdoor `0x86f698` / indoor `0x86f69c`). Each persists across the
-/// transition: zooming the inn's map right in must not disturb the zoom you left outside.
+/// Two zoom indices, outdoor `0x86f698` and indoor `0x86f69c`, picked by the WMO inside flag
+/// `0xceaa60`; each persists across the transition.
 #[test]
 fn minimap_indoor_and_outdoor_zoom_indices_are_independent() {
     let mut s = script();
@@ -85,11 +82,9 @@ fn minimap_indoor_and_outdoor_zoom_indices_are_independent() {
     )
     .unwrap();
 
-    // Outside: the zoom API drives the outdoor index.
     s.run("m:SetZoom(2)").unwrap();
     assert_eq!(s.eval::<u8>("return m:GetZoom()").unwrap(), 2);
 
-    // Step inside: the API now reads/writes the indoor index, still at its own untouched default.
     s.set_minimap_inside(true);
     assert_eq!(
         s.eval::<u8>("return m:GetZoom()").unwrap(),
@@ -118,7 +113,6 @@ fn minimap_indoor_and_outdoor_zoom_indices_are_independent() {
         mm.content
     );
 
-    // Step back outside: the outdoor zoom is exactly where we left it.
     s.set_minimap_inside(false);
     assert_eq!(
         s.eval::<u8>("return m:GetZoom()").unwrap(),
@@ -127,10 +121,8 @@ fn minimap_indoor_and_outdoor_zoom_indices_are_independent() {
     );
 }
 
-/// **The level persists** (decision 1131). `SetZoom` writes the live index *and* the matching CVar
-/// — `minimapInsideZoom` while inside a WMO, `minimapZoom` outside — the client's own `set_zoom` →
-/// `CVar::Set` pair, which is the whole reason a zoom survives a restart. The host push in the
-/// other direction (the seed) does *not* echo back as a change.
+/// `SetZoom` writes the live index and its CVar (`minimapInsideZoom` inside a WMO, `minimapZoom`
+/// outside), as the client's `set_zoom` calls `CVar::Set`; the host's seed does not echo back.
 #[test]
 fn setzoom_persists_the_level_through_the_cvar_it_belongs_to() {
     let mut s = script();
@@ -138,13 +130,11 @@ fn setzoom_persists_the_level_through_the_cvar_it_belongs_to() {
     s.run(r#"m = CreateFrame("Minimap", "TestMinimap")"#)
         .unwrap();
 
-    // The seed is a HOST write: it moves both live indices and queues nothing (the host is the
-    // one that just read them off disk — an echo would re-dirty the file it loaded).
+    // The seed is a host write: it moves both indices and queues nothing.
     s.set_minimap_zoom(1, 4);
     assert_eq!(s.eval::<u8>("return m:GetZoom()").unwrap(), 1);
     assert!(s.take_cvar_changes().is_empty(), "the seed must not echo");
 
-    // Outdoors, a zoom writes the outdoor CVar and only that one.
     s.run("m:SetZoom(5)").unwrap();
     assert_eq!(
         s.take_cvar_changes(),
@@ -152,7 +142,6 @@ fn setzoom_persists_the_level_through_the_cvar_it_belongs_to() {
     );
     assert_eq!(s.cvar("minimapInsideZoom").as_deref(), Some("3"));
 
-    // Indoors it writes the indoor one — the two levels persist separately, like the indices.
     s.set_minimap_inside(true);
     s.run("m:SetZoom(0)").unwrap();
     assert_eq!(
@@ -161,11 +150,11 @@ fn setzoom_persists_the_level_through_the_cvar_it_belongs_to() {
     );
     assert_eq!(s.cvar("minimapZoom").as_deref(), Some("5"));
 
-    // A no-op zoom queues nothing: quiet frames stay quiet, and the config stays clean.
+    // A no-op zoom queues nothing.
     s.run("m:SetZoom(0)").unwrap();
     assert!(s.take_cvar_changes().is_empty());
 
-    // The seed clamps like `set_zoom` does, so a hand-edited config.toml cannot seed out of range.
+    // The seed clamps like `set_zoom`.
     s.set_minimap_zoom(99, 99);
     s.set_minimap_inside(false);
     assert_eq!(
@@ -174,9 +163,7 @@ fn setzoom_persists_the_level_through_the_cvar_it_belongs_to() {
     );
 }
 
-/// A VM whose host registered nothing (a bare test harness, a glue-only run) still zooms — the
-/// engine-side CVar write is a silent no-op there, not a warning: engine writes are code, not UI
-/// content, so a miss means this build's host does not back the var.
+/// With no host CVars (a bare harness, a glue-only run) the engine-side write is a silent no-op.
 #[test]
 fn zooming_without_a_registered_cvar_table_is_silent() {
     let mut s = script();
@@ -190,17 +177,9 @@ fn zooming_without_a_registered_cvar_table_is_silent() {
     );
 }
 
-/// **The nine engine-created `Model` children, and why `[9]` is the player arrow.**
-///
-/// The `CMinimap` ctor `0x4edbc0` builds nine `CSimpleModel` children parented to the Minimap
-/// before anything else touches the widget, in three source-ordered groups (`__LINE__` 1424 / 1438
-/// / 1450), the last being
-/// `[Minimap+0x338]`, the player arrow. Because both linkers append at the tail and the ctor runs
-/// before the XML `<Frames>` descent, `({Minimap:GetChildren()})[9]` is that arrow on a stock
-/// client — which is exactly what Questie's `QuestieArrow.lua` and pfQuest's `compat/client.lua`
-/// index, unguarded, to read the player's heading.
-///
-/// This test is written the way those addons read it, not the way we store it.
+/// The `CMinimap` ctor (`0x4edbc0`) builds nine `CSimpleModel` children before the XML `<Frames>`
+/// descent, the last being the player arrow `[Minimap+0x338]`, so `({Minimap:GetChildren()})[9]`
+/// is the arrow; Questie and pfQuest read the player's heading from it.
 #[test]
 fn a_minimap_is_born_with_nine_model_children_and_the_ninth_is_the_player_arrow() {
     let mut s = script();
@@ -225,20 +204,17 @@ fn a_minimap_is_born_with_nine_model_children_and_the_ninth_is_the_player_arrow(
         )
         .unwrap());
 
-    // Questie's `GetPlayerFacing()`, verbatim. It is `0` until the app pushes, which is the
-    // client's own ctor default (`[frame+0x39c] = 0` at `0x76c92d`) — not nil, and not an error.
+    // Questie's `GetPlayerFacing()`; 0 until the app pushes, the ctor default (`0x76c92d`).
     s.run("function GetPlayerFacing() return ({Minimap:GetChildren()})[9]:GetFacing() end")
         .unwrap();
     s.run(r#"Minimap = m"#).unwrap();
     assert_eq!(s.eval::<f32>("return GetPlayerFacing()").unwrap(), 0.0);
 
-    // `SetPlayerFacing 0x4eb8e0` writes the argument into `[[minimap+0x338]+0x39c]` VERBATIM — no
-    // negation, no offset, no unit change (a `mov [ecx+0x39c],edx` of the dword it was handed).
+    // `SetPlayerFacing 0x4eb8e0` stores the argument into `[[minimap+0x338]+0x39c]` unchanged.
     s.set_minimap_player_facing(2.5);
     assert_eq!(s.eval::<f32>("return GetPlayerFacing()").unwrap(), 2.5);
 
-    // It reaches the arrow through the Minimap's own slot, so an addon appending its own child
-    // cannot displace it: a later `CreateFrame(_, _, Minimap)` lands at index 10.
+    // An addon's own child lands at index 10 and does not displace the arrow.
     s.run(r#"extra = CreateFrame("Frame", nil, m)"#).unwrap();
     s.set_minimap_player_facing(-1.25);
     assert_eq!(s.eval::<f32>("return GetPlayerFacing()").unwrap(), -1.25);
@@ -252,22 +228,15 @@ fn a_minimap_is_born_with_nine_model_children_and_the_ninth_is_the_player_arrow(
         "Frame"
     );
 
-    // The ctor only *constructs* them; the model files are `CMinimap::LoadXML 0x4ee2b0`'s to
-    // assign, so a Lua-built Minimap with no XML behind it has nine file-less Models — exactly as
-    // the reference does.
+    // The model files come from `CMinimap::LoadXML` (`0x4ee2b0`), so a Lua-built one has none.
     assert!(s
         .eval::<Option<String>>("return ({m:GetChildren()})[9]:GetModel()")
         .unwrap()
         .is_none_or(|p| p.is_empty()));
 }
 
-/// **`Minimap:SetMaskTexture` is state, and an empty path restores the default rather than
-/// unmasking the map.**
-///
-/// A real 1.12 method (the name is in the 5875 image) with no getter beside it, so the readback
-/// here is through the arena — the same shape `simplehtml`'s and `modelframe`'s tests use for a
-/// write-only verb. pfUI's `modules/minimap.lua:27` is the caller that matters: swapping this art
-/// is how its square minimap becomes square.
+/// A 1.12 method with no getter, so the test reads the arena; pfUI's `modules/minimap.lua:27`
+/// squares its minimap with it.
 #[test]
 fn set_mask_texture_is_state_and_empty_restores_the_default() {
     let s = script();
@@ -282,21 +251,17 @@ fn set_mask_texture_is_state_and_empty_restores_the_default() {
         Some("Interface\\AddOns\\pfUI\\img\\minimap")
     );
 
-    // Empty and nil both mean "back to the engine's circle" — never "no mask at all". A
-    // nil-means-unmasked reading would hand every mistyped path a silently square minimap.
+    // Empty and nil both restore the engine's circle, never "no mask".
     s.run(r#"m:SetMaskTexture("")"#).unwrap();
     assert_eq!(s.minimap_mask_texture(), None);
     s.run(r#"m:SetMaskTexture("Interface\\Foo") m:SetMaskTexture(nil)"#)
         .unwrap();
     assert_eq!(s.minimap_mask_texture(), None);
 
-    // There is no getter in 1.12, and we do not invent one (decision 1189).
     assert!(s.eval::<bool>("return m.GetMaskTexture == nil").unwrap());
 }
 
-/// `frame_effective_alpha` — the host-side read behind a frame whose pixels the app draws (the
-/// stock `MiniMapPing` model, 1974): `None` while hidden, or hidden through a parent; the
-/// effective alpha while effectively visible.
+/// The host-side alpha read for a frame the app draws itself, such as the stock `MiniMapPing`.
 #[test]
 fn frame_effective_alpha_reads_the_shown_frames_alpha() {
     let s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/tests/mod.rs b/crates/benilla-ui/src/script/tests/mod.rs
index eb688f8d..035b35c9 100644
--- a/crates/benilla-ui/src/script/tests/mod.rs
+++ b/crates/benilla-ui/src/script/tests/mod.rs
@@ -1,8 +1,5 @@
-//! Rust-driven tests of the Lua host: the object model, layout+size reads, show/hide + event + tick
-//! firing (both `0x704d50`/`0x704f10` conventions), the WoW stdlib (positional `format`, the
-//! aliases, `getglobal`), the sandbox holes, and an end-to-end extract in ZKey order.
-//!
-//! Split by subject; the shared `script()` fixture lives in [`common`].
+//! Rust-driven tests of the Lua host, one module per subject; the shared `script()` fixture lives
+//! in [`common`].
 
 mod addon_argument_abi;
 mod addon_index_space;
@@ -58,11 +55,6 @@ mod widget_surface;
 mod worldframe;
 mod worldmap;
 
-/// **A bounded chunk reports instead of hanging** — the guard decision 1247's hang called for.
-///
-/// Without it, a `while true do end` inside an addon takes the whole process with it, and every
-/// instrument downstream produces nothing at all: no roster, no columns, no error row. The bound
-/// turns that into an ordinary Lua error, which every caller already knows how to report.
 #[test]
 fn an_instruction_budget_turns_a_runaway_loop_into_an_error() {
     let s = crate::script::UiScript::new().unwrap();
@@ -81,9 +73,6 @@ fn an_instruction_budget_turns_a_runaway_loop_into_an_error() {
         s.instructions_used()
     );
 
-    // **The VM survives it.** The bound must not poison the interpreter — a survey has 217 more
-    // addons to run after the one that looped, and each gets its own VM only because this one
-    // returned at all.
     assert_eq!(
         s.eval::<i64>("return 2 + 3").unwrap(),
         5,
@@ -98,16 +87,10 @@ fn an_instruction_budget_turns_a_runaway_loop_into_an_error() {
     assert_eq!(t.eval::<i64>("return BudgetOk").unwrap(), 500_500);
 }
 
-/// **`GetBindLocation()` — the hearth location's name, `""` before the packet lands.**
-///
-/// Three corpus addons read it (FuBar_TransporterFu `TransporterFu.lua:456`, Necrosis
-/// `Necrosis.lua:1089`, _LazyPig `LazyPig.lua:623`), and the reference's own hearth confirmation
-/// formats it straight into the dialog (`StaticPopup.lua:1742`).
+/// The hearth location's name, `""` before the packet; `StaticPopup.lua:1742` formats it.
 #[test]
 fn get_bind_location_answers_the_pushed_name_and_never_nil() {
     let mut s = crate::script::UiScript::new().unwrap();
-    // Before the app pushes anything: the empty string, NOT nil. Necrosis concatenates the result,
-    // so nil would be a raise rather than a blank — the same choice `GetRealmName` beside it makes.
     assert_eq!(s.eval::<String>("return GetBindLocation()").unwrap(), "");
     assert_eq!(
         s.eval::<String>("return type(GetBindLocation())").unwrap(),
@@ -120,13 +103,11 @@ fn get_bind_location_answers_the_pushed_name_and_never_nil() {
         s.eval::<String>("return GetBindLocation()").unwrap(),
         "Stormwind City"
     );
-    // Concatenation is the idiom that matters, so it is the one asserted.
     assert_eq!(
         s.eval::<String>(r#"return "Bound: " .. GetBindLocation()"#)
             .unwrap(),
         "Bound: Stormwind City"
     );
-    // A re-bind replaces it rather than accumulating.
     s.set_bind_location("Ironforge");
     assert_eq!(
         s.eval::<String>("return GetBindLocation()").unwrap(),
@@ -134,19 +115,13 @@ fn get_bind_location_answers_the_pushed_name_and_never_nil() {
     );
 }
 
-/// **`RequestTimePlayed()` queues the ask; `TIME_PLAYED_MSG` carries the answer.**
-///
-/// The two halves are one feature: `QuestHistory` calls the verb and then waits on the event, so
-/// shipping the request alone would be 1203 — an addon waiting forever is quieter and worse than
-/// the `attempt to call global` it got before.
+/// `RequestTimePlayed()` queues the ask; `TIME_PLAYED_MSG` carries the answer.
 #[test]
 fn request_time_played_queues_an_ask_and_the_answer_arrives_as_an_event() {
     let mut s = crate::script::UiScript::new().unwrap();
 
-    // The verb returns NOTHING — the answer is an event, never a return value.
     assert_eq!(s.arity("RequestTimePlayed()").unwrap(), 0);
-    // …and that call queued one ask. A COUNT, not a payload: the packet is empty, so two asks in a
-    // frame are two sends rather than one collapsed intent (the pvp queue's rule).
+    // A count, not a latch: the packet is empty, so two asks in a frame are two sends.
     s.run("RequestTimePlayed() RequestTimePlayed()").unwrap();
     assert_eq!(
         s.take_played_time_asks(),
@@ -155,7 +130,6 @@ fn request_time_played_queues_an_ask_and_the_answer_arrives_as_an_event() {
     );
     assert_eq!(s.take_played_time_asks(), 0, "the drain empties the queue");
 
-    // The answer half: the app fires the event with (total, level) in seconds.
     s.run(
         r#"
         TPSeen = nil
@@ -179,9 +153,7 @@ fn request_time_played_queues_an_ask_and_the_answer_arrives_as_an_event() {
     );
 }
 
-/// **The engine hands caught script errors to the CHOSEN Lua error handler** (decision 1305) —
-/// the reference's `seterrorhandler` contract, which is how `_ERRORMESSAGE`'s dialog (or an
-/// addon's own ImprovedErrorFrame-style handler) ever hears about a failure the engine caught.
+/// `seterrorhandler`'s contract: an engine-caught script error goes to the chosen handler.
 #[test]
 fn a_chosen_error_handler_hears_engine_caught_errors_and_the_default_does_not_duplicate() {
     let mut s = crate::script::UiScript::new().unwrap();
@@ -193,8 +165,7 @@ fn a_chosen_error_handler_hears_engine_caught_errors_and_the_default_does_not_du
     )
     .unwrap();
 
-    // Nobody chose a handler: the error lands on the host channel ONCE, and the dispatch —
-    // recognising the stdlib default by identity — adds nothing.
+    // With the stdlib default handler, recognised by identity, the dispatch adds nothing.
     s.fire_event("B271_PROBE", vec![]);
     s.dispatch_script_errors_to_handler();
     let errors = s.take_errors();
@@ -204,8 +175,7 @@ fn a_chosen_error_handler_hears_engine_caught_errors_and_the_default_does_not_du
         "one error, once — the default handler must not double-report: {errors:?}"
     );
 
-    // An addon chose one: the dispatch fires it with the message, and the host channel STILL
-    // records the error (the dual channel is what keeps the harness's instruments sighted).
+    // A chosen handler gets the message, and the host channel still records it.
     s.run("caught = {} seterrorhandler(function(msg) table.insert(caught, msg) end)")
         .unwrap();
     s.fire_event("B271_PROBE", vec![]);
@@ -226,11 +196,6 @@ fn a_chosen_error_handler_hears_engine_caught_errors_and_the_default_does_not_du
     );
 }
 
-/// **Every handler path reaches the chosen handler, not only `OnEvent`.** The widget scripts —
-/// `OnClick`, `OnValueChanged`, the edit box's and keyboard's, the tooltip's — pushed their errors
-/// onto the host channel alone, so an addon's broken click handler was a terminal line and never
-/// the dialog, while the same error from `OnEnter` did pop it (decision 1305's "every
-/// engine-caught script error", which these paths had never joined).
 #[test]
 fn a_widget_handler_error_reaches_the_chosen_error_handler() {
     let mut s = crate::script::UiScript::new().unwrap();
@@ -254,11 +219,7 @@ fn a_widget_handler_error_reaches_the_chosen_error_handler() {
     assert!(caught.contains("slide boom"), "OnValueChanged: {caught}");
 }
 
-/// **A listener that unregisters itself does not rob the next one** — on the engine-internal
-/// dispatch too (`fire_global`: `ADDON_LOADED` for a `LoadAddOn`, `UPDATE_FACTION` from the
-/// faction-header verbs). That walk stepped an index over the live list, so the hook-once idiom
-/// (`this:UnregisterEvent(event)` inside the handler) shifted the successor into the slot just
-/// visited and it never heard the event — the 1324 bug, fixed in `fire_event` and not here.
+/// `fire_global` carries `UPDATE_FACTION` from the faction-header verbs.
 #[test]
 fn a_self_unregistering_listener_does_not_rob_its_successor_on_the_internal_dispatch() {
     let s = crate::script::UiScript::new().unwrap();
@@ -274,8 +235,7 @@ fn a_self_unregistering_listener_does_not_rob_its_successor_on_the_internal_disp
     assert_eq!(s.eval::<String>("return log").unwrap(), "ab");
 }
 
-/// **A handler that itself raises cannot recurse the error path** — its failure is recorded on
-/// the host channel only, never re-queued, and the batch stops on the first handler failure.
+/// The handler's own failure goes to the host channel only, never re-queued; the batch stops.
 #[test]
 fn an_error_handler_that_errors_does_not_recurse() {
     let mut s = crate::script::UiScript::new().unwrap();
@@ -300,7 +260,6 @@ fn an_error_handler_that_errors_does_not_recurse() {
             .any(|e| e.contains("error handler itself failed")),
         "and so is the handler's own failure, named as such: {errors:?}"
     );
-    // A second dispatch finds an EMPTY queue — the handler's failure was never re-queued.
     s.dispatch_script_errors_to_handler();
     assert!(
         s.take_errors().is_empty(),
diff --git a/crates/benilla-ui/src/script/tests/model_clock.rs b/crates/benilla-ui/src/script/tests/model_clock.rs
index f5429d19..2420bda3 100644
--- a/crates/benilla-ui/src/script/tests/model_clock.rs
+++ b/crates/benilla-ui/src/script/tests/model_clock.rs
@@ -1,16 +1,5 @@
-//! **The model pane's clock, arm, and two handlers** (decision 2007; `0x76d7f0`, `0x7121a0`,
-//! `0x76cac0`).
-//!
-//! A `<Model>` widget owns a private scene whose clock its own `OnUpdate` advances while the
-//! frame is visible; `SetSequence`/`SetSequenceTime` arm a sequence with an anchor the sampler
-//! re-reads; `OnUpdateModel` fires at the top of every paint and `OnAnimFinished` from the
-//! completion of a clamped sequence. Every one of those is Lua-observable — the shipped cooldown
-//! sweep is nothing but those handlers driving `SetSequenceTime` — so the law is tested here
-//! against the stock `Cooldown.lua`, transcribed verbatim.
-//!
-//! The engine parses no M2, so a file's sequences and bounds are **facts** the host hands over
-//! ([`ModelFileFacts`]); these tests hand over the facts `benilla-extract m2seq` reads off the
-//! shipped files.
+//! The model pane's clock, sequence arm and handlers (`0x76d7f0`, `0x7121a0`, `0x76cac0`). The
+//! engine parses no M2: a file's sequences and bounds are [`ModelFileFacts`] the host hands over.
 
 use super::common::script;
 use crate::script::{Model, UiScript};
@@ -32,15 +21,13 @@ fn facts(rows: &[(u16, u32, bool)]) -> ModelFileFacts {
     }
 }
 
-/// `UI-Cooldown-Indicator.m2` (`m2seq`): seq 0 = id 0, 1000 ms, clamp; seq 1 = id 1, 1000 ms,
-/// clamp.
+/// `UI-Cooldown-Indicator.m2`'s sequences as `m2seq` reads them.
 const COOLDOWN_FILE: &str = r"Interface\Cooldown\UI-Cooldown-Indicator.mdx";
 fn cooldown_facts() -> ModelFileFacts {
     facts(&[(0, 1000, false), (1, 1000, false)])
 }
 
-/// `MinimapPing.m2` (`m2seq`): seq 0 = id 127, 1333 ms, clamp; seq 1 = id 0, 833 ms, LOOP; seq
-/// 2 = id 1, 333 ms, clamp. `SetSequence(0)` is the looping one.
+/// `MinimapPing.m2`'s sequences as `m2seq` reads them; `SetSequence(0)` is the looping one.
 const PING_FILE: &str = r"Interface\MiniMap\Ping\MinimapPing.mdx";
 fn ping_facts() -> ModelFileFacts {
     facts(&[(127, 1333, false), (0, 833, true), (1, 333, false)])
@@ -64,9 +51,7 @@ fn play_head(s: &UiScript, name: &str, path: &str) -> Option<(u16, u32)> {
     m.play_head(facts).map(|p| (p.anim_id, p.cursor_ms))
 }
 
-/// The widget's `OnUpdate` (`0x76d7f0`) advances the scene clock by `trunc(elapsed · 1000)` —
-/// only while the frame is visible (the UI pump walks visible frames), so a hidden pane's clock
-/// stands still and a re-shown pane resumes where it stopped.
+/// `OnUpdate` (`0x76d7f0`) adds `trunc(elapsed · 1000)` ms, for visible frames only.
 #[test]
 fn the_clock_runs_only_while_the_pane_is_shown_and_truncates() {
     let mut s = script();
@@ -97,20 +82,18 @@ fn the_clock_runs_only_while_the_pane_is_shown_and_truncates() {
         "re-shown: resumes where it stopped"
     );
 
-    // The looping sequence wraps on its 833 ms and never completes.
+    // The looping sequence wraps on its 833 ms.
     assert_eq!(play_head(&s, "Ping", PING_FILE), Some((0, 616)));
     s.tick(0.5); // clock 1116 → 1116 mod 833
     assert_eq!(play_head(&s, "Ping", PING_FILE), Some((0, 283)));
 }
 
-/// `SetModel` runs the loader's completion (`0x70ebd0`) — arm **Stand** (id 0 if the file owns
-/// it, else `animations[0]`'s id), variation 0 — synchronously when the facts are known, and when
-/// they land otherwise; until then the pane is a waiter and the host is asked for the file.
+/// The loader's completion (`0x70ebd0`) arms Stand (id 0 if the file owns it, else
+/// `animations[0]`'s id), at `SetModel` when the facts are known or when they land.
 #[test]
 fn set_model_seeds_stand_now_or_when_the_facts_land() {
     let mut s = script();
     s.set_screen_size(800.0, 600.0);
-    // Facts first: the arm is immediate.
     s.set_model_facts(COOLDOWN_FILE, cooldown_facts());
     s.run(&format!(
         r#"a = CreateFrame("Model", "Known", UIParent) a:SetModel("{}")"#,
@@ -126,7 +109,6 @@ fn set_model_seeds_stand_now_or_when_the_facts_land() {
     );
     assert_eq!(play_head(&s, "Known", COOLDOWN_FILE), Some((0, 0)));
 
-    // Facts unknown: a waiter, and the file goes on the host's list once.
     s.run(&format!(
         r#"b = CreateFrame("Model", "Waiting", UIParent) b:SetModel("{0}")
            c = CreateFrame("Model", "Waiting2", UIParent) c:SetModel("{0}")"#,
@@ -142,7 +124,6 @@ fn set_model_seeds_stand_now_or_when_the_facts_land() {
     );
     assert!(s.model_facts_wanted().is_empty(), "drained");
 
-    // The facts land: every waiter holding the file arms its Stand at its own clock.
     s.tick(0.25);
     s.set_model_facts(PING_FILE, ping_facts());
     for name in ["Waiting", "Waiting2"] {
@@ -155,7 +136,6 @@ fn set_model_seeds_stand_now_or_when_the_facts_land() {
         );
     }
 
-    // A file that does not own id 0 seeds `animations[0]`'s own id.
     s.set_model_facts(
         r"Interface\Odd.mdx",
         facts(&[(204, 500, true), (166, 500, true)]),
@@ -165,9 +145,7 @@ fn set_model_seeds_stand_now_or_when_the_facts_land() {
     assert_eq!(pane(&s, "Odd").armed.map(|a| a.anim_id), Some(204));
 }
 
-/// `SetSequence(id)` with an id the file does not own **stops what was playing and arms
-/// nothing** — `0x7121a0`'s interrupt runs before its bounds check. A queued arm on a
-/// file still loading is kept until the facts say otherwise.
+/// `0x7121a0` interrupts the track before its bounds check; a queued arm waits for the facts.
 #[test]
 fn an_unowned_id_stops_the_track_and_arms_nothing() {
     let mut s = script();
@@ -183,7 +161,6 @@ fn an_unowned_id_stops_the_track_and_arms_nothing() {
     assert_eq!(pane(&s, "P").sequence, 42, "the raw id is still recorded");
     assert!(pane(&s, "P").armed.is_none(), "…but nothing plays");
 
-    // Queued on an unloaded file, then refused when the facts land.
     s.run(r#"q = CreateFrame("Model", "Q", UIParent) q:SetModel("Interface\\Late.mdx") q:SetSequence(7)"#)
         .unwrap();
     assert_eq!(
@@ -198,8 +175,7 @@ fn an_unowned_id_stops_the_track_and_arms_nothing() {
          own — nothing plays"
     );
 
-    // The other order of the same replay: a queued arm the file DOES own wins over the seed,
-    // at its original offset, re-anchored on the clock the file landed on.
+    // A queued arm the file owns wins over the seed, re-anchored on the landing clock.
     s.run(r#"r = CreateFrame("Model", "R", UIParent) r:SetModel("Interface\\Later.mdx") r:SetSequenceTime(5, 40)"#)
         .unwrap();
     s.tick(0.3);
@@ -211,17 +187,13 @@ fn an_unowned_id_stops_the_track_and_arms_nothing() {
     assert_eq!((a.anim_id, a.armed_at_ms, a.anchor_ms), (5, 300, 300 - 40));
 }
 
-/// The shipped cooldown, on the two handlers and nothing else — `Cooldown.lua` verbatim:
-/// `SetTimer` arms sequence 0 and shows; every paint `OnUpdateModel` scrubs
-/// `SetSequenceTime(0, elapsed/duration · 1000)` until done, then flips to sequence 1 at 0; the
-/// flash's completion (`OnAnimFinished`, 1000 ms later) hides the frame.
+/// The stock `Cooldown.lua`, which runs on `OnUpdateModel` and `OnAnimFinished` alone.
 #[test]
 fn the_cooldown_machine_runs_on_the_two_handlers() {
     let mut s = script();
     s.set_screen_size(800.0, 600.0);
     s.set_model_facts(COOLDOWN_FILE, cooldown_facts());
-    // `SetTimer`'s gate is `start > 0`: a session clock still at 0 refuses the timer, as the
-    // reference's would — so the session is a second old before the button is pressed.
+    // `SetTimer` gates on `start > 0`, so the session clock must be past 0.
     s.tick(1.0);
     s.run(&format!(
         r#"
@@ -272,22 +244,18 @@ fn the_cooldown_machine_runs_on_the_two_handlers() {
     assert!(s.frame_visible("CD"));
     assert_eq!(play_head(&s, "CD", COOLDOWN_FILE), Some((0, 0)));
 
-    // The sweep: each paint scrubs sequence 0 to the elapsed fraction.
     s.tick(0.5);
     assert_eq!(play_head(&s, "CD", COOLDOWN_FILE), Some((0, 250)));
     s.tick(1.0);
     assert_eq!(play_head(&s, "CD", COOLDOWN_FILE), Some((0, 750)));
-    // A scrub is an ANCHOR, not a freeze: between two paints the clock runs on from it. The
-    // cooldown never sees that (it re-scrubs every paint), the ping relies on it.
+    // A scrub is an anchor, not a freeze: between paints the clock runs on from it.
     assert_eq!(pane(&s, "CD").armed.map(|a| a.anchor_ms), Some(1500 - 750));
 
-    // Done: the flip to the flash, sequence 1 at 0.
     s.tick(0.6);
     assert_eq!(play_head(&s, "CD", COOLDOWN_FILE), Some((1, 0)));
     assert!(s.frame_visible("CD"));
     assert_eq!(s.eval::<i64>("return cd.stopping").unwrap(), 1);
 
-    // The flash runs its 1000 ms; the completion fires once, and the handler hides the frame.
     s.tick(0.5);
     assert_eq!(play_head(&s, "CD", COOLDOWN_FILE), Some((1, 500)));
     assert!(s.eval::<bool>("return table.getn(fired) == 0").unwrap());
@@ -301,15 +269,13 @@ fn the_cooldown_machine_runs_on_the_two_handlers() {
         !s.frame_visible("CD"),
         "…which the stock handler turns into Hide()"
     );
-    // Hidden: no paint, no second completion, the cursor holds at the end.
     s.tick(1.0);
     assert_eq!(s.eval::<i64>("return table.getn(fired)").unwrap(), 1);
     assert_eq!(play_head(&s, "CD", COOLDOWN_FILE), Some((1, 1000)));
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// `OnUpdateModel` runs with `this` set, once per paint of a **visible** pane, before the
-/// completion is read — so a handler that re-arms in the same paint completes nothing.
+/// `OnUpdateModel` runs before the completion is read, so re-arming each paint completes nothing.
 #[test]
 fn on_update_model_fires_per_visible_paint_with_this() {
     let mut s = script();
@@ -342,7 +308,6 @@ fn on_update_model_fires_per_visible_paint_with_this() {
         2,
         "no paint while hidden"
     );
-    // Re-arming every paint keeps the clamped sequence from ever completing.
     s.run("M:Show() M:SetScript(\"OnUpdateModel\", function() this:SetSequenceTime(1, 0) end)")
         .unwrap();
     for _ in 0..30 {
@@ -351,9 +316,8 @@ fn on_update_model_fires_per_visible_paint_with_this() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// A LOOPING sequence fires `OnAnimFinished` once too — at the end of its first pass — and keeps
-/// looping (`0x719370` enqueues the completion before it tests the loop flag). And a pane with no
-/// file fires no `OnUpdateModel` at all (`76d24c`'s gate), however visible.
+/// `0x719370` enqueues the completion before it tests the loop flag, so a loop's first pass fires
+/// `OnAnimFinished`; a pane with no file fails `0x76d24c`'s gate and never paints.
 #[test]
 fn a_loop_completes_once_and_a_fileless_pane_paints_nothing() {
     let mut s = script();
@@ -409,9 +373,8 @@ fn a_loop_completes_once_and_a_fileless_pane_paints_nothing() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **The implicit rect** (decision 2015): a model pane that authored no size takes its file's
-/// bounding-box extent in LAYOUT units — `768·√(a²+1)` FrameXML units per unit, `1280` at 4:3
-/// — the moment the facts are known; it follows the screen's aspect; an authored size wins.
+/// A pane with no authored size takes its file's bounding box in layout units, `768·√(a²+1)`
+/// FrameXML units each (1280 at 4:3), following the screen's aspect.
 #[test]
 fn a_size_less_pane_takes_its_files_rect_in_layout_units() {
     let mut s = script();
@@ -463,7 +426,7 @@ fn a_size_less_pane_takes_its_files_rect_in_layout_units() {
     assert_eq!((bw, bh), (50.0, 20.0), "an authored size is untouched");
     assert!(pane(&s, "Sized").implicit_size && !pane(&s, "Authored").implicit_size);
 
-    // 16:9 — a layout unit is 768·√((16/9)²+1) = 1566.4 FrameXML units.
+    // At 16:9 a layout unit is 768·√((16/9)²+1) = 1566.4 FrameXML units.
     s.set_screen_size(1600.0, 900.0);
     s.resolve();
     let w: f32 = s.eval("return Sized:GetWidth()").unwrap();
@@ -477,9 +440,7 @@ fn a_size_less_pane_takes_its_files_rect_in_layout_units() {
     assert_eq!(s.eval::<f32>("return Sized:GetWidth()").unwrap(), 10.0);
 }
 
-/// `ReplaceIconTexture` is the type-14 texture override on the INSTANCE: stored over a file
-/// (queued and replayed while it streams), dropped with no file, released by `SetModel` and
-/// `ClearModel`.
+/// The type-14 texture override belongs to the model instance and dies with it.
 #[test]
 fn replace_icon_texture_lives_and_dies_with_the_instance() {
     let mut s = script();
@@ -523,8 +484,7 @@ fn replace_icon_texture_lives_and_dies_with_the_instance() {
     );
 }
 
-/// The XML `scale=` on a model pane is the MODEL's scale (`0x76cac0` → `+0x3a0`), never the
-/// frame's — the cooldown template's 0.75 must not shrink the widget's rect.
+/// A model pane's XML `scale=` is the model's scale (`0x76cac0`, `+0x3a0`), never the frame's.
 #[test]
 fn the_model_scale_attribute_is_the_models_own() {
     let mut s = script();
diff --git a/crates/benilla-ui/src/script/tests/modelframe.rs b/crates/benilla-ui/src/script/tests/modelframe.rs
index 670f2b03..9c0bbbd9 100644
--- a/crates/benilla-ui/src/script/tests/modelframe.rs
+++ b/crates/benilla-ui/src/script/tests/modelframe.rs
@@ -1,22 +1,9 @@
-//! **The model-pane family's Lua surface** — `Model` and `PlayerModel`, read back through the API
-//! that wrote them.
-//!
-//! The property under test throughout is that these widgets are *state the app renders*, not state
-//! the engine interprets: every setter's value must come back out unchanged, and the places where
-//! the widget does have an opinion (one yaw slot written by two verbs on two classes; content being
-//! an either/or) must hold.
-//!
-//! Plus the one structural property, guarded as a whole block:
-//! [`the_two_model_tables_are_the_references_own`] asserts our surfaces against the reference's
-//! enumerated tables in **both** directions, so neither a missing verb nor an invented one can slip
-//! past — and so `Model` can never re-acquire the three that are `PlayerModel`'s.
+//! The `Model` and `PlayerModel` Lua surface, read back through the API that wrote it, and checked
+//! against the reference's method tables in both directions.
 
 use super::common::script;
 use crate::script::UiScript;
 
-/// The whole scene, set and read back — plus the widget's three actual behaviours: `SetRotation`
-/// and `SetFacing` are one slot, `SetModel` and `SetUnit` displace each other, and `ClearModel`
-/// empties both.
 #[test]
 fn the_model_pane_holds_the_scene_it_was_given() {
     let mut s = script();
@@ -24,8 +11,7 @@ fn the_model_pane_holds_the_scene_it_was_given() {
     s.run(r#"m = CreateFrame("Model", "MPane", UIParent)"#)
         .unwrap();
 
-    // A fresh pane: no content, unit SCALE (not zero — a model at scale 0 is invisible, which is
-    // why ModelState hand-writes its Default), no yaw, at the origin.
+    // A fresh pane: no model, scale 1 (not 0, which would draw nothing), no yaw.
     assert_eq!(
         s.eval::<(Option<String>, f64, f64)>(
             "return MPane:GetModel(), MPane:GetModelScale(), MPane:GetFacing()"
@@ -35,8 +21,7 @@ fn the_model_pane_holds_the_scene_it_was_given() {
         "a fresh pane has no model and unit scale"
     );
 
-    // The path round-trips verbatim — the client's own path space, backslashes and `.mdx` intact.
-    // pfUI's autocast shine is exactly this call.
+    // The path round-trips verbatim, backslashes and `.mdx` intact (pfUI's autocast shine).
     s.run(r#"MPane:SetModel("Interface\\Buttons\\UI-AutoCastButton.mdx")"#)
         .unwrap();
     assert_eq!(
@@ -44,12 +29,10 @@ fn the_model_pane_holds_the_scene_it_was_given() {
         r"Interface\Buttons\UI-AutoCastButton.mdx"
     );
 
-    // The yaw. `SetFacing` is the `Model` verb for it (`0x878948[4]`); `SetRotation` writes the
-    // same field but belongs to `PlayerModel` and is tested there.
+    // `SetFacing` is the `Model` yaw verb (`0x878948[4]`).
     s.run("MPane:SetFacing(-0.25)").unwrap();
     assert_eq!(s.eval::<f64>("return MPane:GetFacing()").unwrap(), -0.25);
 
-    // Scale, camera, position — plain storage, read back through their own getters.
     s.run("MPane:SetModelScale(0.4) MPane:SetCamera(2) MPane:SetPosition(0.1, -0.2, 3)")
         .unwrap();
     assert_eq!(
@@ -63,8 +46,6 @@ fn the_model_pane_holds_the_scene_it_was_given() {
         "GetPosition returns the three numbers SetPosition took"
     );
 
-    // `SetModel(nil)` is the documented clear and reaches the same place `ClearModel` does — not
-    // everything in the corpus calls the dedicated verb.
     s.run("MPane:ClearModel()").unwrap();
     assert_eq!(
         s.eval::<Option<String>>("return MPane:GetModel()").unwrap(),
@@ -72,16 +53,9 @@ fn the_model_pane_holds_the_scene_it_was_given() {
     );
 }
 
-/// **A `<PlayerModel>` is a `<Model>` plus exactly three verbs — and the inheritance runs one way.**
-///
-/// The client registers four model-pane types and each has its own Lua method table that never
-/// repeats its base's; a derived pane reaches its base through the miss leg of `vtable+0x8`
-/// (`0x7020b0`). So `PlayerModel`'s three-entry table `0x84f1fc` must sit *over* `Model`'s 23-entry
-/// `0x878948`, and nothing may chain the other way: `CSimpleModel`'s lookup `0x76f870` has no leg
-/// into `CGCharacterModelBase`'s `0x506260`.
-///
-/// This is the shape pfUI's unit frames need — `CreateFrame("PlayerModel", ...)` driven by
-/// `SetUnit` + `SetCamera`, one verb from each table on the same frame.
+/// Each model-pane type has its own method table and reaches its base's through the miss leg of
+/// `vtable+0x8` (`0x7020b0`): `PlayerModel`'s three (`0x84f1fc`) sit over `Model`'s 23
+/// (`0x878948`), and `CSimpleModel`'s lookup `0x76f870` has no leg into `0x506260`.
 #[test]
 fn a_player_model_is_a_model_plus_three_and_the_chain_runs_one_way() {
     let mut s = script();
@@ -94,7 +68,6 @@ fn a_player_model_is_a_model_plus_three_and_the_chain_runs_one_way() {
     )
     .unwrap();
 
-    // Its own three resolve on the PlayerModel...
     for verb in ["SetUnit", "RefreshUnit", "SetRotation"] {
         assert_eq!(
             s.eval::<String>(&format!("return type(PMPane.{verb})"))
@@ -102,8 +75,6 @@ fn a_player_model_is_a_model_plus_three_and_the_chain_runs_one_way() {
             "function",
             "PlayerModel must answer its own {verb}"
         );
-        // ...and on the plain Model they are ABSENT. This is the assertion that would have caught
-        // three years of `SetUnit` published on the wrong class.
         assert_eq!(
             s.eval::<String>(&format!("return type(MOnly.{verb})"))
                 .unwrap(),
@@ -112,7 +83,7 @@ fn a_player_model_is_a_model_plus_three_and_the_chain_runs_one_way() {
         );
     }
 
-    // ...and the base's verbs resolve through the chain, unrepeated. pfUI's portrait line.
+    // pfUI's portrait line: `SetUnit`, then the base's `SetCamera` through the chain.
     s.run(r#"PMPane:SetUnit("player") PMPane:SetCamera(0)"#)
         .unwrap();
     assert_eq!(
@@ -129,8 +100,7 @@ fn a_player_model_is_a_model_plus_three_and_the_chain_runs_one_way() {
         "...and back the other way, the direction an addon reskinning a paper doll takes"
     );
 
-    // `SetRotation` writes THE SAME yaw field `SetFacing` does — `0x505bb0`'s last instruction is
-    // `mov [esi+0x39c], eax`, and `+0x39c` is what `0x76dce0` writes. `GetFacing` reads either.
+    // `SetRotation` (`0x505bb0`) and `SetFacing` (`0x76dce0`) write the same yaw field, `+0x39c`.
     s.run("PMPane:SetRotation(1.5)").unwrap();
     assert_eq!(s.eval::<f64>("return PMPane:GetFacing()").unwrap(), 1.5);
     s.run("PMPane:SetFacing(-0.25)").unwrap();
@@ -140,12 +110,11 @@ fn a_player_model_is_a_model_plus_three_and_the_chain_runs_one_way() {
         "one slot: SetFacing overwrites what SetRotation wrote"
     );
 
-    // RefreshUnit is a live no-op: the pane stores the unit TOKEN and resolves it at render, so
-    // there is no cached appearance to invalidate. It must still exist — the reference's own
-    // DressUp/PaperDoll frames call it, so an addon hooking them will too.
+    // `RefreshUnit` is a no-op, as the pane resolves its unit token at render; stock
+    // `PaperDollFrame.xml:221` calls it.
     assert!(s.run("PMPane:RefreshUnit()").is_ok());
 
-    // ClearModel — a `Model` verb reached through the chain — empties BOTH content slots.
+    // `ClearModel`, reached through the chain, empties both content slots.
     s.run(r#"PMPane:SetUnit("player") PMPane:ClearModel()"#)
         .unwrap();
     assert_eq!(
@@ -155,19 +124,8 @@ fn a_player_model_is_a_model_plus_three_and_the_chain_runs_one_way() {
     );
 }
 
-/// **`SetModel(nil)` raises; `ClearModel()` clears. They are not the same verb.**
-///
-/// This binding asserted the opposite until 2026-08-30 — "the documented clear, and how the corpus
-/// writes 'no model'" — which was invented, not read. `0x76d950` is shape A (decision 1717's
-/// taxonomy): `lua_isstring` gates the argument and `Usage: %s:SetModel("file")` is raised on
-/// anything that is not a string or a number. `ClearModel 0x76db20` is a separate table entry.
-///
-/// The same gate on `ReplaceIconTexture 0x76ed70`, whose *whole* observable behaviour it is: the
-/// swap itself lands on a `CM2Model` we do not have, and with no CM2Model the reference drops the
-/// call and never replays it.
-///
-/// A NUMBER is accepted by both — `lua_isstring` takes tags 3|4 and the client renders it to
-/// decimal text — which is the half a `Value::String`-only match would get wrong.
+/// `SetModel` (`0x76d950`) and `ReplaceIconTexture` (`0x76ed70`) gate on `lua_isstring`, raising
+/// their usage string on anything but a string or a number; `ClearModel` (`0x76db20`) is the clear.
 #[test]
 fn the_string_setters_gate_their_argument_and_a_number_is_a_string() {
     let mut s = script();
@@ -183,26 +141,23 @@ fn the_string_setters_gate_their_argument_and_a_number_is_a_string() {
             "SetModel({bad}) must raise — it is not the clear"
         );
     }
-    // ...and none of those raises disturbed the path that was already set.
     assert_eq!(
         s.eval::<String>("return GateM:GetModel()").unwrap(),
         r"Interface\Buttons\A.mdx",
         "a raised setter leaves the pane alone"
     );
-    // A number IS a string to `lua_isstring`, and the client renders it to decimal text.
+    // A number passes `lua_isstring` and is stored as its decimal text.
     s.run("GateM:SetModel(42)").unwrap();
     assert_eq!(s.eval::<String>("return GateM:GetModel()").unwrap(), "42");
 
-    // ClearModel is the clear, takes no argument, and empties the pane.
     s.run("GateM:ClearModel()").unwrap();
     assert_eq!(
         s.eval::<Option<String>>("return GateM:GetModel()").unwrap(),
         None
     );
 
-    // `ReplaceIconTexture` — same gate, and that gate is all of it. A good argument is accepted
-    // and changes NOTHING observable: the swap targets the CM2Model's type-14 textures, and a
-    // pane with no CM2Model drops the call (the reference's own `[widget+0x318] == 0` leg).
+    // `ReplaceIconTexture` swaps the CM2Model's type-14 textures, and a pane with none
+    // (`[widget+0x318] == 0`) drops the call, so only the gate is observable.
     for bad in ["nil", "{}", "true", ""] {
         assert!(
             s.run(&format!("GateM:ReplaceIconTexture({bad})")).is_err(),
@@ -219,7 +174,7 @@ fn the_string_setters_gate_their_argument_and_a_number_is_a_string() {
         "it is a MATERIAL swap, not a content setter — the pane's model is untouched"
     );
 
-    // `AdvanceTime` takes nothing, returns nothing, and does nothing — verified, not stubbed.
+    // The reference's `AdvanceTime` takes nothing, returns nothing and does nothing.
     assert_eq!(
         s.eval::<usize>("return table.getn({ GateM:AdvanceTime() })")
             .unwrap(),
@@ -228,25 +183,11 @@ fn the_string_setters_gate_their_argument_and_a_number_is_a_string() {
     );
 }
 
-/// **The whole block, both directions** — decision 1718's rule applied to the two model tables.
-///
-/// The lists below are the reference's OWN enumerations, transcribed entry-for-entry from `Model`'s
-/// table `0x878948` and `PlayerModel`'s `0x84f1fc` (each table's count fixed twice: the registering
-/// `mov edx, imm32`, and the dword at `base + 8*count` being the start of the string pool). They
-/// are **not** the names anyone noticed were missing — that is exactly the mistake 1718 records,
-/// and it was re-made inside the test written to enforce it.
-///
-/// Guarding both directions is the point:
-///
-/// - **no gap** — every reference name we claim to publish must resolve;
-/// - **no superset** — a name the reference does not have on a table must not resolve there
-///   (1189: a name we have and the reference lacks routes an addon down a path the real client
-///   never takes);
-/// - **the `UNBUILT` set must stay absent** — it is empty since 2027, so "unbuilt" cannot
-///   quietly become "stubbed" without this test being edited to say so.
+/// The reference's own method tables, entry for entry (`Model` `0x878948`, `PlayerModel`
+/// `0x84f1fc`), checked both ways: every name resolves, and a name a table lacks does not.
 #[test]
 fn the_two_model_tables_are_the_references_own() {
-    /// `Model` — `CSimpleModel`, table `0x878948`, 23 entries, in table order.
+    /// `Model`, `CSimpleModel`'s table `0x878948`, in table order.
     const MODEL_23: [&str; 23] = [
         "SetModel",
         "GetModel",
@@ -272,14 +213,9 @@ fn the_two_model_tables_are_the_references_own() {
         "GetFogFar",
         "ClearFog",
     ];
-    /// `PlayerModel` — `CGCharacterModelBase`, table `0x84f1fc`, 3 entries, in table order.
+    /// `PlayerModel`, `CGCharacterModelBase`'s table `0x84f1fc`, in table order.
     const PLAYERMODEL_3: [&str; 3] = ["SetUnit", "RefreshUnit", "SetRotation"];
-    /// The subset of [`MODEL_23`] this client does not build. Named, not stubbed (1134 §4).
-    /// **Empty since decision 2027** — the last five were the fog near/far set, held back only
-    /// because `ClearFog`'s effect on the colour/near/far triple was uncarved;
-    /// `76f5c5 and [edi+0x3a4],-2` shows bit 0 alone, so the guess is gone and the verbs are
-    /// real. Kept as an empty array rather than deleted: the wall below is the thing that
-    /// notices when a name arrives or leaves.
+    /// The names in [`MODEL_23`] this client leaves unbuilt, absent rather than stubbed: none.
     const UNBUILT: [&str; 0] = [];
 
     let mut s = script();
@@ -299,7 +235,7 @@ fn the_two_model_tables_are_the_references_own() {
 
     for name in MODEL_23 {
         let want = !UNBUILT.contains(&name);
-        // A `Model` verb resolves on BOTH panes — on the PlayerModel through the chain.
+        // A `Model` verb resolves on both panes, on the PlayerModel through the chain.
         for frame in ["GuardM", "GuardPM"] {
             assert_eq!(
                 is_fn(&s, frame, name),
@@ -318,9 +254,7 @@ fn the_two_model_tables_are_the_references_own() {
             "GuardM.{name}: 0x84f1fc is NOT reachable from CSimpleModel's lookup"
         );
     }
-    // The two names a `strings` scan of the model band would tempt anyone into, which do not exist
-    // in 5875 in ANY form (substring scan of the mapped image returns 0, positive control 27 hits
-    // for `Creature`). They are later-expansion verbs; publishing one is decision 1189's error.
+    // Later-expansion verbs, absent from the 1.12 client image in any form.
     for name in ["SetCreature", "SetCustomRace"] {
         for frame in ["GuardM", "GuardPM"] {
             assert!(
@@ -331,11 +265,8 @@ fn the_two_model_tables_are_the_references_own() {
     }
 }
 
-/// **`SetSequence` and `SetSequenceTime` are one arm** (`0x7121a0`): each interrupts what plays
-/// and anchors the new sequence's cursor — at 0, or at the caller's `ms` — on the pane's own
-/// clock. The clock law itself (advance, wrap, completion, the two handlers) is
-/// `script::tests::model_clock`; this is the binding-level shape, with no file facts known, which
-/// is the state the reference's queued replay covers.
+/// `SetSequence` and `SetSequenceTime` share one arm (`0x7121a0`): each interrupts what plays and
+/// anchors the new sequence's cursor, at 0 or at the caller's `ms`, on the pane's own clock.
 #[test]
 fn the_two_sequence_verbs_arm_the_pane_on_its_own_clock() {
     let mut s = script();
@@ -350,8 +281,7 @@ fn the_two_sequence_verbs_arm_the_pane_on_its_own_clock() {
     )
     .unwrap();
 
-    // 1.12 has no `GetSequence`, so the arm is read off the model the way `simplehtml`'s tests
-    // read their blocks — through the arena, because there is no Lua getter to read it through.
+    // 1.12 has no `GetSequence`, so the arm is read off the arena.
     let armed = |s: &UiScript| {
         let lua = s.lua();
         let model = lua.app_data_ref::<crate::script::Model>().expect("model");
@@ -373,19 +303,14 @@ fn the_two_sequence_verbs_arm_the_pane_on_its_own_clock() {
         "a new sequence starts at its own 0 — the old anchor is not carried across"
     );
 
-    // ...and ClearModel releases the instance, arm included.
+    // `ClearModel` releases the instance, arm included.
     s.run("MSeq:SetSequenceTime(3, 40) MSeq:ClearModel()")
         .unwrap();
     assert_eq!(armed(&s).1, None);
 }
 
-/// `SetLight` writes the widget's embedded `CGLight` by the reference's own argument walk
-/// (`0x76e1e0`), and `GetLight` reads it back at arity **7 | 10 | 13**.
-///
-/// This test is the law, not a round trip: the tuple used to be stored verbatim because nobody had
-/// read the binding at the bytes, and "what went in comes out" is the one thing the reference does
-/// NOT do — the intensities are folded into the colours, the direction is normalised, and both
-/// traps change what a call means.
+/// `SetLight` writes the pane's `CGLight` by the reference's argument walk (`0x76e1e0`), folding
+/// intensities into colours and normalising the direction; `GetLight` answers 7, 10 or 13 values.
 #[test]
 fn the_light_tuple_is_opaque_and_survives_the_round_trip() {
     let mut s = script();
@@ -393,8 +318,7 @@ fn the_light_tuple_is_opaque_and_survives_the_round_trip() {
     s.run(r#"m = CreateFrame("Model", "MLight", UIParent)"#)
         .unwrap();
 
-    // A fresh pane: the ctor's white, switched off. Both colour blocks are `> 0`, so both come
-    // back as `1.0, r, g, b` — arity 13 before anything has ever been set.
+    // The constructor's light is off and white; both colour blocks are non-zero, so arity 13.
     let fresh: Vec<f64> = s.eval("return { MLight:GetLight() }").unwrap();
     assert_eq!(
         fresh,
@@ -402,19 +326,17 @@ fn the_light_tuple_is_opaque_and_survives_the_round_trip() {
         "the <Model> ctor: disabled, omni, at the origin, white ambient and diffuse"
     );
 
-    // The commented-out GlueXML line, which is the corpus's only example of the shape.
+    // The commented-out call at `CharacterCreate.lua:61`.
     s.run("MLight:SetLight(1, 0, 0, -0.707, -0.707, 0.7, 1, 1, 1, 0.8, 1, 1, 0.8)")
         .unwrap();
     let l: Vec<f64> = s.eval("return { MLight:GetLight() }").unwrap();
     assert_eq!(l.len(), 13);
     assert_eq!((l[0], l[1]), (1.0, 0.0), "enabled, directional");
-    // The direction is NORMALISED on write (`0x71b6a0`), so `(0, -0.707, -0.707)` comes back as
-    // a unit vector — the one place a naive round trip would disagree.
+    // The direction is normalised on write (`0x71b6a0`).
     let dir = [l[2], l[3], l[4]];
     let len = (dir[0] * dir[0] + dir[1] * dir[1] + dir[2] * dir[2]).sqrt();
     assert!((len - 1.0).abs() < 1e-5, "normalised on write: {dir:?}");
-    // The intensity is FOLDED into the colour: ambient `1,1,1` at `0.7` is `(0.7, 0.7, 0.7)`,
-    // and the reported intensity is a constant 1.0.
+    // The intensity is folded into the colour, so ambient `1,1,1` at 0.7 reads 0.7 at intensity 1.
     assert_eq!(l[5], 1.0);
     for c in &l[6..9] {
         assert!((c - 0.7).abs() < 1e-5, "ambient folded: {c}");
@@ -424,17 +346,14 @@ fn the_light_tuple_is_opaque_and_survives_the_round_trip() {
         assert!((c - want).abs() < 1e-5, "diffuse folded: {c} vs {want}");
     }
 
-    // TRAP 1: `SetLight(0, …)` returns before the local is copied, so it changes NOTHING — it is
-    // not a way to switch a light off, and a `<PlayerModel>`'s built-in one cannot be killed.
+    // `SetLight(0, …)` returns before the copy: a no-op, not a way to switch a light off.
     s.run("MLight:SetLight(0, 1, 5, 5, 5, 1, 1, 1, 1, 1, 1, 1, 1)")
         .unwrap();
     let after: Vec<f64> = s.eval("return { MLight:GetLight() }").unwrap();
     assert_eq!(after, l, "SetLight(0, …) is a no-op, not a disable");
 
-    // TRAP 2: an ambient intensity of 0 makes the walk skip its colour triple WITHOUT advancing
-    // the cursor, so the second intensity is read at index 8 — the seven-argument form. Here
-    // `1, 1, 1` are the ambient rgb the walk never reaches, and `0.5` is index 8 = the diffuse
-    // intensity against a white colour.
+    // A zero ambient intensity skips its colour triple without advancing the cursor, so the next
+    // argument (stack index 8) is the diffuse intensity: 0.5, against a white colour.
     s.run("MLight:SetLight(1, 1, 0, 0, 0, 0, 0.5)").unwrap();
     let t2: Vec<f64> = s.eval("return { MLight:GetLight() }").unwrap();
     assert_eq!(t2.len(), 10, "a zero ambient block collapses the arity");
@@ -448,11 +367,8 @@ fn the_light_tuple_is_opaque_and_survives_the_round_trip() {
     assert!(s.run(r#"MLight:SetLight(1, 0, 0, 0, 0)"#).is_err());
     assert!(s.run(r#"MLight:SetLight("x")"#).is_err());
 
-    // **Fog is NOT the same shape, and this used to assert the opposite.** It read "unset fog
-    // returns NOTHING rather than three zeros — a pane with no fog and a pane fogged to black are
-    // different states", which is a good argument about a model the client does not have: there is
-    // no unset state. The fog colour is one packed `0xAARRGGBB` dword whose ctor writes
-    // `0xffffffff`, so a fresh pane reads **four** values, `1, 1, 1, 1` (decision 1845).
+    // The fog colour is one packed `0xAARRGGBB` dword, `0xffffffff` from the constructor, so a
+    // fresh pane reads four values, all 1; there is no unset state.
     assert_eq!(
         s.eval::<usize>("return table.getn({ MLight:GetFogColor() })")
             .unwrap(),
@@ -465,9 +381,7 @@ fn the_light_tuple_is_opaque_and_survives_the_round_trip() {
         "never set is white and opaque, not four zeros"
     );
 
-    // Three arguments set alpha to **1.0**, not 0 — the fifth is guarded with that default where
-    // r/g/b are read unconditionally. The round trip is LOSSY by 8 bits a channel, because the
-    // store is that packed dword: 0.1 does not survive, 0.2 does.
+    // With three arguments alpha defaults to 1.0; the packed store keeps 8 bits a channel.
     s.run("MLight:SetFogColor(0.1, 0.2, 0.3)").unwrap();
     let (r, g, b, a): (f64, f64, f64, f64) = s.eval("return MLight:GetFogColor()").unwrap();
     assert_eq!(a, 1.0, "the omitted alpha defaults to 1.0");
@@ -478,7 +392,7 @@ fn the_light_tuple_is_opaque_and_survives_the_round_trip() {
         );
     }
 
-    // …and the alpha really is the fifth argument, on the same clamp as the rest.
+    // Alpha is the fourth argument, clamped like the rest.
     s.run("MLight:SetFogColor(1, 1, 1, 0)").unwrap();
     assert_eq!(
         s.eval::<f64>("local _, _, _, a = MLight:GetFogColor() return a")
@@ -487,13 +401,9 @@ fn the_light_tuple_is_opaque_and_survives_the_round_trip() {
     );
 }
 
-/// `SetCamera(n)` selects by **raw table index**, is bounds-checked against the file's camera
-/// count, defers until the file's facts land, and gates the paint until the question is settled —
-/// the four halves of `0x76cec0`/`0x76ce80`/`0x76ce00`/`76d5f0` (decision 2027).
-///
-/// The whole point of the state is which render leg a pane takes: an installed camera is the
-/// perspective leg, the NULL camera is the orthographic one, and an index past the count is a
-/// NULL camera rather than an error or a clamp to the last record.
+/// `SetCamera(n)` picks by raw index, checked against the file's camera count once the file is
+/// known, and the pane waits to draw until then (`0x76cec0`, `0x76ce80`, `0x76ce00`, `0x76d5f0`).
+/// A camera draws in perspective; none, or an index past the count, draws orthographic.
 #[test]
 fn set_camera_is_a_raw_index_bounds_checked_against_the_file() {
     use super::model_clock::pane;
@@ -518,23 +428,21 @@ fn set_camera_is_a_raw_index_bounds_checked_against_the_file() {
     s.set_screen_size(800.0, 600.0);
     s.run(r#"m = CreateFrame("Model", "MCam", UIParent) m:SetModel("Creature\\Wolf\\Wolf.mdx")"#)
         .unwrap();
-    // The ctor's standing request for camera 0 (`0x76c910` writes `+0x320 = 0`), still pending
-    // because the file's facts have not arrived — so the pane is NOT on the paint list.
+    // The constructor's request for camera 0 (`0x76c910` writes `+0x320 = 0`) waits for the file.
     assert_eq!(state(&s, "MCam"), (Some(0), None));
     assert!(s.visible_model_panes().is_empty(), "the draw gate holds");
 
-    // The facts land: the model-ready hook applies the pending index. Wolf has two cameras, so
-    // index 0 installs and the pane takes the perspective leg.
+    // The file lands with two cameras, so the pending index 0 installs: perspective.
     s.set_model_facts(FILE, facts(2));
     assert_eq!(state(&s, "MCam"), (None, Some(0)));
     assert_eq!(s.visible_model_panes().len(), 1, "the gate is settled");
 
-    // With the facts in hand `SetCamera` resolves immediately — raw index 1 is a real record.
+    // With the file known, `SetCamera` resolves at once.
     s.run("MCam:SetCamera(1)").unwrap();
     assert_eq!(state(&s, "MCam"), (None, Some(1)));
 
-    // An index past the count installs the NULL camera: the ORTHOGRAPHIC leg, and the pane keeps
-    // drawing. Not a clamp to the last record, not a raise.
+    // An index past the count installs no camera, not the last one, and the pane draws on,
+    // orthographic.
     s.run("MCam:SetCamera(7)").unwrap();
     assert_eq!(state(&s, "MCam"), (None, None));
     assert_eq!(s.visible_model_panes().len(), 1);
@@ -542,8 +450,7 @@ fn set_camera_is_a_raw_index_bounds_checked_against_the_file() {
     s.run("MCam:SetCamera(1) MCam:SetCamera(-1)").unwrap();
     assert_eq!(state(&s, "MCam"), (None, None));
 
-    // A file with no camera table at all: every index is out of range, so a plain <Model> on it
-    // is always the orthographic leg — which is every shipped in-game UI M2.
+    // A file with no cameras, like every shipped UI M2, always draws orthographic.
     let mut s = script();
     s.set_screen_size(800.0, 600.0);
     s.run(r#"m = CreateFrame("Model", "MFlat", UIParent) m:SetModel("Interface\\Cooldown\\UI-Cooldown-Indicator.mdx")"#)
@@ -551,8 +458,7 @@ fn set_camera_is_a_raw_index_bounds_checked_against_the_file() {
     s.set_model_facts(r"Interface\Cooldown\UI-Cooldown-Indicator.mdx", facts(0));
     assert_eq!(state(&s, "MFlat"), (None, None));
 
-    // `SetCamera` before the file is known DEFERS, and the deferred index is what the facts
-    // apply — bounds-checked then, not at the call.
+    // `SetCamera` before the file is known defers, and the index is checked when the file lands.
     let mut s = script();
     s.set_screen_size(800.0, 600.0);
     s.run(r#"m = CreateFrame("Model", "MLate", UIParent) m:SetCamera(1) m:SetModel("Creature\\Wolf\\Wolf.mdx")"#)
@@ -563,9 +469,8 @@ fn set_camera_is_a_raw_index_bounds_checked_against_the_file() {
     assert_eq!(state(&s, "MLate"), (None, Some(1)));
 }
 
-/// The fog block: `SetFogColor` **arms** it, `ClearFog` disarms **bit 0 alone**, and near/far are
-/// stored raw by the Lua setters (`0x76ee60`/`0x76f540`, decision 2027). The five verbs held back
-/// as uncarved since 1134 §4 are real now.
+/// `SetFogColor` arms the fog, `ClearFog` clears bit 0 alone (`0x76f5c5`), and the Lua setters
+/// store near and far raw (`0x76ee60`/`0x76f540`).
 #[test]
 fn the_fog_block_arms_on_colour_and_clears_only_its_bit() {
     use super::model_clock::pane;
@@ -579,8 +484,7 @@ fn the_fog_block_arms_on_colour_and_clears_only_its_bit() {
     s.set_screen_size(800.0, 600.0);
     s.run(r#"m = CreateFrame("Model", "MFog", UIParent)"#)
         .unwrap();
-    // The ctor: fog OFF, near 0.0, far **1.0** (`76c950`) — not far 0, which would be a
-    // degenerate ramp the batch would refuse.
+    // The constructor's fog: off, near 0, far 1 (`0x76c950`).
     assert_eq!(fog(&s), (false, 0.0, 1.0));
     assert_eq!(
         s.eval::<(f64, f64)>("return MFog:GetFogNear(), MFog:GetFogFar()")
@@ -588,14 +492,13 @@ fn the_fog_block_arms_on_colour_and_clears_only_its_bit() {
         (0.0, 1.0)
     );
 
-    // The glue's own call shape. `SetFogColor` is the arming verb; near/far are not.
+    // `GlueParent.lua:213-215` with the Tauren row (`:18`); only `SetFogColor` arms the fog.
     s.run("MFog:SetFogNear(0) MFog:SetFogFar(153)").unwrap();
     assert_eq!(fog(&s), (false, 0.0, 153.0), "near/far do not arm the fog");
     s.run("MFog:SetFogColor(1.0, 0.61, 0.42)").unwrap();
     assert!(fog(&s).0, "the colour arms it");
 
-    // `ClearFog` touches bit 0 and nothing else: the colour, the near and the far all survive, so
-    // a later SetFogColor re-arms the same ramp.
+    // `ClearFog` keeps the colour, near and far, so a later `SetFogColor` re-arms the same ramp.
     s.run("MFog:ClearFog()").unwrap();
     assert_eq!(fog(&s), (false, 0.0, 153.0));
     let (r, g, b, _): (f64, f64, f64, f64) = s.eval("return MFog:GetFogColor()").unwrap();
@@ -604,8 +507,7 @@ fn the_fog_block_arms_on_colour_and_clears_only_its_bit() {
         "the colour survives a clear: {r}, {g}, {b}"
     );
 
-    // The Lua setters store RAW — no clamp, no ordering check. Only the XML attribute path
-    // clamps at `>= 0`.
+    // The Lua setters store raw, with no clamp or ordering check; only the XML path clamps at 0.
     s.run("MFog:SetFogNear(-40) MFog:SetFogFar(-1)").unwrap();
     assert_eq!(fog(&s), (false, -40.0, -1.0));
 }
diff --git a/crates/benilla-ui/src/script/tests/movable.rs b/crates/benilla-ui/src/script/tests/movable.rs
index b8b2deb4..cfaf53e1 100644
--- a/crates/benilla-ui/src/script/tests/movable.rs
+++ b/crates/benilla-ui/src/script/tests/movable.rs
@@ -1,9 +1,6 @@
-//! The movable-frame family — `SetMovable`/`StartMoving`/`StopMovingOrSizing`/`SetUserPlaced`/
-//! `SetResizable` (the mechanism and its addresses are in `script::object::movable`).
-//!
-//! Every test here drives the PRODUCTION path: the Lua bindings, and the real
-//! `mouse_button`/`mouse_move` entry points, so the drag gesture that fires `OnDragStart` is the
-//! same one an addon gets.
+//! The movable-frame family (`SetMovable`, `StartMoving`, `StopMovingOrSizing`, `SetUserPlaced`,
+//! `SetResizable`), title regions and the user-placed layout cache, driven through the Lua
+//! bindings and the real mouse entry points.
 
 use super::common::script;
 use crate::script::UiScript;
@@ -38,16 +35,13 @@ fn corner(s: &mut UiScript) -> (f32, f32) {
     (left, bottom)
 }
 
-/// The whole point of the family: the four-line addon idiom actually moves the frame, and the
-/// position it was dragged to SURVIVES the stop — nothing snaps it back to the `SetPoint` it was
-/// born with, and nothing keeps moving it after the button is up.
 #[test]
 fn the_canonical_addon_idiom_moves_a_frame_and_the_position_survives_the_stop() {
     let mut s = movable_panel();
     assert_eq!(corner(&mut s), (100.0, 100.0), "born where SetPoint put it");
 
     s.mouse_button(150.0, 140.0, "LeftButton", true); // press inside the panel
-    s.mouse_move(152.0, 140.0); // 2 px — under the drag threshold, nothing yet
+    s.mouse_move(152.0, 140.0); // 2 px, under the drag threshold
     assert_eq!(s.eval::<i64>("return starts").unwrap(), 0);
     assert_eq!(corner(&mut s), (100.0, 100.0));
 
@@ -64,27 +58,23 @@ fn the_canonical_addon_idiom_moves_a_frame_and_the_position_survives_the_stop()
     assert_eq!(s.eval::<i64>("return stops").unwrap(), 1);
     assert_eq!(corner(&mut s), (200.0, 150.0), "the position survives");
 
-    // And the move is really over: further cursor motion moves nothing.
     s.mouse_move(500.0, 400.0);
     assert_eq!(corner(&mut s), (200.0, 150.0), "no longer following");
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 
-    // GetPoint reads back the frame's OWN point with the dragged offsets — the reference writes
-    // the anchors in place rather than rewriting them, so what an addon saves is what it set.
+    // The reference moves the anchors in place, so GetPoint reads the frame's own point, dragged.
     let (point, x, y) = s
         .eval::<(String, f64, f64)>("local p, _, _, x, y = MovePanel:GetPoint() return p, x, y")
         .unwrap();
     assert_eq!((point.as_str(), x, y), ("BOTTOMLEFT", 200.0, 150.0));
 }
 
-/// A moving frame follows SUCCESSIVE moves, each one applying only that step's delta (the pump
-/// re-centers its sample — a bug that integrated from the grab instead would double the second
-/// step, and one that forgot to re-center would freeze after the first).
+/// Each move applies only its own delta: the pump re-centers its sample after every step.
 #[test]
 fn a_moving_frame_follows_successive_mouse_moves() {
     let mut s = movable_panel();
     s.mouse_button(150.0, 140.0, "LeftButton", true);
-    s.mouse_move(160.0, 140.0); // the move that STARTS the drag
+    s.mouse_move(160.0, 140.0); // the move that starts the drag
     assert_eq!(
         corner(&mut s),
         (100.0, 100.0),
@@ -102,9 +92,7 @@ fn a_moving_frame_follows_successive_mouse_moves() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// `StartMoving` on a frame that is not `SetMovable(true)` RAISES and moves nothing — the
-/// reference's own guard (`0x776700`'s movable-bit test). The error is a real Lua error, so an
-/// addon's `pcall` sees it.
+/// The reference's `StartMoving` raises on a frame that is not movable (`0x776700`).
 #[test]
 fn start_moving_on_a_frame_that_is_not_movable_raises_and_moves_nothing() {
     let mut s = script();
@@ -128,13 +116,11 @@ fn start_moving_on_a_frame_that_is_not_movable_raises_and_moves_nothing() {
         "the refusal names why"
     );
 
-    // Nothing is in flight, so the cursor moves nothing.
     s.mouse_move(400.0, 400.0);
     s.resolve();
     let left = s.eval::<f64>("return FixedPanel:GetLeft()").unwrap();
     assert_eq!(left, 100.0, "a refused StartMoving started no move");
 
-    // The same frame, once made movable, moves — proving the guard was the only thing stopping it.
     s.run("FixedPanel:SetMovable(true) FixedPanel:StartMoving()")
         .unwrap();
     s.mouse_move(450.0, 400.0);
@@ -142,10 +128,8 @@ fn start_moving_on_a_frame_that_is_not_movable_raises_and_moves_nothing() {
     assert_eq!(s.eval::<f64>("return FixedPanel:GetLeft()").unwrap(), 150.0);
 }
 
-/// `StopMovingOrSizing` with nothing moving is harmless — the double call, the OnDragStop that
-/// never had a StartMoving, the addon that also wires it to OnMouseUp. And it only stops the
-/// frame that is actually in the drag slot (the reference's `[root+0xcfc] == self` compare), so
-/// one frame's stop cannot end another's move.
+/// `StopMovingOrSizing` is harmless with nothing moving, and stops only the frame in the drag slot
+/// (the reference compares `[root+0xcfc]` with self).
 #[test]
 fn stop_moving_or_sizing_is_harmless_with_nothing_moving_and_stops_only_its_own_frame() {
     let mut s = movable_panel();
@@ -163,7 +147,6 @@ fn stop_moving_or_sizing_is_harmless_with_nothing_moving_and_stops_only_its_own_
     assert!(s.errors().is_empty(), "{:?}", s.errors());
     assert_eq!(corner(&mut s), (100.0, 100.0), "nothing moved");
 
-    // Now start a real move and have the OTHER frame try to stop it.
     s.run("MovePanel:StartMoving()").unwrap();
     s.mouse_move(50.0, 50.0); // cursor_pos was (0,0) ⇒ +50, +50
     assert_eq!(corner(&mut s), (150.0, 150.0));
@@ -180,10 +163,7 @@ fn stop_moving_or_sizing_is_harmless_with_nothing_moving_and_stops_only_its_own_
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// A frame stretched between two anchors — no explicit size at all — moves RIGIDLY and keeps its
-/// derived size. This is the case a single-point rewrite gets wrong (it would drop the opposing
-/// anchor and leave the frame under-constrained, i.e. gone), and the case that decides between
-/// translating one anchor and translating the set.
+/// A move translates every anchor, so a frame sized by two anchors keeps its size.
 #[test]
 fn a_frame_stretched_between_two_anchors_moves_rigidly() {
     let mut s = script();
@@ -219,8 +199,8 @@ fn a_frame_stretched_between_two_anchors_moves_rigidly() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// A SCALED frame moves with the cursor 1:1 on screen — the anchor offsets it writes are in local
-/// units, so they carry the inverse of the frame's own scale (`0x768710`'s `dx/scale`).
+/// A scaled frame tracks the cursor 1:1 on screen: the offsets it writes are in local units
+/// (`0x768710` divides by the frame's scale).
 #[test]
 fn a_scaled_frame_tracks_the_cursor_one_to_one_on_screen() {
     let mut s = script();
@@ -244,7 +224,7 @@ fn a_scaled_frame_tracks_the_cursor_one_to_one_on_screen() {
     );
     s.mouse_move(40.0, 0.0);
     s.resolve();
-    // GetLeft reports LOCAL units: 40 screen px is 20 local, on top of the local 100.
+    // GetLeft reports local units: 40 screen px is 20 local, on top of the local 100.
     assert_eq!(
         s.eval::<f64>("return ScaledPanel:GetLeft()").unwrap(),
         120.0
@@ -256,9 +236,8 @@ fn a_scaled_frame_tracks_the_cursor_one_to_one_on_screen() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The flags: default off, round-trip through their setters, and `SetUserPlaced`'s guard — the
-/// reference refuses it unless the frame is movable OR resizable (`776adb: test ah,0x3`).
-/// `StartMoving` sets the bit itself, which is the reference's drag-start doing it, not us.
+/// The reference refuses `SetUserPlaced` unless the frame is movable or resizable (`0x776adb`),
+/// and its drag start sets the bit itself (`0x7652b0`).
 #[test]
 fn the_three_flags_default_off_round_trip_and_user_placed_is_guarded() {
     let mut s = script();
@@ -282,7 +261,6 @@ fn the_three_flags_default_off_round_trip_and_user_placed_is_guarded() {
         "no frame is born flagged"
     );
 
-    // SetUserPlaced before either flag: refused, exactly like the reference.
     assert!(
         !s.eval::<bool>("return (pcall(function() FlagPanel:SetUserPlaced(true) end))")
             .unwrap(),
@@ -305,7 +283,6 @@ fn the_three_flags_default_off_round_trip_and_user_placed_is_guarded() {
         "truthy 1 sets, false clears"
     );
 
-    // The drag start sets userPlaced itself (`0x7652b0`).
     s.resolve();
     s.run("FlagPanel:StartMoving()").unwrap();
     assert!(
@@ -316,9 +293,6 @@ fn the_three_flags_default_off_round_trip_and_user_placed_is_guarded() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// `movable="true"` / `resizable="true"` in XML land on the real methods — they were a warn-once
-/// gap in the loader until this family existed, which left every reference window authored
-/// movable undraggable while `SetMovable` worked fine from Lua.
 #[test]
 fn the_xml_movable_and_resizable_attributes_reach_the_methods() {
     let s = script();
@@ -349,17 +323,9 @@ fn the_xml_movable_and_resizable_attributes_reach_the_methods() {
     );
 }
 
-/// **`StartSizing(grip)` moves the gripped edges and plants the opposite ones.**
-///
-/// `0x776830`; the reference's own caller is
-/// `FloatingChatFrame.lua:600`. Four corpus addons reach it through ONE line —
-/// `FuBar_Panel.lua:980`, replicated into FuBar_CorkFu, FuBar_FuXPFu, FuBar_SpellStatusFu and oRA2
-/// (1207: one library, not four votes).
-///
-/// What is not settled anywhere is which edges a grip moves — the verb only orchestrates, with no
-/// inline math. Taken here as the plain meaning of an anchor point, which is how the reference's
-/// caller uses it. This test is where that reading is pinned, so a finding that contradicts it
-/// fails here first.
+/// `StartSizing(grip)` (`0x776830`, called from `FloatingChatFrame.lua:600`) moves the gripped
+/// edges and plants the opposite ones. Which edges a grip moves is untraced in the reference, whose
+/// verb has no inline math; this takes the anchor point's plain meaning, as that caller does.
 #[test]
 fn start_sizing_moves_the_gripped_edge_and_plants_the_other() {
     let mut s = crate::script::UiScript::new().unwrap();
@@ -375,7 +341,7 @@ fn start_sizing_moves_the_gripped_edge_and_plants_the_other() {
     .unwrap();
     s.resolve();
 
-    // Grip the RIGHT edge and drag 40 right: width grows, the left edge stays planted.
+    // Grip the right edge and drag 40 right: the width grows, the left edge stays planted.
     s.mouse_move(300.0, 100.0);
     s.run("Sizer:StartSizing(\"RIGHT\")").unwrap();
     s.mouse_move(340.0, 100.0);
@@ -384,8 +350,7 @@ fn start_sizing_moves_the_gripped_edge_and_plants_the_other() {
     assert_eq!(s.eval::<f32>("return Sizer:GetLeft()").unwrap(), 100.0);
     s.run("Sizer:StopMovingOrSizing()").unwrap();
 
-    // Grip the LEFT edge and drag 30 right: width SHRINKS and the left edge follows the cursor,
-    // so the right edge is the one that stays put.
+    // Grip the left edge and drag 30 right: the width shrinks and the right edge stays put.
     let right_before = s.eval::<f32>("return Sizer:GetRight()").unwrap();
     s.run("Sizer:StartSizing(\"LEFT\")").unwrap();
     s.mouse_move(370.0, 100.0);
@@ -398,13 +363,11 @@ fn start_sizing_moves_the_gripped_edge_and_plants_the_other() {
         "the ungripped edge must not move"
     );
 
-    // StopMovingOrSizing ends it: further motion changes nothing.
     s.run("Sizer:StopMovingOrSizing()").unwrap();
     s.mouse_move(500.0, 100.0);
     s.resolve();
     assert_eq!(s.eval::<f32>("return Sizer:GetWidth()").unwrap(), 210.0);
 
-    // A frame that is not resizable refuses, like the movable family's siblings.
     s.run("g = CreateFrame(\"Frame\", \"NotSizer\", UIParent)")
         .unwrap();
     assert!(
@@ -413,9 +376,7 @@ fn start_sizing_moves_the_gripped_edge_and_plants_the_other() {
     );
 }
 
-/// **`CreateTitleRegion` / `GetTitleRegion` — the object half** (`0x773910` / `0x773820`).
-///
-/// Four details, each one a coin-flip a reimplementation loses, and each one asserted.
+/// `CreateTitleRegion` (`0x773910`) and `GetTitleRegion` (`0x773820`): the object half.
 #[test]
 fn a_title_region_is_a_plain_region_and_creating_it_twice_is_destructive() {
     let mut s = script();
@@ -429,15 +390,14 @@ fn a_title_region_is_a_plain_region_and_creating_it_twice_is_destructive() {
     )
     .unwrap();
 
-    // GetTitleRegion answers ONE value and it is nil — not zero values, which is the asymmetry
-    // against `GetBackdrop 0x777370`.
+    // With none, it returns one nil, where `GetBackdrop` (`0x777370`) returns no value at all.
     assert_eq!(s.arity("TFrame:GetTitleRegion()").unwrap(), 1);
     assert!(s
         .eval::<Option<bool>>("return TFrame:GetTitleRegion() ~= nil and true or nil")
         .unwrap()
         .is_none());
 
-    // It is a plain REGION — not a Texture wearing a hat.
+    // A plain Region, not a Texture.
     s.run("TR = TFrame:CreateTitleRegion()").unwrap();
     assert_eq!(
         s.eval::<String>("return TR:GetObjectType()").unwrap(),
@@ -455,14 +415,12 @@ fn a_title_region_is_a_plain_region_and_creating_it_twice_is_destructive() {
         .eval::<bool>("return TFrame:GetTitleRegion() == TR")
         .unwrap());
 
-    // **It takes NO argument**: `CreateTitleRegion(frame)` is the no-arg call, which is exactly
-    // what `CustomNameplates/options.lua:73` writes.
+    // It takes no argument: `CreateTitleRegion(frame)` is the no-argument call.
     assert!(s
         .eval::<bool>("return TFrame:CreateTitleRegion(TFrame) == TR")
         .unwrap());
 
-    // **Idempotent, and DESTRUCTIVELY so.** A second call returns the same object after clearing
-    // its anchors — so it silently wipes the points a caller already set.
+    // A second call returns the same region with its anchors cleared.
     s.run("TR:SetAllPoints(TFrame)").unwrap();
     s.resolve();
     assert_eq!(s.eval::<i64>("return TR:GetNumPoints()").unwrap(), 2);
@@ -475,10 +433,8 @@ fn a_title_region_is_a_plain_region_and_creating_it_twice_is_destructive() {
         "the second call ran ClearAllPoints on the region it returned"
     );
 
-    // **It answers the 19 Region methods and NOTHING else** — 1250 §5's named divergence, closed.
-    // (`0x81c554`/`0x81c528`): no Show/Hide, no scripts, no textures. Ours used to share one
-    // metatable with Texture and FontString, so a title region answered `SetTexture` where the
-    // reference raises.
+    // It answers the 19 Region methods and nothing else (`0x81c554`, `0x81c528`): no Show/Hide,
+    // no scripts, no textures.
     for name in crate::script::REGION_MAP_METHODS {
         assert_eq!(
             s.eval::<String>(&format!("return type(TR.{name})"))
@@ -521,8 +477,7 @@ fn a_title_region_is_a_plain_region_and_creating_it_twice_is_destructive() {
         "a title region emits no quad of its own (the frame's own quad is not one): {region_quads:?}"
     );
 
-    // The full region kinds are untouched by the split — asserted LAST, because creating a real
-    // texture would otherwise put a legitimate quad into the check above.
+    // Checked last: a real texture would add a legitimate quad to the check above.
     s.run("TTex = TFrame:CreateTexture(nil, 'ARTWORK')")
         .unwrap();
     assert_eq!(
@@ -532,10 +487,8 @@ fn a_title_region_is_a_plain_region_and_creating_it_twice_is_destructive() {
     );
 }
 
-/// **The drag half — and the three things that make it not just `StartMoving`.**
-///
-/// A mouse-down inside the title region starts a move that (1) SWALLOWS `OnMouseDown`, (2) ends on
-/// release where a scripted move persists, and (3) does not consult `SetMovable`.
+/// A press in the title region starts a move that, unlike `StartMoving`, swallows `OnMouseDown`,
+/// ends on release and skips the movable check.
 #[test]
 fn a_title_region_drag_swallows_the_press_and_ends_on_release() {
     let mut s = script();
@@ -559,7 +512,6 @@ fn a_title_region_drag_swallows_the_press_and_ends_on_release() {
     };
     assert_eq!(corner(&mut s), 100.0);
 
-    // Press inside the title region: the move starts and OnMouseDown never runs.
     s.mouse_button(150.0, 150.0, "LeftButton", true);
     assert_eq!(
         s.eval::<i64>("return downs").unwrap(),
@@ -569,7 +521,7 @@ fn a_title_region_drag_swallows_the_press_and_ends_on_release() {
     s.mouse_move(250.0, 150.0);
     assert_eq!(corner(&mut s), 200.0, "the frame followed the cursor");
 
-    // **Release ends it** — mode 2 auto-cancels. Moving the cursor afterwards must not drag it.
+    // Release ends it: the title-region move (mode 2) cancels itself.
     s.mouse_button(250.0, 150.0, "LeftButton", false);
     s.mouse_move(400.0, 150.0);
     assert_eq!(
@@ -578,16 +530,12 @@ fn a_title_region_drag_swallows_the_press_and_ends_on_release() {
         "the move ended at the release; a scripted StartMoving would still be running"
     );
 
-    // **No `SetMovable` gate on this path** — TP was never made movable, and it dragged. The
-    // movable bit is simply not read on 0x7662c0->0x765320->0x7652b0->0x768430; a title region on a
-    // non-movable frame is the case that tells it apart from `StartMoving`, which raises "Frame %s
-    // is not movable".
+    // The movable bit is not read on this path (`0x7662c0`, `0x765320`, `0x7652b0`, `0x768430`).
     assert!(!s.eval::<bool>("return TP:IsMovable()").unwrap());
 }
 
-/// A region's rect getters answer in its OWNER's units — screen ÷ the owner's effective scale —
-/// exactly as the frame getters do (decision 1985): a texture inside a frame scaled to 0.5 that
-/// covers the frame answers the frame's own width, not half of it.
+/// A region's rect getters answer in its owner's units, screen ÷ the owner's effective scale, as
+/// the frame getters do.
 #[test]
 fn region_getters_answer_in_the_owners_units_under_scale() {
     let mut s = UiScript::new().unwrap();
@@ -616,14 +564,9 @@ fn region_getters_answer_in_the_owners_units_under_scale() {
     assert!((cx - (fl + fr) * 0.5).abs() < 1e-3);
 }
 
-/// **The layout cache's filter is the flags AND the bit, at both ends** (decision 2193).
-///
-/// `SetUserPlaced` is already guarded by `movable|resizable` at its own setter (`0x776adb`), but
-/// the drag entry (`0x7652b0` @`0x7652e5`) and the cache's own apply stamp the bit without going
-/// through it — so a frame can carry the stamp while carrying neither flag, and the reference's
-/// writer tests for both: `0x490e8e test ah,0x10` (userPlaced) AND `0x490e97 test ah,0x3`
-/// (`movable|resizable`). Clearing the flags is how a window stops being persisted, which is what
-/// an addon's `:OnDisable` does on the way out.
+/// The layout cache writes a frame only when it is user-placed (`0x490e8e`) and movable or
+/// resizable (`0x490e97`): the drag start (`0x7652b0` at `0x7652e5`) and the cache's own apply
+/// set the bit past `SetUserPlaced`'s guard (`0x776adb`), so clearing the flags stops the save.
 #[test]
 fn the_write_filter_is_user_placed_and_movable_or_resizable() {
     let mut s = script();
@@ -659,11 +602,9 @@ fn the_write_filter_is_user_placed_and_movable_or_resizable() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **The apply is gated per ARM** (decision 2193): position behind `movable` (`0x490600 test
-/// ah,0x1`), size behind `resizable` (`0x490689 test ah,0x2`), and each arm stamps the userPlaced
-/// bit itself (`0x49067e` / `0x490706`) only if it ran. A stock frame carrying neither flag is
-/// left entirely alone, however old its row — which is what stops one addon's stamp from seating
-/// a window forever.
+/// The cache's apply seats position only when movable (`0x490600`) and size only when resizable
+/// (`0x490689`), and each arm that runs sets userPlaced (`0x49067e`, `0x490706`); a frame with
+/// neither flag is left alone.
 #[test]
 fn the_apply_seats_position_behind_movable_and_size_behind_resizable() {
     use crate::script::{FrameLayout, LayoutPoint};
diff --git a/crates/benilla-ui/src/script/tests/name_targets.rs b/crates/benilla-ui/src/script/tests/name_targets.rs
index 4804ebe2..13156ad8 100644
--- a/crates/benilla-ui/src/script/tests/name_targets.rs
+++ b/crates/benilla-ui/src/script/tests/name_targets.rs
@@ -1,24 +1,11 @@
-//! **A widget NAME argument is a Lua GLOBAL, not a frame name** — the one rule behind every
-//! binding that takes "a frame or its name": `SetPoint`'s `relativeTo`, `SetAllPoints`,
-//! `SetParent`, `SetScrollChild`.
-//!
-//! The client has a single widget namespace and it is `_G`. The wrapper binder `0x701bd0`
-//! publishes `_G[name] = T` for a named widget (non-overwriting), and the by-name resolvers read
-//! that table back and nothing else — `0x76c760` (FrameScript globals **rawget** + Lua-type-5 +
-//! the `vtbl+0x10` tag check) and its geometry-vtable `+0x28` twin `0x76c700`
-//! (`_G[name]` → `t[0]` userdata → `IsA`).
-//!
-//! A frame's published name is therefore only the commonest way such a global comes to exist —
-//! **an alias is just as good a name**, and 1.12 addons lean on that. Bartender2 2.0 aliases every
-//! stock button (`Bar8Button1 = CharacterBag3Slot`, file scope, `Alias.lua`) and then lays each bar
-//! out by anchoring button *i* to the string `"Bar8Button"..(i-1)`. Resolving those against a
-//! private frame-name registry finds nothing, every anchor falls back to the parent, and all five
-//! bag buttons land in one spot on the bar's far corner. Decision 2105.
+//! A widget name argument (`SetPoint`'s `relativeTo`, `SetAllPoints`, `SetParent`,
+//! `SetScrollChild`) is a Lua global, so an alias resolves too: the binder `0x701bd0` publishes
+//! `_G[name]` without overwriting, and the resolvers `0x76c760` (rawget, type 5, `vtbl+0x10` tag)
+//! and `0x76c700` (`_G[name]`, `t[0]`, `IsA`) read `_G` and nothing else.
 
 use super::common::script;
 
-/// Bartender2's exact shape: stock buttons, addon alias globals that no frame is named, a row laid
-/// out through those aliases alone. The row must come out at the addon's pitch.
+/// Bartender2's shape: a row laid out through alias globals that are no frame's own name.
 #[test]
 fn setpoint_relative_to_resolves_an_alias_global() {
     let mut s = script();
@@ -73,8 +60,7 @@ fn setpoint_relative_to_resolves_an_alias_global() {
     );
 }
 
-/// The namespace is ONE: a **region** published under a global resolves as a `relativeTo` exactly
-/// as a frame does (the real XML anchors frames to FontStrings by name — gossip option rows).
+/// One namespace: stock XML anchors frames to FontStrings by name (the gossip option rows).
 #[test]
 fn setpoint_relative_to_resolves_a_region_alias_global() {
     let mut s = script();
@@ -106,9 +92,7 @@ fn setpoint_relative_to_resolves_a_region_alias_global() {
     assert_eq!(bottom, 20.0);
 }
 
-/// A global that is not a widget resolves to nothing — the reference's type-5 + tag check — and
-/// the binding then takes its unresolved-name leg, which **raises** (`0x87ccd4`; decision 2176).
-/// The value is never used, and no anchor is left behind.
+/// The type-5 and tag check reject it, and the unresolved-name leg raises (`0x87ccd4`).
 #[test]
 fn setpoint_relative_to_ignores_a_non_widget_global() {
     let mut s = script();
@@ -136,11 +120,9 @@ fn setpoint_relative_to_ignores_a_non_widget_global() {
     assert_eq!(n, 0, "the raise leaves no anchor behind");
 }
 
-/// **`$parent` is expanded at RUNTIME, on the anchor path only.** `0x76c5b0` has exactly two call
-/// sites — `SetName 0x76c691` and `0x76c71c` *inside* the layout resolver `0x76c700` — so
-/// `SetPoint`/`SetAllPoints` run the token against the anchoring frame's first **named** ancestor
-/// (skipping anonymous links, `"Top"` when there is none), while `SetParent` and `SetScrollChild`,
-/// which call `0x76c760` directly, do not.
+/// The expander `0x76c5b0` is called only from `SetName` (`0x76c691`) and the layout resolver
+/// (`0x76c71c` in `0x76c700`), so anchors expand `$parent` against the first named ancestor
+/// (`"Top"` if none); `SetParent` and `SetScrollChild` call `0x76c760` directly and do not.
 #[test]
 fn setpoint_relative_to_expands_parent_against_the_first_named_ancestor() {
     let mut s = script();
@@ -174,8 +156,6 @@ fn setpoint_relative_to_expands_parent_against_the_first_named_ancestor() {
     assert!(s.take_warnings().is_empty());
 }
 
-/// The other half of the same fact: the reparent bindings never see the token, so a
-/// `$parent`-prefixed name reaches them literally and fails to resolve.
 #[test]
 fn setparent_does_not_expand_parent() {
     let s = script();
@@ -196,8 +176,7 @@ fn setparent_does_not_expand_parent() {
     );
 }
 
-/// `SetParent` takes the same namespace (`0x7a1550`'s NAME-string path → `0x76c760`) — Bartender2
-/// re-parents every stock button by alias before it anchors it.
+/// `SetParent`'s name path (`0x7a1550`) resolves through `0x76c760` too.
 #[test]
 fn setparent_resolves_an_alias_global() {
     let s = script();
@@ -217,7 +196,6 @@ fn setparent_resolves_an_alias_global() {
     );
 }
 
-/// `SetAllPoints` shares the resolver, so it shares the rule.
 #[test]
 fn setallpoints_resolves_an_alias_global() {
     let mut s = script();
@@ -242,15 +220,8 @@ fn setallpoints_resolves_an_alias_global() {
     assert_eq!((l, b, w, h), (30.0, 40.0, 120.0, 60.0));
 }
 
-/// **A leading `$parent` in a Lua constructor's NAME argument is expanded**, exactly as in XML —
-/// `CreateFrame 0x7060b0`, `CreateTexture 0x773a20` and `CreateFontString 0x773c30` all build a
-/// synthetic node carrying `name=` and read it back through `CScriptRegion::SetName 0x76c650`,
-/// which is one of the expander `0x76c5b0`'s two call sites.
-///
-/// Found by decision 2176's raise, which is the point of a raise: the unexpanded name had been
-/// there all along, degrading quietly into a parent-anchored fallback. `FonzAppraiser` names
-/// roughly thirty widgets this way and `pfQuest/browser.lua:723` builds its search icon as
-/// `input:CreateTexture("$parentSearchIcon", "OVERLAY")`.
+/// `CreateFrame 0x7060b0`, `CreateTexture 0x773a20` and `CreateFontString 0x773c30` read their
+/// `name=` back through `CScriptRegion::SetName 0x76c650`, which calls the expander `0x76c5b0`.
 #[test]
 fn a_constructor_name_expands_parent() {
     let s = script();
@@ -268,7 +239,7 @@ fn a_constructor_name_expands_parent() {
         "RootKid",
         "the base is the first NAMED ancestor of the frame's parent, not the parent itself"
     );
-    // …and the expanded name is what reached `_G`, which is the only widget namespace (2105).
+    // The expanded name is what reached `_G`.
     assert_eq!(
         s.eval::<String>("return RootKid:GetName()").unwrap(),
         "RootKid"
@@ -278,12 +249,12 @@ fn a_constructor_name_expands_parent() {
             .unwrap(),
         "the raw token names nothing"
     );
-    // A region's `$parent` is its OWNER frame, so the walk starts one link lower.
+    // A region's `$parent` is its owner frame.
     assert_eq!(
         s.eval::<String>("return RootKidIcon:GetName()").unwrap(),
         "RootKidIcon"
     );
-    // The payoff: an anchor by the built name resolves instead of raising.
+    // An anchor by the built name resolves.
     s.run(r#"Icon:SetPoint("TOPLEFT", "RootKid", "TOPLEFT", 0, 0)"#)
         .unwrap();
 }
diff --git a/crates/benilla-ui/src/script/tests/nameplate.rs b/crates/benilla-ui/src/script/tests/nameplate.rs
index 21673b58..af972473 100644
--- a/crates/benilla-ui/src/script/tests/nameplate.rs
+++ b/crates/benilla-ui/src/script/tests/nameplate.rs
@@ -1,17 +1,10 @@
-//! The nameplate ABI, as the four vanilla addons actually read it (decision 2148).
-//!
-//! These are not "does the pool work" tests. Each is a transcription of a real corpus idiom — the
-//! same walk, the same destructuring, the same identification test — so a change that would break
-//! a shipped addon fails **here** rather than on the director's screen.
-//!
-//! Sources, all `## Interface: 11200`: `pfUI/modules/nameplates.lua` (+ `compat/vanilla.lua`),
-//! `ShaguTweaks/libs/libnameplate.lua`, `CustomNameplates/CustomNameplates.lua`,
-//! `_Nameplates/_Nameplates.lua`. The byte side is read off the reference binary.
+//! The nameplate ABI as four vanilla addons read it, one idiom per test:
+//! `pfUI/modules/nameplates.lua`, `ShaguTweaks/libs/libnameplate.lua`,
+//! `CustomNameplates/CustomNameplates.lua` and `_Nameplates/_Nameplates.lua`.
 
 use crate::script::{PlateGeometry, PlateState, UiScript};
 
-/// A VM with a `WorldFrame` to hang plates off — the only thing [`UiScript::sync_nameplates`]
-/// requires of a session.
+/// A VM with a `WorldFrame` to hang plates off, all [`UiScript::sync_nameplates`] requires.
 fn vm() -> UiScript {
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
@@ -21,8 +14,7 @@ fn vm() -> UiScript {
     s
 }
 
-/// The plate size at the capture window (`vplates` scenario: one gx unit = 1280 px, so the
-/// 0.1 × 0.025 plate is 128 × 32 px, and at seam scale 1.0 that is 128 × 32 units).
+/// A 1280 px window, where one gx unit is 1280 px, so the 0.1 × 0.025 plate is 128 × 32.
 fn geometry() -> PlateGeometry {
     PlateGeometry {
         width: 128.0,
@@ -43,8 +35,7 @@ fn geometry() -> PlateGeometry {
 
 fn plate(name: &str, health: f32, max: f32) -> PlateState {
     PlateState {
-        // The unit's GUID stands in as a hash of its name: what matters to these tests is that the
-        // same unit keeps the same key across frames and two units never share one.
+        // A hash of the name stands in for the GUID: stable per unit, distinct between units.
         key: name.bytes().map(u64::from).sum(),
         top_centre: (500.0, 400.0),
         health,
@@ -67,11 +58,8 @@ fn drive(s: &mut UiScript, states: &[PlateState]) {
     s.resolve();
 }
 
-/// pfUI + ShaguTweaks share one lineage: `GetNumChildren` grew, so walk the tail.
-///
-/// `initialized` is never reset in either addon, so a client whose child list SHRANK or REORDERED
-/// would make them miss every plate created after the old high-water mark — permanently, and with
-/// no error. This is the test that a retired plate keeps its slot.
+/// pfUI and ShaguTweaks walk only the children past a count they never reset, so the list must not
+/// shrink or reorder: a retired plate keeps its slot.
 #[test]
 fn the_worldframe_child_list_only_grows_and_keeps_its_order() {
     let mut s = vm();
@@ -89,7 +77,7 @@ fn the_worldframe_child_list_only_grows_and_keeps_its_order() {
         2
     );
 
-    // One unit leaves: the plate is HIDDEN, and the child list does not shrink.
+    // One unit leaves: its plate hides, and the list keeps its length.
     drive(&mut s, &[plate("Wolf", 30.0, 40.0)]);
     assert_eq!(
         s.eval::<i64>("return WorldFrame:GetNumChildren()").unwrap(),
@@ -101,7 +89,7 @@ fn the_worldframe_child_list_only_grows_and_keeps_its_order() {
         )
         .unwrap());
 
-    // A third unit arrives: it takes the pooled plate back — the count goes to 2, not 3.
+    // A new unit takes the pooled plate back: the count stays 2.
     drive(
         &mut s,
         &[plate("Wolf", 30.0, 40.0), plate("Boar", 5.0, 50.0)],
@@ -113,12 +101,8 @@ fn the_worldframe_child_list_only_grows_and_keeps_its_order() {
     assert_eq!(s.nameplate_pool_len(), 2);
 }
 
-/// pfUI's `IsNamePlate` (`nameplates.lua:70`) and ShaguTweaks' (`libnameplate.lua:12`), verbatim in
-/// shape: the object type is `"Button"`, and region #1 is a `Texture` whose `GetTexture()` is
-/// exactly `Interface\Tooltips\Nameplate-Border`.
-///
-/// `CustomNameplates` runs the texture half against **every** WorldFrame child
-/// (`CustomNameplates.lua:93`), so `GetRegions()` must also be safe to call on a frame with none.
+/// pfUI's `IsNamePlate` (`nameplates.lua:70`) and ShaguTweaks' (`libnameplate.lua:12`): a `Button`
+/// whose first region is a `Texture` reading `Interface\Tooltips\Nameplate-Border`.
 #[test]
 fn a_plate_identifies_by_button_plus_the_border_texture() {
     let mut s = vm();
@@ -137,12 +121,8 @@ fn a_plate_identifies_by_button_plus_the_border_texture() {
         .unwrap());
 }
 
-/// The two tuples, positionally — the ABI decision 2148 §3 records.
-///
-/// `CustomNameplates.lua:212` binds `Border, Glow, Name, Level, Boss, RaidTargetIcon`; pfUI and
-/// ShaguTweaks bind the same six by the `NAMEPLATE_OBJECTORDER` table. A **seventh** region is a
-/// bug (pfUI blanks any extra with `SetTexture("")`), and a **second** child is a bug too (pfUI
-/// destructures `healthbar, castbar` and would blank ours as a TBC cast bar).
+/// Six regions in `CustomNameplates.lua:212`'s order (`Border, Glow, Name, Level, Boss,
+/// RaidTargetIcon`) and one child; pfUI blanks a seventh region, and a second child as a cast bar.
 #[test]
 fn the_region_and_child_tuples_are_six_and_one() {
     let mut s = vm();
@@ -172,8 +152,8 @@ fn the_region_and_child_tuples_are_six_and_one() {
         "#
         )
         .unwrap());
-    // ShaguTweaks `libnameplate.lua:39`: `plate.healthbar = plate:GetChildren()` — one child, and
-    // it is the StatusBar. Its own single region is the fill `GetStatusBarTexture()` hands back.
+    // `libnameplate.lua:39` takes the one child as the health bar: a StatusBar whose only region
+    // is its fill.
     assert!(s
         .eval::<bool>(
             r#"
@@ -188,10 +168,8 @@ fn the_region_and_child_tuples_are_six_and_one() {
         .unwrap());
 }
 
-/// `_Nameplates.Nameplate.Initialize` (`_Nameplates.lua:163`) is the strictest consumer: it
-/// content-addresses the regions and **validates the two FontString anchors**, rejecting any plate
-/// whose name is not `BOTTOM`→`CENTER` and whose level is not `CENTER`→`BOTTOMRIGHT`. Those are the
-/// reference's own (ctor `0x7cb456`, bind `0x7cb7f5`).
+/// `_Nameplates.lua:163` rejects a plate unless its name is anchored `BOTTOM` to `CENTER` and its
+/// level `CENTER` to `BOTTOMRIGHT`, the reference's own anchors (`0x7cb456`, `0x7cb7f5`).
 #[test]
 fn the_two_fontstring_anchors_are_what_nameplates_validates() {
     let mut s = vm();
@@ -214,12 +192,8 @@ fn the_two_fontstring_anchors_are_what_nameplates_validates() {
         .unwrap());
 }
 
-/// The bar reports **raw** health, not a fraction — `GetValue 0x78f5d0` → `[bar+0x320]`, and
-/// `GetMinMaxValues` → `(0, maxHealth)`. pfUI (`:595`) and CustomNameplates (`:471`) both divide,
-/// so a fraction here would read as full health on every plate.
-///
-/// The internal fill *fraction* `0x783380` is a distinct value, easily confused for the Lua getter
-/// above.
+/// `GetValue` (`0x78f5d0`) is raw health, `[bar+0x320]`, not the fill fraction (`0x783380`), and
+/// `GetMinMaxValues` is `(0, maxHealth)`; pfUI (`:595`) and CustomNameplates (`:471`) divide them.
 #[test]
 fn the_healthbar_reports_raw_health_and_its_max() {
     let mut s = vm();
@@ -235,8 +209,7 @@ fn the_healthbar_reports_raw_health_and_its_max() {
         .unwrap());
 }
 
-/// The plate is anonymous. `_Nameplates.lua:164` rejects any WorldFrame child with a name, and
-/// pfUI's bubble filter does the same — a named plate is invisible to both.
+/// `_Nameplates.lua:164` and pfUI's bubble filter skip any WorldFrame child with a name.
 #[test]
 fn a_plate_is_anonymous() {
     let mut s = vm();
@@ -246,9 +219,8 @@ fn a_plate_is_anonymous() {
         .unwrap());
 }
 
-/// The pooling contract: a retired plate comes back as the **same Lua object**. Every addon keys
-/// its per-plate state off exactly that identity — pfUI's `registry[plate]` (`:342`),
-/// `_Nameplates.Frames[Nameplate]` (`:205`) — and re-runs `OnCreate` for an object it has not seen.
+/// Addons key per-plate state on the plate object: pfUI's `registry[plate]` (`:342`) and
+/// `_Nameplates.Frames[Nameplate]` (`:205`).
 #[test]
 fn a_retired_plate_returns_as_the_same_lua_object() {
     let mut s = vm();
@@ -261,14 +233,8 @@ fn a_retired_plate_returns_as_the_same_lua_object() {
         .unwrap());
 }
 
-/// **A plate belongs to its UNIT, not to this frame's sort order.**
-///
-/// The driver hands plates over in distance-sorted order — the seat priority the reference solves
-/// overlap in — and that order changes whenever two units cross. If the pool were indexed by it,
-/// widget #1 would swap units mid-session, and every addon that caches state on the frame would be
-/// reading the other unit's: pfUI's `nameplate.original.name`/`level`, its `registry[plate]`
-/// bookkeeping, `_Nameplates`' per-plate button. So the pool is keyed by the unit's GUID, and this
-/// is the test that says so.
+/// The pool is keyed by the unit's GUID, not by the driver's distance order, which changes when two
+/// units cross; addons cache per-unit state on the plate.
 #[test]
 fn a_plate_belongs_to_its_unit_across_a_sort_order_swap() {
     let mut s = vm();
@@ -288,8 +254,7 @@ fn a_plate_belongs_to_its_unit_across_a_sort_order_swap() {
     .unwrap();
     assert!(s.eval::<bool>("return WolfPlate ~= nil").unwrap());
 
-    // The two units cross: the driver now sorts Bear first. Nothing about either plate's identity
-    // may move with it.
+    // The units cross: the driver now sorts Bear first.
     drive(
         &mut s,
         &[plate("Bear", 10.0, 90.0), plate("Wolf", 30.0, 40.0)],
@@ -304,8 +269,8 @@ fn a_plate_belongs_to_its_unit_across_a_sort_order_swap() {
         .unwrap());
 }
 
-/// `plate:GetAlpha() == 1` is how pfUI (`:879`) and CustomNameplates (`:287`) detect the TARGET
-/// plate: with a target up, every other plate is dimmed. So alpha is a contract, not a look.
+/// pfUI (`:879`) and CustomNameplates (`:287`) find the target plate as the one at alpha 1; with a
+/// target up, every other plate is dimmed.
 #[test]
 fn the_target_plate_is_the_opaque_one() {
     let mut s = vm();
@@ -321,9 +286,8 @@ fn the_target_plate_is_the_opaque_one() {
         .unwrap());
 }
 
-/// pfUI hooks the bar's `OnValueChanged` (`:393`) and reads `this:GetParent()` inside the handler
-/// to find the plate. The driver moves that value from Rust, so the handler has to fire from there
-/// too — the reference's own bar is driven by a GUID-watch callback and fires it the same way.
+/// pfUI's bar `OnValueChanged` (`:393`) finds the plate by `this:GetParent()`; the reference sets
+/// the bar from a GUID-watch callback that fires the handler, as the driver's write does here.
 #[test]
 fn an_engine_health_write_fires_onvaluechanged_with_the_plate_as_parent() {
     let mut s = vm();
@@ -349,10 +313,8 @@ fn an_engine_health_write_fires_onvaluechanged_with_the_plate_as_parent() {
     assert_eq!(s.eval::<i64>("return Fired").unwrap(), 1);
 }
 
-/// **An addon takes the plate over.** pfUI blanks all six regions (`DisableObject` →
-/// `SetTexture("")`) and paints its own art; ShaguTweaks reparents the raid icon. A driver that
-/// re-stamped every property every frame would undo that at 60 Hz — so static properties are
-/// written once, at creation, and never again.
+/// The driver writes a plate's static properties once, at creation, so an addon's takeover (pfUI
+/// blanks all six regions, ShaguTweaks reparents the raid icon) survives.
 #[test]
 fn the_driver_does_not_overwrite_an_addons_takeover() {
     let mut s = vm();
@@ -366,7 +328,7 @@ fn the_driver_does_not_overwrite_an_addons_takeover() {
     "#,
     )
     .unwrap();
-    // Several frames of ordinary driving — health moving, the unit renamed, the plate re-seated.
+    // Several frames of driving: health moves and the plate re-seats.
     for hp in [29.0, 28.0, 27.0] {
         let mut state = plate("Wolf", hp, 40.0);
         state.top_centre = (500.0 + hp, 400.0);
@@ -382,18 +344,9 @@ fn the_driver_does_not_overwrite_an_addons_takeover() {
         .unwrap());
 }
 
-/// **A hovered plate wears no black box** — the defect the widget port shipped (director report,
-/// 2026-09-10: "they look totally fucked when I hover or click them"), and the two halves that
-/// keep it fixed.
-///
-/// `Nameplate-Glow.blp` is DXT1 with **no alpha channel** and 80.5% pure-black texels. The
-/// reference blends it `ADD` (`push 3` @`0x7cb36a`); blitted with straight `BLEND` it is an opaque
-/// rectangle over the entire plate — which is exactly what the ctor's default mode produced here.
-/// 0184 is the director's call that benilla paints **no rim at all**, so the region has to be ADD
-/// *and* emit nothing, while staying shown and textured for the addons that read it.
-///
-/// The border assert is not decoration: without it the test would pass on an extract that produced
-/// no quads whatsoever.
+/// The glow art has no alpha and is mostly black, so the reference blends it ADD (`0x7cb36a`); as
+/// BLEND it is an opaque box. Deviation: we paint no rim, which reads as hard edges in our
+/// pipeline, but the region stays shown, ADD and textured. The border check fails an empty extract.
 #[test]
 fn a_hovered_plate_emits_no_glow_quad() {
     use crate::script::QuadContent;
@@ -403,7 +356,6 @@ fn a_hovered_plate_emits_no_glow_quad() {
     p.lit = true;
     drive(&mut s, &[p]);
 
-    // The model tells the truth: shown, textured, and the reference's own blend mode.
     assert!(s
         .eval::<bool>(
             r#"local _, glow = WorldFrame:GetChildren():GetRegions()
@@ -431,23 +383,9 @@ fn a_hovered_plate_emits_no_glow_quad() {
     );
 }
 
-/// **The plate's name and level seat off the UI pixel grid** (decision 2172).
-///
-/// The plate is a WorldFrame overlay: the driver snaps its rect to the DEVICE pixel grid
-/// (`vplates::device_snap` — half a logical pixel at 2×) because it slides continuously over the
-/// world, and everything drawn inside it has to be rigid to that. The renderer's UI seat snap
-/// quantizes a text block's top on the coarser LOGICAL grid, so with both laws in force the name
-/// and the level pop a whole pixel every second step the border takes.
-///
-/// The painter this port replaced never snapped them — it measured into degenerate rects, which
-/// the renderer's carve-out skips — so this flag is what carries that seating law across decision
-/// 2148's move into the frame system. It rides the extract, one field per Text quad, because the
-/// renderer is the only thing that can act on it.
-///
-/// It is answered from the OWNER, which is why the third block here matters: pfUI and
-/// ShaguTweaks blank the stock regions and hang their own FontStrings on the plate, and a rule
-/// written on our six regions would have left an addon's strings jittering inside a plate whose
-/// own text had stopped.
+/// Text on a plate skips the UI grid snap: the plate's rect snaps to the finer device grid as it
+/// slides, and a text top snapped to the logical grid would jump a pixel against it. The flag is
+/// the owning frame's, so an addon's own string on the plate gets it too.
 #[test]
 fn the_plates_texts_carry_the_world_seat_and_its_textures_do_not() {
     use crate::script::QuadContent;
@@ -472,8 +410,7 @@ fn the_plates_texts_carry_the_world_seat_and_its_textures_do_not() {
         "the plate draws exactly its name and level, both seated off the UI grid"
     );
 
-    // A FontString on an ordinary frame is interface, and interface is ON the grid — the flag has
-    // to be the plate's claim, not something every string picked up.
+    // A FontString on an ordinary frame stays on the grid.
     s.run(
         r#"local f = CreateFrame("Frame", "Chrome", UIParent) f:SetAllPoints()
            local t = f:CreateFontString("ChromeText") t:SetAllPoints() t:SetText("Chrome")"#,
@@ -485,8 +422,7 @@ fn the_plates_texts_carry_the_world_seat_and_its_textures_do_not() {
         QuadContent::Text { text: Some(t), world_seat: false, .. } if t == "Chrome"
     )));
 
-    // An addon's own string on the plate — pfUI's whole vanilla branch — is drawn inside the same
-    // sliding rect, so it gets the same seat.
+    // An addon's own string on the plate, as pfUI draws its text, gets the same seat.
     s.run(
         r#"local plate = WorldFrame:GetChildren()
            local t = plate:CreateFontString() t:SetAllPoints() t:SetText("pfName")"#,
@@ -502,11 +438,7 @@ fn the_plates_texts_carry_the_world_seat_and_its_textures_do_not() {
     );
 }
 
-/// The suppression is **the reference's own glow art on an ADD region**, and nothing wider: an
-/// addon that re-textures the region gets its art painted like any other texture.
-///
-/// pfUI's vanilla branch does exactly this — it blanks the six regions and paints its own — so a
-/// blanket "plate glow regions never draw" would silently eat an addon's work.
+/// Only the stock glow art on an ADD region goes unpainted; an addon's own glow texture paints.
 #[test]
 fn an_addon_that_retextures_the_glow_gets_its_art_painted() {
     use crate::script::QuadContent;
@@ -531,10 +463,8 @@ fn an_addon_that_retextures_the_glow_gets_its_art_painted() {
         .any(|p| p.contains("pfUI")));
 }
 
-/// pfUI reads `glow:IsShown()` as the MOUSEOVER signal (`:601`, `:880`). benilla does not paint the
-/// additive rim (0184 — it read as hard edge lines on our pipeline, and the director pinned a bar
-/// brighten instead), but the region is structurally present and really shown, because the
-/// deviation is about pixels and this is about data.
+/// pfUI reads `glow:IsShown()` as the mouseover signal (`:601`, `:880`), so the glow shows on hover
+/// though it paints nothing.
 #[test]
 fn the_glow_region_is_the_mouseover_signal() {
     let mut s = vm();
@@ -554,9 +484,8 @@ fn the_glow_region_is_the_mouseover_signal() {
         .unwrap());
 }
 
-/// The level number and the skull share one seat and are mutually exclusive — `skull` is how the
-/// driver says "world boss, or ten levels up". pfUI gates on `levelicon:IsShown()` and
-/// CustomNameplates on `Boss:IsVisible()`, so both flags have to move.
+/// The level and the skull (a world boss, or ten levels up) share one seat; pfUI reads
+/// `levelicon:IsShown()` and CustomNameplates `Boss:IsVisible()`.
 #[test]
 fn the_skull_replaces_the_level_number() {
     let mut s = vm();
@@ -574,9 +503,7 @@ fn the_skull_replaces_the_level_number() {
         .unwrap());
 }
 
-/// **A unit whose level has not arrived is not a world boss.** `level: None` with no skull leaves
-/// the seat EMPTY — the old painter's behaviour, which the widget port inverted by making one
-/// `Option` carry both facts (audit, 2026-09-10).
+/// A level not yet known, with no skull, leaves the seat empty.
 #[test]
 fn a_unit_with_no_level_yet_wears_no_skull() {
     let mut s = vm();
@@ -593,15 +520,11 @@ fn a_unit_with_no_level_yet_wears_no_skull() {
         .unwrap());
 }
 
-/// **A plate the pool grows on any frame but the first is laid out too.** The lay-out used to ride
-/// a per-frame "did the window move?" flag, so a unit that walked into range later got a plate with
-/// no size and no anchors: invisible, permanently, and the number of plates on screen was capped at
-/// however many were up when V was first pressed (audit, 2026-09-10).
 #[test]
 fn a_plate_created_after_the_first_frame_is_laid_out() {
     let mut s = vm();
     drive(&mut s, &[plate("Wolf", 30.0, 40.0)]);
-    // A second unit arrives on a LATER frame, with no free slot and no geometry change.
+    // A second unit on a later frame, with no free slot and no geometry change.
     drive(
         &mut s,
         &[plate("Wolf", 30.0, 40.0), plate("Bear", 10.0, 90.0)],
@@ -610,7 +533,7 @@ fn a_plate_created_after_the_first_frame_is_laid_out() {
         .eval("local _, b = WorldFrame:GetChildren() return b:GetWidth(), b:GetHeight()")
         .unwrap();
     assert_eq!((w, h), (128.0, 32.0), "the second plate has the plate size");
-    // …and its regions are anchored to it, which is what `GetLeft` answering at all proves.
+    // Its regions are anchored to it, or `GetLeft` would not answer.
     assert!(s
         .eval::<bool>(
             r#"local _, b = WorldFrame:GetChildren()
@@ -620,10 +543,8 @@ fn a_plate_created_after_the_first_frame_is_laid_out() {
         .unwrap());
 }
 
-/// An addon's own frame parented to `WorldFrame` shares the list with the plates —
-/// `_NameplatesFrame` and `pfUICombatScreen` both are — which is why the identification test
-/// (`0x7a1390`'s always-nil `GetName`) is load-bearing and why the count-grew heuristic re-scans.
-/// It must not be mistaken for one.
+/// An addon's frame under `WorldFrame` (`pfUICombatScreen`, `_NameplatesFrame`) shares the list
+/// with the plates, whose `GetName` is always nil (`0x7a1390`).
 #[test]
 fn an_addon_frame_under_the_worldframe_is_not_a_plate() {
     let mut s = vm();
@@ -653,11 +574,9 @@ fn an_addon_frame_under_the_worldframe_is_not_a_plate() {
     );
 }
 
-/// **The plate takes the mouse, and hands its unit back.** It is a `Button` and born mouse-enabled
-/// (`CSimpleButton`'s ctor writes `[+0xcc] = 0x4`), so hovering it makes it the mouse focus — which
-/// on this engine means the UI pointer pass owns the cursor and the world pick stands down. What
-/// keeps the mouseover alive is the seam: the widget layer answers WHICH unit's plate the pointer
-/// is inside, exactly as the reference's OnEnter (`0x7cb850`) publishes `[0xb4e2c8]`.
+/// A plate is a mouse-enabled `Button` (`CSimpleButton`'s constructor writes `[+0xcc] = 0x4`), so
+/// hovering it takes the mouse focus from the world; the widget layer then names the plate's unit,
+/// as the reference's OnEnter (`0x7cb850`) publishes `[0xb4e2c8]`.
 #[test]
 fn hovering_a_plate_names_its_unit() {
     let mut s = vm();
@@ -666,19 +585,16 @@ fn hovering_a_plate_names_its_unit() {
     drive(&mut s, &[wolf]);
 
     assert_eq!(s.hovered_nameplate(), None, "nothing hovered yet");
-    // The plate's TOP-CENTRE is (500, 400) and it hangs 32 units below, so this is its middle.
+    // The plate hangs 32 units below its top centre (500, 400), so this is its middle.
     s.mouse_move(500.0, 384.0);
     assert_eq!(s.hovered_nameplate(), Some(key));
-    // Off the plate: the WorldFrame takes the focus again, and no plate is named.
+    // Off the plate the WorldFrame takes the focus again.
     s.mouse_move(50.0, 50.0);
     assert_eq!(s.hovered_nameplate(), None);
 }
 
-/// A completed click on a plate reaches the app — the reference's click slot (`0x7cb910`), whose
-/// tail is the same `SetSelection` a click on the body runs.
-///
-/// **Mouse-UP only**: the plate registers `LeftButtonUp | RightButtonUp` (`RegisterForClicks(0x500)`
-/// at `0x7cb637`), so a press alone selects nothing.
+/// The reference's click slot (`0x7cb910`) ends in the same `SetSelection` as a click on the body,
+/// and fires on the up edge only: `RegisterForClicks(0x500)` at `0x7cb637`.
 #[test]
 fn a_completed_click_on_a_plate_reaches_the_app() {
     let mut s = vm();
@@ -703,14 +619,9 @@ fn a_completed_click_on_a_plate_reaches_the_app() {
     );
 }
 
-/// **The right button too** — `RegisterForClicks(0x500)` is LeftButtonUp | **RightButtonUp**
-/// (`0x7cb637` → `[this+0x330]`), and the reference's slot forks on it: mask 1 → `0x4925d0`
-/// select, mask 4 → `0x492820` select **and interact** (decision 2233).
-///
-/// The regression this pins: a plate is created as a plain `Button`, whose default registered set
-/// is `{"LeftButtonUp"}` alone, so the release was refused before the click funnel — and with 2233
-/// taking the camera off a press that lands on a plate, that left right-clicking a nameplate doing
-/// nothing whatsoever.
+/// `0x500` includes RightButtonUp (`0x7cb637` writes `[this+0x330]`), where a plain `Button`
+/// registers LeftButtonUp alone; the slot forks on the mask: 1 selects (`0x4925d0`), 4 selects and
+/// interacts (`0x492820`).
 #[test]
 fn a_physical_right_click_on_a_plate_reaches_the_app() {
     let mut s = vm();
@@ -731,8 +642,6 @@ fn a_physical_right_click_on_a_plate_reaches_the_app() {
     assert_eq!(clicks[0].button, "RightButton");
 }
 
-/// A button the plate never registered fires nothing — the mask is exactly `0x500`, not "any
-/// button".
 #[test]
 fn a_middle_click_on_a_plate_fires_nothing() {
     let mut s = vm();
@@ -746,10 +655,8 @@ fn a_middle_click_on_a_plate_fires_nothing() {
     );
 }
 
-/// pfUI's click-through calls `plate:Click("LeftButton")` (`nameplates.lua:1274`), and
-/// CustomNameplates and `_Nameplates` do the same. A scripted click has to select the unit like a
-/// physical one — in the reference both go through the button's one click slot, and here they go
-/// through the one funnel that slot's twin lives on.
+/// pfUI's click-through (`nameplates.lua:1274`) calls `plate:Click`; in the reference a scripted
+/// and a physical click go through the button's one click slot.
 #[test]
 fn a_scripted_click_selects_too() {
     let mut s = vm();
@@ -764,15 +671,9 @@ fn a_scripted_click_selects_too() {
     assert_eq!(clicks[0].button, "RightButton");
 }
 
-/// **The mouselook toggle** (`0x60f830`): entering freelook hands the mouse back on every plate,
-/// leaving takes it again — the reference walks its own intrusive plate list doing exactly this,
-/// from `0x483e80` (enter) and `0x483e70` (leave).
-///
-/// **What it is for is NOT "a drag that begins over a plate"** — that gesture never reaches
-/// mouselook at all, because `0x7662c0` hands the mouse-down to the plate and stops the bus walk
-/// before any binding runs (decision 2233, which reversed the inference this doc used to carry).
-/// It is for a turn that started on the **world** and then dragged the pointer across a plate: the
-/// plates must not take a pointer that is hidden and locked to the camera.
+/// Entering mouselook turns the mouse off on every plate and leaving turns it back on (`0x60f830`,
+/// from `0x483e80` and `0x483e70`), for a turn begun on the world that drags across a plate; a
+/// press on a plate never reaches mouselook (`0x7662c0`).
 #[test]
 fn freelook_hands_the_mouse_back() {
     let mut s = vm();
@@ -796,14 +697,9 @@ fn freelook_hands_the_mouse_back() {
     );
 }
 
-/// **The plate's own `+0x3c` veto** (`0x7cba30`) — a DIFFERENT mechanism from the freelook toggle
-/// above, and the reason it is not folded into the same flag.
-///
-/// While a ground-targeted spell is armed the plate refuses the hit test *before* testing its rect
-/// (`0x6e48a0() && 0x6e6320() && !0x6e6180()` → `xor eax,eax; ret 4`, never calling the base), so
-/// the point falls through to the `WorldFrame` at (strata 0, level 0) behind it and the reticle can
-/// be placed through a plate. Crucially it never touches `[+0xcc]`: `IsMouseEnabled()` still
-/// answers **true** throughout, which is exactly what `0x60f830` does not do.
+/// The plate's `+0x3c` hit test (`0x7cba30`) refuses the point while a ground-targeted spell is
+/// armed (`0x6e48a0() && 0x6e6320() && !0x6e6180()`), so it falls through to the `WorldFrame`.
+/// It never touches `[+0xcc]`: `IsMouseEnabled` stays true, unlike under mouselook (`0x60f830`).
 #[test]
 fn a_ground_target_veto_refuses_the_hit_without_disabling_the_mouse() {
     let mut s = vm();
@@ -818,15 +714,13 @@ fn a_ground_target_veto_refuses_the_hit_without_disabling_the_mouse() {
         None,
         "the reticle must be placeable through a plate"
     );
-    // …and the press falls through with it, which is what lets the WorldFrame win the gesture and
-    // the ground cast commit where the player clicked.
+    // The press falls through too, so the WorldFrame takes the ground cast.
     s.mouse_button(500.0, 384.1, "LeftButton", true);
     s.mouse_button(500.0, 384.1, "LeftButton", false);
     assert!(
         s.take_nameplate_clicks().is_empty(),
         "a vetoed plate takes no click either"
     );
-    // The bit the veto must NOT have touched — an addon asking is told the truth.
     assert_eq!(
         s.eval::<i64>("local p = WorldFrame:GetChildren() return p:IsMouseEnabled()")
             .unwrap(),
diff --git a/crates/benilla-ui/src/script/tests/numeric_shape_gate.rs b/crates/benilla-ui/src/script/tests/numeric_shape_gate.rs
index 9f7e8c8d..7aa212c7 100644
--- a/crates/benilla-ui/src/script/tests/numeric_shape_gate.rs
+++ b/crates/benilla-ui/src/script/tests/numeric_shape_gate.rs
@@ -1,32 +1,9 @@
-//! **Shape C, closed as a CLASS**: every shape-C numeric position must take a `nil` — or a
-//! table, or a string — as **0.0** and complete, because the reference reads it with a bare
-//! `lua_tonumber 0x6f3620` and no `lua_isnumber` gate at all.
-//!
-//! This is one test and not six because which shape a given argument takes is per binding, not a
-//! global law: the reference's 408 widget-registrar positions (110 gated, 64 ungated) are a table a
-//! re-implementation is checked against, not an instinct. Our half of that table had drifted: 1973
-//! closed `SetTextColor` and left every sibling strict, so mlua's converter went on being the gate
-//! for five more years' worth of call sites.
-//!
-//! The live symptom that forced the audit: stock `QuestLogFrame.lua:337` does
-//! `QuestLogSkillHighlight:SetVertexColor(titleButton.r, titleButton.g, titleButton.b)`, and those
-//! three fields are only ever assigned in `QuestLog_Update` — so **any** path that selects a
-//! quest-log entry before the window has painted hands `SetVertexColor` three nils. Questie's
-//! `syncQuestWatch` (`QuestieTracker.lua:1160`) is exactly such a path: it calls
-//! `QuestLog_SetSelection` first. On the reference that is a no-op that stores black; for us it
-//! raised, and because the raise happened inside Questie's own event-queue drain — which nils an
-//! entry only *after* its handler returns — the queue jammed at that entry permanently. Every
-//! later entry (`SYNCLOG`, `DRAWNOTES`, `TRACKER`) was stranded for the rest of the session, which
-//! is why the minimap button's right-click could turn the quest icons OFF (a direct call) but
-//! never back ON (a `DRAWNOTES` enqueue).
-//!
-//! **Shape B is not shape C and is not tested here.** The alpha slot of every colour setter is B —
-//! a pre-staged default, `1.0f` at `0x778220` — so its absence is a *default*, not a zero, and
-//! `SetVertexColor`'s own B-slot carries a separate, deliberately-open divergence (1782).
+//! Shape C: a numeric position the reference reads with a bare `lua_tonumber` (`0x6f3620`) and no
+//! `lua_isnumber` gate, so nil, a table or a string is 0.0 and the call completes. Shape B, not
+//! tested here, is a pre-staged default, such as every colour setter's alpha (1.0 at `0x778220`).
 
 use super::common::script;
 
-/// Each row: the Lua that must not raise, and what a reader must say afterwards.
 #[test]
 fn every_shape_c_colour_position_takes_nil_as_zero_and_never_raises() {
     let s = script();
@@ -41,7 +18,7 @@ fn every_shape_c_colour_position_takes_nil_as_zero_and_never_raises() {
     )
     .unwrap();
 
-    // `Texture:SetVertexColor 0x79abd0` — `2=C 3=C 4=C`. The QuestLogFrame.lua:337 shape verbatim.
+    // `Texture:SetVertexColor 0x79abd0` (`2=C 3=C 4=C`), as stock `QuestLogFrame.lua:337` calls it.
     s.run("T:SetVertexColor(nil, nil, nil)")
         .expect("SetVertexColor(nil,nil,nil) is three bare lua_tonumbers, not a raise");
     s.run(
@@ -51,11 +28,11 @@ fn every_shape_c_colour_position_takes_nil_as_zero_and_never_raises() {
         "#,
     )
     .unwrap();
-    // A table and a string are the same 0.0 — `lua_tonumber` tests nothing.
+    // A table and a string are 0.0 too: `lua_tonumber` tests nothing.
     s.run("T:SetVertexColor({}, \"abc\", true)")
         .expect("no tag is rejected at a shape-C position");
 
-    // `Texture:SetTexCoord 0x79beb0` — every coordinate C; only the ARITY raises.
+    // `Texture:SetTexCoord 0x79beb0`: every coordinate C; only the arity raises.
     s.run("T:SetTexCoord(nil, nil, nil, nil)")
         .expect("four nil coordinates are four zeroes");
     s.run("T:SetTexCoord(0, 1, 0, 1, 0, 1, 0, 1)")
@@ -76,18 +53,17 @@ fn every_shape_c_colour_position_takes_nil_as_zero_and_never_raises() {
     )
     .unwrap();
 
-    // `ColorSelect:SetColorRGB 0x78eae0` — C on all three, and it fires OnColorSelect either way.
+    // `ColorSelect:SetColorRGB 0x78eae0`: C on all three; it fires OnColorSelect either way.
     s.run("CS:SetColorRGB(nil, nil, nil)")
         .expect("ColorSelect:SetColorRGB is shape C on r/g/b");
 
-    // `Texture:SetGradient 0x79ae30` / `SetGradientAlpha 0x79b180` — already C before this pass;
-    // pinned so they cannot regress into the family's old strictness.
+    // `Texture:SetGradient 0x79ae30` and `SetGradientAlpha 0x79b180`.
     s.run("T:SetGradient(\"HORIZONTAL\", nil, nil, nil, nil, nil, nil)")
         .expect("SetGradient's six stops are all C");
     s.run("T:SetGradientAlpha(\"VERTICAL\", nil, nil, nil, nil, nil, nil, nil, nil)")
         .expect("SetGradientAlpha's eight are C/B");
 
-    // `FontString:SetTextColor 0x79d9c0` — closed by 1973; pinned here so the class stays closed.
+    // `FontString:SetTextColor 0x79d9c0`.
     s.run("FS:SetTextColor(nil, nil, nil)")
         .expect("the sibling 1973 already fixed");
 }
diff --git a/crates/benilla-ui/src/script/tests/reference_surface.rs b/crates/benilla-ui/src/script/tests/reference_surface.rs
index 9e0231f9..f45f05d7 100644
--- a/crates/benilla-ui/src/script/tests/reference_surface.rs
+++ b/crates/benilla-ui/src/script/tests/reference_surface.rs
@@ -1,21 +1,6 @@
-//! **The 1.12 surface is the contract** (decisions 1188 §2, 1189) — enforced here rather than
-//! trusted to memory.
-//!
-//! benilla targets the 1.12.1 API. Anything beyond it is a *listed, justified* exception, and the
-//! point of this file is that the list cannot go unknown: every global our VM exposes must either
-//! be one 1.12 has, or appear below with a reason. A session that adds an Era-shaped verb has to
-//! delete or extend an assertion that says why not — which is exactly what did not happen when
-//! 1187 shipped eight Era globals on Era's authority and 1189 had to take them back out.
-//!
-//! **Why a superset is not free.** Lua branches on presence. An addon writing `if strmatch then`
-//! takes a path we cannot honour, and the failure surfaces far from the cause. Extra functions are
-//! harmless only if nothing feature-detects, which is not true of this ecosystem.
-//!
-//! The reference side is `reference/1.12-globals.tsv` — the running 1.12.1 client's own in-world
-//! `_G` (see `reference/README.md`). This test reads the `engine` and `lua` rows: the surface a VM
-//! is responsible for. It deliberately does **not** assert the converse — that we have everything
-//! 1.12 has — because that is a multi-year backlog, not a regression gate;
-//! `scripts/api-coverage.sh` is where that number is read.
+//! The 1.12 surface as a gate: every global benilla's VM exposes is one the 1.12.1 client has
+//! (`reference/1.12-globals.tsv`) or a listed exception, since addons branch on a global's
+//! presence; what 1.12 has and benilla lacks is `scripts/api-coverage.sh`'s count.
 
 use std::collections::HashSet;
 
@@ -39,72 +24,17 @@ fn reference() -> Vec<(String, String)> {
         .collect()
 }
 
-/// Names benilla exposes that 1.12 does not, each with the reason it is allowed to stay.
-///
-/// **`Benilla*` and `__benilla_*` are covered by prefix**, not enumerated: the first is our host
-/// bridge (verbs only our own transcribed FrameXML calls — a paperdoll model's facing, an item's
-/// stat block) and the second is the tick's pushed state. Neither is an API-target claim, and
-/// neither is reachable by accident from an addon that means to call a WoW function.
+/// Globals benilla exposes that 1.12 does not. `Benilla*` (the host bridge our own UI files call)
+/// and `__benilla_*` (the tick's pushed state) pass by prefix.
 fn allowed_beyond_1_12() -> HashSet<&'static str> {
     [
-        // ── our Lua runtime is 5.1 where 1.12's is 5.0 ────────────────────────────────────────
-        // `_G` is the last of these inherited rather than chosen: 1.12's base library does not
-        // export it (an addon reaches the globals with `getfenv(0)`, which is what AceLibrary
-        // does), but our own `getglobal`/`setglobal` are written over it. Closing it means
-        // rewriting those against the registry first.
-        //
-        // **This list has been shrinking as the dialect got measured**: `coroutine` left in 1194
-        // with the 5.1-only members of `string`/`table`/`math`; `print` and `_VERSION` left in
-        // 1197, when the base library's 36-entry table `0x811e28` was found to hold neither.
-        // `select` left last, and it is the one that shows what a written reason is worth — it
-        // carried two and outlived both. The first ("our transcribed FrameXML uses it in 16 files
-        // as the 5.1 spelling of 5.0's implicit `arg` table") was retired by 1751's migration and
-        // caught by 2142's census at *zero* sites. The second, written in its place, was that
-        // removing it meant giving up the 5.1 varargs it comes with — which 2101 had already given
-        // up, three days earlier, in the parser. A reason nobody re-derives is a reason with an
-        // expiry date; this list's job is to make the expiry visible, and twice it did not.
-        // The list only ever covered globals — the members needed `dump_globals --members` before
-        // anyone could see them at all.
+        // ── our Lua runtime is 5.1 where 1.12's is 5.0 ──
+        // 1.12's base library does not export `_G` (an addon reaches the globals with
+        // `getfenv(0)`); ours does, as our `getglobal`/`setglobal` are written over it.
         "_G",
-        // ── WoW API past 1.12 — 1188 phase 5's list, and the reason that phase exists ─────────
-        // **The reason written here was "every one of these is used by our own transcribed
-        // FrameXML today", and as of 2026-09-09 that is true of exactly ONE of the sixteen**
-        // (`SubmitChatInput`, in the dev-only `ScriptLogFrame.xml`) — a corpus census measured it
-        // and this file's own claim was checked against `assets/ui`'s seven remaining files, name
-        // by name, before this comment was rewritten (decision 2142). 1751's migration retired the
-        // windows that used the rest; the list outlived its justification, which is exactly how
-        // 2118 found the modifier keys still answering booleans years after 0068's reason for it
-        // had gone.
-        //
-        // **What they are NOT is load-bearing for the addon corpus, and 2143 corrects 2142 for
-        // saying so.** The claim written here was that the vanilla ecosystem assumes several of
-        // these exist — `pfUI/modules/loot.lua` calling `wipe` 25 times and defining it nowhere,
-        // so ours "makes that module run at all". That is wrong twice over, and the error is
-        // instructive: **a "1.12 addon" in that corpus is usually a MULTI-CLIENT addon**. pfUI
-        // ships one codebase for three clients and gates per module —
-        // `pfUI:RegisterModule("loot", "vanilla:tbc", …)`, matched by
-        // `strfind(version, pfUI.expansion)` at `pfUI.lua:250` — so a TBC-era habit sits in code
-        // the vanilla client reaches. The `wipe` calls are in `RequestRolls`,
-        // `BuildSpecialRecipientsMenu` and `ClearRolls`: the master-looter's roll helper, not the
-        // loot window, and that path throws on a real 1.12 client too. And `strsplit` was worse —
-        // pfUI has its own `pfUI.api.strsplit` (`api/api.lua:16`) and ShaguTweaks its own
-        // `ShaguTweaks.strsplit`; the bare calls are inside the vendored `libs/libpredict.lua`,
-        // which has TBC branches of its own.
-        //
-        // So our superset was HIDING those latent nil-calls, never enabling anything. The one
-        // real interaction left is the other direction: `AtlasLoot/Core/AtlasLoot.lua:2119`/`:2148`
-        // define GLOBAL `strsplit`/`strtrim` unconditionally, with incompatible pattern-based
-        // two-return semantics, and clobber ours for everything loaded after them — so ours is not
-        // authoritative at runtime either.
-        //
-        // Resolving each means replacing it with its 1.12 equivalent (`UnitPower` → `UnitMana`,
-        // which 1.12 has and we do not), deleting it, or recording why it stays.
-        //
-        // Three left with 1751's gossip work: `GetNumGossipQuests`, `GetGossipQuestInfo` and
-        // `SelectGossipQuest` were benilla's own single-list shape over the gossip packet's quest
-        // rows, and 1.12 has none of them — it publishes `GetGossipAvailableQuests` /
-        // `GetGossipActiveQuests` and a select for each, which is what this client answers now.
-        // The window that needed them is ours until it migrates; it calls the reference's four.
+        // ── WoW API past 1.12 ──
+        // Only `SubmitChatInput` is called from our UI files (`ScriptLogFrame.xml`'s slash
+        // commands); each of the rest awaits its 1.12 equivalent, removal or a reason.
         "CancelUnitBuff",
         "GetCursorInfo",
         "GetInventoryItemID",
@@ -121,9 +51,6 @@ fn allowed_beyond_1_12() -> HashSet<&'static str> {
 }
 
 /// Every global benilla's VM exposes is one 1.12 has, or a listed exception.
-///
-/// The failure message is the point: it names what is new and tells you the two ways out, so the
-/// next session cannot resolve it by deleting a bare assertion.
 #[test]
 fn our_globals_stay_inside_the_1_12_surface() {
     let reference = reference();
@@ -164,10 +91,7 @@ fn our_globals_stay_inside_the_1_12_surface() {
     );
 }
 
-/// The exception list is exact — no entry outlives the global it excuses.
-///
-/// Without this, a removed global leaves its excuse behind, and the list slowly stops describing
-/// the code. That is how a "listed, justified exception" decays into residue nobody can explain.
+/// The exception list is exact: no entry outlives its global, and none excuses a 1.12 name.
 #[test]
 fn the_exception_list_has_no_dead_entries() {
     let known: HashSet<String> = reference().into_iter().map(|(n, _)| n).collect();
@@ -193,7 +117,6 @@ fn the_exception_list_has_no_dead_entries() {
         dead.join(" ")
     );
 
-    // An entry that 1.12 turns out to have is a different bug: the excuse is wrong, not stale.
     let mut wrong: Vec<&str> = allowed_beyond_1_12()
         .into_iter()
         .filter(|n| known.contains(*n))
@@ -207,16 +130,8 @@ fn the_exception_list_has_no_dead_entries() {
     );
 }
 
-/// **`Texture:GetTexture()` — the three contract details that a plausible implementation gets
-/// silently wrong.** Verified at `0x79ba70`/`0x79baf0`/`0x835708`.
-///
-/// Four corpus addons reach it: `AtlasQuest.lua:228` is `AQATLASMAP = AtlasMap:GetTexture()` and
-/// `FuBarPlugin-2.0.lua:343` is `return self.iconFrame:GetTexture()`, each behind two addons.
-///
-/// The colour case is the one worth a test of its own. `SetTexture(r,g,b)` synthesizes an 8x8 solid
-/// and the getter reports the literal name `"Solid Texture"` — so an addon's `if not tex then`
-/// guard passes straight through. Returning nil there would read as tidier and would be wrong in
-/// exactly the direction callers test for.
+/// `Texture:GetTexture()` (`0x79ba70`/`0x79baf0`/`0x835708`): one value, nil when unset, the path
+/// without its extension, and the literal `"Solid Texture"` for a colour fill.
 #[test]
 fn get_texture_returns_the_stripped_path_and_solid_texture_for_a_fill() {
     let s = crate::script::UiScript::new().unwrap();
@@ -229,22 +144,17 @@ fn get_texture_returns_the_stripped_path_and_solid_texture_for_a_fill() {
     )
     .unwrap();
 
-    // Never set: nil, and exactly one value.
     assert_eq!(
         s.eval::<Option<String>>("return GTFTex:GetTexture()")
             .unwrap(),
         None
     );
     assert_eq!(
-        // `.unwrap()`, not the `.unwrap_or(1)` this carried while it was spelled with `select`:
-        // that default made a raise indistinguishable from the answer being asserted, which is the
-        // one thing an arity check must not do (2171).
         s.arity("GTFTex:GetTexture()").unwrap(),
         1,
         "exactly one return value"
     );
 
-    // A path with no extension comes back unchanged.
     s.run(r#"GTFTex:SetTexture("Interface\\Icons\\Spell_Fire_FlameBolt")"#)
         .unwrap();
     assert_eq!(
@@ -252,8 +162,6 @@ fn get_texture_returns_the_stripped_path_and_solid_texture_for_a_fill() {
         "Interface\\Icons\\Spell_Fire_FlameBolt"
     );
 
-    // ...and one WITH an extension is stripped at the last `.` — the loader appends it, the getter
-    // takes it back off.
     s.run(r#"GTFTex:SetTexture("Interface\\Icons\\Foo.blp")"#)
         .unwrap();
     assert_eq!(
@@ -261,7 +169,6 @@ fn get_texture_returns_the_stripped_path_and_solid_texture_for_a_fill() {
         "Interface\\Icons\\Foo"
     );
 
-    // The colour form: the literal name, NOT nil.
     s.run("GTFFill:SetTexture(1, 0, 0, 1)").unwrap();
     assert_eq!(
         s.eval::<String>("return GTFFill:GetTexture()").unwrap(),
@@ -269,7 +176,6 @@ fn get_texture_returns_the_stripped_path_and_solid_texture_for_a_fill() {
         "a colour-filled region reports a NAME — `if not tex then` must not fire"
     );
 
-    // And a plain SetTexture makes it ordinary again.
     s.run(r#"GTFFill:SetTexture("Interface\\Buttons\\UI-Quickslot2")"#)
         .unwrap();
     assert_eq!(
@@ -278,17 +184,8 @@ fn get_texture_returns_the_stripped_path_and_solid_texture_for_a_fill() {
     );
 }
 
-/// **The shadow accessors on a REGION, and `GetShadowColor`'s four values.**
-///
-/// They existed on the font-object table; a FontString from `CreateFontString` had none, which is
-/// exactly where the corpus calls them. `FuBar_NavigatorFu/NavigatorFu.lua:31` is
-/// `coordText:SetShadowColor(GameFontNormal:GetShadowColor())` — getter on a font object, setter on
-/// a fresh region, in one line — and `KLHThreatMeter/.../KTM_Gui.lua:404` is
-/// `fontstring:SetShadowColor(0,0,0,0.3)`.
-///
-/// **Four values, not three** (`0x79dd2f`, `mov eax,0x4`). Three is
-/// the plausible wrong answer and it silently drops the alpha NavigatorFu round-trips: the whole
-/// point of its line is that whatever `GameFontNormal` carries arrives intact.
+/// A FontString's shadow accessors; `GetShadowColor` returns four values, alpha included
+/// (`0x79dd2f`, `mov eax,0x4`).
 #[test]
 fn region_shadow_accessors_round_trip_four_values() {
     let s = crate::script::UiScript::new().unwrap();
@@ -302,7 +199,6 @@ fn region_shadow_accessors_round_trip_four_values() {
     );
     assert_eq!(s.arity("SHFText:GetShadowOffset()").unwrap(), 2);
 
-    // NavigatorFu's line, in shape: a font object's shadow piped straight into a region's.
     s.run("SHFText:SetShadowColor(0, 0, 0, 0.3) SHFText:SetShadowOffset(1, -1)")
         .unwrap();
     let (r, g, b, a) = s
@@ -315,7 +211,6 @@ fn region_shadow_accessors_round_trip_four_values() {
         (1.0, -1.0)
     );
 
-    // Either half may be set first: setting only the offset must not blank the colour.
     s.run("SHFText:SetShadowOffset(2, -2)").unwrap();
     assert_eq!(
         s.eval::<f32>("local _,_,_,a = SHFText:GetShadowColor() return a")
@@ -325,18 +220,9 @@ fn region_shadow_accessors_round_trip_four_values() {
     );
 }
 
-/// **`Region:SetParent(frame)` — it exists on a Texture/FontString, and we were the ones missing
-/// it.** `SetParent` is in the Region method table (`0x7a1550`) and both leaf lookups fall back to
-/// Region's (`0x79c650` / `0x79ee50`), so `FuBar_FuXPFu.lua:210`'s
-/// `self.Spark:SetParent(self.XPBar)` — a texture from `XPBar:CreateTexture` — is a working line on
-/// the real client.
-///
-/// The two traps pinned here are the ones a plausible implementation gets wrong in opposite
-/// directions. **A non-Frame argument RAISES** (`IsA(FrameTag)` at `0x7a16ea`, message
-/// `"…Wrong parent object type, expected frame"`) rather than no-opping; and **anchors are NOT
-/// touched** by the re-link, which moves draw-layer/region-list membership only — so a re-parented
-/// texture keeps resolving against whatever `SetPoint` named, and FuXPFu's re-point on the next
-/// line is the correct pattern rather than a workaround.
+/// `Region:SetParent` (`0x7a1550`, reached by both leaf lookups' fallback: `0x79c650`, `0x79ee50`)
+/// moves the region's draw-list membership and leaves its anchors alone; a non-Frame argument
+/// raises (`IsA(FrameTag)` at `0x7a16ea`).
 #[test]
 fn region_set_parent_relinks_the_draw_owner_and_leaves_anchors_alone() {
     /// The resolved rect of the one texture quad whose path contains `needle`, if it draws at all.
@@ -369,7 +255,6 @@ fn region_set_parent_relinks_the_draw_owner_and_leaves_anchors_alone() {
     let before = tex_rect(&s, "SPGlow").expect("the spark draws under A");
     assert_eq!(before, crate::layout::Rect::new(22.0, 4.0, 46.0, 28.0));
 
-    // FuXPFu's line, and it returns nothing at all.
     assert_eq!(
         s.arity("Spark:SetParent(B)").unwrap(),
         0,
@@ -382,8 +267,6 @@ fn region_set_parent_relinks_the_draw_owner_and_leaves_anchors_alone() {
         "the anchors are untouched — the spark still resolves against A, 300px from B"
     );
 
-    // …and the re-link is real, not merely recorded: the spark now draws with B. Hiding B takes it
-    // off the screen; hiding A (which it is still anchored to) does not.
     s.run("B:Hide()").unwrap();
     assert_eq!(
         tex_rect(&s, "SPGlow"),
@@ -398,8 +281,6 @@ fn region_set_parent_relinks_the_draw_owner_and_leaves_anchors_alone() {
         "and not with the frame it is merely anchored to"
     );
 
-    // A non-Frame argument raises. A texture is the case the reference names, and it is the one an
-    // addon actually hits (a mixed table of frames and textures walked in a loop).
     for bad in ["Spark:SetParent(Spark)", "Spark:SetParent(5)"] {
         let e = s
             .run(bad)
@@ -410,11 +291,10 @@ fn region_set_parent_relinks_the_draw_owner_and_leaves_anchors_alone() {
             "wanted the reference's 'expected frame' rejection, got: {e}"
         );
     }
-    // A MISSING argument is not the nil form: TNONE never reaches the nil branch.
+    // A missing argument is `TNONE`, which never reaches the nil branch.
     assert!(s.run("Spark:SetParent()").is_err(), "no argument raises");
 
-    // The nil form detaches without error: orphaned and unrendered, not destroyed — a later
-    // re-parent brings the same region back.
+    // nil detaches the region without destroying it.
     s.run("A:Show() Spark:SetParent(nil)").unwrap();
     s.resolve();
     assert_eq!(
@@ -431,19 +311,9 @@ fn region_set_parent_relinks_the_draw_owner_and_leaves_anchors_alone() {
     );
 }
 
-/// **`Button:SetFont(file, height [, flags])` — it exists, it returns NOTHING, and it never
-/// touches the label.** `0x780880`.
-/// `_LazyPig/LazyPigMenu.lua:214` calls it straight on a `CreateFrame("Button", …)` and is blocked
-/// on it today.
-///
-/// Three traps, each pinned here because each is a plausible implementation's silent divergence.
-/// **Zero return values**: the shared impl pushes `1`/nil (a real font-load probe on a Font object)
-/// and Button *discards* it (`xor eax,eax`), so answering `true` would hand an addon a probe the
-/// client does not have. **`GetFont` returns three values**, off the normal embedded font — which
-/// resolves through what that state inherits when nothing set it locally. And **a bare Button with
-/// no `<ButtonText>` is a silent no-op**: `SetFont`/`GetFont` never dereference the FontString
-/// pointer `+0x338`, so there is no error and — the observable half — **no lazy label creation**,
-/// which `GetFontString()` would report.
+/// `Button:SetFont` (`0x780880`) returns nothing, discarding the shared impl's `1`/nil
+/// (`xor eax,eax`), and sets the button's normal font without touching the label pointer
+/// (`+0x338`), so a bare Button makes no label; `GetFont` returns three values off that font.
 #[test]
 fn button_set_font_returns_nothing_and_is_a_no_op_without_a_label() {
     let s = crate::script::UiScript::new().unwrap();
@@ -456,7 +326,6 @@ fn button_set_font_returns_nothing_and_is_a_no_op_without_a_label() {
     )
     .unwrap();
 
-    // _LazyPig's line, on a Button that has no label at all.
     assert_eq!(
         s.arity(r#"SFBare:SetFont("Fonts\\FRIZQT__.TTF", 8)"#)
             .unwrap(),
@@ -479,13 +348,12 @@ fn button_set_font_returns_nothing_and_is_a_no_op_without_a_label() {
             .unwrap(),
         ("Fonts\\FRIZQT__.TTF".to_string(), 8.0, String::new())
     );
-    // Still three when nothing has ever set a font — path and height are nil, not absent.
+    // Nothing set: still three values, the path and height nil.
     assert_eq!(s.arity("SFLabelled:GetFont()").unwrap(), 3);
     assert!(s
         .eval::<bool>("local f = SFLabelled:GetFont() return f == nil")
         .unwrap());
 
-    // The flags argument is normalized to its OUTLINETYPE token, like every other GetFont.
     s.run(r#"SFBare:SetFont("Fonts\\SKURRI.TTF", 12, "THICKOUTLINE")"#)
         .unwrap();
     assert_eq!(
@@ -496,8 +364,7 @@ fn button_set_font_returns_nothing_and_is_a_no_op_without_a_label() {
     // Both arguments are required (`lua_isstring` + `lua_isnumber`, else the usage error).
     assert!(s.run(r#"SFBare:SetFont("Fonts\\SKURRI.TTF")"#).is_err());
 
-    // Unset locally, GetFont reads through what the NORMAL state inherits — how a
-    // GameMenuButtonTemplate button answers its template's face before anything calls SetFont.
+    // Unset locally, GetFont reads through the normal state's font object.
     s.run(
         r#"
         CreateFont("SFInherited")
@@ -512,8 +379,7 @@ fn button_set_font_returns_nothing_and_is_a_no_op_without_a_label() {
         ("Fonts\\MORPHEUS.TTF".to_string(), 14.0)
     );
 
-    // …and a local SetFont outranks that inherited object on the label's PAINT, not only in the
-    // getter — the whole point of the call `_LazyPig` makes.
+    // A local SetFont outranks that object on the label's paint too.
     s.run(r#"SFLabelled:SetFont("Fonts\\SKURRI.TTF", 9)"#)
         .unwrap();
     let (font, height) = s
@@ -536,21 +402,14 @@ fn button_set_font_returns_nothing_and_is_a_no_op_without_a_label() {
     );
 }
 
-/// **`SetNonSpaceWrap` / `CanNonSpaceWrap`** — FontString only (`0x79e9f0`/`0x79ead0`).
-/// `oRA2/Leader/Item.lua:561` is `f.textname:SetNonSpaceWrap(false)`, reached
-/// by two addons.
-///
-/// Two contract details, both easy to get wrong and both pinned here: the getter is
-/// **`CanNonSpaceWrap`**, not `GetNonSpaceWrap`, and it answers **`1` or nil** rather than a
-/// boolean — 1.12 predates that convention and an addon may compare against 1. And a **no-argument
-/// call ENABLES** it; the default is on, so it is not a query.
+/// FontString's `SetNonSpaceWrap`/`CanNonSpaceWrap` (`0x79e9f0`/`0x79ead0`): on by default, the
+/// getter answers `1` or nil, and a bare `SetNonSpaceWrap()` turns it on.
 #[test]
 fn non_space_wrap_defaults_on_and_answers_one_or_nil() {
     let s = crate::script::UiScript::new().unwrap();
     s.run(r#"f = CreateFrame("Frame", "NSF") fs = f:CreateFontString("NSFText", "ARTWORK")"#)
         .unwrap();
 
-    // Default is ON, and the answer is the NUMBER 1 — not `true`.
     assert_eq!(
         s.eval::<Option<i64>>("return NSFText:CanNonSpaceWrap()")
             .unwrap(),
@@ -563,7 +422,6 @@ fn non_space_wrap_defaults_on_and_answers_one_or_nil() {
         "it must NOT be a boolean — an addon comparing against 1 would break"
     );
 
-    // oRA2's line.
     s.run("NSFText:SetNonSpaceWrap(false)").unwrap();
     assert_eq!(
         s.eval::<Option<i64>>("return NSFText:CanNonSpaceWrap()")
@@ -572,7 +430,6 @@ fn non_space_wrap_defaults_on_and_answers_one_or_nil() {
         "off answers nil, not 0 and not false"
     );
 
-    // A no-argument call ENABLES rather than querying.
     s.run("NSFText:SetNonSpaceWrap()").unwrap();
     assert_eq!(
         s.eval::<Option<i64>>("return NSFText:CanNonSpaceWrap()")
@@ -582,23 +439,10 @@ fn non_space_wrap_defaults_on_and_answers_one_or_nil() {
     );
 }
 
-/// **The EditBox font block — the first sixteen entries of its own registrar table, and the largest
-/// single gap the per-kind widget-method census found** (decision 1229, whose ranking opens
-/// `63  EditBox:SetFontObject   (on Texture, FontString)`).
-///
-/// `EditBox`'s table is `.data 0x87bb68`, **48 entries** — the count read from the `mov edx,0x30`
-/// at the registering site `0x799ab5`, never from a run-length scan. There is no `FontInstance`
-/// class in the 1.12 Lua chain (the shared C++ impl `0x79f210`): each of the six text-bearing types
-/// re-declares the block in its own flat table, so membership is a per-table fact and **a name we
-/// add that the table does not carry is exactly as wrong as one we miss**.
-///
-/// The two halves pinned here are therefore both directions. Present: the fourteen we wire.
-/// Absent: `SetSpacing`/`GetSpacing`, which the table *does* carry (#10–#11) and we deliberately
-/// withhold because nothing here models line spacing — a stored-but-undrawn setter is the silent
-/// divergence of 1203/1205/1211, while a nil-value call names itself, and corpus demand is zero.
-/// Absent too: the names that belong to *other* tables and must not leak onto an EditBox through
-/// ours — `CopyFontObject` (Font object only), `SetNonSpaceWrap`/`CanNonSpaceWrap` and
-/// `SetTextHeight`/`GetStringWidth` (FontString only).
+/// EditBox's registrar table (`.data 0x87bb68`, 48 entries, `mov edx,0x30` at `0x799ab5`) opens
+/// with the font block each text-bearing type re-declares over the shared impl `0x79f210`: its
+/// fourteen font verbs answer, its `SetSpacing`/`GetSpacing` (#10, #11) are not installed as
+/// nothing models line spacing, and other tables' names do not leak onto it.
 #[test]
 fn editbox_carries_the_font_block_its_registrar_table_declares() {
     let s = crate::script::UiScript::new().unwrap();
@@ -629,10 +473,10 @@ fn editbox_carries_the_font_block_its_registrar_table_declares() {
     }
 
     for name in [
-        // On EditBox's real table, withheld on purpose (nothing models spacing).
+        // On EditBox's table, not installed: nothing models line spacing.
         "SetSpacing",
         "GetSpacing",
-        // Not on EditBox's table at all — adding one is the same class of error as missing one.
+        // Not on EditBox's table.
         "CopyFontObject",
         "SetNonSpaceWrap",
         "CanNonSpaceWrap",
@@ -647,21 +491,10 @@ fn editbox_carries_the_font_block_its_registrar_table_declares() {
     }
 }
 
-/// **Every EditBox font binding is a type-guard shim that returns whatever the shared implementation
-/// returned**, so the arities below are the shared ones verbatim — verified at the bytes: each
-/// binding ends `call <shared>` then `pop edi; pop esi; pop ebx; ret`, with **no `mov eax,N` and no
-/// `xor eax,eax`** after the call.
-///
-/// The trap is `SetFont`, and it points the opposite way to the one already pinned for Button.
-/// `Button:SetFont` (`0x780880`) ends `xor eax,eax` and returns **nothing** —
-/// [`button_set_font_returns_nothing_and_is_a_no_op_without_a_label`]. `EditBox:SetFont`
-/// (`0x797210` → `0x79f210`) does not discard, so the shared `lua_pushnumber(1.0)` (`0x79f345`) /
-/// `lua_pushnil` (`0x79f361`) passes straight through: **one value, the number `1`, not `true` and
-/// not zero values**. A probe written `if not eb:SetFont(f, s) then` needs the nil half; a probe
-/// written `== 1` needs the number half.
-///
-/// `GetShadowColor` returns **four** values (`0x79f9b3 mov eax,0x4`); three is the plausible wrong
-/// answer and silently drops the alpha.
+/// Each EditBox font binding returns what the shared implementation returns (no `mov eax,N` or
+/// `xor eax,eax` after the call), so unlike `Button:SetFont` (`0x780880`), `EditBox:SetFont`
+/// (`0x797210` → `0x79f210`) answers the number `1` or nil (`0x79f345`/`0x79f361`), and
+/// `GetShadowColor` returns four values (`0x79f9b3 mov eax,0x4`).
 #[test]
 fn editbox_font_block_return_shapes_are_the_shared_implementations() {
     let s = crate::script::UiScript::new().unwrap();
@@ -674,7 +507,6 @@ fn editbox_font_block_return_shapes_are_the_shared_implementations() {
     )
     .unwrap();
 
-    // The mutators push nothing at all.
     for call in [
         "SetFontObject(EBProbeFont)",
         "SetTextColor(1, 0, 0)",
@@ -690,7 +522,6 @@ fn editbox_font_block_return_shapes_are_the_shared_implementations() {
         );
     }
 
-    // The getters' exact widths.
     for (call, want) in [
         ("GetFontObject()", 1),
         ("GetFont()", 3),
@@ -707,7 +538,6 @@ fn editbox_font_block_return_shapes_are_the_shared_implementations() {
         );
     }
 
-    // SetFont: ONE value, and it is the number 1 — not `true`, and not nothing (the Button shape).
     assert_eq!(
         s.arity(r#"EBShape:SetFont("Fonts\\SKURRI.TTF", 12)"#)
             .unwrap(),
@@ -723,14 +553,13 @@ fn editbox_font_block_return_shapes_are_the_shared_implementations() {
     assert!(s
         .eval::<bool>(r#"return EBShape:SetFont("Fonts\\SKURRI.TTF", 12) == 1"#)
         .unwrap());
-    // An unloadable (empty) path is the FALSEY answer, not an error — `!OmniCC`'s probe idiom.
+    // An unloadable (empty) path answers nil, not an error.
     assert!(s
         .eval::<bool>(r#"return EBShape:SetFont("", 12) == nil"#)
         .unwrap());
     // Both arguments are gated (`lua_isstring` + `lua_isnumber`, else the usage error).
     assert!(s.run(r#"EBShape:SetFont("Fonts\\SKURRI.TTF")"#).is_err());
 
-    // The shadow round-trips all four channels — three would drop the alpha.
     assert_eq!(
         s.eval::<(f32, f32, f32, f32)>("return EBShape:GetShadowColor()")
             .unwrap(),
@@ -741,7 +570,7 @@ fn editbox_font_block_return_shapes_are_the_shared_implementations() {
             .unwrap(),
         (1.0, -1.0)
     );
-    // GetFontObject answers the OBJECT, never its name — the corpus indexes the result immediately.
+    // GetFontObject answers the object, not its name.
     assert_eq!(
         s.eval::<String>("return type(EBShape:GetFontObject())")
             .unwrap(),
@@ -749,20 +578,8 @@ fn editbox_font_block_return_shapes_are_the_shared_implementations() {
     );
 }
 
-/// **The real `Dewdrop-2.0` shape, which is the whole reason this landed.**
-///
-/// `Dewdrop-2.0.lua:1673-1675` is verbatim:
-/// ```lua
-/// local editBox = CreateFrame("EditBox", nil, editBoxFrame)
-/// editBoxFrame.editBox = editBox
-/// editBox:SetFontObject(ChatFontNormal)
-/// ```
-/// — an **anonymous** EditBox parented to a frame, then `SetFontObject` on it two lines later. That
-/// file is vendored into **63 addon folders** of the 218-addon corpus (65 copies: `FuBar` plus ~50
-/// FuBar plugins, `BigWigs`, `AtlasLoot`, `oRA2`, `SnaFu`, …), so the census's `63` is **one library
-/// replicated**, not 63 independent addons (decision 1207).
-///
-/// `AceGUIWidget-Slider.lua:204-210` is the same shape with `SetJustifyH("CENTER")` on the end.
+/// `Dewdrop-2.0.lua:1673-1675`'s shape: an anonymous EditBox under a frame, then
+/// `SetFontObject(ChatFontNormal)`.
 #[test]
 fn the_dewdrop_editbox_font_shape_resolves_and_paints() {
     let s = crate::script::UiScript::new().unwrap();
@@ -782,12 +599,10 @@ fn the_dewdrop_editbox_font_shape_resolves_and_paints() {
     )
     .unwrap();
 
-    // The link is live and readable back as the object.
     assert!(s
         .eval::<bool>("return DewdropEBFrame.editBox:GetFontObject() == ChatFontNormal")
         .unwrap());
-    // …and the object's paint really reached the box's implicit FontString (the `[this+0x324]` the
-    // reference's shim hands the shared implementation).
+    // The object's paint reaches the box's own FontString (`[this+0x324]`, what the shim passes).
     assert_eq!(
         s.eval::<(String, f32)>("local p, h = DewdropEBFrame.editBox:GetFont() return p, h")
             .unwrap(),
@@ -798,32 +613,22 @@ fn the_dewdrop_editbox_font_shape_resolves_and_paints() {
         .unwrap();
     assert_eq!((r, g, b), (0.9, 0.9, 0.9));
 
-    // The AceGUI slider's tail, on the same box.
+    // `AceGUIWidget-Slider.lua:204-210` ends the same shape with this.
     s.run(r#"DewdropEBFrame.editBox:SetJustifyH("CENTER")"#)
         .unwrap();
 }
 
-/// **`SetJustifyH`/`SetJustifyV` mask to their own axis, and a token from the other axis silently
-/// clears rather than erroring.** The enum is `.rdata 0x811ad0`, `{bits, token}`: `LEFT` 0x01,
-/// `CENTER` 0x02, `RIGHT` 0x04, `TOP` 0x08, `MIDDLE` 0x10, `BOTTOM` 0x20, stored in one dword with
-/// bits 0–2 horizontal and 3–5 vertical.
-///
-/// Two traps, both of which our older FontString/Font copies of these verbs get wrong by coercing
-/// anything unrecognised to CENTER/MIDDLE:
-///  · **an unknown token RAISES** `Usage: %s:SetJustifyH("justify")` (`0x87c77c`);
-///  · **a valid token from the wrong axis parses and then masks to nothing** — `SetJustifyH("TOP")`
-///    yields 0x08 and `0x08 & 0x07 == 0`, so justifyH is CLEARED and `GetJustifyH()` answers the
-///    literal `"UNKNOWN"` (`0x6f1a00`, `.data 0x838044`). No error is raised either way.
+/// The justify enum (`.rdata 0x811ad0`) keeps both axes in one dword, bits 0-2 horizontal and 3-5
+/// vertical: an unknown token raises (`0x87c77c`), and a token from the other axis masks to
+/// nothing, so `GetJustifyH()` answers `"UNKNOWN"` (`0x6f1a00`, `.data 0x838044`).
 #[test]
 fn editbox_justify_masks_to_its_axis_and_answers_unknown() {
     let s = crate::script::UiScript::new().unwrap();
     s.run(r#"EB = CreateFrame("EditBox", "EBJustify")"#)
         .unwrap();
 
-    // **LEFT, not the generic font default CENTER.** The `CSimpleFont` ctor really does default to
-    // `0x212` (CENTER | MIDDLE | 0x200), but the EditBox ctor overrides the horizontal axis right
-    // after linking its font instance (`0x779bcd … and eax,~6; or eax,1;` stored at `0x779be4`), so
-    // a fresh box starts at `0x211`. Taking the generic default is the plausible wrong answer.
+    // A fresh EditBox is LEFT: its ctor turns the font default `0x212` (CENTER | MIDDLE | 0x200)
+    // into `0x211` (`0x779bcd`, stored at `0x779be4`).
     assert_eq!(
         s.eval::<String>("return EBJustify:GetJustifyH()").unwrap(),
         "LEFT"
@@ -833,7 +638,6 @@ fn editbox_justify_masks_to_its_axis_and_answers_unknown() {
         "MIDDLE"
     );
 
-    // Each axis is replaced independently — setting V leaves H alone.
     s.run(r#"EBJustify:SetJustifyH("LEFT") EBJustify:SetJustifyV("BOTTOM")"#)
         .unwrap();
     assert_eq!(
@@ -842,7 +646,6 @@ fn editbox_justify_masks_to_its_axis_and_answers_unknown() {
         ("LEFT".to_string(), "BOTTOM".to_string())
     );
 
-    // The cross-axis trap: "TOP" parses, masks to 0, and CLEARS justifyH.
     s.run(r#"EBJustify:SetJustifyH("TOP")"#).unwrap();
     assert_eq!(
         s.eval::<String>("return EBJustify:GetJustifyH()").unwrap(),
@@ -855,23 +658,13 @@ fn editbox_justify_masks_to_its_axis_and_answers_unknown() {
         "and it leaves the vertical axis untouched"
     );
 
-    // An unrecognised token is the usage error, never a silent fallback to CENTER.
     assert!(s.run(r#"EBJustify:SetJustifyH("SIDEWAYS")"#).is_err());
 }
 
-/// **`EditBox:SetJustifyV` echoes through its getter and never reaches the pixels — on the real
-/// client too, permanently and by construction.** `CSimpleFontString+0x124` is a per-bit *inherit*
-/// mask over the rendered justify `+0x120`, and `SetMultiLine 0x77a4a0` clears the whole vertical
-/// group `0x38` from it on **both** legs while writing the V bits locally — multi-line → TOP,
-/// single-line → MIDDLE. The
-/// EditBox ctor calls `SetMultiLine` unconditionally at birth (`0x779c2f`, with the ctor's zero
-/// register), and a census of all 256 `+0x124` operands image-wide found every `CSimpleFontString`
-/// writer to be an AND: **nothing ever ORs an inherit bit back in.** So the value written by
-/// `SetJustifyV` is masked out at `0x77086e`, while `GetJustifyV` reads the font *instance*
-/// (`0x79fd73`) and answers it faithfully.
-///
-/// This pins the shape rather than the accident: a future change that "fixes" the getter by wiring
-/// V justify through to the region would match neither the client nor our own draw law.
+/// `EditBox:SetJustifyV` reaches the getter (`0x79fd73` reads the font instance) but never the
+/// pixels: `SetMultiLine 0x77a4a0`, which the ctor always calls (`0x779c2f`), clears the vertical
+/// inherit bits (`CSimpleFontString+0x124`, over the drawn justify `+0x120`) and writes TOP or
+/// MIDDLE itself; nothing sets those bits back, so `0x77086e` masks the setter's value out.
 #[test]
 fn editbox_justify_v_echoes_but_multiline_alone_decides_the_pixels() {
     let mut s = crate::script::UiScript::new().unwrap();
@@ -903,55 +696,38 @@ fn editbox_justify_v_echoes_but_multiline_alone_decides_the_pixels() {
     // A single-line box renders MIDDLE, the `0x77a599` leg.
     assert_eq!(drawn_v(&s), crate::script::JustifyV::Middle);
 
-    // SetJustifyV("TOP") is echoed by the getter…
     s.run(r#"EBJV:SetJustifyV("TOP")"#).unwrap();
     assert_eq!(
         s.eval::<String>("return EBJV:GetJustifyV()").unwrap(),
         "TOP",
         "the getter reads the font instance and echoes faithfully"
     );
-    // …and does NOT move the pixels. This is the disagreement, and it is faithful.
     assert_eq!(
         drawn_v(&s),
         crate::script::JustifyV::Middle,
         "SetJustifyV is masked out of the rendered justify — multiLine alone decides it"
     );
 
-    // multiLine is what actually moves it, on the `0x77a509` leg.
+    // Multi-line moves it, the `0x77a509` leg.
     s.run("EBJV:SetMultiLine(true)").unwrap();
     assert_eq!(drawn_v(&s), crate::script::JustifyV::Top);
-    // …and the getter still echoes whatever was last set, unaffected.
     assert_eq!(
         s.eval::<String>("return EBJV:GetJustifyV()").unwrap(),
         "TOP"
     );
 }
 
-/// **`Texture:SetDesaturated(flag)` answers `shaderSupported`, and since 1327 ours says yes.**
-///
-/// `0x79c1e0`. The reference's own `ItemButtonTemplate.lua:69` is
-/// `local shaderSupported = icon:SetDesaturated(desaturated)`, and lines 70-78 fall back to a 0.5
-/// grey vertex tint when that answer is falsy — 1.12 shipped on cards without the shader, so the
-/// verb reporting "no" is a real machine's answer, not a stub.
-///
-/// benilla answered nil for exactly as long as nothing greyed. Decision 1327 gave the renderer the
-/// luminance fold, so the honest answer flipped: a caller that asks for grey now gets grey, and
-/// keeps its own tint instead of having it overwritten by the 0.5 fallback. The test pins the
-/// return SHAPE, because the return is what callers branch on — `1`, not `true`, because the C
-/// answer is `1|nil` and every reference consumer writes `not shaderSupported`.
-///
-/// 98 of the 109 draw-then-raise addons in the corpus die on this one verb, via
-/// `FuBar_Panel.lua:43` → Dewdrop `AddLine` → `button.arrow:SetDesaturated(true)`, unguarded.
+/// `Texture:SetDesaturated` (`0x79c1e0`) answers `shaderSupported`, `1` or nil; benilla's renderer
+/// greys, so it answers `1`, and stock `ItemButtonTemplate.lua:69` keeps the caller's tint rather
+/// than its 0.5 fallback.
 #[test]
 fn set_desaturated_reports_shader_support_and_does_not_raise() {
     let s = crate::script::UiScript::new().unwrap();
     s.run(r#"f = CreateFrame("Frame", "DsF") tex = f:CreateTexture("DsTex", "ARTWORK")"#)
         .unwrap();
 
-    // Dewdrop's exact call — the one 98 addons reach. It must not raise.
     s.run("DsTex:SetDesaturated(true)").unwrap();
 
-    // ...and it answers truthy, so the reference's shader arm is taken.
     assert!(
         s.eval::<bool>("return DsTex:SetDesaturated(true) == 1")
             .unwrap(),
@@ -963,9 +739,7 @@ fn set_desaturated_reports_shader_support_and_does_not_raise() {
         "one return value"
     );
 
-    // The reference's own consumer, transcribed: a truthy answer keeps the CALLER's tint, and the
-    // 0.5 fallback never fires. This is the half B162 turned on — the talent tree asks for
-    // `(1, 0.65, 0.65, 0.65)` and must get 0.65, greyscale, not a flat 0.5 colour multiply.
+    // `SetItemButtonDesaturated`'s branch, transcribed: a truthy answer keeps the caller's tint.
     s.run(
         r#"
         local shaderSupported = DsTex:SetDesaturated(true)
@@ -983,18 +757,12 @@ fn set_desaturated_reports_shader_support_and_does_not_raise() {
         "the shader arm keeps the caller's tint, got {r},{g},{b}"
     );
 
-    // Both spellings of "off" are off — nil and false.
     s.run("DsTex:SetDesaturated(nil) DsTex:SetDesaturated(false)")
         .unwrap();
 }
 
-/// `UnitCreatureType(unit)` — `0x51a280`'s three-stage resolver, of which we model stages 2 and 3.
-///
-/// The load-bearing assertion is the **player** one. `0x605570` falls through the (never populated)
-/// creature record to a `ChrRaces.dbc` col-9 lookup that is **7 for all nine shipped races**, and
-/// `CreatureType[7]` is `"Humanoid"` — so a player answers a word, not nil. Reading only the
-/// creature record, which is what our data alone suggested, would have been wrong for every
-/// `UnitCreatureType("player")` call in the corpus.
+/// `UnitCreatureType` (`0x51a280`, stages 2 and 3 of three built): a creature's cached record,
+/// else (`0x605570`) the race's `ChrRaces.dbc` column 9, which is 7, "Humanoid", for every race.
 #[test]
 fn unit_creature_type_answers_the_record_then_falls_back_to_humanoid() {
     let mut s = script();
@@ -1015,24 +783,20 @@ fn unit_creature_type_answers_the_record_then_falls_back_to_humanoid() {
         }),
     );
 
-    // Stage 2: a creature's cached record wins.
     assert_eq!(
         s.eval::<String>(r#"return UnitCreatureType("target")"#)
             .unwrap(),
         "Beast"
     );
-    // Stage 3: a player has no record and falls through to race -> Humanoid.
     assert_eq!(
         s.eval::<String>(r#"return UnitCreatureType("player")"#)
             .unwrap(),
         "Humanoid"
     );
-    // An unresolved TOKEN is nil — not a raise.
+    // An unresolved token is nil; a missing argument fails `lua_isstring` and raises.
     assert!(s
         .eval::<bool>(r#"return UnitCreatureType("party4") == nil"#)
         .unwrap());
-    // A non-string ARGUMENT is a raise, which is a different failure from the nil above:
-    // `lua_isstring` gates it and `luaL_error` longjmps, so a missing arg abandons the statement.
     let err = s
         .run("UnitCreatureType()")
         .expect_err("a missing arg must raise");
@@ -1042,23 +806,13 @@ fn unit_creature_type_answers_the_record_then_falls_back_to_humanoid() {
     );
 }
 
-/// `GetInventorySlotInfo(slotName)` — `0x4c81b0`, three returns and a **case-insensitive**,
-/// full-string name match.
-///
-/// The case-insensitivity is the whole point: two 1.12-era corpus addons died at session start on
-/// case variants of real names — `FuBar_AmmoFu` passes `"ammoSlot"`, `FuBar_PoisonFu`
-/// `"MAINHANDSLOT"` — and both worked on the real client, because `0x4c8215` reaches the CRT
-/// `_strnicmp`, which folds both operands.
-///
-/// The other two assertions are things a plausible implementation gets wrong and nothing notices:
-/// the third return is the **number 1**, only for `RangedSlot`, never a boolean; and a miss
-/// **raises** with the reference's own message, which carries no `Usage:` prefix and does not
-/// interpolate the offending name.
+/// `GetInventorySlotInfo` (`0x4c81b0`) matches the whole name case-insensitively (`0x4c8215`,
+/// `_strnicmp`) and returns three values, the third the number 1 for `RangedSlot` alone; a miss
+/// raises the reference's message, with no `Usage:` and no name.
 #[test]
 fn get_inventory_slot_info_folds_case_and_flags_only_the_ranged_slot() {
     let s = script();
 
-    // The exact spelling, and the two case variants the corpus actually ships.
     for name in ["AmmoSlot", "ammoSlot", "AMMOSLOT"] {
         assert_eq!(
             s.eval::<i64>(&format!("return GetInventorySlotInfo('{name}')"))
@@ -1073,18 +827,14 @@ fn get_inventory_slot_info_folds_case_and_flags_only_the_ranged_slot() {
         16
     );
 
-    // Three values, and the second is the empty-slot background art the paper-doll buttons use.
     assert_eq!(s.arity("GetInventorySlotInfo('HeadSlot')").unwrap(), 3);
     let (id, art) = s
         .eval::<(i64, String)>("return GetInventorySlotInfo('HeadSlot')")
         .unwrap();
     assert_eq!(id, 1);
-    // The DBC string verbatim: LOWERCASE directory and the `.blp` extension. The binding pushes
-    // `[esi+4]` with no normalisation, so a caller that keys a table by this sees these bytes.
+    // The DBC string verbatim, lowercase directory and `.blp`: the binding pushes `[esi+4]` as is.
     assert_eq!(art, "interface\\paperdoll\\UI-PaperDoll-Slot-Head.blp");
 
-    // checkRelic: the NUMBER 1 for the ranged slot alone, nil everywhere else — not `false`, which
-    // is falsey like nil but the wrong type for a caller that compares it against 1.
     assert!(s
         .eval::<bool>("local _,_,r = GetInventorySlotInfo('RangedSlot') return r == 1")
         .unwrap());
@@ -1092,9 +842,8 @@ fn get_inventory_slot_info_folds_case_and_flags_only_the_ranged_slot() {
         .eval::<bool>("local _,_,r = GetInventorySlotInfo('HeadSlot') return r == nil")
         .unwrap());
 
-    // The twelve rows this table was short of — `Bag1`..`Bag12` at SlotNumbers 64..75, of which
-    // 64..69 is the bank-bag band. They share ONE string offset with Bag0Slot..Bag3Slot, so all
-    // sixteen bag rows answer the same art.
+    // `Bag1`..`Bag12` are SlotNumbers 64..75 (64..69 the bank bags) and share one string offset
+    // with `Bag0Slot`..`Bag3Slot`, so all sixteen answer the same art.
     assert_eq!(
         s.eval::<i64>("return GetInventorySlotInfo('Bag1')")
             .unwrap(),
@@ -1113,14 +862,13 @@ fn get_inventory_slot_info_folds_case_and_flags_only_the_ranged_slot() {
             .unwrap(),
         "all sixteen bag rows share one string-block offset"
     );
-    // ...and `Bag1` (64) is NOT `Bag1Slot` (21): different names, different ids, both real rows.
+    // `Bag1` (64) and `Bag1Slot` (21) are different rows.
     assert_eq!(
         s.eval::<i64>("return GetInventorySlotInfo('Bag1Slot')")
             .unwrap(),
         21
     );
 
-    // A miss raises — there is no nil path — with the reference's own string.
     let err = s
         .run("GetInventorySlotInfo('NoSuchSlot')")
         .expect_err("an unknown slot name must raise");
@@ -1135,33 +883,12 @@ fn get_inventory_slot_info_folds_case_and_flags_only_the_ranged_slot() {
     );
 }
 
-/// **The whole Region method map, on both leaves that chain to it.**
-///
-/// `SetParent` above landed as one name because one addon line named it. That is how this table has
-/// always grown, and it is why `GetParent` — its own getter — was still absent while `SetParent`
-/// worked. The reference exposes it as a SET, not as names: FontString's lookup `0x79ee20` chains
-/// its own map `0xcf5400` to the Region map `0xcf54b4`, whose 19 entries are
-///
-/// ```text
-/// GetObjectType IsObjectType GetName GetParent SetParent GetCenter GetLeft GetRight GetTop
-/// GetBottom GetWidth SetWidth GetHeight SetHeight GetNumPoints GetPoint SetPoint SetAllPoints
-/// ClearAllPoints
-/// ```
-///
-/// (the reference's Font lookup `0x7a1100` has no fallback — a `<Font>` object does NOT chain and
-/// so has none of these. Texture reaches the identical map through its own leaf lookup, which is
-/// why both are asserted here.)
-///
-/// So this asserts membership rather than behaviour: each name is *present and callable* on a
-/// Texture and on a FontString. Behaviour belongs in the focused tests around it — what is pinned
-/// here is that the set cannot quietly lose a member again, which is the failure `GetParent` was.
+/// Every Region-map name (`0xcf54b4`, 19 entries) is callable on a Texture and a FontString, whose
+/// lookups fall back to it (FontString's `0x79ee20` chains its own `0xcf5400`); a Font object's
+/// lookup (`0x7a1100`) has no fallback.
 #[test]
 fn every_region_map_method_is_callable_on_a_texture_and_a_fontstring() {
-    /// All 19. `GetObjectType`/`IsObjectType` were held out of this list when 1244 landed the other
-    /// four — dispatched rather than guessed — and joined it once `0x7a11d0`/`0x7a1290` were
-    /// confirmed on the Region map. The list is the whole map again.
-    // The one list, shared with the title region's narrower table (`script::REGION_MAP_METHODS`)
-    // so the two can never disagree about what "the Region map" is.
+    /// All 19, `GetObjectType`/`IsObjectType` (`0x7a11d0`/`0x7a1290`) among them.
     const REGION_MAP: [&str; 19] = crate::script::REGION_MAP_METHODS;
     let mut s = crate::script::UiScript::new().unwrap();
     s.set_screen_size(800.0, 600.0);
@@ -1192,11 +919,8 @@ fn every_region_map_method_is_callable_on_a_texture_and_a_fontstring() {
     );
 }
 
-/// **The four Region-map readers, on the cases a frame-shaped copy gets wrong.**
-///
-/// `TheoryCraftUI.lua:720` is the line that found them: `buttontext:GetParent():GetID()`, where
-/// `buttontext` is a FontString — a working line on the real client, and `attempt to call method
-/// 'GetParent' (a nil value)` here, every session.
+/// The Region-map readers where a region differs from a frame: `GetParent` is the owner frame
+/// (`TheoryCraftUI.lua:720` calls it on a FontString), and `GetPoint` answers a sibling region.
 #[test]
 fn the_region_map_readers_answer_the_way_the_edges_do() {
     let mut s = crate::script::UiScript::new().unwrap();
@@ -1215,7 +939,6 @@ fn the_region_map_readers_answer_the_way_the_edges_do() {
     .unwrap();
     s.resolve();
 
-    // GetParent is the OWNER frame — the identity TheoryCraft then calls :GetID() on.
     assert!(
         s.eval::<bool>("return RRPlate:GetParent() == RRFrame")
             .unwrap(),
@@ -1227,15 +950,13 @@ fn the_region_map_readers_answer_the_way_the_edges_do() {
         "…and it is a real frame handle, not a bare id"
     );
 
-    // GetCenter agrees with the edge readers BY CONSTRUCTION — the invariant that forbids scaling
-    // one and not the others.
+    // GetCenter agrees with the edge readers by construction, so none of them is scaled alone.
     let (cx, cy): (f64, f64) = s.eval("return RRPlate:GetCenter()").unwrap();
     let (l, r, t, b): (f64, f64, f64, f64) = s
         .eval("return RRPlate:GetLeft(), RRPlate:GetRight(), RRPlate:GetTop(), RRPlate:GetBottom()")
         .unwrap();
     assert_eq!((cx, cy), ((l + r) * 0.5, (t + b) * 0.5));
 
-    // GetNumPoints counts what SetPoint wrote, and ClearAllPoints takes it back to 0.
     assert_eq!(s.eval::<i64>("return RRPlate:GetNumPoints()").unwrap(), 1);
     assert_eq!(
         s.eval::<i64>("return RRLabel:GetNumPoints()").unwrap(),
@@ -1243,8 +964,8 @@ fn the_region_map_readers_answer_the_way_the_edges_do() {
         "the sibling-anchored label carries its one point"
     );
 
-    // GetPoint's relativeTo must come back as the SIBLING REGION, not a frame wrapper onto the same
-    // id — the one place regions genuinely differ from frames, since both share an id space.
+    // Frames and regions share an id space, so `relativeTo` must come back as the region handle,
+    // not a frame wrapper onto its id.
     let (p, rp, x, y): (String, String, f64, f64) = s
         .eval("local p, _, rp, x, y = RRLabel:GetPoint(1) return p, rp, x, y")
         .unwrap();
@@ -1254,7 +975,6 @@ fn the_region_map_readers_answer_the_way_the_edges_do() {
             .unwrap(),
         "relativeTo is the sibling REGION handle itself"
     );
-    // Out of range is five nils, like the frame twin.
     assert_eq!(
         s.arity("RRPlate:GetPoint(7)").unwrap(),
         5,
@@ -1266,12 +986,7 @@ fn the_region_map_readers_answer_the_way_the_edges_do() {
     );
 }
 
-/// **`GetObjectType`/`IsObjectType` — every detail confirmed at the bytes, asserted.**
-///
-/// 1244 shipped four Region-map members and left these two out rather than guess them, because each
-/// of the four traps below is a coin-flip a reimplementation loses (1203/1205/1211 are three
-/// records of losing it). This test turns that reading into a gate, so the next person to touch
-/// these has to disagree with the binary rather than with me.
+/// A region's `GetObjectType`/`IsObjectType` (`0x7a11d0`/`0x7a1290`).
 #[test]
 fn the_type_identity_verbs_answer_what_the_binary_answers() {
     let s = crate::script::UiScript::new().unwrap();
@@ -1285,7 +1000,7 @@ fn the_type_identity_verbs_answer_what_the_binary_answers() {
     )
     .unwrap();
 
-    // The leaf names, one value each (`lua_pushstring`, no arity check on extra args).
+    // One value each (`lua_pushstring`); extra arguments are ignored.
     assert_eq!(
         s.eval::<String>("return TITex:GetObjectType()").unwrap(),
         "Texture"
@@ -1300,7 +1015,7 @@ fn the_type_identity_verbs_answer_what_the_binary_answers() {
         "one value, and a stray argument is ignored rather than an arity error"
     );
 
-    // The chain is TWO deep and stops there.
+    // The chain is two deep: the leaf, then Region.
     for (obj, leaf) in [("TITex", "Texture"), ("TIStr", "FontString")] {
         assert_eq!(
             s.eval::<i64>(&format!("return {obj}:IsObjectType('{leaf}')"))
@@ -1314,9 +1029,7 @@ fn the_type_identity_verbs_answer_what_the_binary_answers() {
             1,
             "{obj} is a Region"
         );
-        // **The invented root.** 1.12.1 has no LayoutFrame/ScriptObject/Object type at all — those
-        // strings live only in __FILE__ paths and allocator tags. Knowing later clients is exactly
-        // what would put them here.
+        // 1.12.1 has no LayoutFrame, ScriptObject or Object type at all.
         for absent in ["LayoutFrame", "ScriptObject", "Object", "Frame", "Font"] {
             assert!(
                 s.eval::<Option<i64>>(&format!("return {obj}:IsObjectType('{absent}')"))
@@ -1326,14 +1039,12 @@ fn the_type_identity_verbs_answer_what_the_binary_answers() {
             );
         }
     }
-    // …and the two leaves are not each other.
     assert!(s
         .eval::<Option<i64>>("return TITex:IsObjectType('FontString')")
         .unwrap()
         .is_none());
 
-    // Case-INSENSITIVE and WHOLE-string (SStrCmpI folds both operands; the compare stops at the
-    // first NUL, so no prefix or substring match either).
+    // Case-insensitive and whole-string (`SStrCmpI`).
     for spelling in ["texture", "TEXTURE", "TeXtUrE", "region", "REGION"] {
         assert_eq!(
             s.eval::<i64>(&format!("return TITex:IsObjectType('{spelling}')"))
@@ -1351,7 +1062,6 @@ fn the_type_identity_verbs_answer_what_the_binary_answers() {
         );
     }
 
-    // A hit is the NUMBER 1, never a boolean; a miss is nil. Both paths push exactly one value.
     assert_eq!(
         s.eval::<String>("return type(TITex:IsObjectType('Texture'))")
             .unwrap(),
@@ -1366,8 +1076,7 @@ fn the_type_identity_verbs_answer_what_the_binary_answers() {
         );
     }
 
-    // A NUMBER is accepted (lua_isstring takes tags 4 and 3) and stringified in place — it simply
-    // never matches, because no type name is numeric.
+    // A number passes `lua_isstring` and never matches a type name.
     assert!(
         s.eval::<Option<i64>>("return TITex:IsObjectType(5)")
             .unwrap()
@@ -1375,8 +1084,6 @@ fn the_type_identity_verbs_answer_what_the_binary_answers() {
         "a number argument is accepted and quietly answers nil, NOT a raise"
     );
 
-    // Everything else RAISES with the reference's own Usage text, naming the region — or
-    // `<unnamed>` for one declared anonymously.
     for bad in ["", "nil", "true", "{}", "print"] {
         let err = s
             .run(&format!("TITex:IsObjectType({bad})"))
@@ -1397,19 +1104,8 @@ fn the_type_identity_verbs_answer_what_the_binary_answers() {
     );
 }
 
-/// **`GetFrameType`/`IsFrameType` — 1.12's own names for the pair above, on the FRAME side**
-/// (decision 2106).
-///
-/// The client registers type identity twice: `CScriptRegion` publishes
-/// `GetObjectType`/`IsObjectType` (the test above), and `CSimpleFrameScript.cpp` publishes
-/// `GetFrameType 0x773640` / `IsFrameType 0x773700`. Later clients kept the first pair and dropped
-/// the second; we had shipped only the first, which is the inverse of 1189's usual failure — a
-/// real 1.12 name we were *missing*, not an invented one we offered.
-///
-/// It cost the world map. Cartographer 2.02's `LookNFeel.lua:368` finds the map's player arrow
-/// with `v:GetFrameType() == "Model" and not v:GetName()`; with the verb nil that raised inside
-/// `OnEnable`, AceAddon swallowed it, and every map open then put
-/// `LookNFeel.lua:737: attempt to index field 'playerModel'` on screen.
+/// Frames also carry 1.12's frame-side pair, `GetFrameType 0x773640`/`IsFrameType 0x773700`
+/// (`CSimpleFrameScript.cpp`), beside `CScriptRegion`'s `GetObjectType`/`IsObjectType`.
 #[test]
 fn the_frame_side_type_identity_verbs_are_1_12s_own_names() {
     let s = crate::script::UiScript::new().unwrap();
@@ -1423,8 +1119,7 @@ fn the_frame_side_type_identity_verbs_are_1_12s_own_names() {
     )
     .unwrap();
 
-    // `GetFrameType` reads the same per-class type-name slot `GetObjectType` does (`[edx+0x1c]`),
-    // so the two agree by construction — one value, extra arguments ignored.
+    // Both read the same per-class type-name slot (`[edx+0x1c]`).
     for (obj, leaf) in [
         ("FTFrame", "Frame"),
         ("FTButton", "Button"),
@@ -1443,15 +1138,13 @@ fn the_frame_side_type_identity_verbs_are_1_12s_own_names() {
         );
     }
 
-    // The exact line Cartographer walks the world map with.
+    // How Cartographer's `LookNFeel.lua:368` finds the world map's player arrow.
     assert!(
         s.eval::<bool>(r#"return FTModel:GetFrameType() == "Model" and not FTModel:GetName()"#)
             .unwrap(),
         "an anonymous Model must answer its type AND a nil name — LookNFeel.lua:368"
     );
 
-    // `IsFrameType` walks the same chain: the leaf, every base, the number 1 on a hit and nil on
-    // a miss, case-insensitive and whole-string.
     assert_eq!(
         s.eval::<i64>("return FTButton:IsFrameType('Button')")
             .unwrap(),
@@ -1476,18 +1169,13 @@ fn the_frame_side_type_identity_verbs_are_1_12s_own_names() {
         );
     }
 
-    // A REGION does not get the frame-side pair — the two registrars are distinct, and offering
-    // both names on everything would be the superset 1189 forbids.
+    // A region has no frame-side pair: the two registrars are distinct.
     assert!(s.eval::<bool>("return FTTex.GetFrameType == nil").unwrap());
     assert!(s.eval::<bool>("return FTTex.IsFrameType == nil").unwrap());
 }
 
-/// **The frame side of the type identity, and the three chains a guess gets wrong.**
-///
-/// `_Nameplates.lua` is why this half exists: it asks `Region:GetObjectType()` (the region twin)
-/// AND `Nameplate:GetObjectType() ~= "Button"` / `Frame:GetObjectType() == "StatusBar"` in the same
-/// file. The chains come from the reference's own 23-class roster, which is a hardcoded
-/// straight-line list per class in the binary rather than a runtime parent walk.
+/// A frame's type chain follows the reference's 23-class roster, a hardcoded list per class rather
+/// than a runtime parent walk.
 #[test]
 fn a_frames_type_chain_matches_the_roster() {
     let s = crate::script::UiScript::new().unwrap();
@@ -1495,7 +1183,6 @@ fn a_frames_type_chain_matches_the_roster() {
     let cases: &[(&str, &str, &[&str])] = &[
         ("Frame", "Frame", &["Frame", "Region"]),
         ("Button", "Button", &["Button", "Frame", "Region"]),
-        // Depth 4 — the longest chain we can build.
         (
             "CheckButton",
             "CheckButton",
@@ -1514,14 +1201,13 @@ fn a_frames_type_chain_matches_the_roster() {
             "MessageFrame",
             &["MessageFrame", "Frame", "Region"],
         ),
-        // **NOT via MessageFrame**, despite the name (roster `0x787940`).
+        // Not via MessageFrame, despite the name (roster `0x787940`).
         (
             "ScrollingMessageFrame",
             "ScrollingMessageFrame",
             &["ScrollingMessageFrame", "Frame", "Region"],
         ),
-        // **Capital HTML** — the enum variant is `SimpleHtml`, and `GetObjectType` is compared with
-        // `==` by addons, so a variant-derived string would be silently wrong here.
+        // Capital HTML, unlike the `SimpleHtml` variant; addons compare the string with `==`.
         (
             "SimpleHTML",
             "SimpleHTML",
@@ -1538,10 +1224,9 @@ fn a_frames_type_chain_matches_the_roster() {
             &["GameTooltip", "Frame", "Region"],
         ),
         ("Minimap", "Minimap", &["Minimap", "Frame", "Region"]),
-        // `PlayerModel` derives from `Model`, which is why `SetUnit` on a portrait pane finds
-        // `SetCamera` too (`0x505830`/`0x5057c0`) — and `DressUpModel`
-        // derives from it in turn: the roster's maximum depth, 5 (1969; `TabardModel` is the
-        // other depth-5 chain — built by 1977).
+        // `PlayerModel` derives from `Model` (`0x505830`/`0x5057c0`), so a `SetUnit` portrait pane
+        // has `SetCamera` too; `DressUpModel`, like `TabardModel`, derives from `PlayerModel`: the
+        // roster's maximum depth, 5.
         (
             "PlayerModel",
             "PlayerModel",
@@ -1569,8 +1254,6 @@ fn a_frames_type_chain_matches_the_roster() {
                 "{kind} must be a {want}"
             );
         }
-        // Every OTHER leaf in the roster must be absent from this chain — the assertion that
-        // catches a chain built by "sounds related".
         for (other, other_leaf, _) in cases {
             if chain.contains(other_leaf) {
                 continue;
@@ -1584,8 +1267,6 @@ fn a_frames_type_chain_matches_the_roster() {
         }
     }
 
-    // The frame verbs share the region twin's contract: number 1 / nil, one value, and a raise
-    // naming the frame.
     s.run(r#"TCNamed = CreateFrame("Button", "TCNamed")"#)
         .unwrap();
     assert_eq!(
@@ -1604,16 +1285,8 @@ fn a_frames_type_chain_matches_the_roster() {
     );
 }
 
-/// **Every region method belongs to a leaf — no name may be installed and invisible to both.**
-///
-/// The split (`script::region`) copies names out of the full table into a Texture leaf and a
-/// FontString leaf. A name in neither list is still installed, still costs a closure, and is
-/// reachable from NOTHING — the silent half of a wrong partition.
-///
-/// This is not hypothetical: the partition was first built from a grep, and that grep missed
-/// `SetGradient`/`SetGradientAlpha` because they are installed from a LOOP rather than a literal
-/// `m.set("…")`. One test caught one of them; this gate catches the whole class, and it reads the
-/// table the VM actually holds rather than the source that builds it.
+/// Every name on the full region table the VM holds is in a leaf list: `script::region` copies
+/// names out of it into the Texture and FontString leaves, and one in neither is unreachable.
 #[test]
 fn every_installed_region_method_lands_in_a_leaf() {
     use crate::script::{
@@ -1645,10 +1318,7 @@ fn every_installed_region_method_lands_in_a_leaf() {
     );
 }
 
-/// **The Environment Detail pair — `SetWorldDetail 0x488dd0` / `GetWorldDetail 0x488d70`.**
-///
-/// Every assertion below is a byte read out of `WoW.exe`, not a shape chosen here; decision 2163
-/// carries the carve and `script::cvars::install_world_detail_verbs` the reasoning.
+/// The Environment Detail pair, `SetWorldDetail 0x488dd0`/`GetWorldDetail 0x488d70`.
 #[test]
 fn set_world_detail_writes_the_stop_table_and_validates_like_the_reference() {
     let s = script();
@@ -1679,8 +1349,7 @@ fn set_world_detail_writes_the_stop_table_and_validates_like_the_reference() {
         "the table is the reference's, not a transcription that can drift"
     );
 
-    // **Truncation is toward zero** (`0x40a2b0` forces RC = chop), so a fractional stop floors
-    // toward 0 from both sides — and -0.5 is therefore stop 0, ACCEPTED.
+    // Truncation is toward zero (`0x40a2b0` sets RC = chop), so -0.5 is stop 0 and accepted.
     s.run("SetWorldDetail(2.9)").unwrap();
     assert_eq!(frill(&s).as_deref(), Some("48"));
     s.run("SetWorldDetail(-0.5)").unwrap();
@@ -1690,11 +1359,10 @@ fn set_world_detail_writes_the_stop_table_and_validates_like_the_reference() {
         "-0.5 truncates to 0, which is in range: only <= -1 raises"
     );
 
-    // **`lua_isnumber` accepts a numeric string.**
+    // `lua_isnumber` accepts a numeric string.
     s.run(r#"SetWorldDetail("2")"#).unwrap();
     assert_eq!(frill(&s).as_deref(), Some("48"));
 
-    // Both raise paths, with the reference's own strings.
     for bad in [
         "SetWorldDetail(3)",
         "SetWorldDetail(-1)",
@@ -1719,7 +1387,6 @@ fn set_world_detail_writes_the_stop_table_and_validates_like_the_reference() {
         );
     }
 
-    // Zero return values from the setter; exactly one number from the getter.
     s.run("SetWorldDetail(1)").unwrap();
     assert_eq!(
         s.arity("SetWorldDetail(1)").unwrap(),
@@ -1731,17 +1398,13 @@ fn set_world_detail_writes_the_stop_table_and_validates_like_the_reference() {
         s.eval::<String>("return type(GetWorldDetail())").unwrap(),
         "number"
     );
-    // The getter reads no argument — pfUI declares its replacement `function(arg)` and the stock
-    // one it chains to is called with one.
+    // The getter ignores an argument; pfUI's hook passes one.
     assert_eq!(s.eval::<i64>("return GetWorldDetail(7)").unwrap(), 1);
     assert_eq!(stop(&s).as_deref(), Some("1"));
 }
 
-/// **pfUI's `hdgraphic` module, run against the real bindings.**
-///
-/// The module hooks both verbs and drives `frillDensity` past the panel's top stop; this is that
-/// arm executed verbatim (`modules/hdgraphic.lua` l.4-39), because "the verbs exist" and "the
-/// module works" are different claims and only the second one is the point.
+/// pfUI's `hdgraphic` module (`modules/hdgraphic.lua:4-39`), which hooks both verbs to drive
+/// `frillDensity` past the top stop, run against the bindings.
 #[test]
 fn the_pfui_hdgraphic_extended_arm_runs() {
     let s = script();
@@ -1766,8 +1429,6 @@ fn the_pfui_hdgraphic_extended_arm_runs() {
     )
     .unwrap();
 
-    // The hook's own precondition: `local Hook... = SetWorldDetail` captured a FUNCTION. Before
-    // 2163 both were nil and this line took the module down with it.
     assert_eq!(
         s.eval::<i64>("SetWorldDetail(9); return GetWorldDetail()")
             .unwrap(),
@@ -1779,7 +1440,7 @@ fn the_pfui_hdgraphic_extended_arm_runs() {
         Some("160"),
         "(9+1)*16 — inside the reference's own [1, 256], which is why its range is wider than its slider"
     );
-    // ...and the low arm falls through to the stock getter, which is where a nil hook used to bite.
+    // The low arm falls through to the stock getter.
     assert_eq!(
         s.eval::<i64>("SetWorldDetail(2); return GetWorldDetail()")
             .unwrap(),
@@ -1787,19 +1448,9 @@ fn the_pfui_hdgraphic_extended_arm_runs() {
     );
 }
 
-/// **The four nameplate verbs take no argument and return nothing.**
-///
-/// `ShowNameplates 0x489450` / `HideNameplates 0x489460` / `ShowFriendNameplates 0x489470` /
-/// `HideFriendNameplates 0x489480` — four 10-byte bodies over two setters, differing only in an
-/// `or`/`and` mask.
-///
-/// Both halves of the shape are asserted because both are easy to invent differently:
-///
-/// - **No argument is read.** `ShowNameplates(false)` still shows — there is no `lua_gettop` and
-///   no `lua_toboolean` in any of the four. That is *why* there are four verbs instead of two
-///   taking a flag, and a binding typed `fn(bool)` would reject a call the reference accepts.
-/// - **Zero return values, not nil.** The return-list count is 0, which is observably different
-///   from one nil for a caller that counts.
+/// `ShowNameplates 0x489450`, `HideNameplates 0x489460`, `ShowFriendNameplates 0x489470` and
+/// `HideFriendNameplates 0x489480` read no argument and return nothing: four 10-byte bodies over
+/// two setters, differing only in an `or`/`and` mask.
 #[test]
 fn the_nameplate_verbs_ignore_their_arguments_and_return_nothing() {
     let s = script();
@@ -1814,7 +1465,6 @@ fn the_nameplate_verbs_ignore_their_arguments_and_return_nothing() {
         Some("1")
     );
 
-    // Each verb writes its own bit and leaves the other alone.
     s.run("HideNameplates()").unwrap();
     assert_eq!(
         get(&s, crate::script::CVAR_NAMEPLATE_ENEMIES).as_deref(),
@@ -1836,8 +1486,6 @@ fn the_nameplate_verbs_ignore_their_arguments_and_return_nothing() {
         "...and back the other way"
     );
 
-    // **An argument is accepted and IGNORED.** `ShowNameplates(false)` shows, which is the whole
-    // reason the reference ships four verbs rather than two taking a flag.
     s.run("ShowNameplates(false)").unwrap();
     assert_eq!(
         get(&s, crate::script::CVAR_NAMEPLATE_ENEMIES).as_deref(),
@@ -1849,7 +1497,6 @@ fn the_nameplate_verbs_ignore_their_arguments_and_return_nothing() {
             .unwrap_or_else(|e| panic!("{call} must not raise: {e}"));
     }
 
-    // ZERO return values, not one nil.
     assert_eq!(
         s.arity("ShowNameplates()").unwrap(),
         0,
diff --git a/crates/benilla-ui/src/script/tests/region_map.rs b/crates/benilla-ui/src/script/tests/region_map.rs
index e07037c3..1b3b16e9 100644
--- a/crates/benilla-ui/src/script/tests/region_map.rs
+++ b/crates/benilla-ui/src/script/tests/region_map.rs
@@ -1,15 +1,5 @@
-//! **The Region map is ONE function per name, reached by frames and regions alike** — the
-//! [`crate::script::region_map`] law, and the regression guard for bug B267.
-//!
-//! Its header carries the byte evidence (`Frame ∩ Region = ∅`, parsed out of the two `.data`
-//! method tables). What is pinned here is the two things a reader of the code could not otherwise
-//! check: that the sharing is real *by identity*, and that it stops exactly at the 19.
-//!
-//! The reported symptom this file exists for: Quiver's `Api/Index.wow.lua` opens
-//! `_Height = WorldFrame.GetHeight`, applies it to a Texture and a FontString, and benilla raised
-//! `stale or invalid frame handle` — inside the addon's `VARIABLES_LOADED` handler, four lines
-//! before it published `Quiver.CastPetAction`. The addon's own field was nil at macro time because
-//! the handler never finished, which is what got filed.
+//! The Region map ([`crate::script::region_map`]): one function per name for frames and regions
+//! alike, shared by identity and stopping at the 19.
 
 use crate::script::UiScript;
 
@@ -34,12 +24,7 @@ fn vm() -> UiScript {
     s
 }
 
-/// Every one of the 19 is the **same Lua value** on a Frame, a Texture and a FontString.
-///
-/// Not a stand-in for the behaviour tests below: identity is what makes the pulled-off-method
-/// idiom work *for a method the test author never thought of*. In the client it holds because
-/// Frame's table does not carry any of the 19 and its lookup tail-calls Region's; here it holds
-/// because one function is written into every table that chain reaches.
+/// In the client, Frame's table carries none of the 19 and its lookup tail-calls Region's.
 #[test]
 fn the_region_map_is_one_function_on_every_widget() {
     let s = vm();
@@ -56,12 +41,10 @@ fn the_region_map_is_one_function_on_every_widget() {
     }
 }
 
-/// **The bug, reduced to its four lines.** A method pulled off a frame and applied to a region.
 #[test]
 fn a_method_pulled_off_a_frame_works_on_a_texture_and_a_fontstring() {
     let s = vm();
-    // Quiver's own shape: `Api._Height = WorldFrame.GetHeight`, applied to `r.Icon` (a Texture)
-    // and `r.Label` (a FontString), from a table built at file scope.
+    // Quiver's shape: `Api._Height = WorldFrame.GetHeight`, applied to a Texture and a FontString.
     let (th, sh): (f32, f32) = s
         .eval(
             r#"
@@ -82,13 +65,10 @@ fn a_method_pulled_off_a_frame_works_on_a_texture_and_a_fontstring() {
         .unwrap();
     assert_eq!((tw, sw), (64.0, 50.0));
 
-    // …and the setter half, which is the same split and would have been the next wall.
     s.run("local _SetW = Host.SetWidth _SetW(Tex, 99)").unwrap();
     assert_eq!(s.eval::<f32>("return Tex:GetWidth()").unwrap(), 99.0);
 }
 
-/// The other direction — a method pulled off a **region** and applied to a **frame**. Same one
-/// function, so this cannot be made to work by special-casing the reported direction.
 #[test]
 fn a_method_pulled_off_a_texture_works_on_a_frame() {
     let s = vm();
@@ -102,9 +82,7 @@ fn a_method_pulled_off_a_texture_works_on_a_frame() {
     assert_eq!(kind, "Frame");
 }
 
-/// Each receiver keeps its OWN behaviour behind the shared name — the per-kind arms are not
-/// collapsed into one. `GetObjectType` is the cleanest witness (three different answers), and
-/// `GetParent` is the one whose two arms genuinely differ (a region's owner is never nil).
+/// The shared function keeps a per-kind arm; a region's `GetParent` is its owner, never nil.
 #[test]
 fn one_name_still_dispatches_per_kind() {
     let s = vm();
@@ -115,14 +93,12 @@ fn one_name_still_dispatches_per_kind() {
         (f.as_str(), t.as_str(), g.as_str()),
         ("Frame", "Texture", "FontString")
     );
-    // The region arm answers its OWNER; the frame arm answers nil for a parentless top frame.
     let owner: String = s.eval("return Tex:GetParent():GetName()").unwrap();
     assert_eq!(owner, "Host");
     assert!(s.eval::<bool>("return Host:GetParent() == nil").unwrap());
 }
 
-/// `GetNumPoints` — on the Region map, so **every** widget answers it. The frame arm did not
-/// exist until the map was collapsed to one implementation; the region arm shipped alone.
+/// `GetNumPoints` is on the Region map, so every widget answers it.
 #[test]
 fn get_num_points_answers_on_a_frame_too() {
     let s = vm();
@@ -135,11 +111,8 @@ fn get_num_points_answers_on_a_frame_too() {
     assert_eq!(s.eval::<i64>("return Host:GetNumPoints()").unwrap(), 0);
 }
 
-/// **The negative case, and the control that keeps it honest.** These six look like they belong to
-/// the Region map and do not: Frame, Texture and FontString each register their *own* at different
-/// addresses — Texture `SetAlpha 0x79b580` vs FontString `0x79cb70`, and Frame's own `0x774e90`
-/// twin. So `WorldFrame.Show(someTexture)` fails on the real client, and hoisting them here to make
-/// more addon code work would be the superset decision 1189 had to take back out.
+/// Frame, Texture and FontString each register their own copy of these six (Texture `SetAlpha`
+/// `0x79b580`, FontString's `0x79cb70`, Frame's `0x774e90`), so `WorldFrame.Show(tex)` fails.
 #[test]
 fn the_six_look_alikes_are_not_shared() {
     let s = vm();
@@ -159,8 +132,7 @@ fn the_six_look_alikes_are_not_shared() {
     }
 }
 
-/// A receiver that is not a widget at all raises, and says *why* — the bridge resolves the
-/// receiver before either arm runs, so this error must not be flattened into a generic one.
+/// The bridge resolves the receiver before either arm runs, and its error names the reason.
 #[test]
 fn a_non_widget_receiver_raises_and_names_the_reason() {
     let s = vm();
diff --git a/crates/benilla-ui/src/script/tests/regions.rs b/crates/benilla-ui/src/script/tests/regions.rs
index 390e57d8..d0fe9e05 100644
--- a/crates/benilla-ui/src/script/tests/regions.rs
+++ b/crates/benilla-ui/src/script/tests/regions.rs
@@ -1,10 +1,5 @@
-//! Regions join the anchor layout (decision 0068).
-//!
-//! The smeared-merchant root cause: region `<Size>`/`<Anchors>` used to be dropped — a region either
-//! filled its owner or (with a size) drew centered, and its anchors were ignored. Regions now resolve
-//! through the same leaf math as frames, off their own anchors and their own span; an edge nothing
-//! pins does NOT fall back to the owner's (decision 1664 retired that — the owner supplies scale and
-//! nothing else), because the span is content-derived and a pinned edge plus a span is a rect.
+//! Regions in the anchor layout: they resolve through the frames' leaf math, off their own anchors
+//! and content-derived span; the owner supplies scale, never a fallback edge.
 
 use super::common::script;
 use crate::layout::Rect;
@@ -56,11 +51,8 @@ fn region_texture_anchored_topleft_resolves_exact_rect() {
     );
 }
 
-/// A FontString's implicit extent is its measured TEXT, **floored at one FrameXML unit**
-/// (`CSimpleFontString::GetWidth 0x772930` / `GetHeight 0x772a60` — decision 1664). So a
-/// single-anchored FontString whose measure has not landed is a 1×1 box seated on its anchor,
-/// not a collapse onto the pinned edge and not the owner's rect: the floor is what makes such a
-/// FontString **always resolve**, and it is why the resolver needs no owner-edge fallback at all.
+/// A FontString's extent is its measured text floored at one unit (`GetWidth 0x772930`,
+/// `GetHeight 0x772a60`), so an unmeasured one is a 1x1 box on its anchor.
 #[test]
 fn region_fontstring_span_floors_at_one_unit_until_measured() {
     let mut s = script();
@@ -78,8 +70,7 @@ fn region_fontstring_span_floors_at_one_unit_until_measured() {
     )
     .unwrap();
     s.resolve();
-    // Pending measure: both spans floor at one unit. x runs right from the pinned left (5→6);
-    // a LEFT point pins the y-CENTER only (25), so y is the centre ± half a unit.
+    // Unmeasured: x runs 5..6 from the pinned left; LEFT pins the y centre (25), so y is ±0.5.
     assert_eq!(
         region_text_rect(&s, "Name"),
         Rect::new(24.5, 5.0, 25.5, 6.0)
@@ -98,16 +89,9 @@ fn region_fontstring_span_floors_at_one_unit_until_measured() {
     );
 }
 
-/// `ExhaustionLevelFillBar`'s exact shape, both ways: authored width **0**, one TOPLEFT anchor,
-/// and a `<Color>`.
-///
-/// The colour form installs a real 8×8 texture before any resolve (`0x7700a9` → `0x770360` →
-/// `0x44a900`), so `CSimpleTexture::GetWidth 0x770720` answers **8** for the authored zero and
-/// `combineEdge`'s first leg fires: RIGHT = LEFT + 8, and `assemble 0x767a20` returns 1. Strip the
-/// colour and there is no `CGxTex*` at all — the getter answers `0.0`, both `combineEdge` legs
-/// fail their `span != 0.0` test, and the rect never resolves. Our owner-edge fallback used to
-/// turn that second case into the owner's **full width** (1348's 1024-point white band); it is
-/// gone, so the two cases now differ by 8 points and a rect, exactly as they do on the reference.
+/// `ExhaustionLevelFillBar`'s shape, width 0 and one TOPLEFT anchor: its `<Color>` installs an 8x8
+/// texture (`0x7700a9` → `0x770360` → `0x44a900`), so `GetWidth 0x770720` answers 8; with no art
+/// it answers 0.0, and `assemble 0x767a20` leaves the rect unresolved.
 #[test]
 fn a_zero_width_solid_spans_eight_units_and_its_artless_twin_gets_no_rect() {
     let mut s = script();
@@ -142,11 +126,8 @@ fn a_zero_width_solid_spans_eight_units_and_its_artless_twin_gets_no_rect() {
 
 #[test]
 fn templateless_lua_region_without_anchors_never_draws() {
-    // Decision 1310 (`CreateTexture 0x773a20`): the creation-path implicit
-    // anchor fires from Lua CreateTexture only on a template-registry hit — a templateless region
-    // gets NOTHING, stays rect-less (the resolver has no zero-anchor fallback), and never renders,
-    // its explicit size notwithstanding. This replaced the old draws-centered-at-its-size
-    // fallback, which was refuted at the bytes (it was B180's squashed stack-split dialog).
+    // `CreateTexture 0x773a20` anchors a new texture only on a template hit, so a templateless one
+    // has no anchor, no rect and no draw, whatever its size.
     let mut s = script();
     s.set_screen_size(800.0, 600.0);
     s.run(
@@ -193,11 +174,8 @@ fn region_set_all_points_fills_owner() {
     );
 }
 
-/// A region anchored to a **sibling region by name** resolves against the sibling's rect — the
-/// merchant label-plate shape (`plate LEFT → $parentSlot RIGHT −9`), which the old owner-fallback
-/// mis-anchored to the row's right edge (the jutting-plates bug the director's A/B caught). The
-/// plate is declared BEFORE the slot so only the resolve fixpoint (not declaration order) can
-/// order the chain; the slot itself is region-anchored to the row, one deeper than owner-direct.
+/// A region anchored by name to a sibling declared after it: `MerchantItemTemplate`'s label plate
+/// (`LEFT` to `$parentSlotTexture`'s `RIGHT`, -9, -18), ordered by the resolve alone.
 #[test]
 fn region_anchors_to_sibling_region_by_name() {
     let mut s = script();
@@ -232,7 +210,7 @@ fn region_anchors_to_sibling_region_by_name() {
             .and_then(|q| q.rect)
             .unwrap_or_else(|| panic!("no rect for {name}"))
     };
-    // Slot: row TOPLEFT (100..253, 100..144) → slot at (87, 157)-(151, 93)… y-up: top = 144+13 = 157.
+    // The row's TOPLEFT (100, 144) plus (-13, 13): the slot spans 87..151 by 93..157.
     let slot = rect("RowSlot");
     assert_eq!(
         (slot.left, slot.top),
@@ -240,24 +218,20 @@ fn region_anchors_to_sibling_region_by_name() {
         "slot at row TOPLEFT (-13,13)"
     );
     assert_eq!(slot.right, 151.0);
-    // Plate LEFT anchors to the SLOT's RIGHT (151) − 9 = 142 — NOT the row's right edge (253),
-    // which is where the old owner-fallback shoved it (253 − 9 + 128 = jutting past everything).
+    // The plate's LEFT is the slot's RIGHT (151) - 9 = 142, not the row's right edge (253).
     let plate = rect("RowPlate");
     assert_eq!(plate.left, 142.0, "plate.LEFT = slot.RIGHT − 9");
     assert_eq!(
         plate.right, 270.0,
         "plate spans its 128 width from the slot edge"
     );
-    // The LEFT single-point anchor centers the plate vertically on the target point (y-up):
-    // slot center-y = (93+157)/2 = 125, −18 → 107; ±39.
+    // A LEFT point centres the plate vertically: the slot's centre 125, -18 = 107, ±39.
     assert_eq!((plate.bottom, plate.top), (68.0, 146.0));
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// `SetPortraitTexture(region, unit)` (the live model-bake portrait) binds a Texture region to a unit
-/// token, carried out through [`QuadContent::Texture::portrait_unit`] with no BLP path/color of its
-/// own (the app supplies the off-screen bake). A later `SetTexture` makes it an ordinary texture again,
-/// dropping the binding.
+/// `SetPortraitTexture` binds a Texture to a unit token, carried on the quad as `portrait_unit`
+/// with no path or colour (the app supplies the bake); a later `SetTexture` drops the binding.
 #[test]
 fn set_portrait_texture_binds_unit_token_then_settexture_clears_it() {
     let mut s = script();
@@ -291,7 +265,6 @@ fn set_portrait_texture_binds_unit_token_then_settexture_clears_it() {
     assert_eq!(color, None, "the model bake carries no vertex color");
     assert!(circular, "the frame-ring portrait is the round stencil");
 
-    // SetTexture reverts the region to an ordinary texture — the live-unit binding drops.
     s.run(r#" PFramePortrait:SetTexture("Interface\\Icons\\INV_Misc_QuestionMark") "#)
         .unwrap();
     s.resolve();
@@ -308,9 +281,8 @@ fn set_portrait_texture_binds_unit_token_then_settexture_clears_it() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// `BenillaSetBoothTexture(region, token)` — the paper doll's **square** booth binding (decision
-/// 0208 §5): the same `portrait_unit` carriage as `SetPortraitTexture`, but `circular` stays
-/// false (the model pane samples the body bake edge to edge, no frame ring to mask for).
+/// `BenillaSetBoothTexture`, the paper doll's square booth binding: `SetPortraitTexture`'s
+/// carriage with `circular` false, as the model pane has no ring to mask for.
 #[test]
 fn benilla_set_booth_texture_binds_square() {
     let mut s = script();
@@ -344,13 +316,8 @@ fn benilla_set_booth_texture_binds_square() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The quest-log detail pane's shape (the 0109 look fix): a LONG region anchor chain — the real
-/// client's QuestLogFrame chains ~15 regions deep (title → objectives → obj1..10 → description →
-/// rewards) — with a frame (the reward item button) anchored to the chain's tail. The resolver
-/// must run to a true fixpoint: the old bounded rounds (2 frame × 3 region passes) left links past
-/// ~6 on silent owner-edge fallbacks and dropped the tail-anchored FRAME to the screen origin —
-/// decision 0088 §2's "button anchored to a chained region falls to the screen origin" finding,
-/// which forced every window into invented fixed offsets instead of ref-verbatim chains.
+/// The quest log detail pane's shape: a region anchor chain about 15 deep (title, objectives,
+/// description, rewards) with a frame anchored to its tail, which the resolve runs to a fixpoint.
 #[test]
 fn long_region_chain_resolves_and_a_frame_binds_to_its_tail() {
     let mut s = script();
@@ -402,10 +369,7 @@ fn long_region_chain_resolves_and_a_frame_binds_to_its_tail() {
     );
 }
 
-/// Decision 0088 §2 pinned "a child frame shown at runtime does not draw its own `<Layers>`
-/// FontStrings" — the engine constraint that forced every window FLAT. Re-tested after the
-/// resolver fixpoint (decision 0112): a child frame created and SHOWN at runtime, carrying its own
-/// text + texture regions, must extract both quads at the child's resolved position.
+/// A child frame created and shown at runtime draws its own regions where it resolves.
 #[test]
 fn child_frame_layers_regions_render_after_the_fixpoint() {
     let mut s = script();
@@ -449,11 +413,9 @@ fn child_frame_layers_regions_render_after_the_fixpoint() {
     );
 }
 
-/// `SetAlpha`/`GetAlpha` on a Texture/FontString — the region's *own* alpha, distinct from its
-/// owner frame's. A region draws at `ownAlpha × ownerFrame.alpha`: a single hop to the immediate
-/// owner (`SetAlpha 0x76a690` overwrite-cascades onto child *frames* and only invalidates child
-/// regions). The getter must return the region's value, never the frame's: the ref kit ramps a
-/// texture by reading it back (`CastingBarFlash:SetAlpha(GetAlpha() + step)`).
+/// A region draws at its own alpha times its owner frame's, one hop (`SetAlpha 0x76a690` cascades
+/// onto child frames, not regions), and `GetAlpha` answers its own: stock `CastingBarFrame.lua:133`
+/// ramps `CastingBarFlash` by reading it back.
 #[test]
 fn region_alpha_is_its_own_and_multiplies_the_owner_frames() {
     let mut s = script();
@@ -480,12 +442,10 @@ fn region_alpha_is_its_own_and_multiplies_the_owner_frames() {
     };
     assert_eq!(quad_alpha(&s), 1.0);
 
-    // The region's own alpha alone.
     s.run("tex:SetAlpha(0.5)").unwrap();
     assert_eq!(s.eval::<f32>("return tex:GetAlpha()").unwrap(), 0.5);
     assert_eq!(quad_alpha(&s), 0.5);
 
-    // …times the owner frame's. The frame's SetAlpha does NOT overwrite the region's own value.
     s.run("f:SetAlpha(0.5)").unwrap();
     assert_eq!(
         s.eval::<f32>("return tex:GetAlpha()").unwrap(),
@@ -494,7 +454,6 @@ fn region_alpha_is_its_own_and_multiplies_the_owner_frames() {
     );
     assert_eq!(quad_alpha(&s), 0.25, "0.5 region × 0.5 frame");
 
-    // A hidden region draws nothing regardless of alpha.
     s.run("tex:SetAlpha(1); tex:Hide()").unwrap();
     assert!(
         !s.extract()
@@ -504,14 +463,9 @@ fn region_alpha_is_its_own_and_multiplies_the_owner_frames() {
     );
 }
 
-/// **The texture-colour composition law**: a region's own solid colour is a real *texel*
-/// (`SetTexture(r,g,b,a)` → `0x770360` generates an 8×8 block at `+0xcc`), its vertex colour is a
-/// *separate* slot (`SetVertexColor 0x77f750`, `+0xb8`), and the draw **multiplies** them per
-/// channel, alpha included — it does not replace.
-///
-/// This is the reference `SkillFrame` row trough, verbatim: declared `<Color 1,1,1,0.2>`, then
-/// `SetVertexColor(0, 0, 0.75, 0.5)`'d. It draws at alpha `0.2 × 0.5 = 0.1`. benilla stored ONE
-/// colour slot until this test, which made the second call replace the first and drew it at 0.5.
+/// A solid colour is a texel (`0x770360`, an 8x8 block at `+0xcc`) and the vertex colour a
+/// separate slot (`SetVertexColor 0x77f750`, `+0xb8`); the draw multiplies them, alpha included,
+/// as stock `SkillFrame`'s row trough needs (`SkillFrame.xml:35`, `SkillFrame.lua:158`).
 #[test]
 fn a_solid_colour_texel_multiplies_with_the_vertex_colour() {
     let mut s = script();
@@ -551,15 +505,14 @@ fn a_solid_colour_texel_multiplies_with_the_vertex_colour() {
         Some([0.0, 0.0, 0.75, 0.1]),
         "texel x vertex, alpha included: 0.2 x 0.5 = 0.1, NOT 0.5"
     );
-    // The API readback is the vertex slot itself, not the product — the two are distinct storage.
+    // `GetVertexColor` reads the vertex slot, not the product.
     assert_eq!(
         s.eval::<(f32, f32, f32, f32)>("return trough:GetVertexColor()")
             .unwrap(),
         (0.0, 0.0, 0.75, 0.5)
     );
 
-    // Art and a solid colour share the `+0xcc` slot: setting a path releases the generated texel,
-    // and what is left is the tint alone for the renderer to modulate the sample by.
+    // Art and a solid colour share `+0xcc`: a path releases the texel and leaves the tint.
     s.run(r#"trough:SetTexture("Interface\\Bar.blp")"#).unwrap();
     let tinted = s
         .extract()
@@ -580,14 +533,8 @@ fn a_solid_colour_texel_multiplies_with_the_vertex_colour() {
     );
 }
 
-/// **`SetDesaturated` rides the extract, and only against real ART** (decision 1327).
-///
-/// The state was stored from the day the verb landed and read by nobody, which is why every
-/// greyed-out affordance in the UI was a brightness tint (B162's talent tree). The flag now travels
-/// on the quad, so this pins the two ends of that wire — set/clear — plus the one carve-out: a
-/// PATHLESS solid has its colour folded into the quad's tint and draws against a 1x1 white texel,
-/// so a shader that greys the texel would grey white and change nothing. Carrying the flag there
-/// would read as honoured while doing nothing at all, so extract drops it.
+/// The desaturate flag rides an art quad only: a pathless solid draws its colour as the quad's tint
+/// over a white texel, which greying leaves white, so extract drops the flag there.
 #[test]
 fn desaturation_rides_the_extract_for_art_and_never_for_a_solid() {
     let mut s = script();
@@ -628,17 +575,12 @@ fn desaturation_rides_the_extract_for_art_and_never_for_a_solid() {
         "a pathless solid never carries it — greying a white texel is a no-op dressed as a feature"
     );
 
-    // And it clears — the reference's own `SetItemButtonDesaturated(button, nil)` restore.
     s.run("art:SetDesaturated(nil)").unwrap();
     assert!(!grey(&s, true), "clearing the flag restores full colour");
 }
 
-/// Read a Texture region's desaturation state straight off the model, by name.
-///
-/// It has no getter in Lua on purpose — `IsDesaturated` (`0x79c2c0`) exists, but its return shape
-/// is unconfirmed, and inventing one to make a test convenient is how an unverified API
-/// gets shipped (decision 1327's own residual). The extract quad is the other way to see it, but a
-/// cleared texture emits no quad at all, which is exactly the case these tests need to observe.
+/// A Texture region's desaturation state, read off the model by name: `IsDesaturated`
+/// (`0x79c2c0`) is not built, and a cleared texture emits no quad to read it from.
 fn desaturated(s: &UiScript, name: &str) -> bool {
     let lua = s.lua();
     let model = lua.app_data_ref::<crate::script::Model>().expect("model");
@@ -647,15 +589,8 @@ fn desaturated(s: &UiScript, name: &str) -> bool {
     model.region_data.get(&h).is_some_and(|d| d.desaturated)
 }
 
-/// **`SetTexture` clears the desaturation — except when the path does not actually change**
-/// (decision 1330).
-///
-/// `+0x128` is a `CGxShader*`, and `CSimpleTexture::SetTexture` writes it from a shader index the
-/// Lua binding always passes as slot 0 (permanently NULL). Storing a desaturate boolean *beside*
-/// the texture handle — which is what benilla did on 1327 — diverges on the single most common
-/// FrameXML shape there is: a repaint that re-sets the icon and expects the grey to follow the art.
-/// The same-path early-out (`0x770225`) is what makes the *idempotent* repaint keep its grey, and
-/// it is the half a plausible implementation drops.
+/// The desaturation is the shader slot `+0x128`, which `CSimpleTexture::SetTexture` rewrites with
+/// the binding's always-NULL slot 0, except that the same path returns early (`0x770225`).
 #[test]
 fn set_texture_clears_desaturation_unless_the_path_is_unchanged() {
     let s = script();
@@ -670,34 +605,28 @@ fn set_texture_clears_desaturation_unless_the_path_is_unchanged() {
     .unwrap();
     let grey = |s: &UiScript| desaturated(s, "ClrIcon");
 
-    // The idempotent repaint: same file, so the client returns before it can clear anything.
     s.run(r#"icon:SetTexture("Interface\\Icons\\Spell_Nature_Sleep")"#)
         .unwrap();
     assert!(grey(&s), "re-setting the SAME art keeps the grey");
 
-    // A different file reaches the write and zeroes the slot.
     s.run(r#"icon:SetTexture("Interface\\Icons\\Spell_Fire_Fireball")"#)
         .unwrap();
     assert!(!grey(&s), "a texture CHANGE clears the desaturation");
 
-    // The clear forms take the same leg (`test esi,esi` falls through to the write).
+    // nil takes the same leg (`test esi,esi` falls through to the write).
     s.run("icon:SetDesaturated(1) icon:SetTexture(nil)")
         .unwrap();
     assert!(!grey(&s), "SetTexture(nil) clears it too");
 
-    // The COLOUR form is a different function (`0x770360`) and is not one of the field's writers.
+    // The colour form (`0x770360`) does not write the shader slot.
     s.run(r#"icon:SetTexture("Interface\\Icons\\Spell_Nature_Sleep") icon:SetDesaturated(1)"#)
         .unwrap();
     s.run("icon:SetTexture(1, 0, 0)").unwrap();
     assert!(grey(&s), "the colour form does not touch the shader slot");
 }
 
-/// **`SetDesaturated`'s argument truth table has two arms that read backwards**
-/// (`0x6f1c10`'s jump table; decision 1330).
-///
-/// `0x6f1c10(L, 2, default=1)` takes its DEFAULT on `LUA_TNONE`, so a bare `SetDesaturated()` greys
-/// — the opposite of the `if flag then` an implementation writes without looking. And a number is
-/// truncated to an int, so `SetDesaturated(0)` clears where truthiness would have greyed.
+/// `SetDesaturated` reads its flag with `0x6f1c10(L, 2, default=1)`: no argument (`LUA_TNONE`)
+/// greys, and a number is truncated to an int, so 0 and 0.5 clear.
 #[test]
 fn set_desaturated_takes_the_clients_argument_truth_table() {
     let s = script();
@@ -705,7 +634,6 @@ fn set_desaturated_takes_the_clients_argument_truth_table() {
         .unwrap();
     let grey = |s: &UiScript| desaturated(s, "ArgTex");
 
-    // NO ARGUMENT is ON — the LUA_TNONE default arm, not the nil arm.
     s.run("ArgTex:SetDesaturated()").unwrap();
     assert!(
         grey(&s),
@@ -715,26 +643,20 @@ fn set_desaturated_takes_the_clients_argument_truth_table() {
     s.run("ArgTex:SetDesaturated(nil)").unwrap();
     assert!(!grey(&s), "nil clears");
 
-    // A number truncating to zero clears; a non-zero one greys.
     s.run("ArgTex:SetDesaturated(1) ArgTex:SetDesaturated(0)")
         .unwrap();
     assert!(!grey(&s), "0 clears — the number arm truncates to int");
     s.run("ArgTex:SetDesaturated(0.5)").unwrap();
     assert!(!grey(&s), "0.5 truncates to 0 and clears");
 
-    // Both booleans, and Dewdrop's `true` (the call 98 corpus addons reach).
     s.run("ArgTex:SetDesaturated(true)").unwrap();
     assert!(grey(&s), "true greys");
     s.run("ArgTex:SetDesaturated(false)").unwrap();
     assert!(!grey(&s), "false clears");
 }
 
-/// The draw gate is the TEXTURE slot, never the colour: `0x7706e0` tests `+0xcc` and emits NOTHING
-/// when it is empty, whatever the vertex colour holds. Since the tint deliberately survives
-/// `SetTexture(nil)` ("a tint outlives the art it was tinting"), a cleared region used to leak its
-/// tint out of extract as a solid plate — an occupied action button going empty on a character
-/// switch drew its surviving 1/1/1 usable-tint as a solid WHITE square (decision 1108; the
-/// 2026-07-10 grey wells were the same class).
+/// The draw gate is the texture slot, never the colour: `0x7706e0` emits nothing when `+0xcc` is
+/// empty, though the tint survives `SetTexture(nil)`.
 #[test]
 fn a_vertex_colour_without_a_texture_draws_nothing() {
     let mut s = script();
@@ -762,7 +684,6 @@ fn a_vertex_colour_without_a_texture_draws_nothing() {
     };
     assert_eq!(drawn(&s), 1, "tinted art draws");
 
-    // The slot empties: the art clears, the tint stays (distinct storage) — and nothing draws.
     s.run("icon:SetTexture(nil)").unwrap();
     assert_eq!(
         s.eval::<(f32, f32, f32, f32)>("return icon:GetVertexColor()")
@@ -777,21 +698,8 @@ fn a_vertex_colour_without_a_texture_draws_nothing() {
     );
 }
 
-/// **`SetTexture` ignores arguments past the path**, because the client's does.
-///
-/// The path form reads ONE argument (`0x770200`); only the colour form (`0x770360`) reads up to
-/// four, and a C function takes what it wants off the Lua stack and ignores the rest. We typed the
-/// trailing three as `Option<f32>` and so RAISED on a stray extra — `bad argument #3: error
-/// converting Lua boolean to f32` — where the client silently accepts.
-///
-/// The live case is `_LazyPig/LazyPigMenu.lua:182`:
-/// `texture_title:SetTexture("Interface\DialogFrame\UI-DialogBox-Header", true)`. The `true` is
-/// meaningless in 1.12; the addon reached us only once the survey began seating the addon registry.
-///
-/// Asserted as "does not raise", which is the whole claim — there is no `GetTexture` binding to read
-/// the path back through, and inventing one to satisfy a test would be the tail wagging the dog.
-/// The colour form is exercised alongside so the fix cannot have made it lax: a non-numeric channel
-/// must take the same default a missing one does, exactly as `lua_tonumber` of a non-number is 0.
+/// `SetTexture`'s path form reads one argument (`0x770200`) and its colour form up to four
+/// (`0x770360`), ignoring the rest; a non-numeric channel reads as `lua_tonumber` reads it, 0.
 #[test]
 fn set_texture_ignores_arguments_past_the_path_like_the_client_does() {
     let s = script();
@@ -804,25 +712,15 @@ fn set_texture_ignores_arguments_past_the_path_like_the_client_does() {
     )
     .expect("a stray extra argument must not raise — the client ignores it");
 
-    // The colour form, with a boolean and a numeric string among the channels.
     s.run("t:SetTexture(0.25, '0.5', true)")
         .expect("the colour form must tolerate what lua_tonumber tolerates");
 
-    // And the ordinary shapes still work.
     s.run("t:SetTexture(nil) t:SetTexture('') t:SetTexture(1, 0, 0, 1)")
         .expect("clear, blank and the plain colour form are unaffected");
 }
 
-/// **`SetGradientAlpha` / `SetGradient` exist, store both stops, and paint.**
-///
-/// These were the single wall in front of the corpus's largest family: `FuBar\FuBar_Panel.lua:144`
-/// calls `SetGradientAlpha` while building the bar, so all 20 FuBar plugins died there — right after
-/// the chunk-name/`debugstack` fix got them that far.
-///
-/// Asserted on the region PAINTING (a gradient-only region must emit a quad, because the client
-/// generates the gradient into the same texture slot the colour form fills) and on the midpoint
-/// being what a one-tint quad shows. The full gradient stays on the region for a renderer that
-/// grows a second stop.
+/// A gradient fills the texture slot the colour form fills, so a gradient-only region paints;
+/// both stops are stored, and the quad paints their midpoint, not the gradient.
 #[test]
 fn a_gradient_is_stored_whole_and_painted_as_its_midpoint() {
     let mut s = script();
@@ -850,7 +748,7 @@ fn a_gradient_is_stored_whole_and_painted_as_its_midpoint() {
         "a region carrying only a gradient must paint, at the midpoint of its two stops"
     );
 
-    // The alpha-less twin: both stops opaque, and a non-"VERTICAL" token is horizontal.
+    // Any orientation token but "VERTICAL" is horizontal.
     s.run("t:SetGradient('HORIZONTAL', 1, 0, 0, 0, 0, 1)")
         .expect("SetGradient takes six colour arguments and no alpha");
     s.resolve();
@@ -865,11 +763,8 @@ fn a_gradient_is_stored_whole_and_painted_as_its_midpoint() {
     );
 }
 
-/// **The split itself: a Texture answers texture verbs and NOT text ones, and vice versa.**
-///
-/// Until this landed, one shared table meant a Texture answered `SetText` and a FontString answered
-/// `SetTexture` — a superset in both directions (Texture's map `0x87c128` is 22 entries,
-/// FontString's `0xcf5400` is 32, both tail-calling the Region map and stopping there).
+/// Texture's map (`0x87c128`, 22 entries) and FontString's (`0xcf5400`, 32) each answer their own
+/// verbs, then fall back to the Region map and stop there.
 #[test]
 fn the_two_region_leaves_answer_their_own_maps() {
     let s = crate::script::UiScript::new().unwrap();
@@ -887,8 +782,7 @@ fn the_two_region_leaves_answer_their_own_maps() {
             == "function"
     };
 
-    // Texture-only, and an asymmetry worth noting: `SetVertexColor` is on BOTH leaves while
-    // `GetVertexColor` is Texture-only. No reasonable partition invents that.
+    // Texture-only; `GetVertexColor` is here though `SetVertexColor` is on both leaves.
     for m in [
         "SetTexture",
         "GetTexture",
@@ -902,8 +796,7 @@ fn the_two_region_leaves_answer_their_own_maps() {
         assert!(has(&s, "Tex", m), "a Texture answers {m}");
         assert!(!has(&s, "Str", m), "a FontString must NOT answer {m}");
     }
-    // `SetRotation` is 1.12's PLAYERMODEL verb (`0x84f1fc`/`0x505f00`), not a region one — it is in
-    // neither leaf map, and ours used to put it on Texture.
+    // `SetRotation` is 1.12's PlayerModel verb (`0x84f1fc`/`0x505f00`), in neither leaf map.
     for leaf in ["Tex", "Str"] {
         assert!(
             !has(&s, leaf, "SetRotation"),
@@ -921,8 +814,7 @@ fn the_two_region_leaves_answer_their_own_maps() {
         assert!(has(&s, "Str", m), "a FontString answers {m}");
         assert!(!has(&s, "Tex", m), "a Texture must NOT answer {m}");
     }
-    // On BOTH — and each leaf registers its own copy in the client, so these are NOT on the Region
-    // map and must not be hoisted into it.
+    // On both leaves, each registering its own copy, so not on the Region map.
     for m in [
         "SetVertexColor",
         "SetAlpha",
@@ -936,19 +828,13 @@ fn the_two_region_leaves_answer_their_own_maps() {
             "{m} is on both leaves"
         );
     }
-    // The Region map reaches both, through each leaf's own fallback.
     for m in crate::script::REGION_MAP_METHODS {
         assert!(
             has(&s, "Tex", m) && has(&s, "Str", m),
             "{m} is the Region map"
         );
     }
-    // **`GetStringHeight` is GONE and must stay gone.** 1.12 has no such method on any table (0
-    // hits in every encoding; the control `GetStringWidth` has 1), Blizzard's own FrameXML calls it
-    // 0 times, and ours was a byte-identical duplicate of `GetHeight` — which is the method the
-    // reference itself uses for this, falling through to the same cached measurement
-    // `GetStringWidth` reads. Keeping the width and dropping the height is not an oversight: the
-    // client really is asymmetric here.
+    // 1.12 has no `GetStringHeight` on any table; `GetHeight` reads the same measurement.
     assert!(
         !has(&s, "Str", "GetStringHeight"),
         "1.12 has no GetStringHeight"
@@ -967,12 +853,8 @@ fn the_two_region_leaves_answer_their_own_maps() {
     assert!(has(&s, "Str", "SetAlphaGradient") && !has(&s, "Tex", "SetAlphaGradient"));
 }
 
-/// **`SetPortraitToTexture` is a GLOBAL in 1.12, not a Texture method.**
-///
-/// `reference/1.12-globals.tsv` marks it `engine`, and both of the reference's own call sites pass a
-/// texture NAME: `ContainerFrame.lua:419` and `MailFrame.lua:174`. The first is the one that binds
-/// us — we SOURCE `ContainerFrame.lua` off the patch chain, so the client's own file calls this
-/// global inside our VM.
+/// `SetPortraitToTexture` is a 1.12 global, not a Texture method; stock `ContainerFrame.lua:419`
+/// and `MailFrame.lua:174` pass it a texture name.
 #[test]
 fn set_portrait_to_texture_is_a_global_taking_a_name() {
     let s = crate::script::UiScript::new().unwrap();
@@ -988,33 +870,23 @@ fn set_portrait_to_texture_is_a_global_taking_a_name() {
         s.eval::<String>("return Port:GetTexture()").unwrap(),
         "Interface\\ContainerFrame\\KeyRing-Bag-Icon"
     );
-    // The Texture METHOD is gone — 1.12's Texture map has no such entry.
     assert_eq!(
         s.eval::<String>("return type(Port.SetPortraitToTexture)")
             .unwrap(),
         "nil",
         "1.12 has no Texture:SetPortraitToTexture — it is a global"
     );
-    // An unknown name is not an error: the reference's callers compose names that may not exist
-    // yet, and nothing here may raise on the sourced file's behalf.
+    // An unknown name does not raise here; the reference raises "Couldn't find texture named"
+    // (`0x48d7db`).
     s.run(r#"SetPortraitToTexture("NoSuchPortrait", "Interface\\X")"#)
         .unwrap();
     assert!(s.errors().is_empty());
 }
 
-/// **`Region:GetWidth`/`GetHeight` are the VIRTUAL getters** — the same content-derived law the
-/// rect resolver calls, because the Lua bindings dispatch through the same geometry-vtable slots
-/// (`GetWidth 0x7a1e00` ends `ff 52 1c`, `GetHeight 0x7a2030` ends `ff 52 20`; decision 1670).
-///
-/// Both halves of the FontString row, each of which we had backwards:
-///
-/// * the **authored** value wins per axis — `0x772930`'s `jp 0x77294a` skips the measure entirely
-///   when the authored width is not `0.0`, so `<Size x="300" y="0"/>` reports 300 from the author
-///   and the height from the text (`CharacterNameText` is exactly that, in the reference's own
-///   file), where we used to report the 37-point measure;
-/// * on an axis authored `0` the **width** is the NATURAL, unwrapped extent — the very cell
-///   `GetStringWidth` returns (`0x772890`'s `[fs+0xfc]`) — while the **height** is the *wrapped*
-///   one (`0x7729b0`'s `[fs+0x100]`). We used to report the laid-out width for both.
+/// `Region:GetWidth`/`GetHeight` (`0x7a1e00`/`0x7a2030`) call the virtual size getters the rect
+/// resolver uses: a FontString's authored axis wins (`0x772930` skips the measure, `jp 0x77294a`),
+/// else its width is the unwrapped extent `GetStringWidth` reads (`0x772890`, `[fs+0xfc]`) and its
+/// height the wrapped one (`0x7729b0`, `[fs+0x100]`).
 #[test]
 fn the_size_getters_take_the_author_first_then_the_natural_width_and_wrapped_height() {
     let mut s = script();
@@ -1051,12 +923,8 @@ fn the_size_getters_take_the_author_first_then_the_natural_width_and_wrapped_hei
     assert!(s.take_errors().is_empty());
 }
 
-/// The floor, and the state the reference does not have. `0x772930`/`0x772a60` end in a one-unit
-/// clamp, so a genuinely empty string reads back **1**, never `0.0`. But a measure that has not
-/// LANDED is not an extent at all — it is the host round-trip a VM with **no measurer installed**
-/// still takes, which the reference has no equivalent of. A caller that guards
-/// `if h <= 0 then return end` reads that zero as "not yet"; flooring it would tell them to stop
-/// waiting. So: floor a known extent, not the absence of one.
+/// `0x772930`/`0x772a60` clamp to one unit, so an empty string reads 1. A host measure still in
+/// flight, a state the reference does not have, reads 0, so an `if h <= 0` guard keeps waiting.
 #[test]
 fn an_empty_string_reads_back_one_unit_and_a_pending_measure_reads_back_zero() {
     let mut s = script();
@@ -1078,10 +946,8 @@ fn an_empty_string_reads_back_one_unit_and_a_pending_measure_reads_back_zero() {
     assert!(s.take_errors().is_empty());
 }
 
-/// A TEXTURE's getters are the same virtual law with the other override behind them
-/// (`0x770720`/`0x770790`): the authored value when it is not exactly `0.0`, else the art's own
-/// texel extent, else `0.0` — and **no floor**, which only the FontString override carries. This
-/// is the getter half of 1662; before it, Lua saw `0` for a size the screen was already drawing.
+/// A Texture's size getters (`0x770720`/`0x770790`): the authored value unless exactly `0.0`, else
+/// the art's texel extent, else `0.0`, with no floor.
 #[test]
 fn a_textures_getters_report_its_texel_span_on_an_unsized_axis() {
     let mut s = script();
@@ -1106,21 +972,12 @@ fn a_textures_getters_report_its_texel_span_on_an_unsized_axis() {
     assert!(s.take_errors().is_empty());
 }
 
-/// **The three constructors' string arguments are FOUR different shapes, not one rule.**
-///
-/// The discriminator is **not** the argument's type — it is whether the binding *tests* its
-/// parser's return:
-///
-/// | position | fetch | a table there | a number there |
-/// |---|---|---|---|
-/// | `CreateFontString`/`CreateTexture` `name`, `layer` | `0x6f3510` → `0x6f3690`, untested | absent | **accepted, stringified** |
-/// | `CreateFontString`/`CreateTexture` `inherits` | raw `lua_type == LUA_TSTRING`, no coercion | ignored | **ignored** |
-/// | `CreateFrame` `name`, `inherits` | `0x6f3690` **unguarded** | absent | **accepted, stringified** |
-/// | `CreateFrame` `kind` | `0x6f3510`, tested | **raises** | accepted |
-///
-/// The last two rows are the same value taking opposite paths from argument order alone:
-/// `CreateFrame` coerces at `0x70613f` *before* its `cmp 4`, and `0x6f7cb1` retags the number's
-/// stack slot **in place**, so a number arrives at the gate already a string.
+/// The constructors' string arguments take four shapes, by whether the binding tests its parser's
+/// return: a region constructor's `name` and `layer` (`0x6f3510` → `0x6f3690`, untested) and
+/// `CreateFrame`'s `name` and `inherits` (`0x6f3690`, unguarded) read a table as absent and
+/// stringify a number; a region constructor's `inherits` (a raw `lua_type == LUA_TSTRING`) ignores
+/// both; `CreateFrame`'s `kind` (`0x6f3510`, tested) raises on a table and takes a number, which
+/// `CreateFrame` coerces in place before its gate (`0x70613f`, `0x6f7cb1`).
 #[test]
 fn the_constructors_string_arguments_are_four_shapes_not_one() {
     let mut s = script();
@@ -1128,10 +985,7 @@ fn the_constructors_string_arguments_are_four_shapes_not_one() {
     s.run(r#"host = CreateFrame("Frame", "ArgHost", UIParent)"#)
         .unwrap();
 
-    // ── pfUI's line, verbatim. `f.buffs[i]:CreateFontString(nil, "OVERLAY", f.buffs[i])` passes
-    //    the BUTTON as `inheritsFrom`. The real client constructs it, ignores the argument, and
-    //    logs nothing — this raised `bad argument #4` until 2026-08-30 and stopped pfUI, and with
-    //    it pfQuest, pfQuest-turtle and ShaguDPS.
+    // ── A table in `inherits` is ignored and the string still built; pfUI passes a button there.
     s.run(r#"fs = ArgHost:CreateFontString(nil, "OVERLAY", ArgHost)"#)
         .unwrap_or_else(|e| panic!("a table in `inherits` must be ignored, not raise: {e}"));
     assert_eq!(
@@ -1139,7 +993,6 @@ fn the_constructors_string_arguments_are_four_shapes_not_one() {
         "table",
         "...and the FontString is really constructed"
     );
-    // Every other non-string in every region-constructor position: also silent, also constructed.
     for pos in ["{}, \"OVERLAY\"", "nil, {}", "true, false"] {
         for ctor in ["CreateFontString", "CreateTexture"] {
             s.run(&format!("r = ArgHost:{ctor}({pos})"))
@@ -1148,15 +1001,14 @@ fn the_constructors_string_arguments_are_four_shapes_not_one() {
         }
     }
 
-    // ── A NUMBER is a string to `lua_isstring` — so it NAMES the region.
+    // ── A number passes `lua_isstring`, so it names the region.
     s.run("named = ArgHost:CreateTexture(4242)").unwrap();
     assert_eq!(
         s.eval::<String>("return named:GetName()").unwrap(),
         "4242",
         "a number in `name` is stringified, not dropped"
     );
-    // ...but NOT in `inherits`, whose gate reads the raw tag and never coerces. A number there is
-    // ignored, where the same number in CreateFrame's fourth argument would raise.
+    // `inherits` reads the raw tag, so a number there is ignored.
     s.run("ArgHost:CreateTexture(nil, nil, 5)")
         .unwrap_or_else(|e| panic!("a number in a region ctor's `inherits` is ignored: {e}"));
 
@@ -1167,21 +1019,15 @@ fn the_constructors_string_arguments_are_four_shapes_not_one() {
         "77",
         "CreateFrame reads `name` through an UNGUARDED lua_tostring"
     );
-    // ...and an unresolvable `inherits` still raises, which is the pre-existing contract and the
-    // control for the changes above: loosening the OTHER positions must not have loosened this.
     assert!(
         s.run(r#"CreateFrame("Frame", nil, nil, "NoSuchTemplateAnywhere")"#)
             .is_err(),
         "an unresolvable template name still raises — the miss branch is luaL_error"
     );
 
-    // ── The layer argument is PERMISSIVE, and an unrecognised one is ARTWORK, not an error.
-    //    `0x6f18b0` returns 0 with its out-param unwritten and neither constructor reads the
-    //    result, so the pre-staged ARTWORK (2) stands. Matching is case-insensitive.
+    // ── The layer: case-insensitive, and an unrecognised one leaves the pre-staged ARTWORK.
     s.run(r#"lay = ArgHost:CreateTexture(nil, "not-a-layer")"#)
         .unwrap_or_else(|e| panic!("an unrecognised layer must not raise: {e}"));
-    // Read off the arena — 1.12 publishes no `GetDrawLayer`, so there is no Lua getter to ask,
-    // the same reason the sequence scrub is read this way in `modelframe`'s tests.
     let layer_of = |s: &UiScript, name: &str| {
         let lua = s.lua();
         let model = lua.app_data_ref::<crate::script::Model>().expect("model");
@@ -1209,12 +1055,9 @@ fn the_constructors_string_arguments_are_four_shapes_not_one() {
     );
 }
 
-/// The token is CANONICAL on the way out — `"NPC"`, which the stock merchant, guild registrar
-/// and trade windows all write (`MerchantFrame.lua:68`, `GuildRegistrarFrame.lua:4`,
-/// `TradeFrame.lua:41`), binds as `"npc"`. The reference resolves every unit token
-/// case-insensitively (`0x515970`'s ten compares are all `_strnicmp`), and the app samples the
-/// booth by this exact string — a raw `"NPC"` matched no slot and left the ring empty on all
-/// three windows (decision 2022).
+/// `SetPortraitTexture` lowercases the token, which the app matches exactly: the reference reads
+/// unit tokens case-insensitively (`0x515970`, `_strnicmp`), and stock `MerchantFrame.lua:68`
+/// passes `"NPC"`.
 #[test]
 fn set_portrait_texture_folds_the_token_to_lowercase() {
     let mut s = script();
@@ -1243,31 +1086,9 @@ fn set_portrait_texture_folds_the_token_to_lowercase() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **`FontString:GetText` substitutes nil for an EMPTY string, and that substitution is the
-/// getter's own** — `0x79d690` reads the cell, and eleven bytes before the pushstring it does a
-/// FIRST-BYTE test and zeroes the pointer on `'\0'`:
-///
-/// ```text
-/// 79d735 test eax,eax / je 0x79d740     ; NULL      -> substitute
-/// 79d73b cmp byte ptr [eax],0x0         ; the first-byte test
-/// 79d73e jne 0x79d742                   ; non-empty -> keep
-/// 79d740 xor eax,eax                    ; EMPTY     -> NULL
-/// 79d746 call 0x6f3890                  ; NULL -> pushnil
-/// ```
-///
-/// So it cannot return `""`, whatever the cell holds — and the cell really does hold non-NULL
-/// empty strings, because `SetText 0x771d80` never writes NULL to `+0xf0` on any leg: NULL and
-/// `""` share one leg that truncates the buffer in place. Per binding, not per family:
-/// `Button:GetText 0x780e10` carries the same substitution (`0x780ec5`), `EditBox:GetText
-/// 0x7985c0` carries none (decision 2110).
-///
-/// The director's shape (Cartographer 2.02, the world map's hover label): the stock
-/// `WorldMapFrameAreaDescription` is blanked with `SetText("")` by `WorldMapPOI_OnEnter`/`_OnLeave`
-/// on **every** POI hover, and Cartographer's ZoneInfo reads
-/// `if WorldMapFrameAreaDescription:GetText() then` as "this POI has a status line, so put the
-/// zone's level range there instead of on the label". Answering `""` made that true forever after
-/// the first POI touch — the name lost its faction colour, the range moved to the description's own
-/// line beneath it, and nothing ever cleared it again.
+/// `FontString:GetText` (`0x79d690`) pushes nil for an empty string by a first-byte test
+/// (`0x79d73b`), though `SetText 0x771d80` keeps an empty buffer; `Button:GetText 0x780e10` does
+/// the same (`0x780ec5`), and `EditBox:GetText 0x7985c0` returns `""`.
 #[test]
 fn an_empty_fontstring_reads_back_nil_and_an_edit_box_does_not() {
     let s = script();
@@ -1284,15 +1105,12 @@ fn an_empty_fontstring_reads_back_nil_and_an_edit_box_does_not() {
             .unwrap()
     };
 
-    // Never written, and every shape of an empty write, all nil.
     assert_eq!(text_of(&s, "fresh"), None);
     for write in [r#"fresh:SetText("")"#, r#"fresh:SetText(nil)"#] {
         s.run(write).unwrap();
         assert_eq!(text_of(&s, "fresh"), None, "after `{write}`");
     }
 
-    // A string that HAS held text still reads nil once blanked — the substitution is the getter's,
-    // so it does not matter that the cell keeps a (truncated) buffer.
     s.run(r#"held:SetText("In Conflict")"#).unwrap();
     assert_eq!(text_of(&s, "held").as_deref(), Some("In Conflict"));
     s.run(r#"held:SetText("")"#).unwrap();
@@ -1304,7 +1122,7 @@ fn an_empty_fontstring_reads_back_nil_and_an_edit_box_does_not() {
     s.run(r#"held:SetText("back"); held:SetText(nil)"#).unwrap();
     assert_eq!(text_of(&s, "held"), None);
 
-    // Button:GetText carries the SAME substitution; Button:SetText(nil) is its own no-op guard.
+    // `Button:SetText(nil)` leaves the label alone.
     s.run(
         r#"
         local b = CreateFrame("Button", "TextCellButton")
@@ -1321,8 +1139,7 @@ fn an_empty_fontstring_reads_back_nil_and_an_edit_box_does_not() {
     s.run(r#"TextCellButton:SetText("")"#).unwrap();
     assert_eq!(text_of(&s, "TextCellButton"), None, "an empty label is nil");
 
-    // And the EditBox is the counter-example that keeps this from being hoisted: stock
-    // `MailFrame.lua` compares `GetText() == ""` and calls `strlen(GetText())` on one.
+    // Stock `MailFrame.lua:521` compares an EditBox's `GetText() == ""`.
     s.run(
         r#"
         local e = CreateFrame("EditBox", "TextCellEdit")
@@ -1338,18 +1155,8 @@ fn an_empty_fontstring_reads_back_nil_and_an_edit_box_does_not() {
     assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
 }
 
-/// **A `SetTexture` the host cannot resolve leaves the region's art alone** — it does not overwrite
-/// it with the path that failed (decision 2124).
-///
-/// The reference's load-failure arm is explicit about it: `0x770288 cmp [ebp-4],2; jl` →
-/// `0x77028e`–`0x7702b2` releases the handle it just built and returns 0 **without ever touching
-/// `+0xcc`**. Ours stored the path first and used the
-/// probe's verdict only for the return value, so a mistyped or not-yet-shipped path erased the art
-/// it failed to replace — `GetTexture()` echoed the miss, and the extract dropped the quad, so the
-/// region went blank with nothing said anywhere.
-///
-/// The control that must not change is the second half: a resolvable path still replaces, and a VM
-/// with **no probe at all** still stores, because it has no backend to ask.
+/// A path that fails to load leaves the art alone (`0x770288` → `0x77028e`-`0x7702b2` returns 0
+/// without touching `+0xcc`); with no probe installed, every path is stored.
 #[test]
 fn an_unresolvable_set_texture_keeps_the_art_the_region_had() {
     let mut s = script();
@@ -1367,7 +1174,6 @@ fn an_unresolvable_set_texture_keeps_the_art_the_region_had() {
         "Interface\\Real"
     );
 
-    // The miss: nil back, and the art it could not replace is still there.
     assert!(
         s.eval::<bool>(r#"return t:SetTexture("Interface\\Nope") == nil"#)
             .unwrap(),
@@ -1379,7 +1185,6 @@ fn an_unresolvable_set_texture_keeps_the_art_the_region_had() {
         "the failed load overwrote the art the region was holding"
     );
 
-    // The control: a hit still replaces, and an explicit clear still clears.
     assert!(s
         .eval::<bool>(r#"return t:SetTexture("Interface\\Other") == 1"#)
         .unwrap());
@@ -1391,15 +1196,8 @@ fn an_unresolvable_set_texture_keeps_the_art_the_region_had() {
     assert!(s.eval::<bool>("return t:GetTexture() == nil").unwrap());
 }
 
-/// `Texture:GetBlendMode()` — ONE string, the reference's own spelling, round-tripping whatever
-/// `SetBlendMode` was given (`0x79a890`/`0x79a950`, table `0x87c128`, argc 1, arity 1, kinds
-/// `(string?)`).
-///
-/// The untouched default is asserted alongside the round trip because it is the load-bearing half:
-/// `ShaguTweaks/mods/dark-ui-elements.lua:169` guards a recolour with
-/// `region.GetBlendMode and region:GetBlendMode() == "ADD"`, so the answer an ordinary texture gives
-/// decides whether the reference's additive art is left alone. `"BLEND"` is the CSimpleTexture
-/// ctor's `[+0xd0] = 2` (`0x76fc64`).
+/// `Texture:GetBlendMode` (`0x79a890`, table `0x87c128`) answers one string, the mode
+/// `SetBlendMode` (`0x79a950`) set, `"BLEND"` by default (the ctor's `[+0xd0] = 2`, `0x76fc64`).
 #[test]
 fn get_blend_mode_answers_one_string_and_defaults_to_the_ctors_blend() {
     let s = crate::script::UiScript::new().unwrap();
@@ -1411,7 +1209,6 @@ fn get_blend_mode_answers_one_string_and_defaults_to_the_ctors_blend() {
     )
     .unwrap();
 
-    // Arity 1 and kind string, measured the way the shape gate measures it.
     assert_eq!(s.arity("BTex:GetBlendMode()").unwrap(), 1, "arity 1");
     assert_eq!(
         s.eval::<String>("return type(BTex:GetBlendMode())")
@@ -1425,7 +1222,6 @@ fn get_blend_mode_answers_one_string_and_defaults_to_the_ctors_blend() {
         "an untouched texture is the ctor's mode 2"
     );
 
-    // Every one of the enum's five round-trips, including the three the renderer flattens.
     for mode in ["DISABLE", "ALPHAKEY", "BLEND", "ADD", "MOD"] {
         s.run(&format!(r#"BTex:SetBlendMode("{mode}")"#)).unwrap();
         assert_eq!(
@@ -1434,13 +1230,12 @@ fn get_blend_mode_answers_one_string_and_defaults_to_the_ctors_blend() {
             "round trip through the setter"
         );
     }
-    // Case-insensitive in, canonical out — the setter coerces, the getter answers the table's name.
+    // Case-insensitive in, canonical out.
     s.run(r#"BTex:SetBlendMode("add")"#).unwrap();
     assert_eq!(
         s.eval::<String>("return BTex:GetBlendMode()").unwrap(),
         "ADD"
     );
-    // A name outside the enum leaves the mode alone rather than inventing one.
     s.run(r#"BTex:SetBlendMode("NOT_A_MODE")"#).unwrap();
     assert_eq!(
         s.eval::<String>("return BTex:GetBlendMode()").unwrap(),
@@ -1448,7 +1243,6 @@ fn get_blend_mode_answers_one_string_and_defaults_to_the_ctors_blend() {
         "an unknown name changes nothing"
     );
 
-    // A FontString is not a Texture: neither half of the pair is on its map.
     assert!(s
         .eval::<bool>(
             r#"local fs = BlendOwner:CreateFontString("BStr", "ARTWORK")
@@ -1457,14 +1251,8 @@ fn get_blend_mode_answers_one_string_and_defaults_to_the_ctors_blend() {
         .unwrap());
 }
 
-/// `Texture:GetTexCoordModifiesRect()` — the 1.12 predicate return, `1`/`nil` and never a Lua
-/// boolean (`0x79c120`, table `0x87c128`, argc 1, arity 1, kinds `(nil) | (number)`; decision 2118).
-/// `pfUI/modules/thirdparty-tbc.lua:319` calls it bare on a Texture.
-///
-/// The flag's effect on the region's rect is deliberately NOT wired (see
-/// `RegionData::tex_coord_modifies_rect`), so this asserts the state and the shape — and asserts
-/// the un-wiring too, by checking that setting the flag moves no rect: a future change that wires
-/// the geometry will fail here and have to say so.
+/// `Texture:GetTexCoordModifiesRect` (`0x79c120`, table `0x87c128`) answers `1` or nil. The flag is
+/// stored, not applied: on the reference it makes `SetTexCoord` re-derive the rect (`0x770462`).
 #[test]
 fn tex_coord_modifies_rect_is_one_slash_nil_and_moves_no_rect_yet() {
     let mut s = crate::script::UiScript::new().unwrap();
@@ -1508,8 +1296,7 @@ fn tex_coord_modifies_rect_is_one_slash_nil_and_moves_no_rect_yet() {
         "kind number, never boolean"
     );
 
-    // The flag is state only: a SetTexCoord under it still leaves the rect where the anchors and
-    // the size put it. When the geometry leg is built, this assertion is the one that must change.
+    // The assertion that changes when the rect re-derivation is built.
     s.run("TCMTex:SetTexCoord(0, 0.25, 0, 0.5)").unwrap();
     s.resolve();
     assert_eq!(
diff --git a/crates/benilla-ui/src/script/tests/resize_bounds.rs b/crates/benilla-ui/src/script/tests/resize_bounds.rs
index 7e8cd00b..6f1d7df6 100644
--- a/crates/benilla-ui/src/script/tests/resize_bounds.rs
+++ b/crates/benilla-ui/src/script/tests/resize_bounds.rs
@@ -1,20 +1,8 @@
-//! **The resize-bounds quad**, pinned to the reference's own storage (`CLayoutFrame 0x767680`).
-//!
-//! Every assertion here is one the first cut of this code got *wrong* by writing the plausible
-//! thing instead of the read thing — which is why they are pinned rather than trusted:
-//!
-//! | the plausible thing | the byte thing |
-//! |---|---|
-//! | an unset bound is "no bound" and reads back `nil` | all four fields are `0.0`, the getters push two numbers |
-//! | a floor of `1.0` keeps a drag sane | there is **no floor** — a drag goes through zero into negatives |
-//! | a bound is a bound | only an exactly-`0.0` bound is the disable sentinel; a **negative** one clamps |
-//! | `min > max` is a caller error to reconcile | nothing reconciles it; **max wins** |
-//! | setting a bound fixes a frame already outside it | nothing happens until the next drag tick |
-//! | `StartSizing("CENTER")` grips no edge, so it is a no-op | it is the **move** arm, and it is never bounded |
+//! The resize-bounds quad, as the reference stores it (`CLayoutFrame 0x767680`).
 
 use crate::script::UiScript;
 
-/// A resizable 200×100 frame planted at its BOTTOMLEFT, the shape the sibling sizing test uses.
+/// A resizable 200×100 frame planted at its BOTTOMLEFT.
 fn sizer() -> UiScript {
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
@@ -31,7 +19,6 @@ fn sizer() -> UiScript {
     s
 }
 
-/// The getters answer **two numbers**, `0, 0` on a frame nobody bounded — never `nil`.
 #[test]
 fn a_virgin_frames_bounds_read_back_as_zero_not_nil() {
     let s = sizer();
@@ -57,8 +44,7 @@ fn a_virgin_frames_bounds_read_back_as_zero_not_nil() {
         s.eval::<(f64, f64)>("return Sizer:GetMaxResize()").unwrap(),
         (400.0, 300.0)
     );
-    // Setting one pair rewrites the other verbatim — the reference reads all four and writes all
-    // four, so the untouched pair round-trips rather than being cleared.
+    // The reference writes all four fields, so the untouched pair round-trips.
     s.run("Sizer:SetMinResize(10, 10)").unwrap();
     assert_eq!(
         s.eval::<(f64, f64)>("return Sizer:GetMaxResize()").unwrap(),
@@ -66,8 +52,6 @@ fn a_virgin_frames_bounds_read_back_as_zero_not_nil() {
     );
 }
 
-/// The argument gate is `lua_isnumber` — a numeric **string** passes; everything else raises the
-/// reference's own `Usage:` text, naming the frame.
 #[test]
 fn the_setters_gate_is_lua_isnumber_and_the_usage_text_is_the_references() {
     let s = sizer();
@@ -77,7 +61,7 @@ fn the_setters_gate_is_lua_isnumber_and_the_usage_text_is_the_references() {
         (120.0, 60.0),
         "a numeric string is coerced, as 5.0's lua_isnumber does"
     );
-    // Arguments past the third are ignored — no upper arity check.
+    // Arguments past the third are ignored.
     s.run("Sizer:SetMaxResize(400, 300, 999, \"x\")").unwrap();
     assert_eq!(
         s.eval::<(f64, f64)>("return Sizer:GetMaxResize()").unwrap(),
@@ -101,17 +85,13 @@ fn the_setters_gate_is_lua_isnumber_and_the_usage_text_is_the_references() {
     assert!(err.contains("Usage: Sizer:SetMaxResize(maxWidth, maxHeight)"));
 }
 
-/// **A drag clamps against the bounds, and the anchor stops exactly on them.**
-///
-/// The second half is the rebate: without it the size pins at the bound while the delta keeps
-/// feeding the anchor, so a window held past its minimum stops shrinking and starts *walking*.
+/// A saturated grip stops the gripped edge on the bound rather than letting the frame walk.
 #[test]
 fn a_drag_clamps_and_the_planted_edge_stops_on_the_bound() {
     let mut s = sizer();
     s.run("Sizer:SetMinResize(150, 60) Sizer:SetMaxResize(260, 300)")
         .unwrap();
 
-    // RIGHT grip, dragged far right: width saturates at the max, the left edge never moves.
     s.mouse_move(300.0, 100.0);
     s.run("Sizer:StartSizing(\"RIGHT\")").unwrap();
     s.mouse_move(900.0, 100.0);
@@ -120,8 +100,7 @@ fn a_drag_clamps_and_the_planted_edge_stops_on_the_bound() {
     assert_eq!(s.eval::<f32>("return Sizer:GetLeft()").unwrap(), 100.0);
     s.run("Sizer:StopMovingOrSizing()").unwrap();
 
-    // LEFT grip, dragged far right: width saturates at the MIN — and the left edge lands exactly
-    // on it (100 + 260 − 150 = 210), not wherever the raw cursor delta would have carried it.
+    // LEFT grip dragged far right: width saturates at the min, the left edge at 100 + 260 - 150.
     let right_before = s.eval::<f32>("return Sizer:GetRight()").unwrap();
     s.mouse_move(300.0, 100.0);
     s.run("Sizer:StartSizing(\"LEFT\")").unwrap();
@@ -138,7 +117,6 @@ fn a_drag_clamps_and_the_planted_edge_stops_on_the_bound() {
         right_before,
         "the ungripped edge must not move"
     );
-    // Dragging further while saturated moves nothing at all.
     s.mouse_move(1500.0, 100.0);
     s.resolve();
     assert_eq!(
@@ -148,7 +126,7 @@ fn a_drag_clamps_and_the_planted_edge_stops_on_the_bound() {
     s.run("Sizer:StopMovingOrSizing()").unwrap();
 }
 
-/// **`0.0` is the disable sentinel, per field** — and a NEGATIVE bound is live.
+/// Only an exact 0.0 is the disable sentinel, per field.
 #[test]
 fn zero_disables_and_a_negative_bound_still_clamps() {
     let mut s = sizer();
@@ -167,7 +145,7 @@ fn zero_disables_and_a_negative_bound_still_clamps() {
     assert_eq!(s.eval::<f32>("return Sizer:GetHeight()").unwrap(), 90.0);
     s.run("Sizer:StopMovingOrSizing()").unwrap();
 
-    // A negative maximum is NOT a sentinel: it clamps, and the width really does go negative.
+    // A negative maximum clamps, and the width goes negative.
     s.run("Sizer:SetMaxResize(-50, 0) Sizer:SetMinResize(0, 0)")
         .unwrap();
     s.mouse_move(300.0, 100.0);
@@ -177,7 +155,6 @@ fn zero_disables_and_a_negative_bound_still_clamps() {
     assert_eq!(s.eval::<f32>("return Sizer:GetWidth()").unwrap(), -50.0);
 }
 
-/// With no bound at all there is **no floor** — the client has no `1.0` and neither do we.
 #[test]
 fn an_unbounded_drag_goes_through_zero() {
     let mut s = sizer();
@@ -192,7 +169,7 @@ fn an_unbounded_drag_goes_through_zero() {
     );
 }
 
-/// **`min > max` ends at `max`** — min is applied first, then max, and nothing reconciles them.
+/// Min is applied first, then max, and nothing reconciles them.
 #[test]
 fn a_min_above_the_max_resolves_to_the_max() {
     let mut s = sizer();
@@ -205,8 +182,7 @@ fn a_min_above_the_max_resolves_to_the_max() {
     assert_eq!(s.eval::<f32>("return Sizer:GetWidth()").unwrap(), 200.0);
 }
 
-/// **Setting a bound a frame already violates does nothing** until the next drag tick — the setter
-/// does not touch the size, and no other write path consults the bounds.
+/// Only a drag tick consults the bounds; the setter and every other write path do not.
 #[test]
 fn a_bound_set_late_does_not_resize_the_frame() {
     let mut s = sizer();
@@ -214,12 +190,10 @@ fn a_bound_set_late_does_not_resize_the_frame() {
     s.resolve();
     assert_eq!(s.eval::<f32>("return Sizer:GetWidth()").unwrap(), 200.0);
     assert_eq!(s.eval::<f32>("return Sizer:GetHeight()").unwrap(), 100.0);
-    // A programmatic SetWidth past the bound is not clamped either — VERIFIED: no layout vtable
-    // in the client overrides the plain, non-clamping SetWidth/SetHeight.
+    // No layout vtable in the client overrides the plain, non-clamping SetWidth/SetHeight.
     s.run("Sizer:SetWidth(50)").unwrap();
     s.resolve();
     assert_eq!(s.eval::<f32>("return Sizer:GetWidth()").unwrap(), 50.0);
-    // The first drag tick is what snaps it into range.
     s.mouse_move(300.0, 100.0);
     s.run("Sizer:StartSizing(\"RIGHT\")").unwrap();
     s.mouse_move(301.0, 100.0);
@@ -227,7 +201,7 @@ fn a_bound_set_late_does_not_resize_the_frame() {
     assert_eq!(s.eval::<f32>("return Sizer:GetWidth()").unwrap(), 400.0);
 }
 
-/// **`StartSizing("CENTER")` translates the frame and is never bounded** — the pump's case 4.
+/// `StartSizing("CENTER")` is the sizing pump's case 4, a move.
 #[test]
 fn a_center_grip_moves_the_frame_and_ignores_the_bounds() {
     let mut s = sizer();
@@ -252,8 +226,7 @@ fn a_center_grip_moves_the_frame_and_ignores_the_bounds() {
     assert_eq!(s.eval::<f32>("return Sizer:GetLeft()").unwrap(), 140.0);
 }
 
-/// `<ResizeBounds>` in XML reaches the same four fields — and a block naming only `<minResize>`
-/// **resets the max pair to unbounded**, because the client writes all four unconditionally.
+/// The client's `<ResizeBounds>` writes all four fields, so a lone `<minResize>` zeroes the max.
 #[test]
 fn the_xml_element_writes_both_pairs() {
     let mut s = UiScript::new().unwrap();
@@ -280,8 +253,7 @@ fn the_xml_element_writes_both_pairs() {
             .unwrap(),
         (608.0, 400.0)
     );
-    // An authored `<Size>` outside the authored bounds survives load unchanged — neither path
-    // clamps, whatever the document order.
+    // An authored `<Size>` outside the bounds survives load unclamped.
     assert_eq!(s.eval::<f32>("return Chatty:GetWidth()").unwrap(), 400.0);
 
     let partial = benilla_ui_doc(
diff --git a/crates/benilla-ui/src/script/tests/scrollframe.rs b/crates/benilla-ui/src/script/tests/scrollframe.rs
index 1941eed0..650d5cfb 100644
--- a/crates/benilla-ui/src/script/tests/scrollframe.rs
+++ b/crates/benilla-ui/src/script/tests/scrollframe.rs
@@ -1,13 +1,11 @@
-//! ScrollFrame (decision 0112 — the ScrollFrame mechanism): the scroll-child layout override, the
-//! live vertical-scroll range, the ScrollFrame clip on `extract`, and the clip-gated `hit_test`.
+//! ScrollFrame: the scroll-child layout override, the live scroll ranges, the clip on `extract`
+//! and the clip-gated `hit_test`.
 
 use super::common::script;
 use crate::layout::Rect;
 use crate::script::QuadContent;
 
-/// The rect of the first Texture quad whose path equals `marker` (a bare texture with no anchors of
-/// its own draws at exactly its owner frame's resolved rect — the cheapest way to read a frame's
-/// resolved rect back out through the public `extract` surface).
+/// The rect of the first Texture quad whose path is `marker`.
 fn marker_rect(quads: &[crate::script::ExtractedQuad], marker: &str) -> Option<Rect> {
     quads.iter().find_map(|q| match &q.content {
         QuadContent::Texture { path: Some(p), .. } if p == marker => q.rect,
@@ -15,8 +13,7 @@ fn marker_rect(quads: &[crate::script::ExtractedQuad], marker: &str) -> Option<R
     })
 }
 
-/// `Some(clip)` when a marker quad was found (`clip` itself `Option<Rect>`); `None` if no such
-/// marker quad exists at all (a test-authoring mistake, not a legitimate "unclipped").
+/// The clip of the first Texture quad whose path is `marker`; `None` if there is no such quad.
 fn marker_clip(quads: &[crate::script::ExtractedQuad], marker: &str) -> Option<Option<Rect>> {
     quads.iter().find_map(|q| match &q.content {
         QuadContent::Texture { path: Some(p), .. } if p == marker => Some(q.clip),
@@ -72,11 +69,8 @@ fn get_scroll_child_roundtrips_wrapper_and_name_and_clears_on_nil() {
     .unwrap();
 }
 
-/// The sign convention (verified against the design's own worked example): frame top 500, vertical
-/// 40 ⇒ child top 540. Also covers 0, an offset PAST the range and one below zero — both stored and
-/// applied verbatim, since the reference's `0x786db0` never reads the range (decision 2017) — and
-/// that `SetScrollChild(nil)` restores the child's own authored anchor (never mutated — the
-/// override is a local map).
+/// A positive offset lifts the child; offsets past the range or below zero are stored and applied
+/// as given, since `0x786db0` never reads the range.
 #[test]
 fn scroll_child_top_tracks_vertical_scroll_unclamped_then_restores_on_clear() {
     let mut s = script();
@@ -119,9 +113,7 @@ fn scroll_child_top_tracks_vertical_scroll_unclamped_then_restores_on_clear() {
         "vertical=40 -> child top = frame top + 40 (a positive offset lifts the child)"
     );
 
-    // range = child_h(600) - frame_h(200) = 400, and the offset is NOT clamped to it: 450 is
-    // stored and applied as 450. (Keeping the bar inside the range is FrameXML's job, through the
-    // Slider's [min, max] — the engine has no opinion.)
+    // The range is 600 - 200 = 400; keeping the bar inside it is the FrameXML slider's job.
     s.run("SF:SetVerticalScroll(450)").unwrap();
     s.resolve();
     assert_eq!(
@@ -135,7 +127,6 @@ fn scroll_child_top_tracks_vertical_scroll_unclamped_then_restores_on_clear() {
         Some(950.0),
         "applied verbatim: frame top 500 + 450"
     );
-    // Nor at zero.
     s.run("SF:SetVerticalScroll(-30)").unwrap();
     s.resolve();
     assert_eq!(
@@ -149,8 +140,7 @@ fn scroll_child_top_tracks_vertical_scroll_unclamped_then_restores_on_clear() {
         "a negative offset lowers the child: frame top 500 - 30"
     );
 
-    // SetScrollChild(nil): the override stops being computed — the child's own authored anchor
-    // (TOPLEFT, screen, +20,-20) re-applies with no restore step needed (it was never touched).
+    // Clearing the child stops the override, and its own untouched anchor applies again.
     s.run("SF:SetScrollChild(nil)").unwrap();
     s.resolve();
     let quads = s.extract();
@@ -161,11 +151,8 @@ fn scroll_child_top_tracks_vertical_scroll_unclamped_then_restores_on_clear() {
     );
 }
 
-/// The reference's `0x786db0` is gated on the offset actually CHANGING (a compare against the
-/// stored value, nothing else): a `SetVerticalScroll` to the value already held re-lays nothing out
-/// and fires no `OnVerticalScroll`. The same shape as the Slider's `SetValue` change-gate (decision
-/// 0250) — the other half of what keeps the bar ↔ frame wiring from ringing — and a value past the
-/// range is a change like any other.
+/// `0x786db0` acts only when the offset differs from the stored one; a value past the range is
+/// still a change.
 #[test]
 fn set_vertical_scroll_fires_on_vertical_scroll_only_on_a_change() {
     let mut s = script();
@@ -211,7 +198,6 @@ fn vertical_scroll_range_is_live_and_zero_when_unresolved_or_childless_or_shorte
     "#,
     )
     .unwrap();
-    // Before resolve: no resolved rects yet -> 0.
     assert_eq!(
         s.eval::<f32>("return SF:GetVerticalScrollRange()").unwrap(),
         0.0,
@@ -225,7 +211,6 @@ fn vertical_scroll_range_is_live_and_zero_when_unresolved_or_childless_or_shorte
         "600 - 200"
     );
 
-    // A child shorter than the frame: 0, not negative.
     s.run("Child:SetWidth(300); Child:SetHeight(150)").unwrap();
     s.resolve();
     assert_eq!(
@@ -234,7 +219,6 @@ fn vertical_scroll_range_is_live_and_zero_when_unresolved_or_childless_or_shorte
         "child shorter than frame -> 0, not negative"
     );
 
-    // No child at all: 0.
     s.run("SF:SetScrollChild(nil)").unwrap();
     assert_eq!(
         s.eval::<f32>("return SF:GetVerticalScrollRange()").unwrap(),
@@ -243,11 +227,8 @@ fn vertical_scroll_range_is_live_and_zero_when_unresolved_or_childless_or_shorte
     );
 }
 
-/// The range is in LOCAL units, not screen px — `child:GetHeight() - self:GetHeight()`, the
-/// contract the method states. It has to be: `SetVerticalScroll` becomes the child's anchor
-/// y-offset, which the solver multiplies by the child's scale, so a screen-px range against a
-/// local-unit offset makes a SCALED frame stop short of its own end and strand the tail of its
-/// content. (Found on the era-scaled options window's page scroll, which lost 22% of its travel.)
+/// The range is `child:GetHeight() - self:GetHeight()` in local units, like the offset, which
+/// becomes the child's anchor y-offset and is scaled with it.
 #[test]
 fn vertical_scroll_range_is_local_units_on_a_scaled_frame() {
     let mut s = script();
@@ -276,8 +257,6 @@ fn vertical_scroll_range_is_local_units_on_a_scaled_frame() {
         400.0,
         "…which is exactly what the widget contract says it is"
     );
-    // And the clamp agrees, so scrolling to the range really reaches the end: the child's bottom
-    // lands on the frame's.
     s.run("SF:SetVerticalScroll(400)").unwrap();
     s.resolve();
     assert_eq!(
@@ -293,10 +272,8 @@ fn vertical_scroll_range_is_local_units_on_a_scaled_frame() {
     );
 }
 
-/// `OnVerticalScroll` carries the value AS STORED — past the range too (decision 2017: the
-/// reference's `0x786db0` fires with `[+0x328]`, which it never clamps) — under the reference's
-/// handler-firing conventions (`0x704f10`), and `UpdateScrollChildRect` fires
-/// `OnScrollRangeChanged` with the live range.
+/// `0x786db0` fires `OnVerticalScroll` with the unclamped stored value `[+0x328]`, under the
+/// handler conventions of `0x704f10`.
 #[test]
 fn vertical_scroll_fires_as_given_and_update_rect_fires_range_changed() {
     let mut s = script();
@@ -337,12 +314,8 @@ fn vertical_scroll_fires_as_given_and_update_rect_fires_range_changed() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The Era idiom `UpdateScrollChildRect` exists to serve — resize the content, then immediately ask
-/// for the new range, in ONE script tick with no intervening [`UiScript::resolve`] call in between
-/// (exactly how the app's own drive loop runs Lua: `ui_script/mod.rs` resolves once per FRAME, not
-/// once per script statement) — must see the JUST-set size, not the last frame's stale `resolved`
-/// rect. Before `UpdateScrollChildRect` forced its own fresh resolve, this fired the OLD (here,
-/// zero) range on the very call whose whole job is reporting the new one.
+/// `UpdateScrollChildRect` resolves for itself, so a resize earlier in the same tick counts; the
+/// app resolves only once per frame.
 #[test]
 fn update_scroll_child_rect_sees_a_same_tick_resize_with_no_intervening_resolve() {
     let mut s = script();
@@ -376,17 +349,12 @@ fn update_scroll_child_rect_sees_a_same_tick_resize_with_no_intervening_resolve(
         "UpdateScrollChildRect must resolve the JUST-set height itself, not report the stale \
          (pre-resize) range from the last full UiScript::resolve"
     );
-    // GetVerticalScrollRange() also benefits (same fresh `resolved`), and a same-tick
-    // SetVerticalScroll now clamps against the true, current range instead of the stale one.
     assert_eq!(
         s.eval::<f32>("return SF:GetVerticalScrollRange()").unwrap(),
         400.0
     );
 }
 
-/// The clip on `extract`: the scroll child's own quads, and a grandchild region nested arbitrarily
-/// deep under it, carry `clip = Some(the scrollframe's resolved rect)`; a sibling outside the
-/// ScrollFrame entirely carries `None`.
 #[test]
 fn extract_clips_the_scroll_childs_whole_subtree_and_leaves_a_sibling_unclipped() {
     let mut s = script();
@@ -436,9 +404,6 @@ fn extract_clips_the_scroll_childs_whole_subtree_and_leaves_a_sibling_unclipped(
     );
 }
 
-/// Nested ScrollFrames intersect their rects (decision 0112 §4): an inner ScrollFrame living inside
-/// an outer one's scroll child clips its own content to the intersection of both rects, not just
-/// the innermost.
 #[test]
 fn nested_scrollframes_intersect_their_clip_rects() {
     let mut s = script();
@@ -474,8 +439,7 @@ fn nested_scrollframes_intersect_their_clip_rects() {
     let quads = s.extract();
 
     let outer_rect = Rect::new(250.0, 0.0, 550.0, 400.0);
-    // Inner's OWN rect (unclipped by itself): TOPLEFT anchored to C1 (top 550) at (350,-30) -> top
-    // 520, left 350; size 200x150 -> bottom 370, right 550.
+    // Inner's own rect: TOPLEFT at C1's (350, -30), so top 520 and left 350, sized 200x150.
     let inner_rect = Rect::new(370.0, 350.0, 520.0, 550.0);
     let intersection = Rect::new(
         inner_rect.bottom.max(outer_rect.bottom),
@@ -483,8 +447,7 @@ fn nested_scrollframes_intersect_their_clip_rects() {
         inner_rect.top.min(outer_rect.top),
         inner_rect.right.min(outer_rect.right),
     );
-    // A genuine intersection, not just "pick the smaller rect": inner's right edge (550) is cut
-    // back to outer's (400), while inner's tighter bottom/left/top edges win.
+    // Outer cuts inner's right edge from 550 to 400; inner's other edges are tighter.
     assert_eq!(intersection, Rect::new(370.0, 350.0, 520.0, 400.0));
 
     assert_eq!(
@@ -509,9 +472,6 @@ fn nested_scrollframes_intersect_their_clip_rects() {
     );
 }
 
-/// Hit-testing (decision 0112 §5): a button inside the scroll child, scrolled out of the frame's
-/// rect, must not hit even though its own resolved rect contains the cursor; scrolled into view, it
-/// hits normally.
 #[test]
 fn hit_test_denies_a_button_clipped_out_and_admits_it_once_scrolled_into_view() {
     let mut s = script();
@@ -535,16 +495,14 @@ fn hit_test_denies_a_button_clipped_out_and_admits_it_once_scrolled_into_view()
     .unwrap();
     s.resolve();
 
-    // vertical=0: child top 500, button top 500-400=100, bottom 80 — its OWN rect contains (25,90),
-    // but that's well outside the frame's clip [300,500].
+    // At 0 the button spans 80..100, outside the frame's clip of 300..500.
     assert_eq!(
         s.hit_test(25.0, 90.0),
         None,
         "the button's own rect contains the point, but the ScrollFrame's clip excludes it"
     );
 
-    // Scroll 250px: button top 500+250-400=350, bottom 330 — now inside both its own rect AND the
-    // frame's clip window.
+    // Scrolled by 250 the button spans 330..350, inside the clip.
     s.run("SF:SetVerticalScroll(250)").unwrap();
     s.resolve();
     assert!(
@@ -553,9 +511,7 @@ fn hit_test_denies_a_button_clipped_out_and_admits_it_once_scrolled_into_view()
     );
 }
 
-/// `UpdateScrollChildRect` right after the SetTexts that fill a pane reads a range that already
-/// counts the wrapped text — the reference's measure is synchronous, and with a font engine
-/// installed so is ours (1944; stock `QuestLog_UpdateQuestDetails` is the caller that found it).
+/// The reference measures text synchronously, as stock `QuestLog_UpdateQuestDetails` relies on.
 #[test]
 fn update_scroll_child_rect_measures_the_childs_text_before_it_reads_the_range() {
     struct Rows;
@@ -593,16 +549,9 @@ fn update_scroll_child_rect_measures_the_childs_text_before_it_reads_the_range()
     );
 }
 
-/// The horizontal axis is the vertical one's byte-clone (`0x786d30` against `0x786db0`), so this is
-/// the vertical trio's test on the other axis: the offset is stored VERBATIM and re-anchors the
-/// child, `OnHorizontalScroll` fires only on a real change, and the range is
-/// `max(0, subtreeWidth - frameWidth)`.
-///
-/// **The sign is the point.** `0x787100` hands both offsets to `SetPoint(TOPLEFT, self, TOPLEFT,
-/// +hScroll, +vScroll)` unnegated, and x grows right — so a positive horizontal pushes the child
-/// RIGHT where a positive vertical lifts it. `aux-addon/tabs/search/filter.lua:315-322` corroborates
-/// it from the caller's side (it bounds x into `[frameWidth - contentWidth - 10, 0]` and y into
-/// `[0, contentHeight - frameHeight]`), which is why it is asserted here rather than assumed.
+/// The horizontal axis clones the vertical (`0x786d30` against `0x786db0`); `0x787100` passes both
+/// offsets to `SetPoint(TOPLEFT, self, TOPLEFT, +h, +v)` unnegated, so a positive horizontal
+/// offset pushes the child right.
 #[test]
 fn scroll_child_left_tracks_horizontal_scroll_unclamped_and_fires_on_change() {
     let mut s = script();
@@ -640,7 +589,6 @@ fn scroll_child_left_tracks_horizontal_scroll_unclamped_and_fires_on_change() {
         "horizontal=0 -> child left = frame left"
     );
 
-    // Positive pushes the child RIGHT (the reference's unnegated xOff) …
     s.run("HSF:SetHorizontalScroll(40)").unwrap();
     s.resolve();
     assert_eq!(
@@ -648,7 +596,6 @@ fn scroll_child_left_tracks_horizontal_scroll_unclamped_and_fires_on_change() {
         Some(40.0),
         "a positive horizontal offset moves the child right"
     );
-    // … and it is the NEGATIVE direction that scrolls right, which is the half aux-addon relies on.
     s.run("HSF:SetHorizontalScroll(-60)").unwrap();
     s.resolve();
     assert_eq!(
@@ -657,8 +604,7 @@ fn scroll_child_left_tracks_horizontal_scroll_unclamped_and_fires_on_change() {
         "a negative horizontal offset scrolls right"
     );
 
-    // No clamp — the range is 500-300 = 200 and 450 is stored and applied whole (decision 2017's
-    // law, which is `0x786d30`'s as much as `0x786db0`'s: neither reads the range).
+    // Neither `0x786d30` nor `0x786db0` reads the range, so 450 is stored whole.
     assert_eq!(
         s.eval::<f32>("return HSF:GetHorizontalScrollRange()")
             .unwrap(),
@@ -673,7 +619,6 @@ fn scroll_child_left_tracks_horizontal_scroll_unclamped_and_fires_on_change() {
         "stored verbatim, past the range"
     );
 
-    // Arity/kind, the way the shape gate measures them.
     assert_eq!(s.arity("HSF:GetHorizontalScroll()").unwrap(), 1);
     assert_eq!(s.arity("HSF:GetHorizontalScrollRange()").unwrap(), 1);
     assert_eq!(
@@ -692,7 +637,7 @@ fn scroll_child_left_tracks_horizontal_scroll_unclamped_and_fires_on_change() {
         "the setter answers nothing"
     );
 
-    // The change-gate: four setter calls moved the value (40, -60, 450, and 450 again is not one).
+    // Four setter calls, but the second 450 is no change.
     let fired: Vec<f32> = (1..=s.eval::<i64>("return table.getn(hfired)").unwrap())
         .map(|i| s.eval::<f32>(&format!("return hfired[{i}]")).unwrap())
         .collect();
@@ -702,7 +647,6 @@ fn scroll_child_left_tracks_horizontal_scroll_unclamped_and_fires_on_change() {
         "OnHorizontalScroll fires once per ACTUAL change, with the new offset"
     );
 
-    // The two axes are independent state, not one offset behind two names.
     s.run("HSF:SetVerticalScroll(25)").unwrap();
     assert_eq!(
         s.eval::<f32>("return HSF:GetHorizontalScroll()").unwrap(),
@@ -714,11 +658,8 @@ fn scroll_child_left_tracks_horizontal_scroll_unclamped_and_fires_on_change() {
     );
 }
 
-/// `UpdateScrollChildRect` notifies `OnScrollRangeChanged(self, xRange, yRange)` — **horizontal
-/// first**. Byte-derived, not guessed: the vertical result leaves `0x786e30` on top of the x87
-/// stack, is `fstp`'d first and so pushed deepest, landing as `arg2` (easy to read the other way
-/// round, which is why it is asserted here). `arg1` was a hardcoded `0.0` for as long as
-/// there was no horizontal range to put in it.
+/// The vertical range leaves `0x786e30` on top of the x87 stack and is `fstp`'d first, so it is
+/// pushed deepest and lands as `arg2`.
 #[test]
 fn update_scroll_child_rect_reports_both_ranges_horizontal_first() {
     let mut s = script();
diff --git a/crates/benilla-ui/src/script/tests/setparent.rs b/crates/benilla-ui/src/script/tests/setparent.rs
index ea0d06ec..5cee982b 100644
--- a/crates/benilla-ui/src/script/tests/setparent.rs
+++ b/crates/benilla-ui/src/script/tests/setparent.rs
@@ -1,13 +1,10 @@
-//! The runtime `SetParent` law — strata/level re-assignment, the hide→show round-trip, and the
-//! binding's error surface (`SetParent 0x7a1550`; decision 1323). Every test drives the
-//! production Lua binding; the arena split
-//! (`reparent_begin`/`reparent_finish`) is exercised through it.
+//! Runtime `SetParent` (`0x7a1550`): strata and level re-assignment, the hide and show round-trip,
+//! and the binding's errors.
 
 use super::common::script;
 
-/// `strata := parent.strata`, `level := parent.level + 1` (`0x76ab5a`/`0x76ab65`) — and the
-/// subtree is NOT re-based (`propagate = 0`): an existing child keeps its absolute level, landing
-/// below its own parent, exactly as shipped.
+/// `strata := parent.strata`, `level := parent.level + 1` (`0x76ab5a`/`0x76ab65`); the subtree's
+/// levels are not re-based (`propagate = 0`), so a child can land below its own parent.
 #[test]
 fn reparent_relevels_the_moved_frame_only() {
     let s = script();
@@ -44,8 +41,7 @@ fn reparent_relevels_the_moved_frame_only() {
     );
 }
 
-/// `SetParent(nil)` is a RESET — strata MEDIUM, level 0 (`0x76aba3`/`0x76abac`) — never "keep
-/// current".
+/// `SetParent(nil)` resets to strata MEDIUM, level 0 (`0x76aba3`/`0x76abac`).
 #[test]
 fn reparent_to_nil_resets_strata_and_level() {
     let s = script();
@@ -66,11 +62,8 @@ fn reparent_to_nil_resets_strata_and_level() {
     assert_eq!(s.eval::<i64>("return F:GetFrameLevel()").unwrap(), 0);
 }
 
-/// A reparent of an effectively-visible frame is a hide→show round-trip: `OnHide` fires (under the
-/// OLD parent), then `OnShow` refires down the subtree — and an `OnShow` doing
-/// `SetFrameLevel(GetParent():GetFrameLevel()+1)` lands the child back above its parent. That
-/// hand-repair is AtlasLoot's own idiom and the reason its browse panel works on the reference —
-/// the round-trip is what makes it run.
+/// A visible frame's reparent fires `OnHide` under the old parent, then `OnShow` down the subtree,
+/// where AtlasLoot's `SetFrameLevel(GetParent():GetFrameLevel()+1)` lifts a child back up.
 #[test]
 fn a_visible_reparent_refires_onhide_then_onshow() {
     let s = script();
@@ -115,10 +108,8 @@ fn a_visible_reparent_refires_onhide_then_onshow() {
     );
 }
 
-/// A reparent of a hidden frame fires neither event, and does not recompute effective visibility:
-/// the `+0xd4` cascade only runs inside the show half (`0x76abfd` gates on the captured `ebx`), so
-/// a shown-but-invisible frame moved under a visible parent STAYS effectively invisible until
-/// something shows it. Shipped behaviour, byte-verified — not an oversight.
+/// The `+0xd4` visibility cascade runs only in the show half (`0x76abfd` gates on the captured
+/// `ebx`), so a hidden frame moved under a visible parent stays invisible until shown.
 #[test]
 fn a_hidden_reparent_fires_nothing_and_leaves_visibility_stale() {
     let s = script();
@@ -145,9 +136,7 @@ fn a_hidden_reparent_fires_nothing_and_leaves_visibility_stale() {
             .unwrap(),
         "shown bit intact, effective visibility stale-false under the visible new parent"
     );
-    // An explicit Show is what recomputes it — but Show() no-ops while the bit is already set, so
-    // a real transition needs the toggle. The Hide half fires no OnHide (the frame was already
-    // effectively invisible — transition-gated); only the Show half's false→true fires.
+    // Show() no-ops while the shown bit is set, so it takes a toggle; only its Show half fires.
     s.run("STF:Hide(); STF:Show()").unwrap();
     assert!(s.eval::<bool>("return STF:IsVisible()").unwrap());
     assert_eq!(
@@ -157,9 +146,8 @@ fn a_hidden_reparent_fires_nothing_and_leaves_visibility_stale() {
     );
 }
 
-/// The binding's error surface: a cycle RAISES (`0x87cb14` — including `newParent == self`), an
-/// unresolvable name raises `Couldn't find region named`, and an ABSENT argument is the same raise
-/// — not the nil path. The same-parent call is a total no-op that fires nothing.
+/// A cycle, self included, raises (`0x87cb14`); an absent argument takes the bad-name raise, not
+/// the nil path.
 #[test]
 fn the_binding_raises_on_cycle_bad_name_and_absent_argument() {
     let s = script();
@@ -185,7 +173,7 @@ fn the_binding_raises_on_cycle_bad_name_and_absent_argument() {
     let absent = s.run("A:SetParent()").unwrap_err().to_string();
     assert!(absent.contains("Couldn't find region named"), "{absent}");
 
-    // Same parent: the total no-op — no events, no level rewrite.
+    // B's parent is already A: the same-parent call is a total no-op, firing nothing.
     s.run(
         r#"
         B:SetFrameLevel(9)
@@ -204,16 +192,8 @@ fn the_binding_raises_on_cycle_bad_name_and_absent_argument() {
     );
 }
 
-/// **A reparent under a scale change still moves the child's resolved rect** — the falsifier for
-/// decision 2314's claim that `SetParent` is a value-only write the ledger can NAME.
-///
-/// The gate's two tiers police each other under `WOW_LAYOUT_VERIFY`, which is forced on for this
-/// crate's tests: an incremental pass that names its nodes is re-run from scratch and the rects
-/// must be identical. So this test does not have to assert the epoch bookkeeping — it only has to
-/// make the reparent *observable in geometry*, which is what the conservative touch used to buy
-/// wholesale. A child anchored inside a parent inherits `parentScale · ownScale` as its
-/// `LayoutInput.scale`; move it to a parent with a different scale and both its offsets and its
-/// span change.
+/// Under `WOW_LAYOUT_VERIFY`, on for this crate's tests, every incremental pass is checked against
+/// a full one, so the test only needs a reparent that changes the child's scale.
 #[test]
 fn a_reparent_under_a_scale_change_moves_the_childs_rect() {
     let mut s = script();
@@ -235,9 +215,7 @@ fn a_reparent_under_a_scale_change_moves_the_childs_rect() {
         .eval("return ScaleKid:GetLeft(), ScaleKid:GetBottom(), ScaleKid:GetWidth()")
         .unwrap();
 
-    // The whole point: the write between the two reads is the reparent, and the read after it must
-    // see it. Scale 2 doubles the offsets and the span in screen units — and `GetWidth` reports in
-    // the frame's OWN scaled space, so the width reads back unchanged while the edges move.
+    // Own-space reads (`GetLeft`, `GetWidth`) stay put while the screen rect doubles.
     s.run("kid:SetParent(two)").unwrap();
     s.resolve();
     let at_two: (f32, f32, f32) = s
@@ -250,7 +228,7 @@ fn a_reparent_under_a_scale_change_moves_the_childs_rect() {
         (10.0, 20.0, 100.0),
         "own-space coordinates are scale-relative, so these do not move"
     );
-    // …but the SCREEN rect does. Read it off the extraction, which is in screen units.
+    // The extraction is in screen units.
     let widths: Vec<f32> = s
         .extract()
         .iter()
diff --git a/crates/benilla-ui/src/script/tests/simplehtml.rs b/crates/benilla-ui/src/script/tests/simplehtml.rs
index 7f912c48..0da4387e 100644
--- a/crates/benilla-ui/src/script/tests/simplehtml.rs
+++ b/crates/benilla-ui/src/script/tests/simplehtml.rs
@@ -1,18 +1,12 @@
-//! The `SimpleHTML` widget end to end — the markup engine's *model* half.
-//!
-//! The parse itself (strict XML, the three fallback routes, the collapse, the splices) is unit
-//! tested in `script::simplehtml::parse`, against the byte law directly. What is asserted here is
-//! everything that only exists once the blocks are real regions: the anchor chain, the width
-//! snapshot, the element-font resolution and its H1→P fallback, the spacing step, the free on
-//! rebuild, and the 19-name Lua table.
+//! The `SimpleHTML` widget once its blocks are regions: the anchor chain, block widths, element
+//! fonts and their `P` fallback, spacing, the free on rebuild and the 19-name Lua table.
 
 use super::common::script;
 use crate::layout::Point;
 use crate::script::{Model, UiScript};
 use crate::widget::RegionKind;
 
-/// One block as a reader would describe it: what it says, how it is justified, what face it is in,
-/// how wide it was told to be, and where it hangs from.
+/// One block as a reader would describe it.
 #[derive(Clone, Debug, PartialEq)]
 struct Blk {
     text: Option<String>,
@@ -20,21 +14,18 @@ struct Blk {
     justify_h: &'static str,
     font: Option<String>,
     font_height: Option<f32>,
-    /// The `size` the widget wrote: `(frame width, 0)` for a text block — a zero height is how the
-    /// measure round-trip is asked for the intrinsic one.
+    /// `(frame width, 0)` for a text block: a 0 height takes the measured one.
     size: Option<(f32, f32)>,
-    /// `(own point, relative point, x, y, target)`, `None` when the block carries no anchor at all.
+    /// `(own point, relative point, x, y, target)`.
     anchor: Option<(Point, Point, f32, f32, Rel)>,
 }
 
 /// What a block's single anchor points at.
 #[derive(Clone, Copy, Debug, PartialEq)]
 enum Rel {
-    /// The SimpleHTML frame itself — only block 0 ever does this.
+    /// The SimpleHTML frame; only block 0 anchors to it.
     Frame,
-    /// A previous block, by index in the block list.
     Block(usize),
-    /// Something else entirely (never expected; a failure would print it).
     Other,
 }
 
@@ -73,8 +64,6 @@ fn blocks(s: &UiScript, name: &str) -> Vec<Blk> {
                 font_height: d.font_height,
                 size: d.size,
                 anchor,
-                // A texture block has no text; keeping the kind out of the struct and asserting it
-                // here keeps the expected-value literals readable.
             }
             .tap_kind(kind)
         })
@@ -82,9 +71,7 @@ fn blocks(s: &UiScript, name: &str) -> Vec<Blk> {
 }
 
 impl Blk {
-    /// A tiny consistency check folded into the read: a text block is a FontString, an image block
-    /// is a Texture. A regression that made blocks the wrong region kind would otherwise pass
-    /// every text assertion below.
+    /// Asserts a text block is a FontString and an image block a Texture.
     fn tap_kind(self, kind: RegionKind) -> Blk {
         match (&self.text, &self.texture) {
             (Some(_), None) => assert_eq!(kind, RegionKind::FontString),
@@ -95,7 +82,6 @@ impl Blk {
     }
 }
 
-/// Just the strings, for the tests that only care about the walk.
 fn texts(s: &UiScript, name: &str) -> Vec<String> {
     blocks(s, name)
         .into_iter()
@@ -103,8 +89,7 @@ fn texts(s: &UiScript, name: &str) -> Vec<String> {
         .collect()
 }
 
-/// How many regions the frame owns in total — the free-on-rebuild check's instrument. A block that
-/// was orphaned rather than destroyed still sits in its owner's region list and still draws.
+/// The frame's region count, which still counts a block orphaned rather than freed.
 fn region_count(s: &UiScript, name: &str) -> usize {
     let lua = s.lua();
     let model = lua.app_data_ref::<Model>().expect("model");
@@ -112,8 +97,8 @@ fn region_count(s: &UiScript, name: &str) -> usize {
     model.arena.frame(fh).expect("live frame").regions.len()
 }
 
-/// A `SimpleHTML` named `Page`, 270×304 like the reference's `ItemTextPageText`, with one font
-/// object behind it (the `<FontString inherits="ItemTextFontNormal"/>` shape).
+/// A `SimpleHTML` named `Page`, 270×304 and in `ItemTextFontNormal` like the stock
+/// `ItemTextPageText` (`ItemTextFrame.xml:203`).
 fn page(s: &UiScript) {
     s.run(
         r#"
@@ -129,13 +114,9 @@ fn page(s: &UiScript) {
     .unwrap();
 }
 
-/// Answer every pending measure at 16px a line and 100 wide, so the resolved rects below are
-/// arithmetic a reader can check.
-///
-/// The line count is the client's own kernel `0x5c2070`, not "breaks + 1": it counts a line per
-/// class-2 token consumed and exits at the terminator, so a **trailing** break opens no new line
-/// and the one-byte `"\n"` a `<BR/>` block carries is **one** line, not two. An empty string
-/// never enters the loop body at all and measures 0 — the empty-`<P>` edge.
+/// Answer every pending measure at 16 px a line and 100 wide, with the reference's line count
+/// (`0x5c2070`): a trailing break opens no line, so a `<BR/>` block's `"\n"` is one line, and an
+/// empty string is none.
 fn measure_at_16px(s: &mut UiScript) {
     s.resolve();
     let reqs = s.fontstrings_needing_measure();
@@ -160,12 +141,9 @@ fn client_lines(text: &str) -> usize {
     }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The walk, as blocks on the frame
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The walk, as blocks on the frame ──
 
-/// A well-formed body: one block per tag, each carrying the tag's own `align` and — because only
-/// `<FontString>` was declared — every one of them in `P`'s face, the `<H1>` included.
+/// Each tag's block carries its `align`, and with only `P` declared every block is in `P`'s face.
 #[test]
 fn a_well_formed_body_is_one_block_per_tag() {
     let mut s = script();
@@ -192,20 +170,18 @@ fn a_well_formed_body_is_one_block_per_tag() {
             ("Right body.".to_string(), "RIGHT"),
         ]
     );
-    // `elementFont[1]`'s path is empty, so `0x78ae30` substitutes `elementFont[0]`. There
-    // is NO header scaling anywhere in the TU: the H1 is the same 15px as the paragraphs.
+    // `elementFont[1]` has no path, so `0x78ae30` substitutes `elementFont[0]`; nothing scales a
+    // header.
     for blk in &b {
         assert_eq!(blk.font.as_deref(), Some("Fonts\\MORPHEUS.TTF"));
         assert_eq!(blk.font_height, Some(15.0));
-        // `SetWidth(frame.GetWidth())`, and NO height — the intrinsic one comes from the measure.
         assert_eq!(blk.size, Some((270.0, 0.0)));
     }
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The anchor chain (`CLayoutFrame::SetPoint 0x767c70`) and the flush default (`0x770d89` zeroes
-/// spacing): block 0 pins TOPLEFT→frame TOPLEFT, every later block TOPLEFT→**the previous block's**
-/// BOTTOMLEFT at `−spacing` — which is `0` out of the box, so the blocks touch.
+/// Block 0 pins TOPLEFT to the frame's TOPLEFT and each later block TOPLEFT to the previous one's
+/// BOTTOMLEFT at `-spacing` (`0x767c70`); spacing starts at 0 (`0x770d89`), so the blocks touch.
 #[test]
 fn blocks_chain_bottom_to_top_and_are_flush_at_spacing_zero() {
     let mut s = script();
@@ -224,15 +200,13 @@ fn blocks_chain_bottom_to_top_and_are_flush_at_spacing_zero() {
         ]
     );
 
-    // …and the resolved rects really do stack with no gap. Frame top is 600 (screen top, TOPLEFT
-    // at 0,0); three 16px lines run 600→584→568→552.
+    // The frame top is the screen top, 600; three 16 px lines run down to 552.
     measure_at_16px(&mut s);
     let tops = resolved_tops(&s, "Page");
     assert_eq!(tops, [(600.0, 584.0), (584.0, 568.0), (568.0, 552.0)]);
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// `SetSpacing` is the only thing that opens a gap, and it opens it by exactly its own value.
 #[test]
 fn spacing_steps_the_blocks_apart() {
     let mut s = script();
@@ -264,8 +238,7 @@ fn spacing_steps_the_blocks_apart() {
     );
 }
 
-/// `<BR/>` at BODY level is its own `"\n"` block, and `0x5c2070` counts **one** line for it — one
-/// blank line, not two and not a paragraph gap.
+/// A BODY-level `<BR/>` is its own `"\n"` block, which `0x5c2070` counts as one line.
 #[test]
 fn a_body_level_br_is_exactly_one_blank_line() {
     let mut s = script();
@@ -282,8 +255,7 @@ fn a_body_level_br_is_exactly_one_blank_line() {
     );
 }
 
-/// Inline `<BR/>` is a different animal: it splices the two bytes `|n` into the SAME block, which
-/// the font engine turns into a line break within it.
+/// An inline `<BR/>` splices `|n` into the enclosing block, a line break within it.
 #[test]
 fn an_inline_br_stays_inside_its_block() {
     let s = script();
@@ -293,8 +265,8 @@ fn an_inline_br_stays_inside_its_block() {
     assert_eq!(texts(&s, "Page"), ["a|nb"]);
 }
 
-/// All three fallback routes land on ONE block holding the RAW string — no collapse, so embedded
-/// newlines survive as real line breaks. This is the common case for a vmangos `page_text`.
+/// Each fallback route is one block holding the raw, uncollapsed string; most vmangos `page_text`
+/// rows are plain text and take it.
 #[test]
 fn the_three_fallback_routes_each_land_on_one_raw_block() {
     let s = script();
@@ -317,7 +289,6 @@ fn the_three_fallback_routes_each_land_on_one_raw_block() {
     }
 }
 
-/// Malformed markup **falls back**; it never raises and never renders half a document.
 #[test]
 fn malformed_markup_falls_back_rather_than_erroring() {
     let s = script();
@@ -333,8 +304,7 @@ fn malformed_markup_falls_back_rather_than_erroring() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **A second `SetText` destroys the first parse's blocks.** Not hides, not orphans — the regions
-/// are gone from the frame, so nothing of the old page can draw behind the new one.
+/// A second `SetText` frees the first parse's regions, so nothing of the old page draws.
 #[test]
 fn a_second_set_text_replaces_the_blocks() {
     let mut s = script();
@@ -363,9 +333,8 @@ fn a_second_set_text_replaces_the_blocks() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The real `page_text` shape `ItemTextFrame.xml`'s ItemTextPageText renders, driven through the
-/// widget: the `<H1>` at the `<P>` size, every block centred, each `<BR/>` one blank line, and the
-/// body's own inter-tag newlines adding nothing at all.
+/// A real `page_text` body: the `<H1>` at the `<P>` size, each `<BR/>` one blank line, and the
+/// newlines between tags adding nothing.
 #[test]
 fn the_page_text_body_renders_the_block_list_a_reader_would_draw() {
     let mut s = script();
@@ -406,7 +375,7 @@ fn the_page_text_body_renders_the_block_list_a_reader_would_draw() {
         ],
         "the H1 renders at the P size — nothing in the TU scales a header"
     );
-    // Five blocks flush at 16px each: 600 → 520.
+    // Five flush 16 px blocks: 600 down to 520.
     measure_at_16px(&mut s);
     let tops = resolved_tops(&s, "Page");
     assert_eq!(tops.first(), Some(&(600.0, 584.0)));
@@ -414,14 +383,9 @@ fn the_page_text_body_renders_the_block_list_a_reader_would_draw() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **The exact string the reader builds**, on the exact body B240 reports — `ItemTextFrame.xml`'s
-/// READY handler pads an authorless page as `"\n" .. ItemTextGetText() .. "\n"`, and that padding
-/// is the one thing standing between a formatted page and its raw markup.
-/// Whitespace before and after the root element is legal XML, so this must take the MARKUP path;
-/// if it ever takes the fallback, every book in the world silently renders as its own source.
-///
-/// The body is vmangos `page_text` 2676 verbatim — the *Alliance Military Ranks* plaque in
-/// Stormwind's Old Town, `GameObject` 3011, the object in the report's screenshots.
+/// `ItemTextFrame.lua:44` pads an authorless page as `"\n" .. ItemTextGetText() .. "\n"`, and
+/// whitespace around the root element is legal XML, so it still takes the markup path. The body is
+/// vmangos `page_text` 2676, the Alliance Military Ranks plaque (`GameObject` 3011).
 #[test]
 fn the_readers_own_newline_padding_still_parses_as_markup() {
     let mut s = script();
@@ -460,7 +424,7 @@ fn the_readers_own_newline_padding_still_parses_as_markup() {
         "the padded page took the markup path — one block per tag, one blank line per <BR/>, and \
          BODY's own inter-tag newlines adding nothing"
     );
-    // The falsification, stated: the fallback would put the WHOLE source in one block.
+    // The fallback would put the whole source in one block.
     assert!(
         !texts[0].contains('<'),
         "a fallback would render the markup itself — the reported symptom"
@@ -468,10 +432,8 @@ fn the_readers_own_newline_padding_still_parses_as_markup() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The other half of the same guard: `page_text` **1510** (the Crystal Pylon manual) ends
-/// `</HTML.` — a typo in Blizzard's own shipped data. Strict XML rejects it, so it falls back to
-/// raw markup **on the reference client too**, and ours must do the same rather than paper over
-/// it. This is the one of the world's 62 HTML bodies that is not well-formed.
+/// `page_text` 1510, the Crystal Pylon manual, ends `</HTML.`, so strict XML rejects it and the
+/// reference shows the raw markup too; it is the only malformed one of the 62 HTML bodies.
 #[test]
 fn blizzards_own_malformed_page_falls_back_exactly_as_the_reference_does() {
     let s = script();
@@ -490,8 +452,6 @@ fn blizzards_own_malformed_page_falls_back_exactly_as_the_reference_does() {
     );
 }
 
-/// A declared header font **is** honoured — the fallback fires only on an element with no font
-/// from any source, so this is the control for the test above.
 #[test]
 fn a_declared_header_font_wins_over_the_p_fallback() {
     let s = script();
@@ -516,8 +476,7 @@ fn a_declared_header_font_wins_over_the_p_fallback() {
     );
 }
 
-/// An `<IMG>` sizes itself, anchors by `align`, and — when it is NOT floated — reserves its own
-/// height in the flow while leaving `prevBlock` pointing at the last **text** block.
+/// An unfloated `<IMG>` reserves its height in the flow, but `prevBlock` stays the last text block.
 #[test]
 fn an_unfloated_image_reserves_height_without_becoming_the_anchor() {
     let s = script();
@@ -542,19 +501,9 @@ fn an_unfloated_image_reserves_height_without_becoming_the_anchor() {
     );
 }
 
-/// **B342, at the engine.** The symptom: the Alliance crest on *A Treatise on Military Ranks*
-/// draws several times the reference's size, with the page's text over the top of it.
-///
-/// The body is `page_text` 2654 and its `<IMG>` carries **no `width=` and no `height=`**, so the
-/// block is sized `0 × 0`. In the reference that is not "no size": the resolver's size call is
-/// VIRTUAL, and `CSimpleTexture::GetWidth 0x770720` / `GetHeight 0x770790` answer an authored `0.0`
-/// with the loaded texture's own texel extent, through bit-for-bit the converter `<AbsDimension>`
-/// uses — **one texel is one FrameXML unit** (decision 1349).
-/// `PvPRankAlliance.blp` is 128×128, so the crest is a 128-unit square.
-///
-/// The falsification is the reported shape itself, asserted below: a zero span leaves the opposite
-/// edge unresolved (`combine_edge`'s `span != 0.0` leg), and the region sweep's owner-edge fallback
-/// then hands the image the rest of the **270-wide** page.
+/// The `<IMG>` in `page_text` 2654 has no `width=` or `height=`, and the reference's
+/// `CSimpleTexture::GetWidth 0x770720`/`GetHeight 0x770790` answer an authored 0 with the art's
+/// texel size, a texel to a FrameXML unit: the 128×128 crest is a 128-unit square.
 #[test]
 fn the_books_unsized_crest_is_its_arts_texel_square_not_the_whole_page() {
     const CREST: &str = "Interface\\PvPRankBadges\\PvPRankAlliance";
@@ -596,18 +545,15 @@ fn the_books_unsized_crest_is_its_arts_texel_square_not_the_whole_page() {
         (128.0, 128.0),
         "a texel is a FrameXML unit: the 128x128 crest is a 128-unit square, not the page"
     );
-    // The reported symptom, stated as the thing that must not come back: the page is 270 wide and
-    // 304 tall, and the crest used to take all of the first and everything left of the second.
+    // The page is 270 wide; the crest must not span it.
     assert!(
         rect.right - rect.left < 270.0,
         "the crest is stretched across the page width again"
     );
 }
 
-/// The flow half of the same law (`0x78ad07`): an **unfloated** image reserves
-/// `texture.GetHeight()` — `CSimpleTexture`'s override — so one with no `height=` reserves
-/// its art's texel height, and the next text block hangs that far lower. A floated one (the book's
-/// `align="left"`) still reserves nothing, which is why its text overlaps it in both clients.
+/// An unfloated image reserves `GetHeight()` in the flow (`0x78ad07`), its art's texel height when
+/// it has no `height=`; a floated one reserves nothing, so text runs over it in the reference too.
 #[test]
 fn an_unsized_image_reserves_its_arts_texel_height_unless_it_is_floated() {
     let mut s = script();
@@ -641,12 +587,8 @@ fn an_unsized_image_reserves_its_arts_texel_height_unless_it_is_floated() {
     );
 }
 
-/// A VM with no host oracle has no art to measure, so a zero-size image has **no span on either
-/// axis** — and with one corner pinned and nothing to add to it, it does not resolve at all. That
-/// is the reference's own answer for a texture with no `CGxTex*`: `combineEdge`'s legs both fail
-/// their `span != 0.0` test, `assemble 0x767a20` returns 0, and the texture emits a degenerate
-/// all-zero quad. Stated so the
-/// engine-less path cannot quietly go back to borrowing the page's width.
+/// With no size oracle a zero-size image has no span and does not resolve, as in the reference for
+/// a texture with no `CGxTex*`: `assemble 0x767a20` returns 0 and the quad is all zeros.
 #[test]
 fn without_a_size_oracle_an_unsized_image_does_not_resolve() {
     let mut s = script();
@@ -666,12 +608,9 @@ fn without_a_size_oracle_an_unsized_image_does_not_resolve() {
     );
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The Lua table
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The Lua table ──
 
-/// The 19 names of `.data 0x87ba80`, and only those 19 — `GetText` is **not** one of them in
-/// build 5875, and a name a table does not carry is as wrong as a missing one.
+/// The 19 names of `.data 0x87ba80`, and only those: there is no `GetText`.
 #[test]
 fn the_method_table_is_the_nineteen_names() {
     let s = script();
@@ -706,16 +645,15 @@ fn the_method_table_is_the_nineteen_names() {
         !s.eval::<bool>("return H.GetText ~= nil").unwrap(),
         "1.12.1's SimpleHTML table has no GetText"
     );
-    // The names are the SimpleHTML's own — no other widget kind answers them.
+    // The names are the SimpleHTML's own: a Frame does not answer them.
     s.run(r#"F = CreateFrame("Frame")"#).unwrap();
     assert!(!s
         .eval::<bool>("return F.SetHyperlinkFormat ~= nil")
         .unwrap());
 }
 
-/// The optional element-name argument (`0x795d80`): omitting it addresses `P`, the four names are
-/// case-insensitive, and a **string that is not one of the four is not removed** — it becomes the
-/// shared implementation's first real argument.
+/// The optional element name (`0x795d80`): absent means `P`, the four names match in any case, and
+/// any other string stays as the first real argument.
 #[test]
 fn the_element_name_argument_is_optional_case_insensitive_and_non_matching_falls_through() {
     let s = script();
@@ -737,8 +675,7 @@ fn the_element_name_argument_is_optional_case_insensitive_and_non_matching_falls
             .unwrap(),
         ("Fonts\\B.TTF".to_string(), 20.0)
     );
-    // "h4" is not an element: it stays on the stack and is consumed as SetFont's PATH, so this
-    // targets P and sets the face to the literal "h4".
+    // "h4" is no element, so it is `SetFont`'s path and the call targets `P`.
     s.run(r#"H:SetFont("h4", 12)"#).unwrap();
     assert_eq!(
         s.eval::<(String, f32)>("local p, h = H:GetFont(); return p, h")
@@ -747,7 +684,6 @@ fn the_element_name_argument_is_optional_case_insensitive_and_non_matching_falls
     );
 }
 
-/// `SetHyperlinkFormat` governs how an `<A>` is spliced, and takes effect on the next parse.
 #[test]
 fn the_hyperlink_format_shapes_the_a_splice() {
     let s = script();
@@ -767,12 +703,10 @@ fn the_hyperlink_format_shapes_the_a_splice() {
         .unwrap();
     assert_eq!(texts(&s, "Page"), ["see |cff33ff99|Hitem:1|h[this]|h|r"]);
 
-    // A non-string argument raises the reference's own usage string rather than no-opping.
+    // A non-string argument raises the reference's usage string.
     assert!(s.run("Page:SetHyperlinkFormat(7)").is_err());
 }
 
-/// The colour/shadow/justify getters answer per element, and `SetTextColor` reaches the blocks the
-/// next parse builds.
 #[test]
 fn the_paint_setters_land_on_the_element_and_reach_the_next_parse() {
     let s = script();
@@ -791,7 +725,7 @@ fn the_paint_setters_land_on_the_element_and_reach_the_next_parse() {
             .unwrap(),
         (1.0, 0.0, 0.0, 1.0)
     );
-    // P keeps the font object's own colour — the element arg really did scope the write.
+    // `P` keeps the font object's colour: the element argument scoped the write.
     let (r, g, b, _) = s
         .eval::<(f32, f32, f32, f32)>("return Page:GetTextColor(\"P\")")
         .unwrap();
@@ -808,13 +742,9 @@ fn the_paint_setters_land_on_the_element_and_reach_the_next_parse() {
     );
 }
 
-/// **The empty-path fallback substitutes the WHOLE element font, colour included** — so an `H1`
-/// given a colour and nothing else renders in `P`'s colour, and its own red is never drawn.
-///
-/// That is the shape of `0x78ae29`–`0x78ae54`: the register holding `elementFont[elem]` is
-/// *replaced* by `elementFont[0]` before the single `SetFontObject` call, so the test is on the
-/// path and the consequence is on everything. Surprising, faithful, and exactly the sort of thing
-/// a re-implementation gets wrong by merging property-by-property instead.
+/// An element with no font path takes `elementFont[0]` whole, colour included: `0x78ae29` to
+/// `0x78ae54` swap the register before the one `SetFontObject`, so an `H1` given only a colour
+/// draws in `P`'s.
 #[test]
 fn an_element_with_no_font_of_its_own_loses_its_own_colour_too() {
     let s = script();
@@ -826,8 +756,8 @@ fn an_element_with_no_font_of_its_own_loses_its_own_colour_too() {
     "#,
     )
     .unwrap();
-    // The getter still answers the red — the element font really does hold it (`0x795d3e` reads
-    // `[this + idx*4 + 0x350]`, never a block).
+    // The getter still answers red: it reads the element font, never a block (`0x795d3e` reads
+    // `[this + idx*4 + 0x350]`).
     assert_eq!(
         s.eval::<(f32, f32, f32, f32)>("return Page:GetTextColor(\"H1\")")
             .unwrap(),
@@ -839,7 +769,7 @@ fn an_element_with_no_font_of_its_own_loses_its_own_colour_too() {
         "the block took elementFont[0] wholesale, so H1's red never reaches it"
     );
 
-    // Give H1 a path of its own and the fallback stops firing — now the red draws.
+    // With a path of its own, `H1` draws its red.
     s.run(
         r#"
         Page:SetFont("H1", "Fonts\\SKURRI.TTF", 24)
@@ -850,8 +780,7 @@ fn an_element_with_no_font_of_its_own_loses_its_own_colour_too() {
     assert_eq!(block_color(&s, "Page", 0), Some([1.0, 0.0, 0.0, 1.0]));
 }
 
-/// The `vertex_color` of block `i` — a FontString has no texel, so its vertex colour IS the colour
-/// it draws.
+/// Block `i`'s `vertex_color`, which for a FontString is the colour it draws.
 fn block_color(s: &UiScript, name: &str, i: usize) -> Option<[f32; 4]> {
     let lua = s.lua();
     let model = lua.app_data_ref::<Model>().expect("model");
@@ -860,14 +789,9 @@ fn block_color(s: &UiScript, name: &str, i: usize) -> Option<[f32; 4]> {
     model.region_data.get(&st.blocks[i])?.vertex_color
 }
 
-/// The two halves of `SetFontObject`'s severance law, which the element font has to reproduce by
-/// hand because it resolves its object lazily rather than copying the paint at the call:
-///
-/// - a **re-point does not reset** the explicit mask (`CSimpleFont+0x2c`/`CSimpleFontString+0xD4`:
-///   the inheritMask bit a local setter clears is never restored), so a face set on the element
-///   survives being pointed at a different object;
-/// - the **nil form severs the link and leaves the paint standing** — it does not blank the
-///   element.
+/// `SetFontObject` on an element font: a re-point keeps what a local setter set (the inheritMask
+/// bit at `CSimpleFont+0x2c`/`CSimpleFontString+0xD4` is never restored), and nil unlinks the
+/// object but leaves the paint.
 #[test]
 fn set_font_object_keeps_local_overrides_and_the_nil_form_leaves_the_paint_standing() {
     let s = script();
@@ -904,8 +828,8 @@ fn set_font_object_keeps_local_overrides_and_the_nil_form_leaves_the_paint_stand
     );
 }
 
-/// `SetJustifyH` is **inert for rendered text** — the byte law, not a gap: `0x78adb0` overwrites
-/// every block's justifyH with the tag's `align`. The getter still answers what was stored.
+/// `0x78adb0` gives every block its tag's `align`, so `SetJustifyH` is stored and answered but
+/// never drawn.
 #[test]
 fn set_justify_h_is_stored_and_answered_but_never_drawn() {
     let s = script();
@@ -926,13 +850,11 @@ fn set_justify_h_is_stored_and_answered_but_never_drawn() {
         "LEFT",
         "the tag's absent align (LEFT) wins over the element font's justify"
     );
-    // A non-token raises, exactly as `0x87c77c`'s usage arm does.
+    // A non-token raises the usage string (`0x87c77c`).
     assert!(s.run(r#"Page:SetJustifyH("sideways")"#).is_err());
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Helpers that need the resolve
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Helpers that need the resolve ──
 
 /// Every block's resolved `(top, bottom)`, in block order.
 fn resolved_tops(s: &UiScript, name: &str) -> Vec<(f32, f32)> {
@@ -949,7 +871,6 @@ fn resolved_tops(s: &UiScript, name: &str) -> Vec<(f32, f32)> {
         .collect()
 }
 
-/// One block's resolved rect if it HAS one — the shape a region with no span reaches.
 fn maybe_resolved_rect(s: &UiScript, name: &str, block: usize) -> Option<crate::layout::Rect> {
     let lua = s.lua();
     let model = lua.app_data_ref::<Model>().expect("model");
@@ -958,7 +879,6 @@ fn maybe_resolved_rect(s: &UiScript, name: &str, block: usize) -> Option<crate::
     model.region_resolved.get(&st.blocks[block]).copied()
 }
 
-/// One block's resolved rect, by index in the block list.
 fn resolved_rect(s: &UiScript, name: &str, block: usize) -> crate::layout::Rect {
     let lua = s.lua();
     let model = lua.app_data_ref::<Model>().expect("model");
@@ -970,7 +890,7 @@ fn resolved_rect(s: &UiScript, name: &str, block: usize) -> crate::layout::Rect
         .expect("block rect")
 }
 
-/// The text of every quad the extract emits for the page — what is actually on screen.
+/// The text of every quad the extract emits: what is on screen.
 fn page_texts_on_screen(s: &UiScript) -> Vec<String> {
     s.extract()
         .into_iter()
@@ -981,8 +901,7 @@ fn page_texts_on_screen(s: &UiScript) -> Vec<String> {
         .collect()
 }
 
-/// A Rust string as a Lua long-bracket literal — the bodies here are full of quotes and
-/// backslashes, and escaping them twice is how a test asserts on the wrong string.
+/// A Rust string as a Lua long-bracket literal, so quotes and backslashes need no second escape.
 fn lua_str(s: &str) -> String {
     format!("[==[{s}]==]")
 }
diff --git a/crates/benilla-ui/src/script/tests/size_changed.rs b/crates/benilla-ui/src/script/tests/size_changed.rs
index 8ddb5af0..cd950a35 100644
--- a/crates/benilla-ui/src/script/tests/size_changed.rs
+++ b/crates/benilla-ui/src/script/tests/size_changed.rs
@@ -1,16 +1,11 @@
-//! `OnSizeChanged` — the base-map layout script (`0x76a0d0` `+0x120`), fired from the resolve pass.
-//!
-//! Two things are being pinned here, and they are different in kind. The **gate** is byte-verified:
-//! `ApplyRect 0x76b580` fires iff `|Δwidth| ≥ ε ∨ |Δheight| ≥ ε` with `ε = _DAT_008029d4`
-//! ([`crate::layout::SIZE_EPS`]), which is why a frame that merely MOVES fires nothing. The
-//! **seam** is ours: the client applies rects one at a time and fires per application, benilla
-//! solves the whole graph to a fixpoint, so we fire on the entry-vs-convergence diff — one fire per
-//! resolve per frame whose size actually moved, never one per solver round.
+//! `OnSizeChanged`, the base-map layout script (`0x76a0d0` `+0x120`). `ApplyRect 0x76b580` fires
+//! it only when width or height moves by `ε = _DAT_008029d4` ([`crate::layout::SIZE_EPS`]).
+//! Deviation: the client fires per rect application; we fire once per resolve on the size before
+//! and after, because our solver settles the whole graph to a fixpoint.
 
 use super::common::script;
 
-/// The size moves ⇒ `OnSizeChanged(self, width, height)` fires with the NEW size; a pure move fires
-/// nothing (the byte-verified gate is on width/height, not on the rect).
+/// `OnSizeChanged(self, width, height)` carries the new size.
 #[test]
 fn a_resize_fires_on_size_changed_and_a_move_does_not() {
     let mut s = script();
@@ -28,18 +23,15 @@ fn a_resize_fires_on_size_changed_and_a_move_does_not() {
     )
     .unwrap();
 
-    // The FIRST layout is a change too: the client's cached rect starts zeroed, so its first
-    // ApplyRect is 0×0 → 200×50 and does fire.
+    // The client's cached rect starts zeroed, so the first layout fires too.
     s.resolve();
     assert_eq!(s.eval::<i64>("return fires").unwrap(), 1);
     assert_eq!(s.eval::<f64>("return w").unwrap(), 200.0);
     assert_eq!(s.eval::<f64>("return h").unwrap(), 50.0);
 
-    // A second resolve with nothing touched fires nothing — the size did not move.
     s.resolve();
     assert_eq!(s.eval::<i64>("return fires").unwrap(), 1);
 
-    // A MOVE is not a resize.
     s.run(r#"Panel:SetPoint("BOTTOMLEFT", 400, 300)"#).unwrap();
     s.resolve();
     assert_eq!(
@@ -48,7 +40,6 @@ fn a_resize_fires_on_size_changed_and_a_move_does_not() {
         "the rect moved but width/height did not — ApplyRect's gate is on the size alone"
     );
 
-    // A real resize does.
     s.run("Panel:SetHeight(120)").unwrap();
     s.resolve();
     assert_eq!(s.eval::<i64>("return fires").unwrap(), 2);
@@ -57,10 +48,7 @@ fn a_resize_fires_on_size_changed_and_a_move_does_not() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// It fires for a size the frame did not set on itself — the case the corpus actually uses it for
-/// (`MoveAnything`, `CleanMinimap`, `FuBar`, `Outfitter`, `AckisRecipeList` all watch a frame whose
-/// size is decided by something else). Here the child is anchored to two edges of a parent that
-/// resizes, so its own `LayoutInput` never changes at all and only the SOLVE knows it moved.
+/// Addons watch frames sized by their anchors; only the solve knows this child moved.
 #[test]
 fn an_anchor_driven_resize_fires_it_too() {
     let mut s = script();
@@ -93,11 +81,8 @@ fn an_anchor_driven_resize_fires_it_too() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **The loop guard.** A handler that resizes its own frame is the classic `OnSizeChanged` hazard,
-/// and it must not spin the engine. The drain takes ONE batch per resolve
-/// ([`crate::script::event::fire_size_changes`]), so a handler that settles on a constant size
-/// settles — one extra fire for the size it forced, then silence — and one that never settles costs
-/// one fire per resolve rather than hanging inside a single call.
+/// The drain takes one batch per resolve ([`crate::script::event::fire_size_changes`]), so a
+/// handler that resizes its own frame costs one fire per resolve instead of hanging.
 #[test]
 fn a_handler_that_resizes_its_own_frame_settles_instead_of_spinning() {
     let mut s = script();
@@ -117,14 +102,12 @@ fn a_handler_that_resizes_its_own_frame_settles_instead_of_spinning() {
     )
     .unwrap();
 
-    // Resolve returns (does not hang) even though the handler dirties the layout from inside it.
     s.resolve();
     assert_eq!(s.eval::<i64>("return fires").unwrap(), 1);
-    // The next resolve sees the handler's own 200×200 and fires once for it…
+    // The next resolve fires once for the handler's own 200×200.
     s.resolve();
     assert_eq!(s.eval::<i64>("return fires").unwrap(), 2);
     assert_eq!(s.eval::<f64>("return Sq:GetHeight()").unwrap(), 200.0);
-    // …and then it is stable: no further fires, however many passes run.
     for _ in 0..5 {
         s.resolve();
     }
@@ -136,9 +119,6 @@ fn a_handler_that_resizes_its_own_frame_settles_instead_of_spinning() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The regression guard that makes the `SCRIPT_KINDS` row real: `SetScript("OnSizeChanged", …)`
-/// stopped raising, and what replaced the error is a handler that actually runs — not a stored
-/// closure nobody ever calls.
 #[test]
 fn set_script_on_size_changed_is_accepted_because_the_resolve_pass_fires_it() {
     let mut s = script();
@@ -160,15 +140,8 @@ fn set_script_on_size_changed_is_accepted_because_the_resolve_pass_fires_it() {
     assert!(s.eval::<bool>("return ran").unwrap(), "…and it FIRED");
 }
 
-/// **The watch list is exactly the frames carrying the script.** The resolve's "before" snapshot
-/// reads `SetScript`'s maintained `on_size_changed_frames` rather than filtering the whole scripts
-/// map (decision 1634), so the list itself is now load-bearing: `SetScript(…, nil)` must remove
-/// the frame, and re-registering must not enrol it twice.
-///
-/// Asserted on the LIST, not on the fire count, and that is the point. A stale entry fires nothing
-/// — `fire` looks the handler up in Lua and finds nil — so behaviour hides the bug completely and
-/// the only symptom is the snapshot silently growing forever, one dead frame at a time. (Written
-/// as a fire-count test first; it passed with the `retain` deleted.)
+/// The resolve snapshots `on_size_changed_frames`, which `SetScript` maintains. Asserted on the
+/// list itself: a stale entry fires nothing, so only the list would show it.
 #[test]
 fn the_on_size_changed_watch_list_is_exactly_the_frames_carrying_the_script() {
     use crate::script::model::Model;
diff --git a/crates/benilla-ui/src/script/tests/slider.rs b/crates/benilla-ui/src/script/tests/slider.rs
index be561873..dc66bc6d 100644
--- a/crates/benilla-ui/src/script/tests/slider.rs
+++ b/crates/benilla-ui/src/script/tests/slider.rs
@@ -1,12 +1,10 @@
-//! Slider (per-kind behavior; LoadXML `0x789580`, decision 0250). The value/step/orientation
-//! contract, the VERTICAL ctor default, the no-swap divergence from StatusBar, and the change-gate
-//! that keeps the real scrollbar wiring from recursing.
+//! Slider (LoadXML `0x789580`): value, step and orientation, the vertical default, the unswapped
+//! min/max, the value quantiser, and the change gate that keeps scrollbar wiring from recursing.
 
 use super::common::script;
 use crate::script::QuadContent;
 
-/// Find the thumb quad (the texture whose path carries `needle`) and return its
-/// `(left, right, bottom, top)` rect. Panics if absent — the render must emit it.
+/// The `(left, right, bottom, top)` rect of the thumb quad whose texture path contains `needle`.
 fn thumb_rect(quads: &[crate::script::ExtractedQuad], needle: &str) -> (f32, f32, f32, f32) {
     let q = quads
         .iter()
@@ -37,15 +35,14 @@ fn slider_thumb_draws_at_value_fraction_along_the_track() {
     )
     .unwrap();
     s.resolve();
-    // value=min: the thumb sits flush at the track TOP (a scrollbar at 0 is scrolled to the top).
-    // travel = 100 - 16 = 84; thumb centered on cx=108 -> [100,116], top edge at track.top=200.
+    // value=min puts the thumb flush at the track top (a scrollbar at 0 is scrolled up); travel
+    // 100 - 16 = 84, thumb centered on x=108 -> [100,116], top edge at 200.
     assert_eq!(
         thumb_rect(&s.extract(), "Knob"),
         (100.0, 116.0, 184.0, 200.0),
         "value=min: thumb flush at track top, centered on the cross-axis"
     );
 
-    // value=max: the thumb sits flush at the track BOTTOM.
     s.run(r#"SlRender:SetValue(100)"#).unwrap();
     assert_eq!(
         thumb_rect(&s.extract(), "Knob"),
@@ -53,7 +50,6 @@ fn slider_thumb_draws_at_value_fraction_along_the_track() {
         "value=max: thumb flush at track bottom"
     );
 
-    // Halfway: thumb centered in the track (midpoint 150).
     s.run(r#"SlRender:SetValue(50)"#).unwrap();
     let (_, _, bottom, top) = thumb_rect(&s.extract(), "Knob");
     assert_eq!(
@@ -65,8 +61,7 @@ fn slider_thumb_draws_at_value_fraction_along_the_track() {
 
 #[test]
 fn slider_thumb_drag_maps_cursor_to_value() {
-    // The same vertical scrollbar as the render test: track y in [100, 200], 16x16 thumb. At value=0
-    // the thumb spans y[184,200] (its top edge at the track top), centered on x=108.
+    // The render test's scrollbar: track y in [100, 200]; at value 0 the thumb spans y[184,200].
     let mut s = script();
     s.set_screen_size(1024.0, 768.0);
     s.run(
@@ -83,8 +78,7 @@ fn slider_thumb_drag_maps_cursor_to_value() {
     .unwrap();
     s.resolve();
 
-    // Grab the thumb at its center (108, 192) and drag down the track. travel = 84; the grab keeps
-    // the same thumb point under the cursor, so the value tracks the cursor absolutely.
+    // Grab the thumb's center (108, 192); the grab keeps that thumb point under the cursor.
     s.mouse_button(108.0, 192.0, "LeftButton", true);
     s.mouse_move(108.0, 150.0);
     let v: f32 = s.eval("return SlDrag:GetValue()").unwrap();
@@ -96,7 +90,6 @@ fn slider_thumb_drag_maps_cursor_to_value() {
         "cursor at the track bottom -> value 100 (clamped)"
     );
 
-    // Release ends the capture: a later move must not move the value.
     s.mouse_button(108.0, 108.0, "LeftButton", false);
     s.mouse_move(108.0, 192.0);
     let v: f32 = s.eval("return SlDrag:GetValue()").unwrap();
@@ -123,10 +116,8 @@ fn slider_track_press_seats_the_thumb_and_a_mouseless_slider_ignores_it() {
     .unwrap();
     s.resolve();
 
-    // A press on the TRACK below the thumb (108, 120) — inside the slider, not on the thumb
-    // [184,200] — SEATS the thumb's center under the cursor and fires OnValueChanged from the
-    // press itself (0989's track-press law; 0250 §5 covered only the thumb grab). Track
-    // y in [100, 200], travel 84: cursor 120 → thumb top 128 → fraction (200−128)/84 = 72/84.
+    // A press on the track below the thumb seats the thumb's center under the cursor and fires
+    // OnValueChanged from the press: cursor 120 → thumb top 128 → fraction (200−128)/84 = 72/84.
     s.mouse_button(108.0, 120.0, "LeftButton", true);
     let v: f32 = s.eval("return SlTrack:GetValue()").unwrap();
     assert!(
@@ -136,17 +127,13 @@ fn slider_track_press_seats_the_thumb_and_a_mouseless_slider_ignores_it() {
     let n: usize = s.eval("return table.getn(fired)").unwrap();
     assert_eq!(n, 1, "the jump fired OnValueChanged once, from the press");
 
-    // The SAME press keeps dragging — the capture began at the track press.
     s.mouse_move(108.0, 108.0);
     let v: f32 = s.eval("return SlTrack:GetValue()").unwrap();
     assert_eq!(v, 100.0, "the gesture drags on without re-grabbing");
     s.mouse_button(108.0, 108.0, "LeftButton", false);
 
-    // A slider the mouse cannot reach ignores a press anywhere — thumb and track alike. This was
-    // `SlTrack:Disable()` until the Button-only `Enable`/`Disable`/`IsEnabled` trio came off the
-    // Slider table (1.12 registers them on `0x879d00` alone, and the Slider's LoadXML has no
-    // `enabled` attribute either). `EnableMouse(false)` is how the reference keeps a slider off a
-    // press, and it gates upstream in the hit test rather than inside `begin_drag`.
+    // A mouse-disabled slider ignores a press on thumb and track alike. A 1.12 Slider has no
+    // `Disable`: the trio is registered on the Button table (`0x879d00`) alone.
     s.run(r#"SlTrack:SetValue(0); SlTrack:EnableMouse(false); fired = {}"#)
         .unwrap();
     for y in [192.0, 150.0] {
@@ -184,8 +171,8 @@ fn slider_methods_exist_only_on_sliders() {
 
 #[test]
 fn slider_default_orientation_is_vertical() {
-    // The load-bearing fact of decision 0250: every scrollbar omits `orientation` and is vertical,
-    // so the CSimpleSlider ctor default is VERTICAL — the opposite of StatusBar's HORIZONTAL.
+    // Every scrollbar omits `orientation` and is vertical, so the CSimpleSlider default is
+    // `VERTICAL`, where StatusBar's is `HORIZONTAL`.
     let s = script();
     s.run(
         r#"
@@ -242,11 +229,8 @@ fn slider_setvalue_fires_onvaluechanged_only_on_change() {
     .unwrap();
 }
 
-/// `Enable`/`Disable`/`IsEnabled` are a **Button** trio in 1.12 (table `0x879d00`), and a Slider
-/// must not answer them: a duck-typing addon that branches on `if widget.IsEnabled then` reads a
-/// superset as the wrong class (1189/1250 §5). This asserts the removal *and* its control — the
-/// same three names still present on a Button, so a regression that emptied the Button table would
-/// fail here rather than pass by accident.
+/// `Enable`/`Disable`/`IsEnabled` are Button methods in 1.12 (table `0x879d00`), so a Slider must
+/// not answer them: addons duck-type on `if widget.IsEnabled then`. A Button is the control.
 #[test]
 fn a_slider_does_not_answer_the_buttons_enable_trio() {
     let s = script();
@@ -288,11 +272,9 @@ fn slider_get_thumb_texture_returns_a_stable_region() {
 
 #[test]
 fn slider_scrollbar_wiring_does_not_recurse() {
-    // The real FauxScrollFrame wiring (UIPanelTemplates.xml): the scrollbar Slider's OnValueChanged
-    // drives the ScrollFrame's SetVerticalScroll, whose OnVerticalScroll drives the Slider's
-    // SetValue back the other way. A fire-always SetValue would recurse forever; the change-gate
-    // (SliderState::store_value returns Some only on an actual change) breaks the loop after one hop.
-    // This test *is* the recursion — if the gate regressed it would stack-overflow, not assert-fail.
+    // Stock wiring: the slider's OnValueChanged scrolls the frame (`UIPanelTemplates.xml:157`),
+    // whose OnVerticalScroll sets the slider back (`:193`). The change gate
+    // (`SliderState::store_value`) ends it after one hop; without it the stack overflows.
     let mut s = script();
     s.set_screen_size(1024.0, 768.0);
     s.run(
@@ -325,12 +307,9 @@ fn slider_scrollbar_wiring_does_not_recurse() {
 
 #[test]
 fn slider_value_bits_gate_the_first_fire_and_the_range_reclamp() {
-    // The client's `+0x314` bit1 (has a range) and bit2 (has a value), byte-read off
-    // `SetValue 0x789930` / `SetMinMaxValues 0x7898f0`:
-    // rangeless SetValue is a no-op; the FIRST SetValue always fires, even at the zero-init value;
-    // SetMinMaxValues re-clamps through SetValue only once a value exists. Decision 2095 — Atlas's
-    // option sliders raised from their own <OnLoad> because our SetMinMaxValues clamped the
-    // zero-init value into (0.25, 1) and ran a handler the addon had not armed yet.
+    // The reference's `+0x314` bit1 (has a range) and bit2 (has a value), from `SetValue`
+    // (`0x789930`) and `SetMinMaxValues` (`0x7898f0`): a rangeless SetValue is a no-op, the
+    // first SetValue always fires, and SetMinMaxValues re-clamps only once a value exists.
     let s = script();
     s.run(
         r#"
@@ -364,10 +343,8 @@ fn slider_value_bits_gate_the_first_fire_and_the_range_reclamp() {
 
 #[test]
 fn slider_onload_range_does_not_run_an_unarmed_onvaluechanged() {
-    // Atlas's exact shape (AtlasOptions.xml): the slider's <OnLoad> sets a range whose low end is
-    // above zero, and its <OnValueChanged> indexes a saved-variables global that only exists after
-    // ADDON_LOADED. In the reference the load raises nothing; before 2095 ours raised
-    // "attempt to index global 'AtlasOptions' (a nil value)" out of the OnLoad.
+    // Atlas's options slider (`AtlasOptions.xml`): its `<OnValueChanged>` reads a saved variable
+    // that exists only after ADDON_LOADED; in the reference the `<OnLoad>` range raises nothing.
     let mut s = script();
     let doc = crate::framexml::parse(
         r#"<Ui>
@@ -398,14 +375,10 @@ fn slider_onload_range_does_not_run_an_unarmed_onvaluechanged() {
 
 #[test]
 fn a_thumb_with_no_authored_size_takes_its_arts_texel_span_and_still_drags() {
-    // Dewdrop-2.0's `OpenSlider` (Cartographer 2.02 → Look 'n' Feel → Overlay transparency), in
-    // its own construction order — the shape that has no `<ThumbTexture><Size>` anywhere:
-    // `SetThumbTexture(path)` from Lua and nothing else. The reference asks the thumb for its own
-    // `GetWidth`/`GetHeight` (`0x789ba0` → `[thumb_vt+0x1c]/[+0x20]` = `CSimpleTexture::0x770720`
-    // /`0x770790`), which falls back to the art's native texel span — 32×32 for
-    // `UI-SliderBar-Button-Vertical` — so the thumb is a 32-unit knob on a 128-unit track with
-    // 96 units of travel. Ours read the *authored* size only and, finding none, sized the thumb to
-    // the whole track: zero travel, a thumb smeared over the bar, and a drag that cannot move.
+    // Dewdrop-2.0's `OpenSlider`, in its construction order: `SetThumbTexture(path)` and no size.
+    // The reference sizes the thumb by its own `GetWidth`/`GetHeight` (`0x789ba0` calls
+    // `0x770720`, `0x770790`), which fall back to the art's texel span: 32×32 for
+    // `UI-SliderBar-Button-Vertical`, leaving 96 units of travel on the 128-unit track.
     let mut s = script();
     s.set_screen_size(1024.0, 768.0);
     s.set_texture_size_probe(Box::new(|p| {
@@ -449,7 +422,7 @@ fn a_thumb_with_no_authored_size_takes_its_arts_texel_span_and_still_drags() {
         "a sizeless thumb is its art's 32×32, flush at the track top — not the whole 16×128 track"
     );
 
-    // And it drags: grab the thumb at its centre and pull to the bottom of the track.
+    // Grab the thumb at its centre and pull to the bottom of the track.
     s.mouse_button(123.0, 233.0, "LeftButton", true);
     s.mouse_move(123.0, 137.0);
     let v: f32 = s.eval("return DdSlider:GetValue()").unwrap();
@@ -461,10 +434,8 @@ fn a_thumb_with_no_authored_size_takes_its_arts_texel_span_and_still_drags() {
 
 #[test]
 fn slider_setvalue_quantises_onto_the_min_anchored_lattice() {
-    // `SetValue 0x789930` rounds the clamped value onto `min + n·step` (round-half-away-from-zero,
-    // truncated by `__ftol`) BEFORE it stores — so `GetValue` on a stepped slider can only ever
-    // answer a lattice point, and the lattice is anchored at `min`, not at zero. Decision 2095
-    // named this divergence and left it; this is it closed.
+    // `SetValue` (`0x789930`) rounds the clamped value onto `min + n·step` (half away from zero,
+    // then `__ftol`) before storing, so the lattice is anchored at `min`, not at zero.
     let s = script();
     s.run(
         r#"
@@ -474,8 +445,7 @@ fn slider_setvalue_quantises_onto_the_min_anchored_lattice() {
     "#,
     )
     .unwrap();
-    // The lattice is 0.2 / 0.7 / 1.2 — 0.5 and 1.0 are NOT on it, which is the whole point of
-    // anchoring at `min`.
+    // The lattice is 0.2, 0.7, 1.2; 0.5 and 1.0 are not on it.
     for (set, want) in [
         (0.6, 0.7),
         (0.95, 0.7),
@@ -495,9 +465,8 @@ fn slider_setvalue_quantises_onto_the_min_anchored_lattice() {
 
 #[test]
 fn a_zero_step_leaves_the_value_continuous() {
-    // The gate that keeps every scrollbar working: `UIPanelScrollBarTemplate` declares no
-    // `valueStep`, so `[+0x324]` stays at the ctor's 0.0 and `0x78999c`'s `fcomp(step, 0.0)`
-    // skips the quantiser outright. A stepless slider stores exactly what it was handed.
+    // `UIPanelScrollBarTemplate` declares no `valueStep`, so `[+0x324]` stays at the constructor's
+    // 0.0 and `0x78999c` skips the quantiser: a stepless slider stores what it is handed.
     let s = script();
     s.run(
         r#"
@@ -515,11 +484,9 @@ fn a_zero_step_leaves_the_value_continuous() {
 
 #[test]
 fn the_quantised_value_is_not_re_clamped_and_may_pass_max() {
-    // The clamp runs BEFORE the quantiser and there is no second clamp after it (`0x789a06`
-    // stores whatever `fild n; fmul step; fadd min` produced). So a range that is not a whole
-    // number of steps rounds *past* its own max at the top of the travel. This looks like a bug
-    // and is the client's arithmetic; it is unreachable in the shipped UI because every stepped
-    // slider the reference ships is an exact multiple of its step.
+    // The clamp runs before the quantiser and nothing clamps after it (`0x789a06` stores
+    // `min + n·step` as computed), so a range that is not a whole number of steps rounds past
+    // its max. This looks like a bug but is the reference's arithmetic; no stock slider hits it.
     let s = script();
     s.run(
         r#"
@@ -542,11 +509,9 @@ fn the_quantised_value_is_not_re_clamped_and_may_pass_max() {
 
 #[test]
 fn a_faux_scrollframes_rows_snap_and_its_bottom_is_exact() {
-    // The falsifier decision 2095 named for this change, run on the shape it names.
-    // `FauxScrollFrame_Update` builds its range as `(numItems − numToDisplay) · valueStep`
-    // (`UIPanelTemplates.lua:180`) and then sets that same step, so the range IS a whole number
-    // of steps: every drag lands on a row boundary and the bottom of the travel is exactly max.
-    // 20 items, 10 on screen, 16 units a row ⇒ range 0..160, step 16.
+    // `FauxScrollFrame_Update` sets the range `(numItems − numToDisplay) · valueStep` and that
+    // same step (`UIPanelTemplates.lua:180`), so every drag lands on a row and the bottom is
+    // exactly max. 20 items, 10 on screen, 16 units a row: range 0..160, step 16.
     let s = script();
     s.run(
         r#"
@@ -560,13 +525,13 @@ fn a_faux_scrollframes_rows_snap_and_its_bottom_is_exact() {
         (23.9, 16.0), // just under the half-step boundary: the row below
         (24.1, 32.0), // just over it: the row above
         (37.0, 32.0),
-        (160.0, 160.0), // the bottom is exact — no overshoot, the range is 10 steps
+        (160.0, 160.0), // the bottom is exact: the range is 10 steps
         (0.0, 0.0),
     ] {
         s.run(&format!("SlFaux:SetValue({set})")).unwrap();
         let v: f32 = s.eval("return SlFaux:GetValue()").unwrap();
         assert_eq!(v, want, "SetValue({set}) snaps to the row at {want}");
-        // FauxScrollFrame_GetOffset's own arithmetic, which is what the row list reads.
+        // The row offset; stock rounds it (`UIPanelTemplates.lua:231`), equal on a snapped value.
         let off: f32 = s.eval("return floor(SlFaux:GetValue() / 16)").unwrap();
         assert_eq!(off, (want / 16.0).floor(), "and the row offset follows it");
     }
@@ -574,10 +539,8 @@ fn a_faux_scrollframes_rows_snap_and_its_bottom_is_exact() {
 
 #[test]
 fn a_move_inside_one_step_fires_nothing() {
-    // The quantiser sits INSIDE the change-gate (`0x789a0b`'s `fcom` is against the stored value,
-    // and what is stored is already quantised), so a drag that stays within one step's band
-    // resolves to the same lattice point and never reaches `OnValueChanged`. Before this, every
-    // pixel of a stepped drag fired.
+    // The change gate compares against the stored, already quantised value (`0x789a0b`), so a
+    // drag within one step's band never reaches `OnValueChanged`.
     let s = script();
     s.run(
         r#"
@@ -609,9 +572,8 @@ fn a_move_inside_one_step_fires_nothing() {
 
 #[test]
 fn set_value_step_re_quantises_the_held_value_and_can_fire() {
-    // `SetValueStep 0x789a60` stores the step and then re-pushes the range through
-    // `SetMinMaxValues`, which re-clamps the held value through `SetValue` — onto the NEW lattice
-    // (decision 2143). A step handed to a slider that already holds a value moves it and fires.
+    // `SetValueStep` (`0x789a60`) stores the step and re-pushes the range, which re-clamps a held
+    // value through `SetValue` onto the new lattice, and that move fires.
     let s = script();
     s.run(
         r#"
@@ -626,7 +588,7 @@ fn set_value_step_re_quantises_the_held_value_and_can_fire() {
     assert_eq!(s.eval::<f32>("return SlStep:GetValue()").unwrap(), 37.0);
     assert_eq!(s.eval::<i64>("return fires").unwrap(), 1);
 
-    // A step arriving AFTER the value snaps it: 37 → 40 on a 10-lattice, and the move fires.
+    // A step arriving after the value snaps it: 37 → 40 on a 10-lattice.
     s.run("SlStep:SetValueStep(10)").unwrap();
     assert_eq!(
         s.eval::<f32>("return SlStep:GetValue()").unwrap(),
@@ -639,7 +601,6 @@ fn set_value_step_re_quantises_the_held_value_and_can_fire() {
         "…and the move fired OnValueChanged, exactly as a SetValue would"
     );
 
-    // A step that moves nothing fires nothing — the same change gate, one level up.
     s.run("SlStep:SetValueStep(20)").unwrap();
     assert_eq!(s.eval::<f32>("return SlStep:GetValue()").unwrap(), 40.0);
     assert_eq!(s.eval::<i64>("return fires").unwrap(), 2);
@@ -647,10 +608,8 @@ fn set_value_step_re_quantises_the_held_value_and_can_fire() {
 
 #[test]
 fn a_step_before_any_range_is_the_whole_call() {
-    // `0x789a6c test byte [+0x314],2` — bit1 clear ⇒ the step is stored and the function returns.
-    // No range is pushed, nothing is clamped, nothing fires. It is what keeps an `<OnLoad>` that
-    // sets a step before a range from running a handler the addon has not armed (2095's subject,
-    // one verb over).
+    // With no range (bit1 clear at `0x789a6c`) the step is stored and nothing else happens, so an
+    // `<OnLoad>` that sets a step before a range runs no handler.
     let s = script();
     s.run(
         r#"
diff --git a/crates/benilla-ui/src/script/tests/statusbar.rs b/crates/benilla-ui/src/script/tests/statusbar.rs
index 1e8c446a..62eb5925 100644
--- a/crates/benilla-ui/src/script/tests/statusbar.rs
+++ b/crates/benilla-ui/src/script/tests/statusbar.rs
@@ -1,4 +1,4 @@
-//! StatusBar (per-kind behavior; LoadXML `0x782ef0`).
+//! StatusBar behaviour (`LoadXML` `0x782ef0`).
 
 use super::common::script;
 use crate::script::*;
@@ -126,9 +126,8 @@ fn statusbar_bar_region_scales_by_fraction_on_extract() {
     );
 }
 
-/// The fill CROPs its art, never squeezes it (`0x770410`): `SetValue`
-/// rewrites the region's 4-corner UV block with `u1 = GetValue()` *and* shrinks the quad. Squeezing
-/// instead would run a bar texture's whole horizontal ramp inside every partial fill.
+/// The fill crops its art, never squeezes it (`0x770410`): `SetValue` sets the UV `u1` to the fill
+/// fraction `(value - min) / (max - min)` and shrinks the quad by the same fraction.
 #[test]
 fn statusbar_bar_region_crops_its_texture_rather_than_stretching_it() {
     let mut s = script();
@@ -164,7 +163,7 @@ fn statusbar_bar_region_crops_its_texture_rather_than_stretching_it() {
         "horizontal: u cropped to the fill fraction, v whole"
     );
 
-    // Vertical fills bottom-up, so the art's BOTTOM edge is the one pinned.
+    // Vertical fills bottom-up, so the art's bottom edge is pinned.
     s.run(r#"SbCrop:SetOrientation("VERTICAL")"#).unwrap();
     assert_eq!(
         uv(&s),
diff --git a/crates/benilla-ui/src/script/tests/stdlib.rs b/crates/benilla-ui/src/script/tests/stdlib.rs
index fea7e0dd..c53ff6b0 100644
--- a/crates/benilla-ui/src/script/tests/stdlib.rs
+++ b/crates/benilla-ui/src/script/tests/stdlib.rs
@@ -1,9 +1,9 @@
-//! The WoW stdlib: positional `format`, the `getglobal` alias layer, and the
-//! sandbox holes (`loadstring` text-only, dangerous globals removed).
+//! The WoW stdlib: positional `format`, the bare-global aliases, the sandbox, `debugstack`,
+//! `GetTime`, `time`/`date`, `RunScript` and the Lua 5.0 dialect.
 
 use super::common::script;
 
-// ── The positional format wrapper ───────────────────────────────────────────────────────────────
+// ── The positional format wrapper ──
 
 #[test]
 fn positional_format_reorders_and_mix_is_an_error() {
@@ -18,7 +18,7 @@ fn positional_format_reorders_and_mix_is_an_error() {
         s.eval::<String>(r#"return format("%1$05d", 42)"#).unwrap(),
         "00042"
     );
-    // sequential still works (and via string.format too, which we patched)
+    // sequential still works, through the patched `string.format` too
     assert_eq!(
         s.eval::<String>(r#"return string.format("%d-%s", 1, "x")"#)
             .unwrap(),
@@ -29,14 +29,14 @@ fn positional_format_reorders_and_mix_is_an_error() {
         s.eval::<String>(r#"return format("%1$d%%", 50)"#).unwrap(),
         "50%"
     );
-    // mixing positional and sequential is an error (matches Blizzard erroring)
+    // mixing positional and sequential is an error, as in the reference
     let mixed_ok: bool = s
         .eval(r#"return pcall(format, "%1$s %s", "a", "b")"#)
         .unwrap();
     assert!(!mixed_ok, "mixed positional+sequential must error");
 }
 
-// ── getglobal / the alias layer ───────────────────────────────────────────────
+// ── getglobal and the alias layer ──
 
 #[test]
 fn stdlib_aliases_and_helpers() {
@@ -65,7 +65,7 @@ fn stdlib_aliases_and_helpers() {
     .unwrap();
 }
 
-// ── Sandbox holes ───────────────────────────────────────────────────────────────────────────────
+// ── Sandbox holes ──
 
 #[test]
 fn sandbox_removes_dangerous_globals() {
@@ -77,39 +77,24 @@ fn sandbox_removes_dangerous_globals() {
         )
         .unwrap();
     assert!(all_nil);
-    // `debugstack` survives the sandbox — and returns a REAL traceback, not the `""` this used to
-    // assert. The stub was fine for addons that only DISPLAY it and wrong for the ones that PARSE
-    // it: `FuBarPlugin-2.0.lua:752` finds each plugin's own folder in `debugstack(6, 1, 0)`, and
-    // against `""` that returned nil and killed 20 corpus addons.
+    // `debugstack` survives the sandbox and returns a real traceback, which addons parse.
     let trace = s.eval::<String>("return debugstack()").unwrap();
     assert!(
         !trace.is_empty(),
         "debugstack must return a real traceback: {trace:?}"
     );
-    // **Frames only — no `stack traceback:` header** (decision 2121). Line 1 IS a frame, which is
-    // what `AceLibrary.lua:70` reads (`string.gsub(stack, "\n.*", "")` then
-    // `".*\\(.*).lua:%d+: .*"`), and what `AceDB-2.0.lua:742` counts on when it skips exactly one
-    // line to reach its caller's.
+    // Frames only, no `stack traceback:` header: `AceLibrary.lua:70` reads line 1 as a frame and
+    // `AceDB-2.0.lua:742` skips exactly one line to reach its caller.
     assert!(
         !trace.starts_with("stack traceback"),
         "the reference has no header line: {trace:?}"
     );
-    // A level far past the top of the stack is an empty string, never a raise — a caller that
-    // guesses too deep still gets something it can `string.find` against.
+    // A level past the top of the stack is an empty string, never a raise.
     assert_eq!(s.eval::<String>("return debugstack(99)").unwrap(), "");
 }
 
-/// **AceDB-2.0's own capture, run for real across two chunks** (decision 2121).
-///
-/// `RegisterDB` reads the calling addon's folder out of `debugstack()` by skipping exactly one
-/// line — its own frame — and taking the `\AddOns\<folder>\` out of the next. That only works if
-/// line 1 is a frame; with mlua's `stack traceback:` header in front, the capture returned the
-/// folder of whichever addon shipped the winning copy of the library, `RegisterDB` took its
-/// already-loaded branch, and `db.raw` was bound to a fresh table at the addon's file scope —
-/// before the SavedVariables chunk ran. Bartender2 then printed `Creating new DB` at every login.
-///
-/// The two chunks here are the real configuration: the library lives in one addon's folder, the
-/// caller in another's.
+/// AceDB-2.0's `RegisterDB` skips one line of `debugstack()`, its own frame, and takes the caller's
+/// `\AddOns\<folder>\` from the next; here the library and its caller load from different addons.
 #[test]
 fn acedbs_capture_names_the_calling_addon_not_the_librarys_owner() {
     let s = script();
@@ -132,7 +117,7 @@ fn acedbs_capture_names_the_calling_addon_not_the_librarys_owner() {
     );
 }
 
-/// `AceLibrary.lua:70`'s reader: the first line, whole, is a frame it can pull a file name out of.
+/// `AceLibrary.lua:70` pulls a file name out of the first line, a whole frame.
 #[test]
 fn the_first_debugstack_line_is_a_frame() {
     let s = script();
@@ -151,9 +136,8 @@ fn the_first_debugstack_line_is_a_frame() {
     );
 }
 
-/// `AceLibrary.lua:139`'s `argCheck` names the offending function with `"([`<].-['>])"` — a
-/// BACKTICK opening it. Lua 5.4 writes `in function 'name'`, which that pattern cannot match; the
-/// reference's 5.0 wording is `` in function `name' ``.
+/// The reference's Lua 5.0 writes a named frame as `` in function `name' ``, opening with a
+/// backtick, which `AceLibrary.lua:139`'s `argCheck` pattern `` "([`<].-['>])" `` needs.
 #[test]
 fn a_named_frame_uses_the_5_0_backtick_quoting() {
     let s = script();
@@ -165,18 +149,10 @@ fn a_named_frame_uses_the_5_0_backtick_quoting() {
     assert_eq!(found, "`BenillaProbeNamed'");
 }
 
-/// **Every frame carries its own trailing `\n`, and `count1` bounds nothing on its own**
-/// (decision 2121).
-///
-/// Stock Lua 5.0 pushes `"\n\t"` *before* each frame plus a header once; the reference pushes a
-/// single `"\n"` after each frame and no header (`0x703971`). And the walk formats while the level
-/// is `<= start + count1` — `0x703857` is `jbe`, unsigned ≤ — then probes
-/// `getstack(level + count2)`: a probe that FAILS steps back and prints that level as an ordinary
-/// frame. So with `count1 = 1, count2 = 0` a two-deep stack returns TWO frames and no marker, and a
-/// three-deep one returns one frame plus `"...\n"` and nothing after. A client that clamped to
-/// `count1` would diverge at exactly `depth == count1 + 1` — and that is
-/// `FuBarPlugin-2.0.lua:752`'s `debugstack(6, 1, 0)`, whose capture is a GREEDY
-/// `"\\AddOns\\(.*)\\"` reading the LAST path in the string.
+/// The reference ends each frame with `"\n"` and writes no header (`0x703971`). It formats while
+/// the level is `<= start + count1` (`0x703857`, `jbe`), then probes `getstack(level + count2)`; a
+/// failed probe prints that level as an ordinary frame. So with `count1 = 1, count2 = 0` a
+/// two-deep stack gives two frames and no marker, and a three-deep one a frame then `"...\n"`.
 #[test]
 fn debugstack_frames_end_in_newline_and_count1_does_not_clamp() {
     let s = script();
@@ -185,8 +161,6 @@ fn debugstack_frames_end_in_newline_and_count1_does_not_clamp() {
         trace.ends_with('\n'),
         "the newline is pushed AFTER each frame: {trace:?}"
     );
-    // Two levels at or above `start`, `count1 = 1`: the elision probe fails, so the second frame
-    // prints in full and no marker appears.
     let two: String = s
         .eval(
             "function BenillaProbeDepth2() local r = debugstack(1, 1, 0) return r end \
@@ -196,7 +170,6 @@ fn debugstack_frames_end_in_newline_and_count1_does_not_clamp() {
     let lines: Vec<&str> = two.trim_end().split('\n').collect();
     assert_eq!(lines.len(), 2, "two frames, no marker: {two:?}");
     assert!(!two.contains("..."), "no elision at depth 2: {two:?}");
-    // Deeper: one frame, then the marker on its own line, and nothing after it (count2 = 0).
     let deep: String = s
         .eval(
             "function BenillaProbeC() local r = debugstack(1, 1, 0) return r end \
@@ -210,20 +183,15 @@ fn debugstack_frames_end_in_newline_and_count1_does_not_clamp() {
     assert_eq!(lines[1], "...", "the marker is its own complete line");
 }
 
-/// **An addon's chunk is named the way the CLIENT names it**, because addons parse that name.
-///
-/// `FuBarPlugin-2.0.lua:752` is `string.find(debugstack(6, 1, 0), "\\AddOns\\(.*)\\")`, and it
-/// feeds the capture into `format("Interface\\AddOns\\%s\\icon", folderName)`. Without a name
-/// mlua defaults the chunk to the RUST caller location, that pattern misses, and every FuBar plugin
-/// dies formatting a nil three frames from the cause.
-///
-/// The greedy `(.*)` is why the file has to be in the name too: it captures to the LAST backslash.
+/// An addon chunk is named as the reference names it, `@Interface\AddOns\<folder>\<file>`:
+/// `FuBarPlugin-2.0.lua:752` finds its folder with a greedy `"\\AddOns\\(.*)\\"`, which captures
+/// up to the last backslash, so the file must be in the name.
 #[test]
 fn an_addon_chunk_is_named_the_way_the_client_names_it() {
     let name = crate::script::addon_chunk_name("FuBar_BagFu", "FuBar_BagFu.lua");
     assert_eq!(name, "@Interface\\AddOns\\FuBar_BagFu\\FuBar_BagFu.lua");
 
-    // FuBar's own pattern, run for real against a traceback from a chunk loaded under that name.
+    // FuBar's own pattern, against a traceback from a chunk loaded under that name.
     let s = script();
     s.run_chunk_named(
         b"function BenillaProbeFolder() return debugstack(1, 1, 0) end",
@@ -267,7 +235,7 @@ fn loadstring_is_text_only_bytecode_rejected() {
     assert!(ok, "loadstring must reject bytecode");
 }
 
-// ── GetTime: the session clock (decision 0137 — the reference cast bar anchors on it) ───────────
+// ── GetTime: the session clock ──
 
 #[test]
 fn gettime_starts_at_zero_and_tracks_tick() {
@@ -279,15 +247,7 @@ fn gettime_starts_at_zero_and_tracks_tick() {
     assert!((t - 0.5).abs() < 1e-6, "two 0.25s ticks = 0.5 (got {t})");
 }
 
-/// The rest of the bare globals Blizzard's own restricted scope enumerates (decision 1187).
-///
-/// The list is not from memory: `Blizzard_RestrictedAddOnEnvironment/RestrictedEnvironment.lua`
-/// copies exactly these out of the engine, which is what distinguishes them from the table helpers
-/// (`tContains`, `tInvert`, …) that FrameXML defines in Lua and we must therefore NOT supply.
-///
-/// The measured cost of their absence: Bagnon + BagBrother produced 94 load failures, 81 of them
-/// `Cannot find a library instance of "…"`, because `strmatch` was nil so every LibStub-registering
-/// library aborted before it could register.
+/// The rest of the engine's bare string and math globals, and the later-client names it lacks.
 #[test]
 fn the_rest_of_the_bare_globals() {
     let s = script();
@@ -318,20 +278,8 @@ fn the_rest_of_the_bare_globals() {
     .unwrap();
 }
 
-/// **The Lua 5.0 dialect a vanilla addon is written in runs on our 5.1 VM** — measured, because
-/// this question has been answered three different ways from memory.
-///
-/// 1.12 runs Lua 5.0 (byte-confirmed: `0x811b30 = "Lua: Lua 5.0 Copyright..."`);
-/// we run 5.1 via mlua's `lua51`. Decision 1188 called that "the deepest divergence and it is
-/// unresolved" and told the next session to test it; 1189 replied that 0068 had already closed it.
-/// Meanwhile five of our own transcribed FrameXML files carried the opposite claim in a comment —
-/// *"`LUA_COMPAT_VARARG` isn't shipped"* — each citing the others as precedent, so a false fact
-/// propagated by citation without anyone re-running it.
-///
-/// It is shipped. This asserts the five idioms vanilla addon code actually uses, so the next
-/// session reads a result instead of a recollection. **The implicit `arg` table is the one that
-/// matters**: it is the difference between a vanilla addon's vararg functions working and every
-/// one of them erroring at runtime, which is 1188's stated redirect-the-arc risk.
+/// 1.12 runs Lua 5.0 (`0x811b30`, "Lua: Lua 5.0 Copyright..."); this VM is mlua's `lua51`, and the
+/// 5.0 idioms vanilla addons use run on it, above all the implicit vararg `arg` table.
 #[test]
 fn the_lua_5_0_dialect_vanilla_addons_are_written_in_runs_here() {
     let s = script();
@@ -364,22 +312,13 @@ fn the_lua_5_0_dialect_vanilla_addons_are_written_in_runs_here() {
     .unwrap();
 }
 
-/// **`time()` is real epoch seconds and `date()` formats them** — engine globals in the 1.12
-/// client's own `_G` (slots 34/33 of its base registry) that we lacked entirely, because the
-/// sandbox strips `os`.
-///
-/// `time` was the top name in the session-start `attempt to call global` row. Every corpus site
-/// persists it into SavedVariables and compares across sessions
-/// (`FTC_Save[k].LastCheck = time()`), so a session-relative clock like `GetTime` would be wrong in
-/// a way that only shows up on the SECOND login.
-///
-/// The formats asserted are the ones read off real call sites, against a FIXED epoch so the
-/// conversion is checked rather than the machine's clock: 2001-09-09 01:46:40 UTC, a Sunday.
+/// `time()` is wall-clock epoch seconds and `date()` formats them, both engine globals in the 1.12
+/// `_G` (slots 34 and 33 of its base registry); addons save `time()` and compare across logins.
 #[test]
 fn time_is_epoch_seconds_and_date_formats_them() {
     let s = script();
 
-    // A plausible wall clock: after 2020, before 2100. Pins that this is not GetTime's 0-based one.
+    // A plausible wall clock, between 2020 and 2100, not GetTime's 0-based one.
     let now: i64 = s.eval("return time()").unwrap();
     assert!(
         (1_577_836_800..4_102_444_800).contains(&now),
@@ -409,31 +348,26 @@ fn time_is_epoch_seconds_and_date_formats_them() {
         assert_eq!(got, want, "date({fmt:?})");
     }
 
-    // Bare `date()` is `%c` (Recap.lua:2690 calls it with no arguments) and must not raise.
+    // Bare `date()` is `%c` and must not raise; `Recap.lua:2690` calls it with no arguments.
     let bare: String = s.eval("return date()").unwrap();
     assert!(
         bare.len() > 10,
         "bare date() must format something: {bare:?}"
     );
 
-    // A leap day, because the civil conversion is where a date implementation goes wrong.
+    // A leap day, the civil conversion's edge case.
     let leap: String = s.eval(r#"return date("%Y-%m-%d %A", 951782400)"#).unwrap();
     assert_eq!(leap, "2000-02-29 Tuesday");
 }
 
-// ── RunScript, at the image's own contract (2136's "left open", closed) ──────────────────────────
+// ── RunScript ──
 
-/// `RunScript`'s chunk name is the SOURCE, not a label of ours.
-///
-/// `0x48b9c7 mov edx,eax` / `0x48b9c9 mov ecx,eax` hand `lua_tostring`'s one return to
-/// `FrameScript_Execute 0x704cd0` as both the code and the name, so the name reaches
-/// `luaL_loadbuffer` unprefixed and `luaO_chunkid 0x6f5c40` wraps it — `[string "…"]`. We used to
-/// write `=[RunScript]`, whose leading `=` is chunkid's *print this verbatim* marker.
+/// `RunScript` hands its string to `FrameScript_Execute` (`0x704cd0`) as both code and chunk name
+/// (`0x48b9c7`, `0x48b9c9`), so `luaO_chunkid` (`0x6f5c40`) reports it as `[string "…"]`.
 #[test]
 fn a_runscript_chunk_is_named_by_its_own_source() {
     let mut s = script();
-    // The error is consumed by RunScript (fact 3), so read it off the recorded channel rather
-    // than off a raise.
+    // RunScript consumes the error, so read it off the recorded channel.
     s.run("RunScript(\"error('boom')\")").unwrap();
     let errs = s.take_errors();
     assert!(
@@ -443,15 +377,12 @@ fn a_runscript_chunk_is_named_by_its_own_source() {
     );
 }
 
-/// The three silent legs, and the raise that must NOT happen.
-///
-/// `lua_isstring 0x6f3510` is tag-based, so a number passes and runs as its own text; every other
-/// type takes `0x48b98f je 0x48b9f3` to `xor eax,eax; ret`. An empty string takes the same exit at
-/// `0x48b9a1`. There is no `luaL_error 0x6f4940` in the function at all.
+/// A non-string argument returns silently (`0x48b98f` jumps to `0x48b9f3`), as does an empty
+/// string (`0x48b9a1`); a number passes `lua_isstring` (`0x6f3510`) and runs as text. The function
+/// never calls `luaL_error` (`0x6f4940`).
 #[test]
 fn runscript_swallows_a_bad_argument_instead_of_raising() {
     let mut s = script();
-    // Each of these must return normally AND leave the next statement running.
     s.run(
         "BenillaRan = 0
          RunScript(nil)
@@ -466,7 +397,7 @@ fn runscript_swallows_a_bad_argument_instead_of_raising() {
         s.take_errors().is_empty(),
         "a silent no-op records nothing either"
     );
-    // A number IS a string to `lua_isstring`, so it compiles — and `42` is not a statement.
+    // A number is a string to `lua_isstring`, so it compiles, and `42` is not a statement.
     s.run("RunScript(42)").unwrap();
     assert!(
         s.take_errors()
@@ -476,11 +407,9 @@ fn runscript_swallows_a_bad_argument_instead_of_raising() {
     );
 }
 
-/// A raise inside the snippet does not escape it: `0x704ae0` runs the chunk under
-/// `lua_pcall(L, 0, 0, -2)` (`0x704b68`) with the registry's error handler pushed at `0x704afe`,
-/// and pcalls that same handler for a *compile* failure (`0x704b42`). Both legs return 0 values.
-///
-/// This is the one with teeth: raising here let one bad macro abort whatever ran it.
+/// A raise inside the snippet stays there: `0x704ae0` runs it under `lua_pcall` (`0x704b68`) with
+/// the registry's error handler (`0x704afe`), and calls that handler for a compile failure too
+/// (`0x704b42`).
 #[test]
 fn a_runscript_error_reaches_the_handler_and_not_the_caller() {
     let mut s = script();
@@ -503,7 +432,7 @@ fn a_runscript_error_reaches_the_handler_and_not_the_caller() {
         "both errors are recorded, not dropped: {errs:?}"
     );
     assert!(errs[0].contains("inner"), "{errs:?}");
-    // mlua's `Display` category word ("syntax error: ") is not something the image ever writes.
+    // mlua's `Display` prefix ("syntax error: ") is not something the reference writes.
     assert!(
         errs[1].starts_with("[string \"this is not lua\"]:1:"),
         "a compile failure is reported under the same name, undecorated: {errs:?}"
diff --git a/crates/benilla-ui/src/script/tests/structure_queries.rs b/crates/benilla-ui/src/script/tests/structure_queries.rs
index 742ccc95..46132d88 100644
--- a/crates/benilla-ui/src/script/tests/structure_queries.rs
+++ b/crates/benilla-ui/src/script/tests/structure_queries.rs
@@ -1,30 +1,9 @@
-//! **`GetChildren` / `GetNumChildren` / `GetRegions` / `GetNumRegions`** — the four structure
-//! queries, and the properties an addon walking a frame it did not build depends on.
-//!
-//! The consumer that motivated them is `pfUI.api.StripTextures`, embedded in four separate top-20
-//! addons (pfUI, pfQuest, pfQuest-turtle, ShaguDPS):
-//!
-//! ```lua
-//! for _, v in ipairs({ frame:GetRegions() }) do
-//!   if v.SetTexture then ... end
-//! end
-//! ```
-//!
-//! so the shape under test is the one that idiom needs: **multiple return values**, in the
-//! structure's own order, each a usable widget object.
-//!
-//! Every claim here is confirmed against the reference (`0x773f60`/`0x774180`): the lists are
-//! `[frame+0x300]` and `[frame+0x1b8]`, both linkers APPEND AT THE TAIL so the values come back
-//! oldest-first with no reversal, hidden nodes
-//! are returned and counted, a detached region and the title region are both absent, a Button's
-//! label and state textures are present, and an empty frame returns zero values while `GetNum*`
-//! returns the number `0`.
+//! The structure queries `GetChildren`, `GetNumChildren`, `GetRegions` and `GetNumRegions`
+//! (`0x773f60`/`0x774180`): they walk `[frame+0x300]` and `[frame+0x1b8]`, whose linkers append at
+//! the tail, so values come back oldest first as multiple returns, hidden ones included.
 
 use super::common::script;
 
-/// The whole contract in one document: both lists, their order, the counts agreeing with them, the
-/// empty case, and — the one that is a behaviour rather than a plumbing detail — that a region
-/// detached by `SetParent(nil)` leaves both region verbs.
 #[test]
 fn the_structure_queries_report_the_structure() {
     let mut s = script();
@@ -48,8 +27,7 @@ fn the_structure_queries_report_the_structure() {
     )
     .unwrap();
 
-    // ── The lists, by name and IN ORDER. Named rather than counted, so a walk that returned the
-    //    right number of the wrong things (or the right things reversed) cannot pass.
+    // ── The lists, by name and in order.
     assert_eq!(
         s.eval::<String>(
             "local n = '' for _, v in ipairs({ SQHost:GetChildren() }) do \
@@ -69,9 +47,7 @@ fn the_structure_queries_report_the_structure() {
         "regions come back in CREATION order, not draw order — the OVERLAY fontstring stays second"
     );
 
-    // ── The counts are the same walk. A count that disagrees with the list is an off-by-one deep
-    //    inside a loop the addon did not write, so the two verbs share one function by construction
-    //    and this pins it.
+    // ── The counts are the same walk.
     assert_eq!(
         s.eval::<(usize, usize)>(
             "return SQHost:GetNumChildren(), table.getn({ SQHost:GetChildren() })"
@@ -87,8 +63,7 @@ fn the_structure_queries_report_the_structure() {
         (3, 3)
     );
 
-    // ── The objects are USABLE, not opaque handles: `StripTextures` feature-tests `v.SetTexture`
-    //    to tell a texture from a fontstring, then calls it. Both halves have to hold.
+    // ── Usable objects: pfUI's `StripTextures` tests `v.SetTexture`, then calls it.
     assert_eq!(
         s.eval::<String>(
             "local out = '' for _, v in ipairs({ SQHost:GetRegions() }) do \
@@ -100,8 +75,7 @@ fn the_structure_queries_report_the_structure() {
         "a texture answers SetTexture and a fontstring does not — the StripTextures branch"
     );
 
-    // ── A childless, regionless frame yields NOTHING, and counts zero. `ipairs` over it must run
-    //    zero times rather than once over a nil.
+    // ── An empty frame returns no values and counts zero.
     assert_eq!(
         s.eval::<(usize, usize, usize)>(
             "local e = CreateFrame(\"Frame\", \"SQEmpty\", UIParent) \
@@ -111,10 +85,8 @@ fn the_structure_queries_report_the_structure() {
         (0, 0, 0)
     );
 
-    // ── DETACHED REGIONS LEAVE BOTH VERBS. `Region:SetParent(nil)` unlinks from the parent's draw
-    //    layer AND its region list in the client (`0x77fd10`). We keep the entry so the arena can
-    //    still free the slot — a representation choice that must not be observable here, or a
-    //    StripTextures-shaped walk would "strip" a region that is already off the screen.
+    // ── A detached region leaves both verbs: `Region:SetParent(nil)` unlinks it from the draw
+    //    layer and the region list (`0x77fd10`); our arena keeps the entry, unseen here.
     s.run("SQFontB:SetParent(nil)").unwrap();
     assert_eq!(
         s.eval::<String>(
@@ -131,12 +103,8 @@ fn the_structure_queries_report_the_structure() {
         "...and from the count, which is the same walk"
     );
 
-    // ── THE TITLE REGION IS NOT IN THE LIST, and this is the assertion that corrected us. Its two
-    //    creation paths in the client dispatch a vtable slot that is a bare `[this+0x9c] = parent`
-    //    and never reach the region linker, so it was never in the list `GetRegions` walks —
-    //    corroborated by `Hide`/`Show` carrying an explicit extra `[frame+0xa8]` case *because* the
-    //    walk misses it (`0x768060`). Ours lives in `Frame::regions` so the arena can still free
-    //    it, which makes that a representation detail this walk must not leak.
+    // ── The title region is not in the list: its creation sets `[this+0x9c] = parent` without
+    //    the region linker, and `Hide`/`Show` handle `[frame+0xa8]` separately (`0x768060`).
     s.run("SQHost:CreateTitleRegion()").unwrap();
     assert_eq!(
         s.eval::<usize>("return SQHost:GetNumRegions()").unwrap(),
@@ -153,8 +121,7 @@ fn the_structure_queries_report_the_structure() {
         "...and does not appear in it"
     );
 
-    // ── A child reparented away leaves its old parent's child list too (the frame twin of the
-    //    above, and the case an addon hits when it re-hosts a default-UI frame).
+    // ── A reparented child leaves its old parent's list.
     s.run("SQChildB:SetParent(UIParent)").unwrap();
     assert_eq!(
         s.eval::<String>(
diff --git a/crates/benilla-ui/src/script/tests/talent.rs b/crates/benilla-ui/src/script/tests/talent.rs
index 1f9fcc32..ab4c63fc 100644
--- a/crates/benilla-ui/src/script/tests/talent.rs
+++ b/crates/benilla-ui/src/script/tests/talent.rs
@@ -1,6 +1,5 @@
-//! The talent engine seam (decision 0304): the Era binding tuples over a pushed snapshot, the
-//! learn-click queue, and the `SetTalent` tooltip — the spell builder with the talent
-//! interleave (rank line white, req lines red, next-rank block, learn hint green).
+//! The talent bindings over a pushed snapshot, the learn queue, and `SetTalent`: the spell tooltip
+//! with the talent lines interleaved.
 
 use super::common::script;
 use crate::script::*;
@@ -62,8 +61,6 @@ fn one_tab_state() -> TalentUiState {
     }
 }
 
-/// The Era tuples read back exactly what the app pushed — including the 1-based grid seats,
-/// the flat prereq triplets, and the points pair.
 #[test]
 fn bindings_read_the_pushed_snapshot() {
     let mut s = script();
@@ -95,7 +92,6 @@ fn bindings_read_the_pushed_snapshot() {
     assert!(s.take_errors().is_empty());
 }
 
-/// LearnTalent queues (tab, index) verbatim for the app's wire drain.
 #[test]
 fn learn_talent_queues_for_the_app_drain() {
     let mut s = script();
@@ -106,9 +102,8 @@ fn learn_talent_queues_for_the_app_drain() {
     assert!(s.take_errors().is_empty());
 }
 
-/// A stand-in string table for the talent tail's three keys — **deliberately not the shipped
-/// wording**, because what is under test is which key each line reaches and what fills it, never
-/// what the sentence says (decision 2045).
+/// Stand-in values for the three talent keys, not the shipped wording: the tests check which key
+/// each line reaches.
 fn seed_talent_strings(s: &mut UiScript) {
     s.run(
         r#"
@@ -120,9 +115,8 @@ fn seed_talent_strings(s: &mut UiScript) {
     .unwrap();
 }
 
-/// SetTalent = the spell builder + the talent interleave: name, TOOLTIP_TALENT_RANK white, cost
-/// line, gold description, TOOLTIP_TALENT_NEXT_RANK + the next rank's gold description, green
-/// TOOLTIP_TALENT_LEARN.
+/// `SetTalent`'s lines: name, `TOOLTIP_TALENT_RANK` (white), cost, gold description,
+/// `TOOLTIP_TALENT_NEXT_RANK` and the next rank's gold description, green `TOOLTIP_TALENT_LEARN`.
 #[test]
 fn set_talent_renders_the_interleaved_tooltip() {
     let mut s = script();
@@ -162,7 +156,6 @@ fn set_talent_renders_the_interleaved_tooltip() {
     "#,
     )
     .unwrap();
-    // The learn hint wears the tooltip green; the requirement red is exercised below.
     s.resolve();
     let quads = s.extract();
     let green = quads.iter().any(|q| {
@@ -173,14 +166,13 @@ fn set_talent_renders_the_interleaved_tooltip() {
     assert!(s.take_errors().is_empty());
 }
 
-/// A locked talent shows its red requirement line; a missing spell view falls back to the rank
-/// line alone and records the ask for the app resolver (the shared ask-once channel).
+/// A missing spell view renders the rank line alone and asks for the view once.
 #[test]
 fn set_talent_locked_reqs_and_the_ask_once_miss() {
     let mut s = script();
     seed_talent_strings(&mut s);
     s.set_talents(one_tab_state());
-    // No spell view pushed for Ignite (11119): the render falls back, the ask is recorded.
+    // No spell view pushed for Ignite (11119).
     s.run(
         r#"
         local a = CreateFrame("Button", "TB2"); a:SetPoint("CENTER", 0, 0); a:SetWidth(10); a:SetHeight(10)
@@ -198,7 +190,6 @@ fn set_talent_locked_reqs_and_the_ask_once_miss() {
         "the display spell was asked: {asks:?}"
     );
 
-    // With the view landed, the full render carries the red requirement line.
     s.set_spell_tooltip(
         11119,
         SpellTooltipView {
diff --git a/crates/benilla-ui/src/script/tests/taxi.rs b/crates/benilla-ui/src/script/tests/taxi.rs
index 534b9244..91338c00 100644
--- a/crates/benilla-ui/src/script/tests/taxi.rs
+++ b/crates/benilla-ui/src/script/tests/taxi.rs
@@ -1,12 +1,9 @@
-//! The taxi seam (decision 0484): the app-pushed snapshot surfaces through the Era bindings the
-//! reference `TaxiFrame.lua` reads, and the click/close intents drain back out.
+//! The taxi bindings stock `TaxiFrame.lua` reads over a pushed snapshot, and the node and close
+//! intents.
 
 use super::common::script;
 use crate::script::*;
 
-/// The full round trip: push a two-node snapshot, read it back exactly as the reference Lua does
-/// (count, type, position, name, cost, route segments), click a node + close, drain both intents,
-/// and `SetTaxiMap` paints the pushed art onto the target texture region.
 #[test]
 fn taxi_snapshot_surfaces_and_intents_drain() {
     let mut s = script();
@@ -62,7 +59,6 @@ fn taxi_snapshot_surfaces_and_intents_drain() {
     assert!(s.take_taxi_close());
     assert!(!s.take_taxi_close(), "the close flag drains");
 
-    // SetTaxiMap assigned the pushed art onto the texture region.
     s.resolve();
     assert!(
         s.extract().iter().any(|q| matches!(
@@ -72,7 +68,6 @@ fn taxi_snapshot_surfaces_and_intents_drain() {
         "the continent art draws on the SetTaxiMap target"
     );
 
-    // The ride flag reaches UnitOnTaxi.
     s.set_on_taxi(true);
     s.run(r#"assert(UnitOnTaxi("player") == 1)"#).unwrap();
     assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
diff --git a/crates/benilla-ui/src/script/tests/texcoord_font.rs b/crates/benilla-ui/src/script/tests/texcoord_font.rs
index 53d2c8f6..db4e3308 100644
--- a/crates/benilla-ui/src/script/tests/texcoord_font.rs
+++ b/crates/benilla-ui/src/script/tests/texcoord_font.rs
@@ -1,11 +1,8 @@
-//! TexCoords + Font objects (decision 0084).
+//! `SetTexCoord` and font objects.
 
 use super::common::script;
 use crate::script::*;
 
-/// `SetTexCoord(l, r, t, b)` writes the region's UV sub-rect; it surfaces on the extracted quad,
-/// `GetTexCoord` reads it back; the 8-arg affine form carries per-corner UVs (the route-line
-/// draw's rotated quads).
 #[test]
 fn set_tex_coord_changes_extracted_uv() {
     let mut s = script();
@@ -32,14 +29,12 @@ fn set_tex_coord_changes_extracted_uv() {
         tex.content
     );
 
-    // EIGHT values, per corner, in `SetTexCoord`'s own usage order — `ULx, ULy, LLx, LLy, URx,
-    // URy, LRx, LRy` (decision 1840). A Rect stored as `[l, r, t, b]` comes back out as its four
-    // corners, which is the only shape the reference has: there is no 4-value getter.
+    // `GetTexCoord` returns eight values in `SetTexCoord`'s corner order, `ULx, ULy, LLx, LLy,
+    // URx, URy, LRx, LRy`: the reference has no 4-value getter.
     let got: (f32, f32, f32, f32, f32, f32, f32, f32) = s.eval("return t:GetTexCoord()").unwrap();
     assert_eq!(got, (0.1, 0.2, 0.1, 0.8, 0.6, 0.2, 0.6, 0.8));
 
-    // The 8-arg affine form (arg order UL, LL, UR, LR) lands as per-corner UVs in screen order
-    // [TL, TR, BR, BL] — here a 90° rotation of the full texture.
+    // The 8-argument form (UL, LL, UR, LR) lands in screen order [TL, TR, BR, BL]; a 90° turn here.
     s.run("t:SetTexCoord(0,1, 1,1, 0,0, 1,0)").unwrap();
     s.resolve();
     let tex = s
@@ -73,9 +68,6 @@ fn set_tex_coord_changes_extracted_uv() {
     ));
 }
 
-/// `SetFontObject("Name")` copies a registered [`FontObject`]'s face/height/color onto the
-/// FontString; `GetFontObject` hands back the OBJECT (whose `GetName` round-trips); a later call
-/// re-points it (the resolved paint on the extracted quad follows). An unknown name errors.
 #[test]
 fn set_font_object_repoints_fontstring() {
     let mut s = script();
@@ -144,7 +136,6 @@ fn set_font_object_repoints_fontstring() {
         )
     );
 
-    // Re-point.
     s.run("fs:SetFontObject('Small')").unwrap();
     s.resolve();
     assert_eq!(
@@ -156,13 +147,10 @@ fn set_font_object_repoints_fontstring() {
         )
     );
 
-    // An unknown font object errors (never a silent no-op).
     assert!(s.run("fs:SetFontObject('Nope')").is_err());
 }
 
-/// `justifyV`: MIDDLE is the default (the client's own FontString default — what seats the money
-/// numbers on their coins' centerline), `SetJustifyV` overrides it, and a font object carrying one
-/// applies it on `SetFontObject`.
+/// A FontString's `justifyV` defaults to MIDDLE, the client's default.
 #[test]
 fn justify_v_defaults_middle_and_overrides() {
     let mut s = script();
@@ -192,15 +180,9 @@ fn justify_v_defaults_middle_and_overrides() {
     s.resolve();
     assert_eq!(justify_v(&s), JustifyV::Bottom);
 
-    // A font object carrying justify_v applies it — but ONLY on the axis this string has not
-    // already claimed for itself. `SetJustifyV` above severed the V axis, and that severance is
-    // permanent: the reference clears the axis's inheritMask bit (`+0x124`, the per-axis justify
-    // mask) and never restores it, so a later `SetFontObject` cannot take the axis back.
-    //
-    // This assertion used to read `Top`. That was our copy-everything model, not the client's; the
-    // shipped XML path is unaffected either way, because the loader applies `inherits=` BEFORE the
-    // element's own `justifyV=` (`Loader::apply_fontstring_font`), so the explicit attribute still
-    // wins.
+    // A font object's justification applies only on an axis the string has not set itself: a
+    // local setter clears that axis's inherit bit (`+0x124`) for good. XML is unaffected, as the
+    // loader applies `inherits=` before the element's own `justifyV=`.
     s.register_font_object(
         "TopFont",
         FontObject {
@@ -217,7 +199,7 @@ fn justify_v_defaults_middle_and_overrides() {
     s.resolve();
     assert_eq!(justify_v(&s), JustifyV::Bottom, "severance is permanent");
 
-    // A string that never claimed the axis DOES take the object's justification.
+    // A string that never set the axis takes the object's justification.
     s.run(
         r#"
         fresh = f:CreateFontString(nil, "ARTWORK")
diff --git a/crates/benilla-ui/src/script/tests/tooltip.rs b/crates/benilla-ui/src/script/tests/tooltip.rs
index f919e67b..dcb24950 100644
--- a/crates/benilla-ui/src/script/tests/tooltip.rs
+++ b/crates/benilla-ui/src/script/tests/tooltip.rs
@@ -1,7 +1,5 @@
-//! The GameTooltip widget's engine mechanics (decision 0274): the line stack + named line
-//! regions, auto-size from the measure round-trip, the right-flush, SetOwner's anchor law +
-//! IsOwned, SetText's implicit show, both AddLine shapes, ClearLines/Hide firing
-//! `OnTooltipCleared`, SetMinimumWidth's floor, and FadeOut's ramp-then-hide.
+//! The GameTooltip widget's engine mechanics: the line stack and its auto-size, `SetOwner`'s
+//! anchor modes, the implicit and gated shows, and the fade.
 
 use super::common::script;
 use crate::script::*;
@@ -22,8 +20,6 @@ fn measure_all(s: &mut UiScript, sizes: &[(&str, f32, f32)]) {
     s.resolve();
 }
 
-/// The full stack: three lines (one double), measured, auto-sized, right-flushed, and the named
-/// line globals published.
 #[test]
 fn line_stack_autosize_and_right_flush() {
     let mut s = script();
@@ -84,16 +80,8 @@ fn line_stack_autosize_and_right_flush() {
     assert_eq!(l2.top, 536.0);
 }
 
-/// An EMPTY line mid-stack (the corpus' `AddLine("")`; the live shape was an empty-string
-/// subtitle from the wire): a ONE-UNIT row that also charges its 2px slot gap. Two fallbacks died
-/// to get here. First the owner-edge one: an empty FontString never measures, so its unpinned
-/// bottom edge fell back to the OWNER frame's bottom (0068's v1 region rule), the line stretched
-/// to the plate's bottom and the anchor chain marched every later line OUT of the plate (the live
-/// NPC-tooltip spill — name inside, "Level 20"/"PvP" below the frame under the health bar). Then
-/// the zero-span collapse that replaced it, which the reference does not have either: its size
-/// getters floor at one FrameXML unit, so `0.0` is not a span a FontString can have (decision
-/// 1664). The row and the plate read that floor off ONE constant, which is what keeps them from
-/// drifting apart the way B309's did.
+/// An empty line is a one-unit row plus its 2 px gap, as the reference's size getters floor a
+/// FontString at one FrameXML unit; the row and the plate read that floor from one constant.
 #[test]
 fn empty_line_is_a_one_unit_row_and_the_chain_stays_inside_the_plate() {
     let mut s = script();
@@ -123,10 +111,7 @@ fn empty_line_is_a_one_unit_row_and_the_chain_stays_inside_the_plate() {
         ],
     );
     // Rows 14 + 1 + 12 + 12 with 3 slot gaps ⇒ totalh 45, height 65; maxw 90 ⇒ width 110.
-    // The blank row is ONE unit, not zero: a FontString's span floors at one FrameXML unit on
-    // both the plate's metric and the line's own rect, from one constant (decision 1664).
-    // (That this row exists at all is a separate open question — on the reference `AddLine("")`
-    // returns without incrementing the line count, `0x530270`.)
+    // The reference's `AddLine("")` returns without adding a line (`0x530270`); ours adds this row.
     s.run(
         r#"
         assert(TTE:GetWidth() == 110, "auto width, got " .. tostring(TTE:GetWidth()))
@@ -145,8 +130,6 @@ fn empty_line_is_a_one_unit_row_and_the_chain_stays_inside_the_plate() {
     assert!(s.take_errors().is_empty());
 }
 
-/// SetOwner clears previous content (firing OnTooltipCleared), owns the frame for IsOwned, and
-/// Hide drops the owner + content and fires OnTooltipCleared again.
 #[test]
 fn owner_clear_and_hide_lifecycle() {
     let mut s = script();
@@ -179,11 +162,9 @@ fn owner_clear_and_hide_lifecycle() {
     assert!(s.take_errors().is_empty());
 }
 
-/// SetText shows the tooltip implicitly (the PaperDoll empty-slot flow calls no Show); AddLine
-/// does not (the corpus' `AddLine … Show()`). The colour law: positional `r, g, b` apply only
-/// when the r-slot is a number — the corpus' archaic `(text, "", r, g, b)` shape has a string
-/// there, so the real 1.12 binding drops the whole colour tail and renders the DEFAULT GOLD
-/// (the reference's zone tooltip, director-matched; the trailing numbers never shift into place).
+/// `SetText` shows the tooltip and `AddLine` does not. `r, g, b` apply only when the r slot is a
+/// number, so `AddLine(text, "", r, g, b)` draws in the default gold, as the reference's zone
+/// tooltip does.
 #[test]
 fn settext_shows_and_both_addline_shapes() {
     let mut s = script();
@@ -228,20 +209,17 @@ fn settext_shows_and_both_addline_shapes() {
             })
             .unwrap_or_else(|| panic!("no quad for {needle}"))
     };
-    // The engine default gold 0xffffd200 (both no-colour shapes land on it).
+    // The default gold `0xffffd200`, where both no-colour shapes land.
     let gold = [1.0, 210.0 / 255.0, 0.0, 1.0];
     assert_eq!(color_of("Zone Name"), gold);
     assert_eq!(color_of("plain gold"), gold);
     assert_eq!(color_of("wrapped tail"), [0.2, 0.4, 0.6, 1.0]);
-    // The partial tail: r gates the block on, missing g/b read as 0.0 (byte-pinned).
+    // A numeric r gates the block on, and a missing g or b reads as 0.
     assert_eq!(color_of("red only"), [1.0, 0.0, 0.0, 1.0]);
     assert!(s.take_errors().is_empty());
 }
 
-/// A tooltip whose lines haven't been measured yet holds its declared size — the gaps alone must
-/// never resolve it to a gaps-only rect (the first cut summed LINE_GAP/DOUBLE_GAP for unmeasured
-/// rows and collapsed a fresh 4-line tooltip to 60×26; caught during the 0274 call-site
-/// migration).
+/// Until its lines are measured, a tooltip keeps its declared size rather than a gaps-only one.
 #[test]
 fn unmeasured_lines_hold_declared_size() {
     let mut s = script();
@@ -260,7 +238,7 @@ fn unmeasured_lines_hold_declared_size() {
     "#,
     )
     .unwrap();
-    // Resolve WITHOUT answering the measure round-trip: the declared 120×32 must hold.
+    // Resolve without answering the measure: the declared 120×32 holds.
     s.resolve();
     s.run(
         r#"
@@ -284,7 +262,6 @@ fn unmeasured_lines_hold_declared_size() {
         .unwrap();
 }
 
-/// SetMinimumWidth floors the auto width (the money row's law), and clears with the content.
 #[test]
 fn minimum_width_floors_autosize() {
     let mut s = script();
@@ -307,8 +284,7 @@ fn minimum_width_floors_autosize() {
         .unwrap();
 }
 
-/// FadeOut ramps the frame alpha down and hides at the end of the ramp (owner + lines dropped,
-/// OnTooltipCleared fired); fresh content mid-fade cancels the ramp at full alpha.
+/// Fresh content mid-fade cancels the ramp at full alpha.
 #[test]
 fn fadeout_ramps_then_hides() {
     let mut s = script();
@@ -342,7 +318,6 @@ fn fadeout_ramps_then_hides() {
         mid_alpha > 0.2 && mid_alpha < 0.8,
         "mid-fade alpha ~0.5, got {mid_alpha}"
     );
-    // Re-content cancels the fade at full alpha.
     s.run(
         r#"
         TT5:SetText("Fresh Hover")
@@ -360,7 +335,7 @@ fn fadeout_ramps_then_hides() {
         })
         .expect("fresh line draws");
     assert_eq!(fresh_alpha, 1.0, "fresh content restored full alpha");
-    // Run a full ramp to the end: hidden + cleared.
+    // A full ramp ends hidden and cleared.
     s.run("TT5:FadeOut()").unwrap();
     s.tick(0.6);
     s.run(
@@ -374,12 +349,8 @@ fn fadeout_ramps_then_hides() {
     assert!(s.take_errors().is_empty());
 }
 
-/// SetOwner's anchor law at the screen edge CLAMPS — the client's geometry-flags-bit4 clamp
-/// (`assemble 0x767a20`), carried by every GameTooltip frame **by
-/// construction** (decision 0352: no tooltip ever leaves the window). The reproduction is the
-/// minimap zone-text hover (MinimapCluster.xml: `ANCHOR_LEFT` on a button at the very top of
-/// the screen — plate bottom-right at the owner's top-left seats it wholly ABOVE the window):
-/// the reference plate hangs DOWN from the screen top instead, size preserved, X untouched.
+/// Every GameTooltip clamps to the screen (the geometry-flags bit 4 clamp, `assemble 0x767a20`), so
+/// the zone text's `ANCHOR_LEFT` (`Minimap.lua:39`) hangs down from the screen top, not above it.
 #[test]
 fn owner_anchored_tooltip_clamps_to_screen() {
     let mut s = script();
@@ -407,8 +378,7 @@ fn owner_anchored_tooltip_clamps_to_screen() {
         ],
     );
     // Auto-size: maxw 120 ⇒ width 140; totalh 14+2+12 ⇒ height 48. Unclamped, the plate's
-    // BOTTOMRIGHT sits at the owner's TOPLEFT (610, 600) — top 648, wholly above the window.
-    // The clamp shifts it back down: top at the screen top, size preserved, X untouched.
+    // BOTTOMRIGHT at the owner's TOPLEFT (610, 600) puts its top at 648.
     s.run(
         r#"
         assert(TTC:GetTop() == 600, "top clamped to the screen top, got " .. TTC:GetTop())
@@ -419,7 +389,7 @@ fn owner_anchored_tooltip_clamps_to_screen() {
     )
     .unwrap();
     s.resolve();
-    // The flag routes: unclamped, the plate returns to the raw anchor law above the window.
+    // Unclamped, the plate goes back above the window.
     s.run(
         r#"
         assert(not TTC:IsClampedToScreen(), "flag readable")
@@ -431,14 +401,11 @@ fn owner_anchored_tooltip_clamps_to_screen() {
     assert!(s.take_errors().is_empty());
 }
 
-/// `0x52fa50`'s ladder as pure logic — the arm thresholds, the
-/// ceil/truncate asymmetry, and the `_P1` pick — over SYNTHETIC templates, so this asserts the
-/// mechanism and carries none of the reference's own eight strings. The real ones are read off the
-/// player's install and exercised in `benilla::ui_script::buff_tests`.
+/// `0x52fa50`'s duration ladder over stand-in templates: the arm edges, the ceiling on every arm
+/// but seconds, and the `_P1` plural pick.
 #[test]
 fn the_duration_ladder_ceils_every_arm_but_seconds() {
-    // Deliberately not the shipped wording: what is under test is which key is reached and what
-    // number fills it, never what the string says.
+    // Not the shipped wording: the test is which key is reached and what number fills it.
     let table = |key: &str| -> Option<String> {
         Some(
             match key {
@@ -457,8 +424,7 @@ fn the_duration_ladder_ceils_every_arm_but_seconds() {
     };
     let d = |ms: u32| crate::script::tooltip::duration_text(ms, "T", true, &table);
 
-    // The three arm boundaries, from the compare instructions — each is exact, and the arm below
-    // it counts in its own unit right up to the edge.
+    // The three arm edges are exact, and the arm below counts in its own unit up to the edge.
     assert_eq!(d(86_400_000).as_deref(), Some("<1 day>"), "the day edge");
     assert_eq!(
         d(86_399_999).as_deref(),
@@ -478,8 +444,7 @@ fn the_duration_ladder_ceils_every_arm_but_seconds() {
         "the worked example: 61 s ceils to 2, it does not truncate to 1"
     );
 
-    // The asymmetry that makes this one function rather than four format calls: roundUp reaches
-    // the top three arms only.
+    // roundUp reaches the top three arms only.
     assert_eq!(
         d(59_999).as_deref(),
         Some("<59 secs>"),
@@ -498,18 +463,18 @@ fn the_duration_ladder_ceils_every_arm_but_seconds() {
         "exactly one is singular"
     );
 
-    // roundUp = 0 truncates the top arms too (the parameter is real, not a constant we folded).
+    // roundUp = 0 truncates the top arms too.
     assert_eq!(
         crate::script::tooltip::duration_text(61_000, "T", false, &table).as_deref(),
         Some("<1 min>"),
     );
 
-    // A key the string table does not carry yields NO LINE rather than an invented one.
+    // A key the string table lacks yields no line.
     assert_eq!(
         crate::script::tooltip::duration_text(1_000, "NOPE", true, &table),
         None
     );
-    // …and a family shipping only the singular falls back to it rather than vanishing.
+    // A family with only the singular falls back to it.
     let singular_only = |key: &str| (key == "S_SEC").then(|| "<%d s>".to_string());
     assert_eq!(
         crate::script::tooltip::duration_text(5_000, "S", true, &singular_only).as_deref(),
@@ -517,20 +482,9 @@ fn the_duration_ladder_ceils_every_arm_but_seconds() {
     );
 }
 
-/// **B309 — a POOLED line cell that goes empty must not keep the box it measured last hover.**
-///
-/// `measured` is a cache the solver honours without a key check on purpose: it is the last-known
-/// box, held so a line whose text just changed does not collapse for the frame its re-measure is
-/// in flight. Empty text is the one case where that measure never comes — both measure asks
-/// filter empty strings out — so before the fix an emptied cell held its dead box FOREVER, and
-/// only the DRAWN geometry was wrong: the plate's own sum calls empty text zero
-/// (`tooltip::cell`) and the Lua getters key-check (`region::measured_wh`), so both said 0 while
-/// the solver stood a full row there.
-///
-/// Live, that is the item tooltip's SET block: `ClearLines` keeps the cache (the hover re-enter
-/// loop depends on it), so the two blank gold spacers land on cells that carried real text on an
-/// earlier hover. Each drew an uncounted row and the set bonuses hung below the backdrop —
-/// on Field Marshal's Raiment, two blanks, two rows.
+/// The solver keeps a line's last measured box, unkeyed, while a re-measure is in flight, and an
+/// empty line is never measured, so a pooled cell that goes empty must drop its old box: the item
+/// tooltip's set block puts blank spacers on cells that held text.
 #[test]
 fn an_emptied_pooled_line_drops_its_stale_box_and_the_plate_still_contains_the_chain() {
     let mut s = script();
@@ -556,8 +510,7 @@ fn an_emptied_pooled_line_drops_its_stale_box_and_the_plate_still_contains_the_c
         ("PvP", 24.0, 12.0),
     ];
     measure_all(&mut s, sizes);
-    // Hover two, SAME pooled cells: line 2 is now the blank spacer. Nothing new to measure —
-    // lines 1 and 3 re-validate against their own keys, and an empty string is never asked for.
+    // Hover two, same pooled cells: line 2 is now the blank spacer, which is never measured.
     s.run(
         r#"
         TTR:ClearLines()
@@ -590,21 +543,11 @@ fn an_emptied_pooled_line_drops_its_stale_box_and_the_plate_still_contains_the_c
     assert!(s.take_errors().is_empty());
 }
 
-/// **`SetOwner`'s omitted `anchorType` is mode 0 = ANCHOR_LEFT**, and the clear-vs-keep split runs
-/// between NONE and PRESERVE, not between "points" and "doesn't".
-///
-/// 2142's open thread 1 predicted the opposite on both counts — a mode-7 default, and a NONE arm
-/// that must stop dropping anchors — and the bytes refute both (decision 2176). What is actually
-/// there:
-///
-/// * `0x53120d` zeroes the binding's local mode before any compare, and `0x531214`'s
-///   `lua_isstring` gate jumps the whole `SStrCmpI` chain when arg 3 is absent, nil, a boolean or
-///   a table — so the answer is **0 = ANCHOR_LEFT**, silently, with no `luaL_error` anywhere in
-///   `[0x531221, 0x53133a)`. The core's `mov [+0x318],7` at `0x530012` is an unconditional
-///   pre-store `0x530031` overwrites; it survives only when the owner is NULL.
-/// * `0x52fe90` returns for mode **8** at `0x52fead`, *before* `0x52fec2 call 0x767ed0`, and the
-///   mode-7 skip beside that clear is gated on an arg1 `SetOwner`'s core always passes as 1. So
-///   every mode 0..7 clears, and only PRESERVE keeps the placement.
+/// An omitted `anchorType` is mode 0, ANCHOR_LEFT: `0x53120d` zeroes the local, the `lua_isstring`
+/// gate at `0x531214` skips the compare chain, and nothing in `[0x531221, 0x53133a)` raises. The
+/// core's pre-store of mode 7 (`0x530012`) survives only a NULL owner (`0x530031`). `0x52fe90`
+/// returns for mode 8 (`0x52fead`) before its clear (`0x52fec2 call 0x767ed0`), and `SetOwner`
+/// always passes the arg that gates mode 7's skip as 1, so only ANCHOR_PRESERVE keeps the points.
 #[test]
 fn set_owner_defaults_to_anchor_left_and_only_preserve_keeps_the_placement() {
     let mut s = script();
@@ -623,7 +566,7 @@ fn set_owner_defaults_to_anchor_left_and_only_preserve_keeps_the_placement() {
     s.resolve();
     assert_eq!(s.eval::<f32>("return Plate:GetLeft()").unwrap(), 100.0);
 
-    // ANCHOR_PRESERVE (mode 8) is the ONE mode that leaves the plate alone.
+    // ANCHOR_PRESERVE (mode 8) is the one mode that leaves the plate alone.
     s.run(r#"Plate:SetOwner(Owner, "ANCHOR_PRESERVE")"#)
         .unwrap();
     s.resolve();
@@ -634,7 +577,7 @@ fn set_owner_defaults_to_anchor_left_and_only_preserve_keeps_the_placement() {
     );
     assert_eq!(s.eval::<i64>("return Plate:GetNumPoints()").unwrap(), 1);
 
-    // ANCHOR_NONE (mode 7) clears — which is what makes `GameTooltip_SetDefaultAnchor` safe.
+    // ANCHOR_NONE (mode 7) clears, which `GameTooltip.lua:73`'s default anchor relies on.
     s.run(r#"Plate:SetOwner(Owner, "ANCHOR_NONE")"#).unwrap();
     assert_eq!(
         s.eval::<i64>("return Plate:GetNumPoints()").unwrap(),
@@ -642,8 +585,7 @@ fn set_owner_defaults_to_anchor_left_and_only_preserve_keeps_the_placement() {
         "mode 7 reaches the clear: arg1 is always 1 from SetOwner's core"
     );
 
-    // `SetOwner(f)` — no anchor string at all. Mode 0, and mode 0 PLACES: ANCHOR_LEFT pins the
-    // plate's BOTTOMRIGHT to the owner's TOPLEFT, so its right edge sits at the owner's left.
+    // No anchor string: mode 0 places the plate's BOTTOMRIGHT at the owner's TOPLEFT.
     s.run(r#"Plate:SetPoint("BOTTOMLEFT", nil, "BOTTOMLEFT", 100, 100)"#)
         .unwrap();
     s.run("Plate:SetOwner(Owner)").unwrap();
@@ -659,8 +601,7 @@ fn set_owner_defaults_to_anchor_left_and_only_preserve_keeps_the_placement() {
         "the owner's left edge (300) less the plate's own 50 wide"
     );
 
-    // An UNRECOGNISED string is the same silent mode 0 — the compare chain falls through with the
-    // local untouched, and raises nothing.
+    // An unrecognised string falls through the compare chain: the same silent mode 0.
     s.run(r#"Plate:SetOwner(Owner, "ANCHOR_SIDEWAYS")"#)
         .unwrap();
     assert_eq!(
@@ -669,11 +610,7 @@ fn set_owner_defaults_to_anchor_left_and_only_preserve_keeps_the_placement() {
     );
 }
 
-/// **`SetAlpha(255)` on SetOwner is UNCONDITIONAL** — `0x52fff4`, the first thing the SetOwner
-/// core `0x52ffe0` does, before its five stores (`0x52ffe0`). Ours only ever restored the alpha one
-/// of OUR OWN fades had taken away, so a plate left dim by any other path — an addon's `SetAlpha`,
-/// an inherited parent alpha — stayed dim through every subsequent hover, where the reference
-/// stamps it back to full on each SetOwner.
+/// The `SetOwner` core `0x52ffe0` first sets alpha 255 (`0x52fff4`), whatever dimmed the plate.
 #[test]
 fn set_owner_stamps_full_alpha_even_with_no_fade_running() {
     let s = script();
@@ -694,19 +631,9 @@ fn set_owner_stamps_full_alpha_even_with_no_fade_running() {
     .unwrap();
 }
 
-/// **`Show` is an EXISTENCE GATE, not a plain show** — `0x530a80`, the CGameTooltip override of
-/// `vtbl+0x88` (the slot a Lua `:Show()` lands in). It shows only when BOTH the owner `+0x314`
-/// and the line count `+0x31c` are non-zero, and otherwise calls its own `vtbl+0x84`
-/// effective-hide `0x530a60` — the SetOwner core with a NULL owner, so the plate is hidden AND
-/// un-owned (`0x530a80`).
-///
-/// The symptom that found it: `Questie`'s tracker draws an EMPTY plate on hover — correctly
-/// sized and bordered, with no text. `QuestieTracker.lua`'s quest-button OnEnter has a dead zone
-/// between its two arms (an in-progress quest that has objectives AND whose objective text is in
-/// the Questie database matches neither), so it adds no line and then calls `Tooltip:Show()`
-/// unconditionally. The reference swallows that; we drew it — and, because `layout_tooltips`
-/// skips a zero-line plate instead of collapsing it, we drew it at the LAST hover's size, which
-/// is why it looked like a real tooltip with the text missing rather than a stub.
+/// `Show` (`0x530a80`, the `vtbl+0x88` override) shows only with an owner (`+0x314`) and a line
+/// (`+0x31c`); otherwise it calls `0x530a60` (`vtbl+0x84`), the `SetOwner` core with a NULL owner,
+/// which hides and un-owns. `QuestieTracker.lua`'s OnEnter can call `Show` with no line.
 #[test]
 fn show_with_no_lines_self_hides_and_un_owns() {
     let mut s = script();
@@ -726,8 +653,7 @@ fn show_with_no_lines_self_hides_and_un_owns() {
     )
     .unwrap();
 
-    // Questie's exact shape: the re-hover's SetOwner clears the content, the handler's dead zone
-    // adds nothing, and Show() runs anyway.
+    // Questie's shape: a re-hover's `SetOwner` clears the lines, nothing is added, `Show` runs.
     s.run(
         r#"
         Tip:SetOwner(Owner, "ANCHOR_RIGHT")
@@ -739,7 +665,7 @@ fn show_with_no_lines_self_hides_and_un_owns() {
     )
     .unwrap();
 
-    // The other half of the gate, on its own: a line but no owner is equally not shown.
+    // A line but no owner is the other half of the gate.
     s.run(
         r#"
         Tip:AddLine("Orphan", 1, 1, 1)
@@ -750,20 +676,9 @@ fn show_with_no_lines_self_hides_and_un_owns() {
     .unwrap();
 }
 
-/// **A NON-STRING anchor argument must not raise** — and for a year it did, because the binding
-/// took arg 3 as `Option<String>` and let mlua's converter be the gate.
-///
-/// The reference's gate is `lua_isstring 0x6f3510`, whose entire body is `lua_type` then
-/// `cmp eax,4 / cmp eax,3`: LUA_TSTRING or LUA_TNUMBER pass and are read by coercion, and every
-/// other tag takes `0x53121b je 0x53133a` over the whole compare chain to the join, leaving the
-/// zeroed local — mode 0, `ANCHOR_LEFT`, silently, with no `luaL_error` anywhere in
-/// `[0x531221, 0x53133a)`. So a boolean, a table, a function and absent are *indistinguishable*
-/// at this position.
-///
-/// The symptom that found it: `Questie` hovers a world-map note with
-/// `Tooltip:SetOwner(this, this)` (`QuestieNotes.lua` `Questie_Tooltip_OnEnter`) — a frame where
-/// the anchor goes — and got `bad argument #3: error converting Lua table to String` where the
-/// reference draws the tooltip.
+/// `lua_isstring 0x6f3510` passes only a string or a number; any other tag jumps the compare chain
+/// (`0x53121b je 0x53133a`) to mode 0 and raises nothing. `QuestieNotes.lua` passes a frame here
+/// (`SetOwner(this, this)`).
 #[test]
 fn a_non_string_anchor_is_silently_mode_zero_and_never_raises() {
     let s = script();
@@ -775,7 +690,7 @@ fn a_non_string_anchor_is_silently_mode_zero_and_never_raises() {
     )
     .unwrap();
 
-    // A TABLE — Questie's own call shape, a frame passed where the anchor string goes.
+    // A table, as Questie passes.
     s.run("Plate:SetOwner(Owner, Owner)")
         .expect("a table anchor takes the isstring gate's jump, it does not raise");
     assert_eq!(
@@ -783,7 +698,7 @@ fn a_non_string_anchor_is_silently_mode_zero_and_never_raises() {
         "ANCHOR_LEFT"
     );
 
-    // A BOOLEAN and an explicit nil are the same jump.
+    // A boolean and an explicit nil take the same jump.
     for arg in ["true", "false", "nil"] {
         s.run(&format!(
             r#"Plate:SetOwner(Owner, "ANCHOR_RIGHT") Plate:SetOwner(Owner, {arg})"#
@@ -796,8 +711,7 @@ fn a_non_string_anchor_is_silently_mode_zero_and_never_raises() {
         );
     }
 
-    // A NUMBER is the one non-string tag the gate DOES admit: it is stringified and run through
-    // the chain, which no number can match — the same mode 0, by the other route.
+    // A number passes the gate as a string that matches no mode: mode 0 again.
     s.run(r#"Plate:SetOwner(Owner, "ANCHOR_RIGHT") Plate:SetOwner(Owner, 5)"#)
         .unwrap();
     assert_eq!(
@@ -806,11 +720,8 @@ fn a_non_string_anchor_is_silently_mode_zero_and_never_raises() {
     );
 }
 
-/// **`ANCHOR_CURSOR` is a real ninth mode**, not a string to warn about (2142's open thread 2, and
-/// nine corpus files ask for it): mode 6 clears at `SetOwner` time like mode 7, and then the
-/// per-frame update `0x530b20` pins the plate's **BOTTOM** to the screen's **BOTTOMLEFT** at the
-/// cursor's absolute position, divided by the plate's own effective scale. See
-/// `script::tooltip::cursor_anchor`.
+/// `ANCHOR_CURSOR`, mode 6, clears at `SetOwner` like mode 7; the per-frame update `0x530b20` then
+/// pins the plate's BOTTOM to the screen's BOTTOMLEFT at the cursor, over its effective scale.
 #[test]
 fn anchor_cursor_follows_the_cursor_every_frame() {
     let mut s = script();
@@ -851,7 +762,7 @@ fn anchor_cursor_follows_the_cursor_every_frame() {
         "centred horizontally on the cursor: {left}..{right}"
     );
 
-    // It follows. The whole point of mode 6 is that no second SetOwner is needed.
+    // It follows the cursor with no second `SetOwner`.
     s.mouse_move(120.0, 480.0);
     s.resolve();
     let (left, right, bottom): (f32, f32, f32) = s
@@ -864,14 +775,8 @@ fn anchor_cursor_follows_the_cursor_every_frame() {
     );
 }
 
-/// `GameTooltip:GetAnchorType()` — ONE string, the reference's own spelling, round-tripping
-/// whatever `SetOwner` was given (`0x5313e0`, table `0x854198`, argc 1, arity 1, kinds `(string)`,
-/// reading `[+0x318]` back through the name table `0x531530`).
-///
-/// The round trip is the whole point rather than a nicety: `_Nameplates/_Nameplates.lua:479` is
-/// `if GameTooltip:GetAnchorType() ~= Anchor then GameTooltip:SetOwner(Column, Anchor) end`, so an
-/// answer that never equals what the setter was handed would re-own the plate every OnUpdate; and
-/// `pfUI/modules/tooltip.lua:97` compares against the literal `"ANCHOR_NONE"`.
+/// `GetAnchorType` (`0x5313e0`, table `0x854198`) answers one string, `[+0x318]` through the name
+/// table `0x531530`; `_Nameplates.lua:479` compares it with what it passed to `SetOwner`.
 #[test]
 fn tooltip_anchor_type_round_trips_every_reachable_mode() {
     let s = script();
@@ -883,8 +788,7 @@ fn tooltip_anchor_type_round_trips_every_reachable_mode() {
     )
     .unwrap();
 
-    // Arity 1, kind string, and NO nil leg — the shapes row is `(string)` with no alternative, so
-    // a plate nobody has owned still answers a string.
+    // Never nil: a plate nobody has owned answers a string too.
     assert_eq!(s.arity("AnchorTip:GetAnchorType()").unwrap(), 1, "arity 1");
     assert_eq!(
         s.eval::<String>("return type(AnchorTip:GetAnchorType())")
@@ -899,8 +803,7 @@ fn tooltip_anchor_type_round_trips_every_reachable_mode() {
         "a plate nothing has owned is anchored to nothing"
     );
 
-    // All NINE modes SetOwner accepts, each answered back verbatim — ANCHOR_PRESERVE included,
-    // which the reference stores like any other rather than resolving back to what it preserved.
+    // All nine modes round-trip, ANCHOR_PRESERVE included: the reference stores it like any other.
     for mode in [
         "ANCHOR_RIGHT",
         "ANCHOR_LEFT",
@@ -922,7 +825,7 @@ fn tooltip_anchor_type_round_trips_every_reachable_mode() {
         );
     }
 
-    // Lower case in, the reference's canonical spelling out — SetOwner already folds the token.
+    // Lower case in, the canonical spelling out.
     s.run(r#"AnchorTip:SetOwner(AnchorOwner, "anchor_left")"#)
         .unwrap();
     assert_eq!(
@@ -931,9 +834,8 @@ fn tooltip_anchor_type_round_trips_every_reachable_mode() {
         "ANCHOR_LEFT"
     );
 
-    // An anchor SetOwner does not recognise is the binding's zero-initialised local, mode 0 —
-    // silently, with no raise (`0x53120d`, and no `luaL_error` in the compare chain). Ours adds a
-    // warning the reference does not have, which is a diagnostic and not API surface.
+    // An unrecognised anchor is mode 0, with no raise (`0x53120d`). Deviation: we also log a
+    // warning so the unknown token shows up in diagnostics; no addon can see it.
     s.run(r#"AnchorTip:SetOwner(AnchorOwner, "ANCHOR_SIDEWAYS")"#)
         .unwrap();
     assert_eq!(
diff --git a/crates/benilla-ui/src/script/tests/tooltip_item/bindings.rs b/crates/benilla-ui/src/script/tests/tooltip_item/bindings.rs
index 43c0d51f..eb305d82 100644
--- a/crates/benilla-ui/src/script/tests/tooltip_item/bindings.rs
+++ b/crates/benilla-ui/src/script/tests/tooltip_item/bindings.rs
@@ -1,22 +1,16 @@
-//! The Set* entry points: the vendor compare's CURRENTLY_EQUIPPED shape,
-//! SetInventoryItem outside compare, and SetHyperlink's item-link filter.
+//! The `Set*` entry points: the vendor compare, `SetInventoryItem` outside it, `SetHyperlink`'s
+//! item filter, and the tradeskill and merchant-compare row indexing.
 
 use std::collections::HashMap;
 
 use super::script;
 use crate::script::*;
 
-/// The compare SHAPE, driven the only way 1.12.1 drives it: the vendor row's
-/// `SetMerchantCompareItem` (`MerchantFrame.xml:63-80`). The armed render is the equipped item's
-/// ORDINARY tooltip plus ONE line, first — the gray CURRENTLY_EQUIPPED header (p5). Both compare
-/// call sites pass p4 (compact) ZERO, so the two things that are easy to get wrong here are
-/// pinned as negatives: the name keeps its QUALITY color (this worn ring is epic, so the assert
-/// bites), and nothing is cut at `0x52e14c` — the description still prints (2216).
-///
-/// **And the negative control that keeps this engine out of it** (2210): a bag hover seats
-/// nothing, with shift or without, because the reference has no hover compare at all —
-/// `SHOW_COMPARE_TOOLTIP` has zero fire sites in 5875, so nothing may reach a listener for it
-/// either. The plates belong to whatever FrameXML raises them, and this engine raises none.
+/// The compare as 1.12.1 drives it, from the vendor row's `SetMerchantCompareItem`
+/// (`MerchantFrame.xml:63-80`): the worn item's ordinary tooltip under a gray
+/// `CURRENTLY_EQUIPPED` header (p5). Both callers pass p4 zero, so the name keeps its quality
+/// colour and nothing is cut at `0x52e14c`. A bag hover seats no plate, shift or not:
+/// `SHOW_COMPARE_TOOLTIP` has no fire site in the reference.
 #[test]
 fn merchant_compare_renders_the_compare_shape_and_no_hover_seats_a_plate() {
     let mut s = script();
@@ -26,8 +20,7 @@ fn merchant_compare_renders_the_compare_shape_and_no_hover_seats_a_plate() {
         durability: None,
         item_id: 7000,
         name: Some("Old Loop".into()),
-        // EPIC — a white name and a quality name are the same pixel at quality 1, which is how
-        // the conflated flag survived a green test for as long as it did.
+        // Epic: at quality 1 a white name and a quality name are the same pixel.
         quality: 4,
         ..Default::default()
     });
@@ -98,8 +91,7 @@ fn merchant_compare_renders_the_compare_shape_and_no_hover_seats_a_plate() {
             slots,
         }),
     );
-    // The plates are ordinary GameTooltip frames the FrameXML owns — the engine knows nothing
-    // about them (`ShoppingTooltip` does not occur in the image at all).
+    // The plates are ordinary GameTooltips the FrameXML owns; the reference never names them.
     s.run(
         r#"
         local a = CreateFrame("Button", "Slot"); a:SetPoint("LEFT", 0, 0); a:SetWidth(10); a:SetHeight(10)
@@ -175,7 +167,6 @@ fn merchant_compare_renders_the_compare_shape_and_no_hover_seats_a_plate() {
     "#,
     )
     .unwrap();
-    // The compare colors: gray header, and the name in its own QUALITY color — the byte law.
     s.resolve();
     let quads = s.extract();
     let color_of = |txt: &str| {
@@ -206,16 +197,11 @@ fn merchant_compare_renders_the_compare_shape_and_no_hover_seats_a_plate() {
     assert!(s.take_errors().is_empty());
 }
 
-/// **`nameOnly`** — `SetInventoryItem`'s optional third argument, p4 of the builder, and the ONLY
-/// door onto the compact render in 1.12.1 (27 of `0x52b650`'s 31 call sites pass a provable zero,
-/// one forwards, and the three that carry a flag are all this binding's). No stock FrameXML caller
-/// passes it — all 8 stock call sites are two-argument — so this is addon surface, and it is live
-/// code, not a dead arm.
-///
-/// The mode is **trimmed, not bare**, and that is the half a plausible implementation gets wrong:
-/// two non-contiguous cuts plus an early return. Gone: the bind/lock region, the whole stat body,
-/// and everything past the cooldown line. Kept: the name (white), the slot/type cell, durability,
-/// every requirement line and the spell triggers.
+/// `SetInventoryItem`'s third argument, `nameOnly`, is the builder's p4 and the one way to the
+/// compact render: of `0x52b650`'s 31 call sites, 27 pass zero, one forwards and three are this
+/// binding's, and no stock caller passes it. The render is trimmed, not bare: the bind and lock
+/// lines, the stat body and everything past the cooldown line go; the white name, the slot and
+/// type cell, durability, the requirements and the spell triggers stay.
 #[test]
 fn set_inventory_item_name_only_is_the_trimmed_build() {
     let mut s = script();
@@ -237,9 +223,7 @@ fn set_inventory_item_name_only_is_the_trimmed_build() {
             class: 2,
             subclass: 7,
             inventory_type: 13,
-            // One line from each of the three regions p4 treats differently: CONJURED / the bind
-            // line / UNIQUE / LOCKED are CUT, ARMOR is CUT, and the type cell, durability, the
-            // level requirement and the trigger all SURVIVE.
+            // A line from each region p4 treats differently.
             flags: 0x2,
             bonding: 1,
             max_count: 1,
@@ -312,8 +296,7 @@ fn set_inventory_item_name_only_is_the_trimmed_build() {
     assert!(s.take_errors().is_empty());
 }
 
-/// `SetInventoryItem` outside a compare: the FULL line law (quality name, description — no cut),
-/// return 1 on an occupied slot, nil on empty/foreign units.
+/// Outside a compare: the full render, 1 for an occupied slot, nil for an empty or foreign one.
 #[test]
 fn set_inventory_item_renders_full_outside_compare() {
     let mut s = script();
@@ -377,8 +360,6 @@ fn set_inventory_item_renders_full_outside_compare() {
     assert!(s.take_errors().is_empty());
 }
 
-/// `SetHyperlink`: the full escaped chat link and the bare `item:` form both render through the
-/// shared law; non-item links no-op without touching the current content.
 #[test]
 fn set_hyperlink_renders_items_and_ignores_other_links() {
     let mut s = script();
@@ -410,8 +391,7 @@ fn set_hyperlink_renders_items_and_ignores_other_links() {
     assert!(s.take_errors().is_empty());
 }
 
-/// One tradeskill recipe fixture — the product id is `spell_id + 10_000`, so the tooltip's own
-/// name names which recipe the channel actually landed on.
+/// A recipe whose product id is `spell_id + 10_000`, so the tooltip's name shows which row it hit.
 fn ts_recipe(spell_id: u32, name: &str, group: (u32, u32, &str)) -> TradeSkillRecipe {
     TradeSkillRecipe {
         group: Some((group.0, group.1, group.2.to_string())),
@@ -437,13 +417,8 @@ fn ts_recipe(spell_id: u32, name: &str, group: (u32, u32, &str)) -> TradeSkillRe
     }
 }
 
-/// `SetTradeSkillItem`'s index is a **VISIBLE** row index, not a position in `recipes` — headers
-/// interleave with rows, so the two differ the moment any group precedes the recipe. This is the
-/// exact mis-index the tradeskill module doc once carried as a known gap: with one header above it,
-/// visible row 4 is the SECOND group's recipe, and a raw `recipes[4-1]` lookup would land on the
-/// first group's second recipe instead. Both the product channel and the reagent channel are
-/// pinned, since the detail-icon and reagent-slot hovers are the two callers that pass a genuine
-/// visible index straight through. A HEADER row is a no-op, not a shifted hit.
+/// `SetTradeSkillItem` takes a visible row index, headers included, not a position in `recipes`;
+/// the product and reagent hovers both pass one, and a header row is a no-op.
 #[test]
 fn set_trade_skill_item_indexes_visible_rows_not_raw_recipes() {
     let mut s = script();
@@ -468,11 +443,7 @@ fn set_trade_skill_item_indexes_visible_rows_not_raw_recipes() {
     }));
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 6);
 
-    // Visible row 5 is "Alpha Cloak" (spell 4) — its product is 10_004. A raw recipes[5-1] lookup
-    // would land on recipe index 4 (out of range, a silent no-op); recipes[4-1] on "Beta Cloak".
-    // `TTTextLeft1` need not exist when a call renders nothing (what an out-of-range RAW index
-    // does), so read it defensively — that case must surface as an assert_eq naming the row, not
-    // as a Lua nil-index panic three lines away from the claim.
+    // `TTTextLeft1` may not exist when nothing renders, so it is read defensively.
     let name_at = |s: &mut UiScript, row: i64, reagent: &str| -> String {
         s.run(&format!("TT:SetTradeSkillItem({row}{reagent})"))
             .unwrap();
@@ -483,26 +454,20 @@ fn set_trade_skill_item_indexes_visible_rows_not_raw_recipes() {
     assert_eq!(name_at(&mut s, 6, ""), "Beta Cloak");
     assert_eq!(name_at(&mut s, 2, ""), "Alpha Bolt");
 
-    // The reagent channel takes the same mapping.
     assert_eq!(name_at(&mut s, 5, ", 1"), "Alpha Cloak Reagent");
 
-    // A header row resolves to nothing — the hover is a no-op, so the previous render stands
-    // rather than a neighbouring recipe's tooltip appearing under the cursor.
+    // A header row is a no-op: the previous render stands.
     assert_eq!(name_at(&mut s, 4, ""), "Alpha Cloak Reagent");
 }
 
-/// `SetMerchantCompareItem(index [, offset])` — the shopping tooltip the stock vendor row raises.
-///
-/// The contract that decides ghost tooltips versus none is the RETURN, so that is what this pins:
-/// the **number** 1 on success, `nil` on every failure, one value always. Stock's
-/// `if ( ShoppingTooltip1:SetMerchantCompareItem(id, 1) ) then … end` reads it directly, so a
-/// boolean `false` where nil belongs shows an empty tooltip and a truthy nil-case shows two.
+/// `SetMerchantCompareItem(index [, offset])` returns the number 1 or nil, one value, and the stock
+/// vendor row shows each plate on it (`MerchantFrame.xml:67`).
 #[test]
 fn set_merchant_compare_item_answers_one_or_nil_per_candidate_slot() {
     let mut s = script();
     s.set_screen_size(800.0, 600.0);
 
-    // Both finger slots worn, both class 4 (ARMOR) like the ring on the shelf.
+    // Both finger slots worn, class 4 (armor) like the ring on the shelf.
     let mut inv: InventorySlots = Default::default();
     for (slot, id, name) in [(11usize, 7000u32, "Old Loop"), (12, 7001, "Older Loop")] {
         inv[slot] = Some(InvSlotView {
@@ -522,7 +487,7 @@ fn set_merchant_compare_item_answers_one_or_nil_per_candidate_slot() {
             },
         );
     }
-    // …and a shield, class 4, in the off hand — the case that makes offset 2 nil for a WEAPON.
+    // A shield, class 4, in the off hand makes offset 2 nil for a weapon.
     inv[17] = Some(InvSlotView {
         item_id: 7100,
         name: Some("Battered Buckler".into()),
@@ -571,7 +536,7 @@ fn set_merchant_compare_item_answers_one_or_nil_per_candidate_slot() {
             },
             MerchantItem {
                 name: Some("Unseen Thing".into()),
-                item_id: 8999, // no template — the uncached leg
+                item_id: 8999, // no template: the uncached leg
                 ..Default::default()
             },
         ],
@@ -583,7 +548,7 @@ fn set_merchant_compare_item_answers_one_or_nil_per_candidate_slot() {
             name: "Shiny Loop".into(),
             quality: 3,
             class: 4,
-            inventory_type: 11, // finger — two candidate slots
+            inventory_type: 11, // finger: two candidate slots
             ..Default::default()
         },
     );
@@ -593,13 +558,11 @@ fn set_merchant_compare_item_answers_one_or_nil_per_candidate_slot() {
             name: "Sharp Sword".into(),
             quality: 3,
             class: 2,
-            inventory_type: 13, // one-hand — main hand then off hand
+            inventory_type: 13, // one-hand: main hand, then off hand
             ..Default::default()
         },
     );
 
-    // The two shopping tooltips are ordinary GameTooltip frames — the engine knows nothing about
-    // them (the substring `ShoppingTooltip` does not occur in the image at all).
     s.run(
         r#"
         CreateFrame("GameTooltip", "ShoppingTooltip1"):Hide()
@@ -611,7 +574,6 @@ fn set_merchant_compare_item_answers_one_or_nil_per_candidate_slot() {
     let call =
         |s: &mut UiScript, expr: &str| s.eval::<String>(&format!("return type({expr})")).unwrap();
 
-    // A ring against two worn rings: both offsets answer, and the answer is the NUMBER 1.
     assert_eq!(
         s.eval::<String>(r#"return tostring(ShoppingTooltip1:SetMerchantCompareItem(1, 1))"#)
             .unwrap(),
@@ -622,7 +584,6 @@ fn set_merchant_compare_item_answers_one_or_nil_per_candidate_slot() {
         call(&mut s, "ShoppingTooltip2:SetMerchantCompareItem(1, 2)"),
         "number"
     );
-    // …and it filled with the WORN item, headed by the gray compare line.
     assert!(
         s.eval::<bool>(
             r#"local n = ShoppingTooltip1:NumLines()
@@ -637,9 +598,7 @@ fn set_merchant_compare_item_answers_one_or_nil_per_candidate_slot() {
         "the fill is the equipped item's own tooltip with the CURRENTLY_EQUIPPED header"
     );
 
-    // A one-hand weapon: main hand matches (class 2), the off-hand SHIELD does not (class 4), so
-    // offset 2 is nil. This is the reference's class test doing the work, and it is the case a
-    // slot-only reading would get wrong.
+    // A one-hand weapon: the main hand (class 2) matches, the off-hand shield (class 4) does not.
     assert_eq!(
         call(&mut s, "ShoppingTooltip1:SetMerchantCompareItem(2, 1)"),
         "number"
@@ -650,12 +609,12 @@ fn set_merchant_compare_item_answers_one_or_nil_per_candidate_slot() {
         "a shield is not a candidate for a weapon — class, not slot"
     );
 
-    // Offset defaults to 1 when absent, and does NOT raise.
+    // An absent offset is 1, not a raise.
     assert_eq!(
         call(&mut s, "ShoppingTooltip1:SetMerchantCompareItem(1)"),
         "number"
     );
-    // An explicit 0 or a negative is nil — the counter starts below zero and only decrements.
+    // An offset of 0 or less is nil: the counter starts below zero and only decrements.
     for bad in ["0", "-1"] {
         assert_eq!(
             call(
@@ -666,7 +625,6 @@ fn set_merchant_compare_item_answers_one_or_nil_per_candidate_slot() {
             "offset {bad}"
         );
     }
-    // Out of range, and the uncached template, are both nil — never an error.
     for expr in [
         "ShoppingTooltip1:SetMerchantCompareItem(0, 1)",
         "ShoppingTooltip1:SetMerchantCompareItem(99, 1)",
@@ -674,20 +632,18 @@ fn set_merchant_compare_item_answers_one_or_nil_per_candidate_slot() {
     ] {
         assert_eq!(call(&mut s, expr), "nil", "{expr}");
     }
-    // 2.7 re-bases in f64 and THEN truncates: 2.7 - 1 = 1.7 -> row 1, the sword. Doing it the
-    // other way round would land on row 2.
+    // 2.7 re-bases in f64, then truncates: 1.7 is row 1, the sword.
     assert_eq!(
         call(&mut s, "ShoppingTooltip1:SetMerchantCompareItem(2.7, 1)"),
         "number"
     );
 
-    // A non-number index RAISES, with the client's own usage text.
     let e = s
         .run(r#"ShoppingTooltip1:SetMerchantCompareItem({}, 1)"#)
         .unwrap_err()
         .to_string();
     assert!(e.contains("Usage: SetMerchantCompareItem"), "{e}");
-    // …but a numeric STRING is a number to `lua_isnumber`.
+    // A numeric string passes `lua_isnumber`.
     assert_eq!(
         call(&mut s, r#"ShoppingTooltip1:SetMerchantCompareItem("1", 1)"#),
         "number"
diff --git a/crates/benilla-ui/src/script/tests/tooltip_item/law.rs b/crates/benilla-ui/src/script/tests/tooltip_item/law.rs
index efffabc9..cc0ca698 100644
--- a/crates/benilla-ui/src/script/tests/tooltip_item/law.rs
+++ b/crates/benilla-ui/src/script/tests/tooltip_item/law.rs
@@ -1,14 +1,11 @@
-//! The emission-order law and the red requirement checks: the verified line families, the
-//! player-state-tracked reds (level/class/rep), and the slot|type cells' independent
-//! proficiency reds (hard miss on TYPE; alternate/dual-wield on SLOT).
+//! Line order and the red requirement checks: level, class and reputation against player state,
+//! and the slot and type cells' separate proficiency reds.
 
 use std::collections::HashMap;
 
 use super::{axe, lines_of, right_color, script};
 use crate::script::*;
 
-/// The full line law over a rich weapon + the red checks: a level-25 warrior fails the level
-/// requirement (red) but passes the class list (white).
 #[test]
 fn item_line_law_and_red_requirements() {
     let mut s = script();
@@ -16,7 +13,7 @@ fn item_line_law_and_red_requirements() {
     s.set_item_template(871, axe());
     s.set_player_req_state(PlayerReqState {
         level: 25,
-        class_id: 1, // Warrior — allowed
+        class_id: 1, // Warrior: allowed
         race_id: 1,
         skills: HashMap::new(),
         ..Default::default()
@@ -39,14 +36,12 @@ fn item_line_law_and_red_requirements() {
             "Ravager",
             "[ITEM_BIND_ON_EQUIP]",
             "[INVTYPE_2HWEAPON]",
-            // School 0 is physical: the reference names no school word for it either.
-            // The first emitted slot takes the plain key, a later one the `PLUS_` twin, and a
-            // school'd slot the `_WITH_SCHOOL` arm — the word sits INSIDE the template.
+            // School 0 has no school word. The first damage line takes the plain key, later ones
+            // `PLUS_`, and a slot with a school the `_WITH_SCHOOL` arm, the word inside it.
             "[DMG 68 - 103]",
             "[+DMGS 2 - 4 [SCHOOL5]]",
             "[DPS 25.3]",
-            // Display order, NOT wire order: the fixture feeds (Stamina, Strength) but the
-            // 0x808e88 table prints Strength first (STR,AGI,STA,INT,SPI,HP,MANA).
+            // Display order, not field order: `0x808e88` prints STR, AGI, STA, INT, SPI, HP, MANA.
             "[MOD_STRENGTH +9]",
             "[MOD_STAMINA +12]",
             "[RESIST_SINGLE +10 [SCHOOL5]]",
@@ -58,7 +53,6 @@ fn item_line_law_and_red_requirements() {
         ],
         "the verified line order (0276)"
     );
-    // The name wears the Rare blue; the failed level line is red; the passed class line white.
     assert_eq!(lines[0].1, [0.0, 0.439, 0.867, 1.0], "rare-blue name");
     let class_line = &lines[10];
     assert_eq!(
@@ -72,17 +66,13 @@ fn item_line_law_and_red_requirements() {
         [1.0, 32.0 / 255.0, 32.0 / 255.0, 1.0],
         "level 25 < 37 → red"
     );
-    // The right column of the slot|type pair carries the subclass.
     let ty: String = s.eval("return TTTextRight3:GetText()").unwrap();
     assert_eq!(ty, "Axe");
-    // The speed column of the damage pair.
     let speed: String = s.eval("return TTTextRight4:GetText()").unwrap();
     assert_eq!(speed, "Speed 3.50");
     assert!(s.take_errors().is_empty());
 }
 
-/// The red law flips with player state: leveling past the requirement turns the line white; a
-/// class outside the list turns the class line red.
 #[test]
 fn red_lines_track_player_state() {
     let mut s = script();
@@ -90,7 +80,7 @@ fn red_lines_track_player_state() {
     s.set_item_template(871, axe());
     s.set_player_req_state(PlayerReqState {
         level: 60,
-        class_id: 8, // Mage — not in {Warrior, Rogue}
+        class_id: 8, // Mage: not in {Warrior, Rogue}
         race_id: 1,
         skills: HashMap::new(),
         ..Default::default()
@@ -121,12 +111,10 @@ fn red_lines_track_player_state() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The families folded back 2026-07-10 (`0x52b650`): SIGNABLE green,
-/// UNIQUE before STARTS_QUEST, LOCKED red, six-equal resistances collapse to the ALL line (and
-/// Holy never prints singly), a known taught spell reds "Already known", the description gold —
-/// and NO openable line: `BenillaSetItemById` is a template source, and the whole openable/readable/
-/// creator tail rides the ref's item-OBJECT gate (`0x52e1c7`/`0x52e2e0` — byte-read 2026-07-20;
-/// the instance-tail law itself is in [`instance_tail_creator_and_readable`]).
+/// The gated families (`0x52b650`): SIGNABLE green, UNIQUE before STARTS_QUEST, LOCKED red, six
+/// equal resistances as one ALL line (Holy never prints alone), a known taught spell's red
+/// "Already known", the gold description, and no openable line: the openable, readable and creator
+/// tail needs an item object (`0x52e1c7`, `0x52e2e0`), and a template has none.
 #[test]
 fn verified_families_signable_locked_resists_known() {
     let mut s = script();
@@ -146,7 +134,6 @@ fn verified_families_signable_locked_resists_known() {
             ..Default::default()
         },
     );
-    // The player already knows the taught spell 2020.
     s.set_spellbook(SpellBookState {
         tabs: Vec::new(),
         slots: vec![SpellSlotView {
@@ -197,7 +184,6 @@ fn verified_families_signable_locked_resists_known() {
         [1.0, 210.0 / 255.0, 0.0, 1.0],
         "the description is the byte-verified gold"
     );
-    // Holy exclusion: a lone Holy resist prints nothing.
     s.set_item_template(
         5519,
         ItemTemplateView {
@@ -215,10 +201,8 @@ fn verified_families_signable_locked_resists_known() {
     "#,
     )
     .unwrap();
-    // …and the five that DO print come out in the builder's own order, which is not the field
-    // order: `0x52c8ad` runs `edi` 1..5 reading school `(edi == 1) ? 6 : edi`, so **Arcane leads**
-    // and Holy is displaced rather than skipped (decision 2080 named this; we printed plain field
-    // order, Fire first and Arcane last).
+    // The five that print follow the builder, not the fields: `0x52c8ad` runs `edi` 1..5 reading
+    // school `(edi == 1) ? 6 : edi`, so Arcane leads.
     s.set_item_template(
         5520,
         ItemTemplateView {
@@ -246,13 +230,10 @@ fn verified_families_signable_locked_resists_known() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The slot|type line's independent cell reds (byte-read at the builder's coloring legs
-/// against the AddLine-CORE signature): a hard
-/// proficiency miss (`0xc4d4a0[class]` bit `1 << subclass`) reds the TYPE cell; the SLOT cell
-/// reds when the weapon is usable only via its alternate subclass (ItemSubClass
-/// prereq/postreq) or is an off-hand weapon without Dual Wield (`0x5eab70`). Plus the
-/// reputation-requirement red (`0xc0d390` while the player's standing is below the required
-/// rank) and the hidden-type suppression.
+/// The slot and type cells red separately: a hard proficiency miss (`0xc4d4a0[class]` bit
+/// `1 << subclass`) reds the type; usable only through the alternate subclass, or an off-hand
+/// weapon without Dual Wield (`0x5eab70`), reds the slot. The reputation line takes the red
+/// (`0xc0d390`) below the required rank, and a hidden subclass prints no type cell.
 #[test]
 fn proficiency_and_reputation_reds() {
     let mut s = script();
@@ -306,8 +287,7 @@ fn proficiency_and_reputation_reds() {
         white,
         "met reputation is white"
     );
-    // 1H-axes-only mask, no alternate on the view: the hard miss reds the TYPE cell and the
-    // slot stays white. Friendly standing reds the rep line.
+    // A 1H-axes mask, no alternate: the type cell reds, not the slot; Friendly reds the rep line.
     let mut req2 = req;
     req2.proficiency.insert(2, 1 << 0);
     req2.rep_ranks.insert(72, 4);
@@ -326,8 +306,7 @@ fn proficiency_and_reputation_reds() {
         red,
         "unmet reputation is red"
     );
-    // The same mask with the view's alternate resolved to 1H axes (the real (2,1) row's
-    // prerequisite): usable-via-alternate reds the SLOT cell instead; the type goes white.
+    // With the alternate set to 1H axes, as the real (2, 1) row has it, the slot reds instead.
     let mut alt = item;
     alt.proficiency_alt = Some(0);
     s.set_item_template(871, alt);
@@ -344,8 +323,7 @@ fn proficiency_and_reputation_reds() {
         white,
         "the alternate covers the type"
     );
-    // An off-hand weapon with its dagger bit set still reds the SLOT cell without Dual
-    // Wield; learning it (an effect-40 spell) clears the red.
+    // An off-hand dagger reds the slot until Dual Wield (an effect-40 spell) is known.
     s.set_item_template(
         872,
         ItemTemplateView {
@@ -363,8 +341,7 @@ fn proficiency_and_reputation_reds() {
     s.run(r#"TT:SetOwner(Slot9, "ANCHOR_RIGHT"); TT:BenillaSetItemById(872)"#)
         .unwrap();
     let lines = lines_of(&mut s);
-    // `INVTYPE_WEAPONOFFHAND`, NOT `INVTYPE_SHIELD` — one enUS sentence, two keys, and only the
-    // weapon one belongs on an InventoryType 22.
+    // Type 22 takes `INVTYPE_WEAPONOFFHAND`, not `INVTYPE_SHIELD`, though both read "Off Hand".
     assert_eq!(
         color(&lines, "[INVTYPE_WEAPONOFFHAND]"),
         red,
@@ -385,13 +362,12 @@ fn proficiency_and_reputation_reds() {
         white,
         "Dual Wield clears it"
     );
-    // An item class with NO proficiency entry never reds (the map only ever holds classes
-    // the server sent masks for).
+    // A class with no proficiency entry never reds: the map holds only what the server sent.
     s.set_item_template(
         118,
         ItemTemplateView {
             name: "Tattered Cloth Vest".into(),
-            class: 4,    // armor — but req2 carries no class-4 entry
+            class: 4,    // armor, with no class-4 entry in req2
             subclass: 1, // cloth
             inventory_type: 5,
             ..Default::default()
@@ -405,7 +381,7 @@ fn proficiency_and_reputation_reds() {
         white,
         "a class with no mask entry stays white"
     );
-    // A hidden subclass (displayFlags bit 0 — the Miscellaneous family) prints no type cell.
+    // A hidden subclass (displayFlags bit 0, the Miscellaneous family) prints no type cell.
     s.set_item_template(
         889,
         ItemTemplateView {
@@ -429,9 +405,8 @@ fn proficiency_and_reputation_reds() {
     assert!(s.take_errors().is_empty());
 }
 
-/// ITEM_MIN_LEVEL's `> 1` gate (byte-VERIFIED `0x52d2cf`: `cmp esi,0x1 / jle skip`): a level-1
-/// requirement — every starter consumable's shape (bread/water carry `RequiredLevel 1`) —
-/// prints NO line, exactly like no requirement at all; level 2 is the first that prints.
+/// `ITEM_MIN_LEVEL` prints only above 1 (`0x52d2cf`): a level-1 requirement, as starter food and
+/// water carry, prints nothing.
 #[test]
 fn required_level_one_is_hidden() {
     let mut s = script();
@@ -463,28 +438,9 @@ fn required_level_one_is_hidden() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The instance tail (byte-read 2026-07-20, `0x52e1b1`–`0x52e358`): a REAL-instance hover
-/// (`SetBagItem`) appends the creator line — "Written by %s"
-/// (white) when the instance carries letter text, the green-escaped "<Made by %s>" otherwise —
-/// then READABLE off the instance text id (its template's PageText is 0 — the
-/// director-reported gap). An unresolved creator (name query in flight) emits no line. LOCKED
-/// yields to the instance UNLOCKED bit — which is also what un-gates ITEM_OPENABLE: a bag hover
-/// on an openable instance shows the green `<Right Click to Open>` (director-observed on a clam;
-/// the `p6` leg selector, `0x6e2ed0`, gates it).
-/// A **running cooldown** takes SetBagItem's other leg and suppresses the line — the two are
-/// structurally exclusive on this binding (decision 0896).
-/// **Line 3 — the charter's guild name and master**, between the NAME and the green
-/// `ITEM_SIGNABLE` (the builder `0x52b650`'s emission order: 2 NAME, 3 the petition
-/// triple, 4 SIGNABLE).
-///
-/// The director's report was that our charter tooltip showed the name and the green line with
-/// nothing between them, where the real client prints "Guild Name: BTC" / "Guild Master:
-/// Twowarrior". The ORDER is the half a text-only assertion would miss: these lines sit above the
-/// green one, not below it.
-///
-/// Also pinned: the two key families (a plain petition reads "Petition:" / "Created by"), and that
-/// an unresolved owner withholds only its own line — the creator line's rule, and the reason a
-/// first hover of an unopened charter is not blank but partial.
+/// A charter's guild name and master sit between the item name and the green `ITEM_SIGNABLE`
+/// (`0x52b650` emits the name, the petition lines, then SIGNABLE). A plain petition takes the
+/// "Petition:" and "Created by" keys, and an owner still in flight withholds only its own line.
 #[test]
 fn charter_lines_sit_between_the_name_and_the_signable_line() {
     let mut s = script();
@@ -494,7 +450,7 @@ fn charter_lines_sit_between_the_name_and_the_signable_line() {
         ItemTemplateView {
             name: "Guild Charter".into(),
             quality: 1,
-            flags: 0x2000, // ITEM_FLAG_CHARTER — the green line's own gate
+            flags: 0x2000, // ITEM_FLAG_CHARTER, the green line's own gate
             max_count: 1,
             bonding: 1,
             ..Default::default()
@@ -517,7 +473,6 @@ fn charter_lines_sit_between_the_name_and_the_signable_line() {
             owner: Some("Twowarrior".into()),
         })),
     );
-    // The owner's name still in flight — the title line stands, its own does not.
     slots.insert(
         2,
         charter(Some(PetitionSlotView {
@@ -526,9 +481,7 @@ fn charter_lines_sit_between_the_name_and_the_signable_line() {
             owner: None,
         })),
     );
-    // No record yet at all: the plate is the name and the green line, as it was before this.
     slots.insert(3, charter(None));
-    // A non-charter petition takes the OTHER key family.
     slots.insert(
         4,
         charter(Some(PetitionSlotView {
@@ -663,9 +616,6 @@ fn instance_tail_creator_and_readable() {
     slots.insert(3, slot(2589, false, Some("Geoffrey"), 0)); // crafted, still locked
     slots.insert(4, slot(2589, false, None, 0x4)); // unlocked → LOCKED gone, open line on
     slots.insert(5, slot(7973, false, None, 0)); // the clam: lockless, openable outright
-                                                 // The same clam with a RUNNING cooldown — `SetBagItem`'s p6=1 leg, which skips the openable
-                                                 // tree entirely (the ITEM_COOLDOWN_TIME line takes its place in the reference; that line has
-                                                 // no feed here yet, so this slot renders bare).
     slots.insert(
         6,
         ContainerSlot {
@@ -698,12 +648,12 @@ fn instance_tail_creator_and_readable() {
     );
     assert_eq!(lines[1].1, [1.0, 1.0, 1.0, 1.0], "WRITTEN_BY is white");
     assert_eq!(lines[2].1, [0.0, 1.0, 0.0, 1.0], "READABLE is green");
-    // Creator unresolved → no writer line, READABLE stays (the re-push repaints later).
+    // The instance tail (`0x52e1b1`-`0x52e358`): a creator still in flight prints no writer line,
+    // and READABLE stays.
     s.run(r#"TT:SetOwner(getglobal("SlotL"), "ANCHOR_RIGHT"); TT:SetBagItem(0, 2)"#)
         .unwrap();
     let texts: Vec<String> = lines_of(&mut s).into_iter().map(|(t, _)| t).collect();
     assert_eq!(texts, vec!["Plain Letter", "[ITEM_READABLE]"]);
-    // Crafted + locked: the green-escaped Made-by; no open line while LockID gates it.
     s.run(r#"TT:SetOwner(getglobal("SlotL"), "ANCHOR_RIGHT"); TT:SetBagItem(0, 3)"#)
         .unwrap();
     let texts: Vec<String> = lines_of(&mut s).into_iter().map(|(t, _)| t).collect();
@@ -716,22 +666,19 @@ fn instance_tail_creator_and_readable() {
         ],
         "CREATED_BY carries the string's own green escape; locked chest hides OPENABLE"
     );
-    // The instance UNLOCKED bit retires the LOCKED line AND satisfies the openable lock sub-gate.
+    // The instance's UNLOCKED bit drops the LOCKED line and satisfies the openable lock gate.
     s.run(r#"TT:SetOwner(getglobal("SlotL"), "ANCHOR_RIGHT"); TT:SetBagItem(0, 4)"#)
         .unwrap();
     let lines = lines_of(&mut s);
     let texts: Vec<&str> = lines.iter().map(|(t, _)| t.as_str()).collect();
     assert_eq!(texts, vec!["Heavy Chest", "[ITEM_OPENABLE]"]);
     assert_eq!(lines[1].1, [0.0, 1.0, 0.0, 1.0], "OPENABLE is green");
-    // The director's case: a lockless LOOTABLE template (a clam) is openable outright — name +
-    // the green line, nothing between them.
     s.run(r#"TT:SetOwner(getglobal("SlotL"), "ANCHOR_RIGHT"); TT:SetBagItem(0, 5)"#)
         .unwrap();
     let texts: Vec<String> = lines_of(&mut s).into_iter().map(|(t, _)| t).collect();
     assert_eq!(texts, vec!["Small Barnacled Clam", "[ITEM_OPENABLE]"]);
-    // The same clam mid-cooldown takes SetBagItem's OTHER leg (p6=1) — the openable tree is
-    // skipped wholesale, so the green line is gone (the reference prints ITEM_COOLDOWN_TIME in
-    // its place; unfed here). `hasCooldown`, the binding's own return, is the same boolean.
+    // Mid-cooldown the clam takes `SetBagItem`'s other leg (p6 = 1, picked at `0x6e2ed0`), which
+    // skips the openable tree; the reference prints `ITEM_COOLDOWN_TIME` there, unfed here.
     let has_cd: bool = s
         .eval(r#"TT:SetOwner(getglobal("SlotL"), "ANCHOR_RIGHT"); return TT:SetBagItem(0, 6)"#)
         .unwrap();
@@ -745,25 +692,15 @@ fn instance_tail_creator_and_readable() {
     assert!(s.take_errors().is_empty());
 }
 
-/// **The bind line's Soulbound override** — the bind line reads the INSTANCE, not only the template
-/// (an equipped Maiden's Circle reads *Soulbound*, not *Binds when equipped*; equipped pants
-/// likewise, not *Binds when picked up*).
-///
-/// The reference's rule: Bonding `[record+0x194]` ∈ {1..5}
-/// decides whether a line prints at all; a **runtime-bound instance** (`0x5da2c0` — soulbound
-/// flag, or a live enchant slot that binds) overrides it to `ITEM_SOULBOUND`, and to
-/// `ITEM_BIND_QUEST` for the quest kinds; only then does the jump table `0x52e4fc` pick
-/// 1→picked up · 2→equipped · 3→used · 4/5→Quest Item.
-///
-/// Four claims, three of them controls: the override fires on a bound instance, an UNbound
-/// instance of the same item still reads *Binds when equipped*, a template hover (no instance at
-/// all) still reads *Binds when equipped*, and a bound QUEST item stays *Quest Item* — the
-/// override's other arm is the same text 4|5 print anyway.
+/// Bonding `[record+0x194]` in 1..5 decides whether a bind line prints; a runtime-bound instance
+/// (`0x5da2c0`: the soulbound flag, or a live enchant slot that binds) prints `ITEM_SOULBOUND`,
+/// or `ITEM_BIND_QUEST` for the quest kinds; else the jump table `0x52e4fc` picks 1 picked up,
+/// 2 equipped, 3 used, 4 and 5 Quest Item.
 #[test]
 fn a_runtime_bound_instance_overrides_the_bind_line_to_soulbound() {
     let mut s = script();
     s.set_screen_size(800.0, 600.0);
-    s.set_item_template(871, axe()); // bonding 2 — Binds when equipped
+    s.set_item_template(871, axe()); // bonding 2: Binds when equipped
     let ring = ItemTemplateView {
         name: "Maiden's Circle".into(),
         quality: 2,
@@ -789,9 +726,9 @@ fn a_runtime_bound_instance_overrides_the_bind_line_to_soulbound() {
         ..Default::default()
     };
     let mut slots = HashMap::new();
-    slots.insert(1, slot(942, true)); // bound: the reported case
+    slots.insert(1, slot(942, true)); // bound
     slots.insert(2, slot(942, false)); // the same ring, not yet bound
-    slots.insert(3, slot(4913, true)); // a bound QUEST item
+    slots.insert(3, slot(4913, true)); // a bound quest item
     s.set_container(
         0,
         Some(ContainerState {
@@ -831,25 +768,22 @@ fn a_runtime_bound_instance_overrides_the_bind_line_to_soulbound() {
     );
     assert_eq!(color, [1.0, 1.0, 1.0, 1.0], "the bind line is white");
 
-    // Control 1: the SAME item, instance not bound — the template's bonding stands.
+    // Controls: the same ring unbound, and a template hover, which has no instance.
     s.run(r#"TT:SetBagItem(0, 2)"#).unwrap();
     assert_eq!(bind_line(&mut s).0, "[ITEM_BIND_ON_EQUIP]");
 
-    // Control 2: a TEMPLATE hover carries no instance at all, so nothing can override.
     s.run(r#"TT:BenillaSetItemById(871)"#).unwrap();
     assert_eq!(bind_line(&mut s).0, "[ITEM_BIND_ON_EQUIP]");
 
-    // Control 3: the override's other arm is ITEM_BIND_QUEST — the same text 4|5 already print.
+    // A bound quest item stays `ITEM_BIND_QUEST`, the text 4 and 5 print anyway.
     s.run(r#"TT:SetBagItem(0, 3)"#).unwrap();
     assert_eq!(bind_line(&mut s).0, "[ITEM_BIND_QUEST]");
     assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
 }
 
-/// **The damage block's five-arm template matrix** (the loop at `0x52c22b`; decision 2080 named
-/// this cell and 2158 converted it). Each arm here names the leg it takes: the school predicate is
-/// the slot's school NUMBER, the ammo predicate is `ItemClass == 6` alone, the single predicate
-/// compares the two ROUNDED bounds, and the first/`PLUS_` flag is per-item — a skipped slot does
-/// not consume it. The rounding is `floor(min)` / `ceil(max)`, not a round-half pair.
+/// The damage templates (`0x52c22b`): the school arm goes by the slot's school number, the ammo
+/// arm by `ItemClass == 6` alone, the single arm by equal rounded bounds, and the first/`PLUS_`
+/// flag is per item, kept past a skipped slot. Bounds round as `floor(min)`, `ceil(max)`.
 #[test]
 fn damage_matrix_arms_and_the_first_flag() {
     let mut s = script();
@@ -875,9 +809,7 @@ fn damage_matrix_arms_and_the_first_flag() {
         ..Default::default()
     };
 
-    // The plain two-number arm, the SKIP, and the PLUS_ twin — the skipped middle slot does not
-    // consume the first flag, so slot 2 still prints as a later line, and only the FIRST emitted
-    // line carries the Speed cell.
+    // A zero middle slot is skipped; only the first line carries the Speed cell.
     let lines = show(
         &mut s,
         900,
@@ -898,29 +830,24 @@ fn damage_matrix_arms_and_the_first_flag() {
         .expect("right cell 4");
     assert_eq!(later, "", "a later damage line renders left-only");
 
-    // floor(min) / ceil(max) on fractional bounds — Fang of the Mystics' real numbers. A
-    // round-half pair would say "39 - 86"; the biased pair says 38.
+    // Fang of the Mystics' real bounds: `floor`/`ceil` give 38 - 86, where rounding gives 39.
     let lines = show(&mut s, 901, weapon(vec![(38.7, 85.7, 0)]));
     assert_eq!(lines[2], "[DMG 38 - 86]", "{lines:?}");
 
-    // The SINGLE arm — the two ROUNDED bounds equal. It is a no-school, non-ammo leaf only.
+    // The single arm: equal rounded bounds, no school, not ammo.
     let lines = show(&mut s, 902, weapon(vec![(7.0, 7.0, 0)]));
     assert_eq!(lines[2], "[DMG1 7]", "{lines:?}");
-    // …and a school'd slot with equal bounds still takes the WITH_SCHOOL arm, two identical
-    // numbers and all: there is no SINGLE_…_WITH_SCHOOL template.
+    // A slot with a school and equal bounds takes `WITH_SCHOOL`: no single school template exists.
     let lines = show(&mut s, 903, weapon(vec![(7.0, 7.0, 4)]));
     assert_eq!(lines[2], "[DMGS 7 - 7 [SCHOOL4]]", "{lines:?}");
 
-    // AMMO is `ItemClass == 6` alone. The `%g` value is the two rounded bounds averaged and is
-    // NOT divided by anything — Rough Arrow's 1–2 reads 1.5 — and ammo gets neither a Speed
-    // cell nor a DPS line, because both gate on class 2.
+    // Ammo's `%g` is the rounded bounds' average, undivided (Rough Arrow's 1-2 reads 1.5), with
+    // no Speed cell or DPS line, both gated on class 2.
     let arrow = ItemTemplateView {
         name: "Rough Arrow".into(),
         class: 6,
         subclass: 2,
         sub_class_display: Some("Arrow".into()),
-        // `ItemClass.dbc` row 6's own name — the LEFT cell for a class-6 item, which never
-        // consults the InventoryType key table.
         item_type: Some("Projectile".into()),
         inventory_type: 24,
         damages: vec![(1.0, 2.0, 0)],
@@ -928,9 +855,8 @@ fn damage_matrix_arms_and_the_first_flag() {
         ..Default::default()
     };
     let lines = show(&mut s, 904, arrow.clone());
-    // The slot|type line above it reads "Projectile | Arrow": a class-6 item takes
-    // `ItemClass.dbc`'s own row-6 name on the LEFT (`0x52c0bc`, read verbatim — never a
-    // GlobalString), not the empty `INVTYPE_AMMO` key.
+    // The type line reads "Projectile | Arrow": the left cell is the DBC name (`0x52c0bc`),
+    // never a GlobalString such as the absent `INVTYPE_AMMO`.
     assert_eq!(lines[1], "Projectile", "{lines:?}");
     let ty: String = s
         .eval("return TTTextRight2:GetText() or ''")
@@ -984,9 +910,8 @@ fn damage_matrix_arms_and_the_first_flag() {
     );
 }
 
-/// **The bag line** (`0x52b754`): its gate is `InventoryType == 0x12` alone — never the
-/// slot count — and its second hole is the same `ItemSubClass` DisplayName the type cell reads, so
-/// the noun is per-subclass. A container whose row names nothing prints no slot line at all.
+/// The bag line (`0x52b754`) gates on `InventoryType == 0x12` alone, and its noun is the
+/// subclass's DisplayName; a row with no name prints no line.
 #[test]
 fn container_slots_line_names_its_subclass() {
     let mut s = script();
@@ -1020,17 +945,15 @@ fn container_slots_line_names_its_subclass() {
         "[SLOTS 24 Soul Bag]",
         "the noun is the subclass's, not a constant"
     );
-    // A quiver is InventoryType 18 like every other container — INVTYPE_QUIVER is a dead slot
-    // name in 1.12 — so it reaches this line and names itself.
+    // A quiver is InventoryType 18 like any container, so it names itself here.
     let mut quiver = bag(2, Some("Quiver"), 8);
     quiver.class = 11;
     assert_eq!(show(&mut s, 912, quiver)[1], "[SLOTS 8 Quiver]");
-    // The gate never tests the slot count.
     assert_eq!(
         show(&mut s, 913, bag(0, Some("Bag"), 0))[1],
         "[SLOTS 0 Bag]"
     );
-    // No row name: NEITHER this line nor the ordinary slot|type one.
+    // No row name: neither this line nor the slot and type line.
     let lines = show(&mut s, 914, bag(0, None, 16));
     assert_eq!(lines.len(), 1, "name line only: {lines:?}");
 }
diff --git a/crates/benilla-ui/src/script/tests/tooltip_item/mechanics.rs b/crates/benilla-ui/src/script/tests/tooltip_item/mechanics.rs
index a618f52b..e07b04ef 100644
--- a/crates/benilla-ui/src/script/tests/tooltip_item/mechanics.rs
+++ b/crates/benilla-ui/src/script/tests/tooltip_item/mechanics.rs
@@ -1,15 +1,13 @@
-//! Render mechanics around the line law: the sell-price money protocol (OnTooltipAddMoney +
-//! ITEM_UNSELLABLE), wrapped-line measurement through the re-enter loop, and the unit health
-//! bar hiding on an item render.
+//! Render mechanics around the line order: sell price, wrapped lines, the unit health bar,
+//! durability, enchant lines and random-property rolls.
 
 use std::collections::HashMap;
 
 use super::script;
 use crate::script::*;
 
-/// The sell-price money protocol: SetBagItem at an open merchant fires OnTooltipAddMoney with
-/// SellPrice × stack; price 0 prints the ITEM_UNSELLABLE line; no merchant → neither; the
-/// in-flight template renders the link-name fallback and records the ask.
+/// `SetBagItem` at an open merchant fires `OnTooltipAddMoney` with SellPrice × stack, and price 0
+/// prints `ITEM_UNSELLABLE`; with no merchant, neither. A template in flight renders the link name.
 #[test]
 fn bag_item_money_law_and_fallback() {
     let mut s = script();
@@ -80,7 +78,6 @@ fn bag_item_money_law_and_fallback() {
     )
     .unwrap();
     assert_eq!(s.take_item_stat_asks(), vec![9999], "the miss asked");
-    // Zero sell price at a merchant: the ITEM_UNSELLABLE line, no money.
     s.set_item_template(
         9999,
         ItemTemplateView {
@@ -104,13 +101,8 @@ fn bag_item_money_law_and_fallback() {
     assert!(s.take_errors().is_empty());
 }
 
-/// A wrap-flagged line carries its wrap column on the VERY FIRST measure ask (append_line pins
-/// the region width at write time), so ONE round-trip answers the wrapped extent — and the
-/// plate height/width converge even when the hover's re-enter loop clears + rebuilds the
-/// content every frame. The old two-step (layout re-pinning after an overflowing unwrapped
-/// measure) never converged under that loop: the wrapped re-measure was wiped before it could
-/// land, wrap lines contributed no height, and everything after them spilled below the plate
-/// (the live bread/hearthstone bug).
+/// A wrap line's first measure asks with the wrap column, so one pass answers the wrapped size,
+/// and the size holds while the hover clears and rebuilds the content every frame.
 #[test]
 fn wrap_lines_measure_wrapped_in_one_pass_and_survive_the_reenter_loop() {
     let mut s = script();
@@ -137,8 +129,7 @@ fn wrap_lines_measure_wrapped_in_one_pass_and_survive_the_reenter_loop() {
     )
     .unwrap();
     s.resolve();
-    // ONE measure pass, the frame loop's shape: the wrap-flagged description asks WITH the
-    // wrap column; plain lines ask unconstrained.
+    // One measure pass: the wrap-flagged description asks with the wrap column, others without.
     let answer = |s: &mut UiScript| {
         let reqs = s.fontstrings_needing_measure();
         let answers: Vec<(u32, f32, f32, u64)> = reqs
@@ -168,8 +159,7 @@ fn wrap_lines_measure_wrapped_in_one_pass_and_survive_the_reenter_loop() {
     "#,
     )
     .unwrap();
-    // The re-enter loop: clear + rebuild + one measure pass per frame, three frames — the size
-    // must HOLD (the oscillation regression).
+    // Clear, rebuild and measure once per frame for three frames: the size holds.
     for _ in 0..3 {
         s.run(
             r#"
@@ -191,8 +181,7 @@ fn wrap_lines_measure_wrapped_in_one_pass_and_survive_the_reenter_loop() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The mouseover health bar is UNIT content: an item render on the same tooltip HIDES it (the
-/// live bug: the bar from the last mob hover rode under every item tooltip).
+/// The mouseover health bar is unit content: an item render on the same tooltip hides it.
 #[test]
 fn item_render_hides_the_unit_health_bar() {
     let mut s = script();
@@ -241,9 +230,8 @@ fn item_render_hides_the_unit_health_bar() {
     assert!(s.take_errors().is_empty());
 }
 
-/// A REAL-INSTANCE hover renders the instance's LIVE durability pair, not the template's full
-/// max/max — the wire updates `ITEM_FIELD_DURABILITY` on damage (death 10%, spirit healer 25%;
-/// director-reported: the 25% loss showed nowhere). A plain template/link hover keeps max/max.
+/// A bag hover shows the instance's live `ITEM_FIELD_DURABILITY` (a death costs 10%, the spirit
+/// healer 25%); a template or link hover shows max/max.
 #[test]
 fn real_instance_hover_renders_live_durability() {
     let mut s = script();
@@ -302,10 +290,8 @@ fn real_instance_hover_renders_live_durability() {
     assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
 }
 
-/// FULLY BROKEN gear renders its true `0 / max` pair (director-caught: gear ground to durability
-/// 0 by repeated spirit rezzes read as 100% — the create block omits the zero `DURABILITY` field,
-/// and the sparse `None` fell back to the template's max/max; `ObjectFields`' created semantics
-/// now feed the explicit 0 through).
+/// Broken gear shows its true `0 / max`: a create block omits a zero `DURABILITY`, which must not
+/// read as the template's max.
 #[test]
 fn broken_instance_hover_renders_zero_durability() {
     let mut s = script();
@@ -353,8 +339,7 @@ fn broken_instance_hover_renders_zero_durability() {
     )
     .unwrap();
     assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
-    // Red iff broken (`0x854bc4`, colour `0xc0d390`): the 0/40
-    // line paints the requirement red, never white.
+    // Red only when broken (`0x854bc4`, colour `0xc0d390`).
     let lines = super::lines_of(&mut s);
     let dur = lines
         .iter()
@@ -367,12 +352,8 @@ fn broken_instance_hover_renders_zero_durability() {
     );
 }
 
-/// The **enchant lines** (law line 17, decision 0915) — the director's report: an axe carrying
-/// Enchant Weapon - Agility showed its green glow in the world and said nothing in the tooltip.
-///
-/// Three claims at once: the line renders from the instance's resolved enchant text, it sits
-/// **between the resistances and the durability line** (the law's 16 → 17 → 18), and it is green.
-/// The control is the template/link hover of the same item — no instance, no enchant, no line.
+/// An instance's enchant prints from its resolved text, in green, between the resistances and
+/// durability; a template hover of the same item has no instance and so no enchant line.
 #[test]
 fn an_enchanted_instance_renders_its_enchant_line_before_durability() {
     let mut s = script();
@@ -384,8 +365,7 @@ fn an_enchanted_instance_renders_its_enchant_line_before_durability() {
             quality: Some(4),
             item_id: 22816,
             durability: Some((105, 105)),
-            // What the app resolved from `ITEM_FIELD_ENCHANTMENT` slot 0 → enchant 2564 →
-            // `SpellItemEnchantment`'s own name string. Slot 0 = permanent, positive id.
+            // `ITEM_FIELD_ENCHANTMENT` slot 0 (permanent) → enchant 2564 → its name string.
             enchants: vec![EnchantView {
                 slot: 0,
                 name: "Agility +15".into(),
@@ -441,7 +421,6 @@ fn an_enchanted_instance_renders_its_enchant_line_before_durability() {
         "the enchant line is green"
     );
 
-    // The control: the same item as a TEMPLATE hover has no instance, so no enchant line.
     s.run(r#"TT:BenillaSetItemById(22816)"#).unwrap();
     let lines = super::lines_of(&mut s);
     assert!(
@@ -451,11 +430,8 @@ fn an_enchanted_instance_renders_its_enchant_line_before_durability() {
     assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
 }
 
-/// The **enchant colour bands** (`0x52ca29`, decision 0920). The colour is per SLOT, not per
-/// family: only slots 0 (permanent) and 1 (temporary) are ever coloured — green for a positive id,
-/// the tooltip's OTHER red (`0xc0d398 = ffff0000`, distinct from the requirement lines' `ffff2020`)
-/// for a negative one — and the random-property slots 2..6 are always white whatever the sign. Our
-/// first cut painted every slot green.
+/// Enchant colour goes by slot (`0x52ca29`): slots 0 and 1 are green for a positive id and pure
+/// red (`0xc0d398`, `ffff0000`, not the requirement `ffff2020`) for a negative one; 2..6 are white.
 #[test]
 fn enchant_line_colour_is_per_slot_and_sign() {
     let mut s = script();
@@ -483,7 +459,6 @@ fn enchant_line_colour_is_per_slot_and_sign() {
                     name: "Stamina +7".into(),
                     ..Default::default()
                 },
-                // A suffix slot with a NEGATIVE id is still white — the band, not the sign, rules.
                 EnchantView {
                     slot: 4,
                     name: "Spirit +3".into(),
@@ -546,10 +521,8 @@ fn enchant_line_colour_is_per_slot_and_sign() {
     );
 }
 
-/// The temporary enchant's countdown REPLACES the name in the same line (never a second one), and
-/// the charges suffix rides after it — the `0x52fa50` bucket ladder and the `" (%s)"` join. The
-/// countdown's source is `SMSG_ITEM_ENCHANT_TIME_UPDATE`, so a slot with no packet shows the bare
-/// name: that is the control here.
+/// A temporary enchant prints one line, its countdown template (`0x52fa50`) around the name, then
+/// the charges joined by `" (%s)"`; with no `SMSG_ITEM_ENCHANT_TIME_UPDATE` it is the bare name.
 #[test]
 fn temporary_enchant_line_carries_its_countdown_and_charges() {
     let mut s = script();
@@ -615,15 +588,11 @@ fn temporary_enchant_line_carries_its_countdown_and_charges() {
     );
 }
 
-/// **The loot hover shows the ROLL, never the placeholder** (decision 1547). `SetLootItem 0x533470`
-/// writes an instance block (p6=1) whose `+0x424` is the wire's randomPropertyId and whose seven
-/// enchant slots are zeroed, and passes an all-zero item GUID — so there is never an object, the
-/// builder takes the suffix-row copy (`0x52b7e0`) into slots 2..6, and the `ITEM_RANDOM_ENCHANT`
-/// arm is unreachable (the entry fork, `0x52c991`). The row's name is the suffix-joined one
-/// (`0x5d8b00`, the same string `GetLootSlotInfo` returns), so the plate reads "… of the Monkey".
-///
-/// This is the reported bug's exact shape: through the template path (`BenillaSetItemById`) the same
-/// hover printed the ITEM_RANDOM_ENCHANT placeholder until the item reached a bag.
+/// A loot hover shows the roll, never the placeholder: `SetLootItem` (`0x533470`) builds an
+/// instance block (p6 = 1) with the roll at `+0x424`, zeroed enchant slots and no object, so the
+/// builder copies the suffix row into slots 2..6 (`0x52b7e0`) and never reaches
+/// `ITEM_RANDOM_ENCHANT` (`0x52c991`). The name is the suffixed one `GetLootSlotInfo` returns
+/// (`0x5d8b00`).
 #[test]
 fn a_looted_roll_shows_its_lines_and_never_the_placeholder() {
     let mut s = script();
@@ -633,8 +602,7 @@ fn a_looted_roll_shows_its_lines_and_never_the_placeholder() {
             name: "Bloodrazor".into(),
             quality: 2,
             class: 2,
-            // The template CAN roll — the placeholder's own gate, so its absence below is the law
-            // and not an accident of the fixture.
+            // The template can roll, so the placeholder's absence below is the rule at work.
             random_property: 42,
             ..Default::default()
         },
@@ -649,8 +617,7 @@ fn a_looted_roll_shows_its_lines_and_never_the_placeholder() {
             is_coin: false,
             item_id: 8888,
             link: Some("|cff1eff00|Hitem:8888:0:584:0|h[Bloodrazor of the Monkey]|h|r".into()),
-            // The row carries the ROLL, not resolved lines — the engine resolves it, like the
-            // reference reading its own DBC store off the block's `+0x424`.
+            // The row carries the roll id; the engine resolves it, as the reference reads `+0x424`.
             random_property_id: 584,
         })],
         fishing: false,
@@ -702,15 +669,12 @@ fn a_looted_roll_shows_its_lines_and_never_the_placeholder() {
             .iter()
             .find(|(t, _)| t == line)
             .unwrap_or_else(|| panic!("the roll's slot line {line} — got {texts:?}"));
-        // Slots 2..6 are always WHITE, whatever the sign (`0x52ca29`).
         assert_eq!(l.1, [1.0, 1.0, 1.0, 1.0], "{line} is white");
     }
 }
 
-/// The other half of the same law: a loot row with **no** roll shows no enchant line AND no
-/// placeholder, even though the template can roll. The fork tests the block's presence, not its
-/// contents (`0x52c9a3`) — which is why this cannot be expressed as "print the placeholder when the
-/// slots are empty".
+/// A loot row with no roll shows neither enchant lines nor the placeholder, though the template can
+/// roll: the fork tests the block's presence, not its contents (`0x52c9a3`).
 #[test]
 fn a_looted_item_with_no_roll_shows_neither_line_nor_placeholder() {
     let mut s = script();
@@ -754,11 +718,8 @@ fn a_looted_item_with_no_roll_shows_neither_line_nor_placeholder() {
     );
 }
 
-/// A **chat link** is a block source too (`SetHyperlink 0x532181`, p6=1): its `|Hitem:` token 2 is
-/// the roll, which `0x52b7e0` expands into slots 2..6, and the placeholder arm is unreachable.
-/// Decision 0920's prose said a hyperlink hover shows the placeholder; `0x52c9a3` says otherwise,
-/// and this is the case that proves it — the same drop, linked in chat instead of hovered in the
-/// loot window, must read identically.
+/// A chat link is a block source too (`SetHyperlink` `0x532181`, p6 = 1): its `|Hitem:` token 2 is
+/// the roll, `0x52b7e0` expands it into slots 2..6, and `0x52c9a3` never reaches the placeholder.
 #[test]
 fn a_linked_roll_shows_its_lines_and_never_the_placeholder() {
     let mut s = script();
@@ -815,10 +776,8 @@ fn a_linked_roll_shows_its_lines_and_never_the_placeholder() {
     );
 }
 
-/// `ITEM_RANDOM_ENCHANT` (`0x52cc33`) — the template-only placeholder: a random-property item with
-/// NO instance to read a roll from prints it, green, and the per-slot lines and this one are
-/// mutually exclusive by construction. The control is the same template hovered as a real enchanted
-/// instance: the roll is known, so the placeholder gives way to the slot lines.
+/// `ITEM_RANDOM_ENCHANT` (`0x52cc33`) prints, green, only for a random-property item with no
+/// instance to read a roll from; an instance's known roll prints its slot lines instead.
 #[test]
 fn random_property_template_hover_shows_the_placeholder() {
     let mut s = script();
@@ -848,7 +807,6 @@ fn random_property_template_hover_shows_the_placeholder() {
         .expect("the template hover shows the placeholder");
     assert_eq!(placeholder.1, [0.0, 1.0, 0.0, 1.0], "green");
 
-    // With a real instance (the roll is known) the placeholder is gone and the slots print.
     let mut slots = HashMap::new();
     slots.insert(
         1,
diff --git a/crates/benilla-ui/src/script/tests/tooltip_item/mod.rs b/crates/benilla-ui/src/script/tests/tooltip_item/mod.rs
index 531bd138..9c4107a6 100644
--- a/crates/benilla-ui/src/script/tests/tooltip_item/mod.rs
+++ b/crates/benilla-ui/src/script/tests/tooltip_item/mod.rs
@@ -1,22 +1,13 @@
-//! The engine item-tooltip renderer (decision 0274 P1, law per 0276): the verified line law
-//! end-to-end, the red failed-requirement law against live player state, the sell-price money
-//! protocol (engine fires `OnTooltipAddMoney` — merchant open + real instance + repair off),
-//! and the in-flight-template fallback.
+//! The engine item-tooltip renderer: line order, requirement reds against live player state, the
+//! sell price (`OnTooltipAddMoney` at an open merchant, for a real instance, out of repair mode)
+//! and the fallback for a template still in flight.
 
 use super::common::script as bare_script;
 use crate::script::*;
 
-/// A stand-in `GlobalStrings.lua` for the item builder — **deliberately not the shipped wording**.
-///
-/// Every sentence the builder draws is a key resolved off the VM's own globals (decision 2045),
-/// and what these tests establish is *which key* each line reaches and what fills it, never what
-/// the sentence says. Naming each value after its own key is the point: `INVTYPE_SHIELD`,
-/// `INVTYPE_WEAPONOFFHAND` and `SECONDARYHANDSLOT` all read "Off Hand" in enUS, `ITEM_REQ_SKILL`
-/// shares "Requires %s" with the three `LOCKED_WITH_*` keys, and an assertion on the English
-/// would pass on every one of them. Read an expected line here as "this key, filled with these".
-///
-/// The values keep each shipped template's *hole shape* — that is what proves the fill — and
-/// nothing else about it.
+/// Stand-in `GlobalStrings.lua` values, each named after its key with the shipped hole shape:
+/// several keys share one enUS sentence ("Off Hand", "Requires %s"), so the tests assert which key
+/// each line reaches and what fills it.
 fn seed_item_strings(s: &mut UiScript) {
     s.run(
         r#"
@@ -121,8 +112,7 @@ fn seed_item_strings(s: &mut UiScript) {
     .unwrap();
 }
 
-/// The shared fixture VM, with [`seed_item_strings`] already run — every test in this tree needs
-/// it, because a builder that resolves nothing draws nothing.
+/// The fixture VM, with [`seed_item_strings`] run.
 fn script() -> UiScript {
     let mut s = bare_script();
     seed_item_strings(&mut s);
@@ -136,8 +126,7 @@ fn axe() -> ItemTemplateView {
         quality: 3,
         class: 2,
         subclass: 1,
-        // ItemSubClass.dbc's DisplayName for (2, 1) — the app-resolved word the type cell
-        // prints; the two axe subclasses share it.
+        // `ItemSubClass.dbc`'s DisplayName for (2, 1), which both axe subclasses share.
         sub_class_display: Some("Axe".into()),
         inventory_type: 17,
         bonding: 2,
@@ -155,8 +144,7 @@ fn axe() -> ItemTemplateView {
     }
 }
 
-/// The tooltip's left-column lines in order, each with its draw color (read from the extract —
-/// the color a renderer would actually paint).
+/// The tooltip's left-column lines in order, each with the colour the extract paints it.
 fn lines_of(s: &mut UiScript) -> Vec<(String, [f32; 4])> {
     s.resolve();
     let quads = s.extract();
diff --git a/crates/benilla-ui/src/script/tests/tooltip_item/set.rs b/crates/benilla-ui/src/script/tests/tooltip_item/set.rs
index 2b833993..ae351242 100644
--- a/crates/benilla-ui/src/script/tests/tooltip_item/set.rs
+++ b/crates/benilla-ui/src/script/tests/tooltip_item/set.rs
@@ -1,19 +1,12 @@
-//! The item-SET block (`ITEM_SET_NAME 0x854b1c`): order (blank, gold header, skill line, member
-//! ladder, blank, bonuses), the threshold-ascending sort, the skill gate, member cream/gray, and
-//! the ask-once for unseen set ids.
+//! The item-set block (`ITEM_SET_NAME` `0x854b1c`): a blank, the gold header, the skill line, the
+//! member ladder, a blank, then the bonuses by ascending threshold; and the quest reward hovers.
 
 use super::{lines_of, script};
 use crate::script::*;
 
-/// The SET block, byte-read: a blank gold line, the gold `ITEM_SET_NAME` header, the skill
-/// line (white/red) between header and the member ladder (cream when equipped / gray; in-flight
-/// names wait), a second blank, then the threshold bonuses SORTED ascending — green only when the
-/// skill requirement is met AND owned ≥ threshold — plus the ask-once for an unseen set id.
-///
-/// **The two bonus arms are two different keys** (`0x52e056..0x52e0d6`): an ACTIVE bonus formats
-/// `ITEM_SET_BONUS` = "Set: %s" with no count at all, and only an inactive one formats
-/// `ITEM_SET_BONUS_GRAY` = "(%d) Set: %s". Watching the (2) bonus move between them as the skill
-/// gate opens and closes is what these assertions are for.
+/// Members are cream when equipped and gray otherwise; a bonus is green only with the skill met
+/// and enough owned. The bonus arms are two keys (`0x52e056..0x52e0d6`): an active bonus formats
+/// `ITEM_SET_BONUS` ("Set: %s", no count), an inactive one `ITEM_SET_BONUS_GRAY` ("(%d) Set: %s").
 #[test]
 fn item_set_block_counts_and_colors() {
     let mut s = script();
@@ -29,7 +22,7 @@ fn item_set_block_counts_and_colors() {
     };
     vest.stats.clear();
     s.set_item_template(6303, vest);
-    // Two members equipped (the chest itself + the belt).
+    // Two members equipped: the chest itself and the belt.
     let mut slots: InventorySlots = Default::default();
     slots[4] = Some(InvSlotView {
         item_id: 6303,
@@ -46,11 +39,10 @@ fn item_set_block_counts_and_colors() {
             (6303, Some("Defias Mark".into())),
             (6304, Some("Defias Belt".into())),
             (6305, Some("Defias Gloves".into())),
-            (6306, None), // template still in flight — no line yet
+            (6306, None), // template still in flight: no line yet
             (6307, Some("Defias Boots".into())),
         ],
-        // Stored high-first (the catalog keeps DBC slot order — The Gladiator ships
-        // 3,2,5,4): the renderer must sort ascending at print time.
+        // Stored high-first in DBC slot order (The Gladiator ships 3,2,5,4); the renderer sorts.
         bonuses: vec![
             (4, "+10 Attack Power.".into()),
             (2, "Increases movement speed slightly.".into()),
@@ -120,8 +112,7 @@ fn item_set_block_counts_and_colors() {
         gray,
         "inactive bonus is gray"
     );
-    // The skill gate (`0x5eaae0`): an unmet set-level skill reds its line — seated between
-    // the header and the first member — and grays every bonus, met thresholds included.
+    // The skill gate (`0x5eaae0`): an unmet skill reds its line and grays every bonus.
     let mut gated = set_view;
     gated.required_skill = 165;
     gated.required_skill_rank = 250;
@@ -138,7 +129,7 @@ fn item_set_block_counts_and_colors() {
     .unwrap();
     let lines = lines_of(&mut s);
     assert_eq!(color(&lines, "[MIN_SKILL Leatherworking 250]"), red);
-    // The gate also moves it onto the OTHER key: an inactive bonus is the counted spelling.
+    // Grayed, the (2) bonus takes the counted key.
     assert_eq!(
         color(
             &lines,
@@ -162,7 +153,6 @@ fn item_set_block_counts_and_colors() {
         green,
         "meeting the skill restores the green — and the countless key with it"
     );
-    // An unseen set id records the ask-once.
     s.set_item_template(
         9999,
         ItemTemplateView {
@@ -177,10 +167,8 @@ fn item_set_block_counts_and_colors() {
     assert!(s.take_errors().is_empty());
 }
 
-/// `GameTooltip:SetQuestItem(type, index)` and `SetQuestLogItem(type, index)` — the quest-giver
-/// panels' and the quest log's reward hovers (stock QuestFrameTemplates.xml:148,
-/// QuestLogFrame.xml:113): the row's item by id through the shared renderer; a row that is not
-/// there leaves the tooltip empty (1944).
+/// `SetQuestItem` and `SetQuestLogItem`, the reward hovers (`QuestFrameTemplates.xml:148`,
+/// `QuestLogFrame.xml:113`), render the row's item by id; a missing row leaves the tooltip empty.
 #[test]
 fn quest_item_hovers_render_the_rows_item_by_id() {
     let mut s = script();
@@ -236,7 +224,7 @@ fn quest_item_hovers_render_the_rows_item_by_id() {
         }],
         ..Default::default()
     });
-    // The detail hangs on the row now, so the tooltip reads it through the selection (2247).
+    // The detail hangs on the selected row, so select it first.
     s.run("SelectQuestLogEntry(1)").unwrap();
     s.run(r#"TT:SetOwner(Q1, "ANCHOR_RIGHT"); TT:SetQuestLogItem("reward", 1)"#)
         .unwrap();
diff --git a/crates/benilla-ui/src/script/tests/tooltip_spell.rs b/crates/benilla-ui/src/script/tests/tooltip_spell.rs
index 44b9f013..4a83a075 100644
--- a/crates/benilla-ui/src/script/tests/tooltip_spell.rs
+++ b/crates/benilla-ui/src/script/tests/tooltip_spell.rs
@@ -1,8 +1,6 @@
-//! The engine spell/aura tooltip channel (decision 0274 P2, law per 0276): the verified line
-//! shapes — name|rank, ONE cost|range line, ONE casttime|cooldown line, the passive omission,
-//! the aura variant (white description + the SetPlayerBuff-only remaining line, itself gold —
-//! B62), and SetAction's
-//! pure delegation.
+//! The engine spell and aura tooltips: name|rank, one cost|range line, one casttime|cooldown line,
+//! the passive omission, the aura variant (white description, and the gold remaining line on
+//! `SetPlayerBuff` only), and the selectors that delegate to them.
 
 use super::common::script;
 use crate::script::*;
@@ -20,7 +18,7 @@ fn fireball() -> SpellTooltipView {
     }
 }
 
-/// The spellbook hover: name|rank gray, cost|range one line, casttime line, gold description.
+/// The spellbook hover: no rank column, cost|range on one line, cast time, gold description.
 #[test]
 fn spellbook_hover_renders_the_verified_shape() {
     let mut s = script();
@@ -53,7 +51,6 @@ fn spellbook_hover_renders_the_verified_shape() {
     "#,
     )
     .unwrap();
-    // The description wears the byte-verified gold.
     s.resolve();
     let quads = s.extract();
     let gold = quads.iter().any(|q| {
@@ -64,13 +61,8 @@ fn spellbook_hover_renders_the_verified_shape() {
     assert!(s.take_errors().is_empty());
 }
 
-/// **`bookType` decides which book the hover reads** — the fork `SetSpell 0x532d10` makes at
-/// `0x532e1c`/`0x532e2a` (`[4*i + 0xb6f098]` for the pet, `[4*i + 0xb700f0]` otherwise).
-///
-/// The defect (1050): the binding took the argument and dropped it, so a pet-book hover indexed the
-/// PLAYER's slot list — the imp's first spell showed the player's first spell, "Attack" and its
-/// crit line, on the director's screen. Both books are populated here with a *different* spell at
-/// the same slot id, which is the only arrangement that can tell the two apart.
+/// `SetSpell`'s `bookType` picks the book (`0x532d10` forks at `0x532e1c`, `0x532e2a`: the pet's
+/// slots at `0xb6f098`, the player's at `0xb700f0`); both books hold a different spell at slot 1.
 #[test]
 fn a_pet_book_hover_reads_the_pets_book_not_the_players() {
     let mut s = script();
@@ -126,9 +118,8 @@ fn a_pet_book_hover_reads_the_pets_book_not_the_players() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The tracking icon's hover (SetTrackingSpell): a GOLD name over the white (aura-variant)
-/// description — the shape the director's reference A/B pinned (2026-07-20), distinct from
-/// SetPlayerBuff's white name. No cost/casttime lines, no duration-remaining line.
+/// `SetTrackingSpell`, as the reference draws it: a gold name over the white aura description,
+/// with no cost, cast time or remaining line.
 #[test]
 fn tracking_hover_renders_gold_name_over_white_description() {
     let mut s = script();
@@ -178,7 +169,7 @@ fn tracking_hover_renders_gold_name_over_white_description() {
     assert!(s.take_errors().is_empty());
 }
 
-/// A passive spell omits the casttime|cooldown line whole — never a "Passive" text line.
+/// A passive spell omits the casttime|cooldown line whole, with no "Passive" text line.
 #[test]
 fn passive_omits_the_casttime_line() {
     let mut s = script();
@@ -220,8 +211,8 @@ fn passive_omits_the_casttime_line() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The buff hover: the aura variant — WHITE description + the duration-remaining line (only
-/// this entry point), computed off the aura's GetTime expiry.
+/// The buff hover is the aura variant: a white description and, on this entry point only, the
+/// remaining-time line computed off the aura's `GetTime` expiry.
 #[test]
 fn player_buff_hover_is_the_aura_variant() {
     let mut s = script();
@@ -272,7 +263,6 @@ fn player_buff_hover_is_the_aura_variant() {
     "#,
     )
     .unwrap();
-    // The aura description is WHITE (the byte-verified aura/spell difference).
     s.resolve();
     let quads = s.extract();
     let white = quads.iter().any(|q| {
@@ -280,18 +270,14 @@ fn player_buff_hover_is_the_aura_variant() {
             if t.starts_with("Intellect increased") && *c == [1.0, 1.0, 1.0, 1.0])
     });
     assert!(white, "aura description is white, not gold");
-    // …and the NAME is GOLD: the aura builder `0x52f880` writes it through the gold wrapper
-    // `0x530380`, where the spell builder uses the plain `0x530270`. Pinned against the
-    // reference's own buff hover (2026-07-25 report B53), which the white name did not match.
+    // The name is gold: the aura builder `0x52f880` writes it through the gold wrapper
+    // `0x530380`, where the spell builder uses the plain `0x530270`.
     let gold_name = quads.iter().any(|q| {
         matches!(&q.content, QuadContent::Text { text: Some(t), color: Some(c), .. }
             if t == "Arcane Intellect" && (c[1] - 210.0 / 255.0).abs() < 1e-6)
     });
     assert!(gold_name, "aura name is gold, not white");
-    // …and so is the DURATION-REMAINING line — the same `0xffffd200`, not the description's
-    // white. On a 1.12.1 reference shot the "29 minutes remaining" glyphs are exactly
-    // `(255, 210, 0)`, the same pixels as that shot's title row, while its description rows are
-    // `(255, 255, 255)`.
+    // So is the remaining line, the same `0xffffd200`, as in the reference's buff hover.
     let gold_remaining = quads.iter().any(|q| {
         matches!(&q.content, QuadContent::Text { text: Some(t), color: Some(c), .. }
             if t == "<2 mm>" && *c == [1.0, 210.0 / 255.0, 0.0, 1.0])
@@ -300,10 +286,8 @@ fn player_buff_hover_is_the_aura_variant() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The buff builder `0x52f880`'s right column: the buff hover names the DISPEL CLASS where the
-/// spell hover would put a gray "Rank N" — "Magic" on Ice Armor, the half of B53 the gold name
-/// didn't cover — and it is gold, sharing the aura name's wrapper. A `rank` on the same view must
-/// NOT displace it.
+/// The buff builder's (`0x52f880`) right column is the dispel class, gold through the aura name's
+/// wrapper, where the spell hover puts a gray rank; a `rank` on the view must not displace it.
 #[test]
 fn player_buff_hover_names_the_dispel_class_in_gold() {
     let mut s = script();
@@ -312,7 +296,7 @@ fn player_buff_hover_names_the_dispel_class_in_gold() {
         168,
         SpellTooltipView {
             name: "Ice Armor".into(),
-            rank: Some("Rank 1".into()), // the spell variant's column — never the aura's
+            rank: Some("Rank 1".into()), // the spell variant's column, never the aura's
             dispel_type: Some("Magic".into()),
             aura_description: "Encases the caster in a layer of ice.".into(),
             ..Default::default()
@@ -350,9 +334,8 @@ fn player_buff_hover_names_the_dispel_class_in_gold() {
     assert!(s.take_errors().is_empty());
 }
 
-/// `0x52e610`'s equipped-item line and its reagents line — the two lines the 2026-07-25 reports
-/// found missing (B54, B56). Order: cast|cooldown → requires-item → requires-form → reagents →
-/// description, each requirement red while unmet.
+/// `0x52e610`'s line order: cast|cooldown, requires-item, requires-form, reagents, description,
+/// each requirement red while unmet.
 #[test]
 fn requirement_and_reagent_lines_render_in_law_order() {
     let mut s = script();
@@ -401,10 +384,8 @@ fn requirement_and_reagent_lines_render_in_law_order() {
             if t == "Requires Wands" && *c == [1.0, 32.0 / 255.0, 32.0 / 255.0, 1.0])
     });
     assert!(red, "an unmet equipped-item requirement is red");
-    // The reagent's inline `|cffff2020` escape reaches the region VERBATIM: the engine paints
-    // the line's BASE colour white and the app's text layer resolves the escape into colour runs
-    // (`benilla::ui_text::markup`, covered by its own `color_runs_survive_the_wrap`). So what this
-    // layer owns is that the escape is neither stripped nor pre-flattened.
+    // The reagent's `|cffff2020` escape reaches the region verbatim over a white base colour; the
+    // app's text layer (`ui_text::markup`) turns it into colour runs.
     let verbatim = quads.iter().any(|q| {
         matches!(&q.content, QuadContent::Text { text: Some(t), color: Some(c), .. }
             if t == "Reagents: |cffff2020Light Feather|r" && *c == [1.0, 1.0, 1.0, 1.0])
@@ -416,9 +397,9 @@ fn requirement_and_reagent_lines_render_in_law_order() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The target-frame aura hover: SetUnitBuff/SetUnitDebuff render the aura variant for the token's
-/// sign-filtered list — WITHOUT the duration-remaining line (byte-verified: only SetPlayerBuff
-/// appends it, and no other unit carries a duration on the 1.12 wire anyway).
+/// `SetUnitBuff`/`SetUnitDebuff` render the aura variant from the unit's sign-filtered list, with
+/// no remaining line: only `SetPlayerBuff` appends it, and the 1.12 wire carries no other unit's
+/// durations.
 #[test]
 fn unit_buff_and_debuff_hover_render_the_aura_variant_without_remaining() {
     let mut s = script();
@@ -477,20 +458,9 @@ fn unit_buff_and_debuff_hover_render_the_aura_variant_without_remaining() {
     assert!(s.take_errors().is_empty());
 }
 
-/// **`SetPlayerBuff` reads a 1.12 cache position, not an Era ordinal** — the index space the whole
-/// `GetPlayerBuff*` family shares (`script::aura`'s header; pinned by `ref-BuffFrame.lua:105`,
-/// which passes `GetPlayerBuff`'s return straight in).
-///
-/// Every assertion here is a case the previous 1-based, sign-filtered reading got wrong, and got
-/// wrong *silently* — the plate still rendered, just for the wrong aura:
-///
-/// - position 1 is the SECOND aura, not the first again;
-/// - a debuff is reachable at all (the old sign filter defaulted to helpful, so no position ever
-///   resolved to one);
-/// - `-1` clears instead of showing the first buff. `BigWigs/Raids/Naxxramas/Loatheb.lua:260-271`
-///   feeds an unchecked `GetPlayerBuff(i, "HARMFUL")` in and breaks its scan when line 1 goes nil,
-///   so "shows something" there is an addon that never stops scanning;
-/// - a surplus filter argument is ignored (`CT_BuffMod/CT_BuffFrame.lua:151` passes one).
+/// `SetPlayerBuff` takes a 1.12 cache position, the `GetPlayerBuff` family's index space:
+/// `BuffFrame.lua:105` passes that return straight in. A miss, `-1` included, clears the plate,
+/// and a surplus filter argument is ignored.
 #[test]
 fn player_buff_hover_indexes_the_cache_position_not_a_filtered_ordinal() {
     let mut s = script();
@@ -509,7 +479,7 @@ fn player_buff_hover_indexes_the_cache_position_not_a_filtered_ordinal() {
             },
         );
     }
-    // The player's cache: two buffs then a debuff, ONE list, insertion-ordered (decision 0257).
+    // The player's cache: two buffs then a debuff, in one insertion-ordered list.
     s.set_auras(
         "player",
         Some(vec![
@@ -562,8 +532,8 @@ fn player_buff_hover_indexes_the_cache_position_not_a_filtered_ordinal() {
     assert!(s.take_errors().is_empty(), "{:?}", s.take_errors());
 }
 
-/// SetAction delegates by payload kind: a SPELL slot renders the spell view; an empty slot shows
-/// nothing; a miss records the ask.
+/// `SetAction` delegates by payload kind: a spell slot renders the spell view, and a spell the
+/// store lacks shows no plate and records the ask.
 #[test]
 fn action_hover_delegates_by_kind() {
     let mut s = script();
@@ -581,7 +551,7 @@ fn action_hover_delegates_by_kind() {
         25,
         Some(ActionSlot {
             kind: 0x00,
-            action: 5143, // not in the store — the ask channel fires
+            action: 5143, // not in the store: the ask channel fires
             ..Default::default()
         }),
     );
@@ -603,10 +573,8 @@ fn action_hover_delegates_by_kind() {
     assert!(s.take_errors().is_empty());
 }
 
-/// A MACRO slot's hover is the reference's `0x52b040`: ONE white line, the macro's name (the
-/// "normal" colour `0xc0cf60` = 0xffffffff), and a slot whose
-/// macro no longer exists shows no plate at all. The director's report after 1636 landed: a macro
-/// on the bar had no tooltip — the arm was a pre-0983 `_ => Ok(())`.
+/// A macro slot's hover is the reference's `0x52b040`: one line, the macro's name in the normal
+/// colour (`0xc0cf60` holds `0xffffffff`, white); a slot whose macro is gone shows no plate.
 #[test]
 fn action_hover_on_a_macro_slot_shows_its_name_in_white() {
     let mut s = script();
@@ -684,12 +652,8 @@ fn trainer_service(spell_id: u32, name: &str, tooltip: TrainerTooltip) -> Traine
     }
 }
 
-/// `SetTrainerService` is a SELECTOR: it renders no line of its own and routes to whichever shared
-/// builder the app-side law picked. All three arms are pinned here — the item arm, the spell arm
-/// (with `altCaster` suppressing the reagents block), and a header row, which is a no-op.
-///
-/// The index is a VISIBLE row index, so row 1 is the "Arms" header and the services start at 2 —
-/// the same interleave `SetTradeSkillItem` has, and the same way to get it wrong.
+/// `SetTrainerService` renders no line of its own: it routes to the item or spell builder the app
+/// picked (`altCaster` drops the reagents), and its index is a visible row, so row 1 is a header.
 #[test]
 fn set_trainer_service_selects_the_builder_and_never_renders_its_own_line() {
     let mut s = script();
@@ -701,8 +665,8 @@ fn set_trainer_service_selects_the_builder_and_never_renders_its_own_line() {
             quality: 1,
             class: 2,
             subclass: 7,
-            // The type cell's word is app-resolved off ItemSubClass.dbc, never composed in the
-            // renderer — a view that carries none prints no type cell.
+            // The app resolves the type cell's word from ItemSubClass.dbc; a view without one
+            // prints no type cell.
             sub_class_display: Some("Sword".into()),
             ..Default::default()
         },
@@ -759,7 +723,7 @@ fn set_trainer_service_selects_the_builder_and_never_renders_its_own_line() {
     )
     .unwrap();
 
-    // Row 3: the class-trainer service -> the SPELL builder on the TAUGHT spell, reagents shown.
+    // Row 3: the class-trainer service goes to the spell builder on the taught spell.
     s.run(
         r#"
         TT:SetOwner(AB1, "ANCHOR_RIGHT")
@@ -781,7 +745,7 @@ fn set_trainer_service_selects_the_builder_and_never_renders_its_own_line() {
         "the gold description is part of the shared builder's law: {texts:?}"
     );
 
-    // Row 4: the same view, altCaster set -> the reagents block is gone, everything else stays.
+    // Row 4: the same view with altCaster set loses only the reagents block.
     s.run(
         r#"
         TT:SetOwner(AB1, "ANCHOR_RIGHT")
@@ -801,11 +765,8 @@ fn set_trainer_service_selects_the_builder_and_never_renders_its_own_line() {
     assert!(s.take_errors().is_empty());
 }
 
-/// `SetCraftSpell` is `SetTrainerService`'s structural twin: a selector, not the two-line
-/// name/description stub it used to be. Both arms are pinned, and the assertion that matters most
-/// is the negative one — a rod recipe's hover shows the ROD's item tooltip while the same row's
-/// ICON is the spell's (Law D, decision 1107). Icon and tooltip disagreeing on one row is the
-/// verified shape, not a bug to reconcile.
+/// `SetCraftSpell` is a selector like `SetTrainerService`: a rod recipe hovers the rod's item
+/// tooltip while its row's icon is the spell's, which is the reference's shape, not a bug.
 #[test]
 fn set_craft_spell_selects_the_builder_like_the_trainer_hover_does() {
     let mut s = script();
@@ -893,10 +854,8 @@ fn set_craft_spell_selects_the_builder_like_the_trainer_hover_does() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The duration line's **gate**: `0x532b00` skips the duration block on `untilCancelled`
-/// (`532bda: 8b 46 0c` / `532bdf: 75 2d`) — never on "has this aura a duration yet". The three
-/// cases below are the ones that separate the two questions, and the middle two are what the old
-/// `duration > 0 && left > 0` gate got wrong.
+/// `0x532b00` skips the remaining line on `untilCancelled` (`0x532bda`, `0x532bdf`), never on
+/// whether the aura has a duration yet.
 #[test]
 fn the_remaining_line_is_gated_on_until_cancelled_not_on_the_duration() {
     let mut s = script();
@@ -943,8 +902,7 @@ fn the_remaining_line_is_gated_on_until_cancelled_not_on_the_duration() {
         ..Default::default()
     };
 
-    // 1 · Permanent — and carrying a duration anyway, so only the FLAG can be doing the work.
-    // Title + description, nothing else.
+    // 1 · Permanent, with a duration anyway, so only the flag can suppress the line.
     assert_eq!(
         show(AuraState {
             duration: 1800.0,
@@ -956,8 +914,7 @@ fn the_remaining_line_is_gated_on_until_cancelled_not_on_the_duration() {
         "untilCancelled suppresses the line even with a live duration on the record"
     );
 
-    // 2 · Timed, but no duration packet has landed yet — the frame an aura appears. The old gate
-    // blanked this; the reference shows the line, counting from zero.
+    // 2 · Timed, before any duration packet: the reference shows the line, counting from zero.
     assert_eq!(
         show(AuraState {
             duration: 0.0,
@@ -969,8 +926,7 @@ fn the_remaining_line_is_gated_on_until_cancelled_not_on_the_duration() {
         "a timed aura's first frames still carry the line"
     );
 
-    // 3 · Lapsed — the reading the reference's own truncating seconds arm produces, which the old
-    // gate hid entirely.
+    // 3 · Lapsed: the reference's truncating seconds arm reads 0.
     assert_eq!(
         show(AuraState {
             duration: 30.0,
@@ -982,8 +938,7 @@ fn the_remaining_line_is_gated_on_until_cancelled_not_on_the_duration() {
         "a lapsed aura reads 0, it does not lose the line"
     );
 
-    // Control: an ordinary live aura still counts, so none of the above is the line going missing
-    // for an unrelated reason.
+    // Control: an ordinary live aura still counts down.
     assert_eq!(
         show(AuraState {
             duration: 1800.0,
@@ -996,9 +951,9 @@ fn the_remaining_line_is_gated_on_until_cancelled_not_on_the_duration() {
     assert!(s.take_errors().is_empty());
 }
 
-/// `GetRewardSpell()` / `GetQuestLogRewardSpell()` answer `texture, name, isTradeskillSpell` —
-/// three nils when the quest teaches nothing (the reference's own `(nil,nil,nil)` kind) — and
-/// `GameTooltip:SetQuestRewardSpell()` / `SetQuestLogRewardSpell()` render that spell (1944).
+/// `GetRewardSpell()` and `GetQuestLogRewardSpell()` answer `texture, name, isTradeskillSpell`,
+/// three nils when the quest teaches nothing, and `SetQuestRewardSpell()` and
+/// `SetQuestLogRewardSpell()` render that spell.
 #[test]
 fn quest_reward_spell_getters_and_hovers() {
     let mut s = script();
@@ -1066,7 +1021,7 @@ fn quest_reward_spell_getters_and_hovers() {
         }],
         ..Default::default()
     });
-    // The detail hangs on the row now, so both readers go through the selection (2247).
+    // The detail hangs on the row, so both readers go through the selection.
     s.run("SelectQuestLogEntry(1)").unwrap();
     assert_eq!(
         s.eval::<(String, String, Option<i64>)>("return GetQuestLogRewardSpell()")
diff --git a/crates/benilla-ui/src/script/tests/tooltip_unit.rs b/crates/benilla-ui/src/script/tests/tooltip_unit.rs
index b43ed685..f15b9997 100644
--- a/crates/benilla-ui/src/script/tests/tooltip_unit.rs
+++ b/crates/benilla-ui/src/script/tests/tooltip_unit.rs
@@ -1,20 +1,11 @@
-//! The engine unit tooltip builder (decision 0274 P3, law per 0276): the level-line composition
-//! (four `TOOLTIP_UNIT_LEVEL*` keys, the `ELITE`/`BOSS` rank table, "??", `CORPSE`, "Race Class"
-//! over `PLAYER` — all seeded here as marked stand-ins, see [`seed_level_strings`]), the flag lines
-//! (PvP white / Skinnable red / Civilian green), the world-mouseover drive (default anchor +
-//! `UPDATE_MOUSEOVER_UNIT` recolor + the fade arm on loss), and the health-bar watcher.
+//! The engine unit tooltip builder: the level line, the flag lines, the world-mouseover drive and
+//! the health-bar watcher.
 
 use super::common::script;
 use crate::script::*;
 
-/// A stand-in string table for the level line — the four `TOOLTIP_UNIT_LEVEL*` templates and the
-/// three word slots that fill them, **deliberately not the shipped wording**. What these tests
-/// establish is *which key* each slot combination reaches and what fills it, never what the
-/// sentence says (decision 2045, "assert the identifier, not the sentence"), and here that is not
-/// a formality: `TOOLTIP_UNIT_LEVEL_CLASS`'s enUS "Level %s %s" is word-for-word
-/// `FRIENDS_LEVEL_TEMPLATE`, `UNIT_TYPE_LEVEL_TEMPLATE` and `CHARACTER_SELECT_INFO`, and the bare
-/// template's "Level %s" is also `ITEM_LEVEL`, `LEVEL_GAINED` and `UNIT_LEVEL_TEMPLATE`. An
-/// assertion on the English would pass on all seven.
+/// Stand-in level-line strings, deliberately not the shipped wording: the enUS templates repeat
+/// other globals word for word, so only a marked stand-in shows which key was reached.
 fn seed_level_strings(s: &mut UiScript) {
     s.run(
         r#"
@@ -46,7 +37,7 @@ fn wolf() -> UnitState {
     }
 }
 
-/// The creature law: gold name, subtitle, the CLASS_TYPE level line, red Skinnable.
+/// A creature: gold name, subtitle, the CLASS_TYPE level line, red Skinnable.
 #[test]
 fn creature_line_law() {
     let mut s = script();
@@ -82,10 +73,8 @@ fn creature_line_law() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The snapshot the app pushes for a creature the client has only just seen: the DESCRIPTOR's
-/// fields are in (level, reaction, the skinnable flag) and everything the creature record carries
-/// — name, subtitle, type word, rank, civilian/leader — is still absent, because they all arrive
-/// together in the one `SMSG_CREATURE_QUERY_RESPONSE` that fills `CGUnit+0xb30`.
+/// A creature just seen: its descriptor fields are in, but the record fields (name, subtitle, type,
+/// rank, civilian) wait for the `SMSG_CREATURE_QUERY_RESPONSE` that fills `CGUnit+0xb30`.
 fn unqueried_wolf() -> UnitState {
     UnitState {
         exists: true,
@@ -101,22 +90,9 @@ fn unqueried_wolf() -> UnitState {
     }
 }
 
-/// **A name still in flight titles the plate `UNKNOWNOBJECT` — never an empty line** (decision
-/// 2040, closing 2002's residue).
-///
-/// The builder's name read is `CGUnit_C::GetUnitName 0x609210` (`0x52a187`), the same resolver
-/// `UnitName 0x517020` delegates to, and every one of its misses — a null `CGUnit+0xb30`
-/// (`0x609353 je 0x609324`) among them — ends at the same `FrameScript_GetText("UNKNOWNOBJECT")`
-/// tail. So the verb and the plate answer the same string for the same instant, and because the
-/// string is read out of the VM's `_G` it translates with `GlobalStrings.lua`.
-///
-/// The builder has NO counterpart to `UnitName`'s two nils: the `"player"` fast path is the
-/// *binding's* (`0x517083`, before any resolve), so a player whose name has not arrived titles
-/// `UNKNOWNOBJECT` too; and a token resolving to nothing never reaches a builder at all — the
-/// entry gate hands back no object, `SetUnit` answers nil and no plate is drawn.
-///
-/// Failure looks like the empty first line the residue named: `TextLeft1` reads `""`, the plate
-/// measures to a blank row, and the level line reads as the tooltip's title.
+/// `CGUnit_C::GetUnitName 0x609210` (`0x52a187`) reads the name, as for `UnitName 0x517020`, and
+/// every miss, a null `CGUnit+0xb30` among them (`0x609353 je 0x609324`), ends at
+/// `FrameScript_GetText("UNKNOWNOBJECT")`. The `"player"` fast path is the binding's (`0x517083`).
 #[test]
 fn a_pending_name_titles_unknownobject_and_the_answer_replaces_it() {
     let mut s = script();
@@ -145,9 +121,7 @@ fn a_pending_name_titles_unknownobject_and_the_answer_replaces_it() {
     )
     .unwrap();
 
-    // The query answers: the very next render replaces the placeholder with the real name and
-    // fills the record's lines. (Live, the hover feed re-drives this without the mouse moving —
-    // its rebuild key is the whole line-affecting snapshot, `ui_tooltip::lines_view`.)
+    // The query answers: the next render replaces the placeholder and fills the record's lines.
     let mut answered = unqueried_wolf();
     answered.name = Some("Timber Wolf".into());
     answered.subtitle = Some("Alpha".into());
@@ -165,8 +139,7 @@ fn a_pending_name_titles_unknownobject_and_the_answer_replaces_it() {
     )
     .unwrap();
 
-    // An EMPTY (or absent) global is the same miss as no global — `0x609324`'s own check, which
-    // falls to the binary's literal `0x860fa4`.
+    // An empty or absent global falls to the binary's own literal `0x860fa4` (`0x609324`).
     s.set_unit("target", Some(unqueried_wolf()));
     s.run(
         r#"
@@ -177,8 +150,7 @@ fn a_pending_name_titles_unknownobject_and_the_answer_replaces_it() {
     )
     .unwrap();
 
-    // The `"player"` fast path is the BINDING's, not the builder's: a player whose name-cache row
-    // has not answered titles the same placeholder, where `UnitName("player")` would push nil.
+    // A player whose name has not arrived titles the placeholder; `UnitName("player")` pushes nil.
     s.set_unit(
         "player",
         Some(UnitState {
@@ -203,18 +175,15 @@ fn a_pending_name_titles_unknownobject_and_the_answer_replaces_it() {
     )
     .unwrap();
 
-    // The GUID-0 counterpart: a recognised token naming nothing resolves to no object, so no
-    // builder runs — nil, and no plate. (There is no third answer; the builder never sees it.)
+    // A recognised token naming nothing resolves to no object, so no builder runs.
     s.run(r#"assert(TT:SetUnit("party4") == nil, "an absent unit draws no plate at all")"#)
         .unwrap();
     assert!(s.take_errors().is_empty());
 }
 
-/// The faction-name line sits between the level line and "PvP" (the builder-tail block of
-/// `0x529fe0` — the director's Marshal McBride reference: Level, Stormwind, PvP); the
-/// CIVILIAN line is the dishonorable-kill warning, whole gate (`0x612550`): PvP bit + civilian
-/// flag + HOSTILE + GREY/trivial — a friendly (or non-grey) civilian never shows it; LEADER
-/// (white) needs only the PvP bit + the flag (`0x6125c0`).
+/// The faction line sits between the level line and "PvP" (`0x529fe0`). Civilian needs the PvP
+/// bit, the flag, hostility and a grey level (`0x612550`); Leader only the PvP bit and the flag
+/// (`0x6125c0`).
 #[test]
 fn faction_line_and_civilian_gate() {
     let mut s = script();
@@ -224,7 +193,7 @@ fn faction_line_and_civilian_gate() {
         level: 30,
         ..Default::default()
     });
-    // The reference shot's shape: a FRIENDLY civilian guard — faction line, PvP, NO Civilian.
+    // A friendly civilian guard: faction line and PvP, no Civilian.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -252,7 +221,7 @@ fn faction_line_and_civilian_gate() {
     "#,
     )
     .unwrap();
-    // The warning case: HOSTILE + grey (level 20 vs player 30 → gap 10 > band 8) + PvP-flagged.
+    // Hostile, PvP-flagged and grey (a gap of 10 is past the band of 8): the warning shows.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -278,7 +247,7 @@ fn faction_line_and_civilian_gate() {
     "#,
     )
     .unwrap();
-    // Same unit but NOT grey (level 25, gap 5 ≤ band 8): the warning drops.
+    // Not grey (a gap of 5 is inside the band of 8): no warning.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -380,7 +349,7 @@ fn level_line_variants() {
     "#,
     )
     .unwrap();
-    // The "??" gate, byte-pinned: HOSTILE (reaction ≤ 2) + 10 levels up reads "??"…
+    // A hostile unit (reaction 2 or less) 10 levels up reads "??".
     let ten_up = |reaction: u8, is_player: bool| UnitState {
         exists: true,
         name: Some("Elder".into()),
@@ -400,7 +369,7 @@ fn level_line_variants() {
     "#,
     )
     .unwrap();
-    // …but UNFRIENDLY (reaction 3) does not — the internal bound is hated/hostile only…
+    // An unfriendly one (reaction 3) does not.
     s.set_unit("target", Some(ten_up(3, false)));
     s.run(
         r#"
@@ -409,7 +378,7 @@ fn level_line_variants() {
     "#,
     )
     .unwrap();
-    // …and PLAYERS never read "??" regardless of reaction/delta.
+    // Players never read "??".
     s.set_unit("target", Some(ten_up(2, true)));
     s.run(
         r#"
@@ -421,9 +390,7 @@ fn level_line_variants() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The world-mouseover drive: `world_tooltip_unit` fires the default-anchor script, renders,
-/// fires `UPDATE_MOUSEOVER_UNIT` (the Lua recolor), and the health bar tracks later pushes;
-/// hover loss arms the fade (alpha ramps, then hides).
+/// `world_tooltip_unit` fires the default anchor, renders, then fires `UPDATE_MOUSEOVER_UNIT`.
 #[test]
 fn world_hover_drive_and_health_watcher() {
     let mut s = script();
@@ -466,8 +433,7 @@ fn world_hover_drive_and_health_watcher() {
     "#,
     )
     .unwrap();
-    // The handler's seating resolved: bottom-right of the 800×600 screen, −13 in, 70 up.
-    // (Answer the line measures first — the auto-size needs them before the plate has a rect.)
+    // The auto-size needs the line measures before the plate has a rect.
     let answers: Vec<(u32, f32, f32, u64)> = s
         .fontstrings_needing_measure()
         .iter()
@@ -480,7 +446,7 @@ fn world_hover_drive_and_health_watcher() {
                   "plate at the default corner, got " .. tostring(GameTooltip:GetRight()) .. "," .. tostring(GameTooltip:GetBottom()))"#,
     )
     .unwrap();
-    // A health push for the LIVE token re-drives the bar without a rebuild.
+    // A health push for the live token re-drives the bar without a rebuild.
     let mut hurt = wolf();
     hurt.health = 12;
     s.set_unit("mouseover", Some(hurt));
@@ -488,7 +454,6 @@ fn world_hover_drive_and_health_watcher() {
         r#"assert(GameTooltipStatusBar:GetValue() == 12, "the health watcher tracked the push")"#,
     )
     .unwrap();
-    // Hover loss: the fade arms; past the ramp the tooltip hides.
     s.world_tooltip_fade();
     s.tick(0.6);
     s.run(r#"assert(not GameTooltip:IsShown(), "faded out after the ramp")"#)
@@ -496,9 +461,8 @@ fn world_hover_drive_and_health_watcher() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The minimap BLIP tooltip (`minimap_tooltip`): refuses without a Minimap widget; with one, one
-/// white line seated against the widget (the INTERIM ANCHOR_LEFT law), world-owned so the shared
-/// fade arm hides it on hover loss.
+/// The minimap blip tooltip (`minimap_tooltip`): refused without `UIParent`, otherwise one line
+/// seated above the cursor, world-owned so the shared fade hides it on hover loss.
 #[test]
 fn minimap_blip_tooltip_shows_and_fades() {
     let mut s = script();
@@ -524,8 +488,7 @@ fn minimap_blip_tooltip_shows_and_fades() {
     "#,
     )
     .unwrap();
-    // Seated 5 px from the 800-wide screen's right edge: the clamp (the client's G bit4)
-    // slides the plate back inside instead of letting it clip (director-caught).
+    // Seated 5 px from the right edge, the clamp (the client's G bit4) slides the plate inside.
     let answers: Vec<(u32, f32, f32, u64)> = s
         .fontstrings_needing_measure()
         .iter()
@@ -537,11 +500,10 @@ fn minimap_blip_tooltip_shows_and_fades() {
         r#"assert(GameTooltip:GetRight() <= 800, "clamped inside the screen, got " .. tostring(GameTooltip:GetRight()))"#,
     )
     .unwrap();
-    // Follow: a move re-seats without rebuilding the line.
     s.world_tooltip_move(400.0, 300.0);
     s.run(r#"assert(GameTooltipTextLeft1:GetText() == "Stormwind", "content survives a move")"#)
         .unwrap();
-    // Hover loss rides the shared world fade: armed, then hidden past the ramp.
+    // Hover loss rides the shared world fade.
     s.world_tooltip_fade();
     s.tick(0.6);
     s.run(r#"assert(not GameTooltip:IsShown(), "faded out after the ramp")"#)
diff --git a/crates/benilla-ui/src/script/tests/toplevel.rs b/crates/benilla-ui/src/script/tests/toplevel.rs
index 925f623f..958ad2b6 100644
--- a/crates/benilla-ui/src/script/tests/toplevel.rs
+++ b/crates/benilla-ui/src/script/tests/toplevel.rs
@@ -1,16 +1,10 @@
-//! The `toplevel` flag and the raise law — `SetToplevel`/`IsToplevel`, `Raise`/`Lower`, and the
-//! raise itself with its real trigger (Show) and its real gate (occlusion). The mechanism, the byte
-//! addresses and the clause-by-clause mapping onto our order model are in `script::object::toplevel`.
-//!
-//! Every test drives the PRODUCTION path — the Lua bindings, the loader, and the real
-//! `mouse_button`/`mouse_move` entry points — and asserts on the two things that are actually
-//! observable: `GetFrameLevel()` (the arithmetic) and the extracted painter order (the pixels).
+//! The `toplevel` flag and the raise: `SetToplevel`/`IsToplevel`, `Raise`/`Lower`, and the raise
+//! on show, press and drag, gated on occlusion. Tests assert `GetFrameLevel()` and the paint order.
 
 use super::common::script;
 use crate::script::{QuadContent, UiScript};
 
-/// The order textures actually paint in, by their texture path — the render list `extract` returns
-/// IS the draw order (`order::traversal`'s ZKey sort).
+/// Texture paths in paint order: the list `extract` returns is the draw order.
 fn painted(s: &mut UiScript) -> Vec<String> {
     s.resolve();
     s.extract()
@@ -27,14 +21,8 @@ fn level(s: &mut UiScript, frame: &str) -> i64 {
         .unwrap()
 }
 
-/// Two overlapping MEDIUM frames: `Board` — already on screen and sitting at frame level **5** —
-/// and `Dialog`, born at level 0 and hidden.
-///
-/// The level split is the point. A frame's link stamp already lifts it within its bucket when it is
-/// shown (`resequence_to_tail`, decision 0557), so a same-level sibling would prove nothing about
-/// the raise; **level outranks the link stamp** in the draw key, so nothing but a real level bump
-/// can get `Dialog` over `Board`. This is the shape of the complaint the law answers: a dialog
-/// opening behind a window that happens to sit higher in its stratum.
+/// Two overlapping MEDIUM frames: `Board`, shown at level 5, and `Dialog`, hidden at level 0. The
+/// level outranks the link stamp in the draw key, so only a real level bump puts `Dialog` on top.
 fn board_and_dialog() -> UiScript {
     let mut s = script();
     s.set_screen_size(800.0, 600.0);
@@ -58,11 +46,9 @@ fn board_and_dialog() -> UiScript {
     s
 }
 
-// ── The flag ────────────────────────────────────────────────────────────────────────────────────
+// ── The flag ──
 
-/// `SetToplevel`/`IsToplevel` round-trip, including the reference's **default-true** optional
-/// argument (`0x775440` marshals an optional boolean defaulting to true, unlike `SetMovable`).
-/// Nothing is born toplevel.
+/// `SetToplevel`'s optional argument defaults to true (`0x775440`), unlike `SetMovable`'s.
 #[test]
 fn the_flag_round_trips_and_defaults_off() {
     let s = script();
@@ -75,27 +61,19 @@ fn the_flag_round_trips_and_defaults_off() {
     assert!(s.eval::<bool>("return F:IsToplevel()").unwrap());
     s.run("F:SetToplevel(false)").unwrap();
     assert!(!s.eval::<bool>("return F:IsToplevel()").unwrap());
-    // The omitted argument is TRUE, not false — the reference's `SetToplevel()` turns the bit ON.
     s.run("F:SetToplevel()").unwrap();
     assert!(
         s.eval::<bool>("return F:IsToplevel()").unwrap(),
         "SetToplevel() with no argument sets the bit"
     );
-    // Lua truthiness, like every other flag setter here: the corpus writes SetToplevel(1).
+    // Lua truthiness: addons write `SetToplevel(1)`.
     s.run("F:SetToplevel(nil); F:SetToplevel(1)").unwrap();
     assert!(s.eval::<bool>("return F:IsToplevel()").unwrap());
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// `toplevel="true"` in XML lands on the real method — it was a warn-once gap in the loader until
-/// this law existed, which left every window authored toplevel (thirteen of our own frames, 82
-/// corpus addons) unable to come to the front while `SetToplevel` did not exist at all.
-///
-/// `enableKeyboard` used to be warned here on the same principle — implementing one clause is not
-/// a licence to go quiet about the other. It now lands on a real `EnableKeyboard`, so the warning
-/// is gone and this asserts the flag instead. Key *delivery* reads the same flag
-/// (`script::keyboard`'s walk, 1319); the flag and a handler stay separable in the reference too
-/// (`0x76af00`), which is why this asserts the flag alone.
+/// The XML `toplevel` and `enableKeyboard` attributes set the flags their methods read; in the
+/// reference the keyboard flag is separate from any handler (`0x76af00`).
 #[test]
 fn the_xml_toplevel_and_enable_keyboard_attributes_both_reach_their_methods() {
     let s = script();
@@ -126,8 +104,7 @@ fn the_xml_toplevel_and_enable_keyboard_attributes_both_reach_their_methods() {
         s.eval::<bool>("return XmlTop:IsKeyboardEnabled()").unwrap(),
         "the XML attribute must reach the flag"
     );
-    // Default false, and the setter round-trips both ways — a frame that never asked is not in the
-    // bucket (`0x76af00` is reached from the attribute or an explicit call, never a ctor).
+    // Off by default: `0x76af00` runs from the attribute or a call, never a constructor.
     s.run("Plain = CreateFrame('Frame', 'PlainKbd')").unwrap();
     assert!(!s.eval::<bool>("return Plain:IsKeyboardEnabled()").unwrap());
     s.run("Plain:EnableKeyboard(true)").unwrap();
@@ -136,10 +113,9 @@ fn the_xml_toplevel_and_enable_keyboard_attributes_both_reach_their_methods() {
     assert!(!s.eval::<bool>("return Plain:IsKeyboardEnabled()").unwrap());
 }
 
-// ── The raise on Show ───────────────────────────────────────────────────────────────────────────
+// ── The raise on Show ──
 
-/// The control, and the behaviour before this landed: a **non-toplevel** frame is shown and moves
-/// nowhere. `Dialog` paints under `Board` because its level is lower, exactly as the draw key says.
+/// The control: a frame that is not toplevel keeps its level when shown, and paints under `Board`.
 #[test]
 fn a_non_toplevel_frame_does_not_move_when_shown() {
     let mut s = board_and_dialog();
@@ -153,14 +129,8 @@ fn a_non_toplevel_frame_does_not_move_when_shown() {
     );
 }
 
-/// The headline: the same frame, marked `toplevel`, comes to the front on **Show** — the trigger
-/// the reference raises on (`0x76ae10` @`0x76aee0`), not on a click.
-///
-/// The arithmetic is pinned here because it is the whole mapping onto our order model. Visible
-/// MEDIUM levels are `{0 (Dialog), 5 (Board)}`; level compaction (`0x764eb0`) renumbers those
-/// occupied levels contiguously into `[0, 2)` — Board 5 → 1 — and the raise then writes
-/// `level := bucket->count` = **2**. Not a live max-scan (`5 + 1`), not a re-stamp: one above the
-/// top *occupied* level, counted after the compaction.
+/// A toplevel frame raises on show (`0x76ae10` at `0x76aee0`): compaction (`0x764eb0`) renumbers
+/// the occupied levels `{0, 5}` to `[0, 2)`, then the raise writes `level := bucket->count`, 2.
 #[test]
 fn a_raise_is_top_occupied_level_plus_one_after_compaction() {
     let mut s = board_and_dialog();
@@ -184,15 +154,9 @@ fn a_raise_is_top_occupied_level_plus_one_after_compaction() {
     );
 }
 
-/// The trigger is the **`effectiveVisible` false→true transition**, not the `Show()` call: a frame
-/// whose own `shown` bit is already set raises when an ancestor's Show finally makes it visible, and
-/// a `Show()` that changes no effective visibility raises nothing.
-///
-/// The setup order is load-bearing and is worth reading as the law's own proof. `Holder` is hidden
-/// *before* `Dialog:Show()`, so that Show is not a transition — leave it visible and `Dialog` raises
-/// there instead, ends up above everything, and the transition under test then correctly declines
-/// because nothing is left to raise over. (That mis-ordering is what the first draft of this test
-/// did; the gate was right and the fixture was wrong.)
+/// The trigger is the effective-visibility transition, not the `Show` call. `Holder` is hidden
+/// before `Dialog:Show()` so that call is no transition; otherwise `Dialog` raises there and has
+/// nothing left to raise over.
 #[test]
 fn the_trigger_is_the_effective_visibility_transition_not_the_show_call() {
     let mut s = board_and_dialog();
@@ -217,8 +181,8 @@ fn the_trigger_is_the_effective_visibility_transition_not_the_show_call() {
     assert_eq!(level(&mut s, "Board"), 5, "and compacts nothing");
 
     s.run("Holder:Show()").unwrap();
-    // Occupied visible MEDIUM levels at the raise: Holder 0, Dialog 1, Board 5 → compaction
-    // renumbers to {0, 1, 2} (Board → 2), count 3, and the raise writes Dialog := 3.
+    // Levels at the raise are Holder 0, Dialog 1, Board 5; compaction makes Board 2, count 3, and
+    // the raise writes Dialog := 3.
     assert_eq!(
         level(&mut s, "Dialog"),
         3,
@@ -227,11 +191,9 @@ fn the_trigger_is_the_effective_visibility_transition_not_the_show_call() {
     assert_eq!(level(&mut s, "Board"), 2, "the compaction ran with it");
 }
 
-// ── The gate ────────────────────────────────────────────────────────────────────────────────────
+// ── The gate ──
 
-/// **Occlusion-gated**: a toplevel frame that overlaps nothing changes nothing at all. The gate sits
-/// *before* the compaction in `0x7650f0`, so a declined raise leaves the whole stratum's levels
-/// untouched too — `Board` keeps its authored 5.
+/// The occlusion gate runs before the compaction in `0x7650f0`, so a declined raise moves no level.
 #[test]
 fn a_raise_on_a_frame_that_overlaps_nothing_is_a_total_no_op() {
     let mut s = board_and_dialog();
@@ -253,9 +215,7 @@ fn a_raise_on_a_frame_that_overlaps_nothing_is_a_total_no_op() {
     );
 }
 
-/// The scan runs from the frame's **own level upward** (`for lvl = T->+0xc4; lvl < bucket->count`).
-/// A toplevel frame whose only overlap is with something *below* it is already in front of it, so
-/// there is nothing to raise over.
+/// The occlusion scan starts at the frame's own level (`for lvl = T->+0xc4; lvl < bucket->count`).
 #[test]
 fn the_scan_ignores_frames_below_the_raised_frames_own_level() {
     let mut s = board_and_dialog();
@@ -276,9 +236,7 @@ fn the_scan_ignores_frames_below_the_raised_frames_own_level() {
     assert_eq!(level(&mut s, "Board"), 3);
 }
 
-/// A window overlaps its own children by construction, so the scan excludes the raised frame's
-/// subtree (`0x767010`). Without that clause every toplevel frame with content in it
-/// would raise on every trigger.
+/// The scan excludes the raised frame's own subtree (`0x767010`).
 #[test]
 fn the_scan_excludes_the_raised_frames_own_subtree() {
     let mut s = board_and_dialog();
@@ -299,10 +257,7 @@ fn the_scan_excludes_the_raised_frames_own_subtree() {
     );
 }
 
-/// A raise **never changes the stratum** — `0x7650f0` never writes `+0xc0`. A LOW toplevel frame
-/// raises over its LOW neighbours and stays under every MEDIUM frame, however many times it is
-/// raised. (This is the mechanism that could not have fixed the party-frame-through-loot-window
-/// bug — refuted.)
+/// `0x7650f0` never writes the stratum (`+0xc0`), so a LOW toplevel frame raises within LOW only.
 #[test]
 fn a_raise_can_never_lift_a_frame_out_of_its_stratum() {
     let mut s = script();
@@ -354,16 +309,11 @@ fn a_raise_can_never_lift_a_frame_out_of_its_stratum() {
     );
 }
 
-// ── Propagation and compaction ──────────────────────────────────────────────────────────────────
+// ── Propagation and compaction ──
 
-/// `propagate = 1` shifts **same-strata** children by the same delta (`0x76a4f0` @`0x76a58a`), so
-/// the raised subtree keeps its internal order; cross-strata children are untouched
-/// (`0x76a582: cmp …; jne`).
-///
-/// The arithmetic in full. Visible MEDIUM levels before the raise are `{0 Dialog, 1 Kid, 2 Grandkid,
-/// 5 Board}`; compaction maps them to `{0, 1, 2, 3}` (Board 5 → 3) and reports `count = 4`. The
-/// raise writes `Dialog := 4`, i.e. `delta = +4`, and pushes that same +4 into Kid (1 → 5) and
-/// Grandkid (2 → 6) — gaps and order preserved. `Cross`, moved to the DIALOG stratum, keeps its 1.
+/// The raise's `propagate = 1` shifts same-strata children by its delta (`0x76a4f0` at
+/// `0x76a58a`) and skips the others (`0x76a582`). Levels `{0, 1, 2, 5}` compact to `{0, 1, 2, 3}`,
+/// so Dialog goes to 4 and Kid and Grandkid move by the same +4.
 #[test]
 fn the_raised_subtree_shifts_by_one_delta_and_keeps_its_internal_order() {
     let mut s = board_and_dialog();
@@ -394,12 +344,8 @@ fn the_raised_subtree_shifts_by_one_delta_and_keeps_its_internal_order() {
     );
 }
 
-/// Compaction is what keeps `level := top + 1` from ratcheting. Two overlapping toplevel windows
-/// traded back and forth twenty times settle inside a two-level band instead of climbing one step
-/// per show — and the frame shown last is on top every single time.
-///
-/// Without level compaction (`0x764eb0`) this test ends at level 20, and a long session ends at
-/// `u16::MAX`.
+/// Compaction (`0x764eb0`) keeps `level := top + 1` from climbing: twenty alternating raises stay
+/// within a two-level band.
 #[test]
 fn compaction_bounds_the_raise_across_repeated_shows() {
     let mut s = script();
@@ -436,11 +382,10 @@ fn compaction_bounds_the_raise_across_repeated_shows() {
     );
 }
 
-// ── The Lua verbs ───────────────────────────────────────────────────────────────────────────────
+// ── The Lua verbs ──
 
-/// `Frame:Raise()` — the explicit script call (`0x775a50` → `0x76a5b0` → `0x7650f0(force = 1)`).
-/// Called on a **non-toplevel** frame it acts on the nearest toplevel ancestor, and on nothing at
-/// all when there is none: the gate lives in the worker, so no call site has to check.
+/// `Raise` (`0x775a50`, then `0x76a5b0`, then `0x7650f0` with force 1) acts on the nearest toplevel
+/// self or ancestor, and on nothing when there is none.
 #[test]
 fn lua_raise_acts_on_the_nearest_toplevel_ancestor_and_is_silent_without_one() {
     let mut s = board_and_dialog();
@@ -465,7 +410,7 @@ fn lua_raise_acts_on_the_nearest_toplevel_ancestor_and_is_silent_without_one() {
         "raising a child raised the toplevel window it lives in"
     );
 
-    // A frame with no toplevel in its chain: a total no-op, and not an error.
+    // No toplevel in the chain: a no-op, not an error.
     let board_before = level(&mut s, "Board");
     let loose_before = level(&mut s, "Loose");
     s.run("Loose:Raise()").unwrap();
@@ -474,9 +419,7 @@ fn lua_raise_acts_on_the_nearest_toplevel_ancestor_and_is_silent_without_one() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// `Frame:Lower()` is a **verified no-op stub** in build 5875 (`0x7652a0` = `xor eax,eax; ret 4`,
-/// its frame argument never read). It exists so a caller gets the reference's silence rather than a
-/// nil-call error — and it must not become "the opposite of Raise".
+/// The reference's `Lower` does nothing (`0x7652a0`: `xor eax,eax; ret 4`), and neither does ours.
 #[test]
 fn lua_lower_exists_and_does_nothing() {
     let mut s = board_and_dialog();
@@ -487,9 +430,7 @@ fn lua_lower_exists_and_does_nothing() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The drag-start trigger (`0x7652b0` @`0x7652d7`): grabbing a movable toplevel window brings it
-/// forward before the drag begins. This was the deferral `object::movable`'s doc carried ("benilla
-/// has no raise law yet") and it is closed.
+/// `StartMoving` raises a toplevel window before the drag begins (`0x7652b0` at `0x7652d7`).
 #[test]
 fn starting_a_move_raises_the_dragged_window() {
     let mut s = board_and_dialog();
@@ -516,7 +457,7 @@ fn starting_a_move_raises_the_dragged_window() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-// ── The mouse-DOWN trigger ──────────────────────────────────────────────────────────────────────
+// ── The mouse-down trigger ──
 
 /// The centre of `name`'s resolved rect, in the coordinate space [`UiScript::mouse_button`] takes.
 fn centre(s: &UiScript, name: &str) -> (f32, f32) {
@@ -529,11 +470,7 @@ fn centre(s: &UiScript, name: &str) -> (f32, f32) {
     (x as f32, y as f32)
 }
 
-/// **A press brings the window forward** — the trigger at `0x766392` in the mouse-down handler
-/// `0x7662c0`, the last of the six census sites to be wired (`0x7662c0`).
-///
-/// Without it `toplevel` gives only half the behaviour a player reads as "windows": a window you
-/// *open* comes to the front, and a window you *click* stays buried under whatever is on top of it.
+/// A press raises the window: the trigger at `0x766392` in the mouse-down handler `0x7662c0`.
 #[test]
 fn pressing_a_toplevel_window_brings_it_to_the_front() {
     let mut s = board_and_dialog();
@@ -550,7 +487,7 @@ fn pressing_a_toplevel_window_brings_it_to_the_front() {
     s.resolve();
     assert!(level(&mut s, "Dialog") < level(&mut s, "Board"));
 
-    // A point inside Dialog and clear of Board, so the hit is unambiguous.
+    // Board overlaps Dialog's centre but takes no mouse, so the hit is Dialog.
     let (x, y) = centre(&s, "Dialog");
     assert_eq!(s.hit_test_name(x, y).as_deref(), Some("Dialog"));
     s.mouse_button(x, y, "LeftButton", true);
@@ -562,10 +499,7 @@ fn pressing_a_toplevel_window_brings_it_to_the_front() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The trigger is **UNGUARDED** — there is no toplevel test at the call site. The worker resolves
-/// the nearest toplevel *self-or-ancestor*, so pressing a plain child raises the window that owns
-/// it. This is the clause that makes clicking a window's button, tab or background art work at all;
-/// with a guard out here, only a press landing on the window frame itself would raise.
+/// The press trigger has no toplevel test; the worker raises the nearest toplevel self or ancestor.
 #[test]
 fn pressing_a_child_of_a_toplevel_window_raises_the_window() {
     let mut s = board_and_dialog();
@@ -596,9 +530,7 @@ fn pressing_a_child_of_a_toplevel_window_raises_the_window() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **The RELEASE never raises.** The sibling category-`0xe` handler `0x766420` has no `Raise` call
-/// anywhere in it; only the down edge does. A raise on the release would be invisible in the
-/// ordinary case and wrong in the one that matters — a press that started a drag elsewhere.
+/// The mouse-up handler (`0x766420`, category `0xe`) has no raise; only the down edge raises.
 #[test]
 fn releasing_over_a_toplevel_window_does_not_raise_it() {
     let mut s = board_and_dialog();
@@ -615,7 +547,7 @@ fn releasing_over_a_toplevel_window_does_not_raise_it() {
     s.resolve();
     let (x, y) = centre(&s, "Dialog");
     let before = level(&mut s, "Dialog");
-    // A release with no press before it: the down edge never ran, so nothing may move.
+    // A release with no press before it.
     s.mouse_button(x, y, "LeftButton", false);
     assert_eq!(
         level(&mut s, "Dialog"),
@@ -625,11 +557,8 @@ fn releasing_over_a_toplevel_window_does_not_raise_it() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **Capture else hover.** The handler resolves `root+0x80` (the existing capture) *before* falling
-/// back to `root+0x7c` (the frame under the cursor), so a second button pressed while the first is
-/// still held raises the frame being HELD, not whatever the pointer has wandered onto. The capture
-/// clears only when the last button comes up (`0x7664bb`, gated on the post-event mask), so the
-/// next press after that resolves to the hover again.
+/// The press raises the capture (`root+0x80`) before the hover (`root+0x7c`), so a second button
+/// raises the held frame; the capture clears when the last button comes up (`0x7664bb`).
 #[test]
 fn a_chorded_press_raises_the_held_frame_not_the_one_under_the_cursor() {
     let mut s = board_and_dialog();
@@ -659,14 +588,13 @@ fn a_chorded_press_raises_the_held_frame_not_the_one_under_the_cursor() {
     .unwrap();
     s.resolve();
 
-    // Hold the left button on Dialog…
+    // Hold the left button on Dialog.
     let (dx, dy) = centre(&s, "Dialog");
     s.mouse_button(dx, dy, "LeftButton", true);
     let dialog_held = level(&mut s, "Dialog");
     let other_before = level(&mut s, "Other");
 
-    // …then press the right button away over Other. The capture is still Dialog's, so Other is not
-    // the raise target even though it is what the cursor is on.
+    // Then press the right button over Other: the capture is still Dialog's.
     let (ox, oy) = centre(&s, "Other");
     assert_eq!(s.hit_test_name(ox, oy).as_deref(), Some("Other"));
     s.mouse_button(ox, oy, "RightButton", true);
@@ -677,7 +605,7 @@ fn a_chorded_press_raises_the_held_frame_not_the_one_under_the_cursor() {
     );
     assert_eq!(level(&mut s, "Dialog"), dialog_held);
 
-    // Both buttons up — only now does the capture clear.
+    // Both buttons up: only now does the capture clear.
     s.mouse_button(ox, oy, "LeftButton", false);
     s.mouse_button(ox, oy, "RightButton", false);
     let other_now = level(&mut s, "Other");
@@ -690,30 +618,9 @@ fn a_chorded_press_raises_the_held_frame_not_the_one_under_the_cursor() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **A window raised while part of it is hidden must keep its own children level with each other**
-/// — the compaction may not split a sibling pair (director's report 2026-09-08, decision 2104).
-///
-/// This is Gatherer 1.0.0's Report window, built the way its XML builds it and reduced to the four
-/// frames that matter:
-///
-/// - `Win` — `toplevel`, `frameStrata="DIALOG"`, born hidden, at level 1 (what `SetParent` gives a
-///   child of a level-0 `UIParent`).
-/// - `Close` — a Button declared inside `Win`'s `<Frames>`, so level 2, and visible with `Win`.
-/// - `Body` — a `<Frame parent="Win" hidden="true" enableMouse="true">` covering the whole window
-///   (`GathererInfo_ReportFrame`, 640×370 centred on a 640×390 dialog), also level 2, but HIDDEN
-///   when `Win` is shown. The addon shows it one line later.
-/// - `Other` — the already-open Options window it overlaps, which is what arms the occlusion gate.
-///
-/// The sequence is the addon's: `Win:Show()` (whose raise runs while `Body` is still hidden), then
-/// `Body:Show()`. `Close` and `Body` are siblings under one parent, so their levels are equal by
-/// construction and **must stay equal** — the reference's hit sweep then gives the tie to the
-/// earlier-linked frame, which is `Close`, and the Close button works.
-///
-/// What went wrong: the compaction renumbered `Close` (visible, in the bucket) and not `Body`
-/// (hidden, in no bucket), then the raise's propagate pushed the same delta into both — so the one
-/// level the compaction squeezed out of `Close` and not out of `Body` became a permanent inversion.
-/// `Body` is mouse-enabled and covers the window, so it swallowed every click and hover the Close
-/// button should have had: the button showed no highlight and could not be pressed.
+/// Gatherer's Report window: `Win` raises while its full-cover `Body` is still hidden, then `Body`
+/// shows. Siblings `Close` and `Body` must stay level through the compaction, so the reference's
+/// hit sweep gives the tie to the earlier-linked `Close`.
 #[test]
 fn a_raise_with_a_hidden_child_keeps_the_windows_own_siblings_level() {
     let mut s = script();
@@ -757,8 +664,7 @@ fn a_raise_with_a_hidden_child_keeps_the_windows_own_siblings_level() {
     .unwrap();
     s.resolve();
 
-    // The addon's own two lines: show the window (the raise fires here, with `Body` still hidden),
-    // then show the sub-frame for the selected tab.
+    // The addon's two lines: the raise fires on the first, with `Body` still hidden.
     s.run("Win:Show()").unwrap();
     s.run("Body:Show()").unwrap();
     s.resolve();
@@ -770,9 +676,7 @@ fn a_raise_with_a_hidden_child_keeps_the_windows_own_siblings_level() {
         level(&mut s, "Other")
     );
 
-    // THE SYMPTOM FIRST, through the engine's own pointer path: the Close button takes its own
-    // click and its own hover. Asserted before the arithmetic below so a regression reports what
-    // the director would see, not the number behind it.
+    // The Close button takes its own click and hover, asserted before the levels behind them.
     let (cx, cy) = centre(&s, "Close");
     assert_eq!(
         s.hit_test_name(cx, cy).as_deref(),
@@ -792,7 +696,6 @@ fn a_raise_with_a_hidden_child_keeps_the_windows_own_siblings_level() {
         "Close"
     );
 
-    // …and the number behind it.
     assert_eq!(
         level(&mut s, "Close"),
         level(&mut s, "Body"),
@@ -802,11 +705,8 @@ fn a_raise_with_a_hidden_child_keeps_the_windows_own_siblings_level() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **A script level change carries no children** (decision 2189): the Lua binding `0x774560`
-/// calls `set_frame_level 0x76a4f0` with `propagate=0` — only the raise shifts a subtree. Stock
-/// FrameXML is written against it (`BonusActionButtonTemplate` raises the button and then its
-/// cooldown by hand), and carrying the children put the bonus bar's sweep over an addon's
-/// cooldown count.
+/// `SetFrameLevel` (`0x774560`) calls `0x76a4f0` with `propagate=0`, so the children stay put;
+/// stock `BonusActionBarFrame.xml:13-15` raises a button and then its cooldown by hand.
 #[test]
 fn a_script_level_change_leaves_the_children_where_they_were() {
     let mut s = script();
diff --git a/crates/benilla-ui/src/script/tests/visibility.rs b/crates/benilla-ui/src/script/tests/visibility.rs
index 3805b3d8..fcb21929 100644
--- a/crates/benilla-ui/src/script/tests/visibility.rs
+++ b/crates/benilla-ui/src/script/tests/visibility.rs
@@ -1,4 +1,4 @@
-//! Show/Hide fire OnShow/OnHide exactly on effective transitions; OnUpdate ticks gate on visibility.
+//! Show and Hide fire OnShow/OnHide only on effective transitions; OnUpdate runs only when visible.
 
 use super::common::script;
 
diff --git a/crates/benilla-ui/src/script/tests/widget_surface.rs b/crates/benilla-ui/src/script/tests/widget_surface.rs
index 83daa23f..b5a02e0c 100644
--- a/crates/benilla-ui/src/script/tests/widget_surface.rs
+++ b/crates/benilla-ui/src/script/tests/widget_surface.rs
@@ -1,44 +1,13 @@
-//! **The widget-method surface gate** — the sibling of [`super::reference_surface`], for the API
-//! an addon reaches through a *widget* rather than through `_G` (decision 2142).
-//!
-//! `our_globals_stay_inside_the_1_12_surface` has guarded the global namespace since 1189, and the
-//! shape gate (1842/1843/2118) guards the arity and return kinds of the methods we *have*. Between
-//! them sat the question neither asks: **is the set of method NAMES on each widget class the set
-//! 1.12 registers?** A method the reference has and we do not is invisible to the shape gate,
-//! which skips what does not exist; a method we have and the reference does not is invisible to
-//! everything, and is the superset `api-coverage.sh`'s header calls "not free" — an addon that
-//! feature-detects (`if region.GetBlendMode then`) takes a path we cannot honour, and the failure
-//! surfaces far from the cause.
-//!
-//! A corpus census over 110 top-20 and 219 vanilla addons found both directions live at once
-//! (2142): `ShaguTweaks` probes `GetBlendMode`, which we were missing, and silently recolours
-//! textures the reference leaves alone; `pfUI` and `_Nameplates` call `GameTooltip:GetAnchorType`
-//! bare and raise. The demand is in the corpus, which is not in this repo — so this gate does not
-//! measure demand. It measures the SURFACE, and every entry in the two declared lists below is
-//! where the reading of the demand got written down.
-//!
-//! When re-reading that demand: those corpora hold addons that *run on* 1.12, not addons written
-//! only for it — most of the big ones are multi-client and pick a code path at load, and they come
-//! in several versions of themselves. `scripts/api-coverage.sh`'s header has the detail; decision
-//! 2146 is the case that made it matter.
-//!
-//! ## The reference side is a CHAIN, not 23 flat surfaces
-//!
-//! The reference's 23 widget registrar tables are mutually **disjoint** — a class's real surface is
-//! its own table plus the tables it misses into. Comparing a live `Frame` against `0x878ec0` alone
-//! reports 87 of its 88 methods as beyond-1.12, which is how you get a gate nobody believes.
-//! [`WIDGET_CHAINS`] is that inheritance, and its two non-obvious rows are byte-settled, not
-//! guessed: `0x87c9b8` is the base `Region` map (its 19 names are exactly [`super::super`]'s
-//! `REGION_MAP_METHODS`), and `0x847ce4` is `LootButton`, whose whole surface of its own is
-//! `SetSlot` (decision 1799, read off the registrar's own `mov edx,1`).
+//! The widget-method surface gate, the widget sibling of [`super::reference_surface`]. The
+//! reference's 23 widget registrar tables are disjoint, so a class's surface is its own table plus
+//! those it inherits ([`WIDGET_CHAINS`]): `0x87c9b8` is the base `Region` map (the 19
+//! `REGION_MAP_METHODS`), and `LootButton`'s own `0x847ce4` holds only `SetSlot`.
 use std::collections::{BTreeMap, BTreeSet};
 
 use crate::script::{widget_method_census, UiScript};
 
-/// `(class, its own registrar table, the tables it inherits)`.
-///
-/// `WorldFrame` is a `Frame` to Lua (1983/1984) and `TitleRegion` a bare `Region`, so neither has a
-/// table of its own among the 23. `TaxiRouteFrame` is absent for the same reason (1828).
+/// `(class, its own registrar table, the tables it inherits)`. `WorldFrame` is a `Frame` to Lua
+/// and `TitleRegion` a bare `Region`; like `TaxiRouteFrame`, neither has a table of its own.
 const WIDGET_CHAINS: &[(&str, &str, &[&str])] = &[
     ("Frame", FRAME, &[REGION]),
     ("WorldFrame", FRAME, &[REGION]),
@@ -70,8 +39,7 @@ const WIDGET_CHAINS: &[(&str, &str, &[&str])] = &[
     ("Minimap", "0x84c538", FRAME_CHAIN),
     ("Texture", "0x87c128", &[REGION]),
     ("FontString", "0x87c1d8", &[REGION]),
-    // The font OBJECT (`CreateFont`) carries its own `GetName`/`GetObjectType`/`IsObjectType` and
-    // inherits nothing.
+    // The font object (`CreateFont`) inherits nothing.
     ("Font", "0x87c7c8", &[]),
     ("TitleRegion", REGION, &[]),
 ];
@@ -82,17 +50,11 @@ const MODEL: &str = "0x878948";
 const PLAYER_MODEL: &str = "0x84f1fc";
 const FRAME_CHAIN: &[&str] = &[FRAME, REGION];
 
-/// Methods the reference registers that this client does not answer — **a list that may only
-/// shrink**, one row per name, naming every class it is missing on and why it has not been built.
-///
-/// The corpus demand behind each is 2142's census. A name with real, live callers does not belong
-/// here: it belongs implemented.
+/// Reference methods this client does not answer yet: one row per name, its classes and why. The
+/// list only shrinks; a name with live callers belongs implemented.
 const NOT_YET_ANSWERED: &[(&str, &str, &str)] = &[
-    // ── The MovieFrame trio: zero addon demand, and the stock GLUE screen calls all three ──────
-    // `_extracted_gluexml/MovieFrame.lua:23/30/35/47/71`. The glue screens stay ours permanently
-    // (0068 §8), so the intro-movie screen is owed these however little the ecosystem wants them —
-    // which makes this the one group here that is a real backlog item rather than a name nobody
-    // has ever typed. benilla has no movie playback at all, so it is a feature, not a verb.
+    // ── The MovieFrame trio ──
+    // The stock glue `MovieFrame.lua` calls all three; benilla plays no movie yet.
     (
         "StartMovie",
         "MovieFrame",
@@ -104,10 +66,8 @@ const NOT_YET_ANSWERED: &[(&str, &str, &str)] = &[
         "MovieFrame",
         "the same — `MovieFrame.lua:35` passes `GetMovieSubtitles()`",
     ),
-    // ── The Minimap's four content setters ────────────────────────────────────────────────────
-    // benilla draws the minimap's blips, arrow and mask from the app side (`minimap/blips`), never
-    // through Lua; the stock UI does not call these either. Wiring them means routing the art
-    // choice back through the VM, which nothing has asked for.
+    // ── The Minimap's four content setters ──
+    // The app draws the minimap's blips and arrow itself, never through Lua.
     (
         "SetArrowModel",
         "Minimap",
@@ -116,10 +76,8 @@ const NOT_YET_ANSWERED: &[(&str, &str, &str)] = &[
     ("SetBlipTexture", "Minimap", "the same"),
     ("SetIconTexture", "Minimap", "the same"),
     ("SetPlayerModel", "Minimap", "the same"),
-    // ── The Button font-object and text-colour family ─────────────────────────────────────────
-    // Seven getters and one setter over a button's disabled/highlight/pushed font state. benilla
-    // keeps that state (`button.rs`'s `Slot` triple) but publishes none of it back. **Zero call
-    // sites in 329 addon folders and zero in the stock UI** — the whole family is completeness.
+    // ── The Button font-object and text-colour family ──
+    // `button.rs` keeps this font state but publishes none of it; nothing calls these.
     (
         "GetDisabledFontObject",
         "Button CheckButton LootButton",
@@ -155,9 +113,7 @@ const NOT_YET_ANSWERED: &[(&str, &str, &str)] = &[
         "Button CheckButton LootButton",
         "the same family",
     ),
-    // ── Line spacing, on the five classes that carry text ─────────────────────────────────────
-    // A real layout property benilla's text layout does not model — a setter here is not a store,
-    // it is a change to how `ui_text` lays out wrapped lines. No caller anywhere measured.
+    // ── Line spacing, on the five classes that carry text ──
     (
         "GetSpacing",
         "EditBox Font FontString MessageFrame ScrollingMessageFrame",
@@ -168,9 +124,7 @@ const NOT_YET_ANSWERED: &[(&str, &str, &str)] = &[
         "EditBox Font FontString MessageFrame ScrollingMessageFrame",
         "the same — the setter is a layout change, not a stored value",
     ),
-    // ── EditBox mode read-backs ───────────────────────────────────────────────────────────────
-    // The four modes are all SET here (`editbox`'s `SetAutoFocus`/`SetMultiLine`/`SetNumeric`/
-    // `SetPassword`) and none is readable. Cheap, and nothing has ever asked.
+    // ── EditBox mode read-backs ──
     (
         "IsAutoFocus",
         "EditBox",
@@ -179,10 +133,7 @@ const NOT_YET_ANSWERED: &[(&str, &str, &str)] = &[
     ("IsMultiLine", "EditBox", "the same"),
     ("IsNumeric", "EditBox", "the same"),
     ("IsPassword", "EditBox", "the same"),
-    // ── ScrollingMessageFrame's line-position surface ─────────────────────────────────────────
-    // The scroll POSITION verbs (`ScrollUp`/`ScrollDown`/`ScrollToTop`…) are all here; these four
-    // report or set where that position sits, which our message buffer tracks internally and does
-    // not publish. No caller anywhere measured.
+    // ── ScrollingMessageFrame's line-position surface ──
     (
         "GetCurrentLine",
         "ScrollingMessageFrame",
@@ -191,16 +142,14 @@ const NOT_YET_ANSWERED: &[(&str, &str, &str)] = &[
     ("GetCurrentScroll", "ScrollingMessageFrame", "the same"),
     ("GetNumLinesDisplayed", "ScrollingMessageFrame", "the same"),
     ("SetScrollFromBottom", "ScrollingMessageFrame", "the same"),
-    // ── The colour picker's HSV pair ──────────────────────────────────────────────────────────
-    // `ColorSelect` publishes the RGB pair; the HSV twin would need the conversion the reference
-    // does in C. The stock `ColorPickerFrame` uses RGB only, and so does every corpus caller.
+    // ── The colour picker's HSV pair ──
     (
         "GetColorHSV",
         "ColorSelect",
         "the RGB pair is published; nothing measured asks for HSV",
     ),
     ("SetColorHSV", "ColorSelect", "the same"),
-    // ── One texture read-back ─────────────────────────────────────────────────────────────────
+    // ── One texture read-back ──
     (
         "IsDesaturated",
         "Texture",
@@ -208,9 +157,7 @@ const NOT_YET_ANSWERED: &[(&str, &str, &str)] = &[
     ),
 ];
 
-/// Methods this client answers that 1.12 does not register on that class — **each a deliberate,
-/// reasoned exception, never a quiet superset**. Same contract as
-/// [`super::reference_surface::allowed_beyond_1_12`]: a name here must say why it stays.
+/// Methods answered here that 1.12 does not register on that class, each with why it stays.
 const ALLOWED_BEYOND: &[(&str, &str, &str)] = &[];
 
 /// The reference's widget rows, `table_va -> {name}`.
@@ -236,7 +183,7 @@ fn reference_tables() -> BTreeMap<String, BTreeSet<String>> {
     out
 }
 
-/// `class -> the effective reference surface` (own table + everything it inherits).
+/// `class -> the effective reference surface` (its own table and everything it inherits).
 fn reference_surface_by_class() -> BTreeMap<&'static str, BTreeSet<String>> {
     let tables = reference_tables();
     assert!(
@@ -284,8 +231,7 @@ fn declared(list: &[(&str, &str, &str)]) -> BTreeMap<String, BTreeSet<String>> {
         .collect()
 }
 
-/// Render a `class -> names` map as the declared-list rows it would need, so a failure hands you
-/// the entry to paste rather than a set difference to transcribe.
+/// Render a `class -> names` map as declared-list rows, ready to paste in.
 fn as_rows(diff: &BTreeMap<String, BTreeSet<String>>) -> String {
     let mut by_name: BTreeMap<&String, Vec<&String>> = BTreeMap::new();
     for (class, names) in diff {
@@ -343,7 +289,7 @@ fn every_1_12_widget_method_is_answered() {
         as_rows(&missing)
     );
 
-    // A listed name that came back fails, so the list cannot outlive its fix.
+    // A listed name that is answered now fails, so the list cannot outlive its fix.
     let mut healed: Vec<String> = Vec::new();
     for (name, classes, _) in NOT_YET_ANSWERED {
         for class in classes.split_whitespace() {
@@ -374,8 +320,7 @@ fn our_widget_methods_stay_inside_the_1_12_surface() {
         let extra: BTreeSet<String> = have
             .iter()
             .filter(|n| !want.contains(*n))
-            // Our host bridge and the VM's own internals declare themselves ours by prefix, the
-            // same discipline `reference_surface` uses for globals.
+            // Our host bridge and VM internals are marked by prefix, as `reference_surface` does.
             .filter(|n| !n.starts_with("Benilla") && !n.starts_with("__benilla_"))
             .filter(|n| !listed.get(*n).is_some_and(|c| c.contains(class)))
             .cloned()
diff --git a/crates/benilla-ui/src/script/tests/worldframe.rs b/crates/benilla-ui/src/script/tests/worldframe.rs
index 090e9e9e..52825b82 100644
--- a/crates/benilla-ui/src/script/tests/worldframe.rs
+++ b/crates/benilla-ui/src/script/tests/worldframe.rs
@@ -1,6 +1,5 @@
-//! The `WorldFrame` kind (decisions 1983/1984; vtable `0x8043e8`): a `Frame` to Lua,
-//! a one-shot type, born in stratum `WORLD` with mouse and wheel enabled, and a hit the app's
-//! arbiter must be able to tell apart.
+//! The `WorldFrame` kind (vtable `0x8043e8`): a `Frame` to Lua, creatable once, born in stratum
+//! `WORLD` with mouse and wheel on, and a hit the app can tell apart.
 
 use crate::script::UiScript;
 
@@ -13,9 +12,8 @@ fn vm() -> UiScript {
     s
 }
 
-/// `GetObjectType()` answers `"Frame"` and `IsObjectType("WorldFrame")` is nil: the class
-/// inherits the base table's type slots (the TaxiRouteFrame precedent), so the registered name
-/// never becomes an identity.
+/// `GetObjectType()` answers `"Frame"`: the class keeps the base table's type slots, as
+/// `TaxiRouteFrame` does.
 #[test]
 fn the_world_frame_is_a_frame_to_lua() {
     let s = vm();
@@ -72,8 +70,6 @@ fn the_world_frame_is_born_in_stratum_world_with_the_mouse_and_wheel() {
     );
 }
 
-/// The hit test answers the world frame where nothing else is under the cursor — the addon-facing
-/// scripts on it fire — and the app can tell that hit apart from a UI hit.
 #[test]
 fn a_hit_on_the_world_frame_is_told_apart_from_a_ui_hit() {
     let mut s = vm();
diff --git a/crates/benilla-ui/src/script/tests/worldmap.rs b/crates/benilla-ui/src/script/tests/worldmap.rs
index 5a9fbd3c..c3b307fb 100644
--- a/crates/benilla-ui/src/script/tests/worldmap.rs
+++ b/crates/benilla-ui/src/script/tests/worldmap.rs
@@ -1,21 +1,19 @@
-//! The world-map bindings (decision 0203 phase 2): catalog/feed pushes, the engine-owned
-//! selection, and the deferred WORLD_MAP_UPDATE queue.
+//! The world-map bindings: catalog and feed pushes, the engine-owned selection, and the deferred
+//! `WORLD_MAP_UPDATE` queue.
 
 use super::common::script;
 use crate::script::*;
 
-/// A two-continent catalog shaped like the real 5875 one (Kalimdor first — the app's push order
-/// defines every Lua-visible index; the sheet rects are the real disjoint kernel outputs). The
-/// EK zone grid is sparse: exactly the real Goldshire cell (12735, verified against the shipped
-/// Azeroth.zmp) marked as zone 1.
+/// A two-continent catalog shaped like the real one: Kalimdor first, since the push order defines
+/// every Lua-visible index, with the real disjoint sheet rects. The sparse EK grid marks the real
+/// Goldshire cell (12735 in `Azeroth.zmp`) as zone 1.
 fn push_catalog(s: &mut UiScript) {
     let mut ek_grid = vec![0u16; 128 * 128];
     ek_grid[12735] = 1;
-    // Cell 8801 = the child (0.5, 0.5) resolves to through Elwynn's OWN loc rect — a "Stormwind
-    // City" peer child. Clicking it from the Elwynn zone map drills into the city (`0x4a67a0`).
+    // Cell 8801 is where (0.5, 0.5) lands through Elwynn's own loc rect: the Stormwind City peer,
+    // which a click on the Elwynn map drills into (`0x4a67a0`).
     ek_grid[8801] = 2;
-    // Cell 9060 = the child (0.82, 0.82) resolves to through Elwynn's own rect — Elwynn itself,
-    // the case the zone-level hover must stay silent on (the displayed zone never names itself).
+    // Cell 9060, where (0.82, 0.82) lands: Elwynn itself, which the zone-level hover never names.
     ek_grid[9060] = 1;
     s.set_world_map_catalog(vec![
         WorldMapContinentView {
@@ -52,15 +50,11 @@ fn push_catalog(s: &mut UiScript) {
                     name: "Elwynn Forest".into(),
                     area_id: 12,
                     map_file: "Elwynn".into(),
-                    // A clean synthetic loc rect inside the EK continent rect: w=2000, h=1500 → the
-                    // continent-highlight formula lands on round-ish expected coords (asserted below).
+                    // Synthetic, inside EK's rect: w=2000, h=1500, for round highlight coords.
                     loc_rect: (-8000.0, -10000.0, -400.0, -1900.0),
-                    // Three overlays. Two are shaped like real Elwynn rows: Northshire reveals
-                    // on explore bit 125, Goldshire on bit 124 (the real AreaTable exploreFlags);
-                    // their hit rects (top, left, bottom, right; px of 1002×668) sit apart so a
-                    // point is in at most one. The first is a row whose first area slot resolves
-                    // to nothing (bit 126; its rect overlaps Northshire's) — the zone-level hover
-                    // must walk past it, not stop at it.
+                    // Northshire (bit 125) and Goldshire (124) carry the real exploreFlags; hit
+                    // rects are (top, left, bottom, right) in px of 1002×668. The first row's area
+                    // is unresolvable (bit 126) and overlaps Northshire: the hover walks past it.
                     overlays: vec![
                         WorldMapOverlayView {
                             texture: "Interface\\WorldMap\\Elwynn\\STONECAIRNLAKE".into(),
@@ -94,8 +88,7 @@ fn push_catalog(s: &mut UiScript) {
                         },
                     ],
                 },
-                // A city peer of Elwynn — a WorldMapArea child of the continent with its own art
-                // folder, indistinguishable from a zone in code (`0x4a67a0`).
+                // A city peer of Elwynn, which the reference treats as a zone (`0x4a67a0`).
                 WorldMapZoneView {
                     name: "Stormwind City".into(),
                     area_id: 1519,
@@ -108,19 +101,16 @@ fn push_catalog(s: &mut UiScript) {
     ]);
 }
 
-/// The **orphan list** — `0x4a5d00`'s third array, and in 5875 its entire population: the three
-/// battlegrounds, with the real row ids, map ids, area ids and art folders, in `WorldMapArea.dbc`
-/// **file order** (the fill pass appends with no sort). Alterac Valley carries one of its three
-/// real `WorldMapOverlay` rows over its real AreaBit 954 — the only battleground art the
-/// explored-bit gate has anything to say about (WSG and AB key zero overlay rows).
+/// The orphan list, `0x4a5d00`'s third array: in 1.12 exactly the three battlegrounds, with their
+/// real row, map and area ids and art folders, in `WorldMapArea.dbc` file order (no sort). Alterac
+/// Valley carries one of its real `WorldMapOverlay` rows (AreaBit 954); WSG and AB have none.
 fn push_direct_areas(s: &mut UiScript) {
     let row = |name: &str, area_id: u32, folder: &str, overlays: Vec<WorldMapOverlayView>| {
         WorldMapZoneView {
             name: name.into(),
             area_id,
             map_file: folder.into(),
-            // A synthetic rect: nothing engine-side projects through it (the app owns every
-            // projection), it is carried because the row is the row.
+            // A synthetic rect: the app owns every projection, so nothing here reads it.
             loc_rect: (1500.0, 500.0, 1600.0, 600.0),
             overlays,
         }
@@ -149,20 +139,17 @@ fn push_direct_areas(s: &mut UiScript) {
     ]);
 }
 
-/// **The direct-area selection** — the third state, and the whole of what a battleground map is
-/// (`[0x845074]`). Inside Warsong Gulch the
-/// reference selects `(continent = -2, direct = WorldMapArea 443)`, and `GetMapInfo()` answers the
-/// art folder that `Blizzard_BattlefieldMinimap.lua:83-86` needs before it will draw anything at
-/// all; a client that models the selection as `(continent, zone)` answers nil there and draws an
-/// empty battle map.
+/// The direct-area selection (`[0x845074]`) is a third state: inside Warsong Gulch the reference
+/// selects `(continent = -2, direct = WorldMapArea 443)`, and `GetMapInfo()` answers the art
+/// folder `Blizzard_BattlefieldMinimap.lua:83` needs before it draws.
 #[test]
 fn a_direct_area_is_the_third_selection_state() {
     let mut s = script();
     push_catalog(&mut s);
     push_direct_areas(&mut s);
 
-    // The player is in Warsong Gulch: `0x4a6650`'s continent loop misses (map 489 is no
-    // continent's) and only then does the orphan loop match, selecting the row's own id.
+    // In Warsong Gulch `0x4a6650`'s continent loop misses (map 489 is no continent's) and the
+    // orphan loop selects the row's own id.
     s.set_world_map_feed(None, Some((0.5, 0.5)), 0.0, None, Vec::new(), Vec::new());
     s.set_world_map_player_direct_area(Some(443));
     s.run("SetMapToCurrentZone()").unwrap();
@@ -188,9 +175,8 @@ fn a_direct_area_is_the_third_selection_state() {
          row id has no entries to fire from"
     );
 
-    // Hover and click are refused. Both matter: there is no `.zmp` bitmap for a battleground
-    // (`0x4a6ec0`/`0x4a7620`/`0x4a7540` each test `-2` explicitly), and the world sheet's
-    // continent walk must not run just because the direct state shares its `continent == 0` cell.
+    // Hover and click are refused: a battleground has no `.zmp` bitmap (`0x4a6ec0`, `0x4a7620`,
+    // `0x4a7540` each test `-2`), and the world sheet's walk must not run on `continent == 0`.
     assert!(s
         .eval::<Option<String>>("return UpdateMapHighlight(0.5, 0.5)")
         .unwrap()
@@ -203,10 +189,9 @@ fn a_direct_area_is_the_third_selection_state() {
         "a click cannot drill off an instance map"
     );
 
-    // ── THE REFRESH TRAP. All five of the reference's in-place refresh sites re-pass
-    // `direct != -1 ? direct : zone` (`0x48f9f6`, `0x4a6460`, `0x6d93d8`, `0x6d9a17`, `0x6dac72`);
-    // one that re-passed the zone alone would drop the instance map back to the world view on the
-    // next world-state push or exploration update — silently, and only inside a battleground.
+    // All five of the reference's refresh sites re-pass `direct != -1 ? direct : zone`
+    // (`0x48f9f6`, `0x4a6460`, `0x6d93d8`, `0x6d9a17`, `0x6dac72`); passing the zone alone would
+    // drop an instance map to the world view on the next refresh.
     s.set_world_map_explored(vec![u32::MAX; 64]);
     s.set_world_map_landmarks(Vec::new());
     s.run("SetMapToCurrentZone()").unwrap();
@@ -218,8 +203,8 @@ fn a_direct_area_is_the_third_selection_state() {
         "a refresh re-selects the DIRECT cell, never the (0, 0) pair beside it"
     );
 
-    // Selecting a continent or a zone CLEARS the direct cell: `0x4a67a0`'s other legs all fall
-    // into `0x4a67ea mov [0x845074],-1`, and only `ecx == -2` jumps past it.
+    // Selecting a continent or zone clears the direct cell: `0x4a67a0`'s other legs all reach
+    // `0x4a67ea`, which writes -1 to `[0x845074]`; only `ecx == -2` jumps past it.
     s.run("SetMapZoom(2, 1)").unwrap();
     assert_eq!(
         s.eval::<(String, i64, i64)>(
@@ -230,8 +215,8 @@ fn a_direct_area_is_the_third_selection_state() {
         "the instance map does not shadow later navigation"
     );
 
-    // And the stock zoom-out button's own path off a battleground map: its `else` arm fires
-    // because `GetCurrentMapZone()` is 0 there, and `SetMapZoom(0)` is the world view.
+    // The stock zoom-out button off a battleground map: `GetCurrentMapZone()` is 0 there, so its
+    // `else` arm runs `SetMapZoom(0)`, the world view (`WorldMapFrame.lua:257`).
     s.run("SetMapToCurrentZone()").unwrap();
     s.run("SetMapZoom(0)").unwrap();
     assert_eq!(
@@ -242,10 +227,8 @@ fn a_direct_area_is_the_third_selection_state() {
     );
 }
 
-/// An instance map's overlays are **admitted**, keyed by the direct area, under exactly the zone's
-/// explored-bit gate (`0x4a67a0`'s overlay half, `0x4a6b10 jl 0x4a6b3d`) — no free reveal for a
-/// battleground. On 5875 data that means Alterac Valley's three rows and nothing at all for the
-/// other two.
+/// An instance map's overlays, keyed by the direct area, pass the zone's explored-bit gate
+/// (`0x4a67a0`'s overlay half, `0x4a6b10` to `0x4a6b3d`), with no free reveal for a battleground.
 #[test]
 fn an_instance_map_reveals_its_overlays_under_the_zone_gate() {
     let mut s = script();
@@ -270,18 +253,15 @@ fn an_instance_map_reveals_its_overlays_under_the_zone_gate() {
         "Interface\\WorldMap\\AlteracValley\\DUNBALDAR"
     );
 
-    // Warsong Gulch keys zero `WorldMapOverlay` rows — a fully explored character still sees bare
-    // detail tiles there.
+    // Warsong Gulch keys no `WorldMapOverlay` rows, so even fully explored it shows none.
     s.set_world_map_player_direct_area(Some(443));
     s.run("SetMapToCurrentZone()").unwrap();
     s.set_world_map_explored(vec![u32::MAX; 64]);
     assert_eq!(s.eval::<i64>("return GetNumMapOverlays()").unwrap(), 0);
 }
 
-/// The navigation surface: lists come from the catalog, SetMapZoom's selection reads back
-/// synchronously in the same Lua breath (the reference's dropdown-click contract), zone/continent
-/// arguments clamp, and GetMapInfo names the displayed art folder (nil at the world level — the
-/// reference Lua's own "World" fallback).
+/// Lists come from the catalog, `SetMapZoom` reads back in the same call stack as the reference's
+/// dropdown expects, arguments clamp, and `GetMapInfo` names the art folder (nil at world level).
 #[test]
 fn worldmap_navigation_and_map_info() {
     let mut s = script();
@@ -306,7 +286,6 @@ fn worldmap_navigation_and_map_info() {
         ("Durotar".into(), "The Barrens".into())
     );
 
-    // World level by default: continent 0, nil map info.
     assert_eq!(
         s.eval::<(i64, i64)>("return GetCurrentMapContinent(), GetCurrentMapZone()")
             .unwrap(),
@@ -314,7 +293,6 @@ fn worldmap_navigation_and_map_info() {
     );
     assert!(s.eval::<bool>("return GetMapInfo() == nil").unwrap());
 
-    // The synchronous read-back the reference relies on, and the art-folder name per level.
     s.run("SetMapZoom(2)").unwrap();
     assert_eq!(
         s.eval::<(i64, i64, String)>(
@@ -330,7 +308,6 @@ fn worldmap_navigation_and_map_info() {
         "a zone selection names the ZONE's art folder"
     );
 
-    // Out-of-range arguments clamp (never a Lua error — addons pass garbage).
     s.run("SetMapZoom(9, 9)").unwrap();
     assert_eq!(
         s.eval::<(i64, i64)>("return GetCurrentMapContinent(), GetCurrentMapZone()")
@@ -340,9 +317,9 @@ fn worldmap_navigation_and_map_info() {
     );
 }
 
-/// SetMapToCurrentZone lands on the app-fed player zone; the feed's projection + facing surface
-/// through GetPlayerMapPosition/GetPlayerFacing — for `"player"` and, since report B320, for the
-/// `party1..4` slots too. A `raid` token still answers the off-map sentinel.
+/// `SetMapToCurrentZone` lands on the app-fed player zone, and the feed surfaces through
+/// `GetPlayerFacing` and `GetPlayerMapPosition` for the player and `party1..4`. A `raid` token
+/// answers the off-map sentinel; the reference reads raid positions (`WorldMapFrame.lua:379`).
 #[test]
 fn worldmap_current_zone_and_player_feed() {
     let mut s = script();
@@ -389,20 +366,14 @@ fn worldmap_current_zone_and_player_feed() {
     assert_eq!(s.eval::<i64>("return GetCurrentMapContinent()").unwrap(), 0);
 }
 
-/// The **engine** moves the selection too, with no Lua in the loop — the reference's second
-/// writer of `[0x84506c]`/`[0x845070]`: `0x494780`'s `old == 0` side call to the resolver
-/// `0x4a6650`, which every exit of ends in the `SetMap` setter `0x4a67a0`.
-///
-/// We only ever had the Lua writers, so until something opened the map we sat at the world
-/// level — and there `GetPlayerMapPosition` answers a world-SHEET uv, which every addon built on
-/// Astrolabe rescales as a zone uv. This pins that a fresh session can be on the player's own
-/// zone before a single line of FrameXML or addon Lua has asked for it.
+/// The engine moves the selection with no Lua in the loop: the reference's second writer of
+/// `[0x84506c]`/`[0x845070]` is `0x494780`'s `old == 0` call to the resolver `0x4a6650`, whose
+/// every exit ends in the `SetMap` setter `0x4a67a0`.
 #[test]
 fn the_engine_can_select_a_zone_with_no_lua_call() {
     let mut s = script();
     push_catalog(&mut s);
 
-    // A fresh VM is the world sheet, and nothing Lua-side has run.
     assert_eq!(
         s.eval::<(i64, i64)>("return GetCurrentMapContinent(), GetCurrentMapZone()")
             .unwrap(),
@@ -417,8 +388,7 @@ fn the_engine_can_select_a_zone_with_no_lua_call() {
         (1, 2),
         "the engine's own SetMap is what Lua reads back"
     );
-    // The WHOLE selection moved, not just the pair of globals: GetMapInfo names the zone sheet,
-    // which is what `WorldMapFrame_Update` loads art from and what Astrolabe keys its scale on.
+    // The whole selection moved: `GetMapInfo` names the zone sheet `WorldMapFrame_Update` loads.
     assert!(
         s.eval::<Option<String>>("return GetMapInfo()")
             .unwrap()
@@ -426,8 +396,7 @@ fn the_engine_can_select_a_zone_with_no_lua_call() {
         "a selected zone names its map file; the world level is the nil that mis-scales"
     );
 
-    // It clamps through the same tail as the Lua verbs — an out-of-range pair cannot corrupt
-    // the selection (`0x4a67a0` range-checks the zone against the continent's child count).
+    // It clamps through the same tail as the Lua verbs (`0x4a67a0` range-checks the zone).
     s.sync_world_map_to_player_zone(99, 99, None);
     let (c, _) = s
         .eval::<(i64, i64)>("return GetCurrentMapContinent(), GetCurrentMapZone()")
@@ -435,9 +404,9 @@ fn the_engine_can_select_a_zone_with_no_lua_call() {
     assert!(c > 0, "clamped into the catalog, never past it");
 }
 
-/// World-level ProcessMapClick picks the continent whose sheet-rect contains the click (the
-/// 0x4a7100 AABB walk — the real kernel rects are disjoint); continent-level clicks resolve
-/// through the 0x4a6ec0 zone grid; hover names ride the same cell law.
+/// A world-level `ProcessMapClick` picks the continent whose sheet rect contains it (`0x4a7100`,
+/// the real rects being disjoint); continent-level clicks and hovers resolve through the zone grid
+/// (`0x4a6ec0`).
 #[test]
 fn worldmap_click_containment_and_zone_grid() {
     let mut s = script();
@@ -460,10 +429,9 @@ fn worldmap_click_containment_and_zone_grid() {
     s.run("ProcessMapClick(0.72, 0.63)").unwrap();
     assert_eq!(s.eval::<i64>("return GetCurrentMapContinent()").unwrap(), 2);
 
-    // Continent level: Goldshire's UV inside the EK rect lands on grid cell 12735 (the real
-    // Azeroth.zmp index for that world position) → zone 1. The zone lights up: name + fileName +
-    // the six geometry values (`0x4a8494`), all against the zone's loc rect
-    // within the continent. cont_w=35199.9, cont_h=23466.6; w=2000, h=1500.
+    // Continent level: Goldshire's uv lands on cell 12735, zone 1, which lights up with its name,
+    // file name and six geometry values (`0x4a8494`) against its loc rect in the continent:
+    // cont_w=35199.9, cont_h=23466.6; w=2000, h=1500.
     let (name, file, tpx, tpy, tx, ty, sx, sy) = s
         .eval::<(String, String, f64, f64, f64, f64, f64, f64)>(
             "return UpdateMapHighlight(0.452843, 0.720880)",
@@ -511,10 +479,8 @@ fn worldmap_click_containment_and_zone_grid() {
         "the grid click drills into the zone"
     );
 
-    // Now at the ZONE level (Elwynn): a click re-expressed through ELWYNN's own rect lands on cell
-    // 8801 = the Stormwind City peer child → drills into the city map. This is the path that was a
-    // no-op before (`0x4a75c9`: continent- and zone-level clicks run identical code, only the
-    // windowing rect differs).
+    // At zone level a click through Elwynn's own rect lands on cell 8801, the Stormwind City peer,
+    // and drills in: `0x4a75c9` runs continent- and zone-level clicks alike, windowed differently.
     s.run("ProcessMapClick(0.5, 0.5)").unwrap();
     assert_eq!(
         s.eval::<(i64, i64)>("return GetCurrentMapContinent(), GetCurrentMapZone()")
@@ -529,12 +495,10 @@ fn worldmap_click_containment_and_zone_grid() {
     assert_eq!(s.eval::<i64>("return GetCurrentMapContinent()").unwrap(), 0);
 }
 
-/// At ZONE level `UpdateMapHighlight` answers a NAME only (report B360; `0x4a812e`):
-/// a revealed overlay's sub-area when the cursor is inside its hit rect, else the neighbouring
-/// zone or city whose grid cell the cursor is in through the DISPLAYED zone's rect window — never
-/// the displayed zone itself — and always a nil fileName + six zeros, so the stock frame hides the
-/// highlight quad. Fogged sub-areas have no name; an overlay with no resolvable first area is
-/// walked past. The reference's own Duskwood shot: "Deadwind Pass" in the label, no highlight.
+/// At zone level `UpdateMapHighlight` answers a name only (`0x4a812e`): a revealed overlay's
+/// sub-area under the cursor, else the neighbouring zone or city whose cell the cursor is in
+/// through the displayed zone's rect, never that zone itself. The file name is nil and the
+/// geometry zeros, so the stock frame hides the quad.
 #[test]
 fn worldmap_zone_level_hover_names_without_highlight() {
     let mut s = script();
@@ -550,20 +514,18 @@ fn worldmap_zone_level_hover_names_without_highlight() {
         |name: &str| -> Answer { (Some(name.into()), None, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0) };
     let miss: Answer = (None, None, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0);
 
-    // Nothing explored. (0.5, 0.5) through Elwynn's rect is cell 8801 = the Stormwind City peer:
-    // the neighbouring child is NAMED, and nothing else — the B360 answer, Deadwind Pass from
-    // Duskwood in the report.
+    // Nothing explored: (0.5, 0.5) is cell 8801, the Stormwind City peer, named and nothing else.
     assert_eq!(hover(&mut s, 0.5, 0.5), name_only("Stormwind City"));
     // Cell 9060 = Elwynn itself: the displayed zone never names itself.
     assert_eq!(hover(&mut s, 0.82, 0.82), miss);
     // An empty cell, no overlay: the tail.
     assert_eq!(hover(&mut s, 0.2, 0.2), miss);
-    // Inside Goldshire's hit rect but fogged (bit 124 clear): no name — the pre-search walks the
-    // REVEALED list, and cell 8929 under it is empty.
+    // Inside Goldshire's hit rect, fogged (bit 124 clear): the pre-search walks only revealed
+    // overlays, and cell 8929 under it is empty.
     assert_eq!(hover(&mut s, 0.42, 0.7), miss);
 
-    // Reveal Northshire (bit 125 = word 3, bit 29). Its rect contains (0.5, 0.5): the overlay
-    // pre-search runs BEFORE the grid, so the sub-area wins over the city under the same point.
+    // Reveal Northshire (bit 125 = word 3, bit 29): the overlay pre-search runs before the grid,
+    // so its sub-area wins over the city under (0.5, 0.5).
     let mut explored = vec![0u32; 64];
     explored[3] = 1 << 29;
     s.set_world_map_explored(explored.clone());
@@ -585,8 +547,7 @@ fn worldmap_zone_level_hover_names_without_highlight() {
     s.set_world_map_explored(explored);
     assert_eq!(hover(&mut s, 0.5, 0.5), name_only("Northshire Valley"));
 
-    // Control: back at the continent level the hovered zone still lights up — fileName is the art
-    // folder and the quad geometry is non-zero.
+    // Control: at continent level the hovered zone still lights up, with its art folder.
     s.run("SetMapZoom(2)").unwrap();
     let (name, file, tpx, _, tx, ty, _, _) = hover(&mut s, 0.452843, 0.720880);
     assert_eq!(
@@ -596,8 +557,8 @@ fn worldmap_zone_level_hover_names_without_highlight() {
     assert!(tx > 0.0 && ty > 0.0);
 }
 
-/// SetMapZoom queues WORLD_MAP_UPDATE through the pending-event queue: nothing fires inside the
-/// call (a binding can't re-enter dispatch), the registered frame hears it on the next tick.
+/// `SetMapZoom` queues `WORLD_MAP_UPDATE` rather than firing it, since a binding cannot re-enter
+/// dispatch; the registered frame hears it on the next tick.
 #[test]
 fn worldmap_update_event_fires_on_next_tick() {
     let mut s = script();
@@ -629,16 +590,14 @@ fn worldmap_update_event_fires_on_next_tick() {
     );
 }
 
-/// The exploration fog: overlays reveal per the pushed bitset — none before any push, the
-/// matching subset after (bit 125 = Northshire in the fixture), the full info tuple comes back,
-/// and re-pushing the same bitset queues no extra repaint.
+/// Overlays reveal per the pushed explored bitset: none before a push, the matching subset after,
+/// each with its full info tuple.
 #[test]
 fn worldmap_overlays_reveal_by_explored_bits() {
     let mut s = script();
     push_catalog(&mut s);
-    s.run("SetMapZoom(2, 1)").unwrap(); // the Elwynn zone map (EK's only fixture zone)
+    s.run("SetMapZoom(2, 1)").unwrap(); // the Elwynn zone map
 
-    // Nothing explored: the zone shows no overlays (all parchment).
     assert_eq!(s.eval::<i64>("return GetNumMapOverlays()").unwrap(), 0);
 
     // Bit 125 set (word 3, bit 29): Northshire reveals, Goldshire stays fogged.
@@ -661,7 +620,7 @@ fn worldmap_overlays_reveal_by_explored_bits() {
         .eval::<bool>("return GetMapOverlayInfo(3) == nil")
         .unwrap());
 
-    // At the continent level the overlay family reads empty (fog is a zone-map thing).
+    // At continent level the overlay family reads empty: fog is a zone-map thing.
     s.run("SetMapZoom(2)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumMapOverlays()").unwrap(), 0);
 }
diff --git a/crates/benilla-ui/src/script/tick.rs b/crates/benilla-ui/src/script/tick.rs
index 2b5ee32a..cffc511a 100644
--- a/crates/benilla-ui/src/script/tick.rs
+++ b/crates/benilla-ui/src/script/tick.rs
@@ -1,7 +1,5 @@
-//! The host runtime loop — an `impl UiScript` block beside its concern (the `layout.rs` pattern):
-//! the event fan-out to registered frames ([`UiScript::fire_event`]), the per-frame advance
-//! ([`UiScript::tick`]: OnUpdate + the engine-side fades and the model panes' clocks), and the FrameXML session clock
-//! ([`UiScript::now`]). The low-level handler-firing these drive lives in [`super::event`].
+//! The host runtime loop: event fan-out ([`UiScript::fire_event`]), the per-frame advance
+//! ([`UiScript::tick`]) and the `GetTime()` clock ([`UiScript::now`]).
 
 use mlua::Lua;
 
@@ -10,59 +8,32 @@ use crate::widget::FrameHandle;
 use super::{editbox, event, tooltip, Model, ScriptValue, UiScript};
 
 impl UiScript {
-    /// Queue an event to fire at the **start of the next tick**, into the same
-    /// [`super::Model::pending_events`] list the engine's own bindings use — so it lands *after*
-    /// everything queued earlier in the frame and before that tick's `OnUpdate` pass.
-    ///
-    /// **Ordering, not laziness, is the whole reason this is public** (decision 1750). A benilla
-    /// drain runs a step behind the input pass that fed it, so an event it fires *immediately*
-    /// arrives BEFORE events the same input already queued — the reverse of the reference, where
-    /// the deferral happens inside the very call that queued them. That inversion is not
-    /// hypothetical: the soulbind confirm raised by placing an item into a worn slot was cancelled
-    /// one tick later by that same place's own `CURSOR_UPDATE`, whose `StaticPopup_Hide` is
-    /// `UIParent.lua:356-360` transcribed correctly. Queueing restores the reference's relative
-    /// order — cursor-change first, question second — while a *later* cursor change still retires
-    /// the question, which is exactly what that arm is for.
-    ///
-    /// Use [`Self::fire_event`] for anything whose ordering against in-flight queued events does
-    /// not matter, which is nearly everything.
+    /// Queue an event for the start of the next tick, behind everything queued earlier and before
+    /// that tick's `OnUpdate` pass. A drain runs a step behind its input, so firing at once would
+    /// overtake events that input already queued: the soulbind confirm for an item placed into a
+    /// worn slot must follow that placement's `CURSOR_UPDATE`, whose handler hides it
+    /// (`UIParent.lua:357-361`).
     pub fn queue_event(&mut self, event: &str, args: Vec<ScriptValue>) {
         self.model_mut()
             .pending_events
             .push((event.to_string(), args));
     }
 
-    /// Fire an event to every frame registered for it, invoking their `OnEvent` handlers
-    /// (`0x704d50`/`0x704f10`): both the legacy `this`/`event`/`arg1..argN` globals *and* the
-    /// modern `(self, event, ...)` arguments. Events reach registered frames regardless of
-    /// visibility, **in registration order** — the client's `SignalEvent 0x703e50` walks the
-    /// per-event listener list head-first (tail-append insert `0x7052d0`: FIFO, first-registered
-    /// fires first). Cross-frame order is a LAW consumers depend on: both ZoneText frames write
-    /// `PVPInfoTextString` on one event — the last writer decides. Handler errors are collected
-    /// into [`UiScript::errors`], never panicking.
+    /// Fire an event to every frame registered for it, shown or not, setting both the
+    /// `this`/`event`/`arg1..argN` globals and the `(self, event, ...)` arguments (`0x704d50`,
+    /// `0x704f10`); handler errors go to [`UiScript::errors`]. Frames fire in registration order,
+    /// as `SignalEvent` (`0x703e50`) walks its tail-appended list (`0x7052d0`), and consumers rely
+    /// on it: both ZoneText frames write `PVPInfoTextString` on one event, and the last one wins.
     ///
-    /// **The walk steps by a next-listener SAVED BEFORE the handler runs** (`0x703ee8: mov
-    /// edi,[eax+0x4]` — "save the next node before firing"; decision 1324), never by list index.
-    /// That is what makes a handler that UNREGISTERS ITSELF mid-dispatch unable to rob its
-    /// successor — and it is load-bearing in the wild: AceEvent-2.0 treats `PLAYER_LOGIN` /
-    /// `VARIABLES_LOADED` as fire-once events and unregisters its frame *inside* the handler, so
-    /// an index walk skipped whichever addon registered right after AceEvent (Bagnon_Forever's
-    /// saved-bag DB never initialized — the director's `SaveBagData:76` error dialogs). A frame
-    /// registered mid-dispatch tail-appends and is still visited; a handler that unregisters the
-    /// walk's SAVED next stops the dispatch there (the reference frees the node and walks into
-    /// its zeroed links — memory-accident territory we render as a deterministic stop, a knowing
-    /// divergence from an accident, not from a mechanism).
+    /// The walk steps by the next listener saved before each handler runs (`0x703ee8`), so a
+    /// handler that unregisters itself does not skip its successor. Deviation: a handler that
+    /// unregisters the saved next ends the dispatch, because the reference then reads a freed node.
     pub fn fire_event(&mut self, event: &str, args: Vec<ScriptValue>) {
         fire_event_into(&self.lua, event, args);
     }
 }
 
-/// [`UiScript::fire_event`] against the VM directly, for a caller that holds `&Lua` rather than
-/// `&UiScript` — which is every Lua binding, and therefore `UpdateSpells` (decision 1924).
-///
-/// Identical behaviour; `fire_event` is the same call with the script's own VM. The `&mut self` on
-/// the method was never load-bearing — the body reaches everything through `lua.app_data_mut()` —
-/// and this is the shape [`crate::loader::load_into`] already uses for the same reason (1188 §2).
+/// [`UiScript::fire_event`] for a caller holding `&Lua`, such as a Lua binding.
 pub(crate) fn fire_event_into(lua: &Lua, event: &str, args: Vec<ScriptValue>) {
     let model_mut = || lua.app_data_mut::<Model>().expect("model app_data set");
     {
@@ -75,8 +46,7 @@ pub(crate) fn fire_event_into(lua: &Lua, event: &str, args: Vec<ScriptValue>) {
         };
         while let Some(h) = at {
             let mut model = model_mut();
-            // The saved handle must still be registered — its removal (by the previous handler)
-            // ends the walk, per the doc above.
+            // A saved next that the previous handler unregistered ends the walk.
             let Some(pos) = model
                 .event_to_frames
                 .get(event)
@@ -100,38 +70,26 @@ pub(crate) fn fire_event_into(lua: &Lua, event: &str, args: Vec<ScriptValue>) {
 }
 
 impl super::UiScript {
-    /// Advance time: run `OnUpdate(self, elapsed)` on every *effectively-visible* frame that has one
-    /// (`0x704f10`: OnUpdate → `this` + `arg1 = elapsed`). Errors collected, never panicking.
-    /// Also advances the `GetTime()` clock — the FrameXML session clock (seconds, monotonic,
-    /// arbitrary epoch like the real client's), kept as the `__benilla_now` global so the stdlib
-    /// binding reads it without a host round-trip. Reference FrameXML (CastingBarFrame & co.)
-    /// anchors durations on GetTime; the clock advancing in the same call that fires OnUpdate
-    /// keeps the two views of time consistent within a frame.
-    /// The current `GetTime()` value (`__benilla_now`, seconds) — the FrameXML clock. The app
-    /// reads it to stamp an absolute expiry into the clock a Lua countdown reads (the aura feed's
-    /// `expirationTime`, decision 0257); it is the same value `GetTime()` returns inside the VM.
+    /// The current `GetTime()` value in seconds; the app stamps absolute expiries with it, such as
+    /// an aura's `expirationTime`.
     pub fn now(&self) -> f64 {
         self.lua.globals().get("__benilla_now").unwrap_or(0.0)
     }
 
-    /// Start this VM's `GetTime()` clock at `secs` rather than at zero — how a host hands a
-    /// **freshly built** VM the clock its process is already on (decision 2116).
-    ///
-    /// The reference's `GetTime` (`0x515ea0`) is `KERNEL32!GetTickCount` scaled by 0.001 (through
-    /// the thunk `0x42c010` → `0x42b790`) — an **OS** clock that knows nothing about the Lua VM and
-    /// never restarts, which is exactly what lets stock `Cooldown.lua` gate on `start > 0`. Ours
-    /// lives inside the VM, so without this a rebuilt VM — every logout/login, every `ReloadUI` —
-    /// would restart it at zero and every host value already converted onto it would land in the
-    /// past.
-    ///
-    /// Set once, at construction: from then on only [`Self::tick`] moves the clock, so the
-    /// `(Instant, GetTime)` pair a host keeps beside it stays atomic by construction.
+    /// Start this VM's `GetTime()` clock at `secs`, so a rebuilt VM (a relog, a `ReloadUI`) keeps
+    /// the process's clock. The reference's `GetTime` (`0x515ea0`, through `0x42c010` and
+    /// `0x42b790`) is `GetTickCount` scaled by 0.001, an OS clock that never restarts, which stock
+    /// `Cooldown.lua` relies on (`start > 0`). Set once, at construction; after that only
+    /// [`Self::tick`] moves it.
     pub fn set_now(&mut self, secs: f64) {
         if let Err(e) = self.lua.globals().set("__benilla_now", secs) {
             self.push_error(e);
         }
     }
 
+    /// Advance a frame: the `GetTime()` clock, the edit boxes and queued events, then
+    /// `OnUpdate(self, elapsed)` on every visible frame that has one (`0x704f10`), then the
+    /// engine's own fades, model panes and hover.
     pub fn tick(&mut self, elapsed: f32) {
         let clock = {
             let g = self.lua.globals();
@@ -141,32 +99,22 @@ impl super::UiScript {
         if let Err(e) = clock {
             self.push_error(e);
         }
-        // The focused edit box's caret blink (`0x77a790` runs on the client's frame tick).
+        // The focused edit box's caret blink (`0x77a790`, on the client's frame tick).
         editbox::tick_blink(&self.lua, elapsed);
-        // …and, from inside that same `0x77a790` (`0x77a7a1`), the dirty-word drain that fires the
-        // `OnTextChanged`s an edit only marked (decision 1831). It runs BEFORE this tick's
-        // OnUpdate sweep, matching the reference's order: the box's own OnUpdate override drains
-        // before the FrameXML handlers that read the box get their turn.
+        // Then `0x77a790`'s drain of the `OnTextChanged`s an edit only marked (`0x77a7a1`), before
+        // the OnUpdate sweep, as in the reference.
         editbox::drain_text_changed(&self.lua);
-        // …and the caret flush's own fire, the second half of `0x77a790`'s update walk
-        // (`0x77d3e0` → `0x77da80`): `OnCursorChanged` when the caret has moved. It is what
-        // `ScrollingEdit_OnCursorChanged` records and `ScrollingEdit_OnUpdate` then scrolls by,
-        // so this is the mail body and the GM ticket box following the caret as you type.
+        // Then the caret flush (`0x77d3e0` → `0x77da80`): `OnCursorChanged` when the caret moved,
+        // which `ScrollingEdit_OnUpdate` scrolls by.
         editbox::drain_cursor_changed(&self.lua);
-        // Events queued by Lua bindings last tick (`Model::pending_events` — e.g. `SetMapZoom` →
-        // `WORLD_MAP_UPDATE`; the cursor arc's `CURSOR_UPDATE`/`ITEM_LOCK_CHANGED`/
-        // `DELETE_ITEM_CONFIRM`, decision 0216) fire first, so handlers see them before this
-        // frame's OnUpdate runs.
+        // Events queued since the last tick fire before this tick's OnUpdate.
         let pending = std::mem::take(&mut self.model_mut().pending_events);
         for (event, args) in pending {
             self.fire_event(&event, args);
         }
         let ids: Vec<u32> = {
             let mut model = self.model_mut();
-            // The OnUpdate population is its own list (decision 1446) — maintained by
-            // `SetScript`, `scripts`' one writer — so this reads a few hundred handles instead
-            // of re-filtering the whole scripts map. A destroyed frame's handle stays until its
-            // liveness check fails once, then compacts here.
+            // `SetScript` keeps the OnUpdate list; a destroyed frame's handle compacts out here.
             let frames: Vec<FrameHandle> = model
                 .on_update_frames
                 .iter()
@@ -188,18 +136,9 @@ impl super::UiScript {
                 model.on_update_frames = live;
             }
             let mut ids: Vec<u32> = frames.into_iter().map(|h| model.frame_id(h)).collect();
-            // **Deterministic order, by frame id — i.e. creation order.**
-            //
-            // `model.scripts` is a hash map, so this sweep used to fire OnUpdate in an order that
-            // varied per process. That was invisible for as long as every geometry getter answered
-            // from the PREVIOUS frame's resolve: each handler saw the same stale world regardless
-            // of when it ran. The moment the getters began settling on demand (so a handler can
-            // observe work an earlier handler did this same sweep), the order became load-bearing
-            // and the macro window's tab width started flipping 164/167 run to run.
-            //
-            // Random order was always wrong — the reference sweeps a defined order — the staleness
-            // was merely hiding it. Creation order is stable, matches FrameXML declaration order,
-            // and is what a handler reading a sibling's geometry should see.
+            // Creation order, by frame id: getters settle on demand, so a handler sees what an
+            // earlier one did this sweep, and the order must be stable. The reference walks each
+            // strata level's list of shown frames (`0x765650`).
             ids.sort_unstable();
             ids
         };
@@ -209,16 +148,10 @@ impl super::UiScript {
             }
         }
         self.tick_model_panes(elapsed);
-        // Advance every ScrollingMessageFrame's per-line fade (the client's OnUpdate `0x788460`).
-        // Independent of the frame's own OnUpdate script — the fade is C++ behavior, not Lua. The
-        // AtBottom freeze gate lives inside `ScrollingMessageState::tick`.
+        // The engine's line fades, apart from any OnUpdate script: ScrollingMessageFrame's
+        // (`0x788460`) and MessageFrame's (`0x786200`), which also keeps only the lines that fit
+        // its height, so its rows are read from the resolved rect before the mutable walk.
         let mut model = self.model_mut();
-        // The sibling class's OnUpdate (`0x786200`): the same two-phase fade with no scroll gate,
-        // plus the capacity law that is this class's stand-in for `maxLines` — the cap is what fits
-        // vertically, so it needs the frame's resolved rect and is collected first (the arena walk
-        // below holds a mutable borrow that cannot also read `model.resolved`).
-        // Both per-kind walks below ride the arena's ticked-kind registry (decision 1446):
-        // dozens of handles instead of two full-arena sweeps per tick.
         let ticked: Vec<FrameHandle> = model.arena.ticked_kinds().to_vec();
         let message_frames: Vec<(FrameHandle, usize)> = ticked
             .iter()
@@ -248,16 +181,11 @@ impl super::UiScript {
             }
         }
         drop(model);
-        // Advance fading tooltips (FadeOut's ramp + end-of-ramp hide) — engine behavior like the
-        // message fade above, decision 0274.
+        // Tooltip fades: `FadeOut`'s ramp and the hide at its end.
         tooltip::tick_fades(&self.lua);
-        // The hover RE-PICK ([`Model::hover_repick`]): the world under a stationary cursor
-        // changed this tick (the hovered frame hid, or a frame was shown over the cursor), so
-        // re-run the hover walk at the SAVED cursor position — the reference's own pump tail
-        // (`0x765650` → `0x7660d0` with the saved event, didn't-move coalesce bypassed).
-        // `mouse_move` at the unchanged point is exactly that walk: the hidden frame's OnLeave
-        // already fired at hide time and `mouseover` is clear, so only the new winner's
-        // boundary fires — no second OnLeave, `OnEnter` with no physical mouse move.
+        // A frame hid or showed under a still cursor: re-run the hover walk at the saved position,
+        // as the reference's pump tail does (`0x765650` → `0x7660d0`). The hidden frame's OnLeave
+        // already fired, so only the new winner's `OnEnter` fires.
         let repick = {
             let mut model = self.model_mut();
             let due = model.hover_repick;
@@ -267,29 +195,18 @@ impl super::UiScript {
         if let Some((x, y)) = repick {
             self.mouse_move(x, y);
         }
-        // `WOW_UI_HANDLERS=<secs>` — who spent the frame (decision 1395). Last, so a report covers
-        // everything this tick fired; a no-op unless the instrument is armed.
+        // `WOW_UI_HANDLERS=<secs>`: last, so its report covers everything this tick fired.
         self.report_handler_profile(elapsed);
     }
 }
 
 impl UiScript {
-    /// The model panes' per-frame pass (decision 2007).
-    ///
-    /// Three things the reference does each frame for a **visible** model pane, in this order:
-    /// the widget's own `OnUpdate` (`0x76d7f0`, walked by the UI pump with the Lua OnUpdates the
-    /// caller just fired) advances its private scene clock by `trunc(elapsed · 1000)` ms — a
-    /// truncation, no `+0.5` (`76d854 __ftol`); the paint (`vt+0x98`, `0x76d1a0`) fires
-    /// `OnUpdateModel` before it builds the scene; and the scene's animate runs the completion
-    /// callback (`0x76cdc0`) when the armed sequence has run its length — `OnAnimFinished`, on
-    /// natural completion only (mode 0), once per arm, for a looping sequence's first pass as
-    /// much as for a clamped one's end (the flag test sits after the enqueue, `0x719370`). A hidden
-    /// pane gets none of the three: its
-    /// clock stands still and it completes nothing, which is what makes the minimap ping "resume
-    /// where the last one stopped".
-    ///
-    /// The completion is read AFTER `OnUpdateModel` because the handler may re-arm (the cooldown
-    /// flips to its flash there), and a fresh arm has nothing to complete.
+    /// The model panes' per-frame pass, for visible panes, in the reference's order: the pane's
+    /// `OnUpdate` (`0x76d7f0`) advances its clock by `trunc(elapsed · 1000)` ms, the paint
+    /// (`0x76d1a0`) fires `OnUpdateModel`, and the animate fires `OnAnimFinished` (`0x76cdc0`) once
+    /// per arm when the armed sequence completes naturally, a loop's first pass included
+    /// (`0x719370`). A hidden pane's clock stands still. Completion is read after `OnUpdateModel`,
+    /// whose handler may re-arm.
     fn tick_model_panes(&mut self, elapsed: f32) {
         let dt_ms = (elapsed * 1000.0).trunc().max(0.0) as u64;
         let update_ids: Vec<u32> = {
@@ -306,8 +223,7 @@ impl UiScript {
                     m.clock_ms += dt_ms;
                 }
             }
-            // The handler population, maintained by `SetScript` like `on_update_frames`; a
-            // destroyed frame's handle compacts out on its first miss.
+            // Kept by `SetScript`; a destroyed frame's handle compacts out on its first miss.
             if model
                 .on_update_model_frames
                 .iter()
@@ -322,11 +238,9 @@ impl UiScript {
                     .collect();
                 model.on_update_model_frames = live;
             }
-            // Visible MODEL panes WITH A MODEL INSTALLED: the handler is `CSimpleModel::LoadXML`'s
-            // (`+0x3cc`) and the paint that fires it (`76d1bc`) is reached only past the
-            // `[widget+0x318] ≠ 0` gate at `76d24c` — a file set, resident or still streaming;
-            // a pane with no file paints nothing and fires nothing. A script of that name on any
-            // other kind is inert, as it is in the reference.
+            // Only visible Model panes with a file set, resident or streaming: the paint that fires
+            // the handler (`0x76d1bc`) is gated on `[widget+0x318] ≠ 0` (`0x76d24c`). On any other
+            // kind the script is inert.
             let frames: Vec<FrameHandle> = model
                 .on_update_model_frames
                 .iter()
@@ -339,7 +253,7 @@ impl UiScript {
                 })
                 .collect();
             let mut ids: Vec<u32> = frames.into_iter().map(|h| model.frame_id(h)).collect();
-            ids.sort_unstable(); // creation order — the OnUpdate sweep's own law
+            ids.sort_unstable(); // creation order, as in the OnUpdate sweep
             ids
         };
         for id in update_ids {
diff --git a/crates/benilla-ui/src/script/tooltip/mod.rs b/crates/benilla-ui/src/script/tooltip/mod.rs
index 69e677c3..56f421d0 100644
--- a/crates/benilla-ui/src/script/tooltip/mod.rs
+++ b/crates/benilla-ui/src/script/tooltip/mod.rs
@@ -1,28 +1,14 @@
-//! The `GameTooltip` method surface + engine behavior (decision 0274): the line stack, the
-//! owner/anchor law, auto-size, and the fade — the modeled behavior of the client's game-layer
-//! tooltip class over `CSimpleFrame` (the reference's full 38-binding Lua surface, plus its
-//! money/cooldown internals; the *content* builders land per 0274's phases on top of these
-//! mechanics).
+//! The `GameTooltip` method surface and engine behaviour: the line stack, owner and anchor,
+//! auto-size and the fade.
 //!
-//! **Lines are real named FontString regions**, engine-created on demand and published as Lua
-//! globals (`<name>TextLeft1` …) — reference Lua addresses them by name
-//! (`GameTooltipTextLeft1:SetTextColor`, UnitFrame.lua), so they cannot be private state. The
-//! real template pre-declares 30 pairs and the class grows past them with `AddFontStrings`;
-//! benilla uses the one growth mechanism for all of them.
+//! Lines are named FontString regions published as Lua globals (`<name>TextLeft1` …), since
+//! FrameXML addresses them by name (`GameTooltipTextLeft1:SetTextColor`, `UnitFrame.lua:76`). The
+//! template declares 30 pairs, which are adopted; the reference grows past them through
+//! `AddFontStrings`, and this also creates pairs on demand.
 //!
-//! **Layout is a `resolve` pre-pass** ([`layout_tooltips`]): frame size = max measured line width
-//! (+ the double-line gap) + 2·pad × summed line heights + gaps, with `SetMinimumWidth` as a
-//! floor, and each double line's right column re-pointed flush to the text inset — the job the
-//! real client's C++ line layout does over the template's static anchors. It reads the measure
-//! round-trip's cached extents, so a fresh tooltip converges in ~2 frames (same as the retired
-//! Lua `OnUpdate` measure loop it replaces).
-//!
-//! `AddLine` accepts both shipped-FrameXML shapes — `(text, r, g, b[, wrap])` and the archaic
-//! `(text, "", r, g, b)` (both appear across the real 1.12 corpus; the non-number second slot is
-//! skipped). A wrap-flagged line has [`crate::widget::TOOLTIP_WRAP_WIDTH`] pinned onto its
-//! region at APPEND time, so its very first measure comes back wrapped — one round-trip, stable
-//! under the hover re-enter loop's per-frame content clears (the item description /
-//! trigger-effect lines).
+//! Layout is a pre-pass of every `resolve` ([`layout_tooltips`]): the width is the widest line (a
+//! double line adds the column gap) plus padding, floored by `SetMinimumWidth`; the height is the
+//! summed line heights and gaps; each right column sits flush with the text inset.
 
 use mlua::{Lua, Table, Value};
 
@@ -37,11 +23,10 @@ use crate::widget::{
     TOOLTIP_FADE_SECS, TOOLTIP_LINE_GAP, TOOLTIP_PAD,
 };
 
-/// Registry key of the GameTooltip method table (the MAXCSTACK discipline: named registry root).
+/// Registry key of the GameTooltip method table, a named registry root (the MAXCSTACK discipline).
 pub(super) const REG_TOOLTIP_METHODS: &str = "__benilla_tooltip_methods";
 
-/// Run `f` over a frame's tooltip state under one short write borrow. Errors if `this` is not a
-/// live GameTooltip (unreachable through the kind dispatcher, but the table is a plain Lua value).
+/// Runs `f` over a GameTooltip's state under one short write borrow.
 fn with_tip<T>(lua: &Lua, this: &Table, f: impl FnOnce(&mut TooltipState) -> T) -> mlua::Result<T> {
     let h = frame_handle_of(lua, this)?;
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -55,17 +40,12 @@ pub(super) fn tip_mut(model: &mut Model, h: FrameHandle) -> mlua::Result<&mut To
     }
 }
 
-/// Copy a named font object's resolved paint onto a line region (the `SetFontObject` copy,
-/// minus the error on a missing name: engine tests load file subsets where Fonts.xml may be
-/// absent — an unregistered name leaves the renderer's default face rather than failing the
-/// hover).
+/// `SetFontObject` onto a line cell, except that a missing font object keeps the default face
+/// rather than raising (a VM loaded without Fonts.xml).
 fn apply_font(d: &mut RegionData, name: &str, fo: Option<&FontObject>) {
     d.font_object = Some(name.to_string());
-    // The severance mask is left standing — a re-point does NOT restore inheritance in the
-    // reference (see `super::font`'s module doc on the `+0x2c` inheritMask). A freshly created
-    // line has a clean mask anyway; an adopted XML-declared line keeps whatever its own attributes
-    // severed. Either way the line inherits the object LIVE from here: a later
-    // `GameTooltipText:SetFont(…)` re-paints every tooltip line through `font::propagate`.
+    // The inherit mask (`+0x2c`) stays: a re-point does not restore inheritance in the reference.
+    // From here the line follows the font object live, through `font::propagate`.
     if let Some(f) = fo {
         d.font_path = f.font.clone();
         d.font_height = f.height;
@@ -77,14 +57,9 @@ fn apply_font(d: &mut RegionData, name: &str, fo: Option<&FontObject>) {
     }
 }
 
-/// Ensure the line-pair pool holds at least `n` pairs — ADOPTING XML-declared pairs
-/// (`<name>TextLeft<i>`/`TextRight<i>`, the ref template's pre-declared ladder: their faces
-/// ride, the engine owns justify/visibility/anchors) and creating the rest (faces cloned from
-/// the previous pair when a ladder exists, else the header/text defaults).
-/// Pair `i` (1-based): left at TOPLEFT (pad,−pad) of the frame (i = 1) or the previous left's
-/// BOTTOMLEFT (0,−gap); right at RIGHT→left RIGHT (its x offset is [`layout_tooltips`]'s to
-/// recompute). Line 1 wears `GameTooltipHeaderText`, the rest `GameTooltipText` — the real
-/// template's fonts.
+/// Grows the line-pair pool to `n` pairs: XML-declared pairs (`<name>TextLeft<i>`) are adopted
+/// with their fonts, and created pairs clone the previous pair's fonts past a declared ladder, or
+/// else wear the template's `GameTooltipHeaderText` (line 1) and `GameTooltipText`.
 fn ensure_lines(lua: &Lua, this: &Table, n: usize) -> mlua::Result<()> {
     let h = frame_handle_of(lua, this)?;
     // (id, global name) pairs to publish once the model borrow is dropped.
@@ -113,10 +88,7 @@ fn ensure_lines(lua: &Lua, this: &Table, n: usize) -> mlua::Result<()> {
             }
             let i = have + 1;
 
-            // An XML-declared pair for this index? The ref template mechanism: FrameXML declares
-            // the leading pairs (ShoppingTooltipTemplate's small-font ladder, TextLeft1..N), the
-            // class ADOPTS them and, past the ladder, grows lines that clone the previous pair's
-            // faces. GameTooltip declares none, so the header/text defaults hold there.
+            // The template's declared pair for this index (ShoppingTooltipTemplate's ladder).
             let declared = |model: &Model, cell: &str| -> Option<crate::widget::RegionHandle> {
                 if frame_name.is_empty() {
                     return None;
@@ -128,8 +100,7 @@ fn ensure_lines(lua: &Lua, this: &Table, n: usize) -> mlua::Result<()> {
                 let rh = model.id_to_region.get(&id).copied()?;
                 (model.arena.region(rh)?.owner == h).then_some(rh)
             };
-            // Font source for a CREATED cell: the previous line's declared/cloned faces when the
-            // frame carries an XML ladder, else the engine defaults.
+            // A created cell's fonts: the previous line's under an XML ladder, else the defaults.
             let seed_font =
                 |model: &mut Model,
                  d: &mut RegionData,
@@ -179,9 +150,7 @@ fn ensure_lines(lua: &Lua, this: &Table, n: usize) -> mlua::Result<()> {
                     d
                 };
                 d.hidden = true;
-                // Left-justified like the template's line stack — invisible while the rect hugs
-                // the measured text, load-bearing once the wrap consumer pins a region to the
-                // wrap column.
+                // Left-justified as in the template; it shows once a wrap line pins its width.
                 d.justify.set_h(super::JustifyH::Left);
                 d.anchors = vec![match prev_left {
                     None => Anchor::new(
@@ -204,7 +173,7 @@ fn ensure_lines(lua: &Lua, this: &Table, n: usize) -> mlua::Result<()> {
                 }];
                 model.region_data.insert(left, d);
                 model.touch_measure(left); // an adopted cell can arrive text-in-hand
-                model.touch_layout(); // a line row entered the layout graph (decision 0740)
+                model.touch_layout(); // a line row entered the layout graph
             }
             let left_id = model.region_id(left);
 
@@ -232,12 +201,12 @@ fn ensure_lines(lua: &Lua, this: &Table, n: usize) -> mlua::Result<()> {
                 d.anchors = vec![Anchor::new(Point::Right, left_id, Point::Right, 0.0, 0.0)];
                 model.region_data.insert(right, d);
                 model.touch_measure(right); // an adopted cell can arrive text-in-hand
-                model.touch_layout(); // a line row entered the layout graph (decision 0740)
+                model.touch_layout(); // a line row entered the layout graph
             }
             let right_id = model.region_id(right);
 
             if !frame_name.is_empty() {
-                // Adopted pairs are already named + published by the loader.
+                // Adopted pairs are already named and published by the loader.
                 if adopted_left.is_none() {
                     let ln = format!("{frame_name}TextLeft{i}");
                     model.region_names.entry(ln.clone()).or_insert(left_id);
@@ -265,7 +234,7 @@ fn ensure_lines(lua: &Lua, this: &Table, n: usize) -> mlua::Result<()> {
     Ok(())
 }
 
-/// One text cell's write: text + color + shown. `color` alpha defaults opaque.
+/// Writes a line cell's text and colour and shows it.
 pub(super) fn write_cell(
     model: &mut Model,
     rh: crate::widget::RegionHandle,
@@ -275,18 +244,15 @@ pub(super) fn write_cell(
     let d = model.region_data.entry(rh).or_default();
     d.text = Some(text.to_string());
     d.vertex_color = Some(color);
-    // `AddLine("…", r, g, b)`'s colour is this line's OWN colour, exactly as if Lua had called
-    // `SetTextColor` on the cell — so it must survive a later mutation of the font object the
-    // line inherits ([`super::types::FontExplicit`]). Without the mark, one
-    // `GameTooltipText:SetTextColor(…)` would repaint every red/green line in the tooltip.
+    // The line's own colour, as if set by `SetTextColor`: a later
+    // `GameTooltipText:SetTextColor` must not repaint it.
     d.font_explicit.color = true;
     d.hidden = false;
     model.touch_measure(rh);
 }
 
-/// Hide + blank every line cell and zero the counters. The caller fires `OnTooltipCleared`
-/// (outside the model borrow) — the engine-fired widget script the reference wires to its
-/// money-row clear.
+/// Hides and blanks every line cell and resets the counters; the caller fires `OnTooltipCleared`
+/// outside the model borrow.
 pub(super) fn clear_content(model: &mut Model, h: FrameHandle) {
     let (lefts, rights) = match model.arena.frame(h).map(|f| &f.kind_state) {
         Some(KindState::Tooltip(t)) => (t.left_lines.clone(), t.right_lines.clone()),
@@ -296,30 +262,10 @@ pub(super) fn clear_content(model: &mut Model, h: FrameHandle) {
         if let Some(d) = model.region_data.get_mut(&rh) {
             d.text = None;
             d.hidden = true;
-            // `measured` is deliberately KEPT. It is a cache whose validity gate is its own
-            // content hash ([`RegionData::measure_key`] over text/font/wrap/outline), so wiping
-            // it here invalidates nothing the key would not — while destroying the one thing that
-            // makes the hover re-enter loop affordable. That loop
-            // (`ContainerFrameItemButton_OnUpdate`, unthrottled in 1.12 and shipped verbatim as
-            // the reference's `ContainerFrameItemButton_OnUpdate`) clears and rebuilds the SAME content
-            // every frame: keeping the cache lets each rebuilt line re-validate against its own
-            // key, so nothing re-shapes, the measure list stays empty, its forced second resolve
-            // never happens, and the layout gate's fingerprint — which exists precisely to
-            // "absorb idempotent writes for free" (layout.rs) — closes over the whole loop.
-            // Wiping it cost +10 CPU ms/frame on a live bag hover (measured 13.2 → 23.9 cpu_ms,
-            // `WOW_CAPTURE=ui-bag` vs `ui-tooltip`); the gate is
-            // `layout_gate::the_hover_re_enter_loop_neither_re_measures_nor_re_solves`.
-            //
-            // The wrap pin (`size`) is likewise KEPT, and for the stronger reason: wiping it here
-            // was the last write that made the hover re-enter loop differ from itself. The wipe
-            // and `append_line`'s re-pin are a round trip inside ONE frame — same cell, same
-            // width, no observable state between them — but each half bumped the layout epoch, so
-            // tier 1 went dirty every hover frame and tier 2 hashed the whole UI to conclude
-            // nothing had moved (~0.65 ms/frame, `WOW_UI_COST=1` on `WOW_CAPTURE=ui-tooltip`, at
-            // solves=0). The pin is now written from the line's own wrap flag at append time —
-            // set for a wrap line, cleared for a plain one — which covers the case this wipe
-            // existed for (a cell whose new content doesn't wrap) without a write per frame.
-            // A hidden, textless cell contributes nothing to layout in between either way.
+            // `measured` and the wrap pin (`size`) stay: the measure cache is keyed by content
+            // ([`RegionData::measure_key`]) and `append_line` rewrites the pin, so the hover
+            // loop's per-frame clear and rebuild (`ContainerFrameItemButton_OnUpdate`) re-measures
+            // and re-lays out nothing.
         }
     }
     if let Ok(t) = tip_mut(model, h) {
@@ -328,9 +274,8 @@ pub(super) fn clear_content(model: &mut Model, h: FrameHandle) {
         t.unit_token = None;
         t.world_owned = false;
     }
-    // The mouseover health bar is UNIT content: it hides with the lines (the ref bar exists
-    // only while a unit shows; the byte law's watcher re-shows it on the next unit render).
-    // Without this, the bar from the last mob hover rode under every ITEM tooltip.
+    // The `<name>StatusBar` health bar is unit content: it hides with the lines, and the next
+    // unit render re-shows it.
     let bar = model
         .arena
         .frame(h)
@@ -341,7 +286,7 @@ pub(super) fn clear_content(model: &mut Model, h: FrameHandle) {
     }
 }
 
-/// Fire `OnTooltipCleared` on the tooltip frame (errors → [`Model::errors`], never propagated).
+/// Fires `OnTooltipCleared`; a script error is recorded, never propagated.
 pub(super) fn fire_cleared(lua: &Lua, h: FrameHandle) {
     let id = {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -354,11 +299,9 @@ pub(super) fn fire_cleared(lua: &Lua, h: FrameHandle) {
     }
 }
 
-/// A content `Set*`'s tail: show when it rendered lines, hide when it rendered none. The real
-/// client's uncached path leaves a CLEARED tooltip whose size collapses to nothing — with our
-/// declared-size plate the visible equivalent is a hide; the hover's re-enter repaints the
-/// moment the app answers the ask. Hiding through the arena directly (not [`hide_tooltip`])
-/// keeps the owner: IsOwned must stay true for the re-enter loop.
+/// A content `Set*`'s tail: shown with lines, hidden without. The reference leaves an uncached
+/// tooltip cleared and collapsed to nothing; this plate keeps its declared size, so it hides. It
+/// hides without [`hide_tooltip`] to keep the owner, which the hover loop's `IsOwned` needs.
 pub(super) fn show_or_hide_empty(lua: &Lua, h: FrameHandle) {
     let lines = {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -370,10 +313,8 @@ pub(super) fn show_or_hide_empty(lua: &Lua, h: FrameHandle) {
     set_shown(lua, h, lines > 0);
 }
 
-/// Cancel a running fade and restore full alpha (fresh CONTENT does this — re-hovering during
-/// the fade-out resurrects the tooltip at full strength). Conditional on a fade actually running,
-/// because an addon that lowered the plate's alpha itself and then added a line keeps its alpha:
-/// only the three sites in [`full_alpha`] are documented to stamp it back.
+/// New content cancels a running fade at full alpha; with no fade running, an alpha the addon set
+/// stays, since only the paths in [`full_alpha`] reset it.
 fn cancel_fade(model: &mut Model, h: FrameHandle) {
     if let Ok(t) = tip_mut(model, h) {
         if t.fade_start.take().is_some() {
@@ -382,14 +323,8 @@ fn cancel_fade(model: &mut Model, h: FrameHandle) {
     }
 }
 
-/// `SetAlpha(255)` — **UNCONDITIONAL**, and the FIRST thing the SetOwner core `0x52ffe0` does
-/// (`0x52fff4`), before the five stores; `0x530a80`'s show arm does it too, and its self-hide arm
-/// reaches it through `0x530a60` → `0x52ffe0(0, 0, 0, 0)`. So all three of SetOwner, Show and the
-/// effective-hide leave the plate at full strength whether or not one of OUR fades was running
-/// (`0x52ffe0` / `0x530a80`).
-///
-/// [`cancel_fade`] is not this: it only restores the alpha a fade of ours took away, so a plate
-/// left dim by any other path never recovered where the reference recovers on the next SetOwner.
+/// `SetAlpha(255)`, unconditional: the SetOwner core `0x52ffe0` does it first (`0x52fff4`), and
+/// Show (`0x530a80`) and its self-hide (`0x530a60`, the core with no owner) reach it too.
 fn full_alpha(model: &mut Model, h: FrameHandle) {
     if let Ok(t) = tip_mut(model, h) {
         t.fade_start = None;
@@ -397,12 +332,12 @@ fn full_alpha(model: &mut Model, h: FrameHandle) {
     model.arena.set_alpha(h, 1.0);
 }
 
-/// The engine's `GetTime` clock (the `__benilla_now` global [`super::UiScript::tick`] advances).
+/// The engine's `GetTime` clock, which [`super::UiScript::tick`] advances.
 fn now(lua: &Lua) -> f64 {
     lua.globals().get("__benilla_now").unwrap_or(0.0)
 }
 
-/// Show/hide through the arena with the visibility events fired (the shared Show/Hide's path).
+/// Shows or hides through the arena and fires the visibility events.
 pub(super) fn set_shown(lua: &Lua, h: FrameHandle, shown: bool) {
     let changed = {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -411,37 +346,15 @@ pub(super) fn set_shown(lua: &Lua, h: FrameHandle, shown: bool) {
     event::fire_visibility_changes(lua, changed);
 }
 
-/// The engine tooltip's default text colour — the byte constant `0xc0d3e8` = `0xffffd200` gold
-/// every no-colour `AddLine`/`SetText` renders with. This is why the reference's zone tooltip is
-/// GOLD despite Minimap.lua's `AddLine(text, "", 1.0, 1.0, 1.0)`: 1.12's binding reads the colour
-/// at its fixed positions, the `""` in the r-slot is not a number, and the whole colour tail is
-/// dropped in favour of this default — the trailing 1.0s never shift into place (the last one is
-/// consumed as the truthy wrap flag). Byte-pinned: the static-init writer `0x528e50` stores
-/// `0xffffd200` at `0xc0d3e8`.
+/// The default line colour, gold `0xffffd200` (stored at `0xc0d3e8` by `0x528e50`). The zone
+/// tooltip's `AddLine(text, "", 1.0, 1.0, 1.0)` (`Minimap.lua:40`) renders in it: the `""` r-slot
+/// drops the whole colour, and the last `1.0` lands in the wrap slot.
 pub(in crate::script) const DEFAULT_TEXT_GOLD: [f32; 4] = [1.0, 210.0 / 255.0, 0.0, 1.0];
 
-/// The client's duration-string formatter, `0x52fa50` — the one that turns a millisecond count into
-/// "2 hours remaining" / "45 seconds remaining". Its parameter vector is the binary's: `(V_ms,
-/// keyPrefix, roundUp)`, minus the `extraArg` slot only the enchant line fills.
-///
-/// **The ladder, with the thresholds decoded from the compare instructions** (`52fa76`, `52fab4`,
-/// `52fb03`, falling through to `0x52fb4f`): `≥ 86_400_000` → `_DAYS` · `≥ 3_600_000` → `_HOURS` ·
-/// `≥ 60_000` → `_MIN` · else `_SEC`. Each arm divides by its own threshold, so the number shown is
-/// always in the unit the arm names.
-///
-/// **`roundUp` ceils — but only in the top three arms; `_SEC` always truncates.** That asymmetry is
-/// the whole reason this is a shared function and not four `format!`s, and it is what produces the
-/// reference's three surprising readings: 61 s is "2 minutes remaining" (ceil, not "1"), 3 599 999 ms
-/// is "60 minutes remaining" (the hour arm needs the full hour, so there is no "1 hour" until
-/// exactly 3 600 000), and the final second before an aura lapses reads "**0** seconds remaining"
-/// (truncation, not "1").
-///
-/// **The text is the player's own `GlobalStrings.lua`, never ours.** `get` is the VM-global lookup
-/// (`load_global_strings` runs the shipped file into this VM at boot, off the patch chain); the
-/// template arrives as `"%d minutes remaining"` and the count fills its one `%d`. A key the string
-/// table doesn't carry yields **no line at all** rather than an invented one — the same disposition
-/// 0620 §5 took for a reagent whose template hasn't streamed. That is also why this house ships no
-/// copy of the eight strings: on an install they are read, and off one there is nothing to render.
+/// The client's duration formatter (`0x52fa50`): days, hours, minutes or seconds by threshold,
+/// each dividing by its own unit. `round_up` ceils every arm but seconds, which truncates, so 61 s
+/// reads "2 minutes" and 3 599 999 ms "60 minutes". The text is the player's own
+/// `GlobalStrings.lua` through `get`; a missing key renders no line.
 pub(in crate::script) fn duration_text(
     ms: u32,
     key_prefix: &str,
@@ -462,8 +375,6 @@ pub(in crate::script) fn duration_text(
     } else {
         ("SEC", SEC_MS)
     };
-    // `roundUp` reaches the day/hour/minute arms only — the seconds arm has no rounding branch at
-    // all, so it truncates whatever `roundUp` says.
     let n = if round_up && divisor != SEC_MS {
         ms.div_ceil(divisor)
     } else {
@@ -473,19 +384,9 @@ pub(in crate::script) fn duration_text(
     Some(template.replacen("%d", &n.to_string(), 1))
 }
 
-/// [`crate::strings::plural`] for this module's callers — the `_P1` pick behind
-/// `GetText(token, gender, n)`, whose byte law (and the refuted `> 1` reading: `703c89` is a
-/// *signed* test, so a zero ordinal takes the plural arm and a lapsing aura reads "0 seconds
-/// remaining") now lives with the primitive rather than in a fourth private copy of it. Four
-/// copies of one rule is the shape decision 2045 wrote about; `fill` had eight.
-///
-/// **Gender is not modelled, and that is faithful, not a gap:** `0x52fa50` pushes a literal `0`
-/// on both arms (`52fb8d: 6a 00`, `52fbaa: 6a 00`), which `0x703bf0` turns into nil, and enUS
-/// folds nil to no suffix.
-///
-/// (When BOTH the twin and the bare token are absent the reference renders an EMPTY line, off its
-/// pre-seeded `0x882748`; we render no line at all. Unreachable with shipped data — all eight of
-/// the aura family's keys ship — and off an install there is no string table to be faithful to.)
+/// [`crate::strings::plural`], the `_P1` pick of `GetText(token, gender, n)`. There is no gender:
+/// the formatter passes a literal 0 (`0x52fa50`), which `0x703bf0` reads as nil. With neither key
+/// present the lookup yields "" (`0x882748`), which the line core drops, so no line either way.
 pub(in crate::script) fn plural_template(
     token: &str,
     n: u32,
@@ -494,8 +395,7 @@ pub(in crate::script) fn plural_template(
     crate::strings::plural(token, Some(n), get)
 }
 
-/// A colour-component argument — `lua_tonumber`'s coercion (a numeric string counts, `""` and
-/// other strings don't).
+/// A colour component by `lua_tonumber`'s coercion: a numeric string counts, other strings do not.
 fn color_num(v: Option<&Value>) -> Option<f32> {
     match v {
         Some(Value::Number(n)) => Some(*n as f32),
@@ -505,8 +405,9 @@ fn color_num(v: Option<&Value>) -> Option<f32> {
     }
 }
 
-/// The bindings' boolean-argument read (`GetBoolOrDefault 0x6f1c10`): nil/absent, false, numeric 0,
-/// and the strings `"0"`/`"off"`/`"disabled"` are false; everything else is true.
+/// A wrap flag: nil, false, 0 and the strings "0", "off" and "disabled" are false, anything else
+/// true. The reference reads it with `GetBoolOrDefault` (`0x6f1c10`,
+/// `binding_abi::bool_or_default`), where "false", "no" and 0.5 are false too.
 fn bool_arg(v: Option<&Value>) -> bool {
     match v {
         None | Some(Value::Nil) | Some(Value::Boolean(false)) => false,
@@ -519,12 +420,8 @@ fn bool_arg(v: Option<&Value>) -> bool {
     }
 }
 
-/// The colour block of an `AddLine`-family tail (the values at the r/g/b positions): applied
-/// only when the r-slot is a number (`lua_isnumber 0x6f34d0` — the sole gate);
-/// anything else drops the WHOLE block to the default gold [`DEFAULT_TEXT_GOLD`] — the ref's
-/// gold zone tooltip, whose `(text, "", 1.0, 1.0, 1.0)` shape has `""` at the r-slot. When the
-/// gate passes, g/b are UNGATED `lua_tonumber` reads: a missing/non-number component is **0.0**
-/// (byte-pinned). Alpha is forced opaque (the bindings pack `0xFF`).
+/// An `AddLine`-family colour, gated on the r-slot alone (`lua_isnumber`, `0x6f34d0`), else
+/// [`DEFAULT_TEXT_GOLD`]; past the gate a non-number g or b reads 0, and alpha is always opaque.
 fn parse_line_color(r: Option<&Value>, g: Option<&Value>, b: Option<&Value>) -> [f32; 4] {
     match color_num(r) {
         Some(r) => [
@@ -537,9 +434,8 @@ fn parse_line_color(r: Option<&Value>, g: Option<&Value>, b: Option<&Value>) ->
     }
 }
 
-/// Parse an `AddLine` tail (the args after `text`): positional `r, g, b, wrapText` — the
-/// byte-pinned `0x531630` signature. The wrap flag is read at its position REGARDLESS of the
-/// colour gate (the ref's zone-tooltip shape wraps: its trailing `1.0` lands in the wrap slot).
+/// An `AddLine` tail, positional `r, g, b, wrap` (`0x531630`); the wrap flag is read whatever the
+/// colour gate decides.
 fn parse_line_tail(args: &[Value]) -> ([f32; 4], bool) {
     (
         parse_line_color(args.first(), args.get(1), args.get(2)),
@@ -547,8 +443,7 @@ fn parse_line_tail(args: &[Value]) -> ([f32; 4], bool) {
     )
 }
 
-/// A Lua text argument → the line's string: strings pass through, numbers stringify (Lua
-/// coercion), nil/absent is an empty line (`GameTooltip:AddLine()` ships in the corpus).
+/// A text argument as a line's string: numbers stringify as Lua does, and nil is empty.
 fn text_of(v: Option<&Value>) -> String {
     match v {
         Some(Value::String(s)) => s.to_str().map(|s| s.to_string()).unwrap_or_default(),
@@ -565,10 +460,9 @@ fn text_of(v: Option<&Value>) -> String {
     }
 }
 
-/// Append one line (both columns; `right = None` leaves the right cell hidden). Grows the pool,
-/// writes the cells, bumps `num_lines` (+ the line's wrap flag), cancels any fade. Does NOT show
-/// the tooltip — `AddLine` leaves showing to the caller (the corpus' `AddLine … Show()`),
-/// `SetText`/the content builders show themselves.
+/// Appends one line and cancels any fade, without showing the tooltip: `AddLine` callers call
+/// `Show`. The reference's line core drops a line whose sides are both empty (`0x530270`); this
+/// appends it.
 pub(super) fn append_line(
     lua: &Lua,
     this: &Table,
@@ -585,30 +479,14 @@ pub(super) fn append_line(
         _ => return Err(mlua::Error::runtime("not a GameTooltip")),
     };
     write_cell(&mut model, lh, &left.0, left.1);
-    // A wrap-flagged line PINS its wrap column at write time, so its very first measure ask
-    // carries the width and comes back WRAPPED (multi-row height) in the same frame. The old
-    // shape — layout re-pinning after an overflowing single-line measure — needed a second
-    // round-trip that the bag re-enter loop's per-frame content clear kept wiping out: wrapped
-    // lines never converged live (the plate under-counted their rows forever — the bread/
-    // hearthstone spill). One step, no oscillation.
-    // The wrap pin is written from the LINE's own flag every append — set for a wrap line,
-    // cleared for a plain one — so a cell that changes role can never keep a stale pin, and
-    // `clear_content` needs no wipe of its own (which is what used to make this write differ
-    // every frame). The epoch bump is gated on a REAL change: in the hover re-enter loop the
-    // rebuilt line pins the same width it already carried, so tier 1 stays clean and the
-    // whole-UI fingerprint (tier 2) never runs — see `clear_content`'s note.
+    // The wrap width is pinned at append, so the first measure already comes back wrapped. It is
+    // written from this line's own flag every time, and layout is touched only on a change.
     let pin = wrap.then_some((crate::widget::TOOLTIP_WRAP_WIDTH, 0.0));
     if let Some(d) = model.region_data.get_mut(&lh) {
         if d.size != pin {
             d.size = pin;
-            // NAMED, not conservative (decision 1388). This writes one region's EXPLICIT SIZE and
-            // nothing else — no anchor target, no roster membership — which is the exact shape
-            // 1388 migrated every size setter to. It was missed because it is an internal write
-            // rather than a `SetWidth` binding, and the miss is expensive in the one place it can
-            // least afford to be: the pin flips whenever a line changes ROLE between wrapped and
-            // plain, which is what every hover from one item or spell to a differently-shaped one
-            // does. A conservative touch there re-derives the whole layout graph — every live
-            // frame's scale re-synced, every anchored region re-hashed — on each hover.
+            // A size-only write takes the named touch: a conservative one would re-derive the
+            // whole layout graph on every hover that turns a line between wrapped and plain.
             model.touch_layout_region(lh);
             // The wrap pin is the measure key's wrap-width input.
             model.touch_measure(lh);
@@ -627,8 +505,7 @@ pub(super) fn append_line(
 mod verbs;
 pub(super) use verbs::install;
 
-/// The full hide: drop the owner, cancel the fade, clear the content, hide the frame, fire
-/// `OnTooltipCleared`. Shared by the `Hide` method and the fade's end-of-ramp.
+/// The full hide shared by `Hide`, a `Show` with no owner or no lines, and the end of a fade.
 pub(super) fn hide_tooltip(lua: &Lua, h: FrameHandle) {
     {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -642,14 +519,8 @@ pub(super) fn hide_tooltip(lua: &Lua, h: FrameHandle) {
     fire_cleared(lua, h);
 }
 
-/// One line cell's layout input: `Some((w, h))` once the cell is shown with text AND the measure
-/// round-trip has answered; one floored unit each way for a shown but EMPTY cell (the reference's
-/// `AddLine("")` adds no line at all, and its virtual `GetHeight` never reads back `0.0`); `None`
-/// for hidden/cleared cells and for PENDING measures. A pending cell contributes nothing — no
-/// width, no height, and (in the caller) no gaps — so a fresh tooltip holds its declared default
-/// size until real extents land, instead of collapsing to a gaps-only rect (the guard the first
-/// cut got wrong: it summed LINE_GAP/DOUBLE_GAP for unmeasured rows, caught by the migration
-/// pass).
+/// A line cell's measured extent; `None` for a hidden or unmeasured cell, which adds no size and
+/// no gap, so a fresh tooltip keeps its declared size until its lines are measured.
 type Cell = Option<(f32, f32)>;
 
 fn cell(model: &Model, rh: crate::widget::RegionHandle) -> Cell {
@@ -659,11 +530,8 @@ fn cell(model: &Model, rh: crate::widget::RegionHandle) -> Cell {
         return None;
     }
     if text.is_empty() {
-        // The same floor the sweep applies to the line's own rect (`layout::FONTSTRING_MIN_SPAN`):
-        // the reference's `GetHeight 0x772a60` is virtual and ends in a one-unit clamp, so `0.0` is
-        // not a height any caller — plate arithmetic included — can read back off a FontString.
-        // Reporting zero here while the chain below the row resolved one unit is the B309 shape at
-        // 1/14th the size, and the point of one constant is that the two cannot drift apart.
+        // One unit each way, the floor of the line's own rect: the reference's `GetHeight`
+        // (`0x772a60`) clamps to one unit, so no FontString reads back 0.
         return Some((
             super::layout::FONTSTRING_MIN_SPAN,
             super::layout::FONTSTRING_MIN_SPAN,
@@ -672,52 +540,13 @@ fn cell(model: &Model, rh: crate::widget::RegionHandle) -> Cell {
     d.measured.map(|m| (m.w, m.h))
 }
 
-/// The auto-size + right-flush pre-pass, run at the top of every layout resolve (decision 0274):
-/// for each live GameTooltip, frame size = max measured line width (a double line is
-/// left + gap + right) + 2·pad, floored by `SetMinimumWidth`, × summed line heights + gaps; each
-/// visible right column's anchor re-points so its right edge sits at the text inset. Skips
-/// frames whose lines haven't been measured yet — the XML default size holds until the extents
-/// land. With a [`TextMeasure`](super::TextMeasure) installed that is the SAME `resolve`
-/// (`resolve` solves, fills the pending measures inline, and solves again, so this pre-pass runs
-/// a second time with real extents); without one it is the host's batch round-trip, one frame
-/// later, which is the engine-less path every measurer-free VM still takes.
-/// **ANCHOR_CURSOR — mode 6, re-anchored to the live cursor every frame** (`0x530b20`, the
-/// `CGameTooltip` override of `vtable+0x38` on `0x808f60`). Nine corpus files ask for it — `pfUI`'s
-/// tooltip, xpbar and chat modules, `pfQuest/browser.lua`, `TipBuddy` — and until decision 2176
-/// benilla warned and placed them by some other mode.
-///
-/// The whole of the re-anchor is one `SetPoint`:
-///
-/// ```text
-/// 530b32  cmp [this+0x318],6 ; jne                    -- every other mode skips
-/// 530b3b  eax = [this+0xa0]                           -- the CSimpleTop root == [0xcf0bd8]
-/// 530b4f  ecx = [eax+0x111c] ; edx = [eax+0x1118]     -- the SAVED cursor, normalised [0,1]
-/// 530b63  call 0x41ad80                               -- x *= G44 (screen w), y *= G48 (screen h)
-/// 530b68  fld [this+0x7c] ; fdivr 1.0f                -- 1 / the tooltip's own effective scale
-/// 530b97  call 0x767c70(BOTTOM=7, [0xcf0bd8], BOTTOMLEFT=6, x/scale, y/scale, doResolve=1)
-/// ```
-///
-/// So **the plate's BOTTOM-centre is pinned to the screen's BOTTOMLEFT plus the cursor's absolute
-/// position** — centred horizontally on the cursor and sitting directly above it. Four details are
-/// worth keeping because none is guessable from the name:
-///
-/// * The `relativeTo` is the screen root passed **raw**, not `+0x24` like every other anchor — the
-///   `CSimpleTop`'s `CLayoutFrame` base sits at offset 0. Ours is [`SCREEN`](super::SCREEN), which
-///   is the same object.
-/// * The **divide by the tooltip's own effective scale** is the "cursor box recip": an anchor
-///   offset is stored raw and multiplied by the child's scale at resolve time, so dividing here is
-///   what makes the result land at the cursor's *absolute* position. Ours does the same divide,
-///   against the same scale [`GetWidth`](super::object::eff_scale) reads.
-/// * **The `SetOwner`-time offsets `+0x3c4/+0x3c8` do not participate** — 12 reads of them, every
-///   one on a modes-0..5 arm of `0x52fe90`.
-/// * There is **no `ClearAllPoints` here** (earned zero over the function's complete call set): one
-///   anchor slot is overwritten, and `0x767c70`'s own no-op gate — same target, same
-///   `relativePoint`, both offsets within 2⁻²² — is what keeps a still cursor free.
-///
-/// It runs from the per-frame update pump, which a hidden tooltip is not in (`0x76ad9d`
-/// deregisters on hide), and in the **same frame** as the placement it produces: the layout drain
-/// `0x768ed0` runs at `0x765799`, right after the `+0x38` loop and before the draw. Hence its home
-/// here, at the top of the resolve, beside the auto-size pass.
+/// `ANCHOR_CURSOR` (mode 6), re-anchored every frame by the update override `0x530b20`: one
+/// `SetPoint` (`0x767c70`) pins the plate's BOTTOM to the screen root's BOTTOMLEFT (`0xcf0bd8`)
+/// at the cursor position divided by the tooltip's own effective scale, so it sits centred above
+/// the cursor. There is no `ClearAllPoints`, and `SetPoint`'s no-op gate keeps a still cursor
+/// free. The `SetOwner` offsets play no part (only `0x52fe90` reads them). Only a shown tooltip is
+/// in the update pump (`0x76ad9d`), and the placement lands the same frame, before the layout
+/// drain (`0x768ed0`).
 fn cursor_anchor(model: &mut Model, h: FrameHandle) {
     let scale = crate::script::object::eff_scale(model, h);
     let (cx, cy) = model.cursor_pos;
@@ -729,7 +558,7 @@ fn cursor_anchor(model: &mut Model, h: FrameHandle) {
         cy / scale,
     );
     let input = model.layout_inputs.entry(h).or_default();
-    // `0x767c70`'s change-detect, in our own terms: one slot, replaced only on a real change.
+    // `0x767c70`'s change detect: the one slot is replaced only on a real change.
     let same =
         input.anchors.len() == 1 && crate::script::object::anchor_bits_eq(&input.anchors[0], &new);
     if same {
@@ -741,10 +570,8 @@ fn cursor_anchor(model: &mut Model, h: FrameHandle) {
 }
 
 pub(super) fn layout_tooltips(model: &mut Model) {
-    // The arena's tooltip registry, not the resolve's whole frame roster: this pre-pass runs at
-    // the top of EVERY resolve, and finding two or three tooltips by scanning ~4000 ids was most
-    // of what it cost (decision 1634). `frame_to_id` still gates each one — a tooltip outside the
-    // resolve's roster would mint an id here and take the ledger's conservative branch with it.
+    // Only tooltips in the resolve's roster: one outside it would mint an id here and take the
+    // layout ledger's conservative branch.
     let tips: Vec<FrameHandle> = model
         .arena
         .tooltip_kinds()
@@ -753,9 +580,7 @@ pub(super) fn layout_tooltips(model: &mut Model) {
         .filter(|h| model.frame_to_id.contains_key(h))
         .collect();
     for h in tips {
-        // Mode 6 first, and **before the line gate below**: the reference's per-frame update is
-        // not gated on content at all, only on the plate being in the pump's list — which is the
-        // shown list. See [`cursor_anchor`].
+        // Mode 6 runs before the line gate: the reference re-anchors any shown plate, lines or not.
         let cursor_mode = match model.arena.frame(h).map(|f| (&f.kind_state, f.shown)) {
             Some((KindState::Tooltip(t), shown)) => shown && t.anchor == TooltipAnchor::Cursor,
             _ => false,
@@ -776,13 +601,6 @@ pub(super) fn layout_tooltips(model: &mut Model) {
         if num == 0 {
             continue;
         }
-        // (Wrap columns are pinned at append time — append_line — so every measure here is
-        // already the wrapped one; no second round-trip.)
-        // Per-line metrics next (one read pass), then the size + right-flush writes. Only
-        // measured cells contribute — a row with no measured cell adds no height and no gap, and
-        // a tooltip with nothing measured yet is skipped whole (its declared size holds until the
-        // extents land — this resolve's own `fill_measures` with a measurer installed, the host's
-        // batch round-trip a frame later without one).
         let n = num.min(lefts.len()).min(rights.len());
         let rows: Vec<(Cell, Cell)> = (0..n)
             .map(|i| (cell(model, lefts[i]), cell(model, rights[i])))
@@ -804,22 +622,20 @@ pub(super) fn layout_tooltips(model: &mut Model) {
             maxw = maxw.max(lw + rw);
         }
         if counted == 0 {
-            continue; // nothing measured yet — hold the declared size
+            continue; // nothing measured yet: the declared size holds
         }
         maxw = maxw.max(min_w);
         if maxw <= 0.0 || totalh <= 0.0 {
             continue;
         }
         let input = model.layout_inputs.entry(h).or_default();
-        // `pad_w` = SetPadding's extra width (ref ItemRefTooltip: room for the close button).
+        // `pad_w` is `SetPadding`'s extra width (ItemRefTooltip's room for its close button).
         input.width = maxw + 2.0 * TOOLTIP_PAD + pad_w;
         input.height = totalh + 2.0 * TOOLTIP_PAD;
-        // This pre-pass runs INSIDE the resolve, so it must not open tier 1 (see the note method's
-        // own doc) — but the per-node ledger decision 1388's incremental pass seeds from still has
-        // to hear that these two inputs were written by something other than a Lua setter.
+        // Inside the resolve, so a note and not a touch; the incremental pass still has to hear
+        // that these inputs changed.
         model.note_layout_frame_write(h);
-        // Right-flush each double line: right edge = left.right + (maxw − left.width)
-        // = frame.left + pad + maxw = the text inset's right.
+        // Right-flush each double line: left.right + (maxw - left.width) is the text inset.
         for (i, (l, r)) in rows.iter().enumerate() {
             if r.is_none() {
                 continue;
@@ -839,19 +655,15 @@ pub(super) fn layout_tooltips(model: &mut Model) {
     }
 }
 
-/// Advance every fading tooltip (called from [`super::UiScript::tick`], the ScrollingMessage/
-/// Cooldown pattern): alpha ramps 1→0 over [`TOOLTIP_FADE_SECS`]; at the end the tooltip hides
-/// for real (owner dropped, content cleared, `OnTooltipCleared` fired).
+/// Advances every fading tooltip: alpha ramps from 1 to 0 over [`TOOLTIP_FADE_SECS`], then the
+/// full hide.
 pub(super) fn tick_fades(lua: &Lua) {
     let t = now(lua);
     let mut ramping: Vec<(FrameHandle, f32)> = Vec::new();
     let mut finished: Vec<FrameHandle> = Vec::new();
     {
         let model = lua.app_data_ref::<Model>().expect("model app_data");
-        // The arena's tooltip registry (1634) — this runs every tick, and the roster it used to
-        // walk is ~4000 entries at a corpus UI. The `frame_to_id` gate is kept: `hide_tooltip`
-        // below writes layout, and a frame outside the resolve's roster takes the ledger's
-        // conservative branch.
+        // Roster-gated as in `layout_tooltips`, since `hide_tooltip` below writes layout.
         for &h in model.arena.tooltip_kinds() {
             if !model.frame_to_id.contains_key(&h) {
                 continue;
@@ -866,7 +678,7 @@ pub(super) fn tick_fades(lua: &Lua) {
                 continue;
             };
             if !frame.shown {
-                finished.push(h); // hidden mid-fade by other means — just tidy the state
+                finished.push(h); // hidden mid-fade by other means: just tidy the state
                 continue;
             }
             let a = 1.0 - ((t - start) / TOOLTIP_FADE_SECS) as f32;
diff --git a/crates/benilla-ui/src/script/tooltip/verbs.rs b/crates/benilla-ui/src/script/tooltip/verbs.rs
index 1c708869..b83607ea 100644
--- a/crates/benilla-ui/src/script/tooltip/verbs.rs
+++ b/crates/benilla-ui/src/script/tooltip/verbs.rs
@@ -1,7 +1,4 @@
-//! The GameTooltip Lua verb table — [`install`] registers the widget methods (SetOwner /
-//! AddLine / AddDoubleLine / SetText / ClearLines / SetMinimumWidth / SetPadding / FadeOut /
-//! IsOwned / NumLines / the anchor law) over the parent module's line-pool mechanics, then
-//! chains the item/unit content builders' method sets.
+//! The GameTooltip Lua methods over the parent module's line pool, plus the content builders'.
 
 use mlua::{Lua, Table, Value, Variadic};
 
@@ -21,49 +18,25 @@ use super::{
 pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
     let m = lua.create_table()?;
 
-    // SetOwner(owner, anchorType [, x, y]) — the binding `0x5310d0` and the core it calls,
-    // `0x52ffe0(owner_region, mode, dx, dy)`: SetAlpha(255) (`0x52fff4`), fade-disarm
-    // (`0x530002`), `+0x314 = owner` (`0x53000c`), the mode (`0x530031`), the offsets, then the
-    // anchor-apply `0x52fe90`. We clear the content too, because the engine fires
-    // OnTooltipCleared: a fresh owner never inherits the last hover's lines or money.
+    // SetOwner(owner, anchorType [, x, y]): the binding `0x5310d0` calls the core `0x52ffe0`,
+    // which sets full alpha (`0x52fff4`), disarms the fade, stores the owner (`0x53000c`), mode
+    // and offsets, then applies the anchor (`0x52fe90`). The content clears and OnTooltipCleared
+    // fires, so a new owner never inherits the last hover's lines or money.
     //
-    // **The omitted / unreadable / unrecognised anchorType is mode 0 = ANCHOR_LEFT, silently.**
-    // `0x53120d` writes 0 into the binding's local mode *before any compare runs*; `0x531214`'s
-    // `lua_isstring` gate jumps the whole `SStrCmpI` chain when arg 3 is absent, nil, boolean or a
-    // table; the chain's last `jne` reaches the same join untouched; and `[0x531221, 0x53133a)`
-    // contains no `luaL_error` (earned zero, positive-controlled against the five this function
-    // *does* have in its owner-validation prologue). `0x5313c0` then hands that local to the core.
+    // A missing, non-string or unknown anchorType is mode 0, ANCHOR_LEFT, with no error: the
+    // binding's local starts at 0 (`0x53120d`). The core's pre-store of 7 (`0x530012`) survives
+    // only a NULL owner, the un-own path (`0x530a60`) of every hide.
     //
-    // The core's own `mov [+0x318],7` at `0x530012` is **not** that default: it is an
-    // unconditional pre-store that `0x530031` overwrites with the argument, and it survives only
-    // when the owner pointer is NULL — the un-own path `0x530a60` takes on every hide.
-    //
-    // **The anchor-apply clears, and only ANCHOR_PRESERVE escapes it** (`0x52fe90` read
-    // contiguously): a NULL owner returns at `0x52fe9e`; **mode 8 returns at `0x52fead`, before
-    // the clear**; then `0x52feb8` tests the caller's arg1, which `0x530037` always passes as
-    // **1** (`0x53002d push 0x1`), so the mode-7 skip at `0x52feba` is dead on this path and
-    // `0x52fec2 call 0x767ed0` (ClearAllPoints) runs for **every mode 0..7**; and only then does
-    // `0x52fed0 ja` send 6 and 7 home while 0..5 take the SetPoint jump table `0x52ffbc`.
-    //
-    // So the three arms below are: 0..5 clear-and-point, **6 and 7 clear**, 8 nothing. Decision
-    // 2176 replaces 2142's open thread 1, which had it backwards on both counts — it read the
-    // core's pre-store as the Lua default and read "no SetPoint" as "no clear"; the bytes refute
-    // both.
+    // The anchor apply returns first for ANCHOR_PRESERVE (8, `0x52fead`), then clears all points
+    // (`0x767ed0` at `0x52fec2`) for modes 0..7; modes 0..5 then set a point (`0x52ffbc`).
     m.set(
         "SetOwner",
         lua.create_function(
             |lua, (this, owner, anchor, x, y): (Table, Table, Value, Option<f32>, Option<f32>)| {
                 let h = frame_handle_of(lua, &this)?;
                 let owner_h = frame_handle_of(lua, &owner)?;
-                // The gate is `lua_isstring 0x6f3510`, whose whole body is `lua_type` then
-                // `cmp eax,4 / cmp eax,3` — LUA_TSTRING or LUA_TNUMBER and nothing else — so the
-                // anchor argument is read the reference's way, by COERCION, and a boolean, table,
-                // function or userdata is indistinguishable from absent. Taking it as
-                // `Option<String>` made mlua's converter the gate instead, and mlua raises on a
-                // table: `Questie`'s `Tooltip:SetOwner(this, this)` (QuestieNotes.lua, the map-note
-                // hover) died with "bad argument #3: error converting Lua table to String" on a
-                // call the reference completes silently at mode 0. This function's doc comment has
-                // stated the law since 2176 — only the signature disagreed.
+                // The gate is `lua_isstring` (`0x6f3510`): a string or number is read, and any
+                // other type counts as absent rather than raising.
                 let anchor = optional_string(lua, &anchor);
                 {
                     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -71,17 +44,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                     full_alpha(&mut model, h);
                     tip_mut(&mut model, h)?.owner = Some(owner_h);
                     let owner_id = model.frame_id(owner_h);
-                    // The anchor mode is resolved ONCE, into the reference's own enum, and both
-                    // the placement below and `GetAnchorType`'s answer are taken from that one
-                    // value — so the plate and the getter can never tell different stories.
-                    //
-                    // Absent, unreadable and unrecognised all land on **ANCHOR_LEFT**, which is
-                    // the binding's zero-initialised local (`0x53120d`) surviving the
-                    // `lua_isstring` gate or the compare chain, with no raise. The warning on the
-                    // unrecognised leg is ours and stays: the reference is silent, but nothing
-                    // observable to Lua changes, and this exact warning is what made
-                    // `ANCHOR_CURSOR` visible as a real ninth mode nine corpus files ask for
-                    // rather than a typo (2142's open thread 2).
+                    // Resolved once: the placement and `GetAnchorType` both read this value. The
+                    // warning on an unknown name is ours; the reference is silent, and Lua sees no
+                    // difference.
                     let anchor = match anchor
                         .as_deref()
                         .map(str::to_ascii_uppercase)
@@ -117,23 +82,10 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                             None
                         }
                     };
-                    // **Modes 6 and 7 CLEAR and stop; mode 8 does neither.** `0x52fe90` reaches
-                    // `0x52fec2 call 0x767ed0` for every mode 0..7 — the mode-7 skip beside it is
-                    // gated on an arg1 that `SetOwner`'s core always passes as 1 — and mode 8
-                    // returned two compares earlier, at `0x52fead`, without touching anything.
-                    //
-                    // For ANCHOR_NONE that clear is what makes `GameTooltip_SetDefaultAnchor`
-                    // (`SetOwner(owner, "ANCHOR_NONE")` → `ClearAllPoints()` → `SetPoint(...)`,
-                    // the path of every action-bar hover) safe: a stale owner anchor cannot win
-                    // the frame the caller forgets to re-point. For ANCHOR_CURSOR it is the
-                    // opening move of a placement the per-frame update finishes
-                    // (`script::tooltip::cursor_anchor`).
-                    //
-                    // Dropping every anchor is a retarget to the EMPTY target set, and it names
-                    // its node like any other (decision 1625). It matters here more than
-                    // anywhere: left on the conservative touch, this line was a whole-graph
-                    // derivation on every action button the cursor crossed and on nothing else —
-                    // exactly the shape the director's recorder reported (decision 1630).
+                    // Modes 6 and 7 clear all points and stop. The clear lets
+                    // `GameTooltip_SetDefaultAnchor` (GameTooltip.lua:76-77) set one point with no
+                    // stale owner anchor; mode 6 is then placed per frame by `cursor_anchor`. The
+                    // drop is a named retarget to no targets, not a conservative touch.
                     if matches!(anchor, TooltipAnchor::Cursor | TooltipAnchor::None) {
                         let dropped = match model.layout_inputs.get_mut(&h) {
                             Some(input) if !input.anchors.is_empty() => {
@@ -150,18 +102,13 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                         let new =
                             Anchor::new(own, owner_id, rel, x.unwrap_or(0.0), y.unwrap_or(0.0));
                         let input = model.layout_inputs.entry(h).or_default();
-                        // The no-op compare keeps the per-frame SetOwner idiom (the bag
-                        // hover's OnUpdate re-enter) from dirtying tier 1 by itself; the
-                        // content clear above already reports its own writes.
+                        // No-op when unchanged, so the bag hover's per-frame SetOwner does not
+                        // dirty the layout.
                         let same = input.anchors.len() == 1
                             && crate::script::object::anchor_bits_eq(&input.anchors[0], &new);
                         if !same {
-                            // The plate re-points at the button under the cursor, which moves
-                            // an EDGE — structural under 1388, and therefore a whole-graph
-                            // derivation on every bag slot and every spellbook button a hover
-                            // sweep crossed. It names its node now (decision 1625): the old
-                            // and new target lists are both right here, so the cached graph's
-                            // edges are re-pointed instead of thrown away.
+                            // A named retarget: the cached layout graph re-points this edge
+                            // instead of being rebuilt.
                             let old_targets: Vec<u32> =
                                 input.anchors.iter().map(|a| a.relative_to).collect();
                             input.anchors = vec![new];
@@ -174,14 +121,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             },
         )?,
     )?;
-    // GameTooltip:BenillaGetTooltipOwner() — **ours, and the prefix is what makes it honest.**
-    // 1.12 registers `IsOwned` (ask about ONE frame) and no getter at all, so there is no
-    // reference spelling for "which frame owns this plate" to be faithful to; a `GetOwner` here
-    // would be an unexplained superset an addon can feature-detect (1188, and the census that
-    // moved it, 2142). Under the `Benilla` prefix it is unreachable by accident from an addon
-    // that means to call a WoW function. Its one caller is the dev-only hover recorder
-    // (`benilla-app/src/hover_log.rs`), which needs the owner's NAME per frame so a trace reads
-    // the same names the director sees.
+    // GameTooltip:BenillaGetTooltipOwner(): not a 1.12 method (1.12 has only `IsOwned`); the dev
+    // hover recorder (`benilla-app/src/hover_log.rs`) reads the owner's name through it.
     m.set(
         "BenillaGetTooltipOwner",
         lua.create_function(|lua, this: Table| {
@@ -198,21 +139,10 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             }
         })?,
     )?;
-    // GetAnchorType() — ONE string, the mode the last SetOwner placed this plate by
-    // (`0x5313e0`, table `0x854198`, argc 1, arity 1, kinds `(string)`; it reads `[+0x318]` back
-    // through the 9-entry name table `0x531530`). The kinds column has no nil alternative and this
-    // does not answer one: a tooltip nothing has owned yet answers `"ANCHOR_NONE"`, which is
-    // [`TooltipAnchor`]'s default and the same mode the reference's own SetOwner core falls back to.
-    //
-    // Two corpus callers, both unguarded, both raising against this VM until now, and they are the
-    // two shapes the verb has: `pfUI/modules/tooltip.lua:97` compares against ONE mode
-    // (`if GameTooltip:GetAnchorType() == "ANCHOR_NONE" then` — its OnShow reposition, so an equality
-    // on the exact reference spelling), and `_Nameplates/_Nameplates.lua:479` compares against a
-    // mode it computed (`if GameTooltip:GetAnchorType() ~= Anchor then GameTooltip:SetOwner(Column,
-    // Anchor) end` — a re-SetOwner suppressor, so an answer that never equals what SetOwner was
-    // given would re-own the plate on every OnUpdate). Both need the string to round-trip through
-    // the setter verbatim, which is why the mode is resolved once up there and read straight back
-    // here rather than re-derived from the plate's anchors.
+    // GetAnchorType(): the last SetOwner's mode by name (`0x5313e0`, name table `0x531530`), never
+    // nil; a never-owned tooltip answers "ANCHOR_NONE". The reference also answers it after any
+    // hide, whose un-own leaves mode 7; this keeps the last mode. Addons compare it with what they
+    // passed to SetOwner, so the name must round-trip.
     m.set(
         "GetAnchorType",
         lua.create_function(|lua, this: Table| {
@@ -220,9 +150,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(anchor.name())
         })?,
     )?;
-    // IsOwned(frame) — the hover re-enter loop's gate (ref ContainerFrame.lua OnUpdate): true
-    // only while `frame` is the live owner; the owner drops on hide, so a hidden tooltip never
-    // resurrects from a stale OnUpdate.
+    // IsOwned(frame): the hover loop's OnUpdate gate (`ContainerFrame.lua:657`); the owner drops
+    // on hide, so a stale OnUpdate never brings a hidden tooltip back.
     m.set(
         "IsOwned",
         lua.create_function(|lua, (this, frame): (Table, Table)| {
@@ -232,13 +161,10 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetText(text, r, g, b, alpha, textWrap) — the byte-pinned `0x531b90` signature (alpha is
-    // a REAL parsed argument here, its own isnumber gate, default 1.0 — unlike AddLine's forced
-    // opaque; GameTooltip_AddNewbieTip passes `(text, r, g, b, 1, 1)`). `text` is REQUIRED — a
-    // non-string raises the binding's own 'Usage: SetText("text" [, color])' FrameScript error
-    // and adds no line. No colour args → the engine default GOLD. Clears, writes line 1,
-    // SHOWS — the corpus never calls Show after SetText (PaperDoll's empty-slot text relies
-    // on it).
+    // SetText(text, r, g, b, alpha, wrap) (`0x531b90`): alpha has its own number gate, default 1,
+    // and a text that is neither string nor number raises the binding's usage error. It clears,
+    // writes line 1 and shows: the empty-slot hover calls no Show after it
+    // (PaperDollFrame.lua:747).
     m.set(
         "SetText",
         lua.create_function(|lua, (this, args): (Table, Variadic<Value>)| {
@@ -269,27 +195,10 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // AppendText(text) — `0x531e30`. The reference's bag/bar tooltips build a title with SetText
-    // and then hang the keybinding on the end of that same line rather than adding a second one:
-    //
-    //     GameTooltip:SetText(TEXT(BACKPACK_TOOLTIP), 1.0, 1.0, 1.0);
-    //     if ( GetBindingKey("TOGGLEBACKPACK") ) then
-    //         GameTooltip:AppendText(" "..NORMAL_FONT_COLOR_CODE.."("..key..")"..FONT_COLOR_CODE_CLOSE)
-    //     end
-    //
-    // — ContainerFrame.xml l.188-206 (the bag window's portrait button, one arm per bag id) and
-    // MainMenuBarBagButtons.xml l.96 / .lua l.91 (the bar's). Both files run off the player's own
-    // chain (1751), so those are live call sites in this VM, not transcriptions we could adjust.
-    //
-    // LINE 1's left cell, appended in place, keeping its colour: the escape codes in the argument
-    // are what colour the suffix, which only works if it lands INSIDE an existing line. A tooltip
-    // with no lines yet is a no-op rather than a raise — the reference's own callers always SetText
-    // first, and the empty case is unconfirmed in the binary.
-    //
-    // INFERRED, unconfirmed in the binary: that `0x531e30` targets line 1 rather than the last line
-    // added. Every attested call site sets exactly one line before appending, so the two readings
-    // are indistinguishable from the corpus alone; line 1 is chosen because the reference's own
-    // name for the target is `GameTooltipTextLeft1`. Re-measure is unconditional either way.
+    // AppendText(text) (`0x531e30`): appends to line 1's left cell in place, keeping its colour,
+    // and does nothing with no lines, as the reference's body does (`0x5305b0`, line 1 at
+    // `0x5305cc`). The bag tooltips hang a keybinding on their SetText title with it
+    // (ContainerFrame.xml:198, MainMenuBarBagButtons.lua:91).
     m.set(
         "AppendText",
         lua.create_function(|lua, (this, text): (Table, Value)| {
@@ -312,10 +221,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // AddLine(text [, r, g, b [, wrap]]) — positional; the corpus' archaic `(text, "", r, g, b)`
-    // shape has a non-number in the r-slot, so the real binding drops the colour tail and the
-    // line renders the default GOLD (the ref's zone/taxi/repair tooltips — director-matched).
-    // Appends without showing.
+    // AddLine(text [, r, g, b [, wrap]]): positional, and appends without showing; the
+    // `(text, "", r, g, b)` shape has a non-number r-slot, so it renders default gold.
     m.set(
         "AddLine",
         lua.create_function(|lua, (this, args): (Table, Variadic<Value>)| {
@@ -324,11 +231,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             append_line(lua, &this, (text, color), None, wrap)
         })?,
     )?;
-    // AddDoubleLine(textL, textR, rL, gL, bL, rR, gR, bR [, wrap]) — the two-column line
-    // (slot|type, damage|speed), byte-pinned `0x531840`: each side's colour gates on ITS OWN
-    // r-slot isnumber (default gold, g/b ungated → 0.0, alpha forced opaque), and the wrap arg
-    // is dead weight — the core forces wrap=0 whenever the right text is non-empty. The right
-    // column right-flushes in the layout pass.
+    // AddDoubleLine(textL, textR, rL, gL, bL, rR, gR, bR [, wrap]) (`0x531840`): each side's
+    // colour gates on its own r-slot. The core forces wrap off when the right text is non-empty;
+    // this never wraps.
     m.set(
         "AddDoubleLine",
         lua.create_function(
@@ -361,19 +266,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         "NumLines",
         lua.create_function(|lua, this: Table| with_tip(lua, &this, |t| t.num_lines as i64))?,
     )?;
-    // AddFontStrings(left, right) — adopt two caller-made FontStrings as the next line pair
-    // (`0x530c40`; the parent module's doc already names it as how the real class grows past its
-    // template's 30 declared pairs).
-    //
-    // The scan-tooltip idiom, and the reason this landed with the font-object work rather than
-    // separately: `Gratuity-2.0.lua:56-59` builds its whole 30-line hidden tooltip out of
-    // `tt:CreateFontString()` + `:SetFontObject(GameFontNormal)` + `tt:AddFontStrings(l, r)`, so
-    // publishing the font globals only moved that library's death one line down. Five corpus addons
-    // sit behind those four lines.
-    //
-    // The pair is placed exactly as an engine-grown one (hidden, left/right justified, hung off the
-    // previous line) — the layout pass owns line geometry either way — but the regions' FONTS are
-    // left alone, since choosing them is the entire point of the caller doing this by hand.
+    // AddFontStrings(left, right) (`0x530c40`): adopts two caller-made FontStrings as the next
+    // line pair, placed like an engine-grown pair but keeping the caller's fonts.
     m.set(
         "AddFontStrings",
         lua.create_function(|lua, (this, left, right): (Table, Table, Table)| {
@@ -418,31 +312,31 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                 d.justify.set_h(crate::script::JustifyH::Right);
                 d.anchors = vec![Anchor::new(Point::Right, left_id, Point::Right, 0.0, 0.0)];
             }
-            model.touch_layout(); // two line rows entered the layout graph (decision 0740)
+            model.touch_layout(); // two line rows entered the layout graph
             let t = tip_mut(&mut model, h)?;
             t.left_lines.push(lh);
             t.right_lines.push(rh);
             Ok(())
         })?,
     )?;
-    // SetMinimumWidth(w) — a floor on the auto-sized width (the ref's SetTooltipMoney calls it
-    // with the money row's width so coins never overhang the plate).
+    // SetMinimumWidth(w): a floor on the auto-sized width (`SetTooltipMoney` passes the money
+    // row's, GameTooltip.lua:91).
     m.set(
         "SetMinimumWidth",
         lua.create_function(|lua, (this, w): (Table, f32)| {
             with_tip(lua, &this, |t| t.min_width = w.max(0.0))
         })?,
     )?;
-    // SetPadding(w) — extra auto-size width (ref ItemRefTooltip OnLoad: SetPadding(16) keeps the
-    // corner close button off the text). A frame property — persists across content clears.
+    // SetPadding(w): extra auto-size width that survives a content clear (ItemRefTooltip's 16
+    // keeps its close button off the text, ItemRef.xml:40).
     m.set(
         "SetPadding",
         lua.create_function(|lua, (this, w): (Table, f32)| {
             with_tip(lua, &this, |t| t.padding = w.max(0.0))
         })?,
     )?;
-    // FadeOut() — the world-mouseover loss ramp (alpha 1→0 over TOOLTIP_FADE_SECS, INTERIM
-    // constant, then a real hide). Fresh content or Show cancels it.
+    // FadeOut(): alpha ramps to 0 over `TOOLTIP_FADE_SECS`, then the full hide; new content or
+    // Show cancels it.
     m.set(
         "FadeOut",
         lua.create_function(|lua, this: Table| {
@@ -454,28 +348,10 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             })
         })?,
     )?;
-    // Show/Hide — shadow the shared pair (kind tables resolve first) to keep the tooltip's
-    // state honest: Show cancels a fade at full alpha; Hide drops the owner + content and fires
-    // OnTooltipCleared (the ref clears its money row through exactly that script).
-    // Show is an EXISTENCE GATE, not a plain show. `0x530a80` — the CGameTooltip override of
-    // `vtbl+0x88`, which is the slot a Lua `:Show()` lands in (the generic widget Show path
-    // `0x7a3350` sets `[+0xd0]=1` then calls slot `+0x88`) — shows only when BOTH `+0x314` (the
-    // owner) and `+0x31c` (the line count) are non-zero; otherwise it calls its own `vtbl+0x84`
-    // effective-hide `0x530a60`, which is the SetOwner core with a NULL owner, so the plate is
-    // hidden AND un-owned and OnTooltipCleared fires. Evaluated at Show time only — it is never a
-    // visibility poll (`0x530a80`).
-    //
-    // Without the gate an addon that reaches `Show()` having added no lines leaves a VISIBLE
-    // empty plate — and, because `layout_tooltips` skips a zero-line plate rather than collapsing
-    // it, one still wearing the last hover's width and height. That is what `Questie`'s tracker
-    // does: `QuestieTracker.lua`'s quest-button OnEnter has a dead zone between its two arms (an
-    // in-progress quest whose objective text IS in its database adds nothing) and then calls
-    // `Tooltip:Show()` unconditionally. On the reference `0x530a80` swallows it; we drew the
-    // empty plate.
-    //
-    // `show_or_hide_empty` is the same law for the app-answered content asks, and deliberately
-    // does NOT un-own (its re-enter repaint needs the owner). This path is the reference's own,
-    // so it takes the reference's full effective-hide.
+    // Show and Hide shadow the shared pair. Show (`0x530a80`, the override the generic Show at
+    // `0x7a3350` calls) shows only a plate with an owner and at least one line, checked at Show
+    // time only; otherwise it takes the full hide (`0x530a60`): un-owned, cleared,
+    // OnTooltipCleared fired. Hide is the full hide.
     m.set(
         "Show",
         lua.create_function(|lua, this: Table| {
@@ -503,17 +379,10 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The item content channels (BenillaSetItemById/SetBagItem/SetMerchantItem/SetBuybackItem) live in
-    // their own module — the one shared renderer + the red usable law (decision 0274 P1).
+    // The content methods: items, spells and auras, talents, units.
     crate::script::tooltip_item::install_methods(lua, &m)?;
-    // The spell/aura/action content channels (SetSpell/SetShapeshift/SetPlayerBuff/SetAction) —
-    // the verified spell-builder law (decision 0274 P2, grounded by 0276).
     crate::script::tooltip_spell::install_methods(lua, &m)?;
-    // The talent channel (SetTalent) — the spell builder with the talent interleave
-    // (decision 0304).
     crate::script::talent::install_tooltip_method(lua, &m)?;
-    // The unit content channel (SetUnit + the world-mouseover drivers) — the verified unit law
-    // (decision 0274 P3, grounded by 0276).
     crate::script::tooltip_unit::install_methods(lua, &m)?;
 
     lua.set_named_registry_value(REG_TOOLTIP_METHODS, m)?;
diff --git a/crates/benilla-ui/src/script/tooltip_item/mod.rs b/crates/benilla-ui/src/script/tooltip_item/mod.rs
index 7d05f696..02dc756e 100644
--- a/crates/benilla-ui/src/script/tooltip_item/mod.rs
+++ b/crates/benilla-ui/src/script/tooltip_item/mod.rs
@@ -1,54 +1,14 @@
-//! The engine **item-tooltip renderer** (decision 0274 P1) — the one line law every item hover
-//! renders through, mirroring the real client's single shared C++ renderer (`0x52b650`, behind
-//! 8 of the 9 `Set*Item` bindings). The entry methods
-//! (`SetBagItem`, `SetMerchantItem`, `SetBuybackItem`, and the prefixed `BenillaSetItemById` —
-//! ours, because 1.12 has no id-keyed door onto the shared renderer) register into the
-//! GameTooltip kind table beside the widget verbs ([`super::tooltip`]).
+//! The engine item-tooltip renderer: every item hover renders through one line law, as 8 of the
+//! reference's 9 `Set*Item` bindings share the builder `0x52b650`. The methods register into the
+//! GameTooltip kind table beside the widget verbs ([`super::tooltip`]). Every family's order,
+//! gate and colour is the reference's, and every sentence is a key resolved off the player's own
+//! `GlobalStrings.lua` at render time. Red (`0xc0d390`, `0xffff2020`) marks unmet requirements,
+//! LOCKED, broken durability and "Already known"; the name never recolors.
 //!
-//! **The line law is BYTE-VERIFIED** — the 0274 §5 verdict on `0x52b650`'s emission order:
-//! every family's order, gate, and color pointer is the binary's, and every sentence is a KEY
-//! resolved off the player's own `GlobalStrings.lua` at render time (decision 2045). Not yet
-//! built (feeds pending, laws recorded): the instance families (soulbound override, enchants,
-//! made-by, live durability, cooldown-remaining).
-//! Residual INTERIMs cited inline: the dual-wield/off-hand proficiency exception
-//! (`0x5eab70`), the type cell's override red, the set-owned count source.
-//!
-//! **Compare mode** (0274 P4, re-based by 2202, scoped back to the reference by 2210, and corrected
-//! to match the reference by 2216): `SetInventoryItem` on an ARMED shopping tooltip renders the
-//! equipped item's ORDINARY tooltip plus ONE extra line, first — the gray "Currently Equipped"
-//! (`[arg+0x18]≠0`). That is the entire difference. The builder's other flag, p4 `[arg+0x14]`, *is*
-//! a compact mode (white name, stat body jumped, early-return at `0x52e14c`) — but the two compare
-//! call sites pass it **zero** (`0x5362c0`, `0x53602a`), so a shopping plate shows a
-//! quality-colored name and the full body, and a client that abbreviates here is wrong. **Nothing
-//! in this engine seats a shopping plate**: the two callers that arm this mode are
-//! [`compare_against_worn`]'s own bindings — `SetMerchantCompareItem` and `SetAuctionCompareItem` —
-//! and the FrameXML that calls them (`MerchantFrame.xml:63-80`, `AuctionFrame`) owns the plates'
-//! geometry and lifetime, exactly as in 1.12.1. There is no hover compare in the reference at all:
-//! `SHOW_COMPARE_TOOLTIP` has zero fire sites in the whole image (its only two dynamic fire sites,
-//! `0x49211a`/`0x49630d`, can never produce event 377), so `PaperDollFrame.lua`'s slot listener is
-//! dead code there.
-//!
-//! **`nameOnly`** (p4 `[arg+0x14]`, the flag 2216 had tangled with the header; built by 2224): the
-//! builder's compact mode, and a census of the reference's call sites found exactly one door onto
-//! it — this module's `SetInventoryItem`, third argument, a number `> 0`. It is what the image's
-//! own usage string `0x8552dc` calls it. No stock FrameXML caller passes it (all 8 sites are
-//! two-argument), so it is addon surface; it is nonetheless live code, and the mode is **trimmed,
-//! not bare** — the bind/lock region and the stat body are jumped and the tail is cut, but the
-//! slot/type cell, durability, every requirement line and the spell triggers all still print. Both
-//! flags ride in [`render::BuilderFlags`], a struct precisely so they cannot be collapsed again.
-//!
-//! **The red "you can't use this" law** (the director's explicit ask): the AddLine colour pointer
-//! `0xc0d390` is `0xffff2020`, applied to requirement lines the ACTIVE player fails (level,
-//! class/race lists, skill rank, required spell), to LOCKED, to broken durability, and
-//! unconditionally to "Already known"; the NAME never recolors. Compared against
-//! [`super::PlayerReqState`] + the spellbook.
-//!
-//! The sell-price money row is the byte-verified law: only a REAL-INSTANCE source (`SetBagItem`)
-//! while the merchant window is open and repair mode is off — the engine computes
-//! `SellPrice × stack` and fires the `OnTooltipAddMoney` script; FrameXML renders the coins
-//! (`SetTooltipMoney`). A zero sell price in that context prints `ITEM_UNSELLABLE`
-//! (`0x854a74`, pushed at `0x52e4a3`). Template sources (`SetMerchantItem`/`BenillaSetItemById`/quest
-//! rows) never show money, per the same law.
+//! Stock FrameXML seats the shopping plates (`MerchantFrame.xml:63-80`,
+//! `Blizzard_AuctionUI.lua:1078`). There is no hover compare: `SHOW_COMPARE_TOOLTIP` has no fire
+//! site (`0x49211a` and `0x49630d` never produce event 377), so `PaperDollFrame.lua`'s listener
+//! for it is dead code.
 
 use mlua::{Lua, MultiValue, Table, Value};
 
@@ -62,17 +22,11 @@ mod render;
 use names::{quality_color, GRAY, WHITE};
 use render::{render_view, BuilderFlags};
 
-/// The compare tooltips' shared body — what `SetMerchantCompareItem 0x536080` and
-/// `SetAuctionCompareItem 0x535d70` both run once their wrapper has an offered template and a
-/// re-based `offset` (`0x5d9f30` gates the class test): walk the offered type's candidate slots
-/// (`0x809200[InventoryType]`), skipping EMPTY slots without decrementing and slots whose
-/// worn item's CLASS differs, until `offset` occupied matches have been passed; then fill the
-/// ordinary EQUIPPED-item tooltip with the compare header on — the FULL body (`p4 = 0`) plus one
-/// gray `CURRENTLY_EQUIPPED` line (`p5 = 1`), by arming the `equipped_header_armed` latch and running
-/// `SetInventoryItem`, which is what the reference does too:
-/// `0x536080` calls the ordinary item builder `0x52b650` with the header flag set. The NUMBER 1 on
-/// success; nil on a miss, which does NOT clear the tooltip (the reference's nil exit touches
-/// nothing else).
+/// The body both compare bindings run (`0x536080`, `0x535d70`): walk `0x809200[InventoryType]`'s
+/// slots, skipping empty ones uncounted and ones whose worn item's class differs (`0x5d9f30`),
+/// until `left` matches have passed; then run `SetInventoryItem` there with the header latch armed,
+/// as `0x536080` calls `0x52b650` with p4 = 0, p5 = 1. The number 1, or nil on a miss, which leaves
+/// the tooltip untouched.
 fn compare_against_worn(
     lua: &Lua,
     this: &Table,
@@ -88,7 +42,7 @@ fn compare_against_worn(
                 .inv_slot("player", slot as usize)
                 .filter(|s| s.item_id != 0)
             else {
-                continue; // empty: skipped WITHOUT decrementing
+                continue; // an empty slot is not counted
             };
             let same_class = model
                 .item_templates
@@ -119,8 +73,7 @@ fn compare_against_worn(
     Ok(Value::Integer(1))
 }
 
-/// Look up the store; a miss records the ask (the app sends `CMSG_ITEM_QUERY` and pushes back —
-/// the hover's re-enter loop repaints on arrival).
+/// The cached template; a miss records the ask, and the hover's re-enter loop repaints on arrival.
 fn view_of(lua: &Lua, item_id: u32) -> Option<ItemTemplateView> {
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
     let v = model.item_templates.get(&item_id).cloned();
@@ -130,10 +83,8 @@ fn view_of(lua: &Lua, item_id: u32) -> Option<ItemTemplateView> {
     v
 }
 
-/// The enchant lines a **random-suffix roll** contributes, out of the pushed roll table — the
-/// reference's `0x52b7bf` copy of the suffix row's five ids into enchant slots 2..6, which every
-/// block-supplying source with no item object relies on (loot, links, auction rows, the roll
-/// window). `0`, or an id the table doesn't name, contributes nothing.
+/// A random-suffix roll's enchant lines: the reference copies the suffix row's five ids into
+/// enchant slots 2..6 (`0x52b7bf`) for a block source with no item object.
 fn roll_enchants(lua: &Lua, random_property_id: u32) -> Vec<crate::script::EnchantView> {
     let model = lua.app_data_ref::<Model>().expect("model app_data");
     model
@@ -143,16 +94,13 @@ fn roll_enchants(lua: &Lua, random_property_id: u32) -> Vec<crate::script::Encha
         .unwrap_or_default()
 }
 
-/// The bracketed name out of an `|Hitem:…|h[Name]|h` link (the container slot's own display
-/// name — the miss-path fallback line's source).
 fn link_name(link: &str) -> Option<&str> {
     let start = link.find('[')? + 1;
     let end = link[start..].find(']')? + start;
     Some(&link[start..end])
 }
 
-/// Fire the engine→Lua money hand-off (`OnTooltipAddMoney(copper)` — the byte-verified protocol:
-/// the engine computes, FrameXML's `SetTooltipMoney` renders).
+/// Fire `OnTooltipAddMoney(copper)`: the engine computes, FrameXML's `SetTooltipMoney` draws.
 fn fire_add_money(lua: &Lua, h: crate::widget::FrameHandle, copper: u64) {
     let id = {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -170,15 +118,6 @@ fn fire_add_money(lua: &Lua, h: crate::widget::FrameHandle, copper: u64) {
     }
 }
 
-/// The `|Hitem:` payload's numeric fields — the full escaped shape
-/// (`|cff…|Hitem:2947:0:584:0|h[Name]|h|r`) or a bare `item:2947`.
-///
-/// The four are `(item id, enchant id, randomPropertyId, uniqueId)` — the reference's own link
-/// format `"%s|Hitem:%d:%d:%d:%d|h[%s]|h%s"` (`0x8549c8`), and `SetHyperlink 0x532181` parses them
-/// straight into the tooltip's instance block: token 1 → enchant slot 0 (`+0x3d0`), **token 2 →
-/// `+0x424`, the roll** (which `0x52b7bf` then expands into slots 2..6), token 3 → `+0x420`, which
-/// nothing reads. Missing fields read `0`, like the bare `item:id` shape an addon may pass.
-/// The `enchant:<spellId>` of an enchant hyperlink, or `None` for any other link.
 fn hyperlink_enchant_spell(link: &str) -> Option<u32> {
     let at = link.find("enchant:")? + 8;
     let tail = &link[at..];
@@ -201,8 +140,7 @@ fn hyperlink_item_fields(link: &str) -> Option<(u32, u32, u32)> {
     (item_id != 0).then_some((item_id, enchant_id, random_property_id))
 }
 
-/// The shared id-keyed render (`BenillaSetItemById`/`SetHyperlink`): template hit → the full line law
-/// (+ the compare arm when this is the main GameTooltip); miss → the ask + a name-only line.
+/// The id-keyed render; on a miss, the ask and a name-only line, as `SetBagItem`'s miss path.
 fn render_by_id(
     lua: &Lua,
     this: &Table,
@@ -236,7 +174,6 @@ fn render_by_id(
     Ok(())
 }
 
-/// The quest-item hover: the row's item by id, or an empty tooltip when the row is not there.
 fn set_quest_item_view(
     lua: &Lua,
     this: &Table,
@@ -256,11 +193,8 @@ fn set_quest_item_view(
     }
 }
 
-/// The paperdoll slots an item of this InventoryType equips into (the 1.12
-/// `GetInventorySlotInfo` slot ids) — the compare drive's candidate slots. Two-slot families
-/// (rings, trinkets, one-hand weapons, and a two-hander displacing both hands) can fill both
-/// shopping plates. Twin of the app-side `ui_items::find_equip_slot` (the equip-click fit rule) —
-/// one law, two consumers.
+/// An InventoryType's compare candidate slots, as `GetInventorySlotInfo` ids: the reference's
+/// mask table `0x809200[InventoryType]`.
 fn equip_slots_for(inventory_type: u32) -> &'static [u32] {
     match inventory_type {
         1 => &[1],             // head
@@ -280,12 +214,8 @@ fn equip_slots_for(inventory_type: u32) -> &'static [u32] {
         13 => &[16, 17],       // one-hand
         21 => &[16],           // main hand
         14 | 22 | 23 => &[17], // shield / off-hand weapon / held
-        // Two-hand: **main hand ONLY**, which is not the obvious answer. A 2H displaces both
-        // hands when equipped, and this table was written `[16, 17]` on that reasoning. The
-        // reference's own mask disagrees: `0x809200[17]` is `0x8000`, bit 15, main hand alone.
-        // It is a COMPARE-CANDIDATE table, not an
-        // occupancy one — the question it answers is "which worn item is this offering to
-        // replace", and for a two-hander that is the weapon in your main hand.
+        // Two-hand: main hand only, though a two-hander displaces both: `0x809200[17]` is
+        // `0x8000`, bit 15.
         17 => &[16],
         15 | 25 | 26 | 28 => &[18], // bow / thrown / wand-gun / relic
         _ => &[],
@@ -294,20 +224,10 @@ fn equip_slots_for(inventory_type: u32) -> &'static [u32] {
 
 /// Register the item content channels into the GameTooltip kind method table.
 pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
-    // GameTooltip:BenillaSetItemById(itemId [, fallbackName, fallbackQuality]) — the id-keyed
-    // hover (quest reward rows, loot rows).
-    //
-    // **Ours, and the `Benilla` prefix is what keeps it honest.** 1.12's nine `Set*Item` bindings
-    // all name a CONTAINER — a bag slot, a merchant row, a loot slot — because the reference's
-    // callers always have one; nothing there takes a bare item id. Ours do: the channels in this
-    // module reach [`render_by_id`] as a Rust call, but the ones that live in a sibling module
-    // (`tooltip_spell`'s action-bar item arm, `SetTrainerService`, `SetCraftSpell`) reach it
-    // through the wrapper table, and that needs a NAME. Spelling that name like a WoW function
-    // would be an unexplained superset an addon can feature-detect (1188; the census that moved
-    // it, 2142); under the prefix it is unreachable by accident from an addon that means to call
-    // a WoW function, and no addon has reason to call it at all.
-    //
-    // Template source: no money row, per the byte-verified sell-price law.
+    // GameTooltip:BenillaSetItemById(itemId [, fallbackName, fallbackQuality]). Not a 1.12 verb,
+    // whose `Set*Item` bindings all name a container: sibling modules' item hovers (the action
+    // bar's, `SetTrainerService`, `SetCraftSpell`) reach `render_by_id` by this name through the
+    // wrapper table, and the prefix keeps it off the 1.12 surface.
     m.set(
         "BenillaSetItemById",
         lua.create_function(
@@ -317,13 +237,9 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         )?,
     )?;
 
-    // GameTooltip:SetQuestItem(type, index) / SetQuestLogItem(type, index) — the quest-giver
-    // panels' and the quest log's reward/choice/required hovers (stock QuestFrameTemplates.xml:148,
-    // QuestLogFrame.xml:113; bindings 0x533610 / 0x533760, 3 args with self, 0 returns). `type` is
-    // the same "choice" | "reward" | "required" key `GetQuestItemInfo` takes, `index` the 1-based
-    // slot; the item is rendered by id through the shared renderer, with the row's own name and
-    // quality as the fallbacks a template that has not arrived yet paints from. An unknown type or
-    // an out-of-range index shows nothing — the reference's tooltip stays empty too.
+    // GameTooltip:SetQuestItem(type, index) / SetQuestLogItem(type, index) (`0x533610`,
+    // `0x533760`; `QuestFrameTemplates.xml:148`, `QuestLogFrame.xml:113`), no returns. `type` is
+    // `GetQuestItemInfo`'s; an unknown type or index leaves the tooltip empty, as in the reference.
     m.set(
         "SetQuestItem",
         lua.create_function(|lua, (this, kind, index): (Table, String, usize)| {
@@ -357,16 +273,14 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GameTooltip:SetHyperlink(link) — the chat-link tooltip (ref ItemRef.lua's SetItemRef →
-    // ItemRefTooltip:SetHyperlink). Accepts the full escaped link or a bare "item:<id>";
-    // non-item links (player/spell/quest) have no tooltip surface yet and no-op.
+    // GameTooltip:SetHyperlink(link): the chat-link tooltip (`ItemRef.lua:60`). Takes an item
+    // link, escaped or a bare "item:<id>", or an enchant link; any other link does nothing.
     m.set(
         "SetHyperlink",
         lua.create_function(|lua, (this, link): (Table, String)| {
-            // The client's only other link kind: `|Henchant:<spellId>|h[name]|h`, the craft
-            // window's enchant link (`GetCraftItemLink`, 1973), which `SetHyperlink` consumes
-            // behind the same castUI gate its producer stands behind (`0x532243`) — the spell's
-            // own tooltip, by id.
+            // The only other link it takes, the craft window's `|Henchant:<spellId>|h[name]|h`
+            // (`GetCraftItemLink`): the spell's own tooltip, behind its producer's castUI gate
+            // (`0x532243`).
             if let Some(spell) = hyperlink_enchant_spell(&link) {
                 return super::tooltip_spell::set_spell_by_id(
                     lua,
@@ -386,16 +300,13 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 clear_content(&mut model, h);
             }
             fire_cleared(lua, h);
-            // A link is a **block source** (`SetHyperlink 0x532181` passes p6=1), so it never
-            // reaches the `<Random enchantment>` arm (`0x52cc33`) and it does show the roll's own
-            // lines — decision 0920's prose had that half backwards. The NAME comes off the link's
-            // own brackets: the sender's client built that text with the suffix already joined
-            // (`0x5d8b00` feeds the link builder), so re-deriving it would only invite the two to
-            // disagree.
-            //
-            // The link's ENCHANT field (slot 0, a permanent enchant like "Crusader") is parsed but
-            // not yet rendered: naming it needs the `SpellItemEnchantment` row, and no benilla
-            // surface writes that field into a link it composes today. A stated gap, not drift.
+            // The reference's format is `"%s|Hitem:%d:%d:%d:%d|h[%s]|h%s"` (`0x8549c8`), and
+            // `SetHyperlink` (`0x532181`) parses it into a block (p6=1): the enchant id to slot 0
+            // (`+0x3d0`), the roll to `+0x424` (expanded into slots 2..6 by `0x52b7bf`), the
+            // unique id to `+0x420`, unread; a missing field is 0. So a link shows its roll's
+            // lines, never the placeholder (`0x52cc33`). The name is the link's own, built with
+            // the suffix joined (`0x5d8b00`). The enchant id is parsed, not rendered: naming it
+            // needs its `SpellItemEnchantment` row, and no link benilla composes carries one.
             let inst = render::ItemInstance {
                 name: link_name(&link).map(str::to_string),
                 enchants: roll_enchants(lua, roll),
@@ -404,7 +315,6 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
             match view_of(lua, id) {
                 Some(v) => {
                     render_view(lua, &this, &v, BuilderFlags::default(), Some(&inst))?;
-                    // Unchanged from the `render_by_id` this leg used to share: a link dropped on
                 }
                 None => {
                     if let Some(name) = link_name(&link) {
@@ -423,46 +333,20 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GameTooltip:SetInventoryItem(unit, slot) → hasItem, hasCooldown, repairCost — the equipped-slot hover
-    // (paperdoll slots, buff-frame weapon enchants) and the shopping-compare listener's render
-    // (ref PaperDollFrame.lua:626). **Unit-keyed** through `Model::inv_slot`, the same router the
-    // `GetInventoryItem*` getters use: `"player"` from the self feed, the inspected token from the
-    // PUBLIC visible-item view (decision 0631 — the ref's inspect slot OnEnter calls exactly this,
-    // `InspectPaperDollFrame.xml:20`). An inspected item carries no durability/creator, so those
-    // lines simply don't render — the reference's own inspect tooltip shape. On an ARMED shopping
-    // tooltip this renders the byte law's compare shape; the arm is consumed either way.
-    // hasCooldown is nil INTERIM (no equipped-cooldown feed yet — its truthiness gates the ref's
-    // re-poll only).
-    //
-    // **THREE returns, not two.** The reference's own `PaperDollFrame.lua:741` reads
-    // `local hasItem, hasCooldown, repairCost = GameTooltip:SetInventoryItem("player", this:GetID())`
-    // — Blizzard's file, out of the shipped `patch.MPQ`, and its very next use is
-    // `if ( InRepairMode() and repairCost and (repairCost > 0) ) then ... SetTooltipMoney(...)`.
-    // (l.632 in the same file reads only two, which is a caller not needing the third, not a
-    // different contract.) We pushed two, so pfUI's durability scan died on
-    // `panel.lua:499: attempt to perform arithmetic on local 'repCost' (a nil value)`.
-    //
-    // `repairCost` is **0 INTERIM**, the same posture and the same reason as `SetBagItem`'s below:
-    // the per-item repair feed is the paper-doll arc's and does not exist yet. Zero rather than nil
-    // because the reference **always pushes a number** there — `0x534975` reads `fild [ebp-0x30];
-    // call 0x6f3810` on `SetBagItem`'s unconditional leg — and an undamaged item's cost genuinely
-    // is 0, so the interim value is a *real* value of the domain rather than a stand-in. Every
-    // reference consumer guards on `> 0`.
-    //
-    // Arity provenance, stated because it differs from the rest of this module: the *three* is the
-    // reference's own consumer, not a byte-read `mov eax, 3`. `SetBagItem`'s two IS byte-verified
-    // (`mov eax,2` @0x534985). Reading `0x532ee0`'s tail from the bytes would upgrade this line.
+    // GameTooltip:SetInventoryItem(unit, slot [, nameOnly]) -> hasItem, hasCooldown, repairCost
+    // (`0x532ee0`), three as `PaperDollFrame.lua:741` reads them; the arity is that consumer's,
+    // not byte-read as `SetBagItem`'s two is (`0x534985`). Unit-keyed through `Model::inv_slot`:
+    // an inspected item (`InspectPaperDollFrame.xml:20`) has no durability or creator, so those
+    // lines do not show, as in the reference. An armed shopping tooltip renders the compare
+    // shape; the arm is consumed either way. repairCost is 0, as `SetBagItem`'s is.
     m.set(
         "SetInventoryItem",
         lua.create_function(
             |lua, (this, unit, slot, name_only): (Table, String, usize, Value)| {
                 let h = frame_handle_of(lua, &this)?;
-                // **The third argument the binary names itself**: `0x8552dc` carries
-                // `"Usage: SetInventoryItem(unit, slot [, nameOnly])"`, and `0x533027`–`0x53304c` is
-                // its gate — the flag seeds 0 and becomes 1 only on `lua_isnumber(L,4)` AND
-                // `lua_tonumber(L,4) > 0.0` STRICTLY. A miss does not raise; it leaves the zero and
-                // builds the ordinary tooltip. Three of this binding's four builder legs pass it
-                // through (the fourth, `0x533106`, does not).
+                // `nameOnly` (usage string `0x8552dc`) is set only by a number above 0
+                // (`0x533027..0x53304c`); anything else builds the ordinary tooltip, without an
+                // error. Three of the binding's four builder legs pass it on, not `0x533106`.
                 let name_only = super::binding_abi::positive_number_flag(lua, name_only)?;
                 let (item_id, name, quality, inst, currently_equipped) = {
                     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -479,25 +363,19 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                                 s.name.clone(),
                                 s.quality,
                                 render::ItemInstance {
-                                    // The slot's own name — app-composed, so it carries the
-                                    // random-suffix roll off `ITEM_FIELD_RANDOM_PROPERTIES_ID`.
+                                    // App-composed, with the suffix off
+                                    // `ITEM_FIELD_RANDOM_PROPERTIES_ID`.
                                     name: s.name.clone(),
                                     durability: s.durability,
                                     creator: s.creator.clone(),
                                     has_text: false,
                                     flags: s.flags,
                                     already_bound: s.already_bound,
-                                    // No petition line on the doll: a charter has `InventoryType = 0`
-                                    // and cannot be equipped, so this hover can never be over one.
+                                    // A charter has `InventoryType` 0 and is never equipped.
                                     petition: None,
                                     enchants: s.enchants.clone(),
-                                    // `SetInventoryItem 0x532ee0` also has p6=0 legs (`0x533106`,
-                                    // `0x5332ad`) — the "this binding can never emit OPENABLE"
-                                    // claim is dead here too. Which leg each takes is not pinned,
-                                    // and the case is unobservable anyway:
-                                    // nothing openable is equippable, so the doll hover has no clam to
-                                    // show. Left `false` deliberately — inventing a selector we have
-                                    // not read would be the §4 trade, and there is nothing to gain.
+                                    // `0x532ee0` has p6=0 legs too (`0x533106`, `0x5332ad`), but
+                                    // nothing openable is equippable.
                                     openable_source: false,
                                     duration_ms: s.duration_ms,
                                 },
@@ -505,12 +383,8 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                         });
                     match view {
                         Some((id, name, q, inst)) => (id, name, q, inst, armed),
-                        // An EMPTY slot answers `nil` for hasItem — and still pushes the other two,
-                        // because the reference's own caller destructures all three unconditionally
-                        // and only then tests `hasItem`. Answering one value here would hand
-                        // `PaperDollItemSlotButton_OnEnter` a nil `repairCost` on every empty slot,
-                        // which its `repairCost and (repairCost > 0)` guard survives but pfUI's bare
-                        // `totalRep + repCost` does not.
+                        // An empty slot answers nil and still pushes the other two: callers
+                        // destructure all three first, and an addon may add up repairCost.
                         None => {
                             return Ok(MultiValue::from_vec(vec![
                                 Value::Nil,
@@ -520,7 +394,6 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                         }
                     }
                 };
-                // p5 and p4, carried as one value but never as one flag (2216).
                 let flags = BuilderFlags {
                     currently_equipped,
                     name_only,
@@ -533,10 +406,8 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 match view_of(lua, item_id) {
                     Some(v) => render_view(lua, &this, &v, flags, Some(&inst))?,
                     None => {
-                        // Template in flight — the slot view's own name holds the plate (the same
-                        // 0138 posture as SetBagItem's miss path).
-                        // The compare header is a key like every other sentence (2045); this
-                        // fallback path shows it for exactly the reason the full render does.
+                        // Template in flight: the header and the slot's own name, as
+                        // `SetBagItem`'s miss path.
                         if flags.currently_equipped {
                             if let Some(t) = crate::strings::global(lua, "CURRENTLY_EQUIPPED") {
                                 append_line(lua, &this, (t, GRAY), None, false)?;
@@ -555,13 +426,9 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 show_or_hide_empty(lua, h);
                 Ok(MultiValue::from_vec(vec![
                     Value::Integer(1),
-                    // `hasCooldown` — **broader than its name**, and this is the one arm of it we can
-                    // answer. The builder's Lua return is `[ebp-0x38]`, set by FOUR sites, only one of
-                    // which is the cooldown line: LOCKED_WITH_ITEM, the temporary-enchant countdown,
-                    // **the item's own duration line** (`0x52ce0d`), and ITEM_COOLDOWN_TIME. So a
-                    // duration-bearing item answers truthy here with no cooldown of any kind, and an
-                    // addon can see it (decision 1933's fold-back). The equipped-cooldown feed is
-                    // still the INTERIM above; this is the half that now exists.
+                    // hasCooldown is the builder's `[ebp-0x38]`, set by four lines:
+                    // LOCKED_WITH_ITEM, the temporary-enchant countdown, the item's duration
+                    // (`0x52ce0d`) and ITEM_COOLDOWN_TIME. Only the duration is answered here.
                     if inst.duration_ms.is_some() {
                         Value::Boolean(true)
                     } else {
@@ -573,11 +440,11 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         )?,
     )?;
 
-    // GameTooltip:SetBagItem(bag, slot) → hasCooldown, repairCost — the real-instance hover.
-    // The one money-eligible source built so far: merchant open + repair off ⇒ the engine fires
-    // OnTooltipAddMoney(SellPrice × stack), or prints ITEM_UNSELLABLE at price 0 (the gate at
-    // `0x52e376`, engine-side at last). repairCost is 0 INTERIM (the per-item
-    // durability/repair feed is the paper-doll arc's).
+    // GameTooltip:SetBagItem(bag, slot) -> hasCooldown, repairCost: the real-instance hover and
+    // the one money source: with the merchant open and repair off (`0x52e376`), the engine fires
+    // `OnTooltipAddMoney(SellPrice × stack)`, or prints ITEM_UNSELLABLE at price 0 (`0x854a74`,
+    // pushed at `0x52e4a3`). repairCost is 0: the per-item repair cost is not fed. The reference
+    // always pushes a number there (`0x534975`), and stock guards on `> 0`.
     m.set(
         "SetBagItem",
         lua.create_function(|lua, (this, bag, slot): (Table, i64, u32)| {
@@ -590,11 +457,9 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                     .and_then(|c| c.slots.get(&slot))
                     .filter(|s| s.item_id != 0)
                 {
-                    // The reference's own leg selector, byte-read: `SetBagItem 0x534620` asks the
-                    // item-cooldown query `0x6e2ed0` and takes the p6=1 (instance-block) leg iff
-                    // **all three** of enable/start/duration are non-zero — a genuinely running
-                    // cooldown. That one boolean is both the Lua `hasCooldown` return and the
-                    // openable gate's inverse, so they are computed once, here (decision 0896).
+                    // `0x534620` takes the p6=1 leg iff the cooldown query `0x6e2ed0` reports
+                    // enable, start and duration all non-zero; that one boolean is both the
+                    // `hasCooldown` return and the inverse of the openable gate.
                     Some(s) => {
                         let has_cd = s
                             .cooldown
@@ -606,24 +471,17 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                             s.link.clone(),
                             s.quality.unwrap_or(1),
                             render::ItemInstance {
-                                // The bag slot's display name rides its LINK (the reference
-                                // builds that link out of `0x5d8b00`'s output, so the two are the
-                                // same string by construction — the roll's suffix included).
+                                // The link's name: the reference builds both from `0x5d8b00`.
                                 name: s.link.as_deref().and_then(link_name).map(str::to_string),
                                 durability: s.durability,
                                 creator: s.creator.clone(),
                                 has_text: s.readable,
                                 flags: s.flags,
                                 already_bound: s.already_bound,
-                                // Line 3 — the charter's guild name and master. Only the BAG hover
-                                // carries it: a charter has `InventoryType = 0` and cannot be worn,
-                                // so the doll site above has no petition to show and does not ask
-                                // its slot view for one.
                                 petition: s.petition.clone(),
                                 enchants: s.enchants.clone(),
-                                // p6 == 0 ⇔ no running cooldown. A clam shows the green line; the
-                                // same clam mid-cooldown would show ITEM_COOLDOWN_TIME instead
-                                // (that line has no feed here yet — a separate, pre-existing gap).
+                                // p6 = 0 iff no cooldown runs; mid-cooldown the reference shows
+                                // ITEM_COOLDOWN_TIME instead, which is not built.
                                 openable_source: !has_cd,
                                 duration_ms: s.duration_ms,
                             },
@@ -653,11 +511,9 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                     }
                 }
                 None => {
-                    // Template in flight. The real client early-outs to an EMPTY tooltip here
-                    // (`0x52b6a3`); benilla keeps a name-only line instead
-                    // (decision 0138 — the name is already on the slot's link, and a blank plate
-                    // under an on-screen name reads broken). The re-enter loop repaints the
-                    // moment the push lands.
+                    // Deviation: while the template is in flight the reference leaves the tooltip
+                    // empty (`0x52b6a3`); this shows the slot's name, because a blank plate under
+                    // an on-screen name reads as broken. The re-enter loop repaints on arrival.
                     if let Some(name) = link.as_deref().and_then(link_name) {
                         append_line(
                             lua,
@@ -671,32 +527,17 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
             }
             show_or_hide_empty(lua, h);
             Ok(MultiValue::from_vec(vec![
-                // Not just the cooldown: the builder's return is set by four line sites, and the
-                // item's own duration line is one of them (see `SetInventoryItem`'s note above,
-                // decision 1933's fold-back).
+                // The builder's `[ebp-0x38]`: a running cooldown or the item's duration line.
                 Value::Boolean(has_cd || inst.duration_ms.is_some()),
                 Value::Integer(0),
             ]))
         })?,
     )?;
 
-    // GameTooltip:SetLootItem(slot) — the loot-row hover (the reference's own binding,
-    // `0x533470`, which its `LootButtonTemplate` <OnEnter> runs behind `LootSlotIsItem`).
-    // **A block source, not a template one** (the leg at `0x533564` supplies the instance block,
-    // p6=1), and that is the whole point of it existing here: a loot
-    // slot is no item object, so its rolled random-suffix enchants reach the builder through the
-    // block — never through `ITEM_FIELD_ENCHANTMENT`, which the wire does not carry for loot.
-    // Hovering a "… of the Monkey" drop through the template path `BenillaSetItemById` instead printed
-    // the `<Random enchantment>` placeholder until the item was in the bag (decision 1547).
-    //
-    // `slot` is the 1-based display row, like every other loot getter; the coin pile and a
-    // cleared row have no tooltip.
-    // GameTooltip:SetTradePlayerItem(id) / SetTradeTargetItem(id) — `0x5341e0` / `0x534410`, two
-    // arguments exact (self, slot), no returns: the trade slot's item, rendered off its template
-    // the way the loot slot is (decision 1966; the stock TradeFrame.xml's slot OnEnter). The
-    // target side reads the partner's slot guids (`[0xb715a0 + slot*4]`); an empty or
-    // out-of-range slot leaves the tooltip untouched. The
-    // slot's enchant line waits on the trade snapshot carrying the wire's enchant id (0592 P3).
+    // GameTooltip:SetTradePlayerItem(slot) / SetTradeTargetItem(slot) (`0x5341e0`, `0x534410`;
+    // `TradeFrame.xml:150`, `TradeFrame.xml:106`), no returns: the slot's item, the target side
+    // off the partner's slot guids (`[0xb715a0 + slot*4]`). An empty or out-of-range slot leaves
+    // the tooltip untouched. The enchant line is not rendered: the trade view has no enchant id.
     for (name, player_side) in [("SetTradePlayerItem", true), ("SetTradeTargetItem", false)] {
         m.set(
             name,
@@ -743,6 +584,10 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         )?;
     }
 
+    // GameTooltip:SetLootItem(slot): the loot-row hover (`0x533470`, `LootFrame.xml:42`, behind
+    // `LootSlotIsItem`). A block source (`0x533564`, p6=1): a loot slot is no item object, so a
+    // rolled suffix's enchants reach the builder through the block, never through
+    // `ITEM_FIELD_ENCHANTMENT`. `slot` is the 1-based row; coin and cleared rows have no tooltip.
     m.set(
         "SetLootItem",
         lua.create_function(|lua, (this, slot): (Table, usize)| {
@@ -764,10 +609,8 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 clear_content(&mut model, h);
             }
             fire_cleared(lua, h);
-            // The row's own name is the app-composed one — the roll's suffix already joined, so
-            // the plate reads "Chipped Claw of the Bear" like the reference's `0x5d8b00` output.
-            // The lines come from the roll id through the pushed table, which is where the
-            // reference reads them too (its `+0x424` against the DBC store, `0x52b7bf`).
+            // The row's app-composed name has the suffix joined, as `0x5d8b00` does; the lines
+            // come from the roll id, the reference's `+0x424` (`0x52b7bf`).
             let inst = render::ItemInstance {
                 name: row.name.clone(),
                 enchants: roll_enchants(lua, row.random_property_id),
@@ -775,8 +618,7 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
             };
             match view_of(lua, row.item_id) {
                 Some(v) => render_view(lua, &this, &v, BuilderFlags::default(), Some(&inst))?,
-                // Template in flight — the row's name holds the plate (SetBagItem's 0138 posture;
-                // the re-enter loop repaints when the push lands).
+                // Template in flight: the row's name, as `SetBagItem`'s miss path.
                 None => {
                     if let Some(name) = row.name.clone() {
                         append_line(
@@ -794,11 +636,10 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GameTooltip:SetLootRollItem(rollId) — the group-loot roll window's hover (the reference's
-    // own `0x5364a0`). The same shape as SetLootItem beside it, byte-verified on the same
-    // dispatch: p6=1 with `+0x424 ← [roll+0x20]` (the roll's randomPropertyId), all 7 enchant
-    // slots zero, and BOTH guid args `&{0,0}` — no item object, so the suffix-row copy (`0x52b7bf`)
-    // is the only enchant source and the placeholder arm (`0x52cc33`) is unreachable.
+    // GameTooltip:SetLootRollItem(rollId): the roll window's hover (`0x5364a0`,
+    // `LootFrame.xml:343`). Like `SetLootItem`: p6=1 with `+0x424` = `[roll+0x20]`, the roll's
+    // randomPropertyId, every enchant slot zero and no item object, so the suffix-row copy
+    // (`0x52b7bf`) is the only enchant source.
     m.set(
         "SetLootRollItem",
         lua.create_function(|lua, (this, roll_id): (Table, u32)| {
@@ -845,34 +686,13 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GameTooltip:SetMerchantCompareItem(index [, offset]) — `0x536080`, GameTooltip method-table
-    // entry 43. The shopping tooltip the stock vendor row raises beside the main one: "here is what
-    // you are wearing that this would replace".
-    //
-    // **`offset` is not a slot.** It is the 1-based ordinal among CANDIDATE slots, and a slot is a
-    // candidate only when all three of these hold — the reference's own conjunction:
-    //
-    //   1. its bit is set in `0x809200[InventoryType]` (our [`equip_slots_for`]),
-    //   2. the slot is OCCUPIED,
-    //   3. the equipped item's **class** equals the vendor item's class. Class only — subclass is
-    //      never read.
-    //
-    // Empty slots are skipped **without** decrementing, so offset 1 finds the first occupied
-    // matching slot wherever it sits. The consequences are the reference's and they are not
-    // obvious: a shield in the off hand makes offset 2 nil for a one-hand weapon (ARMOR ≠ WEAPON),
-    // and an equipped wand DOES compare against a bow on the shelf (both class 2, both bit 17).
-    // Any type with one candidate slot answers nil for offset 2, which is what makes stock's
-    // second `if` cheap.
-    //
-    // **The return contract decides ghost tooltips versus none**, so it is transcribed exactly:
-    // ONE Lua value on every non-raising path — the NUMBER 1 on success (`lua_pushnumber`, not a
-    // boolean), `nil` on every failure. A bad `this` or a non-number index RAISES; a missing
-    // `offset` does not, and defaults to 1. An explicit `offset` of 0 or less is nil, because the
-    // counter starts below zero and only ever decrements.
-    //
-    // An uncached vendor template answers nil AND fires the query ([`view_of`] does both), so the
-    // first hover of an unseen vendor item shows no shopping tooltip and a later one does. That is
-    // the reference's behaviour, not a race we lost.
+    // GameTooltip:SetMerchantCompareItem(index [, offset]) (`0x536080`, method-table entry 43):
+    // the shopping tooltip beside a vendor row. `offset` counts candidate slots, 1-based: set in
+    // `0x809200[InventoryType]`, occupied, and holding an item of the offered class (never
+    // subclass), so a worn shield makes offset 2 nil for a one-hand weapon and a worn wand compares
+    // against a bow. One value on every non-raising path: the number 1 (`lua_pushnumber`) or nil.
+    // A bad `this` or a non-number index raises; a missing `offset` is 1, one of 0 or less is nil.
+    // An uncached template answers nil and fires the query, as in the reference.
     m.set(
         "SetMerchantCompareItem",
         lua.create_function(
@@ -887,20 +707,18 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                         _ => None,
                     }
                 };
-                // The one argument whose absence is an ERROR, with the client's own usage text.
+                // The one argument whose absence raises, with the reference's usage text.
                 let Some(idx) = as_number(&index) else {
                     return Err(mlua::Error::runtime(
                         "Usage: SetMerchantCompareItem(\"slot\" [, offset])",
                     ));
                 };
-                // The reference re-bases the index in f64 and THEN truncates toward zero, so 2.7
-                // is row 1 (1.7 → 1) rather than row 2. Doing it the other way round differs by
-                // one for every fractional index.
+                // Re-based in f64, then truncated toward zero, as the reference does: 0.5 is row 1.
                 let row = (idx - 1.0).trunc();
                 if row.is_nan() || row < 0.0 || row > f64::from(u32::MAX) {
                     return Ok(Value::Nil);
                 }
-                // `offset` re-bases as an INTEGER, and its absence means 1.
+                // `offset` is truncated before it is re-based; absent, it is 1.
                 let left = match offset.as_ref().and_then(as_number) {
                     Some(n) if n.is_nan() => return Ok(Value::Nil),
                     Some(n) => n.trunc() - 1.0,
@@ -922,8 +740,6 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 }) else {
                     return Ok(Value::Nil);
                 };
-                // The vendor item's own template — the class this compares by, and the miss that
-                // fires the query.
                 let Some(offered) = view_of(lua, item_id) else {
                     return Ok(Value::Nil);
                 };
@@ -933,15 +749,11 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         )?,
     )?;
 
-    // GameTooltip:SetAuctionCompareItem("type", index [, offset]) — `0x535d70`, the auction row's
-    // twin of the vendor compare: the same body (`0x53603e` and `0x5362d4` both reach the shared
-    // compare with `p4 = 0, p5 = 1`), fed by one of the three auction lists instead of the vendor's
-    // shelf.
-    // The type argument is `lua_isstring`-gated (`0x535e28`) and matched against the list names;
-    // a non-string type or non-number index raises the reference's own Usage; a bad list name,
-    // an out-of-range row or an uncached template is nil. Return contract as the merchant's: the
-    // NUMBER 1 on success, nil otherwise — the stock `AuctionFrameItem_OnEnter` gates each
-    // shopping tooltip on it (1971).
+    // GameTooltip:SetAuctionCompareItem("type", index [, offset]) (`0x535d70`): the vendor
+    // compare's body (`0x53603e` and `0x5362d4` both pass p4 = 0, p5 = 1) over an auction list.
+    // `type` is `lua_isstring`-gated (`0x535e28`); a non-string type or non-number index raises
+    // the reference's usage, and a bad list, row or uncached template is nil. The number 1 on
+    // success, which `Blizzard_AuctionUI.lua:1081` gates each shopping tooltip on.
     m.set(
         "SetAuctionCompareItem",
         lua.create_function(
@@ -1004,10 +816,8 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         )?,
     )?;
 
-    // GameTooltip:SetMerchantItem(index) / SetBuybackItem(index) — template-id sources through
-    // the same store (the real `SetMerchantItem 0x534080` is the template path); the
-    // merchant feed's own stat head is the fallback while the template answer is in flight, so
-    // the vendor hover always shows at least the head it showed pre-0274.
+    // GameTooltip:SetMerchantItem(index) / SetBuybackItem(index): template sources, as the
+    // reference's `SetMerchantItem` (`0x534080`) is.
     for (method, buyback) in [("SetMerchantItem", false), ("SetBuybackItem", true)] {
         m.set(
             method,
@@ -1034,17 +844,13 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 match view_of(lua, row.item_id) {
                     Some(v) => {
                         render_view(lua, &this, &v, BuilderFlags::default(), None)?;
-                        // **The vendor tab arms nothing** — `MerchantFrame.xml:67-80` seats
-                        // `ShoppingTooltip1/2` itself on every hover of it, unconditionally, and
-                        // that is the reference's own live compare. Arming here would put the
-                        // shift drive on the same two plates the stock row already owns, and its
-                        // release edge would then hide a compare the player never asked it to.
-                        // The BUYBACK tab is the other branch of the same button and seats
-                        // nothing, so it arms like any other hover.
+                        // Nothing to arm: the vendor tab's row seats `ShoppingTooltip1/2` itself
+                        // (`MerchantFrame.xml:67-80`), and the buyback tab seats none.
                         if buyback {}
                     }
                     None => {
-                        // Template in flight: the row's own stat head as a minimal view.
+                        // Template in flight: the row's own stat head as a minimal view, the
+                        // same deviation as `SetBagItem`'s miss path.
                         let head = row.stats.unwrap_or_default();
                         let v = ItemTemplateView {
                             name: row.name.clone().unwrap_or_default(),
@@ -1071,9 +877,8 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         )?;
     }
 
-    // GameTooltip:SetInboxItem(index) — the mail window's enclosed-item hover (decision 0544): the
-    // inbox row's item entry through the same id-keyed store (MailFrame.lua l.218/470). A row with no
-    // enclosed item (item_id 0) is a no-op, like the reference (which only calls this when hasItem).
+    // GameTooltip:SetInboxItem(index): the mail item hover (`MailFrame.lua:218`,
+    // `MailFrame.lua:470`). A row with no item does nothing; stock calls it only when there is one.
     m.set(
         "SetInboxItem",
         lua.create_function(|lua, (this, index): (Table, usize)| {
@@ -1096,9 +901,7 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 clear_content(&mut model, h);
             }
             fire_cleared(lua, h);
-            // A block source (`SetInboxItem 0x5355fa`, p6=1) carrying the attachment's roll — so
-            // an "… of the Monkey" in the mail reads like the same drop in the loot window, and
-            // the placeholder arm is unreachable here too (decision 1547).
+            // A block source (`0x5355fa`, p6=1) carrying the attachment's roll: no placeholder.
             let inst = render::ItemInstance {
                 name,
                 enchants: roll_enchants(lua, roll),
@@ -1112,14 +915,9 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GameTooltip:SetAuctionItem(type, index) — an auction ROW's hover (decision 1511). The row's
-    // item entry through the same id-keyed store, keyed by list type ("list"/"bidder"/"owner").
-    //
-    // An auction row's tooltip deliberately emits **no** "Made by", "Gift from" or openable lines,
-    // and the reason is structural rather than a rule anyone applies: the reference's binding
-    // zeroes the GUID arguments (`0x535a6d`/`0x535a73`) before it resolves anything, so the gate
-    // those lines hang off fails outright. Our id-keyed store has no instance to report either,
-    // so we land on the same output by the same shape of reasoning.
+    // GameTooltip:SetAuctionItem(type, index): an auction row's hover, `type` "list", "bidder" or
+    // "owner". No creator, gift or open line: the reference zeroes the guid arguments
+    // (`0x535a6d`, `0x535a73`), so the item-object gate those lines hang off fails.
     m.set(
         "SetAuctionItem",
         lua.create_function(|lua, (this, kind, index): (Table, String, usize)| {
@@ -1145,9 +943,7 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 clear_content(&mut model, h);
             }
             fire_cleared(lua, h);
-            // A block source (`SetAuctionItem 0x5359d9`, p6=1) carrying the listing's roll: a
-            // rolled auction shows its real lines, never the placeholder (decision 1547). The
-            // zeroed GUIDs the note above describes are unaffected — a roll is not an instance.
+            // A block source (`0x5359d9`, p6=1) carrying the listing's roll: no placeholder.
             let inst = render::ItemInstance {
                 name,
                 enchants: roll_enchants(lua, roll),
@@ -1161,15 +957,9 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GameTooltip:SetAuctionSellItem() — the create-auction slot's hover (decision 1511). The item
-    // staged in the sell slot, through the same id-keyed store. A no-op when the slot is empty
-    // (the reference gates the call on GetAuctionSellItemInfo()).
-    //
-    // Unlike an auction ROW, this one names a real item the player owns — the reference passes the
-    // live sell-slot GUID (`[0xb72608]`/`[0xb7260c]`) here and resolves an actual object
-    // (`0x5357b4`), so its creator line is structurally reachable. Ours is still the id-keyed
-    // template view, so we do not print one; that is a known narrowing, not a claim about the
-    // reference.
+    // GameTooltip:SetAuctionSellItem(): the sell slot's hover (`Blizzard_AuctionUI.xml:1791`); an
+    // empty slot does nothing. The reference resolves the live sell-slot object (`[0xb72608]`,
+    // `[0xb7260c]`, `0x5357b4`), so its creator line can show; this renders the template alone.
     m.set(
         "SetAuctionSellItem",
         lua.create_function(|lua, this: Table| {
@@ -1198,9 +988,8 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GameTooltip:SetSendMailItem() — the mail Send tab's attached-item hover (decision 0544): the
-    // cursor item attached to the send slot, through the same id-keyed store (MailFrame.lua l.952).
-    // A no-op when nothing is attached (the reference gates the call on GetSendMailItem()).
+    // GameTooltip:SetSendMailItem(): the attached item's hover (`MailFrame.xml:952`); an empty
+    // slot does nothing.
     m.set(
         "SetSendMailItem",
         lua.create_function(|lua, this: Table| {
@@ -1229,22 +1018,16 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GameTooltip:SetTradeSkillItem(skillIndex [, reagentIndex]) — the tradeskill window's item
-    // hover (decision 0437 phase 2): with reagentIndex, that recipe's reagent's item; without, the
-    // recipe's PRODUCT item. Routes through the same id-keyed renderer BenillaSetItemById uses. A product
-    // id of 0 (a pure-effect recipe) or an in-flight ask-once answer both fall to render_by_id's own
-    // name-only fallback line (the recipe's name for the product channel, the reagent's own —
-    // possibly still-nil — name for the reagent channel) rather than a no-op: that fallback already
-    // exists and reads better than a blank hover. An out-of-range skill/reagent index is a no-op.
+    // GameTooltip:SetTradeSkillItem(skillIndex [, reagentIndex]): the reagent's item, or without
+    // `reagentIndex` the recipe's product. A product id of 0 or an uncached template shows the
+    // recipe's or the reagent's name alone (`render_by_id`); a bad index does nothing.
     m.set(
         "SetTradeSkillItem",
         lua.create_function(
             |lua, (this, skill_index, reagent_index): (Table, usize, Option<usize>)| {
                 let found = {
                     let model = lua.app_data_ref::<Model>().expect("model app_data");
-                    // The VISIBLE-row mapping (headers interleave since the grouped build,
-                    // `0x4fca20`, landed) — never a raw recipes[] index; a header index resolves to
-                    // None.
+                    // A visible-row index, headers included (`0x4fca20`); a header is None.
                     let Some(recipe) = super::tradeskill::recipe_at(&model, skill_index) else {
                         return Ok(());
                     };
@@ -1264,13 +1047,9 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         )?,
     )?;
 
-    // GameTooltip:SetCraftItem(craftIndex, reagentIndex) — the craft window's reagent hover
-    // (decision 0437 phase 3, ref `CraftItemTemplate`'s OnEnter, `Blizzard_CraftUI.xml:33`):
-    // ALWAYS the REAGENT's item — unlike SetTradeSkillItem, Craft has no product-item concept to
-    // fall back to when reagentIndex is omitted (craft.rs's own module doc, "no product-item
-    // concept"), so this signature has no optional arm; the ref itself never calls it with one
-    // argument either. Routes through the same id-keyed renderer. An out-of-range craft/reagent
-    // index is a no-op.
+    // GameTooltip:SetCraftItem(craftIndex, reagentIndex): the reagent's item
+    // (`Blizzard_CraftUI.xml:33`); a craft has no product item, so both arguments are required. A
+    // bad index does nothing.
     m.set(
         "SetCraftItem",
         lua.create_function(
diff --git a/crates/benilla-ui/src/script/tooltip_item/names.rs b/crates/benilla-ui/src/script/tooltip_item/names.rs
index 42d20b4a..847cc3d2 100644
--- a/crates/benilla-ui/src/script/tooltip_item/names.rs
+++ b/crates/benilla-ui/src/script/tooltip_item/names.rs
@@ -1,24 +1,10 @@
-//! The item tooltip's display vocabulary — the builder's own **key** tables (`INVTYPE_*`,
-//! `ITEM_MOD_*`, `SPELL_SCHOOL%d_CAP`), the DBC-sourced subclass/class/race names, and the
-//! byte-verified color constants the render law paints with. Pure data; the law itself is
-//! [`super::render`], which resolves every key here against the player's own `GlobalStrings.lua`
-//! (decision 2045).
-//!
-//! **Keys, not sentences, and the difference is not cosmetic.** `INVTYPE_SHIELD` and
-//! `INVTYPE_WEAPONOFFHAND` both read "Off Hand" in enUS and are separately localizable
-//! everywhere else; a table that stored the English could not tell them apart, and this one had
-//! them collapsed into a single arm until 2045's sweep.
-//!
-//! **What stays a Rust literal here, and why it is not the same thing**: [`CLASS_NAMES`] and
-//! [`RACE_NAMES`] name rows the reference reads out of DBC records (ChrClasses, ChrRaces), never
-//! out of `GlobalStrings.lua`. Those belong to the DBC-feed question, not to this one — and the
-//! subclass names that used to sit beside them have gone the whole way there: the type cell and
-//! the bag line both read `ItemSubClass.dbc`'s own DisplayName off the app-resolved view now,
-//! rather than a hand-typed copy of it.
+//! The item tooltip's vocabulary: the builder's key tables (`INVTYPE_*`, `ITEM_MOD_*`,
+//! `SPELL_SCHOOL%d_CAP`), which [`super::render`] resolves against the player's own
+//! `GlobalStrings.lua`, and its colours. Keys, not English: `INVTYPE_SHIELD` and
+//! `INVTYPE_WEAPONOFFHAND` both read "Off Hand" in enUS and differ elsewhere. [`CLASS_NAMES`] and
+//! [`RACE_NAMES`] are English literals; the reference reads `ChrClasses.dbc` and `ChrRaces.dbc`.
 
-/// The client's 7-entry quality→color table (`0xc0d3c8` behind
-/// `GetItemQualityColor 0x48dfb0`): Poor gray, Common white, Uncommon green, Rare blue, Epic
-/// purple, Legendary orange, Artifact gold.
+/// The reference's quality colour table, `0xc0d3c8`, read by `GetItemQualityColor` (`0x48dfb0`).
 pub(super) const QUALITY_RGB: [[f32; 3]; 7] = [
     [0.616, 0.616, 0.616], // 0 Poor      9d9d9d
     [1.0, 1.0, 1.0],       // 1 Common    ffffff
@@ -29,41 +15,23 @@ pub(super) const QUALITY_RGB: [[f32; 3]; 7] = [
     [0.902, 0.8, 0.502],   // 6 Artifact  e6cc80
 ];
 
-// The tooltip color constants: white `0xc0cf60=ffffffff`, red `0xc0d390=ffff2020` (255,32,32),
-// green `0xc0d3ac=ff00ff00`, gold `0xc0d3e8=ffffd200` (255,210,0), gray `0xc0d3c4=ff808080`.
+// The tooltip colours: white `0xc0cf60` ffffffff, red `0xc0d390` ffff2020, green `0xc0d3ac`
+// ff00ff00, gold `0xc0d3e8` ffffd200, gray `0xc0d3c4` ff808080.
 pub(super) const WHITE: [f32; 4] = [1.0, 1.0, 1.0, 1.0];
 pub(super) const GREEN: [f32; 4] = [0.0, 1.0, 0.0, 1.0];
 pub(super) const RED: [f32; 4] = [1.0, 32.0 / 255.0, 32.0 / 255.0, 1.0];
-/// The tooltip's OTHER red — `0xc0d398 = ffff0000`, a pure red distinct from the (255,32,32) the
-/// requirement lines wear. Two lines use it, both in the enchant family: a **negative** enchant id
-/// in slot 0/1, and ITEM_ENCHANT_DISCLAIMER (`0x52ca29`, `0x52cc13`).
+/// The pure red `0xc0d398` (ffff0000), used by two enchant lines (`0x52ca29`, `0x52cc13`): a
+/// negative enchant id in slot 0 or 1, and ITEM_ENCHANT_DISCLAIMER.
 pub(super) const ENCHANT_RED: [f32; 4] = [1.0, 0.0, 0.0, 1.0];
 pub(super) const GOLD: [f32; 4] = [1.0, 210.0 / 255.0, 0.0, 1.0];
 pub(super) const GRAY: [f32; 4] = [128.0 / 255.0, 128.0 / 255.0, 128.0 / 255.0, 1.0];
-/// The owned set member's pale cream — byte-read `0xc0d368 = ffffff97` (writer `0x529050`).
+/// An equipped set member's cream, `0xc0d368` (ffffff97, written at `0x529050`).
 pub(super) const CREAM: [f32; 4] = [1.0, 1.0, 151.0 / 255.0, 1.0];
 
-/// InventoryType → the slot line's GlobalString **key** — the builder's own 30-entry pointer
-/// table at `0x83ddb0`, indexed by `[record+0x2c]` directly (`0x52c103: mov ecx,[ecx*4+0x83ddb0]`),
-/// dumped entry by entry rather than matched by English.
-///
-/// **Index 0 and index 29 are the pre-seeded empty string `0x882748`** — a non-equip item and an
-/// out-of-range type name nothing, which is the `None` here. 18 (bag) and 27 (quiver) *do* have
-/// entries (`INVTYPE_BAG`/`INVTYPE_QUIVER`) but are unreachable: both are containers, and a
-/// container takes the CONTAINER_SLOTS line above this call instead.
-///
-/// **Four of these keys ship no value, and that is the reference's behaviour, not a gap.**
-/// `INVTYPE_AMMO` (24), `INVTYPE_THROWN` (25), `INVTYPE_RANGEDRIGHT` (26) and `INVTYPE_QUIVER`
-/// (27) are in the exe's table but absent from `GlobalStrings.lua`, so `FrameScript_GetText`
-/// hands the builder an empty left cell. We had written "Projectile", "Thrown" and "Ranged" into
-/// those arms — the invention class decision 2045 says a text-matching tripwire cannot catch.
-///
-/// **But an arrow's cell is not empty, and this table is not why.** A class-6 item never reaches
-/// here at all: the builder forks to `ItemClass.dbc`'s own name for it one instruction earlier
-/// (`0x52c0bc`), so ammunition reads "Projectile | Arrow" — the word 2080 deleted, restored by
-/// the mechanism that actually produces it rather than by the key that does not. `INVTYPE_RANGED`
-/// (15) likewise **does** ship, so a bow reads "Ranged | Bow"; it is 25 and 26 — thrown weapons
-/// and guns/crossbows/wands, all ItemClass 2 — that genuinely draw the type word alone.
+/// InventoryType to the slot line's key: the builder's 30-entry table `0x83ddb0`, indexed by
+/// `[record+0x2c]` (`0x52c103`); entries 0 and 29 are the empty string `0x882748`, here `None`. A
+/// bag (18) takes CONTAINER_SLOTS instead, and class 6 its class name (`0x52c0bc`); 24-27 ship no
+/// `GlobalStrings.lua` value, so a thrown weapon (25) or a gun (26) has an empty slot cell.
 pub(super) fn invtype_key(t: u32) -> Option<&'static str> {
     Some(match t {
         1 => "INVTYPE_HEAD",
@@ -96,40 +64,30 @@ pub(super) fn invtype_key(t: u32) -> Option<&'static str> {
     })
 }
 
-/// The damage block's bias constant — `[0x808120]`, byte-exact `0.9999899864196777`
-/// (`0x3f7fff58`). Neither `0.5` nor `1.0`: the epsilon is what stops an exactly-integral max
-/// from being bumped by one, and a true `ceil()` differs from this expression for any value
-/// within ~1e-5 above an integer.
+/// The damage bias `[0x808120]`, 0.9999899864196777: an integral max is not bumped, and unlike a
+/// true `ceil()` a value within ~1e-5 above an integer is not rounded up.
 const DAMAGE_BIAS: f32 = f32::from_bits(0x3f7f_ff58);
 
-/// `floor(DamageMin)` as the builder computes it — `fsub [0x808120]` iff the value is **not**
-/// greater than 0, then `__ftol`'s truncate-toward-zero (`0x52c253`–`0x52c276`).
+/// The builder's `floor(DamageMin)`: subtract the bias unless positive, then truncate toward zero
+/// (`0x52c253..0x52c276`).
 pub(super) fn floor_min(m: f32) -> i32 {
     (if m > 0.0 { m } else { m - DAMAGE_BIAS }) as i32
 }
 
-/// `ceil(DamageMax)` — the mirror: `fadd [0x808120]` iff the value **is** greater than 0, then
-/// the same truncating conversion (`0x52c26e`–`0x52c28c`).
+/// The builder's `ceil(DamageMax)`: add the bias if positive, then truncate (`0x52c26e..0x52c28c`).
 pub(super) fn ceil_max(m: f32) -> i32 {
     (if m > 0.0 { m + DAMAGE_BIAS } else { m }) as i32
 }
 
-/// A damage/resistance school's name key — `SPELL_SCHOOL%d_CAP`, the one string the builder
-/// composes at runtime rather than naming outright (`0x84e4cc`, pushed at `0x52c2a8` for the
-/// damage line and `0x52c8d1` for the resistance line).
-///
-/// The index is the school itself: `SPELL_SCHOOL0_CAP` is "Physical" and 1..6 are
-/// Holy/Fire/Nature/Frost/Shadow/Arcane. **School 0 answers `None`** because the reference
-/// doesn't name it either — a physical weapon takes the school-less `DAMAGE_TEMPLATE` arm rather
-/// than printing the word.
+/// A school's name key, `SPELL_SCHOOL%d_CAP`, the one key the builder composes (`0x84e4cc`,
+/// pushed at `0x52c2a8` and `0x52c8d1`). School 0 has none: a physical weapon takes the
+/// school-less `DAMAGE_TEMPLATE` arm.
 pub(super) fn school_key(s: u32) -> Option<String> {
     (1..=6).contains(&s).then(|| format!("SPELL_SCHOOL{s}_CAP"))
 }
 
-/// Stat-mod type → its `ITEM_MOD_*` key. Not a *name*: the key resolves to the whole line
-/// template, sign hole and all (`ITEM_MOD_AGILITY = "%c%d Agility"`), which is why 2 has no arm —
-/// the builder's 8-way jump table `0x52e510` skips it (keys byte-read at
-/// `0x52c6eb..0x52c777`).
+/// Stat type to its `ITEM_MOD_*` line template (`"%c%d Agility"`); the builder's 8-way jump table
+/// `0x52e510` skips 2 (keys at `0x52c6eb..0x52c777`).
 pub(super) fn stat_key(t: u32) -> Option<&'static str> {
     Some(match t {
         0 => "ITEM_MOD_MANA",
@@ -143,7 +101,7 @@ pub(super) fn stat_key(t: u32) -> Option<&'static str> {
     })
 }
 
-/// Class id → display name (vanilla playable ids; the `ITEM_CLASSES_ALLOWED` list).
+/// The playable class ids and names the `ITEM_CLASSES_ALLOWED` list prints.
 pub(super) const CLASS_NAMES: [(u32, &str); 9] = [
     (1, "Warrior"),
     (2, "Paladin"),
@@ -156,7 +114,7 @@ pub(super) const CLASS_NAMES: [(u32, &str); 9] = [
     (11, "Druid"),
 ];
 
-/// Race id → display name (vanilla playable ids; the `ITEM_RACES_ALLOWED` list).
+/// The playable race ids and names the `ITEM_RACES_ALLOWED` list prints.
 pub(super) const RACE_NAMES: [(u32, &str); 8] = [
     (1, "Human"),
     (2, "Orc"),
@@ -168,7 +126,7 @@ pub(super) const RACE_NAMES: [(u32, &str); 8] = [
     (8, "Troll"),
 ];
 
-/// A playable-ids mask covering every listed id — a mask covering all of them shows no line.
+/// The mask of every listed id; an item allowing all of them shows no line.
 pub(super) fn full_mask(ids: &[(u32, &str)]) -> i32 {
     ids.iter().fold(0i32, |m, &(id, _)| m | (1 << (id - 1)))
 }
diff --git a/crates/benilla-ui/src/script/tooltip_item/render.rs b/crates/benilla-ui/src/script/tooltip_item/render.rs
index 3482ad9e..3802541f 100644
--- a/crates/benilla-ui/src/script/tooltip_item/render.rs
+++ b/crates/benilla-ui/src/script/tooltip_item/render.rs
@@ -1,18 +1,9 @@
-//! The item tooltip's line law — [`render_view`], the byte-verified emission order of the
-//! client's shared renderer `0x52b650` (see the parent module doc for the law's provenance and
-//! the compare/red/SET summaries).
-//!
-//! **Every sentence here is a key, never a Rust string** (decision 2045). The builder names its
-//! keys outright — the census of the string pointers reachable from `[0x52b650, 0x52e600)` is
-//! where each one below came from, so a line's key is the *reference's* choice and not a match on
-//! English. That distinction is load-bearing: `ITEM_REQ_SKILL`, `LOCKED_WITH_ITEM`,
-//! `LOCKED_WITH_SPELL` and `LOCKED_WITH_SPELL_KNOWN` are all "Requires %s" in enUS and four
-//! different strings anywhere else.
-//!
-//! A key the player's `GlobalStrings.lua` does not carry emits **no line at all** — never an
-//! invented one. That is `duration_text`'s disposition and the reference's own: its
-//! `FrameScript_GetText` hands back the pre-seeded empty string and `AddLine` drops an empty row
-//! before it ever counts it.
+//! The item tooltip's line law, [`render_view`]: the emission order of the reference's builder
+//! `0x52b650`. Every sentence is a key the builder itself names (the string pointers reachable
+//! from `[0x52b650, 0x52e600)`), never a match on English: `ITEM_REQ_SKILL` and the three
+//! `LOCKED_WITH_*` keys all read "Requires %s" in enUS and differ elsewhere. A key the player's
+//! `GlobalStrings.lua` lacks emits no line, as in the reference, whose `FrameScript_GetText`
+//! returns the empty string and whose `AddLine` drops an empty row uncounted.
 
 use mlua::{Lua, Table};
 
@@ -22,145 +13,80 @@ use crate::strings::{fill, Arg};
 
 use super::names::*;
 
-/// The REAL instance's contribution to the line law — the fields only a streamed item OBJECT
-/// carries. A template/link hover passes `None` at the call site: the ref gates the whole
-/// creator + openable/readable tail on the item-object pointer (`0x52e1c7`/`0x52e2e0` — no
-/// object, no lines), and keeps the authored full max/max durability.
+/// What a source knows beyond the template: an item object's fields, or a block source's name and
+/// roll. A template source passes `None`.
 #[derive(Default)]
 pub(super) struct ItemInstance {
-    /// The source's own display NAME, when it knows one the template cannot compose — today that
-    /// is exactly the **random-suffix roll**: "Chipped Claw" + `ItemRandomProperties[id].suffix`
-    /// = "Chipped Claw of the Bear". The reference composes it inside the builder (`0x52b7bf`
-    /// keeps the suffix row for the name, and `0x5d8b00` joins it through `ITEM_SUFFIX_TEMPLATE`);
-    /// here the app owns every DBC join, so it arrives already joined — the same division the
-    /// enchant lines below already use. `None` = the template's own name (`ItemTemplateView::name`).
+    /// The name with its random suffix joined, which the reference composes in the builder
+    /// (`0x52b7bf`, `0x5d8b00` through `ITEM_SUFFIX_TEMPLATE`); `None` takes the template's.
     pub name: Option<String>,
-    /// Live `(current, max)` durability (director-reported: the spirit healer's 25% loss
-    /// showed nowhere); `None` = indestructible (max 0) or the create not yet landed.
+    /// Live `(current, max)`; `None` for an indestructible item or one not yet streamed.
     pub durability: Option<(u32, u32)>,
-    /// The RESOLVED `ITEM_FIELD_CREATOR` name (the app's ask-once name cache — the ref's
-    /// `0x55f080` probe). `None` = authorless OR the name query is still in flight: the ref
-    /// emits no line either way (`0x52e209`; its resolve callback repaints the tooltip, ours
-    /// is the container re-enter loop).
+    /// The resolved `ITEM_FIELD_CREATOR` name (the reference's `0x55f080`); `None` while it is
+    /// unresolved, which prints no line either (`0x52e209`).
     pub creator: Option<String>,
-    /// Instance `ITEM_FIELD_ITEM_TEXT_ID` ≠ 0 (a mail permanent copy): flips the creator line
-    /// to WRITTEN_BY (`0x52e223`) and satisfies the READABLE gate (`0x52e348`).
+    /// `ITEM_FIELD_ITEM_TEXT_ID` ≠ 0, a letter's copy: the creator line reads WRITTEN_BY
+    /// (`0x52e223`) and READABLE shows (`0x52e348`).
     pub has_text: bool,
-    /// Instance `ITEM_FIELD_FLAGS` — the openable lock sub-gate reads UNLOCKED `0x4`
-    /// (`0x52e30c`) and the wrapped-gift arm WRAPPED `0x8` (`0x52e31d`).
+    /// `ITEM_FIELD_FLAGS`: UNLOCKED `0x4` (read at `0x52e30c`), WRAPPED `0x8` (`0x52e31d`).
     pub flags: u32,
-    /// `0x5da2c0` — **this instance is runtime-bound**: `ITEM_FIELD_FLAGS & 1`, or a live
-    /// enchant slot naming a `SpellItemEnchantment` row that binds. The binding half needs a DBC
-    /// join, so the whole predicate arrives app-resolved
-    /// ([`crate::script::ContainerSlot::already_bound`]) rather than being re-derived here off
-    /// [`Self::enchants`] — that list is a *display* view and drops rows the line law hides.
-    /// Drives the Soulbound override; `false` on every template/link source.
+    /// Runtime-bound (`0x5da2c0`): `ITEM_FIELD_FLAGS & 1`, or an enchant that binds. App-resolved,
+    /// since [`Self::enchants`] drops rows the line law hides.
     pub already_bound: bool,
-    /// The petition this charter names — **line 3**, between the NAME and `ITEM_SIGNABLE`. See
-    /// [`crate::script::PetitionSlotView`], which carries the reason its third line is unbuilt.
+    /// The petition a charter names, printed between the name and `ITEM_SIGNABLE`.
     pub petition: Option<crate::script::PetitionSlotView>,
-    /// The instance's enchant slots, app-resolved and in slot order (`0x52c991`,
-    /// decisions 0915/0920) — see [`crate::script::EnchantView`]. Empty on an unenchanted item and
-    /// on every template/link source (no instance, nothing enchanted).
+    /// The enchant slots, app-resolved, in slot order (`0x52c991`).
     pub enchants: Vec<crate::script::EnchantView>,
-    /// May this source emit the ITEM_OPENABLE line? = the reference's `p6 == 0` — "this tooltip
-    /// carries **no** caller-supplied instance block" (`[this+0x440]`, tested at `0x52e2e8`: when
-    /// it is set, the builder evaluates only READABLE and skips the openable tree entirely).
-    ///
-    /// **This is not a per-binding constant**, though it looks like one: the old p6 table treated
-    /// `SetBagItem` as passing `p6=1` unconditionally, and so never showed the line — which is why
-    /// our bag hover had no green line at all, and which the director's screenshot of a clam
-    /// falsified. The cause: the old p6 table was enumerated per *binding* from the instance-block
-    /// **writers**, so it only ever saw the p6=1 leg. A per-**call-site** census of all 31
-    /// `0x52b650` sites finds five callers with two or more legs, and `SetBagItem 0x534620` is one:
-    /// `0x534900` p6=1 and `0x53493e` p6=0.
-    ///
-    /// What selects the leg is the item-cooldown query `0x6e2ed0` at `0x53483a` — p6=1 iff
-    /// **enable, start and duration are all non-zero**, i.e. iff the item has a *running
-    /// cooldown*. That same block writes `this+0x408 = start + duration − now`, whose sole
-    /// consumer is the ITEM_COOLDOWN_TIME line and the builder's `hasCooldown` return. So on the
-    /// bag binding the two lines are structurally exclusive: **an item on cooldown shows
-    /// "Cooldown remaining", the same item off cooldown shows `<Right Click to Open>`.**
-    /// Decision 0896.
+    /// The reference's p6 = 0, no caller-supplied instance block (`[this+0x440]`, tested at
+    /// `0x52e2e8`; when set, only READABLE is evaluated). It is per call site, not per binding:
+    /// `SetBagItem` (`0x534620`) takes p6=1 (`0x534900`) iff the cooldown query `0x6e2ed0` at
+    /// `0x53483a` finds one running, else p6=0 (`0x53493e`), so the open line and the cooldown
+    /// line never show together there.
     pub openable_source: bool,
-    /// **The instance's remaining LIFETIME in milliseconds** — a duration-limited item (a
-    /// conjured stone, a holiday gift, a timed quest item) counting down to its own destruction.
-    /// `None` = no timer, which is every ordinary item and every template/link source.
-    ///
-    /// App-resolved from the client-local deadline `SMSG_ITEM_TIME_UPDATE` parks
-    /// ([`crate::script::ContainerSlot::duration_ms`]), not from the instance's
-    /// `ITEM_FIELD_DURATION` field: vmangos's own writer says the field is not what the client
-    /// displays from — *"Though the client has the information in the item's data field, we have
-    /// to send SMSG_ITEM_TIME_UPDATE to display the remaining time"* (`Item::SendTimeUpdate`,
-    /// `Objects/Item.cpp:1094`) — which is the same split the temporary-enchant countdown one
-    /// field up already takes (decisions 0920/1933).
+    /// A timed item's remaining lifetime in ms, from `SMSG_ITEM_TIME_UPDATE`, not
+    /// `ITEM_FIELD_DURATION`: the client displays from the packet (`Objects/Item.cpp:1093`).
     pub duration_ms: Option<u64>,
 }
 
-/// The SET block's blank gold spacer — the reference's own literal `0x854b2c`, and it is **not**
-/// the empty string. It is a SPACE followed by a newline, and the difference is a whole row.
-///
-/// Both halves:
-/// `AddLine`'s core `0x530270` takes an empty left text with no right text and **bails before it
-/// ever increments the line count** (`5302a9: test ebx,ebx; 5302ab: je 0x530378`, the shared exit,
-/// which never reaches the `inc [esi+0x31c]` at `0x530372`) — an empty string here is silently
-/// dropped, not even a zero-height slot. So the reference cannot spell this line `""`, and it
-/// doesn't: `" \n"` is one real line carrying one space. It measures as ONE row, not two, because
-/// the width-based stepper `0x5c7470` consumes the trailing break inside the same call that
-/// scanned the space (`5c7659: add esi,ecx`) and the kernel's next top-of-loop read hits the NUL.
-///
-/// benilla lands on the same row count from the same law: the app's `fontstring_lines`
-/// trailing-break rule (decision 1343) drops the empty segment a plain split would leave, so
-/// `" \n"` is one line here too. We wrote `String::new()`, which our own engine calls zero lines
-/// of zero height — so the set block's two spacers were invisible where the reference shows two
-/// blank rows.
+/// The set block's blank gold line, the reference's literal `0x854b2c`: a space and a newline. An
+/// empty string would be no row, as `AddLine` (`0x530270`) drops an empty left text uncounted
+/// (`0x5302a9`). `" \n"` is one row: the stepper `0x5c7470` consumes the break with the space
+/// (`0x5c7659`), as the app's `fontstring_lines` trailing-break rule does.
 const SET_SPACER: &str = " \n";
 
-/// The builder's two independent render flags, p4 and p5 of `0x52b650` — a struct rather than two
-/// adjacent `bool`s because collapsing them into one was decision 2216's bug, and two positional
-/// bools at a call site is the same mistake with an extra step.
+/// The builder's two independent render flags, p4 and p5 of `0x52b650`.
 #[derive(Clone, Copy, Default)]
 pub(super) struct BuilderFlags {
-    /// **p5 `[arg+0x18]`** — prepend the gray `CURRENTLY_EQUIPPED` line. Set by the two shopping
-    /// plates (`SetMerchantCompareItem`, `SetAuctionCompareItem`) and by nothing else in the
-    /// image; those two sites pass [`name_only`](Self::name_only) ZERO.
+    /// p5 `[arg+0x18]`: prepend the gray `CURRENTLY_EQUIPPED` line. Only the two compare bindings
+    /// set it, and both pass [`name_only`](Self::name_only) zero.
     pub currently_equipped: bool,
-    /// **p4 `[arg+0x14]`** — the compact mode the binary itself calls `nameOnly`
-    /// (`0x8552dc`: `"Usage: SetInventoryItem(unit, slot [, nameOnly])"`). Reachable from exactly
-    /// one binding — `SetInventoryItem`'s optional third argument, a number `> 0` — and from no
-    /// stock FrameXML caller at all, but it is live code an addon can ask for (benilla
-    /// decision 2224).
-    ///
-    /// It is *trimmed*, not bare, and the trim is two non-contiguous jumps plus an early return:
-    /// the name goes white, the bind/lock region and the whole stat body are cut, and everything
-    /// after the cooldown line is skipped. What survives is the name, the slot/type cell,
-    /// durability, duration, every requirement line, the spell triggers and the set block.
+    /// p4 `[arg+0x14]`, the compact mode the reference calls `nameOnly` (`0x8552dc`), reachable
+    /// only through `SetInventoryItem`'s third argument. The name goes white, the bind/lock region
+    /// and the stat body are cut, and all after the cooldown line is skipped; the slot/type cell,
+    /// durability, duration, requirements, spell triggers and set block still print.
     pub name_only: bool,
 }
 
-/// Render one item template into the tooltip — the emission law of the shared
-/// renderer `0x52b650` (the enchant lines are decision 0915's), minus the instance-only families
-/// still unfed (soulbound override, cooldown-remaining, the gift-wrap family).
+/// Render one item into the tooltip in `0x52b650`'s order. Not built: ITEM_COOLDOWN_TIME,
+/// ITEM_WRAPPED_BY and the `LOCKED_WITH_*` line under LOCKED.
 pub(super) fn render_view(
     lua: &Lua,
     this: &Table,
     v: &ItemTemplateView,
     flags: BuilderFlags,
-    // `None` = a template/link source (the ref's no-object path).
+    // `None`: a template source, with no item object and no instance block.
     inst: Option<&ItemInstance>,
 ) -> mlua::Result<()> {
     let (req, known_spell, taught_known, set_view, equipped) = {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
         let knows = |id: u32| model.spellbook.slots.iter().any(|s| s.spell_id == id);
         let known = v.required_spell != 0 && knows(v.required_spell);
-        // A taught spell (trigger 6, SPELL_EFFECT_LEARN) the player already knows — the
-        // unconditional-red ITEM_SPELL_KNOWN "Already known" line (recipes).
+        // A taught spell (trigger 6, learn) the player knows: the always-red ITEM_SPELL_KNOWN.
         let taught = v
             .spell_triggers
             .iter()
             .any(|&(t, id, _)| t == 6 && id != 0 && knows(id));
-        // The SET block's inputs: the app-resolved set view (a miss records the ask-once) and
-        // the player's equipped item ids — the (owned/total) count + per-member highlight.
+        // The set view (a miss records the ask) and the equipped ids the set block counts.
         let set_view = (v.item_set != 0)
             .then(|| {
                 let view = model.item_sets.get(&v.item_set).cloned();
@@ -182,12 +108,7 @@ pub(super) fn render_view(
     let addw = |l: (String, [f32; 4])| append_line(lua, this, l, None, true);
     let add2 =
         |l: (String, [f32; 4]), r: (String, [f32; 4])| append_line(lua, this, l, Some(r), false);
-    // The VM's own `GlobalStrings.lua`, off the player's patch chain — the one source of every
-    // sentence below.
     let get = |key: &str| crate::strings::global(lua, key);
-    // One line, named by KEY and filled from the template the install carries. A key the table
-    // does not hold emits nothing: the reference's empty `FrameScript_GetText` return reaches
-    // `AddLine`'s `0x530270`, which bails before it increments the line count.
     let keyed = |key: &str, args: &[Arg<'_>], color: [f32; 4], wrap: bool| -> mlua::Result<()> {
         match get(key) {
             Some(t) => append_line(lua, this, (fill(&t, args), color), None, wrap),
@@ -195,39 +116,25 @@ pub(super) fn render_view(
         }
     };
 
-    // The gray CURRENTLY_EQUIPPED header (`[arg+0x18]≠0`, color ptr `0xc0d3c4`) — and it is the
-    // ONLY thing a shopping-tooltip fill adds. **Against a plain `SetInventoryItem` of the same
-    // equipped item, one extra line, first, is the whole difference**: the two callers that set
-    // the header (`SetMerchantCompareItem`'s arg vector at `0x5362d4`, `SetAuctionCompareItem`'s
-    // at `0x53603e`) pass **p4 = 0**, so compact/compare mode is OFF — the NAME keeps its quality
-    // color, the stat body is not jumped, and nothing is cut at `0x52e14c`. A downstream client
-    // that renders a "compare mode" abbreviated tooltip here is wrong — the per-call-site census
-    // over all 31 sites of `0x52b650` is what settles it: those two are
-    // the only sites in the image passing a literal non-zero p5, and both pass p4 zero.
+    // The gray header (`[arg+0x18]`, colour `0xc0d3c4`) is all a compare adds: the only two of
+    // `0x52b650`'s 31 call sites passing p5 (`0x5362d4`, `0x53603e`) pass p4 = 0, so none is cut.
     if flags.currently_equipped {
         keyed("CURRENTLY_EQUIPPED", &[], GRAY, false)?;
     }
     let name = inst
         .and_then(|i| i.name.clone())
         .unwrap_or_else(|| v.name.clone());
-    // The NAME's one recolor: `nameOnly` paints it white (`0x52b8b3`, the `je 0x52b8ca` target
-    // being the quality arm `lea ecx,[eax*4+0xc0d3c8]`). Nothing else ever recolors it — an
-    // unusable item's name stays quality-colored.
+    // `nameOnly` paints the name white (`0x52b8b3`), else the quality arm colours it (`0x52b8ca`);
+    // nothing else recolors it, not even for an unusable item.
     let name_color = if flags.name_only {
         WHITE
     } else {
         quality_color(v.quality)
     };
     add((name, name_color))?;
-    // Line 3 — the petition block, ABOVE the green line and below the name: "Guild Name: X" then
-    // "Guild Master: Y" for a charter, "Petition: X" / "Created by Y" for a plain petition. The
-    // keys are picked by the record's own charter bit, the same bit `GetPetitionInfo`'s first
-    // return reads.
-    //
-    // Each line is withheld while its source is unresolved rather than printed with a hole: an
-    // uncached owner name shows the title alone, and the repaint fills it in — the creator line's
-    // rule, and the reference's own (its resolve callback repaints the tooltip; ours is the
-    // container re-enter loop).
+    // The petition lines, below the name: a charter's `GUILD_CHARTER_*` pair or a petition's
+    // `PETITION_*`, by the record's charter bit (`GetPetitionInfo`'s first return). A line whose
+    // source is unresolved waits for the repaint, as the creator line does.
     if let Some(p) = inst.and_then(|i| i.petition.as_ref()) {
         let (title_key, creator_key) = if p.is_charter {
             ("GUILD_CHARTER_TITLE", "GUILD_CHARTER_CREATOR")
@@ -241,27 +148,19 @@ pub(super) fn render_view(
             keyed(creator_key, &[Arg::S(owner)], WHITE, false)?;
         }
     }
-    // ITEM_SIGNABLE (green) — Flags bit 0x2000 (petitions).
+    // ITEM_SIGNABLE: template flag `0x2000`, a petition.
     if v.flags & 0x2000 != 0 {
         keyed("ITEM_SIGNABLE", &[], GREEN, false)?;
     }
-    // **p4's FIRST cut** (`0x52babe`; `0x52bac3 jne 0x52bfad` skips `[0x52bac9, 0x52bfad)`) — the
-    // whole bind/lock region. `ITEM_SIGNABLE` just above is NOT in the jumped range and survives.
+    // p4's first cut (`0x52babe`, skipping `[0x52bac9, 0x52bfad)` at `0x52bac3`): the bind/lock
+    // region. ITEM_SIGNABLE above survives it.
     if !flags.name_only {
-        // ITEM_CONJURED (Flags bit 0x2).
         if v.flags & 0x2 != 0 {
             keyed("ITEM_CONJURED", &[], WHITE, false)?;
         }
-        // The bind line (white, one line). Bonding `[record+0x194]` ∈ {1..5} is what decides
-        // whether a line prints at ALL — a Bonding-0 item says nothing here however it is held.
-        // Within that, a **runtime-bound instance** (`0x5da2c0` — [`ItemInstance::already_bound`])
-        // overrides the whole line to ITEM_SOULBOUND, and to ITEM_BIND_QUEST for the two quest
-        // kinds, which is the same text 4|5 print anyway; only then does the jump table `0x52e4fc`
-        // pick 1→picked up · 2→equipped · 3→used · 4/5→Quest Item.
-        //
-        // Before this arm an equipped Binds-when-equipped piece kept saying *Binds when equipped*
-        // forever: the template's `bonding` never changes when the item binds —
-        // the instance's flag is the only thing that does.
+        // Bonding (`[record+0x194]`) 1..5 decides whether a bind line prints. A runtime-bound
+        // instance (`0x5da2c0`) prints ITEM_SOULBOUND, or ITEM_BIND_QUEST for the quest kinds;
+        // otherwise the jump table `0x52e4fc` picks 1 pickup, 2 equip, 3 use, 4 and 5 quest.
         match v.bonding {
             4 | 5 => keyed("ITEM_BIND_QUEST", &[], WHITE, false)?,
             1..=3 if inst.is_some_and(|i| i.already_bound) => {
@@ -280,37 +179,22 @@ pub(super) fn render_view(
         if v.start_quest != 0 {
             keyed("ITEM_STARTS_QUEST", &[], WHITE, false)?;
         }
-        // LOCKED (red) — suppressed once the INSTANCE carries UNLOCKED `0x4` (the law's "and the
-        // item is not already unlocked"; the same bit the openable sub-gate reads). The key-item
-        // "Requires %s" sub-line joins with the Lock.dbc resolve (the GO-locks follow-up).
+        // LOCKED, red, until the instance carries UNLOCKED `0x4`.
         if v.lock_id != 0 && inst.is_none_or(|i| i.flags & 0x4 == 0) {
             keyed("LOCKED", &[], RED, false)?;
         }
     }
-    // Slot | type — or, for a bag, the single CONTAINER_SLOTS line in the same seat. The type
-    // cell is suppressed for cloaks (InventoryType 16) and displayFlags-hidden subclasses
-    // (rings/trinkets/shirts — the "Miscellaneous" family), both builder gates. The two cells
-    // recolor independently (byte-read at the builder's `0x52c143..0x52c1f9` legs against the
-    // verified `0x530270(this, left, right, leftColor, rightColor, wrap)` signature — NB the cells
-    // are swapped): a proficiency-mask miss (`0xc4d4a0[class]` bit
-    // `1 << subclass`; our SMSG_SET_PROFICIENCY-fed map; no mask entry never reds) reds the
-    // TYPE cell — unless a weapon's alternate subclass (ItemSubClass prereq/postreq) is
-    // proficient, which reds the SLOT cell instead. Independently, an off-hand weapon
-    // (InventoryType 22) reds the SLOT cell without Dual Wield (`0x5eab70` = the learned
-    // effect-40 spell), even when the type itself is proficient.
-    // The bag line's gate is `InventoryType == 0x12` **alone** (`0x52b754 sete`, read at
-    // `0x52bffe`) — never the slot count, which the gate does not test at all: a 0-slot bag
-    // prints "0 Slot Bag". Every shipped container carries 18, quivers and ammo pouches
-    // included, which is why `INVTYPE_QUIVER` is a dead slot name in 1.12 (InventoryType 27
-    // occurs in none of the 848 records of the reference install's own
-    // `itemcache.wdb`, and `0x809200[27]` maps to no equipment slot at all).
+    // The slot | type line, or for a bag the CONTAINER_SLOTS line in its seat. The type cell is
+    // hidden for cloaks (16) and display-hidden subclasses. The cells recolor independently
+    // (`0x52c143..0x52c1f9`): a proficiency miss (`0xc4d4a0[class]` bit `1 << subclass`; a class
+    // with no mask never reds) reds the type, or the slot when a weapon's alternate subclass is
+    // proficient; an off-hand weapon (22) without Dual Wield (`0x5eab70`) reds the slot.
+    // The bag gate is `InventoryType == 18` alone (`0x52b754`, read at `0x52bffe`), never the slot
+    // count. Quivers and ammo pouches are 18 too, so 27 is dead (`0x809200[27]` maps to no slot).
     if v.inventory_type == 18 {
-        // `%d` is `ContainerSlots`; `%s` is the SAME `ItemSubClass` DisplayName the type cell
-        // reads — so the noun is per-subclass ("24 Slot Soul Bag", "8 Slot Quiver", "6 Slot
-        // Ammo Pouch"), never the constant "Bag" this line used to print for every container.
-        // A container whose row has no display name emits NEITHER this line nor the ordinary
-        // slot|type one (`0x52c006`/`0x52c018`/`0x52c021` all jump past the whole region), and
-        // displayFlags bit 0 is not consulted on this path.
+        // `%s` is the subclass DisplayName the type cell reads ("8 Slot Quiver"); a subclass
+        // without one prints no line at all (`0x52c006`, `0x52c018`, `0x52c021`), and
+        // displayFlags bit 0 is not read here.
         if let Some(name) = v.sub_class_display.as_deref() {
             keyed(
                 "CONTAINER_SLOTS",
@@ -320,27 +204,16 @@ pub(super) fn render_view(
             )?;
         }
     } else {
-        // The slot cell. For **`ItemClass == 6` the InventoryType key table is not consulted at
-        // all** (`0x52c0bc cmp dword [esi],6`): the reference reads `ItemClass.dbc` row 6's own
-        // localized name — "Projectile" — verbatim out of the store at `[0xc0dc24]`, never
-        // through `FrameScript_GetText`. That is the same `[classRow + 4·locale + 0xc]` column
-        // `GetItemInfo`'s `itemType` answers with, which the view already carries.
-        //
-        // Every other class takes the `0x83ddb0` key table for its InventoryType, so the types
-        // whose keys `GlobalStrings.lua` does not carry (24 ammo, 25 thrown, 26 ranged-right,
-        // 27 quiver) draw no slot cell — but 15 `INVTYPE_RANGED` *does* ship, so a bow reads
-        // "Ranged | Bow" while a gun reads "Gun" alone. Decision 2080 removed three invented
-        // words here and was right about the KEYS; an arrow's cell is nonetheless not empty,
-        // because ammunition never reaches them.
+        // The slot cell: for `ItemClass == 6`, `ItemClass.dbc`'s own name ("Projectile", read
+        // from `[0xc0dc24]` at `0x52c0bc`), the column `GetItemInfo`'s itemType reads; else the
+        // `0x83ddb0` key, so a bow reads "Ranged | Bow" and a gun, whose key ships no string,
+        // "Gun" alone.
         let slot = if v.class == 6 {
             v.item_type.clone()
         } else {
             invtype_key(v.inventory_type).and_then(&get)
         };
-        // The type cell is `ItemSubClass.dbc`'s DisplayName for the pair, app-resolved (the
-        // builder's `0xc0db90` row cache read) — never a table in here: 2080 found the same
-        // shape one file over, where a hand-typed "Lockpicking" shadowed `LockType.dbc`'s own
-        // "Pick Lock".
+        // The type cell: `ItemSubClass.dbc`'s DisplayName, app-resolved (the builder's `0xc0db90`).
         let ty = if v.inventory_type == 16 || v.hide_subclass {
             None
         } else {
@@ -368,47 +241,30 @@ pub(super) fn render_view(
                 (t.to_string(), req_color(!right_red)),
             )?,
             (Some(s), None) => add((s, req_color(!left_red)))?,
-            // No slot name: the type stands alone and takes the hard-miss color (the
-            // builder's single-cell fallback keeps flag-1).
+            // No slot name: the type stands alone, keeping its own colour.
             (None, Some(t)) => add((t.to_string(), req_color(!right_red)))?,
             _ => {}
         }
     }
-    // **p4's SECOND cut** (`0x52c220`; `0x52c225 jne 0x52cc5b` skips `[0x52c22b, 0x52cc5b)`) —
-    // damage/speed/DPS, armor, block, the stat mods, the resistances and the whole enchant family.
-    // The two cuts are not contiguous: the slot/type cell between them is emitted either way.
+    // p4's second cut (`0x52c220`, skipping `[0x52c22b, 0x52cc5b)` at `0x52c225`): damage through
+    // the enchant family. The slot/type cell between the two cuts always prints.
     if !flags.name_only {
-        // **The damage block** — five slots, a five-arm template matrix and a first/PLUS_ flag
-        // (`[0x52c22b, 0x52c5a1)`). Every arm is a key, and every hole's shape is the
-        // binary's own push list — this block composed its English in Rust until it was converted.
-        //
-        // The three predicates and the flag: **hasSchool** is the slot's school field being nonzero
-        // (school 0 takes the no-school subtree — `SPELL_SCHOOL0_CAP` is never looked up);
-        // **isAmmo** is `ItemClass == 6` and *only* that (not InventoryType, not a flag);
-        // **isSingle** is `floor(min) == ceil(max)` on the ROUNDED integers, tested only on the
-        // no-school non-ammo leaf (there is no `SINGLE_…_WITH_SCHOOL`); and **isFirst** is per-ITEM,
-        // cleared on the first EMITTED slot, so a skipped slot does not consume it.
+        // The damage block, `[0x52c22b, 0x52c5a1)`: per slot, a key picked by school (non-zero),
+        // ammo (`ItemClass == 6` alone) and, on the no-school non-ammo leaf only, single
+        // (`floor(min) == ceil(max)`); every emitted slot after the first takes `PLUS_`.
         let mut first = true;
         let mut dps_acc = 0.0f32;
         for &(min, max, school) in v.damages.iter().take(5) {
-            // `floor(min)` / `ceil(max)` — NOT a round-half pair, which is what this block used to
-            // do on both bounds. The reference biases by `0x808120` (0.9999899864196777, neither 0.5
-            // nor 1.0 — the epsilon is what stops an exactly-integral max being bumped) and converts
-            // with `__ftol`'s truncate-toward-zero. Fang of the Mystics' 38.7–85.7 reads "38 - 86";
-            // rounding to nearest would say "39 - 86" (43 shipped items carry fractional damage).
+            // The biased floor and ceil (`0x808120`), not rounding: 38.7-85.7 reads "38 - 86".
             let (lo, hi) = (floor_min(min), ceil_max(max));
             // A slot is emitted iff either rounded bound is nonzero (`0x52c292`).
             if lo == 0 && hi == 0 {
                 continue;
             }
-            // The school WORD is the resolved key; the school NUMBER is what picks the arm. A chain
-            // that carries no `SPELL_SCHOOL%d_CAP` still takes the with-school template and fills
-            // the hole with the empty string, exactly as `FrameScript_GetText` does.
+            // The school number picks the arm; a missing `SPELL_SCHOOL%d_CAP` fills its hole empty.
             let school_name = school_key(school).and_then(|k| get(&k)).unwrap_or_default();
-            // `avg` is the two ROUNDED bounds averaged, round-tripped through f32 — and it is NOT
-            // divided by anything: `AMMO_DAMAGE_TEMPLATE`'s shipped "Adds %g damage per second" is
-            // FrameXML's phrasing over a number the binary never makes per-second (Rough Arrow's
-            // 1–2 reads "Adds 1.5 damage per second").
+            // The rounded bounds' mean, not per second whatever `AMMO_DAMAGE_TEMPLATE` says: an
+            // arrow of 1-2 reads "Adds 1.5 damage per second".
             let avg = f64::from((lo + hi) as f32 * 0.5);
             let plus = |k: &str| {
                 if first {
@@ -439,17 +295,14 @@ pub(super) fn render_view(
                     vec![Arg::D(lo.into()), Arg::D(hi.into())],
                 )
             };
-            // The RIGHT cell is the FIRST emitted line's alone, and weapons' alone (`0x52c494`/
-            // `0x52c49c` — the only two conjuncts): every later damage line, and every line of a
-            // non-weapon, renders left-text-only. `"%s %.2f"` is an `.rdata` LITERAL, not a key —
-            // only the word "Speed" is looked up — over `Delay × 0.001`.
+            // Speed rides a weapon's first emitted line only (`0x52c494`, `0x52c49c`): the literal
+            // `"%s %.2f"` over `Delay × 0.001`, with only the word a key.
             let speed = (first && v.class == 2).then(|| {
                 let word = get("SPEED").unwrap_or_default();
                 let secs = f64::from(v.delay_ms) * f64::from(0.001_f32);
                 format!("{word} {secs:.2}")
             });
-            // The damage line is white in BOTH cells unconditionally — it never reddens for an item
-            // the player cannot use (`0x52c4fa`–`0x52c516`).
+            // White in both cells, even for an unusable item (`0x52c4fa..0x52c516`).
             if let Some(t) = get(&key) {
                 let line = (fill(&t, &args), WHITE);
                 match speed {
@@ -457,17 +310,14 @@ pub(super) fn render_view(
                     None => add(line)?,
                 }
             }
-            // The DPS accumulator runs on the emit path, and it uses the RAW floats — so the
-            // printed range and the printed DPS are computed from different numbers by design.
+            // DPS sums the raw floats of the emitted slots, not the printed bounds.
             dps_acc += (max + min) * 0.5;
             first = false;
         }
-        // DPS — two conjuncts: a line was emitted AND `ItemClass == 2`. Ammo can satisfy neither
-        // (its arms require class 6), so an arrow gets no DPS line and no Speed cell.
+        // DPS needs an emitted line and `ItemClass == 2`, so ammunition has none.
         if !first && v.class == 2 {
-            // The precision is DPS_TEMPLATE's own `%.1f`, not ours — a locale that respells it gets
-            // its own number of decimals with no code change (`0x854c4c`: "the print precision is
-            // FRAMEXML-DATA"). There is no divide-by-zero guard in the reference either.
+            // The precision is `DPS_TEMPLATE`'s own (`0x854c4c`); the reference has no
+            // divide-by-zero guard either.
             let secs = f64::from(v.delay_ms) * f64::from(0.001_f32);
             keyed(
                 "DPS_TEMPLATE",
@@ -487,30 +337,23 @@ pub(super) fn render_view(
                 false,
             )?;
         }
-        // Stat mods (+N Stamina …) in the client's DISPLAY order — the `0x808e88` table (byte-read:
-        // 4,3,7,5,6,1,0 then 8,9,2,10 + zero padding; the builder's outer loop walks the table,
-        // the inner loop scans the item's raw slots — `0x52c6b0..0x52c801`). So Strength, Agility,
-        // Stamina, Intellect, Spirit, Health, Mana — never the wire order. (The table's trailing
-        // ZERO entries would re-match a mana slot once per pass — a dormant client quirk nothing
-        // shipped can reach: the only mana-stat item in the whole 1.12 DB is the internal "Test MP
-        // Ring" 6674. Not emulated.)
+        // Stats in the display order of `0x808e88` (4,3,7,5,6,1,0, then 8,9,2,10 and zero padding;
+        // `0x52c6b0..0x52c801`), not wire order. Deviation: the reference's padding repeats a mana
+        // stat once per zero entry; not emulated, since only the internal test ring 6674 has one.
         const STAT_DISPLAY_ORDER: [u32; 7] = [4, 3, 7, 5, 6, 1, 0];
         for &want in &STAT_DISPLAY_ORDER {
             for &(t, val) in &v.stats {
                 if t != want || val == 0 {
                     continue;
                 }
-                // The `ITEM_MOD_*` template is the whole line, sign hole included
-                // (`"%c%d Agility"`) — the sign is an argument, not a prefix we glue on.
+                // The sign fills the template's `%c` (`"%c%d Agility"`).
                 let Some(key) = stat_key(t) else { continue };
                 let sign = if val > 0 { "+" } else { "-" };
                 keyed(key, &[Arg::S(sign), Arg::D(val.abs().into())], WHITE, false)?;
             }
         }
-        // Resistances: six equal nonzero values collapse to the ALL line; otherwise one line per
-        // nonzero school with HOLY excluded from the singles loop (both byte-verified). The six
-        // fields are schools 1..6, so slot `i` names `SPELL_SCHOOL{i+1}_CAP` — the same `%d`-composed
-        // key the damage line uses one block up.
+        // Six equal non-zero resistances print the ALL line; otherwise one line per non-zero
+        // school, Holy excluded. Field `i` is school `i + 1`.
         let first_res = v.resistances[0];
         if first_res != 0 && v.resistances.iter().all(|&r| r == first_res) {
             let sign = if first_res > 0 { "+" } else { "-" };
@@ -521,12 +364,8 @@ pub(super) fn render_view(
                 false,
             )?;
         } else {
-            // **The singles come out in the BUILDER's order, not the field order.** `0x52c8ad–
-            // 0x52c93e` runs `edi` 1..5 and reads school `esi = (edi == 1) ? 6 : edi`, so the lines
-            // are Arcane, Fire, Nature, Frost, Shadow — and that 1→6 remap is *how* Holy is excluded:
-            // it is displaced by Arcane rather than skipped by a test. Read while converting the
-            // block's keys and named in decision 2080; we emitted plain field order (Fire first,
-            // Arcane last) until it was converted.
+            // The builder's order, not field order: `0x52c8ad..0x52c93e` walks 1..5 reading school
+            // 6 for 1, so Arcane comes first and Holy is displaced rather than tested.
             const RESIST_EMIT_ORDER: [u32; 5] = [6, 2, 3, 4, 5];
             for school in RESIST_EMIT_ORDER {
                 let r = v.resistances[school as usize - 1];
@@ -543,42 +382,18 @@ pub(super) fn render_view(
                 )?;
             }
         }
-        // **Line 17 — the enchant family** (decisions 0915/0920). One contiguous block
-        // `[0x52c991, 0x52cc69)` between the resistances and the durability precompute, and three arms
-        // that are mutually exclusive by construction — the per-slot loop falls through to the
-        // proposed-enchant pair and jumps the block's end, so RANDOM_ENCHANT is reachable only when
-        // there was no id source at all.
-        //
-        // The **colour is per slot** — the value is a
-        // computed local, defaulting to WHITE, overwritten **only for slots 0 and 1** — green
-        // `0xc0d3ac` for a positive id, pure-red `0xc0d398` for a negative one. Slots 2..6 — the
-        // random-property suffix enchants — are **always white**, whatever the sign. (Our first cut
-        // painted every slot green.) The sign never picks a different DBC row; the app already
-        // resolved that off `abs(id)`.
-        //
-        // Two gates sit above the loop. **ITEM_SIGNABLE** (template Flags bit `0x2000`, a petition
-        // or guild charter) forces every id to 0 with no fallback (`0x52c9e0: test ah,0x20`) — such
-        // an item shows no enchant line even if its instance carries ids. And with **no id source
-        // at all** the block instead prints the template-only `ITEM_RANDOM_ENCHANT` placeholder
-        // (`0x52cc33`).
+        // The enchant family, `[0x52c991, 0x52cc69)`: the slot loop, or with no id source at all
+        // the `ITEM_RANDOM_ENCHANT` placeholder (`0x52cc33`). Slots 0 and 1 are green `0xc0d3ac`
+        // for a positive id and red `0xc0d398` for a negative one; the suffix slots 2..6 are always
+        // white. A signable item (`0x2000`) zeroes every id (`0x52c9e0`) and shows no enchant line.
         let signable = v.flags & 0x2000 != 0;
         let enchant_slots = match signable {
             true => &[][..],
             false => inst.map(|i| i.enchants.as_slice()).unwrap_or_default(),
         };
-        // "No id source" is the reference's own three-way fork (`0x52c991`): a wrapped gift, or no
-        // item object AND no caller-supplied instance block (`+0x440 == 0`). Ours reads the same: a
-        // hover
-        // that passes NO [`ItemInstance`] is a p6=0 leg — the template sources (merchant, quest,
-        // craft, buyback, send-mail, the compare legs, `BenillaSetItemById`) — plus the wrapped-gift bit.
-        //
-        // **A block-supplying source never prints the placeholder, even carrying no ids at all.** The
-        // fork tests the block's presence, not its contents, so `SetLootItem`/`SetHyperlink`/
-        // `SetInboxItem`/`SetAuctionItem`/`SetLootRollItem`/the trade legs fall into the slot loop and
-        // print whatever their slots hold — nothing, when the roll is absent. Decision 0920's prose
-        // put a hyperlink hover on the placeholder arm; the `0x52c9a3` fork says otherwise, and
-        // that is the drift 1547 corrects (a linked or looted "of the Monkey" showed the placeholder
-        // where the reference shows the rolled lines).
+        // No id source (`0x52c991`): a wrapped gift, or no item object and no instance block
+        // (`+0x440 == 0`), here a hover passing no [`ItemInstance`]. The fork tests the block's
+        // presence, not its contents (`0x52c9a3`), so a block source never shows the placeholder.
         let no_id_source = inst.is_none_or(|i| i.flags & 0x8 != 0);
         if no_id_source && !signable && v.random_property != 0 {
             keyed("ITEM_RANDOM_ENCHANT", &[], GREEN, false)?;
@@ -589,27 +404,19 @@ pub(super) fn render_view(
                 (true, true) => ENCHANT_RED,
                 (false, _) => WHITE,
             };
-            // A TEMPORARY enchant's countdown REPLACES the plain name in the same line and keeps
-            // that colour — it is never a second line (`0x52ca49`). The bucket ladder
-            // (day/hour/min/sec) and its
-            // ceil-vs-truncate split are [`enchant_time_left`]'s; its source is
-            // `SMSG_ITEM_ENCHANT_TIME_UPDATE`, never the item's own duration field.
+            // A temporary enchant's countdown replaces its name, in the same line and colour
+            // (`0x52ca49`); the time is `SMSG_ITEM_ENCHANT_TIME_UPDATE`'s.
             let mut text = match e.remaining_ms {
-                // The countdown IS the line — `ITEM_ENCHANT_TIME_LEFT_MIN = "%s (%d min)"` carries
-                // the enchant's own name in its first hole. Without that template there is no line
-                // to compose: the reference printf's an empty format into a zeroed buffer and
-                // `AddLine` drops the empty row, so a missing key skips the slot rather than falling
-                // back to the bare name.
+                // A missing template skips the slot, not falling back to the bare name: the
+                // reference formats an empty string, which `AddLine` drops.
                 Some(ms) => match enchant_time_left(&e.name, ms, &get) {
                     Some(t) => t,
                     None => continue,
                 },
                 None => e.name.clone(),
             };
-            // " (N Charges)" — the slot's own charges dword through ITEM_SPELL_CHARGES, then the
-            // literal `" (%s)" 0x854820` (`0x52caa6–0x52cb38`), which is the engine's own format and
-            // not a string table entry. Only an owned item object carries charges; the session/inspect
-            // legs ship ids alone, so this is naturally absent there.
+            // The slot's charges: ITEM_SPELL_CHARGES inside the literal `" (%s)"` (`0x854820`,
+            // `0x52caa6..0x52cb38`).
             if let Some(charges) = charges_phrase(e.charges, &get) {
                 text.push_str(&format!(" ({charges})"));
             }
@@ -617,8 +424,7 @@ pub(super) fn render_view(
         }
     }
     if let Some((cur, max)) = inst.and_then(|i| i.durability).filter(|&(_, max)| max > 0) {
-        // Red iff BROKEN (durability 0) — the byte law ("durability (red iff broken==0)", the
-        // AddLine colour pointer `0xc0d390`, the same red as the unmet-requirement lines).
+        // Red (`0xc0d390`) only when broken.
         let color = if cur == 0 { RED } else { WHITE };
         keyed(
             "DURABILITY_TEMPLATE",
@@ -635,29 +441,17 @@ pub(super) fn render_view(
             false,
         )?;
     }
-    // **ITEM_DURATION `0x854bb4` — the item's own expiry countdown** (`0x52ce0d`, one of the four
-    // sites that set the builder's `[ebp-0x38]` return). It sits here by that address: after the
-    // durability precompute, pinned at `0x52cd0e–0x52cd22`, and well before `ITEM_COOLDOWN_TIME` at
-    // `0x52e140` — the reference's own numbered emission order omits the line entirely, which is
-    // the gap decision 1933 names.
-    // Formatted through the same `0x52fa50` ladder as the enchant countdown, with key prefix
-    // `ITEM_DURATION`; unlike its siblings that prefix ships **no `_P1` plural twin**, so every
-    // count reads "days"/"hrs" (`GlobalStrings.lua:2401-2404`) — which `plural_template`'s
-    // fall-back-to-the-bare-token arm produces without a special case.
-    //
-    // **This is `tooltip::duration_text` itself**, not a second copy of the ladder: the two had
-    // drifted into separate implementations of the same four arms, and the local one always
-    // emitted a line (an invented sentence off an install) where the shared one returns `None`.
-    // The one seam is the width — the deadline is parked as `u64` milliseconds and the reference's
-    // formatter takes a dword, so a timer past 49.7 days saturates rather than wrapping. No 1.12
-    // item carries one; the longest shipped duration is a fortnight.
+    // ITEM_DURATION (`0x854bb4`, `0x52ce0d`), the item's own expiry: after durability
+    // (`0x52cd0e..0x52cd22`), before ITEM_COOLDOWN_TIME (`0x52e140`), through the `0x52fa50`
+    // ladder. Its prefix ships no `_P1` twin, so every count reads "days" or "hrs"
+    // (`GlobalStrings.lua:2401-2404`). The reference's formatter takes a dword, so a timer past
+    // 49.7 days saturates here; no 1.12 item lasts past a fortnight.
     if let Some(ms) = inst.and_then(|i| i.duration_ms) {
         let ms = u32::try_from(ms).unwrap_or(u32::MAX);
         if let Some(line) = duration_text(ms, "ITEM_DURATION", true, &get) {
             add((line, WHITE))?;
         }
     }
-    // Class/race lists — red when the player's own bit is absent (the usable ask).
     if v.allowable_class > 0
         && (v.allowable_class & full_mask(&CLASS_NAMES)) != full_mask(&CLASS_NAMES)
     {
@@ -693,9 +487,7 @@ pub(super) fn render_view(
             )?;
         }
     }
-    // ITEM_MIN_LEVEL prints only for RequiredLevel > 1 (byte-VERIFIED `0x52d2cf`: `cmp esi,0x1 /
-    // jle skip`) — a level-1 requirement gates nothing a logged-in player could fail, so the
-    // real client hides it on all the level-1 consumables that carry one.
+    // Only a required level above 1 prints (`0x52d2cf`).
     if v.required_level > 1 {
         keyed(
             "ITEM_MIN_LEVEL",
@@ -704,11 +496,8 @@ pub(super) fn render_view(
             false,
         )?;
     }
-    // The skill requirement is TWO keys, picked by whether a rank is asked for — `ITEM_MIN_SKILL`
-    // = "Requires %s (%d)" and `ITEM_REQ_SKILL` = "Requires %s" (the builder's own pair at
-    // `0x52d34e`/`0x52d355`). `ITEM_REQ_SKILL` is also what the required-SPELL line below takes
-    // (`0x52d650`): three other 1.12 keys read "Requires %s" in enUS — the `LOCKED_WITH_*` trio —
-    // and none of them is this line.
+    // ITEM_MIN_SKILL with a rank, ITEM_REQ_SKILL without (`0x52d34e`, `0x52d355`); the required
+    // spell takes ITEM_REQ_SKILL too (`0x52d650`).
     if let Some(skill) = &v.required_skill_name {
         let have = req.skills.get(&v.required_skill).copied().unwrap_or(0);
         let color = req_color(have >= v.required_skill_rank.max(1));
@@ -730,9 +519,7 @@ pub(super) fn render_view(
         }
     }
     if let Some(rep) = &v.required_rep_line {
-        // Red when the player's rank with the faction is below the requirement (`0xc0d390`;
-        // standing `< [+0x58]`); an unfed faction reads as unmet, like the real client's
-        // empty store at login (INITIALIZE_FACTIONS lands before the world does).
+        // Red (`0xc0d390`) below the required rank (`[+0x58]`); an unfed faction reads as unmet.
         let rank = req
             .rep_ranks
             .get(&v.required_rep_faction)
@@ -743,14 +530,11 @@ pub(super) fn render_view(
             req_color(u32::from(rank) >= v.required_rep_rank),
         ))?;
     }
-    // ITEM_SPELL_KNOWN — a taught spell the player already knows, UNCONDITIONALLY red.
     if taught_known {
         keyed("ITEM_SPELL_KNOWN", &[], RED, false)?;
     }
-    // Green trigger lines, wrapped — the text is app-resolved (the spell's name in P1; its
-    // $-substituted description via the token engine in P2). The prefix is a key, joined to the
-    // text by the engine's own `"%s %s"` literal `0x82ef08` (`0x52da7e`) — which is why the
-    // shipped values ("Use:", "Equip:", "Chance on hit:") carry no trailing space of their own.
+    // Green, wrapped trigger lines: the prefix key and the app-resolved text joined by the
+    // literal `"%s %s"` (`0x82ef08`, `0x52da7e`).
     for &(trigger, _, ref text) in &v.spell_triggers {
         let key = match trigger {
             0 | 5 => "ITEM_SPELL_TRIGGER_ONUSE",
@@ -764,21 +548,12 @@ pub(super) fn render_view(
     if let Some(charges) = charges_phrase(v.charges.max(0) as u32, &get) {
         add((charges, WHITE))?;
     }
-    // The item-SET block (above the binary's p4 cut at `0x52e14c`), byte-read at the builder's
-    // `0x52d8a0..0x52e0f5`: a blank gold line ([`SET_SPACER`]), the gold "name (owned/total)"
-    // header, the set-level skill line (white, red when short), the member ladder ("  name" —
-    // pale-cream `0xc0d368` when equipped, gray otherwise; a member whose template is still in
-    // flight waits — the app re-pushes the view as names land), a second blank, then the threshold
-    // bonuses sorted THRESHOLD-ASCENDING (the builder qsorts the slot indices via `0x52e5c0` —
-    // never the DBC's stored order), green only when the skill requirement is met (`0x5eaae0`)
-    // AND owned ≥ threshold. "Owned" counts EQUIPPED members on both builder paths (the
-    // owner-unit 19-slot scan / the hyperlink walk with section mask 0x1).
-    //
-    // **The two bonus arms are two different KEYS, and this is where reading the byte law paid**
-    // (`0x52e056..0x52e0d6`): the met arm formats `ITEM_SET_BONUS` = "Set: %s" with the text
-    // alone, and only the unmet arm formats `ITEM_SET_BONUS_GRAY` = "(%d) Set: %s" with the
-    // count. We had printed the counted form in both colours, so an ACTIVE set bonus read
-    // "(3) Set: …" where 1.12 reads "Set: …".
+    // The set block (`0x52d8a0..0x52e0f5`), above p4's cut at `0x52e14c`: a blank gold line, the
+    // gold "name (owned/total)" header, the set's skill line, the members (cream `0xc0d368` when
+    // equipped, else gray; one still in flight waits), a second blank, then the bonuses sorted by
+    // threshold (`0x52e5c0`), green when the skill is met (`0x5eaae0`) and enough are owned.
+    // "Owned" counts equipped members on both builder paths. A met bonus is ITEM_SET_BONUS, the
+    // text alone; only an unmet one is ITEM_SET_BONUS_GRAY, with its count (`0x52e056..0x52e0d6`).
     if let Some(set) = &set_view {
         let owned = set
             .members
@@ -809,8 +584,7 @@ pub(super) fn render_view(
                 keyed("ITEM_REQ_SKILL", &[Arg::S(skill)], color, false)?;
             }
         }
-        // The member ladder's two-space indent is the engine's own `"  %s"` literal `0x854b14`,
-        // not a string-table entry.
+        // The two-space indent is the literal `"  %s"` (`0x854b14`), not a key.
         for (id, name) in &set.members {
             let Some(name) = name else { continue };
             let color = if equipped.contains(id) { CREAM } else { GRAY };
@@ -828,30 +602,22 @@ pub(super) fn render_view(
             }
         }
     }
-    // **p4's early return** — `0x52e147` reads the flag and `0x52e14c je 0x52e170` takes the
-    // NON-compact leg, so compact is the fall-through `0x52e14e`: it stamps `[esi+0xd0]=1`, lays
-    // out, and returns `[ebp-0x38]` (the `hasCooldown` answer is produced on this path too).
-    // Everything from here down — flavor text, creator/gift, OPENABLE/READABLE, money — is below
-    // `0x52e170` and never runs.
+    // p4's early return (`0x52e147..0x52e14c`): compact falls through to `0x52e14e`, lays out and
+    // returns, so nothing from `0x52e170` on runs: flavor text, creator, open or read line, money.
     if flags.name_only {
         return Ok(());
     }
-    // The quoted flavor text — gold, wrapped, literal quotes (all three byte-verified).
     if !v.description.is_empty() {
         addw((format!("\"{}\"", v.description), GOLD))?;
     }
-    // Everything below rides the REAL-INSTANCE gate (`0x52e1c7`/`0x52e2e0`): a template/link
-    // hover emits no creator line and no openable/readable line — you can't right-click a
-    // hyperlink open.
+    // The reference gates the rest on an item object (`0x52e1c7`, `0x52e2e0`). Here only a template
+    // source (`None`) stops, so a link, loot, mail or auction hover, which has an instance but no
+    // object, still reaches READABLE.
     let Some(inst) = inst else { return Ok(()) };
-    // The creator line (`0x52e1b1..0x52e2db`): the resolved
-    // `ITEM_FIELD_CREATOR` name — a letter (instance text id) is ITEM_WRITTEN_BY, anything
-    // else ITEM_CREATED_BY, both the literal 1.12 GlobalStrings (the Made-by green is the
-    // string's OWN `|cff00ff00` escape; the AddLine color pointer is white `0xc0cf60`, wrap 0).
-    // A WRAPPED instance (`ITEM_FIELD_FLAGS` bit `0x8` — the arm gate `0x52b7b0`, instance bit
-    // only) switches the whole line to ITEM_WRAPPED_BY off `ITEM_FIELD_GIFTCREATOR`; that
-    // field has no feed yet, so a wrapped instance emits NOTHING here rather than a wrong
-    // "Made by" (gifts join with the wrap/unwrap arc).
+    // The creator line (`0x52e1b1..0x52e2db`), white `0xc0cf60`: ITEM_WRITTEN_BY for a letter, else
+    // ITEM_CREATED_BY, green by its own `|cff00ff00`. A wrapped instance (`0x8`, gate `0x52b7b0`)
+    // takes ITEM_WRAPPED_BY off `ITEM_FIELD_GIFTCREATOR` in the reference; that is not built, so a
+    // wrapped instance prints no creator line.
     if inst.flags & 0x8 == 0 {
         if let Some(name) = &inst.creator {
             let key = if inst.has_text {
@@ -862,17 +628,10 @@ pub(super) fn render_view(
             keyed(key, &[Arg::S(name)], WHITE, false)?;
         }
     }
-    // ITEM_OPENABLE / ITEM_READABLE — ONE line, openable wins outright (the `jmp 0x52e35d` past
-    // the READABLE test; `0x52e2f2..0x52e35d`): openable = a p6=0 source ([`ItemInstance::
-    // openable_source`]) AND the template loot flag `0x4` behind its lock sub-gate (LockID set →
-    // only once the instance carries UNLOCKED `0x4`), or a wrapped gift (template WRAPPER `0x200`
-    // + instance WRAPPED `0x8`); readable = template PageText (the CGItem vtable `+0x74` getter
-    // `0x5d9e10`) OR the instance letter text. Both green.
-    //
-    // Note the lock sub-gate is the LINE's, not the CLICK's: the send arm tests the bare template
-    // bit, so a locked junkbox stays silent here while its right-click still goes out and draws
-    // the server's "Item is locked" (decision 0896, `ItemInfo::opens_loot`). The click order is
-    // also the inverse of this one — READABLE wins there.
+    // One green line, OPENABLE winning (`0x52e2f2..0x52e35d`). Openable: a p6=0 source and either
+    // the loot flag `0x4` behind its lock gate (a lock needs UNLOCKED) or a wrapped gift (`0x200`
+    // and WRAPPED `0x8`). Readable: PageText (`0x5d9e10`) or the letter text. The lock gate is the
+    // line's only: the click tests the bare flag (`ItemInfo::opens_loot`), and READABLE wins there.
     let openable = inst.openable_source
         && ((v.flags & 0x4 != 0 && (v.lock_id == 0 || inst.flags & 0x4 != 0))
             || (v.flags & 0x200 != 0 && inst.flags & 0x8 != 0));
@@ -884,33 +643,17 @@ pub(super) fn render_view(
     Ok(())
 }
 
-/// A temporary enchant's line text — the name with its countdown, the reference's own bucket
-/// ladder (`0x52fa50`): a runtime key
-/// `ITEM_ENCHANT_TIME_LEFT_<DAYS|HOURS|MIN|SEC>` chosen by the largest unit that fits, with the
-/// count taken as **ceil** in the day/hour/minute arms and **truncated** in the seconds arm, and
-/// the `_P1` plural twin picked by [`plural_template`]'s byte-pinned rule. The day and hour keys
-/// ship a twin; minutes and seconds do not, so those read "(1 min)" at one minute exactly as they
-/// read "(9 min)".
-///
-/// **Two holes, which is why this cannot be `duration_text`**: the templates are
-/// `"%s (%d min)"` — the enchant's own name fills the first, the count the second. That name is
-/// the `SpellItemEnchantment` row's, DBC data rather than a string-table sentence, so it arrives
-/// as an argument. `None` = the family is absent from the install's string table, and the caller
-/// draws no line at all.
+/// A temporary enchant's name with its countdown (`0x52fa50`): `ITEM_ENCHANT_TIME_LEFT_<unit>`, its
+/// `_P1` twin picked by [`plural_template`]. Two holes, the name then the count, so not
+/// `duration_text`; `None` when the install lacks the family, and the caller draws no line.
 fn enchant_time_left(name: &str, ms: u64, get: &dyn Fn(&str) -> Option<String>) -> Option<String> {
     let (suffix, n) = time_bucket(ms);
     let template = plural_template(&format!("ITEM_ENCHANT_TIME_LEFT_{suffix}"), n, get)?;
     Some(fill(&template, &[Arg::S(name), Arg::D(i64::from(n))]))
 }
 
-/// `0x52fa50`'s bucket + count for the ENCHANT countdown — the key suffix and the number that
-/// fills it. The largest unit that fits wins (`>= 1 day` · `>= 1 h` · `>= 1 min` · else seconds);
-/// the count is **ceil** in the day/hour/minute arms (the `roundUp` argument, which all seven of
-/// the function's callers pass as 1) and plain **truncation** in the seconds arm.
-///
-/// The same ladder [`crate::script::tooltip::duration_text`] walks — it stays separate only
-/// because that one fills a single-hole template and this family has two holes; every other
-/// countdown in the tooltips goes through `duration_text`.
+/// `0x52fa50`'s unit and count: the largest unit that fits, the count ceiled for days, hours and
+/// minutes (all seven callers pass `roundUp` 1) and truncated for seconds.
 fn time_bucket(ms: u64) -> (&'static str, u32) {
     const SEC: u64 = 1_000;
     const MIN: u64 = 60 * SEC;
@@ -926,12 +669,8 @@ fn time_bucket(ms: u64) -> (&'static str, u32) {
     (suffix, u32::try_from(n).unwrap_or(u32::MAX))
 }
 
-/// `ITEM_SPELL_CHARGES` and its `_P1` plural twin (`0x84e3b4`, pushed at `0x52cae8` for the
-/// enchant suffix and `0x52db61` for the standalone line). One rule for both consumers: the
-/// charges line and the enchant line's ` (…)` suffix.
-///
-/// Zero answers `None` — the reference never reaches this with a zero count, and neither
-/// consumer here has a line to draw without one.
+/// `ITEM_SPELL_CHARGES` or its `_P1` twin (`0x84e3b4`), pushed at `0x52cae8` for the enchant
+/// suffix and `0x52db61` for the charges line; zero charges have no phrase.
 fn charges_phrase(n: u32, get: &dyn Fn(&str) -> Option<String>) -> Option<String> {
     if n == 0 {
         return None;
@@ -944,10 +683,8 @@ fn charges_phrase(n: u32, get: &dyn Fn(&str) -> Option<String>) -> Option<String
 mod tests {
     use super::*;
 
-    /// A stand-in string table, **deliberately not the shipped wording** — what is under test is
-    /// which key is reached and what fills it, never what the sentence says (decision 2045,
-    /// "assert the identifier, not the sentence"). Every value carries angle brackets so a
-    /// resolved line cannot be mistaken for a composed one.
+    /// A stand-in string table, not the shipped wording: the tests check which key is reached and
+    /// what fills it.
     fn table(key: &str) -> Option<String> {
         Some(
             match key {
@@ -965,10 +702,7 @@ mod tests {
         )
     }
 
-    /// The countdown's bucket ladder (`0x52fa50`): the largest unit that
-    /// fits wins, the count is **ceil** in the day/hour/minute arms and **truncated** in seconds,
-    /// and the day/hour arms have `_P1` twins while minutes and seconds do not — so those two
-    /// suffixes reach the same key at every count.
+    /// The `0x52fa50` ladder: minutes and seconds have no `_P1` twin, so each reaches one key.
     #[test]
     fn enchant_countdown_buckets_and_rounding() {
         let t = |ms| enchant_time_left("Rockbiter", ms, &table);
@@ -984,21 +718,17 @@ mod tests {
         // Days ceil.
         assert_eq!(t(86_400_000).as_deref(), Some("<Rockbiter :: 1 D>"));
         assert_eq!(t(86_400_001).as_deref(), Some("<Rockbiter :: 2 DD>"));
-        // Zero never reaches here (the app drops an expired timer), but it must not panic — and
-        // zero takes the PLURAL arm, which is `GetPluralIndex`'s rule, not a rounding accident.
+        // The app drops an expired timer, but zero must not panic; it takes the plural arm,
+        // `GetPluralIndex`'s rule.
         assert_eq!(t(0).as_deref(), Some("<Rockbiter :: 0 S>"));
     }
 
-    /// A string table that does not carry the family draws **no line**, never an invented one —
-    /// the whole point of resolving by key rather than composing (2045).
     #[test]
     fn a_missing_countdown_family_draws_nothing() {
         assert_eq!(enchant_time_left("Rockbiter", 60_000, &|_| None), None);
         assert_eq!(charges_phrase(3, &|_| None), None);
     }
 
-    /// `ITEM_SPELL_CHARGES` and its `_P1` plural twin — one rule, both consumers (the charges
-    /// line and the enchant line's suffix). A zero count has no line either way.
     #[test]
     fn charges_phrase_picks_the_plural() {
         assert_eq!(charges_phrase(1, &table).as_deref(), Some("<1 chg>"));
diff --git a/crates/benilla-ui/src/script/tooltip_spell.rs b/crates/benilla-ui/src/script/tooltip_spell.rs
index 4b2222d4..e4757cd6 100644
--- a/crates/benilla-ui/src/script/tooltip_spell.rs
+++ b/crates/benilla-ui/src/script/tooltip_spell.rs
@@ -1,25 +1,12 @@
-//! The engine **spell/aura tooltip channel** (decision 0274 P2) — the verified line law of the
-//! spell builder `0x52e610` and the aura builder `0x52f880` (the 0276 fold-back):
+//! The spell and aura tooltip content, in the line order of the spell builder `0x52e610` and the
+//! aura builder `0x52f880`: name and rank; cost and range; cast time and cooldown (omitted for a
+//! passive spell, with no "Passive" line); the required item class, then form, white when met and
+//! red when not; reagents, a missing one inline red; the description, gold (white on an aura).
+//! Only `SetPlayerBuff` adds the gold time-remaining line.
 //!
-//! - name | rank (gray) — one double line. The name's colour is the BUILDER's: **white** from
-//!   the spell builder (`0x530270`), **gold** from the aura builder (`0x530380`, the gold
-//!   wrapper) — the same split `SetTrackingSpell` shows;
-//! - **Cost | Range** — ONE double line (either side may be absent);
-//! - **CastTime | Cooldown** — ONE double line; a passive spell simply omits it (there is NO
-//!   "Passive" text in the 1.12 builder);
-//! - required tool / form — the equipped-item-class line then the stance line, each white when
-//!   met and red when not;
-//! - reagents — inline red per missing item (the one builder that uses the `|cffff2020` escape;
-//!   joins when a reagent feed exists);
-//! - description — gold, wrapped. An AURA's description is **white** (byte-verified difference),
-//!   and only `SetPlayerBuff` appends the duration-remaining line, which is **gold** again
-//!   (`0xffffd200`, the title's gold — B62; see [`render_spell`]'s tail).
-//!
-//! The engine renders VIEWS ([`SpellTooltipView`]) the app resolves at push time — the $-token
-//! substitution (values off Spell.dbc + the player's level), cast-time/duration/range text —
-//! because the catalogs and the token engine live app-side; the engine holds no DBC knowledge.
-//! Views are keyed by spell id in an ask-once store (the item-template store's pattern): a
-//! renderer miss records the id, the app resolves and pushes, the hover's re-enter repaints.
+//! The app resolves each spell into a [`SpellTooltipView`] (`$`-tokens, cast, range and duration
+//! text), kept in an ask-once store by spell id: a miss records the id, the app pushes the view and
+//! the next hover repaints.
 
 use mlua::{Lua, Table, Value};
 
@@ -28,82 +15,67 @@ use super::tooltip::{append_line, clear_content, fire_cleared};
 use super::{CraftTooltip, Model, TrainerTooltip};
 
 const WHITE: [f32; 4] = [1.0, 1.0, 1.0, 1.0];
-/// The rank column's gray — byte-verified `0xff808080` (0276).
+/// The rank column's gray, `0xff808080`.
 const GRAY: [f32; 4] = [128.0 / 255.0, 128.0 / 255.0, 128.0 / 255.0, 1.0];
-/// The description gold — byte-verified `0xffffd200` (0276).
+/// The description gold, `0xffffd200`.
 const GOLD: [f32; 4] = [1.0, 210.0 / 255.0, 0.0, 1.0];
 
-/// One spell's tooltip view — every string app-resolved (the $-engine's output for the
-/// description; the cost/range/cast/cooldown texts off the DBC catalogs).
+/// One spell's tooltip, every string resolved by the app.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct SpellTooltipView {
     pub name: String,
-    /// "Rank N" — the gray right column of the name line, on the SPELL variant only.
+    /// "Rank N", the name line's gray right column on the spell variant.
     pub rank: Option<String>,
-    /// "Magic" / "Curse" / "Disease" / "Poison" — the AURA variant's right column (`0x52f8e5`),
-    /// the `SpellDispelType.dbc` name of the spell's dispel class gated by that table's `[+0x28]`
-    /// flag, so an undispellable aura (Stealth) carries `None`. Rendered GOLD, like the aura name
-    /// it shares its line with — not the spell variant's gray.
+    /// The aura variant's gold right column (`0x52f8e5`): the `SpellDispelType.dbc` name, such as
+    /// "Magic", when that row's `[+0x28]` flag is set, so Stealth has none.
     pub dispel_type: Option<String>,
-    /// "35 Mana" / "20 Rage" / "20 Health" / "11 Health, plus 5 per sec" — the cost cell: the
-    /// RESOLVED cost through the power-type key array with the health fallback (1074).
+    /// The cost cell, such as "35 Mana" or "11 Health, plus 5 per sec": the resolved cost through
+    /// the power-type keys, falling back to health.
     pub cost: Option<String>,
-    /// "30 yd range" — the range cell.
     pub range: Option<String>,
-    /// "1.5 sec cast" / "Instant cast" / "Instant" / "Next melee" / "Attack speed" /
-    /// "Channeled" — `None` = a passive spell: the whole casttime|cooldown line is omitted
-    /// (the verified law; never a "Passive" text line).
+    /// The cast cell ("1.5 sec cast", "Instant", "Next melee", "Channeled"); `None` is a passive
+    /// spell, whose cast and cooldown line is omitted.
     pub cast_time: Option<String>,
-    /// "15 sec cooldown" — the cooldown cell: `max(RecoveryTime, CategoryRecoveryTime)` (the 0276
-    /// line law, `SPELL_RECAST_TIME_SEC 0x854ed4` — Charge's 15 s lives in the CATEGORY column).
+    /// The cooldown cell (`SPELL_RECAST_TIME_SEC 0x854ed4`): `max(RecoveryTime,
+    /// CategoryRecoveryTime)`, as Charge's 15 s is in the category column.
     pub cooldown: Option<String>,
-    /// "Requires Wands" — the equipped-item-class half (`SPELL_EQUIPPED_ITEM 0x854e94`), over
-    /// `EquippedItemClass`/`EquippedItemSubClassMask`: white when [`Self::item_met`], red when
-    /// not. Sits ABOVE [`Self::requires_form`] (the law's tool-then-form order).
+    /// "Requires Wands" (`SPELL_EQUIPPED_ITEM 0x854e94`), from `EquippedItemClass` and
+    /// `EquippedItemSubClassMask`.
     pub requires_item: Option<String>,
-    /// Whether some WORN item satisfies the class + subclass mask (the app re-pushes views when
-    /// the equipped set changes, so the color tracks live swaps).
+    /// A worn item matches the class and subclass mask; re-pushed on an equipment change.
     pub item_met: bool,
-    /// "Requires Battle Stance" — the required-form line (`SPELL_REQUIRED_FORM 0x854e64` over
-    /// the `Stances` mask): white when [`Self::form_met`], red when not.
+    /// "Requires Battle Stance" (`SPELL_REQUIRED_FORM 0x854e64`), from the `Stances` mask.
     pub requires_form: Option<String>,
-    /// Whether the player's CURRENT shapeshift form satisfies the mask (the app re-pushes views
-    /// on a form change, so the color tracks live stance switches).
+    /// The current shapeshift form matches the mask; the app re-pushes on a form change.
     pub form_met: bool,
-    /// "Reagents: Light Feather" — `SPELL_REAGENTS 0x854e54` ("Reagents: ", no format slot) +
-    /// the 8 reagent slots. Rendered WHITE and wrapped; a reagent the player is short of carries
-    /// the builder's own **inline** `|cffff2020` escape (the spell builder is the one builder
-    /// that colors mid-line), so the composed string arrives paint-ready from the app.
+    /// "Reagents: Light Feather" (`SPELL_REAGENTS 0x854e54` and the eight reagent slots); the app
+    /// writes a missing reagent's inline `|cffff2020` escape.
     pub reagents: Option<String>,
-    /// "2.62% chance to dodge" — `CHANCE_TO_DODGE 0x854e44` and its siblings, selected by the
-    /// spell's `Effect[0]` and rendered white and unwrapped, BELOW the reagents and ABOVE the
-    /// description. The
-    /// percentage is the player's own live avoidance/crit field, so the app re-pushes as it moves.
+    /// "2.62% chance to dodge" (`CHANCE_TO_DODGE 0x854e44` and its siblings, by `Effect[0]`),
+    /// from the player's live stat, which the app re-pushes as it moves.
     pub chance: Option<String>,
-    /// The $-substituted description — gold + wrapped for spells.
+    /// The `$`-substituted description.
     pub description: String,
-    /// The $-substituted AURA description (`Spell.dbc AuraDescription`) — the buff hover's
-    /// white text (byte-verified: the aura builder reads the aura column). Falls back to
-    /// `description` when empty.
+    /// The `$`-substituted `AuraDescription`, which the aura builder reads; `description` stands in
+    /// when it is empty.
     pub aura_description: String,
 }
 
 impl super::UiScript {
-    /// Store (or replace) a spell's tooltip view — the app's push half of the ask-once flow.
+    /// Store or replace a spell's view, answering its ask.
     pub fn set_spell_tooltip(&mut self, spell_id: u32, view: SpellTooltipView) {
         let mut model = self.model_mut();
         model.spell_tooltip_asks.remove(&spell_id);
         model.spell_tooltips.insert(spell_id, view);
     }
 
-    /// Drain the spell ids the renderers asked for that the store didn't have.
+    /// Drain the spell ids the renderers asked for and the store lacked.
     pub fn take_spell_tooltip_asks(&mut self) -> Vec<u32> {
         self.model_mut().spell_tooltip_asks.drain().collect()
     }
 }
 
-/// Look up the store; a miss records the ask. `pub(super)` for the talent tooltip's shared use
-/// (its display + next-rank spells ride this same ask-once channel — decision 0304).
+/// Look up a spell's view; a miss records the ask.
 pub(super) fn spell_view_of(lua: &Lua, spell_id: u32) -> Option<SpellTooltipView> {
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
     let v = model.spell_tooltips.get(&spell_id).cloned();
@@ -113,49 +85,35 @@ pub(super) fn spell_view_of(lua: &Lua, spell_id: u32) -> Option<SpellTooltipView
     v
 }
 
-/// The talent interleave for [`render_spell`] (decision 0304; the builder's own talent params —
-/// `TOOLTIP_TALENT_RANK 0x854a2c` / `TOOLTIP_TALENT_LEARN 0x8549f8`): the white "Rank r/m" after
-/// the name, the red requirement lines while locked (position CONFIRMED — decision 0305's residue:
-/// matches the builder law, after the rank line), the "Next rank:" block, and the green learn hint.
+/// The talent lines [`render_spell`] interleaves (`TOOLTIP_TALENT_RANK 0x854a2c`,
+/// `TOOLTIP_TALENT_LEARN 0x8549f8`): the white "Rank r/m" after the name, the red requirements
+/// while locked, the next-rank block and the green learn hint.
 #[derive(Clone, Debug, Default)]
 pub(super) struct TalentLines {
-    /// `TOOLTIP_TALENT_RANK` = "Rank %d/%d", already filled by the caller off the player's own
-    /// string table. `None` = the table does not carry the key, and the plate shows no rank row
-    /// (decision 2045 — never an invented one).
+    /// `TOOLTIP_TALENT_RANK` ("Rank %d/%d") filled from the player's strings; `None` when they
+    /// lack the key, and no rank row shows.
     pub rank_line: Option<String>,
     pub reqs: Vec<String>,
-    /// The next rank's spell id (0 = none) — asked from the spell store when its description
-    /// hasn't landed yet, so the hover's re-enter completes the block.
+    /// The next rank's spell id, 0 for none, asked from the store while `next_desc` is missing.
     pub next_spell: u32,
     pub next_desc: Option<String>,
     pub learn: bool,
 }
 
-/// `TOOLTIP_TALENT_LEARN 0x8549f8`'s green — the shared talent-learn green of the tooltip color
-/// table (`0xff00ff00`).
+/// The talent learn hint's green, `0xff00ff00`.
 const GREEN: [f32; 4] = [0.0, 1.0, 0.0, 1.0];
-/// The unmet-requirement red — `0xc0d390 = ffff2020` (the item builder's own RED value).
+/// The unmet-requirement red, `0xffff2020` (`0xc0d390`, the item builder's red).
 const RED: [f32; 4] = [1.0, 32.0 / 255.0, 32.0 / 255.0, 1.0];
 
-/// Render one spell view — the verified law (module doc). `aura` renders the aura variant:
-/// white description, plus the caller-supplied duration-remaining line (`SetPlayerBuff` only).
-/// `talent` interleaves the talent lines ([`TalentLines`] doc).
-/// The builder's parameter vector, named as the byte law names it (`0x52e610`'s param3..param8).
-/// These were three positional `bool`s at a
-/// 7-argument call site, which is exactly the shape that gets silently transposed; `Default` is the
-/// plain spell hover every caller but two wants.
+/// The spell builder's options (`0x52e610`'s parameters); `Default` is the plain spell hover.
 #[derive(Clone, Copy, Default)]
 pub(super) struct SpellRenderOpts {
-    /// Render through the AURA builder (`0x52f880`) rather than the spell builder: gold name, white
-    /// description, the dispel-class right column.
+    /// The aura builder (`0x52f880`): gold name, white description, the dispel class at right.
     pub(super) aura: bool,
-    /// `param6` showRank — the gray "Rank N" right column. `SetSpell` passes 0 (the spellbook hover
-    /// never shows it), `SetAction` passes 1.
+    /// `param6` showRank, the gray "Rank N" column: `SetSpell` passes 0, `SetAction` 1.
     pub(super) show_rank: bool,
-    /// `param5` altCaster — **one** gate suppressing **both** the totems and the reagents lines
-    /// (byte-verified at the two branch sites `0x52ed43` and `0x52f393`). Set only by
-    /// `SetTrainerService`, and only when the matched learn-wrapper slot was `LEARN_PET_SPELL`: a
-    /// pet-training service shows neither block.
+    /// `param5` altCaster, which drops the totem and reagent lines (`0x52ed43`, `0x52f393`); only
+    /// `SetTrainerService` sets it, for a `LEARN_PET_SPELL` service.
     pub(super) alt_caster: bool,
 }
 
@@ -172,24 +130,15 @@ fn render_spell(
         show_rank,
         alt_caster,
     } = opts;
-    // The name colour splits by BUILDER, byte-verified: the spell builder `0x52e610` writes its
-    // name line through `0x530270` (white), the aura builder `0x52f880` through `0x530380` — the
-    // GOLD wrapper. SetTrackingSpell's gold,
-    // already pinned by the director's own A/B, is the same wrapper.
+    // The spell builder writes the name white (`0x530270`), the aura builder gold (`0x530380`).
     let name_color = if aura { GOLD } else { WHITE };
-    // The name line's RIGHT column splits by builder too. The spell builder's is the gray "Rank N",
-    // and it shows only when the CALLER asks (byte-verified: SetSpell passes param6=0 — the
-    // spellbook hover never shows "Rank N"; SetAction passes 1). The aura builder's is the dispel
-    // class ("Magic" on Ice Armor — `0x52f8e5`), and it is GOLD, not gray: a buff never shows a
-    // rank.
     let right = if aura {
         v.dispel_type.clone().map(|t| (t, GOLD))
     } else {
         v.rank.clone().filter(|_| show_rank).map(|t| (t, GRAY))
     };
     append_line(lua, this, (v.name.clone(), name_color), right, false)?;
-    // The talent head: "Rank r/m" (builder line 2, TOOLTIP_TALENT_RANK white) + the red
-    // requirement lines while locked (position CONFIRMED, decision 0305 — TalentLines doc).
+    // The talent head: the white rank line, then the red requirements while locked.
     if let Some(t) = talent {
         if let Some(rank) = &t.rank_line {
             append_line(lua, this, (rank.clone(), WHITE), None, false)?;
@@ -199,7 +148,6 @@ fn render_spell(
         }
     }
     if !aura {
-        // Cost | Range — one line, either side optional.
         match (&v.cost, &v.range) {
             (Some(c), Some(r)) => append_line(
                 lua,
@@ -212,7 +160,6 @@ fn render_spell(
             (None, Some(r)) => append_line(lua, this, (r.clone(), WHITE), None, false)?,
             (None, None) => {}
         }
-        // CastTime | Cooldown — one line; a passive spell (cast_time None) omits it whole.
         if let Some(ct) = &v.cast_time {
             match &v.cooldown {
                 Some(cd) => append_line(
@@ -225,9 +172,6 @@ fn render_spell(
                 None => append_line(lua, this, (ct.clone(), WHITE), None, false)?,
             }
         }
-        // Required tool / form (`SPELL_EQUIPPED_ITEM 0x854e94` / `SPELL_REQUIRED_FORM 0x854e64`):
-        // the equipped-item-class line first, then the stance line. Each white when met, red when
-        // not.
         if let Some(req) = &v.requires_item {
             let color = if v.item_met { WHITE } else { RED };
             append_line(lua, this, (req.clone(), color), None, false)?;
@@ -236,15 +180,12 @@ fn render_spell(
             let color = if v.form_met { WHITE } else { RED };
             append_line(lua, this, (req.clone(), color), None, false)?;
         }
-        // Reagents (`SPELL_REAGENTS 0x854e54`): white + wrapped, the missing entries inline-red
-        // inside the text.
-        // Suppressed wholesale by altCaster — the same gate that hides the totems block, which we
-        // have no feed for yet, so this is the only half of it that is observable here.
+        // Reagents, white and wrapped, unless altCaster drops them; the totem line it also drops
+        // is not built.
         if let Some(reagents) = v.reagents.as_ref().filter(|_| !alt_caster) {
             append_line(lua, this, (reagents.clone(), WHITE), None, true)?;
         }
-        // Chance to dodge/parry/block/crit (`CHANCE_TO_DODGE 0x854e44` and its siblings) — white,
-        // NOT wrapped, and it sits here: below the reagents, above the description.
+        // The chance line, white and unwrapped, between the reagents and the description.
         if let Some(chance) = &v.chance {
             append_line(lua, this, (chance.clone(), WHITE), None, false)?;
         }
@@ -258,11 +199,9 @@ fn render_spell(
         let color = if aura { WHITE } else { GOLD };
         append_line(lua, this, (desc.clone(), color), None, true)?;
     }
-    // The talent tail: the TOOLTIP_TALENT_NEXT_RANK header (white, `0x854a10` pushed at
-    // `0x52b2cd`) over the next rank's gold description, and the green learn hint (builder
-    // line 13, TOOLTIP_TALENT_LEARN `0x8549f8` at `0x52b362`). Both are keys into the player's
-    // own string table (decision 2045); an install without them shows the description alone
-    // rather than a sentence of ours.
+    // The talent tail: the white `TOOLTIP_TALENT_NEXT_RANK` header (`0x854a10`, pushed at
+    // `0x52b2cd`) over the next rank's gold description, then the green `TOOLTIP_TALENT_LEARN`
+    // hint (`0x52b362`). Both are the player's own strings; without them the line is skipped.
     if let Some(t) = talent {
         if let Some(next) = &t.next_desc {
             if let Some(header) = crate::strings::global(lua, "TOOLTIP_TALENT_NEXT_RANK") {
@@ -276,20 +215,16 @@ fn render_spell(
             }
         }
     }
-    // The duration-remaining line (`SetPlayerBuff` only) is GOLD `0xffffd200` — the same gold as
-    // the aura title it sits under, NOT the description's white. Measured off a 1.12.1 reference
-    // shot of Ice Armor in Wetlands: the
-    // "29 minutes remaining" glyphs read exactly `(255, 210, 0)`, pixel-identical to that shot's
-    // "Ice Armor" / "Magic" title row, while its description rows read `(255, 255, 255)`.
+    // The time-remaining line (`SetPlayerBuff` only) is the title's gold `0xffffd200`, not the
+    // description's white: a 1.12.1 screenshot reads (255, 210, 0) on it.
     if let Some(rem) = remaining {
         append_line(lua, this, (rem, GOLD), None, false)?;
     }
     Ok(())
 }
 
-/// The talent tooltip's entry (decision 0304 — `GameTooltip:SetTalent`'s render half): the
-/// display spell through the shared store + the talent interleave. A missing next-rank view is
-/// re-asked so the hover's re-enter completes the block.
+/// `GameTooltip:SetTalent`'s render: the talent's spell plus its talent lines; a missing next-rank
+/// view is asked for.
 pub(super) fn set_spell_with_talent(
     lua: &Lua,
     this: &Table,
@@ -315,8 +250,7 @@ pub(super) fn set_spell_with_talent(
             Some(&talent),
         )?,
         None => {
-            // The view hasn't landed: show the talent head alone (the ask is recorded; the
-            // hover's re-enter repaints complete) — the spell channel's own fallback shape.
+            // No view yet: the rank line alone until the next hover.
             if let Some(rank) = &talent.rank_line {
                 append_line(lua, this, (rank.clone(), WHITE), None, false)?;
             }
@@ -326,10 +260,7 @@ pub(super) fn set_spell_with_talent(
     Ok(())
 }
 
-/// Shared entry: clear, render (or record the ask and show nothing but the name if the caller
-/// knows one), show.
-/// The reward-spell hover: the spell by id with the quest's own name as the fallback, or an
-/// empty tooltip.
+/// The reward-spell hover: the spell, its name as the fallback, or an empty tooltip.
 fn set_reward_spell(
     lua: &Lua,
     this: &Table,
@@ -375,27 +306,16 @@ pub(super) fn set_spell_by_id(
     Ok(())
 }
 
-/// Register the spell/aura content channels into the GameTooltip kind method table.
+/// Register the spell and aura content methods on the GameTooltip method table.
 pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
-    // GameTooltip:SetSpell(bookId, bookType) — the spellbook hover: the 1-based book slot resolves
-    // through the named book's state to a spell id.
-    //
-    // **`bookType` decides which book**, exactly like every `bookType`-taking global
-    // (`super::spellbook::book_slot`). Byte-verified in `SetSpell 0x532d10`, which is its own
-    // implementation of the same fork rather than a caller of the shared parser: arg2 → number,
-    // `- 1`, bounded `[0, 0x400)` (`0x532dd4`-`0x532df4`); arg3 → string, compared against the
-    // literal `"pet"` at `0x846960` (`0x532e13`); match takes `[4*i + 0xb6f098]` — the PET book —
-    // and sets `isPet = 1` (`0x532e1c`), everything else takes `[4*i + 0xb700f0]` (`0x532e2a`).
-    // That `isPet` then rides into `0x6e2ea0` as the cooldown BANK (`0x532e50`), the same bank
-    // split 1031 built.
-    //
-    // Before the fork, a pet-book hover indexed the PLAYER's slot list, so hovering the imp's first
-    // spell showed the player's first spell — "Attack", crit line and all (decision 1050).
+    // GameTooltip:SetSpell(bookId, bookType): the spellbook hover. `SetSpell 0x532d10` bounds the
+    // 1-based slot to `[0, 0x400)` (`0x532dd4`) and reads the pet book (`0xb6f098`) when `bookType`
+    // is "pet" (`0x532e13`), else the player's (`0xb700f0`); the pet flag also picks the cooldown
+    // bank it passes to `0x6e2ea0` (`0x532e50`).
     m.set(
         "SetSpell",
         lua.create_function(|lua, (this, book_id, book_type): (Table, u32, Value)| {
-            // The reference requires a STRING third argument and bails otherwise (`0x532dc0`'s
-            // `lua_isstring(3)` → `je` out); a non-string is therefore not "the player's book".
+            // A non-string `bookType` bails (`0x532dc0`) rather than meaning the player's book.
             let Some(book_type) = book_type.as_string().and_then(|s| s.to_str().ok()) else {
                 return Ok(());
             };
@@ -409,7 +329,7 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
             set_spell_by_id(lua, &this, spell_id, name, SpellRenderOpts::default(), None)
         })?,
     )?;
-    // GameTooltip:SetShapeshift(index) — the stance-bar hover (the form's own spell tooltip).
+    // GameTooltip:SetShapeshift(index): the stance-bar hover, the form's spell tooltip.
     m.set(
         "SetShapeshift",
         lua.create_function(|lua, (this, index): (Table, usize)| {
@@ -423,11 +343,9 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
             set_spell_by_id(lua, &this, spell_id, name, SpellRenderOpts::default(), None)
         })?,
     )?;
-    // GameTooltip:SetPetAction(index) — the pet-bar hover (decision 0982). Only ever reached for a
-    // SPELL slot: the reference's `PetActionButton_OnEnter` builds a token slot's tooltip inline
-    // from `tooltipName`/`tooltipSubtext` and never calls this. A slot with no spell (a token, an
-    // empty slot, an out-of-range index) is a no-op, leaving whatever was shown — the same shape
-    // as SetSpell's out-of-range.
+    // GameTooltip:SetPetAction(index): the pet-bar hover for a spell slot; the stock
+    // `PetActionButton_OnEnter` builds a token's tooltip itself (`PetActionBarFrame.lua:290`). A
+    // slot with no spell is a no-op.
     m.set(
         "SetPetAction",
         lua.create_function(|lua, (this, index): (Table, usize)| {
@@ -449,29 +367,11 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
             set_spell_by_id(lua, &this, spell_id, name, SpellRenderOpts::default(), None)
         })?,
     )?;
-    // GameTooltip:SetPlayerBuff(buffIndex) — the buff-bar hover: the aura variant (white
-    // AuraDescription) + the duration-remaining line only this entry point appends (byte-verified;
-    // remaining computed live off the aura's GetTime expiry). The line's TEXT is no longer interim:
-    // `0x52fa50`'s four-arm ladder and its rounding pin it, and
-    // `tooltip::duration_text` is it.
-    //
-    // **The argument is a 1.12 CACHE POSITION, not a filtered ordinal** — the same 0-based handle
-    // `GetPlayerBuff` returns and every `GetPlayerBuff*` sibling consumes (see
-    // `super::aura`'s header). `ref-BuffFrame.lua:105` is the pin: `GameTooltip:SetPlayerBuff(buffIndex)`
-    // where `buffIndex` came straight out of `GetPlayerBuff`, never from the button's own id.
-    //
-    // This corrects a real defect: the binding previously read a 1-based index within the
-    // sign-filtered list, so of the corpus's 21 call sites — all of which pass a cache position —
-    // every position >= 1 resolved one aura too early, no debuff was ever reachable (the sign
-    // defaulted to helpful), and `SetPlayerBuff(-1)` showed the FIRST buff instead of nothing.
-    // That last one is load-bearing: `BigWigs/Raids/Naxxramas/Loatheb.lua:260-271` feeds an
-    // unchecked `GetPlayerBuff(i, "HARMFUL")` straight in and terminates its scan on the tooltip's
-    // first line going nil.
-    //
-    // A miss (out of range, negative, empty cache) routes through the shared entry with spell id 0,
-    // exactly like SetUnitBuff's: content clears and the plate hides, never a stale tooltip left
-    // showing. Any surplus argument is ignored — `CT_BuffMod/CT_BuffFrame.lua:151` passes a filter
-    // string the reference's own binding never reads.
+    // GameTooltip:SetPlayerBuff(buffIndex): the aura variant plus the time-remaining line only
+    // this entry appends, its text `0x52fa50`'s (`tooltip::duration_text`). The argument is the
+    // 0-based cache position `GetPlayerBuff` returns (`BuffFrame.lua:105`), not a filtered
+    // ordinal. A miss, negative included, clears and hides the plate as `SetUnitBuff`'s does; a
+    // surplus argument is ignored, as in the reference.
     m.set(
         "SetPlayerBuff",
         lua.create_function(|lua, (this, index): (Table, i64)| {
@@ -486,33 +386,25 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                     .and_then(|pos| model.auras.get("player").and_then(|a| a.get(pos)));
                 match hit {
                     Some(a) => {
-                        // The gate is `untilCancelled`, NOT "does this aura have a duration yet".
-                        // `0x532b00` skips the whole duration block when the
-                        // cache record's `+0xc` is set (`532bda: 8b 46 0c` / `532bdf: 75 2d`), so
-                        // a permanent aura shows title + description and nothing more. That flag
-                        // is DBC-derived, so it is already right on the frame an aura appears —
-                        // before any `SMSG_UPDATE_AURA_DURATION` lands — which is exactly why
-                        // `AuraState::until_cancelled`'s own doc calls it a different question
-                        // from `expiration_time == 0.0`. Gating on the duration (what this did)
-                        // blanked the line for a timed aura's first frames, and hid the
-                        // reference's own "0 seconds remaining" once one lapsed.
+                        // The gate is `untilCancelled`, not a known duration: `0x532b00` skips
+                        // the line when the record's `+0xc` is set (`0x532bdf`), a DBC flag that
+                        // holds before any `SMSG_UPDATE_AURA_DURATION` lands; a lapsed aura shows
+                        // "0 seconds remaining".
                         let ms = (!a.until_cancelled).then(|| {
-                            // The reference counts integer milliseconds off GetTickCount; ours is
-                            // a float second clock, so this is the nearest millisecond to it.
+                            // The reference counts integer milliseconds off `GetTickCount`;
+                            // this rounds the float clock to the nearest one.
                             ((a.expiration_time - now) * 1000.0)
                                 .round()
                                 .clamp(0.0, f64::from(u32::MAX)) as u32
                         });
                         (a.spell_id, a.name.clone(), ms)
                     }
-                    // The miss clears rather than leaving the previous plate up — the same shape
-                    // SetUnitBuff uses, and the one Loatheb's scan depends on: it breaks its loop
-                    // when TextLeft1 reads nil, so a stale line would never let it terminate.
+                    // A miss clears: an addon scan that stops when `TextLeft1` reads nil would
+                    // otherwise never end.
                     None => (0, None, None),
                 }
             };
-            // The text is `0x52fa50`'s, over the player's own GlobalStrings — never a string of
-            // ours. Off an install the table is absent and the line simply does not render.
+            // `0x52fa50`'s text from the player's own strings; without them the line is skipped.
             let remaining = remaining_ms.and_then(|ms| {
                 let g = lua.globals();
                 super::tooltip::duration_text(ms, "SPELL_TIME_REMAINING", true, &|key| {
@@ -532,22 +424,13 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
             )
         })?,
     )?;
-    // GameTooltip:SetUnitBuff(unit, index) / SetUnitDebuff(unit, index) — the target frame's aura
-    // hover: the same aura variant (white AuraDescription), WITHOUT the duration-remaining line —
-    // byte-verified, only SetPlayerBuff appends it (and no other unit has a duration on the 1.12
-    // wire anyway). The index counts within the sign-filtered list, the UnitBuff/UnitDebuff
-    // convention.
+    // GameTooltip:SetUnitBuff/SetUnitDebuff(unit, index): the aura variant with no time line; the
+    // 1-based index counts within the helpful or harmful list, as `UnitBuff` does.
     for (verb, helpful) in [("SetUnitBuff", true), ("SetUnitDebuff", false)] {
         m.set(
             verb,
-            // `index` is `Value`, not `i64`, and that is a fidelity fix rather than laxity — the
-            // same correction `SetTexture` already carries. A C binding reads what it wants off
-            // the Lua stack: `lua_tonumber` on nil yields 0, which finds no aura and shows
-            // nothing. Typing it `i64` made us RAISE on a call the real client accepts silently.
-            //
-            // Found by the use-probe: `CT_AssistFrameDebuff1:OnEnter` calls
-            // `SetUnitDebuff(unit, this:GetID())` and the id is nil on a frame CT_UnitFrames
-            // created without one. It only fires on hover, so nothing before the probe saw it.
+            // `index` is a `Value`: the reference's `lua_tonumber` reads nil as 0, which finds no
+            // aura, where an `i64` would raise.
             lua.create_function(move |lua, (this, token, index): (Table, String, Value)| {
                 let index = match &index {
                     Value::Integer(i) => *i,
@@ -568,9 +451,8 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                         .and_then(|a| a.iter().filter(|a| a.helpful == helpful).nth(idx))
                         .map(|a| (a.spell_id, a.name.clone()))
                 };
-                // A miss (index past the list, unknown token) still routes through the shared
-                // entry with spell id 0: content clears and the empty plate hides — never a
-                // stale previous tooltip left showing. Id 0 records no ask.
+                // A miss goes through with spell id 0, which clears and hides the plate and
+                // records no ask.
                 let (spell_id, name) = hit.unwrap_or((0, None));
                 set_spell_by_id(
                     lua,
@@ -586,13 +468,9 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
             })?,
         )?;
     }
-    // GameTooltip:SetTrackingSpell() — the minimap tracking icon's hover: NAME gold over a white
-    // (aura-)description, pinned by the director's reference A/B (2026-07-20: "Find Minerals"
-    // gold over white "Finding Minerals."). That is just the AURA builder's shape — its name line
-    // rides the gold wrapper `0x530380` too — so this is no longer a one-off; `0x532c50`'s body
-    // is still unconfirmed in the binary, so read it before extending BEYOND that shape. No
-    // duration-remaining line (only SetPlayerBuff appends one), and no tracking active clears +
-    // hides, like the SetUnitBuff miss path.
+    // GameTooltip:SetTrackingSpell(): the tracking icon's hover, the name gold over the white
+    // aura description, as the reference shows "Find Minerals" and as the aura builder's gold
+    // wrapper `0x530380` writes it; `0x532c50` itself is untraced. No tracking clears and hides.
     m.set(
         "SetTrackingSpell",
         lua.create_function(|lua, this: Table| {
@@ -623,8 +501,7 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                     }
                 }
                 None => {
-                    // The view hasn't landed (ask recorded; the re-enter repaints): the name
-                    // alone, in the same gold.
+                    // No view yet: the name alone, gold.
                     if let Some(name) = fallback_name {
                         append_line(lua, &this, (name, GOLD), None, false)?;
                     }
@@ -634,21 +511,9 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // GameTooltip:SetAction(slot) — the action-bar hover: pure delegation by payload kind
-    // (`0x5322a0`, byte-verified: SPELL 0x00 → the spell builder `0x52e610`, ITEM 0x80 → the item
-    // builder `0x52b650`, MACRO 0x40 → `0x52b040`).
-    //
-    // The MACRO arm is the reference's whole `0x52b040`: fetch the record (`0x4f0f40`), and either
-    // hide (no record) or render ONE line — the macro's NAME (`rec+0x24`) — through the
-    // single-coloured-line wrapper `0x5303b0` in the "normal" colour `0xc0cf60`, which is WHITE
-    // (`0xffffffff`, never rewritten). Not the spell title's gold, and nothing about the bound
-    // spell: 1.12 has no
-    // `#showtooltip`. This arm was a `_ => Ok(())` left from before 0983 shipped macros, which is
-    // why a macro on the bar hovered to nothing (the director, 2026-08-27, after 1636).
-    // GameTooltip:SetQuestRewardSpell() / SetQuestLogRewardSpell() — the hover of the reward
-    // slot stock marks `rewardType = "spell"` (QuestFrameTemplates.xml:150, QuestLogFrame.xml:115;
-    // bindings 0x535bb0 / 0x535c60, self only, 0 returns): the quest's reward spell by id through
-    // the spell renderer, an empty tooltip when the quest rewards none.
+    // GameTooltip:SetQuestRewardSpell() / SetQuestLogRewardSpell() (`0x535bb0`, `0x535c60`): the
+    // hover of a reward slot whose `rewardType` is "spell" (`QuestFrameTemplates.xml:150`,
+    // `QuestLogFrame.xml:115`), the quest's reward spell or an empty tooltip.
     m.set(
         "SetQuestRewardSpell",
         lua.create_function(|lua, this: Table| {
@@ -676,6 +541,10 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
             set_reward_spell(lua, &this, id)
         })?,
     )?;
+    // GameTooltip:SetAction(slot): the action-bar hover by payload kind (`0x5322a0`): a spell
+    // (0x00) to the spell builder `0x52e610`, an item (0x80) to the item builder `0x52b650`, a
+    // macro (0x40) to `0x52b040`, which fetches it (`0x4f0f40`) and renders only its name, white
+    // (`0x5303b0` in colour `0xc0cf60`), or hides with none; 1.12 has no `#showtooltip`.
     m.set(
         "SetAction",
         lua.create_function(|lua, (this, slot): (Table, u32)| {
@@ -697,7 +566,6 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                     None,
                 ),
                 0x80 => {
-                    // Route through the shared item renderer (the id-keyed entry).
                     let f: mlua::Function = this.get("BenillaSetItemById")?;
                     f.call::<()>((this.clone(), a.action))
                 }
@@ -706,8 +574,8 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                     let name = {
                         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
                         clear_content(&mut model, h);
-                        // The same 1..36 index lookup `GetActionText` and the bar's icon arm
-                        // make, so the three can never disagree about which macro a slot holds.
+                        // The same 1..36 lookup as `GetActionText` and the bar icon, so the
+                        // three agree on a slot's macro.
                         model.macros.get(a.action as usize).map(|m| m.name.clone())
                     };
                     fire_cleared(lua, h);
@@ -722,19 +590,10 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GameTooltip:SetTrainerService(index) — the trainer detail-icon hover (ref
-    // `Blizzard_TrainerUI.xml:452`, whose OnEnter is SetOwner(this,"ANCHOR_RIGHT") +
-    // SetTrainerService(ClassTrainerFrame.selectedService) + Show(); the LIST ROWS carry no tooltip
-    // at all).
-    //
-    // The binding is a **selector, not a renderer**: `0x5338b0` emits no line of its own (verified
-    // negative — none of the four AddLine helpers appears in its extent) and hands one of the two
-    // shared builders a subject. The subject is decided app-side, because the law reads `Spell.dbc`
-    // fields the engine cannot see, and arrives pre-resolved as `TrainerService::tooltip`. All this
-    // does is pick the renderer — which is exactly what the reference binding does.
-    //
-    // `index` is a **VISIBLE** row index (headers interleave), resolved through the same mapping
-    // every other trainer getter uses; a header row is a no-op.
+    // GameTooltip:SetTrainerService(index): the trainer detail icon's hover
+    // (`Blizzard_TrainerUI.xml:452`); list rows have no tooltip. `0x5338b0` writes no line itself
+    // and hands a shared builder the subject the app resolved (`TrainerService::tooltip`). `index`
+    // is a visible row, headers included; a header is a no-op.
     m.set(
         "SetTrainerService",
         lua.create_function(|lua, (this, index): (Table, usize)| {
@@ -746,9 +605,8 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 }
             };
             match subject {
-                // Route through the shared item renderer, the way the reference routes into
-                // `0x52b650`. No fallback name: an item id of 0 or a template still in flight
-                // renders an EMPTY tooltip, which is the builder's own early-out.
+                // The item builder (`0x52b650`), with no fallback name: id 0 or a template in
+                // flight renders empty, the builder's own early-out.
                 TrainerTooltip::Item(item_id) => {
                     let f: mlua::Function = this.get("BenillaSetItemById")?;
                     f.call::<()>((this.clone(), item_id))
@@ -770,17 +628,10 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
             }
         })?,
     )?;
-    // GameTooltip:SetCraftSpell(craftIndex) — the Craft window's detail-icon hover (ref
-    // `CraftIcon`'s OnEnter, `Blizzard_CraftUI.xml:566`). `SetTrainerService`'s structural twin and
-    // its law's opposite (`SetCraftSpell 0x533e90`): a selector into
-    // the same two shared builders, deciding on the RECIPE's own effect columns rather than a
-    // taught spell's attributes. The subject arrives pre-resolved as `CraftRecipe::tooltip`.
-    //
-    // This replaced a v1 two-line "name white, description gold" render. That was wrong in both
-    // halves: `0x533e90` funnels into `0x52e610`/`0x52b650` like every other content binding, so
-    // two lines were eight-plus short, and on a `LEARN_SPELL` or `CREATE_ITEM` recipe it was
-    // describing the wrong subject entirely. `craft_index` is a raw recipe position — the Craft
-    // window is FLAT, with no headers to interleave (unlike the tradeskill list).
+    // GameTooltip:SetCraftSpell(craftIndex): the craft detail icon's hover
+    // (`Blizzard_CraftUI.xml:566`). `SetCraftSpell 0x533e90` hands a shared builder the subject the
+    // app resolved from the recipe's own effects (`CraftRecipe::tooltip`). `craftIndex` is a plain
+    // recipe position: the craft list has no headers.
     m.set(
         "SetCraftSpell",
         lua.create_function(|lua, (this, craft_index): (Table, usize)| {
diff --git a/crates/benilla-ui/src/script/tooltip_unit.rs b/crates/benilla-ui/src/script/tooltip_unit.rs
index 08bfc84c..d22b8a78 100644
--- a/crates/benilla-ui/src/script/tooltip_unit.rs
+++ b/crates/benilla-ui/src/script/tooltip_unit.rs
@@ -1,40 +1,12 @@
-//! The engine **unit tooltip builder** (decision 0274 P3) — the byte-verified line law of
-//! `0x529fe0` (the 0276 fold-back):
-//!
-//! - NAME (gold — FrameXML recolors `TextLeft1` by reaction on `UPDATE_MOUSEOVER_UNIT`, exactly
-//!   like the reference's `GameTooltip_UnitColor`; the guild line is likewise FrameXML's and
-//!   joins when guild data streams). A name still in flight reads `UNKNOWNOBJECT`, never an
-//!   empty line — the builder's name read is `0x609210`, the same resolver `UnitName` uses, and
-//!   its miss tail is the same string (decisions 2002/2040);
-//! - the creature SUBTITLE ("Stable Master") — white;
-//! - the LEVEL line, filled from three slots into one of the four `TOOLTIP_UNIT_LEVEL*` templates
-//!   the player's own `GlobalStrings.lua` carries (decision 2045 — the keys are the builder's,
-//!   read off `0x52a622`/`0x52a64d`/`0x52a682`/`0x52a6ac`, never matched on their English):
-//!   level text (`"??"` for a world boss, a much-higher hostile, or level ≤ 0 — the hostile
-//!   delta is INTERIM at +10 pending a byte pin of the comparison), the class slot (the creature
-//!   TYPE word for hostile/neutral creatures, `"Race Class"` for players, `CORPSE` when dead),
-//!   and the type slot (the rank key table `{"", ELITE, ELITE, BOSS, ""}`; `PLAYER` for players);
-//! - the FACTION NAME ("Stormwind", white) — the builder-tail block `0x52a7a0..`, which our
-//!   emission order originally omitted: the app resolves it (`faction_name`), every gate applied;
-//! - "PvP" (white) · "Skinnable" (**red**) · "Civilian" (green, `0x612550`: PvP-flagged +
-//!   query-civilian + HOSTILE + GREY/trivial — the dishonorable-kill warning) · "Leader"
-//!   (white, `0x6125c0`: PvP-flagged + query racial_leader);
-//! - health on the attached status bar (`<name>StatusBar`, the template child below the plate),
-//!   refreshed by every `set_unit` push for the live token — the byte law's HEALTH watcher.
-//!
-//! The world mouseover drives this through [`super::UiScript::world_tooltip_unit`] (the engine
-//! shows the tooltip at the default anchor by firing `OnTooltipSetDefaultAnchor`, renders, and
-//! fires `UPDATE_MOUSEOVER_UNIT` for the Lua recolor) and [`super::UiScript::world_tooltip_fade`]
-//! (the byte law ARMS a fade on hover loss, not an instant hide). Unit-frame hovers call the
-//! same `SetUnit` from Lua.
+//! The engine unit tooltip, in `0x529fe0`'s line order: the name (gold; FrameXML recolours it by
+//! reaction), the creature subtitle, the level line, the faction name, then "PvP", "Skinnable",
+//! "Civilian" and "Leader", with health on the `<name>StatusBar` child. The world mouseover drives
+//! it through [`super::UiScript::world_tooltip_unit`]; unit-frame hovers call `SetUnit` from Lua.
 
 use mlua::{Lua, Table};
 
 use super::object::frame_handle_of;
 use super::tooltip::{append_line, clear_content, fire_cleared, show_or_hide_empty, tip_mut};
-// The grey band + trivial/GREY check (`0x5f0700`, the CIVILIAN line's last gate: a green-or-
-// better con never warns of a dishonorable kill) and the "??" gate live in one shared home
-// (`unit.rs`), alongside `UnitLevel`'s −1 return and the `GetQuestGreenRange` binding.
 use super::unit::{is_civilian_kill, level_reads_unknown, unknownobject};
 use super::{KindState, Model, UnitState};
 use crate::layout::{Anchor, Point};
@@ -44,35 +16,29 @@ use crate::widget::FrameHandle;
 const WHITE: [f32; 4] = [1.0, 1.0, 1.0, 1.0];
 const GREEN: [f32; 4] = [0.0, 1.0, 0.0, 1.0];
 const RED: [f32; 4] = [1.0, 32.0 / 255.0, 32.0 / 255.0, 1.0];
-/// `0xc0d420` = `0xff40c040` — the satisfiable-lock green (see [`TooltipTint::LockOpen`]).
+/// `0xc0d420` = `0xff40c040`, the satisfiable-lock green.
 const LOCK_OPEN: [f32; 4] = [64.0 / 255.0, 192.0 / 255.0, 64.0 / 255.0, 1.0];
-/// Unit names render gold (byte-verified `0xffffd200`); FrameXML recolors line 1 by reaction.
+/// `0xffffd200`, the unit name's colour until FrameXML recolours it by reaction.
 const GOLD: [f32; 4] = [1.0, 210.0 / 255.0, 0.0, 1.0];
 
-/// A GameObject tooltip line's colour, as the builder `0x52aa20` picks it (decision 0756). The
-/// app half decides *which* line gets which tint from the lock law; this enum is only the
-/// crate-boundary spelling, so the colour constants stay private to the UI engine.
+/// A GameObject tooltip line's colour, as the builder `0x52aa20` picks it; the app picks the tint
+/// for each line.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum TooltipTint {
-    /// `0xc0cf60` — the requirement line's normal colour (the key-item "Requires %s").
+    /// `0xc0cf60`: a requirement line's normal colour (the key item's "Requires %s").
     White,
-    /// The "Locked" line's UNMET colour `0xc0d3a8` = `0xffff2020`, and the unknown-skill
-    /// "Requires %s" (whose own red is `0xffff0000` — a difference of 32/255 in G and B that no
-    /// eye resolves, so one slot serves both).
+    /// `0xc0d3a8` = `0xffff2020`, the unmet "Locked" line. Deviation: the unknown-skill
+    /// "Requires %s" shares it, though its reference red is `0xffff0000`, because a 32/255
+    /// difference in G and B does not show.
     Red,
-    /// The "Locked" line when the lock **is** satisfiable — `0xc0d420` = `0xff40c040`
-    /// (64,192,64). Deliberately NOT the tooltip's ordinary green `0xc0d3ac` = `0xff00ff00`: this
-    /// is the second rung of the skill-difficulty ramp `0x529fa0` (grey/green/yellow/orange/red,
-    /// static-init writers at `0x5290d0` &c.), which the lock line borrows wholesale, and it is a
-    /// visibly softer green than the one every other tooltip line uses.
+    /// The satisfiable "Locked" line: `0xc0d420` = `0xff40c040`, the green rung of the
+    /// skill-difficulty ramp `0x529fa0`, not the ordinary green `0xc0d3ac` = `0xff00ff00`.
     LockOpen,
 }
 
-/// The rank word's GlobalString **key** — byte-verified `0x854158[]`, the pointer table the
-/// builder indexes by rank at `0x52a5bd`/`0x52a5d4`. Its entries are key names, not words: index 0
-/// and 4 are the pre-seeded empty string `0x882748`, 1 and 2 are both `ELITE` (rare-elite prints
-/// ELITE, rare prints nothing — there is no distinct "Rare Elite" word in 1.12's builder), 3 is
-/// `BOSS`.
+/// The rank word's GlobalString key, from the builder's table `0x854158` (indexed at `0x52a5bd`
+/// and `0x52a5d4`): ranks 1 and 2 (elite, rare elite) are `ELITE`, 3 is `BOSS`, and 0 and 4 (rare)
+/// are the empty string `0x882748`.
 fn rank_key(rank: u32) -> Option<&'static str> {
     match rank {
         1 | 2 => Some("ELITE"),
@@ -81,31 +47,19 @@ fn rank_key(rank: u32) -> Option<&'static str> {
     }
 }
 
-/// The level line — three slots over the four `TOOLTIP_UNIT_LEVEL*` templates, each resolved off
-/// the player's own `GlobalStrings.lua` (decision 2045). The keys are the builder's own, pushed at
-/// `0x52a622` (`_CLASS_TYPE`), `0x52a64d` (`_CLASS`), `0x52a682` (`_TYPE`) and `0x52a6ac` (the
-/// bare one) — which matters, because `TOOLTIP_UNIT_LEVEL_CLASS`'s enUS "Level %s %s" is also the
-/// wording of `FRIENDS_LEVEL_TEMPLATE`, `UNIT_TYPE_LEVEL_TEMPLATE` and `CHARACTER_SELECT_INFO`,
-/// and the bare one collides with `ITEM_LEVEL`, `LEVEL_GAINED` and `UNIT_LEVEL_TEMPLATE`. Seven
-/// wrong keys are reachable by matching the English here; none by reading the builder.
-///
-/// `None` = the install's string table carries no template for the slot combination in hand, and
-/// the plate shows no level row rather than a composed one.
+/// The level line: level, class and type slots in one of the four `TOOLTIP_UNIT_LEVEL*`
+/// GlobalStrings, keyed as the builder keys them (`0x52a622` `_CLASS_TYPE`, `0x52a64d` `_CLASS`,
+/// `0x52a682` `_TYPE`, `0x52a6ac` bare), never by their English, which other keys share. `None`
+/// when the install has no template for the combination, and then no row shows.
 fn level_line(lua: &Lua, u: &UnitState, player_level: u32) -> Option<String> {
     let get = |key: &str| crate::strings::global(lua, key);
-    // The "??" gate, byte-pinned (`0x529fe0`): much-higher HOSTILE — internal reaction
-    // ≤ 1 = hated/hostile = UnitReaction ≤ 2 on our 1..8 API scale (the UnitIsEnemy mapping) —
-    // with playerLevel ≤ targetLevel−10; OR WorldBoss; OR level ≤ 0. Players NEVER read "??".
-    // Shared with `UnitLevel`'s −1 return, so the tooltip and the target frame can never
-    // disagree on who reads "??" ([`level_reads_unknown`]).
+    // "??" by the gate `UnitLevel`'s -1 shares (`0x529fe0`), so tooltip and target frame agree.
     let level_text = if level_reads_unknown(u, player_level) {
         "??".to_string()
     } else {
         u.level.to_string()
     };
-    // The class slot: "Race Class" for players; the creature TYPE word for hostile/neutral
-    // creatures (a friendly creature shows none — the byte law's hostile/neutral-only gate);
-    // "Corpse" when dead.
+    // `CORPSE` when dead, "Race Class" for a player, the creature type only if hostile or neutral.
     let class_slot = if u.dead {
         get("CORPSE")
     } else if u.is_player {
@@ -120,7 +74,6 @@ fn level_line(lua: &Lua, u: &UnitState, player_level: u32) -> Option<String> {
     } else {
         None
     };
-    // The type slot: the rank word, or PLAYER for players.
     let type_slot = if u.is_player {
         get("PLAYER")
     } else {
@@ -160,23 +113,13 @@ fn render_unit(lua: &Lua, this: &Table, token: &str) -> mlua::Result<bool> {
     }
     fire_cleared(lua, h);
     let Some(u) = unit else {
-        // No unit: drop the live token and leave the tooltip hidden-empty.
         set_live_token(lua, h, None);
         show_or_hide_empty(lua, h);
         return Ok(false);
     };
-    // The NAME line. A unit whose name query has not answered yet does NOT title an empty plate:
-    // the builder resolves the name through `CGUnit_C::GetUnitName 0x609210` (`0x52a187`), and
-    // every one of that function's misses — a creature whose `creaturecache.wdb` record
-    // (`CGUnit+0xb30`) is still null, a pet whose `petnamecache.wdb` row is absent or stale, a
-    // player row `namecache.wdb` has not answered — falls to the SAME
-    // `FrameScript_GetText("UNKNOWNOBJECT")` tail `UnitName` falls to. One seam, one resolver
-    // ([`unknownobject`], decisions 2002/2040), so the verb and the plate can never disagree.
-    //
-    // The builder has no counterpart to `UnitName`'s two nils: the `"player"` fast path is the
-    // *binding's* (`0x517083`, before any resolve), and a token resolving to GUID 0 never reaches
-    // a builder at all — the entry gate `0x468460(typemask 8)` hands back no object, `SetUnit`
-    // answers nil and no plate is drawn (the `unit` early-return above).
+    // The name: `CGUnit_C::GetUnitName` `0x609210` (`0x52a187`), whose every miss falls to
+    // `UNKNOWNOBJECT`, as `UnitName`'s does. A token with no object never reaches the builder
+    // (`0x468460`): no plate, and `SetUnit` answers nil.
     let title = match &u.name {
         Some(n) => n.clone(),
         None => unknownobject(lua)?.to_str()?.to_string(),
@@ -188,8 +131,7 @@ fn render_unit(lua: &Lua, this: &Table, token: &str) -> mlua::Result<bool> {
     if let Some(level) = level_line(lua, &u, player_level) {
         append_line(lua, this, (level, WHITE), None, false)?;
     }
-    // The faction-name line ("Stormwind", white) sits between the level line and "PvP" — the
-    // builder-tail block at `0x52a7a0`. The app resolved every gate into `faction_name`.
+    // The faction name, between the level line and "PvP" (`0x52a7a0`); the app applied its gates.
     if let Some(faction) = &u.faction_name {
         append_line(lua, this, (faction.clone(), WHITE), None, false)?;
     }
@@ -199,15 +141,11 @@ fn render_unit(lua: &Lua, this: &Table, token: &str) -> mlua::Result<bool> {
     if u.skinnable {
         append_line(lua, this, ("Skinnable".into(), RED), None, false)?;
     }
-    // CIVILIAN (green) — `0x612550`, whole: the unit's PvP bit + the query civilian flag + the
-    // unit is HOSTILE to the player (UnitReaction ≤ 2 — internal reaction < 2) + the kill would
-    // be GREY/trivial. PVP_RANK_CIVILIAN = "Civilian" (extracted GlobalStrings). The predicate
-    // itself lives in `unit` because `UnitPVPName` gates its own civilian arm on the same call.
+    // "Civilian" (`0x612550`): PvP-flagged, a civilian, hostile, and grey to kill (`0x5f0700`).
     if is_civilian_kill(&u, player_level) {
         append_line(lua, this, ("Civilian".into(), GREEN), None, false)?;
     }
-    // LEADER (white) — `0x6125c0`: the PvP bit + the query racial_leader flag, no other gate.
-    // PVP_RANK_LEADER = "Leader" (extracted GlobalStrings).
+    // "Leader" (`0x6125c0`): PvP-flagged and a racial leader, no other gate.
     if u.racial_leader && u.pvp {
         append_line(lua, this, ("Leader".into(), WHITE), None, false)?;
     }
@@ -227,7 +165,7 @@ fn set_world_owned(lua: &Lua, h: FrameHandle) {
     }
 }
 
-/// Remember (or drop) the tooltip's live unit token — the health watcher's key.
+/// Remember (or drop) the tooltip's live unit token, the health watcher's key.
 fn set_live_token(lua: &Lua, h: FrameHandle, token: Option<String>) {
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
     if let Some(f) = model.arena.frame_mut(h) {
@@ -237,8 +175,8 @@ fn set_live_token(lua: &Lua, h: FrameHandle, token: Option<String>) {
     }
 }
 
-/// Drive the `<name>StatusBar` child from a unit snapshot (`None` hides it) — the engine pushes
-/// health, FrameXML's `HealthBar_OnValueChanged` colors the fill.
+/// Drive the `<name>StatusBar` child from a unit snapshot (`None` hides it); FrameXML's
+/// `HealthBar_OnValueChanged` colours the fill.
 fn update_bar(lua: &Lua, h: FrameHandle, unit: Option<&UnitState>) {
     let bar = {
         let model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -289,13 +227,12 @@ fn update_bar(lua: &Lua, h: FrameHandle, unit: Option<&UnitState>) {
     }
 }
 
-/// The `set_unit` push hook: a fresh snapshot for the tooltip's LIVE token re-drives the health
-/// bar (the byte law's HEALTH UpdateField watcher — the bar tracks without a line rebuild).
+/// A `set_unit` push for a tooltip's live token updates its health bar without rebuilding the
+/// lines, as the reference's HEALTH field watcher does.
 pub(super) fn on_unit_push(lua: &Lua, token: &str) {
     let hits: Vec<FrameHandle> = {
         let model = lua.app_data_mut::<Model>().expect("model app_data");
-        // The arena's tooltip registry (1634), gated by the resolve's roster exactly as the walk
-        // it replaces was — `update_bar` writes layout.
+        // Registered frames only, as `update_bar` writes layout.
         model
             .arena
             .tooltip_kinds()
@@ -320,11 +257,9 @@ pub(super) fn on_unit_push(lua: &Lua, token: &str) {
 }
 
 impl super::UiScript {
-    /// Show the world-mouseover unit tooltip (the engine-driven flow the byte law describes):
-    /// fire `OnTooltipSetDefaultAnchor` (FrameXML seats the plate at the default corner), render
-    /// `token`'s snapshot, fire `UPDATE_MOUSEOVER_UNIT` (FrameXML recolors the name line by
-    /// reaction). Call on hover-target CHANGE — the health bar tracks pushes in between; a
-    /// re-show mid-fade resurrects at full alpha. `false` = no tooltip frame / no such unit.
+    /// Show the world-mouseover unit tooltip: fire `OnTooltipSetDefaultAnchor`, render `token`,
+    /// fire `UPDATE_MOUSEOVER_UNIT`. Call on a hover-target change; a re-show mid-fade returns to
+    /// full alpha. `false` when there is no tooltip frame or no such unit.
     pub fn world_tooltip_unit(&mut self, token: &str) -> bool {
         let h = {
             let mut model = self.model_mut();
@@ -356,7 +291,6 @@ impl super::UiScript {
         };
         if shown {
             set_world_owned(&self.lua, h);
-            // Cancel any running fade at full alpha (a re-hover resurrects).
             let mut model = self.model_mut();
             if let Some(f) = model.arena.frame_mut(h) {
                 if let KindState::Tooltip(t) = &mut f.kind_state {
@@ -371,25 +305,12 @@ impl super::UiScript {
         shown
     }
 
-    /// Show the world-mouseover GAMEOBJECT tooltip — the byte-verified GO builder `0x52aa20`
-    /// (decisions 0276 / **0756**): the NAME (gold) followed by the lock lines the caller
-    /// resolved, each with its own tint.
-    ///
-    /// **The anchor FORKS per object — it is not uniform** (decision 0766, correcting 0756). The
-    /// publisher's GameObject leg calls the picked object's `[obj->vtbl+0x5c]` and branches:
-    ///
-    /// - **true** (`0x492a01`) → `0x52ffe0(owner, 6, 0, 0)` — anchor-state **6**, the *cursor*
-    ///   anchor. Corroborated by the loss path: `0x530ae0` hides an anchor-state-6 tooltip
-    ///   **immediately** instead of arming the fade, which is how a pointer-following label behaves.
-    /// - **false** (`0x492a42`) → no `SetOwner` at all; the plate keeps its default corner seat.
-    ///
-    /// The **unit** leg (`0x492983`) never consults `+0x5c` — units are always corner-seated, which
-    /// is why the fork went unnoticed when 0756 made every GameObject corner-seated too. `cursor`
-    /// carries the caller's verdict: `Some(ui_xy)` = the cursor arm (and then
-    /// [`Self::world_tooltip_move`] follows the pointer), `None` = the corner.
-    ///
-    /// Same fade lifecycle as the unit flow (no `UPDATE_MOUSEOVER_UNIT` — that recolor is the
-    /// unit line's).
+    /// Show the world-mouseover GameObject tooltip (builder `0x52aa20`): the name in gold, then
+    /// the caller's lock lines. The anchor forks on the object's `[vtbl+0x5c]`: true (`0x492a01`)
+    /// seats it at the cursor, anchor state 6 (`0x52ffe0(owner, 6, 0, 0)`); false (`0x492a42`)
+    /// keeps the default corner, as units (`0x492983`) always do. `cursor` is that verdict, and
+    /// [`Self::world_tooltip_move`] follows a cursor-seated plate. Hover loss arms the unit flow's
+    /// fade, where the reference's loss path (`0x530ae0`) hides an anchor-state-6 plate at once.
     pub fn world_tooltip_gameobject(
         &mut self,
         name: &str,
@@ -408,31 +329,15 @@ impl super::UiScript {
             (h, id, root, root_id)
         };
         match cursor {
-            // The cursor arm: seated centred above the pointer, clamped by the tooltip frame's own
-            // flag. Compare-then-touch so a still pointer never re-layouts.
+            // The cursor arm: centred above the pointer; compare-then-touch, so a still pointer
+            // never re-layouts.
             Some((ui_x, ui_y)) => {
                 let mut model = self.model_mut();
-                // **The OWNER, which this arm used to skip** (decision 2255). The
-                // reference's cursor arm is `0x492a01 → 0x52ffe0(owner, 6, 0, 0)` — the SetOwner
-                // CORE, not a bare re-anchor — and the core's `0x53000c` stores that owner into
-                // `+0x314`. Every OTHER world plate we build reaches an owner by accident: the
-                // corner arm below and the unit flow both fire `OnTooltipSetDefaultAnchor`, whose
-                // FrameXML handler calls `GameTooltip:SetOwner(UIParent, …)` in Lua. This arm
-                // fires nothing, so `+0x314` stayed NULL on exactly the cursor-seated objects —
-                // a signpost, a mailbox, every GENERIC(5).
-                //
-                // A null owner is not cosmetic, because **`:Show()` is an existence gate**:
-                // `0x530a80` shows only when `+0x314` AND `+0x31c` are both non-zero, and
-                // otherwise takes the effective-hide `0x530a60` — which we implement faithfully
-                // (see the `Show` verb). So any Lua that reached `GameTooltip:Show()` while one of
-                // these plates was up HID IT, and hid it through our own correct code.
-                //
-                // That is not hypothetical: `!Questie` hooks GameTooltip's `OnShow` at
-                // PLAYER_LOGIN (`Questie:hookTooltip`, installed because stock GameTooltip has no
-                // OnShow of its own) and its handler ends in `GameTooltip:Show()`. So the plate's
-                // own show event hid the plate, ~26 ms after the engine built it, on every
-                // signpost, for the whole session — the director's report. The reference cannot
-                // reach that state: `0x492a01` writes the owner before the plate is ever shown.
+                // The owner: this arm is the SetOwner core (`0x52ffe0`), which stores it at
+                // `+0x314` (`0x53000c`); the other arms get theirs from FrameXML's
+                // `OnTooltipSetDefaultAnchor`. Without one, any Lua `GameTooltip:Show()` hides the
+                // plate: `0x530a80` shows only when `+0x314` and `+0x31c` are both set, else it
+                // takes `0x530a60`.
                 if let Ok(t) = tip_mut(&mut model, h) {
                     t.owner = Some(root);
                 }
@@ -445,7 +350,7 @@ impl super::UiScript {
                     model.touch_layout();
                 }
             }
-            // The corner arm: the same default-anchor handler the unit flow fires.
+            // The corner arm: the default-anchor handler the unit flow fires too.
             None => {
                 if let Err(e) = super::event::fire_widget_handler(
                     &self.lua,
@@ -500,13 +405,10 @@ impl super::UiScript {
         true
     }
 
-    /// Show the minimap BLIP tooltip — a landmark's `AreaPOI` name or a quest-dot NPC's name,
-    /// one GOLD line (the reference's engine SetText gold; a cross-interior dot renders FAINT
-    /// gold — the byte law's `|cffb0b0b0` wrap modulating the gold base, director-matched),
-    /// seated centred ABOVE the cursor: the tooltip's BOTTOM at the given UI-space point. The
-    /// plate FOLLOWS the pointer — `Self::minimap_tooltip_move` re-seats it as the cursor
-    /// drifts within one blip. Same world-owned fade lifecycle as the mouseover tooltip:
-    /// hover loss arms [`Self::world_tooltip_fade`].
+    /// Show the minimap blip tooltip (an `AreaPOI` or quest-dot name): one gold line, faint gold
+    /// for a cross-interior dot, its bottom at the given UI point above the cursor.
+    /// [`Self::world_tooltip_move`] follows the pointer, and hover loss arms
+    /// [`Self::world_tooltip_fade`].
     pub fn minimap_tooltip(&mut self, text: &str, ui_x: f32, ui_y: f32, grey: bool) -> bool {
         let (h, id, root_id) = {
             let mut model = self.model_mut();
@@ -530,13 +432,10 @@ impl super::UiScript {
             let mut model = self.model_mut();
             clear_content(&mut model, h);
             let input = model.layout_inputs.entry(h).or_default();
-            // Anchor only — the screen clamp (G flags bit4: a cursor-seated plate near the window
-            // edge slides back in instead of clipping, director's report at the screen-right
-            // minimap) is the tooltip FRAME's own flag (`Frame::clamped_to_screen`), synced with
-            // live extents at every resolve.
+            // Anchor only: the frame's own clamp flag (`Frame::clamped_to_screen`, G flags bit 4)
+            // slides a plate near the window edge back on screen.
             let new = Anchor::new(Point::Bottom, root_id, Point::BottomLeft, ui_x, ui_y);
-            // Compare-then-touch: a still cursor re-seats the plate at the same point every
-            // frame — tier 1 of the layout gate stays quiet unless the pointer actually moved.
+            // Compare-then-touch, so a still cursor does not dirty the layout.
             let same =
                 input.anchors.len() == 1 && super::object::anchor_bits_eq(&input.anchors[0], &new);
             if !same {
@@ -545,10 +444,7 @@ impl super::UiScript {
             }
         }
         fire_cleared(&self.lua, h);
-        // The blip name renders GOLD like the reference (the engine tooltip's SetText line —
-        // the same 0xffffd200 the unit-name line uses); a cross-interior entry renders the
-        // byte law's `|cffb0b0b0` wrap MODULATING that gold — faint gold, not flat grey
-        // (director-matched against the reference, 2026-07-13).
+        // A cross-interior entry's `|cffb0b0b0` wrap modulates the gold: faint gold, not grey.
         let dim = 0xb0 as f32 / 255.0;
         let color = if grey {
             [GOLD[0] * dim, GOLD[1] * dim, GOLD[2] * dim, 1.0]
@@ -574,9 +470,7 @@ impl super::UiScript {
         true
     }
 
-    /// Re-seat the showing cursor-anchored tooltip at a new pointer point (the follow half of
-    /// [`Self::minimap_tooltip`] and [`Self::world_tooltip_gameobject`]): anchor-only — no
-    /// content rebuild, no fade churn. No-op when the tooltip isn't the world-owned shown plate.
+    /// Re-seat the shown world-owned tooltip at a new pointer point, anchor only; else a no-op.
     pub fn world_tooltip_move(&mut self, ui_x: f32, ui_y: f32) {
         let mut model = self.model_mut();
         let Some(h) = model.arena.lookup("GameTooltip") else {
@@ -595,11 +489,8 @@ impl super::UiScript {
         }
         let root_id = model.frame_id(root);
         let input = model.layout_inputs.entry(h).or_default();
-        // Anchor only — the frame's own clamp flag keeps the plate on screen (see
-        // `Frame::clamped_to_screen`).
         let new = Anchor::new(Point::Bottom, root_id, Point::BottomLeft, ui_x, ui_y);
-        // Compare-then-touch, as in the seat/blip paths above: the follow fires per pointer
-        // event, and a still cursor must not dirty the layout gate's tier 1.
+        // Compare-then-touch: this runs on every pointer event.
         let same =
             input.anchors.len() == 1 && super::object::anchor_bits_eq(&input.anchors[0], &new);
         if !same {
@@ -608,12 +499,8 @@ impl super::UiScript {
         }
     }
 
-    /// **Is `GameTooltip` still the plate a world hover put up?** — world-owned (no Lua
-    /// `SetOwner`, no content `Set*` and no `Hide` has taken it since) and still shown.
-    ///
-    /// The world-hover driver keeps a host-side memo of which plate it put up so it does not
-    /// rebuild one per frame; that memo is about the HOVER, and this is the other half of the
-    /// question — whether the plate that memo describes is still on the screen.
+    /// Whether `GameTooltip` is still the shown plate a world hover put up, with no Lua
+    /// `SetOwner`, content `Set*` or `Hide` since.
     pub fn world_tooltip_up(&mut self) -> bool {
         let model = self.model_mut();
         let Some(h) = model.arena.lookup("GameTooltip") else {
@@ -626,8 +513,8 @@ impl super::UiScript {
             .unwrap_or(false)
     }
 
-    /// Arm the mouseover tooltip's fade-out (hover loss — the byte law arms a timestamped fade,
-    /// never an instant hide). No-op when the tooltip isn't showing a world unit.
+    /// On hover loss, arm the world tooltip's timed fade (the reference's unit plate fades rather
+    /// than hiding); a no-op unless a world-owned plate is shown.
     pub fn world_tooltip_fade(&mut self) {
         let now = self.now();
         let mut model = self.model_mut();
@@ -646,15 +533,12 @@ impl super::UiScript {
 
 /// Register the unit content channel into the GameTooltip kind method table.
 pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
-    // GameTooltip:SetUnit(token) → 1/nil — the unit-frame hover (ref UnitFrame_OnEnter reads
-    // the return to arm its re-poll).
+    // GameTooltip:SetUnit(token) → 1 or nil, which `UnitFrame_OnEnter` reads to arm its re-poll.
     m.set(
         "SetUnit",
         lua.create_function(|lua, (this, token): (Table, String)| {
-            // Same gate as every `Unit*` verb: `SetUnit` resolves its argument through the client's
-            // one token resolver, so an unrecognised name raises here too rather than drawing an
-            // empty tooltip. NOT inside `render_unit` — the app's own push calls that with a
-            // canonical token and must never be gated against itself.
+            // The token gate every `Unit*` verb uses: an unknown token raises. Not in
+            // `render_unit`, which the app calls with canonical tokens.
             crate::script::unit::check_unit_token(&Some(token.clone()))?;
             let ok = render_unit(lua, &this, &token)?;
             Ok(if ok {
diff --git a/crates/benilla-ui/src/script/trade.rs b/crates/benilla-ui/src/script/trade.rs
index d753a981..fc9f68c2 100644
--- a/crates/benilla-ui/src/script/trade.rs
+++ b/crates/benilla-ui/src/script/trade.rs
@@ -1,29 +1,7 @@
-//! The player-to-player trade bindings (decision 0592 P1) — the two-sided trade-window surface, the
-//! same push/intent seam as [`super::mail`]/[`super::merchant`]: the app pushes a **trade snapshot**
-//! ([`UiScript::set_trade`] — both sides' slots already resolved from the wire to name/icon/quality
-//! by the app's item-template + display caches, and the partner's name from the name cache) and the
-//! Lua `InitiateTrade`/`AcceptTrade`/`CloseTrade`/… calls queue outbound **intents** the app drains.
-//! The engine holds no trade knowledge — a slot is a resolved item view, a side is seven slots + a
-//! gold amount, and the accept-glow is a fired event, never read state.
-//!
-//! ## The 5875 API shape (VERIFIED against the extracted `TradeFrame.lua`)
-//!
-//! `id` is **1-based** everywhere (slots 1..=7; slot 7 is the non-traded / enchant slot); an
-//! out-of-range or empty slot answers `nil`. The read getters:
-//! `GetTradePlayerItemInfo(id)` → `name, texture, numItems, isUsable, enchantment` (our own offer),
-//! `GetTradeTargetItemInfo(id)` → `name, texture, numItems, quality, isUsable, enchantment` (the
-//! partner's offer — the extra `quality` drives its slot's colour + the red not-usable tint),
-//! `GetPlayerTradeMoney()`/`GetTargetTradeMoney()` → the two gold amounts in copper, and
-//! `GetTradePartnerName()` → the partner's name (benilla's getter for the window header, in place of
-//! the reference's `UnitName("NPC")`; the partner's *portrait* rides the `"npc"` token the app points
-//! at the partner entity — decision 0592, [`crate::script`] has no engine-side unit for it).
-//! `enchantment` is `nil` in P1 (the enchant-slot spell name is decision 0592 P3).
-//!
-//! The intents: `InitiateTrade(unit)` queues the right-click menu's trade offer (the app resolves the
-//! unit token → guid → `CMSG_INITIATE_TRADE`); `AcceptTrade()`/`CancelTradeAccept()`/`CloseTrade()`
-//! flag the accept / un-accept / cancel verbs the app maps to `CMSG_ACCEPT_TRADE` /
-//! `CMSG_UNACCEPT_TRADE` / `CMSG_CANCEL_TRADE`. Setting items/gold onto the window (the drag-drop
-//! slots + the money widget) is decision 0592 P2.
+//! The trade bindings: the app pushes both sides of the open trade ([`UiScript::set_trade`]), and
+//! the trade verbs queue intents it drains. Slots are 1-based, 1..=7, the seventh the non-traded
+//! enchant slot; an empty or out-of-range slot answers nil. The partner rides the `"npc"` unit,
+//! which the app points at them.
 
 use mlua::{Lua, MultiValue, Value};
 
@@ -31,63 +9,48 @@ use super::binding_abi::flag;
 use super::cursor::{self, CursorPayload};
 use super::Model;
 
-/// The seven trade slots per side (`TRADE_SLOT_COUNT`, vmangos `TradeData.h`) — six tradeable
-/// (1..=6) plus the seventh non-traded / enchant slot. Mirrors the wire's fixed count without a
-/// `benilla-protocol` dependency (this crate is engine-only).
+/// Slots per side, six traded and the non-traded enchant slot: vmangos `TRADE_SLOT_COUNT`
+/// (`TradeData.h`), kept equal to the protocol crate's, which this crate does not depend on.
 pub const TRADE_SLOTS: usize = 7;
 
-/// One resolved trade slot, as the app pushes it (decision 0592) — the wire `TradeItem`'s
-/// entry/display resolved through the shared item-template + display caches. Plain data; an empty
-/// slot is `None` in [`TradeSideState::slots`], never a zeroed `Some`.
+/// One filled trade slot, resolved by the app; an empty slot is `None`, never a zeroed `Some`.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TradeSlotItem {
-    /// The item template entry (`0` never stored — an empty slot is `None`) — the `isUsable` gate's
-    /// key over the shared item-template store, and the slot tooltip's identity (decision 0592 P2).
+    /// The item entry, the key for `isUsable` and the tooltip.
     pub item_id: u32,
-    /// The item name (from the template); `None` while the ask-once template answer is in flight.
+    /// `None` while the item template is in flight.
     pub name: Option<String>,
-    /// The item icon (from the wire `display_id` via `ItemDisplayInfo.dbc`); `None` while in flight.
     pub texture: Option<String>,
-    /// The stack count in this slot (`>= 1` for a filled slot).
     pub count: u32,
-    /// The item quality (0..=6); `None` while the template is in flight. Read only for the target
-    /// side (the recipient slot's quality colour + red not-usable tint — `TradeFrame.lua` l.84).
+    /// `None` while the template is in flight; only the target side's info returns it
+    /// (`TradeFrame.lua:84`).
     pub quality: Option<u32>,
-    /// The enchant-slot spell name (slot 7 only) — `None` in P1 (the applied-spell path is
-    /// decision 0592 P3).
+    /// The name of the enchant being applied to slot 7, which stock shows in green
+    /// (`TradeFrame.lua:62`); the app always sends `None`.
     pub enchantment: Option<String>,
-    /// The slot's full escaped `|cff…|Hitem:…|h[Name]|h|r` link — `GetTradePlayerItemLink` /
-    /// `GetTradeTargetItemLink`'s answer, and `None` while the ask-once template answer is in
-    /// flight (the link embeds the name and the quality colour).
-    ///
-    /// The same shape as [`super::merchant::MerchantItem::link`] and for the same reason: 1.12's
-    /// own `TradeFrame.lua` hands it straight to `DressUpItemLink` on a ctrl-click and to
-    /// `ChatFrameEditBox:Insert` on a shift-click, so it is a string the app already knows rather
-    /// than anything the engine composes.
+    /// The escaped item link the link verbs answer; `None` while the template is in flight, since
+    /// it embeds the name and the quality.
     pub link: Option<String>,
 }
 
-/// One side of the trade window — the seven slots (1-based in the API) plus the gold offered on
-/// this side, in copper. `player` is our own offer, `target` the partner's ([`TradeState`]).
+/// One side's offer.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TradeSideState {
-    /// The seven slots (index 0 = trade slot 1 … index 6 = the enchant slot); `None` = empty.
+    /// Index 0 is trade slot 1, index 6 the enchant slot.
     pub slots: [Option<TradeSlotItem>; TRADE_SLOTS],
-    /// Gold offered on this side, in copper.
+    /// In copper.
     pub gold: u32,
 }
 
-/// The open trade window's snapshot. Pushed whole by the app; `None` = no trade open (the window is
-/// closed). The accept-glow state is **not** here — it rides the fired `TRADE_ACCEPT_UPDATE` event,
-/// never a getter (the reference `TradeFrame_SetAcceptState`, `TradeFrame.lua` l.116).
+/// The open trade, pushed whole by the app. The accept highlight is not here: it rides the
+/// `TRADE_ACCEPT_UPDATE` event (`TradeFrame.lua:35`).
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TradeState {
-    /// Our own offer (the wire's `their_window == false` snapshot).
+    /// Our offer.
     pub player: TradeSideState,
-    /// The partner's offer (the wire's `their_window == true` snapshot).
+    /// The partner's offer, the wire's `their_window` snapshot.
     pub target: TradeSideState,
-    /// The partner's name, resolved by the app through the name cache; `None` while in flight. The
-    /// window header reads this (benilla's `GetTradePartnerName()` in place of `UnitName("NPC")`).
+    /// The partner's name for `GetTradePartnerName()`, `None` while in flight.
     pub partner_name: Option<String>,
 }
 
@@ -97,65 +60,55 @@ impl super::UiScript {
         self.model_mut().trade = state;
     }
 
-    /// Drain the unit tokens `InitiateTrade` queued since the last drain — the app resolves each
-    /// token → player guid and sends `CMSG_INITIATE_TRADE`.
+    /// Drain the tokens `InitiateTrade` queued; the app sends `CMSG_INITIATE_TRADE` for each.
     pub fn take_trade_initiates(&mut self) -> Vec<String> {
         std::mem::take(&mut self.model_mut().trade_initiates)
     }
 
-    /// Whether `AcceptTrade` was called since the last drain (and clear the flag) — the app maps it
-    /// to `CMSG_ACCEPT_TRADE`.
+    /// Whether `AcceptTrade` was called since the last drain: `CMSG_ACCEPT_TRADE`.
     pub fn take_trade_accept(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().trade_accept)
     }
 
-    /// Whether `CancelTradeAccept` was called since the last drain — the app maps it to
-    /// `CMSG_UNACCEPT_TRADE` (drop your accept, stay in the trade).
+    /// Whether `CancelTradeAccept` was called since the last drain: `CMSG_UNACCEPT_TRADE`.
     pub fn take_trade_unaccept(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().trade_unaccept)
     }
 
-    /// Whether `CloseTrade` was called since the last drain — the app maps it to `CMSG_CANCEL_TRADE`
-    /// and clears its local trade session (the window's OnHide close verb).
+    /// Whether `CloseTrade`, the window's OnHide verb, was called since the last drain; the app
+    /// sends `CMSG_CANCEL_TRADE` and ends its session.
     pub fn take_trade_close(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().trade_close)
     }
 
-    /// Whether `BeginTrade()` was called since the last drain — `CMSG_BEGIN_TRADE`, empty
-    /// (decision 1963; the TRADE dialog that calls it can never show in 1.12.1, so this is an
-    /// addon's reach).
+    /// Whether `BeginTrade()` was called since the last drain: an empty `CMSG_BEGIN_TRADE`.
     pub fn take_trade_begin(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().trade_begin)
     }
 
-    /// Whether `CancelTrade()` was called since the last drain — the BARE `CMSG_CANCEL_TRADE`,
-    /// where `CloseTrade` wraps the same opcode in the window's teardown (decision 1963).
+    /// Whether `CancelTrade()` was called since the last drain: the bare `CMSG_CANCEL_TRADE`.
     pub fn take_trade_cancel(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().trade_cancel)
     }
 
-    /// The copper amount `SetTradeMoney` last offered since the last drain (and clear it) — the app
-    /// maps it to `CMSG_SET_TRADE_GOLD` (decision 0592 P2).
+    /// The copper `SetTradeMoney` last offered since the last drain: `CMSG_SET_TRADE_GOLD`.
     pub fn take_trade_money(&mut self) -> Option<u32> {
         std::mem::take(&mut self.model_mut().trade_set_money)
     }
 
-    /// The `(trade_id, bag, slot)` placements `ClickTradeButton` queued since the last drain — the app
-    /// maps each `(bag, slot)` through its wire-position map to `CMSG_SET_TRADE_ITEM` (decision 0592 P2).
-    /// `trade_id` is 1-based (1..=7); `bag`/`slot` are the engine's cursor space (0 backpack …).
+    /// The `(trade_id, bag, slot)` placements `ClickTradeButton` queued, for `CMSG_SET_TRADE_ITEM`:
+    /// `trade_id` 1..=7, `bag` and `slot` in the cursor's space.
     pub fn take_trade_set_items(&mut self) -> Vec<(u32, i64, u32)> {
         std::mem::take(&mut self.model_mut().trade_set_items)
     }
 
-    /// The 1-based trade slot ids `ClickTradeButton` queued to clear (empty-cursor click on a filled
-    /// slot) — the app maps each to `CMSG_CLEAR_TRADE_ITEM` (decision 0592 P2).
+    /// The 1-based slots `ClickTradeButton` queued to clear, for `CMSG_CLEAR_TRADE_ITEM`.
     pub fn take_trade_clear_items(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().trade_clear_items)
     }
 }
 
-/// Fetch a cloned slot for a 1-based index off one side, or `None` (out of range / empty / no trade
-/// open). `pick` selects the side from the pushed [`TradeState`].
+/// The slot at a 1-based index on the side `pick` selects.
 fn slot_at(
     model: &Model,
     index: usize,
@@ -170,20 +123,16 @@ fn slot_at(
         .flatten()
 }
 
-/// The gold on one side (copper), or `0` if no trade is open.
 fn gold(model: &Model, pick: impl Fn(&TradeState) -> &TradeSideState) -> u32 {
     model.trade.as_ref().map(pick).map_or(0, |side| side.gold)
 }
 
-/// A click on OUR trade slot `id` (1-based) as a cursor drop target (decision 0592 P2, ref
-/// `ClickTradeButton`, TradeFrame.xml l.135): a held bag item drops in — queue a `(id, bag, slot)`
-/// placement the app maps to `CMSG_SET_TRADE_ITEM` — and the cursor is **cleared** (the 0218
-/// plain-clear: no local held copy, the filled slot reads back from `SMSG_TRADE_STATUS_EXTENDED`). An
-/// empty cursor on a filled slot queues a clear (`CMSG_CLEAR_TRADE_ITEM`; the item never left the bag,
-/// the server just un-references it). A spell/action payload is refused, put back untouched.
+/// `ClickTradeButton(id)` on our slot (`TradeFrame.xml:135`): a held bag item is queued for
+/// `CMSG_SET_TRADE_ITEM` and the cursor cleared, the app filling our column itself since vmangos
+/// echoes a placement only to the partner (`TradeData.cpp:81`); an empty cursor on a filled slot
+/// queues a clear. Any other payload stays on the cursor.
 fn click_trade_button(model: &mut Model, id: u32) {
-    // The money arm runs first and never reads the index (`0x4bfe34`, decision 1965): coins on
-    // the cursor go into the offer as `AddTradeMoney` puts them, and that is the whole click.
+    // Coins on the cursor go into the offer, the index unread (`0x4bfe34`).
     if matches!(model.cursor, Some(CursorPayload::Money(_))) {
         cursor::money::add_trade_money(model);
         return;
@@ -217,8 +166,7 @@ fn click_trade_button(model: &mut Model, id: u32) {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetTradePlayerItemInfo(id) → name, texture, numItems, isUsable, enchantment (our own offer;
-    // TradeFrame.lua l.55). An empty/out-of-range slot answers nil.
+    // GetTradePlayerItemInfo(id): the five values `TradeFrame.lua:55` reads.
     g.set(
         "GetTradePlayerItemInfo",
         lua.create_function(|lua, id: usize| {
@@ -249,13 +197,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradePlayerItemLink(id) / GetTradeTargetItemLink(id) → the slot's escaped item link, or
-    // nil for an empty slot / one whose template answer is still in flight.
-    //
-    // 1.12's `TradeFrame.lua` reaches for these on a modified click of a trade slot — ctrl hands
-    // the link to `DressUpItemLink`, shift inserts it into the chat box — the same pair of arms
-    // the merchant rows have, which is why this mirrors `GetMerchantItemLink` exactly rather than
-    // composing anything here.
+    // The link verbs, for a slot's ctrl and shift clicks (`TradeFrame.xml:129`, `:95`).
     for (name, side) in [
         ("GetTradePlayerItemLink", true),
         ("GetTradeTargetItemLink", false),
@@ -280,8 +222,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // GetTradeTargetItemInfo(id) → name, texture, numItems, quality, isUsable, enchantment (the
-    // partner's offer; TradeFrame.lua l.84 — the extra `quality` is the recipient-only colour).
+    // GetTradeTargetItemInfo(id): the six values `TradeFrame.lua:84` reads.
     g.set(
         "GetTradeTargetItemInfo",
         lua.create_function(|lua, id: usize| {
@@ -317,8 +258,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPlayerTradeMoney() / GetTargetTradeMoney() → the two gold amounts, copper (TradeFrame.lua
-    // l.165/l.585). 0 when no trade is open.
     g.set(
         "GetPlayerTradeMoney",
         lua.create_function(|lua, ()| {
@@ -334,8 +273,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradePartnerName() → the partner's name (benilla's header getter, in place of the
-    // reference's UnitName("NPC") — see the module doc). nil while in flight / no trade open.
+    // `GetTradePartnerName()` is not a 1.12 global; the stock header reads `UnitName("NPC")`
+    // (`TradeFrame.lua:43`).
     g.set(
         "GetTradePartnerName",
         lua.create_function(|lua, ()| {
@@ -349,8 +288,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // InitiateTrade(unit) — queue the right-click menu's trade offer against a unit token; the app
-    // resolves it → player guid → CMSG_INITIATE_TRADE (the UnitPopup TRADE row, decision 0592 P1).
+    // InitiateTrade(unit): the unit menu's TRADE row.
     g.set(
         "InitiateTrade",
         lua.create_function(|lua, unit: String| {
@@ -362,8 +300,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // AcceptTrade() / CancelTradeAccept() / CloseTrade() — the Trade / un-accept / cancel verbs the
-    // app maps to CMSG_ACCEPT_TRADE / CMSG_UNACCEPT_TRADE / CMSG_CANCEL_TRADE (decision 0592 P1).
     g.set(
         "AcceptTrade",
         lua.create_function(|lua, ()| {
@@ -391,10 +327,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // BeginTrade() / CancelTrade() — the TRADE dialog's pair (`0x48aa60`/`0x48aa70`:
-    // 0 args, 0 returns, no gate; `0x117` and `0x11C`, both empty). The dialog itself can never
-    // show in 1.12.1 (TRADE_REQUEST is signalled by nothing), so both are an addon's reach;
-    // CancelTrade is the bare packet, CloseTrade above the same opcode wrapped in the teardown.
+    // BeginTrade() and CancelTrade() (`0x48aa60`, `0x48aa70`): no arguments, no returns, no gate,
+    // and an empty `0x117` or `0x11C`. They are the `TRADE` popup's Yes and No
+    // (`StaticPopup.lua:517-522`), which never shows in 1.12 as nothing signals `TRADE_REQUEST`.
     g.set(
         "BeginTrade",
         lua.create_function(|lua, ()| {
@@ -414,14 +349,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetTradeMoney(copper) — offer this many copper on our side (the money input's value-changed
-    // callback); the app maps it to CMSG_SET_TRADE_GOLD (decision 0592 P2). `i64` in, clamped, so a
-    // fractional/negative Lua number can never panic the coercion.
+    // SetTradeMoney(copper): the money input's callback (`TradeFrame.lua:173`).
     g.set(
         "SetTradeMoney",
         lua.create_function(|lua, copper: Value| {
-            // `0x4c0820` (decision 1965): a non-number RAISES; the low dword goes on the wire as an
-            // absolute offer, gated on the purse covering it — a refusal is silent at every level.
+            // `0x4c0820`: a non-number raises; the low dword is the whole offer, sent only when the
+            // purse covers it, and a refusal is silent.
             let n = crate::script::binding_abi::number_arg(
                 lua,
                 copper,
@@ -436,8 +369,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ClickTradeButton(id) — drop a held bag item into / clear our trade slot `id` (1..=7); the app
-    // maps it to CMSG_SET_TRADE_ITEM / CMSG_CLEAR_TRADE_ITEM (decision 0592 P2).
     g.set(
         "ClickTradeButton",
         lua.create_function(|lua, id: u32| {
@@ -447,14 +378,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ClickTargetTradeButton(id) — the partner's column is read-only (their offer is server-driven);
-    // inert in P2 (the shift-click item link is decision 0592 P3). Registered so the shared slot
-    // handler can call it for the recipient side without erroring.
+    // ClickTargetTradeButton(id) (`TradeFrame.xml:101`): the partner's column takes nothing.
     g.set(
         "ClickTargetTradeButton",
         lua.create_function(|lua, _id: u32| {
-            // The same money arm as `ClickTradeButton` (`0x4c00a3`, decision 1965): coins on the
-            // cursor go into OUR offer whichever side's slot was clicked, the index unread.
+            // Coins on the cursor still go into our offer, the index unread (`0x4c00a3`).
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
             cursor::money::add_trade_money(&mut model);
             Ok(())
@@ -502,12 +430,6 @@ mod tests {
         }
     }
 
-    /// **The two link verbs**, and the two absences they share with every other item-link reader
-    /// here: an empty slot, and a slot whose ask-once template answer has not landed.
-    ///
-    /// 1.12's `TradeFrame.lua` reaches for these on a modified click of a trade slot — ctrl hands
-    /// the link to `DressUpItemLink`, shift inserts it into the chat box. They were two of the four
-    /// engine verbs the readiness probe reports against stock `TradeFrame.xml`.
     #[test]
     fn the_trade_slots_answer_their_item_links() {
         let mut s = UiScript::new().unwrap();
@@ -520,7 +442,7 @@ mod tests {
             .unwrap());
 
         let mut st = state();
-        // A slot whose template is still in flight carries no link — the string embeds the name.
+        // A slot whose template is in flight has no link.
         st.target.slots[1] = Some(TradeSlotItem {
             item_id: 4306,
             name: None,
@@ -542,7 +464,7 @@ mod tests {
                 .unwrap(),
             "|cffffffff|Hitem:4306:0:0:0|h[Linen Cloth]|h|r"
         );
-        // …the in-flight slot, and an empty one, and one past the seven.
+        // The in-flight slot, an empty one, and one past the seven.
         assert!(s
             .eval::<bool>("return GetTradeTargetItemLink(2) == nil")
             .unwrap());
@@ -565,7 +487,6 @@ mod tests {
 
         s.set_trade(Some(state()));
 
-        // Player slot 1: name, texture, count 5, isUsable 1, enchantment nil.
         let (name, tex, count, usable): (String, String, i64, i64) = s
             .eval(
                 "local n,t,c,u,e = GetTradePlayerItemInfo(1)\n\
@@ -577,12 +498,11 @@ mod tests {
         assert!(s
             .eval::<bool>("local n,t,c,u,e = GetTradePlayerItemInfo(1)\nreturn e == nil")
             .unwrap());
-        // An empty player slot → nil.
         assert!(s
             .eval::<bool>("return GetTradePlayerItemInfo(2) == nil")
             .unwrap());
 
-        // Target slot 1 carries the extra quality (index 4 of the 6-tuple).
+        // The target side adds quality as the fourth return.
         let (name, _tex, count, quality, usable): (String, String, i64, i64, i64) =
             s.eval("return GetTradeTargetItemInfo(1)").unwrap();
         assert_eq!(
@@ -643,13 +563,12 @@ mod tests {
         assert!(s.take_trade_close());
         assert!(!s.take_trade_close(), "drained");
 
-        // SetTradeMoney folds gold/silver/copper into a copper total the app ships as SET_TRADE_GOLD,
-        // gated on the purse covering it (1965).
+        // An offer is sent only when the purse covers it.
         s.set_money(20_000);
         s.run("SetTradeMoney(1 * 10000 + 23 * 100 + 45)").unwrap();
         assert_eq!(s.take_trade_money(), Some(12_345));
         assert_eq!(s.take_trade_money(), None, "drained");
-        // The low dword of -5 is an unsigned 0xFFFFFFFB, past any purse: refused silently (1965).
+        // The low dword of -5 is 0xFFFFFFFB, past any purse: refused silently.
         s.run("SetTradeMoney(-5)").unwrap();
         assert_eq!(s.take_trade_money(), None);
         s.run("SetTradeMoney(30000)").unwrap();
@@ -682,8 +601,7 @@ mod tests {
         assert!(s.take_trade_set_items().is_empty());
         assert!(s.take_trade_clear_items().is_empty());
 
-        // A held backpack item (bag 0, slot 3) dropped on our slot 2 → a (2, 0, 3) placement, and the
-        // cursor is cleared (0218 plain-clear — no local held copy).
+        // A held backpack item dropped on our slot 2 queues (2, 0, 3) and clears the cursor.
         s.model_mut().cursor = Some(item(0, 3));
         s.run("ClickTradeButton(2)").unwrap();
         assert_eq!(s.take_trade_set_items(), vec![(2, 0, 3)]);
@@ -692,7 +610,7 @@ mod tests {
             "the drop clears the cursor"
         );
 
-        // Empty cursor on a FILLED player slot → clear it; on an empty slot → nothing.
+        // An empty cursor clears a filled slot and does nothing on an empty one.
         let mut st = TradeState::default();
         st.player.slots[0] = Some(TradeSlotItem {
             item_id: 2589,
@@ -708,7 +626,7 @@ mod tests {
             "an empty slot clears nothing"
         );
 
-        // The partner column is read-only — ClickTargetTradeButton never queues and never eats the cursor.
+        // The partner's column queues nothing and leaves the cursor alone.
         s.model_mut().cursor = Some(item(0, 3));
         s.run("ClickTargetTradeButton(1)").unwrap();
         assert!(s.take_trade_set_items().is_empty());
@@ -717,7 +635,7 @@ mod tests {
             "a partner-side click leaves the cursor untouched"
         );
 
-        // A spell payload is refused — put back untouched, nothing queued.
+        // A spell payload is refused and stays on the cursor.
         s.model_mut().cursor = Some(CursorPayload::Spell(crate::script::cursor::CursorSpell {
             passive: false,
             book_slot: 1,
diff --git a/crates/benilla-ui/src/script/tradeskill/api.rs b/crates/benilla-ui/src/script/tradeskill/api.rs
index 8e331c9f..03eb2134 100644
--- a/crates/benilla-ui/src/script/tradeskill/api.rs
+++ b/crates/benilla-ui/src/script/tradeskill/api.rs
@@ -1,5 +1,4 @@
-//! The Lua globals (`GetTradeSkillInfo`, `DoTradeSkill`, the filter family, …) — [`install`] wires
-//! the Era `TradeSkillFrame.lua` API surface onto [`super::view`]'s display-tree/filter machinery.
+//! The tradeskill Lua globals over [`super::view`]'s visible rows and filters.
 
 use mlua::{Lua, MultiValue, Value};
 
@@ -20,7 +19,7 @@ fn opt_str(lua: &Lua, s: Option<&String>) -> mlua::Result<Value> {
     })
 }
 
-/// A `bool` as the Era `1`/`nil` shape.
+/// A `bool` as the 1.12 API's `1` or `nil`.
 fn era_bool(b: bool) -> Value {
     if b {
         Value::Integer(1)
@@ -33,8 +32,7 @@ fn era_bool(b: bool) -> Value {
 pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetTradeSkillLine() → lineName, rank, maxRank; ("UNKNOWN", 0, 0) with no window open (the
-    // ref's own no-tradeskill shape).
+    // GetTradeSkillLine(): ("UNKNOWN", 0, 0) with no window open, as the reference answers.
     g.set(
         "GetTradeSkillLine",
         lua.create_function(|lua, ()| {
@@ -51,8 +49,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // → the number of VISIBLE rows the open window offers — headers + the recipes of uncollapsed
-    // groups (0 when closed).
+    // GetNumTradeSkills(): the visible rows, headers included.
     g.set(
         "GetNumTradeSkills",
         lua.create_function(|lua, ()| {
@@ -61,12 +58,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The two link verbs (decision 1973).
-    //
-    // GetTradeSkillItemLink(index) — `0x4ff410`: the number gate raises its Usage; then ZERO
-    // values on every miss — an index off the list, a header row, a recipe with no product, an
-    // uncached product template (no query is ever sent; the app pre-asks when the list lands) —
-    // and otherwise ONE string, the product's `|Hitem:` link in its quality colour.
+    // GetTradeSkillItemLink(index) (`0x4ff410`): zero values on any miss (a header, no product, an
+    // uncached template, which is never queried here), else the product's item link.
     g.set(
         "GetTradeSkillItemLink",
         lua.create_function(|lua, index: Value| {
@@ -94,10 +87,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradeSkillReagentItemLink(index, reagentIndex) — `0x4ff800`: both arguments through the
-    // number gate, raising `Usage: GetTradeReagentSkillItemLink(…)` — Blizzard's own typo, kept.
-    // `reagentIndex` is 1-based over the NON-EMPTY reagent slots and never range-checked in the
-    // client; ALWAYS exactly one value: the reagent's link, or nil on any miss.
+    // GetTradeSkillReagentItemLink(index, reagentIndex) (`0x4ff800`): always one value, the link
+    // or nil; `reagentIndex` counts the non-empty reagent slots, and the usage error's
+    // `GetTradeReagentSkillItemLink` is the reference's own typo.
     g.set(
         "GetTradeSkillReagentItemLink",
         lua.create_function(|lua, (index, reagent): (Value, Value)| {
@@ -128,10 +120,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradeSkillInfo(index) → name, type, numAvailable, isExpanded. `index` 1-based into the
-    // VISIBLE row list (the module doc's grouped-list law, `0x4fca20`). A header row:
-    // (groupName, "header", 0, isExpanded 1/nil). A recipe row: (name, difficulty color key,
-    // numAvailable, nil). Out of range → a single nil.
+    // GetTradeSkillInfo(index): (name, "header", 0, isExpanded) for a header, (name, difficulty,
+    // numAvailable, nil) for a recipe, one nil out of range.
     g.set(
         "GetTradeSkillInfo",
         lua.create_function(|lua, index: usize| {
@@ -169,7 +159,6 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetFirstTradeSkill() → the first NON-header visible index (0 when none).
     g.set(
         "GetFirstTradeSkill",
         lua.create_function(|lua, ()| {
@@ -178,9 +167,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradeSkillSubClasses() → the current group names, in group order (`0x4ffb60`: the
-    // filter-dropdown vocabulary IS the header list) — though v1 ships no
-    // filter dropdown to consume it yet (the SubClass/InvSlot filter family below stays inert).
+    // GetTradeSkillSubClasses(): the group names in order, unfiltered (`0x4ffb60`).
     g.set(
         "GetTradeSkillSubClasses",
         lua.create_function(|lua, ()| {
@@ -195,8 +182,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ExpandTradeSkillSubClass(i) / CollapseTradeSkillSubClass(i) — fold a group by its header's
-    // VISIBLE index (i == 0 = ALL groups, the CollapseAll semantics — see [`set_collapsed`]).
+    // Expand/CollapseTradeSkillSubClass(i): the group whose header is visible row i; 0 is all.
     g.set(
         "ExpandTradeSkillSubClass",
         lua.create_function(|lua, id: usize| {
@@ -216,7 +202,6 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradeSkillIcon(index) → icon texture path (nil while in flight / OOB / a header row).
     g.set(
         "GetTradeSkillIcon",
         lua.create_function(|lua, index: usize| {
@@ -225,7 +210,6 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradeSkillNumMade(index) → minMade, maxMade (0, 0 when OOB / no window / a header row).
     g.set(
         "GetTradeSkillNumMade",
         lua.create_function(|lua, index: usize| {
@@ -239,8 +223,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradeSkillCooldown(index) → remaining cooldown seconds, or nil when ready / OOB / a header
-    // row (the ref Lua tests this return for truthiness).
+    // GetTradeSkillCooldown(index): nil when ready, which the stock Lua tests for truthiness
+    // (Blizzard_TradeSkillUI.lua:215).
     g.set(
         "GetTradeSkillCooldown",
         lua.create_function(|lua, index: usize| {
@@ -254,8 +238,6 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradeSkillNumReagents(index) → this recipe's reagent count (0 when OOB / no window / a
-    // header row).
     g.set(
         "GetTradeSkillNumReagents",
         lua.create_function(|lua, index: usize| {
@@ -264,10 +246,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradeSkillReagentInfo(index, reagentIndex) → name, icon, need, have (a single nil when the
-    // recipe/reagent index is OOB or `index` is a header row). name/icon are themselves nil while
-    // the ask-once template answer is in flight — the ref grays/counts the row off exactly these
-    // four.
+    // GetTradeSkillReagentInfo(index, reagentIndex): one nil on a miss; name and icon are nil
+    // until the item template arrives.
     g.set(
         "GetTradeSkillReagentInfo",
         lua.create_function(|lua, (index, reagent_index): (usize, usize)| {
@@ -286,9 +266,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradeSkillTools(index) → an alternating (name, has) multivalue, one pair per Requirements
-    // tool (e.g. "Anvil", 1, "Mining Pick", nil) — the ref feeds this straight into
-    // BuildColoredListString. Empty when the recipe has no tools / index is OOB / a header row.
+    // GetTradeSkillTools(index): alternating (name, has) pairs, which the stock Lua feeds to
+    // `BuildColoredListString` (Blizzard_TradeSkillUI.lua:274).
     g.set(
         "GetTradeSkillTools",
         lua.create_function(|lua, index: usize| {
@@ -304,8 +283,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradeskillRepeatCount() → the remaining Create All repeats (note the lowercase "s" in
-    // "Tradeskill" — that IS the real 1.12 API name). 0 with no window open.
+    // GetTradeskillRepeatCount(): the lowercase "s" is the 1.12 name.
     g.set(
         "GetTradeskillRepeatCount",
         lua.create_function(|lua, ()| {
@@ -316,9 +294,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SelectTradeSkill(index) / GetTradeSkillSelectionIndex() — the engine-held selection, VISIBLE
-    // index in ([`select`]: a header index is IGNORED, not cleared), VISIBLE index out
-    // ([`selected_visible_index`]), held internally as a stable flat-recipe position (module doc).
+    // SelectTradeSkill and GetTradeSkillSelectionIndex take and answer visible indices.
     g.set(
         "SelectTradeSkill",
         lua.create_function(|lua, index: u32| {
@@ -335,9 +311,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // DoTradeSkill(index, count) — queue the recipe's SPELL ID for `count` crafts (default 1, never
-    // less than 1) — the app's repeat machine turns this into that many CMSG_CAST_SPELL sends. Out
-    // of range / a header index → ignored.
+    // DoTradeSkill(index, count): queues the recipe's spell for `count` crafts, which the app sends
+    // as one `CMSG_CAST_SPELL` each.
     g.set(
         "DoTradeSkill",
         lua.create_function(|lua, (index, count): (usize, Option<i64>)| {
@@ -345,8 +320,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             if let Some((spell_id, avail)) =
                 recipe_at(&model, index).map(|r| (r.spell_id, r.num_available))
             {
-                // The client clamps the repeat to numAvailable at the latch
-                // (`DoTradeSkill 0x500280`).
+                // The client clamps the repeat to numAvailable, at least 1 (`0x500280`).
                 let n = (count.unwrap_or(1).max(1) as u32).min(avail.max(1));
                 model.trade_skill_dos.push((spell_id, n));
             }
@@ -354,8 +328,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CloseTradeSkill() — client-side close (no packet, vanilla): flag it so the app clears its
-    // local state.
+    // CloseTradeSkill(): client-side only, no packet; the app clears its state.
     g.set(
         "CloseTradeSkill",
         lua.create_function(|lua, ()| {
@@ -365,16 +338,12 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The sub-class/inv-slot FILTER family — real now (the dropdowns ship, ref
-    // Blizzard_TradeSkillUI.lua l.314-414). Indexing follows the C originals: the SubClass index
-    // is 1-based into the CURRENT GetTradeSkillSubClasses order (`0x4ffc70` bounds-checks against
-    // the live header count), the InvSlot index 1-based into the GetTradeSkillInvSlots order;
-    // index 0 is the "All" pseudo-entry on both. `Set*(0, 1, …)` = everything back on (the ref's
-    // "All Subclasses"/"All Slots" menu row); `Set*(i, 1, 1)` = EXCLUSIVE — only entry i shown
-    // (every ref menu click passes exactly this shape); `Set*(i, 1)` un-hides i; `Set*(i, 0)`
-    // hides it. Each set re-lists + fires TRADE_SKILL_UPDATE via the touched flag (the `0x4fd710`
-    // re-sort + event 0x139 shape). `Get*(0)` answers "is everything shown" — the ref's
-    // all-checked probe.
+    // The subclass and inv-slot filters (Blizzard_TradeSkillUI.lua:314-414): index i is 1-based
+    // into `GetTradeSkillSubClasses` (`0x4ffc70` bounds-checks it) or `GetTradeSkillInvSlots`, and
+    // 0 is all. `Set*(i, 1, 1)` shows only i, as every menu click does; `Set*(i, 1)` shows i and
+    // `Set*(i, 0)` hides it. Each set fires TRADE_SKILL_UPDATE through the touched flag
+    // (`0x4fd710`), and `Get*(0)` asks whether everything is shown. The reference's per-header
+    // subclass flag (`+0xc`, mask `0x84dd60`) is kept here as hidden group keys.
     g.set(
         "GetTradeSkillSubClassFilter",
         lua.create_function(|lua, index: usize| {
@@ -432,17 +401,14 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             },
         )?,
     )?;
-    // GetTradeSkillInvSlots() → the distinct slot words of the open window's products, ascending
-    // slot-bit order (the `0xbde058` bit walk — [`present_inv_slots`]).
+    // GetTradeSkillInvSlots(): the products' slot names in ascending bit order (`0xbde058`).
     g.set(
         "GetTradeSkillInvSlots",
         lua.create_function(|lua, ()| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             let mut out = Vec::new();
-            // Each word is its `0x84dd70` token resolved off the player's own string table
-            // (decision 2045). A token the table does not carry answers the empty string rather
-            // than being dropped: the list is POSITIONAL — `GetTradeSkillInvSlotFilter(index)`
-            // indexes the same order — so a hole would shift every filter after it.
+            // A token (`0x84dd70`) missing from the string table answers "" rather than being
+            // dropped: the filter verbs index this list by position.
             for bit in present_inv_slots(&model) {
                 let word = inv_slot_token(bit)
                     .and_then(|k| crate::strings::global(lua, k))
@@ -452,9 +418,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(MultiValue::from_vec(out))
         })?,
     )?;
-    // The InvSlot pair reads/writes the shown-mask (`0x84dd64`) with the index resolving to the
-    // (index-1)-th SET bit of the accumulated present-slots mask — present slots only, ascending
-    // (`0x4ffe60`'s enumeration; `GetTradeSkillInvSlots` returns exactly that order).
+    // The inv-slot pair works on the shown mask (`0x84dd64`); index i is the i-th present slot bit
+    // (`0x4ffe60`).
     g.set(
         "GetTradeSkillInvSlotFilter",
         lua.create_function(|lua, index: usize| {
@@ -464,7 +429,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             }
             let bits = present_inv_slots(&model);
             Ok(match index.checked_sub(1) {
-                // The "all shown?" probe: (present & mask) == present (`0x4fffd0`).
+                // Everything shown: (present & mask) == present (`0x4fffd0`).
                 None => era_bool(
                     bits.iter()
                         .all(|&b| model.trade_skill_invslot_mask & (1 << b) != 0),
@@ -487,8 +452,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                 let bits = present_inv_slots(&model);
                 let on = on.unwrap_or(1) != 0;
                 let exclusive = exclusive.unwrap_or(0) != 0;
-                // The exact mask math per path (the recovered `0x4fd730` args): all →
-                // 0xffffffff · off → old & ~(1<<b) · exclusive → 1<<b · add → old | (1<<b).
+                // The mask each path writes, as `0x4fd730` is called.
                 match index.checked_sub(1) {
                     None => model.trade_skill_invslot_mask = u32::MAX,
                     Some(n) => {
diff --git a/crates/benilla-ui/src/script/tradeskill/mod.rs b/crates/benilla-ui/src/script/tradeskill/mod.rs
index 95fb68b1..81f04d9a 100644
--- a/crates/benilla-ui/src/script/tradeskill/mod.rs
+++ b/crates/benilla-ui/src/script/tradeskill/mod.rs
@@ -1,90 +1,8 @@
-//! The tradeskill bindings (decision 0437 phase 2) — the Era-shaped crafting-window surface driving a
-//! faithful port of the real 1.12 `TradeSkillFrame` (extracted from `interface.MPQ`:
-//! `Interface\FrameXML\Blizzard_TradeSkillUI\TradeSkillFrame.{xml,lua}`). Same two-way seam as
-//! [`super::trainer`]: the app pushes a **tradeskill snapshot** ([`UiScript::set_trade_skill`] — the
-//! recipes already resolved to name/icon/reagents/tools/color by the app from `Spell.dbc`/
-//! `SkillLineAbility.dbc`/bag counts), and the Lua `DoTradeSkill`/`CloseTradeSkill` calls queue
-//! outbound **intents** the app drains ([`UiScript::take_trade_skill_dos`] returns
-//! `(spell id, count)` pairs / [`UiScript::take_trade_skill_close`]). The engine holds no recipe
-//! knowledge — a recipe is name/icon/difficulty/reagents/tools/cooldown, all app-resolved (0437 §"The
-//! decision" item 1).
-//!
-//! ## The Era API shape (matched to the real `TradeSkillFrame.lua`)
-//!
-//! `GetTradeSkillInfo(index) → name, type, numAvailable, isExpanded`: `type` is either the recipe's
-//! difficulty color key (`"optimal"|"medium"|"easy"|"trivial"`, [`TradeSkillDifficulty::as_str`]) or
-//! `"header"` for a group row (see below); `isExpanded` is `nil` for a recipe row, `1`/`nil` for a
-//! header. `GetTradeSkillReagentInfo`/`GetTradeSkillTools`/`GetTradeSkillCooldown`/
-//! `GetTradeSkillNumMade`/`GetTradeskillRepeatCount` (note the lowercase "s" in "Tradeskill" — that
-//! IS the real 1.12 spelling) round out the detail pane; `DoTradeSkill` queues the craft,
-//! `CloseTradeSkill` is the client-side close (vanilla sends no packet here either, matching
-//! [`super::trainer`]'s `CloseTrainer` precedent).
-//!
-//! ## The grouped list (`0x4fca20`)
-//!
-//! Unlike v1's flat render, the engine now owns the WHOLE display tree, built fresh from
-//! [`TradeSkillState::recipes`] on every query ([`build_groups`]) — [`TradeSkillState::recipes`] is
-//! just the app's flat, unordered input; its push order carries no meaning. Every recipe belongs to
-//! a group keyed by the CREATED item's `(ItemClass, ItemSubClass)`, named from `ItemSubClass.dbc`
-//! (resolved app-side — [`TradeSkillRecipe::group`]); a recipe whose product template is still in
-//! flight has no group yet (the client's own one-frame header deferral) and buckets trailing under
-//! a synthesized group keyed `(u32::MAX, u32::MAX)` with an empty name — no real `ItemClass` reaches
-//! `u32::MAX`, so it sorts last with no special-casing. Groups order by `ItemClass` id ascending,
-//! ties broken alphabetically by group name (case-insensitive, never by subclass id); within a
-//! group, recipes order by difficulty tier ascending (Optimal < Medium < Easy < Trivial — the byte
-//! tiers 0..3, [`TradeSkillDifficulty::tier`]), ties broken alphabetically by recipe name. The
-//! client's own middle tiebreak (an item-template field) is SKIPPED — the one INFERRED remainder,
-//! named and pinned like [`TradeSkillDifficulty`]'s own INTERIM color law once was.
-//!
-//! Visible rows are each group's header (always shown) plus — for an uncollapsed group — its
-//! recipes; every index the Era API takes/returns is 1-based into THAT list (mirrors
-//! [`super::skills`]'s tree exactly: groups + collapse + visible-index remapping). `GetTradeSkillInfo`
-//! on a header row returns `(groupName, "header", 0, isExpanded)`; `GetNumTradeSkills()` counts
-//! visible rows; `GetFirstTradeSkill()` is the first NON-header visible index (`0` when none).
-//! `Expand/CollapseTradeSkillSubClass(i)` fold a group by its header's VISIBLE index (`i == 0` =
-//! ALL groups — the CollapseAll button's own call shape); the collapse set is keyed by group key
-//! ([`Model::trade_skill_collapsed`]) and survives a `set_trade_skill` content re-push (pruned to
-//! still-live groups). `GetTradeSkillSubClasses()` returns the current group names in group
-//! order — the VERIFIED filter-dropdown vocabulary IS the header list, and it never shrinks
-//! under a filter — and the `SubClassFilter`/`InvSlot` filter family: the subclass filter is
-//! hidden group keys (the client's per-header
-//! `+0xc` flag, position mask `0x84dd60` derived), the inv-slot filter is a shown-bit mask
-//! (`0x84dd64`) over the accumulated slot vocabulary, [`rows`] drops filtered recipes and any
-//! group left empty (a merely-collapsed group keeps its header), and every engine-side mutator
-//! (a filter set, an expand/collapse) raises the `trade_skill_touched` flag the app answers with
-//! `TRADE_SKILL_UPDATE` — the real client's in-call recompute+resort + event 0x13a (the
-//! `0x4fd710`/`0x4fd730`/`0x4fd750` writer trio). Persistence is the client's `0xbde064`-keyed
-//! story: filters, collapse, and the spell-id selection all survive a same-profession
-//! close→reopen and reset on a profession switch ([`UiScript::set_trade_skill`]). The InvSlot
-//! vocabulary folds each product's `InventoryType` through the dumped `DAT_00809200` table
-//! ([`inv_slot_mask`] — WEAPON contributes both hand bits) and names bits via the `0x84dd70`
-//! token table ([`inv_slot_name`]).
-//!
-//! Every per-recipe getter — `DoTradeSkill`, `GetTradeSkillIcon`/`NumMade`/`Cooldown`/`NumReagents`/
-//! `ReagentInfo`/`Tools` — resolves its `index` through this same visible mapping via [`recipe_at`]
-//! and no-ops/nil-shapes on a header row. **`SelectTradeSkill(i)` on a header index is IGNORED, not
-//! cleared** — the ref's own `SetSelection` toggles the fold instead of selecting (ref l.184-192,
-//! transcribed in the XML); the engine simply leaves the prior selection untouched. The selection
-//! itself is held internally as a position into the OPEN WINDOW's FLAT `recipes` list — stable
-//! across a collapse/expand (which never reorders `recipes`, only what's visible) and remapped by
-//! spell id only across a `set_trade_skill` re-push ([`selected_visible_index`] derives the current
-//! VISIBLE index from that flat position on every read, [`super::skills`]'s own by-identity
-//! persistence pattern adapted to a field this module can't change the type of).
-//!
-//! ## The tooltip channel
-//!
-//! `GameTooltip:SetTradeSkillItem(skillIndex [, reagentIndex])` is registered in
-//! [`super::tooltip_item`], beside `SetMerchantItem`, through the same id-keyed item renderer: with
-//! `reagentIndex` it resolves that recipe's reagent's item, without it the recipe's PRODUCT item. A
-//! product id of `0` (a pure-effect recipe) or an in-flight ask-once template answer both fall back to
-//! the renderer's own name-only line — the recipe's name for the product channel — rather than a
-//! no-op, since that fallback already exists and reads better than a blank hover.
-//!
-//! `skillIndex` is a **VISIBLE** index and is resolved through [`recipe_at`] (`pub(crate)` for
-//! exactly this), never a raw [`TradeSkillState::recipes`] position — headers interleave with rows
-//! since the grouped build (`0x4fca20`) landed, so a raw index would show the wrong item the moment
-//! any group precedes the selected recipe's own. A header index resolves to `None` and the hover is
-//! a no-op.
+//! The tradeskill bindings behind the stock `Blizzard_TradeSkillUI`: the app pushes a snapshot
+//! ([`UiScript::set_trade_skill`]) with recipes resolved from `Spell.dbc`, `SkillLineAbility.dbc`
+//! and bag counts, and drains the intents `DoTradeSkill` and `CloseTradeSkill` queue. The engine
+//! owns the grouped, filtered list (`0x4fca20`); every Lua index, `SetTradeSkillItem`'s included,
+//! is 1-based into its visible rows ([`recipe_at`]).
 
 use std::collections::HashSet;
 
@@ -99,27 +17,23 @@ use view::build_groups;
 pub(super) use api::install;
 pub(crate) use view::recipe_at;
 
-/// The recipe difficulty band (the color law, computed app-side): the Lua color-table key
-/// `GetTradeSkillInfo` returns as its `type`. These four names ARE the real client's own
-/// `TradeSkillTypeColor` keys (`TradeSkillFrame.lua`); WHICH recipes land in which band (the
-/// trivial-rank cut points) is CONFIRMED at the bytes (decision 0446, `0x4fca20`:
-/// gray ≥ trivialHigh, green ≥ the low/high midpoint, yellow ≥ trivialLow, orange below) — this
-/// enum is the verified Era vocabulary the app's law picks from.
+/// A recipe's difficulty band, computed app-side: gray at or above trivialHigh, green from the
+/// low/high midpoint, yellow from trivialLow, orange below (`0x4fca20`).
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum TradeSkillDifficulty {
-    /// Orange — a near-certain skill-up (the hardest recipes relative to current rank).
+    /// Orange: a near-certain skill-up.
     Optimal,
-    /// Yellow — a good skill-up chance.
+    /// Yellow: a good skill-up chance.
     Medium,
-    /// Green — a fading skill-up chance.
+    /// Green: a fading skill-up chance.
     Easy,
-    /// Gray — no more skill-up; still craftable for its own sake.
+    /// Gray: no skill-up.
     Trivial,
 }
 
 impl TradeSkillDifficulty {
-    /// The Era `type` string `GetTradeSkillInfo` returns for a RECIPE row (a header row returns
-    /// `"header"` instead — the module doc's grouped list).
+    /// A recipe row's `type` in `GetTradeSkillInfo`, a `TradeSkillTypeColor` key
+    /// (`Blizzard_TradeSkillUI.lua:7-10`).
     pub fn as_str(self) -> &'static str {
         match self {
             TradeSkillDifficulty::Optimal => "optimal",
@@ -129,12 +43,8 @@ impl TradeSkillDifficulty {
         }
     }
 
-    /// The byte tier a group sorts recipes by, ascending (`0x4fd380`):
-    /// Optimal < Medium < Easy < Trivial, 0..3. The **Craft** window's row comparators key on the
-    /// same tier byte first (`row[+0xc]`, decision 1124), which is why this is `pub(crate)` and not
-    /// private to this module: the client's two code tables are one vocabulary shifted by one
-    /// (Craft's `0` is a `"none"` tier benilla cannot produce), so the *relative* order is identical
-    /// and the shift is invisible to a comparator.
+    /// The tier byte recipes sort by, ascending (`0x4fd380`). The Craft window's comparators key on
+    /// the same order (`row[+0xc]`, shifted by one for a "none" tier), so it shares this.
     pub(crate) fn tier(self) -> u8 {
         match self {
             TradeSkillDifficulty::Optimal => 0,
@@ -145,114 +55,74 @@ impl TradeSkillDifficulty {
     }
 }
 
-/// One reagent a recipe consumes (`GetTradeSkillReagentInfo`): the bag-counted need/have plus the
-/// resolved name/icon — both `None` until the app's ask-once item-template answer lands (the same
-/// miss path as [`super::ItemTemplateView`]'s own asks), at which point the ref Lua sees the slot as
-/// blank (a `nil` name/texture hides the row's icon+text, not an error state).
+/// One reagent of a recipe, as `GetTradeSkillReagentInfo` reports it.
 #[derive(Clone, Debug, PartialEq)]
 pub struct TradeSkillReagent {
-    /// The reagent's item entry — the tooltip channel key (`GameTooltip:SetTradeSkillItem(i, j)`
-    /// resolves through this, never through `name`/`icon`).
+    /// The item entry `SetTradeSkillItem(i, j)` resolves through.
     pub item: u32,
-    /// The resolved display name, or `None` while the ask-once template answer is still in flight.
+    /// `None` until the item template arrives.
     pub name: Option<String>,
-    /// The resolved icon texture path, or `None` while still in flight.
+    /// `None` until the item template arrives.
     pub icon: Option<String>,
     /// How many this recipe consumes.
     pub need: u32,
-    /// How many the player's bags currently hold (`count_of`, decision 0269) — the row's own
-    /// have-vs-need gate, which the ref Lua grays/counts off directly.
+    /// How many the player's bags hold.
     pub have: u32,
 }
 
-/// One recipe row (`GetTradeSkillInfo` + its detail-pane getters): a known spell carrying attr
-/// `SPELL_ATTR_IS_TRADESKILL` (0437 §"What scoping verified"), resolved by the app from
-/// `Spell.dbc`/`SkillLineAbility.dbc`/bag counts into everything the window shows.
+/// One recipe: a known spell with `SPELL_ATTR_IS_TRADESKILL`, resolved app-side from `Spell.dbc`,
+/// `SkillLineAbility.dbc` and bag counts.
 #[derive(Clone, Debug, PartialEq)]
 pub struct TradeSkillRecipe {
-    /// The header key (`0x55ba30`): the created item's `(ItemClass,
-    /// ItemSubClass)` + the resolved `ItemSubClass.dbc` display name; `None` while the product's
-    /// template is still in flight (the client's own one-frame header deferral) — [`build_groups`]
-    /// buckets those trailing under a synthesized empty-named group.
+    /// The product's `(ItemClass, ItemSubClass)` and `ItemSubClass.dbc` name, the header key
+    /// (`0x55ba30`); `None` until the product's template arrives.
     pub group: Option<(u32, u32, String)>,
-    /// The recipe spell id — what `DoTradeSkill` queues as the `CMSG_CAST_SPELL` target (one send
-    /// per item crafted, decision 0437 — there is no wire count field).
+    /// What `DoTradeSkill` casts, one `CMSG_CAST_SPELL` per item: the packet has no count.
     pub spell_id: u32,
     pub name: String,
-    /// The color band `GetTradeSkillInfo`'s `type` reports ([`TradeSkillDifficulty`]).
     pub difficulty: TradeSkillDifficulty,
-    /// `min` over reagents of `floor(have/need)` — `0` when any reagent is short (uncraftable); the
-    /// count `GetTradeSkillInfo` reports as `numAvailable`.
+    /// The least `have / need` over the reagents, reported as `numAvailable`.
     pub num_available: u32,
-    /// The product item's icon if it resolved, else the spell's own icon (an app-resolved fallback);
-    /// `None` only while both are still in flight.
+    /// The product's icon, else the spell's; `None` while neither has arrived.
     pub icon: Option<String>,
     pub min_made: u32,
     pub max_made: u32,
-    /// Remaining tradeskill cooldown in seconds (the Mooncloth-style per-recipe cooldown); `None` =
-    /// ready now (`GetTradeSkillCooldown` returns `nil`, which the ref Lua tests for truthiness).
+    /// Remaining cooldown in seconds; `None` when ready.
     pub cooldown_secs: Option<u64>,
-    /// The item entry this recipe creates — the tooltip channel key for the no-`reagentIndex` call to
-    /// `SetTradeSkillItem`; `0` = no product item (a pure-effect recipe has nothing to show there).
+    /// The created item, 0 for a pure-effect recipe.
     pub product_item: u32,
-    /// The product's `InventoryType` (item template) — the InvSlot filter's raw input, folded to
-    /// its slot-bit contribution by [`inv_slot_mask`] (the real client's
-    /// `DAT_00809200[InventoryType]` OR-accumulate (`0x4fcee6`) + overrides).
-    /// `0` (non-equip, or the template still in flight) folds to the `0x800000` catch-all bit.
+    /// The product's `InventoryType`, which the inv-slot filter folds to slot bits through
+    /// `DAT_00809200` (`0x4fcee6`); 0 takes the catch-all bit.
     pub product_inv_type: u32,
-    /// The product's `ItemLevel` (item template `+0x38`) — the sort's SECONDARY key, ascending,
-    /// between the difficulty tier and the name (the `record+0x14` field identity: the dbcache
-    /// `ItemStats_C::Read 0x7c9640` write order). `0` while the template is in flight — moot,
-    /// since a template-less recipe has
-    /// no group yet and buckets trailing anyway.
+    /// The product's `ItemLevel`, the sort key between tier and name (`record+0x14`, `0x7c9640`).
     pub product_item_level: u32,
-    /// Consumed reagents, in display order (`GetTradeSkillNumReagents`/`GetTradeSkillReagentInfo`).
+    /// In display order.
     pub reagents: Vec<TradeSkillReagent>,
-    /// The Requirements line's tool list — `(tool name, have)` pairs (e.g. `("Anvil", true)`); exposed
-    /// to Lua as `GetTradeSkillTools`'s alternating multivalue, which the ref feeds into
-    /// `BuildColoredListString`.
+    /// The Requirements line's `(tool name, have)` pairs.
     pub tools: Vec<(String, bool)>,
 }
 
-/// One open tradeskill window: the skill line's name/rank and its recipe list. Pushed whole by the
-/// app ([`UiScript::set_trade_skill`]); `None` means the window is closed.
+/// One open tradeskill window, pushed whole by the app.
 #[derive(Clone, Debug, PartialEq)]
 pub struct TradeSkillState {
-    /// The skill line id (`SkillLine.dbc`) — the persistence cache key (`0xbde064`): a push
-    /// for a different line than the last resets the filters, the
-    /// collapse set, and the selection; the same line keeps them, across close/reopen too.
+    /// The `SkillLine.dbc` id, the persistence key (`0xbde064`).
     pub line: u32,
-    /// The skill line's display name (`SkillLine.dbc`) — e.g. `"Tailoring"`.
     pub line_name: String,
     pub rank: u32,
     pub max_rank: u32,
-    /// The window's recipe rows — the app's FLAT, UNORDERED input; the engine owns ALL ordering
-    /// (group + tier + name, the module doc's grouped-list law, `0x4fca20`) and
-    /// builds the display tree fresh from this on every query ([`build_groups`]), so push order
-    /// carries no meaning. The Era API's `index` is 1-based into the synthesized VISIBLE list, never
-    /// straight into this slice — see [`recipe_at`].
+    /// Unordered: the engine sorts them (`0x4fca20`), and Lua indexes the visible rows, not this.
     pub recipes: Vec<TradeSkillRecipe>,
-    /// Remaining Create All repeats (`GetTradeskillRepeatCount`) — the client-side repeat machine's
-    /// own counter (`0x500230`, decision 0446), not engine-driven: the app decrements
-    /// and re-pushes as each repeat's cast resolves.
+    /// Remaining Create All repeats (`0x500230`), decremented by the app as each cast resolves.
     pub repeat_count: u32,
 }
 
 impl super::UiScript {
-    /// Push (or clear, with `None`) the open tradeskill window's recipe snapshot. Snapshots re-push
-    /// every time a resolved field changes (reagent counts, ask-once answers landing, …) — no
-    /// diffing happens here.
+    /// Pushes the open window's snapshot, or `None` on close; the app re-pushes on any change.
     ///
-    /// Persistence is the real client's (`0x4fc910`, keyed by the
-    /// `0xbde064` last-built-line cache): a push for a **different skill line** resets the two
-    /// filters, the collapse set, and the selection; the **same line** keeps all of them — and
-    /// because a close (`None`) touches none of that state either, they survive a close→reopen
-    /// round trip exactly like the client's statics do. The selection rides its **spell id**
-    /// (`0xbde044`'s own storage) — on every push it remaps to the id's new flat position, or
-    /// clears if the recipe vanished. The collapse/subclass-hidden key sets are pruned to the
-    /// groups the fresh recipes still produce (the client's save→restore-by-key round trip loses
-    /// exactly the keys that stopped existing); the inv-slot mask is deliberately NOT pruned —
-    /// the build never touches `0x84dd64`.
+    /// Persistence follows the reference (`0x4fc910`, keyed by `0xbde064`): a different skill line
+    /// resets filters, folds and selection, and the same line keeps them across a close. The
+    /// selection rides its spell id (`0xbde044`); fold and subclass keys are pruned to live groups,
+    /// while the inv-slot mask (`0x84dd64`) is never pruned.
     pub fn set_trade_skill(&mut self, state: Option<TradeSkillState>) {
         let mut model = self.model_mut();
         match state {
@@ -289,28 +159,21 @@ impl super::UiScript {
         }
     }
 
-    /// Drain the **(spell id, count)** intents `DoTradeSkill` queued since the last call — the engine
-    /// resolves each clicked recipe's INDEX to its spell id, so the app sends `CMSG_CAST_SPELL`
-    /// without needing the index mapping; `count` is the total the app's own client-side repeat
-    /// loop (decision 0437 §5, `0x4fd7b0`) turns into that many sequential sends, one per item —
-    /// "Create" queues `1`, "Create All" queues [`TradeSkillState::repeat_count`].
+    /// Drains the `(spell id, count)` crafts `DoTradeSkill` queued; the app's repeat loop
+    /// (`0x4fd7b0`) sends one cast per item.
     pub fn take_trade_skill_dos(&mut self) -> Vec<(u32, u32)> {
         std::mem::take(&mut self.model_mut().trade_skill_dos)
     }
 
-    /// Whether `CloseTradeSkill` was called since the last drain (and clear the flag). Like
-    /// [`super::trainer`]'s `CloseTrainer`, the client-side close sends no packet — the app just
-    /// clears its local tradeskill state.
+    /// Whether `CloseTradeSkill` ran since the last drain; the close sends no packet.
     pub fn take_trade_skill_close(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().trade_skill_close)
     }
 
-    /// Whether an engine-side list mutator ran since the last drain (a filter set, an
-    /// expand/collapse) — the real client answers those from inside the C call with a
-    /// recompute+resort + `TRADE_SKILL_UPDATE` (the `0x4fd710`/`0x4fd730`/`0x4fd750` writer trio
-    /// → event 0x13a); the app drains this and fires the event the
-    /// same frame (the ref's `CollapseAllButton_OnClick` and the filter-menu clicks repaint ONLY
-    /// off that event — no direct `TradeSkillFrame_Update()` call).
+    /// Whether a filter or fold changed since the last drain. The reference re-sorts and fires
+    /// `TRADE_SKILL_UPDATE` (event `0x13a`) inside the call (`0x4fd710`, `0x4fd730`, `0x4fd750`);
+    /// the app fires it the same frame, and the stock filter and collapse-all clicks repaint only
+    /// off that event.
     pub fn take_trade_skill_touched(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().trade_skill_touched)
     }
diff --git a/crates/benilla-ui/src/script/tradeskill/tests.rs b/crates/benilla-ui/src/script/tradeskill/tests.rs
index fe58828a..0a9ab929 100644
--- a/crates/benilla-ui/src/script/tradeskill/tests.rs
+++ b/crates/benilla-ui/src/script/tradeskill/tests.rs
@@ -1,7 +1,7 @@
 use super::*;
 use crate::script::UiScript;
 
-/// One recipe fixture — a single-reagent, single-tool row, distinct spell/product ids per name.
+/// A single-reagent, single-tool recipe fixture.
 fn recipe(
     spell_id: u32,
     name: &str,
@@ -20,9 +20,8 @@ fn recipe(
         max_made: 1,
         cooldown_secs: None,
         product_item: spell_id + 10_000,
-        product_inv_type: 20, // Robe — folds to the Chest slot bit (4)
-        // Neutral by default (0 everywhere = the tie falls through to the name, the pre-verdict
-        // order every other test pins); the ItemLevel tie-break test overrides it explicitly.
+        product_inv_type: 20, // Robe: folds to the Chest slot bit (4)
+        // 0 everywhere, so ties fall through to the name; the ItemLevel test sets it.
         product_item_level: 0,
         reagents: vec![TradeSkillReagent {
             item: 2589,
@@ -35,9 +34,7 @@ fn recipe(
     }
 }
 
-/// A two-recipe, SINGLE-group Tailoring window (the original v1 fixture, now grouped under one
-/// "Cloth" header): row 1 is the header, rows 2-3 are the recipes, tier-sorted — Simple Robe
-/// (Optimal, tier 0) before Bolt of Linen Cloth (Trivial, tier 3).
+/// One "Cloth" group: row 1 the header, then Simple Robe (tier 0) and Bolt of Linen Cloth (tier 3).
 fn two_recipe_state() -> TradeSkillState {
     TradeSkillState {
         line: 197,
@@ -64,11 +61,8 @@ fn two_recipe_state() -> TradeSkillState {
     }
 }
 
-/// Four groups (`0x4fca20`): class 1 "Bolts" (two Optimal-tier recipes — a NAME
-/// tie within a tier), class 2 "Armor Kit"/"Zephyr Cloak" (a CLASS tie broken by group NAME, not
-/// subclass id — "Zephyr Cloak"'s subclass id 1 is LOWER than "Armor Kit"'s 5, yet "Armor Kit"
-/// sorts first), and one recipe whose product template hasn't resolved yet (`group: None`),
-/// bucketed trailing under an empty header.
+/// Four groups: "Bolts" (class 1, a name tie within a tier); "Armor Kit" and "Zephyr Cloak"
+/// (class 2, ordered by name against their subclass ids 5 and 1); a recipe with no group yet.
 fn state() -> TradeSkillState {
     TradeSkillState {
         line: 197,
@@ -137,7 +131,7 @@ fn grouped_visible_rows_ordered_by_class_then_name_tie_then_tier_then_name() {
         ("Bolts", "header"),
         ("Alpha Bolt", "optimal"), // tier tie -> name
         ("Beta Bolt", "optimal"),
-        ("Armor Kit", "header"), // class tie -> NAME, not subclass id (5 > 1)
+        ("Armor Kit", "header"), // class tie -> name, not subclass id (5 > 1)
         ("Alpha Plate", "optimal"), // tier 0 before...
         ("Zinc Chain", "trivial"), // ...tier 3
         ("Zephyr Cloak", "header"),
@@ -160,8 +154,7 @@ fn collapse_hides_a_groups_entries_and_remaps_indices_incl_collapse_all() {
     let mut s = UiScript::new().unwrap();
     s.set_trade_skill(Some(state()));
 
-    // Collapse "Armor Kit" (header at visible index 4): its two recipes vanish, 10 -> 8, and it
-    // now reports isExpanded=nil.
+    // "Armor Kit" is header 4: its two recipes go, 10 -> 8, and it reports isExpanded nil.
     s.run("CollapseTradeSkillSubClass(4)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 8);
     let (name, _, _, expanded) = s
@@ -170,20 +163,18 @@ fn collapse_hides_a_groups_entries_and_remaps_indices_incl_collapse_all() {
         )
         .unwrap();
     assert_eq!((name.as_str(), expanded), ("Armor Kit", None));
-    // "Zephyr Cloak" is now row 5 (was row 7) — the two hidden entries shift everything after.
+    // "Zephyr Cloak" moves up from row 7 to row 5.
     assert_eq!(
         row_kind(&mut s, 5),
         ("Zephyr Cloak".into(), "header".into())
     );
 
-    // Expand it back.
     s.run("ExpandTradeSkillSubClass(4)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 10);
 
-    // Collapse-all (id 0): only the 4 headers remain.
+    // Id 0 folds every group: the 4 headers remain.
     s.run("CollapseTradeSkillSubClass(0)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 4);
-    // Expand-all (id 0).
     s.run("ExpandTradeSkillSubClass(0)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 10);
 }
@@ -193,8 +184,7 @@ fn pending_recipes_bucket_trailing_under_an_empty_header() {
     let mut s = UiScript::new().unwrap();
     s.set_trade_skill(Some(state()));
 
-    // The pending header (row 9): empty name, "header", numAvailable 0, expanded by default —
-    // a real group like any other (nothing has collapsed it).
+    // Row 9 is the pending group's header.
     let (name, kind, avail, expanded) = s
         .eval::<(String, String, i64, Option<i64>)>(
             "local n,t,a,e = GetTradeSkillInfo(9) return n,t,a,e",
@@ -204,10 +194,8 @@ fn pending_recipes_bucket_trailing_under_an_empty_header() {
         (name.as_str(), kind.as_str(), avail, expanded),
         ("", "header", 0, Some(1))
     );
-    // Its one recipe (row 10) reads normally.
     assert_eq!(row_kind(&mut s, 10), ("Mystery Item".into(), "easy".into()));
 
-    // It folds/unfolds exactly like a named group.
     s.run("CollapseTradeSkillSubClass(9)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 9);
 }
@@ -217,7 +205,6 @@ fn header_and_entry_tuple_shapes() {
     let mut s = UiScript::new().unwrap();
     s.set_trade_skill(Some(state()));
 
-    // Header row 1 ("Bolts"): (name, "header", 0, expanded=1).
     let (name, kind, avail, expanded) = s
         .eval::<(String, String, i64, Option<i64>)>(
             "local n,t,a,e = GetTradeSkillInfo(1) return n,t,a,e",
@@ -228,7 +215,6 @@ fn header_and_entry_tuple_shapes() {
         ("Bolts", "header", 0, Some(1))
     );
 
-    // Recipe row 2 ("Alpha Bolt", optimal, numAvailable 5): (name, "optimal", 5, nil).
     let (name, kind, avail, expanded) = s
         .eval::<(String, String, i64, Option<i64>)>(
             "local n,t,a,e = GetTradeSkillInfo(2) return n,t,a,e",
@@ -245,8 +231,7 @@ fn do_trade_skill_and_getters_no_op_on_a_header_index() {
     let mut s = UiScript::new().unwrap();
     s.set_trade_skill(Some(state()));
 
-    // Header row 1 ("Bolts"): every per-recipe getter reads nil/zero/empty rather than
-    // misreading through to whatever recipe happens to sit at that raw position.
+    // Row 1 is a header: every per-recipe getter reads nil, zero or empty.
     assert!(s
         .eval::<bool>("return GetTradeSkillIcon(1) == nil")
         .unwrap());
@@ -273,7 +258,7 @@ fn do_trade_skill_and_getters_no_op_on_a_header_index() {
         "a header index queues no craft"
     );
 
-    // SelectTradeSkill on a header index is IGNORED — the prior selection is untouched.
+    // A header index leaves the selection as it was.
     s.run("SelectTradeSkill(2)").unwrap(); // "Alpha Bolt", row 2
     assert_eq!(
         s.eval::<i64>("return GetTradeSkillSelectionIndex()")
@@ -324,8 +309,7 @@ fn selection_persists_across_collapse_and_a_regroup() {
         8
     );
 
-    // Collapsing an EARLIER group ("Bolts", header 1) shifts every later row up two — the
-    // selection follows Wind Cloak to its new visible position, not the stale numeric index.
+    // Folding "Bolts" above it moves Wind Cloak up two rows, and the selection follows.
     s.run("CollapseTradeSkillSubClass(1)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 8);
     assert_eq!(
@@ -335,15 +319,14 @@ fn selection_persists_across_collapse_and_a_regroup() {
     );
     s.run("ExpandTradeSkillSubClass(1)").unwrap();
 
-    // Collapsing Wind Cloak's OWN group ("Zephyr Cloak", back at row 7) hides the selected row:
-    // the index reads 0 without discarding the underlying selection...
+    // Folding its own group (row 7) hides it: the index reads 0, but the selection stays...
     s.run("CollapseTradeSkillSubClass(7)").unwrap();
     assert_eq!(
         s.eval::<i64>("return GetTradeSkillSelectionIndex()")
             .unwrap(),
         0
     );
-    // ...expanding it again brings the SAME recipe right back into view at row 8.
+    // ...and comes back at row 8.
     s.run("ExpandTradeSkillSubClass(7)").unwrap();
     assert_eq!(
         s.eval::<i64>("return GetTradeSkillSelectionIndex()")
@@ -361,8 +344,7 @@ fn selection_persists_across_collapse_and_a_regroup() {
         8
     );
 
-    // A re-push that drops the selected recipe entirely (its whole group along with it) clears
-    // the selection.
+    // A re-push without the recipe clears the selection.
     let mut without_wind_cloak = state();
     without_wind_cloak.recipes.remove(4);
     s.set_trade_skill(Some(without_wind_cloak));
@@ -383,8 +365,7 @@ fn snapshot_feeds_the_api_tuples_through_the_visible_mapping() {
             .unwrap(),
         ("Tailoring".into(), 57, 75)
     );
-    // 1 header + 2 recipes = 3 visible rows; the first NON-header row is 2 (Simple Robe, the
-    // group's tier-0 recipe).
+    // 1 header + 2 recipes; the first recipe row is 2 (Simple Robe, tier 0).
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 3);
     assert_eq!(s.eval::<i64>("return GetFirstTradeSkill()").unwrap(), 2);
 
@@ -437,7 +418,7 @@ fn selection_persists_across_a_repush_by_spell_id() {
     let mut s = UiScript::new().unwrap();
     s.set_trade_skill(Some(two_recipe_state()));
 
-    // Select "Bolt of Linen Cloth" (spell 2963), the group's tier-3 row (row 3).
+    // Bolt of Linen Cloth (spell 2963) is row 3.
     s.run("SelectTradeSkill(3)").unwrap();
     assert_eq!(
         s.eval::<i64>("return GetTradeSkillSelectionIndex()")
@@ -445,9 +426,7 @@ fn selection_persists_across_a_repush_by_spell_id() {
         3
     );
 
-    // Re-push with the flat array reordered (a reagent-count re-list from the app) — the
-    // ENGINE re-sorts regardless of push order, so Bolt of Linen Cloth stays visible row 3; the
-    // selection follows it there by SPELL ID, not by its (now different) flat array position.
+    // A reordered re-push: the engine re-sorts, and the selection follows the spell id to row 3.
     let mut reordered = two_recipe_state();
     reordered.recipes.swap(0, 1);
     s.set_trade_skill(Some(reordered));
@@ -457,7 +436,7 @@ fn selection_persists_across_a_repush_by_spell_id() {
         3
     );
 
-    // A re-push that drops the selected recipe entirely clears the selection.
+    // A re-push without the recipe clears the selection.
     let mut without_2963 = two_recipe_state();
     without_2963.recipes.remove(0);
     s.set_trade_skill(Some(without_2963));
@@ -478,17 +457,14 @@ fn do_trade_skill_drains_spell_id_and_count() {
     assert_eq!(s.take_trade_skill_dos(), vec![(2963, 5)]);
     assert!(s.take_trade_skill_dos().is_empty(), "drained");
 
-    // Row 2 = Simple Robe (spell 3919, numAvailable 0). No count arg defaults to 1; a
-    // non-positive count clamps up to 1 (the `DoTradeSkill 0x500280` latch floor —
-    // `max(avail, 1)`).
+    // Row 2 = Simple Robe (spell 3919, numAvailable 0): a missing or zero count is 1 (`0x500280`).
     s.run("DoTradeSkill(2) DoTradeSkill(2, 0)").unwrap();
     assert_eq!(s.take_trade_skill_dos(), vec![(3919, 1), (3919, 1)]);
 
-    // An out-of-range index is ignored.
     s.run("DoTradeSkill(99)").unwrap();
     assert!(s.take_trade_skill_dos().is_empty());
 
-    // A HEADER index (row 1, "Cloth") queues nothing either.
+    // Row 1 is the "Cloth" header.
     s.run("DoTradeSkill(1, 5)").unwrap();
     assert!(s.take_trade_skill_dos().is_empty());
 }
@@ -533,7 +509,6 @@ fn no_snapshot_shapes_unknown_line_and_nil_info() {
     s.run("DoTradeSkill(1, 1)").unwrap();
     assert!(s.take_trade_skill_dos().is_empty(), "no window, no intent");
 
-    // Collapse/expand/select on an empty pane are harmless no-ops.
     s.run("CollapseTradeSkillSubClass(0) ExpandTradeSkillSubClass(1) SelectTradeSkill(1)")
         .unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 0);
@@ -557,24 +532,22 @@ fn get_trade_skill_tools_multivalue_shape() {
         ("Anvil", Some(1), "Mining Pick", None)
     );
 
-    // A recipe with no tools returns an empty multivalue (arity 0, not one nil).
+    // No tools: zero values, not one nil.
     let mut t2 = two_recipe_state();
     t2.recipes[0].tools.clear();
     s.set_trade_skill(Some(t2));
     assert_eq!(s.arity("GetTradeSkillTools(3)").unwrap(), 0);
 
-    // A HEADER index (row 1) also returns an empty multivalue.
+    // A header row: zero values too.
     assert_eq!(s.arity("GetTradeSkillTools(1)").unwrap(), 0);
 }
 
-/// The verified persistence story (`0x4fc910`, the `0xbde064` cache key):
-/// collapse/filter/selection state SURVIVES a same-profession close→reopen and resets only
-/// when a DIFFERENT skill line opens.
+/// Persistence keyed by skill line (`0x4fc910`, `0xbde064`).
 #[test]
 fn close_reopen_keeps_state_for_the_same_line_and_resets_on_a_switch() {
     let mut s = UiScript::new().unwrap();
     s.set_trade_skill(Some(two_recipe_state()));
-    s.run("SelectTradeSkill(2)").unwrap(); // Simple Robe (the tier-0 row under the header)
+    s.run("SelectTradeSkill(2)").unwrap(); // Simple Robe, the tier-0 row
     s.run("CollapseTradeSkillSubClass(1)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 1);
 
@@ -591,10 +564,10 @@ fn close_reopen_keeps_state_for_the_same_line_and_resets_on_a_switch() {
         0
     );
 
-    // Reopen the SAME line: the fold survives the round trip (header only, still collapsed)…
+    // The same line: the fold survives...
     s.set_trade_skill(Some(two_recipe_state()));
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 1);
-    // …and so does the selection, by spell id: expand and it's visible index 2 again.
+    // ...and so does the selection, by spell id.
     s.run("ExpandTradeSkillSubClass(1)").unwrap();
     assert_eq!(
         s.eval::<i64>("return GetTradeSkillSelectionIndex()")
@@ -602,7 +575,7 @@ fn close_reopen_keeps_state_for_the_same_line_and_resets_on_a_switch() {
         2
     );
 
-    // A DIFFERENT line resets everything: fully expanded, nothing selected.
+    // A different line resets everything.
     s.run("CollapseTradeSkillSubClass(1)").unwrap();
     let mut other = two_recipe_state();
     other.line = 164; // Blacksmithing
@@ -615,9 +588,7 @@ fn close_reopen_keeps_state_for_the_same_line_and_resets_on_a_switch() {
     );
 }
 
-/// The SubClass filter (ref Blizzard_TradeSkillUI.lua l.406-408): an exclusive set shows only
-/// that group; the vocabulary (`GetTradeSkillSubClasses`) never shrinks; `Get(0)` answers the
-/// all-shown probe; `Set(0, 1, 1)` (the "All Subclasses" row) restores everything.
+/// The subclass filter as the stock menu drives it (`Blizzard_TradeSkillUI.lua:406-409`).
 #[test]
 fn subclass_filter_exclusive_narrows_list_but_not_vocabulary() {
     let mut s = UiScript::new().unwrap();
@@ -652,7 +623,7 @@ fn subclass_filter_exclusive_narrows_list_but_not_vocabulary() {
         1
     );
 
-    // The "All Subclasses" row's own call shape restores everything.
+    // The "All Subclasses" row's call restores everything.
     s.run("SetTradeSkillSubClassFilter(0, 1, 1)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 10);
     assert_eq!(
@@ -662,12 +633,9 @@ fn subclass_filter_exclusive_narrows_list_but_not_vocabulary() {
     );
 }
 
-/// A stand-in string table for the `0x84dd70` token family — **deliberately not the shipped
-/// wording**, because what these tests establish is *which token* each slot bit reaches, never
-/// what the word says (decision 2045, "assert the identifier, not the sentence"). Naming each
-/// value after its own key is the point: `SECONDARYHANDSLOT`, `INVTYPE_SHIELD` and
-/// `INVTYPE_WEAPONOFFHAND` all read "Off Hand" in enUS, so an assertion on the English could not
-/// tell a correct table from one wired to the item tooltip's family.
+/// Stand-in slot strings named after their tokens (`0x84dd70`): `SECONDARYHANDSLOT`,
+/// `INVTYPE_SHIELD` and `INVTYPE_WEAPONOFFHAND` all read "Off Hand" in enUS, so only the token
+/// shows which one a bit reaches.
 fn seed_slot_tokens(s: &mut UiScript) {
     s.run(
         r#"
@@ -687,9 +655,6 @@ fn seed_slot_tokens(s: &mut UiScript) {
     .unwrap();
 }
 
-/// The InvSlot filter: the vocabulary is the distinct slot words ascending by slot bit; an
-/// exclusive set drops every recipe on other slots AND any group that empties — header
-/// included.
 #[test]
 fn invslot_filter_drops_recipes_and_emptied_groups() {
     let mut s = UiScript::new().unwrap();
@@ -728,9 +693,7 @@ fn invslot_filter_drops_recipes_and_emptied_groups() {
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 10);
 }
 
-/// WEAPON (InventoryType 13) is the one multi-bit contribution (`0x18000`): a
-/// one-hand weapon lists BOTH hand slots in the vocabulary and stays visible under either
-/// hand's exclusive filter.
+/// A one-hand weapon (InventoryType 13, `0x18000`) lists both hand slots and passes either.
 #[test]
 fn one_hand_weapon_spans_both_hand_slots() {
     let mut s = UiScript::new().unwrap();
@@ -758,8 +721,8 @@ fn one_hand_weapon_spans_both_hand_slots() {
     );
 }
 
-/// Every engine-side list mutator raises the touched flag exactly once per drain — the app's
-/// cue to fire TRADE_SKILL_UPDATE (the `0x4fd710`/`0x4fd750` in-call event, module doc).
+/// Each filter or fold raises the flag the app answers with TRADE_SKILL_UPDATE (`0x4fd710`,
+/// `0x4fd750`).
 #[test]
 fn filter_and_fold_mutators_raise_the_touched_flag() {
     let mut s = UiScript::new().unwrap();
@@ -779,10 +742,7 @@ fn filter_and_fold_mutators_raise_the_touched_flag() {
     assert!(s.take_trade_skill_touched());
 }
 
-/// The sort's SECONDARY key is the product's ItemLevel, ascending — between the difficulty tier
-/// and the name (the `record+0x14` = item template ItemLevel identity, pinned 2026-07-17). Two
-/// same-tier recipes whose ALPHABETICAL order contradicts their item levels must order by level;
-/// equal levels fall through to the name.
+/// ItemLevel (`record+0x14`) sorts between tier and name.
 #[test]
 fn same_tier_recipes_order_by_product_item_level_before_name() {
     let mut s = UiScript::new().unwrap();
@@ -828,17 +788,12 @@ fn same_tier_recipes_order_by_product_item_level_before_name() {
     assert_eq!(names, ["Cloth", "Mmm Robe", "Zzz Robe", "Aaa Robe"]);
 }
 
-/// The link pair (`0x4ff410`/`0x4ff800`, decision 1973): the product's link in its
-/// quality colour with zero tokens; ZERO values for a header, a missing product or an uncached
-/// template; the reagent link nil on the same misses and always exactly one value; the typo'd
-/// reagent Usage; the number gate.
+/// The two link verbs' shapes (`0x4ff410`, `0x4ff800`).
 #[test]
 fn the_link_verbs_answer_the_clients_shapes() {
     let mut s = UiScript::new().unwrap();
     s.set_trade_skill(Some(state()));
-    // Row 1 is a header; row 2 the first VISIBLE recipe — found by the name the API answers for
-    // it, since the visible order is the grouped one, not the pushed one. Seed its product's and
-    // one reagent's templates.
+    // Row 2 is the first recipe, found by name since the visible order is the sorted one.
     let st = state();
     let row2 = s.eval::<String>("return (GetTradeSkillInfo(2))").unwrap();
     let r = st
diff --git a/crates/benilla-ui/src/script/tradeskill/view.rs b/crates/benilla-ui/src/script/tradeskill/view.rs
index d833495c..798e4082 100644
--- a/crates/benilla-ui/src/script/tradeskill/view.rs
+++ b/crates/benilla-ui/src/script/tradeskill/view.rs
@@ -1,6 +1,5 @@
-//! The display-tree + filter machinery: grouping/sorting the flat `TradeSkillRecipe` list into the
-//! visible-row tree the Era API indexes (see the parent module doc — the grouped-list law and the
-//! byte-VERIFIED `SubClassFilter`/`InvSlot` filter family, `0x4fca20`/`0x4fd180`).
+//! The visible rows the tradeskill API indexes: grouping, sorting and filtering the flat recipes
+//! (`0x4fca20`, `0x4fd180`).
 
 use std::collections::HashMap;
 
@@ -8,13 +7,9 @@ use crate::script::Model;
 
 use super::TradeSkillRecipe;
 
-/// Fold a product's `InventoryType` to its InvSlot-filter contribution (`record+0x10`) — the
-/// real client's 29-entry `DAT_00809200` table with its build-time overrides, dumped in full and
-/// byte-VERIFIED (`0x809200`): FINGER/TRINKET/BAG collapse to their first slot's
-/// single bit (`0xb → 0x400`, `0xc → 0x1000`, `0x12 → 0x80000` — the raw table's multi-slot
-/// entries are dead, overwritten before use), zero contributions (NON_EQUIP/AMMO/QUIVER) take the
-/// `0x800000` catch-all (bit 23), and **WEAPON (13) is the one multi-bit survivor** — `0x18000`,
-/// a one-hand weapon shows under both hand slots.
+/// A product's `InventoryType` as inv-slot filter bits (`record+0x10`): the client's 29-entry
+/// table at `0x809200` after its overrides, so finger, trinket and bag take one bit each, a
+/// one-hand weapon sets both hand bits, and non-equipment takes the catch-all bit 23.
 fn inv_slot_mask(inv_type: u32) -> u32 {
     match inv_type {
         1 => 1 << 0,                  // HEAD
@@ -27,34 +22,22 @@ fn inv_slot_mask(inv_type: u32) -> u32 {
         8 => 1 << 7,                  // FEET
         9 => 1 << 8,                  // WRIST
         10 => 1 << 9,                 // HANDS
-        11 => 1 << 10,                // FINGER (override — single bit)
-        12 => 1 << 12,                // TRINKET (override — single bit)
-        13 => (1 << 15) | (1 << 16),  // WEAPON — both hands (0x18000)
+        11 => 1 << 10,                // FINGER (override: single bit)
+        12 => 1 << 12,                // TRINKET (override: single bit)
+        13 => (1 << 15) | (1 << 16),  // WEAPON: both hands (0x18000)
         14 | 22 | 23 => 1 << 16,      // SHIELD / WEAPONOFFHAND / HOLDABLE
         15 | 25 | 26 | 28 => 1 << 17, // RANGED / THROWN / RANGEDRIGHT / RELIC
         16 => 1 << 14,                // CLOAK (back)
         17 | 21 => 1 << 15,           // 2HWEAPON / WEAPONMAINHAND
-        18 => 1 << 19,                // BAG (override — single bit)
+        18 => 1 << 19,                // BAG (override: single bit)
         19 => 1 << 18,                // TABARD
-        _ => 1 << 23,                 // NON_EQUIP / AMMO / QUIVER / unknown — the catch-all
+        _ => 1 << 23,                 // NON_EQUIP / AMMO / QUIVER / unknown: the catch-all
     }
 }
 
-/// The InvSlot dropdown's per-bit GlobalString **token** — the real client's 24-entry table
-/// (`0x84dd70`), dumped entry by entry. The caller
-/// resolves it against the player's own `GlobalStrings.lua` (decision 2045); these are the
-/// paper-doll `*SLOT` family, **not** the `INVTYPE_*` family the item tooltip's slot line uses,
-/// and that distinction is exactly why the word cannot be stored here: `SECONDARYHANDSLOT`,
-/// `INVTYPE_SHIELD` and `INVTYPE_WEAPONOFFHAND` are three separately-localizable strings that all
-/// read "Off Hand" in enUS.
-///
-/// Bits 11/13/20-22 (`FINGER1SLOT`/`TRINKET1SLOT`/the extra `BAGSLOT`s) are present in the table
-/// but unreachable through [`inv_slot_mask`] — kept for the full 24-entry fidelity.
-///
-/// **`None` is the out-of-range arm and is unreachable by construction**: the only caller walks
-/// [`present_inv_slots`], which enumerates bits 0..23, and the reference's table has an entry for
-/// every one of them. It resolves to the empty string at the call site, which is what
-/// `FrameScript_GetText` hands back for a token the table has no row for.
+/// The inv-slot dropdown's `GlobalStrings.lua` token per bit, the client's 24-entry table at
+/// `0x84dd70`: the paper-doll `*SLOT` names, not the tooltip's `INVTYPE_*` ones. Bits 11, 13 and
+/// 20-22 are in the table, but no `InventoryType` reaches them.
 pub(super) fn inv_slot_token(bit: u32) -> Option<&'static str> {
     Some(match bit {
         0 => "HEADSLOT",
@@ -82,10 +65,8 @@ pub(super) fn inv_slot_token(bit: u32) -> Option<&'static str> {
     })
 }
 
-/// The InvSlot filter vocabulary: the set bits of the accumulated slot mask, ascending — the real
-/// client's bits-0..23 walk over `0xbde058` (`GetTradeSkillInvSlots 0x4ffc20`).
-/// Accumulated over ALL recipes, unfiltered — the mask ORs up at list build, before any filter
-/// applies.
+/// The inv-slot vocabulary: the set bits, ascending, of the slot mask over all recipes, unfiltered
+/// (`0xbde058`, walked by `GetTradeSkillInvSlots`, `0x4ffc20`).
 pub(super) fn present_inv_slots(model: &Model) -> Vec<u32> {
     let Some(t) = model.trade_skill.as_ref() else {
         return Vec::new();
@@ -97,9 +78,8 @@ pub(super) fn present_inv_slots(model: &Model) -> Vec<u32> {
     (0..24).filter(|b| accum & (1 << b) != 0).collect()
 }
 
-/// Whether a recipe passes the current filters (the recompute's own row test, `0x4fd180`): its slot
-/// contribution overlaps the shown-mask (`record+0x10 & 0x84dd64 != 0`) and its group isn't
-/// subclass-hidden.
+/// The recompute's row test (`0x4fd180`): the slot bits meet the shown mask (`0x84dd64`) and the
+/// group is not hidden.
 fn passes_filters(model: &Model, r: &TradeSkillRecipe) -> bool {
     let key = r
         .group
@@ -109,40 +89,27 @@ fn passes_filters(model: &Model, r: &TradeSkillRecipe) -> bool {
         && inv_slot_mask(r.product_inv_type) & model.trade_skill_invslot_mask != 0
 }
 
-/// One recipe group in the synthesized display tree (`0x4fca20`): the created item's
-/// `(ItemClass, ItemSubClass)` key (the collapse key) + resolved display name, and the positions
-/// (into [`TradeSkillState::recipes`]) of the group's recipes, pre-sorted by tier, product
-/// ItemLevel, then name.
-/// Engine-internal — rebuilt fresh from the flat recipes on every query ([`build_groups`]) rather
-/// than cached on [`Model`] (unlike [`super::skills::SkillGroup`]): `TradeSkillState` has no
-/// engine-owned tree field of its own, so [`Row::Header`] just carries the group's key/name
-/// directly instead of an index into a cached `Vec`.
+/// One recipe group (`0x4fca20`), keyed by the product's `(ItemClass, ItemSubClass)` and rebuilt
+/// on every query.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub(super) struct TradeSkillGroup {
     pub(super) key: (u32, u32),
     pub(super) name: String,
-    /// Positions into [`TradeSkillState::recipes`], sorted by tier, product ItemLevel, then
-    /// [`collate`]d name.
+    /// Positions into `TradeSkillState::recipes`, in display order.
     entries: Vec<usize>,
 }
 
-/// The WoW enUS collator, approximated ([`super::skills`]/[`super::trainer`]'s own helper,
-/// duplicated here rather than shared — each seam module keeps its own copy, the established local
-/// convention): case-insensitive alphabetical, raw bytes as a stable tie-break.
+/// An approximation of the reference's name compare, the case-insensitive `0x64a4c0`:
+/// case-insensitive, then raw bytes.
 fn collate(a: &str, b: &str) -> std::cmp::Ordering {
     a.to_lowercase()
         .cmp(&b.to_lowercase())
         .then_with(|| a.cmp(b))
 }
 
-/// Build the display tree from the flat recipes (the module doc's grouped-list law,
-/// `0x4fca20`): group by the created item's `(ItemClass, ItemSubClass)` — a recipe with no
-/// group yet (`group: None`, its product template still in flight) buckets into the trailing
-/// `(u32::MAX, u32::MAX)`/`""` group; sort each group's recipes by tier, then the product's
-/// **ItemLevel ascending** (the `record+0x14` secondary key — field identity pinned 2026-07-17,
-/// [`TradeSkillRecipe::product_item_level`]), then [`collate`]d name; sort the groups by
-/// `ItemClass` id ascending, ties broken by [`collate`]d name (never by subclass id — the pending
-/// group's `u32::MAX` class id sorts it last with no special-casing needed).
+/// The groups in display order (`0x4fca20`): by `ItemClass`, then name, never subclass id; each
+/// group's recipes by tier, product ItemLevel (`record+0x14`), then name. A recipe with no group
+/// yet goes into an empty-named group keyed `u32::MAX`, which sorts last.
 pub(super) fn build_groups(recipes: &[TradeSkillRecipe]) -> Vec<TradeSkillGroup> {
     let mut map: HashMap<(u32, u32), TradeSkillGroup> = HashMap::new();
     for (i, r) in recipes.iter().enumerate() {
@@ -183,22 +150,16 @@ pub(super) fn build_groups(recipes: &[TradeSkillRecipe]) -> Vec<TradeSkillGroup>
     groups
 }
 
-/// One visible row of the display tree: a group **header** (carrying its key/name — see
-/// [`TradeSkillGroup`]'s own doc for why this isn't an index) or a **recipe** (carrying its
-/// position into [`TradeSkillState::recipes`]).
+/// One visible row: a group header, or a recipe's position in `TradeSkillState::recipes`.
 #[derive(Clone)]
 pub(super) enum Row {
     Header { key: (u32, u32), name: String },
     Entry(usize),
 }
 
-/// The visible rows in display order: each group's header, then — when the group isn't
-/// collapsed — its recipes that pass the filters ([`passes_filters`]). A subclass-hidden group,
-/// or one whose every recipe the InvSlot filter drops, contributes NO rows at all — header
-/// included (the real window never shows an empty header under a filter — the visibility law
-/// decision 0452 landed byte-exact, `0x4fd180`: filtered recipes and emptied/
-/// filtered headers drop out of the numbered list; a merely-collapsed header stays). The Lua's
-/// 1-based `index` is a position in *this* list. Empty when no window is open.
+/// The visible rows every Lua index is 1-based into: each group's header, then its recipes that
+/// pass the filters unless it is folded. A group the filters empty loses its header too; a merely
+/// folded one keeps it (`0x4fd180`).
 pub(super) fn rows(model: &Model) -> Vec<Row> {
     let Some(t) = model.trade_skill.as_ref() else {
         return Vec::new();
@@ -230,19 +191,12 @@ pub(super) fn rows(model: &Model) -> Vec<Row> {
     out
 }
 
-/// The count of visible rows (headers + the recipes of uncollapsed groups).
 pub(super) fn num_rows(model: &Model) -> usize {
     rows(model).len()
 }
 
-/// The recipe at a 1-based VISIBLE index, or `None` when that row is a header (or OOB) — so every
-/// per-recipe getter/`DoTradeSkill` safely no-ops on a header row (`0x4fca20`).
-///
-/// `pub(crate)`: the tooltip channel (`super::tooltip_item`'s `SetTradeSkillItem`) SHOULD route
-/// through this too — a header index, or the header rows preceding a real recipe, would otherwise
-/// misalign a raw `TradeSkillState::recipes` index against the visible list the XML actually clicks
-/// through. See the module doc's "KNOWN GAP" note: that follow-up isn't done here (out of this
-/// change's file scope), but the seam is exposed for it.
+/// The recipe at a 1-based visible index; `None` on a header, so the per-recipe verbs and
+/// `SetTradeSkillItem` no-op there.
 pub(crate) fn recipe_at(model: &Model, index: usize) -> Option<&TradeSkillRecipe> {
     let n = index.checked_sub(1)?;
     match rows(model).get(n)? {
@@ -251,7 +205,7 @@ pub(crate) fn recipe_at(model: &Model, index: usize) -> Option<&TradeSkillRecipe
     }
 }
 
-/// The first NON-header visible index (`GetFirstTradeSkill`'s law), `0` when none.
+/// `GetFirstTradeSkill`: the first recipe row's visible index, 0 when none.
 pub(super) fn first_recipe_index(model: &Model) -> u32 {
     rows(model)
         .iter()
@@ -259,13 +213,8 @@ pub(super) fn first_recipe_index(model: &Model) -> u32 {
         .map_or(0, |p| (p + 1) as u32)
 }
 
-/// `GetTradeSkillSelectionIndex()` — the CURRENT visible index of the engine-held selection (`0`
-/// when nothing is selected, or the selected recipe isn't visible right now, e.g. its group just got
-/// collapsed). [`Model::trade_skill_selection`] holds a stable position into the open window's FLAT
-/// `recipes` list (module doc) — collapse/expand never touches it, only what [`rows`] shows, so this
-/// derives the visible position fresh on every read rather than needing an eager remap on every
-/// collapse toggle ([`super::skills`]'s own by-identity pattern, adapted to a field this module can't
-/// change the type of).
+/// `GetTradeSkillSelectionIndex`: the selection's visible index, 0 when none or hidden. The
+/// selection is held as a flat recipe position, so a fold never moves it.
 pub(super) fn selected_visible_index(model: &Model) -> u32 {
     let Some(pos) = model.trade_skill_selection.checked_sub(1) else {
         return 0;
@@ -276,19 +225,15 @@ pub(super) fn selected_visible_index(model: &Model) -> u32 {
         .map_or(0, |p| (p + 1) as u32)
 }
 
-/// `SelectTradeSkill(index)` — resolve the 1-based VISIBLE index to a position in the open window's
-/// flat recipe list and hold THAT ([`selected_visible_index`]'s own doc). A HEADER row is IGNORED —
-/// the prior selection is left exactly as it was (the module doc: the ref's own `SetSelection`
-/// toggles the fold instead of selecting, so a header index never reaches here through the XML in
-/// practice, but the engine contract holds regardless). An out-of-range index clears the selection
-/// (the pre-existing convention, unchanged).
+/// `SelectTradeSkill`: holds the recipe at a visible index. A header index leaves the selection
+/// as it was, and an out-of-range one clears it; the stock Lua folds a header instead of selecting
+/// it (`Blizzard_TradeSkillUI.lua:184-192`).
 pub(super) fn select(model: &mut Model, index: u32) {
     let visible = rows(model);
     match index.checked_sub(1).and_then(|n| visible.get(n as usize)) {
         Some(Row::Entry(ei)) => {
             model.trade_skill_selection = (*ei + 1) as u32;
-            // The spell-id shadow (`0xbde044`'s own storage) — what survives a close→reopen and
-            // remaps across a re-push ([`super::UiScript::set_trade_skill`]).
+            // The spell id (`0xbde044`) is what survives a close and remaps across a re-push.
             model.trade_skill_selected_spell = model
                 .trade_skill
                 .as_ref()
@@ -303,11 +248,8 @@ pub(super) fn select(model: &mut Model, index: u32) {
     }
 }
 
-/// Collapse (`collapse = true`) or expand a group by the **display index of its header row**
-/// ([`super::skills`]'s own `Collapse/ExpandSkillHeader` shape). `id == 0` targets ALL groups (the
-/// CollapseAll semantics — no such button ships this slice, the XML's own deviation note); `id > 0`
-/// resolves the header at that visible index to its group key. A non-header (or OOB) index is a
-/// no-op.
+/// Folds or unfolds the group whose header is visible row `id`; 0 is every group, as the stock
+/// collapse-all button passes, and any other row is a no-op.
 pub(super) fn set_collapsed(model: &mut Model, id: usize, collapse: bool) {
     if id == 0 && !collapse {
         model.trade_skill_collapsed.clear();
diff --git a/crates/benilla-ui/src/script/trainer/mod.rs b/crates/benilla-ui/src/script/trainer/mod.rs
index 1fd6b041..070b1f75 100644
--- a/crates/benilla-ui/src/script/trainer/mod.rs
+++ b/crates/benilla-ui/src/script/trainer/mod.rs
@@ -1,97 +1,24 @@
-//! The trainer bindings (decision 0237) — the Era-shaped class/profession trainer surface driving a
-//! faithful port of the real 1.12 `ClassTrainerFrame` (extracted from `interface.MPQ`:
-//! `Interface\FrameXML\ClassTrainerFrame.{xml,lua}`). Same two-way seam as [`super::merchant`]: the
-//! app pushes a **trainer snapshot** ([`UiScript::set_trainer`] — the wire services already resolved
-//! to name/icon/cost/state/requirements by the app), and the Lua `BuyTrainerService`/`CloseTrainer`
-//! calls queue outbound **intents** the app drains ([`UiScript::take_trainer_buys`] returns the
-//! chosen services' **spell ids** / [`UiScript::take_trainer_close`]). The engine holds no trainer
-//! knowledge — a service is name/subtext/icon/cost/state/gates/description, all app-resolved.
-//!
-//! ## The Era API shape (matched to the real `ClassTrainerFrame.lua`)
-//!
-//! The reference window's `.lua` is transcribed onto these bindings, so the return *shapes* match it
-//! verbatim: `GetTrainerServiceInfo → name, subText, serviceType, isExpanded`;
-//! `GetTrainerServiceCost → money, talentPointCost, professionPointCost`;
-//! `GetTrainerServiceSkillReq → skill, rank, hasReq`; `GetTrainerServiceAbilityReq → name, hasReq`;
-//! `IsTrainerServiceLearnSpell → isLearnSpell, isPetLearnSpell`. `serviceType` is either the string
-//! `"header"` (a skill-line group header, with `isExpanded` set) or the service's colour state
-//! `"available"`/`"unavailable"`/`"used"` (green/red/gray, `isExpanded` nil).
-//!
-//! ## The tree (decisions 0247 + 1124 — the byte-verified grouping/sort model, **per trainer type**)
-//!
-//! The 1.12 wire (`SMSG_TRAINER_LIST`) is a **flat** service list; the client builds a **collapsible
-//! tree** on top of it, and `index` is **1-based into that visible tree**, not the wire order.
-//! [`UiScript::set_trainer`] takes the flat services (each already carrying its app-resolved
-//! [`TrainerService::group_key`]/[`TrainerService::group_name`]) and synthesizes the tree: one
-//! **header row per distinct group key**, then that group's services in the group's own order. State
-//! is a per-row **colour**, never the grouping key.
-//!
-//! **The `trainerType` selects everything** — the list finalizer `0x4d8410` picks the row comparator
-//! by `ds:0xb73a08` (`dec eax; je` chain @ `0x4d8561`) and the builder `0x4d7560` picks both the
-//! group key and the header comparator by the same dword (`0x4d7786`, `0x4d79eb`). Neither the group
-//! key nor the sort is one law with a "later refinement" — they are four laws, and 1124 is where
-//! benilla stopped applying the class one to all of them:
-//!
-//! | type | rows | headers | group key |
-//! |---|---|---|---|
-//! | 0 class, 3 pet | `0x4d85c0` — level → skill value → name → rank | `0x4d7b90`, by name | taught spell's `SkillLine` |
-//! | 1 mount ("talent") | `0x4d8850` — **state byte → name** | `0x4d7b90`, `-1` first then by name | `-1` when the service is `used`, else the `SkillLine` |
-//! | 2 tradeskill | `0x4d8760` — **skill value → name**, no level key, no rank key | `0x4d7c30`, by **raw key asc** | **1 or 2**, see below |
-//!
-//! At type 2 the group key is **not a skill line and never resolves one**: the builder defaults it
-//! to 2 and sets it to 1 iff the **wire** spell's own `Spell.dbc Effect[0..2]` contains `44`
-//! `SKILL_STEP` (`0x4d77b6`), which makes exactly two groups — `TRADESKILL_SERVICE_STEP` ("Development
-//! Skills", the profession-learn services) and `TRADESKILL_SERVICE_LEARN` ("Recipes") — and means
-//! **no row is ever dropped at a tradeskill trainer**. That partition, not a level key, is what puts
-//! "Apprentice Blacksmith" at the top of a blacksmithing trainer: `reqLevel` is inert at type 2.
-//! At the other types a service whose group key is `0` (unresolved skill line) is still dropped,
-//! matching the client.
-//!
-//! A service hides when its state fails the dropdown filter ([`Model::trainer_filter`]) or its group
-//! is collapsed ([`Model::trainer_collapsed`]) — but **hiding is not removing**: the client parks a
-//! hidden record in a tail behind the visible ones and keeps its index, so `GetNumTrainerServices`
-//! answers with the *visible* count while every getter's index space is the *whole* array ([`rows`]).
-//! An index past the count is a legal hidden row, and the stock window is handed exactly one after a
-//! purchase ([`selected_row`]). `Collapse/ExpandTrainerSkillLine(id)` take the **display index of a
-//! header row** (`id == 0` = all groups — the collapse-all button); they toggle that group's
-//! visibility, never reorder.
-//!
-//! The **selection** is likewise the selected service's **spell id** (`ds:0xb73a0c`), re-resolved to
-//! a position on every `GetTrainerSelectionIndex` — never a stored row number ([`selected_row`]).
-//!
-//! ## Faithful stubs (no wire data yet — kept so the ported XML runs)
-//!
-//! `GetTrainerServiceStepReq` returns nil (no tradeskill-step data on the wire), and per-requirement
-//! `hasReq`/`met` flags are derived from the service's overall `category` (an unavailable service has
-//! an unmet gate) rather than a per-gate wire bit, which 5875 does not send.
-//!
-//! One thing the client does that this engine does not, named rather than left to be discovered: a
-//! group whose row counters go to zero **vanishes entirely, header included** (`0x4d8460`,
-//! `0x4d8528`–`0x4d8549`) — which is how a type-1 trainer whose every service is `used` shows one
-//! "My Talents" header and no skill-line headers at all. benilla always keeps a header. The case
-//! that is *reachable* here (does the state-filter dropdown emptying a group also take its header?)
-//! is an open question; the build-time case above cannot arise, because benilla builds
-//! a group only from services that exist.
+//! The trainer bindings the stock `Blizzard_TrainerUI` window calls, over the snapshot the app
+//! pushes ([`UiScript::set_trainer`]). `SMSG_TRAINER_LIST` is flat; the client builds a collapsible
+//! tree of header and service rows over it, every Lua index is 1-based into that tree, and the
+//! trainer type (`ds:0xb73a08`) picks the row comparator (`0x4d8561`), the group key and the
+//! header comparator (`0x4d7786`, `0x4d79eb`).
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// The green/red/gray state of a service (the wire's `TrainerSpellState`, decision 0237), surfaced to
-/// Lua as the Era `category` string `GetTrainerServiceInfo` returns.
+/// A service's state (the wire's `TrainerSpellState`): green learnable, red gated, gray known.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub enum TrainerServiceCategory {
-    /// Green — learnable now.
     #[default]
     Available,
-    /// Red — a requirement (level / skill / prerequisite) is unmet.
     Unavailable,
-    /// Gray — already known.
     Used,
 }
 
 impl TrainerServiceCategory {
-    /// The Era `category` string (`ClassTrainerFrame`'s colour switch reads exactly these).
+    /// `GetTrainerServiceInfo`'s type string, which the stock window colours each row by.
     fn era_str(self) -> &'static str {
         match self {
             TrainerServiceCategory::Available => "available",
@@ -109,10 +36,8 @@ impl TrainerServiceCategory {
         }
     }
 
-    /// The row's **state byte** `[+0x30]` — the value `0x4d8ba0` maps to the colour string (`0` →
-    /// available, `2` → used, anything else → unavailable). It is a colour on every trainer type but
-    /// one: at type 1 it is also the third sort key ([`talent_order`]), which is why this exists
-    /// separately from the filter slot it numerically coincides with.
+    /// The record's state byte `[+0x30]`, which `0x4d8ba0` maps to the type string; at type 1 it is
+    /// also a sort key ([`talent_order`]), so it stays apart from the equal filter slot.
     fn state_key(self) -> u8 {
         match self {
             TrainerServiceCategory::Available => 0,
@@ -121,7 +46,6 @@ impl TrainerServiceCategory {
         }
     }
 
-    /// Parse the Era filter-type string the sort checkboxes pass.
     fn from_filter_str(s: &str) -> Option<Self> {
         match s {
             "available" => Some(TrainerServiceCategory::Available),
@@ -132,8 +56,8 @@ impl TrainerServiceCategory {
     }
 }
 
-/// A skill-line requirement on a service (`GetTrainerServiceSkillReq`): the skill's display name, the
-/// rank required, and whether the player meets it (`hasReq`, derived from the service `category`).
+/// A service's skill requirement (`GetTrainerServiceSkillReq`). The wire has no per-gate bit, so
+/// `met` comes from the service's `category`.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct TrainerSkillReq {
     pub name: String,
@@ -141,38 +65,27 @@ pub struct TrainerSkillReq {
     pub met: bool,
 }
 
-/// A prerequisite-ability requirement (`GetTrainerServiceAbilityReq`): the ability's display name and
-/// whether the player has it (`hasReq`).
+/// A prerequisite ability (`GetTrainerServiceAbilityReq`); `met` is whether the player knows it.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct TrainerAbilityReq {
     pub name: String,
     pub met: bool,
 }
 
-/// What `GameTooltip:SetTrainerService` describes for one row — the pre-resolved output of the
-/// **app-side** tooltip law (`ui_trainer::service_tooltip`, transcribing `SetTrainerService
-/// 0x5338b0`). The engine holds no DBC, so the app decides the subject and the engine only picks a
-/// renderer; the binding in the real client does exactly that too — it emits no line of its own and
-/// is a three-way selector into the shared spell builder `0x52e610` or item builder `0x52b650`.
-///
-/// This is deliberately **not** derivable from [`TrainerService::texture`]: the tooltip and the icon
-/// disagree, by design and in both directions (`0x4d8f50` gates on trainer-type, `0x5338b0` does
-/// not — the icon needs a trainer-type gate the tooltip does not have, and the icon pins the *wire*
-/// wrapper where the tooltip hops to the *taught* spell). On ~806 of the shipped corpus's trainer
-/// services the reference client visibly shows one spell's icon above another spell's tooltip.
+/// What `GameTooltip:SetTrainerService` (`0x5338b0`) describes for a row, resolved by the app; the
+/// reference only picks the spell builder `0x52e610` or the item builder `0x52b650`. Not derivable
+/// from [`TrainerService::texture`]: the icon (`0x4d8f50`) gates on the trainer type and shows the
+/// wire spell, while the tooltip describes the taught one.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum TrainerTooltip {
-    /// The ITEM builder, on this item id — the taught spell carries `SPELL_ATTR_IS_TRADESKILL`.
-    /// `0` (or a template still in flight) renders an EMPTY tooltip, which is the client's own
-    /// behaviour: the builder early-outs on a cache miss and the query is enqueued.
+    /// The item builder on this item id, for a taught spell with `SPELL_ATTR_IS_TRADESKILL`; 0 or
+    /// an uncached template renders empty, as the reference's builder does on a cache miss.
     Item(u32),
-    /// The SPELL builder, on the taught spell — or on the wire spell itself when no learn-wrapper
-    /// slot resolved, the only path that describes the wrapper.
+    /// The spell builder on the taught spell, or on the wire spell when no learn slot resolved.
     Spell {
         spell_id: u32,
-        /// `param5` altCaster — ONE gate suppressing BOTH the totems and the reagents lines
-        /// (byte-verified at `0x52ed43` and `0x52f393`). Set exactly when the matched wrapper slot
-        /// was `SPELL_EFFECT_LEARN_PET_SPELL`.
+        /// The builder's altCaster argument, which drops the totem and reagent lines (`0x52ed43`,
+        /// `0x52f393`); set when the matched slot is `SPELL_EFFECT_LEARN_PET_SPELL`.
         alt_caster: bool,
     },
 }
@@ -186,88 +99,63 @@ impl Default for TrainerTooltip {
     }
 }
 
-/// One trainer service row, resolved by the app from the wire `TrainerSpell` (decision 0237). Plain
-/// data — position in [`TrainerState::services`] is the *unsorted* wire order; the 1-based index the
-/// Lua uses is a position in the visible display tree ([`rows`], built from [`TrainerState::groups`]).
+/// One service, resolved by the app from the wire `TrainerSpell`; its place in
+/// [`TrainerState::services`] is wire order, not display order.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TrainerService {
-    /// The service spell id — what the app sends for `CMSG_TRAINER_BUY_SPELL` when this row is bought.
+    /// The wire spell id, which `CMSG_TRAINER_BUY_SPELL` names.
     pub spell_id: u32,
-    /// The spell name (`GetTrainerServiceInfo`'s first return); `None` while `Spell.dbc` is still
-    /// loading (the API reports `nil`, the XML shows `UNKNOWN`).
+    /// The wire spell's name; `None` (before `Spell.dbc` loads) answers nil, shown as `UNKNOWN`.
     pub name: Option<String>,
-    /// The rank/subtext line (`Spell.dbc` NameSubtext — "Rank N"); `None`/empty shows no second line.
+    /// The wire spell's rank text, such as "Rank 2".
     pub subtext: Option<String>,
-    /// Icon texture path (`Interface\Icons\…`); `None` while the catalog answer is in flight.
     pub texture: Option<String>,
-    /// The spell description shown in the detail pane (`GetTrainerServiceDescription`); `""` when the
-    /// app has no description source yet.
     pub description: String,
-    /// Money cost in copper (already reputation-discounted server-side).
+    /// In copper, already reputation-discounted by the server.
     pub cost: u32,
-    /// A primary-profession first rank — the real window's `cpCost2 > 0` (the profession-point cost
-    /// that raises the "you can only have two professions" confirm dialog).
+    /// A primary profession's first rank: the stock window's `cpCost2 > 0`, which asks to confirm.
     pub prof_first_rank: bool,
-    /// The green/red/gray colour ([`TrainerServiceCategory`]).
     pub category: TrainerServiceCategory,
-    /// Character level required (0 = none).
     pub level_req: u32,
-    /// The skill-line requirement, or `None` when the service has no skill gate.
     pub skill_req: Option<TrainerSkillReq>,
-    /// Prerequisite-ability requirements (resolved from the wire's req-spell ids); empty when none.
     pub ability_reqs: Vec<TrainerAbilityReq>,
-    /// A tradeskill step (`IsTrainerServiceTradeSkill`) vs. a plain learn-spell.
     pub is_trade_skill: bool,
-    /// The tree's grouping key, resolved app-side by the **trainer type's own** builder law
-    /// (module doc, decision 1124): the taught spell's `SkillLine` at types 0/1/3, or the
-    /// `SKILL_STEP` partition's `1`/`2` at type 2. `0` = unresolved: the service is **dropped** from
-    /// the tree (the client's `skillLine == 0 → drop`) — reachable only at types 0/1/3.
+    /// The tree group: the taught spell's `SkillLine` at types 0, 1 and 3, where 0 (unresolved)
+    /// drops the service and a known service at type 1 takes `TRAINER_GROUP_KNOWN`; at type 2, 1
+    /// when the wire spell has a `SKILL_STEP` (44) effect, else 2 (`0x4d77b6`), so a tradeskill
+    /// trainer drops nothing.
     pub group_key: u32,
-    /// The group's localized display name — the header row's text. `SkillLine.dbc`'s name at types
-    /// 0/1/3; the `TRADESKILL_SERVICE_STEP`/`_LEARN` global strings at type 2.
+    /// The header text: the skill line's name, `KNOWN_TALENTS_HEADER` for the known group, or at
+    /// type 2 `TRADESKILL_SERVICE_STEP`/`_LEARN`.
     pub group_name: String,
-    /// What the detail-icon hover describes ([`TrainerTooltip`]) — resolved app-side, because the
-    /// law reads `Spell.dbc` fields the engine cannot see. Independent of [`Self::texture`].
     pub tooltip: TrainerTooltip,
 }
 
-/// One group in the display tree (decisions 0247/1124): the header's key + name and the positions
-/// (into [`TrainerState::services`]) of the group's services, pre-sorted by the trainer type's
-/// within-group comparator. Synthesized by [`UiScript::set_trainer`] — the app pushes only the flat
-/// services.
+/// One header and its services, built by [`UiScript::set_trainer`].
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TrainerGroup {
-    /// The group key (also the collapse key).
+    /// Also the collapse key.
     pub key: u32,
-    /// The header's display name.
     pub name: String,
-    /// The group's services, as positions into [`TrainerState::services`], in display order.
+    /// Positions into [`TrainerState::services`], in display order.
     pub services: Vec<usize>,
 }
 
-/// One open trainer window: the services, the greeting line, and the wire trainer type. Pushed whole
-/// by the app; `None` means no trainer is open (the window is closed).
+/// The open trainer, pushed whole by the app.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TrainerState {
     pub services: Vec<TrainerService>,
-    /// The trainer's greeting/title line (`SMSG_TRAINER_LIST`'s trailing string).
+    /// `SMSG_TRAINER_LIST`'s trailing string.
     pub greeting: String,
-    /// `SMSG_TRAINER_LIST`'s `trainerType` (`ds:0xb73a08`), verbatim — **the** switch: it selects the
-    /// row comparator, the header comparator and the group-key law (module doc), and it is what the
-    /// two whole-trainer predicates test (`IsTradeskillTrainer 0x4d8ea0`: `== 2`; `IsTalentTrainer
-    /// 0x4d8ed0`: `== 1`). 0 class · 1 mount · 2 tradeskill · 3 pet.
+    /// `SMSG_TRAINER_LIST`'s trainer type (`ds:0xb73a08`): 0 class, 1 mount, 2 tradeskill, 3 pet.
     pub trainer_type: u32,
-    /// The sorted skill-line groups over `services` — **built by [`UiScript::set_trainer`]**, not
-    /// pushed by the app (default-empty on a bare `TrainerState`). The display tree walks these.
+    /// Built by [`UiScript::set_trainer`], not pushed by the app.
     pub groups: Vec<TrainerGroup>,
 }
 
 impl super::UiScript {
-    /// Push (or clear, with `None`) the open trainer's service snapshot. On a push, the engine
-    /// **builds the skill-line tree** ([`build_groups`]) from the flat services and prunes the
-    /// collapse set to the lines that still exist (so a collapse survives a content update — a buy
-    /// re-lists — but a switch to a different trainer starts expanded). Clearing resets the selection
-    /// and the collapse set (a closed window holds nothing).
+    /// Push the open trainer, or clear it with `None`. A push builds the tree ([`build_groups`])
+    /// and keeps only the collapsed groups that still exist, so a fold survives a content update.
     pub fn set_trainer(&mut self, state: Option<TrainerState>) {
         let mut model = self.model_mut();
         match state {
@@ -285,37 +173,15 @@ impl super::UiScript {
         }
     }
 
-    /// **Reset what one `SMSG_TRAINER_LIST` arriving resets — the state filter, the collapse set,
-    /// and the selection.**
+    /// Reset what each `SMSG_TRAINER_LIST` resets in the reference (`0x4d7560`): the filter to mask
+    /// 3, or 5 at a mount trainer (`0x4d75d9`), the collapse set and the selection. Call it per
+    /// packet, never per snapshot: the repaint path `0x4d7d40` touches none of the three.
     ///
-    /// Byte-verified (decision 1128): the list builder writes the filter mask itself on every
-    /// packet — `0x4d75d9 mov ds:0xb73a1c,3`
-    /// (available|unavailable, "already known" OFF), or `5` (available|used) when `trainerType == 1`
-    /// — alongside `ds:0xb73a20 = ds:0xb73a24 = 0xffffffff`, which is "no group collapsed". So the
-    /// player's filter choice does NOT live in the engine across trainer visits in the reference: it
-    /// lives in the saved variable `TRAINER_FILTER_*`, and the window's show handler pushes it back
-    /// over this reset (decision 1128; `TrainerFrame.xml`'s `BenillaTrainerFrame_ApplyFilter`).
-    ///
-    /// **The selection is the same edge and the same law.** `0x4d7560`'s tail selects record 0 —
-    /// `0x4d7b40 xor ecx,ecx` → `0x4d7b42 call 0x4d74f0`, after the sort — and since row 0 is always
-    /// a group header, whose record carries the id `0xffffffff` (`0x4d7b05`), the getter's scan
-    /// finds the first header and answers **1**. Clearing is the same thing to every caller: the
-    /// stock window only ever asks `GetTrainerSelectionIndex() > 1`, which 0 and 1 both fail, so
-    /// both send it down `ClassTrainer_SelectFirstLearnableSkill`. Without this a re-opened trainer
-    /// could inherit a selection from the last visit — the same spell id, still in the list, still
-    /// resolving — which the reference cannot do.
-    ///
-    /// The repaint path `0x4d7d40` touches **none** of the three (a `ds:0xb73a0c` census over the
-    /// whole image returns four references, all in the setter/getter/teardown), which is why a
-    /// purchase leaves the selection sitting on the service it just greyed out.
-    ///
-    /// This is the **packet** edge, not the content edge — [`Self::set_trainer`] runs on every
-    /// snapshot change (an item template landing, a name resolving), and the reference's repaint path
-    /// `0x4d7d40` does not touch either mask. Reset there and a filter would evaporate mid-window.
+    /// Deviation: the selection clears to 0, because the header the reference re-selects
+    /// (`0x4d7b42`, reading 1) has no spell id; the stock window's `> 1` test treats 0 and 1 alike.
     pub fn reset_trainer_list_state(&mut self, trainer_type: u32) {
         let mut model = self.model_mut();
-        // Mask 5 at a mount/"talent" trainer: available + already-known, which is what makes a
-        // known mount visible under its "My Talents" header at all (decision 1124's group -1).
+        // Mask 5 at a mount trainer shows available and known services, so the known group shows.
         model.trainer_filter = if trainer_type == TRAINER_TYPE_MOUNT {
             [true, false, true]
         } else {
@@ -325,59 +191,47 @@ impl super::UiScript {
         model.trainer_selection = None;
     }
 
-    /// Drain the **spell ids** `BuyTrainerService` queued since the last call (the engine resolves each
-    /// clicked filtered row to its service's spell id, so the app sends `CMSG_TRAINER_BUY_SPELL`
-    /// without needing to know the filter/index mapping).
+    /// Drain the spell ids `BuyTrainerService` queued, each already resolved from its row.
     pub fn take_trainer_buys(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().trainer_buys)
     }
 
-    /// Whether `CloseTrainer` was called since the last drain (and clear the flag). vanilla's
-    /// client-side close sends no packet — the app just clears its local trainer state.
+    /// Whether `CloseTrainer` was called since the last drain; the close sends no packet.
     pub fn take_trainer_close(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().trainer_close)
     }
 }
 
-/// One visible row of the display tree: a skill-line **header** (carrying its group index) or a
-/// **service** (carrying its position into [`TrainerState::services`]).
+/// One row: a header by group index, or a service by its position in [`TrainerState::services`].
 #[derive(Clone, Copy)]
 enum Row {
     Header(usize),
     Service(usize),
 }
 
-/// The WoW enUS collator (`0x64a480`), approximated: case-insensitive alphabetical, with the raw
-/// bytes as a stable tie-break so equal-when-folded names keep a deterministic order.
+/// Folds case, raw bytes breaking ties. The reference's row comparators call the case-sensitive
+/// `0x64a480`, its header comparator the case-insensitive `0x64a4c0` (`0x4d7c12`).
 fn collate(a: &str, b: &str) -> std::cmp::Ordering {
     a.to_lowercase()
         .cmp(&b.to_lowercase())
         .then_with(|| a.cmp(b))
 }
 
-/// `SMSG_TRAINER_LIST`'s tradeskill `trainerType` (module doc's table).
 const TRAINER_TYPE_TRADESKILL: u32 = 2;
-/// `SMSG_TRAINER_LIST`'s mount `trainerType` — the one the client's own vocabulary calls "talent"
-/// (`IsTalentTrainer 0x4d8ed0` tests it).
+/// The mount trainer type, which the client calls "talent".
 const TRAINER_TYPE_MOUNT: u32 = 1;
 
-/// The already-known group a **type 1** trainer buckets its `used` services into — the client's
-/// signed `-1` group key (`0x4d77e8`), whose header takes the `KNOWN_TALENTS_HEADER` global string
-/// ("My Talents", 1.12.1 enUS). Modelled as `u32::MAX` because the key is otherwise a skill-line id;
-/// the header comparator `0x4d7b90` tests for it explicitly and sorts it **first**, ahead of the
-/// name ordering that ranks every other header.
+/// The group a type 1 trainer files its `used` services under: the client's signed -1 key
+/// (`0x4d77e8`), headed `KNOWN_TALENTS_HEADER` and sorted before every other header by `0x4d7b90`.
 pub const TRAINER_GROUP_KNOWN: u32 = u32::MAX;
 
-/// A service's required-skill value (`[+0x1c]`, the wire's `reqSkillValue`) — `0` when the service
-/// carries no skill gate.
+/// The record's required-skill value `[+0x1c]`, 0 with no skill gate.
 fn skill_value(s: &TrainerService) -> u32 {
     s.skill_req.as_ref().map_or(0, |r| r.rank)
 }
 
-/// The within-group comparator for a **class** (type 0) or **pet** (type 3) trainer — keys ④–⑦ of
-/// the verified `0x4d85c0`: required level (`[+0x14]` byte) → required-skill value (`[+0x1c]` u32) →
-/// localized name → localized rank/subtext, all ascending. Pet is not special-cased anywhere in the
-/// selection chain at `0x4d8561`; it lands here with class.
+/// Rows at a class or pet trainer (`0x4d85c0`; `0x4d8561` sends pet here too): required level,
+/// skill value, name, then rank, all ascending.
 fn class_order(a: &TrainerService, b: &TrainerService) -> std::cmp::Ordering {
     let name = |s: &TrainerService| s.name.clone().unwrap_or_default();
     let rank = |s: &TrainerService| s.subtext.clone().unwrap_or_default();
@@ -388,13 +242,8 @@ fn class_order(a: &TrainerService, b: &TrainerService) -> std::cmp::Ordering {
         .then_with(|| collate(&rank(a), &rank(b)))
 }
 
-/// The within-group comparator for a **tradeskill** trainer (type 2) — the whole of `0x4d8760`'s
-/// row half: required-skill value **ascending** (`0x4d87d9`/`0x4d8801`), then the localized name.
-///
-/// The two keys it pointedly does *not* have are the interesting ones, and both were in benilla's
-/// output until 1124: there is **no `[+0x14]` required-level key** (which is what used to sink the
-/// profession-learn row — the only row with a level — to the bottom of every profession trainer),
-/// and **no `[+0x204]` rank tie-break**.
+/// Rows at a tradeskill trainer (`0x4d8760`): required skill value ascending (`0x4d87d9`), then
+/// name. It has no level key and no rank key.
 fn tradeskill_order(a: &TrainerService, b: &TrainerService) -> std::cmp::Ordering {
     let name = |s: &TrainerService| s.name.clone().unwrap_or_default();
     skill_value(a)
@@ -402,11 +251,8 @@ fn tradeskill_order(a: &TrainerService, b: &TrainerService) -> std::cmp::Orderin
         .then_with(|| collate(&name(a), &name(b)))
 }
 
-/// The within-group comparator for a **mount** trainer (type 1, the client's "talent") — the whole
-/// of `0x4d8850`'s row half: the **state byte** `[+0x30]` ascending (`0x4d88f1`, so available →
-/// unavailable → used), then the localized name. The one comparator on which the green/red/gray is a
-/// sort key rather than only a colour; like the tradeskill one it has no level, skill-value or rank
-/// key.
+/// Rows at a mount trainer (`0x4d8850`): the state byte ascending (`0x4d88f1`: available,
+/// unavailable, used), then name.
 fn talent_order(a: &TrainerService, b: &TrainerService) -> std::cmp::Ordering {
     let name = |s: &TrainerService| s.name.clone().unwrap_or_default();
     a.category
@@ -415,17 +261,9 @@ fn talent_order(a: &TrainerService, b: &TrainerService) -> std::cmp::Ordering {
         .then_with(|| collate(&name(a), &name(b)))
 }
 
-/// Build the display tree from the flat services (decisions 0247/1124), by the trainer type's own
-/// three laws:
-///
-/// * **group** on the app-resolved [`TrainerService::group_key`], dropping the unresolved `0` (which
-///   a type-2 list never produces — its partition is total);
-/// * **order each group's services** with that type's row comparator;
-/// * **order the headers** by raw key ascending at type 2 (`0x4d7c30`: one key, no name, no
-///   tie-break), else by localized name with the key breaking a name tie (`0x4d7b90`).
-///
-/// The service positions index back into the unchanged `services` slice, so every getter still
-/// resolves a row to its full service data.
+/// Group the services by [`TrainerService::group_key`], dropping key 0, and sort each group's rows
+/// by the type's comparator; headers sort by raw key at type 2 (`0x4d7c30`), else by name
+/// (`0x4d7b90`).
 fn build_groups(services: &[TrainerService], trainer_type: u32) -> Vec<TrainerGroup> {
     let mut map: std::collections::HashMap<u32, TrainerGroup> = std::collections::HashMap::new();
     for (i, s) in services.iter().enumerate() {
@@ -454,9 +292,8 @@ fn build_groups(services: &[TrainerService], trainer_type: u32) -> Vec<TrainerGr
     if trainer_type == TRAINER_TYPE_TRADESKILL {
         groups.sort_by_key(|g| g.key);
     } else {
-        // `0x4d7b90`: the `-1` (already-known) group first, then localized name. Its second key —
-        // `hdr[+0x24] == 0` first, between those two — is uncarved and unreachable here: benilla's
-        // headers are one per distinct skill line, so nothing ties on the name that it would break.
+        // `0x4d7b90`: the known group first, then name. Its middle key, `hdr[+0x24] == 0` first, is
+        // untraced and not built.
         groups.sort_by(|a, b| {
             (a.key != TRAINER_GROUP_KNOWN)
                 .cmp(&(b.key != TRAINER_GROUP_KNOWN))
@@ -467,42 +304,12 @@ fn build_groups(services: &[TrainerService], trainer_type: u32) -> Vec<TrainerGr
     groups
 }
 
-/// The client's whole row array, and how much of its front is **on screen** — the visible rows in
-/// display order (decisions 0247/1124), then every hidden one in a **tail** behind them.
-///
-/// **Hiding a row is not removing it**, and that is the shape of the real array rather than a
-/// convenience here. The finalizer `0x4d8410` writes only a per-record visible flag — `[+0x34] = 1`
-/// at `0x4d84c6`, `= 0` at `0x4d8546` — decrements the *visible* count `ds:0xb73a18` (`0x4d8549`),
-/// and then `qsort`s **all `ds:0xb73a10`** records (`0x4d857e`) with that flag as the comparator's
-/// PRIMARY key (`0x4d85ce` … `0x4d8744 setne al` / `0x4d874e lea eax,[eax+eax-1]` → ±1). A hidden
-/// row therefore keeps a record, a position and an index — it is simply parked behind the visible
-/// ones. `GetNumTrainerServices` (`0x4d8d90`) answers with the visible count `ds:0xb73a18`, while
-/// the index space every getter is bounds-checked against is the **total** `ds:0xb73a10`: the
-/// thirteen service getters all route through one shared accessor gate, `0x4d89b0`'s
-/// `cmp ecx, dword ptr [0xb73a10]`, and `GetTrainerServiceInfo` (`0x4d8dc0`) reaches the same gate
-/// through its four siblings (`0x4d8aa2`, `0x4d8b52`, `0x4d8ba2`, `0x4d8c32`). The visible count has
-/// **five references image-wide** — the finalizer seeding and decrementing it, the buy-ALL loop, and
-/// `GetNumTrainerServices` — and **no getter is among them**. So an index past
-/// `GetNumTrainerServices()` is a legal, resolvable, *hidden* row — which is exactly the index the
-/// stock window is handed after a purchase, and reading it as out-of-range is what used to strand
-/// the detail pane ([`selected_row`]). An all-boxes-off window is empty because the Lua stops
-/// iterating, not because the rows stopped existing.
-///
-/// The tail's own ORDER is the comparator's remaining keys in the client and tree order here. It is
-/// unobservable through the stock window — nothing iterates past `GetNumTrainerServices()`, and the
-/// single index that ever reaches in is the selection's, resolved by identity — so the difference
-/// costs nothing until something walks the tail.
-///
-/// **The filter and the collapse are deliberately asymmetric**, and that asymmetry is structural in
-/// the client rather than incidental. The finalizer builds a per-group flag `hdr[+0x1c]` by walking
-/// the group's per-state member counts through the **live** state mask `ds:0xb73a1c` (`0x4d8431`,
-/// `0x4d8447`), and the hide it drives at `0x4d8535` has **no header-row exemption** — so a group
-/// every one of whose rows the dropdown hides disappears entirely, header included, and unchecking
-/// every box empties the window (`GetNumTrainerServices() == 0`). The collapse test three
-/// instructions later (`0x4d8541`) *does* exempt headers (`0x4d853d`) and reads a different field
-/// (`hdr[+0x20]`), so a collapsed group keeps its header — which is what makes it re-expandable.
-/// benilla had both cases keeping the header, with a test asserting it; 1124 inverted the filter
-/// half.
+/// The client's whole row array and its visible count: visible rows in display order, then every
+/// hidden row in a tail. The finalizer `0x4d8410` only clears a hidden record's visible flag
+/// (`0x4d8546`) and sorts it behind (`0x4d857e`), and the getters bound on the total
+/// (`0x4d89b0`, `ds:0xb73a10`), so a hidden row keeps its index. A group the filter empties hides
+/// its header too (`0x4d8535`); a collapsed one keeps it (`0x4d853d`). The tail's order here is
+/// tree order, not the client's; the stock window reaches the tail only by the selection's index.
 fn rows(model: &Model) -> (Vec<Row>, usize) {
     let Some(t) = model.trainer.as_ref() else {
         return (Vec::new(), 0);
@@ -516,7 +323,7 @@ fn rows(model: &Model) -> (Vec<Row>, usize) {
             .copied()
             .partition(|&si| model.trainer_filter[t.services[si].category.filter_slot()]);
         if passes.is_empty() {
-            // The whole group is filtered away — header with it (1124's inverted half).
+            // The filter hid every service, so the header goes too.
             tail.push(Row::Header(gi));
         } else {
             shown.push(Row::Header(gi));
@@ -535,10 +342,8 @@ fn rows(model: &Model) -> (Vec<Row>, usize) {
     (shown, visible)
 }
 
-/// The service at a 1-based visible index, or `None` when that row is a **header** (or OOB / no
-/// trainer) — so the getters/buy that read a service safely no-op on a header row. `pub(super)`:
-/// `GameTooltip:SetTrainerService` lives in the tooltip channel and must resolve its index through
-/// the same VISIBLE mapping, never a raw `services[]` position.
+/// The service at a 1-based row index; `None` for a header. `GameTooltip:SetTrainerService`
+/// resolves its index through this too, never through a raw `services` position.
 pub(super) fn service(model: &Model, index: usize) -> Option<&TrainerService> {
     let n = index.checked_sub(1)?;
     match rows(model).0.get(n)? {
@@ -547,43 +352,16 @@ pub(super) fn service(model: &Model, index: usize) -> Option<&TrainerService> {
     }
 }
 
-/// `GetNumTrainerServices`' answer — the count of rows **on screen** (headers + unfiltered,
-/// uncollapsed services), which is the client's `ds:0xb73a18` and not the length of the row array
-/// the indices run over ([`rows`]).
+/// `GetNumTrainerServices` (`0x4d8d90`): the visible count `ds:0xb73a18`, not the array's length.
 fn num_services(model: &Model) -> usize {
     rows(model).1
 }
 
-/// The selected service's 1-based position in the row array ([`rows`]) — which is **past
-/// `GetNumTrainerServices()` when that service is hidden**, and `None` only when nothing is selected
-/// or the service has left the trainer's list altogether.
-///
-/// **The selection is the service, not the row it happens to sit on.** `SelectTrainerService`
-/// (`0x4d8e60` → `0x4d74f0`) stores the record's **spell id** at `ds:0xb73a0c` — 0 when the index is
-/// out of range, never a clamp — and this getter (`0x4d8f10` → `0x4d7520`) finds it again by linear
-/// scan over the whole array, `cmp dword ptr [edi], esi` at `0x4d7543`, answering `-1` → Lua `0`
-/// only when the scan runs out. Three separate things renumber the rows under a stored number — the
-/// state filter, a collapse, a re-list — so an index stored on Monday is a different service on
-/// Tuesday, and one merely *clamped* to the row count is the worst answer available: plausible, in
-/// range, and wrong. benilla stored the number.
-///
-/// It is load-bearing far beyond bookkeeping, because the stock `Blizzard_TrainerUI.lua` repaints
-/// its detail pane through exactly **one** door. `ClassTrainerTrainButton_OnClick` clears
-/// `ClassTrainerFrame.showSkillDetails`, and `ClassTrainer_SetSelection` early-returns while that is
-/// nil — so on `TRAINER_UPDATE` only the `GetTrainerSelectionIndex() > 1` **else** branch,
-/// `ClassTrainer_SelectFirstLearnableSkill`, puts the flag back and rewrites the name, icon,
-/// `Requires:` line and cost. Answering with a *live, visible* row number for a service that has
-/// left the screen therefore takes the silent branch and leaves the pane describing the spell the
-/// player just learned, under a highlight sitting on the row that slid up into its place — the
-/// director's report.
-///
-/// The reference's own answer there is the hidden row's index, and its consequence is worth stating
-/// because it is what a player sees: `> 1` is true, so the window resets the scroll, calls
-/// `ClassTrainer_SetSelection` on a row nothing displays, and the update loop — which asks only
-/// whether the selection is *on screen* — finds it is not and hides the detail pane. **After you
-/// train a spell the reference blanks the pane and highlights nothing**; it does not advance to the
-/// next spell. Answering `0` instead would select the first learnable and repaint, which is the
-/// fresh-window behaviour, not the post-purchase one.
+/// `GetTrainerSelectionIndex`: the selected service's 1-based row, past the visible count while it
+/// is hidden; `None` when nothing is selected or it left the list. The selection is the record's
+/// spell id (`0x4d8e60` stores it at `ds:0xb73a0c`, `0x4d8f10` scans for it at `0x4d7543`), so no
+/// filter, collapse or update moves it to another service. After a purchase hides the service,
+/// the stock window blanks its detail pane and highlights nothing, as the reference does.
 fn selected_row(model: &Model) -> Option<usize> {
     let want = model.trainer_selection?;
     let t = model.trainer.as_ref()?;
@@ -597,32 +375,10 @@ fn selected_row(model: &Model) -> Option<usize> {
         .checked_add(1)
 }
 
-/// Collapse (`collapse = true`) or expand a skill line by the **display index of its header row**
-/// (decision 0247's `Collapse/ExpandTrainerSkillLine`). `id == 0` targets **all** groups (the
-/// collapse-all button); `id > 0` resolves the header at that index to its skill line. A non-header
-/// (or out-of-range) index is a no-op.
-///
-/// Like every other index in this surface it runs over the whole row array, so a header sitting in
-/// the hidden tail resolves too ([`rows`]). That is the shape of the accessor gate the service
-/// getters were carved to share (`0x4d89b0`, bounded by the total); these two bindings' own gate was
-/// **not** carved, and the difference is unobservable through the stock window, which only ever
-/// passes a visible header's index or `0`.
-/// Queue `TRAINER_UPDATE` — **the repaint the reference fires from the mask-commit thunk itself**,
-/// not from Lua (decision 2244).
-///
-/// `SetTrainerServiceTypeFilter`'s four legs all commit through `0x4d8c90`, whose whole body is
-/// `mov ds:0xb73a1c,ecx; call 0x4d8410; mov ecx,0x136; jmp 0x703e50` — write the mask, re-run the
-/// finalizer, **fire event `0x136` = `TRAINER_UPDATE`**. Its siblings `0x4d8cb0` (the skill-line
-/// mask) and `0x4d8cd0` (the expand mask, which is what Collapse/ExpandTrainerSkillLine commit)
-/// follow `0x4d8c90`'s same shape.
-///
-/// That matters because **nothing in the stock window repaints after a filter click**:
-/// `ClassTrainerFrameFilterDropDown_OnClick` sets the saved global, calls the filter verb, and then
-/// only does `ClassTrainerListScrollFrameScrollBar:SetValue(0)` — a no-op when the bar is already at
-/// zero. The list is repainted by `ClassTrainerFrame_OnEvent`'s `TRAINER_UPDATE` arm, and by nothing
-/// else. While our own `TrainerFrame.xml` ran (before 1957) its click handler repainted explicitly,
-/// which is why this only became visible when the window went stock: the checkboxes moved and the
-/// list underneath did not.
+/// Queue `TRAINER_UPDATE`, which the reference fires from its mask commits, not from Lua:
+/// `0x4d8c90` writes the filter mask, re-runs the finalizer and fires event `0x136`, and the
+/// skill-line and expand-mask commits (`0x4d8cb0`, `0x4d8cd0`, the collapse verbs') do the same.
+/// The stock window's filter click (`Blizzard_TrainerUI.lua:524`) does not repaint.
 fn queue_trainer_update(model: &mut Model) {
     model
         .pending_events
@@ -661,7 +417,6 @@ fn set_collapsed(model: &mut Model, id: usize, collapse: bool) {
     }
 }
 
-/// An optional string as a Lua value (`nil` when absent).
 fn opt_str(lua: &Lua, s: Option<&String>) -> mlua::Result<Value> {
     Ok(match s {
         Some(s) => Value::String(lua.create_string(s)?),
@@ -669,7 +424,7 @@ fn opt_str(lua: &Lua, s: Option<&String>) -> mlua::Result<Value> {
     })
 }
 
-/// A `bool` as the Era `1`/`nil` shape.
+/// A `bool` as the reference's `1` or nil.
 fn era_bool(b: bool) -> Value {
     if b {
         Value::Integer(1)
@@ -682,7 +437,6 @@ fn era_bool(b: bool) -> Value {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // → the number of services the open trainer offers under the current filter (0 when closed).
     g.set(
         "GetNumTrainerServices",
         lua.create_function(|lua, ()| {
@@ -691,9 +445,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerServiceInfo(index) → name, subText, serviceType, isExpanded. `index` 1-based into the
-    // visible tree; out of range → a single nil. A HEADER row returns (skillLineName, nil, "header",
-    // isExpanded); a SERVICE row returns (name, subText, stateString, nil) (decision 0247).
+    // GetTrainerServiceInfo(index) → name, subText, serviceType, isExpanded; one nil past the end.
     g.set(
         "GetTrainerServiceInfo",
         lua.create_function(|lua, index: usize| {
@@ -732,13 +484,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerServiceSkillLine(index) → the skill line the service teaches into, by name — the
-    // group the tree files it under (`TrainerService::group_name`: `SkillLine.dbc`'s name at
-    // trainer types 0/1/3, 1124's builder law). The stock window's one caller is the
-    // CONFIRM_PROFESSION dialog, which formats "learn <profession>?" with it
-    // (Blizzard_TrainerUI.lua l.19-24). A header row or an out-of-range index answers nil. The
-    // binding is registered (`0x4d9160`, 399 bytes) but its return law is not confirmed beyond
-    // "delegates"; this is the call site's reading (1957).
+    // GetTrainerServiceSkillLine(index): the group name, nil for a header. The reference's return
+    // (`0x4d9160`) is untraced; the stock `CONFIRM_PROFESSION` dialog shows it as the profession.
     g.set(
         "GetTrainerServiceSkillLine",
         lua.create_function(|lua, index: usize| {
@@ -759,7 +506,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerServiceIcon(index) → texture path (nil while in flight / OOB).
     g.set(
         "GetTrainerServiceIcon",
         lua.create_function(|lua, index: usize| {
@@ -768,7 +514,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerServiceDescription(index) → the spell description ("" when the app has none / OOB).
     g.set(
         "GetTrainerServiceDescription",
         lua.create_function(|lua, index: usize| {
@@ -780,8 +525,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerServiceCost(index) → money, talentPointCost, professionPointCost. Talent cost is
-    // always 0 (no talent trainer); profession cost is 1 for a primary-profession first rank.
+    // GetTrainerServiceCost(index) → money, talentPointCost, professionPointCost; the talent cost
+    // is always 0, the profession cost 1 for a primary profession's first rank.
     g.set(
         "GetTrainerServiceCost",
         lua.create_function(|lua, index: usize| {
@@ -797,7 +542,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerServiceLevelReq(index) → required character level (0 = none).
     g.set(
         "GetTrainerServiceLevelReq",
         lua.create_function(|lua, index: usize| {
@@ -806,7 +550,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerServiceSkillReq(index) → skillName, skillRank, hasReq (nil when no skill gate / OOB).
     g.set(
         "GetTrainerServiceSkillReq",
         lua.create_function(|lua, index: usize| {
@@ -822,7 +565,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerServiceNumAbilityReq(index) → how many prerequisite abilities the service lists.
     g.set(
         "GetTrainerServiceNumAbilityReq",
         lua.create_function(|lua, index: usize| {
@@ -831,7 +573,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerServiceAbilityReq(index, i) → abilityName, hasReq (nil OOB).
     g.set(
         "GetTrainerServiceAbilityReq",
         lua.create_function(|lua, (index, i): (usize, usize)| {
@@ -848,13 +589,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerServiceStepReq(index) → step, met — always nil (no tradeskill-step data on the wire).
+    // GetTrainerServiceStepReq(index) → step, met: always nil, as the wire carries no step data.
     g.set(
         "GetTrainerServiceStepReq",
         lua.create_function(|_, _index: usize| Ok(Value::Nil))?,
     )?;
 
-    // IsTrainerServiceTradeSkill(index) → 1/nil (a tradeskill step vs. a learn-spell).
     g.set(
         "IsTrainerServiceTradeSkill",
         lua.create_function(|lua, index: usize| {
@@ -865,8 +605,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsTrainerServiceLearnSpell(index) → isLearnSpell, isPetLearnSpell. Pet-learn is always nil
-    // (benilla drives no pet trainer); a non-tradeskill service is a learn-spell.
+    // IsTrainerServiceLearnSpell(index) → isLearnSpell, isPetLearnSpell: any service that is not a
+    // tradeskill is a learn spell; isPetLearnSpell is not built and always answers nil.
     g.set(
         "IsTrainerServiceLearnSpell",
         lua.create_function(|lua, index: usize| {
@@ -876,8 +616,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsTradeskillTrainer() → 1/nil for the whole trainer (drives the tradeskill-vs-class layout):
-    // `0x4d8ea0` tests trainerType == 2.
+    // IsTradeskillTrainer(): trainer type 2 (`0x4d8ea0`).
     g.set(
         "IsTradeskillTrainer",
         lua.create_function(|lua, ()| {
@@ -888,9 +627,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsTalentTrainer() → 1/nil: `0x4d8ed0` tests trainerType == 1 — vmangos's MOUNT trainers, which
-    // the client's own vocabulary calls "talent" (decision 1124). It used to return a hardcoded nil
-    // on the belief that benilla drives no such trainer; the shipped world has 23 of them.
+    // IsTalentTrainer(): trainer type 1 (`0x4d8ed0`), which vmangos gives its mount trainers.
     g.set(
         "IsTalentTrainer",
         lua.create_function(|lua, ()| {
@@ -901,7 +638,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerGreetingText() → the trainer's greeting line ("" when no trainer is open).
     g.set(
         "GetTrainerGreetingText",
         lua.create_function(|lua, ()| {
@@ -915,8 +651,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerServiceTypeFilter(type) → 1/nil (whether that category is shown). SetTrainerService-
-    // TypeFilter(type, on) toggles it — the sort checkboxes' real client-side filtering.
     g.set(
         "GetTrainerServiceTypeFilter",
         lua.create_function(|lua, kind: String| {
@@ -932,19 +666,18 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, (kind, on): (String, Value)| {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
             if let Some(c) = TrainerServiceCategory::from_filter_str(&kind) {
-                // Era passes 1 / 0 (or true/nil); anything truthy-but-not-0 enables.
+                // The stock window passes 1 or 0; nil, false and 0 disable.
                 let enable = !matches!(on, Value::Nil | Value::Integer(0) | Value::Boolean(false));
                 model.trainer_filter[c.filter_slot()] = enable;
-                // …and the repaint, from here rather than from Lua ([`queue_trainer_update`]).
-                // Unconditional, like the thunk: it fires whether or not the bit moved.
+                // Fires even when the bit did not move, as the reference's thunk does.
                 queue_trainer_update(&mut model);
             }
             Ok(())
         })?,
     )?;
 
-    // Collapse/ExpandTrainerSkillLine(id) — fold a skill line by the display index of its header row
-    // (id 0 = all groups, the collapse-all button); a non-header index no-ops (decision 0247).
+    // Collapse/ExpandTrainerSkillLine(id): fold the group headed by row `id`, or all at 0. `id`
+    // spans the whole row array like the getters' gate (`0x4d89b0`); their own bound is untraced.
     g.set(
         "CollapseTrainerSkillLine",
         lua.create_function(|lua, id: usize| {
@@ -964,14 +697,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SelectTrainerService(index) — select the SERVICE at that row, by its spell id. An index out
-    // of range clears the selection (`0x4d74f0`'s `cmp ecx, ds:0xb73a10` / `mov [0xb73a0c], 0` —
-    // cleared, never clamped); [`selected_row`] is why the id and not the row number.
-    //
-    // A HEADER row clears here too, where the reference would store the header record's own id,
-    // `0xffffffff` (`0x4d7b05`), and find the FIRST header again on the way back out — answering 1
-    // rather than 0. The two are the same answer to the only question the stock window asks of this
-    // number (`GetTrainerSelectionIndex() > 1`), and nothing else reads it.
+    // SelectTrainerService(index): select the row's service by spell id; past the end clears it
+    // (`0x4d74f0` stores 0, never a clamp). Deviation: a header clears it too, because it has no
+    // spell id; the reference stores its `0xffffffff` (`0x4d7b05`) and reads back 1, which the
+    // stock window's `> 1` test treats the same as 0.
     g.set(
         "SelectTrainerService",
         lua.create_function(|lua, index: usize| {
@@ -981,9 +710,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerSelectionIndex() → the selected service's current 1-based row — **past
-    // `GetNumTrainerServices()` while that service is hidden**, and 0 only when nothing is selected
-    // or the service has left the list entirely ([`selected_row`] has the law and what rides on it).
     g.set(
         "GetTrainerSelectionIndex",
         lua.create_function(|lua, ()| {
@@ -992,19 +718,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // BuyTrainerService(index) — queue that row's SPELL ID for purchase (the app sends
-    // CMSG_TRAINER_BUY_SPELL). A header row, an out-of-range index, or an ALREADY-KNOWN row is
-    // silently ignored: the single-row path `0x4d89d0` resolves through the same total-bounded
-    // accessor gate as every getter, then refuses on the state byte — `0x4d89e1 cmp esi,ebx; je`
-    // (no record) and `0x4d89e5 cmp byte ptr [esi+0x30], bl; jne` (state != 0, i.e. anything but
-    // `available`), both jumping to the same do-nothing exit.
-    //
-    // Deliberately NOT built: the reference's buy-ALL convenience `0x4d8a70`, the one
-    // visible-count-bounded loop in the whole surface (`0x4d8a71`/`0x4d8a88` read `ds:0xb73a18`).
-    // The split `0x4da244 dec eax; 0x4da245 jns` is SIGNED, so it is every Lua index **<= 0** that
-    // lands there — `BuyTrainerService(0)` buys the player's entire visible list in one call. Here
-    // index 0 is a no-op instead. Nothing in the stock window passes a non-positive index, and a
-    // verb that spends the whole purse on a typo is not one to reproduce on the strength of that.
+    // BuyTrainerService(index): queue the row's spell id. `0x4d89d0` bounds through the getters'
+    // gate and refuses any state byte but 0 (`0x4d89e5`), so only an available service queues.
+    // Deviation: index 0 is a no-op, because one stray call would spend the purse; the reference
+    // buys every visible service for any index at or below 0 (`0x4da244`, `0x4d8a70`).
     g.set(
         "BuyTrainerService",
         lua.create_function(|lua, index: usize| {
@@ -1019,7 +736,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CloseTrainer() — client-side close (no packet, vanilla): flag it so the app clears its state.
+    // CloseTrainer(): sends no packet; the app clears its state on the flag.
     g.set(
         "CloseTrainer",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/trainer/tests.rs b/crates/benilla-ui/src/script/trainer/tests.rs
index b5c58142..def3be58 100644
--- a/crates/benilla-ui/src/script/trainer/tests.rs
+++ b/crates/benilla-ui/src/script/trainer/tests.rs
@@ -1,6 +1,4 @@
-//! The trainer tree's tests — the per-`trainerType` ordering laws (decisions 0247/1124) pinned
-//! against emulated runs of the real finalizer, plus the filter/collapse/intent
-//! surface. Split out of `mod.rs` when the four comparators pushed it past the file budget.
+//! Tests for the trainer tree: the per-type row orders, the filter, the collapse and the intents.
 
 use super::*;
 use crate::script::UiScript;
@@ -14,8 +12,6 @@ fn svc(
 ) -> TrainerService {
     TrainerService {
         spell_id,
-        // The fixture's default subject: the wire spell, no hop (the "no learn wrapper"
-        // fallback); the tooltip tests set the arm they mean explicitly.
         tooltip: TrainerTooltip::Spell {
             spell_id,
             alt_caster: false,
@@ -36,10 +32,8 @@ fn svc(
     }
 }
 
-/// A two-line warrior trainer (type 0). Groups sort by name (Arms < Fury); within Arms, the level
-/// keys order Heroic Strike (level 1) before Cleave (level 20). The default-expanded tree is thus:
-/// `[H:Arms, Heroic Strike(avail), Cleave(used), H:Fury, Bloodrage(unavail)]` — a 5-row list whose
-/// service rows sit at indices 2, 3, 5.
+/// A class trainer whose tree is `[H:Arms, Heroic Strike, Cleave, H:Fury, Bloodrage]`, the three
+/// services available, used and unavailable.
 fn trainer() -> TrainerState {
     let mut hs = svc(
         78,
@@ -66,7 +60,7 @@ fn trainer() -> TrainerState {
     }
 }
 
-/// Every visible row as `(name, serviceType)` — the shape the ported XML actually renders.
+/// Every visible row as `(name, serviceType)`.
 fn visible(s: &mut UiScript) -> Vec<(String, String)> {
     let n = s.eval::<i64>("return GetNumTrainerServices()").unwrap();
     (1..=n)
@@ -88,10 +82,8 @@ fn tree_interleaves_headers_and_ordered_services() {
         .unwrap());
 
     s.set_trainer(Some(trainer()));
-    // 2 headers + 3 services = 5 visible rows.
     assert_eq!(s.eval::<i64>("return GetNumTrainerServices()").unwrap(), 5);
 
-    // Row 1 is the "Arms" header: name, nil subtext, "header", isExpanded=1.
     let (hn, hsub, ht, hexp) = s
         .eval::<(String, Option<String>, String, Option<i64>)>(
             "local n,s,t,e = GetTrainerServiceInfo(1) return n,s,t,e",
@@ -100,7 +92,6 @@ fn tree_interleaves_headers_and_ordered_services() {
     assert_eq!((hn.as_str(), ht.as_str()), ("Arms", "header"));
     assert_eq!((hsub, hexp), (None, Some(1)));
 
-    // Rows 2..5: services (name/state) then the Fury header then its service — the sorted tree.
     let info = |s: &mut UiScript, i: i64| {
         s.eval::<(String, String)>(&format!(
             "local n,_,t = GetTrainerServiceInfo({i}) return n,t"
@@ -120,7 +111,7 @@ fn tree_interleaves_headers_and_ordered_services() {
 fn service_getters_read_the_row_at_a_visible_index() {
     let mut s = UiScript::new().unwrap();
     let mut t = trainer();
-    // Heroic Strike (services[0], the row at index 2) carries a full gate set.
+    // Heroic Strike, row 2, gets a full gate set.
     t.services[0].skill_req = Some(TrainerSkillReq {
         name: "Blacksmithing".into(),
         rank: 100,
@@ -132,7 +123,6 @@ fn service_getters_read_the_row_at_a_visible_index() {
     }];
     s.set_trainer(Some(t));
 
-    // Cost/level/desc/reqs all resolve at the SERVICE index 2 (not the header at 1).
     assert_eq!(
         s.eval::<(i64, i64, i64)>("return GetTrainerServiceCost(2)")
             .unwrap(),
@@ -161,7 +151,7 @@ fn service_getters_read_the_row_at_a_visible_index() {
         .eval::<bool>("local l,p = IsTrainerServiceLearnSpell(2) return l==1 and p==nil")
         .unwrap());
 
-    // A HEADER row (index 1) has no service data — the getters no-op to defaults.
+    // Row 1 is a header, so the getters answer their defaults.
     assert_eq!(
         s.eval::<i64>("return GetTrainerServiceLevelReq(1)")
             .unwrap(),
@@ -175,17 +165,13 @@ fn service_getters_read_the_row_at_a_visible_index() {
         .unwrap());
 }
 
-/// The state filter takes a group's **header with it** once it hides the group's last service — the
-/// finalizer's `[+0x1c]` hide has no header-row exemption (`0x4d8528`/`0x4d8535`, decision 1124).
-/// This asserted the opposite until 1124: benilla rendered bare headers over empty groups, and an
-/// all-boxes-off filter left a window full of headings and nothing else.
+/// The reference's filter hide exempts no header (`0x4d8528`, `0x4d8535`).
 #[test]
 fn state_filter_takes_a_groups_header_with_its_last_service() {
     let mut s = UiScript::new().unwrap();
     s.set_trainer(Some(trainer()));
     assert_eq!(s.eval::<i64>("return GetNumTrainerServices()").unwrap(), 5);
 
-    // Hide "used": Cleave drops (5 → 4), and BOTH headers stay — Arms still has Heroic Strike.
     s.run("SetTrainerServiceTypeFilter('used', 0)").unwrap();
     assert_eq!(
         visible(&mut s)
@@ -195,8 +181,6 @@ fn state_filter_takes_a_groups_header_with_its_last_service() {
         ["header", "available", "header", "unavailable"]
     );
 
-    // Now hide "available" too: Arms loses its last row, so the ARMS HEADER GOES WITH IT — only
-    // Fury's header and its unavailable service remain.
     s.run("SetTrainerServiceTypeFilter('available', 0)")
         .unwrap();
     assert_eq!(
@@ -207,17 +191,12 @@ fn state_filter_takes_a_groups_header_with_its_last_service() {
         ]
     );
 
-    // Every box off renders NOTHING — not a list of bare headings.
     s.run("SetTrainerServiceTypeFilter('unavailable', 0)")
         .unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTrainerServices()").unwrap(), 0);
 
-    // …but the *rows* are still there behind it, and the getters still serve them (2231). This line
-    // asserted `GetTrainerServiceInfo(1) == nil` until the accessor gate was confirmed: the single
-    // one every service getter shares, `0x4d89b0`, bounds against the TOTAL `ds:0xb73a10`, and the
-    // visible count `ds:0xb73a18` has exactly five references image-wide — the finalizer seeding and
-    // decrementing it, the buy-ALL loop, and `GetNumTrainerServices`. No getter reads it. An empty
-    // window is empty because the Lua stops iterating, not because the rows stopped existing.
+    // The rows remain: the getters bound on the total `ds:0xb73a10` (`0x4d89b0`), not the visible
+    // count `ds:0xb73a18`.
     assert_eq!(
         s.eval::<String>("return (GetTrainerServiceInfo(1))")
             .unwrap(),
@@ -231,15 +210,12 @@ fn state_filter_takes_a_groups_header_with_its_last_service() {
     );
 }
 
-/// Collapse is the *asymmetric* case, and deliberately so: it hides a group's services but keeps the
-/// header — a different field (`hdr[+0x20]`) tested three instructions after the filter's, with a
-/// header-row exemption the filter's lacks (`0x4d853d`). Without it a collapsed group could never be
-/// re-expanded, having no header left to click.
+/// The reference's collapse test exempts headers (`0x4d853d`), where the filter's does not.
 #[test]
 fn collapse_keeps_the_header_the_filter_would_remove() {
     let mut s = UiScript::new().unwrap();
     s.set_trainer(Some(trainer()));
-    s.run("CollapseTrainerSkillLine(1)").unwrap(); // fold Arms — both its services hide
+    s.run("CollapseTrainerSkillLine(1)").unwrap(); // fold Arms
     assert_eq!(
         visible(&mut s),
         [
@@ -248,7 +224,6 @@ fn collapse_keeps_the_header_the_filter_would_remove() {
             ("Bloodrage".to_string(), "unavailable".to_string()),
         ]
     );
-    // Collapse-all keeps every header; the filter's empty case keeps none.
     s.run("CollapseTrainerSkillLine(0)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTrainerServices()").unwrap(), 2);
 }
@@ -258,8 +233,6 @@ fn collapse_by_header_index_and_collapse_all() {
     let mut s = UiScript::new().unwrap();
     s.set_trainer(Some(trainer()));
 
-    // Collapse the Arms group by its header's display index (1): its two services vanish, the
-    // header stays and now reports isExpanded=nil. 5 → 3 (H:Arms, H:Fury, Bloodrage).
     s.run("CollapseTrainerSkillLine(1)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTrainerServices()").unwrap(), 3);
     assert!(s
@@ -272,14 +245,11 @@ fn collapse_by_header_index_and_collapse_all() {
         "Arms' services are folded; Fury's header is now row 2"
     );
 
-    // Expand it back by the same header index.
     s.run("ExpandTrainerSkillLine(1)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTrainerServices()").unwrap(), 5);
 
-    // Collapse-all (id 0): both groups fold → just the two headers.
     s.run("CollapseTrainerSkillLine(0)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTrainerServices()").unwrap(), 2);
-    // Expand-all (id 0): back to the full tree.
     s.run("ExpandTrainerSkillLine(0)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTrainerServices()").unwrap(), 5);
 }
@@ -291,7 +261,7 @@ fn collapse_survives_a_content_update_and_resets_on_close() {
     s.run("CollapseTrainerSkillLine(1)").unwrap(); // fold Arms
     assert_eq!(s.eval::<i64>("return GetNumTrainerServices()").unwrap(), 3);
 
-    // A re-list (same skill lines) keeps the fold — a buy re-lists and the tree shouldn't jump open.
+    // A content update over the same groups keeps the fold.
     s.set_trainer(Some(trainer()));
     assert_eq!(
         s.eval::<i64>("return GetNumTrainerServices()").unwrap(),
@@ -299,31 +269,23 @@ fn collapse_survives_a_content_update_and_resets_on_close() {
         "Arms stays collapsed across a content update"
     );
 
-    // Close → the collapse set resets; a re-open is fully expanded.
     s.set_trainer(None);
     s.set_trainer(Some(trainer()));
     assert_eq!(s.eval::<i64>("return GetNumTrainerServices()").unwrap(), 5);
 }
 
-/// A buy queues the row's **spell id**, and only a green row can be bought — the single-row path
-/// `0x4d89d0` resolves the index through the shared total-bounded gate and then refuses on the state
-/// byte (`0x4d89e5 cmp byte ptr [esi+0x30], bl; jne`), so red and gray rows are silently dropped on
-/// the floor rather than sent to the server (2231). This used to queue whatever the index resolved
-/// to, which is how a `used` row could still put a `CMSG_TRAINER_BUY_SPELL` on the wire.
+/// The reference's buy refuses any state byte but 0 (`0x4d89d0`, `0x4d89e5`).
 #[test]
 fn buy_queues_an_available_services_spell_id_and_refuses_every_other_row() {
     let mut s = UiScript::new().unwrap();
     s.set_trainer(Some(trainer()));
-    // Row 2 is Heroic Strike (spell 78, available). Buying it queues its spell id, not its index.
     s.run("BuyTrainerService(2)").unwrap();
     assert_eq!(s.take_trainer_buys(), vec![78]);
     assert!(s.take_trainer_buys().is_empty(), "drained");
 
-    // Buying a HEADER row (index 1) queues nothing.
     s.run("BuyTrainerService(1)").unwrap();
     assert!(s.take_trainer_buys().is_empty(), "a header is not buyable");
 
-    // Nor does a gray row (Cleave, already known) or a red one (Bloodrage, gated).
     s.run("BuyTrainerService(3)").unwrap();
     s.run("BuyTrainerService(5)").unwrap();
     assert!(
@@ -345,7 +307,7 @@ fn selection_and_close_intents() {
         s.eval::<i64>("return GetTrainerSelectionIndex()").unwrap(),
         2
     );
-    s.run("SelectTrainerService(9)").unwrap(); // OOB (past the 5 rows) clears
+    s.run("SelectTrainerService(9)").unwrap(); // past the 5 rows: clears
     assert_eq!(
         s.eval::<i64>("return GetTrainerSelectionIndex()").unwrap(),
         0
@@ -357,9 +319,7 @@ fn selection_and_close_intents() {
     assert!(!s.take_trainer_close(), "drained");
 }
 
-/// The two whole-trainer predicates fork on the wire `trainer_type` — `IsTradeskillTrainer` on
-/// `== 2` (`0x4d8ea0`), `IsTalentTrainer` on `== 1` (`0x4d8ed0`) — so at most one is ever true, and
-/// at a class trainer neither is.
+/// `IsTradeskillTrainer` tests type 2 (`0x4d8ea0`), `IsTalentTrainer` type 1 (`0x4d8ed0`).
 #[test]
 fn tradeskill_and_talent_flags() {
     let mut s = UiScript::new().unwrap();
@@ -367,13 +327,12 @@ fn tradeskill_and_talent_flags() {
         .eval::<bool>("return IsTradeskillTrainer() == nil")
         .unwrap());
 
-    // A class trainer: neither predicate.
     s.set_trainer(Some(trainer()));
     assert!(s
         .eval::<bool>("return IsTradeskillTrainer() == nil and IsTalentTrainer() == nil")
         .unwrap());
 
-    // A tradeskill trainer — one "Recipes" group, so its one service is the row at index 2.
+    // One "Recipes" group, so its service is row 2.
     let mut recipe = svc(
         2743,
         "Copper Chain Pants",
@@ -395,7 +354,6 @@ fn tradeskill_and_talent_flags() {
         .eval::<bool>("return IsTrainerServiceTradeSkill(2) == 1")
         .unwrap());
 
-    // A mount trainer — the "talent" predicate, which used to be a hardcoded nil.
     s.set_trainer(Some(TrainerState {
         greeting: String::new(),
         trainer_type: 1,
@@ -417,7 +375,6 @@ fn tradeskill_and_talent_flags() {
 fn unresolved_skill_line_is_dropped() {
     let mut s = UiScript::new().unwrap();
     let mut t = trainer();
-    // A service whose skill line didn't resolve (0) is dropped from the tree entirely.
     t.services.push(svc(
         999,
         "Orphan Spell",
@@ -426,19 +383,11 @@ fn unresolved_skill_line_is_dropped() {
         "",
     ));
     s.set_trainer(Some(t));
-    // Still 5 rows — the orphan contributes neither a header nor a service row.
     assert_eq!(s.eval::<i64>("return GetNumTrainerServices()").unwrap(), 5);
 }
 
-/// **The selection is the service, never the row it sits on** — and a hidden service keeps a row.
-///
-/// `SelectTrainerService` stores the record's spell id (`ds:0xb73a0c`, `0x4d74f0`) and
-/// `GetTrainerSelectionIndex` finds it again by scanning the **whole** array (`0x4d7520`, bounded by
-/// the total `ds:0xb73a10`, not the visible `ds:0xb73a18`). Filtering and collapsing only clear a
-/// record's visible flag `[+0x34]` and sort it into a tail, so the answer for an off-screen
-/// selection is an index *past* `GetNumTrainerServices()` — never a clamp, and never a live row
-/// number belonging to some other service. benilla stored the row number and clamped it, which is
-/// the director's "the info and img below don't update" report: see [`super::selected_row`].
+/// The reference stores the selection as a spell id (`0x4d74f0`) and scans the whole array for it
+/// (`0x4d7520`), so a hidden selection reads past the visible count.
 #[test]
 fn the_selection_follows_its_service_and_lands_in_the_tail_when_it_is_hidden() {
     let mut s = UiScript::new().unwrap();
@@ -450,13 +399,11 @@ fn the_selection_follows_its_service_and_lands_in_the_tail_when_it_is_hidden() {
             .unwrap()
     };
 
-    // Bloodrage sits at row 5 of `[H:Arms, Heroic Strike, Cleave, H:Fury, Bloodrage]`.
     s.run("SelectTrainerService(5)").unwrap();
     assert_eq!(sel(&mut s), 5);
     assert_eq!(at(&mut s, 5), "Bloodrage");
 
-    // Hide the already-known state: Cleave leaves and everything under it slides up one. The row
-    // number 5 now names nothing on screen; the selection is still Bloodrage, at row 4.
+    // Hiding Cleave moves Bloodrage up to row 4.
     s.run("SetTrainerServiceTypeFilter('used', 0)").unwrap();
     assert_eq!(at(&mut s, 4), "Bloodrage");
     assert_eq!(
@@ -465,9 +412,7 @@ fn the_selection_follows_its_service_and_lands_in_the_tail_when_it_is_hidden() {
         "it followed its service, it did not stay put"
     );
 
-    // Fold Bloodrage's group away. It is off screen but not gone: its record goes to the tail, so
-    // the answer is an index past the visible count — which is what sends the stock window down its
-    // "the selection is not on screen" path instead of silently repainting someone else's row.
+    // Row 3 is now the Fury header.
     s.run("CollapseTrainerSkillLine(3)").unwrap();
     let folded = sel(&mut s);
     assert!(
@@ -478,8 +423,7 @@ fn the_selection_follows_its_service_and_lands_in_the_tail_when_it_is_hidden() {
     s.run("ExpandTrainerSkillLine(3)").unwrap();
     assert_eq!(sel(&mut s), 4, "and back on screen when the group unfolds");
 
-    // He learns it. The re-list brings it back gray and the filter hides it — the tail again, never
-    // the row number of whatever moved up into its place.
+    // Learned, it comes back gray and the filter hides it.
     let mut learned = trainer();
     learned.services[2].category = TrainerServiceCategory::Used;
     s.set_trainer(Some(learned));
@@ -488,23 +432,18 @@ fn the_selection_follows_its_service_and_lands_in_the_tail_when_it_is_hidden() {
         "the learned spell is off screen, not at some live row"
     );
 
-    // A service that has left the trainer's list altogether is the one case that reads 0.
     let mut shorter = trainer();
     shorter.services.remove(2);
     s.set_trainer(Some(shorter));
     assert_eq!(sel(&mut s), 0);
 
-    // A header row is not a selection, and neither is a row past the end.
     s.set_trainer(Some(trainer()));
     s.run("SelectTrainerService(1)").unwrap();
     assert_eq!(sel(&mut s), 0, "row 1 is the Arms header");
 }
 
-/// A new `SMSG_TRAINER_LIST` resets the selection with the rest of the builder's state — `0x4d7560`
-/// selects record 0 after the sort (`0x4d7b40 xor ecx,ecx` → `0x4d7b42 call 0x4d74f0`), which is
-/// always a group header and so reads back as 1. Clearing is the same answer to the only question
-/// the stock window asks (`GetTrainerSelectionIndex() > 1`, which 0 and 1 both fail); what matters
-/// is that a re-opened trainer cannot inherit the last visit's selection.
+/// The reference's list builder re-selects a header (`0x4d7560`, `0x4d7b42`), so a re-opened
+/// trainer never keeps the last visit's selection.
 #[test]
 fn a_new_list_packet_clears_the_selection() {
     let mut s = UiScript::new().unwrap();
@@ -536,23 +475,12 @@ fn clearing_empties_and_resets_selection() {
     );
 }
 
-/// **The tradeskill order, pinned against an emulated run of the real finalizer** (decision
-/// 1124). The fixture is creature 957 "Dane Lindgren" — the blacksmithing trainer in the director's
-/// report — with his 19 real `npc_trainer` rows: 18 recipes on skill line 164 with ascending
-/// `reqSkillValue`, plus the profession-learn service 2020 ("Apprentice Blacksmith", `reqLevel 5`,
-/// no skill gate). This exact set was fed through the builder `0x4d7560` + finalizer `0x4d8410`
-/// with `0xb73a08 = 2` and the real `qsort`/collator, and got the 21 rows asserted below.
-///
-/// Two things this pins that benilla had wrong, and one it never had:
-/// - the learn row is **first among services**, under its own `Development Skills` header — placed
-///   by the `SKILL_STEP` group partition, *not* by any level key;
-/// - `reqLevel` is **inert** at type 2 (the class comparator's first key, which used to sink 2020 to
-///   the bottom of the list);
-/// - recipes ascend by `reqSkillValue`, ties broken by name.
+/// Creature 957's 19 vmangos `npc_trainer` rows, in the order the reference's builder `0x4d7560`
+/// and finalizer `0x4d8410` give them at type 2: the `SKILL_STEP` learn row first under its own
+/// header, `reqLevel` inert, the recipes by `reqSkillValue` then name.
 #[test]
 fn tradeskill_trainer_matches_the_emulated_reference_order() {
-    // (wire spell, name, reqSkillValue) — the recipes, in wire order (ascending here, but the
-    // fixture is shuffled below to prove the order is the comparator's and not the input's).
+    // (wire spell, name, reqSkillValue), reversed below so the order must come from the sort.
     let recipes: &[(u32, &str, u32)] = &[
         (2743, "Copper Chain Pants", 1),
         (2754, "Copper Mace", 15),
@@ -576,7 +504,7 @@ fn tradeskill_trainer_matches_the_emulated_reference_order() {
     let mut services: Vec<TrainerService> = recipes
         .iter()
         .map(|&(id, name, req)| {
-            // Group key 2 = TRADESKILL_SERVICE_LEARN: no SKILL_STEP effect on the wire spell.
+            // Group key 2, `TRADESKILL_SERVICE_LEARN`: the wire spell has no `SKILL_STEP` effect.
             let mut s = svc(id, name, TrainerServiceCategory::Unavailable, 2, "Recipes");
             s.subtext = None;
             s.level_req = 0;
@@ -588,8 +516,8 @@ fn tradeskill_trainer_matches_the_emulated_reference_order() {
             s
         })
         .collect();
-    services.reverse(); // wire order is not display order — and must not be
-                        // Group key 1 = TRADESKILL_SERVICE_STEP: spell 2020 carries Effect 44 SKILL_STEP.
+    services.reverse();
+    // Group key 1, `TRADESKILL_SERVICE_STEP`: spell 2020 has effect 44, `SKILL_STEP`.
     let mut learn = svc(
         2020,
         "Apprentice Blacksmith",
@@ -598,7 +526,7 @@ fn tradeskill_trainer_matches_the_emulated_reference_order() {
         "Development Skills",
     );
     learn.subtext = None;
-    learn.level_req = 5; // the key that used to decide everything, and decides nothing here
+    learn.level_req = 5; // inert at type 2
     learn.prof_first_rank = true;
     services.insert(services.len() / 2, learn);
 
@@ -638,10 +566,7 @@ fn tradeskill_trainer_matches_the_emulated_reference_order() {
     assert_eq!(got, expected);
 }
 
-/// **The mount (type 1, the client's "talent") order, pinned against an emulated run**
-/// (decision 1124): the already-known services fold into the `-1` "My Talents" group, which the
-/// header comparator puts **first**, ahead of the name-ordered skill-line headers; within a group
-/// the state byte sorts available → unavailable → used, then the name.
+/// At a mount trainer the known group's header sorts first (`0x4d7b90`), the rest by name.
 #[test]
 fn mount_trainer_folds_known_services_into_my_talents() {
     let known = |id: u32, name: &str| {
@@ -700,16 +625,13 @@ fn mount_trainer_folds_known_services_into_my_talents() {
         ],
         "the -1 group leads; every other header is name-ordered"
     );
-    // And the type predicates fork on the same dword the sort does.
     assert!(s.eval::<bool>("return IsTalentTrainer() == 1").unwrap());
     assert!(s
         .eval::<bool>("return IsTradeskillTrainer() == nil")
         .unwrap());
 }
 
-/// The **state byte is a sort key at type 1 and only there** — the same three services, ordered by
-/// state (available → unavailable → used) inside one group, where the class cascade would order
-/// them by level and the tradeskill one by skill value.
+/// Only at type 1 is the state byte a sort key (`0x4d8850`).
 #[test]
 fn talent_order_sorts_on_state_within_a_group() {
     let one = |id: u32, name: &str, cat: TrainerServiceCategory| svc(id, name, cat, 762, "Riding");
@@ -728,8 +650,7 @@ fn talent_order_sorts_on_state_within_a_group() {
     let got: Vec<String> = visible(&mut s).into_iter().map(|(n, _)| n).collect();
     assert_eq!(got, ["Riding", "Cee", "Bee", "Aye"]);
 
-    // The same three at a CLASS trainer sort by name instead (equal levels, no skill gates) — the
-    // proof that the comparator really is selected by the type and not shared.
+    // At a class trainer the same three sort by name: equal levels, no skill gates.
     s.set_trainer(Some(TrainerState {
         greeting: String::new(),
         trainer_type: 0,
diff --git a/crates/benilla-ui/src/script/tutorial.rs b/crates/benilla-ui/src/script/tutorial.rs
index d77c1408..d9fb026f 100644
--- a/crates/benilla-ui/src/script/tutorial.rs
+++ b/crates/benilla-ui/src/script/tutorial.rs
@@ -1,33 +1,23 @@
-//! The tutorial system's four Lua verbs (decision 1976): the registrar table at `.data 0x846b04` —
-//! `TutorialsEnabled`, `FlagTutorial`, `ClearTutorials`, `ResetTutorials`.
-//!
-//! The banks are the app's (they are wire state, and the fire-once trigger law lives beside the
-//! sites that trigger): the app pushes the **acknowledged** bank's bytes here when they change,
-//! which is all `TutorialsEnabled` reads, and drains the three writes.
-//!
-//! | verb | shape |
-//! |---|---|
-//! | `TutorialsEnabled()` | one value on both legs: the number `1` if ANY byte of the acknowledged bank is not `0xFF`, else `nil` — over the whole bank, not the 50 real ids; `nil` with no bank |
-//! | `FlagTutorial(n)` | `n` must pass `lua_isnumber` else `Usage: FlagTutorial("tutorial")` (the quoted usage is the reference's own, and misleading — a number is required); truncated, `n − 1` must lie in `0..50` else a SILENT no-op; zero values |
-//! | `ClearTutorials()` | zero values; every bit set in both banks and `CMSG_TUTORIAL_CLEAR` |
-//! | `ResetTutorials()` | zero values; every bit cleared in both banks and `CMSG_TUTORIAL_RESET` |
+//! The four tutorial verbs, registered at `0x846b04`. The banks are the app's: it pushes the
+//! acknowledged bank for `TutorialsEnabled` and drains the writes. `ClearTutorials()` sets every
+//! bit of both banks and sends `CMSG_TUTORIAL_CLEAR`; `ResetTutorials()` clears them and sends
+//! `CMSG_TUTORIAL_RESET`. None of the three writers returns a value.
 
 use mlua::{Lua, Value};
 
 use super::binding_abi::{flag, number_arg};
 use super::Model;
 
-/// `FlagTutorial`'s clamp: `0 ≤ n − 1 < 0x32` — the fifty ids `GlobalStrings.lua` names.
+/// `FlagTutorial`'s bound, `0 ≤ n − 1 < 0x32`: the fifty tutorials `GlobalStrings.lua` names.
 const TUTORIAL_IDS: i32 = 0x32;
 
 impl super::UiScript {
-    /// The acknowledged bank's bytes (`None` before `SMSG_TUTORIAL_FLAGS` lands) — what
-    /// `TutorialsEnabled()` scans.
+    /// The acknowledged bank's bytes, `None` before `SMSG_TUTORIAL_FLAGS`.
     pub fn set_tutorial_bank(&mut self, bank: Option<Vec<u8>>) {
         self.model_mut().tutorial_bank = bank;
     }
 
-    /// `FlagTutorial(n)` calls since the last drain: the **0-based** ids (`n − 1`), in range.
+    /// `FlagTutorial(n)` calls since the last drain, as 0-based ids (`n − 1`).
     pub fn take_tutorial_flag_requests(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().tutorial_flag_requests)
     }
@@ -46,8 +36,8 @@ impl super::UiScript {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // `TutorialsEnabled()` (`0x4b5960`): scans `[0xb711ec] * 4` bytes of bank B for one ≠ 0xFF;
-    // `1.0` or nil, one value; an unallocated bank skips the loop and answers nil.
+    // `TutorialsEnabled()` (`0x4b5960`): 1 if any of the bank's `[0xb711ec] * 4` bytes is not
+    // 0xFF, the whole bank and not just the fifty ids; else nil, as with no bank.
     g.set(
         "TutorialsEnabled",
         lua.create_function(|lua, ()| {
@@ -60,8 +50,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `FlagTutorial(n)` (`0x4b59b0`): `lua_isnumber` else the Usage raise; `__ftol`; `dec`; `js`
-    // and `cmp 0x32 / jge` bail silently; else the acknowledge-and-send setter with the 0-based id.
+    // `FlagTutorial(n)` (`0x4b59b0`): a non-number raises the reference's usage text, which asks
+    // for a string; truncated, an `n − 1` outside `0..0x32` is a silent no-op.
     g.set(
         "FlagTutorial",
         lua.create_function(|lua, n: Value| {
@@ -101,7 +91,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 mod tests {
     use crate::script::UiScript;
 
-    /// `1` or nil, one value, over the WHOLE bank — and nil with none.
     #[test]
     fn tutorials_enabled_scans_the_whole_acknowledged_bank() {
         let mut s = UiScript::new().unwrap();
@@ -127,7 +116,6 @@ mod tests {
         assert_eq!(s.eval::<i64>("return TutorialsEnabled()").unwrap(), 1);
     }
 
-    /// `FlagTutorial`: the number gate's raise, `n − 1`, the silent out-of-range legs, truncation.
     #[test]
     fn flag_tutorial_takes_a_one_based_number_and_bails_silently_off_the_fifty() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/types.rs b/crates/benilla-ui/src/script/types.rs
index 6f42b3ce..8f38b434 100644
--- a/crates/benilla-ui/src/script/types.rs
+++ b/crates/benilla-ui/src/script/types.rs
@@ -3,18 +3,11 @@ use mlua::{Lua, Value};
 use crate::layout::{Anchor, Rect};
 use crate::order::ZTarget;
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Public value + extract types (engine-free seams)
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-
-/// A simple, engine-free value the host can inject into Lua — the seam the app's net/state→event
-/// bridge (decision 0068 §3) uses to hand `fire_event` its `arg1..argN`. Deliberately not
-/// `mlua::Value` so callers never touch mlua handles (the MAXCSTACK discipline reaches the API too).
+/// A value the host passes into Lua, such as a `fire_event` argument, without an mlua handle.
 #[derive(Clone, Debug, PartialEq)]
 pub enum ScriptValue {
     Nil,
     Bool(bool),
-    /// An integer argument (GUIDs-as-strings aside, most event args are ints/strings).
     Int(i64),
     Number(f64),
     Str(String),
@@ -32,27 +25,20 @@ impl ScriptValue {
     }
 }
 
-/// A texture region's UV mapping — the two live `SetTexCoord` forms.
+/// A texture region's UV mapping, one of the two `SetTexCoord` forms.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub enum TexCoords {
-    /// The 4-edge crop `[left, right, top, bottom]` (`SetTexCoord(l,r,t,b)` / XML `<TexCoords>`):
-    /// an axis-aligned UV sub-rect in 0..1 texture space, top-left origin. A mirrored
-    /// (`left > right`) or flipped tuple keeps its orientation.
+    /// `SetTexCoord(l,r,t,b)` or XML `<TexCoords>`, 0..1 from the top left; a mirrored or
+    /// flipped tuple keeps its orientation.
     Rect([f32; 4]),
-    /// The 8-arg affine form (`SetTexCoord(ULx,ULy, LLx,LLy, URx,URy, LRx,LRy)`) — an arbitrary
-    /// UV quad (rotation/shear; the reference's `DrawRouteLine` taxi route lines are the first
-    /// consumer). Stored per corner in **screen order `[TL, TR, BR, BL]`** (the renderer's
-    /// `push_quad` winding — the Lua arg order is converted at the binding).
+    /// `SetTexCoord(ULx,ULy, LLx,LLy, URx,URy, LRx,LRy)`, an arbitrary UV quad, stored in screen
+    /// order `[TL, TR, BR, BL]`: the binding reorders the Lua arguments.
     Corners([[f32; 2]; 4]),
 }
 
 impl TexCoords {
-    /// The tightest axis-aligned `[left, right, top, bottom]` containing the mapping (exact for
-    /// `Rect`, the bounding box for `Corners`).
-    ///
-    /// **Not what `GetTexCoord()` reports** — that answers eight per-corner values, and the 4-value
-    /// rect it used to return is a shape the reference has nowhere (decision 1840). This is the
-    /// renderer's and the app's convenience view, and it keeps its callers.
+    /// The mapping's axis-aligned `[left, right, top, bottom]` bounds; not what `GetTexCoord()`
+    /// answers, which is the eight corner values.
     pub fn edges(&self) -> [f32; 4] {
         match *self {
             TexCoords::Rect(e) => e,
@@ -69,51 +55,25 @@ impl TexCoords {
 /// What an [`ExtractedQuad`] carries to a renderer, beyond its rect.
 #[derive(Clone, Debug, PartialEq)]
 pub enum QuadContent {
-    /// The frame's own draw slot (backdrop/scissor seat) — no region visual of its own in v1.
+    /// The frame's own draw slot, which draws nothing itself.
     Frame,
-    /// A `Minimap` widget's own draw slot: the circular HUD map's content hole. The engine core
-    /// carries the resolved rect + the zoom index; the app renderer draws the world into it —
-    /// the streamed tile window, the mask, and the player arrow (decision 0203). Emitted *at the
-    /// frame's own z*, so the widget's children (border art, buttons) paint above the map exactly
-    /// as the reference layers them.
+    /// A `Minimap` widget's content hole, which the app fills with the map; emitted at the
+    /// frame's own z, so the widget's children (border art, buttons) paint above it.
     Minimap {
-        /// The **outdoor** zoom index, `0..MINIMAP_ZOOM_LEVELS` (0 = widest) — see
-        /// [`crate::widget::MinimapState`].
+        /// The outdoor zoom index, `0..MINIMAP_ZOOM_LEVELS`, 0 the widest.
         zoom: u8,
-        /// The **indoor** zoom index (persisted separately; the client's `0x86f69c`). Both travel
-        /// so the app renderer picks by its own WMO-containment test rather than racing the
-        /// `inside` flag it pushed down.
+        /// The indoor zoom index (`0x86f69c`), sent too so the renderer picks by its own test.
         inside_zoom: u8,
     },
-    /// A `Model` / `PlayerModel` widget's own draw slot: the 3D pane's content hole. The engine
-    /// core carries the resolved rect and the pane's identity; the app renderer puts pixels in it
-    /// — the same division of labour [`QuadContent::Minimap`] uses, and for the same reason (the
-    /// scene state is [`crate::widget::ModelState`]; the render is not this crate's).
-    ///
-    /// **The clock is deliberately NOT here.** A pane's play head moves every tick, and the
-    /// host memoizes its whole quad conversion on the extracted list being unchanged — a
-    /// cursor in this variant would re-convert the entire interface every frame a cooldown or a
-    /// ping is showing. The host reads the play heads straight off the engine instead
-    /// (`UiScript::visible_model_panes`, decision 2008); this variant carries only what the
-    /// layout and the Lua setters decide.
-    ///
-    /// **Why the NAME travels rather than the scene.** benilla draws a body pane by sampling an
-    /// off-screen bake the app already keeps per *window* (the paper doll's, the inspect window's,
-    /// the pet page's), and which bake a pane samples is a fact about that window, not about the
-    /// widget. So the seam carries what the app needs to make the join — the pane's global frame
-    /// name, which since decision 1751 is the reference's own — and nothing it would have to
-    /// invent a meaning for. A pane with no name, or one no window has claimed, draws nothing;
-    /// that is also what a `SetModel` pane does today, and it is honest rather than a white slab.
+    /// A `Model` or `PlayerModel` widget's 3D pane: a `model` file draws as a tile, a unit pane
+    /// samples the bake of the window its name belongs to, or nothing. The host memoizes on this
+    /// list, so it reads the moving play head from `UiScript::visible_model_panes` instead.
     ModelPane {
-        /// The pane's frame handle — the renderer's key for the tile it keeps per pane (a name
-        /// is optional and shared by nothing; the handle is neither). Decision 2007.
+        /// The renderer's key for the tile it keeps per pane.
         handle: crate::widget::FrameHandle,
-        /// The pane's global frame name (`$parent`-expanded), or `None` for an anonymous
-        /// `CreateFrame("Model")` — pfUI's autocast shine is the corpus example of the latter.
+        /// The global frame name; `None` for an anonymous `CreateFrame("Model")`.
         name: Option<String>,
-        /// The `SetModel` path the pane holds (`None` for a unit pane or an empty one) — what the
-        /// host's tile renderer draws (decision 2013), the map arrow's `crate::script::ARROW_MODEL`
-        /// among them since 2015.
+        /// The `SetModel` file; `None` for a unit pane or an empty one.
         model: Option<String>,
         /// `SetFacing`'s radians (0 default).
         facing: f32,
@@ -122,157 +82,91 @@ pub enum QuadContent {
         /// `SetPosition`'s offset, in the ortho leg's layout units (`0x76d1a0`: the root is
         /// `T(pos · layoutScale) · R(facing) · S(…)`).
         position: (f32, f32, f32),
-        /// The frame's **own** alpha — what the model instance draws at. The reference re-pushes
-        /// `[widget+0xc8]/255` into the instance on every `Frame:SetAlpha` (`0x76d120`), and
-        /// nothing folds the parent chain in: a pane under a faded parent draws at its own
-        /// alpha. [`ExtractedQuad::alpha`] carries the effective one.
+        /// The frame's own alpha, which the model draws at: `Frame:SetAlpha` pushes it into the
+        /// instance without the parent chain (`0x76d120`).
         own_alpha: f32,
-        /// `ReplaceIconTexture`'s path — the type-14 texture override, or `None` for the file's
-        /// own textures.
+        /// `ReplaceIconTexture`'s path, the type-14 texture override.
         icon: Option<String>,
-        /// The installed camera as a RAW index into the file's camera table, or `None` for the
-        /// NULL camera. **This is the render leg** (decision 2027): `None` is the orthographic
-        /// one — the model laid flat over the pane's rect — and `Some(n)` the perspective one,
-        /// framed by the file's own record `n`.
+        /// The camera, a raw index into the file's camera table: `None` renders orthographic, the
+        /// model laid flat over the rect, and `Some(n)` in perspective through camera `n`.
         camera: Option<u32>,
-        /// The pane's embedded `CGLight`. Disabled on every shipped pane, which is why an
-        /// unlit-on-every-material UI M2 never notices; a LIT batch under a disabled light draws
-        /// black, and that is the reference's answer, not a gap.
+        /// The embedded `CGLight`, off on every shipped pane; a lit batch under it draws black, as
+        /// in the reference.
         light: crate::widget::ModelLight,
-        /// The pane's fog, only when armed — colour, near and far as the fill callback stages
-        /// them. Per-batch from there: a material with the UNFOGGED bit ignores it.
+        /// The fog, when armed; a material with the UNFOGGED bit ignores it.
         fog: Option<crate::widget::ModelFog>,
     },
-    /// A `Texture` region: a BLP path *or* a solid/vertex color (or both — a tinted texture).
+    /// A `Texture` region: a BLP path, a solid or vertex colour, or both (a tinted texture).
     Texture {
         path: Option<String>,
         color: Option<[f32; 4]>,
-        /// WoW `ADD` blend (highlights/glows) instead of straight alpha.
+        /// The `ADD` blend instead of straight alpha.
         additive: bool,
-        /// The `<TexCoords>`/`SetTexCoord` UV mapping the region samples — the 4-edge crop or the
-        /// 8-arg affine quad ([`TexCoords`]). `None` = the full texture (0,1,0,1). The renderer
-        /// crops (or reprojects) the quad's UVs to this.
+        /// `None` is the full texture.
         tex_coords: Option<TexCoords>,
-        /// Draw masked to the inscribed circle — a **portrait** (`SetPortraitToTexture`, and
-        /// `SetPortraitTexture`'s round unit-portrait binding). The renderer bakes the circular
-        /// alpha so the square icon/model doesn't poke past the frame ring. A `portrait_unit`
-        /// binding with this **false** is the square booth pane (`BenillaSetBoothTexture` —
-        /// the paper doll's model view, decision 0208 §5).
+        /// A portrait, masked to the inscribed circle; false with a `portrait_unit` is the square
+        /// booth pane (`BenillaSetBoothTexture`).
         circular: bool,
-        /// A **live unit portrait** (`SetPortraitTexture(region, unit)` round;
-        /// `BenillaSetBoothTexture(region, token)` square — `circular` above distinguishes): the
-        /// unit token whose model this region renders. When `Some`, the renderer ignores
-        /// `path`/`color` and samples the app-side portrait render-target for this token (the
-        /// off-screen model bake). `None` = an ordinary texture/color region. The engine-free core
-        /// only carries the token; resolving it to a rendered image is the app's job (the modern
-        /// 2D portrait is a high-res model bake).
+        /// A live unit portrait's unit: the renderer samples the app's bake of it instead of
+        /// `path` and `color`.
         portrait_unit: Option<String>,
-        /// On-screen rotation about the quad center, radians, **counterclockwise-positive**.
-        ///
-        /// **Always `0.0` now — nothing writes it any more.** It carried a later-era
-        /// `Texture:SetRotation` benilla shipped early so the world-map player arrow could spin,
-        /// standing in for the reference's engine arrow model (0203 flags the stand-in). That arrow
-        /// became a real Model frame driven by `ModelState::facing` (`script::worldmap_arrow`), and
-        /// the verb has since come off the Texture map — 1.12 registers `SetRotation` on PlayerModel
-        /// alone (`0x84f1fc`). The plumbing is left standing rather than pruned in the same change,
-        /// because it runs into the app's quad emit; see [`RegionData::rotation`].
+        /// Rotation about the centre, radians counterclockwise; always 0, since 1.12 registers
+        /// `SetRotation` on PlayerModel alone (`0x84f1fc`).
         rotation: f32,
-        /// `Texture:SetDesaturated(1)` — draw the sampled texel as its **luminance** instead of
-        /// its colour (decision 1327). The renderer greys the texel and *then* modulates by
-        /// `color`, because the reference's own consumers pass a dim tint alongside the flag
-        /// (`SetItemButtonDesaturated(button, 1, 0.65, 0.65, 0.65)`) and expect both to land.
+        /// `SetDesaturated`: the texel draws as its luminance, then is tinted by `color`, since
+        /// `SetItemButtonDesaturated` passes a dim tint with the flag.
         desaturated: bool,
     },
-    /// A `ColorSelect`'s **hue disc** — its `<ColorWheelTexture>` region. That element carries no
-    /// `file=` in the reference either: the wheel is generated by the client, not loaded, and there
-    /// is no BLP anywhere in the MPQ chain that is a colour wheel. So the engine core hands the
-    /// renderer the rect and the widget's HSV and the app makes the pixels — the same division the
-    /// [`QuadContent::Minimap`] slot uses, for the same reason.
-    ///
-    /// The disc it must draw is fixed by the *pick* law it has to invert (`0x78bd80`): at
-    /// normalised offset `(nx, ny)` from the rect's centre the
-    /// pixel is `HSV(atan2(ny, nx)·180/π + 180, min(|n|, 1), …)`, so clicking a pixel selects the
-    /// colour that pixel shows.
-    ///
-    /// **It carries no colour**, and that is the byte law rather than an omission: the fill loop
-    /// draws every texel at a literal `V = 1.0` (`0x78b68b`) and never reads the widget's own
-    /// value, so the disc is the same image at every colour. Handing the renderer an HSV it must
-    /// ignore would also churn this quad on every step of a drag, for no pixel.
+    /// A `ColorSelect`'s `<ColorWheelTexture>` disc, generated: the pixel at normalised offset
+    /// `(nx, ny)` from the centre is `HSV(atan2(ny, nx)·180/π + 180, min(|n|, 1), 1)`, inverting
+    /// the pick law (`0x78bd80`); the fill draws every texel at `V = 1` (`0x78b68b`), so no colour
+    /// travels.
     ColorWheel,
-    /// A `ColorSelect`'s **brightness strip** — its `<ColorValueTexture>` region, the wheel's
-    /// file-less twin. A vertical ramp of the currently selected hue and saturation, black at the
-    /// bottom, which is the inverse of the strip's own pick law
-    /// (`V = clamp((y − bottom)/(top − bottom), 0, 1)`).
+    /// A `ColorSelect`'s `<ColorValueTexture>` strip: the hue and saturation, black at the
+    /// bottom, the inverse of its pick law `V = clamp((y − bottom)/(top − bottom), 0, 1)`.
     ColorValue {
-        /// The widget's hue, degrees.
+        /// Degrees.
         hue: f32,
-        /// The widget's saturation, `0..=1`. Together these are the whole strip: its top is
-        /// `HSV(hue, sat, 1)` and its bottom is black, so the widget's **value** moves no pixel of
-        /// it (only its marker).
+        /// `0..=1`; the widget's value moves only its marker, never the strip.
         sat: f32,
     },
-    /// One frame `Backdrop` piece (the tiled bg, or one of the 8 border pieces) — emitted at the
-    /// owning frame's own draw slot, behind its regions ([`UiScript::extract`](super::UiScript::extract)). A textured quad
-    /// whose UVs are four explicit per-corner pairs (`[TL, TR, BR, BL]`, screen order) because the
-    /// TOP/BOTTOM edges are rotated 90°, and whose texture needs REPEAT addressing (edges tile).
-    /// The [`ExtractedQuad::rect`] is the piece's screen bounding box.
+    /// One `Backdrop` piece, the tiled background or one of the 8 border pieces, drawn in the
+    /// frame's slot behind its regions; per-corner UVs, since the top and bottom edges turn 90°.
     Backdrop {
-        /// The bg or edge texture path.
         path: String,
-        /// The bg (`SetBackdropColor`) or border (`SetBackdropBorderColor`) vertex tint, pre-alpha.
+        /// The `SetBackdropColor` or `SetBackdropBorderColor` tint, pre-alpha.
         color: [f32; 4],
-        /// Four per-corner UVs, `[TL, TR, BR, BL]` (screen order).
+        /// `[TL, TR, BR, BL]`, screen order.
         uvs: [[f32; 2]; 4],
-        /// Sample the texture with REPEAT (wrap) addressing.
+        /// Sample with repeat (wrap) addressing.
         tile: bool,
     },
-    /// A `FontString` region: its text, color, horizontal justification, and the resolved font
-    /// (path + height + shadow) from its font object / `SetFont` — rendering/metrics are the Bevy
-    /// side's job (it honors [`QuadContent::Text::justify_h`], picks the face by `font`, bakes at
-    /// `height`, and draws [`QuadContent::Text::shadow`] as an offset dark pass behind the glyphs).
+    /// A `FontString` region with its resolved font; the app measures and draws it.
     Text {
         text: Option<String>,
         color: Option<[f32; 4]>,
         justify_h: JustifyH,
         justify_v: JustifyV,
-        /// The resolved font face path (`SetFontObject`/`SetFont`/XML `inherits=`), e.g.
-        /// `"Fonts\\FRIZQT__.TTF"`. `None` ⇒ the renderer's default face (Friz Quadrata).
+        /// The face path, e.g. `"Fonts\\FRIZQT__.TTF"`; `None` is Friz Quadrata.
         font: Option<String>,
-        /// The resolved font height in logical px. `None` ⇒ the renderer's default size.
+        /// Logical px; `None` is the renderer's default size.
         font_height: Option<f32>,
-        /// The `SetTextHeight` override (see [`RegionData::text_height`]): `Some` = the
-        /// scaled-string regime — draw at THIS height, uncapped (the one-to-one 32-px raster cap
-        /// applies only when this is `None`).
+        /// The `SetTextHeight` override, drawn uncapped; `None` keeps the 32 px raster cap.
         text_height: Option<f32>,
-        /// The resolved drop shadow (font object `<Shadow>` — offset + color). The real 1.12
-        /// `MasterFont` root carries `(1,-1)` black, so nearly every stock font is shadowed; the
-        /// crispness of client text against parchment/world IS this shadow.
+        /// 1.12's `MasterFont` sets `(1,-1)` black, so nearly every stock font has one.
         shadow: Option<FontShadow>,
-        /// The resolved glyph outline (`outline="NORMAL"/"THICK"`). The Number* fonts (action-bar
-        /// hotkeys/counts) carry it; the renderer draws it as a black offset halo under the fill —
-        /// `cosmic-text` has no native outline. `None` for the common un-outlined case.
         outline: Outline,
-        /// The write-on reveal (`SetAlphaGradient` — see [`RegionData::alpha_gradient`]): the
-        /// renderer multiplies each glyph's alpha by the ramp at its character position (before
-        /// `start` opaque, the next `length` chars 1→0, beyond invisible). `None` = draw whole.
+        /// `SetAlphaGradient`: before `start` opaque, the next `length` characters fading from 1
+        /// to 0, the rest invisible.
         alpha_gradient: Option<(f32, f32)>,
-        /// **Seat this block exactly where `rect` puts it**, skipping the UI grid's vertical
-        /// block-top snap — true for a FontString owned by a V-plate, false for every other one
-        /// (`super::nameplate::is_world_seated`, decision 2172).
-        ///
-        /// Not a client concept: in the reference the whole interface *is* the pixel grid, so the
-        /// snap and the rect agree by construction. benilla has one family of frames that lives
-        /// outside it — the WorldFrame overlays that slide continuously over the 3-D scene, whose
-        /// seat law is a DEVICE-pixel snap (`vplates::device_snap`, 0188/1398) rather than the
-        /// UI's logical-pixel one. Snapping their text on the coarser UI grid makes it *beat*
-        /// against the art it is supposed to be rigid to: two quantizers on one sliding object.
+        /// Seat the text at `rect` without the UI grid's block-top snap: true on a nameplate
+        /// (`super::nameplate::is_world_seated`), which slides on a device-pixel snap, so a second
+        /// snap would jitter its text. Not a reference field.
         world_seat: bool,
     },
 }
 
-/// A `FontString`'s horizontal text justification within its resolved rect — the XML `justifyH`
-/// attr (`SetJustifyH`). The FrameXML default is **CENTER** (the client's `JustifyH` field default);
-/// the app's text renderer positions each line's run against the rect per this.
+/// A `FontString`'s horizontal justification (`justifyH`, `SetJustifyH`); CENTER by default.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub enum JustifyH {
     Left,
@@ -281,12 +175,8 @@ pub enum JustifyH {
     Right,
 }
 
-/// A `FontString`'s vertical text justification within its resolved rect — the XML `justifyV`
-/// attr (`SetJustifyV`). The FrameXML default is **MIDDLE** (the client's `JustifyV` field
-/// default) — a sized FontString centers its line block vertically, which is why the real
-/// client's 13px money numbers sit on their coin icons' centerline. The app's text renderer
-/// offsets the line block against the rect per this (no-op for a rect sized to its text, i.e.
-/// every host-measured height-less FontString).
+/// A `FontString`'s vertical justification (`justifyV`, `SetJustifyV`); MIDDLE by default, so a
+/// sized FontString centres its lines.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub enum JustifyV {
     Top,
@@ -295,43 +185,26 @@ pub enum JustifyV {
     Bottom,
 }
 
-/// A Texture's blend mode — the client's shared `alphaMode` enum, the `{value, name}` table at
-/// `0x811aa8`: `DISABLE=0 · ALPHAKEY=1 · BLEND=2 · ADD=3 · MOD=4`. It is one enum reached two
-/// ways — the XML `alphaMode=` attribute and `Texture:SetBlendMode` — and read back by
-/// `Texture:GetBlendMode`.
-///
-/// **`Blend` is the default because the CSimpleTexture ctor writes it**: `0x76fc64 mov
-/// [esi+0xd0],2`, which `ActionButtonTemplate.xml`'s `<NormalTexture>` keeps by declaring no
-/// `alphaMode` (`0x76fb82` gates on the value for a different question, and it is therefore
-/// evidence rather than assertion — mode 1
-/// would alpha-test a half-alpha vertex colour away entirely, mode 2 ghosts it). It is the answer
-/// every ordinary texture gives `ShaguTweaks/mods/dark-ui-elements.lua:169`'s
-/// `region:GetBlendMode() == "ADD"` guard, so getting it wrong is the same recolouring bug one
-/// branch over.
-///
-/// **Only ADD changes what this engine draws.** The renderer takes the ADD/not-ADD bit
-/// ([`QuadContent::Texture::additive`]); `DISABLE`, `ALPHAKEY` and `MOD` are carried faithfully
-/// through the setter and the getter and drawn as straight alpha — the stated v1 gap, unchanged by
-/// storing the whole mode instead of a bool.
+/// A Texture's blend mode, the client's `alphaMode` enum (`0x811aa8`), set by XML `alphaMode=`
+/// or `SetBlendMode`; BLEND is the constructor's (`0x76fc64 mov [esi+0xd0],2`). The renderer
+/// acts only on ADD: the others draw as straight alpha, their reference blending not built.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub enum BlendMode {
-    /// `DISABLE` = 0 — `GL_ONE, GL_ZERO`, alpha reference 0. Drawn as straight alpha here.
+    /// `DISABLE` (0): `GL_ONE, GL_ZERO`, alpha reference 0.
     Disable,
-    /// `ALPHAKEY` = 1 — `GL_ONE, GL_ZERO` with alpha reference 224/255. Drawn as straight alpha here.
+    /// `ALPHAKEY` (1): `GL_ONE, GL_ZERO`, alpha reference 224/255.
     AlphaKey,
-    /// `BLEND` = 2 — `GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA`. The ctor's value, hence the default.
+    /// `BLEND` (2): `GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA`.
     #[default]
     Blend,
-    /// `ADD` = 3 — `GL_SRC_ALPHA, GL_ONE`. The one mode the renderer acts on.
+    /// `ADD` (3): `GL_SRC_ALPHA, GL_ONE`.
     Add,
-    /// `MOD` = 4 — `GL_DST_COLOR, GL_ZERO`. Drawn as straight alpha here.
+    /// `MOD` (4): `GL_DST_COLOR, GL_ZERO`.
     Mod,
 }
 
 impl BlendMode {
-    /// Parse the enum's own spelling, as `SetBlendMode` and the XML `alphaMode=` attribute take it.
-    /// Case-insensitive (the Lua binding coerces through the shared string-arg law); `None` for a
-    /// name outside the table's five.
+    /// Parse the name, case-insensitively, as `SetBlendMode` and XML `alphaMode=` take it.
     pub fn parse(s: &str) -> Option<BlendMode> {
         match s.to_ascii_uppercase().as_str() {
             "DISABLE" => Some(BlendMode::Disable),
@@ -343,7 +216,7 @@ impl BlendMode {
         }
     }
 
-    /// The reference's own spelling, as `GetBlendMode()` answers it (the name column of `0x811aa8`).
+    /// The name `GetBlendMode()` answers (the name column of `0x811aa8`).
     pub const fn name(self) -> &'static str {
         match self {
             BlendMode::Disable => "DISABLE",
@@ -355,10 +228,7 @@ impl BlendMode {
     }
 }
 
-/// A `FontString`'s glyph outline (the XML `outline`/`<Font outline=>` attr, OUTLINETYPE): `NONE`
-/// (the common case), `NORMAL`, or `THICK`. Resolved through the font registry and readable via
-/// `GetFont`; the v1 text renderer does **not** yet rasterize outlines (a documented gap — the atlas
-/// bakes plain coverage), so this is carried for fidelity/round-tripping, not drawn.
+/// A `FontString`'s glyph outline (XML `outline=`, OUTLINETYPE), answered by `GetFont`.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub enum Outline {
     #[default]
@@ -368,8 +238,8 @@ pub enum Outline {
 }
 
 impl Outline {
-    /// Parse the **XML** OUTLINETYPE attribute (`outline="NONE"/"NORMAL"/"THICK"`,
-    /// case-insensitive); unknown ⇒ `None`. This is *not* the Lua spelling — see [`Outline::flags`].
+    /// Parse the XML `outline=` attribute, case-insensitively; not the Lua spelling, which is
+    /// [`Outline::flags`].
     pub fn parse(s: &str) -> Outline {
         match s.to_ascii_uppercase().as_str() {
             "NORMAL" => Outline::Normal,
@@ -378,22 +248,9 @@ impl Outline {
         }
     }
 
-    /// Parse a **Lua `SetFont` flags string** — a different vocabulary from the XML attribute
-    /// above, and mixing the two is a silent no-op: `SetFont(path, h, "OUTLINE")` through
-    /// [`Outline::parse`] matches nothing and lands on `NONE`.
-    ///
-    /// The reference reads the argument as a *set* of substrings against
-    /// `{0x1 OUTLINE, 0x4 THICKOUTLINE, 0x2 MONOCHROME}` (`0x811b10`), which is why this is
-    /// `contains` and not
-    /// equality — `"OUTLINE, MONOCHROME"` is a real thing addons write. MONOCHROME has no field
-    /// here (we model no glyph AA mode) and is ignored; `THICK` is checked first because
-    /// `"THICKOUTLINE"` contains `"OUTLINE"`.
-    ///
-    /// One function, three callers: `Button:SetFont`, `FontString:SetFont` and `Font:SetFont` all
-    /// delegate to the *same* impl in the reference (`0x79f210`), so they cannot be allowed to
-    /// disagree here. They did: the Font-object binding parsed its Lua flags with the XML reader,
-    /// so `GameFontNormal:SetFont(f, h, "OUTLINE")` silently cleared the outline instead of setting
-    /// it, while the FontString binding carried its own inline copy of this match.
+    /// Parse a Lua `SetFont` flags string, shared by every `SetFont` (`0x79f210`) and matched by
+    /// substring against `{0x1 OUTLINE, 0x4 THICKOUTLINE, 0x2 MONOCHROME}` (`0x811b10`): THICK
+    /// first, since `THICKOUTLINE` contains `OUTLINE`. MONOCHROME is ignored, its mode not built.
     pub fn flags(s: &str) -> Outline {
         let s = s.to_ascii_uppercase();
         if s.contains("THICK") {
@@ -405,7 +262,7 @@ impl Outline {
         }
     }
 
-    /// The OUTLINETYPE token (for `GetFont`'s flags return).
+    /// The flags token `GetFont` answers.
     pub fn as_str(self) -> &'static str {
         match self {
             Outline::None => "",
@@ -415,89 +272,63 @@ impl Outline {
     }
 }
 
-/// A font object's drop shadow (`<Shadow><Offset/><Color/></Shadow>`): pixel offset in WoW y-up
-/// XML convention (`y="-1"` = 1px down) + color. Inherited down `<Font>` chains like every other
-/// paint field (the 1.12 `MasterFont` root sets `(1,-1)` black — ref-Fonts.xml l.55-62).
+/// A font object's `<Shadow>`, inherited down `<Font>` chains; 1.12's `MasterFont` sets `(1,-1)`
+/// black (`Fonts.xml:55`).
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct FontShadow {
-    /// XML `<Offset><AbsDimension x= y=/>` — WoW y-up (negative y = down-screen).
+    /// Pixels, y up: `y="-1"` is 1 px down.
     pub offset: [f32; 2],
-    /// `<Color r= g= b= a=/>`; alpha defaults 1.
+    /// Alpha defaults to 1.
     pub color: [f32; 4],
 }
 
-/// A named virtual **Font object** (`<Font name=… font=… inherits=…>`): the resolved paint a
-/// `FontString` picks up by `inherits=`/`SetFontObject`. Values are already flattened through the
-/// `<Font>` inherits chain (rooted at a real TTF path); any field the chain never set is `None`
-/// (the renderer falls back). This is the registry entry [`Model::font_objects`](super::Model::font_objects) keys by name.
+/// A named `<Font>` object's paint, flattened through its `inherits=` chain; a field the chain
+/// never sets is `None`.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct FontObject {
-    /// The TTF path (`font="Fonts\\FRIZQT__.TTF"`), inherited down the chain.
+    /// The TTF path (`font=`).
     pub font: Option<String>,
-    /// The font height in logical px (`<FontHeight><AbsValue val=/>`).
+    /// Logical px (`<FontHeight>`).
     pub height: Option<f32>,
-    /// The drop shadow (`<Shadow>`), inherited down the chain like the rest of the paint.
     pub shadow: Option<FontShadow>,
-    /// The text color (`<Color r= g= b= a=/>`).
     pub color: Option<[f32; 4]>,
-    /// The glyph outline (`outline=` attr).
     pub outline: Outline,
-    /// The default horizontal justification (`justifyH=` attr), if the object sets one.
     pub justify_h: Option<JustifyH>,
-    /// The default vertical justification (`justifyV=` attr), if the object sets one.
     pub justify_v: Option<JustifyV>,
 }
 
-/// One entry of the render list [`UiScript::extract`](super::UiScript::extract) produces: a draw target in the client's exact
-/// painter order (the [`crate::order::traversal`] `ZKey` order), its resolved screen rect (if the
-/// layout pass resolved it), the effective alpha to draw at, and its content. This is the seam the
-/// Bevy extractor consumes; it names only this crate's own types (handles, [`Rect`]) — no engine.
+/// One entry of [`UiScript::extract`](super::UiScript::extract)'s render list, in the client's
+/// painter order ([`crate::order::traversal`]).
 #[derive(Clone, Debug, PartialEq)]
 pub struct ExtractedQuad {
-    /// The draw target (a frame's own slot, or one of its regions).
+    /// A frame's own slot, or one of its regions.
     pub target: ZTarget,
-    /// The packed draw-order key (`ZKey::raw`); entries are already sorted ascending by it.
+    /// The packed draw-order key (`ZKey::raw`); entries are sorted ascending by it.
     pub z: u64,
-    /// The resolved rect (`[bottom, left, top, right]`, screen px, y-up). `None` if the owning frame
-    /// is under-constrained (no resolvable anchors) — a renderer skips it. A region's rect is its
-    /// own owner-relative resolution when it carries anchors, else centered-on / filling its owner
-    /// (see [`UiScript::extract`](super::UiScript::extract)).
+    /// `None` when the owning frame's anchors do not resolve; a renderer skips it.
     pub rect: Option<Rect>,
-    /// The effective alpha to draw at: for a frame slot its own `effective_alpha`; for a region the
-    /// verified single-hop product `region.alpha × ownerFrame.effective_alpha` (see
-    /// [`RegionData::alpha`]).
+    /// A frame's `effective_alpha`, or a region's alpha times its owner's, one hop only.
     pub alpha: f32,
-    /// The renderable content.
     pub content: QuadContent,
-    /// The ScrollFrame clip this quad draws within (decision 0112): `Some(rect)` when the owning
-    /// frame is a ScrollFrame's scroll child, or any descendant of one — nested ScrollFrames
-    /// intersect (see [`UiScript::extract`](super::UiScript::extract)'s `effective_clip`). `None` = unclipped, the common case.
+    /// The ScrollFrame clip of a scroll child and its descendants, nested ones intersecting.
     pub clip: Option<Rect>,
-    /// The owning frame's `effective_scale` (`0x76ac90`: `parentScale · ownScale`). The
-    /// `rect` above already carries it — the layout solver multiplies every placement by the
-    /// owner's scale — but glyph METRICS don't live in the rect: the renderer must rasterize a
-    /// `Text` quad's font at `font_height × scale` (and scale the shadow offset with it) or a
-    /// `SetScale`'d window draws scaled boxes full of unscaled text, the exact divergence
-    /// decision 0219 §2 recorded. 1.0 for the unscaled common case.
+    /// The owner's `effective_scale` (`0x76ac90`), already in `rect`; a `Text` quad's font and
+    /// shadow offset must be scaled by it too.
     pub scale: f32,
 }
 
-/// The visual state of a region leaf (`Texture`/`FontString`), stored beside the arena because
-/// [`crate::widget::Region`] models only structure (kind/owner/layer), not paint. See [`object`]'s
-/// `SetTexture`/`SetVertexColor`/`SetText`.
 /// A two-stop linear gradient (`SetGradientAlpha`/`SetGradient`).
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct Gradient {
-    /// `true` for `"VERTICAL"`, `false` for `"HORIZONTAL"` — the client matches the token
-    /// case-insensitively and treats anything else as horizontal.
+    /// `"VERTICAL"`, matched case-insensitively; anything else is horizontal, as in the client.
     pub vertical: bool,
-    /// The gradient's two stops, RGBA. `SetGradient` (no alpha) sets both alphas to 1.
+    /// RGBA; `SetGradient`, which takes no alpha, sets both alphas to 1.
     pub start: [f32; 4],
     pub end: [f32; 4],
 }
 
 impl Gradient {
-    /// The single colour a one-tint quad can show for this gradient — the midpoint.
+    /// The midpoint, the one colour a one-tint quad can show.
     pub fn midpoint(&self) -> [f32; 4] {
         let mut out = [0.0; 4];
         for (i, chan) in out.iter_mut().enumerate() {
@@ -509,194 +340,91 @@ impl Gradient {
 
 #[derive(Clone, Debug, Default, PartialEq)]
 pub(crate) struct RegionData {
-    /// Region-level visibility (`Show`/`Hide` on a Texture/FontString, XML `hidden=` — the real
-    /// VisibleRegion bit): a hidden region emits no quad regardless of its owner frame's state.
-    /// The ref's own kit relies on it (PanelTemplates_SelectTab hides tab slice textures;
-    /// ContainerFrame_Update hides cooldown textures).
+    /// `Show`/`Hide` and XML `hidden=`: a hidden region emits no quad, whatever its owner's state.
     pub(crate) hidden: bool,
-    /// The region's own alpha (`SetAlpha`/`GetAlpha`, XML `alpha=`); `None` = never set = 1.0.
+    /// `SetAlpha`, XML `alpha=`; `None` is 1. Drawn times the owner frame's alpha, one hop only:
+    /// frame `SetAlpha` (`0x76a690`) cascades to child frames and only invalidates regions.
     ///
-    /// A region draws at `ownAlpha × ownerFrame.alpha` — a **single hop** to its immediate owner,
-    /// never a product up the tree (frame `SetAlpha 0x76a690`
-    /// overwrite-cascades onto child *frames* and only *invalidates* child regions, which re-read
-    /// the owner's `+0xc8` at draw). [`UiScript::extract`](super::UiScript::extract) folds this into
-    /// [`ExtractedQuad::alpha`] alongside that owner alpha.
-    ///
-    /// **Settled for a Texture, kept distinct anyway:** `Texture:SetAlpha 0x79b580` is
-    /// `SetVertexColor(r, g, b, a)` on the *same* `+0xa8`/`+0xb8` slot as [`Self::vertex_color`], so
-    /// in the real client the two clobber each other. We keep them separate fields because the draw
-    /// result is identical either way — both readings end in one product,
-    /// `texel × ownColorAlpha × frameAlpha` — and no reference call site sets both on one region;
-    /// separate storage additionally keeps `SetAlpha` on a FontString from wiping its font object's
-    /// colour, which the CSimpleFontString half of that binding was never pinned for. The
-    /// divergence is now *known* rather than open: a call site that sets both is where it bites.
+    /// Deviation: kept apart from [`Self::vertex_color`], which the reference's `Texture:SetAlpha`
+    /// (`0x79b580`) rewrites, because the drawn product differs only on a region that sets both,
+    /// which no stock code does, and a FontString's `SetAlpha` then keeps its font colour.
     pub(crate) alpha: Option<f32>,
     /// A texture path (`SetTexture("Interface\\...")`).
     pub(crate) texture: Option<String>,
-    /// The **solid-colour texture** (`SetTexture(r, g, b, a)`, and XML `<Texture><Color/></Texture>`
-    /// with no `file=`) — the `+0xcc` slot [`Self::texture`] also occupies, so the two are mutually
-    /// exclusive by construction: every writer of one clears the other. Not a tint. The real client
-    /// really does *generate an 8×8 texture* here (`CSimpleTexture::SetTexture(const CImVector*)`
-    /// `0x770360` → `0x44a9c0` → the `rep stos` generator `0x5c5350` fills 64 texels with the packed
-    /// ARGB), which is why the XML alpha rides in the **texel** and multiplies with
-    /// [`Self::vertex_color`] rather than being replaced by it.
+    /// `SetTexture(r, g, b, a)` or an XML `<Color>` with no `file=`, sharing `+0xcc` with
+    /// [`Self::texture`]: setting one clears the other. The reference makes an 8×8 texture of it
+    /// (`0x770360` → `0x44a9c0` → `0x5c5350`), so its alpha multiplies with the vertex colour's.
     pub(crate) fill: Option<[f32; 4]>,
-    /// `SetGradientAlpha(orientation, r1,g1,b1,a1, r2,g2,b2,a2)` / `SetGradient(...)` — the two-stop
-    /// linear gradient the client generates into the same texture slot the colour form fills.
-    ///
-    /// **Stored in full, painted as its midpoint, and that gap is stated rather than implied.** The
-    /// UI renderer has one tint per quad (a colour region is the shared 1x1 white image tinted), so
-    /// there is nowhere yet to put a second stop; folding to the average is a *visible*
-    /// approximation and belongs to the director to judge (method §7). It is kept whole HERE so the
-    /// renderer can honour it later without another API change — the data is already right, only
-    /// the paint is coarse.
-    ///
-    /// Measured cost of the approximation on the corpus's biggest consumer: `FuBar_Panel.lua:144`
-    /// is `SetGradientAlpha("VERTICAL", 1,1,1,0, 1,1,1,0.5*t)` — **white at both stops, alpha
-    /// only**, i.e. a soft fade, and both textures are `Hide()`n on the next two lines. A uniform
-    /// half-alpha band instead of a fade is the whole difference there.
+    /// `SetGradientAlpha`/`SetGradient`, stored whole and drawn as its midpoint: the renderer has
+    /// one tint per quad, so the reference's gradient is not built.
     pub(crate) gradient: Option<Gradient>,
-    /// The **vertex colour** (`SetVertexColor 0x79abd0` → `0x77f750`, writing `+0xb8`; a StatusBar's
-    /// `SetStatusBarColor`; a FontString's `SetTextColor` and its font object's colour) — storage
-    /// distinct from [`Self::fill`]/[`Self::texture`]'s `+0xcc`.
-    ///
-    /// **Draw law** (`0x77f750`):
-    /// `drawn = texel × vertexColour`, per channel, **alpha included**. `None` = never set = the
-    /// untinted white every region draws at by default. This is why the reference `SkillFrame`'s
-    /// row trough — declared `<Color 1,1,1,0.2>`, then `SetVertexColor(0, 0, 0.75, 0.5)`'d — draws
-    /// at alpha `0.2 × 0.5 = 0.1`, not `0.5`. [`super::extract`] does that multiply.
+    /// `SetVertexColor` (`0x79abd0` → `0x77f750`, `+0xb8`), `SetStatusBarColor` or a text colour,
+    /// drawn as `texel × colour` per channel, alpha included: a `<Color 1,1,1,0.2>` tinted
+    /// `(0, 0, 0.75, 0.5)` draws at alpha 0.1, as `SkillFrame`'s row trough does.
     pub(crate) vertex_color: Option<[f32; 4]>,
-    /// This region is a **portrait**: draw its texture masked to the inscribed circle (set by
-    /// `SetPortraitToTexture`, and by `SetPortraitTexture`'s round unit binding). WoW portraits
-    /// are circular — the frame ring is a thin band whose transparent corners would otherwise
-    /// expose the square icon/model. The app bakes the circular alpha mask; the flag rides
-    /// through [`QuadContent::Texture::circular`]. False with a live `portrait_unit` = the square
-    /// booth pane (`BenillaSetBoothTexture`, decision 0208 §5).
+    /// A portrait (`SetPortraitToTexture`, `SetPortraitTexture`), masked to the inscribed circle;
+    /// false with a `portrait_unit` is the square booth pane (`BenillaSetBoothTexture`).
     pub(crate) circular: bool,
-    /// A **live unit portrait** (`SetPortraitTexture(region, unit)` round;
-    /// `BenillaSetBoothTexture(region, token)` square): the unit token whose model this region
-    /// renders. `Some` ⇒ the region samples the app's off-screen portrait bake for this token
-    /// (ignoring `texture`/`color`); rides through [`QuadContent::Texture::portrait_unit`]. Cleared by
-    /// `SetTexture`/`SetPortraitToTexture` (the region becomes an ordinary texture again).
+    /// A live unit portrait's unit, drawn from the app's bake instead of the texture or colour;
+    /// cleared by `SetTexture` and `SetPortraitToTexture`.
     pub(crate) portrait_unit: Option<String>,
     /// FontString text (`SetText`).
     pub(crate) text: Option<String>,
-    /// The write-on reveal (`SetAlphaGradient(start, length)` — CSimpleFontString's per-character
-    /// alpha gradient, the quest-description "writing" machinery): characters before `start` draw
-    /// opaque, the next `length` ramp 1→0, the rest invisible. `None` = no gradient (every
-    /// FontString but an armed quest description). Cleared by `SetText` — fresh text draws whole.
+    /// `SetAlphaGradient(start, length)`, the quest text's write-on reveal; cleared by `SetText`.
     pub(crate) alpha_gradient: Option<(f32, f32)>,
-    /// The region's blend mode (`SetBlendMode` / XML `alphaMode` — the reference's `[texture+0xd0]`,
-    /// the shared enum `0x811aa8`). Highlight state textures are created at
-    /// [`BlendMode::Add`] (the client's `SetHighlightTexture` contract); everything else starts at
-    /// the ctor's [`BlendMode::Blend`].
-    ///
-    /// **The whole mode is kept, not just "is it ADD"**, because `GetBlendMode` answers it back as
-    /// a string and a getter that could only ever say `"BLEND"` or `"ADD"` would answer `"BLEND"`
-    /// to a texture the caller set to `"MOD"`. The renderer still reads only the ADD/not-ADD
-    /// distinction ([`QuadContent::Texture::additive`]) — that is unchanged, and the three modes it
-    /// flattens are the stated gap they always were.
+    /// `SetBlendMode`, XML `alphaMode` (the reference's `+0xd0`), starting at [`BlendMode::Add`]
+    /// for a highlight texture, as `SetHighlightTexture` makes it, else at the constructor's BLEND.
     pub(crate) blend: BlendMode,
-    /// Explicit region size (`SetWidth`/`SetHeight`/XML `<Size>`); `None` = derive. Size fills the
-    /// axis the anchors don't pin (the client's "0 = derive") — so under a texture's implicit
-    /// SetAllPoints (two corners pin everything) an authored size is structurally unread, which is
-    /// how the reference stack-split plate authors 256×32 and renders 172×96 (decision 1310, B180).
+    /// `SetWidth`/`SetHeight`, XML `<Size>`; `None` derives it. It fills only an axis the anchors
+    /// leave free, so under an implicit `SetAllPoints` the stack-split plate's 256×32 is unread.
     pub(crate) size: Option<(f32, f32)>,
-    /// Region anchors (`SetPoint`/XML `<Anchors>` on a Texture/FontString). An anchor's
-    /// `relative_to` defaults to the owner frame and may name a frame or a **sibling region**
-    /// (resolved via [`Model::region_names`]; the fixpoint in [`UiScript::resolve`] orders the
-    /// sibling chain). Every drawable region carries at least one — authored, or the
-    /// creation-path implicit anchor ([`super::region::implicit_creation_anchor`], decision
-    /// 1310); empty means a templateless Lua region nobody anchored, which never resolves and
-    /// never draws. Non-empty ⇒ resolved in [`UiScript::resolve`], any edge the anchors leave
-    /// unset inherited from the owner frame's rect.
+    /// `SetPoint`, XML `<Anchors>`, relative to the owner frame unless naming a frame or sibling
+    /// region. An edge they leave unset comes from the region's own size, measured text or texel
+    /// extent, never the owner's rect; one still unset leaves the region unresolved (`0x767a20`).
+    /// Empty is a Lua region nobody anchored, which never draws: every other has an authored or
+    /// creation-time anchor ([`super::region::implicit_creation_anchor`]).
     pub(crate) anchors: Vec<Anchor>,
-    /// `Texture:SetDesaturated(flag)` — the shader desaturation state (`0x79c1e0`).
-    /// Rides the extract as [`QuadContent::Texture::desaturated`] and the
-    /// renderer greys the texel by it (decision 1327), so the binding answers "shader supported"
-    /// — see `region/paint.rs`'s `SetDesaturated`.
+    /// `SetDesaturated` (`0x79c1e0`): the renderer greys the texel, so the binding reports support.
     pub(crate) desaturated: bool,
-    /// `SetNonSpaceWrap` / `CanNonSpaceWrap` — FontString only (`0x79e9f0`/`0x79ead0`).
-    /// **State only here.** The real client's gx flag `0x40` feeds a
-    /// mid-word wrap carry and the fit-count terminator whose one consumer is the ellipsis
-    /// truncate at `0x771ec0`; our text layout has no ellipsis path, so honouring the value in
-    /// layout would mean inventing one. Stored and answered faithfully, unread by the renderer —
-    /// which is the honest position and is stated rather than left to be discovered.
-    ///
-    /// Default is ON (a no-arg `SetNonSpaceWrap()` also enables), so `None` reads as enabled.
+    /// `SetNonSpaceWrap`/`CanNonSpaceWrap` (`0x79e9f0`/`0x79ead0`), `None` on. Stored, not applied:
+    /// the reference's flag `0x40` drives a mid-word wrap and the ellipsis fit count (`0x771ec0`).
     pub(crate) non_space_wrap: Option<bool>,
-    /// FontString justification, as the client's own **dword** rather than a pair of resolved
-    /// enums — `CSimpleFontString+0x120`, bits 0–2 horizontal and 3–5 vertical, defaulting to the
-    /// ctor's `0x212` (CENTER|MIDDLE). See [`crate::justify::Justify`]: an axis can be *cleared*,
-    /// which no resolved enum can hold, and the Lua getter and the draw path then answer that
-    /// state differently (`"UNKNOWN"` vs centred) — both faithfully.
+    /// The client's dword at `CSimpleFontString+0x120`: bits 0-2 horizontal, 3-5 vertical, `0x212`
+    /// from the constructor. A cleared axis answers `"UNKNOWN"` to the getter and draws centred.
     pub(crate) justify: crate::justify::Justify,
-    /// The `<TexCoords>`/`SetTexCoord` UV mapping ([`TexCoords`]: the 4-edge crop, or the 8-arg
-    /// affine quad). `None` = the full texture. Slices the quadrant/atlas art (decision 0084).
+    /// The `<TexCoords>`/`SetTexCoord` mapping; `None` is the full texture.
     pub(crate) tex_coords: Option<TexCoords>,
-    /// `Texture:SetTexCoordModifiesRect(flag)` / `GetTexCoordModifiesRect()` — the reference's
-    /// `[texture+0x124]`, whose sole writer is `SetTexCoordModifiesRect 0x79c080`
-    /// (`0x79c113 mov [edi+0x124],eax`) and which is BSS-zero otherwise.
-    ///
-    /// **State only, and the geometry half is NOT wired.** In the reference the flag gates a
-    /// rect-recompute leg (`0x770462`): with it set, a `SetTexCoord` re-derives the
-    /// region's own rect from the UV quad rather than leaving the rect alone and merely resampling
-    /// inside it. Honouring that here means `region::layout`'s resolve reading this flag and
-    /// deriving the region's rect from [`Self::tex_coords`] instead of from its anchors and size —
-    /// a resolve-order change, not a paint one, and nothing in either addon corpus or the stock UI
-    /// calls the SETTER, so there is no measured case to build it against. Stored and answered
-    /// truthfully, unread by layout; stated here rather than left to be discovered.
+    /// `SetTexCoordModifiesRect`, the reference's `+0x124` (written only at `0x79c113`, in
+    /// `0x79c080`). Stored, not applied: there a set flag makes `SetTexCoord` re-derive the rect
+    /// from the UV quad (`0x770462`); no stock or corpus code sets it.
     pub(crate) tex_coord_modifies_rect: bool,
-    /// On-screen rotation about the region center, radians, counterclockwise-positive.
-    /// **Unwritable: the `Texture:SetRotation` that was its only setter is gone** (1.12 registers
-    /// the name on PlayerModel alone) — see [`QuadContent::Texture::rotation`] for why it is still
-    /// here.
+    /// Rotation about the centre, radians counterclockwise; always 0: 1.12 has no Texture setter.
     pub(crate) rotation: f32,
-    /// The named font object this FontString last resolved (`inherits=`/`SetFontObject`) — our
-    /// `FONTINSTANCE+0x028 parentFontObject`, and a **live** link: mutating that object
-    /// (`GameFontNormal:SetFont(…)`) re-paints this region through
-    /// [`script::font::propagate`](super::font::propagate). `GetFontObject` returns its handle.
-    /// The object's paint is eagerly copied into the fields below so every reader stays a plain
-    /// field read.
+    /// The font object this FontString inherits (`FONTINSTANCE+0x028`, a FontString's `+0xd0`), a
+    /// live link: its paint is copied below, and
+    /// [`script::font::propagate`](super::font::propagate) repaints on a change.
     pub(crate) font_object: Option<String>,
-    /// Which of the font properties below this region set **for itself** since its last
-    /// `SetFontObject` — our `FONTINSTANCE+0x038 explicitlySetMask`. See [`FontExplicit`].
+    /// What this region set for itself, which its font object no longer overwrites.
     pub(crate) font_explicit: FontExplicit,
-    /// Resolved font face path (`SetFont`/`SetFontObject`). `None` = the renderer's default face.
+    /// Resolved font face path (`SetFont`/`SetFontObject`); `None` is the renderer's default.
     pub(crate) font_path: Option<String>,
-    /// Resolved font height in logical px (`SetFont`/`SetFontObject`/`<FontHeight>`). `None` = default.
+    /// Resolved font height in logical px; `None` is the renderer's default.
     pub(crate) font_height: Option<f32>,
-    /// A `SetTextHeight` scale override — the client's two text-size regimes:
-    /// a FontString defaults to **one-to-one** (bit `0x200`,
-    /// drawn at the raster px, subject to the 32-px raster cap); `SetTextHeight 0x771600` is the
-    /// ONLY clearer — the literal size then flows through UNCAPPED, magnified from the raster.
-    /// `Some` = that regime; the renderer draws at this height and skips the one-to-one cap.
+    /// A `SetTextHeight` override: a FontString is one-to-one by default (bit `0x200`, capped at
+    /// 32 px), and only `SetTextHeight 0x771600` clears that, drawing the size uncapped.
     pub(crate) text_height: Option<f32>,
-    /// Resolved glyph outline (`SetFont` flags / font object). Carried, not yet drawn (see [`Outline`]).
+    /// Resolved glyph outline (`SetFont` flags or the font object).
     pub(crate) outline: Outline,
-    /// Resolved drop shadow (font object `<Shadow>`), drawn by the renderer behind the glyphs.
+    /// Resolved drop shadow (font object `<Shadow>`), drawn behind the glyphs.
     pub(crate) font_shadow: Option<FontShadow>,
-    /// The host-measured wrapped text size for a FontString with no explicit height — the engine's
-    /// side of the measure round-trip ([`UiScript::fontstrings_needing_measure`] →
-    /// [`UiScript::set_measured_text`]): the real client's layout asks its font engine for string
-    /// metrics exactly like this. `key` invalidates on text/font/wrap changes.
+    /// The host-measured size of a FontString with no explicit height.
     pub(crate) measured: Option<MeasuredText>,
 }
 
-/// The per-property "this region set it itself, so it does not inherit" record — the real client's
-/// `FONTINSTANCE+0x038 explicitlySetMask`.
-///
-/// It exists for exactly one job: when a **font object is mutated**
-/// (`GameFontNormal:SetTextColor(…)`), every region inheriting it re-reads the object, and a
-/// property the region had overridden must survive that re-read. A dropdown row that does
-/// `SetFontObject(GameFontNormalSmall)` and then `SetTextColor(1, 0, 0)` keeps its red.
-///
-/// A fresh `SetFontObject` **clears the whole mask** — re-pointing at an object is a deliberate
-/// "take this object's paint", and `Dewdrop-2.0` re-runs exactly that pair on every row refresh
-/// (`SetFontObject` at l.2160-2166, then `SetTextColor` at l.2180), which only stays correct if the
-/// re-point wins. (Whether the real client's mask outlives a re-point is the one part of this the
-/// bytes have not yet been asked; the choice above is the one that leaves current behaviour
-/// untouched, and it is the *propagation* half — new behaviour either way — that the mask governs.)
+/// The font properties a region set for itself, which changes to its font object no longer
+/// reach: the reference's inherit mask (`FONTINSTANCE+0x2c`, a FontString's `+0xd4`; justify
+/// per axis at `+0x124`), whose bit each local setter clears. Nothing restores one, a later
+/// `SetFontObject` included, so a row that calls `SetTextColor(1, 0, 0)` stays red.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub(crate) struct FontExplicit {
     /// `SetFont`'s path argument, or XML `font=`.
@@ -707,7 +435,7 @@ pub(crate) struct FontExplicit {
     pub(crate) outline: bool,
     /// `SetTextColor`/`SetVertexColor`, or a `<FontString><Color>`.
     pub(crate) color: bool,
-    /// Reserved for a region-level shadow setter; XML `<Shadow>` on the FontString itself.
+    /// `SetShadowColor`/`SetShadowOffset`, or XML `<Shadow>` on the FontString itself.
     pub(crate) shadow: bool,
     /// `SetJustifyH`, or XML `justifyH=`.
     pub(crate) justify_h: bool,
@@ -715,48 +443,23 @@ pub(crate) struct FontExplicit {
     pub(crate) justify_v: bool,
 }
 
-/// A cached host measurement of a FontString's laid-out text (see [`RegionData::measured`]).
+/// A cached host measurement of a FontString's laid-out text.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub(crate) struct MeasuredText {
-    /// The extent of the text **as laid out** — wrapped inside the region's declared width, if it
-    /// has one. The auto-size input, and what `GetWidth`/`GetHeight` echo.
+    /// The laid-out extent, wrapped in any declared width, which auto-size and `GetWidth` read.
     pub(crate) w: f32,
     pub(crate) h: f32,
-    /// The extent the text would take with **no wrap constraint** — what `GetStringWidth` reports,
-    /// and a different number from [`Self::w`] for exactly those regions that carry a declared width.
-    ///
-    /// The reference keeps only this one (`GetStringWidth 0x79e510` → `0x772890`, cached at
-    /// `+0xfc`): it measures the raw text with **no wrap constraint**, so "Lua sees the natural,
-    /// unwrapped, un-truncated width at the DRAWN size". benilla needs both, because its auto-size
-    /// path reads the laid-out extent off this same cache.
-    ///
-    /// Serving the laid-out width to `GetStringWidth` instead is a **feedback loop**, not a rounding
-    /// difference: any kit that sizes a box from `GetStringWidth` and then sets a width on the string
-    /// — which is what the reference's own `PanelTemplates_TabResize` does — reads its own output
-    /// back as its next input. The macro window's character tab changed width every single frame for
-    /// exactly this reason (decision 0997).
+    /// The unwrapped width `GetStringWidth` answers, the only one the reference keeps
+    /// (`0x79e510` → `0x772890`, cached at `+0xfc`); answering `w` would feed back through
+    /// `PanelTemplates_TabResize`, which sets the string's width from it.
     pub(crate) natural_w: f32,
-    /// Hash of (text, font path, font height bits, wrap-width bits) — mismatch ⇒ re-measure.
+    /// The [`RegionData::measure_key`] it was measured under; a mismatch re-measures.
     pub(crate) key: u64,
 }
 
 impl MeasuredText {
-    /// Did the part of this measurement the **layout** reads move? (decision 1385)
-    ///
-    /// Only `w`/`h` are layout inputs — they are the auto-size axes, and the only fields
-    /// `InputFingerprint` feeds (`script::layout`'s region walk hashes `m.w`/`m.h`, nothing else).
-    /// `key` is the measure CACHE's business and `natural_w` is `GetStringWidth`'s; neither can
-    /// move a rect.
-    ///
-    /// The distinction is load-bearing, not tidiness. A measure request is only ever *issued* when
-    /// the stored key mismatches, and `MeasuredText`'s derived `PartialEq` includes `key` — so
-    /// `d.measured != Some(new)` is **structurally always true** at both write sites, and touching
-    /// the epoch on it meant every answered measure opened tier 1. A FontString whose text changes
-    /// to something the same size does that on a cadence: a buff countdown ticking `"58s" → "57s"`,
-    /// a colour-code swap, any same-width digit. Tier 1 then went dirty and tier 2 hashed all
-    /// ~10k anchored regions to conclude nothing had moved — ~1 ms, `solves=0`, per tick, times
-    /// the number of unsynchronised timers on screen. The same shape 0740's own doc records the
-    /// bag-hover loop paying, and a sibling of the castbar's (1385).
+    /// Whether `w` or `h`, the layout's only inputs, moved: a fresh measure always differs in
+    /// `key`, so a whole-value compare would dirty the layout on every same-size text change.
     pub(crate) fn layout_moved(before: Option<Self>, after: Self) -> bool {
         before.is_none_or(|b| {
             b.w.to_bits() != after.w.to_bits() || b.h.to_bits() != after.h.to_bits()
@@ -765,162 +468,119 @@ impl MeasuredText {
 }
 
 impl RegionData {
-    /// The measure-cache key for the region's CURRENT text/font/wrap/outline — the one recipe both
-    /// sides of the measure round-trip share. [`super::UiScript::fontstrings_needing_measure`]
-    /// stamps it into each request (and skips regions whose stored [`MeasuredText::key`] still
-    /// matches); the Lua-visible metric reads (`GetStringWidth`/`GetWidth`, region.rs) treat a
-    /// stored measure whose key mismatches as ABSENT — a measure of text this region no longer
-    /// holds is not a metric (the whisper-header cursor bug: `SetText("Tell …: ")` then a
-    /// same-frame `GetWidth()` served the OLD header's width, and the edit box latched its text
-    /// insets on it). The layout solver's own read (layout.rs) deliberately does NOT key-check:
-    /// it keeps the last-known box until the fresh measure lands, so lines never collapse for the
-    /// round-trip frame. **With one carve-out, and it is the carve-out this cache needs**: EMPTY
-    /// text is never measured at all (both measure asks filter it out), so "until the fresh
-    /// measure lands" is a promise that can never be kept for a cell that goes from text to `""`
-    /// — the solver drops the stored measure there rather than hold a dead box forever (B309: the
-    /// item tooltip's blank SET spacers drew rows the plate counted as zero).
-    /// `scale` is the owner frame's `effective_scale`: it's in the key because the host measures
-    /// at the drawn raster size ([`MeasureRequest::scale`]), so a `SetScale` under a cached
-    /// measure must invalidate it exactly like a font-size change.
+    /// The measure-cache key of the text, font, wrap width, outline and owner scale. A Lua metric
+    /// read treats a measure under another key as absent; the layout keeps the old box until the
+    /// new one lands, except for empty text, which is never measured.
     pub(crate) fn measure_key(&self, scale: f32) -> u64 {
         use std::hash::{Hash, Hasher};
         let mut hasher = std::collections::hash_map::DefaultHasher::new();
-        // By reference: `String` hashes exactly as `str` does, and this runs for every
-        // FontString on every frame's staleness sweep — a clone here was ~1.5k heap allocs a
-        // frame at a city pin, all discarded at the key compare.
+        // By reference: `String` hashes as `str` does, and this runs for every FontString every
+        // frame, so a clone would allocate for nothing.
         self.text.as_deref().unwrap_or("").hash(&mut hasher);
         self.font_path.hash(&mut hasher);
         self.font_height.map(f32::to_bits).hash(&mut hasher);
         self.text_height.map(f32::to_bits).hash(&mut hasher);
         let wrap_width = self.size.map(|s| s.0).filter(|w| *w > 0.0);
         wrap_width.map(f32::to_bits).hash(&mut hasher);
-        // Outline is in the key because it changes measured WIDTH under the client's step law
-        // (an outlined font steps +1px more per glyph — GlyphStepBase 0x5ca2b0).
+        // The outline changes the measure: a THICK one steps each glyph 1 px further
+        // (`GlyphStepBase 0x5ca2b0`).
         (self.outline as u8).hash(&mut hasher);
         scale.to_bits().hash(&mut hasher);
         hasher.finish()
     }
 }
 
-/// The focused EditBox's advance-table request — returned by
-/// [`UiScript::editbox_advances_request`](super::UiScript::editbox_advances_request), answered
-/// via [`UiScript::set_editbox_advances`](super::UiScript::set_editbox_advances) with the
-/// per-byte cumulative laid-out widths of `text` (len+1 entries, `[0] = 0`, a continuation byte
-/// repeating its lead's value). The metrics seam that makes click→char-index, drag-select, and
-/// the caret scroll window engine-local (the click handler `0x77b800` and its caret leaves).
+/// The focused EditBox's advance-table request, answered via
+/// [`UiScript::set_editbox_advances`](super::UiScript::set_editbox_advances) with the width at
+/// each byte of `text` (len+1 entries, `[0] = 0`, a continuation byte repeating its lead's), for
+/// the engine's click-to-caret and selection (the reference's click handler is `0x77b800`).
 #[derive(Clone, Debug, PartialEq)]
 pub struct EditBoxAdvanceRequest {
-    /// Opaque frame id of the box — pass back verbatim.
+    /// Opaque frame id; pass it back verbatim.
     pub id: u32,
     pub font: Option<String>,
     pub height: Option<f32>,
-    /// The resolved glyph outline — the per-glyph step bias (+1px, GlyphStepBase 0x5ca2b0)
-    /// changes every advance.
+    /// A THICK outline adds 1 px to every glyph step (`GlyphStepBase 0x5ca2b0`).
     pub outline: Outline,
-    /// The box frame's `effective_scale`. The host measures at the drawn raster size
-    /// (`height × scale × seam`) but divides the answer by the SEAM ALONE, so the advances come
-    /// back in screen UI units — the space the engine's ÷seam mouse feed and the box's resolved
-    /// (scale-multiplied) rect both live in. Contrast [`MeasureRequest::scale`], whose answer is
-    /// frame-local.
+    /// The box's `effective_scale`. The host measures at `height × scale × seam` but divides by
+    /// the seam alone, so advances come back in screen UI units, like the mouse feed and the
+    /// box's rect; a [`MeasureRequest`] answer is frame-local instead.
     pub scale: f32,
-    /// The DISPLAY string (mask-aware) the table indexes.
+    /// The displayed string (mask-aware) the table indexes.
     pub text: String,
-    /// `Some(width)` for a multiline box: also answer the wrapped-row starts + row pitch at this
-    /// wrap width (the text region's resolved width — the same width the draw wraps at), via
-    /// [`UiScript::set_editbox_advances`](super::UiScript::set_editbox_advances)'s `rows`/`cell_h`.
-    /// `None` = single-line (answer `rows = [0]`).
+    /// For a multiline box, the width the draw wraps at: the answer then also carries the row
+    /// starts and pitch (`rows`, `cell_h`); `None` is single-line, answered `rows = [0]`.
     pub wrap_width: Option<f32>,
-    /// Cache key — pass back verbatim.
+    /// Cache key; pass it back verbatim.
     pub key: u64,
 }
 
-// `EditAction`/`EditUnit` are the *editing law's* vocabulary, so they live beside the state that
-// law mutates ([`crate::widget::EditBoxState`]) rather than here — `script` depends on `widget`,
-// never the other way round, and the glue screens drive the law with no Lua VM in sight
-// (decision 0704). Re-exported here because this is the path the host has always used.
+// Re-exported from `widget`, which `script` depends on and never the reverse.
 pub use crate::widget::{EditAction, EditOutcome, EditUnit};
 
-/// The focused EditBox's per-frame text-UI geometry — returned by
-/// [`UiScript::focused_editbox_text_ui`](super::UiScript::focused_editbox_text_ui): everything
-/// the host needs to draw the box's window substring, selection highlight, and caret.
+/// The focused EditBox's per-frame text geometry: its text window, selection and caret.
 #[derive(Clone, Debug, PartialEq)]
 pub struct EditBoxTextUi {
-    /// The text region's draw target — match the extracted Text quad by it.
+    /// The text region's draw target, to find its extracted Text quad by.
     pub target: crate::order::ZTarget,
-    /// Draw `display[display_from..]` (the scroll window's start, a DISPLAY byte offset).
-    /// Always 0 for a multiline box (it wraps in place instead of windowing).
+    /// The scroll window's start, a display byte offset; always 0 for a multiline box.
     pub display_from: usize,
-    /// The box is multiline: the host draws the full wrapped block (no window, no unbounded
-    /// rect) and seats the caret/selection by `(row, x)` at the answered row pitch.
+    /// Multiline: the whole wrapped block draws, caret and selection seated by `(row, x)`.
     pub multi_line: bool,
     /// Caret x in px from the drawn window's text origin (multiline: from the row's origin).
     pub caret_x: f32,
-    /// Caret wrapped-row index (always 0 single-line) — the vertical half of the 2-D seat.
+    /// Always 0 single-line.
     pub caret_row: usize,
-    /// The answered row pitch in px (0 until the advance answer lands); the host may prefer its
-    /// own draw-side line cell — the two are the same law (the snapped font em).
+    /// The answered row pitch in px, 0 until the advances arrive.
     pub cell_h: f32,
-    /// The blink phase — draw the caret this frame (hosts may pin it on for captures).
+    /// The blink phase: draw the caret this frame.
     pub caret_on: bool,
-    /// The selection as per-row `(row, x0, x1)` px spans from each row's origin, when non-empty
-    /// (single-line: at most one span, row 0 — the old scalar span).
+    /// Per-row `(row, x0, x1)` px spans from each row's origin; single-line has at most one.
     pub selection: Vec<(usize, f32, f32)>,
-    /// The selection highlight tint (`SetHighlightColor`; ctor default opaque `0x606060` gray).
+    /// `SetHighlightColor`; the constructor's default is opaque `0x606060` grey.
     pub highlight_color: [f32; 4],
 }
 
-/// One FontString the layout needs host-measured this frame (no explicit height; text present).
-/// Returned by [`UiScript::fontstrings_needing_measure`](super::UiScript::fontstrings_needing_measure); answer via [`UiScript::set_measured_text`](super::UiScript::set_measured_text).
+/// One FontString the layout needs host-measured this frame (text, no explicit height), answered
+/// via [`UiScript::set_measured_text`](super::UiScript::set_measured_text).
 #[derive(Clone, Debug, PartialEq)]
 pub struct MeasureRequest {
-    /// Opaque region id — pass back verbatim.
+    /// Opaque region id; pass it back verbatim.
     pub id: u32,
     pub font: Option<String>,
     pub height: Option<f32>,
-    /// The `SetTextHeight` override (see [`RegionData::text_height`]): measured at this height,
-    /// uncapped, when present — the drawn size is the measured size (`0x772890`).
+    /// The `SetTextHeight` override, measured uncapped at the drawn size (`0x772890`).
     pub text_height: Option<f32>,
-    /// Wrap width when the region's width is pinned (explicit `<Size x>`), else single-line.
+    /// Set when the region's width is pinned (explicit `<Size x>`), else single-line.
     pub wrap_width: Option<f32>,
-    /// The resolved glyph outline — it biases the client's per-glyph step (+1px, GlyphStepBase
-    /// 0x5ca2b0), so the measured width depends on it.
+    /// A THICK outline adds 1 px to every glyph step (`GlyphStepBase 0x5ca2b0`).
     pub outline: Outline,
-    /// The owner frame's `effective_scale`. The host must measure at the DRAWN raster size —
-    /// `font_height × scale × its own screen seam` — and divide the px answer back by the full
-    /// product: glyph advances step to whole pixels (the step law), so a measure taken at the
-    /// unscaled size is not `scale ×` the drawn one, and an auto-sized FontString in a scaled
-    /// frame would mis-fit its own text (spurious wrap → spurious "..." ellipsis).
+    /// The owner's `effective_scale`. The host measures at `font_height × scale × seam` and
+    /// divides by that whole product: advances step to whole pixels, so a measure at the
+    /// unscaled size is not proportional to the drawn one.
     pub scale: f32,
     pub text: String,
-    /// Cache key — pass back verbatim.
+    /// Cache key; pass it back verbatim.
     pub key: u64,
 }
 
-/// One ScrollingMessageFrame ring line whose wrapped **row count** needs a host measurement (its
-/// cache key went stale — new line, width change, font change). The message-frame half of the
-/// measure round-trip: returned by
-/// [`UiScript::message_lines_needing_measure`](super::UiScript::message_lines_needing_measure),
-/// answered via [`UiScript::set_message_line_rows`](super::UiScript::set_message_line_rows) with
-/// `(frame, index, rows, key)` — same-frame, before extract, no re-resolve needed (rows shift only
-/// the emitted bands, never the anchor graph).
+/// One ScrollingMessageFrame line whose wrapped row count needs measuring, answered via
+/// [`UiScript::set_message_line_rows`](super::UiScript::set_message_line_rows) in the same frame,
+/// before extract: rows move only the drawn bands, never the anchors.
 #[derive(Clone, Debug, PartialEq)]
 pub struct LineMeasureRequest {
-    /// Opaque frame id — pass back verbatim.
+    /// Opaque frame id; pass it back verbatim.
     pub frame: u32,
-    /// The line's ring index at collect time — pass back verbatim (the ring cannot shift between
-    /// collect and answer within one host drive; the key still guards a stale store).
+    /// The line's ring index at collect time; pass it back verbatim.
     pub index: u32,
     pub font: Option<String>,
     pub height: Option<f32>,
-    /// The frame's resolved inner width — the wrap constraint. Already scale-multiplied (it is
-    /// the resolved rect's width), unlike `height`, which is the font's local size.
+    /// The frame's inner width: already scale-multiplied, unlike `height`, the font's own size.
     pub wrap_width: f32,
-    /// The resolved glyph outline (step-law width bias, as on [`MeasureRequest`]).
     pub outline: Outline,
-    /// The frame's `effective_scale` — the host wraps at the drawn raster size
-    /// (`height × scale × seam`), as on [`MeasureRequest::scale`].
+    /// As for [`MeasureRequest::scale`].
     pub scale: f32,
     pub text: String,
-    /// Cache key — pass back verbatim.
+    /// Cache key; pass it back verbatim.
     pub key: u64,
 }
diff --git a/crates/benilla-ui/src/script/ui_errors.rs b/crates/benilla-ui/src/script/ui_errors.rs
index 3e68f4b2..f7b8639a 100644
--- a/crates/benilla-ui/src/script/ui_errors.rs
+++ b/crates/benilla-ui/src/script/ui_errors.rs
@@ -1,24 +1,16 @@
-//! **The Lua-callable half of the client-local error-display family** — FrameXML-facing globals
-//! whose whole body, in the reference binary, is "push one catalog id at
-//! `CGGameUI::DisplayError`'s dispatcher". The engine-side half (a Rust system raising a key
-//! directly, e.g. the passive-on-bar refusal) pushes onto the same [`Model::ui_errors`] queue;
-//! the app drains it, resolves each key against the VM's own GlobalStrings and fires
-//! `UI_ERROR_MESSAGE` (`ui_action/feed.rs`) — which is byte-for-byte the reference route: catalog
-//! row → GlobalStrings text → FrameScript event `0xe0`, rendered by UIErrorsFrame.
+//! Lua globals whose whole body pushes one catalog id at `CGGameUI::DisplayError`'s dispatcher.
+//! Engine-side refusals share the [`Model::ui_errors`] queue, which the app resolves against
+//! GlobalStrings and fires as `UI_ERROR_MESSAGE` (event `0xe0`), the reference's route.
 //!
-//! First tenant: `NotWhileDeadError` (decision 1507's open item): registration pair `0x83e398`,
-//! C body `0x48d340` = `push 0x7e; call 0x496720; xor eax,eax; ret` — no argument read, no
-//! dead-check of its own, 0 return values, and its catalog row (`0xb4be70`, key
-//! `ERR_PLAYER_DEAD`) names sound `"NONE"`, so the toast is silent. FrameXML decides *when* to
-//! call it (ShowUIPanel's `whileDead` refusal, UIParent.lua l.663-666; ContainerFrame.lua l.147
-//! and l.190); the binding only displays.
+//! `NotWhileDeadError` (`0x48d340`, registered at `0x83e398`) is `push 0x7e; call 0x496720`: no
+//! argument, no dead check, no return, and a silent catalog row (`0xb4be70`). FrameXML decides
+//! when to call it (`UIParent.lua:663-666`, `ContainerFrame.lua:147` and `:190`).
 
 use mlua::Lua;
 
 use super::model::Model;
 
-/// The GlobalStrings key of catalog id `0x7e` — the row `NotWhileDeadError`'s pushed id resolves
-/// to ("You can't do that when you're dead.").
+/// Catalog id `0x7e`'s GlobalStrings key ("You can't do that when you're dead.").
 const NOT_WHILE_DEAD_KEY: &str = "ERR_PLAYER_DEAD";
 
 /// Register the error-display globals.
diff --git a/crates/benilla-ui/src/script/unit/bindings.rs b/crates/benilla-ui/src/script/unit/bindings.rs
index 3d090462..8b6b51d8 100644
--- a/crates/benilla-ui/src/script/unit/bindings.rs
+++ b/crates/benilla-ui/src/script/unit/bindings.rs
@@ -1,19 +1,7 @@
-//! The `Unit*` global registrations (see the parent module's doc for the seam and the return
-//! shapes): every binding reads the per-token [`UnitState`](super::UnitState) snapshot store
-//! through the parent's `with_unit`/`pick_unit_token` helpers.
-//!
-//! **Every predicate here returns through one function** — [`super::unit_predicate`] when it reads
-//! a snapshot field, [`flag`](super::super::binding_abi::flag) when it computes its own bool.
-//! Neither ever hands mlua a Rust `bool`: all 29 of the reference's unit predicates push the
-//! constant double `1.0` (`lua_pushnumber 0x6f3810`) or `nil` (`lua_pushnil 0x6f37f0`), one value
-//! at every live `ret`, and **no binding in the 83-entry table at `0x850438` calls
-//! `lua_pushboolean 0x6f39f0` at all** (decisions 1830, 2043, 2048). A new predicate that open-codes
-//! `Value::Integer(1)`/`Value::Nil`, or returns a `bool`, is the drift those records exist to stop.
-//!
-//! **The scope of that claim is the unit table, not "the binding surface"** — 2043 said the wider
-//! thing and 2048 corrected it. `lua_pushboolean` exists at `0x6f39f0` with seven call sites, and
-//! one of them *is* a registered FrameScript binding: `IsPetAttackActive 0x4be0e0` answers a real
-//! Lua `true`/`false`, never nil (ours already does — `super::super::pet`).
+//! The `Unit*` global registrations, over the per-token [`UnitState`](super::UnitState) snapshots.
+//! Every predicate answers the number 1 or nil through [`super::unit_predicate`] or
+//! [`flag`](super::super::binding_abi::flag): no binding in the reference's unit table (`0x850438`)
+//! calls `lua_pushboolean` (`0x6f39f0`), though `IsPetAttackActive` (`0x4be0e0`) outside it does.
 
 use mlua::{Lua, Value};
 
@@ -24,18 +12,9 @@ use super::{
     unit_predicate, unknownobject, with_unit, PlayerRecord, SelectionRequest,
 };
 
-/// **The `"player"` fast path, shared by the four verbs that take it** (decision 2263).
-///
-/// `Some(x)` = this token is `"player"` and `x` is the record's answer; `None` = it is any other
-/// token and the caller falls through to the unit resolver. That is the reference's own shape —
-/// a full-string, case-insensitive compare of the token against `0x847894` (`b"player\0"`) whose
-/// **match is the fall-through** — and it is one function rather than four copies for the reason
-/// [`super::super::names::gated_rank`](crate)'s sibling comment gives about rank: four readers of
-/// one record, each testing the token itself, is how they drift apart. `UnitName`, `UnitRace`,
-/// `UnitClass` and `UnitSex` are the whole set; `UnitLevel` is **not** one of them.
-///
-/// The compare is a full string, not a prefix: `"playerfoo"` is a recognised-but-unresolvable
-/// token ([`super::token_recognised`]) and goes to the resolver, not here.
+/// The `"player"` fast path of `UnitName`, `UnitRace`, `UnitClass` and `UnitSex`, never
+/// `UnitLevel`: the record's answer when the token equals `"player"` (`0x847894`) whole and
+/// case-insensitively; any other token, `"playerfoo"` included, goes to the resolver.
 fn player_record_arm<T>(
     lua: &Lua,
     token: &Option<String>,
@@ -51,18 +30,12 @@ fn player_record_arm<T>(
     Some(f(&model.player_record))
 }
 
-/// The two class ids `GetComboPoints 0x51a190` accepts — the literals `4` and `0xb` it compares
-/// the class byte `[[player+0x110]+0x79]` against. That byte is `UNIT_FIELD_BYTES_0` byte 1, the
-/// same value [`PlayerReqState::class_id`](super::super::PlayerReqState) carries; `UnitClass`'s own
-/// binding (`0x518350`) reads it through the identical `[obj+0x110]+0x79` chain, which is what
-/// identifies it. The *names* are the conventional vanilla ids — the client's class table is
-/// heap-built, so nothing in the file maps 4→Rogue by itself (decision 0875).
+/// The class ids `GetComboPoints` (`0x51a190`) accepts: it compares the class, `UNIT_FIELD_BYTES_0`
+/// byte 1, with 4 and 0xb.
 const CLASS_ROGUE: u32 = 4;
 const CLASS_DRUID: u32 = 11;
 
-/// Register the `Unit*` globals reading the per-token snapshot store (the same style/place the
-/// object model and stdlib register their globals — bare globals on `_G`, matching the live API
-/// surface).
+/// Register the `Unit*` globals.
 pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
@@ -73,20 +46,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `UnitIsVisible(unit)` — `0x516030`, and it is **object presence, nothing else**:
-    // `ClntObjMgrObjectPtr(resolve(token), TYPEMASK_UNIT) != NULL`. 57 bytes, one branch, no field
-    // read and no comparison beyond `test eax,eax`.
-    //
-    // **Not a synonym for `UnitExists`, and neither implies the other.** An out-of-range party
-    // member has a roster entry and no object: `UnitExists` = 1 through its GUID fallback,
-    // `UnitIsVisible` = nil. That pair is the branch pfUI takes seven times — most visibly
-    // `if not UnitIsVisible(unitstr) or not UnitIsConnected(unitstr)`, which chooses between a 3D
-    // portrait and a flat one.
-    //
-    // **The return is the NUMBER 1, never a boolean** — `0x6f3810` writes tag 3 with the operands
-    // of `1.0` on the true leg, `lua_pushnil` on the false one. `UnitExists` above answers a Rust
-    // `bool` and so hands Lua `true`/`false`; that is its own pre-existing question, and matching
-    // it here would have been the wrong kind of consistency.
+    // `UnitIsVisible(unit)` (`0x516030`): whether the client holds the unit's object, nothing else.
+    // Not `UnitExists`: an out-of-range party member exists through its roster entry, unseen.
     g.set(
         "UnitIsVisible",
         lua.create_function(|lua, token: Option<String>| {
@@ -94,26 +55,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `UnitIsTapped(unit)` / `UnitIsTappedByPlayer(unit)` — `0x519c90` / `0x519d00`, a masked-byte
-    // pair (108 bytes each; only the mask and the `Usage:` string differ). Each is
-    // `object present && (UNIT_DYNAMIC_FLAGS & mask)` and nothing else: no ownership, no GUID
-    // compare, no party/raid or health conjunct anywhere in either body.
-    //
-    // **Shape A, unlike `UnitIsVisible` directly above** — these two carry an `lua_isstring` gate
-    // and a `Usage:` `luaL_error`, where their neighbour has none. Two adjacent verbs in one
-    // family with opposite argument shapes is exactly why 1717's taxonomy is settled per binding;
-    // inheriting the sibling's shape here would have been wrong in the quiet direction.
-    //
-    // The reference raises TWO different messages — `Usage:` for a non-string/non-number, and the
-    // resolver's `"Unknown unit name: %s"` for a bad token (and for any NUMBER, since the
-    // `lua_isstring` gate admits tag 3 and hands the resolver `"5"`). `check_unit_token` inside
-    // `with_unit` is the second of those; the first is the `?` on the argument type below.
-    // The gate is the BINDING's, not `with_unit`'s: `check_unit_token` lets a nil through by
-    // design, because that is right for `UnitExists`, `UnitIsVisible` and eleven others. **"and
-    // most of this family" is what this comment used to say, and it was the wrong way round** —
-    // all 83 entries of the table at `0x850438` gate and raise in 53 cases, with only 13 unit-token
-    // bindings quiet (decision 1834). These two were never the exception; they were an early
-    // instance of the rule.
+    // `UnitIsTapped`/`UnitIsTappedByPlayer` (`0x519c90`/`0x519d00`): the object is present and its
+    // `UNIT_DYNAMIC_FLAGS` has the mask bit, nothing more. Unlike `UnitIsVisible` they gate with
+    // `lua_isstring`: another type raises `Usage:`, and a number raises `Unknown unit name`.
     for (name, usage, by_player) in [
         ("UnitIsTapped", r#"Usage: UnitIsTapped("unit")"#, false),
         (
@@ -125,10 +69,6 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         g.set(
             name,
             lua.create_function(move |lua, token: Value| {
-                // Shape A: a string OR a number passes (`lua_isstring` admits tag 3, and the
-                // client hands the resolver `"5"` — which then raises `Unknown unit name: 5`,
-                // the family's SECOND message). Everything else — nil, absent, boolean, table,
-                // function — is the `Usage:` raise.
                 let token = Some(crate::script::binding_abi::string_arg(lua, token, usage)?);
                 let hit = with_unit(lua, &token, false, |u| {
                     if by_player {
@@ -137,35 +77,16 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                         u.tapped
                     }
                 })?;
-                // One value, and it is the NUMBER 1 or nil — never a boolean, the same shape the
-                // rest of this family answers in.
                 Ok(flag(hit))
             })?,
         )?;
     }
 
-    // `UnitIsPartyLeader(unit)` — `0x516210`. **Two legs, ORed, covering disjoint failures:**
-    //
-    //     o = ObjPtr(resolve(token), TYPEMASK_PLAYER)          -- 0x10, not this family's 8
-    //     (o != NULL && (o.PLAYER_FLAGS & 0x1)) || resolve(token) == g_groupLeaderGuid
-    //
-    // The descriptor leg answers for any held player — including a stranger who leads their OWN
-    // party, which a comparison against our group's leader can never express. The GUID leg answers
-    // for a group member whose object the client does not hold (an out-of-range `party3`, any
-    // `raidN`), where there is no descriptor to read. Neither is sufficient alone, which is why
-    // this is not derivable from `IsPartyLeader()` + `GetPartyLeaderIndex()` however it is
-    // arranged.
-    //
-    // **No zero guard, and that is deliberate.** `IsPartyLeader 0x4e9130` short-circuits on a
-    // `0:0` cached leader; this one does not. An unresolvable-but-non-raising token resolves to
-    // `0:0`, which equals the zeroed leader while ungrouped — so `UnitIsPartyLeader(nil)` answers
-    // **1 solo**. It reads like a bug and it is the behaviour; answering nil there would be the
-    // divergence.
-    //
-    // Shape C with a shape-A tail: no `lua_isstring` gate and no `Usage:` of its own, but a bad
-    // token — and any Lua NUMBER, which the resolver stringifies first — raises
-    // `"Unknown unit name: %s"` from `check_unit_token`. One value on both legs, the number 1 or
-    // nil, never a boolean.
+    // `UnitIsPartyLeader(unit)` (`0x516210`): a held player's `PLAYER_FLAGS` bit 0x1, for a
+    // stranger leading their own party, or a GUID equal to the group leader's, for a member not
+    // held. No zero guard (unlike `IsPartyLeader`, `0x4e9130`): GUID 0 matches the zeroed leader,
+    // so `UnitIsPartyLeader(nil)` answers 1 while ungrouped. No `Usage:` gate; a bad token or a
+    // number raises `Unknown unit name`.
     g.set(
         "UnitIsPartyLeader",
         lua.create_function(|lua, token: Option<String>| {
@@ -175,8 +96,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                 .as_ref()
                 .and_then(|t| model.unit(t))
                 .is_some_and(|u| u.group_leader);
-            // The GUID leg. A token with no snapshot resolves to GUID 0 — the reference's `0:0` —
-            // and 0 == the zeroed leader is exactly the solo case above.
+            // A token with no snapshot is GUID 0, the reference's `0:0`.
             let guid = token
                 .as_ref()
                 .and_then(|t| model.unit(t))
@@ -193,50 +113,13 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                 token,
                 r#"Usage: UnitName("unit")"#,
             )?);
-            // TWO values on every live path (`eax = 2` at `0x5170ae` and `0x517289`): the name and
-            // the **realm**. Slot 2 is nil for a same-realm player, and *structurally* nil for a
-            // pet, creature, game object or item — `0x609210` writes the out-parameter only on its
-            // PLAYER branch. benilla is single-realm, so the second is always nil here; the day a
-            // cross-realm name arrives it is `UnitState`'s to carry, and `UnitPopup.lua:106`'s
-            // `name.."-"..server` join is what will read it. Decision 1840.
-            //
-            // Not to be confused with `showServerName`: that is the parameter of FrameXML's own
-            // `GetUnitName(unit, showServerName)` wrapper, which calls this binding with ONE
-            // argument. The engine's real second argument is a strict `LUA_TBOOLEAN` and is not
-            // modelled — no consumer passes it.
-            //
-            // Value 1 — and the ONLY two nils a recognised token can produce (`0x517020`): the
-            // `"player"` fast path reads the local name buffer and pushes nil when it is empty
-            // (`0x51708c` → `0x5abdc0`; the `0x517083` this used to cite is the token's string
-            // *compare*, `call 0x64a4c0` — corrected 2261), and a token that resolves to GUID 0
-            // pushes nil (`0x5170c0`).
-            // The empty-buffer nil is not an explicit push either: `0x517095` is
-            // `lua_pushstring`, which falls through on NULL at `0x6f3895` into `lua_pushnil`. EVERY other path ends in a
-            // string — the cached name, or `FrameScript_GetText("UNKNOWNOBJECT")`: `0x517220` for
-            // a GUID with no object and no cache row, `0x609324` inside `CGUnit_C::GetUnitName`
-            // for a unit whose name cache has not answered or is stale (a pet's is
-            // `petnamecache.wdb` (`0x554e10`), keyed by `UNIT_FIELD_PETNUMBER` (`0x6092b2`)). A
-            // freshly called pet is that case by construction: `UNIT_PET` fires off the
-            // descriptor and the name lands a `CMSG_PET_NAME_QUERY` round-trip later, and stock
-            // `PetStable.lua:129` concatenates the answer in between.
-            //
-            // "Resolved to a GUID" is a SEATED SNAPSHOT — not `exists`. The reference's
-            // `UnitExists` is a conjunction with `IsSelectable` (the `UnitState::exists` doc's
-            // named gap), so a not-selectable unit reads its name there with `UnitExists` nil; the
-            // name resolver's own nil is GUID 0 and nothing else, and a feed that seats a token
-            // has resolved it. Decision 2002.
-            //
-            // **The `"player"` arm is the BUFFER, not the snapshot** (decision 2261). `0x51708c`
-            // reads `0x5abdc0` — the local name buffer at `0xc27d88` — and returns; it never
-            // reaches the resolver, so no object, no descriptor and no name-query answer is
-            // involved on this path at all. Modelling it off the snapshot (as this did until
-            // 2261) put the one name the client always knows behind the one cache that can miss:
-            // decision 2260's realm-cache load dropped our own guid, the feed pushed a nameless
-            // player over the roster seat, and `UnitName("player")` read nil in the world.
-            //
-            // The buffer's emptiness is still the reference's own nil — it just means something
-            // a snapshot cannot say, and something a client that is in the world never is:
-            // "no Enter World has been committed in this process".
+            // Two values (`0x5170ae`, `0x517289`): the name, and the realm, nil for a same-realm
+            // player or a non-player (`0x609210`), so always nil in single-realm benilla. A second
+            // argument (stock `UnitPopup.lua:106` passes `true`) is not read. The name is nil only
+            // for an empty `"player"` buffer (`0x51708c`, `0x6f3895`) or GUID 0 (`0x5170c0`);
+            // otherwise a string, `UNKNOWNOBJECT` until the name cache answers (`0x517220`,
+            // `0x609324`), as for a new pet. A seated snapshot answers even where `exists` is
+            // false; the `"player"` arm reads the local name buffer (`0xc27d88`), never the unit.
             if let Some(seeded) = player_record_arm(lua, &token, |r| r.name.clone()) {
                 let name = if seeded.is_empty() {
                     Value::Nil
@@ -279,13 +162,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitLevel (`0x517fc0`): the raw UNIT_FIELD_LEVEL — a raw ≤ 0
-    // VERBATIM (never −1) — or **−1** iff world-boss rank 3 (unconditional) / hostile
-    // (reaction ≤ 1 internal) AND ≥ 10 levels above the player (inclusive). The FrameXML
-    // target frame branches its skull on `<= 0` (`TargetFrame_CheckLevel`), so a level-0
-    // (unstreamed) unit skulls through the verbatim 0, exactly as the reference does. Not
-    // carried: the dormant attackable-decay override (`max(1, raw − round(min(b,100)·0.05))`,
-    // `b` INFERRED and 0 in normal play — it can never drive the value ≤ 0 anyway).
+    // UnitLevel (`0x517fc0`): the raw level (a raw 0 stays 0), or -1 for a world boss or a hostile
+    // unit 10 or more levels above the player. The reference's attackable-decay override
+    // (`max(1, raw - round(min(b, 100) * 0.05))`, `b` an untraced byte not seen set) is not built.
     g.set(
         "UnitLevel",
         lua.create_function(|lua, token: Value| {
@@ -309,12 +188,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitIsCorpse (`0x5161c0`) → 1/nil: a pure OBJECT-TYPE check —
-    // the token resolves to a live TYPEID_CORPSE world object (a released player's remains).
-    // NO health test: a dead mob or dead player is NOT a corpse (the ref target frame shows a
-    // dead mob's level number, not the skull). Reads [`UnitState::corpse_object`], which no
-    // feed sets yet — corpse objects aren't selectable in benilla — so this returns nil today,
-    // faithfully.
+    // UnitIsCorpse (`0x5161c0`): the token names a corpse object, a released player's remains; a
+    // dead unit is not one. No feed sets `corpse_object`, so this answers nil.
     g.set(
         "UnitIsCorpse",
         lua.create_function(|lua, token: Option<String>| {
@@ -322,16 +197,14 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitCanAttack (`0x516c50`) → 1/nil: pure delegation to the
-    // `CanAttack 0x606980` predicate (decision 0172), read from the non-player token's app-fed
-    // snapshot ([`UnitState::can_attack`]). Directional in the live API; our snapshot carries
-    // the player→unit direction, the only order the shipped FrameXML calls
-    // (`UnitCanAttack("player", "target")`).
+    // UnitCanAttack (`0x516c50`) delegates to `CanAttack` (`0x606980`). The snapshot holds only
+    // whether the player can attack the unit, fed for `target`, `targettarget` and `npc`, and that
+    // answers both argument orders; the reverse direction stock FrameXML also asks
+    // (`TargetFrame.lua:147`) is not built.
     g.set(
         "UnitCanAttack",
         lua.create_function(|lua, (a, b): (Value, Value)| {
-            // BOTH positions carry an `lua_isstring` gate — two sites in the body —
-            // so either argument being nil raises (decision 1836).
+            // Both arguments are `lua_isstring`-gated, so either one nil raises.
             let a = Some(crate::script::binding_abi::string_arg(
                 lua,
                 a,
@@ -347,10 +220,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetQuestGreenRange (`0x4e17d0`) — the green→grey boundary the
-    // FrameXML `GetDifficultyColor` buckets by (ref QuestLogFrame.lua l.593):
-    // `GRAYBAND[min(playerLevel/5, 19)]` off the binary's `0x8076c0` table, byte-identical to
-    // the `0x81dda8`/`0x80ae98` twins [`grey_band`] transcribes. No args; 0 with no player.
+    // GetQuestGreenRange (`0x4e17d0`): the green-to-grey boundary `QuestLogFrame.lua:593` buckets
+    // by, from the table at `0x8076c0`. The reference answers 0 with no player object (`0x4e17f8`);
+    // here a level of 0 reads the table's first entry, 4.
     g.set(
         "GetQuestGreenRange",
         lua.create_function(|lua, ()| {
@@ -371,8 +243,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The other two of the client's death trio (decision 0308 §1): a released ghost has health 1,
-    // so IsDead is false for it and the popup flow branches on all three.
+    // A released ghost has health 1, so `UnitIsDead` is false for it.
     g.set(
         "UnitIsGhost",
         lua.create_function(|lua, token: Value| {
@@ -396,26 +267,14 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitReaction(unit, other) → the reaction scale, or nil. The live API is directional (unit's
-    // reaction toward `other`); our feed only resolves it for the "target" token toward the player,
-    // which is the sole caller (`TargetFrame_CheckFaction`), so the `other` arg is accepted and
-    // unused.
-    //
-    // **NOT a 1/nil predicate, and its nil does not mean "reaction 0"** (decision 2048, correcting
-    // 2043's aside). `0x5167e0` pushes `0x6061e0(u1, u2)` **plus one** (`0x51683e inc eax`,
-    // `0x516842 fild`) — a self-compare answers **5** — so the value is 1-based and **0 is
-    // unreachable**. Its nil leg (`0x51685f`) means only that a token failed to resolve to a live
-    // UNIT.
-    //
-    // Ours maps our own `reaction == 0` to nil because that is our sentinel for "not yet fed", and
-    // the observable is the same nil an unresolved token gives. The gap is the feed's, not the
-    // shape's: a resolved unit whose reaction has not streamed answers nil here where the reference
-    // answers a number. The target frame paints its name plate blue on that nil.
+    // UnitReaction(unit, other) (`0x5167e0`): `0x6061e0(unit, other)` plus one (`0x51683e`), so
+    // 1-based, 5 for a unit toward itself, never 0; nil (`0x51685f`) only when a token names no
+    // unit. Our reaction 0 means "not fed" and also answers nil, where the reference answers a
+    // number. The snapshot holds the reaction toward the player, so `other` is checked, not read.
     g.set(
         "UnitReaction",
         lua.create_function(|lua, (token, _other): (Value, Value)| {
-            // BOTH positions carry an `lua_isstring` gate — two sites in the body —
-            // so either argument being nil raises (decision 1836).
+            // Both arguments are `lua_isstring`-gated, so either one nil raises.
             let token = Some(crate::script::binding_abi::string_arg(
                 lua,
                 token,
@@ -435,19 +294,13 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitIsEnemy / UnitIsFriend — the reaction-thresholded pair (the ref target-select sound
-    // branch, TargetFrame_OnShow). v1 derives both from the same snapshot as `UnitReaction`:
-    // enemy = reaction ≤ 2 (hated/hostile), friend = reaction ≥ 5 (friendly+); the live API's
-    // extra PvP inputs (duels, flagged players, sanctuaries) are deferred with the rest of the
-    // PvP wire. The pair is directional in the live API but our snapshot only carries the
-    // target↔player reaction, so the binding reads whichever arg isn't "player" (the ref calls
-    // both orders: UnitIsEnemy("target","player"), UnitIsFriend("player","target")). Unknown
-    // reaction (0) → nil for both, the API's "can't tell". `1`/nil returns, era-style.
+    // UnitIsEnemy/UnitIsFriend (`0x516890`/`0x516930`) threshold the reaction `UnitReaction`
+    // reads: enemy at 1 or 2, friend at 5 and up, and an unfed 0 is neither. The snapshot holds the
+    // reaction toward the player, so the non-player argument names the unit.
     g.set(
         "UnitIsEnemy",
         lua.create_function(|lua, (a, b): (Value, Value)| {
-            // BOTH positions carry an `lua_isstring` gate — two sites in the body —
-            // so either argument being nil raises (decision 1836).
+            // Both arguments are `lua_isstring`-gated, so either one nil raises.
             let a = Some(crate::script::binding_abi::string_arg(
                 lua,
                 a,
@@ -466,8 +319,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
     g.set(
         "UnitIsFriend",
         lua.create_function(|lua, (a, b): (Value, Value)| {
-            // BOTH positions carry an `lua_isstring` gate — two sites in the body —
-            // so either argument being nil raises (decision 1836).
+            // Both arguments are `lua_isstring`-gated, so either one nil raises.
             let a = Some(crate::script::binding_abi::string_arg(
                 lua,
                 a,
@@ -484,22 +336,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitIsPlayer(unit) → 1 if the unit is a player character, else nil. Reads the snapshot's
-    // guid-family flag (the same one the unit tooltip's "(Player)" line keys on). The target frame's
-    // faction tint branches on it (`TargetFrame_CheckFaction`): a player-controlled unit takes the
-    // red/blue player legs, an NPC the reaction swatch. (The live gate is `UnitPlayerControlled`,
-    // which also covers pets/charmed creatures; we resolve only the player half of it — the extra
-    // reach needs a player-controlled flag we don't carry, and a player's own alt is the case here.)
-    // UnitIsCivilian(unit) → 1 if killing this unit would be a DISHONORABLE kill, else nil. This is
-    // `0x612550` itself handed to Lua — the same four-term predicate (`pvp` bit AND creature-query
-    // civilian flag AND hostile AND the kill would be grey) that the unit tooltip's green CIVILIAN
-    // line and `UnitPVPName`'s civilian arm already run through `is_civilian_kill`. That function's
-    // doc called itself "ONE home, two callers"; the stock target frame is the third, and it is the
-    // one that names the predicate — `TargetFrame_CheckDishonorableKill` (TargetFrame.lua:230) is
-    // its only FrameXML caller and the comment inside it reads "Is a dishonorable kill".
-    //
-    // Sharing the function is the point: a second copy would let the tooltip, the name and the
-    // target plate disagree about the same mob.
+    // UnitIsCivilian(unit): killing the unit would be dishonorable, the predicate `0x612550`. It
+    // shares `is_civilian_kill` with the tooltip's civilian line and `UnitPVPName`, so all agree.
     g.set(
         "UnitIsCivilian",
         lua.create_function(|lua, unit: Value| {
@@ -516,11 +354,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             ))
         })?,
     )?;
-    // UnitPlayerControlled(unit) → 1 if a PLAYER is driving this unit, else nil. `UNIT_FIELD_FLAGS`
-    // bit 3 (`UNIT_FLAG_PVP_ATTACKABLE 0x8`), which is wider than `UnitIsPlayer` below: a player's
-    // pet and a charmed creature answer 1 here and nil there. Stock `UnitFrame_OnEnter`
-    // (UnitFrame.lua:58) is the caller that made this a blocker rather than a nicety — it gates the
-    // player-options newbie tip on it, so a missing binding raised on the first unit-frame hover.
+    // UnitPlayerControlled(unit) (`0x516410`): `UNIT_FIELD_FLAGS` bit 0x8, vmangos
+    // `UNIT_FLAG_PLAYER_CONTROLLED`, so a player's pet or a charmed creature answers 1 where
+    // `UnitIsPlayer` answers nil. An unrecognised token answers nil here; the reference raises.
     g.set(
         "UnitPlayerControlled",
         lua.create_function(|lua, unit: Option<String>| {
@@ -537,42 +373,23 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             unit_predicate(lua, &token, |u| u.is_player)
         })?,
     )?;
-    // UnitIsPlusMob(unit) → 1 if this unit is a "plus" mob, else nil (`0x516d40`, extent
-    // `[0x516d40,0x516d8f)`). One bit of the SAME `UNIT_FIELD_FLAGS` word `UnitPlayerControlled`
-    // reads: `shr ecx,6; test cl,1` — bit 6, `UNIT_FLAG_PLUS_MOB 0x40`.
-    //
-    // **It is not a rank read**, which is the trap the name sets. `UnitClassification` is its
-    // table neighbour and answers off the gated creature rank (decision 0782), so the obvious
-    // implementation is `rank > 0` — but `0x516d40` never calls the rank getter `0x605620` (whose
-    // six callers are enumerated) and never touches the creature cache. The two agree in practice
-    // because the SERVER derives the bit from the rank — vmangos `Creature::UpdateEntry` sets it
-    // on `!IsPet() && rank > 0` (`Creature.cpp:634`, INFERRED from source) — so **rare** answers 1
-    // here alongside elite, rare-elite and world boss, while a player, a pet and a normal mob
-    // answer nil. Where they part is the unstreamed unit: a creature whose cache record has not
-    // arrived still carries its own flags, so this answers truthfully where a rank read would say
-    // "normal". No client code writes the bit (zero bitwise RMWs at `+0xa0` image-wide), so it is
-    // the server's word verbatim.
-    //
-    // No stock FrameXML file calls it, which is why nothing shipped ever raised on its absence;
-    // addons do (`FuBar_DakSmak` colours its tooltip with it), and calling the nil global is what
-    // B385 reported. Last of the three verbs decision 1834 left loudly absent. Decision 2209.
+    // UnitIsPlusMob(unit) (`0x516d40`): `UNIT_FIELD_FLAGS` bit 0x40, never the creature rank
+    // (`0x605620`). The server sets it for a non-pet above normal rank (`Creature.cpp:634`), so a
+    // rare answers 1, and an uncached creature still answers from its flags.
     g.set(
         "UnitIsPlusMob",
         lua.create_function(|lua, token: Option<String>| {
-            // One of 1834's quiet thirteen: no `lua_isstring` gate and no `Usage:` arm, so a nil
-            // or absent token is a quiet nil. An UNRECOGNISED one still raises — the body reaches
-            // the shared resolver through `0x515940`, and that is `unit_predicate`'s own gate.
+            // No `lua_isstring` gate, so nil answers nil; an unrecognised token still raises in
+            // the resolver (`0x515940`).
             unit_predicate(lua, &token, |u| u.flags & 0x40 != 0)
         })?,
     )?;
 
-    // The identity predicates (decision 0434 §5 — the unit popup's menu pick + gating). Same-token
-    // is trivially the same unit; otherwise both snapshots must carry a real (nonzero) guid.
+    // UnitIsUnit(a, b): both units exist and are the same token or share a nonzero GUID.
     g.set(
         "UnitIsUnit",
         lua.create_function(|lua, (a, b): (Value, Value)| {
-            // BOTH positions carry an `lua_isstring` gate — two sites in the body —
-            // so either argument being nil raises (decision 1836).
+            // Both arguments are `lua_isstring`-gated, so either one nil raises.
             let a = Some(crate::script::binding_abi::string_arg(
                 lua,
                 a,
@@ -583,7 +400,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                 b,
                 r#"Usage: UnitIsUnit("unit", "otherUnit")"#,
             )?);
-            // BOTH arguments go through the resolver, so either being unrecognised raises.
+            // Both go through the resolver, so either one unrecognised raises.
             check_unit_token(&a)?;
             check_unit_token(&b)?;
             let model = lua.app_data_ref::<Model>().expect("model app_data");
@@ -600,17 +417,10 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitAffectingCombat(unit) → the number 1 in combat, else nil (`0x517e10`).
-    //
-    // The unusual half is the miss shape: **false and "no such unit" are the SAME arm**
-    // (`0x517e48 je 0x517e73` joins `0x517e5c je 0x517e73`), so an unresolvable token is
-    // indistinguishable from a peaceful one. Reproduced deliberately — an addon cannot use this
-    // binding to probe whether a unit exists, and ours must not let it either.
-    //
-    // A **bad or missing argument raises**, unlike its `UnitInRaid` neighbour: the guard here is
-    // `0x6f3510` (number-or-string, and NULL for an absent argument) with the usage literal at
-    // `0x851070` behind `0x6f4940`, which does not return. A *number* is accepted and stringified
-    // — `UnitAffectingCombat(5)` resolves the token `"5"`, finds nothing, and answers nil.
+    // UnitAffectingCombat(unit) (`0x517e10`): 1 in combat, else nil. No such unit takes the same
+    // arm as a unit out of combat (`0x517e48`, `0x517e5c`), so it cannot probe existence. A missing
+    // argument, or one neither string nor number, raises `Usage:` (`0x6f3510`, `0x6f4940`), unlike
+    // `UnitInRaid`; a number reaches the resolver, which raises `Unknown unit name` (`0x515c14`).
     g.set(
         "UnitAffectingCombat",
         lua.create_function(|lua, token: Value| {
@@ -624,27 +434,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitInRaid(unit) → **the constant number 1** on a hit, nil on a miss. NOT an index, and
-    // never a raise (`0x516350`).
-    //
-    // Three things about this binding are the opposite of the obvious guess, and all three are
-    // read off its 83 bytes:
-    //
-    //  * **The hit value is a hard-coded `1.0`** — `0x51637e push 0x3ff00000; push 0` into the
-    //    push-number helper. The membership helper underneath (`0x4baee0`) only ever returns
-    //    `mov eax,1` / `xor eax,eax`; it never exposes its loop counter, so there is no index to
-    //    be 0- or 1-based about. An addon doing `local i = UnitInRaid(u)` and then
-    //    `GetRaidRosterInfo(i)` reads member 1 on the real client too.
-    //  * **It never raises.** `0x6f3690` hands back NULL for a missing or uncoercible argument
-    //    instead of erroring, `0x515970` maps NULL/empty to GUID `0:0`, and `0x4baee0`
-    //    short-circuits `0:0` to false at its entry (`or eax,esi; je`). So a missing, wrong-typed
-    //    or unresolvable unit answers `nil`, not an error — hence `Option<String>` and no usage
-    //    string, unlike its `GetRaidRosterInfo` sibling.
-    //  * **The player is in the roster array**, so no `t == "player"` special case is needed here
-    //    — unlike `UnitInParty` below, whose roster excludes the recipient.
-    // HasFullControl() → 1 | nil: the reference's `[0xb4b3e4]` read at `0x51a158` — the control
-    // flag `SMSG_CLIENT_CONTROL_UPDATE` writes for the local player, which the stock unit menu
-    // greys its follow/trade rows on (1958).
+    // HasFullControl(): the flag `SMSG_CLIENT_CONTROL_UPDATE` writes for the local player
+    // (`0xb4b3e4`, read at `0x51a158`), which the stock unit menu greys its follow and trade on.
     g.set(
         "HasFullControl",
         lua.create_function(|lua, ()| {
@@ -653,11 +444,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitPlayerOrPetInParty(unit) / UnitPlayerOrPetInRaid(unit) → 1 | nil: the unit is a
-    // member of the group, or a member's pet — its owner (`UNIT_FIELD_SUMMONEDBY`, else the
-    // charmer, else the creator: `UnitState::owner`) is. The bindings are registered
-    // (`0x5162f0` / `0x5163b0`) and delegate to a C++ predicate not yet identified; the
-    // owner reading is this file's, flagged in 1958.
+    // UnitPlayerOrPetInParty/InRaid(unit): the unit or its owner (`UnitState::owner`) is in the
+    // group. The reference's predicate behind `0x5162f0`/`0x5163b0` is untraced; the owner reading
+    // is benilla's.
     for (name, raid) in [
         ("UnitPlayerOrPetInParty", false),
         ("UnitPlayerOrPetInRaid", true),
@@ -693,6 +482,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
+    // UnitInRaid(unit) (`0x516350`): the constant 1 on a hit (`0x51637e`), never an index. The
+    // reference never raises `Usage:`: a missing or uncoercible argument is GUID 0 (`0x6f3690`,
+    // `0x515970`), a miss (`0x4baee0`). The roster holds the player, unlike `UnitInParty`'s.
     g.set(
         "UnitInRaid",
         lua.create_function(|lua, token: Option<String>| {
@@ -713,8 +505,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitInParty(unit) → 1 when the unit is the player-in-a-group or one of the party1..4
-    // members (a party token directly, or any token whose guid matches the roster's).
+    // UnitInParty(unit): the grouped player or a party member, by token or by roster GUID.
     g.set(
         "UnitInParty",
         lua.create_function(|lua, token: Option<String>| {
@@ -743,15 +534,13 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitCanCooperate(a, b) → 1 for a friendly PLAYER unit. DEVIATION, stated: the client
-    // resolves faction-template cooperation masks; this reads the snapshot's is_player +
-    // UnitIsFriend's reaction>=5 — the same verdict for every case the popup gates on (invite/
-    // whisper a same-faction player), without the faction machinery the engine doesn't carry.
+    // Deviation: UnitCanCooperate answers 1 for a friendly (5 and up) player, because the engine
+    // carries no faction templates; the reference resolves their cooperation masks. The verdict
+    // matches for the unit popup's invite and whisper gates.
     g.set(
         "UnitCanCooperate",
         lua.create_function(|lua, (a, b): (Value, Value)| {
-            // BOTH positions carry an `lua_isstring` gate — two sites in the body —
-            // so either argument being nil raises (decision 1836).
+            // Both arguments are `lua_isstring`-gated, so either one nil raises.
             let a = Some(crate::script::binding_abi::string_arg(
                 lua,
                 a,
@@ -770,13 +559,11 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetRaidTargetIndex(unit) → the mark slot 1..8, or nil unmarked (decision 0434 §6's board,
-    // fed per token).
+    // GetRaidTargetIndex(unit): the mark, 1 to 8, or nil.
     g.set(
         "GetRaidTargetIndex",
         lua.create_function(|lua, token: Value| {
-            // Gated (`0x4bb4be` → `0x4bb4cd`), and the usage string names the
-            // argument unquoted — the reference's own spelling. Decision 1836.
+            // Gated (`0x4bb4be`, `0x4bb4cd`); the unquoted `unit` is the reference's spelling.
             let token = Some(crate::script::binding_abi::string_arg(
                 lua,
                 token,
@@ -791,17 +578,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The party-frame status predicates (decision 0434 §2/§3): connection, AFK/DND, and the two PvP
-    // flags. All 1/nil, through the family's one push site (2043).
-    //
-    // **`UnitIsAFK`/`UnitIsDND` are OURS, not the reference's** — this comment used to claim they
-    // "follow the era shape from the start", which named the wrong authority. A raw byte census
-    // over the whole image finds ZERO occurrences of `UnitIsAFK`, `UnitIsDND`, `IsAFK` or `IsDND`,
-    // as bindings or as strings (positive control: `UnitIsPVP\0` and `UnitIsGhost\0` each return
-    // exactly 1). 1.12 surfaces a member's AFK/DND state through `GetGuildRosterInfo` and the
-    // `CHAT_FLAG_AFK`/`CHAT_FLAG_DND` GlobalStrings; there is no unit predicate for it. They wear
-    // the family's shape because that is the right shape for an invention of ours to wear, not
-    // because a binding was read.
+    // The party frame's status predicates. `UnitIsAFK` and `UnitIsDND` do not exist in the 1.12
+    // client, which has no unit AFK or DND predicate; benilla adds them beyond the 1.12 surface.
     g.set(
         "UnitIsConnected",
         lua.create_function(|lua, token: Value| {
@@ -825,8 +603,6 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             unit_predicate(lua, &token, |u| u.is_dnd)
         })?,
     )?;
-    // UnitIsPVP reads the same `pvp` field the unit tooltip's "PvP" line already does (one flag,
-    // two callers) — see the field doc.
     g.set(
         "UnitIsPVP",
         lua.create_function(|lua, token: Value| {
@@ -849,20 +625,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             unit_predicate(lua, &token, |u| u.is_pvp_ffa)
         })?,
     )?;
-    // UnitFactionGroup(unit) → (englishGroup, localizedName), the pair the PvP icon law reads:
-    // the first names the `UI-PVP-<group>` texture, the second titles the player frame's hit-area
-    // tooltip. nil, nil for a unit with no side (Monster/neutral templates) or no snapshot — the
-    // ref's icon branches gate on exactly that (decision 0646 §1/§3).
-    //
-    // **The two are genuinely different strings and this used to push one twice.** They are
-    // FactionGroup.dbc's `InternalName` (field 2) and `Name0` (field 3), and only on enUS are they
-    // the same word — which is why the duplication survived, and why the old doc on
-    // `UnitState::faction_group` said so as if it settled the matter. Every stock consumer of the
-    // FIRST return concatenates it into a path: `"…\UI-PVP-"..factionGroup` at `PlayerFrame.lua:68`,
-    // `TargetFrame.lua:198` and `PartyMemberFrame.lua:125`, `"…\Battleground-"..` at
-    // `BattlefieldFrame.lua:195`, and `HonorFrame.lua:68` compares it to the literal "Alliance".
-    // On any localized client the old shape named a texture that does not exist. All five of those
-    // files are on our chain.
+    // UnitFactionGroup(unit) → FactionGroup.dbc's `InternalName` (field 2), which stock FrameXML
+    // builds texture paths from (`PlayerFrame.lua:68`), and its localized `Name0` (field 3); nil,
+    // nil for a unit with no side or no snapshot.
     g.set(
         "UnitFactionGroup",
         lua.create_function(|lua, token: Value| {
@@ -877,9 +642,6 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             match pair {
                 (Some(english), localized) => {
                     let a = Value::String(lua.create_string(&english)?);
-                    // The localized half falls back to the English one rather than to nil: a unit
-                    // with a side always has an `InternalName`, and `Name0` is empty for the
-                    // Player/Monster rows, so nil here would blank a tooltip the reference fills.
                     let b = match localized {
                         Some(l) if !l.is_empty() => Value::String(lua.create_string(&l)?),
                         _ => a.clone(),
@@ -891,10 +653,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitRace(unit) → (localized, raceFile) or nil, nil; UnitClass(unit) → (localized,
-    // classFileName) — the paper doll's "Level %d %s %s" line + the CLASSFILENAME-keyed
-    // stat-tooltip lookups (decision 0208 §3). Unknown (feed not landed / a raceless creature)
-    // reports nil, nil — the live API's shape for an absent unit.
+    // UnitRace(unit) → localized, raceFile; UnitClass(unit) → localized, classFileName; nil, nil
+    // for a unit without one.
     g.set(
         "UnitRace",
         lua.create_function(|lua, token: Value| {
@@ -903,9 +663,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                 token,
                 r#"Usage: UnitRace("unit")"#,
             )?);
-            // The `"player"` arm is the RECORD, not the snapshot (decision 2263): `0x518269`
-            // reads `0x5abdd0` — `0xc27e80`, the char-enum row's race byte — and resolves it
-            // through `ChrRaces`, never reaching the unit resolver. See [`PlayerRecord`].
+            // The `"player"` arm reads the character-select record's race byte (`0x518269`,
+            // `0xc27e80`), never the unit resolver.
             if let Some(pair) = player_record_arm(lua, &token, |r| r.race.clone()) {
                 return match pair {
                     Some((loc, file)) => Ok((
@@ -935,8 +694,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                 token,
                 r#"Usage: UnitClass("unit")"#,
             )?);
-            // The `"player"` arm is the RECORD (decision 2263): `0x5183b9` → `0x5abde0`,
-            // `0xc27e81` through `ChrClasses`. Second return is the UPPERCASE token.
+            // The `"player"` arm reads the record's class byte (`0x5183b9`, `0xc27e81`); the second
+            // return is the uppercase token.
             if let Some(pair) = player_record_arm(lua, &token, |r| r.class.clone()) {
                 return match pair {
                     Some((loc, file)) => Ok((
@@ -958,28 +717,10 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             }
         })?,
     )?;
-    // UnitHasRelicSlot(unit) → **the number 1, or nil** (`0x519e50`). Whether this unit's
-    // INVSLOT 17 holds a Libram/Totem/Idol instead of a bow.
-    //
-    // The whole body is: typemask bit 4 (PLAYER) → `UNIT_FIELD_BYTES_0` byte 1 (the class) →
-    // bounds against `ds:0xc0def8` → `ds:0xc0def4`[class] → `[row+0x40]`, `ChrClasses.dbc` field
-    // 16. There is **no `cmp` against a class id anywhere in the function** — 1.12 is entirely
-    // data-driven here, and `benilla_formats::ChrClasses` is that data. The app resolves it and
-    // hands us the bit, exactly as it does for `class_file`.
-    //
-    // **This shipped absent for a long time, on a claim that was simply false** — that the relic
-    // slot post-dates 1.12 and `UnitHasRelicSlot` is a later-era verb. The base `dbc.MPQ` copy of
-    // `ChrClasses.dbc` really does have no field 16; the `patch.MPQ` copy the client actually
-    // reads has it, set for Paladin, Shaman and Druid. Decision 1796. Stock `PaperDollFrame.lua`
-    // calls this **unconditionally** at l.429 and l.580 — so while it was missing, the character
-    // sheet raised `attempt to call global 'UnitHasRelicSlot' (a nil value)` for *every* class,
-    // not just the three.
-    //
-    // No `"player"` fast path (unlike `UnitClass 0x5183b0`, which has one), so this answers for
-    // any token — `UnitHasRelicSlot("target")` on an enemy druid is 1, and the stock inspect path
-    // at `PaperDollFrame.lua:429` depends on exactly that.
-    //
-    // The truthy leg is the NUMBER 1, never a boolean; the false leg is nil, never `false`.
+    // UnitHasRelicSlot(unit) (`0x519e50`): a player unit's class has a relic slot, `ChrClasses.dbc`
+    // field 16 (`ds:0xc0def4`), which the app resolves; no class id is compared in code. Field 16
+    // is in the `patch.MPQ` copy only, set for Paladin, Shaman and Druid. No `"player"` fast path,
+    // so any token answers, as stock `InspectPaperDollFrame.lua:123` needs.
     g.set(
         "UnitHasRelicSlot",
         lua.create_function(|lua, token: Value| {
@@ -993,13 +734,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitSex(unit) → 2 male, 3 female (1 = neuter — no 1.12 unit feed produces it).
-    //
-    // **The absent/unstreamed leg is the NUMBER 2, not nil** — `UnitSex 0x517f9f` pushes the
-    // constant double 2.0 (`push 0x40000000; push 0`) — the numeric-getter contrast to the
-    // predicate family's `1.0`/nil: the numeric getters in this same table answer a number on the
-    // unresolved leg, never nil. The shapes table agrees — this row is `(number)`, with no nil
-    // alternative anywhere (decision 2118).
+    // UnitSex(unit): 2 male, 3 female, or 1 neuter, which no feed sends. A unit that does not
+    // resolve answers 2, never nil (`0x517f9f`).
     g.set(
         "UnitSex",
         lua.create_function(|lua, token: Value| {
@@ -1008,10 +744,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                 token,
                 r#"Usage: UnitSex("unit")"#,
             )?);
-            // The `"player"` arm is the RECORD (decision 2263): `0x517ef9` → `0x5abdf0`,
-            // `0xc27e82`. **No bounds check anywhere on that path** — the byte indexes
-            // `fild [4*eax+0x808be4]` over `{2,3,1,6}` directly — so an unset record answers `2`
-            // ("male") in the reference too, which is what our `0` maps to below.
+            // The `"player"` arm reads the record's byte (`0x517ef9`, `0xc27e82`) into
+            // `{2, 3, 1, 6}` unchecked (`0x808be4`), so an unset record answers 2 there too.
             let sex = match player_record_arm(lua, &token, |r| r.sex) {
                 Some(sex) => sex,
                 None => with_unit(lua, &token, 0u8, |u| u.sex)?,
@@ -1020,56 +754,27 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitCreatureType(unit) → **1 string, or nil** (`0x51a280`), the sibling of
-    // `UnitCreatureFamily 0x51a310`. Adjacent addresses and the same shape — but a DIFFERENT
-    // column: this reads `CreatureType.dbc` col `1 + locale`, the family reads col `8 + locale`.
-    // "Adjacent so probably identical" was right about the shape and wrong about the map.
-    //
-    // **A three-stage resolver** (`0x605570`), with no class or typemask gate anywhere — its only
-    // three tests are bounds checks:
-    //   1. **shapeshift override** — `SpellShapeshiftForm.dbc` col 12, keyed by field 138
-    //      `UNIT_FIELD_BYTES_1` byte 2, taken only if signed `> 0` (`0x60559a jg`), so `0` **and
-    //      the `-1` sentinel** fall through;
-    //   2. **the cached creature record** `[unit+0xb30]+0x18`, returned **unvalidated** — this is
-    //      what [`UnitState::creature_type_name`] carries;
-    //   3. **race fallback** — `ChrRaces.dbc` col 9, keyed by field 36 `UNIT_FIELD_BYTES_0` byte 0.
-    //
-    // Stage 3 is why **a PLAYER answers `"Humanoid"`, not nil**: `ChrRaces` col 9 is **7 for all
-    // nine shipped race rows** and `CreatureType[7]` is `"Humanoid"`, while `[player+0xb30]` is
-    // never populated (a 4-hit writer census: the ctor zeroes it (`0x5fae1a`), two writers
-    // early-out on `key==0`, and the third is hard-gated on `OBJECT_FIELD_TYPE == 0x9`
-    // (`0x60b131`), an equality a player's `0x19` fails structurally). A creature-record-only
-    // reading answers nil there, which would have been wrong for every `UnitCreatureType("player")`
-    // and every `("target")` aimed at a player.
-    //
-    // **Stage 1 is NOT modelled, and it is the one divergence to know about.** A druid in Cat,
-    // Bear, Dire Bear, Travel or Aquatic form — and a shaman in Ghost Wolf — answers `"Beast"` on
-    // the reference and `"Humanoid"` here. Tree Form, Moonkin, Battle Stance, Shadowform and
-    // Spirit of Redemption carry col 12 = `-1` and fall through to race anyway, so those already
-    // agree. We hold the active form's spell id and name ([`super::super::ShapeshiftFormView`])
-    // but **not the form INDEX the DBC is keyed by**, and matching on a localised form name would
-    // be inventing a mechanism the client does not use.
-    //
-    // The argument gate is real, and differs from the two boolean siblings: arg1 goes through
-    // `lua_isstring` (`0x6f3510`) and a miss calls `luaL_error 0x6f4940`, which **longjmps** — so a
-    // non-string, including a MISSING argument, abandons the caller's statement. An unresolved
-    // *token* is a different thing entirely and answers nil (`0x51a2b8`).
-    //
-    // Demand: 6 distinct corpus addons over 11 files.
+    // UnitCreatureType(unit) (`0x51a280`): one string, nil for a token naming no unit (`0x51a2b8`).
+    // Its resolver `0x605570` tries the shapeshift form's type (`SpellShapeshiftForm.dbc` column
+    // 12, only above 0, `0x60559a`), the cached creature record, then the race's (`ChrRaces.dbc`
+    // column 9, "Humanoid" for every race). The form stage is not built (no form index here), so an
+    // animal-form druid or a Ghost Wolf shaman answers "Humanoid" where the reference says "Beast".
+    // A missing argument, or one neither string nor number, raises `Usage:` (`0x6f3510`,
+    // `0x6f4940`).
     g.set(
         "UnitCreatureType",
         lua.create_function(|lua, token: Value| {
             let token = match &token {
                 Value::String(s) => Some(s.to_str()?.to_string()),
-                // `lua_isstring` coerces a number, so a numeric token is accepted and simply
-                // resolves to nothing.
+                // A number passes `lua_isstring`; here it answers nil, where the reference's
+                // resolver raises `Unknown unit name` for it.
                 Value::Number(_) | Value::Integer(_) => Some(String::new()),
                 _ => return Err(mlua::Error::runtime("Usage: UnitCreatureType(\"unit\")")),
             };
             let word = with_unit(lua, &token, None, |u| {
                 u.creature_type_name
                     .clone()
-                    // Stage 3, collapsed: every player race maps to CreatureType 7.
+                    // The race stage, collapsed: every player race maps to type 7.
                     .or_else(|| u.is_player.then(|| "Humanoid".to_string()))
             })?;
             match word {
@@ -1079,11 +784,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitClassification(unit) → "normal" | "elite" | "rareelite" | "worldboss" | "rare" (decision
-    // 0782, byte-verified `0x516d90`): a plain table index by the gated rank, and it answers a
-    // STRING for every input — never nil. An absent snapshot deliberately reports "normal" rather
-    // than nil because the binary does: its unresolved-token path loads table index 0 and pushes
-    // that, so a frame reading it gets the plain border art instead of a nil comparison.
+    // UnitClassification(unit) (`0x516d90`): the rank's word, and "normal" for a token that
+    // resolves to no unit, never nil.
     g.set(
         "UnitClassification",
         lua.create_function(|lua, token: Option<String>| {
@@ -1092,8 +794,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitPowerType(unit) → (index, token): (0, "MANA"), (1, "RAGE"), … (the live API also returns
-    // alt-power color components; addons that read those handle nil).
+    // UnitPowerType(unit) (`0x517940`): one number, the power index (0 mana, 1 rage, ...), with no
+    // token string. A unit that does not resolve answers 0, never nil: `UnitFrame.lua:122` indexes
+    // `ManaBarColor` with it.
     g.set(
         "UnitPowerType",
         lua.create_function(|lua, token: Value| {
@@ -1102,29 +805,13 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                 token,
                 r#"Usage: UnitPowerType("unit")"#,
             )?);
-            // ONE value, not the Era pair. `0x517940` has four live `ret`s and `eax = 1` at every
-            // one, four `lua_pushnumber` sites and zero `lua_pushstring` — the `(type, "MANA")`
-            // tuple does not exist in 5875 (decision 1840). `power_token` stays: 1819's per-resource
-            // event names are its real caller.
-            //
-            // The miss default is the NUMBER 0, the same value as Mana and never nil, which is
-            // load-bearing rather than tidy: `UnitFrame.lua:122` indexes `ManaBarColor[...]` with it.
             let ty = with_unit(lua, &token, 0u8, |u| u.power_type)?;
             Ok(i64::from(ty))
         })?,
     )?;
 
-    // **`UnitMana`/`UnitManaMax(unit)`, not `UnitPower`** (1188 phase 5, decision 1190's list).
-    // These carried Era's names — `UnitPower`/`UnitPowerMax` do not exist in 1.12 at all, which
-    // `reference/1.12-globals.tsv` says outright — and an addon feature-detecting `if UnitPower`
-    // would have taken a path this client cannot honour.
-    //
-    // The rename is exact, not approximate: 1.12's verbs take **one argument** and return the
-    // current/max of whatever power the unit actually uses (`UnitFrame.lua`: `local currValue =
-    // UnitMana(unit)`), which is precisely what the Era pair did when called without a type — and
-    // every one of our own call sites called it that way. The type-filtering second argument goes
-    // with the name: 1.12 has no such parameter, and asking "how much *mana* does a rage user
-    // have" is spelled `UnitPowerType(unit)` first, which we already provide and which IS 1.12.
+    // UnitMana/UnitManaMax(unit): the current and maximum of whatever power the unit uses; 1.12
+    // has no `UnitPower` and no power-type argument.
     g.set(
         "UnitMana",
         lua.create_function(|lua, token: Value| {
@@ -1148,10 +835,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitXP/UnitXPMax(unit) → the player's XP within the level / the level's requirement. Player-
-    // level values (PLAYER_XP is PRIVATE, only our own avatar's), but the live API is unit-tokened:
-    // it returns the values only for the "player" token and 0 for any other unit — faithfully, no
-    // creature/other player exposes XP. `0` until the app's feed lands (SetMinMaxValues clamps).
+    // UnitXP/UnitXPMax(unit): `PLAYER_XP` is a private field, so only `"player"` has a value and
+    // any other token answers 0.
     let is_player = |token: &Option<String>| token.as_deref() == Some("player");
     g.set(
         "UnitXP",
@@ -1186,19 +871,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitIsCharmed(unit) → 1 while somebody is charming this unit, else nil (`0x516cf0`).
-    //
-    // Three details, all byte-verified, none of them what a reimplementation reaches for:
-    //  · the predicate is `UNIT_FIELD_CHARMEDBY != 0` — a plain 64-bit non-zero test on fields
-    //    10/11 — **not** a `UNIT_FIELD_FLAGS` bit, which is the obvious guess for a boolean-shaped
-    //    unit question;
-    //  · a hit is the NUMBER 1 (`lua_pushnumber`, tag 3) and a miss is `nil` (tag 0) — never
-    //    `true`/`false`, and never `0`. Exactly one value on both arms;
-    //  · it is ASYMMETRIC. The field is "who charms me", so the CHARMER reads nil and the charmed
-    //    unit reads 1. `UnitIsPossessed` does not exist in 5875 at all — this is the only
-    //    charm verb in the API.
-    //
-    // KLHThreatMeter is the corpus addon blocked on it (`KTM_My.lua:533`); seven others name it.
+    // UnitIsCharmed(unit) (`0x516cf0`): `UNIT_FIELD_CHARMEDBY` is nonzero, not a flags bit, so the
+    // charmed unit answers 1 and its charmer nil. 1.12 has no `UnitIsPossessed`.
     g.set(
         "UnitIsCharmed",
         lua.create_function(|lua, token: Option<String>| {
@@ -1206,8 +880,6 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetMoney() → the player's purse in copper (a player-level global, not a unit token). The coin
-    // display + the merchant window's money line read it; `0` until the app's coinage feed lands.
     g.set(
         "GetMoney",
         lua.create_function(|lua, ()| {
@@ -1216,29 +888,10 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetComboPoints() → the player's banked combo points, 0..5 (a player-level global, not a unit
-    // token — the 1.12 binding takes no arguments). `ComboFrame` shows/hides on it, and the
-    // combat-text COMBO_POINTS arm reads it.
-    //
-    // TWO gates before the byte, transcribed from `0x51a190` (decision 0875) — the
-    // reference `ComboFrame.lua` carries no class check at all, so BOTH of them live here or
-    // nowhere:
-    //
-    //   51a1c3  mov eax,[esi+0x110]; mov al,[eax+0x79]   ; the class byte
-    //   51a1cc  cmp al,4 / cmp al,0xb → jne push 0.0     ; ROGUE or DRUID, nothing else
-    //   51a1f3  edx=[esi+0xe68]; eax=[edx+0x838] …0x83c  ; PLAYER_FIELD_COMBO_TARGET
-    //   51a205  cmp against [0xb4e2d8]/[0xb4e2dc]        ; == the CURRENT target, or push 0.0
-    //   51a234  mov al,[ecx+0x1029]                      ; only now, PLAYER_FIELD_BYTES byte 1
-    //
-    // The class gate is why a *warrior* never sees a dot even though the server really does bank a
-    // point for them on a victim's dodge: that byte reaches the usable walk's leg 5 (which has no
-    // class test, and is what greys Overpower — 0869) but stops here, before any UI can see it.
-    // The target gate is why combo points read as "per target": re-targeting empties the dots
-    // without the count moving, and selecting the banked unit again refills them.
-    //
-    // Both comparisons are the binary's own plain equality — no null special case. With nothing
-    // banked and no target both GUIDs are 0, which passes the target gate and reads a byte that is
-    // 0 anyway; the server writes and clears the pair together.
+    // GetComboPoints() (`0x51a190`): `PLAYER_FIELD_BYTES` byte 1, behind two gates stock
+    // `ComboFrame.lua` does not repeat: the class is rogue or druid (`0x51a1cc`), so a warrior's
+    // dodge point never shows, and `PLAYER_FIELD_COMBO_TARGET` equals the current target
+    // (`0x51a205`), so the points read per target. Both are plain equality, GUID 0 included.
     g.set(
         "GetComboPoints",
         lua.create_function(|lua, ()| {
@@ -1255,18 +908,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The rest-state trio (decisions 1082/1087) — player-level globals over the app's rest feed
-    // ([`UiScript::set_rest_state`]), the MainMenuBar exhaustion tick's and the player frame's
-    // whole wire: the surface is Exhaustion.dbc DATA, not client constants — the rows live in the
-    // model ([`UiScript::set_exhaustion_rows`]; shipped-table fallback).
-    //
-    // GetRestState() → (stateID, stateName, multiplier) — `0x48d350`: the raw `PLAYER_BYTES_2`
-    // byte 3 indexes Exhaustion.dbc DIRECTLY (the `[0xc0dd78]` ID→row array) and the triple is
-    // `(row.ID, row.name[locale], row.factor)`: 1 → (1, "Rested", 2.0), 2 → (2, "Normal", 1.0),
-    // and FrameXML's dead 3..5 branches map to the real beta rows (XXXTired 1.0/0.5,
-    // XXXExhausted 0.25). Every failure — byte 0 (pre-feed), byte past the table, no row —
-    // returns (nil, nil, nil), the binary's own fail path. The multiplier is what
-    // `EXHAUST_TOOLTIP1` renders ×100 ("200% of normal experience").
+    // GetRestState() (`0x48d350`) → the Exhaustion.dbc row's ID, name and factor, indexed directly
+    // by `PLAYER_BYTES_2` byte 3 (`0xc0dd78`); nil, nil, nil when there is no such row.
     g.set(
         "GetRestState",
         lua.create_function(|lua, ()| {
@@ -1281,15 +924,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             })
         })?,
     )?;
-    // GetXPExhaustion() → the rested span in BAR-XP units — `0x48d3f0`: the u32 pool × the f32
-    // factor of **Exhaustion.dbc row ID 1, hard-coded** (`[[0xc0dd78]+4]`, whatever the current
-    // state) — 2.0 in the shipped data, which is the whole "rested XP is double" law: the server
-    // drains the pool 1:1 against BASE kill XP while granting +100% (vmangos `GetXPRestBonus`),
-    // and the client scales by exactly this row's factor. **nil is decided by the rest-state
-    // byte, never by the pool** (`0x48d43b dec/jne`): byte ≠ 1 → nil whatever the pool holds
-    // (vmangos's 0 < bonus ≤ 10 hysteresis window sends byte 2 with a nonzero pool — nil there),
-    // and a rested byte with pool 0 → the NUMBER 0. The tick parks at `currXP + this`
-    // (`ExhaustionTick_Update`).
+    // GetXPExhaustion() (`0x48d3f0`): the rested pool times the factor of Exhaustion.dbc row 1
+    // whatever the state (2.0 shipped). Nil unless the rest byte is 1 (`0x48d43b`), whatever the
+    // pool holds, so a rested byte with an empty pool answers 0.
     g.set(
         "GetXPExhaustion",
         lua.create_function(|lua, ()| {
@@ -1302,9 +939,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             })
         })?,
     )?;
-    // IsResting() → 1/nil: inside a rest area (inn/city) right now — `0x516ea0`, byte-VERIFIED:
-    // PLAYER_FLAGS `shr 5; test 1` = bit 0x20, pushed as the NUMBER 1.0 or nil (the Lua-vanilla
-    // predicate shape, not a boolean). The player frame's flashing zzz reads exactly this.
+    // IsResting() (`0x516ea0`): `PLAYER_FLAGS` bit 0x20, in a rest area.
     g.set(
         "IsResting",
         lua.create_function(|lua, ()| {
@@ -1312,12 +947,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(flag(model.resting))
         })?,
     )?;
-    // PartialPlayTime() / NoPlayTime() → 1/nil: the two anti-addiction play-time regimes, read
-    // straight off `PLAYER_FLAGS` — `0x48eb70` is `shr eax,0xc; and al,1` (bit 12) and `0x48ebe0`
-    // its bit-13 neighbour (decision 1746, which carved both while establishing that bit 0x1000 is
-    // PARTIAL_PLAY_TIME on 5875 rather than the pre-1.6.1 CAN_SELF_RESURRECT). Same Lua-vanilla
-    // predicate shape as `IsResting` above: the NUMBER 1 or nil, never a boolean. Stock
-    // `PlayerFrame_UpdatePlaytime` (PlayerFrame.lua:244) is the only FrameXML caller of either.
+    // PartialPlayTime()/NoPlayTime(): the play-time limit flags, `PLAYER_FLAGS` bits 0x1000
+    // (`0x48eb70`) and 0x2000 (`0x48ebe0`).
     g.set(
         "PartialPlayTime",
         lua.create_function(|lua, ()| {
@@ -1332,19 +963,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(flag(model.no_play_time))
         })?,
     )?;
-    // GetBillingTimeRested() → the account's rested billing MINUTES, as one number, always
-    // (decision 1820; binding `0x48ec50`, byte-VERIFIED). The body has no `jcc` at all and ends in
-    // an unconditional `mov eax,1`, and both callees are branchless and call-free — so it can never
-    // return nil and never return zero values, which is why this is not the `Value::Nil` shape its
-    // neighbours use. The engine applies NO conversion: `0x48ec5e` is a bare unsigned u32→double
-    // push, so "minutes" is the server's convention, corroborated by stock `PlayerFrame.lua:246`
-    // dividing by 60 against `REQUIRED_REST_HOURS = 5`.
-    //
-    // Against vmangos this reads 0, because the server hardcodes `uint32(0)` for the field
-    // (`World.cpp:331`). It is fed from the wire rather than pinned to a constant so a server that
-    // populates it is reported honestly. Note the reference only ever reaches this call from
-    // INSIDE `if PartialPlayTime() ... elseif NoPlayTime()`, so with those bits clear stock
-    // FrameXML never calls it — it has to exist for the file to load, and is off the live path.
+    // GetBillingTimeRested() (`0x48ec50`): always one number, unconverted (`0x48ec5e`); stock
+    // `PlayerFrame.lua:246` reads it as minutes. vmangos always sends 0 (`World.cpp:331`).
     g.set(
         "GetBillingTimeRested",
         lua.create_function(|lua, ()| {
@@ -1352,18 +972,14 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(Value::Number(f64::from(model.billing_time_rested)))
         })?,
     )?;
-    // GetTimeToWellRested() → nil, always — `0x48d4b0`, byte-VERIFIED: the whole binding is 11
-    // bytes, `pushnil; return 1`. FrameXML's EXHAUST_TOOLTIP4 countdown branch is dead in 5875.
+    // GetTimeToWellRested(): always nil; the reference's binding (`0x48d4b0`) only pushes nil.
     g.set(
         "GetTimeToWellRested",
         lua.create_function(|_, ()| Ok(Value::Nil))?,
     )?;
 
-    // TargetUnit(unit) — select a unit by token (the reference's `TargetUnit` Lua shim → SetSelection;
-    // the caller here is `PlayerFrame_OnClick`'s left-click branch → `TargetUnit("player")`, and the
-    // TARGETSELF binding). Queues the raw token; the app resolves it to a streamed entity and commits
-    // the selection. A nil/absent unit is ignored, as is any token the app can't resolve — the real
-    // client no-ops `TargetUnit` on a unit that doesn't exist.
+    // TargetUnit(unit): queue the token for the app to resolve and select; a token naming no unit
+    // is a no-op, as in the reference.
     g.set(
         "TargetUnit",
         lua.create_function(|lua, token: Option<String>| {
@@ -1375,30 +991,11 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // AssistUnit(unit) — select the *token's own* target (`0x489b80`). The ASSISTTARGET binding's
-    // body is `AssistUnit("target")`, and `/assist`'s bare form is the same call.
-    //
-    // The shared assist tail (`0x489bb2`–`0x489c07`, byte-identical to `AssistByName`'s) is three
-    // steps and no more: read `UNIT_FIELD_TARGET` off the basis (`[[obj+0x110]+0x28]`), bail
-    // **silently** if it is zero, then hand the guid to the select-if-resolves helper `0x489a40`.
-    // Four things it deliberately is not:
-    //
-    //  * **not gated by `CanAssist`** — a whole-binary census of the 25 `call 0x6066f0` sites puts
-    //    none of them on this path (VERIFIED negative), so `AssistUnit("target")` on a hostile
-    //    creature assists it, and that is the common case in play.
-    //  * **not players-only** — unlike `AssistByName`'s typemask `0x10`, the token resolver takes
-    //    whatever the token names.
-    //  * **not a deselect on failure** — an unresolvable token, a basis with no target, and a
-    //    target that is not streamed all leave the current selection exactly where it was
-    //    (`0x489a40`'s arm 3 is a bare `ret`).
-    //  * **not an attack** — the tail's swing leg is gated on the `assistAttack` CVar, whose
-    //    registered default is `"0"` (VERIFIED at the registration bytes `0x48fc50`). Stock assist
-    //    selects and does not swing; the leg becomes reachable only if benilla grows the CVar.
-    //
-    // A nil/absent unit is ignored here rather than queued, like `TargetUnit`'s: the reference
-    // emits game-message `0xb8` for the token it cannot parse, and that id→string table is
-    // runtime-populated BSS, not statically recoverable — the same known deviation
-    // `TargetByName` already carries, and silence is better than an invented line.
+    // AssistUnit(unit) (`0x489b80`): select the unit's `UNIT_FIELD_TARGET`. The shared tail
+    // (`0x489bb2`-`0x489c07`) returns silently on 0 and selects through `0x489a40`, which leaves
+    // the selection alone when nothing resolves; no `CanAssist` gate (`0x6066f0`), any unit, and a
+    // swing only with `assistAttack` set (default "0", `0x48fc50`). Deviation: a nil token is
+    // silent, because the reference's game message `0xb8` for it has no recoverable text.
     g.set(
         "AssistUnit",
         lua.create_function(|lua, token: Option<String>| {
@@ -1412,14 +1009,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // TargetLastEnemy() — re-select the last **attackable** unit that was targeted (`0x489b45`
-    // reads the pair `[0xb4e2e8]/[0xb4e2ec]`, which `SetSelection 0x493540` stamps at `0x49377d`
-    // alongside the plain last-target pair `TargetLastTarget` reads). The TARGETLASTHOSTILE
-    // binding (default `G`) is its only shipped caller.
-    //
-    // Takes no argument and routes through the same select-if-resolves helper, so a remembered
-    // guid whose unit has since streamed out is a silent no-op rather than a deselect. The app
-    // owns the memory itself (`crate::target::scan`'s `LastEnemy`) — the VM holds no guids.
+    // TargetLastEnemy(): re-select the last attackable target (`0x489b45` reads `0xb4e2e8`, which
+    // `SetSelection` stamps at `0x49377d`), a no-op once it has streamed out. The app remembers it.
     g.set(
         "TargetLastEnemy",
         lua.create_function(|lua, ()| {
@@ -1429,18 +1020,10 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // TargetNearestFriend([reverse]) — the friendly half of the TAB scan. `0x489aa0` is
-    // byte-for-byte `TargetNearestEnemy`'s shim with one changed immediate: both fetch the
-    // optional Lua arg #1 as the reverse flag (`0x6f1c10`, default 0) and call the one cycler
-    // `0x493f60(ecx = reverse, edx = mode)` — `edx = 1` for enemy, **`2` for friend** (3 and 4 are
-    // the party and raid siblings). Everything downstream is the same code; only the
-    // per-candidate filter `0x493e40` forks on the mode, and mode 2's arm (`0x493eca`) is
-    // `CanAssist(player, cand)` then `UNIT_FIELD_HEALTH > 0`.
-    //
-    // TARGETNEARESTFRIEND (`CTRL-TAB`) calls it bare; TARGETPREVIOUSFRIEND (`CTRL-SHIFT-TAB`)
-    // calls `TargetNearestFriend(1)` — 1.12's own `Bindings.xml` comments the argument
-    // `-- 1 (or "true") means reverse!`, so the truthiness test below takes a number OR a boolean.
-    // A numeric 0 is forward, matching `0x6f1c10`'s "absent == 0" reading.
+    // TargetNearestFriend([reverse]) (`0x489aa0`): the Tab cycler `0x493f60` in mode 2 (enemy is
+    // 1), whose filter (`0x493eca`) wants `CanAssist` and health above 0. Argument 1 reverses
+    // (`0x6f1c10`, absent is 0); stock `Bindings.xml` says "1 (or "true")", so a number or a
+    // boolean reverses.
     g.set(
         "TargetNearestFriend",
         lua.create_function(|lua, reverse: Option<Value>| {
@@ -1456,41 +1039,20 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // TargetByName(name [, exactMatch]) — select by NAME through the shared resolver `0x493aa0`
-    // (`0x489d60`). The app already owns that resolver for `/target` (decision 0886,
-    // `crate::target::by_name`); this is the binding half, which 11 corpus addons call and the
-    // slash command bypassed.
-    //
-    // The four things this signature is not:
-    //
-    //  * **not exact by default** — tier 1 is a whole-string case-insensitive compare, tier 2 is
-    //    the longest common PREFIX (anchored at 0, never a substring), and tier 2 is live
-    //    whenever Lua arg #2 is absent or 0. `TargetByName("Rag")` selects Ragnaros.
-    //  * **not nearest** — a tier-1 hit returns 0 from the walk callback and *terminates the
-    //    enumeration*, so among whole-string matches the winner is the first in enumeration
-    //    order, not the closest. Our resolver ranks exact-then-longest-prefix-then-nearest
-    //    instead; the deviation and its cost are argued at length in `by_name`'s module header,
-    //    which is the one place to change if that judgement is ever reversed.
-    //  * **not players-only** — typemask 8 is UNIT, i.e. creatures *and* players (contrast
-    //    `AssistByName`/`FollowByName`, which pass `0x10`). And with filter mode 0 there is no
-    //    dead, reaction, attackability, range, cone or scene-attach gate, and **no
-    //    self-exclusion**: `TargetByName(UnitName("player"))` self-targets.
-    //  * **not silent on a miss** — the reference emits game-message `0x127` (named, nothing
-    //    matched) or `0xb8` (null/empty name) and leaves the current target untouched. We keep
-    //    the target untouched and say nothing: the id→string table is runtime-populated BSS that
-    //    cannot be statically recovered, and inventing a line is worse than omitting one.
-    //    Same known deviation the slash path already carries.
-    //
-    // A missing or wrong-typed first argument RAISES (`0x489d69 call 0x6f3510` → `0x489de1` →
-    // `0x6f4940`, usage literal `0x842698`); a number is accepted and stringified.
+    // TargetByName(name [, exactMatch]) (`0x489d60`, resolver `0x493aa0`, shared with `/target`): a
+    // case-insensitive whole-name match wins, else without `exactMatch` the longest common prefix,
+    // so "Rag" selects Ragnaros. Any unit (typemask 8), no dead, reaction, range or self gate. A
+    // missing name, or one neither string nor number, raises `Usage:` (`0x489d69`, `0x6f4940`); a
+    // number is taken as its string. Deviation: among whole-name matches ours picks the nearest,
+    // because the reference's first-walked pick is order-dependent and reads as a bug. Deviation: a
+    // miss is silent, because the reference's game messages `0x127` and `0xb8` have no statically
+    // recoverable text.
     g.set(
         "TargetByName",
         lua.create_function(|lua, (name, exact): (Value, Option<Value>)| {
             let name =
                 super::super::binding_abi::string_arg(lua, name, "Usage: TargetByName(\"name\")")?;
-            // Arg #2 is fetched with `0x6f1c10(idx=2, default 0)` — it never raises, and a
-            // numeric 0 is the same as absent. Matches `FollowByName`'s reading of its own
-            // arg #2, which reaches the identical `ctx+0x0c` slot.
+            // Argument 2 comes from `0x6f1c10` with default 0: it never raises, and 0 is absent.
             let exact = match exact {
                 None | Some(Value::Nil) | Some(Value::Boolean(false)) => false,
                 Some(Value::Integer(n)) => n != 0,
@@ -1503,16 +1065,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // DropItemOnUnit(unit) — drop the cursor's held item onto a unit (`0x48d960`). Two legs in the
-    // reference: the PET leg feeds the pet, the PLAYER leg opens a trade. Queues the raw token and
-    // nothing else — every gate reads state this VM does not hold, so the app owns all of them
-    // (`ui_action::drop_item`).
-    //
-    // This binding **existed in our shipped `PetFrame_OnClick` before it existed here**: the
-    // handler transcribed the reference's three legs faithfully, and the middle one called a nil
-    // global, so the whole handler errored out the moment you clicked your pet holding anything.
-    // That is B208's "dropping food onto the pet doesn't feed" — the reported bug was a missing
-    // registration, not a missing mechanism.
+    // DropItemOnUnit(unit) (`0x48d960`): drop the cursor's item on a unit, feeding a pet or
+    // opening a trade with a player. Only the token is queued; the app runs every gate.
     g.set(
         "DropItemOnUnit",
         lua.create_function(|lua, token: Option<String>| {
@@ -1524,28 +1078,16 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SpellTargetUnit(unit) — bind a unit to the spell awaiting its click. The other leg of
-    // `PetFrame_OnClick`, tested BEFORE `CursorHasItem()` (ref `PetFrame.lua:114-129`), and dead
-    // in our VM for the same reason `DropItemOnUnit` was.
-    //
-    // It is registered as an accepted **no-op**, deliberately, and that is faithful for every word
-    // benilla can currently arm: the targeting cursor models the location / item / gameobject
-    // seams (0792/0923/0939), and a *unit* cannot satisfy any of them — the reference's
-    // `BindTarget 0x6e5b40` would reject it at the same three mask tests our seams ask. The word
-    // that would make this do something is the residual unit-word machine that `cast_target`'s
-    // header names as still deferred (a unit-target spell never enters targeting mode here at all;
-    // it resolves to `CastWireTarget::Unit` or refuses). So: present, silent, and honest — what it
-    // must NOT be is absent, which is what took the handler down with it.
+    // SpellTargetUnit(unit): a no-op. A unit-target spell never enters targeting mode here, and for
+    // the location, item and gameobject modes this client arms, the reference's `BindTarget`
+    // (`0x6e5b40`) rejects a unit too. Stock `PetFrame_OnClick` calls it, so it must exist.
     g.set(
         "SpellTargetUnit",
         lua.create_function(|_, _token: Option<String>| Ok(()))?,
     )?;
 
-    // ClearTarget() — drop the current selection (the reference API returns 1 when it cleared,
-    // nil when there was nothing to clear; `ToggleGameMenu`'s ESC chain depends on the nil to
-    // fall through to opening the menu). Reads the same per-token store `UnitExists("target")`
-    // answers from; the app commits the actual deselect (SetSelection guid 0 + the engaged
-    // attack-stop) from the drained trigger.
+    // ClearTarget(): 1 when it cleared a target, nil when there was none, which `ToggleGameMenu`'s
+    // Escape chain needs to fall through to the menu. The app commits the deselect.
     g.set(
         "ClearTarget",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/unit/mod.rs b/crates/benilla-ui/src/script/unit/mod.rs
index de29dbe7..212898d1 100644
--- a/crates/benilla-ui/src/script/unit/mod.rs
+++ b/crates/benilla-ui/src/script/unit/mod.rs
@@ -1,175 +1,75 @@
-//! The game-state `Unit*` bindings (decision 0068 §3) — the first slice of the addon-facing API that
-//! reads *live game state*, and the seam that keeps this crate engine-free while doing so.
-//!
-//! The engine must not touch the ECS/net (decisions 0006/0061: the codec is stateless, the ECS owns
-//! state). So instead of reaching outward, the app pushes a per-frame **unit snapshot** into the VM
-//! via [`UiScript::set_unit`], and the `Unit*` globals here read that plain data. A frame's
-//! `UnitHealth("player")` therefore resolves against a [`UnitState`] the Bevy side deposited that
-//! frame — the same shape a real addon sees, with none of the coupling.
-//!
-//! Return shapes follow the reference: `UnitName` returns the name *or nil*;
-//! `UnitHealth`/`UnitHealthMax`/`UnitLevel` return numbers (`UnitLevel` returns **−1** for a
-//! unit whose level "can't be told" — [`level_reads_unknown`], the target frame's skull gate);
-//! a unit that doesn't exist reports `UnitExists` nil and the numbers `0` (nil for the name),
-//! exactly as the client does for an absent unit token. Tokens (`"player"`, `"target"`, …) are opaque strings the host never
-//! interprets — the app decides what each maps to.
-//!
-//! **Every predicate in this family answers the number `1` or `nil`, never a Lua boolean**, and it
-//! answers it through the one helper — [`unit_predicate`], over
-//! [`super::binding_abi::flag`]. Decision 2043; the law is 1830's, which settled the same
-//! question for the widget predicates a family earlier.
-//!
-//! v1 gaps, stated not hidden: the snapshot carries only the *active* power slot (see the
-//! `UnitMana` note below); `UnitIsConnected`'s backing
-//! field defaults `false`, and no app-side feed sets it `true` for live units yet (decision 0434
-//! §2's party-frame predicates land the binding first, the feed follows — see the field doc).
+//! The `Unit*` bindings. The app pushes each token's [`UnitState`] every frame through
+//! [`UiScript::set_unit`], and the globals read that plain data, which keeps this crate free of
+//! the ECS. Every predicate answers the number `1` or nil, never a Lua boolean.
 
 use mlua::Lua;
 
 use super::Model;
 
-/// One queued **selection ask** from Lua, in call order — the app resolves it to a guid and
-/// commits it through the one SetSelection tail.
-///
-/// The three verbs share one queue because the reference shares one *function*: `TargetUnit`
-/// (`0x4899d0`), `AssistUnit` (`0x489b80`), `TargetLastEnemy` and `TargetLastTarget` all reach
-/// selection through the "select if it resolves" helper `0x489a40`, whose three arms are the same
-/// for every caller — resolve the guid and commit, else fall back to the group roster, else a
-/// **silent return**. Splitting them
-/// into a queue each would also lose their relative order, which a macro can observe
-/// (`TargetUnit("party1"); AssistUnit("target")` is not the same as the reverse).
+/// A selection ask from Lua, queued in call order for the app to resolve and commit. The reference
+/// routes `TargetUnit`, `AssistUnit` and `TargetLastEnemy` through one helper (`0x489a40`: commit,
+/// else the group roster, else a silent return), and a macro can observe their order.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum SelectionRequest {
-    /// `TargetUnit(unit)` — select the unit the token names.
+    /// `TargetUnit(unit)` (`0x4899d0`): the unit the token names.
     Unit(String),
-    /// `AssistUnit(unit)` — select the token's own `UNIT_FIELD_TARGET`; a basis with no target is
-    /// a silent no-op (the reference's shared assist tail bails before any send).
+    /// `AssistUnit(unit)` (`0x489b80`): the token's own `UNIT_FIELD_TARGET`; a token with no
+    /// target is a silent no-op that sends nothing.
     Assist(String),
-    /// `AssistByName(name)` (`0x489c40`) — the `/assist Bob` handler's verb: select what the
-    /// *named player* is targeting. A name, not a unit token, so it is the app's name→unit
-    /// resolution (`AssistRequest`) rather than `Assist`'s token walk.
+    /// `AssistByName(name)` (`0x489c40`), the `/assist <name>` verb: what the named player
+    /// targets, resolved by name rather than by token.
     AssistByName(String),
-    /// `TargetLastEnemy()` — select the last *attackable* unit that was committed.
+    /// `TargetLastEnemy()`: the last attackable unit committed.
     LastEnemy,
 }
 
-/// **The local player record — `0xc27d80`, ours** (decision 2263).
-///
-/// A copy of ONE `SMSG_CHAR_ENUM` `CHARACTER_INFO` row, and the source the reference answers four
-/// `"player"` verbs from. Each opens with the identical full-string, case-insensitive compare of
-/// the token against `0x847894` (`b"player\0"`) whose **match is the fall-through**, and each is
-/// unconditional — there is no arm that re-routes `"player"` to the unit resolver, so the
-/// descriptor never supersedes this record even once the object exists:
-///
-/// | verb | fast path | accessor | byte |
-/// |---|---|---|---|
-/// | `UnitName` `0x517020` | `0x51708c` | `0x5abdc0` | `+0x08` name |
-/// | `UnitRace` `0x518200` | `0x518269` | `0x5abdd0` | `+0x100` → `ChrRaces` |
-/// | `UnitClass` `0x518350` | `0x5183b9` | `0x5abde0` | `+0x101` → `ChrClasses` |
-/// | `UnitSex` `0x517e90` | `0x517ef9` | `0x5abdf0` | `+0x102` gender |
-///
-/// One writer image-wide — `0x5abd9e` (`rep movsd`, 0x44 dwords) inside `CGlueMgr::EnterWorld`,
-/// at the character-select commit — and **no instruction anywhere clears it**. It is filled before
-/// FrameXML loads and before `CMSG_PLAYER_LOGIN` is sent, which is why the reference can run addon
-/// `OnUpdate` (`0x765650`) for many frames with no local player object and still answer all four.
-///
-/// **`UnitLevel` is deliberately NOT here.** The record carries the level at `+0x108` and the
-/// client ships an accessor for it, `0x5abe00`, that **nothing calls** — so `UnitLevel("player")`
-/// reads the descriptor and answers `0` in exactly the window the four answer in.
-///
-/// **Resolved strings, not the raw bytes**, because this crate has no DBC: the reference resolves
-/// `+0x100`/`+0x101` through `ChrRaces`/`ChrClasses` at call time, and the app does that same
-/// resolution once when it seeds the record (it is the identical lookup
-/// `ui_unit::race_names`/`class_names` already does for the unit snapshot, so the two cannot
-/// disagree about what a race byte means).
+/// The reference's local player record (`0xc27d80`): a copy of the chosen `SMSG_CHAR_ENUM` row,
+/// written once at the Enter World commit (`0x5abd9e`) before FrameXML loads, and never cleared.
+/// `UnitName` (`0x517020`), `UnitRace` (`0x518200`), `UnitClass` (`0x518350`) and `UnitSex`
+/// (`0x517e90`) answer `"player"`, matched whole in any case, from it and never from the
+/// descriptor, so they answer before the player object exists. `UnitLevel` reads the descriptor:
+/// the record's level accessor (`0x5abe00`) has no caller. Race and class are held resolved, as
+/// this crate has no DBC.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct PlayerRecord {
-    /// `+0x08` — the NUL-terminated name buffer at `0xc27d88`. Empty is the record's only unset
-    /// state, and the reference's only `UnitName("player")` nil: `lua_pushstring(NULL)` at
-    /// `0x517095` tail-jumps into `lua_pushnil`. Unreachable from Lua in the real client, because
-    /// the verb is not registered until `UI_Init` and only an Enter World commit gets there.
+    /// `+0x08`, the name; empty is the unset record, whose `UnitName("player")` is nil
+    /// (`0x517095`).
     pub name: String,
-    /// `+0x100` resolved — `UnitRace`'s `(localized, file token)` pair, e.g.
-    /// `("Night Elf", "NightElf")`. `None` is the all-zero record: race 0 has no `ChrRaces` row,
-    /// and the reference's bound/NULL-row arms push `nil, nil` rather than reaching the resolver.
+    /// `+0x100` as `UnitRace`'s (localized, file token) pair; `None` is race 0, which has no
+    /// `ChrRaces` row and answers `nil, nil`.
     pub race: Option<(String, String)>,
-    /// `+0x101` resolved — `UnitClass`'s `(localized, UPPERCASE token)` pair, e.g.
-    /// `("Warrior", "WARRIOR")`. `None` for the all-zero record, same shape as [`Self::race`].
+    /// `+0x101` as `UnitClass`'s (localized, uppercase token) pair; `None` answers `nil, nil`.
     pub class: Option<(String, String)>,
-    /// `+0x102` on `UnitSex`'s scale (2 male, 3 female) — **not** the wire's 0/1.
-    ///
-    /// `0` is our unset marker and reads as `2`, which is not a fudge: `0x517ef9`'s accessor feeds
-    /// `fild [4*eax+0x808be4]` over `{2,3,1,6}` with **no bounds check at all**, so an all-zero
-    /// record answers `2` ("male") in the reference too. It is the one of the four with no
-    /// validity guard.
+    /// `+0x102` on `UnitSex`'s scale (2 male, 3 female), not the wire's 0/1. The unset 0 answers
+    /// 2, as the reference's all-zero record does: `0x517ef9` indexes `{2,3,1,6}` (`0x808be4`)
+    /// with no bounds check.
     pub sex: u8,
 }
 
-/// One unit-token's game-state snapshot, pushed by the app each frame and read by the `Unit*`
-/// bindings. Plain data (no mlua handles, no ECS types) — the engine-free seam decision 0068 §3
-/// draws between the app's net/ECS feed and the Lua API.
+/// One unit token's snapshot, pushed by the app each frame and read by the `Unit*` bindings;
+/// plain data, with no mlua handles or ECS types.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct UnitState {
-    /// Whether the unit exists (`UnitExists`). A token with no snapshot is treated as `false` too.
-    ///
-    /// **Stays TRUE for an out-of-range party member** — that is the whole point of the roster
-    /// fallback, and it is what separates this field from [`Self::has_object`].
-    ///
-    /// *Named gap, second order:* 1.12's `UnitExists 0x515fb0` is a **conjunction** — the object
-    /// lookup AND a virtual `[edx+0x58]` that resolves to `IsSelectable 0x60be60`
-    /// (`!(UNIT_FIELD_FLAGS & 0x02000000) || UNIT_FIELD_CREATEDBY == you`) — falling back to the
-    /// GUID-only roster test on a miss. We model the fallback and not the conjunct, so a
-    /// not-selectable unit created by someone else reads `exists` here and `nil` there. No corpus
-    /// caller reaches it; recorded rather than folded in.
+    /// `UnitExists`, true for an out-of-range party member through the roster fallback. The
+    /// reference (`0x515fb0`) also requires a held object to be selectable before that fallback
+    /// (`0x60be60`: `UNIT_FIELD_FLAGS & 0x02000000` clear, or created by us); that is not built.
     pub exists: bool,
-    /// **`UnitIsVisible` — the client holds a live object for this token, and nothing else.**
-    ///
-    /// The reference is 57 bytes with one branch (`0x516030`):
-    /// `ClntObjMgrObjectPtr(resolve(token), TYPEMASK_UNIT) != NULL`. Its body reads **zero** object
-    /// fields, makes **zero** comparisons beyond `test eax,eax`, and contains **zero** float
-    /// opcodes — so there is no distance term, no radius, no alpha/fade/interpolation flag and no
-    /// "known to the client" bit in it. Addons read it as a range gate because **the range test is
-    /// the server's**: `SMSG_DESTROY_OBJECT` and the OUT_OF_RANGE demotion unlink the object from
-    /// the manager index this query searches, so the client answers with the presence of the
-    /// object the server chose to send.
-    ///
-    /// Distinct from [`Self::exists`], and neither implies the other. The one that matters here:
-    /// an out-of-range party member is `exists == true`, `has_object == false` — which is exactly
-    /// pfUI's `if not UnitIsVisible(unitstr) or not UnitIsConnected(unitstr)` portrait branch.
-    ///
-    /// The app already computed this and did not publish it: `ui_party::feed`'s
-    /// `member_unit_state` takes `store: Option<&ObjectStore>` and its own comment calls that
-    /// argument "the reference's `0x468460`". Every snapshot built from a live store sets it
-    /// (`ui_unit::snapshot`); the roster-record leg and a token with no snapshot leave it `false`.
-    ///
-    /// **One presence field serves three verbs** — `UnitIsVisible`, and the object-presence
-    /// conjunct of both tapped predicates below.
+    /// `UnitIsVisible` (`0x516030`): the client holds an object for this token, and nothing more;
+    /// the range test is the server's, which drops out-of-range objects. Not [`Self::exists`]: an
+    /// out-of-range party member exists without an object.
     pub has_object: bool,
-    /// `UnitIsTapped` — `UNIT_DYNAMIC_FLAGS` (UpdateField **143**) bit `0x4`: this unit is
-    /// someone's kill credit. `0x519c90` is `test BYTE PTR [eax+0x224],0x4` behind the same
-    /// object-presence check [`Self::has_object`] carries, and **nothing else** — no ownership, no
-    /// GUID compare, no party/raid or health conjunct anywhere in the body.
-    ///
-    /// Set only on the live-descriptor leg, so an out-of-range unit reads `false` — which is the
-    /// object-presence conjunct, for free, by the same route `has_object` gets it.
+    /// `UnitIsTapped` (`0x519c90`): `UNIT_DYNAMIC_FLAGS` (field 143) bit `0x4`, someone holds the
+    /// kill credit. Set only from a live descriptor, which supplies the reference's
+    /// object-presence check.
     pub tapped: bool,
-    /// **`UnitIsPartyLeader`'s FIRST leg** — the server's `PLAYER_FLAGS & 0x1` on this unit's own
-    /// descriptor, restricted to players (`TYPEMASK_PLAYER`, `0x10` — **not** this family's usual
-    /// `8`, which is the one difference the predicate makes to the object lookup).
-    ///
-    /// Not derived client-side, and not the same question as "leads MY group": it is true for a
-    /// stranger who leads their own party, which no comparison against our group's leader GUID can
-    /// express. The second leg is that comparison, in `script::party` — the two cover disjoint
-    /// failures and the reference ORs them (`0x516210`).
+    /// `UnitIsPartyLeader`'s first leg: `PLAYER_FLAGS & 0x1` on a player's own descriptor, true
+    /// for a stranger leading their own party. The reference (`0x516210`) ORs it with a compare
+    /// against our group leader's guid.
     pub group_leader: bool,
-    /// `UnitIsTappedByPlayer` — the same field's bit `0x8` (`0x519d00`, a masked-byte clone of its
-    /// sibling: 108 bytes each, differing only in the mask and the `Usage:` string).
-    ///
-    /// Read as a **pair**: `tapped && !tapped_by_player` is "someone else's kill", which is the
-    /// grey-bar condition unit-frame addons draw (pfUI `api/unitframes.lua:2012`).
+    /// `UnitIsTappedByPlayer` (`0x519d00`): the same field's bit `0x8`. Tapped without it is
+    /// someone else's kill, the grey unit frame.
     pub tapped_by_player: bool,
-    /// The unit's name (`UnitName` → the string, or nil). `None` while the app's name-query cache
-    /// hasn't answered (or the server doesn't know the unit).
+    /// `UnitName`'s name; `None` until the name query answers, which reads as [`unknownobject`].
     pub name: Option<String>,
     /// Current health (`UnitHealth`).
     pub health: u32,
@@ -177,302 +77,131 @@ pub struct UnitState {
     pub max_health: u32,
     /// Level (`UnitLevel`).
     pub level: u32,
-    /// The active power type (`UnitPowerType`): `0` mana, `1` rage, `2` focus, `3` energy,
-    /// `4` happiness — the descriptor's `UNIT_FIELD_BYTES_0` byte 3.
+    /// The active power type (`UnitPowerType`), `UNIT_FIELD_BYTES_0` byte 3: 0 mana, 1 rage,
+    /// 2 focus, 3 energy, 4 happiness.
     pub power_type: u8,
     /// Current power of the active type (`UnitMana`).
     pub power: u32,
     /// Maximum power of the active type (`UnitManaMax`).
     pub max_power: u32,
-    /// Whether the unit is dead (`UnitIsDead`). NB a released ghost is NOT dead by this
-    /// predicate — its wire health is 1 (decision 0308 §1); the trio is dead / [`Self::ghost`] /
-    /// dead-or-ghost, the real client's three tests.
+    /// `UnitIsDead`; a released ghost is not dead by it, as its health is 1.
     pub dead: bool,
-    /// Whether somebody is charming this unit (`UnitIsCharmed`).
-    ///
-    /// **`UNIT_FIELD_CHARMEDBY != 0`, and the asymmetry is the fact worth keeping.** The binding
-    /// `0x516cf0` reads fields 10/11 as one 64-bit value and tests it non-zero — not a
-    /// `UNIT_FIELD_FLAGS` bit, and not a comparison against the player (its body contains no `cmp`
-    /// at all). The field means *"who charms me"*; its mirror `UNIT_FIELD_CHARM` (*"whom I charm"*)
-    /// is never read here. So a **charmer** answers nil, a **charmed** pet answers 1, and an
-    /// ordinary **summoned** pet answers nil — `"pet"` is itself charm-else-summon in the resolver.
+    /// `UnitIsCharmed` (`0x516cf0`): `UNIT_FIELD_CHARMEDBY` (fields 10-11) is non-zero.
+    /// `UNIT_FIELD_CHARM` is never read, so a charmer answers nil, as does a summoned pet.
     pub charmed: bool,
-    /// Whether the unit is a released ghost (`UnitIsGhost` — `PLAYER_FLAGS` bit 0x10, decision
-    /// 0308 §1). Only meaningful for player tokens; creatures stay `false`.
+    /// `UnitIsGhost`: `PLAYER_FLAGS` bit `0x10`, so players only.
     pub ghost: bool,
-    /// The unit's reaction toward the player on the `UnitReaction` scale (`1` hated … `4` neutral …
-    /// `8` exalted; `0` = unknown → `UnitReaction` returns nil). The app resolves it from the
-    /// faction-template / reputation decode (the same one the selection ring uses) for the `"target"`
-    /// token; other tokens leave it `0`. Read by `UnitReaction`, which the target frame tints its
-    /// name plate by (`TargetFrame_CheckFaction`).
+    /// The reaction toward the player on `UnitReaction`'s scale, 1 hated to 8 exalted, 0 unknown
+    /// (nil). Fed for the tokens naming another unit; `"player"` and `"pet"` stay 0.
     pub reaction: u8,
-    /// The unit's localized race display name (`UnitRace`'s first return, e.g. "Night Elf").
-    /// `None` = unknown (the race byte hasn't streamed, or a raceless creature) → `UnitRace`
-    /// returns nil, nil. The app resolves it from `UNIT_FIELD_BYTES_0` byte 0 (decision 0208 §3).
+    /// `UnitRace`'s localized first return, from `UNIT_FIELD_BYTES_0` byte 0; `None` answers
+    /// `nil, nil`.
     pub race: Option<String>,
-    /// The race's file/token name (`UnitRace`'s second return, e.g. "NightElf" — 1.12's 8 races),
-    /// the shape texture-path splices key on.
+    /// `UnitRace`'s second return, the file token (`"NightElf"`) texture paths are built from.
     pub race_file: Option<String>,
-    /// The unit's localized class display name (`UnitClass`'s first return, e.g. "Warrior").
+    /// `UnitClass`'s localized first return.
     pub class: Option<String>,
-    /// The class's file name (`UnitClass`'s second return): the **uppercase** token ("WARRIOR")
-    /// the ref's stat-tooltip lookups key on (`getglobal(strupper(class).."_STAT_TOOLTIP")` —
-    /// the ref uppercases it again defensively; we store it already uppercase).
+    /// `UnitClass`'s second return, the uppercase token (`"WARRIOR"`).
     pub class_file: Option<String>,
-    /// This unit's INVSLOT 17 is a **relic** slot rather than a ranged-weapon slot —
-    /// `UnitHasRelicSlot`'s whole answer (`0x519e50`).
-    ///
-    /// Resolved app-side off `ChrClasses.dbc` field 16, for the same reason [`Self::class_file`]
-    /// is resolved app-side: it is a static per-class column of a table this crate cannot read.
-    /// The reference gates on TYPEMASK_PLAYER before it looks at the class byte, so the feed sets
-    /// this only for a player — a creature, a pet and an unstreamed unit all leave it `false`,
-    /// which is the nil leg.
-    ///
-    /// True for exactly Paladin, Shaman and Druid in 1.12 (Libram, Totem, Idol). It was believed
-    /// here for a long time that no 1.12 class had one; see decision 1796 for how that survived.
+    /// `UnitHasRelicSlot` (`0x519e50`): INVSLOT 17 is a relic slot, from `ChrClasses.dbc` field
+    /// 16. Players only, true for Paladin, Shaman and Druid.
     pub has_relic_slot: bool,
-    /// The unit's sex on the `UnitSex` scale: `2` male, `3` female (`1` = neuter/unknown). `0`
-    /// (the unfilled default) reports as nil — the API's "can't tell", like [`Self::reaction`].
-    /// The app maps `UNIT_FIELD_BYTES_0` byte 2 (0 male / 1 female) onto this shape.
+    /// `UnitSex`'s scale, 2 male and 3 female, from `UNIT_FIELD_BYTES_0` byte 2 (0 male, 1
+    /// female). The unfilled 0 answers 2, the reference's unresolved answer (`0x517f9f`).
     pub sex: u8,
-    /// This token is a PLAYER character (guid family) — the unit tooltip's level line renders
-    /// "Race Class (Player)" instead of the creature type (decision 0276's verified law).
+    /// `UnitIsPlayer`: a player character by guid, whose tooltip level line shows race and class.
     pub is_player: bool,
-    /// This token is **player-CONTROLLED** — `UNIT_FIELD_FLAGS` bit 3
-    /// (`UNIT_FLAG_PVP_ATTACKABLE 0x8`, behaviourally "player-controlled"; the same bit
-    /// `target::relations::ring_reaction`'s duel leg selects on). Wider than
-    /// [`Self::is_player`]: a player's pet and a charmed creature are player-controlled without
-    /// being players, which is exactly the distinction stock `UnitFrame_OnEnter`
-    /// (UnitFrame.lua:58) needs when it decides whether the hovered plate gets the
-    /// player-options newbie tip. `UnitIsPlayer`'s note used to call this reach a gap we did not
-    /// carry; the unit-frame migration is what closed it.
+    /// `UnitPlayerControlled` (`0x516410`): `UNIT_FIELD_FLAGS` bit `0x8`, which a player's pet
+    /// and a charmed creature carry as well as a player.
     pub player_controlled: bool,
-    /// `UNIT_FIELD_FLAGS`, raw — what `UNIT_FLAGS` fires on (the app's `fire_transitions`); the
-    /// three readings above are bits of it.
+    /// `UNIT_FIELD_FLAGS`, raw: `UnitIsPlusMob` reads bit `0x40`, and `UNIT_FLAGS` fires when it
+    /// moves.
     pub flags: u32,
-    /// `PLAYER_FLAGS` (descriptor index 190), raw — what **`PLAYER_FLAGS_CHANGED`** fires on, the
-    /// [`Self::flags`] pattern one field over. `0` on a creature, which has no PLAYER block.
-    ///
-    /// The reference watches this dword type-wide over TYPEID_PLAYER (`0x468070(ecx=4, edx=8,
-    /// width 4)` registered at `0x5e25d7`), and its handler `0x5ee990` fires the event from
-    /// `0x5eea35`-`0x5eea3d` — **unguarded by any bit test, and above the local-player GUID gate
-    /// at `0x5eea93`** — so *any* bit moving on *any* player announces itself, remote players
-    /// included. Decision 2078.
-    ///
-    /// Raw, not a decoded subset, and that is the point: [`Self::group_leader`] (`0x1`) and
-    /// [`Self::ghost`] (`0x10`) are the only bits this struct decodes, while `0x2`/`0x4` (the
-    /// chat AFK/DND flags), `0x8` (GM), `0x200` (PvP-desired), `0x400`/`0x800` (hide helm/cloak)
-    /// and `0x1000`/`0x2000` (the play-time regimes) all move without touching either. Firing off
-    /// the decoded pair would silently under-announce every one of them.
+    /// `PLAYER_FLAGS` (field 190), raw, 0 on a creature. `PLAYER_FLAGS_CHANGED` fires when any
+    /// bit moves on any player, remote ones included: the reference's handler (`0x5ee990`) fires
+    /// before any bit test or local-player check. Raw, as most of its bits are not decoded here.
     pub player_flags: u32,
-    /// `UNIT_DYNAMIC_FLAGS` (descriptor index 143), raw — what **`UNIT_DYNAMIC_FLAGS`** the
-    /// *event* fires on, the [`Self::flags`] pattern a hundred fields over.
-    ///
-    /// The event is id **137**, and the id is not arbitrary: the reference's generic bridge
-    /// `0x51bbb0` registers one watch per unit-window field whose name-table slot is non-NULL, and
-    /// the id it dispatches is that field's own window index — `137 + 6 = 143`, this field.
-    /// Byte-verified: `0xbe1198 + 137*4 = 0xbe13bc` has exactly one writer image-wide (`0x51ad8b`),
-    /// and the pointer it stores resolves to `"UNIT_DYNAMIC_FLAGS"`. The watch **length** is 4 —
-    /// selector byte `[0x51bc98 + 137] = 4`, jump-table entry `0x51bbf9 mov eax,4` — so the gate is
-    /// a `repe cmpsb` over exactly this one dword against the object's shadow copy (`0x4655bb`),
-    /// and **any** bit moving fires it.
-    ///
-    /// Raw for the same reason [`Self::player_flags`] is, and the cost of getting it wrong is
-    /// larger here: this struct decodes four of its bits ([`Self::tapped`],
-    /// [`Self::tapped_by_player`], and — through the store — lootable `0x1` and dead-looking
-    /// `0x20`), while `0x2` (tracked, Hunter's Mark) and `0x10` moves without touching any of
-    /// them. Firing off the decoded subset would silently under-announce those.
+    /// `UNIT_DYNAMIC_FLAGS` (field 143), raw. The event of the same name fires when any bit
+    /// moves: the reference's field watch (`0x51bbb0`) compares the whole dword, and bits such as
+    /// `0x2` (tracked) are not decoded here.
     pub dynamic_flags: u32,
-    /// The unit's owner — `UNIT_FIELD_SUMMONEDBY`, else its charmer, else its creator; `0` for
-    /// nobody's. What `UnitPlayerOrPetInParty`/`InRaid` read for the "or pet" half (1958).
+    /// The owner: `UNIT_FIELD_SUMMONEDBY`, else the charmer, else the creator, else 0; the
+    /// "or pet" half of `UnitPlayerOrPetInParty` and `UnitPlayerOrPetInRaid`.
     pub owner: u64,
-    /// The unit's guild membership (`GetGuildInfo(unit)`, decision 1257). `None` = guildless, or
-    /// a creature, or a player whose `PLAYER_GUILDID` has not streamed yet. Filled from the
-    /// PUBLIC descriptor fields 191/192 joined against the app's guild-identity cache — see
-    /// [`super::guild::UnitGuild`].
+    /// `GetGuildInfo(unit)`, from descriptor fields 191-192 and the guild-name cache; `None`
+    /// when guildless or not yet streamed.
     pub guild: Option<super::guild::UnitGuild>,
-    /// The NPC subtitle line ("Stable Master") — the creature template's subname; the unit
-    /// tooltip's second line. `None` for players/untitled creatures.
+    /// The creature template's subname ("Stable Master"), the tooltip's second line.
     pub subtitle: Option<String>,
-    /// The creature TYPE display word ("Beast", "Humanoid", …) — app-resolved from
-    /// `CreatureType.dbc`; the level line's class slot for hostile/neutral creatures.
+    /// The creature type word ("Beast") from `CreatureType.dbc`, the level line's class slot.
     pub creature_type_name: Option<String>,
-    /// Elite rank 0..4 — the creature classification every rank reader in the client shares, via
-    /// the one getter `0x605620`: the level line's rank word `{"", Elite, Elite, Boss, ""}` (0276),
-    /// `UnitLevel`'s world-boss −1 ([`level_reads_unknown`]), and `UnitClassification`
-    /// ([`classification_word`], decision 0782). **Already gated** by the app when it fills this:
-    /// the getter answers `0` unless the unit has a cached creature template *and* a zero
-    /// `UNIT_FIELD_PETNUMBER`, so a player, an un-queried creature and an enslaved elite all read
-    /// `0` here — the gate belongs at the one write, not in each of the three readers.
+    /// Creature rank 0..=4 as the reference's getter (`0x605620`) answers it, so already gated:
+    /// 0 without a cached creature template or with a pet number. The tooltip's rank word,
+    /// `UnitLevel`'s boss -1 and `UnitClassification` all read it.
     pub rank: u32,
-    /// The creature civilian flag — feeds the tooltip's green CIVILIAN line (shown only for a
-    /// PvP-flagged HOSTILE unit that is also GREY/trivial to the player — the dishonorable-kill
-    /// warning, the client's `0x612550` gate; a friendly civilian never shows it).
+    /// The creature civilian flag, one term of [`is_civilian_kill`].
     pub civilian: bool,
-    /// The creature racial-leader flag — the tooltip's white LEADER line (`0x6125c0`, gated on
-    /// the same PvP bit as CIVILIAN).
+    /// The creature racial-leader flag, the tooltip's LEADER line when PvP-flagged (`0x6125c0`).
     pub racial_leader: bool,
-    /// PvP-flagged (`UNIT_FIELD_FLAGS` PvP bit) — the tooltip's "PvP" line, and also `UnitIsPVP`
-    /// (decision 0434 §2: the party-frame PVP icon reads the same flag the tooltip line does, so
-    /// there's one field, not two).
+    /// `UNIT_FIELD_FLAGS`' PvP bit: `UnitIsPVP` and the tooltip's PvP line.
     pub pvp: bool,
-    /// Skinnable (`UNIT_FIELD_FLAGS` skinnable bit) — the tooltip's RED "Skinnable" line.
+    /// `UNIT_FIELD_FLAGS`' skinnable bit, the tooltip's red Skinnable line.
     pub skinnable: bool,
-    /// The unit's faction display name ("Stormwind") — the tooltip's white line between the
-    /// level line and "PvP". App-resolved (Faction.dbc through the unit's faction template,
-    /// every gate applied: reputation faction, race/class slot, hidden flag, the creature
-    /// HIDE_FACTION_TOOLTIP type flag); `None` = no line.
+    /// The faction name ("Stormwind"), the tooltip line after the level line, from `Faction.dbc`
+    /// through the faction template with its hiding gates applied; `None` shows no line.
     pub faction_name: Option<String>,
-    /// Connection to the server is live (`UnitIsConnected`) — an offline party member's portrait
-    /// desaturates (decision 0434 §2/§3: the `GROUP_LIST` status byte's `0x01` online bit).
-    /// **The zero value is `false`**, so a snapshot built via `..Default::default()` reports a unit
-    /// DISCONNECTED — which matters more than it reads: stock `UnitFrameManaBar_Update`
-    /// (UnitFrame.lua:213) greys a disconnected unit's bar and never reaches the power colour at
-    /// all. A synthetic unit that means to be live must say so.
-    ///
-    /// The app's own feed does (`ui_unit::snapshot`, "the stated `is_connected` gap, closed"), and
-    /// the party feed reads the roster status byte's `0x01` for its tokens. This doc used to call
-    /// that "a pending app-side change, not yet wired"; it has been wired since, and the note
-    /// outlived it. A token absent from the store (`UnitExists` false) still reports nil
-    /// regardless, via the same "no snapshot" path every other predicate here uses.
+    /// `UnitIsConnected`; party tokens take the roster status byte's `0x01`. The default `false`
+    /// reads disconnected, which greys a stock mana bar (`UnitFrame.lua:214`), so a synthetic
+    /// live unit must set it.
     pub is_connected: bool,
-    /// Away-from-keyboard (`UnitIsAFK` — decision 0434 §2's status-byte `0x40` bit). The party
-    /// frame's name line and chat both key off it. App-resolved; `false` until the feed lands.
+    /// `UnitIsAFK`, the roster status byte's `0x40`, fed for party tokens.
     pub is_afk: bool,
-    /// Do-not-disturb (`UnitIsDND` — decision 0434 §2's status-byte `0x80` bit), the AFK flag's
-    /// sibling.
+    /// `UnitIsDND`, the roster status byte's `0x80`, fed for party tokens.
     pub is_dnd: bool,
-    /// Free-for-all PvP-flagged (`UnitIsPVPFreeForAll` — decision 0434 §2's status-byte `0x10`
-    /// bit) — distinct from [`Self::pvp`]'s ordinary faction PvP flag; a unit can carry either, both,
-    /// or neither independently (an FFA zone flags this without the ordinary flag ever setting).
+    /// `UnitIsPVPFreeForAll`: `PLAYER_FLAGS` bit `0x80`, or the roster status byte's `0x10`;
+    /// independent of [`Self::pvp`].
     pub is_pvp_ffa: bool,
-    /// The unit's **current** PvP rank on the internal `0..=18` scale, `0` = no rank
-    /// (`UnitPVPRank`; decision 1512). `PLAYER_BYTES_3` **byte 3** — a **PUBLIC** descriptor field,
-    /// which is the whole reason a foreign player's rank is knowable and why the reference's
-    /// inspect pane can call `UnitPVPRank("target")`. Not to be confused with the HIGHEST LIFETIME
-    /// rank (`PLAYER_FIELD_BYTES` byte 3), which is private, rides
-    /// [`HonorState`](super::HonorState) instead, and is what `GetPVPLifetimeStats` reports.
-    ///
-    /// Internal, not visual: the badge texture and `GetPVPRankInfo`'s second return are the
-    /// `-4..=14` visual scale, converted in [`super::pvp`] and nowhere else.
+    /// `UnitPVPRank`: the current rank on the internal `0..=18` scale (0 none), from the public
+    /// `PLAYER_BYTES_3` byte 3. The private lifetime highest rides
+    /// [`HonorState`](super::HonorState); [`super::pvp`] converts to the `-4..=14` visual scale.
     pub pvp_rank: u8,
-    /// The unit's **city-protector title** index — `PLAYER_BYTES_3` **byte 2**, the byte next door
-    /// to [`Self::pvp_rank`] (vmangos `PLAYER_BYTES_3_OFFSET_CITY_PROTECTOR_TITLE`), PUBLIC like
-    /// it. `0` = none. Read by exactly one thing: `UnitPVPName`'s medal line, which appends
-    /// `"\n"` + the `PVP_MEDAL<n>` GlobalString when it is non-zero (`0x6093ef`).
-    ///
-    /// **v1 feed gap, stated not hidden:** no app-side feed fills this yet — it rides the same
-    /// dword the rank byte is decoded from, so wiring it is one line there, and until that line
-    /// exists every unit reads `0` and `UnitPVPName` renders no medal. The binding leg is built
-    /// against the field rather than left out, so the seam is a feed line rather than a missing
-    /// arm (same shape as [`Self::is_connected`]'s stated gap).
+    /// The city-protector title, `PLAYER_BYTES_3` byte 2 (0 none): `UnitPVPName` appends the
+    /// `PVP_MEDAL<n>` line for a non-zero one (`0x6093ef`).
     pub pvp_medal: u8,
-    /// The unit's PvP faction group — `"Alliance"` or `"Horde"`, else `None` (`UnitFactionGroup`;
-    /// decision 0646 §1). App-resolved from `UNIT_FIELD_FACTIONTEMPLATE` → `FactionTemplate.dbc`'s
-    /// group mask, with the Player bit skipped: every playable race's template carries
-    /// Player|<side> (mask 3 or 5), and so do the PvP-flagged city guards, so the side bit is the
-    /// only one that can name a shipped `UI-PVP-<group>` texture. `None` for Monster/neutral
-    /// templates is a state the icon callers explicitly handle (`if ( factionGroup and … )`).
-    ///
-    /// This is the **English** half — FactionGroup.dbc's `InternalName` — because that is what
-    /// `UnitFactionGroup`'s first return must carry: every stock consumer concatenates it into a
-    /// texture path (`"…\UI-PVP-"..factionGroup` at `PlayerFrame.lua:68`, `TargetFrame.lua:198`,
-    /// `PartyMemberFrame.lua:125`; `"…\Battleground-"..` at `BattlefieldFrame.lua:195`), and
-    /// `HonorFrame.lua:68` compares it against the literal `"Alliance"`.
-    ///
-    /// This field's doc used to say the binding "returns it twice … enUS ships the same word for
-    /// both". That is true of enUS and of nothing else: `Name0` is localized, so on any other
-    /// client the texture path would name a file that does not exist. The localized half lives in
-    /// [`Self::faction_group_localized`] now.
+    /// `UnitFactionGroup`'s first return, `"Alliance"` or `"Horde"`: `FactionGroup.dbc`'s English
+    /// `InternalName` for the side bit of the faction template's group mask, which stock builds
+    /// texture paths from (`PlayerFrame.lua:68`). `None` for a template with no side.
     pub faction_group: Option<String>,
-    /// The **localized** group name — FactionGroup.dbc's `Name0`, and `UnitFactionGroup`'s SECOND
-    /// return, which stock uses as display text (`PlayerFrame.lua`'s PvP hit-area tooltip title).
-    /// Never interchangeable with the English half above.
+    /// `UnitFactionGroup`'s second return, `FactionGroup.dbc`'s localized `Name0`: display text.
     pub faction_group_localized: Option<String>,
-    /// The unit's **PvP team digit** — `0x5efe00`'s tri-state: `0` Horde, `1` Alliance, `-1` a
-    /// unit with no side. The second `%d` of `PVP_RANK_<rank>_<team>`, and **not**
-    /// [`Self::faction_group`] restated.
-    ///
-    /// The two answer different questions and the difference is a shipped bug's whole cause
-    /// (report B378, decision 2227): `UnitFactionGroup` reads the unit's LIVE
-    /// `UNIT_FIELD_FACTIONTEMPLATE` (`0x5166b8`/`0x5166be`), while every rank-title surface reads
-    /// the unit's **RACE** and walks `ChrRaces` → `FactionTemplate` → factionGroupMask
-    /// (`0x5efe00`, `[obj+0x110]+0x78`). A vmangos GM is forced to template 35 and so genuinely
-    /// loses the PvP flag icon — and keeps his rank title, because his race did not move. Wiring
-    /// this to the faction group instead read `NONE` at every rank for a Grand Marshal.
-    ///
-    /// **`Default` is `0`, and that is the reference's answer too, not a placeholder.** A literal
-    /// snapshot is one the object manager could not resolve (the out-of-range roster leg), and
-    /// `GetPVPRankInfo`'s team register is left at its initial `0` on exactly that edge
-    /// (`0x51a9af`'s lookup failing) — so a roster-only unit is named off the Horde list on both
-    /// clients. Every snapshot built from a live descriptor fills it (`ui_unit::snapshot`).
+    /// The team digit of `PVP_RANK_<rank>_<team>` (`0x5efe00`): 0 Horde, 1 Alliance, -1 no side.
+    /// It follows the race through `ChrRaces` and `FactionTemplate`, never the live template
+    /// `UnitFactionGroup` reads (`0x5166b8`), so a GM on template 35 keeps the rank title. The
+    /// default 0 is the reference's answer for a unit it cannot resolve (`0x51a9af`).
     pub pvp_team: i8,
-    /// The unit's GUID (`OBJECT_FIELD_GUID`) — the identity the cross-token predicates compare
-    /// (`UnitIsUnit`, `UnitInParty`; decision 0434 §5's popup gating). `0` = the app's feed didn't
-    /// resolve one; two zero guids never compare equal.
+    /// `OBJECT_FIELD_GUID`, which `UnitIsUnit` and `UnitInParty` compare; 0 is unresolved, and
+    /// two zeros never match.
     pub guid: u64,
-    /// The raid-target mark on this unit (`GetRaidTargetIndex`): `0` none, `1..=8` the slot.
-    /// App-fed from the `GroupState` raid-target board (decision 0434 §6's verified 8-slot table
-    /// law) — the phase-5 submenu reads it; the phase-6 world renders draw from the same board.
+    /// `GetRaidTargetIndex`: 0 none, else the mark 1..=8, from the group's raid-target board.
     pub raid_target: u8,
-    /// The player can attack this unit (`UnitCanAttack("player", unit)`) — app-fed from the
-    /// byte-confirmed `CanAttack 0x606980` predicate (decision 0172; the flag disqualifiers +
-    /// reaction ≤ neutral legs TAB and the combat flash share; the Lua binding `0x516c50` is
-    /// pure delegation to it). Like [`Self::reaction`], the feed resolves it for
-    /// the `"target"` token; other tokens leave the default `false` (→ nil), which is right for
-    /// every current caller (`TargetFrame_CheckLevel`'s difficulty-color gate).
+    /// Whether the player can attack the unit, `UnitCanAttack("player", unit)`, which the binding
+    /// (`0x516c50`, delegating to `CanAttack` `0x606980`) answers for both argument orders. Fed for
+    /// `target`, `targettarget` and `npc`; other tokens read false.
     pub can_attack: bool,
-    /// This token resolves to a **TYPEID_CORPSE world object** — `UnitIsCorpse`'s whole
-    /// predicate (`0x5161c0`: a pure object-type check, no health test; a dead
-    /// mob/player is NOT a corpse). No feed sets it yet — corpse objects (a released player's
-    /// remains) aren't selectable in benilla — a stated gap, not an oversight.
+    /// `UnitIsCorpse` (`0x5161c0`): the token names a `TYPEID_CORPSE` object, which a dead unit
+    /// is not. No feed sets it.
     pub corpse_object: bool,
-    /// In combat (`UnitAffectingCombat`) — `UNIT_FIELD_FLAGS` (descriptor index 46) **bit 19**,
-    /// mask `0x00080000` (`0x517e10`: `mov ecx,[eax+0xa0]; shr ecx,0x13; test cl,1`).
-    ///
-    /// **There is no player-specific combat latch**, stated as the explicit negative because it
-    /// is precisely what a client is tempted to invent: a whole-image census of the
-    /// `shr reg,0x13` + `test rl,1` idiom returns 7 hits, six of them this same field+bit — and
-    /// two of those six are hardcoded *local-player* readers taking no token at all. `"player"`
-    /// takes a fast path to the cached local-player GUID inside `0x515970` and then reads the
-    /// identical bit. One wire flag answers this for every token, which is what this one field
-    /// is; `benilla::spell::usable` already reads the same bit off the same descriptor.
+    /// `UnitAffectingCombat` (`0x517e10`): `UNIT_FIELD_FLAGS` bit `0x00080000`, for every token
+    /// including `"player"`; the reference has no separate player combat flag.
     pub in_combat: bool,
 }
 
-/// `FrameScript_GetText("UNKNOWNOBJECT")` as the client's name resolvers call it — the VM's own
-/// GlobalString, read out of `_G` exactly as `0x703bf0` reads it (so a translated
-/// `GlobalStrings.lua` translates this too; enUS `"Unknown"`, `GlobalStrings.lua:4444`), falling
-/// back to the binary's own literal `"Unknown Being"` (`0x860fa4`) when the global is missing or
-/// empty. Always a string — this is the "name not yet known" state, never a nil.
-///
-/// **ONE home, two callers**, the same reason [`is_civilian_kill`] is a function. `UnitName`
-/// `0x517020` reaches it at `0x517220`, and `CGUnit_C::GetUnitName 0x609210` — which the UNIT
-/// TOOLTIP builder `0x529fe0` calls for its title line (`0x52a187`) — reaches the *same* tail at
-/// `0x609324`, from every one of its misses:
-///
-/// ```text
-/// 609353  je 0x609324        ; creature: [CGUnit+0xb30] (creaturecache.wdb) still null
-/// 6092ce  je 0x609324        ; pet: petnamecache.wdb row absent, or its stamp stale
-/// 609265  je 0x609324        ; player: namecache.wdb has not answered
-/// 609324  push 0x0 / or edx,-1 / mov ecx,0x850ed0 ("UNKNOWNOBJECT") / call 0x703bf0
-/// 60933c  mov eax,0x860fa4   ; the global missing or empty -> "Unknown Being"
-/// ```
-///
-/// One resolver, so the verb and the plate can never disagree about what a unit whose name is
-/// still in flight is called (decisions 2002, 2040).
-///
-/// **Both halves of that tail are here, and both are load-bearing.** The lookup is the rule
-/// (decision 2045: the sentence is the install's, not ours); the literal beside it is the
-/// reference's own `0x860fa4`, which is what "a literal is legitimate only as a fallback beside a
-/// lookup" means. Spelled `globals().get::<String>` — the shape `benilla-app`'s
-/// `reference_strings` tripwire recognises as a resolver — so the fallback reads as the fallback
-/// it is rather than as undeclared drift. It answers the same three cases the `mlua::Value` read
-/// it replaces did: a non-empty string is returned, and both a missing global and a present-but-
-/// EMPTY one take `0x860fa4` (the binary tests the pointer and then its first byte).
+/// The name of a unit whose name is not yet known, as the reference's `UnitName` (`0x517220`) and
+/// unit tooltip title (`0x609324`) both answer it: the `UNKNOWNOBJECT` GlobalString (enUS
+/// "Unknown"), else the literal "Unknown Being" (`0x860fa4`) when the global is missing or empty.
 pub fn unknownobject(lua: &Lua) -> mlua::Result<mlua::String> {
-    // One expression, deliberately: `globals().get::<String>` is what the tripwire matches on,
-    // and a line break inside it would hide this resolver from the walk again.
+    // One expression: `benilla-app`'s `reference_strings` check matches
+    // `globals().get::<String>`, and a line break inside it would hide this lookup.
     let global = lua.globals().get::<String>("UNKNOWNOBJECT").ok();
     lua.create_string(match global.as_deref() {
         Some(s) if !s.is_empty() => s,
@@ -480,18 +209,13 @@ pub fn unknownobject(lua: &Lua) -> mlua::Result<mlua::String> {
     })
 }
 
-/// The grey-band table `0x80ae98` (a byte-identical twin at `0x81dda8` drives the nameplate's
-/// grey level colour), indexed by `playerLevel / 5` and clamped to 12 past the table. ONE home
-/// for its three consumers: [`unit_is_grey`] (tooltip CIVILIAN gate + the plate's skull/grey
-/// legs), the `GetQuestGreenRange` binding (the FrameXML `GetDifficultyColor` green→grey
-/// boundary), and — through both — every level con the UI shows.
+/// The reference's grey-level band (`0x80ae98`; twins at `0x81dda8` and `0x8076c0`), indexed by
+/// player level / 5.
 const GREY_BAND: [u32; 20] = [
     4, 4, 5, 5, 6, 6, 7, 7, 8, 9, 10, 11, 12, 12, 12, 12, 12, 12, 12, 12,
 ];
 
-/// The band value for a player level — `GREY_BAND[min(playerLevel/5, 19)]` (the
-/// `GetQuestGreenRange` return: the binding `0x4e17d0` reads the
-/// byte-identical `0x8076c0` twin with exactly this index clamp).
+/// `GetQuestGreenRange`'s answer (`0x4e17d0`): the band for a player level, 12 past the table.
 pub fn grey_band(player_level: u32) -> u32 {
     GREY_BAND
         .get((player_level / 5) as usize)
@@ -499,57 +223,32 @@ pub fn grey_band(player_level: u32) -> u32 {
         .unwrap_or(12)
 }
 
-/// The trivial/GREY check (`0x5f0700`): a unit enough
-/// levels *below* the player that it cons grey — `playerLevel − unitLevel >
-/// GREY_BAND[playerLevel/5]`, **strict >** (diff == band is still green). The binary's full
-/// predicate also requires not-player-controlled; every consumer here applies this to creatures.
+/// The reference's grey level test (`0x5f0700`): the unit is more than the band below the player,
+/// strictly, so a gap equal to the band is still green. The reference also requires the unit not
+/// be player-controlled; every caller here passes creatures.
 pub fn unit_is_grey(player_level: u32, unit_level: u32) -> bool {
     player_level > unit_level && player_level - unit_level > grey_band(player_level)
 }
 
-/// The **CIVILIAN predicate `0x612550`** — "killing this would be a dishonorable kill": the unit's
-/// PvP bit **and** the creature-query civilian flag **and** the unit is HOSTILE to the player
-/// (`UnitReaction` ≤ 2) **and** the kill would be GREY/trivial ([`unit_is_grey`]). A friendly
-/// civilian, or one that still cons, is not one.
-///
-/// **ONE home, two callers**, which is the whole reason it is a function: the unit tooltip's green
-/// CIVILIAN line ([`super::tooltip_unit`], decision 0276) and `UnitPVPName`'s civilian arm
-/// ([`super::pvp`] — `0x609370` leg B, which prefixes `PVP_RANK_CIVILIAN` onto a non-player's
-/// name). The engine gates both on the same call; a second copy here would let the tooltip and the
-/// name disagree about whether the same mob is a civilian.
-///
-/// **Scope of the verification.** `0x612550` is named by its use here, not independently
-/// confirmed at the bytes; the four terms are decision 0276's tooltip-line law, which is where
-/// this composition was verified. So this is the tooltip's gate reused at the second call site —
-/// not an independently byte-checked predicate.
+/// The civilian gate (`0x612550`), a dishonorable kill: PvP-flagged, a civilian creature, hostile
+/// (`UnitReaction` <= 2) and grey. The tooltip's CIVILIAN line and `UnitPVPName`'s civilian prefix
+/// (`0x609370`) both read it. The terms are the tooltip line's; `0x612550`'s body is not traced.
 pub fn is_civilian_kill(u: &UnitState, player_level: u32) -> bool {
     u.civilian && u.pvp && u.reaction != 0 && u.reaction <= 2 && unit_is_grey(player_level, u.level)
 }
 
-/// The "level reads ??" gate — the engine tooltip's byte-pinned leg set (`0x529fe0`): never
-/// players; level 0 (unstreamed), world-boss rank 3, or a much-higher hostile (reaction ≤ 2 on the
-/// 1..8 API scale, unit ≥ player + 10 — **inclusive**, byte-confirmed). The Lua `UnitLevel`'s −1
-/// law agrees with this: its two −1 legs are exactly the boss + hostile-≥10 legs here (no
-/// trivial-gray term exists in `0x517fc0`, and none is possible at ≥ +10), with ONE divergence the
-/// binding handles itself — a raw level ≤ 0 returns VERBATIM, not −1 (same skull outcome in
-/// FrameXML; the tooltip's "??" keeps the level-0 leg per its own law).
+/// The tooltip's "??" level gate (`0x529fe0`): never a player; level 0, world-boss rank 3, or a
+/// hostile (reaction <= 2) at least 10 levels above the player. `UnitLevel` (`0x517fc0`) answers
+/// the boss and hostile legs with -1, but returns a level of 0 as is.
 pub fn level_reads_unknown(u: &UnitState, player_level: u32) -> bool {
     let much_higher_hostile =
         u.reaction != 0 && u.reaction <= 2 && u.level >= player_level.saturating_add(10);
     !u.is_player && (u.level == 0 || u.rank == 3 || much_higher_hostile)
 }
 
-/// `UnitClassification`'s return — the classification-word table, **byte-verified** at `0x850424`
-/// (decision 0782): the binding `0x516d90` is nothing but `TABLE[rank(unit)]`, indexed by the same
-/// gated rank [`UnitState::rank`] carries. The table is exactly five entries long (the sixth dword
-/// at `0x850438` is an unrelated `"UnitExists"` literal), and rank comes pre-clamped to 0..4 by
-/// `CreatureInfo+0x20`, so an out-of-range value can only be our own bug — it reads `"normal"`,
-/// which is also what the binding's unresolved-token path pushes (`0x516dc4` loads index 0).
-///
-/// Note `"rareelite"` is a real return here even though 1.12 has no rare-elite *art* and no
-/// rare-elite tooltip *word* — the reference's `TargetFrame_CheckClassification` sends it to the
-/// same Elite border as `"elite"`, and the tooltip's `{"", Elite, Elite, Boss, ""}` prints ELITE for
-/// it. The distinction exists in the API and nowhere in the pixels.
+/// `UnitClassification` (`0x516d90`): the word table at `0x850424` indexed by the gated
+/// [`UnitState::rank`]; an unresolved token reads index 0, "normal" (`0x516dc4`). "rareelite" is
+/// a real answer, though stock draws it with the elite art (`TargetFrame.lua:209`).
 pub fn classification_word(rank: u32) -> &'static str {
     match rank {
         1 => "elite",
@@ -560,8 +259,8 @@ pub fn classification_word(rank: u32) -> &'static str {
     }
 }
 
-/// The Era power-token string for a power-type index (`UnitPowerType`'s second return,
-/// `UNIT_POWER_UPDATE`'s arg2). Unknown indices report as mana, the descriptor default.
+/// The resource name for a power type, the suffix of 1.12's per-resource events (`UNIT_RAGE`,
+/// `UNIT_MAXRAGE`); an unknown index reads as mana, the descriptor default.
 pub fn power_token(ty: u8) -> &'static str {
     match ty {
         1 => "RAGE",
@@ -573,28 +272,17 @@ pub fn power_token(ty: u8) -> &'static str {
 }
 
 impl super::UiScript {
-    /// Push (or clear) a unit token's snapshot. `Some(state)` stores it under `token`; `None` removes
-    /// it (so `UnitExists(token)` reports false and the numeric getters return `0`). The app's
-    /// per-frame feed (decision 0068 §3) calls this for `"player"`/`"target"`/… before the VM's
-    /// event dispatch, so a frame's `OnEvent` sees the current values.
+    /// Push, or clear with `None`, a token's snapshot; the app's feed calls it each frame before
+    /// event dispatch, so a frame's `OnEvent` sees current values.
     pub fn set_unit(&mut self, token: &str, state: Option<UnitState>) {
         {
             let mut model = self.model_mut();
             match state {
-                // Folded on the way IN as well as on the way out — the map's key type is the
-                // canonical lowercase token, so a feed that ever pushed `"Target"` could not create
-                // a second, shadowing entry.
+                // Keys fold to lowercase on the way in too, so a `"Target"` push cannot shadow
+                // `"target"`.
                 Some(s) => {
-                    // **A `"player"` push keeps the record in step, field by field** (2261,
-                    // widened by 2263). The reference writes `0xc27d80` once per Enter World
-                    // commit and never clears it; our VM is rebuilt per login, so the entry load
-                    // seeds it — and this keeps it true for any later push that KNOWS a field,
-                    // without ever letting one that doesn't blank it.
-                    //
-                    // That asymmetry is the whole mechanism: 2260's nameless player snapshot is
-                    // exactly the push that must not be able to reach these four verbs. It is also
-                    // what keeps every fixture in the workspace correct without touching them — a
-                    // test that seats a full player is, by this rule, also seating the record.
+                    // A `"player"` push updates each record field it carries and never blanks
+                    // one, so a nameless snapshot cannot reach the four record verbs.
                     if token.eq_ignore_ascii_case("player") {
                         let rec = &mut model.player_record;
                         if let Some(name) = s.name.as_deref().filter(|n| !n.is_empty()) {
@@ -619,34 +307,26 @@ impl super::UiScript {
                 }
             }
         }
-        // A push for a tooltip's LIVE unit token re-drives its health bar (the byte law's
-        // HEALTH watcher — decision 0276; no line rebuild).
+        // A push for a tooltip's live unit token re-drives its health bar, without a line rebuild.
         super::tooltip_unit::on_unit_push(&self.lua, token);
     }
 
-    /// Push the player's purse in copper (`PLAYER_FIELD_COINAGE`), read by the `GetMoney` global. A
-    /// player-level snapshot (like the unit tokens) — the app calls this each frame the coinage
-    /// field changes (decision 0081 phase 4).
+    /// Push the player's copper (`PLAYER_FIELD_COINAGE`), read by `GetMoney`.
     pub fn set_money(&mut self, copper: u64) {
         self.model_mut().money = copper;
     }
 
-    /// Push the player's experience within the level (`PLAYER_XP`) and the level's requirement
-    /// (`PLAYER_NEXT_LEVEL_XP`), read by the `UnitXP`/`UnitXPMax` globals. A player-level pair (like
-    /// [`Self::set_money`]) — the app calls this each frame the XP fields change (the MainMenuBar XP
-    /// bar feed). Both PRIVATE descriptor fields, so this only ever carries our own avatar's values.
+    /// Push `PLAYER_XP` and `PLAYER_NEXT_LEVEL_XP`, private fields that `UnitXP` and `UnitXPMax`
+    /// answer for `"player"` alone.
     pub fn set_player_xp(&mut self, xp: u32, next_level_xp: u32) {
         let mut model = self.model_mut();
         model.player_xp = xp;
         model.player_next_level_xp = next_level_xp;
     }
 
-    /// Push the player's rest snapshot — the `PLAYER_BYTES_2` byte 3 rest state, the
-    /// `PLAYER_REST_STATE_EXPERIENCE` pool (raw wire value, base kill-XP units) and the
-    /// `PLAYER_FLAGS_RESTING` bit — taken together so the `GetRestState`/`GetXPExhaustion`/
-    /// `IsResting` trio can never read a half-updated rest picture. Player-level fields, same
-    /// shape as [`Self::set_money`]; the app calls this each frame any of the three moves
-    /// (decision 1082).
+    /// Push the rest state (`PLAYER_BYTES_2` byte 3), the rested pool
+    /// (`PLAYER_REST_STATE_EXPERIENCE`, raw) and `PLAYER_FLAGS_RESTING` together, so
+    /// `GetRestState`, `GetXPExhaustion` and `IsResting` never read a half update.
     pub fn set_rest_state(&mut self, state: u8, pool: u32, resting: bool) {
         let mut model = self.model_mut();
         model.rest_state = state;
@@ -654,48 +334,40 @@ impl super::UiScript {
         model.resting = resting;
     }
 
-    /// Push the two **play-time** bits of `PLAYER_FLAGS` — 12 (`PartialPlayTime`) and 13
-    /// (`NoPlayTime`), decision 1746. Taken together for the same reason the rest trio is:
-    /// stock `PlayerFrame_UpdatePlaytime` (PlayerFrame.lua:244) tests them as an if/elseif pair
-    /// and a half-updated pair would paint the wrong one of the two icons.
+    /// Push `PLAYER_FLAGS` bits 12 (`PartialPlayTime`) and 13 (`NoPlayTime`) together, as
+    /// `PlayerFrame.lua:244` tests them in one if/elseif.
     pub fn set_play_time(&mut self, partial: bool, none: bool) {
         let mut model = self.model_mut();
         model.partial_play_time = partial;
         model.no_play_time = none;
     }
 
-    /// Push the account's **rested billing minutes**, from the `SMSG_AUTH_RESPONSE` that admitted
-    /// the session — what `GetBillingTimeRested()` returns (decision 1820). Set once at login: the
-    /// client parks it in a process-lifetime global and nothing else on the wire ever writes it.
+    /// Push `GetBillingTimeRested()`'s minutes, from the `SMSG_AUTH_RESPONSE` that admitted the
+    /// session; nothing else on the wire writes it.
     pub fn set_billing_time_rested(&mut self, minutes: u32) {
         self.model_mut().billing_time_rested = minutes;
     }
 
-    /// Enter the **UI-load sound-suppression scope** — the reference's `0x458f50`, an `inc` on the
-    /// counted depth every name-keyed `PlaySound` reads. Counted, not a flag, exactly as the
-    /// client has it: nesting is legal and only the outermost exit re-enables sound.
+    /// Enter the UI-load sound-suppression scope (`0x458f50`): a depth every name-keyed
+    /// `PlaySound` reads, so scopes nest and only the outermost exit re-enables sound.
     pub fn push_sound_suppression(&self) {
         let mut model = self.model_mut();
         model.sound_suppression = model.sound_suppression.saturating_add(1);
     }
 
-    /// Leave it — `0x458f60`'s `dec`. Saturating on the way down too: an unbalanced pop is a bug
-    /// in the caller, and silently wrapping to a permanently-muted UI would be the worse failure.
+    /// Leave it (`0x458f60`), saturating so an unbalanced pop cannot wrap to a muted UI.
     pub fn pop_sound_suppression(&self) {
         let mut model = self.model_mut();
         model.sound_suppression = model.sound_suppression.saturating_sub(1);
     }
 
-    /// Push whether a cinematic is playing — what `InCinematic()` answers.
+    /// Push whether a cinematic is playing, `InCinematic()`'s answer.
     pub fn set_in_cinematic(&mut self, playing: bool) {
         self.model_mut().in_cinematic = playing;
     }
 
-    /// Push Exhaustion.dbc — `(rest-state byte, localized name, factor)` rows for the
-    /// `GetRestState`/`GetXPExhaustion` bindings (they read the table exactly as `0x48d350` /
-    /// `0x48d3f0` read the client's own copy; decision 1087). Called once at startup off the
-    /// patch chain; an empty push is ignored so a failed DBC read keeps the shipped-table
-    /// fallback the model seeds.
+    /// Push `Exhaustion.dbc`'s (rest state, localized name, factor) rows, read as `0x48d350` and
+    /// `0x48d3f0` read them; an empty push keeps the fallback table the model seeds.
     pub fn set_exhaustion_rows(&mut self, rows: Vec<(u8, String, f64)>) {
         if rows.is_empty() {
             return;
@@ -704,64 +376,45 @@ impl super::UiScript {
         model.exhaustion = rows.into_iter().map(|(id, n, f)| (id, (n, f))).collect();
     }
 
-    /// Push the player's banked combo points (`PLAYER_FIELD_BYTES` byte 1) and the unit they sit
-    /// on (`PLAYER_FIELD_COMBO_TARGET`) — the pair `Player::SetComboPoints` writes together, taken
-    /// together so they can never be read half-updated. Player-level PRIVATE fields, same shape as
-    /// [`Self::set_money`]; the app calls this each frame either moves, including the drop back to
-    /// zero (decisions 0869, 0875).
-    ///
-    /// **Raw wire values** — `GetComboPoints`'s class and current-target gates live in the binding,
-    /// where the binary puts them.
+    /// Push the combo points (`PLAYER_FIELD_BYTES` byte 1) and their target
+    /// (`PLAYER_FIELD_COMBO_TARGET`) together, as `Player::SetComboPoints` writes them. Raw:
+    /// `GetComboPoints`' class and target gates are the binding's.
     pub fn set_combo_points(&mut self, points: u8, target: u64) {
         let mut model = self.model_mut();
         model.combo_points = points;
         model.combo_target = target;
     }
 
-    /// Drain the selection asks queued since the last call — the app resolves each to a guid and
-    /// commits it through the one SetSelection tail. See [`SelectionRequest`] for why the three
-    /// verbs share one ordered queue.
+    /// Drain the queued [`SelectionRequest`]s, in call order.
     pub fn take_selection_requests(&mut self) -> Vec<SelectionRequest> {
         std::mem::take(&mut self.model_mut().selection_requests)
     }
 
-    /// Drain the `TargetNearestFriend([reverse])` presses queued since the last call — one `bool`
-    /// per call, the cycle direction (`false` forward, `true` backward). Its own queue rather than
-    /// a [`SelectionRequest`] variant because it names no unit: the reference runs it through the
-    /// TAB cycler `0x493f60(reverse, mode 2)` and straight into `SetSelection`, never through the
-    /// select-if-resolves helper the other three share.
+    /// Drain the `TargetNearestFriend([reverse])` calls, `true` for reverse. It names no unit: the
+    /// reference runs the TAB cycler (`0x493f60`, mode 2) straight into `SetSelection`.
     pub fn take_target_nearest_friend_requests(&mut self) -> Vec<bool> {
         std::mem::take(&mut self.model_mut().target_nearest_friend_requests)
     }
 
-    /// Drain the `(name, exactMatch)` pairs `TargetByName` queued since the last call — the app
-    /// runs the shared by-name resolver (decision 0886) and commits the selection.
+    /// Drain the `TargetByName(name, exactMatch)` calls for the app's by-name resolver.
     pub fn take_target_by_name_requests(&mut self) -> Vec<(String, bool)> {
         std::mem::take(&mut self.model_mut().target_by_name_requests)
     }
 
-    /// Drain the `ClearTarget()` trigger: `true` if it fired with a live target since the last
-    /// call — the ESC chain's last leg; the app commits the deselect (SetSelection guid 0).
+    /// Drain `ClearTarget()`: true if it fired with a live target; the app deselects (guid 0).
     pub fn take_target_clear(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().target_clear)
     }
 
-    /// Drain the unit tokens `DropItemOnUnit` queued since the last call — the app runs every gate
-    /// and, on the pet leg, casts the learned Feed Pet spell at the held item (`0x48d960`).
+    /// Drain `DropItemOnUnit`'s tokens; on the pet the app casts the learned Feed Pet spell at
+    /// the held item (`0x48d960`).
     pub fn take_drop_item_on_unit(&mut self) -> Vec<String> {
         std::mem::take(&mut self.model_mut().drop_item_on_unit)
     }
 }
 
-/// Pick the interesting token from a directional two-unit call (`UnitIsEnemy(a, b)`): whichever
-/// arg isn't `"player"` — our snapshot stores the relationship on the non-player unit (target),
-/// and the ref calls both argument orders.
-///
-/// **The `"player"` test folds case**, like every other token comparison here and like the client's
-/// own resolver. It is the kind of site the map's fold does not cover on its own: an addon passing
-/// `UnitIsEnemy("Player", "target")` would otherwise be read as naming a non-player first arg, and
-/// this would answer about the wrong unit — a wrong ANSWER rather than a missing one, which is the
-/// worse failure of the two.
+/// The non-`"player"` token of a two-unit call such as `UnitIsEnemy(a, b)`, which the snapshot
+/// holds the relationship on; the test folds case, as the resolver does.
 fn pick_unit_token(a: &Option<String>, b: &Option<String>) -> Option<String> {
     match (a, b) {
         (Some(x), _) if !x.eq_ignore_ascii_case("player") => Some(x.clone()),
@@ -770,16 +423,9 @@ fn pick_unit_token(a: &Option<String>, b: &Option<String>) -> Option<String> {
     }
 }
 
-/// The token prefixes 1.12's resolver `0x515970` recognises, in its own order.
-///
-/// The order is the binary's and is preserved even though our recogniser is order-insensitive:
-/// `partypet` must be tested before `party` and `raidpet` before `raid` for a *resolver* to pick the
-/// right unit, and the day this grows from a boolean into a resolver, the list is already right.
-///
-/// **These are PREFIX tests.** The compare length is the literal's, and `_strnicmp` stops at either
-/// string's NUL, so `"playerfoo"` matches `player` — which is why it is a quiet nil rather than a
-/// raise. `npc` is the sole FULL-STRING compare in the resolver, so `"npctarget"` matches nothing
-/// and raises; it is deliberately absent from this list and handled separately below.
+/// The token prefixes the resolver (`0x515970`) tests, in its order (`partypet` before `party`).
+/// Each is a prefix test, so `"playerfoo"` is recognised; `npc`, its one full-string compare, is
+/// tested apart.
 const UNIT_TOKEN_PREFIXES: [&str; 8] = [
     "player",
     "pet",
@@ -791,47 +437,24 @@ const UNIT_TOKEN_PREFIXES: [&str; 8] = [
     "mouseover",
 ];
 
-/// Does 1.12's resolver RECOGNISE this token — whether or not it names a live unit?
-///
-/// This is the whole raise/nil distinction, so it is worth being exact about what it is not: it does
-/// not ask whether a unit exists. `"party5"` on a solo character, `"pet"` with no pet, and
-/// `"playerfoo"` are all *recognised* and answer nil; only a token the resolver's nine compares
-/// never match raises `Unknown unit name`.
+/// Whether the resolver recognises the token, not whether it names a unit: `"party5"` solo is
+/// recognised and answers nil, and only a token none of its nine compares match raises.
 pub(crate) fn token_recognised(token: &str) -> bool {
-    // `npc` full-string, everything else a prefix — and folded, like every compare in the resolver
-    // (`SStrCmpI` -> `_strnicmp`, ASCII only; 1247).
+    // `npc` full-string, the rest prefixes, all folded as `_strnicmp` folds: ASCII only.
     token.eq_ignore_ascii_case("npc")
         || UNIT_TOKEN_PREFIXES
             .iter()
-            // BYTES, not a string slice. `token[..p.len()]` panics when the token is multibyte
-            // UTF-8 and the prefix length lands mid-character ("byte index N is not a char
-            // boundary") — an addon passing a non-ASCII token would take the client down. The
-            // client's own compare is `_strnicmp` over bytes with an ASCII-only fold, so byte
-            // comparison is both the safe form and the faithful one.
+            // Bytes, not a `str` slice, which panics mid-character on a multibyte token.
             .any(|p| {
                 token.len() >= p.len()
                     && token.as_bytes()[..p.len()].eq_ignore_ascii_case(p.as_bytes())
             })
 }
 
-/// The gate every `Unit*` binding puts an addon-supplied token through.
-///
-/// **An unrecognised token RAISES and does not return** — `0x515970` falls off the end of its nine
-/// compares into `luaL_error(L, "Unknown unit name: %s")`, which longjmps. Ours answered nil for
-/// everything unknown, which is 1203's shape pointed the other way: a failure the client reports,
-/// silently swallowed.
-///
-/// The split is THREE-way, not two, and the two quiet legs are as follows:
-///   * **absent argument** — quiet nil *here*, because this helper is only the resolver's half.
-///     Whether a nil ever reaches it is the BINDING's question, and it is settled per binding:
-///     all 83 entries at `0x850438` gate the token position with `lua_isstring` and raise `Usage:`
-///     in 53 cases, against 13 unit-token bindings with no gate at all (decision 1834). The gated
-///     ones call `binding_abi::string_arg` before they get here, so a nil never arrives; the quiet
-///     13 pass it straight through. This comment used to say the gates were "NOT uniform … only
-///     those two poles are verified" and decline to guess, which was the right call at the time —
-///     the table now exists, so it is applied rather than feared;
-///   * **`""`** — quiet nil;
-///   * a **recognised** token naming nothing (`"party5"` solo, `"playerfoo"`) — quiet nil.
+/// The resolver's token check: an unrecognised token raises `Unknown unit name`, as `0x515970`
+/// ends in `luaL_error`; `""`, an absent token and a recognised one naming nothing pass. Whether
+/// nil arrives is per binding: of the 83 in the table at `0x850438`, 53 raise `Usage:` first and
+/// 13 unit-token bindings take nil with no gate.
 pub(crate) fn check_unit_token(token: &Option<String>) -> mlua::Result<()> {
     match token {
         Some(t) if !t.is_empty() && !token_recognised(t) => {
@@ -841,10 +464,8 @@ pub(crate) fn check_unit_token(token: &Option<String>) -> mlua::Result<()> {
     }
 }
 
-/// Read a unit token's snapshot under a short model borrow, mapping it through `f`; `default` when the
-/// token is absent (the "unit doesn't exist" path).
-///
-/// Raises for an unrecognised token ([`check_unit_token`]) before it looks anything up.
+/// Map a token's snapshot through `f` under a short model borrow, or answer `default` for an
+/// absent unit, after the token check.
 fn with_unit<T>(
     lua: &Lua,
     token: &Option<String>,
@@ -859,21 +480,10 @@ fn with_unit<T>(
     })
 }
 
-/// A unit **predicate** binding's whole body: resolve the token, map its snapshot to a bool, and
-/// push the family's one return shape — the number `1` or `nil`, never a Lua boolean.
-///
-/// [`with_unit`] answers whatever `f` answers, so a predicate written on it *directly* hands mlua a
-/// Rust `bool`, and mlua pushes tag 1. That is the one shape 1.12 cannot produce: `UnitExists`
-/// (`0x515fb0`) pushes `lua_pushnumber` (`0x6f3810`, tag 3, the double `1.0`) or `lua_pushnil`
-/// (`0x6f37f0`, tag 0) and nothing else, and so does every other predicate in the family. So the
-/// whole family goes through [`super::binding_abi::flag`] — 1830's widget law, which is the
-/// *same* law, finally applied to the unit surface (decision 2043). A predicate that hand-computes
-/// its own bool calls that helper directly; one that reads a snapshot field calls this. Both end at
-/// the one push site, which is what stops the family drifting apart again.
-///
-/// **Not every unit binding is a predicate.** `UnitReaction` answers the reaction *number*,
-/// `UnitLevel` a level (with `-1` for "can't be told"), `UnitPowerType` a power index whose miss is
-/// the number `0` and never nil. Those keep their own shapes and must not be routed here.
+/// A unit predicate's body: the number 1 or nil through [`super::binding_abi::flag`], never a Lua
+/// boolean, as the reference pushes only `lua_pushnumber` (`0x6f3810`) or `lua_pushnil`
+/// (`0x6f37f0`). `UnitReaction`, `UnitLevel` and `UnitPowerType` are getters with their own
+/// shapes and do not route here.
 fn unit_predicate(
     lua: &Lua,
     token: &Option<String>,
@@ -882,8 +492,7 @@ fn unit_predicate(
     Ok(super::binding_abi::flag(with_unit(lua, token, false, f)?))
 }
 
-/// The `Unit*`/`GetQuestGreenRange` Lua binding registrations — split from this module's
-/// state+laws half purely for size (same seam as the other script modules' install fns).
+/// The `Unit*` and `GetQuestGreenRange` registrations.
 mod bindings;
 #[cfg(test)]
 mod tests;
diff --git a/crates/benilla-ui/src/script/unit/tests.rs b/crates/benilla-ui/src/script/unit/tests.rs
index adb73058..014ecc9c 100644
--- a/crates/benilla-ui/src/script/unit/tests.rs
+++ b/crates/benilla-ui/src/script/unit/tests.rs
@@ -1,4 +1,4 @@
-//! The `Unit*` binding tests (the parent module is the unit under test).
+//! The `Unit*` binding tests.
 
 use crate::script::{PartyState, PlayerRecord, UiScript, UnitState};
 
@@ -26,7 +26,7 @@ fn player() -> UnitState {
 #[test]
 fn unit_reaction_reports_the_scale_value_or_nil() {
     let mut s = UiScript::new().unwrap();
-    // Neutral target (UnitReaction 4) → the integer; the name-plate palette indexes it.
+    // 4 is neutral.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -40,7 +40,7 @@ fn unit_reaction_reports_the_scale_value_or_nil() {
             .unwrap(),
         4
     );
-    // reaction 0 (unresolved) reports as nil — the API's "can't tell".
+    // 0 is unresolved, which answers nil.
     s.set_unit(
         "player",
         Some(UnitState {
@@ -54,15 +54,11 @@ fn unit_reaction_reports_the_scale_value_or_nil() {
         .unwrap());
 }
 
-/// The target plate's faction decision (TargetFrame_CheckFaction, as `UnitFrame_Update`
-/// composes it): a player-controlled target picks red (mutually hostile) or blue (else) and
-/// NEVER the reaction green; only an NPC reads the reaction swatch. This pins the predicate
-/// composition the plate branch depends on — a friendly *player* must resolve to blue, which is
-/// exactly the green-vs-blue bug the branch fixes.
+/// A player target branches on `UnitIsEnemy` and an NPC on `UnitReaction` (2 hostile, 5
+/// friendly), so a friendly player is blue, never the reaction colour.
 #[test]
 fn the_name_plate_faction_branch_picks_player_red_blue_over_the_reaction_swatch() {
     let mut s = UiScript::new().unwrap();
-    // The plate's decision, verbatim from the XML Update (a chunk whose if-branches each return).
     let plate = r#"
             local u = "target"
             if UnitIsPlayer(u) then
@@ -73,7 +69,6 @@ fn the_name_plate_faction_branch_picks_player_red_blue_over_the_reaction_swatch(
         "#;
     let decide = |s: &mut UiScript| s.eval::<String>(plate).unwrap();
 
-    // A friendly PLAYER (reaction 5) → blue, not the reaction green.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -84,7 +79,6 @@ fn the_name_plate_faction_branch_picks_player_red_blue_over_the_reaction_swatch(
         }),
     );
     assert_eq!(decide(&mut s), "blue");
-    // A hostile PLAYER (reaction 2) → red.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -95,7 +89,6 @@ fn the_name_plate_faction_branch_picks_player_red_blue_over_the_reaction_swatch(
         }),
     );
     assert_eq!(decide(&mut s), "red");
-    // A friendly NPC (same reaction 5, not a player) → the reaction swatch (green), unchanged.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -106,7 +99,6 @@ fn the_name_plate_faction_branch_picks_player_red_blue_over_the_reaction_swatch(
         }),
     );
     assert_eq!(decide(&mut s), "reaction");
-    // UnitIsPlayer itself: 1 for a player, nil otherwise.
     assert!(s
         .eval::<bool>(r#"return UnitIsPlayer("target") == nil"#)
         .unwrap());
@@ -132,8 +124,7 @@ fn unit_level_reads_minus_one_when_the_level_cant_be_told() {
         level: 3,
         ..Default::default()
     });
-    // A hostile 10+ levels up (reaction 2, level 13 vs player 3) → −1: the target frame's
-    // skull branch (TargetFrame_CheckLevel's `level <= 0`).
+    // Hostile (2) and 10 levels above the player: -1, the target frame's skull.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -144,7 +135,7 @@ fn unit_level_reads_minus_one_when_the_level_cant_be_told() {
         }),
     );
     assert_eq!(s.eval::<i64>(r#"return UnitLevel("target")"#).unwrap(), -1);
-    // One level short of the band (12 vs 3) → the raw number.
+    // 9 above: the level.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -155,7 +146,7 @@ fn unit_level_reads_minus_one_when_the_level_cant_be_told() {
         }),
     );
     assert_eq!(s.eval::<i64>(r#"return UnitLevel("target")"#).unwrap(), 12);
-    // The same 10-up gap on a NEUTRAL (reaction 4) tells its level — the gate is hostile-only.
+    // Neutral (4) at 10 above: the level, as the gate is hostile-only.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -166,7 +157,7 @@ fn unit_level_reads_minus_one_when_the_level_cant_be_told() {
         }),
     );
     assert_eq!(s.eval::<i64>(r#"return UnitLevel("target")"#).unwrap(), 13);
-    // A world boss (creature rank 3) hides its level regardless of the gap.
+    // A world boss (rank 3) at any gap: -1.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -178,7 +169,6 @@ fn unit_level_reads_minus_one_when_the_level_cant_be_told() {
         }),
     );
     assert_eq!(s.eval::<i64>(r#"return UnitLevel("target")"#).unwrap(), -1);
-    // A PLAYER never reads −1 (rank/reaction notwithstanding).
     s.set_unit(
         "target",
         Some(UnitState {
@@ -190,8 +180,7 @@ fn unit_level_reads_minus_one_when_the_level_cant_be_told() {
         }),
     );
     assert_eq!(s.eval::<i64>(r#"return UnitLevel("target")"#).unwrap(), 60);
-    // A raw level 0 (unstreamed) returns VERBATIM — never −1 (`0x517fc0` pushes the
-    // raw field; only the boss/hostile legs substitute). Same skull outcome via `<= 0`.
+    // An unstreamed level 0 answers 0, not -1: `0x517fc0` pushes the raw field.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -208,7 +197,7 @@ fn unit_level_reads_minus_one_when_the_level_cant_be_told() {
 fn corpse_can_attack_and_green_range_bindings() {
     use crate::script::PlayerReqState;
     let mut s = UiScript::new().unwrap();
-    // UnitIsCorpse: a pure TYPEID_CORPSE object check (`0x5161c0`) — a DEAD unit is NOT a corpse…
+    // `UnitIsCorpse` is an object-type check (`0x5161c0`): a dead unit is not a corpse.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -220,7 +209,6 @@ fn corpse_can_attack_and_green_range_bindings() {
     assert!(s
         .eval::<bool>(r#"return UnitIsCorpse("target") == nil"#)
         .unwrap());
-    // …only a resolved corpse world object is.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -233,8 +221,7 @@ fn corpse_can_attack_and_green_range_bindings() {
         s.eval::<i64>(r#"return UnitIsCorpse("target")"#).unwrap(),
         1
     );
-    // UnitCanAttack reads the app-fed 0x606980 verdict off the non-player token, both
-    // argument orders; false → nil.
+    // `UnitCanAttack` reads the non-player token's verdict in either argument order.
     assert!(s
         .eval::<bool>(r#"return UnitCanAttack("player", "target") == nil"#)
         .unwrap());
@@ -259,8 +246,7 @@ fn corpse_can_attack_and_green_range_bindings() {
     assert!(s
         .eval::<bool>(r#"return UnitIsCorpse("target") == nil"#)
         .unwrap());
-    // GetQuestGreenRange: the grey band for the player's level — 4 at level 3, 9 at 46,
-    // 12 clamped past the table (the byte-verified GREY_BAND).
+    // `GetQuestGreenRange`: the grey band for the player's level, 12 past the table.
     for (pl, want) in [(3u32, 4i64), (46, 9), (120, 12)] {
         s.set_player_req_state(PlayerReqState {
             level: pl,
@@ -278,9 +264,8 @@ fn corpse_can_attack_and_green_range_bindings() {
 fn target_unit_queues_the_token_for_the_app_to_resolve() {
     use crate::script::SelectionRequest;
     let mut s = UiScript::new().unwrap();
-    // Nothing queued until a call lands.
     assert!(s.take_selection_requests().is_empty());
-    // Each call queues its raw token, in order; a nil token is ignored.
+    // A nil token is not queued.
     s.eval::<()>(r#"TargetUnit("player")"#).unwrap();
     s.eval::<()>(r#"TargetUnit("target")"#).unwrap();
     s.eval::<()>(r#"TargetUnit(nil)"#).unwrap();
@@ -291,14 +276,10 @@ fn target_unit_queues_the_token_for_the_app_to_resolve() {
             SelectionRequest::Unit("target".into()),
         ]
     );
-    // The drain is a take — a second read is empty.
     assert!(s.take_selection_requests().is_empty());
 }
 
-/// The three verbs share ONE queue, and the queue keeps their call order — which is the whole
-/// reason it is one queue (`0x489a40` is one function for all of them, and a macro can observe
-/// the order). A nil `AssistUnit` argument is dropped like `TargetUnit`'s, and
-/// `TargetLastEnemy()` names no unit at all.
+/// A nil `AssistUnit` argument is dropped like `TargetUnit`'s.
 #[test]
 fn the_selection_queue_carries_all_three_verbs_in_call_order() {
     use crate::script::SelectionRequest;
@@ -318,9 +299,8 @@ fn the_selection_queue_carries_all_three_verbs_in_call_order() {
     assert!(s.take_selection_requests().is_empty());
 }
 
-/// `TargetNearestFriend`'s reverse flag, read exactly as `0x6f1c10(idx 1, default 0)` does:
-/// absent or nil is forward, and 1.12's own `Bindings.xml` note — *"1 (or \"true\") means
-/// reverse!"* — is why a boolean and a number both count. A numeric `0` is forward.
+/// The reverse flag as `0x6f1c10` reads it: absent, nil and 0 are forward, 1 and `true` reverse
+/// (`Bindings.xml:458`).
 #[test]
 fn target_nearest_friend_queues_its_reverse_flag() {
     let mut s = UiScript::new().unwrap();
@@ -361,8 +341,6 @@ fn set_unit_is_read_by_the_bindings() {
 #[test]
 fn absent_token_reports_not_existing_with_zero_numbers() {
     let s = UiScript::new().unwrap();
-    // **nil, not `false`** — the family's false leg (decision 2043). `== nil` is the comparison a
-    // boolean would invert, so it is the one worth asserting.
     assert!(s
         .eval::<bool>(r#"return UnitExists("target") == nil"#)
         .unwrap());
@@ -398,21 +376,17 @@ fn a_dead_unit_reports_dead_and_zero_health() {
     assert_eq!(s.eval::<i64>(r#"return UnitExists("target")"#).unwrap(), 1);
     assert_eq!(s.eval::<i64>(r#"return UnitIsDead("target")"#).unwrap(), 1);
     assert_eq!(s.eval::<i64>(r#"return UnitHealth("target")"#).unwrap(), 0);
-    // Name unknown (no name-query yet) → `UNKNOWNOBJECT`, never nil: the unit RESOLVED, and the
-    // reference pushes nil for a zero GUID only (decision 2002; the shape is pinned below). A bare
-    // VM carries no GlobalStrings, so this is the binary's own literal.
+    // A resolved unit with no name yet reads `UNKNOWNOBJECT`, never nil; a bare VM has no
+    // GlobalStrings, so this is the literal fallback.
     assert_eq!(
         s.eval::<String>(r#"return UnitName("target")"#).unwrap(),
         "Unknown Being"
     );
 }
 
-/// `UnitName`'s value 1 is nil in exactly two cases — a zero GUID, and the `"player"` fast path
-/// over an empty local-name buffer — and a STRING everywhere else: the cached name, or
-/// `FrameScript_GetText("UNKNOWNOBJECT")` for a unit that resolved but whose name the cache has not
-/// answered (`0x517020`; `0x609324`). The stock stable window concatenates the answer on
-/// `UNIT_PET` (`PetStable.lua:129`), the instant a called pet's name is still in flight — the
-/// director's `attempt to concatenate a nil value` dialog (decision 2002).
+/// `UnitName` (`0x517020`) is nil only for a zero guid or an empty `"player"` record, else a
+/// string: the name, or `UNKNOWNOBJECT` while it is in flight (`0x609324`). `PetStable.lua:129`
+/// concatenates it on `UNIT_PET`, before a called pet's name arrives.
 #[test]
 fn unitname_reads_unknownobject_for_a_resolved_unit_whose_name_is_in_flight() {
     let mut s = UiScript::new().unwrap();
@@ -426,24 +400,23 @@ fn unitname_reads_unknownobject_for_a_resolved_unit_whose_name_is_in_flight() {
     };
     s.set_unit("pet", Some(pending.clone()));
 
-    // No GlobalStrings loaded: the literal the binary falls back to (`0x860fa4`).
+    // No GlobalStrings: the literal fallback (`0x860fa4`).
     assert_eq!(
         s.eval::<String>(r#"return UnitName("pet")"#).unwrap(),
         "Unknown Being"
     );
-    // With the stock global seated, its (localizable) value — read out of the VM, not baked in.
     s.run(r#"UNKNOWNOBJECT = "Unknown""#).unwrap();
     assert_eq!(
         s.eval::<String>(r#"return UnitName("pet")"#).unwrap(),
         "Unknown"
     );
-    // An EMPTY global is the same miss as an absent one (`0x609324`'s empty check).
+    // An empty global is the same miss as an absent one.
     s.run(r#"UNKNOWNOBJECT = """#).unwrap();
     assert_eq!(
         s.eval::<String>(r#"return UnitName("pet")"#).unwrap(),
         "Unknown Being"
     );
-    // Still two returns, the second nil (1840).
+    // Two returns, the realm nil.
     assert_eq!(
         s.eval::<i64>(r#"local t = {UnitName("pet")}; return table.getn(t)"#)
             .unwrap(),
@@ -454,7 +427,6 @@ fn unitname_reads_unknownobject_for_a_resolved_unit_whose_name_is_in_flight() {
         .eval::<bool>(r#"local _, realm = UnitName("pet"); return realm == nil"#)
         .unwrap());
 
-    // The name lands: the string, and nothing else changes.
     let mut named = pending.clone();
     named.name = Some("Snarl".into());
     s.set_unit("pet", Some(named));
@@ -463,7 +435,7 @@ fn unitname_reads_unknownobject_for_a_resolved_unit_whose_name_is_in_flight() {
         "Snarl"
     );
 
-    // The `"player"` fast path never reaches the resolver: an empty local-name buffer is nil.
+    // `"player"` reads the record, never the snapshot: an empty record is nil.
     s.set_unit("player", Some(pending));
     assert!(s
         .eval::<bool>(r#"return UnitName("player") == nil"#)
@@ -472,7 +444,7 @@ fn unitname_reads_unknownobject_for_a_resolved_unit_whose_name_is_in_flight() {
         .eval::<bool>(r#"return UnitName("PLAYER") == nil"#)
         .unwrap());
 
-    // A token nothing resolves is GUID 0 → nil (the shape `absent_token_…` pins too).
+    // A token that resolves nothing is guid 0: nil.
     assert!(s
         .eval::<bool>(r#"return UnitName("target") == nil"#)
         .unwrap());
@@ -482,8 +454,7 @@ fn unitname_reads_unknownobject_for_a_resolved_unit_whose_name_is_in_flight() {
 fn power_bindings_read_the_active_type() {
     let mut s = UiScript::new().unwrap();
     s.set_unit("player", Some(player())); // rage 35/100
-                                          // ONE value. The Era `(type, "RAGE")` pair does not exist in 5875 — `0x517940` pushes a
-                                          // number at every one of its four live `ret`s and never a string (decision 1840).
+                                          // One value: `0x517940` pushes a number, never a string.
     assert_eq!(
         s.eval::<i64>(r#"return UnitPowerType("player")"#).unwrap(),
         1
@@ -493,19 +464,14 @@ fn power_bindings_read_the_active_type() {
         s.eval::<i64>(r#"return UnitManaMax("player")"#).unwrap(),
         100
     );
-    // **The 1.12 verbs take one argument and report the ACTIVE power**, whatever it is — this
-    // unit is a rage user and `UnitMana` reads 35 rage, which looks wrong and is exactly right
-    // (`UnitFrame.lua`: `local currValue = UnitMana(unit)` for every power type). Asking about a
-    // specific type is `UnitPowerType(unit)` first; there is no second argument to pass, and the
-    // Era pair that had one is gone (decision 1190's beyond-1.12 list, 1188 phase 5).
+    // `UnitMana` reports the active power, here rage, as `UnitFrame.lua:218` reads it for every
+    // type; `UnitPower` and `UnitPowerMax` are not 1.12 verbs.
     assert!(
         s.eval::<bool>("return UnitPower == nil and UnitPowerMax == nil")
             .unwrap(),
         "the Era spellings must not linger beside the 1.12 ones"
     );
-    // An absent unit: the NUMBER 0 — the same value Mana has, and never nil. Load-bearing rather
-    // than tidy: stock `UnitFrame.lua:122` writes `ManaBarColor[UnitPowerType(unitFrame.unit)]`,
-    // and a nil there indexes nothing.
+    // An absent unit is the number 0, never nil: `UnitFrame.lua:122` indexes `ManaBarColor` by it.
     assert_eq!(
         s.eval::<i64>(r#"return UnitPowerType("target")"#).unwrap(),
         0
@@ -515,7 +481,6 @@ fn power_bindings_read_the_active_type() {
 #[test]
 fn get_money_reads_the_pushed_purse() {
     let mut s = UiScript::new().unwrap();
-    // No feed yet: 0 copper.
     assert_eq!(s.eval::<i64>("return GetMoney()").unwrap(), 0);
     s.set_money(123_456);
     assert_eq!(s.eval::<i64>("return GetMoney()").unwrap(), 123_456);
@@ -524,7 +489,6 @@ fn get_money_reads_the_pushed_purse() {
 #[test]
 fn unit_xp_reads_the_player_globals_only_for_the_player_token() {
     let mut s = UiScript::new().unwrap();
-    // No feed yet: 0/0.
     assert_eq!(s.eval::<i64>(r#"return UnitXP("player")"#).unwrap(), 0);
     assert_eq!(s.eval::<i64>(r#"return UnitXPMax("player")"#).unwrap(), 0);
     s.set_player_xp(4200, 6000);
@@ -533,7 +497,6 @@ fn unit_xp_reads_the_player_globals_only_for_the_player_token() {
         s.eval::<i64>(r#"return UnitXPMax("player")"#).unwrap(),
         6000
     );
-    // Any non-player token reports 0 (no creature/other unit exposes XP — the live shape).
     assert_eq!(s.eval::<i64>(r#"return UnitXP("target")"#).unwrap(), 0);
     assert_eq!(s.eval::<i64>(r#"return UnitXPMax("target")"#).unwrap(), 0);
 }
@@ -579,7 +542,6 @@ fn party_frame_predicates_report_1_or_nil() {
         .eval::<bool>(r#"return UnitIsPVPFreeForAll("party1") == nil"#)
         .unwrap());
 
-    // Flip every flag: the false/true cases aren't just "always true".
     s.set_unit(
         "party1",
         Some(UnitState {
@@ -608,7 +570,6 @@ fn party_frame_predicates_report_1_or_nil() {
         1
     );
 
-    // An absent token reports nil regardless of any flag's zero value.
     assert!(s
         .eval::<bool>(r#"return UnitIsConnected("party2") == nil"#)
         .unwrap());
@@ -629,10 +590,7 @@ fn unit_race_class_sex_report_the_snapshot_or_the_absent_shape() {
         ("Warrior".into(), "WARRIOR".into())
     );
     assert_eq!(s.eval::<i64>(r#"return UnitSex("player")"#).unwrap(), 3);
-    // An absent token: the two string pairs go nil, nil — but **`UnitSex` answers the number 2**,
-    // not nil. It is a numeric getter, and `0x517f9f` pushes the constant double 2.0 on the
-    // unresolved leg exactly as `UnitLevel`/`UnitMana`/`GetMoney` push 0.0 on theirs (decision
-    // 2118). The shapes table has no nil alternative for this row at all.
+    // An absent token: `nil, nil` for the pairs, but `UnitSex` answers the number 2 (`0x517f9f`).
     assert!(s
         .eval::<bool>(r#"local a, b = UnitRace("target") return a == nil and b == nil"#)
         .unwrap());
@@ -640,7 +598,6 @@ fn unit_race_class_sex_report_the_snapshot_or_the_absent_shape() {
         .eval::<bool>(r#"local a, b = UnitClass("target") return a == nil and b == nil"#)
         .unwrap());
     assert_eq!(s.eval::<i64>(r#"return UnitSex("target")"#).unwrap(), 2);
-    // A snapshot whose race/class haven't resolved yet (feed pending): same nils.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -651,13 +608,11 @@ fn unit_race_class_sex_report_the_snapshot_or_the_absent_shape() {
     assert!(s
         .eval::<bool>(r#"local a, b = UnitRace("target") return a == nil and b == nil"#)
         .unwrap());
-    // Same for a seated body whose sex byte has not streamed: the number 2, never nil.
+    // An unstreamed sex byte reads 2 too.
     assert_eq!(s.eval::<i64>(r#"return UnitSex("target")"#).unwrap(), 2);
 }
 
-/// `UnitFactionGroup` returns the (english, localized) pair the PvP-icon law reads, and `nil, nil`
-/// for a unit with no side — the state the reference's `if ( factionGroup and … )` gate exists
-/// for (decision 0646 §1). `TogglePVP` queues one toggle per call.
+/// `UnitFactionGroup` answers (English, localized), or `nil, nil` for a unit with no side.
 #[test]
 fn faction_group_pair_and_the_pvp_toggle() {
     let mut s = UiScript::new().unwrap();
@@ -672,17 +627,11 @@ fn faction_group_pair_and_the_pvp_toggle() {
     let (english, localized) = s
         .eval::<(String, String)>(r#"return UnitFactionGroup("target")"#)
         .unwrap();
-    // With no localized name fed, the second return falls back to the English one rather than nil:
-    // FactionGroup.dbc leaves `Name0` empty for some rows, and nil here would blank a tooltip the
-    // reference fills.
+    // With no localized name fed, the second return falls back to the English one, not nil.
     assert_eq!((english.as_str(), localized.as_str()), ("Horde", "Horde"));
 
-    // **The two halves are DIFFERENT fields and this is the assertion that says so.** They are
-    // FactionGroup.dbc's `InternalName` and `Name0`; only on enUS do they hold the same word, which
-    // is why returning one twice went unnoticed. The first is concatenated into a texture path by
-    // every stock consumer (`"…\UI-PVP-"..factionGroup` — PlayerFrame.lua:68, TargetFrame.lua:198,
-    // PartyMemberFrame.lua:125; `"…\Battleground-"..` — BattlefieldFrame.lua:195), so a localized
-    // string there names a file that does not exist. This fixture is a deDE-shaped client.
+    // A deDE-shaped client: the halves are `InternalName` and `Name0`, and stock builds texture
+    // paths from the English first (`TargetFrame.lua:198`, `BattlefieldFrame.lua:195`).
     s.set_unit(
         "target",
         Some(UnitState {
@@ -701,7 +650,6 @@ fn faction_group_pair_and_the_pvp_toggle() {
         "the FIRST return is the English InternalName — a texture path is built from it"
     );
 
-    // No side (a Monster/neutral template, or a unit whose template hasn't streamed).
     s.set_unit(
         "target",
         Some(UnitState {
@@ -713,9 +661,7 @@ fn faction_group_pair_and_the_pvp_toggle() {
     assert!(s
         .eval::<bool>(r#"local a, b = UnitFactionGroup("target") return a == nil and b == nil"#)
         .unwrap());
-    // An absent unit answers the same way. (This read `"focus"` until the unrecognised-token raise
-    // landed — a token 1.12 does not have at all, so it now raises rather than being "absent". The
-    // question the line means to ask needs a RECOGNISED token that names nothing.)
+    // An absent unit, a recognised token naming nothing, answers the same.
     assert!(s
         .eval::<bool>(r#"local a = UnitFactionGroup("party4") return a == nil"#)
         .unwrap());
@@ -730,9 +676,8 @@ fn faction_group_pair_and_the_pvp_toggle() {
     assert_eq!(s.take_pvp_toggles(), 0, "the drain empties the queue");
 }
 
-/// `UnitClassification` (decision 0782, byte-verified table `0x850424`): five words indexed by the
-/// gated rank, a STRING for every input — including an absent token, which the binary answers
-/// `"normal"` for (its unresolved path loads index 0), never nil.
+/// The word table at `0x850424` by gated rank answers a string for every input: an absent token
+/// reads index 0, "normal", never nil.
 #[test]
 fn unit_classification_reads_the_five_word_table() {
     let mut s = UiScript::new().unwrap();
@@ -760,9 +705,6 @@ fn unit_classification_reads_the_five_word_table() {
         );
     }
 
-    // No snapshot at all, and a missing argument: still "normal", never nil. The target frame's
-    // border branch compares this against string literals, so a nil here would be a Lua error the
-    // reference cannot produce.
     s.set_unit("target", None);
     assert_eq!(
         s.eval::<String>(r#"return UnitClassification("target")"#)
@@ -779,9 +721,8 @@ fn unit_classification_reads_the_five_word_table() {
 
 // ── `UnitAffectingCombat` and `TargetByName` ────────────────────────────────────────────────────
 
-/// `UnitAffectingCombat` → the number 1 / nil, and **one arm serves both "not in combat" and "no
-/// such unit"** (`0x517e48` and `0x517e5c` jump to the same `0x517e73`). That indistinguishability
-/// is the behaviour, not a shortcut: an addon must not be able to probe existence with this verb.
+/// Not in combat and no such unit share one nil arm: `0x517e48` and `0x517e5c` both jump to
+/// `0x517e73`.
 #[test]
 fn unit_affecting_combat_is_one_or_nil_and_hides_the_missing_unit() {
     let mut s = UiScript::new().unwrap();
@@ -804,19 +745,14 @@ fn unit_affecting_combat_is_one_or_nil_and_hides_the_missing_unit() {
             .unwrap(),
         "an unresolvable token is the SAME nil a peaceful unit gives"
     );
-    // **A number is accepted and stringified — and that is exactly why it RAISES.** The gate
-    // `0x6f3510` is number-OR-string, so `5` is coerced via `%.14g` to the token `"5"`; `"5"` then
-    // matches none of the resolver's nine prefixes and falls into
-    // `luaL_error("Unknown unit name: %s")`. This assertion read `== nil` and "it does not raise"
-    // until corrected: the acceptance was right, the conclusion was not.
+    // A number passes the gate (`0x6f3510`) as the token "5", which matches no prefix and raises.
     assert!(
         s.run("UnitAffectingCombat(5)").is_err(),
         "a number is coerced to a token that matches nothing, so it raises"
     );
 }
 
-/// A missing or wrong-typed argument **raises** — `0x6f4940` is `luaL_error` and does not return,
-/// so the caller's statement is abandoned rather than continuing with a nil.
+/// The usage raise is `luaL_error` (`0x6f4940`), which does not return.
 #[test]
 fn unit_affecting_combat_raises_on_a_bad_argument() {
     let s = UiScript::new().unwrap();
@@ -831,8 +767,8 @@ fn unit_affecting_combat_raises_on_a_bad_argument() {
     }
 }
 
-/// `TargetByName(name [, exactMatch])` queues the name **and the second argument** — the flag the
-/// slash command has no way to supply, which turns the resolver's longest-common-prefix tier off.
+/// `exactMatch`, which the slash command cannot pass, turns off the resolver's
+/// longest-common-prefix tier.
 #[test]
 fn target_by_name_queues_the_name_and_the_exact_flag() {
     let mut s = UiScript::new().unwrap();
@@ -855,7 +791,7 @@ fn target_by_name_queues_the_name_and_the_exact_flag() {
     );
     assert!(s.take_target_by_name_requests().is_empty());
 
-    // A missing/wrong-typed name raises (`0x489d69 call 0x6f3510` → `0x489de1`).
+    // A missing name raises: the gate call at `0x489d69` fails to `0x489de1`.
     let err = s.eval::<mlua::Value>("return TargetByName()").unwrap_err();
     assert!(
         format!("{err}").contains(r#"Usage: TargetByName("name")"#),
@@ -863,12 +799,7 @@ fn target_by_name_queues_the_name_and_the_exact_flag() {
     );
 }
 
-/// **`UnitIsCharmed` — the number `1`, the nil, and the asymmetry.**
-///
-/// `KLHThreatMeter\Code\KTM_My.lua:533` is the corpus line blocked on it; seven other addons name
-/// it. The binding (`0x516cf0`) reads `UNIT_FIELD_CHARMEDBY != 0` — a 64-bit non-zero test on
-/// fields 10/11, **not** a `UNIT_FIELD_FLAGS` bit, which is what a boolean-shaped unit question
-/// invites you to assume.
+/// `0x516cf0` tests `UNIT_FIELD_CHARMEDBY` (fields 10-11) non-zero, not a `UNIT_FIELD_FLAGS` bit.
 #[test]
 fn unit_is_charmed_answers_one_or_nil_and_only_for_the_charmed_side() {
     let mut s = UiScript::new().unwrap();
@@ -877,8 +808,6 @@ fn unit_is_charmed_answers_one_or_nil_and_only_for_the_charmed_side() {
     mc.charmed = true;
     s.set_unit("target", Some(mc));
 
-    // A hit is the NUMBER 1 — `lua_pushnumber` writes tag 3; tag 1 (boolean) is never written on
-    // either arm, so `== true` in an addon must NOT match.
     assert_eq!(
         s.eval::<i64>(r#"return UnitIsCharmed("target")"#).unwrap(),
         1
@@ -895,7 +824,6 @@ fn unit_is_charmed_answers_one_or_nil_and_only_for_the_charmed_side() {
         "exactly one value on the hit path"
     );
 
-    // An uncharmed unit and an absent one both answer nil — and nil, not `false` and not `0`.
     for token in ["player", "party1"] {
         assert!(
             s.eval::<Option<i64>>(&format!(r#"return UnitIsCharmed("{token}")"#))
@@ -911,8 +839,6 @@ fn unit_is_charmed_answers_one_or_nil_and_only_for_the_charmed_side() {
         );
     }
 
-    // **The asymmetry.** The field is "who charms me", never "whom I charm", so the charmer reads
-    // nil while its victim reads 1 — here the player is doing the charming and is not charmed.
     assert!(
         s.eval::<Option<i64>>(r#"return UnitIsCharmed("player")"#)
             .unwrap()
@@ -921,19 +847,8 @@ fn unit_is_charmed_answers_one_or_nil_and_only_for_the_charmed_side() {
     );
 }
 
-/// **`UnitIsPlusMob` reads a FLAG BIT, not the creature rank** (B385; `0x516d40`).
-///
-/// Decision 2209. The name says "elite" and its table neighbour `UnitClassification` answers off
-/// the gated rank, so the natural implementation is `rank > 0`. The binary's is not: it takes
-/// `UNIT_FIELD_FLAGS` and tests bit 6 (`UNIT_FLAG_PLUS_MOB 0x40`), never calling the rank getter
-/// `0x605620`). The two normally
-/// agree because the server derives the bit from the rank — so **rare** answers 1 here, not just
-/// elite — and they part on the unit whose creature-cache record has not arrived, which still
-/// carries its own flags while its rank reads 0.
-///
-/// That divergence is the whole reason this is a test and not a reading: a `rank > 0`
-/// implementation passes every ordinary case and is wrong exactly where the flag is the only
-/// thing the client has.
+/// `0x516d40` tests `UNIT_FLAG_PLUS_MOB` (`0x40`) and never the rank getter (`0x605620`). The
+/// server sets the bit from the rank, so the two part only while the creature record is missing.
 #[test]
 fn unit_is_plus_mob_reads_the_flag_bit_and_not_the_rank() {
     let with = |flags: u32, rank: u32| UnitState {
@@ -946,8 +861,7 @@ fn unit_is_plus_mob_reads_the_flag_bit_and_not_the_rank() {
     let mut s = UiScript::new().unwrap();
     s.set_unit("player", Some(player()));
 
-    // The ordinary agreeing cases: the server sets the bit on `!IsPet() && rank > 0`, so elite,
-    // rare-elite, world boss AND rare all carry it, and a normal mob does not.
+    // The server sets the bit on `!IsPet() && rank > 0` (`Creature.h:185`), so rare carries it.
     for (rank, word) in [
         (1u32, "elite"),
         (2, "rareelite"),
@@ -969,16 +883,14 @@ fn unit_is_plus_mob_reads_the_flag_bit_and_not_the_rank() {
         "a normal mob answers nil"
     );
 
-    // ── The two legs a rank read gets wrong ──
-    // The flag WITHOUT a rank: an unstreamed creature, whose cache record has not arrived, still
-    // has its own descriptor. `rank > 0` would call it normal; the client says 1.
+    // The flag without a rank: a creature whose cache record has not arrived.
     s.set_unit("target", Some(with(0x40, 0)));
     assert_eq!(
         s.eval::<i64>(r#"return UnitIsPlusMob("target")"#).unwrap(),
         1,
         "the bit alone decides — no creature-cache rank is consulted"
     );
-    // A rank WITHOUT the flag — a player's pet, which the server excludes (`!IsPet()`).
+    // A rank without the flag: a pet, which the server excludes.
     s.set_unit("target", Some(with(0x8, 2)));
     assert!(
         s.eval::<Option<i64>>(r#"return UnitIsPlusMob("target")"#)
@@ -987,9 +899,8 @@ fn unit_is_plus_mob_reads_the_flag_bit_and_not_the_rank() {
         "no bit, no plus mob — a neighbouring flag (player-controlled) must not read as one"
     );
 
-    // The token grammar: quiet on nil/absent (one of 1834's thirteen with no `lua_isstring`
-    // gate), quiet on a recognised token naming nothing, and a raise on an unrecognised one —
-    // the body reaches the shared resolver through `0x515940`.
+    // One of the 13 with no `lua_isstring` gate: nil is quiet, and an unrecognised token raises
+    // through the resolver (`0x515940`).
     assert!(s.run("UnitIsPlusMob()").is_ok(), "nil token stays quiet");
     assert!(
         s.run("UnitIsPlusMob(nil)").is_ok(),
@@ -1008,17 +919,7 @@ fn unit_is_plus_mob_reads_the_flag_bit_and_not_the_rank() {
     );
 }
 
-/// **Unit tokens fold case, because the client's resolver does.**
-///
-/// `0x515970` compares every one of its literals with `SStrCmpI` → `_strnicmp`, whose fold is
-/// `'A'..'Z' += 0x20`; not one of its ten compares reaches the case-sensitive sibling. So this is
-/// a NARROWING fix — the real client resolves these and we did not — rather than the superset 1189
-/// had to take back out.
-///
-/// `Accountant.lua:107` is the corpus line that paid for it: `UnitFactionGroup("Player")`, capital
-/// P, whose nil made `Accountant_SaveData[realm][faction]` a nil table index at l.192 and ended the
-/// addon's session. Roughly ten addons pass `Player`, `PLAYER`, `Target`, `Pet`, `PARTY`, `NPC`,
-/// `Mouseover` or `"Raid"..i`.
+/// The resolver (`0x515970`) compares every literal with `_strnicmp`, folding ASCII case.
 #[test]
 fn a_unit_token_resolves_whatever_its_case() {
     let mut s = UiScript::new().unwrap();
@@ -1027,7 +928,6 @@ fn a_unit_token_resolves_whatever_its_case() {
     tgt.name = Some("Hogger".into());
     s.set_unit("target", Some(tgt));
 
-    // Every spelling names the same unit — the getter, the number and the predicate alike.
     for spelling in ["player", "Player", "PLAYER", "PlAyEr"] {
         assert_eq!(
             s.eval::<String>(&format!(r#"return UnitName("{spelling}")"#))
@@ -1054,10 +954,8 @@ fn a_unit_token_resolves_whatever_its_case() {
         );
     }
 
-    // **The two-unit call, which the map's fold does not cover on its own.**
-    // `pick_unit_token` chooses "whichever arg is not the player"; with a case-sensitive test,
-    // `("Player", "target")` reads as a non-player FIRST arg and the call answers about the wrong
-    // unit — a wrong answer rather than a missing one.
+    // `pick_unit_token`'s own `"player"` test folds too, or `"Player"` would read as the other
+    // unit.
     assert!(
         s.eval::<bool>(
             r#"return UnitIsEnemy("Player", "target") == UnitIsEnemy("player", "target")"#
@@ -1066,9 +964,6 @@ fn a_unit_token_resolves_whatever_its_case() {
         "the directional pick folds case too"
     );
 
-    // An unseated but RECOGNISED token is still absent whatever its case — folding must not invent
-    // units. (`bogus` moved out of this list when the unrecognised-token raise landed: it is not
-    // "absent", it is not a unit token at all, and the client says so.)
     for spelling in ["Party1", "PARTY1", "raid9", "MouseOver"] {
         assert!(
             !s.eval::<bool>(&format!(r#"return UnitExists("{spelling}")"#))
@@ -1078,8 +973,7 @@ fn a_unit_token_resolves_whatever_its_case() {
     }
 }
 
-/// The fold is on the way **IN** as well as out: a feed that pushes `"Target"` must not create a
-/// second entry shadowing `"target"`, which is what a lookup-only fold would allow.
+/// A `"Target"` push must not create an entry shadowing `"target"`.
 #[test]
 fn seating_a_token_folds_its_key_too() {
     let mut s = UiScript::new().unwrap();
@@ -1092,7 +986,6 @@ fn seating_a_token_folds_its_key_too() {
         "a token seated as \"Target\" is readable as \"target\""
     );
 
-    // …and clearing it through the other spelling really clears it, rather than leaving a shadow.
     s.set_unit("TARGET", None);
     assert!(
         s.eval::<bool>(r#"return UnitExists("target") == nil"#)
@@ -1101,20 +994,12 @@ fn seating_a_token_folds_its_key_too() {
     );
 }
 
-/// **An unrecognised token RAISES; a recognised one that names nothing is a quiet nil.**
-///
-/// `0x515970` falls off the end of its nine compares into `luaL_error(L, "Unknown unit name: %s")`,
-/// which longjmps and never returns. Ours answered nil for everything unknown — 1203's shape
-/// pointed the other way, a failure the client reports and we swallowed.
-///
-/// The split is THREE-way, and the two quiet legs are the ones a "raise on nil" implementation gets
-/// wrong.
+/// `0x515970` ends its nine compares in `luaL_error(L, "Unknown unit name: %s")`.
 #[test]
 fn an_unrecognised_unit_token_raises_and_a_recognised_empty_one_does_not() {
     let mut s = UiScript::new().unwrap();
     s.set_unit("player", Some(player()));
 
-    // RAISE: nothing the resolver's compares match.
     for bogus in ["bogus", "focus", "boss1", "arena1"] {
         let err = s
             .run(&format!(r#"UnitName("{bogus}")"#))
@@ -1125,12 +1010,10 @@ fn an_unrecognised_unit_token_raises_and_a_recognised_empty_one_does_not() {
             "the raise carries the client's own text and the offending token: {err}"
         );
     }
-    // `npc` is the SOLE full-string compare, so a suffix on it matches nothing at all.
+    // `npc` is the one full-string compare, so a suffix on it matches nothing.
     assert!(s.run(r#"UnitName("npctarget")"#).is_err());
-    // …while `npc` itself is recognised, folded like everything else.
     assert!(s.run(r#"UnitName("NPC")"#).is_ok());
 
-    // QUIET NIL, leg 1: a recognised token naming nothing here.
     for absent in [
         "party5",
         "raid17",
@@ -1146,8 +1029,7 @@ fn an_unrecognised_unit_token_raises_and_a_recognised_empty_one_does_not() {
             "{absent} is recognised and absent — nil, not a raise"
         );
     }
-    // QUIET NIL, leg 2: a recognised PREFIX with a junk suffix. The compares are prefix tests that
-    // stop at either NUL, so `playerfoo` matches `player` and never reaches the raise.
+    // A recognised prefix with a suffix is quiet too: the compares stop at either NUL.
     for junk in ["playerfoo", "raidx", "petx", "targetish"] {
         assert!(
             s.eval::<Option<String>>(&format!(r#"return UnitName("{junk}")"#))
@@ -1157,26 +1039,21 @@ fn an_unrecognised_unit_token_raises_and_a_recognised_empty_one_does_not() {
              implementation that raises on \"did not resolve\" gets wrong."
         );
     }
-    // QUIET NIL, leg 3: the empty string — which passes the `lua_isstring` gate (it IS a string)
-    // and dies quietly in the resolver's own NULL/empty guard.
+    // Quiet nil: the empty string passes the `lua_isstring` gate and stops at the resolver's
+    // empty guard.
     assert!(s.run(r#"UnitName("")"#).is_ok());
 
-    // …but an ABSENT or nil argument is NOT leg 3, and this line used to assert that it was.
-    // `UnitName 0x517020` gates its token position at `0x517048` and raises
-    // `Usage: UnitName("unit")` (`0x850ee0`); `luaL_error` does not return. The comment this
-    // replaces said the per-binding gates were "not uniform … only two poles verified", which was
-    // true when it was written — all 83 entries of the table at `0x850438` gate and raise in 53
-    // cases, and only 13 unit-token bindings are quiet. Decision 1834.
+    // An absent or nil argument raises `Usage: UnitName("unit")` (`0x850ee0`) from `UnitName`'s
+    // own gate (`0x517048`).
     assert!(s.run("UnitName()").is_err(), "absent argument raises");
     assert!(s.run("UnitName(nil)").is_err(), "nil argument raises");
-    // A NUMBER passes the gate — `lua_isstring` admits tag 3 — and is handed to the resolver as
-    // "5", which then raises the family's OTHER message rather than the `Usage:` one.
+    // A number passes the gate as "5" and raises the resolver's message instead.
     assert!(
         s.run("UnitName(5)").is_err(),
         "a number reaches the resolver"
     );
 
-    // The thirteen that stay quiet, three of them here: no gate at all, so nil is fine.
+    // Three of the 13 with no gate, where nil is quiet.
     for quiet in ["UnitExists", "UnitIsVisible", "UnitClassification"] {
         assert!(
             s.run(&format!("{quiet}()")).is_ok(),
@@ -1184,30 +1061,20 @@ fn an_unrecognised_unit_token_raises_and_a_recognised_empty_one_does_not() {
         );
     }
 
-    // A two-unit call gates BOTH arguments.
+    // A two-unit call checks both tokens.
     assert!(s.run(r#"UnitIsUnit("player", "bogus")"#).is_err());
     assert!(s.run(r#"UnitIsUnit("bogus", "player")"#).is_err());
     assert!(s.run(r#"UnitIsUnit("player", "party3")"#).is_ok());
 }
 
-/// **A multibyte unit token must not take the client down.**
-///
-/// The prefix test used to slice the token as a `&str` — `token[..p.len()]` — which PANICS when the
-/// token is multibyte UTF-8 and the prefix length lands mid-character ("byte index N is not a char
-/// boundary"). Any addon passing a non-ASCII token would have crashed the process rather than
-/// getting the `Unknown unit name` raise the client gives.
-///
-/// The client compares with `_strnicmp` over BYTES and folds ASCII only, so byte comparison is both
-/// the safe form and the faithful one — a token whose bytes differ above 0x7F is simply not one of
-/// the nine prefixes.
+/// The resolver compares bytes with an ASCII fold, so a non-ASCII token matches no prefix and
+/// raises, where slicing it as a `str` would panic mid-character.
 #[test]
 fn a_multibyte_unit_token_raises_rather_than_panicking() {
     let mut s = UiScript::new().unwrap();
     s.set_unit("player", Some(player()));
 
-    // Each of these has a multibyte character positioned so that a byte-index slice at one of the
-    // prefix lengths (3 for `pet`, 4 for `raid`, 5 for `party`, 6 for `player`/`target`) would land
-    // inside it.
+    // Each puts a multibyte character across a prefix length: 3, 4, 5 or 6 bytes.
     for token in ["pé", "раid", "playér", "targét", "мышь", "日本語のトークン"] {
         let err = s
             .run(&format!(r#"UnitName("{token}")"#))
@@ -1218,7 +1085,6 @@ fn a_multibyte_unit_token_raises_rather_than_panicking() {
             "it must RAISE, not panic and not answer: {err}"
         );
     }
-    // …and an ASCII token that merely shares a prefix's leading bytes still behaves.
     assert!(s
         .eval::<Option<String>>(r#"return UnitName("playerfoo")"#)
         .unwrap()
@@ -1229,25 +1095,12 @@ fn a_multibyte_unit_token_raises_rather_than_panicking() {
     );
 }
 
-/// **`UnitIsVisible` is object presence, and it is NOT `UnitExists`** — the pair an out-of-range
-/// party member separates, and the branch pfUI takes seven times.
-///
-/// `0x516030` is 57 bytes with one branch:
-/// `ClntObjMgrObjectPtr(resolve(token), TYPEMASK_UNIT) != NULL`. No field read, no comparison
-/// beyond `test eax,eax`, no float opcode — so no distance, no radius, no visibility flag. The
-/// range test is the *server's*: the out-of-range demotion unlinks the object from the very
-/// manager index this query searches.
-///
-/// The state that backs it is [`UnitState::has_object`], which `ui_party::feed`'s
-/// `member_unit_state` has always branched on — its `store: Option<&ObjectStore>` argument, whose
-/// own comment names `0x468460`. This test is what stops the two fields being conflated back
-/// together, because in every *in-range* case they agree and only the out-of-range one tells them
-/// apart.
+/// `0x516030` tests only that the client holds the object, so an out-of-range party member exists
+/// but is not visible.
 #[test]
 fn unit_is_visible_is_object_presence_not_existence() {
     let mut s = UiScript::new().unwrap();
 
-    // In range: the object is held, both answer yes.
     s.set_unit(
         "party1",
         Some(UnitState {
@@ -1262,9 +1115,7 @@ fn unit_is_visible_is_object_presence_not_existence() {
         "a held object is visible — and the return is the NUMBER 1, never a boolean"
     );
 
-    // **Out of range: the roster still has them, the object manager does not.** This is the row
-    // that matters; `exists` MUST stay true here, because that is what UnitExists's own GUID
-    // fallback answers, and folding the two fields into one would silently break it.
+    // Out of range: the roster has the member, the object manager does not.
     s.set_unit(
         "party1",
         Some(UnitState {
@@ -1285,7 +1136,7 @@ fn unit_is_visible_is_object_presence_not_existence() {
         "...and UnitExists must NOT have moved with it — the roster fallback is the difference"
     );
 
-    // pfUI's actual line (`unitframes.lua:1873`), which chooses a flat portrait over a 3D one.
+    // pfUI's portrait test (`api/unitframes.lua:1873`).
     assert!(
         s.eval::<bool>(
             r#"return (not UnitIsVisible("party1") or not UnitIsConnected("party1")) and true or false"#
@@ -1294,7 +1145,6 @@ fn unit_is_visible_is_object_presence_not_existence() {
         "the portrait branch fires for an out-of-range member"
     );
 
-    // A token with no snapshot at all: nil, via the same "no snapshot" path every predicate uses.
     assert_eq!(
         s.eval::<Option<i64>>(r#"return UnitIsVisible("party4")"#)
             .unwrap(),
@@ -1302,19 +1152,8 @@ fn unit_is_visible_is_object_presence_not_existence() {
     );
 }
 
-/// **The tapped pair, and the two ways it goes wrong.**
-///
-/// `UnitIsTapped 0x519c90` / `UnitIsTappedByPlayer 0x519d00` are a masked-byte pair — 108 bytes
-/// each, differing only in the `UNIT_DYNAMIC_FLAGS` mask (`0x4`/`0x8`, UpdateField 143) and the
-/// `Usage:` string. Each is `object present && (flags & mask)` and nothing else: no ownership, no
-/// GUID compare, no party/raid or health conjunct.
-///
-/// Asserted here because both are easy to get wrong in a way that still looks right:
-///
-/// - **Shape A, not shape C.** `UnitIsVisible` beside them has *no* `Usage:` raise; these two do.
-///   Inheriting the neighbour's shape would fail quietly, in the permissive direction.
-/// - **The pair is read as a conjunction.** `tapped && not tappedByPlayer` — someone *else's* kill
-///   — is the condition addons actually draw, and either bit alone says nothing useful.
+/// `0x519c90` and `0x519d00` test `UNIT_DYNAMIC_FLAGS` bits `0x4` and `0x8` behind object
+/// presence, and unlike `UnitIsVisible` both raise `Usage:` on a bad argument.
 #[test]
 fn the_tapped_pair_is_two_masks_of_one_field_and_raises_on_a_bad_argument() {
     let mut s = UiScript::new().unwrap();
@@ -1331,7 +1170,6 @@ fn the_tapped_pair_is_two_masks_of_one_field_and_raises_on_a_bad_argument() {
         );
     };
 
-    // Untapped: both nil.
     set(&mut s, false, false);
     assert_eq!(
         s.eval::<Option<i64>>(r#"return UnitIsTapped("target")"#)
@@ -1339,7 +1177,7 @@ fn the_tapped_pair_is_two_masks_of_one_field_and_raises_on_a_bad_argument() {
         None
     );
 
-    // Tapped by someone ELSE — the grey-bar case, pfUI `api/unitframes.lua:2012`.
+    // Tapped by someone else: the grey bar (pfUI `api/unitframes.lua:2012`).
     set(&mut s, true, false);
     assert_eq!(
         s.eval::<i64>(r#"return UnitIsTapped("target")"#).unwrap(),
@@ -1359,7 +1197,6 @@ fn the_tapped_pair_is_two_masks_of_one_field_and_raises_on_a_bad_argument() {
         "someone else's kill — the conjunction addons actually draw"
     );
 
-    // Tapped by ME: both set, so the grey-bar branch must NOT fire.
     set(&mut s, true, true);
     assert!(
         !s.eval::<bool>(
@@ -1369,8 +1206,8 @@ fn the_tapped_pair_is_two_masks_of_one_field_and_raises_on_a_bad_argument() {
         "my own tap is not greyed"
     );
 
-    // Object presence is a conjunct of BOTH: an out-of-range unit is neither, whatever the bits
-    // say — and the bits cannot even be read, because there is no descriptor to read them from.
+    // No object with the bit set, which the feed never builds: it sets `tapped` only from a live
+    // descriptor, so the binding reads the field as given.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -1381,9 +1218,6 @@ fn the_tapped_pair_is_two_masks_of_one_field_and_raises_on_a_bad_argument() {
             ..Default::default()
         }),
     );
-    // (The feed can never build that combination — `ui_unit::snapshot` sets all three together —
-    // but the binding is asserted against it anyway, because a future feed that forgot would
-    // otherwise report a tapped unit the object manager does not hold.)
     assert_eq!(
         s.eval::<i64>(r#"return UnitIsTapped("target")"#).unwrap(),
         1,
@@ -1391,11 +1225,7 @@ fn the_tapped_pair_is_two_masks_of_one_field_and_raises_on_a_bad_argument() {
          assertion records which of the two owns it"
     );
 
-    // SHAPE A. `UnitIsVisible` next door has no `Usage:` raise; these do — and **nil is in the
-    // list**, which is the half that does not come free: the shared `check_unit_token` lets a nil
-    // through by design (right for `UnitExists` and `UnitIsVisible`, wrong for these two), so the
-    // gate has to live in the binding. This assertion is what found that; the original spelling
-    // used `print`, which is not defined in our VM and so was quietly testing nil all along.
+    // Shape A, nil included: `check_unit_token` lets nil through, so the gate is the binding's.
     for bad in ["{}", "true", "nil", "", "function() end"] {
         assert!(
             s.run(&format!("UnitIsTapped({bad})")).is_err(),
@@ -1408,27 +1238,15 @@ fn the_tapped_pair_is_two_masks_of_one_field_and_raises_on_a_bad_argument() {
     }
 }
 
-/// **`UnitIsPartyLeader` is two legs ORed, and the solo case answers 1.**
-///
-/// `0x516210` is
-///
-/// ```text
-/// o = ObjPtr(resolve(t), TYPEMASK_PLAYER)
-/// (o != NULL && (o.PLAYER_FLAGS & 0x1)) || resolve(t) == g_groupLeaderGuid
-/// ```
-///
-/// and it is **not** derivable from `IsPartyLeader()` + `GetPartyLeaderIndex()` however arranged —
-/// the two legs cover disjoint failures. Each leg is asserted with the other one dead, because
-/// either alone looks sufficient until the case it cannot reach.
+/// `0x516210`: the player object's `PLAYER_FLAGS & 0x1`, or the resolved guid is the group
+/// leader's; each leg is asserted with the other dead.
 #[test]
 fn unit_is_party_leader_ors_two_legs_and_answers_one_when_solo() {
     let mut s = UiScript::new().unwrap();
     const ME: u64 = 0x1111;
     const THEM: u64 = 0x2222;
 
-    // ── LEG 1 alone: the descriptor flag, with the leader GUID matching nobody.
-    //    This is the leg that answers for a STRANGER who leads their own party — something no
-    //    comparison against our group's leader could ever express.
+    // Leg 1 alone: the flag, as on a stranger who leads their own party.
     s.set_party(PartyState {
         leader_guid: 0x9999,
         own_guid: 0,
@@ -1451,8 +1269,7 @@ fn unit_is_party_leader_ors_two_legs_and_answers_one_when_solo() {
         "the server's PLAYER_FLAGS bit answers on its own"
     );
 
-    // ── LEG 2 alone: no descriptor flag, but the resolved GUID IS our leader. This is the
-    //    out-of-range member — the client holds no object, so leg 1 has nothing to read.
+    // Leg 2 alone: an out-of-range member, with no object to read, whose guid is our leader.
     s.set_party(PartyState {
         leader_guid: THEM,
         own_guid: 0,
@@ -1475,7 +1292,6 @@ fn unit_is_party_leader_ors_two_legs_and_answers_one_when_solo() {
         "the GUID compare answers where there is no descriptor to read a flag from"
     );
 
-    // ── Neither leg: a grouped member who does not lead.
     s.set_unit(
         "party2",
         Some(UnitState {
@@ -1492,10 +1308,8 @@ fn unit_is_party_leader_ors_two_legs_and_answers_one_when_solo() {
         None
     );
 
-    // ── **NO ZERO GUARD.** Ungrouped, the cached leader is 0 and an unresolvable-but-non-raising
-    //    token resolves to 0 — so they match and the answer is 1. `IsPartyLeader 0x4e9130`
-    //    short-circuits on a `0:0` leader and `0x516210` does not; that asymmetry is the finding,
-    //    and answering nil here would be the divergence, however much it reads like a bug.
+    // No zero guard: solo, the cached leader is 0 and an unresolved token is 0, so the answer is
+    // 1; `IsPartyLeader` (`0x4e9130`) guards a zero leader, `0x516210` does not.
     s.set_party(PartyState::default());
     assert_eq!(
         s.eval::<i64>("return UnitIsPartyLeader(nil)").unwrap(),
@@ -1509,16 +1323,11 @@ fn unit_is_party_leader_ors_two_legs_and_answers_one_when_solo() {
         "...and so does a token with no snapshot, by the same route"
     );
 
-    // A bad token still raises through the shared resolver — shape C with a shape-A tail.
     assert!(s.run(r#"UnitIsPartyLeader("notatoken")"#).is_err());
 }
 
-/// `UnitHasRelicSlot` — the number 1 or nil, per token, never a boolean.
-///
-/// This shipped **absent** for months on the belief that the relic slot post-dates 1.12, which is
-/// false (decision 1796). Stock `PaperDollFrame.lua` calls it unconditionally at l.429 and l.580,
-/// so while it was missing the character sheet raised `attempt to call global` for every class —
-/// which is why the nil-global case is asserted here too, not just the answer.
+/// Stock calls it unconditionally (`PaperDollFrame.lua:429`, `PaperDollFrame.lua:580`), so the
+/// global must exist for every class.
 #[test]
 fn unit_has_relic_slot_answers_one_or_nil() {
     let mut s = UiScript::new().unwrap();
@@ -1533,8 +1342,7 @@ fn unit_has_relic_slot_answers_one_or_nil() {
     warrior.has_relic_slot = false;
     s.set_unit("target", Some(warrior));
 
-    // The truthy leg is the NUMBER 1 (`lua_pushnumber`, `0x519ec8`) — a caller comparing it to 1
-    // is stock idiom, and a boolean would silently fail that.
+    // The true leg is the number 1 (`0x519ec8`).
     assert_eq!(
         s.eval::<String>(r#"return tostring(UnitHasRelicSlot("player"))"#)
             .unwrap(),
@@ -1545,34 +1353,26 @@ fn unit_has_relic_slot_answers_one_or_nil() {
             .unwrap(),
         "number"
     );
-    // The false leg is nil, never `false` (`lua_pushnil`, `0x519edb`).
+    // The false leg is nil, never false (`0x519edb`).
     assert_eq!(
         s.eval::<String>(r#"return type(UnitHasRelicSlot("target"))"#)
             .unwrap(),
         "nil"
     );
-    // No `"player"` fast path in the reference, so every token is answered the same way — the
-    // stock inspect path at `PaperDollFrame.lua:429` passes the inspected unit, not "player".
+    // No `"player"` fast path: `InspectPaperDollFrame.lua:123` passes the inspected unit.
     assert_eq!(
         s.eval::<String>(r#"return type(UnitHasRelicSlot("party1"))"#)
             .unwrap(),
         "nil"
     );
-    // And it EXISTS — the regression that actually bit. A nil global here takes the whole
-    // character sheet down for every class, not just the three that answer 1.
     assert_eq!(
         s.eval::<String>("return type(UnitHasRelicSlot)").unwrap(),
         "function"
     );
 }
 
-/// **The two-token predicates gate BOTH positions** — decision 1836, closing the half 1834 left
-/// open on purpose.
-///
-/// 1834 applied the `lua_isstring` gate only where a partial census named a single-token binding,
-/// because a census that finds "a gate somewhere in this body" cannot say *which* argument carries
-/// it. The complete 83-row table (`0x850438`) resolves it: these seven each carry **two**
-/// `lua_isstring` sites, so either argument being nil raises.
+/// Each of these carries two `lua_isstring` gates in the table at `0x850438`, so either argument
+/// nil raises.
 #[test]
 fn a_two_token_predicate_raises_on_either_nil_argument() {
     let mut s = UiScript::new().unwrap();
@@ -1602,14 +1402,12 @@ fn a_two_token_predicate_raises_on_either_nil_argument() {
         assert!(s.run(&format!("{verb}()")).is_err(), "{verb} with neither");
     }
 
-    // `GetRaidTargetIndex` is the one of six previously-unclassified names that takes a token, and
-    // it is gated. Its usage string names the argument UNQUOTED — the reference's own spelling.
+    // `GetRaidTargetIndex` takes a token and is gated.
     assert!(s.run(r#"GetRaidTargetIndex("player")"#).is_ok());
     assert!(s.run("GetRaidTargetIndex()").is_err());
 
-    // …while the other five take no argument at all and have no gate. `GetTimeToWellRested` is a
-    // three-instruction stub in the reference that always pushes nil; computing a value there
-    // would be divergence, not a feature.
+    // These take no argument and have no gate; `GetTimeToWellRested` is a stub in the reference
+    // that always pushes nil.
     for none in [
         "GetQuestGreenRange",
         "GetRestState",
@@ -1621,30 +1419,14 @@ fn a_two_token_predicate_raises_on_either_nil_argument() {
     }
 }
 
-// ── The family's return SHAPE, pinned per binding ───────────────────────────────────────────────
+// ── The predicates' return shape ────────────────────────────────────────────────────────────────
 
-/// **Every `Unit*` predicate answers the number `1` or `nil` — never a Lua boolean** (decision
-/// 2043; the law is 1830's, made for the widget predicates a family earlier).
-///
-/// The reference cannot produce a boolean here. Its pushes are `lua_pushnumber 0x6f3810` (tag 3,
-/// the double `1.0`) and `lua_pushnil 0x6f37f0` (tag 0); `lua_pushboolean 0x6f39f0` has seven call
-/// sites image-wide and not one is a registered binding body, so **tag 1 is never written**
-/// (`UnitExists 0x515fb0`, `UnitIsVisible 0x516030`, `UnitIsTapped 0x519c90`, `UnitAffectingCombat
-/// 0x517e10`, `UnitPlayerControlled 0x516410`, `UnitInRaid 0x516350`, `UnitIsCharmed 0x516cf0` and
-/// `UnitHasRelicSlot 0x519e50` each confirm it individually).
-///
-/// **Truthiness is exactly why this needs a test rather than a reading.** `if UnitIsDead(u)` and
-/// `if not UnitIsDead(u)` are identical under either shape, and mlua's `bool` conversion maps
-/// `Integer(1)` to `true` as happily as it maps `Boolean(true)` — so a test that reads the value
-/// as a Rust `bool` passes under the bug. Only `type(...)`, `== 1` and `== nil` separate them, and
-/// `== nil` is the one that *inverts*: a boolean `false` is not `nil`, so a caller comparing
-/// against `nil` concludes the opposite of the truth.
-///
-/// The table is the whole registered family, so a new predicate added outside the seam fails here
-/// rather than shipping its own shape.
+/// The reference pushes the number 1 (`lua_pushnumber`, `0x6f3810`) or nil (`0x6f37f0`), and no
+/// unit binding calls `lua_pushboolean` (`0x6f39f0`). mlua reads 1 as `true`, so only `type`,
+/// `== 1` and `== nil` tell the shapes apart.
 #[test]
 fn every_unit_predicate_is_one_or_nil_and_never_a_boolean() {
-    // (binding, the call as an addon writes it, a UnitState that makes it TRUE)
+    // (binding, the call, a UnitState that makes it true)
     let table: Vec<(&str, &str, UnitState)> = vec![
         (
             "UnitExists",
@@ -1865,7 +1647,6 @@ fn every_unit_predicate_is_one_or_nil_and_never_a_boolean() {
     ];
 
     for (name, call, live) in table {
-        // ---- the TRUE leg: the number 1, one value, and NOT a boolean ----
         let mut s = UiScript::new().unwrap();
         s.set_unit("player", Some(player()));
         s.set_unit("target", Some(live));
@@ -1894,9 +1675,7 @@ fn every_unit_predicate_is_one_or_nil_and_never_a_boolean() {
             "{name} returns exactly one value on the true leg"
         );
 
-        // ---- the FALSE leg: nil, one value, and NOT `false` ----
-        // The token is cleared rather than re-flagged, so this also covers the "no such unit" arm
-        // the reference shares with a false predicate.
+        // The false leg: nil, one value. Clearing the token also covers the absent-unit arm.
         let mut s = UiScript::new().unwrap();
         s.set_unit("player", Some(player()));
         s.set_unit("target", None);
@@ -1918,11 +1697,7 @@ fn every_unit_predicate_is_one_or_nil_and_never_a_boolean() {
     }
 }
 
-/// The corpus idiom, spelled the way an addon spells it, on a live token and a dead one.
-///
-/// This is the shape a `bool` breaks and truthiness hides: `if UnitExists("target") == 1` is
-/// simply never true under a boolean, and `if UnitExists("target") == nil` is never true either —
-/// the branch silently picks the wrong arm in both directions at once.
+/// The addon idiom: under a boolean, neither `== 1` nor `== nil` would ever be true.
 #[test]
 fn the_equals_one_idiom_branches_correctly_on_a_live_and_a_dead_token() {
     let mut s = UiScript::new().unwrap();
@@ -1955,9 +1730,8 @@ fn the_equals_one_idiom_branches_correctly_on_a_live_and_a_dead_token() {
     );
 }
 
-/// `UnitOnTaxi` (`0x517a40`) is the family's one predicate registered outside `unit/`, over the
-/// taxi module's own ride flag — which is how it stayed a `bool` when its 22 siblings were fixed.
-/// Same shape, and the same `Usage:` raise its gate at `0x517a48` carries.
+/// `UnitOnTaxi` (`0x517a40`), registered with the taxi module's ride flag, has the family's shape
+/// and raises `Usage:` from its gate (`0x517a48`).
 #[test]
 fn unit_on_taxi_is_one_or_nil_and_raises_the_reference_usage() {
     let mut s = UiScript::new().unwrap();
@@ -1976,7 +1750,7 @@ fn unit_on_taxi_is_one_or_nil_and_raises_the_reference_usage() {
     assert!(!s
         .eval::<bool>(r#"return UnitOnTaxi("player") == true"#)
         .unwrap());
-    // Any other token is nil, not false — only our own player is tracked.
+    // Only the player's ride is tracked: any other token is nil.
     assert!(s
         .eval::<bool>(r#"return UnitOnTaxi("target") == nil"#)
         .unwrap());
@@ -1988,24 +1762,18 @@ fn unit_on_taxi_is_one_or_nil_and_raises_the_reference_usage() {
     );
 }
 
-/// **The four `"player"` verbs read the seeded record, and nothing can blank it** (2261/2263).
-///
-/// The reference's `"player"` arm never reaches the resolver: `0x51708c` reads `0xc27d88`, a copy
-/// of the char-enum row written once at the Enter World commit and never cleared anywhere in the
-/// image. So the name survives everything that can happen to the *snapshot* — which is the whole
-/// of decision 2260's bug: a name-cache miss for our own guid produced a nameless player push, it
-/// replaced the roster seat, and the verb went nil in the world. That push is modelled here
-/// exactly, and it must now be invisible to this verb.
+/// The reference's `"player"` arm reads the record (`0x51708c` reads `0xc27d88`), never the
+/// snapshot, so a nameless player push cannot blank the name.
 #[test]
 fn the_player_record_outlives_every_snapshot() {
     let mut s = UiScript::new().unwrap();
 
-    // Before any Enter World commit — the buffer's one empty state, and the reference's nil.
+    // Before Enter World the record is empty: nil.
     assert!(s
         .eval::<bool>(r#"return UnitName("player") == nil"#)
         .unwrap());
 
-    // The world-entry load seeds it from the roster row, before a single addon file runs.
+    // Enter World seeds it from the character row, before any addon file runs.
     s.set_player_record(PlayerRecord {
         name: "Nelprifour".into(),
         race: Some(("Night Elf".into(), "NightElf".into())),
@@ -2019,7 +1787,7 @@ fn the_player_record_outlives_every_snapshot() {
          for many frames with no local player object and this verb still answers"
     );
 
-    // 2260's push, verbatim: the descriptor landed, the name cache missed for our own guid.
+    // The descriptor has landed, but the name cache missed our own guid.
     let nameless = UnitState {
         exists: true,
         has_object: true,
@@ -2045,12 +1813,10 @@ fn the_player_record_outlives_every_snapshot() {
         "UnitClass's second return is the UPPERCASE token"
     );
     assert_eq!(s.eval::<i64>(r#"return UnitSex("player")"#).unwrap(), 2);
-    // …and the snapshot is still the snapshot for everything else. `UnitLevel` is the boundary:
-    // the record carries a level byte and the client's accessor for it (`0x5abe00`) is DEAD, so
-    // this one reads the descriptor even for `"player"`.
+    // `UnitLevel` reads the snapshot: the record's level accessor (`0x5abe00`) has no caller.
     assert_eq!(s.eval::<i64>(r#"return UnitLevel("player")"#).unwrap(), 5);
 
-    // The token going away entirely (the logout despawn frames) does not empty the buffer either.
+    // Removing the token, as at logout, keeps the record.
     s.set_unit("player", None);
     assert_eq!(
         s.eval::<String>(r#"return UnitName("player")"#).unwrap(),
@@ -2062,7 +1828,7 @@ fn the_player_record_outlives_every_snapshot() {
         "the name and the unit are different questions — which is exactly what the buffer buys"
     );
 
-    // An empty seed is refused, not stored: nothing in the reference ever empties this record.
+    // An empty seed is refused: nothing empties the reference's record.
     s.set_player_record(PlayerRecord::default());
     assert_eq!(
         s.eval::<String>(r#"return UnitName("player")"#).unwrap(),
@@ -2073,8 +1839,7 @@ fn the_player_record_outlives_every_snapshot() {
         "Night Elf"
     );
 
-    // A NAMED push does keep it in step — a second login as somebody else (1290's per-login VM
-    // is the usual route, but a push must never leave the two disagreeing).
+    // A named push updates the record, so a push never leaves the two disagreeing.
     let mut other = player();
     other.name = Some("Onewarrior".into());
     s.set_unit("player", Some(other));
@@ -2094,32 +1859,22 @@ fn the_player_record_outlives_every_snapshot() {
         "player() is female — the record follows the push"
     );
 
-    // Still the family's two returns, the second nil (1840).
+    // Two returns, the realm nil.
     assert_eq!(
         s.eval::<i64>(r#"local t = {UnitName("player")}; return table.getn(t)"#)
             .unwrap(),
         1
     );
-    // …and the case fold on the token holds on the fast path too.
+    // The record path folds case too.
     assert_eq!(
         s.eval::<String>(r#"return UnitName("PLAYER")"#).unwrap(),
         "Onewarrior"
     );
 }
 
-/// **The unset record's four answers, which are not uniform** (decision 2263).
-///
-/// The state is "no Enter World has been committed in this process" — unreachable from Lua in the
-/// reference, because the four verbs only exist inside `UI_Init`'s table and only an Enter World
-/// commit gets there. It is reachable *here* (a bare VM, a capture, a test world with no pick), so
-/// it is pinned to what the bytes do rather than left to whatever falls out:
-///
-/// - `UnitName` → nil, via `lua_pushstring(NULL)` at `0x517095` tail-jumping into `lua_pushnil`;
-/// - `UnitRace`/`UnitClass` → `nil, nil`, via the DBC bound and NULL-row arms — race 0 and class 0
-///   have no row, and those arms reach `pushnil` **without** falling back to the unit resolver;
-/// - `UnitSex` → the number **2**, because `0x517ef9`'s accessor feeds `fild [4*eax+0x808be4]`
-///   over `{2,3,1,6}` with **no bounds check at all**. It is the one of the four with no validity
-///   guard, and "male" is what an all-zero record means to it.
+/// An all-zero record, which a bare VM here can reach: `UnitName` nil (`0x517095`), `UnitRace` and
+/// `UnitClass` `nil, nil` as race and class 0 have no row, and `UnitSex` 2, as `0x517ef9` indexes
+/// its table (`0x808be4`) unchecked.
 #[test]
 fn an_unseeded_player_record_answers_the_references_four_ways() {
     let s = UiScript::new().unwrap();
@@ -2143,8 +1898,7 @@ fn an_unseeded_player_record_answers_the_references_four_ways() {
         2,
         "the one of the four with no bounds check — an all-zero record reads male, not nil"
     );
-    // And the fast path is the TOKEN, not a prefix: `"playerfoo"` is recognised but resolves to
-    // nothing, so it goes to the resolver and answers the resolver's nil.
+    // The record arm needs the whole token: `"playerfoo"` goes to the resolver.
     assert!(s
         .eval::<bool>(r#"return UnitName("playerfoo") == nil"#)
         .unwrap());
diff --git a/crates/benilla-ui/src/script/weapon_enchant.rs b/crates/benilla-ui/src/script/weapon_enchant.rs
index a185d4c8..81a41ffb 100644
--- a/crates/benilla-ui/src/script/weapon_enchant.rs
+++ b/crates/benilla-ui/src/script/weapon_enchant.rs
@@ -1,98 +1,42 @@
-//! `GetWeaponEnchantInfo` — the two **temporary weapon enchantment** slots, as virtual buff slots.
+//! `GetWeaponEnchantInfo` (`0x4c9790`): the two temporary weapon enchantments, which
+//! `BuffFrame_Enchant_OnUpdate` (`BuffFrame.lua:162-233`) polls every frame.
 //!
-//! This is the whole data path behind the reference's `TemporaryEnchantFrame`
-//! (`BuffFrame.lua:162-233`): the row polls this verb every frame, shows an icon per enchanted
-//! weapon, and counts its expiry down. Eight corpus addons call it as well.
+//! No arguments; six values on every path (`0x4c993a`, `0x4c995b`, `0x4c998f`), main hand
+//! (equipment slot 15, `0x4c97c3`) then off hand (slot 16, `0x4c988b`):
 //!
-//! # The byte-verified signature (`0x4c9790`)
-//!
-//! Zero arguments — the function never touches the Lua stack for input; `edi` is the state. **Six**
-//! return values on **every** path (`mov eax,0x6` at `0x4c993a`, `0x4c995b` and `0x4c998f`, the
-//! three exits), in the order FrameXML destructures them:
-//!
-//! ```text
-//! hasMainHandEnchant, mainHandExpiration, mainHandCharges,
-//! hasOffHandEnchant,  offHandExpiration,  offHandCharges
-//! ```
-//!
-//! | value | shape | absent |
+//! | value | present | absent |
 //! |---|---|---|
-//! | `has*Enchant` | the **number 1** (`push 0x3ff00000; push 0x0` — the double 1.0 — through the number-push at `0x6f3810`, `0x4c97fc`/`0x4c98c3`) | **nil** (`0x6f37f0`, the nil-push, three of them at `0x4c9873` / `0x4c9944`) |
-//! | `*Expiration` | a number of **MILLISECONDS remaining** (`0x5d9d00(item, 1)` → `fild` → number-push, `0x4c9828`-`0x4c983f`) | **nil** |
-//! | `*Charges` | a number (the enchantment triple's third dword) | the number **0**, never nil (`mov DWORD PTR [ebp-0x4],0x0; fild`, `0x4c985a`) |
+//! | `has*Enchant` | the number 1 (`0x6f3810`) | nil (`0x6f37f0`) |
+//! | `*Expiration` | milliseconds remaining (`0x5d9d00`) | nil |
+//! | `*Charges` | the charges | 0, never nil (`0x4c985a`) |
 //!
-//! Milliseconds, not seconds: `ref-BuffFrame.lua:189`/`:212` divide by 1000 before displaying, and
-//! `0x5d9d00` is the same live remaining-time reader `benilla::items::Countdowns::enchant_remaining_ms`
-//! mirrors (decision 0920). It is *remaining* time, recomputed per call against a deadline — never
-//! an absolute stamp.
+//! Each weapon's `ITEM_FIELD_ENCHANTMENT` slot 1 triple is read raw (`0x83a3c8`): a nonzero id is
+//! the whole gate (`0x4c97f8`), with no DBC lookup, so the totem imbues, which the tooltip's
+//! enchant list drops, still show. The duration dword only gates the expiration (`0x4c981b`); the
+//! value is `max(0, deadline - now)` on a deadline `0x5d9cc0` parks from the seconds in
+//! `SMSG_ITEM_ENCHANT_TIME_UPDATE`, so the host subtracts on read and an elapsed timer is 0.
 //!
-//! # Which slots, and which enchantment
-//!
-//! Main hand is fetched first, from **equipment slot 15** (`push 0xf`, `0x4c97c3`), off hand from
-//! **16** (`push 0x10`, `0x4c988b`) — the client's 0-based `EQUIPMENT_SLOT_*` numbering, so the
-//! live-API `GetInventorySlotInfo` ids one higher (16 `MainHandSlot`, 17 `SecondaryHandSlot`) are
-//! what the frame passes to `GetInventoryItemTexture`.
-//!
-//! Per weapon the binary reads three consecutive dwords off the item's descriptor —
-//! `[D+0x4c]` the enchant **id** (`test eax,eax; je` = the entire has-an-enchant gate, `0x4c97f8`),
-//! `[D+0x50]` the **duration**, `[D+0x54]` the **charges** — and the `push 0x1` handed to
-//! `0x5d9d00` names the enchantment slot: **1 = TEMP**. The identity is read off the client's own
-//! field-metadata table, not inferred: `0x83a3c8` = `"ITEM_FIELD_ENCHANTMENT"`, index `0x10`, size
-//! `0x15`, with `0x83a2d4`/`0x83a2e8` fixing `D = O + 0x18` — so the triple is fields 25/26/27,
-//! slot 1.
-//!
-//! **The gate is the raw id and nothing else** — no DBC lookup, no display filter. That is why the
-//! app feeds this from [`benilla_protocol`]'s `item_enchant(1)` rather than from the tooltip-shaped
-//! [`super::EnchantView`] list, which drops an id the `SpellItemEnchantment` catalog cannot name
-//! *and* the whole `Flags & 0x2` print-no-line family (decision 0928) — the totem weapon imbues,
-//! i.e. precisely the enchants this row exists to show.
-//!
-//! # The expiration is NOT the wire field
-//!
-//! The trap: `[D+0x50]`, the item's own enchantment **duration** dword, is read *only* as a
-//! non-zero presence gate (`0x4c981b test ecx,ecx`) — **its value is never returned**. The number
-//! comes from a client-local **absolute deadline** at `item+0x324[slot]`, written only by
-//! `0x5d9cc0` out of `SMSG_ITEM_ENCHANT_TIME_UPDATE` as `now_ms + seconds*1000`, and read back as
-//! `max(0, deadline − now)` (`0x5d9d00`: `0x5d9d15` clock, `0x5d9d2a sub`). **The wire carries
-//! seconds; this API returns milliseconds.** So a host stores a deadline and subtracts on read — it
-//! never ticks a countdown. `benilla::items::Countdowns` does exactly that, and
-//! `Countdowns::enchant_deadline_ms` is the read that keeps an *elapsed* timer as the number `0` rather
-//! than collapsing it to "no timer", which is the distinction `BuffFrame_Enchant_OnUpdate` draws
-//! "0 s" from.
-//!
-//! **Our one named gap.** The reference's nil-expiration branch is `[D+0x50] == 0`; ours is "no
-//! deadline was ever parked for this slot". They differ for exactly one state — an enchant whose
-//! duration field is set but whose `SMSG_ITEM_ENCHANT_TIME_UPDATE` has not arrived yet, where the
-//! reference answers the number `0` and we answer nil. Closing it needs an
-//! `item_enchant_duration(slot)` accessor beside `item_enchant`/`item_enchant_charges` in
-//! `benilla_protocol` (the triple's middle field, deliberately unexposed there because the tooltip
-//! never reads it — decision 0920). The server sends the packet in the same breath as the field, so
-//! the window is a frame or two.
+//! The reference's expiration is nil only when the duration dword is 0; ours is nil until the
+//! first `SMSG_ITEM_ENCHANT_TIME_UPDATE`, which follows the field within a frame or two.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// One weapon's **temporary** enchantment (`ITEM_FIELD_ENCHANTMENT` slot 1), as the app reads it
-/// off the equipped item object. Its mere existence is `has*Enchant`: the app only builds one when
-/// the enchant id is nonzero, which is the binary's own gate.
+/// One weapon's temporary enchantment (`ITEM_FIELD_ENCHANTMENT` slot 1); the app builds one only
+/// for a nonzero enchant id, the reference's gate.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub struct WeaponEnchant {
-    /// Milliseconds left on the enchant — `max(0, deadline − now)` off the parked
-    /// `SMSG_ITEM_ENCHANT_TIME_UPDATE` deadline, so **`Some(0)` for an elapsed timer** (the
-    /// reference returns the number 0 there, and the row draws "0 s" and pulses). `None` is the
-    /// reference's nil expiration: no timer on this enchant at all.
+    /// Milliseconds left, `max(0, deadline - now)`: `Some(0)` once elapsed, where the reference
+    /// returns 0 and the row draws "0 s"; `None` is no timer at all.
     pub remaining_ms: Option<u64>,
-    /// The triple's charges dword — `0` for an enchant that carries none, never absent.
+    /// The charges dword, 0 for none.
     pub charges: u32,
 }
 
 impl super::UiScript {
-    /// Push the two weapons' temporary enchantments (`None` = no item, or no enchant on it).
-    ///
-    /// **Pushed every frame, not on change**: `remaining_ms` is a live countdown, so folding it
-    /// into a change-gated snapshot would either fire that snapshot's event every frame or freeze
-    /// the timer. The reference recomputes it per call for the same reason.
+    /// Push the two weapons' temporary enchantments, `None` for no item or no enchant. Pushed every
+    /// frame: `remaining_ms` is live, and the reference recomputes it per call.
     pub fn set_weapon_enchants(
         &mut self,
         main_hand: Option<WeaponEnchant>,
@@ -110,8 +54,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, ()| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             let mut out = Vec::with_capacity(6);
-            // Main hand then off hand, three values each — the arity is fixed at six whatever is
-            // equipped, so a caller's `local a, b, c, d, e, f = …` never shifts.
+            // Main hand then off hand, three values each: always six.
             for hand in model.weapon_enchants {
                 match hand {
                     Some(e) => {
@@ -134,16 +77,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 mod tests {
     use crate::script::{UiScript, WeaponEnchant};
 
-    /// **The arity, and the shapes that carry it.** Six values on every path — the reference's
-    /// `mov eax,0x6` — with `nil` for an unenchanted weapon and the *number* 1 for an enchanted
-    /// one. An implementation that returned `false`/`0`, or that returned early with three values
-    /// when the off hand is empty, breaks `BuffFrame_Enchant_OnUpdate`'s single destructuring
-    /// assignment and every corpus caller with it.
+    /// `BuffFrame.lua:163` destructures all six at once.
     #[test]
     fn get_weapon_enchant_info_returns_six_values_on_every_path() {
         let mut s = UiScript::new().unwrap();
 
-        // Nothing equipped or nothing enchanted: six nils, not zero values.
+        // Nothing enchanted: six nils, not zero values.
         assert_eq!(s.arity("GetWeaponEnchantInfo()").unwrap(), 6);
         assert!(s
             .eval::<bool>(
@@ -151,7 +90,6 @@ mod tests {
                  return a == nil and b == nil and c == nil and d == nil and e == nil and f == nil"
             )
             .unwrap());
-        // The reference's own early-out branch, run for real.
         assert!(s
             .eval::<bool>("local m, _, _, o = GetWeaponEnchantInfo() return (not m) and (not o)")
             .unwrap());
@@ -177,11 +115,10 @@ mod tests {
             (1.0, 480_000.0, 0.0),
             "the number 1, MILLISECONDS, and a zero charge count"
         );
-        // `has` is the number 1, not a boolean: `true ~= 1` would invert any `== 1` test.
+        // The number 1, not a boolean: `true ~= 1`.
         assert!(s
             .eval::<bool>("local a = GetWeaponEnchantInfo() return a == 1")
             .unwrap());
-        // The off hand is still all nil.
         assert!(s
             .eval::<bool>(
                 "local _, _, _, d, e, f = GetWeaponEnchantInfo() \
@@ -210,10 +147,7 @@ mod tests {
             "no parked deadline is a nil expiration, never a fabricated 0"
         );
 
-        // ...and the state that is NOT nil: an elapsed timer. The reference returns the number 0
-        // there (`max(0, deadline - now)` on a deadline in the past), and the enchant row's
-        // `if ( expiration )` is TRUE for 0 in Lua — so it draws "0 s" and pulses the icon. A host
-        // that collapsed "expired" into "no timer" would blank the last second of every enchant.
+        // An elapsed timer is the number 0, which the row's `if ( expiration )` takes as true.
         s.set_weapon_enchants(
             Some(WeaponEnchant {
                 remaining_ms: Some(0),
@@ -232,20 +166,14 @@ mod tests {
             "and 0 is truthy in Lua, which is what makes the row draw it"
         );
 
-        // Zero arguments — and a surplus one is IGNORED, not an error. The reference reads nothing
-        // off the stack and has no usage string at all (contrast its neighbour
-        // `GetInventoryAlertStatus`, which has both), so an addon that guesses at a slot argument
-        // still gets an answer rather than a raised error.
+        // The reference reads no arguments and has no usage string, so a surplus one is ignored.
         assert_eq!(
             s.arity("GetWeaponEnchantInfo(16, \"nonsense\")").unwrap(),
             6
         );
     }
 
-    /// The reference's own consumer arithmetic, run over the binding: `expiration/1000` is the
-    /// number of seconds the row prints, and the `< BUFF_WARNING_TIME` flash test rides on it.
-    /// Milliseconds is the whole point — a seconds return would make a 480 s enchant read as
-    /// 0.48 s and flash from the moment it was applied.
+    /// `BuffFrame.lua:212` divides by 1000 before its `BUFF_WARNING_TIME` test.
     #[test]
     fn the_expiration_is_milliseconds_the_way_the_reference_divides_it() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/who_sort.rs b/crates/benilla-ui/src/script/who_sort.rs
index 576d51ad..7ba19abf 100644
--- a/crates/benilla-ui/src/script/who_sort.rs
+++ b/crates/benilla-ui/src/script/who_sort.rs
@@ -1,57 +1,34 @@
-//! The `/who` list's sort — the reference's seven-slot key chain, its promote-and-flip rule, and
-//! the comparator that walks it (`SortWho 0x5ad890`, comparator `0x5ada00`; benilla decision 2030).
-//!
-//! **A `/who` sort is not "order by the clicked column".** The reference keeps a *chain* of seven
-//! `{key, dir}` slots at `0xc2817c`/`0xc28180`, seeded once per process to `key[i] = i`
-//! (`0x5add04`), i.e. **zone → level → class → group → name → race → guild**, every direction
-//! ascending. Each click *promotes* its key to the front of that chain; the keys it displaces
-//! stay behind it, so the chain reads most-recently-used first and the comparator walks it as a
-//! **tie-breaker list**, not as a single key. Two players on the same level keep whatever order
-//! the previously clicked key gave them.
-//!
-//! Two consequences that are the whole of bug B365:
-//!
-//! - **A repeated click reverses.** The promote flips the direction **only when the key was
-//!   already at the front** (`0x5ad99e`–`0x5ad9a7`, the `sete` on `i == 0`); promoting a key from
-//!   anywhere else carries its *remembered* direction over unchanged. So Name, Name reverses; but
-//!   Name, Level, Name does **not** — the second Name click restores the direction the first one
-//!   left there.
-//! - **Nothing here is a request to the server.** The chain and the comparator are engine state;
-//!   `SortWho` sorts the array it already holds and fires `WHO_LIST_UPDATE` synchronously, inside
-//!   the binding ([`super::social`]'s `SortWho`).
-//!
-//! The chain is **per-process** in the reference — its initialiser `0x5adc50` runs once from the
-//! process-start run at `0x401666` — so it survives a logout and the next login inherits it.
-//! `SocialState::clear_session` on the app side keeps it for that reason.
+//! The `/who` sort (`SortWho` `0x5ad890`, comparator `0x5ada00`): a chain of seven `{key, dir}`
+//! slots (`0xc2817c`/`0xc28180`), seeded zone, level, class, group, name, race, guild, all
+//! ascending (`0x5add04`). A click promotes its key to the front and the comparator walks the chain
+//! as tie-breakers, so earlier clicks still order ties. The direction flips only when the key was
+//! already in front (`0x5ad99e`–`0x5ad9a7`); promoted from behind, it keeps its old direction.
+//! Sorting is local, never a server request, and the chain lives for the process (`0x5adc50`, run
+//! from `0x401666`), so it survives a logout.
 
 use std::cmp::Ordering;
 
 use super::social::WhoInfo;
 
-/// The seven keys `SortWho` maps its argument to. **The declaration order is the reference's key
-/// numbering** (`edi` in `0x5ad8bb`–`0x5ad979`) *and* the chain's seeded order, because the
-/// initialiser writes `key[i] = i`.
+/// The seven keys `SortWho` maps its argument to, declared in the reference's numbering
+/// (`0x5ad8bb`–`0x5ad979`), which is also the chain's seeded order.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
 pub enum WhoSortKey {
-    /// `0` — `"zone"`, the frame's own resting column.
+    /// `0`, `"zone"`, the frame's resting column.
     Zone,
-    /// `1` — `"level"`, the one numeric arm: at `dir = 0` the **lower** level comes first.
+    /// `1`, `"level"`, the one numeric arm: ascending puts the lower level first.
     Level,
-    /// `2` — `"class"`.
+    /// `2`, `"class"`.
     Class,
-    /// `3` — `"group"`. A real chain key whose comparator arm (`0x5adbb2`) *is* the continue
-    /// label: it orders nothing, ever. Unreachable from the shipped UI as well — the header that
-    /// carries `sortType = "group"` sits inside `FriendsFrame.xml`'s commented span 1413–1429 —
-    /// but it is modelled because it occupies a slot, and promoting it still displaces whatever
-    /// key was at the front.
+    /// `3`, `"group"`: its arm (`0x5adbb2`) orders nothing, but promoting it still displaces the
+    /// front key. The stock header for it is commented out (`FriendsFrame.xml:1413-1429`).
     Group,
-    /// `4` — `"name"`, and the answer for **any** string the seven compares miss: `edi` is
-    /// preloaded with 4 at `0x5ad8bb` and never reassigned on the no-match path.
+    /// `4`, `"name"`, and the answer for any other string (preloaded at `0x5ad8bb`).
     #[default]
     Name,
-    /// `5` — `"race"`.
+    /// `5`, `"race"`.
     Race,
-    /// `6` — `"guild"`.
+    /// `6`, `"guild"`.
     Guild,
 }
 
@@ -67,9 +44,8 @@ impl WhoSortKey {
         Self::Guild,
     ];
 
-    /// `SortWho`'s argument → key: seven `0x64a4c0` compares (`0x5ad8c0`–`0x5ad979`), which are
-    /// **case-insensitive** (`0x414310` folds `A`–`Z` on both operands), with [`Self::Name`] as
-    /// the no-match answer.
+    /// `SortWho`'s argument to its key: seven ASCII case-insensitive compares (`0x64a4c0`,
+    /// `0x5ad8c0`–`0x5ad979`), [`Self::Name`] when none match.
     pub fn from_sort_type(sort_type: &str) -> Self {
         match () {
             _ if sort_type.eq_ignore_ascii_case("name") => Self::Name,
@@ -83,33 +59,28 @@ impl WhoSortKey {
         }
     }
 
-    /// This key's own ordering of two rows at `dir = 0` — the comparator's seven jump-table arms
-    /// (`0x5adbd8`), each returning `0x64a4c0`'s `−1/0/+1` or the level arm's `setge` sign.
+    /// This key's ascending order of two rows: the comparator's jump-table arms (`0x5adbd8`).
     fn order(self, a: &WhoInfo, b: &WhoInfo) -> Ordering {
         match self {
-            // `a+0` / `a+0x30`: wire strings, compared case-insensitively. An empty guild is a
-            // real value here (`""` sorts before any name), not a missing row.
+            // `a+0`/`a+0x30`, wire strings; an empty guild is a real value and sorts first.
             Self::Name => ascii_ci_cmp(&a.name, &b.name),
             Self::Guild => ascii_ci_cmp(&a.guild, &b.guild),
-            // `a+0x90`, i32: `cmp; je tie; setge dl; lea edx,[edx*2-1]` — lower level first.
+            // `a+0x90`, an i32, lower level first.
             Self::Level => a.level.cmp(&b.level),
-            // The three DBC arms: the *localized name* out of `ChrClasses`/`ChrRaces`/`AreaTable`
-            // is what gets compared, which is exactly what the app already resolved into the row.
+            // The localized `ChrClasses`/`ChrRaces`/`AreaTable` name the app resolved into the row.
             Self::Class => dbc_name_cmp(&a.class, &b.class),
             Self::Race => dbc_name_cmp(&a.race, &b.race),
             Self::Zone => dbc_name_cmp(&a.zone, &b.zone),
-            // `0x5adbb2` is the continue label itself.
+            // `0x5adbb2` is the chain loop's continue label.
             Self::Group => Ordering::Equal,
         }
     }
 }
 
-/// The seven-slot `{key, dir}` chain at `0xc2817c`/`0xc28180`: the sort keys most-recently-used
-/// first, each with the direction it was last left in. See the module doc.
+/// The seven-slot chain: keys most recently used first, each with the direction it was left in.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct WhoSortChain {
-    /// `(key, reversed)`, slot 0 first. Every key appears exactly once — a promote permutes, it
-    /// never inserts or drops.
+    /// `(key, reversed)`, slot 0 first; always a permutation of all seven keys.
     slots: [(WhoSortKey, bool); 7],
 }
 
@@ -123,14 +94,12 @@ impl Default for WhoSortChain {
 }
 
 impl WhoSortChain {
-    /// `SortWho`'s promote (`0x5ad980`–`0x5ad9c9`): move `sort_type`'s key to the front, flipping
-    /// its direction **only if it was already there**, and shift the keys it passed down one slot
-    /// each. Keys behind it keep their own remembered directions.
+    /// `SortWho`'s promote (`0x5ad980`–`0x5ad9c9`): move the key to the front, flipping its
+    /// direction only if it was already there; the keys it passes shift down one slot.
     pub fn promote(&mut self, sort_type: &str) {
         let key = WhoSortKey::from_sort_type(sort_type);
         let Some(at) = self.slots.iter().position(|(k, _)| *k == key) else {
-            // Unreachable: the chain is a permutation of all seven keys. The reference's own
-            // not-found edge (`0x5ad991 jmp 0x5ad9cf`) skips the promote and sorts anyway.
+            // Unreachable; the reference's not-found edge skips the promote and sorts (`0x5ad991`).
             return;
         };
         let dir = if at == 0 {
@@ -142,8 +111,8 @@ impl WhoSortChain {
         self.slots[0] = (key, dir);
     }
 
-    /// The comparator `0x5ada00`: walk the chain, return the first key that does not tie —
-    /// negated when that slot's direction is set — and `Equal` when all seven tie.
+    /// The comparator (`0x5ada00`): the first key that does not tie, negated when its slot is
+    /// reversed, else `Equal`.
     pub fn compare(&self, a: &WhoInfo, b: &WhoInfo) -> Ordering {
         for (key, reversed) in self.slots {
             let order = key.order(a, b);
@@ -154,29 +123,21 @@ impl WhoSortChain {
         Ordering::Equal
     }
 
-    /// Order `rows` by the chain — the `qsort` at `0x5ad9cf` (a click) and `0x5ae0e2` (a fresh
-    /// `SMSG_WHO` answer, which is why results arrive already in the current order).
-    ///
-    /// The reference's `qsort` is unstable and this is not; the difference is unobservable,
-    /// because the name key never leaves the chain and no two rows of one realm's `/who` answer
-    /// share a name, so [`Self::compare`] is a total order over the rows that can actually occur.
+    /// Order `rows` by the chain, as the reference's `qsort` does on a click (`0x5ad9cf`) and on
+    /// each `SMSG_WHO` answer (`0x5ae0e2`). This sort is stable where `qsort` is not, which no two
+    /// rows can show: names are unique and the name key never leaves the chain.
     pub fn sort(&self, rows: &mut [WhoInfo]) {
         rows.sort_by(|a, b| self.compare(a, b));
     }
 
-    /// The chain's keys, front (most recently clicked) first — for tests and diagnostics.
     #[cfg(test)]
     fn keys(&self) -> [(WhoSortKey, bool); 7] {
         self.slots
     }
 }
 
-/// `0x64a4c0` → `0x414310`: a **case-insensitive ASCII** compare, folding only `A`–`Z` by `+0x20`
-/// on both operands (`0x41434a`–`0x41435c`) and answering `−1/0/+1`.
-///
-/// Deliberately not `to_lowercase()`: that is a Unicode fold, and it would order the accented
-/// names the localized clients allow differently from the reference, which only ever touches the
-/// 26 ASCII letters.
+/// The reference's string compare (`0x64a4c0`, `0x414310`): it folds `A`–`Z` only
+/// (`0x41434a`–`0x41435c`), so accented names order as they do there, not by a Unicode fold.
 fn ascii_ci_cmp(a: &str, b: &str) -> Ordering {
     let (a, b) = (a.as_bytes(), b.as_bytes());
     for (x, y) in a.iter().zip(b) {
@@ -189,22 +150,10 @@ fn ascii_ci_cmp(a: &str, b: &str) -> Ordering {
     a.len().cmp(&b.len())
 }
 
-/// The three DBC-backed arms' compare. **A row the id could not resolve TIES** — verified on all
-/// three arms (class `0x5ada7b`, race `0x5adadf`, zone `0x5adb40`), which are one idiom
-/// byte-for-byte: three miss conditions (a negative id, an id past the *inclusive* bound, a NULL
-/// row at an in-range id) zero the row register, and either side being zero jumps to `0x5adbb2`,
-/// which **is** the chain loop's `inc esi`. So it is not a returned `0` compared against
-/// something — the key contributes nothing and the next slot decides. `dir` cannot reach it
-/// either (the `neg` is gated behind the compare the tie branch skips).
-///
-/// The tie matters more than it looks: an unresolved id would otherwise sort as `""`, parking
-/// every unknown zone at the top of the list ahead of Ahn'Qiraj.
-///
-/// **The empty string is this side's marker for "no row", and the two sides of the reference
-/// disagree on purpose.** `GetWhoInfo 0x5ad6e0` substitutes the localized `"UNKNOWN"` on the same
-/// three legs, so a row can read UNKNOWN in the cell while sorting as though that column did not
-/// exist. Anything that starts showing UNKNOWN here has to carry the miss to this comparator by
-/// some route other than the string.
+/// The class, race and zone arms (`0x5ada7b`, `0x5adadf`, `0x5adb40`): an id with no DBC row, an
+/// empty name here, ties and passes to the next key (`0x5adbb2`) rather than sorting as `""`. The
+/// empty name is the miss marker: the reference's `GetWhoInfo` (`0x5ad6e0`) shows `UNKNOWN` for
+/// it, benilla's an empty cell, and a row that carried `UNKNOWN` would sort on that word.
 fn dbc_name_cmp(a: &str, b: &str) -> Ordering {
     if a.is_empty() || b.is_empty() {
         return Ordering::Equal;
@@ -231,8 +180,6 @@ mod tests {
         rows.iter().map(|r| r.name.as_str()).collect()
     }
 
-    /// The seeded chain is the reference's `key[i] = i`, all ascending — so a list nobody has
-    /// clicked is ordered zone, then level, then class, then name.
     #[test]
     fn the_chain_is_seeded_in_key_order() {
         assert_eq!(
@@ -249,8 +196,6 @@ mod tests {
         );
     }
 
-    /// The key mapping, including the case-insensitive compares and the name fallback that
-    /// swallows every unrecognised string.
     #[test]
     fn the_sort_type_maps_case_insensitively_and_falls_back_to_name() {
         for (arg, key) in [
@@ -275,7 +220,6 @@ mod tests {
         }
     }
 
-    /// **B365's headline.** A first click sorts ascending; the *same* key clicked again reverses.
     #[test]
     fn a_repeated_click_reverses() {
         let mut rows = vec![
@@ -297,10 +241,6 @@ mod tests {
         assert_eq!(names(&rows), ["Erdrin", "Galas"], "and back again");
     }
 
-    /// The flip is `i == 0` ONLY. Clicking a different key in between promotes name from slot 1
-    /// with its remembered direction *carried*, so the third click below does not re-reverse —
-    /// it restores what the second one left, which is the half a naive "toggle on every click"
-    /// implementation gets wrong.
     #[test]
     fn promoting_from_behind_carries_the_direction_it_left() {
         let mut chain = WhoSortChain::default();
@@ -309,7 +249,7 @@ mod tests {
         chain.promote("level"); // name drops to slot 1, still descending
         assert_eq!(chain.keys()[1], (WhoSortKey::Name, true));
 
-        chain.promote("name"); // back to the front — NOT a flip
+        chain.promote("name"); // back to the front, not a flip
         assert_eq!(chain.keys()[0], (WhoSortKey::Name, true));
 
         let mut rows = vec![
@@ -320,9 +260,6 @@ mod tests {
         assert_eq!(names(&rows), ["Bbb", "Aaa"], "still descending");
     }
 
-    /// The displaced keys stay behind the clicked one, most-recently-used first — so a click is a
-    /// tie-breaker chain, not a fresh single-key sort. Level, then class: rows equal on class
-    /// keep the *level* order the earlier click established.
     #[test]
     fn earlier_clicks_survive_as_tie_breakers() {
         let mut chain = WhoSortChain::default();
@@ -346,7 +283,6 @@ mod tests {
         );
     }
 
-    /// The level arm is the numeric one, and ascending means the LOWER level first.
     #[test]
     fn level_ascends_before_it_reverses() {
         let mut rows = vec![row("High", 60, "Mage", "Z"), row("Low", 12, "Mage", "Z")];
@@ -359,8 +295,6 @@ mod tests {
         assert_eq!(names(&rows), ["High", "Low"]);
     }
 
-    /// Names fold case the way `0x414310` does — `apple` and `Apple` compare equal, and `Zed`
-    /// sorts after `apple` rather than before it as a byte compare would have it.
     #[test]
     fn the_string_arms_fold_ascii_case() {
         assert_eq!(ascii_ci_cmp("Apple", "apple"), Ordering::Equal);
@@ -369,16 +303,12 @@ mod tests {
         assert_eq!(ascii_ci_cmp("Ann", "Anne"), Ordering::Less, "prefix first");
     }
 
-    /// An unresolved DBC name ties rather than sorting as `""` — otherwise every row whose zone
-    /// id has no `AreaTable` row would pile up at the top of a zone sort.
     #[test]
     fn an_unresolved_dbc_name_ties() {
         let mut chain = WhoSortChain::default();
         chain.promote("zone");
         let known = row("Bbb", 10, "Mage", "Westfall");
         let unknown = row("Aaa", 10, "Mage", "");
-        // Not `Less`: a `""` zone does not sort first, it does not sort at all — the zone key
-        // ties and the chain falls through to the name, where Aaa beats Bbb.
         assert_eq!(
             chain.compare(&known, &unknown),
             Ordering::Greater,
@@ -386,12 +316,10 @@ mod tests {
         );
         assert_eq!(chain.compare(&unknown, &known), Ordering::Less);
 
-        // A *guild* is not a DBC lookup: an empty guild is a real value and sorts first.
+        // A guild is not a DBC lookup: an empty guild is a real value and sorts first.
         assert_eq!(ascii_ci_cmp("", "Legacy"), Ordering::Less);
     }
 
-    /// `"group"` is a live chain key with a dead arm: it displaces whatever was at the front, and
-    /// orders nothing itself, so the list falls straight through to the rest of the chain.
     #[test]
     fn the_group_key_displaces_but_orders_nothing() {
         let mut chain = WhoSortChain::default();
@@ -410,8 +338,6 @@ mod tests {
         );
     }
 
-    /// Every key ties ⇒ `Equal`, the comparator's `xor eax,eax` tail. Only reachable for two rows
-    /// that agree on all six live keys.
     #[test]
     fn identical_rows_tie_on_every_key() {
         let chain = WhoSortChain::default();
diff --git a/crates/benilla-ui/src/script/worldmap.rs b/crates/benilla-ui/src/script/worldmap.rs
index 0e7feef1..1e5a10d2 100644
--- a/crates/benilla-ui/src/script/worldmap.rs
+++ b/crates/benilla-ui/src/script/worldmap.rs
@@ -1,153 +1,86 @@
-//! The world-map bindings (decision 0203 phase 2) — the Era-shaped map-navigation surface the
-//! reference `WorldMapFrame.lua` reads, over the questgiver/quest-log seam shape: the app pushes
-//! a static **catalog** once (continents → zones, from `WorldMapArea`/`AreaTable`/
-//! `WorldMapContinent`) and a small per-frame **feed** (the player's resolved zone, projected map
-//! position, and facing — all projection math stays app-side in `map_proj`); the engine owns the
-//! **selection** (which map is displayed) so `SetMapZoom` → `GetCurrentMapContinent` reads back
-//! synchronously in the same click, exactly like the quest-log selection precedent.
+//! The world-map bindings `WorldMapFrame.lua` reads, over a catalog and a per-frame feed the app
+//! pushes (projection stays in `map_proj`); the engine owns the selection, so `SetMapZoom` reads
+//! back in the same click.
 //!
-//! `SetMapZoom`/`SetMapToCurrentZone`/`ProcessMapClick` queue `WORLD_MAP_UPDATE` through the
-//! model's pending-event queue (fired at the next tick — the reference's synchronous fire is a
-//! repaint trigger, and one tick is invisible at frame rate).
+//! The Lua selection is the client's indices plus one (`0x4a7ed0`, `0x4a7f00`): continent 0 is the
+//! world sheet, zone 0 the whole continent; continents in `WorldMapArea` file order (`0x4a5d00`),
+//! zones by case-insensitive name (`0x4a6390`). An instance map is a third state (`0x4a67a0`).
 //!
-//! Selection encoding (the Lua-visible one, the client's internal indices `+1` — `0x4a7ed0`/
-//! `0x4a7f00`): continent `0` = the world sheet, `1..` = the catalog's continents; zone `0` = the
-//! whole continent, `1..` = that continent's zone list. The catalog's *order* defines those
-//! indices everywhere (dropdowns, `SetMapZoom`, the feed) — the app builds it under the
-//! verified rules (WorldMapArea file order for continents, `0x4a5d00`; case-insensitive
-//! display-name sort for zones, `0x4a6390`).
-//!
-//! …and a **third** selection state beside that pair: the **direct area**, the map of an
-//! instance — a battleground, a dungeon — which is no continent's child and so falls out of both
-//! lists (`0x4a67a0`). The reference does not
-//! encode it inside `(continent, zone)`: it carries THREE `.data` cells, and `continent == -2`
-//! with a `WorldMapArea` row **ID** in the third one IS that state ([`WorldMapState::direct_area`]).
-//! Inside Warsong Gulch a client without it answers `GetMapInfo() == nil`, and the stock
-//! `Blizzard_BattlefieldMinimap.lua:83-86` returns on the fourth line of its update — an empty
-//! battle map and an empty world map, which is the bug this models away.
-//!
-//! Continent-level hover/click resolve through the pushed **zone grid** — the 128×128 area
-//! bitmap (`Interface\WorldMap\<Continent>.zmp`, remapped app-side to 1-based zone indices; the
-//! source + cell law read at `0x4a5feb`/`0x4a6ec0`). The cell
-//! law itself is transcribed here ([`area_grid_cell`]) rather than in the app's `map_proj`
-//! because its only callers are these bindings. `UpdateMapHighlight` answers per level exactly
-//! as `0x4a7fa0` does: at continent level the hovered zone's name **and** its
-//! highlight quad; at zone level a **name only** — a revealed overlay's sub-area when the cursor
-//! is inside its `WorldMapOverlay` hit rect, else the neighbouring zone or city whose grid cell
-//! the cursor is in through the displayed zone's rect window, never the displayed zone itself —
-//! with a nil fileName, so the frame hides the quad (report B360). The world sheet's continent
-//! highlight is not built: hovering a continent there answers the nil/zero tail.
-//!
-//! Zone maps carry **exploration fog**: the base tiles are the unexplored parchment, and each
-//! discovered sub-area's overlay art (`GetNumMapOverlays`/`GetMapOverlayInfo`, filtered by the
-//! pushed `PLAYER_EXPLORED_ZONES` bitset) fills it in — the reference's own overlay pool draws
-//! the returned pieces. The landmark family (`GetNumMapLandmarks`/`GetMapLandmarkInfo`) answers
-//! with the `AreaPOI.dbc` rows the displayed level admits, then the guard-directions marker
-//! (decisions 1586, 1514).
+//! Deviation: `WORLD_MAP_UPDATE` fires at the next tick, where the reference fires it
+//! synchronously, because it only triggers a repaint and one tick is invisible.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// One zone row in a continent's list. Its 1-based position IS the zone index Lua sees.
+/// One zone of a continent; its 1-based position is the Lua zone index.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct WorldMapZoneView {
-    /// The display name (AreaTable's localized string — "Elwynn Forest").
+    /// `AreaTable.dbc`'s localized name, "Elwynn Forest".
     pub name: String,
-    /// The AreaTable id (the feed's player-zone resolution joins on this; phase 3 overlays too).
+    /// The `AreaTable.dbc` id the feed's player-zone resolution joins on.
     pub area_id: u32,
-    /// The `Interface\WorldMap\<file>\` art folder (WorldMapArea's internal name — "Elwynn").
+    /// The `Interface\WorldMap\<file>\` art folder, `WorldMapArea`'s internal name ("Elwynn").
     pub map_file: String,
-    /// This zone's WorldMapArea loc rect `(left, right, top, bottom)` — the window the continent
-    /// highlight sizes/seats against, and the rect the zone-level `ProcessMapClick` un-lerps
-    /// through (`0x4a6ec0`: the zone is a rect window onto the one per-continent bitmap).
+    /// The `WorldMapArea` loc rect `(left, right, top, bottom)`; at zone level, the grid's window.
     pub loc_rect: (f32, f32, f32, f32),
-    /// The zone's discovery overlays (WorldMapOverlay rows) — the art that fills the parchment
-    /// as sub-areas are explored (`GetNumMapOverlays`/`GetMapOverlayInfo`).
     pub overlays: Vec<WorldMapOverlayView>,
 }
 
-/// One **map landmark** — a POI icon on the displayed map (`GetNumMapLandmarks` /
-/// `GetMapLandmarkInfo`). The app projects it, so what arrives here is already map UV.
-///
-/// Two sources feed it, in the reference's own order (its builder `0x4a67a0`):
-///
-/// - the **`AreaPOI.dbc` rows** that survive the builder's level-flag, exploration and
-///   world-state gates — the town and capital icons, the capitals' "Under Attack" markers, and the
-///   Eastern Plaguelands towers (decision 1586);
-/// - then the **guard-directions marker** (`SMSG_GOSSIP_POI` — the flag a guard drops when you ask
-///   where the warrior trainer is), appended last as the one element with `+0x10 == 1` and exempt
-///   from every gate above.
+/// A POI icon on the displayed map, projected to map UV. The reference's builder (`0x4a67a0`)
+/// lists the `AreaPOI.dbc` rows past its level, exploration and world-state gates, then the
+/// guard-directions marker (`SMSG_GOSSIP_POI`, `+0x10 == 1`), ungated.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct WorldMapLandmarkView {
-    /// The label its tooltip shows ("Stormwind Warrior Trainer").
     pub name: String,
-    /// The second tooltip line — a live status string on the AreaPOI rows that carry one (a
-    /// battleground node's "In Conflict"); empty for the guard marker.
+    /// The second tooltip line, a live status such as "In Conflict"; empty for the guard marker.
     pub description: String,
-    /// The `Interface\Minimap\POIIcons` cell, 8×8 grid (the guard marker's is `6` — the red flag).
+    /// The `Interface\Minimap\POIIcons` cell in its 8×8 grid.
     pub texture_index: u32,
-    /// Position on the DISPLAYED map, `[0,1]` UV from its top-left.
+    /// Position on the displayed map, UV from its top-left.
     pub uv: (f32, f32),
 }
 
-/// One discovery overlay: a sub-area's map art, drawn over the base tiles once any of its
-/// explore bits is set (decision 0203 phase 3).
+/// A sub-area's map art, drawn over the base tiles once any of its explore bits is set.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct WorldMapOverlayView {
-    /// The full texture path prefix (`Interface\WorldMap\<Zone>\<TexName>`) — the reference Lua
-    /// appends the piece number (`..1`, `..2`, …) exactly as the client's C return does.
+    /// The path prefix `Interface\WorldMap\<Zone>\<TexName>`; the Lua appends the piece number.
     pub texture: String,
-    /// The overlay's art size in map px (the Lua slices it into 256-tiles with POT file sizes).
     pub width: u32,
     pub height: u32,
-    /// Placement within the 1002×668 detail frame, px from its TOPLEFT.
+    /// Placement in the 1002×668 detail frame, pixels from its top-left.
     pub offset_x: u32,
     pub offset_y: u32,
-    /// The AreaTable `exploreFlag` bit indices that reveal this overlay (any set bit shows it;
-    /// empty = never shown — an overlay whose areas are unknown).
+    /// The `AreaTable.dbc` exploreFlag bits that reveal it, any one sufficing; empty never shows.
     pub explore_bits: Vec<u32>,
-    /// The hover hit rect `(top, left, bottom, right)`, px of the 1002×668 detail frame — the
-    /// DBC's own `HitRect*` fields. The zone-level `UpdateMapHighlight` scales it by 1/1002 and
-    /// 1/668 and tests the normalized cursor against it, both edges inclusive
-    /// (`0x4a7ffc..0x4a80ea`).
+    /// The DBC's `HitRect*` `(top, left, bottom, right)` in detail-frame pixels, which the
+    /// zone-level hover tests with both edges inclusive (`0x4a7ffc..0x4a80ea`).
     pub hit_rect: (u32, u32, u32, u32),
-    /// The name that hover shows inside the rect: the localized AreaTable name of the overlay's
-    /// FIRST area slot (`0x4a7fa0` reads `+0x8` only). `None` when that slot resolves to no row —
-    /// the client then walks past the overlay exactly as if the cursor were outside it.
+    /// The hover name: the `AreaTable.dbc` name of the first area slot only (`0x4a7fa0` reads
+    /// `+0x8`); `None` walks past the overlay as if the cursor were outside.
     pub area_name: Option<String>,
 }
 
-/// One continent. Its 1-based position IS the continent index Lua sees.
+/// One continent; its 1-based position is the Lua continent index.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct WorldMapContinentView {
-    /// The display name — Map.dbc's localized MapName ("Eastern Kingdoms", "Kalimdor"), the
-    /// client's own dropdown-label source (`0x4a65a0`), never the art folder string.
+    /// `Map.dbc`'s localized MapName, the dropdown label (`0x4a65a0`), not the art folder.
     pub name: String,
-    /// The `Interface\WorldMap\<file>\` art folder.
     pub map_file: String,
-    /// This continent's rect on the world sheet, normalized UV `(u0, v0, u1, v1)` — world-level
-    /// `ProcessMapClick` picks the first continent (catalog order) containing the click, exactly
-    /// the client's AABB walk (`0x4a7100`'s world branch over the record trailer floats). The
-    /// app computes it with the verified `0x4a5d00` kernel (`map_proj::continent_sheet_rect`,
-    /// from the WorldMapContinent tile bounds); the 5875 rects are disjoint.
+    /// The rect on the world sheet in UV `(u0, v0, u1, v1)`, from the `WorldMapContinent` tile
+    /// bounds (`0x4a5d00`); a world-level click takes the first that holds it (`0x4a7100`).
     pub world_rect: (f32, f32, f32, f32),
-    /// The continent's WorldMapArea world rect (loc left/right/top/bottom) — the rect the
-    /// `0x4a6ec0` cell law un-lerps hover/click UVs through ([`area_grid_cell`]).
+    /// The `WorldMapArea` loc rect the cell law un-lerps a hover or click through.
     pub loc_rect: (f32, f32, f32, f32),
-    /// The 128×128 area bitmap, remapped app-side to **1-based zone indices** into
-    /// [`Self::zones`] (0 = no zone; empty = no bitmap shipped — hover/click inert). Row-major,
-    /// indexed by [`area_grid_cell`].
+    /// The 128×128 area bitmap (`<Continent>.zmp`, read at `0x4a5feb`) as 1-based indices into
+    /// [`Self::zones`], 0 for none; empty when no bitmap ships, leaving hover and click inert.
     pub zone_grid: Vec<u16>,
-    /// The continent's zones, in Lua index order.
     pub zones: Vec<WorldMapZoneView>,
 }
 
-/// The `0x4a6ec0` cell law, verbatim: clamp the UV, un-lerp through the continent's WorldMapArea
-/// rect back to world coords, quantize on the half-ADT world grid (2.9296876e-5 = 1/(64·533.33),
-/// the binary's 0x806544), range-check, index `col − row·128` (row is truncated from the negated
-/// axis, so it's ≤ 0). Verified against the shipped Azeroth.zmp: Goldshire's world position
-/// lands on cell 12735 = Elwynn Forest.
+/// The `0x4a6ec0` cell law: clamp the UV, un-lerp through the loc rect to world coordinates,
+/// scale by `0x806544` (1/(64·533.33)), range-check, and index `col - row·128`, `row` being
+/// truncated from the negated axis and so `<= 0`.
 fn area_grid_cell(loc: (f32, f32, f32, f32), u: f32, v: f32) -> Option<usize> {
     const K: f32 = 2.929_687_6e-5;
     let (left, right, top, bottom) = loc;
@@ -178,18 +111,11 @@ fn area_grid_cell(loc: (f32, f32, f32, f32), u: f32, v: f32) -> Option<usize> {
         .filter(|&i| i < 128 * 128)
 }
 
-/// The hovered/clicked child (zone OR city) at the current CONTINENT or ZONE selection: the grid
-/// cell's 1-based index into the continent's `zones`, or `None` off-land / off-grid / at world
-/// level. The rect that windows the one per-continent 128×128 bitmap is the continent's own loc
-/// rect at continent level, the CURRENT zone's loc rect at zone level — there is no per-zone
-/// bitmap, a zone/city is just a different rect window (`0x4a6ec0`). This
-/// is what lets a click on a city's footprint from its neighbouring zone map drill into the city.
+/// The 1-based zone or city under a hover or click: the continent's one grid, windowed by its own
+/// loc rect at continent level and by the displayed zone's at zone level (`0x4a6ec0`).
 fn grid_area(state: &WorldMapState, u: f32, v: f32) -> Option<u16> {
-    // The direct-area state has no bitmap and is refused before the cell law runs: `0x4a6ec0`
-    // opens `cmp esi,-2; je 0x4a70ed` — the chain
-    // ships exactly three `.zmp` files and none of them is a battleground's. Explicit rather than
-    // left to `c == 0` below, because "the world sheet" and "an instance map" are different
-    // states that happen to share that cell.
+    // An instance map has no grid (`0x4a6ec0` opens `cmp esi,-2; je 0x4a70ed`); tested apart from
+    // `c == 0`, which the world sheet shares.
     if state.direct_area.is_some() {
         return None;
     }
@@ -213,8 +139,7 @@ fn grid_area(state: &WorldMapState, u: f32, v: f32) -> Option<u16> {
     }
 }
 
-/// Power-of-two round-up (≥ n, ≥ 1) — the client's round-up at `0x4a833c`, used for the
-/// continent highlight's vertical texcoord crop (`texPercentageY = dim / potdim`).
+/// The client's power-of-two round-up (`0x4a833c`).
 fn next_pow2(n: i64) -> i64 {
     let mut p = 1i64;
     while p < n {
@@ -223,97 +148,58 @@ fn next_pow2(n: i64) -> i64 {
     p
 }
 
-/// The engine-side world-map state: the pushed catalog + feed, and the engine-owned selection.
+/// The engine-side world-map state: the pushed catalog and feed, and the selection.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct WorldMapState {
-    /// The static catalog (pushed once at startup; empty until then — every binding degrades to
-    /// the world level, where `GetMapInfo` returns nil and the reference Lua falls back to
-    /// `"World"`).
+    /// The catalog, pushed once at startup; until then every binding answers as at world level.
     pub continents: Vec<WorldMapContinentView>,
-    /// The **orphan list** — the third array the reference's catalog builder fills (`0x4a5d00`'s
-    /// count/fill passes `0x4a6130`/`0x4a61c9`): every `WorldMapArea` row with `areaID != 0`
-    /// whose mapID matches **no** continent record, as `(row ID, the row)`, in DBC **file order,
-    /// unsorted** — the three battlegrounds in 5875. Keyed by id, never indexed: nothing outside
-    /// [`direct_row`]'s lookup reads a position here, because the selection stores the row's own
-    /// ID rather than a place in this list.
+    /// The orphan list the reference's catalog builder also fills (`0x4a6130`, `0x4a61c9`): each
+    /// `WorldMapArea` row with `areaID != 0` on no continent's map, the three battlegrounds.
     pub direct_areas: Vec<(u32, WorldMapZoneView)>,
-    /// The displayed map: `(continent, zone)`, `(0, 0)` = the world sheet. **Not the whole
-    /// selection on its own** — [`Self::direct_area`] overrides it.
+    /// The displayed `(continent, zone)`, `(0, 0)` the world sheet, unless [`Self::direct_area`].
     pub selection: (u32, u32),
-    /// The **direct-area selection**: the `WorldMapArea` row **ID** of an instance map, or `None`
-    /// at every continent/zone/world selection.
-    ///
-    /// The reference's selection is THREE `.data` cells, not two: `[0x84506c]` continent,
-    /// `[0x845070]` zone, `[0x845074]` direct. `continent == -2` IS this state, and the third cell
-    /// then holds the row's own id — **not** an index into [`Self::direct_areas`], which is only
-    /// ever a lookup table.
-    /// The setter `0x4a67a0` keeps the two exclusive (`0x4a67c1` stores the id only on the
-    /// `ecx == -2` leg and jumps past `0x4a67ea`'s `= -1`; every other leg reaches it), so
-    /// `direct_area.is_some()` ⇒ `selection == (0, 0)` — enforced in [`store_selection`], the one
-    /// writer.
+    /// An instance map's `WorldMapArea` row id: the reference's third selection cell `[0x845074]`
+    /// beside continent `[0x84506c]` (then -2) and zone `[0x845070]`. The setter `0x4a67a0` keeps
+    /// it exclusive with the pair (`0x4a67c1`, `0x4a67ea`); [`store_selection`] is the one writer.
     pub direct_area: Option<u32>,
-    /// Where `SetMapToCurrentZone` lands — the player's current `(continent, zone)` resolved by
-    /// the app (AreaTable parent walk × the catalog). `None` = no continent matched → either the
-    /// orphan leg below, or the world sheet.
+    /// The player's `(continent, zone)`, where `SetMapToCurrentZone` lands.
     pub player_zone: Option<(u32, u32)>,
-    /// The orphan half of that same answer: the `WorldMapArea` row ID whose mapID is the player's
-    /// own map, or `None`. `0x4a6650` runs its continent loop FIRST and reaches the orphan loop
-    /// only on a miss (`0x4a66c3`), so at most one of the two is ever set — and inside a
-    /// battleground it is this one.
+    /// The resolver's orphan leg, the `WorldMapArea` row id on the player's map. `0x4a6650`
+    /// reaches it only when its continent loop misses (`0x4a66c3`), so at most one is set.
     pub player_direct_area: Option<u32>,
-    /// `GetPlayerMapPosition("player")` for the CURRENT selection — projected app-side each frame
-    /// (`map_proj`), `None`/(0,0) = off this map (the reference hides the blip).
+    /// `GetPlayerMapPosition("player")` on the displayed map; `None` is off it.
     pub player_uv: Option<(f32, f32)>,
-    /// The world map's arrow frame and the battlefield minimap's — the two per-session
-    /// singletons `CreateWorldMapArrowFrame`/`CreateMiniWorldMapArrowFrame` build, by wrapper id
-    /// (`worldmap_arrow`, 1980). `None` until the first create.
+    /// The arrow frames' wrapper ids, built once per session; `None` until created.
     pub arrow_world: Option<u32>,
     pub arrow_mini: Option<u32>,
-    /// `GetPlayerMapPosition("party1".."party4")` for the CURRENT selection, in `party_slots`
-    /// order — projected app-side through the same law as [`Self::player_uv`] (report B320).
-    /// A slot is `None` when there is no member there, when we hold no position for them, or when
-    /// that position is off the displayed map; all three read as the reference's `(0,0)` hide
-    /// sentinel at the binding, which is the only answer its FrameXML consumer knows.
-    ///
-    /// Shorter than 4 whenever the party is: a missing index is a `None`.
+    /// `party1`..`party4` in `party_slots` order; `None` or missing answers `(0, 0)`.
     pub party_uv: Vec<Option<(f32, f32)>>,
-    /// `raid1..raid40` in roster order — the stock map's raid arm (1980), fed like `party_uv`.
+    /// `raid1`..`raid40` in roster order, fed like [`Self::party_uv`].
     pub raid_uv: Vec<Option<(f32, f32)>>,
-    /// `GetPlayerFacing()` — wow orientation radians (0 = north, counterclockwise-positive). Our
-    /// transcribed frame spins its arrow texture with it (`SetRotation`); the reference rotates
-    /// an engine-rendered arrow model instead (0203 flags the stand-in).
+    /// Radians, 0 north, counterclockwise-positive; `UpdateWorldMapArrowFrames` turns the arrows.
     pub player_facing: f32,
-    /// `GetCorpseMapPosition()` for the CURRENT selection — the corpse-run marker (decision 0308
-    /// §5), projected app-side like [`Self::player_uv`]; `None`/(0,0) = no corpse or off this map
-    /// (the reference's WorldMapFrame.lua:443-452 hide law).
+    /// `GetCorpseMapPosition()` on the displayed map; `None` is no corpse or off the map.
     pub corpse_uv: Option<(f32, f32)>,
-    /// The discovery bitset (`PLAYER_EXPLORED_ZONES_1` — 64 u32 = 2048 bits, bit n = AreaTable
-    /// exploreFlag n), pushed by the app when the descriptor changes. Empty = nothing explored.
+    /// `PLAYER_EXPLORED_ZONES_1`, 64 words, bit n being `AreaTable.dbc` exploreFlag n.
     pub explored: Vec<u32>,
-    /// The POI icons on the displayed map (`GetNumMapLandmarks`/`GetMapLandmarkInfo`), already
-    /// projected into its UV — pushed by the app on change, which repaints an open map.
     pub landmarks: Vec<WorldMapLandmarkView>,
 }
 
-/// Is explore-bit `n` set in the pushed bitset?
 fn explored_bit(explored: &[u32], n: u32) -> bool {
     explored
         .get((n / 32) as usize)
         .is_some_and(|w| w & (1 << (n % 32)) != 0)
 }
 
-/// The reciprocals `0x4a7fa0` scales a `WorldMapOverlay` hit rect by: the rect is authored in
-/// pixels of the 1002×668 detail frame, the cursor arrives normalized, and the client brings the
-/// rect to the cursor (`fild` → `fmul` a f32 constant → `fstp dword`), so the edges are f32.
+/// The f32 reciprocals `0x4a7fa0` scales a hit rect's detail-frame pixels by (`fild`, `fmul`,
+/// `fstp dword`) to meet the normalized cursor, so the edges are f32.
 const OVERLAY_RECIP_X: f32 = 1.0 / 1002.0;
 const OVERLAY_RECIP_Y: f32 = 1.0 / 668.0;
 
-/// The zone-level **overlay pre-search** (`0x4a7ffc..0x4a80ea`): the first
-/// REVEALED overlay whose hit rect contains the cursor names its first area. Both edges are
-/// inclusive; a rect with a zero-width edge never hits; a NaN cursor never hits; an overlay whose
-/// first area resolves to no AreaTable row is walked past, not stopped at. The list is the one
-/// `GetNumMapOverlays` counts — the exploration-gated one (`[0xb6e630]`, built by `0x4a6ad9`
-/// under the explored-byte read at `0x4a6bfa`), so a fogged sub-area has no name.
+/// The zone-level overlay pre-search (`0x4a7ffc..0x4a80ea`): the first revealed overlay whose hit
+/// rect holds the cursor, edges inclusive, names its first area; a zero-width rect or a NaN cursor
+/// never hits, and a nameless overlay is walked past. The list is the revealed one (`[0xb6e630]`,
+/// built by `0x4a6ad9`, gated at `0x4a6bfa`), so a fogged sub-area has no name.
 fn overlay_hover(state: &WorldMapState, x: f32, y: f32) -> Option<String> {
     revealed_overlays(state).into_iter().find_map(|o| {
         let (top, left, bottom, right) = o.hit_rect;
@@ -339,8 +225,6 @@ fn overlay_hover(state: &WorldMapState, x: f32, y: f32) -> Option<String> {
 
 /// What `UpdateMapHighlight` answers for a cursor at map UV `(x, y)` under the current selection.
 enum Hover {
-    /// Continent level, over a zone: its name and the highlight quad — fileName, texPercentageY,
-    /// textureX/Y, scrollChildX/Y (texPercentageX is that branch's constant 1.0).
     Highlight {
         name: String,
         file: String,
@@ -348,16 +232,13 @@ enum Hover {
         texture: (f64, f64),
         scroll: (f64, f64),
     },
-    /// Zone level: a name only — fileName nil, six zeros, the frame hides the quad.
     Name(String),
-    /// Off every area: the nil/zero tail.
     Miss,
 }
 
-/// The continent-level answer for the hovered zone (the `0x4a81de → 0x4a822a` highlight-compute
-/// path, zone-search branch): fileName = its art folder (the frame draws `<file>\<file>Highlight`),
-/// the six coords seat/size/crop that texture over the zone's rect within the continent, keeping
-/// the client's f32/f64 asymmetric narrowing.
+/// The continent-level highlight (`0x4a81de` → `0x4a822a`): the zone's art folder, drawn as
+/// `<file>\<file>Highlight`, and the coords seating it over the zone's rect in the client's mixed
+/// f32 and f64.
 fn continent_hover(cont: &WorldMapContinentView, zone: &WorldMapZoneView) -> Option<Hover> {
     let (cl, cr, ct, cb) = cont.loc_rect;
     let (zl, zr, zt, zb) = zone.loc_rect;
@@ -372,7 +253,7 @@ fn continent_hover(cont: &WorldMapContinentView, zone: &WorldMapZoneView) -> Opt
     let texture_y = (1.0f64 / f64::from(cont_h)) * f64::from(h);
     let scroll_x = f64::from(recip_x * (cl - zl));
     let scroll_y = f64::from(recip_y_f32 * (ct - zt));
-    // texPctY = dim/potdim, dim = __ftol((h·128)/w) (rect-form K = 128).
+    // texPctY = dim / potdim, dim = __ftol(h·128 / w).
     let dim = ((h * 128.0) / w) as i64;
     let potdim = next_pow2(dim);
     let tex_pct_y = if potdim > 0 {
@@ -389,14 +270,12 @@ fn continent_hover(cont: &WorldMapContinentView, zone: &WorldMapZoneView) -> Opt
     })
 }
 
-/// `0x4a7fa0`'s level dispatch. Continent level: the grid cell's zone lights
-/// up. Zone level: the overlay pre-search first, then the same grid re-windowed by the displayed
-/// zone's own rect (`0x4a7620`), which returns nothing for the displayed zone itself — and only the
-/// name-only tail is reachable from there (`0x4a812e`). World level: the continent highlight is
-/// not built, so the tail.
+/// `0x4a7fa0`'s level dispatch. Continent level: the grid's zone highlights. Zone level: the
+/// overlay pre-search, then the grid through the displayed zone's rect (`0x4a7620`), naming a
+/// neighbour but never the displayed zone, name only (`0x4a812e`). World level: the tail, as the
+/// continent highlight the reference draws there is not built here.
 fn hover(wm: &WorldMapState, x: f32, y: f32) -> Hover {
-    // An instance map resolves no area under the cursor: the lookup INSIDE `UpdateMapHighlight`
-    // (`0x4a7620`) opens `cmp esi,-2; je 0x4a76d7` → `xor eax,eax`, so no highlight and no name.
+    // An instance map resolves no area (`0x4a7620` opens `cmp esi,-2; je 0x4a76d7`).
     if wm.direct_area.is_some() {
         return Hover::Miss;
     }
@@ -422,10 +301,8 @@ fn hover(wm: &WorldMapState, x: f32, y: f32) -> Hover {
         .unwrap_or(Hover::Miss)
 }
 
-/// The selected direct area's row, resolved by **id** through the orphan list — the reference's
-/// `[0xc0d5bc]` id-index lookup (`0x4a6cf0`'s `0x4a6d24` leg), which bound-checks on every read
-/// rather than trusting the stored cell. An id no row carries reads back as `None`, which is the
-/// binary's own NULL → `lua_pushnil`.
+/// The direct area's row by id, bound-checked as the reference's `[0xc0d5bc]` lookup is
+/// (`0x4a6d24`); an id no row carries is `None`, its NULL.
 fn direct_row(state: &WorldMapState) -> Option<&WorldMapZoneView> {
     let id = state.direct_area?;
     state
@@ -435,11 +312,8 @@ fn direct_row(state: &WorldMapState) -> Option<&WorldMapZoneView> {
         .map(|(_, row)| row)
 }
 
-/// The displayed map's `WorldMapArea` row, if one is displayed: the selected zone, or — in the
-/// direct-area state — the instance map's own row. `0x4a6cf0` resolves both through the same id
-/// lookup, and `0x4a67a0`'s overlay half admits the `-2` state with the displayed key
-/// `= [0x845074]`, so a battleground's overlays
-/// reveal under the explored-bit gate exactly as a zone's do — no free reveal.
+/// The displayed zone's or instance map's row; `0x4a67a0` keys the -2 state's overlays by
+/// `[0x845074]`, so an instance map's pass the same explored-bit gate.
 fn current_zone(state: &WorldMapState) -> Option<&WorldMapZoneView> {
     if state.direct_area.is_some() {
         return direct_row(state);
@@ -455,7 +329,7 @@ fn current_zone(state: &WorldMapState) -> Option<&WorldMapZoneView> {
         .get(z as usize - 1)
 }
 
-/// The displayed zone's REVEALED overlays, in catalog order (the i-th is `GetMapOverlayInfo(i)`).
+/// The displayed zone's revealed overlays in catalog order, the i-th `GetMapOverlayInfo(i)`.
 fn revealed_overlays(state: &WorldMapState) -> Vec<&WorldMapOverlayView> {
     current_zone(state)
         .map(|zone| {
@@ -472,8 +346,7 @@ fn revealed_overlays(state: &WorldMapState) -> Vec<&WorldMapOverlayView> {
 }
 
 impl super::UiScript {
-    /// Push the static catalog (startup, once the DBCs are read). Queues `WORLD_MAP_UPDATE` so an
-    /// already-open frame repaints (startup normally precedes any frame, harmlessly).
+    /// Pushes the catalog at startup, queueing `WORLD_MAP_UPDATE` so an open map repaints.
     pub fn set_world_map_catalog(&mut self, continents: Vec<WorldMapContinentView>) {
         let mut model = self.model_mut();
         model.worldmap.continents = continents;
@@ -482,9 +355,7 @@ impl super::UiScript {
             .push(("WORLD_MAP_UPDATE".to_string(), Vec::new()));
     }
 
-    /// Push the **orphan list** — the instance maps, keyed by `WorldMapArea` row id (see
-    /// [`WorldMapState::direct_areas`]). Pushed beside the continent catalog at the same edge and
-    /// for the same reason; the reference fills both containers in one walk (`0x4a5d00`).
+    /// Pushes the orphan list beside the catalog, both filled in one walk (`0x4a5d00`).
     pub fn set_world_map_direct_areas(&mut self, direct_areas: Vec<(u32, WorldMapZoneView)>) {
         let mut model = self.model_mut();
         model.worldmap.direct_areas = direct_areas;
@@ -493,17 +364,12 @@ impl super::UiScript {
             .push(("WORLD_MAP_UPDATE".to_string(), Vec::new()));
     }
 
-    /// Push the resolver's **orphan leg** for the player — the `WorldMapArea` row id whose map is
-    /// the player's own, or `None` (see [`WorldMapState::player_direct_area`]). The continent/zone
-    /// leg rides [`Self::set_world_map_feed`]'s `player_zone`; `0x4a6650` computes both in one
-    /// pass and reaches this one only when that one missed.
+    /// Pushes the resolver's orphan leg; the continent leg rides [`Self::set_world_map_feed`].
     pub fn set_world_map_player_direct_area(&mut self, direct_area: Option<u32>) {
         self.model_mut().worldmap.player_direct_area = direct_area;
     }
 
-    /// Push the discovery bitset (the app calls this when `PLAYER_EXPLORED_ZONES` changes —
-    /// including the first stream-in). Queues `WORLD_MAP_UPDATE` so an open zone map fills in
-    /// newly explored art immediately.
+    /// Pushes the discovery bitset; a change queues `WORLD_MAP_UPDATE` so an open map fills in.
     pub fn set_world_map_explored(&mut self, explored: Vec<u32>) {
         let mut model = self.model_mut();
         if model.worldmap.explored != explored {
@@ -514,9 +380,7 @@ impl super::UiScript {
         }
     }
 
-    /// Push the displayed map's landmarks (the app projects them; see [`WorldMapLandmarkView`]).
-    /// On change, queues `WORLD_MAP_UPDATE` — the repaint that re-seats the POI icons, exactly
-    /// the event the overlay push above uses for the same reason.
+    /// Pushes the displayed map's landmarks; a change queues `WORLD_MAP_UPDATE` to re-seat them.
     pub fn set_world_map_landmarks(&mut self, landmarks: Vec<WorldMapLandmarkView>) {
         let mut model = self.model_mut();
         if model.worldmap.landmarks != landmarks {
@@ -527,8 +391,7 @@ impl super::UiScript {
         }
     }
 
-    /// Push the per-frame feed (player zone/projection/facing, the corpse marker, and the party
-    /// slots' projections — see [`WorldMapState`]).
+    /// Pushes the per-frame feed: the player's zone, the projected positions and the facing.
     pub fn set_world_map_feed(
         &mut self,
         player_zone: Option<(u32, u32)>,
@@ -547,32 +410,18 @@ impl super::UiScript {
         model.worldmap.raid_uv = raid_uv;
     }
 
-    /// The engine-owned selection — the app reads it each frame to project the feed for the
-    /// displayed map. **All three of the reference's cells**, in its own order: the continent and
-    /// zone pair (`0` = whole), then the direct-area row id
-    /// ([`WorldMapState::direct_area`]) which overrides both when it is `Some`. A consumer that
-    /// reads only the pair sees an instance map as the world sheet — which is precisely the bug
-    /// that left the battle map empty — so the third cell travels with them.
+    /// The selection's three cells, which the app reads each frame to project the feed: continent,
+    /// zone, and the direct-area id that overrides them when `Some`. The pair alone reads an
+    /// instance map as the world sheet.
     pub fn world_map_selection(&self) -> (u32, u32, Option<u32>) {
         let wm = &self.model_ref().worldmap;
         (wm.selection.0, wm.selection.1, wm.direct_area)
     }
 
-    /// Move the selection **from the engine**, with no Lua in the loop — the reference's
-    /// `SetMap` setter `0x4a67a0` reached from the zone updater `0x494780` rather than from a
-    /// binding, which is how a freshly-logged-in client already shows the player's own zone.
-    ///
-    /// The reference has TWO writers of `[0x84506c]`/`[0x845070]`: the Lua verbs
-    /// (`SetMapZoom`/`SetMapToCurrentZone`/`ProcessMapClick`), and this one. We only ever had the
-    /// first, so until some addon opened the map we sat at the world level — and at the world
-    /// level `GetPlayerMapPosition` answers a world-SHEET uv (`0x4a7360` step 2), which every
-    /// addon that assumes a zone uv silently mis-scales. See [`crate::script::worldmap`]'s caller
-    /// in `ui_world_map::feed_world_map` for the gate.
-    ///
-    /// It takes the resolver's whole answer — including the orphan leg — because `0x4947ac` calls
-    /// `0x4a6650`, the same resolver `SetMapToCurrentZone` does: a player logging straight into a
-    /// battleground is on the battleground's own map before any Lua runs, exactly as one logging
-    /// into Elwynn is on Elwynn's.
+    /// Moves the selection from the engine, as the zone updater `0x494780` calls the setter
+    /// `0x4a67a0`: a fresh login shows the player's map before any Lua runs, not the world sheet,
+    /// whose `GetPlayerMapPosition` is sheet UV (`0x4a7360`). It takes the resolver's whole
+    /// answer, orphan leg included, as `0x4947ac` calls `0x4a6650`.
     pub fn sync_world_map_to_player_zone(
         &mut self,
         continent: u32,
@@ -583,27 +432,15 @@ impl super::UiScript {
         select_resolved(&mut model, continent, zone, direct_area);
     }
 
-    /// The **normalized position within the map art** at UI-space `(x, y)`, or `None` when the
-    /// point isn't over it. Reproduces the reference's own click normalization verbatim —
-    /// `WorldMapFrame.xml`'s `WorldMapButton_OnClick`: `u = (x − left)/width`,
-    /// `v = (top − y)/height` over `WorldMapButton`'s rect — so the UV handed back is the same one
-    /// [`ProcessMapClick`](install) reads and the same one the blips are placed in. The Lua's
-    /// effective-scale division cancels here: point and rect are both already in screen units.
-    ///
-    /// A pure query (fires nothing, mutates nothing). Its consumer is the app-side dev map-jump,
-    /// which needs a click's UV *without* going through the faithful click path — that path drills
-    /// into a zone, and the reference's law for it must not grow a second meaning.
+    /// The map UV at UI point `(x, y)`, or `None` off the art, normalized over `WorldMapButton`
+    /// as `WorldMapButton_OnClick` does (WorldMapFrame.lua:287-291). A pure query for the app's
+    /// dev map-jump, which must not drill in as the click path does.
     pub fn world_map_uv_at(&self, x: f32, y: f32) -> Option<(f32, f32)> {
         let id = self.hit_test(x, y)?;
         let model = self.model_ref();
         let hit = model.id_to_frame.get(&id).copied()?;
-        // The map button, or **anything sitting on it**: the stock file makes every POI icon a
-        // child of `WorldMapButton` (`WorldMapFrame.lua:178`), and so are the player arrow's clear
-        // button and the party/raid blips, so the topmost frame over a town or a teammate is one
-        // of those and not the button. Requiring the button itself made the click deaf exactly
-        // where the map has something to show — the director's report on the stock map. Walking
-        // up rather than widening the name test keeps everything else out: a click on the
-        // continent dropdown or the close button is over neither the button nor its subtree.
+        // The button or anything on it: POI icons (WorldMapFrame.lua:178), the player arrow's
+        // button and the blips are its children and sit on top.
         let mut fh = hit;
         while model.arena.frame(fh)?.name.as_deref() != Some("WorldMapButton") {
             fh = model.arena.frame(fh)?.parent?;
@@ -614,11 +451,8 @@ impl super::UiScript {
     }
 }
 
-/// **The one writer of the three selection cells** — `0x4a67a0`, whose whole job is that the
-/// continent/zone pair and the direct-area id can never both be live: the setter's valid-continent
-/// leg and its `-1` leg both fall into `0x4a67ea mov [0x845074],eax` (`= -1`), and only `ecx == -2`
-/// jumps past it after storing the id (`0x4a67c1`), having already forced the zone cell to `-1`.
-/// Every selection verb in this module goes through here, so neither half can be moved alone.
+/// The one writer of the three selection cells, as the setter `0x4a67a0` is: every leg but
+/// `ecx == -2` clears the direct cell (`0x4a67ea`), and that one stores the id (`0x4a67c1`).
 fn store_selection(model: &mut Model, selection: (u32, u32), direct_area: Option<u32>) {
     model.worldmap.selection = selection;
     model.worldmap.direct_area = direct_area;
@@ -627,9 +461,8 @@ fn store_selection(model: &mut Model, selection: (u32, u32), direct_area: Option
         .push(("WORLD_MAP_UPDATE".to_string(), Vec::new()));
 }
 
-/// Clamp + store a continent/zone selection and queue the repaint event. The shared tail of
-/// `SetMapZoom`/`SetMapToCurrentZone`/`ProcessMapClick` — and it **clears the direct area**, which
-/// is the setter invariant above.
+/// Clamps and stores a continent and zone, clearing the direct area: the tail of `SetMapZoom`,
+/// `SetMapToCurrentZone` and `ProcessMapClick`.
 fn select(model: &mut Model, continent: i64, zone: i64) {
     let c = continent.clamp(0, model.worldmap.continents.len() as i64) as u32;
     let z = if c == 0 {
@@ -641,22 +474,14 @@ fn select(model: &mut Model, continent: i64, zone: i64) {
     store_selection(model, (c, z), None);
 }
 
-/// Select an instance map directly — `0x4a67a0` reached with `ecx == -2`: the zone cell goes to
-/// `-1` (our `0`) and the raw `WorldMapArea` row id lands in `[0x845074]` **verbatim and
-/// unchecked**. We keep it unchecked for the same reason the reference can: every consumer
-/// bound-checks on read ([`direct_row`]), so an id no row carries degrades to the nil map name
-/// instead of corrupting the selection.
+/// Selects an instance map, `0x4a67a0` with `ecx == -2`: the zone cell goes to -1 (our 0) and the
+/// row id is stored unchecked, as every reader bound-checks it ([`direct_row`]).
 fn select_direct(model: &mut Model, wma_id: u32) {
     store_selection(model, (0, 0), Some(wma_id));
 }
 
-/// Apply the resolver `0x4a6650`'s answer — the shared tail of `SetMapToCurrentZone` (`0x4a7e20`
-/// is literally `call 0x4a6650`) and of the engine's own first-world-enter sync (`0x4947ac`, the
-/// same function: there is no second resolver).
-///
-/// The orphan leg wins when it is set, and it is set only when no continent matched — the
-/// reference reaches `0x4a66c3` exclusively through the continent loop's miss, so the two answers
-/// are mutually exclusive by construction upstream and the order here is belt-and-braces.
+/// Applies the resolver `0x4a6650`'s answer, the tail of `SetMapToCurrentZone` and of the login
+/// sync (`0x4947ac`).
 fn select_resolved(model: &mut Model, continent: u32, zone: u32, direct_area: Option<u32>) {
     match direct_area {
         Some(id) => select_direct(model, id),
@@ -668,7 +493,7 @@ fn select_resolved(model: &mut Model, continent: u32, zone: u32, direct_area: Op
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetMapContinents() → name1, name2, … (the dropdown list; index = continent number).
+    // GetMapContinents() → the continent names, in index order.
     g.set(
         "GetMapContinents",
         lua.create_function(|lua, ()| {
@@ -683,12 +508,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetMapZones(continent) → name1, name2, … (that continent's zone list; index = zone number).
-    // A NEGATIVE continent answers empty — `0x4a7d10`'s `dec edi; cmp edi,[0xb6e664]; jae` is an
-    // unsigned bound, so `GetCurrentMapContinent()`'s `-1` on an instance map takes the empty
-    // exit. That emptiness is load-bearing: it is what leaves `WorldMapZoneButton_OnClick` with
-    // no button to fire, and so what stops a `SetMapZoom(-1, id)` from writing a bogus row id
-    // into the direct cell.
+    // GetMapZones(continent) → the zone names. A negative continent answers none, as `0x4a7d10`'s
+    // bound is unsigned (`dec edi; cmp edi,[0xb6e664]; jae`): an instance map's empty zone list is
+    // what keeps `WorldMapZoneButton_OnClick` from calling `SetMapZoom(-1, id)`.
     g.set(
         "GetMapZones",
         lua.create_function(|lua, c: i64| {
@@ -707,13 +529,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCurrentMapContinent() / GetCurrentMapZone() — the selection halves (0 = world / whole
-    // continent). The reference reads them right after SetMapZoom in the same click. Each is its
-    // cell `+ 1` and nothing else (`0x4a7ed0`, `0x4a7f00`: a straight-line fild/pushnumber), so
-    // the direct-area state answers **-1** (from the `-2` sentinel) and **0** (the zone cell it
-    // forces to `-1`). The `-1` is a value no stock path tests for, and benignly: it leaves
-    // `WorldMapFrame.lua:59`'s zoom-out button enabled, and the zone dropdown it would feed is
-    // empty because `GetMapZones(-1)` takes the unsigned-bound exit below.
+    // GetCurrentMapContinent() / GetCurrentMapZone(): each cell plus one (`0x4a7ed0`, `0x4a7f00`),
+    // so an instance map answers -1 and 0.
     g.set(
         "GetCurrentMapContinent",
         lua.create_function(|lua, ()| {
@@ -732,7 +549,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetMapZoom(continent[, zone]) — the dropdowns' and zoom-out button's navigation verb.
     g.set(
         "SetMapZoom",
         lua.create_function(|lua, (c, z): (i64, Option<i64>)| {
@@ -742,10 +558,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetMapToCurrentZone() — the OnShow verb: jump to the player's own map (app-resolved feed).
-    // `0x4a7e20` is `call 0x4a6650; xor eax,eax; ret`, so this is the resolver's whole answer,
-    // orphan leg included — which is what puts a player standing in Warsong Gulch on the Warsong
-    // Gulch map. The stock battlefield minimap calls it itself on PLAYER_ENTERING_WORLD.
+    // SetMapToCurrentZone(): the resolver's whole answer, orphan leg included (`0x4a7e20` is
+    // `call 0x4a6650; xor eax,eax; ret`).
     g.set(
         "SetMapToCurrentZone",
         lua.create_function(|lua, ()| {
@@ -757,23 +571,16 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetMapInfo() → mapFileName (the Interface\WorldMap\<name>\ folder). World level → nil —
-    // the reference Lua's own `"World"` fallback exists because the client returned nil there
-    // (`0x4a6cf0`).
-    //
-    // The name is `WorldMapArea` field[3], the **art-folder identifier** — "WarsongGulch", never
-    // the localized "Warsong Gulch": `0x4a6cf0` reads `[row+0xc]` with no locale multiplier, in
-    // deliberate contrast to `0x4a8740`'s `[rec + 4*[0xc0e080] + 0x2c]` AreaTable read. That is
-    // why FrameXML interpolates it straight into `Interface\WorldMap\<name>\<name>1..12`.
+    // GetMapInfo() → mapFileName and two texture dimensions (`0x4a7e30`, `mov eax,3`): nil, 0, 0
+    // at world level. The name is the unlocalized art folder (`0x4a6cf0` reads `[row+0xc]`).
     g.set(
         "GetMapInfo",
         lua.create_function(|lua, ()| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             let wm = &model.worldmap;
             let file = match (wm.direct_area, wm.selection) {
-                // The direct-area state — an instance map, resolved by id through the orphan
-                // list. `0x4a6cf0`'s `jl 0x4a6d24` sends BOTH negative continents here and the
-                // `-1` world level answers nil only because its third cell is `-1` too.
+                // An instance map, by id through the orphan list: `0x4a6cf0`'s `jl 0x4a6d24`
+                // sends both negative continents there, and world level's third cell is -1.
                 (Some(_), _) => direct_row(wm).map(|row| row.map_file.clone()),
                 (None, (0, _)) => None,
                 (None, (c, z)) => wm.continents.get(c as usize - 1).map(|cont| match z {
@@ -785,16 +592,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                         .unwrap_or_else(|| cont.map_file.clone()),
                 }),
             };
-            // THREE values, always: `0x4a7e30` pushes all three unconditionally and returns
-            // `mov eax,3` from its single `ret`, so the world-level answer is `nil, 0, 0` rather
-            // than one nil. (Its four conditional jumps all sit inside slot 3's power-of-two
-            // round and none gates a push. `arity_conf = exact`; decision 1845.)
-            //
-            // The two zeros are the map art's texture dimensions, which no caller reads: both
-            // consumers bind slot 2 to a `textureHeight` local they never read again. They are
-            // **0 on every instance map** in the reference too — `0x4a6d50` scans
-            // `WorldMapContinent.dbc` for the row's mapID and that table ships only mapIDs
-            // {0, 1}, so the scan exhausts.
+            // No caller reads the dimensions, 0 here on every map; the reference computes them
+            // from `WorldMapContinent.dbc` (`0x4a6d50`), which lacks an instance map's mapID.
             let file = match file {
                 Some(f) => Value::String(lua.create_string(&f)?),
                 None => Value::Nil,
@@ -803,8 +602,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCorpseMapPosition() → x, y in [0,1] map UV; (0,0) = no corpse / not on this map — the
-    // reference's hide sentinel (WorldMapFrame.lua:445), same shape as the player position below.
+    // GetCorpseMapPosition() → map UV, or (0, 0), which WorldMapFrame.lua:445 hides.
     g.set(
         "GetCorpseMapPosition",
         lua.create_function(|lua, ()| {
@@ -814,9 +612,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPlayerMapPosition(unit) → x, y in [0,1] map UV; (0,0) = not on this map (hide the
-    // blip). `"player"`, `"party1".."party4"` (report B320) and `"raid1".."raid40"` (1980, the
-    // stock map's raid arm over its `WorldMapRaid1..40` pool) resolve; anything else is (0,0).
+    // GetPlayerMapPosition(unit) → map UV, or (0, 0) off the map; `player`, `party1`..`party4`
+    // and `raid1`..`raid40` resolve, anything else is (0, 0).
     g.set(
         "GetPlayerMapPosition",
         lua.create_function(|lua, unit: String| {
@@ -838,9 +635,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPlayerFacing() → wow orientation radians (counterclockwise-positive, 0 = north). Feeds
-    // the transcribed frame's arrow SetRotation (the reference's engine arrow reads facing
-    // natively; a Lua-visible getter is our seam for the texture stand-in).
+    // GetPlayerFacing() → the facing in radians. Not a 1.12 global.
     g.set(
         "GetPlayerFacing",
         lua.create_function(|lua, ()| {
@@ -849,21 +644,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ProcessMapClick(x, y) — normalized click within WorldMapButton (`0x4a7f30`).
-    // World level: pick the first continent whose sheet-rect contains the click (the 0x4a7100
-    // AABB walk; the 5875 rects are disjoint). Continent OR zone level: identical instructions —
-    // the 0x4a6ec0 grid cell through the CURRENT selection's rect (the continent's, or the current
-    // zone's) → a continent child index → drill. Because a city is just another child, a click on
-    // its footprint — from the continent map, or from a neighbouring zone map when the footprint
-    // falls in that zone's window — drills into the city's own map.
+    // ProcessMapClick(x, y) (`0x4a7f30`): at world level the first continent whose sheet rect
+    // holds the click (`0x4a7100`); otherwise the zone or city under it through the displayed
+    // rect (`0x4a6ec0`), which it drills into.
     g.set(
         "ProcessMapClick",
         lua.create_function(|lua, (x, y): (f32, f32)| {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // An instance map swallows the click: the drill INSIDE `ProcessMapClick`
-            // (`0x4a7540`) opens `cmp esi,-2; je 0x4a760d`, a bare epilogue. Ahead of the world
-            // arm below, because the direct state shares its `continent == 0` cell and must not
-            // fall into the world sheet's continent walk.
+            // An instance map swallows the click (`0x4a7540` opens `cmp esi,-2; je 0x4a760d`),
+            // tested first as it shares the world sheet's `continent == 0`.
             if model.worldmap.direct_area.is_some() {
                 return Ok(());
             }
@@ -884,9 +673,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // UpdateMapHighlight(x, y) → name, fileName, texPctX, texPctY, textureX, textureY,
-    // scrollChildX, scrollChildY (`0x4a7fa0`) — the per-level law is [`hover`].
-    // Eight values always: the frame reads `fileName` to decide whether a quad is drawn at all,
-    // so a name-only answer carries a nil there and six zeros behind it.
+    // scrollChildX, scrollChildY (`0x4a7fa0`): eight values always, a nil fileName hiding the quad.
     g.set(
         "UpdateMapHighlight",
         lua.create_function(|lua, (x, y): (f32, f32)| {
@@ -918,8 +705,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetNumMapLandmarks() — how many POI icons the displayed map carries: the `AreaPOI.dbc` rows
-    // that pass the builder's gates, then the guard-directions marker.
     g.set(
         "GetNumMapLandmarks",
         lua.create_function(|lua, ()| {
@@ -928,15 +713,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetMapLandmarkInfo(i) → name, description, textureIndex, x, y — the i-th (1-based) landmark
-    // (return shape at `0x4a8740`).
-    // `textureIndex` indexes `Interface\Minimap\POIIcons`' 8×8 grid, already resolved app-side
-    // through the reference's own leg (`0x4a8848`): a row's `Icon`, or the constant 15 at zone
-    // level unless it carries `Flags & 0x80`; the guard's marker is its packet `Icon` verbatim.
-    // x/y are `[0,1]` UV on the displayed map, the same space `GetPlayerMapPosition` answers in. A
-    // landmark with no description answers **nil** there, as the reference does (`0x6f3890` pushes
-    // nil on a NULL string) — the guard's marker never carries one, and neither do the ~2/3 of
-    // AreaPOI rows with no live status text.
+    // GetMapLandmarkInfo(i) → name, description, textureIndex, x, y (`0x4a8740`). textureIndex is
+    // a row's Icon, or 15 at zone level without `Flags & 0x80` (`0x4a8848`), and the guard
+    // marker's packet Icon; an empty description is nil, as `0x6f3890` pushes for a NULL string.
     g.set(
         "GetMapLandmarkInfo",
         lua.create_function(|lua, i: i64| {
@@ -964,11 +743,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetNumMapOverlays() — how many of the displayed map's overlays are REVEALED by the
-    // explored bitset (the client's C side filters the same way; the reference Lua draws every
-    // returned overlay). 0 at world/continent level; an instance map is admitted under the same
-    // gate as a zone (see [`current_zone`]) — which on 5875 data means Alterac Valley's three
-    // rows and nothing for the other two battlegrounds.
+    // GetNumMapOverlays(): the displayed map's revealed overlays; 0 at world and continent level.
     g.set(
         "GetNumMapOverlays",
         lua.create_function(|lua, ()| {
@@ -978,8 +753,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // GetMapOverlayInfo(i) → textureName, textureWidth, textureHeight, offsetX, offsetY,
-    // mapPointX, mapPointY — the i-th (1-based) revealed overlay. The texture is the full path
-    // prefix (the Lua appends the piece number); mapPointX/Y are 0 on every 5875 row.
+    // mapPointX, mapPointY; mapPointX and mapPointY are 0 on every 5875 row.
     g.set(
         "GetMapOverlayInfo",
         lua.create_function(|lua, i: i64| {
diff --git a/crates/benilla-ui/src/script/worldmap_arrow.rs b/crates/benilla-ui/src/script/worldmap_arrow.rs
index 5248b760..9141c321 100644
--- a/crates/benilla-ui/src/script/worldmap_arrow.rs
+++ b/crates/benilla-ui/src/script/worldmap_arrow.rs
@@ -1,21 +1,7 @@
-//! The world map's **arrow frames** (decision 1980, `0x4a8bb0`): the seven bindings the stock
-//! `WorldMapFrame.lua` and `Blizzard_BattlefieldMinimap.lua` call to put the player's arrow on
-//! the map.
-//!
-//! The reference keeps **two singletons per UI session** — the world map's and the battlefield
-//! minimap's — each a stock `Model` widget (the same class `CreateFrame("Model")` makes) born as a
-//! child of the frame the first `Create…` was given, loaded with `Interface\Minimap\MinimapArrow.mdx`,
-//! shown, and never freed: every later `Create…` is a no-op even with a different parent. Its
-//! rect is the model's bounding box (no authored size), its model is re-centred on that rect by
-//! every `Update…`, and its facing is the camera-tracked object's — the player's. `Position…` is
-//! literally `arrow:SetPoint(...)` with the generic binder's three error strings and two silent
-//! legs; `Show…` is `arrow:Show()`/`Hide()` under the never-raising boolean coercion.
-//!
-//! Here the singleton is an anonymous `Model` frame this module creates through the same factory
-//! `CreateFrame` uses, sized to the arrow's byte-measured footprint, and the app draws it: a
-//! `Model` frame whose file is the minimap arrow extracts as [`QuadContent::ModelPane`] with the
-//! path and the facing, and the app's model-pane arm paints the arrow sprite there
-//! (`ui_script/extract`).
+//! The world map's arrow frames (`0x4a8bb0`), the seven bindings `WorldMapFrame.lua` and
+//! `Blizzard_BattlefieldMinimap.lua` call. The reference keeps two singletons per UI session, the
+//! world map's and the battlefield minimap's: stock `Model` frames made by the first `Create`,
+//! never freed, their rect the arrow file's bounding box and their facing the player's.
 
 use mlua::{Lua, MultiValue, ObjectLike, Table, Value};
 
@@ -23,15 +9,11 @@ use super::binding_abi::bool_or_default;
 use super::object::{create_frame, decode_id, frame_handle_of, frame_wrapper, point_from_str};
 use super::Model;
 
-/// The arrow's model — `0x8453c0`, and NOT `Rotating-MinimapArrow`.
+/// The arrow's model (`0x8453c0`), not `Rotating-MinimapArrow`.
 pub const ARROW_MODEL: &str = "Interface\\Minimap\\MinimapArrow.mdx";
 
-/// The arrow's rect is the file's own bounding box — the implicit rect of a size-less pane
-/// (decision 2015; `MinimapArrow.mdx`'s `0.0262 × 0.0263` model units read as layout units,
-/// `1280·extent = 33.5 × 33.7` FrameXML units at 4:3). The world-map arrow's model scale is
-/// `G48 · 5/3` (`= 1.0` at 4:3, `G48 = 1/√(aspect² + 1)`) and the mini's `G48 · 10/9`, so the
-/// quad holds a constant apparent size as the window's shape changes while its rect grows with
-/// `√(a²+1)` (`0x4a7ad8`).
+/// Half the file's bounding box, which is the size-less pane's rect in layout units (33.5 x 33.7
+/// FrameXML units at 4:3); `0x4a7b20` centres the model there.
 fn centre_of(facts: Option<&crate::widget::ModelFileFacts>) -> (f32, f32, f32) {
     facts.map_or((0.0, 0.0, 0.0), |f| {
         let (x, y) = f.extent();
@@ -59,7 +41,8 @@ impl Arrow {
             Arrow::Mini => model.worldmap.arrow_mini = Some(id),
         }
     }
-    /// The model-scale numerator: `5/3` for the world map's arrow, `10/9` for the mini's.
+    /// The model scale over `G48`: `5/3` for the world map, `10/9` for the mini, so the arrow keeps
+    /// its apparent size as the window's shape changes (`0x4a7ad8`).
     fn scale_over_g48(self) -> f32 {
         match self {
             Arrow::World => 5.0 / 3.0,
@@ -96,15 +79,15 @@ impl Arrow {
     }
 }
 
-/// `[0x832a48]` — the Y half-extent of the reference's layout space, `1/√(A² + 1)` for the
-/// screen's aspect `A`; `0.6` at 4:3.
+/// `G48` (`0x832a48`), the Y half-extent of the reference's layout space: `1/√(A² + 1)` for the
+/// screen's aspect `A`, 0.6 at 4:3.
 fn g48(model: &Model) -> f32 {
     let (w, h) = (model.screen.width(), model.screen.height());
     let a = if h > 0.0 { w / h } else { 4.0 / 3.0 };
     1.0 / (a * a + 1.0).sqrt()
 }
 
-/// The arrow's model scale for this screen, and the footprint that scale gives it.
+/// The arrow's model scale for this screen.
 fn arrow_scale(model: &Model, which: Arrow) -> f32 {
     g48(model) * which.scale_over_g48()
 }
@@ -153,13 +136,8 @@ fn create(lua: &Lua, which: Arrow, parent: Value) -> mlua::Result<()> {
         let model = lua.app_data_ref::<Model>().expect("model app_data");
         arrow_scale(&model, which)
     };
-    // `SetModel("Interface\Minimap\MinimapArrow.mdx")` in C++ (`0x4a7a80` → `0x76c8e0`): the
-    // same file set every pane takes, seeded with the file's facts when the host has them
-    // (decision 2007 — the arrow's Stand loops its 3.333 s with no bone keyed, so nothing
-    // moves; the arm is the reference's, not a look). No authored size: the widget's rect is
-    // the file's bounding box (decision 2015), and `0x4a7b20`'s `SetPosition(½·GetWidth,
-    // ½·GetHeight, 0)` — the geometry override's bbox extent, in layout units — centres the
-    // model on it.
+    // The reference's `SetModel` (`0x4a7a80` calls `0x76c8e0`) with no authored size: the rect is
+    // the file's bounding box, and `0x4a7b20` centres the model on it.
     let facts = lua
         .app_data_mut::<Model>()
         .expect("model app_data")
@@ -176,7 +154,6 @@ fn create(lua: &Lua, which: Arrow, parent: Value) -> mlua::Result<()> {
     Ok(())
 }
 
-/// The singleton's wrapper, or `None` while it does not exist.
 fn arrow_wrapper(lua: &Lua, which: Arrow) -> mlua::Result<Option<Table>> {
     let id = {
         let model = lua.app_data_ref::<Model>().expect("model app_data");
@@ -185,10 +162,8 @@ fn arrow_wrapper(lua: &Lua, which: Arrow) -> mlua::Result<Option<Table>> {
     id.map(|id| frame_wrapper(lua, id)).transpose()
 }
 
-/// `UpdateWorldMapArrowFrames()` (`0x4a8d10`/`0x4a7c20`): for each existing arrow, re-centre the
-/// model on its rect and copy the camera-tracked object's facing — the player's, which the app
-/// pushes with the world-map feed — into its rotation about +Z. No player → neither facing
-/// moves.
+/// `UpdateWorldMapArrowFrames()` (`0x4a8d10`, `0x4a7c20`): re-centre each arrow and copy the
+/// camera-tracked object's facing, the player's; with no player the facing stays.
 fn update(lua: &Lua) -> mlua::Result<()> {
     for which in [Arrow::World, Arrow::Mini] {
         let Some(wrapper) = arrow_wrapper(lua, which)? else {
@@ -212,13 +187,9 @@ fn update(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// `Position…("point", "frame" [, relativePoint] [, offsetX, offsetY])` (`0x4a8d20`/`0x4a8f20`):
-/// silent with no arrow; args 1 and 2 must be strings (a number is one) else the usage raise;
-/// the point through the same table `SetPoint` reads, else `Unknown frame point`; the frame by
-/// name — `$parent` expanded against the arrow's parent, then `_G` — else `Couldn't find frame
-/// named '%s'`, and the arrow itself `Error: %s is anchored to itself`; a non-string third
-/// argument means `relativePoint = point` and zero offsets with no error; offsets only when both
-/// are numbers.
+/// `Position...("point", "frame" [, relativePoint] [, offsetX, offsetY])` (`0x4a8d20`,
+/// `0x4a8f20`): `SetPoint` on the arrow, silent with no arrow. A non-string third argument means
+/// the same point and zero offsets, with no error; offsets apply only when both are numbers.
 fn position(lua: &Lua, which: Arrow, args: [Value; 5]) -> mlua::Result<()> {
     let Some(arrow) = arrow_wrapper(lua, which)? else {
         return Ok(());
@@ -233,7 +204,9 @@ fn position(lua: &Lua, which: Arrow, args: [Value; 5]) -> mlua::Result<()> {
     }
     let frame_name = as_string(&frame)?;
     let resolved = if let Some(rest) = frame_name.strip_prefix("$parent") {
-        // The first NAMED ancestor of the arrow — its parent frame, or that frame's own parent.
+        // The reference (`0x76c5b0`) matches `$parent` in any case and takes the first named
+        // ancestor's name, else "Top"; here the prefix matches as spelled and only the direct
+        // parent's name is tried.
         let parent_name: Option<String> = arrow
             .call_method::<Option<Table>>("GetParent", ())?
             .and_then(|p| {
@@ -279,15 +252,14 @@ fn position(lua: &Lua, which: Arrow, args: [Value; 5]) -> mlua::Result<()> {
     )
 }
 
-/// `Show…([shown])` (`0x4a9120`/`0x4a9170`): silent with no arrow; the never-raising boolean
-/// coercion with a default of true (absent → show, `nil` → hide).
+/// `Show...([shown])` (`0x4a9120`, `0x4a9170`): silent with no arrow; the never-raising boolean
+/// coercion, true by default.
 fn show(lua: &Lua, which: Arrow, args: MultiValue) -> mlua::Result<()> {
     let Some(arrow) = arrow_wrapper(lua, which)? else {
         return Ok(());
     };
-    // An ABSENT argument is not nil at the C API (`LUA_TNONE`, which the binding's nil test does
-    // not match), so the bare call shows; an explicit nil hides; anything else is the boolean
-    // coercion with its true default.
+    // An absent argument is `LUA_TNONE`, which the binding's nil test does not match, so a bare
+    // call shows and an explicit nil hides.
     let on = match args.front() {
         None => true,
         Some(Value::Nil) => false,
@@ -341,8 +313,8 @@ mod tests {
     use super::*;
     use crate::script::UiScript;
 
-    /// The arrow file's facts, as the host hands them over (2007/2015): the header box the
-    /// implicit rect and the re-centring read.
+    /// The arrow file's facts as the host hands them over: the header box the rect and the
+    /// centring read.
     fn arrow_facts(s: &mut UiScript) {
         s.set_model_facts(
             ARROW_MODEL,
@@ -370,8 +342,6 @@ mod tests {
         s
     }
 
-    /// The three raise strings, then the singleton: an anonymous Model child of the parent,
-    /// loaded with the arrow, born shown, sized to its footprint; a second create a no-op.
     #[test]
     fn create_validates_its_parent_and_makes_one_arrow_per_session() {
         let mut s = vm();
@@ -413,11 +383,9 @@ mod tests {
         assert_eq!(kind, "Model");
         assert!(shown, "born shown");
         assert_eq!(w, 0.0, "no authored size, no facts yet: no rect");
-        // The file lands: the rect is its box in layout units — 0.0262 × 1280 at 4:3 — and the
-        // model is centred on it (`0x4a7b20`, half the box, in layout units).
+        // The rect is the box in layout units, 0.0262 x 1280 at 4:3, with the model centred on it.
         arrow_facts(&mut s);
-        // The C++ re-centres on create and on every `UpdateWorldMapArrowFrames` (`0x4a7b20`);
-        // a file that lands after the create is picked up by the next update.
+        // Facts that land after the create are picked up by the next update, which re-centres.
         s.run("UpdateWorldMapArrowFrames()").unwrap();
         s.resolve();
         let w: f32 = s.eval("return ({WM:GetChildren()})[2]:GetWidth()").unwrap();
@@ -442,8 +410,6 @@ mod tests {
         );
     }
 
-    /// `Position…` anchors the arrow like SetPoint, with the reference's three strings and its
-    /// two silent legs; `Show…` follows the boolean coercion; `Update…` copies the facing.
     #[test]
     fn position_show_and_update_drive_the_arrow() {
         let mut s = vm();
@@ -488,7 +454,7 @@ mod tests {
             (cx - (dl + 100.0)).abs() < 0.01 && (cy - (dt - 50.0)).abs() < 0.01,
             "{cx} {cy}"
         );
-        // A non-string third argument: relativePoint = point, offsets ignored, no error.
+        // A non-string third argument: the same point, offsets ignored, no error.
         s.run("PositionWorldMapArrowFrame('TOPLEFT', 'WorldMapDetailFrame', nil, 100, -50)")
             .unwrap();
         s.resolve();
diff --git a/crates/benilla-ui/src/script/worldstate.rs b/crates/benilla-ui/src/script/worldstate.rs
index 628b459e..7c06445d 100644
--- a/crates/benilla-ui/src/script/worldstate.rs
+++ b/crates/benilla-ui/src/script/worldstate.rs
@@ -1,44 +1,27 @@
-//! The world-state UI seam — `GetNumWorldStateUI` / `GetWorldStateUIInfo`, the two bindings behind
-//! the always-up PvP readout (`WorldStateFrame`; decision 1586).
-//!
-//! The list is built app-side ([`crate::world_state_ui`](benilla_app)) because every one of its
-//! gates reads app state — the last init's `(map, area)` scope, the joined chat channels, the live
-//! world-state table — and pushed here as already-resolved rows. That is the same split every
-//! other feed uses; what the reference keeps in a process global (`0xb71e7c`, an array of DBC row
-//! ids re-walked on demand) we keep as the resolved answer.
-//!
-//! **Return shape** at `0x4c5a70`.
-//! Worth stating what it is *not*: this is a **ten**-value return, and it carries **no `uiType` and
-//! no `hidden`** — those are a later expansion of the API, and a client that answered twelve values
-//! here would hand `WorldStateFrame` its icon path where it expects a number.
+//! `GetNumWorldStateUI` and `GetWorldStateUIInfo`, behind the always-up PvP readout, over rows the
+//! app resolves; the reference re-walks an array of DBC row ids (`0xb71e7c`) on demand. The info
+//! is ten values (`0x4c5a70`), with no `uiType` or `hidden`, which came later.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// One row of the always-up world-state readout — the ten values `GetWorldStateUIInfo` returns,
-/// in its order.
+/// One row of the readout: the ten values `GetWorldStateUIInfo` returns, in order.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct WorldStateUiView {
-    /// `uiState` — the row's `StateVariable` world state resolved through the table, or **`1`**
-    /// when it carries none (`0x4c5ad8`: the miss is a literal `1.0`, not `0`, so a row without a
-    /// state reads as "on" rather than "off").
+    /// `uiState`: the row's `StateVariable` world state, or 1 (on) when it has none (`0x4c5ad8`).
     pub ui_state: i32,
-    /// The label, already macro-expanded (`"Towers Controlled: 3"`). The **only** expanded string
-    /// of the ten.
+    /// The label, macro-expanded, the only expanded string of the ten.
     pub text: String,
     /// The static icon's texture path, or `""`.
     pub icon: String,
-    /// The icon that replaces it while the row's state is live (Warsong Gulch's enemy flag), or
-    /// `""`.
+    /// The icon that replaces it while the state is live (Warsong Gulch's enemy flag), or `""`.
     pub dynamic_icon: String,
     pub tooltip: String,
     pub dynamic_tooltip: String,
-    /// A token naming an extra widget the row drives — `"CAPTUREPOINT"` on the one row that has
-    /// one — or `""`.
+    /// The extra widget the row drives, `"CAPTUREPOINT"` on the one row that has one, or `""`.
     pub extended_ui: String,
-    /// That widget's three world states, **resolved to values** (the DBC holds ids; the binding
-    /// answers what they read).
+    /// That widget's three world states, resolved to values; the DBC holds ids.
     pub extended_ui_state: [i32; 3],
 }
 
@@ -48,19 +31,10 @@ pub(crate) struct WorldStateUiState {
 }
 
 impl super::UiScript {
-    /// Push the always-up world-state readout's rows (see
-    /// [`WorldStateUiView`](WorldStateUiView)). On change, queues
-    /// **`UPDATE_WORLD_STATES`** — event `0x20e`, the reference's own name for it.
-    ///
-    /// **Named divergence, in the *trigger*, not the shape.** The reference fires that event from
-    /// exactly two sites (`0x48fa12`, after an init rebuilds the list; `0x49bdd6`, when the
-    /// zone-defense channel membership flips) and, verified by a whole-`.text` scan for the id,
-    /// nowhere else — so a plain `SMSG_UPDATE_WORLD_STATE` changing a tower count fires nothing.
-    /// It can afford that because its Lua re-reads live values off the table at whatever moment it
-    /// repaints; we push resolved values, so a silent value change would simply never reach the
-    /// frame. We therefore fire on any change to what the readout would *display*, which is the
-    /// reference's two triggers plus the value updates its own frame must already be reacting to
-    /// by some means the binary does not show.
+    /// Push the readout's rows, queuing `UPDATE_WORLD_STATES` (event `0x20e`) on any change.
+    /// Deviation: the reference fires it only after an init rebuild (`0x48fa12`) or a zone-defense
+    /// channel flip (`0x49bdd6`); we fire on a value change too, because our rows are resolved
+    /// values its Lua would re-read live.
     pub fn set_world_state_ui(&mut self, rows: Vec<WorldStateUiView>) {
         let mut model = self.model_mut();
         if model.worldstate.rows != rows {
@@ -75,8 +49,7 @@ impl super::UiScript {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetNumWorldStateUI() — how many always-up rows the current scope admits (`0x4c5a40`: pushes
-    // the count, no validation, always one return).
+    // `0x4c5a40`: the count, no validation, always one return.
     g.set(
         "GetNumWorldStateUI",
         lua.create_function(|lua, ()| {
@@ -85,28 +58,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetWorldStateUIInfo(index) — the i-th (1-based) row, ten values (`0x4c5a70`).
-    //
-    // Two legs of the reference's behaviour are easy to get wrong and are reproduced here:
-    //
-    // - a **non-number** argument RAISES `"Usage: GetWorldStateUIInfo(index)"`. The binding's
-    //   `luaL_error` leg looks like it returns — its callee has a `ret` — but that `ret` is an
-    //   MSVC epilogue, and closing the range two levels down (`luaG_errormsg`, then `luaD_throw`,
-    //   neither of which contains a single `ret`) proves the longjmp. So this is an error, not a
-    //   quiet nil.
-    // - an **out-of-range** index returns exactly ONE value, the number `0` — not nil, and not a
-    //   run of ten nils (`0x4c5be5`). The index falls through a row-id substitution of `0`, whose
-    //   id-index slot is NULL, and lands on that shared bail.
-    //
-    // No string return is ever nil: an empty DBC column resolves to the string block's leading
-    // NUL, so Lua gets `""`. The `__ftol` on the index truncates toward zero.
+    // A non-number raises (the `luaL_error` longjmps), an out-of-range index answers the single
+    // number 0 (`0x4c5be5`), and no string is ever nil: an empty DBC column reads `""`.
     g.set(
         "GetWorldStateUIInfo",
         lua.create_function(|lua, index: Value| {
             let index = match index {
                 Value::Integer(i) => i as f64,
                 Value::Number(n) => n,
-                // The reference accepts a numeric STRING too — `lua_isnumber` coerces.
+                // A numeric string too, as `lua_isnumber` coerces.
                 Value::String(ref s) => match s.to_str().ok().and_then(|s| s.trim().parse().ok()) {
                     Some(n) => n,
                     None => return Err(mlua::Error::runtime("Usage: GetWorldStateUIInfo(index)")),
@@ -115,7 +75,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             };
             let row = {
                 let model = lua.app_data_ref::<Model>().expect("model app_data");
-                // Truncate toward zero, then 1-based.
+                // Truncated toward zero by `__ftol`, then 1-based.
                 usize::try_from(index.trunc() as i64)
                     .ok()
                     .and_then(|i| i.checked_sub(1))
diff --git a/crates/benilla-ui/src/script/worn_display.rs b/crates/benilla-ui/src/script/worn_display.rs
index 6565d124..071a0af8 100644
--- a/crates/benilla-ui/src/script/worn_display.rs
+++ b/crates/benilla-ui/src/script/worn_display.rs
@@ -1,81 +1,52 @@
-//! The **equipment-display** API surface — `ShowHelm`/`ShowingHelm`, `ShowCloak`/`ShowingCloak`
-//! (decision 1472): the player's two "don't draw this piece of my gear" preferences.
-//!
-//! Two bits, and they are not the UI's to keep. The preference lives server-side in the character's
-//! own `PLAYER_FLAGS` (`HIDE_HELM 0x400` / `HIDE_CLOAK 0x800`), which is a **public** descriptor
-//! field — so it dresses our body on every client that can see us, and every other player's on
-//! ours. That is why there is no CVar and no saved variable behind this row: the wire flag is the
-//! single source of truth, it is per-character rather than per-install, and it is already persisted
-//! by whoever we are logged into.
-//!
-//! **The setter is a set; the wire verb is a flip.** `CMSG_TOGGLE_HELM`/`CMSG_TOGGLE_CLOAK` carry no
-//! body and have no target-state form at all (vmangos `HandleShowingHelmOpcode` is a bare
-//! `ToggleFlag`), so `ShowHelm(v)` compares `v` against what we currently believe and queues a flip
-//! only on a difference. The belief is updated **optimistically at the call** and overwritten only
-//! when the *wire* bit actually moves ([`super::UiScript::set_worn_display`], pushed on the
-//! descriptor edge and not per frame) — without that, the value would snap back to the stale
-//! descriptor for the length of the round trip and a second click inside that window would compute
-//! the wrong flip.
-//!
-//! The 1.12 panel calls the setter with the **strings** `"1"` / `"0"` (`UIOptionsFrame_Save`
-//! l.286-297, `value.setFunc(value.value)`), so the argument is read *numerically* — plain Lua
-//! truthiness would make `"0"` mean "show" and the reference's own Options panel could never turn
-//! a helm off. See [`shown_arg`].
+//! `ShowHelm`/`ShowingHelm` and `ShowCloak`/`ShowingCloak`, over the `PLAYER_FLAGS` bits
+//! `HIDE_HELM` (`0x400`) and `HIDE_CLOAK` (`0x800`), which the server keeps per character, so no
+//! CVar backs them. The wire verbs are bodiless flips (vmangos `HandleShowingHelmOpcode` is a bare
+//! `ToggleFlag`), so a set queues a flip only when it differs from a belief that moves at the call
+//! and is overwritten when the wire bit moves.
 
 use mlua::{Lua, Value};
 
 use super::Model;
 
-/// Which of the two worn-display preferences a queued flip is for. One entry per
-/// `CMSG_TOGGLE_HELM`/`CMSG_TOGGLE_CLOAK` the app should send.
+/// A queued flip: one `CMSG_TOGGLE_HELM` or `CMSG_TOGGLE_CLOAK` for the app to send.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum WornDisplay {
-    /// The head slot — `PLAYER_FLAGS_HIDE_HELM`.
+    /// The head slot, `PLAYER_FLAGS_HIDE_HELM`.
     Helm,
-    /// The back slot — `PLAYER_FLAGS_HIDE_CLOAK`.
+    /// The back slot, `PLAYER_FLAGS_HIDE_CLOAK`.
     Cloak,
 }
 
 impl super::UiScript {
-    /// Drain the worn-display flips queued since the last call — one `CMSG_TOGGLE_HELM` /
-    /// `CMSG_TOGGLE_CLOAK` each. A list rather than a count because the two slots are distinct
-    /// packets; within one slot, two flips in a frame are two sends, exactly like the PvP toggle.
+    /// Drain the queued flips, one packet each; two flips of one slot in a frame are two sends.
     pub fn take_worn_display_toggles(&mut self) -> Vec<WornDisplay> {
         std::mem::take(&mut self.model_mut().worn_display_toggles)
     }
 
-    /// Push the wire truth for both preferences — the app calls this **on a `PLAYER_FLAGS` edge**,
-    /// never per frame, so an optimistic flip made by [`install`]'s setters survives until the
-    /// server's answer actually arrives (see the module doc).
+    /// Push the wire truth, only on a `PLAYER_FLAGS` edge: pushed per frame, it would undo an
+    /// optimistic flip before the server answers, and a second click would flip the wrong way.
     pub fn set_worn_display(&mut self, helm_shown: bool, cloak_shown: bool) {
         let mut model = self.model_mut();
         model.helm_shown = helm_shown;
         model.cloak_shown = cloak_shown;
     }
 
-    /// What the VM currently believes — the app's own read, for the drain's compare and for tests.
+    /// What the VM currently believes, `(helm_shown, cloak_shown)`.
     pub fn worn_display(&self) -> (bool, bool) {
         let model = self.model_ref();
         (model.helm_shown, model.cloak_shown)
     }
 }
 
-/// The setter's argument convention: **numeric**, not Lua-truthy. `nil`/`false`/`0`/`"0"` read as
-/// "hide"; `true`, any non-zero number and any non-numeric string read as "show".
-///
-/// The distinction is load-bearing rather than pedantic. 1.12's own Interface panel hands this
-/// binding the *string* `"0"` to mean off (`UIOptionsFrame_Save`), and in Lua 5.0 `"0"` is truthy —
-/// so a plain `lua_toboolean` reading would make the reference's own Show Helm checkbox a one-way
-/// switch. Numeric-string coercion is what makes it work, and it is the same shape
-/// [`super::action::truthy_nonzero`] already carries for `UseAction`'s `checkCursor`.
+/// Numeric, not Lua-truthy: the stock panel passes the string `"0"` for off
+/// (`UIOptionsFrame_Save`), which Lua 5.0 holds truthy. Nil, false, 0 and `"0"` hide.
 fn shown_arg(v: &Value) -> bool {
     match v {
         Value::Nil => false,
         Value::Boolean(b) => *b,
         Value::Integer(i) => *i != 0,
         Value::Number(n) => *n != 0.0,
-        // A numeric string coerces like Lua's own arithmetic does; a non-numeric one is not a
-        // value this API is ever handed, and reads as "show" rather than silently hiding gear.
+        // A non-numeric string is never handed to this API; it shows rather than hiding gear.
         Value::String(s) => s
             .to_str()
             .ok()
@@ -94,11 +65,10 @@ fn want(model: &mut Model, which: WornDisplay, show: bool) {
     if *held == show {
         return;
     }
-    *held = show; // optimistic — the wire edge overwrites it when the server answers
+    *held = show; // optimistic: the wire edge overwrites it when the server answers
     model.worn_display_toggles.push(which);
 }
 
-/// Register the equipment-display globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
@@ -116,8 +86,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // The getters the Options row reads its checked state from — `1`/`nil`, the 1.12 boolean
-    // return the panel feeds straight into `SetChecked`.
+    // `1` or nil, which the Options row feeds straight into `SetChecked`.
     for (name, which) in [
         ("ShowingHelm", WornDisplay::Helm),
         ("ShowingCloak", WornDisplay::Cloak),
@@ -142,10 +111,6 @@ mod tests {
     use super::WornDisplay;
     use crate::script::UiScript;
 
-    /// The argument convention, and the one that would silently break the feature: 1.12's own
-    /// Options panel calls the setter with the **string** `"0"` to mean "hide", and in Lua 5.0 that
-    /// string is truthy. A plain truthiness reading would make Show Helm a one-way switch — on
-    /// forever, off never — with no error anywhere to say so.
     #[test]
     fn the_setter_reads_its_argument_numerically_so_the_string_zero_hides() {
         let mut s = UiScript::new().unwrap();
@@ -175,9 +140,8 @@ mod tests {
         );
     }
 
-    /// The wire verb is a blind flip, so **asking for the state we are already in must send
-    /// nothing** — otherwise the Options window's Defaults button, which writes every row on the
-    /// page unconditionally, would invert whichever preference was already at its default.
+    /// The Options window's Defaults button writes every row, so a flip on no difference would
+    /// invert a preference already at its default.
     #[test]
     fn asking_for_the_state_we_are_already_in_sends_nothing() {
         let mut s = UiScript::new().unwrap();
@@ -196,8 +160,6 @@ mod tests {
         );
     }
 
-    /// The descriptor is the truth: a wire push overrides whatever the VM believed. This is the
-    /// edge the app feeds — it is why the app pushes on a `PLAYER_FLAGS` CHANGE and not per frame.
     #[test]
     fn the_wire_push_overrides_the_optimistic_belief() {
         let mut s = UiScript::new().unwrap();
@@ -205,8 +167,7 @@ mod tests {
         let _ = s.take_worn_display_toggles();
         assert_eq!(s.worn_display(), (false, true));
 
-        // The server answers something else entirely (another client toggled it, or our flip
-        // crossed a login) — the descriptor wins, and the next ask is computed from it.
+        // The server answers otherwise; the descriptor wins and the next ask is computed from it.
         s.set_worn_display(true, false);
         assert_eq!(s.worn_display(), (true, false));
         s.run("ShowHelm(0)").unwrap();
diff --git a/crates/benilla-ui/src/source.rs b/crates/benilla-ui/src/source.rs
index aa7ae4aa..2c0b5f51 100644
--- a/crates/benilla-ui/src/source.rs
+++ b/crates/benilla-ui/src/source.rs
@@ -1,85 +1,29 @@
-//! **UI source bytes** — what a `.lua`, `.xml` or `.toc` file *is*, before any parser sees it.
-//!
-//! One rule, and it is the reference's: **a UI source file is bytes, not text.** `0x704bc0` slurps
-//! the file (`0x648620`) with `pad = 0`, so there is not even a trailing NUL, the handle is opened
-//! **binary** on every leg of `0x647db0`, and `0x704ae0` hands the pointer and length straight to
-//! `luaL_loadbuffer 0x6f5690`. No transcoding, no codepage conversion; the only
-//! `WideCharToMultiByte` on the path converts the *path*. Lua 5.0 strings *are* byte strings, so a
-//! cp1252 German locale file loads there and its literals carry the raw bytes.
-//!
-//! Two things the compiler's front door does do, and we do them too because they are the
-//! reference's own code rather than Lua's: it **strips a UTF-8 BOM** ([`strip_bom`] — ten
-//! instructions Blizzard patched into `luaL_loadbuffer`) and it **eats a leading `#`-line**
-//! ([`strip_hashbang`] — Lua 5.0 puts that in `luaX_setinput`, where every chunk passes; 5.1 moved
-//! it somewhere mlua never calls).
-//!
-//! benilla read every one of these files with `read_to_string` until decision 1193, which meant a
-//! file that was not valid UTF-8 did not merely lose a glyph — it **did not exist**: the read
-//! returned `None` and the loader reported "not found". Measured over a real 218-addon vanilla
-//! corpus, that is **80 addons of 218** (37 %): 76 non-UTF-8 `.lua` files, 5 non-UTF-8 `.toc`
-//! files (which made those addons invisible to discovery entirely), and 160 files carrying a UTF-8
-//! BOM. `AceAddon-2.0.lua` is one of them, and it is embedded in ~30 addons — one library file
-//! taking out the whole Ace/FuBar half of the ecosystem.
-//!
-//! ## Two verbs, because there are two kinds of consumer
-//!
-//! - [`strip_bom`] + raw bytes → **Lua chunks**. Byte-transparent, exactly as the reference.
-//!   `string.len()` on a literal returns what it returns there, and byte-indexing agrees.
-//! - [`decode`] → **our own parsers** (FrameXML XML, `.toc`), which need `&str` because Rust
-//!   parsers do. This is the only place a guess is made, and it is made where it is cheapest.
-//!
-//! **Why not transcode the Lua too, so everything downstream is UTF-8?** Because that would
-//! silently change `string.len`, `string.sub` and `string.byte` on every non-ASCII literal — a
-//! divergence from the verified mechanism, bought for a rendering convenience. The right place to
-//! turn bytes into text is the boundary that actually requires text, which is a Rust binding
-//! signature, not the file loader. A stray byte should cost one glyph, not the file.
+//! UI source files are bytes, not text. The reference reads a Lua file whole and binary
+//! (`0x704bc0` via `0x648620`, no trailing NUL; binary on every leg of `0x647db0`), and
+//! `0x704ae0` hands it untranscoded to `luaL_loadbuffer 0x6f5690`, so a cp1252 file's literals
+//! keep their raw bytes. [`chunk`] prepares a Lua chunk byte for byte; [`decode`] gives our own
+//! `.xml` and `.toc` parsers the `&str` they need. Transcoding Lua instead would change
+//! `string.len`, `string.sub` and `string.byte` on every non-ASCII literal.
 
 use std::borrow::Cow;
 
-/// The UTF-8 byte-order mark. Not an encoding — a three-byte signature some Windows editors write
-/// in front of a UTF-8 file.
 const BOM: &[u8] = &[0xEF, 0xBB, 0xBF];
 
-/// `bytes` without a leading UTF-8 BOM.
-///
-/// **This is fidelity, not a modernisation** — and that is a correction to this module's first
-/// draft, which reasoned that stock Lua 5.0's lexer meets `0xEF` and stops, so a BOM'd file must
-/// have failed on the real client too, so stripping it was us being kinder than the original.
-/// Reading the disassembly instead of the manual shows it: **Blizzard patched the strip into
-/// `luaL_loadbuffer 0x6f5690` themselves.** Ten instructions stock Lua does not have
-/// (`0x6f5699`–`0x6f56b4`): a `size >= 3` guard, three byte compares against `EF BB BF`, then `add
-/// edx,3` / `sub eax,3` — all before the `LoadS` fill and `lua_load 0x6f4320`. That is the only
-/// live door into the compiler, so addon files, FrameXML, XML script bodies and `loadstring` all
-/// get it. The `.toc` reader has its own separate skip at `0x6edc71`.
-///
-/// The lexer reasoning was right and the conclusion drawn from it was wrong: `luaX_lex 0x6ff610`
-/// *would* reject `0xEF`, which is precisely why the patch has to exist. A verified mechanism
-/// beats a correct-sounding derivation, every time.
-///
-/// The edge semantics are the reference's, byte for byte: **at most one** mark, **only** at offset
-/// 0, and a file shorter than three bytes is untouched (a BOM-only file compiles as an empty
-/// chunk). A UTF-16 BOM (`FF FE` / `FE FF`) is left alone — the reference does not handle one
-/// either, that file is not a Lua chunk in any encoding it could run, and transcoding it would be
-/// inventing content rather than reading it. None exists in the corpus.
+/// `bytes` without a leading UTF-8 BOM, a strip the reference added to its
+/// `luaL_loadbuffer 0x6f5690` (`0x6f5699`–`0x6f56b4`), so every chunk gets it, `loadstring`
+/// included; the `.toc` reader has its own at `0x6edc71`. At most one mark, only at offset 0; a
+/// UTF-16 mark is left alone, as the reference leaves it.
 pub fn strip_bom(bytes: &[u8]) -> &[u8] {
     bytes.strip_prefix(BOM).unwrap_or(bytes)
 }
 
-/// `bytes` with a leading `#`-line removed — the **hash-bang skip**, which is a dialect difference
-/// and not a convenience.
-///
-/// Lua 5.0 puts this skip in `luaX_setinput` (`0x6ff5cd`–`0x6ff600`), which every chunk goes
-/// through: a source file whose first character is `#` loses its whole first line, including one
-/// handed to `loadstring`. **Lua 5.1 moved it out** into `luaL_loadfile`, which mlua's
-/// `Lua::load` does not call — so a 5.1-family VM silently keeps the line and then fails to
-/// compile it.
-///
-/// Applied after the BOM strip, because that is the order the reference applies them in: the mark
-/// is removed inside `luaL_loadbuffer`, and the lexer sees the shortened buffer.
+/// `bytes` without a leading `#` line: Lua 5.0 skips it for every chunk in `luaX_setinput`
+/// (`0x6ff5cd`–`0x6ff600`), while 5.1 moved the skip to `luaL_loadfile`, which mlua's
+/// `Lua::load` never calls. Runs after the BOM strip, the reference's order.
 pub fn strip_hashbang(bytes: &[u8]) -> &[u8] {
     match bytes.first() {
         Some(b'#') => match bytes.iter().position(|&b| b == b'\n') {
-            // Lua 5.0 leaves the newline for the line counter; so do we.
+            // Lua 5.0 keeps the newline for the line counter.
             Some(nl) => &bytes[nl..],
             None => &bytes[bytes.len()..],
         },
@@ -92,19 +36,9 @@ pub fn chunk(bytes: &[u8]) -> &[u8] {
     strip_hashbang(strip_bom(bytes))
 }
 
-/// Interpret UI source bytes as text, for the parsers that cannot take bytes.
-///
-/// Valid UTF-8 passes through **borrowed and unchanged** — which is every file we ship and the
-/// overwhelming majority of every corpus, so the guess below is never reached for them.
-///
-/// Otherwise the bytes are decoded as **cp1252** (Windows-1252). That is a guess, and it is the
-/// right one to make: the vanilla-era addons that are not UTF-8 are Western-European locale files
-/// written on a Windows box — German and French `## Notes:` lines and `<Include>`d localisation
-/// documents. cp1252 maps every byte (the five undefined slots become U+FFFD), so the decode
-/// cannot fail and the addon cannot vanish. A GBK or EUC-KR file decodes to mojibake instead of
-/// disappearing, which is a strictly better failure and one that is visible rather than silent.
-///
-/// The BOM is stripped first, so a BOM'd UTF-8 file is borrowed too.
+/// UI source bytes as text for our parsers: after the BOM, valid UTF-8 is borrowed unchanged and
+/// anything else is read as cp1252, which the non-UTF-8 vanilla addons (Western-European locale
+/// files) are written in; every byte maps, so no file fails to decode.
 pub fn decode(bytes: &[u8]) -> Cow<'_, str> {
     let bytes = strip_bom(bytes);
     match std::str::from_utf8(bytes) {
@@ -113,13 +47,8 @@ pub fn decode(bytes: &[u8]) -> Cow<'_, str> {
     }
 }
 
-/// One cp1252 byte as a `char`.
-///
-/// cp1252 is Latin-1 (where a byte *is* its code point) except for `0x80..=0x9F`, which Latin-1
-/// leaves as C1 control codes and Windows fills with the punctuation people actually type — the
-/// curly quotes, the em dash, the euro sign. Getting that window wrong is what turns a French
-/// addon's `l'objet` into a control character, so the window is spelled out rather than
-/// approximated by a Latin-1 cast.
+/// One cp1252 byte as a `char`: Latin-1, except `0x80..=0x9F`, where Latin-1 has C1 controls and
+/// cp1252 has punctuation (the five undefined slots become U+FFFD).
 fn cp1252(b: u8) -> char {
     const C1: [char; 32] = [
         '\u{20AC}', '\u{FFFD}', '\u{201A}', '\u{0192}', '\u{201E}', '\u{2026}', '\u{2020}',
@@ -138,20 +67,18 @@ fn cp1252(b: u8) -> char {
 mod tests {
     use super::*;
 
-    /// A BOM'd file loses exactly three bytes, and a file without one is untouched.
     #[test]
     fn the_utf8_bom_is_removed_and_nothing_else_is() {
         assert_eq!(strip_bom(b"\xEF\xBB\xBFlocal x = 1"), b"local x = 1");
         assert_eq!(strip_bom(b"local x = 1"), b"local x = 1");
-        // A lone 0xEF is not a BOM, and a truncated one is not either — neither may be eaten.
+        // A truncated mark is not a BOM.
         assert_eq!(strip_bom(b"\xEF\xBB"), b"\xEF\xBB");
         assert_eq!(strip_bom(b"\xEF"), b"\xEF");
         assert_eq!(strip_bom(b""), b"");
-        // A UTF-16 mark is left alone: that file is not a chunk we can honestly run.
+        // A UTF-16 mark is left alone.
         assert_eq!(strip_bom(b"\xFF\xFEl\0"), b"\xFF\xFEl\0");
     }
 
-    /// Valid UTF-8 is borrowed, not rebuilt — the common path allocates nothing.
     #[test]
     fn valid_utf8_is_borrowed_unchanged() {
         let text = "## Title: Sch\u{e4}tze";
@@ -161,44 +88,33 @@ mod tests {
         assert_eq!(decode(&bom), text);
     }
 
-    /// A cp1252 `.toc` line decodes to the glyphs its author typed, rather than to nothing.
-    ///
-    /// `0xE4` is `a`-umlaut in both Latin-1 and cp1252; `0x92` is the right single quote in cp1252
-    /// and a C1 control in Latin-1, which is the difference this table exists for.
+    /// `0xE4` is `ä` in Latin-1 and cp1252 alike; `0x92` is cp1252's right single quote but a C1
+    /// control in Latin-1.
     #[test]
     fn cp1252_is_decoded_where_utf8_fails() {
         assert_eq!(decode(b"## Notes: Sch\xE4tze"), "## Notes: Sch\u{e4}tze");
         assert_eq!(decode(b"l\x92objet"), "l\u{2019}objet");
         assert_eq!(decode(b"\x80"), "\u{20AC}");
-        // Undefined cp1252 slots survive as the replacement char — never as a decode failure.
+        // An undefined cp1252 slot becomes the replacement char.
         assert_eq!(decode(b"\x81"), "\u{FFFD}");
     }
 
-    /// The `#`-line skip is Lua 5.0's, and it is a *dialect* fact rather than a nicety.
-    ///
-    /// `luaX_setinput 0x6ff5cd` eats it for every chunk the reference compiles, including one
-    /// handed to `loadstring`. mlua's 5.1 does not, because 5.1 moved the skip into
-    /// `luaL_loadfile` and `Lua::load` never calls that.
     #[test]
     fn a_leading_hash_line_is_eaten_the_way_lua_5_0_eats_it() {
-        // The newline survives — 5.0 leaves it so the line counter stays honest.
+        // The newline stays, for the line counter.
         assert_eq!(strip_hashbang(b"#!/usr/bin/lua\nreturn 1"), b"\nreturn 1");
-        // A `#` with no newline at all leaves nothing behind.
         assert_eq!(strip_hashbang(b"# only a comment"), b"");
-        // Anything else is untouched — `#t` mid-expression is a length operator, not a shebang.
         assert_eq!(strip_hashbang(b"local n = #t"), b"local n = #t");
         assert_eq!(strip_hashbang(b""), b"");
-        // ...and the two run in the reference's order: mark first, then the line.
+        // The mark goes first, then the line: the reference's order.
         assert_eq!(chunk(b"\xEF\xBB\xBF#line\nreturn 1"), b"\nreturn 1");
     }
 
-    /// The whole point, stated as a property: **no byte sequence makes a source file vanish**.
     #[test]
     fn every_byte_sequence_decodes_to_something() {
         let all: Vec<u8> = (0u8..=255).collect();
         let text = decode(&all);
         assert!(!text.is_empty());
-        // ASCII survives verbatim, which is what a parser actually keys on.
         assert!(text.starts_with('\0'));
         assert!(text.contains("ABC"));
     }
diff --git a/crates/benilla-ui/src/strings.rs b/crates/benilla-ui/src/strings.rs
index c21df352..212f9267 100644
--- a/crates/benilla-ui/src/strings.rs
+++ b/crates/benilla-ui/src/strings.rs
@@ -1,64 +1,19 @@
-//! **One faithful substitution for reference string templates** — the client's `SStrPrintf` face.
-//!
-//! Every user-visible sentence benilla shows comes from `GlobalStrings.lua` or `GlueStrings.lua`
-//! (decision 2045), and most of those carry `%s`/`%d` holes the caller fills. Doing that filling
-//! correctly is not `format!`'s job and never was: the template is *data read at runtime from the
-//! player's install*, so the holes have to be walked, not compiled.
-//!
-//! **Why this module exists.** Before it, the substitution had been reinvented at least eight
-//! times across the workspace, with semantics that did not agree:
-//!
-//! - `ui_instance::fill_template` — ordered, `%%`-aware, starvation-safe, and tested. The best of
-//!   them, and the one this is derived from.
-//! - `ui_duel::winner_line` — a hand-rolled `%1$s`/`%2$s` positional pass, because the duel's
-//!   retreat wording swaps its two names and no ordered filler can express that.
-//! - `ui_action::errors::ui_error_text` — `str::replace`, which fills **every** `%s` with the
-//!   *same* argument. Latent rather than live (no message it currently carries has two), but it
-//!   was a real trap waiting for the first two-argument template to reach that queue.
-//! - `ui_guild::fill`, `ui_petition::fill`, and one-off `replacen` calls in `ui_binder`,
-//!   `ui_trade`, `ui_items::feed` and `equip_error`.
-//!
-//! Eight copies of one primitive is how the `ui_error_text` bug survived: there was no single
-//! place where "how do we fill a reference template" could be got right once.
-//!
-//! **The semantics, and why each is what it is.**
-//!
-//! - `%s` and `%d` consume the next argument, **left to right**. This is `SStrPrintf`'s own order.
-//! - `%N$s` / `%N$d` take argument `N` (1-based) and do **not** move the sequential cursor. 1.12
-//!   uses these exactly where a translation needs to reorder the holes —
-//!   `DUEL_WINNER_RETREAT = "%2$s has fled from %1$s in a duel"` is the canonical case, and it is
-//!   also why hardcoding an English sentence is a localization bug and not merely untidy.
-//! - `%%` collapses to one `%`.
-//! - **A specifier whose argument is missing is copied through literally.** A template we
-//!   mis-modelled should look wrong, not look plausible — `ui_instance` established this and it is
-//!   the right call: a visibly broken line gets reported, a quietly wrong one does not.
-//! - Any other specifier is copied through untouched.
-//!
-//! **`%c` and `%f`/`%g` are here because 1.12's own tables use them**, not for completeness. The
-//! item tooltip's stat and resistance families are spelled with a *character* hole for the sign —
-//! `ITEM_MOD_AGILITY = "%c%d Agility"`, `ITEM_RESIST_SINGLE = "%c%d %s Resistance"` — and its
-//! rate lines with a float one: `DPS_TEMPLATE = "(%.1f damage per second)"`,
-//! `AMMO_DAMAGE_TEMPLATE = "Adds %g damage per second"`. A filler that only knew `%s`/`%d` would
-//! copy those holes through visibly, which is the same as not being able to show the line.
-//!
-//! **The precision is the template's, never the caller's** — `%.1f` is one decimal because
-//! `DPS_TEMPLATE` says so, and a locale that respells it to `%.2f` gets two without a code change.
-//! That is the whole point of reading the template at runtime.
+//! Fills the `%` holes of a `GlobalStrings.lua` or `GlueStrings.lua` template read at runtime, as
+//! the client's `SStrPrintf` does: `%s`, `%d`, `%c`, `%f` and `%g` take the next argument left to
+//! right, `%N$s` takes argument N without moving that cursor (`DUEL_WINNER_RETREAT` reorders its
+//! two names), `%%` is `%`, and the precision is the template's. A hole with no argument, or one
+//! this does not know, is copied through literally so a mis-modelled template shows.
 
 use std::fmt::Write as _;
 
-/// One argument to [`fill`]. Every hole renders every variant — `%s` as text, `%d` as an integer,
-/// `%f`/`%g` as a real — so a caller that groups its arguments differently from the template still
-/// fills in the order the template asks for.
+/// One argument to [`fill`]; any variant renders in any hole, so the template's order decides.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub enum Arg<'a> {
-    /// A string argument — a player name, an item link, a zone. Also what a `%c` hole takes: the
-    /// only `%c` 1.12 spells is the `+`/`-` sign char of the `ITEM_MOD_*`/`ITEM_RESIST_*` family,
-    /// and a one-character string is how a caller says that.
+    /// Text; also what `%c` takes, whose one 1.12 use is the `+`/`-` sign of `ITEM_MOD_*` and
+    /// `ITEM_RESIST_*`.
     S(&'a str),
-    /// A numeric argument.
     D(i64),
-    /// A real argument — the rate lines (`DPS_TEMPLATE`, the `AMMO_*` damage templates).
+    /// A real, for the rate lines (`DPS_TEMPLATE`, the `AMMO_*` damage templates).
     F(f64),
 }
 
@@ -98,7 +53,7 @@ impl From<f64> for Arg<'_> {
 }
 
 impl Arg<'_> {
-    /// `%s` — and `%c`, whose only 1.12 use is a one-character sign string.
+    /// `%s` and `%c`.
     fn as_s(&self, out: &mut String) {
         match self {
             Arg::S(s) => out.push_str(s),
@@ -116,9 +71,7 @@ impl Arg<'_> {
             Arg::D(n) => {
                 let _ = write!(out, "{n}");
             }
-            // A `%d` handed a string is a caller bug, not a display decision; showing the string
-            // is strictly more useful than showing nothing and matches what varargs would do with
-            // a pointer-sized value far better than a zero would.
+            // A string in a `%d` hole is a caller bug; showing it beats showing nothing.
             Arg::S(s) => out.push_str(s),
             // C truncates toward zero here; so does `as`.
             Arg::F(x) => {
@@ -127,7 +80,7 @@ impl Arg<'_> {
         }
     }
 
-    /// `%f` / `%.Nf` — the precision is the template's, defaulting to C's 6.
+    /// `%f`/`%.Nf`, the precision defaulting to C's 6.
     fn as_f(&self, prec: Option<usize>, out: &mut String) {
         let p = prec.unwrap_or(6);
         match self {
@@ -141,21 +94,10 @@ impl Arg<'_> {
         }
     }
 
-    /// `%g` / `%.Ng` — C's rule, **including the precision**, which is significant digits here
-    /// rather than decimal places.
-    ///
-    /// The precision is not decoration on this one. Five 1.12 templates are spelled `%.3g` —
-    /// `SPELL_CAST_TIME_SEC`, `SPELL_CAST_TIME_MIN`, `SPELL_RECAST_TIME_SEC`,
-    /// `SPELL_RECAST_TIME_MIN`, `SPELL_CAST_TIME_RANGED` — and the numbers reaching them are
-    /// divisions: a 100-second cooldown is 1.666… minutes. Under C that is "1.67 min cooldown".
-    /// Under Rust's shortest round-trip `{}` it is "1.6666666666666667 min cooldown", which is
-    /// why `{}` cannot stand in for `%g` in general even though it agrees with it on the one- and
-    /// two-decimal values the ammo templates carry.
-    ///
-    /// C's rule, from the standard: let X be the exponent of the value written in `%e` style at
-    /// precision P−1; use `%f` with precision P−1−X when P > X ≥ −4, and `%e` otherwise; then
-    /// drop trailing zeros from the fraction, and the point with them if nothing is left. Taking
-    /// X *after* the rounding is what makes 9.999 at P=3 read "10" rather than "10.0".
+    /// `%g`/`%.Ng` by C's rule, the precision P counting significant digits: with X the exponent
+    /// of the value in `%e` at precision P−1, use `%f` at P−1−X when P > X ≥ −4, else `%e`, then
+    /// drop trailing zeros. 1.12's five `%.3g` cast and cooldown templates need it: a 100-second
+    /// cooldown is "1.67 min", where Rust's shortest round-trip `{}` prints 17 digits.
     fn as_g(&self, prec: Option<usize>, out: &mut String) {
         let Arg::F(x) = self else {
             return self.as_s(out);
@@ -165,7 +107,7 @@ impl Arg<'_> {
             out.push('0');
             return;
         }
-        // Round first, then read the exponent off the result — the standard's own order.
+        // Round first, then read the exponent, so 9.999 at P=3 is "10", not "10.0".
         let sci = format!("{:.*e}", p - 1, x);
         let (mantissa, exp) = sci.split_once('e').unwrap_or((sci.as_str(), "0"));
         let exp: i32 = exp.parse().unwrap_or(0);
@@ -180,8 +122,7 @@ impl Arg<'_> {
     }
 }
 
-/// Drop a fraction's trailing zeros, and the point with them if nothing survives — `%g`'s last
-/// step, and the reason "1.50" prints as "1.5" and "2.00" as "2".
+/// `%g`'s last step: drop a fraction's trailing zeros, and the point if nothing is left.
 fn trim_zeros(s: &str) -> &str {
     match s.contains('.') {
         true => s.trim_end_matches('0').trim_end_matches('.'),
@@ -189,21 +130,19 @@ fn trim_zeros(s: &str) -> &str {
     }
 }
 
-/// One parsed `%…` specifier: where it ends, which argument it names, how precise, and what
-/// conversion. Split out because the scan now has four optional parts before the conversion
-/// letter and inlining it made the fill loop unreadable.
+/// One parsed `%…` specifier.
 struct Spec {
-    /// 1-based `%N$` argument, when the specifier is positional.
+    /// The 1-based `N` of `%N$`.
     positional: Option<usize>,
-    /// `.N`, when the specifier carries one.
+    /// `.N`.
     precision: Option<usize>,
     conv: char,
     /// Index just past the conversion letter.
     end: usize,
 }
 
-/// Scan `[N$][flags][width][.prec]conv` starting just after a `%`. `None` = not a conversion this
-/// module knows, which the caller copies through untouched.
+/// Scan `[N$][flags][width][.prec]conv` just after a `%`; `None` for a conversion this does not
+/// know.
 fn parse_spec(chars: &[char], after_percent: usize) -> Option<Spec> {
     let mut i = after_percent;
     let digits = |i: &mut usize| {
@@ -213,8 +152,7 @@ fn parse_spec(chars: &[char], after_percent: usize) -> Option<Spec> {
         }
         chars[start..*i].iter().collect::<String>()
     };
-    // `%N$…` — positional. Bare digits without the `$` are a width, so this only commits when the
-    // `$` is actually there.
+    // Digits are a position only when a `$` follows; otherwise they are a width.
     let mut positional = None;
     let mut probe = i;
     let n = digits(&mut probe);
@@ -239,53 +177,26 @@ fn parse_spec(chars: &[char], after_percent: usize) -> Option<Spec> {
     })
 }
 
-/// **The other half of decision 2045**: a reference string off the VM's own globals, `None` when
-/// the key is absent **or empty**. `load_global_strings` runs the player's own
-/// `GlobalStrings.lua` — and the `Localize()` patch over it — into this VM at boot, so this is
-/// the whole of "read the sentence from the install".
-///
-/// **Empty counts as missing, and that is the reference's own test, not a convenience.**
-/// `FrameScript_GetText` hands back a pre-seeded empty string (`0x882748`) for a key the table
-/// does not carry, and the callers that care test both — `GetPVPRankInfo` checks the pointer at
-/// `0x51aa1c` and then its first byte at `0x51aa20`. A caller here gets `None` for both, and the
-/// house rule is that **`None` emits no line at all rather than an invented one** (the
-/// disposition [`crate::script`]'s `duration_text` took, and 0620 §5 before it).
-///
-/// Spelled `globals().get::<String>` deliberately: that is the shape
-/// `benilla-app/tests/reference_strings.rs` recognises as a key lookup, so a function that
-/// resolves through this is visible to the tripwire as resolving.
+/// A string from the VM's globals, where the install's `GlobalStrings.lua` is loaded at boot;
+/// `None`, and so no line, when absent or empty. `FrameScript_GetText` returns an empty string
+/// (`0x882748`) for a missing key, and callers test both (`GetPVPRankInfo`, `0x51aa1c`/`0x51aa20`).
 pub fn global(lua: &mlua::Lua, key: &str) -> Option<String> {
-    // Bound before the filter so the lookup stays one unbroken `globals().get::<String>` — a
-    // rustfmt-split chain is a resolver the tripwire's substring match cannot see.
+    // Bound before the filter so `globals().get::<String>` stays one unbroken substring, which is
+    // what `benilla-app/tests/reference_strings.rs` matches as a key lookup.
     let value = lua.globals().get::<String>(key).ok();
     value.filter(|s| !s.is_empty())
 }
 
-/// **`GetText(token, nil, ordinal)`'s plural pick**, resolved: the bare token for exactly one, the
-/// `_P1` twin for anything else — **zero included** — and `GetText`'s own fall-back to the bare
-/// token when the twin is absent.
-///
-/// **Byte-pinned, and the `> 1` reading is refuted.** `0x52fa50` snprintf's the bare key, then
-/// `0x703bf0` looks up the Lua global `GetText` and pcalls it with `(key, ordinal, gender)`; the
-/// predicate is `LocaleProperties.lua`'s `GetPluralIndex`, singular iff `not ordinal or
-/// ordinal == 1`, and `703c89: 7d 07` is a **signed** test — a zero ordinal is pushed as the
-/// number `0`, which Lua reads as truthy, so it takes the plural arm. Only a negative becomes
-/// nil. Had zero mapped to nil, a lapsing aura would read "0 second remaining".
-///
-/// Lives here, beside [`fill`], because it is the second half of the same job and it had grown
-/// **four** private copies that had to agree and could not be made to: the aura ladder's, the
-/// instance lockouts', the talent pane's, and one inlined in the death screen's sickness timer.
-/// That is the shape decision 2045 wrote about — the first `fill` had eight.
-///
-/// `None` = neither the twin nor the bare token resolves, which is the reference's
-/// data-suppression face and means **no line at all** rather than an invented one.
+/// `GetText(token, nil, ordinal)`'s plural pick: `0x52fa50` formats the key and `0x703bf0`
+/// pcalls the Lua `GetText`, where `GetPluralIndex` (`LocaleProperties.lua:56`) is singular for
+/// `not ordinal or ordinal == 1`. So one or no ordinal takes the bare token, anything else the
+/// `_P1` twin, falling back to the bare token. Zero is plural: the test at `0x703c89` is signed,
+/// only a negative becomes nil, and the number `0` is truthy in Lua.
 pub fn plural(
     token: &str,
     ordinal: Option<u32>,
     get: &dyn Fn(&str) -> Option<String>,
 ) -> Option<String> {
-    // `not ordinal or ordinal == 1` is the SINGULAR arm, so an absent ordinal takes the bare
-    // token — the same `GetText(token)` short arm a nil `genderTag` sends the reference down.
     if ordinal.is_some_and(|n| n != 1) {
         if let Some(twin) = get(&format!("{token}_P1")).filter(|s| !s.is_empty()) {
             return Some(twin);
@@ -294,7 +205,7 @@ pub fn plural(
     get(token).filter(|s| !s.is_empty())
 }
 
-/// Fill a reference template. See the module doc for the rules.
+/// Fill a reference template, by the rules in the module doc.
 pub fn fill(template: &str, args: &[Arg<'_>]) -> String {
     let mut out = String::with_capacity(template.len() + 16);
     let chars: Vec<char> = template.chars().collect();
@@ -306,20 +217,18 @@ pub fn fill(template: &str, args: &[Arg<'_>]) -> String {
             i += 1;
             continue;
         }
-        // `%%`
         if chars.get(i + 1) == Some(&'%') {
             out.push('%');
             i += 2;
             continue;
         }
         let Some(spec) = parse_spec(&chars, i + 1) else {
-            // Not a conversion we know — copy the `%` and rescan from the next char, so `50% off`
-            // survives intact.
+            // Unknown: copy the `%` and rescan from the next char, so `50% off` survives.
             out.push('%');
             i += 1;
             continue;
         };
-        // A positional names its argument outright and does NOT move the sequential cursor.
+        // A positional does not move the sequential cursor.
         let idx = match spec.positional {
             Some(n) => n.checked_sub(1),
             None => Some(next),
@@ -336,7 +245,7 @@ pub fn fill(template: &str, args: &[Arg<'_>]) -> String {
                     next += 1;
                 }
             }
-            // starved — copy the whole specifier through so a mis-modelled template looks wrong
+            // Starved: copy the specifier through so a mis-modelled template shows.
             None => out.extend(&chars[i..spec.end]),
         }
         i = spec.end;
@@ -348,8 +257,6 @@ pub fn fill(template: &str, args: &[Arg<'_>]) -> String {
 mod tests {
     use super::*;
 
-    /// `ui_instance::fill_template`'s own contract, which this subsumes — ordered, starvation-safe,
-    /// `%%`-aware. These are its test's cases verbatim, so the migration cannot change behaviour.
     #[test]
     fn ordered_fills_stop_at_the_arguments_they_have() {
         assert_eq!(
@@ -361,19 +268,13 @@ mod tests {
         assert_eq!(fill("no fills", &[Arg::D(7)]), "no fills");
     }
 
-    /// **`%.3g` is significant digits, and the precision is load-bearing.** Five 1.12 templates
-    /// carry it, all of them fed by a division: `SPELL_RECAST_TIME_MIN = "%.3g min cooldown"`
-    /// against a 100-second cooldown is 1.666… minutes. Rust's shortest round-trip `{}` — the
-    /// obvious stand-in for `%g`, and what this filler shipped with for a day — writes all
-    /// seventeen digits of that. C writes three significant ones.
     #[test]
     fn g_is_significant_digits_and_drops_trailing_zeros() {
         let g = |t: &str, v: f64| fill(t, &[Arg::F(v)]);
         assert_eq!(g("%.3g min cooldown", 100.0 / 60.0), "1.67 min cooldown");
         assert_eq!(g("%.3g sec cast", 1.5), "1.5 sec cast");
-        // Trailing zeros go, and the point with them — 2.00 is "2", not "2.00".
         assert_eq!(g("%.3g sec cast", 2.0), "2 sec cast");
-        // The exponent is taken AFTER the rounding, which is what makes this "10" and not "10.0".
+        // The exponent is read after rounding.
         assert_eq!(g("%.3g", 9.999), "10");
         // A bare `%g` is C's default precision of six.
         assert_eq!(g("%g", 1.0 / 3.0), "0.333333");
@@ -382,8 +283,6 @@ mod tests {
         assert_eq!(g("%.3g", 123_456.0), "1.23e+05");
     }
 
-    /// `%f` takes the template's precision, not the caller's — `DPS_TEMPLATE` is one decimal
-    /// because the shipped string says `%.1f`, and a locale that respells it gets two for free.
     #[test]
     fn f_takes_the_templates_precision() {
         assert_eq!(
@@ -393,14 +292,9 @@ mod tests {
         assert_eq!(fill("%.2f", &[Arg::F(41.25)]), "41.25");
     }
 
-    /// **The plural pick's zero, which is the half people get wrong.** `GetText`'s predicate is
-    /// `not ordinal or ordinal == 1` — so an ABSENT ordinal is singular, and a zero one is
-    /// **plural**, because `703c89` is a signed test and Lua reads the number `0` as truthy. The
-    /// tempting `> 1` reading makes a lapsing aura read "0 second remaining".
     #[test]
     fn plural_takes_the_twin_for_zero_and_the_bare_token_for_none() {
         let table = |key: &str| -> Option<String> {
-            // Deliberately not the shipped wording: which key is reached is the whole question.
             match key {
                 "T" => Some("<one>".into()),
                 "T_P1" => Some("<many>".into()),
@@ -420,15 +314,11 @@ mod tests {
             Some("<one>"),
             "no ordinal at all takes GetText's short arm"
         );
-        // A token with no `_P1` twin falls back to itself, at any count.
         assert_eq!(plural("ONLY", Some(7), &table).as_deref(), Some("<only>"));
-        // Neither resolving is no line at all, never an invented one.
         assert_eq!(plural("ABSENT", Some(2), &table), None);
     }
 
-    /// **The case an ordered filler cannot express**, and the reason positional specifiers exist:
-    /// 1.12's duel pair reorders the same two names, so filling them left-to-right names the wrong
-    /// winner. Both templates are quoted from GlobalStrings (958/959).
+    /// The duel pair, `GlobalStrings.lua:958-959`.
     #[test]
     fn positional_specifiers_reorder_rather_than_consume() {
         let (a, b) = (Arg::S("Alice"), Arg::S("Bob"));
@@ -440,12 +330,9 @@ mod tests {
             fill("%2$s has fled from %1$s in a duel", &[a, b]),
             "Bob has fled from Alice in a duel"
         );
-        // A positional may repeat an argument, which no cursor-based fill can do.
         assert_eq!(fill("%1$s vs %1$s", &[a]), "Alice vs Alice");
     }
 
-    /// The bug that eight copies of this hid: `str::replace` fills every `%s` with the *same*
-    /// argument. Two holes must take two arguments.
     #[test]
     fn each_hole_takes_its_own_argument() {
         assert_eq!(
@@ -457,7 +344,6 @@ mod tests {
         );
     }
 
-    /// A starved positional is copied through too, and an unknown specifier is left alone.
     #[test]
     fn starved_and_unknown_specifiers_survive_visibly() {
         assert_eq!(fill("%1$s and %2$s", &[Arg::S("only")]), "only and %2$s");
@@ -465,17 +351,14 @@ mod tests {
         assert_eq!(fill("%q", &[Arg::S("x")]), "%q");
     }
 
-    /// Numbers reach `%s` as digits and strings reach `%d` as themselves — a caller whose argument
-    /// grouping differs from the template's still fills in the template's order.
     #[test]
     fn arguments_render_for_whichever_hole_they_meet() {
         assert_eq!(fill("%s/%d", &[Arg::D(3), Arg::D(5)]), "3/5");
         assert_eq!(fill("%d", &[Arg::S("many")]), "many");
     }
 
-    /// The item tooltip's own two exotic holes, quoted from GlobalStrings (2416, 2441, 942): a
-    /// `%c` sign character and a `%.1f` rate. Both consume an argument like any other hole — the
-    /// bug they replace is a filler that copied them through and showed the player `"%c+5"`.
+    /// `ITEM_MOD_AGILITY`, `ITEM_RESIST_SINGLE` and `DPS_TEMPLATE`, `GlobalStrings.lua:2416`,
+    /// `:2441` and `:942`.
     #[test]
     fn the_sign_and_rate_holes_the_item_builder_uses() {
         assert_eq!(
@@ -493,21 +376,17 @@ mod tests {
             fill("(%.1f damage per second)", &[Arg::F(24.428_571)]),
             "(24.4 damage per second)"
         );
-        // The PRECISION is the template's: respelling it changes the line with no code change.
         assert_eq!(fill("%.3f", &[Arg::F(1.5)]), "1.500");
         assert_eq!(fill("%f", &[Arg::F(1.5)]), "1.500000", "C's default is 6");
-        // `%g` drops the trailing zeros the ammo templates would otherwise show.
         assert_eq!(fill("Adds %g damage", &[Arg::F(7.0)]), "Adds 7 damage");
         assert_eq!(fill("Adds %g damage", &[Arg::F(7.5)]), "Adds 7.5 damage");
     }
 
-    /// A width or flag between the `%` and the letter is skipped rather than breaking the scan,
-    /// and a starved `%.1f` still copies through whole.
     #[test]
     fn widths_and_flags_do_not_derail_the_scan() {
         assert_eq!(fill("%5d|%-3s", &[Arg::D(7), Arg::S("x")]), "7|x");
         assert_eq!(fill("%.1f and %.1f", &[Arg::F(1.0)]), "1.0 and %.1f");
-        // A bare `%` before a digit that never reaches a conversion letter is still just a `%`.
+        // `%1 ` never reaches a conversion letter, so the `%` stays literal.
         assert_eq!(fill("100%1 of it", &[Arg::D(3)]), "100%1 of it");
     }
 }
diff --git a/crates/benilla-ui/src/toc.rs b/crates/benilla-ui/src/toc.rs
index 046ec6a2..3c66828b 100644
--- a/crates/benilla-ui/src/toc.rs
+++ b/crates/benilla-ui/src/toc.rs
@@ -1,37 +1,24 @@
-//! The `.toc` manifest parser — the load list + metadata of every addon, including Blizzard's own
-//! (`FrameXML.toc` and the `Blizzard_*` AddOns are ordinary manifests; third-party addons are the
-//! identical mechanism — decision 0068).
-//!
-//! Grammar, shared by 1.12 and Era manifests (Era only adds directive *keys*, not syntax):
-//! - `## Key: Value` — a directive. Keys compare case-insensitively; localized variants carry a
-//!   locale suffix (`## Title-deDE: …`). Era manifests list several client builds in one
-//!   `## Interface: 11507, 11508`.
-//! - `#` (not followed by another `#`) — a comment.
-//! - anything else non-blank — a file to load, in order (`.lua`/`.xml`, `\` or `/` separators).
-//!
-//! The parser is lossless about order (directives keep file order for duplicate keys; files keep
-//! load order) and byte-tolerant: UTF-8 BOM, `\r\n`, and stray whitespace are the norm in shipped
-//! manifests, not the exception.
+//! The `.toc` manifest parser, for FrameXML, the `Blizzard_*` addons and third-party ones alike:
+//! `## Key: Value` is a directive, any other `#` line a comment, and any other non-blank line a
+//! file to load, in order. A BOM, `\r\n` and stray whitespace are tolerated.
 
-/// A parsed `.toc` manifest: ordered directives + the ordered file load list.
+/// A parsed `.toc` manifest.
 #[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct Toc {
-    /// `## Key: Value` directives in file order, keys as written (compare via [`Toc::directive`]).
+    /// `## Key: Value` pairs in file order, keys as written.
     pub directives: Vec<(String, String)>,
-    /// Files to load, in order, exactly as written (path separators are normalized at *load* time,
-    /// not here — the manifest is quoted verbatim in errors and tooling).
+    /// Files to load, in order, as written; separators are normalized at load time.
     pub files: Vec<String>,
 }
 
-/// Case-insensitive ASCII prefix test — the reference's `SStrCmpI(line, key, SStrLen(key))`.
+/// Case-insensitive ASCII prefix test, the reference's `SStrCmpI(line, key, SStrLen(key))`.
 fn starts_with_ci(s: &str, prefix: &str) -> bool {
     let (s, p) = (s.as_bytes(), prefix.as_bytes());
     s.len() >= p.len() && s[..p.len()].eq_ignore_ascii_case(p)
 }
 
 impl Toc {
-    /// Parse manifest text. Never fails: unrecognizable lines are file entries by definition of
-    /// the grammar, and an empty input is an empty manifest.
+    /// Parse manifest text; never fails, since any unrecognized line is a file entry.
     pub fn parse(text: &str) -> Self {
         let text = text.strip_prefix('\u{feff}').unwrap_or(text);
         let mut toc = Toc::default();
@@ -41,8 +28,7 @@ impl Toc {
                 continue;
             }
             if let Some(directive) = line.strip_prefix("##") {
-                // `##` alone (or without a colon) is treated as a comment, matching the client's
-                // tolerance for malformed directives.
+                // `##` with no colon is a comment, as the client tolerates it.
                 if let Some((key, value)) = directive.split_once(':') {
                     let key = key.trim();
                     if !key.is_empty() {
@@ -57,17 +43,8 @@ impl Toc {
         toc
     }
 
-    /// The directive whose key matches `key` case-insensitively — **the LAST one, when a manifest
-    /// writes the key twice**.
-    ///
-    /// This read the first for as long as the doc here said "shipped manifests don't duplicate
-    /// keys", which two of them do: `MoveAnything.toc` has `## Notes` on lines 3 and 5, and
-    /// `AtlasLoot.toc` has `## Author` on lines 6 and 9. The reference hashes each directive into
-    /// the metadata map at `[rec+0x98]` (`0x51d580`) and, on an existing entry, **frees the old
-    /// value and stores the new** (`0x51d77b`) — a hash insert, so the last line written wins.
-    ///
-    /// Note the asymmetry with [`Self::list`] one function down, and that both halves were wrong
-    /// here in the same direction: a **scalar** replaces, a **list** appends.
+    /// The directive matching `key` case-insensitively, the last one when a key repeats: the
+    /// reference's hash insert into `[rec+0x98]` (`0x51d580`) replaces the old value (`0x51d77b`).
     pub fn directive(&self, key: &str) -> Option<&str> {
         self.directives
             .iter()
@@ -76,20 +53,15 @@ impl Toc {
             .map(|(_, v)| v.as_str())
     }
 
-    /// `## Interface:` as client build numbers. Era manifests list several (`11507, 11508`);
-    /// 1.12's lists one (`11200`). Unparseable entries are skipped, not errors.
+    /// `## Interface:` as build numbers, for display; Era manifests list several (`11507, 11508`).
     pub fn interface_versions(&self) -> Vec<u32> {
         self.directive("Interface")
             .map(|v| v.split(',').filter_map(|n| n.trim().parse().ok()).collect())
             .unwrap_or_default()
     }
 
-    /// `## Interface:` **as the 1.12 client reads it** (decision 1292): the leading integer of the
-    /// value, and a manifest with no `## Interface` line (or a non-numeric one) is `0`.
-    /// `Toc_Parse 0x51c9b0` stores `SStrToInt` of the value at `[rec+0x1c]`, the record ctor
-    /// leaves it `0`, and the version gate compares that single dword — so an Era manifest's
-    /// `11507, 11508` reads as `11507`, exactly as the reference would read it.
-    /// [`Toc::interface_versions`] stays for display; the GATE runs on this.
+    /// `## Interface:` as the version gate reads it: `Toc_Parse 0x51c9b0` stores `SStrToInt` of
+    /// the value at `[rec+0x1c]` (else the ctor's `0`), so `11507, 11508` reads `11507`.
     pub fn interface_version(&self) -> u32 {
         self.directive("Interface")
             .map(|v| {
@@ -99,29 +71,14 @@ impl Toc {
             .unwrap_or(0)
     }
 
-    /// A list directive (`SavedVariables`, `OptionalDeps`, `Dependencies`, …), tokenized the way
-    /// the reference tokenizes it. Missing directive = empty list.
-    ///
-    /// **Two departures from the obvious read, both byte-derived, both of which were losing real
-    /// data** (decision 2126):
-    ///
-    /// * **A repeated directive APPENDS.** The reference `strdup`s each item (`0x64a620`) into a
-    ///   `0x40`-granular array at `[rec+0x80]` with a running count at `[rec+0x7c]`, so a second
-    ///   `## SavedVariables:` line continues the first rather than being ignored. Reading only the
-    ///   first line cost `CT_RaidAssist` 18 of
-    ///   its 25 saved globals — it declares them across four lines and got seven, so raid
-    ///   positions, menu state, boss timers, debuff templates, the loot method and the squelch
-    ///   list were never written and never restored.
-    /// * **A space separates as surely as a comma.** The tokenizer is `SStrTokenize 0x64ae50` over
-    ///   the delimiter SET `" ,"` at `0x8537c4` — readable in the image's own `.rdata`, sitting
-    ///   between the `RequiredDep` and `OptionalDep` literals. `SpecialTalentUI` writes
-    ///   `## SavedVariables: SpecialTalentPlannedSaved SpecialTalentFrameSaved` and we registered
-    ///   one "global" whose name contained a space.
+    /// A list directive (`SavedVariables`, `OptionalDeps`, …) as the reference tokenizes it: a
+    /// repeated line appends (`0x64a620` into the array at `[rec+0x80]`, count at `[rec+0x7c]`),
+    /// and a space separates like a comma (`SStrTokenize 0x64ae50`, delimiters `" ,"` at
+    /// `0x8537c4`).
     pub fn list(&self, key: &str) -> Vec<&str> {
         self.list_where(|k| k.eq_ignore_ascii_case(key))
     }
 
-    /// [`Self::list`] over every directive whose key satisfies `pick`, in file order.
     fn list_where(&self, mut pick: impl FnMut(&str) -> bool) -> Vec<&str> {
         self.directives
             .iter()
@@ -131,64 +88,29 @@ impl Toc {
             .collect()
     }
 
-    /// Hard dependencies — **every directive whose key STARTS WITH `Dep` or `RequiredDep`**.
-    ///
-    /// The three dependency keys are the only ones in the reference's directive table that carry
-    /// **no colon**: the `.rdata` cluster reads
-    /// `SavedVariablesPerCharacter:\0 SavedVariables:\0 LoadWith:\0 \0\0 Dep\0 RequiredDep\0 " ,"\0\0 OptionalDep\0 Revision:\0`,
-    /// and a whole-key compare against `"Dep"` could never match a line reading `Dependencies:`.
-    /// So the compare is a PREFIX compare — `SStrCmpI(line, key, SStrLen(key))` at
-    /// `0x51cd4e`-`0x51cd5f` — and `## Dependencies`, `## RequiredDependencies` and
-    /// `## Dependency` all land here (decision 2126).
-    ///
-    /// Both keys feed the SAME array in the reference (`[rec+0x50]`), so a manifest writing both
-    /// gets their union rather than whichever this function happened to test first.
+    /// Hard dependencies: every directive whose key starts with `Dep` or `RequiredDep`. The
+    /// reference stores these keys without a colon and prefix-compares them
+    /// (`0x51cd4e`-`0x51cd5f`), so `## Dependencies` and `## RequiredDependencies` both land in
+    /// its one array at `[rec+0x50]`.
     pub fn dependencies(&self) -> Vec<&str> {
         self.list_where(|k| starts_with_ci(k, "RequiredDep") || starts_with_ci(k, "Dep"))
     }
 
-    /// Soft dependencies — every directive whose key starts with `OptionalDep`, on the same
-    /// prefix rule as [`Self::dependencies`].
-    ///
-    /// **They load FIRST and their failures are ignored** — `AddOn_Load 0x51f240`'s own order,
-    /// quoted in 1191 §2 — which is what lets `## OptionalDeps: FuBar, Ace2` mean "if Ace2 is
-    /// installed, its libraries are already global by the time my files run". **130 corpus addons
-    /// declare them**, and the whole FuBar family leans on exactly that: `FuBar_BagFu`'s `.toc`
-    /// lists `FuBarPlugin-2.0.lua` BEFORE `AceLibrary.lua`, which only works because the `Ace2`
-    /// addon went first.
-    ///
-    /// The long form `## OptionalDependencies:` — which 4 corpus addons write — used to be
-    /// refused here, on the reasoning that it was "verified for the required half and merely
-    /// plausible for this one, left open". The premise was wrong: the reference
-    /// matches all three dependency keys by the same colon-less prefix, so the long form was never
-    /// a separate question.
+    /// Soft dependencies: every directive whose key starts with `OptionalDep`, the long form
+    /// included. `AddOn_Load 0x51f240` loads them first and ignores their failures.
     pub fn optional_dependencies(&self) -> Vec<&str> {
         self.list_where(|k| starts_with_ci(k, "OptionalDep"))
     }
 
-    /// `## LoadOnDemand: 1` (Era loader; absent in 1.12 manifests).
+    /// `## LoadOnDemand: 1`, which stock 1.12 addons such as `Blizzard_TalentUI` carry.
     pub fn load_on_demand(&self) -> bool {
         self.directive("LoadOnDemand").map(str::trim) == Some("1")
     }
 
-    /// `## DefaultState:` — what this addon's enable state is for a character who has never
-    /// expressed one. The reference's `[rec+0x2b]`, stored by `Toc_Parse` at `0x51d204` from the
-    /// two literals `"enabled"` (`0x853764`) → `1` and `"disabled"` (`0x853758`) → `0`.
-    ///
-    /// It is load-bearing well beyond a manifest that writes it: the enable query `0x51e470`
-    /// falls back to this byte whenever the characters disagree, and whenever *none* of them has
-    /// an opinion at all — which is every addon on a fresh install.
-    ///
-    /// **A manifest that does not write the line is enabled** — which is what makes a folder
-    /// dropped into `AddOns/` just work, and is the record's initial byte, read at the bytes and
-    /// not inferred from the two literals' fall-through (decision 2316). The ctor `0x520550` seeds
-    /// this one field to 1 explicitly — `0x5205b9 mov [esi+0x2b],al` with `eax = 1`, where its five
-    /// neighbours take `bl = 0` — over an allocation that does zero-fill, which is exactly what
-    /// made "the ctor zeroes it" read as true.
-    ///
-    /// Two consequences this function depends on, both verified: a value matching **neither**
-    /// literal leaves the 1 (`0x51d21a jne`, no store — there is no "unrecognised means disabled"),
-    /// and a duplicated directive is **last-wins**, which is [`Self::directive`]'s own rule.
+    /// `## DefaultState:`, the byte at `[rec+0x2b]` the enable query `0x51e470` falls back to when
+    /// characters disagree or none has chosen. `Toc_Parse` stores `"enabled"` (`0x853764`) as 1 and
+    /// `"disabled"` (`0x853758`) as 0 at `0x51d204` and any other value not at all (`0x51d21a`);
+    /// the ctor `0x520550` seeds 1 (`0x5205b9`), so only `disabled` disables.
     pub fn default_state(&self) -> bool {
         !self
             .directive("DefaultState")
@@ -228,13 +150,6 @@ mod tests {
         assert_eq!(toc.directives.len(), 4);
     }
 
-    /// **`## DefaultState:` and its three non-obvious answers**: an absent line is *enabled*
-    /// because the record's ctor seeds `[rec+0x2b]` to 1, a value matching neither literal leaves
-    /// that 1 rather than meaning disabled, and a duplicated line is last-wins.
-    ///
-    /// Only `disabled` disables, in other words — which is the same asymmetry `AddOns.txt`'s own
-    /// value grammar has, and worth a falsifier because "unrecognised means off" is the reading
-    /// anyone would write by hand.
     #[test]
     fn default_state_is_enabled_unless_the_manifest_says_disabled() {
         let d = |body: &str| Toc::parse(body).default_state();
@@ -253,7 +168,7 @@ mod tests {
             d("## DefaultState:\n"),
             "empty value is not `disabled` either"
         );
-        // Last-wins, the reference's hash insert — not first-wins, and not an append.
+        // Last-wins, the reference's hash insert.
         assert!(!d("## DefaultState: enabled\n## DefaultState: disabled\n"));
         assert!(d("## DefaultState: disabled\n## DefaultState: enabled\n"));
     }
@@ -273,10 +188,6 @@ mod tests {
         assert_eq!(toc.files.len(), 2);
     }
 
-    /// **A scalar directive REPLACES on a repeat; a list directive APPENDS** — the reference's two
-    /// stores, and this file had both backwards (decision 2126). `MoveAnything.toc` writes
-    /// `## Notes` twice and `AtlasLoot.toc` writes `## Author` twice, so the scalar half is not
-    /// hypothetical either.
     #[test]
     fn a_scalar_directive_replaces_and_a_list_directive_appends() {
         let toc = Toc::parse(
@@ -290,13 +201,6 @@ mod tests {
         assert!(toc.load_on_demand());
     }
 
-    /// **`CT_RaidAssist`'s own manifest, in shape** — 25 saved globals across four lines, of which
-    /// we registered the first seven. The rest (raid positions, menu state, boss timers, debuff
-    /// templates, the loot method, the squelch list) were never written and never restored.
-    ///
-    /// Plus `SpecialTalentUI`'s: two names separated by a SPACE, which we read as one global whose
-    /// name contained a space. The tokenizer is `SStrTokenize 0x64ae50` over the delimiter set
-    /// `" ,"` at `0x8537c4`.
     #[test]
     fn a_repeated_list_directive_accumulates_across_lines_and_splits_on_space() {
         let toc = Toc::parse(
@@ -308,15 +212,6 @@ mod tests {
         assert_eq!(toc.list("SavedVariablesPerCharacter"), vec!["E", "F"]);
     }
 
-    /// **The three dependency keys are matched by PREFIX**, because they are the only directives in
-    /// the reference's table with no colon: the `.rdata` cluster is
-    /// `… LoadWith:\0 \0\0 Dep\0 RequiredDep\0 " ,"\0\0 OptionalDep\0 Revision:\0 …`, and a
-    /// whole-key compare against `"Dep"` could never match a line reading `Dependencies:`.
-    ///
-    /// Four corpus addons write the long optional form (`FuBar_CRDelayFu`, `FuBar_PetInFu`,
-    /// `FuBar_ToFu`, `FuBar_WeaponRebuffFu`), which this file used to refuse on the reasoning that
-    /// the long form was "merely plausible" for the optional half. It was never a separate
-    /// question.
     #[test]
     fn the_dependency_keys_match_by_prefix_and_both_required_spellings_union() {
         let toc = Toc::parse(
@@ -331,8 +226,7 @@ mod tests {
             vec!["LibC", "LibD", "LibE"],
             "the long and short optional spellings are the same key"
         );
-        // And the prefixes do not bleed into each other: `OptionalDependencies` does not start
-        // with `Dep`, so it never lands in the required list.
+        // `OptionalDependencies` does not start with `Dep`.
         assert!(!toc.dependencies().contains(&"LibC"));
     }
 
diff --git a/crates/benilla-ui/src/widget/kinds/editbox.rs b/crates/benilla-ui/src/widget/kinds/editbox.rs
index 0f0c3f70..4028ba68 100644
--- a/crates/benilla-ui/src/widget/kinds/editbox.rs
+++ b/crates/benilla-ui/src/widget/kinds/editbox.rs
@@ -3,282 +3,136 @@ use super::RegionHandle;
 /// The text span a cursor motion or deletion operates over.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum EditUnit {
-    /// One character (the plain arrow / Backspace / Delete granularity).
+    /// One character, a whole link counting as one: plain arrow, Backspace, Delete.
     Char,
-    /// One word run ([`EditBoxState::word_boundary`] — the Ctrl/Option-arrow granularity).
+    /// One word run ([`EditBoxState::word_boundary`]): Ctrl/Option+arrow.
     Word,
-    /// The line edge: text start going back, text end going forward (Home/End, Cmd+arrow).
+    /// Text start going back, text end going forward: Home/End, Cmd+arrow.
     Edge,
 }
 
-/// One semantic text-editing operation on an edit box — fed to [`EditBoxState::apply`]. The host's
-/// per-OS keymap (which physical chord means which action: Ctrl+Left on Windows, Option+Left on
-/// macOS, …) translates key events into these; the *effect* of each action is the reference's own
-/// edit-box law (selection anchoring, selection-first deletes, word classes). Clipboard operations
-/// are deliberately absent: they need the OS pasteboard, so they stay host-side.
+/// One semantic editing operation for [`EditBoxState::apply`]: the host's per-OS keymap picks the
+/// action, the reference's edit-box law decides its effect. Clipboard operations stay host-side.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum EditAction {
-    /// Move the caret one `unit` back/forward; `extend` drags the selection from its fixed
-    /// anchor (the Shift family). (The alt-arrow gate is upstream, on the key — the
-    /// ref guard `0x77b18e`; arrows are the only chord source of `Char` moves).
+    /// Move the caret one `unit`; `extend` (Shift) drags the selection from its fixed anchor. The
+    /// alt-arrow gate (`0x77b18e`) acts upstream, on the key.
     Move {
         unit: EditUnit,
         back: bool,
         extend: bool,
     },
-    /// Delete one `unit` back/forward from the caret — the selection first when one exists
-    /// (every deletion gesture collapses to "delete the selection"). `Edge` going back is the
-    /// macOS Cmd+Backspace "clear to start".
+    /// Delete one `unit` from the caret, or the selection if any; `Edge` back is Cmd+Backspace.
     Delete { unit: EditUnit, back: bool },
-    /// Select the whole text, caret to the end (the ref's Ctrl+A, `HighlightText(0, -1)`).
+    /// Ctrl+A: select all, caret to the end (`HighlightText(0, -1)`).
     SelectAll,
-    /// Recall the previous (older) submitted line into the box (`historyLines`).
+    /// Recall the next older submitted line (`historyLines`).
     HistoryPrev,
     /// Step back toward the newest line; past it, restore the stashed draft.
     HistoryNext,
 }
 
-/// A `CSimpleEditBox`'s runtime state — the text/cursor/selection/flags model.
-/// Offsets below are the client's **E-base** (the CScriptObject `this`), the base the runtime
-/// input/text handlers address the object through.
-///
-/// The client stores text as a NUL-terminated `char*` with a parallel per-byte class array; benilla
-/// holds it as a Rust `String` and keeps every byte offset ([`cursor`](Self::cursor)/
-/// [`sel_start`](Self::sel_start)/[`sel_end`](Self::sel_end)) snapped to a UTF-8 char boundary — the
-/// same invariant the client's boundary-snap (`0x77bd30`) maintains.
+/// A `CSimpleEditBox`'s runtime state; `E+` offsets are from its `CScriptObject` `this`. Byte
+/// offsets stay on char boundaries, as the client's boundary snap (`0x77bd30`) keeps them.
 #[derive(Clone, Debug, PartialEq)]
 pub struct EditBoxState {
-    /// The real text buffer (`E+0x32c`, `char*`). `GetText`/`GetNumber` read this; `password` masks
-    /// only the *display* (`E+0x334`, rebuilt by `0x77d4d0`), never this buffer.
+    /// The real text (`E+0x32c`); `password` masks only the display (`E+0x334`, `0x77d4d0`).
     pub text: String,
-    /// The insertion caret as a byte offset into [`text`](Self::text) (`E+0x36c`; sole setter
-    /// clamps to `[0, len]`). Always on a char boundary.
+    /// The caret, a byte offset into the text (`E+0x36c`, clamped to `[0, len]`).
     pub cursor: usize,
-    /// Selection anchor (`E+0x35c`) — equal to [`sel_end`](Self::sel_end) (and the cursor) when no
-    /// text is selected. Byte offset, char-boundary-snapped.
+    /// Selection start (`E+0x35c`); equal to `sel_end` and the cursor when nothing is selected.
     pub sel_start: usize,
-    /// Selection end (`E+0x360`). A non-empty selection is `sel_start != sel_end`; every insert
-    /// replaces it first (`0x77cd70`).
+    /// Selection end (`E+0x360`); an insert replaces a non-empty selection first (`0x77cd70`).
     pub sel_end: usize,
-    /// `autoFocus` (`flags@E+0x318` bit0). Two acquisition paths, and both are built:
-    ///
-    /// 1. **On SHOW** — the box self-focuses when it becomes visible, gated on nothing else holding
-    ///    focus. The EditBox's own OnShow vtable override (`0x81c910` slot +0x30, `0x77a750`) fires
-    ///    the Lua handler and then tail-jumps `SetFocus`:
-    ///    `if ([0xcf4dc8] == 0 && (flags & 1)) jmp 0x77e3d0` @`0x77a76d`. The mirror slot +0x34
-    ///    (`0x77a780`) tail-jumps `ClearFocus`, so **hiding an edit box releases the keyboard**.
-    ///    Ours is [`crate::script::editbox`]'s `visibility_focus`.
-    /// 2. **On the first key/char event** while nothing is focused — the self-acquire guard; the box
-    ///    grabs focus and processes that same event.
-    ///
-    /// **Both corrections landed together, decision 1686 (2026-08-29).** The construction default
-    /// came with it and is byte-read, not chosen — see [`Default`]'s `flags = 1` note below. Every
-    /// `autoFocus` in the shipped 1.12.1 chain is `="false"`, ten opt-outs and no opt-ins, which is
-    /// the authoring signature of exactly that default.
+    /// `autoFocus` (`E+0x318` bit 0): take the focus when shown if nothing holds it (the OnShow
+    /// override `0x77a750`, `0x77a76d`) and on a key or char event while nothing is focused.
     pub auto_focus: bool,
-    /// `multiLine` (bit1): Enter inserts a newline (rather than firing `OnEnterPressed`) and `\n` is
-    /// accepted into the buffer.
+    /// `multiLine` (bit 1): Enter inserts a newline instead of firing `OnEnterPressed`.
     pub multi_line: bool,
-    /// `numeric` (bit2): an insert containing ANY char outside `'0'..='9'` is aborted wholesale
-    /// (not per-char filtered) — the char filter `0x77bf41`.
+    /// `numeric` (bit 2): an insert with any non-digit is refused whole, not filtered (`0x77bf41`).
     pub numeric: bool,
-    /// `password` (bit3): the display string is one `'*'` per *character* (the mask, `E+0x334`); the
-    /// real text is untouched.
+    /// `password` (bit 3): the display is one `*` per character (`E+0x334`); the text is untouched.
     pub password: bool,
-    /// **Alt-arrow mode** (bit4) — the XML attribute spells it `ignoreArrows`, the Lua surface
-    /// spells it `SetAltArrowKeyMode`/`GetAltArrowKeyMode` (`0x7996e0`/`0x799790`), and there is
-    /// exactly one flag behind both names. `SetIgnoreArrows` does **not** exist in 5875: the
-    /// 48-entry EditBox method table `[0x87bb68, 0x87bce8)` carries the Alt pair at 46/47 and no
-    /// entry whose name contains "Ignore".
-    ///
-    /// **What it does, and it is not what "ignore" suggests.** With the flag set, the four arrow
-    /// keys (`0x204` LEFT / `0x205` UP / `0x206` RIGHT / `0x207` DOWN) are **not consumed by the
-    /// box at all** unless ALT is held — the guard `0x77b18e` returns 0, the strata walk carries
-    /// on down to `CGWorldFrame`, and the key reaches its binding (`TURNLEFT`, `MOVEFORWARD`).
-    /// That is the whole point: it is what lets you turn while the chat box has focus. With Alt
-    /// held the guard falls through to ordinary handling and the caret moves.
-    ///
-    /// A focused box otherwise consumes **everything** (the handler's shared tail `0x77b35e`
-    /// returns 1), so these four keys are the only ones it ever lets past.
-    ///
-    /// benilla read this as "consumed but inert, unless Ctrl" for two rounds — the modifier was
-    /// wrong (`0x41f8f0(2)` is ALT, not Ctrl) and so was the consumption. Both are corrected above.
+    /// Alt-arrow mode (bit 4; XML `ignoreArrows`, Lua `SetAltArrowKeyMode`): a focused box lets the
+    /// four arrows through to their bindings unless Alt (`0x41f8f0(2)`) is held (`0x77b18e`), so
+    /// you can turn while typing. It consumes every other key (`0x77b35e`).
     pub alt_arrow_key_mode: bool,
-    /// `maxLetters` (`E+0x340`, 0 = unlimited): after each insert, trim from the end while the
-    /// *letter* (char) count exceeds this (`0x77c02d`).
+    /// `maxLetters` (`E+0x340`), 0 for unlimited.
     pub max_letters: usize,
-    /// `maxBytes` (`E+0x33c`; the client's `-1` sentinel = unlimited → `None` here): trim from the
-    /// end while the byte length exceeds this, applied before `maxLetters`.
+    /// `maxBytes` (`E+0x33c`); the client's `-1`, unlimited, is `None`.
     pub max_bytes: Option<usize>,
-    /// The implicit FontString the text renders through (`E+0x328`, the EditBox's analogue of
-    /// ButtonText). **Built by the ctor**, not lazily: `0x779bee` constructs it from allocator
-    /// `0xcf4d10` with tag `0x846544` = `".?AVCSimpleFontString@@"` via `0x770d30(E, 2, 1)`, and
-    /// that is the FIRST of the five regions a `CSimpleEditBox` is born with. Creation order is
-    /// what `GetRegions 0x773f60` hands Lua — one flat creation-ordered list off `[frame+0x1b8]`,
-    /// oldest first, no filter — so these five precede every `<Layers>` region.
-    ///
-    /// **DEFERRED, and named rather than silently taken:** the ctor's draw layer is 2 sub 1
-    /// (ARTWORK), while this region is still created at OVERLAY sub 0 — what ships today and what
-    /// the director has looked at. Moving it is a draw-order change to every EditBox in the client
-    /// with nothing asking for it, so it is a separate change, not a rider on this one.
+    /// The implicit FontString the text renders through (`E+0x328`, ctor `0x779bee`).
     pub text_region: Option<RegionHandle>,
-    /// The **three selection-highlight quads** (`E+0x350`/`0x354`/`0x358`), built by the ctor loop
-    /// `0x779c41–0x779c72` as `CSimpleTexture`s via `0x76fc40(E, 2, 0)` — allocator `0xcf4ce0`, tag
-    /// `0x846588` = `".?AVCSimpleTexture@@"`, class-identical to the caret. They are
-    /// members of the frame's region list like any other region (`0x76fc40`→`0x77f640`→`0x77fd10`,
-    /// the single linker into `[frame+0x1b8]`), which is why they are built here.
-    ///
-    /// **They carry no art of their own and paint nothing.** benilla draws the selection highlight
-    /// host-side, from [`sel_start`](Self::sel_start)/[`sel_end`](Self::sel_end) through the seam —
-    /// so these are the real regions the client has, not yet the regions the highlight rides.
-    /// Routing the paint through them is a separate, larger change (the host would have to read a
-    /// region rect instead of a seam field); this is stated, not stubbed.
+    /// The three selection-highlight textures (`E+0x350`/`0x354`/`0x358`, ctor `0x779c41`). They
+    /// paint nothing: the host draws the highlight from `sel_start`/`sel_end`.
     pub selection_regions: [Option<RegionHandle>; 3],
-    /// The **caret** (`E+0x368`), the ctor's fifth and last region: a `CSimpleTexture` built at
-    /// `0x779c86–0x779cac` via `0x76fc40(E, 3, 1)` — a solid vertex-coloured quad, never a glyph
-    /// (no texture path is ever assigned to `E+0x368`, band-wide census). Layer 3 over
-    /// the text's 2 is why the caret draws above the text and the selection quads below it.
-    ///
-    /// Same standing as [`selection_regions`](Self::selection_regions): the region is real and in
-    /// the list, the *painting* is still host-side off [`caret_shown`](Self::caret_shown).
+    /// The caret texture (`E+0x368`, ctor `0x779c86`), a solid quad above the text. It paints
+    /// nothing: the host draws the caret from `caret_shown`.
     pub caret_region: Option<RegionHandle>,
-    /// The submitted-line history (`AddHistoryLine`; the XML `historyLines` cap) — oldest first,
-    /// newest last; UP recalls older from the end, DOWN newer. The exact recall keys + draft model
-    /// are inferred: the 1.12 history controller is an untraced observer (`0x77b730`) — plain
-    /// UP/DOWN with the in-progress line restored past the newest entry; still open on the chat arc
-    /// (decision 0288).
+    /// The submitted lines, oldest first. UP/DOWN recall and the restored draft are inferred: the
+    /// reference's history controller (`0x77b730`) is untraced.
     pub history: Vec<String>,
-    /// `historyLines` — max entries kept (drop-oldest on add). `0` = history off (the widget
-    /// default; ChatFrame's edit box declares 32).
+    /// `historyLines`, the most lines kept; 0 (the default) is no history.
     pub history_max: usize,
-    /// The active recall position while browsing (an index into [`Self::history`]); `None` = live
-    /// editing. Typed edits, [`Self::add_history_line`], and focus gain end browsing —
-    /// programmatic `SetText` deliberately does NOT (the chat live parse rewrites the box on
-    /// every recalled slash line; ending the browse there pinned every UP to the newest entry).
+    /// The recall position, `None` while editing. `SetText` must not end the browse: the chat
+    /// parser rewrites a recalled slash line through it.
     pub history_pos: Option<usize>,
     /// The live line stashed when browsing starts, restored when DOWN walks past the newest entry.
     pub history_draft: Option<String>,
-    /// `SetTextInsets(l, r, t, b)` / XML `<TextInsets>` — the text region's rect shrink inside the
-    /// box (the chat edit box drives its left inset past the "Say:" header every header change).
-    /// Applied as the text region's two corner anchors (`script::editbox::set_text_insets`).
+    /// `SetTextInsets(l, r, t, b)`, applied as the text region's two corner anchors.
     pub text_insets: [f32; 4],
-    /// The focused box's per-byte cumulative advance table — the host's answer to the advance
-    /// measure request: `advances[i]` = laid-out width of `display[..i]` (len+1 entries; a
-    /// continuation byte repeats its lead's value). This is the metrics seam that makes
-    /// click→index (`0x77d0d0`), drag-select, and the scroll window engine-local — the real
-    /// client reads the same geometry off its embedded render object. Empty until answered.
+    /// The host-measured width of `display[..i]` per byte `i`, a continuation byte repeating its
+    /// lead's; hit-testing (`0x77d0d0`) and the scroll window read it. Empty until answered.
     pub advances: Vec<f32>,
-    /// Cache key of [`Self::advances`] (display text + font identity hash) — the same staleness
-    /// discipline as the FontString measure round-trip.
+    /// Hash of the display text and font [`Self::advances`] was measured for.
     pub advances_key: u64,
-    /// The wrapped-row starts of the DISPLAY string — answered with [`Self::advances`] by the
-    /// host, which runs the same wrap pass the draw uses. `rows[i]` is the byte where row `i`
-    /// begins; row `i` covers `rows[i]..rows[i+1]` (last row to end of display). Always at least
-    /// `[0]`; a single-line box stays exactly `[0]`. The 2-D caret/click law
-    /// ([`Self::caret_row_x`]/[`Self::index_at_pos`]) reads it; bytes swallowed at a break (the
-    /// dropped trailing separator, the `\n` itself) belong to the row they end.
+    /// The display byte each wrapped row starts at, measured by the host with the draw's wrap pass;
+    /// at least `[0]`. Bytes swallowed at a break (the space, the `\n`) belong to the row they end.
     pub rows: Vec<usize>,
-    /// The row pitch in px (the snapped font em — the same `N·S` block law the host's measure
-    /// uses), answered with [`Self::advances`]. `0.0` until answered.
+    /// The row pitch in pixels (the snapped font em), answered with the advances; 0 until then.
     pub cell_h: f32,
-    /// The `(row, x)` the last `OnCursorChanged` was fired with — the caret-flush edge's memory
-    /// (`0x77da80`, whose one caller `0x77d475` is gated on dirty bit 2, so the fire is per
-    /// *change*, not per frame). `None` = never fired, which is what makes the first flush after
-    /// a focus fire even though the caret is at the home position.
+    /// The `(row, x)` of the last `OnCursorChanged`, fired per change (`0x77da80`, dirty bit 2 at
+    /// `0x77d475`); `None` lets the first flush after focus fire with the caret at home.
     pub cursor_fired: Option<(usize, f32)>,
-    /// First visible byte of the display window (`E+0x348` display/scroll start index) — the
-    /// char-granular h-scroll. Clamped each read so the cursor stays inside the window
-    /// (`0x77da80`'s early-out hides the caret outside `[start, start+visible]`).
+    /// The first visible display byte of a single-line box (`E+0x348`), scrolled by whole chars
+    /// to keep the caret in view; `0x77da80` hides a caret outside the window.
     pub scroll_start: usize,
-    /// A LeftButton press landed inside the box and hasn't released (`E+0x364`
-    /// mouse-drag-active): every mouse move maps to a char index and extends the selection there,
-    /// cursor following (`0x77a860`).
+    /// A left-button press in the box is held (`E+0x364`); moves extend the selection (`0x77a860`).
     pub drag_active: bool,
-    /// Caret blink half-period in seconds (`E+0x370`; ctor default **0.5**, the XML `blinkSpeed`
-    /// attr overrides).
+    /// Caret blink half-period in seconds (`E+0x370`; ctor 0.5, XML `blinkSpeed`).
     pub blink_period: f32,
-    /// Blink accumulator (`E+0x374`): += dt while focused; crossing the period toggles
-    /// [`Self::caret_shown`] and resets.
+    /// Blink accumulator (`E+0x374`): grows while focused; crossing the period toggles the caret.
     pub blink_accum: f32,
-    /// The blink phase — caret visible this half-period. Every cursor/text/selection change
-    /// resets it to `true` with a fresh accumulator (the client's click path calls the dirty
-    /// flush's blink reset before placing the cursor).
+    /// The caret shows this half-period; every cursor, text or selection change turns it on.
     pub caret_shown: bool,
-    /// The selection highlight tint (`SetHighlightColor`, the `E+0x350` texture trio's color;
-    /// ctor default **0xFF606060** — opaque medium gray). RGBA 0..1.
+    /// The selection tint (`SetHighlightColor`), RGBA 0..1; the ctor default is `0xFF606060`.
     pub highlight_color: [f32; 4],
-    /// The justification bit word behind `Set/GetJustifyH` and `Set/GetJustifyV` — entries #12–#15
-    /// of the EditBox method table (`0x797990`/`0x797a50`/`0x797b10`/`0x797bd0`, tail-calling the
-    /// shared `0x79fc20`/`0x79fcb0`/`0x79fce0`/`0x79fd70`).
-    ///
-    /// **One dword, two axes** (`CSimpleFont+0x54` / `CSimpleFontString+0x120`), from the 6-entry
-    /// enum at `.rdata 0x811ad0`: bits 0–2 horizontal (`LEFT` 0x01, `CENTER` 0x02, `RIGHT` 0x04),
-    /// bits 3–5 vertical (`TOP` 0x08, `MIDDLE` 0x10, `BOTTOM` 0x20).
-    ///
-    /// **An EditBox's default is `0x211` — LEFT, not the generic CENTER.** The `CSimpleFont` ctor
-    /// default really is `0x212` (`CENTER | MIDDLE | 0x200`), but the EditBox constructor
-    /// *overrides* the horizontal axis immediately after linking its font instance —
-    /// `0x779bcd mov ecx,[edi+0x54]; and eax,~6; or eax,1; 0x779be4 mov [edi+0x54],eax` — so
-    /// `GetJustifyH()` on a fresh box answers **`"LEFT"`**. Bit `0x200` falls outside both axis
-    /// masks and neither accessor reads it, so only `0x11` is modelled. (This **corrected** our
-    /// first cut, which took the generic `0x212` and answered `"CENTER"`.)
-    ///
-    /// **Kept on the box, not on its text region.** Each font binding's shim hands the shared
-    /// implementation `[this+0x324]` — the box's implicit FontString, i.e. [`Self::text_region`] —
-    /// so on the reference these do write that string's justify field. But our EditBox draw law
-    /// seats that region's vertical justification by `multiLine` (TOP / MIDDLE) and its horizontal
-    /// one LEFT, and writing the region here would fight that law *and* be clobbered by the next
-    /// `SetMultiLine`.
-    ///
-    /// **The vertical half of that is now confirmed exactly right, and for a reason worth
-    /// keeping.** `CSimpleFontString+0x124` is a per-bit *inherit* mask over
-    /// `+0x120`, and `SetMultiLine 0x77a4a0` clears the whole vertical group `0x38` from it on
-    /// **both** legs while writing the V bits locally (multi-line → TOP, single-line → MIDDLE) —
-    /// and the EditBox ctor calls `SetMultiLine` unconditionally at birth (`0x779c2f`, with the
-    /// ctor's zero register). A census of all 256 `+0x124` operands image-wide found every
-    /// `CSimpleFontString` writer to be an AND: **nothing ever ORs an inherit bit back.** So
-    /// `SetJustifyV` writes the instance and is masked out at `0x77086e`, never reaching the
-    /// rendered text, while `GetJustifyV` reads the instance (`0x79fd73`) and echoes it back:
-    /// **the getter and the pixels disagree permanently, by construction, on the real client too.**
-    /// Our rendered V justify is decided solely by `multiLine`, which is the same rule.
-    ///
-    /// **The horizontal half stays open, and is deliberately not guessed.** `SetMultiLine` never
-    /// clears the `0x7` bits, so `SetJustifyH`'s value *does* reach the FontString's `+0x120` —
-    /// but whether the editbox's own draw `0x77da80` reads it for placement, rather than
-    /// left-anchoring at the insets rect the way the reference's windowed draw describes, is
-    /// untraced.
-    /// Verifying that the value propagates is not verifying that the draw honours it, so the
-    /// reading that changes no pixels is the one taken and the question is named. It is the whole
-    /// visible difference for `AceGUIWidget-Slider.lua:210`'s `editbox:SetJustifyH("CENTER")`
-    /// (3 corpus addons), whose call now round-trips either way.
+    /// The bits of `Set/GetJustifyH` and `Set/GetJustifyV` (`0x797990`-`0x797bd0`), kept on the
+    /// box and not drawn. For V that is the reference: `SetMultiLine` (`0x77a4a0`) makes the
+    /// text's V bits local, so a `SetJustifyV` is masked out (`0x77086e`) and only the getter sees
+    /// it. Whether the draw (`0x77da80`) reads H is untraced.
     pub justify: u32,
 }
 
 impl EditBoxState {
-    /// The horizontal axis mask (bits 0–2) — `SetJustifyH`'s `(cur & ~7) | (parsed & 7)`.
+    /// The horizontal justify bits (0-2).
     pub const JUSTIFY_H_MASK: u32 = crate::justify::H_MASK;
-    /// The vertical axis mask (bits 3–5) — `SetJustifyV`'s.
+    /// The vertical justify bits (3-5).
     pub const JUSTIFY_V_MASK: u32 = crate::justify::V_MASK;
 
-    /// Parse a justify token to its bit — [`crate::justify::parse_bits`]. `None` = no match, which
-    /// is what makes the caller raise `Usage: %s:SetJustifyH("justify")`; the reference checks this
-    /// one, unlike `SetTextColor`.
+    /// A justify token's bit; `None` makes the caller raise the reference's
+    /// `Usage: %s:SetJustifyH("justify")`.
     pub fn justify_bit(token: &str) -> Option<u32> {
         crate::justify::parse_bits(token)
     }
 
-    /// Replace one axis's bits with `parsed`'s — [`crate::justify::set_axis`].
-    ///
-    /// **The verified trap this reproduces:** `SetJustifyH("TOP")` *parses* (0x08) but
-    /// `0x08 & 0x07 == 0`, so it **clears** justifyH and a later `GetJustifyH()` answers
-    /// `"UNKNOWN"` — no error is raised. A plausible implementation that maps unknown-to-CENTER
-    /// silently answers something the client never would; the FontString and `<Font>` tables both
-    /// did exactly that until this law was lifted out of here and shared with them.
+    /// Replace one axis's bits with `parsed`'s. `SetJustifyH("TOP")` parses but clears the H bits,
+    /// so `GetJustifyH()` then answers `"UNKNOWN"`, with no error.
     pub fn set_justify_axis(&mut self, mask: u32, parsed: u32) {
         self.justify = crate::justify::set_axis(self.justify, mask, parsed);
     }
 
-    /// The token for one axis — [`crate::justify::name_of`].
+    /// The token for one axis.
     pub fn justify_token(&self, mask: u32) -> &'static str {
         crate::justify::name_of(self.justify, mask)
     }
@@ -291,8 +145,8 @@ impl Default for EditBoxState {
             cursor: 0,
             sel_start: 0,
             sel_end: 0,
-            // `flags = 1` at construction (`0x779a29`/`0x779a2e`): bit0 (autoFocus) SET, every
-            // other flag clear. A box that says nothing self-focuses when shown.
+            // The ctor sets the flags to 1 (`0x779a29`/`0x779a2e`), autoFocus alone, so a box
+            // that says nothing self-focuses when shown.
             auto_focus: true,
             multi_line: false,
             numeric: false,
@@ -316,21 +170,19 @@ impl Default for EditBoxState {
             blink_period: 0.5,
             blink_accum: 0.0,
             caret_shown: true,
-            // Filled by `Arena::create`'s ctor pass — `Default` cannot reach the arena, and a
-            // handle-less default is what a not-yet-created box has.
+            // Filled by `WidgetArena::create`'s ctor pass, which `Default` cannot reach.
             selection_regions: [None; 3],
             caret_region: None,
             highlight_color: [96.0 / 255.0, 96.0 / 255.0, 96.0 / 255.0, 1.0],
-            // The EditBox ctor's `0x211` minus the unread bit 0x200 — `LEFT | MIDDLE`. LEFT, not
-            // the generic font default CENTER: `0x779be4` overrides the H axis at construction.
+            // The ctor's `0x211` less the unread bit 0x200: LEFT | MIDDLE, since the ctor
+            // overrides the font default's CENTER (`0x779be4`).
             justify: 0x01 | 0x10,
         }
     }
 }
 
 impl EditBoxState {
-    /// `AddHistoryLine`: append (drop-oldest past [`Self::history_max`]) and end any browse in
-    /// progress. Empty lines and a zero cap are no-ops.
+    /// `AddHistoryLine`: append the line, dropping the oldest past the cap, and end any browse.
     pub fn add_history_line(&mut self, line: &str) {
         if self.history_max == 0 || line.is_empty() {
             return;
@@ -344,10 +196,8 @@ impl EditBoxState {
         self.history_draft = None;
     }
 
-    /// One UP (`older = true`) or DOWN step through the history. Returns the text the box should
-    /// now show: entering browse mode stashes the live draft; stepping past the newest entry
-    /// leaves browse mode and returns the draft. `None` = nothing to do (no history / already at
-    /// the oldest / not browsing on DOWN).
+    /// One UP (`older`) or DOWN step, returning the text to show: the first UP stashes the draft,
+    /// and DOWN past the newest entry restores it.
     pub fn history_step(&mut self, older: bool) -> Option<String> {
         if self.history.is_empty() {
             return None;
@@ -358,11 +208,11 @@ impl EditBoxState {
                 self.history_pos = Some(self.history.len() - 1);
             }
             (None, false) => return None,
-            (Some(0), true) => return None, // already at the oldest — hold
+            (Some(0), true) => return None, // at the oldest: hold
             (Some(p), true) => self.history_pos = Some(p - 1),
             (Some(p), false) if p + 1 < self.history.len() => self.history_pos = Some(p + 1),
             (Some(_), false) => {
-                // Past the newest — back to the stashed live line.
+                // Past the newest: back to the stashed draft.
                 self.history_pos = None;
                 return Some(self.history_draft.take().unwrap_or_default());
             }
@@ -370,9 +220,7 @@ impl EditBoxState {
         self.history_pos.map(|p| self.history[p].clone())
     }
 
-    /// End any history browse (the recalled line becomes an ordinary draft; the stash is
-    /// dropped). Called on typed edits, [`Self::add_history_line`], and focus gain — never on
-    /// programmatic `SetText` (see [`Self::history_pos`]).
+    /// End any history browse; `SetText` must not call this (see [`Self::history_pos`]).
     pub fn end_history_browse(&mut self) {
         self.history_pos = None;
         self.history_draft = None;
@@ -380,9 +228,8 @@ impl EditBoxState {
 
     // ── selection / geometry law ─────────────────────────────────────────────────────────────
 
-    /// The DISPLAY string — what the box draws, what the advance table indexes, and what
-    /// hit-tests run against: the text itself, or one `'*'` per character under `password`
-    /// (the `E+0x334` mask; both draw `0x77da80` and hit-test `0x77d0d0` branch on the flag).
+    /// What the box draws and hit-tests: the text, or one `*` per character under `password`
+    /// (`E+0x334`; the draw `0x77da80` and the hit-test `0x77d0d0` both branch on the flag).
     pub fn display(&self) -> String {
         if self.password {
             "*".repeat(self.text.chars().count())
@@ -391,8 +238,7 @@ impl EditBoxState {
         }
     }
 
-    /// TEXT byte offset → DISPLAY byte offset (identity unless `password`, where each char is
-    /// one `'*'` byte).
+    /// A text byte offset as a display byte offset.
     pub fn text_to_display(&self, byte: usize) -> usize {
         if self.password {
             self.text[..byte.min(self.text.len())].chars().count()
@@ -401,7 +247,7 @@ impl EditBoxState {
         }
     }
 
-    /// DISPLAY byte offset → TEXT byte offset (inverse of [`Self::text_to_display`]).
+    /// A display byte offset as a text byte offset.
     pub fn display_to_text(&self, dbyte: usize) -> usize {
         if self.password {
             self.text
@@ -413,24 +259,16 @@ impl EditBoxState {
         }
     }
 
-    /// The char-boundary DISPLAY index nearest pixel `x` (x measured from the text origin, i.e.
-    /// the advance table's zero — the caller adds the scroll window's offset first). Walks the
-    /// cumulative table over char boundaries; nearest-boundary rounding (INFERRED — `0x77d0d0`'s
-    /// exact rounding is undiffed; nearest is the Windows-edit convention). Empty table (host
-    /// hasn't answered yet) → end of text.
+    /// The display index nearest pixel `x` from the text origin, the caller adding the scroll
+    /// offset. It rounds to the nearest stop; `0x77d0d0`'s rounding is untraced.
     pub fn index_at_x(&self, x: f32) -> usize {
         let display = self.display();
         self.index_at_x_in(x, 0, display.len(), &display)
     }
 
-    /// [`Self::index_at_x`] restricted to the boundary range `[start, end]` of `display` —
-    /// the per-row walk of the 2-D law ([`Self::index_at_pos`]). `x` is measured from
-    /// `advances[start]`.
-    ///
-    /// The candidates are the **reachable cursor stops**, not every char boundary: the client's
-    /// hit-test converts its glyph index through the same token walk everything else uses, with
-    /// `atomicLinks = 0` (`0x77d0d0`, `6a 00` @`0x77d2f6`), so a click stops on each visible
-    /// character of a link's text but can never land inside an escape (decision 1077).
+    /// [`Self::index_at_x`] within `[start, end]`, `x` measured from `advances[start]`. It lands
+    /// only on cursor stops: the hit-test walks tokens with `atomicLinks = 0` (`0x77d0d0`, at
+    /// `0x77d2f6`), so a click reaches each visible character of a link but never an escape.
     fn index_at_x_in(&self, x: f32, start: usize, end: usize, display: &str) -> usize {
         if self.advances.len() != display.len() + 1 {
             return end;
@@ -439,7 +277,7 @@ impl EditBoxState {
         let mut prev = start;
         for b in self.stops_in(start, end, display) {
             if self.advances[b] - origin >= x {
-                // x lies between boundaries `prev` and `b` — pick the nearer.
+                // x lies between stops `prev` and `b`: pick the nearer.
                 return if x - (self.advances[prev] - origin) <= (self.advances[b] - origin) - x {
                     prev
                 } else {
@@ -451,8 +289,8 @@ impl EditBoxState {
         end
     }
 
-    /// The cursor stops strictly inside `(start, end]` of `display`, in order — the mouse-path walk
-    /// of [`crate::markup::ClassMap::advance`] (`atomic_links = false`). Always ends at `end`.
+    /// The cursor stops in `(start, end]`, in order, walked with links not atomic (the mouse walk);
+    /// always ends at `end`.
     fn stops_in(&self, start: usize, end: usize, display: &str) -> Vec<usize> {
         let map = crate::markup::ClassMap::new(display);
         let mut stops = Vec::new();
@@ -471,9 +309,7 @@ impl EditBoxState {
         stops
     }
 
-    /// The wrapped row index containing DISPLAY byte `b` — the last row whose start is ≤ `b`
-    /// (a byte exactly on a wrap boundary belongs to the row it *starts*, so the caret lands at
-    /// the head of the new row, where typing continues).
+    /// The wrapped row holding display byte `b`; a byte on a wrap boundary heads the new row.
     pub fn row_of(&self, b: usize) -> usize {
         match self.rows.binary_search(&b) {
             Ok(i) => i,
@@ -481,17 +317,14 @@ impl EditBoxState {
         }
     }
 
-    /// Row `i`'s DISPLAY byte range `[start, end)` — `end` is the next row's start (the swallowed
-    /// break bytes live at the tail of this range), or the display length for the last row.
+    /// Row `i`'s display byte range, with the break bytes it swallowed at its tail.
     pub fn row_range(&self, i: usize, display_len: usize) -> (usize, usize) {
         let start = self.rows.get(i).copied().unwrap_or(0);
         let end = self.rows.get(i + 1).copied().unwrap_or(display_len);
         (start, end.max(start))
     }
 
-    /// The caret's wrapped position: `(row, x)` with `x` the advance from the row's start —
-    /// the 2-D twin of the single-line `advances[cursor]` read. Row 0 / x 0 until the host has
-    /// answered the advance table.
+    /// The caret's wrapped `(row, x)`, `x` measured from the row's start.
     pub fn caret_row_x(&self, cursor_d: usize) -> (usize, f32) {
         let display = self.display();
         if self.advances.len() != display.len() + 1 {
@@ -503,12 +336,8 @@ impl EditBoxState {
         (row, self.advances[cursor_d] - self.advances[start])
     }
 
-    /// The char-boundary DISPLAY index nearest point `(x, y)` — the multiline click law
-    /// (`0x77d0d0`'s 2-D half): `y` (px down from the text region's top) picks the row by the
-    /// answered pitch, `x` walks that row's advances. Degrades to the 1-D walk while the rows/
-    /// pitch are unanswered (single-line boxes stay exactly the old behavior). The row's END
-    /// boundary excludes trailing break bytes only in x (clicking past a wrapped row's ink lands
-    /// at the wrap point).
+    /// The display index nearest `(x, y)` (`0x77d0d0`): `y`, down from the text top, picks the row
+    /// by the pitch and `x` walks that row. Without rows it is [`Self::index_at_x`].
     pub fn index_at_pos(&self, x: f32, y: f32) -> usize {
         let display = self.display();
         if self.rows.len() <= 1 || self.cell_h <= 0.0 {
@@ -525,9 +354,8 @@ impl EditBoxState {
         )
     }
 
-    /// The word-jump target from the cursor (Ctrl+arrow — the client walks its per-byte class
-    /// array `E+0x330`; benilla approximates the classes with alphanumeric runs, INFERRED):
-    /// forward = end of the current/next alnum run; back = start of the current/previous one.
+    /// The Ctrl+arrow target. A word here is a run of ASCII alphanumerics or non-ASCII bytes; the
+    /// reference walks its per-byte class array (`E+0x330`).
     pub fn word_boundary(&self, forward: bool) -> usize {
         let bytes = self.text.as_bytes();
         let is_word = |b: u8| b.is_ascii_alphanumeric() || b >= 0x80;
@@ -552,21 +380,16 @@ impl EditBoxState {
         }
     }
 
-    /// Show the caret and restart its blink cycle — the client's dirty flush resets the blink on
-    /// every cursor/text/selection change (and the click path calls it before placing the cursor).
+    /// Show the caret and restart its blink, as the client's dirty flush does on every change.
     pub fn reset_blink(&mut self) {
         self.caret_shown = true;
         self.blink_accum = 0.0;
     }
 
-    /// Clamp the scroll window (`E+0x348`, a DISPLAY-byte start index) so the caret stays inside
-    /// `avail` pixels: window start ≤ cursor, and the cursor's advance fits within the window's
-    /// width. Whole-char steps (the client scrolls its display window by characters, never
-    /// sub-pixel). No-op until the host has answered the advance table.
+    /// Scroll the single-line window (`E+0x348`) by whole chars to keep the caret in `avail` px.
     pub fn clamp_scroll(&mut self, avail: f32) {
         if self.multi_line {
-            // A multiline box wraps instead of windowing (the client's h-scroll `E+0x348` is the
-            // single-line mechanism; multiline scrolls via its parent ScrollFrame).
+            // A multiline box wraps; its parent ScrollFrame scrolls it.
             self.scroll_start = 0;
             return;
         }
@@ -575,7 +398,7 @@ impl EditBoxState {
             return;
         }
         let cursor_d = self.text_to_display(self.cursor);
-        // Snap a stale start (text shrank / mid-char) back onto a boundary.
+        // Snap a stale start back onto a char boundary.
         self.scroll_start = self.scroll_start.min(display.len());
         while self.scroll_start > 0 && !display.is_char_boundary(self.scroll_start) {
             self.scroll_start -= 1;
@@ -599,30 +422,23 @@ impl EditBoxState {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
-// The editing law — pure over the state, no Lua, no widget tree
+// The editing law: pure over the state, no Lua, no widget tree
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 //
-// These used to live in `script::editbox` welded to the Lua layer, which meant the *only* way to
-// get the byte-verified box law was to be a FrameXML EditBox. The glue screens (login, character
-// create, the delete dialog) therefore each grew their own three-case imitation of it — append a
-// char, Backspace, Tab — with no caret movement, no selection, and no clipboard (decision 0704).
-// The law lives here now, and `script::editbox` is a thin wrapper that calls these and fires the
-// Lua events an [`EditOutcome`] tells it to. Anything with a `&mut EditBoxState` gets the real
-// law, whether or not there is a Lua VM anywhere near it.
+// `script::editbox` wraps these and fires the Lua events an `EditOutcome` names; the glue
+// screens use them with no Lua at all.
 
-/// What a pure edit changed, so a caller with events to fire knows which to fire. The FrameXML
-/// wrapper turns this into `OnTextChanged`/`OnSpacePressed`; the glue screens ignore it.
+/// What an edit changed, for the FrameXML wrapper's `OnTextChanged` and `OnSpacePressed` fires.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub struct EditOutcome {
-    /// The text buffer changed — the `OnTextChanged` trigger.
+    /// The text changed: `OnTextChanged`.
     pub text_changed: bool,
-    /// Spaces this edit inserted — the `OnSpacePressed` fire count. Only an insert of typed text
-    /// reports these; a paste deliberately does not (a paste is not a typed space).
+    /// Typed spaces inserted, one `OnSpacePressed` each; a paste reports none.
     pub spaces: usize,
 }
 
 impl EditOutcome {
-    /// A change that fires `OnTextChanged` and nothing else.
+    /// An outcome with no typed spaces.
     fn changed(text_changed: bool) -> Self {
         EditOutcome {
             text_changed,
@@ -632,17 +448,13 @@ impl EditOutcome {
 }
 
 impl EditBoxState {
-    /// Apply one semantic [`EditAction`] — the single entry point the host's per-OS chord table
-    /// feeds (decision 0301: the host owns *which chord*, this owns *what it does*).
+    /// Apply one [`EditAction`] from the host's per-OS chord table.
     pub fn apply(&mut self, action: EditAction) -> EditOutcome {
         match action {
             EditAction::Move { unit, back, extend } => {
                 match unit {
-                    // No flag test here any more. The alt-arrow gate is on the KEY, not on the
-                    // action — with the flag set the box never sees the arrow at all, because the
-                    // host declines it before the chord is dispatched (`UiScript::
-                    // editbox_alt_arrow_fallthrough`). Anything that reaches this far was either
-                    // Alt-held or not an arrow, and both move the caret normally.
+                    // The alt-arrow gate is on the key: the host declines a gated arrow before
+                    // it becomes an action (`UiScript::editbox_alt_arrow_mode`).
                     EditUnit::Char => self.move_by_char(!back, extend),
                     EditUnit::Word => self.move_by_word(!back, extend),
                     EditUnit::Edge => self.move_to_edge(!back, extend),
@@ -664,27 +476,23 @@ impl EditBoxState {
                 self.highlight_text(0, -1);
                 EditOutcome::default()
             }
-            // History recall is the caller's: it routes through the SetText path so the FrameXML
-            // box also fires `OnTextSet`. `history_step` is the state half.
+            // The caller recalls history through `SetText`, so `OnTextSet` fires.
             EditAction::HistoryPrev | EditAction::HistoryNext => EditOutcome::default(),
         }
     }
 
-    /// Insert `ins` at the cursor (`0x77bee0`): replace any selection first; `numeric` aborts the
-    /// insert **wholesale** on any non-digit (not per-char filtering — the char filter `0x77bf41`);
-    /// splice, advance the caret, enforce the caps.
+    /// Insert at the cursor (`0x77bee0`), replacing any selection; `numeric` refuses the whole
+    /// insert on any non-digit (`0x77bf41`).
     pub fn insert(&mut self, ins: &str) -> EditOutcome {
         if self.numeric && !ins.chars().all(|c| c.is_ascii_digit()) {
             return EditOutcome::default();
         }
-        // Refused outright with the caret strictly inside a hyperlink — the opening guard of
-        // `0x77bee0` (decision 1077). Only the mouse can put the caret there (the keyboard treats a
-        // link as one unit), and the client then silently swallows the typing rather than letting
-        // it split `|Hitem:…|h[Name]|h` into something unclickable.
+        // Typing with the caret inside a hyperlink, where only the mouse can put it, is
+        // swallowed: the opening guard of `0x77bee0`.
         if !crate::markup::ClassMap::new(&self.text).insert_allowed(self.cursor) {
             return EditOutcome::default();
         }
-        self.end_history_browse(); // a typed edit turns a recalled line into an ordinary draft
+        self.end_history_browse();
         self.delete_selection();
         self.text.insert_str(self.cursor, ins);
         self.cursor += ins.len();
@@ -697,9 +505,8 @@ impl EditBoxState {
         }
     }
 
-    /// Insert OS-clipboard text: [`insert`](Self::insert) with the paste sanitation — every control
-    /// character is dropped, except `\n` into a multiline box. Reports no spaces: a paste is not a
-    /// typed space, so it fires no `OnSpacePressed`.
+    /// Insert clipboard text with its control characters dropped, bar `\n` in a multiline box; a
+    /// paste fires no `OnSpacePressed`.
     pub fn paste(&mut self, text: &str) -> EditOutcome {
         let cleaned: String = text
             .chars()
@@ -711,27 +518,16 @@ impl EditBoxState {
         EditOutcome::changed(self.insert(&cleaned).text_changed)
     }
 
-    /// `SetText` (`0x77be00`) is a clear-all followed by `Insert`, not a plain assignment, and the
-    /// order of its three parts is load-bearing (decision 1831):
-    ///
-    /// 1. the selection collapses **unconditionally**, before anything is compared — an identical
-    ///    `SetText` still drops a highlight;
-    /// 2. a case-sensitive equality test then short-circuits (`SStrCmp` at `0x77be4b`), skipping the
-    ///    clear-all, the insert and both fires — so the caller fires nothing;
-    /// 3. the changing leg is `0x77c500` (delete the whole buffer) then `0x77bee0` (`Insert`), which
-    ///    means `SetText` **inherits `Insert`'s gates**. The one that shows is `numeric`: the gate
-    ///    abandons the insert wholesale on any non-digit, and the clear-all has already run, so the
-    ///    box is left **empty** rather than unchanged. `SetNumber(-5)` and `SetNumber(0.8)` both
-    ///    empty a `numeric` box, because `-` and `.` are not digits.
-    ///
-    /// The clear-all raises the `textChanged` dirty bit on every path it reaches, so the aborted
-    /// insert still reports a change and still fires — reporting `""`.
+    /// `SetText` (`0x77be00`), in order: collapse the selection even when the text is equal; stop
+    /// if equal (`SStrCmp`, case-sensitive, `0x77be4b`), firing nothing; else clear all
+    /// (`0x77c500`), then `Insert` (`0x77bee0`) with its gates. So a `numeric` box given a
+    /// non-digit, as by `SetNumber(-5)`, ends empty and still reports a change.
     pub fn set_text(&mut self, s: &str) -> bool {
-        self.collapse(); // (1) unconditional, ahead of the comparison
+        self.collapse(); // even when the text is equal
         if self.text == s {
-            return false; // (2)
+            return false;
         }
-        // (3) the clear-all, then Insert — whose `numeric` gate refuses the whole string.
+        // Clear all, then Insert, whose `numeric` gate refuses the whole string.
         self.text = if self.numeric && !s.chars().all(|c| c.is_ascii_digit()) {
             String::new()
         } else {
@@ -744,8 +540,7 @@ impl EditBoxState {
         true
     }
 
-    /// The selected substring, or `None` with no selection (Ctrl+C, `0x77e1d0`). A password box
-    /// yields its **mask run**, never the real text — the client copies a placeholder.
+    /// The selection for Ctrl+C (`0x77e1d0`); a password box yields its mask, never the text.
     pub fn selected_text(&self) -> Option<String> {
         if self.sel_start == self.sel_end {
             return None;
@@ -770,9 +565,7 @@ impl EditBoxState {
         Some(taken)
     }
 
-    /// `HighlightText` (`0x77cca0`), the client's exact clamp: `start = clamp(start, 0..=len)`;
-    /// `end = (end < 0 || end > len) ? len : end`; then `if end < start { end = len }` — so
-    /// `(0, -1)` selects all. Byte offsets, snapped to char boundaries.
+    /// `HighlightText` (`0x77cca0`) with the client's clamp, so `(0, -1)` selects all.
     pub fn highlight_text(&mut self, start: i64, end: i64) {
         let len = self.text.len() as i64;
         let s = start.clamp(0, len);
@@ -786,8 +579,7 @@ impl EditBoxState {
         self.reset_blink();
     }
 
-    /// BACKSPACE / DELETE: the selection when there is one, else the char before (`forward=false`)
-    /// or after the caret. `true` when anything was removed.
+    /// Backspace (`forward = false`) or Delete: the selection if any, else one step.
     pub fn delete_dir(&mut self, forward: bool) -> bool {
         self.end_history_browse();
         let did = 'del: {
@@ -795,9 +587,8 @@ impl EditBoxState {
                 self.delete_selection();
                 break 'del true;
             }
-            // One ATOMIC token step, then the endpoint snap — `0x77c280(±1)` passes
-            // `atomicLinks = 1` (`6a 01` @`0x77c2a3`) and hands the span to `0x77c510`, so one
-            // BACKSPACE takes a whole item link, escapes and trailing `|r` included (1077).
+            // One atomic token step (`0x77c280`, `atomicLinks = 1` at `0x77c2a3`), then the span
+            // snap (`0x77c510`): one Backspace takes a whole item link, escapes and `|r` included.
             let target = crate::markup::ClassMap::new(&self.text).advance(
                 self.cursor,
                 if forward { 1 } else { -1 },
@@ -815,8 +606,7 @@ impl EditBoxState {
         did
     }
 
-    /// Word/edge delete: the selection first when one exists, else the span between the caret and
-    /// `target`. `true` when anything was removed.
+    /// Word or edge delete: the selection if any, else the span from the caret to `target`.
     pub fn delete_to(&mut self, target: usize) -> bool {
         self.end_history_browse();
         let did = if self.sel_start != self.sel_end {
@@ -837,13 +627,11 @@ impl EditBoxState {
         did
     }
 
-    /// LEFT/RIGHT one char: `extend` drags the selection from its fixed anchor; otherwise the caret
-    /// collapses onto the selection edge (when there is one) or steps one char.
+    /// Left or Right one step, `extend` dragging the selection; without it, a selection collapses
+    /// to its edge instead.
     pub fn move_by_char(&mut self, right: bool, extend: bool) {
-        // One TOKEN step, links atomic — `0x77bb30(±1, atomicLinks = 1)`, which every arrow path
-        // reaches (`6a 01` @`0x77c6d2`). So one press crosses a whole `|cff…|Hitem:…|h[Name]|h|r`
-        // rather than stepping into the middle of an escape, and Shift+arrow selects all of it
-        // (decision 1077). Not a char step: an escape byte is not a cursor position.
+        // One token step, links atomic (`0x77bb30`, `atomicLinks = 1` at `0x77c6d2`): a press
+        // crosses a whole link, never into an escape, and Shift+arrow selects all of it.
         let step = |s: &str, i: usize| {
             crate::markup::ClassMap::new(s).advance(i, if right { 1 } else { -1 }, true)
         };
@@ -861,10 +649,8 @@ impl EditBoxState {
         self.reset_blink();
     }
 
-    /// Ctrl/Option+arrow: the caret to the next [`word_boundary`](Self::word_boundary) — reached as
-    /// a **loop of single atomic steps** (`0x77c8c0`/`0x77c7a0` loop `0x77c6b0`), so the landing
-    /// place is always a reachable stop even when the word target falls inside an escape or
-    /// part-way through a link (decision 1077).
+    /// Ctrl/Option+arrow: the caret to the [`word_boundary`](Self::word_boundary) by single atomic
+    /// steps (`0x77c8c0`/`0x77c7a0` loop `0x77c6b0`), so it always lands on a reachable stop.
     pub fn move_by_word(&mut self, right: bool, extend: bool) {
         let word = self.word_boundary(right);
         let mut target = self.cursor;
@@ -891,8 +677,7 @@ impl EditBoxState {
         self.move_caret_to(target, extend);
     }
 
-    /// Place the caret at `target`, extending the selection from its fixed anchor when `extend`.
-    /// The shared tail of every non-char move (and of a mouse click/drag).
+    /// Place the caret at `target`, extending the selection from its anchor when `extend`.
     pub fn move_caret_to(&mut self, target: usize, extend: bool) {
         let target = snap_down(&self.text, target.min(self.text.len()));
         if extend {
@@ -906,7 +691,6 @@ impl EditBoxState {
         self.reset_blink();
     }
 
-    /// Delete the current selection: remove `[min, max)` and collapse the caret to its left edge.
     fn delete_selection(&mut self) {
         if self.sel_start == self.sel_end {
             return;
@@ -918,10 +702,8 @@ impl EditBoxState {
         self.delete_span(a..b);
     }
 
-    /// Remove a byte span, first widening it out of any hyperlink it cuts — `0x77c510` (decision
-    /// 1077), the second guarantee under the atomic walk: a mouse-drag selection that clips half an
-    /// item link still deletes the whole `|c…|H…|h[text]|h|r` unit rather than leaving orphaned
-    /// escape bytes. The caret collapses to the widened span's left edge.
+    /// Remove a byte span widened to whole hyperlinks (`0x77c510`), so a drag selection that clips
+    /// a link deletes all of it; the caret lands at the span's start.
     fn delete_span(&mut self, span: std::ops::Range<usize>) {
         let span = crate::markup::ClassMap::new(&self.text).snap_delete_range(span);
         self.cursor = span.start;
@@ -929,15 +711,14 @@ impl EditBoxState {
         self.collapse();
     }
 
-    /// Collapse the selection onto the caret — the client's own `0x77ccf0`, which every delete
-    /// path runs and which a screen losing the keyboard runs on the box it is leaving.
+    /// Collapse the selection onto the caret (`0x77ccf0`), as every delete does and as a screen
+    /// losing the keyboard does to the box it leaves.
     pub fn collapse(&mut self) {
         self.sel_start = self.cursor;
         self.sel_end = self.cursor;
     }
 
-    /// The fixed end of the selection while extending — the endpoint that is *not* the caret (the
-    /// caret itself when nothing is selected).
+    /// The selection end that is not the caret.
     fn selection_anchor(&self) -> usize {
         if self.sel_start == self.cursor {
             self.sel_end
@@ -946,14 +727,12 @@ impl EditBoxState {
         }
     }
 
-    /// Set the selection to `[min(a,b), max(a,b)]`.
     fn set_span(&mut self, a: usize, b: usize) {
         self.sel_start = a.min(b);
         self.sel_end = a.max(b);
     }
 
-    /// Enforce the length caps after an edit (`0x77c02d`): trim whole chars from the end while over
-    /// `maxBytes`, then while over `maxLetters`; clamp caret/selection back into the buffer.
+    /// After an edit, trim from the end to `maxBytes`, then `maxLetters` (`0x77c02d`).
     fn enforce_caps(&mut self) {
         if let Some(mb) = self.max_bytes {
             while self.text.len() > mb {
@@ -961,15 +740,9 @@ impl EditBoxState {
             }
         }
         if self.max_letters > 0 {
-            // LETTERS, not chars: `0x77bc80` counts classes 2, 3 and 6 only, so a 48-byte item link
-            // costs 14 against `maxLetters` — its visible `[Chipped Claw]` and nothing more
-            // (decision 1077). Counting raw chars made a 255-letter chat line fill up three times
-            // too fast once it held links.
-            //
-            // The trim pops through `0x77c280(-1)` — the BACKSPACE primitive, `atomicLinks = 1` —
-            // re-counting the whole buffer after every pop (`0x77c0e4`). So an over-long buffer
-            // sheds a whole hyperlink in one bite, exactly as a keypress would, and can never shear
-            // an escape in half.
+            // Letters, not chars: `0x77bc80` counts classes 2, 3 and 6, so an item link costs only
+            // its visible name. The trim is the Backspace step (`0x77c280(-1)`, links atomic),
+            // re-counting after each pop (`0x77c0e4`), so it sheds a whole link at once.
             loop {
                 let map = crate::markup::ClassMap::new(&self.text);
                 if map.num_letters() <= self.max_letters {
@@ -989,7 +762,7 @@ impl EditBoxState {
     }
 }
 
-/// The byte offset of the char boundary at or below `i` (identity if `i` is already on one).
+/// The char boundary at or below `i`.
 fn snap_down(s: &str, i: usize) -> usize {
     let mut i = i.min(s.len());
     while i > 0 && !s.is_char_boundary(i) {
@@ -1019,7 +792,7 @@ mod row_law_tests {
     fn the_caret_seats_by_row_and_row_local_x() {
         let eb = two_row_box();
         assert_eq!(eb.caret_row_x(5), (0, 35.0));
-        // A cursor exactly on the wrap boundary heads the NEW row (typing continues there).
+        // A cursor on the wrap boundary heads the new row.
         assert_eq!(eb.caret_row_x(10), (1, 0.0));
         assert_eq!(eb.caret_row_x(15), (1, 35.0));
     }
@@ -1027,7 +800,7 @@ mod row_law_tests {
     #[test]
     fn a_click_picks_its_row_then_walks_it() {
         let eb = two_row_box();
-        // Row 1 (y past one pitch), x 21 → boundary 3 within the row → byte 13.
+        // Row 1 (y past one pitch), x 21: the row's third stop, byte 13.
         assert_eq!(eb.index_at_pos(21.0, 20.0), 13);
         // Above the block clamps to row 0; below clamps to the last row.
         assert_eq!(eb.index_at_pos(0.0, -5.0), 0);
diff --git a/crates/benilla-ui/src/widget/kinds/messageframe.rs b/crates/benilla-ui/src/widget/kinds/messageframe.rs
index 8dd25542..48a767c9 100644
--- a/crates/benilla-ui/src/widget/kinds/messageframe.rs
+++ b/crates/benilla-ui/src/widget/kinds/messageframe.rs
@@ -1,105 +1,60 @@
 use std::collections::VecDeque;
 
-/// One line held in a [`ScrollingMessageState`] ring — its text, its already-quantized color, its
-/// live fade state (a per-line snapshot of the frame's `timeVisible`/`fadeDuration` at insert,
-/// MessageData `+0xc`/`+0x10`), and its host-measured wrapped row count (the message-line half of
-/// the measure round-trip — a long chat line occupies as many display rows as it wraps into, so the
-/// bands above it shift up by real content height).
+/// One message line: its text, quantized color, own fade countdowns (the record's `+0xc`/`+0x10`
+/// snapshots of `timeVisible`/`fadeDuration`) and host-measured row count.
 #[derive(Clone, Debug, PartialEq)]
 pub struct MessageLine {
-    /// The line text (already formatted app-side: `[Name]: text`, `Name yells: text`, …).
+    /// The line as printed, already formatted by the caller.
     pub text: String,
-    /// The RGB the line draws at, **byte-quantized** at insert (`AddMessage` `trunc(x*255+0.5)`,
-    /// round-half-up; alpha is never stored — it is forced opaque and then driven by the fade).
+    /// The line's RGB, byte-quantized at insert ([`quantize_u8`]).
     pub color: [u8; 3],
-    /// `AddMessage`'s fifth argument — the chat-type index the line was printed under
-    /// (`GetChatTypeIndex`), so `UpdateColorByID` can find every line of a type when
-    /// `UPDATE_CHAT_COLOR` lands. 0 for a line printed without one.
+    /// `AddMessage`'s fifth argument, the chat-type id `UpdateColorByID` matches; 0 when absent.
     pub id: u32,
-    /// Remaining phase-1 countdown (the `timeVisible` snapshot ticking down); while `> 0` the line
-    /// holds full alpha.
+    /// Seconds left before the fade starts, from the `timeVisible` snapshot.
     pub time_left: f32,
-    /// Remaining phase-2 countdown (the `fadeDuration` snapshot). Once `time_left` hits `0` this
-    /// counts down and drives [`Self::alpha`].
+    /// Seconds of fade left, from the `fadeDuration` snapshot; counts once `time_left` is spent.
     pub fade_left: f32,
-    /// The current display alpha in `[0, 1]`. Phase 1 leaves it at whatever `AddMessage` set —
-    /// forced opaque on a ScrollingMessageFrame (`792add: or edi,0xffffff00`), the caller's real
-    /// alpha arg on a MessageFrame (`795752`, default 1.0) — and phase 2 **overwrites** it with the
-    /// byte-quantized ramp `trunc(remaining/fadeDuration*255)`, the client's own store into the
-    /// line's alpha byte (`0x788547` / `786364`→`[edi+0xb]`). `0` once fully faded — in a
-    /// ScrollingMessageFrame the line stays in the ring (a slot is freed only by drop-oldest /
-    /// `SetMaxLines`) and merely draws nothing, its rows still holding their place; a MessageFrame
-    /// has no ring, so its retire helper (`0x786570`) frees the line outright and the rest re-pack.
+    /// The display alpha: `AddMessage`'s (opaque on a ScrollingMessageFrame, `0x792add`; the alpha
+    /// argument on a MessageFrame, `0x795752`) until the fade overwrites it with the byte ramp
+    /// `trunc(remaining / fadeDuration * 255)` (`0x788547`, `0x786364`). At 0 a scrolling line
+    /// keeps its ring slot and rows; a MessageFrame frees it (`0x786570`).
     pub alpha: f32,
-    /// How many display rows the line wraps into at the frame's current width/font — host-measured
-    /// through the message-line measure round-trip
-    /// ([`crate::script::UiScript::message_lines_needing_measure`]). `1` until measured.
+    /// The rows the line wraps into at the frame's width and font, host-measured; 1 until then.
     pub rows: u16,
-    /// Cache key of the [`Self::rows`] measurement — hash of (text, font, height, wrap width),
-    /// computed engine-side. `0` = unmeasured (drawn as one row until the same-frame answer lands);
-    /// a width/font change mismatches the key and re-requests.
+    /// Hash of the text, font, height and wrap width `rows` was measured at; 0 is unmeasured.
     pub rows_key: u64,
 }
 
-/// A `CSimpleMessageScrollFrame`'s runtime state (ctor `0x787670`): a true ring of `max_lines`
-/// (drop-oldest, independent of how many display), each line carrying its own fade snapshot; a
-/// scrollback cursor counted **up from the bottom** (`0` = newest = AtBottom); and the frame-level
-/// fade config the per-line snapshots copy at insert.
+/// A `CSimpleMessageScrollFrame`'s runtime state (ctor `0x787670`): a drop-oldest ring of lines,
+/// a scrollback cursor counted up from the newest line, and the fade config new lines copy.
 #[derive(Clone, Debug, PartialEq)]
 pub struct ScrollingMessageState {
-    /// The frame's OWN justification, set by `SetJustifyH`/`SetJustifyV` — `None` until one of
-    /// them is called.
-    ///
-    /// Present on both classes: the ScrollingMessageFrame method table `0x87b5c0`
-    /// (the one whose `AddMessage` is `0x792900`) carries
-    /// `SetJustifyH 0x792600`/`GetJustifyH`/`SetJustifyV`/`GetJustifyV`, and the MessageFrame table
-    /// `0x87b960` (`AddMessage 0x795590`, the `SetInsertMode` sibling) carries the same four. Read
-    /// off the `{const char*, void*}` pair bytes; the same walk reproduces the Button table at
-    /// `0x879d00` exactly, and confirms Button has no `SetJustifyH` — which is
-    /// why the family cannot be inferred and had to be read.
-    ///
-    /// **`Option`, and the reason is ours not the client's.** The real object keeps ONE justify
-    /// dword: its font instance's. Ours reads a message frame's font instance off its first
-    /// `<FontString>` region (`message_frame_font`), which is where XML's
-    /// `<FontString … justifyH="LEFT"/>` lands — but a frame built by `CreateFrame` has no such
-    /// child and would have nowhere to store. So `None` means "never told, defer to the font
-    /// object" and keeps the shipped chat rendering byte-for-byte what it was; `Some` is an
-    /// explicit call and wins. The divergence that buys: on a frame that HAS a FontString, setting
-    /// the frame's justify does not change what that FontString's own `GetJustifyH` reports, where
-    /// the client would have them be one field.
+    /// The frame's own `SetJustifyH`/`SetJustifyV` (method table `0x87b5c0`), `None` until called
+    /// and then winning over the font's. Deviation: the reference has one field, the font's, but
+    /// our font is read off the first `<FontString>` region (`message_frame_font`), which a
+    /// `CreateFrame` frame lacks; so that FontString's own `GetJustifyH` does not see this.
     pub justify: Option<crate::justify::Justify>,
 
-    /// The line ring, newest at the back. Capacity is enforced by drop-oldest in [`Self::add`].
+    /// The line ring, newest at the back.
     pub lines: VecDeque<MessageLine>,
-    /// The ring capacity (`maxLines`; ctor default 8, ChatFrame.xml sets 128). `SetMaxLines` is
-    /// **destructive** (`0x787dd0`).
+    /// `maxLines`, the ring capacity (ctor 8); `SetMaxLines` clears the ring (`0x787dd0`).
     pub max_lines: usize,
-    /// `timeVisible`/`displayDuration` — phase-1 duration a new line holds full alpha (ctor 10.0s;
-    /// ChatFrame 120.0s).
+    /// `timeVisible`/`displayDuration`: seconds a new line holds full alpha (ctor 10).
     pub time_visible: f32,
-    /// `fadeDuration` — phase-2 fade ramp length (ctor 3.0s). `0` ⇒ the line vanishes instantly at
-    /// phase-1 expiry (no ramp).
+    /// `fadeDuration`: the fade's length in seconds (ctor 3); 0 hides the line at once.
     pub fade_duration: f32,
-    /// Bumped by every path that can change a line's TEXT set (add, clear, SetMaxLines, and the
-    /// generic mut door `KindState::message_lines_mut`) — the measure sweep's skip token
-    /// (`message_lines_needing_measure`): a frame whose generation and measure environment both
-    /// match its last clean sweep hashes no lines. Fade ticking deliberately does NOT bump (it
-    /// moves alpha/time, never text), or a fading chat line would keep the sweep hot for its
-    /// whole 2-minute ride.
+    /// Bumped by every change to the lines' text or colour, `KindState::message_lines_mut` too,
+    /// so the measure sweep skips an unchanged frame; the fade tick must not bump it.
     pub lines_gen: u64,
-    /// `fadingEnabled` (ctor 1). While false, lines never fade.
+    /// `fadingEnabled` (ctor 1).
     pub fading_enabled: bool,
-    /// The scrollback offset, counted up from the newest line: `0` = pinned to the bottom (AtBottom,
-    /// the only state in which fades tick — though every scroll entry re-arms the displayed lines
-    /// regardless, [`Self::reset_all_fade_times`]); `n` = the view is `n` lines older. Clamped in
-    /// [`Self::scroll_up`].
+    /// Lines scrolled back from the newest; 0 is AtBottom, the only state in which fades tick.
     pub scroll_offset: usize,
 }
 
 impl Default for ScrollingMessageState {
     fn default() -> ScrollingMessageState {
-        // The shared CSimpleMessageScrollFrame ctor (`0x787670`) defaults: fadingEnabled=1,
-        // timeVisible=10.0, fadeDuration=3.0; SMF maxLines=8.
+        // The ctor's defaults (`0x787670`).
         ScrollingMessageState {
             justify: None,
             lines: VecDeque::new(),
@@ -113,34 +68,15 @@ impl Default for ScrollingMessageState {
     }
 }
 
-/// Byte-quantize a `0..1` color/alpha component the way `AddMessage` does (`clamp[0,1]`, `*255`,
-/// `+0.5`, truncate — round-half-up; `AddMessage 0x788150`).
+/// A `0..1` colour component as a byte, rounded half up as `AddMessage` does (`0x788150`).
 pub fn quantize_u8(x: f32) -> u8 {
     (x.clamp(0.0, 1.0) * 255.0 + 0.5).trunc() as u8
 }
 
 impl ScrollingMessageState {
-    /// `AddMessage(text, r, g, b)` (`0x788150`): quantize the color, snapshot the current
-    /// `timeVisible`/`fadeDuration` onto the new line, and push it at the ring's newest slot,
-    /// dropping the oldest when over `max_lines`. A view scrolled up stays anchored on the same
-    /// content (the ring cursor is a slot, not an offset).
-    /// `ScrollingMessageFrame:UpdateColorByID(id, r, g, b)` (`0x7932b0` → `0x788250`) — every line
-    /// tagged `id` takes the new colour, quantised the way `AddMessage` quantised the old one.
-    /// Returns how many lines moved; a recolour bumps the generation so a settled frame redraws.
-    ///
-    /// **`id == 0` matches nothing, and that is a guard the reference opens with, not a
-    /// consequence** (decision 2125).
-    /// `0x788250` is `mov edi,[ebp+8]; test edi,edi; je 0x7882a4` → `ret 8`: zero never reaches a
-    /// comparison and the record walk is not entered at all.
-    ///
-    /// Without it this was a live repaint of every line ever printed with no explicit colour,
-    /// because `AddMessage`'s absent-id case stores an explicit literal `0` (`0x7929b7 xor edi,edi`
-    /// → `0x78821d mov [edi+0x14],ecx`) and `ChatTypeInfo["REPLY"].id` is 0 too — FrameXML declares
-    /// REPLY and the engine's 94-row registry does not carry it. So `ChatFrame_OnEvent`'s
-    /// `UPDATE_CHAT_COLOR` arm mirroring WHISPER into REPLY (`ChatFrame.lua` l.1357-1365) called
-    /// `UpdateColorByID(0, 1.0, 0.5, 1.0)` and turned every `AceConsole:Print` in the window
-    /// whisper-pink. Measured `(255,128,255)` on Bartender2's login line where the reference reads
-    /// `(255,255,255)`.
+    /// `UpdateColorByID(id, r, g, b)` (`0x7932b0`): recolour every line tagged `id`, returning how
+    /// many changed. `id == 0` matches nothing (the guard at `0x788250`): a line printed without
+    /// an id stores 0 (`0x7929b7`), and `ChatFrame.lua:1357` recolours REPLY, whose id is 0.
     pub fn update_color_by_id(&mut self, id: u32, r: f32, g: f32, b: f32) -> usize {
         if id == 0 {
             return 0;
@@ -163,8 +99,8 @@ impl ScrollingMessageState {
         self.add_with_id(text, r, g, b, 0);
     }
 
-    /// `AddMessage(text, r, g, b, id)` — the line, tagged with the chat-type index it was
-    /// printed under so a later `UpdateColorByID(id, …)` can recolour it.
+    /// `AddMessage(text, r, g, b, id)` (`0x792900`, `0x788150`): push the line and drop the oldest
+    /// past `max_lines`; a scrolled-up view stays on the same lines.
     pub fn add_with_id(&mut self, text: String, r: f32, g: f32, b: f32, id: u32) {
         self.lines_gen = self.lines_gen.wrapping_add(1);
         let line = MessageLine {
@@ -184,14 +120,13 @@ impl ScrollingMessageState {
         }
         while self.lines.len() > self.max_lines {
             self.lines.pop_front();
-            // The dropped line was above the view — walk the anchor back down with it.
+            // The dropped line was above the view: walk the anchor back down with it.
             self.scroll_offset = self.scroll_offset.saturating_sub(1);
         }
         self.clamp_scroll();
     }
 
-    /// `SetMaxLines(n)` — **destructive** (`0x787dd0`): frees every line + resets the cursor, then
-    /// sets the new capacity. Not a preserving resize.
+    /// `SetMaxLines(n)` (`0x787dd0`): free every line and reset the scroll, then set the capacity.
     pub fn set_max_lines(&mut self, n: usize) {
         self.lines_gen = self.lines_gen.wrapping_add(1);
         self.lines.clear();
@@ -206,8 +141,7 @@ impl ScrollingMessageState {
         self.scroll_offset = 0;
     }
 
-    /// Whether the view is pinned to the newest line (`AtBottom` — the only state in which fades
-    /// tick).
+    /// Whether the view is pinned to the newest line (`AtBottom`).
     pub fn at_bottom(&self) -> bool {
         self.scroll_offset == 0
     }
@@ -226,24 +160,9 @@ impl ScrollingMessageState {
         self.scroll_offset = self.scroll_offset.min(self.max_scroll());
     }
 
-    /// **Re-arm the displayed lines' fade** — the engine's `0x788b80`, which every scroll entry
-    /// reaches (see the scroll methods below). Per displayed line it writes the quartet
-    /// `alpha = 0xFF` (`0x788baf`), the in-use flag (`0x788bb3`), and the frame's *current*
-    /// `timeVisible`/`fadeDuration` **defaults** back onto the record's `+0xc`/`+0x10` snapshots
-    /// (`0x788bc0`/`0x788bc9`) — full values, never partial, and the frame default rather than
-    /// whatever the line was inserted with.
-    ///
-    /// Two properties that are easy to get wrong and are both byte-verified:
-    ///
-    /// - **The displayed set only, never the whole ring.** `0x788b80` walks `[+0x34c]` entries of
-    ///   the display vector `[+0x3a4]`, reaching each record through `node.+0xc`. A line scrolled
-    ///   out of view keeps whatever fade state it had.
-    /// - **A fully-faded line is recoverable.** Expiry (`0x788525`–`0x788538`) only clears the
-    ///   in-use flag, blanks the display object and hides it; `0x788460` contains no allocator call
-    ///   at all, so the record, its text and its wrapped height all survive and come straight back.
-    ///
-    /// Not a Lua binding: it is in no vtable and no data dword, and 1.12's FrameXML has no
-    /// `ResetAllFadeTimes` caller. It is engine behavior, reached only through the scroll entries.
+    /// Re-arm the fade of the displayed lines only (`0x788b80`): full alpha and the frame's
+    /// current `timeVisible`/`fadeDuration`, so even a fully faded line comes back (expiry frees
+    /// nothing, `0x788525`). Engine-only, not a 1.12 Lua verb; every scroll entry reaches it.
     pub fn reset_all_fade_times(&mut self, viewport_rows: usize) {
         let (time_visible, fade_duration) = (self.time_visible, self.fade_duration);
         for line in self.lines.range_mut(self.displayed_range(viewport_rows)) {
@@ -253,10 +172,7 @@ impl ScrollingMessageState {
         }
     }
 
-    /// The ring indices the view currently shows, oldest-first — the set
-    /// [`Self::reset_all_fade_times`] walks. The newest displayed line sits at the top end (it is
-    /// the bottom row on screen); the walk runs older from there for [`Self::displayed_count`]
-    /// messages.
+    /// The ring indices the view shows, oldest first.
     pub fn displayed_range(&self, viewport_rows: usize) -> std::ops::Range<usize> {
         let count = self.displayed_count(viewport_rows);
         if count == 0 {
@@ -268,53 +184,37 @@ impl ScrollingMessageState {
 
     // ── The scroll entries ──────────────────────────────────────────────────────────────────
     //
-    // **Every one of them re-arms the displayed lines' fade**, by one of two engine routes that
-    // between them leave no gap:
-    //
-    // - the cursor does NOT move (a scroll that is already at the boundary, or a no-op jump) — the
-    //   binding calls `0x788b80` directly: `ScrollUp` at AtTop (`0x788626`), `ScrollDown` at
-    //   AtBottom (`0x788666`), `ScrollToBottom` at AtBottom (`0x7886e5`);
-    // - the cursor DOES move — the relayout `0x788750` runs and its per-line helper `0x788af0`
-    //   (sole caller `0x7888be`) writes the same quartet under `arg3 != 0 || AtBottom == 0`, where
-    //   `arg3` is the relayout's own 0→1 AtBottom edge flag (`0x7887a3`). Land off the bottom and
-    //   the second term fires; land back ON the bottom and the edge flag does.
-    //
-    // So the re-arm is unconditional at this level and the two routes collapse into one call
-    // after the cursor has moved — which is also the right order, since the displayed set the
-    // engine walks is the one the new cursor selects. **Correction (2026-08-29):** benilla
-    // previously had scrolling merely *freeze* the countdown. Faded chat could never be brought
-    // back; the director reported it.
+    // Each re-arms the displayed lines' fade after moving the cursor. A scroll that cannot move
+    // calls `0x788b80` directly (`0x788626`, `0x788666`, `0x7886e5`); one that moves relayouts
+    // (`0x788750`), whose helper `0x788af0` re-arms on landing off the bottom or back onto it.
 
-    /// `ScrollUp` (`0x788610`) — one line older (no cursor move at the top), then re-arm.
+    /// `ScrollUp` (`0x788610`): one line older, then re-arm.
     pub fn scroll_up(&mut self, viewport_rows: usize) {
         self.scroll_offset = (self.scroll_offset + 1).min(self.max_scroll());
         self.reset_all_fade_times(viewport_rows);
     }
 
-    /// `ScrollDown` (`0x788650`) — one line newer (no cursor move at the bottom), then re-arm.
+    /// `ScrollDown` (`0x788650`): one line newer, then re-arm.
     pub fn scroll_down(&mut self, viewport_rows: usize) {
         self.scroll_offset = self.scroll_offset.saturating_sub(1);
         self.reset_all_fade_times(viewport_rows);
     }
 
-    /// `ScrollToBottom` (`0x7886d0`) — jump to the newest line, then re-arm.
+    /// `ScrollToBottom` (`0x7886d0`): to the newest line, then re-arm.
     pub fn scroll_to_bottom(&mut self, viewport_rows: usize) {
         self.scroll_offset = 0;
         self.reset_all_fade_times(viewport_rows);
     }
 
-    /// `ScrollToTop` (`0x788690`) — jump to the oldest line, then re-arm. This one never reaches
-    /// `0x788b80`; it re-arms because it always relayouts with AtBottom = 0.
+    /// `ScrollToTop` (`0x788690`): to the oldest line, then re-arm, as its relayout always lands
+    /// off the bottom.
     pub fn scroll_to_top(&mut self, viewport_rows: usize) {
         self.scroll_offset = self.max_scroll();
         self.reset_all_fade_times(viewport_rows);
     }
 
-    /// How many messages the view shows from the current anchor, given the viewport's row budget
-    /// (`floor(frame height / pitch)`): walk older from the anchor summing each message's wrapped
-    /// [`MessageLine::rows`] until the budget is spent. A partially-fitting message counts (it draws,
-    /// clipped), matching [`emit`](crate::script::UiScript::extract)'s band walk. At least 1 when
-    /// any line exists.
+    /// How many messages fit `viewport_rows` from the anchor, each costing its wrapped rows; a
+    /// partly fitting one counts, as in the draw's band walk (`emit_message_lines`).
     pub fn displayed_count(&self, viewport_rows: usize) -> usize {
         if self.lines.is_empty() || viewport_rows == 0 {
             return 0;
@@ -332,36 +232,24 @@ impl ScrollingMessageState {
         count.max(1)
     }
 
-    /// `PageUp` — the client pages by `numLinesDisplayed` scroll steps then one back
-    /// (`0x7885b0`: net page = displayed − 1, one line of overlap).
+    /// `PageUp` (`0x7885b0`): back by the displayed count less one, then re-arm.
     pub fn page_up(&mut self, viewport_rows: usize) {
         let page = self.displayed_count(viewport_rows).saturating_sub(1).max(1);
         self.scroll_offset = (self.scroll_offset + page).min(self.max_scroll());
         self.reset_all_fade_times(viewport_rows);
     }
 
-    /// `PageDown` — the same page size toward the newest line. Pages inherit both re-arm routes
-    /// from the `ScrollUp`/`ScrollDown` steps they are built out of.
+    /// `PageDown`: the same page toward the newest line, then re-arm.
     pub fn page_down(&mut self, viewport_rows: usize) {
         let page = self.displayed_count(viewport_rows).saturating_sub(1).max(1);
         self.scroll_offset = self.scroll_offset.saturating_sub(page);
         self.reset_all_fade_times(viewport_rows);
     }
 
-    /// Advance the fade by `dt` (the OnUpdate tick, `0x788460`). The entry gate is **AtBottom** and
-    /// `fading_enabled` — scrolled up, every line holds its current alpha and *this* function never
-    /// un-fades one. Un-fading is the scroll entries' job, through
-    /// [`Self::reset_all_fade_times`] — do not read the freeze below as "nothing ever comes back",
-    /// which is the reading that cost us the bug. Each
-    /// line runs phase 1 (`time_left` countdown at full alpha), then phase 2 (`fade_left` countdown,
-    /// alpha = `trunc(fade_left/fade_duration*255)`); `fade_duration == 0` snaps straight to 0.
-    ///
-    /// **Both countdowns are `fst`-without-pop** (`0x7884d7` phase 1, `0x788544` phase 2): memory
-    /// takes the `f32` rounding of `remaining − dt` while the x87 stack keeps the un-rounded value,
-    /// and it is the *un-rounded* one that the `fdiv`/`fmul 255.0`/`__ftol` ramp then consumes. So
-    /// the arithmetic runs wide and only the stored countdown narrows to `f32`. Phase 1's negative
-    /// overshoot is discarded — it stores exactly `0`, and phase 2 starts on the next tick with the
-    /// full fade rather than the remainder.
+    /// Advance the fade by `dt` (OnUpdate, `0x788460`), only at the bottom with fading on; the
+    /// scroll entries, not this, bring faded lines back. Both countdowns store `f32` while the
+    /// ramp reads the unrounded x87 value (`fst` without pop, `0x7884d7`, `0x788544`), and phase
+    /// 1's overshoot is dropped, so the fade starts whole on the next tick.
     pub fn tick(&mut self, dt: f32) {
         if !self.fading_enabled || !self.at_bottom() {
             return;
@@ -373,7 +261,7 @@ impl ScrollingMessageState {
                 continue;
             }
             if self.fade_duration <= 0.0 {
-                // No ramp — the line vanishes the instant phase 1 expires.
+                // No ramp: the line vanishes when phase 1 ends.
                 line.alpha = 0.0;
                 continue;
             }
@@ -383,9 +271,8 @@ impl ScrollingMessageState {
                 line.fade_left = 0.0;
                 line.alpha = 0.0;
             } else {
-                // Divisor is the LIVE frame fadeDuration (a mid-fade SetFadeDuration rescales the
-                // ramp), byte-quantized like the client — off the wide `remaining`, not the stored
-                // f32, per the `fst`-no-pop shape above.
+                // Over the live fadeDuration (a mid-fade change rescales the ramp), from the
+                // unrounded `remaining`, not the stored f32.
                 let byte = quantize_fade_wide(remaining / f64::from(self.fade_duration));
                 line.alpha = f32::from(byte) / 255.0;
             }
@@ -393,102 +280,57 @@ impl ScrollingMessageState {
     }
 }
 
-/// Phase-2 alpha quantization: `trunc(x*255)` (no `+0.5` — the fade tick truncates, `0x788547`).
+/// The fade's alpha byte, truncated with no `+0.5` (`0x788547`).
 fn quantize_fade(x: f32) -> u8 {
     (x.clamp(0.0, 1.0) * 255.0).trunc() as u8
 }
 
-/// [`quantize_fade`] off the x87 stack's un-rounded ratio — see [`ScrollingMessageState::tick`] on
-/// the `fst`-without-pop shape that makes the ramp wider than the countdown it stores.
+/// [`quantize_fade`] of the unrounded ratio (see [`ScrollingMessageState::tick`]).
 fn quantize_fade_wide(x: f64) -> u8 {
     (x.clamp(0.0, 1.0) * 255.0).trunc() as u8
 }
 
-/// Where a [`MessageFrameState`]'s newest message enters the display stack — the `insertMode` XML
-/// attribute (`0x87a618`) and the `SetInsertMode`/`GetInsertMode` pair (`0x794ed0`/`0x794ff0`).
-///
-/// **MessageFrame only**, which is why it lives here and not on [`ScrollingMessageState`]: the
-/// scrolling class has neither binding and no such XML attribute.
+/// Where a MessageFrame's newest message enters: XML `insertMode` (`0x87a618`) and
+/// `SetInsertMode`/`GetInsertMode` (`0x794ed0`/`0x794ff0`); the scrolling class has neither.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub enum InsertMode {
-    /// `"TOP"` (the client's `0`): the newest message takes the frame's **top** line and older ones
-    /// step down. The reference's own `UIErrorsFrame.xml:4` asks for this, and so does every corpus
-    /// caller of `SetInsertMode` (`BigWigs/Plugins/Messages.lua:209`).
+    /// `"TOP"` (0): newest on the top line, older stepping down, as `UIErrorsFrame.xml:4` asks.
     Top,
-    /// `"BOTTOM"` (the client's `1`, and the **ctor default**): newest at the bottom, older stepping
-    /// up — the chat shape.
+    /// `"BOTTOM"` (1, the ctor default): newest on the bottom line, older stepping up.
     #[default]
     Bottom,
 }
 
-/// A `CSimpleMessageFrame`'s runtime state (ctor `0x785640`) — the class `UIErrorsFrame` is, and
-/// [`ScrollingMessageState`]'s **sibling, never its base**. The two come from different ctors and
-/// their `AddMessage` bindings are different functions with different tails, so nothing is shared
-/// here beyond the line record itself:
+/// A `CSimpleMessageFrame`'s runtime state (ctor `0x785640`), the class of `UIErrorsFrame` and a
+/// sibling of [`ScrollingMessageState`]: no ring, no `maxLines` (the cap is what fits), no
+/// scrollback, an `AddMessage` alpha in place of the id, and a faded line freed (`0x786570`).
 ///
-/// | | MessageFrame (this) | ScrollingMessageFrame |
-/// |---|---|---|
-/// | store | display lines only — no ring, **no `maxLines`**; the cap is what fits vertically | a true ring of `maxLines`, drop-oldest |
-/// | `AddMessage` tail | a real **alpha**, default 1.0 (`0x795590`) | an **id**; alpha forced `0xFF` (`0x792900`) |
-/// | scrollback | none at all | cursor + scroll/page set |
-/// | `SetInsertMode` | yes ([`InsertMode`]) | no binding, no attribute |
-/// | a fully-faded line | retired and the rest re-pack (`0x786570`) | keeps its ring slot and its rows |
-///
-/// The one recorded shape this does **not** model is the pending queue: the real class only
-/// *enqueues* in `AddMessage` and drains at OnUpdate, dropping the message outright if
-/// `numLinesDisplayed` is 0 at drain time (`786265`). Here a message lands in [`Self::lines`]
-/// immediately and [`Self::trim_to_viewport`] applies the vertical cap at the next tick — the same
-/// observable result one tick earlier, without a second buffer whose only visible consequence is
-/// that a message added to a zero-height frame vanishes.
+/// The reference queues `AddMessage` and drains it at OnUpdate, dropping a message while
+/// `numLinesDisplayed` is 0 (`0x786265`); here a line lands at once and
+/// [`Self::trim_to_viewport`] applies the cap.
 #[derive(Clone, Debug, PartialEq)]
 pub struct MessageFrameState {
-    /// The frame's OWN justification, set by `SetJustifyH`/`SetJustifyV` — `None` until one of
-    /// them is called.
-    ///
-    /// Present on both classes: the ScrollingMessageFrame method table `0x87b5c0`
-    /// (the one whose `AddMessage` is `0x792900`) carries
-    /// `SetJustifyH 0x792600`/`GetJustifyH`/`SetJustifyV`/`GetJustifyV`, and the MessageFrame table
-    /// `0x87b960` (`AddMessage 0x795590`, the `SetInsertMode` sibling) carries the same four. Read
-    /// off the `{const char*, void*}` pair bytes; the same walk reproduces the Button table at
-    /// `0x879d00` exactly, and confirms Button has no `SetJustifyH` — which is
-    /// why the family cannot be inferred and had to be read.
-    ///
-    /// **`Option`, and the reason is ours not the client's.** The real object keeps ONE justify
-    /// dword: its font instance's. Ours reads a message frame's font instance off its first
-    /// `<FontString>` region (`message_frame_font`), which is where XML's
-    /// `<FontString … justifyH="LEFT"/>` lands — but a frame built by `CreateFrame` has no such
-    /// child and would have nowhere to store. So `None` means "never told, defer to the font
-    /// object" and keeps the shipped chat rendering byte-for-byte what it was; `Some` is an
-    /// explicit call and wins. The divergence that buys: on a frame that HAS a FontString, setting
-    /// the frame's justify does not change what that FontString's own `GetJustifyH` reports, where
-    /// the client would have them be one field.
+    /// The frame's own `SetJustifyH`/`SetJustifyV` (method table `0x87b960`), `None` until called.
+    /// Deviation: kept apart from the font's, as [`ScrollingMessageState::justify`] is.
     pub justify: Option<crate::justify::Justify>,
 
-    /// See [`ScrollingMessageState::lines_gen`] — the same sweep-skip token.
+    /// The measure sweep's skip token, as [`ScrollingMessageState::lines_gen`].
     pub lines_gen: u64,
-    /// The display lines, **newest at the back always** — [`InsertMode`] is a *display direction*
-    /// resolved at emit, not a storage order, so "evict the oldest" is one `pop_front` in both
-    /// modes.
+    /// The lines, newest at the back in both insert modes: [`InsertMode`] only orders the draw.
     pub lines: VecDeque<MessageLine>,
-    /// `insertMode` — which end of the frame new messages enter from (ctor default BOTTOM).
+    /// `insertMode` (ctor BOTTOM).
     pub insert_mode: InsertMode,
-    /// `timeVisible`/`displayDuration` — phase-1 duration a new line holds its insert alpha (ctor
-    /// 10.0s; `UIErrorsFrame.xml` sets 5).
+    /// `timeVisible`/`displayDuration`: seconds a new line holds its insert alpha (ctor 10).
     pub time_visible: f32,
-    /// `fadeDuration` — phase-2 ramp length (ctor 3.0s). `0` ⇒ the line vanishes at phase-1 expiry
-    /// with no ramp.
+    /// `fadeDuration`: the fade's length in seconds (ctor 3); 0 hides the line at once.
     pub fade_duration: f32,
-    /// `fadingEnabled` (ctor 1). While false nothing fades — and, because retirement is what bounds
-    /// this list, nothing retires either; the vertical cap is then the only bound (which is exactly
-    /// the client's own arrangement).
+    /// `fadingEnabled` (ctor 1); while false only the vertical cap bounds the lines.
     pub fading_enabled: bool,
 }
 
 impl Default for MessageFrameState {
     fn default() -> MessageFrameState {
-        // The CSimpleMessageFrame ctor (`0x785640`) defaults: fadingEnabled=1,
-        // timeVisible=10.0, fadeDuration=3.0; insertMode 1 = BOTTOM. Note the fade pair is
-        // shared with the scrolling class but `maxLines` has no counterpart here.
+        // The ctor's defaults (`0x785640`).
         MessageFrameState {
             justify: None,
             lines: VecDeque::new(),
@@ -502,10 +344,8 @@ impl Default for MessageFrameState {
 }
 
 impl MessageFrameState {
-    /// `AddMessage(text, r, g, b, a)` (`0x795590` → `0x785d00`): quantize the colour the same
-    /// round-half-up way the scrolling class does, take the **alpha argument** as the line's
-    /// starting alpha (this class's fourth numeric really is alpha — the scrolling one's is an id
-    /// and forces `0xFF`), snapshot the frame's fade config, and append.
+    /// `AddMessage(text, r, g, b, a)` (`0x795590`, `0x785d00`): the fourth number is the line's
+    /// starting alpha, where the scrolling class takes an id and forces opaque.
     pub fn add(&mut self, text: String, r: f32, g: f32, b: f32, a: f32) {
         self.lines_gen = self.lines_gen.wrapping_add(1);
         self.lines.push_back(MessageLine {
@@ -514,35 +354,23 @@ impl MessageFrameState {
             color: [quantize_u8(r), quantize_u8(g), quantize_u8(b)],
             time_left: self.time_visible,
             fade_left: self.fade_duration,
-            // Quantized like the colour: the client packs all four channels into one 0xAARRGGBB
-            // dword through the same `ftol(v*255 + 0.5)`.
+            // Quantized like the colour: all four channels pack into one ARGB dword.
             alpha: f32::from(quantize_u8(a)) / 255.0,
             rows: 1,
             rows_key: 0,
         });
     }
 
-    /// `Clear` — retire every line immediately, no fade. (`_LazyPig` calls `UIErrorsFrame:Clear()`
-    /// eleven times; it is the one non-`AddMessage` verb the corpus actually uses on this class.)
+    /// `Clear`: drop every line at once, no fade.
     pub fn clear(&mut self) {
         self.lines_gen = self.lines_gen.wrapping_add(1);
         self.lines.clear();
     }
 
-    /// Advance the fade by `dt` — the OnUpdate virtual `0x786200`, whose gate is
-    /// `activeCount != 0 && fadingEnabled != 0 && numLinesDisplayed > 0`. **No scroll gate**: this
-    /// class has no scrollback, so unlike [`ScrollingMessageState::tick`] nothing can freeze it.
-    ///
-    /// Two phases per line, identical formula to the scrolling class: `time_left` counts down at the
-    /// insert alpha, then `fade_left` counts down and *overwrites* the alpha with
-    /// `trunc(fade_left/fade_duration*255)` against the **live** frame `fade_duration`. A finished
-    /// line is then **freed** rather than left in place — this class has no ring to hold a slot, so
-    /// the survivors re-pack (`0x786570`, the retire helper that decrements the active count).
-    ///
-    /// Deliberately still narrow arithmetic: the `fst`-without-pop shape is byte-cited for the
-    /// *scrolling* class's tick (`0x7884d7`/`0x788544`), and `0x786200` has not been walked for it.
-    /// Copying the wide form across on the strength of "same formula" would be the scope error
-    /// decision 1692 is about, one class over.
+    /// Advance the fade by `dt` (OnUpdate, `0x786200`) in the scrolling class's two phases, with no
+    /// scroll gate, freeing a finished line (`0x786570`). The reference also gates on
+    /// `numLinesDisplayed > 0`, which this does not check. The arithmetic is `f32`: whether
+    /// `0x786200` keeps the unrounded x87 value like the scrolling tick is untraced.
     pub fn tick(&mut self, dt: f32) {
         if !self.fading_enabled {
             return;
@@ -564,19 +392,13 @@ impl MessageFrameState {
                 line.alpha = f32::from(quantize_fade(line.fade_left / self.fade_duration)) / 255.0;
             }
         }
-        // Retired lines are gone, not blank: `alpha == 0` past phase 1 is the finished state.
+        // A line past phase 1 at alpha 0 is finished, and freed.
         self.lines.retain(|l| l.time_left > 0.0 || l.alpha > 0.0);
     }
 
-    /// Evict the oldest lines until only what fits in `viewport_rows` display rows remains — this
-    /// class's whole capacity law ("no `maxLines` anywhere on this class — the cap is what fits
-    /// vertically"), with each line costing its host-measured wrapped [`MessageLine::rows`].
-    ///
-    /// `viewport_rows == 0` means the frame has no resolved rect yet (or a degenerate one) and is
-    /// left alone rather than emptied: dropping there would lose a message posted from an `OnLoad`
-    /// before the first solve, which is a v1 ordering artefact and not the client's zero-height
-    /// case. The fade is what bounds the list in that window — and with `fading_enabled` false it
-    /// is unbounded until the frame resolves, which is stated rather than papered over.
+    /// Evict the oldest lines until the rest fit `viewport_rows`, each costing its wrapped rows.
+    /// Zero rows means no rect yet and evicts nothing, so a message posted from `OnLoad` before
+    /// the first layout survives; until then only the fade bounds the list.
     pub fn trim_to_viewport(&mut self, viewport_rows: usize) {
         if viewport_rows == 0 {
             return;
diff --git a/crates/benilla-ui/src/widget/kinds/mod.rs b/crates/benilla-ui/src/widget/kinds/mod.rs
index ea5aa388..f94deefd 100644
--- a/crates/benilla-ui/src/widget/kinds/mod.rs
+++ b/crates/benilla-ui/src/widget/kinds/mod.rs
@@ -1,8 +1,4 @@
-//! The widget-kind vocabulary + per-kind state (the "later layer" over the frame arena): the
-//! 13 client widget classes ([`FrameKind`]), the two region leaves ([`RegionKind`]), and the
-//! modeled per-kind behavior ([`KindState`]) that a `CSimple*` subtype adds over `CSimpleFrame`
-//! (the reference's LoadXML tables; decision 0068). Split from the arena so each grows
-//! independently.
+//! Widget kinds: [`FrameKind`], [`RegionKind`] and the per-kind state, [`KindState`].
 
 use std::collections::{HashSet, VecDeque};
 
@@ -13,55 +9,17 @@ mod messageframe;
 pub use editbox::*;
 pub use messageframe::*;
 
-/// The widget subtype of a [`Frame`]. Each corresponds to a client `CSimple*` class
-/// (the reference's 13 widget factories, decision 0068). Kinds with modeled behavior carry it
-/// in [`Frame::kind_state`] (StatusBar today); the rest are tags whose per-kind behavior (button
-/// states, editbox text, …) is a later layer over this arena.
+/// A [`Frame`]'s widget class; one with modeled behavior carries it in [`Frame::kind_state`].
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 pub enum FrameKind {
-    /// Plain `CSimpleFrame` — the base container.
+    /// Plain `CSimpleFrame`, the base container.
     Frame,
-    /// The reference's `CGWorldFrame` (decisions 1983/1984): the singleton the 3D world renders
-    /// behind. Registered as its own frame type (`"WorldFrame"`
-    /// @`0x843450`, factory `0x4959d0`) whose registry record is **destroyed on the first
-    /// instantiation** — a second `<WorldFrame>` or `CreateFrame("WorldFrame")` is an unknown type;
-    /// **a `Frame` to Lua** (`GetObjectType()` answers `"Frame"`, `IsObjectType("WorldFrame")` is
-    /// nil — its vtable inherits the base's type slots, the TaxiRouteFrame precedent); born with
-    /// key, mouse and wheel enabled (`0xE`) in **stratum 0, `WORLD`, below `BACKGROUND`**, which
-    /// no XML or Lua can name. benilla draws the world through Bevy, so the kind is a full-screen
-    /// frame whose hits are the WORLD's: the app's pointer arbiter treats a hovered WorldFrame as
-    /// not-over-UI while its own scripts still fire, as the reference's do before the click's
-    /// binding runs.
+    /// `CGWorldFrame` (factory `0x4959d0`), the singleton the world renders behind: a `Frame` to
+    /// Lua, in stratum `WORLD` below `BACKGROUND`; hovered, it is not over the UI but runs scripts.
     WorldFrame,
     Button,
-    /// `CLootButton` (`Ui\\LootFrame.h:21`, factory `0x495a30`, size `0x4e0`) — a
-    /// **registered `CreateFrame` type**, one of the eight the client registers through
-    /// `0x495940` (pair `("LootButton" @0x843414, 0x495a30)` at site `0x4959a6`), and the reason
-    /// the stock `LootFrame.xml` cannot load against a plain `<Button>`.
-    ///
-    /// It is a `CSimpleButton` **plus one dword and one overridden virtual**, and that is the
-    /// whole class. The dword at `+0x4dc` is the 0-based loot slot; the virtual is primary slot 37
-    /// `OnClick 0x4c1820`. Everything else it overrides (slots 0, 2, 4, 6, 7 and the secondary
-    /// adjustor thunk) is compiler-mandated identity and lifetime plumbing. A binary-wide census
-    /// of `+0x4dc` finds exactly three sites in its code: the ctor's zero, `SetSlot`'s write, and
-    /// `OnClick`'s read.
-    ///
-    /// **What it does NOT have**, each proven by the vtable dwords being *identical* to
-    /// `CSimpleButton`'s: no C-side `OnEnter`/`OnLeave` (slots 19/20), so the hover tooltip is
-    /// purely the FrameXML `<OnEnter>`; no drag (29/30/31); no `OnLoad`/`OnShow`/`OnHide`/
-    /// `OnUpdate` (9/12/13/14). And no button-code test anywhere in its 79-byte click body — it
-    /// reads `[ebp+8]` once and immediately forwards it — so **right-click loots exactly like
-    /// left-click**, and with no `<OnDoubleClick>` a fast double-click takes two slots.
-    ///
-    /// The click, in order (`0x4c1820`): a scripted click returns immediately and does **nothing,
-    /// not even run the Lua `<OnClick>`** (`0x4c182b`); otherwise the base fires the Lua handler
-    /// unconditionally, and then — only with **no shift, ctrl or alt** held — the take runs. That
-    /// gate is what keeps the C take and `LootFrameItem_OnClick`'s ctrl/shift arms from firing
-    /// together, and it is why the shipped Lua handler deliberately never calls a take itself.
-    ///
-    /// Its whole Lua surface of its own is **one method, `SetSlot(index)`** (table `0x847ce4`,
-    /// count 1 read off the registrar's own `mov edx,1`) — 1-based in, 0-based stored, no returns.
-    /// `LootFrame.lua:94` is its only caller. Decision 1799.
+    /// `CLootButton` (factory `0x495a30`): a `CSimpleButton` plus a loot slot and an `OnClick`
+    /// (`0x4c1820`) that takes it; a registered `CreateFrame` type the stock `LootFrame.xml` needs.
     LootButton,
     CheckButton,
     EditBox,
@@ -69,163 +27,73 @@ pub enum FrameKind {
     Slider,
     ScrollFrame,
     Model,
-    /// `CGCharacterModelBase` (`0x505680`, size `0x3f8`) — the **unit-showing** model pane, and a
-    /// registered `CreateFrame` type in its own right: pair `("PlayerModel" @0x84343c, factory
-    /// 0x495bd0)` at registration site `0x49597f`, one of the eight the game client registers
-    /// through `0x495940`.
-    ///
-    /// **It extends [`FrameKind::Model`] and adds exactly three verbs** — `SetUnit`, `RefreshUnit`,
-    /// `SetRotation` (table `0x84f1fc`, 3 entries). Its Lua surface is those three *plus* all 23 of
-    /// `Model`'s, and it gets them by **chaining, not repetition**: `CGCharacterModelBase`'s method
-    /// lookup `0x506260` probes its own 3-entry map and, on a miss, tail-calls `0x506290 call
-    /// 0x76f870` — `CSimpleModel`'s. Our `__index` already walks a *slice* of registry keys, so the
-    /// chain is `&[PLAYERMODEL, MODEL]` and nothing is duplicated.
-    ///
-    /// **The direction is derived → base only.** A plain `<Model>` does *not* acquire `SetUnit`/
-    /// `RefreshUnit`/`SetRotation`: nothing chains from `0x76f870` down into `0x506260`. benilla
-    /// published all three on `Model` until 2026-08-30 — a `strings WoW.exe` hit read as ownership,
-    /// which it cannot be (`SetUnit`'s pooled string `0x84f22c` is referenced by **two** table
-    /// entries, `PlayerModel 0x84f1fc` and `GameTooltip 0x854290`, and by no `Model` entry).
-    ///
-    /// Same posture as its base: the engine core holds the scene the Lua API reads and writes
-    /// ([`KindState::Model`], shared with [`FrameKind::Model`]); the pixels are the app renderer's.
-    /// `CGCharacterModelBase` adds `0x1c` bytes of members over `CSimpleModel` — the turn-animation
-    /// flag/expiry at `+0x3e8`/`+0x3ec` that `SetRotation` arms — and those are **not modeled**:
-    /// no getter reads them, and the app's `<Model>` renderer draws no shuffle animation.
-    /// `script::modelframe`'s `SetRotation` carries the addresses.
+    /// `CGCharacterModelBase` (`0x505680`, factory `0x495bd0`): `Model` plus `SetUnit`,
+    /// `RefreshUnit` and `SetRotation` (table `0x84f1fc`), which a plain `<Model>` lacks.
     PlayerModel,
-    /// `DressUpModel` — `CGDressUpModelFrame` (`Ui\DressUpModelFrame.cpp`, factory `0x495c00`,
-    /// ctor `0x5041d0` chaining `CGCharacterModelBase`'s `0x505680`): the dressing room's pane.
-    /// It EXTENDS [`FrameKind::PlayerModel`] — the same members, two behavioural vtable overrides
-    /// (idx36 `0x504350`: clone the unit's CharacterComponents and seed the two hand lanes; idx38
-    /// `0x504470`) — and adds exactly three verbs of its own, table `0x84f190`: `Undress 0x504c00`,
-    /// `Dress 0x504cd0`, `TryOn 0x504d90`. Everything else it answers is `PlayerModel`'s and then
-    /// `Model`'s, by the same chaining. Its state is [`KindState::Model`] like both of them; what a
-    /// try-on DOES lives app-side as an ordered intent queue (`script::dressup`), because the
-    /// substitution set is a look composed against the player's live equipment, which the VM
-    /// never holds (`0x707400` duplicates the live model natively; decisions 1060, 1969).
+    /// `CGDressUpModelFrame` (factory `0x495c00`): `PlayerModel` plus `Undress`, `Dress` and
+    /// `TryOn` (table `0x84f190`); a try-on is composed app-side against live equipment.
     DressUpModel,
-    /// `TabardModel` (`0x503bd0`) — the guild tabard designer's pane: `CGCharacterModelBase`'s
-    /// other subclass (the dress-up model's sibling), with ten verbs of its own in table
-    /// `0x84ee40` — the emblem/colour cycling, the two emblem-texture setters, the save gate and
-    /// the save. Its state is [`KindState::Model`] like its siblings; the design it carries lives
-    /// app-side (`script::tabard`, decision 1977).
+    /// `TabardModel` (`0x503bd0`): `CGCharacterModelBase` plus ten verbs (table `0x84ee40`).
     TabardModel,
-    /// `CSimpleMessageFrame` — the non-scrolling message frame (`UIErrorsFrame`'s class, and the
-    /// one `CreateFrame("MessageFrame")` makes). Its behaviour (the display lines, the per-line
-    /// fade, `insertMode`) is modeled in [`KindState::Message`]. Sibling of
-    /// [`FrameKind::ScrollingMessageFrame`], not a base or a subset of it.
+    /// `CSimpleMessageFrame`, `UIErrorsFrame`'s class: a sibling of the scrolling one.
     MessageFrame,
-    /// `CSimpleMessageScrollFrame` — the scrolling, ring-buffered message frame (the chat window's
-    /// class). Its behavior (the line ring, per-line fade, wheel scrollback) is modeled in
-    /// [`KindState::ScrollingMessage`]. Sibling of [`FrameKind::MessageFrame`] (different C++ ctor),
-    /// not a subclass — offsets/semantics do not transfer (different base ctors `0x7a3540`/
-    /// `0x769090`).
+    /// `CSimpleMessageScrollFrame`, the chat window's ring-buffered class; a sibling of
+    /// [`FrameKind::MessageFrame`] whose offsets do not transfer (bases `0x7a3540`/`0x769090`).
     ScrollingMessageFrame,
     ColorSelect,
     SimpleHtml,
     MovieFrame,
-    /// The `GameTooltip` widget family (decision 0274). Like [`FrameKind::Minimap`], a
-    /// *game-layer* factory over `CSimpleFrame`; its modeled behavior —
-    /// the line stack, owner/anchor law, auto-size, fade — lives in [`KindState::Tooltip`] and
-    /// `script::tooltip`. The real class's Lua surface is the 38-binding family at
-    /// `0x530c40`–`0x5364a0`; the line/color primitives are byte-diffed (`0x531630`/`0x531840`),
-    /// the content builders land per 0274's phases.
+    /// The `GameTooltip` family, a game-layer factory; its 38 bindings are `0x530c40`..`0x5364a0`.
     GameTooltip,
-    /// The `<Minimap>` widget (Minimap.xml's circular HUD map). Like [`FrameKind::GameTooltip`], a
-    /// *game-layer* factory, not one of the 13 base FrameXML types (`RegisterFrameFactories`
-    /// `0x495940` registers the game UI's own widget set at `CGGameUI::Initialize`; ui node). The
-    /// widget is a sized hole the game engine draws into — tiles, blips, and the player arrow are
-    /// the app renderer's job (decision 0203); the engine core carries only the rect and the zoom
-    /// state ([`KindState::Minimap`]).
+    /// The `<Minimap>` widget, a game-layer factory (`0x495940`) the app draws the map into.
     Minimap,
 }
 
-/// Whether a [`Region`] leaf is a texture or a text string. These are the client's two non-frame
-/// region types (`CScriptRegion`-derived leaves).
+/// The kind of a [`Region`] leaf, the client's `CScriptRegion`-derived non-frame objects.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 pub enum RegionKind {
     /// A `Texture` (BLP quad).
     Texture,
     /// A `FontString` (text run).
     FontString,
-    /// A frame's **title region** — the drag handle `Frame:CreateTitleRegion()` makes.
-    ///
-    /// A third leaf rather than a texture that happens to draw nothing, because the difference is
-    /// OBSERVABLE: the client makes the object a plain Region (`0x773910`) whose
-    /// `GetObjectType()` answers `"Region"` and which exposes exactly the 19
-    /// Region methods — **no Show/Hide, no scripts, no textures**. A `Texture` in disguise would
-    /// answer `"Texture"` to any addon that asked, and would emit a quad.
+    /// A frame's title region, the drag handle `Frame:CreateTitleRegion()` makes: a plain Region
+    /// (`0x773910`) that answers `"Region"` and has only the 19 Region methods.
     Title,
 }
 
-/// Per-kind widget state — the "later layer" over the kind tag, for the kinds whose behavior is
-/// modeled. Lives on the [`Frame`] node (the client's `CSimpleStatusBar` etc. extend `CSimpleFrame`
-/// with exactly such members).
+/// The state a modeled kind adds over `CSimpleFrame`, carried on the [`Frame`] node.
 #[derive(Clone, Debug, PartialEq)]
 pub enum KindState {
-    /// No modeled per-kind behavior (a plain frame, or a kind whose behavior is a later layer).
+    /// No modeled per-kind state.
     None,
-    /// `CSimpleStatusBar` (factory `0x6eef20`; LoadXML `0x782ef0`): a value in `[min, max]` filling
-    /// a bar texture along the orientation axis.
+    /// `CSimpleStatusBar` (factory `0x6eef20`, LoadXML `0x782ef0`): a value filling a bar texture.
     StatusBar(StatusBarState),
-    /// `CSimpleButton`/`CSimpleCheckbox` (factories `0x6eeab0`/`0x6eeb30`;
-    /// LoadXML `0x7788c0`/`0x785170`) —
-    /// the state-texture array + ButtonText. [`FrameKind::CheckButton`] shares this state (the
-    /// client's checkbox extends the button class), using the two `checked` members.
+    /// `CSimpleButton`/`CSimpleCheckbox` (factories `0x6eeab0`/`0x6eeb30`, LoadXML
+    /// `0x7788c0`/`0x785170`); the checkbox extends the button and uses the `checked` members.
     Button(ButtonState),
-    /// `CSimpleEditBox` (factory `0x6eec70`): the text buffer, cursor,
-    /// selection, config flags, and the FontString the text renders through.
+    /// `CSimpleEditBox` (factory `0x6eec70`): text, cursor, selection, flags and its FontString.
     EditBox(EditBoxState),
-    /// `CSimpleMessageScrollFrame` (ctor `0x787670`): the line
-    /// ring, the per-line fade snapshots + phases, and the scrollback cursor.
+    /// `CSimpleMessageScrollFrame` (ctor `0x787670`): the line ring, fades and scrollback.
     ScrollingMessage(ScrollingMessageState),
-    /// `CSimpleMessageFrame` (ctor `0x785640`; same runtime model) — the `UIErrorsFrame` class:
-    /// display lines with no ring and no scrollback, plus `insertMode`. A **sibling** of
-    /// [`KindState::ScrollingMessage`], not a subset of it ([`MessageFrameState`]'s doc has the
-    /// contract table).
+    /// `CSimpleMessageFrame` (ctor `0x785640`): lines and `insertMode`, no ring or scrollback.
     Message(MessageFrameState),
-    /// `CSimpleScrollFrame` (decision 0112 — the ScrollFrame mechanism, the engine's last structural
-    /// gap: the quest log's detail pane, chat history, and every long-content window need it): the
-    /// scroll child + the vertical scroll offset. The offset setter and the range are byte-pinned
-    /// (2017: `0x786db0` stores the offset as given, no clamp; 1338: `0x786e30` measures the
-    /// child's subtree); the rest is spec-faithful to the documented contract, same posture as
-    /// StatusBar's fill. Horizontal scroll is out of scope (no 1.12 template drives it).
+    /// `CSimpleScrollFrame`: the scroll child and offsets. `0x786db0` stores an offset unclamped;
+    /// `0x786e30` measures the range from the child's subtree.
     Scroll(ScrollFrameState),
-    /// `CSimpleSlider` (factory `0x6eee40`; LoadXML table `0x789580`): a value in `[min, max]`
-    /// with a step and orientation, positioning a thumb texture along the track. The mechanism is
-    /// spec-faithful to the documented Slider widget contract (same posture as StatusBar's fill /
-    /// ScrollFrame's scroll), not byte-pinned. Every scrollbar is one (decision 0250).
+    /// `CSimpleSlider` (factory `0x6eee40`, LoadXML `0x789580`), every scrollbar included.
     Slider(SliderState),
-    /// `CSimpleColorSelect` (ctor `0x78b220`, factory `0x6eef90`; LoadXML `0x78b3f0`, script-map
-    /// `0x78b4f0`): the colour the picker window holds, as the client holds it — **HSV
-    /// floats**, not RGB ([`ColorSelectState`], whose docs carry the byte-verified law). The colour
-    /// *wheel* and *value strip* the real widget draws are engine art with no BLP behind them (their
-    /// `<ColorWheelTexture>`/`<ColorValueTexture>` elements carry no `file=`), so this state is the
-    /// widget's whole modeled behavior here; see [`crate::script::colorselect`].
+    /// `CSimpleColorSelect` (ctor `0x78b220`, factory `0x6eef90`, LoadXML `0x78b3f0`).
     ColorSelect(ColorSelectState),
-    /// The `Model` widget's scene state — the 3D pane an addon or a FrameXML frame parks a model
-    /// in. **The same split as [`KindState::Minimap`]**: the engine core carries exactly what
-    /// the Lua API reads and writes, and the pixels are the app renderer's job. See
-    /// [`ModelState`].
+    /// The scene state of every model kind; the pixels are the app's.
     Model(ModelState),
-    /// The `<Minimap>` widget's zoom state (decision 0203). The engine core carries only what the
-    /// Lua API reads/writes (`GetZoom`/`SetZoom`/`GetZoomLevels`); the tile/blip render is app-side.
+    /// The `<Minimap>` widget's zoom, mask and player arrow; the tiles and blips are the app's.
     Minimap(MinimapState),
-    /// The GameTooltip widget's line stack + owner/fade state ([`TooltipState`], decision 0274).
+    /// The `GameTooltip` line stack, owner and fade.
     Tooltip(TooltipState),
 }
 
 impl KindState {
-    /// The display lines of **either** message-frame class, or `None` for every other kind.
-    ///
-    /// The two classes are siblings with different stores, different `AddMessage` tails and
-    /// different scrollback (see [`MessageFrameState`]), but the *line record* they display is the
-    /// same [`MessageLine`] — text, quantized colour, fade phases, wrapped row count. This pair of
-    /// accessors is the only place that likeness is spent: the wrapped-row measure round-trip and
-    /// the band emit are one code path for both, while every behaviour that actually differs stays
-    /// on its own state. Matching on the two variants at those sites instead would have been two
-    /// near-copies of the round-trip, which is how the second one silently rots.
+    /// The display lines of either message-frame class, which share the [`MessageLine`] record.
     pub fn message_lines(&self) -> Option<&VecDeque<MessageLine>> {
         match self {
             KindState::ScrollingMessage(smf) => Some(&smf.lines),
@@ -234,8 +102,7 @@ impl KindState {
         }
     }
 
-    /// The message kinds' sweep-skip generation ([`ScrollingMessageState::lines_gen`]);
-    /// `None` for every other kind.
+    /// The message kinds' sweep-skip generation ([`ScrollingMessageState::lines_gen`]).
     pub fn lines_gen(&self) -> Option<u64> {
         match self {
             KindState::ScrollingMessage(smf) => Some(smf.lines_gen),
@@ -244,11 +111,10 @@ impl KindState {
         }
     }
 
-    /// [`Self::message_lines`], mutably — the measure round-trip's write-back half.
+    /// [`Self::message_lines`], mutably, for the measure's write-back.
     pub fn message_lines_mut(&mut self) -> Option<&mut VecDeque<MessageLine>> {
         match self {
-            // Any mut borrow through this door counts as a text change for the measure sweep's
-            // skip token — conservative, and the door every write-back path uses.
+            // Any mutable borrow counts as a text change for the measure sweep's skip token.
             KindState::ScrollingMessage(smf) => {
                 smf.lines_gen = smf.lines_gen.wrapping_add(1);
                 Some(&mut smf.lines)
@@ -262,67 +128,34 @@ impl KindState {
     }
 }
 
-/// A tooltip's anchor mode — the reference's `+0x318`, which `SetOwner 0x5310d0` writes and
-/// `GetAnchorType 0x5313e0` reads back through the 9-entry jump table `.rdata 0x531530`.
-///
-/// **The id order below is the jump table's, and it is NOT the setter's compare order**: the
-/// setter compares `ANCHOR_BOTTOMRIGHT` third and stores it as id 3 while comparing
-/// `ANCHOR_BOTTOMLEFT` fourth and storing it as id 2; the getter's arm *bodies* sit in `.text` in
-/// that same compare order, corroborating it (decision 2176).
-///
-/// **All nine modes are reachable.** `SetOwner`'s absent / non-string / unrecognised argument is
-/// mode **0** = [`TooltipAnchor::Left`], silently — the binding zero-initialises its local at
-/// `0x53120d` and neither the `lua_isstring` gate nor the compare chain's fall-through raises.
-///
-/// **What each mode does to the placement** (`0x52fe90`, read contiguously): a NULL owner returns
-/// at once; mode **8** returns at `0x52fead`, *before* the clear; every other mode reaches
-/// `0x52fec2 call 0x767ed0` (ClearAllPoints) — the mode-7 skip beside it is gated on an arg1
-/// `SetOwner`'s core always passes as 1 — and then modes **0..5** take the SetPoint jump table
-/// `0x52ffbc` while **6** and **7** stop there. So: 0..5 clear and point, 6 and 7 clear, 8 does
-/// neither.
+/// A tooltip's anchor mode (`+0x318`), set by `SetOwner` (`0x5310d0`), which reads a missing or
+/// unknown mode as [`TooltipAnchor::Left`] (`0x53120d`). The ids follow `GetAnchorType`'s table
+/// (`0x5313e0`, `0x531530`), not the setter's compare order. Placement (`0x52fe90`): modes 0..5
+/// clear the anchors and point, 6 and 7 only clear, 8 does neither.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub enum TooltipAnchor {
-    /// `ANCHOR_LEFT` — the plate's right edge on the owner's left.
+    /// `ANCHOR_LEFT`: the plate's right edge on the owner's left.
     Left,
-    /// `ANCHOR_RIGHT` — the plate's left edge on the owner's right; the stock UI's overwhelming
-    /// default (87 of the 123 `ANCHOR_*` mentions in 1.12's FrameXML).
+    /// `ANCHOR_RIGHT`: the plate's left edge on the owner's right.
     Right,
-    /// `ANCHOR_BOTTOMLEFT`.
     BottomLeft,
-    /// `ANCHOR_BOTTOMRIGHT`.
     BottomRight,
-    /// `ANCHOR_TOPLEFT`.
     TopLeft,
-    /// `ANCHOR_TOPRIGHT`.
     TopRight,
-    /// `ANCHOR_CURSOR` — mode 6: the anchors are cleared, and then the plate is re-anchored to the
-    /// live cursor **every frame** by the class's own update override `0x530b20`
-    /// (`script::tooltip::cursor_anchor` carries the law). Nine corpus files ask for it — `pfUI`'s
-    /// tooltip, xpbar and chat modules, `pfQuest/browser.lua`, `TipBuddy`.
+    /// `ANCHOR_CURSOR`: re-anchored to the live cursor every frame by the update `0x530b20`.
     Cursor,
-    /// `ANCHOR_NONE` — mode 7: the anchors are cleared and no `SetPoint` follows, leaving the
-    /// caller to point the plate (`GameTooltip_SetDefaultAnchor` does exactly that on the next
-    /// line, and that clear is what keeps a stale owner anchor from winning the frame a caller
-    /// forgets to re-point).
-    ///
-    /// **The default here**, which is a benilla choice rather than a read byte: the ctor
-    /// `0x529240` does not write `+0x318` at all, so what a never-owned plate holds depends on the
-    /// allocator, and `GetAnchorType` answers `"ANCHOR_NONE"` for anything out of range
-    /// (`0x53146f ja` shares the id-7 arm). ANCHOR_NONE is therefore the answer that is right
-    /// under the widest reading, and it is the one `pfUI/modules/tooltip.lua:97` compares against.
-    /// It is **not** `SetOwner`'s omitted-argument default, which is mode 0 — see the type doc.
+    /// `ANCHOR_NONE`: cleared, and the caller points the plate. The default here: the ctor
+    /// `0x529240` never writes `+0x318`, leaving the reference's start value to its allocator,
+    /// and the getter answers this for any out-of-range id (`0x53146f`).
     #[default]
     None,
-    /// `ANCHOR_PRESERVE` — mode 8: the owner is recorded and the previous placement is kept
-    /// *including its anchors* — `0x52fe90` returns at `0x52fead`, before the ClearAllPoints that
-    /// every other mode reaches. That clear-vs-keep split is the entire difference between this
-    /// and [`TooltipAnchor::None`]. Stored like any other mode, so `GetAnchorType` answers
-    /// `"ANCHOR_PRESERVE"` after one — the reference does not resolve it back to what it preserved.
+    /// `ANCHOR_PRESERVE`: the previous placement and its anchors are kept (`0x52fe90` returns at
+    /// `0x52fead`, before the clear); `GetAnchorType` still answers `"ANCHOR_PRESERVE"`.
     Preserve,
 }
 
 impl TooltipAnchor {
-    /// The reference's own spelling, as `GetAnchorType()` answers it (table `0x531530`).
+    /// The name `GetAnchorType()` answers (table `0x531530`).
     pub const fn name(self) -> &'static str {
         match self {
             TooltipAnchor::Left => "ANCHOR_LEFT",
@@ -338,256 +171,126 @@ impl TooltipAnchor {
     }
 }
 
-/// A `GameTooltip`'s runtime state (decision 0274). The line *text/color/wrap* is not duplicated
-/// here — each line pair is a real named FontString region (`<name>TextLeftN`/`TextRightN`,
-/// engine-created on demand, published as Lua globals exactly like the real template's 30
-/// pre-declared pairs, which reference Lua addresses by name: `GameTooltipTextLeft1:SetTextColor`).
-/// The state carries what the C++ class carries beside its strings: the live line count, the
-/// owner + the region pool, the minimum width, and the fade clock.
-///
-/// Layout is engine-side (`script::tooltip::layout_tooltips`, a `resolve` pre-pass): frame size =
-/// max measured line width + 2·[`TOOLTIP_PAD`] × summed line heights + gaps, right columns
-/// re-pointed flush to the text inset — the job the real client's C++ line layout does over the
-/// template's static anchors (today's Lua `OnUpdate` measure loop, retired).
+/// A `GameTooltip`'s state. Its lines are FontString regions named `<name>TextLeftN`/`TextRightN`,
+/// made on demand and published as Lua globals, as the stock template's 30 pairs are.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TooltipState {
     /// Lines currently filled (`NumLines`). Regions past this index exist but are hidden.
     pub num_lines: usize,
-    /// The left-column FontString pool, index i = line i+1. Grown on demand — no line cap (the
-    /// real template ships 30 pairs and the class grows via `AddFontStrings`; one mechanism here).
+    /// The left-column FontString pool, index i = line i+1, grown on demand with no line cap.
     pub left_lines: Vec<RegionHandle>,
     /// The right-column pool (the `AddDoubleLine`/`TextRightN` half), parallel to `left_lines`.
     pub right_lines: Vec<RegionHandle>,
-    /// `SetOwner`'s frame — dropped on hide (`IsOwned` is the hover re-enter loop's gate,
-    /// ref `ContainerFrame.lua` OnUpdate).
+    /// `SetOwner`'s frame, dropped on hide.
     pub owner: Option<FrameHandle>,
-    /// The anchor mode the last `SetOwner` placed this plate by, read back by `GetAnchorType()` —
-    /// the reference's `+0x318`.
+    /// The last `SetOwner`'s mode, read back by `GetAnchorType()`.
     pub anchor: TooltipAnchor,
-    /// `SetMinimumWidth(w)` — a floor on the auto-sized width (the ref's money-row floor).
-    /// Cleared (0.0) by `ClearLines`/hide, like the content.
+    /// `SetMinimumWidth`: a floor on the auto-sized width, cleared with the content.
     pub min_width: f32,
-    /// `FadeOut()`'s start on the `GetTime` clock; `None` = not fading. Any fresh content
-    /// (SetOwner/SetText/AddLine/Show) cancels the fade and restores full alpha.
+    /// `FadeOut()`'s start on the `GetTime` clock; any fresh content or `Show` cancels the fade.
     pub fade_start: Option<f64>,
-    /// The unit token this tooltip currently shows (`SetUnit`/the world mouseover) — the health
-    /// watcher's key: a `set_unit` push for this token re-drives the status bar (decision 0276's
-    /// verified refresh law). Dropped with the content.
+    /// The unit this tooltip shows; a `set_unit` push for it re-drives the health bar.
     pub unit_token: Option<String>,
-    /// This tooltip currently shows WORLD-hover content (a mouseover unit, GameObject, or
-    /// corpse) — the fade-on-loss gate (`world_tooltip_fade`); a window hover never fades.
-    /// Dropped with the content.
+    /// Shows world-hover content, which fades when the hover is lost; a window hover never fades.
     pub world_owned: bool,
-    /// ARMED for a shopping-compare render: the next `SetInventoryItem` on this frame prepends the
-    /// gray "Currently Equipped" line — the builder's p5 `[arg+0x18]≠0` and NOTHING else. It is
-    /// deliberately not the neighbouring p4 `[arg+0x14]` (compact: white name, stat body jumped,
-    /// cut at `0x52e14c`), which both compare call sites pass as zero; conflating the two is what
-    /// made our shopping plates paint an epic's name white and drop its description (2216). Set by
-    /// the engine right before it fills a shopping plate, and consumed by that render. Survives
-    /// `SetOwner`'s content clear, because the reference's own compare caller
-    /// (`MerchantFrame.xml:67-72`) SetOwners *between* the arm and the render; how the real engine
-    /// plumbs the flag to `0x52b650` is unrecorded, so this seam is the INTERIM model of it.
+    /// Armed for a compare render: the next `SetInventoryItem` prepends "Currently Equipped"
+    /// (`[arg+0x18]`, not the compact `[arg+0x14]`), surviving the stock caller's `SetOwner` in
+    /// between (`MerchantFrame.xml:67-72`); the reference's route to `0x52b650` is untraced.
     pub equipped_header_armed: bool,
-    /// `SetPadding(w)` — extra width beyond the measured content (ref ItemRefTooltip's
-    /// OnLoad `SetPadding(16)`: room for the corner close button). 0 for ordinary tooltips.
+    /// `SetPadding`: extra width past the content (`ItemRef.xml:40` sets 16 for the close button).
     pub padding: f32,
-    /// Line 1 was ADOPTED from XML-declared regions (`<name>TextLeft1` in the instance/template
-    /// — ShoppingTooltipTemplate's small-font ladder): lines the engine creates past the
-    /// declared set clone the previous line's faces instead of the header/text defaults, the
-    /// real class's grow-past-the-template behavior.
+    /// Line 1 came from XML (`ShoppingTooltipTemplate`), so later lines clone the previous fonts.
     pub xml_declared_lines: bool,
 }
 
-/// The tooltip plate's text inset — the real template seats `TextLeft1` at TOPLEFT (10,−10).
+/// The plate's text inset: the stock template seats `TextLeft1` at TOPLEFT (10, −10).
 pub const TOOLTIP_PAD: f32 = 10.0;
-/// Inter-line gap — each `TextLeftN` hangs at the previous line's BOTTOMLEFT (0,−2).
+/// The line gap: each `TextLeftN` hangs at the previous line's BOTTOMLEFT (0, −2).
 pub const TOOLTIP_LINE_GAP: f32 = 2.0;
-/// The minimum gap between a double line's columns. INFERRED from the ref template's static
-/// `TextRightN` offset (+40 off its partner); the C++ layout that owns the real gap isn't RE'd —
-/// this is the eyeball knob if a double line reads too wide/tight (carried over from the
-/// pre-0274 Lua tooltip).
+/// The least double-line column gap, the stock `TextRightN` offset; the reference's is untraced.
 pub const TOOLTIP_DOUBLE_GAP: f32 = 40.0;
-/// `FadeOut`'s ramp length, seconds. INTERIM pending the 0274 §5 lifecycle verdict (the world-
-/// mouseover tooltip's fade constant lives in the untraced SetUnit/mouseover path).
+/// `FadeOut`'s ramp length in seconds; the reference's constant is untraced.
 pub const TOOLTIP_FADE_SECS: f64 = 0.5;
-/// The width a wrap-flagged line wraps at, logical px — pinned onto the line region at APPEND
-/// time (`append_line`), so its first measure comes back wrapped. INTERIM pending the 0274 §5
-/// (the real wrap column lives in the untraced C++ line layout); sized against the reference's
-/// description/trigger-line wrap by eye.
+/// A wrap-flagged line's width, pinned when it is appended; the reference's column is untraced.
 pub const TOOLTIP_WRAP_WIDTH: f32 = 260.0;
 
-/// The model-pane scene state — **shared by [`FrameKind::Model`] and [`FrameKind::PlayerModel`]**,
-/// because the client's `CGCharacterModelBase` (`0x505680`) *extends* `CSimpleModel` (`0x76c8e0`)
-/// rather than replacing it: every field below is a `CSimpleModel` member both classes carry.
-///
-/// **What this is and is not.** The 1.12 `Model` widget is a viewport that draws one M2 in a
-/// little scene of its own — the character pane, the tabard designer, the minimap ping, the pet
-/// bar's autocast shine, and every addon that wants a 3D thing in a frame. The engine core holds
-/// exactly the scene an addon can read back or write; **the render is the app's**, the same
-/// contract [`MinimapState`] already runs under, and the reason both exist as state-only kinds
-/// here.
-///
-/// **Every field is a 1.12 binding's storage, and which binding is read off the registrar, not off
-/// a string scan.** Read at the pair bytes: `Model`'s table is `0x878948` with **23** entries,
-/// `PlayerModel`'s is `0x84f1fc` with **3**, and the derived table never repeats its base's. The
-/// earlier justification for these fields — "the names are in the binary as isolated strings" — is
-/// the mistake: a `strings` hit answers *whether a name exists*, never *which table owns it*, and
-/// `SetUnit`'s single pooled string `0x84f22c` is referenced by two entries in two different
-/// tables. Ownership now comes from a dword-reference count over the name's VA.
-///
-/// **All 23 of `Model`'s are published** (decision 2027 carved the last seven — `AdvanceTime`,
-/// `ReplaceIconTexture` and the fog near/far/clear set). `script::tests::modelframe`'s `UNBUILT`
-/// array is the live count and is empty; the wall around it is what notices a name arriving or
-/// leaving (1134 §4's naming rule, with nothing left to name).
+/// A model pane's scene: the `CSimpleModel` (`0x76c8e0`) members every model kind carries, read
+/// and written by `Model`'s 23 methods (table `0x878948`); the render is the app's.
 #[derive(Clone, Debug, PartialEq)]
 pub struct ModelState {
-    /// The M2/MDX path last given to `SetModel`, or `None` after `ClearModel` / before any set.
-    /// Stored **as written** — the client's own path space is `Interface\...\Foo.mdx`, and the
-    /// app's loader is what maps `.mdx` to the `.m2` that actually ships.
+    /// `SetModel`'s path as written (`.mdx`); the app's loader maps it to the shipped `.m2`.
     pub path: Option<String>,
-    /// `PlayerModel:SetUnit(unit)` — the *other* way a pane gets its content, used by the dress-up
-    /// and paper-doll frames. Mutually exclusive with [`Self::path`] in practice: whichever was set
-    /// last is what the pane shows, so each setter clears the other.
-    ///
-    /// The field lives on every pane because it is a `CSimpleModel` member; the **setter** does
-    /// not — `SetUnit` is [`FrameKind::PlayerModel`]'s (`0x84f1fc[0]` → `0x505d70`), and a plain
-    /// `<Model>` has no way to reach it.
+    /// `PlayerModel:SetUnit`'s unit (`0x505d70`); it and [`Self::path`] each clear the other.
     pub unit: Option<String>,
-    /// `SetSequence(n)` — the last animation id asked for (the raw id lands in
-    /// `[bone0 block + 0xf8]`, which `PlayerModel`'s per-paint stomp reads). What actually
-    /// PLAYS is [`Self::armed`].
+    /// The last `SetSequence` id (`[bone0 block + 0xf8]`); what plays is [`Self::armed`].
     pub sequence: i32,
-    /// **The widget's private scene clock**, milliseconds — `[scene+0xc]` of the `CM2Scene` the
-    /// widget owns (`0x76cfc0`, cached at `+0x314`; never the world's `[0xc7b298]`). Advanced by
-    /// the widget's own `OnUpdate` (`0x76d7f0`: `trunc(elapsed · 1000)`, no `+0.5`), which the UI
-    /// pump walks for **visible** frames only — so a hidden pane's clock stands still and a
-    /// re-shown one resumes where it stopped (the minimap ping's "ping N resumes where ping N−1
-    /// left off"). Nothing else advances it: `AdvanceTime` is inert. The scene outlives the
-    /// model, so `SetModel` does not reset it. Decision 2007.
+    /// The pane's own scene clock in ms (`0x76cfc0`): its `OnUpdate` (`0x76d7f0`) adds
+    /// `trunc(elapsed · 1000)` only while shown; `AdvanceTime` is inert, `SetModel` keeps it.
     pub clock_ms: u64,
-    /// What is armed on bone slot 0 — the sequence the pane plays and the anchor its cursor is
-    /// read against. `None` while nothing plays: before any file, after `ClearModel`, or after
-    /// a `SetSequence` naming an id the file does not own (which stops what was playing and
-    /// arms nothing — `0x7121a0`'s interrupt runs before its bounds check).
+    /// The sequence on bone slot 0. A `SetSequence` id the file does not own stops what played
+    /// and arms nothing (`0x7121a0` interrupts before its bounds check).
     pub armed: Option<ArmedSequence>,
-    /// `SetModel` ran but the loader's own arm has not — the file's facts ([`ModelFileFacts`])
-    /// were not known at the call. The reference links the instance as a waiter for the
-    /// streaming drain and runs the completion (`0x70ebd0`: arm Stand, variation 0) when the
-    /// asset lands; [`ModelState::seed_from_facts`] is that completion, run when the host hands
-    /// the facts over.
+    /// `SetModel` ran and the loader's completion ([`ModelState::seed_from_facts`]) awaits facts.
     pub pending_seed: bool,
-    /// `ReplaceIconTexture(path)` — the type-14 texture override (`0x76cfe0(0xe, path)` →
-    /// `0x710ec0`), which lives on the model instance and dies with it: `SetModel` and
-    /// `ClearModel` clear it. `None` = the file's own textures.
+    /// `ReplaceIconTexture`'s override (`0x76cfe0`); `SetModel` and `ClearModel` drop it.
     pub icon: Option<String>,
-    /// The frame's size is the **implicit rect** — the file's bounding-box extent in layout units
-    /// (`bboxExtent · 768·√(a²+1)` FrameXML units, the `0x6f1eb0` unit conversion),
-    /// written by the engine because the pane authored no size (decision 2015). The geometry
-    /// getters `0x76d080`/`0x76d0d0` answer it whenever no size is authored; here it is written
-    /// into the layout input when the file's facts land and re-derived when the screen's aspect
-    /// moves, and an authored `SetWidth`/`SetHeight` clears it for good.
+    /// No size authored: the pane takes the file's box extent, `bboxExtent · 768·√(a²+1)` units
+    /// (`0x6f1eb0`, `0x76d080`), re-derived on aspect change; an authored size clears it for good.
     pub implicit_size: bool,
-    /// The pane's yaw in radians — `CSimpleModel+0x39c`. **One slot, written by two verbs on two
-    /// different classes**: `Model:SetFacing` (`0x76dce0`) and `PlayerModel:SetRotation`
-    /// (`0x505f00` → `0x505bb0`, whose last act is `0x505c44 mov [esi+0x39c], eax` — literally the
-    /// same field). That is why the reference's rotate buttons can drive a paper-doll pane through
-    /// `SetRotation` and `GetFacing` reads it back.
+    /// Yaw in radians (`+0x39c`), one slot written by both `Model:SetFacing` (`0x76dce0`) and
+    /// `PlayerModel:SetRotation` (`0x505f00`), so `GetFacing` reads either back.
     pub facing: f32,
-    /// `SetModelScale` — the model's own scale within the pane, default 1.
+    /// `SetModelScale`: the model's scale within the pane, default 1.
     pub scale: f32,
-    /// The **pending** camera index (`CSimpleModel+0x320`) — `Some(n)` while the camera question
-    /// is open, `None` once it is settled. The ctor writes `Some(0)`, a standing request for raw
-    /// camera 0, which the model-ready hook applies ([`ModelState::seed_from_facts`]); `SetCamera`
-    /// with no facts yet defers into it (`0x76cec0`'s two early legs). **While it is `Some`, the
-    /// pane draws nothing at all** — the reference's draw gate is
-    /// `76d5f0 cmp [this+0x320],-1 ; jne <skip everything>` (decision 2027).
+    /// The camera index still to install (`+0x320`): the ctor's `Some(0)`, or a `SetCamera` made
+    /// before the facts (`0x76cec0`). While it is `Some` the pane draws nothing (`0x76d5f0`).
     pub camera_pending: Option<i32>,
-    /// The **installed** camera (`+0x31c`) as a RAW index into the file's camera table, or `None`
-    /// for the NULL camera — which is what an index past the table's count installs (`76cf08`)
-    /// and what a file with no cameras always gets. `None` is the **orthographic** render leg;
-    /// `Some(n)` is the perspective one, framed by the file's own record `n`.
-    ///
-    /// Raw is the whole point: `0x76cec0` reads the count off `MD20+0x124` and the record at
-    /// `[model+0x3c4] + idx·0x84 + 0x80`, and **never consults `cameraLookup`** — that array is
-    /// the portrait bake's path.
+    /// The installed camera (`+0x31c`): a raw camera-table index, never via `cameraLookup`, drawn
+    /// in perspective; `None`, the NULL camera an out-of-range index installs, draws orthographic.
     pub camera: Option<u32>,
-    /// `SetPosition(x, y, z)` — the model's offset within the pane's scene.
+    /// `SetPosition`: the model's offset within the pane's scene.
     pub position: (f32, f32, f32),
-    /// The pane's embedded `CGLight` (`CSimpleModel+0x324`) — see [`ModelLight`]. Typed since
-    /// decision 2027, once every field, its consumer and both of `SetLight 0x76e1e0`'s traps were
-    /// established, so the tuple no longer has to be stored opaquely.
     pub light: ModelLight,
-    /// `SetFogColor(r, g, b, a)` as the reference stores it: **one packed `0xAARRGGBB` dword**,
-    /// which is why its getter is four values wide and why a Set→Get round trip is **lossy** —
-    /// eight bits per channel (decision 1845).
-    ///
-    /// `0xffff_ffff` is the ctor's own terminal write, so the never-set answer is `1, 1, 1, 1` and
-    /// not four zeros. It used to be `Option<(f32, f32, f32)>` here: three components, no alpha,
-    /// and `None` for unset — every one of those three wrong.
-    ///
-    /// All seven fog verbs are built as of decision 2027 — this pair plus
-    /// `SetFogNear`/`GetFogNear`/`SetFogFar`/`GetFogFar`/`ClearFog`.
+    /// `SetFogColor` as the reference stores it, one packed `0xAARRGGBB` dword, so a round trip
+    /// keeps 8 bits a channel; the ctor's `0xffff_ffff` reads back as `1, 1, 1, 1`.
     pub fog_color: u32,
-    /// `+0x3a4` **bit 0** — fog armed. Set by `SetFogColor` (`76f059 or [edi+0x3a4],1`) and by the
-    /// XML `<FogColor>` child; cleared by `ClearFog` (`76f5c5 and [edi+0x3a4],-2` — **bit 0 only**,
-    /// so the colour, near and far all survive a clear and come back on the next `SetFogColor`).
-    /// The ctor leaves it off.
+    /// Fog armed (`+0x3a4` bit 0): set by `SetFogColor` and `<FogColor>`, cleared by `ClearFog`,
+    /// which leaves colour, near and far for the next `SetFogColor`.
     pub fog: bool,
-    /// `+0x3ac` — fog near, raw and unclamped from `SetFogNear` (`76f282 fstp`), clamped at `≥ 0`
-    /// only on the XML `fogNear` attribute path (`76cbbb`). Ctor `0.0`.
+    /// Fog near (`+0x3ac`): unclamped from `SetFogNear`, clamped `≥ 0` only from XML `fogNear`.
     pub fog_near: f32,
-    /// `+0x3b0` — fog far, same shape as [`Self::fog_near`] (`76f432`, XML `fogFar` at `76cbf3`).
-    /// **Ctor `1.0`**, not `0.0`: the fill callback stages `1/(far − near)` and the batch fogs
-    /// only when that is `> 0`, so the ctor's pair is already a valid (if tiny) ramp.
+    /// Fog far (`+0x3b0`), shaped like [`Self::fog_near`]; the ctor's is `1.0`.
     pub fog_far: f32,
 }
 
-/// A model pane's **armed** fog — [`ModelState::armed_fog`]'s answer, and the whole of what the
-/// renderer needs: the disarmed values are engine state that nothing draws.
+/// A model pane's armed fog, all the renderer needs ([`ModelState::armed_fog`]).
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct ModelFog {
-    /// The packed `0xAARRGGBB` colour (`+0x3a8`). The alpha byte exists and is **never read** by
-    /// the fill callback (`0x76d680` takes bytes 2,1,0 only).
+    /// The packed `0xAARRGGBB` colour (`+0x3a8`); the fill callback `0x76d680` never reads alpha.
     pub color: u32,
-    /// `+0x3ac` / `+0x3b0`, raw. The fill stages `1/(far − near)` and a batch fogs only when that
-    /// is `> 0`, so a `far <= near` pair arms the flag and still draws unfogged.
+    /// Raw near and far (`+0x3ac`/`+0x3b0`); a batch fogs only when `1/(far − near) > 0`, so
+    /// `far <= near` draws unfogged.
     pub near: f32,
     pub far: f32,
 }
 
 impl ModelFog {
-    /// The colour as linear `[r, g, b]` in `0..=1` — the fill callback's own unpack
-    /// (`0x7bbf20` -> bytes 2,1,0 × 1/255).
+    /// The colour as `[r, g, b]` in `0..=1`, the fill callback's unpack (`0x7bbf20`).
     pub fn rgb(&self) -> [f32; 3] {
         [16, 8, 0].map(|shift| ((self.color >> shift) & 0xff) as f32 / 255.0)
     }
 }
 
-/// A model pane's embedded **`CGLight`** — the 0x6c-byte object at `CSimpleModel+0x324` that the
-/// per-paint fill callback `0x76d680` adds to the model's light collector, and the only light a
-/// `<Model>` widget has.
-///
-/// **A plain `<Model>`'s is DISABLED and stays that way unless Lua enables it.** The ctor
-/// `0x76c8e0` leaves `+0x60 = 0`, so `0x71bf90` returns before adding anything and the collector
-/// finalizes with zero ambient and zero diffuse — under which a LIT batch draws **black**. That
-/// is harmless by asset design (every in-game UI M2 is UNLIT on every material, measured across the
-/// reference's own assets) and it is the faithful answer for an addon's lit one. `<PlayerModel>`'s
-/// ctor `0x505680` enables its own instead, which is why the paper doll is lit; those panes are the
-/// portrait booth's, not this widget's.
-///
-/// Each colour is stored **already multiplied by its intensity** — `SetLight` folds
-/// `rgb/255 × intensity` before the copy — which is why there is no separate intensity field.
+/// A model pane's embedded `CGLight` (`+0x324`), its only light (`0x76d680`): off on a plain
+/// `<Model>` until Lua enables it, so a lit batch draws black (`0x71bf90`), and on for a
+/// `PlayerModel` (ctor `0x505680`). Colours are stored times their intensity.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct ModelLight {
-    /// `CGLight+0x60` — enabled. `SetLight`'s first argument writes it, and **only when nonzero**:
-    /// `SetLight(0, …)` returns at `76e2cb` without touching the widget at all, so it is not a
-    /// way to turn a light off.
+    /// `+0x60`: set by a nonzero `SetLight` (`0x76e1e0`) first argument; `SetLight(0, …)` is inert.
     pub enabled: bool,
-    /// `+0x08` — type. `true` = point/omni (`1`, what both ctors write), `false` = directional.
-    /// Chooses which of the two vector setters `SetLight`'s `(x, y, z)` reaches.
+    /// `+0x08`: point (`1`, both ctors) or directional; picks where `SetLight`'s `(x, y, z)` goes.
     pub omni: bool,
-    /// `+0x0c` position (when [`Self::omni`]) or `+0x24` direction (when not) — the direction is
-    /// **normalised on write** by `0x71b6a0`, and is a *from-light* vector.
+    /// Position (`+0x0c`), or a directional light's from-light direction (`+0x24`), normalised.
     pub vector: [f32; 3],
     /// `+0x30` ambient, intensity already folded in.
     pub ambient: [f32; 3],
@@ -595,9 +298,7 @@ pub struct ModelLight {
     pub diffuse: [f32; 3],
 }
 
-/// The `<Model>` ctor's light (`0x76c8e0`): `0x71b4a0` (type 1, everything else zero), then
-/// enabled `0` at `76c99c`, type `1` at `76c9a5`, ambient `(1,1,1)` at `76c9b4`–`76c9d3` and
-/// diffuse `(1,1,1)` at `76c9d6`–`76c9ff`. White, and switched off.
+/// The `<Model>` ctor's light (`0x76c8e0`, `0x71b4a0`): white, and switched off.
 impl Default for ModelLight {
     fn default() -> Self {
         Self {
@@ -610,11 +311,7 @@ impl Default for ModelLight {
     }
 }
 
-/// A fresh `Model` pane: no content, sequence 0, unrotated, unit scale, camera 0, at the origin.
-///
-/// `scale` is the one field whose zero value would be wrong — a model at scale 0 is invisible, and
-/// the widget's documented default is 1 — so [`ModelState`] cannot use a derived `Default` for it
-/// and this impl exists to say why.
+/// A fresh pane as the `CSimpleModel` ctor leaves it.
 impl Default for ModelState {
     fn default() -> Self {
         Self {
@@ -640,105 +337,75 @@ impl Default for ModelState {
     }
 }
 
-/// What a pane's bone slot 0 is playing — the reference's `0x7121a0` arm (`SetSequence`
-/// `0x76dec0` → `0x76cf50`, `SetSequenceTime` `0x76dfc0` → `0x76cf80`, and the loader's own
-/// seed `0x70ebd0`): the id, and the **anchor** the cursor is read against. The reference
-/// bakes `cursor_lo = sceneClock − trunc(ms)` once and its sampler re-reads that anchor every
-/// frame; there is no counter that advances on its own, which is what lets the cooldown scrub
-/// the pane every paint without the clock fighting it. Decision 2007.
+/// What bone slot 0 plays, as the `0x7121a0` arm leaves it: the id and the anchor the cursor
+/// counts from, with no counter of its own, so a caller can scrub the pane every paint.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct ArmedSequence {
-    /// The `AnimationData.dbc` id — `SetSequence`'s argument, or the loader's Stand seed.
+    /// The `AnimationData.dbc` id: `SetSequence`'s argument, or the loader's Stand seed.
     pub anim_id: i32,
-    /// The scene-clock value the cursor counts from: `cursor = clock_ms − anchor_ms`, so a
-    /// `SetSequenceTime(id, ms)` at clock `c` stores `c − ms`.
+    /// The clock value the cursor counts from: `SetSequenceTime(id, ms)` at `c` stores `c − ms`.
     pub anchor_ms: i64,
-    /// The scene clock when the arm was made — so a queued arm (made before the file's facts
-    /// were known) can replay at residency with its original offset: `armed_at − anchor` is the
-    /// `ms` the call asked for.
+    /// The clock at the arm, so an arm queued behind the load replays with its offset.
     pub armed_at_ms: u64,
-    /// The completion callback has fired for this arm — the sequence ran its length (a clamp's
-    /// end, or a loop's first pass) and the widget's `OnAnimFinished` ran. Once per arm: a
-    /// re-arm starts a fresh one.
+    /// `OnAnimFinished` has fired for this arm; it fires once per arm.
     pub finished: bool,
 }
 
-/// The playing sequence's cursor, as the renderer samples it — [`ModelState::play_head`]'s
-/// answer under the file's facts.
+/// The playing sequence's cursor, as the renderer samples it ([`ModelState::play_head`]).
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct ModelPlayHead {
-    /// The `AnimationData.dbc` id of the armed sequence (the file owns it — see
-    /// [`ModelFileFacts::owns`]).
+    /// The armed sequence's `AnimationData.dbc` id, one the file owns.
     pub anim_id: u16,
-    /// Milliseconds into the sequence: wrapped for a looping one, held at the last frame for a
-    /// clamped one that has completed.
+    /// Milliseconds in: wrapped when looping, held at the end when clamped.
     pub cursor_ms: u32,
 }
 
-/// One sequence of a model file, as the clock needs it — see [`ModelFileFacts`].
+/// One sequence of a model file, as the pane clock needs it.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct SequenceFacts {
     /// The `AnimationData.dbc` id (`M2Sequence+0x00`).
     pub anim_id: u16,
     /// The sequence's length, `end − start` on the file's timeline (`+0x08 − +0x04`).
     pub duration_ms: u32,
-    /// The sequence loops (the flag the formats crate decodes as `looping`); a clamped one
-    /// holds its last frame and fires the completion callback once.
+    /// Loops; a clamped sequence holds its last frame.
     pub looping: bool,
 }
 
-/// What the engine needs to know about a model **file** to run a pane's clock — the reference
-/// reads these off the resident `MD20` (`animationLookup` at `md20+0x24`, the sequence table,
-/// the header bounds); here the host's M2 loader has them and hands them over through
-/// `UiScript::set_model_facts` once the asset lands. Keyed by the `SetModel` path
-/// ([`model_key`]), shared by every pane holding that file. Decision 2007.
+/// What a pane needs from its model file, which the reference reads off the resident `MD20`; the
+/// host hands it over (`UiScript::set_model_facts`), keyed by [`model_key`].
 #[derive(Clone, Debug, PartialEq)]
 pub struct ModelFileFacts {
-    /// The sequences the file owns, **in file order** — the first is `animations[0]`, the
-    /// loader's fallback seed when the file does not own id 0.
+    /// The file's sequences in file order; the first is the seed when id 0 is missing.
     pub sequences: Vec<SequenceFacts>,
-    /// The header bounding box, raw WoW model space (`min`, `max`) — the implicit rect of a
-    /// size-less `<Model>` (`0x76d080`/`0x76d0d0`) and the arrow's re-centring.
+    /// The header bounding box `(min, max)` in model space.
     pub bbox: ([f32; 3], [f32; 3]),
-    /// How many records the file's **camera table** holds (`MD20+0x124`) — the bound
-    /// `Model:SetCamera(n)` is checked against (`0x76cec0`: `76ceeb if idx >= count -> install
-    /// NULL`). `0` for the overwhelming majority of models, which is why a plain `<Model>` almost
-    /// always ends on the orthographic leg. Decision 2027.
+    /// The camera table's size (`MD20+0x124`), `SetCamera`'s bound (`0x76cec0`); 0 for most models.
     pub cameras: u32,
 }
 
 impl ModelFileFacts {
-    /// Does the file own `anim_id` — the reference's `0x711960` ("does `animationLookup` map
-    /// it"): a model owns an id iff some sequence carries it.
+    /// Whether the file owns `anim_id`: `0x711960`'s `animationLookup` test.
     pub fn owns(&self, anim_id: u16) -> bool {
         self.sequences.iter().any(|s| s.anim_id == anim_id)
     }
 
-    /// The sequence `SetSequence(anim_id)` plays: the id's **first** file slot — variation 0,
-    /// which is what both the loader's seed and the widget's arm pass (`0x7121a0`'s third
-    /// argument is `0`, never `-1`, on this path).
+    /// The sequence `SetSequence(anim_id)` plays: the id's first slot, variation 0 (`0x7121a0`).
     pub fn sequence(&self, anim_id: u16) -> Option<&SequenceFacts> {
         self.sequences.iter().find(|s| s.anim_id == anim_id)
     }
 
-    /// The header bounding box's `(x, y)` extent in model units — the implicit rect of a size-less
-    /// pane (`0x76d080`/`0x76d0d0`) and the arrow's re-centring (`0x4a7b20`: `½·GetWidth`,
-    /// `½·GetHeight`, both the geometry override's bbox extent).
+    /// The box's `(x, y)` extent, a size-less pane's implicit rect (`0x76d080`/`0x76d0d0`).
     pub fn extent(&self) -> (f32, f32) {
         let (min, max) = self.bbox;
         ((max[0] - min[0]).max(0.0), (max[1] - min[1]).max(0.0))
     }
 
-    /// Which camera raw index `idx` installs: `Some(idx)` when the table has it, `None` — the
-    /// **NULL** camera, i.e. the orthographic leg — when it does not. Negative indices land in the
-    /// same place the reference's unsigned `jae` puts them.
+    /// The camera raw index `idx` installs; `None`, the NULL camera, out of range or negative.
     pub fn camera_at(&self, idx: i32) -> Option<u32> {
         u32::try_from(idx).ok().filter(|&i| i < self.cameras)
     }
 
-    /// The loader's idle seed (`0x70ebd0`'s tail, `0x710153`–`0x71019b`): **id 0 (`Stand`) if
-    /// the file owns it, else `animations[0]`'s own id**; `None` only for a file with no
-    /// sequences at all.
+    /// The loader's idle seed (`0x70ebd0`): Stand (id 0) if owned, else the first sequence's id.
     pub fn stand_id(&self) -> Option<u16> {
         if self.owns(0) {
             Some(0)
@@ -748,9 +415,7 @@ impl ModelFileFacts {
     }
 }
 
-/// The key a model path is filed under: case-folded, forward slashes, no extension — so
-/// `Interface\Cooldown\UI-Cooldown-Indicator.mdx` and its shipped `.m2` twin are one file, as
-/// they are for the loader.
+/// A model path's key: case-folded, forward slashes, no extension, so `.mdx` and `.m2` match.
 pub fn model_key(path: &str) -> String {
     let p = path.to_ascii_lowercase().replace('\\', "/");
     let stem = p
@@ -762,11 +427,8 @@ pub fn model_key(path: &str) -> String {
 }
 
 impl ModelState {
-    /// `SetModel(path)` — `vt+0x94` (`0x76cce0`): a **fresh instance** of the file (`CreateModel`
-    /// with flags 5), which displaces a unit, drops the previous instance's icon override and
-    /// its arm, and runs the loader's completion (`0x70ebd0`) synchronously when the file is
-    /// resident — [`Self::seed_from_facts`] — else waits for it ([`Self::pending_seed`]). The
-    /// scene clock is the WIDGET's, not the instance's, and keeps running.
+    /// `SetModel` (`0x76cce0`): a fresh instance, dropping unit, icon override and arm, seeded now
+    /// if the file is resident, else when it lands (`0x70ebd0`); the scene clock runs on.
     pub fn set_file(&mut self, path: String, facts: Option<&ModelFileFacts>) {
         self.path = Some(path);
         self.unit = None;
@@ -778,7 +440,7 @@ impl ModelState {
         }
     }
 
-    /// `ClearModel` — releases the instance: no file, no unit, no override, nothing armed.
+    /// `ClearModel`: releases the instance.
     pub fn clear_file(&mut self) {
         self.path = None;
         self.unit = None;
@@ -787,13 +449,8 @@ impl ModelState {
         self.pending_seed = false;
     }
 
-    /// `SetSequence` / `SetSequenceTime` — the `0x7121a0` arm. It **interrupts** whatever plays
-    /// first (the completion callback fires with a non-zero mode there, which the widget's
-    /// `OnAnimFinished` gate ignores — `0x76cdc6`: natural completion only), then arms `id` at `ms`
-    /// into it — or arms nothing when the file does not own the id (the bounds check at
-    /// `71247c` returns having armed nothing). With the facts not known yet the arm is kept and
-    /// re-checked when they land ([`Self::seed_from_facts`]) — the reference's queued replay for
-    /// a file still streaming.
+    /// `SetSequence`/`SetSequenceTime` (`0x7121a0`): interrupts what plays, with no
+    /// `OnAnimFinished` (`0x76cdc6`), then arms `id` at `ms` unless the known file lacks it.
     pub fn arm(&mut self, id: i32, ms: i64, facts: Option<&ModelFileFacts>) {
         self.sequence = id;
         let owned = u16::try_from(id)
@@ -807,12 +464,8 @@ impl ModelState {
         });
     }
 
-    /// The loader's completion for a file that just became resident (`0x70ebd0`), then the
-    /// replay of what was queued behind the load: the seed arms Stand (variation 0); an explicit
-    /// `SetSequence`/`SetSequenceTime` made while the file streamed replays AFTER it — at its
-    /// original offset — and decides the final state, which for an id the file does not own is
-    /// **nothing armed** (the interrupt ran, the bounds check armed nothing). Idempotent once
-    /// the seed has run: a second hand-over of the same facts only re-checks ownership.
+    /// The loader's completion (`0x70ebd0`): arms Stand, then replays an arm queued during the
+    /// load at its offset, which decides the result. A later call only re-checks ownership.
     pub fn seed_from_facts(&mut self, facts: &ModelFileFacts) {
         let queued = self.armed.filter(|_| self.pending_seed);
         if self.pending_seed {
@@ -832,18 +485,13 @@ impl ModelState {
                 self.armed = None;
             }
         }
-        // The model-ready hook's other half (`0x76ce00` `76ce3e`): apply the pending camera index
-        // if the question is still open. The ctor's standing `Some(0)` is what gives a plain
-        // `<Model>` its default camera 0, and it is applied here, once, exactly as the reference
-        // applies it on the asset-ready edge.
+        // The model-ready hook's other half (`0x76ce00`): the pending camera, 0 from the ctor.
         if let Some(idx) = self.camera_pending {
             self.install_camera(idx, Some(facts));
         }
     }
 
-    /// The pane's fog, **only when it is armed** (`+0x3a4` bit 0) — the fill callback's own gate
-    /// (`76d68a test byte [esi+0x3a4],1 ; je`). A disarmed pane stages nothing, and its collector
-    /// keeps the zeroed `1/(far − near)` that the per-batch fog test refuses.
+    /// The pane's fog when armed (`+0x3a4` bit 0), the fill callback's own gate.
     pub fn armed_fog(&self) -> Option<ModelFog> {
         self.fog.then_some(ModelFog {
             color: self.fog_color,
@@ -852,13 +500,8 @@ impl ModelState {
         })
     }
 
-    /// `0x76cec0` — select a camera by RAW table index. With no facts yet (the reference's "no
-    /// model" / "not ready" legs at `76cece`/`76cedb`) the index is **deferred** into
-    /// [`Self::camera_pending`] and nothing draws until it resolves; with facts, the index is
-    /// bounds-checked against the table's count and either installed or answered with the NULL
-    /// camera, and **either way the pending index is cleared** (`0x76ce80`'s
-    /// `76cead mov [esi+0x320],-1` — installing *any* camera, NULL included, settles the
-    /// question).
+    /// `SetCamera` by raw index (`0x76cec0`): deferred until the facts are known, then installed
+    /// or answered with the NULL camera, either clearing the pending index (`0x76ce80`).
     pub fn install_camera(&mut self, idx: i32, facts: Option<&ModelFileFacts>) {
         match facts {
             Some(f) => {
@@ -869,9 +512,7 @@ impl ModelState {
         }
     }
 
-    /// Where the armed sequence stands on the scene clock, under `facts`: wrapped for a looping
-    /// sequence, held at the end for a clamped one. `None` when nothing is armed or the arm names
-    /// a sequence the facts do not carry.
+    /// Where the armed sequence stands on the scene clock under `facts`.
     pub fn play_head(&self, facts: &ModelFileFacts) -> Option<ModelPlayHead> {
         let armed = self.armed?;
         let anim_id = u16::try_from(armed.anim_id).ok()?;
@@ -891,11 +532,8 @@ impl ModelState {
         })
     }
 
-    /// Has the armed sequence run its length without its completion having fired — the edge the
-    /// tick turns into `OnAnimFinished` (the completion callback `0x76cdc0`, `mode == 0`). Once
-    /// per arm, and **for a looping sequence too**: `0x719370` enqueues the completion when the
-    /// widget clock reaches `lo + duration · replays` and tests the loop flag only after it, so a
-    /// loop's first pass completes exactly like a clamp's end (corrects 2007's "clamped only").
+    /// The armed sequence ran its length and `OnAnimFinished` (`0x76cdc0`) is owed, once per arm
+    /// and for a loop too: `0x719370` enqueues it before testing the loop flag.
     pub fn completion_due(&self, facts: &ModelFileFacts) -> bool {
         let Some(armed) = self.armed else {
             return false;
@@ -913,50 +551,24 @@ impl ModelState {
     }
 }
 
-/// The Minimap widget's modeled state — the client keeps **two independent zoom indices**, chosen
-/// by whether the player is inside a WMO: the inside flag `0xceaa60` routes the outdoor index
-/// `0x86f698` (CVar `minimapZoom`, chunk table `0x8116d0`) or the indoor index `0x86f69c` (CVar
-/// `minimapInsideZoom`, radius table `0x8116e8` = `{150,120,90,60,40,25}` yd). `GetZoom`/`SetZoom`
-/// read/write whichever is active, and each persists across transitions — so zooming in indoors
-/// does not disturb the outdoor zoom, and vice versa. (An earlier reading held the second index to
-/// be a rotate-minimap CVar and the interior scale to be a constant; both were wrong. There is
-/// **no rotate-minimap CVar in 5875 at all** — a 214-site `CVar::Register` census plus a
-/// whole-image string scan found no such knob, so nothing on this path ever needs a rotation
-/// term.) `set_zoom` clamps to 5.
+/// The Minimap widget's state. The client keeps two zoom indices, outdoor (`0x86f698`, CVar
+/// `minimapZoom`) and indoor (`0x86f69c`, CVar `minimapInsideZoom`, radii `{150,120,90,60,40,25}`
+/// yd); the WMO-interior flag `0xceaa60` picks which one `GetZoom`/`SetZoom` use.
 #[derive(Clone, Debug, PartialEq)]
 pub struct MinimapState {
-    /// The **outdoor** zoom index, `0..MINIMAP_ZOOM_LEVELS` (0 = widest, 5 = tightest). `SetZoom`
-    /// clamps like the client's `0x6daa10` (clamp at 5, mark dirty).
+    /// The outdoor zoom index, 0 widest to 5 tightest; `SetZoom` clamps at 5 (`0x6daa10`).
     pub zoom: u8,
-    /// The **indoor** zoom index (same range), persisted separately — the client's `0x86f69c`.
     pub inside_zoom: u8,
-    /// Is the player inside a WMO interior (the client's `0xceaa60`)? Selects which index the Lua
-    /// zoom API reads and writes. Pushed down by the app, which owns the WMO containment test.
+    /// Inside a WMO interior, which picks the index; pushed by the app, which owns that test.
     pub inside: bool,
-    /// The mask art the disc is cut to — `Minimap:SetMaskTexture(path)`, a real 1.12 method (the
-    /// name is in the 5875 image; there is no `GetMaskTexture` beside it, so this is write-only
-    /// from Lua). `None` = the engine default, [`MINIMAP_DEFAULT_MASK`].
-    ///
-    /// State-only here, pixels app-side, like the zoom index (0203): the app already masks the
-    /// disc through its own `UiQuadMask`, and this only decides which texture it loads. It is what
-    /// makes a **square minimap** possible, which is the single most recognisable thing pfUI does
-    /// to the default UI (`modules/minimap.lua:27`).
+    /// `Minimap:SetMaskTexture`'s mask, write-only from Lua; `None` is [`MINIMAP_DEFAULT_MASK`].
     pub mask_texture: Option<String>,
-    /// The **player-arrow** `Model` — the client's `[Minimap+0x338]`, ninth and last of the nine
-    /// engine children the ctor builds ([`MINIMAP_ENGINE_CHILDREN`]). An explicit slot because that
-    /// is the shape the client keeps: `CMinimap::SetPlayerFacing 0x4eb8e0` reaches the arrow through
-    /// this field, never by counting children; "it is also `GetChildren()[9]`" is a *consequence* of
-    /// the ctor's order, not the definition.
+    /// The player-arrow `Model` (`[Minimap+0x338]`), reached by `SetPlayerFacing` (`0x4eb8e0`).
     pub player_arrow: Option<FrameHandle>,
 }
 
-/// Both minimap zoom CVars register with the default `"3"` — **not** 0 (the
-/// `RegisterCVar 0x63db90` argument slot: `minimapZoom` @`0x48fc5a` and `minimapInsideZoom`
-/// @`0x48fc76` each push the string `"3"` at `0x82e960`). The minimap reset path copies the
-/// persisted CVar int into the live index rather than zeroing it, so 3 is what a fresh client runs.
-/// **Higher index = more zoomed in**: index 3 ⇒ a 60 yd indoor radius (of the `{150…25}` table) and a
-/// 133.3 yd outdoor half-extent (of the `{14…4}` chunk table). Seeding 0 here made both maps far too
-/// wide — the director's "way too zoomed out" (2026-07-09).
+/// Both zoom CVars register with `"3"` (`0x48fc5a`/`0x48fc76`) and the reset copies the CVar in;
+/// a higher index zooms in, 3 being a 60 yd indoor radius and a 133.3 yd outdoor half-extent.
 pub const MINIMAP_DEFAULT_ZOOM: u8 = 3;
 
 impl Default for MinimapState {
@@ -966,15 +578,14 @@ impl Default for MinimapState {
             inside_zoom: MINIMAP_DEFAULT_ZOOM,
             inside: false,
             mask_texture: None,
-            // Filled by the arena the moment the widget is inserted — the nine are ctor-time, so a
-            // Minimap is never observably without them (`WidgetArena::create`).
+            // Set by `WidgetArena::create` on insert, as the ctor builds its children.
             player_arrow: None,
         }
     }
 }
 
 impl MinimapState {
-    /// The zoom index the client's `get_zoom_index`/`set_zoom` operate on right now.
+    /// The index `GetZoom`/`SetZoom` act on now.
     pub fn active_zoom(&self) -> u8 {
         if self.inside {
             self.inside_zoom
@@ -983,7 +594,7 @@ impl MinimapState {
         }
     }
 
-    /// Write the active index (the `set_zoom` half of the same routing).
+    /// Writes the index the inside flag selects.
     pub fn set_active_zoom(&mut self, zoom: u8) {
         if self.inside {
             self.inside_zoom = zoom;
@@ -993,116 +604,53 @@ impl MinimapState {
     }
 }
 
-/// The client's minimap zoom-level count (`get_zoom_levels` `0x6da9a0` returns the constant 6).
+/// The zoom-level count (`GetZoomLevels`, `0x6da9a0`).
 pub const MINIMAP_ZOOM_LEVELS: u8 = 6;
 
-/// The engine's own minimap mask — the circle `Minimap:SetMaskTexture` replaces. benilla's
-/// renderer has loaded this path since the minimap existed; naming it here is what lets the Lua
-/// setter override it.
+/// The engine's circular minimap mask, which `Minimap:SetMaskTexture` replaces.
 pub const MINIMAP_DEFAULT_MASK: &str = "Textures\\MinimapMask";
 
-/// **Nine `Model` children, built by the `CMinimap` ctor before anything else sees the widget.**
-/// The ctor `0x4edbc0` (TU `Ui\MinimapFrame.cpp`) allocates `CSimpleModel` (`0x76c8e0`) nine times
-/// with the Minimap as parent, in three source-ordered groups whose `__LINE__` arguments give the
-/// order directly:
-///
-/// | # | stored at | `__LINE__` | what it is |
-/// |---|---|---|---|
-/// | 1–5 | `[Minimap+0x320 + 4k]` | 1424 | the rim/party arrows (`minimapArrowModel`) |
-/// | 6–8 | `[Minimap+0x314 + 4k]` | 1438 | the three POI direction arrows (`minimapArrowModel`) |
-/// | 9 | `[Minimap+0x338]` | 1450 | **the player arrow** (`minimapPlayerModel`) |
-///
-/// **Why the engine core carries them at all**, when the app draws every one of these arrows itself
-/// from its own art (`benilla-app`'s `minimap::blips`): because they are *structure the Lua API can
-/// see*, and two of the most-installed 1.12 addons read it. `Questie`'s `QuestieArrow.lua`
-/// `GetPlayerFacing()` is `({Minimap:GetChildren()})[9]:GetFacing()`, and pfQuest's
-/// `compat/client.lua` does the same — the ctor runs before the XML `<Frames>` descent
-/// (`0x6ee408` before `0x6ee4ea`) and both linkers append at the tail, so on a stock client the
-/// tuple is these nine then `Minimap.xml`'s six, and index 9 is the arrow. Without them that read
-/// is `nil` and the addon dies calling a method on it.
-///
-/// The count is fixed and unconditional: an unloadable model file only skips the *file* assignment
-/// (`0x4ee286` returns early), never the child.
+/// The `Model` children the `CMinimap` ctor (`0x4edbc0`) makes before its XML ones, even for an
+/// unloadable file (`0x4ee286`): five rim and party arrows, three POI arrows, the player arrow;
+/// addons (Questie, pfQuest) read `({Minimap:GetChildren()})[9]` as the player arrow.
 pub const MINIMAP_ENGINE_CHILDREN: usize = 9;
 
-/// The engine default for `<Minimap minimapArrowModel=…>` — the string at `0x84c768`, applied by
-/// `0x4ee170` to engine children 1–8. (`Minimap.xml:97` sets the attribute explicitly, in the `.mdl`
-/// spelling; the loader rewrites the extension either way.)
+/// The default `minimapArrowModel` (`0x84c768`), applied to engine children 1 to 8 (`0x4ee170`).
 pub const MINIMAP_DEFAULT_ARROW_MODEL: &str = "Interface\\Minimap\\Rotating-MinimapArrow.mdx";
 
-/// The engine default for `<Minimap minimapPlayerModel=…>` — the string at `0x8453c0`, applied by
-/// `0x4ee260` to engine child 9 **alone**.
+/// The default `minimapPlayerModel` (`0x8453c0`), applied to engine child 9 alone (`0x4ee260`).
 pub const MINIMAP_DEFAULT_PLAYER_MODEL: &str = "Interface\\Minimap\\MinimapArrow.mdx";
 
-/// A `CSimpleScrollFrame`'s runtime state: the frame whose anchors are overridden to track the
-/// scroll offset ([`crate::script::UiScript::resolve`]'s scroll-child override), and the current
-/// scroll position on each axis. `SetVerticalScroll` stores the offset VERBATIM — the reference's
-/// `0x786db0` never reads the range (decision 2017) — and the ranges are always computed live from
-/// the resolved rects (never cached here), so this struct carries only the three members the
-/// client's `SetScrollChild`/`SetHorizontalScroll`/`SetVerticalScroll` actually set (`[+0x318]`,
-/// `[+0x324]`, `[+0x328]`).
+/// A `CSimpleScrollFrame`'s members (`+0x318`/`+0x324`/`+0x328`); the ranges are measured live.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct ScrollFrameState {
-    /// The scroll child (`SetScrollChild`) — the one frame whose content pans within this frame's
-    /// rect. `None` = no child (nothing to clip or offset).
+    /// `SetScrollChild`'s frame, which pans within this frame's rect.
     pub child: Option<FrameHandle>,
-    /// The horizontal scroll offset in px (`SetHorizontalScroll`), unclamped — the reference's
-    /// `[+0x324]`, whose setter `0x786d30` is the byte-clone of the vertical one's `0x786db0`.
-    ///
-    /// **The sign is the mirror of the vertical one below, and that is the reference's, not a
-    /// slip.** `0x787100` re-anchors the child as
-    /// `SetPoint(TOPLEFT, self, TOPLEFT, +[+0x324], +[+0x328])` — both offsets handed over raw,
-    /// neither negated. x grows right, so
-    /// a POSITIVE horizontal offset pushes the child right and reveals nothing new; scrolling
-    /// right takes a NEGATIVE one, where scrolling down takes a positive vertical.
-    /// `aux-addon/tabs/search/filter.lua:315-322` corroborates it from the caller's side: it
-    /// bounds x into `[min(0, frameWidth - contentWidth - 10), 0]` and y into
-    /// `[0, contentHeight - frameHeight]`.
+    /// `SetHorizontalScroll`'s offset in px, unclamped; `0x787100` anchors the child at
+    /// `(+horizontal, +vertical)`, so scrolling right takes a negative offset, down a positive.
     pub horizontal: f32,
-    /// The vertical scroll offset in px (`SetVerticalScroll`), unclamped — the reference's
-    /// `[+0x328]`. XML y-positive-up: a positive offset lifts the child
-    /// (`child.top = scrollframe.top + vertical`), bringing content below the fold into view. The
-    /// scroll bar's `[min, max]` is what keeps it inside the range — in FrameXML, never here.
+    /// `SetVerticalScroll`'s offset in px (`0x786db0`), unclamped: a positive one lifts the child
+    /// to show what is below; the FrameXML scroll bar's range keeps it in bounds.
     pub vertical: f32,
 }
 
-/// The face/size/flags one `Button:SetFont(file, height [, flags])` call writes.
-///
-/// **One record, not three, and that is the faithful shape here rather than a shortcut.** The
-/// client's Button embeds three `CSimpleFont` sub-objects — normal `+0x33c`, disabled `+0x434`,
-/// highlight `+0x3b8` — and `SetFont` (`0x780880`) retunes **all three with the same values**
-/// (`GetFont` reads only the normal one). Nothing in the 1.12 Lua surface can set them apart: a
-/// Button has `SetFont` and the `*FontObject` triple, and the latter changes which object each
-/// state *inherits*, never its local face. So three identical copies could only ever diverge by
-/// our own bug.
+/// `Button:SetFont`'s record, one for the client's three embedded fonts (`+0x33c`, `+0x434`,
+/// `+0x3b8`), since `SetFont` (`0x780880`) sets all three alike and no Lua call parts them.
 #[derive(Clone, Debug, PartialEq)]
 pub struct ButtonFont {
-    /// The TTF path (`"Fonts\\FRIZQT__.TTF"`).
     pub path: String,
     /// The font height in logical px.
     pub height: f32,
-    /// The **normalized** OUTLINETYPE token — `""`, `"OUTLINE"` or `"THICKOUTLINE"` — so
-    /// `GetFont`'s third return reads like the FontString/Font-object one rather than echoing
-    /// whatever the addon spelled. Kept as a string, not `script::Outline`, because this module is
-    /// the arena's vocabulary and deliberately names no script type.
-    ///
-    /// **An omitted `flags` argument clears the outline** (this is `""`), which is the reading the
-    /// batch does not pin: it records arg4 as parsed against `{OUTLINE, THICKOUTLINE, MONOCHROME}`
-    /// and says nothing about its absence. A `lua_tostring` on a missing argument yields no flags,
-    /// so "absent means none" is what the shared impl most plausibly does, and it is the reading
-    /// an addon setting a plain face expects.
+    /// The normalized outline, `""`, `"OUTLINE"` or `"THICKOUTLINE"`, as `GetFont` answers it; an
+    /// omitted `flags` clears it, where the reference's handling is untraced.
     pub flags: String,
 }
 
-/// The client's button STATE INDEX — `[CSimpleButton+0x328]`, the one variable `SetState
-/// 0x779790` writes and `IsEnabled 0x7800b0` / `GetButtonState 0x780180` read back.
-///
-/// The client numbers them 0 DISABLED / 1 NORMAL / 2 PUSHED, which is also the index into its
-/// state-texture array (`[this + state*4 + 0x4b8]`); we name the variants instead, because
-/// nothing here indexes.
+/// A button's state, `[CSimpleButton+0x328]`: 0 DISABLED, 1 NORMAL, 2 PUSHED, also the index into
+/// its texture array `+0x4b8`. Past the ctor, `SetState` (`0x779790`) is its only writer.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub enum ButtonVisualState {
-    /// `Disable()` — the button fires no clicks and draws from the Disabled slot.
+    /// `Disable()`: the button fires no clicks and draws from the Disabled slot.
     Disabled,
     /// The resting state a button is born in.
     #[default]
@@ -1111,138 +659,63 @@ pub enum ButtonVisualState {
     Pushed,
 }
 
-/// A Button's state model: which of the state textures draws is a **latched** consequence of the
-/// interaction state, not a pure function of it — the client's texture array `+0x4b8` plus its
-/// currently-shown pointer `+0x4c4`, which moves only on a transition into a state that *has* a
-/// texture ([`Self::settle`]). The regions all exist in the arena; [`Self::region_visible`] reads
-/// the pointer at extract time.
+/// A button's state. The drawn state texture is latched, not derived: the shown pointer
+/// (`+0x4c4`) moves only on a transition into a state that has a texture ([`Self::set_state`]).
 #[derive(Clone, Debug, PartialEq)]
 pub struct ButtonState {
-    /// **`[CSimpleButton+0x32c]` — the LOCK**, written unconditionally by every
-    /// `SetButtonState(state, locked) 0x779790` and read by exactly four guards, all of them the
-    /// engine's own edges. While it is set the button **ignores the mouse press/release
-    /// transitions entirely**; while it is clear, any engine edge that fires re-writes it to
-    /// `false`, because every engine call site passes `locked = 0` (`Enable`/`Disable`'s shared
-    /// `0x779160` among them, which therefore CLEAR a lock a script set).
-    ///
-    /// `MainMenuBarMicroButtons.lua` is the reference's own customer: `SetButtonState("PUSHED", 1)`
-    /// when a panel opens, `SetButtonState("NORMAL")` — the flag defaulting to 0 — when it closes.
-    /// The ordinary action bars pass no flag at all, and Tablet-2.0 pushes its clicked rows
-    /// unlocked and never un-pushes them, which is the whole reason this field exists (2134).
+    /// The lock (`+0x32c`) of `SetButtonState(state, locked)`: while set, the hide, press, release
+    /// and drag edges skip the button, and an `Enable`/`Disable` that runs (`0x779160`) clears it.
     pub locked: bool,
-    /// [`FrameKind::LootButton`]'s own field — `CLootButton +0x4dc`, the **0-based** loot slot
-    /// this row takes when clicked. `None` until `SetSlot` writes it (the ctor's zero is a slot
-    /// id in the reference; ours is `None`, so a row that was never given one takes nothing
-    /// rather than silently taking slot 0). Unused on every other button kind, the same way
-    /// [`Self::checked`] below is unused on a plain Button — the client's subclasses add their one
-    /// field the same way, and our flat state mirrors that rather than growing a variant.
+    /// [`FrameKind::LootButton`]'s 0-based slot (`+0x4dc`) from `SetSlot`. Deviation: `None`
+    /// until then, not the ctor's 0, so that an unset row takes nothing rather than slot 0.
     pub loot_slot: Option<u32>,
-    /// CheckButton's checked flag (`+0x4dc`; XML `checked`). Unused on a plain Button.
+    /// A CheckButton's checked flag (`+0x4dc`, XML `checked`).
     pub checked: bool,
     /// `<NormalTexture>`/`SetNormalTexture` (`+0x4bc`).
     pub normal: Option<RegionHandle>,
-    /// `<PushedTexture>` (`+0x4c0`) — taken on the press transition. A button with none keeps
-    /// whatever it was showing ([`Self::set_state`]), which is not a fallback but the absence of
-    /// one.
+    /// `<PushedTexture>` (`+0x4c0`); a button with none keeps what it showed ([`Self::set_state`]).
     pub pushed: Option<RegionHandle>,
     /// `<DisabledTexture>` (`+0x4b8`).
     pub disabled: Option<RegionHandle>,
-    /// `<HighlightTexture>` (`+0x4c8`) — additive over the current state texture while hovered
-    /// (it lives in the HIGHLIGHT draw layer, above the others, not instead of them).
+    /// `<HighlightTexture>` (`+0x4c8`), drawn over the state texture while hovered.
     pub highlight: Option<RegionHandle>,
-    /// CheckButton `<CheckedTexture>` (`+0x4e0`) — additive while checked. A SEPARATE array from
-    /// the state textures, with its own rule (`0x7854c0`): hide both, then show
-    /// [`Self::disabled_checked`] if checked ∧ it exists ∧ the state is DISABLED, else this one if
-    /// it exists, else nothing. **The fallback is one-way** — a disabled checked button with no
-    /// DisabledChecked art falls back to this; a checked one never falls the other way.
+    /// `<CheckedTexture>` (`+0x4e0`), drawn while checked; `0x7854c0` shows
+    /// [`Self::disabled_checked`] instead when disabled and it exists.
     pub checked_tex: Option<RegionHandle>,
-    /// CheckButton `<DisabledCheckedTexture>` (`+0x4e4`) — replaces CheckedTexture when disabled.
-    /// The greyed tick a peace-forced faction's At War box wears (B369).
+    /// `<DisabledCheckedTexture>` (`+0x4e4`), which replaces the checked texture when disabled.
     pub disabled_checked: Option<RegionHandle>,
-    /// The `<ButtonText>` fontstring (`+0x338`; `SetText`). Always drawn.
+    /// The `<ButtonText>` fontstring (`+0x338`, `SetText`), always drawn.
     pub text: Option<RegionHandle>,
-    /// `RegisterForClicks`' set (the exact 1.12 API strings, e.g. `"LeftButtonUp"`,
-    /// `"RightButtonDown"`) — which press/release transitions reach `OnClick`. Plain strings, not
-    /// an enum: the API is an open list of `"<Button>Button<Up|Down>"` names and the input path
-    /// only ever needs membership, never to enumerate it. Defaults to the client's own default
-    /// (`{"LeftButtonUp"}` — a left click, on release).
+    /// `RegisterForClicks`' names, the transitions that reach `OnClick`; default `"LeftButtonUp"`.
     pub registered_clicks: HashSet<String>,
-    /// Per-state label font-object NAMES (`<NormalFont inherits=>`/`SetTextFontObject` and the
-    /// Highlight/Disabled pair): at extract, the ButtonText re-points to the current state's font
-    /// object — the client's per-state CFontString font swap (UIPanelButtonTemplate's gold
-    /// normal / white highlight / gray disabled label). `None` = keep the label's own paint.
+    /// The normal state's label font object (`<NormalFont>`); `None` keeps the label's own paint.
     pub normal_font: Option<String>,
-    /// See [`ButtonState::normal_font`] — the highlighted state (hovered **or**
-    /// [`locked_highlight`](ButtonState::locked_highlight)). `None` means the button has no
-    /// highlight instance at all and the label stays on the normal one, colour included.
+    /// [`ButtonState::normal_font`] when highlighted; `None` keeps the normal one, colour and all.
     pub highlight_font: Option<String>,
-    /// See [`ButtonState::normal_font`] — the disabled state.
+    /// [`ButtonState::normal_font`] for the disabled state.
     pub disabled_font: Option<String>,
-    /// The NORMAL embedded font's own justify — `<NormalFont justifyH=>` (or the `<NormalText>`
-    /// alias), a **local** write on the instance at `+0x33c` (`CSimpleButton::LoadXML 0x7788c0`
-    /// → the `<Font>` loader `0x783c30`), severed from whatever object the instance inherits and
-    /// surviving a later `SetTextFontObject`. `None` = the instance shows its object's justify.
-    ///
-    /// Two readers, and the first is the one that made this a field of the *button*: the label
-    /// adopter `CSimpleButton::SetFontString 0x778d20` — the tail `SetText`'s lazy creation and
-    /// the Lua adopter share — anchors an unanchored label to the button by exactly this word
-    /// (`[button+0x390]`: LEFT→LEFT, RIGHT→RIGHT, else CENTER), which is how a row of the
-    /// reference's `UIMenuButtonTemplate` (no `<ButtonText>`, `SetText` from Lua) hugs its left
-    /// edge. The second is the label's paint and query surface, reached through the live link
-    /// (`script::button::apply_normal_font`, `script::extract`). Decision 1996.
+    /// `<NormalFont justifyH=>`, local to the normal font (`+0x33c`) and kept over
+    /// `SetTextFontObject`; `SetFontString` (`0x778d20`) anchors an unanchored label by it.
     pub normal_justify_h: Option<crate::script::JustifyH>,
-    /// See [`ButtonState::normal_justify_h`] — `<HighlightFont justifyH=>`, the highlight instance
-    /// (`+0x3b8`). Paint only: the adopter reads the normal instance alone.
+    /// `<HighlightFont justifyH=>` (`+0x3b8`); paint only, the label anchor reads the normal one.
     pub highlight_justify_h: Option<crate::script::JustifyH>,
-    /// See [`ButtonState::normal_justify_h`] — `<DisabledFont justifyH=>`, the disabled instance
-    /// (`+0x434`). Paint only.
+    /// `<DisabledFont justifyH=>` (`+0x434`); paint only.
     pub disabled_justify_h: Option<crate::script::JustifyH>,
-    /// `Button:SetFont(file, height [, flags])` — the button's own face/size/flags, set on the
-    /// embedded font objects themselves rather than on any font object they inherit. See
-    /// [`ButtonFont`] for why one record covers the client's three.
-    ///
-    /// It lives here, not on the ButtonText's [`crate::script::RegionData`], because the reference
-    /// **never dereferences the label pointer** (`+0x338`) in `SetFont`/`GetFont`: styling a
-    /// `CreateFrame("Button")` with no `<ButtonText>` is a silent no-op there, and writing to a
-    /// label would have meant lazily creating one — observable through `GetFontString()`, which
-    /// must stay nil. `extract` applies it to the label whenever there is one, which also makes a
-    /// later `SetText` (which *does* create the FontString) pick the style up for free.
+    /// `Button:SetFont`'s face, kept on the button since `SetFont` never touches the label
+    /// (`+0x338`) and so creates none; extract applies it to whatever label there is.
     pub font: Option<ButtonFont>,
-    /// Per-state label COLOR overrides (`Button:SetTextColor` and the Highlight/Disabled pair):
-    /// when the matching state is current, extract repaints the ButtonText with this color over
-    /// the state font object's own paint — the dropdown kit's rows lean on all three
-    /// (`info.textR/G/B`, isTitle's NORMAL-yellow and notClickable's HIGHLIGHT-white recolors of
-    /// a disabled row). `None` = the state font's paint.
+    /// `SetTextColor`'s label colour for the normal state, painted over the state font's own.
     pub normal_color: Option<[f32; 4]>,
-    /// See [`ButtonState::normal_color`] — the highlighted state. It does **not** fall back to
-    /// `normal_color`: each state is its own font instance, so a `SetTextColor` cannot reach the
-    /// highlighted label (which is why `UIDropDownMenu.lua` always pairs the two setters).
+    /// [`ButtonState::normal_color`] for the highlighted state, which never falls back to it.
     pub highlight_color: Option<[f32; 4]>,
-    /// See [`ButtonState::normal_color`] — the disabled state.
+    /// [`ButtonState::normal_color`] for the disabled state.
     pub disabled_color: Option<[f32; 4]>,
-    /// `LockHighlight()` — the button reads as highlighted regardless of hover until
-    /// `UnlockHighlight()` (ref `CButton::LockHighlight`; the dropdown kit keeps a checked row's
-    /// highlight lit). That covers BOTH halves of the highlighted look: the HighlightTexture
-    /// ([`Self::region_visible`]) and the label's font instance (`script::extract`). The list
-    /// windows lean on the second alone — a tradeskill/craft/trainer recipe row blanks its
-    /// highlight texture to `""` and locks the selected row anyway, purely for the white label.
+    /// `LockHighlight()`: highlighted regardless of hover, both the texture and the label font.
     pub locked_highlight: bool,
-    /// The client's **currently-shown state texture** — the pointer at `+0x4c4`. Private, and the
-    /// only thing [`Self::region_visible`] consults for the three state textures: it is written by
-    /// [`Self::set_state`] and [`Self::set_state_slot`] alone, which is what makes the transition
-    /// rule un-bypassable.
+    /// The shown state texture (`+0x4c4`), written only by `set_state` and `set_state_slot`.
     shown: Option<RegionHandle>,
-    /// **`[CSimpleButton+0x328]` — THE state**, and the client really does have only this one
-    /// variable: `SetButtonState 0x779790` is its only writer past the ctor, and `IsEnabled
-    /// 0x7800b0`, `GetButtonState 0x780180` and every texture decision read it back.
-    ///
-    /// Private, because it is a **latch driven by edges**, not a value derived from inputs. That
-    /// distinction is the whole of decision 2134: benilla used to carry `enabled` and
-    /// `pushed_state` beside it and re-derive `state` from them plus the live mouse
-    /// (`(held && hovered) || pushed_state`), and the reference's press state **has no hover term
-    /// at all** — the enter and leave notifies (`0x779490`/`0x7794e0`) read `[+0x328]` only as a
-    /// DISABLED guard and never write it. A derived model un-presses when the cursor leaves a held
-    /// button and re-presses when it comes back; the reference does neither.
+    /// The state (`+0x328`), a latch moved only by edges: the enter and leave notifies
+    /// (`0x779490`/`0x7794e0`) never write it, so leaving a held button does not un-press it.
     state: ButtonVisualState,
 }
 
@@ -1278,7 +751,7 @@ impl Default for ButtonState {
 }
 
 impl ButtonState {
-    /// The slot a state draws from — the client's `[this + state*4 + 0x4b8]`.
+    /// The slot a state draws from, the client's `[this + state*4 + 0x4b8]`.
     fn state_slot(&self, state: ButtonVisualState) -> Option<RegionHandle> {
         match state {
             ButtonVisualState::Disabled => self.disabled,
@@ -1287,39 +760,9 @@ impl ButtonState {
         }
     }
 
-    /// **`CSimpleButton::SetState 0x779790`** — the transition, and the whole of why the shown
-    /// texture is state rather than a lookup.
-    ///
-    /// Both halves of the swap test the SAME dword — the new state's own slot: `0x7797b5` loads
-    /// `[esi + 4*edi + 0x4b8]` and `0x7797be` skips the hide when it is null; `0x7797d9`/`0x7797e2`
-    /// skips the show on the same value. The state itself is written regardless (`0x779801`). So a
-    /// transition into a state with no texture of its own **changes nothing** — the
-    /// previously-shown texture stays up, and there is no fallback path to Normal anywhere in the
-    /// function. The equality early-out sits at `0x7797a3`/`0x7797a9`, *after* the unconditional
-    /// `[+0x32c] = locked` store and *before* every texture step.
-    ///
-    /// **A button is NORMAL before its art is loaded, which is what makes the rule bite.** The
-    /// `CSimpleButton` ctor `0x7786a0` writes `[+0x328] = 0` and `[+0x4c4] = 0`, then ends
-    /// `push 1; call 0x779160` → `[vtbl+0x9c]` = this function with NORMAL. Only then does
-    /// `LoadXML` install the art, each child through the `0x778fd0` setter family
-    /// ([`Self::set_state_slot`]) — `<NormalTexture>` at `0x77890e` with idx 1, which matches, so
-    /// it is shown on the spot. Every button in the family therefore reaches its first `Disable()`
-    /// already wearing its normal art.
-    ///
-    /// Three things the reference draws out of that one rule, which a pure `state → slot`
-    /// resolution cannot:
-    ///
-    /// - **A press with no PushedTexture keeps its normal art.** (Our old resolution special-cased
-    ///   this as `pushed.or(normal)` — the fallback was never a rule, it was this mechanism seen
-    ///   from one side.)
-    /// - **`Disable()` on a button with no DisabledTexture keeps its normal art.** This is B369:
-    ///   `ReputationDetailAtWarCheckBox` has a `<NormalTexture>` and no `<DisabledTexture>`, and
-    ///   `ReputationFrame_Update` `Disable()`s it for a faction whose war flag cannot be toggled —
-    ///   in the reference the box stays on screen (greyed label, still a box); resolving the shown
-    ///   texture as a pure function of the state made it vanish, leaving a bare label.
-    ///   `Disable 0x77ffd0` reaches here through `0x78009a call [vtbl+0x90](0)` → `0x779160`.
-    /// - **So does an empty spellbook slot's `UI-Quickslot2` ring**, which is the same shape and
-    ///   was the case decision 0227 got backwards — see 2011.
+    /// `SetState` (`0x779790`): entering a state with no texture keeps the shown one
+    /// (`0x7797be`/`0x7797e2`). A button is NORMAL before `LoadXML` adds its art (ctor
+    /// `0x7786a0`), so a press or `Disable()` without its own texture keeps the normal art.
     fn set_state(&mut self, new: ButtonVisualState) {
         if new == self.state {
             return;
@@ -1330,48 +773,28 @@ impl ButtonState {
         }
     }
 
-    /// **`CSimpleButton::SetButtonState(state, locked) 0x779790` — the ONE writer**, and the door
-    /// every edge below goes through.
-    ///
-    /// `0x77979d mov [this+0x32c], locked` is **unconditional**, before and independent of the
-    /// state's own equality early-out at `0x7797a3` — so a `SetButtonState("NORMAL", 1)` on a
-    /// button that is already NORMAL still arms the lock, and every engine edge (all of which pass
-    /// `locked = 0`) disarms it even when the state does not move.
+    /// `SetButtonState(state, locked)` (`0x779790`), the one writer: the lock is stored before the
+    /// equal-state early-out (`0x77979d`), so it is set or cleared even when the state holds.
     pub fn set_button_state(&mut self, new: ButtonVisualState, locked: bool) {
         self.locked = locked;
         self.set_state(new);
     }
 
-    /// `IsEnabled 0x7800b0` — which reads `[+0x328]` and nothing else, because there is no
-    /// separate enabled flag in the class.
+    /// `IsEnabled` (`0x7800b0`): the state alone; the class has no enabled flag.
     pub fn enabled(&self) -> bool {
         self.state != ButtonVisualState::Disabled
     }
 
-    /// `GetButtonState 0x780180` — the same one variable, un-derived. A button held down by the
-    /// mouse answers `"PUSHED"` because the press *wrote* it, not because a getter re-checks the
-    /// cursor (which is what ours used to do, and why it could disagree with the art).
+    /// `GetButtonState` (`0x780180`): the latched state, never re-derived from the cursor.
     pub fn button_state(&self) -> ButtonVisualState {
         self.state
     }
 
-    // ── The engine's edges ───────────────────────────────────────────────────────────────────
-    //
-    // Seven call sites of `0x779790` exist image-wide; six are below and the seventh is the Lua
-    // binding ([`Self::set_button_state`]). Every one of the six passes `locked = 0`. There is
-    // **no enter edge and no leave edge** — `0x779490`/`0x7794e0` re-apply the label style and
-    // never touch `[+0x328]` — which is the correction 2134 is built on.
+    // ── The engine's edges ──
+    // Six of `0x779790`'s seven call sites, all passing `locked = 0`; the seventh is Lua's.
 
-    /// **`SetEnabled(bool) 0x779160`** (vtable `+0x90`) — `Enable 0x77fef0` / `Disable 0x77ffd0`.
-    ///
-    /// Two asymmetries the byte read settles, both early-outs on the state it already has:
-    /// `Enable()` on a button that is not DISABLED does **nothing at all** (`0x779175`) — so it
-    /// does not un-push a PUSHED button and does not clear a lock; `Disable()` on an
-    /// already-DISABLED one likewise (`0x77919c`). When it does run it passes `locked = 0`
-    /// (`0x779179`/`0x7791c2`), so enabling or disabling a script-locked button **unlocks** it.
-    ///
-    /// Returns whether the transition ran — the caller owes the HIGHLIGHT draw-layer half only
-    /// then (`script::button::set_enabled`).
+    /// `SetEnabled` (`0x779160`): a no-op if nothing changes (`0x779175`/`0x77919c`), so enabling a
+    /// pushed button neither un-pushes nor unlocks it; returns whether it ran.
     pub fn set_enabled(&mut self, on: bool) -> bool {
         if on == self.enabled() {
             return false;
@@ -1387,72 +810,40 @@ impl ButtonState {
         true
     }
 
-    /// **The hide edge** — `CSimpleButton`'s `+0x34` override `0x7791e0`, which un-presses and then
-    /// tail-jumps the base notify so the frame's `<OnHide>` still fires. Guard at `0x7791ed`:
-    /// `state != DISABLED && locked == 0`.
+    /// The hide edge (`0x7791e0`): an unlocked, enabled button goes NORMAL; `<OnHide>` still fires.
     pub fn on_hide(&mut self) {
         if self.state != ButtonVisualState::Disabled && !self.locked {
             self.set_button_state(ButtonVisualState::Normal, false);
         }
     }
 
-    /// **The press edge** — the mouse-down dispatcher `0x779210`'s `0x7792b1`
-    /// `SetButtonState(PUSHED, 0)`, guarded at `0x779295` on `locked == 0 && state != DISABLED`.
-    /// Unconditional past the registration and hit gates above it, which is why a right-click on a
-    /// slot that registered `RightButtonUp` lights up even when the click does nothing.
+    /// The press edge (`0x779210`), past the registration and hit gates, so a registered click
+    /// pushes the button even when the click itself does nothing.
     pub fn on_mouse_down(&mut self) {
         if !self.locked && self.state != ButtonVisualState::Disabled {
             self.set_button_state(ButtonVisualState::Pushed, false);
         }
     }
 
-    /// **The release edge** — the mouse-up dispatcher `0x7792d0`'s `0x7793de`
-    /// `SetButtonState(NORMAL, 0)`, guarded at `0x7793c2` on `locked == 0` and at `0x779307` on the
-    /// state actually being PUSHED.
-    ///
-    /// **It does not ask where the cursor is.** A press held over a button and released anywhere
-    /// on screen un-presses it; the release is the edge, the hover is not. (The caller skips this
-    /// when the base finalized a drag — `0x7792df`'s `0x76c040` test — which is our
-    /// `cursor::take_drag(..).started`.)
-    ///
-    /// This is the edge that fixes Tablet-2.0: its rows call `SetButtonState("PUSHED")` with no
-    /// lock argument and never call `SetButtonState("NORMAL")` at all, because in the reference
-    /// this release does it for them.
+    /// The release edge (`0x7792d0`): a pushed, unlocked button goes NORMAL wherever the cursor
+    /// is, even one Lua pushed. The caller skips it when the release ends a drag (`0x7792df`).
     pub fn on_mouse_up(&mut self) {
         if !self.locked && self.state == ButtonVisualState::Pushed {
             self.set_button_state(ButtonVisualState::Normal, false);
         }
     }
 
-    /// **The drag-start edge** — `+0x74`'s override `0x7793f0`, `0x779410`
-    /// `SetButtonState(NORMAL, 0)` under the same `0x779400` guard, before forwarding to the base
-    /// `0x76c1e0` that fires `<OnDragStart>`.
-    ///
-    /// It fires on the drag THRESHOLD crossing (a link-time `0.01` frame units, `0x81c468`), not on
-    /// the rect edge, and only for a frame that called `RegisterForDrag` — so a button you drag off
-    /// un-presses well before the cursor leaves it, and one you merely slide off does not.
+    /// The drag-start edge (`0x7793f0`), before `<OnDragStart>`: it fires at the drag threshold
+    /// (0.01 frame units, `0x81c468`) on a `RegisterForDrag` frame, not at the rect edge.
     pub fn on_drag_start(&mut self) {
         if !self.locked && self.state != ButtonVisualState::Disabled {
             self.set_button_state(ButtonVisualState::Normal, false);
         }
     }
 
-    /// **`SetNormalTexture`/`SetPushedTexture`/`SetDisabledTexture 0x778fd0`** — the slot store,
-    /// plus the conditional push to the shown pointer: `[this+idx*4+0x4b8] = tex`, and `+0x4c4`
-    /// takes it **only when `idx == [this+0x328]`** (the gate at `0x779027`). Setting a state's
-    /// texture while the button is in a *different* state does not display it: a fresh region is
-    /// born hidden (`0x77f695` writes `+0xc4 = 0`), so a non-current slot is installed dark.
-    ///
-    /// This is also how a button's art first reaches the screen at all — see [`Self::set_state`]
-    /// for why LoadXML always finds the button in NORMAL.
-    ///
-    /// **One stated divergence.** When the write DISPLACES an occupant, the reference *destroys*
-    /// it (`0x77900a` calls the old object's `vtbl[0](1)`) and clears `+0x4c4` if that occupant
-    /// was the shown one. Ours never gets there: `script::button::ensure_slot` creates a slot's
-    /// region once and later `SetNormalTexture` calls repaint that same region, so the handle is
-    /// stable and an addon holding `GetNormalTexture()` keeps a live object where the reference
-    /// would have handed it a dead one. Nothing in the corpus reads a state texture across a
-    /// replacement; the object-identity half is not modeled.
+    /// `SetNormalTexture` and kin (`0x778fd0`): stores the slot, shown only if it is the current
+    /// state's (`0x779027`). The reference destroys a displaced texture (`0x77900a`); here the
+    /// region is made once and repainted, so a held `GetNormalTexture()` stays live.
     pub fn set_state_slot(&mut self, state: ButtonVisualState, rh: Option<RegionHandle>) {
         match state {
             ButtonVisualState::Disabled => self.disabled = rh,
@@ -1464,21 +855,15 @@ impl ButtonState {
         }
     }
 
-    /// Whether a region of this button draws. The three state textures answer from the shown
-    /// pointer alone ([`Self::set_state`]) — which is why the press is no longer an argument here:
-    /// it is an *input to the transition*, consumed at [`Self::settle`], not something a paint
-    /// re-derives. `hovered` stays because the Highlight is not a state texture and really does
-    /// track the cursor with no latch of its own. Checked draws additively per its own condition,
-    /// and any region that is not one of these (ButtonText, user regions) always draws.
+    /// Whether a region of this button draws: a state texture only when shown, the highlight
+    /// while hovered or locked, the checked pair by their rule, anything else always.
     pub fn region_visible(&self, rh: RegionHandle, hovered: bool) -> bool {
         let some = Some(rh);
         if some == self.normal || some == self.pushed || some == self.disabled {
             return some == self.shown;
         }
         if some == self.highlight {
-            // No `enabled` term: a disabled button loses its highlight because `Disable()` turns
-            // the whole HIGHLIGHT draw layer off (`script::button::set_enabled`), which extract
-            // applies before it ever reaches here.
+            // No `enabled` term: `Disable()` turns the whole HIGHLIGHT layer off before this.
             return hovered || self.locked_highlight;
         }
         if some == self.checked_tex {
@@ -1491,28 +876,23 @@ impl ButtonState {
     }
 }
 
-/// A StatusBar's value model + its bar-fill region. Zero-initialized like the client's members —
-/// a degenerate range (`max <= min`) draws an empty bar until the data configures it.
+/// A StatusBar's value and fill texture, zero-initialized like the client's members.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct StatusBarState {
-    /// `SetMinMaxValues` low bound (XML `minValue`; the 1.12 loader swaps a reversed pair,
-    /// `0x782ef0`).
+    /// `SetMinMaxValues` low bound (XML `minValue`); the loader swaps a reversed pair (`0x782ef0`).
     pub min: f32,
     /// `SetMinMaxValues` high bound (XML `maxValue`).
     pub max: f32,
     /// The current value (`SetValue`/XML `defaultValue`), clamped into `[min, max]`.
     pub value: f32,
-    /// `true` = VERTICAL (fills bottom-up); `false` = HORIZONTAL (fills left-to-right), the default
-    /// (shared enum table `0x811b00`: HORIZONTAL=0/VERTICAL=1).
+    /// VERTICAL fills bottom-up; HORIZONTAL, the default, left to right (enum `0x811b00`).
     pub vertical: bool,
-    /// The bar-fill texture region (`SetStatusBarTexture`/`<BarTexture>`), created on first set. A
-    /// renderer scales this region's rect by [`Self::fraction`] along the orientation axis.
+    /// The fill texture (`<BarTexture>`), cropped to [`Self::fraction`] along the orientation axis.
     pub bar: Option<RegionHandle>,
 }
 
 impl StatusBarState {
-    /// The fill fraction `(value − min) / (max − min)`, clamped to `[0, 1]`; a degenerate range
-    /// (`max <= min`) is `0.0` (an unconfigured bar draws empty, matching zero-init members).
+    /// The fill fraction `(value − min) / (max − min)` in `[0, 1]`; `0.0` when `max <= min`.
     pub fn fraction(&self) -> f32 {
         if self.max > self.min {
             ((self.value - self.min) / (self.max - self.min)).clamp(0.0, 1.0)
@@ -1522,54 +902,27 @@ impl StatusBarState {
     }
 }
 
-/// A `CSimpleSlider`'s runtime state (LoadXML `0x789580`): the value in `[min, max]`, the
-/// value step, orientation, an enabled flag, and the thumb texture the engine positions by the value
-/// fraction along the track. Only the members the documented `SetMinMaxValues`/`SetValue`/
-/// `SetValueStep`/`SetOrientation`/`SetThumbTexture` contract sets — the thumb's *position* is
-/// derived live from the fraction (never cached here), like StatusBar's fill.
-///
-/// **Default orientation is VERTICAL** — the opposite of [`StatusBarState`]'s HORIZONTAL default,
-/// and verified against the real templates, not assumed: `UIPanelScrollBarTemplate` (every
-/// scrollbar) declares no `orientation` and is vertical, while a horizontal slider
-/// (`OptionsSliderTemplate`) must declare `orientation="HORIZONTAL"` (decision 0250). Sliders in the
-/// UI are overwhelmingly scrollbars, so VERTICAL is the ctor default.
+/// A `CSimpleSlider`'s state. The default orientation is VERTICAL, unlike a StatusBar's: the
+/// stock `UIPanelScrollBarTemplate` declares none and is vertical.
 #[derive(Clone, Debug, PartialEq)]
 pub struct SliderState {
-    /// `SetMinMaxValues` low bound (XML `minValue`). Unlike StatusBar, a reversed pair is **not**
-    /// swapped (the Slider LoadXML `0x789580` stores `min` + `max−min` as a range and does no
-    /// swap); the value clamp guards a degenerate range instead ([`Self::clamp`]).
+    /// `SetMinMaxValues` low bound (XML `minValue`); a reversed pair is not swapped (`0x789580`).
     pub min: f32,
     /// `SetMinMaxValues` high bound (XML `maxValue`).
     pub max: f32,
-    /// The current value (`SetValue`/XML `defaultValue`), clamped into `[min, max]`. Zero-initialised
-    /// like the client's `+0x320`, and readable through `GetValue` before anything set it.
+    /// The stored value (`+0x320`), zero-initialised and readable before any `SetValue`.
     pub value: f32,
-    /// **Has a range** — the client's `+0x314` bit1, set by `SetMinMaxValues` (`0x7898f0`) and
-    /// never cleared. Until it is set, `SetValue 0x789930` is a complete no-op: no store, no
-    /// `OnValueChanged`.
+    /// `+0x314` bit 1, set by `SetMinMaxValues` (`0x7898f0`); until then `SetValue` is a no-op.
     pub range_valid: bool,
-    /// **Has a value** — the client's `+0x314` bit2, set by the first successful `SetValue` and
-    /// never cleared. Two things hang off it (`0x789930`, `0x7898f0`): the first-ever `SetValue`
-    /// **always** fires `OnValueChanged`, even when the new value equals the zero-init one; and
-    /// `SetMinMaxValues` re-clamps the held value through `SetValue` **only** once a value exists.
-    /// Before this flag, `SetMinMaxValues` on a fresh
-    /// slider clamped the zero-init value into the new range and fired the handler — which is how
-    /// Atlas's option sliders raised `attempt to index global 'AtlasOptions'` from their own
-    /// `<OnLoad>`, a handler the reference never runs at that point.
+    /// `+0x314` bit 2, set by the first `SetValue`, which always fires `OnValueChanged`;
+    /// `SetMinMaxValues` re-clamps the value only once this is set.
     pub has_value: bool,
-    /// `SetValueStep` (XML `valueStep`) — the client's `[+0x324]`, and **the quantiser every
-    /// stored value passes through**, not merely the arrow keys' stride: `SetValue 0x789930`
-    /// rounds the clamped value onto the `min + n·step` lattice before the change compare, so
-    /// `GetValue` on a stepped slider can only ever answer a lattice point ([`slider_set_value`],
-    /// which is the whole kernel transcribed). A `step` of exactly `0.0` — the ctor default, and
-    /// what every scrollbar template leaves it at — skips the quantiser outright, which is the
-    /// gate that keeps `UIPanelScrollBarTemplate` continuous.
+    /// `SetValueStep` (`+0x324`): every stored value is quantised onto `min + n·step`
+    /// ([`slider_set_value`]); 0, the default the scrollbars keep, skips the quantiser.
     pub step: f32,
-    /// `true` = VERTICAL (the ctor default; value maps along the track's height, min at the top),
-    /// `false` = HORIZONTAL (`orientation`; shared enum `0x811b00` HORIZONTAL=0/VERTICAL=1).
+    /// VERTICAL, the default, puts `min` at the top of the track (enum `0x811b00`).
     pub vertical: bool,
-    /// The thumb texture region (`SetThumbTexture`/`<ThumbTexture>`), created on first set. A
-    /// renderer positions this region's rect at [`Self::fraction`] along the orientation axis.
+    /// The thumb texture (`<ThumbTexture>`), placed at [`Self::fraction`] along the track.
     pub thumb: Option<RegionHandle>,
 }
 
@@ -1588,38 +941,11 @@ impl Default for SliderState {
     }
 }
 
-/// **The slider drag law — the one owner, for every lane.**
-///
-/// Two pure functions, stated on a single axis in *distance from the track's leading edge* (the
-/// end the thumb sits at when the value is `min`). That framing is what makes them lane-neutral:
-/// the Lua widget arena measures y **up** and the Bevy-UI glue screens measure y **down**, and
-/// both reduce to "how far along the track is this", so neither has to restate the arithmetic.
-///
-/// Restating it is exactly what went wrong. The AddOns glue scrollbar shipped with a *decorative*
-/// knob and no drag at all (1297 named the gap; B273's reporter hit it), the char-create glue
-/// scrollbar grew its own accumulated-delta drag that drifts off the cursor, and the engine slider
-/// held the real formula — three surfaces, one widget, no shared line of code. These two functions
-/// are that shared line.
-///
-/// **The law is benilla's, and it diverges from 1.12 deliberately in one place.** `CSimpleSlider`
-/// (`0x789ba0`/`0x789ca0`) has **no thumb hit-test in the class at all** — every press, track or
-/// thumb, warps the value to seat the thumb's CENTER under the cursor and begins one continuous
-/// drag capture, button-agnostic, clamped by SetValue. We take all of that except the thumb press:
-/// ours grabs **offset-preserving**, so the point you grabbed stays under the finger instead of
-/// jumping to the thumb's middle (decision 0992 §6 — kept as the less surprising feel, and
-/// invisible on a reference-sized thumb either way). If that ever flips to byte-faithful, it flips
-/// here, once, for every surface at the same time.
-///
-/// [`slider_grab`] runs on the press, [`slider_fraction`] on the press and on every move after it.
-///
-/// Where a press grabs the thumb: the offset from the thumb's leading edge that stays under the
-/// cursor for the rest of the drag.
-///
-/// `cursor` and `thumb_lead` are distances from the track's leading edge; `thumb_extent` is the
-/// thumb's length along the axis. A press **on** the thumb keeps its grabbed point (0992 §6); a
-/// press **off** it — anywhere on the track — grabs the thumb by its center, which is what makes
-/// the value warp under the cursor and the drag continue as one gesture (1.12's whole law, and
-/// 0989's directed requirement, which converged with it).
+/// Where a press grabs the thumb: the offset from its leading edge that stays under the cursor,
+/// with distances from the track's leading edge so every UI surface shares it. Off the thumb it
+/// is the center, warping the value under the cursor. Deviation: on the thumb it is the grabbed
+/// point, where `CSimpleSlider` (`0x789ba0`/`0x789ca0`) always centers it, because that feels
+/// less surprising and a stock-sized thumb hides the difference.
 pub fn slider_grab(cursor: f32, thumb_lead: f32, thumb_extent: f32) -> f32 {
     if cursor >= thumb_lead && cursor <= thumb_lead + thumb_extent {
         cursor - thumb_lead
@@ -1628,13 +954,8 @@ pub fn slider_grab(cursor: f32, thumb_lead: f32, thumb_extent: f32) -> f32 {
     }
 }
 
-/// Cursor → fraction of travel, absolute and drift-free: the thumb's leading edge goes to
-/// `cursor − grab`, and that lands at `fraction × (track_extent − thumb_extent)`.
-///
-/// `None` when the travel is zero or negative — a thumb as long as its track has nowhere to go, so
-/// there is no value to compute and the caller must leave the slider alone rather than divide by
-/// zero. Otherwise clamped to `[0, 1]`: dragging past either end pins there, exactly as the
-/// client's own out-of-span presses pin through SetValue's clamp.
+/// The fraction of travel that puts the thumb's leading edge at `cursor − grab`, clamped to
+/// `[0, 1]` as `SetValue` clamps; `None` when the thumb fills the track.
 pub fn slider_fraction(
     cursor: f32,
     grab: f32,
@@ -1645,45 +966,16 @@ pub fn slider_fraction(
     (travel > 0.0).then(|| ((cursor - grab) / travel).clamp(0.0, 1.0))
 }
 
-/// **`CSimpleSlider::SetValue`'s arithmetic kernel — `0x789930`, clamp then quantise.**
-///
-/// The value a `SetValue(v)` actually stores, given the widget's range fields as the client holds
-/// them: `min` = `[+0x318]`, `span` = `[+0x31c]` (the client keeps the *span*, not the max — the
-/// range setter `0x7898f0` stores `end − start` and `0x789a60` re-derives `max = span + min`), and
-/// `step` = `[+0x324]`.
-///
-/// Transcribed op-for-op from `0x789930`, byte-exact — the emitted jccs read:
-///
-/// 1. **clamp-low** (`0x789947`..`0x78995f`) — `fld min; fcomp v; test ah,0x41; jne`: `max(min, v)`,
-///    with an unordered compare (NaN) taking the `v` arm.
-/// 2. **`bound = span + min`** (`0x789962`/`0x789968`), spilled to the f32 slot `[ebp-4]`.
-/// 3. **clamp-high** (`0x78996e`..`0x78999c`) — `hi = bound` *reloaded as f32* iff `bound < lo`
-///    ordered-strict; otherwise `hi` is the clamp-low again. Net: `clamp(v, min, bound)`, except
-///    that a **degenerate range pins to `bound`, not to `min`** — which is the one place this
-///    replaced an assumption, our old `v.clamp(min, max.max(min))` having pinned the other way.
-/// 4. **quantise** (`0x78999c`..`0x789a06`), skipped entirely when `step == 0.0`:
-///    `diff = hi − min`, `halfstep = step · 0.5`, then **round-half-away-from-zero** —
-///    `(diff + halfstep) / step` when `diff > 0` ordered, `(diff − halfstep) / step` otherwise
-///    (`≤ 0` and NaN both take the round-down arm) — truncated toward zero by `__ftol`, and
-///    `hi = n · step + min`.
-///
-/// Two consequences worth stating because they look like bugs and are not:
-///
-/// * **The quantised value is NOT re-clamped.** With a range that is not a whole number of steps,
-///   the top of the travel rounds *past* `max` by up to half a step. Every stepped slider the
-///   reference ships is an exact multiple (`FauxScrollFrame_Update` builds its range as
-///   `(numItems − numToDisplay) · valueStep`; the option sliders are all 10/20/100 steps), so the
-///   overshoot is unreachable there — but an addon's odd range really does produce it.
-/// * **The lattice is anchored at `min`, not at zero**, so a slider over `[0.25, 1.0]` stepping by
-///   `0.1` settles on `0.25, 0.35, …`, never on `0.3`.
-///
-/// The f64 intermediates are the x87 register stack at PC_53, and the two `as f32` narrowings are
-/// its two `fst`/`fstp` spills — not an approximation of them.
+/// `CSimpleSlider::SetValue`'s arithmetic (`0x789930`), op for op. The client holds the range as
+/// `min` and `span` (`0x7898f0` stores `end − start`). Clamp into `[min, span + min]`, a
+/// degenerate range pinning to `span + min`; then, unless `step` is 0, round half away from zero
+/// onto the `min + n·step` lattice. The result is not re-clamped, so an uneven range can overshoot
+/// `max` by up to half a step. The f64 intermediates are the x87 registers, each `as f32` a spill.
 pub fn slider_set_value(v: f32, min: f32, span: f32, step: f32) -> f32 {
     let minv = f64::from(min);
     let vv = f64::from(v);
 
-    // clamp-low: `fcomp(min, v)` falls through to `min` only on `min > v` ordered-strict.
+    // Clamp low: `fcomp(min, v)` takes `min` only on `min > v` ordered, so a NaN `v` passes.
     let clamp_low = |v: f64| {
         if matches!(minv.partial_cmp(&v), Some(core::cmp::Ordering::Greater)) {
             minv
@@ -1693,10 +985,10 @@ pub fn slider_set_value(v: f32, min: f32, span: f32, step: f32) -> f32 {
     };
     let lo = clamp_low(vv);
 
-    // `bound = span + min`, live, and spilled to f32 at `[ebp-4]`.
+    // `bound = span + min`, spilled to f32 at `[ebp-4]`.
     let bound = f64::from(span) + minv;
     let mut hi = if matches!(bound.partial_cmp(&lo), Some(core::cmp::Ordering::Less)) {
-        f64::from(bound as f32) // `fld [ebp-4]` — the f32 reload, not the live value
+        f64::from(bound as f32) // `fld [ebp-4]`: the f32 reload, not the live value
     } else {
         clamp_low(vv)
     };
@@ -1718,8 +1010,7 @@ pub fn slider_set_value(v: f32, min: f32, span: f32, step: f32) -> f32 {
 }
 
 impl SliderState {
-    /// The value fraction `(value − min) / (max − min)`, clamped to `[0, 1]`; a degenerate range
-    /// (`max <= min`, an unscrollable slider) is `0.0` — the thumb sits at the track's start.
+    /// The value fraction in `[0, 1]`; `0.0` when `max <= min`, the thumb at the track's start.
     pub fn fraction(&self) -> f32 {
         if self.max > self.min {
             ((self.value - self.min) / (self.max - self.min)).clamp(0.0, 1.0)
@@ -1728,25 +1019,9 @@ impl SliderState {
         }
     }
 
-    /// `SetValue` (`0x789930`): clamp **and quantise** `v` ([`slider_set_value`]) and store it;
-    /// returns `Some(value)` when the caller must fire `OnValueChanged`. The fire law is the
-    /// client's, read off the emitted jccs: **no range yet → a complete
-    /// no-op**; **first-ever value → always store and fire**; after that, **fire iff the
-    /// clamped/step-quantised value differs** from the stored one. The change-gate is load-bearing,
-    /// not an optimisation: the reference scrollbar wires `OnValueChanged → SetVerticalScroll →
-    /// scrollbar:SetValue` back on itself, and the gate is what stops that after one hop.
-    ///
-    /// **The quantiser is inside the gate, not after it**, and that is what makes a stepped
-    /// slider's drag cheap as well as faithful: a thumb moved a pixel within one step's band
-    /// resolves to the same lattice point and fires nothing at all, exactly as the reference's
-    /// `fcom` against `[+0x320]` decides.
-    ///
-    /// The client holds the range as `min` + `span`; we hold `min` + `max`, so the span is derived
-    /// here the way `0x7898f0` computes it (`end − start`, at f64 and narrowed). That keeps
-    /// `GetMinMaxValues` answering the exact pair that was set — the reference's own `max` is
-    /// re-derived as `span + min` and can differ from it in the last ulp — at the cost of the
-    /// clamp bound being that same re-derivation. A degenerate range (`max < min`) pins to the
-    /// bound, which is the client's arm, not to `min`.
+    /// `SetValue` (`0x789930`): stores the settled value, returning it when `OnValueChanged` fires:
+    /// never without a range, always the first time, else only on a change, which is what ends the
+    /// scrollbar's `SetVerticalScroll` loop. The span is derived as `0x7898f0` computes it.
     pub fn store_value(&mut self, v: f32) -> Option<f32> {
         if !self.range_valid {
             return None;
@@ -1761,27 +1036,9 @@ impl SliderState {
         })
     }
 
-    /// **`SetValueStep` (`0x789a60`) — which is not a field write** (decision 2143).
-    ///
-    /// The byte read:
-    ///
-    /// 1. `0x789a66` stores the step — **unconditional**.
-    /// 2. `0x789a6c test byte [+0x314],2` — **no range yet ⇒ return, and nothing else happens.**
-    /// 3. Otherwise `0x789a91 call 0x7898f0(min, f32(span + min))` — [`Self::set_min_max`] with the
-    ///    max **re-derived**, which re-clamps the held value through `SetValue` when one exists,
-    ///    re-quantising it onto the NEW lattice and firing `OnValueChanged` if it moved.
-    ///
-    /// So a step handed to a slider that already holds a value can move that value and fire — and,
-    /// because `span′ = f32(f32(span + min) − min)` is **not the identity**, it can also change the
-    /// range (`min = 1.0`, `span = 1e-8` collapses it to zero). Ours stored the step and stopped,
-    /// which diverged on all three counts and on the next `GetMinMaxValues` besides.
-    ///
-    /// Inert for every caller the reference ships, and **not for the reason decision 2133 gave**
-    /// (that they set the range and the step before any value exists — true only of each site's
-    /// first run; `FauxScrollFrame_Update` re-runs on a live bar from fourteen update functions and
-    /// never calls `SetValue` at all). It is inert because the only writer of the value is
-    /// `SetValue`, which quantises on the way in, so the value is always already on the lattice
-    /// being re-imposed.
+    /// `SetValueStep` (`0x789a60`): stores the step, then with a range re-runs `SetMinMaxValues`
+    /// with the max re-derived as `f32(span + min)` (`0x789a91`), which can re-quantise the value,
+    /// fire `OnValueChanged` and even change the range, since that sum rounds.
     pub fn set_value_step(&mut self, step: f32) -> Option<f32> {
         self.step = step;
         if !self.range_valid {
@@ -1792,9 +1049,7 @@ impl SliderState {
         self.set_min_max(self.min, max)
     }
 
-    /// `SetMinMaxValues` (`0x7898f0`): set the range, mark it valid, and re-clamp the held value
-    /// **only if one exists** (bit2) — a fresh slider's zero-init value is not a value, so a range
-    /// that excludes zero fires nothing. Returns what [`Self::store_value`] would for the re-clamp.
+    /// `SetMinMaxValues` (`0x7898f0`): sets the range; re-settles the value only once one exists.
     pub fn set_min_max(&mut self, min: f32, max: f32) -> Option<f32> {
         (self.min, self.max) = (min, max);
         self.range_valid = true;
@@ -1806,66 +1061,27 @@ impl SliderState {
     }
 }
 
-/// A `ColorSelect`'s colour (`CSimpleColorSelect`, ctor `0x78b220`) — **three HSV `f32`s**, hue in
-/// **degrees**, and `-1` for the hue of anything grey.
-///
-/// **This is the corrected model, and the correction is the point.** The obvious store is three RGB
-/// bytes, and it is wrong: the ctor `0x78b220` initialises `+0x328` hue-degrees, `+0x32c`
-/// saturation, `+0x330` value, all `f32`, to `(0, 0, 1)` = white — with the packed dword at
-/// `+0x334` a *derived cache* for the value-strip gradient, not the state. Two consequences a byte
-/// store cannot express: hue survives a drag that takes saturation to zero, and `GetColorHSV`
-/// really does answer `-1` for a grey (`0x7bbc80` writes the sentinel at `0x7bbccd`).
-///
-/// **The round trip is not the identity, and that is the client's arithmetic, not ours.** There are
-/// two quantizers and they disagree:
-///
-/// * **A, inbound, round-half-up** — `SetColorRGB` only: `trunc(v·255 + 0.5)` via the CRT `__ftol`
-///   (`0x78ec7d`/`0x78ec91`/`0x78eca9`).
-/// * **B, outbound, floor** — every read path: `(bits_f32(v·255 + 512.0) >> 14) & 0xff`
-///   (`0x7bbec0`), a one-sided `2^-15` window.
-///
-/// Composed over the lossy `f32`-degrees hue trip, an exhaustive sweep of all 256³ reachable
-/// triples finds **1,636,226 (9.7527 %) come back with exactly one channel exactly `-1`** — never
-/// `+1`, never `±2`, never the minimum channel, greys never. And because `quantize_a(b/255) == b` for
-/// every byte, it **ratchets**: the FrameXML idiom `r,g,b = f:GetColorRGB() … f:SetColorRGB(r,g,b)`
-/// re-applies the same lossy map instead of settling — `(0, 8, 132)` walks to `(0, 0, 132)` in eight
-/// cycles. Every Ace2/Dewdrop colour option is that idiom, once per open-and-accept.
-///
-/// It is transcribed rather than smoothed **because it is what the client computes** and the addons
-/// were written against it. If it ever has to go, the surgical change is one line — using
-/// quantizer A on the read-back too drives the mismatch count to exactly 0, measured — and it
-/// would be a deliberate, recorded deviation, not a bug fix.
-///
-/// No alpha: `SetColorRGB` reads an optional 5th argument, quantizes it, and *discards* it
-/// (`0x7bbf20` reads three bytes; `0x7bbec0` hard-writes `0xff`). The reference's opacity is a
-/// separate `Slider`. `SetColorHSV`/`GetColorHSV` (`0x78e920`/`0x78ea00`) have zero callers across
-/// the 218-addon corpus, so they wait for a customer (decision 1195) — but the state they would read
-/// and write is now the right shape for them.
+/// A `ColorSelect`'s colour (ctor `0x78b220`): HSV `f32`s, hue in degrees, `-1` for a grey
+/// (`0x7bbccd`). RGB enters rounded half up (quantizer A) and leaves floored (B), so a
+/// `GetColorRGB`/`SetColorRGB` round trip drops a channel by 1 for about 9.75 % of colours, and
+/// repeating it ratchets; that drift is the reference's. `SetColorRGB` discards a fifth argument.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct ColorSelectState {
-    /// `[hue-degrees, saturation, value]` — the widget's `+0x328`/`+0x32c`/`+0x330`. Hue is `-1.0`
-    /// whenever saturation is 0 (the grey sentinel).
+    /// `[hue°, saturation, value]` (`+0x328`/`+0x32c`/`+0x330`); an RGB grey has hue `-1.0`.
     pub hsv: [f32; 3],
-    /// `<ColorWheelTexture>` / `SetColorWheelTexture` (`0x78de90`), the widget's `+0x318` — the hue
-    /// disc. The **rect of this region is the wheel's hit box**: the press handler tests the cursor
-    /// against `[+0x318]+0x24`, not against the frame. Created on first set, like a Slider's thumb.
+    /// The hue disc (`<ColorWheelTexture>`, `0x78de90`, `+0x318`), its rect the wheel's hit box.
     pub wheel: Option<RegionHandle>,
-    /// `<ColorWheelThumbTexture>` / `SetColorWheelThumbTexture` (`0x78e160`) — the little marker
-    /// that rides the disc. Its rect is *derived* from `hsv` at extract, and an anchor authored on
-    /// it in XML is **discarded**: `0x78b850` calls `ClearAllPoints 0x767ed0` and re-`SetPoint`s
-    /// from C++ on every colour change. The two thumbs are the only elements here with a `file=`
-    /// and the only ones the reference gives no `<Anchors>` — those two facts are the same fact.
+    /// The disc's marker (`<ColorWheelThumbTexture>`, `0x78e160`), placed from `hsv` at extract;
+    /// an XML anchor on it is discarded (`0x78b850` re-points it on every colour change).
     pub wheel_thumb: Option<RegionHandle>,
-    /// `<ColorValueTexture>` / `SetColorValueTexture` (`0x78e450`), the widget's `+0x320` — the
-    /// brightness strip, and the second hit box (`[+0x320]+0x24`).
+    /// The brightness strip (`<ColorValueTexture>`, `0x78e450`, `+0x320`), the second hit box.
     pub value_strip: Option<RegionHandle>,
-    /// `<ColorValueThumbTexture>` / `SetColorValueThumbTexture` (`0x78e720`) — the strip's marker,
-    /// rect derived from `hsv[2]`.
+    /// The strip's marker (`<ColorValueThumbTexture>`, `0x78e720`), placed from `hsv[2]`.
     pub value_thumb: Option<RegionHandle>,
 }
 
 impl Default for ColorSelectState {
-    /// The ctor's own initial state: H=0, S=0, V=1 — white (`0x78b27e`/`0x78b298`/`0x78b28e`).
+    /// The ctor's white: H=0, S=0, V=1 (`0x78b27e`/`0x78b298`/`0x78b28e`).
     fn default() -> ColorSelectState {
         ColorSelectState {
             hsv: [0.0, 0.0, 1.0],
@@ -1878,43 +1094,33 @@ impl Default for ColorSelectState {
 }
 
 impl ColorSelectState {
-    /// **Quantizer A** — `SetColorRGB`'s inbound leg only (`0x78ec7d`/`0x78ec91`/`0x78eca9`): clamp
-    /// to `[0, 1]`, `·255.0 + 0.5`, then the CRT `__ftol` (`0x40a2b0`) which forces round-to-chop.
-    /// Round-**half-up**. The `255.0`/`0.5` operands are `f32` in `.rdata` and widen exactly, so the
-    /// chain runs in `f64` as the x87 PC_53 registers do.
+    /// Quantizer A, `SetColorRGB`'s inbound leg (`0x78ec7d`): clamp to `[0, 1]`, `·255 + 0.5`,
+    /// truncate (`__ftol`, `0x40a2b0`), so round half up, in `f64` as the x87 registers run it.
     pub fn quantize_a(v: f64) -> u8 {
         let clamped = if v.is_nan() { 0.0 } else { v.clamp(0.0, 1.0) };
         // In-range the product is `[0.5, 255.5]`, so the truncation is always a valid byte.
         (clamped * 255.0 + 0.5) as u8
     }
 
-    /// **Quantizer B** — `0x7bbec0`'s magic-512 pack, on *every* outbound path (the `OnColorSelect`
-    /// payload `0x78bb42`, `GetColorRGB` `0x78ede6`, the strip tint `0x78bbf6`). `v·255 + 512.0`
-    /// lands in the `[512, 1024)` binade where the `f32` ulp is exactly `2^-14`, so the mantissa
-    /// holds `RN(v·255·2^14)` and `>>14` reads its **floor**. No clamp — out-of-range wraps mod 256,
-    /// which is reachable through `SetColorHSV` (unclamped) but not through `SetColorRGB`.
+    /// Quantizer B, every outbound path (`0x7bbec0`): `v·255 + 512` as `f32` has a `2^-14` ulp, so
+    /// `>> 14` reads the floor of `v·255`. Unclamped: out of range wraps mod 256.
     pub fn quantize_b(v: f32) -> u8 {
         let c = (f64::from(v) * 255.0 + 512.0) as f32;
         ((c.to_bits() >> 14) & 0xff) as u8
     }
 
-    /// `0x7bbf20`'s unpack — a colour byte back to `f32`, scaling by the **`f32`** `0x3b808081`
-    /// (≈1/255, rounded *up*: this is why the only round-trip failure mode is a shortfall that
-    /// floors down). Distinct from the `f64` `1/255` the Lua push uses; both appear in one call.
+    /// `0x7bbf20`'s unpack: the byte times the `f32` `0x3b808081`, 1/255 rounded up.
     fn unpack_byte(b: u8) -> f32 {
         let k = f32::from_bits(0x3b80_8081);
         (f64::from(i32::from(b)) * f64::from(k)) as f32
     }
 
-    /// The Lua-facing normalize (`0x78bb47..0x78bb85` and `0x78edfa`/`0x78ee17`/`0x78ee34`): the
-    /// channel byte times the **`f64`** `1/255` at `0x804578` — a multiply by the reciprocal, never a
-    /// divide (they are not the same double).
+    /// The Lua-facing normalize: the byte times the `f64` `1/255` at `0x804578`, never a divide.
     pub fn normalize(byte: u8) -> f64 {
         f64::from(byte) * (1.0_f64 / 255.0)
     }
 
-    /// `0x7bf680` — the index of the largest `|component|`. Compares are strict `>` (`fcom`; equal
-    /// takes the not-greater branch), so a tie resolves to the **later** index.
+    /// `0x7bf680`: the index of the largest `|component|`, a tie going to the later index.
     fn dominant_axis(v: &[f32; 3]) -> usize {
         let (a0, a1, a2) = (v[0].abs(), v[1].abs(), v[2].abs());
         if a0 > a1 {
@@ -1930,7 +1136,7 @@ impl ColorSelectState {
         }
     }
 
-    /// `0x7bf700` — the index of the smallest `|component|`, traced from the same flag pattern.
+    /// `0x7bf700`: the index of the smallest `|component|`.
     fn minor_axis(v: &[f32; 3]) -> usize {
         let (a0, a1, a2) = (v[0].abs(), v[1].abs(), v[2].abs());
         if a0 >= a1 {
@@ -1946,10 +1152,7 @@ impl ColorSelectState {
         }
     }
 
-    /// `0x7bbc80` — RGB→HSV. `value` is the dominant channel; `saturation = (value − minor)/value`
-    /// (0 when `value == 0`); `hue` is the `-1` sentinel when saturation is 0, else the 60°-sector
-    /// formula on the chroma, wrapped `+360` if negative. Each store rounds to `f32`; the chroma
-    /// divide runs on the un-rounded `f64` register.
+    /// `0x7bbc80`, RGB to HSV: each store rounds to `f32`; the chroma divide runs in `f64`.
     fn rgb_to_hsv(rgb: &[f32; 3]) -> [f32; 3] {
         let f = f64::from;
         let dom = Self::dominant_axis(rgb);
@@ -1979,10 +1182,8 @@ impl ColorSelectState {
         [hue, sat, value]
     }
 
-    /// `0x7bbd60` — HSV→RGB. `s == 0` short-circuits to `(v, v, v)` *without reading hue*, which is
-    /// what makes the `-1` sentinel inert on the way out. Otherwise the 6-sector decode, with the
-    /// sector floored by the same magic-512 trick as quantizer B and clamped to `≤ 5`. The
-    /// `f32(1/60) = 0x3c888889` on the way back is the lossy step the whole `-1` drift comes from.
+    /// `0x7bbd60`, HSV to RGB: a grey never reads hue; the sector is floored by quantizer B's
+    /// trick, and the `f32` 1/60 (`0x3c888889`) is where the round trip's drift comes from.
     pub fn hsv_to_rgb(hsv: &[f32; 3]) -> [f32; 3] {
         let f = f64::from;
         let (h, s, v) = (hsv[0], hsv[1], hsv[2]);
@@ -2009,24 +1210,13 @@ impl ColorSelectState {
         }
     }
 
-    /// Store HSV **raw** — no clamp, no quantize, no round trip through RGB. This is what the
-    /// widget's own drag handler does (`0x78bd80`: `fstp [esi+0x328]` / `[+0x32c]` / `[+0x330]`
-    /// straight off the geometry) and what `SetColorHSV 0x78e920` does. The reachable state set is
-    /// therefore *strictly finer* than [`Self::set_rgb`]'s, which can only ever land on the HSV
-    /// image of the 8-bit lattice —
-    /// the picker's wheel resolves colours the Lua boundary cannot name. What Lua *reads back* is
-    /// quantized identically either way, because the quantize lives on the outbound leg.
+    /// Stores HSV raw, as the drag handler (`0x78bd80`) and `SetColorHSV` (`0x78e920`) do.
     pub fn set_hsv(&mut self, h: f32, s: f32, v: f32) {
         self.hsv = [h, s, v];
     }
 
-    /// `SetColorRGB`'s whole store, in the binary's order (`0x78eb7e`…`0x78ecfa`): clamp each
-    /// argument to `[0, 1]` as `f32` → quantizer A → back to `f32` through `0x7bbf20`'s `1/255` →
-    /// `0x7bbc80` RGB→HSV → store. Always stores — there is deliberately **no change-gate**, unlike
-    /// [`SliderState::store_value`]: the only conditional between `SetColorRGB`'s entry and its
-    /// handler invoke is `0x78bafd`, which tests whether a handler is *bound*, and none of the three
-    /// writers reads the old HSV before overwriting it. Two sibling widgets in the same band,
-    /// opposite gating.
+    /// `SetColorRGB`'s store (`0x78eb7e`): quantizer A, the `0x7bbf20` unpack, RGB to HSV. It
+    /// always stores, with no change gate: `0x78bafd` only tests whether a handler is bound.
     pub fn set_rgb(&mut self, r: f64, g: f64, b: f64) {
         let bytes = [
             Self::quantize_a(r),
@@ -2041,10 +1231,8 @@ impl ColorSelectState {
         self.hsv = Self::rgb_to_hsv(&rgb);
     }
 
-    /// The read-back both `GetColorRGB` and the `OnColorSelect` payload run — literally the same two
-    /// calls in the same order (`0x78edda`/`0x78ede6` vs `0x78bb36`/`0x78bb42`), which is *why* a
-    /// handler's `arg1..arg3` are bit-identical to a `GetColorRGB()` on the next line: HSV→RGB, then
-    /// quantizer B, then the `f64` `1/255`.
+    /// The read-back `GetColorRGB` (`0x78edda`) and the `OnColorSelect` payload (`0x78bb36`) both
+    /// run, so they match bit for bit: HSV to RGB, quantizer B, then the `f64` `1/255`.
     pub fn rgb_f64(&self) -> (f64, f64, f64) {
         let rgb = Self::hsv_to_rgb(&self.hsv);
         (
diff --git a/crates/benilla-ui/src/widget/mod.rs b/crates/benilla-ui/src/widget/mod.rs
index 5d63115a..3784f93a 100644
--- a/crates/benilla-ui/src/widget/mod.rs
+++ b/crates/benilla-ui/src/widget/mod.rs
@@ -1,64 +1,18 @@
-//! The widget object model — the frame arena and the show/hide/strata/level/scale/alpha
-//! mutations, transcribed from the reference's binary-verified propagation cluster (decision 0068).
-//!
-//! This crate owns the *model*, not the runtime: the arena stores frames and their region leaves and
-//! implements the propagation math, but it does **not** run Lua or fire `OnShow`/`OnHide` — the
-//! mutations that cause visibility transitions *return the set of frames that changed* so the
-//! Lua-embedding layer (the app) can fire the handlers in order.
-//!
-//! ## Ground truth (binary-verified against `WoW.exe`)
-//!
-//! - **Effective visibility** (show `0x76ae10` / hide `0x76ad50`): `effectiveVisible = shown AND
-//!   (parent == null OR parent.effectiveVisible)`.
-//!   A transition recurses into child frames — **a hidden mid-tree frame blocks its whole subtree** —
-//!   and fires `OnShow`/`OnHide`. The recursion is *transition-gated*: a node whose effective
-//!   visibility does not change stops the walk (its subtree cannot have changed).
-//! - **Strata** (`set_frame_strata 0x76a470`): the **whole subtree is forced to one stratum** — the
-//!   frame's strata is set, then every child frame is recursively set to the same value.
-//! - **Level** (`set_frame_level 0x76a4f0`): clamp `>= 0`; `delta = new - old`; **same-strata**
-//!   children shift by the same `delta` (relative offsets preserved); cross-strata children are
-//!   untouched.
-//! - **Effective scale** (`0x76ac90`): `effectiveScale = parentScale * ownScale`,
-//!   written to `layoutScale`, **ε-gated** (skip the write + recursion if `|new - cur| < 2.384e-7`,
-//!   the `_DAT_008029d4` constant — [`SCALE_EPS`]); recurse to child frames.
-//! - **Alpha** (`SetAlpha 0x76a690`):
-//!   an eager set-time **overwrite-cascade** — SetAlpha writes the raw value to the frame and
-//!   recurses over its child frames pushing the SAME value (a flatten, like the strata subtree-
-//!   force; never a draw-time ancestor product). At draw a region multiplies its own alpha by its
-//!   OWNER frame's alpha only (one hop, `0x772180`/`0x77fac0`) — which is what `effective_alpha`
-//!   feeds, so effective always equals own.
-//! - **Named auto-publish**: a frame with a name is published to the global name table; a duplicate
-//!   name does **not** overwrite the first (see [`WidgetArena::lookup`]).
-//!
-//! ## Alpha: the settled model (the old 1.12-vs-Era tension is resolved)
-//!
-//! An earlier INFERRED reading ("1.12 alpha is not tree-propagated") kept a dormant Era-style
-//! propagation flag here as a hedge. `SetAlpha 0x76a690` settled it: 1.12
-//! DOES reach the subtree, but by set-time overwrite (the same raw byte pushed to every
-//! descendant frame's `+0xc8`), not by a live parent×child product — Era's `ignoreParentAlpha`
-//! belongs to the later multiplicative model and has no 1.12 counterpart (there is no
-//! `GetEffectiveAlpha` in 5875). The hedge machinery is gone; [`WidgetArena::set_alpha`] IS the
-//! client's mechanism. Consequences worth knowing: a child's later own-SetAlpha diverges from its
-//! parent until the parent is set again (last write wins), and a frame created under a dimmed
-//! parent starts at 1.0 (creation does not re-push the parent's alpha). Scale keeps its own
-//! (verified multiplicative) propagation and Era `ignore_parent_scale` opt-out, inert in 1.12.
+//! The widget object model: the frame arena, its regions, and the reference's propagation of
+//! show, strata, level, scale and alpha down the frame tree. It runs no Lua: a mutation that
+//! moves visibility returns the frames that changed, for the caller to fire `OnShow`/`OnHide`.
 
 use std::collections::HashMap;
 
 use crate::order::{DrawLayer, Strata};
 
-/// The scale-propagation ε — `_DAT_008029d4` = `0x34800000` ≈ 2.384e-7 (`0x76ac90`): a
-/// recomputed effective scale within ε of the current one is skipped (no write, no recursion).
-/// This is the *same* binary constant the layout resolver uses for its `OnSizeChanged`
-/// gate, so we reuse it rather than restate the value.
+/// The effective-scale epsilon of `0x76ac90`: the client's constant `0x8029d4` (`0x34800000`,
+/// about 2.384e-7), the same one the layout's `OnSizeChanged` gate uses.
 pub const SCALE_EPS: f64 = crate::layout::SIZE_EPS;
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Handles — generational, so a destroyed-then-reused slot never aliases a stale handle
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Handles ──────────────────────────────────────────────────────────────────────────────────
 
-/// A generational handle to a [`Frame`] in a [`WidgetArena`]. Copyable and comparable; a handle to a
-/// destroyed frame is detected (the slot's generation moved on) and reads return `None`.
+/// A generational handle to a [`Frame`]: it stops resolving once the frame is destroyed.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 pub struct FrameHandle {
     index: u32,
@@ -73,26 +27,21 @@ pub struct RegionHandle {
 }
 
 impl RegionHandle {
-    /// The handle's identity as one integer — index and generation packed — for the layout change
-    /// gate's fingerprint (`script::layout::InputFingerprint`), which must notice a region being
-    /// swapped for a different one at the same map size.
+    /// Index and generation in one integer: the layout gate's fingerprint must see a region swap.
     #[inline]
     pub(crate) fn fingerprint_bits(self) -> u64 {
         (u64::from(self.generation) << 32) | u64::from(self.index)
     }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// A hand-rolled generational arena (no external deps — a slotmap in miniature)
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The generational arena ───────────────────────────────────────────────────────────────────
 
 struct Slot<T> {
     generation: u32,
     value: Option<T>,
 }
 
-/// Minimal generational arena: `insert` reuses freed slots, `remove` bumps the slot's generation so
-/// old handles stop resolving. Indices/generations are `u32` — plenty for a UI.
+/// `remove` bumps the slot's generation, so an old handle stops resolving.
 struct Arena<T> {
     slots: Vec<Slot<T>>,
     free: Vec<u32>,
@@ -150,7 +99,6 @@ impl<T> Arena<T> {
         slot.value.as_mut()
     }
 
-    /// Iterate live entries as `(index, generation, &value)`.
     fn iter(&self) -> impl Iterator<Item = (u32, u32, &T)> + '_ {
         self.slots
             .iter()
@@ -158,7 +106,6 @@ impl<T> Arena<T> {
             .filter_map(|(i, s)| s.value.as_ref().map(|v| (i as u32, s.generation, v)))
     }
 
-    /// Iterate live entries as `(index, generation, &mut value)`.
     fn iter_mut(&mut self) -> impl Iterator<Item = (u32, u32, &mut T)> + '_ {
         self.slots
             .iter_mut()
@@ -167,9 +114,7 @@ impl<T> Arena<T> {
     }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Widget kinds
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Widget kinds ─────────────────────────────────────────────────────────────────────────────
 
 mod kinds;
 pub use kinds::{
@@ -183,53 +128,26 @@ pub use kinds::{
     TOOLTIP_FADE_SECS, TOOLTIP_LINE_GAP, TOOLTIP_PAD, TOOLTIP_WRAP_WIDTH,
 };
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Frame + Region nodes
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Frame and Region nodes ───────────────────────────────────────────────────────────────────
 
-/// A frame node in the arena — the modeled subset of `CSimpleFrame`.
-///
-/// The invariant-bearing fields (`effective_visible`, `effective_scale`, `effective_alpha`) and the
-/// structural fields (`parent`, `children`, `regions`) are maintained by the [`WidgetArena`]
-/// mutators; treat them as **read-only** and change state through
-/// [`WidgetArena::set_shown`]/[`set_frame_strata`](WidgetArena::set_frame_strata)/etc. so propagation
-/// stays correct. (Not to be confused with [`crate::layout::LayoutInput`], which is the *layout resolver's*
-/// per-frame anchor/size input — a separate concern.)
+/// A frame node, the modelled subset of `CSimpleFrame`. The `effective_*` fields and the tree
+/// links belong to the [`WidgetArena`] mutators: change state through them so it propagates.
 #[derive(Clone, Debug, PartialEq)]
 pub struct Frame {
-    /// The widget subtype.
     pub kind: FrameKind,
-    /// Draw layers switched OFF on this frame — bit `n` = [`DrawLayer::index`] `n`.
-    ///
-    /// `Frame:EnableDrawLayer(layer)` / `DisableDrawLayer(layer)`, present on the Frame
-    /// method table `0x878ec0` at `0x7755b0` / `0x775680`, sitting between `IsToplevel` and `Show`.
-    /// (Read off the `{const char*, void*}` pair bytes; the same walk reproduces the Button table
-    /// at `0x879d00` exactly.)
-    ///
-    /// A disabled layer hides every region the frame owns in it, and the region's own `Show`/`Hide`
-    /// is untouched underneath — re-enabling the layer brings back exactly what was showing before,
-    /// which is why this is a frame-level mask rather than a sweep over the regions. Both corpus
-    /// consumers (pfUI, MoveAnything) use it to strip Blizzard artwork off a frame they are
-    /// reskinning without disturbing what the owner does to its own regions.
+    /// Layers switched off by `DisableDrawLayer` (`0x775680`) and back on by `EnableDrawLayer`
+    /// (`0x7755b0`), bit `n` for [`DrawLayer::index`] `n`: a frame-level mask, so each region
+    /// keeps its own shown state underneath.
     pub disabled_layers: u8,
-    /// The frame's name (its global identifier), if any. See [`WidgetArena::lookup`] for the
-    /// non-overwriting publish rule.
+    /// The global name, which a later duplicate carries without owning ([`WidgetArena::lookup`]).
     pub name: Option<String>,
-    /// The parent frame, or `None` for a top-level frame (attached to the screen root / `UIParent`).
     pub parent: Option<FrameHandle>,
-    /// Child frames in **insertion order** (the client's `+0x300` child list order) — this order is
-    /// the draw-order tiebreak within a `(strata, level)` bucket for equal-insertion children.
+    /// Child frames in link order, oldest first (the client's child list at `+0x300`).
     pub children: Vec<FrameHandle>,
-    /// Owned region leaves (textures/fontstrings), in creation order. A region detached by
-    /// `SetParent(nil)` stays in this list so [`WidgetArena::destroy`] still frees it — see
-    /// [`Region::detached`], which is what actually takes it out of the draw.
+    /// Owned regions in link order, a detached one included so `destroy` frees it.
     pub regions: Vec<RegionHandle>,
-    /// This frame's **title region** — the drag handle at `CSimpleFrame+0xA8`, or `None`.
-    ///
-    /// **One per frame**, which is what makes `CreateTitleRegion` idempotent: a second call returns
-    /// the SAME object after clearing its anchors, so calling it on an XML-declared title region
-    /// silently wipes them (`0x767ed0`→`0x767620`, ClearAllPoints). It is also in
-    /// [`Frame::regions`], so the arena still frees it.
+    /// The title region (`CSimpleFrame+0xA8`), also in `regions`. One per frame: a second
+    /// `CreateTitleRegion` returns it with its anchors cleared (`0x767ed0` → `0x767620`).
     pub title_region: Option<RegionHandle>,
     /// The draw stratum (`frameStrata +0xc0`, default MEDIUM).
     pub strata: Strata,
@@ -237,187 +155,83 @@ pub struct Frame {
     pub level: u16,
     /// This frame's own alpha, 0.0..=1.0 (`alpha +0xc8`, default 1.0).
     pub alpha: f32,
-    /// The alpha a renderer should apply — always == [`Frame::alpha`] (see the module's alpha
-    /// section: 1.12 cascades at set time, so there is no separate draw-time product). Kept as its
-    /// propagated product (see the module tension note).
+    /// Always equal to [`Frame::alpha`]: alpha cascades at set time, and at draw a region
+    /// multiplies only its owner frame's alpha (`0x772180`/`0x77fac0`).
     pub effective_alpha: f32,
-    /// `shown` bit (`shown +0xd0`, default true) — the frame's own Show/Hide state.
+    /// The frame's own Show/Hide bit (`+0xd0`, default true).
     pub shown: bool,
-    /// `effectiveVisible +0xd4` — `shown AND parent-chain visible`. Maintained by propagation.
+    /// `shown` and every ancestor effectively visible (`+0xd4`).
     pub effective_visible: bool,
-    /// Whether the frame accepts the mouse (`EnableMouse`). Default **false** — WoW's `enableMouse`
-    /// default; only mouse-enabled *and* effective-visible frames capture the cursor in
-    /// [`crate::order::hit_test`]. (Keyboard focus / `EnableKeyboard` is a separate flag, out of
-    /// scope in this crate for now.)
+    /// `EnableMouse`: the mouse bit (bit 2) of the input mask `[frame+0xcc]`.
     pub mouse_enabled: bool,
-    /// Whether the frame accepts the **wheel** (`EnableMouseWheel` / XML `enableMouseWheel`) — a
-    /// flag of its own in the reference, and separate from [`Self::mouse_enabled`] there and here
-    /// (decision 1198).
-    ///
-    /// Default **false**, WoW's own default. The wheel dispatch bubbles to the nearest *enabled*
-    /// ancestor carrying an `OnMouseWheel`, which is how a scroll region hands the wheel to the
-    /// window behind it while keeping its handler installed — a frame with a handler it has not
-    /// enabled is deliberately transparent to the wheel.
+    /// `EnableMouseWheel`, or an `<OnMouseWheel>` script at XML load: the mask's wheel bit (3).
+    /// A frame with the script but not the bit is transparent to the wheel.
     pub mouse_wheel_enabled: bool,
-    /// Whether the frame is **keyboard-enabled** (`EnableKeyboard` `0x776f90` / XML
-    /// `enableKeyboard`) — the kind-0/kind-1 bucket membership `0x76af00` writes as
-    /// `[frame+0xcc] |= 1<<kind`.
-    ///
-    /// Default **false**, the client's own default. **This is the field key delivery gates on**:
-    /// [`crate::script::keyboard`]'s walk builds its candidate set from
-    /// `effective_visible && keyboard_enabled`, then orders it strata 8→0 / level high→low /
-    /// oldest-registration-first (built 2026-08-14, decision 1319). `0x76af00` never touches the
-    /// handler slots, so the flag and a handler are separable: `EnableKeyboard(true)` on a
-    /// script-less frame "puts it in the walk where it is called and declines — transparent to
-    /// everything downstream", so **being enabled is not being a handler**.
+    /// `EnableKeyboard` (`0x776ec0`), XML `enableKeyboard` or a key script at XML load: the
+    /// mask's char and key bits (`0x76af00`), which key delivery walks
+    /// ([`crate::script::keyboard`]); a script-less frame there declines.
     pub keyboard_enabled: bool,
-    /// Clamp-to-screen (`SetClampedToScreen` / XML `clampedToScreen` — the client's geometry
-    /// flags **bit4**, applied inside rect assembly `0x767a20`): the layout
-    /// resolve shifts this frame's assembled rect back inside the screen, size preserved.
-    /// Default **true for GameTooltip frames**, false otherwise: the reference tooltip observably
-    /// clamps (the minimap zone-text hover's ANCHOR_LEFT plate hangs down from the screen top
-    /// instead of leaving the window) though its XML never sets the attribute — the class supplies
-    /// the flag — and the rule here is absolute: no tooltip ever leaves the window (decision 0352).
+    /// `SetClampedToScreen`, geometry flags bit 4: `0x767a20` shifts the rect back on screen.
+    /// Every GameTooltip is born with it here; the stock tooltips get it from their template,
+    /// `GameTooltipTemplate.xml:3`.
     pub clamped_to_screen: bool,
-    /// `SetHitRectInsets` / XML `<HitRectInsets>` — how far the frame's **mouse** rect is inset
-    /// from its resolved rect, as `[left, right, top, bottom]` (default all 0, i.e. the hit rect
-    /// IS the frame rect). Only [`crate::order::hit_test`] reads it: drawing, anchoring, and
-    /// `GetLeft`/`GetWidth` all stay on the un-inset rect. The reference uses it wherever a
-    /// button's art fills less than its frame — the micro buttons are 29×58 frames whose art
-    /// occupies only the lower ~40 px, and a `top="18"` inset is what stops that empty header
-    /// from swallowing hover and clicks aimed past the bar.
+    /// `SetHitRectInsets` or `<HitRectInsets>`: the mouse rect's `[left, right, top, bottom]`
+    /// inset. Only the hit test reads it; drawing, anchoring and `GetLeft`/`GetWidth` do not.
     pub hit_rect_insets: [f32; 4],
-    /// `SetMovable` / XML `movable` — whether `StartMoving()` may drag this frame. Default
-    /// **false**, and the flag is a *guard*, not a behaviour: nothing moves until a script calls
-    /// `StartMoving`, and `StartMoving` without this bit set raises instead of moving
-    /// ([`crate::script`]'s `object::movable` cluster).
+    /// `SetMovable`: only a guard, as `StartMoving` errors without it.
     pub movable: bool,
-    /// `SetResizable` / XML `resizable` — the sizing twin of [`Frame::movable`], guarding the
-    /// `StartSizing` half of the same family. Default false. benilla stores and reports the flag;
-    /// no resize *drag* is built (`StopMovingOrSizing` already covers the stop side of both).
+    /// `SetResizable`: the guard `StartSizing` checks.
     pub resizable: bool,
-    /// `SetMinResize` / `SetMaxResize` — the interactive-resize bounds as `(width, height)`
-    /// (`0x776020` / `0x7762a0`, with `GetMinResize 0x775f20` / `GetMaxResize 0x7761a0`; all four
-    /// on the Frame method table `0x878ec0`, stored in the client at `CLayoutFrame+0x5c..+0x68`
-    /// as a `CRect`-shaped `{minY, minX, maxY, maxX}`).
-    ///
-    /// **`0.0` is the client's own "unbounded" sentinel, on each field independently** (1505) — not a
-    /// flag, not a negative, not a `None`: the `CLayoutFrame` ctor `0x767680` zeroes all four, the
-    /// getters hand back two plain numbers (`0, 0` on a frame nobody bounded, never `nil`), and
-    /// the clamp's first test on every axis is `bound == 0.0 → skip`. A **negative** bound is
-    /// therefore live and clamps normally (`0x768710`).
-    ///
-    /// The values are lengths in the same space as the explicit width/height, so they compare
-    /// directly against [`crate::layout::LayoutInput`]'s — the binding runs the byte-identical
-    /// logical→internal transform `SetWidth`'s does.
-    ///
-    /// A window kit's opening lines are `SetResizable(true)` + these two; Quiver's
-    /// `SideEffectMakeMoveable` calls `SetMinResize` on every module frame it builds and died on
-    /// the nil method (part of B267).
-    ///
-    /// **Only the interactive drag reads them** — VERIFIED, not an omission: the setters store raw
-    /// and do not even mark the layout dirty, `CLayoutFrame::SetWidth`/`SetHeight` never consult
-    /// them, and no layout-resolve path does either. A frame sized 100 wide with
-    /// `SetMinResize(400, 400)` stays 100 wide until the first drag tick snaps it into range.
+    /// `SetMinResize` (`0x776020`; `GetMinResize` `0x775f20`): the resize drag's floor, `(width,
+    /// height)` in `SetWidth` units. `0.0` is unbounded per axis (ctor `0x767680`); a negative
+    /// bound clamps (`0x768710`). Only the drag reads it, never `SetWidth` or the layout.
     pub min_resize: (f32, f32),
-    /// The upper twin of [`Frame::min_resize`] — see its doc, including the `0.0` sentinel.
+    /// `SetMaxResize` (`0x7762a0`; `GetMaxResize` `0x7761a0`): the ceiling, same rules.
     pub max_resize: (f32, f32),
-    /// `SetUserPlaced` — the client's "the user placed this frame; persist its position across
-    /// sessions" bit. Default false, readable through `IsUserPlaced`, and consumed by the layout
-    /// cache ([`crate::script::layout_cache`]) — which is where persisting a frame's position
-    /// belongs, rather than with the drag that moved it.
-    ///
-    /// **Necessary, not sufficient.** Every drag entry stamps this bit unconditionally
-    /// (`0x7652b0` @`0x7652e5`), so an addon that drags a stock frame once stamps it too; the
-    /// cache's own filter is this bit AND [`Frame::movable`]`|`[`Frame::resizable`], at both the
-    /// write and the apply, which is what lets the stamp fall off again (decision 2193).
+    /// `SetUserPlaced`: the layout cache keeps this frame's position. Every drag (`0x7652b0`)
+    /// stamps it (`0x7652e5`), so the cache also requires `movable` or `resizable`, at write and
+    /// at apply.
     pub user_placed: bool,
-    /// `SetToplevel` / XML `toplevel` — flag word `[frame+0xb4]` **bit `0x1`**, the same word as
-    /// [`Frame::movable`] (`0x100`) and [`Frame::resizable`] (`0x200`), written by the same pure
-    /// bit-setter `0x76a3c0`. Default false.
-    ///
-    /// The flag only **marks**: setting it performs no raise (`SetToplevel 0x775440` is
-    /// arg-marshal + `0x76a3c0` and returns). What reads it is the raise worker
-    /// `CSimpleTop::Raise 0x7650f0`, which resolves the nearest toplevel *self-or-ancestor* and
-    /// raises **that** — so a frame with this bit clear is never the subject of a raise, and a
-    /// frame with it set is what a click/show anywhere in its subtree lifts. The law, the gate and
-    /// the arithmetic live in [`crate::script::object::toplevel`].
+    /// `SetToplevel` (`0x775440`): bit `0x1` of the flag word `[frame+0xb4]` (`movable` `0x100`,
+    /// `resizable` `0x200`, all set by `0x76a3c0`). It raises nothing; `CSimpleTop::Raise`
+    /// (`0x7650f0`) raises the nearest toplevel self-or-ancestor of a clicked or shown frame.
     pub toplevel: bool,
     /// This frame's own scale (`ownScale +0xb8`, default 1.0).
     pub scale: f32,
     /// `layoutScale` = `parentEffective * ownScale`, ε-gated (`0x76ac90`).
     pub effective_scale: f32,
-    /// Era `ignoreParentScale` opt-out — inert in 1.12 (no frame sets it; extension point).
+    /// A later client's `ignoreParentScale`, not 1.12: nothing sets it.
     pub ignore_parent_scale: bool,
-    /// The Lua-visible numeric id (`GetID`/`SetID`, XML `id=` — the client's `+0xb4`): an
-    /// app-meaning-free label frames carry for their handlers (a dropdown row's list position, a
-    /// tab index). Default 0. Distinct from the layout/wrapper id ([`Model`](crate::script::Model)'s
-    /// bijection) — this one is data, not identity.
+    /// `GetID`/`SetID` and XML `id`, at `+0xb0` (`0x77531f`, `0x7753e7`): data for handlers, such
+    /// as a tab index, not the script model's frame id. Default 0.
     pub wow_id: i64,
-    /// The frame's **live link position** in its `(strata, level)` bucket — the client's intrusive
-    /// list order, not a creation index. Seeded at creation and re-stamped to the bucket's tail by
-    /// [`WidgetArena::resequence_to_tail`] on every relink the reference performs: becoming
-    /// effectively visible, and a *changing* strata or level on an already-visible frame.
-    ///
-    /// It orders **two** sweeps that disagree about which end wins. Drawing takes the LATER-linked
-    /// frame on top; the HIT sweep probes the EARLIER-linked frame first and stops there
-    /// (decision 1816). See [`crate::order::hit_test`], and the note on [`WidgetArena`].
+    /// The link position in the `(strata, level)` bucket, re-stamped at the tail on each relink.
+    /// Drawing puts the later-linked frame on top; the hit test probes the earlier-linked first.
     pub insertion_seq: u32,
-    /// Per-kind behavior state (StatusBar value model, …); [`KindState::None`] for plain kinds.
     pub kind_state: KindState,
-    /// Next declaration index handed to a new region of this frame (region draw-order tiebreak).
     next_decl: u32,
 }
 
-/// A region leaf — a texture or fontstring belonging to one frame.
+/// A region leaf: a texture or font string owned by one frame.
 #[derive(Clone, Debug, PartialEq)]
 pub struct Region {
-    /// Texture or fontstring.
     pub kind: RegionKind,
-    /// The frame this region belongs to.
     pub owner: FrameHandle,
-    /// The draw layer within the owner (BACKGROUND..HIGHLIGHT).
     pub draw_layer: DrawLayer,
-    /// `textureSubLevel` — ordering within the draw layer (extension point beyond 1.12; see
-    /// [`crate::order`]).
+    /// A later client's `textureSubLevel`; 1.12 has no sub-level (`0x76a860`).
     pub sub_level: i8,
-    /// Declaration index within the owner frame — the final within-layer draw tiebreak.
+    /// The index within the owner frame, the last within-layer draw tiebreak.
     pub decl_seq: u32,
-    /// `Region:SetParent(nil)` — the region is **orphaned and unrendered, not destroyed** (the
-    /// re-link virtual `0x77fd10` with a null parent unlinks from the old parent's draw layer and
-    /// region list and stores nothing in their place).
-    ///
-    /// Modelled as a flag rather than as an owner-less region: [`Frame::regions`] keeps the entry
-    /// so [`WidgetArena::destroy`] still frees the slab slot, and
-    /// [`crate::order::traversal`] skips it, so it emits no quad. A later
-    /// `SetParent(frame)` clears it and re-links for real
-    /// ([`WidgetArena::set_region_owner`]).
+    /// `Region:SetParent(nil)`: unlinked and not drawn, but not destroyed (`0x77fd10` with a null
+    /// parent). The owner's `regions` keeps it so `destroy` frees it; `SetParent(frame)` relinks.
     pub detached: bool,
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The arena
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The arena ────────────────────────────────────────────────────────────────────────────────
 
-/// The frame arena: the store of all frames and regions, the name registry, and the propagation
-/// mutators.
-///
-/// The **screen root** (`CSimpleTop` / `UIParent`) is *not* a node here — a frame with
-/// `parent == None` is a top-level frame anchored to the always-visible, unit-scale screen root.
-///
-/// **Link-stamp / draw order.** Each frame gets a monotonic `insertion_seq` at creation, used as the
-/// draw-order tiebreak **below the draw layer** within a `(strata, level)` bucket (decision 0884 —
-/// the layer outranks the frame; see [`crate::order`]). Like the client, a frame is re-stamped to
-/// its bucket's **tail** whenever it *becomes visible* (show `0x76ae10` re-ADDS to the intrusive
-/// level list) or a visible frame changes strata/level (both setters remove-then-add). Show order
-/// IS draw order within a bucket — how the reference's late-shown
-/// `MiniMapTrackingFrame` draws over the earlier-declared `MinimapBackdrop` ring despite the XML
-/// declaring it first (decision 0557; the mutators live in [`propagation`]).
-///
-/// The client's own list is a *head* insert walked tail→head, i.e. FIFO by link time with the
-/// newest-linked frame emitted last — order-equivalent to this ascending counter, which is why the
-/// counter stays (0884's §5 refuted the intuition that a head insert draws *first*). A same-value
-/// `SetFrameLevel` early-outs before re-stamping, matching `0x76a4f0`'s `je` at `0x76a509`.
+/// The frame arena: frames, regions, the name registry and the propagation mutators. The screen
+/// root is not a node: a frame with no parent hangs off it. Within a bucket the client's list is a
+/// head insert walked tail to head, the same order as the ascending [`Frame::insertion_seq`].
 pub struct WidgetArena {
     frames: Arena<Frame>,
     regions: Arena<Region>,
@@ -425,30 +239,14 @@ pub struct WidgetArena {
     next_insertion: u32,
     /// The draw list's fingerprint cache ([`crate::order::traversal`]).
     pub(crate) order_cache: crate::order::OrderCache,
-    /// Monotonic count of Minimap-kind frames ever created — an O(1) "a new Minimap widget
-    /// exists" signal, so the per-frame state feed (`set_minimap_inside`'s caller) re-pushes
-    /// exactly when one appears instead of walking every frame to find out.
+    /// Minimap frames ever created, so the state feed notices a new one without a walk.
     minimap_created: u64,
-    /// Frames whose kind carries **engine-side per-tick behavior** — ScrollingMessageFrame /
-    /// MessageFrame (the line fades) and Cooldown (the flash-finished hide). The tick's registry
-    /// (decision 1446, the `minimap_created` disposition at list size): the per-frame advance
-    /// walks these few dozen instead of the whole arena, which it used to do TWICE per tick — a
-    /// corpus UI is thousands of frames. Appended at creation (kinds never change after);
-    /// `destroy` removes its own handle, so the list never carries dead entries.
+    /// The live frames the host ticks (message fades, model scene clocks), so the tick skips the
+    /// rest of the arena. Added at creation, as kinds never change; `destroy` removes its own.
     ticked_kinds: Vec<FrameHandle>,
-    /// Every live **GameTooltip**, same registry shape as [`Self::ticked_kinds`] and for the same
-    /// reason one layer over: three hot paths (the auto-size pre-pass at the top of every layout
-    /// resolve, the per-tick fade advance, and the unit-push hook) all begin "find the tooltips",
-    /// and all three did it by walking the resolve's whole frame roster — ~4000 entries at a
-    /// corpus UI, to reach the two or three that exist. Appended at creation (kinds never change);
-    /// `destroy` removes its own handle, so the list never carries dead entries.
+    /// The live GameTooltips, kept the same way, for the layout pre-pass, fade tick and unit push.
     tooltip_kinds: Vec<FrameHandle>,
-    /// Every live **Minimap**, same registry shape as [`Self::ticked_kinds`] and for the same
-    /// reason: three state feeds (containment, the two zoom indices, and the player-arrow facing)
-    /// all begin "find the Minimaps", and the facing is *per frame*. The ping's own lesson
-    /// (decision 1596) was that a per-widget push must not walk the ~3–4k-frame arena every frame
-    /// to reach the one widget that exists. Appended at creation (kinds never change); `destroy`
-    /// removes its own handle.
+    /// The live Minimaps, kept the same way, for the containment, zoom and arrow-facing feeds.
     minimap_kinds: Vec<FrameHandle>,
 }
 
@@ -458,52 +256,29 @@ impl Default for WidgetArena {
     }
 }
 
-/// Whether a widget of this kind is **mouse-enabled by its constructor**, needing neither an
-/// `enableMouse` attribute nor an auto-enabling `<Scripts>` handler to be clickable.
-///
-/// One list, because there are two readers: this arena, and `benilla-app`'s `frame_flag_gate`
-/// sweep, which compares our frames against a model of the reference's XML. That sweep used to
-/// carry its own copy with a comment claiming it was "deliberately the SAME list" — it was not,
-/// and it drifted silently the first time this one was edited. A wrong entry should be wrong in
-/// one place.
-///
-/// **Read off the client's ctors.** `[frame+0xcc]` is a four-bit input mask — char, keyboard,
-/// MOUSE, wheel — zeroed by the base `CSimpleFrame` ctor `0x769090` and set by exactly five
-/// subclass ctors:
-/// Button `0x778771`, CheckButton (through Button), Slider `0x789467`, ColorSelect `0x78b2b5`,
-/// and EditBox `0x779ced`, which takes char+keyboard+mouse together because it must take a click
-/// to focus. `Minimap` is an engine frame born `0x4` (`0x4edc38`), and ours is a `FrameKind`.
-///
-/// **`ScrollFrame` and `ScrollingMessageFrame` are NOT here, and that was the hard one.** They
-/// were, on the reasoning that a scroll frame "takes the wheel in its ctor" — the wheel is a
-/// different bit, and no ctor writes it at all. Against that stood a recorded observation:
-/// `ChatFrame1` is a `ScrollingMessageFrame`, and something has to make a 1.12 chat link
-/// clickable. The follow-up round settled it: nothing about the frame does. The engine synthesises
-/// one mouse-enabled `CSimpleHyperlinkButton` child PER LINK SPAN (`0x7a3240`, born through the
-/// `CSimpleButton` ctor) and routes the hyperlink scripts back to the parent. We hold spans as
-/// rects rather than child frames, so `script::pointer`'s hit test carries the same law as a
-/// disjunct: the chat window is a candidate over a link and inert everywhere else.
+/// Whether this kind's constructor enables the mouse, so it takes clicks with no `enableMouse`
+/// and no mouse script: the base ctor `0x769090` zeroes the input mask `[frame+0xcc]`, and Button
+/// (`0x778771`, CheckButton through it), Slider (`0x789467`), ColorSelect (`0x78b2b5`), EditBox
+/// (`0x779ced`..`0x779d03`, with char and key) and Minimap (`0x4edc38`) set its mouse bit. The
+/// ScrollFrame and ScrollingMessageFrame ctors set none; a chat link takes clicks through a
+/// mouse-enabled child per span (`0x7a3240`), which `script::pointer` models as rects.
 pub fn mouse_enabled_by_ctor(kind: FrameKind) -> bool {
     matches!(
         kind,
         FrameKind::Button
             | FrameKind::CheckButton
             | FrameKind::EditBox
-            // `CGWorldFrame`'s ctor enables key + mouse + wheel (`0x481b09`/`0x481b14`/`0x481b1f`);
-            // the hit is the world's, not the UI's (decision 1983).
+            // `CGWorldFrame`'s ctor enables key, mouse, wheel (`0x481b09`/`0x481b14`/`0x481b1f`).
             | FrameKind::WorldFrame
-            // A Slider's thumb must be draggable: every scrollbar is a UIPanelScrollBarTemplate
-            // Slider that declares no `enableMouse` yet is draggable in-game (decision 0250).
             | FrameKind::Slider
             | FrameKind::ColorSelect
             | FrameKind::Minimap
-            // `LootButton` extends `CSimpleButton` and inherits its ctor's bit (decision 1799).
+            // `LootButton` extends `CSimpleButton` and inherits its ctor's bit.
             | FrameKind::LootButton
     )
 }
 
 impl WidgetArena {
-    /// A new, empty arena in **1.12 mode** (alpha does not propagate).
     pub fn new() -> WidgetArena {
         WidgetArena {
             frames: Arena::new(),
@@ -518,75 +293,63 @@ impl WidgetArena {
         }
     }
 
-    /// Monotonic count of Minimap widgets ever created (see the field note).
+    /// Minimap frames ever created, a cheap signal that a new one exists.
     pub fn minimap_created(&self) -> u64 {
         self.minimap_created
     }
 
-    /// The frames whose kind the host must advance each tick (see the field note).
+    /// The frames the host advances each tick.
     pub fn ticked_kinds(&self) -> &[FrameHandle] {
         &self.ticked_kinds
     }
 
-    /// The live GameTooltip frames (see the field note).
     pub fn tooltip_kinds(&self) -> &[FrameHandle] {
         &self.tooltip_kinds
     }
 
-    /// The live Minimap frames (see the field note).
     pub fn minimap_kinds(&self) -> &[FrameHandle] {
         &self.minimap_kinds
     }
 
     // ── Read access ────────────────────────────────────────────────────────────────────────────
 
-    /// Borrow a frame, or `None` if the handle is stale/unknown.
     pub fn frame(&self, h: FrameHandle) -> Option<&Frame> {
         self.frames.get(h.index, h.generation)
     }
 
-    /// Mutably borrow a frame. Prefer the dedicated mutators for state that propagates
-    /// (shown/strata/level/scale/alpha/parent) — direct edits bypass propagation.
+    /// Direct edits skip propagation: shown, strata, level, scale, alpha and parent go through
+    /// the mutators.
     pub fn frame_mut(&mut self, h: FrameHandle) -> Option<&mut Frame> {
         self.frames.get_mut(h.index, h.generation)
     }
 
-    /// Borrow a region, or `None` if the handle is stale/unknown.
     pub fn region(&self, h: RegionHandle) -> Option<&Region> {
         self.regions.get(h.index, h.generation)
     }
 
-    /// Mutably borrow a region.
     pub fn region_mut(&mut self, h: RegionHandle) -> Option<&mut Region> {
         self.regions.get_mut(h.index, h.generation)
     }
 
-    /// Iterate every live frame as `(handle, &Frame)` (arena order — [`crate::order::traversal`]
-    /// sorts into draw order).
+    /// Every live frame, in arena order, not draw order.
     pub fn iter_frames(&self) -> impl Iterator<Item = (FrameHandle, &Frame)> + '_ {
         self.frames
             .iter()
             .map(|(index, generation, f)| (FrameHandle { index, generation }, f))
     }
 
-    /// Iterate every live frame as `(handle, &mut Frame)` — for per-kind state the host advances each
-    /// tick (the ScrollingMessageFrame fade). Structural fields stay the arena's to mutate through its
-    /// propagation setters; this is for [`Frame::kind_state`] only.
+    /// Every live frame, mutably, for [`Frame::kind_state`].
     pub fn iter_frames_mut(&mut self) -> impl Iterator<Item = (FrameHandle, &mut Frame)> + '_ {
         self.frames
             .iter_mut()
             .map(|(index, generation, f)| (FrameHandle { index, generation }, f))
     }
 
-    /// Move `h` to the **tail** of its `(strata, level)` draw bucket — the client's own live-list
-    /// maintenance: show `0x76ae10` re-ADDS a frame to its level's intrusive list on the
-    /// hidden→visible transition, and `set_frame_strata 0x76a470` /
-    /// `set_frame_level 0x76a4f0` remove-then-add a visible frame — an intrusive-list add appends.
-    /// Called by the [`propagation`] mutators on exactly those transitions (module doc).
+    /// Move `h` to its bucket's tail, as the client's level-list add does: show `0x76ae10` on
+    /// becoming visible, and strata `0x76a470` or level `0x76a4f0` on a visible frame.
     pub(crate) fn resequence_to_tail(&mut self, h: FrameHandle) {
-        // The seq lives in an 18-bit field of the packed `ZKey`; unbounded show-bumping could
-        // exhaust it over a marathon session, so at the cap renumber every frame in its current
-        // order (order-preserving, so no visible change) instead of tripping ZKey's assert.
+        // The stamp is `INSERTION_BITS` wide in the packed `ZKey`: at the cap, renumber every
+        // frame in its current order, which changes no draw order.
         if self.next_insertion >= (1 << crate::order::INSERTION_BITS) {
             let mut order: Vec<FrameHandle> =
                 self.iter_frames().map(|(handle, _)| handle).collect();
@@ -605,31 +368,21 @@ impl WidgetArena {
         }
     }
 
-    /// Resolve a name to the frame that published it, or `None`. Publishing is **non-overwriting**:
-    /// the first frame created with a given name owns it; a later duplicate keeps its own `name`
-    /// field but does not become the lookup target (matching the client's auto-publish rule,
-    /// `0x701bd0`; decision 0068).
+    /// The first frame created with `name`; a later duplicate never takes it over (`0x701bd0`).
     pub fn lookup(&self, name: &str) -> Option<FrameHandle> {
         self.names.get(name).copied()
     }
 
     // ── Create / destroy ────────────────────────────────────────────────────────────────────────
 
-    /// Create a frame of `kind`, with an optional `name` and `parent`. A `parent` handle that is not
-    /// live is treated as `None` (top-level). The new frame starts `shown`, strata MEDIUM, level 0,
-    /// scale 1.0, alpha 1.0; its `effective_visible`/`effective_scale`/`effective_alpha` are computed
-    /// from the parent immediately. If `name` is given and not already published, it is published.
-    ///
-    /// (Strata/level inheritance from the parent at create time is a *loader/CreateFrame* concern,
-    /// not the ctor's — the client's ctor `0x769090` writes MEDIUM/0 unconditionally; we match that
-    /// and leave inheritance to the layer above.)
+    /// Create a frame as the client's ctor `0x769090` does, whatever the parent: shown, MEDIUM,
+    /// level 0, scale and alpha 1.0. A dead `parent` makes a top-level frame.
     pub fn create(
         &mut self,
         kind: FrameKind,
         name: Option<String>,
         parent: Option<FrameHandle>,
     ) -> FrameHandle {
-        // Only keep a parent that is actually live.
         let parent = parent.filter(|&p| self.frame(p).is_some());
         let parent_visible = parent.is_none_or(|p| self.frame(p).unwrap().effective_visible);
         let parent_scale = parent.map_or(1.0, |p| self.frame(p).unwrap().effective_scale);
@@ -639,8 +392,7 @@ impl WidgetArena {
 
         let shown = true;
         let scale = 1.0f32;
-        // Alpha starts at 1.0 regardless of the parent's — creation does not re-push a dimmed
-        // parent's value (only SetAlpha cascades; module alpha section).
+        // 1.0 whatever the parent's: only `SetAlpha` pushes alpha down the tree.
         let alpha = 1.0f32;
         let effective_alpha = alpha;
 
@@ -652,8 +404,7 @@ impl WidgetArena {
             children: Vec::new(),
             regions: Vec::new(),
             title_region: None,
-            // The WorldFrame's constructor is the one writer of stratum 0 (`WORLD`, below
-            // `BACKGROUND`); every other kind starts at the base ctor's MEDIUM (1984).
+            // The WorldFrame ctor alone writes stratum 0, WORLD; the rest start MEDIUM.
             strata: if kind == FrameKind::WorldFrame {
                 Strata::World
             } else {
@@ -665,32 +416,19 @@ impl WidgetArena {
             shown,
             effective_visible: shown && parent_visible,
             mouse_enabled: mouse_enabled_by_ctor(kind),
-            // The two kinds whose ctor takes the WHEEL rather than the mouse generally — the same
-            // by-construction argument as above, narrowed to the flag it is actually about
-            // (decision 1198): a ScrollingMessageFrame and a ScrollFrame are wheel-interactive
-            // with no attribute, and nothing else is.
+            // The WorldFrame ctor takes the wheel (`0x481b1f`); the reference's ScrollFrame and
+            // ScrollingMessageFrame ctors do not, and a stock one takes it from `<OnMouseWheel>`.
             mouse_wheel_enabled: matches!(
                 kind,
                 FrameKind::ScrollingMessageFrame | FrameKind::ScrollFrame | FrameKind::WorldFrame
             ),
-            // Nothing is keyboard-enabled by construction: `0x76af00` is only ever reached from the
-            // XML attribute or an explicit call, never a ctor.
+            // No kind is keyboard-enabled at creation here; the reference's EditBox
+            // (`0x779ced`/`0x779cf8`) and WorldFrame (`0x481b09`) ctors enable key input.
             keyboard_enabled: false,
-            // A tooltip clamps to the screen by construction (its XML never sets the attribute,
-            // yet the reference plate observably never leaves the window — the class supplies
-            // geometry flags bit4; decision 0352's law: no tooltip off-screen, ever).
             clamped_to_screen: matches!(kind, FrameKind::GameTooltip),
-            // No frame is born with an inset hit rect — `<HitRectInsets>`/SetHitRectInsets is the
-            // only source (the client's ctor zeroes the four floats too).
             hit_rect_insets: [0.0; 4],
-            // No kind is born movable/resizable/user-placed/toplevel: every one of the four is
-            // opt-in from XML or a script, and a frame nobody opted in stays where its anchors put
-            // it, at the level it was created with.
             movable: false,
             resizable: false,
-            // All four zeroed, which IS the client's unbounded state — `CLayoutFrame`'s ctor
-            // `0x767680` does exactly this (`xor esi,esi` into `+0x5c..+0x68`), and `0.0` is the
-            // sentinel the clamp tests rather than a separate flag.
             min_resize: (0.0, 0.0),
             max_resize: (0.0, 0.0),
             user_placed: false,
@@ -702,8 +440,8 @@ impl WidgetArena {
             insertion_seq,
             kind_state: match kind {
                 FrameKind::StatusBar => KindState::StatusBar(StatusBarState::default()),
-                // `CLootButton` and `CSimpleCheckbox` both extend `CSimpleButton` and both add
-                // exactly one field, which `ButtonState` carries for them (`loot_slot`/`checked`).
+                // `CLootButton` and `CSimpleCheckbox` extend `CSimpleButton` by one field each,
+                // which `ButtonState` carries (`loot_slot`, `checked`).
                 FrameKind::Button | FrameKind::CheckButton | FrameKind::LootButton => {
                     KindState::Button(ButtonState::default())
                 }
@@ -717,9 +455,8 @@ impl WidgetArena {
                 FrameKind::ColorSelect => {
                     KindState::ColorSelect(kinds::ColorSelectState::default())
                 }
-                // Both model panes share one state: `CGCharacterModelBase` EXTENDS `CSimpleModel`,
-                // so a `<PlayerModel>` carries every `CSimpleModel` member and adds only the
-                // turn-animation pair we do not model (`ModelState`'s doc).
+                // `CGCharacterModelBase` extends `CSimpleModel`, adding only a turn-animation pair,
+                // which is not modelled.
                 FrameKind::Model
                 | FrameKind::PlayerModel
                 | FrameKind::DressUpModel
@@ -734,8 +471,6 @@ impl WidgetArena {
         if matches!(kind, FrameKind::Minimap) {
             self.minimap_created += 1;
         }
-        // The model panes ride the same registry: their scene clock advances per tick and their
-        // completion edge is read there (decision 2007).
         let ticked = matches!(
             kind,
             FrameKind::ScrollingMessageFrame
@@ -760,7 +495,6 @@ impl WidgetArena {
                 .push(handle);
         }
         if let Some(n) = name {
-            // Non-overwriting: first writer wins.
             self.names.entry(n).or_insert(handle);
         }
         if matches!(kind, FrameKind::EditBox) {
@@ -768,46 +502,21 @@ impl WidgetArena {
         }
         if matches!(kind, FrameKind::Minimap) {
             self.minimap_kinds.push(handle);
-            // The `CMinimap` ctor's own last act, so no observer ever sees a Minimap without its
-            // nine (see [`MINIMAP_ENGINE_CHILDREN`]). It sits here rather than in the loader
-            // because the client builds them in the *element factory* — `CreateFrame("Minimap")`
-            // from Lua gets them too, and gets them before its OnLoad runs.
+            // The `CMinimap` ctor's last act, so a `CreateFrame("Minimap")` has its nine children
+            // before its `OnLoad` too.
             self.build_minimap_engine_children(handle);
         }
         handle
     }
 
-    /// Build the **five engine-owned regions of a fresh EditBox**, in the ctor's own order — the
-    /// same posture as [`Self::build_minimap_engine_children`] below, and for the same reason: the
-    /// client builds them in `CSimpleEditBox`'s ctor, so a `CreateFrame("EditBox")` with no XML
-    /// behind it has them too, before its OnLoad runs.
-    ///
-    /// All five, byte-verified:
-    ///
-    /// | # | region | ctor site | built by |
-    /// |---|---|---|---|
-    /// | 1 | text FontString `E+0x328` | `0x779bee` | `0x770d30(E, 2, 1)` |
-    /// | 2-4 | selection-highlight quads `E+0x350/0x354/0x358` | `0x779c41`–`0x779c72` | `0x76fc40(E, 2, 0)` |
-    /// | 5 | caret `E+0x368` | `0x779c86`–`0x779cac` | `0x76fc40(E, 3, 1)` |
-    ///
-    /// **Why the ORDER is the whole point.** `GetRegions 0x773f60` walks `[frame+0x1b8]` — one flat
-    /// creation-ordered list, oldest first, with **no filter** (hidden regions are returned and
-    /// counted), and insertion is at the TAIL. All five reach
-    /// that list through `0x77fd10`, the single linker. So on a real client the authored `<Layers>`
-    /// regions start at index **6**, and an addon may index them there.
-    ///
-    /// pfUI's `skins/blizzard/friends.lua` l.379 is the report:
-    /// `local _,_,_,_,_,left,right = GuildControlPopupFrameEditBox:GetRegions()` — it skips five and
-    /// takes the box's two `UI-ChatInputBorder` textures. Before this, benilla returned only the
-    /// authored regions, so `left` was nil and the whole guild-control skin died on it.
-    ///
-    /// The four quads are created blank — no texture, no fill — so they emit nothing; benilla's
-    /// caret and selection highlight are still painted host-side. That gap is named on the
-    /// [`EditBoxState`](kinds::EditBoxState) fields rather than papered over.
+    /// Build the five regions the `CSimpleEditBox` ctor gives every EditBox, in its order: the
+    /// text FontString `E+0x328` (`0x779bee`, `0x770d30(E, 2, 1)`), three selection quads
+    /// `E+0x350/0x354/0x358` (`0x779c41`..`0x779c72`, `0x76fc40(E, 2, 0)`) and the caret
+    /// `E+0x368` (`0x779c86`..`0x779cac`, `0x76fc40(E, 3, 1)`). `GetRegions` (`0x773f60`) lists
+    /// them first, hidden or not, so authored `<Layers>` regions start at index 6. The quads carry
+    /// no texture: caret and selection paint host-side.
     fn build_editbox_engine_regions(&mut self, eb: FrameHandle) {
-        // The text region keeps the OVERLAY/0 layer it has always shipped with; the ctor's own
-        // 2/1 is recorded on the field and deferred there (a draw-order change to every EditBox
-        // is not a rider on a region-list fix).
+        // OVERLAY here; the reference ctor puts the text in layer 2, ARTWORK (`0x770d30(E, 2, 1)`).
         let text = self.create_region(eb, RegionKind::FontString, DrawLayer::Overlay, 0);
         let mut selection = [None; 3];
         for slot in &mut selection {
@@ -821,11 +530,8 @@ impl WidgetArena {
         }
     }
 
-    /// Build the nine engine-owned `Model` children of a fresh Minimap and remember the ninth as
-    /// its player arrow. They are created **anonymous and file-less**: the ctor only constructs
-    /// them, and the model paths are `CMinimap::LoadXML 0x4ee2b0`'s to assign from the two
-    /// attributes (the loader's minimap pass) — which is why a `CreateFrame("Minimap")` with no XML
-    /// behind it has nine blank Models here, exactly as the reference does.
+    /// Build a Minimap's nine engine `Model` children, the ninth its player arrow. They are born
+    /// anonymous and without a model file; `CMinimap::LoadXML` (`0x4ee2b0`) assigns the paths.
     fn build_minimap_engine_children(&mut self, minimap: FrameHandle) {
         let mut ninth = None;
         for _ in 0..kinds::MINIMAP_ENGINE_CHILDREN {
@@ -836,8 +542,7 @@ impl WidgetArena {
         }
     }
 
-    /// Destroy a frame and its whole subtree (child frames and all regions), unpublishing any names
-    /// it owns and detaching it from its parent's child list. Stale handles are ignored.
+    /// Destroy a frame and its subtree, with their regions and the names they own.
     pub fn destroy(&mut self, h: FrameHandle) {
         let Some(frame) = self.frame(h) else {
             return;
@@ -846,7 +551,7 @@ impl WidgetArena {
         let regions = frame.regions.clone();
         let parent = frame.parent;
         let name = frame.name.clone();
-        // Each (recursive) destroy removes its own handle — the tick registry stays dead-free.
+        // Each recursive call removes its own handle, so the registries hold no dead frame.
         self.ticked_kinds.retain(|&t| t != h);
         self.tooltip_kinds.retain(|&t| t != h);
         self.minimap_kinds.retain(|&t| t != h);
@@ -870,7 +575,6 @@ impl WidgetArena {
         self.frames.remove(h.index, h.generation);
     }
 
-    /// Create a region leaf owned by `owner`. Returns `None` if `owner` is stale.
     pub fn create_region(
         &mut self,
         owner: FrameHandle,
@@ -900,23 +604,9 @@ impl WidgetArena {
         Some(handle)
     }
 
-    /// **Free one region leaf** — unlink it from its owner's region list and release the slab slot,
-    /// so the handle stops resolving and the region stops drawing. Returns whether it was live.
-    ///
-    /// There is no `Region:Destroy` in the widget API and none is wanted: this exists for the one
-    /// engine-owned lifetime in the client, `CSimpleHTML::SetText`, which pool-frees the blocks of
-    /// the previous parse before building the new ones (the pool allocate at `0x78adc6` has a
-    /// matching free, and the CONTENTNODE list at `+0x340` is what names the objects to free).
-    /// Without it a second `SetText` leaves the first parse's
-    /// FontStrings on screen, stacked behind the new ones.
-    ///
-    /// **The caller owns the rest of the region's identity.** The arena holds only structure;
-    /// paint (`RegionData`), the stable id maps, the resolved-rect cache and any name publish live
-    /// on the script model, and a caller that frees a region without dropping those leaves a
-    /// resolvable id pointing at a dead handle. [`crate::script`]'s SimpleHTML block teardown is
-    /// the one caller and does the whole set. For the same reason this must never be pointed at a
-    /// region some *state* still holds by handle (a button's texture slot, a tooltip line, an
-    /// EditBox's text region): freeing those would leave that state dangling.
+    /// Free one region, as only `CSimpleHTML::SetText` does in the client, pool-freeing the last
+    /// parse's blocks (`0x78adc6`). The caller drops the region's script-model state too, and never
+    /// frees a region some state holds by handle.
     pub fn destroy_region(&mut self, h: RegionHandle) -> bool {
         let Some(region) = self.region(h) else {
             return false;
@@ -932,8 +622,6 @@ impl WidgetArena {
     }
 }
 
-// The propagation mutators (visibility/strata/level/scale/alpha/reparenting) — split out for size;
-// see `propagation`'s module doc.
 mod propagation;
 
 #[cfg(test)]
diff --git a/crates/benilla-ui/src/widget/propagation.rs b/crates/benilla-ui/src/widget/propagation.rs
index 859da493..9ac43f9a 100644
--- a/crates/benilla-ui/src/widget/propagation.rs
+++ b/crates/benilla-ui/src/widget/propagation.rs
@@ -1,32 +1,17 @@
-//! [`WidgetArena`]'s propagation mutators — the binary-verified subtree math that keeps
-//! `effective_visible`/`strata`/`level`/`effective_scale`/`effective_alpha` (and reparenting, which
-//! touches several of those at once) consistent whenever a frame's own state changes. Split out of
-//! [`super`] because this is the module's dense, ground-truth-heavy core (see the module doc's
-//! "Ground truth" section); the arena's storage/create/destroy/read-access lives with the struct
-//! definition in [`super`].
+//! [`WidgetArena`]'s mutators: propagation down the subtree, reparenting and the frame flags.
 
 use crate::order::Strata;
 
 use super::{FrameHandle, RegionHandle, WidgetArena, SCALE_EPS};
 
 impl WidgetArena {
-    // ── Visibility (effective_visible_show/_hide) ────────────────────────────────────────────────
+    // ── Visibility ───────────────────────────────────────────────────────────────────────────────
 
-    /// Set a frame's own `shown` bit and propagate effective visibility through its subtree, after
-    /// show `0x76ae10` / hide `0x76ad50`. Returns, in pre-order (a node before its descendants),
-    /// **every frame whose `effective_visible` actually changed** — the caller fires
-    /// `OnShow`/`OnHide` for those, in order.
-    ///
-    /// **Two recorded deviations from `0x76ae10`, both in this signature** (decision 2317). The
-    /// reference is **post-order** — it marks itself visible, recurses into its children, and fires
-    /// its own notify last (`0x76aef5`, past both child loops) — so descendants are notified before
-    /// ancestors. And it keeps **no snapshot**: each loop re-reads the live links after every
-    /// per-node call, so a frame hidden by a handler mid-cascade refuses at its own gate
-    /// (`0x76ae1d`) and is never notified, where the list returned here already holds it. The
-    /// auction window exercises exactly that case and lands on the same state by the other road;
-    /// 2317 has the measurements and the risk for whoever changes this. A no-op `shown` write, or
-    /// a change that does not move any effective visibility (e.g. hiding an already-invisible frame),
-    /// returns empty.
+    /// Set `shown` and propagate effective visibility down the subtree (show `0x76ae10`, hide
+    /// `0x76ad50`), returning the frames that changed, a node before its descendants, for the
+    /// caller to fire `OnShow`/`OnHide`. The reference notifies post-order (`0x76aef5`) and
+    /// re-reads live links, so a frame a handler hides mid-cascade fails its gate (`0x76ae1d`) and
+    /// is never notified; this list is a snapshot that still holds it.
     pub fn set_shown(&mut self, h: FrameHandle, shown: bool) -> Vec<FrameHandle> {
         let mut changed = Vec::new();
         match self.frame_mut(h) {
@@ -50,17 +35,12 @@ impl WidgetArena {
         };
         let new_ev = shown && parent_visible;
         if new_ev == old_ev {
-            // Transition-gated: no change here ⇒ no change below (children's parent-visibility and
-            // own shown are unchanged). Prune, exactly like the client's recursion.
+            // No change here means none below: prune, as the client's recursion does.
             return;
         }
         self.frame_mut(h).unwrap().effective_visible = new_ev;
         if new_ev {
-            // The client re-ADDS the frame to its (strata, level) bucket on this transition —
-            // an intrusive-list append, so a newly shown frame draws over everything already in
-            // its bucket ([`WidgetArena::resequence_to_tail`]). Pre-order recursion gives the
-            // descendants later seqs than the node, exactly like the client's recursion re-adding
-            // each as its own effectiveVisible flips.
+            // Re-added at its bucket's tail, as the client does, and each descendant after it.
             self.resequence_to_tail(h);
         }
         changed.push(h);
@@ -69,14 +49,10 @@ impl WidgetArena {
         }
     }
 
-    // ── Strata (set_frame_strata) ────────────────────────────────────────────────────────────────
+    // ── Strata ───────────────────────────────────────────────────────────────────────────────────
 
-    /// Force `h` and its **whole subtree** to `strata`, per `set_frame_strata 0x76a470`: set the
-    /// frame's strata, then recursively set every child frame to the same value. The client's
-    /// visible-gated bucket remove/add (its live draw-list maintenance) is mirrored by
-    /// re-sequencing a visible frame to its new bucket's tail
-    /// ([`WidgetArena::resequence_to_tail`]); [`crate::order::traversal`] recomputes the buckets
-    /// from the fields.
+    /// Force `h` and its whole subtree to `strata` (`0x76a470`), moving each visible frame to the
+    /// tail of its new bucket.
     pub fn set_frame_strata(&mut self, h: FrameHandle, strata: Strata) {
         let (visible, children) = match self.frame_mut(h) {
             Some(f) => {
@@ -96,13 +72,10 @@ impl WidgetArena {
         }
     }
 
-    // ── Level (set_frame_level) ──────────────────────────────────────────────────────────────────
+    // ── Level ────────────────────────────────────────────────────────────────────────────────────
 
-    /// Set `h`'s level. When `propagate`, **same-strata** child frames shift by the same delta
-    /// (relative offsets preserved); cross-strata children are untouched — per `set_frame_level
-    /// 0x76a4f0`. Level is unsigned here, so the client's `if (level < 0) level =
-    /// 0` clamp is subsumed by the type (a Lua binding saturates on conversion); a propagated shift
-    /// that would go negative saturates to 0, and an overflow saturates to `u16::MAX`.
+    /// Set `h`'s level (`0x76a4f0`); with `propagate`, same-strata children shift by the same
+    /// delta. A same-value call returns before relinking (`0x76a509`).
     pub fn set_frame_level(&mut self, h: FrameHandle, level: u16, propagate: bool) {
         let (delta, strata, children) = match self.frame_mut(h) {
             Some(f) => {
@@ -115,8 +88,7 @@ impl WidgetArena {
             }
             None => return,
         };
-        // The client's visible-gated remove/add: a visible frame lands at its NEW bucket's tail
-        // (a hidden one is in no bucket — it appends on its next show anyway).
+        // Only a visible frame relinks (`0x76a541`); a hidden one is in no bucket.
         if self.frame(h).is_some_and(|f| f.effective_visible) {
             self.resequence_to_tail(h);
         }
@@ -128,62 +100,21 @@ impl WidgetArena {
                 Some(cf) if cf.strata == strata => {
                     (i32::from(cf.level) + delta).clamp(0, i32::from(u16::MAX)) as u16
                 }
-                _ => continue, // cross-strata (or stale) child: untouched
+                _ => continue, // cross-strata or stale: untouched
             };
             self.set_frame_level(c, child_new, true);
         }
     }
 
-    /// Squeeze the free levels out of `strata` and return the level counter — level compaction
-    /// (`0x764eb0`), the step `CSimpleTop::Raise 0x7650f0` runs immediately before it sets the
-    /// raised frame's level to `bucket->count(+0x8)`.
+    /// Level compaction (`0x764eb0`), run by `CSimpleTop::Raise` (`0x7650f0`) before it sets the
+    /// raised frame's level to the returned count: renumber the occupied levels of `strata` in
+    /// order, hidden frames included (the scan tests only strata and level, `0x764f18`/`0x764f20`),
+    /// without propagating (`0x764faf`). `level` is written directly, so `insertion_seq` survives
+    /// where the reference re-levels through `0x76a4f0` (`0x764fb6`) and relinks visible frames.
     ///
-    /// **EVERY frame of the stratum is renumbered — hidden ones included, and that is the byte
-    /// law, not a benilla choice** (decision 2104). `0x764eb0`'s occupancy test is a two-part OR: a
-    /// level node's own list, else a scan of the client's **master frame list** (`[root+0xcc4]`,
-    /// link offset `0x304` — every live frame, joined in the `CSimpleFrame` ctor and counted by
-    /// `GetNumFrames`), and that scan filters on exactly two fields — `+0xc0` strata (`0x764f18`)
-    /// and `+0xc4` level (`0x764f20`). The renumber pass `0x764f80..0x764fc9` walks the same list.
-    /// A census of `+0xd4` (effectiveVisible) over the whole body `[0x764eb0, 0x76500e)` finds
-    /// **zero** hits; in `set_frame_level 0x76a4f0` the `+0xc4` write is unconditional
-    /// (`0x76a53b`) and `+0xd4` gates only the bucket relink below it (`0x76a541`).
-    ///
-    /// Gating the renumber on visibility — which benilla did, reasoning from the level lists rather
-    /// than from the bytes — is not a relabelling at all: it changes the relative order of the part
-    /// it touches against the part it does not, and that difference then rides out on the raise's
-    /// `propagate` delta, which is computed in the *new* numbering and applied to levels still
-    /// carrying the *old* one. One level of squeeze taken out of a visible child and not out of its
-    /// hidden sibling becomes a permanent inversion between two frames that are level by
-    /// construction — `parent.level + 1` for both. Gatherer's Report window is the shape that found
-    /// it: the window's visible Close button and its hidden, mouse-enabled, full-cover body are both
-    /// direct children, the body was hidden for the Show raise, and it came out one level above the
-    /// button and ate every click and hover the button should have had. The reference lands that
-    /// pair equal, and the hit sweep's tie then goes to the earlier-linked frame, the button (1816).
-    ///
-    /// So the visible gate stays where it belongs — on the *link list* (`resequence_to_tail`, draw
-    /// participation) — and off the *numbering*, which is a property of the frame.
-    ///
-    /// **The renumber is strictly order-preserving, so by itself it changes no draw order**: distinct
-    /// levels map to distinct indices monotonically and equal levels stay equal. Its whole job is to
-    /// keep the raise target *bounded* — without it, `level := max + 1` would ratchet upward one step
-    /// per raise for as long as the session lasts.
-    ///
-    /// **Ours packs tighter than the binary's, deliberately.** `bucket+0x8` is a high-water *bound*,
-    /// not a count of occupied levels, and `0x764eb0`'s cursor resumes at its saved pre-gap index
-    /// while that bound shrinks under it (`0x764fd3`/`0x764fd8`), so a wide gap carries an interior
-    /// hole past it: occupied `{0, 4, 6}` at count 7 comes out `{0, 1, 3}` at count 4, not
-    /// `{0, 1, 2}` at 3. That artifact is invisible to draw and hit order — both maps are monotone
-    /// and injective on levels, and both keep the invariant the raise needs (`count` above every
-    /// occupied level) — so we take the contiguous one rather than model a cursor bug.
-    ///
-    /// Two things it deliberately is **not**: it does not propagate (`0x764faf` passes
-    /// `propagate = 0`, so a parent/child level *offset* is not preserved across a hole either —
-    /// parent 5 / child 7 comes out adjacent), and **it does not relink**, which is a known
-    /// divergence: the binary re-levels each moved frame through `0x76a4f0` at `0x764fb6`, so every
-    /// moved *visible* frame is unlinked and re-inserted and its within-level link order is
-    /// rewritten (a hidden frame takes no list churn). We write `level` directly instead, so our
-    /// `insertion_seq` survives a compaction untouched. Nothing observed yet turns on it; it is
-    /// named in 2104 rather than changed under a bug fix.
+    /// Deviation: levels pack contiguously, because the reference's resuming cursor
+    /// (`0x764fd3`/`0x764fd8`) leaves a hole past a wide gap ({0, 4, 6} at count 7 gives {0, 1, 3}
+    /// at count 4) that no draw or hit order can see.
     pub fn compact_levels(&mut self, strata: Strata) -> u16 {
         let mut occupied: Vec<u16> = self
             .iter_frames()
@@ -208,28 +139,23 @@ impl WidgetArena {
         occupied.len() as u16
     }
 
-    // ── The toplevel flag (flag word bit 0x1) ────────────────────────────────────────────────────
+    // ── Toplevel ─────────────────────────────────────────────────────────────────────────────────
 
-    /// Set a frame's `toplevel` bit — `SetToplevel 0x775440` / XML `toplevel`, both through the pure
-    /// bit-setter `0x76a3c0` (see [`Frame::toplevel`]). A pure flag write: **it raises nothing**.
-    /// A stale handle is a no-op.
+    /// `SetToplevel` (`0x775440`) via the bit-setter `0x76a3c0`: a flag write that raises nothing.
     pub fn set_toplevel(&mut self, h: FrameHandle, toplevel: bool) {
         if let Some(f) = self.frame_mut(h) {
             f.toplevel = toplevel;
         }
     }
 
-    /// Whether the frame carries the `toplevel` bit (`IsToplevel`). A stale handle reads as `false`.
     pub fn is_toplevel(&self, h: FrameHandle) -> bool {
         self.frame(h).is_some_and(|f| f.toplevel)
     }
 
     // ── Scale ────────────────────────────────────────────────────────────────────────────────────
 
-    /// Set `h`'s own scale and recompute effective scale down the subtree, ε-gated, per
-    /// `0x76ac90`: `effectiveScale = parentScale * ownScale`; a
-    /// node whose new effective scale is within [`SCALE_EPS`] of its current one is skipped along
-    /// with its subtree (its children's parent-scale did not move).
+    /// Set `h`'s own scale and recompute `effective_scale = parent's * own` down the subtree
+    /// (`0x76ac90`), stopping at a frame whose value moves less than [`SCALE_EPS`].
     pub fn set_scale(&mut self, h: FrameHandle, scale: f32) {
         if let Some(f) = self.frame_mut(h) {
             f.scale = scale;
@@ -262,11 +188,8 @@ impl WidgetArena {
 
     // ── Alpha ────────────────────────────────────────────────────────────────────────────────────
 
-    /// Set `h`'s alpha and **overwrite every descendant frame's** with the same raw value — the
-    /// 1.12 mechanism (`SetAlpha 0x76a690` writes `[this+0xc8]` then recurses the child-frame list
-    /// pushing the SAME value). An eager set-time flatten, structurally the strata subtree-force —
-    /// never a draw-time ancestor product, so `effective_alpha` (what a renderer's one-hop region
-    /// composition reads) always equals `alpha`.
+    /// `SetAlpha` (`0x76a690`): write the raw value to `h` and every descendant frame (`+0xc8`),
+    /// with no draw-time product, so a child's own later `SetAlpha` holds until an ancestor's next.
     pub fn set_alpha(&mut self, h: FrameHandle, alpha: f32) {
         let Some(f) = self.frame_mut(h) else { return };
         f.alpha = alpha;
@@ -277,31 +200,21 @@ impl WidgetArena {
         }
     }
 
-    // ── Reparenting (reparent_begin / reparent_finish) ───────────────────────────────────────────
+    // ── Reparenting ──────────────────────────────────────────────────────────────────────────────
 
-    /// The runtime reparent, phase 1 of 2 — the guards and the **hide half** of
-    /// `CSimpleFrame::SetParent 0x76ab10`'s sequence (decision 1323, which corrects this
-    /// module's previous "strata/level are NOT changed by reparenting" — refuted at `0x76ab65`).
+    /// Phase 1 of `SetParent` (`0x76ab10`): the guards and the hide half. `None` when the parent
+    /// is unchanged (`0x76ab20` skips everything), the frame is dead, or the move would cycle (the
+    /// Lua binding raises first, `0x7a177f`); otherwise the frames that lost effective visibility,
+    /// in pre-order, whose `OnHide` runs under the old parent (`0x76ab41`).
     ///
-    /// Returns `None` for the byte-verified TOTAL no-op — `newParent == currentParent` (`0x76ab20`
-    /// skips *everything*) — and for a dead handle or a cycle (the Lua binding raises on a cycle
-    /// *before* calling here, per the binding's own inline `+0x9c` walk at `0x7a177f`; a direct
-    /// caller gets the silent reject as a backstop). Otherwise `Some(hidden)`: every frame whose
-    /// effective visibility just dropped, in pre-order — empty when the frame was not effectively
-    /// visible ("a reparent of a hidden frame fires neither" event). The caller fires `OnHide` for
-    /// those and then calls [`Self::reparent_finish`]; the hide runs while the frame still hangs
-    /// under its OLD parent, as the reference's `0x76ab41` does before the `+0x9c` store, so an
-    /// `OnHide` handler observes the old parent. (One knowing divergence: the reference unlinks
-    /// from the old parent's child list *before* the hide, so an `OnHide` calling
-    /// `oldParent:GetChildren()` no longer sees the frame there; ours still does — the relink is
-    /// phase 2's, so a handler that itself reparents can't leave the lists half-spliced.)
+    /// Deviation: the frame is still in the old parent's child list during `OnHide`, unlike the
+    /// reference, because a handler that itself reparents must not find the lists half-spliced.
     pub fn reparent_begin(
         &mut self,
         h: FrameHandle,
         new_parent: Option<FrameHandle>,
     ) -> Option<Vec<FrameHandle>> {
         self.frame(h)?;
-        // Keep only a live new parent; reject a cycle (new_parent == h or below h).
         let new_parent = new_parent.filter(|&p| self.frame(p).is_some());
         if let Some(np) = new_parent {
             if np == h || self.is_ancestor(h, np) {
@@ -318,32 +231,13 @@ impl WidgetArena {
         Some(hidden)
     }
 
-    /// Phase 2 — the relink and the rest of `0x76ab10`'s verified sequence: **strata := parent's**
-    /// (`0x76ab5a` → the value-gated subtree force of [`Self::set_frame_strata`]; MEDIUM for nil),
-    /// **level := parent.level + 1 with `propagate = 0`** (`0x76ab65`; 0 for nil), scale
-    /// re-inherit, then the **show half**. Returns the frames whose effective visibility came back
-    /// (fire `OnShow` for those, in order).
-    ///
-    /// Load-bearing consequences:
-    ///
-    /// - **Existing children keep their absolute levels** (`propagate = 0`; level compaction
-    ///   `0x764eb0`'s one caller is the toplevel Raise, unreachable from here). A child created
-    ///   when the parent sat lower can land BELOW its own parent — the client ships that and
-    ///   nothing repairs it but the child's own `SetFrameLevel` (which is exactly what AtlasLoot's
-    ///   button templates do in `OnShow`, and why its browse panel works on the reference).
-    /// - **The show half is gated on `was_visible`** (`0x76abfd`: `ebx && (parent==0 ||
-    ///   parent->+0xd4)`) — the `+0xd4` cascade only runs inside `0x76ae10`, so a reparent of a
-    ///   hidden (or hidden-chained) frame does NOT recompute effective visibility: moved under a
-    ///   visible parent it stays effectively invisible until something shows it. That staleness is
-    ///   the shipped behaviour, not an oversight to "fix" here.
-    /// - The `OnShow` refire down the re-shown subtree is what lets an addon hand-repair the
-    ///   propagate-0 level law (`this:SetFrameLevel(GetParent():GetFrameLevel()+1)` in `OnShow` —
-    ///   the reference fires it via the `+0x84`/`+0x88` hide→show round-trip on any visible
-    ///   reparent).
-    ///
-    /// `was_visible` is phase 1's `!hidden.is_empty()` — the reference's `ebx`, captured at
-    /// `0x76ab2b` before anything runs. Alpha stays untouched throughout: the client only pushes
-    /// alpha at `SetAlpha` time (module alpha section).
+    /// Phase 2 of `SetParent` (`0x76ab10`): relink, strata := the parent's (`0x76ab5a`, MEDIUM for
+    /// none), level := the parent's + 1 without propagating (`0x76ab65`, 0 for none), scale
+    /// re-inherited, then the show half, returning the frames that became visible; alpha is
+    /// untouched. `h`'s own children keep their levels, so one can end up below `h`.
+    /// `was_visible` is whether phase 1 hid anything (the reference's `ebx` at `0x76ab2b`); the
+    /// show half runs only then (`0x76abfd`), so a hidden frame moved under a visible parent keeps
+    /// a stale effective visibility until something shows it.
     pub fn reparent_finish(
         &mut self,
         h: FrameHandle,
@@ -352,11 +246,11 @@ impl WidgetArena {
     ) -> Vec<FrameHandle> {
         let mut shown = Vec::new();
         if self.frame(h).is_none() {
-            return shown; // died inside an OnHide — nothing left to move
+            return shown; // died inside an OnHide: nothing to move
         }
         let new_parent = new_parent.filter(|&p| self.frame(p).is_some());
-        // Relink from the CURRENT parent (an OnHide handler may itself have reparented; the
-        // reference's unconditional `+0x9c` store at `0x76ab49` means the outer call wins).
+        // Relink from the current parent: an `OnHide` may have reparented it, and the reference's
+        // unconditional `+0x9c` store (`0x76ab49`) lets the outer call win.
         let old_parent = self.frame(h).unwrap().parent;
         if let Some(op) = old_parent {
             if let Some(of) = self.frame_mut(op) {
@@ -373,8 +267,7 @@ impl WidgetArena {
                 let pf = self.frame(np).expect("live new parent");
                 (pf.strata, pf.level.saturating_add(1))
             }
-            // SetParent(nil) is a RESET — strata 3 (MEDIUM), level 0 (`0x76aba3`/`0x76abac`) —
-            // not "keep current".
+            // `SetParent(nil)` resets to MEDIUM and level 0 (`0x76aba3`/`0x76abac`).
             None => (Strata::default(), 0),
         };
         self.set_frame_strata(h, pstrata);
@@ -388,10 +281,7 @@ impl WidgetArena {
         shown
     }
 
-    /// [`Self::reparent_begin`] + [`Self::reparent_finish`] in one call, for callers with no Lua
-    /// to fire between the halves (tests, direct arena use). Returns both phases' visibility
-    /// changes concatenated — hide half first. The Lua binding does NOT use this: it must fire
-    /// `OnHide` between the phases (the events' direction is read from live state at fire time).
+    /// Both reparent phases in one call, hide changes first, for a caller with no `OnHide` to fire.
     pub fn set_parent(
         &mut self,
         h: FrameHandle,
@@ -405,41 +295,18 @@ impl WidgetArena {
         [hidden, shown].concat()
     }
 
-    /// Re-link a **region leaf** (Texture/FontString) to a new owner frame — the arena half of
-    /// `Region:SetParent`. `None` detaches ([`super::Region::detached`]). Returns whether anything
-    /// moved (a same-owner call and a stale handle both report `false`).
-    ///
-    /// **This is a different mechanism from the frame reparent above, and the difference is
-    /// verified.** `SetParent` is one Region-table binding (`0x7a1550`) dispatching a per-class
-    /// virtual: a plain Region gets `0x76c430`, which writes the geometry parent and nothing else,
-    /// but a Texture or FontString gets `0x7733d0` → `0x77fd10`, a **full re-link** — remove from
-    /// the old parent's draw layer (`0x77fc60`) and region list (`vtbl+0x2c`), store the new
-    /// parent, insert into its region list (`0x76a750`) and re-register in its draw layer
-    /// (`0x77fcb0`), **preserving layer and sub-level**.
-    /// So the layer/sub-level fields are deliberately untouched here and only the membership moves;
-    /// the fresh `decl_seq` is the "insert into the new parent's region list" half, which lands the
-    /// region at the tail of that frame's list exactly as the client's insert does.
-    ///
-    /// Nothing propagates, unlike the frame reparent: a region has no effective-visible/scale/alpha
-    /// of its own here — every reader (`IsVisible`, the measure key, `extract`'s alpha product)
-    /// resolves the owner frame's live values through [`super::Region::owner`], so re-pointing that
-    /// field *is* the propagation the client does eagerly (`0x77fd10` pushes the new parent's shown
-    /// bit into the region).
-    ///
-    /// **A same-owner call is a no-op, and that is the conservative reading, not a verified one.**
-    /// `0x77fd10` is unconditional, so the reference may re-tail a region within its own layer when
-    /// an addon re-parents it to the frame it already belongs to. Not reproducing that can only
-    /// ever *preserve* declared draw order, never invent one; and the corpus's only region
-    /// `SetParent` caller — `FuBar_FuXPFu.lua:210-211`, which re-parents two `XPBar:CreateTexture`
-    /// sparks to `XPBar` — moves both in declaration order, so the two readings agree there.
+    /// `Region:SetParent` for a texture or font string; `None` detaches. The client re-links in
+    /// full (`0x7733d0` → `0x77fd10`): out of the old parent's layer (`0x77fc60`) and list, into
+    /// the new parent's list (`0x76a750`) and layer (`0x77fcb0`), its layer kept, so the region
+    /// takes the tail `decl_seq`. Readers resolve through `owner`, so nothing propagates. A
+    /// same-owner call is a no-op, as in the reference (`0x77fd33`).
     pub fn set_region_owner(&mut self, rh: RegionHandle, new_owner: Option<FrameHandle>) -> bool {
         let Some(region) = self.region(rh) else {
             return false;
         };
         let (old_owner, was_detached) = (region.owner, region.detached);
-        // Keep only a live new owner. No cycle check: the client's (`0x7a177f`) walks the new
-        // parent's frame chain looking for the receiver, and a Texture/FontString is never a frame,
-        // so for a region it can never fire.
+        // No cycle check: the client's (`0x7a177f`) looks for the receiver in the new parent's
+        // frame chain, and a region is never a frame.
         let new_owner = new_owner.filter(|&f| self.frame(f).is_some());
         match new_owner {
             Some(f) if f == old_owner && !was_detached => return false,
@@ -447,8 +314,6 @@ impl WidgetArena {
             _ => {}
         }
         let Some(new_owner) = new_owner else {
-            // Detached: the entry stays in its last owner's list (so `destroy` still frees it) and
-            // the flag alone takes it out of the draw.
             if let Some(r) = self.region_mut(rh) {
                 r.detached = true;
             }
@@ -475,89 +340,69 @@ impl WidgetArena {
         true
     }
 
-    // ── Mouse interaction (the hit-test flag) ────────────────────────────────────────────────────
+    // ── Frame flags ──────────────────────────────────────────────────────────────────────────────
 
-    /// Set a frame's `mouse_enabled` flag (`EnableMouse`). Only mouse-enabled *and* effective-visible
-    /// frames capture the cursor in [`crate::order::hit_test`]; the default is **false** (WoW's
-    /// `enableMouse` default). A stale handle is a no-op. (Keyboard focus is a separate concern, not
-    /// modeled here yet.)
+    /// `EnableMouse`.
     pub fn set_mouse_enabled(&mut self, h: FrameHandle, enabled: bool) {
         if let Some(f) = self.frame_mut(h) {
             f.mouse_enabled = enabled;
         }
     }
 
-    /// `EnableKeyboard` (`0x776f90`) — kind-0/kind-1 bucket membership. Stored and answered, and
-    /// it is what [`crate::script::keyboard`]'s delivery walk filters on (1319).
+    /// `EnableKeyboard` (`0x776ec0`): the char and key bits the key walk filters on.
     pub fn set_keyboard_enabled(&mut self, h: FrameHandle, enabled: bool) {
         if let Some(f) = self.frame_mut(h) {
             f.keyboard_enabled = enabled;
         }
     }
 
-    /// Whether the frame is keyboard-enabled. A stale handle reads as `false`.
+    /// `IsKeyboardEnabled` (`0x776f90`).
     pub fn is_keyboard_enabled(&self, h: FrameHandle) -> bool {
         self.frame(h).is_some_and(|f| f.keyboard_enabled)
     }
 
-    /// `EnableMouseWheel` — the wheel's own gate, separate from the mouse's (decision 1198).
+    /// `EnableMouseWheel`, the wheel's own bit, separate from the mouse's.
     pub fn set_mouse_wheel_enabled(&mut self, h: FrameHandle, enabled: bool) {
         if let Some(f) = self.frame_mut(h) {
             f.mouse_wheel_enabled = enabled;
         }
     }
 
-    /// Whether the frame currently accepts the wheel. A stale handle reads as `false`.
     pub fn is_mouse_wheel_enabled(&self, h: FrameHandle) -> bool {
         self.frame(h).is_some_and(|f| f.mouse_wheel_enabled)
     }
 
-    /// Whether the frame currently accepts the mouse (see [`WidgetArena::set_mouse_enabled`]). A
-    /// stale handle reads as `false`.
     pub fn is_mouse_enabled(&self, h: FrameHandle) -> bool {
         self.frame(h).map(|f| f.mouse_enabled).unwrap_or(false)
     }
 
-    // ── Clamp-to-screen (geometry flags bit4) ────────────────────────────────────────────────────
-
-    /// Set a frame's clamp-to-screen flag (`SetClampedToScreen` `0x776c00` — geometry flags bit4;
-    /// see [`Frame::clamped_to_screen`] for the tooltip-kind default). A stale handle is a no-op.
+    /// `SetClampedToScreen` (`0x776c00`).
     pub fn set_clamped_to_screen(&mut self, h: FrameHandle, clamp: bool) {
         if let Some(f) = self.frame_mut(h) {
             f.clamped_to_screen = clamp;
         }
     }
 
-    /// Whether the frame clamps to the screen (`IsClampedToScreen` `0x776cb0`). A stale handle
-    /// reads as `false`.
+    /// `IsClampedToScreen` (`0x776cb0`).
     pub fn is_clamped_to_screen(&self, h: FrameHandle) -> bool {
         self.frame(h).map(|f| f.clamped_to_screen).unwrap_or(false)
     }
 
-    // ── Hit-rect insets (the mouse rect, not the draw rect) ──────────────────────────────────────
-
-    /// Set a frame's hit-rect insets, `[left, right, top, bottom]` (`SetHitRectInsets`; see
-    /// [`Frame::hit_rect_insets`]). A stale handle is a no-op.
+    /// `SetHitRectInsets`, `[left, right, top, bottom]`.
     pub fn set_hit_rect_insets(&mut self, h: FrameHandle, insets: [f32; 4]) {
         if let Some(f) = self.frame_mut(h) {
             f.hit_rect_insets = insets;
         }
     }
 
-    /// A frame's hit-rect insets, `[left, right, top, bottom]` (`GetHitRectInsets`). A stale handle
-    /// reads as all-zero — the same "no inset" answer an untouched frame gives.
+    /// `GetHitRectInsets`, `[left, right, top, bottom]`.
     pub fn hit_rect_insets(&self, h: FrameHandle) -> [f32; 4] {
         self.frame(h).map(|f| f.hit_rect_insets).unwrap_or([0.0; 4])
     }
 
     // ── Small helpers ────────────────────────────────────────────────────────────────────────────
 
-    /// Is `maybe_ancestor` on the parent chain of `node` (walking up, loop-guarded)? — the client's
-    /// `0x767010`, read the other way round.
-    ///
-    /// Two callers, and they are the two the binary has: [`WidgetArena::set_parent`]'s cycle guard,
-    /// and the raise's overlap scan, which excludes the raised frame's own subtree from the frames
-    /// it may be considered to overlap ([`crate::script::object::toplevel`]).
+    /// Whether `maybe_ancestor` is on `node`'s parent chain (`0x767010`, read the other way round).
     pub fn is_ancestor(&self, maybe_ancestor: FrameHandle, node: FrameHandle) -> bool {
         let mut cur = self.frame(node).and_then(|f| f.parent);
         let mut guard = 0usize;
@@ -568,7 +413,7 @@ impl WidgetArena {
             cur = self.frame(c).and_then(|f| f.parent);
             guard += 1;
             if guard > self.frames.slots.len() {
-                break; // defensive; a well-formed tree never loops
+                break; // a well-formed tree never loops
             }
         }
         false
diff --git a/crates/benilla-ui/src/widget/tests.rs b/crates/benilla-ui/src/widget/tests.rs
index eb2c857c..3dcbfdc0 100644
--- a/crates/benilla-ui/src/widget/tests.rs
+++ b/crates/benilla-ui/src/widget/tests.rs
@@ -1,8 +1,4 @@
-//! Rust-driven tests of [`super::WidgetArena`]'s propagation mutators: effective visibility,
-//! strata subtree-force, level delta-shift, scale propagation, reparenting, the named registry, and
-//! the byte-verified alpha overwrite-cascade. Split out alongside the propagation mutators purely
-//! for size — the tests exercise both `super` (create/destroy) and `super::propagation` (the
-//! mutators) through the one public `WidgetArena` surface.
+//! Tests of [`super::WidgetArena`]'s mutators and registries.
 
 use super::*;
 
@@ -22,7 +18,6 @@ fn hide_show_toggles_effective_visibility_and_reports_changes() {
     assert_eq!(changed, vec![root]);
     assert!(!a.frame(root).unwrap().effective_visible);
 
-    // Hiding again is a no-op (already hidden).
     assert!(a.set_shown(root, false).is_empty());
 
     let changed = a.set_shown(root, true);
@@ -38,7 +33,6 @@ fn mid_tree_hide_blocks_a_shown_grandchild() {
     let grand = a.create(FrameKind::Frame, None, Some(child));
     assert!(a.frame(grand).unwrap().effective_visible);
 
-    // Hide the middle frame: child + grand lose effective visibility, though both are `shown`.
     let changed = a.set_shown(child, false);
     assert_eq!(changed, vec![child, grand]); // pre-order
     assert!(a.frame(root).unwrap().effective_visible);
@@ -49,7 +43,6 @@ fn mid_tree_hide_blocks_a_shown_grandchild() {
         "grandchild's own shown bit is untouched"
     );
 
-    // Re-show the middle: both come back.
     let changed = a.set_shown(child, true);
     assert_eq!(changed, vec![child, grand]);
     assert!(a.frame(grand).unwrap().effective_visible);
@@ -62,13 +55,12 @@ fn hidden_grandchild_stays_hidden_when_ancestor_reshows() {
     let child = a.create(FrameKind::Frame, None, Some(root));
     let grand = a.create(FrameKind::Frame, None, Some(child));
 
-    a.set_shown(grand, false); // grand's own shown = false
-    let changed = a.set_shown(root, false); // hide the top
-                                            // grand was already effectively invisible, so it does NOT re-report on the hide.
+    a.set_shown(grand, false);
+    let changed = a.set_shown(root, false);
+    // grand is already invisible, so the hide does not report it.
     assert_eq!(changed, vec![root, child]);
 
-    let changed = a.set_shown(root, true); // re-show top
-                                           // child comes back; grand stays hidden (its own shown is false).
+    let changed = a.set_shown(root, true);
     assert_eq!(changed, vec![root, child]);
     assert!(a.frame(child).unwrap().effective_visible);
     assert!(!a.frame(grand).unwrap().effective_visible);
@@ -97,13 +89,11 @@ fn set_level_delta_shifts_same_strata_children_only() {
     let root = a.create(FrameKind::Frame, None, None);
     let same = a.create(FrameKind::Frame, None, Some(root));
     let cross = a.create(FrameKind::Frame, None, Some(root));
-    // root level 0; give the children distinct levels to prove the *delta* (relative offset) is
-    // preserved, not the absolute value.
+    // Distinct child levels show the delta is kept, not the absolute level.
     a.set_frame_level(same, 5, true);
     a.set_frame_level(cross, 2, true);
-    a.set_frame_strata(cross, Strata::High); // move `cross` to another strata
+    a.set_frame_strata(cross, Strata::High);
 
-    // Raise root by +10 with propagation.
     a.set_frame_level(root, 10, true);
     assert_eq!(a.frame(root).unwrap().level, 10);
     assert_eq!(
@@ -124,8 +114,8 @@ fn level_shift_saturates_at_zero() {
     let root = a.create(FrameKind::Frame, None, None);
     let child = a.create(FrameKind::Frame, None, Some(root));
     a.set_frame_level(root, 10, true);
-    a.set_frame_level(child, 12, true); // child two above root
-                                        // Drop root to 0 (delta -10): child would be 2.
+    a.set_frame_level(child, 12, true);
+    // Root drops by 10, taking the child from 12 to 2.
     a.set_frame_level(root, 0, true);
     assert_eq!(a.frame(child).unwrap().level, 2);
 }
@@ -154,12 +144,10 @@ fn scale_epsilon_gate_skips_subthreshold_change() {
     let mut a = arena();
     let root = a.create(FrameKind::Frame, None, None);
     let child = a.create(FrameKind::Frame, None, Some(root));
-    // Set a marker on the child's effective scale we can detect being (not) overwritten.
     a.set_scale(child, 4.0);
     assert_eq!(a.frame(child).unwrap().effective_scale, 4.0);
 
-    // Nudge root by less than ε: effective scale of root barely moves, so the recursion into the
-    // child is pruned and the child keeps its exact prior value.
+    // A sub-ε change to the root prunes the recursion, so the child keeps its exact value.
     let tiny = 1.0 + (SCALE_EPS as f32) / 4.0;
     a.set_scale(root, tiny);
     assert_eq!(
@@ -184,7 +172,6 @@ fn reparent_reinherits_visibility_and_scale() {
     assert!(a.frame(child).unwrap().effective_visible);
     assert_eq!(a.frame(child).unwrap().effective_scale, 3.0);
 
-    // Move under the hidden parent: child loses visibility and re-inherits scale 2.0.
     let changed = a.set_parent(child, Some(hidden));
     assert_eq!(changed, vec![child]);
     assert!(!a.frame(child).unwrap().effective_visible);
@@ -201,7 +188,6 @@ fn reparent_cycle_is_rejected() {
     let mut a = arena();
     let root = a.create(FrameKind::Frame, None, None);
     let child = a.create(FrameKind::Frame, None, Some(root));
-    // Making root a child of its own child would cycle — rejected, no-op.
     let changed = a.set_parent(root, Some(child));
     assert!(changed.is_empty());
     assert_eq!(a.frame(root).unwrap().parent, None);
@@ -216,7 +202,6 @@ fn named_registry_is_non_overwriting() {
     let first = a.create(FrameKind::Frame, Some("MyFrame".into()), None);
     let second = a.create(FrameKind::Frame, Some("MyFrame".into()), None);
     assert_ne!(first, second);
-    // The first writer owns the name; the duplicate still carries its own `name` field.
     assert_eq!(a.lookup("MyFrame"), Some(first));
     assert_eq!(a.frame(second).unwrap().name.as_deref(), Some("MyFrame"));
 }
@@ -243,13 +228,12 @@ fn generational_handle_detects_reuse() {
     let mut a = arena();
     let h = a.create(FrameKind::Frame, None, None);
     a.destroy(h);
-    // A new frame may reuse the slot; the old handle must not resolve to it.
     let h2 = a.create(FrameKind::Frame, None, None);
     assert!(a.frame(h).is_none());
     assert!(a.frame(h2).is_some());
 }
 
-// ── Alpha (the byte-verified overwrite-cascade, SetAlpha 0x76a690) ───────────────────────────
+// ── Alpha ────────────────────────────────────────────────────────────────────────────────────
 
 #[test]
 fn set_alpha_overwrites_the_subtree() {
@@ -258,27 +242,23 @@ fn set_alpha_overwrites_the_subtree() {
     let child = a.create(FrameKind::Frame, None, Some(root));
     let grandchild = a.create(FrameKind::Frame, None, Some(child));
     a.set_alpha(root, 0.5);
-    // The same raw value lands on every descendant frame (a flatten, not a product).
     for h in [root, child, grandchild] {
         assert_eq!(a.frame(h).unwrap().alpha, 0.5);
         assert_eq!(a.frame(h).unwrap().effective_alpha, 0.5);
     }
-    // Last write wins: a child's own later SetAlpha diverges until the parent sets again…
+    // Last write wins: the child's own SetAlpha holds until the parent sets again.
     a.set_alpha(child, 1.0);
     assert_eq!(a.frame(root).unwrap().effective_alpha, 0.5);
     assert_eq!(a.frame(child).unwrap().effective_alpha, 1.0);
     assert_eq!(a.frame(grandchild).unwrap().effective_alpha, 1.0);
-    // …and a frame created under a dimmed parent starts at 1.0 (creation doesn't re-push).
+    // A frame created under a dimmed parent starts at 1.0.
     let late = a.create(FrameKind::Frame, None, Some(root));
     assert_eq!(a.frame(late).unwrap().effective_alpha, 1.0);
 }
 
 // ── The per-kind registries ──────────────────────────────────────────────────────────────────
 
-/// The tooltip registry is exactly the live GameTooltips — including when one dies as somebody
-/// else's child, which is the case a registry maintained only at the explicit `destroy` call site
-/// would miss. Three hot paths read it instead of scanning the resolve's roster (decision 1634), so
-/// a stale entry is a dangling handle in the layout pre-pass, not a cosmetic drift.
+/// Includes a tooltip destroyed as another frame's child.
 #[test]
 fn the_tooltip_registry_tracks_live_gametooltips() {
     let mut a = arena();
@@ -287,11 +267,9 @@ fn the_tooltip_registry_tracks_live_gametooltips() {
     let holder = a.create(FrameKind::Frame, None, None);
     let loose = a.create(FrameKind::GameTooltip, None, None);
     let child = a.create(FrameKind::GameTooltip, None, Some(holder));
-    // A non-tooltip kind never enters the list.
     let _plain = a.create(FrameKind::Button, None, None);
     assert_eq!(a.tooltip_kinds(), &[loose, child]);
 
-    // Destroying the PARENT takes its tooltip child with it.
     a.destroy(holder);
     assert_eq!(a.tooltip_kinds(), &[loose]);