@frankieai/react 0.2.8 → 0.2.10

package/src/hooks/FrankieProvider.tsx

@@ -3,6 +3,7 @@
 import { createContext, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
 import type { PublicWidgetConfig, WidgetTheme } from "@frankieai/core";
 import { FrankieClient, type FrankieClientOptions, type PageContext } from "../lib/client.js";
+import { inferHostTheme } from "../lib/theme-inherit.js";
 import { FrankieChatContext, useFrankieChatState } from "./useFrankieChat.js";
 
 export interface FrankieProviderProps extends FrankieClientOptions {
@@ -10,6 +11,15 @@ export interface FrankieProviderProps extends FrankieClientOptions {
   context?: PageContext;
   theme?: WidgetTheme;
   config?: PublicWidgetConfig;
+  /**
+   * Set to `false` if the host compiles Frankie's classes itself instead of
+   * loading `@frankieai/react/styles.css` — e.g. a Tailwind v4 host that
+   * `@source`s this package — so it isn't given a second, independently-themed
+   * copy of the stylesheet when its own build never sets the styles-ready
+   * sentinel. Defaults to `true`: a host that simply forgot the import, or
+   * whose CSS chunk hasn't landed yet, still gets a correctly-styled widget.
+   */
+  injectStyles?: boolean;
 }
 
 interface FrankieContextValue {
@@ -19,6 +29,7 @@ interface FrankieContextValue {
   loading: boolean;
   context?: PageContext;
   theme?: WidgetTheme;
+  injectStyles: boolean;
 }
 
 const FrankieContext = createContext<FrankieContextValue | null>(null);
@@ -28,6 +39,7 @@ export function FrankieProvider({
   context,
   theme,
   config: providedConfig,
+  injectStyles = true,
   ...clientOptions
 }: FrankieProviderProps) {
   const tokenCallback = useRef(clientOptions.getUserToken);
@@ -35,7 +47,7 @@ export function FrankieProvider({
   const client = useMemo(
     () => new FrankieClient({ ...clientOptions, ...(clientOptions.getUserToken ? { getUserToken: () => tokenCallback.current?.() } : {}) }),
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [clientOptions.baseUrl, clientOptions.publishableKey, clientOptions.storageNamespace, clientOptions.conversationId, clientOptions.persist, clientOptions.fetchImpl, Boolean(clientOptions.getUserToken)],
+    [clientOptions.baseUrl, clientOptions.publishableKey, clientOptions.storageNamespace, clientOptions.conversationId, clientOptions.persist, clientOptions.fetchImpl, clientOptions.api?.baseUrl, clientOptions.api?.credentials, Boolean(clientOptions.getUserToken)],
   );
 
   const [config, setConfig] = useState<PublicWidgetConfig | undefined>(providedConfig);
@@ -70,8 +82,9 @@ export function FrankieProvider({
       loading,
       ...(context ? { context } : {}),
       ...(theme ? { theme } : {}),
+      injectStyles,
     }),
-    [client, config, configError, loading, context, theme],
+    [client, config, configError, loading, context, theme, injectStyles],
   );
 
   return <FrankieContext.Provider value={value}><ConversationState key={client.namespace + ":" + (client.conversationId ?? "")}>{children}</ConversationState></FrankieContext.Provider>;
@@ -90,5 +103,19 @@ export function useFrankie(): FrankieContextValue {
 
 export function useFrankieTheme(): WidgetTheme | undefined {
   const { config, theme } = useFrankie();
-  return useMemo(() => ({ ...config?.theme, ...theme }), [config?.theme, theme]);
+  const merged = useMemo<WidgetTheme | undefined>(() => ({ ...config?.theme, ...theme }), [config?.theme, theme]);
+  const inheriting = merged?.source === "inherit";
+  // Sampling reads the live DOM, so it can only run once mounted — not during
+  // the render that decides `inheriting`, and never on the server.
+  const [inferred, setInferred] = useState<Partial<WidgetTheme> | null>(null);
+  useEffect(() => {
+    setInferred(inheriting ? inferHostTheme() : null);
+  }, [inheriting]);
+  return useMemo(() => {
+    if (!inheriting || !inferred) return merged;
+    // Detection succeeded: the host's own colors replace the configured
+    // palette, which stays as the fallback already folded into `merged`
+    // wherever a specific inferred value is missing.
+    return { ...merged, ...inferred };
+  }, [merged, inheriting, inferred]);
 }

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

@@ -12,8 +12,9 @@ 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";
-export { MessageBubble, TypingDots } from "./components/chat/MessageBubble.js";
+export { MessageBubble, TypingDots, Thinking } 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/client.ts

@@ -3,11 +3,35 @@ import type {
   ChatRequestBody,
   CreateSessionResponse,
   FrankieServerEvent,
+  HostToolRequest,
+  HostToolResult,
   PublicWidgetConfig,
 } from "@frankieai/core";
+import { sessionIdentity } from "./identity.js";
 
 export type PageContext = Record<string, string | number | boolean | null>;
 
+/**
+ * How the widget reaches the host's own API for client-side tool execution.
+ *
+ * When a workspace marks an API source `execution: "client"`, Frankie asks the
+ * browser to make the call itself — from the user's existing session — instead
+ * of calling the API from Frankie's servers. This says where that API lives and
+ * how the browser authenticates to it: normally the app's own cookies
+ * (`credentials: "include"` on a same-origin or CORS-allowed API), or a bearer
+ * token the app already holds, added via `headers`. Frankie sends no credential
+ * of its own; the host API authorizes the call exactly as it would any request
+ * from the host's frontend.
+ */
+export interface HostApiClientOptions {
+  /** Base URL that operation paths resolve against, e.g. "/api" or "https://api.acme.com". */
+  baseUrl: string;
+  /** fetch credentials mode. "include" sends the app's cookies. Defaults to "same-origin". */
+  credentials?: RequestCredentials;
+  /** Extra headers for every host call (e.g. an app access token). Awaited per call. */
+  headers?: () => Promise<Record<string, string>> | Record<string, string>;
+}
+
 /**
  * The hosted Frankie data plane. Embedding needs only a publishable key, so
  * `baseUrl` defaults here — override it only when self-hosting the server.
@@ -26,6 +50,13 @@ export interface FrankieClientOptions {
    */
   getUserToken?: () => Promise<string | undefined> | string | undefined;
   fetchImpl?: typeof fetch;
+  /**
+   * Reaches the host's own API for `execution: "client"` tool calls (see
+   * `HostApiClientOptions`). Required only for workspaces that use client-side
+   * execution; omit it and a client-mode tool reports that no host API is
+   * configured rather than calling anything.
+   */
+  api?: HostApiClientOptions;
   /**
    * Remember the session (and, in the hook, the transcript) in localStorage so a
    * page reload resumes the same anonymous conversation. Authenticated chat
@@ -59,7 +90,8 @@ export class FrankieClient {
   private readonly baseUrl: string;
   private readonly doFetch: typeof fetch;
   private session?: CreateSessionResponse;
-  private sessionUserToken?: string;
+  /** Identity (JWT `sub`, else the raw token) the cached session was issued for. */
+  private sessionUserKey?: string;
 
   constructor(private readonly options: FrankieClientOptions) {
     this.baseUrl = (options.baseUrl ?? FRANKIE_CLOUD_URL).replace(/\/+$/, "");
@@ -121,7 +153,20 @@ export class FrankieClient {
   }
 
   async ensureSession(context?: PageContext): Promise<CreateSessionResponse> {
-    const userToken = await this.options.getUserToken?.();
+    // The host's token endpoint knows why it failed (not signed in, secret
+    // missing, lookup not wired); a thrown Error carries that reason to the user.
+    let userToken: string | undefined;
+    try {
+      userToken = await this.options.getUserToken?.();
+    } catch (error) {
+      this.resetSession();
+      const reason = error instanceof Error && error.message.trim() ? error.message.trim() : undefined;
+      throw new FrankieApiError(
+        reason ?? "Your signed-in Frankie session could not be verified. Refresh the page and sign in again.",
+        401,
+        "user_token_unavailable",
+      );
+    }
     if (this.options.getUserToken && !userToken) {
       this.resetSession();
       throw new FrankieApiError(
@@ -130,7 +175,13 @@ export class FrankieClient {
         "user_token_unavailable",
       );
     }
-    if (userToken !== this.sessionUserToken) this.resetSession();
+    // Reset only when the *person* changed, not when the same person's token
+    // was re-minted. Hosts mint a fresh JWT (with `iat`) before every turn, so
+    // comparing raw bytes threw the session away on every message and started
+    // a new, empty transcript each time — the agent never saw the last turn.
+    // Sign-out is handled above; a different user resets here as before.
+    const userKey = sessionIdentity(userToken);
+    if (userKey !== this.sessionUserKey) this.resetSession();
     if (this.session && new Date(this.session.expiresAt).getTime() > Date.now() + 30_000) return this.session;
     const response = await this.doFetch(`${this.baseUrl}/v1/session`, {
       method: "POST",
@@ -142,7 +193,7 @@ export class FrankieClient {
       }),
     });
     this.session = (await this.unwrap(response)) as CreateSessionResponse;
-    this.sessionUserToken = userToken;
+    this.sessionUserKey = userKey;
     this.writeStored();
     return this.session;
   }
@@ -166,7 +217,7 @@ export class FrankieClient {
     if (response.status === 404) return undefined;
     const body = (await this.unwrap(response)) as { session: CreateSessionResponse; messages?: unknown[]; title?: string };
     this.session = body.session;
-    this.sessionUserToken = userToken;
+    this.sessionUserKey = sessionIdentity(userToken);
     this.writeStored();
     return { messages: Array.isArray(body.messages) ? body.messages : [], title: body.title ?? "New chat" };
   }
@@ -242,10 +293,77 @@ export class FrankieClient {
     }
 
     for await (const event of readEventStream(response.body)) {
+      // A client-side tool call is handled here, not surfaced to the UI: run it
+      // against the host API on the user's own session and POST the outcome
+      // back. It runs detached so reading the stream never blocks on a host call
+      // (the server's agent loop is what waits, via the tool-result endpoint).
+      if (event.type === "tool_call_request") {
+        void this.runClientTool(session, event.callId, event.request);
+        continue;
+      }
       onEvent(event);
     }
   }
 
+  /**
+   * Execute one host API call in the browser and report the outcome back to the
+   * server. Never throws: a transport failure or a missing `api` client becomes
+   * a result the model can see and explain, exactly like a non-2xx status.
+   */
+  private async runClientTool(
+    session: CreateSessionResponse,
+    callId: string,
+    request: HostToolRequest,
+  ): Promise<void> {
+    const result = await this.callHostApi(request);
+    await this.postToolResult(session, callId, result).catch(() => undefined);
+  }
+
+  private async callHostApi(request: HostToolRequest): Promise<HostToolResult> {
+    const api = this.options.api;
+    if (!api) {
+      return {
+        status: 0,
+        error:
+          "This assistant tried to call your API from the browser, but no host API client is configured " +
+          "in the Frankie SDK (the `api` option).",
+      };
+    }
+    try {
+      const extra = api.headers ? await api.headers() : {};
+      const response = await this.doFetch(joinHostUrl(api.baseUrl, request.path), {
+        method: request.method,
+        credentials: api.credentials ?? "same-origin",
+        headers: {
+          accept: "application/json, text/plain;q=0.9, */*;q=0.8",
+          ...(request.body !== undefined ? { "content-type": "application/json" } : {}),
+          ...extra,
+        },
+        ...(request.body !== undefined ? { body: JSON.stringify(request.body) } : {}),
+      });
+      const body = await response.text().catch(() => "");
+      return { status: response.status, body };
+    } catch (error) {
+      return { status: 0, error: error instanceof Error ? error.message : String(error) };
+    }
+  }
+
+  private async postToolResult(
+    session: CreateSessionResponse,
+    callId: string,
+    result: HostToolResult,
+  ): Promise<void> {
+    await this.doFetch(`${this.baseUrl}/v1/chat/tool-result`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-frankie-key": this.options.publishableKey,
+        authorization: `Bearer ${session.sessionToken}`,
+      },
+      body: JSON.stringify({ callId, result }),
+    });
+  }
+
   private async unwrap(response: Response): Promise<unknown> {
     if (response.ok) return response.json();
     let code = "internal";
@@ -261,6 +379,19 @@ export class FrankieClient {
   }
 }
 
+/**
+ * Join the host's configured base URL with a server-supplied relative path. The
+ * server always sends a relative path (params interpolated, no scheme or host),
+ * and this refuses anything that looks absolute or protocol-relative — so a tool
+ * call can never be steered to a different origin than the one the host set.
+ */
+export function joinHostUrl(baseUrl: string, path: string): string {
+  if (/^[a-z][a-z0-9+.-]*:/i.test(path) || path.startsWith("//")) {
+    throw new Error("A client tool path must be relative to the configured host API base URL.");
+  }
+  return `${baseUrl.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+}
+
 export async function* readEventStream(
   body: ReadableStream<Uint8Array>,
 ): AsyncGenerator<FrankieServerEvent> {

package/src/lib/ensure-frankie-styles.ts

@@ -0,0 +1,32 @@
+import { FRANKIE_CSS_CONTENT } from "../generated/css-content.js";
+
+const STYLE_ELEMENT_ID = "frankie-fallback-styles";
+let attempted = false;
+
+/**
+ * Last resort for a host that never loaded `@frankieai/react/styles.css` —
+ * forgot the import, or its CSS chunk hasn't landed by the time
+ * `useStylesReady`'s bounded wait gives up. Injects the same stylesheet the
+ * package ships as `./styles.css`, so the widget still renders correctly
+ * instead of as raw, unstyled HTML.
+ *
+ * Only called when a host hasn't opted out via `injectStyles={false}` — the
+ * documented escape hatch for a host that compiles Frankie's classes itself
+ * (e.g. a Tailwind v4 host `@source`-ing this package) and would not want a
+ * second, independently-themed copy of the stylesheet appended.
+ */
+export function ensureFrankieStyles(): void {
+  if (attempted || typeof document === "undefined") return;
+  attempted = true;
+  if (document.getElementById(STYLE_ELEMENT_ID)) return;
+  const style = document.createElement("style");
+  style.id = STYLE_ELEMENT_ID;
+  style.textContent = FRANKIE_CSS_CONTENT;
+  document.head.appendChild(style);
+}
+
+/** Test-only: clears the injected-once guard so each test starts clean. */
+export function __resetFrankieStylesForTests(): void {
+  attempted = false;
+  document.getElementById(STYLE_ELEMENT_ID)?.remove();
+}

package/src/lib/identity.ts

@@ -0,0 +1,39 @@
+/**
+ * The stable identity a host-signed user token carries, used only to decide
+ * whether a cached chat session still belongs to the same person.
+ *
+ * The client never verifies the token — it has no secret, and the server
+ * re-verifies on every `/v1/session` anyway. It only needs a key that stays
+ * constant while the same user's token is re-minted. A JWT's `sub` is that
+ * key: hosts mint with `setIssuedAt()`, so the raw string changes every
+ * second even though nothing about the user did.
+ *
+ * Anything that isn't a readable JWT falls back to the raw token, which is
+ * exactly the previous behaviour — an opaque token that changes still resets
+ * the session, so this can only ever reuse a session, never leak one.
+ */
+export function sessionIdentity(token: string | undefined): string | undefined {
+  if (!token) return undefined;
+  return jwtSubject(token) ?? token;
+}
+
+function jwtSubject(token: string): string | undefined {
+  const parts = token.split(".");
+  if (parts.length !== 3 || !parts[1]) return undefined;
+  try {
+    const payload = JSON.parse(base64UrlDecode(parts[1])) as { sub?: unknown };
+    return typeof payload.sub === "string" && payload.sub ? payload.sub : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function base64UrlDecode(segment: string): string {
+  const base64 = segment.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64 + "=".repeat((4 - (base64.length % 4)) % 4);
+  if (typeof atob === "function") {
+    const bytes = atob(padded);
+    return decodeURIComponent(Array.from(bytes, (c) => "%" + c.charCodeAt(0).toString(16).padStart(2, "0")).join(""));
+  }
+  return Buffer.from(padded, "base64").toString("utf8");
+}

package/src/lib/styles-ready.ts

@@ -0,0 +1,83 @@
+import { useEffect, useLayoutEffect, useState, type RefObject } from "react";
+import { ensureFrankieStyles } from "./ensure-frankie-styles.js";
+
+/** `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. After `timeoutMs`, with no sentinel found,
+ * this injects the stylesheet itself (`ensureFrankieStyles`) as a fallback for
+ * a host that never loaded `styles.css` — the far more common way this shows
+ * up in practice than the one case it must not clobber: a Tailwind v4 host
+ * told it may skip our stylesheet and compile the same classes itself, which
+ * also never sets the sentinel. That host opts out with `injectStyles={false}`
+ * so it doesn't get a second, independently-themed copy of the stylesheet.
+ */
+export function useStylesReady(ref: RefObject<HTMLElement | null>, timeoutMs = 600, injectFallback = true): 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()) {
+        setReady(true);
+        return;
+      }
+      if (Date.now() >= deadline) {
+        // Inline `<style>` insertion applies synchronously, so re-check right
+        // after — but set `ready` regardless, matching the pre-existing
+        // "never hide the widget forever" guarantee.
+        if (injectFallback) ensureFrankieStyles();
+        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, injectFallback]);
+
+  return ready;
+}