@luigisbox/luma 0.0.0-stage → 0.2.0

package/footprint/model.mjs

@@ -0,0 +1,184 @@
+// What `yarn luma footprint` (footprint/run.mjs) turns its measurements into. Pure
+// functions, no browser: the round trips a file needs on a new connection,
+// Luma's main-thread time from a CPU profile and a trace, the request chain,
+// medians, and the report table. Tested offline (Luma's own tests).
+
+/** TCP's first flight: 10 segments (RFC 6928) of 1460 bytes of payload. */
+export const INITCWND = 10;
+export const MSS = 1460;
+/**
+ * Bytes on the wire around a response body: its HTTP/2 HEADERS frame (HPACK,
+ * a CDN's usual set), DATA frame headers and TLS record overhead. An estimate,
+ * on the safe side.
+ */
+export const OVERHEAD = 600;
+
+/**
+ * Round trips the server needs to deliver `bytes` (one response) on a
+ * connection that has already delivered `before` bytes (the loader on the same
+ * host), in TCP slow start without loss: each round trip the window grows by
+ * the segments acknowledged (it doubles). The request itself is not counted:
+ * 1 = the whole response arrives in the first flight after the request.
+ * @param {number} bytes
+ * @param {{ before?: number, overhead?: number, initcwnd?: number, mss?: number }} [o]
+ */
+export const roundTrips = (bytes, { before = 0, overhead = OVERHEAD, initcwnd = INITCWND, mss = MSS } = {}) => {
+  let cwnd = initcwnd + Math.ceil(before / mss);
+  let left = Math.ceil((bytes + overhead) / mss);
+  let trips = 0;
+  while (left > 0) {
+    trips++;
+    const sent = Math.min(cwnd, left);
+    left -= sent;
+    cwnd += sent;
+  }
+  return trips;
+};
+
+/** Bytes the first flight can carry for a response after `before` bytes (the largest body that still takes 1 round trip). */
+export const firstFlight = ({ before = 0, overhead = OVERHEAD, initcwnd = INITCWND, mss = MSS } = {}) => (initcwnd + Math.ceil(before / mss)) * mss - overhead;
+
+/** Is this URL one of Luma's scripts (the build served under /__lbx/)? */
+export const isLumaScript = (url) => typeof url === 'string' && /\/__lbx\/[^?#]*\.js(?:[?#]|$)/.test(url);
+
+/**
+ * Milliseconds of a CPU profile (CDP Profiler.Profile) spent with a frame of
+ * Luma's on the stack: our code and what it calls (DOM, layout it forces, the
+ * browser's APIs). `ours(url)` decides what is Luma's.
+ * @param {{ nodes: { id: number, parent?: number, children?: number[], callFrame: { url: string } }[], samples: number[], timeDeltas: number[] }} profile
+ */
+export const profileMs = (profile, ours = isLumaScript) => {
+  const byId = new Map(profile.nodes.map((n) => [n.id, n]));
+  const parent = new Map();
+  for (const n of profile.nodes) for (const c of n.children ?? []) parent.set(c, n.id);
+  const memo = new Map();
+  const mine = (id) => {
+    if (memo.has(id)) return memo.get(id);
+    const n = byId.get(id);
+    const v = !!n && (ours(n.callFrame.url) || (parent.has(id) && mine(parent.get(id))));
+    memo.set(id, v);
+    return v;
+  };
+  let us = 0;
+  // timeDeltas[i] is the time before sample i: the time sample i-1 stood for is timeDeltas[i].
+  for (let i = 0; i < profile.samples.length; i++) {
+    const d = profile.timeDeltas[i + 1] ?? 0;
+    if (d > 0 && mine(profile.samples[i])) us += d;
+  }
+  return us / 1000;
+};
+
+/**
+ * Milliseconds V8 spent compiling Luma's scripts (trace events v8.compile,
+ * v8.compileModule, …: before a module runs, outside any profiled frame).
+ * Nested events are counted once.
+ * @param {{ name: string, ph: string, dur?: number, ts: number, tid?: number, args?: any }[]} events
+ */
+export const compileMs = (events, ours = isLumaScript) => {
+  const urlOf = (e) => e.args?.data?.url ?? e.args?.fileName ?? e.args?.data?.fileName ?? e.args?.url;
+  const spans = events
+    .filter((e) => e.ph === 'X' && /^v8\.(compile|compileModule|parseOnBackground|produceModuleCache)/.test(e.name) && ours(urlOf(e)))
+    .map((e) => [e.tid ?? 0, e.ts, e.ts + (e.dur ?? 0)])
+    .sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+  let total = 0;
+  let tid = null;
+  let end = -Infinity;
+  for (const [t, s, e] of spans) {
+    if (t !== tid) (tid = t), (end = -Infinity);
+    if (e <= end) continue;
+    total += e - Math.max(s, end);
+    end = e;
+  }
+  return total / 1000;
+};
+
+/**
+ * The longest chain of Luma requests, each started by the one before it (its
+ * initiator): the page → the entry → a chunk = 2. `requests`: url and the url
+ * of what started it (a script, or the page).
+ * @param {{ url: string, initiator?: string }[]} requests
+ */
+export const chainDepth = (requests, ours = isLumaScript) => {
+  const by = new Map(requests.filter((r) => ours(r.url)).map((r) => [r.url, r]));
+  const memo = new Map();
+  const depth = (url, seen = new Set()) => {
+    if (memo.has(url)) return memo.get(url);
+    const r = by.get(url);
+    if (!r || seen.has(url)) return 0;
+    seen.add(url);
+    const d = 1 + (r.initiator && r.initiator !== url ? depth(r.initiator, seen) : 0);
+    memo.set(url, d);
+    return d;
+  };
+  return Math.max(0, ...[...by.keys()].map((u) => depth(u)));
+};
+
+/** The median (the mean of the two middle values for an even count); null for none. */
+export const median = (xs) => {
+  const s = xs.filter((x) => x != null && Number.isFinite(x)).sort((a, b) => a - b);
+  if (!s.length) return null;
+  const m = s.length >> 1;
+  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+};
+
+/** The rows of the report, in order: what each scenario costs. `lower`: smaller is better (all of them). */
+export const METRICS = [
+  { key: 'requests', label: 'Luma scripts', unit: '', digits: 0 },
+  { key: 'br', label: 'Luma JS (brotli)', unit: 'kB', digits: 1, scale: 1 / 1000 },
+  { key: 'gzip', label: 'Luma JS (gzip)', unit: 'kB', digits: 1, scale: 1 / 1000 },
+  { key: 'chain', label: 'script chain (page = 0)', unit: '', digits: 0 },
+  { key: 'mainMs', label: 'Luma main thread', unit: 'ms', digits: 1 },
+  { key: 'compileMs', label: 'Luma compile', unit: 'ms', digits: 1 },
+  { key: 'apiCalls', label: 'API requests (auth + api)', unit: '', digits: 0 },
+  { key: 'reconciles', label: 'reconcile passes', unit: '', digits: 0 },
+  { key: 'readyMs', label: 'ready (listing shown / suggestions)', unit: 'ms', digits: 0 },
+  // --dictionary only (a row without a value in any scenario is left out).
+  { key: 'dict', label: 'Luma JS (previous build as dictionary)', unit: 'kB', digits: 1, scale: 1 / 1000 },
+];
+
+const fmt = (m, v) => (v == null ? '–' : `${(v * (m.scale ?? 1)).toFixed(m.digits)}${m.unit ? ` ${m.unit}` : ''}`);
+
+/**
+ * The terminal report: the entry's size and round trips, then per scenario the
+ * medians of its runs.
+ * @param {{ entry: { raw: number, gzip: number, br: number, trips: number, tripsGzip: number, flight: number }, scenarios: { name: string, runs: Record<string, number | null>[] }[], meta?: Record<string, string> }} r
+ */
+export const formatReport = ({ entry, scenarios, meta = {} }) => {
+  const lines = [];
+  for (const [k, v] of Object.entries(meta)) lines.push(`${k}: ${v}`);
+  lines.push(
+    `entry: ${(entry.br / 1000).toFixed(1)} kB brotli, ${(entry.gzip / 1000).toFixed(1)} kB gzip, ${(entry.raw / 1000).toFixed(1)} kB raw; ` +
+      `round trips ${entry.trips} (brotli) / ${entry.tripsGzip} (gzip); first flight holds ${(entry.flight / 1000).toFixed(1)} kB`,
+  );
+  const head = ['metric', ...scenarios.map((s) => s.name)];
+  const rows = METRICS.filter((m) => scenarios.some((s) => median(s.runs.map((r) => r[m.key])) != null)).map((m) => [m.label, ...scenarios.map((s) => fmt(m, median(s.runs.map((r) => r[m.key]))))]);
+  const width = head.map((_, i) => Math.max(...[head, ...rows].map((r) => String(r[i]).length)));
+  const line = (r) => r.map((c, i) => (i ? String(c).padStart(width[i]) : String(c).padEnd(width[i]))).join('  ');
+  lines.push('', line(head), ...rows.map(line));
+  return lines.join('\n');
+};
+
+/** Medians per scenario and metric: what is compared between two runs of the tool (--json). */
+export const summarize = (scenarios) => Object.fromEntries(scenarios.map((s) => [s.name, Object.fromEntries(METRICS.map((m) => [m.key, median(s.runs.map((r) => r[m.key]))]))]));
+
+/**
+ * A page that names these scripts as modulepreload links, first in its <head>
+ * (where the preload scanner finds them with the entry): a loader's hint.
+ * @param {string} html @param {string[]} hrefs
+ */
+export const withPreloads = (html, hrefs) => {
+  if (!hrefs.length) return html;
+  const links = hrefs.map((h) => `<link rel="modulepreload" href="${h.replace(/"/g, '&quot;')}">`).join('');
+  return /<head(\s[^>]*)?>/i.test(html) ? html.replace(/<head(\s[^>]*)?>/i, (h) => h + links) : links + html;
+};
+
+/** A build file's name without its content hash (`luma-chunks/lbx-listing-BgR9IMfP.js` -> `luma-chunks/lbx-listing.js`): the same chunk in another build. */
+export const chunkBase = (file) => file.replace(/-[\w-]{8}\.js$/, '.js');
+
+/**
+ * The previous build's version of `file` (Use-As-Dictionary: the browser
+ * offers what it has cached of the same name pattern): the same path, else
+ * the chunk of the same name under another hash; null for a new file.
+ * @param {string} file @param {string[]} previous
+ */
+export const previousOf = (file, previous) => (previous.includes(file) ? file : (previous.find((p) => chunkBase(p) === chunkBase(file)) ?? null));

package/footprint/run.mjs

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+// yarn luma footprint: what Luma itself costs a storefront's pages, page type by
+// page type, measured on the integration's build. Run from the integration
+// repository (Luma as the @luigisbox/luma package, or an older luma/ submodule):
+//
+//   yarn luma footprint    (the integration's one `luma` script: bin/luma.mjs)
+//   yarn luma footprint [--runs 5] [--cpu 4] [--json out.json] [--no-build]
+//
+// - The entry (dist/luma-integration.js): its size (brotli, gzip, raw) and the
+//   round trips it takes on the CDN's connection after the platform's loader
+//   (footprint/model.mjs roundTrips: TCP slow start; --loader-bytes).
+// - Per scenario: the pages (luma.config.mjs `perf.pages`, else home and
+//   its fixtures' category, product and search) and "typing" (home, then the
+//   fixtures' query typed into the search input): the Luma scripts loaded and
+//   their bytes (the build's files compressed here, as the CDN serves them),
+//   the longest chain of them (page = 0: the entry is 1), Luma's main-thread
+//   time (CPU profile: samples with a frame of ours on the stack) and compile
+//   time (trace), API requests, reconcile passes, and when it was ready (our
+//   listing shown, suggestions on screen; a listing still loading after --settle
+//   is waited for). Cold (a new profile) and warm (the same page again in that
+//   tab: HTTP cache, token, stored rules), medians of --runs.
+// - --rtt: a round trip of latency for each of the page's and the build's
+//   responses (concurrent requests overlap, as on one HTTP/2 connection), so
+//   the chain of scripts costs what it would on a network. --preload: the page
+//   names the scenario's own chunks as modulepreload links (found by a run
+//   before), as a platform loader that knew them could: what that would save.
+//
+// The page is the integration's stub page (luma.config.mjs `stubPage`) on the
+// storefront's host name (LBX_HOST), with Luma as a customer installs it (the
+// early-hold snippet, then the build: parity/hold.mjs); the API is live. Not
+// the storefront's own scripts: this is Luma's cost, not the page's (that is
+// `yarn luma perf`, which needs the server-side rendering rig, not in the published package). Chromium at --cpu x CPU throttling.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join, normalize, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { brotliCompressSync, constants, gzipSync, zstdCompressSync } from 'node:zlib';
+import { chainDepth, compileMs, firstFlight, formatReport, isLumaScript, previousOf, profileMs, roundTrips, summarize, withPreloads } from './model.mjs';
+
+const LUMA = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const USAGE = `usage: yarn luma footprint [options]
+
+  --runs N            runs per scenario and visit (default 5)
+  --cpu N             CPU throttling (default 4)
+  --settle MS         time after the load event before reading the page (default 4000)
+  --only a,b          scenarios: the perf pages (home, category, search, product) and typing
+  --loader-bytes N    bytes the platform's loader took on the same connection before the entry (default 0)
+  --rtt MS            latency per response of the page and the build (default 0)
+  --preload           the page preloads the chunks its scenario loads (not typing's): a loader's hint
+  --dictionary DIR    a previous build (its dist/): each script also compressed with its previous
+                      version as the dictionary (zstd), as a returning visitor gets it after a deploy
+  --json FILE         also write the runs and medians as JSON
+  --no-build          use the integration's dist/ as it is
+  --headed            show the browser
+  --site-dir DIR      the integration repository (default: the current directory, LBX_SITE_DIR)`;
+
+const args = process.argv.slice(2);
+const opt = { runs: 5, cpu: 4, settle: 4000, only: [], loader: 0, rtt: 0, preload: false, dictionary: '', json: '', build: true, headed: false, 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 === '--runs') opt.runs = Number(next());
+  else if (a === '--cpu') opt.cpu = Number(next());
+  else if (a === '--settle') opt.settle = Number(next());
+  else if (a === '--only') opt.only = next().split(',').map((s) => s.trim()).filter(Boolean);
+  else if (a === '--loader-bytes') opt.loader = Number(next());
+  else if (a === '--rtt') opt.rtt = Number(next());
+  else if (a === '--preload') opt.preload = true;
+  else if (a === '--dictionary') opt.dictionary = resolve(next());
+  else if (a === '--json') opt.json = next();
+  else if (a === '--no-build') opt.build = false;
+  else if (a === '--headed') opt.headed = true;
+  else if (a === '--site-dir') opt.siteDir = next();
+  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;
+
+const { chromium } = await import('playwright-core');
+const { loadConfig } = await import('../bin/config.mjs');
+const config = await loadConfig(SITE_DIR);
+const { host: HOST, stubPage } = config;
+const { SNIPPET, holdInit } = await import('../parity/hold.mjs');
+
+const F = config.fixtures;
+const ORIGIN = `https://${HOST}`;
+const DIST = join(SITE_DIR, 'dist');
+const PREFIX = '/__lbx/footprint/';
+const BUNDLE = `${ORIGIN}${PREFIX}luma-integration.js`;
+
+if (opt.build) {
+  process.stderr.write(`building ${relative(process.cwd(), SITE_DIR) || '.'} (yarn build)… `);
+  try {
+    execFileSync('yarn', ['build'], { cwd: SITE_DIR, stdio: ['ignore', 'pipe', 'pipe'] });
+    process.stderr.write('done\n');
+  } catch (e) {
+    process.stderr.write('failed\n');
+    die(`yarn build failed:\n${e.stdout ?? ''}${e.stderr ?? ''}`);
+  }
+}
+if (!existsSync(join(DIST, 'luma-integration.js'))) die(`${DIST}/luma-integration.js is missing: run yarn build (or drop --no-build).`);
+
+// ------------------------------------------------------------------ the build's files, as the CDN serves them
+
+const walk = (dir, out = []) => {
+  for (const e of readdirSync(dir, { withFileTypes: true })) (e.isDirectory() ? walk : (p) => out.push(p))(join(dir, e.name), out);
+  return out;
+};
+const sizes = new Map();
+for (const f of walk(DIST)) {
+  const b = readFileSync(f);
+  sizes.set(relative(DIST, f).split('\\').join('/'), {
+    raw: b.length,
+    gzip: gzipSync(b, { level: 9 }).length,
+    br: brotliCompressSync(b, { params: { [constants.BROTLI_PARAM_QUALITY]: 11 } }).length,
+  });
+}
+// --dictionary: each file compressed with its previous version as the dictionary (a new file: its brotli size).
+if (opt.dictionary) {
+  if (!existsSync(join(opt.dictionary, 'luma-integration.js'))) die(`--dictionary ${opt.dictionary}: no luma-integration.js there (a build's dist/)`);
+  if (typeof zstdCompressSync !== 'function') die('--dictionary needs zstd in node:zlib (Node 22.15+)');
+  const previous = walk(opt.dictionary).map((f) => relative(opt.dictionary, f).split('\\').join('/'));
+  for (const [f, sz] of sizes) {
+    const prev = previousOf(f, previous);
+    sz.dict = prev ? zstdCompressSync(readFileSync(join(DIST, f)), { params: { [constants.ZSTD_c_compressionLevel]: 19 }, dictionary: readFileSync(join(opt.dictionary, prev)) }).length : sz.br;
+  }
+}
+const entrySize = sizes.get('luma-integration.js');
+const entry = {
+  ...entrySize,
+  trips: roundTrips(entrySize.br, { before: opt.loader }),
+  tripsGzip: roundTrips(entrySize.gzip, { before: opt.loader }),
+  flight: firstFlight({ before: opt.loader }),
+};
+const fileOf = (url) => {
+  const p = new URL(url).pathname;
+  return p.startsWith(PREFIX) ? decodeURIComponent(p.slice(PREFIX.length)) : null;
+};
+
+// ------------------------------------------------------------------ scenarios
+
+const pages = config.perf?.pages ?? Object.fromEntries([['home', '/'], ['category', F.category], ['search', F.query ? `/search?q=${encodeURIComponent(F.query)}` : null], ['product', F.product]].filter(([, p]) => p));
+const scenarios = [...Object.entries(pages).map(([name, path]) => ({ name, path })), ...(F.input && F.query ? [{ name: 'typing', path: '/', type: F.query }] : [])].filter((s) => !opt.only.length || opt.only.includes(s.name));
+if (!scenarios.length) die('no scenario to run (luma.config.mjs perf.pages or fixtures; --only)');
+
+// ------------------------------------------------------------------ browser
+
+const launch = async () => {
+  const o = { headless: !opt.headed };
+  const tries = [...(process.env.LBX_CHROMIUM_PATH ? [{ ...o, executablePath: process.env.LBX_CHROMIUM_PATH }] : []), { ...o, channel: 'chromium' }, { ...o, channel: 'chrome' }, o];
+  let err;
+  for (const t of tries) {
+    try {
+      return await chromium.launch(t);
+    } catch (e) {
+      err = e;
+    }
+  }
+  die(`No Chromium to run (set LBX_CHROMIUM_PATH).\n${err?.message?.split('\n')[0] ?? ''}`);
+};
+const TYPES = { '.js': 'text/javascript', '.css': 'text/css', '.json': 'application/json' };
+
+/** Per page (path and query): the build's files it names as modulepreload links (--preload). */
+const preloads = new Map();
+
+const newContext = async (browser) => {
+  const ctx = await browser.newContext({ viewport: { width: 1280, height: 800 }, serviceWorkers: 'block' });
+  // The site's own Luigi's Box scripts never run: ours is the build measured.
+  await ctx.route(/^https:\/\/(cdn\.luigisbox\.(com|tech)|cdn\.eu1\.luigisbox\.ai|scripts\.luigisbox\.(com|tech))\//, (r) => r.abort('blockedbyclient'));
+  await ctx.route(`${ORIGIN}/**`, async (route) => {
+    const req = route.request();
+    const url = new URL(req.url());
+    if (opt.rtt) await sleep(opt.rtt);
+    if (url.pathname.startsWith(PREFIX)) {
+      const file = normalize(join(DIST, decodeURIComponent(url.pathname.slice(PREFIX.length))));
+      if (!file.startsWith(DIST) || !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' } });
+    }
+    if (req.resourceType() === 'document') return route.fulfill({ status: 200, contentType: 'text/html; charset=utf-8', body: withPreloads(await stubPage(url), (preloads.get(url.pathname + url.search) ?? []).map((f) => PREFIX + f)) });
+    return route.fulfill({ status: 404, body: '' });
+  });
+  await ctx.addInitScript(holdInit, { origin: ORIGIN, bundle: BUNDLE, snippet: SNIPPET, tag: 'footprint' });
+  return ctx;
+};
+
+/** In the page: when an autocomplete row is on screen (through shadow roots). */
+function suggestionsShown() {
+  const find = (root) => {
+    if (root.querySelector?.('[data-lbx-part="ac-row"], [role="option"]')) return true;
+    for (const el of root.querySelectorAll?.('*') ?? []) if (el.shadowRoot && find(el.shadowRoot)) return true;
+    return false;
+  };
+  return find(document);
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** One page load of a scenario in `page`, measured. */
+const measure = async (browser, page, s) => {
+  const cdp = await page.context().newCDPSession(page);
+  await cdp.send('Emulation.setCPUThrottlingRate', { rate: opt.cpu });
+  const requests = [];
+  await cdp.send('Network.enable');
+  cdp.on('Network.requestWillBeSent', (e) => {
+    const i = e.initiator ?? {};
+    const frames = [];
+    for (let st = i.stack; st; st = st.parent) frames.push(...(st.callFrames ?? []));
+    const by = frames.find((f) => f.url)?.url ?? i.url ?? '';
+    requests.push({ url: e.request.url, initiator: by });
+  });
+  await cdp.send('Profiler.enable');
+  await cdp.send('Profiler.setSamplingInterval', { interval: 100 });
+  await browser.startTracing(page, { categories: ['v8', 'disabled-by-default-v8.compile', 'devtools.timeline'] });
+  await cdp.send('Profiler.start');
+  await page.goto(`${ORIGIN}${s.path}`, { waitUntil: 'load', timeout: 60000 });
+  let readyMs = null;
+  if (s.type) {
+    await sleep(opt.settle);
+    const input = page.locator(F.input).first();
+    const t0 = await page.evaluate(() => performance.now());
+    await input.click();
+    await input.pressSequentially(s.type, { delay: 120 });
+    const shown = await page.waitForFunction(suggestionsShown, null, { timeout: 15000, polling: 16 }).then(() => true, () => false);
+    if (shown) readyMs = (await page.evaluate(() => performance.now())) - t0;
+    await sleep(1500);
+  } else {
+    await sleep(opt.settle);
+    // A listing still loading (held, not yet ours or handed back): its end, within 20 s.
+    await page
+      .waitForFunction(() => {
+        const t = (window.__lbx?.health?.timeline ?? []).map(([, w]) => w);
+        const held = t.some((w) => / takeover (hold|native)$/.test(w));
+        return !held || t.some((w) => / takeover (ours|released)$/.test(w));
+      }, null, { timeout: 20000, polling: 100 })
+      .catch(() => {});
+    await sleep(500);
+  }
+  const { profile } = await cdp.send('Profiler.stop');
+  const trace = JSON.parse((await browser.stopTracing()).toString('utf8'));
+  const lbx = await page.evaluate(() => {
+    const l = window.__lbx;
+    return l ? { apiCalls: l.health?.apiCalls ?? 0, reconciles: l.health?.reconciles ?? 0, errors: l.health?.errors ?? [], timeline: l.health?.timeline ?? [] } : null;
+  });
+  await cdp.detach();
+  if (!s.type && lbx) {
+    const shown = lbx.timeline.find(([, what]) => / takeover ours$/.test(what));
+    readyMs = shown ? shown[0] : null;
+  }
+  const files = [...new Set(requests.map((r) => r.url).filter(isLumaScript))].map(fileOf).filter(Boolean);
+  const sum = (k) => files.reduce((a, f) => a + (sizes.get(f)?.[k] ?? 0), 0);
+  return {
+    metrics: {
+      requests: files.length,
+      br: sum('br'),
+      gzip: sum('gzip'),
+      chain: chainDepth(requests),
+      mainMs: profileMs(profile),
+      compileMs: compileMs(trace.traceEvents ?? []),
+      apiCalls: requests.filter((r) => /^https:\/\/(auth|api)\.[\w-]+\.luigisbox\.ai\//.test(r.url)).length,
+      reconciles: lbx?.reconciles ?? null,
+      readyMs,
+      dict: opt.dictionary ? sum('dict') : null,
+    },
+    files,
+    errors: lbx?.errors ?? ['window.__lbx missing: Luma did not boot'],
+  };
+};
+
+const browser = await launch();
+const results = { cold: [], warm: [] };
+const errors = new Set();
+const filesBy = {};
+for (const s of scenarios) {
+  const cold = { name: s.name, runs: [] };
+  const warm = { name: s.name, runs: [] };
+  if (opt.preload && !s.type) {
+    // The scenario's chunks, from a run not counted.
+    process.stderr.write(`\r${s.name}: finding its chunks   `);
+    const ctx = await newContext(browser);
+    try {
+      const { files } = await measure(browser, await ctx.newPage(), s);
+      preloads.set(s.path, files.filter((f) => f !== 'luma-integration.js'));
+    } finally {
+      await ctx.close();
+    }
+  }
+  for (let i = 0; i < opt.runs; i++) {
+    process.stderr.write(`\r${s.name}: run ${i + 1}/${opt.runs}   `);
+    const ctx = await newContext(browser);
+    try {
+      const page = await ctx.newPage();
+      const c = await measure(browser, page, s);
+      cold.runs.push(c.metrics);
+      filesBy[s.name] = c.files;
+      c.errors.forEach((e) => errors.add(`${s.name}: ${e}`));
+      // The same tab (sessionStorage is per tab: the token, stashes), the next page view.
+      await page.goto('about:blank');
+      const w = await measure(browser, page, s);
+      warm.runs.push(w.metrics);
+      w.errors.forEach((e) => errors.add(`${s.name} (warm): ${e}`));
+    } finally {
+      await ctx.close();
+    }
+  }
+  results.cold.push(cold);
+  results.warm.push(warm);
+}
+process.stderr.write('\r');
+await browser.close();
+
+const meta = { integration: SITE_DIR, host: HOST, runs: String(opt.runs), cpu: `${opt.cpu}x`, ...(opt.rtt ? { rtt: `${opt.rtt} ms` } : {}), ...(opt.preload ? { preload: 'the scenario\'s chunks (a loader\'s hint)' } : {}), ...(opt.dictionary ? { dictionary: `${opt.dictionary} (the entry with it: ${(entrySize.dict / 1000).toFixed(1)} kB)` } : {}), page: config.ownStubPage ? "the integration's stub page" : "Luma's neutral stub page" };
+console.log(formatReport({ entry, scenarios: results.cold, meta: { ...meta, visit: 'cold (a new profile)' } }));
+console.log(`\n${formatReport({ entry, scenarios: results.warm, meta: { visit: 'warm (the same page again, same tab)' } }).split('\n').slice(2).join('\n')}`);
+console.log(`\nscripts per scenario (cold): ${Object.entries(filesBy).map(([k, v]) => `\n  ${k}: ${v.join(', ')}`).join('')}`);
+if (errors.size) console.log(`\nLuma errors:\n  ${[...errors].join('\n  ')}`);
+if (opt.json) {
+  writeFileSync(opt.json, `${JSON.stringify({ meta, entry, files: Object.fromEntries(sizes), scripts: filesBy, cold: summarize(results.cold), warm: summarize(results.warm), runs: results }, null, 2)}\n`);
+  console.log(`\nwritten: ${opt.json}`);
+}

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@luigisbox/luma",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Luma: Luigi's Box frontend integrations (autocomplete, search, category listings, recommenders) on the Luigi's Box AI API. Pre-release.",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "packageManager": "yarn@4.4.1",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "luma": "bin/luma.mjs"
+  },
+  "files": [
+    "src",
+    "!src/ssr.ts",
+    "tsconfig.json",
+    "build/vite.mjs",
+    "build/baseline.mjs",
+    "build/baseline.d.mts",
+    "build/tooling.mjs",
+    "bin",
+    "a11y",
+    "footprint",
+    "tasks",
+    "parity",
+    "chrome",
+    "snippet/early-hold.js",
+    "snippet/early-hold.min.js",
+    "docs/ACCESSIBILITY.md",
+    "docs/INTEGRATION-PERFORMANCE.md",
+    "docs/PARITY.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@jridgewell/trace-mapping": "0.3.31",
+    "@lit-labs/ssr-client": "^1.1.8",
+    "@typescript-eslint/parser": "8.71.0",
+    "axe-core": "4.13.0",
+    "eslint": "10.11.0",
+    "eslint-plugin-baseline-js": "0.7.2",
+    "lit-html": "^3.3.3",
+    "parse5": "8.0.1",
+    "pixelmatch": "7.2.0",
+    "playwright-core": "1.63.0",
+    "pngjs": "7.0.0",
+    "stylelint": "17.16.0",
+    "stylelint-plugin-use-baseline": "1.4.6",
+    "terser": "5.36.0"
+  },
+  "peerDependencies": {
+    "typescript": "^6.0.3",
+    "vite": "^7.3.6"
+  },
+  "scripts": {
+    "postpublish": "node build/publish-manifest.mjs restore"
+  }
+}