@luigisbox/luma 0.0.0-stage → 0.1.0

package/LICENSE.md

@@ -0,0 +1,90 @@
+LUIGI'S BOX COMMERCIAL SOURCE LICENSE
+
+Copyright (c) 2026 Luigi's Box s.r.o., registered in Slovakia.
+All rights reserved.
+
+1. GRANT OF LICENSE
+
+   This software and associated documentation files (the "Software") are
+   proprietary to Luigi's Box s.r.o. ("Licensor"). Subject to the terms of
+   a valid, current commercial agreement between the Licensor and the
+   licensee ("Agreement"), the Licensor grants the licensee a limited,
+   non-exclusive, non-transferable, non-sublicensable license to use the
+   Software solely for the purposes defined in the Agreement.
+
+2. CONDITIONS OF USE
+
+   Use of the Software is permitted only:
+   (a) by a party that has entered into a valid Agreement with the Licensor;
+   (b) for the duration of that Agreement; and
+   (c) solely for the purposes expressly permitted under that Agreement.
+
+3. RESTRICTIONS
+
+   The licensee may not:
+   (a) copy, distribute, sublicense, sell, or transfer the Software or any
+       portion thereof to any third party;
+   (b) modify, adapt, translate, reverse engineer, decompile, or create
+       derivative works based on the core Software library. For the
+       avoidance of doubt, the licensee is permitted to write, modify,
+       and maintain integration code that interfaces with the Software
+       through its published public API, provided such integration code
+       does not incorporate, derive from, or replicate any portion of
+       the Software's internal implementation
+   (c) remove or alter any copyright, trademark, or proprietary notices
+       contained in the Software.
+   (d) use the Software, or any integration code built against it, to
+       communicate with, connect to, or interoperate with any backend
+       API, service, or infrastructure other than those operated by
+       Luigi's Box s.r.o. The Software is licensed exclusively for use
+       with Luigi's Box services. Any attempt to adapt, reconfigure, or
+       redirect the Software to function with a third-party service is 
+       a material breach of this license and the Agreement.
+
+4. TERMINATION AND RETURN OF SOURCE CODE
+
+   This license is effective until terminated. It terminates automatically,
+   without notice, upon expiry or termination of the Agreement. Upon
+   termination, the licensee must immediately cease all use of the Software
+   and permanently destroy all copies of the Software in its possession or
+   control, including source code, compiled versions, and any backups.
+   Upon request, the licensee shall provide the Licensor with written
+   confirmation of such destruction within 14 days.
+
+5. DISCLAIMER OF WARRANTIES
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+   OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
+   THE LICENSOR DOES NOT WARRANT THAT THE SOFTWARE WILL BE ERROR-FREE OR
+   UNINTERRUPTED.
+
+6. LIMITATION OF LIABILITY
+
+   TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL
+   THE LICENSOR BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL,
+   EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+   LOSS OF PROFITS, DATA, OR BUSINESS INTERRUPTION) ARISING OUT OF OR IN
+   CONNECTION WITH THE USE OR INABILITY TO USE THE SOFTWARE, EVEN IF
+   ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+7. GOVERNING LAW AND JURISDICTION
+
+   This license shall be governed by and construed in accordance with the
+   laws of the Slovak Republic, without regard to its conflict of law
+   provisions. Any disputes arising under this license shall be subject
+   to the exclusive jurisdiction of the courts of Bratislava, Slovakia.
+
+8. SEVERABILITY
+
+   If any provision of this license is found to be unenforceable or invalid
+   under applicable law, that provision shall be limited or eliminated to
+   the minimum extent necessary, and the remaining provisions shall continue
+   in full force and effect.
+
+9. ENTIRE AGREEMENT
+
+   This license, together with the Agreement, constitutes the entire
+   agreement between the parties with respect to the Software and
+   supersedes all prior or contemporaneous understandings regarding
+   such subject matter.

package/README.md

@@ -1,3 +1,489 @@
-# 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.
+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
+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
+> 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
+> changes.
+
+## Core principles
+
+### The problem
+
+Luma runs on storefronts we don'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,
+   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
+   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.
+
+### 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.
+- **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
+  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.
+- **Sense and reconcile, not imperative patching.** Host signals (URL changes,
+  DOM mutations, our 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 ours in one frame.
+  Its height is reserved from the last visit. Target: zero layout shift after
+  ours 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
+  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
+  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
+  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 we work
+
+- **One framework, many integrations.** Nothing site-specific in this
+  repository; each integration has its own, 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.
+
+What we accept in exchange: [Known limitations](#known-limitations).
+
+
+## Repository layout
+
+| 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) |
+| `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 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)).
+
+## What the customer includes
+
+Everything goes in the site's HTML, in `<head>`, on every page.
+`<distribution id>` is the site's distribution (`lbdr_…`).
+
+**Loader only** (a tag manager is fine): the site's own listing may flash
+before ours 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 our 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`: our 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). Our 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
+their 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
+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.
+
+## 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). 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.
+
+The package holds what an integration uses: the framework's source, the build
+config, `yarn luma` and the client 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
+                                   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
+  the page is ours. 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 |
+
+## 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 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.
+- **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
+  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
+  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 our 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 a customer would install 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; with the submodule,
+`"node luma/bin/luma.mjs"` after `yarn --cwd luma install`), 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 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 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 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 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.