@frankieai/react 0.1.1 → 0.1.4

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,6 +39,7 @@ 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);
 
@@ -52,30 +53,47 @@ 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) setMessages(stored);
+        } catch {
+          /* storage unavailable; server history can still restore */
+        }
+      }
+      try {
+        const remote = await client.resumeConversation();
+        if (active && remote?.messages.length) setMessages(remote.messages as ChatMessage[]);
+      } 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) =>
@@ -110,6 +128,8 @@ export function useFrankieChat(): UseFrankieChatResult {
       abortRef.current = abort;
 
       try {
+        let receivedText = false;
+        let receivedToolActivity = false;
         await client.send(
           {
             message: outgoing,
@@ -120,9 +140,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,7 +168,9 @@ 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 }));
         }
@@ -160,6 +196,7 @@ export function useFrankieChat(): UseFrankieChatResult {
     setMessages([]);
     setError(undefined);
     setBusy(false);
+    setRestored(true);
     try {
       if (client.persist) window.localStorage.removeItem(`${client.namespace}.messages`);
     } catch {
@@ -169,3 +206,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> {

package/src/styles/frankie.css

@@ -7,15 +7,23 @@
  * a CSS variable scoped to `.frankie-root`, so a host can restyle the widget
  * without touching this file.
  *
- * Hosts that already run Tailwind v4 can skip this file entirely and instead
- * add `@source "../node_modules/@frankieai/react/dist";` to their own CSS: the
- * widget then compiles against their design tokens.
+ * This stylesheet is self-contained. Widget utilities are compiled ahead of
+ * time and prefixed with `.frankie-root`, so they cannot style the host app.
  */
 
 @layer theme, components, utilities;
 
 @import "tailwindcss/theme.css" layer(theme);
-@import "tailwindcss/utilities.css" layer(utilities) source(none);
+
+/*
+ * The widget is embedded inside arbitrary applications. Native CSS scoping
+ * keeps Tailwind's generated utilities inside the widget instead of relying on
+ * Tailwind's invalid selector-important import syntax (which made the whole
+ * utility layer disappear in production).
+ */
+@scope (.frankie-root) {
+  @tailwind utilities;
+}
 
 @source "../";