@magicx-eng/ai-autocomplete-vanilla 0.35.0 → 0.36.0

package/README.md

@@ -59,7 +59,7 @@ const ac = new AIAutocomplete(document.getElementById("root"), {
   onSubmit: (result) => {
     console.log(result.query);            // "Create a email"
     console.log(result.raw_query);        // "Create a {{TASK_1}}"
-    console.log(result.completed_params); // [{ placeholder: "{{TASK_1}}", type: "task", ... }]
+    console.log(result.completed_params); // [{ placeholder: "{{TASK_1}}", parameter: "task", ... }]
   },
 });
 ```
@@ -283,7 +283,7 @@ ac.subscribe((state) => {
   if (!report) return;                         // no catalog was read for this response
   count.textContent = `${report.items.total} results`;
   if (report.dropped_filters.length > 0) {
-    // e.g. { param: "Color", value: "Chartreuse", op: "eq" } — the shopper asked
+    // e.g. { parameter: "Color", value: "Chartreuse", op: "eq" } — the shopper asked
     // for a colour no item carries, so the results ignore it. Say so.
     note.textContent = `No match for ${report.dropped_filters.map((f) => f.value).join(", ")}`;
   }
@@ -291,7 +291,7 @@ ac.subscribe((state) => {
 ```
 
 - `applied_filters` / `dropped_filters` — the constraints the server read out
-  of the query as `{ param, value, op }` (`op` is one of `eq`, `ne`, `lt`,
+  of the query as `{ parameter, value, op }` (`op` is one of `eq`, `ne`, `lt`,
   `lte`, `gt`, `gte`), split into the ones the catalog answered and the ones it
   could not (a parameter it does not have, a bound that is not a number, a
   value no item carries). The items answer the applied set, so the dropped
@@ -751,9 +751,9 @@ The structured query as the SDK currently understands it. The same object is pas
 | `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. |
+| `identified_params` | `IdentifiedParam[]` | Parameters the server recognised in the user's own words, as `{ parameter, text }` — e.g. `{ parameter: "due_date", text: "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. |
-| `custom_fields?` | `CustomFieldsReport` | What catalog grounding did for the latest applied response, when it read a catalog at all — see [Product strip](#product-strip). `applied_filters` and `dropped_filters` list the query's constraints as `{ param, value, op }`; `items.total` is how many items the applied ones left standing and `items.matched` the ones the strip renders. Absent (no key) when the response carried no report. |
+| `custom_fields?` | `CustomFieldsReport` | What catalog grounding did for the latest applied response, when it read a catalog at all — see [Product strip](#product-strip). `applied_filters` and `dropped_filters` list the query's constraints as `{ parameter, value, op }`; `items.total` is how many items the applied ones left standing and `items.matched` the ones the strip renders. Absent (no key) when the response carried no report. |
 
 #### Reading the query as it's built
 
@@ -787,12 +787,12 @@ What "every successful round-trip" means in practice:
 Pressing <kbd>→</kbd> at the end of the input dismisses the active pill. The dismissal is reported to the server — and included in `completed_params` here — as an entry with no placeholder and the sentinel text `"skipped"`:
 
 ```ts
-{ placeholder: "", type: "goal", text: "skipped", kind: null }
+{ placeholder: "", parameter: "goal", text: "skipped", kind: null }
 ```
 
-Skipped entries are appended after the filled params (they have no position in the query) and are deduped by type. A skip is dropped if a param of the same type ends up filled anyway. Skipping the last available pill triggers an immediate request so the server can suggest something else; earlier skips ride along on the next request. `reset()` clears them.
+Skipped entries are appended after the filled params (they have no position in the query) and are deduped by parameter. A skip is dropped if a param of the same parameter ends up filled anyway. Skipping the last available pill triggers an immediate request so the server can suggest something else; earlier skips ride along on the next request. `reset()` clears them.
 
-> **Reading `state.skippedParams` directly:** the array is append-only until `reset()`. The "drop a skip whose type got filled" rule is applied when the payload is built, not by pruning the array — so if the user skips `goal` and later fills one, the raw array still holds the `goal` entry. That's deliberate: the filter self-heals if they then delete that param's text, where pruning would discard the signal for good. Apply the same rule yourself with the exported `withSkippedParams(completedParams, skippedParams)`.
+> **Reading `state.skippedParams` directly:** the array is append-only until `reset()`. The "drop a skip whose parameter got filled" rule is applied when the payload is built, not by pruning the array — so if the user skips `goal` and later fills one, the raw array still holds the `goal` entry. That's deliberate: the filter self-heals if they then delete that param's text, where pruning would discard the signal for good. Apply the same rule yourself with the exported `withSkippedParams(completedParams, skippedParams)`.
 
 ### Event Subscription
 
@@ -1007,7 +1007,7 @@ Submits from Enter and from the built-in submit button are recorded for you. If
 
 ## 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:
+Supply the options for a parameter yourself instead of taking the server's. Each entry is keyed by the suggestion `parameter` and is a function of the phrase the user has typed for that parameter:
 
 ```ts
 new AIAutocomplete(el, {
@@ -1028,11 +1028,11 @@ new AIAutocomplete(el, {
 });
 ```
 
-**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.
+**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 parameter 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 parameter.
 
 **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.
+**The server's role.** The server's own options for an overridden parameter 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.
 

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 type TaskKind = "automation" | "email" | "insight";
 interface CompletedParam {
     placeholder: string;
-    type: string;
+    parameter: string;
     text?: string;
     kind: TaskKind | null;
 }
@@ -49,15 +49,34 @@ interface SuggestionOption {
     is_tappable: boolean;
     kind: TaskKind | null;
     metadata?: Record<string, unknown>;
+    /**
+     * The parameter a tap on this option answers. The server names it on every
+     * option; options the SDK builds itself (a calendar's dates) carry their
+     * suggestion's.
+     */
+    parameter?: string;
+}
+/**
+ * The value type of a suggestion's parameter — which picker it needs. Present
+ * only for a date or date-range parameter.
+ */
+interface SuggestionType {
+    kind: "string" | "numeric" | "date" | "date_range" | "boolean";
+    /** How a date is written, e.g. "DD/MM/YYYY". */
+    date_format?: string;
+    /** What joins the two dates of a range, e.g. " to ". */
+    separator?: string;
+    unit?: string;
 }
 interface Suggestion {
-    type: string;
+    parameter: string;
     text: string;
     required: boolean;
     options?: SuggestionOption[];
+    type?: SuggestionType;
 }
 interface InputItem {
-    type: string;
+    parameter: string;
     text: string;
     state: "completed" | "in_progress";
     /** Absent or "selected" = echo of client params; "identified" = LLM-inferred. */
@@ -65,15 +84,15 @@ interface InputItem {
 }
 /** Wire shape for an LLM-identified param echoed back to the server. */
 interface IdentifiedParam {
-    type: string;
-    value: string;
+    parameter: string;
+    text: string;
 }
 /**
  * Wire shape for a recently-suggested hint entry: a suggestion that was on
  * screen when the user started typing the current unresolved trailing text.
  */
 interface RecentlySuggested {
-    type: string;
+    parameter: string;
     text: string;
 }
 interface AutocompleteRequest {
@@ -92,6 +111,8 @@ interface AutocompleteRequest {
         client_version: string;
         session_id: string;
         source?: "full-sdk" | "headless-sdk";
+        /** The wire format this SDK speaks ({@link SCHEMA_VERSION}). */
+        schema_version: string;
     };
 }
 interface AutocompleteResponse {
@@ -111,6 +132,8 @@ interface AutocompleteResponse {
         request_at: string;
         /** The server's funnel-telemetry switch. Absent means off: send no funnel events. */
         funnel_telemetry?: boolean;
+        /** The request's `schema_version`, echoed back. */
+        schema_version?: string;
     };
 }
 /** Comparison an {@link ExpressedFilter} applies to its value. */
@@ -120,7 +143,7 @@ type FilterOp = "eq" | "ne" | "lt" | "lte" | "gt" | "gte";
  * how the two compare ("price", "100", "lt").
  */
 interface ExpressedFilter {
-    param: string;
+    parameter: string;
     value: string;
     op: FilterOp;
 }
@@ -213,8 +236,13 @@ interface CompletedParamState extends CompletedParam {
     text: string;
     /** The originating option's `value` (see {@link SuggestionOption.value}), carried over so `toWireParam` can send it instead of the shortened `text`. */
     value?: string;
-    /** Source suggestion's `type` — used by re-edit mode to render the dropdown pill. */
-    suggestionType: string;
+    /** Source suggestion's `parameter` — used by re-edit mode to render the dropdown pill. */
+    suggestionParameter: string;
+    /**
+     * Source suggestion's `type` (its value type), carried so re-edit opens the
+     * same picker the first pick did — see {@link Suggestion.type}.
+     */
+    suggestionValueType?: SuggestionType;
     /** Source suggestion's `text` — used by re-edit mode to render the dropdown pill. */
     suggestionPlaceholder: string;
     /** Cached options from the suggestion that produced this param — re-edit shows these. */
@@ -253,8 +281,8 @@ interface CompletedParamState extends CompletedParam {
  */
 interface SkippedParamState {
     id: string;
-    /** The skipped suggestion's `type` (e.g. "goal"). */
-    type: string;
+    /** The skipped suggestion's `parameter` (e.g. "goal"). */
+    parameter: string;
     /** The suggestion's display text at skip time. Introspection only — never sent. */
     suggestionPlaceholder: string;
 }
@@ -265,7 +293,7 @@ interface SkippedParamState {
  */
 interface IdentifiedParamState {
     id: string;
-    type: string;
+    parameter: string;
     text: string;
 }
 type Segment = {
@@ -580,12 +608,15 @@ declare function isCalendarFormat(format: FormatType): boolean;
  * them. A parameter called `travel_date` whose options are all spans is a span
  * parameter, whatever its name says.
  *
- * Accepts anything with a `type`, not a `Suggestion`, so re-edit can ask the
- * same question about a completed param via its `suggestionType`.
+ * Accepts anything with a `parameter`, not a `Suggestion`, so re-edit can ask
+ * the same question about a completed param via its `suggestionParameter`.
+ * A suggestion whose `type` names a date or date-range parameter is that,
+ * whatever its options and name say.
  */
 declare function resolveFormatType(source: {
-    type: string;
+    parameter: string;
     options?: SuggestionOption[];
+    type?: SuggestionType;
 } | undefined | null): FormatType;
 
 /**
@@ -654,7 +685,7 @@ interface CoreInputState {
      * owns the pill on screen. Owned by `OptionSourceController`.
      */
     optionSearch: {
-        type: string;
+        parameter: string;
         query: string;
         status: "loading" | "done";
     } | null;
@@ -757,7 +788,7 @@ interface CoreInputState {
     editingIdentified: {
         id: string;
         /** The identified param's type, which the committed param inherits. */
-        type: string;
+        parameter: string;
         /** Plain-text offsets bounding the span being replaced. */
         anchor: number;
         tail: number;
@@ -1269,7 +1300,7 @@ declare class AIAutocomplete {
      * The skipped suggestion is recorded in `skippedParams` so every subsequent
      * request (and the submit result) carries it as a `completed_params` entry
      * with `text: "skipped"` — otherwise the server has no way to know the user
-     * declined it and keeps suggesting the same parameter. Deduped by type: the
+     * declined it and keeps suggesting the same parameter. Deduped by parameter: the
      * same type skipped twice is one entry.
      *
      * When the last pill is removed there are no options left to show, so the
@@ -2127,6 +2158,12 @@ interface Store<S> {
 }
 declare function createStore<S>(initial: S): Store<S>;
 
+/**
+ * The /suggest wire format this SDK speaks, sent as `meta.schema_version` on
+ * every request. The server answers in the same format.
+ */
+declare const SCHEMA_VERSION = "1.0";
+
 /** Base URL for the "AI Autocomplete" branding/attribution link in the dropdown footer. */
 declare const ATTRIBUTION_URL = "https://ai-autocomplete.com";
 /**
@@ -2178,7 +2215,7 @@ declare function getFooterHint(optionHighlighted: boolean, isInputEmpty: boolean
 /**
  * Projects client-side identified-param state onto its wire shape.
  *
- * The one place the `{ type, value }` form is spelled out. Both the request
+ * The one place the `{ parameter, text }` 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.
@@ -2318,4 +2355,4 @@ interface SubmitResultExtras {
  */
 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 CustomFieldsReport, DATE_RANGE_META_END, DATE_RANGE_META_START, DEFAULT_OPTION_COUNT_UNIT, type DateMonthView, type DateRange, type DateSelection, type ExpressedFilter, type FilterOp, type FormatType, type IdentifiedParam, type IdentifiedParamState, type InputItem, type LooseDateOptions, type MatchedItem, type MatchedItems, 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, PRODUCT_PATH_PREFIX, PRODUCT_ROW_PX_PER_LINE, type Product, type ProductImageFallback, type ProductRowMetrics, type ProductRowWheel, type ProductsConfig, type ProductsLayout, RANGE_SEPARATOR, type RecentlySuggested, type RenderMode, SCROLL_ARROW_ATTR, SCROLL_ARROW_BOTTOM_VAR, SCROLL_ARROW_CLASS, SCROLL_ARROW_FADE_MS, SCROLL_ARROW_LABEL, SCROLL_ARROW_SCROLL_IDLE_MS, 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, attachProductRowWheel, attachScrollArrow, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, chipIdFromTap, computeOptionsGridLayout, containScroll, createStore, cursorIsAtEnd, dateCellMarks, dateSelectionFor, extractPlainText, formatAbsoluteDate, formatDate, formatDateRange, formatOptionCount, getCursorOffset, getFooterHint, identifiedParamLabel, isCalendarFormat, isOptionsGridMobileViewport, isoDate, keepCaretOnChip, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionCountLabel, optionEnterDelayMs, optionHasImage, optionImageSrc, optionLabel, optionsEntranceDurationMs, optionsGridTemplateColumns, parseDate, parseLooseDate, parseLooseDateRange, plainTextLength, planOptionsGrid, previousGraphemeBoundary, productFromMatchedItem, productInitial, productRowWheelTarget, productsFromCustomFields, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sameOptionRows, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, toWireIdentifiedParams, visibleDateRange, 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 CustomFieldsReport, DATE_RANGE_META_END, DATE_RANGE_META_START, DEFAULT_OPTION_COUNT_UNIT, type DateMonthView, type DateRange, type DateSelection, type ExpressedFilter, type FilterOp, type FormatType, type IdentifiedParam, type IdentifiedParamState, type InputItem, type LooseDateOptions, type MatchedItem, type MatchedItems, 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, PRODUCT_PATH_PREFIX, PRODUCT_ROW_PX_PER_LINE, type Product, type ProductImageFallback, type ProductRowMetrics, type ProductRowWheel, type ProductsConfig, type ProductsLayout, RANGE_SEPARATOR, type RecentlySuggested, type RenderMode, SCHEMA_VERSION, SCROLL_ARROW_ATTR, SCROLL_ARROW_BOTTOM_VAR, SCROLL_ARROW_CLASS, SCROLL_ARROW_FADE_MS, SCROLL_ARROW_LABEL, SCROLL_ARROW_SCROLL_IDLE_MS, SCROLL_ARROW_VISIBLE_ATTR, SKIPPED_PARAM_TEXT, type ScrollArrowArgs, type ScrollArrowController, type Segment, type SkippedParamState, type Store, type SubmitResultExtras, type Suggestion, type SuggestionOption, type SuggestionType, type TaskKind, WEEKDAY_LABELS, addMonths, attachProductRowWheel, attachScrollArrow, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, chipIdFromTap, computeOptionsGridLayout, containScroll, createStore, cursorIsAtEnd, dateCellMarks, dateSelectionFor, extractPlainText, formatAbsoluteDate, formatDate, formatDateRange, formatOptionCount, getCursorOffset, getFooterHint, identifiedParamLabel, isCalendarFormat, isOptionsGridMobileViewport, isoDate, keepCaretOnChip, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionCountLabel, optionEnterDelayMs, optionHasImage, optionImageSrc, optionLabel, optionsEntranceDurationMs, optionsGridTemplateColumns, parseDate, parseLooseDate, parseLooseDateRange, plainTextLength, planOptionsGrid, previousGraphemeBoundary, productFromMatchedItem, productInitial, productRowWheelTarget, productsFromCustomFields, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sameOptionRows, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, toWireIdentifiedParams, visibleDateRange, withSkippedParams };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 type TaskKind = "automation" | "email" | "insight";
 interface CompletedParam {
     placeholder: string;
-    type: string;
+    parameter: string;
     text?: string;
     kind: TaskKind | null;
 }
@@ -49,15 +49,34 @@ interface SuggestionOption {
     is_tappable: boolean;
     kind: TaskKind | null;
     metadata?: Record<string, unknown>;
+    /**
+     * The parameter a tap on this option answers. The server names it on every
+     * option; options the SDK builds itself (a calendar's dates) carry their
+     * suggestion's.
+     */
+    parameter?: string;
+}
+/**
+ * The value type of a suggestion's parameter — which picker it needs. Present
+ * only for a date or date-range parameter.
+ */
+interface SuggestionType {
+    kind: "string" | "numeric" | "date" | "date_range" | "boolean";
+    /** How a date is written, e.g. "DD/MM/YYYY". */
+    date_format?: string;
+    /** What joins the two dates of a range, e.g. " to ". */
+    separator?: string;
+    unit?: string;
 }
 interface Suggestion {
-    type: string;
+    parameter: string;
     text: string;
     required: boolean;
     options?: SuggestionOption[];
+    type?: SuggestionType;
 }
 interface InputItem {
-    type: string;
+    parameter: string;
     text: string;
     state: "completed" | "in_progress";
     /** Absent or "selected" = echo of client params; "identified" = LLM-inferred. */
@@ -65,15 +84,15 @@ interface InputItem {
 }
 /** Wire shape for an LLM-identified param echoed back to the server. */
 interface IdentifiedParam {
-    type: string;
-    value: string;
+    parameter: string;
+    text: string;
 }
 /**
  * Wire shape for a recently-suggested hint entry: a suggestion that was on
  * screen when the user started typing the current unresolved trailing text.
  */
 interface RecentlySuggested {
-    type: string;
+    parameter: string;
     text: string;
 }
 interface AutocompleteRequest {
@@ -92,6 +111,8 @@ interface AutocompleteRequest {
         client_version: string;
         session_id: string;
         source?: "full-sdk" | "headless-sdk";
+        /** The wire format this SDK speaks ({@link SCHEMA_VERSION}). */
+        schema_version: string;
     };
 }
 interface AutocompleteResponse {
@@ -111,6 +132,8 @@ interface AutocompleteResponse {
         request_at: string;
         /** The server's funnel-telemetry switch. Absent means off: send no funnel events. */
         funnel_telemetry?: boolean;
+        /** The request's `schema_version`, echoed back. */
+        schema_version?: string;
     };
 }
 /** Comparison an {@link ExpressedFilter} applies to its value. */
@@ -120,7 +143,7 @@ type FilterOp = "eq" | "ne" | "lt" | "lte" | "gt" | "gte";
  * how the two compare ("price", "100", "lt").
  */
 interface ExpressedFilter {
-    param: string;
+    parameter: string;
     value: string;
     op: FilterOp;
 }
@@ -213,8 +236,13 @@ interface CompletedParamState extends CompletedParam {
     text: string;
     /** The originating option's `value` (see {@link SuggestionOption.value}), carried over so `toWireParam` can send it instead of the shortened `text`. */
     value?: string;
-    /** Source suggestion's `type` — used by re-edit mode to render the dropdown pill. */
-    suggestionType: string;
+    /** Source suggestion's `parameter` — used by re-edit mode to render the dropdown pill. */
+    suggestionParameter: string;
+    /**
+     * Source suggestion's `type` (its value type), carried so re-edit opens the
+     * same picker the first pick did — see {@link Suggestion.type}.
+     */
+    suggestionValueType?: SuggestionType;
     /** Source suggestion's `text` — used by re-edit mode to render the dropdown pill. */
     suggestionPlaceholder: string;
     /** Cached options from the suggestion that produced this param — re-edit shows these. */
@@ -253,8 +281,8 @@ interface CompletedParamState extends CompletedParam {
  */
 interface SkippedParamState {
     id: string;
-    /** The skipped suggestion's `type` (e.g. "goal"). */
-    type: string;
+    /** The skipped suggestion's `parameter` (e.g. "goal"). */
+    parameter: string;
     /** The suggestion's display text at skip time. Introspection only — never sent. */
     suggestionPlaceholder: string;
 }
@@ -265,7 +293,7 @@ interface SkippedParamState {
  */
 interface IdentifiedParamState {
     id: string;
-    type: string;
+    parameter: string;
     text: string;
 }
 type Segment = {
@@ -580,12 +608,15 @@ declare function isCalendarFormat(format: FormatType): boolean;
  * them. A parameter called `travel_date` whose options are all spans is a span
  * parameter, whatever its name says.
  *
- * Accepts anything with a `type`, not a `Suggestion`, so re-edit can ask the
- * same question about a completed param via its `suggestionType`.
+ * Accepts anything with a `parameter`, not a `Suggestion`, so re-edit can ask
+ * the same question about a completed param via its `suggestionParameter`.
+ * A suggestion whose `type` names a date or date-range parameter is that,
+ * whatever its options and name say.
  */
 declare function resolveFormatType(source: {
-    type: string;
+    parameter: string;
     options?: SuggestionOption[];
+    type?: SuggestionType;
 } | undefined | null): FormatType;
 
 /**
@@ -654,7 +685,7 @@ interface CoreInputState {
      * owns the pill on screen. Owned by `OptionSourceController`.
      */
     optionSearch: {
-        type: string;
+        parameter: string;
         query: string;
         status: "loading" | "done";
     } | null;
@@ -757,7 +788,7 @@ interface CoreInputState {
     editingIdentified: {
         id: string;
         /** The identified param's type, which the committed param inherits. */
-        type: string;
+        parameter: string;
         /** Plain-text offsets bounding the span being replaced. */
         anchor: number;
         tail: number;
@@ -1269,7 +1300,7 @@ declare class AIAutocomplete {
      * The skipped suggestion is recorded in `skippedParams` so every subsequent
      * request (and the submit result) carries it as a `completed_params` entry
      * with `text: "skipped"` — otherwise the server has no way to know the user
-     * declined it and keeps suggesting the same parameter. Deduped by type: the
+     * declined it and keeps suggesting the same parameter. Deduped by parameter: the
      * same type skipped twice is one entry.
      *
      * When the last pill is removed there are no options left to show, so the
@@ -2127,6 +2158,12 @@ interface Store<S> {
 }
 declare function createStore<S>(initial: S): Store<S>;
 
+/**
+ * The /suggest wire format this SDK speaks, sent as `meta.schema_version` on
+ * every request. The server answers in the same format.
+ */
+declare const SCHEMA_VERSION = "1.0";
+
 /** Base URL for the "AI Autocomplete" branding/attribution link in the dropdown footer. */
 declare const ATTRIBUTION_URL = "https://ai-autocomplete.com";
 /**
@@ -2178,7 +2215,7 @@ declare function getFooterHint(optionHighlighted: boolean, isInputEmpty: boolean
 /**
  * Projects client-side identified-param state onto its wire shape.
  *
- * The one place the `{ type, value }` form is spelled out. Both the request
+ * The one place the `{ parameter, text }` 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.
@@ -2318,4 +2355,4 @@ interface SubmitResultExtras {
  */
 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 CustomFieldsReport, DATE_RANGE_META_END, DATE_RANGE_META_START, DEFAULT_OPTION_COUNT_UNIT, type DateMonthView, type DateRange, type DateSelection, type ExpressedFilter, type FilterOp, type FormatType, type IdentifiedParam, type IdentifiedParamState, type InputItem, type LooseDateOptions, type MatchedItem, type MatchedItems, 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, PRODUCT_PATH_PREFIX, PRODUCT_ROW_PX_PER_LINE, type Product, type ProductImageFallback, type ProductRowMetrics, type ProductRowWheel, type ProductsConfig, type ProductsLayout, RANGE_SEPARATOR, type RecentlySuggested, type RenderMode, SCROLL_ARROW_ATTR, SCROLL_ARROW_BOTTOM_VAR, SCROLL_ARROW_CLASS, SCROLL_ARROW_FADE_MS, SCROLL_ARROW_LABEL, SCROLL_ARROW_SCROLL_IDLE_MS, 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, attachProductRowWheel, attachScrollArrow, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, chipIdFromTap, computeOptionsGridLayout, containScroll, createStore, cursorIsAtEnd, dateCellMarks, dateSelectionFor, extractPlainText, formatAbsoluteDate, formatDate, formatDateRange, formatOptionCount, getCursorOffset, getFooterHint, identifiedParamLabel, isCalendarFormat, isOptionsGridMobileViewport, isoDate, keepCaretOnChip, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionCountLabel, optionEnterDelayMs, optionHasImage, optionImageSrc, optionLabel, optionsEntranceDurationMs, optionsGridTemplateColumns, parseDate, parseLooseDate, parseLooseDateRange, plainTextLength, planOptionsGrid, previousGraphemeBoundary, productFromMatchedItem, productInitial, productRowWheelTarget, productsFromCustomFields, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sameOptionRows, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, toWireIdentifiedParams, visibleDateRange, 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 CustomFieldsReport, DATE_RANGE_META_END, DATE_RANGE_META_START, DEFAULT_OPTION_COUNT_UNIT, type DateMonthView, type DateRange, type DateSelection, type ExpressedFilter, type FilterOp, type FormatType, type IdentifiedParam, type IdentifiedParamState, type InputItem, type LooseDateOptions, type MatchedItem, type MatchedItems, 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, PRODUCT_PATH_PREFIX, PRODUCT_ROW_PX_PER_LINE, type Product, type ProductImageFallback, type ProductRowMetrics, type ProductRowWheel, type ProductsConfig, type ProductsLayout, RANGE_SEPARATOR, type RecentlySuggested, type RenderMode, SCHEMA_VERSION, SCROLL_ARROW_ATTR, SCROLL_ARROW_BOTTOM_VAR, SCROLL_ARROW_CLASS, SCROLL_ARROW_FADE_MS, SCROLL_ARROW_LABEL, SCROLL_ARROW_SCROLL_IDLE_MS, SCROLL_ARROW_VISIBLE_ATTR, SKIPPED_PARAM_TEXT, type ScrollArrowArgs, type ScrollArrowController, type Segment, type SkippedParamState, type Store, type SubmitResultExtras, type Suggestion, type SuggestionOption, type SuggestionType, type TaskKind, WEEKDAY_LABELS, addMonths, attachProductRowWheel, attachScrollArrow, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, chipIdFromTap, computeOptionsGridLayout, containScroll, createStore, cursorIsAtEnd, dateCellMarks, dateSelectionFor, extractPlainText, formatAbsoluteDate, formatDate, formatDateRange, formatOptionCount, getCursorOffset, getFooterHint, identifiedParamLabel, isCalendarFormat, isOptionsGridMobileViewport, isoDate, keepCaretOnChip, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionCountLabel, optionEnterDelayMs, optionHasImage, optionImageSrc, optionLabel, optionsEntranceDurationMs, optionsGridTemplateColumns, parseDate, parseLooseDate, parseLooseDateRange, plainTextLength, planOptionsGrid, previousGraphemeBoundary, productFromMatchedItem, productInitial, productRowWheelTarget, productsFromCustomFields, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sameOptionRows, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, toWireIdentifiedParams, visibleDateRange, withSkippedParams };