@luigisbox/luma 0.7.0 → 0.8.0-beta.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ before 1.0, a minor version may break the integration API.
 
 ## Unreleased
 
+### Added
+
+- Conversational search: a `convo/` folder adds a dialog where the shopper
+  asks in their own words and Luigi's Box's assistant answers with text and
+  products. Opened by a click on any element with `data-lbx-convo`; its
+  code loads only when the shopper goes near one. Products come from the
+  Luigi's Box AI catalog (`surface`, `idField`); the conversation from
+  Luigi's Box's conversation service (`trackerId`).
+- `convo.trigger`: Luma's own assistant button in the site's search field.
+- `convo.assist`: for sites Luigi's Box has set up for it, the assistant's
+  answer to a phrase in the autocomplete (a row on top) and on the search
+  page (a box above the results); either continues in the panel.
+
+## 0.7.1 — 2026-11-02
+
+### Fixed
+
+- iOS Safari: swiping Back from a product to a listing showed a blank page
+  for a moment; the swipe now shows the listing.
+
 ## 0.7.0 — 2026-10-29
 
 ### Added

package/README.md

@@ -12,7 +12,7 @@ its own repository and depends on `@luigisbox/luma`
 
 > **Pre-release.** Until 1.0, a minor version (0.8.0) may change the
 > integration API (config keys, template scope, the build); a patch version
-> (0.7.1) only fixes. Depend on `^0.7.0` to take fixes without breaking
+> (0.7.2) only fixes. Depend on `^0.7.1` to take fixes without breaking
 > changes. [`CHANGELOG.md`](CHANGELOG.md) says what each version changed.
 
 ## Core principles
@@ -308,6 +308,7 @@ integration/
   search/                          _config.ts _translations.ts style-host.css template-search-*.ts
   plp/                             _config.ts _init.ts style-host.css (templates fall back to search/)
   recommender <name>/              _config.ts [_init.ts] _translations.ts
+  convo/                           _config.ts [_init.ts] [style-host.css] [style-convo.css] [template-convo-*.ts]
 ```
 
 - **`_config.ts` is JSON** (checked at boot in development: `yarn dev`);
@@ -317,7 +318,7 @@ integration/
   key is typed and documented in `src/types.ts`.
 - **A widget is its folder.** The build carries only the widgets the
   integration has folders for (`autocomplete/`, `search/`, `plp/`,
-  `recommender <name>/`) and analytics only where a folder has an
+  `recommender <name>/`, `convo/`) and analytics only where a folder has an
   `_analytics.ts`: an integration with an autocomplete only loads about half
   as much on every page as one with every widget. A config `_global/_init.ts`
   creates for a widget without its folder is ignored. The development server
@@ -343,7 +344,114 @@ integration/
   `search-facets-default`, `search-results-default`, `search-result-default`,
   `search-pagination`, `autocomplete-box`, `autocomplete-result-default`,
   `autocomplete-sheet`, `autocomplete-empty`, `recommender-box-default`,
-  `recommender-result-default`, `recommender-popup`.
+  `recommender-result-default`, `recommender-popup`, `convo-box`,
+  `convo-result-default`, and with `convo.assist`, `autocomplete-assist` and
+  `convo-preview`.
+
+### Conversational search
+
+The shopper asks in their own words, in a dialog, and Luigi's Box's shopping
+assistant answers: streamed text, the products it picked, follow-up
+suggestions, questions with choices, comparisons. Only an integration with a
+`convo/` folder has it, and a page loads its code only when the shopper goes
+near one of its triggers (about 11 kB gzip, once).
+
+A click on any element with `data-lbx-convo` opens the dialog: the site's
+own button, or one in a template. Its value, when not empty, is a question:
+from the autocomplete's templates (passing the phrase typed,
+`data-lbx-convo=${s.query}`) it is asked at once; from anything else (the
+site's markup, a listing's or recommender's tile) it is put in the dialog's
+input for the shopper to send (text on a page never speaks in the
+shopper's name).
+
+```html
+<button type="button" data-lbx-convo>Ask our shopping assistant</button>
+```
+
+Or Luma's own sparkle in the site's search field: `trigger: { anchor,
+position, label }` places a 32 px round button (`[data-lbx="convo-trigger"]`,
+`position` as a listing's anchor, default `append`; named "Ask the shopping
+assistant" in English, Czech or German by `_global.locale`, or `label`)
+that opens the dialog with the phrase typed in the site's search input
+(`_global.inputSelector`). In flow by default; the folder's
+`style-host.css` (applied on every page with the folder, before the button
+is placed) lays it over the field and keeps the field's text clear of it.
+It is in the build only where `convo/_config.ts` names `trigger` (about
+0.8 kB gzip on every page, loaded after the page's own scripts).
+
+```css
+/* integration/convo/style-host.css */
+.search-form { position: relative; }
+.search-form > [data-lbx="convo-trigger"] { position: absolute; top: 6px; right: 6px; color: #7b2cbf; background: #f3eafb; border-color: #b48ad9; border-radius: 50%; }
+.search-form:has(> [data-lbx="convo-trigger"]) input[name="q"] { padding-right: 44px; }
+```
+
+```ts
+// integration/convo/_config.ts
+export default {
+  trackerId: '1234-5678',            // the site in Luigi's Box's conversation service
+  surface: 'lbs_collection_main',    // the collection surface its products are looked up on
+  idField: 'id',                     // the catalog field holding the identity the assistant names a product by
+  fields: ['@title', 'web_url', 'lbx:image', 'lbx:price'],
+  locale: 'de',                      // the language it answers in (default: _global.locale)
+  trigger: { anchor: 'header form.search' },  // optional: Luma's sparkle in the site's search field
+  assist: true,                      // optional: its answer in the autocomplete and on the search page
+};
+```
+
+- **The conversation** is Luigi's Box's conversation service
+  (`conversational-proxy.luigisbox.com`, `endpoint` to change it), keyed by
+  `trackerId`. A site with a strict Content Security Policy allows that host
+  in `connect-src`. The assistant answers in `en`, `sk`, `cs`, `pl`, `de` or
+  `hu`: set `locale` to the shop's language when the interface's differs.
+- **Its products** are the catalog's: the identities the assistant names are
+  looked up on `surface` by `idField`, and drawn with the
+  `convo-result-default` template (the integration's, like every other tile:
+  `r.c.*`, `img`, `price`). A product the channel does not serve gets no
+  tile.
+- **It lasts the tab's session**: a product opened from the dialog and Back,
+  or a trigger on the next page, shows the same conversation, for about an
+  hour. "Start over" begins a new one.
+- **Where the site's assistant is off** (over its monthly budget, no
+  catalog), the dialog says so, and the triggers are hidden on the session's
+  later pages.
+- **Its look**: a panel from the right over the dimmed page (the whole
+  screen on a phone), in a shadow root (the site's CSS does not reach in).
+  `style-convo.css` in `convo/` styles it, starting with its tokens: the
+  site's brand colour is enough, the tints of the shopper's bubbles, chips
+  and the assistant's mark come from it, and Luma darkens the text drawn in
+  it until it reads (4.5:1) and picks white or black for what stands
+  on it: `:host { --lbx-cv-accent: #8740bf;
+  --lbx-cv-font: 'Inter', sans-serif; }` (`--lbx-cv-fg`, `-bg`,
+  `-muted`, `-line`, `-field`, `-soft`, `-width`). The `convo-box` template draws the whole dialog
+  (`ConvoScope`). Its words come in English, Czech and German with its code;
+  `_translations.ts` overrides them under `convo` (`{ sk: { convo: { title:
+  'Nákupný asistent' } } }`).
+- **The assistant's answer where the shopper searches** (`assist: true`,
+  for a site Luigi's Box has set up for it; elsewhere nothing is shown and
+  Luma stops asking for the session): Luigi's Box decides per phrase whether
+  the assistant serves it better than the results, and answers it when so.
+  The autocomplete asks about a phrase of 3 or more words once the shopper
+  pauses (600 ms), and shows a row on top with the answer's first words
+  (`autocomplete-assist`; in the site's own `autocomplete-box`,
+  `s.assist`: a button with `data-lbx-convo=${s.assist.query}` and
+  `data-lbx-assist`). The search page asks about its query (3 or more
+  words, for a search made on the site: a search page reached from another
+  site shows only an answer the tab already has, never asks in the
+  shopper's name) and shows a box above the listing with the answer, three
+  of its products, its suggestions and "Continue with the assistant"
+  (`convo-preview`, `ConvoPreviewScope`). An answer that ends in an error
+  shows nothing.
+  Either opens the panel with that answer as the conversation's first turn:
+  one answer per phrase, kept for the tab's session, so a phrase answered in
+  the autocomplete and then searched is not asked again (one still streaming
+  is asked again with its own conversation, which Luigi's Box replays). Its
+  code is a chunk of its own (about 2.7 kB gzip), loaded when a phrase
+  settles or on a search page; the panel's only once there is an answer. The search box is placed
+  before Luma's listing (`lbx-search`): CSS of the integration's that hides
+  the rest of the listing's container lets `lbx-convo-preview` through.
+- **Not yet**: adding products to a comparison from their tiles (the
+  assistant's comparisons are shown), feedback on an answer.
 
 ### Templates
 
@@ -474,7 +582,7 @@ built as on.
 | `search.prefetchWhileTyping` | the search result is fetched once the typed phrase settles, so Enter shows it at once | |
 | `search.pageWhileTyping` (`'prefetch'`, `'prerender'`, `false`) | the search page of the typed phrase is fetched ahead (Chrome, Edge; Firefox and Safari as they ship it), so Enter from another page skips the site's server render; `'prerender'` renders it ahead as well (Chrome, Edge) | the site cannot take a document request per typed phrase; `'prerender'` only where its tags wait for `prerenderingchange` |
 | `search.queryUrl` (an `_init.ts` hook, off unless set) | where the site's server redirects its search form to the query's page (`/search?q=x` to `/search/x/`), names that page: Enter, the autocomplete's "show all" and a picked query load it directly, without the redirect, and the result fetched while typing is shown there | the form's other fields decide the page, or the site must handle every search itself |
-| `restoreOnBack` | Back from a product restores the listing (every page shown) and the followed tile's position, as does the page loaded again within a minute of following a link (a reload, a link whose server redirects back to it); Luma turns the browser's own scroll restoration (`history.scrollRestoration`) off for the listing's history entry until it has placed the page, unless the site set it | |
+| `restoreOnBack` | Back from a product restores the listing (every page shown) and the followed tile's position, as does the page loaded again within a minute of following a link (a reload, a link whose server redirects back to it); Luma turns the browser's own scroll restoration (`history.scrollRestoration`) off for the listing's history entry until it has placed the page (not while the page is in the browser's back/forward cache, which restores it from memory), unless the site set it | |
 | `prefetchNextPage` | "show more" is fetched as the shopper nears the end | |
 | `contentVisibility` (opt-in) | tiles out of view skip style, layout and paint, each at its own measured size: a long list's re-render about halves | keep it off where a tile draws outside its box (a hover panel, a badge hanging out) or holds a `position: fixed` element |
 | `variants: { fields }` (opt-in) | each tile's result gets its variant group (`r.variants`, "Templates" above): one request to Luigi's Box per page of results, never waited for | the surface does not collapse variants (every group is a group of one) |
@@ -648,6 +756,9 @@ integration repository").
   while typing a document per settled phrase (`search.pageWhileTyping: false`).
 - **Early hold**: the snippet carries no site's rules, so the first page
   view is not held.
+- **Conversational search** runs on Luigi's Box's conversation service, keyed
+  by the site's tracker id, until Luigi's Box AI serves conversations; its
+  products are already the Luigi's Box AI catalog's.
 - **Host routers out of reach**: where Luma cannot find the host's router (Vue
   Router 4 when its app is not discoverable, Angular in production), the
   router can overwrite Luma's history entry or show a stale query in its search

package/build/vite.mjs

@@ -22,7 +22,7 @@ const FRAMEWORK = resolve(dirname(fileURLToPath(import.meta.url)), '../src');
 //                     (soleUser: the listing's contrast toggle, fold, …)
 //   lbx-listing       search results and category pages (one listing: plp is
 //                     a route of it) with the integration's search/ templates
-//   lbx-autocomplete  lbx-recommender   each widget with its templates
+//   lbx-autocomplete  lbx-recommender  lbx-convo   each widget with its templates
 //   lbx-plp  lbx-place  lbx-search  lbx-search-in-place  lbx-speculate  lbx-token
 //                     the plp widget and its templates, placement and
 //                     recommender triggers, the search page's own, a new query
@@ -46,7 +46,7 @@ const FRAMEWORK = resolve(dirname(fileURLToPath(import.meta.url)), '../src');
 // 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 KIND_CHUNK = { autocomplete: 'lbx-autocomplete', search: 'lbx-listing', plp: 'lbx-plp', recommender: 'lbx-recommender', convo: 'lbx-convo' };
 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\//;
@@ -86,9 +86,10 @@ export const chunkOf = (id) => {
   // Hydration of server-rendered listings: only those pages load it.
   // lit-html's private SSR support is the hydrator's alone (not every widget page's lbx-core).
   if (/\/node_modules\/(@lit-labs\/ssr-client\/|lit-html\/private-ssr-support\.js)/.test(id)) return 'lbx-hydrate';
-  // 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';
+  // Placing our elements (core/reconciler.ts), the recommenders' triggers and the
+  // conversation's sparkle (widgets/convo/trigger.ts): pages with a listing, a
+  // recommender or the sparkle, in parallel with their other chunks.
+  if (/\/src\/(core\/(reconciler|recommenders)|widgets\/convo\/trigger)\.ts$/.test(id)) return 'lbx-place';
   // The listing's high-contrast toggle: only a site that turns it on loads it (widgets/listing/element.ts).
   if (/\/src\/core\/contrast-toggle\.ts$/.test(id)) return 'lbx-contrast';
   // An Apply's cue in a staged drawer: asked for when such a drawer opens (widgets/listing/element.ts).
@@ -132,9 +133,14 @@ const soleUser = (id, getModuleInfo, entry, seen = new Set([id])) => {
   }
   return users;
 };
+// The assistant's answer to what is typed (widgets/convo/assist.ts) and the wire it shares with the
+// panel (protocol.ts): their own chunk where the build has it (the autocomplete and the search page
+// load it without the panel), else in the panel's.
+const ASSIST = /\/src\/widgets\/convo\/(assist|protocol)\.ts$/;
 const manualChunks = (id, { getModuleInfo, getModuleIds }) => {
   const entry = entryGraph(getModuleInfo, getModuleIds);
   if (entry.has(id)) return 'integration';
+  if (ASSIST.test(id)) return [...getModuleIds()].some((m) => /\/src\/widgets\/convo\/assist\.ts$/.test(m) && getModuleInfo(m)?.isIncluded) ? 'lbx-assist' : 'lbx-convo';
   const c = chunkOf(id);
   if (c !== 'lbx-core') return c;
   const users = soleUser(id, getModuleInfo, entry);
@@ -224,7 +230,9 @@ const rawCss = () => ({
  * `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'] };
+/** Built-in templates a feature of the integration renders (core/features.ts): left out of a build without it. */
+export const FEATURE_TEMPLATES = { autocomplete: { 'autocomplete-assist': '__LBX_CONVO_ASSIST__' }, convo: { 'convo-preview': '__LBX_CONVO_ASSIST__' } };
+export const ENTRY_TEMPLATES = { autocomplete: ['autocomplete-box'], search: ['search-box'], recommender: ['recommender-box-default', 'recommender-popup'], convo: ['convo-box', 'convo-preview'] };
 const includes = (src) => {
   const calls = [...src.matchAll(/\binclude\(\s*(?:(['"])([\w-]+)\1)?/g)];
   return calls.some((m) => !m[2]) ? null : calls.map((m) => m[2]);
@@ -240,6 +248,7 @@ export const unrenderedBuiltIns = (integration, builtIns) => {
       ...(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'] })),
+    convo: folders.includes('convo') ? [{ folders: ['_global', 'convo'], kinds: ['convo'] }] : [],
   };
   const out = {};
   for (const [widget, instances] of Object.entries(users)) {
@@ -285,7 +294,7 @@ const templateSources = (dir) => {
     }
   return out;
 };
-const BUILT_INS = /\/src\/widgets\/(autocomplete|search|recommender)\/(?:index|assets)\.ts$/;
+const BUILT_INS = /\/src\/widgets\/(autocomplete|search|recommender|convo)\/(?:index|assets)\.ts$/;
 
 /**
  * A built-in template's own rules in its widget's stylesheet, marked
@@ -319,6 +328,10 @@ const unusedBuiltIns = (root) => {
       const itg = templateSources(resolve(root, 'integration'));
       const builtIns = templateSources(resolve(FRAMEWORK, 'widgets'));
       drop = unrenderedBuiltIns(itg, builtIns);
+      // Those of a feature the integration does not name (an assistant's nudge without `assist`).
+      const defines = featureDefines(resolve(root, 'integration'));
+      for (const [widget, names] of Object.entries(FEATURE_TEMPLATES))
+        if (drop[widget]) for (const [name, flag] of Object.entries(names)) if (defines[flag] === 'false' && !drop[widget].includes(name)) drop[widget].push(name);
       // The left-out templates' stylesheet parts no template of the widget's folders still uses.
       cssDrop = {};
       for (const [widget, names] of Object.entries(drop)) {
@@ -551,12 +564,18 @@ export const featureDefines = (integrationDir) => {
     readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
       e.name.startsWith('.') || e.name === 'node_modules' || e.name === 'dist' ? [] : e.isDirectory() ? read(resolve(dir, e.name)) : /\.(ts|tsx|js|jsx|mts|mjs|cts|cjs|html)$/.test(e.name) ? [readFileSync(resolve(dir, e.name), 'utf8')] : [],
     );
+  // A key in a folder's _config.ts (a word alone is common: a catalog field, a comment).
+  const configText = (f) => (existsSync(resolve(integrationDir, f, '_config.ts')) ? readFileSync(resolve(integrationDir, f, '_config.ts'), 'utf8') : '');
   const inFiles = (...needles) => ((text ??= read(dirname(integrationDir)).join('\n')), needles.some((n) => text.includes(n)));
   return {
     __LBX_AUTOCOMPLETE__: has((d) => d.includes('autocomplete')),
     __LBX_SEARCH__: has((d) => d.includes('search')),
     __LBX_PLP__: has((d) => d.includes('plp')),
     __LBX_RECOMMENDER__: has((d) => d.some((f) => f.split(/\s+/)[0] === 'recommender')),
+    __LBX_CONVO__: has((d) => d.includes('convo')),
+    // Its sparkle in the site's search field: the key in convo/_config.ts (the word alone is common).
+    __LBX_CONVO_TRIGGER__: has((d) => d.includes('convo') && /\btrigger\b["']?\s*:/.test(configText('convo'))),
+    __LBX_CONVO_ASSIST__: has((d) => d.includes('convo') && /\bassist\b["']?\s*:/.test(configText('convo'))),
     __LBX_ANALYTICS__: has((d) => d.some((f) => existsSync(resolve(integrationDir, f, '_analytics.ts')))),
     __LBX_WIDGET_INITS__: has((d) => d.some((f) => existsSync(resolve(integrationDir, f, '_widget.ts')))),
     __LBX_HOST_STYLES__: has((d) => d.some((f) => existsSync(resolve(integrationDir, f, 'style-host.css')))),
@@ -579,13 +598,13 @@ export const featureDefines = (integrationDir) => {
     __LBX_PRERENDER_TYPING__: has(() => inFiles('prerenderWhileTyping', 'pageWhileTyping')),
     __LBX_CONTENT_VISIBILITY__: has(() => inFiles('contentVisibility')),
     // A listing's variant groups: the key in a folder's _config.ts (the word alone is common: a catalog field, a comment).
-    __LBX_VARIANTS__: has((d) => d.some((f) => /\bvariants\b["']?\s*[:,}]/.test(existsSync(resolve(integrationDir, f, '_config.ts')) ? readFileSync(resolve(integrationDir, f, '_config.ts'), 'utf8') : ''))),
+    __LBX_VARIANTS__: has((d) => d.some((f) => /\bvariants\b["']?\s*[:,}]/.test(configText(f)))),
     // Options on by default: one no file names is on.
     ...Object.fromEntries(ON_BY_DEFAULT.map((k) => [`__LBX_NAMED_${k.replace(/[A-Z]/g, (c) => `_${c}`).toUpperCase()}__`, has(() => inFiles(k))])),
   };
 };
 /** Luma's dictionaries' namespaces (src/locales/*.json) a build without the widget leaves out: plp reads search's too. */
-export const LOCALE_NAMESPACES = { autocomplete: ['AUTOCOMPLETE'], search: ['SEARCH', 'PLP'], plp: ['PLP'], recommender: ['RECOMMENDER'] };
+export const LOCALE_NAMESPACES = { autocomplete: ['AUTOCOMPLETE'], search: ['SEARCH', 'PLP'], plp: ['PLP'], recommender: ['RECOMMENDER'], assist: ['CONVO_ASSIST'] };
 export const pruneDictionary = (json, defines) => {
   const dict = JSON.parse(json);
   for (const [ns, flags] of Object.entries(LOCALE_NAMESPACES)) if (flags.every((f) => defines[`__LBX_${f}__`] === 'false')) delete dict[ns];

package/docs/ACCESSIBILITY.md

@@ -120,7 +120,8 @@ guessed alt text, and forced colours and the OS setting are honoured.
 - **Keys** as before: arrows move the selection, Enter picks it (or is the
   host's search), Escape closes ours first, as whole gestures. Focus never
   leaves the input on a click or a tap (`pointerdown` on the dropdown is
-  prevented); only Tab moves it, to "Show all products".
+  prevented); only Tab moves it, to "Show all products" (or first to the
+  assistant's row, when there is one: below).
 - **Colours**: the host's text and accent colours are sampled only where they
   read at 4.5:1 on our white panel (`readable`, `core/a11y.ts`; a dark site's
   light text or a pale brand colour falls back); text on an accent fill is
@@ -251,6 +252,60 @@ guessed alt text, and forced colours and the OS setting are honoured.
   appears after the shopper's own add-to-cart click; moving focus there would
   pull them away from the host's notice).
 
+### The conversational search (`widgets/convo/`)
+
+- A modal `<dialog>` (`showModal()`, a panel from the right) named by its
+  title ("Shopping assistant", `convo.title`): the page behind is inert, so
+  Tab and the screen reader's cursor stay in it; Escape, the 40 px close
+  button named "Close" and a press on the backdrop close it, and focus goes
+  back to the trigger. Focus starts in its input (named "Ask anything…").
+  Its icon buttons (Start over, Close, Send / Stop) are named and titled;
+  the log is a region named "Conversation"; Enter in the input while an
+  answer streams does nothing (only the Stop button stops it).
+- The answer streams in word by word: the log is not a live region (it
+  would be read in pieces) but `aria-busy` while it streams. "Thinking" is
+  said as the turn starts, the answer once, politely, when it is done: its
+  words without the Markdown's marks, up to the sentence ending past 500
+  characters (an error after it). Each question and answer starts with a
+  visually hidden "You:" / "Assistant:"; a question the assistant ignored
+  says "not answered", and that is said too.
+- Focus never falls to the page: Send and Stop are one button, and a
+  control that goes away with a render (a suggestion used, a retry, the
+  input disabled when the conversation ends) gives focus to the log.
+  The fields' edges are 3:1, their placeholder (their visible label) 4.5:1.
+- Luma's sparkle in the site's search field (`trigger`) is a 32 px button
+  named "Ask the shopping assistant" in the site's language (`label`), with
+  a focus ring of its own that a site's outline reset cannot remove (3 px
+  Highlight in forced colours).
+- The assistant's answer in the autocomplete (`assist`) is a button above
+  the dropdown's results, named by its title ("The assistant has an
+  answer"), its first words (up to 160 characters, not the whole answer)
+  and "Continue"; Tab from the search input reaches it first, then "Show
+  all products" (Shift+Tab back), and its title is said once, politely,
+  when it appears, with the result count if that is still to be said. The
+  arrow keys' last stop is still "Show all products". Its words are in the
+  text colour (the muted grey and the accent can fall under 4.5:1 on the
+  accent's tint). Closing the dialog opened from it (its dropdown gone)
+  gives focus to the site's search field. Its one-time shimmer and slide-in run only without reduced
+  motion; until the answer's first words come, three dots (hidden from
+  assistive technology) bounce, or only fade in turn under reduced motion,
+  and keep the text colour in forced colours.
+- The search page's answer box is a section named by its heading
+  ("Shopping assistant"), `aria-busy` while the answer streams (not a live
+  region: the results are the page's main content); its suggestions and
+  "Continue with the assistant" are buttons that open the dialog, focus
+  going back to the one pressed when it closes. An answer that breaks off
+  removes the box; focus in it goes on to the listing after it. Its accent is made readable
+  as the dialog's (white or black on it, whichever reads better: at least
+  4.58:1 on any accent).
+- Every control is a named button of at least 24 px (suggestions, choices,
+  a product's "Tell me more: <product>", each refinement's remove control
+  named by the assistant, Try again, Stop, Start over). A comparison table
+  scrolls in its own focusable region with row and column headers.
+- On a phone (or a short touch screen: a phone in landscape) the dialog is the whole screen. Forced colours keep the
+  dialog's, the bubbles' and the controls' edges; under reduced motion the
+  "thinking" dots stand still.
+
 ### Every widget
 
 - **Focus ring**: `:focus-visible` gets an outline in our subtrees (`@layer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luigisbox/luma",
-  "version": "0.7.0",
+  "version": "0.8.0-beta.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",

package/src/core/a11y.ts

@@ -12,7 +12,9 @@ export const SR_ONLY =
 /**
  * A polite status region (WCAG 4.1.3). `say(text)` announces it once the
  * caller has been quiet for `delay` ms (a burst of renders is one message);
- * the same text twice is announced twice (it is cleared first).
+ * the same text twice is announced twice (it is cleared first). `keep`: a
+ * message a later one does not replace but is said with (two pieces of news
+ * that come together: the autocomplete's results and the assistant's answer).
  */
 export const liveRegion = () => {
   const el = document.createElement('div');
@@ -21,17 +23,22 @@ export const liveRegion = () => {
   el.setAttribute('aria-atomic', 'true');
   el.style.cssText = SR_ONLY;
   let timer = 0;
+  let plain = '';
+  let kept = '';
   return {
     el,
-    say(text: string, delay = 150) {
+    say(text: string, delay = 150, keep = false) {
+      if (keep) kept = text;
+      else plain = text;
+      const out = plain && kept ? `${plain.replace(/[.\s]+$/, '')}. ${kept}` : plain || kept;
       clearTimeout(timer);
       el.textContent = '';
       // In a later task: a region whose text is replaced in the same task as it appears is not announced.
-      timer = window.setTimeout(() => void (el.textContent = text), delay);
+      timer = window.setTimeout(() => void ((el.textContent = out), (plain = kept = '')), delay);
     },
     clear() {
       clearTimeout(timer);
-      el.textContent = '';
+      plain = kept = el.textContent = '';
     },
   };
 };

package/src/core/context.ts

@@ -6,7 +6,7 @@
 import type { Templates } from './templates';
 import type { LumaConfigType } from '../types';
 import type { WidgetContext } from '../main';
-import { QUERY_URL } from './features';
+import { CONVO_ASSIST, QUERY_URL } from './features';
 import { nameOf, slot } from './integration';
 
 type Support = typeof import('./support');
@@ -106,5 +106,6 @@ export const widgetContext = (
     // Images: a listing's first row is eager; elsewhere (recommenders, the autocomplete) every image is lazy.
     helpers: { t, price, plain: s.plain, first: s.first, ...s.imageHelpers(g.images, w.id !== 'search' && w.id !== 'plp') },
     queryUrl: QUERY_URL ? config.search?.queryUrl : undefined,
+    assist: CONVO_ASSIST && config.convo?.assist && !config.convo.disabled ? config.convo : undefined,
   };
 };

package/src/core/features.ts

@@ -1,5 +1,5 @@
 // The widgets an integration has (build/vite.mjs `features`): a widget is its
-// folder (integration/autocomplete/, search/, plp/, recommender <name>/; an
+// folder (integration/autocomplete/, search/, plp/, recommender <name>/, convo/; an
 // _analytics.ts or _widget.ts in any folder); a feature only the
 // integration's own files can ask for (a template's attribute, a hook its
 // _init.ts sets) by that text in them. The build defines these from the folders, so
@@ -11,6 +11,9 @@ declare const __LBX_AUTOCOMPLETE__: boolean | undefined;
 declare const __LBX_SEARCH__: boolean | undefined;
 declare const __LBX_PLP__: boolean | undefined;
 declare const __LBX_RECOMMENDER__: boolean | undefined;
+declare const __LBX_CONVO__: boolean | undefined;
+declare const __LBX_CONVO_TRIGGER__: boolean | undefined;
+declare const __LBX_CONVO_ASSIST__: boolean | undefined;
 declare const __LBX_ANALYTICS__: boolean | undefined;
 declare const __LBX_SSR__: boolean | undefined;
 declare const __LBX_WIDGET_INITS__: boolean | undefined;
@@ -50,6 +53,12 @@ export const SEARCH = typeof __LBX_SEARCH__ === 'boolean' ? __LBX_SEARCH__ : tru
 export const PLP = typeof __LBX_PLP__ === 'boolean' ? __LBX_PLP__ : true;
 /** An integration/recommender <name>/. */
 export const RECOMMENDER = typeof __LBX_RECOMMENDER__ === 'boolean' ? __LBX_RECOMMENDER__ : true;
+/** integration/convo/: the conversational search (widgets/convo). */
+export const CONVO = typeof __LBX_CONVO__ === 'boolean' ? __LBX_CONVO__ : true;
+/** The conversational search's sparkle in the site's search field: `trigger` in convo/_config.ts (main.ts). */
+export const CONVO_TRIGGER = typeof __LBX_CONVO_TRIGGER__ === 'boolean' ? __LBX_CONVO_TRIGGER__ : true;
+/** The assistant asked about what is typed (/assist, lean trackers): `assist` in convo/_config.ts (widgets/convo/assist.ts). */
+export const CONVO_ASSIST = typeof __LBX_CONVO_ASSIST__ === 'boolean' ? __LBX_CONVO_ASSIST__ : true;
 /** An _analytics.ts in any folder (without one, analytics is off: main.ts). */
 export const ANALYTICS = typeof __LBX_ANALYTICS__ === 'boolean' ? __LBX_ANALYTICS__ : true;
 /** A _widget.ts in any folder (without one, core/widget-inits.ts has nothing to run). */

package/src/core/image-load.ts

@@ -2,7 +2,8 @@
 // - load marks: `data-lbx-loaded` on an `img[data-lbx-img]` and its
 //   `[data-lbx-ph]` box once it has loaded (or failed: the alt text shows), so
 //   the placeholder goes and a lazy image fades in (style-search.css). One
-//   capture listener on the document for every widget; an image already
+//   capture listener on the document for every widget (and on a widget's
+//   shadow root: the conversation's dialog); an image already
 //   complete when a render puts it in (the memory cache, a persisted tile, a
 //   server-rendered one loaded before hydration) is marked in that task:
 //   no placeholder flash, no fade;
@@ -12,6 +13,7 @@
 //   filter), at low priority, behind a cap.
 // Browser only, in the widgets' chunks: never in the entry or the server renderer.
 
+import { CONVO } from './features';
 import type { ImageInfo } from './images';
 
 const SEL = 'img[data-lbx-img]:not([data-lbx-loaded])';
@@ -24,18 +26,18 @@ const loaded = (img: Element, how: '' | 'fade') => {
   img.closest('[data-lbx-ph]')?.setAttribute('data-lbx-loaded', how);
 };
 
-let watching = false;
-const watch = () => {
-  if (watching) return;
-  watching = true;
-  const on = (e: Event) => {
-    const t = e.target as Element;
-    if (t?.nodeType !== 1 || t.localName !== 'img' || !t.hasAttribute('data-lbx-img') || t.hasAttribute('data-lbx-loaded')) return;
-    loaded(t, performance.now() - renderedAt < CACHED_MS ? '' : 'fade');
-  };
-  // load and error do not bubble: capture sees every image of the document.
-  document.addEventListener('load', on, true);
-  document.addEventListener('error', on, true);
+const on = (e: Event) => {
+  const t = e.target as Element;
+  if (t?.nodeType !== 1 || t.localName !== 'img' || !t.hasAttribute('data-lbx-img') || t.hasAttribute('data-lbx-loaded')) return;
+  loaded(t, performance.now() - renderedAt < CACHED_MS ? '' : 'fade');
+};
+const watching = new WeakSet<Node>();
+/** load and error do not bubble: capture sees every image of the document, or of a shadow root (theirs never leave it). */
+const watch = (root: Node) => {
+  if (watching.has(root)) return;
+  watching.add(root);
+  root.addEventListener('load', on, true);
+  root.addEventListener('error', on, true);
 };
 
 /**
@@ -44,7 +46,12 @@ const watch = () => {
  * when `fade` is on. Server-rendered markup without JavaScript has no fade.
  */
 export const settleImages = (root: Element, fade = true) => {
-  watch();
+  watch(document);
+  // Only the conversation's dialog renders images in a shadow root (core/features.ts).
+  if (CONVO) {
+    const sr = root.getRootNode();
+    if (sr instanceof ShadowRoot) watch(sr);
+  }
   renderedAt = performance.now();
   for (const img of root.querySelectorAll<HTMLImageElement>(SEL)) if (img.complete && img.getAttribute('src')) loaded(img, '');
   if (fade && !root.hasAttribute('data-lbx-fade')) root.setAttribute('data-lbx-fade', '');

package/src/core/integration.ts

@@ -5,13 +5,13 @@
 // templates, translations and helpers the bundle would.
 
 import type { LumaApi, LumaConfigType, LumaInitType } from '../types';
-import { AUTOCOMPLETE, HOST_STYLES, INITS, PLP, RECOMMENDER, SEARCH, TRANSLATIONS, VARIANTS } from './features';
+import { AUTOCOMPLETE, CONVO, HOST_STYLES, INITS, PLP, RECOMMENDER, SEARCH, TRANSLATIONS, VARIANTS } from './features';
 
 export type Lazy<T> = Record<string, () => Promise<T>>;
 
 export const folderOf = (path: string) => path.split('/').slice(-2)[0];
 export const nameOf = (path: string) => path.split('/').pop()!.replace(/^(template|style)-/, '').replace(/\.\w+$/, '');
-const KINDS = ['autocomplete', 'search', 'plp', 'recommender'];
+const KINDS = ['autocomplete', 'search', 'plp', 'recommender', 'convo'];
 
 /**
  * Each listing's folders (template and style precedence) and translation
@@ -104,7 +104,7 @@ export const loadConfig = async (files: Pick<IntegrationFiles, 'configs' | 'init
   const Luma: LumaApi = { version, config };
   if (globalInit && (await globalInit(config, Luma)) === false) return null;
   if (config._global.disabled || !config._global.publishableKey || !config._global.channelId) return null;
-  const apps = [AUTOCOMPLETE ? config.autocomplete : null, SEARCH ? config.search : null, PLP ? config.plp : null, ...(RECOMMENDER ? Object.values(config.recommenders ?? {}) : [])];
+  const apps = [AUTOCOMPLETE ? config.autocomplete : null, SEARCH ? config.search : null, PLP ? config.plp : null, CONVO ? config.convo : null, ...(RECOMMENDER ? Object.values(config.recommenders ?? {}) : [])];
   if (INITS) for (const app of apps) if (app && !app.disabled && app.initialize && (await (app.initialize as any)(app, Luma)) === false) app.disabled = true;
   // `variants` comes into a build from a folder's _config.ts only (build/vite.mjs
   // featureDefines): set by an _init.ts, a build would leave it out unsaid.

package/src/core/own.ts

@@ -5,6 +5,15 @@ import { DOCUMENT_REACT } from './frameworks';
 
 export const OWN_ATTR = 'data-lbx';
 
+/**
+ * Elements Luma created, by identity (an attribute, `data-lbx`, can be put on
+ * the page by anyone who can put markup there: a review keeping data-*):
+ * what is inside one of them is ours (a template's), what is not is the
+ * site's. Read by the conversational search: a question asked at once only
+ * from a trigger of ours (widgets/convo).
+ */
+export const created = new WeakSet<Element>();
+
 /**
  * Whether a node of ours the host removes is put back before the next paint
  * (core/sense.ts, scheduleNow): from when we have something to put back, a

package/src/locales/cs.json

@@ -90,5 +90,9 @@
     "close": "Zavřít",
     "title": "Doporučujeme"
   },
-  "contrast": "Režim vysokého kontrastu"
+  "contrast": "Režim vysokého kontrastu",
+  "assist": {
+    "title": "Asistent má odpověď",
+    "continue": "Pokračovat"
+  }
 }

package/src/locales/de.json

@@ -84,5 +84,9 @@
     "close": "Schließen",
     "title": "Empfehlungen für Sie"
   },
-  "contrast": "Hoher Kontrast"
+  "contrast": "Hoher Kontrast",
+  "assist": {
+    "title": "Der Assistent hat eine Antwort",
+    "continue": "Weiter"
+  }
 }

package/src/locales/en.json

@@ -84,5 +84,9 @@
     "close": "Close",
     "title": "Recommended for you"
   },
-  "contrast": "High-contrast mode"
+  "contrast": "High-contrast mode",
+  "assist": {
+    "title": "The assistant has an answer",
+    "continue": "Continue"
+  }
 }