@nextclaw/ui 0.14.0 → 0.14.1-beta.1

package/src/features/chat/features/welcome/components/chat-conversation-welcome.tsx

@@ -0,0 +1,104 @@
+import type { ReactNode } from "react";
+import { usePresenter } from "@/features/chat/components/providers/chat-presenter.provider";
+import {
+  buildSessionTypeOptions,
+  DEFAULT_SESSION_TYPE,
+  normalizeSessionType,
+} from "@/features/chat/features/session-type/utils/chat-session-type.utils";
+import { ChatWelcome } from "@/features/chat/features/welcome/components/chat-welcome";
+import {
+  resolveChatWelcomeAgents,
+  resolveChatWelcomeSelectedSessionType,
+} from "@/features/chat/features/welcome/utils/chat-welcome-selection.utils";
+import { buildChatWelcomeProjectOptions } from "@/features/chat/features/welcome/utils/chat-welcome-project-options.utils";
+import { useChatInputStore } from "@/features/chat/stores/chat-input.store";
+import { useChatQueryStore } from "@/features/chat/stores/ncp-chat-query.store";
+import { useChatSessionListStore } from "@/features/chat/stores/chat-session-list.store";
+import { useChatThreadStore } from "@/features/chat/stores/chat-thread.store";
+import { useAgents } from "@/shared/hooks/use-agents";
+import type { NcpSessionSummaryView } from "@/shared/lib/api";
+import { normalizeSessionProjectRootValue } from "@/shared/lib/session-project";
+
+const EMPTY_NCP_SESSION_SUMMARIES: NcpSessionSummaryView[] = [];
+
+type ChatConversationWelcomeProps = {
+  inputSlot: ReactNode;
+};
+
+export function ChatConversationWelcome({
+  inputSlot,
+}: ChatConversationWelcomeProps) {
+  const presenter = usePresenter();
+  const inputSnapshot = useChatInputStore((state) => state.snapshot);
+  const selectedAgentId = useChatSessionListStore(
+    (state) => state.snapshot.selectedAgentId,
+  );
+  const threadSnapshot = useChatThreadStore((state) => state.snapshot);
+  const config = useChatQueryStore(
+    (state) => state.snapshot.configQuery?.data ?? null,
+  );
+  const sessionSummaries = useChatQueryStore(
+    (state) => state.snapshot.sessionsQuery?.data?.sessions ?? EMPTY_NCP_SESSION_SUMMARIES,
+  );
+  const sessionTypesData = useChatQueryStore(
+    (state) => state.snapshot.sessionTypesQuery?.data ?? null,
+  );
+  const agentsQuery = useAgents();
+  const draftAgentId = threadSnapshot.agentId ?? selectedAgentId;
+  const availableAgents = resolveChatWelcomeAgents({
+    agents: agentsQuery.data?.agents,
+    fallbackAgentId: draftAgentId,
+  });
+  const defaultProjectRoot = normalizeSessionProjectRootValue(
+    config?.agents.defaults.workspace,
+  );
+  const selectedProjectRoot = normalizeSessionProjectRootValue(
+    inputSnapshot.pendingProjectRoot,
+  );
+  const sessionTypeOptions = buildSessionTypeOptions(
+    sessionTypesData?.options ?? [],
+  );
+  const defaultSessionType = normalizeSessionType(
+    sessionTypesData?.defaultType ?? inputSnapshot.defaultSessionType ?? DEFAULT_SESSION_TYPE,
+  );
+  const selectedSessionType = resolveChatWelcomeSelectedSessionType({
+    defaultSessionType,
+    pendingSessionType: inputSnapshot.pendingSessionType,
+    selectedSessionType: inputSnapshot.selectedSessionType,
+    sessionTypeOptions,
+  });
+  const projectOptions = buildChatWelcomeProjectOptions({
+    defaultProjectRoot,
+    sessionSummaries,
+  });
+  const selectDraftAgent = (agentId: string) => {
+    presenter.chatSessionListManager.setSelectedAgentId(agentId);
+    presenter.chatInputManager.setPendingSessionType(
+      resolveChatWelcomeSelectedSessionType({
+        agents: availableAgents,
+        agentId,
+        defaultSessionType,
+        pendingSessionType: null,
+        selectedSessionType: null,
+        sessionTypeOptions,
+      }),
+    );
+  };
+
+  return (
+    <ChatWelcome
+      agents={availableAgents}
+      defaultProjectRoot={defaultProjectRoot}
+      inputSlot={inputSlot}
+      projectOptions={projectOptions}
+      selectedAgentId={draftAgentId}
+      selectedProjectRoot={selectedProjectRoot}
+      selectedSessionType={selectedSessionType}
+      sessionTypeOptions={sessionTypeOptions}
+      onSelectAgent={selectDraftAgent}
+      onSelectPrompt={presenter.chatInputManager.applyPromptSuggestion}
+      onSelectProjectRoot={presenter.chatInputManager.setPendingProjectRoot}
+      onSelectSessionType={presenter.chatInputManager.setPendingSessionType}
+    />
+  );
+}

package/src/features/chat/features/welcome/components/chat-welcome-agent-picker.tsx

@@ -0,0 +1,72 @@
+import { AgentAvatar } from '@/shared/components/common/agent-avatar';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  createSelectAvailableHeightLimit,
+} from '@/shared/components/ui/select';
+import type { AgentProfileView } from '@/shared/lib/api';
+import { t } from '@/shared/lib/i18n';
+
+type ChatWelcomeAgentPickerProps = {
+  agents: AgentProfileView[];
+  selectedAgent: AgentProfileView | null;
+  selectedAgentId: string;
+  onSelectAgent: (agentId: string) => void;
+};
+
+const AGENT_PICKER_MAX_HEIGHT = createSelectAvailableHeightLimit('18rem');
+
+export function ChatWelcomeAgentPicker({
+  agents,
+  selectedAgent,
+  selectedAgentId,
+  onSelectAgent,
+}: ChatWelcomeAgentPickerProps) {
+  return (
+    <Select value={selectedAgentId} onValueChange={onSelectAgent}>
+      <SelectTrigger
+        aria-label={t('chatDraftAgentTitle')}
+        className="h-auto w-auto min-w-0 gap-1 rounded-lg border-0 bg-transparent px-2 py-1.5 text-gray-500 shadow-none hover:bg-gray-100 hover:text-gray-800 focus:ring-0"
+      >
+        <span className="sr-only">{t('chatDraftAgentTitle')}</span>
+        <div className="flex min-w-0 items-center gap-1.5">
+          {selectedAgent ? (
+            <>
+              <AgentAvatar
+                agentId={selectedAgent.id}
+                displayName={selectedAgent.displayName}
+                avatarUrl={selectedAgent.avatarUrl}
+                className="h-5 w-5 shrink-0"
+              />
+              <span className="max-w-28 truncate text-sm font-medium">
+                {selectedAgent.displayName?.trim() || selectedAgent.id}
+              </span>
+            </>
+          ) : null}
+        </div>
+      </SelectTrigger>
+      <SelectContent
+        className="rounded-xl border-gray-200/80 shadow-lg"
+        style={{ maxHeight: AGENT_PICKER_MAX_HEIGHT }}
+      >
+        {agents.map((agent) => (
+          <SelectItem key={agent.id} value={agent.id} className="rounded-lg pr-10">
+            <div className="flex min-w-0 items-center gap-2">
+              <AgentAvatar
+                agentId={agent.id}
+                displayName={agent.displayName}
+                avatarUrl={agent.avatarUrl}
+                className="h-5 w-5 shrink-0"
+              />
+              <span className="truncate text-sm font-medium text-gray-700">
+                {agent.displayName?.trim() || agent.id}
+              </span>
+            </div>
+          </SelectItem>
+        ))}
+      </SelectContent>
+    </Select>
+  );
+}

package/src/features/chat/features/welcome/components/chat-welcome-capability-grid.tsx

@@ -0,0 +1,54 @@
+import { AlarmClock, BrainCircuit, MessageCircle } from 'lucide-react';
+import { t } from '@/shared/lib/i18n';
+
+const WELCOME_CAPABILITIES = [
+  {
+    icon: MessageCircle,
+    titleKey: 'chatWelcomeCapability1Title' as const,
+    descKey: 'chatWelcomeCapability1Desc' as const,
+    promptKey: 'chatWelcomeCapability1Prompt' as const,
+  },
+  {
+    icon: BrainCircuit,
+    titleKey: 'chatWelcomeCapability2Title' as const,
+    descKey: 'chatWelcomeCapability2Desc' as const,
+    promptKey: 'chatWelcomeCapability2Prompt' as const,
+  },
+  {
+    icon: AlarmClock,
+    titleKey: 'chatWelcomeCapability3Title' as const,
+    descKey: 'chatWelcomeCapability3Desc' as const,
+    promptKey: 'chatWelcomeCapability3Prompt' as const,
+  },
+];
+
+export function ChatWelcomeCapabilityGrid({
+  onSelectPrompt,
+}: {
+  onSelectPrompt: (prompt: string) => void;
+}) {
+  return (
+    <div className="mt-8 grid grid-cols-[repeat(auto-fit,minmax(min(100%,9.5rem),1fr))] gap-3">
+      {WELCOME_CAPABILITIES.map((capability) => {
+        const Icon = capability.icon;
+        return (
+          <button
+            key={capability.titleKey}
+            onClick={() => onSelectPrompt(t(capability.promptKey))}
+            className="min-w-0 rounded-2xl border border-gray-200 bg-white p-3 text-left shadow-card transition-shadow hover:shadow-card-hover sm:p-4"
+          >
+            <div className="mb-3 flex h-9 w-9 items-center justify-center rounded-xl bg-primary/8">
+              <Icon className="h-4.5 w-4.5 text-primary" />
+            </div>
+            <div className="mb-1 text-sm font-semibold text-gray-900">
+              {t(capability.titleKey)}
+            </div>
+            <div className="text-[11px] leading-relaxed text-gray-500">
+              {t(capability.descKey)}
+            </div>
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/src/features/chat/features/welcome/components/chat-welcome-project-picker.tsx

@@ -0,0 +1,132 @@
+import { useState } from 'react';
+import { ChevronDown, FolderOpen } from 'lucide-react';
+import type { ChatWelcomeProjectOption } from '@/features/chat/features/welcome/utils/chat-welcome-project-options.utils';
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+  createPopoverAvailableHeightLimit,
+} from '@/shared/components/ui/popover';
+import { t } from '@/shared/lib/i18n';
+import { getSessionProjectName } from '@/shared/lib/session-project';
+
+type ChatWelcomeProjectPickerProps = {
+  defaultProjectRoot?: string | null;
+  isSaving: boolean;
+  projectOptions: readonly ChatWelcomeProjectOption[];
+  projectRoot: string | null;
+  selectable: boolean;
+  onOpenProjectDialog: () => void;
+  onSelectProjectRoot: (projectRoot: string) => Promise<void> | void;
+};
+
+const PROJECT_PICKER_MAX_HEIGHT = createPopoverAvailableHeightLimit('20rem');
+
+export function ChatWelcomeProjectPicker({
+  defaultProjectRoot,
+  isSaving,
+  projectOptions,
+  projectRoot,
+  selectable,
+  onOpenProjectDialog,
+  onSelectProjectRoot,
+}: ChatWelcomeProjectPickerProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const projectLabel =
+    getSessionProjectName(projectRoot) ?? t('chatWelcomeProjectPickerPlaceholder');
+  const isDefaultProject =
+    defaultProjectRoot !== null &&
+    defaultProjectRoot !== undefined &&
+    projectRoot === defaultProjectRoot;
+
+  const selectProjectRoot = async (nextProjectRoot: string) => {
+    setIsOpen(false);
+    await onSelectProjectRoot(nextProjectRoot);
+  };
+
+  return (
+    <Popover open={isOpen} onOpenChange={setIsOpen}>
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          className="inline-flex min-w-0 max-w-full items-center gap-1.5 rounded-lg px-2 py-1.5 text-left font-medium text-gray-500 transition-colors hover:bg-gray-100 hover:text-gray-800 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/25"
+          title={projectRoot ?? undefined}
+          aria-label={t('chatWelcomeProjectPickerLabel')}
+          disabled={!selectable || isSaving}
+        >
+          <FolderOpen className="h-4 w-4 shrink-0" />
+          <span className="truncate">{projectLabel}</span>
+          {isDefaultProject ? (
+            <span className="shrink-0 text-xs font-normal text-gray-400">
+              {t('chatWelcomeProjectDefaultBadge')}
+            </span>
+          ) : null}
+          <ChevronDown className="h-3.5 w-3.5 shrink-0 text-gray-400" />
+        </button>
+      </PopoverTrigger>
+      <PopoverContent
+        align="start"
+        className="flex w-[min(20rem,calc(100vw-1rem))] flex-col overflow-hidden rounded-2xl border border-gray-200/80 bg-white p-0 shadow-[0_24px_60px_-28px_rgba(15,23,42,0.38)]"
+        style={{ maxHeight: PROJECT_PICKER_MAX_HEIGHT }}
+      >
+        <div className="shrink-0 px-3 pb-2 pt-3 text-[10px] font-semibold uppercase tracking-[0.18em] text-gray-400">
+          {t('chatWelcomeProjectRecentTitle')}
+        </div>
+        <div className="min-h-0 flex-1 overflow-y-auto px-1.5 pb-1.5">
+          {projectOptions.length > 0 ? (
+            projectOptions.map((option) => (
+              <button
+                key={option.projectRoot}
+                type="button"
+                className="flex w-full min-w-0 items-start gap-2 rounded-xl px-2 py-2 text-left transition-colors hover:bg-gray-50"
+                title={option.projectRoot}
+                onClick={() => {
+                  void selectProjectRoot(option.projectRoot);
+                }}
+              >
+                <FolderOpen className="mt-0.5 h-4 w-4 shrink-0 text-gray-400" />
+                <span className="min-w-0 flex-1">
+                  <span className="flex min-w-0 items-center gap-1.5">
+                    <span className="truncate text-[13px] font-semibold text-gray-800">
+                      {option.projectName}
+                    </span>
+                    {option.isDefault ? (
+                      <span className="shrink-0 text-[10px] font-medium text-gray-400">
+                        {t('chatWelcomeProjectDefaultBadge')}
+                      </span>
+                    ) : null}
+                  </span>
+                  <span className="block truncate text-[11px] leading-4 text-gray-500">
+                    {option.projectRoot}
+                  </span>
+                </span>
+                {option.sessionCount > 0 ? (
+                  <span className="mt-0.5 shrink-0 rounded-full bg-gray-100 px-1.5 py-0.5 text-[10px] font-medium text-gray-500">
+                    {option.sessionCount}
+                  </span>
+                ) : null}
+              </button>
+            ))
+          ) : (
+            <div className="px-2 py-5 text-center text-xs text-gray-400">
+              {t('chatWelcomeProjectNoRecent')}
+            </div>
+          )}
+        </div>
+        <div className="shrink-0 border-t border-gray-100 p-1.5">
+          <button
+            type="button"
+            className="flex w-full items-center gap-2 rounded-xl px-2.5 py-2 text-left text-[13px] font-semibold text-gray-700 transition-colors hover:bg-gray-50"
+            onClick={() => {
+              setIsOpen(false);
+              onOpenProjectDialog();
+            }}
+          >
+            <FolderOpen className="h-4 w-4 shrink-0 text-gray-400" />
+            <span>{t('chatWelcomeProjectOpenFolder')}</span>
+          </button>
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}

package/src/features/chat/features/welcome/components/chat-welcome-session-type-picker.tsx

@@ -0,0 +1,82 @@
+import { useState } from 'react';
+import { Bot, ChevronDown } from 'lucide-react';
+import { SessionContextIconNode } from '@/features/chat/features/session/components/session-context-icon';
+import { ChatSessionTypeOptionItem } from '@/features/chat/features/session-type/components/chat-session-type-option-item';
+import type { ChatInputSnapshot } from '@/features/chat/stores/chat-input.store';
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+  createPopoverAvailableHeightLimit,
+} from '@/shared/components/ui/popover';
+import { t } from '@/shared/lib/i18n';
+
+type SessionTypeOption = ChatInputSnapshot['sessionTypeOptions'][number];
+
+type ChatWelcomeSessionTypePickerProps = {
+  options: readonly SessionTypeOption[];
+  selectedSessionType: string;
+  onSelectSessionType: (sessionType: string) => void;
+};
+
+const SESSION_TYPE_PICKER_MAX_HEIGHT = createPopoverAvailableHeightLimit('18rem');
+
+export function ChatWelcomeSessionTypePicker({
+  options,
+  selectedSessionType,
+  onSelectSessionType,
+}: ChatWelcomeSessionTypePickerProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const selectedOption =
+    options.find((option) => option.value === selectedSessionType) ?? options[0] ?? null;
+
+  if (!selectedOption) {
+    return null;
+  }
+
+  return (
+    <Popover open={isOpen} onOpenChange={setIsOpen}>
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          className="inline-flex min-w-0 max-w-full items-center gap-1.5 rounded-lg px-2 py-1.5 text-left font-medium text-gray-500 transition-colors hover:bg-gray-100 hover:text-gray-800 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/25"
+          aria-label={t('chatWelcomeSessionTypePickerLabel')}
+        >
+          {selectedOption.icon?.src ? (
+            <SessionContextIconNode
+              icon={{
+                kind: 'runtime-image',
+                src: selectedOption.icon.src,
+                alt: selectedOption.icon.alt ?? null,
+                name: selectedOption.label,
+              }}
+              className="h-4 w-4"
+            />
+          ) : (
+            <Bot className="h-4 w-4 shrink-0" />
+          )}
+          <span className="truncate">{selectedOption.label}</span>
+          <ChevronDown className="h-3.5 w-3.5 shrink-0 text-gray-400" />
+        </button>
+      </PopoverTrigger>
+      <PopoverContent
+        align="start"
+        className="flex w-[min(16rem,calc(100vw-1rem))] flex-col overflow-hidden rounded-2xl border border-gray-200/80 bg-white p-1.5 shadow-[0_24px_60px_-28px_rgba(15,23,42,0.38)]"
+        style={{ maxHeight: SESSION_TYPE_PICKER_MAX_HEIGHT }}
+      >
+        <div className="min-h-0 flex-1 overflow-y-auto">
+          {options.map((option) => (
+            <ChatSessionTypeOptionItem
+              key={option.value}
+              option={option}
+              onSelect={() => {
+                onSelectSessionType(option.value);
+                setIsOpen(false);
+              }}
+            />
+          ))}
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}

package/src/features/chat/features/welcome/components/chat-welcome.tsx

@@ -0,0 +1,121 @@
+import type { ReactNode } from 'react';
+import { useState } from 'react';
+import { Bot } from 'lucide-react';
+import { ChatSessionProjectDialog } from '@/features/chat/features/session/components/session-header/chat-session-project-dialog';
+import { ChatWelcomeAgentPicker } from '@/features/chat/features/welcome/components/chat-welcome-agent-picker';
+import { ChatWelcomeCapabilityGrid } from '@/features/chat/features/welcome/components/chat-welcome-capability-grid';
+import { ChatWelcomeProjectPicker } from '@/features/chat/features/welcome/components/chat-welcome-project-picker';
+import { ChatWelcomeSessionTypePicker } from '@/features/chat/features/welcome/components/chat-welcome-session-type-picker';
+import type { ChatWelcomeProjectOption } from '@/features/chat/features/welcome/utils/chat-welcome-project-options.utils';
+import type { ChatInputSnapshot } from '@/features/chat/stores/chat-input.store';
+import type { AgentProfileView } from '@/shared/lib/api';
+import { t } from '@/shared/lib/i18n';
+
+type SessionTypeOption = ChatInputSnapshot['sessionTypeOptions'][number];
+
+type ChatWelcomeProps = {
+  agents: AgentProfileView[];
+  inputSlot?: ReactNode;
+  defaultProjectRoot?: string | null;
+  projectOptions: readonly ChatWelcomeProjectOption[];
+  selectedAgentId: string;
+  selectedProjectRoot?: string | null;
+  selectedSessionType: string;
+  sessionTypeOptions: readonly SessionTypeOption[];
+  onSelectAgent: (agentId: string) => void;
+  onSelectPrompt: (prompt: string) => void;
+  onSelectProjectRoot?: (projectRoot: string) => Promise<void> | void;
+  onSelectSessionType: (sessionType: string) => void;
+};
+
+export function ChatWelcome({
+  agents,
+  defaultProjectRoot,
+  inputSlot,
+  projectOptions,
+  selectedAgentId,
+  selectedProjectRoot,
+  selectedSessionType,
+  sessionTypeOptions,
+  onSelectAgent,
+  onSelectPrompt,
+  onSelectProjectRoot,
+  onSelectSessionType,
+}: ChatWelcomeProps) {
+  const selectedAgent = agents.find((agent) => agent.id === selectedAgentId) ?? null;
+  const [isProjectDialogOpen, setIsProjectDialogOpen] = useState(false);
+  const [isProjectSaving, setIsProjectSaving] = useState(false);
+  const resolvedProjectRoot = selectedProjectRoot ?? defaultProjectRoot ?? null;
+
+  const saveProjectRoot = async (projectRoot: string) => {
+    if (!onSelectProjectRoot) {
+      return;
+    }
+    setIsProjectSaving(true);
+    try {
+      await onSelectProjectRoot(projectRoot);
+      setIsProjectDialogOpen(false);
+    } finally {
+      setIsProjectSaving(false);
+    }
+  };
+  const selectableProjectRoot = Boolean(onSelectProjectRoot);
+
+  return (
+    <div className="flex min-h-full items-center justify-center px-4 py-8 sm:p-8">
+      <div className="min-w-0 w-full max-w-[min(760px,100%)]">
+        <div className="mx-auto mb-5 flex h-14 w-14 items-center justify-center rounded-2xl bg-primary/10">
+          <Bot className="h-8 w-8 text-primary" />
+        </div>
+
+        <div className="text-center">
+          <h2 className="text-2xl font-semibold text-gray-950 sm:text-3xl">
+            {t('chatWelcomeTitle')}
+          </h2>
+          <p className="mt-3 text-sm font-medium text-gray-500 sm:text-base">
+            {t('chatWelcomeSubtitle')}
+          </p>
+        </div>
+
+        {inputSlot ? <div className="mt-8">{inputSlot}</div> : null}
+
+        <div className="mt-3 flex flex-wrap items-center gap-2 px-1 text-sm text-gray-500">
+          {onSelectProjectRoot ? (
+            <ChatWelcomeProjectPicker
+              defaultProjectRoot={defaultProjectRoot}
+              isSaving={isProjectSaving}
+              projectOptions={projectOptions}
+              projectRoot={resolvedProjectRoot}
+              selectable={selectableProjectRoot}
+              onOpenProjectDialog={() => setIsProjectDialogOpen(true)}
+              onSelectProjectRoot={saveProjectRoot}
+            />
+          ) : null}
+          <ChatWelcomeAgentPicker
+            agents={agents}
+            selectedAgent={selectedAgent}
+            selectedAgentId={selectedAgentId}
+            onSelectAgent={onSelectAgent}
+          />
+          <ChatWelcomeSessionTypePicker
+            options={sessionTypeOptions}
+            selectedSessionType={selectedSessionType}
+            onSelectSessionType={onSelectSessionType}
+          />
+        </div>
+
+        <ChatWelcomeCapabilityGrid onSelectPrompt={onSelectPrompt} />
+      </div>
+
+      {onSelectProjectRoot ? (
+        <ChatSessionProjectDialog
+          open={isProjectDialogOpen}
+          currentProjectRoot={resolvedProjectRoot}
+          isSaving={isProjectSaving}
+          onOpenChange={setIsProjectDialogOpen}
+          onSave={saveProjectRoot}
+        />
+      ) : null}
+    </div>
+  );
+}

package/src/features/chat/features/welcome/utils/__tests__/chat-welcome-project-options.utils.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { buildChatWelcomeProjectOptions } from "@/features/chat/features/welcome/utils/chat-welcome-project-options.utils";
+import type { NcpSessionSummaryView } from "@/shared/lib/api";
+
+function createSummary(
+  overrides: Partial<NcpSessionSummaryView> & { sessionId: string },
+): NcpSessionSummaryView {
+  return {
+    sessionId: overrides.sessionId,
+    agentId: "main",
+    createdAt: overrides.createdAt ?? "2026-06-10T10:00:00.000Z",
+    updatedAt: overrides.updatedAt ?? "2026-06-10T10:00:00.000Z",
+    lastMessageAt: overrides.lastMessageAt,
+    messageCount: 1,
+    metadata: overrides.metadata ?? {},
+    status: "idle",
+  };
+}
+
+describe("buildChatWelcomeProjectOptions", () => {
+  it("builds recent project options from session summaries", () => {
+    const options = buildChatWelcomeProjectOptions({
+      defaultProjectRoot: "/Users/demo/.nextclaw/workspace",
+      sessionSummaries: [
+        createSummary({
+          sessionId: "session-1",
+          lastMessageAt: "2026-06-10T10:00:00.000Z",
+          metadata: { project_root: "/tmp/project-alpha" },
+        }),
+        createSummary({
+          sessionId: "session-2",
+          lastMessageAt: "2026-06-11T10:00:00.000Z",
+          metadata: { project_root: "/tmp/project-alpha" },
+        }),
+      ],
+    });
+
+    expect(options).toEqual([
+      {
+        projectRoot: "/Users/demo/.nextclaw/workspace",
+        projectName: "workspace",
+        sessionCount: 0,
+        isDefault: true,
+      },
+      {
+        projectRoot: "/tmp/project-alpha",
+        projectName: "project-alpha",
+        sessionCount: 2,
+        isDefault: false,
+      },
+    ]);
+  });
+});

package/src/features/chat/features/welcome/utils/__tests__/chat-welcome-selection.utils.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import {
+  resolveChatWelcomeAgents,
+  resolveChatWelcomeSelectedAgent,
+  resolveChatWelcomeSelectedSessionType,
+} from "@/features/chat/features/welcome/utils/chat-welcome-selection.utils";
+
+const agents = [
+  { id: "main", displayName: "Main", runtime: "native" },
+  { id: "engineer", displayName: "Engineer", runtime: "codex" },
+];
+
+describe("chat welcome selection utils", () => {
+  it("falls back to the selected agent when agent loading is empty", () => {
+    expect(
+      resolveChatWelcomeAgents({
+        agents: [],
+        fallbackAgentId: "main",
+      }),
+    ).toEqual([{ id: "main" }]);
+  });
+
+  it("resolves the selected welcome agent", () => {
+    expect(
+      resolveChatWelcomeSelectedAgent({
+        agents,
+        agentId: "engineer",
+      })?.runtime,
+    ).toBe("codex");
+  });
+
+  it("resolves the session type from the selected agent runtime", () => {
+    expect(
+      resolveChatWelcomeSelectedSessionType({
+        agents,
+        agentId: "engineer",
+        defaultSessionType: "native",
+        pendingSessionType: null,
+        selectedSessionType: null,
+        sessionTypeOptions: [
+          { value: "native" },
+          { value: "codex" },
+        ],
+      }),
+    ).toBe("codex");
+  });
+
+  it("prefers an explicit session type over the selected agent runtime", () => {
+    expect(
+      resolveChatWelcomeSelectedSessionType({
+        agents,
+        agentId: "engineer",
+        defaultSessionType: "native",
+        pendingSessionType: "native",
+        selectedSessionType: "native",
+        sessionTypeOptions: [
+          { value: "native" },
+          { value: "codex" },
+        ],
+      }),
+    ).toBe("native");
+  });
+});