@wpic/ui 0.3.5

package/src/components/chat/LLM_STREAMING.md

@@ -0,0 +1,390 @@
+# Chat LLM streaming guide
+
+Use this when implementing the backend call behind `WChatPanel`. The UI component does not call providers directly; the host app must provide an authenticated chat endpoint.
+
+This guide is based on the working WPIC Perform chat flow:
+
+- `frontend/src/components/ChatPanel.vue`
+- `routes/chat.py`
+- DeepSeek `/v1/chat/completions`
+- SSE response shape compatible with OpenAI chat-completions streams
+- optional tool events in the same SSE stream
+- usage reporting at the end of the stream
+
+## Recommended transport
+
+Use Server-Sent Events for rich chat streams:
+
+```http
+Content-Type: text/event-stream
+Cache-Control: no-cache
+X-Accel-Buffering: no
+```
+
+Each event is sent as:
+
+```text
+data: {"choices":[{"delta":{"content":"hello"},"finish_reason":null}]}
+
+data: {"usage":{"prompt_tokens":123,"completion_tokens":45}}
+
+data: {"tools_used":["search_products"]}
+
+data: {"app_event":{"type":"navigate","path":"/campaigns"}}
+
+data: [DONE]
+
+```
+
+Plain text streaming is acceptable for a minimal MVP, but SSE is better once you need usage, tool calls, navigation, choices, error payloads, or structured events.
+
+## Frontend SSE parser
+
+Use `AbortController` for cancel. Keep one stable assistant placeholder and append deltas into it.
+
+```ts
+let abortController: AbortController | null = null
+
+async function sendChat(input: {
+  endpoint: string
+  messages: Array<{ role: 'user' | 'assistant'; content: string }>
+  context?: Record<string, unknown>
+  token?: string
+  onDelta: (text: string) => void
+  onUsage?: (usage: { prompt_tokens?: number; completion_tokens?: number }) => void
+  onToolEvent?: (event: unknown) => void
+  onToolsUsed?: (tools: string[]) => void
+}) {
+  abortController = new AbortController()
+  const res = await fetch(input.endpoint, {
+    method: 'POST',
+    signal: abortController.signal,
+    headers: {
+      'Content-Type': 'application/json',
+      ...(input.token ? { Authorization: `Bearer ${input.token}` } : {}),
+    },
+    body: JSON.stringify({
+      messages: input.messages,
+      context: input.context ?? {},
+    }),
+  })
+
+  if (!res.ok || !res.body) {
+    throw new Error(`Chat request failed: HTTP ${res.status}`)
+  }
+
+  const reader = res.body.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ''
+
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    buffer += decoder.decode(value, { stream: true })
+
+    const lines = buffer.split('\n')
+    buffer = lines.pop() ?? ''
+
+    for (const line of lines) {
+      if (!line.startsWith('data: ')) continue
+      const payload = line.slice(6).trim()
+      if (!payload) continue
+      if (payload === '[DONE]') return
+
+      let event: any
+      try {
+        event = JSON.parse(payload)
+      } catch {
+        continue
+      }
+
+      if (event.usage) {
+        input.onUsage?.(event.usage)
+        continue
+      }
+      if (event.tools_used?.length) {
+        input.onToolsUsed?.(event.tools_used)
+        continue
+      }
+      if (event.app_event || event.webber_event) {
+        input.onToolEvent?.(event.app_event ?? event.webber_event)
+        continue
+      }
+
+      const delta = event.choices?.[0]?.delta?.content
+      if (delta) input.onDelta(delta)
+    }
+  }
+}
+
+function cancelChat() {
+  abortController?.abort()
+  abortController = null
+}
+```
+
+## Frontend send checklist
+
+- Reject send while a stream is active.
+- Create session first if the app uses persisted sessions.
+- Push the user message immediately.
+- Push an empty assistant placeholder immediately after.
+- Store the placeholder object or index before streaming starts.
+- Clear input before the network call.
+- Pass only the last N messages unless the backend loads history from DB.
+- Use `AbortController` and expose a Cancel or Stop action.
+- Treat `AbortError` as cancelled, not as a provider failure.
+- Mark the placeholder as non-streaming in `finally`.
+- If no content arrived, show an empty-response message.
+- Scroll to bottom on each delta.
+
+## Backend request shape
+
+Keep the host-app endpoint small and explicit:
+
+```ts
+type ChatRequest = {
+  messages: Array<{
+    role: 'user' | 'assistant'
+    content: string
+    attachments?: Array<{ name: string; content: string; mime_type?: string }>
+  }>
+  context?: Record<string, unknown>
+  session_id?: string | number | null
+}
+```
+
+Backend responsibilities:
+
+- authenticate the user
+- resolve organization / workspace
+- load conversation history if `session_id` is provided
+- load relevant product/domain context
+- build one system prompt
+- call the LLM provider with streaming enabled
+- forward deltas as SSE
+- execute tool calls when needed
+- emit app events for navigation or refresh
+- save final user and assistant messages after successful completion
+- write usage counters
+- avoid saving internal trigger messages
+
+## Next.js route example
+
+This example streams OpenAI-compatible chunks and emits plain content deltas as SSE.
+
+```ts
+export const runtime = 'nodejs'
+export const dynamic = 'force-dynamic'
+
+export async function POST(req: Request) {
+  const body = await req.json()
+  const messages = body.messages ?? []
+
+  const upstream = await fetch('https://api.openai.com/v1/chat/completions', {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
+    },
+    body: JSON.stringify({
+      model: process.env.CHAT_MODEL ?? 'gpt-4.1-mini',
+      stream: true,
+      stream_options: { include_usage: true },
+      messages: [
+        { role: 'system', content: 'You are the app assistant.' },
+        ...messages,
+      ],
+    }),
+  })
+
+  if (!upstream.ok || !upstream.body) {
+    const text = await upstream.text().catch(() => upstream.statusText)
+    return Response.json({ error: 'chat_provider_error', detail: text.slice(0, 500) }, { status: 502 })
+  }
+
+  const encoder = new TextEncoder()
+  const decoder = new TextDecoder()
+  let buffer = ''
+
+  const stream = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const reader = upstream.body!.getReader()
+      try {
+        for (;;) {
+          const { done, value } = await reader.read()
+          if (done) break
+          buffer += decoder.decode(value, { stream: true })
+          const lines = buffer.split('\n')
+          buffer = lines.pop() ?? ''
+
+          for (const line of lines) {
+            if (!line.startsWith('data:')) continue
+            const data = line.slice(5).trim()
+            if (!data || data === '[DONE]') continue
+
+            const chunk = JSON.parse(data)
+            const usage = chunk.usage
+            if (usage) {
+              controller.enqueue(encoder.encode(`data: ${JSON.stringify({ usage })}\n\n`))
+              continue
+            }
+
+            const delta = chunk.choices?.[0]?.delta?.content
+            if (delta) {
+              controller.enqueue(encoder.encode(`data: ${JSON.stringify({
+                choices: [{ delta: { content: delta }, finish_reason: null }],
+              })}\n\n`))
+            }
+          }
+        }
+        controller.enqueue(encoder.encode('data: [DONE]\n\n'))
+        controller.close()
+      } catch (error) {
+        controller.error(error)
+      } finally {
+        reader.releaseLock()
+      }
+    },
+  })
+
+  return new Response(stream, {
+    headers: {
+      'content-type': 'text/event-stream',
+      'cache-control': 'no-cache',
+      'x-accel-buffering': 'no',
+    },
+  })
+}
+```
+
+## FastAPI + DeepSeek pattern from Perform
+
+Perform calls DeepSeek with OpenAI-compatible chat completions:
+
+```py
+payload = {
+    "model": DEEPSEEK_MODEL,
+    "messages": current_msgs,
+    "tools": TOOLS,
+    "tool_choice": "auto",
+    "max_tokens": 2048,
+    "stream": True,
+    "stream_options": {"include_usage": True},
+}
+
+async with client.stream("POST", url, json=payload, headers=headers_ds) as resp:
+    async for line in resp.aiter_lines():
+        if not line or not line.startswith("data: "):
+            continue
+        data_str = line[6:].strip()
+        if data_str == "[DONE]":
+            continue
+        chunk = json.loads(data_str)
+```
+
+Forward content deltas immediately:
+
+```py
+if delta.get("content"):
+    full_content += delta["content"]
+    if not tool_calls_raw:
+        yield f"data: {json.dumps({'choices': [{'delta': {'content': delta['content']}, 'finish_reason': None}]})}\n\n"
+```
+
+Accumulate streamed tool calls instead of executing partial arguments:
+
+```py
+for tc in delta.get("tool_calls", []):
+    idx = tc.get("index", 0)
+    if idx not in tool_calls_raw:
+        tool_calls_raw[idx] = {"id": "", "type": "function", "function": {"name": "", "arguments": ""}}
+    if tc.get("id"):
+        tool_calls_raw[idx]["id"] = tc["id"]
+    if tc.get("function", {}).get("name"):
+        tool_calls_raw[idx]["function"]["name"] += tc["function"]["name"]
+    if tc.get("function", {}).get("arguments"):
+        tool_calls_raw[idx]["function"]["arguments"] += tc["function"]["arguments"]
+```
+
+When `finish_reason == "tool_calls"`, execute tools, append tool results to `current_msgs`, emit app events if needed, then run another provider round. Keep a hard round cap such as `8`.
+
+At the end:
+
+```py
+yield f"data: {json.dumps({'choices': [{'delta': {}, 'finish_reason': 'stop'}]})}\n\n"
+yield f"data: {json.dumps({'usage': usage_data})}\n\n"
+if tools_used:
+    yield f"data: {json.dumps({'tools_used': list(dict.fromkeys(tools_used))})}\n\n"
+yield "data: [DONE]\n\n"
+```
+
+Use:
+
+```py
+return StreamingResponse(
+    stream_response(),
+    media_type="text/event-stream",
+    headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+)
+```
+
+## Tool-event guidance
+
+Do not make the chat UI know app-specific tools. Emit structured events and let the host wrapper handle them.
+
+Examples:
+
+```json
+{"app_event":{"type":"navigate","path":"/campaigns"}}
+{"app_event":{"type":"refresh","resource":"campaigns"}}
+{"app_event":{"type":"ask_choices","question":"Which client?","choices":["A","B"]}}
+```
+
+The wrapper can route, refresh stores, or render choice buttons.
+
+## Cancellation
+
+Client cancel:
+
+- call `AbortController.abort()`
+- mark the assistant placeholder as cancelled
+- set `streaming=false`
+
+Server cancel:
+
+- most frameworks stop the response generator when the client disconnects
+- avoid saving incomplete assistant messages unless the product wants partial history
+- wrap stream loops in `try/finally`
+- release readers and close provider clients
+
+For expensive tool calls, check disconnect signals where the framework supports it.
+
+## Persistence timing
+
+Save messages after the final assistant text is known. Perform saves:
+
+- user row with input token count
+- assistant row with output token count
+- session `updated_at`
+- daily user usage
+
+Do not save:
+
+- internal trigger messages
+- empty assistant responses
+- cancelled responses unless explicitly desired
+- import/ephemeral reviews when the product says they are not saved
+
+See `DB_SCHEMA.md` for table patterns.
+
+## Provider notes
+
+OpenAI-compatible providers differ in details:
+
+- DeepSeek: `/v1/chat/completions`, streamed tool calls, usage with `stream_options.include_usage`.
+- OpenAI chat completions: similar SSE shape.
+- OpenAI Responses API: different event schema; adapt parser or normalize server-side into the SSE shape above.
+- Anthropic Messages: different event schema; normalize server-side if using `WChatPanel`.
+
+Best practice: normalize every provider to one app SSE contract before it reaches the UI.

package/src/components/chat/UI_INTEGRATION.md

@@ -0,0 +1,273 @@
+# WChatPanel app integration guide
+
+Use this when adding the shared chat UI to an existing Vue app. The component lives at `src/components/WChatPanel.vue` and is exported as `WChatPanel` from `@wpic/ui`.
+
+## What this component owns
+
+`WChatPanel` is presentation plus panel interaction only:
+
+- message rendering
+- prompt input
+- send / clear / new / close buttons
+- copy assistant message
+- project and conversation navigator UI
+- selected project/session highlighting
+- floating mode
+- drag to move
+- resize from edges and corners
+- dock / undock toggle
+
+It does not own:
+
+- auth headers
+- LLM calls
+- SSE parsing
+- persistence
+- conversation/session/project storage or APIs
+- app layout resizing
+- tool events or navigation events
+
+Keep those in the host app.
+
+## Typography rule
+
+Do not add random text-size classes to chat UI. WPIC apps set `html/body` to 13px, so the normal inherited size is correct. Prefer no text-size class, or `text-base` only when an explicit class is required. Avoid `text-sm`, `text-xs`, `text-lg`, arbitrary `text-[...]`, and inline `font-size` unless the design system explicitly calls for it.
+
+## Minimal store
+
+Create a host-app store that persists panel and message state. Example:
+
+```ts
+import { defineStore } from 'pinia'
+import { ref, watch } from 'vue'
+import type { WChatMessage } from '@wpic/ui'
+
+const KEY = 'app-chat'
+
+type StoredChat = {
+  open?: boolean
+  docked?: boolean
+  width?: number
+  height?: number
+  x?: number
+  y?: number
+  messages?: WChatMessage[]
+}
+
+function loadStored(): StoredChat {
+  try {
+    return JSON.parse(localStorage.getItem(KEY) ?? '{}') as StoredChat
+  } catch {
+    return {}
+  }
+}
+
+export const useChatStore = defineStore('chat', () => {
+  const stored = loadStored()
+  const open = ref(stored.open ?? false)
+  const docked = ref(stored.docked ?? false)
+  const width = ref(stored.width ?? 420)
+  const height = ref(stored.height ?? 560)
+  const x = ref(stored.x ?? -1)
+  const y = ref(stored.y ?? -1)
+  const input = ref('')
+  const messages = ref<WChatMessage[]>(stored.messages ?? [])
+
+  function toggle() { open.value = !open.value }
+  function close() { open.value = false }
+  function startNew() {
+    messages.value = []
+    input.value = ''
+    open.value = true
+  }
+  function clear() { messages.value = [] }
+
+  watch([open, docked, width, height, x, y, messages], () => {
+    localStorage.setItem(KEY, JSON.stringify({
+      open: open.value,
+      docked: docked.value,
+      width: width.value,
+      height: height.value,
+      x: x.value,
+      y: y.value,
+      messages: messages.value.slice(-30),
+    }))
+  }, { deep: true })
+
+  return { open, docked, width, height, x, y, input, messages, toggle, close, startNew, clear }
+})
+```
+
+Use DB-backed persistence instead of `localStorage` when conversations must survive devices, support admin history, or show session/project lists. See `DB_SCHEMA.md`.
+
+## Projects and conversations
+
+`WChatPanel` can render projects and conversations, but the host app owns the data. Pass `projects`, `sessions`, `selectedProjectId`, and `selectedSessionId`, then handle these events:
+
+- `select-project`
+- `select-session`
+- `new-project`
+- `new-conversation`
+- `rename-project`
+- `rename-session`
+- `delete-project`
+- `delete-session`
+
+Use `WChatProject` and `WChatSession` from `@wpic/ui` for the shared shape. Keep app-specific fields in your DB `metadata` or in the host store, then map them into the shared UI types.
+
+## Minimal wrapper component
+
+Make an app wrapper around `WChatPanel`. The wrapper is where the app calls its own chat endpoint.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { useRoute } from 'vue-router'
+import { WChatPanel, type WChatMessage } from '@wpic/ui'
+import { useChatStore } from '@/stores/chat'
+import { apiFetch } from '@/lib/api'
+
+const chat = useChatStore()
+const route = useRoute()
+const loading = ref(false)
+let abortController: AbortController | null = null
+
+function id() {
+  return `${Date.now()}-${Math.random().toString(16).slice(2)}`
+}
+
+async function send(value: string) {
+  const prompt = value.trim()
+  if (!prompt || loading.value) return
+
+  chat.input = ''
+  chat.messages.push({ id: id(), role: 'user', content: prompt })
+  const assistant: WChatMessage = { id: id(), role: 'assistant', content: '', streaming: true }
+  chat.messages.push(assistant)
+  loading.value = true
+  abortController = new AbortController()
+
+  try {
+    const res = await apiFetch('/api/chat', {
+      method: 'POST',
+      signal: abortController.signal,
+      body: JSON.stringify({
+        messages: chat.messages
+          .filter((m) => m.role === 'user' || m.role === 'assistant')
+          .filter((m) => m.content.trim())
+          .slice(-12)
+          .map(({ role, content }) => ({ role, content })),
+        context: { route: route.fullPath },
+      }),
+    })
+
+    if (!res.ok || !res.body) throw new Error(`HTTP ${res.status}`)
+    await readTextStream(res, (delta) => { assistant.content += delta })
+    assistant.content = assistant.content.trim() || 'Empty response. Please try again.'
+  } catch (error) {
+    assistant.error = true
+    assistant.content = abortController?.signal.aborted
+      ? 'Cancelled.'
+      : error instanceof Error ? error.message : 'Connection error.'
+  } finally {
+    assistant.streaming = false
+    loading.value = false
+    abortController = null
+  }
+}
+
+function cancel() {
+  abortController?.abort()
+}
+
+async function readTextStream(res: Response, onDelta: (delta: string) => void) {
+  const reader = res.body!.getReader()
+  const decoder = new TextDecoder()
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    onDelta(decoder.decode(value, { stream: true }))
+  }
+}
+</script>
+
+<template>
+  <WChatPanel
+    v-model="chat.input"
+    v-model:docked="chat.docked"
+    v-model:width="chat.width"
+    v-model:height="chat.height"
+    v-model:x="chat.x"
+    v-model:y="chat.y"
+    :open="chat.open"
+    :messages="chat.messages"
+    :loading="loading"
+    title="Chat"
+    subtitle="Assistant"
+    placeholder="Ask anything..."
+    @close="chat.close"
+    @new="chat.startNew"
+    @clear="chat.clear"
+    @send="send"
+  />
+</template>
+```
+
+If the endpoint returns SSE instead of plain text chunks, use the parser pattern in `LLM_STREAMING.md`.
+
+## Docking like Claude browser
+
+The component positions itself when `docked=true`, but the host app must reserve layout space. Do this at the app shell/root, not only inside the main content area, so the topbar, nav, and page all stop before the chat column.
+
+```vue
+<template>
+  <div
+    class="flex h-dvh flex-col overflow-hidden transition-[padding] duration-150"
+    :style="{ paddingRight: chat.open && chat.docked ? `${chat.width}px` : undefined }"
+  >
+    <TopBar />
+    <div class="flex flex-1 overflow-hidden">
+      <NavBar />
+      <main class="min-w-0 flex-1 overflow-y-auto">
+        <RouterView />
+      </main>
+    </div>
+
+    <AppChatPanel />
+  </div>
+</template>
+```
+
+For a topbar-inside-app layout, pass `topOffset=0` when docked so the chat fills the full right edge. For floating mode, pass the topbar height as `topOffset` if the panel should not overlap the topbar.
+
+```vue
+<WChatPanel :top-offset="chat.docked ? 0 : 48" />
+```
+
+## Topbar trigger
+
+Use an icon button in the topbar and mark it active when open.
+
+```vue
+<WButton
+  variant="secondary"
+  size="sm"
+  :icon="MessageCircle"
+  :active="chat.open"
+  title="Chat"
+  @click="chat.toggle"
+/>
+```
+
+## Interaction checklist
+
+- Persist `open`, `docked`, `width`, `height`, `x`, `y`.
+- In docked mode, reserve `padding-right` on the app shell.
+- In floating mode, allow drag and resize.
+- Keep `Enter` to send and `Shift+Enter` for newline.
+- Focus the textarea when opening the panel.
+- Keep the latest assistant placeholder stable while streaming.
+- Provide a cancel path with `AbortController`.
+- Make failed or cancelled assistant messages visibly different.
+- Do not put app-specific API logic into `WChatPanel`.
+- Do not add arbitrary chat font-size classes.