@luigisbox/luma 0.7.0 → 0.8.0-beta.0

package/src/main.ts

@@ -25,15 +25,17 @@ import { plpAccepts, searchAccepts, searchReadQuery } from './core/routes';
 import { clearEarlyRules, earlyHold, plpRule, searchRule, writeEarlyRules, type EarlyRoute } from './core/early-rules';
 import { askChallenge, storedToken } from './api/token-key';
 import { loadDictionary } from './core/locales';
-import { ANALYTICS, AUTOCOMPLETE, NAMED_PRECONNECT_IMAGES, NAMED_PREFETCH_WHILE_TYPING, NAMED_SPECULATION, PLP, QUERY_URL, RECOMMENDER, SEARCH, SSR } from './core/features';
+import { ANALYTICS, AUTOCOMPLETE, CONVO, CONVO_ASSIST, CONVO_TRIGGER, NAMED_PRECONNECT_IMAGES, NAMED_PREFETCH_WHILE_TYPING, NAMED_SPECULATION, PLP, QUERY_URL, RECOMMENDER, SEARCH, SSR } from './core/features';
 import { keepDl } from './core/kept';
+import { created } from './core/own';
 import './core/boot-state'; // the page's state at boot, for lbx-place's reconciler
 import { onFlush, schedule } from './core/scheduler';
 import { onUrlChange, startSensing } from './core/sense';
 import { layered, setCss, whenApplied } from './core/styles';
+import { session } from './core/storage';
 import type { ListingRoute } from './core/listings';
 import type { Reco } from './core/recommenders';
-import type { GlobalConfigType, LumaConfigType, Result, SearchConfigType } from './types';
+import type { ConvoConfigType, GlobalConfigType, LumaConfigType, Result, SearchConfigType } from './types';
 
 declare const __VERSION__: string;
 // Replaced at build time; the dev server (the loader's development mode) does not replace it.
@@ -57,6 +59,8 @@ export interface WidgetContext<C = any> {
   helpers: Record<string, unknown>;
   /** The search page of a phrase where the site's server redirects its form there (`search.queryUrl`): the autocomplete's "show all" link. */
   queryUrl?: SearchConfigType['queryUrl'];
+  /** The conversational search, where it asks about what is typed (`convo.assist`): the autocomplete's nudge. */
+  assist?: ConvoConfigType;
 }
 
 export const startIntegration = async (files: IntegrationFiles) => {
@@ -114,6 +118,7 @@ const modules = {
   search: SEARCH ? () => import('./widgets/search') : null,
   plp: PLP ? () => import('./widgets/plp') : null,
   recommender: RECOMMENDER ? () => import('./widgets/recommender') : null,
+  convo: CONVO ? () => import('./widgets/convo') : null,
 };
 type Kind = keyof typeof modules;
 
@@ -469,6 +474,86 @@ function boot(config: LumaConfigType, files: IntegrationFiles) {
     onFlush(() => recent() && check());
   }
 
+  // --- the conversational search (widgets/convo, lbx-convo): a click on an
+  // element with data-lbx-convo (the site's markup, or a template's) opens
+  // it, its value the first question; a pointer over one, or its focus,
+  // fetches the chunk ahead. Where the site's assistant was found off this
+  // session (widgets/convo ON), its triggers are hidden. `trigger`: a button
+  // of ours in the site's search field (`anchor`), opening it with the
+  // phrase typed; kept there on every reconcile (the host may re-render it).
+  const cv = config.convo;
+  if (CONVO && cv && !cv.disabled) {
+    if (session.get('lbx:convo:on') === false) setCss('convo:off', '[data-lbx-convo]{display:none!important}');
+    const hostConvo = hostCss('convo');
+    if (hostConvo) setCss('host-convo', hostConvo);
+    // Luma's sparkle in the site's search field: built and placed by lbx-place (widgets/convo/trigger.ts,
+    // the reconciler's chunk, loaded after boot); only where convo/_config.ts names `trigger`.
+    const tr = cv.trigger;
+    if (CONVO_TRIGGER && tr?.anchor)
+      import('./widgets/convo/trigger')
+        .then((m) => m.place(tr, g))
+        .catch((e) => reportError('convo trigger', e));
+    const loadCv = () => load('convo', 'convo', ['_global', 'convo'], cv, ['convo']);
+    // The assistant's answer to a search page's query (convo.assist): /assist (lbx-assist)
+    // asked as the page is the search route's, with its listing, for a phrase of 3+ words
+    // (the autocomplete's rule); the panel's chunk and a box above the results only where it
+    // answers, on that URL only (a late answer to an earlier query is not shown). Asked for a
+    // search the shopper made here: reached from the site's own pages, or a new query in place.
+    // A page reached from elsewhere (a crafted link's phrase) shows only an answer this tab
+    // already has: a phrase is never asked in the shopper's name. Asked again on a page
+    // restored from the back/forward cache (an answer streaming was cut as it was left).
+    if (CONVO_ASSIST && cv.assist && search) {
+      const readQ = searchReadQuery(search);
+      // A referrer is serialised with a path: the site's own pages, not a look-alike host or another port.
+      const here = document.referrer.startsWith(`${location.origin}/`);
+      const phrase = (u: URL) => readQ(u)?.trim().replace(/\s+/g, ' ').toLowerCase() ?? '';
+      // The phrase a page reached from elsewhere came with: never the shopper's, whatever later
+      // writes the URL (a filter, a sort, the host's own replaceState, Back to it).
+      const landed = here ? '' : phrase(new URL(location.href));
+      const ask = (u: URL) => {
+        if (session.get('lbx:convo:lean') === false || !routes.some((r) => r.kind === 'search' && r.accepts(u))) return;
+        const q = readQ(u)?.trim().replace(/\s+/g, ' ');
+        if (q && q.split(' ').length >= 3)
+          import('./widgets/convo/assist')
+            // Held as it comes (the box's): the autocomplete sharing it never cuts it, even before the panel's chunk is here.
+            .then((m) => m.ask(g, cv, q, !!landed && phrase(u) === landed).then((a) => (a && m.hold(a), a)))
+            .then((a) => a && run('convo', loadCv(), ({ mod, ctx }) => mod.preview(ctx, a, u.href)))
+            .catch((e) => reportError('convo assist', e));
+      };
+      ask(new URL(location.href));
+      onUrlChange(ask);
+      addEventListener('pageshow', (e) => e.persisted && ask(new URL(location.href)));
+    }
+    // composedPath: a trigger in a shadow root (a template of ours, the site's web component).
+    const triggerOf = (e: Event) => e.composedPath().find((n): n is Element => n instanceof Element && n.hasAttribute('data-lbx-convo'));
+    const ahead = (e: Event) => {
+      if (!triggerOf(e)) return;
+      for (const t of ['pointerover', 'focusin']) removeEventListener(t, ahead, true);
+      loadCv().catch(() => {});
+    };
+    for (const t of ['pointerover', 'focusin']) addEventListener(t, ahead, true);
+    addEventListener(
+      'click',
+      (e) => {
+        const t = triggerOf(e);
+        if (!t) return;
+        e.preventDefault(); // a link or a form's button as the trigger: the dialog instead
+        // Our sparkle (by identity): the phrase typed in the site's search input
+        // (`inputSelector`, a text or search field; nothing else of their forms).
+        const i = CONVO_TRIGGER && created.has(t) && g.inputSelector ? (t.closest('form') ?? document).querySelector(g.inputSelector) : null;
+        const typed = i instanceof HTMLInputElement && /^(text|search)$/.test(i.type) ? i.value : null;
+        // Its chunk failed to load: the site's link or submit button does what it would have
+        // (a same-window web page only: a target or download link is left, as is a click elsewhere).
+        const fallback = () => {
+          if (t instanceof HTMLAnchorElement) return void (/^https?:$/.test(t.protocol) && (!t.target || t.target === '_self') && !t.hasAttribute('download') && location.assign(t.href));
+          if (t instanceof HTMLButtonElement && t.type === 'submit' && t.form) t.form.requestSubmit(t);
+        };
+        run('convo', loadCv(), ({ mod, ctx }) => mod.open(ctx, typed ?? t.getAttribute('data-lbx-convo') ?? '', t), fallback);
+      },
+      true,
+    );
+  }
+
   // --- analytics (src/analytics, lbx-analytics): where the integration has an
   // _analytics.ts (nothing is sent that it does not say), every page once it
   // has loaded or with the first widget (its chains on our tiles listen then).

package/src/types.ts

@@ -596,8 +596,55 @@ export interface RecommenderConfigType extends AppConfig<RecommenderConfigType>
   intent?: (target: Element) => string | null;
 }
 
+/**
+ * The conversational search (integration/convo/): a dialog where the shopper
+ * asks in their own words and an assistant answers with text and products.
+ * Opened by a click on any element with `data-lbx-convo` (its value, when
+ * not empty, is the first question). The conversation is Luigi's Box's
+ * conversation service (keyed by the site's tracker id); its products are
+ * looked up on the channel's collection surface, so tiles are the catalog's
+ * as every other widget's.
+ */
+export interface ConvoConfigType extends AppConfig<ConvoConfigType> {
+  /** The site's tracker id in Luigi's Box's conversation service (`1234-5678`). */
+  trackerId: string;
+  /** The conversation service's base URL (default `https://conversational-proxy.luigisbox.com/api/v2`). */
+  endpoint?: string;
+  /** Collection surface (lbs_collection_…) the conversation's products are looked up on. */
+  surface: string;
+  /** The catalog field holding the identity the conversation names a product by. */
+  idField: string;
+  /** Object type of the products (default: _global.itemType). */
+  type?: string;
+  /** return_fields the tiles need (keeps the response small). */
+  fields?: string[];
+  /** The language the assistant answers in (en, sk, cs, pl, de, hu); default _global.locale. */
+  locale?: string;
+  /** The catalog fields the assistant reads a price and availability from, when the service asks for them. */
+  priceField?: string;
+  availabilityField?: string;
+  /**
+   * A button of Luma's (a sparkle, `[data-lbx="convo-trigger"]`) placed
+   * at `anchor` (`position`, default `append`), typically in the site's
+   * search form: it opens the dialog with the phrase typed in the form's
+   * search input. `label` names it (default "Ask the shopping assistant").
+   * The folder's style-host.css places it in the field. Built only where
+   * this key is in convo/_config.ts (about 0.5 kB of every page).
+   */
+  trigger?: { anchor: string; position?: Position; label?: string };
+  /**
+   * Ask the assistant about what the shopper types (lean trackers only):
+   * the autocomplete shows a row with its answer's first words when it has
+   * one (a settled phrase of 3+ words), the search page a box with the answer
+   * above the results; either continues in the panel. Built only where this
+   * key is in convo/_config.ts.
+   */
+  assist?: boolean;
+}
+
 export interface LumaConfigType {
   _global: GlobalConfigType;
+  convo?: ConvoConfigType;
   autocomplete?: AutocompleteConfigType;
   search?: SearchConfigType;
   plp?: PlpConfigType;
@@ -789,6 +836,14 @@ export interface SearchResultScope extends SearchScope {
 
 export interface AutocompleteScope extends Helpers {
   query: string;
+  /**
+   * The assistant's answer to what is typed (`convo.assist`: a phrase of 3+
+   * words), as its first words stream in; null without one. Render it as a
+   * button with `data-lbx-convo=${assist.query}` and `data-lbx-assist`: a
+   * click opens the panel with the answer (Tab reaches it before "Show all
+   * products").
+   */
+  assist: { query: string; text: string; done: boolean } | null;
   /** One group per configured type that has results, in config order; `kind` is the type. */
   groups: { kind: string; label: string; rows: { r: Result; i: number }[] }[];
   /** Rows of one type ([] when none). */
@@ -864,3 +919,72 @@ export interface RecommenderResultScope extends RecommenderScope {
   r: Result;
   i: number;
 }
+
+/** A control the assistant offers (a suggestion, a question's choice, a product's "tell me more"). */
+export interface ConvoAction {
+  label: string;
+  action_ref?: string | null;
+}
+/**
+ * A block of an answer, as the conversation service sends it (rendered in
+ * its order): `text` (`text`, Markdown: render it with `md`), `suggestions` (`actions`), `question` (`text`, `choices`,
+ * `text_input`, `question_ref`), `product_grid` and `product_preview`
+ * (`products`: read them with `products(block)`), `comparison` (`products`,
+ * `rows` of `label` and `values`), `notice` and `support` (`title`, `text`,
+ * `actions`), `provenance` (`items`). An unknown type renders nothing.
+ */
+export interface ConvoBlock {
+  block_id: string;
+  type: string;
+  heading?: string | null;
+  [field: string]: any;
+}
+export interface ConvoMessage {
+  role: 'user' | 'assistant';
+  /** The question ('' for an answer: its blocks hold its text, in its places). */
+  text: string;
+  blocks: ConvoBlock[];
+  status: 'streaming' | 'done' | 'failed' | 'ignored';
+  /** What went wrong (a key of the widget's translations: error, busy, gone, unavailable, limit, stopped). */
+  error?: string;
+  /** The failed turn can be sent again (`retry`). */
+  retry?: boolean;
+}
+export interface ConvoScope extends Helpers {
+  messages: ConvoMessage[];
+  /** A turn is on its way: Stop instead of Send. */
+  busy: boolean;
+  /** `unavailable`: the site's assistant is off; `ended`: start over to go on; `final`: it cannot go on. */
+  state: 'ready' | 'unavailable' | 'ended' | 'final';
+  /** What the assistant goes by (filters, preferences), each with a remove control. */
+  refinements: { state_item_id: string; label: string; remove?: { action_ref: string; accessible_label: string } | null }[];
+  send: (text: string) => void;
+  act: (a: ConvoAction) => void;
+  answer: (questionRef: string, text: string) => void;
+  retry: () => void;
+  stop: () => void;
+  startOver: () => void;
+  close: () => void;
+  /** The products of a block, as results, in its order (those the catalog has). */
+  products: (b: ConvoBlock) => Result[];
+  /** A product's own controls in a block ("Tell me more"); the same array every draw. */
+  actionsOf: (b: ConvoBlock, r: Result) => ConvoAction[];
+  /** The assistant's Markdown (paragraphs, lists, headings, emphasis, tables, same-site links) as markup. */
+  md: (text: string) => unknown;
+}
+/** The search page's box (`convo.assist`): the answer to its query, streaming in. */
+export interface ConvoPreviewScope extends ConvoScope {
+  query: string;
+  /** The answer's blocks so far (text in its places). */
+  blocks: ConvoBlock[];
+  /** It has all come. */
+  done: boolean;
+  /** The panel, going on with this conversation; with a suggestion, that turn next; `from`: the control pressed (focus goes back to it as the panel closes). */
+  open: (then?: ConvoAction, from?: Element | null) => void;
+}
+export interface ConvoResultScope extends ConvoScope {
+  r: Result;
+  i: number;
+  /** The product's own controls ("Tell me more"). */
+  actions: ConvoAction[];
+}

package/src/widgets/autocomplete/index.ts

@@ -18,9 +18,9 @@ import { borrow, liveRegion, useContrast } from '../../core/a11y';
 import { luminanceOf, readable } from '../../core/color';
 import { defaultSubmitter, formDataOf } from '../../core/default-button';
 import { onOwnBack } from '../../core/entries';
-import { AC_HOOKS, ANALYTICS, LIGHT_FULL_SCREEN, QUERY_URL } from '../../core/features';
+import { AC_HOOKS, ANALYTICS, CONVO_ASSIST, LIGHT_FULL_SCREEN, QUERY_URL } from '../../core/features';
 import { mark, reportError } from '../../core/health';
-import { modalOf } from '../../core/own';
+import { created, modalOf } from '../../core/own';
 import { byName, view } from '../../core/templates';
 import { first, navigable, plain, safeUrl } from '../../core/result';
 import { afterFrame } from '../../core/scheduler';
@@ -330,6 +330,7 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
     if (host) return;
     host = document.createElement('div');
     host.setAttribute('data-lbx', 'ac-overlay');
+    created.add(host);
     host.setAttribute('popover', 'manual');
     host.id = (light && ac.hostId) || 'lbx-ac-overlay';
     if (light) {
@@ -396,6 +397,13 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
         return;
       }
       if (e.key !== 'Tab' && e.key !== 'Escape') return;
+      // The nudge and "Show all products": Tab and Shift+Tab between them.
+      if (CONVO_ASSIST && e.key === 'Tab') {
+        const at = e.composedPath()[0] as Element;
+        const sel = !e.shiftKey && at?.closest?.('[data-lbx-assist]') ? '[data-lbx-all]' : e.shiftKey && at?.closest?.('[data-lbx-all]') ? '[data-lbx-assist]' : '';
+        const to = sel ? box.querySelector<HTMLElement>(sel) : null;
+        if (to) return void (e.preventDefault(), to.focus());
+      }
       if (e.key === 'Escape') {
         e.preventDefault();
         e.stopPropagation(); // ours, not a host modal's
@@ -894,7 +902,7 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
         mirror.setSelectionRange(from, to);
       } catch {}
     }
-    query(mirror?.value ?? i.value);
+    query(mirror?.value ?? i.value, true);
     rehearse(); // the first results' one-time costs, while the visitor starts typing
   };
 
@@ -944,6 +952,7 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
     // Answers still on their way fill the cache but do not reopen it: only the
     // visitor does (typing, focus, a press into the input).
     want = '';
+    if (CONVO_ASSIST) clearTimeout(assistTimer);
     clearTimeout(timer); // a debounce still pending asks for nothing
     timer = waiting = 0;
     if (!open) return;
@@ -1057,6 +1066,7 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
       unhover,
       heroVariant: ac.hero?.variant === 'spec' ? 'spec' : 'image',
       productLayout: ac.productLayout === 'list' ? 'list' : 'grid',
+      assist: CONVO_ASSIST ? (assisted && assisted.q === want && !assisted.a.failed ? { query: assisted.q, text: assisted.a.text(), done: assisted.a.done } : null) : null,
       field: (r: Result, name: string) => {
         const f = name === 'badge' ? ac.hero?.badgeField : (ac.productFields as Record<string, string | undefined> | undefined)?.[name];
         if (!f) return '';
@@ -1131,8 +1141,10 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
       return '';
     }
   };
-  /** "Show all products" (`data-lbx-all`), the dropdown's one tab stop, while it is open. */
+  /** "Show all products" (`data-lbx-all`), the arrows' last stop and the dropdown's tab stop, while it is open. */
   const allLink = () => (open ? (box.querySelector('[data-lbx-all]') as HTMLElement | null) : null);
+  /** Where Tab from the input goes: the assistant's nudge (`data-lbx-assist`), else "Show all products". */
+  const tabStop = () => (CONVO_ASSIST && open ? (box.querySelector('[data-lbx-assist]') as HTMLElement | null) : null) ?? allLink();
   /** Inside our dropdown (its shadow root too). */
   const inOverlay = (el: Element | null) => !!el && !!host && (host.contains(el) || !!host.shadowRoot?.contains(el));
   /** Focus back on the input from our dropdown, without it counting as the visitor's focus. */
@@ -1301,10 +1313,54 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
     launch(want);
   };
 
-  const query = (value: string) => {
+  // The assistant (convo.assist): asked about a phrase of 3+ words once it has settled
+  // (0.6 s: an answer costs the site a generated reply), its answer's first words a row
+  // on top of the dropdown (the nudge). Its client is its own chunk (lbx-assist).
+  let assistTimer = 0;
+  let assisted: { q: string; a: import('../convo/assist').Answer; off: () => void } | null = null;
+  const assistSoon = (q: string) => {
+    clearTimeout(assistTimer);
+    const cv = ctx.assist;
+    if (!cv || q.split(' ').length < 3 || assisted?.q === q) return;
+    // The chunk on its way while the phrase settles: the request goes as the pause ends, not a round trip later.
+    const mod = import('../convo/assist');
+    assistTimer = window.setTimeout(
+      () =>
+        void mod
+          .then((m) =>
+            // The phrase as found, not typed: only an answer this tab has (a crafted link's phrase is never asked).
+            m.ask(ctx.global, cv, q, q === found).then((a) => {
+              // Typed past it meanwhile: its stream is cut (not kept), unless it has come whole.
+              if (!a || want !== q) return void (a && m.drop(q));
+              if (assisted) m.drop(assisted.q);
+              assisted?.off();
+              // Drawn at most once a frame, and only when what the row shows changes (its first words, its end).
+              let shown = '';
+              let frame = 0;
+              const off = a.listen(() => {
+                const now = a.done ? `${a.failed}` : a.text();
+                if (now === shown || frame) return;
+                shown = now;
+                frame = requestAnimationFrame(() => ((frame = 0), want === q && render()));
+              });
+              assisted = { q, a, off };
+              render();
+              live.say(t('assist.title'), 700, true);
+            }),
+          )
+          .catch((e) => reportError('autocomplete assist', e)),
+      600,
+    );
+  };
+
+  /** The phrase the field held as the shopper came to it (a search page's query: maybe a link's from elsewhere), not typed. */
+  let found = '';
+  const query = (value: string, reopened = false) => {
     const q = norm(value);
     clearTimeout(timer);
     timer = 0;
+    if (reopened) found = q;
+    if (CONVO_ASSIST) assistSoon(q);
     if (q.length < minChars) {
       waiting = 0;
       queued = '';
@@ -1583,7 +1639,7 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
     watchRoots(i);
     adopt(i);
     prepare(i);
-    if (input.value.trim().length >= minChars) query(input.value);
+    if (input.value.trim().length >= minChars) query(input.value, true);
   };
 
   const onFocusIn = once<'focusin'>((_, target) => {
@@ -1676,7 +1732,7 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
       // "Show all products" is the dropdown's tab stop: Tab reaches it (it sits
       // at the end of <body> or in the top layer, never next to the input in
       // the page's own order). Alt+Tab too (Safari's Option+Tab).
-      const all = allLink();
+      const all = tabStop();
       if (!all) return;
       consume(e);
       // The one thing lit: the options' selection goes (its focus ring shows where Tab went).
@@ -1702,7 +1758,7 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
     if (matches(target) && !open && target === focused()) {
       if (phone()) return engage(target);
       input = target;
-      if (input.value.trim().length >= minChars) query(input.value);
+      if (input.value.trim().length >= minChars) query(input.value, true);
       return;
     }
     if (!open || target === input || (host && e.composedPath().includes(host))) return;

package/src/widgets/autocomplete/style-autocomplete.css

@@ -278,3 +278,34 @@ button { font: inherit; color: inherit; background: none; border: 0; padding: 0;
   }
   .all, .pill, .try, .compact { border: 1px solid CanvasText; }
 }
+
+/* @lbx-part autocomplete-assist: the assistant's nudge (convo.assist): a row on top of the panel,
+   its answer's first words streaming in; a shimmer sweeps across it once as it arrives (not under reduced motion). */
+.nudge { display: flex; align-items: center; gap: 12px; width: 100%; margin: 0 0 12px; padding: 10px 14px; border: 1px solid var(--c-tint, var(--lbx-tint)); border-radius: var(--lbx-radius-row); background: var(--lbx-tint); color: var(--c-fg); text-align: start; }
+.nudge:hover, .nudge:focus-visible { border-color: var(--c-accent); }
+.nudge-mark { flex: none; display: flex; align-items: center; justify-content: center; width: 30px; height: 30px; border-radius: 50%; background: var(--c-fill); color: var(--c-on-fill); }
+.nudge-body { flex: 1; min-width: 0; display: flex; flex-direction: column; gap: 2px; }
+.nudge-title { font-weight: 600; }
+/* Its words in the text colour (the row's, inherited): on the accent's tint, the muted grey and the accent itself can fall under 4.5:1 (the accent is guarded on white only). */
+.nudge-text { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.nudge-go { flex: none; display: inline-flex; align-items: center; gap: 4px; font-weight: 600; }
+.nudge-go svg { color: var(--c-accent); }
+@media (prefers-reduced-motion: no-preference) {
+  .nudge { background-image: linear-gradient(100deg, transparent 30%, rgb(255 255 255 / .7) 50%, transparent 70%); background-size: 250% 100%; background-repeat: no-repeat; animation: lbx-nudge 1.4s ease-out 1 both, lbx-nudge-in .25s ease-out; }
+}
+/* Until its first words come: three dots, moving (fading in turn under reduced motion): it is on its way, not stuck. */
+.nudge-wait { display: inline-flex; gap: 4px; padding: 6px 0; vertical-align: middle; }
+/* Borders, not a background: forced colours keep them, as the text colour. */
+.nudge-wait i { width: 0; height: 0; border: 3px solid; border-radius: 50%; animation: lbx-nudge-fade 1.2s ease-in-out infinite; }
+.nudge-wait i:nth-child(2) { animation-delay: .15s; }
+.nudge-wait i:nth-child(3) { animation-delay: .3s; }
+@media (prefers-reduced-motion: no-preference) {
+  .nudge-wait i { animation-name: lbx-nudge-dot; }
+}
+@keyframes lbx-nudge-dot { 0%, 60%, 100% { transform: none; opacity: .4; } 30% { transform: translateY(-4px); opacity: 1; } }
+@keyframes lbx-nudge-fade { 0%, 60%, 100% { opacity: .3; } 30% { opacity: 1; } }
+@keyframes lbx-nudge { from { background-position: 120% 0; } to { background-position: -120% 0; } }
+@keyframes lbx-nudge-in { from { opacity: 0; transform: translateY(-4px); } }
+.sh-assist { padding: 8px 12px 0; }
+.sh-assist .nudge { margin: 0; }
+/* @lbx-part-end */

package/src/widgets/autocomplete/template-autocomplete-assist.ts

@@ -0,0 +1,16 @@
+import { html, nothing } from '../../lit';
+import type { AutocompleteScope } from '../../types';
+import { ARROW } from './template-autocomplete-box';
+
+// The assistant's nudge (`convo.assist`): a row on top of the panel, its
+// answer's first words streaming in (dots moving until the first ones come),
+// a one-time shimmer; a click opens the
+// panel with the answer. Built only where convo/_config.ts names `assist`.
+export default (s: AutocompleteScope) =>
+  s.assist
+    ? html`<button type="button" class="nudge" data-lbx-part="ac-assist" data-lbx-assist data-lbx-convo=${s.assist.query}>
+        <span class="nudge-mark" aria-hidden="true"><svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor"><path d="M10 3l1.6 4.4L16 9l-4.4 1.6L10 15l-1.6-4.4L4 9l4.4-1.6zM18 13l.9 2.1L21 16l-2.1.9L18 19l-.9-2.1L15 16l2.1-.9z"></path></svg></span>
+        <span class="nudge-body"><span class="nudge-title">${s.t('assist.title')}</span><span class="nudge-text">${s.assist.text || (s.assist.done ? nothing : html`<span class="nudge-wait" aria-hidden="true"><i></i><i></i><i></i></span>`)}</span></span>
+        <span class="nudge-go">${s.t('assist.continue')}${ARROW}</span>
+      </button>`
+    : nothing;

package/src/widgets/autocomplete/template-autocomplete-box.ts

@@ -1,4 +1,5 @@
 import { html, nothing, repeat } from '../../lit';
+import { CONVO_ASSIST } from '../../core/features';
 import type { AutocompleteScope } from '../../types';
 
 // The house design's panel: an accent
@@ -37,6 +38,7 @@ export default (s: AutocompleteScope) => {
     <div class=${cls} data-lbx-part="ac-panel">
       <span class="caret" aria-hidden="true"></span>
       <div class="panel">
+        ${CONVO_ASSIST ? s.include('autocomplete-assist') : nothing}
         ${s.state !== 'results'
           ? s.include('autocomplete-empty')
           : html`<div class="cols" role="listbox" id="lbx-ac-listbox" aria-label=${s.t('label')}>

package/src/widgets/autocomplete/template-autocomplete-sheet.ts

@@ -1,4 +1,5 @@
 import { html, nothing, repeat } from '../../lit';
+import { CONVO_ASSIST } from '../../core/features';
 import type { AutocompleteScope } from '../../types';
 import { POWERED, group, showAll } from './template-autocomplete-box';
 
@@ -45,6 +46,7 @@ export default (s: AutocompleteScope) => {
           ? html`<button type="button" class="icon clear" aria-label=${s.t('clear')} @click=${() => s.clear()}><span class="x"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.25" stroke-linecap="round" aria-hidden="true"><path d="M6 6l12 12M18 6 6 18"></path></svg></span></button>`
           : nothing}
       </div>
+      ${CONVO_ASSIST && s.assist ? html`<div class="sh-assist">${s.include('autocomplete-assist')}</div>` : nothing}
       ${s.state === 'empty'
         ? s.include('autocomplete-empty')
         : results