Sylpheed/docs/port/DECISIONS.md

# Decisions

One entry per decision that outlives the container it was made in. Newest last.
A decision that lives only in an agent's context is lost when that container
dies, which is what this file is for.

---

## P0 — the exporter, 2026-08-28

### The exporter reads one authored file, and stamps its provenance into the output

`export/` is derived and `authored/` is hand-written, and the natural reading of
that is that the exporter never touches `authored/`. But a screen has to be
*called* something, and the disc does not name its builds — the identification of
build 5 as the main menu is HANDOFF Q2, **measured against a live capture**, not
a field.

Two ways to handle that:

1. the exporter emits `build_05.json` and the runtime renames it from
   `authored/screen_names.json`;
2. the exporter reads that map and writes `main_menu.json` directly.

Chose **2**, with a condition: every name it applies carries `name_source:
"authored"` and a `name_why` quoting the evidence, and `check` **rejects** an
authored name with no `why`. The file that lands in `export/` is therefore still
honest about which of its fields is a measurement — which is the property the
derived/authored split exists to protect — while a human opening the tree sees
`main_menu.json` rather than having to resolve a rename in their head. A build
nobody has identified exports as `build_NN` with `name_source: "index"`, which is
a locator and not a claim.

This is the **only** authored input the exporter takes. Everything else in
`authored/` is applied by the runtime over `export/`.

### Sprites are per screen, not a flat pool

`main_menu` and `extras` both ship a `ptbase.t32` and they are different
pictures. A flat `sprites/` directory would have silently collided; whichever
screen exported second would have won, and the loser would have drawn the wrong
background with no error anywhere. `sprites/<subdir>/<screen>/<name>.png`.

### The format is executable

`sylpheed-export check --out export` validates a tree against `docs/FORMAT.md`
with no disc in hand. It exists because "the export is correct" is otherwise an
assertion, and because the P0 gate is *"validates against FORMAT.md"* — which is
not a thing anyone can confirm by reading.

It reads the tree the way Godot will: as a stranger, with no access to the disc,
the decoders, or the exporter's internals. It deliberately does **not** check the
export against the disc — that is what `sylpheed-cli screen render` is for, at P1.

Checked that it bites, rather than assuming: five mutations of a valid
`main_menu.json` — a broken `paint_order` permutation, a dangling
`focus_sprite`, a reversed `buttons` list, a `#rrggbbaa` colour, an invented
`name_source` — are each caught with a specific message.

### The highlight sprite pairs by name; `opt ` is exported but not believed

FORMAT v1 said `focus_sprite` came from the element's `opt ` link. That reading
was **measured and refuted** by the RE agent, and this export shows why plainly:
on the main menu, `opt ` chains `ptloop01 → ptloop02 → ptbtn01` — two decorations
and then a button. It is a linked list of something, and it is not focus.

The highlight is paired by **sprite name** instead (`ptbtn01.t32` ↔
`ptbtn01f.t32`), which is HANDOFF's convention and holds for all 54 real pairs on
the disc. It resolves all five main-menu buttons. The raw link is still exported
as `opt_link`, renamed so that nothing downstream mistakes it for navigation, and
so that whoever eventually decodes it has the data.

Note this is 🟡 a naming convention, not a decoded field. It is authored in
effect, and lives in the exporter only because it is a rule over disc data rather
than a value we chose.

### The paint order is exported, not authored

Q3 decoded it — a `u16` layer key at `+0x0A` of each `T8aD` sprite header,
stable-sorted with declaration index. So it is read in the exporter, per the
contract's own rule for a decoded answer, and `paint_order` in `export/` is a
derived field. `"paint_order"` is gone from `unresolved`; **`paint_order_ties`
replaces it**, because the tie-break is still unknown and costs one element's
blend on one screen.

Where an element has no `T8aD` header the key comes from the decoders' table of
keys **measured off the running game**. That is a different kind of fact, so it
is labelled: `layer_source` is `"sprite"`, `"implied"` or `"none"`, and a
consumer that needs to know whether a layer is read or measured can tell.

### Colours are exported as two fields with the byte order in the name

There are two modulate colours and they multiply: `tint` is RGBA, `fade` is
**ARGB** and its high byte is the alpha that ramps. v1's single `"#ffffffff"`
could not carry both and silently discarded the ramping alpha. They are exported
as `tint_rgba` and `fade_argb`, raw hex, byte order in the key — because getting
it backwards is silent and looks like an art bug rather than a parse bug.

### `t` stays raw

HANDOFF Q1 is answered — linear ramp, 2 units per rendered frame, working
conversion 1 unit = 1/60 s — but that conversion is **measured off the running
game, not read from the file**, and the finding itself flags the 27.6 present-
frames/second measurement as the part worth re-testing. If the game turns out to
present at 60 Hz, every duration halves.

So `t` is exported exactly as the disc spells it, `keyframe_time_unit` stays in
`unresolved`, and the conversion will live in one authored place at P2. One
constant to change, in a file that says it is a decision.

### The final keyframe has no `t`, and `check` enforces that

The disc has no time slot on the last keyframe of a group. A file that carries
one there has invented it. `check` rejects it — this is the one place where the
temptation to emit a plausible number is strongest and the resulting error is
completely invisible.

---

## P1 — Godot draws the screen, 2026-08-28

### The Godot side reads the manifest, not a path

`ExportTree` is the only class that knows where `export/` is: `SYLPHEED_EXPORT`
if set, otherwise `<project>/../export`. Screens are addressed by their manifest
**name** (`main_menu`), never by a file path, so the runtime never encodes the
archive's subdirectory and a re-export that moves a file does not break it. It
also checks `format` on both the manifest and each screen, and refuses a tree it
was not built to read rather than half-drawing one.

Textures are read as bytes and decoded with `load_png_from_buffer` at runtime.
They are deliberately **not** Godot-imported resources: `export/` is gitignored
and regenerated wholesale, and a `.import` sidecar per sprite would be derived
state living next to derived state, invalidated on every re-export.

### One CanvasItem draws the whole screen

`ScreenView._draw` walks `paint_order` and draws each element itself, rather
than making a node per element and leaning on `z_index`. The export's
`paint_order` is already back-to-front, so honouring it is a loop; expressing
the same order through sixteen nodes' z-indices would hide the one thing that is
still unresolved about it — the **ties** — behind Godot's own sibling rules,
where a change in the export would silently become a change in Godot's tree
order instead of a visible change in the draw sequence.

### P1 draws `rest` and nothing else

Every element is drawn at its resting pose. No keyframe interpolation: that is
P2, and it depends on the keyframe time unit, which is **measured** rather than
decoded. A milestone whose gate is a pixel diff must not have a measured
constant inside it, or the diff stops being evidence about the port.

For the same reason `focused_id` is empty at P1. Initial focus was measured as
unstable boot to boot (HANDOFF Q5), so choosing one is an authored decision and
it belongs to P5, where a human is pressing keys.

### Nearest-neighbour, and why that is not a preference

`TEXTURE_FILTER_NEAREST`. The export is a 1:1 copy of the disc's own texels and
elements draw at up to 500 %; a bilinear filter invents detail the disc does not
have. It is also what the reference renderer does — `ui_layout::blit` maps
destination to source by integer division — so a filter difference cannot
masquerade as a placement difference in the diff.

### The capture is the SubViewport, not the window

The screen is drawn into a `SubViewport` sized to the export's own `design`
rectangle and shown through a container that scales it to the window. The first
attempt captured `get_viewport()` and got **1235×695**: there is a window manager
on the Xvfb display and its title bar had eaten 45×25 px of a screen the export
declares as 1280×720. A gate that compares a rescaled 1235×695 capture against a
1280×720 composite measures the compositor.

So `--capture` grabs the SubViewport texture: exactly the design rectangle,
independent of the window, directly comparable with `screen render` with no crop
and no resample. The windowed run is still worth doing — it is what proves a
human sees the screen — but it is not what the numbers come from.

## P1 gate — the diff, and what it found

`tools/verify-screen` renders every screen in the manifest both ways and reports
the largest per-channel difference anywhere in the frame. Both renderers are held
to the same inputs: the reference CLI built by `build-reference-cli` from the
revision the exporter is **pinned** to (not `/reborn/target/`, which is a live
mount that moves mid-iteration), `--black` because the screen carries its own
background, and `--primitives --animated` because those are what make the CLI
draw the same element set the port draws at rest.

| screen | build | max per-channel Δ | |
|---|---|---|---|
| `main_menu` | 5 | **3** | the P0/P1 gate screen |
| `main_menu_jp` | 8 | 3 | |
| `extras` / `extras_jp` | 6 / 9 | 4 / 3 | |
| `press_start` / `press_start_jp` | 2 / 3 | 1 | |
| `build_00` / `build_01` | 0 / 1 | 3 | |
| `build_10` / `build_11` | 10 / 11 | **0** | byte-identical |
| `title` | 4 | 6 | paint-order tie, below |
| `title_jp` | 7 | 154 | sampling phase, below |

`main_menu` — the milestone's own gate — agrees to **≤3/255 on every channel of
every pixel**, RMSE 0.38 %, with **no** pixel differing by more than 4 %. 3/255
is what integer-truncating compositing in the CLI and float rounding on a GPU
differ by; there is no structural disagreement anywhere in the frame.

Three screens exceed that, and each has a named cause rather than a threshold.

### `title`: a tie in the paint order — neither renderer is wrong

Build 4 is the one screen where the CLI uses a paint order **measured off the
running game** instead of deriving it. Compared against the order this port
exports, every single disagreement is **inside a tie** — the two orders differ
only among elements carrying *identical* layer keys (`0x8083`, the `back2` glow
group, and `0x80a0`):

```
derived : … 15, 16, 17, 18, 0, 1, 2, 3, 4, 5, 7, …
measured: … 15, 18, 16, 17, 0, 2, 4, 7, 1, 3, 5, …
```

That is exactly the residual HANDOFF Q3 documents and this export already
declares in `unresolved: ["paint_order_ties"]`. It is worth stating what it
costs: **904 px** in the glow band at (445,117)–(1195,313), all of them 4–6/255.
The port keeps the stable sort, per HANDOFF's own recommendation. Nothing to fix,
and nothing to tune — a "fix" here would be fitting the port to one screen's
capture.

Two of the reordered indices (`0x80a0`) are `kind & 0x4` template instances that
both renderers skip, so the only real reorder outside the glow group is
`ptlogo2` against `ptlogo_tm`, which do not overlap.

### `title_jp`: nearest-neighbour sampling phase — the CLI is the one I would call wrong

`title_jp` is the **only** screen in the export with a drawn element at a scale
that is not a whole multiple of 100 %: `ptlogo_eff2` at 125 %. It is also the
only screen with a difference above 6/255. The two facts are the same fact.

At a non-integer ratio the two renderers pick different source texels:

* `ui_layout::blit` samples the source at the destination pixel's **top-left
  corner** — `sxi = col * sw / dw`.
* A GPU samples at the destination pixel's **centre** — `floor((col+0.5)·sw/dw)`.

At 125 % those disagree on one column in five, which is why the differing pixels
are ~30 above 100/255 strung along thin diagonal edges rather than a shifted
region. At every whole multiple of 100 % they agree exactly, which is why the
other eleven screens are clean.

**Which is wrong:** the CLI, I think. Corner-sampled nearest is a half-
destination-pixel bias toward the top-left that no rasteriser produces, and the
Xenon GPU that drew this screen sampled at pixel centres. But I have no
framebuffer capture of `title_jp` and the disagreement is sub-pixel on one glow,
so this is a reading, not a measurement — recorded in `docs/BLOCKED.md` rather
than acted on. **The port is not changing to match**, because matching the CLI
here would mean deliberately reproducing a half-pixel offset in order to make a
number smaller.

### `extras`: two pixels

Two pixels at 4/255. Rounding.

### What the diff cannot tell us

The pivot question in `docs/BLOCKED.md` predicted that a P1 diff could not
distinguish "anchor scale to the declared pivot" from "anchor to half the
texture", because both renderers use the declared pivot. That prediction held:
the port and the CLI agree on every scaled element, and that agreement is **not
evidence** about which anchor the game uses. It stays open.

### ~~`pteff05.t32` and `pteff04.t32` have no sprite, and that is correct~~

**RETRACTED 2026-08-29. This was wrong, and it was the most consequential thing
on this page.** See "The menu had no background" below.

---

## P2 — keyframe animation, 2026-08-28

### The time unit is authored, in one file, and says loudly that it is not on the disc

`authored/timing.json`. HANDOFF Q1 is answered — linear ramp, 2 units per
rendered frame, 1 unit = 1/60 s — but that conversion is **measured off the
running game**, not read from a file, which is exactly the case the
derived/authored split exists for. It is expressed as
`keyframe_units_per_second: 60` rather than seconds-per-unit so the value is
exact instead of a repeating decimal, and it carries the two independent lines
that support it. `t` stays raw everywhere in `export/`; seconds appear only
where this file is applied, which is one line of `boot.gd`.

`exit_ramp_seconds` is deliberately **null**. See below.

### The timeline stops at the last *timed* keyframe, and never plays the exit

The last keyframe of every group carries **no `t`** — the disc has no time slot
there. Across this export that final frame is an *exit* pose: for 116 of 134
elements it differs from the last timed keyframe **in alpha only** (a fade-out),
for 12 it is the loading splash's scale-and-slide exit, and for 6 it is
identical (no exit animation at all).

So the group is `pre-roll → ramp in → hold → [exit]`, and the port plays it up to
the hold and stops. Playing into the exit would mean **inventing how long the
ramp takes**, because the disc does not say. That duration is the screen
transition — HANDOFF Q7 measured it at ~0.4 s — and it belongs to P3, with its
own evidence. This is why `exit_ramp_seconds` is null rather than 0.4: P2 has no
business holding it.

### The interpolation is checked by where it lands, not by inspection

For **8 of the 12** screens the settled timeline is **byte-identical** to the
`--pose=rest` render. That is the useful assertion: the port walks the keyframes
with an authored time unit and arrives, to the pixel, at the pose the pinned
decoders independently identify as the resting one. `tools/screen-strip` reports
this per screen, so a change to the interpolation that drifts by one unit shows
up as a diff rather than as nothing.

The four that differ do so for two distinct reasons, below.

## `rest` misidentifies six elements, and the running game says so

On `main_menu`, the settled timeline and `rest` differ in exactly one region:
**400×470 at (440,108)** — the bounding box of `ptframe1` and `ptframe2`, and
nothing else on the screen.

`rest` puts both at their **first** keyframe: off-position and fully
transparent. The keyframes say they slide (620,108)→(440,108) and (403,267)→
(583,267) while fading 0x00→0xff, and then hold that pose for their last three
keyframes including the untimed one.

`/reborn/docs/re/captures/main-menu-oracle.png`, a capture of the running game,
**shows them**: the bright circuit-frame bracket around the menu, with a ring at
the bottom right. Cropping the same 250×180 region from the capture and from
both renders puts the ring and its elbow trace in the port's timeline render
**pixel-aligned with the game's**, and absent from the `rest` render. That is
geometry, not luminance, so it does not depend on the capture's gamma or on the
fact that it was taken with `NEW GAME` focused.

### Why the decoders get it wrong, precisely

`ui_layout::rest_plateau` excludes a run of identical keyframes that **ends the
group**, because that run is normally the exit — the comment cites the pause
menu, where taking the trailing run erased the word PAUSE. That exclusion is
right in general and wrong for an element with **no exit animation**, where the
trailing run *is* the hold. The rule then falls back to an earlier run, which
for a slide-in is the invisible pre-roll.

The condition that identifies the affected elements exactly, with no false
positives in this export, is:

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

Six elements match it and `rest` misses all six: `ptframe1`/`ptframe2` on
`main_menu` and `main_menu_jp`, and `pteff02` on `title` and `title_jp`. This is
a **finding for the RE agent** about `sylpheed-formats`, not something this port
fixes: the decoders are pinned and must not be reimplemented here. The port
simply does not use `rest` — it derives the arrived pose from the keyframes,
which needs no heuristic — and `verify-screen` still asks for `--pose=rest` so
that renderer-vs-renderer diffing compares like with like.

Note what this says about P1: the port and the reference renderer **agreed** on
`main_menu` to 3/255, and both were missing two elements the game draws. Two
renderers reading the same field through the same decoder agreeing is not
evidence that the field is right. `docs/BLOCKED.md` had already said that about
the pivot; here it bit for real.

## The title is not settled, and P2 does not claim it

`title` and `title_jp` differ between the two modes by much more (max 142 and
247), and there the disagreement is **not** the six-element bug alone. `rest`
picks a mid-timeline hold for several glows (`pteff01`, `ptlogoall_eff`,
`ptlogoall_eff2`, `ptlogo_back2eff5`) where the timeline runs on to a much
brighter pose.

I could not settle which is right, and did not try to make the numbers agree:

* No element's alpha ever reverses direction anywhere in this export, so the
  title's 4.48 s timeline is a slow one-way ramp, not a pulse — which removes the
  obvious reason to expect a loop, but does not prove there is none.
* The only live title capture composites the **`PRESS Ⓐ` plate (build 2) over
  the title (build 4)**, so it cannot be diffed against build 4 alone. Mean
  luminance is oracle 64.1, `rest` 62.8, timeline 80.0 — which looks like it
  favours `rest`, except that the plate *adds* brightness and `rest` is carrying
  a 25 % black dim quad (`pteff02`) that is itself one of the six misidentified
  elements. The comparison is confounded in both directions and settles nothing.
* **Both modes are visibly wrong anyway.** Side by side with the capture, the
  port draws a washed-out cyan glow slab across the logo that the running game
  does not have — in `rest` mode too. That is a third problem, independent of
  this one, and it is P3's.

So: the timeline is the default because it is derived from the disc's own
keyframes with one measured constant and no heuristic, and because it is proven
right on the screen this milestone gates. On the title it is **unverified**, and
P3 should not assume P2 settled it.

---

## P2, corrected — the pin moved, and the settle rule was wrong, 2026-08-28

### Answering the RE agent's question: which six, and on what screens

They asked, having found only two elements on the English main menu satisfying
the condition this port proposed. The six span the whole 12-screen export:

| element | screens | trailing run |
|---|---|---|
| `ptframe1`, `ptframe2` | `main_menu`, `main_menu_jp` | alpha `0xff` — **visible** |
| `pteff02` | `title`, `title_jp` | alpha `0x00` — **transparent** |

So four of the six are the pair they already found, once per language build, and
their alpha rule accepts exactly those. The other two are `pteff02`, whose
trailing run is transparent, so their rule **excludes** it and leaves `rest` at
`0x40`.

**That exclusion is right, and their own measurement proves it.** `pteff02` is
the 25 % dim quad; they measured the title render going from **+13.14 to +0.55**
against the plate-free capture once the dim is drawn. `rest` must therefore stay
at `0x40` and must *not* move to the transparent trailing run — which is what
their rule does. Two investigations converging from opposite directions.

The condition this port proposed was **too loose**; the alpha discriminator is
the correct rule and the port has no amendment to offer.

### The pin moved 8b6dbcf → 5414db3

Its own commit, and what I wanted from it is the fixed `ui_layout::rest()`.
Pinned at `5414db3` rather than `4bc9706` where the fix was written, because
`5414db3` is where it carries its disc-wide check — 30 of 13 991 elements move,
4 become visible, **0 become invisible**.

The re-export is the evidence the change was contained: **two files changed, and
within them exactly four `rest` blocks** — `ptframe1`/`ptframe2` on both main
menus moving from `(620,108)/(403,267)` at `t=16` and alpha `0x00` to
`(440,108)/(583,267)` at `t=62` and alpha `0xff`. Every diff line pairs; the
other ten screens are byte-identical, `pteff02` did not move, and no sprite
changed.

### The settle rule was wrong, and their title finding is what showed it

P2 shipped "hold the last **timed** keyframe", on the reasoning that the exit is
the final untimed frame. **That is wrong**, and the title is the counter-example:
`pteff02` holds at `t=46` with the dim at alpha `0x40` and then ramps to `0x00`
by `t=236`. The exit is not only the untimed frame — it can be a long run of
timed ones. Running to the end drops the dim and makes the whole screen ~13/255
too bright, which is exactly the luminance excess P2 recorded (oracle 64.1,
`rest` 62.8, timeline 80.0) and could not explain.

A group is `pre-roll → ramp in → hold → ramp out → post-roll`, and a screen that
has arrived sits on **the hold**. So the timeline now plays in and stops at
`rest`, which is the decoders' identification of that hold and carries its own
`t`. `settle_units()` is `rest.t`.

The check is that the disagreement vanishes: on **all twelve** screens the
settled timeline is now byte-identical to the `--pose=rest` render, where before
this change four of them differed by up to 247/255. The timeline's endpoint
*should* be `rest` — the animation is what the timeline adds, not a different
destination — so this is the property to want, and it now holds without a
special case.

That also retires P2's open question about looping, from the other side: the RE
agent measured that groups hold rather than loop (`ptloop01`/`ptloop02` park
off-screen at x=1521 and x=−839; 18 s of settled title sits at sd ≤ 0.01).

## The reference renderer was stale for three diff runs

Worth recording as a process failure, because it defeated the project's whole
verification method for a while and it failed *silently*.

After bumping the pin I rebuilt the reference CLI, and `build-reference-cli`
reported success at rev `5414db3`. `verify-screen` then showed `main_menu`
jumping from 3/255 to **72/255**. The natural reading — the port had regressed —
was wrong. The port was right and **the reference was a revision behind**: the
shared `CARGO_TARGET_DIR` still held a `sylpheed-cli` built from `8b6dbcf`, and
cargo reported `Finished in 0.13s` and left it in place. Building into a clean
target directory produced a binary that resolves `ptframe1` to `(440,108) t=62`;
the shared one still said `(620,108) t=16`.

The old check — "does `screen list` run?" — cannot catch this, because a stale
binary runs perfectly.

Two changes:

* `build-reference-cli` builds into `$CARGO_TARGET_DIR/reference-cli/$rev`, a
  tree **keyed by the pinned revision**, so a new pin has no artifacts to reuse.
  A stable copy is placed alongside for consumers.
* It then checks the binary **against `export/`**: both come from the same pin,
  so if the CLI resolves `ptframe1`'s rest differently from what the exporter
  wrote, the two halves of the verification are not the same revision and it
  fails loudly. It compares the two rather than asserting a literal, so it stays
  true when the pin moves again.

`docker/bin/` is baked into the image, so this takes effect on the next image
build; until then the repo copy has to be invoked by path. The RE agent hit the
same class of trap this session from the other side (`./target/debug` stale
against a redirected `CARGO_TARGET_DIR`). It is worth naming the general shape:
**a build system reporting success is not evidence that the artifact you are
about to trust is the code you pinned.**

### What this did not change

`title` (6/255), `extras` (4/255) and `title_jp` (154/255) are unchanged, and
their diagnoses stand — a paint-order tie, two pixels, and nearest-neighbour
sampling phase at 125 % scale. The title's swoosh defect the RE agent localised
(drawn thick and white where the game draws it thin and pink) is untouched by
any of this and remains P3's.

---

## The menu had no background, and P1 called that correct, 2026-08-29

The pin moved `5414db3 → f817dd5` for `56cc7ac`, "a RATC child's name is stated,
not inferred". `ratc::parse` had named each child by scanning backwards for the
last printable run of bytes before its magic. For `pteff05.t32` the three
trailing payload bytes are `38 41 58` — `8AX` — which beat the real name, so the
child registered under a name no element declares and resolved to no sprite.

`pteff05.t32` is the **full-resolution background of all five menu screens**.

So every render this port has produced of a menu screen has been missing its
background, and P1 wrote that up as a property of the disc: *"the bundle declares
them and carries zero RATC children for either, so there is no texture on the
disc to export."* That sentence was false. The bundle carries the child; the
decoder was handing back the wrong name for it. Retracted above rather than
edited away.

### What the re-export shows

Six new sprites and nothing else: `pteff05.png` on `main_menu`, `extras` and
their Japanese twins, `pteff04.png` on both titles. Per screen the JSON gains a
`sprite` line and `layer_source` moves `"implied" → "sprite"` — the layer key is
now **read from the file** instead of taken from the decoders' table of keys
measured off the running game. That is the derived/authored ratchet turning the
right way, in the exporter rather than in `authored/`.

`pteff05.png` is **1280×720**; `ptbase.png`, which had been carrying the
background alone, is 640×360 drawn at 200 %. The screen was being shown its own
art at half resolution.

### Measured against the live capture, not against the other renderer

Whole-frame RMSE of the settled `main_menu` against
`captures/main-menu-oracle.png`:

| | RMSE |
|---|---|
| before this pin | 8.05 % |
| with the real background | **5.92 %** |

A 26 % reduction, and it is the right kind of evidence: the reference renderer
was missing the same element for the same reason, so a renderer-vs-renderer diff
could not have found this. It is the third time on this project that the
capture caught something both renderers agreed on — the bracket, the title dim
quad, and now the background.

`verify-screen` after the bump is unchanged in character: everything at 3–4/255
except `title` (6, the paint-order tie) and `title_jp` (155, the sampling phase).
Both renderers gained the background together.

### One thing the comparison says that I did not expect

Rendering with `--focus=ptbtn01`, which is how the capture was taken, makes the
RMSE **worse** — 5.92 % → 7.00 %. The port *replaces* an element's sprite with
its `*f` twin; `sylpheed-cli`'s own `--focus` is documented as drawing the
focused record **over** the base element. Those are different operations, and
the capture shows a ring marker beside `NEW GAME` that the port does not draw.

This is P5's, not P2's, and it is not being guessed at here. Raised in
`docs/BLOCKED.md`.

---

## P3 — splash → title, unattended, 2026-08-29

### The splash is located by entry index, because no rule can find it

The RE agent looked for a content predicate and there is none: design size fails
(every extra composable bundle sampled is 1280×720, the same as every screen) and
element count fails (fragments run 2…15 elements in `GP_OPTIONS`/`GP_SAVE_LOAD`
while the splash halves are 3 and 7 — the ranges overlap).

So `screen_builds` is now `is_build` **plus an authored allow-list of entry
indices**, in `authored/screen_names.json` under `also_export`, each with a `why`
that says it is a locator and not a claim. This is safe in `GP_TITLE` and would
not be in general: there, widening adds exactly four bundles and all four are
real screens with zero fragments. That is why it is an allow-list rather than a
loosened predicate.

**There were two splash screens and the port had neither.** Entries 11/14 are the
developer logos (GAME ARTS / SETA / studio anima); entries **10/13 are the SQUARE
ENIX publisher wordmark, the first thing the boot shows**, and nothing in this
project had noticed them. Both pairs are region twins — ™ on 10, ® on 13 — and
the port shows one of each, not both.

### `authored/screen_names.json` is now keyed by pak entry, not by ordinal

Widening the enumeration renumbers the ordinals, and a name that moves when the
enumeration rule changes is not a name. The file had always called the entry
"the stronger locator"; it is now the only stable one. In `GP_TITLE` the two
coincide across all 16 entries, which is also the numbering `sylpheed-cli screen
--build N --all` takes — so `verify-screen` now passes `--all`, and without it
`--build 10` would have landed on entry 12.

The two previously-unnamed plates therefore renamed `build_10`/`build_11` →
`build_12`/`build_15`. Their names were always locators; now they locate the
right thing.

### The exit is the group playing itself out, not a black rect over a freeze

HANDOFF's answer to ask 2 was (a), and it came with a test that discriminates
rather than a plausibility argument. Under "a black quad over a frozen screen"
every region is scaled by the same 1−α, so the button-region / background-region
brightness **ratio** stays constant through the fade. Measured, it falls
6.495 → 5.574 → 3.105 → 2.125 → 1.935 — a 3.4× monotonic drop. The screen plays
out: `pteff00.prm` ramps to opaque black while the labels, `ptmsg`, `pteff10`
and `pteff12` ramp to transparent, and `ptframe1`/`ptframe2` hold.

Implemented by giving the final untimed keyframe a **synthetic time**,
`exit_ramp_units` after the last timed one, and then interpolating it like any
other. One code path: the difference between arriving and leaving is only how far
`t` is allowed to run, not a second kind of animation.

`exit_ramp_units = 24` (~0.4 s) is authored, and `authored/timing.json` carries
the RE agent's own reach caveat rather than smoothing it: the filmstrip is
downsampled and the button region contains some background, so this pins the
**direction**, not 0.4 s to ±0.05 s, and it is one transition pair.

### Nothing waits on a timer the disc does not carry

`dwell` in `authored/flow.json` is deliberately empty. Each screen's dwell is its
own keyframe group — the publisher wordmark reaches its hold at t=235 (3.92 s),
the developer logos at t=190 (3.17 s), both read from the disc. Adding a hold on
top would be inventing a number nobody measured. The pacing you see is the
disc's own, and the file says where a measured number would go.

### The last screen holds

A screen plays itself out because something is taking its place. Nothing takes
the title's place yet, so the sequencer holds there. A boot that ends by fading
to black is a boot that looks like it crashed. P4 puts the intro video in front
of the title and P5 gives the title somewhere to go.

### `flow.json` reproduces an observation and says so

Q6 closed with a negative: the order is in none of the four places it could have
been, and a transition is a call with a name argument chosen by code. So this
file is authored and its header says plainly that it reproduces what was watched,
not what any file states. The intro video's place in the real boot is **named as
a gap** rather than the order being quietly rewritten to hide it.

## P3 gate

`godot --path port -- --boot --film=/tmp/boot` runs unattended:

```
publisher_logo  →  developer_logos at 4.65 s  →  title at 8.57 s
boot sequence complete after 13.05 s, holding on title
```

The filmstrip shows each screen fading in, holding, and fading through black into
the next, and the title staying up. `verify-screen` covers all **16** screens
now; the four new splash bundles come in at max 1–2/255 against the reference
renderer. The three known differences are unchanged: `title` 6 (paint-order tie),
`main_menu` 4, `title_jp` 155 (sampling phase at 125 % scale).

## Answers taken from the RE agent without re-deriving them

* **Focus stays "replace".** Over-vs-instead is unobservable: the focused sprite
  covers the base at 100 % of base-visible pixels, and the two compositions
  differ by RMSE 1.1 inside the button rect — under the gamma floor. The port's
  guess was right for the wrong reason, and the actual gap is that
  `ptbtn0Nf.rat` declares **two** sprites — `ptbtneff01.t32`, a glowing ring, and
  then the bright label — where `ptbtn0N.rat` declares one. The ring is P5's, and
  its placement inside the record is **not decoded**, so it will be authored from
  the capture and marked as such.
* **RMSE against captures has a floor, so stop chasing it.** The capture is
  `≈ 255·(render/255)^γ` with γ ≈ 1.49 on the menu and `EXTRAS`, 1.34 on the
  title, and it is a ramp *the game installed* (`VdGetCurrentDisplayGamma` at
  video init), not a capture-path artefact to subtract. Its reach is narrow —
  the flat patches it was fitted on are almost all dark — so the port will not
  extrapolate it across the range, and will not apply it to rendered output on
  this evidence. It is a comparison constant, not a rendering one.
* **Rotation is escalated to a human and the port has not acted.** The RE half is
  answered — rotate about the **declared pivot**, measured against the GPU
  capture — and it has zero effect on the five screens at rest. The port will
  carry `rotation_deg` in a future FORMAT v3 because carrying a decoded field the
  renderer ignores beats dropping it, but it will not draw it until the
  divergence question is settled.

---

## P4 — the intro video, 2026-08-29

### Theora at 720p is fine here, and no runtime dependency is requested

MISSION §6 anticipated that Theora might be too poor at 720p and permitted the
FFmpeg-GDExtension fallback to be **proposed**. It is not needed, and this was
measured rather than judged by eye alone. SSIM against the decoded source over a
10 s sample: **0.9863 at `-q:v 6`, 0.9896 at 8, 0.9924 at 10**. At 200 % zoom on
the reel's hardest case — fine serif text and soft gradients over near-black,
where Theora breaks first — q8 is indistinguishable from the source.

`-q:v 8`, and **no GDExtension is being proposed or adopted**.

`-ac 2` because the source is **6-channel** WMA Pro and Godot's Theora path is
not a surround one. That downmix is a decision, so it lives in the recorded
command where a modder can see and change it rather than in prose.

### The exact command is in the manifest, per MISSION §6

`export/manifest.json` gains a `videos` array, each entry carrying the verbatim
`ffmpeg` line that produced it. A modder who dislikes the quality re-runs one
line instead of reverse-engineering what was done to their video — which is the
whole reason this project converts the disc rather than reading it at runtime.

### A cache, and why that is not a hand-edit

`export/` is regenerated wholesale, but re-encoding 232 s of video on every run
costs ~4 minutes to produce a byte-identical file, and an exporter nobody re-runs
is worse than a cache. So each movie gets a `.cmd` sidecar recording the command
and the source size, and the encode is skipped only when both match exactly. Any
change to either re-encodes. This is derived state validating derived state, not
a hand-edit.

### The player renders into the design viewport, not beside it

First attempt parented the `VideoStreamPlayer` to the Boot node. It played, and
every captured frame was **black**: the capture reads the SubViewport, and the
player was rendering to the window. Worth stating as more than a capture bug —
everything this port draws composes in the export's own 1280×720 design space,
and a movie outside that space is outside the coordinate system every screen is
expressed in.

### Ⓐ skips, because Q9 measured it

The only input the port handles so far. HANDOFF Q9: one Ⓐ press skips a movie,
measured — the title was reached at 57 s against a 193 s baseline. Menu
navigation is still P5.

## P4 gate

`godot --path port -- --boot --film=…` runs
`publisher_logo → developer_logos → ADV.ogv → title`, unattended. The filmstrip
shows the SQUARE ENIX ident, then the reel's live-action-styled CG, then the
title. The movie's place in the boot is **measured, not decoded** — Q9 decodes
`ADVERTISE_MOVIE → ADV.wmv` from the movie manifest, but *where it sits in the
boot order* is what the RE agent watched, and `authored/flow.json` says so.

### What I cannot verify from here

**Audible playback.** This container has no audio device — Godot falls back to
the dummy driver. What is verified is that the Vorbis stream exists in the
transcode, is 2-channel, and decodes. Whether Godot emits it audibly is
unconfirmed and is stated as unconfirmed rather than assumed from the stream's
presence. It is a cheap check for anyone with a sound device and an impossible
one here.

---

## RETRACTION — `sylpheed-cli` is not the oracle, 2026-08-29

**This corrects a framing that runs through everything above, so it is a
retraction rather than an edit.** Every place this file called
`sylpheed-cli screen render` *"the reference renderer"* — and it does so
repeatedly, starting at P1 — overstated what it is.

The correction comes from the human, via the RE agent, in their words: Reborn
"was/is just a GUI explorer and extraction CLI for verifying the decoding of the
various files. It may very well be wrong." **The oracle is the Xenia Canary
capture and the game.**

So `tools/verify-screen` is a **consistency check between two decoders that
share their assumptions**, and a regression detector. It is not a correctness
check, and agreement in it is not evidence of correctness.

### The embarrassing part is that this file already knew

After the `ptframe1` case, P2's write-up says: *"Two renderers reading one field
through one decoder agreeing is not evidence that the field is right."* Then P1's
numbers kept being quoted as though 3/255 against `sylpheed-cli` meant the port
was right. Having the principle written down did not stop me leaning on the
agreement — which is worth recording, because that is the failure mode, not
ignorance of the principle.

**Three times** both renderers agreed and both were wrong, all three caught by a
capture and catchable by nothing else:

| | what both got wrong | how it surfaced |
|---|---|---|
| `pteff05` | the menu screens had **no background** | the RE agent decoded the RATC child name |
| scale 0 | drawn at full size instead of collapsed | RE agent's control run |
| `rest()` | `ptframe1`/`ptframe2` invisible; the menu bracket missing | `main-menu-oracle.png` |

### What changes

* `tools/verify-screen` says all of this in its own header, calls the CLI the
  **comparison** renderer, and a `DIFFERS` row now means "we moved apart, find
  out which of us moved" rather than "the port is wrong".
* The correctness question moves to the captures. The RE agent has committed
  nine of them with an index at `docs/re/captures/ORACLE-CAPTURES.md`, covering
  all five screens in scope — including a **main menu with `OPTIONS` focused**,
  whose difference from the unfocused menu isolates exactly what focus changes.
* Three cautions travel with any capture comparison, and they are the RE agent's:
  the captures are **not gamma-neutral** (γ ≈ 1.49 menu, 1.34 title — there is a
  floor, do not chase it); **geometry is sound** (best alignment 0,0 at corr
  0.9466, so a positional disagreement is real); and each is **one moment of a
  still-animating screen**, so compare settled poses or regions known to be at
  rest.

### What does not change

The port keeps running `verify-screen` over all 16 screens every iteration. A
consistency check is still worth having — it is total, it is cheap, and it is
what catches a divergence the RE agent introduces on their side. It is simply
not a grade, and this file will stop quoting it as one.