feat(docs): user feedback + surfaced error frames in docs ask widget (#23288)

critesjosh · web-flow · commit 9047030ac81d · 2026-05-14T19:59:25.000Z
## Summary Two small changes to the `AztecDocsWidget` (the in-docs "Ask Aztec" panel that talks to honk-ai): ### 1. User feedback (thumbs up / down on assistant replies) After an assistant message finishes streaming, render thumbs-up / thumbs-down buttons. Clicking one POSTs to `${apiHost}/api/feedback` with `{ conversation_id, question_index, feedback: "like" | "dislike", api_key }` (matching honk-ai's existing `SubmitFeedback` route in `application/api/answer/routes/feedback.py`). The choice is locked client-side (`feedbackByIndex` per-message-index) so a user can vote once; both buttons become disabled after the first vote, with the active choice highlighted. Files: - `docs/src/components/AztecDocsWidget/Icons.jsx` — `thumbUp`/`thumbDown` SVGs. - `docs/src/components/AztecDocsWidget/Message.jsx` — feedback row, only for assistant messages with a non-empty `response`, hidden while streaming. - `docs/src/components/AztecDocsWidget/Panel.jsx` — passes the `onFeedback` callback down. - `docs/src/components/AztecDocsWidget/index.jsx` — `handleFeedback`, marks the message as voted optimistically and short-circuits repeat clicks. On POST failure, the optimistic mark is reverted and an inline "Couldn't save feedback." note is shown so the user can retry. - `docs/src/components/AztecDocsWidget/sendFeedback.js` — small fetch helper that throws on non-2xx so the caller can surface the failure. ### 2. Surface backend errors to the user honk-ai PR #129 changed `complete_stream` to emit a `type: "error"` SSE frame with the sanitized real cause (timeout / 429 / 503 / …) instead of the generic "Please try again later". The docs widget previously consumed only `answer` / `source` / `id` / `end` frames and silently dropped `error` frames. This PR adds an `onError` path: - `streamAnswer.js` — branch on `type === "error"` and invoke a new `onError(message)` callback, reading `parsed.error` to match honk-ai's frame shape (`{"type": "error", "error": "..."}`). - `index.jsx` — store the error on the active assistant message as `error: <text>`, stop the streaming spinner. - `Message.jsx` — when `message.error` is set, render the body inside a vermillion `[error]` alert box so the user actually sees what went wrong (rate limit, upstream timeout, etc.) instead of a stalled empty bubble. Together with honk-ai #129 this means: backend failures now reach the docs widget user with a real, actionable cause; and we start collecting per-message feedback signal from the docs surface. ## Related - honk-ai #129 (server-side error relay + per-message logging) — required for the error path to deliver useful messages. - Thread context: docs-widget gap identified in the activity report (https://gist.github.com/AztecBot/4932e495f8d622cc3c82c1776e37f891). ## Test plan - [ ] `yarn workspace docs start` and exercise the widget: trigger a normal answer, click thumbs up/down, verify a POST to `/api/feedback` with the expected payload and that both buttons lock after one click. - [ ] Click the opposite thumb after voting; verify nothing happens (no second POST, state unchanged). - [ ] Simulate a backend error frame (e.g. point widget at a stub that emits `{"type":"error","error":"upstream timeout"}`); verify the vermillion alert renders with the real text and the spinner stops. - [ ] Simulate a feedback POST failure (e.g. 500); verify the "Couldn't save feedback." note renders and the user can re-vote. --- *Created by [claudebox](https://claudebox.work/v2/sessions/0334e56dbe6330cd) · group: `slackbot`*
diff --git a/docs/src/components/AztecDocsWidget/Icons.jsx b/docs/src/components/AztecDocsWidget/Icons.jsx
@@ -154,4 +154,34 @@ export const Icons = {
       <path d="M3 21l7-7" />
     </svg>
   ),
+  thumbUp: (p) => (
+    <svg
+      viewBox="0 0 24 24"
+      width={p.size || 13}
+      height={p.size || 13}
+      fill={p.filled ? "currentColor" : "none"}
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M7 11v9H4a1 1 0 0 1-1-1v-7a1 1 0 0 1 1-1h3z" />
+      <path d="M7 11l5-8a2 2 0 0 1 2 2v4h5a2 2 0 0 1 2 2l-2 7a2 2 0 0 1-2 1H7" />
+    </svg>
+  ),
+  thumbDown: (p) => (
+    <svg
+      viewBox="0 0 24 24"
+      width={p.size || 13}
+      height={p.size || 13}
+      fill={p.filled ? "currentColor" : "none"}
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M17 13V4h3a1 1 0 0 1 1 1v7a1 1 0 0 1-1 1h-3z" />
+      <path d="M17 13l-5 8a2 2 0 0 1-2-2v-4H5a2 2 0 0 1-2-2l2-7a2 2 0 0 1 2-1h10" />
+    </svg>
+  ),
 };
diff --git a/docs/src/components/AztecDocsWidget/Message.jsx b/docs/src/components/AztecDocsWidget/Message.jsx
@@ -33,10 +33,46 @@ export function AssistantBody({
   text,
   sources,
   thinking,
+  error,
   tokens,
   mdComponents,
+  feedback,
+  feedbackError,
+  onFeedback,
+  showFeedback,
 }) {
   const { isInk, accentColor, panelFg, panelFg2 } = tokens;
+  const feedbackBtn = (kind) => {
+    const Icon = kind === "like" ? Icons.thumbUp : Icons.thumbDown;
+    const active = feedback === kind;
+    const dimmed = feedback && !active;
+    const label = kind === "like" ? "Helpful" : "Not helpful";
+    return (
+      <button
+        type="button"
+        onClick={() => onFeedback?.(kind)}
+        disabled={!onFeedback || !!feedback}
+        title={label}
+        aria-label={label}
+        aria-pressed={active}
+        style={{
+          width: 26,
+          height: 26,
+          padding: 0,
+          border: `1px solid ${isInk ? "rgba(242,238,225,0.2)" : "var(--azw-ink-tint-1)"}`,
+          background: active ? accentColor : "transparent",
+          color: active ? "var(--azw-ink)" : dimmed ? panelFg2 : panelFg,
+          cursor: onFeedback && !feedback ? "pointer" : "default",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          opacity: dimmed ? 0.5 : 1,
+        }}
+      >
+        <Icon size={12} filled={active} />
+      </button>
+    );
+  };
   return (
     <div
       style={{
@@ -107,6 +143,26 @@ export function AssistantBody({
             </ReactMarkdown>
           ) : null}
         </div>
+        {error && (
+          <div
+            role="alert"
+            style={{
+              marginTop: text ? 10 : 0,
+              padding: "8px 10px",
+              border: `1px solid var(--azw-vermillion, ${accentColor})`,
+              background: isInk
+                ? "rgba(217, 74, 58, 0.12)"
+                : "rgba(217, 74, 58, 0.08)",
+              color: "var(--azw-vermillion, #d94a3a)",
+              fontFamily: "var(--azw-font-sans)",
+              fontSize: 12.5,
+              lineHeight: 1.45,
+              letterSpacing: "-0.01em",
+            }}
+          >
+            {error}
+          </div>
+        )}
         {sources?.length > 0 && (
           <div style={{ marginTop: 10 }}>
             <div
@@ -153,6 +209,38 @@ export function AssistantBody({
             </div>
           </div>
         )}
+        {showFeedback && (
+          <div
+            style={{
+              marginTop: 10,
+              display: "flex",
+              alignItems: "center",
+              gap: 8,
+              fontFamily: "var(--azw-font-mono)",
+              fontSize: 10,
+              letterSpacing: "0.1em",
+              textTransform: "uppercase",
+              color: panelFg2,
+            }}
+          >
+            <span>Was this helpful?</span>
+            <div style={{ display: "flex", gap: 6 }}>
+              {feedbackBtn("like")}
+              {feedbackBtn("dislike")}
+            </div>
+            {feedback && !feedbackError && (
+              <span style={{ color: panelFg2 }}>Thanks for the feedback.</span>
+            )}
+            {feedbackError && (
+              <span
+                style={{ color: "var(--azw-vermillion, #d94a3a)" }}
+                role="alert"
+              >
+                Couldn't save feedback.
+              </span>
+            )}
+          </div>
+        )}
       </div>
     </div>
   );
diff --git a/docs/src/components/AztecDocsWidget/Panel.jsx b/docs/src/components/AztecDocsWidget/Panel.jsx
@@ -26,6 +26,10 @@ export default function Panel({
   expanded,
   onToggleExpanded,
   scrollRef,
+  feedbackByIndex,
+  feedbackErrorsByIndex,
+  onFeedback,
+  conversationId,
 }) {
   const {
     isInk,
@@ -224,16 +228,28 @@ export default function Panel({
                 const text = isLast && streaming ? streamText : m.response;
                 const sources = isLast && streaming ? streamSources : m.sources;
                 const isStreamingLast = isLast && streaming;
+                const error = isStreamingLast ? null : m.error;
+                const showFeedback =
+                  !isStreamingLast && !!m.response && !!conversationId;
                 return (
                   <React.Fragment key={i}>
                     <UserBubble text={m.prompt} tokens={tokens} />
-                    {(text || isStreamingLast) && (
+                    {(text || isStreamingLast || error) && (
                       <AssistantBody
                         text={text}
                         sources={sources}
                         thinking={isStreamingLast}
+                        error={error}
                         tokens={tokens}
                         mdComponents={mdComponents}
+                        showFeedback={showFeedback}
+                        feedback={feedbackByIndex?.[i]}
+                        feedbackError={feedbackErrorsByIndex?.[i]}
+                        onFeedback={
+                          showFeedback
+                            ? (kind) => onFeedback?.(i, kind)
+                            : undefined
+                        }
                       />
                     )}
                   </React.Fragment>
diff --git a/docs/src/components/AztecDocsWidget/index.jsx b/docs/src/components/AztecDocsWidget/index.jsx
@@ -3,6 +3,7 @@ import "./styles.css";
 import { DEFAULT_SUGGESTED, getTheme } from "./theme";
 import { makeMarkdownComponents } from "./markdown";
 import { streamAnswer } from "./streamAnswer";
+import { sendFeedback } from "./sendFeedback";
 import LauncherButton from "./LauncherButton";
 import Panel from "./Panel";
 
@@ -28,6 +29,8 @@ export default function AztecDocsWidget({
   const [streamText, setStreamText] = useState("");
   const [streamSources, setStreamSources] = useState([]);
   const [conversationId, setConversationId] = useState(null);
+  const [feedbackByIndex, setFeedbackByIndex] = useState({});
+  const [feedbackErrorsByIndex, setFeedbackErrorsByIndex] = useState({});
   const scrollRef = useRef(null);
   const abortRef = useRef(null);
 
@@ -70,6 +73,7 @@ export default function AztecDocsWidget({
 
     let acc = "";
     let sources = [];
+    let errorMessage = null;
     try {
       await streamAnswer({
         apiHost,
@@ -87,18 +91,27 @@ export default function AztecDocsWidget({
           setStreamSources(sources);
         },
         onConversationId: (id) => setConversationId(id),
+        onError: (message) => {
+          errorMessage = message;
+        },
         onDone: () => {},
       });
     } catch (err) {
       if (err.name !== "AbortError") {
-        acc =
-          acc || "Something went wrong fetching an answer. Please try again.";
+        errorMessage =
+          errorMessage ||
+          "Something went wrong fetching an answer. Please try again.";
       }
     }
 
     setMessages((prev) => {
       const copy = [...prev];
-      copy[copy.length - 1] = { prompt: question, response: acc, sources };
+      copy[copy.length - 1] = {
+        prompt: question,
+        response: acc,
+        sources,
+        error: errorMessage,
+      };
       return copy;
     });
     setStreaming(false);
@@ -113,6 +126,36 @@ export default function AztecDocsWidget({
     setStreamText("");
     setStreamSources([]);
     setConversationId(null);
+    setFeedbackByIndex({});
+    setFeedbackErrorsByIndex({});
+  }
+
+  async function handleFeedback(messageIndex, kind) {
+    if (!conversationId) return;
+    if (feedbackByIndex[messageIndex]) return;
+    setFeedbackByIndex((prev) => ({ ...prev, [messageIndex]: kind }));
+    setFeedbackErrorsByIndex((prev) => {
+      if (!prev[messageIndex]) return prev;
+      const copy = { ...prev };
+      delete copy[messageIndex];
+      return copy;
+    });
+    try {
+      await sendFeedback({
+        apiHost,
+        apiKey,
+        conversationId,
+        questionIndex: messageIndex,
+        feedback: kind,
+      });
+    } catch (err) {
+      setFeedbackByIndex((prev) => {
+        const copy = { ...prev };
+        delete copy[messageIndex];
+        return copy;
+      });
+      setFeedbackErrorsByIndex((prev) => ({ ...prev, [messageIndex]: true }));
+    }
   }
 
   return (
@@ -148,6 +191,10 @@ export default function AztecDocsWidget({
           expanded={expanded}
           onToggleExpanded={() => setExpanded((v) => !v)}
           scrollRef={scrollRef}
+          conversationId={conversationId}
+          feedbackByIndex={feedbackByIndex}
+          feedbackErrorsByIndex={feedbackErrorsByIndex}
+          onFeedback={handleFeedback}
         />
       )}
     </div>
diff --git a/docs/src/components/AztecDocsWidget/sendFeedback.js b/docs/src/components/AztecDocsWidget/sendFeedback.js
@@ -0,0 +1,27 @@
+export async function sendFeedback({
+  apiHost,
+  apiKey,
+  conversationId,
+  questionIndex,
+  feedback,
+  signal,
+}) {
+  if (!conversationId || questionIndex == null) {
+    throw new Error("Feedback requires conversationId and questionIndex");
+  }
+  const res = await fetch(`${apiHost.replace(/\/$/, "")}/api/feedback`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      conversation_id: conversationId,
+      question_index: questionIndex,
+      feedback,
+      api_key: apiKey,
+    }),
+    signal,
+  });
+  if (!res.ok) {
+    throw new Error(`DocsGPT feedback failed: ${res.status}`);
+  }
+  return res.json().catch(() => ({}));
+}
diff --git a/docs/src/components/AztecDocsWidget/streamAnswer.js b/docs/src/components/AztecDocsWidget/streamAnswer.js
@@ -7,6 +7,7 @@ export async function streamAnswer({
   onToken,
   onSource,
   onConversationId,
+  onError,
   onDone,
   signal,
 }) {
@@ -56,6 +57,14 @@ export async function streamAnswer({
         onSource(sources);
       } else if (parsed.type === "id" && parsed.id) {
         onConversationId(parsed.id);
+      } else if (parsed.type === "error") {
+        const message =
+          typeof parsed.error === "string" && parsed.error.trim()
+            ? parsed.error
+            : "Something went wrong generating an answer.";
+        onError?.(message);
+        onDone();
+        return;
       } else if (parsed.type === "end") {
         onDone();
         return;
