@luigisbox/luma 0.7.0 → 0.8.0-beta.0

package/src/widgets/convo/index.ts

@@ -0,0 +1,713 @@
+// The conversational search: a modal dialog where the shopper asks in their
+// own words and Luigi's Box's assistant answers, streamed, with text, products,
+// follow-up suggestions, questions and comparisons. Loaded by the entry on
+// intent (a pointer over or focus on an element with `data-lbx-convo`) and
+// opened by a click on one; a site without integration/convo/ has none of it.
+//
+// - The conversation is the conversation service's (protocol.ts), keyed by
+//   the site's tracker id; its products are looked up by their identity on
+//   the channel's collection surface (`idField`), so a tile is the catalog's
+//   and the integration's template, as every other widget's.
+// - It lasts the tab's session across pages (sessionStorage, `lbx:convo`),
+//   about as long as the service keeps it: a product opened from it and Back,
+//   or the next page's trigger, shows the same conversation.
+// - Where the site's assistant is off (the eligibility check, a 403, the
+//   month's cap), the dialog says so, and the entry hides the triggers on the
+//   session's later pages (`lbx:convo:on`).
+// - Our markup lives in a shadow root (the house design, `style-convo.css`,
+//   then the integration's): the site's CSS cannot reach into the dialog.
+
+import { liveRegion, useContrast } from '../../core/a11y';
+import { visitorId } from '../../api/token';
+import { CONVO_ASSIST, NAMED_FADE } from '../../core/features';
+import type { T } from '../../core/i18n';
+import { mark, reportError } from '../../core/health';
+import { created } from '../../core/own';
+import { first } from '../../core/result';
+import { schedule } from '../../core/scheduler';
+import { onUrlChange } from '../../core/sense';
+import { lru, session } from '../../core/storage';
+import { cspNonce, setCss } from '../../core/styles';
+import { settleImages } from '../../core/support';
+import { byName, view } from '../../core/templates';
+import { watch } from '../../core/tiles';
+import type { WidgetContext } from '../../main';
+import type { ConvoAction, ConvoBlock, ConvoConfigType, ConvoMessage, ConvoScope, Helpers, Result } from '../../types';
+import { answerFor, drop, hold, type Answer } from './assist';
+import { md } from './markdown';
+import { addBlock, contextOf, endpointOf, events, failure, StreamError, turnBody, words, type Event, type Input, type Intent } from './protocol';
+import STRINGS from './strings';
+import CSS from './style-convo.css?raw';
+
+export const templates = byName(import.meta.glob('./template-*.ts', { eager: true, import: 'default' }));
+
+type Ctx = WidgetContext<ConvoConfigType>;
+
+/** The conversation, this tab's (sessionStorage). */
+const KEY = 'lbx:convo';
+/** The site's assistant is on (true) or off (false) this session; unknown until asked. Read by the entry (main.ts). */
+const ON = 'lbx:convo:on';
+/** The service keeps an idle conversation for about 75 minutes: ours is forgotten a quarter of an hour sooner. */
+const TTL = 60 * 60e3;
+/** A turn's stream: no bytes for 30 s, or 2 minutes in all, and it has failed. */
+const IDLE_MS = 30e3;
+const TURN_MS = 120e3;
+/** Messages kept (a question and its answer are two). */
+const MAX = 40;
+
+interface Saved {
+  id: string;
+  /** The service has accepted a turn of it: the next one converses. */
+  committed: boolean;
+  messages: ConvoMessage[];
+  refinements: ConvoScope['refinements'];
+  revision: number;
+  state: 'ready' | 'ended' | 'final';
+  /** The last failed turn, to send again (`retry`). */
+  failed: Intent | null;
+  at: number;
+}
+const fresh = (): Saved => ({
+  id: crypto.randomUUID(),
+  committed: false,
+  messages: [],
+  refinements: [],
+  revision: -1,
+  state: 'ready',
+  failed: null,
+  at: Date.now(),
+});
+
+/** What sessionStorage holds, if it is a conversation of ours young enough to go on with (storage is never trusted to be ours). */
+const restore = (): Saved => {
+  const v = session.get<Saved>(KEY);
+  if (!v || typeof v !== 'object' || typeof v.id !== 'string' || !Array.isArray(v.messages) || !(Date.now() - v.at < TTL)) return fresh();
+  const messages = v.messages.filter((m) => m && (m.role === 'user' || m.role === 'assistant') && typeof m.text === 'string' && Array.isArray(m.blocks));
+  // A turn the last page left on its way did not finish.
+  for (const m of messages) if (m.status === 'streaming') Object.assign(m, { status: 'failed', error: 'error', retry: !!v.failed });
+  const state = v.state === 'ended' || v.state === 'final' ? v.state : 'ready';
+  const failed = v.failed && typeof v.failed.key === 'string' && v.failed.input && typeof v.failed.input === 'object' ? v.failed : null;
+  return {
+    id: v.id,
+    committed: v.committed === true,
+    messages,
+    refinements: Array.isArray(v.refinements) ? v.refinements : [],
+    revision: Number(v.revision) || -1,
+    state,
+    failed,
+    at: v.at,
+  };
+};
+
+let s: Saved | null = null;
+let busy = false;
+let ctl: AbortController | null = null;
+/** The turn in flight was cut by the shopper's Stop (not a deadline, not the page going away). */
+let stopped = false;
+/** The site's assistant is off this session (`ON`): read once, kept in step with what is learnt. */
+let off = false;
+const setOn = (v: boolean) => {
+  off = !v;
+  session.set(ON, v);
+};
+
+let dialog: HTMLDialogElement | null = null;
+let host: HTMLElement;
+let root: ShadowRoot;
+let box: HTMLElement;
+let v: ReturnType<typeof view>;
+let live: ReturnType<typeof liveRegion>;
+let opener: Element | null = null;
+let t: T;
+let scope: Omit<ConvoScope, 'messages' | 'busy' | 'state' | 'refinements' | 'include'>;
+const NO_ACTIONS: ConvoAction[] = [];
+let draw = (_opening?: boolean) => {};
+
+// --- products: the identities the conversation names, as the catalog's results
+const products = lru<Result | null>(500, Infinity);
+const asking = new Set<string>();
+const idOf = (p: any) => String(p?.identity ?? '');
+const shown = () => (s?.messages ?? []).flatMap((m) => m.blocks.flatMap(productsOf));
+const productsOf = (b: ConvoBlock) => (Array.isArray(b.products) ? b.products.map((p) => products.get(idOf(p))).filter((r): r is Result => !!r) : []);
+/** The products of blocks, looked up once each per page: one request per 50 (a conversation read back has many). */
+const hydrate = (ctx: Ctx, list: unknown) => {
+  if (!Array.isArray(list)) return;
+  const all = [...new Set(list.map(idOf))].filter((id) => id && products.get(id) === undefined && !asking.has(id));
+  for (let i = 0; i < all.length; i += 50) ask(ctx, all.slice(i, i + 50));
+};
+const ask = (ctx: Ctx, ids: string[]) => {
+  const c = ctx.config;
+  for (const id of ids) asking.add(id);
+  ctx.api
+    .search({
+      endpoint: 'collections',
+      surface: c.surface,
+      type: c.type ?? ctx.global.itemType ?? 'product',
+      scope: { [c.idField]: { in: ids } },
+      size: ids.length,
+      fields: c.fields?.length ? [...new Set([...c.fields, c.idField])] : undefined,
+    })
+    .then((page) => {
+      for (const h of page.hits) products.set(String(first(h[c.idField])), ctx.result(h));
+      // Not in this channel's catalog: no tile (the service and the catalog may differ for a while).
+      for (const id of ids) if (products.get(id) === undefined) products.set(id, null);
+    })
+    .catch((e) => reportError('convo products', e))
+    .finally(() => {
+      for (const id of ids) asking.delete(id);
+      draw();
+    });
+};
+
+const save = () => s && session.set(KEY, s);
+
+// --- turns
+const endpoint = (ctx: Ctx) => endpointOf(ctx.config);
+
+/** Asked once a session, when the dialog first opens: a site over its month's budget, or without a catalog, says so at once. */
+let checked = false;
+const check = (ctx: Ctx) => {
+  if (checked || session.get(ON) != null) return;
+  checked = true;
+  const c = new AbortController();
+  setTimeout(() => c.abort(), 8000);
+  fetch(`${endpoint(ctx)}/eligibility_check`, { signal: c.signal })
+    .then((r) => (r.ok ? r.json() : r.status === 403 ? { data: { eligible: false } } : null))
+    .then((j) => {
+      if (j == null) return; // the service's trouble: the first turn will tell
+      setOn(j?.data?.eligible === true);
+      draw();
+    })
+    .catch(() => {});
+};
+
+const fail = (m: ConvoMessage, error: string, retry: boolean, intent: Intent | null) => {
+  m.status = 'failed';
+  m.error = error;
+  m.retry = retry;
+  s!.failed = retry ? intent : null;
+  if (error === 'unavailable') setOn(false);
+};
+
+/**
+ * A turn: the intent sent to /turn, or (`from`) an answer /assist already has
+ * (its events replayed and followed: the same conversation, nothing asked
+ * again). Resolves once it has ended.
+ */
+const turn = (ctx: Ctx, intent: Intent, from?: Answer) => {
+  const st = s!;
+  const m: ConvoMessage = {
+    role: 'assistant',
+    text: '',
+    blocks: [],
+    status: 'streaming',
+  };
+  st.messages.push(m);
+  st.failed = null;
+  st.at = Date.now();
+  busy = true;
+  // The wait, said (a turn may take a while; "Thinking" in the log is not live).
+  live.say(t('thinking'));
+  stopped = false;
+  const c = (ctl = new AbortController());
+  let idle = 0;
+  const kick = () => {
+    clearTimeout(idle);
+    idle = window.setTimeout(() => c.abort(), IDLE_MS);
+  };
+  const total = window.setTimeout(() => c.abort(), TURN_MS);
+  const g = ctx.global;
+  const cfg = ctx.config;
+  const apply = (type: string, p: any) => {
+    switch (type) {
+      case 'turn.accepted':
+        st.committed = true;
+        break;
+      case 'text.delta':
+      case 'render.block':
+        hydrate(ctx, addBlock(m.blocks, type, p)?.products);
+        break;
+      case 'conversation.state':
+        // Snapshots may come out of order: an older one is dropped.
+        if (Number(p?.revision) >= st.revision) {
+          st.revision = Number(p.revision);
+          st.refinements = Array.isArray(p.refinements) ? p.refinements : [];
+        }
+        break;
+      case 'turn.limitation':
+        m.error = 'limit';
+        break;
+      case 'turn.completed':
+        m.status = 'done';
+        break;
+      case 'turn.error':
+        // The month's cap does not clear by retrying; a rate limit does.
+        fail(m, p?.code === 'cap_exceeded' ? 'unavailable' : p?.code === 'rate_limited' ? 'busy' : 'error', p?.code !== 'cap_exceeded' && !!p?.retriable, intent);
+        break;
+      case 'turn.abandoned':
+        fail(m, 'error', false, null);
+        break;
+      case 'turn.ignored': {
+        // A control from an older answer: the question stands, unanswered.
+        st.messages.splice(st.messages.indexOf(m), 1);
+        const q = st.messages[st.messages.length - 1];
+        if (q?.role === 'user') q.status = 'ignored';
+        break;
+      }
+      case 'conversation.terminated':
+        st.state = p?.can_start_new_conversation === false ? 'final' : 'ended';
+        if (m.status === 'streaming') m.status = 'done';
+        break;
+    }
+  };
+  // Respond first: the question is drawn in the click's task, the request goes in the next.
+  // /assist's answer replayed (convo.assist): chosen out of the try, where a build flag does not fold.
+  const replay = CONVO_ASSIST ? from : undefined;
+  // A replayed answer cut (Stop, a deadline): its request goes too.
+  const cut = CONVO_ASSIST ? (from ? () => drop(from.query, true) : null) : null;
+  return new Promise<void>((done) =>
+    setTimeout(async () => {
+      try {
+        kick();
+        let src: AsyncIterable<Event>;
+        // Stop and the deadlines reach a replayed answer too (its signal).
+        if (replay) src = replay.stream(c.signal);
+        else {
+          const r = await fetch(`${endpoint(ctx)}/turn`, {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+              Accept: 'text/event-stream',
+            },
+            body: JSON.stringify(turnBody(st.id, st.committed, intent, contextOf(g, cfg, visitorId()))),
+            signal: c.signal,
+          });
+          if (!r.ok || !r.body) {
+            const f = failure(r.status);
+            reportError('convo turn', `HTTP ${r.status} ${(await r.text().catch(() => '')).slice(0, 300)}`);
+            return fail(m, f.error, f.retry, intent);
+          }
+          src = events(r.body, kick);
+        }
+        for await (const e of src) {
+          if (s !== st) return; // started over meanwhile
+          kick();
+          apply(e.event_type, e.payload);
+          later();
+        }
+      } catch (e) {
+        // Stop or a deadline (the conversation unchanged): not Start over, which leaves the page's box its answer.
+        if (cut && c.signal.aborted && s === st) cut();
+        if (s !== st) return;
+        if (stopped) fail(m, 'stopped', false, null);
+        else {
+          fail(m, 'error', true, intent);
+          if (e instanceof StreamError) reportError('convo stream', e.message);
+          else if (!c.signal.aborted) reportError('convo turn', e);
+        }
+      } finally {
+        clearTimeout(idle);
+        clearTimeout(total);
+        if (ctl === c) {
+          ctl = null;
+          busy = false;
+        }
+        if (s === st) {
+          if (m.status === 'streaming') m.status = 'done';
+          st.at = Date.now();
+          if (st.messages.length > MAX) st.messages.splice(0, st.messages.length - MAX);
+          save();
+          draw();
+          // The answer, said once it is whole (the log is not live: its words come in pieces),
+          // as words without the Markdown's marks, cut at a sentence after 500 characters.
+          const said = words(m.blocks.map((b) => (b.type === 'text' ? b.text : '')).join('\n\n'));
+          const cut = said.length > 500 ? `${said.slice(0, said.lastIndexOf('. ', 500) + 1 || 500)} …` : said;
+          const asked = st.messages[st.messages.length - 1];
+          live.say(asked?.status === 'ignored' && !st.messages.includes(m) ? t('ignored') : m.error ? `${cut} ${t(m.error)}`.trim() : cut || (m.blocks.some((b) => Array.isArray(b.products)) ? t('products') : ''));
+          mark(`convo turn ${m.status}`);
+        }
+        done();
+      }
+    }, 0),
+  );
+};
+
+const send = (ctx: Ctx, input: Input, label: string) => {
+  if (busy || !s || s.state !== 'ready' || off || !label.trim()) return;
+  // A first turn tried and never accepted (stopped, cut, failed before the stream): the
+  // service may hold its id under that turn's key; a new question with another key would be
+  // refused for good (400). A new question, then: a new conversation.
+  if (!s.committed && s.messages.some((m) => m.role === 'assistant')) ((s.id = crypto.randomUUID()), (s.failed = null));
+  s.messages.push({
+    role: 'user',
+    text: label.trim(),
+    blocks: [],
+    status: 'done',
+  });
+  turn(ctx, { input, key: crypto.randomUUID() });
+  draw();
+  toEnd();
+};
+
+/** The log at its end (a column-reverse scroller: 0 is its end), a frame later: never a layout read in the click's task. */
+const toEnd = () =>
+  requestAnimationFrame(() => {
+    const log = box.querySelector('[data-lbx-convo-log]');
+    if (log) log.scrollTop = 0;
+  });
+
+/** At most one draw a frame while an answer streams in. */
+let queued = false;
+const later = () => {
+  if (queued) return;
+  queued = true;
+  requestAnimationFrame(() => {
+    queued = false;
+    draw();
+  });
+};
+
+const close = () => dialog?.close();
+
+/**
+ * The site's accent may be any colour: text in it made dark enough for 4.5:1
+ * on its tint (toward black on a light panel, toward white on a dark one),
+ * what stands on it white or black, whichever reads better. The browser
+ * resolves the tokens as the host's own colours (the host draws nothing: its
+ * shadow content sets its own; `color-mix(… srgb)` reports any colour space
+ * as sRGB, `color(srgb r g b)` 0-1, rgb() in older engines), read a frame
+ * later, before the first paint. A few lines of its own: core/color.ts shared
+ * with the autocomplete would move into lbx-core, every widget's.
+ */
+const readable = (el: HTMLElement) => {
+  el.style.color = 'color-mix(in srgb, var(--lbx-cv-accent) 100%, transparent)';
+  el.style.backgroundColor = 'var(--lbx-cv-bg)';
+  requestAnimationFrame(() => {
+    const cs = getComputedStyle(el);
+    const rgb = (c: string) => {
+      const m = /(rgba?\(|srgb\s+)([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)/.exec(c);
+      return m ? m.slice(2).map((v) => Number(v) * (m[1][0] === 's' ? 255 : 1)) : [];
+    };
+    const lum = (c: number[]) => c.map((v) => ((v /= 255) <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4)).reduce((l, v, i) => l + v * [0.2126, 0.7152, 0.0722][i], 0);
+    const a = rgb(cs.color);
+    const bg = rgb(cs.backgroundColor);
+    if (a.length < 3 || bg.length < 3) return;
+    const mix = (x: number[], y: number[], w: number) => x.map((v, i) => Math.round(v * w + y[i] * (1 - w)));
+    const tint = lum(mix(a, bg, 0.1));
+    const to = tint < 0.18 ? [255, 255, 255] : [0, 0, 0];
+    const ratio = (c: number[]) => {
+      const [x, y] = [lum(c), tint].sort((p, q) => q - p);
+      return (x + 0.05) / (y + 0.05);
+    };
+    let text = a;
+    for (let k = 0.92; k > 0 && ratio(text) < 4.5; k -= 0.08) text = mix(a, to, k);
+    el.style.setProperty('--lbx-cv-accent-text', `rgb(${text})`);
+    // White or black, whichever reads better on it: never under 4.58:1 (a fixed cut at ~0.18 picked the worse
+    // near it, and a near-black instead of black left a band of accents where neither reached 4.5:1).
+    const la = lum(a);
+    el.style.setProperty('--lbx-cv-on-accent', 1.05 / (la + 0.05) >= (la + 0.05) / 0.05 ? '#fff' : '#000');
+  });
+};
+
+const build = (ctx: Ctx) => {
+  host = document.createElement('lbx-convo');
+  host.setAttribute('data-lbx', 'convo');
+  root = host.attachShadow({ mode: 'open' });
+  // Elements, not innerHTML: sites enforcing Trusted Types reject string HTML.
+  const style = document.createElement('style');
+  style.nonce = cspNonce();
+  style.textContent = [CSS, ...ctx.styles].join('\n');
+  dialog = document.createElement('dialog');
+  dialog.className = 'lbx-cv';
+  dialog.setAttribute('aria-labelledby', 'lbx-cv-title');
+  dialog.setAttribute('aria-describedby', 'lbx-cv-note');
+  box = document.createElement('div');
+  box.className = 'lbx-cv__box';
+  live = liveRegion();
+  dialog.append(box, live.el);
+  root.append(style, dialog);
+  document.body.append(host);
+  v = view(box, ctx.templates);
+  // The high-contrast mode's palette (--lbx-c-*), as every widget at its start: this may be the page's only one.
+  useContrast();
+  readable(host);
+  const fade = NAMED_FADE ? ctx.global.images?.fade !== false : true;
+  // Markdown parsed once per finished text (an answer streaming in is drawn every frame, its text new each time).
+  const parsed = lru<unknown>(200, Infinity);
+  // The dialog's words (strings.ts) under the site's translations.
+  const own = STRINGS[(ctx.global.locale ?? 'en').split('-')[0]] ?? STRINGS.en;
+  t = (k, p) => {
+    const x = ctx.t(k, p);
+    return x === k && own[k] ? own[k] : x;
+  };
+  const act = (a: ConvoAction) => {
+    if (a?.action_ref) send(ctx, { kind: 'action', action_ref: a.action_ref }, String(a.label ?? ''));
+  };
+  scope = {
+    ...(ctx.helpers as unknown as Omit<Helpers, 'include'>),
+    t,
+    send: (text) => send(ctx, { kind: 'text', text: text.trim() }, text),
+    act,
+    answer: (ref, text) => send(ctx, { kind: 'answer', text: text.trim(), question_ref: ref }, text),
+    retry: () => {
+      const f = s?.failed;
+      if (busy || !f || !s) return;
+      const last = s.messages[s.messages.length - 1];
+      if (last?.role === 'assistant' && last.status === 'failed') s.messages.pop();
+      turn(ctx, f);
+      draw();
+    },
+    stop: () => {
+      stopped = true;
+      ctl?.abort();
+    },
+    startOver: () => {
+      ctl?.abort();
+      ctl = null;
+      busy = false;
+      s = fresh();
+      save();
+      draw();
+      box.querySelector<HTMLInputElement>('input')?.focus();
+    },
+    close,
+    products: productsOf,
+    actionsOf: (b, r) => {
+      const a = Array.isArray(b.products) ? b.products.find((p) => products.get(idOf(p)) === r)?.actions : null;
+      return Array.isArray(a) ? a : NO_ACTIONS;
+    },
+    md: (text) => {
+      let out = parsed.get(text);
+      if (out === undefined) {
+        out = md(text);
+        if (!busy) parsed.set(text, out);
+      }
+      return out;
+    },
+  };
+  // The panel drawn only while it is open (show() draws it as it opens): a box streaming on the search page redraws itself alone.
+  draw = (opening = false) => {
+    if (CONVO_ASSIST) drawPreview(ctx);
+    if (!s || !dialog || !(opening || dialog.open)) return;
+    try {
+      const had = root.activeElement as HTMLButtonElement | null;
+      v.render('convo-box', {
+        ...scope,
+        messages: s.messages,
+        busy,
+        state: off ? 'unavailable' : s.state,
+        refinements: s.refinements,
+      });
+      settleImages(box, fade);
+      // A control that went with the render (a suggestion used, the input disabled at the end):
+      // focus to the log, not to the inert page (no keyboard popping up on a phone either).
+      if (had && (!had.isConnected || had.disabled)) box.querySelector<HTMLElement>('[data-lbx-convo-log]')?.focus();
+    } catch (e) {
+      reportError('convo render', e);
+    }
+  };
+  // Product clicks and add-to-carts on our tiles (core/tiles.ts).
+  watch(box, { list: 'lbx_convo', global: ctx.global, results: shown });
+  dialog.addEventListener('close', () => {
+    setCss('convo:lock', null);
+    // Back to the trigger; one of ours hidden meanwhile (the autocomplete's nudge: its dropdown closed as focus
+    // left it) gives it to the site's search field. A site's trigger it removed: left to the browser.
+    const shown = opener instanceof HTMLElement && opener.isConnected && opener.getClientRects().length;
+    const back = shown ? opener : ours(opener) && ctx.global.inputSelector ? [...document.querySelectorAll<HTMLElement>(ctx.global.inputSelector)].find((i) => i.getClientRects().length) : null;
+    (back as HTMLElement | null | undefined)?.focus();
+    mark('convo close');
+  });
+  // A press on the backdrop (the dialog itself: its content fills it) closes it; a
+  // text selection dragged out of the log onto it (its click's target is the dialog too) does not.
+  let down: EventTarget | null = null;
+  dialog.addEventListener('pointerdown', (e) => (down = e.target));
+  // Not a double click's second (on the trigger: the first opened it, the second lands on the backdrop).
+  dialog.addEventListener('click', (e) => e.target === dialog && down === dialog && e.detail < 2 && close());
+  onUrlChange(close);
+  // A turn on its way keeps the page out of the back/forward cache: cut it (sent again from the next page's dialog).
+  addEventListener('pagehide', () => {
+    // Its catch runs before the page unloads (every engine, tested): the turn is kept as failed, retriable.
+    ctl?.abort();
+    save();
+  });
+};
+
+/** A node Luma created (our sparkle, the autocomplete's dropdown and its templates), across shadow roots, by identity: not the site's markup. */
+const ours = (n: Element | null) => {
+  for (; n; n = n.parentElement ?? ((n.getRootNode() as ShadowRoot).host || null)) if (created.has(n)) return true;
+  return false;
+};
+
+/**
+ * Called by the entry on a click on a `data-lbx-convo` element: `prompt` is
+ * its value. Asked at once from a trigger of ours (an autocomplete template
+ * passing the phrase typed); from the site's markup only put in the input,
+ * for the shopper to send: text on the page (a review, a crafted link's
+ * phrase) is never asked in their name.
+ */
+export const open = (ctx: Ctx, prompt: string, trigger: Element | null) => {
+  show(ctx, trigger);
+  if (!prompt.trim()) return;
+  // The autocomplete's nudge: the answer /assist already has for the phrase, taken over.
+  if (CONVO_ASSIST) {
+    const a = ours(trigger) ? answerFor(prompt) : undefined;
+    if (a && !busy) return void adopt(ctx, a);
+  }
+  // Not while an answer is on its way: then it waits in the input, as the site's do.
+  if (ours(trigger) && !busy) scope.send(prompt);
+  else {
+    const i = box.querySelector<HTMLInputElement>('input[name="q"]');
+    if (i && !i.value) i.value = prompt;
+  }
+};
+
+/** /assist's answer as a new conversation's first turn (its own id: the panel goes on with it). */
+const adopt = (ctx: Ctx, a: Answer) => {
+  if (s?.id === a.id) return Promise.resolve();
+  hold(a);
+  ctl?.abort();
+  s = { ...fresh(), id: a.id };
+  s.messages.push({ role: 'user', text: a.query, blocks: [], status: 'done' });
+  const done = turn(ctx, { input: { kind: 'text', text: a.query }, key: a.key }, a);
+  draw();
+  toEnd();
+  return done;
+};
+
+/** The panel, opened (built the first time, the session's conversation read back). */
+const show = (ctx: Ctx, trigger: Element | null) => {
+  const first = !s;
+  if (!dialog) build(ctx);
+  // A host that swaps <body> (Turbo Drive, Astro's view transitions) took ours with it: back in, closed.
+  else if (!host.isConnected) {
+    dialog.removeAttribute('open');
+    setCss('convo:lock', null);
+    document.body.append(host);
+  }
+  if (!s) {
+    s = restore();
+    off = session.get(ON) === false;
+  }
+  opener = trigger;
+  draw(true);
+  if (!dialog!.open) {
+    // The page behind does not scroll (its own scrollbar would move under the dialog).
+    setCss('convo:lock', ':root{overflow:hidden!important}');
+    dialog!.showModal();
+    toEnd();
+    mark('convo open');
+  }
+  // Respond first: the requests (the session's check, a conversation's products read back) in the next task.
+  setTimeout(() => {
+    check(ctx);
+    if (first)
+      hydrate(
+        ctx,
+        s!.messages.flatMap((m) => m.blocks.flatMap((b) => (Array.isArray(b.products) ? b.products : []))),
+      );
+  }, 0);
+};
+
+// --- the search page's box: /assist's answer to the query, above the results (convo.assist)
+let pv: {
+  el: HTMLElement;
+  box: HTMLElement;
+  v: ReturnType<typeof view>;
+  a: Answer | null;
+  on: string;
+  off?: () => void;
+} | null = null;
+const drawPreview = (ctx: Ctx) => {
+  if (!pv?.a) return;
+  const a = pv.a;
+  // An answer that broke off (or was cut as the page was left): no box; focus in it goes on to the listing after it, not to <body>.
+  if (a.failed) {
+    const next = pv.el.nextElementSibling as HTMLElement | null;
+    if (pv.el.shadowRoot!.activeElement && next) {
+      if (!next.hasAttribute('tabindex')) next.tabIndex = -1;
+      next.focus({ preventScroll: true });
+    }
+    pv.el.style.display = 'none';
+    return;
+  }
+  pv.el.style.display = '';
+  try {
+    pv.v.render('convo-preview', {
+      ...scope,
+      query: a.query,
+      blocks: a.blocks,
+      done: a.done,
+      // "Continue with the assistant": the panel, going on with this conversation; a suggestion: that turn next.
+      // Focus goes back to the control pressed when the panel closes.
+      open: (then?: ConvoAction, from?: Element | null) => {
+        show(ctx, from ?? null);
+        if (busy && s?.id !== a.id) return;
+        void adopt(ctx, a).then(() => then && scope.act(then));
+      },
+    });
+    settleImages(pv.box, NAMED_FADE ? ctx.global.images?.fade !== false : true);
+  } catch (e) {
+    reportError('convo preview', e);
+  }
+};
+
+/**
+ * Called by the entry on a search page whose query /assist answered: the box
+ * above the listing (`lbx-search`, a placement rule: it waits for the page's
+ * framework, the host may re-render around it), drawn as the answer streams in.
+ * A new query (in place) brings a new answer or none: the box goes with its URL.
+ */
+export const preview = CONVO_ASSIST
+  ? (ctx: Ctx, a: Answer, at: string): void => {
+      // A late answer to a query the page has moved on from: not shown, nor in the place of the current one's.
+      if (at !== location.href) return;
+      // An answer kept from the autocomplete comes at once: before <body> exists on a page still parsing.
+      if (!document.body) return void addEventListener('DOMContentLoaded', () => preview!(ctx, a, at), { once: true });
+      hold(a);
+      // The panel's scope (its words, products, Markdown) is the box's too; the conversation is read back when it opens.
+      if (!dialog) build(ctx);
+      if (!pv) {
+        const el = document.createElement('lbx-convo-preview');
+        const root = el.attachShadow({ mode: 'open' });
+        const style = document.createElement('style');
+        style.nonce = cspNonce();
+        style.textContent = [CSS, ...ctx.styles].join('\n');
+        const b = document.createElement('div');
+        b.className = 'lbx-cv lbx-cv--preview';
+        root.append(style, b);
+        pv = { el, box: b, v: view(b, ctx.templates), a: null, on: '' };
+        watch(b, {
+          list: 'lbx_convo',
+          global: ctx.global,
+          results: () => (pv?.a ? pv.a.blocks.flatMap(productsOf) : []),
+        });
+        const p = pv;
+        import('../../core/reconciler')
+          .then(({ addRule }) => {
+            addRule({
+              id: 'convo-preview',
+              active: (u) => u.href === p.on,
+              anchors: ['lbx-search'],
+              position: 'before',
+              // Its accent made readable once it is in the page (a detached element has no computed colours).
+              create: () => (readable(p.el), p.el),
+            });
+            schedule();
+          })
+          .catch((e) => reportError('convo preview', e));
+      }
+      pv.off?.();
+      pv.a = a;
+      pv.on = at;
+      let seen = 0;
+      // Its products, looked up as their blocks arrive.
+      const on = () => {
+        for (; seen < a.blocks.length; seen++) hydrate(ctx, a.blocks[seen].products);
+        later();
+      };
+      pv.off = a.listen(on);
+      on();
+      drawPreview(ctx);
+      schedule();
+    }
+  : undefined;