Sylpheed-Godot/docs/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

Both renderers skip them. The bundle declares them and carries **zero** RATC
children for either, so there is no texture on the disc to export — this is a
property of the disc, not a gap in the exporter, and `ScreenView` reports it as
`no sprite in the export` rather than dropping it silently.