# Page performance

> What the page editor loads, in the four phases a load is measured in, what waits until first use, and the practices you can reuse in your own documents.

Source: https://clayjs.com/docs/page-performance/

The page editor is built for documents that grow: an article typed in a browser, saved as a file, merged with a peer's copy of it. This page says what its load costs in each phase it is measured in, what waits until it is first used, what keeps a long document responsive, and which of those practices transfer to a document you write yourself.

## A load is four phases, not one

| Phase | What it measures |
|---|---|
| View ready | what a reader downloads before the article is on screen |
| Edit ready | what the editor adds after the person enters editing |
| Automatic late work | what is loaded with no action from the person |
| First use | what the first save, the first incoming merge and the first use of a feature each cost |

Every phase is bytes over the wire, so each one is a number you can compare with the same number before a change. Moving bytes from edit ready to automatic late work does not count as loading on demand: the session still downloads them, and nobody did anything to ask for them.

## The ceilings

Brotli over the wire, a reader page is at most 45 KiB, the text editor is at most 340 KiB (348,160 bytes), the editor also carries a stretch target of 260 KiB, which a report says was reached or not, and a boot may chain at most 3 levels of module requests.

Measured on ClayJS main on 2026-10-28 for the text fixture: the reader page is 44.5 KB and the editor is 324.1 KB, both under their ceilings.

## What waits for first use

- The source map and its HTML parser (parse5) load on the first save that needs them.
- The merge engine is not imported when an incoming receipt is unchanged and has no tags.
- Optional editor commands load when first invoked: mentions, dates, emoji, toggle headings, table of contents, icon and cover, Markdown import and export, and the reading copy.

None of these is part of edit ready, so a person who opens a page and types one sentence does not download them.

## Long documents

Hover and drag read geometry once per animation frame, and reuse an outline cached by the document's identity.

Typing in a 2,000 block document has a median under 16 ms, about 10 ms measured, and still about 5 ms after 100 block deletes and 300 backspaces. A keystroke that only changed text inside one block re-reads that block alone and splices it into the previous walk, keeping the ProseMirror nodes of every untouched block. Anything else, a new block, a move, an attribute, a recovery record, or text next to a removed block's region, walks the whole document as before.

Transport entries are retired only after a checkpoint is confirmed to cover them exactly, and long session caches keep only live references, with caps.

## Measure readiness, automatic late work and first use separately

A single total hides the thing you are about to break. A change that moves code out of a reader path shows up in the view ready number, and a feature that loads on import shows up in edit ready rather than in the first use row where its cost belongs. Report one line per phase, from a report that names the build it measured, so a later comparison is against the same fixture and the same release.

```sh
npm run build && node scripts/measure-load.mjs --built "$PWD/dist" tests/fixtures/load/document-text.html --json > report.json
CLAY_LOAD_REPORT=report.json npm test -- tests/unit/page/load-budgets.test.js
```

The first command writes the report and the second checks the ceilings against it. Keep the report beside the change that produced it: a number with no build behind it cannot be compared with anything.

## Prove first use at the moment of the trigger

A check that runs at a ready event, or one animation frame after it, says nothing about what the trigger loads. It passes whether the module is deferred or already downloaded. Look at the moment the person acts: the first save that needs the parser, the first incoming receipt that carries tags, the first opening of a picker. Then a failure means what you think it means.

## Cache derived layout by an immutable document identity, and read geometry once per frame

An outline, a set of heading anchors or an index of blocks is derived from the document, so it changes when the document changes and only then. Key it on an identity that cannot change under it, so an unchanged document reuses the answer instead of walking itself again. Read layout in the same frame that asks for it, once, because reading geometry after a write forces the browser to lay the page out twice.

## Retire inputs only after their exact coverage is confirmed

Deleting a message, a queued edit or a transport entry because a later one probably covers it loses the changes that fall between them. Retire an input when the thing that supersedes it is confirmed to cover exactly that input, and keep only live references in a cache that lives as long as the session, with a cap, so a long session does not hold every document it has ever seen.

## Skip work only when you can prove it would change nothing

The saving is real, but only if the proof is. Skip a render, a repair or a save when a check says the result would be identical, and make that check recompute what it is comparing: a cached answer that agrees with a cached answer proves nothing. A keystroke that reuses the document walk and finds no change costs one walk and nothing else, and typing stays inside a frame.

An incremental projection gets the same treatment. The page editor's one-block re-read has a test switch that recomputes the full walk beside every incremental one and compares the two, including the bookkeeping the next keystroke reads (hidden regions, holes, the positions of moved copies). Run long sessions and the fuzz tests with that switch on. Short unit cases miss the drift: the moved-copy positions only came out wrong after 1,550 operations.
