Skip to content

feat(web): show a page skeleton while the next page loads - #222

Merged
harenome merged 1 commit into
ThinkFlowLab:mainfrom
harenome:feat/page-skeleton
Nov 19, 2026
Merged

harenome merged 1 commit into
ThinkFlowLab:mainfrom
harenome:feat/page-skeleton

Conversation

@harenome

@harenome harenome commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Closes #221

What

page-loading.js, loaded by base.html on every page, watches for a click or a submit that replaces the page in the same tab. After 180 ms, unless another handler called preventDefault, it puts a skeleton at the top of #main-content: a title, a subtitle line, a row of buttons and five row blocks. The page's own content is hidden under main[aria-busy="true"]. A hidden role="status" on body, outside the busy region, says "Loading". The next page replaces all of it.

No skeleton for: a modifier or middle click, a target other than _self, a download link, a hash on the same page, another origin or a non-http link, a method="dialog" form. The skeleton goes on pageshow from the back/forward cache, after a beforeunload prompt, and on Escape. A form's action and target are read with getAttribute, because a field named action shadows form.action.

.skel in style.css is the block: --surface-2 with a slow opacity pulse, still under prefers-reduced-motion. Later lazy loading of cards, table rows or the rail can use it.

Touches

templates and static (base.html, page-loading.js, style.css) · tests (ui_tests/test_page_loading.py)

Before and after

Before, the old page stays as it was until the next one arrives. After, while /benchmarks loads, delayed by 2.5 s in the test:

Light Dark
1280 px skeleton-light-1280 skeleton-dark-1280
390 px skeleton-light-390 skeleton-dark-390

Verified

In a throwaway rootless python:3.12 container with Node.js and uv, on a copy of the branch:

  • python3 app/tests/parallel.py: 2984 tests in 153 modules, OK.
  • pip install -r app/requirements.txt, then python3 app/tests/parallel.py app/ui_tests: 654 tests in 55 modules, OK.
  • test_page_loading.py: Node tests on a small stand-in DOM for which links and forms show the skeleton and what hides it, and a route test that /runs, /benchmarks and /settings load the script.

Browser check, Chromium (Playwright 1.49.1), with the document delayed by route interception: the skeleton shows in light and dark at 1280 and 390 px, and nothing is left after the page arrives. A 10 ms response shows no skeleton. Back and forward leave none. A ctrl-click and a form handled by a script show none. No page JavaScript error.

Not checked in a browser: a page restored from the back/forward cache (Chromium did not cache it under interception; the Node test covers it) and the reduced-motion look.

Risk

  • The browser's Stop button fires no event, so the skeleton stays until the next navigation or Escape. A timeout would hide it on pages that are slow but still loading.
  • A link without download that answers with an attachment or a 204 would leave the skeleton up. No such link exists today.
  • A navigation started by a script (location.href, form.submit()), a reload or a typed address shows no skeleton.
  • A revert removes the script, its line in base.html and the styles.

Slow pages left the old page on screen with no sign a click was taken, so it was clicked again. A same-tab link or form that navigates the document now replaces the main content with a pulsing skeleton after 180 ms; the header and rail stay. Modified, middle, new-tab, download, hash-only and other-origin links, and forms a script handles, do not show it; a page restored from the back-forward cache, a cancelled leave and Escape take it away. The .skel blocks are reusable.
@harenome
harenome merged commit 56da6cf into ThinkFlowLab:main Nov 19, 2026
2 checks passed
@harenome
harenome deleted the feat/page-skeleton branch November 19, 2026 11:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Web: a slow page gives no sign that it is loading

1 participant