@flamingo-stack/openframe-frontend-core 0.0.488 → 0.0.489-snapshot.20260728173516

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.488",
+  "version": "0.0.489-snapshot.20260728173516",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/chat/chat-message-enhanced.tsx

@@ -11,6 +11,7 @@ import { ApprovalBatchMessage } from "./approval-batch-message"
 import { ErrorMessageDisplay } from "./error-message-display"
 import { ContextCompactionDisplay } from "./context-compaction-display"
 import { ThinkingDisplay } from "./thinking-display"
+import { GuideDisplay } from "./guide-display"
 import { SimpleMarkdownRenderer } from "../ui/simple-markdown-renderer"
 import type { ChatRef } from "./chat-ref.types"
 import { remarkCardLinks } from "./remark-card-links"
@@ -172,7 +173,12 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
       // duplicates so two siblings never collide on the same React key.
       const emittedBlockKeys = new Set<string>()
       segments.forEach((segment, segIdx) => {
-        if (segment.type !== 'text') return
+        // Both markdown-bearing segment types take part: a `guide` body is
+        // authored by the same LLM and carries the same `[card://]` markers,
+        // so skipping it here left its markers with no `inlineByKey` entry and
+        // no hoisted card — the `<a card://>` override silently degraded them
+        // to a bare title / id.
+        if (segment.type !== 'text' && segment.type !== 'guide') return
         const text = segment.text
         const parts: SegmentPart[] = []
         let cursor = 0
@@ -384,6 +390,52 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
       }
     }, [hasMarkerSupport, hasMentionSupport, renderMention, chatRefs, renderingPlan, NavLinkAnchor])
 
+    /**
+     * Body of a markdown-bearing segment (`text` / `guide`).
+     *
+     * No block markers in this segment → a single SimpleMarkdownRenderer call
+     * (the vast majority of messages). Otherwise the text is split at each
+     * marker and block payloads are interleaved: each text chunk includes its
+     * trailing marker so the inline pill renders at the right position via the
+     * `<a>` override, and block payloads land AS SIBLINGS between text chunks —
+     * HTML-valid (block DOM never nests inside `<p>`) AND positionally correct
+     * (the block appears where the marker is in the flow, not at the segment's
+     * end). Stable React keys come from the card key (block) and chunk position
+     * (text); streaming token-by-token reuses the same React instances so
+     * `<Video>` doesn't remount mid-play.
+     */
+    const renderSegmentBody = (segIndex: number, text: string) => {
+      const parts = renderingPlan?.partsBySegment.get(segIndex)
+      if (!parts || parts.length === 0) {
+        return (
+          <SimpleMarkdownRenderer
+            content={text}
+            textSize="compact"
+            additionalRemarkPlugins={cardRemarkPlugins}
+            componentOverrides={cardComponentOverrides}
+          />
+        )
+      }
+      return parts.map((part, pIdx) => {
+        if (part.kind === 'text') {
+          return (
+            <SimpleMarkdownRenderer
+              key={`t-${pIdx}`}
+              content={part.text}
+              textSize="compact"
+              additionalRemarkPlugins={cardRemarkPlugins}
+              componentOverrides={cardComponentOverrides}
+            />
+          )
+        }
+        return (
+          <div key={`b-${part.key}`} className="my-3">
+            {part.node}
+          </div>
+        )
+      })
+    }
+
     const getAvatarProps = () => {
       const displayName = name || (isUser ? "User" : assistantType === 'mingo' ? "Mingo" : "Fae")
       const isMingo = assistantType === 'mingo'
@@ -488,60 +540,19 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
           {(!isSystem || segments.length > 0) && <div className="flex flex-col gap-2">
             {segments.map((segment, index) => {
                 if (segment.type === 'text') {
-                  const parts = renderingPlan?.partsBySegment.get(index)
-                  const wrapperClass = cn(
-                    "min-w-0 w-full break-words text-h4",
-                    isError ? "text-ods-error" : "text-ods-text-primary",
-                  )
-                  // No block markers in this segment → single
-                  // SimpleMarkdownRenderer call (existing behaviour
-                  // preserved for the vast majority of messages).
-                  if (!parts || parts.length === 0) {
-                    return (
-                      <div key={index} className={wrapperClass}>
-                        <SimpleMarkdownRenderer
-                          content={segment.text}
-                          textSize="compact"
-                          additionalRemarkPlugins={cardRemarkPlugins}
-                          componentOverrides={cardComponentOverrides}
-                        />
-                      </div>
-                    )
-                  }
-                  // Block markers present → split text at each marker
-                  // and interleave block payloads. Each text chunk
-                  // includes its trailing marker so the inline pill
-                  // renders at the right position via the `<a>`
-                  // override. Block payloads land AS SIBLINGS between
-                  // text chunks — HTML-valid (block DOM never nests
-                  // inside `<p>`) AND positionally correct (block
-                  // appears where the marker is in the flow, not at
-                  // the segment's end). Stable React keys come from
-                  // the card key (block) and chunk position (text);
-                  // streaming token-by-token reuses the same React
-                  // instances so `<Video>` doesn't remount mid-play.
                   return (
-                    <div key={index} className={wrapperClass}>
-                      {parts.map((part, pIdx) => {
-                        if (part.kind === 'text') {
-                          return (
-                            <SimpleMarkdownRenderer
-                              key={`t-${pIdx}`}
-                              content={part.text}
-                              textSize="compact"
-                              additionalRemarkPlugins={cardRemarkPlugins}
-                              componentOverrides={cardComponentOverrides}
-                            />
-                          )
-                        }
-                        return (
-                          <div key={`b-${part.key}`} className="my-3">
-                            {part.node}
-                          </div>
-                        )
-                      })}
+                    <div
+                      key={index}
+                      className={cn(
+                        "min-w-0 w-full break-words text-h4",
+                        isError ? "text-ods-error" : "text-ods-text-primary",
+                      )}
+                    >
+                      {renderSegmentBody(index, segment.text)}
                     </div>
                   )
+                } else if (segment.type === 'guide') {
+                  return <GuideDisplay key={index}>{renderSegmentBody(index, segment.text)}</GuideDisplay>
                 } else if (segment.type === 'tool_execution') {
                   return (
                     <ToolExecutionDisplay

package/src/components/chat/guide-display.tsx

@@ -0,0 +1,44 @@
+"use client"
+
+import { forwardRef } from "react"
+
+import { cn } from "../../utils/cn"
+import { CompassIcon } from "../icons-v2-generated"
+import type { GuideDisplayProps } from "./types"
+
+const GUIDE_LABEL = "OpenFrame Guide"
+
+/**
+ * `GUIDE` segment — the assistant's how-to/documentation answer, framed as a
+ * titled card instead of a bare paragraph.
+ *
+ * Chrome only: the caller renders the markdown body and passes it as children,
+ * so a guide goes through the SAME body pipeline as a text segment
+ * (`[card://]` splitting + hoisted entity cards + mention chips). Rendering the
+ * raw markdown here instead would bypass that plan and degrade every card
+ * marker inside a guide to a bare title.
+ */
+const GuideDisplay = forwardRef<HTMLDivElement, GuideDisplayProps>(
+  ({ className, children, ...props }, ref) => {
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          "flex flex-col gap-[var(--spacing-system-m)] rounded-md border border-ods-border bg-ods-card p-[var(--spacing-system-m)]",
+          className
+        )}
+        {...props}
+      >
+        <div className="flex items-center gap-[var(--spacing-system-xs)]">
+          <CompassIcon size={16} className="shrink-0 text-ods-open-yellow" />
+          <span className="text-h5 text-ods-open-yellow">{GUIDE_LABEL}</span>
+        </div>
+        <div className="min-w-0 w-full break-words text-h4 text-ods-text-primary">{children}</div>
+      </div>
+    )
+  }
+)
+
+GuideDisplay.displayName = "GuideDisplay"
+
+export { GuideDisplay }

package/src/components/chat/hooks/use-chat-history-hydration.ts

@@ -0,0 +1,142 @@
+'use client'
+
+/**
+ * useChatHistoryHydration — mount-time rebuild of the chat message list from
+ * the SERVER-side conversation store (the `chat_conversations` /
+ * `chat_messages` SSOT behind `GET <chatStreamUrl>/history`).
+ *
+ * The client persists ONLY the server-issued conversation id (see
+ * `chat-conversation-storage.ts`); this hook turns that id back into rendered
+ * history: message bubbles, inline entity-card refs (per send index, same
+ * `sendIdx` scheme as live turns), and the send counter.
+ *
+ * Failure semantics: a fetch/parse failure simply leaves the UI empty — the
+ * SERVER still resolves full history for the next turn (it re-reads
+ * `chat_messages` by conversation id on every send), so conversation context
+ * is never lost when hydration misses.
+ */
+
+import { useEffect, useRef, useState, type MutableRefObject } from 'react'
+import type { ChatRef } from '../chat-ref.types'
+import type { Message } from './use-chat'
+import { chatAuthedFetch } from '../utils/chat-authed-fetch'
+import { AUTO_CONTINUATION_DIRECTIVE_PREFIX } from '../utils/auto-continuation-directive'
+
+export interface UseChatHistoryHydrationArgs {
+  /** Mirrors the adapter's `active` gate — an idle (Mingo-mode) mount never fetches. */
+  active: boolean
+  /** Chat source (= platform); part of the once-per-conversation guard key. */
+  source: string
+  /** Resolved history endpoint (`<chatStreamUrl>/history` by default). */
+  historyUrl: string
+  /** The server-issued conversation id (null = nothing to hydrate). */
+  conversationIdRef: MutableRefObject<string | null>
+  /** Per-send inline entity-card refs — repopulated from `chat_refs`. */
+  refsMapRef: MutableRefObject<Map<number, Record<string, ChatRef>>>
+  /** User-send counter — set to the hydrated user-turn count so the next
+   *  live send lands on the following `sendIdx`. */
+  sendCountRef: MutableRefObject<number>
+  /** `useChat`'s injection primitive (replace-or-prepend). */
+  hydrateMessages: (history: Message[]) => void
+  /** Invalidates the adapter's `latestMeta` memo after refs repopulate. */
+  bumpMetaTick: () => void
+}
+
+export interface UseChatHistoryHydrationResult {
+  /** True while the rebuild request is in flight. */
+  isHydratingHistory: boolean
+  /** Once-per-`source:conversationId` guard. The adapter's `clearMessages`
+   *  resets it to null alongside the stored id (a fresh conversation has no
+   *  server history to fetch). */
+  hydratedKeyRef: MutableRefObject<string | null>
+}
+
+export function useChatHistoryHydration({
+  active,
+  source,
+  historyUrl,
+  conversationIdRef,
+  refsMapRef,
+  sendCountRef,
+  hydrateMessages,
+  bumpMetaTick,
+}: UseChatHistoryHydrationArgs): UseChatHistoryHydrationResult {
+  const [isHydratingHistory, setIsHydratingHistory] = useState(false)
+  const hydratedKeyRef = useRef<string | null>(null)
+
+  useEffect(() => {
+    if (!active) return
+    // No stored conversation id → nothing to hydrate (fresh visitor / after
+    // "new chat"); the first send establishes the conversation server-side.
+    const conversationId = conversationIdRef.current
+    if (!conversationId) return
+    const key = `${source}:${conversationId}`
+    if (hydratedKeyRef.current === key) return
+    hydratedKeyRef.current = key
+    let cancelled = false
+    setIsHydratingHistory(true)
+    ;(async () => {
+      try {
+        const res = await chatAuthedFetch(
+          `${historyUrl}?conversationId=${encodeURIComponent(conversationId)}`,
+          { method: 'GET' },
+        )
+        if (!res.ok) return
+        const payload = await res.json().catch(() => null)
+        // route-base successResponse envelope ({ data }) with a raw-body fallback.
+        const body = (payload?.data ?? payload) as
+          | { messages?: Array<Record<string, unknown>> }
+          | null
+        const rows = Array.isArray(body?.messages) ? body!.messages! : []
+        if (cancelled || rows.length === 0) return
+        const hydrated: Message[] = []
+        let userTurns = 0
+        for (const row of rows) {
+          const role =
+            row.role === 'assistant' ? 'assistant' : row.role === 'user' ? 'user' : null
+          if (!role) continue
+          const content = typeof row.content === 'string' ? row.content : ''
+          // The approval placeholder ('') and the server-built auto-continuation
+          // directive are part of the LLM history but never rendered.
+          const hidden =
+            role === 'user' &&
+            (content === '' || content.startsWith(AUTO_CONTINUATION_DIRECTIVE_PREFIX))
+          if (role === 'user') {
+            userTurns += 1
+          } else if (row.chat_refs && typeof row.chat_refs === 'object') {
+            // Re-attach inline entity-card refs at the send index this
+            // assistant row belongs to (same sendIdx scheme as live turns).
+            refsMapRef.current.set(
+              Math.max(0, userTurns - 1),
+              row.chat_refs as Record<string, ChatRef>,
+            )
+          }
+          hydrated.push({
+            id: `hydrated-${String(row.seq ?? hydrated.length)}`,
+            role,
+            content,
+            ...(typeof row.created_at === 'string'
+              ? { timestamp: new Date(row.created_at) }
+              : {}),
+            ...(hidden ? { hidden: true } : {}),
+          } as Message)
+        }
+        if (cancelled || hydrated.length === 0) return
+        sendCountRef.current = userTurns
+        hydrateMessages(hydrated)
+        bumpMetaTick()
+      } catch {
+        // Fetch failed — start empty; the server still owns history (above).
+      } finally {
+        if (!cancelled) setIsHydratingHistory(false)
+      }
+    })()
+    return () => {
+      cancelled = true
+    }
+    // Refs are stable across renders — the effect keys on the identity-ish deps only.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [active, source, historyUrl, hydrateMessages, bumpMetaTick])
+
+  return { isHydratingHistory, hydratedKeyRef }
+}

package/src/components/chat/hooks/use-chat.ts

@@ -476,6 +476,17 @@ export function useChat({
     reset()
   }, [reset])
 
+  /**
+   * Replace-or-prepend server-hydrated history. Called once by the SSE
+   * adapter after `GET /api/docs/chat/history` resolves. If the user already
+   * sent a message before hydration landed, the fetched history is PREPENDED
+   * so nothing typed is lost — correctness is unaffected either way because
+   * the server resolves LLM history from its own store, not from this state.
+   */
+  const hydrateMessages = useCallback((history: Message[]) => {
+    setMessages((prev) => (prev.length === 0 ? history : [...history, ...prev]))
+  }, [])
+
   /**
    * Abort the in-flight streamed message. The fetch's AbortSignal terminates
    * the upstream Anthropic request (so billing stops); the `for await` loop
@@ -496,6 +507,7 @@ export function useChat({
     stopMessage,
     handleQuickAction,
     clearMessages,
+    hydrateMessages,
     hasMessages: messages.length > 0,
   }
 }

package/src/components/chat/hooks/use-nats-chat-adapter.ts

@@ -442,6 +442,8 @@ export function appendToTrailingAssistant(
       merged[merged.length - 1] = { type: 'text', text: tail.text + seg.text }
     } else if (seg.type === 'thinking' && tail?.type === 'thinking') {
       merged[merged.length - 1] = { type: 'thinking', text: tail.text + seg.text }
+    } else if (seg.type === 'guide' && tail?.type === 'guide') {
+      merged[merged.length - 1] = { type: 'guide', text: tail.text + seg.text }
     } else if (seg.type === 'approval_batch') {
       // Approval deltas must be IDEMPOTENT: the escalated-result emit can be
       // seen twice (live + catch-up replay over hydrated history), so upsert

package/src/components/chat/hooks/use-realtime-chunk-processor.ts

@@ -173,6 +173,16 @@ export function useRealtimeChunkProcessor(
           break
         }
 
+        case 'guide': {
+          const segments = accumulator.appendGuide(action.text)
+          if (isInStreamRef.current || !hasEverStreamedRef.current) {
+            emitSegments(segments)
+          } else {
+            emitSegments([{ type: 'guide', text: action.text }], { append: true })
+          }
+          break
+        }
+
         case 'tool_execution': {
           // A starting tool run means the agent's turn is in progress even
           // when this lands after MESSAGE_END (approved commands execute