Syplheed-Reborn/docs/re/structures/ui-resting-pose.md

# A keyframe is the start of a ramp, not a pose that is held

**Status:** ✅ `CONFIRMED` against the framebuffer capture of the running title
screen — the new rule aligns at **zero shift**, the old one had to be moved.
🟡 the fallback for groups that never hold is unverified. ❔ interpolation
between keyframes is still not implemented, only the resting pose.

## The rule that was wrong

`Element::rest()` answers "where is this element when the screen is just sitting
there", and every composite the port draws depends on it. It used to pick the
keyframe with the **largest gap to the next keyframe's time** — the frame that
"dwells longest".

That reads a keyframe as a value held until the next one. It is not: a keyframe
is the **start of a ramp toward the next one**. So a long gap after keyframe *k*
means the screen spends that whole time *arriving at* `k+1` — the settled pose is
at the **far** end of the gap, not the near one.

The title wordmark makes it concrete. `ptlogo1.t32` zooms in from off-screen:

```
kf0  150%  (-116,  -7)  a=0x00   t=26     off-screen, invisible
kf1  150%  (-116,  -7)  a=0x00   t=34
kf2  112%  ( 109, 123)  a=0x80   t=38
kf3  103%  ( 165, 171)  a=0xc0   t=40
kf4  101%  ( 179, 186)  a=0xe0   t=42     ← old rule picked this
kf5  100%  ( 184, 193)  a=0xff   t=251    ← the settled pose
kf6  100%  ( 184, 193)  a=0xff   t=264    ← held here
kf7  100%  ( 184, 193)  a=0x00   t=None   fades out
```

The gap 42 → 251 is by far the largest, so the old rule picked **kf4** — 1 % too
large and 5 px up-left, a frame from mid-zoom. The pose the screen actually holds
is kf5–kf6.

## The rule that is right

**The resting pose is the hold: the longest run of consecutive keyframes with an
identical pose.** Ties go to the later run, matching the in → hold → out shape.
Groups that ramp through every frame and never hold fall back to longest-dwell.

## The measurement

`docs/re/captures/title-screen-oracle.png` is a framebuffer capture of the
running title screen. It is a **1:1 crop** of the 1280×720 frame (1279×675) —
verified by the copyright line landing on row 669 in the capture and in both
composites — so frame coordinates map directly and a shift is meaningful.

Edge-correlated over the wordmark box (x 150–1150, y 200–400) with
`tools/re-capture/align_to_capture.py`. Gradient magnitude, not colour: the
capture's planet is mid-explosion and orange while ours is blue, and the wordmark
materials are undecoded, so a pixel diff would measure everything except the
question being asked.

| resting rule | best correlation | at shift | at (0,0) |
|---|---|---|---|
| **plateau** (landed) | **0.4597** | **(0, 0)** | 0.4597 |
| longest dwell (old) | 0.1511 | (+3, +8) | 0.1268 |

The old composite peaks 3× lower **and only after being moved** — displaced by
about the (−5,−7) that kf4-instead-of-kf5 predicts. The new one is already where
the game puts it.

* [composited with the plateau rule](../captures/ui-layout/title-composited-plateau-rest.png)
* [composited with the old longest-dwell rule](../captures/ui-layout/title-composited-longest-dwell-rest.png)

## What else it fixed, on the same screen

The old rule systematically picked the **invisible** end of a fade-in. On the
title screen it rested these at alpha `0x00`, where the capture plainly shows
them:

`ptlogo_tm` (the ™), `ptcopyright`, `ptlogo_back2`, `ptlogo_back2eff`,
`ptloop01`/`ptloop02`.

And `pteff00.prm` — the full-screen fade quad that paints **last** — rested at
**opaque black**. That is the whole screen, and it is why `.prm` compositing was
blocked ([`ui-prm-primitives.md`](ui-prm-primitives.md)).

None of that was visible before, because `compose` never applied the `fade`
alpha at all: `blit` modulates by `tint` only, and `tint` is `0xffffffff` on
essentially every keyframe. The wrong keyframes were being chosen and then their
one distinguishing field was ignored. That is worth stating as its own finding —
see below.

## The `fade` alpha, applied (same day)

`blit` modulated by `tint` only — `0xffffffff` on essentially every keyframe — so
the `fade` word was decoded, stored, and then thrown away. Applying it as an
**ARGB** modulate on top of `tint` is what turns the resting pose from an
academic result into a picture:

| composite | best correlation vs the capture | at shift |
|---|---|---|
| plateau rest, `fade` applied | **0.9538** | (0, 0) |
| plateau rest, `fade` ignored | 0.4597 | (0, 0) |
| longest-dwell rest | 0.1511 | (+3, +8) |

0.95 against a framebuffer capture of the running game.
[The composite](../captures/ui-layout/title-composited-fade-applied.png) now has
the white wordmark with its blue outline, the ™, the copyright, and the orange
exploding planet — the last of which appeared because a full-screen blue effect
that rests at alpha 0 had been painting over it at full opacity.

**ARGB is measured, not assumed.** Across a fade-in the *high* byte walks
`0x00 → 0x80 → 0xc0 → 0xe0 → 0xff` while the low three stay `ffffff`, and the low
24 bits are `0xffffff` on 5 276 of the disc's 5 453 resting keyframes (with
`0x000000` on 165 — the `.prm` blacks — and `0x5dc9ff` on 12).

Risk checked, because a modulate can only ever remove pixels: it is a **no-op on
4 060 of 5 200** sprite elements, partial on 453, and hides 687 — which are
transient HUD indicators (`pb_emergency`, `pb_refilling`, `pbcm1_arrow1`) that
should not be lit on a resting screen. **No build is left with nothing visible**,
and a disc test asserts it.

### And it caught a bug in the resting rule

With `fade` applied, the pause menu lost the word **PAUSE**, which the capture of
the running game plainly shows
([`pause-tutorial-real-vs-rebuilt.png`](../captures/ui-layout/pause-tutorial-real-vs-rebuilt.png)).

`pgptitle.rat` has **three** runs of two identical keyframes — invisible,
visible, invisible:

```
kf0 a=0x00 t=5    kf1 a=0x00 t=13     pre-roll
kf2 a=0xff t=23   kf3 a=0xff t=28     the hold
kf4 a=0x00 t=30   kf5 a=0x00 t=None   the exit
```

A group carries the screen's entry animation **and its exit**. The tie-break
"later run wins" grabbed the exit. Fixed: a run ending on the last keyframe is
excluded unless it is the only one. The title's correlation is unchanged at
0.9538, and [PAUSE is back](../captures/ui-layout/pause-composited-fade-applied.png).

This is why the two changes landed together: the trailing-run defect is
invisible — in the literal sense — until `fade` is applied.

## What is not settled

* ❔ **Blend mode.** Everything above is straight alpha-over. The near-white
  flash quads and the coloured ones may well be additive, and nothing has been
  measured; the title capture cannot separate the two because its resting
  elements are all `0xffffff`.
* 🟡 **The fallback.** Groups with no two adjacent keyframes alike still use
  longest-dwell. How many there are, and whether the correct answer for them is
  the *last* keyframe instead, is unmeasured.
* ❔ **Interpolation.** Only the resting pose is decoded; nothing tweens. A
  viewer that animates these screens needs the ramp, and whether it is linear is
  unknown.
* 🟡 One-shot flashes (`ptlogoall_eff`, `ptlogoall_eff2`) ramp 0 → 0x80 → 0x4b →
  0 and never hold at a visible value, so the plateau rule rests them at alpha 0
  — invisible. That is *probably* right for a settled screen, but the capture
  cannot confirm it while `fade` is unapplied.


## 🔴 `rest_plateau` is wrong for elements with no exit animation (2026-08-28)

Reported by the port agent with a capture that proves it, and it affects
`sylpheed-cli screen render` too — this is not only a port concern.

`rest_plateau` drops a trailing run of identical keyframes because that run is
normally the **exit** animation. On an element that has **no exit**, the trailing
run *is* the hold, and dropping it puts the element back at its **first**
keyframe — off-position and transparent.

**The condition that identifies these exactly** (no false positives across the
port's whole export):

> the final untimed keyframe has the same pose as the last timed one

**Six elements** on `main_menu` match it and `rest()` misses all six. The
visible cost: on `main_menu` the timeline render and the `rest` render differ in
exactly one region — **400 × 470 at (440,108)**, the bounding box of `ptframe1`
and `ptframe2` and nothing else. That is the **bright circuit bracket around the
menu**, plainly present in
[`../captures/main-menu-oracle.png`](../captures/main-menu-oracle.png) and absent
from the `rest` render. Cropping the same region from the capture and from both
renders puts the ring and its elbow trace pixel-aligned with the game's in the
timeline render.

This also explains a long-standing ❔ on
[`ui-paint-order-key.md`](ui-paint-order-key.md): *"`ptframe1`/`ptframe2` rest at
`0x00ffffff` (alpha 0) and are therefore not drawn, but the capture shows the menu
frame plainly."* Same two elements, same cause — now identified.

## ✅ Fixed 2026-08-28 — but the condition is the ALPHA, not the pose

The report's proposed test — *"the final untimed keyframe has the same pose as the
last timed one"* — **misfires**, and on the exact case the exclusion was written
for. `pgptitle.rat`'s last two keyframes are also identical:

```
pgptitle.rat   kf4: fade=0x00ffffff pos=(220,69) t=30
               kf5: fade=0x00ffffff pos=(220,69) t=None     <- same pose
```

Adopting it as stated would erase the word PAUSE again. What separates the two is
**visibility**:

| | trailing run | alpha | is it the hold? |
|---|---|---|---|
| `ptframe1`/`ptframe2` (main menu) | 3 × `0xffffffff` at (440,108) | `0xff` | **yes** — no exit animation |
| `pgptitle` (pause menu) | 2 × `0x00ffffff` | `0x00` | no — it is the fade-out |

An exit fades the element out, so its last keyframe is transparent; an element
with no exit ends on the pose you can see. **So a trailing run is the hold exactly
when it is visible**, and that is what `rest_plateau` now tests.

### Verified against a capture, not against another renderer

| check | result |
|---|---|
| `ptframe1` rest | `(620,108) t=16` → **`(440,108) t=62`** |
| bracket region draws | mean 61.74 → **62.79** |
| **oracle correlation** over that region vs [`main-menu-oracle.png`](../captures/main-menu-oracle.png) | **0.9596 → 0.9748** |
| pixels changed, whole frame | 10 082, bounding box **x 440–839, y 108–577** — exactly the 400 × 470 at (440,108) the report predicted |
| **regression control**: PAUSE wordmark, 3 pause builds | **unchanged** (2833 / 2858 / 2833 bright px) |

✅ **`cargo test -p sylpheed-formats` with `SYLPHEED_DISC` set: 131 passed, 0
failed** across 6 binaries including the disc-gated ones. (One pre-existing
`ignored` — the XBG7 shared-resource test — unrelated.)

### ✅ The disc-wide check

Both rules reimplemented over the parsed keyframes of **every** `RATC` bundle on
the disc — 2 859 bundles, 13 991 elements with ≥ 2 keyframes:

| | |
|---|---|
| elements whose `rest` moves | **30** (0.21 %) |
| invisible → visible | **4** |
| **visible → invisible** | **0** — the safety property |

The change is surgical and it never hides something that was being drawn. The
remaining 26 move `rest` between two *visible* poses (position, not visibility).

The 4 revealed are `ptframe1.t32` and `ptframe2.t32` in `GP_TITLE` **entry 5 and
entry 8** — the same two elements, once per language build.

### 🟡 Reconciling with the report's "six elements"

On the **English main menu exactly two** elements satisfy the report's condition
(last two keyframes identical), and both are `ptframe1`/`ptframe2`. So the six
must span its whole 12-screen export, not that one screen — consistent with its
own observation that the timeline and `rest` differ *"in exactly one region …
the bounding box of `ptframe1`/`ptframe2` and nothing else"*.

❔ **Open, and it matters:** if any of the other four have a **transparent**
trailing run, this rule deliberately leaves them alone — that exclusion is what
protects the word PAUSE. If a capture shows one of them drawn, the alpha rule is
incomplete and needs a third discriminator. **Which screens are they on?**

---

## 🔴 The dwell fallback is unsound whenever it actually runs (2026-08-28)

`rest()` tries `rest_plateau()` first and, failing that, picks the keyframe with
the longest **dwell** — the largest gap `t[k+1] − t[k]`. That rule is not sound,
and the reason is structural rather than a tuning problem.

A gap between `t[k]` and `t[k+1]` is time the element spends **interpolating from
pose `k` to pose `k+1`**. Neither pose is *held* during it — unless the two poses
are equal, which is exactly a plateau, and the plateau path has already handled
that case and returned. **So by the time the fallback runs, it is guaranteed that
no pose is held, and the rule is choosing an endpoint of a movement.**

### The element that exposed it

`GP_TITLE` build 7, `ptlogo_eff3.t32` — a transient bloom:

```
 46: (98,42)  100%,100% a=0
 61: (108,72)   0%,0%   a=0
103: (108,72) 200%,200% a=255  r=80
  -: (108,72)   0%,0%   a=0    r=150
```

No two adjacent poses are equal, so there is no plateau. The longest gap is
`61 → 103` (42 units), during which the sprite grows from nothing to **200 %** at
full alpha while rotating 80°, then collapses again. The rule returns whichever
end of that movement the indexing lands on:

| | returned "rest pose" |
|---|---|
| as decoded | `(108,72) 0%,0% a=0` — invisible |
| with `SYLPHEED_KF_TIME_SHIFT=1` | `(108,72) 200%,200% a=255` — the peak |

An 896×389 sprite at 200 % scale is 1792×778 — larger than the screen. Painting
it permanently is what made build 7's render 13.1 % different and 4.9 luminance
units brighter.

**The element has no resting pose.** It is a flash; after it plays there is
nothing. Neither answer is *derived* — one of them is merely harmless.

### 🔴 What this retracts

Last iteration I reported the build 7 render difference as evidence **against**
the keyframe-time shift, on the reasoning that language twins should match in
brightness. **Withdrawn.** The difference is not about the time association at
all: it is the dwell fallback guessing, and it would guess on this element under
any reading of the times. The brightness comparison was measuring a heuristic,
not a decode.

What that leaves: the case *for* the shift (a factor of 26 on the hold:fade-out
ratio, [`ui-keyframe-time-unit.md`](../ui-keyframe-time-unit.md)) is no longer
opposed by render evidence — 10 of 11 builds are byte-identical and the 11th
differs only through an unsound heuristic.

🟡 **It is still not adopted**, for a different reason than before: adopting it
would flip this element to the visibly wrong answer, so the shift and a decision
about what `rest()` should do for plateau-less elements have to land together,
and the second half has no capture to verify against either.

### ⚠️ What the port should take from this

Any element whose keyframes contain **no two adjacent identical poses** has a
`rest()` result that is guessed, not decoded — in our renderer and in anything
built from it. That is a property a consumer can test for itself in one pass over
the keyframes, and it is worth flagging in an export rather than silently
inheriting our guess.