blume 2.0.2 → 2.1.0

package/src/components/islands/assistant.tsx

@@ -4,10 +4,14 @@ import { useEffect, useRef, useState } from "react";
 import type { FormEvent, KeyboardEvent as ReactKeyboardEvent } from "react";
 import { createPortal } from "react-dom";
 
+import type { CaptchaSettings } from "../../captcha/schema.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import { copyText } from "../copy-feedback.ts";
-import { joinBase, prefixBase } from "./base-path.ts";
+import { joinBase, mountBase } from "./base-path.ts";
+import { splitCode, withCode } from "./code-question.ts";
+import type { CodeAttachment } from "./code-question.ts";
 import { useAssistant } from "./hooks.ts";
+import { supportHref } from "./support-link.ts";
 
 /** A resolved empty-state prompt; `icon` is ready-to-inline SVG (or null). */
 interface Suggestion {
@@ -25,6 +29,8 @@ interface AssistantIcons {
   clear: string;
   close: string;
   copy: string;
+  /** The attached code chip's dismiss glyph. */
+  remove?: string;
 }
 
 // Empty bodies so the island still renders (iconless) if instantiated without
@@ -45,11 +51,18 @@ const DEFAULT_ASK: UIStrings["assistant"] = {
   copy: "Copy conversation",
   empty: "Ask a question about the docs.",
   error: "Sorry, something went wrong.",
+  explainCode: "Explain this code.",
   label: "Ask a question",
+  open: "Open assistant",
   placeholder: "Ask a question…",
+  rateLimited: "You've asked a lot of questions. Try again in a few minutes.",
+  removeCode: "Remove code",
   send: "Send",
+  support: "Contact support",
+  supportSubject: "Question from the docs",
   tip: "Tip: You can open and close chat with",
   title: "Assistant",
+  verifyFailed: "We couldn't check that you're human. Try again.",
   you: "You",
 };
 
@@ -65,11 +78,12 @@ const markdown = new Marked({
   breaks: true,
   gfm: true,
   // The model cites pages as base-less logical routes (`[Title](/route)`); rewrite
-  // link targets to served URLs so citations resolve under `deployment.base`.
-  // `prefixBase` leaves external URLs and fragments untouched and is idempotent.
+  // link targets to served URLs so citations resolve under `deployment.base`,
+  // even a route that starts with the base's own name. `mountBase` leaves
+  // external URLs and fragments untouched.
   walkTokens: (token) => {
     if (token.type === "link") {
-      token.href = prefixBase(import.meta.env.BASE_URL, token.href);
+      token.href = mountBase(import.meta.env.BASE_URL, token.href);
     }
   },
 });
@@ -139,22 +153,54 @@ const ICON_BUTTON_CLASS =
 const ANSWER_CLASS =
   "prose prose-sm max-w-none text-foreground [&_a]:inline-flex [&_a]:items-center [&_a]:gap-1 [&_a]:rounded-full [&_a]:bg-muted [&_a]:px-2 [&_a]:py-1 [&_a]:align-middle [&_a]:font-medium [&_a]:text-[0.7rem] [&_a]:leading-none [&_a]:text-muted-foreground! [&_a]:no-underline! [&_a:hover]:text-foreground!";
 
+/** A reader's message bubble. */
+const USER_MESSAGE_CLASS =
+  "rounded-blume bg-muted text-foreground max-w-[85%] self-end px-3 py-2 text-sm whitespace-pre-wrap";
+
+/** What `blume:open-assistant` may carry. */
+interface OpenAssistantDetail {
+  code?: CodeAttachment;
+  query?: string;
+}
+
+/** A reader's message, with any code they asked about shown as a block. */
+const UserMessage = ({ content }: { content: string }) => {
+  const { code, text } = splitCode(content);
+  if (!code) {
+    return <div className={USER_MESSAGE_CLASS}>{text}</div>;
+  }
+  return (
+    <div className={USER_MESSAGE_CLASS}>
+      {text}
+      <pre className="bg-background mt-2 max-h-40 overflow-auto rounded-md p-2 font-mono text-xs whitespace-pre">
+        {code.source}
+      </pre>
+    </div>
+  );
+};
+
 const Assistant = ({
+  captcha,
   endpoint = DEFAULT_ASK_ENDPOINT,
   icons = EMPTY_ICONS,
   strings,
   suggestions = EMPTY_SUGGESTIONS,
+  support,
 }: {
+  captcha?: CaptchaSettings;
   endpoint?: string;
   icons?: AssistantIcons;
   strings?: UIStrings["assistant"];
   suggestions?: Suggestion[];
+  support?: string;
 }) => {
   // Merge per key (not `strings ?? …`) so a dictionary from a stale snapshot
   // that predates newer keys still resolves every label to its English default.
   const t = { ...DEFAULT_ASK, ...strings };
   const [open, setOpen] = useState(false);
   const [input, setInput] = useState("");
+  // A code block the reader is asking about, sent with the next question.
+  const [code, setCode] = useState<CodeAttachment | null>(null);
   // The streaming client — request shaping, optimistic assistant bubble,
   // stale-stream/abort guards, error-body handling — is the public useAssistant
   // hook, so the built-in panel and custom UIs share one implementation.
@@ -163,7 +209,14 @@ const Assistant = ({
     loading: busy,
     messages,
     reset,
-  } = useAssistant({ endpoint, errorMessage: t.error });
+    thread,
+  } = useAssistant({
+    captcha,
+    endpoint,
+    errorMessage: t.error,
+    rateLimitMessage: t.rateLimited,
+    verifyMessage: t.verifyFailed,
+  });
   const inputRef = useRef<HTMLTextAreaElement>(null);
   const scrollRef = useRef<HTMLDivElement>(null);
   const triggerRef = useRef<HTMLButtonElement>(null);
@@ -192,14 +245,18 @@ const Assistant = ({
     return () => document.removeEventListener("astro:after-swap", onSwap);
   }, []);
 
-  // The search modal forwards its query so "Assistant: <query>" carries straight in.
+  // The search modal forwards its query so "Assistant: <query>" carries
+  // straight in, and a code block's Ask button attaches its code.
   useEffect(() => {
     const handler = (event: Event) => {
       // SAFETY: `blume:open-assistant` is only ever dispatched as a CustomEvent
-      // whose optional detail carries the search query.
-      const query = (event as CustomEvent<{ query?: string }>).detail?.query;
-      if (query) {
-        setInput(query);
+      // whose optional detail carries the search query or a code block.
+      const { detail } = event as CustomEvent<OpenAssistantDetail | null>;
+      if (detail?.query) {
+        setInput(detail.query);
+      }
+      if (detail?.code) {
+        setCode(detail.code);
       }
       setOpen(true);
     };
@@ -262,6 +319,22 @@ const Assistant = ({
     };
   }, [open]);
 
+  // Stamp the incoming body before the swap installs it, as the theme and
+  // banner scripts do for <html>. Stamped only after the swap (below, in a
+  // passive effect), the new body would first paint without the push padding,
+  // replaying its transition on every navigation with the panel docked.
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+    const onBeforeSwap = (event: DocumentEventMap["astro:before-swap"]) => {
+      event.newDocument.body.dataset.blumeAssistant = "open";
+    };
+    document.addEventListener("astro:before-swap", onBeforeSwap);
+    return () =>
+      document.removeEventListener("astro:before-swap", onBeforeSwap);
+  }, [open]);
+
   // Re-stamp the push attribute after a swap while the panel is open — the new
   // body arrives without it. Deliberately separate from the effect above: a
   // navigation must not re-run the focus handling and yank focus out of the
@@ -349,12 +422,14 @@ const Assistant = ({
   }, [messages, portalTarget]);
 
   const runQuestion = (raw: string) => {
-    const question = raw.trim();
+    // A question about attached code may leave the words to us.
+    const question = raw.trim() || (code ? t.explainCode : "");
     if (!question || busy) {
       return;
     }
-    void ask(question);
+    void ask(code ? withCode(question, code) : question);
     setInput("");
+    setCode(null);
   };
 
   const clearConversation = () => {
@@ -447,13 +522,11 @@ const Assistant = ({
                 last entry while streaming, or clears wholesale on reset. */}
             {messages.map((message, index) =>
               message.role === "user" ? (
-                <div
-                  className="rounded-blume bg-muted text-foreground max-w-[85%] self-end px-3 py-2 text-sm whitespace-pre-wrap"
+                <UserMessage
+                  content={message.content}
                   // oxlint-disable-next-line react/no-array-index-key -- append-only list, see above
                   key={index}
-                >
-                  {message.content}
-                </div>
+                />
               ) : (
                 // oxlint-disable-next-line react/no-array-index-key -- append-only list, see above
                 <div className={ANSWER_CLASS} key={index}>
@@ -474,6 +547,23 @@ const Assistant = ({
                 </div>
               )
             )}
+            {support && !busy && (
+              <a
+                className="text-muted-foreground hover:text-foreground self-start text-xs underline underline-offset-2 transition-colors"
+                href={supportHref(support, {
+                  ai: t.ai,
+                  messages,
+                  subject: t.supportSubject,
+                  thread,
+                  you: t.you,
+                })}
+                {...(support.startsWith("mailto:") || support.startsWith("/")
+                  ? {}
+                  : { rel: "noopener noreferrer", target: "_blank" })}
+              >
+                {t.support}
+              </a>
+            )}
           </div>
         ) : (
           <div className="mt-auto flex flex-col gap-0.5 p-4">
@@ -514,6 +604,21 @@ const Assistant = ({
         className="border-border relative shrink-0 border-t"
         onSubmit={onSubmit}
       >
+        {code && (
+          <div className="flex items-center gap-1.5 px-4 pt-3">
+            <span className="rounded-blume bg-muted text-muted-foreground max-w-full truncate px-2 py-1 font-mono text-xs">
+              {code.title || code.language || t.explainCode}
+            </span>
+            <button
+              aria-label={t.removeCode}
+              className={ICON_BUTTON_CLASS}
+              onClick={() => setCode(null)}
+              type="button"
+            >
+              <Glyph path={icons.remove ?? ""} size={14} />
+            </button>
+          </div>
+        )}
         <textarea
           aria-label={t.label}
           className="text-foreground placeholder:text-muted-foreground max-h-48 min-h-[5rem] w-full resize-none bg-transparent px-4 py-3.5 pe-14 text-sm outline-none pointer-coarse:text-base"
@@ -527,7 +632,7 @@ const Assistant = ({
         <button
           aria-label={t.send}
           className="rounded-blume bg-foreground text-background absolute end-3 bottom-3 inline-flex h-8 w-8 cursor-pointer items-center justify-center transition-opacity disabled:cursor-not-allowed disabled:opacity-40"
-          disabled={busy || input.trim().length === 0}
+          disabled={busy || (input.trim().length === 0 && !code)}
           type="submit"
         >
           <Glyph path={icons.arrowUp} />
@@ -542,6 +647,8 @@ const Assistant = ({
         aria-expanded={open}
         aria-label={t.title}
         className={TRIGGER_CLASS}
+        // Named by the header's tooltip, like the buttons beside it.
+        data-blume-tooltip={t.open}
         onClick={() => setOpen((value) => !value)}
         ref={triggerRef}
         type="button"

package/src/components/islands/base-path.ts

@@ -13,20 +13,50 @@ export const withTrailingSlash = (base: string): string =>
 export const joinBase = (base: string, path: string): string =>
   `${withTrailingSlash(base)}${path}`;
 
+/** A root-relative internal target (`/x`) — never `//host` or a URL. */
+const isRootRelative = (route: string): boolean =>
+  route.startsWith("/") && !route.startsWith("//");
+
+/** A target's path, without its `?query` or `#fragment`. */
+const pathOf = (route: string): string => {
+  const at = route.search(/[#?]/u);
+  return at === -1 ? route : route.slice(0, at);
+};
+
 /**
- * Prefix a root-relative internal route with the deployment base
- * (`/guide` under base `/sub` -> `/sub/guide`), so a rendered link points at the
+ * Prefix a root-relative internal link an author wrote with the deployment
+ * base (`/guide` under base `/sub` -> `/sub/guide`), so it points at the
  * page's real served URL. External URLs, protocol-relative URLs, and fragments
- * pass through untouched, and it's idempotent (a route already under the base is
- * returned unchanged). This is applied only where a URL is *emitted* — the
- * navigation model and active-route matching stay in base-less logical space.
+ * pass through untouched, and it's idempotent: a link whose path is already
+ * under the base (`/sub/guide`, `/sub#install`) is returned unchanged, so a
+ * base written by hand isn't doubled. A route Blume generates takes
+ * {@link mountBase} instead. This is applied only where a URL is *emitted* —
+ * the navigation model and active-route matching stay in base-less logical
+ * space.
  */
 export const prefixBase = (base: string, route: string): string => {
-  if (!route.startsWith("/") || route.startsWith("//")) {
+  if (!isRootRelative(route)) {
     return route;
   }
   const trimmed = base.replace(/\/+$/u, "");
-  if (!trimmed || route === trimmed || route.startsWith(`${trimmed}/`)) {
+  const path = pathOf(route);
+  if (!trimmed || path === trimmed || path.startsWith(`${trimmed}/`)) {
+    return route;
+  }
+  return route === "/" ? trimmed : `${trimmed}${route}`;
+};
+
+/**
+ * Prefix a route Blume generates (a page, a sidebar entry, a Markdown mirror,
+ * an agent artifact) with the deployment base, unconditionally. Unlike
+ * {@link prefixBase}, a route whose first segment matches the base is still
+ * prefixed: under base `/guides`, the page `guides/setup.md` is served at
+ * `/guides/guides/setup`, not at `/guides/setup`. External and
+ * protocol-relative URLs pass through untouched.
+ */
+export const mountBase = (base: string, route: string): string => {
+  const trimmed = base.replace(/\/+$/u, "");
+  if (!(trimmed && isRootRelative(route))) {
     return route;
   }
   return route === "/" ? trimmed : `${trimmed}${route}`;
@@ -34,13 +64,20 @@ export const prefixBase = (base: string, route: string): string => {
 
 /**
  * {@link prefixBase} bound to the build-time `BASE_URL` (the resolved
- * `deployment.base`). The ergonomic form for `.astro` templates — `href={
- * withBase(route)}` — since `BASE_URL` is inlined by Vite wherever this module
- * is bundled into the site.
+ * `deployment.base`), for links an author wrote. The ergonomic form for
+ * `.astro` templates — `href={withBase(href)}` — since `BASE_URL` is inlined
+ * by Vite wherever this module is bundled into the site.
  */
 export const withBase = (route: string): string =>
   prefixBase(import.meta.env.BASE_URL ?? "/", route);
 
+/**
+ * {@link mountBase} bound to the build-time `BASE_URL`, for routes Blume
+ * generates: `href={withMountedBase(page.route)}`.
+ */
+export const withMountedBase = (route: string): string =>
+  mountBase(import.meta.env.BASE_URL ?? "/", route);
+
 /**
  * A pathname with the deployment base stripped (`/docs/guide` -> `/guide`),
  * for page-context lookups against base-less document routes.

package/src/components/islands/code-question.ts

@@ -0,0 +1,62 @@
+/**
+ * Questions about a code block. A code block's Ask button opens the assistant
+ * with the block attached (`blume:open-assistant` with `detail.code`); the
+ * question goes out with the code folded in as a fenced block after the
+ * reader's words, which is how the model sees it, and the conversation shows
+ * the two apart again.
+ */
+
+/** A code block the reader asked about. */
+export interface CodeAttachment {
+  /** The fence language (`ts`), or empty when the block has none. */
+  language: string;
+  source: string;
+  /** The block's title (`server.ts`), when it has one. */
+  title?: string;
+}
+
+/** The most code one question carries, well inside the route's budget. */
+export const MAX_ATTACHED_CODE = 6000;
+
+/** A user message, split into the reader's words and any attached code. */
+export interface SplitQuestion {
+  code?: { language: string; source: string };
+  text: string;
+}
+
+/** A fence longer than any backtick run in the code, so the code can't close it. */
+const fenceFor = (source: string): string => {
+  const longest = Math.max(
+    2,
+    ...[...source.matchAll(/`+/gu)].map(([run]) => run.length)
+  );
+  return "`".repeat(longest + 1);
+};
+
+/** The question as sent: the reader's words, then the code as a fenced block. */
+export const withCode = (question: string, code: CodeAttachment): string => {
+  const source =
+    code.source.length > MAX_ATTACHED_CODE
+      ? `${code.source.slice(0, MAX_ATTACHED_CODE)}\n…`
+      : code.source.replace(/\n+$/u, "");
+  const fence = fenceFor(source);
+  return `${question}\n\n${fence}${code.language}\n${source}\n${fence}`;
+};
+
+const TRAILING_FENCE =
+  /\n\n(?<fence>`{3,})(?<language>[^\n`]*)\n(?<source>[\s\S]*)\n\k<fence>$/u;
+
+/** A user message split back into the words and the attached code. */
+export const splitCode = (content: string): SplitQuestion => {
+  const match = TRAILING_FENCE.exec(content);
+  if (!match?.groups) {
+    return { text: content };
+  }
+  return {
+    code: {
+      language: match.groups.language ?? "",
+      source: match.groups.source ?? "",
+    },
+    text: content.slice(0, match.index),
+  };
+};