@frankieai/react 0.1.0

package/src/components/chat/Markdown.tsx

@@ -0,0 +1,136 @@
+"use client";
+
+import { Fragment, type ReactNode } from "react";
+import { cn } from "../../lib/utils.js";
+
+/**
+ * A deliberately small Markdown subset — paragraphs, lists, fenced code, bold,
+ * italic, inline code and links.
+ *
+ * Everything is rendered as React elements; nothing goes through
+ * `dangerouslySetInnerHTML`. Model output lands in someone else's production
+ * page, so it is never trusted as markup.
+ */
+export function Markdown({ text, className }: { text: string; className?: string }) {
+  return <div className={cn("frankie-prose", className)}>{renderBlocks(text)}</div>;
+}
+
+function renderBlocks(text: string): ReactNode[] {
+  const lines = text.split("\n");
+  const blocks: ReactNode[] = [];
+  let paragraph: string[] = [];
+  let list: { ordered: boolean; items: string[] } | null = null;
+  let code: { lang: string; lines: string[] } | null = null;
+
+  const flushParagraph = () => {
+    if (paragraph.length === 0) return;
+    blocks.push(<p key={`p${blocks.length}`}>{renderInline(paragraph.join(" "))}</p>);
+    paragraph = [];
+  };
+  const flushList = () => {
+    if (!list) return;
+    const items = list.items.map((item, index) => <li key={index}>{renderInline(item)}</li>);
+    blocks.push(list.ordered ? <ol key={`l${blocks.length}`}>{items}</ol> : <ul key={`l${blocks.length}`}>{items}</ul>);
+    list = null;
+  };
+
+  for (const line of lines) {
+    const fence = /^```(\w*)\s*$/.exec(line);
+    if (fence) {
+      if (code) {
+        blocks.push(
+          <pre key={`c${blocks.length}`}>
+            <code>{code.lines.join("\n")}</code>
+          </pre>,
+        );
+        code = null;
+      } else {
+        flushParagraph();
+        flushList();
+        code = { lang: fence[1] ?? "", lines: [] };
+      }
+      continue;
+    }
+    if (code) {
+      code.lines.push(line);
+      continue;
+    }
+
+    const bullet = /^\s*[-*+]\s+(.*)$/.exec(line);
+    const ordered = /^\s*\d+[.)]\s+(.*)$/.exec(line);
+    if (bullet ?? ordered) {
+      flushParagraph();
+      const isOrdered = Boolean(ordered);
+      if (!list || list.ordered !== isOrdered) {
+        flushList();
+        list = { ordered: isOrdered, items: [] };
+      }
+      list.items.push((ordered?.[1] ?? bullet?.[1]) ?? "");
+      continue;
+    }
+
+    if (line.trim() === "") {
+      flushParagraph();
+      flushList();
+      continue;
+    }
+
+    const heading = /^#{1,6}\s+(.*)$/.exec(line);
+    if (heading) {
+      flushParagraph();
+      flushList();
+      blocks.push(<p key={`h${blocks.length}`} className="font-semibold">{renderInline(heading[1] ?? "")}</p>);
+      continue;
+    }
+
+    flushList();
+    paragraph.push(line.trim());
+  }
+
+  if (code) {
+    blocks.push(
+      <pre key={`c${blocks.length}`}>
+        <code>{code.lines.join("\n")}</code>
+      </pre>,
+    );
+  }
+  flushParagraph();
+  flushList();
+  return blocks;
+}
+
+const INLINE = /(\*\*[^*]+\*\*|`[^`]+`|\[[^\]]+\]\((?:https?:\/\/|\/)[^)\s]+\)|\bhttps?:\/\/[^\s<>()]+)/g;
+
+function renderInline(text: string): ReactNode[] {
+  const nodes: ReactNode[] = [];
+  let lastIndex = 0;
+
+  for (const match of text.matchAll(INLINE)) {
+    const token = match[0];
+    const start = match.index;
+    if (start > lastIndex) nodes.push(text.slice(lastIndex, start));
+    nodes.push(<Fragment key={start}>{renderToken(token)}</Fragment>);
+    lastIndex = start + token.length;
+  }
+
+  if (lastIndex < text.length) nodes.push(text.slice(lastIndex));
+  return nodes;
+}
+
+function renderToken(token: string): ReactNode {
+  if (token.startsWith("**")) return <strong>{token.slice(2, -2)}</strong>;
+  if (token.startsWith("`")) return <code>{token.slice(1, -1)}</code>;
+
+  const link = /^\[([^\]]+)\]\(([^)]+)\)$/.exec(token);
+  const href = link ? (link[2] ?? "") : token;
+  const label = link ? (link[1] ?? "") : token;
+
+  // Only http(s) and same-site paths become links; anything else stays text,
+  // so a model can never emit a `javascript:` href into the host page.
+  if (!/^(https?:\/\/|\/)/.test(href)) return token;
+  return (
+    <a href={href} target="_blank" rel="noopener noreferrer nofollow">
+      {label}
+    </a>
+  );
+}

package/src/components/chat/MessageBubble.tsx

@@ -0,0 +1,70 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { cn } from "../../lib/utils.js";
+import type { ChatMessage, ToolActivity } from "../../lib/messages.js";
+import { Avatar } from "../ui/avatar.js";
+import { Markdown } from "./Markdown.js";
+import { ToolActivityList } from "./ToolActivityList.js";
+
+export interface MessageBubbleProps {
+  message: ChatMessage;
+  assistantName: string;
+  avatarUrl?: string;
+  showToolActivity: boolean;
+  renderTool?: (tool: ToolActivity) => ReactNode;
+}
+
+export function MessageBubble({
+  message,
+  assistantName,
+  avatarUrl,
+  showToolActivity,
+  renderTool,
+}: MessageBubbleProps) {
+  if (message.role === "user") {
+    return (
+      <div className="flex justify-end">
+        <div className="max-w-[85%] rounded-[var(--frankie-radius)] bg-primary px-3 py-2 text-sm text-primary-foreground">
+          {message.text}
+        </div>
+      </div>
+    );
+  }
+
+  const empty = message.text.length === 0 && message.tools.length === 0;
+
+  return (
+    <div className="flex gap-2">
+      <Avatar {...(avatarUrl ? { src: avatarUrl } : {})} name={assistantName} className="mt-0.5" />
+      <div className="min-w-0 max-w-[85%]">
+        {message.status === "error" ? (
+          <p className="rounded-[var(--frankie-radius)] bg-red-500/10 px-3 py-2 text-sm text-red-600 dark:text-red-400">
+            {message.error}
+          </p>
+        ) : empty && message.status === "streaming" ? (
+          <TypingDots />
+        ) : (
+          <Markdown text={message.text} className="text-sm" />
+        )}
+        {showToolActivity ? (
+          <ToolActivityList tools={message.tools} {...(renderTool ? { renderTool } : {})} />
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+export function TypingDots() {
+  return (
+    <span className="inline-flex items-center gap-1 py-2" role="status" aria-label="Thinking">
+      {[0, 1, 2].map((index) => (
+        <span
+          key={index}
+          className={cn("size-1.5 animate-pulse rounded-full bg-muted-foreground")}
+          style={{ animationDelay: `${index * 150}ms` }}
+        />
+      ))}
+    </span>
+  );
+}

package/src/components/chat/SuggestedPrompts.tsx

@@ -0,0 +1,31 @@
+"use client";
+
+import { Button } from "../ui/button.js";
+
+export function SuggestedPrompts({
+  prompts,
+  onPick,
+  disabled,
+}: {
+  prompts: string[];
+  onPick: (prompt: string) => void;
+  disabled?: boolean;
+}) {
+  if (prompts.length === 0) return null;
+  return (
+    <div className="flex flex-wrap gap-2">
+      {prompts.map((prompt) => (
+        <Button
+          key={prompt}
+          type="button"
+          size="sm"
+          variant="outline"
+          disabled={disabled}
+          onClick={() => onPick(prompt)}
+        >
+          {prompt}
+        </Button>
+      ))}
+    </div>
+  );
+}

package/src/components/chat/ToolActivityList.tsx

@@ -0,0 +1,52 @@
+"use client";
+
+import { Check, Loader2, ShieldAlert, X } from "lucide-react";
+import { Badge } from "../ui/badge.js";
+import type { ToolActivity } from "../../lib/messages.js";
+
+export interface ToolActivityListProps {
+  tools: ToolActivity[];
+  /** Replace the default row rendering entirely. */
+  renderTool?: (tool: ToolActivity) => React.ReactNode;
+}
+
+/** The "what the assistant is doing" strip under a streaming answer. */
+export function ToolActivityList({ tools, renderTool }: ToolActivityListProps) {
+  if (tools.length === 0) return null;
+  return (
+    <ul className="mt-2 flex flex-col gap-1">
+      {tools.map((tool) => (
+        <li key={tool.id}>{renderTool ? renderTool(tool) : <ToolActivityRow tool={tool} />}</li>
+      ))}
+    </ul>
+  );
+}
+
+export function ToolActivityRow({ tool }: { tool: ToolActivity }) {
+  return (
+    <Badge variant={badgeVariant(tool.status)} title={tool.detail ?? tool.name}>
+      <ToolIcon status={tool.status} />
+      <span className="truncate">{tool.label}</span>
+    </Badge>
+  );
+}
+
+function ToolIcon({ status }: { status: ToolActivity["status"] }) {
+  switch (status) {
+    case "running":
+      return <Loader2 className="size-3 animate-spin" aria-hidden="true" />;
+    case "done":
+      return <Check className="size-3" aria-hidden="true" />;
+    case "denied":
+      return <ShieldAlert className="size-3" aria-hidden="true" />;
+    default:
+      return <X className="size-3" aria-hidden="true" />;
+  }
+}
+
+function badgeVariant(status: ToolActivity["status"]): "default" | "success" | "danger" | "outline" {
+  if (status === "done") return "success";
+  if (status === "failed") return "danger";
+  if (status === "denied") return "outline";
+  return "default";
+}

package/src/components/ui/avatar.tsx

@@ -0,0 +1,30 @@
+"use client";
+
+import { cn } from "../../lib/utils.js";
+
+export interface AvatarProps {
+  src?: string;
+  name: string;
+  className?: string;
+}
+
+/** Image avatar with an initials fallback — no image request when `src` is absent. */
+export function Avatar({ src, name, className }: AvatarProps) {
+  const initials = name
+    .split(/\s+/)
+    .slice(0, 2)
+    .map((part) => part[0]?.toUpperCase() ?? "")
+    .join("");
+
+  return (
+    <span
+      className={cn(
+        "inline-flex size-7 shrink-0 items-center justify-center overflow-hidden rounded-full bg-primary text-[0.625rem] font-semibold text-primary-foreground",
+        className,
+      )}
+      aria-hidden="true"
+    >
+      {src ? <img src={src} alt="" className="size-full object-cover" /> : initials}
+    </span>
+  );
+}

package/src/components/ui/badge.tsx

@@ -0,0 +1,28 @@
+"use client";
+
+import { cva, type VariantProps } from "class-variance-authority";
+import type { HTMLAttributes } from "react";
+import { cn } from "../../lib/utils.js";
+
+const badgeVariants = cva(
+  "inline-flex items-center gap-1 rounded-full border px-2 py-0.5 text-[0.6875rem] font-medium",
+  {
+    variants: {
+      variant: {
+        default: "border-transparent bg-muted text-muted-foreground",
+        success: "border-transparent bg-emerald-500/10 text-emerald-600 dark:text-emerald-400",
+        danger: "border-transparent bg-red-500/10 text-red-600 dark:text-red-400",
+        outline: "border-border text-muted-foreground",
+      },
+    },
+    defaultVariants: { variant: "default" },
+  },
+);
+
+export function Badge({
+  className,
+  variant,
+  ...props
+}: HTMLAttributes<HTMLSpanElement> & VariantProps<typeof badgeVariants>) {
+  return <span className={cn(badgeVariants({ variant }), className)} {...props} />;
+}

package/src/components/ui/button.tsx

@@ -0,0 +1,39 @@
+"use client";
+
+import { Slot } from "@radix-ui/react-slot";
+import { cva, type VariantProps } from "class-variance-authority";
+import type { ButtonHTMLAttributes } from "react";
+import { cn } from "../../lib/utils.js";
+
+export const buttonVariants = cva(
+  "frankie-focus inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-[var(--frankie-radius)] text-sm font-medium transition-colors disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:opacity-90",
+        secondary: "bg-secondary text-secondary-foreground hover:bg-muted",
+        outline: "border border-border bg-background hover:bg-muted",
+        ghost: "hover:bg-muted",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-9 px-4 py-2",
+        sm: "h-8 rounded-[calc(var(--frankie-radius)-2px)] px-3 text-xs",
+        lg: "h-10 px-6",
+        icon: "size-9",
+      },
+    },
+    defaultVariants: { variant: "default", size: "default" },
+  },
+);
+
+export interface ButtonProps
+  extends ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean;
+}
+
+export function Button({ className, variant, size, asChild = false, ...props }: ButtonProps) {
+  const Comp = asChild ? Slot : "button";
+  return <Comp className={cn(buttonVariants({ variant, size }), className)} {...props} />;
+}

package/src/components/ui/card.tsx

@@ -0,0 +1,36 @@
+"use client";
+
+import type { HTMLAttributes } from "react";
+import { cn } from "../../lib/utils.js";
+
+export function Card({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn(
+        "flex flex-col rounded-[calc(var(--frankie-radius)+4px)] border border-border bg-background text-foreground shadow-lg",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function CardHeader({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn("flex items-center gap-3 border-b border-border px-4 py-3", className)} {...props} />;
+}
+
+export function CardTitle({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn("text-sm font-semibold leading-tight", className)} {...props} />;
+}
+
+export function CardDescription({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn("text-xs text-muted-foreground", className)} {...props} />;
+}
+
+export function CardContent({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn("flex-1 overflow-hidden", className)} {...props} />;
+}
+
+export function CardFooter({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn("border-t border-border p-3", className)} {...props} />;
+}

package/src/components/ui/scroll-area.tsx

@@ -0,0 +1,15 @@
+"use client";
+
+import { forwardRef, type HTMLAttributes } from "react";
+import { cn } from "../../lib/utils.js";
+
+/**
+ * A plain overflow container rather than Radix's ScrollArea: the widget lives
+ * inside someone else's page, and a native scroller inherits their scrollbar
+ * behaviour instead of fighting it.
+ */
+export const ScrollArea = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(
+  function ScrollArea({ className, ...props }, ref) {
+    return <div ref={ref} className={cn("frankie-scroll overflow-y-auto overscroll-contain", className)} {...props} />;
+  },
+);

package/src/components/ui/separator.tsx

@@ -0,0 +1,7 @@
+"use client";
+
+import { cn } from "../../lib/utils.js";
+
+export function Separator({ className }: { className?: string }) {
+  return <div role="separator" className={cn("h-px w-full bg-border", className)} />;
+}

package/src/components/ui/textarea.tsx

@@ -0,0 +1,20 @@
+"use client";
+
+import { forwardRef, type TextareaHTMLAttributes } from "react";
+import { cn } from "../../lib/utils.js";
+
+/** `forwardRef` rather than React 19's ref-as-prop, so React 18 hosts work too. */
+export const Textarea = forwardRef<HTMLTextAreaElement, TextareaHTMLAttributes<HTMLTextAreaElement>>(
+  function Textarea({ className, ...props }, ref) {
+    return (
+      <textarea
+        ref={ref}
+        className={cn(
+          "frankie-focus flex min-h-[2.25rem] w-full resize-none rounded-[var(--frankie-radius)] border border-border bg-background px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50",
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);

package/src/hooks/FrankieProvider.tsx

@@ -0,0 +1,94 @@
+"use client";
+
+import { createContext, useContext, useEffect, useMemo, useState, type ReactNode } from "react";
+import type { PublicWidgetConfig, WidgetTheme } from "@frankieai/core";
+import { FrankieClient, type FrankieClientOptions, type PageContext } from "../lib/client.js";
+
+export interface FrankieProviderProps extends FrankieClientOptions {
+  children: ReactNode;
+  /**
+   * Page context sent with every turn — current route, plan tier, whatever the
+   * agent should know. Treated as data by the server, never as instructions.
+   */
+  context?: PageContext;
+  /** Overrides for the server-side theme, so a host can restyle without a redeploy. */
+  theme?: WidgetTheme;
+  /** Skip the `/v1/config` fetch by supplying the config yourself. */
+  config?: PublicWidgetConfig;
+}
+
+interface FrankieContextValue {
+  client: FrankieClient;
+  config?: PublicWidgetConfig;
+  configError?: string;
+  loading: boolean;
+  context?: PageContext;
+  theme?: WidgetTheme;
+}
+
+const FrankieContext = createContext<FrankieContextValue | null>(null);
+
+export function FrankieProvider({
+  children,
+  context,
+  theme,
+  config: providedConfig,
+  ...clientOptions
+}: FrankieProviderProps) {
+  const client = useMemo(
+    () => new FrankieClient(clientOptions),
+    // The client holds session state; rebuild it only when the endpoint changes.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [clientOptions.baseUrl, clientOptions.publishableKey],
+  );
+
+  const [config, setConfig] = useState<PublicWidgetConfig | undefined>(providedConfig);
+  const [configError, setConfigError] = useState<string | undefined>(undefined);
+  const [loading, setLoading] = useState(!providedConfig);
+
+  useEffect(() => {
+    if (providedConfig) return;
+    const abort = new AbortController();
+    setLoading(true);
+    client
+      .getConfig(abort.signal)
+      .then((next) => {
+        setConfig(next);
+        setConfigError(undefined);
+      })
+      .catch((error: unknown) => {
+        if (abort.signal.aborted) return;
+        setConfigError(error instanceof Error ? error.message : "Could not load the assistant.");
+      })
+      .finally(() => {
+        if (!abort.signal.aborted) setLoading(false);
+      });
+    return () => abort.abort();
+  }, [client, providedConfig]);
+
+  const value = useMemo<FrankieContextValue>(
+    () => ({
+      client,
+      ...(config ? { config } : {}),
+      ...(configError ? { configError } : {}),
+      loading,
+      ...(context ? { context } : {}),
+      ...(theme ? { theme } : {}),
+    }),
+    [client, config, configError, loading, context, theme],
+  );
+
+  return <FrankieContext.Provider value={value}>{children}</FrankieContext.Provider>;
+}
+
+export function useFrankie(): FrankieContextValue {
+  const value = useContext(FrankieContext);
+  if (!value) throw new Error("Frankie components must be rendered inside <FrankieProvider>.");
+  return value;
+}
+
+/** The theme actually in effect: provider override wins over server config. */
+export function useFrankieTheme(): WidgetTheme | undefined {
+  const { config, theme } = useFrankie();
+  return useMemo(() => ({ ...config?.theme, ...theme }), [config?.theme, theme]);
+}