@frankieai/react 0.2.9 → 0.2.10

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

@@ -1,4 +1,5 @@
 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;
@@ -24,12 +25,15 @@ const SENTINEL = "--frankie-styles-ready";
  * 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.
+ * 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): boolean {
+export function useStylesReady(ref: RefObject<HTMLElement | null>, timeoutMs = 600, injectFallback = true): boolean {
   const [ready, setReady] = useState(false);
 
   useIsomorphicLayoutEffect(() => {
@@ -51,7 +55,15 @@ export function useStylesReady(ref: RefObject<HTMLElement | null>, timeoutMs = 6
     const deadline = Date.now() + timeoutMs;
     let frame = 0;
     const poll = () => {
-      if (applied() || Date.now() >= deadline) {
+      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;
       }
@@ -65,7 +77,7 @@ export function useStylesReady(ref: RefObject<HTMLElement | null>, timeoutMs = 6
     }
     frame = window.requestAnimationFrame(poll);
     return () => window.cancelAnimationFrame(frame);
-  }, [ref, ready, timeoutMs]);
+  }, [ref, ready, timeoutMs, injectFallback]);
 
   return ready;
 }

package/src/lib/theme-inherit.test.ts

@@ -0,0 +1,68 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { inferHostTheme } from "./theme-inherit.js";
+
+/** Answer `getComputedStyle` with fixed colors per element, keyed by a data attribute. */
+function stubComputedStyle(styles: Record<string, { backgroundColor: string; color: string }>) {
+  vi.spyOn(window, "getComputedStyle").mockImplementation((el: Element) => {
+    const key = el === document.body ? "body" : (el as HTMLElement).dataset.stub;
+    const found = key ? styles[key] : undefined;
+    return (found ?? { backgroundColor: "rgba(0, 0, 0, 0)", color: "rgba(0, 0, 0, 0)" }) as CSSStyleDeclaration;
+  });
+}
+
+describe("inferHostTheme", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    document.body.innerHTML = "";
+  });
+
+  it("reads a light page's background, text and a button's accent color", () => {
+    document.body.innerHTML = '<button data-stub="accent">Buy now</button>';
+    stubComputedStyle({
+      body: { backgroundColor: "rgb(255, 255, 255)", color: "rgb(10, 10, 10)" },
+      accent: { backgroundColor: "rgb(37, 99, 235)", color: "rgb(255, 255, 255)" },
+    });
+    const theme = inferHostTheme();
+    expect(theme).toEqual({
+      background: "rgb(255, 255, 255)",
+      foreground: "rgb(10, 10, 10)",
+      primary: "rgb(37, 99, 235)",
+      primaryForeground: "#fafafa", // the accent itself is dark, so light text reads on it
+    });
+  });
+
+  it("prefers an explicit data-frankie-accent hook over a guessed button", () => {
+    document.body.innerHTML = '<a href="/pricing" data-stub="wrong-guess">Pricing</a><button data-frankie-accent data-stub="real-accent">Go</button>';
+    stubComputedStyle({
+      body: { backgroundColor: "rgb(255, 255, 255)", color: "rgb(10, 10, 10)" },
+      "wrong-guess": { backgroundColor: "rgb(255, 255, 255)", color: "rgb(80, 80, 80)" }, // no real accent — a plain link
+      "real-accent": { backgroundColor: "rgb(220, 38, 38)", color: "rgb(255, 255, 255)" },
+    });
+    const theme = inferHostTheme();
+    expect(theme?.primary).toBe("rgb(220, 38, 38)");
+  });
+
+  it("returns null for a transparent body background — nothing real to read", () => {
+    stubComputedStyle({ body: { backgroundColor: "rgba(0, 0, 0, 0)", color: "rgb(10, 10, 10)" } });
+    expect(inferHostTheme()).toBeNull();
+  });
+
+  it("returns null when background and text are too close to distinguish", () => {
+    stubComputedStyle({ body: { backgroundColor: "rgb(120, 120, 120)", color: "rgb(130, 130, 130)" } });
+    expect(inferHostTheme()).toBeNull();
+  });
+
+  it("returns null when nothing on the page reads as a distinct accent", () => {
+    document.body.innerHTML = '<button data-stub="blends-in">OK</button>';
+    stubComputedStyle({
+      body: { backgroundColor: "rgb(255, 255, 255)", color: "rgb(10, 10, 10)" },
+      "blends-in": { backgroundColor: "rgb(255, 255, 255)", color: "rgb(10, 10, 10)" }, // identical to the page — not an accent
+    });
+    expect(inferHostTheme()).toBeNull();
+  });
+
+  it("never guesses on a DOM access failure", () => {
+    vi.spyOn(window, "getComputedStyle").mockImplementation(() => { throw new Error("boom"); });
+    expect(inferHostTheme()).toBeNull();
+  });
+});

package/src/lib/theme-inherit.ts

@@ -0,0 +1,89 @@
+import type { WidgetTheme } from "@frankieai/core";
+
+type Rgba = [number, number, number, number];
+
+/** Computed colors always come back as `rgb()`/`rgba()`, never a hex or name. */
+function parseRgb(value: string): Rgba | null {
+  const match = value.match(/rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)(?:\s*[,/]\s*([\d.]+%?))?\s*\)/i);
+  if (!match) return null;
+  const alpha = match[4] === undefined ? 1 : match[4].endsWith("%") ? Number(match[4].slice(0, -1)) / 100 : Number(match[4]);
+  return [Number(match[1]), Number(match[2]), Number(match[3]), alpha];
+}
+
+function toCss([r, g, b, a]: Rgba): string {
+  return a >= 1 ? `rgb(${r}, ${g}, ${b})` : `rgba(${r}, ${g}, ${b}, ${a})`;
+}
+
+function sameColor(a: Rgba, b: Rgba): boolean {
+  return Math.abs(a[0] - b[0]) < 12 && Math.abs(a[1] - b[1]) < 12 && Math.abs(a[2] - b[2]) < 12;
+}
+
+/** Relative luminance (WCAG), 0 = black, 1 = white. */
+function luminance([r, g, b]: Rgba): number {
+  const channel = (c: number) => {
+    const v = c / 255;
+    return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+
+function contrastRatio(a: Rgba, b: Rgba): number {
+  const la = luminance(a), lb = luminance(b);
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+/**
+ * Elements likely to carry a site's own accent color, checked in order.
+ * `data-frankie-accent` is an explicit opt-in hook a host can add to any
+ * element (e.g. their own primary button) to make detection reliable instead
+ * of guessed; everything after it is a heuristic guess at a "branded"
+ * element, weakest last.
+ */
+const ACCENT_SELECTORS = ["[data-frankie-accent]", "button[type=submit]", "a[href]", "button", "[class*=primary]", "[class*=btn]"];
+
+/**
+ * Best-effort read of the host page's own background/text/accent colors, for
+ * a workspace that chose "inherit my site's theme" over a manually configured
+ * palette. Deliberately conservative: returns `null` — never a guess — the
+ * moment anything sampled looks unreliable (no DOM to read, a transparent
+ * body background, illegible contrast, no element that reads as an accent),
+ * so the caller falls back to the configured or default theme rather than
+ * shipping a widget that looks broken on a page this heuristic can't read.
+ *
+ * Never attempts full brand-color extraction (logos, images, gradients) —
+ * only colors real elements are already rendering with, via
+ * `getComputedStyle`. Runs once per mount; it does not track the host
+ * toggling its own light/dark mode after that.
+ */
+export function inferHostTheme(): Partial<WidgetTheme> | null {
+  if (typeof document === "undefined" || typeof getComputedStyle !== "function") return null;
+  try {
+    const bodyStyle = getComputedStyle(document.body);
+    const background = parseRgb(bodyStyle.backgroundColor);
+    const foreground = parseRgb(bodyStyle.color);
+    if (!background || !foreground) return null;
+    if (background[3] < 0.5) return null; // a transparent/near-transparent body tells us nothing real
+    if (contrastRatio(background, foreground) < 2) return null; // too low-contrast to trust as a real reading
+
+    let accent: Rgba | null = null;
+    for (const selector of ACCENT_SELECTORS) {
+      const element = document.querySelector(selector);
+      if (!element) continue;
+      const style = getComputedStyle(element);
+      const surface = parseRgb(style.backgroundColor);
+      if (surface && surface[3] > 0.5 && !sameColor(surface, background)) { accent = surface; break; }
+      const text = parseRgb(style.color);
+      if (text && text[3] > 0.5 && !sameColor(text, foreground)) { accent = text; break; }
+    }
+    if (!accent) return null; // nothing distinct enough from the page's own surface to call an accent
+
+    return {
+      background: toCss(background),
+      foreground: toCss(foreground),
+      primary: toCss(accent),
+      primaryForeground: luminance(accent) > 0.5 ? "#0a0a0a" : "#fafafa",
+    };
+  } catch {
+    return null; // any DOM access failure (unusual host environment): never guess
+  }
+}

package/src/styles/frankie.css

@@ -446,6 +446,14 @@
 .frankie-root.frankie-chat-panel-fill .frankie-composer textarea { order:-1; flex:0 0 100%; width:100%; min-height:32px; max-height:140px; margin-bottom:4px; padding:2px 6px; border:0; border-radius:0; resize:none; background:transparent; color:var(--frankie-foreground); font-size:16px; box-shadow:none; outline:none; }
 .frankie-root.frankie-chat-panel-fill .frankie-composer button[aria-label="Send"],.frankie-root.frankie-chat-panel-fill .frankie-composer button[aria-label="Stop"] { margin-left:auto; width:42px; height:42px; border-radius:50%; background:var(--frankie-primary); color:var(--frankie-primary-foreground); border:0; }
 .frankie-root.frankie-chat-panel-fill .frankie-composer button[aria-label="Attach files"] { width:42px; height:42px; border-radius:50%; }
+/* Compact model picker — a subtle bottom-left control (like Claude's), not a
+   full-height dropdown crowding the send row. */
+.frankie-root .frankie-composer-meta { display:flex; align-items:center; gap:8px; margin-top:6px; padding:0 2px; }
+.frankie-root .frankie-model-picker { display:inline-flex; align-items:center; min-width:0; }
+.frankie-root .frankie-model-select { appearance:none; -webkit-appearance:none; max-width:12rem; border:0; border-radius:8px; background-color:transparent; color:var(--frankie-muted-foreground); font:inherit; font-size:12px; font-weight:500; line-height:1; padding:5px 22px 5px 8px; cursor:pointer; text-overflow:ellipsis; background-image:url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 24 24' fill='none' stroke='%238b8b8b' stroke-width='2.5' stroke-linecap='round' stroke-linejoin='round'><polyline points='6 9 12 15 18 9'/></svg>"); background-repeat:no-repeat; background-position:right 6px center; background-size:11px; transition:background-color .12s ease, color .12s ease; }
+.frankie-root .frankie-model-select:hover { background-color:var(--frankie-muted); color:var(--frankie-foreground); }
+.frankie-root .frankie-model-select:disabled { opacity:.5; cursor:not-allowed; }
+.frankie-root .frankie-model-select option { color:var(--frankie-foreground); background:var(--frankie-background); font-weight:400; }
 .frankie-root .frankie-history-desktop { width:290px; background:var(--frankie-background); padding:20px 12px; }
 .frankie-root .frankie-history-collapsed { width:56px; padding:20px 8px; }
 .frankie-root .frankie-new-chat { justify-content:flex-start; border:0; background:transparent; padding:8px 12px; font-size:15px; }
@@ -515,3 +523,25 @@
 .frankie-root .frankie-choice-other:hover:not(:disabled) { color:var(--frankie-foreground); }
 .frankie-root .frankie-choice-other:hover:not(:disabled) .frankie-choice-index { background:var(--frankie-muted); border-color:var(--frankie-border); color:var(--frankie-foreground); }
 .frankie-root .frankie-choice-hint { flex:none; font-size:12px; color:var(--frankie-muted-foreground); }
+
+/* Loading skeleton shown while a reply is still being produced (before the
+   first words, or in the pause after a tool result). Shimmering placeholder
+   tiles so the gap reads as "loading" rather than a frozen chat. */
+.frankie-root .frankie-skeleton { display:flex; flex-direction:column; gap:8px; padding:4px 0 6px; max-width:min(420px, 100%); }
+.frankie-root .frankie-skeleton-line {
+  height:12px; border-radius:6px;
+  background:linear-gradient(90deg,
+    color-mix(in srgb, var(--frankie-muted-foreground) 11%, transparent) 25%,
+    color-mix(in srgb, var(--frankie-muted-foreground) 26%, transparent) 37%,
+    color-mix(in srgb, var(--frankie-muted-foreground) 11%, transparent) 63%);
+  background-size:400% 100%;
+  animation:frankie-shimmer 1.4s ease infinite;
+}
+@keyframes frankie-shimmer { 0% { background-position:100% 50%; } 100% { background-position:0 50%; } }
+@keyframes frankie-skeleton-pulse { 0%,100% { opacity:.45; } 50% { opacity:.85; } }
+@media (prefers-reduced-motion: reduce) {
+  .frankie-root .frankie-skeleton-line {
+    background:color-mix(in srgb, var(--frankie-muted-foreground) 16%, transparent);
+    animation:frankie-skeleton-pulse 1.6s ease-in-out infinite;
+  }
+}

package/src/styles-ready.test.tsx

@@ -1,12 +1,13 @@
 import { render, screen, waitFor } from "@testing-library/react";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { useRef } from "react";
+import { __resetFrankieStylesForTests } from "./lib/ensure-frankie-styles.js";
 import { useStylesReady } from "./lib/styles-ready.js";
 
 /** Stand-in for a widget root: reports what the hook decided. */
-function Probe({ timeoutMs }: { timeoutMs?: number }) {
+function Probe({ timeoutMs, injectFallback }: { timeoutMs?: number; injectFallback?: boolean }) {
   const ref = useRef<HTMLDivElement>(null);
-  const ready = useStylesReady(ref, timeoutMs);
+  const ready = useStylesReady(ref, timeoutMs, injectFallback);
   return (
     <div ref={ref} data-testid="root" data-frankie-styles={ready ? "ready" : "pending"}>
       {ready ? "panel" : null}
@@ -29,7 +30,10 @@ function withSentinel(present: boolean | (() => boolean)) {
   });
 }
 
-afterEach(() => vi.restoreAllMocks());
+afterEach(() => {
+  vi.restoreAllMocks();
+  __resetFrankieStylesForTests();
+});
 
 describe("useStylesReady", () => {
   it("renders immediately when the stylesheet is already applied", () => {
@@ -68,4 +72,27 @@ describe("useStylesReady", () => {
     // sentinel; it must still get a widget rather than an invisible one.
     await waitFor(() => expect(screen.getByTestId("root").dataset.frankieStyles).toBe("ready"));
   });
+
+  it("injects the stylesheet itself once the wait for a host's own copy runs out", async () => {
+    withSentinel(false);
+    render(<Probe timeoutMs={0} />);
+    await waitFor(() => expect(screen.getByTestId("root").dataset.frankieStyles).toBe("ready"));
+    expect(document.getElementById("frankie-fallback-styles")).not.toBeNull();
+  });
+
+  it("never injects a second copy for a host that opted out with injectStyles={false}", async () => {
+    withSentinel(false);
+    render(<Probe timeoutMs={0} injectFallback={false} />);
+    await waitFor(() => expect(screen.getByTestId("root").dataset.frankieStyles).toBe("ready"));
+    // The Tailwind v4 opt-out case: this host compiles the same classes itself
+    // and never sets the sentinel either, so a blind fallback would give it an
+    // unwanted, independently-themed second stylesheet.
+    expect(document.getElementById("frankie-fallback-styles")).toBeNull();
+  });
+
+  it("never injects the fallback when the host's own stylesheet is already applied", () => {
+    withSentinel(true);
+    render(<Probe />);
+    expect(document.getElementById("frankie-fallback-styles")).toBeNull();
+  });
 });

package/src/widget.test.tsx

@@ -5,6 +5,7 @@ import { FrankieProvider } from "./hooks/FrankieProvider.jsx";
 import { ChatPanel } from "./components/chat/ChatPanel.js";
 import { FrankieChatPage } from "./components/chat/FrankieChatPage.js";
 import { Markdown } from "./components/chat/Markdown.js";
+import { sessionIdentity } from "./lib/identity.js";
 import { FrankieClient, readEventStream } from "./lib/client.js";
 import { applyEvent, newAssistantMessage } from "./lib/messages.js";
 import { themeToCssVars } from "./lib/theme.js";
@@ -157,6 +158,75 @@ describe("FrankieClient", () => {
     expect(headers["x-frankie-key"]).toBe("pk_1");
   });
 
+  /** A JWT with the given claims; the signature is irrelevant to the client. */
+  const jwt = (claims: Record<string, unknown>) =>
+    `h.${Buffer.from(JSON.stringify(claims)).toString("base64url")}.sig`;
+
+  it("keeps the same session when the same user's token is re-minted between turns", async () => {
+    // Hosts mint with setIssuedAt(), so every getUserToken() call returns a
+    // different string for the same person. That must not start a new,
+    // empty conversation — the agent would never see the previous turn.
+    let iat = 1_700_000_000;
+    const getUserToken = () => jwt({ sub: "user_42", iat: iat++ });
+    let sessionCalls = 0;
+    const bearers: string[] = [];
+    const fetchImpl = vi.fn(async (url: string | URL | Request, init?: RequestInit) => {
+      const href = String(url);
+      if (href.endsWith("/v1/session")) {
+        sessionCalls += 1;
+        return Response.json({ sessionId: `s${sessionCalls}`, sessionToken: `bearer-${sessionCalls}`, expiresAt: new Date(Date.now() + 600_000).toISOString(), user: { id: "user_42", anonymous: false } });
+      }
+      bearers.push((init?.headers as Record<string, string>)["authorization"] ?? "");
+      return new Response(sseStream([{ type: "text_delta", text: "ok" }]), { status: 200 });
+    }) as unknown as typeof fetch;
+
+    const client = new FrankieClient({ publishableKey: "pk_rotate", getUserToken, fetchImpl });
+    await client.send({ message: "first" }, () => {});
+    await client.send({ message: "second" }, () => {});
+
+    expect(sessionCalls).toBe(1);
+    expect(bearers).toEqual(["Bearer bearer-1", "Bearer bearer-1"]);
+    expect(client.sessionId).toBe("s1");
+  });
+
+  it("still starts a new session when a different user signs in", async () => {
+    let sub = "user_42";
+    const getUserToken = () => jwt({ sub, iat: 1 });
+    let sessionCalls = 0;
+    const fetchImpl = vi.fn(async (url: string | URL | Request) => {
+      if (String(url).endsWith("/v1/session")) {
+        sessionCalls += 1;
+        return Response.json({ sessionId: `s${sessionCalls}`, sessionToken: `bearer-${sessionCalls}`, expiresAt: new Date(Date.now() + 600_000).toISOString(), user: { id: sub, anonymous: false } });
+      }
+      return new Response(sseStream([{ type: "text_delta", text: "ok" }]), { status: 200 });
+    }) as unknown as typeof fetch;
+
+    const client = new FrankieClient({ publishableKey: "pk_switch", getUserToken, fetchImpl });
+    await client.send({ message: "as 42" }, () => {});
+    sub = "user_99"; // account change on the host
+    await client.send({ message: "as 99" }, () => {});
+
+    expect(sessionCalls).toBe(2);
+    expect(client.sessionId).toBe("s2");
+  });
+
+  it("falls back to comparing an opaque token, so a changed one still resets", async () => {
+    let token = "opaque-token-a";
+    let sessionCalls = 0;
+    const fetchImpl = vi.fn(async (url: string | URL | Request) => {
+      if (String(url).endsWith("/v1/session")) {
+        sessionCalls += 1;
+        return Response.json({ sessionId: `s${sessionCalls}`, sessionToken: `b${sessionCalls}`, expiresAt: new Date(Date.now() + 600_000).toISOString(), user: { id: "u", anonymous: false } });
+      }
+      return new Response(sseStream([{ type: "text_delta", text: "ok" }]), { status: 200 });
+    }) as unknown as typeof fetch;
+    const client = new FrankieClient({ publishableKey: "pk_opaque", getUserToken: () => token, fetchImpl });
+    await client.send({ message: "a" }, () => {});
+    token = "opaque-token-b";
+    await client.send({ message: "b" }, () => {});
+    expect(sessionCalls).toBe(2);
+  });
+
   it("drops a rejected session so the next send re-authenticates", async () => {
     let sessionCalls = 0;
     const fetchImpl = vi.fn(async (url: string | URL | Request) => {
@@ -333,6 +403,49 @@ describe("ChatPanel", () => {
     expect(root.style.getPropertyValue("--frankie-primary")).toBe("rgb(255, 0, 128)");
     expect(root.classList.contains("dark")).toBe(true);
   });
+
+  it("inherits the host page's own colors once sampling succeeds", async () => {
+    document.body.innerHTML = '<button data-stub="host-accent">Buy</button>';
+    const real = window.getComputedStyle.bind(window);
+    vi.spyOn(window, "getComputedStyle").mockImplementation((el: Element) => {
+      if (el === document.body) return { backgroundColor: "rgb(250, 250, 250)", color: "rgb(20, 20, 20)" } as CSSStyleDeclaration;
+      if ((el as HTMLElement).dataset?.stub === "host-accent") return { backgroundColor: "rgb(16, 185, 129)", color: "rgb(255, 255, 255)" } as CSSStyleDeclaration;
+      return real(el);
+    });
+    const { container } = render(
+      <FrankieProvider
+        baseUrl="https://agent.acme.com"
+        publishableKey="pk_1"
+        config={{ ...config, theme: { mode: "light", source: "inherit", primary: "#configured-fallback" } }}
+      >
+        <ChatPanel />
+      </FrankieProvider>,
+    );
+    const root = () => container.querySelector(".frankie-root") as HTMLElement;
+    // Sampling runs post-mount, so the first paint still shows the configured
+    // fallback — never a blank/undefined value — until inference resolves.
+    await waitFor(() => expect(root().style.getPropertyValue("--frankie-primary")).toBe("rgb(16, 185, 129)"));
+    expect(root().style.getPropertyValue("--frankie-background")).toBe("rgb(250, 250, 250)");
+    vi.restoreAllMocks();
+  });
+
+  it("keeps the configured fallback when the host page can't be read reliably", async () => {
+    vi.spyOn(window, "getComputedStyle").mockImplementation(() => ({ backgroundColor: "rgba(0, 0, 0, 0)", color: "rgba(0, 0, 0, 0)" }) as CSSStyleDeclaration);
+    const { container } = render(
+      <FrankieProvider
+        baseUrl="https://agent.acme.com"
+        publishableKey="pk_1"
+        config={{ ...config, theme: { mode: "light", source: "inherit", primary: "rgb(1, 2, 3)" } }}
+      >
+        <ChatPanel />
+      </FrankieProvider>,
+    );
+    const root = container.querySelector(".frankie-root") as HTMLElement;
+    // A transparent body background means inference declines to guess, so
+    // the configured value is what the widget shows — not left blank.
+    await waitFor(() => expect(root.style.getPropertyValue("--frankie-primary")).toBe("rgb(1, 2, 3)"));
+    vi.restoreAllMocks();
+  });
 });
 
 describe("FrankieChatPage", () => {
@@ -366,3 +479,108 @@ describe("FrankieChatPage", () => {
     cleanup();
   });
 });
+
+describe("sessionIdentity", () => {
+  const jwt = (claims: Record<string, unknown>) => `h.${Buffer.from(JSON.stringify(claims)).toString("base64url")}.sig`;
+  it("reads the JWT subject", () => expect(sessionIdentity(jwt({ sub: "user_42", iat: 1 }))).toBe("user_42"));
+  it("is stable across re-minted tokens for the same subject", () =>
+    expect(sessionIdentity(jwt({ sub: "u", iat: 1 }))).toBe(sessionIdentity(jwt({ sub: "u", iat: 2 }))));
+  it("falls back to the raw token when there is no readable subject", () => {
+    expect(sessionIdentity("opaque")).toBe("opaque");
+    expect(sessionIdentity("a.b")).toBe("a.b");
+    expect(sessionIdentity(jwt({ iat: 1 }))).toBe(jwt({ iat: 1 }));
+    expect(sessionIdentity("h.%%%notbase64%%%.s")).toBe("h.%%%notbase64%%%.s");
+  });
+  it("maps a missing token to undefined", () => expect(sessionIdentity(undefined)).toBeUndefined());
+});
+
+describe("client-side tool execution", () => {
+  it("joinHostUrl joins base and relative path, and refuses an absolute one", async () => {
+    const { joinHostUrl } = await import("./lib/client.js");
+    expect(joinHostUrl("https://app.acme.com/api", "restaurants/1?x=2")).toBe("https://app.acme.com/api/restaurants/1?x=2");
+    expect(joinHostUrl("https://app.acme.com/api/", "/restaurants")).toBe("https://app.acme.com/api/restaurants");
+    expect(() => joinHostUrl("https://app.acme.com", "https://evil.com/steal")).toThrow(/relative/);
+    expect(() => joinHostUrl("https://app.acme.com", "//evil.com/steal")).toThrow(/relative/);
+  });
+
+  it("runs a tool_call_request against the host API and posts the outcome back", async () => {
+    const calls: Array<{ url: string; init?: RequestInit }> = [];
+    const fetchImpl = vi.fn(async (url: string | URL | Request, init?: RequestInit) => {
+      const href = String(url);
+      calls.push({ url: href, ...(init ? { init } : {}) });
+      if (href.endsWith("/v1/session")) {
+        return Response.json({ sessionId: "s1", sessionToken: "bearer-1", expiresAt: new Date(Date.now() + 600_000).toISOString(), user: { id: "u", anonymous: true } });
+      }
+      if (href.endsWith("/v1/chat")) {
+        return new Response(
+          sseStream([
+            { type: "tool_call_request", callId: "c-1", toolUseId: "c-1", name: "api__acme__getRestaurant", request: { source: "acme", method: "GET", path: "restaurants/9" } },
+            { type: "text_delta", text: "done" },
+            { type: "turn_end", stopReason: "end_turn" },
+          ]),
+          { status: 200 },
+        );
+      }
+      if (href.endsWith("/v1/chat/tool-result")) return Response.json({ ok: true });
+      // The host API call itself.
+      return new Response(JSON.stringify({ name: "Bistro" }), { status: 200 });
+    }) as unknown as typeof fetch;
+
+    const client = new FrankieClient({
+      baseUrl: "https://agent.acme.com",
+      publishableKey: "pk_client_exec",
+      api: { baseUrl: "https://app.acme.com/api", credentials: "include" },
+      fetchImpl,
+      persist: false,
+    });
+
+    await client.send({ message: "show me restaurant 9" }, () => {});
+
+    // The host API was called from the browser, at the configured base, with the
+    // app's own credentials — Frankie added no Authorization of its own.
+    await waitFor(() => expect(calls.some((c) => c.url === "https://app.acme.com/api/restaurants/9")).toBe(true));
+    const hostCall = calls.find((c) => c.url === "https://app.acme.com/api/restaurants/9")!;
+    expect(hostCall.init?.method).toBe("GET");
+    expect(hostCall.init?.credentials).toBe("include");
+    expect((hostCall.init?.headers as Record<string, string> | undefined)?.["authorization"]).toBeUndefined();
+
+    // The outcome was posted back with the matching callId and the host status.
+    await waitFor(() => expect(calls.some((c) => c.url.endsWith("/v1/chat/tool-result"))).toBe(true));
+    const post = calls.find((c) => c.url.endsWith("/v1/chat/tool-result"))!;
+    const body = JSON.parse(String(post.init?.body)) as { callId: string; result: { status: number; body: string } };
+    expect(body.callId).toBe("c-1");
+    expect(body.result.status).toBe(200);
+    expect(body.result.body).toContain("Bistro");
+  });
+
+  it("reports a transport failure when no host api client is configured", async () => {
+    const calls: Array<{ url: string; init?: RequestInit }> = [];
+    const fetchImpl = vi.fn(async (url: string | URL | Request, init?: RequestInit) => {
+      const href = String(url);
+      calls.push({ url: href, ...(init ? { init } : {}) });
+      if (href.endsWith("/v1/session")) {
+        return Response.json({ sessionId: "s1", sessionToken: "b1", expiresAt: new Date(Date.now() + 600_000).toISOString(), user: { id: "u", anonymous: true } });
+      }
+      if (href.endsWith("/v1/chat")) {
+        return new Response(
+          sseStream([
+            { type: "tool_call_request", callId: "c-2", toolUseId: "c-2", name: "api__acme__x", request: { source: "acme", method: "GET", path: "x" } },
+            { type: "turn_end", stopReason: "end_turn" },
+          ]),
+          { status: 200 },
+        );
+      }
+      return Response.json({ ok: true });
+    }) as unknown as typeof fetch;
+
+    // No `api` option configured.
+    const client = new FrankieClient({ baseUrl: "https://agent.acme.com", publishableKey: "pk_no_api", fetchImpl, persist: false });
+    await client.send({ message: "hi" }, () => {});
+
+    await waitFor(() => expect(calls.some((c) => c.url.endsWith("/v1/chat/tool-result"))).toBe(true));
+    const post = calls.find((c) => c.url.endsWith("/v1/chat/tool-result"))!;
+    const body = JSON.parse(String(post.init?.body)) as { result: { status: number; error?: string } };
+    expect(body.result.status).toBe(0);
+    expect(body.result.error).toMatch(/no host API client/i);
+  });
+});