@hevmind/ask 0.1.0

package/src/components/SearchOverlay.astro

@@ -0,0 +1,1375 @@
+---
+interface Props {
+  /** Endpoint to query. Must match the integration's `endpoint` option. */
+  endpoint?: string;
+  /** Placeholder text for the search input. */
+  placeholder?: string;
+  /** Debounce in ms before a query is sent after typing stops. */
+  debounce?: number;
+}
+
+const {
+  endpoint = '/api/ask',
+  placeholder = 'Search the docs…',
+  debounce = 500,
+} = Astro.props;
+---
+
+<dialog
+  class="as-overlay"
+  data-endpoint={endpoint}
+  data-debounce={debounce}
+  aria-label="Search"
+>
+  <div class="as-box">
+    <div class="as-inputrow">
+      <svg class="as-icon" width="18" height="18" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+        <circle cx="11" cy="11" r="7" stroke="currentColor" stroke-width="2" />
+        <path d="m20 20-3-3" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
+      </svg>
+      <input
+        class="as-input"
+        type="search"
+        placeholder={placeholder}
+        autocomplete="off"
+        autocorrect="off"
+        autocapitalize="off"
+        spellcheck="false"
+        aria-label="Search query"
+      />
+      <button class="as-ai-button" type="button" disabled>
+        <span class="as-ai-label">Ask AI</span>
+        <kbd class="as-kbd">↵</kbd>
+      </button>
+      <kbd class="as-kbd as-esc">esc</kbd>
+    </div>
+
+    <div class="as-results" role="listbox" aria-label="Search results" tabindex="-1"></div>
+    <div class="as-answer" hidden>
+      <div class="as-answer-body" aria-live="polite"></div>
+      <div class="as-answer-sources" hidden></div>
+    </div>
+    <div class="as-searched" hidden></div>
+
+    <div class="as-footer">
+      <span class="as-hint">
+        <kbd class="as-kbd">↵</kbd> ask AI · <kbd class="as-kbd">↑</kbd><kbd class="as-kbd">↓</kbd> open
+      </span>
+      <span class="as-meta">
+        <span class="as-mode" hidden>
+          <span class="as-mode-label"></span>
+          <button class="as-mode-toggle" type="button"></button>
+        </span>
+        <span class="as-brand"><a
+            class="as-brandlink"
+            href="https://github.com/hev/ask"
+            target="_blank"
+            rel="noopener noreferrer">hev/ask</a></span>
+      </span>
+    </div>
+  </div>
+</dialog>
+
+<style>
+  .as-overlay {
+    --as-bg: var(--paper, #111111);
+    --as-fg: var(--ink, #f2f2f2);
+    --as-muted: var(--muted, #8a8a8a);
+    --as-accent: var(--signal, #e25822);
+    --as-border: color-mix(in srgb, var(--as-fg) 14%, transparent);
+    --as-hover: color-mix(in srgb, var(--as-fg) 7%, transparent);
+
+    width: min(640px, calc(100vw - 2rem));
+    max-width: 640px;
+    padding: 0;
+    border: 1px solid var(--as-border);
+    border-radius: 14px;
+    background: var(--as-bg);
+    color: var(--as-fg);
+    box-shadow: 0 24px 60px -12px rgba(0, 0, 0, 0.6);
+    /* Explicit margins: a host site's `* { margin: 0 }` reset would otherwise
+       clobber the UA dialog centering and drift the overlay to the left. */
+    margin-block: 12vh auto;
+    margin-inline: auto;
+    overflow: hidden;
+  }
+
+  .as-overlay::backdrop {
+    background: rgba(0, 0, 0, 0.55);
+    backdrop-filter: blur(3px);
+  }
+
+  .as-overlay[open] {
+    animation: as-pop 120ms ease-out;
+  }
+
+  @keyframes as-pop {
+    from { opacity: 0; transform: translateY(-6px); }
+    to { opacity: 1; transform: translateY(0); }
+  }
+
+  .as-box {
+    display: flex;
+    flex-direction: column;
+  }
+
+  .as-inputrow {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    padding: 14px 16px;
+    border-bottom: 1px solid var(--as-border);
+  }
+
+  .as-icon {
+    color: var(--as-muted);
+    flex: none;
+  }
+
+  .as-input {
+    flex: 1;
+    min-width: 0;
+    border: none;
+    outline: none;
+    background: transparent;
+    color: var(--as-fg);
+    font-size: 1rem;
+    font-family: inherit;
+  }
+
+  .as-input::placeholder { color: var(--as-muted); }
+  /* Hide native search clear button for a cleaner palette. */
+  .as-input::-webkit-search-cancel-button { display: none; }
+
+  .as-ai-button {
+    flex: none;
+    display: inline-flex;
+    align-items: center;
+    gap: 7px;
+    min-height: 32px;
+    padding: 4px 8px 4px 10px;
+    border: 1px solid color-mix(in srgb, var(--as-accent) 70%, var(--as-border));
+    border-radius: 8px;
+    background: color-mix(in srgb, var(--as-accent) 18%, transparent);
+    color: var(--as-fg);
+    cursor: pointer;
+    font-size: 0.78rem;
+    font-weight: 600;
+    transition: background 0.12s ease, border-color 0.12s ease, opacity 0.12s ease;
+  }
+
+  .as-ai-button:hover:not(:disabled) {
+    border-color: var(--as-accent);
+    background: color-mix(in srgb, var(--as-accent) 26%, transparent);
+  }
+
+  .as-ai-button:disabled {
+    cursor: default;
+    opacity: 0.48;
+  }
+
+  .as-ai-button--loading {
+    opacity: 0.78;
+  }
+
+  .as-ai-button .as-kbd {
+    color: var(--as-fg);
+    border-color: color-mix(in srgb, var(--as-accent) 55%, var(--as-border));
+    background: color-mix(in srgb, var(--as-accent) 20%, transparent);
+  }
+
+  .as-kbd {
+    font-family: var(--font-mono, "JetBrains Mono Variable", ui-monospace, monospace);
+    font-size: 0.7rem;
+    line-height: 1;
+    padding: 3px 6px;
+    border: 1px solid var(--as-border);
+    border-radius: 5px;
+    color: var(--as-muted);
+    background: var(--as-hover);
+  }
+
+  .as-hint :global(.as-kbd) {
+    font-family: var(--font-mono, "JetBrains Mono Variable", ui-monospace, monospace);
+    font-size: 0.7rem;
+    line-height: 1;
+    padding: 3px 6px;
+    border: 1px solid var(--as-border);
+    border-radius: 5px;
+    color: var(--as-muted);
+    background: var(--as-hover);
+  }
+
+  .as-results {
+    max-height: min(56vh, 440px);
+    overflow-y: auto;
+    padding: 6px;
+  }
+
+  .as-results:empty { display: none; }
+
+  /* Result rows are created at runtime in client JS, so they never receive
+     Astro's scope attribute. Use :global() (anchored under the scoped
+     .as-results) so these styles actually apply to them. */
+  .as-results :global(.as-result) {
+    display: block;
+    padding: 9px 11px;
+    border-radius: 8px;
+    border-left: 2px solid transparent;
+    text-decoration: none;
+    color: var(--as-fg);
+    cursor: pointer;
+  }
+
+  .as-results :global(.as-result:hover) {
+    background: var(--as-hover);
+  }
+
+  .as-results :global(.as-result[aria-selected="true"]) {
+    background: color-mix(in srgb, var(--as-fg) 10%, transparent);
+    border-left-color: var(--as-accent);
+  }
+
+  .as-results :global(.as-result[aria-selected="true"] .as-result-title) {
+    color: var(--as-accent);
+  }
+
+  .as-results :global(.as-result-top) {
+    display: flex;
+    align-items: baseline;
+    justify-content: space-between;
+    gap: 12px;
+  }
+
+  .as-results :global(.as-result-title) {
+    font-weight: 600;
+    font-size: 0.92rem;
+    color: var(--as-fg);
+    text-decoration: none;
+  }
+
+  .as-results :global(.as-result-group) {
+    flex: none;
+    font-family: var(--font-mono, "JetBrains Mono Variable", ui-monospace, monospace);
+    font-size: 0.66rem;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    color: var(--as-muted);
+  }
+
+  .as-results :global(.as-result-snippet) {
+    margin-top: 2px;
+    font-size: 0.82rem;
+    line-height: 1.45;
+    color: var(--as-muted);
+    text-decoration: none;
+    display: -webkit-box;
+    -webkit-line-clamp: 2;
+    -webkit-box-orient: vertical;
+    overflow: hidden;
+  }
+
+  .as-results :global(.as-result-heading) {
+    margin-top: 1px;
+    font-size: 0.72rem;
+    color: var(--as-muted);
+    opacity: 0.86;
+  }
+
+  .as-results :global(.as-state) {
+    padding: 22px 16px;
+    text-align: center;
+    color: var(--as-muted);
+    font-size: 0.88rem;
+  }
+
+  .as-results :global(.as-state.as-error) {
+    color: var(--as-accent);
+  }
+
+  /* Empty-state suggested questions. */
+  .as-results :global(.as-suggest-label) {
+    padding: 8px 11px 4px;
+    font-family: var(--font-mono, "JetBrains Mono Variable", ui-monospace, monospace);
+    font-size: 0.66rem;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    color: var(--as-muted);
+  }
+
+  .as-results :global(.as-suggest) {
+    display: block;
+    width: 100%;
+    text-align: left;
+    padding: 9px 11px;
+    border: none;
+    border-left: 2px solid transparent;
+    border-radius: 8px;
+    background: transparent;
+    color: var(--as-fg);
+    font: inherit;
+    font-size: 0.9rem;
+    cursor: pointer;
+  }
+
+  .as-results :global(.as-suggest:hover),
+  .as-results :global(.as-suggest:focus-visible) {
+    background: var(--as-hover);
+    border-left-color: var(--as-accent);
+    outline: none;
+  }
+
+  /* Ask-mode hint row: clicking it (or pressing Enter) runs the agentic ask.
+     Deliberately calm — a quiet prompt, not an alarming orange button. */
+  .as-results :global(.as-ask-row) {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 10px;
+    width: 100%;
+    text-align: left;
+    padding: 11px 12px;
+    border: 1px solid var(--as-border);
+    border-radius: 8px;
+    background: var(--as-hover);
+    color: var(--as-muted);
+    font: inherit;
+    cursor: pointer;
+    transition: border-color 0.12s ease, color 0.12s ease;
+  }
+
+  .as-results :global(.as-ask-row:hover) {
+    border-color: color-mix(in srgb, var(--as-accent) 45%, var(--as-border));
+    color: var(--as-fg);
+  }
+
+  .as-results :global(.as-ask-row-hint) {
+    flex: 1;
+    min-width: 0;
+    font-size: 0.88rem;
+  }
+
+  .as-results :global(.as-ask-row .as-kbd) {
+    flex: none;
+  }
+
+  .as-answer {
+    max-height: min(56vh, 440px);
+    overflow-y: auto;
+    padding: 14px 16px 6px;
+  }
+
+  .as-answer[hidden] { display: none; }
+
+  .as-answer-body {
+    font-size: 0.9rem;
+    line-height: 1.55;
+    color: var(--as-fg);
+  }
+
+  .as-answer-body :global(p) {
+    margin: 0 0 0.7em;
+  }
+
+  .as-answer-body :global(p:last-child) {
+    margin-bottom: 0;
+  }
+
+  .as-answer-body :global(ul),
+  .as-answer-body :global(ol) {
+    margin: 0 0 0.7em;
+    padding-left: 1.3em;
+  }
+
+  .as-answer-body :global(li) {
+    margin: 0.15em 0;
+  }
+
+  .as-answer-body :global(code) {
+    font-family: var(--font-mono, "JetBrains Mono Variable", ui-monospace, monospace);
+    font-size: 0.82em;
+    padding: 1px 5px;
+    border-radius: 5px;
+    background: var(--as-hover);
+  }
+
+  /* Animated tool-calling status (spinner + cycling verb). Built at runtime, so
+     these live under :global() anchored to the scoped .as-answer-body. */
+  .as-answer-body :global(.as-thinking) {
+    display: inline-flex;
+    align-items: baseline;
+    gap: 9px;
+    color: var(--as-muted);
+    font-size: 0.9rem;
+  }
+
+  .as-answer-body :global(.as-thinking-spin) {
+    display: inline-block;
+    width: 1ch;
+    color: var(--as-accent);
+    font-family: var(--font-mono, "JetBrains Mono Variable", ui-monospace, monospace);
+    font-size: 1.05rem;
+    line-height: 1;
+  }
+
+  .as-answer-body :global(.as-thinking-verb) {
+    font-variant-numeric: tabular-nums;
+  }
+
+  .as-answer-body :global(.as-answer-link) {
+    color: var(--as-accent);
+    text-decoration: none;
+    border-bottom: 1px solid color-mix(in srgb, var(--as-accent) 45%, transparent);
+    transition: border-color 0.12s ease;
+  }
+
+  .as-answer-body :global(.as-answer-link:hover) {
+    border-bottom-color: var(--as-accent);
+  }
+
+  /* Streaming caret while tokens are still arriving. */
+  .as-answer-body.is-streaming::after {
+    content: "▌";
+    margin-left: 1px;
+    color: var(--as-accent);
+    animation: as-blink 1s step-end infinite;
+  }
+
+  @keyframes as-blink {
+    50% { opacity: 0; }
+  }
+
+  .as-answer-sources {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 6px;
+    margin-top: 12px;
+    padding-top: 10px;
+    border-top: 1px solid var(--as-border);
+  }
+
+  .as-answer-sources[hidden] { display: none; }
+
+  .as-answer-sources :global(.as-answer-sources-label) {
+    font-family: var(--font-mono, "JetBrains Mono Variable", ui-monospace, monospace);
+    font-size: 0.66rem;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    color: var(--as-muted);
+    margin-right: 2px;
+  }
+
+  .as-answer-sources :global(.as-source-chip) {
+    font-size: 0.74rem;
+    padding: 3px 8px;
+    border: 1px solid var(--as-border);
+    border-radius: 6px;
+    color: var(--as-fg);
+    text-decoration: none;
+    transition: border-color 0.12s ease, color 0.12s ease;
+  }
+
+  .as-answer-sources :global(.as-source-chip:hover) {
+    border-color: var(--as-accent);
+    color: var(--as-accent);
+  }
+
+  .as-searched {
+    padding: 0 16px 9px;
+    color: var(--as-muted);
+    font-size: 0.72rem;
+    opacity: 0.72;
+  }
+
+  .as-searched.as-warning {
+    color: var(--as-accent);
+    opacity: 1;
+  }
+
+  .as-footer {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 10px 16px;
+    border-top: 1px solid var(--as-border);
+    font-size: 0.75rem;
+    color: var(--as-muted);
+  }
+
+  .as-hint { display: flex; align-items: center; gap: 5px; }
+
+  .as-meta {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+  }
+
+  .as-mode {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+  }
+
+  .as-mode:not([hidden]) + .as-brand::before {
+    content: "·";
+    margin-right: 8px;
+    opacity: 0.5;
+  }
+
+  .as-mode-label {
+    font-family: var(--font-mono, "JetBrains Mono Variable", ui-monospace, monospace);
+    font-size: 0.7rem;
+    color: var(--as-muted);
+    opacity: 0.75;
+  }
+
+  .as-mode--off .as-mode-label {
+    text-decoration: line-through;
+    opacity: 0.5;
+  }
+
+  .as-mode-toggle {
+    font-family: var(--font-mono, "JetBrains Mono Variable", ui-monospace, monospace);
+    font-size: 0.7rem;
+    line-height: 1;
+    padding: 2px 5px;
+    border: 1px solid var(--as-border);
+    border-radius: 5px;
+    background: transparent;
+    color: var(--as-muted);
+    cursor: pointer;
+    transition: color 0.12s ease, border-color 0.12s ease;
+  }
+
+  .as-mode-toggle:hover {
+    color: var(--as-accent);
+    border-color: var(--as-accent);
+  }
+
+  .as-brand {
+    font-family: var(--font-mono, "JetBrains Mono Variable", ui-monospace, monospace);
+    letter-spacing: 0.04em;
+  }
+
+  .as-brandlink {
+    color: var(--signal, #e25822);
+    text-decoration: none;
+    font-weight: 600;
+  }
+
+  .as-brandlink:hover {
+    text-decoration: underline;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .as-overlay[open] { animation: none; }
+  }
+
+  @media (max-width: 520px) {
+    .as-ai-label {
+      display: none;
+    }
+
+    .as-ai-button {
+      padding-inline: 8px;
+    }
+  }
+</style>
+
+<script>
+  import { renderMarkdown, sourceBreadcrumb, type Source } from './markdown.ts';
+
+  interface SearchResult {
+    title: string;
+    heading?: string;
+    url: string;
+    group?: string;
+    snippet: string;
+  }
+
+  interface SearchResponse {
+    results?: SearchResult[];
+    searches?: string[];
+    model?: string;
+    mode?: 'keyword' | 'agentic';
+    warning?: string;
+    error?: string;
+  }
+
+  // Braille spinner — reads as a smooth rotating glyph in monospace.
+  const SPIN_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  // Whimsical gerunds, cycled while the agent is tool-calling (à la Claude Code).
+  const THINKING_VERBS = [
+    'Sautéing', 'Percolating', 'Noodling', 'Marinating', 'Conjuring', 'Rummaging',
+    'Foraging', 'Spelunking', 'Distilling', 'Untangling', 'Divining', 'Pondering',
+    'Scheming', 'Brewing', 'Whisking', 'Simmering', 'Excavating', 'Sifting',
+    'Wrangling', 'Cogitating', 'Finagling', 'Tinkering', 'Riffing', 'Mulling',
+  ];
+
+  class HevAskOverlay {
+    private dialog: HTMLDialogElement;
+    private input: HTMLInputElement;
+    private results: HTMLDivElement;
+    private answer: HTMLDivElement;
+    private answerBody: HTMLDivElement;
+    private answerSources: HTMLDivElement;
+    private searched: HTMLDivElement;
+    private askButton: HTMLButtonElement;
+    private askButtonLabel: HTMLElement;
+    private hint: HTMLElement;
+    private modeEl: HTMLElement | null;
+    private modeLabelEl: HTMLElement | null;
+    private modeToggleEl: HTMLButtonElement | null;
+    private model = '';
+    private agentic = true;
+    private endpoint: string;
+    private debounceMs: number;
+    private timer: number | undefined;
+    private controller: AbortController | undefined;
+    private activeMode: 'keyword' | 'agentic' | null = null;
+    private requestSeq = 0;
+    private items: HTMLAnchorElement[] = [];
+    private active = -1;
+    private lastQuery = '';
+    private userSelected = false;
+    private pressOnBackdrop = false;
+    private answerRaf: number | undefined;
+    private thinkTimer: number | undefined;
+    private suggestions: string[] = [];
+    private suggestionsFetched = false;
+    private defaultPlaceholder: string;
+
+    constructor(dialog: HTMLDialogElement) {
+      this.dialog = dialog;
+      this.endpoint = dialog.dataset.endpoint || '/api/ask';
+      this.debounceMs = Number(dialog.dataset.debounce) || 300;
+      this.input = dialog.querySelector('.as-input') as HTMLInputElement;
+      this.defaultPlaceholder = this.input.getAttribute('placeholder') || 'Search the docs…';
+      this.results = dialog.querySelector('.as-results') as HTMLDivElement;
+      this.answer = dialog.querySelector('.as-answer') as HTMLDivElement;
+      this.answerBody = dialog.querySelector('.as-answer-body') as HTMLDivElement;
+      this.answerSources = dialog.querySelector('.as-answer-sources') as HTMLDivElement;
+      this.searched = dialog.querySelector('.as-searched') as HTMLDivElement;
+      this.askButton = dialog.querySelector('.as-ai-button') as HTMLButtonElement;
+      this.askButtonLabel = dialog.querySelector('.as-ai-label') as HTMLElement;
+      this.hint = dialog.querySelector('.as-hint') as HTMLElement;
+      this.modeEl = dialog.querySelector('.as-mode');
+      this.modeLabelEl = dialog.querySelector('.as-mode-label');
+      this.modeToggleEl = dialog.querySelector('.as-mode-toggle');
+      this.agentic = this.readPref();
+      this.askButton.addEventListener('click', (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        this.askAgentic();
+      });
+      this.modeToggleEl?.addEventListener('click', () => this.toggleMode());
+      this.updateModeUI();
+      this.applyModePlaceholder();
+      this.syncAskButton();
+
+      this.input.addEventListener('input', () => this.onInput());
+      this.dialog.addEventListener('keydown', (e) => this.onKeydown(e));
+      this.dialog.addEventListener('close', () => this.reset());
+      // Clicking the backdrop (outside the inner box) closes the dialog. A
+      // `click` resolves to the common ancestor of its mousedown and mouseup
+      // targets, so a drag-select that starts in the input and releases on the
+      // backdrop would otherwise resolve to the dialog and close it. Require the
+      // press to have *started* on the backdrop too, so text selection and
+      // edge-sloppy clicks inside the box never dismiss the overlay.
+      this.dialog.addEventListener('mousedown', (e) => {
+        this.pressOnBackdrop = e.target === this.dialog;
+      });
+      this.dialog.addEventListener('click', (e) => {
+        if (e.target === this.dialog && this.pressOnBackdrop) this.dialog.close();
+      });
+    }
+
+    open() {
+      if (this.dialog.open) return;
+      this.dialog.showModal();
+      this.input.focus();
+      this.input.select();
+      void this.maybeFetchSuggestions();
+      this.showInitial();
+    }
+
+    /**
+     * The suggested questions come from the digest and are served by the
+     * endpoint's GET. Fetch once per session, only when AI is on.
+     */
+    private async maybeFetchSuggestions() {
+      if (this.suggestionsFetched || !this.agentic) return;
+      this.suggestionsFetched = true;
+      try {
+        const res = await fetch(this.endpoint, { method: 'GET', headers: { accept: 'application/json' } });
+        if (!res.ok) return;
+        const data = (await res.json()) as { suggestions?: string[]; model?: string };
+        if (data.model) this.setModel(data.model);
+        this.suggestions = Array.isArray(data.suggestions) ? data.suggestions.filter(Boolean).slice(0, 4) : [];
+        // If the overlay is still open on an empty query, surface them now.
+        if (this.dialog.open && !this.input.value.trim()) this.showInitial();
+      } catch {
+        /* suggestions are a nicety; ignore fetch failures */
+      }
+    }
+
+    /** Empty-state view: suggested questions when asking, otherwise nothing. */
+    private showInitial() {
+      this.clearAnswer();
+      if (this.agentic && this.suggestions.length) {
+        this.renderSuggestions();
+      } else {
+        this.render([]);
+      }
+    }
+
+    private reset() {
+      this.controller?.abort();
+      window.clearTimeout(this.timer);
+      this.timer = undefined;
+      this.activeMode = null;
+      this.requestSeq += 1;
+      this.input.value = '';
+      this.results.innerHTML = '';
+      this.clearAnswer();
+      this.searched.classList.remove('as-warning');
+      this.searched.hidden = true;
+      this.searched.textContent = '';
+      this.items = [];
+      this.active = -1;
+      this.lastQuery = '';
+      this.userSelected = false;
+      this.syncAskButton();
+    }
+
+    private onInput() {
+      window.clearTimeout(this.timer);
+      this.timer = undefined;
+      const q = this.input.value.trim();
+      if (this.activeMode === 'agentic') {
+        this.controller?.abort();
+        this.activeMode = null;
+      }
+      this.syncAskButton();
+      if (!q) {
+        this.controller?.abort();
+        this.showInitial();
+        return;
+      }
+      // Ask-first: once the query is more than one word (a space appears) and AI
+      // is on, stop keyword type-ahead and switch to ask mode — Enter asks.
+      if (this.agentic && /\s/.test(q)) {
+        this.enterAskMode(q);
+        return;
+      }
+      this.timer = window.setTimeout(() => this.searchKeyword(q), this.debounceMs);
+    }
+
+    /** Multi-word query with AI on: present the ask affordance, don't call the model yet. */
+    private enterAskMode(query: string) {
+      window.clearTimeout(this.timer);
+      this.timer = undefined;
+      this.controller?.abort();
+      this.activeMode = null;
+      this.lastQuery = '';
+      this.clearAnswer();
+      this.renderAsk(query);
+      this.syncAskButton();
+    }
+
+    private async searchKeyword(query: string) {
+      if (this.activeMode === 'agentic') return;
+      if (query === this.lastQuery) return;
+      this.lastQuery = query;
+      await this.search(query, 'keyword');
+    }
+
+    private async runAgentic(query: string) {
+      window.clearTimeout(this.timer);
+      this.timer = undefined;
+      this.lastQuery = '';
+      await this.streamAgentic(query);
+    }
+
+    private askAgentic() {
+      const q = this.input.value.trim();
+      if (!q) return;
+      void this.runAgentic(q);
+    }
+
+    private async search(query: string, mode: 'keyword' | 'agentic') {
+      const requestId = this.requestSeq + 1;
+      this.requestSeq = requestId;
+      this.controller?.abort();
+      const controller = new AbortController();
+      this.controller = controller;
+      this.activeMode = mode;
+      this.syncAskButton();
+      this.searched.hidden = true;
+      this.searched.textContent = '';
+      this.searched.classList.remove('as-warning');
+      this.setState('Searching…');
+      const rankingTimer =
+        mode === 'agentic'
+          ? window.setTimeout(() => {
+              if (this.requestSeq === requestId && this.activeMode === 'agentic') this.setState('Ranking…');
+            }, 700)
+          : undefined;
+
+      try {
+        const res = await fetch(this.endpoint, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ query, mode }),
+          signal: controller.signal,
+        });
+        if (rankingTimer) window.clearTimeout(rankingTimer);
+        const contentType = res.headers.get('content-type') || '';
+        if (!contentType.includes('application/json')) {
+          throw new Error(
+            res.status === 404
+              ? 'Search endpoint not found — is the integration loaded? (Restart the dev server.)'
+              : `Unexpected response from search endpoint (${res.status}).`,
+          );
+        }
+        const data = (await res.json()) as SearchResponse;
+        if (!res.ok) throw new Error(data.error || 'Search failed.');
+        if (data.model) this.setModel(data.model);
+        // Ignore stale responses if the query moved on.
+        if (this.requestSeq !== requestId || controller.signal.aborted) return;
+        if (this.input.value.trim() !== query) return;
+        if (!data.results?.length) {
+          this.setState('No results.');
+          return;
+        }
+        const warning =
+          data.warning ||
+          (mode === 'agentic' && data.mode !== 'agentic'
+            ? 'AI search is unavailable; showing keyword matches.'
+            : '');
+        this.render(data.results, data.searches, warning);
+      } catch (err) {
+        if (rankingTimer) window.clearTimeout(rankingTimer);
+        if ((err as Error).name === 'AbortError') return;
+        this.setState((err as Error).message, true);
+      } finally {
+        if (this.requestSeq === requestId) {
+          this.activeMode = null;
+          this.syncAskButton();
+        }
+      }
+    }
+
+    private async streamAgentic(query: string) {
+      const requestId = this.requestSeq + 1;
+      this.requestSeq = requestId;
+      this.controller?.abort();
+      const controller = new AbortController();
+      this.controller = controller;
+      this.activeMode = 'agentic';
+      this.syncAskButton();
+      this.results.innerHTML = '';
+      this.items = [];
+      this.active = -1;
+      this.userSelected = false;
+      this.searched.hidden = true;
+      this.searched.textContent = '';
+      this.searched.classList.remove('as-warning');
+      this.showAnswer();
+      this.startThinking();
+
+      const searches: string[] = [];
+      let sources: Source[] = [];
+      let answer = '';
+      const stale = () =>
+        this.requestSeq !== requestId || controller.signal.aborted || this.input.value.trim() !== query;
+
+      try {
+        const res = await fetch(this.endpoint, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ query, mode: 'agentic' }),
+          signal: controller.signal,
+        });
+        const contentType = res.headers.get('content-type') || '';
+
+        // Graceful degradation (no API key) returns JSON keyword results.
+        if (contentType.includes('application/json')) {
+          const data = (await res.json()) as SearchResponse;
+          if (!res.ok) throw new Error(data.error || 'Search failed.');
+          if (data.model) this.setModel(data.model);
+          if (stale()) return;
+          this.clearAnswer();
+          if (!data.results?.length) {
+            this.setState('No results.');
+            return;
+          }
+          this.render(data.results, data.searches, data.warning || 'AI search is unavailable; showing keyword matches.');
+          return;
+        }
+
+        if (!contentType.includes('text/event-stream') || !res.body) {
+          throw new Error(
+            res.status === 404
+              ? 'Search endpoint not found — is the integration loaded? (Restart the dev server.)'
+              : `Unexpected response from search endpoint (${res.status}).`,
+          );
+        }
+
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder('utf-8');
+        let buffer = '';
+        let started = false;
+
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          let sep: number;
+          while ((sep = buffer.indexOf('\n\n')) !== -1) {
+            const frame = buffer.slice(0, sep);
+            buffer = buffer.slice(sep + 2);
+            const evt = this.parseSseFrame(frame);
+            if (!evt) continue;
+            if (stale()) return;
+
+            if (evt.event === 'search') {
+              const q = (evt.data as { query?: string }).query;
+              if (q) {
+                searches.push(q);
+                this.showSearched(`searching: ${searches.join(', ')}`);
+              }
+            } else if (evt.event === 'sources') {
+              const payload = evt.data as { sources?: Source[]; model?: string };
+              sources = payload.sources || [];
+              if (payload.model) this.setModel(payload.model);
+              this.renderSources(sources);
+            } else if (evt.event === 'token') {
+              if (!started) {
+                started = true;
+                answer = '';
+                this.stopThinking();
+                this.answerBody.classList.add('is-streaming');
+              }
+              answer += (evt.data as { text?: string }).text || '';
+              this.scheduleAnswerRender(answer, sources);
+            } else if (evt.event === 'done') {
+              this.stopThinking();
+              this.flushAnswerRender(answer, sources);
+              this.answerBody.classList.remove('is-streaming');
+              if (searches.length) this.showSearched(`searched: ${searches.join(', ')}`);
+            } else if (evt.event === 'error') {
+              throw new Error((evt.data as { error?: string }).error || 'AI search failed.');
+            }
+          }
+        }
+        this.answerBody.classList.remove('is-streaming');
+      } catch (err) {
+        if ((err as Error).name === 'AbortError') return;
+        if (stale()) return;
+        this.clearAnswer();
+        this.setState((err as Error).message, true);
+      } finally {
+        if (this.requestSeq === requestId) {
+          this.activeMode = null;
+          this.syncAskButton();
+        }
+      }
+    }
+
+    private parseSseFrame(frame: string): { event: string; data: unknown } | null {
+      let event = 'message';
+      const dataLines: string[] = [];
+      for (const line of frame.split('\n')) {
+        if (line.startsWith('event:')) event = line.slice(6).trim();
+        else if (line.startsWith('data:')) dataLines.push(line.slice(5).trim());
+      }
+      if (!dataLines.length) return null;
+      try {
+        return { event, data: JSON.parse(dataLines.join('')) };
+      } catch {
+        return null;
+      }
+    }
+
+    /**
+     * Animated "the agent is working" status: a braille spinner alongside a
+     * whimsical gerund that cycles every so often. Replaces the old static
+     * "Searching…" placeholder while the loop tool-calls, before tokens stream.
+     */
+    private startThinking() {
+      this.stopThinking();
+      this.answerBody.classList.remove('is-streaming');
+      this.answerBody.innerHTML =
+        '<span class="as-thinking"><span class="as-thinking-spin"></span><span class="as-thinking-verb"></span></span>';
+      const spin = this.answerBody.querySelector('.as-thinking-spin') as HTMLElement;
+      const verb = this.answerBody.querySelector('.as-thinking-verb') as HTMLElement;
+      // Start on a different verb each time so repeat asks feel alive.
+      let vi = Math.floor(Math.random() * THINKING_VERBS.length);
+      const setVerb = () => {
+        verb.textContent = `${THINKING_VERBS[vi % THINKING_VERBS.length]}…`;
+      };
+      spin.textContent = SPIN_FRAMES[0];
+      setVerb();
+      const reduce =
+        typeof window.matchMedia === 'function' &&
+        window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+      if (reduce) return; // honour reduced-motion: static spinner + verb, no churn.
+      let fi = 0;
+      let tick = 0;
+      this.thinkTimer = window.setInterval(() => {
+        fi = (fi + 1) % SPIN_FRAMES.length;
+        spin.textContent = SPIN_FRAMES[fi];
+        // ~18 frames × 90ms ≈ 1.6s per verb.
+        if (++tick % 18 === 0) {
+          vi += 1;
+          setVerb();
+        }
+      }, 90);
+    }
+
+    private stopThinking() {
+      if (this.thinkTimer !== undefined) {
+        window.clearInterval(this.thinkTimer);
+        this.thinkTimer = undefined;
+      }
+    }
+
+    private scheduleAnswerRender(answer: string, sources: Source[]) {
+      if (this.answerRaf !== undefined) return;
+      this.answerRaf = window.requestAnimationFrame(() => {
+        this.answerRaf = undefined;
+        this.answerBody.innerHTML = renderMarkdown(answer, sources);
+      });
+    }
+
+    private flushAnswerRender(answer: string, sources: Source[]) {
+      if (this.answerRaf !== undefined) {
+        window.cancelAnimationFrame(this.answerRaf);
+        this.answerRaf = undefined;
+      }
+      this.answerBody.innerHTML = renderMarkdown(answer, sources);
+    }
+
+    private renderSources(sources: Source[]) {
+      this.answerSources.innerHTML = '';
+      if (!sources.length) {
+        this.answerSources.hidden = true;
+        return;
+      }
+      const label = document.createElement('span');
+      label.className = 'as-answer-sources-label';
+      label.textContent = 'Sources';
+      this.answerSources.appendChild(label);
+      for (const source of sources) {
+        const chip = document.createElement('a');
+        chip.className = 'as-source-chip';
+        chip.href = source.url;
+        chip.textContent = sourceBreadcrumb(source);
+        this.answerSources.appendChild(chip);
+      }
+      this.answerSources.hidden = false;
+    }
+
+    private showAnswer() {
+      this.results.innerHTML = '';
+      this.answer.hidden = false;
+      this.answerSources.hidden = true;
+      this.answerSources.innerHTML = '';
+    }
+
+    private clearAnswer() {
+      this.stopThinking();
+      if (this.answerRaf !== undefined) {
+        window.cancelAnimationFrame(this.answerRaf);
+        this.answerRaf = undefined;
+      }
+      this.answer.hidden = true;
+      this.answerBody.classList.remove('is-streaming');
+      this.answerBody.innerHTML = '';
+      this.answerSources.hidden = true;
+      this.answerSources.innerHTML = '';
+    }
+
+    private showSearched(text: string) {
+      this.searched.classList.remove('as-warning');
+      this.searched.textContent = text;
+      this.searched.hidden = false;
+    }
+
+    private setState(message: string, isError = false) {
+      this.clearAnswer();
+      this.items = [];
+      this.active = -1;
+      this.userSelected = false;
+      this.searched.hidden = true;
+      this.searched.textContent = '';
+      this.searched.classList.remove('as-warning');
+      this.results.innerHTML = `<div class="as-state${isError ? ' as-error' : ''}"></div>`;
+      (this.results.firstElementChild as HTMLElement).textContent = message;
+    }
+
+    /** Empty-state suggested questions. Clicking one fills the input and asks it. */
+    private renderSuggestions() {
+      this.results.innerHTML = '';
+      this.items = [];
+      this.active = -1;
+      this.userSelected = false;
+      this.searched.hidden = true;
+      this.searched.textContent = '';
+      this.searched.classList.remove('as-warning');
+
+      const label = document.createElement('div');
+      label.className = 'as-suggest-label';
+      label.textContent = 'Ask anything';
+      this.results.appendChild(label);
+
+      for (const question of this.suggestions) {
+        const row = document.createElement('button');
+        row.type = 'button';
+        row.className = 'as-suggest';
+        row.textContent = question;
+        row.addEventListener('click', () => {
+          this.input.value = question;
+          this.syncAskButton();
+          this.runAgentic(question);
+        });
+        this.results.appendChild(row);
+      }
+    }
+
+    /** Ask-mode affordance: a single primary row that runs the agentic loop. */
+    private renderAsk(query: string) {
+      this.results.innerHTML = '';
+      this.items = [];
+      this.active = -1;
+      this.userSelected = false;
+      this.searched.hidden = true;
+      this.searched.textContent = '';
+      this.searched.classList.remove('as-warning');
+
+      const row = document.createElement('button');
+      row.type = 'button';
+      row.className = 'as-ask-row';
+      const hint = document.createElement('span');
+      hint.className = 'as-ask-row-hint';
+      hint.textContent = 'Press Enter to send your question';
+      const kbd = document.createElement('kbd');
+      kbd.className = 'as-kbd';
+      kbd.textContent = '↵';
+      row.append(hint, kbd);
+      row.addEventListener('click', () => this.runAgentic(query));
+      this.results.appendChild(row);
+    }
+
+    private applyModePlaceholder() {
+      this.input.placeholder = this.agentic ? 'Ask a question, or type to search…' : this.defaultPlaceholder;
+    }
+
+    private readPref(): boolean {
+      try {
+        return localStorage.getItem('hev-ask:mode') !== 'keyword';
+      } catch {
+        return true;
+      }
+    }
+
+    private writePref() {
+      try {
+        localStorage.setItem('hev-ask:mode', this.agentic ? 'agentic' : 'keyword');
+      } catch {
+        /* storage unavailable — preference is session-only */
+      }
+    }
+
+    private setModel(model: string) {
+      this.model = model;
+      this.updateModeUI();
+    }
+
+    private updateModeUI() {
+      if (!this.modeEl || !this.modeLabelEl || !this.modeToggleEl) return;
+      if (this.agentic) {
+        this.modeEl.classList.remove('as-mode--off');
+        this.modeLabelEl.textContent = this.model || 'AI on Enter';
+        this.modeToggleEl.textContent = '✕';
+        this.modeToggleEl.title = 'Disable AI on Enter';
+        this.modeToggleEl.setAttribute('aria-label', 'Disable AI on Enter');
+        this.hint.innerHTML =
+          '<kbd class="as-kbd">↵</kbd> ask AI · <kbd class="as-kbd">↑</kbd><kbd class="as-kbd">↓</kbd> select';
+      } else {
+        this.modeEl.classList.add('as-mode--off');
+        this.modeLabelEl.textContent = 'keyword only';
+        this.modeToggleEl.textContent = 'AI';
+        this.modeToggleEl.title = 'Enable AI on Enter';
+        this.modeToggleEl.setAttribute('aria-label', 'Enable AI on Enter');
+        this.hint.innerHTML =
+          '<kbd class="as-kbd">↑</kbd><kbd class="as-kbd">↓</kbd> navigate <kbd class="as-kbd">↵</kbd> open';
+      }
+      this.modeEl.hidden = false;
+    }
+
+    private toggleMode() {
+      this.agentic = !this.agentic;
+      this.writePref();
+      this.updateModeUI();
+      this.applyModePlaceholder();
+      this.syncAskButton();
+      if (this.agentic) void this.maybeFetchSuggestions();
+      const q = this.input.value.trim();
+      if (!q) {
+        this.showInitial();
+      } else if (this.agentic && /\s/.test(q)) {
+        this.enterAskMode(q);
+      } else {
+        this.lastQuery = '';
+        this.searchKeyword(q);
+      }
+    }
+
+    private syncAskButton() {
+      const hasQuery = Boolean(this.input.value.trim());
+      const isAsking = this.activeMode === 'agentic';
+      this.askButton.disabled = !hasQuery || isAsking;
+      this.askButton.classList.toggle('as-ai-button--loading', isAsking);
+      this.askButtonLabel.textContent = isAsking ? 'Asking' : 'Ask AI';
+      this.askButton.title = hasQuery ? 'Ask AI search' : 'Type a query to ask AI';
+      this.askButton.setAttribute('aria-label', this.askButton.title);
+    }
+
+    private render(results: SearchResult[], searches: string[] = [], warning = '') {
+      this.clearAnswer();
+      this.results.innerHTML = '';
+      this.searched.classList.remove('as-warning');
+      this.searched.hidden = true;
+      this.searched.textContent = '';
+      this.items = [];
+      this.active = -1;
+      this.userSelected = false;
+      for (const r of results) {
+        const a = document.createElement('a');
+        a.className = 'as-result';
+        a.href = r.url;
+        a.setAttribute('role', 'option');
+
+        const top = document.createElement('div');
+        top.className = 'as-result-top';
+        const title = document.createElement('span');
+        title.className = 'as-result-title';
+        title.textContent = r.title;
+        top.appendChild(title);
+        if (r.group) {
+          const group = document.createElement('span');
+          group.className = 'as-result-group';
+          group.textContent = r.group;
+          top.appendChild(group);
+        }
+
+        const heading = document.createElement('div');
+        heading.className = 'as-result-heading';
+        heading.textContent = r.heading ? `${r.group ? `${r.group} › ` : ''}${r.heading}` : '';
+        heading.hidden = !r.heading;
+
+        const snippet = document.createElement('div');
+        snippet.className = 'as-result-snippet';
+        snippet.textContent = r.snippet;
+
+        a.append(top, heading, snippet);
+        a.addEventListener('mousemove', () => this.setActive(this.items.indexOf(a), true));
+        this.results.appendChild(a);
+        this.items.push(a);
+      }
+      if (warning) {
+        const searched = searches.length ? ` searched: ${searches.join(', ')}` : '';
+        this.searched.textContent = `${warning}${searched}`;
+        this.searched.classList.add('as-warning');
+        this.searched.hidden = false;
+      } else if (searches.length) {
+        this.searched.textContent = `searched: ${searches.join(', ')}`;
+        this.searched.hidden = false;
+      }
+      if (this.items.length) this.setActive(0);
+    }
+
+    private setActive(i: number, userSelected = false) {
+      if (i < 0 || i >= this.items.length) return;
+      if (i === this.active) {
+        if (userSelected) this.userSelected = true;
+        return;
+      }
+      this.items[this.active]?.setAttribute('aria-selected', 'false');
+      this.active = i;
+      if (userSelected) this.userSelected = true;
+      const el = this.items[i];
+      el.setAttribute('aria-selected', 'true');
+      el.scrollIntoView({ block: 'nearest' });
+    }
+
+    private onKeydown(e: KeyboardEvent) {
+      // Tab accepts the first suggested question into the input (empty + asking).
+      if (e.key === 'Tab' && !e.shiftKey && this.agentic && !this.input.value.trim() && this.suggestions.length) {
+        e.preventDefault();
+        this.input.value = this.suggestions[0];
+        this.onInput();
+        return;
+      }
+      if (e.key === 'ArrowDown') {
+        e.preventDefault();
+        e.stopPropagation();
+        this.setActive(Math.min(this.active + 1, this.items.length - 1), true);
+      } else if (e.key === 'ArrowUp') {
+        e.preventDefault();
+        e.stopPropagation();
+        this.setActive(Math.max(this.active - 1, 0), true);
+      } else if (e.key === 'Enter') {
+        const el = this.items[this.active];
+        const q = this.input.value.trim();
+        if (el && (this.userSelected || !this.agentic || !q)) {
+          e.preventDefault();
+          e.stopPropagation();
+          window.location.href = el.href;
+        } else if (q && this.agentic) {
+          e.preventDefault();
+          e.stopPropagation();
+          this.runAgentic(q);
+        }
+      }
+    }
+  }
+
+  function init() {
+    const dialog = document.querySelector('.as-overlay') as HTMLDialogElement | null;
+    if (!dialog) return;
+    const overlay = new HevAskOverlay(dialog);
+
+    // Global hotkeys: ⌘K / Ctrl+K anywhere, or "/" when not typing in a field.
+    document.addEventListener('keydown', (e) => {
+      const k = e.key.toLowerCase();
+      const inField =
+        document.activeElement instanceof HTMLElement &&
+        ['input', 'textarea', 'select'].includes(document.activeElement.tagName.toLowerCase());
+      if ((e.metaKey || e.ctrlKey) && k === 'k') {
+        e.preventDefault();
+        overlay.open();
+      } else if (k === '/' && !inField && !dialog.open) {
+        e.preventDefault();
+        overlay.open();
+      }
+    });
+
+    // Any element with [data-hev-ask-open] opens the overlay.
+    document.querySelectorAll('[data-hev-ask-open]').forEach((el) => {
+      el.addEventListener('click', (e) => {
+        e.preventDefault();
+        overlay.open();
+      });
+    });
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', init);
+  } else {
+    init();
+  }
+</script>