app/enhance/ask.ts

Functions

Imports

It imports app/lib/search/ask-keys.mjs, app/lib/search/follow-up.mjs, app/lib/search/sse.mjs. Imported by app/enhance/palette.ts.

Source

1import { labelForUrl, urlForKey } from "~/lib/search/ask-keys.mjs";
2import { splitFollowUp } from "~/lib/search/follow-up.mjs";
3import { answerDelta, takeSseFrames } from "~/lib/search/sse.mjs";
4
5const CHUNKS_EVENT = "chunks";
6
7interface AskCitation {
8  url: string;
9  title: string;
10  isSection: boolean;
11}
12
13interface AskHandle {
14  cancel(): void;
15  /** Settles when the stream has been read to its end, or has failed and said so. */
16  done: Promise<void>;
17}
18
19function el<K extends keyof HTMLElementTagNameMap>(
20  tag: K,
21  className?: string,
22  text?: string,
23): HTMLElementTagNameMap[K] {
24  const node = document.createElement(tag);
25  if (className) node.className = className;
26  if (text) node.textContent = text;
27  return node;
28}
29
30/**
31 * `appendChild`, never `.append()`: with the Workers types in scope the global `Element` is
32 * HTMLRewriter's, whose `append` rejects DOM nodes at compile time.
33 */
34function attach(parent: HTMLElement, ...children: HTMLElement[]): void {
35  for (const child of children) parent.appendChild(child);
36}
37
38/**
39 * The `chunks` event's payload as citations, deduplicated by URL. Same key-to-URL mapping as the
40 * upload path, so a citation cannot disagree with what was indexed.
41 */
42function citationsFromChunks(parsed: unknown): AskCitation[] {
43  const chunks: Array<{ item?: { key?: string } }> = Array.isArray(parsed)
44    ? parsed
45    : [];
46  const seen = new Set<string>();
47  const out: AskCitation[] = [];
48  for (const chunk of chunks) {
49    const url = urlForKey(chunk?.item?.key ?? "");
50    if (!url || seen.has(url)) continue;
51    seen.add(url);
52    out.push({
53      url,
54      title: labelForUrl(url),
55      isSection: url.includes("#"),
56    });
57  }
58  return out;
59}
60
61/** Reads the stream to its end, handing each complete SSE frame to `onFrame`; a read error throws. */
62async function readFrames(
63  stream: ReadableStream<Uint8Array>,
64  onFrame: (eventName: string | undefined, parsed: unknown) => void,
65): Promise<void> {
66  const reader = stream.getReader();
67  const decoder = new TextDecoder();
68  let buffer = "";
69  for (;;) {
70    const { done, value } = await reader.read();
71    if (done) break;
72    buffer += decoder.decode(value, { stream: true });
73
74    const taken = takeSseFrames(buffer);
75    buffer = taken.rest;
76
77    for (const { event: eventName, data: parsed } of taken.frames) onFrame(eventName, parsed);
78  }
79}
80
81/** Every DOM write goes through textContent: generated text is never rendered as HTML. */
82export function ask(container: HTMLElement, question: string): AskHandle {
83  const controller = new AbortController();
84  container.textContent = "";
85  container.hidden = false;
86
87  const panel = el("div", "ask-panel");
88  panel.setAttribute("role", "region");
89  panel.setAttribute("aria-label", "AI answer");
90  // Focusable but not a Tab stop, so focus has somewhere to go when the trigger hides.
91  panel.tabIndex = -1;
92
93  const header = el("div", "ask-header");
94  const badge = el("span", "ask-badge", "AI generated");
95  const note = el("span", "ask-note", "May be wrong. Check the sources.");
96  attach(header, badge, note);
97
98  const body = el("p", "ask-body");
99  body.setAttribute("aria-busy", "true");
100
101  /*
102   * The body is not live: rewritten on every token, it would be announced over and over. This region
103   * exists before anything is written to it, and speaks twice: that the lookup started, then the whole
104   * answer or the failure.
105   */
106  const announcer = el("p", "sr-only");
107  announcer.setAttribute("aria-live", "polite");
108
109  // Not "Thinking...": the request is retrieval over this site's chunks, and an ellipsis reads as stalling.
110  const status = el("p", "ask-status", "Looking it up.");
111  const sources = el("ul", "ask-sources");
112  sources.hidden = true;
113
114  // Hidden until there is one: the model is asked for a follow-up, not required to give one.
115  const followUp = el("p", "ask-followup");
116  followUp.hidden = true;
117
118  attach(panel, header, status, body, sources, followUp, announcer);
119  attach(container, panel);
120  // A frame later, so the region is in the tree before its text changes and the change is heard.
121  requestAnimationFrame(() => {
122    if (!announcer.textContent) announcer.textContent = "Looking it up.";
123  });
124
125  let answer = "";
126  let citations: AskCitation[] = [];
127
128  function renderCitations() {
129    if (citations.length === 0) return;
130    sources.textContent = "";
131    const heading = el("li", "ask-sources-heading", "Sources");
132    attach(sources, heading);
133    /*
134     * Same-origin paths only: a URL that is not one did not come from the corpus, and is dropped
135     * rather than shown unlinked.
136     */
137    let index = 0;
138    for (const citation of citations) {
139      if (!citation.url.startsWith("/") || citation.url.startsWith("//")) continue;
140      index += 1;
141      const item = el("li");
142      const link = el("a");
143      link.href = citation.url;
144      attach(link, el("span", "ask-source-index", `${index}. `), el("span", undefined, citation.title));
145      attach(item, link);
146      if (citation.isSection) {
147        attach(item, el("span", "ask-source-kind", " section"));
148      }
149      attach(sources, item);
150    }
151    if (index === 0) {
152      sources.hidden = true;
153      return;
154    }
155    sources.hidden = false;
156  }
157
158  function fail(message: string) {
159    status.textContent = message;
160    status.hidden = false;
161    body.removeAttribute("aria-busy");
162    announcer.textContent = message;
163  }
164
165  function onChunks(parsed: unknown) {
166    citations = citationsFromChunks(parsed);
167    renderCitations();
168  }
169
170  let firstToken = true;
171
172  function onAnswer(parsed: unknown) {
173    const delta = answerDelta(parsed);
174    if (delta === undefined || delta.length === 0) return;
175    if (firstToken) {
176      status.hidden = true;
177      firstToken = false;
178    }
179    answer += delta;
180    // Split on every frame so the raw "NEXT:" marker never shows in the prose mid-stream.
181    const parts = splitFollowUp(answer);
182    body.textContent = parts.answer;
183    // Rebuilt only when the text changed, not on every frame, so the link is not replaced under a reader.
184    if (parts.followUp && parts.followUp !== followUp.textContent) {
185      followUp.textContent = "";
186      const link = el("a");
187      link.href = `/search?q=${encodeURIComponent(parts.followUp)}`;
188      link.textContent = parts.followUp;
189      attach(followUp, link);
190      followUp.hidden = false;
191    }
192  }
193
194  const done = (async () => {
195    let response: Response;
196    try {
197      // POST because the endpoint bills: a GET would be spendable by crawlers, prefetch or a foreign `<img src>`.
198      response = await fetch("/search/ask", {
199        method: "POST",
200        signal: controller.signal,
201        headers: {
202          accept: "text/event-stream",
203          "content-type": "application/x-www-form-urlencoded",
204        },
205        body: new URLSearchParams({ q: question }),
206      });
207    } catch {
208      if (!controller.signal.aborted) fail("Ask is unavailable.");
209      return;
210    }
211
212    if (!response.ok || !response.body) {
213      fail("Ask is unavailable.");
214      return;
215    }
216
217    try {
218      await readFrames(response.body, (eventName, parsed) => {
219        if (eventName === CHUNKS_EVENT) onChunks(parsed);
220        else onAnswer(parsed);
221      });
222    } catch {
223      if (!controller.signal.aborted) fail("Ask stopped early.");
224      return;
225    }
226
227    body.removeAttribute("aria-busy");
228    if (answer.trim().length === 0) fail("No answer for that one.");
229    else announcer.textContent = `AI answer: ${splitFollowUp(answer).answer}`;
230  })();
231
232  /*
233   * A trigger hidden on click drops focus to <body> (WCAG 2.4.3); focus is caught here, on the answer
234   * it asked for. Focus the caller still holds on something visible is left where it is.
235   */
236  const held = document.activeElement;
237  if (!held || held === document.body || (held instanceof HTMLElement && held.closest("[hidden]"))) {
238    panel.focus();
239  }
240
241  return {
242    done,
243    cancel() {
244      controller.abort();
245      container.textContent = "";
246      container.hidden = true;
247    },
248  };
249}
250
251/**
252 * Guarded on the DOM, not module state, because both bundles run this module on `/search` and two
253 * listeners would stream two billed answers per click.
254 */
255function mountAskTriggers() {
256  for (const mount of document.querySelectorAll<HTMLElement>("[data-ask-mount]")) {
257    const trigger = mount.querySelector<HTMLButtonElement>("[data-ask-trigger]");
258    const container = mount.querySelector<HTMLElement>("[data-ask-container]");
259    if (!trigger || !container) continue;
260    if (trigger.dataset.askBound) continue;
261    trigger.dataset.askBound = "true";
262    const question = () => (mount.dataset.askQuestion ?? "").trim();
263    if (!question()) continue;
264    trigger.hidden = false;
265    // Read at the click, not at binding: the live search rewrites the question as the reader retypes.
266    trigger.addEventListener("click", () => {
267      trigger.hidden = true;
268      ask(container, question());
269    });
270  }
271}
272
273mountAskTriggers();