@luigisbox/luma 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,118 @@
+# Changelog
+
+All notable changes to `@luigisbox/luma`. Follows [semver](https://semver.org);
+before 1.0, a minor version may break the integration API.
+
+## Unreleased
+
+## 0.5.0 — 2026-10-19
+
+Upgrading from 0.4.0: read **Changed** first.
+
+### Added
+
+- `search.queryUrl` hook: the search page URL for a phrase. Use it when the
+  site's server redirects its search form (e.g. `/search?q=x` → `/search/x/`).
+  Enter, suggestions and "show all results" then go straight to that page.
+- `search.pageWhileTyping`: `'prefetch'` (default), `'prerender'` or `false`.
+  `prerenderWhileTyping: true` equals `'prerender'`.
+- `clientConfig` option `framework` (name or list): build in support for these
+  frameworks only. List every framework that renders part of a page Luma runs
+  on. Unknown names fail the build.
+- `clientConfig` option `serverRendering: false`: leave out hydration of
+  server-rendered listings.
+- `clientConfig` option `locales`: ship only these dictionaries (plus English).
+  Unknown locales or an empty list fail the build.
+
+### Changed
+
+- The build includes only widgets that have a folder (`autocomplete/`,
+  `search/`, `plp/`, `recommender <name>/`). Config for a widget without a
+  folder is ignored. A `recommender` folder without a name fails the build.
+  `yarn dev` still includes every widget.
+- These are built only if their name appears literally in a `.ts`, `.js` (or
+  variant) or `.html` file of the integration's repository, outside
+  `node_modules`, `dist` and hidden folders:
+  - attributes `data-lbx-cart`, `data-lbx-drawer`, `data-lbx-menu`,
+    `data-lbx-dropdown`
+  - hooks `onRender`, `readQuery`, `queryUrl`, `facetsFor`, `onOpen`,
+    `onClose`, `onSelect`, `onReady`
+  - options `emptyValues`, `prerenderWhileTyping` / `pageWhileTyping`,
+    `contentVisibility`
+
+  A name that only appears in a `.vue`, `.svelte` or `.hbs` file or in a
+  package does not count.
+- The search page for the typed phrase is prefetched by default. Set
+  `search.pageWhileTyping: false` to turn it off.
+- Results fetched while typing are cached per query, not per URL.
+- Enter in the search form follows the browser's implicit submission rules.
+- The `_config.ts` check (no functions) runs in development only.
+
+### Fixed
+
+- WebKit: when frames stalled, the site's listing could show instead of
+  Luma's.
+- Safari: listing images were all fetched on render, twice. Bind `src` last
+  in your own `<img>` templates too.
+- WebKit: two chunks were fetched twice per page.
+- Autocomplete: ARIA attributes could stay on the site's input after focus
+  left.
+
+## 0.4.0 — 2026-10-16
+
+### Added
+
+- Readers can return `{ reference, attributedToList: true }` for clicks and
+  add-to-carts on the site's own lists.
+
+### Fixed
+
+- Analytics: clicks and add-to-carts from Luma's widgets were never credited
+  to the search or recommendation that showed the product. They now carry
+  `attributed_to_list: true`, as does GA4 `select_item`.
+- Early hold now covers search routes with the query in the path (`urlMatch`
+  with a capture group). The snippet is unchanged.
+
+## 0.3.0 — 2026-10-15
+
+### Added
+
+- `alignTo: { field, column }` for the autocomplete panel. By default the
+  panel stays within the page's content column.
+
+### Changed
+
+- Cancelling the phone autocomplete sheet restores the site's input value.
+- Back closes an open staged filter drawer (`facetsApply`) and discards its
+  changes.
+- Reloading a listing within a minute after "show more" restores it as left.
+
+### Fixed
+
+- Phone autocomplete sheet: sized to the visible viewport, shown in
+  landscape, `autocorrect="off"`, keeps letters typed while it opens.
+- Autocomplete: lists scroll to top on new results; top product's prices
+  sit under its title.
+- iOS Safari: Back to a listing restores position and "show more" pages.
+- Listing position survives a reload or a redirect back within a minute.
+- Position is restored at the clicked link, not a hidden copy.
+- Staged drawer: Apply scrolls to the listing's top; crossing a breakpoint
+  closes the drawer.
+- A filter group opened by a selection stays open when the value is
+  unticked.
+- Range slider: touch drag on the track follows the finger; vertical scroll
+  starting on the track doesn't move a thumb.
+
+## 0.2.0 — 2026-10-13
+
+### Added
+
+- Analytics, configured in `_global/_analytics.ts`: one `collect.<event>` line
+  per event, with triggers (`lumaPages`, `lumaClicks`, `lumaCarts`, `dl`,
+  `domClick`, `urlChange`, `mutationOf`, `xhrMatching`, `manual`) and readers
+  (`fromLuma`, `fromGa4` or a function). `analytics: false` turns it off.
+- `yarn luma chrome --allow HOST`: keep that host's Luigi's Box scripts.
+
+## 0.1.0 — 2026-10-12
+
+First published version.

package/README.md

@@ -10,10 +10,10 @@ 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.5.0) may change the
+> **Pre-release.** Until 1.0, a minor version (0.6.0) may change the
 > integration API (config keys, template scope, the build); a patch version
-> (0.4.1) only fixes. Depend on `^0.4.0` to take fixes without breaking
-> changes.
+> (0.5.1) only fixes. Depend on `^0.5.0` to take fixes without breaking
+> changes. [`CHANGELOG.md`](CHANGELOG.md) says what each version changed.
 
 ## Core principles
 
@@ -245,6 +245,51 @@ import { clientConfig } from '@luigisbox/luma/build/vite.mjs';
 export default clientConfig(import.meta.url, { plugins: [mkcert()], server: { host: 'localhost', https: {} } });
 ```
 
+`framework` names the site's frontend framework, so the build carries Luma's
+support for that framework only. Without it, every integration carries the
+support for all of them (waiting for each one's hydration, writing URLs through
+its router, keeping out of its page snapshots), and Luma tells them apart on
+each page. Declared, a listing page loads about 1.4 to 2.3 kB gzip less, and
+every page about 0.2 kB less unless React hydrates the whole document. It is
+one of the following, or a list of them:
+
+| `framework` | the site |
+|---|---|
+| `next` | Next.js (app or pages router) |
+| `remix`, `react-router` | Remix, React Router 7, Hydrogen |
+| `react` | a React app in a root element (Vite, Create React App) |
+| `vue`, `nuxt` | Vue 2 or 3, Nuxt |
+| `angular` | Angular |
+| `svelte`, `sveltekit` | a Svelte app, SvelteKit |
+| `astro` | Astro (add the framework of its islands that hold Luma's anchors) |
+| `turbo` | Turbo Drive or Turbolinks |
+| `none` | server-rendered pages: jQuery, htmx, Alpine |
+
+```ts
+export default clientConfig(import.meta.url, { framework: 'vue', plugins: [mkcert()], server: { host: 'localhost', https: {} } });
+```
+
+`serverRendering: false` declares that the site has no server-rendered
+listings (the server-side includes above): the build then leaves out adopting
+and hydrating the server's markup, about 0.9 kB gzip on a listing page. Leave
+it out when the site uses them or may; in development Luma reports
+server-rendered markup a build without them meets.
+
+`locales` lists the locales the site uses (`['cs', 'sk']`): every page then
+carries the map of those dictionaries and English only (about 20 B gzip per
+locale left out). A widget in a locale not listed reads English. Without it,
+every locale Luma has a dictionary for. A locale Luma has no dictionary for
+fails the build.
+
+List every framework that renders a part of the page Luma places into or
+navigates with, on every page Luma runs on (`['astro', 'react']` for an Astro
+site with React islands). Without its framework's support, Luma does not
+wait for that framework's hydration: React or Svelte renders the page anew,
+Vue drops Luma's element, Angular binds the wrong element, a router puts its
+own URL back. In development (`yarn dev`) Luma reports a framework the page
+uses and the build leaves out in `window.__lbx.health.errors`. An unknown name
+fails the build.
+
 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
@@ -265,19 +310,31 @@ integration/
   recommender <name>/              _config.ts [_init.ts] _translations.ts
 ```
 
-- **`_config.ts` is JSON** (checked at boot); anything that needs code goes in
+- **`_config.ts` is JSON** (checked at boot in development: `yarn dev`);
+  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`.
+- **A widget is its folder.** The build carries only the widgets the
+  integration has folders for (`autocomplete/`, `search/`, `plp/`,
+  `recommender <name>/`) and analytics only where a folder has an
+  `_analytics.ts`: an integration with an autocomplete only loads about half
+  as much on every page as one with every widget. A config `_global/_init.ts`
+  creates for a widget without its folder is ignored. The development server
+  (`yarn dev`) carries every widget.
 - **`_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
+  runs (`disabled`, `active`, `readQuery`, `queryUrl`, `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' })`.
+  The build calls `onRender`, `readQuery`, `queryUrl`, `facetsFor` and the autocomplete's
+  `onOpen`, `onClose`, `onSelect`, `onReady` only where a file of the
+  integration's repository (a script or `.html` file, not in `node_modules`, `dist` or a hidden folder) names them, as setting
+  them does (`config.search.onRender = …`).
 - **`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.
@@ -328,7 +385,10 @@ export default ({ r, i, img, price }: SearchResultScope) => html`
 - **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).
+  `_global.images` (srcset, sizes, the eager first row, placeholders). In
+  your own `<img>`, bind `src` last: Safari starts the fetch when `src` is
+  set, so a `loading` or `srcset` bound after it loads every image at once,
+  and twice.
 - **Pagination** is "show more" only: templates get `results`, `more` and
   `showMore`; there are no numbered pages.
 - **No results under filters**: the scope still holds the selected groups,
@@ -348,11 +408,17 @@ export default ({ r, i, img, price }: SearchResultScope) => html`
 ### Behaviour switches
 
 On by default unless noted; each falls back to what the page would do anyway.
+`emptyValues`, `prerenderWhileTyping` and `contentVisibility`, off by
+default, are in the build only where a file of the integration's repository
+(a script or `.html` file, not in `node_modules`, `dist` or a hidden folder) names them, as `_config.ts` or `_init.ts` does when
+it sets them; a switch on by default that no file names is built as on.
 
 | 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 | |
+| `search.pageWhileTyping` (`'prefetch'`, `'prerender'`, `false`) | the search page of the typed phrase is fetched ahead (Chrome, Edge; Firefox and Safari as they ship it), so Enter from another page skips the site's server render; `'prerender'` renders it ahead as well (Chrome, Edge) | the site cannot take a document request per typed phrase; `'prerender'` only where its tags wait for `prerenderingchange` |
+| `search.queryUrl` (an `_init.ts` hook, off unless set) | where the site's server redirects its search form to the query's page (`/search?q=x` to `/search/x/`), names that page: Enter, the autocomplete's "show all" and a picked query load it directly, without the redirect, and the result fetched while typing is shown there | the form's other fields decide the page, or the site must handle every search itself |
 | `restoreOnBack` | Back from a product restores the listing (every page shown) and the followed tile's position, as does the page loaded again within a minute of following a link (a reload, a link whose server redirects back to it); Luma turns the browser's own scroll restoration (`history.scrollRestoration`) off for the listing's history entry until it has placed the page, unless the site set it | |
 | `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 |
@@ -416,7 +482,7 @@ collect.purchase.on(dl('purchase')).read(fromGa4.purchase);
 |---|---|---|
 | `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? }` |
+| `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. The attribute is written in a template of the integration as `data-lbx-cart`: the build includes add-to-cart only where a file of the integration's repository (a script or `.html` file, not in `node_modules`, `dist` or a hidden folder) has it | `{ 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 }` |
@@ -522,7 +588,8 @@ integration repository").
   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).
+  (`speculation: false` turns it off), and the search page fetched ahead
+  while typing a document per settled phrase (`search.pageWhileTyping: false`).
 - **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

package/build/baseline.mjs

@@ -53,8 +53,8 @@ export const ALLOW = [
   {
     // Limited availability (Chromium only). document.prerendering through `any`, as above.
     feature: 'speculation-rules',
-    files: ['src/core/speculation.ts', 'src/core/takeover.ts', 'src/main.ts'],
-    why: "The prerender rule is added only when HTMLScriptElement.supports('speculationrules'); document.prerendering is undefined (falsy) elsewhere, so a hold's timer starts at once.",
+    files: ['src/core/speculation.ts', 'src/core/takeover.ts', 'src/main.ts', 'src/widgets/search/speculate.ts'],
+    why: "The product-page prerender rule, and the search page of the phrase typed fetched ahead (prerendered with pageWhileTyping 'prerender'), are added only when HTMLScriptElement.supports('speculationrules'); without it Enter loads the page as usual and its result comes from the stash. document.prerendering is undefined (falsy) elsewhere, so a hold's timer starts at once.",
   },
 ];
 

package/build/vite.mjs

@@ -17,17 +17,21 @@ const FRAMEWORK = resolve(dirname(fileURLToPath(import.meta.url)), '../src');
 // One lazy chunk per widget plus what they share, so a page loads few files:
 //   lbx-core          lit, the template registry, a11y, core/support (i18n,
 //                     images, speculation rules) and the integration's shared
-//                     _global templates (the product tile): every widget's
+//                     _global templates (the product tile): every widget's;
+//                     a core module one chunk alone reaches goes with it
+//                     (soleUser: the listing's contrast toggle, fold, …)
 //   lbx-listing       search results and category pages (one listing: plp is
 //                     a route of it) with the integration's search/ templates
 //   lbx-autocomplete  lbx-recommender   each widget with its templates
-//   lbx-plp  lbx-place  lbx-search  lbx-speculate  lbx-token   the plp widget and its templates,
-//                     placement and recommender triggers, the search page's own,
-//                     search while typing, minting the token (chunkOf)
+//   lbx-plp  lbx-place  lbx-search  lbx-search-in-place  lbx-speculate  lbx-token
+//                     the plp widget and its templates, placement and
+//                     recommender triggers, the search page's own, a new query
+//                     in place, search while typing (and Enter straight to the
+//                     query's page), minting the token (chunkOf)
 //   lbx-nav           what search while typing (lbx-speculate) needs, a
 //                     search page's first request (widgets/search/first.ts)
 //                     and what they share with the listing (the route, query
-//                     building, stash, in-place query, URL writing): typing on
+//                     building, stash, a form's URL, 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
@@ -82,17 +86,19 @@ export const chunkOf = (id) => {
   // Hydration of server-rendered listings: only those pages load it.
   // lit-html's private SSR support is the hydrator's alone (not every widget page's lbx-core).
   if (/\/node_modules\/(@lit-labs\/ssr-client\/|lit-html\/private-ssr-support\.js)/.test(id)) return 'lbx-hydrate';
-  // Helpers one widget alone uses go with it, not into lbx-core (every widget's).
-  if (/\/src\/core\/color\.ts$/.test(id)) return 'lbx-autocomplete';
-  if (/\/src\/core\/a11y-keys\.ts$/.test(id)) return 'lbx-listing';
   // Placing our elements (core/reconciler.ts) and the recommenders' triggers:
   // pages with a listing or a recommender, in parallel with their other chunks.
   if (/\/src\/core\/(reconciler|recommenders)\.ts$/.test(id)) return 'lbx-place';
-  // The search page's own (its start, a new query in place): not in lbx-listing,
-  // which a category page loads too (2.1 kB gzip it never ran).
-  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';
+  // The listing's high-contrast toggle: only a site that turns it on loads it (widgets/listing/element.ts).
+  if (/\/src\/core\/contrast-toggle\.ts$/.test(id)) return 'lbx-contrast';
+  // The search page's own: not in lbx-listing, which a category page loads too
+  // (2.1 kB gzip it never ran).
+  if (/\/src\/widgets\/search\/index\.ts$/.test(id)) return 'lbx-search';
+  // A new query in place, and taking a submit of the site's search form (submit.ts, direct.ts's too: a
+  // category page never takes one): asked for as lbx-search runs, not waited for (widgets/search/index.ts).
+  if (/\/src\/widgets\/search\/(in-place|submit)\.ts$/.test(id)) return 'lbx-search-in-place';
+  // Search while typing, and Enter straight to the query's page (main.ts loads both once the shopper types): not in lbx-nav, which a listing page loads at once.
+  if (/\/src\/widgets\/search\/(speculate|direct)\.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.
@@ -108,7 +114,31 @@ export const chunkOf = (id) => {
 // The entry's own modules are named into the entry chunk (rollupOptions.input's
 // key) rather than left out: Rollup would pull a module a manual chunk depends
 // on into that chunk, entry or not.
-const manualChunks = (id, { getModuleInfo, getModuleIds }) => (entryGraph(getModuleInfo, getModuleIds).has(id) ? 'integration' : chunkOf(id));
+//
+// A module bound for lbx-core (every widget's) that one other chunk alone
+// reaches (directly, or through other lbx-core modules) goes with that chunk:
+// a listing's helper is not on an autocomplete page (core/fold.ts, a11y-keys,
+// color, the contrast toggle).
+const soleUser = (id, getModuleInfo, entry, seen = new Set([id])) => {
+  const users = new Set();
+  for (const by of [...(getModuleInfo(id)?.importers ?? []), ...(getModuleInfo(id)?.dynamicImporters ?? [])]) {
+    if (seen.has(by)) continue;
+    seen.add(by);
+    const c = entry.has(by) ? 'integration' : chunkOf(by);
+    if (c === 'lbx-core') for (const u of soleUser(by, getModuleInfo, entry, seen)) users.add(u);
+    else users.add(c);
+  }
+  return users;
+};
+const manualChunks = (id, { getModuleInfo, getModuleIds }) => {
+  const entry = entryGraph(getModuleInfo, getModuleIds);
+  if (entry.has(id)) return 'integration';
+  const c = chunkOf(id);
+  if (c !== 'lbx-core') return c;
+  const users = soleUser(id, getModuleInfo, entry);
+  const [only] = users;
+  return users.size === 1 && only && only !== 'integration' ? only : c;
+};
 
 /**
  * Template scope members Luma no longer has, and what replaces each. A
@@ -356,7 +386,7 @@ export const dedentTemplates = (ts, code, file) => {
   for (const [a, b, s] of edits.sort((x, y) => y[0] - x[0])) out = out.slice(0, a) + s + out.slice(b);
   return out;
 };
-const templateText = (root) => {
+export const templateText = (root) => {
   let ts;
   // Module ids are real paths: an integration/ reached through a symlink too.
   const dir = resolve(root, 'integration');
@@ -377,6 +407,50 @@ const templateText = (root) => {
   };
 };
 
+/**
+ * lit-html's directives (`@/lit`) as free of side effects: each module only
+ * defines its directive, and one no template uses is left out. Without this
+ * one assigning its class's static fields (unsafeHTML: `directiveName`,
+ * `resultType`) stays in lbx-core though no template uses it (0.6 kB, found
+ * 2026-10-17); lit-html's package.json declares no `sideEffects`.
+ */
+const pureDirectives = () => ({
+  name: 'lbx-pure-directives',
+  apply: 'build',
+  transform(code, id) {
+    if (!/\/node_modules\/lit-html\/directives\/[\w-]+\.js$/.test(id.split('?')[0])) return null;
+    return { code, map: null, moduleSideEffects: false };
+  },
+});
+
+/**
+ * Chunks nothing loads, left out: a widget the integration has no folder for
+ * (src/core/features.ts) leaves its modules tree-shaken to nothing, and the
+ * chunk they are named into (manualChunks) would still be emitted, empty
+ * but for imports. A chunk is loaded when another one imports it, statically
+ * or dynamically, or names its file (a preload list); the entry always.
+ */
+const unreachable = () => ({
+  name: 'lbx-unreachable-chunks',
+  apply: 'build',
+  enforce: 'post',
+  generateBundle(_, bundle) {
+    for (let pruned = true; pruned; ) {
+      pruned = false;
+      const chunks = Object.values(bundle).filter((c) => c.type === 'chunk');
+      for (const c of chunks) {
+        if (c.isEntry) continue;
+        const base = c.fileName.split('/').pop();
+        const used = chunks.some((o) => o !== c && (o.imports.includes(c.fileName) || o.dynamicImports.includes(c.fileName) || o.code.includes(base)));
+        if (!used) {
+          delete bundle[c.fileName];
+          pruned = true;
+        }
+      }
+    }
+  },
+});
+
 /**
  * A second minifier after Vite's esbuild pass: terser (two compress passes,
  * mangled top-level names in each module) finds what esbuild leaves (~3 %
@@ -419,6 +493,14 @@ const terse = () => ({
  * handles CSS dependencies, a <meta> nonce, a `preload` fallback and a
  * vite:preloadError event, none of which a Luma build uses: ~1 kB gzip of the
  * entry. A failed preload is the import's failure (it fetches the same file).
+ *
+ * `deps` starts with the imported chunk itself, even when it is the only one
+ * (resolveDependencies below; Vite's is [] then), so that it is marked: no
+ * later import's link preloads a chunk already imported or in flight. WebKit
+ * fetches such a link's chunk again and never uses the response (lbx-token
+ * and lbx-place, imported by the entry, then a listing's dependencies: twice
+ * per document, 2026-10-15). Its own link stays: Firefox holds the page's
+ * load event for a chunk an import() fetches, not for one a link does.
  */
 export const PRELOAD_HELPER = `const seen = {};
 export const __vitePreload = (load, deps, base) => {
@@ -444,10 +526,159 @@ const preloadHelper = () => ({
   },
 });
 
+/**
+ * The widgets the integration has (src/core/features.ts): a widget is its
+ * folder of integration/, analytics an _analytics.ts in any. Defined for a
+ * build from the folders (the entry leaves out a missing widget's triggers);
+ * the dev server sees folders come and go: everything there.
+ */
+/** Options on by default whose reads fold where no file of the integration names them (src/core/features.ts NAMED_*). */
+export const ON_BY_DEFAULT = ['preconnectImages', 'prefetchFilters', 'preload', 'fade', 'restoreOnBack', 'prefetchNextPage', 'inPlaceQuery', 'prefetchWhileTyping', 'earlyHold', 'speculation'];
+
+export const featureDefines = (integrationDir) => {
+  const folders = existsSync(integrationDir) ? readdirSync(integrationDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name) : null;
+  // A recommender folder is `recommender <name>` (src/core/integration.ts slot: checked there in development only).
+  for (const f of folders ?? []) if (f.trim() === 'recommender') throw new Error(`integration/${f}: a recommender folder needs a name, e.g. "recommender home"`);
+  const has = (f) => String(!folders || f(folders));
+  // The integration repository's code and markup (integration/ and anything
+  // it imports from beside it; not node_modules, builds or hidden folders),
+  // read once: a feature only its own files can ask for (a template's
+  // attribute, a hook _init.ts sets).
+  let text;
+  const read = (dir) =>
+    readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
+      e.name.startsWith('.') || e.name === 'node_modules' || e.name === 'dist' ? [] : e.isDirectory() ? read(resolve(dir, e.name)) : /\.(ts|tsx|js|jsx|mts|mjs|cts|cjs|html)$/.test(e.name) ? [readFileSync(resolve(dir, e.name), 'utf8')] : [],
+    );
+  const inFiles = (...needles) => ((text ??= read(dirname(integrationDir)).join('\n')), needles.some((n) => text.includes(n)));
+  return {
+    __LBX_AUTOCOMPLETE__: has((d) => d.includes('autocomplete')),
+    __LBX_SEARCH__: has((d) => d.includes('search')),
+    __LBX_PLP__: has((d) => d.includes('plp')),
+    __LBX_RECOMMENDER__: has((d) => d.some((f) => f.split(/\s+/)[0] === 'recommender')),
+    __LBX_ANALYTICS__: has((d) => d.some((f) => existsSync(resolve(integrationDir, f, '_analytics.ts')))),
+    __LBX_WIDGET_INITS__: has((d) => d.some((f) => existsSync(resolve(integrationDir, f, '_widget.ts')))),
+    __LBX_HOST_STYLES__: has((d) => d.some((f) => existsSync(resolve(integrationDir, f, 'style-host.css')))),
+    __LBX_TRANSLATIONS__: has((d) => d.some((f) => existsSync(resolve(integrationDir, f, '_translations.ts')))),
+    __LBX_INITS__: has((d) => d.some((f) => existsSync(resolve(integrationDir, f, '_init.ts')))),
+    // Only an integration's templates make a cart button, a filter drawer or a menu (Luma's own have none).
+    __LBX_CART__: has(() => inFiles('data-lbx-cart')),
+    __LBX_DRAWER__: has(() => inFiles('data-lbx-drawer')),
+    __LBX_MENU__: has(() => inFiles('data-lbx-menu')),
+    __LBX_DROPDOWN__: has(() => inFiles('data-lbx-dropdown')),
+    // Hooks only the integration's code sets (_init.ts, _widget.ts: functions, never in _config.ts).
+    __LBX_AC_HOOKS__: has(() => inFiles('onOpen', 'onClose', 'onSelect', 'onReady')),
+    __LBX_ON_RENDER__: has(() => inFiles('onRender')),
+    __LBX_READ_QUERY__: has(() => inFiles('readQuery')),
+    __LBX_FACETS_FOR__: has(() => inFiles('facetsFor')),
+    __LBX_QUERY_URL__: has(() => inFiles('queryUrl')),
+    // Options off by default: a key no file names keeps its default.
+    __LBX_EMPTY_VALUES__: has(() => inFiles('emptyValues')),
+    __LBX_PRERENDER_TYPING__: has(() => inFiles('prerenderWhileTyping', 'pageWhileTyping')),
+    __LBX_CONTENT_VISIBILITY__: has(() => inFiles('contentVisibility')),
+    // Options on by default: one no file names is on.
+    ...Object.fromEntries(ON_BY_DEFAULT.map((k) => [`__LBX_NAMED_${k.replace(/[A-Z]/g, (c) => `_${c}`).toUpperCase()}__`, has(() => inFiles(k))])),
+  };
+};
+/** Luma's dictionaries' namespaces (src/locales/*.json) a build without the widget leaves out: plp reads search's too. */
+export const LOCALE_NAMESPACES = { autocomplete: ['AUTOCOMPLETE'], search: ['SEARCH', 'PLP'], plp: ['PLP'], recommender: ['RECOMMENDER'] };
+export const pruneDictionary = (json, defines) => {
+  const dict = JSON.parse(json);
+  for (const [ns, flags] of Object.entries(LOCALE_NAMESPACES)) if (flags.every((f) => defines[`__LBX_${f}__`] === 'false')) delete dict[ns];
+  return JSON.stringify(dict);
+};
+const features = (root) => {
+  let defines = null;
+  return {
+    name: 'lbx-features',
+    enforce: 'pre',
+    config(_, { command }) {
+      if (command !== 'build') return undefined;
+      defines = featureDefines(resolve(root, 'integration'));
+      return { define: defines };
+    },
+    // Before Vite's JSON plugin: the dictionary as JSON.
+    transform(code, id) {
+      if (!defines || !id.startsWith(FRAMEWORK) || !/\/locales\/[\w-]+\.json$/.test(id.split('?')[0])) return null;
+      return { code: pruneDictionary(code, defines), map: null };
+    },
+  };
+};
+
+/**
+ * The locales the site uses (`locales` of clientConfig: a list), so the
+ * entry's map of Luma's dictionaries (src/core/locales.ts, a glob) has those
+ * and English only: ~20 B gzip on every page per locale left out. A locale not
+ * listed reads English (loadDictionary's fallback). Not declared: every one.
+ */
+export const LOCALES = readdirSync(resolve(FRAMEWORK, 'locales')).filter((f) => f.endsWith('.json')).map((f) => f.slice(0, -5));
+export const localeGlob = (locales) => {
+  if (locales === undefined) return null;
+  if (!Array.isArray(locales) || !locales.length) throw new Error(`clientConfig: locales is a list of locales (${LOCALES.join(', ')}), not ${JSON.stringify(locales)}`);
+  for (const l of locales) if (!LOCALES.includes(l)) throw new Error(`clientConfig: Luma has no dictionary for locale ${JSON.stringify(l)}: one of ${LOCALES.join(', ')}`);
+  return [...new Set(['en', ...locales])].sort().map((l) => `../locales/${l}.json`);
+};
+const onlyLocales = (locales) => {
+  const glob = localeGlob(locales);
+  return {
+    name: 'lbx-only-locales',
+    enforce: 'pre',
+    transform(code, id) {
+      if (!glob || id.split('?')[0] !== resolve(FRAMEWORK, 'core/locales.ts')) return null;
+      const from = "import.meta.glob<Dictionary>('../locales/*.json',";
+      if (!code.includes(from)) return this.error('src/core/locales.ts: its dictionaries glob changed; update onlyLocales');
+      return { code: code.replace(from, `import.meta.glob<Dictionary>(${JSON.stringify(glob)},`), map: null };
+    },
+  };
+};
+
+/**
+ * Luma's support for the site's framework, in parts (src/core/frameworks.ts):
+ *   react          React roots and islands (hydration, Suspense)
+ *   documentReact  React hydrating the whole document (the entry's checks)
+ *   next           Next.js pages router (its router, its hydration measure)
+ *   vue            Vue 2 / 3 and Nuxt (mount, router)
+ *   angular        Angular hydration
+ *   sveltekit      SvelteKit (its root, its history entries)
+ *   astro          Astro (islands, ClientRouter history entries)
+ *   turbo          Turbo Drive / Turbolinks (snapshots, history, prefetch)
+ * A build has all of them unless the integration declares its framework(s)
+ * (`framework` of clientConfig: a name or a list): then only theirs, the rest
+ * left out of every chunk. Measured on the test fixture 2026-10-17: see
+ * test/browser/specs/budgets.spec.ts.
+ */
+export const SUPPORTS = ['react', 'documentReact', 'next', 'vue', 'angular', 'sveltekit', 'astro', 'turbo'];
+export const FRAMEWORKS = {
+  next: ['react', 'documentReact', 'next'],
+  remix: ['react', 'documentReact'],
+  'react-router': ['react', 'documentReact'],
+  react: ['react'],
+  vue: ['vue'],
+  nuxt: ['vue'],
+  angular: ['angular'],
+  svelte: [],
+  sveltekit: ['sveltekit'],
+  astro: ['astro'],
+  turbo: ['turbo'],
+  none: [],
+};
+
+/** The defines of a declaration (undefined: everything). */
+export const frameworkDefines = (framework) => {
+  const names = framework === undefined ? null : [framework].flat();
+  for (const f of names ?? [])
+    if (typeof f !== 'string' || !Object.hasOwn(FRAMEWORKS, f))
+      throw new Error(`clientConfig: unknown framework ${JSON.stringify(f)}: one of ${Object.keys(FRAMEWORKS).join(', ')}, a list of them, or leave it out`);
+  if (names && !names.length) throw new Error('clientConfig: framework is an empty list: name the site\'s framework(s), none, or leave it out');
+  const has = new Set(names ? names.flatMap((f) => FRAMEWORKS[f]) : SUPPORTS);
+  return Object.fromEntries(SUPPORTS.map((k) => [`__LBX_${k.replace(/[A-Z]/g, (c) => `_${c}`).toUpperCase()}__`, String(has.has(k))]));
+};
+
 /**
  * `overrides` are merged into the config; `plugins` are appended and `server`
  * is merged, so a client repo can add e.g. HTTPS for the loader's development
- * mode without losing ours.
+ * mode without losing ours. `framework` (FRAMEWORKS), `serverRendering`
+ * (false: the site has no server-rendered listings, src/core/features.ts SSR)
+ * and `locales` (onlyLocales) are Luma's, not Vite's.
  */
 export const clientConfig = (configUrl, overrides = {}) => {
   const root = dirname(fileURLToPath(configUrl));
@@ -456,11 +687,12 @@ export const clientConfig = (configUrl, overrides = {}) => {
   // may read it. Unset: any origin (convenient, but any page open in the
   // developer's browser could read the source while the server runs).
   const devOrigins = process.env.LBX_DEV_ORIGINS?.split(',').map((o) => o.trim()).filter(Boolean);
-  const { plugins = [], server = {}, ...rest } = overrides;
+  const { plugins = [], server = {}, framework, serverRendering, locales, ...rest } = overrides;
+  if (serverRendering !== undefined && typeof serverRendering !== 'boolean') throw new Error(`clientConfig: serverRendering is true or false, not ${JSON.stringify(serverRendering)}`);
   return {
     root,
     resolve: { alias: { '@': FRAMEWORK } },
-    define: { __VERSION__: JSON.stringify(new Date().toISOString()) },
+    define: { __VERSION__: JSON.stringify(new Date().toISOString()), ...frameworkDefines(framework), __LBX_SSR__: String(serverRendering !== false) },
     // css.postcss: {} stops Vite from picking up a PostCSS config from parent dirs.
     css: { postcss: {} },
     // Class fields are fields (tsconfig.json's ES2022), wherever Luma is: Vite
@@ -471,7 +703,7 @@ export const clientConfig = (configUrl, overrides = {}) => {
     // pre-bundled as a dependency: installed under node_modules/, Vite would.
     optimizeDeps: { exclude: ['@'] },
     base: './',
-    plugins: [preloadHelper(), scopeCheck(), unusedBuiltIns(root), rawCss(), templateText(root), terse(), ...plugins],
+    plugins: [preloadHelper(), scopeCheck(), features(root), onlyLocales(locales), unusedBuiltIns(root), rawCss(), templateText(root), pureDirectives(), terse(), unreachable(), ...plugins],
     server: {
       port: 8069,
       strictPort: true,
@@ -488,7 +720,8 @@ export const clientConfig = (configUrl, overrides = {}) => {
       // Syntax only: APIs are not polyfilled, which `yarn luma baseline` checks.
       target: 'baseline-widely-available',
       // Preload a lazy chunk's own dependencies in parallel with it.
-      modulePreload: { polyfill: false },
+      // Each import's own chunk first, even alone (Vite's []): the helper marks it.
+      modulePreload: { polyfill: false, resolveDependencies: (file, deps) => [file, ...deps.filter((d) => d !== file)] },
       rollupOptions: {
         input: { integration: resolve(root, 'integration/__integration.ts') },
         output: {