@dogsbay/plugin-ask 0.2.0-beta.101

package/src/client.ts

@@ -0,0 +1,542 @@
+/**
+ * Client runtime for `@dogsbay/plugin-ask`.
+ *
+ * Renders a multi-turn "Ask AI" conversation in two targets that share one
+ * code path:
+ *  - **Docked panel** — a server-rendered shell (`RightRailAsk.astro`,
+ *    `[data-dba-panel="rail"]`) placed in DocsLayout's `right-rail` slot.
+ *  - **Floating modal** — a body-level button + `<dialog>` built here; the
+ *    fallback on rail-less layouts and the mobile entry when a panel exists.
+ *
+ * Each turn appends to a `.dba-thread`; with `conversational` on (default) the
+ * history is sent as context so follow-ups are understood. Astro view
+ * transitions swap the document, so we mount on `astro:page-load` and tear the
+ * floating widget down on `astro:before-swap` (the docked shell is re-wired).
+ */
+// @ts-expect-error: virtual module resolved by the Dogsbay Vite alias at build.
+import config from "virtual:dogsbay-plugin-config/@dogsbay/plugin-ask";
+import {
+  buildAskRequest,
+  buildChatRequest,
+  buildFeedbackRequest,
+  trimHistory,
+  extractText,
+  parseSources,
+  shouldRetryTurnstile,
+  type ChatMessage,
+  type Source,
+} from "./protocol.js";
+import { renderMarkdown, escapeHtml } from "./md.js";
+import type { AskMode, AskPlacement, AskPosition } from "./schema.js";
+
+interface RuntimeConfig {
+  endpoint: string;
+  site: string;
+  mode: AskMode;
+  buttonLabel: string;
+  title: string;
+  placeholder: string;
+  position: AskPosition;
+  placement: AskPlacement;
+  conversational: boolean;
+  maxTurns: number;
+  persistConversation: boolean;
+  feedback: boolean;
+  linkBase: string;
+  turnstileSitekey: string;
+}
+
+const cfg = config as RuntimeConfig;
+
+// Turnstile token (refreshed per ask). Populated by the widget callbacks.
+let turnstileToken: string | null = null;
+let turnstileScriptLoaded = false;
+
+interface TurnstileApi {
+  reset?: (widget?: unknown) => void;
+}
+function turnstileApi(): TurnstileApi | undefined {
+  return (window as unknown as { turnstile?: TurnstileApi }).turnstile;
+}
+
+function loadTurnstile(): void {
+  if (turnstileScriptLoaded || !cfg.turnstileSitekey) return;
+  turnstileScriptLoaded = true;
+  const w = window as unknown as Record<string, unknown>;
+  w.__dbaTsCb = (t: string) => { turnstileToken = t; };
+  w.__dbaTsExpired = () => { turnstileToken = null; };
+  const s = document.createElement("script");
+  s.src = "https://challenges.cloudflare.com/turnstile/v0/api.js";
+  s.async = true;
+  s.defer = true;
+  document.head.appendChild(s);
+}
+
+function sourcesHtml(sources: Source[]): string {
+  const items = sources
+    .map((s) =>
+      s.href
+        ? `<li><a href="${escapeHtml(s.href)}">${escapeHtml(s.label)}</a></li>`
+        : `<li>${escapeHtml(s.label)}</li>`,
+    )
+    .join("");
+  return `<div class="dba-sources"><div class="dba-sources-title">Sources</div><ul>${items}</ul></div>`;
+}
+
+// ─── Conversation persistence (sessionStorage; tab-scoped; OPT-IN) ───────────
+// Persisting the reader's own conversation lets it survive a page refresh and
+// same-window navigation (e.g. clicking a source link). It is OFF by default —
+// nothing is stored until the reader opts in via "Remember conversation".
+// Tab-scoped, cleared on tab close, never sent anywhere.
+
+const STORE = "dba-ask";
+const OPT_IN = "1";
+const convoKey = () => `${STORE}:convo:${cfg.site}`;
+const optInKey = () => `${STORE}:save:${cfg.site}`;
+
+function isPersistMode(): boolean {
+  return cfg.conversational && cfg.mode !== "search" && cfg.persistConversation;
+}
+function persistOptedIn(): boolean {
+  try { return sessionStorage.getItem(optInKey()) === OPT_IN; } catch { return false; }
+}
+function persistEnabled(): boolean {
+  return isPersistMode() && persistOptedIn();
+}
+function loadStoredHistory(): ChatMessage[] {
+  if (!persistEnabled()) return [];
+  try {
+    const parsed = JSON.parse(sessionStorage.getItem(convoKey()) || "null");
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(
+      (m): m is ChatMessage =>
+        m && (m.role === "user" || m.role === "assistant") && typeof m.content === "string",
+    );
+  } catch { return []; }
+}
+function saveStoredHistory(history: ChatMessage[]): void {
+  if (!persistEnabled()) return;
+  try { sessionStorage.setItem(convoKey(), JSON.stringify(history)); } catch { /* storage off */ }
+}
+function clearStoredHistory(): void {
+  try { sessionStorage.removeItem(convoKey()); } catch { /* ignore */ }
+}
+function setPersistOptIn(optedIn: boolean): void {
+  try {
+    if (optedIn) sessionStorage.setItem(optInKey(), OPT_IN);
+    else { sessionStorage.removeItem(optInKey()); clearStoredHistory(); }
+  } catch { /* ignore */ }
+}
+
+/** POST a prebuilt request body with the current Turnstile token (if any). */
+function postBody(body: object): Promise<Response> {
+  return fetch(cfg.endpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ ...body, ...(turnstileToken ? { turnstileToken } : {}) }),
+  });
+}
+
+/** Resolve once a Turnstile token is available, or after `timeoutMs`. */
+function waitForTurnstileToken(timeoutMs: number): Promise<string | null> {
+  if (turnstileToken) return Promise.resolve(turnstileToken);
+  return new Promise((resolve) => {
+    const start = Date.now();
+    const tick = () => {
+      if (turnstileToken) return resolve(turnstileToken);
+      if (Date.now() - start >= timeoutMs) return resolve(null);
+      setTimeout(tick, 150);
+    };
+    tick();
+  });
+}
+
+/**
+ * POST a thumbs vote for an answer, reusing the question Turnstile-retry path.
+ * Best-effort: failures never disrupt reading. Tokens are single-use, so this
+ * obtains a fresh one and resets afterwards.
+ */
+async function sendFeedback(askId: string, rating: 1 | -1): Promise<void> {
+  const body = buildFeedbackRequest(askId, rating);
+  try {
+    loadTurnstile();
+    if (cfg.turnstileSitekey && !turnstileToken) await waitForTurnstileToken(4000);
+    let res = await postBody(body);
+    if (shouldRetryTurnstile(res.status, !!cfg.turnstileSitekey)) {
+      const token = await waitForTurnstileToken(4000);
+      if (token) res = await postBody(body);
+    }
+  } catch {
+    /* feedback is best-effort */
+  } finally {
+    turnstileApi()?.reset?.();
+    turnstileToken = null;
+  }
+}
+
+/** Render a 👍/👎 helpfulness control under a completed assistant answer. */
+function appendFeedback(turn: HTMLElement, answer: HTMLDivElement): void {
+  if (!cfg.feedback) return;
+  const askId = answer.dataset.askId;
+  if (!askId) return; // no id to correlate (search mode / older proxy / restored)
+
+  const fb = document.createElement("div");
+  fb.className = "dba-feedback";
+  const q = document.createElement("span");
+  q.className = "dba-feedback-q";
+  q.textContent = "Was this helpful?";
+  const up = document.createElement("button");
+  up.type = "button";
+  up.className = "dba-fb dba-fb-up";
+  up.setAttribute("aria-label", "Helpful");
+  up.textContent = "👍";
+  const down = document.createElement("button");
+  down.type = "button";
+  down.className = "dba-fb dba-fb-down";
+  down.setAttribute("aria-label", "Not helpful");
+  down.textContent = "👎";
+
+  const thank = () => {
+    fb.textContent = "Thanks for the feedback.";
+    fb.classList.add("dba-feedback-done");
+  };
+  up.addEventListener("click", () => { void sendFeedback(askId, 1); thank(); });
+  down.addEventListener("click", () => { void sendFeedback(askId, -1); thank(); });
+  fb.append(q, up, down);
+  turn.appendChild(fb);
+}
+
+/** Nearest scrollable ancestor (the rail aside, or the dialog's thread). */
+function scrollParent(el: HTMLElement): HTMLElement | null {
+  let p = el.parentElement;
+  while (p) {
+    const oy = getComputedStyle(p).overflowY;
+    if ((oy === "auto" || oy === "scroll") && p.scrollHeight > p.clientHeight) return p;
+    p = p.parentElement;
+  }
+  return null;
+}
+
+/** Stream a proxy response into an answer element; returns the answer Markdown. */
+async function streamInto(res: Response, answer: HTMLDivElement): Promise<string> {
+  answer.textContent = "";
+  answer.dataset.state = "streaming";
+  // Stamp the answer with the proxy's interaction id so a later thumbs vote can
+  // name this exact answer. Empty when absent (search mode / older proxy).
+  answer.dataset.askId = res.headers.get("X-Ask-Id") ?? "";
+
+  const sc = scrollParent(answer);
+  // Keep the newest content in view as it streams — but only if the reader is
+  // already at the bottom, so we don't yank them up while they re-read earlier.
+  const atBottom = () => !sc || sc.scrollTop + sc.clientHeight >= sc.scrollHeight - 80;
+  const render = (html: string) => {
+    const stick = atBottom();
+    answer.innerHTML = html;
+    if (stick && sc) sc.scrollTop = sc.scrollHeight;
+  };
+
+  const reader = res.body!.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";       // line buffer (don't parse a frame split across reads)
+  let rawAll = "";    // whole stream, for the trailing `event: chunks` sources
+  let answerMd = "";  // accumulated answer markdown
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    const text = decoder.decode(value, { stream: true });
+    rawAll += text;
+    buf += text;
+    const nl = buf.lastIndexOf("\n");
+    if (nl >= 0) {
+      answerMd += extractText(buf.slice(0, nl + 1));
+      buf = buf.slice(nl + 1);
+      render(renderMarkdown(answerMd));
+    }
+  }
+  if (buf) answerMd += extractText(buf);
+  const sources = parseSources(rawAll, cfg.linkBase);
+  render(renderMarkdown(answerMd) + (sources.length ? sourcesHtml(sources) : ""));
+  answer.dataset.state = "done";
+  return answerMd;
+}
+
+function appendUserTurn(thread: HTMLElement, text: string): void {
+  const turn = document.createElement("div");
+  turn.className = "dba-turn dba-turn-user";
+  turn.textContent = text; // textContent — no injection from the question
+  thread.appendChild(turn);
+}
+
+function appendAssistantTurn(thread: HTMLElement): HTMLDivElement {
+  const turn = document.createElement("div");
+  turn.className = "dba-turn dba-turn-assistant";
+  const answer = document.createElement("div");
+  answer.className = "dba-answer";
+  answer.setAttribute("aria-live", "polite");
+  answer.dataset.state = "loading";
+  answer.textContent = "…";
+  turn.appendChild(answer);
+  thread.appendChild(turn);
+  return answer;
+}
+
+interface ConvoEls {
+  form: HTMLFormElement;
+  input: HTMLInputElement;
+  submit: HTMLButtonElement;
+  thread: HTMLElement;
+  newChat?: HTMLButtonElement | null;
+  remember?: HTMLInputElement | null;
+}
+
+/** Re-render a stored conversation into the thread (no streaming). */
+function restoreThread(thread: HTMLElement, history: ChatMessage[]): void {
+  let last: HTMLElement | null = null;
+  for (const m of history) {
+    if (m.role === "user") {
+      appendUserTurn(thread, m.content);
+    } else {
+      const a = appendAssistantTurn(thread);
+      a.dataset.state = "done";
+      a.innerHTML = renderMarkdown(m.content);
+    }
+    last = thread.lastElementChild as HTMLElement | null;
+  }
+  // Land at the bottom of the restored conversation (after a refresh / a
+  // same-window source-link navigation), once layout has settled.
+  if (last) {
+    requestAnimationFrame(() => {
+      const sc = scrollParent(last!);
+      if (sc) sc.scrollTop = sc.scrollHeight;
+      else last!.scrollIntoView({ block: "end" });
+    });
+  }
+}
+
+/**
+ * Wire one conversation surface (docked panel or floating dialog). Each keeps
+ * its own history closure. Shares the stream + Turnstile-retry logic.
+ */
+function wireConversation(els: ConvoEls): void {
+  // Restore a persisted conversation (refresh / same-window navigation).
+  const history: ChatMessage[] = loadStoredHistory();
+  if (history.length) restoreThread(els.thread, history);
+
+  // Reader opt-IN toggle: persistence is off until the reader checks it. On
+  // change, start persisting (saving the current conversation) or stop + clear.
+  if (els.remember) {
+    els.remember.checked = persistOptedIn();
+    els.remember.addEventListener("change", () => {
+      setPersistOptIn(els.remember!.checked);
+      if (els.remember!.checked) saveStoredHistory(history);
+    });
+  }
+
+  const reset = () => {
+    els.thread.innerHTML = "";
+    history.length = 0;
+    clearStoredHistory();
+  };
+  els.newChat?.addEventListener("click", () => {
+    reset();
+    els.input.focus();
+  });
+
+  els.form.addEventListener("submit", async (e) => {
+    e.preventDefault();
+    const query = els.input.value.trim();
+    if (!query) return;
+    els.input.value = "";
+
+    // Single-shot modes show one exchange at a time.
+    const conversational = cfg.conversational && cfg.mode !== "search";
+    if (!conversational) els.thread.innerHTML = "";
+
+    appendUserTurn(els.thread, query);
+    const answer = appendAssistantTurn(els.thread);
+    answer.scrollIntoView?.({ block: "nearest" });
+    els.submit.disabled = true;
+
+    // Build the request body. Conversational answer mode sends trimmed history;
+    // search and non-conversational answer stay single-shot.
+    let body: object;
+    if (cfg.mode === "search") {
+      body = buildAskRequest(cfg.site, query, "search");
+    } else if (conversational) {
+      history.push({ role: "user", content: query });
+      body = buildChatRequest(cfg.site, trimHistory(history, cfg.maxTurns));
+    } else {
+      body = buildAskRequest(cfg.site, query, "answer");
+    }
+
+    try {
+      let res = await postBody(body);
+      // Turnstile race: lazy-loaded on first interaction, so a fast submit can
+      // beat the token and the proxy 403s. Wait once for a fresh token + retry.
+      if (shouldRetryTurnstile(res.status, !!cfg.turnstileSitekey)) {
+        loadTurnstile();
+        if (turnstileToken) {
+          turnstileApi()?.reset?.();
+          turnstileToken = null;
+        }
+        const token = await waitForTurnstileToken(4000);
+        if (token) res = await postBody(body);
+      }
+      if (!res.ok || !res.body) {
+        throw new Error(`Request failed (${res.status})`);
+      }
+      const answerMd = await streamInto(res, answer);
+      // Offer thumbs feedback on the completed answer (no-op in search mode /
+      // when feedback is off / when the proxy stamped no id).
+      appendFeedback(answer.parentElement as HTMLElement, answer);
+      if (conversational) {
+        history.push({ role: "assistant", content: answerMd });
+        saveStoredHistory(history);
+      }
+    } catch (err) {
+      answer.dataset.state = "error";
+      answer.textContent = `Sorry — something went wrong. ${(err as Error).message}`;
+      // Drop the unanswered user turn from history so the next send isn't
+      // skewed by a question that never got a reply.
+      if (conversational && history[history.length - 1]?.role === "user") history.pop();
+    } finally {
+      els.submit.disabled = false;
+      // Turnstile tokens are single-use — refresh for the next question.
+      turnstileApi()?.reset?.();
+      turnstileToken = null;
+    }
+  });
+}
+
+const ROOT_ID = "dba-root";
+
+/**
+ * Wire the server-rendered docked panel if present. Returns whether a docked
+ * shell exists (so the caller knows to mark the floating button mobile-only).
+ */
+function wireDockedPanel(): boolean {
+  const panel = document.querySelector<HTMLElement>('[data-dba-panel="rail"]');
+  if (!panel) return false;
+  if (panel.dataset.dbaWired) return true;
+  panel.dataset.dbaWired = "1";
+
+  const form = panel.querySelector<HTMLFormElement>("[data-dba-form]");
+  const input = panel.querySelector<HTMLInputElement>(".dba-input");
+  const submit = panel.querySelector<HTMLButtonElement>(".dba-submit");
+  const thread = panel.querySelector<HTMLElement>("[data-dba-thread]");
+  if (!form || !input || !submit || !thread) return true;
+
+  // Lazy-load Turnstile on first interaction so a page that merely shows the
+  // docked panel still sets no third-party cookies until the reader engages.
+  input.addEventListener("focus", loadTurnstile, { once: true });
+  wireConversation({
+    form,
+    input,
+    submit,
+    thread,
+    newChat: panel.querySelector<HTMLButtonElement>("[data-dba-newchat]"),
+    remember: panel.querySelector<HTMLInputElement>("[data-dba-remember]"),
+  });
+  return true;
+}
+
+/**
+ * Build + wire the floating button + dialog. `hasDocked` marks the root so CSS
+ * can hide the trigger at desktop widths (where the docked panel is visible).
+ */
+function mountFloating(hasDocked: boolean): void {
+  if (document.getElementById(ROOT_ID)) return;
+
+  const root = document.createElement("div");
+  root.id = ROOT_ID;
+  root.dataset.position = cfg.position;
+  if (hasDocked) root.dataset.hasDocked = "1";
+
+  const button = document.createElement("button");
+  button.type = "button";
+  button.className = "dba-trigger";
+  button.textContent = cfg.buttonLabel;
+  button.setAttribute("aria-haspopup", "dialog");
+
+  const dialog = document.createElement("dialog");
+  dialog.className = "dba-dialog";
+  dialog.setAttribute("aria-label", cfg.title);
+  const tsMarkup = cfg.turnstileSitekey
+    ? `<div class="cf-turnstile dba-turnstile" data-sitekey="${cfg.turnstileSitekey}" data-appearance="interaction-only" data-callback="__dbaTsCb" data-expired-callback="__dbaTsExpired" data-error-callback="__dbaTsExpired"></div>`
+    : "";
+  const newChatMarkup = cfg.conversational
+    ? `<button type="button" class="dba-newchat" data-dba-newchat>New chat</button>`
+    : "";
+  const rememberMarkup = cfg.conversational && cfg.persistConversation
+    ? `<label class="dba-remember"><input type="checkbox" data-dba-remember /> Remember conversation</label>`
+    : "";
+  dialog.innerHTML = `
+    <form class="dba-form" method="dialog" data-dba-form>
+      <header class="dba-header">
+        <h2 class="dba-title"></h2>
+        <div class="dba-header-actions">
+          ${newChatMarkup}
+          <button type="button" class="dba-close" aria-label="Close">×</button>
+        </div>
+      </header>
+      ${rememberMarkup}
+      <div class="dba-thread" data-dba-thread></div>
+      <div class="dba-inputrow">
+        <input class="dba-input" type="text" autocomplete="off" enterkeyhint="search" />
+        <button type="submit" class="dba-submit">Ask</button>
+      </div>
+      ${tsMarkup}
+      ${rememberMarkup}
+    </form>
+  `;
+
+  // textContent (not innerHTML) for user-configurable strings — no injection.
+  dialog.querySelector<HTMLHeadingElement>(".dba-title")!.textContent = cfg.title;
+  const input = dialog.querySelector<HTMLInputElement>(".dba-input")!;
+  input.placeholder = cfg.placeholder;
+  const form = dialog.querySelector<HTMLFormElement>(".dba-form")!;
+  const submit = dialog.querySelector<HTMLButtonElement>(".dba-submit")!;
+  const thread = dialog.querySelector<HTMLElement>("[data-dba-thread]")!;
+
+  button.addEventListener("click", () => {
+    // Lazy-load Turnstile only when the user engages, so normal page loads set
+    // no third-party cookies (Lighthouse-clean) and don't fetch the widget.
+    loadTurnstile();
+    dialog.showModal();
+    input.focus();
+  });
+  dialog.querySelector<HTMLButtonElement>(".dba-close")!.addEventListener("click", () => dialog.close());
+
+  wireConversation({
+    form,
+    input,
+    submit,
+    thread,
+    newChat: dialog.querySelector<HTMLButtonElement>("[data-dba-newchat]"),
+    remember: dialog.querySelector<HTMLInputElement>("[data-dba-remember]"),
+  });
+
+  root.append(button, dialog);
+  document.body.appendChild(root);
+}
+
+function mount(): void {
+  if (typeof document === "undefined") return;
+  const hasDocked = wireDockedPanel();
+  mountFloating(hasDocked);
+}
+
+function unmount(): void {
+  if (typeof document === "undefined") return;
+  document.getElementById(ROOT_ID)?.remove();
+}
+
+if (typeof document !== "undefined") {
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", mount);
+  } else {
+    mount();
+  }
+  document.addEventListener("astro:page-load", mount);
+  document.addEventListener("astro:before-swap", unmount);
+}