@gram-ai/elements 1.33.2 → 1.35.0

package/dist/types/index.d.ts

@@ -1,7 +1,7 @@
+import { GramChatMessage } from '../lib/messageConverter';
 import { MODELS } from '../lib/models';
-import { FrontendTool } from '../lib/tools';
-import { ImageMessagePartComponent, ReasoningGroupComponent, ReasoningMessagePartComponent, TextMessagePartComponent, ToolCallMessagePartComponent } from '@assistant-ui/react';
-import { LanguageModel } from 'ai';
+import { AssistantTool, ImageMessagePartComponent, ReasoningGroupComponent, ReasoningMessagePartComponent, TextMessagePartComponent, ToolCallMessagePartComponent } from '@assistant-ui/react';
+import { ChatTransport, LanguageModel, UIMessage } from 'ai';
 import { ComponentType, Dispatch, PropsWithChildren, SetStateAction, ReactNode } from 'react';
 import { Plugin } from './plugins';
 /**
@@ -34,6 +34,34 @@ export interface MCPServerEntry {
 }
 export declare const VARIANTS: readonly ["widget", "sidecar", "standalone"];
 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.
  *
@@ -49,6 +77,27 @@ export interface ElementsConfig {
      * The system prompt to use for the Elements library.
      */
     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.
      *
@@ -544,7 +593,7 @@ export interface ComponentOverrides {
 export type ToolsFilter = string[] | (({ toolName }: {
     toolName: string;
 }) => boolean);
-export type FrontendTools = Record<string, FrontendTool<any, any>>;
+export type FrontendTools = Record<string, AssistantTool>;
 /**
  * ToolsConfig is used to configure tool support in the Elements library.
  * At the moment, you can override the default React components used by
@@ -710,6 +759,11 @@ export interface ContextCompactionConfig {
     disabled?: boolean;
 }
 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.
      */
@@ -898,6 +952,39 @@ export interface HistoryConfig {
      * @default false
      */
     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.
@@ -937,5 +1024,7 @@ 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;
 };
 export {};

package/package.json

@@ -2,7 +2,7 @@
   "name": "@gram-ai/elements",
   "description": "Gram Elements is a library of UI primitives for building chat-like experiences for MCP Servers.",
   "type": "module",
-  "version": "1.33.2",
+  "version": "1.35.0",
   "main": "dist/index.js",
   "exports": {
     ".": {
@@ -186,8 +186,6 @@
   },
   "devDependencies": {
     "@ai-sdk/google": "^2",
-    "@eslint/compat": "^2.0.0",
-    "@eslint/js": "^9.39.1",
     "@openrouter/sdk": "^0.3.14",
     "@storybook/addon-docs": "^10.0.8",
     "@storybook/react-vite": "^10.0.8",
@@ -198,10 +196,6 @@
     "@types/node": "^24.10.1",
     "@vitejs/plugin-react": "^5.0.3",
     "chromatic": "^13.3.5",
-    "eslint": "^9.39.1",
-    "eslint-plugin-react-refresh": "^0.4.24",
-    "eslint-plugin-storybook": "^10.1.4",
-    "eslint-plugin-unused-imports": "^4.3.0",
     "fastify": "^5.7.4",
     "hono": "^4.11.7",
     "lodash.merge": "^4.6.2",
@@ -216,7 +210,8 @@
     "tw-animate-css": "^1.3.8",
     "typedoc": "^0.28.15",
     "typedoc-plugin-markdown": "^4.9.0",
-    "typescript-eslint": "^8.48.1",
+    "oxlint": "^1.67.0",
+    "oxlint-tsgolint": "^0.23.0",
     "vite": "^7.1.6",
     "vite-plugin-dts": "^4.5.4",
     "vite-plugin-turbosnap": "^1.0.3",
@@ -232,7 +227,11 @@
     "build": "vite build",
     "test": "vitest run",
     "test:watch": "vitest",
-    "lint": "eslint src",
+    "lint": "pnpm lint:format && pnpm lint:no-barrels && pnpm lint:oxlint && pnpm type-check",
+    "lint:oxlint": "oxlint --type-aware",
+    "lint:fix": "oxlint --type-aware --fix",
+    "lint:format": "oxfmt --check .",
+    "lint:no-barrels": "! grep -rEn '^export \\*' src --include='*.ts' --include='*.tsx' || (echo 'Barrel re-exports (export *) are not allowed. Re-export named symbols instead.' && exit 1)",
     "analyze": "pnpm dlx vite-bundle-visualizer",
     "storybook": "pnpm clean:cache && storybook dev -p ${ELEMENTS_STORYBOOK_PORT:-6007} --no-open",
     "build-storybook": "storybook build --stats-json",

package/src/compat-shims.ts

@@ -39,6 +39,7 @@ function createUseSyncExternalStoreShim(R: ReactLike) {
       inst.value = value;
       inst.getSnapshot = getSnapshot;
       if (snapshotChanged(inst)) forceUpdate({ inst });
+      // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [subscribe, value, getSnapshot]);
 
     R.useEffect(() => {
@@ -46,6 +47,7 @@ function createUseSyncExternalStoreShim(R: ReactLike) {
       return subscribe(() => {
         if (snapshotChanged(inst)) forceUpdate({ inst });
       });
+      // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [subscribe]);
 
     return value;
@@ -61,14 +63,26 @@ function createUseIdShim(R: ReactLike) {
   };
 }
 
+export interface ReactShims {
+  useSyncExternalStore: <T>(
+    subscribe: (cb: () => void) => () => void,
+    getSnapshot: () => T,
+  ) => T;
+  useId: () => string;
+  useInsertionEffect: typeof import("react").useLayoutEffect;
+  startTransition: (cb: () => void) => void;
+  useTransition: () => [boolean, (cb: () => void) => void];
+  useDeferredValue: <T>(value: T) => T;
+}
+
 /** Build polyfills for a React instance. Native APIs take precedence via ??. */
-export function createShims(R: ReactLike) {
+export function createShims(R: ReactLike): ReactShims {
   return {
     useSyncExternalStore:
       R.useSyncExternalStore ?? createUseSyncExternalStoreShim(R),
     useId: R.useId ?? createUseIdShim(R),
     useInsertionEffect: R.useInsertionEffect ?? R.useLayoutEffect,
-    startTransition: R.startTransition ?? ((cb: () => void) => cb()),
+    startTransition: R.startTransition ?? ((cb: () => void): void => cb()),
     useTransition:
       R.useTransition ??
       ((): [boolean, (cb: () => void) => void] => [false, (cb) => cb()]),

package/src/components/Chat/index.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import * as React from "react";
 import { useElements } from "@/hooks/useElements";
 import { AssistantModal } from "../assistant-ui/assistant-modal";
 import { AssistantSidecar } from "../assistant-ui/assistant-sidecar";
@@ -11,7 +12,7 @@ interface ChatProps {
   className?: string;
 }
 
-export const Chat = ({ className }: ChatProps) => {
+export const Chat = ({ className }: ChatProps): React.JSX.Element => {
   const { config } = useElements();
 
   switch (config.variant) {
@@ -34,6 +35,8 @@ export const Chat = ({ className }: ChatProps) => {
 
     // If no variant is provided then fallback to the modal
     // Modal has its own internal ErrorBoundary around Thread
+    case "widget":
+    case undefined:
     default:
       return (
         <ShadowRoot>

package/src/components/Chat/stories/FrontendTools.stories.tsx

@@ -29,7 +29,7 @@ const FetchTool = defineFrontendTool<{ url: string }, string>(
         const text = await response.text();
         return text;
       } catch (error) {
-        return `Error fetching ${url}: ${error instanceof Error ? error.message : "Unknown error"}. Note: URL must support CORS for browser requests.`;
+        return `Error fetching ${String(url)}: ${error instanceof Error ? error.message : "Unknown error"}. Note: URL must support CORS for browser requests.`;
       }
     },
   },

package/src/components/Chat/stories/ToolApproval.stories.tsx

@@ -93,8 +93,8 @@ const deleteFile = defineFrontendTool<{ fileId: string }, string>(
       fileId: z.string().describe("The ID of the file to delete"),
     }),
     execute: async ({ fileId }) => {
-      alert(`File ${fileId} deleted`);
-      return `File ${fileId} deleted`;
+      alert(`File ${String(fileId)} deleted`);
+      return `File ${String(fileId)} deleted`;
     },
   },
   "deleteFile",

package/src/components/Chat/stories/Tools.stories.tsx

@@ -139,7 +139,9 @@ const ProductCardComponent = ({ result }: ToolCallMessagePartProps) => {
               ${product.price?.toFixed(2)}
             </span>
             <button
-              onClick={handleAddToCart}
+              onClick={() => {
+                void handleAddToCart();
+              }}
               disabled={
                 isLoading || addedToCart || !canAddToCart || !product.inStock
               }
@@ -242,8 +244,10 @@ const ApproveRequestTool = defineFrontendTool<{ id: number }, string>(
     }),
     execute: async ({ id }) => {
       // Simulate API call
-      await new Promise((resolve) => setTimeout(resolve, 500));
-      return `Request #${id} has been approved successfully.`;
+      await new Promise((resolve) => {
+        setTimeout(resolve, 500);
+      });
+      return `Request #${String(id)} has been approved successfully.`;
     },
   },
   "approve_request",
@@ -260,8 +264,12 @@ const RejectRequestTool = defineFrontendTool<
       reason: z.string().optional().describe("Reason for rejection"),
     }),
     execute: async ({ id, reason }) => {
-      await new Promise((resolve) => setTimeout(resolve, 500));
-      return `Request #${id} has been rejected.${reason ? ` Reason: ${reason}` : ""}`;
+      await new Promise((resolve) => {
+        setTimeout(resolve, 500);
+      });
+      return `Request #${String(id)} has been rejected.${
+        reason ? ` Reason: ${JSON.stringify(reason)}` : ""
+      }`;
     },
   },
   "reject_request",

package/src/components/ChatHistory.tsx

@@ -7,7 +7,9 @@ interface ChatHistoryProps {
   className?: string;
 }
 
-export const ChatHistory = ({ className }: ChatHistoryProps) => {
+export const ChatHistory = ({
+  className,
+}: ChatHistoryProps): React.JSX.Element => {
   return (
     <ShadowRoot hostStyle={{ height: "inherit", width: "inherit" }}>
       <ThreadList className={className} />

package/src/components/FrontendTools/index.tsx

@@ -5,7 +5,7 @@ export function FrontendTools({
   tools: frontendTools,
 }: {
   tools: FrontendTools;
-}) {
+}): React.JSX.Element {
   return (
     <>
       {Object.entries(frontendTools).map(([, tool]) =>

package/src/components/MessageContent.tsx

@@ -26,6 +26,7 @@ const STUB_CONTEXT: ElementsContextType = {
   setIsOpen: () => {},
   plugins: recommended,
   mcpTools: undefined,
+  mcpToolsLoading: false,
 };
 
 export interface MessageContentProps {

package/src/components/Replay.stories.tsx

@@ -1,10 +1,9 @@
-import type { StoryFn } from "@storybook/react-vite";
+import type { Meta, StoryFn } from "@storybook/react-vite";
 import { Chat } from "@/components/Chat";
 import { Replay } from "@/components/Replay";
 import type { Cassette } from "@/lib/cassette";
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const meta: any = {
+const meta: Meta<typeof Replay> = {
   title: "Misc/Replay",
   component: Replay,
   parameters: {

package/src/components/Replay.tsx

@@ -63,17 +63,20 @@ export const Replay = ({
   userMessageDelay,
   assistantStartDelay,
   onComplete,
-}: ReplayProps) => {
-  const replayOptions: ReplayOptions = {
-    typingSpeed,
-    userMessageDelay,
-    assistantStartDelay,
-    onComplete,
-  };
+}: ReplayProps): React.JSX.Element => {
+  const replayOptions = useMemo<ReplayOptions>(
+    () => ({
+      typingSpeed,
+      userMessageDelay,
+      assistantStartDelay,
+      onComplete,
+    }),
+    [typingSpeed, userMessageDelay, assistantStartDelay, onComplete],
+  );
 
   const transport = useMemo(
     () => createReplayTransport(cassette, replayOptions),
-    [cassette, typingSpeed, userMessageDelay, assistantStartDelay, onComplete],
+    [cassette, replayOptions],
   );
 
   const runtime = useChatRuntime({ transport });
@@ -108,6 +111,7 @@ export const Replay = ({
       setIsOpen: () => {},
       plugins,
       mcpTools: undefined,
+      mcpToolsLoading: false,
     }),
     [config, plugins],
   );
@@ -148,7 +152,9 @@ export const Replay = ({
 // ---------------------------------------------------------------------------
 
 function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
 }
 
 /**
@@ -238,11 +244,12 @@ const ReplayController = ({ cassette, options }: ReplayControllerProps) => {
       options.onComplete?.();
     };
 
-    runReplay();
+    void runReplay();
 
     return () => {
       cancelled = true;
     };
+    // oxlint-disable-next-line react-hooks/exhaustive-deps -- run-once driver, see hasStarted ref
   }, []);
 
   return null;

package/src/components/ShadowRoot.tsx

@@ -26,7 +26,7 @@ export const ShadowRoot = ({
   children,
   hostClassName,
   hostStyle,
-}: ShadowRootProps) => {
+}: ShadowRootProps): React.JSX.Element => {
   const hostRef = useRef<HTMLDivElement>(null);
   const containerRef = useRef<HTMLDivElement>(null);
   const [shadowRoot, setShadowRoot] = useState<ShadowRoot | null>(null);
@@ -66,7 +66,7 @@ export const ShadowRoot = ({
     styleElement.setAttribute("data-gram-elements", "true");
     styleElement.textContent = elementsStyles;
     shadowRoot.prepend(styleElement);
-  }, [shadowRoot, elementsStyles]);
+  }, [shadowRoot]);
 
   return (
     <div

package/src/components/ShareButton/index.tsx

@@ -80,7 +80,7 @@ export function ShareButton({
   size = "sm",
   className,
   children,
-}: ShareButtonProps) {
+}: ShareButtonProps): React.JSX.Element {
   const { threadId } = useThreadId();
 
   const handleShare = useCallback(async () => {
@@ -118,7 +118,9 @@ export function ShareButton({
         <Button
           variant={variant}
           size={size}
-          onClick={handleShare}
+          onClick={() => {
+            void handleShare();
+          }}
           disabled={!threadId}
           className={cn("aui-share-button", className)}
           aria-label="Share chat"

package/src/components/assistant-ui/assistant-modal.tsx

@@ -36,9 +36,9 @@ const LAYOUT_TRANSITION = {
 } as const;
 
 type Dimensions = {
-  width?: string | number | `${number}%`;
-  height?: string | number | `${number}%`;
-  maxHeight?: string | number | `${number}%`;
+  width?: string | number;
+  height?: string | number;
+  maxHeight?: string | number;
 };
 
 interface AssistantModalProps {
@@ -277,6 +277,8 @@ function positionClassname(
       return "left-4 top-4";
     case "bottom-right":
       return "right-4 bottom-4";
+    case undefined:
+      return "right-4 bottom-4";
     default:
       assertNever(position);
   }

package/src/components/assistant-ui/attachment.tsx

@@ -140,7 +140,7 @@ const AttachmentUI: FC = () => {
         return "File";
       default: {
         const _exhaustiveCheck: never = type;
-        throw new Error(`Unknown attachment type: ${_exhaustiveCheck}`);
+        throw new Error(`Unknown attachment type: ${String(_exhaustiveCheck)}`);
       }
     }
   });

package/src/components/assistant-ui/error-boundary.tsx

@@ -90,7 +90,7 @@ export class ErrorBoundary extends Component<
     this.props.onError?.(error, errorInfo);
   }
 
-  handleRetry = () => {
+  handleRetry = (): void => {
     // Increment resetKey to force remount of children, reinitializing the chat
     this.setState((state) => ({
       hasError: false,

package/src/components/assistant-ui/markdown-text.tsx

@@ -66,7 +66,7 @@ const useCopyToClipboard = ({
   const copyToClipboard = (value: string) => {
     if (!value) return;
 
-    navigator.clipboard.writeText(value).then(() => {
+    void navigator.clipboard.writeText(value).then(() => {
       setIsCopied(true);
       setTimeout(() => setIsCopied(false), copiedDuration);
     });