@open-mercato/ui 0.5.1-develop.3036.f02c281f23 → 0.5.1-develop.3045.b4b3320cc2

package/src/ai/useAiChatUpload.ts

@@ -0,0 +1,180 @@
+"use client"
+
+import * as React from 'react'
+import {
+  uploadAttachmentsForChat,
+  type UploadAttachmentsForChatOptions,
+  type UploadAttachmentsForChatResult,
+  type UploadFailureReason,
+} from './upload-adapter'
+
+/**
+ * React hook wrapping {@link uploadAttachmentsForChat} with per-file state so
+ * the {@link AiChat} composer can render progress chips, error badges, and a
+ * Clear action without each consumer re-implementing the machinery.
+ *
+ * The hook is DS-neutral: it exposes only state and {@link UploadFailureReason}
+ * codes. Consumers translate user-facing strings through `useT()` at render
+ * time — no hard-coded copy in the hook.
+ */
+
+export interface UseAiChatUploadOptions extends UploadAttachmentsForChatOptions {
+  /** Identical to the adapter options; forwarded verbatim. */
+}
+
+export type AiChatUploadFileStatus = 'queued' | 'uploading' | 'done' | 'error'
+
+export interface AiChatUploadFileState {
+  fileName: string
+  size: number
+  progress: number
+  status: AiChatUploadFileStatus
+  attachmentId?: string
+  reason?: UploadFailureReason
+  error?: string
+}
+
+export interface UseAiChatUploadState {
+  files: AiChatUploadFileState[]
+  overallProgress: number
+  busy: boolean
+  upload: (files: File[]) => Promise<UploadAttachmentsForChatResult>
+  reset: () => void
+}
+
+const EMPTY_STATE: AiChatUploadFileState[] = []
+
+function computeOverallProgress(entries: AiChatUploadFileState[]): number {
+  if (entries.length === 0) return 0
+  const total = entries.reduce((sum, entry) => sum + entry.progress, 0)
+  const average = total / entries.length
+  if (!Number.isFinite(average)) return 0
+  if (average < 0) return 0
+  if (average > 1) return 1
+  return average
+}
+
+export function useAiChatUpload(
+  options: UseAiChatUploadOptions = {},
+): UseAiChatUploadState {
+  const [files, setFiles] = React.useState<AiChatUploadFileState[]>(EMPTY_STATE)
+  const [busy, setBusy] = React.useState(false)
+  const optionsRef = React.useRef(options)
+  React.useEffect(() => {
+    optionsRef.current = options
+  }, [options])
+
+  const overallProgress = React.useMemo(() => computeOverallProgress(files), [files])
+
+  const reset = React.useCallback(() => {
+    setFiles(EMPTY_STATE)
+    setBusy(false)
+  }, [])
+
+  const upload = React.useCallback(
+    async (incoming: File[]): Promise<UploadAttachmentsForChatResult> => {
+      if (!incoming || incoming.length === 0) {
+        return { items: [], failed: [] }
+      }
+      const initialEntries: AiChatUploadFileState[] = incoming.map((file) => ({
+        fileName: file.name,
+        size: file.size,
+        progress: 0,
+        status: 'uploading',
+      }))
+      setFiles(initialEntries)
+      setBusy(true)
+
+      const callerOptions = optionsRef.current
+      const callerProgress = callerOptions.onProgress
+      const result = await uploadAttachmentsForChat(incoming, {
+        ...callerOptions,
+        onProgress: (fileIndex, progress) => {
+          const ratio =
+            progress.total > 0
+              ? Math.max(0, Math.min(1, progress.loaded / progress.total))
+              : 0
+          setFiles((current) => {
+            if (fileIndex < 0 || fileIndex >= current.length) return current
+            const next = current.slice()
+            const entry = next[fileIndex]
+            if (!entry) return current
+            next[fileIndex] = { ...entry, progress: ratio }
+            return next
+          })
+          if (callerProgress) {
+            try {
+              callerProgress(fileIndex, progress)
+            } catch {
+              // Consumer-supplied callbacks must never abort state updates.
+            }
+          }
+        },
+      }).catch((err) => {
+        // uploadAttachmentsForChat only rejects on programming errors; coerce
+        // to a failure envelope so the hook state never throws at consumers.
+        const message = err instanceof Error ? err.message : 'Upload batch failed.'
+        return {
+          items: [],
+          failed: incoming.map((file, inputIndex) => ({
+            fileName: file.name,
+            originalFileName: file.name,
+            inputIndex,
+            reason: 'network' as UploadFailureReason,
+            message,
+          })),
+        } satisfies UploadAttachmentsForChatResult
+      })
+
+      setFiles((current) => {
+        const failedByName = new Map<string, typeof result.failed[number]>()
+        for (const failure of result.failed) {
+          if (!failedByName.has(failure.fileName)) {
+            failedByName.set(failure.fileName, failure)
+          }
+        }
+        return current.map((entry, index) => {
+          const success = result.items.find(
+            (item, itemIndex) => itemIndex === index && item.fileName === entry.fileName,
+          )
+          if (success) {
+            return {
+              ...entry,
+              progress: 1,
+              status: 'done' as AiChatUploadFileStatus,
+              attachmentId: success.attachmentId,
+            }
+          }
+          const failure = failedByName.get(entry.fileName)
+          if (failure) {
+            failedByName.delete(entry.fileName)
+            return {
+              ...entry,
+              status: 'error' as AiChatUploadFileStatus,
+              reason: failure.reason,
+              error: failure.message,
+            }
+          }
+          // Defensive: a worker exited without producing either outcome.
+          return {
+            ...entry,
+            status: 'error' as AiChatUploadFileStatus,
+            reason: 'network' as UploadFailureReason,
+          }
+        })
+      })
+
+      setBusy(false)
+      return result
+    },
+    [],
+  )
+
+  return {
+    files,
+    overallProgress,
+    busy,
+    upload,
+    reset,
+  }
+}

package/src/ai/useAiShortcuts.ts

@@ -0,0 +1,79 @@
+"use client"
+
+import * as React from 'react'
+
+/**
+ * Shared keyboard-shortcut hook for the AI surfaces shipped in Phase 2
+ * (Step 4.6 / Phase 2 WS-B polish). Centralises the `Cmd/Ctrl+Enter` and
+ * `Escape` handling used by `<AiChat>`, the AI playground, and the agent
+ * settings page so every surface honours the same shortcuts without each
+ * page rolling its own listener.
+ *
+ * - `onSubmit` fires on `Enter` (without `Shift`) when the shortcut is
+ *   triggered while focus is inside the bound element. `Shift+Enter` is
+ *   left to the browser for native newline insertion.
+ * - `onCancel` fires on `Escape`. Callers decide what cancel means (abort an
+ *   in-flight stream, blur the composer, close a drawer, reset a draft).
+ * - `enabled` gates the hook for conditional bindings without unmounting.
+ *
+ * The hook is deliberately minimal. It never stops propagation; callers that
+ * embed modal dialogs keep their own Escape handling because React events
+ * bubble predictably.
+ */
+export interface UseAiShortcutsOptions {
+  onSubmit?: () => void
+  onCancel?: () => void
+  enabled?: boolean
+}
+
+export interface UseAiShortcutsResult {
+  /**
+   * Keyboard handler ready to be attached via `onKeyDown`. Returns `true`
+   * when the event matched a shortcut so callers can branch on the result.
+   */
+  handleKeyDown: (event: React.KeyboardEvent) => boolean
+}
+
+export function useAiShortcuts(options: UseAiShortcutsOptions): UseAiShortcutsResult {
+  const { onSubmit, onCancel, enabled = true } = options
+
+  const onSubmitRef = React.useRef(onSubmit)
+  const onCancelRef = React.useRef(onCancel)
+  React.useEffect(() => {
+    onSubmitRef.current = onSubmit
+  }, [onSubmit])
+  React.useEffect(() => {
+    onCancelRef.current = onCancel
+  }, [onCancel])
+
+  const handleKeyDown = React.useCallback<UseAiShortcutsResult['handleKeyDown']>(
+    (event) => {
+      if (!enabled) return false
+      // Enter — primary submit. Shift+Enter inserts a newline instead.
+      if (event.key === 'Enter' && !event.shiftKey) {
+        if (onSubmitRef.current) {
+          event.preventDefault()
+          onSubmitRef.current()
+          return true
+        }
+        return false
+      }
+      // Escape — secondary cancel. Never swallow unless a handler is bound so
+      // parent dialogs can still handle Escape the native way.
+      if (event.key === 'Escape') {
+        if (onCancelRef.current) {
+          event.preventDefault()
+          onCancelRef.current()
+          return true
+        }
+        return false
+      }
+      return false
+    },
+    [enabled],
+  )
+
+  return { handleKeyDown }
+}
+
+export default useAiShortcuts

package/src/backend/AppShell.tsx

@@ -30,6 +30,9 @@ import { resolveInjectedIcon } from './injection/resolveInjectedIcon'
 import { useEventBridge } from './injection/eventBridge'
 import { StatusBadgeInjectionSpot } from './injection/StatusBadgeInjectionSpot'
 import { UmesDevToolsPanel } from './devtools'
+import { AiDockProvider } from '../ai/AiDock'
+import { AiChatSessionsProvider } from '../ai/AiChatSessions'
+import { AiAssistantLauncher } from '../ai/AiAssistantLauncher'
 import { BackendChromeProvider, useBackendChrome } from './BackendChromeProvider'
 import {
   BACKEND_LAYOUT_FOOTER_INJECTION_SPOT_ID,
@@ -393,7 +396,11 @@ export function AppShell(props: AppShellProps) {
   return (
     <QueryProvider>
       <BackendChromeProvider adminNavApi={props.adminNavApi}>
-        <AppShellBody {...props} />
+        <AiChatSessionsProvider>
+          <AiDockProvider>
+            <AppShellBody {...props} />
+          </AiDockProvider>
+        </AiChatSessionsProvider>
       </BackendChromeProvider>
     </QueryProvider>
   )
@@ -464,11 +471,11 @@ function AppShellBody({ productName, logo, email, groups, rightHeaderSlot, child
     }
     update()
     target.addEventListener('scroll', update, { passive: true })
-    const ro = new ResizeObserver(update)
-    ro.observe(target)
+    const ro = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(update) : null
+    ro?.observe(target)
     return () => {
       target.removeEventListener('scroll', update)
-      ro.disconnect()
+      ro?.disconnect()
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [pathname, effectiveCollapsed])
@@ -1229,6 +1236,7 @@ function AppShellBody({ productName, logo, email, groups, rightHeaderSlot, child
               context={injectionContext}
             />
             {renderedTopbarInjectedActions}
+            <AiAssistantLauncher variant="topbar" />
             {rightHeaderSlot ? (
               rightHeaderSlot
             ) : (
@@ -1298,4 +1306,3 @@ function AppShellBody({ productName, logo, email, groups, rightHeaderSlot, child
     </HeaderContext.Provider>
   )
 }
-

package/src/backend/BackendChromeProvider.tsx

@@ -41,6 +41,8 @@ export function BackendChromeProvider({ adminNavApi, children }: BackendChromePr
       const nextPayload = call.result
       chromeCache.set(buildCacheKey(adminNavApi), nextPayload)
       setPayload(nextPayload)
+    } catch {
+      return
     } finally {
       setIsLoading(false)
     }

package/src/backend/DataTable.tsx

@@ -1039,7 +1039,7 @@ export function DataTable<T>({
   }, [injectionSpotId, perspective?.tableId])
   const resolvedInjectionSpotId = injectionSpotId ?? (perspective?.tableId ? `data-table:${perspective.tableId}` : null)
   const resolvedReplacementHandle = replacementHandle ?? ComponentReplacementHandles.dataTable(extensionTableId ?? 'unknown')
-  const resolvedInjectionContext = React.useMemo(
+  const baseInjectionContext = React.useMemo(
     () => injectionContext ?? { tableId: perspective?.tableId ?? null, title: typeof title === 'string' ? title : undefined },
     [injectionContext, perspective?.tableId, title]
   )
@@ -1051,6 +1051,10 @@ export function DataTable<T>({
     () => (resolvedInjectionSpotId ? `${resolvedInjectionSpotId}:toolbar` : null),
     [resolvedInjectionSpotId]
   )
+  const searchTrailingInjectionSpotId = React.useMemo(
+    () => (resolvedInjectionSpotId ? `${resolvedInjectionSpotId}:search-trailing` : null),
+    [resolvedInjectionSpotId]
+  )
   const footerInjectionSpotId = React.useMemo(
     () => (resolvedInjectionSpotId ? `${resolvedInjectionSpotId}:footer` : null),
     [resolvedInjectionSpotId]
@@ -1340,6 +1344,15 @@ export function DataTable<T>({
     if (Object.keys(rowSelection).length === 0) return
     setRowSelection({})
   }, [hasInjectedBulkActions, rowSelection])
+  const resolvedInjectionContext = React.useMemo(
+    () => {
+      if (!hasInjectedBulkActions) return baseInjectionContext
+      const selectedIds = Object.keys(rowSelection).filter((key) => rowSelection[key])
+      if (selectedIds.length === 0) return baseInjectionContext
+      return { ...baseInjectionContext, _selectedRowIds: selectedIds, _selectedCount: selectedIds.length }
+    },
+    [baseInjectionContext, hasInjectedBulkActions, rowSelection],
+  )
   React.useEffect(() => {
     const ids = table.getAllLeafColumns().map((column) => column.id)
     if (!ids.length) return
@@ -2180,6 +2193,9 @@ export function DataTable<T>({
         }) : null}
       </div>
     ) : null
+    const searchTrailingNode = searchTrailingInjectionSpotId && onSearchChange ? (
+      <InjectionSpot spotId={searchTrailingInjectionSpotId} context={resolvedInjectionContext} />
+    ) : null
     return (
       <FilterBar
         searchValue={searchValue}
@@ -2192,6 +2208,7 @@ export function DataTable<T>({
         onClear={onFiltersClear}
         leadingItems={leadingItems}
         trailingItems={trailingItems}
+        searchTrailing={searchTrailingNode}
         filtersExtraContent={fieldsetSelector}
         layout={embedded ? 'inline' : 'stacked'}
         className={embedded ? 'min-h-[2.25rem]' : undefined}
@@ -2224,6 +2241,8 @@ export function DataTable<T>({
     selectedRows,
     runBulkAction,
     runPropBulkAction,
+    searchTrailingInjectionSpotId,
+    resolvedInjectionContext,
   ])
 
   const hasTitle = title != null

package/src/backend/FilterBar.tsx

@@ -17,6 +17,13 @@ export type FilterBarProps = {
   className?: string
   leadingItems?: React.ReactNode
   trailingItems?: React.ReactNode
+  /**
+   * Items rendered immediately after the search input on the same row.
+   * Intended for compact, icon-sized triggers (AI assistants, saved view
+   * shortcuts). Stays adjacent to the search input regardless of
+   * `searchAlign` and is suppressed when no search input is rendered.
+   */
+  searchTrailing?: React.ReactNode
   layout?: 'stacked' | 'inline'
   filtersExtraContent?: React.ReactNode
 }
@@ -33,6 +40,7 @@ export function FilterBar({
   className,
   leadingItems,
   trailingItems,
+  searchTrailing,
   layout = 'stacked',
   filtersExtraContent,
 }: FilterBarProps) {
@@ -72,20 +80,25 @@ export function FilterBar({
   }, [values])
 
   const containerClass = `flex flex-col ${layout === 'inline' ? 'gap-1 sm:gap-2' : 'gap-2'} w-full`
-  const searchInput = onSearchChange ? (
-    <div className={`relative w-full sm:w-72 lg:w-80 ${searchAlign === 'right' ? 'sm:ml-auto' : ''}`}>
-      <input
-        value={searchDraft}
-        onChange={(e) => setSearchDraft(e.target.value)}
-        placeholder={resolvedSearchPlaceholder}
-        className="h-9 w-full rounded-md border border-input bg-background pl-8 pr-2 text-sm shadow-xs outline-none transition-colors placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring/50"
-        suppressHydrationWarning
-      />
-      <Search aria-hidden="true" className="absolute left-2 top-1/2 size-4 -translate-y-1/2 text-muted-foreground" />
+  const searchBlock = onSearchChange ? (
+    <div className={`flex items-center gap-2 ${searchAlign === 'right' ? 'sm:ml-auto' : ''}`}>
+      <div className="relative w-full sm:w-72 lg:w-80">
+        <input
+          value={searchDraft}
+          onChange={(e) => setSearchDraft(e.target.value)}
+          placeholder={resolvedSearchPlaceholder}
+          className="h-9 w-full rounded-md border border-input bg-background pl-8 pr-2 text-sm shadow-xs outline-none transition-colors placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring/50"
+          suppressHydrationWarning
+        />
+        <Search aria-hidden="true" className="absolute left-2 top-1/2 size-4 -translate-y-1/2 text-muted-foreground" />
+      </div>
+      {searchTrailing ? (
+        <div className="flex items-center gap-1">{searchTrailing}</div>
+      ) : null}
     </div>
   ) : null
   const controls = (
-    <div className={`flex flex-wrap items-center gap-2 ${searchAlign === 'left' && searchInput ? 'sm:ml-auto' : ''}`}>
+    <div className={`flex flex-wrap items-center gap-2 ${searchAlign === 'left' && searchBlock ? 'sm:ml-auto' : ''}`}>
       {filters.length > 0 && (
         <Button variant="outline" onClick={() => setOpen(true)}>
           <ListFilter aria-hidden="true" className="size-4 opacity-80" />
@@ -103,9 +116,9 @@ export function FilterBar({
   return (
     <div className={`${containerClass} ${className ?? ''}`}>
       <div className="flex flex-wrap items-center gap-2 w-full">
-        {searchAlign === 'left' ? searchInput : null}
+        {searchAlign === 'left' ? searchBlock : null}
         {controls}
-        {searchAlign === 'right' ? searchInput : null}
+        {searchAlign === 'right' ? searchBlock : null}
       </div>
       {/* Active filter chips */}
       {filters.length > 0 && activeCount > 0 && (

package/src/backend/__tests__/BackendChromeProvider.test.tsx

@@ -0,0 +1,45 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import * as React from 'react'
+import { render, screen, waitFor } from '@testing-library/react'
+import { BackendChromeProvider, useBackendChrome } from '../BackendChromeProvider'
+import { apiCall } from '../utils/apiCall'
+
+jest.mock('../utils/apiCall', () => ({
+  apiCall: jest.fn(),
+}))
+
+function ChromeStateProbe() {
+  const chrome = useBackendChrome()
+  return (
+    <div>
+      <span data-testid="loading">{chrome.isLoading ? 'loading' : 'idle'}</span>
+      <span data-testid="ready">{chrome.isReady ? 'ready' : 'not-ready'}</span>
+    </div>
+  )
+}
+
+describe('BackendChromeProvider', () => {
+  beforeEach(() => {
+    ;(apiCall as jest.Mock).mockReset()
+  })
+
+  it('contains transient navigation fetch failures', async () => {
+    ;(apiCall as jest.Mock).mockRejectedValue(new TypeError('Failed to fetch'))
+
+    render(
+      <BackendChromeProvider adminNavApi="/api/auth/admin/nav">
+        <ChromeStateProbe />
+      </BackendChromeProvider>,
+    )
+
+    await waitFor(() => {
+      expect(screen.getByTestId('loading')).toHaveTextContent('idle')
+    })
+
+    expect(screen.getByTestId('ready')).toHaveTextContent('not-ready')
+    expect(apiCall).toHaveBeenCalledWith('/api/auth/admin/nav', { credentials: 'include' })
+  })
+})

package/src/backend/dashboard/DashboardScreen.tsx

@@ -5,11 +5,12 @@ import { Button } from '@open-mercato/ui/primitives/button'
 import { IconButton } from '@open-mercato/ui/primitives/icon-button'
 import { Spinner } from '@open-mercato/ui/primitives/spinner'
 import { ErrorNotice } from '@open-mercato/ui/primitives/ErrorNotice'
+import { Alert, AlertDescription, AlertTitle } from '@open-mercato/ui/primitives/alert'
 import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
-import { loadDashboardWidgetModule } from './widgetRegistry'
+import { getDashboardWidgets, loadDashboardWidgetModule } from './widgetRegistry'
 import type { DashboardWidgetModule } from '@open-mercato/shared/modules/dashboard/widgets'
 import { cn } from '@open-mercato/shared/lib/utils'
-import { GripVertical, Plus, RefreshCw, Settings2, Trash2, X, Loader2 } from 'lucide-react'
+import { GripVertical, Info, Plus, RefreshCw, Settings2, Trash2, X, Loader2 } from 'lucide-react'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { InjectionSpot } from '../injection/InjectionSpot'
 
@@ -93,6 +94,7 @@ export function DashboardScreen() {
   const t = useT()
   const [loading, setLoading] = React.useState(true)
   const [error, setError] = React.useState<string | null>(null)
+  const [hasRegisteredWidgets, setHasRegisteredWidgets] = React.useState(true)
   const [saving, setSaving] = React.useState(false)
   const [layout, setLayout] = React.useState<LayoutItem[]>([])
   const [widgetCatalog, setWidgetCatalog] = React.useState<WidgetMeta[]>([])
@@ -119,9 +121,11 @@ export function DashboardScreen() {
         throw new Error(`Failed with status ${call.status}`)
       }
       const data = call.result
+      const registeredWidgetCount = getDashboardWidgets().length
       const normalizedLayout = sortLayout(data.layout?.items ?? [])
       setLayout(normalizedLayout)
       setWidgetCatalog(data.widgets ?? [])
+      setHasRegisteredWidgets(registeredWidgetCount > 0 || (data.widgets ?? []).length > 0)
       setAllowedWidgetIds(data.allowedWidgetIds ?? [])
       setCanConfigure(!!data.canConfigure)
       if (data.context) {
@@ -142,6 +146,17 @@ export function DashboardScreen() {
       }
     } catch (err) {
       console.error('Failed to load dashboard layout', err)
+      if (getDashboardWidgets().length === 0) {
+        setHasRegisteredWidgets(false)
+        setLayout([])
+        setWidgetCatalog([])
+        setAllowedWidgetIds([])
+        setCanConfigure(false)
+        setContext(null)
+        setEditing(false)
+        setSettingsId(null)
+        return
+      }
       setError(t('dashboard.loadError'))
     } finally {
       setLoading(false)
@@ -345,6 +360,21 @@ export function DashboardScreen() {
     )
   }
 
+  if (!hasRegisteredWidgets && layout.length === 0) {
+    return (
+      <Alert variant="info">
+        <Info className="h-4 w-4" aria-hidden />
+        <AlertTitle>{t('dashboard.empty.noWidgets.title', 'No dashboard widgets yet')}</AlertTitle>
+        <AlertDescription>
+          {t(
+            'dashboard.empty.noWidgets.description',
+            'After you add the first module that exposes dashboard widgets, they will appear here.',
+          )}
+        </AlertDescription>
+      </Alert>
+    )
+  }
+
   return (
     <div className="space-y-6">
       <div className="flex flex-wrap items-center justify-between gap-3">
@@ -464,7 +494,12 @@ export function DashboardScreen() {
 
       {layout.length === 0 && (
         <div className="rounded-lg border border-dashed bg-muted/30 p-10 text-center text-sm text-muted-foreground">
-          {canConfigure ? t('dashboard.empty.configurable') : t('dashboard.empty.readonly')}
+          {!hasRegisteredWidgets
+            ? t(
+              'dashboard.empty.noWidgets.description',
+              'After you add the first module that exposes dashboard widgets, they will appear here.',
+            )
+            : canConfigure ? t('dashboard.empty.configurable') : t('dashboard.empty.readonly')}
         </div>
       )}
 

package/src/backend/dashboard/__tests__/DashboardScreen.test.tsx

@@ -7,7 +7,7 @@ import { screen, waitFor } from '@testing-library/react'
 import { renderWithProviders } from '@open-mercato/shared/lib/testing/renderWithProviders'
 import { DashboardScreen } from '../DashboardScreen'
 import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
-import { loadDashboardWidgetModule } from '../widgetRegistry'
+import { getDashboardWidgets, loadDashboardWidgetModule } from '../widgetRegistry'
 
 jest.setTimeout(20000)
 
@@ -16,6 +16,7 @@ jest.mock('@open-mercato/ui/backend/utils/apiCall', () => ({
 }))
 
 jest.mock('../widgetRegistry', () => ({
+  getDashboardWidgets: jest.fn(),
   loadDashboardWidgetModule: jest.fn(),
 }))
 
@@ -31,6 +32,8 @@ const createMockResponse = (status: number): Response => ({ status } as Response
 
 const dict = {
   'dashboard.loadError': 'Failed to load dashboard',
+  'dashboard.empty.noWidgets.title': 'No dashboard widgets yet',
+  'dashboard.empty.noWidgets.description': 'Dashboard widgets will appear here after you add a module.',
   'dashboard.widgets.foo.title': 'Widget Foo',
   'dashboard.widgets.foo.description': 'Widget description',
 }
@@ -71,6 +74,7 @@ function MockWidget() {
 describe('DashboardScreen', () => {
   beforeEach(() => {
     jest.resetAllMocks()
+    ;(getDashboardWidgets as jest.Mock).mockReturnValue([{ key: 'foo.loader', loader: jest.fn() }])
     ;(loadDashboardWidgetModule as jest.Mock).mockResolvedValue({
       Widget: MockWidget,
       hydrateSettings: (value: unknown) => value,
@@ -111,4 +115,23 @@ describe('DashboardScreen', () => {
 
     errorSpy.mockRestore()
   })
+
+  it('shows an informational empty state when no dashboard widgets are registered', async () => {
+    const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {})
+    ;(getDashboardWidgets as jest.Mock).mockReturnValue([])
+    ;(apiCall as jest.Mock).mockResolvedValue({
+      ok: false,
+      status: 500,
+      result: null,
+      response: createMockResponse(500),
+    })
+
+    renderWithProviders(<DashboardScreen />, { dict })
+
+    expect(await screen.findByText('No dashboard widgets yet')).toBeInTheDocument()
+    expect(screen.getByText('Dashboard widgets will appear here after you add a module.')).toBeInTheDocument()
+    expect(screen.queryByText('Failed to load dashboard')).not.toBeInTheDocument()
+
+    errorSpy.mockRestore()
+  })
 })

package/src/backend/injection/spotIds.ts

@@ -33,6 +33,12 @@ export const DataTableInjectionSpots = {
   header: (tableId: string): InjectionSpotId => `data-table:${tableId}:header`,
   footer: (tableId: string): InjectionSpotId => `data-table:${tableId}:footer`,
   toolbar: (tableId: string): InjectionSpotId => `data-table:${tableId}:toolbar`,
+  // Slot rendered immediately after the search input on the same row as the
+  // FilterBar — intended for compact, icon-sized triggers (AI assistants,
+  // saved view shortcuts, etc.). Hosts pass the resolved spot ID through to
+  // FilterBar's `searchTrailing` prop. Stays empty when the table has no
+  // search input.
+  searchTrailing: (tableId: string): InjectionSpotId => `data-table:${tableId}:search-trailing`,
   emptyState: (tableId: string): InjectionSpotId => `data-table:${tableId}:empty-state`,
   columns: (tableId: string): InjectionSpotId => `data-table:${tableId}:columns`,
   rowActions: (tableId: string): InjectionSpotId => `data-table:${tableId}:row-actions`,