@magicx-eng/ai-autocomplete-react 0.7.0 → 0.8.1

package/README.md

@@ -17,6 +17,7 @@ A React/TypeScript SDK that provides a guided AI-powered autocomplete experience
 - **IME-safe** — composition events are buffered so input text is committed once, after composition ends
 - **Client-side filtering** — instant substring filtering on every keystroke
 - **Option overrides** — inject or dynamically generate client-side options per suggestion type
+- **Product strip (opt-in)** — plug in any platform's product search and the dropdown renders a horizontal row of product cards below the options; the SDK owns the UI, your integration owns only `fetch` and `transform`
 - **Controlled & uncontrolled** — works out of the box or integrates with external state
 - **Ref forwarding** — imperative `focus()`, `blur()`, `reset()`, and `setMode()` via ref
 - **Accessible** — ARIA combobox 1.2 pattern with `role="listbox"`, `aria-activedescendant`
@@ -246,9 +247,110 @@ function App() {
 | `completedParams?` | `CompletedParamState[]` | — | Controlled completed params. |
 | `onChange?` | `(value: string) => void` | — | Called when text changes (controlled mode). |
 | `onParamsChange?` | `(params: CompletedParamState[]) => void` | — | Called when params change (controlled mode). |
+| `products?` | `ProductsConfig` | — | Opt-in product strip — see [Product strip](#product-strip). Omit it and nothing about the dropdown changes. |
+| `onProductSelect?` | `(product: Product) => void` | — | Called when a product card is activated. The SDK never navigates. |
 | `submitButton?` | `ReactNode` | — | Custom submit button. Pass any `ReactNode` to replace the default arrow button. Pass `null` to render no button. Clicks bubble up and trigger submit, so consumer-supplied buttons work without re-wiring `onClick`. |
 | `ref?` | `Ref<AIAutocompleteHandle>` | — | Imperative handle with `focus()`, `blur()`, `reset()`, and `setMode()`. |
 
+#### Product strip
+
+Opt in with `products` and the dropdown renders a horizontal row of product
+cards below the options grid. Every platform (Shopify today, others later) has
+its own search endpoint and its own response shape, so the SDK owns the UI and
+the integration owns only the fetching and the mapping.
+
+```tsx
+import { AIAutocomplete, type Product } from "@magicx-eng/ai-autocomplete-react";
+
+const products = {
+  // You own the request entirely — auth headers, GraphQL body, locale
+  // prefixes. Honour the signal: the SDK aborts it as soon as a newer query
+  // supersedes this one.
+  fetch: (query: string, signal: AbortSignal) =>
+    fetch(`/api/products?q=${encodeURIComponent(query)}`, { signal }).then((r) => r.json()),
+
+  // Pure mapping, kept out of `fetch` so you can unit-test it without a
+  // network.
+  transform: (raw: unknown): Product[] =>
+    (raw as ApiResponse).items.map((item) => ({
+      id: item.id,
+      title: item.title,
+      url: item.url,
+      imageUrl: item.image?.src ?? null,   // null renders the placeholder tile
+      price: formatMoney(item.price),      // you know the currency
+      vendor: item.brand,
+    })),
+
+  limit: 8,   // applied by the SDK, after transform
+};
+
+<AIAutocomplete
+  onSubmit={handleSubmit}
+  products={products}
+  // Selection emits — the SDK never navigates.
+  onProductSelect={(product) => router.push(product.url)}
+/>;
+```
+
+`Product` is exactly six fields; only `id`, `title` and `url` are required:
+
+```ts
+type Product = {
+  id: string;
+  title: string;
+  url: string;
+  imageUrl?: string | null;
+  price?: string;
+  vendor?: string;
+};
+```
+
+**What the SDK guarantees**
+
+- **One fetch cadence.** The product search rides the same debounce, the same
+  `AbortController` and the same version guard as `/suggest` — there is no
+  second timer to drift out of step.
+- **Empty queries never reach you.** On mount and after `reset()` the strip
+  clears.
+- **Out-of-order responses are dropped.** A slow response for an older query is
+  never rendered over a newer one.
+- **Failure is silent.** A rejected `fetch` or a throwing `transform` clears the
+  strip, logs once, and leaves the suggestions half untouched — no `error`
+  state, no `onError`, no effect on `isLoading`.
+- **The two halves are independent.** The panel opens if *either* has content,
+  so products keep it open when option filtering empties the option list.
+  `dropdownTrigger` (`manual` / `hidden`) still gates the panel as before.
+- **Inline configs are safe.** `products={{ fetch, transform }}` written inline
+  re-creates the object on every render; the hook forwards through a stable
+  proxy, so only turning the strip on or off reaches the core. Two deliberate
+  consequences: swapping one live config for another leaves the previous
+  integration's cards up until the next request replaces them (toggle
+  `products` off and back on to clear immediately), and turning the strip on
+  mid-session shows nothing until the next `/suggest` request fires — the
+  product search rides that one scheduler, and enabling the strip doesn't
+  itself change the query.
+
+**Selection and links.** Cards are real `<a href>` elements, so cmd/ctrl-click,
+middle-click and "copy link address" behave natively. A plain left click is
+intercepted (`preventDefault`) and emits `onProductSelect` instead.
+
+`product.url` is used verbatim — the SDK trusts your `transform` output and
+does not sanitise it, so validate the URL there if the platform response isn't
+fully under your control. (Angular additionally runs its own `[href]`
+sanitiser, so unrecognised schemes like `myapp://…` are rewritten to
+`unsafe:…` in that package only.)
+
+**Accessibility.** The strip is a `role="group"` labelled "Products"; each card
+is a `role="option"` in the tab order, activated with Enter or Space, with a
+visible focus ring. Tabbing into the strip does not close the panel. The row
+scrolls horizontally by trackpad, wheel, touch and keyboard; the page never
+scrolls sideways and the scrollbar chrome is hidden in all engines.
+
+Tier 2 gets the same thing: pass `products` / `onProductSelect` to
+`useAIAutocomplete()` and the strip renders inside `<AIAutocompleteDropdown />`
+via `dropdownProps`. Tier 3 consumers read `products` from the hook and call
+`selectProduct(product)` from their own cards.
+
 #### Custom submit button
 
 ```tsx
@@ -329,6 +431,7 @@ The headless hook for Tier 2 and Tier 3. Accepts the same options as `<AIAutocom
 | `isDropdownOpen` | `boolean` | Whether the dropdown should be visible. Drive your own dropdown's visibility with this in Tier 3. |
 | `placeholderText` | `string` | Suggested placeholder text for the current step. |
 | `error` | `Error \| null` | Last fetch error. |
+| `products` | `Product[]` | Results of the latest product search. Empty unless `products` is configured. Already spread into `dropdownProps` — read it directly only if you render your own strip. |
 
 **Actions**
 
@@ -338,6 +441,7 @@ The headless hook for Tier 2 and Tier 3. Accepts the same options as `<AIAutocom
 | `removeLastParam` | `() => void` | Remove the last completed param from state. The text stays in the input as plain text. |
 | `clearNewParamId` | `() => void` | Clear shimmer animation state. |
 | `reset` | `() => void` | Clear all state, re-fetch, and start a new session (rotates `session_id`). Call this after handling submit. |
+| `selectProduct` | `(product: Product) => void` | Announce a product selection (fires `onProductSelect`). The built-in dropdown calls this for you; hand-rolled strips call it themselves. Never navigates. |
 
 **Input forwarding (custom inputs)** — call these instead of spreading `inputProps` when your input isn't a `<textarea>` (contentEditable / rich-text editors):
 
@@ -353,7 +457,7 @@ The headless hook for Tier 2 and Tier 3. Accepts the same options as `<AIAutocom
 | Field | Type | Description |
 |---|---|---|
 | `inputProps` | `object` | Spread onto a `<textarea>`. Includes `value`, `placeholder`, `onChange`, `onKeyDown`, and ARIA attributes. |
-| `dropdownProps` | `AIAutocompleteDropdownProps` | Spread onto `<AIAutocompleteDropdown />`. Carries the options, `activeIndex`, `onSelect` / `onHighlight`, pills, open state, and `optionsPosition` — read these directly to render your own dropdown in Tier 3. |
+| `dropdownProps` | `AIAutocompleteDropdownProps` | Spread onto `<AIAutocompleteDropdown />`. Carries the options, `activeIndex`, `onSelect` / `onHighlight`, pills, open state, `optionsPosition`, and the product strip's `products` / `onProductSelect` / `onProductFocusChange` — read these directly to render your own dropdown in Tier 3. |
 
 ### `<AIAutocompleteDropdown />`
 
@@ -373,6 +477,9 @@ The dropdown component for Tier 2. Spread `dropdownProps` from the hook (and add
 | `pills?` | `Suggestion[]` | Pills to render inside the dropdown. |
 | `onPillClick?` | `(index: number) => void` | Called when a pill is clicked. |
 | `showPills?` | `boolean` | Whether to render pills. Default: `true`. |
+| `products?` | `Product[]` | Product cards to render below the options grid. Empty (the default) renders no strip. |
+| `onProductSelect?` | `(product: Product) => void` | Called when a card is activated. |
+| `onProductFocusChange?` | `(focused: boolean) => void` | Called when focus enters/leaves the strip. Wired to `setFocused` by `dropdownProps` so a tabbed-to card doesn't close the panel. |
 | `isLoading?` | `boolean` | When `true`, the dropdown renders its pills + options as a skeleton: text masked, layout (count and widths) preserved, shimmer pulse animating. Falls back to a generic 3-bar placeholder when no pills/options are cached. |
 
 ### `AutocompleteResult`
@@ -431,6 +538,21 @@ Override on the container (via `className`). All defaults use `:where()` (zero s
 | `--aia-scrollbar-thumb` | `rgba(0, 0, 0, 0.3)` | `rgba(0, 0, 0, 0.3)` | Color of the option list's scrollbar thumb (Firefox + WebKit). |
 | `--aia-streak-rgb` | `99, 102, 241` | `255, 255, 255` | Comma-separated RGB triplet used to tint the option-selection streak animation (consumed via `rgba(var(--aia-streak-rgb), …)`). |
 | `--aia-streak-glass-bg` | `rgba(99, 102, 241, 0.1)` | `rgba(255, 255, 255, 0.1)` | Background fill for the streak's glass-pill effect. |
+| `--aia-product-card-width` | `116px` | `116px` | Width of a product card in the strip. The media tile is square, so this also sets its height. |
+| `--aia-product-gap` | `8px` | `8px` | Gap between product cards. |
+| `--aia-product-bg` | `transparent` | `transparent` | Product card background. |
+| `--aia-product-bg-active` | `--aia-option-bg` | `--aia-option-bg` | Product card background on hover. |
+| `--aia-product-media-bg` | `--aia-skeleton-bg` | `--aia-skeleton-bg` | Fill behind the product image, and of the placeholder tile when a product has no image. |
+| `--aia-product-placeholder-color` | `--aia-option-color` | `--aia-option-color` | Glyph color of the no-image placeholder tile. |
+| `--aia-product-title-color` | `--aia-option-color-selected` | `--aia-option-color-selected` | Product title text. Follows the option colors by default, so theming the panel moves suggestions and products together. |
+| `--aia-product-price-color` | `--aia-option-color-selected` | `--aia-option-color-selected` | Product price text. |
+| `--aia-product-vendor-color` | `--aia-option-color` | `--aia-option-color` | Product vendor line. |
+| `--aia-product-focus-ring` | `--aia-option-color-selected` | `--aia-option-color-selected` | Focus ring drawn on a keyboard-focused card. |
+| `--aia-products-label-color` | `--aia-option-color` | `--aia-option-color` | "Products" section label. |
+| `--aia-product-title-font-size` | `12px` | `12px` | Product title font size. |
+| `--aia-product-price-font-size` | `11px` | `11px` | Product price font size. |
+| `--aia-product-vendor-font-size` | `10px` | `10px` | Product vendor font size. |
+| `--aia-products-label-font-size` | `11px` | `11px` | Section label font size. |
 | `--aia-skeleton-bg` | `rgba(189, 189, 189, 0.25)` | `#1a1b1d` | Fill color for the loading skeleton bars and the masked text in cached pills/options. |
 
 Legacy `--aia-color-*` variables are still supported as fallbacks.
@@ -459,7 +581,11 @@ For styling beyond the CSS variables, target these stable `data-aia-*` attribute
 | `[data-aia-pill]` | Each unfilled-suggestion pill |
 | `[data-aia-pillbar]` | Pill bar container inside the dropdown |
 | `[data-aia-option]` | Each suggestion option |
-| `[data-aia-dropdown]` | The dropdown root (listbox) |
+| `[data-aia-dropdown]` | The dropdown root (listbox). Carries `data-aia-has-products` while the product strip has cards. |
+| `[data-aia-products]` | Product strip section (label + row) |
+| `[data-aia-products-row]` | The horizontally scrolling row of cards |
+| `[data-aia-product]` | Each product card |
+| `[data-aia-product-placeholder]` | Media tile of a card whose product has no image |
 
 Completed params render as inline `<strong>` elements inside the editor. Override their weight with `[data-aia-input] strong { font-weight: 700; }` (the built-in style uses `:where()` so any consumer selector wins without `!important`).
 

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { AutocompleteResult, OptionOverrides, APIConfig, AppearanceMode, CompletedParamState, Suggestion, SuggestionOption, SkippedParamState, Segment } from '@magicx-eng/ai-autocomplete-vanilla';
-export { APIConfig, APIKeyConfig, AccessTokenConfig, AccessTokenResult, AppearanceMode, AutocompleteResult, CompletedParam, CompletedParamState, OptionOverrides, Segment, SkippedParamState, Suggestion, SuggestionOption, TaskKind, buildSubmitResult, withSkippedParams } from '@magicx-eng/ai-autocomplete-vanilla';
+import { AutocompleteResult, OptionOverrides, APIConfig, AppearanceMode, CompletedParamState, ProductsConfig, Product, Suggestion, SuggestionOption, SkippedParamState, Segment } from '@magicx-eng/ai-autocomplete-vanilla';
+export { APIConfig, APIKeyConfig, AccessTokenConfig, AccessTokenResult, AppearanceMode, AutocompleteResult, CompletedParam, CompletedParamState, OptionOverrides, Product, ProductsConfig, Segment, SkippedParamState, Suggestion, SuggestionOption, TaskKind, buildSubmitResult, withSkippedParams } from '@magicx-eng/ai-autocomplete-vanilla';
 import * as react from 'react';
 import { ReactNode, KeyboardEvent, ChangeEvent } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -42,6 +42,32 @@ interface AIAutocompleteProps {
     completedParams?: CompletedParamState[];
     onChange?: (value: string) => void;
     onParamsChange?: (params: CompletedParamState[]) => void;
+    /**
+     * Opt-in product strip. When set, the dropdown renders a horizontal row of
+     * product cards below the options grid, fed by your own search endpoint on
+     * the SDK's existing fetch cadence. Omit it and nothing about the dropdown
+     * changes — no request, no markup, no layout shift.
+     *
+     * The object may be re-created on every render: the hook forwards calls
+     * through a stable proxy, so only toggling the strip on or off reaches the
+     * core.
+     *
+     * Two consequences of that proxy, both deliberate:
+     * - Swapping one live config for another (A → B, both defined) can't be told
+     *   apart from a re-render, so A's cards stay on screen until the next
+     *   request replaces them. Toggle `products` off and back on to clear
+     *   immediately.
+     * - Turning the strip on mid-session shows nothing until the next `/suggest`
+     *   request fires, because the product search rides that one scheduler and
+     *   enabling the strip doesn't itself change the query.
+     */
+    products?: ProductsConfig;
+    /**
+     * Called when the user activates a product card. The SDK does not navigate —
+     * you decide what a selection means. Modifier / middle clicks are left to the
+     * browser (so cmd-click still opens a tab) and don't fire this.
+     */
+    onProductSelect?: (product: Product) => void;
     /**
      * Custom submit button. Pass any ReactNode to replace the default button.
      * Pass `null` to render no button. Default (`undefined`) renders the built-in
@@ -75,6 +101,32 @@ interface UseAIAutocompleteOptions {
     onFocus?: () => void;
     /** Called when the input loses focus. */
     onBlur?: () => void;
+    /**
+     * Opt-in product strip. When set, the dropdown renders a horizontal row of
+     * product cards below the options grid, fed by your own search endpoint on
+     * the SDK's existing fetch cadence. Omit it and nothing about the dropdown
+     * changes — no request, no markup, no layout shift.
+     *
+     * The object may be re-created on every render: the hook forwards calls
+     * through a stable proxy, so only toggling the strip on or off reaches the
+     * core.
+     *
+     * Two consequences of that proxy, both deliberate:
+     * - Swapping one live config for another (A → B, both defined) can't be told
+     *   apart from a re-render, so A's cards stay on screen until the next
+     *   request replaces them. Toggle `products` off and back on to clear
+     *   immediately.
+     * - Turning the strip on mid-session shows nothing until the next `/suggest`
+     *   request fires, because the product search rides that one scheduler and
+     *   enabling the strip doesn't itself change the query.
+     */
+    products?: ProductsConfig;
+    /**
+     * Called when the user activates a product card. The SDK does not navigate —
+     * you decide what a selection means. Modifier / middle clicks are left to the
+     * browser (so cmd-click still opens a tab) and don't fire this.
+     */
+    onProductSelect?: (product: Product) => void;
     value?: string;
     completedParams?: CompletedParamState[];
     onChange?: (value: string) => void;
@@ -120,6 +172,18 @@ interface UseAIAutocompleteReturn {
     placeholderText: string;
     listboxId: string;
     error: Error | null;
+    /**
+     * Results of the latest product search. Always empty unless `products` is
+     * configured. Already spread into `dropdownProps` — read it directly only if
+     * you render your own strip.
+     */
+    products: Product[];
+    /**
+     * Announce a product selection (fires `onProductSelect`). The built-in
+     * dropdown calls this for you; hand-rolled strips call it themselves. The SDK
+     * never navigates.
+     */
+    selectProduct: (product: Product) => void;
     /** Tier 1 helper: forward plain-text input to the core (autocapitalize handled). */
     handleTextChange: (value: string) => void;
     /** Tier 1 helper: forward keyboard events to the core. */
@@ -177,6 +241,17 @@ interface AIAutocompleteDropdownProps {
     isLoading?: boolean;
     /** When the input has no typed text, the footer hint reads "tab to select". Provided by `dropdownProps` from the hook. */
     isInputEmpty?: boolean;
+    /** Product cards to render below the options grid. Provided by `dropdownProps` from the hook. Empty (the default) renders no strip. */
+    products?: Product[];
+    /** Called when a product card is activated. Provided by `dropdownProps` from the hook. */
+    onProductSelect?: (product: Product) => void;
+    /**
+     * Called when focus moves into / out of the product strip. The panel closes
+     * on blur by default and the input blurs the instant a card takes focus, so
+     * without this a card is unreachable by Tab. Provided by `dropdownProps`
+     * from the hook (wired to `setFocused`).
+     */
+    onProductFocusChange?: (focused: boolean) => void;
     /**
      * Where the dropdown opens relative to the input. When `"above"`, the dropdown
      * positions itself above (and reverses its internal layout so options sit
@@ -200,8 +275,8 @@ interface AIAutocompleteDropdownProps {
 
 declare const AIAutocomplete: react.ForwardRefExoticComponent<AIAutocompleteProps & react.RefAttributes<AIAutocompleteHandle>>;
 
-declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, isOpen, id, className, pills, onPillClick, showPills, activeSelected, isLoading, isInputEmpty, optionsPosition, mode, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
+declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, isOpen, id, className, pills, onPillClick, showPills, activeSelected, isLoading, isInputEmpty, products, onProductSelect, onProductFocusChange, optionsPosition, mode, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
 
-declare function useAIAutocomplete({ onSubmit, onError, optionOverrides, maskCompletedText, apiConfig, columns, dropdownTrigger, optionsPosition, closeDropdownOnBlur, showNonTappableOptions, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, source, setCursor, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
+declare function useAIAutocomplete({ onSubmit, onError, optionOverrides, maskCompletedText, apiConfig, columns, dropdownTrigger, optionsPosition, closeDropdownOnBlur, showNonTappableOptions, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, products, onProductSelect, source, setCursor, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
 
 export { AIAutocomplete, AIAutocompleteDropdown, type AIAutocompleteDropdownProps, type AIAutocompleteHandle, type AIAutocompleteProps, type UseAIAutocompleteOptions, type UseAIAutocompleteReturn, useAIAutocomplete };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { AutocompleteResult, OptionOverrides, APIConfig, AppearanceMode, CompletedParamState, Suggestion, SuggestionOption, SkippedParamState, Segment } from '@magicx-eng/ai-autocomplete-vanilla';
-export { APIConfig, APIKeyConfig, AccessTokenConfig, AccessTokenResult, AppearanceMode, AutocompleteResult, CompletedParam, CompletedParamState, OptionOverrides, Segment, SkippedParamState, Suggestion, SuggestionOption, TaskKind, buildSubmitResult, withSkippedParams } from '@magicx-eng/ai-autocomplete-vanilla';
+import { AutocompleteResult, OptionOverrides, APIConfig, AppearanceMode, CompletedParamState, ProductsConfig, Product, Suggestion, SuggestionOption, SkippedParamState, Segment } from '@magicx-eng/ai-autocomplete-vanilla';
+export { APIConfig, APIKeyConfig, AccessTokenConfig, AccessTokenResult, AppearanceMode, AutocompleteResult, CompletedParam, CompletedParamState, OptionOverrides, Product, ProductsConfig, Segment, SkippedParamState, Suggestion, SuggestionOption, TaskKind, buildSubmitResult, withSkippedParams } from '@magicx-eng/ai-autocomplete-vanilla';
 import * as react from 'react';
 import { ReactNode, KeyboardEvent, ChangeEvent } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -42,6 +42,32 @@ interface AIAutocompleteProps {
     completedParams?: CompletedParamState[];
     onChange?: (value: string) => void;
     onParamsChange?: (params: CompletedParamState[]) => void;
+    /**
+     * Opt-in product strip. When set, the dropdown renders a horizontal row of
+     * product cards below the options grid, fed by your own search endpoint on
+     * the SDK's existing fetch cadence. Omit it and nothing about the dropdown
+     * changes — no request, no markup, no layout shift.
+     *
+     * The object may be re-created on every render: the hook forwards calls
+     * through a stable proxy, so only toggling the strip on or off reaches the
+     * core.
+     *
+     * Two consequences of that proxy, both deliberate:
+     * - Swapping one live config for another (A → B, both defined) can't be told
+     *   apart from a re-render, so A's cards stay on screen until the next
+     *   request replaces them. Toggle `products` off and back on to clear
+     *   immediately.
+     * - Turning the strip on mid-session shows nothing until the next `/suggest`
+     *   request fires, because the product search rides that one scheduler and
+     *   enabling the strip doesn't itself change the query.
+     */
+    products?: ProductsConfig;
+    /**
+     * Called when the user activates a product card. The SDK does not navigate —
+     * you decide what a selection means. Modifier / middle clicks are left to the
+     * browser (so cmd-click still opens a tab) and don't fire this.
+     */
+    onProductSelect?: (product: Product) => void;
     /**
      * Custom submit button. Pass any ReactNode to replace the default button.
      * Pass `null` to render no button. Default (`undefined`) renders the built-in
@@ -75,6 +101,32 @@ interface UseAIAutocompleteOptions {
     onFocus?: () => void;
     /** Called when the input loses focus. */
     onBlur?: () => void;
+    /**
+     * Opt-in product strip. When set, the dropdown renders a horizontal row of
+     * product cards below the options grid, fed by your own search endpoint on
+     * the SDK's existing fetch cadence. Omit it and nothing about the dropdown
+     * changes — no request, no markup, no layout shift.
+     *
+     * The object may be re-created on every render: the hook forwards calls
+     * through a stable proxy, so only toggling the strip on or off reaches the
+     * core.
+     *
+     * Two consequences of that proxy, both deliberate:
+     * - Swapping one live config for another (A → B, both defined) can't be told
+     *   apart from a re-render, so A's cards stay on screen until the next
+     *   request replaces them. Toggle `products` off and back on to clear
+     *   immediately.
+     * - Turning the strip on mid-session shows nothing until the next `/suggest`
+     *   request fires, because the product search rides that one scheduler and
+     *   enabling the strip doesn't itself change the query.
+     */
+    products?: ProductsConfig;
+    /**
+     * Called when the user activates a product card. The SDK does not navigate —
+     * you decide what a selection means. Modifier / middle clicks are left to the
+     * browser (so cmd-click still opens a tab) and don't fire this.
+     */
+    onProductSelect?: (product: Product) => void;
     value?: string;
     completedParams?: CompletedParamState[];
     onChange?: (value: string) => void;
@@ -120,6 +172,18 @@ interface UseAIAutocompleteReturn {
     placeholderText: string;
     listboxId: string;
     error: Error | null;
+    /**
+     * Results of the latest product search. Always empty unless `products` is
+     * configured. Already spread into `dropdownProps` — read it directly only if
+     * you render your own strip.
+     */
+    products: Product[];
+    /**
+     * Announce a product selection (fires `onProductSelect`). The built-in
+     * dropdown calls this for you; hand-rolled strips call it themselves. The SDK
+     * never navigates.
+     */
+    selectProduct: (product: Product) => void;
     /** Tier 1 helper: forward plain-text input to the core (autocapitalize handled). */
     handleTextChange: (value: string) => void;
     /** Tier 1 helper: forward keyboard events to the core. */
@@ -177,6 +241,17 @@ interface AIAutocompleteDropdownProps {
     isLoading?: boolean;
     /** When the input has no typed text, the footer hint reads "tab to select". Provided by `dropdownProps` from the hook. */
     isInputEmpty?: boolean;
+    /** Product cards to render below the options grid. Provided by `dropdownProps` from the hook. Empty (the default) renders no strip. */
+    products?: Product[];
+    /** Called when a product card is activated. Provided by `dropdownProps` from the hook. */
+    onProductSelect?: (product: Product) => void;
+    /**
+     * Called when focus moves into / out of the product strip. The panel closes
+     * on blur by default and the input blurs the instant a card takes focus, so
+     * without this a card is unreachable by Tab. Provided by `dropdownProps`
+     * from the hook (wired to `setFocused`).
+     */
+    onProductFocusChange?: (focused: boolean) => void;
     /**
      * Where the dropdown opens relative to the input. When `"above"`, the dropdown
      * positions itself above (and reverses its internal layout so options sit
@@ -200,8 +275,8 @@ interface AIAutocompleteDropdownProps {
 
 declare const AIAutocomplete: react.ForwardRefExoticComponent<AIAutocompleteProps & react.RefAttributes<AIAutocompleteHandle>>;
 
-declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, isOpen, id, className, pills, onPillClick, showPills, activeSelected, isLoading, isInputEmpty, optionsPosition, mode, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
+declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, isOpen, id, className, pills, onPillClick, showPills, activeSelected, isLoading, isInputEmpty, products, onProductSelect, onProductFocusChange, optionsPosition, mode, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
 
-declare function useAIAutocomplete({ onSubmit, onError, optionOverrides, maskCompletedText, apiConfig, columns, dropdownTrigger, optionsPosition, closeDropdownOnBlur, showNonTappableOptions, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, source, setCursor, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
+declare function useAIAutocomplete({ onSubmit, onError, optionOverrides, maskCompletedText, apiConfig, columns, dropdownTrigger, optionsPosition, closeDropdownOnBlur, showNonTappableOptions, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, products, onProductSelect, source, setCursor, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
 
 export { AIAutocomplete, AIAutocompleteDropdown, type AIAutocompleteDropdownProps, type AIAutocompleteHandle, type AIAutocompleteProps, type UseAIAutocompleteOptions, type UseAIAutocompleteReturn, useAIAutocomplete };