@frankieai/react 0.2.7 → 0.2.9

package/src/lib/styles-ready.ts

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

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; }
@@ -412,3 +474,44 @@
 
 .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); }

package/src/styles-ready.test.tsx

@@ -0,0 +1,71 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { useRef } from "react";
+import { useStylesReady } from "./lib/styles-ready.js";
+
+/** Stand-in for a widget root: reports what the hook decided. */
+function Probe({ timeoutMs }: { timeoutMs?: number }) {
+  const ref = useRef<HTMLDivElement>(null);
+  const ready = useStylesReady(ref, timeoutMs);
+  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());
+
+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"));
+  });
+});

package/src/widget.test.tsx

@@ -261,6 +261,23 @@ describe("ChatPanel", () => {
     await waitFor(() => expect(scrollTop).toBe(scroller.scrollHeight));
     cleanup();
   });
+  it("shows the active API spec hash and operation count once tools_active arrives", async () => {
+    cleanup();
+    const fetchImpl = vi.fn(async (url: string | URL | Request) =>
+      String(url).endsWith("/v1/session")
+        ? Response.json({ sessionId: "apis", sessionToken: "fixture", expiresAt: new Date(Date.now() + 600_000).toISOString(), user: { id: "one", anonymous: true } })
+        : new Response(sseStream([{ type: "tools_active", apis: [{ name: "acme", specHash: "abc123def456", operationCount: 4 }] }, { type: "text_delta", text: "Done" }, { type: "turn_end", stopReason: "end_turn" }])),
+    );
+    render(<FrankieProvider publishableKey="pk_apis_fixture" config={config} fetchImpl={fetchImpl} persist={false}><ChatPanel /></FrankieProvider>);
+    await waitFor(() => expect((screen.getByLabelText("Message") as HTMLTextAreaElement).disabled).toBe(false));
+    fireEvent.change(screen.getByLabelText("Message"), { target: { value: "Hi" } });
+    fireEvent.click(screen.getByRole("button", { name: "Send" }));
+    await screen.findByText("Done");
+    fireEvent.click(screen.getByLabelText("Agent context"));
+    expect(screen.getByText("acme")).toBeTruthy();
+    expect(screen.getByText("spec abc123def456 · 4 operations")).toBeTruthy();
+  });
+
   it("refreshes the context count and revisions from each server turn", async () => {
     cleanup();
     let turn = 0;