Pseudocode decompialtion improvements and docs

tools/tests/test_usecode_structuring.py

@@ -3,10 +3,12 @@ from __future__ import annotations
 import unittest
 
 from tools.poc_crusader_usecode_parser import (
+    format_target_event_reference,
     get_intrinsic_hints,
     intrinsic_display_name,
     render_partially_structured_blocks,
     render_structured_pseudocode,
+    try_decode_loop_selector,
 )
 
 
@@ -91,6 +93,78 @@ class UsecodeStructuringTests(unittest.TestCase):
         self.assertIn("while (!condition) {", text)
         self.assertNotIn("goto block_0118;", text)
 
+    def test_loop_selector_block_renders_as_for_loop(self) -> None:
+        blocks = [
+            ("entry", ["/* loop_selector item in nearby_items(shape=0x04D0, origin=arg_06) */"]),
+            ("block_0118", ["if condition goto block_0151;"]),
+            ("block_011B", ["if (Item.getFrame(item) != 0) goto block_014D;", "suspend;"]),
+            ("block_014D", ["goto block_0118;"]),
+            ("block_0151", ["return;"]),
+        ]
+
+        rendered = render_structured_pseudocode(blocks)
+
+        self.assertIsNotNone(rendered)
+        text = "\n".join(rendered or [])
+        self.assertIn("for item in nearby_items(shape=0x04D0, origin=arg_06) {", text)
+        self.assertNotIn("while (!condition) {", text)
+
+    def test_loop_selector_renders_in_partial_fallback(self) -> None:
+        blocks = [
+            ("entry", ["/* loop_selector item in nearby_items(shape=0x04D0, origin=arg_06) */"]),
+            ("block_0118", ["if condition goto block_0151;"]),
+            ("block_011B", ["if other goto block_014D;", "suspend;"]),
+            ("block_014D", ["goto block_0118;"]),
+            ("block_0151", ["goto block_0200;"]),
+            ("block_0200", ["return;"]),
+        ]
+
+        rendered = render_partially_structured_blocks(blocks)
+
+        text = "\n".join(rendered)
+        self.assertIn("entry:", text)
+        self.assertIn("for item in nearby_items(shape=0x04D0, origin=arg_06) {", text)
+
+    def test_target_event_reference_prefers_alias_and_class_name(self) -> None:
+        target = format_target_event_reference(
+            {
+                "target_class_id": 0x0A0C,
+                "target_class_name_hint": "FREE",
+                "target_event_slot": 0x32,
+                "target_event_name_hint": None,
+            }
+        )
+
+        self.assertEqual(target, "FREE.waitNTimerTicks")
+
+    def test_selector_0x42_decodes_to_readable_fallback(self) -> None:
+        decoded = try_decode_loop_selector(
+            [
+                {"mnemonic": "loopscr", "operands": {"value_u8": 0x24}},
+                {"mnemonic": "push_word_immediate", "operands": {"value_u16": 0x04C8}},
+                {"mnemonic": "push_word_immediate", "operands": {"value_u16": 0x01CD}},
+                {"mnemonic": "loopscr", "operands": {"value_u8": 0x42}},
+                {"mnemonic": "push_byte_immediate", "operands": {"value_u8": 0x32, "value_signed": 50}},
+                {"mnemonic": "push_byte_immediate", "operands": {"value_u8": 0x20, "value_signed": 32}},
+                {"mnemonic": "mul", "operands": {}},
+                {"mnemonic": "push_local_word", "operands": {"bp_offset": 0x0A}},
+                {
+                    "mnemonic": "loop",
+                    "operands": {"current_var": 0xFE, "string_bytes": 0x6, "loop_type": 0x2},
+                },
+            ],
+            0,
+            {0xFE: "n", 0x0A: "eventTrigger"},
+        )
+
+        self.assertEqual(
+            decoded,
+            (
+                "n in selector_0x42(arg0=0x04C8, arg1=0x01CD, arg2=(50 * 32), origin=eventTrigger)",
+                9,
+            ),
+        )
+
     def test_selector_ladder_renders_as_else_if_chain(self) -> None:
         blocks = [
             ("entry", ["if (dir != 0) goto block_0358;"]),