@luigisbox/luma 0.1.0 → 0.2.0

package/README.md

@@ -1,53 +1,57 @@
 # Luma
 
-The framework for 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 our script. Optionally, listings arrive
+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.
 
-> **Pre-release.** Until 1.0, a minor version (0.2.0) may change the
+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.1.1) only fixes. Depend on `^0.1.0` to take fixes without breaking
+> (0.2.1) only fixes. Depend on `^0.2.0` to take fixes without breaking
 > changes.
 
 ## Core principles
 
 ### The problem
 
-Luma runs on storefronts we don't own, often included as a single script tag.
-That sets the constraints:
+Luma runs on storefronts it doesn't own, often included as a single script
+tag. That sets the constraints:
 
-1. **The page is someone else's.** Their framework, router, CSS and scripts
-   were there first and keep changing. We work around them without breaking
-   anything.
-2. **We are judged by how the page feels.** If search or listings feel slower,
+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 us.** Results look like the site's own UI
+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 `src/` ships to every
-   client, so the rules must hold in general, not for one site.
-5. **Measured, not claimed.** We cannot check every client's site by hand, so
-   each principle below has a test, a gate or a tool behind it.
+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 their nodes. It
-  never throws into the page, every network call has a deadline, and nothing
-  of ours keeps a page out of the back/forward cache. A failed request, a URL
-  we 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 we were never
-  there.
+  (`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.
-  Our history entries carry no state of ours (null, or for SvelteKit and
-  Astro only the router's own bookkeeping keys); we never rewrite the host's.
-  Anything we cannot do exactly as the browser would (POST, a new window, a
+  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 our search page is shown in place.
+  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, our nodes removed) only mean "reconcile soon". At most once
+  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:
@@ -65,24 +69,24 @@ That sets the constraints:
 ### 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 ours in one frame.
-  Its height is reserved from the last visit. Target: zero layout shift after
-  ours is shown.
+  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 ours over 16 ms (a frame
+- **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 our DOM writes in
+  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 our servers. The site can serve our listing in
-  its own HTML through SSI/ESI in its web server or CDN; the browser takes the
+  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.
 
@@ -105,10 +109,10 @@ That sets the constraints:
   feature-detected and the page works without it. `yarn luma baseline`
   enforces it ([Browser support](#browser-support)).
 
-### D. How we work
+### D. How Luma is built
 
-- **One framework, many integrations.** Nothing site-specific in this
-  repository; each integration has its own, with Luma as the `@luigisbox/luma`
+- **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,
@@ -116,16 +120,16 @@ That sets the constraints:
   Chromium, Firefox and WebKit, desktop and phones, on every change. Every fix
   lands with a test that fails without it.
 
-What we accept in exchange: [Known limitations](#known-limitations).
+The trade-offs that come with this: [Known limitations](#known-limitations).
 
 
-## Repository layout
+## 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 client) |
+| `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 |
@@ -133,17 +137,18 @@ What we accept in exchange: [Known limitations](#known-limitations).
 | `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 do not live here: each has its own repository with Luma as the
-`@luigisbox/luma` package (older ones: the `luma/` submodule;
-[Integration repository](#integration-repository)).
+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 customer includes
+## What the site includes
 
 Everything goes in the site's HTML, in `<head>`, on every page.
-`<distribution id>` is the site's distribution (`lbdr_…`).
+`<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 ours on a hard load.
+before Luma's on a hard load.
 
 ```html
 <script async src="https://cdn.eu1.luigisbox.ai/b/<distribution id>/loader.js"></script>
@@ -167,7 +172,7 @@ first and the snippet as the last element of `<head>`.
 ```
 
 **Connection hints** (recommended, first in `<head>`, before the snippet): the
-connections our requests need, opened while the HTML is still arriving instead
+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
@@ -185,7 +190,7 @@ catalog's product images.
 - 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`: our requests are CORS `fetch()`es.
+- 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).
@@ -193,7 +198,7 @@ catalog's product images.
   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). Our listing is those pages' main content. Measure it with
+  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:
@@ -215,15 +220,15 @@ 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
-their web server or CDN config, with the loader as above. The site adds an
+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 for the site. The
+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 our listing does not render within 4 s, the request fails or the URL is one
-we cannot serve, the site's own listing is shown and the page stays theirs
-until the next visit.
+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
 
@@ -244,18 +249,15 @@ 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). An older
-repository has Luma as the `luma/` submodule instead (`./luma/…` for
-`@luigisbox/luma/…`, and `yarn --cwd luma install` for the tools); both build
-the same.
+`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 the client tools, and their docs.
+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] _translations.ts style-*.css
+  _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
@@ -277,7 +279,7 @@ integration/
   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
-  the page is ours. Other `style-*.css` load with their widget. Luma's built-in
+  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`,
@@ -352,6 +354,128 @@ On by default unless noted; each falls back to what the page would do anyway.
 | `_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
@@ -369,18 +493,22 @@ integration repository").
 
 - **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 ours
-  on a hard load.
-- **Analytics**: Luma sends no tracking events. A search shown in place fires no page
-  view of the host's. Speculative requests (prefetches, prerenders) count in
-  the API's request numbers, though never as searches or impressions.
+- **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 client's rules, so the first page
+- **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 our history entry or show a stale query in its search
+  router can overwrite Luma's history entry or show a stale query in its search
   box. `inPlaceQuery: false` for such a site.
 
 ## Development
@@ -390,7 +518,7 @@ 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 our loader yet.
+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:
@@ -408,7 +536,7 @@ 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 a customer would install it (the early-hold snippet,
+integration injected as the site would include it (the early-hold snippet,
 then the build):
 
 ```bash
@@ -435,8 +563,7 @@ 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; with the submodule,
-`"node luma/bin/luma.mjs"` after `yarn --cwd luma install`), and its
+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`
@@ -445,11 +572,11 @@ sets an integration up
 
 | Command | What |
 |---|---|
-| `yarn luma chrome [path]` | the live storefront in your Chrome with the integration on it as a customer installs 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 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 ours, component by component ([`docs/PARITY.md`](docs/PARITY.md)) |
+| `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` | our 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 our calls apart ([`tasks/run.mjs`](tasks/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`

package/build/vite.mjs

@@ -30,6 +30,9 @@ const FRAMEWORK = resolve(dirname(fileURLToPath(import.meta.url)), '../src');
 //                     building, stash, in-place query, URL writing): typing on
 //                     any page and the listing need it, a page with only a
 //                     recommender does not
+//   lbx-analytics     pageviews, our tiles' clicks and add-to-carts, the
+//                     site's GA4 events, the integration's _analytics.ts and
+//                     what it imports (tree-shaken): every page once loaded, and widgets
 //   lbx-locale-*  lbx-hydrate   only where needed (the site's
 //                     locale, server-rendered pages)
 // A module the entry imports statically (health, sense, the listing's query
@@ -60,6 +63,10 @@ const entryGraph = (getModuleInfo, getModuleIds) => {
   return seen;
 };
 export const chunkOf = (id) => {
+  // An integration's _analytics.ts (its analytics setup) goes with the analytics
+  // chunk that reads it (no request of its own), with what it imports from
+  // @/analytics: the rest of src/analytics is tree-shaken out of it.
+  if (/\/integration\/[^/]+\/_analytics\.[jt]s$/.test(id)) return 'lbx-analytics';
   // Any other module of an integration folder that only something lazy imports
   // (its lazy _translations.ts, code an _init.ts hook imports on demand) goes
   // with its folder's templates: no chunk, no request of its own. An eager one
@@ -86,6 +93,8 @@ export const chunkOf = (id) => {
   if (/\/src\/widgets\/search\/(index|in-place)\.ts$/.test(id)) return 'lbx-search';
   // Search while typing (main.ts loads it once the shopper types): not in lbx-nav, which a listing page loads at once.
   if (/\/src\/widgets\/search\/speculate\.ts$/.test(id)) return 'lbx-speculate';
+  // Analytics (src/analytics): every page once loaded (main.ts), widgets import it for their tiles' clicks.
+  if (/\/src\/analytics\//.test(id)) return 'lbx-analytics';
   // Minting the browser token: a session's first page loads it at boot (main.ts), lbx-core imports it.
   if (/\/src\/api\/token\.ts$/.test(id)) return 'lbx-token';
   // Only the site's locale is ever loaded.

package/chrome/block.mjs

@@ -0,0 +1,8 @@
+// The Luigi's Box scripts `yarn luma chrome` keeps off the storefront (a
+// platform loader, a previous integration: never with ours), but the hosts
+// `--allow` names: a previous generation's search or autocomplete the
+// integration's analytics observes (mutationOf, xhrMatching).
+export const LBX_SCRIPTS = /^https:\/\/(cdn\.luigisbox\.(com|tech)|cdn\.eu1\.luigisbox\.ai|scripts\.luigisbox\.(com|tech))\//;
+
+/** Whether `url` is blocked, `allow` the host names left alone. */
+export const blocked = (url, allow = []) => LBX_SCRIPTS.test(url) && !allow.includes(new URL(url).hostname);

package/chrome/run.mjs

@@ -7,6 +7,7 @@
 //   yarn luma chrome                  the storefront's home page (luma.config.mjs `host`, or LBX_HOST)
 //   yarn luma chrome /some-category   another page
 //   yarn luma chrome --dev            from the dev server (yarn dev): an edit shows on reload, no build
+//   yarn luma chrome --allow cdn.luigisbox.tech   that host's Luigi's Box scripts left on (their previous search, say)
 //
 // Nothing else of the site changes: Luigi's Box's scripts it already loads (a
 // platform loader, a previous integration) are blocked, so ours is the only
@@ -20,6 +21,7 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync } fr
 import { homedir, tmpdir } from 'node:os';
 import { extname, join, normalize, resolve } from 'node:path';
 import { inside } from '../bin/paths.mjs';
+import { blocked } from './block.mjs';
 
 const USAGE = `usage: yarn luma chrome [path] [options]
 
@@ -30,10 +32,12 @@ const USAGE = `usage: yarn luma chrome [path] [options]
   --no-snippet       the build alone, without the early-hold snippet in <head>
   --channel NAME     chrome (default: your installed Chrome) or chromium (Playwright's)
   --profile DIR      the browser profile (default ~/.lbx-chrome/<host>)
-  --site-dir DIR     the integration repository (default: the current directory, LBX_SITE_DIR)`;
+  --site-dir DIR     the integration repository (default: the current directory, LBX_SITE_DIR)
+  --allow HOST       leave that host's Luigi's Box scripts on (repeatable): a previous search or
+                     autocomplete the integration's analytics observes (cdn.luigisbox.tech)`;
 
 const args = process.argv.slice(2);
-const opt = { path: '/', check: false, dev: false, build: true, snippet: true, channel: 'chrome', profile: '', siteDir: '' };
+const opt = { path: '/', check: false, dev: false, build: true, snippet: true, channel: 'chrome', profile: '', siteDir: '', allow: [] };
 const die = (msg) => {
   console.error(msg);
   process.exit(2);
@@ -55,6 +59,7 @@ for (let i = 0; i < args.length; i++) {
   else if (a === '--channel') opt.channel = next();
   else if (a === '--profile') opt.profile = next();
   else if (a === '--site-dir') opt.siteDir = next();
+  else if (a === '--allow') opt.allow.push(next());
   else if (!a.startsWith('--')) opt.path = a.startsWith('/') ? a : `/${a}`;
   else die(`unknown option ${a}\n\n${USAGE}`);
 }
@@ -115,8 +120,8 @@ for (const channel of [opt.channel, ...(opt.channel === 'chrome' ? ['chromium']
     if (channel === 'chromium') die(`No browser to open: install Chrome, or \`yarn playwright-core install chromium\`.\n${e.message.split('\n')[0]}`);
   }
 }
-// Luigi's Box's scripts the site loads already: never with ours.
-await ctx.route(/^https:\/\/(cdn\.luigisbox\.(com|tech)|cdn\.eu1\.luigisbox\.ai|scripts\.luigisbox\.(com|tech))\//, (r) => r.abort('blockedbyclient'));
+// Luigi's Box's scripts the site loads already: never with ours (but the hosts --allow names).
+await ctx.route((u) => blocked(u.href, opt.allow), (r) => r.abort('blockedbyclient'));
 // The build, from the storefront's own origin (as a platform loader serves it): fresh on every reload.
 await ctx.route(`${ORIGIN}${PREFIX}**`, (route) => {
   const file = normalize(join(DIST, decodeURIComponent(new URL(route.request().url()).pathname.slice(PREFIX.length))));
@@ -139,7 +144,7 @@ if (opt.check) {
   await ctx.close();
   process.exit(!s || s.error || s.errors?.length ? 1 : 0);
 }
-console.log(`${ORIGIN}${opt.path} with ${opt.dev ? 'the dev server (yarn dev)' : opt.build ? 'this build' : 'dist/'}${opt.snippet ? ' and the early-hold snippet' : ''}, Luigi's Box's own scripts blocked.`);
+console.log(`${ORIGIN}${opt.path} with ${opt.dev ? 'the dev server (yarn dev)' : opt.build ? 'this build' : 'dist/'}${opt.snippet ? ' and the early-hold snippet' : ''}, Luigi's Box's own scripts blocked${opt.allow.length ? ` but ${opt.allow.join(', ')}` : ''}.`);
 console.log(opt.dev ? 'Edit, then reload the page. ' : opt.build ? 'A change: run this again (or --dev with yarn dev). ' : 'A change: yarn build, then reload. ');
 console.log(`window.__lbx in the console: Luma's state. Close the window to stop (profile: ${profile}).`);
 await new Promise((r) => ctx.on('close', r));

package/docs/ACCESSIBILITY.md

@@ -400,8 +400,7 @@ From the integration repository: `yarn luma a11y`
 (README, "Tools for an integration repository": the one `luma` script). The
 storefront's host name is its `luma.config.mjs` `host` (`LBX_HOST` overrides it;
 the browser token is minted for that origin). Its dependencies come with Luma
-(Playwright, axe-core; with the `luma/` submodule: `yarn --cwd luma install`
-once); the browser is Playwright's Chromium or the installed Chrome,
+(Playwright, axe-core); the browser is Playwright's Chromium or the installed Chrome,
 `LBX_CHROMIUM_PATH` otherwise.
 
 ```bash

package/docs/INTEGRATION-PERFORMANCE.md

@@ -1,7 +1,7 @@
 # Integration performance: what to measure, what to optimize
 
 A guideline for integration work (an integration repository with Luma as the
-`@luigisbox/luma` package, or as the `luma/` submodule). Luma's own budgets are
+`@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.
@@ -187,10 +187,9 @@ slowest type sets the pace (usually products).
 
 ## How to measure, step by step
 
-0. `yarn luma tooling` (with the `luma/` submodule, before the script exists:
-   `node luma/build/tooling.mjs`):
-   the integration has the one `luma` script and its storefront's host in
-   `luma.config.mjs` (`--write` adds them); `yarn luma` lists the tools.
+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
@@ -208,7 +207,7 @@ slowest type sets the pace (usually products).
    layout (facets and quick types above or beside) differs by width, and the
    first screen holds more tiles on a tall one.
 
-## What the customer includes
+## What the site includes
 
 The snippet with the connection hints is in README.md ("What the customer
 includes").

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luigisbox/luma",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Luma: Luigi's Box frontend integrations (autocomplete, search, category listings, recommenders) on the Luigi's Box AI API. Pre-release.",
   "license": "SEE LICENSE IN LICENSE.md",

package/parity/hold.mjs

@@ -1,4 +1,4 @@
-// Luma on a page as a customer installs it (README, "What the customer includes"): the
+// Luma on a page as a customer installs it (README, "What the site includes"): the
 // generic early-hold snippet (snippet/early-hold.min.js) first in <head>,
 // then the build. `yarn luma parity` (ours in every mode: replay, --record,
 // --live, --dev) and `yarn luma a11y` put the build in the storefront's own page