@frankieai/react 0.2.8 → 0.2.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frankieai/react",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "Embeddable, themeable chat widget for the Frankie onboarding agent — shadcn/ui components, works with or without Tailwind in the host app.",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "clsx": "^2.1.1",
     "lucide-react": "^0.460.0",
     "tailwind-merge": "^2.5.0",
-    "@frankieai/core": "0.2.1"
+    "@frankieai/core": "0.2.2"
   },
   "devDependencies": {
     "@tailwindcss/cli": "^4.0.0",
@@ -46,6 +46,9 @@
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   },
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
     "build": "tsup && pnpm build:css",
     "build:css": "tailwindcss -i src/styles/frankie.css -o dist/frankie.css --minify",

package/src/components/chat/ChatPanel.tsx

@@ -65,6 +65,9 @@ export function ChatPanel({
   const features = config?.features;
   const pickerModels = features?.modelPicker.enabled ? features.modelPicker.models : [];
   const [model, setModel] = useState<string | undefined>(undefined);
+  // A "Something else" choice focuses the composer through this handle.
+  const composerFocus = useRef<(() => void) | null>(null);
+  const focusComposer = () => composerFocus.current?.();
 
   useEffect(() => {
     const node = scrollRef.current;
@@ -138,7 +141,7 @@ export function ChatPanel({
             ))
           ) : (
             <div className="frankie-message-list flex flex-col gap-4">
-              {messages.map((message) =>
+              {messages.map((message, index) =>
                 renderMessage ? (
                   <div key={message.id}>{renderMessage(message)}</div>
                 ) : (
@@ -149,6 +152,10 @@ export function ChatPanel({
                     {...(config?.branding.avatarUrl ? { avatarUrl: config.branding.avatarUrl } : {})}
                     showToolActivity={config?.showToolActivity ?? true}
                     {...(renderTool ? { renderTool } : {})}
+                    onChoose={send}
+                    onRequestInput={focusComposer}
+                    active={index === messages.length - 1}
+                    busy={busy}
                   />
                 ),
               )}
@@ -164,6 +171,7 @@ export function ChatPanel({
             onSend={send}
             onStop={stop}
             busy={busy}
+            focusHandleRef={composerFocus}
             disabled={loading || restoring || Boolean(configError)}
             {...(placeholder ? { placeholder } : {})}
             {...(autoFocus ? { autoFocus } : {})}

package/src/components/chat/Choices.tsx

@@ -0,0 +1,52 @@
+"use client";
+
+import { ArrowRight, PencilLine } from "lucide-react";
+
+/**
+ * Clickable answer options the agent offered via a `frankie:choices` block.
+ * Picking one sends it as the next message. A trailing "Something else" row
+ * doesn't send — it moves the caret to the composer so the user can type their
+ * own answer, while the offered options stay put in case they change their mind.
+ */
+export function Choices({
+  options,
+  onPick,
+  onSomethingElse,
+  disabled,
+}: {
+  options: string[];
+  onPick: (choice: string) => void;
+  onSomethingElse?: () => void;
+  disabled?: boolean;
+}) {
+  if (options.length === 0) return null;
+  return (
+    <div className="frankie-choices" role="group" aria-label="Choose an option">
+      {options.map((option, index) => (
+        <button
+          key={`${index}-${option}`}
+          type="button"
+          className="frankie-choice"
+          disabled={disabled}
+          onClick={() => onPick(option)}
+        >
+          <span className="frankie-choice-index" aria-hidden>{index + 1}</span>
+          <span className="frankie-choice-label">{option}</span>
+          <ArrowRight className="frankie-choice-go size-4" aria-hidden />
+        </button>
+      ))}
+      {onSomethingElse ? (
+        <button
+          type="button"
+          className="frankie-choice frankie-choice-other"
+          disabled={disabled}
+          onClick={onSomethingElse}
+        >
+          <span className="frankie-choice-index" aria-hidden><PencilLine className="size-3.5" /></span>
+          <span className="frankie-choice-label">Something else…</span>
+          <span className="frankie-choice-hint" aria-hidden>Type your own</span>
+        </button>
+      ) : null}
+    </div>
+  );
+}

package/src/components/chat/Composer.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { ArrowUp, Paperclip, Plus, Square, X } from "lucide-react";
-import { useCallback, useEffect, useRef, useState, type KeyboardEvent } from "react";
+import { useCallback, useEffect, useRef, useState, type KeyboardEvent, type MutableRefObject } from "react";
 import type { ChatAttachment } from "@frankieai/core";
 import { Button } from "../ui/button.js";
 import { Textarea } from "../ui/textarea.js";
@@ -31,6 +31,8 @@ export interface ComposerProps {
   attachments?: ComposerAttachmentsConfig;
   /** Enables a model dropdown when provided with at least one model. */
   modelPicker?: ComposerModelPicker;
+  /** Populated with a function that focuses the input, so a "type your own" choice can jump here. */
+  focusHandleRef?: MutableRefObject<(() => void) | null>;
 }
 
 interface PickedFile extends ChatAttachment {
@@ -39,13 +41,21 @@ interface PickedFile extends ChatAttachment {
 
 const MAX_ROWS_PX = 140;
 
-export function Composer({ onSend, onStop, busy, placeholder, disabled, autoFocus, attachments, modelPicker }: ComposerProps) {
+export function Composer({ onSend, onStop, busy, placeholder, disabled, autoFocus, attachments, modelPicker, focusHandleRef }: ComposerProps) {
   const [value, setValue] = useState("");
   const [files, setFiles] = useState<PickedFile[]>([]);
   const [fileError, setFileError] = useState<string | undefined>(undefined);
   const textareaRef = useRef<HTMLTextAreaElement>(null);
   const fileInputRef = useRef<HTMLInputElement>(null);
 
+  // Publish a focus handle so a "Something else" choice elsewhere in the panel
+  // can move the caret here without reaching into the DOM.
+  useEffect(() => {
+    if (!focusHandleRef) return;
+    focusHandleRef.current = () => textareaRef.current?.focus();
+    return () => { focusHandleRef.current = null; };
+  }, [focusHandleRef]);
+
   const canAttach = Boolean(attachments?.enabled);
   const models = modelPicker?.models ?? [];
 

package/src/components/chat/FrankieChatPage.tsx

@@ -5,6 +5,7 @@ import { ChevronsLeft, ChevronsRight, History, Menu, Plus, Settings, X } from "l
 import type { FrankieProviderProps } from "../../hooks/FrankieProvider.jsx";
 import { FrankieProvider, useFrankie, useFrankieTheme } from "../../hooks/FrankieProvider.jsx";
 import { useFrankieChat } from "../../hooks/useFrankieChat.js";
+import { useStylesReady } from "../../lib/styles-ready.js";
 import { themeToCssVars, resolveMode } from "../../lib/theme.js";
 import { FrankieApiError, type ChatConversation } from "../../lib/client.js";
 import { FrankieInline } from "./FrankieInline.js";
@@ -104,7 +105,9 @@ function PageChrome({ showHistory, navigation, currentId, onSelect, onNew, ...pa
 export function FrankieChatPage({ className, style, header, footer, emptyState, renderMessage, renderTool, placeholder, autoFocus, showHistory = true, navigation, ...provider }: FrankieChatPageProps) {
   const [id, setId] = useState(() => provider.conversationId ?? crypto.randomUUID());
   const onNew = () => setId(crypto.randomUUID());
-  return <div className={["frankie-root", "frankie-chat-page", className].filter(Boolean).join(" ")} style={{ height: "100%", minHeight: "min(36rem, 100dvh)", width: "100%", ...style }}>
+  const pageRef = useRef<HTMLDivElement>(null);
+  const stylesReady = useStylesReady(pageRef);
+  return <div ref={pageRef} className={["frankie-root", "frankie-chat-page", className].filter(Boolean).join(" ")} style={{ height: "100%", minHeight: "min(36rem, 100dvh)", width: "100%", ...style, ...(stylesReady ? null : { opacity: 0 as const }) }} data-frankie-styles={stylesReady ? "ready" : "pending"}>
     <FrankieProvider {...provider} conversationId={id} storageNamespace={(provider.storageNamespace ?? "frankie." + provider.publishableKey) + "." + id}>
       <PageChrome showHistory={showHistory} navigation={navigation} currentId={id} onSelect={setId} onNew={onNew} header={header} footer={footer} emptyState={emptyState} renderMessage={renderMessage} renderTool={renderTool} placeholder={placeholder} autoFocus={autoFocus} />
     </FrankieProvider>

package/src/components/chat/FrankieInline.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import type { CSSProperties } from "react";
+import { useRef, type CSSProperties } from "react";
 import { useFrankieTheme } from "../../hooks/FrankieProvider.jsx";
+import { useStylesReady } from "../../lib/styles-ready.js";
 import { resolveMode, themeToCssVars } from "../../lib/theme.js";
 import { cn } from "../../lib/utils.js";
 import { ChatPanel, type ChatPanelProps } from "./ChatPanel.js";
@@ -23,11 +24,15 @@ export interface FrankieInlineProps extends ChatPanelProps {
 export function FrankieInline({ className, style, ...panelProps }: FrankieInlineProps) {
   const theme = useFrankieTheme();
   const mode = resolveMode(theme?.mode);
+  const rootRef = useRef<HTMLDivElement>(null);
+  const stylesReady = useStylesReady(rootRef);
   return (
     <div
+      ref={rootRef}
       className={cn("frankie-root frankie-inline", mode === "dark" && "dark", className)}
-      style={{ ...themeToCssVars(theme), display: "flex", height: "100%", width: "100%", ...style }}
+      style={{ ...themeToCssVars(theme), display: "flex", height: "100%", width: "100%", ...style, ...(stylesReady ? null : { opacity: 0 as const }) }}
       data-frankie-mode={mode}
+      data-frankie-styles={stylesReady ? "ready" : "pending"}
     >
       <ChatPanel {...panelProps} fill />
     </div>

package/src/components/chat/FrankieWidget.tsx

@@ -1,8 +1,9 @@
 "use client";
 
 import { MessageCircle, X } from "lucide-react";
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { useFrankie, useFrankieTheme } from "../../hooks/FrankieProvider.jsx";
+import { useStylesReady } from "../../lib/styles-ready.js";
 import { resolveMode, themeToCssVars } from "../../lib/theme.js";
 import { cn } from "../../lib/utils.js";
 import { Button } from "../ui/button.js";
@@ -40,6 +41,9 @@ export function FrankieWidget({
 }: FrankieWidgetProps) {
   const { config } = useFrankie();
   const theme = useFrankieTheme();
+  const rootRef = useRef<HTMLDivElement>(null);
+  // Never paint the panel as raw HTML while the host's CSS chunk is still in flight.
+  const stylesReady = useStylesReady(rootRef);
   const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen);
   const open = controlledOpen ?? uncontrolledOpen;
 
@@ -65,9 +69,14 @@ export function FrankieWidget({
 
   return (
     <div
+      ref={rootRef}
       className={cn("frankie-root frankie-widget", mode === "dark" && "dark")}
-      style={{ ...themeToCssVars(theme), position: "fixed", bottom: offset, ...side, zIndex, pointerEvents: "none" }}
+      // `opacity` rather than `visibility` or unmounting: the sentinel has to stay
+      // measurable on this element, and the two alternatives both drop the widget
+      // out of the accessibility tree for the wait.
+      style={{ ...themeToCssVars(theme), position: "fixed", bottom: offset, ...side, zIndex, pointerEvents: "none", ...(stylesReady ? null : { opacity: 0 as const }) }}
       data-frankie-mode={mode}
+      data-frankie-styles={stylesReady ? "ready" : "pending"}
     >
       <div className={cn("flex flex-col gap-3", position === "bottom-left" ? "items-start" : "items-end")}>
         {open ? <div style={{ pointerEvents: "auto", maxHeight: "calc(100dvh - 100px)", overflow: "hidden" }}><ChatPanel {...panelProps} className={cn("frankie-widget-panel", panelProps.className)} onClose={() => setOpen(false)} autoFocus /></div> : null}

package/src/components/chat/Markdown.tsx

@@ -1,19 +1,24 @@
 "use client";
 
-import { Fragment, type ReactNode } from "react";
+import { Fragment, memo, useMemo, type ReactNode } from "react";
 import { cn } from "../../lib/utils.js";
 
 /**
- * A deliberately small Markdown subset — paragraphs, lists, fenced code, bold,
- * italic, inline code and links.
+ * A deliberately small Markdown subset — headings, paragraphs, lists, fenced
+ * code, bold, italic, inline code and links.
  *
  * Everything is rendered as React elements; nothing goes through
  * `dangerouslySetInnerHTML`. Model output lands in someone else's production
  * page, so it is never trusted as markup.
+ *
+ * Memoized on `text`: while a reply streams, the parent re-renders every frame,
+ * but the block tree is only recomputed when the text actually grows — the
+ * settled messages above never re-parse at all.
  */
-export function Markdown({ text, className }: { text: string; className?: string }) {
-  return <div className={cn("frankie-prose", className)}>{renderBlocks(text)}</div>;
-}
+export const Markdown = memo(function Markdown({ text, className }: { text: string; className?: string }) {
+  const blocks = useMemo(() => renderBlocks(text), [text]);
+  return <div className={cn("frankie-prose", className)}>{blocks}</div>;
+});
 
 function renderBlocks(text: string): ReactNode[] {
   const lines = text.split("\n");
@@ -75,11 +80,13 @@ function renderBlocks(text: string): ReactNode[] {
       continue;
     }
 
-    const heading = /^#{1,6}\s+(.*)$/.exec(line);
+    const heading = /^(#{1,6})\s+(.*)$/.exec(line);
     if (heading) {
       flushParagraph();
       flushList();
-      blocks.push(<p key={`h${blocks.length}`} className="font-semibold">{renderInline(heading[1] ?? "")}</p>);
+      const level = (heading[1] ?? "#").length;
+      const Tag = level <= 1 ? "h3" : level === 2 ? "h4" : "h5";
+      blocks.push(<Tag key={`h${blocks.length}`} className="frankie-h">{renderInline(heading[2] ?? "")}</Tag>);
       continue;
     }
 

package/src/components/chat/MessageBubble.tsx

@@ -2,10 +2,12 @@
 
 import { Check, Copy, Paperclip } from "lucide-react";
 import "./message-actions.css";
-import { useState, type ReactNode } from "react";
+import { memo, useState, type ReactNode } from "react";
 import { cn } from "../../lib/utils.js";
+import { extractChoices } from "../../lib/choices.js";
 import type { ChatMessage, ToolActivity } from "../../lib/messages.js";
 import { Avatar } from "../ui/avatar.js";
+import { Choices } from "./Choices.js";
 import { Markdown } from "./Markdown.js";
 import { ToolActivityList } from "./ToolActivityList.js";
 
@@ -15,14 +17,29 @@ export interface MessageBubbleProps {
   avatarUrl?: string;
   showToolActivity: boolean;
   renderTool?: (tool: ToolActivity) => ReactNode;
+  /** Send a picked choice as the next message. Omitted when the host renders its own. */
+  onChoose?: (choice: string) => void;
+  /** Focus the composer so the user can type their own answer instead of picking. */
+  onRequestInput?: () => void;
+  /** True only for the newest message, so stale choices from earlier turns aren't clickable. */
+  active?: boolean;
+  /** A turn is in flight, so choices should be disabled. */
+  busy?: boolean;
 }
 
-export function MessageBubble({
+// Memoized: during a stream only the message whose object identity changed (the
+// one being written) re-renders. Every earlier bubble keeps its parsed markdown,
+// which is what keeps a long transcript from re-laying-out on every token.
+export const MessageBubble = memo(function MessageBubble({
   message,
   assistantName,
   avatarUrl,
   showToolActivity,
   renderTool,
+  onChoose,
+  onRequestInput,
+  active,
+  busy,
 }: MessageBubbleProps) {
   if (message.role === "user") {
     return (
@@ -51,12 +68,18 @@ export function MessageBubble({
   }
 
   const empty = message.text.length === 0 && message.tools.length === 0;
+  // Lift any offered options out of the prose. While the reply is still
+  // streaming, a half-written block is hidden (options stays null) so the raw
+  // fence never flashes. Options become clickable only on the newest, settled
+  // message so answering an earlier turn's question can't jump the transcript.
+  const { body, options } = extractChoices(message.text);
+  const showChoices = Boolean(active && onChoose && options && message.status === "done");
 
   return (
     <div className="frankie-assistant-message flex gap-2">
       <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}
+        {body ? <MessageCopyButton text={body} /> : null}
       </div>
       <div className="frankie-assistant-content min-w-0 max-w-[85%]">
         {message.status === "error" ? (
@@ -66,15 +89,16 @@ export function MessageBubble({
         ) : empty && message.status === "streaming" ? (
           <TypingDots />
         ) : (
-          <Markdown text={message.text} className="text-sm" />
+          <Markdown text={body} className="text-sm" />
         )}
+        {showChoices ? <Choices options={options ?? []} onPick={onChoose!} {...(onRequestInput ? { onSomethingElse: onRequestInput } : {})} disabled={busy} /> : null}
         {showToolActivity ? (
           <ToolActivityList tools={message.tools} {...(renderTool ? { renderTool } : {})} />
         ) : null}
       </div>
     </div>
   );
-}
+});
 
 function MessageCopyButton({ text }: { text: string }) {
   const [copied, setCopied] = useState(false);

package/src/hooks/useFrankieChat.ts

@@ -162,6 +162,49 @@ export function useFrankieChatState(): UseFrankieChatResult {
       const abort = new AbortController();
       abortRef.current = abort;
 
+      // Models stream text in uneven bursts — a few characters, then a lull,
+      // then a whole paragraph at once — which reads as a stutter no matter how
+      // efficiently React renders it. So we don't paint what arrives; we buffer
+      // it and *reveal* it at a steady cadence, a slice per animation frame, so
+      // the answer types out smoothly regardless of how lumpy the network is.
+      // The slice is a fraction of what's waiting, so a big burst drains fast
+      // (and never lags far behind) while a trickle still advances a few chars a
+      // frame. Thinking isn't rendered, so it commits in full without pacing.
+      // Any structural event, the stream's end, or an abort flushes the whole
+      // remaining buffer at once, so ordering holds and no token is dropped.
+      let bufferedText = "";
+      let pendingThinking = "";
+      let frame: number | null = null;
+      const raf = typeof requestAnimationFrame === "function" ? requestAnimationFrame : (cb: FrameRequestCallback) => setTimeout(() => cb(performance.now()), 16) as unknown as number;
+      const cancelRaf = typeof cancelAnimationFrame === "function" ? cancelAnimationFrame : (clearTimeout as (id: number) => void);
+      const revealTick = () => {
+        frame = null;
+        let addText = "";
+        if (bufferedText) {
+          // Reveal ~1/6 of what's waiting (at least a few chars) so the pace
+          // eases with the backlog: snappy on a burst, gentle on a trickle.
+          const step = Math.max(3, Math.ceil(bufferedText.length / 6));
+          addText = bufferedText.slice(0, step);
+          bufferedText = bufferedText.slice(step);
+        }
+        const addThinking = pendingThinking;
+        pendingThinking = "";
+        if (addText || addThinking) {
+          patchAssistant(assistantId, (message) => ({ ...message, text: message.text + addText, thinking: message.thinking + addThinking }));
+        }
+        if (bufferedText) scheduleReveal();
+      };
+      const scheduleReveal = () => { if (frame === null) frame = raf(revealTick); };
+      const flushDeltas = () => {
+        if (frame !== null) { cancelRaf(frame); frame = null; }
+        if (!bufferedText && !pendingThinking) return;
+        const addText = bufferedText;
+        const addThinking = pendingThinking;
+        bufferedText = "";
+        pendingThinking = "";
+        patchAssistant(assistantId, (message) => ({ ...message, text: message.text + addText, thinking: message.thinking + addThinking }));
+      };
+
       try {
         let receivedText = false;
         let receivedToolActivity = false;
@@ -177,11 +220,18 @@ export function useFrankieChatState(): UseFrankieChatResult {
             if (event.type === "skills_loaded") { setLoadedSkills(event.skills); return; }
             if (event.type === "tools_active") { setActiveApis(event.apis); return; }
             if (event.type === "ping" || event.type === "session") return;
-            if (event.type === "text_delta") receivedText = true;
+            if (event.type === "text_delta") { receivedText = true; bufferedText += event.text; scheduleReveal(); return; }
+            if (event.type === "thinking_delta") { pendingThinking += event.text; scheduleReveal(); return; }
             if (event.type === "tool_start" || event.type === "tool_end") receivedToolActivity = true;
+            // A structural event: land the buffered text before it so the tool
+            // row or terminal status sits in the right place in the transcript.
+            flushDeltas();
             patchAssistant(assistantId, (message) => applyEvent(message, event));
           },
         );
+        // Commit anything still buffered when the stream ends, so the closing
+        // words appear at once instead of trickling after the reply is done.
+        flushDeltas();
         // 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.
@@ -195,6 +245,9 @@ export function useFrankieChatState(): UseFrankieChatResult {
           }));
         }
       } catch (caught) {
+        // Land any tokens buffered when the stream broke off, so a stopped or
+        // failed turn still shows everything that had arrived.
+        flushDeltas();
         if (abort.signal.aborted) {
           patchAssistant(assistantId, (message) => ({
             ...message,
@@ -212,6 +265,9 @@ export function useFrankieChatState(): UseFrankieChatResult {
           patchAssistant(assistantId, (current) => ({ ...current, status: "error", error: message }));
         }
       } finally {
+        // Ensure no frame is left pending and every buffered token is committed
+        // before the turn settles and the transcript is persisted.
+        flushDeltas();
         // A turn that ended without a `turn_end` event still has to settle.
         patchAssistant(assistantId, (message) =>
           message.status === "streaming" ? { ...message, status: "done" } : message,

package/src/index.ts

@@ -14,6 +14,7 @@ export type { ChatPanelProps } from "./components/chat/ChatPanel.js";
 export { Composer } from "./components/chat/Composer.js";
 export { MessageBubble, TypingDots } from "./components/chat/MessageBubble.js";
 export { Markdown } from "./components/chat/Markdown.js";
+export { Choices } from "./components/chat/Choices.js";
 export { SuggestedPrompts } from "./components/chat/SuggestedPrompts.js";
 export { ToolActivityList, ToolActivityRow } from "./components/chat/ToolActivityList.js";
 
@@ -30,6 +31,8 @@ export { FrankieClient, FrankieApiError, readEventStream, FRANKIE_CLOUD_URL } fr
 export type { FrankieClientOptions, PageContext } from "./lib/client.js";
 export { applyEvent, newAssistantMessage, newUserMessage } from "./lib/messages.js";
 export type { AssistantChatMessage, ChatMessage, MessageAttachment, ToolActivity, UserChatMessage } from "./lib/messages.js";
+export { extractChoices } from "./lib/choices.js";
+export type { ExtractedChoices } from "./lib/choices.js";
 export { resolveMode, themeToCssVars } from "./lib/theme.js";
 export { cn } from "./lib/utils.js";
 

package/src/lib/choices.ts

@@ -0,0 +1,49 @@
+/**
+ * Interactive choice blocks.
+ *
+ * The agent can end a reply with a fenced block to offer the user a small set
+ * of discrete answers:
+ *
+ *     ```frankie:choices
+ *     British
+ *     Indian
+ *     Australian
+ *     ```
+ *
+ * The SDK lifts that block out of the prose and renders it as clickable options
+ * (the composer stays open, so the user can always type their own answer). The
+ * block is a plain fenced code block, so a host that doesn't understand it just
+ * shows a harmless code listing instead — never broken markup.
+ */
+export interface ExtractedChoices {
+  /** The reply text with the choices block removed. */
+  body: string;
+  /** The offered options, or null when there is no complete block. */
+  options: string[] | null;
+}
+
+const CLOSED = /```frankie:choices[ \t]*\r?\n([\s\S]*?)```/;
+const OPEN = /```frankie:choices[ \t]*\r?\n?[\s\S]*$/;
+
+export function extractChoices(text: string): ExtractedChoices {
+  const closed = CLOSED.exec(text);
+  if (closed) {
+    const options = parseOptionLines(closed[1] ?? "");
+    const body = (text.slice(0, closed.index) + text.slice(closed.index + closed[0].length))
+      .replace(/\n{3,}/g, "\n\n")
+      .trimEnd();
+    return { body, options: options.length ? options : null };
+  }
+  // An unterminated block means the reply is still streaming the options in.
+  // Hide the half-written fence so the user never sees the raw ``` marker.
+  const open = OPEN.exec(text);
+  if (open) return { body: text.slice(0, open.index).trimEnd(), options: null };
+  return { body: text, options: null };
+}
+
+function parseOptionLines(block: string): string[] {
+  return block
+    .split("\n")
+    .map((line) => line.trim().replace(/^([-*+]|\d+[.)])\s+/, "").trim())
+    .filter(Boolean);
+}

package/src/lib/styles-ready.ts

@@ -0,0 +1,71 @@
+import { useEffect, useLayoutEffect, useState, type RefObject } from "react";
+
+/** `useLayoutEffect` warns during SSR, where there is nothing to measure anyway. */
+const useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+
+/** The property `frankie.css` sets on `.frankie-root`, and the value it sets. */
+const SENTINEL = "--frankie-styles-ready";
+
+/**
+ * Whether this widget's stylesheet has actually been applied to `node`.
+ *
+ * The widget is mounted inside someone else's application and bundler. A host
+ * that imports `@frankieai/react/styles.css` from a client component ships it
+ * in that component's chunk, and on a client-side navigation React can render
+ * the panel before the CSS arrives — the panel then paints as raw HTML: native
+ * `<details>` markers, no pills, browser-default type. A full reload hides this
+ * because the stylesheet is in `<head>` before first paint.
+ *
+ * Probing a custom property costs nothing and asks the only question that
+ * matters — are our rules in effect for this element — rather than guessing at
+ * `<link>` elements the host may have inlined, bundled or renamed.
+ *
+ * Callers hide the root with `opacity` for the wait rather than `visibility` or
+ * unmounting: the sentinel must stay measurable on that element, and both of the
+ * alternatives would also drop the widget out of the accessibility tree.
+ *
+ * The wait is deliberately bounded. A Tailwind v4 host is told it may skip our
+ * stylesheet and compile the utilities itself, and such a page never sets the
+ * sentinel; it must still get a widget. After `timeoutMs` we render regardless,
+ * which is exactly today's behaviour.
+ */
+export function useStylesReady(ref: RefObject<HTMLElement | null>, timeoutMs = 600): boolean {
+  const [ready, setReady] = useState(false);
+
+  useIsomorphicLayoutEffect(() => {
+    if (ready) return;
+    const node = ref.current;
+    if (!node || typeof window === "undefined" || typeof window.getComputedStyle !== "function") {
+      setReady(true);
+      return;
+    }
+
+    const applied = () => window.getComputedStyle(node).getPropertyValue(SENTINEL).trim() === "1";
+    // The common case — stylesheet already in `<head>` — resolves here, inside a
+    // layout effect, so nothing unstyled is ever painted and nothing flickers.
+    if (applied()) {
+      setReady(true);
+      return;
+    }
+
+    const deadline = Date.now() + timeoutMs;
+    let frame = 0;
+    const poll = () => {
+      if (applied() || Date.now() >= deadline) {
+        setReady(true);
+        return;
+      }
+      frame = window.requestAnimationFrame(poll);
+    };
+    // `requestAnimationFrame` is missing in some test environments; fall back to
+    // rendering rather than hiding the widget forever.
+    if (typeof window.requestAnimationFrame !== "function") {
+      setReady(true);
+      return;
+    }
+    frame = window.requestAnimationFrame(poll);
+    return () => window.cancelAnimationFrame(frame);
+  }, [ref, ready, timeoutMs]);
+
+  return ready;
+}