@classic-homes/agent-chat 0.4.1 → 0.5.0

package/README.md

@@ -51,6 +51,10 @@ agent-api origin that serves `/frame`; artifacts and MCP-UI resources only ever
   (`ComposerPrompt.text` may be a loader, e.g. fetching the template).
 - `ToolTimeline`: tool calls with status and duration, delegations nested; `toolLabels` maps
   tool names to readable ones (`AgentChat` passes both through).
+- `Welcome`: the empty conversation, with a greeting (`userName`), a capability line and up to
+  four `suggestions` that send when chosen. `AgentChat` shows it unless the host passes an
+  `empty` snippet, a loading skeleton while an existing conversation's transcript arrives, and
+  an error with Try again when that load fails.
 - `ArtifactPanel`, `UiFrame`, `ModeBanner`.
 
 Publishing: `docs/operations/package-publishing.md`.

package/dist/components/AgentChat.svelte

@@ -7,15 +7,25 @@
     FileRef,
   } from '@classic-homes/agent-contracts';
   import type { BackendMode } from '@classic-homes/agent-contracts';
-  import { cn, ResizablePanes, Sheet } from '@classic-homes/theme-svelte';
+  import {
+    Alert,
+    Button,
+    cn,
+    Icon,
+    ResizablePanes,
+    Sheet,
+    Skeleton,
+  } from '@classic-homes/theme-svelte';
   import { MediaQuery } from 'svelte/reactivity';
   import { releaseStuckBodyLock } from '../body-lock.js';
   import type { ComposerPrompt } from '../composer-prompts.js';
   import { ChatSession } from '../session.svelte.js';
+  import type { WelcomeSuggestion } from '../welcome.js';
   import ArtifactPanel from './ArtifactPanel.svelte';
   import Composer from './Composer.svelte';
   import MessageList from './MessageList.svelte';
   import ModeBanner from './ModeBanner.svelte';
+  import Welcome from './Welcome.svelte';
 
   interface Props {
     client: AgentApiClient;
@@ -45,9 +55,18 @@
     prompts?: ComposerPrompt[];
     /** Readable tool names for the timeline, by tool name (`server/name` or `name`). */
     toolLabels?: Record<string, string>;
+    /** The signed-in user's name for the welcome greeting (first word shown). */
+    userName?: string | null;
+    /** Starters on an empty conversation (up to four); choosing one sends it. */
+    suggestions?: WelcomeSuggestion[];
+    /** Replaces the welcome's time-of-day greeting. */
+    welcomeTitle?: string;
+    /** Replaces the welcome's capability line. */
+    welcomeDescription?: string;
     /** Rendered above the transcript, e.g. a `ChatHeader`. */
     header?: import('svelte').Snippet;
     context?: import('svelte').Snippet;
+    /** Replaces the default `Welcome` on an empty conversation. */
     empty?: import('svelte').Snippet;
     class?: string;
   }
@@ -69,6 +88,10 @@
     placeholder,
     prompts,
     toolLabels,
+    userName,
+    suggestions,
+    welcomeTitle,
+    welcomeDescription,
     header,
     context,
     empty,
@@ -94,15 +117,20 @@
       }
     },
   });
+  let attemptedId: string | null = null;
   // The constructor already knows `conversationId`; what decides a fetch is whether the
   // transcript for it has been loaded (or started) in this session.
   $effect(() => {
     if (
       conversationId &&
       conversationId !== session.loadedConversationId &&
+      conversationId !== attemptedId &&
       session.status !== 'loading'
-    )
+    ) {
+      // Once per id: a failed load waits for Try again instead of retrying in a loop.
+      attemptedId = conversationId;
       void session.load(conversationId);
+    }
   });
   $effect(() => {
     if (mode && !session.mode) session.mode = mode;
@@ -135,19 +163,82 @@
     const last = session.messages[session.messages.length - 1];
     if (last?.role === 'assistant') void session.retry(last.requestId);
   }
+  // An existing conversation whose transcript has not arrived yet: show a skeleton, not the
+  // welcome (which would flash before the messages).
+  const pending = $derived(
+    session.status === 'loading' ||
+      (!!conversationId &&
+        conversationId !== session.loadedConversationId &&
+        !session.loadError &&
+        session.messages.length === 0),
+  );
+  function reload(): void {
+    if (conversationId) void session.load(conversationId);
+  }
   function prompt(text: string): void {
     draft = text;
     composer?.focus();
   }
 </script>
 
+{#snippet emptyState()}
+  {#if pending}
+    <div
+      class="mx-auto flex w-full max-w-3xl flex-col gap-6 px-4 py-6"
+      aria-busy="true"
+      data-agent-loading
+    >
+      <span class="sr-only" role="status">Loading conversation…</span>
+      <Skeleton class="ml-auto h-10 w-2/5 rounded-2xl" />
+      <div class="flex flex-col gap-2">
+        <Skeleton variant="text" class="w-11/12" />
+        <Skeleton variant="text" class="w-4/5" />
+        <Skeleton variant="text" class="w-3/5" />
+      </div>
+      <Skeleton class="ml-auto h-10 w-1/3 rounded-2xl" />
+      <div class="flex flex-col gap-2">
+        <Skeleton variant="text" class="w-10/12" />
+        <Skeleton variant="text" class="w-2/3" />
+      </div>
+    </div>
+  {:else if session.loadError}
+    <!-- The alert above explains it; no welcome under a failed load. -->
+  {:else if empty}
+    {@render empty()}
+  {:else}
+    <Welcome
+      name={userName}
+      title={welcomeTitle}
+      description={welcomeDescription}
+      {suggestions}
+      compact={variant === 'panel'}
+      disabled={session.status !== 'idle'}
+      onselect={(text) => void send(text)}
+    />
+  {/if}
+{/snippet}
+
 {#snippet chat()}
   <div class="flex h-full min-w-0 flex-1 flex-col">
     {#if header}{@render header()}{/if}
     <ModeBanner mode={session.mode} />
-    {#if session.loadError}<div class="px-4 py-2 text-sm text-destructive" role="alert">
-        {session.loadError}
-      </div>{/if}
+    {#if session.loadError}
+      <div class="mx-auto w-full max-w-3xl px-4 pt-3">
+        <Alert variant="error">
+          <div class="flex flex-wrap items-center gap-x-3 gap-y-1">
+            <p class="min-w-0 flex-1">
+              <strong class="font-semibold">Could not load this conversation.</strong>
+              {session.loadError}
+            </p>
+            {#if conversationId}
+              <Button variant="outline" size="sm" onclick={reload}>
+                <Icon name="refresh" size={14} /> Try again
+              </Button>
+            {/if}
+          </div>
+        </Alert>
+      </div>
+    {/if}
     <MessageList
       messages={session.messages}
       streaming={session.streaming}
@@ -164,7 +255,7 @@
       {onnotify}
       onretry={retry}
       oncontinue={() => void session.send('Continue.')}
-      {empty}
+      empty={emptyState}
     />
     <Composer
       bind:this={composer}

package/dist/components/AgentChat.svelte.d.ts

@@ -2,6 +2,7 @@ import type { AgentApiClient } from '@classic-homes/agent-client';
 import type { AgentKey, ClientKind, DocumentContext } from '@classic-homes/agent-contracts';
 import type { BackendMode } from '@classic-homes/agent-contracts';
 import type { ComposerPrompt } from '../composer-prompts.js';
+import type { WelcomeSuggestion } from '../welcome.js';
 interface Props {
     client: AgentApiClient;
     /** Sandbox origin for artifacts and MCP-UI (agent-api `/frame`). */
@@ -30,9 +31,18 @@ interface Props {
     prompts?: ComposerPrompt[];
     /** Readable tool names for the timeline, by tool name (`server/name` or `name`). */
     toolLabels?: Record<string, string>;
+    /** The signed-in user's name for the welcome greeting (first word shown). */
+    userName?: string | null;
+    /** Starters on an empty conversation (up to four); choosing one sends it. */
+    suggestions?: WelcomeSuggestion[];
+    /** Replaces the welcome's time-of-day greeting. */
+    welcomeTitle?: string;
+    /** Replaces the welcome's capability line. */
+    welcomeDescription?: string;
     /** Rendered above the transcript, e.g. a `ChatHeader`. */
     header?: import('svelte').Snippet;
     context?: import('svelte').Snippet;
+    /** Replaces the default `Welcome` on an empty conversation. */
     empty?: import('svelte').Snippet;
     class?: string;
 }

package/dist/components/AgentChat.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AgentChat.svelte.d.ts","sourceRoot":"","sources":["../../src/lib/components/AgentChat.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,KAAK,EACR,QAAQ,EACR,UAAU,EACV,eAAe,EAEhB,MAAM,gCAAgC,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAIlE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAQ3D,UAAU,KAAK;IACb,MAAM,EAAE,cAAc,CAAC;IACvB,oEAAoE;IACpE,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,+EAA+E;IAC/E,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,eAAe,GAAG,IAAI,GAAG,SAAS,CAAC;IACtD,qBAAqB,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,IAAI,CAAC;IACzD,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACtD,gFAAgF;IAChF,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;QAC9B,MAAM,EAAE,MAAM,CAAC;KAChB,KAAK,IAAI,CAAC;IACX,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,iGAAiG;IACjG,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,0DAA0D;IAC1D,MAAM,CAAC,EAAE,OAAO,QAAQ,EAAE,OAAO,CAAC;IAClC,OAAO,CAAC,EAAE,OAAO,QAAQ,EAAE,OAAO,CAAC;IACnC,KAAK,CAAC,EAAE,OAAO,QAAQ,EAAE,OAAO,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAgJH,QAAA,MAAM,SAAS,2CAAwC,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}
+{"version":3,"file":"AgentChat.svelte.d.ts","sourceRoot":"","sources":["../../src/lib/components/AgentChat.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,KAAK,EACR,QAAQ,EACR,UAAU,EACV,eAAe,EAEhB,MAAM,gCAAgC,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAYlE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAQrD,UAAU,KAAK;IACb,MAAM,EAAE,cAAc,CAAC;IACvB,oEAAoE;IACpE,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,+EAA+E;IAC/E,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,eAAe,GAAG,IAAI,GAAG,SAAS,CAAC;IACtD,qBAAqB,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,IAAI,CAAC;IACzD,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACtD,gFAAgF;IAChF,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;QAC9B,MAAM,EAAE,MAAM,CAAC;KAChB,KAAK,IAAI,CAAC;IACX,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,iGAAiG;IACjG,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAClC,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,0DAA0D;IAC1D,MAAM,CAAC,EAAE,OAAO,QAAQ,EAAE,OAAO,CAAC;IAClC,OAAO,CAAC,EAAE,OAAO,QAAQ,EAAE,OAAO,CAAC;IACnC,+DAA+D;IAC/D,KAAK,CAAC,EAAE,OAAO,QAAQ,EAAE,OAAO,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA8MH,QAAA,MAAM,SAAS,2CAAwC,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}

package/dist/components/Welcome.svelte

@@ -0,0 +1,99 @@
+<!--
+  @component
+  The default empty conversation: a greeting, a capability line and starter suggestions.
+  `AgentChat` renders it unless the host passes its own `empty` snippet.
+-->
+<script lang="ts">
+  import { cn, Icon } from '@classic-homes/theme-svelte';
+  import { greeting, suggestionText, type WelcomeSuggestion } from '../welcome.js';
+
+  interface Props {
+    /** The user's name; only the first word is shown. */
+    name?: string | null;
+    /** Replaces the time-of-day greeting. */
+    title?: string;
+    description?: string;
+    suggestions?: WelcomeSuggestion[];
+    /** Compact single-column layout for the side panel. */
+    compact?: boolean;
+    disabled?: boolean;
+    onselect?: (text: string, suggestion: WelcomeSuggestion) => void;
+    class?: string;
+  }
+  let {
+    name,
+    title,
+    description = 'Ask about homes, lots, documents and company data, or attach a file to work from it.',
+    suggestions = [],
+    compact = false,
+    disabled = false,
+    onselect,
+    class: className,
+  }: Props = $props();
+
+  const headingId = $props.id();
+  const heading = $derived(title ?? greeting(name));
+  const shown = $derived(suggestions.filter((s) => suggestionText(s)).slice(0, 4));
+</script>
+
+<section
+  class={cn(
+    'm-auto flex w-full flex-col items-center px-4 text-center motion-safe:animate-fade-in',
+    compact ? 'max-w-sm gap-4 py-6' : 'max-w-2xl gap-6 py-10',
+    className,
+  )}
+  aria-labelledby={headingId}
+  data-agent-welcome
+>
+  <div class="flex flex-col items-center gap-3">
+    <span
+      class={cn(
+        'inline-flex items-center justify-center rounded-full bg-primary/10 text-primary',
+        compact ? 'size-10' : 'size-12',
+      )}
+      aria-hidden="true"
+    >
+      <Icon name="sparkles" size={compact ? 20 : 24} />
+    </span>
+    <h2
+      id={headingId}
+      class={cn('font-semibold tracking-tight text-foreground', compact ? 'text-lg' : 'text-2xl')}
+    >
+      {heading}
+    </h2>
+    {#if description}
+      <p class="max-w-md text-sm text-muted-foreground">{description}</p>
+    {/if}
+  </div>
+  {#if shown.length}
+    <ul
+      class={cn('grid w-full gap-2 text-left', !compact && 'sm:grid-cols-2')}
+      aria-label="Suggestions"
+    >
+      {#each shown as suggestion (suggestion.id ?? suggestion.label)}
+        <li class="flex">
+          <button
+            type="button"
+            class="group flex w-full items-start gap-3 rounded-lg border border-border bg-background p-3 text-left text-sm transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50"
+            {disabled}
+            onclick={() => onselect?.(suggestionText(suggestion), suggestion)}
+          >
+            <Icon
+              name={suggestion.icon ?? 'message-square'}
+              size={16}
+              class="mt-0.5 shrink-0 text-muted-foreground group-hover:text-foreground"
+            />
+            <span class="min-w-0">
+              <span class="block font-medium text-foreground">{suggestion.label}</span>
+              {#if suggestion.description}
+                <span class="mt-0.5 block text-xs text-muted-foreground"
+                  >{suggestion.description}</span
+                >
+              {/if}
+            </span>
+          </button>
+        </li>
+      {/each}
+    </ul>
+  {/if}
+</section>

package/dist/components/Welcome.svelte.d.ts

@@ -0,0 +1,22 @@
+import { type WelcomeSuggestion } from '../welcome.js';
+interface Props {
+    /** The user's name; only the first word is shown. */
+    name?: string | null;
+    /** Replaces the time-of-day greeting. */
+    title?: string;
+    description?: string;
+    suggestions?: WelcomeSuggestion[];
+    /** Compact single-column layout for the side panel. */
+    compact?: boolean;
+    disabled?: boolean;
+    onselect?: (text: string, suggestion: WelcomeSuggestion) => void;
+    class?: string;
+}
+/**
+ * The default empty conversation: a greeting, a capability line and starter suggestions.
+ * `AgentChat` renders it unless the host passes its own `empty` snippet.
+ */
+declare const Welcome: import("svelte").Component<Props, {}, "">;
+type Welcome = ReturnType<typeof Welcome>;
+export default Welcome;
+//# sourceMappingURL=Welcome.svelte.d.ts.map

package/dist/components/Welcome.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Welcome.svelte.d.ts","sourceRoot":"","sources":["../../src/lib/components/Welcome.svelte.ts"],"names":[],"mappings":"AAIA,OAAO,EAA4B,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAG/E,UAAU,KAAK;IACb,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAClC,uDAAuD;IACvD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA8DH;;;GAGG;AACH,QAAA,MAAM,OAAO,2CAAwC,CAAC;AACtD,KAAK,OAAO,GAAG,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC;AAC1C,eAAe,OAAO,CAAC"}

package/dist/components/welcome.svelte.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=welcome.svelte.test.d.ts.map

package/dist/components/welcome.svelte.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"welcome.svelte.test.d.ts","sourceRoot":"","sources":["../../src/lib/components/welcome.svelte.test.ts"],"names":[],"mappings":""}

package/dist/components/welcome.svelte.test.js

@@ -0,0 +1,119 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render, screen, waitFor } from '@testing-library/svelte';
+import userEvent from '@testing-library/user-event';
+import { greeting, suggestionText } from '../welcome.js';
+import AgentChat from './AgentChat.svelte';
+import Welcome from './Welcome.svelte';
+afterEach(() => cleanup());
+function fakeClient(getConversation = vi.fn()) {
+    return {
+        fileUrl: (id) => `#${id}`,
+        uploadFile: vi.fn(),
+        cancel: vi.fn(),
+        getConversation,
+        resumeTurn: vi.fn(),
+        streamChat: vi.fn(async (req, opts) => {
+            [
+                { type: 'start', conversationId: 'c-1', mode: 'live' },
+                { type: 'delta', text: 'Sure.' },
+                { type: 'done', finishReason: 'stop' },
+            ].forEach((e, seq) => opts.onEvent({ requestId: req.requestId, seq, ...e }));
+            return { kind: 'done' };
+        }),
+    };
+}
+const base = { sandboxOrigin: 'https://frame.test' };
+describe('welcome helpers', () => {
+    it('greets by the time of day and the first name only', () => {
+        expect(greeting('Pat Lee', new Date(2026, 10, 4, 9))).toBe('Good morning, Pat');
+        expect(greeting(undefined, new Date(2026, 10, 4, 14))).toBe('Good afternoon');
+        expect(greeting('  ', new Date(2026, 10, 4, 20))).toBe('Good evening');
+        expect(greeting('Sam', new Date(2026, 10, 4, 2))).toBe('Good evening, Sam');
+    });
+    it('sends the text, or the label without one', () => {
+        expect(suggestionText({ label: 'Open lots' })).toBe('Open lots');
+        expect(suggestionText({ label: 'Lots', text: ' List open lots ' })).toBe('List open lots');
+    });
+});
+describe('Welcome', () => {
+    it('shows at most four suggestions and reports the chosen one', async () => {
+        const onselect = vi.fn();
+        render(Welcome, {
+            props: {
+                name: 'Pat',
+                title: 'Hi Pat',
+                onselect,
+                suggestions: ['A', 'B', 'C', 'D', 'E'].map((label) => ({ label, text: `Do ${label}` })),
+            },
+        });
+        expect(screen.getByRole('heading', { name: 'Hi Pat' })).toBeTruthy();
+        const list = screen.getByRole('list', { name: 'Suggestions' });
+        expect(list.querySelectorAll('button')).toHaveLength(4);
+        await userEvent.click(screen.getByRole('button', { name: 'B' }));
+        expect(onselect).toHaveBeenCalledWith('Do B', expect.objectContaining({ label: 'B' }));
+    });
+});
+describe('AgentChat empty states', () => {
+    it('welcomes a new chat and sends a chosen suggestion', async () => {
+        const client = fakeClient();
+        render(AgentChat, {
+            props: {
+                ...base,
+                client: client,
+                userName: 'Pat Lee',
+                suggestions: [{ label: 'Open lots', text: 'List the open lots' }],
+            },
+        });
+        expect(screen.getByRole('heading', { name: /, Pat$/ })).toBeTruthy();
+        await userEvent.click(screen.getByRole('button', { name: 'Open lots' }));
+        await waitFor(() => expect(client.streamChat).toHaveBeenCalledOnce());
+        expect(client.streamChat.mock.calls[0][0]).toMatchObject({ message: 'List the open lots' });
+        expect((await screen.findAllByText('Sure.')).length).toBeGreaterThan(0);
+        expect(document.querySelector('[data-agent-welcome]')).toBeNull();
+    });
+    it('shows a skeleton, not the welcome, while a conversation loads', async () => {
+        let resolve;
+        const client = fakeClient(vi.fn(() => new Promise((r) => (resolve = r))));
+        render(AgentChat, { props: { ...base, client: client, conversationId: 'c-9' } });
+        expect(document.querySelector('[data-agent-loading]')).toBeTruthy();
+        expect(document.querySelector('[data-agent-welcome]')).toBeNull();
+        resolve({
+            conversation: { conversationId: 'c-9', activeRequestId: null },
+            messages: [
+                {
+                    id: 'u-1',
+                    role: 'user',
+                    content: [{ type: 'text', text: 'Earlier question' }],
+                    createdAt: Date.now(),
+                },
+            ],
+        });
+        expect(await screen.findByText('Earlier question')).toBeTruthy();
+        expect(document.querySelector('[data-agent-loading]')).toBeNull();
+    });
+    it('explains a failed load and retries it', async () => {
+        const getConversation = vi
+            .fn()
+            .mockRejectedValueOnce(new Error('Network down'))
+            .mockResolvedValueOnce({
+            conversation: { conversationId: 'c-9', activeRequestId: null },
+            messages: [],
+        });
+        render(AgentChat, {
+            props: { ...base, client: fakeClient(getConversation), conversationId: 'c-9' },
+        });
+        expect(await screen.findByText('Could not load this conversation.')).toBeTruthy();
+        expect(document.querySelector('[data-agent-welcome]')).toBeNull();
+        // No automatic retry loop.
+        await new Promise((r) => setTimeout(r, 50));
+        expect(getConversation).toHaveBeenCalledOnce();
+        await userEvent.click(screen.getByRole('button', { name: /Try again/ }));
+        await waitFor(() => expect(getConversation).toHaveBeenCalledTimes(2));
+        await waitFor(() => expect(screen.queryByText('Could not load this conversation.')).toBeNull());
+        expect(document.querySelector('[data-agent-welcome]')).toBeTruthy();
+    });
+    it('renders the welcome when the host gives no empty snippet', () => {
+        render(AgentChat, { props: { ...base, client: fakeClient() } });
+        expect(document.querySelector('[data-agent-welcome]')).toBeTruthy();
+    });
+});

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export * from './message-format.js';
 export * from './reducer.js';
 export * from './session.svelte.js';
 export * from './ui-frame-protocol.js';
+export * from './welcome.js';
 export { default as AgentChat } from './components/AgentChat.svelte';
 export { default as ArtifactPanel } from './components/ArtifactPanel.svelte';
 export { default as Composer } from './components/Composer.svelte';
@@ -22,4 +23,5 @@ export { default as MessageActions } from './components/MessageActions.svelte';
 export { default as ArtifactChip } from './components/ArtifactChip.svelte';
 export { default as MessageFiles } from './components/MessageFiles.svelte';
 export { default as ProposalCard } from './components/ProposalCard.svelte';
+export { default as Welcome } from './components/Welcome.svelte';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/lib/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAC7E,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AACzF,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AACnF,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAC/E,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,kCAAkC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/lib/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAC7E,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AACzF,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AACnF,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAC/E,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/index.js

@@ -6,6 +6,7 @@ export * from './message-format.js';
 export * from './reducer.js';
 export * from './session.svelte.js';
 export * from './ui-frame-protocol.js';
+export * from './welcome.js';
 export { default as AgentChat } from './components/AgentChat.svelte';
 export { default as ArtifactPanel } from './components/ArtifactPanel.svelte';
 export { default as Composer } from './components/Composer.svelte';
@@ -22,3 +23,4 @@ export { default as MessageActions } from './components/MessageActions.svelte';
 export { default as ArtifactChip } from './components/ArtifactChip.svelte';
 export { default as MessageFiles } from './components/MessageFiles.svelte';
 export { default as ProposalCard } from './components/ProposalCard.svelte';
+export { default as Welcome } from './components/Welcome.svelte';

package/dist/welcome.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Helpers for the empty conversation: greeting and suggestion types.
+ */
+import type { IconName } from '@classic-homes/theme-svelte';
+/** A starter offered on an empty conversation. */
+export interface WelcomeSuggestion {
+    /** Stable key; defaults to the label. */
+    id?: string;
+    /** Short card title, e.g. "Summarize this lot". */
+    label: string;
+    /** One line under the label. */
+    description?: string;
+    /** Message sent when the card is chosen (defaults to the label). */
+    text?: string;
+    icon?: IconName;
+}
+/** The text a suggestion sends. */
+export declare function suggestionText(s: WelcomeSuggestion): string;
+/** "Good morning, Pat" by the local hour; without a name, "Good morning". */
+export declare function greeting(name?: string | null, now?: Date): string;
+//# sourceMappingURL=welcome.d.ts.map

package/dist/welcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"welcome.d.ts","sourceRoot":"","sources":["../src/lib/welcome.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAE5D,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED,mCAAmC;AACnC,wBAAgB,cAAc,CAAC,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAE3D;AAED,6EAA6E;AAC7E,wBAAgB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,GAAE,IAAiB,GAAG,MAAM,CAK7E"}

package/dist/welcome.js

@@ -0,0 +1,11 @@
+/** The text a suggestion sends. */
+export function suggestionText(s) {
+    return (s.text ?? s.label).trim();
+}
+/** "Good morning, Pat" by the local hour; without a name, "Good morning". */
+export function greeting(name, now = new Date()) {
+    const hour = now.getHours();
+    const part = hour < 5 ? 'evening' : hour < 12 ? 'morning' : hour < 18 ? 'afternoon' : 'evening';
+    const first = name?.trim().split(/\s+/)[0];
+    return first ? `Good ${part}, ${first}` : `Good ${part}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classic-homes/agent-chat",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "private": false,
   "type": "module",
   "description": "Svelte 5 chat UI for Classic Agent: session state, message list, composer, tool timeline, artifacts and MCP-UI sandbox frames. Consumed by the Classic App.",
@@ -17,8 +17,8 @@
     "dist"
   ],
   "dependencies": {
-    "@classic-homes/agent-client": "0.4.1",
-    "@classic-homes/agent-contracts": "0.4.1",
+    "@classic-homes/agent-client": "0.5.0",
+    "@classic-homes/agent-contracts": "0.5.0",
     "dompurify": "3.4.17"
   },
   "peerDependencies": {