@frankieai/react 0.2.8 → 0.2.10

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

@@ -71,6 +71,13 @@
   .frankie-root button:disabled { opacity:.5; cursor:not-allowed; }
   @media(max-width:760px) { .frankie-history-desktop { display:none; }.frankie-mobile-only { display:inline-flex!important; }.frankie-header-caption { display:none; }.frankie-page-header { padding:6px 10px; }.frankie-history-heading button { border:0; background:transparent; min-width:44px; min-height:44px; align-items:center; justify-content:center; }.frankie-page-prompts { gap:8px; }.frankie-widget-panel { width:calc(100vw - 32px); } }
   .frankie-root {
+    /* Sentinel. The widget mounts into someone else's bundler, where this sheet
+       can land after React has already rendered — a client-side navigation that
+       code-splits it is enough. `useStylesReady` probes this property and holds
+       the first paint, so the panel never shows as raw HTML. Keep the name and
+       the value in step with that hook. */
+    --frankie-styles-ready: 1;
+
     --frankie-background: #ffffff;
     --frankie-foreground: #0a0a0a;
     --frankie-primary: #171717;
@@ -136,22 +143,60 @@
   /* Typography for model output. Scoped so the host's prose styles do not leak
      in and ours do not leak out. */
   .frankie-prose > * + * {
-    margin-top: 0.5rem;
+    margin-top: 0.6rem;
   }
 
   .frankie-prose p {
     margin: 0;
+    line-height: 1.6;
     white-space: pre-wrap;
     overflow-wrap: anywhere;
   }
 
+  /* Headings give replies a real hierarchy instead of a wall of bold text.
+     Extra space above sets each section apart; the first one never adds a gap. */
+  .frankie-prose > .frankie-h {
+    margin-top: 1.15rem;
+    line-height: 1.3;
+    letter-spacing: -0.01em;
+  }
+  .frankie-prose > .frankie-h:first-child {
+    margin-top: 0;
+  }
+  .frankie-prose h3.frankie-h {
+    font-size: 1.06em;
+    font-weight: 700;
+  }
+  .frankie-prose h4.frankie-h {
+    font-size: 1em;
+    font-weight: 600;
+  }
+  .frankie-prose h5.frankie-h {
+    font-size: 0.92em;
+    font-weight: 600;
+    color: var(--frankie-muted-foreground);
+  }
+
+  .frankie-prose strong {
+    font-weight: 600;
+  }
+
   .frankie-prose ul,
   .frankie-prose ol {
     margin: 0;
-    padding-left: 1.15rem;
+    padding-left: 1.4rem;
     display: flex;
     flex-direction: column;
-    gap: 0.25rem;
+    gap: 0.35rem;
+  }
+
+  .frankie-prose li {
+    line-height: 1.55;
+    padding-left: 0.15rem;
+  }
+
+  .frankie-prose li::marker {
+    color: var(--frankie-muted-foreground);
   }
 
   .frankie-prose ul {
@@ -353,6 +398,23 @@
 
 /* Shared conversation surface: SDK pages, embedded panels and Frankie's app. */
 .frankie-root.frankie-chat-panel { min-height:0; position:relative; }
+
+/* Floating widget panel: a pronounced, layered lift plus a hairline ring so the
+   assistant clearly reads as an overlay hovering above the host page — not a
+   flat box flush with it. Scoped to the widget so the full-page /chat surface
+   (which is the page, not an overlay) stays shadow-free. */
+.frankie-root.frankie-widget-panel {
+  box-shadow:
+    0 32px 72px -18px color-mix(in srgb, var(--frankie-primary) 22%, rgba(15,23,42,0.42)),
+    0 12px 28px -12px rgba(15,23,42,0.28),
+    0 0 0 1px color-mix(in srgb, var(--frankie-foreground) 8%, transparent);
+}
+.frankie-root.frankie-widget-panel.dark {
+  box-shadow:
+    0 34px 80px -16px rgba(0,0,0,0.72),
+    0 14px 32px -12px rgba(0,0,0,0.6),
+    0 0 0 1px color-mix(in srgb, var(--frankie-foreground) 12%, transparent);
+}
 .frankie-root .frankie-agent-context-wrap { flex:none; display:flex; justify-content:center; padding:12px 10px; }
 .frankie-root .frankie-agent-context { position:relative; max-width:100%; color:var(--frankie-foreground); font-size:13px; }
 .frankie-root .frankie-agent-context > summary { display:flex; align-items:center; justify-content:center; gap:10px; min-height:44px; padding:7px 13px; border:1px solid var(--frankie-border); border-radius:999px; background:var(--frankie-background); box-shadow:0 1px 3px #0000000d; cursor:pointer; list-style:none; white-space:nowrap; }
@@ -384,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; }
@@ -412,3 +482,66 @@
 
 .frankie-root .frankie-agent-context > summary > span:first-of-type { border-right:1px solid var(--frankie-border); padding-right:10px; }
 @media(max-width:760px) { .frankie-root .frankie-page-header button > span { display:none; } }
+
+/* Interactive answer options offered via a frankie:choices block. Numbered,
+   full-width rows that read as pick-one buttons, matching the message surface. */
+.frankie-root .frankie-choices { display:flex; flex-direction:column; gap:8px; margin-top:12px; }
+.frankie-root .frankie-choice {
+  display:flex; align-items:center; gap:12px; width:100%; padding:11px 14px; text-align:left; cursor:pointer;
+  border:1px solid var(--frankie-border); border-radius:var(--frankie-radius); background:var(--frankie-background);
+  color:var(--frankie-foreground); font:inherit; font-size:14px; line-height:1.4;
+  transition:border-color .15s ease, background-color .15s ease, transform .12s ease;
+}
+.frankie-root .frankie-choice:hover:not(:disabled) {
+  border-color:color-mix(in srgb, var(--frankie-primary) 55%, var(--frankie-border));
+  background:color-mix(in srgb, var(--frankie-primary) 6%, var(--frankie-background));
+}
+.frankie-root .frankie-choice:active:not(:disabled) { transform:scale(.99); }
+.frankie-root .frankie-choice:focus-visible { outline:none; box-shadow:0 0 0 2px color-mix(in srgb, var(--frankie-primary) 40%, transparent); }
+.frankie-root .frankie-choice:disabled { opacity:.6; cursor:default; }
+.frankie-root .frankie-choice-index {
+  flex:none; display:grid; place-items:center; width:24px; height:24px; border-radius:50%;
+  border:1px solid var(--frankie-border); background:var(--frankie-muted);
+  color:var(--frankie-muted-foreground); font-size:12px; font-weight:600;
+  transition:background-color .15s ease, color .15s ease, border-color .15s ease;
+}
+.frankie-root .frankie-choice:hover:not(:disabled) .frankie-choice-index {
+  background:var(--frankie-primary); border-color:var(--frankie-primary); color:var(--frankie-primary-foreground);
+}
+.frankie-root .frankie-choice-label { flex:1; min-width:0; }
+.frankie-root .frankie-choice-go { flex:none; color:var(--frankie-muted-foreground); opacity:0; transform:translateX(-4px); transition:opacity .15s ease, transform .15s ease; }
+.frankie-root .frankie-choice:hover:not(:disabled) .frankie-choice-go { opacity:1; transform:none; color:var(--frankie-primary); }
+@media (prefers-reduced-motion: reduce) {
+  .frankie-root .frankie-choice, .frankie-root .frankie-choice-go, .frankie-root .frankie-choice-index { transition:none; }
+}
+
+/* "Something else" escape hatch under the offered options: visually set apart
+   (dashed, muted) so it reads as "none of these — let me type" rather than a
+   real option. It focuses the composer instead of sending. */
+.frankie-root .frankie-choice-other { border-style:dashed; color:var(--frankie-muted-foreground); }
+.frankie-root .frankie-choice-other .frankie-choice-index { background:transparent; }
+.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

@@ -0,0 +1,98 @@
+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, injectFallback }: { timeoutMs?: number; injectFallback?: boolean }) {
+  const ref = useRef<HTMLDivElement>(null);
+  const ready = useStylesReady(ref, timeoutMs, injectFallback);
+  return (
+    <div ref={ref} data-testid="root" data-frankie-styles={ready ? "ready" : "pending"}>
+      {ready ? "panel" : null}
+    </div>
+  );
+}
+
+/** Make `getComputedStyle` answer as a browser would with/without our sheet. */
+function withSentinel(present: boolean | (() => boolean)) {
+  const real = window.getComputedStyle.bind(window);
+  vi.spyOn(window, "getComputedStyle").mockImplementation((el: Element, pseudo?: string | null) => {
+    const style = real(el, pseudo ?? undefined);
+    return {
+      ...style,
+      getPropertyValue: (property: string) =>
+        property === "--frankie-styles-ready"
+          ? ((typeof present === "function" ? present() : present) ? "1" : "")
+          : style.getPropertyValue(property),
+    } as CSSStyleDeclaration;
+  });
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  __resetFrankieStylesForTests();
+});
+
+describe("useStylesReady", () => {
+  it("renders immediately when the stylesheet is already applied", () => {
+    withSentinel(true);
+    render(<Probe />);
+    // Resolved inside a layout effect, so nothing unstyled is ever painted.
+    expect(screen.getByTestId("root").dataset.frankieStyles).toBe("ready");
+    expect(screen.getByText("panel")).toBeTruthy();
+  });
+
+  it("holds the first paint while the stylesheet is still in flight", () => {
+    withSentinel(false);
+    render(<Probe />);
+    const root = screen.getByTestId("root");
+    expect(root.dataset.frankieStyles).toBe("pending");
+    expect(screen.queryByText("panel")).toBeNull();
+    // Hidden, not unmounted — the sentinel has to stay measurable on this node.
+    expect(root.isConnected).toBe(true);
+  });
+
+  it("renders as soon as a late stylesheet lands", async () => {
+    let applied = false;
+    withSentinel(() => applied);
+    render(<Probe />);
+    expect(screen.getByTestId("root").dataset.frankieStyles).toBe("pending");
+
+    applied = true; // the CSS chunk arrives
+    await waitFor(() => expect(screen.getByTestId("root").dataset.frankieStyles).toBe("ready"));
+    expect(screen.getByText("panel")).toBeTruthy();
+  });
+
+  it("gives up and renders for a host that ships no Frankie stylesheet", async () => {
+    withSentinel(false);
+    render(<Probe timeoutMs={0} />);
+    // A Tailwind v4 host compiles the utilities itself and never sets the
+    // 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();
+  });
+});