@magicx-eng/ai-autocomplete-vanilla 0.14.0 → 0.16.0

package/README.md

@@ -14,16 +14,17 @@ A framework-agnostic vanilla JS/TypeScript library that provides a guided AI-pow
 - **Access token auth** — short-lived tokens with automatic refresh, single-flight deduplication, and 401 retry
 - **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 as `MONTH DAY YEAR` (e.g. `March 23 2026`). Tapping a committed date re-opens the calendar on the month it holds.
+- **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
 - **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`
 - **IME-safe** — composition events are buffered so input text is committed once, after composition ends
-- **Animations** — option selection streak animation, text shimmer on newly added params
-- **Loading skeleton** — while a fetch is in flight, the dropdown and inline pills keep the previous layout (same count and widths) with their text masked and a shimmer pulse. The skeleton is held back until the selection streak animation finishes, so taps don't visually "stutter" into loading.
+- **Animations** — option press (the picked option compresses while the rest step back), text shimmer on newly added params
+- **Loading skeleton** — while a fetch is in flight, the dropdown and inline pills keep the previous layout (same count and widths) with their text masked and a shimmer pulse. The skeleton is held back until the option-press animation finishes, so taps don't visually "stutter" into loading.
 - **Lightweight** — ~10 KB gzipped, styles auto-injected at runtime
 - **TypeScript first** — full type definitions shipped with the package
+- **Shadow-DOM ready** — mount the container inside a shadow root and the styles and caret follow it there, with nothing to configure; page CSS can't reach the widget
 - **SSR-safe** — no top-level `document`/`window` access
 
 ## Installation
@@ -81,7 +82,7 @@ const ac = new AIAutocomplete(container, {
   // Appearance
   mode: "auto",               // "light" | "dark" | "auto"
   optionsPosition: "below",   // "above" | "below"
-  animations: true,            // enable streak + shimmer
+  animations: true,            // press, shimmer, typed placeholder, staggered options, scroll arrow
   pillPlacement: "dropdown",   // "inline" | "dropdown" | "hidden"
   dropdownTrigger: "auto",   // "auto" | "manual" | "hidden"
   closeDropdownOnBlur: true, // false = keep dropdown open even when input loses focus
@@ -91,6 +92,11 @@ const ac = new AIAutocomplete(container, {
   // Focus
   autoFocus: true,           // focus the input on mount (Tier 1 only)
 
+  // Where the stylesheet is injected. Defaults to the container's own root —
+  // the document, or the shadow root when the widget is mounted in one — so
+  // this is only for sending the styles somewhere else. See "Shadow DOM".
+  styleRoot: undefined,
+
   // Product strip (opt-in). Omit it and nothing changes: no request, no markup.
   products: {
     fetch: (query, signal) => myPlatform.search(query, { signal }),
@@ -287,13 +293,24 @@ the calendar for you; in Tier 3 the same data reaches your own renderer (see
 | Month arrows | Page the calendar. Paging never commits anything |
 | <kbd>→</kbd> at the end of the input | Skips the parameter, same as any other pill |
 
-**The committed value** is always `MONTH DAY YEAR` in English — `March 23 2026`
-— regardless of the visitor's locale, so the value you receive has one shape
-everywhere. It arrives as an ordinary completed parameter: bold in the input,
+**The committed value** is written the way a person would write it, always in
+English regardless of the visitor's locale, so the value you receive has one
+vocabulary everywhere:
+
+- a date inside the next week (today included) commits as its weekday name —
+  `Tuesday`. Like the sentence it sits in, that name is relative: read later,
+  it means the next such day;
+- one further out in the current year as `MONTH DAY` — `March 23`;
+- one in another year as `MONTH DAY YEAR` — `March 23 2027`.
+
+It arrives as an ordinary completed parameter: bold in the input,
 and present in `completed_params` on submit like any other answer.
 
-**Re-editing** a committed date re-opens the calendar on that date's month with
-the day marked, so changing an answer takes one click.
+**Re-editing** a committed date re-opens the calendar on the month the committed
+text names, with that day marked, so changing an answer takes one click. For a
+weekday name that reading is relative, so once the day it named has gone by,
+re-editing marks the next such day rather than the one originally picked — the
+calendar shows what the sentence says today, which is also what gets submitted.
 
 **Reading the value back.** The date arrives as text, so if you need a `Date`
 object, `parseDate` is exported for it:
@@ -301,7 +318,9 @@ object, `parseDate` is exported for it:
 ```ts
 import { parseDate } from "@magicx-eng/ai-autocomplete-vanilla";
 
-const due = parseDate("March 23 2026"); // Date, or null if the text isn't one of ours
+// Reads all three committed shapes: a weekday name is the one date it can
+// mean in the next seven days, and a yearless month-day is the current year.
+const due = parseDate("March 23"); // Date, or null if the text isn't one of ours
 ```
 
 `parseLooseDate` is exported too, for the looser shapes a person types into a
@@ -362,6 +381,8 @@ The [product strip](#product-strip) works here too: pass `products` / `onProduct
 
 > Focus/blur wiring is required when `dropdownTrigger` is `"auto"` (the default) — the dropdown only opens while the input is focused. Without `setFocused()`, the dropdown will never open.
 
+If your input is a scrollable `contenteditable` rather than the `<input>` above, see [Keeping the caret visible](#keeping-the-caret-visible) — placing the caret is yours to do in this mode, and so is scrolling to it.
+
 ---
 
 ## Tier 3: Headless
@@ -412,7 +433,7 @@ unsub();
 > **Custom (rich-text) editors:** the wiring above assumes `myInput` is a `<textarea>`/`<input>`, whose caret the library reads directly. If you're driving a contentEditable or rich-text editor instead, also call `ac.handleCaretMove(offset)` on selection changes (with the caret as a plain-text offset) so arrow keys can move from the input into the dropdown.
 
 
-> **Datepicker in a custom UI.** For a date parameter, `state.activeFormatType` is `"date"` and `state.filteredOptions` holds that month's day cells. Each cell's `text` is the date it commits (`"March 23 2026"`), so rendering them as a plain list already works — `selectOption(cell)` behaves exactly as it does for an option. To draw an actual calendar, read `state.dateView` for the month on show, `cellDay(cell)` for the number to paint, and call `showPreviousMonth()` / `showNextMonth()` to page. Cells that pad the start and end of the month have `is_tappable: false`.
+> **Datepicker in a custom UI.** For a date parameter, `state.activeFormatType` is `"date"` and `state.filteredOptions` holds that month's day cells. Each cell's `text` is the date it commits (`"March 23"`, or `"Tuesday"` inside the next week), so rendering them as a plain list already works — `selectOption(cell)` behaves exactly as it does for an option. To draw an actual calendar, read `state.dateView` for the month on show, `cellDay(cell)` for the number to paint, and call `showPreviousMonth()` / `showNextMonth()` to page. Cells that pad the start and end of the month have `is_tappable: false`.
 ### State shape (`CoreState`)
 
 | Field | Type | Description |
@@ -421,7 +442,7 @@ unsub();
 | `completedParams` | `CompletedParamState[]` | Filled parameters |
 | `suggestions` | `Suggestion[]` | All suggestions from server (including placeholder type) |
 | `actionableSuggestions` | `Suggestion[]` | Non-placeholder suggestions (the pills) |
-| `filteredOptions` | `SuggestionOption[]` | Options for the active suggestion, filtered by current query. For a date parameter these are the visible month's day cells instead — each cell's `text` is the date it commits (`"March 23 2026"`), and cells padding the start/end of the month have `is_tappable: false`. |
+| `filteredOptions` | `SuggestionOption[]` | Options for the active suggestion, filtered by current query. For a date parameter these are the visible month's day cells instead — each cell's `text` is the date it commits (`"March 23"`, or `"Tuesday"` inside the next week), and cells padding the start/end of the month have `is_tappable: false`. |
 | `activeFormatType` | `"options" \| "date"` | How the active parameter is answered: pick an option, or pick a date. `"date"` shows a calendar instead of the option list. Typing does not filter it — the text is treated as a new query. |
 | `dateView` | `DateMonthView \| null` | The month the calendar is showing (`{ year, month }`, 0-based month). Null unless `activeFormatType` is `"date"`. |
 | `segments` | `Segment[]` | Input text split into typed text vs completed params — completed segments render as bold `<strong>` runs inside the editor |
@@ -430,7 +451,7 @@ 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`. |
-| `inSelectionAnimation` | `boolean` | True for the 500 ms after a user-initiated option tap so the streak animation can finish before the dropdown switches to the loading skeleton. |
+| `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`. |
 | `isReady` | `boolean` | Server indicates query is complete |
@@ -470,6 +491,30 @@ The pattern for any framework:
 4. Forward user events (input, keydown, click) → core actions
 5. Destroy on unmount
 
+### Keeping the caret visible
+
+Tier 1 handles this for you. In Tiers 2 and 3 you own the editor, so if you
+render your own `contenteditable` that can scroll — held to one line with
+`overflow-x`, or capped in height — call `scrollCaretIntoView` after you move
+the caret yourself:
+
+```ts
+import { scrollCaretIntoView } from "@magicx-eng/ai-autocomplete-vanilla";
+
+// ...right after placing the caret
+scrollCaretIntoView(editorElement);
+```
+
+A browser scrolls an editor to the caret while the user types, but not when the
+caret is moved by script — so answering a parameter can otherwise leave the
+caret, and everything typed next, outside the visible box.
+
+It scrolls only the nearest scrollable box around the element you pass, and
+never the page. It is a no-op when nothing overflows, when the caret is already
+visible, and when the caret is not inside the element you pass — which includes
+a plain `<input>` or `<textarea>`, whose caret the document selection cannot
+reach. Those are the browser's to scroll, not this helper's.
+
 ---
 
 ## API Reference
@@ -554,6 +599,25 @@ Constructor callbacks (`onSubmit`, `onChange`, etc.) are registered once at cons
 
 Styles are auto-injected at runtime (Tier 1 and Tier 2). No CSS import needed. The component ships built-in light and dark defaults.
 
+### Shadow DOM
+
+Mount the container inside a shadow root and the widget works there — the stylesheet is injected into that root rather than `document.head`, and the caret is read from the root that owns the editor:
+
+```js
+const host = document.querySelector("#autocomplete-host");
+const root = host.attachShadow({ mode: "open" });
+const container = document.createElement("div");
+root.appendChild(container);
+
+const ac = new AIAutocomplete(container, { apiConfig: { apiKey: "..." } });
+```
+
+Nothing to configure: the root is derived from the container. Light-DOM mounts are unaffected, and a page can hold both — each root gets the stylesheet.
+
+This is the way to embed the widget in a page whose CSS you don't control. In the light DOM every page rule reaches the widget, and the ones that reach it by element (`footer`, `kbd`, `a`) or with `!important` win over the SDK's own classes. A shadow root ends that: page rules stop at the boundary. Note that the same boundary stops **your** page CSS too, so the [selector hooks](#selector-hooks) below have to be applied from inside the shadow root (or through the `--aia-*` variables, which inherit across it — set them on the host).
+
+`styleRoot` overrides where the styles land, for the rare mount whose container root isn't where they should go. It's applied once, at construction.
+
 ### CSS Variables
 
 Override these on the container element. All built-in defaults use `:where()` (zero specificity) — your overrides always win without `!important`.
@@ -582,13 +646,17 @@ Override these on the container element. All built-in defaults use `:where()` (z
 | `--aia-footer-chip-bg` | `--aia-surface` at 65% | `--aia-surface` at 65% | Fill behind the footer's keyboard hint and AI-Autocomplete badge. The option list scrolls under the footer, so this keeps both legible over the row passing behind them. `transparent` on the glass surface. |
 | `--aia-dropdown-bg` | — | — | Optional bg color the dropdown's "glass" rim shadow tints toward. Set this to the page background behind the dropdown so the bottom-corner glow blends seamlessly. |
 | `--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-streak-rgb` | `99, 102, 241` | `255, 255, 255` | Comma-separated RGB triplet tinting the datepicker's pressed cell, and its selected cell when `--aia-date-selected-bg` is unset. The today ring uses `--aia-date-today-ring`, not this. |
 | `--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-scroll-arrow-bg` | `--aia-surface` | `--aia-surface` | Fill of the "more below" arrow — the round button that rises at the bottom of the option list while there is more to scroll to. |
+| `--aia-scroll-arrow-color` | `--aia-option-color` | `--aia-option-color` | Chevron color of the arrow (`--aia-scroll-arrow-color-hover` on hover). |
+| `--aia-scroll-arrow-border` | `--aia-dropdown-border` | `--aia-dropdown-border` | Hairline around the arrow. |
+| `--aia-scroll-arrow-shadow` | `0 2px 8px rgba(0,0,0,0.12)` | `0 2px 8px rgba(0,0,0,0.12)` | Elevation of the arrow. |
+| `--aia-placeholder-fade` | `120ms` | `120ms` | Fade-out of the outgoing placeholder phrase when the starting-state placeholder changes (the incoming one types itself in). |
 | `--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. |
@@ -599,9 +667,10 @@ Override these on the container element. All built-in defaults use `:where()` (z
 | `--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-date-cell-size` | `36px` | `36px` | Size of a day's square — the box that carries the highlight, the today ring and the selected fill. |
-| `--aia-date-row-height` | `40px` | `40px` | Height of one week row. Lower it to fit a 6-week month in a shorter dropdown. |
-| `--aia-date-cell-font-size` | `14px` | `14px` | Day-number font size. |
+| `--aia-date-panel-width` | `312px` | `312px` | Max width of the whole dropdown panel while the calendar is up — the panel narrows to calendar size. |
+| `--aia-date-cell-size` | `26px` | `26px` | Size of a day's square — the box that carries the highlight, the today ring and the selected fill. |
+| `--aia-date-row-height` | `28px` | `28px` | Height of one week row. Lower it to fit a 6-week month in a shorter dropdown. |
+| `--aia-date-cell-font-size` | `13px` | `13px` | Day-number font size. |
 | `--aia-date-month-font-size` | `14px` | `14px` | Font size of the "March 2026" header. |
 | `--aia-date-weekday-font-size` | `11px` | `11px` | Font size of the S/M/T/W/T/F/S column letters. |
 | `--aia-date-today-ring` | `--aia-option-color` | `--aia-option-color` | Outline drawn around today's date. |
@@ -641,6 +710,7 @@ For styling beyond the CSS variables, target these stable `data-aia-*` attribute
 | `[data-aia-pill-scroll]` | Scrollable pill region inside the bar — carries the horizontal scroll and right-edge fade mask |
 | `[data-aia-skip]` | The pill bar's trailing "skip" button. Tune via `--aia-skip-font-size` / `--aia-skip-color` / `--aia-skip-color-hover` / `--aia-skip-hover-bg` |
 | `[data-aia-option]` | Each suggestion option |
+| `[data-aia-scroll-arrow]` | The "more below" arrow on the dropdown — carries `data-aia-visible` while shown |
 | `[data-aia-dropdown]` | The dropdown root (listbox). Carries `data-aia-has-products` while the product strip has cards. |
 | `[data-aia-datepicker]` | The calendar, rendered in place of the option list for a date parameter |
 | `[data-aia-date-month]` | The "March 2026" header label |

package/dist/index.d.mts

@@ -229,12 +229,35 @@ declare const WEEKDAY_LABELS: string[];
  * Greenwich would produce `2026-03-22`.
  */
 declare function isoDate(d: Date): string;
-/** The committed form of a date: "March 23 2026". */
+/**
+ * The committed form of a date — written the way a person would, since the
+ * text lands verbatim in the user's own sentence:
+ *
+ *  - today through six days out: the weekday alone, "Tuesday". The window
+ *    stops before day seven so every weekday name still means exactly one
+ *    date when read back.
+ *  - further out, same year: "March 23" — the year restates what "this year"
+ *    already says.
+ *  - a different year: "March 23 2027".
+ */
 declare function formatDate(d: Date): string;
 /**
  * Inverse of {@link formatDate}, for re-opening the calendar on the month a
- * completed date param already holds. Returns null for anything else — the
- * caller falls back to the current month.
+ * completed date param already holds. Reads all three committed shapes — a
+ * weekday name resolves to its one date in the next seven days, and a
+ * yearless month-day to the current year, mirroring how they were written.
+ * Returns null for anything else — the caller falls back to the current
+ * month.
+ *
+ * Deliberately RELATIVE, like the sentence it reads: the committed text is
+ * the single source of truth, and "Schedule a campaign Tuesday" means the
+ * next Tuesday to everyone who reads it — the user re-reading their own
+ * sentence, this parser, and the server parsing the submitted query alike.
+ * So once the originally-picked Tuesday has gone by, re-editing marks the
+ * date the sentence NOW names, a week later — not the stale pick. Anchoring
+ * to the pick would make the calendar disagree with the sentence above it
+ * (and with what the server will act on), which is the worse wrong. Pinned
+ * by the clock-advance test in datepicker.test.ts.
  */
 declare function parseDate(text: string | undefined | null): Date | null;
 /** "March 2026" — the calendar header. */
@@ -253,11 +276,15 @@ declare function addMonths(view: DateMonthView, delta: number): DateMonthView;
  * the grid's own column-major traversal already *is* calendar navigation
  * (→ = +1 day, ↓ = +7 days).
  *
- * Each day cell's `text` is the committed value ("March 23 2026"), NOT its
- * label: `computeSelectionPatch` commits `option.text` verbatim, so the value
- * has to live there. The renderer reads `metadata.aiaDay` for the "23" it
- * paints. Padding cells are non-tappable, which is what stops arrow navigation
+ * Each day cell's `text` is the committed value ("March 23", or "Tuesday"
+ * inside the next week — see {@link formatDate}), NOT its label:
+ * `computeSelectionPatch` commits `option.text` verbatim, so the value has to
+ * live there. The renderer reads `metadata.aiaDay` for the "23" it paints. Padding cells are non-tappable, which is what stops arrow navigation
  * from landing on them.
+ *
+ * Days before today stay tappable — the calendar de-emphasizes the past, it
+ * does not forbid it. The renderers compare each cell's ISO date against
+ * today's and paint past days dimmed; picking one still commits normally.
  */
 declare function buildDateOptions(view: DateMonthView): SuggestionOption[];
 /**
@@ -366,7 +393,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 streak
+     * True for ~500ms 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.
      */
@@ -503,6 +530,15 @@ interface CoreOptions {
     showSkipButton?: boolean;
     /** Render mode. Default: "full". */
     renderMode?: RenderMode;
+    /**
+     * Where the SDK's stylesheet is injected. Defaults to the root the container
+     * is mounted in — the document, or the shadow root when the widget is inside
+     * one — so mounting into a shadow root is styled correctly with no
+     * configuration. Set this only when the styles need to land somewhere else
+     * than the container's own root. Applied once at construction; ignored by
+     * `update()`, and by `renderMode: "headless"`, which injects no styles.
+     */
+    styleRoot?: Document | ShadowRoot;
     /**
      * Identifies which SDK surface is in use, for telemetry only. The hook can't
      * distinguish on its own — the Tier 1 component sets "full-sdk" when wiring
@@ -563,7 +599,7 @@ type AIAutocompleteEvents = {
     blur: [];
     productSelect: [product: Product];
 };
-type CoreUpdateOptions = Partial<Omit<CoreOptions, "onSubmit" | "onError" | "onChange" | "onParamsChange" | "onStateChange" | "onFocus" | "onBlur" | "onProductSelect">>;
+type CoreUpdateOptions = Partial<Omit<CoreOptions, "onSubmit" | "onError" | "onChange" | "onParamsChange" | "onStateChange" | "onFocus" | "onBlur" | "onProductSelect" | "styleRoot">>;
 declare class AIAutocomplete {
     private inputStore;
     private store;
@@ -891,6 +927,49 @@ declare function resolveIdentifiedDate(param: {
     isoDate?: unknown;
 }, opts?: LooseDateOptions): string | null;
 
+/**
+ * Entrance choreography for the dropdown's option rows.
+ *
+ * When a new set of options lands, each row fades in while rising into place,
+ * and the rows start one after another from the input's side outward — the
+ * row nearest the input first. The reference (the RB2B support box's
+ * suggestion bubbles, 2026-08-19): opacity 0→1 over ~150 ms, a ~16 px rise
+ * easing out over ~280 ms, consecutive rows ~80–110 ms apart.
+ *
+ * The per-row motion is CSS (the option rule in each package's stylesheet —
+ * keep the three copies identical; the parity test compares them). This module
+ * owns the *timing numbers* and the per-row delay, so vanilla, React and
+ * Angular can't drift onto three different cascades. `OPTION_ENTER_RISE_MS` and
+ * `OPTION_ENTER_FADE_MS` must match the durations declared in those rules.
+ */
+/** Gap between consecutive rows starting their entrance. */
+declare const OPTION_ENTER_STAGGER_MS = 80;
+/** Duration of a row's opacity fade — mirrors the stylesheets' entrance rule. */
+declare const OPTION_ENTER_FADE_MS = 150;
+/** Duration of a row's rise into place — mirrors the stylesheets' entrance rule. */
+declare const OPTION_ENTER_RISE_MS = 280;
+/** Distance a row rises from, in CSS px — mirrors the stylesheets' entrance rule. */
+declare const OPTION_ENTER_RISE_PX = 16;
+/** Inline custom property each option carries with its own start delay. */
+declare const OPTION_ENTER_DELAY_VAR = "--aia-option-enter-delay";
+/**
+ * Start delay (ms) for the option at `index` in a grid of `count` options laid
+ * out in `cols` columns, when the dropdown sits `optionsPosition` the input.
+ *
+ * Rows, not cells, are the unit: the cells of one row share a start so a
+ * two-column layout reads as rows appearing, not as a zig-zag. "below" starts
+ * at the top row (the one against the input); "above" starts at the bottom row
+ * for the same reason — the stack is reversed there and the last row is the
+ * one nearest the input.
+ */
+declare function optionEnterDelayMs(index: number, cols: number, count: number, optionsPosition?: "above" | "below"): number;
+/**
+ * How long after the options render until the last row has settled — the
+ * moment anything that measures the grid (the scroll arrow) can trust its
+ * geometry again, since a row mid-rise still extends the scrollable area.
+ */
+declare function optionsEntranceDurationMs(count: number, cols: number): number;
+
 /**
  * Rows/columns policy for the dropdown's options grid.
  *
@@ -912,11 +991,61 @@ interface OptionsGridLayout {
 }
 /**
  * - Mobile: one column, five rows visible (scroll past five).
- * - Web: one column, four rows visible by default — but when there are exactly
- *   five or six options, two balanced columns (so 5/6 fit without scrolling).
- *   Columns fill row-major, so the two columns end up 3/2 (five) or 3/3 (six).
+ * - Web: one column, four rows visible (scroll past four).
+ *
+ * This is the measurement-free baseline (and the only layout mobile ever
+ * uses). On web, `planOptionsGrid` upgrades five-plus options to two columns
+ * when the rendered rows prove they fit — the upgrade needs the DOM, so it
+ * can't live here.
  */
 declare function computeOptionsGridLayout(count: number, isMobile: boolean): OptionsGridLayout;
+interface OptionsGridPlan extends OptionsGridLayout {
+    /**
+     * Value for `grid-template-columns`. Tracks carry no inner spaces (the
+     * keyboard controller counts tracks by splitting on spaces).
+     */
+    template: string;
+    /**
+     * Indices of the options on the last visible row of a scrollable web grid —
+     * their text gets the fade that signals more options below. Empty on mobile
+     * and whenever everything is already visible.
+     */
+    scrollHintIndices: number[];
+}
+/**
+ * Whether measuring the rendered rows could change the plan at all. Measuring
+ * clones every row and forces a layout, and renders happen per keystroke —
+ * so the callers skip it whenever `planOptionsGrid` would ignore the result
+ * anyway (mobile, or fewer options than the two-column minimum).
+ */
+declare function needsOptionsGridMeasurement(count: number, isMobile: boolean): boolean;
+/**
+ * The full layout decision, measurements included.
+ *
+ * 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.
+ *
+ * `rowWidths` are single-line pixel widths of the rendered rows (see
+ * `measureOptionsGrid`); `gridWidth` is the grid's content width.
+ */
+declare function planOptionsGrid(count: number, isMobile: boolean, rowWidths: number[] | null, gridWidth: number | null): OptionsGridPlan;
+/**
+ * Measure the rendered option rows for `planOptionsGrid`: each row's
+ * single-line width (a hidden `max-content` + `nowrap` clone, so real classes,
+ * fonts, icons, tags and padding are all in the number), and the width the
+ * columns have to share — the grid's content box less its column gap.
+ * Returns null when there's nothing to measure.
+ */
+declare function measureOptionsGrid(grid: HTMLElement): {
+    rowWidths: number[];
+    gridWidth: number;
+} | null;
 /**
  * `grid-template-columns` for a fixed column count. Space-separated
  * `minmax(0,1fr)` tracks (no `repeat()`, no inner spaces) so rows fill
@@ -952,6 +1081,10 @@ declare function getCursorOffset(root: HTMLElement): number | null;
  * with no following text node, we use `setStartAfter(strong)` so the caret
  * sits OUTSIDE the bold subtree — otherwise a caret at the end of a strong's
  * text is still "inside" the strong, which would falsely trigger re-edit mode.
+ *
+ * Also scrolls the caret back into view (see `scrollCaretIntoView`) — this is
+ * the single caret-placement choke point, and a scripted caret move does not
+ * get the browser's own scroll-to-caret behaviour.
  */
 declare function setCursorOffset(root: HTMLElement, offset: number): void;
 /**
@@ -966,6 +1099,66 @@ declare function cursorIsAtEnd(root: HTMLElement): boolean;
  */
 declare function previousGraphemeBoundary(text: string, offset: number): number;
 
+/**
+ * Scroll-to-caret for the editor's own scroll container.
+ *
+ * The editor is a scroll container (`overflow-y: auto` under a height cap in
+ * the core stylesheet; a consumer holding it to one line adds `overflow-x`).
+ * Browsers scroll such a box to the caret as the user types, but not when the
+ * caret is moved by script — which the SDK does on every render that actually
+ * rewrites the editable's content (`renderEditable` early-returns on an
+ * unchanged segment key, and restores the caret only while focused).
+ * Everything here exists to close that gap.
+ */
+/**
+ * Scroll the caret back into view inside the editor's own scroll container.
+ *
+ * Browsers do this themselves while the user types, but not when the caret is
+ * moved by script — so every programmatic caret placement (option selection,
+ * caret restore after a re-render, controlled-mode `setValue`) would otherwise
+ * leave the caret, and everything typed next, outside the visible box.
+ *
+ * Exactly one box is scrolled, by writing its own `scrollLeft` / `scrollTop`:
+ * the nearest scrollable ancestor of the editable, which inside the widget's
+ * own markup is the editor. `scrollIntoView` is deliberately not used — it
+ * would walk the whole ancestor chain and the page with it. When the widget
+ * does not own the editable's ancestry (a consumer-rendered editor in
+ * `"dropdown"` / `"headless"` mode) that nearest box may be one of the
+ * consumer's, which is what the browser would scroll for typed input anyway;
+ * nothing above it moves either way. A no-op when nothing overflows, when the
+ * caret is already visible, or when the caret has no measurable box.
+ */
+declare function scrollCaretIntoView(root: HTMLElement): void;
+
+/**
+ * Types the starting-state placeholder into the input one character at a
+ * time instead of popping it in whole.
+ *
+ * The reference (the RB2B support box, 2026-08-19): ~33 ms per character, no
+ * caret, a brief hold on word boundaries; when the phrase changes the old
+ * one fades out (~120 ms), the field sits empty for a beat (~50 ms), then the
+ * new phrase types in from nothing. Characters appear at full opacity — the
+ * only fade is the outgoing phrase.
+ *
+ * Shared by every package: vanilla, React and Angular all render the
+ * placeholder through `renderEditableContent`, which hands the target text
+ * to `syncPlaceholder` below. The typed prefix lives in `data-placeholder`
+ * (the stylesheets render it via `::before`), so nothing enters the
+ * contentEditable's DOM and the core's notion of the placeholder — which
+ * drives Tab-to-accept and prefix-typing suppression — stays the full phrase
+ * at all times.
+ */
+/** Delay between characters. */
+declare const PLACEHOLDER_TYPE_MS = 33;
+/** Extra hold after a word boundary (space / hyphen). */
+declare const PLACEHOLDER_WORD_PAUSE_MS = 70;
+/** Fade-out of the outgoing phrase — must match `--aia-placeholder-fade` in the stylesheets. */
+declare const PLACEHOLDER_FADE_OUT_MS = 120;
+/** Empty beat between the fade-out and the next phrase typing in. */
+declare const PLACEHOLDER_SWAP_GAP_MS = 50;
+/** Set on the input while the outgoing phrase fades; the stylesheets fade `::before` on it. */
+declare const PLACEHOLDER_LEAVING_ATTR = "data-aia-placeholder-leaving";
+
 interface RenderEditableArgs {
     input: HTMLElement;
     segments: Segment[];
@@ -990,6 +1183,56 @@ interface RenderEditableArgs {
  */
 declare function renderEditableContent(args: RenderEditableArgs): void;
 
+/**
+ * The "more below" arrow for the options grid.
+ *
+ * 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.
+ *
+ * The DOM differs per package (vanilla builds the button here; React and
+ * Angular render their own markup with the same classes and data attributes),
+ * so the *behaviour* lives in this one controller and each package hands it
+ * its dropdown, grid and button elements:
+ *
+ * - `update()` after every render — re-measures where the grid's bottom edge
+ *   is and re-evaluates visibility. The disc seats itself in the grid's
+ *   reserved fade band when there is one (below-mode with the footer), and
+ *   floats a small gap above the grid's edge in layouts that zero the band
+ *   (`optionsPosition="above"`, product strip). A new
+ *   option group (`data-aia-group` on the grid changed) keeps the arrow hidden
+ *   until the rows' entrance animation has settled, because a row mid-rise
+ *   still extends the scrollable area and would flash the arrow on.
+ * - The controller listens for the grid's own `scroll` and size changes itself.
+ * - `destroy()` when the grid or dropdown goes away.
+ */
+declare const SCROLL_ARROW_CLASS = "magicx-aia-scroll-arrow";
+/** Stable styling hook (module class names aren't part of the API). */
+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";
+/** 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";
+interface ScrollArrowController {
+    /** Re-measure and re-evaluate. Call after every render of the dropdown. */
+    update(): void;
+    destroy(): void;
+}
+interface ScrollArrowArgs {
+    /** The dropdown panel — the button's containing block; its lower edge clips the hidden button. */
+    dropdown: HTMLElement;
+    /** The options grid (the scroll box). */
+    grid: HTMLElement;
+    /** The arrow button, already in the dropdown. */
+    button: HTMLElement;
+}
+declare function attachScrollArrow({ dropdown, grid, button, }: ScrollArrowArgs): ScrollArrowController;
+
 type Listener<S> = (next: S, prev: S) => void;
 interface Store<S> {
     get: () => S;
@@ -1060,6 +1303,23 @@ declare class ModeController {
     private detachListener;
 }
 
+/**
+ * The dropdown pill-bar label for a parameter that has no suggestion behind it.
+ *
+ * Every pill normally shows its suggestion's `text` — a phrase written to be
+ * read, "Due date". A date the server identified in the user's own words
+ * ("september 5th") has no suggestion to borrow one from, only the wire `type`,
+ * so the type is read back into words instead: `travel_date` and `travelDate`
+ * both become "travel date". Without this the raw type is the label, both while
+ * the calendar is open over the span and again if that parameter is re-edited
+ * after being answered.
+ *
+ * Lower-casing costs nothing here — every package's pill CSS sets
+ * `text-transform: uppercase`, so a label's original case never reaches the
+ * screen either way.
+ */
+declare function identifiedParamLabel(type: string): string;
+
 /**
  * Sentinel `text` marking a `completed_params` entry the user skipped (→)
  * rather than filled. Sent regardless of `maskCompletedText` — it's a fixed
@@ -1092,4 +1352,4 @@ declare function withSkippedParams(completed: CompletedParam[], skipped: Skipped
  */
 declare function buildSubmitResult(text: string, completedParams: CompletedParamState[], skippedParams?: SkippedParamState[]): 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, type OptionOverrides, type OptionsGridLayout, type Product, type ProductsConfig, type RecentlySuggested, type RenderMode, SKIPPED_PARAM_TEXT, type Segment, type SkippedParamState, type Store, type Suggestion, type SuggestionOption, type TaskKind, WEEKDAY_LABELS, addMonths, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, computeOptionsGridLayout, createStore, cursorIsAtEnd, extractPlainText, formatDate, getCursorOffset, getFooterHint, isOptionsGridMobileViewport, isoDate, monthLabel, optionsGridTemplateColumns, parseDate, parseLooseDate, plainTextLength, previousGraphemeBoundary, renderEditableContent, resolveFormatType, resolveIdentifiedDate, 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 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 };