Skip to content

docs: design lazy loading in three levels - #1246

Merged
andiwand merged 3 commits into
mainfrom
docs/lazy-loading
Oct 24, 2026
Merged

andiwand merged 3 commits into
mainfrom
docs/lazy-loading

Conversation

@andiwand

@andiwand andiwand commented Oct 24, 2026 •

Copy link
Copy Markdown
Member

🤖 Generated with Claude Code

Refs #764.

Summary

This adds docs/design/lazy-loading.md, a proposal. The design rests on measurements:

  • The browser fails first. A text file of 1 M lines paints its first frame in headless Chrome after 154 s, with a 6.3 GB renderer. Split into chunks of 256 lines that stay content-visibility: hidden until a script marks them near the viewport, the same DOM paints its first frame in 0.85 s with 0.9 GB. auto alone takes 13.5 s, because Chrome lays out every auto chunk once on the first frame. With only a window of lines in the DOM, the page paints in 0.5 s.
  • Core comes second. efficiency-big-1.ods peaks at 697 MB:

The three levels:

  1. Containment: the view writes chunks that are hidden until a small script marks them near the viewport, with auto as the fallback when no script runs. It works offline, and odr.search, the editor, copy and print see all the content. The find of the browser does not reach a far chunk.
  2. A window: the page keeps a far chunk as a string and splices it back. This works offline too.
  3. On demand: the page asks a host for a chunk, through the HTTP server or a binding callback. Core renders only that chunk.

So most of the work also helps a file that bring_offline writes. Only level 3 needs a server.

The order of work starts with level 1 for text files (#1247): chunks, plus line numbers as a CSS counter instead of the ResizeObserver gutter that doubles the load today.

The second commit corrects the first one's level 1 numbers. The page that I measured first was laid out wrong.

Review fixes

  • The problem section said 151 s, the load time of the first measurement. It now states 154 s, the first frame of the table.
  • The order of work states why each chunk sets the number of its first line: style containment keeps the counter inside the chunk.

andiwand and others added 2 commits October 24, 2026 19:56
The browser fails before core does: a text file of one million lines
takes 151 s to load in Chrome. The same page in chunks with
`content-visibility: auto` loads in 1.5 s, offline and with no script.
The design builds on that:

1. Containment: chunks that the browser does not lay out.
2. A window: the page keeps a far chunk as a string.
3. On demand: core renders a chunk that the host asks for.

Levels 1 and 2 also work in an offline file. Text files go first, because
they need no engine work.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017QtawyvLP2SCnoBtnVfFed
The chunked page that loaded in 1.5 s was laid out wrong. Its gutter
took the 5120 px of `contain-intrinsic-size` as its width, so the text
column was 32 px wide. Measured on a correct page:

- With `content-visibility: auto`, the first frame comes after 13.5 s.
  Chrome lays out each chunk once to find whether it is near.
- A chunk that is `hidden` until a script marks it near paints the
  first frame after 0.85 s.

So level 1 starts each chunk `hidden`. That hides a far chunk from the
find of the browser.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017QtawyvLP2SCnoBtnVfFed
The problem section said 151 s, the load time of the first measurement.
The table states 154 s, the time to the first frame. Also state why each
chunk sets the number of its first line: style containment keeps the
counter inside the chunk.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YHNzLmVv1mFWfPitHASucN
@andiwand
andiwand merged commit d2de150 into main Oct 24, 2026
27 checks passed
@andiwand
andiwand deleted the docs/lazy-loading branch October 24, 2026 18:31
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.

1 participant