feat: greeting messages — first-class welcome UI for chat

[gadenbuie]

Closes #217

Summary

Adds native greeting messages as a first-class feature in shinychat. Greetings are a distinct UI element — separate from the conversation message stream — that welcome users when the chat loads and can include suggestion cards.

Screen.Recording.2026-05-15.at.8.42.05.AM.mov

Content paths

• Static: chat_ui(greeting = "## Welcome!") — renders immediately on mount
• Dynamic: chat_set_greeting() / Chat.set_greeting() with computed or streamed content
• Generated: server listens for <id>_greeting_requested and streams an LLM-generated greeting

Key design decisions

• Stand-alone visual: greetings are centered, styled separately from assistant messages, with their own entrance/dismiss animations
• Dismissible by default: greeting fades out on first user message; reappears if chat is cleared
• greeting_requested input: a state-driven Shiny input that fires when the chat is visible, empty, and has no greeting — handles init, clear, bookmark restore, and hidden-tab cases uniformly
• chat_clear(greeting=TRUE): clears both messages and greeting, naturally triggering greeting_requested for regeneration
• Module support (R): chat_mod_server(greeting=) accepts a static value or a function; functions are called automatically on init and after clear(greeting=TRUE), with optional client injection for one-arg functions

Protocol

Five new action types for the stand-alone greeting path: greeting, greeting_start, greeting_chunk, greeting_end, greeting_clear. Content flows through the same HAST markdown pipeline as regular messages.

What was dropped during implementation

• as_assistant_message — removed; authors who want assistant-styled welcomes use chat_append() directly
• include_in_history — removed; shinychat doesn't own model history

Verification

Set ANTHROPIC_API_KEY and run any of the example apps below. Things to verify:

• Greeting streams in on load with suggestion cards
• Clicking a suggestion fills the input
• Sending a message dismisses the greeting with a fade animation
• "Clear chat" re-shows the original greeting
• "Clear chat + greeting" regenerates a fresh greeting from the LLM

haiku_app.R — R with manual chat plumbing

library(shiny)
library(bslib)
library(shinychat)
library(ellmer)

MODEL <- "claude-haiku-4-5"

GREETING_PROMPT <- r"(
You generate short, friendly welcome greetings for a programming explainer app.
Respond with markdown only — no preamble, no closing remarks.

Use exactly this structure:

## <a brief, varied welcome heading>

<one inviting sentence about explaining programming and data science concepts>

**Try one of these:**

- <span class="suggestion">programming or data science topic 1</span>
- <span class="suggestion">programming or data science topic 2</span>
- <span class="suggestion">programming or data science topic 3</span>

Suggestions should be specific concepts like "What is a closure?",
"Explain tidy evaluation", "How does gradient descent work?", etc.
Vary the wording each time. Keep the entire greeting under 60 words.
)"

CHAT_PROMPT <- "You explain programming and data science concepts concisely in 1-2 sentences. Use markdown when appropriate."

ui <- page_fillable(
  card(
    card_header(
      "Haiku greeting demo (manual)",
      toolbar(
        align = "right",
        toolbar_input_button("clear_chat", "Clear chat", icon = icon("eraser")),
        toolbar_input_button(
          "clear_chat_and_greeting",
          "Clear chat + greeting",
          icon = icon("trash")
        )
      )
    ),
    chat_ui("chat", placeholder = "Ask me anything...", fill = TRUE)
  )
)

server <- function(input, output, session) {
  client <- ellmer::chat_anthropic(
    model = MODEL,
    system_prompt = CHAT_PROMPT,
    echo = "none"
  )

  observeEvent(input$chat_user_input, {
    stream <- client$stream_async(input$chat_user_input)
    chat_append("chat", stream)
  })

  # Fires when the chat is visible, empty, and has no greeting.
  observeEvent(input$chat_greeting_requested, {
    greeter <- ellmer::chat_anthropic(
      model = MODEL,
      system_prompt = GREETING_PROMPT,
      echo = "none"
    )
    stream <- greeter$stream_async("Generate a welcome greeting for the user.")
    chat_set_greeting("chat", chat_greeting(stream))
  })

  observeEvent(input$clear_chat, {
    chat_clear("chat")
  })

  observeEvent(input$clear_chat_and_greeting, {
    chat_clear("chat", greeting = TRUE)
  })
}

shinyApp(ui, server)

haiku_mod_app.R — R with chat_mod_server()

library(shiny)
library(bslib)
library(shinychat)
library(ellmer)

MODEL <- "claude-haiku-4-5"

GREETING_PROMPT <- r"(
You generate short, friendly welcome greetings for a programming explainer app.
Respond with markdown only — no preamble, no closing remarks.

Use exactly this structure:

## <a brief, varied welcome heading>

<one inviting sentence about explaining programming and data science concepts>

**Try one of these:**

- <span class="suggestion">programming or data science topic 1</span>
- <span class="suggestion">programming or data science topic 2</span>
- <span class="suggestion">programming or data science topic 3</span>

Suggestions should be specific concepts like "What is a closure?",
"Explain tidy evaluation", "How does gradient descent work?", etc.
Vary the wording each time. Keep the entire greeting under 60 words.
)"

CHAT_PROMPT <- "You explain programming and data science concepts concisely in 1-2 sentences. Use markdown when appropriate."

ui <- page_fillable(
  card(
    card_header(
      "Haiku greeting demo (module)",
      toolbar(
        align = "right",
        toolbar_input_button("clear_chat", "Clear chat", icon = icon("eraser")),
        toolbar_input_button(
          "clear_chat_and_greeting",
          "Clear chat + greeting",
          icon = icon("trash")
        )
      )
    ),
    chat_mod_ui("chat")
  )
)

server <- function(input, output, session) {
  client <- ellmer::chat_anthropic(
    model = MODEL,
    system_prompt = CHAT_PROMPT,
    echo = "none"
  )

  chat <- chat_mod_server("chat", client, greeting = function() {
    greeter <- ellmer::chat_anthropic(
      model = MODEL,
      system_prompt = GREETING_PROMPT,
      echo = "none"
    )
    greeter$stream_async("Generate a welcome greeting for the user.")
  })

  observeEvent(input$clear_chat, {
    chat$clear()
  })

  observeEvent(input$clear_chat_and_greeting, {
    chat$clear(greeting = TRUE)
  })
}

shinyApp(ui, server)

haiku_app.py — Python

"""
Live Haiku-powered greeting demo (Python).

Generates a fresh greeting via the state-driven `<id>_greeting_requested`
Shiny input. Set ANTHROPIC_API_KEY before running.

    uv run shiny run _dev/agents/greeting/haiku_app.py
"""

from chatlas import ChatAnthropic
from shiny import App, reactive, ui

from shinychat import Chat, chat_greeting, chat_ui

MODEL = "claude-haiku-4-5"

GREETING_PROMPT = """\
You generate short, friendly welcome greetings for a programming explainer app.
Respond with markdown only — no preamble, no closing remarks.

Use exactly this structure:

## <a brief, varied welcome heading>

<one inviting sentence about explaining programming and data science concepts>

**Try one of these:**

- <span class="suggestion">programming or data science topic 1</span>
- <span class="suggestion">programming or data science topic 2</span>
- <span class="suggestion">programming or data science topic 3</span>

Suggestions should be specific concepts like "What is a closure?",
"Explain tidy evaluation", "How does gradient descent work?", etc.
Vary the wording each time. Keep the entire greeting under 60 words.
"""

CHAT_PROMPT = (
    "You explain programming and data science concepts concisely "
    "in 1-2 sentences. Use markdown when appropriate."
)


app_ui = ui.page_fillable(
    ui.card(
        ui.card_header(
            "Haiku greeting demo (Python)",
            ui.toolbar(
                ui.toolbar_input_button("clear_chat", "Clear", tooltip="Clear chat"),
                ui.toolbar_input_button(
                    "clear_chat_and_greeting",
                    "Reset",
                    tooltip="Clear chat + greeting",
                ),
                align="right",
            ),
        ),
        chat_ui("chat", placeholder="Ask me anything...", fill=True),
    ),
)


def server(input, output, session):
    chat = Chat(id="chat")
    client = ChatAnthropic(model=MODEL, system_prompt=CHAT_PROMPT)

    @chat.on_user_submit
    async def _(user_input: str):
        stream = await client.stream_async(user_input)
        await chat.append_message_stream(stream)

    # Fires when the chat is visible, empty, and has no greeting.
    @reactive.effect
    @reactive.event(input.chat_greeting_requested)
    async def _generate_greeting():
        greeter = ChatAnthropic(model=MODEL, system_prompt=GREETING_PROMPT)
        stream = await greeter.stream_async("Generate a welcome greeting for the user.")
        await chat.set_greeting(chat_greeting(stream))

    @reactive.effect
    @reactive.event(input.clear_chat)
    async def _clear_chat():
        await chat.clear_messages()

    @reactive.effect
    @reactive.event(input.clear_chat_and_greeting)
    async def _clear_chat_and_greeting():
        await chat.clear_messages(greeting=True)


app = App(app_ui, server)

[cpsievert]

I noticed that set_greeting() is a silent no-op after the greeting has been dismissed — it updates the internal state but nothing visible changes until clear(greeting=TRUE) resets things (via computeGreetingVisibility in state.ts:142-150).

I think that makes sense as a design choice, but I could see someone calling set_greeting("Try asking about X\!") mid-conversation and being confused when nothing happens. Might be worth calling this out in the set_greeting() docstrings so people don't have to discover it through debugging.

[cpsievert]

The dismiss lifecycle uses three correlated booleans (visible, dismissed, dismissing) that have 8 possible combinations, most of which are invalid — the reducer has to be careful not to produce them. Would a single status: "visible" | "dismissing" | "dismissed" enum work here? It would make impossible states unrepresentable while keeping the same animation coordination. The layout-stability trick with [data-greeting-dismissing] and the centering CSS is clever — not suggesting changing any of that.

[cpsievert]

I think this means that HTML() will get treated like markdown.

[cpsievert]

I think this check is too narrow. In Python, a value can be a valid async stream for async for without being an AsyncIterator specifically. If that happens here, we will fall through into the non-stream path instead.

I think the fix here should be:

• widen the types from AsyncIterator to AsyncIterable
• update the runtime check accordingly, not just the annotation
• add a test with a custom async-iterable object, not just a native async generator

I would keep this scoped to async iterables only for this PR. Supporting sync iterables would be a separate feature expansion.