@nextclaw/ui 0.15.5 → 0.15.6

package/src/features/chat/features/conversation/hooks/use-session-conversation-input-state.ts

@@ -5,6 +5,10 @@ import type { NcpDraftAttachment } from '@nextclaw/ncp-react';
 import type { ThinkingLevel } from '@/shared/lib/api';
 import { DEFAULT_SESSION_TYPE } from '@/features/chat/features/session-type/utils/chat-session-type.utils';
 import { createChatComposerNodesFromDraft } from '@/features/chat/features/input/utils/chat-composer-state.utils';
+import {
+  useSessionConversationPreferenceActions,
+  type SessionConversationPreferenceSyncParams,
+} from '@/features/chat/features/conversation/hooks/use-session-conversation-preference-actions';
 
 type SessionConversationInputStateValue = string | null | undefined;
 type SessionConversationSkillSelection = {
@@ -51,6 +55,7 @@ export type SessionConversationInputActions = {
   readonly removeAttachment: (attachmentId: string) => void;
   readonly setSelectedModel: (model: SessionConversationInputStateValue) => void;
   readonly setSelectedThinkingLevel: (level: ThinkingLevel | null) => void;
+  readonly syncSessionPreferences: (params: SessionConversationPreferenceSyncParams) => void;
   readonly setPendingSessionType: (sessionType: SetStateAction<string>) => void;
   readonly setPendingProjectRoot: (projectRoot: string | null) => void;
   readonly setSelectedSkills: (
@@ -198,13 +203,11 @@ export const useSessionConversationInputState = () => {
     }));
   }, [update]);
 
-  const setSelectedModel = useCallback((model: SessionConversationInputStateValue) => {
-    update({ selectedModel: model });
-  }, [update]);
-
-  const setSelectedThinkingLevel = useCallback((level: ThinkingLevel | null) => {
-    update({ selectedThinkingLevel: level });
-  }, [update]);
+  const preferenceActions = useSessionConversationPreferenceActions({
+    selectedModel: snapshot.selectedModel,
+    selectedThinkingLevel: snapshot.selectedThinkingLevel,
+    updatePreferences: update,
+  });
 
   const setPendingSessionType = useCallback((sessionType: SetStateAction<string>) => {
     update((current) => {
@@ -249,8 +252,7 @@ export const useSessionConversationInputState = () => {
     setAttachments,
     addAttachments,
     removeAttachment,
-    setSelectedModel,
-    setSelectedThinkingLevel,
+    ...preferenceActions,
     setPendingSessionType,
     setPendingProjectRoot,
     setSelectedSkills,
@@ -266,8 +268,7 @@ export const useSessionConversationInputState = () => {
     setAttachments,
     addAttachments,
     removeAttachment,
-    setSelectedModel,
-    setSelectedThinkingLevel,
+    preferenceActions,
     setPendingSessionType,
     setPendingProjectRoot,
     setSelectedSkills,

package/src/features/chat/features/conversation/hooks/use-session-conversation-preference-actions.ts

@@ -0,0 +1,94 @@
+import { useCallback, useMemo, useRef } from 'react';
+
+import type { ThinkingLevel } from '@/shared/lib/api';
+import type { ChatModelOption } from '@/features/chat/types/chat-input.types';
+import {
+  resolveSelectedModelValue,
+  resolveSelectedThinkingLevelValue,
+} from '@/features/chat/features/session/utils/chat-session-preference-governance.utils';
+
+type ConversationPreferenceValue = string | null | undefined;
+
+export type SessionConversationPreferenceSyncParams = {
+  readonly defaultModel?: string;
+  readonly fallbackPreferredModel?: string;
+  readonly fallbackPreferredThinking?: ThinkingLevel | null;
+  readonly modelOptions: ChatModelOption[];
+  readonly selectedSessionExists: boolean;
+  readonly selectedSessionKey?: string | null;
+  readonly selectedSessionPreferredModel?: string;
+  readonly selectedSessionPreferredThinking?: ThinkingLevel | null;
+};
+
+type SessionConversationPreferenceActionsParams = {
+  readonly selectedModel: ConversationPreferenceValue;
+  readonly selectedThinkingLevel: ThinkingLevel | null;
+  readonly updatePreferences: (patch: {
+    readonly selectedModel?: ConversationPreferenceValue;
+    readonly selectedThinkingLevel?: ThinkingLevel | null;
+  }) => void;
+};
+
+export const useSessionConversationPreferenceActions = ({
+  selectedModel: currentSelectedModel,
+  selectedThinkingLevel: currentSelectedThinkingLevel,
+  updatePreferences,
+}: SessionConversationPreferenceActionsParams) => {
+  const previousSessionKeyRef = useRef<string | null | undefined>(undefined);
+  const setSelectedModel = useCallback((selectedModel: ConversationPreferenceValue) => {
+    updatePreferences({ selectedModel });
+  }, [updatePreferences]);
+  const setSelectedThinkingLevel = useCallback((selectedThinkingLevel: ThinkingLevel | null) => {
+    updatePreferences({ selectedThinkingLevel });
+  }, [updatePreferences]);
+  const syncSessionPreferences = useCallback(({
+    defaultModel,
+    fallbackPreferredModel,
+    fallbackPreferredThinking,
+    modelOptions,
+    selectedSessionExists,
+    selectedSessionKey: sessionKey,
+    selectedSessionPreferredModel,
+    selectedSessionPreferredThinking,
+  }: SessionConversationPreferenceSyncParams) => {
+    const selectedSessionKey = sessionKey ?? null;
+    const sessionChanged = previousSessionKeyRef.current !== selectedSessionKey;
+    const preserveCurrentPreference = sessionChanged && Boolean(selectedSessionKey) && !selectedSessionExists;
+    const selectedModel = resolveSelectedModelValue({
+      currentSelectedModel: currentSelectedModel ?? undefined,
+      modelOptions,
+      selectedSessionPreferredModel,
+      fallbackPreferredModel,
+      defaultModel,
+      preferSessionPreferredModel: sessionChanged,
+      preserveCurrentSelectedModelOnSessionChange: preserveCurrentPreference,
+    });
+    const modelOption = modelOptions.find((option) => option.value === selectedModel);
+    const selectedThinkingLevel = resolveSelectedThinkingLevelValue({
+      currentSelectedThinkingLevel,
+      supportedThinkingLevels:
+        (modelOption?.thinkingCapability?.supported as ThinkingLevel[] | undefined) ?? [],
+      selectedSessionPreferredThinking,
+      fallbackPreferredThinking,
+      defaultThinkingLevel:
+        (modelOption?.thinkingCapability?.default as ThinkingLevel | null | undefined) ?? null,
+      preferSessionPreferredThinking: sessionChanged,
+      preserveCurrentSelectedThinkingOnSessionChange: preserveCurrentPreference,
+    });
+    if (
+      currentSelectedModel !== selectedModel ||
+      currentSelectedThinkingLevel !== selectedThinkingLevel
+    ) {
+      updatePreferences({ selectedModel, selectedThinkingLevel });
+    }
+    if (!selectedSessionKey || selectedSessionExists) {
+      previousSessionKeyRef.current = selectedSessionKey;
+    }
+  }, [currentSelectedModel, currentSelectedThinkingLevel, updatePreferences]);
+
+  return useMemo(() => ({
+    setSelectedModel,
+    setSelectedThinkingLevel,
+    syncSessionPreferences,
+  }), [setSelectedModel, setSelectedThinkingLevel, syncSessionPreferences]);
+};

package/src/features/chat/features/input/hooks/__tests__/use-chat-input-surface-state.test.tsx

@@ -9,10 +9,21 @@ const usePanelAppsMock = vi.hoisted(() =>
     isLoading: false,
   })),
 );
+const useServerPathSearchMock = vi.hoisted(() =>
+  vi.fn(() => ({
+    data: { entries: [] },
+    error: null,
+    isFetching: false,
+    isLoading: false,
+  })),
+);
 
 vi.mock('@/features/panel-apps', () => ({
   usePanelApps: usePanelAppsMock,
 }));
+vi.mock('@/shared/hooks/use-server-path-search', () => ({
+  useServerPathSearch: useServerPathSearchMock,
+}));
 
 function createHookParams() {
   return {
@@ -29,6 +40,7 @@ function createHookParams() {
     language: 'zh' as const,
     onSelectPanelApp: vi.fn(),
     onSelectSkill: vi.fn(),
+    projectRoot: '/tmp/project',
     recentSkillValues: [],
     skillRecords: [],
   };
@@ -36,6 +48,31 @@ function createHookParams() {
 
 beforeEach(() => {
   usePanelAppsMock.mockClear();
+  useServerPathSearchMock.mockClear();
+});
+
+it('enables project path search after navigating into files and folders', () => {
+  const { result } = renderHook(() => useChatInputSurfaceState(createHookParams()));
+
+  act(() =>
+    result.current.setInputSurfaceTrigger({
+      end: 1,
+      key: 'context-reference',
+      marker: '@',
+      query: '',
+      start: 0,
+    }),
+  );
+  const filesItem = result.current.inputSurfaceState.panel?.items.find(
+    (item) => item.selectionBehavior === 'navigate',
+  );
+  act(() => result.current.inputSurfaceState.panel?.onSelectItem?.(filesItem!));
+
+  expect(useServerPathSearchMock).toHaveBeenLastCalledWith({
+    basePath: '/tmp/project',
+    query: '',
+    enabled: true,
+  });
 });
 
 it('keeps equivalent input surface trigger updates from rerendering the composer owner', () => {

package/src/features/chat/features/input/hooks/use-chat-input-surface-state.ts

@@ -1,4 +1,4 @@
-import { useCallback, useMemo, useRef, useState } from 'react';
+import { useCallback, useDeferredValue, useMemo, useRef, useState } from 'react';
 import {
   CHAT_INPUT_SURFACE_SLASH_TRIGGER_SPEC,
   resolveChatInputSurfaceState,
@@ -7,105 +7,169 @@ import {
 import { usePanelApps } from '@/features/panel-apps';
 import { t, type I18nLanguage } from '@/shared/lib/i18n';
 import {
-  createPanelAppReferenceInputSurfacePlugin,
-  PANEL_APP_REFERENCE_TRIGGER_SPEC,
-} from '@/features/chat/features/input/input-surface-plugins/panel-app-reference-plugin.utils';
+  CONTEXT_REFERENCE_TRIGGER_SPEC,
+  createContextReferenceInputSurfacePlugin,
+} from '@/features/chat/features/input/input-surface-plugins/context-reference-plugin.utils';
+import type { ContextReferenceMode } from '@/features/chat/features/input/input-surface-plugins/chat-input-product-plugin-adapters.types';
 import {
   createSlashCommandInputSurfacePlugin,
   type ChatSlashCommandDescriptor,
 } from '@/features/chat/features/input/input-surface-plugins/slash-command-plugin.utils';
 import type { ChatInputBarAdapterTexts, ChatSkillRecord } from '@/features/chat/types/chat-input-bar.types';
+import { useServerPathSearch } from '@/shared/hooks/use-server-path-search';
 
-export function useChatInputSurfaceState(params: {
+type ChatInputSurfaceSlashTexts = Pick<
+  ChatInputBarAdapterTexts,
+  'slashSkillSubtitle' | 'slashSkillSpecLabel' | 'slashSkillScopeLabel' | 'noSkillDescription'
+>;
+
+type UseChatInputSurfaceStateParams = {
   commands: readonly ChatSlashCommandDescriptor[];
   isSkillsLoading: boolean;
-  itemTexts: {
-    slashTexts: Pick<
-      ChatInputBarAdapterTexts,
-      'slashSkillSubtitle' | 'slashSkillSpecLabel' | 'slashSkillScopeLabel' | 'noSkillDescription'
-    >;
-  };
+  itemTexts: { slashTexts: ChatInputSurfaceSlashTexts };
   language: I18nLanguage;
   onSelectPanelApp: (appId: string) => void;
   onSelectSkill: (skillRef: string) => void;
+  projectRoot: string;
   recentSkillValues: readonly string[];
   skillRecords: readonly ChatSkillRecord[];
+};
+
+function buildChatInputSurfacePlugins(params: {
+  commands: readonly ChatSlashCommandDescriptor[];
+  language: I18nLanguage;
+  onNavigate: (mode: ContextReferenceMode) => void;
+  onSelectPanelApp: (appId: string) => void;
+  onSelectSkill: (skillRef: string) => void;
+  slashTexts: ChatInputSurfaceSlashTexts;
 }) {
+  const {
+    commands,
+    language,
+    onNavigate,
+    onSelectPanelApp,
+    onSelectSkill,
+    slashTexts,
+  } = params;
+  const panelAppTexts = {
+    appIdLabel: t('chatPanelAppReferenceAppId', language),
+    fileLabel: t('chatPanelAppReferenceFile', language),
+    noDescriptionLabel: t('chatPanelAppReferenceNoDescription', language),
+    subtitle: t('chatPanelAppReferenceType', language),
+  };
+  return [
+    createSlashCommandInputSurfacePlugin({
+      commands,
+      itemTexts: {
+        panelAppTexts,
+        skillTexts: slashTexts,
+      },
+      menuTexts: {
+        loadingLabel: t('chatSlashLoading', language),
+        sectionLabel: t('chatSlashSection', language),
+        emptyLabel: t('chatSlashNoResult', language),
+        hintLabel: t('chatSlashHint', language),
+        itemHintLabel: t('chatSlashSkillHint', language),
+      },
+      labels: {
+        commandHintLabel: t('chatSlashCommandHint', language),
+        commandSectionLabel: t('chatSlashSectionCommands', language),
+        commandSubtitle: t('chatSlashTypeCommand', language),
+        filterAllLabel: t('chatSlashFilterAll', language),
+        filterCommandsLabel: t('chatSlashFilterCommands', language),
+        filterPanelAppsLabel: t('chatSlashFilterPanelApps', language),
+        filterSkillsLabel: t('chatSlashFilterSkills', language),
+        panelAppHintLabel: t('chatSlashPanelAppHint', language),
+        panelAppSectionLabel: t('chatPanelAppReferenceSection', language),
+        skillHintLabel: t('chatSlashSkillHint', language),
+        skillSectionLabel: t('chatSlashSectionSkills', language),
+      },
+      onSelectPanelApp,
+      onSelectSkill,
+    }),
+    createContextReferenceInputSurfacePlugin({
+      itemTexts: {
+        context: {
+          backLabel: t('chatContextReferenceBack', language),
+          backDescription: t('chatContextReferenceBackDescription', language),
+          backHintLabel: t('chatContextReferenceBackHint', language),
+          directoryDescription: t('chatContextReferenceDirectoryDescription', language),
+          fileDescription: t('chatContextReferenceFileDescription', language),
+          filesDescription: t('chatContextReferenceFilesDescription', language),
+          filesHintLabel: t('chatContextReferenceFilesHint', language),
+          filesLabel: t('chatContextReferenceFilesLabel', language),
+          filesSubtitle: t('chatContextReferenceFilesType', language),
+          panelAppSectionLabel: t('chatPanelAppReferenceSection', language),
+          projectRootLabel: t('chatContextReferenceProjectRoot', language),
+          searchFailedLabel: t('chatContextReferenceSearchFailed', language),
+          workspaceSectionLabel: t('chatContextReferenceWorkspaceSection', language),
+        },
+        panelApp: panelAppTexts,
+      },
+      menuTexts: {
+        loadingLabel: t('chatContextReferenceLoading', language),
+        sectionLabel: t('chatContextReferenceSection', language),
+        emptyLabel: t('chatContextReferenceNoResult', language),
+        hintLabel: t('chatContextReferenceHint', language),
+        itemHintLabel: t('chatContextReferenceItemHint', language),
+      },
+      onNavigate,
+    }),
+  ];
+}
+
+export function useChatInputSurfaceState(params: UseChatInputSurfaceStateParams) {
   const {
     isSkillsLoading,
     itemTexts,
     language,
     onSelectPanelApp,
     onSelectSkill,
+    projectRoot,
     recentSkillValues,
     skillRecords,
     commands,
   } = params;
+  const [referenceMode, setReferenceMode] = useState<ContextReferenceMode>('root');
   const [inputSurfaceTrigger, setInputSurfaceTriggerState] = useState<ChatInputSurfaceTrigger | null>(null);
   const inputSurfaceTriggerSignatureRef = useRef('null');
   const setInputSurfaceTrigger = useCallback((nextTrigger: ChatInputSurfaceTrigger | null): void => {
     const nextSignature = JSON.stringify(nextTrigger ? [nextTrigger.key, nextTrigger.marker, nextTrigger.query, nextTrigger.start, nextTrigger.end] : null);
     if (inputSurfaceTriggerSignatureRef.current === nextSignature) return;
     inputSurfaceTriggerSignatureRef.current = nextSignature;
+    if (!nextTrigger) {
+      setReferenceMode('root');
+    }
     setInputSurfaceTriggerState(nextTrigger);
   }, []);
+  const isContextReferenceTrigger = inputSurfaceTrigger?.key === CONTEXT_REFERENCE_TRIGGER_SPEC.key;
+  const deferredReferenceQuery = useDeferredValue(
+    isContextReferenceTrigger ? inputSurfaceTrigger.query : '',
+  );
+  const shouldSearchServerPaths = Boolean(
+    isContextReferenceTrigger &&
+    projectRoot &&
+    (referenceMode === 'files' || deferredReferenceQuery.trim()),
+  );
+  const serverPathSearch = useServerPathSearch({
+    basePath: projectRoot,
+    query: deferredReferenceQuery,
+    enabled: shouldSearchServerPaths,
+  });
   const shouldLoadPanelApps =
-    inputSurfaceTrigger?.key === PANEL_APP_REFERENCE_TRIGGER_SPEC.key ||
+    isContextReferenceTrigger ||
     inputSurfaceTrigger?.key === CHAT_INPUT_SURFACE_SLASH_TRIGGER_SPEC.key;
   const panelApps = usePanelApps({ enabled: shouldLoadPanelApps });
 
   const inputSurfacePlugins = useMemo(
-    () => [
-      createSlashCommandInputSurfacePlugin({
-        commands,
-        itemTexts: {
-          panelAppTexts: {
-            appIdLabel: t('chatPanelAppReferenceAppId', language),
-            fileLabel: t('chatPanelAppReferenceFile', language),
-            noDescriptionLabel: t('chatPanelAppReferenceNoDescription', language),
-            subtitle: t('chatPanelAppReferenceType', language),
-          },
-          skillTexts: itemTexts.slashTexts,
-        },
-        menuTexts: {
-          loadingLabel: t('chatSlashLoading', language),
-          sectionLabel: t('chatSlashSection', language),
-          emptyLabel: t('chatSlashNoResult', language),
-          hintLabel: t('chatSlashHint', language),
-          itemHintLabel: t('chatSlashSkillHint', language)
-        },
-        labels: {
-          commandHintLabel: t('chatSlashCommandHint', language),
-          commandSectionLabel: t('chatSlashSectionCommands', language),
-          commandSubtitle: t('chatSlashTypeCommand', language),
-          filterAllLabel: t('chatSlashFilterAll', language),
-          filterCommandsLabel: t('chatSlashFilterCommands', language),
-          filterPanelAppsLabel: t('chatSlashFilterPanelApps', language),
-          filterSkillsLabel: t('chatSlashFilterSkills', language),
-          panelAppHintLabel: t('chatSlashPanelAppHint', language),
-          panelAppSectionLabel: t('chatPanelAppReferenceSection', language),
-          skillHintLabel: t('chatSlashSkillHint', language),
-          skillSectionLabel: t('chatSlashSectionSkills', language)
-        },
-        onSelectPanelApp,
-        onSelectSkill
-      }),
-      createPanelAppReferenceInputSurfacePlugin({
-        itemTexts: {
-          appIdLabel: t('chatPanelAppReferenceAppId', language),
-          fileLabel: t('chatPanelAppReferenceFile', language),
-          noDescriptionLabel: t('chatPanelAppReferenceNoDescription', language),
-          subtitle: t('chatPanelAppReferenceType', language)
-        },
-        menuTexts: {
-          loadingLabel: t('chatPanelAppReferenceLoading', language),
-          sectionLabel: t('chatPanelAppReferenceSection', language),
-          emptyLabel: t('chatPanelAppReferenceNoResult', language),
-          hintLabel: t('chatPanelAppReferenceHint', language),
-          itemHintLabel: t('chatPanelAppReferenceItemHint', language)
-        }
-      })
-    ],
+    () => buildChatInputSurfacePlugins({
+      commands,
+      language,
+      onNavigate: setReferenceMode,
+      onSelectPanelApp,
+      onSelectSkill,
+      slashTexts: itemTexts.slashTexts,
+    }),
     [
       commands,
       itemTexts.slashTexts,
@@ -118,9 +182,16 @@ export function useChatInputSurfaceState(params: {
     () => resolveChatInputSurfaceState({
       data: {
         isPanelAppsLoading: panelApps.isLoading || panelApps.isFetching,
+        isServerPathSearchLoading: serverPathSearch.isLoading || serverPathSearch.isFetching,
         isSkillsLoading,
         panelApps: panelApps.data?.entries ?? [],
+        projectRoot,
         recentSkillValues,
+        referenceMode,
+        serverPathEntries: serverPathSearch.data?.entries ?? [],
+        serverPathSearchError: serverPathSearch.error instanceof Error
+          ? serverPathSearch.error.message
+          : null,
         skillRecords
       },
       plugins: inputSurfacePlugins,
@@ -132,6 +203,12 @@ export function useChatInputSurfaceState(params: {
       panelApps.data?.entries,
       panelApps.isFetching,
       panelApps.isLoading,
+      projectRoot,
+      referenceMode,
+      serverPathSearch.data?.entries,
+      serverPathSearch.error,
+      serverPathSearch.isFetching,
+      serverPathSearch.isLoading,
       isSkillsLoading,
       recentSkillValues,
       skillRecords

package/src/features/chat/features/input/input-surface-plugins/__tests__/context-reference-plugin.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it, vi } from 'vitest';
+import { resolveChatInputSurfaceState } from '@nextclaw/agent-chat-ui';
+import {
+  CONTEXT_REFERENCE_TRIGGER_SPEC,
+  createContextReferenceInputSurfacePlugin,
+} from '@/features/chat/features/input/input-surface-plugins/context-reference-plugin.utils';
+import type { PanelAppEntryView } from '@/shared/lib/api';
+
+function createPanelApp(): PanelAppEntryView {
+  return {
+    id: 'task-board',
+    appId: 'task-board',
+    fileName: 'task-board.panel.html',
+    kind: 'single-file',
+    title: 'Task Board',
+    description: 'Track tasks',
+    contentPath: '/panels/task-board.panel.html',
+    createdAt: '2026-06-18T00:00:00.000Z',
+    updatedAt: '2026-06-18T00:00:00.000Z',
+    sizeBytes: 100,
+    favorite: false,
+    clientDeclared: false,
+    clientGranted: false,
+    openCount: 0,
+  };
+}
+
+function createPlugin(onNavigate = vi.fn()) {
+  return createContextReferenceInputSurfacePlugin({
+    itemTexts: {
+      context: {
+        backLabel: 'Back',
+        backDescription: 'Back to references',
+        backHintLabel: 'Enter to go back',
+        directoryDescription: 'Directory context',
+        fileDescription: 'File context',
+        filesDescription: 'Browse project files',
+        filesHintLabel: 'Enter to browse',
+        filesLabel: 'Files & Folders',
+        filesSubtitle: 'Project Context',
+        panelAppSectionLabel: 'Panel Apps',
+        projectRootLabel: 'Project directory',
+        searchFailedLabel: 'Search failed',
+        workspaceSectionLabel: 'Files & Folders',
+      },
+      panelApp: {
+        appIdLabel: 'App ID',
+        fileLabel: 'File',
+        noDescriptionLabel: 'No description',
+        subtitle: 'Panel App',
+      },
+    },
+    menuTexts: {
+      loadingLabel: 'Loading',
+      sectionLabel: 'References',
+      emptyLabel: 'Empty',
+      hintLabel: 'Type @',
+      itemHintLabel: 'Enter to reference',
+    },
+    onNavigate,
+  });
+}
+
+function createData(referenceMode: 'root' | 'files' = 'root') {
+  return {
+    isPanelAppsLoading: false,
+    isServerPathSearchLoading: false,
+    isSkillsLoading: false,
+    panelApps: [createPanelApp()],
+    projectRoot: '/tmp/project',
+    recentSkillValues: [],
+    referenceMode,
+    serverPathEntries: [
+      {
+        name: 'server-path.ts',
+        path: '/tmp/project/src/server-path.ts',
+        relativePath: 'src/server-path.ts',
+        parentRelativePath: 'src',
+        kind: 'file' as const,
+        hidden: false,
+      },
+      {
+        name: 'docs',
+        path: '/tmp/project/docs',
+        relativePath: 'docs',
+        parentRelativePath: '',
+        kind: 'directory' as const,
+        hidden: false,
+      },
+    ],
+    serverPathSearchError: null,
+    skillRecords: [],
+  };
+}
+
+describe('context reference input surface plugin', () => {
+  it('shows Files & Folders and panel apps in the root @ menu', () => {
+    const state = resolveChatInputSurfaceState({
+      plugins: [createPlugin()],
+      trigger: {
+        ...CONTEXT_REFERENCE_TRIGGER_SPEC,
+        query: '',
+        start: 0,
+        end: 1,
+      },
+      data: createData(),
+    });
+
+    expect(state.panel?.items).toEqual([
+      expect.objectContaining({
+        title: 'Files & Folders',
+        icon: 'files',
+        selectionBehavior: 'navigate',
+      }),
+      expect.objectContaining({
+        key: 'panel-app:task-board',
+        tokenKind: 'panel_app',
+        tokenKey: 'task-board',
+      }),
+    ]);
+  });
+
+  it('builds file and directory tokens with path previews in files mode', () => {
+    const state = resolveChatInputSurfaceState({
+      plugins: [createPlugin()],
+      trigger: {
+        ...CONTEXT_REFERENCE_TRIGGER_SPEC,
+        query: 'server',
+        start: 0,
+        end: 7,
+      },
+      data: createData('files'),
+    });
+
+    expect(state.panel?.items.slice(1)).toEqual([
+      expect.objectContaining({
+        title: 'server-path.ts',
+        tokenKind: 'workspace_file',
+        tokenKey: 'src/server-path.ts',
+        pathPreview: {
+          rootLabel: 'project',
+          segments: [
+            { label: 'src', kind: 'directory' },
+            { label: 'server-path.ts', kind: 'file' },
+          ],
+        },
+      }),
+      expect.objectContaining({
+        title: 'docs',
+        tokenKind: 'workspace_directory',
+        tokenKey: 'docs',
+      }),
+    ]);
+  });
+
+  it('navigates without producing a composer token', () => {
+    const onNavigate = vi.fn();
+    const state = resolveChatInputSurfaceState({
+      plugins: [createPlugin(onNavigate)],
+      trigger: {
+        ...CONTEXT_REFERENCE_TRIGGER_SPEC,
+        query: '',
+        start: 0,
+        end: 1,
+      },
+      data: createData(),
+    });
+    const item = state.panel?.items[0];
+
+    state.panel?.onSelectItem?.(item!);
+
+    expect(onNavigate).toHaveBeenCalledWith('files');
+    expect(item).not.toHaveProperty('tokenKind');
+  });
+});