@dogsbay/plugin-ask 0.2.0-beta.87 → 0.2.0-beta.89

package/src/client.ts

@@ -1,22 +1,30 @@
 /**
  * Client runtime for `@dogsbay/plugin-ask`.
  *
- * Runs for side effects on every page. Two render targets share one code path:
- *
+ * 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"]`) that DocsLayout places in its `right-rail`
- *    slot. Visible on desktop; hidden < lg because the rail is `hidden lg:block`.
- *  - **Floating modal** — a body-level button + `<dialog>` built here. Used when
- *    there's no rail (floating placement, wide/API pages) and as the mobile
- *    entry when a docked panel exists.
+ *    `[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.
  *
- * 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
- * part of the swapped document, so it's re-wired each navigation).
+ * 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, extractText, parseSources, type Source } from "./protocol.js";
+import {
+  buildAskRequest,
+  buildChatRequest,
+  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";
 
@@ -29,6 +37,9 @@ interface RuntimeConfig {
   placeholder: string;
   position: AskPosition;
   placement: AskPlacement;
+  conversational: boolean;
+  maxTurns: number;
+  persistConversation: boolean;
   linkBase: string;
   turnstileSitekey: string;
 }
@@ -63,83 +74,262 @@ function sourcesHtml(sources: Source[]): string {
   const items = sources
     .map((s) =>
       s.href
-        ? `<li><a href="${escapeHtml(s.href)}" target="_blank" rel="noopener noreferrer">${escapeHtml(s.label)}</a></li>`
+        ? `<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>`;
 }
 
-interface AskEls {
+// ─── Conversation persistence (sessionStorage; tab-scoped) ───────────────────
+// Persisting the reader's own conversation lets it survive a page refresh and
+// same-window navigation (e.g. clicking a source link). Tab-scoped, cleared on
+// tab close, never sent anywhere. Gated by config + a per-tab reader opt-out.
+
+const STORE = "dba-ask";
+const OPT_OUT = "0";
+const convoKey = () => `${STORE}:convo:${cfg.site}`;
+const optOutKey = () => `${STORE}:save:${cfg.site}`;
+
+function isPersistMode(): boolean {
+  return cfg.conversational && cfg.mode !== "search" && cfg.persistConversation;
+}
+function persistOptedOut(): boolean {
+  try { return sessionStorage.getItem(optOutKey()) === OPT_OUT; } catch { return false; }
+}
+function persistEnabled(): boolean {
+  return isPersistMode() && !persistOptedOut();
+}
+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 setPersistOptOut(optedOut: boolean): void {
+  try {
+    if (optedOut) { sessionStorage.setItem(optOutKey(), OPT_OUT); clearStoredHistory(); }
+    else sessionStorage.removeItem(optOutKey());
+  } 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();
+  });
+}
+
+/** 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";
+
+  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;
-  answer: HTMLDivElement;
   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 {
+  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);
+    }
+  }
 }
 
 /**
- * The one ask flow: POST the question, stream the answer, render Markdown +
- * a Sources list. Shared by the docked panel and the floating dialog.
+ * Wire one conversation surface (docked panel or floating dialog). Each keeps
+ * its own history closure. Shares the stream + Turnstile-retry logic.
  */
-async function runAsk({ input, answer, submit }: AskEls): Promise<void> {
-  const query = input.value.trim();
-  if (!query) return;
+function wireConversation(els: ConvoEls): void {
+  // Restore a persisted conversation (refresh / same-window navigation).
+  const history: ChatMessage[] = loadStoredHistory();
+  if (history.length) restoreThread(els.thread, history);
 
-  submit.disabled = true;
-  answer.dataset.state = "loading";
-  answer.textContent = "…";
-
-  try {
-    const res = await fetch(cfg.endpoint, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        ...buildAskRequest(cfg.site, query, cfg.mode),
-        ...(turnstileToken ? { turnstileToken } : {}),
-      }),
+  // Reader opt-out toggle: reflect the stored preference, and on change
+  // start/stop persisting (clearing storage on opt-out).
+  if (els.remember) {
+    els.remember.checked = !persistOptedOut();
+    els.remember.addEventListener("change", () => {
+      setPersistOptOut(!els.remember!.checked);
+      if (els.remember!.checked) saveStoredHistory(history);
     });
-    if (!res.ok || !res.body) {
-      throw new Error(`Request failed (${res.status})`);
-    }
-    answer.textContent = "";
-    answer.dataset.state = "streaming";
-    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);
-        answer.innerHTML = renderMarkdown(answerMd);
-      }
-    }
-    if (buf) answerMd += extractText(buf);
-    const sources = parseSources(rawAll, cfg.linkBase);
-    answer.innerHTML = renderMarkdown(answerMd) + (sources.length ? sourcesHtml(sources) : "");
-    answer.dataset.state = "done";
-  } catch (err) {
-    answer.dataset.state = "error";
-    answer.textContent = `Sorry — something went wrong. ${(err as Error).message}`;
-  } finally {
-    submit.disabled = false;
-    // Turnstile tokens are single-use — refresh for the next question.
-    turnstileApi()?.reset?.();
-    turnstileToken = null;
   }
-}
 
-function wireForm(els: AskEls): void {
-  els.form.addEventListener("submit", (e) => {
+  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();
-    void runAsk(els);
+    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);
+      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;
+    }
   });
 }
 
@@ -147,8 +337,7 @@ const ROOT_ID = "dba-root";
 
 /**
  * Wire the server-rendered docked panel if present. Returns whether a docked
- * shell exists on the page (so the caller knows to mark the floating button as
- * a mobile-only entry). Idempotent via a `data-dba-wired` marker.
+ * 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"]');
@@ -158,14 +347,21 @@ function wireDockedPanel(): boolean {
 
   const form = panel.querySelector<HTMLFormElement>("[data-dba-form]");
   const input = panel.querySelector<HTMLInputElement>(".dba-input");
-  const answer = panel.querySelector<HTMLDivElement>(".dba-answer");
   const submit = panel.querySelector<HTMLButtonElement>(".dba-submit");
-  if (!form || !input || !answer || !submit) return true;
+  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 });
-  wireForm({ form, input, answer, submit });
+  wireConversation({
+    form,
+    input,
+    submit,
+    thread,
+    newChat: panel.querySelector<HTMLButtonElement>("[data-dba-newchat]"),
+    remember: panel.querySelector<HTMLInputElement>("[data-dba-remember]"),
+  });
   return true;
 }
 
@@ -193,18 +389,28 @@ function mountFloating(hasDocked: boolean): void {
   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 checked /> Remember conversation</label>`
+    : "";
   dialog.innerHTML = `
     <form class="dba-form" method="dialog" data-dba-form>
       <header class="dba-header">
         <h2 class="dba-title"></h2>
-        <button type="button" class="dba-close" aria-label="Close">×</button>
+        <div class="dba-header-actions">
+          ${newChatMarkup}
+          <button type="button" class="dba-close" aria-label="Close">×</button>
+        </div>
       </header>
+      <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}
-      <div class="dba-answer" aria-live="polite" tabindex="-1"></div>
+      ${rememberMarkup}
     </form>
   `;
 
@@ -212,9 +418,9 @@ function mountFloating(hasDocked: boolean): void {
   dialog.querySelector<HTMLHeadingElement>(".dba-title")!.textContent = cfg.title;
   const input = dialog.querySelector<HTMLInputElement>(".dba-input")!;
   input.placeholder = cfg.placeholder;
-  const answer = dialog.querySelector<HTMLDivElement>(".dba-answer")!;
   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
@@ -225,7 +431,14 @@ function mountFloating(hasDocked: boolean): void {
   });
   dialog.querySelector<HTMLButtonElement>(".dba-close")!.addEventListener("click", () => dialog.close());
 
-  wireForm({ form, input, answer, submit });
+  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);
@@ -233,16 +446,12 @@ function mountFloating(hasDocked: boolean): void {
 
 function mount(): void {
   if (typeof document === "undefined") return;
-  // Wire the docked panel first; its presence decides whether the floating
-  // button is a full widget (no rail) or just the mobile entry (rail present).
   const hasDocked = wireDockedPanel();
   mountFloating(hasDocked);
 }
 
 function unmount(): void {
   if (typeof document === "undefined") return;
-  // Only the floating widget is ours to remove; the docked shell is part of the
-  // document Astro swaps, and is re-wired by mount() on the next page-load.
   document.getElementById(ROOT_ID)?.remove();
 }
 

package/src/styles.css

@@ -28,8 +28,54 @@
 /* The docked form fills the rail column. */
 .dba-panel .dba-form { padding: 0; gap: 0.5rem; }
 .dba-panel .dba-title { font-size: 0.95rem; }
-/* The rail aside scrolls, so let the answer grow rather than scroll internally. */
+/* The rail aside scrolls, so let answers grow rather than scroll internally. */
 .dba-panel .dba-answer { max-height: none; }
+/* Keep the input visible while the rail scrolls the conversation. */
+.dba-panel .dba-inputrow {
+  position: sticky;
+  bottom: 0;
+  background: var(--dba-surface);
+  padding-block: 0.4rem;
+}
+
+/* Conversation thread (docked panel + floating dialog). */
+.dba-thread { display: flex; flex-direction: column; gap: 0.75rem; }
+.dba-thread:empty { display: none; }
+.dba-turn-user {
+  align-self: flex-end;
+  max-width: 92%;
+  padding: 0.4rem 0.7rem;
+  white-space: pre-wrap;
+  background: color-mix(in srgb, var(--dba-accent) 14%, transparent);
+  border-radius: var(--dba-radius);
+}
+.dba-turn-assistant { align-self: stretch; }
+.dba-header-actions { display: flex; align-items: center; gap: 0.4rem; }
+.dba-newchat {
+  font: inherit;
+  font-size: 0.78rem;
+  padding: 0.2rem 0.5rem;
+  cursor: pointer;
+  color: var(--dba-text);
+  opacity: 0.7;
+  background: none;
+  border: 1px solid var(--dba-border);
+  border-radius: var(--dba-radius);
+}
+.dba-newchat:hover { opacity: 1; }
+/* In the modal, bound the thread so it scrolls and the input stays visible. */
+.dba-dialog .dba-thread { max-height: 55vh; overflow-y: auto; }
+
+/* Reader opt-out for conversation persistence. */
+.dba-remember {
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+  font-size: 0.78rem;
+  opacity: 0.75;
+  cursor: pointer;
+}
+.dba-remember input { cursor: pointer; }
 
 .dba-trigger {
   position: fixed;