# Rows without Python: findings and proposal (2026-11-01)

Trigger: Standa, marking one episode reloaded every row of the page, Filmy waits, Pro tebe is slow after an update.
Built 2026-11-01. Tools: `scripts/skin_harness/ux/`.

Measured on the Mac with Kodi duty-cycled to 1/5 of its CPU (`ux/throttle.py 5`). A stand-in, not the real TV.

| Scenario | Before | Built |
|---|---|---|
| After an update: Pro tebe | first row 10.5 to 15 s | all rows at 4.2 s |
| After an update: Filmy, key to first row | 10.4 to 11.4 s | 0 s, loaded before the key |
| After an update: CPU until quiet | 25 to 26 s | 11.6 s |
| Kodi start: Pro tebe | first row 7.5 s, all rows 10.1 s | all rows at 4.1 to 5.2 s |
| Kodi start: Filmy right after the first screen | 2.7 s | 0 s, loaded before the key |
| Detail: rows after the hero | 2.8 s | 0.25 s; opened again 0.5 s at 1x |
| Mark one episode | 11 rows rebuilt over 18 s, page changes up to 10 s later | the card, other rows untouched |
| Calls into Kodi from Python at idle Home | about 500 per second | about 60 per second |

First start of this version, no row file yet (one time only): Pro tebe's first row 2 s after Home, a switch to Filmy
1.7 s, because every row asks again where the user is (`journal._sweep`).

Idle Home at 1x: 9 to 12 % of a core from run to run, plain Estuary 3.8 % on the same machine. The difference is Kodi
evaluating the visible cards' conditions every frame (about 4 %); Python is below 2 %. Thinning the cards' conditions
and the service's polls further moved nothing beyond that noise.

A settings file written while another thread loads it logs `failed to load addon settings`: a start now writes
`webshare_vip_info` only when it changed, and three starts in a row logged it no more.

## Causes

1. **Every row call starts its own Python.** All 16 row calls logged at each speed had `reused=False`: Kodi reuses
   only an idle interpreter and rows are asked for in parallel. At 5x one row costs about 1.2 s, the data about 0.2 s.
2. **One change reloads everything.** `refresh.media_rows` marks every row of a media type, the revision goes into
   the URL even when the row's cards did not change, and 2.1.112 added it to all detail rows (cast too).
3. **A row file is tied to the revision, its parameters and the code.** New data or parameters build the row at once. After
   an update (`main.py` mtime, the file's `code`) the row keeps working: every row with a file is ready for the skin before
   anything is built, and `journal._settle` rebuilds older rows one at a time between key presses, with a pause as long as
   the build, never waiting more than 30 s per row. A row with no file is built first.
4. **Idle work holds the Python lock:** about 500 Kodi calls per second at idle Home. `journal.run` parses the JSON of
   every row every 3 s; `hero_source` polls at 10 Hz, `perflog` at 20 Hz, the tracker at 2 Hz. `getCondVisibility`
   waits for the GUI lock (up to 42 ms here).
5. **Cards are heavy:** 76 calls per card, 1542 per row, 160 KB per row; many properties are written twice.
6. **Rejected:** rows called one after another (a chain of gates). Calls got cheaper but the total hardly moved.

## What was built

Only the cinematic sections: mycinema, ai, kraska and tmdb use Estuary's own cards, which read art and watch state from
the item, so they stay plugin lists (`hero_contract.PLUGIN_SECTIONS`, `gen_slots.PLUGIN_CONTENT`).

A row is a file Kodi reads itself, with no Python: `rows/<sec>.<slot>.m3u`, `#EXTINF` for the label and
`#KODIPROP:key=value` for every property Verified: every property reaches the card and hero, click,
context menu, a rewrite of the file with a new name keeps the focus and shows no blank frame (the focus ring drops
for one frame at 5x).

1. **Show first, check later.** The skin always points at the last file, also after an update. The service rebuilds
   in the background and changes a row only when its content hash differs.
2. **Only what changed.** An index key -> rows; an action rewrites just that card in those files, at once. Rows whose
   membership can change (Continue, next episodes) are rebuilt in the background, the row on screen stays stable.
3. **Revisions in Home properties**, not `Skin.SetString`, with the base file always current for the next start.
4. **Detail and genre page** use the same files; only their own rows change.
5. **No polling at idle:** journal scan by revision, hero from the skin's own focus events, tracker on player events,
   `perflog` removed.
6. **Webshare results cached** per title (today every play searches again); TMDb always served stale first.

## Kodi's limits

- A playlist of one item is no directory: such a row holds the card twice and the list's `limit` shows one. The skin
  knows the class from `Skin.String(mil.<sec>.<n>.cards)` (0, 1, 99), written only when it changes.
- A line has a 4096 byte buffer and a longer one breaks the file: `rowfiles.LINE_LIMIT`, longer values are left out and
  logged; the game's URL keeps a short plot.
- A file path cannot carry a revision (`|`, `?`, `#` and `dir/../` all fail): a new name is a copy of the file.
- Items have no `Playcount`, resume or art: cards read properties.
- Kodi parses an item's path for every label of every frame: the path in the file is short, and unique, because a
  reloaded list keeps its focus by the path.
- A hidden list never reloads: a row that knows it has cards stays visible (`known_items`).
- `Integer.IsGreaterOrEqual` does not read a Window property: conditions compare text.
