@luigisbox/luma 0.0.0-stage → 0.1.0

package/build/vite.mjs

@@ -0,0 +1,498 @@
+// Vite config for a client integration repository. The repo's own
+// vite.config.ts is a one-liner:
+//   import { clientConfig } from '@luigisbox/luma/build/vite.mjs';
+//   export default clientConfig(import.meta.url);
+//
+// Output (dist/), what the distribution platform's loader expects:
+//   luma-integration.js   the entry: configs, inits, sensing, triggers
+//   luma-chunks/*.js      per widget: code, templates, styles, dictionary (loaded on demand)
+
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { transformWithEsbuild } from 'vite';
+
+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
+//   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-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
+//                     any page and the listing need it, a page with only a
+//                     recommender does not
+//   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
+// and state for the prefetch, …) is never grouped: pulled into a lazy chunk,
+// it would make the entry import that chunk at boot. The entry's static graph
+// is computed from Rollup's module info, so a module moving into or out of the
+// entry needs no change here. _global/ files named after a widget
+// (template-recommender-*.ts) go with that widget only. Integration folders
+// are named after their widget (`recommender similar`): the first word says which.
+const KIND_CHUNK = { autocomplete: 'lbx-autocomplete', search: 'lbx-listing', plp: 'lbx-plp', recommender: 'lbx-recommender' };
+const NAV = /\/src\/(widgets\/listing\/(stash|query|state|flow)|widgets\/search\/(form-url|route|first)|core\/(url|listings|takeover|turbo|prefetch|stash|page))\.ts$/;
+const WIDGET = /\/src\/widgets\/([a-z]+)\//;
+const CORE = /\/src\/(lit\.ts|core\/|api\/)|\/node_modules\/lit-html\//;
+const entryGraphs = new WeakMap();
+/** Every module the entry imports statically (transitively). */
+const entryGraph = (getModuleInfo, getModuleIds) => {
+  let seen = entryGraphs.get(getModuleInfo);
+  if (seen) return seen;
+  seen = new Set();
+  const stack = [...getModuleIds()].filter((id) => getModuleInfo(id)?.isEntry);
+  while (stack.length) {
+    const id = stack.pop();
+    if (seen.has(id)) continue;
+    seen.add(id);
+    stack.push(...(getModuleInfo(id)?.importedIds ?? []));
+  }
+  entryGraphs.set(getModuleInfo, seen);
+  return seen;
+};
+export const chunkOf = (id) => {
+  // 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
+  // never gets here (the entry's, see manualChunks).
+  const own = id.match(/\/integration\/([^/]+)\/(?!template-|style-)[^/?]+\.[jt]s$/);
+  if (own) return own[1] === '_global' ? 'lbx-core' : KIND_CHUNK[own[1].split(/\s+/)[0]];
+  const m = id.match(/\/integration\/([^/]+)\/(?:template|style)-([^/?]+?)\.(?:ts|css)/);
+  if (m && m[2] !== 'host') {
+    const [, folder, name] = m;
+    const kind = (folder === '_global' ? name.split('-')[0] : folder.split(/\s+/)[0]);
+    return KIND_CHUNK[kind] ?? (folder === '_global' ? 'lbx-core' : `itg-${folder.replace(/\s+/g, '-')}`);
+  }
+  // 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';
+  // 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.
+  const loc = id.match(/\/src\/locales\/([\w-]+)\.json$/);
+  if (loc) return `lbx-locale-${loc[1]}`;
+  if (NAV.test(id)) return 'lbx-nav';
+  const w = id.match(WIDGET);
+  if (w) return KIND_CHUNK[w[1]] ?? (w[1] === 'listing' ? 'lbx-listing' : undefined);
+  if (CORE.test(id)) return 'lbx-core';
+};
+// 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));
+
+/**
+ * Template scope members Luma no longer has, and what replaces each. A
+ * template using one would render nothing for it, or a link to
+ * "…/undefined", with no error: the build fails instead (`yarn typecheck`
+ * catches every use; this catches the unmistakable ones in a build that
+ * does not typecheck).
+ */
+export const REMOVED_SCOPE = [
+  // 2026-10-02, "next page" only: no numbered pages.
+  [/\bpageLinks\b/, '`pageLinks` is gone (no numbered pages): render "show more" with `more` and `showMore`'],
+  [/\bsetPage\b/, '`setPage` is gone (no numbered pages): `@click=${s.showMore}` appends the next page'],
+  [/\bmore\s*\.\s*(?:href|patch)\b|\bgo\(\s*(?:\w+\s*\.\s*)?more\s*\)/, '`more` is a boolean now (no page URL): `<button data-lbx-more @click=${s.showMore}>`'],
+];
+/** The removed scope members a template's source uses: [{ line, message }]. */
+export const removedScopeUses = (code) => {
+  const out = [];
+  code.split('\n').forEach((text, i) => {
+    for (const [re, message] of REMOVED_SCOPE) if (re.test(text)) out.push({ line: i + 1, message });
+  });
+  return out;
+};
+const scopeCheck = () => ({
+  name: 'lbx-removed-scope',
+  enforce: 'pre',
+  transform(code, id) {
+    if (!/\/integration\/.+\/template-[^/]+\.ts$/.test(id.split('?')[0])) return null;
+    const uses = removedScopeUses(code);
+    if (uses.length) this.error(uses.map((u) => `${id.split('/integration/')[1]}:${u.line}: ${u.message}`).join('\n'));
+    return null;
+  },
+});
+
+/**
+ * Stylesheets imported as strings (`style-*.css?raw`: Luma's own widget styles,
+ * the integration's widget and host styles) minified, as Vite minifies the
+ * code around them: their comments and layout are for whoever edits them, not
+ * on every shopper's download (an integration's host styles are in the entry).
+ * esbuild's CSS minifier (Vite's own): it parses the CSS, so strings, comments
+ * and custom properties are safe, and it lowers nothing (no target).
+ */
+export const minifyCss = async (css) => (await transformWithEsbuild(css, 'style.css', { loader: 'css', minify: true, logLevel: 'silent' })).code.trim();
+const rawCss = () => ({
+  name: 'lbx-raw-css',
+  enforce: 'pre',
+  async transform(code, id) {
+    const [file, query] = id.split('?');
+    // A dependency's CSS is left as it is; Luma's own is minified, installed under node_modules/ too
+    if (query !== 'raw' || !file.endsWith('.css') || (file.includes('/node_modules/') && !file.startsWith(FRAMEWORK))) return null;
+    const m = /^export default (".*");?\s*$/s.exec(code);
+    if (!m) return null;
+    try {
+      return { code: `export default ${JSON.stringify(await minifyCss(JSON.parse(m[1])))};`, map: null };
+    } catch (e) {
+      // Not CSS esbuild can parse: shipped as written (the browser decides), and said.
+      this.warn(`${file}: not minified (${e.message.split('\n')[0]})`);
+      return null;
+    }
+  },
+});
+
+/**
+ * Built-in templates no instance can render are left out of the build. A
+ * widget's built-ins are an eager glob of its `template-*.ts`
+ * (src/widgets/<widget>/); an integration's file of the same name wins
+ * (src/core/context.ts). Widget code renders an entry template (ENTRY_TEMPLATES)
+ * and every other one is reached by `include('name')` from a template in use.
+ * So per instance using a widget's built-ins (search and category pages share
+ * the listing's; each recommender folder is an instance; a _global/ file only
+ * for the widget it is named after, as `widgetFiles` reads them) the templates
+ * in use are walked from the entries, each name resolved as the instance would
+ * (its folders', else the built-in); a built-in reached in no instance is
+ * never rendered: overridden everywhere, or only included by templates that
+ * are themselves overridden (an integration's own facets template drawing its
+ * own range slider leaves the built-in slider and its handlers, range.ts,
+ * unused). A template including a computed name (not a quoted literal) keeps
+ * every built-in of its widget. A built-in another built-in imports stays as
+ * far as it is imported (Rollup drops the unused rest). The build only: the
+ * dev server sees files come and go.
+ *
+ * `integration`: { folder: { name: source } }; `builtIns`: { widget: { name: source } }.
+ * Returns { widget: [built-in names to leave out] }.
+ */
+export const ENTRY_TEMPLATES = { autocomplete: ['autocomplete-box'], search: ['search-box'], recommender: ['recommender-box-default', 'recommender-popup'] };
+const includes = (src) => {
+  const calls = [...src.matchAll(/\binclude\(\s*(?:(['"])([\w-]+)\1)?/g)];
+  return calls.some((m) => !m[2]) ? null : calls.map((m) => m[2]);
+};
+export const unrenderedBuiltIns = (integration, builtIns) => {
+  const folders = Object.keys(integration);
+  const applies = (folder, name, kinds) => folder !== '_global' || !Object.keys(KIND_CHUNK).includes(name.split('-')[0]) || kinds.includes(name.split('-')[0]);
+  // Each widget's built-ins: the instances using them (their folders, and the kinds their _global/ files are read for).
+  const users = {
+    autocomplete: folders.includes('autocomplete') ? [{ folders: ['_global', 'autocomplete'], kinds: ['autocomplete'] }] : [],
+    search: [
+      ...(folders.includes('search') ? [{ folders: ['_global', 'search'], kinds: ['search'] }] : []),
+      ...(folders.includes('plp') ? [{ folders: ['_global', 'search', 'plp'], kinds: ['search', 'plp'] }] : []),
+    ],
+    recommender: folders.filter((f) => f.split(/\s+/)[0] === 'recommender').map((f) => ({ folders: ['_global', f], kinds: ['recommender'] })),
+  };
+  const out = {};
+  for (const [widget, instances] of Object.entries(users)) {
+    if (!instances.length) continue;
+    const mine = builtIns[widget] ?? {};
+    const used = new Set();
+    let dynamic = false;
+    for (const i of instances) {
+      // The instance's template of a name: its last folder having it, else the built-in.
+      const resolveName = (name) => {
+        for (const f of [...i.folders].reverse()) if (integration[f]?.[name] != null && applies(f, name, i.kinds)) return { src: integration[f][name], builtIn: false };
+        return mine[name] != null ? { src: mine[name], builtIn: true } : null;
+      };
+      const seen = new Set();
+      const todo = [...ENTRY_TEMPLATES[widget]];
+      while (todo.length) {
+        const name = todo.pop();
+        if (seen.has(name)) continue;
+        seen.add(name);
+        const t = resolveName(name);
+        if (!t) continue;
+        if (t.builtIn) used.add(name);
+        const next = includes(t.src);
+        if (next == null) dynamic = true;
+        else todo.push(...next);
+      }
+    }
+    out[widget] = dynamic ? [] : Object.keys(mine).filter((n) => !used.has(n)).sort();
+  }
+  return out;
+};
+/** { folder: { template name: source } } of an integration/ directory, or of a widget directory's built-ins. */
+const templateSources = (dir) => {
+  const out = {};
+  if (!existsSync(dir)) return out;
+  for (const e of readdirSync(dir, { withFileTypes: true }))
+    if (e.isDirectory()) {
+      out[e.name] = {};
+      for (const f of readdirSync(resolve(dir, e.name))) {
+        const n = /^template-(.+)\.ts$/.exec(f)?.[1];
+        if (n) out[e.name][n] = readFileSync(resolve(dir, e.name, f), 'utf8');
+      }
+    }
+  return out;
+};
+const BUILT_INS = /\/src\/widgets\/(autocomplete|search|recommender)\/(?:index|assets)\.ts$/;
+
+/**
+ * A built-in template's own rules in its widget's stylesheet, marked
+ * `/* @lbx-part <template> ... *\/ … /* @lbx-part-end *\/`, go with the
+ * template, unless a template of the integration (the widget's folders) uses
+ * one of their distinctive classes: those the replaced built-in renders and no
+ * kept built-in does (an override may reuse the built-in's markup; then its
+ * rules stay). A rule of the part needs one of them (`.sheet .pill`), so with
+ * none rendered it matches nothing.
+ */
+const classesOf = (css) => new Set([...css.replace(/\/\*[\s\S]*?\*\//g, '').matchAll(/\.(-?[_a-zA-Z][\w-]*)/g)].map((m) => m[1]));
+const wordsOf = (sources) => new Set(sources.flatMap((s) => s.match(/[-\w]+/g) ?? []));
+const PART = /\/\* @lbx-part ([\w-]+)[^*]*\*\/([\s\S]*?)\/\* @lbx-part-end \*\//g;
+/** The stylesheet without the parts of `names`. */
+export const withoutParts = (css, names) => css.replace(PART, (all, n) => (names.includes(n) ? '' : all));
+export const cssPartUnused = (partCss, droppedSrc, keptSrcs, integrationSrcs) => {
+  const dropped = wordsOf([droppedSrc]);
+  const kept = wordsOf(keptSrcs);
+  const theirs = wordsOf(integrationSrcs);
+  const own = [...classesOf(partCss)].filter((c) => dropped.has(c) && !kept.has(c));
+  return own.length > 0 && !own.some((c) => theirs.has(c));
+};
+const unusedBuiltIns = (root) => {
+  let drop = null;
+  let cssDrop = null;
+  return {
+    name: 'lbx-unused-built-ins',
+    apply: 'build',
+    enforce: 'pre',
+    buildStart() {
+      const itg = templateSources(resolve(root, 'integration'));
+      const builtIns = templateSources(resolve(FRAMEWORK, 'widgets'));
+      drop = unrenderedBuiltIns(itg, builtIns);
+      // The left-out templates' stylesheet parts no template of the widget's folders still uses.
+      cssDrop = {};
+      for (const [widget, names] of Object.entries(drop)) {
+        const theirs = [itg._global, itg[widget]].flatMap((f) => Object.values(f ?? {}));
+        const kept = Object.entries(builtIns[widget] ?? {}).filter(([n]) => !names.includes(n)).map(([, src]) => src);
+        const dir = resolve(FRAMEWORK, 'widgets', widget);
+        const sheets = existsSync(dir) ? readdirSync(dir).filter((f) => /^style-[\w-]+\.css$/.test(f)).map((f) => readFileSync(resolve(dir, f), 'utf8')) : [];
+        cssDrop[widget] = names.filter((n) => sheets.some((css) => [...css.matchAll(PART)].some(([, p, body]) => p === n && cssPartUnused(body, builtIns[widget]?.[n] ?? '', kept, theirs))));
+      }
+    },
+    transform(code, id) {
+      // A widget's own stylesheet (?raw, before it is minified): without the parts of templates left out.
+      const css = /\/src\/widgets\/(\w+)\/style-[\w-]+\.css\?raw$/.exec(id);
+      if (css && id.startsWith(FRAMEWORK)) {
+        const parts = cssDrop?.[css[1]];
+        const raw = /^export default (".*");?\s*$/s.exec(code);
+        if (!parts?.length || !raw) return null;
+        return { code: `export default ${JSON.stringify(withoutParts(JSON.parse(raw[1]), parts))};`, map: null };
+      }
+      const m = BUILT_INS.exec(id.split('?')[0]);
+      const names = m && id.startsWith(FRAMEWORK) ? drop?.[m[1]] : null;
+      if (!names?.length) return null;
+      const glob = "import.meta.glob('./template-*.ts',";
+      if (!code.includes(glob)) return null;
+      return { code: code.replace(glob, `import.meta.glob(${JSON.stringify(['./template-*.ts', ...names.map((n) => `!./template-${n}.ts`)])},`), map: null };
+    },
+  };
+};
+
+/**
+ * lit templates without their source indentation: in an `html`/`svg` tagged
+ * template's static text, the spaces and tabs after a line break are layout
+ * for whoever edits the template. HTML collapses them with the line break (and
+ * `white-space: pre-line` keeps the line break, which stays), so dropping them
+ * renders the same; only preformatted whitespace would show them, so a file
+ * mentioning `<pre`, `<textarea` or a `pre`/`pre-wrap`/`break-spaces`
+ * white-space is left as written. Templates are found by TypeScript's parser
+ * (strings, comments, regexes and nested templates are parsed, not guessed).
+ */
+export const dedentTemplates = (ts, code, file) => {
+  if (!/\b(?:html|svg)`/.test(code) || /<pre\b|<textarea\b|white-space\s*:\s*(?:pre|pre-wrap|break-spaces)\b/i.test(code)) return null;
+  const sf = ts.createSourceFile(file, code, ts.ScriptTarget.Latest, true, file.endsWith('.js') ? ts.ScriptKind.JS : ts.ScriptKind.TS);
+  const edits = [];
+  const literal = (node, open, close) => {
+    // The literal's raw text between its delimiters (` or } before, ` or ${ after).
+    const a = node.getStart(sf) + open;
+    const b = node.getEnd() - close;
+    const raw = code.slice(a, b);
+    // Not after a line continuation (a backslash before the line break).
+    const out = raw.replace(/(?<!\\)\n[ \t]+/g, '\n');
+    if (out !== raw) edits.push([a, b, out]);
+  };
+  const visit = (n) => {
+    if (ts.isTaggedTemplateExpression(n) && ts.isIdentifier(n.tag) && (n.tag.text === 'html' || n.tag.text === 'svg')) {
+      const t = n.template;
+      if (ts.isNoSubstitutionTemplateLiteral(t)) literal(t, 1, 1);
+      else {
+        literal(t.head, 1, 2);
+        for (const s of t.templateSpans) literal(s.literal, 1, ts.isTemplateTail(s.literal) ? 1 : 2);
+      }
+    }
+    ts.forEachChild(n, visit);
+  };
+  visit(sf);
+  if (!edits.length) return null;
+  let out = code;
+  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) => {
+  let ts;
+  // Module ids are real paths: an integration/ reached through a symlink too.
+  const dir = resolve(root, 'integration');
+  const itg = existsSync(dir) ? realpathSync(dir) : dir;
+  return {
+    name: 'lbx-template-text',
+    apply: 'build',
+    enforce: 'pre',
+    async transform(code, id) {
+      const file = id.split('?')[0];
+      // Luma's own templates and the integration's (Luma installed under node_modules/ too)
+      if (!/\.[jt]s$/.test(file) || !(file.startsWith(FRAMEWORK) || file.startsWith(itg))) return null;
+      if (!/\b(?:html|svg)`/.test(code)) return null;
+      ts ??= (await import('typescript')).default;
+      const out = dedentTemplates(ts, code, file);
+      return out == null ? null : { code: out, map: null };
+    },
+  };
+};
+
+/**
+ * A second minifier after Vite's esbuild pass: terser (two compress passes,
+ * mangled top-level names in each module) finds what esbuild leaves (~3 %
+ * gzip: measured on a production integration 2026-10-10, 0.6 kB of the entry, 0.9 kB of the
+ * listing). On the finished chunks (generateBundle: after every renderChunk,
+ * Vite's own minify and target included). Luma's dependency, resolved from
+ * here (an integration installs Luma's dependencies: yarn install); without it, esbuild's output as before,
+ * and said. Source maps of a build that asks for them stay esbuild's: not run.
+ */
+// wrap_func_args off: terser's parentheses around every function argument are a
+// V8 eager-compile hint, useless for our callbacks and 0.3 kB gzip of bytes.
+export const terserOptions = { module: true, ecma: 2020, compress: { passes: 2 }, mangle: true, format: { comments: false, wrap_func_args: false } };
+const terse = () => ({
+  name: 'lbx-terser',
+  apply: 'build',
+  enforce: 'post',
+  async generateBundle(opts, bundle) {
+    if (opts.sourcemap) return;
+    let minify;
+    try {
+      ({ minify } = await import('terser'));
+    } catch {
+      return this.warn('terser is not installed (yarn install): esbuild\'s minification only');
+    }
+    await Promise.all(
+      Object.values(bundle)
+        .filter((c) => c.type === 'chunk')
+        .map(async (c) => {
+          const r = await minify(c.code, terserOptions);
+          if (r.code) c.code = r.code;
+        }),
+    );
+  },
+});
+
+/**
+ * Vite's preload helper (what a dynamic import() becomes: preload the chunk's
+ * own imports, then import it) replaced with what our chunks need: a
+ * modulepreload link per dependency, once, with the page's CSP nonce. Vite's
+ * 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).
+ */
+export const PRELOAD_HELPER = `const seen = {};
+export const __vitePreload = (load, deps, base) => {
+  for (const d of deps || []) {
+    const href = new URL(d, base).href;
+    if (seen[href]) continue;
+    seen[href] = 1;
+    const l = document.createElement('link');
+    l.rel = 'modulepreload';
+    l.href = href;
+    const nonce = document.querySelector('script[nonce]')?.nonce;
+    if (nonce) l.nonce = nonce;
+    document.head.append(l);
+  }
+  return load();
+};`;
+const preloadHelper = () => ({
+  name: 'lbx-preload-helper',
+  apply: 'build',
+  enforce: 'pre',
+  load(id) {
+    if (id === '\0vite/preload-helper.js') return { code: PRELOAD_HELPER, moduleSideEffects: false };
+  },
+});
+
+/**
+ * `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.
+ */
+export const clientConfig = (configUrl, overrides = {}) => {
+  const root = dirname(fileURLToPath(configUrl));
+  // The dev server serves the integration's source to the site's pages: only
+  // the origins in LBX_DEV_ORIGINS (comma-separated, e.g. https://www.shop.example)
+  // 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;
+  return {
+    root,
+    resolve: { alias: { '@': FRAMEWORK } },
+    define: { __VERSION__: JSON.stringify(new Date().toISOString()) },
+    // 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
+    // reads no tsconfig for a file under node_modules/, and esbuild without one
+    // turns them into constructor assignments (the package, unlike luma/).
+    esbuild: { tsconfigRaw: { compilerOptions: { useDefineForClassFields: true } } },
+    // Luma's source (`@/…`) is served as modules like the integration's, not
+    // pre-bundled as a dependency: installed under node_modules/, Vite would.
+    optimizeDeps: { exclude: ['@'] },
+    base: './',
+    plugins: [preloadHelper(), scopeCheck(), unusedBuiltIns(root), rawCss(), templateText(root), terse(), ...plugins],
+    server: {
+      port: 8069,
+      strictPort: true,
+      cors: devOrigins ? { origin: devOrigins } : true,
+      // Chrome's Local Network Access: a public page loading from localhost.
+      headers: { 'Access-Control-Allow-Private-Network': 'true' },
+      ...server,
+    },
+    build: {
+      emptyOutDir: true,
+      // Baseline Widely available: the browser
+      // versions Vite 7 pins for it (Chrome/Edge 107, Firefox 104, Safari 16:
+      // Widely available on 2025-05-01), so modern syntax ships as written.
+      // 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 },
+      rollupOptions: {
+        input: { integration: resolve(root, 'integration/__integration.ts') },
+        output: {
+          entryFileNames: 'luma-[name].js',
+          chunkFileNames: 'luma-chunks/[name]-[hash].js',
+          assetFileNames: 'luma-assets/[name]-[hash].[ext]',
+          manualChunks,
+          // Merges tiny chunks into ones loaded with them where that cannot change
+          // execution order: fewer requests per page, the entry stays untouched.
+          experimentalMinChunkSize: 4096,
+        },
+      },
+    },
+    ...rest,
+  };
+};

package/chrome/run.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+// yarn luma chrome [path]: the live storefront in your Chrome with this
+// integration on it as a customer installs it (the early-hold snippet first
+// in <head>, then the build: parity/hold.mjs), whether or not the site
+// includes it yet. Run from the integration repository:
+//
+//   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
+//
+// 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
+// one; its own scripts and consent dialog stay as they are. The
+// profile is kept per storefront (its cookies, a consent given once), apart
+// from your own Chrome profile. No rig, no Docker, no DNS: the storefront is
+// the real one.
+// The window stays until you close it.
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { extname, join, normalize, resolve } from 'node:path';
+import { inside } from '../bin/paths.mjs';
+
+const USAGE = `usage: yarn luma chrome [path] [options]
+
+  path               the storefront page to open (default /)
+  --dev              load the integration from the dev server (https://localhost:8069, yarn dev): no build
+  --check            open, wait for Luma, print its state (started, what it inserted, errors), close: exit 1 on an error
+  --no-build         serve dist/ as it is (yarn build yourself, then reload)
+  --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)`;
+
+const args = process.argv.slice(2);
+const opt = { path: '/', check: false, dev: false, build: true, snippet: true, channel: 'chrome', profile: '', siteDir: '' };
+const die = (msg) => {
+  console.error(msg);
+  process.exit(2);
+};
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  const next = () => {
+    const v = args[++i];
+    if (v === undefined || v.startsWith('--')) die(`${a} needs a value\n\n${USAGE}`);
+    return v;
+  };
+  if (a === '--help' || a === '-h') {
+    console.log(USAGE);
+    process.exit(0);
+  } else if (a === '--dev') opt.dev = true;
+  else if (a === '--check') opt.check = true;
+  else if (a === '--no-build') opt.build = false;
+  else if (a === '--no-snippet') opt.snippet = false;
+  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.startsWith('--')) opt.path = a.startsWith('/') ? a : `/${a}`;
+  else die(`unknown option ${a}\n\n${USAGE}`);
+}
+const SITE_DIR = resolve(opt.siteDir || process.env.LBX_SITE_DIR || process.cwd());
+if (!existsSync(join(SITE_DIR, 'integration'))) die(`${SITE_DIR} has no integration/ folder: run it from the integration repository (or --site-dir).`);
+process.env.LBX_SITE_DIR = SITE_DIR;
+
+let chromium;
+try {
+  ({ chromium } = await import('playwright-core'));
+} catch {
+  die("Luma's dependencies are not installed (playwright-core is missing): run `yarn install`.");
+}
+const { loadConfig } = await import('../bin/config.mjs');
+const config = await loadConfig(SITE_DIR);
+const { SNIPPET, holdInit } = await import('../parity/hold.mjs');
+
+const HOST = config.hostKnown ? config.host : '';
+if (!HOST) die("No storefront host: `export const host = 'www.shop.example'` in luma.config.mjs (yarn luma tooling --write --host <name>), or LBX_HOST.");
+const ORIGIN = `https://${HOST}`;
+const PREFIX = '/__lbx/chrome/';
+const DEV = 'https://localhost:8069/integration/__integration.ts';
+
+// ------------------------------------------------------------------ the build (a folder of its own: dist/ is left as it is)
+
+let DIST = join(SITE_DIR, 'dist');
+let temp = '';
+if (!opt.dev && opt.build) {
+  temp = DIST = mkdtempSync(join(tmpdir(), 'lbx-chrome-'));
+  process.stderr.write('building… ');
+  try {
+    execFileSync('yarn', ['vite', 'build', '--outDir', DIST, '--emptyOutDir'], { cwd: SITE_DIR, stdio: ['ignore', 'pipe', 'pipe'] });
+    process.stderr.write('done\n');
+  } catch (e) {
+    process.stderr.write('failed\n');
+    die(`the build failed:\n${e.stdout ?? ''}${e.stderr ?? ''}`);
+  }
+}
+if (!opt.dev && !existsSync(join(DIST, 'luma-integration.js'))) die(`${DIST}/luma-integration.js is missing: run yarn build (or drop --no-build).`);
+const cleanup = () => temp && rmSync(temp, { recursive: true, force: true });
+process.on('exit', cleanup);
+for (const s of ['SIGINT', 'SIGTERM']) process.on(s, () => process.exit(130));
+
+// ------------------------------------------------------------------ the browser
+
+const profile = resolve(opt.profile || join(homedir(), '.lbx-chrome', HOST));
+mkdirSync(profile, { recursive: true });
+const TYPES = { '.js': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.map': 'application/json' };
+let ctx;
+for (const channel of [opt.channel, ...(opt.channel === 'chrome' ? ['chromium'] : [])]) {
+  try {
+    ctx = await chromium.launchPersistentContext(profile, { channel, headless: false, viewport: null, ignoreHTTPSErrors: opt.dev, serviceWorkers: 'block' });
+    if (channel !== opt.channel) console.error(`(no installed Chrome: Playwright's Chromium instead)`);
+    break;
+  } catch (e) {
+    // The profile is one browser's at a time: a window of this command still open has it.
+    if (/already in use|existing browser session|ProcessSingleton/i.test(e.message)) die(`The profile ${profile} is in use (a yarn luma chrome window is open): close it, or --profile <another folder>.`);
+    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'));
+// 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))));
+  if (!inside(DIST, file) || !existsSync(file) || !statSync(file).isFile()) return route.fulfill({ status: 404, body: '' });
+  return route.fulfill({ status: 200, body: readFileSync(file), headers: { 'content-type': TYPES[extname(file)] ?? 'application/octet-stream', 'cache-control': 'no-store' } });
+});
+await ctx.addInitScript(holdInit, { origin: ORIGIN, bundle: opt.dev ? DEV : `${ORIGIN}${PREFIX}luma-integration.js`, snippet: opt.snippet ? SNIPPET : '', tag: 'chrome' });
+
+const page = ctx.pages()[0] ?? (await ctx.newPage());
+await page.goto(`${ORIGIN}${opt.path}`, { waitUntil: 'domcontentloaded', timeout: 60000 }).catch((e) => console.error(`${ORIGIN}${opt.path}: ${e.message.split('\n')[0]}`));
+if (opt.check) {
+  // Luma's own record (window.__lbx.health): did it start, what did it take over, what failed.
+  await page.waitForFunction(() => !!(window).__lbx?.health, null, { timeout: 20000 }).catch(() => {});
+  await new Promise((r) => setTimeout(r, 6000));
+  const s = await page.evaluate(() => {
+    const l = (window).__lbx;
+    return l ? { version: l.version, snippet: !!l.hold?.snippet, inserts: l.health?.inserts ?? null, marks: (l.health?.timeline ?? []).slice(0, 12).map(([t, w]) => `${t} ${w}`), errors: l.health?.errors ?? [] } : null;
+  }).catch((e) => ({ error: e.message }));
+  console.log(JSON.stringify({ url: page.url(), luma: s }, null, 1));
+  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(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));