@gram-ai/elements 1.33.2 → 1.35.0

package/src/plugins/generative-ui/ui/separator.tsx

@@ -10,7 +10,7 @@ function Separator({
   orientation = "horizontal",
   decorative = true,
   ...props
-}: React.ComponentProps<typeof SeparatorPrimitive.Root>) {
+}: React.ComponentProps<typeof SeparatorPrimitive.Root>): React.JSX.Element {
   return (
     <SeparatorPrimitive.Root
       data-slot="separator"

package/src/plugins/generative-ui/ui/skeleton-wrapper.tsx

@@ -17,7 +17,7 @@ export function SkeletonWrapper({
   width,
   height,
   className,
-}: SkeletonWrapperProps) {
+}: SkeletonWrapperProps): React.JSX.Element {
   return (
     <Skeleton
       className={cn(className)}

package/src/plugins/generative-ui/ui/skeleton.tsx

@@ -1,6 +1,9 @@
 import { cn } from "@/lib/utils";
 
-function Skeleton({ className, ...props }: React.ComponentProps<"div">) {
+function Skeleton({
+  className,
+  ...props
+}: React.ComponentProps<"div">): React.JSX.Element {
   return (
     <div
       data-slot="skeleton"

package/src/plugins/generative-ui/ui/stack.tsx

@@ -36,7 +36,7 @@ export function Stack({
   justify,
   className,
   ...props
-}: StackProps) {
+}: StackProps): React.JSX.Element {
   return (
     <div
       data-slot="stack"

package/src/plugins/generative-ui/ui/switch.tsx

@@ -11,7 +11,7 @@ function Switch({
   ...props
 }: React.ComponentProps<typeof SwitchPrimitive.Root> & {
   size?: "sm" | "default";
-}) {
+}): React.JSX.Element {
   return (
     <SwitchPrimitive.Root
       data-slot="switch"

package/src/plugins/generative-ui/ui/table.tsx

@@ -4,7 +4,10 @@ import * as React from "react";
 
 import { cn } from "@/lib/utils";
 
-function Table({ className, ...props }: React.ComponentProps<"table">) {
+function Table({
+  className,
+  ...props
+}: React.ComponentProps<"table">): React.JSX.Element {
   return (
     <div
       data-slot="table-container"
@@ -19,7 +22,10 @@ function Table({ className, ...props }: React.ComponentProps<"table">) {
   );
 }
 
-function TableHeader({ className, ...props }: React.ComponentProps<"thead">) {
+function TableHeader({
+  className,
+  ...props
+}: React.ComponentProps<"thead">): React.JSX.Element {
   return (
     <thead
       data-slot="table-header"
@@ -29,7 +35,10 @@ function TableHeader({ className, ...props }: React.ComponentProps<"thead">) {
   );
 }
 
-function TableBody({ className, ...props }: React.ComponentProps<"tbody">) {
+function TableBody({
+  className,
+  ...props
+}: React.ComponentProps<"tbody">): React.JSX.Element {
   return (
     <tbody
       data-slot="table-body"
@@ -39,7 +48,10 @@ function TableBody({ className, ...props }: React.ComponentProps<"tbody">) {
   );
 }
 
-function TableFooter({ className, ...props }: React.ComponentProps<"tfoot">) {
+function TableFooter({
+  className,
+  ...props
+}: React.ComponentProps<"tfoot">): React.JSX.Element {
   return (
     <tfoot
       data-slot="table-footer"
@@ -52,7 +64,10 @@ function TableFooter({ className, ...props }: React.ComponentProps<"tfoot">) {
   );
 }
 
-function TableRow({ className, ...props }: React.ComponentProps<"tr">) {
+function TableRow({
+  className,
+  ...props
+}: React.ComponentProps<"tr">): React.JSX.Element {
   return (
     <tr
       data-slot="table-row"
@@ -65,7 +80,10 @@ function TableRow({ className, ...props }: React.ComponentProps<"tr">) {
   );
 }
 
-function TableHead({ className, ...props }: React.ComponentProps<"th">) {
+function TableHead({
+  className,
+  ...props
+}: React.ComponentProps<"th">): React.JSX.Element {
   return (
     <th
       data-slot="table-head"
@@ -78,7 +96,10 @@ function TableHead({ className, ...props }: React.ComponentProps<"th">) {
   );
 }
 
-function TableCell({ className, ...props }: React.ComponentProps<"td">) {
+function TableCell({
+  className,
+  ...props
+}: React.ComponentProps<"td">): React.JSX.Element {
   return (
     <td
       data-slot="table-cell"
@@ -94,7 +115,7 @@ function TableCell({ className, ...props }: React.ComponentProps<"td">) {
 function TableCaption({
   className,
   ...props
-}: React.ComponentProps<"caption">) {
+}: React.ComponentProps<"caption">): React.JSX.Element {
   return (
     <caption
       data-slot="table-caption"

package/src/plugins/generative-ui/ui/tabs-wrapper.tsx

@@ -21,7 +21,7 @@ export function TabsWrapper({
   defaultValue,
   tabs,
   children,
-}: TabsWrapperProps) {
+}: TabsWrapperProps): React.JSX.Element {
   const defaultTab = defaultValue ?? tabs[0]?.value;
 
   return (
@@ -46,6 +46,9 @@ export interface TabContentWrapperProps {
 /**
  * TabContent wrapper - passes through to TabsContent.
  */
-export function TabContentWrapper({ value, children }: TabContentWrapperProps) {
+export function TabContentWrapper({
+  value,
+  children,
+}: TabContentWrapperProps): React.JSX.Element {
   return <TabsContentPrimitive value={value}>{children}</TabsContentPrimitive>;
 }

package/src/plugins/generative-ui/ui/tabs.tsx

@@ -10,7 +10,7 @@ function Tabs({
   className,
   orientation = "horizontal",
   ...props
-}: React.ComponentProps<typeof TabsPrimitive.Root>) {
+}: React.ComponentProps<typeof TabsPrimitive.Root>): React.JSX.Element {
   return (
     <TabsPrimitive.Root
       data-slot="tabs"
@@ -45,7 +45,7 @@ function TabsList({
   variant = "default",
   ...props
 }: React.ComponentProps<typeof TabsPrimitive.List> &
-  VariantProps<typeof tabsListVariants>) {
+  VariantProps<typeof tabsListVariants>): React.JSX.Element {
   return (
     <TabsPrimitive.List
       data-slot="tabs-list"
@@ -59,7 +59,7 @@ function TabsList({
 function TabsTrigger({
   className,
   ...props
-}: React.ComponentProps<typeof TabsPrimitive.Trigger>) {
+}: React.ComponentProps<typeof TabsPrimitive.Trigger>): React.JSX.Element {
   return (
     <TabsPrimitive.Trigger
       data-slot="tabs-trigger"
@@ -78,7 +78,7 @@ function TabsTrigger({
 function TabsContent({
   className,
   ...props
-}: React.ComponentProps<typeof TabsPrimitive.Content>) {
+}: React.ComponentProps<typeof TabsPrimitive.Content>): React.JSX.Element {
   return (
     <TabsPrimitive.Content
       data-slot="tabs-content"

package/src/plugins/generative-ui/ui/text.tsx

@@ -20,7 +20,7 @@ export function Text({
   className,
   children,
   ...props
-}: TextProps) {
+}: TextProps): React.JSX.Element {
   return (
     <span
       data-slot="text"

package/src/plugins/generative-ui/ui/textarea.tsx

@@ -2,7 +2,10 @@ import * as React from "react";
 
 import { cn } from "@/lib/utils";
 
-function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
+function Textarea({
+  className,
+  ...props
+}: React.ComponentProps<"textarea">): React.JSX.Element {
   return (
     <textarea
       data-slot="textarea"

package/src/plugins/generative-ui/ui/tooltip.tsx

@@ -8,7 +8,7 @@ import { cn } from "@/lib/utils";
 function TooltipProvider({
   delayDuration = 0,
   ...props
-}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
+}: React.ComponentProps<typeof TooltipPrimitive.Provider>): React.JSX.Element {
   return (
     <TooltipPrimitive.Provider
       data-slot="tooltip-provider"
@@ -20,13 +20,13 @@ function TooltipProvider({
 
 function Tooltip({
   ...props
-}: React.ComponentProps<typeof TooltipPrimitive.Root>) {
+}: React.ComponentProps<typeof TooltipPrimitive.Root>): React.JSX.Element {
   return <TooltipPrimitive.Root data-slot="tooltip" {...props} />;
 }
 
 function TooltipTrigger({
   ...props
-}: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
+}: React.ComponentProps<typeof TooltipPrimitive.Trigger>): React.JSX.Element {
   return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />;
 }
 
@@ -35,7 +35,7 @@ function TooltipContent({
   sideOffset = 0,
   children,
   ...props
-}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+}: React.ComponentProps<typeof TooltipPrimitive.Content>): React.JSX.Element {
   return (
     <TooltipPrimitive.Portal>
       <TooltipPrimitive.Content

package/src/react-shim.ts

@@ -10,10 +10,15 @@ import { createShims } from "./compat-shims";
 
 const Shimmed = { ...ReactOriginal, ...createShims(ReactOriginal) };
 
-// React internals required by react-dom
-export const __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED =
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  (ReactOriginal as any).__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED;
+// React internals required by react-dom. Not part of React's public types;
+// declared here as an opaque escape hatch so consuming code can re-export the
+// same symbol react-dom looks up at runtime.
+interface ReactInternals {
+  __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED?: unknown;
+}
+export const __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED = (
+  ReactOriginal as ReactInternals
+).__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED;
 
 export const {
   Children,

package/src/server/bun.ts

@@ -33,7 +33,7 @@ export function createBunHandler(
     | ((
         request: Request,
       ) => SessionHandlerOptions | Promise<SessionHandlerOptions>),
-) {
+): (request: Request) => Promise<Response> {
   return async (request: Request) => {
     const projectSlug = request.headers.get("gram-project");
 

package/src/server/express.ts

@@ -34,7 +34,7 @@ export function createExpressHandler(
     | ((
         req: Request,
       ) => SessionHandlerOptions | Promise<SessionHandlerOptions>),
-) {
+): (req: Request, res: Response) => Promise<void> {
   return async (req: Request, res: Response) => {
     const projectSlug = Array.isArray(req.headers["gram-project"])
       ? req.headers["gram-project"][0]

package/src/server/fastify.ts

@@ -33,7 +33,7 @@ export function createFastifyHandler(
     | ((
         request: FastifyRequest,
       ) => SessionHandlerOptions | Promise<SessionHandlerOptions>),
-) {
+): (request: FastifyRequest, reply: FastifyReply) => Promise<void> {
   return async (request: FastifyRequest, reply: FastifyReply) => {
     const projectSlug = Array.isArray(request.headers["gram-project"])
       ? request.headers["gram-project"][0]

package/src/server/hono.ts

@@ -31,7 +31,7 @@ export function createHonoHandler(
   options:
     | SessionHandlerOptions
     | ((c: Context) => SessionHandlerOptions | Promise<SessionHandlerOptions>),
-) {
+): (c: Context) => Promise<Response> {
   return async (c: Context) => {
     const projectSlug = c.req.header("gram-project");
 

package/src/server/nextjs.ts

@@ -28,7 +28,7 @@ export function createNextHandler(
     | ((
         request: Request,
       ) => SessionHandlerOptions | Promise<SessionHandlerOptions>),
-) {
+): (request: Request) => Promise<Response> {
   return async (request: Request) => {
     const projectSlug = request.headers.get("gram-project");
 

package/src/server/tanstack-start.ts

@@ -47,7 +47,7 @@ export function createTanStackStartHandler(
     | ((
         request: Request,
       ) => SessionHandlerOptions | Promise<SessionHandlerOptions>),
-) {
+): (request: Request) => Promise<Response> {
   return async (request: Request) => {
     const projectSlug = request.headers.get("gram-project");
 

package/src/storybook.d.ts

@@ -15,6 +15,11 @@ export interface ElementsParameters {
    * Use this to override specific config values per-story.
    */
   config?: Partial<ElementsConfig>;
+  /**
+   * When true, the global ElementsProvider decorator is skipped — useful for
+   * stories that render their own provider (e.g. `<Replay>`).
+   */
+  skipProvider?: boolean;
 }
 
 declare module "storybook/internal/csf" {

package/src/types/index.ts

@@ -1,13 +1,14 @@
+import type { GramChatMessage } from "@/lib/messageConverter";
 import { MODELS } from "@/lib/models";
-import type { FrontendTool } from "@/lib/tools";
 import {
+  AssistantTool,
   ImageMessagePartComponent,
   ReasoningGroupComponent,
   ReasoningMessagePartComponent,
   TextMessagePartComponent,
   ToolCallMessagePartComponent,
 } from "@assistant-ui/react";
-import { LanguageModel } from "ai";
+import { ChatTransport, LanguageModel, UIMessage } from "ai";
 import {
   ComponentType,
   Dispatch,
@@ -49,6 +50,39 @@ export interface MCPServerEntry {
 export const VARIANTS = ["widget", "sidecar", "standalone"] as const;
 export type Variant = (typeof VARIANTS)[number];
 
+/**
+ * Live chat context handed to a {@link ElementsTransportFactory}.
+ */
+export interface ElementsTransportContext {
+  /**
+   * The active conversation's persisted chat id, or null when the current
+   * thread has no server-side chat yet (a brand-new, not-yet-sent thread).
+   * Sourced from the thread-list runtime, so it stays current as the user
+   * switches conversations.
+   */
+  getChatId: () => string | null;
+
+  /**
+   * Adopt a chat id assigned out-of-band (e.g. a server-minted id a consumer
+   * transport receives on the first send). Call at the START of an async send
+   * to capture the active conversation, then invoke the returned function with
+   * the server's id once it's known. The closure binds to the conversation the
+   * send originated from, so a thread switch or a parallel send on another
+   * thread during the round-trip can't mis-associate the id.
+   */
+  adoptChatId: () => (chatId: string) => void;
+}
+
+/**
+ * A factory for a {@link ChatTransport}. When `ElementsConfig.transport` is a
+ * function, Elements invokes it once inside the provider and passes the live
+ * chat context, letting the transport read the current chat id at send time
+ * without reaching into Elements internals.
+ */
+export type ElementsTransportFactory = (
+  ctx: ElementsTransportContext,
+) => ChatTransport<UIMessage>;
+
 /**
  * The top level configuration object for the Elements library.
  *
@@ -65,6 +99,29 @@ export interface ElementsConfig {
    */
   systemPrompt?: string;
 
+  /**
+   * Optional chat transport override. When provided, Elements uses this
+   * transport instead of its built-in client-side streaming transport — e.g.
+   * to route the conversation through a persistent server-side assistant that
+   * generates replies and is polled for them. When omitted, the default
+   * client-side transport is used.
+   *
+   * May be a {@link ChatTransport} directly, or an {@link ElementsTransportFactory}
+   * that Elements invokes inside the provider with the live chat context — use
+   * the factory form when the transport needs the active chat id at send time.
+   */
+  transport?: ChatTransport<UIMessage> | ElementsTransportFactory;
+
+  /**
+   * Whether to expose the inline message-edit affordance on user messages.
+   * Edit relies on assistant-ui's local branch rewriting; transports backed by a
+   * persistent server-side assistant typically can't honour that, so the
+   * sidebar uses this to hide the action rather than offer a broken control.
+   *
+   * @default true
+   */
+  allowMessageEdit?: boolean;
+
   /**
    * Any plugins to use for the Elements library.
    *
@@ -606,8 +663,15 @@ export type ToolsFilter =
   | string[]
   | (({ toolName }: { toolName: string }) => boolean);
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type FrontendTools = Record<string, FrontendTool<any, any>>;
+// FrontendTools holds heterogeneous, user-defined tools. Each entry was made by
+// `defineFrontendTool<TArgs, TResult>` with its own narrow generics, but
+// assistant-ui's `AssistantToolProps<TArgs, TResult>` is invariant in both
+// parameters (input position in `execute`, output position in `streamCall`), so
+// no single `FrontendTool<...>` parameterisation can stand in for an arbitrary
+// one. The SDK addresses this on its own `AssistantTool` shape with
+// `unstable_tool: AssistantToolProps<any, any>`; we mirror that here for the
+// record's value type.
+export type FrontendTools = Record<string, AssistantTool>;
 
 /**
  * ToolsConfig is used to configure tool support in the Elements library.
@@ -786,6 +850,12 @@ export interface ContextCompactionConfig {
 }
 
 export interface WelcomeConfig {
+  /**
+   * Optional logo image URL shown above the title on the empty-thread welcome
+   * screen.
+   */
+  logo?: string;
+
   /**
    * The welcome message to display when the thread is empty.
    */
@@ -1003,6 +1073,42 @@ export interface HistoryConfig {
    */
   enabled: boolean;
 
+  /**
+   * Extra query parameters forwarded to the thread-list request, used to
+   * filter which conversations are shown. Opaque to Elements — the consumer
+   * decides the keys (e.g. a search term, or a backend-specific scope). When
+   * omitted, all of the caller's chats are listed.
+   */
+  threadListFilters?: Record<string, string>;
+
+  /**
+   * Let the backend own chat-id creation. When true, a brand-new thread does not
+   * get a client-generated id; instead the transport assigns the id (e.g. one
+   * the server minted on the first send, reported via the transport context's
+   * `adoptChatId`). Use with a server-backed `transport`.
+   */
+  deferThreadIdMinting?: boolean;
+
+  /**
+   * Optional hook to transform or drop each persisted message before it is
+   * rendered from history. Return a (possibly rewritten) message to render it,
+   * or `null` to omit it entirely. Elements applies this to every message
+   * returned by `chat.load` before conversion.
+   *
+   * Use this to keep product- or backend-specific transcript conventions out of
+   * the library — e.g. stripping a server-injected framing block from a turn's
+   * text, or hiding system events that carry no user-facing content. Elements
+   * itself stays agnostic to any such convention.
+   *
+   * @example
+   * // Strip a server-injected framing block and hide framing-only turns.
+   * transformChatMessage: (msg) => {
+   *   const cleaned = stripFraming(msg);
+   *   return isFramingOnly(cleaned) ? null : cleaned;
+   * }
+   */
+  transformChatMessage?: (message: GramChatMessage) => GramChatMessage | null;
+
   /**
    * Whether to show the thread list sidebar/panel.
    * Only applicable for widget and sidecar variants.
@@ -1044,4 +1150,6 @@ export type ElementsContextType = {
   setIsOpen: (isOpen: boolean) => void;
   plugins: Plugin[];
   mcpTools: Record<string, unknown> | undefined;
+  /** True while the MCP tool list is actively being fetched. */
+  mcpToolsLoading: boolean;
 };