@luigisbox/luma 0.0.0-stage → 0.2.0

package/docs/INTEGRATION-PERFORMANCE.md

@@ -0,0 +1,213 @@
+# Integration performance: what to measure, what to optimize
+
+A guideline for integration work (an integration repository with Luma as the
+`@luigisbox/luma` package). Luma's own budgets are
+held by its own test suites. An integration can still undo them with heavy tiles, a
+layout that moves, or a slow install. This page lists the numbers to watch,
+in priority order, and the levers an integration has.
+
+## The metrics, in priority order
+
+| # | Metric | Target | Where to read it |
+|---|---|---|---|
+| 1 | **Time to listing shown** (first tiles painted, from navigation) | Repeat visit ≤ 1.2 s; first visit as low as the API chain allows (below) | `__lbx.health.timeline`, `yarn luma footprint` (`ready`), DevTools Performance |
+| 2 | **Layout shift caused by us** | 0 after ours is shown | `yarn luma footprint`, a `layout-shift` PerformanceObserver, DevTools Performance (Layout shifts track) |
+| 3 | **Longest main-thread task of ours** | ≤ 16 ms of our own code (a frame) at 4x CPU | `yarn luma tasks` (per task, on the storefront, by source line); the `rendered in N frames (a/b/c ms)` mark; DevTools at 4x |
+| 4 | **Script chain before the listing renders** | Entry ≤ 14 kB brotli (1 round trip); chain depth ≤ 3 | `yarn luma footprint` (entry size, round trips, chain) |
+| 5 | **API requests per page** | Category: lookup (first visit) + products + facets. Search: products + facets + one per quick type. Token: once per session | `yarn luma footprint` (API requests), DevTools Network |
+| 6 | **Recommenders** | Inline: never empty in view. Popup: open within ~100 ms of the notice | DevTools; `reserve` set |
+| 7 | **Bytes per scenario** | No growth without a reason | `yarn luma footprint` (scripts and bytes per page); `--dictionary` for a returning visitor after a deploy |
+| 8 | **Autocomplete as you type** | Keystroke to next paint ≤ 50 ms (INP), first opening included; the typed phrase shown ≤ debounce + one answer after the last key | Event Timing (`event` entries), `ac ask <q>` / `ac shown <q>` in `__lbx.health.timeline`, `yarn luma footprint` (typing) |
+
+What does not matter much: total JS bytes of chunks that load after the
+listing shows (autocomplete, recommender), CORS preflights (cached 20 min),
+and Lighthouse scores on pages without a listing.
+
+### 1. Time to listing shown
+
+This is the number shoppers feel. It is a chain:
+
+```
+HTML → loader → entry (1 RTT) → [challenge → token: first page of a session]
+     → [category lookup: first visit of that category] → products → (facets)
+     → render (first screen in ~100–120 ms at 4x) → shown
+```
+
+- **On a real network, not in a sandbox.** Behind a proxy, the connect and TLS
+  setup alone can take several hundred ms per host, which hides what
+  preconnects save. Measure on your machine with `yarn luma footprint --rtt 100` (an
+  emulated 100 ms round trip), and with DevTools on the live site.
+- Read it in the page:
+
+  ```js
+  __lbx.health.timeline   // [ms since navigation, what]; for example (illustrative):
+  // [ 812, 'plp render 24 hits' ]
+  // [ 941, 'plp rendered in 4 frames (9/14/15/12 ms)' ]
+  // [ 760, 'plp products before their facets' ]
+  // [1210, 'search quick types after the products' ]
+  ```
+
+  Together with the Network panel: the gap between the products response
+  and `render` is ours. The gap between navigation and the products request is
+  the chain above.
+- Reference (a production integration on its stub page, 4x CPU): ours is shown 108–121 ms after its
+  render starts. The rest of the listing finishes 90–140 ms later, busy
+  meanwhile. A repeat visit shows in 0.9–1.2 s. A first visit is dominated by
+  the serial API chain (challenge, token, lookup, products).
+- **What an integration controls:**
+  - the snippet in `<head>` (below);
+  - where the facets and quick types sit. Beside the grid, in a drawer, or
+    below it, the products are shown without waiting for them. Above the
+    grid, they wait so that they don't push it down. Luma learns this per
+    route and width; you choose it with the layout;
+  - tile cost: a tile template that renders in ≤ 1 ms at 4x;
+  - `size`: the first page is what is rendered; a screen plus a row is enough,
+    and "show more" is cheap.
+
+### 2. Layout shift
+
+Zero after ours is shown. The first frame's swap (their listing collapsing as
+ours takes its place) is the takeover's and expected. Anything after it is a
+bug in the integration or in Luma. Sources, most common first:
+
+- **Images without a box.** Use `image()` / `img()` from templates: they emit
+  `aspect-ratio` from `images.width/height`. Set those to the catalog's real
+  ratio.
+- **Parts arriving late above the grid.** Luma waits for the facets and quick
+  types where they sit above, but a template that renders something else
+  above the list from data that comes later (a banner, a count) shifts it.
+  Use `facetsPending` / `quickPending` in the scope to keep their place.
+- **Fonts.** Ours shows in the site's final font; a tile that uses a font the
+  page does not load swaps later. Use the site's fonts.
+- **Recommenders** without `reserve`: the block grows when it fills. Set
+  `reserve` to the rendered height.
+- **The reserved height of a hard load** (`reserveSelector`, the remembered
+  height): check with the footer in view on a tall screen.
+
+Measure it with:
+
+```js
+new PerformanceObserver((l) => l.getEntries().forEach((e) => !e.hadRecentInput && console.log(e.startTime|0, e.value, e.sources?.map((s) => s.node)))).observe({ type: 'layout-shift', buffered: true });
+```
+
+### 3. Main thread: no task of ours over a frame (16 ms) at 4x CPU
+
+`yarn luma tasks` measures it on the storefront (or the stub page): every
+scenario (the `luma.config.mjs` pages loaded, a change of the listing's state, show
+more, Back, typing) three times at 4x CPU, and for each the worst task by
+**our own** time, with its functions named by the integration's source. Our
+own time leaves out the site's code that runs inside our calls (its
+`pushState` hooks, its handlers an integration hook calls): that is in
+`ours`, reported, but not ours to make faster. Exit 1 when a scenario's
+median is over the budget (`--budget`, default 16).
+
+What it found on a production integration, integration-side, the kind of
+thing to look for:
+
+- work at a module's top level in `_init.ts`: an `Intl.NumberFormat` made
+  there loads its locale's data on every page (18 ms of a 30 ms boot task);
+  make such things lazily, or not at all (a fixed price format written out);
+- an `onOpen` that calls into the site (its search overlay opening, jQuery
+  `:visible` checks forcing a layout): 9-18 ms in the autocomplete's first
+  opening; Luma draws the rows in a task before it, but the hook's own cost
+  is the integration's;
+- the browser's `history.pushState` (8-15 ms on a heavy page) in the URL
+  write after a filter: reported under `core/sense.ts`, not reducible by us.
+
+The first render runs in steps: the first 4 tiles with the skeleton, then
+the facet groups and quick types, then the rest, each step within ~16 ms. The
+`rendered in N frames (…ms)` mark lists every step's time. A step over 30 ms
+means the template is too heavy. Typical causes:
+
+- per-tile work in the template (formatting, regexes, `toLocaleString` per
+  call): precompute it in `_init.ts` or in a `result` mapper;
+- deep markup per tile (SVG icons inline per tile: use a `<use href>` sprite);
+- many facet values rendered open (`facetSize`, collapsed groups).
+
+`contentVisibility: true` (opt-in) makes re-renders after "show more" and
+sorting cheaper on long listings (style, layout and paint 243 → 144 ms on
+a production integration's listing), but it contains every tile: check tile hover effects, absolutely
+positioned badges and overflowing shadows before turning it on.
+
+### 4. Scripts: size and chain
+
+`yarn luma footprint` reports the entry (brotli) and the round trips it needs. Keep
+the entry within the TCP first flight (14 kB): one round trip. Integration
+code in `_init.ts` and `_config.ts` lands in the entry. Keep it small: no
+libraries, no catalog data, no templates (templates go to their widget's
+chunk). `--preload` shows what a loader's preload hint for the scenario's
+chunks would save (−100 to −300 ms at 100 ms RTT on a production integration).
+`--dictionary <previous dist>` shows what a returning visitor downloads after a
+deploy with Use-As-Dictionary (category page 56.4 kB → 3.7 kB after a
+one-commit change).
+
+### 5. API requests
+
+Every request is a round trip on a first visit and load on the API.
+Luma's own suites pin its counts. An integration adds
+requests by:
+
+- quick types (one request each; 2 is typical);
+- `emptyValues` (the unfiltered facets, once per scope or query, on a filtered page);
+- several recommenders on a page (each its own request);
+- range facets over fields that are not numeric (a lookup per scope).
+
+The token is minted once per session, off the main thread. The challenge is
+asked by the entry while the minting code loads.
+
+### 6. Recommenders
+
+Inline recommenders are asked two screens ahead, after the page's load event
+(not competing with it). Popups are asked at the click that opens them.
+Watch:
+
+- **empty in view:** scroll at normal speed; the block must be filled
+  before it enters the viewport;
+- `reserve`: the block's rendered height, so filling it does not shift.
+
+### 7. Autocomplete as you type
+
+Two numbers. **Input latency**: no keystroke waits on us. The first opening is
+the risky one: its one-time costs (templates, the first style and layout of
+each text style) are rehearsed after focus. **Freshness**: how far the
+dropdown trails the phrase. A batch goes out on the first 3 characters, then
+after 300 ms of quiet or every 800 ms while typing (`instantChars`,
+`debounceMs`, `maxWaitMs`). It renders once every type has answered, so the
+slowest type sets the pace (usually products).
+
+- The timeline pairs each phrase's `ac ask <q>` with its `ac shown <q>`. The
+  gap is the API's answer plus the pictures (≤ 100 ms) plus our render.
+- Keep product rows light: few `fields`, `size` ≤ 7. Every field is server time
+  and bytes on every keystroke batch.
+- Templates: the same rules as tiles (no per-row formatting work). A batch's
+  render should stay within one frame at 4x on a phone.
+- Measure with real typing (150–250 ms between keys), cold (first opening on
+  a page) and warm. On a phone the sheet opens on the tap: that tap's task is
+  the one to watch.
+
+## How to measure, step by step
+
+0. `yarn luma tooling`: the integration has the one `luma` script and its
+   storefront's host in `luma.config.mjs` (`--write` adds them); `yarn luma`
+   lists the tools.
+1. `yarn luma footprint --rtt 100 --runs 5` in the integration repository, before
+   and after the change. Compare the cold and warm `ready`, main thread, scripts,
+   bytes, chain and API requests per scenario. Commit the JSON (`--json`) so
+   the next change has a baseline.
+2. `yarn luma tasks`: no task of our own over 16 ms at 4x CPU, per scenario. A
+   bot challenge stops the live run and is never worked around: run it on the
+   stub page, or ask the client to allowlist the runner.
+3. On the live site with `?_lbx_env=development`, in DevTools with 4x CPU
+   and Fast 4G: a Performance recording of a category page and a search page,
+   cold (new profile) and warm. Check the Layout shifts track, the longest task
+   in ours, and `__lbx.health.timeline`.
+4. `yarn luma a11y` and `yarn luma parity`: speed must not cost accessibility or parity
+   with the site's listing.
+5. Phone width, desktop width, and a tall screen (1600 px): the learnt
+   layout (facets and quick types above or beside) differs by width, and the
+   first screen holds more tiles on a tall one.
+
+## What the site includes
+
+The snippet with the connection hints is in README.md ("What the customer
+includes").