@magicx-eng/ai-autocomplete-vanilla 0.1.1 → 0.1.3

package/README.md

@@ -4,6 +4,7 @@ A framework-agnostic vanilla JS/TypeScript library that provides a guided AI-pow
 
 ## Features
 
+- **Three tiers of integration** — full drop-in component, dropdown-only, or fully headless
 - **Zero dependencies** — no React, no framework, no virtual DOM
 - **Pill-based input** — inline pills for unfilled parameters, completed text for filled ones
 - **Pill placement** — render pills inline in the input or inside the dropdown
@@ -12,8 +13,7 @@ A framework-agnostic vanilla JS/TypeScript library that provides a guided AI-pow
 - **Keyboard navigation** — arrow keys, enter to submit, tab to autocomplete
 - **Client-side filtering** — instant substring filtering on every keystroke
 - **Option overrides** — inject or dynamically generate client-side options per suggestion type
-- **Controlled & uncontrolled** — works out of the box or integrates with external state via `setValue()` / `setCompletedParams()`
-- **Imperative API** — `focus()`, `reset()`, `setMode()`, `destroy()`, and more
+- **Controlled & uncontrolled** — works out of the box or integrates with external state
 - **Accessible** — ARIA combobox pattern with `role="listbox"`, `aria-activedescendant`
 - **Animations** — option selection streak animation, text shimmer on newly added params
 - **Lightweight** — ~10 KB gzipped, styles auto-injected at runtime
@@ -26,121 +26,219 @@ A framework-agnostic vanilla JS/TypeScript library that provides a guided AI-pow
 pnpm add @magicx-eng/ai-autocomplete-vanilla
 ```
 
-## Quick Start
+## Three Tiers
 
-```html
-<div id="ac"></div>
+| Tier | What you get | What you own | Use when |
+|---|---|---|---|
+| **Tier 1: Full** | Input + dropdown + pills + keyboard + state | Nothing — drop in and go | You want a complete widget with zero setup |
+| **Tier 2: Dropdown** | Dropdown + pills + keyboard + state | The input element | You need a custom input (e.g. rich text, search bar) |
+| **Tier 3: Headless** | State + controllers + derived data | All DOM | You're building a framework wrapper (React, Vue, Svelte) or need full rendering control |
 
-<script type="module">
-  import { AIAutocomplete } from "@magicx-eng/ai-autocomplete-vanilla";
+---
 
-  const instance = new AIAutocomplete(document.getElementById("ac"), {
-    apiConfig: {
-      endpoint: "https://api.example.com/ac/suggest",
-      apiKey: "your_api_key",
-    },
-    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", ... }]
-    },
-  });
-</script>
+## Tier 1: Full Component
+
+Drop-in. The library creates and owns the input, dropdown, pills, and all DOM.
+
+```ts
+import { AIAutocomplete } from "@magicx-eng/ai-autocomplete-vanilla";
+
+const ac = new AIAutocomplete(document.getElementById("root"), {
+  apiConfig: {
+    endpoint: "https://api.example.com/ac/suggest",
+    apiKey: "your_api_key",
+  },
+  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", ... }]
+  },
+});
 ```
 
 No CSS import needed — styles are auto-injected on first instantiation.
 
-## Usage with Frameworks
+### Options
+
+```ts
+const ac = new AIAutocomplete(container, {
+  // Tier: "full" (default) | "dropdown" | "headless"
+  renderMode: "full",
+
+  // API
+  apiConfig: { apiKey: "...", authScheme: "Bearer", endpoint: "/ac/suggest" },
+  optionOverrides: { account: (query) => [...] },
+  columns: 2,
+  maskCompletedText: false, // when true, omits completed params' text from API requests (PII masking)
+
+  // Appearance
+  mode: "auto",               // "light" | "dark" | "auto"
+  optionsPosition: "below",   // "above" | "below"
+  animations: true,            // enable streak + shimmer
+  pillPlacement: "inline",     // "inline" | "dropdown" | "hidden"
+  dropdownTrigger: "auto",   // "auto" | "manual" | "hidden"
+  closeDropdownOnBlur: true, // false = keep dropdown open even when input loses focus
+
+  // Focus
+  autoFocus: true,           // focus the input on mount (Tier 1 only)
+
+  // Events
+  onSubmit: (result) => { ... },
+  onError: (error) => { ... },
+  onChange: (text) => { ... },
+  onParamsChange: (params) => { ... },
+  onFocus: () => { ... },
+  onBlur: () => { ... },
+
+  // Controlled mode
+  value: "initial text",
+  completedParams: [],
+});
+```
+
+### Methods
+
+```ts
+ac.focus();                    // Focus the input
+ac.blur();                     // Blur the input
+ac.reset();                    // Clear everything, re-fetch
+ac.destroy();                  // Remove DOM, listeners, timers
+ac.setMode("dark");            // Switch color mode
+ac.update({ animations: false, optionsPosition: "above" });
+```
+
+> `autoFocus`, `focus()`, and `blur()` only operate on the textarea the library owns (Tier 1 / `renderMode: "full"`). In Tier 2/3, the consumer owns the input and calls `.focus()` / `.blur()` on their own element; the `onFocus` / `onBlur` callbacks still fire whenever `setFocused()` is called.
+
+---
 
-### Vue
+## Tier 2: Dropdown Only
 
-```vue
-<template>
-  <div ref="acRef" />
-</template>
+You own the input. The library renders the dropdown with pills inside a container you provide.
 
-<script setup>
-import { ref, onMounted, onUnmounted } from "vue";
+```ts
 import { AIAutocomplete } from "@magicx-eng/ai-autocomplete-vanilla";
 
-const acRef = ref(null);
-let instance;
+const input = document.getElementById("my-input");
+const dropdownContainer = document.getElementById("my-dropdown");
 
-onMounted(() => {
-  instance = new AIAutocomplete(acRef.value, {
-    apiConfig: { endpoint: "/ac/suggest", apiKey: "your_key" },
-    onSubmit: (result) => console.log(result),
-  });
+const ac = new AIAutocomplete(dropdownContainer, {
+  renderMode: "dropdown",
+  apiConfig: { apiKey: "your_api_key" },
+  onChange: (text) => {
+    // Keep your input in sync when the library updates text (e.g. option selected)
+    if (input.value !== text) input.value = text;
+  },
+  onSubmit: (result) => console.log(result),
 });
 
-onUnmounted(() => instance?.destroy());
-</script>
+// Wire your input → library
+input.addEventListener("input", () => ac.handleTextChange(input.value));
+input.addEventListener("keydown", (e) => ac.handleKeyDown(e));
+input.addEventListener("focus", () => ac.setFocused(true));
+input.addEventListener("blur", () => ac.setFocused(false));
 ```
 
-### Svelte
+Pills always render inside the dropdown in this mode. The library creates the dropdown DOM inside your container — you just provide the element and wire up your input's events.
 
-```svelte
-<script>
-  import { onMount, onDestroy } from "svelte";
-  import { AIAutocomplete } from "@magicx-eng/ai-autocomplete-vanilla";
+> 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.
 
-  let el;
-  let instance;
+---
 
-  onMount(() => {
-    instance = new AIAutocomplete(el, {
-      apiConfig: { endpoint: "/ac/suggest", apiKey: "your_key" },
-      onSubmit: (result) => console.log(result),
-    });
-  });
+## Tier 3: Headless
 
-  onDestroy(() => instance?.destroy());
-</script>
+No DOM at all. You get state, controllers, and derived data. You render everything yourself.
 
-<div bind:this={el}></div>
-```
+This is what framework wrappers (React, Vue, Svelte) use under the hood.
+
+```ts
+import { AIAutocomplete } from "@magicx-eng/ai-autocomplete-vanilla";
 
-### Plain HTML (CDN)
+const ac = new AIAutocomplete(document.createElement("div"), {
+  renderMode: "headless",
+  apiConfig: { apiKey: "your_api_key" },
+  onSubmit: (result) => console.log(result),
+});
 
-```html
-<div id="ac"></div>
-<script type="module">
-  import { AIAutocomplete } from "https://unpkg.com/@magicx-eng/ai-autocomplete-vanilla/index.mjs";
+// Read state
+const state = ac.getState();
+// state.text, state.completedParams, state.suggestions,
+// state.segments, state.filteredOptions, state.actionableSuggestions,
+// state.placeholderText, state.isDropdownOpen, state.activeDropdownIndex,
+// state.newParamId, state.isLoading, state.isReady, state.error
+
+// Subscribe to changes (fires after derived state is settled)
+const unsub = ac.subscribe((state) => {
+  renderMyInput(state.text, state.placeholderText);
+  renderMyPills(state.actionableSuggestions);
+  renderMyDropdown(state.filteredOptions, state.activeDropdownIndex, state.isDropdownOpen);
+  renderMySegments(state.segments, state.newParamId);
+});
 
-  new AIAutocomplete(document.getElementById("ac"), {
-    apiConfig: { endpoint: "/ac/suggest", apiKey: "your_key" },
-    onSubmit: (result) => console.log(result),
-  });
-</script>
+// Forward user actions → library
+myInput.addEventListener("input", () => ac.handleTextChange(myInput.value));
+myInput.addEventListener("keydown", (e) => ac.handleKeyDown(e));
+myInput.addEventListener("focus", () => ac.setFocused(true));
+myInput.addEventListener("blur", () => ac.setFocused(false));
+myOptionEl.addEventListener("click", () => ac.selectOption(option));
+myPillEl.addEventListener("click", () => ac.setActivePill(index));
+
+// Cleanup
+ac.destroy();
+unsub();
 ```
 
-## API Reference
+### State shape (`CoreState`)
 
-### Constructor
+| Field | Type | Description |
+|---|---|---|
+| `text` | `string` | Current input text |
+| `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 |
+| `segments` | `Segment[]` | Input text split into typed text vs completed params — for overlay rendering |
+| `placeholderText` | `string` | Placeholder text from server suggestions (joined `placeholder`-type suggestion texts) |
+| `activeDropdownIndex` | `number` | Highlighted option index (-1 = none) |
+| `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 |
+| `isReady` | `boolean` | Server indicates query is complete |
+| `error` | `Error \| null` | Last fetch error |
+
+### Actions
 
-```ts
-new AIAutocomplete(container: HTMLElement, options?: CoreOptions)
-```
+| Method | Description |
+|---|---|
+| `handleTextChange(value)` | Call when user types. Handles capitalization, param reconciliation, filter updates. |
+| `handleKeyDown(event)` | Forward keyboard events. Handles arrow nav, Enter, Tab, Escape. |
+| `setFocused(focused)` | Notify the library that the input has focus. Required for `dropdownTrigger: "auto"` in Tier 2/3 — the dropdown only opens while focused. |
+| `selectOption(option)` | Select a dropdown option. Updates text, creates completed param, triggers shimmer. |
+| `setActiveDropdownIndex(index)` | Set the highlighted option (for mouse hover). |
+| `setActivePill(index)` | Reorder pills — moves pill at `index` to front (active). |
+| `removeLastParam()` | Remove last completed param, restore it as a pill. |
+| `clearNewParamId()` | Clear shimmer animation state. |
+| `reset()` | Clear all state, re-fetch initial suggestions. |
+| `setValue(text)` | Set text (controlled mode). |
+| `setCompletedParams(params)` | Set completed params (controlled mode). |
+| `setMode(mode)` | Switch color mode at runtime. |
+| `update(opts)` | Update multiple options at once (e.g. `animations`, `pillPlacement`, `dropdownTrigger`, `optionsPosition`). |
+| `getState()` | Get a snapshot of the current state. Useful for initial read before subscribing. |
+| `subscribe(listener)` | Subscribe to state changes (fires after derived state settles). Returns unsubscribe function. |
+| `destroy()` | Cleanup — abort fetches, clear timers, remove listeners. |
 
-### `CoreOptions`
+### Building a framework wrapper
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `apiConfig` | `APIConfig` | — | API configuration (see below). |
-| `optionOverrides?` | `Record<string, (query: string) => SuggestionOption[]>` | — | Override options per suggestion type. |
-| `placeholder?` | `string` | — | Fallback placeholder when the server doesn't return one. |
-| `columns?` | `number` | `2` | Number of columns in the dropdown grid. |
-| `typewriterEffect?` | `boolean` | `false` | Letter-by-letter reveal on option select. |
-| `pillPlacement?` | `"inline" \| "dropdown"` | `"inline"` | Where to render unfilled pills. |
-| `mode?` | `"light" \| "dark" \| "auto"` | `"auto"` | Color mode. `"auto"` follows `prefers-color-scheme`. |
-| `optionsPosition?` | `"above" \| "below"` | `"below"` | Where the dropdown opens relative to the input. |
-| `animations?` | `boolean` | `true` | Enable/disable all animations (streak + shimmer). |
-| `onSubmit?` | `(result: AutocompleteResult) => void` | — | Called on Enter or submit button. |
-| `onError?` | `(error: Error) => void` | — | Called when a fetch fails. |
-| `onChange?` | `(text: string) => void` | — | Called when text changes. |
-| `onParamsChange?` | `(params: CompletedParamState[]) => void` | — | Called when completed params change. |
-| `value?` | `string` | — | Controlled text value. |
-| `completedParams?` | `CompletedParamState[]` | — | Controlled completed params. |
+The pattern for any framework:
+
+1. Create a headless instance on mount
+2. Subscribe to state → map to framework reactivity (`useState`, `ref()`, `writable()`)
+3. Render your own components using the state
+4. Forward user events (input, keydown, click) → core actions
+5. Destroy on unmount
+
+---
+
+## API Reference
 
 ### `APIConfig`
 
@@ -172,100 +270,104 @@ A discriminated union: `APIKeyConfig | AccessTokenConfig`.
 }
 ```
 
-The SDK handles token refresh transparently: if a request returns 401, it calls `getAccessToken` once, retries, and only surfaces an error if the retry also fails. Concurrent 401s share a single refresh call.
+The SDK handles token refresh transparently: if a request returns 401, it calls `getAccessToken` once, retries, and only surfaces an error if the retry also fails. Concurrent 401s share a single refresh call. Tokens are refreshed proactively 30 seconds before `expiresAt`.
 
-### Instance Methods
+### `AutocompleteResult`
 
-| Method | Description |
-|---|---|
-| `focus()` | Focus the textarea. |
-| `reset()` | Clear all state and re-fetch initial suggestions. |
-| `destroy()` | Remove all DOM, listeners, and timers. Call when unmounting. |
-| `setMode(mode)` | Switch color mode at runtime (`"light"`, `"dark"`, `"auto"`). |
-| `update(opts)` | Update any option at runtime (mode, pillPlacement, animations, etc.). |
-| `setValue(text)` | Set text value (controlled mode). |
-| `setCompletedParams(params)` | Set completed params (controlled mode). |
-| `setActivePill(index)` | Reorder pills, making the one at `index` active. |
-| `removeLastParam()` | Remove the last completed param and restore it as a pill. |
-| `clearNewParamId()` | Clear the shimmer animation state. |
-| `getState()` | Get a snapshot of the full internal state. |
-| `isReady` | `true` when the server indicates the query is ready for execution. |
+The object passed to `onSubmit`:
+
+| 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. |
 
 ### Event Subscription
 
 ```ts
-const off = instance.on("submit", (result) => { ... });
+const off = ac.on("submit", (result) => { ... });
 off(); // unsubscribe
 ```
 
-Events: `submit`, `error`, `change`, `paramsChange`, `stateChange`.
+Events: `submit`, `error`, `change`, `paramsChange`, `focus`, `blur`.
 
 Constructor callbacks (`onSubmit`, `onChange`, etc.) are equivalent to calling `on()`.
 
-### `AutocompleteResult`
+**`subscribe()` vs `on()`:** Use `on()` for specific events (submit, error, text change). Use `subscribe()` (Tier 3) for full state updates — it fires after derived state is settled, making it safe for rendering.
 
-The object passed to `onSubmit`:
-
-| 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. |
+---
 
 ## CSS Customization
 
-Styles are auto-injected at runtime — no CSS import needed. The component ships built-in light and dark defaults that apply automatically based on the `mode` option.
+Styles are auto-injected at runtime (Tier 1 and Tier 2). No CSS import needed. The component ships built-in light and dark defaults.
 
 ### CSS Variables
 
-Override these on the container element to customize the appearance. All built-in defaults use `:where()` (zero specificity), so your overrides always win without `!important`.
+Override these on the container element. All built-in defaults use `:where()` (zero specificity) — your overrides always win without `!important`.
 
 | Variable | Default (light) | Default (dark) | Description |
 |---|---|---|---|
-| `--ac-pill-bg` | `#f1f5f9` | `#1e293b` | Pill background color |
-| `--ac-pill-color` | `#475569` | `#cbd5e1` | Pill text color |
-| `--ac-pill-font-size` | `19px` | `19px` | Pill font size |
-| `--ac-option-bg` | `transparent` | `transparent` | Option background (highlighted) |
-| `--ac-option-color` | `#475569` | `#cbd5e1` | Option text color |
-| `--ac-option-color-selected` | `#0f172a` | `#f8fafc` | Highlighted option text color |
-| `--ac-option-font-size` | `19px` | `19px` | Option font size |
-| `--ac-written-text-color` | `#0f172a` | `#f1f5f9` | Input text color |
-| `--ac-written-text-font-size` | `19px` | `19px` | Input text font size |
+| `--aia-pill-bg` | `#bdbdbd` | `#bdbdbd` | Pill background |
+| `--aia-pill-color` | `#000000` | `#ffffff` | Pill text |
+| `--aia-pill-font-size` | `19px` | `19px` | Pill font size |
+| `--aia-option-bg` | `transparent` | `transparent` | Option background (highlighted) |
+| `--aia-option-color` | `#000000` | `#ffffff` | Option text |
+| `--aia-option-color-selected` | `#000000` | `#ffffff` | Highlighted option text |
+| `--aia-option-font-size` | `19px` | `19px` | Option font size |
+| `--aia-written-text-color` | `#000000` | `#ffffff` | Input text |
+| `--aia-written-text-font-size` | `19px` | `19px` | Input text font size |
+| `--aia-caret-color` | `--aia-written-text-color` | `--aia-written-text-color` | Textarea caret color. Override independently of input text color. |
+| `--aia-submit-bg` | `#000000` | `#ffffff` | Submit button background |
+| `--aia-submit-color` | `#ffffff` | `#000000` | Submit button icon color |
+| `--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. |
 
 ### Per-mode Overrides
 
 ```css
 #my-autocomplete[data-mode="light"] {
-  --ac-pill-bg: #e2e8f0;
-  --ac-written-text-color: #1e293b;
+  --aia-pill-bg: #e2e8f0;
 }
-
 #my-autocomplete[data-mode="dark"] {
-  --ac-pill-bg: #334155;
-  --ac-written-text-color: #f8fafc;
+  --aia-pill-bg: #334155;
 }
 ```
 
 ### Live Preview
 
-CSS variables update instantly — great for theme editors:
-
 ```ts
 document.getElementById("my-autocomplete")
-  .style.setProperty("--ac-pill-bg", newColor);
+  .style.setProperty("--aia-pill-bg", newColor);
 ```
 
-## Keyboard Behavior
+### Selector Hooks
 
-| Key | Behavior |
+For styling beyond the CSS variables, target these stable `data-aia-*` attributes:
+
+| Attribute | Element |
 |---|---|
-| **Arrow Down** | Open dropdown and select first option, or navigate to next option. |
-| **Arrow Up** | Navigate to previous option. Deselects if on the first row. |
-| **Arrow Right** | Jump to next column when an option is highlighted. Cycles to next pill when cursor is at the end. |
-| **Arrow Left** | Jump to previous column when an option is highlighted. |
-| **Tab** | Select the first tappable option (or highlighted one). Accepts placeholder when input is empty. |
-| **Enter** | Select highlighted option if one is highlighted. Otherwise submits the query. |
-| **Escape** | Deselect the highlighted option. |
+| `[data-aia-editor]` | Editor area wrapping the textarea + overlay |
+| `[data-aia-textarea]` | The `<textarea>` |
+| `[data-aia-submit]` | Submit button |
+| `[data-aia-pill]` | Each unfilled-suggestion pill |
+| `[data-aia-pillbar]` | Pill bar container inside the dropdown |
+| `[data-aia-option]` | Each suggestion option |
+| `[data-aia-dropdown]` | The dropdown root (listbox) |
+
+The vanilla core also exposes stable BEM class names (`magicx-aia-*`); both can be used.
+
+```css
+/* Solid (non-glass) dropdown */
+#my-autocomplete [data-aia-dropdown] {
+  background: #fff;
+  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.1);
+  backdrop-filter: none;
+}
+```
+
+---
 
 ## Option Overrides
 
@@ -286,6 +388,8 @@ new AIAutocomplete(el, {
 });
 ```
 
+---
+
 ## License
 
 Private package. All rights reserved.

package/index.d.mts

@@ -43,7 +43,7 @@ interface APIConfigBase {
 }
 interface APIKeyConfig extends APIConfigBase {
     type?: "apiKey";
-    apiKey: string;
+    apiKey?: string;
     authScheme?: "Bearer" | "Basic";
 }
 interface AccessTokenConfig extends APIConfigBase {
@@ -64,14 +64,6 @@ interface AutocompleteResult {
     completed_params: CompletedParam[];
 }
 
-type Listener<S> = (next: S, prev: S) => void;
-interface Store<S> {
-    get: () => S;
-    set: (patch: Partial<S> | ((s: S) => Partial<S>)) => void;
-    subscribe: (listener: Listener<S>) => () => void;
-}
-declare function createStore<S>(initial: S): Store<S>;
-
 /** Internal state managed by the store. */
 interface CoreState {
     text: string;
@@ -92,60 +84,67 @@ interface CoreState {
     pillTapped: boolean;
     skipNextFetch: boolean;
     lastRawQuery: string;
+    isFocused: boolean;
 }
+/**
+ * Render mode:
+ * - "full" (default) — renders input + dropdown + pills. Tier 1.
+ * - "dropdown" — renders only the dropdown with pills. Consumer owns the input. Tier 2.
+ * - "headless" — no DOM. State + controllers only. For framework wrappers.
+ */
+type RenderMode = "full" | "dropdown" | "headless";
 /** Options passed to the AIAutocomplete constructor. */
 interface CoreOptions {
     apiConfig?: APIConfig;
     optionOverrides?: OptionOverrides;
     maskCompletedText?: boolean;
-    placeholder?: string;
     columns?: number;
-    typewriterEffect?: boolean;
-    pillPlacement?: "inline" | "dropdown";
+    /** Where pills render in "full" mode. Ignored in "dropdown" mode (always in dropdown). */
+    pillPlacement?: "inline" | "dropdown" | "hidden";
     mode?: AppearanceMode;
     optionsPosition?: "above" | "below";
     animations?: boolean;
+    /** When the dropdown appears. "auto" = shows when options available. "manual" = only on pill tap. "hidden" = never. Default: "auto". */
+    dropdownTrigger?: "auto" | "manual" | "hidden";
+    /** When true (default), the dropdown closes when the input loses focus. Set to false to keep it open whenever options are available, regardless of focus. */
+    closeDropdownOnBlur?: boolean;
+    /** Render mode. Default: "full". */
+    renderMode?: RenderMode;
+    /** Focus the input on mount (Tier 1 / "full" render mode only). Default: true. */
+    autoFocus?: boolean;
     onSubmit?: (result: AutocompleteResult) => void;
     onError?: (error: Error) => void;
     onChange?: (text: string) => void;
     onParamsChange?: (params: CompletedParamState[]) => void;
     onStateChange?: (state: CoreState) => void;
+    /** Called when the input gains focus (or `setFocused(true)` is called). */
+    onFocus?: () => void;
+    /** Called when the input loses focus (or `setFocused(false)` is called). */
+    onBlur?: () => void;
     value?: string;
     completedParams?: CompletedParamState[];
 }
 
-interface KeyboardContext {
-    columns: number;
-    listboxId: string;
-    onSubmit?: (result: AutocompleteResult) => void;
-    selectOption: (option: SuggestionOption) => void;
-}
-declare class KeyboardController {
-    private store;
-    private ctx;
-    constructor(store: Store<CoreState>, ctx: KeyboardContext);
-    handleKeyDown(e: KeyboardEvent): void;
-    private getTappableIndices;
-    private clickOrSelect;
-    /** Delegate to pills controller logic inline (avoids circular dep) */
-    private pillsSetActivePill;
-}
-
 declare class AIAutocomplete {
     private store;
-    private listboxId;
+    private _listboxId;
     private opts;
     private fetchController;
-    keyboardController: KeyboardController;
+    private keyboardController;
     private pillsController;
     private modeController;
     private container;
     private unsubscribers;
     private derivedInProgress;
+    private renderMode;
     private domRefs;
+    private dropdownRefs;
     private newParamTimer;
+    private suggestionRemovalTimer;
+    private externalListeners;
     constructor(container: HTMLElement, opts?: CoreOptions);
     focus(): void;
+    blur(): void;
     reset(): void;
     destroy(): void;
     setMode(mode: AppearanceMode): void;
@@ -154,15 +153,35 @@ declare class AIAutocomplete {
     setActivePill(index: number): void;
     removeLastParam(): void;
     clearNewParamId(): void;
+    setActiveDropdownIndex(index: number): void;
+    handleTextChange(value: string): void;
+    handleKeyDown(e: KeyboardEvent): void;
+    setFocused(focused: boolean): void;
+    /** Subscribe to state changes (fires after derived state is settled). Returns unsubscribe function. */
+    subscribe(listener: (state: CoreState) => void): () => void;
     getState(): CoreState;
+    get listboxId(): string;
     get isReady(): boolean;
     on(event: string, callback: (...args: unknown[]) => void): () => void;
     update(opts: Partial<CoreOptions>): void;
-    private selectOption;
+    selectOption(option: SuggestionOption): void;
     private recomputeDerived;
     private setupContainer;
-    private buildAndRender;
+    private buildAndRenderFull;
+    private buildAndRenderDropdown;
+    /** Batched render subscriber — coalesces multiple store.set calls into one DOM update. */
+    private subscribeBatchedRender;
+    /** Auto-clear newParamId after shimmer animation. */
+    private subscribeNewParamTimer;
     private handleChange;
 }
 
-export { AIAutocomplete, type APIConfig, type APIKeyConfig, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteResult, type CompletedParam, type CompletedParamState, type CoreOptions, type CoreState, type Segment, type Store, type Suggestion, type SuggestionOption, createStore };
+type Listener<S> = (next: S, prev: S) => void;
+interface Store<S> {
+    get: () => S;
+    set: (patch: Partial<S> | ((s: S) => Partial<S>)) => void;
+    subscribe: (listener: Listener<S>) => () => void;
+}
+declare function createStore<S>(initial: S): Store<S>;
+
+export { AIAutocomplete, type APIConfig, type APIKeyConfig, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteResult, type CompletedParam, type CompletedParamState, type CoreOptions, type CoreState, type RenderMode, type Segment, type Store, type Suggestion, type SuggestionOption, createStore };