@frankieai/react 0.1.1 → 0.1.5

package/src/components/chat/FrankieChatPage.tsx

@@ -0,0 +1,121 @@
+"use client";
+
+import type { CSSProperties } from "react";
+import type { FrankieProviderProps } from "../../hooks/FrankieProvider.jsx";
+import { FrankieProvider, useFrankie } from "../../hooks/FrankieProvider.jsx";
+import { useFrankieChat } from "../../hooks/useFrankieChat.js";
+import { FrankieInline } from "./FrankieInline.js";
+import type { ChatPanelProps } from "./ChatPanel.js";
+
+export interface FrankieChatPageProps
+  extends Omit<FrankieProviderProps, "children">,
+    Pick<
+      ChatPanelProps,
+      "header" | "footer" | "emptyState" | "renderMessage" | "renderTool" | "placeholder" | "autoFocus"
+    > {
+  className?: string;
+  style?: CSSProperties;
+}
+
+function PageEmptyState() {
+  const { config } = useFrankie();
+  const { send, busy } = useFrankieChat();
+  const name = config?.branding.name ?? "Frankie";
+  const prompts = config?.suggestedPrompts?.slice(0, 3) ?? [];
+
+  return (
+    <section className="frankie-page-empty" aria-label="Start a conversation">
+      <span className="frankie-page-avatar" aria-hidden>{name.trim().slice(0, 1).toUpperCase()}</span>
+      <div>
+        <p className="frankie-page-kicker">{name} assistant</p>
+        <h1>What would you like to do?</h1>
+        <p>{config?.greeting ?? "Ask a question or choose a task to get started."}</p>
+      </div>
+      {prompts.length ? (
+        <div className="frankie-page-prompts">
+          {prompts.map((prompt, index) => (
+            <button key={prompt} type="button" disabled={busy} onClick={() => send(prompt)}>
+              <span>{String(index + 1).padStart(2, "0")}</span>
+              <strong>{prompt}</strong>
+              <b aria-hidden>↗</b>
+            </button>
+          ))}
+        </div>
+      ) : null}
+    </section>
+  );
+}
+
+function PageChrome({
+  header,
+  footer,
+  emptyState,
+  renderMessage,
+  renderTool,
+  placeholder,
+  autoFocus,
+}: Pick<FrankieChatPageProps, "header" | "footer" | "emptyState" | "renderMessage" | "renderTool" | "placeholder" | "autoFocus">) {
+  const { config } = useFrankie();
+  const { reset } = useFrankieChat();
+  const name = config?.branding.name ?? "Frankie";
+
+  return (
+    <>
+      <header className="frankie-page-header">
+        <div>
+          <span className="frankie-page-status" aria-hidden />
+          <strong>{name}</strong>
+        </div>
+        <button type="button" onClick={reset} aria-label="Start a new conversation">New chat</button>
+      </header>
+      <div className="frankie-page-canvas">
+        <FrankieInline
+          header={header ?? false}
+          footer={footer}
+          emptyState={emptyState ?? <PageEmptyState />}
+          renderMessage={renderMessage}
+          renderTool={renderTool}
+          placeholder={placeholder}
+          autoFocus={autoFocus}
+        />
+      </div>
+    </>
+  );
+}
+
+/**
+ * A complete, polished chat route matching Frankie's own conversation canvas.
+ * The shell, header, empty state and composer are all scoped under
+ * `.frankie-root`, so host application styles remain untouched.
+ */
+export function FrankieChatPage({
+  className,
+  style,
+  header,
+  footer,
+  emptyState,
+  renderMessage,
+  renderTool,
+  placeholder,
+  autoFocus,
+  ...providerProps
+}: FrankieChatPageProps) {
+  return (
+    <main
+      className={["frankie-root", "frankie-chat-page", className].filter(Boolean).join(" ")}
+      style={{ height: "100dvh", minHeight: "100dvh", width: "100%", ...style }}
+    >
+      <FrankieProvider {...providerProps}>
+        <PageChrome
+          header={header}
+          footer={footer}
+          emptyState={emptyState}
+          renderMessage={renderMessage}
+          renderTool={renderTool}
+          placeholder={placeholder}
+          autoFocus={autoFocus}
+        />
+      </FrankieProvider>
+    </main>
+  );
+}

package/src/components/chat/MessageBubble.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import { Paperclip } from "lucide-react";
-import type { ReactNode } from "react";
+import { Check, Copy, Paperclip } from "lucide-react";
+import "./message-actions.css";
+import { useState, type ReactNode } from "react";
 import { cn } from "../../lib/utils.js";
 import type { ChatMessage, ToolActivity } from "../../lib/messages.js";
 import { Avatar } from "../ui/avatar.js";
@@ -40,8 +41,9 @@ export function MessageBubble({
           </div>
         ) : null}
         {message.text ? (
-          <div className="max-w-[85%] rounded-[var(--frankie-radius)] bg-primary px-3 py-2 text-sm text-primary-foreground">
-            {message.text}
+          <div className="flex max-w-[85%] items-end gap-1">
+            <div className="rounded-[var(--frankie-radius)] bg-primary px-3 py-2 text-sm text-primary-foreground">{message.text}</div>
+            <MessageCopyButton text={message.text} />
           </div>
         ) : null}
       </div>
@@ -52,7 +54,10 @@ export function MessageBubble({
 
   return (
     <div className="flex gap-2">
-      <Avatar {...(avatarUrl ? { src: avatarUrl } : {})} name={assistantName} className="mt-0.5" />
+      <div className="frankie-assistant-actions mt-0.5 flex shrink-0 flex-col items-center gap-1">
+        <Avatar {...(avatarUrl ? { src: avatarUrl } : {})} name={assistantName} />
+        {message.text ? <MessageCopyButton text={message.text} /> : null}
+      </div>
       <div className="min-w-0 max-w-[85%]">
         {message.status === "error" ? (
           <p className="rounded-[var(--frankie-radius)] bg-red-500/10 px-3 py-2 text-sm text-red-600 dark:text-red-400">
@@ -71,6 +76,18 @@ export function MessageBubble({
   );
 }
 
+function MessageCopyButton({ text }: { text: string }) {
+  const [copied, setCopied] = useState(false);
+  const copy = async () => {
+    try {
+      await navigator.clipboard.writeText(text);
+      setCopied(true);
+      window.setTimeout(() => setCopied(false), 1500);
+    } catch { /* Clipboard access can be disabled by an embedding host. */ }
+  };
+  return <button type="button" onClick={() => void copy()} className="frankie-message-copy inline-flex size-8 shrink-0 items-center justify-center rounded-md border border-transparent text-muted-foreground transition hover:border-border hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary" aria-label={copied ? "Copied" : "Copy message"} title={copied ? "Copied" : "Copy message"}>{copied ? <Check className="size-3.5" aria-hidden="true" /> : <Copy className="size-3.5" aria-hidden="true" />}</button>;
+}
+
 export function TypingDots() {
   return (
     <span className="inline-flex items-center gap-1 py-2" role="status" aria-label="Thinking">

package/src/components/chat/ToolActivityList.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { Check, Loader2, ShieldAlert, X } from "lucide-react";
+import { Check, ChevronDown, Loader2, ShieldAlert, X } from "lucide-react";
 import { Badge } from "../ui/badge.js";
 import type { ToolActivity } from "../../lib/messages.js";
 
@@ -13,12 +13,16 @@ export interface ToolActivityListProps {
 /** The "what the assistant is doing" strip under a streaming answer. */
 export function ToolActivityList({ tools, renderTool }: ToolActivityListProps) {
   if (tools.length === 0) return null;
+  const running = tools.some((tool) => tool.status === "running");
   return (
-    <ul className="mt-2 flex flex-col gap-1">
-      {tools.map((tool) => (
-        <li key={tool.id}>{renderTool ? renderTool(tool) : <ToolActivityRow tool={tool} />}</li>
-      ))}
-    </ul>
+    <details className="frankie-tool-activity mt-2" open={running}>
+      <summary className="inline-flex min-h-7 cursor-pointer list-none items-center gap-1.5 rounded-md px-1 text-xs font-medium text-muted-foreground hover:bg-muted hover:text-foreground [&::-webkit-details-marker]:hidden">
+        <ChevronDown className="frankie-tool-chevron size-3.5 transition-transform" aria-hidden="true" />
+        <span>{running ? "Working" : "Activity"}</span>
+        <span className="text-[11px]">· {tools.length} tool call{tools.length === 1 ? "" : "s"}</span>
+      </summary>
+      <ul className="mt-1 flex flex-col gap-1 border-l border-border pl-2">{tools.map((tool) => <li key={tool.id}>{renderTool ? renderTool(tool) : <ToolActivityRow tool={tool} />}</li>)}</ul>
+    </details>
   );
 }
 

package/src/components/chat/message-actions.css

@@ -0,0 +1,13 @@
+.frankie-root .frankie-message-copy { opacity: .72; }
+.frankie-root .frankie-message-copy:hover { opacity: 1; }
+.frankie-root .frankie-tool-activity[open] .frankie-tool-chevron { transform: rotate(180deg); }
+
+.frankie-root .frankie-assistant-actions .frankie-message-copy {
+  width: 28px; height: 28px; min-width: 28px; min-height: 28px;
+  border: 0; background: transparent; opacity: .46;
+}
+.frankie-root .frankie-assistant-actions .frankie-message-copy:hover,
+.frankie-root .frankie-assistant-actions .frankie-message-copy:focus-visible { opacity: 1; }
+.frankie-root .frankie-tool-activity { max-width: 100%; }
+.frankie-root .frankie-tool-activity[open] > summary { color: var(--frankie-foreground); }
+.frankie-root .frankie-tool-activity li .frankie-badge { max-width: 100%; }

package/src/hooks/FrankieProvider.tsx

@@ -6,14 +6,8 @@ import { FrankieClient, type FrankieClientOptions, type PageContext } from "../l
 
 export interface FrankieProviderProps extends FrankieClientOptions {
   children: ReactNode;
-  /**
-   * Page context sent with every turn — current route, plan tier, whatever the
-   * agent should know. Treated as data by the server, never as instructions.
-   */
   context?: PageContext;
-  /** Overrides for the server-side theme, so a host can restyle without a redeploy. */
   theme?: WidgetTheme;
-  /** Skip the `/v1/config` fetch by supplying the config yourself. */
   config?: PublicWidgetConfig;
 }
 
@@ -37,9 +31,8 @@ export function FrankieProvider({
 }: FrankieProviderProps) {
   const client = useMemo(
     () => new FrankieClient(clientOptions),
-    // The client holds session state; rebuild it only when the endpoint changes.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [clientOptions.baseUrl, clientOptions.publishableKey],
+    [clientOptions.baseUrl, clientOptions.publishableKey, clientOptions.storageNamespace, clientOptions.conversationId],
   );
 
   const [config, setConfig] = useState<PublicWidgetConfig | undefined>(providedConfig);
@@ -87,7 +80,6 @@ export function useFrankie(): FrankieContextValue {
   return value;
 }
 
-/** The theme actually in effect: provider override wins over server config. */
 export function useFrankieTheme(): WidgetTheme | undefined {
   const { config, theme } = useFrankie();
   return useMemo(() => ({ ...config?.theme, ...theme }), [config?.theme, theme]);

package/src/hooks/useFrankieChat.ts

@@ -39,8 +39,12 @@ export function useFrankieChat(): UseFrankieChatResult {
   const [messages, setMessages] = useState<ChatMessage[]>([]);
   const [busy, setBusy] = useState(false);
   const [error, setError] = useState<string | undefined>(undefined);
+  const [restored, setRestored] = useState(false);
   const abortRef = useRef<AbortController | null>(null);
   const mounted = useRef(true);
+  // State updates can be batched while a stream is arriving. Keep the latest
+  // transcript synchronously so the final server sync cannot save a stale copy.
+  const messagesRef = useRef<ChatMessage[]>([]);
 
   useEffect(() => {
     mounted.current = true;
@@ -52,37 +56,61 @@ export function useFrankieChat(): UseFrankieChatResult {
 
   const storageKey = `${client.namespace}.messages`;
 
-  // Restore the transcript on mount, so a page reload keeps the conversation.
-  // The client resumes the matching server session, so context is kept too.
+  // Restore local storage immediately, then hydrate the authoritative server
+  // transcript. The server path makes the same signed-in user's chats available
+  // on another browser or device.
   useEffect(() => {
-    if (!client.persist) return;
-    try {
-      const raw = window.localStorage.getItem(storageKey);
-      const stored = raw ? (JSON.parse(raw) as ChatMessage[]) : [];
-      if (Array.isArray(stored) && stored.length) setMessages(stored);
-    } catch {
-      /* storage unavailable; start empty */
-    }
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [storageKey]);
+    let active = true;
+    const restore = async () => {
+      if (client.persist) {
+        try {
+          const raw = window.localStorage.getItem(storageKey);
+          const stored = raw ? (JSON.parse(raw) as ChatMessage[]) : [];
+          if (Array.isArray(stored) && stored.length && active) {
+            messagesRef.current = stored;
+            setMessages(stored);
+          }
+        } catch {
+          /* storage unavailable; server history can still restore */
+        }
+      }
+      try {
+        const remote = await client.resumeConversation();
+        if (active && remote?.messages.length) {
+          const restoredMessages = remote.messages as ChatMessage[];
+          messagesRef.current = restoredMessages;
+          setMessages(restoredMessages);
+        }
+      } catch {
+        /* A new conversation does not exist remotely until its first message. */
+      } finally {
+        if (active) setRestored(true);
+      }
+    };
+    void restore();
+    return () => { active = false; };
+  }, [client, storageKey]);
 
   // Persist once a turn settles — never mid-stream — so the saved copy is clean.
+  // Wait until the initial restore has completed so an empty initial state never
+  // deletes an existing transcript.
   useEffect(() => {
-    if (!client.persist || busy) return;
+    if (!client.persist || !restored || busy) return;
     try {
       if (messages.length) window.localStorage.setItem(storageKey, JSON.stringify(messages));
       else window.localStorage.removeItem(storageKey);
     } catch {
       /* ignore */
     }
-  }, [messages, busy, client, storageKey]);
+    if (messages.length) void client.syncConversation(messages, conversationTitle(messages)).catch(() => undefined);
+  }, [messages, busy, client, storageKey, restored]);
 
   const patchAssistant = useCallback((id: string, update: (m: AssistantChatMessage) => AssistantChatMessage) => {
-    setMessages((current) =>
-      current.map((message) =>
-        message.id === id && message.role === "assistant" ? update(message) : message,
-      ),
+    const next = messagesRef.current.map((message) =>
+      message.id === id && message.role === "assistant" ? update(message) : message,
     );
+    messagesRef.current = next;
+    setMessages(next);
   }, []);
 
   const send = useCallback(
@@ -96,20 +124,24 @@ export function useFrankieChat(): UseFrankieChatResult {
       const assistantId = nextId("a");
       setError(undefined);
       setBusy(true);
-      setMessages((current) => [
-        ...current,
+      const next = [
+        ...messagesRef.current,
         newUserMessage(
           nextId("u"),
           trimmed,
           attachments.map((file) => ({ name: file.name, mimeType: file.mimeType })),
         ),
         newAssistantMessage(assistantId),
-      ]);
+      ];
+      messagesRef.current = next;
+      setMessages(next);
 
       const abort = new AbortController();
       abortRef.current = abort;
 
       try {
+        let receivedText = false;
+        let receivedToolActivity = false;
         await client.send(
           {
             message: outgoing,
@@ -120,9 +152,23 @@ export function useFrankieChat(): UseFrankieChatResult {
           },
           (event) => {
             if (event.type === "ping" || event.type === "session") return;
+            if (event.type === "text_delta") receivedText = true;
+            if (event.type === "tool_start" || event.type === "tool_end") receivedToolActivity = true;
             patchAssistant(assistantId, (message) => applyEvent(message, event));
           },
         );
+        // A terminated stream with no text previously looked like Frankie did
+        // nothing. Preserve visible tool activity, but never leave an empty
+        // assistant bubble for the user to interpret.
+        if (!receivedText) {
+          patchAssistant(assistantId, (message) => ({
+            ...message,
+            status: "done",
+            text: receivedToolActivity
+              ? "Completed. Open Agent activity for the details."
+              : "Frankie didn’t return an answer. Please try again.",
+          }));
+        }
       } catch (caught) {
         if (abort.signal.aborted) {
           patchAssistant(assistantId, (message) => ({
@@ -134,18 +180,25 @@ export function useFrankieChat(): UseFrankieChatResult {
           const message =
             caught instanceof FrankieApiError
               ? caught.message
-              : "Could not reach the assistant. Check your connection and try again.";
+              : caught instanceof Error && caught.message.startsWith("Frankie")
+                ? caught.message
+                : "Could not reach the assistant. Check your connection and try again.";
           if (mounted.current) setError(message);
           patchAssistant(assistantId, (current) => ({ ...current, status: "error", error: message }));
         }
       } finally {
-        if (mounted.current) {
-          setBusy(false);
-          // A turn that ended without a `turn_end` event still has to settle.
-          patchAssistant(assistantId, (message) =>
-            message.status === "streaming" ? { ...message, status: "done" } : message,
-          );
+        // A turn that ended without a `turn_end` event still has to settle.
+        patchAssistant(assistantId, (message) =>
+          message.status === "streaming" ? { ...message, status: "done" } : message,
+        );
+        // Persist before send() resolves. This closes the previous gap where a
+        // route change or tab close could leave a server conversation with no
+        // rendered messages even though the agent transcript existed.
+        const transcript = messagesRef.current;
+        if (transcript.length) {
+          await client.syncConversation(transcript, conversationTitle(transcript)).catch(() => undefined);
         }
+        if (mounted.current) setBusy(false);
         abortRef.current = null;
       }
     },
@@ -157,9 +210,11 @@ export function useFrankieChat(): UseFrankieChatResult {
   const reset = useCallback(() => {
     abortRef.current?.abort();
     client.resetSession();
+    messagesRef.current = [];
     setMessages([]);
     setError(undefined);
     setBusy(false);
+    setRestored(true);
     try {
       if (client.persist) window.localStorage.removeItem(`${client.namespace}.messages`);
     } catch {
@@ -169,3 +224,11 @@ export function useFrankieChat(): UseFrankieChatResult {
 
   return { messages, busy, ...(error ? { error } : {}), send, stop, reset };
 }
+
+
+function conversationTitle(messages: ChatMessage[]): string | undefined {
+  const first = messages.find((message) => message.role === "user" && message.text.trim());
+  if (!first) return undefined;
+  const title = first.text.trim().replace(/\s+/g, " ");
+  return title.length > 42 ? `${title.slice(0, 42)}…` : title;
+}

package/src/index.ts

@@ -7,6 +7,8 @@ export { FrankieWidget } from "./components/chat/FrankieWidget.js";
 export type { FrankieWidgetProps } from "./components/chat/FrankieWidget.js";
 export { FrankieInline } from "./components/chat/FrankieInline.js";
 export type { FrankieInlineProps } from "./components/chat/FrankieInline.js";
+export { FrankieChatPage } from "./components/chat/FrankieChatPage.js";
+export type { FrankieChatPageProps } from "./components/chat/FrankieChatPage.js";
 export { ChatPanel } from "./components/chat/ChatPanel.js";
 export type { ChatPanelProps } from "./components/chat/ChatPanel.js";
 export { Composer } from "./components/chat/Composer.js";

package/src/lib/client.ts

@@ -32,6 +32,17 @@ export interface FrankieClientOptions {
    * set false for an ephemeral chat that starts fresh every load.
    */
   persist?: boolean;
+  /** Override localStorage namespace for session and transcript. */
+  storageNamespace?: string;
+  /** Stable id for a server-backed conversation. */
+  conversationId?: string;
+}
+
+export interface ChatConversation {
+  id: string;
+  title: string;
+  createdAt: number;
+  updatedAt: number;
 }
 
 export class FrankieApiError extends Error {
@@ -59,14 +70,18 @@ export class FrankieClient {
     return this.session?.sessionId;
   }
 
+  get conversationId(): string | undefined {
+    return this.options.conversationId;
+  }
+
   /** Whether this client persists across reloads (browser only, opt-out via `persist:false`). */
   get persist(): boolean {
     return this.options.persist !== false && typeof window !== "undefined";
   }
 
-  /** localStorage namespace for this tenant, shared with the chat hook. */
+  /** localStorage namespace for this tenant/conversation, shared with the chat hook. */
   get namespace(): string {
-    return `frankie.${this.options.publishableKey}`;
+    return this.options.storageNamespace ?? `frankie.${this.options.publishableKey}`;
   }
 
   private readStored(): CreateSessionResponse | undefined {
@@ -75,7 +90,6 @@ export class FrankieClient {
       const raw = window.localStorage.getItem(`${this.namespace}.session`);
       if (!raw) return undefined;
       const session = JSON.parse(raw) as CreateSessionResponse;
-      // A stored session past its expiry is useless; drop it.
       return new Date(session.expiresAt).getTime() > Date.now() + 30_000 ? session : undefined;
     } catch {
       return undefined;
@@ -100,39 +114,92 @@ export class FrankieClient {
     return (await this.unwrap(response)) as PublicWidgetConfig;
   }
 
-  /** Opens (or reuses) a chat session. */
   async ensureSession(context?: PageContext): Promise<CreateSessionResponse> {
-    if (this.session && new Date(this.session.expiresAt).getTime() > Date.now() + 30_000) {
-      return this.session;
-    }
+    if (this.session && new Date(this.session.expiresAt).getTime() > Date.now() + 30_000) return this.session;
     const userToken = await this.options.getUserToken?.();
+    if (this.options.getUserToken && !userToken) {
+      throw new FrankieApiError(
+        "Your signed-in Frankie session could not be verified. Refresh the page and sign in again.",
+        401,
+        "user_token_unavailable",
+      );
+    }
     const response = await this.doFetch(`${this.baseUrl}/v1/session`, {
       method: "POST",
       headers: { "content-type": "application/json", "x-frankie-key": this.options.publishableKey },
-      body: JSON.stringify({ ...(userToken ? { userToken } : {}), ...(context ? { context } : {}) }),
+      body: JSON.stringify({
+        ...(userToken ? { userToken } : {}),
+        ...(context ? { context } : {}),
+        ...(this.options.conversationId ? { conversationId: this.options.conversationId } : {}),
+      }),
     });
     this.session = (await this.unwrap(response)) as CreateSessionResponse;
     this.writeStored();
     return this.session;
   }
 
-  /** Forget the current session so the next send starts a fresh conversation. */
+  async listConversations(): Promise<ChatConversation[]> {
+    const userToken = await this.requireUserToken();
+    const response = await this.doFetch(`${this.baseUrl}/v1/conversations`, {
+      headers: { "x-frankie-key": this.options.publishableKey, authorization: `Bearer ${userToken}` },
+    });
+    const body = (await this.unwrap(response)) as { conversations?: ChatConversation[] };
+    return Array.isArray(body.conversations) ? body.conversations : [];
+  }
+
+  async resumeConversation(id = this.options.conversationId): Promise<{ messages: unknown[]; title: string } | undefined> {
+    if (!id) return undefined;
+    const userToken = await this.requireUserToken();
+    const response = await this.doFetch(`${this.baseUrl}/v1/conversations/${encodeURIComponent(id)}/resume`, {
+      method: "POST",
+      headers: { "x-frankie-key": this.options.publishableKey, authorization: `Bearer ${userToken}` },
+    });
+    if (response.status === 404) return undefined;
+    const body = (await this.unwrap(response)) as { session: CreateSessionResponse; messages?: unknown[]; title?: string };
+    this.session = body.session;
+    this.writeStored();
+    return { messages: Array.isArray(body.messages) ? body.messages : [], title: body.title ?? "New chat" };
+  }
+
+  async syncConversation(messages: unknown[], title?: string): Promise<void> {
+    if (!this.session || !this.options.conversationId) return;
+    const response = await this.doFetch(`${this.baseUrl}/v1/conversations/${encodeURIComponent(this.options.conversationId)}`, {
+      method: "PUT",
+      headers: {
+        "content-type": "application/json",
+        "x-frankie-key": this.options.publishableKey,
+        authorization: `Bearer ${this.session.sessionToken}`,
+      },
+      body: JSON.stringify({ messages, ...(title ? { title } : {}) }),
+    });
+    await this.unwrap(response);
+  }
+
+  async deleteConversation(id: string): Promise<void> {
+    const userToken = await this.requireUserToken();
+    const response = await this.doFetch(`${this.baseUrl}/v1/conversations/${encodeURIComponent(id)}`, {
+      method: "DELETE",
+      headers: { "x-frankie-key": this.options.publishableKey, authorization: `Bearer ${userToken}` },
+    });
+    if (response.status !== 404) await this.unwrap(response);
+  }
+
+  private async requireUserToken(): Promise<string> {
+    const token = await this.options.getUserToken?.();
+    if (!token) throw new FrankieApiError("Sign in to access your chat history.", 401, "unauthorized");
+    return token;
+  }
+
   resetSession(): void {
     this.session = undefined;
     this.writeStored();
   }
 
-  /**
-   * Sends a message and invokes `onEvent` for each server event as it arrives.
-   * Resolves when the turn ends.
-   */
   async send(
     input: {
       message: string;
       context?: PageContext;
-      /** Model id chosen by the user, honoured only if the workspace allows it. */
       model?: string;
-      /** Files attached to this turn. */
       attachments?: ChatAttachment[];
       signal?: AbortSignal;
     },
@@ -159,7 +226,6 @@ export class FrankieClient {
     });
 
     if (!response.ok || !response.body) {
-      // A dropped session is recoverable: clear it so the next send re-auths.
       if (response.status === 401 || response.status === 404) this.resetSession();
       await this.unwrap(response);
       return;
@@ -185,7 +251,6 @@ export class FrankieClient {
   }
 }
 
-/** Parse the server's `data:`-only SSE stream into typed events. */
 export async function* readEventStream(
   body: ReadableStream<Uint8Array>,
 ): AsyncGenerator<FrankieServerEvent> {