Design update for shell and conversion starter

js/packages/react-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crayonai/react-core",
-  "version": "0.7.6",
+  "version": "0.7.7",
   "description": "Generative UI SDK",
   "license": "MIT",
   "main": "dist/index.js",

js/packages/react-core/src/hooks/useThreadState.ts

@@ -19,5 +19,6 @@ export const useThreadState = (): ThreadState => {
     messages: useStore(threadManager, (store) => store.messages),
     error: useStore(threadManager, (store) => store.error),
     responseTemplates: useStore(threadManager, (store) => store.responseTemplates),
+    isInitialized: useStore(threadManager, (store) => store.isInitialized),
   };
 };

js/packages/react-core/src/internal/useThreadManagerStore.ts

@@ -10,6 +10,7 @@ export const useThreadManagerStore = (inputThreadManager: ThreadManager) => {
 
   const [threadManagerStore] = useState(() =>
     create<ThreadManager>(() => ({
+      isInitialized: inputThreadManager.isInitialized,
       isLoadingMessages: inputThreadManager.isLoadingMessages,
       isRunning: inputThreadManager.isRunning,
       messages: inputThreadManager.messages,
@@ -31,12 +32,14 @@ export const useThreadManagerStore = (inputThreadManager: ThreadManager) => {
       messages: inputThreadManager.messages,
       error: inputThreadManager.error,
       isLoadingMessages: inputThreadManager.isLoadingMessages,
+      isInitialized: inputThreadManager.isInitialized,
     });
   }, [
     inputThreadManager.isRunning,
     inputThreadManager.messages,
     inputThreadManager.error,
     inputThreadManager.isLoadingMessages,
+    inputThreadManager.isInitialized,
   ]);
 
   if (inputThreadManagerRef.current.responseTemplates !== inputThreadManager.responseTemplates) {

js/packages/react-core/src/types/chatManager.ts

@@ -57,6 +57,8 @@ export type ThreadState = {
    * `responseTemplates` property provided to the hook.
    */
   responseTemplates: Record<string, ResponseTemplate>;
+  /** Indicates if the thread manager is initialized and the thread can show threadList or welcome screen */
+  isInitialized: boolean;
 };
 
 /**

js/packages/react-core/src/useThreadManager.ts

@@ -43,7 +43,7 @@ export const useThreadManager = (params: UseThreadManagerParams): ThreadManager
   propsRef.current = params;
 
   const store = useMemo(() => {
-    return createStore<
+    const store = createStore<
       ThreadManager & {
         abortController: AbortController | null;
       }
@@ -54,6 +54,7 @@ export const useThreadManager = (params: UseThreadManagerParams): ThreadManager
         abortController: null,
         isRunning: false,
         isLoadingMessages: false,
+        isInitialized: false,
         setMessages: (messages: Message[]) => {
           set({ messages });
         },
@@ -117,6 +118,21 @@ export const useThreadManager = (params: UseThreadManagerParams): ThreadManager
         ),
       };
     });
+
+    /**
+     * Delay initialization to ensure proper thread manager setup.
+     *
+     * Why this delay is necessary:
+     * - Multiple React effects must run to determine the initial `selectedThreadId`
+     * - Without a definitive thread ID state (null vs. valid ID), the UI cannot
+     *   determine whether to render the thread list or welcome screen
+     * - This 200ms buffer allows all effects to complete, providing a stable state
+     *   before marking initialization as complete
+     */
+    setTimeout(() => {
+      store.setState({ isInitialized: true });
+    }, 200);
+    return store;
   }, [propsRef]);
 
   useEffect(() => {

js/packages/react-ui/package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "name": "@crayonai/react-ui",
   "license": "MIT",
-  "version": "0.9.11",
+  "version": "0.9.12",
   "description": "Component library for Generative UI SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

js/packages/react-ui/src/components/BottomTray/ConversationStarter.tsx

@@ -0,0 +1,145 @@
+import { useThreadActions, useThreadState } from "@crayonai/react-core";
+import clsx from "clsx";
+import { ArrowUp, Lightbulb } from "lucide-react";
+import { Fragment, ReactNode } from "react";
+import { ConversationStarterIcon, ConversationStarterProps } from "../../types/ConversationStarter";
+import { Separator } from "../Separator";
+
+export type ConversationStarterVariant = "short" | "long";
+
+interface ConversationStarterItemProps extends ConversationStarterProps {
+  onClick: (prompt: string) => void;
+  variant: ConversationStarterVariant;
+}
+
+/**
+ * Renders the appropriate icon based on the icon prop value
+ * - undefined: Show default lightbulb icon
+ * - ReactNode: Show the provided icon (use <></> or React.Fragment for no icon)
+ */
+const renderIcon = (icon: ConversationStarterIcon | undefined): ReactNode => {
+  if (icon === undefined) {
+    return <Lightbulb size={16} />;
+  }
+  return icon;
+};
+
+const ConversationStarterItem = ({
+  displayText,
+  prompt,
+  onClick,
+  variant,
+  icon,
+}: ConversationStarterItemProps) => {
+  const renderedIcon = renderIcon(icon);
+
+  if (variant === "short") {
+    return (
+      <button
+        type="button"
+        className="crayon-bottom-tray-conversation-starter-item-short"
+        onClick={() => onClick(prompt)}
+      >
+        {renderedIcon && (
+          <span className="crayon-bottom-tray-conversation-starter-item-short__icon">
+            {renderedIcon}
+          </span>
+        )}
+        <span className="crayon-bottom-tray-conversation-starter-item-short__text">
+          {displayText}
+        </span>
+      </button>
+    );
+  }
+
+  // Long variant (detailed list style)
+  return (
+    <button
+      type="button"
+      className="crayon-bottom-tray-conversation-starter-item-long"
+      onClick={() => onClick(prompt)}
+    >
+      <div className="crayon-bottom-tray-conversation-starter-item-long__content">
+        {renderedIcon && (
+          <span className="crayon-bottom-tray-conversation-starter-item-long__icon">
+            {renderedIcon}
+          </span>
+        )}
+        <span className="crayon-bottom-tray-conversation-starter-item-long__text">
+          {displayText}
+        </span>
+      </div>
+      <span className="crayon-bottom-tray-conversation-starter-item-long__arrow">
+        <ArrowUp size={16} />
+      </span>
+    </button>
+  );
+};
+
+export interface ConversationStarterContainerProps {
+  starters: ConversationStarterProps[];
+  className?: string;
+  /**
+   * Variant of the conversation starter
+   * - "short": Pill-style horizontal buttons (default)
+   * - "long": List items with icons and hover arrow
+   */
+  variant?: ConversationStarterVariant;
+}
+
+export const ConversationStarter = ({
+  starters,
+  className,
+  variant = "short",
+}: ConversationStarterContainerProps) => {
+  const { processMessage } = useThreadActions();
+  const { isRunning, messages } = useThreadState();
+
+  const handleClick = (prompt: string) => {
+    if (isRunning) return;
+    processMessage({
+      type: "prompt",
+      role: "user",
+      message: prompt,
+    });
+  };
+
+  // Only show when there are no messages
+  if (messages.length > 0) {
+    return null;
+  }
+
+  if (starters.length === 0) {
+    return null;
+  }
+
+  return (
+    <div
+      className={clsx(
+        "crayon-bottom-tray-conversation-starter",
+        `crayon-bottom-tray-conversation-starter--${variant}`,
+        className,
+      )}
+    >
+      {starters.map((item, index) => (
+        <Fragment key={`${item.displayText}-${index}`}>
+          <ConversationStarterItem
+            displayText={item.displayText}
+            prompt={item.prompt}
+            icon={item.icon}
+            onClick={handleClick}
+            variant={variant}
+          />
+          {/* Add separator between items in long variant */}
+          {variant === "long" && index < starters.length - 1 && (
+            <div className="crayon-bottom-tray-conversation-starter__separator">
+              <Separator />
+            </div>
+          )}
+        </Fragment>
+      ))}
+    </div>
+  );
+};
+
+export default ConversationStarter;

js/packages/react-ui/src/components/BottomTray/Thread.tsx

@@ -6,7 +6,7 @@ import {
   useThreadState,
 } from "@crayonai/react-core";
 import clsx from "clsx";
-import { ArrowRight, Square } from "lucide-react";
+import { ArrowUp, Square } from "lucide-react";
 import React, { memo, useEffect, useLayoutEffect, useRef } from "react";
 import { useComposerState } from "../../hooks/useComposerState";
 import { ScrollVariant, useScrollToBottom } from "../../hooks/useScrollToBottom";
@@ -35,7 +35,20 @@ export const ThreadContainer = ({
     setArtifactRenderer(renderArtifact);
   }, [isArtifactActive, renderArtifact, setIsArtifactActive, setArtifactRenderer]);
 
-  return <div className={clsx("crayon-bottom-tray-thread-container", className)}>{children}</div>;
+  const { isInitialized } = useThreadManagerSelector((store) => ({
+    isInitialized: store.isInitialized,
+  }));
+
+  return (
+    <div
+      className={clsx("crayon-bottom-tray-thread-container", className)}
+      style={{
+        visibility: isInitialized ? undefined : "hidden",
+      }}
+    >
+      {children}
+    </div>
+  );
 };
 
 export const ScrollArea = ({
@@ -265,7 +278,7 @@ export const Composer = ({ className }: { className?: string }) => {
         />
         <IconButton
           onClick={isRunning ? onCancel : handleSubmit}
-          icon={isRunning ? <Square size="1em" fill="currentColor" /> : <ArrowRight size="1em" />}
+          icon={isRunning ? <Square size="1em" fill="currentColor" /> : <ArrowUp size="1em" />}
         />
       </div>
     </div>

js/packages/react-ui/src/components/BottomTray/WelcomeScreen.tsx

@@ -0,0 +1,106 @@
+import { useThreadState } from "@crayonai/react-core";
+import clsx from "clsx";
+import { ReactNode } from "react";
+
+interface WelcomeScreenBaseProps {
+  /**
+   * Additional CSS class name
+   */
+  className?: string;
+}
+
+interface WelcomeScreenWithContentProps extends WelcomeScreenBaseProps {
+  /**
+   * The greeting/title text to display
+   */
+  title?: string;
+  /**
+   * Optional description text to add more context
+   */
+  description?: string;
+  /**
+   * Image to display - can be a URL object or a ReactNode
+   * - { url: string }: Renders an <img> tag with default styling (64x64, object-fit: cover, rounded)
+   * - ReactNode: Renders the provided element directly (for custom icons, styled images, etc.)
+   */
+  image?: { url: string } | ReactNode;
+  /**
+   * Children are not allowed when using props-based content
+   */
+  children?: never;
+}
+
+interface WelcomeScreenWithChildrenProps extends WelcomeScreenBaseProps {
+  /**
+   * Custom content to render inside the welcome screen
+   * When children are provided, title, description, and image are ignored
+   */
+  children: ReactNode;
+  title?: never;
+  description?: never;
+  image?: never;
+}
+
+export type WelcomeScreenProps = WelcomeScreenWithContentProps | WelcomeScreenWithChildrenProps;
+
+/**
+ * Type guard to check if image is a URL object
+ */
+const isImageUrl = (image: { url: string } | ReactNode): image is { url: string } => {
+  return typeof image === "object" && image !== null && "url" in image;
+};
+
+export const WelcomeScreen = (props: WelcomeScreenProps) => {
+  const { className } = props;
+
+  const { messages } = useThreadState();
+
+  // Only show when there are no messages
+  if (messages.length > 0) {
+    return null;
+  }
+
+  // Check if children are provided
+  if ("children" in props && props.children) {
+    return (
+      <div className={clsx("crayon-bottom-tray-welcome-screen", className)}>{props.children}</div>
+    );
+  }
+
+  // Props-based content
+  const { title, description, image } = props as WelcomeScreenWithContentProps;
+
+  const renderImage = () => {
+    if (!image) return null;
+
+    if (isImageUrl(image)) {
+      return (
+        <img
+          src={image.url}
+          alt={title || ""}
+          className="crayon-bottom-tray-welcome-screen__image"
+        />
+      );
+    }
+
+    return image;
+  };
+
+  return (
+    <div className={clsx("crayon-bottom-tray-welcome-screen", className)}>
+      {image && (
+        <div className="crayon-bottom-tray-welcome-screen__image-container">{renderImage()}</div>
+      )}
+      {(title || description) && (
+        <div className="crayon-bottom-tray-welcome-screen__content">
+          {title && <h2 className="crayon-bottom-tray-welcome-screen__title">{title}</h2>}
+          {description && (
+            <p className="crayon-bottom-tray-welcome-screen__description">{description}</p>
+          )}
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default WelcomeScreen;

js/packages/react-ui/src/components/BottomTray/bottomTray.scss

@@ -6,3 +6,5 @@
 @use "./header.scss";
 @use "./threadList.scss";
 @use "./thread.scss";
+@use "./conversationStarter.scss";
+@use "./welcomeScreen.scss";