docs/re: the paint order is sorted by a layer key in the T8aD sprite header

The word at +0x08 of a T8aD header — which this project's decoder never read,
taking width/height/tiles from +0x14 onward — is non-decreasing in the order the
game paints a screen, on BOTH screens whose order has been measured: 20 of the
title's 24 elements (the other four have no T8aD sprite) and 6 of the splash's 7.
No inversion anywhere.

On the splash it explains the whole permutation: the three _eff glows carry
0xa100 and their base logos 0xa110, so the glows paint first even though the
declaration table interleaves them.

This is the first FILE-DERIVABLE account of the paint order. Everything checked
before failed — declaration order and its reverse, the placement region, the RATC
child order, keyframe start and rest times, resting Y, the runtime record's
fields, and every other build's table.

Recorded as unsettled: the ties (two groups share a key and are painted in an
order that is not declaration order), what the bits actually mean (the values
look like flag words, and the two screens use different ranges), and the fact
that two screens is two screens — a third permutation either promotes this to a
rule or breaks it.

docs/re/structures/ui-paint-order-key.md

@@ -0,0 +1,66 @@
+# The paint order comes from a layer key in the T8aD sprite header
+
+**Status:** ✅ `CONFIRMED` on both screens whose paint order has been measured —
+the key is **non-decreasing in paint order on every element that has a sprite**,
+20 of 24 on one and 6 of 7 on the other. 🟡 ties are not explained. ❔ the field's
+full meaning (it looks like flags, not a plain depth).
+
+## The field
+
+Every `T8aD` sprite begins with a 44-byte header. The word at **`+0x08`** —
+untouched by this project's decoder, which reads width/height/tile-count at
+`+0x14`/`+0x18`/`+0x1c` — sorts the screen.
+
+Read in the order the game paints them (`ui-screen-runtime.md` has how that order
+was measured — off the live child list, checked against a draw capture):
+
+**`GP_TITLE` build 4, the title screen**
+
+| paint slot | element | sprite | `+0x08` |
+|---|---|---|---|
+| 0 | 9 | `ptbase2` | `0x8000` |
+| 3 | 10 | `pteff04` | `0x8020` |
+| 5 | 6 | `pteff01` | `0x8040` |
+| 6 | 20 | `ptlogo_back2eff` | `0x8081` |
+| 7 | 19 | `ptlogo_back2` | `0x8082` |
+| 8–12 | 14,15,18,16,17 | `back2eff1…5` | `0x8083` ×5 |
+| 13–19 | 0,2,4,7,1,3,5 | `ptlogo1`/`tm`/`ptlogo2` | `0x80a0` ×7 |
+| 20 | 22 | `ptlogoall_eff` | `0x80a8` |
+| 21 | 23 | `ptlogoall_eff2` | `0x80a9` |
+| 22 | 21 | `ptcopyright` | `0x8100` |
+
+**`GP_TITLE` entries 11/14, the developer-logo splash**
+
+| paint slot | sprite | `+0x08` |
+|---|---|---|
+| 1–3 | the three `_eff` glows | `0x a100` ×3 |
+| 4–6 | the three base logos | `0x a110` ×3 |
+
+Both are **ascending, with no inversion anywhere**. On the splash it explains the
+whole permutation — the glows sort before their logos because `0xa100 < 0xa110`,
+which is why the declaration table's interleaving (base, glow, base, glow) is not
+what you see.
+
+## Why this matters
+
+It is the first **file-derivable** account of the paint order. Everything checked
+before it failed: declaration order and its reverse, the placement region, the
+RATC child order, keyframe start and rest times, resting Y, the runtime element
+record's fields, and every other build's table. This is a per-sprite value the
+port can read directly.
+
+## What is not settled
+
+* **Ties.** Two groups share a key (`0x8083` ×5 and `0x80a0` ×7) and the game
+  paints them in an order that is *not* the declaration order —
+  `14,15,18,16,17` and `0,2,4,7,1,3,5`. Something breaks those ties and it is not
+  known. For the port it may not matter (tied elements are same-layer, and the
+  three `ptlogo1`/`ptlogo2` instances are the ghosts that are not drawn at rest),
+  but it is unmeasured, not proven harmless.
+* **The field's meaning.** `0x8000`, `0x8020`, `0x8040`, `0x8081`… `0x8100` on
+  one screen and `0xa100`/`0xa110` on another look like flag words with a layer
+  in some of the bits rather than a plain integer depth. Sorting on the whole
+  word works on both screens; which bits actually carry the layer is unknown.
+* **Two screens is two screens.** A third measured permutation would either
+  promote this to a rule or break it. The cheapest one available is any screen
+  whose object is resident at the same time as the title's.