@magicx-eng/ai-autocomplete-vanilla 0.16.1 → 0.18.0

package/README.md

@@ -15,7 +15,7 @@ A framework-agnostic vanilla JS/TypeScript library that provides a guided AI-pow
 - **Keyboard navigation** — arrow keys, enter to submit, tab to autocomplete, backspace to un-bold the last completed param
 - **Client-side filtering** — instant substring filtering on every keystroke
 - **Datepicker** — date parameters are answered with a calendar instead of an option list. Click a day or navigate with the arrow keys; the date is committed the way it would be written — `Tuesday` for a date inside the next week, `March 23` for one later this year, `March 23 2027` for another year. Tapping a committed date re-opens the calendar on the month that text names now — for a weekday name, that is the next such day, not the one originally picked.
-- **Option overrides** — inject or dynamically generate client-side options per suggestion type
+- **Option overrides** — supply the options for a parameter yourself: a fixed list, a computed one, or one fetched from your own search endpoint as the user types
 - **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
 - **Accessible** — ARIA combobox 1.2 pattern with `role="listbox"`, `aria-activedescendant`
@@ -74,7 +74,7 @@ const ac = new AIAutocomplete(container, {
 
   // API
   apiConfig: { apiKey: "...", authScheme: "Bearer", endpoint: "https://api.ai-autocomplete.com/api/suggest" },
-  optionOverrides: { account: (query) => [...] },
+  optionOverrides: { location: async (query, signal) => [...] }, // see "Option Overrides"
   columns: 2,
   maskCompletedText: false, // when true, omits completed params' text from API requests (PII masking)
   additionalContext: { tier: "gold" }, // optional user context, to personalize suggestions and options
@@ -112,6 +112,7 @@ const ac = new AIAutocomplete(container, {
 
   // Events
   onSubmit: (result) => { ... },
+  onResult: (result) => { ... },           // after every successful round-trip — see "Reading the query as it's built"
   onError: (error) => { ... },
   onChange: (text) => { ... },
   onParamsChange: (params) => { ... },
@@ -135,6 +136,7 @@ ac.destroy();                  // Remove DOM, listeners, timers
 ac.setMode("dark");            // Switch color mode
 ac.update({ animations: false, optionsPosition: "above" });
 ac.selectProduct(product);     // Emit onProductSelect (Tier 3 / custom strips)
+ac.getResult();                // The AutocompleteResult as it stands right now
 ```
 
 > **Tier 1 auto-resets** after both Enter key and built-in submit-button clicks — your `onSubmit` runs, then the SDK clears the input and starts a new session. You don't need to call `ac.reset()` yourself in Tier 1.
@@ -451,6 +453,8 @@ unsub();
 | `isDropdownOpen` | `boolean` | Whether the dropdown should be visible |
 | `newParamId` | `string \| null` | ID of the most recently added param (for shimmer animation) |
 | `isLoading` | `boolean` | Fetch in progress. The Tier 1 / Tier 2 renderers gate the loading skeleton additionally on `!inSelectionAnimation` and `!editingParam`. |
+| `optionQuery` | `string` | The phrase the active parameter's options are filtered by — what the user has typed for it, trimmed — or the replacement typed so far during a re-edit. This is what an [option override](#option-overrides) is asked with. |
+| `isSearchingOptions` | `boolean` | True while an [option override](#option-overrides) for the parameter on screen has been asked and hasn't answered. Render the same skeleton you render for `isLoading`; the built-in dropdowns do. |
 | `inSelectionAnimation` | `boolean` | True for the 500 ms after a user-initiated option tap so the press animation can finish before the dropdown switches to the loading skeleton. |
 | `editingParam` | `CompletedParamState \| null` | When non-null, the user is re-editing a bold completed param; cached options remain visible and the loading skeleton is suppressed. |
 | `products` | `Product[]` | Results of the latest product search (empty unless `products` is configured). See [Product strip](#product-strip) — Tier 3 consumers render their own cards and call `selectProduct(product)` to emit `onProductSelect`. |
@@ -553,13 +557,42 @@ The SDK handles token refresh transparently: if a request returns 401, it calls
 
 ### `AutocompleteResult`
 
-The object passed to `onSubmit`:
+The structured query as the SDK currently understands it. The same object is passed to `onSubmit` when the user submits, to `onResult` after every successful round-trip, and returned by `ac.getResult()` on demand:
 
 | Field | Type | Description |
 |---|---|---|
-| `query` | `string` | Plain text as the user sees it. |
-| `raw_query` | `string` | Text with placeholder tokens (e.g. `"Create a {{TASK_1}}"`). |
-| `completed_params` | `CompletedParam[]` | Array of filled parameter values, followed by any the user skipped (see below). |
+| `query` | `string` | Plain text as the user sees it, trimmed. |
+| `raw_query` | `string` | `query` with each completed param replaced by its placeholder token (e.g. `"Create a {{TASK_1}}"`). |
+| `completed_params` | `CompletedParam[]` | Filled parameter values in query order, followed by any the user skipped (see below). |
+| `identified_params` | `IdentifiedParam[]` | Parameters the server recognised in the user's own words, as `{ type, value }` — e.g. `{ type: "due_date", value: "Friday" }` when the user typed "by Friday" instead of picking a date. They are not tokenized in `raw_query`, and they are tentative: each response replaces the set, and an entry drops out as soon as its text is edited away. |
+| `is_ready` | `boolean` | Whether the server considers the query complete enough to act on. |
+
+#### Reading the query as it's built
+
+You don't have to wait for submit. `onResult` fires after **every** successful round-trip with the result as it now stands, so you can mirror the structured query live — a preview panel, a draft saved as the user goes, analytics on how far they got:
+
+```ts
+const ac = new AIAutocomplete(el, {
+  onResult: (result) => {
+    preview.textContent = result.raw_query;
+    if (result.is_ready) enableRunButton();
+  },
+  onSubmit: (result) => run(result),
+});
+
+// Or subscribe later / more than once:
+const off = ac.on("result", (result) => save(result));
+
+// Or read it on demand, from a place that has no event handy:
+const draft = ac.getResult();
+```
+
+What "every successful round-trip" means in practice:
+
+- It fires once per response the SDK applied — including the very first request on mount (an empty result) and after a response that promoted text the user had already typed into a completed param.
+- It does **not** fire for a request that failed (`onError` does), was cancelled, or was superseded by a newer one before it returned.
+- Keystrokes that haven't been sent yet don't fire it. Typing is debounced and only reaches the server once at least two new characters have been added, so `onResult` lags the input by a beat; `ac.getResult()` always reflects the input as it is right now.
+- A submit is the last result you saw plus whatever the user typed since. Both are built by the same exported `buildSubmitResult`, so the shapes never drift.
 
 #### Skipped parameters
 
@@ -585,9 +618,11 @@ const offA = ac.on("change", logToAnalytics);
 const offB = ac.on("change", syncToStore);
 ```
 
-Events: `submit`, `error`, `change`, `paramsChange`, `stateChange`, `focus`, `blur`, `productSelect`.
+Events: `submit`, `result`, `error`, `change`, `paramsChange`, `stateChange`, `focus`, `blur`, `productSelect`.
+
+`result` carries an `AutocompleteResult` after every successful round-trip — see [Reading the query as it's built](#reading-the-query-as-its-built). Prefer it over `stateChange` when what you want is the structured query: `stateChange` fires on every internal update (focus, highlight, keystroke) and hands you raw state you would have to assemble yourself.
 
-**Errors in your callbacks are contained.** A listener that throws is logged to the console (once per event per instance) and the remaining listeners still run — the SDK's own state is unaffected, so a bug in one handler can't stall the widget. The same holds for `subscribe()` listeners and `optionOverrides` functions; an override that throws falls back to that suggestion's existing options rather than blanking the list. One exception is deliberate: if an `onSubmit` handler throws, Tier 1 skips its auto-reset so the user's typed query isn't cleared out from under a failed submit.
+**Errors in your callbacks are contained.** A listener that throws is logged to the console (once per event per instance) and the remaining listeners still run — the SDK's own state is unaffected, so a bug in one handler can't stall the widget. The same holds for `subscribe()` listeners and `optionOverrides` functions; an override that throws or rejects is logged once per instance and treated as an empty answer, never as a fetch error. One exception is deliberate: if an `onSubmit` handler throws, Tier 1 skips its auto-reset so the user's typed query isn't cleared out from under a failed submit.
 
 Constructor callbacks (`onSubmit`, `onChange`, etc.) are registered once at construction as the initial listener for that event. Use `on()` for any additional or replacement listeners. **`update()` does not swap event listeners** — use `on()` for dynamic listener management.
 
@@ -773,24 +808,36 @@ const ac = new AIAutocomplete(container, {
 
 ## Option Overrides
 
+Supply the options for a parameter yourself instead of taking the server's. Each entry is keyed by the suggestion `type` and is a function of the phrase the user has typed for that parameter:
+
 ```ts
 new AIAutocomplete(el, {
   optionOverrides: {
+    // A fixed list — a plain array is applied at once, no loading state.
     account: () => [
       { text: "Savings", is_tappable: true, kind: null },
       { text: "Checking", is_tappable: true, kind: null },
     ],
-    value: (query) => {
-      const digits = query.replace(/\D/g, "");
-      if (!digits) return [{ text: "$100", is_tappable: true, kind: null }];
-      return [{ text: `$${digits}`, is_tappable: true, kind: null }];
+    // A list that lives behind a request — return a promise. The dropdown
+    // shows its loading skeleton until it settles.
+    location: async (query, signal) => {
+      const res = await fetch(`/api/locations?q=${encodeURIComponent(query)}`, { signal });
+      const places = await res.json();
+      return places.map((p) => ({ text: p.name, is_tappable: true, kind: null }));
     },
   },
-  onSubmit: handleSubmit,
 });
 ```
 
----
+**When it's called.** Once the moment the parameter becomes active — a response suggests it, a skip or a selection moves it to the front, or the user taps a completed value of that type to change it — with whatever they have already typed for it (usually `""`, the request for the default list). Then again on the SDK's typing debounce with each new phrase, so you can run a search or page through a larger list. If a phrase is already covered by what you last returned, return that list again. The third argument is the `Suggestion` being answered, for the rare override that serves more than one type.
+
+**What's shown.** Your answer, as-is: it is not filtered again by the phrase it was produced for, so a fuzzy or synonym match survives. Between two calls the previous answer is filtered locally by what the user types, so the list reacts to every keystroke. Typing the full text of an option in the answer completes the parameter, exactly as it does for a server option.
+
+**The server's role.** The server's own options for an overridden type are never shown. While an override owns the active parameter the server is not asked for suggestions; it is asked again when the parameter is answered or skipped. Return an empty list for a typed phrase and the SDK falls back to the server for that phrase — the typed text goes out the way it does for a parameter with no matching options — and won't ask you the same phrase twice. An empty list for `""` leaves the parameter on screen with no options.
+
+**Cancellation and errors.** Honour `signal`: it is aborted when a newer phrase supersedes the call, when the parameter stops being active, and on `destroy()`. A throw or a rejection is logged once per instance and treated as an empty answer, never as a fetch error.
+
+Tier 3 exposes the pieces: `state.optionQuery` is the phrase, and `state.isSearchingOptions` is true while an answer is pending.
 
 ## License
 

package/dist/index.d.mts

@@ -147,7 +147,42 @@ interface AccessTokenResult {
     expiresAt?: number;
 }
 type APIConfig = APIKeyConfig | AccessTokenConfig;
-type OptionOverrides = Record<string, (query: string) => SuggestionOption[]>;
+/**
+ * Supplies the options for one suggestion type in place of the server's,
+ * which are never shown for an overridden type.
+ *
+ * Called
+ * - the moment a pill of this type becomes active (a response suggests it, a
+ *   skip or a selection moves it to the front, a completed param of this type
+ *   is tapped to re-edit), with whatever the user has already typed for it —
+ *   usually `""`, the request for the default list;
+ * - again on the SDK's typing debounce with each new phrase, so a consumer
+ *   whose options live behind a request can run a second search or page
+ *   through a larger list. Return the same list early if the phrase is
+ *   already covered by what was last returned.
+ *
+ * A plain array is applied synchronously — the right shape for a fixed or
+ * locally computed list. A promise shows the dropdown's loading state until it
+ * settles. Either way the answer is listed as-is, never filtered again by the
+ * phrase it was produced for, so a fuzzy or synonym match survives. Between
+ * two calls the previous answer is filtered locally by what the user types,
+ * for instant feedback.
+ *
+ * The server is not asked for suggestions while an override owns the active
+ * pill. It is asked again when the user answers or skips the pill, and as a
+ * fallback when the override returns an empty list for a non-empty phrase —
+ * the typed text then goes to the server the way it does for a pill with no
+ * matching options. An empty answer for `""` leaves the pill with no options,
+ * and the override is not re-asked for a phrase it has already answered empty.
+ *
+ * Honour `signal` in anything asynchronous: it is aborted when a newer phrase
+ * supersedes this call, when the pill stops being active, and on `destroy()`.
+ * A rejected promise or a throw is contained — logged once per instance and
+ * treated as an empty answer.
+ */
+type OptionOverride = (query: string, signal: AbortSignal, suggestion: Suggestion) => Promise<SuggestionOption[]> | SuggestionOption[];
+/** Per-suggestion-type option overrides, keyed by the suggestion's `type`. */
+type OptionOverrides = Record<string, OptionOverride>;
 /**
  * A single product card in the dropdown's product strip.
  *
@@ -208,10 +243,33 @@ interface ProductsConfig {
     /** Optional cap the SDK applies after `transform`. */
     limit?: number;
 }
+/**
+ * The structured query as the SDK currently understands it.
+ *
+ * Delivered to `onResult` after every successful suggestion round-trip and to
+ * `onSubmit` when the user submits. Both are built by `buildSubmitResult`, so
+ * a submit is just the last result the consumer already saw — plus whatever
+ * the user typed in between.
+ */
 interface AutocompleteResult {
+    /** Plain text as the user sees it, trimmed. */
     query: string;
+    /** `query` with each completed param replaced by its `{{PLACEHOLDER}}` token. */
     raw_query: string;
+    /**
+     * Params the user filled (in query order), followed by any they skipped
+     * (`text: "skipped"`, no placeholder). See `withSkippedParams`.
+     */
     completed_params: CompletedParam[];
+    /**
+     * Params the server identified in the user's own words — spans it matched to
+     * a parameter type without the user picking an option. Tentative: replaced
+     * wholesale by every response and dropped as soon as the text no longer
+     * matches. Never tokenized in `raw_query`.
+     */
+    identified_params: IdentifiedParam[];
+    /** Whether the server considers the query complete enough to act on. */
+    is_ready: boolean;
 }
 
 /** A calendar month on screen. `month` is 0-based, matching `Date#getMonth`. */
@@ -368,6 +426,20 @@ interface CoreInputState {
      * never shows results belonging to an older query.
      */
     products: Product[];
+    /**
+     * The consumer's {@link OptionSource} request for the pill on screen — the
+     * active suggestion, or the completed param being re-edited. `type` is the
+     * suggestion type it was asked for and `query` the phrase it was asked with;
+     * the answer itself is written into that suggestion's (or param's) `options`
+     * so every reader of those — filtering, exact-match promotion, the re-edit
+     * cache — sees it without knowing where it came from. Null when no source
+     * owns the pill on screen. Owned by `OptionSourceController`.
+     */
+    optionSearch: {
+        type: string;
+        query: string;
+        status: "loading" | "done";
+    } | null;
     activeDropdownIndex: number;
     newParamId: string | null;
     isLoading: boolean;
@@ -393,7 +465,7 @@ interface CoreInputState {
     /** Current caret offset within the editor. Tracked via DOM `selectionchange`. */
     caretOffset: number | null;
     /**
-     * True for ~500ms after a user-initiated option selection so the press
+     * True for ~170ms after a user-initiated option selection so the press
      * animation can finish before the dropdown switches to its loading skeleton.
      * Set by selectOption / ReEditManager.selectOption, cleared by a timer.
      */
@@ -467,6 +539,20 @@ interface CoreDerivedState {
     /** The month the datepicker is showing. Null unless `activeFormatType` is `"date"`. */
     dateView: DateMonthView | null;
     placeholderText: string;
+    /**
+     * The phrase the active pill's options are filtered by — what the user has
+     * typed for it, trimmed — or, during a re-edit, the replacement typed so
+     * far. `""` when nothing has been typed for the pill yet. This is the query
+     * an {@link OptionSource} is asked with.
+     */
+    optionQuery: string;
+    /**
+     * True while the consumer's {@link OptionSource} for the pill on screen has
+     * been asked and hasn't answered yet. The built-in dropdowns show their
+     * loading skeleton for it exactly as they do for `isLoading`; a custom UI
+     * should treat it the same way. Never true for a pill without a source.
+     */
+    isSearchingOptions: boolean;
     isDropdownOpen: boolean;
     /**
      * Whether the active (leading) pill should render in its `selected` state
@@ -561,7 +647,22 @@ interface CoreOptions {
      * the dropdown changes — no request, no markup, no layout shift.
      */
     products?: ProductsConfig;
+    /** Called when the user submits (Enter, or the submit button in Tier 1). */
     onSubmit?: (result: AutocompleteResult) => void;
+    /**
+     * Called after every successful suggestion round-trip with the structured
+     * query as the SDK now understands it — the same `AutocompleteResult` shape
+     * `onSubmit` delivers, so a consumer can mirror the query as it is built
+     * (a live preview, a draft, analytics) without waiting for submit.
+     *
+     * Fires once per response that was applied, including the initial request
+     * on mount (an empty result) and after a response that promoted typed text
+     * into a completed param. Does not fire for a request that failed, was
+     * aborted, or was superseded by a newer one before it returned. Nothing
+     * fires for a keystroke that hasn't been sent yet — read `getResult()` for
+     * the current value on demand.
+     */
+    onResult?: (result: AutocompleteResult) => void;
     onError?: (error: Error) => void;
     onChange?: (text: string) => void;
     onParamsChange?: (params: CompletedParamState[]) => void;
@@ -591,6 +692,7 @@ interface CoreOptions {
 
 type AIAutocompleteEvents = {
     submit: [result: AutocompleteResult];
+    result: [result: AutocompleteResult];
     error: [error: Error];
     change: [text: string];
     paramsChange: [params: CompletedParamState[]];
@@ -599,7 +701,7 @@ type AIAutocompleteEvents = {
     blur: [];
     productSelect: [product: Product];
 };
-type CoreUpdateOptions = Partial<Omit<CoreOptions, "onSubmit" | "onError" | "onChange" | "onParamsChange" | "onStateChange" | "onFocus" | "onBlur" | "onProductSelect" | "styleRoot">>;
+type CoreUpdateOptions = Partial<Omit<CoreOptions, "onSubmit" | "onResult" | "onError" | "onChange" | "onParamsChange" | "onStateChange" | "onFocus" | "onBlur" | "onProductSelect" | "styleRoot">>;
 declare class AIAutocomplete {
     private inputStore;
     private store;
@@ -609,6 +711,7 @@ declare class AIAutocomplete {
     private keyboardController;
     private pillsController;
     private productsController;
+    private optionSource;
     private reEdit;
     private modeController;
     private container;
@@ -617,11 +720,9 @@ declare class AIAutocomplete {
     private domRefs;
     private dropdownRefs;
     private timers;
-    /** One per instance — see {@link ConsumerBoundary}. Shared by the emitter, `subscribe()` and `optionOverrides`. */
+    /** One per instance — see {@link ConsumerBoundary}. Shared by the emitter and `subscribe()`. */
     private boundary;
     /** Identity of the raw override record the wrapped copy below was built from. */
-    private rawOverrides;
-    private wrappedOverrides;
     private subscriberCount;
     private emitter;
     private sessionId;
@@ -782,6 +883,14 @@ declare class AIAutocomplete {
      */
     subscribe(listener: (state: CoreState) => void): () => void;
     getState(): CoreState;
+    /**
+     * The structured query as the SDK understands it right now — the same
+     * object `onResult` delivers after each response and `onSubmit` delivers
+     * on submit. Read it on demand from a place that has no event handy (a
+     * custom submit button, a "save draft" action).
+     */
+    getResult(): AutocompleteResult;
+    private buildResult;
     get listboxId(): string;
     get isReady(): boolean;
     /**
@@ -797,24 +906,6 @@ declare class AIAutocomplete {
     selectOption(option: SuggestionOption): void;
     private startSelectionAnimationTimer;
     private fireTelemetry;
-    /**
-     * `this.opts` with every `optionOverrides` entry wrapped in the instance's
-     * {@link ConsumerBoundary}.
-     *
-     * The derive layer calls these functions on the SDK's stack — from
-     * `getState()`, and from inside the store's notification drain — so an
-     * un-wrapped throw would unwind whatever internal operation triggered the
-     * derive and abort delivery of every queued notification with it, taking the
-     * instance down rather than just the override. Wrapped, a failed override
-     * answers `undefined` and each call site falls back to the server's options.
-     *
-     * Memoized on the raw record's identity so a swapped integration is
-     * re-wrapped while a stable one isn't re-wrapped on every derive. Note
-     * `update({ optionOverrides })` only becomes visible on the next store write
-     * — the derived layer memoizes on inputs identity, and `update` doesn't
-     * invalidate it for this key. Pre-existing, and unchanged by the wrapping.
-     */
-    private deriveOpts;
     private setupContainer;
     private buildAndRenderFull;
     private buildAndRenderDropdown;
@@ -1024,12 +1115,18 @@ declare function needsOptionsGridMeasurement(count: number, isMobile: boolean):
  *
  * Web, five-plus options: two columns of three visible rows — but only when
  * every option provably fits on one line. Rows fill row-major (even indices
- * left, odd right), each column is as wide as its widest option, and the
- * columns may be unequal: the template splits the width in proportion to the
- * two column maxima, so whenever `left + right <= gridWidth`, each column gets
- * at least what its widest row needs. When the pair doesn't fit — or there are
- * no usable measurements (SSR, hidden grid, loading skeletons) — the layout
- * stays one scrollable column.
+ * left, odd right). The left track is exactly as wide as its widest option
+ * (a fixed pixel width from the measurement) and the right track takes the
+ * rest of the grid — which is at least its own widest option, because
+ * `left + right <= gridWidth` is the fit check. So the second column starts
+ * right where the first column's longest text ends, and short options such as
+ * sizes sit beside each other. (Splitting the width in proportion to the two
+ * maxima, as this used to, handed ALL the slack out in that ratio too: one
+ * long option in the left column and "34"-length options on the right gave
+ * the left column ~85% of the box and pushed the right column to the far
+ * edge, 2026-09-03.) When the pair doesn't fit — or there are no usable
+ * measurements (SSR, hidden grid, loading skeletons) — the layout stays one
+ * scrollable column.
  *
  * `rowWidths` are single-line pixel widths of the rendered rows (see
  * `measureOptionsGrid`); `gridWidth` is the grid's content width.
@@ -1189,10 +1286,17 @@ declare function renderEditableContent(args: RenderEditableArgs): void;
  * When the option list is taller than its scroll box, a small round button
  * with a down chevron sits at the bottom-centre of the list. It slides up into
  * view from behind the dropdown's lower edge (the footer, when the dropdown
- * opens below the input) the moment there is more to scroll to, slides back
- * down once the list is scrolled to its end, and scrolls the list a page on
- * click. The reference (the RB2B support panel, 2026-08-19): a white 32 px
- * disc that rises from behind the composer over ~150–180 ms, no fade.
+ * opens below the input) the moment there is more to scroll to, dissolves in
+ * place once the list is scrolled to its end, and scrolls the list a page on
+ * click. The entrance follows the reference (the RB2B support panel,
+ * 2026-08-19): a white 32 px disc that rises from behind the composer over
+ * ~150–180 ms, no fade. The exit deliberately does not mirror it — sliding
+ * back down read as the disc "falling" into the footer (2026-09-03), so
+ * instead it fades out where it stands, with a slight shrink, over
+ * SCROLL_ARROW_LEAVE_MS. The stylesheets key the two moves off two attributes:
+ * `data-aia-visible` (rise, stay) and `data-aia-leaving` (dissolve), which
+ * this controller holds for the fade's length and then clears, so the disc
+ * re-parks below the edge — invisibly — ready to rise again.
  *
  * The DOM differs per package (vanilla builds the button here; React and
  * Angular render their own markup with the same classes and data attributes),
@@ -1215,6 +1319,16 @@ declare const SCROLL_ARROW_CLASS = "magicx-aia-scroll-arrow";
 declare const SCROLL_ARROW_ATTR = "data-aia-scroll-arrow";
 /** Present on the button while it is shown. The stylesheets slide it in on this. */
 declare const SCROLL_ARROW_VISIBLE_ATTR = "data-aia-visible";
+/**
+ * Present on the button while it fades out. The stylesheets dissolve it in
+ * place on this; the controller clears it after SCROLL_ARROW_LEAVE_MS.
+ */
+declare const SCROLL_ARROW_LEAVING_ATTR = "data-aia-leaving";
+/**
+ * Length of the fade-out. Mirrors the `[data-aia-leaving]` transition in each
+ * package's stylesheet — change both together.
+ */
+declare const SCROLL_ARROW_LEAVE_MS = 240;
 /** Inline custom property: how far the button's bottom edge sits above the dropdown's padding edge. */
 declare const SCROLL_ARROW_BOTTOM_VAR = "--aia-scroll-arrow-bottom";
 declare const SCROLL_ARROW_LABEL = "Scroll down for more options";
@@ -1289,6 +1403,16 @@ declare function getFooterHint(optionHighlighted: boolean, isInputEmpty: boolean
     hint: string;
 };
 
+/**
+ * Projects client-side identified-param state onto its wire shape.
+ *
+ * The one place the `{ type, value }` form is spelled out. Both the request
+ * body (`api.ts`) and the `AutocompleteResult` handed to `onResult` /
+ * `onSubmit` go through it, so the params the consumer receives are exactly
+ * the ones the server was told about.
+ */
+declare function toWireIdentifiedParams(params: IdentifiedParamState[]): IdentifiedParam[];
+
 declare class ModeController {
     private container;
     private mode;
@@ -1342,14 +1466,25 @@ declare const SKIPPED_PARAM_TEXT = "skipped";
 declare function withSkippedParams(completed: CompletedParam[], skipped: SkippedParamState[]): CompletedParam[];
 
 /**
- * Builds the `AutocompleteResult` handed to `onSubmit`: the placeholder-
- * tokenized raw query plus the completed params, with skipped suggestions
- * folded in (see {@link withSkippedParams}).
+ * Fields of an {@link AutocompleteResult} that come from the latest server
+ * response rather than from the input. Both default to "nothing yet".
+ */
+interface SubmitResultExtras {
+    /** Server-identified params (`state.identifiedParams`). Default: none. */
+    identifiedParams?: IdentifiedParamState[];
+    /** Server's "query is complete" verdict (`state.isReady`). Default: false. */
+    isReady?: boolean;
+}
+/**
+ * Builds the `AutocompleteResult` handed to `onSubmit` and `onResult`: the
+ * placeholder-tokenized raw query plus the completed params, with skipped
+ * suggestions folded in (see {@link withSkippedParams}), the server-identified
+ * params in their wire shape, and the server's readiness verdict.
  *
  * Shared by every submit path — vanilla Enter / submit button, the React Tier 1
- * component, the Angular Tier 1 component — so they can't drift on what a
- * result contains.
+ * component, the Angular Tier 1 component — and by the core's per-response
+ * `result` event, so none of them can drift on what a result contains.
  */
-declare function buildSubmitResult(text: string, completedParams: CompletedParamState[], skippedParams?: SkippedParamState[]): AutocompleteResult;
+declare function buildSubmitResult(text: string, completedParams: CompletedParamState[], skippedParams?: SkippedParamState[], extras?: SubmitResultExtras): AutocompleteResult;
 
-export { AIAutocomplete, type APIConfig, type APIKeyConfig, ATTRIBUTION_URL, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteRequest, type AutocompleteResponse, type AutocompleteResult, type CompletedParam, type CompletedParamState, type CoreOptions, type CoreState, type DateMonthView, type FormatType, type IdentifiedParam, type IdentifiedParamState, type InputItem, type LooseDateOptions, ModeController, OPTIONS_GRID_MOBILE_QUERY, OPTION_ENTER_DELAY_VAR, OPTION_ENTER_FADE_MS, OPTION_ENTER_RISE_MS, OPTION_ENTER_RISE_PX, OPTION_ENTER_STAGGER_MS, type OptionOverrides, type OptionsGridLayout, type OptionsGridPlan, PLACEHOLDER_FADE_OUT_MS, PLACEHOLDER_LEAVING_ATTR, PLACEHOLDER_SWAP_GAP_MS, PLACEHOLDER_TYPE_MS, PLACEHOLDER_WORD_PAUSE_MS, type Product, type ProductsConfig, type RecentlySuggested, type RenderMode, SCROLL_ARROW_ATTR, SCROLL_ARROW_BOTTOM_VAR, SCROLL_ARROW_CLASS, SCROLL_ARROW_LABEL, SCROLL_ARROW_VISIBLE_ATTR, SKIPPED_PARAM_TEXT, type ScrollArrowArgs, type ScrollArrowController, type Segment, type SkippedParamState, type Store, type Suggestion, type SuggestionOption, type TaskKind, WEEKDAY_LABELS, addMonths, attachScrollArrow, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, computeOptionsGridLayout, createStore, cursorIsAtEnd, extractPlainText, formatDate, getCursorOffset, getFooterHint, identifiedParamLabel, isOptionsGridMobileViewport, isoDate, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionEnterDelayMs, optionsEntranceDurationMs, optionsGridTemplateColumns, parseDate, parseLooseDate, plainTextLength, planOptionsGrid, previousGraphemeBoundary, renderEditableContent, resolveFormatType, resolveIdentifiedDate, scrollCaretIntoView, selectedIsoFromText, setCursorOffset, withSkippedParams };
+export { AIAutocomplete, type APIConfig, type APIKeyConfig, ATTRIBUTION_URL, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteRequest, type AutocompleteResponse, type AutocompleteResult, type CompletedParam, type CompletedParamState, type CoreOptions, type CoreState, type DateMonthView, type FormatType, type IdentifiedParam, type IdentifiedParamState, type InputItem, type LooseDateOptions, ModeController, OPTIONS_GRID_MOBILE_QUERY, OPTION_ENTER_DELAY_VAR, OPTION_ENTER_FADE_MS, OPTION_ENTER_RISE_MS, OPTION_ENTER_RISE_PX, OPTION_ENTER_STAGGER_MS, type OptionOverride, type OptionOverrides, type OptionsGridLayout, type OptionsGridPlan, PLACEHOLDER_FADE_OUT_MS, PLACEHOLDER_LEAVING_ATTR, PLACEHOLDER_SWAP_GAP_MS, PLACEHOLDER_TYPE_MS, PLACEHOLDER_WORD_PAUSE_MS, type Product, type ProductsConfig, type RecentlySuggested, type RenderMode, SCROLL_ARROW_ATTR, SCROLL_ARROW_BOTTOM_VAR, SCROLL_ARROW_CLASS, SCROLL_ARROW_LABEL, SCROLL_ARROW_LEAVE_MS, SCROLL_ARROW_LEAVING_ATTR, SCROLL_ARROW_VISIBLE_ATTR, SKIPPED_PARAM_TEXT, type ScrollArrowArgs, type ScrollArrowController, type Segment, type SkippedParamState, type Store, type SubmitResultExtras, type Suggestion, type SuggestionOption, type TaskKind, WEEKDAY_LABELS, addMonths, attachScrollArrow, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, computeOptionsGridLayout, createStore, cursorIsAtEnd, extractPlainText, formatDate, getCursorOffset, getFooterHint, identifiedParamLabel, isOptionsGridMobileViewport, isoDate, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionEnterDelayMs, optionsEntranceDurationMs, optionsGridTemplateColumns, parseDate, parseLooseDate, plainTextLength, planOptionsGrid, previousGraphemeBoundary, renderEditableContent, resolveFormatType, resolveIdentifiedDate, scrollCaretIntoView, selectedIsoFromText, setCursorOffset, toWireIdentifiedParams, withSkippedParams };