@algolia/wizard 0.47.0 → 0.48.0-rc.141.344

package/dist/main.js

@@ -3584,7 +3584,7 @@ async function runAnalysis(mode, extraInstructions = []) {
 // package.json
 var package_default = {
   name: "@algolia/wizard",
-  version: "0.47.0",
+  version: "0.48.0-rc.141.344",
   description: "Magically implement Algolia functionality in your codebase",
   type: "module",
   engines: {
@@ -4299,6 +4299,7 @@ function searchInstructions(input) {
   return [
     "Implement an in-app Algolia search experience.",
     `Build the search UI for ${input.searchUiTarget}.`,
+    "Search UI only \u2014 the index is already populated. Do not create or modify ingestion scripts, rake/manage/CLI tasks, migrations, seeders, or other data-loading code, even if 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
@@ -4306,9 +4307,12 @@ 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.",
+    "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 the input and the active result a focus indicator visible against whatever sits behind it. Style the panel through the widget's class and CSS-variable overrides (or, when hand-built, the app's existing theme tokens) \u2014 never assume a light surface or reuse the surrounding page's colors unchanged inside the panel.",
+    "Vendor theme CSS, 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 overrides in a global block (Astro <style is:global>, an unscoped Vue block, a plain global CSS file). Never a framework-scoped style block or a CSS Module \u2014 scoping rewrites the vendor selectors and the widget's runtime DOM carries no scope attribute, so not one rule matches: 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 min-width of 320px independent of the input, anchored to the input edge it opens from so widening 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,20 @@ 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 as plain exported constants. They are public, safe to commit — never read
+  them from an env var or `.env*` file, and never hardcode them elsewhere.
 - 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 must be **global**: import an InstantSearch theme from a JS/TS module or the
+  app's global stylesheet and keep `.ais-*` overrides in a global block. In a scoped style
+  block (Astro `<style>`, Vue `<style scoped>`, Svelte `<style>`) or a CSS Module, scoping
+  rewrites the selectors, the widget's runtime DOM carries no scope attribute, and the
+  styling silently does nothing while the build passes.
 
 ## Files
 

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

@@ -20,10 +20,18 @@ const searchClient = algoliasearch(ALGOLIA_APP_ID, ALGOLIA_SEARCH_API_KEY)
 
 ## Vanilla (`instantsearch.js` v4)
 
+Use the `autocomplete` widget for the results panel. It owns focus, blur, outside-click
+dismissal, Up/Down navigation with wrap-around, Enter/Escape/Tab, and the combobox ARIA
+(`combobox`, `aria-expanded`, `aria-activedescendant`) — add no open/close logic or ARIA
+roles of your own.
+
+Needs `instantsearch.js` **4.110.0+**. If an older 4.x is pinned, upgrade within `^4`
+rather than switching widgets.
+
 ```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 +47,128 @@ 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: 'title' })}
+            </div>`
+          },
+          noResults(_, { html }) {
+            return html`<span>No results</span>`
+          },
+        },
+      },
+    ],
+  }),
 ])
 
 search.start()
 ```
 
+### Match entity schema
+
+Ensure the attributes you map into the component match the entity. 'title' above is an example.
+
+### Navigation is `getURL`'s job, not the template's
+
+- `indices[].getURL` — `(item) => string`, a route that already exists; don't invent one.
+  It navigates on click **and** on Enter over a highlighted item, and records the click
+  event.
+- The `item` template renders content only: **no `<a>`, no `href`, no click handler of
+  your own, never `stopPropagation`.** The widget's `<li>` owns the click — it sends the
+  Insights `click`, closes the panel, clears the active option.
+- `getSearchPageURL` sends Enter with nothing highlighted to a full results page; pass it
+  only if the app has one. `.getQuery` is optional.
+- TypeScript: type records through the generic, not casts inside templates —
+  `type ProductHit = Hit<{ title: string; handle: string }>` (`Hit` from
+  `instantsearch.js`), then `autocomplete<ProductHit>({ ... })` types `item`, `getURL`,
+  and the templates.
+
+### Styling the panel
+
+The widget ships no CSS. Install `instantsearch.css` and import a theme once, from the
+component's own JS/TS module or the app's global stylesheet:
+
+```js
+import 'instantsearch.css/themes/satellite.css'
+```
+
+The theme and your `.ais-*` overrides must be **global**: never a CSS `@import` inside a
+framework-scoped style block (Astro `<style>`, Vue `<style scoped>`, Svelte `<style>`) or
+a CSS Module.
+Use `<style is:global>` (Astro), an unscoped block or `:deep()` (Vue), or plain global CSS.
+
+The theme ships a dark palette behind `:root[data-theme=dark], .dark`: in a dark app set
+`data-theme="dark"` on `<html>` or render under a `.dark` ancestor, then adjust.
+
+Palette lives in `--ais-*` custom properties on `:root` as **RGB triplets consumed through
+`rgba()`**, override with triplets only:
+
+```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 classes, or `cssClasses` /
+`indices[].cssClasses` to add your own names to the same elements. Who owns what:
+
+- `.ais-Autocomplete` — root. Its **container** sets the widget's width; don't size the
+  widget from the input.
+- `.ais-AutocompleteForm` — visible frame: background, border, radius, focus ring
+  (`:focus-within`). The input's pill goes here.
+- `.ais-AutocompleteInput` — text only; theme sets `border: 0`, `background: none`,
+  `width: 100%`. A border or width here leaves the form's frame drawn around it and
+  changes no widths.
+- `.ais-AutocompletePanel` (+ `--open`), `.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` — form
+  controls.
+- `.ais-AutocompleteDetached*` — detached mode (below).
+
+The theme's panel is `position: absolute; width: 100%`, so it inherits the input
+container's width — a small input yields an unreadably narrow panel. Give it a min-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 goes detached (fullscreen): the inline form becomes
+a `.ais-AutocompleteDetachedSearchButton`, form and results move into an overlay
+(`.ais-AutocompleteDetachedOverlay`, `.ais-AutocompleteDetachedContainer`,
+`.ais-AutocompleteDetachedFormContainer`). So panel-width rules apply only above that
+breakpoint, and styling the inline form leaves the mobile trigger button on the theme's
+look unless you style it too. Change it with `detachedMediaQuery` or
+`--ais-autocomplete-detached-media-query`; pass `''` to disable detached mode entirely.
+
 ## 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, pass `insightsClient`, or declare
+`window.aa`.
 
-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
+Only if the project has a Content-Security-Policy blocking jsDelivr (the CDN script then
+cannot load): install `search-insights` from npm and pass its default export as
 `insightsClient` in the `insights` option:
 
 ```js
@@ -74,9 +186,7 @@ manual `init` call is needed. Keep using the `insightsInitParams` option (for
 example `useCookie`) the same way as with the CDN path.
 
 The middleware sets an anonymous `userToken` itself, so events fire with no extra
-code. That token lives in memory only — a page reload starts a new one, which is
-enough for search→click attribution within a session but not across sessions, and not
-enough for Personalization to build a profile. To persist it in the first-party
+code. To persist it in the first-party
 `_ALGOLIA` cookie, switch to the object form — only where the app's cookie-consent
 policy allows it:
 
@@ -90,27 +200,16 @@ 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`, `autocomplete` sends `view` (on render) and `click` (from the
+result element's own handler) itself. Its item template gets `{ item, onSelect }` and
+**no `sendEvent`** — nothing to wire. Call `onSelect` for the widget's selection behavior
+(close the panel, record 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
-      >`
-    },
-  },
-})
-```
+`hits` and `infiniteHits` behave the same; only a custom `item` template whose click
+target is your own element needs wiring — it 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) away from the results
+panel: wire them at the real action, in a component with its own `sendEvent`:
 
 ```js
 sendEvent('conversion', hit, 'Product Added To Cart', {
@@ -161,14 +260,3 @@ import aa from 'search-insights'
 aa('setAuthenticatedUserToken', userId)
 aa('setAuthenticatedUserToken', undefined) // on logout
 ```
-
-## Frameworks without their own flavor
-
-Only React and Vue have a maintained InstantSearch wrapper. For any other
-framework — Angular, Svelte, Solid — drive `instantsearch.js` directly from a
-component, mounting widgets against element refs and calling `search.dispose()`
-on teardown.
-
-Do NOT install `angular-instantsearch` or a community `*-instantsearch` package:
-`angular-instantsearch` is deprecated and archived (last release v4.4.3, Sep 2024),
-is incompatible with Angular v13+, and receives no security fixes.

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

@@ -20,9 +20,17 @@ const searchClient = algoliasearch(ALGOLIA_APP_ID, ALGOLIA_SEARCH_API_KEY)
 
 ## React (`react-instantsearch` v7)
 
+Use the `Autocomplete` widget for the results panel. It owns focus, blur, outside-click
+dismissal, Up/Down navigation with wrap-around, Enter/Escape/Tab, and the combobox ARIA
+(`combobox` on the input, `aria-expanded`, `aria-activedescendant`) — add no open/close
+logic or ARIA roles of your own.
+
+Needs `react-instantsearch` **7.18.0+**. If an older 7.x is pinned, upgrade within `^7`
+rather than switching widgets.
+
 ```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 +46,109 @@ 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.title}</div>
+            ),
+            noResultsComponent: () => <span>No results</span>,
+          },
+        ]}
+      />
     </InstantSearch>
   )
 }
 ```
 
+### Match entity schema
+
+Ensure the attributes you map into the component match the entity. 'title' above is an example.
+
+### Navigation is `getURL`'s job, not the item component's
+
+- `indices[].getURL` — `(item) => string`, a route that already exists; don't invent one.
+  It navigates on click **and** on Enter over a highlighted item, and records the click
+  event.
+- `itemComponent` renders content only: **no `<a>`, no `href`, no `onClick` beyond the
+  `onSelect` it is handed, never `stopPropagation`.** The widget's `<li>` owns the click —
+  it sends the Insights `click`, closes the panel, clears the active option.
+- `getSearchPageURL` sends Enter with nothing highlighted to a full results page; pass it
+  only if the app has one. `.getQuery` is optional.
+- TypeScript: type records through the generic, not casts inside `itemComponent` —
+  `type ProductHit = Hit<{ title: string; handle: string }>` (`Hit` from
+  `instantsearch.js`), then `<Autocomplete<ProductHit> ... />` types `item`, `getURL`, and
+  `itemComponent`.
+
+### Styling the panel
+
+The widget ships no CSS. 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'
+```
+
+The theme and your `.ais-*` overrides must be **global**: never route either through a CSS
+Module, a scoped style block (Astro `<style>`, Vue `<style scoped>`, Svelte `<style>`), or
+any styled-components-style wrapper that rewrites selectors. Keep them in a global
+stylesheet, or add your own class names via `classNames` and style those.
+
+The theme ships a dark palette behind `:root[data-theme=dark], .dark`: in a dark app set
+`data-theme="dark"` on `<html>` or render under a `.dark` ancestor, then adjust.
+
+Palette lives in `--ais-*` custom properties on `:root` as **RGB triplets consumed through
+`rgba()`**, override with triplets only:
+
+```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 classes, or the `classNames` /
+`indices[].classNames` props to add your own names to the same elements. Who owns what:
+
+- `.ais-Autocomplete` — root. Its **container** sets the widget's width; don't size the
+  widget from the input.
+- `.ais-AutocompleteForm` — visible frame: background, border, radius, focus ring
+  (`:focus-within`). The input's pill goes here.
+- `.ais-AutocompleteInput` — text only; theme sets `border: 0`, `background: none`,
+  `width: 100%`. A border or width here leaves the form's frame drawn around it and
+  changes no widths.
+- `.ais-AutocompletePanel` (+ `--open`), `.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` — form
+  controls.
+- `.ais-AutocompleteDetached*` — detached mode (below).
+
+The theme's panel is `position: absolute; width: 100%`, so it inherits the input
+container's width — a small input yields an unreadably narrow panel. Give it a min-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 goes detached (fullscreen): the inline form becomes
+a `.ais-AutocompleteDetachedSearchButton`, form and results move into an overlay
+(`.ais-AutocompleteDetachedOverlay`, `.ais-AutocompleteDetachedContainer`,
+`.ais-AutocompleteDetachedFormContainer`). So panel-width rules apply only above that
+breakpoint, and styling the inline form leaves the mobile trigger button on the theme's
+look unless you style it too. Change it with `detachedMediaQuery` or
+`--ais-autocomplete-detached-media-query`; pass `''` to disable detached mode entirely.
+
 Do not inline `searchClient={algoliasearch(...)}` — keep the stable reference above.
 
 ## Insights (click analytics) — always enable it
@@ -53,17 +157,24 @@ 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, pass `insightsClient`, or declare
+`window.aa`.
 
-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
+Only if the project has a Content-Security-Policy blocking jsDelivr (the CDN script then
+cannot load): 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
@@ -71,9 +182,7 @@ manual `init` call is needed. Keep using the `insightsInitParams` option (for
 example `useCookie`) the same way as with the CDN path.
 
 The middleware sets an anonymous `userToken` itself, so events fire with no extra
-code. That token lives in memory only — a page reload starts a new one, which is
-enough for search→click attribution within a session but not across sessions, and not
-enough for Personalization to build a profile. To persist it in the first-party
+code. To persist it in the first-party
 `_ALGOLIA` cookie, switch to the object form — only where the app's cookie-consent
 policy allows it:
 
@@ -83,8 +192,13 @@ 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` (on render) and `click` (from the
+result element's own handler) itself. Its `itemComponent` receives
+`{ item, onSelect, onApply }` and **no `sendEvent`** — nothing to wire. Call `onSelect`
+for the widget's selection behavior (close the panel, record 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. It is **headless**: its default
+slot provides only `currentRefinement`, `indices`, and `refine` — it renders nothing and
+handles no focus, blur, keyboard, or ARIA. Build all of it yourself: panel closed until
+the input is focused and has a query; close on Escape, blur, or outside click; active-option
+highlight on Up/Down with Enter to select; combobox ARIA on the input; 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,71 @@ 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"` on the `input`, not a wrapper — with `aria-controls` at the popup's
+  `id` and `aria-activedescendant` at the active option's `id`. Focus stays on the input
+  while the arrows move the highlight.
+- The `role="listbox"` element must be the direct parent of the `role="option"` elements;
+  a `ul` inside a `listbox` div, or options one level deeper, breaks the a11y tree.
+- `v-show`, not `v-if`, so the `aria-activedescendant` target stays in the DOM.
+- `@mousedown.prevent` on an option, not `@click` — selection must 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 chrome). Don't add a `document` click listener on
+  top — it fights `@mousedown.prevent`.
+- `.is-active` needs a visible style, not just `aria-selected` — it is a keyboard user's
+  only focus feedback, since focus never leaves the input.
+
+The panel is your own markup with no widget theme to inherit: give `.search-panel` a
+background from the app's theme tokens (never transparent over page content), text
+clearing 4.5:1 against it, `position: absolute` with `min-width: 320px` anchored to the
+input edge it opens from, and a `max-height` with `overflow-y: auto`.
+
+`indices` supports federated search across indices; this project has one, so `indices[0]`
+is always the one to read.
+
 Register the widgets via the InstantSearch Vue plugin in your app entry:
 
 ```js
@@ -57,12 +168,11 @@ 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, pass `insightsClient`, or declare `window.aa`.
 
-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
-`insightsClient`:
+Only if the project has a Content-Security-Policy blocking jsDelivr (the CDN script then cannot
+load): install `search-insights` from npm and pass its default export as `insightsClient`:
 
 ```js
 import aa from 'search-insights'
@@ -73,9 +183,7 @@ The middleware calls `aa('init', ...)` itself with the app ID and search key, so
 manual `init` call is needed.
 
 The middleware sets an anonymous `userToken` itself, so events fire with no extra
-code. That token lives in memory only — a page reload starts a new one, which is
-enough for search→click attribution within a session but not across sessions, and not
-enough for Personalization to build a profile. To persist it in the first-party
+code. To persist it in the first-party
 `_ALGOLIA` cookie, bind the object form — only where the app's cookie-consent policy
 allows it:
 
@@ -85,19 +193,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` fires on its
+own when results render. `click` does not — 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) sends both itself; only a custom
+`item` slot whose click target is your own element needs wiring — 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.47.0",
+  "version": "0.48.0-rc.141.344",
   "description": "Magically implement Algolia functionality in your codebase",
   "type": "module",
   "engines": {