Layout never settles when the vertical scroll bar decides whether content overflows (re-layout on every frame)

Open
#6,785 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
53/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Active
Tech stack
python
Domain
frontend

Research direction

Start by running the supplied minimal reproduction with app.run_test(size=(18, 5)); it instruments Screen._refresh_layout and shows the alternating scrollbar and widget-height states. Read Screen._refresh_layout and the layout/scrollbar behavior it invokes to understand why the screen keeps relaying out. Done means the layout settles for this case, idle layout counts stop increasing, and pilot.pause() can reach idle.

Written by the indexing model from the issue text.

Description

Hi! I hit this while writing generated tests against Textual's widgets. Some small layouts never settle. Showing the screen's vertical scroll bar takes 2 cells, which makes a percentage-width widget too narrow to have any text, so it's 0 rows tall, so nothing overflows, so the bar goes, and then the text wraps again and overflows. Textual re-lays the screen out on every update tick, indefinitely, and the widget alternates between the two states. This looks like the same kind of loop as #4141, which #4315 fixed, but this case still loops on main.

import asyncio
import time

import textual
from textual.app import App, ComposeResult
from textual.screen import Screen
from textual.widgets import Static

class FlipApp(App):
    CSS = """
    Static { width: 50%; padding: 0 4; }
    """

    def compose(self) -> ComposeResult:
        yield Static("abcdef")

async def main() -> None:
    layouts = 0
    states = []
    original = Screen._refresh_layout

    def counting_refresh_layout(self, *args, **kwargs):
        nonlocal layouts
        layouts += 1
        result = original(self, *args, **kwargs)
        if self.is_attached and self.query(Static):
            states.append((self.show_vertical_scrollbar, self.query_one(Static).size.height))
        return result

    Screen._refresh_layout = counting_refresh_layout

    app = FlipApp()
    async with app.run_test(size=(18, 5)) as pilot:
        await pilot.pause(0.2)
        states.clear()
        layouts = 0
        await asyncio.sleep(1)
        in_one_second = layouts
        start = time.monotonic()
        await pilot.pause()
        pause_took = time.monotonic() - start
    print(f"Textual {textual.__version__}")
    print("(screen scroll bar shown, Static height) after the first 6 layouts:", states[:6])
    print("screen layouts in one idle second:", in_one_second)
    print(f"pilot.pause() took {pause_took:.2f} s")

asyncio.run(main())

Output on main (5e5b7ef), Python 3.13, macOS:

Textual 8.2.8
(screen scroll bar shown, Static height) after the first 6 layouts: [(False, 0), (True, 6), (False, 0), (True, 6), (False, 0), (True, 6)]
screen layouts in one idle second: 57
pilot.pause() took 1.02 s

On 8.2.7 it's the same: the same alternation, 51 layouts in the idle second. pilot.pause() took 0.12 s in that run, so the time it takes varies.

What users see:

  • the widget flickers between two layouts, and the app uses CPU while idle;
  • which layout a given frame shows depends on the clock;
  • in tests, pilot.pause() (through wait_for_idle) can wait up to its max_sleep of 1 second, because the app is never idle.

I expected the layout to settle in one of the two states, for example by keeping the scroll bar once it has been shown for a layout that would otherwise loop. Adding Screen { scrollbar-gutter: stable; } to the CSS above avoids it: 0 layouts in the idle second, and pilot.pause() takes 0.02 s. I don't know the layout code well enough to suggest where to detect the loop, so I'm reporting it with the repro rather than a fix.

Dominant language
Python
Stars
37.7k
Forks
1.5k
PR merge metrics
No merged PRs in 30d

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Textualize/textual

All issues in Textualize/textual

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.