@luigisbox/luma 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,616 @@
-# Temporary Holding Version
+# Luma
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Luma is the framework behind Luigi's Box frontend integrations: autocomplete,
+search results, category listings (PLP) and recommenders on the Luigi's Box AI
+API, for sites that can only include a script. Optionally, listings arrive
+server-rendered through the site's own cache, from a rendering service Luigi's
+Box runs.
+
+This package is what an integration is built with. Each integration lives in
+its own repository and depends on `@luigisbox/luma`
+([Integration repository](#integration-repository)).
+
+> **Pre-release.** Until 1.0, a minor version (0.3.0) may change the
+> integration API (config keys, template scope, the build); a patch version
+> (0.2.1) only fixes. Depend on `^0.2.0` to take fixes without breaking
+> changes.
+
+## Core principles
+
+### The problem
+
+Luma runs on storefronts it doesn't own, often included as a single script
+tag. That sets the constraints:
+
+1. **The page belongs to the site.** The site's framework, router, CSS and
+   scripts were there first and keep changing. Luma works around them without
+   breaking anything.
+2. **Luma is judged by how the page feels.** If search or listings feel slower,
+   flicker or jump compared with the site's own, the integration is a
+   regression, however good the results are.
+3. **The shopper should not notice Luma.** Results look like the site's own UI
+   and are usable by everyone.
+4. **One framework, many integrations.** Every change to Luma ships to every
+   site that uses it, so the rules must hold in general, not for one site.
+5. **Measured, not claimed.** No one can check every site by hand, so each
+   principle below has a test, a gate or a tool behind it.
+
+### A. A guest on the page
+
+- **Do no harm, always fall back.** Luma adds only its own nodes
+  (`data-lbx`), hides the host's UI with CSS and never removes the host's
+  nodes. It never throws into the page, every network call has a deadline, and
+  nothing of Luma's keeps a page out of the back/forward cache. A failed
+  request, a URL Luma cannot serve, a listing not rendered within 4 s, a
+  non-HTTPS page or a missing browser feature: the site's own UI comes back as
+  if Luma were never there.
+- **Navigation stays the host's.** The site's router owns the URL and history.
+  Luma's history entries carry no state of its own (null, or for SvelteKit and
+  Astro only the router's own bookkeeping keys); it never rewrites the host's.
+  Anything Luma cannot do exactly as the browser would (POST, a new window, a
+  modifier key) stays the browser's. The one exception: a new query from the
+  site's search form while on Luma's search page is shown in place.
+- **Sense and reconcile, not imperative patching.** Host signals (URL changes,
+  DOM mutations, Luma's nodes removed) only mean "reconcile soon". At most once
+  per frame the reconciler makes the page match declarative rules: it removes
+  nodes whose rule is inactive, puts the same instance back if the host
+  removed it, and waits for the anchor to settle. A missed signal is harmless:
+  the next reconcile computes everything from scratch.
+- **Works with any frontend stack.** React/Next.js, Remix/React Router 7,
+  Vue/Nuxt, Angular, SvelteKit, Astro, Turbo and htmx, with no code change on
+  the site. Inside a server-rendered root, Luma waits for that framework's own
+  hydration signal before inserting anything. Every framework host has a
+  contract suite on Chromium, Firefox and WebKit.
+- **Listen at the window, not on host elements.** Input, submit and keydown are
+  window-capture listeners matched against selectors; inputs in shadow roots
+  are read from the composed path. Nothing is bound to the host's input or
+  form, so a re-created input keeps working.
+
+### B. Faster than the site it replaces
+
+- **No flicker, no layout shift.** With the inline snippet in `<head>`, the
+  host's listing is held before first paint and swapped for Luma's in one
+  frame. Its height is reserved from the last visit. Target: zero layout shift
+  after Luma's listing is shown.
+- **A small entry, one round trip.** The entry is at most 14 kB brotli (one TCP
+  initial congestion window). Each widget's code, templates, styles and
+  dictionary are 2–7 kB chunks loaded only when that widget can run: a site
+  without recommenders never downloads that code.
+- **Never block the main thread.** Target: no task of Luma's over 16 ms (a frame
+  at 60 fps) at 4x CPU; the test gate is 30 ms. Typing in autocomplete reaches
+  the next paint within 50 ms (INP). Visual feedback in the handler; fetches
+  and history writes in later tasks. No layout reads after Luma's DOM writes in
+  the same task. Large listings render in steps that each fit a frame.
+- **Instant.** Results are prefetched while the shopper types or hovers a
+  filter, Back restores the listing at the tile they followed, product pages
+  are prerendered on intent (Speculation Rules, Chromium).
+- **Server-side rendering, same code.** The same integration and templates
+  render in the browser and on Luigi's Box servers. The site can serve Luma's
+  listing in its own HTML through SSI/ESI in its web server or CDN; the browser takes the
+  server-rendered listing over. The server renderer and everything it imports
+  stay free of DOM access.
+
+### C. Looks native, works for everyone
+
+- **The site's own look.** Listing templates reuse the site's markup and CSS
+  classes. Luma's built-in CSS sits in `@layer lbx`, so the site's CSS always
+  wins. `yarn luma parity` measures how close the port is.
+- **Web components, DOM mode per widget.** Custom elements are the unit of
+  placement and lifecycle. Listings are light DOM, so the site's CSS applies.
+  Autocomplete is shadow DOM by default: a robust house design isolated from
+  host CSS, with a light-DOM mode for sites that want their own styling.
+- **Accessible by design.** WCAG 2.2 AA (EN 301 549, the European
+  Accessibility Act). Combobox ARIA on the input (`aria-expanded`,
+  `aria-controls`, `aria-activedescendant`), modal dialogs with managed focus,
+  `aria-busy` while a listing renders. `yarn luma a11y` checks an integration.
+- **The modern platform, no polyfills.** Baseline Widely available (custom
+  elements, shadow DOM, cascade layers, `<dialog>`, `inert`, `color-mix()`).
+  Anything newer (Popover API, Navigation API, Speculation Rules) is
+  feature-detected and the page works without it. `yarn luma baseline`
+  enforces it ([Browser support](#browser-support)).
+
+### D. How Luma is built
+
+- **One framework, many integrations.** Nothing site-specific in Luma itself;
+  each integration has its own repository, with Luma as the `@luigisbox/luma`
+  package. `_config.ts` is JSON; code goes in `_init.ts`.
+- **Measured, not claimed.** Every principle has a gate: budgets and
+  main-thread limits, request counts, the bfcache test, the baseline lint,
+  framework contracts, the accessibility and parity checks. The suites run on
+  Chromium, Firefox and WebKit, desktop and phones, on every change. Every fix
+  lands with a test that fails without it.
+
+The trade-offs that come with this: [Known limitations](#known-limitations).
+
+
+## What's in the package
+
+| Path | What |
+|---|---|
+| `src/` | the framework: config, sensing and placement, takeover, templates, API client, widgets |
+| `build/vite.mjs` | the Vite config every integration builds with |
+| `snippet/` | the inline early-hold snippet (identical for every site) |
+| `a11y/` | `yarn luma a11y`: an integration's WCAG 2.2 AA check |
+| `parity/` | `yarn luma parity`: an integration compared with the site it replaces |
+| `bin/` | `yarn luma <tool>`: every tool below, from an integration repository, with one script |
+| `footprint/` | `yarn luma footprint`: what Luma itself costs each page type of an integration |
+| `chrome/` | `yarn luma chrome`: the live storefront in your Chrome with an integration on it, before the site includes it |
+| `tasks/` | `yarn luma tasks`: an integration's main-thread tasks over a frame's budget on the storefront, by source line |
+
+Integrations are not part of the package: each has its own repository with
+Luma as the `@luigisbox/luma` package
+([Integration repository](#integration-repository)).
+
+## What the site includes
+
+Everything goes in the site's HTML, in `<head>`, on every page.
+`<distribution id>` is the site's distribution (`lbdr_…`), provided by
+Luigi's Box.
+
+**Loader only** (a tag manager is fine): the site's own listing may flash
+before Luma's on a hard load.
+
+```html
+<script async src="https://cdn.eu1.luigisbox.ai/b/<distribution id>/loader.js"></script>
+```
+
+**Snippet + loader** (recommended): the inline snippet hides the site's listing
+before first paint, from rules the bundle stored on earlier page views; it makes
+no request and gives up after a timeout. The first page view in a browser has
+no rules yet. Put both first in `<head>`, before the site's own scripts and
+stylesheets (not through a tag manager: too late). With a strict CSP, give the
+snippet's tag the page's `nonce` or allow its hash. On a site whose React
+hydrates the whole document (Remix, React Router 7, Hydrogen), put the loader
+first and the snippet as the last element of `<head>`.
+
+<!-- lbx-snippet: the minified form is snippet/early-hold.min.js (generated from snippet/early-hold.js); this copy must not differ from it -->
+```html
+<script>
+"use strict";(function(){try{if(window.__lbx&&window.__lbx.early)return;var n=JSON.parse(localStorage.getItem("lbx:early")||"null");if(!n||n.v!==1||!(n.exp>Date.now())||performance.getEntriesByName&&performance.getEntriesByName("first-contentful-paint").length)return;for(var o=new URL(location.href),i=0;i<n.routes.length;i++){var e=n.routes[i];if(new RegExp(e.path).test(o.pathname)){for(var r=!0,l=0;e.need&&l<e.need.length;l++)(o.searchParams.get(e.need[l])||"").trim()||(r=!1);if(r&&e.allow){var d=new RegExp(e.allow);o.searchParams.forEach(function(a,p){a&&!d.test(p)&&(r=!1)})}if(r){var t=document.createElement("style"),c=document.currentScript;c&&c.nonce&&(t.nonce=c.nonce),t.setAttribute("data-lbx","early"),t.textContent=e.css,(document.head||document.documentElement).appendChild(t);var f=function(){clearTimeout(u),t.parentNode&&t.parentNode.removeChild(t)},u=setTimeout(f,n.ms||1500),m=window.__lbx=window.__lbx||{};m.early={t:performance.now(),route:e.id,snippet:1,claim:function(a){return!t.parentNode||a!==e.id?!1:(clearTimeout(u),!0)},drop:f};return}}}}catch(a){}})();
+</script>
+<script async src="https://cdn.eu1.luigisbox.ai/b/<distribution id>/loader.js"></script>
+```
+
+**Connection hints** (recommended, first in `<head>`, before the snippet): the
+connections Luma's requests need, opened while the HTML is still arriving instead
+of after the loader and the entry have run (the entry adds the same hints, but
+only once `<body>` starts). On a first visit they take the TCP and TLS setup
+(one to three round trips per host) off the path to the listing. Use the
+region of the site's distribution (`eu1` here) and the host of the
+catalog's product images.
+
+```html
+<link rel="preconnect" href="https://cdn.eu1.luigisbox.ai">
+<link rel="preconnect" href="https://cdn.eu1.luigisbox.ai" crossorigin>
+<link rel="preconnect" href="https://api.eu1.luigisbox.ai" crossorigin>
+<link rel="preconnect" href="https://auth.eu1.luigisbox.ai" crossorigin>
+<link rel="preconnect" href="https://<product image host>">
+```
+
+- The CDN twice: the loader is a classic script (no CORS) and the chunks are
+  modules loaded with CORS. A browser does not share connections between the two
+  modes. Drop the plain one if the Network panel shows a single connection.
+- The API and auth hosts with `crossorigin`: Luma's requests are CORS `fetch()`es.
+  A preconnect without it opens a connection they cannot use.
+- The image host without `crossorigin` (images are no-CORS). Leave it out if
+  it is the site's own host (connected already).
+- At most these five. More preconnects compete with the page's own
+  connections, and an unused one is closed after about 10 s.
+- On listing and search pages, `fetchpriority="high"` on the loader's tag moves
+  it ahead of the page's images (an `async` script is otherwise fetched at low
+  priority). Luma's listing is those pages' main content. Measure it with
+  `yarn luma footprint` and DevTools before keeping it.
+
+The whole `<head>` start of a listing page, in order:
+
+```html
+<head>
+  <meta charset="utf-8">
+  <link rel="preconnect" href="https://cdn.eu1.luigisbox.ai">
+  <link rel="preconnect" href="https://cdn.eu1.luigisbox.ai" crossorigin>
+  <link rel="preconnect" href="https://api.eu1.luigisbox.ai" crossorigin>
+  <link rel="preconnect" href="https://auth.eu1.luigisbox.ai" crossorigin>
+  <link rel="preconnect" href="https://<product image host>">
+  <script>/* the early-hold snippet above, verbatim */</script>
+  <script async fetchpriority="high" src="https://cdn.eu1.luigisbox.ai/b/<distribution id>/loader.js"></script>
+  <!-- the site's own stylesheets and scripts -->
+```
+
+What to measure, and the numbers to optimize for:
+[docs/INTEGRATION-PERFORMANCE.md](docs/INTEGRATION-PERFORMANCE.md).
+
+**Server-side includes**: the listing arrives in the site's HTML, through
+the site's web server or CDN config, with the loader as above. The site adds an
+include (nginx SSI or Varnish/CDN ESI) and a marker at its listing, and a short
+snippet to its server config; Luigi's Box provides both. The
+include sits outside any root the site's own framework hydrates, and the site's
+own listing stays the fallback.
+
+If Luma's listing does not render within 4 s, the request fails or the URL is
+one Luma cannot serve, the site's own listing is shown and the page stays the
+site's until the next visit.
+
+## Integration repository
+
+An integration repository has the shape of the distribution platform's
+scaffold: Luma as the `@luigisbox/luma` package (a devDependency, in
+`node_modules/@luigisbox/luma/`), the integration in `integration/`, a Vite
+build that emits `dist/luma-integration.js` (what the platform's loader
+imports) plus on-demand chunks. Its `vite.config.ts`:
+
+```ts
+import mkcert from 'vite-plugin-mkcert';
+import { clientConfig } from '@luigisbox/luma/build/vite.mjs';
+
+export default clientConfig(import.meta.url, { plugins: [mkcert()], server: { host: 'localhost', https: {} } });
+```
+
+Its `tsconfig.json` extends `@luigisbox/luma/tsconfig.json`, includes
+`integration/**/*` and `node_modules/@luigisbox/luma/src/**/*`, and maps `@/*`
+to `./node_modules/@luigisbox/luma/src/*`. Its `package.json` depends on
+`@luigisbox/luma`, `vite` 7, `typescript` and `vite-plugin-mkcert` (Luma brings
+`lit-html`, `@lit-labs/ssr-client` and its tools' dependencies).
+
+The package holds what an integration uses: the framework's source, the build
+config, `yarn luma` and its tools, and their docs.
+
+```
+integration/
+  __integration.ts                 hands the folder to the framework (startIntegration)
+  _global/                         _config.ts _init.ts [_widget.ts] [_analytics.ts] _translations.ts style-*.css
+                                   template-*.ts shared by every widget (a tile, …)
+  autocomplete/                    _config.ts [_init.ts] [_widget.ts] [style-host.css] [template-autocomplete-*.ts]
+  search/                          _config.ts _translations.ts style-host.css template-search-*.ts
+  plp/                             _config.ts _init.ts style-host.css (templates fall back to search/)
+  recommender <name>/              _config.ts [_init.ts] _translations.ts
+```
+
+- **`_config.ts` is JSON** (checked at boot); anything that needs code goes in
+  `_init.ts`. `_global/_init.ts` runs first and can change any config or return
+  `false` to stop; a widget's `_init.ts` gets that widget's config. Every config
+  key is typed and documented in `src/types.ts`.
+- **`_init.ts` ships and runs on every page; `_widget.ts` loads with its
+  widget.** Keep in `_init.ts` only what decides whether and where a widget
+  runs (`disabled`, `active`, `readQuery`, `items`, `intent`, selectors set in
+  code, switching the site's own widgets off). Hooks only a widget calls
+  (`computedAttributes`, `toFilter`, `facetsFor`, `onRender`, `onOpen`, …) go
+  in the folder's optional `_widget.ts`, same signature (its return value is
+  ignored): it is loaded with the widget's chunk and run once before its
+  context is made, `_global/_widget.ts` first. `__integration.ts` hands it
+  over as a lazy glob: `widgetInits: import.meta.glob('./*/_widget.ts', { import: 'default' })`.
+- **`style-host.css`** hides the host's own listing or suggestions, only while
+  Luma has the page. Other `style-*.css` load with their widget. Luma's built-in
+  CSS sits in `@layer lbx`, so the integration's and the site's CSS win.
+- **Templates override by name**: a widget's built-in templates, then
+  `_global/`, then the widget's own folder. Names: `search-box`, `search-header`,
+  `search-facets-default`, `search-results-default`, `search-result-default`,
+  `search-pagination`, `autocomplete-box`, `autocomplete-result-default`,
+  `autocomplete-sheet`, `autocomplete-empty`, `recommender-box-default`,
+  `recommender-result-default`, `recommender-popup`.
+
+### Templates
+
+Templates are [lit-html](https://lit.dev/docs/templates/overview/): each
+`template-<name>.ts` default-exports a function of the template's scope that
+returns `` html`…` ``. Only changed bindings touch the DOM, so images, focus and
+open `<details>` survive re-renders; no `eval`, CSP-safe. Import lit from `@/lit`
+and the scope types from `@/types` (`SearchScope`, `SearchResultScope`,
+`AutocompleteScope`, `RecommenderScope`, …).
+
+```ts
+// integration/search/template-search-result-default.ts
+import { html, nothing } from '@/lit';
+import type { SearchResultScope } from '@/types';
+
+export default ({ r, i, img, price }: SearchResultScope) => html`
+  <a class="tile" href=${r.c.url}>
+    ${img(r, i)}
+    <span>${r.c.title}</span>
+    ${r.c.price ? html`<b>${price(r.c.price)}</b>` : nothing}
+  </a>`;
+```
+
+| lit | |
+|---|---|
+| `${expr}` | text (escaped) |
+| `` ${cond ? html`…` : nothing} `` | conditions |
+| `` ${repeat(list, (x) => x.id, (x, i) => html`…`)} `` | keyed lists (`list.map(…)` for unkeyed) |
+| `attr=${v}`, `?disabled=${b}`, `.checked=${b}` | attribute, boolean attribute, property |
+| `@click=${s.showMore}`, `@change=${() => s.toggleFacet(f.name, v.value)}` | event handlers |
+| `${include('product-tile', { extra })}` | another template of the widget, with this scope plus props |
+
+- **Results**: `r.a` is the hit's attributes, `r.c` its computed attributes
+  (functions in `_global/_init.ts`, `computedAttributes`). `r.c.url` is always a
+  web link; a `javascript:` or `data:` value becomes `''`. Links you bind from
+  `r.a` or your own computed attributes, and `unsafeHTML`, get no such check:
+  keep catalog data out of them, or check it. With Trusted Types enforced, the
+  site's `trusted-types` directive must allow the `lit-html` policy.
+- **Helpers** in every scope: `t(key, params)`, `price(n)`, `plain()`,
+  `first()`, `include()`, and `img(r, i)` (a complete `<img>` in its placeholder
+  box) / `image(r, i)` (its attributes, for your own markup), configured by
+  `_global.images` (srcset, sizes, the eager first row, placeholders).
+- **Pagination** is "show more" only: templates get `results`, `more` and
+  `showMore`; there are no numbered pages.
+- **Translations** are JSON dictionaries per locale (`src/locales/<locale>.json`,
+  `{name}` placeholders, plural forms by `Intl.PluralRules` category); only the
+  site's locale is loaded. Override keys in `_translations.ts`, keyed by locale:
+  `_global` for all widgets, a widget's own for that widget. Give
+  `__integration.ts` their glob without `eager`
+  (`translations: import.meta.glob('./*/_translations.ts', { import: 'default' })`)
+  and they load with their widget instead of on every page; `_init.ts` then
+  does not see them.
+
+### Behaviour switches
+
+On by default unless noted; each falls back to what the page would do anyway.
+
+| Config | What it does | Turn it off when |
+|---|---|---|
+| `search.inPlaceQuery` | a new query on the search page renders in place, without a page load | the host's page-view analytics or server-rendered parts of the search page must follow every query |
+| `search.prefetchWhileTyping` | the search result is fetched once the typed phrase settles, so Enter shows it at once | |
+| `restoreOnBack` | Back from a product restores the listing and the followed tile's position | |
+| `prefetchNextPage` | "show more" is fetched as the shopper nears the end | |
+| `contentVisibility` (opt-in) | tiles out of view skip style, layout and paint, each at its own measured size: a long list's re-render about halves | keep it off where a tile draws outside its box (a hover panel, a badge hanging out) or holds a `position: fixed` element |
+| `_global.prefetchFilters` | a filter, sort or chip is fetched on hover, touch or focus | |
+| `_global.speculation` | product pages are prerendered on hover (`'prerender'`, `'prefetch'`, `false`) | the site's server or its product-page scripts can't take a render per unfollowed hover |
+
+### Analytics
+
+Luma sends analytics events to the Luigi's Box AI events API
+([docs](https://docs.luigisbox.ai/analytics/overview/)) as the integration's
+`_global/_analytics.ts` describes them. Every event sent is one
+`collect.<event>` line in that file, and nothing else is sent: reading the file
+top to bottom tells you what the site collects. Without the file there is no
+analytics at all (no code loaded, nothing sent).
+
+`__integration.ts` hands the file over as a lazy glob:
+`analytics: import.meta.glob('./*/_analytics.ts', { import: 'default' })`.
+`analytics: false` in `_global/_config.ts` turns analytics off whatever the
+file says. Luma does not check consent: whatever includes Luma on the page
+(the Luigi's Box loader) decides that, and once Luma runs, events are sent.
+
+Each line names the event, when it happens and how it is read:
+
+```ts
+collect.addToCart          // the event sent: an add-to-cart
+  .on(dl('add_to_cart'))   // when: each dataLayer push with event 'add_to_cart'
+  .read(fromGa4.addToCart) // how: the push read as GA4 ecommerce
+```
+
+`.read()` takes a reader (`fromGa4.…`, `fromLuma.…`) or a function of the
+trigger's context that returns what the event sends (`null`: nothing).
+`.when(f)`, `.throttle(ms)` and `.once()` (once per page) go before `.read()`.
+A typical integration:
+
+```ts
+// integration/_global/_analytics.ts
+import { collect, dl, fromGa4, fromLuma, lumaCarts, lumaClicks, lumaPages, ref } from '@/analytics';
+
+ref.product.by('sku'); // product references by the catalog's `sku` field: product/sku:<value>
+
+collect.pageView.on(lumaPages()).read(fromLuma.pageView);
+collect.click.on(lumaClicks()).read(fromLuma.click);
+collect.addToCart.on(lumaCarts()).read(fromLuma.addToCart);
+collect.addToCart.on(dl('add_to_cart')).read(fromGa4.addToCart);
+collect.purchase.on(dl('purchase')).read(fromGa4.purchase);
+```
+
+**Events**
+
+| Event | What `.read()` returns |
+|---|---|
+| `pageView` | the page's reference, or `null` for a page without one. On `lumaPages()`, one pageview per page, sent at once. On any other trigger, one per page that waits for its reference from that trigger (`.timeout(ms)`, default 1000 ms) and is sent without one after that. One `pageView` line per file |
+| `click` | a product click: a reference, or `{ reference }` |
+| `addToCart` | `{ reference, count?, price? }`, or a list of them |
+| `purchase` | `{ id?, currency?, items: [{ reference, title, count, total_price, was_discounted? }] }`; sent once per `id`, so a reloaded thank-you page does not count twice |
+| `search`, `autocomplete`, `recommender(name)` | a list from the site's own service: `{ query?, items, filters? }`. Not sent on a page where Luma runs that service itself (the API records Luma's own results) |
+
+**Triggers**
+
+| Trigger | When | Context |
+|---|---|---|
+| `lumaPages()` | each page: the first, the next page of a single-page app, a page restored from the back/forward cache, a prerendered page once it is shown. Filtering or sorting a Luma listing is not a new page | `{ url, referrer }` |
+| `lumaClicks()` | a click on a product in a Luma widget: any link to it, middle and modifier clicks included, and a pick in the autocomplete | `{ reference, result, index, list }` |
+| `lumaCarts()` | a click on a `[data-lbx-cart]` button in a Luma product tile (its value: the quantity). `_global.addToCart(result, { count, el, event })` adds the product to the site's cart, with or without analytics | `{ reference, result, index, list, count, price? }` |
+| `dl(event)` | a dataLayer push with that event name, object or `gtag()` form, including pushes made before Luma loaded. `_global.dataLayer` in `_config.ts` names another layer | `{ event, eventType, data, ecommerce }` |
+| `domClick(selector)` | a click (or middle click) on an element of the site's that matches `selector` | `{ element, event }` |
+| `urlChange()` | a navigation in a single-page app | `{ url, previousUrl }` |
+| `mutationOf(selector, { root? })` | the site renders that element into the page, or renders into it; read once the browser is idle | `{ element }` |
+| `xhrMatching(({ url, method }) => …)` | a response to one of the site's own requests (XMLHttpRequest or fetch) that the test matches | `{ url, method, response }` |
+| `manual()` | `fire(data)` is called: `const { trigger, fire } = manual()` | `{ data }` |
+
+**Readers**
+
+| Reader | Reads |
+|---|---|
+| `fromLuma.pageView`, `.click`, `.addToCart` | what Luma's own triggers saw (`lumaPages()`, `lumaClicks()`, `lumaCarts()`). Products are referenced by their catalog `@id` |
+| `fromGa4.addToCart`, `.purchase`, `.click`, `.pageView`, `.search`, `.autocomplete`, `.recommender` | GA4 ecommerce: `add_to_cart`, `purchase`, `select_item`, `view_item`, `view_item_list`. The data is taken from the push's `ecommerce` (or `gtag()`'s parameters), or from the push itself when its `items` are there. Items are referenced by `ref.product(item_id)`; purchases get line totals, and `was_discounted` from `discount` |
+
+Each reader belongs to one event: `collect.purchase…read(fromGa4.addToCart)`
+is a type error, and throws when the file runs.
+
+**References** follow `<type>/<field>:<value>`
+([docs](https://docs.luigisbox.ai/analytics/references/)).
+`ref.product(value)` uses the field set by `ref.product.by(field)` (default
+`@id`); `ref.product(field, value)` names another field. `ref.variant`,
+`ref.category` and `ref.brand` work the same way. `user.identify(fn)` sends
+the signed-in shopper's own id as `user_id`.
+
+**Nothing is lost when the page changes.** A click or add-to-cart on a Luma
+product is recorded the moment it happens, and dataLayer pushes on a page the
+shopper leaves before analytics has loaded (a thank-you page closed at once)
+are kept. The next page sends them, dated as they happened; a purchase is still
+sent once.
+
+**Size.** Analytics loads as one chunk, after the page has loaded, holding
+only what the file uses: every event, trigger and reader is a separate export
+(`fromGa4.purchase` brings that reader alone). Gzip sizes:
+
+| `_analytics.ts` | Size |
+|---|---|
+| none | nothing loaded |
+| pageviews only | 2.2 kB |
+| pageviews, add-to-carts and purchases from GA4 | 3.6 kB |
+| + Luma's own clicks and add-to-carts (`lumaClicks()`, `lumaCarts()`) | +0.2 kB |
+| + `domClick()` | +0.2 kB |
+| + a `fromGa4` list reader (`.search`, `.autocomplete`, `.recommender`) | +0.1 kB |
+| + `mutationOf()`, `xhrMatching()` | +0.3, +0.4 kB |
+| + `user.identify()`, a page reference, a list read by a function of yours, `.once()`, `.throttle()` | under 0.1 kB each |
+
+**A site's own search and suggestions** (where Luma does not render them) are
+read with functions of your own, for example:
+
+```ts
+import { collect, dl, domClick, fromGa4, mutationOf, ref, xhrMatching } from '@/analytics';
+
+// the site's search results, rendered into #results
+collect.search.on(mutationOf('#results')).once().read(({ element }) => ({
+  query: { string: new URLSearchParams(location.search).get('q') ?? '' },
+  items: [...element.querySelectorAll('[data-sku]')].map((tile, n) => ({ title: tile.textContent ?? '', type: 'product', reference: ref.product(tile.getAttribute('data-sku')!), position: n + 1 })),
+}));
+// clicks on those results
+collect.click.on(domClick('#results [data-sku] a')).read(({ element }) => ref.product(element.closest('[data-sku]')!.getAttribute('data-sku')!));
+// the site's suggestions, from its own API
+collect.autocomplete.on(xhrMatching(({ url }) => url.includes('/suggest'))).read(({ response }) => ({ items: /* … */ [] }));
+// the product page's product, from GA4's view_item
+collect.pageView.on(dl('view_item')).read(fromGa4.pageView);
+```
+
+## Browser support
+
+Luma targets [Baseline](https://web.dev/baseline) **Widely available**; anything
+newer (Popover API, Navigation API, Speculation Rules) is
+feature-detected and optional. **HTTPS only**: on a plain-HTTP page Luma does
+not start and the site keeps its own search. Tested on Chromium, Firefox and
+WebKit, desktop and phone, on every change.
+
+An integration repository runs the same check on its `integration/` folder:
+`yarn luma baseline`, and `yarn luma
+baseline --built dist` over a build's output (below, "Tools for an
+integration repository").
+
+## Known limitations
+
+- **Autocomplete needs the Popover API**: without it (Safari < 17, Firefox
+  < 125) the site keeps its own suggestions.
+- **Loader without the snippet**: the site's own listing may flash before
+  Luma's on a hard load.
+- **Analytics**: a search shown in place fires no page view in the site's own
+  tags (Luma's `lumaPages()` counts it). Prefetches and prerenders count in the
+  API's request numbers, though never as searches or impressions. Analytics
+  loads after the page has: a visitor who leaves before that sends no pageview
+  and no click on the site's own elements (`domClick()`); clicks and
+  add-to-carts on Luma's products and dataLayer pushes are kept for the next
+  page. A/B tests are not supported yet (`listing_ab_test` is always `false`).
+- **Prerendering** costs the site a page render per unfollowed hover
+  (`speculation: false` turns it off).
+- **Early hold**: the snippet carries no site's rules, so the first page
+  view is not held.
+- **Host routers out of reach**: where Luma cannot find the host's router (Vue
+  Router 4 when its app is not discoverable, Angular in production), the
+  router can overwrite Luma's history entry or show a stale query in its search
+  box. `inPlaceQuery: false` for such a site.
+
+## Development
+
+Node 24 or later, Yarn 4 (corepack).
+
+### Seeing an integration on the storefront
+
+An integration is developed in its own repository. How you see it on the live
+site depends on whether the site includes the Luigi's Box loader yet.
+
+**The site includes the loader.** Serve the integration and add
+`?_lbx_env=development` to any page of the site:
+
+```bash
+yarn dev                # serves the integration on https://localhost:8069
+```
+
+```
+https://www.shop.example/some-category?_lbx_env=development
+```
+
+The loader then imports the integration from your dev server instead of the
+published build (a red banner says so); an edit shows on reload.
+`LBX_DEV_ORIGINS` (comma-separated) limits which sites may load from it.
+
+**The site does not include the loader yet.** Open the storefront with the
+integration injected as the site would include it (the early-hold snippet,
+then the build):
+
+```bash
+yarn luma chrome                  # builds, opens the home page in your Chrome
+yarn luma chrome /some-category   # another page
+yarn luma chrome --dev            # from yarn dev: an edit shows on reload, no build
+```
+
+It needs the storefront's host in `luma.config.mjs` (`export const host =
+'www.shop.example'`). The site's own Luigi's Box scripts are blocked, nothing
+else of the site changes, and the browser profile is kept per storefront
+(`~/.lbx-chrome/<host>`), apart from your own. `--check` prints what Luma did
+and exits; `--help` lists the rest ([`chrome/run.mjs`](chrome/run.mjs)).
+
+Either way, `window.__lbx` in the console is Luma's state (`health.errors`,
+`health.timeline`). `yarn build` emits `dist/`.
+
+### Working on Luma itself
+
+Luma is developed by Luigi's Box. Every change is type-checked and runs the
+unit and browser suites and the performance gates on Chromium, Firefox and
+WebKit before it ships.
+
+### Tools for an integration repository
+
+An integration repository's `package.json` has one script for
+all of them, `"luma": "luma"` (the package's command), and its
+`luma.config.mjs` the storefront's host (`export const host =
+'www.shop.example'`): a tool Luma adds is there once Luma is updated, nothing to
+change in the integration. `yarn luma` lists them; `yarn luma tooling --write`
+sets an integration up
+([`bin/tools.mjs`](bin/tools.mjs), [`build/tooling.mjs`](build/tooling.mjs)).
+
+| Command | What |
+|---|---|
+| `yarn luma chrome [path]` | the live storefront in your Chrome with the integration on it as the site would include it (the early-hold snippet, then the build), whether or not the site includes it yet; the site's own Luigi's Box scripts blocked, nothing else changed; `--dev` from `yarn dev`, `--check` prints what Luma did and exits ([`chrome/run.mjs`](chrome/run.mjs)) |
+| `yarn luma a11y` | WCAG 2.2 AA check of the integration's widgets, by keyboard too ([`docs/ACCESSIBILITY.md`](docs/ACCESSIBILITY.md) §8) |
+| `yarn luma parity` | compares the site's search and category UI with Luma's, component by component ([`docs/PARITY.md`](docs/PARITY.md)) |
+| `yarn luma footprint` | what Luma itself costs per page type: the entry's size and round trips, scripts and bytes loaded, the script chain, main-thread and compile time, API requests, time to ready; on the integration's stub page ([`footprint/run.mjs`](footprint/run.mjs)) |
+| `yarn luma tasks` | Luma's main-thread tasks per scenario (pages, a state change, show more, Back, typing) at 4x CPU on the storefront: the worst task's own time against a 16 ms budget, its functions by source line, the site's code under Luma's calls apart ([`tasks/run.mjs`](tasks/run.mjs)) |
+| `yarn luma baseline` | nothing in `integration/` newer than Baseline Widely available (`--built dist`: the build) |
+
+The integration's settings for the tools are its `luma.config.mjs`
+([`bin/config.mjs`](bin/config.mjs) loads it, with Luma's defaults). Every
+export is optional:
+
+```js
+// The storefront's host name: the tools open it (LBX_HOST overrides it). Without
+// it they use the stub page (`yarn luma chrome` needs it).
+export const host = 'www.shop.example';
+// The site's name (LBX_SITE overrides it); default: package.json's name.
+export const site = 'shop';
+// A page in the site's own markup and stylesheet, for the tools' runs on the
+// stub page (a string, or a promise of one).
+export const stubPage = (url) => `<!DOCTYPE html>…`;
+// What the tools' scenarios load: a category page, a search, a product page,
+// the header search input.
+export const fixtures = { category: '/some-category', query: 'shoes', product: '/some-product', input: 'input#search' };
+// The pages footprint and tasks measure, { label: path }; default: home,
+// fixtures.category, a search for fixtures.query, fixtures.product.
+export const perf = { pages: { home: '/', category: '/some-category', search: '/search?q=shoes' } };
+```
+
+Without a `stubPage`: a neutral page with a header search form (`input
+name=q`), a search anchor `<div id="lbx-search-anchor">` on `/search`, and
+elsewhere a category listing `<div id="lbx-listing">`. Older integrations kept
+these settings in `edge/rig.mjs`: the tools refuse that name, `yarn luma
+tooling --write` moves it.
+
+How to make an integration fast and light, and which tool measures what:
+[`docs/INTEGRATION-PERFORMANCE.md`](docs/INTEGRATION-PERFORMANCE.md).
+
+## Documentation
+
+- [`docs/INTEGRATION-PERFORMANCE.md`](docs/INTEGRATION-PERFORMANCE.md): what to measure in integration work, and the metrics to optimize.
+- [`docs/ACCESSIBILITY.md`](docs/ACCESSIBILITY.md): what Luma guarantees, what templates must do.
+- [`docs/PARITY.md`](docs/PARITY.md): the parity check.