@magicx-eng/ai-autocomplete-vanilla 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,386 @@
+# @magicx-eng/ai-autocomplete-vanilla
+
+A framework-agnostic vanilla JS/TypeScript library that provides a guided AI-powered autocomplete experience with pill-based input and dropdown suggestions. Works with any tech stack — React, Vue, Svelte, Angular, or plain HTML.
+
+## 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
+- **Light/dark mode** — built-in themes with `prefers-color-scheme` support, fully overridable via CSS variables
+- **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
+- **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
+- **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
+- **TypeScript first** — full type definitions shipped with the package
+- **SSR-safe** — no top-level `document`/`window` access
+
+## Installation
+
+```bash
+pnpm add @magicx-eng/ai-autocomplete-vanilla
+```
+
+## Three Tiers
+
+| 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 |
+
+---
+
+## 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.
+
+### 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"
+
+  // Events
+  onSubmit: (result) => { ... },
+  onError: (error) => { ... },
+  onChange: (text) => { ... },
+  onParamsChange: (params) => { ... },
+
+  // Controlled mode
+  value: "initial text",
+  completedParams: [],
+});
+```
+
+### Methods
+
+```ts
+ac.focus();                    // Focus 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" });
+```
+
+---
+
+## Tier 2: Dropdown Only
+
+You own the input. The library renders the dropdown with pills inside a container you provide.
+
+```ts
+import { AIAutocomplete } from "@magicx-eng/ai-autocomplete-vanilla";
+
+const input = document.getElementById("my-input");
+const dropdownContainer = document.getElementById("my-dropdown");
+
+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),
+});
+
+// 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));
+```
+
+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.
+
+> 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.
+
+---
+
+## Tier 3: Headless
+
+No DOM at all. You get state, controllers, and derived data. You render everything yourself.
+
+This is what framework wrappers (React, Vue, Svelte) use under the hood.
+
+```ts
+import { AIAutocomplete } from "@magicx-eng/ai-autocomplete-vanilla";
+
+const ac = new AIAutocomplete(document.createElement("div"), {
+  renderMode: "headless",
+  apiConfig: { apiKey: "your_api_key" },
+  onSubmit: (result) => console.log(result),
+});
+
+// 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);
+});
+
+// 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();
+```
+
+### State shape (`CoreState`)
+
+| 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
+
+| 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. |
+
+### Building a framework wrapper
+
+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`
+
+A discriminated union: `APIKeyConfig | AccessTokenConfig`.
+
+#### API Key Mode (default)
+
+```ts
+{
+  apiKey: "your_api_key",
+  authScheme: "Bearer",         // or "Basic"
+  endpoint: "/ac/suggest",      // optional
+  appIdentifier: "my-app",      // optional
+  headers: { "X-Custom": "v" }, // optional
+}
+```
+
+#### Access Token Mode
+
+```ts
+{
+  type: "accessToken",
+  getAccessToken: async () => {
+    const res = await fetch("/api/ac-token");
+    const { access_token, expires_at } = await res.json();
+    return { accessToken: access_token, expiresAt: expires_at };
+  },
+  endpoint: "/ac/suggest",      // optional
+}
+```
+
+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`.
+
+### `AutocompleteResult`
+
+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 = ac.on("submit", (result) => { ... });
+off(); // unsubscribe
+```
+
+Events: `submit`, `error`, `change`, `paramsChange`.
+
+Constructor callbacks (`onSubmit`, `onChange`, etc.) are equivalent to calling `on()`.
+
+**`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.
+
+---
+
+## CSS Customization
+
+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. All built-in defaults use `:where()` (zero specificity) — your overrides always win without `!important`.
+
+| Variable | Default (light) | Default (dark) | Description |
+|---|---|---|---|
+| `--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"] {
+  --aia-pill-bg: #e2e8f0;
+}
+#my-autocomplete[data-mode="dark"] {
+  --aia-pill-bg: #334155;
+}
+```
+
+### Live Preview
+
+```ts
+document.getElementById("my-autocomplete")
+  .style.setProperty("--aia-pill-bg", newColor);
+```
+
+### Selector Hooks
+
+For styling beyond the CSS variables, target these stable `data-aia-*` attributes:
+
+| Attribute | Element |
+|---|---|
+| `[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
+
+```ts
+new AIAutocomplete(el, {
+  optionOverrides: {
+    account: () => [
+      { text: "Savings", is_tappable: true, kind: null },
+      { text: "Checking", is_tappable: true, kind: null },
+    ],
+    value: (query) => {
+      const digits = query.replace(/\D/g, "");
+      if (!digits) return [{ text: "$100", is_tappable: true, kind: null }];
+      return [{ text: `$${digits}`, is_tappable: true, kind: null }];
+    },
+  },
+  onSubmit: handleSubmit,
+});
+```
+
+---
+
+## 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,19 +84,30 @@ 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";
+    /** Render mode. Default: "full". */
+    renderMode?: RenderMode;
     onSubmit?: (result: AutocompleteResult) => void;
     onError?: (error: Error) => void;
     onChange?: (text: string) => void;
@@ -114,36 +117,23 @@ interface CoreOptions {
     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;
     reset(): void;
@@ -154,15 +144,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 };

package/index.d.ts

@@ -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,19 +84,30 @@ 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";
+    /** Render mode. Default: "full". */
+    renderMode?: RenderMode;
     onSubmit?: (result: AutocompleteResult) => void;
     onError?: (error: Error) => void;
     onChange?: (text: string) => void;
@@ -114,36 +117,23 @@ interface CoreOptions {
     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;
     reset(): void;
@@ -154,15 +144,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 };