@flamingo-stack/openframe-frontend-core 0.0.468-snapshot.20260723140929 → 0.0.468

package/src/components/chat/hooks/__tests__/persisted-state-v1-golden.test.ts

@@ -1,272 +0,0 @@
-/**
- * Phase-0 GOLDEN CHARACTERIZATION TESTS — PersistedChatState v1.
- *
- * The SSE chat adapter persists its conversation under
- * `mingo-chat-<source>-v1` (see `use-sse-chat-adapter.ts`:
- * chatStorageKey / loadPersistedChat / savePersistedChat). This file
- * seeds localStorage with a hand-crafted, REALISTIC v1 blob and pins the
- * exact rehydrated state the hook exposes. This blob is the MIGRATION
- * CONTRACT for the future unified reducer: whatever replaces the three
- * stream-reading layers must restore this v1 shape identically (or
- * migrate it losslessly).
- *
- * Blob contents:
- *   - 2 visible user sends (sendCount: 2)
- *   - 4 assistant messages — send #0 fans out to main reply (approval
- *     card) + post-approve receipt + continuation bubble (with a hidden
- *     approval-action user turn in between); send #1 is a plain RAG answer
- *   - sendIdx-keyed refs map with a card ref (ticket:77 on send #0)
- *   - sendIdx-keyed sources map (pricing source on send #1)
- *   - a NON-hidden auto-continuation directive bubble that the loader's
- *     forward-migration must flip to hidden:true
- */
-
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
-import { renderHook } from '@testing-library/react'
-import { createElement, type ReactNode } from 'react'
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-import { useSseChatAdapter } from '../use-sse-chat-adapter'
-import { ChatRuntimeContext, type ChatRuntime } from '../../../../contexts/chat-runtime-context'
-import { AUTO_CONTINUATION_DIRECTIVE_PREFIX } from '../../utils/auto-continuation-directive'
-
-const SOURCE = 'goldensrc'
-const STORAGE_KEY = `mingo-chat-${SOURCE}-v1`
-
-const runtime: ChatRuntime = {
-  endpoints: {
-    chatStreamUrl: '/api/docs/chat',
-    approvalToolUrl: '/api/chat/agent/confirm-tool',
-    commandsUrl: '/api/docs/commands',
-    buildListUrl: () => null,
-    attachmentUploadUrl: '/api/storage/generate-upload-url',
-    attachmentViewUrlPrefix: '/api/storage/view/chat-attachments/',
-    identityUrl: '/api/chat/identity',
-  },
-  navigation: { mode: 'host' },
-  source: SOURCE,
-}
-
-function wrapper({ children }: { children: ReactNode }) {
-  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } })
-  return createElement(
-    QueryClientProvider,
-    { client: queryClient },
-    createElement(ChatRuntimeContext.Provider, { value: runtime }, children),
-  )
-}
-
-/**
- * Hand-crafted v1 blob — REALISTIC shapes recorded from the live flow.
- * Timestamps are ISO strings on disk (loadPersistedChat revives them to
- * Date objects in place).
- */
-const V1_BLOB = {
-  messages: [
-    // ── send #0: "open a ticket" ────────────────────────────────────
-    {
-      id: 'user-1752915600000',
-      role: 'user',
-      name: 'You',
-      content: 'open a ticket for the broken printer',
-      timestamp: '2026-07-19T09:00:00.000Z',
-    },
-    {
-      // Main reply: preamble text + (resolved) approval card.
-      id: 'assistant-1752915600000',
-      role: 'assistant',
-      name: 'Mingo AI',
-      content: [
-        { type: 'text', text: "I'll open a ticket for you." },
-        {
-          type: 'approval_request',
-          data: {
-            command: 'Create ticket',
-            fields: [
-              { label: 'Subject', value: 'Broken printer' },
-              { label: 'Priority', value: 'High' },
-            ],
-            requestId: 'prop-1',
-            approvalType: 'create_ticket',
-          },
-          status: 'approved',
-        },
-      ],
-      timestamp: '2026-07-19T09:00:05.000Z',
-    },
-    {
-      // Hidden approval-action turn (content '' — the Approve click).
-      id: 'user-1752915610000',
-      role: 'user',
-      name: 'You',
-      content: '',
-      hidden: true,
-      timestamp: '2026-07-19T09:00:10.000Z',
-    },
-    {
-      // Post-approve receipt + card marker; chatRefs stamped on-message.
-      id: 'assistant-1752915610000',
-      role: 'assistant',
-      name: 'Mingo AI',
-      content: [
-        {
-          type: 'text',
-          text: '✅ Approved — ticket created: [card://ticket:77]\n\nNow, to triage faster: which floor is the printer on?',
-        },
-      ],
-      chatRefs: {
-        'ticket:77': {
-          type: 'ticket',
-          id: '77',
-          title: 'Broken printer',
-          url: null,
-          metadata: { status: 'OPEN' },
-        },
-      },
-      timestamp: '2026-07-19T09:00:12.000Z',
-    },
-    {
-      // Auto-continuation directive bubble persisted by an OLD lib version
-      // WITHOUT hidden:true — the loader's forward-migration must flip it.
-      id: 'user-1752915612000',
-      role: 'user',
-      name: 'You',
-      content: `${AUTO_CONTINUATION_DIRECTIVE_PREFIX} The user just approved create_ticket (ticket #77). Ask diagnostic follow-ups.`,
-      timestamp: '2026-07-19T09:00:12.500Z',
-    },
-    {
-      // Continuation prose for send #0 (third assistant message).
-      id: 'assistant-1752915613000',
-      role: 'assistant',
-      name: 'Mingo AI',
-      content: [{ type: 'text', text: 'Also: is the printer showing any error code on its display?' }],
-      timestamp: '2026-07-19T09:00:13.000Z',
-    },
-    // ── send #1: plain RAG answer ───────────────────────────────────
-    {
-      id: 'user-1752915700000',
-      role: 'user',
-      name: 'You',
-      content: 'what is the pricing?',
-      timestamp: '2026-07-19T09:01:40.000Z',
-    },
-    {
-      id: 'assistant-1752915700000',
-      role: 'assistant',
-      name: 'Mingo AI',
-      content: [
-        { type: 'thinking', text: 'Checking pricing docs…' },
-        { type: 'text', text: 'Pricing starts at $99/month per site.' },
-      ],
-      timestamp: '2026-07-19T09:01:45.000Z',
-    },
-  ],
-  // sendIdx-keyed maps (entries arrays, as serialized by savePersistedChat).
-  sources: [
-    [
-      1,
-      [
-        {
-          index: 1,
-          name: 'Pricing overview',
-          path: 'docs/pricing.md',
-          documentType: 'markdown',
-          sourceRepo: 'markdown',
-        },
-      ],
-    ],
-  ],
-  refs: [
-    [
-      0,
-      {
-        'ticket:77': {
-          type: 'ticket',
-          id: '77',
-          title: 'Broken printer',
-          url: null,
-          metadata: { status: 'OPEN' },
-        },
-      },
-    ],
-  ],
-  sendCount: 2,
-}
-
-beforeEach(() => {
-  window.localStorage.clear()
-  vi.spyOn(Date, 'now').mockReturnValue(1_700_000_000_000)
-})
-
-afterEach(() => {
-  vi.restoreAllMocks()
-})
-
-describe('PersistedChatState v1 — golden rehydration (migration contract)', () => {
-  it('restores messages / refs / sources from a hand-crafted v1 blob (snapshot)', () => {
-    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(V1_BLOB))
-
-    const { result } = renderHook(() => useSseChatAdapter(undefined, { active: false }), {
-      wrapper,
-    })
-
-    // Pin the FULL rehydrated public state:
-    //  - hidden approval-action turn + migrated directive bubble carry hidden:true
-    //  - all THREE assistant messages of send #0 resolve chatRefs['ticket:77']
-    //    (message-bound copy on the receipt, refs-map fallback for the others)
-    //  - send #1's assistant message carries the sources array
-    expect({
-      messages: result.current.messages,
-      streamingPhase: result.current.streamingPhase,
-      isLoading: result.current.isLoading,
-    }).toMatchSnapshot()
-  })
-
-  it('forward-migration flips a non-hidden auto-continuation directive bubble to hidden', () => {
-    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(V1_BLOB))
-    const { result } = renderHook(() => useSseChatAdapter(undefined, { active: false }), {
-      wrapper,
-    })
-    const directive = result.current.messages.find((m) =>
-      m.content.startsWith(AUTO_CONTINUATION_DIRECTIVE_PREFIX),
-    )
-    expect(directive?.hidden).toBe(true)
-  })
-
-  it('hidden user turns do NOT advance the sendIdx used for sources/refs lookup', () => {
-    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(V1_BLOB))
-    const { result } = renderHook(() => useSseChatAdapter(undefined, { active: false }), {
-      wrapper,
-    })
-    const assistants = result.current.messages.filter((m) => m.role === 'assistant')
-    // Send #0 fans out into THREE assistant bubbles (main reply +
-    // post-approve receipt + continuation); send #1 adds a fourth.
-    expect(assistants).toHaveLength(4)
-    // All send-#0 assistant bubbles resolve the ticket ref…
-    expect(assistants[0].chatRefs?.['ticket:77']?.id).toBe('77')
-    expect(assistants[1].chatRefs?.['ticket:77']?.id).toBe('77')
-    expect(assistants[2].chatRefs?.['ticket:77']?.id).toBe('77')
-    // …and the send-#1 bubble gets the pricing sources instead.
-    expect(assistants[3].sources?.[0]?.name).toBe('Pricing overview')
-    expect(assistants[3].chatRefs).toBeUndefined()
-  })
-
-  it('a corrupt blob falls back to an empty conversation', () => {
-    window.localStorage.setItem(STORAGE_KEY, '{not json')
-    const { result } = renderHook(() => useSseChatAdapter(undefined, { active: false }), {
-      wrapper,
-    })
-    expect(result.current.messages).toEqual([])
-  })
-
-  it('rehydration round-trips: the persist callback re-saves an equivalent v1 blob', () => {
-    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(V1_BLOB))
-    renderHook(() => useSseChatAdapter(undefined, { active: false }), { wrapper })
-
-    // Mounting fires onMessagesChange → savePersistedChat with the loaded
-    // state (timestamps re-serialized to ISO strings, directive bubble now
-    // hidden:true). Pin the re-saved wire shape — THIS is the exact v1 blob
-    // a future reducer will find on disk.
-    const resaved = JSON.parse(window.localStorage.getItem(STORAGE_KEY)!)
-    expect(resaved).toMatchSnapshot()
-  })
-})

package/src/components/chat/hooks/__tests__/sse-stream-golden.test.ts

@@ -1,318 +0,0 @@
-/**
- * Phase-0 GOLDEN CHARACTERIZATION TESTS — the SSE wire decoder inside
- * `useSseChatAdapter` (`createDocStreamFn`), driven through the full
- * public hook (`useSseChatAdapter` → `useChat` → `useSSE`).
- *
- * Wire format (recorded from the hub's /api/docs/chat):
- *   [JSON frame]\0 [JSON frame]\0 …  \x1E  <raw UTF-8 answer deltas>  \x1F [JSON usage trailer]
- *
- * Each fixture feeds a mocked global fetch whose Response body is a
- * ReadableStream of Uint8Array chunks, then snapshots the resulting
- * message state. Behaviors captured here — INCLUDING the sentinel-byte
- * mis-framing in fixture (d) — are the recorded baseline for the
- * unification reducer. Do NOT "fix" them here.
- */
-
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
-import { renderHook, act } from '@testing-library/react'
-import { createElement, type ReactNode } from 'react'
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-import { useSseChatAdapter } from '../use-sse-chat-adapter'
-import { ChatRuntimeContext, type ChatRuntime } from '../../../../contexts/chat-runtime-context'
-
-// =============================================================================
-// Harness
-// =============================================================================
-
-const SOURCE = 'goldensrc'
-
-const runtime: ChatRuntime = {
-  endpoints: {
-    chatStreamUrl: '/api/docs/chat',
-    approvalToolUrl: '/api/chat/agent/confirm-tool',
-    commandsUrl: '/api/docs/commands',
-    buildListUrl: () => null,
-    attachmentUploadUrl: '/api/storage/generate-upload-url',
-    attachmentViewUrlPrefix: '/api/storage/view/chat-attachments/',
-    identityUrl: '/api/chat/identity',
-  },
-  navigation: { mode: 'host' },
-  source: SOURCE,
-}
-
-function wrapper({ children }: { children: ReactNode }) {
-  const queryClient = new QueryClient({
-    defaultOptions: { queries: { retry: false } },
-  })
-  return createElement(
-    QueryClientProvider,
-    { client: queryClient },
-    createElement(ChatRuntimeContext.Provider, { value: runtime }, children),
-  )
-}
-
-/** renderHook with the required runtime + react-query providers.
- *  `active: false` skips the slash-command registry fetch so the mocked
- *  fetch only ever serves the chat stream. */
-function renderAdapter() {
-  return renderHook(() => useSseChatAdapter(undefined, { active: false }), { wrapper })
-}
-
-const enc = new TextEncoder()
-
-/** Build a ReadableStream that enqueues each chunk (string → UTF-8) then closes. */
-function streamOf(chunks: Array<string | Uint8Array>): ReadableStream<Uint8Array> {
-  return new ReadableStream<Uint8Array>({
-    start(controller) {
-      for (const c of chunks) {
-        controller.enqueue(typeof c === 'string' ? enc.encode(c) : c)
-      }
-      controller.close()
-    },
-  })
-}
-
-/** Mock global fetch to serve ONE streamed chat response. */
-function mockFetchStream(chunks: Array<string | Uint8Array>) {
-  const fetchMock = vi.fn(async (_url: string, init?: RequestInit) => {
-    const body = streamOf(chunks)
-    // Honor the caller's AbortSignal like real fetch: error the stream so
-    // pending reader.read() calls reject with AbortError.
-    return { ok: true, status: 200, body } as unknown as Response
-  })
-  vi.stubGlobal('fetch', fetchMock)
-  return fetchMock
-}
-
-const tick = () => new Promise<void>((r) => setTimeout(r, 0))
-
-beforeEach(() => {
-  window.localStorage.clear()
-  // Deterministic Date.now: message ids (`user-<now>`) and the 50ms
-  // thinking-throttle both read it. With a frozen clock the FIRST
-  // thinking delta yields immediately (now - 0 >= 50) and every later
-  // delta within the same stream is throttled (now - last = 0 < 50) and
-  // flushed at the \x1E boundary — fully deterministic.
-  vi.spyOn(Date, 'now').mockReturnValue(1_700_000_000_000)
-})
-
-afterEach(() => {
-  vi.unstubAllGlobals()
-  vi.restoreAllMocks()
-})
-
-/** Compact projection of the adapter's public state for snapshots. */
-function snapshotState(result: { current: ReturnType<typeof useSseChatAdapter> }) {
-  const s = result.current
-  return {
-    messages: s.messages,
-    streamingPhase: s.streamingPhase,
-    provider: s.currentProvider,
-    modelLabel: s.currentModelLabel,
-    contextWindowMaxTokens: s.currentContextWindowMaxTokens,
-    inputTokens: s.currentInputTokens,
-    outputTokens: s.currentOutputTokens,
-    cacheHitRatePct: s.currentCacheHitRatePct,
-    usageBreakdown: s.currentUsageBreakdown,
-  }
-}
-
-// Shared leading-frame fixtures (recorded wire shapes).
-const THINKING_STATUS = '{"status":"thinking"}\0'
-const THINKING_DELTA_1 = '{"kind":"thinking-delta","text":"Let me check the docs… "}\0'
-const THINKING_DELTA_2 = '{"kind":"thinking-delta","text":"found it."}\0'
-const METADATA_FRAME =
-  '{"sources":[{"index":1,"name":"Pricing overview","path":"docs/pricing.md","documentType":"markdown","sourceRepo":"markdown"}],"model":"claude-sonnet-x","modelLabel":"Claude Sonnet","provider":"anthropic","contextWindowMaxTokens":200000}\0'
-const ROUTING_FRAME = '{"kind":"routing","routedComplexity":"simple","routedThinkingBudget":0}\0'
-const USAGE_START_FRAME = '{"kind":"usage","stage":"start","input_tokens":1234}\0'
-const USAGE_END_TRAILER =
-  '{"kind":"usage","stage":"end","input_tokens":1234,"output_tokens":56,"hit_rate_pct":81.5,"breakdown":{"haikuRewriter":{"input":10,"output":4},"haikuClassifier":{"input":8,"output":1},"routedAnswer":{"model":"claude-sonnet-x","complexity":"simple","thinkingBudget":0}}}'
-
-describe('SSE wire decode — golden fixtures (full hook path)', () => {
-  it('(a) normal turn: thinking frames → metadata → usage:start → \\x1E → text ×3 → \\x1F trailer', async () => {
-    mockFetchStream([
-      THINKING_STATUS,
-      THINKING_DELTA_1,
-      THINKING_DELTA_2,
-      METADATA_FRAME,
-      ROUTING_FRAME,
-      USAGE_START_FRAME,
-      '\x1E',
-      'Answer part one, ',
-      'part two, ',
-      'part three.',
-      '\x1F' + USAGE_END_TRAILER,
-    ])
-    const { result } = renderAdapter()
-    await act(async () => {
-      await result.current.sendMessage('what is the pricing?')
-    })
-    expect(snapshotState(result)).toMatchSnapshot()
-  })
-
-  it('(b) EVERYTHING in one single TCP chunk', async () => {
-    mockFetchStream([
-      THINKING_STATUS +
-        THINKING_DELTA_1 +
-        METADATA_FRAME +
-        USAGE_START_FRAME +
-        '\x1E' +
-        'One-chunk answer.' +
-        '\x1F' +
-        USAGE_END_TRAILER,
-    ])
-    const { result } = renderAdapter()
-    await act(async () => {
-      await result.current.sendMessage('one chunk please')
-    })
-    expect(snapshotState(result)).toMatchSnapshot()
-  })
-
-  it('(c) trailer split across two chunks arriving with stream done', async () => {
-    mockFetchStream([
-      METADATA_FRAME,
-      '\x1E',
-      'Split-trailer answer.',
-      '\x1F{"kind":"usage","stage":"end","input_to',
-      'kens":42,"output_tokens":9,"hit_rate_pct":12.5}',
-    ])
-    const { result } = renderAdapter()
-    await act(async () => {
-      await result.current.sendMessage('split the trailer')
-    })
-    expect(snapshotState(result)).toMatchSnapshot()
-  })
-
-  it('(d) answer text containing literal \\x1E/\\x1F/\\0 bytes', async () => {
-    // CHARACTERIZATION: current behavior, see unification plan.
-    //  - In text mode only \x1F is scanned: literal \0 and \x1E bytes in
-    //    the answer pass through into the rendered text unchanged.
-    //  - The FIRST literal \x1F flips the decoder into trailer mode:
-    //    everything after it (including later real text) is captured as
-    //    the trailer buffer, fails JSON.parse, and is SILENTLY DROPPED —
-    //    the real \x1F usage trailer is lost too (mis-framing/truncation).
-    mockFetchStream([
-      METADATA_FRAME,
-      '\x1E',
-      'has-nul[\0]and-rs[\x1E]still-text. ',
-      'now-us[\x1F]everything-after-is-swallowed',
-      ' including this and the real trailer:',
-      '\x1F' + USAGE_END_TRAILER,
-    ])
-    const { result } = renderAdapter()
-    await act(async () => {
-      await result.current.sendMessage('sentinel bytes in answer')
-    })
-    expect(snapshotState(result)).toMatchSnapshot()
-  })
-
-  it('(e) [card://blog:x] marker in the answer with refs metadata frame', async () => {
-    const refsFrame =
-      '{"refs":{"blog:x":{"type":"blog","id":"x","title":"Post X","url":"/blog/x","metadata":{"slug":"post-x"}}}}\0'
-    mockFetchStream([
-      METADATA_FRAME,
-      refsFrame,
-      '\x1E',
-      'See [card://blog:x] for the full story.',
-      '\x1F' + USAGE_END_TRAILER,
-    ])
-    const { result } = renderAdapter()
-    await act(async () => {
-      await result.current.sendMessage('show me the post')
-    })
-    expect(snapshotState(result)).toMatchSnapshot()
-  })
-
-  it('(f) abort mid-stream via AbortController leaves the partial message in place', async () => {
-    // Manually-controlled stream: enqueue the leading frames + first text
-    // delta, keep the stream OPEN, then Stop. The mocked fetch honors the
-    // AbortSignal by erroring the stream with AbortError — same observable
-    // behavior as real fetch cancelling the body.
-    let ctrl!: ReadableStreamDefaultController<Uint8Array>
-    const body = new ReadableStream<Uint8Array>({
-      start(c) {
-        ctrl = c
-        c.enqueue(enc.encode(METADATA_FRAME))
-        c.enqueue(enc.encode('\x1E'))
-        c.enqueue(enc.encode('Partial ans'))
-      },
-    })
-    const fetchMock = vi.fn(async (_url: string, init?: RequestInit) => {
-      init?.signal?.addEventListener('abort', () => {
-        try {
-          ctrl.error(new DOMException('The operation was aborted.', 'AbortError'))
-        } catch {
-          /* already closed */
-        }
-      })
-      return { ok: true, status: 200, body } as unknown as Response
-    })
-    vi.stubGlobal('fetch', fetchMock)
-
-    const { result } = renderAdapter()
-    let sendPromise!: Promise<void>
-    act(() => {
-      sendPromise = result.current.sendMessage('will be aborted')
-    })
-    // Let the decoder consume the enqueued chunks.
-    await act(async () => {
-      await tick()
-      await tick()
-      await tick()
-    })
-    act(() => {
-      result.current.stopMessage()
-    })
-    await act(async () => {
-      await sendPromise
-    })
-    expect(snapshotState(result)).toMatchSnapshot()
-    expect(fetchMock).toHaveBeenCalledTimes(1)
-  })
-
-  it('(g) multi-byte UTF-8 character split across two chunks decodes intact', async () => {
-    // '🦩' = F0 9F A6 A9 — split 2+2 across chunk boundary. The decoder is
-    // created once per stream with {stream:true} reads, so the glyph
-    // survives the split. CHARACTERIZATION: current (correct) behavior.
-    const flamingo = enc.encode('🦩')
-    mockFetchStream([
-      METADATA_FRAME,
-      '\x1E',
-      'A wild ',
-      flamingo.slice(0, 2),
-      flamingo.slice(2),
-      ' appears',
-      '\x1F' + USAGE_END_TRAILER,
-    ])
-    const { result } = renderAdapter()
-    await act(async () => {
-      await result.current.sendMessage('emoji split')
-    })
-    expect(snapshotState(result)).toMatchSnapshot()
-  })
-
-  it('leading approval_request + text-leading frames yield a pending approval card', async () => {
-    mockFetchStream([
-      '{"kind":"text-leading","text":"I\'ll open a ticket for you."}\0',
-      '{"kind":"approval_request","proposalId":"prop-1","toolName":"create_ticket","title":"Create ticket","fields":[{"label":"Subject","value":"Printer down"},{"label":"Priority","value":"High"},{"bad":"missing label/value"}]}\0',
-      // Stream closes with NO \x1E answer body — the approval turn ends here.
-    ])
-    const { result } = renderAdapter()
-    await act(async () => {
-      await result.current.sendMessage('open a ticket')
-    })
-    expect(snapshotState(result)).toMatchSnapshot()
-  })
-
-  it('non-JSON leading buffer falls through to answer text (legacy no-frame stream)', async () => {
-    // CHARACTERIZATION: a frame-less response whose first \0-terminated
-    // block is not JSON flips straight into text mode and the buffer is
-    // emitted as answer text.
-    mockFetchStream(['plain text answer with no frames\0and more after the nul'])
-    const { result } = renderAdapter()
-    await act(async () => {
-      await result.current.sendMessage('legacy stream')
-    })
-    expect(snapshotState(result)).toMatchSnapshot()
-  })
-})