@frankieai/react 0.2.9 → 0.2.11

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

@@ -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,18 @@
 .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%; }
+/* The bottom-left toolbar: attach + model picker on one row (not stacked). In
+   the full-page composer the textarea floats to its own top row (order:-1), so
+   this group and the send button share the row below — group left, send right. */
+.frankie-root .frankie-composer-actions { display:flex; align-items:center; gap:6px; min-width:0; }
+/* 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 +527,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/host-safety.test.ts

@@ -0,0 +1,57 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+/**
+ * The widget stylesheet is loaded into arbitrary host pages. It must never
+ * restyle a host's own elements — every rule has to be scoped to
+ * `.frankie-root`. This guards the two ways that broke before: a Tailwind
+ * Preflight-style reset of bare elements, and (the one that actually shipped)
+ * the design tokens Tailwind emits onto a global `:root,:host`, which reset a
+ * Tailwind-v4 host's spacing/typography scale. See scripts/scope-host-safe.mjs.
+ */
+const root = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+const css = readFileSync(join(root, "dist", "frankie.css"), "utf8");
+// The same string is embedded into the JS bundle for the fallback injector.
+const embedded = readFileSync(join(root, "src", "generated", "css-content.ts"), "utf8");
+
+/** Selectors at a rule boundary that would reach the host document. */
+function globalSelectors(source: string): string[] {
+  const stripped = source.replace(/\/\*[\s\S]*?\*\//g, "");
+  const hits: string[] = [];
+  // A selector list before `{`, at the start or just after `}` / `{`.
+  const rule = /(?:^|[}{])\s*([^@{}][^{}]*?)\s*\{/g;
+  let m: RegExpExecArray | null;
+  while ((m = rule.exec(stripped))) {
+    const selector = (m[1] ?? "").trim();
+    // Fine: anything scoped to the widget root, or Tailwind's registered
+    // custom properties / keyframes (those never target host elements).
+    if (selector.includes(".frankie-root")) continue;
+    // A host-reaching selector: a global root, a bare element, `*`, `html`,
+    // `body`, or an attribute/class not under `.frankie-root`.
+    if (/(^|,)\s*(:root|:host|\*|html|body|h[1-6]|p|ul|ol|li|a|img|button|input|figure|blockquote|table)\b/.test(selector)
+        || /(^|,)\s*:(root|host)\b/.test(selector)) {
+      hits.push(selector);
+    }
+  }
+  return hits;
+}
+
+describe("widget stylesheet is host-safe", () => {
+  it("dist/frankie.css has no selector that reaches the host document", () => {
+    expect(globalSelectors(css)).toEqual([]);
+  });
+
+  it("never emits a global :root/:host token block (the LessonCast breakage)", () => {
+    expect(css).not.toMatch(/(?:^|[}{])\s*:(?:root|host)(?:\s*,\s*:(?:root|host))*\s*\{/);
+    // --spacing drives every Tailwind spacing utility; it must live on the
+    // widget root, never on the host's.
+    expect(css).toMatch(/\.frankie-root\{[^}]*--spacing:/);
+  });
+
+  it("the JS-embedded fallback copy is scoped the same way", () => {
+    expect(embedded).not.toMatch(/:(?:root|host)\s*[,{]/);
+    expect(embedded).toContain(".frankie-root");
+  });
+});

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();
+  });
 });