@algolia/wizard 0.42.0 → 0.43.0-rc.141.299

package/dist/main.js

@@ -3472,7 +3472,7 @@ async function runAnalysis(mode, extraInstructions = []) {
 // package.json
 var package_default = {
   name: "@algolia/wizard",
-  version: "0.42.0",
+  version: "0.43.0-rc.141.299",
   description: "Magically implement Algolia functionality in your codebase",
   type: "module",
   engines: {
@@ -4132,6 +4132,7 @@ function searchInstructions(input) {
   return [
     "Implement an in-app Algolia search experience.",
     `Build the search UI for ${input.searchUiTarget}.`,
+    "This step is search UI only \u2014 the index is already populated. Do not create or modify ingestion scripts, rake/manage/CLI tasks, migrations, seeders, or any other data-loading code, even if you notice the data looks incomplete.",
     ...doc ? [
       "Follow the Algolia SDK reference below for client setup, search UI wiring, and Insights instrumentation \u2014 Insights is required, not optional; prefer the reference over prior knowledge:",
       doc
@@ -4139,9 +4140,15 @@ function searchInstructions(input) {
       "No bundled Algolia SDK reference exists for this stack, so rely on the project's own conventions and Algolia's official client for its language. Do not invent APIs \u2014 keep to the documented search endpoint and its parameters."
     ],
     `Create the search experience as its own component in a new file, following the project's existing component conventions (location, naming, styling approach). Do not write it inline into an existing file.`,
-    `Import and render that new component from ${input.searchLocation ? `"${input.searchLocation}"` : "the best shared, always-rendered layout location (e.g. a header/nav component)"} so it is reachable across the app \u2014 at least a working search input and results list against the target index.`,
+    `Import and render that new component from ${input.searchLocation ? `"${input.searchLocation}"` : "the best shared, always-rendered layout location (e.g. a header/nav component)"} so it is reachable across the app \u2014 at least a working search input and results panel against the target index.`,
     "If a search box already exists, replace its usage with an import and render of your new component; remove the old implementation.",
     "When rendering results with an existing shared component (e.g. a card), import and reuse that component rather than inlining its markup \u2014 inlining silently drops the styles and behavior its own file provides.",
+    "Results appear as a dropdown panel, not a permanently visible list. If the SDK reference above documents an Autocomplete widget for this stack, it already owns that behavior \u2014 when the panel opens and closes, Escape, blur, outside click, arrow-key navigation, combobox ARIA, Insights events \u2014 so use it as-is and add no open/close logic, query gating, or ARIA roles of your own, even if it opens on focus before anything is typed. Only build this by hand when the reference has no such widget for this stack, or says it is headless; then show the panel only while the input is focused and has a non-empty query, close it on Escape, on blur, and on an outside click, and move an active-result highlight with Up/Down arrows with Enter to select.",
+    "Let the widget own result selection: where the hits have a detail page, pass its per-index URL option (getURL or the flavor's equivalent) so it navigates on click and on Enter with a result highlighted, and keep your item template or item component to content only \u2014 no anchor, no href, no click handler of your own, no stopPropagation. The widget's own result element is what sends the Insights click event, closes the panel, and clears the active option; wrapping a result in your own link swallows all three while still navigating, so it looks correct and silently loses click analytics.",
+    "Render the zero-results state through the widget's own no-results template or component, so a query that matches nothing shows a message rather than an empty panel.",
+    "Meet WCAG AA contrast (4.5:1 body text, 3:1 large text/icons) between the panel's text and its own background, and give both the input and the active result a focus indicator that is visible against whatever sits behind it. Style the panel through the widget's own class and CSS-variable overrides (or, if building by hand, the app's existing theme tokens) \u2014 never assume a light surface or reuse the surrounding page's colors unchanged inside the panel.",
+    "A vendor theme stylesheet, and any CSS you write against vendor class names, must be global: import the theme from the component's own script module or the app's global stylesheet, and put the overrides in a global block (Astro's <style is:global>, an unscoped Vue block, a plain global CSS file). Never route either through a framework-scoped style block or a CSS Module \u2014 scoping rewrites the vendor selectors, and the widget builds its DOM at runtime with no scope attribute on it, so not one rule matches: the styling silently does nothing and the build still passes.",
+    "The panel takes its width from the input by default, so a small input makes it unreadably narrow: give it a minimum width of 320px independent of the input, and keep it anchored to the input edge it opens from so widening it does not push it off-screen.",
     `Define ${SEARCH_CONFIG_APP_ID}, ${SEARCH_CONFIG_SEARCH_KEY}, and ${SEARCH_CONFIG_INDEX_NAME} as exported constants in a module that fits this project's existing conventions for shared client-side config \u2014 reuse an existing one if it already holds config like this, or add a small new one otherwise. These are PUBLIC values, safe to commit and expose client-side: never read them from an environment variable or a .env* file, and never hardcode them anywhere except in that one module (import them wherever the search client needs them).`,
     `Set ${SEARCH_CONFIG_APP_ID} to "${input.appId}" and ${SEARCH_CONFIG_INDEX_NAME} to "${input.targetIndex}".`,
     input.searchKey ? `Set ${SEARCH_CONFIG_SEARCH_KEY} to "${input.searchKey}".` : `A real search-only key could not be provisioned${input.searchKeyError ? ` (${input.searchKeyError})` : ""} \u2014 set ${SEARCH_CONFIG_SEARCH_KEY} to the placeholder "${SEARCH_KEY_PLACEHOLDER}" and add a prominent TODO for the developer to fill in a real one.`,

package/docs/algolia-sdk/README.md

@@ -20,14 +20,21 @@ Always install the **latest stable** within the major (use a caret range like `^
 
 - Use a **search-only API key** in any browser/client code. It is safe to expose.
   NEVER ship an admin or any write-capable key to the client.
-- Read the Application ID and search-only key from **public env vars**, never hardcode
-  them inline.
+- Import the Application ID and search-only key from the project's shared client-side
+  config module, where they are plain exported constants. They are public values, safe to
+  commit — do not read them from an env var or `.env*` file, and never hardcode them
+  inline anywhere else.
 - Instantiate the search client **once, outside your components**, and pass a stable
   reference. Do not inline `algoliasearch(...)` as a prop value — it breaks the
   client cache and causes re-renders.
 - For InstantSearch, import the client from `algoliasearch/lite` (smaller bundle and
   correct types — see `instantsearch-setup.md`).
 - Always enable **Insights** on the InstantSearch root with `insights: true`. Without it there are no click/conversion events, so many Algolia features will not work as expected.
+- Vendor CSS has to be **global** CSS: import an InstantSearch theme from a JS/TS module
+  or the app's global stylesheet, and keep `.ais-*` overrides in a global block. Inside a
+  framework-scoped style block (Astro `<style>`, Vue `<style scoped>`, Svelte `<style>`) or
+  a CSS Module, scoping rewrites the selectors, the widget's runtime DOM never carries the
+  scope attribute, and the styling silently does nothing while the build still passes.
 
 ## Files
 

package/docs/algolia-sdk/instantsearch-setup-js.md

@@ -20,10 +20,19 @@ const searchClient = algoliasearch(ALGOLIA_APP_ID, ALGOLIA_SEARCH_API_KEY)
 
 ## Vanilla (`instantsearch.js` v4)
 
+Use the `autocomplete` widget for the results panel. It already manages focus, blur,
+outside-click dismissal, Up/Down arrow navigation with wrap-around, Enter/Escape/Tab, and
+the combobox ARIA (`combobox`, `aria-expanded`, `aria-activedescendant`), so do not add
+your own open/close logic or ARIA roles around it.
+
+The `autocomplete` export needs `instantsearch.js` **4.110.0 or newer**. If the project
+pins an older 4.x, upgrade within the major (`^4`) rather than reaching for a different
+widget.
+
 ```js
 import { liteClient as algoliasearch } from 'algoliasearch/lite'
 import instantsearch from 'instantsearch.js'
-import { searchBox, hits } from 'instantsearch.js/es/widgets'
+import { autocomplete } from 'instantsearch.js/es/widgets'
 import {
   ALGOLIA_APP_ID,
   ALGOLIA_SEARCH_API_KEY,
@@ -39,24 +48,159 @@ const search = instantsearch({
 })
 
 search.addWidgets([
-  searchBox({ container: '#searchbox' }),
-  hits({ container: '#hits' }),
+  autocomplete({
+    container: '#autocomplete',
+    placeholder: 'Search...',
+    indices: [
+      {
+        indexName: ALGOLIA_INDEX_NAME,
+        getURL: (item) => `/products/${item.handle}`,
+        templates: {
+          item({ item, onSelect }, { html, components }) {
+            return html`<div onClick=${onSelect}>
+              ${components.Highlight({ hit: item, attribute: 'name' })}
+            </div>`
+          },
+          noResults(_, { html }) {
+            return html`<span>No results</span>`
+          },
+        },
+      },
+    ],
+  }),
 ])
 
 search.start()
 ```
 
+### Navigation is `getURL`'s job, not the template's
+
+Where the hits have a detail page, pass `indices[].getURL` — `(item) => string`, a route
+that already exists; don't invent one. The widget then navigates on click **and** on Enter
+over a keyboard-highlighted item, and records the click event on the way out. Without it,
+Enter on a highlighted result does nothing.
+
+The `item` template renders content only: **no `<a>`, no `href`, no click handler of your
+own, and never `stopPropagation`.** The widget's own `<li>` owns the click — it sends the
+Insights `click` event, closes the panel, and clears the active option. Wrapping the
+template in an anchor swallows all three: the link still navigates, so it looks correct,
+while click analytics never fire and the panel stays open behind the new page.
+
+Give every index a `templates.noResults` — without it the panel renders an empty box on a
+query that matches nothing.
+
+`getSearchPageURL` sends Enter with no result highlighted to a full search-results page;
+pass it only if the app has one. `.getQuery` is optional. Leave `showQuerySuggestions`,
+`showPromptSuggestions`, `showRecent`, and `aiMode` unset — each depends on an index or
+feature (query suggestions, recent-search storage, AI chat) this project doesn't have.
+
+In TypeScript, type the records through the widget's generic instead of casting inside the
+templates:
+
+```ts
+import type { Hit } from 'instantsearch.js'
+
+type ProductHit = Hit<{ title: string; handle: string }>
+
+autocomplete<ProductHit>({
+  /* item, getURL, and the templates are all typed from ProductHit */
+})
+```
+
+### Styling the panel
+
+The widget ships no CSS of its own. Install `instantsearch.css` and import a theme once,
+from the component's own JS/TS module or from the app's global stylesheet:
+
+```js
+import 'instantsearch.css/themes/satellite.css'
+```
+
+**Never import the theme as a CSS `@import` inside a framework-scoped style block** — an
+Astro `<style>`, a Vue `<style scoped>`, a Svelte `<style>`, a CSS Module. Scoping
+rewrites every selector in the imported theme
+(`.ais-AutocompleteInput[data-astro-cid-abc123]`), and the widget renders its own DOM at
+runtime into an empty container, so none of those elements carry the scope attribute and
+not one theme rule matches. Nothing errors, the build passes, and the search UI renders
+unstyled. Your own overrides of `.ais-*` classes have the same problem: put them in global
+CSS (`<style is:global>` in Astro, an unscoped block or `:deep()` in Vue).
+
+The theme already ships a dark palette behind `:root[data-theme=dark], .dark`. In a dark
+app, set `data-theme="dark"` on `<html>` or render the widget under a `.dark` ancestor and
+adjust from there — don't redefine the light palette by hand.
+
+The theme defines its palette as `--ais-*` custom properties on `:root`, and the colors
+are **RGB triplets consumed through `rgba()`**, not CSS colors — override them with
+triplets or every widget color breaks:
+
+```css
+:root {
+  --ais-background-color-rgb: 24, 24, 27; /* not #18181b */
+  --ais-text-color-rgb: 244, 244, 245;
+  --ais-primary-color-rgb: 129, 140, 248;
+}
+```
+
+Everything else is plain CSS against the widget's own classes, or `cssClasses` /
+`indices[].cssClasses` to add your own class names to the same elements. Know which
+element owns what before writing a rule:
+
+- `.ais-Autocomplete` — root. Its **container** sets the widget's width; don't try to size
+  the widget from the input.
+- `.ais-AutocompleteForm` — the visible frame: background, border, radius, and the focus
+  ring (`:focus-within`). Style the input's pill here.
+- `.ais-AutocompleteInput` — text only. The theme gives it `border: 0`,
+  `background: none`, `width: 100%`. A border or a fixed width here leaves the form's own
+  frame drawn around it and changes no widths.
+- `.ais-AutocompletePanel` (+ `--open`) and `.ais-AutocompletePanelLayout` — dropdown
+  surface and its scroll container.
+- `.ais-AutocompleteIndex`, `-IndexHeader`, `-IndexList`, `-IndexItem`, `-IndexNoResults`
+  — one index's results. The active item carries `aria-selected="true"`.
+- `.ais-AutocompleteItemWrapper`, `-ItemContent`, `-ItemIcon` — inside one result.
+- `.ais-AutocompleteSubmitButton`, `-ClearButton`, `-LoadingIndicator`, `-Label` — the
+  form's own controls.
+- `.ais-AutocompleteDetached*` — detached mode (below).
+
+Don't style a class that isn't in that list: `.ais-SearchBox-*` belongs to the `searchBox`
+widget and does nothing here. To check the names against the installed version:
+`grep -o 'ais-Autocomplete[A-Za-z-]*' node_modules/instantsearch.css/themes/satellite.css | sort -u`.
+
+The theme's panel is `position: absolute; width: 100%`, so it inherits the width of the
+input container — a small input yields an unreadably narrow panel. Give it a minimum
+width and anchor it to the edge it opens from, or it grows off-screen:
+
+```css
+.ais-AutocompletePanel {
+  min-width: 320px;
+  left: 0; /* right: 0; left: auto for an input aligned to the right */
+}
+```
+
+Below `(max-width: 680px)` the widget switches to detached (fullscreen) mode: the inline
+form is replaced by a `.ais-AutocompleteDetachedSearchButton`, and the form and results
+move into an overlay (`.ais-AutocompleteDetachedOverlay`,
+`.ais-AutocompleteDetachedContainer`, `.ais-AutocompleteDetachedFormContainer`). So panel
+width rules only apply above that breakpoint, and styling the inline form leaves the
+mobile trigger button on the theme's own look unless you style it too. Change the
+breakpoint with `detachedMediaQuery` or `--ais-autocomplete-detached-media-query`; pass
+`''` to disable detached mode and keep the inline form at every width.
+
 ## Insights (click analytics) — always enable it
 
 The `insights` option turns on the Insights middleware (`instantsearch.js` v4.55+),
 which adds `clickAnalytics: true` to every query and keeps the `userToken` in sync
 between search and event calls. Never set `clickAnalytics` or `userToken` on the `configure` widget by hand.
 
-Use `insights: true`. The middleware loads `search-insights` from the jsDelivr CDN
-itself; do not install the package or pass `insightsClient`.
+Use `insights: true` and nothing else. The middleware loads `search-insights` from the
+jsDelivr CDN itself; do not install the package, do not pass `insightsClient`, and do not
+declare `window.aa`.
+
+Everything below this line is a **conditional fallback**. Apply one only when its stated
+condition actually holds in this project — a CSP you can point at, a user id the app
+already has. Where it doesn't hold, `insights: true` is the whole implementation.
 
-If a Content-Security-Policy blocks jsDelivr, the CDN script cannot load. In that
-case, install `search-insights` from npm and pass its default export as
+If the project has a Content-Security-Policy that blocks jsDelivr, the CDN script cannot
+load. Only in that case, install `search-insights` from npm and pass its default export as
 `insightsClient` in the `insights` option:
 
 ```js
@@ -90,27 +234,19 @@ insights: {
 
 ### Click and conversion events
 
-The `hits` and `infiniteHits` widgets send `view` and `click` events on their own. A
-custom `item` template whose click target is your own element gets `sendEvent` as the
-second argument:
+With `insights: true`, the `autocomplete` widget sends `view` and `click` events itself:
+`view` when results render, `click` from the result element's own click handler. Its item
+template receives `{ item, onSelect }` and **no `sendEvent`** — there is nothing to wire,
+and nothing to send events from. Call `onSelect` for the widget's own selection behavior
+(closing the panel, recording a recent search); the click event fires either way.
 
-```js
-hits({
-  container: '#hits',
-  templates: {
-    item(hit, { html, sendEvent }) {
-      return html`<a
-        href="${hit.url}"
-        onClick="${() => sendEvent('click', hit, 'Hit Clicked')}"
-        >${hit.name}</a
-      >`
-    },
-  },
-})
-```
+The `hits` and `infiniteHits` widgets behave the same way. Only a custom `item` template
+there needs explicit wiring, and only when its click target is your own element — that
+template gets `sendEvent` as the second argument.
 
-Conversions are business actions (add to cart, signup, booking), so wire them at the
-real action, not at render:
+Conversions are business actions (add to cart, signup, booking) that happen away from the
+results panel, so wire them at the real action, in a component that has a `sendEvent` of
+its own:
 
 ```js
 sendEvent('conversion', hit, 'Product Added To Cart', {

package/docs/algolia-sdk/instantsearch-setup-react.md

@@ -20,9 +20,18 @@ const searchClient = algoliasearch(ALGOLIA_APP_ID, ALGOLIA_SEARCH_API_KEY)
 
 ## React (`react-instantsearch` v7)
 
+Use the `Autocomplete` widget for the results panel. It already manages focus, blur,
+outside-click dismissal, Up/Down arrow navigation with wrap-around, Enter/Escape/Tab, and
+the combobox ARIA (`combobox` on the input, `aria-expanded`, `aria-activedescendant`), so
+do not add your own open/close logic or ARIA roles around it.
+
+The `Autocomplete` export needs `react-instantsearch` **7.18.0 or newer**. If the project
+pins an older 7.x, upgrade within the major (`^7`) rather than reaching for a different
+widget.
+
 ```tsx
 import { liteClient as algoliasearch } from 'algoliasearch/lite'
-import { InstantSearch, SearchBox, Hits } from 'react-instantsearch'
+import { InstantSearch, Autocomplete } from 'react-instantsearch'
 import {
   ALGOLIA_APP_ID,
   ALGOLIA_SEARCH_API_KEY,
@@ -38,13 +47,137 @@ export function Search() {
       indexName={ALGOLIA_INDEX_NAME}
       insights={true}
     >
-      <SearchBox />
-      <Hits />
+      <Autocomplete
+        placeholder="Search..."
+        indices={[
+          {
+            indexName: ALGOLIA_INDEX_NAME,
+            getURL: (item) => `/products/${item.handle}`,
+            itemComponent: ({ item, onSelect }) => (
+              <div onClick={onSelect}>{item.name}</div>
+            ),
+            noResultsComponent: () => <span>No results</span>,
+          },
+        ]}
+      />
     </InstantSearch>
   )
 }
 ```
 
+### Navigation is `getURL`'s job, not the item component's
+
+Where the hits have a detail page, pass `indices[].getURL` — `(item) => string`, a route
+that already exists; don't invent one. The widget then navigates on click **and** on Enter
+over a keyboard-highlighted item, and records the click event on the way out. Without it,
+Enter on a highlighted result does nothing.
+
+`itemComponent` renders content only: **no `<a>`, no `href`, no `onClick` of your own
+beyond the `onSelect` it is handed, and never `stopPropagation`.** The widget's own `<li>`
+owns the click — it sends the Insights `click` event, closes the panel, and clears the
+active option. Wrapping the item in a link or a router `<Link>` swallows all three: the
+navigation still happens, so it looks correct, while click analytics never fire and the
+panel stays open behind the new page.
+
+Give every index a `noResultsComponent` — without it the panel renders an empty box on a
+query that matches nothing.
+
+`getSearchPageURL` sends Enter with no result highlighted to a full search-results page;
+pass it only if the app has one. `.getQuery` is optional. Leave `showQuerySuggestions`,
+`showPromptSuggestions`, `showRecent`, and `aiMode` unset — each depends on an index or
+feature (query suggestions, recent-search storage, AI chat) this project doesn't have.
+
+In TypeScript, type the records through the component's generic instead of casting inside
+`itemComponent`:
+
+```tsx
+import type { Hit } from 'instantsearch.js'
+
+type ProductHit = Hit<{ title: string; handle: string }>
+
+export function Search() {
+  // item, getURL, and itemComponent are all typed from ProductHit
+  return <Autocomplete<ProductHit> indices={[]} />
+}
+```
+
+### Styling the panel
+
+The widget ships no CSS of its own. Install `instantsearch.css` and import a theme once,
+from the component module or the app's global stylesheet:
+
+```tsx
+import 'instantsearch.css/themes/satellite.css'
+```
+
+**Never route the theme through scoped or module CSS** — a CSS Module, an Astro `<style>`,
+a Vue `<style scoped>`, a Svelte `<style>`, or any styled-components-style wrapper that
+rewrites selectors. Scoping renames every selector in the imported theme, and the widget
+renders its own DOM at runtime, so none of its elements match the rewritten names. Nothing
+errors, the build passes, and the search UI renders unstyled. Your own overrides of
+`.ais-*` classes have the same problem: keep them in a global stylesheet, or add your own
+class names through `classNames` and style those instead.
+
+The theme already ships a dark palette behind `:root[data-theme=dark], .dark`. In a dark
+app, set `data-theme="dark"` on `<html>` or render the widget under a `.dark` ancestor and
+adjust from there — don't redefine the light palette by hand.
+
+The theme defines its palette as `--ais-*` custom properties on `:root`, and the colors
+are **RGB triplets consumed through `rgba()`**, not CSS colors — override them with
+triplets or every widget color breaks:
+
+```css
+:root {
+  --ais-background-color-rgb: 24, 24, 27; /* not #18181b */
+  --ais-text-color-rgb: 244, 244, 245;
+  --ais-primary-color-rgb: 129, 140, 248;
+}
+```
+
+Everything else is plain CSS against the widget's own classes, or the `classNames` /
+`indices[].classNames` props to add your own class names to the same elements. Know which
+element owns what before writing a rule:
+
+- `.ais-Autocomplete` — root. Its **container** sets the widget's width; don't try to size
+  the widget from the input.
+- `.ais-AutocompleteForm` — the visible frame: background, border, radius, and the focus
+  ring (`:focus-within`). Style the input's pill here.
+- `.ais-AutocompleteInput` — text only. The theme gives it `border: 0`,
+  `background: none`, `width: 100%`. A border or a fixed width here leaves the form's own
+  frame drawn around it and changes no widths.
+- `.ais-AutocompletePanel` (+ `--open`) and `.ais-AutocompletePanelLayout` — dropdown
+  surface and its scroll container.
+- `.ais-AutocompleteIndex`, `-IndexHeader`, `-IndexList`, `-IndexItem`, `-IndexNoResults`
+  — one index's results. The active item carries `aria-selected="true"`.
+- `.ais-AutocompleteItemWrapper`, `-ItemContent`, `-ItemIcon` — inside one result.
+- `.ais-AutocompleteSubmitButton`, `-ClearButton`, `-LoadingIndicator`, `-Label` — the
+  form's own controls.
+- `.ais-AutocompleteDetached*` — detached mode (below).
+
+Don't style a class that isn't in that list: `.ais-SearchBox-*` belongs to the `SearchBox`
+widget and does nothing here. To check the names against the installed version:
+`grep -o 'ais-Autocomplete[A-Za-z-]*' node_modules/instantsearch.css/themes/satellite.css | sort -u`.
+
+The theme's panel is `position: absolute; width: 100%`, so it inherits the width of the
+input container — a small input yields an unreadably narrow panel. Give it a minimum
+width and anchor it to the edge it opens from, or it grows off-screen:
+
+```css
+.ais-AutocompletePanel {
+  min-width: 320px;
+  left: 0; /* right: 0; left: auto for an input aligned to the right */
+}
+```
+
+Below `(max-width: 680px)` the widget switches to detached (fullscreen) mode: the inline
+form is replaced by a `.ais-AutocompleteDetachedSearchButton`, and the form and results
+move into an overlay (`.ais-AutocompleteDetachedOverlay`,
+`.ais-AutocompleteDetachedContainer`, `.ais-AutocompleteDetachedFormContainer`). So panel
+width rules only apply above that breakpoint, and styling the inline form leaves the
+mobile trigger button on the theme's own look unless you style it too. Change the
+breakpoint with `detachedMediaQuery` or `--ais-autocomplete-detached-media-query`; pass
+`''` to disable detached mode and keep the inline form at every width.
+
 Do not inline `searchClient={algoliasearch(...)}` — keep the stable reference above.
 
 ## Insights (click analytics) — always enable it
@@ -53,17 +186,29 @@ The `insights` prop turns on the Insights middleware, which adds
 `clickAnalytics: true` to every query and keeps the `userToken` in sync between search
 and event calls. Never set `clickAnalytics` or `userToken` on `<Configure>` by hand.
 
-Use `insights={true}`. The middleware loads `search-insights` from the jsDelivr CDN
-itself; do not install the package or pass `insightsClient`.
+Use `insights={true}` and nothing else. The middleware loads `search-insights` from the
+jsDelivr CDN itself; do not install the package, do not pass `insightsClient`, and do not
+declare `window.aa`.
+
+Everything below this line is a **conditional fallback**. Apply one only when its stated
+condition actually holds in this project — a CSP you can point at, a user id the app
+already has. Where it doesn't hold, `insights={true}` is the whole implementation.
 
-If a Content-Security-Policy blocks jsDelivr, the CDN script cannot load. In that
+If the project has a Content-Security-Policy that blocks jsDelivr, the CDN script cannot
+load. In that
 case, install `search-insights` from npm and pass its default export as
 `insightsClient`:
 
 ```tsx
 import aa from 'search-insights'
 
-<InstantSearch insights={{ insightsClient: aa }} />
+export function Search() {
+  return (
+    <InstantSearch insights={{ insightsClient: aa }}>
+      {/* widgets */}
+    </InstantSearch>
+  )
+}
 ```
 
 The middleware calls `aa('init', ...)` itself with the app ID and search key, so no
@@ -83,8 +228,14 @@ policy allows it:
 
 ### Click and conversion events
 
-`<Hits>` and `<InfiniteHits>` send `view` and `click` events on their own. Two cases
-need explicit wiring:
+With `insights={true}`, `<Autocomplete>` sends `view` and `click` events itself: `view`
+when results render, `click` from the result element's own click handler. Its
+`itemComponent` receives `{ item, onSelect, onApply }` and **no `sendEvent`** — there is
+nothing to wire, and nothing to send events from. Call `onSelect` for the widget's own
+selection behavior (closing the panel, recording a recent search); the click event fires
+either way.
+
+`<Hits>` and `<InfiniteHits>` behave the same way. Two cases there need explicit wiring:
 
 - A custom `hitComponent` whose click target is your own element — it receives a
   `sendEvent` prop.

package/docs/algolia-sdk/instantsearch-setup-vue.md

@@ -20,19 +20,68 @@ const searchClient = algoliasearch(ALGOLIA_APP_ID, ALGOLIA_SEARCH_API_KEY)
 
 ## Vue (`vue-instantsearch` v4)
 
+Use `ais-autocomplete` for the query and results state. `ais-autocomplete` is headless: its default
+slot only provides `currentRefinement`, `indices`, and `refine` — it renders nothing and
+handles no focus, blur, keyboard, or ARIA itself. You must build all of it: keep the panel
+closed until the input is focused and has a query, close it on Escape, blur, or an outside
+click, move an active-option highlight with the Up/Down arrows and select it with Enter,
+carry the combobox ARIA on the input, and send click events via each index's `sendEvent`.
+
 ```vue
 <template>
-  <ais-instant-search
-    :search-client="searchClient"
-    :index-name="ALGOLIA_INDEX_NAME"
-    :insights="true"
-  >
-    <ais-search-box />
-    <ais-hits />
-  </ais-instant-search>
+  <div ref="containerRef" class="search" @focusout="onFocusOut">
+    <ais-instant-search
+      :search-client="searchClient"
+      :index-name="ALGOLIA_INDEX_NAME"
+      :insights="true"
+    >
+      <ais-autocomplete>
+        <template v-slot="{ currentRefinement, indices, refine }">
+          <input
+            type="search"
+            role="combobox"
+            aria-autocomplete="list"
+            aria-controls="search-panel"
+            :aria-expanded="isOpen(currentRefinement)"
+            :aria-activedescendant="
+              active >= 0 ? `search-option-${active}` : undefined
+            "
+            :value="currentRefinement"
+            @focus="open = true"
+            @input="onInput(refine, $event)"
+            @keydown.down.prevent="move(1, indices)"
+            @keydown.up.prevent="move(-1, indices)"
+            @keydown.enter.prevent="select(indices, active)"
+            @keydown.esc="close"
+          />
+          <ul
+            v-show="isOpen(currentRefinement)"
+            id="search-panel"
+            class="search-panel"
+            role="listbox"
+            aria-label="Search results"
+          >
+            <li
+              v-for="(hit, i) in indices[0]?.hits ?? []"
+              :id="`search-option-${i}`"
+              :key="hit.objectID"
+              role="option"
+              :aria-selected="i === active"
+              :class="{ 'is-active': i === active }"
+              @mousedown.prevent="select(indices, i)"
+              @mousemove="active = i"
+            >
+              <ais-highlight attribute="name" :hit="hit" />
+            </li>
+          </ul>
+        </template>
+      </ais-autocomplete>
+    </ais-instant-search>
+  </div>
 </template>
 
 <script setup>
+import { ref } from 'vue'
 import { liteClient as algoliasearch } from 'algoliasearch/lite'
 import {
   ALGOLIA_APP_ID,
@@ -41,9 +90,73 @@ import {
 } from '<the project's shared config module>'
 
 const searchClient = algoliasearch(ALGOLIA_APP_ID, ALGOLIA_SEARCH_API_KEY)
+const open = ref(false)
+const active = ref(-1)
+const containerRef = ref(null)
+
+function isOpen(currentRefinement) {
+  return open.value && Boolean(currentRefinement)
+}
+
+function onInput(refine, event) {
+  open.value = true
+  active.value = -1
+  refine(event.currentTarget.value)
+}
+
+function move(delta, indices) {
+  const hits = indices[0]?.hits ?? []
+  if (!hits.length) return
+  open.value = true
+  const next = active.value + delta
+  active.value = next < 0 ? hits.length - 1 : next % hits.length
+}
+
+function select(indices, index) {
+  const hit = indices[0]?.hits?.[index]
+  if (!hit) return
+  indices[0].sendEvent('click', hit, 'Hit Clicked')
+  close()
+  // TODO: navigate to this hit's page, where the app has one
+}
+
+function close() {
+  open.value = false
+  active.value = -1
+}
+
+function onFocusOut(event) {
+  if (!containerRef.value?.contains(event.relatedTarget)) close()
+}
 </script>
 ```
 
+Details that break accessibility if changed:
+
+- `role="combobox"` belongs on the `input`, not on a wrapper — with `aria-controls`
+  pointing at the popup's `id` and `aria-activedescendant` at the active option's `id`.
+  Keep focus on the input while the arrows move the highlight.
+- The element carrying `role="listbox"` must be the direct parent of the
+  `role="option"` elements. A `ul` nested inside a `listbox` div, or options nested one
+  level deeper, breaks the accessibility tree.
+- `v-show`, not `v-if`, so the `aria-activedescendant` target stays in the DOM.
+- `@mousedown.prevent` on an option, not `@click` — selection has to land before
+  `focusout` closes the panel.
+- `focusout` on the wrapper is the outside-click dismissal: `event.relatedTarget` is
+  `null` for a click on non-focusable page chrome, so the panel closes. Don't add a
+  `document` click listener on top — it fights `@mousedown.prevent` on the options.
+- `.is-active` needs a visible style, not just `aria-selected`: the panel is the only
+  focus feedback a keyboard user gets, since focus never leaves the input.
+
+The panel is your own markup here, so it has no widget theme to inherit from: give
+`.search-panel` its own background from the app's theme tokens (never transparent over
+page content), text that clears 4.5:1 against that background, `position: absolute` with
+`min-width: 320px` anchored to the input edge it opens from, and a `max-height` with
+`overflow-y: auto`.
+
+`ais-autocomplete`'s `indices` slot prop supports federated search across multiple
+indices; this project has only one, so `indices[0]` is always the one to read.
+
 Register the widgets via the InstantSearch Vue plugin in your app entry:
 
 ```js
@@ -57,10 +170,14 @@ The `insights` prop turns on the Insights middleware, which adds
 `clickAnalytics: true` to every query and keeps the `userToken` in sync between search
 and event calls. Never set `clickAnalytics` or `userToken` on `ais-configure` by hand.
 
-Use `:insights="true"`. The middleware loads `search-insights` from the jsDelivr CDN itself; do not install
-the package or pass `insightsClient`.
+Use `:insights="true"` and nothing else. The middleware loads `search-insights` from the jsDelivr CDN
+itself; do not install the package, do not pass `insightsClient`, and do not declare `window.aa`.
 
-If a Content-Security-Policy blocks jsDelivr, the CDN script cannot load. In that
+Everything below this line is a **conditional fallback**. Apply one only when its stated condition
+actually holds in this project — a CSP you can point at, a user id the app already has. Where it
+doesn't hold, `:insights="true"` is the whole implementation.
+
+If the project has a Content-Security-Policy that blocks jsDelivr, the CDN script cannot load. In that
 case, install `search-insights` from npm and pass its default export as
 `insightsClient`:
 
@@ -85,19 +202,18 @@ const insights = { insightsInitParams: { useCookie: true } } // then :insights="
 
 ### Click and conversion events
 
-`ais-hits` sends `view` and `click` events on its own. A custom `item` slot whose
-click target is your own element needs the slot's `sendEvent`:
+`ais-autocomplete` wraps the same connector as the other flavors, so `view` events fire
+on their own when results render. `click` does not, because the option markup is yours:
+call the index's `sendEvent` from your own option handler, as in the setup example above.
 
 ```vue
-<ais-hits>
-  <template v-slot:item="{ item, sendEvent }">
-    <a :href="item.url" @click="sendEvent('click', item, 'Hit Clicked')">
-      {{ item.name }}
-    </a>
-  </template>
-</ais-hits>
+<li @mousedown.prevent="indices[0].sendEvent('click', hit, 'Hit Clicked')">
 ```
 
+`ais-hits`, if the app also has a full results page, does send `view` and `click` itself.
+Only a custom `item` slot there needs wiring, and only when its click target is your own
+element — that slot provides `sendEvent`.
+
 Conversions are business actions (add to cart, signup, booking), so wire them at the
 real action, not at render:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@algolia/wizard",
-  "version": "0.42.0",
+  "version": "0.43.0-rc.141.299",
   "description": "Magically implement Algolia functionality in your codebase",
   "type": "module",
   "engines": {