@varo-ui/ai 1.0.0

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './agent-stream'
+export * from './event-channel'
+export * from './event-parser'
+export * from './markdown'
+export * from './markdown-view'
+export * from './sse'
+export * from './text-stream'
+export * from './types'

package/src/markdown-view.ts

@@ -0,0 +1,227 @@
+import { isUnknownRecord } from './type-guards'
+import type { ParsedNode } from 'stream-markdown-parser'
+
+export type AgentMarkdownNodeKind =
+  | 'admonition'
+  | 'blockquote'
+  | 'checkbox'
+  | 'code-block'
+  | 'definition'
+  | 'definition-list'
+  | 'emphasis'
+  | 'footnote'
+  | 'hardbreak'
+  | 'heading'
+  | 'highlight'
+  | 'image'
+  | 'inline-code'
+  | 'insert'
+  | 'link'
+  | 'list'
+  | 'list-item'
+  | 'math-block'
+  | 'math-inline'
+  | 'paragraph'
+  | 'strikethrough'
+  | 'strong'
+  | 'subscript'
+  | 'superscript'
+  | 'table'
+  | 'table-cell'
+  | 'table-row'
+  | 'text'
+  | 'thematic-break'
+
+export interface AgentMarkdownViewNode {
+  align?: 'center' | 'left' | 'right'
+  alt?: string
+  checked?: boolean
+  children?: AgentMarkdownViewNode[]
+  header?: boolean
+  href?: string
+  kind: AgentMarkdownNodeKind
+  language?: string
+  level?: number
+  loading?: boolean
+  ordered?: boolean
+  start?: number
+  text?: string
+  title?: string
+}
+
+function stringValue(value: unknown, fallback = '') {
+  return typeof value === 'string' ? value : fallback
+}
+
+function booleanValue(value: unknown) {
+  return typeof value === 'boolean' ? value : undefined
+}
+
+function numberValue(value: unknown) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined
+}
+
+function alignValue(value: unknown): 'center' | 'left' | 'right' | undefined {
+  return value === 'center' || value === 'left' || value === 'right' ? value : undefined
+}
+
+function nodeField(node: ParsedNode, key: string): unknown {
+  return key in node ? Reflect.get(node, key) : undefined
+}
+
+function normalizeUnknownNode(value: unknown): AgentMarkdownViewNode | undefined {
+  if (!isUnknownRecord(value) || typeof value.type !== 'string' || typeof value.raw !== 'string') return undefined
+  // The required BaseNode fields are validated above; extension fields stay runtime-checked.
+  const node = value as ParsedNode
+  return normalizeMarkdownNode(node)
+}
+
+function normalizeChildren(value: unknown): AgentMarkdownViewNode[] {
+  if (!Array.isArray(value)) return []
+  const result: AgentMarkdownViewNode[] = []
+  value.forEach((item) => {
+    const normalized = normalizeUnknownNode(item)
+    if (normalized) result.push(normalized)
+  })
+  return result
+}
+
+function textNode(text: string): AgentMarkdownViewNode {
+  return { kind: 'text', text }
+}
+
+export function normalizeMarkdownNode(node: ParsedNode): AgentMarkdownViewNode {
+  const fallback = stringValue(node.raw)
+
+  switch (node.type) {
+    case 'text':
+      return textNode(stringValue(node.content, fallback))
+    case 'heading':
+      return {
+        children: normalizeChildren(node.children),
+        kind: 'heading',
+        level: numberValue(nodeField(node, 'level')) ?? 2,
+        text: stringValue(nodeField(node, 'text'))
+      }
+    case 'paragraph':
+    case 'inline':
+      return { children: normalizeChildren(node.children), kind: 'paragraph' }
+    case 'list':
+      return {
+        children: normalizeChildren(nodeField(node, 'items')),
+        kind: 'list',
+        ordered: booleanValue(nodeField(node, 'ordered')) ?? false,
+        start: numberValue(nodeField(node, 'start'))
+      }
+    case 'list_item':
+      return { children: normalizeChildren(node.children), kind: 'list-item' }
+    case 'code_block':
+      return {
+        kind: 'code-block',
+        language: stringValue(nodeField(node, 'language')),
+        loading: booleanValue(node.loading),
+        text: stringValue(node.code, fallback)
+      }
+    case 'inline_code':
+      return { kind: 'inline-code', text: stringValue(node.code, fallback) }
+    case 'link':
+      return {
+        children: normalizeChildren(node.children),
+        href: stringValue(nodeField(node, 'href')),
+        kind: 'link',
+        text: stringValue(nodeField(node, 'text')),
+        title: stringValue(nodeField(node, 'title'))
+      }
+    case 'image':
+      return {
+        alt: stringValue(nodeField(node, 'alt')),
+        href: stringValue(nodeField(node, 'src')),
+        kind: 'image',
+        title: stringValue(nodeField(node, 'title'))
+      }
+    case 'thematic_break':
+      return { kind: 'thematic-break' }
+    case 'blockquote':
+      return { children: normalizeChildren(node.children), kind: 'blockquote' }
+    case 'table': {
+      const header = nodeField(node, 'header')
+      const rows = nodeField(node, 'rows')
+      return {
+        children: normalizeChildren(Array.isArray(rows) ? [header, ...rows] : [header]),
+        kind: 'table'
+      }
+    }
+    case 'table_row':
+      return { children: normalizeChildren(nodeField(node, 'cells')), kind: 'table-row' }
+    case 'table_cell':
+      return {
+        align: alignValue(nodeField(node, 'align')),
+        children: normalizeChildren(node.children),
+        header: booleanValue(nodeField(node, 'header')),
+        kind: 'table-cell'
+      }
+    case 'strong':
+      return { children: normalizeChildren(node.children), kind: 'strong' }
+    case 'emphasis':
+      return { children: normalizeChildren(node.children), kind: 'emphasis' }
+    case 'strikethrough':
+      return { children: normalizeChildren(node.children), kind: 'strikethrough' }
+    case 'highlight':
+      return { children: normalizeChildren(node.children), kind: 'highlight' }
+    case 'insert':
+      return { children: normalizeChildren(node.children), kind: 'insert' }
+    case 'subscript':
+      return { children: normalizeChildren(node.children), kind: 'subscript' }
+    case 'superscript':
+      return { children: normalizeChildren(node.children), kind: 'superscript' }
+    case 'checkbox':
+    case 'checkbox_input':
+      return { checked: booleanValue(nodeField(node, 'checked')), kind: 'checkbox' }
+    case 'emoji':
+      return textNode(stringValue(nodeField(node, 'markup'), fallback))
+    case 'definition_list':
+      return { children: normalizeChildren(nodeField(node, 'items')), kind: 'definition-list' }
+    case 'definition_item':
+      return {
+        children: [
+          { children: normalizeChildren(nodeField(node, 'term')), header: true, kind: 'definition' },
+          { children: normalizeChildren(nodeField(node, 'definition')), kind: 'definition' }
+        ],
+        kind: 'definition'
+      }
+    case 'footnote':
+      return { children: normalizeChildren(node.children), kind: 'footnote', title: stringValue(nodeField(node, 'id')) }
+    case 'footnote_reference':
+    case 'reference':
+      return { kind: 'footnote', text: stringValue(nodeField(node, 'id')) }
+    case 'admonition':
+      return {
+        children: normalizeChildren(node.children),
+        kind: 'admonition',
+        text: stringValue(nodeField(node, 'kind')),
+        title: stringValue(nodeField(node, 'title'))
+      }
+    case 'vmr_container':
+      return {
+        children: normalizeChildren(node.children),
+        kind: 'admonition',
+        loading: booleanValue(node.loading),
+        title: stringValue(nodeField(node, 'name'))
+      }
+    case 'hardbreak':
+      return { kind: 'hardbreak' }
+    case 'math_inline':
+      return { kind: 'math-inline', text: stringValue(node.content, fallback) }
+    case 'math_block':
+      return { kind: 'math-block', text: stringValue(node.content, fallback) }
+    case 'html_block':
+    case 'html_inline':
+      return textNode(stringValue(node.content, fallback))
+    default:
+      return textNode(fallback)
+  }
+}
+
+export function normalizeMarkdownNodes(nodes: ParsedNode[]): AgentMarkdownViewNode[] {
+  return nodes.map(normalizeMarkdownNode)
+}

package/src/markdown.ts

@@ -0,0 +1,58 @@
+import {
+  getMarkdown,
+  isUnsafeHtmlUrl,
+  parseMarkdownToStructure,
+  type GetMarkdownOptions,
+  type ParsedNode
+} from 'stream-markdown-parser'
+
+export interface StreamingMarkdownParserOptions {
+  customHtmlTags?: readonly string[]
+  enableMath?: boolean
+  includeSourceMap?: boolean
+  markdownItOptions?: GetMarkdownOptions['markdownItOptions']
+  validateLink?: (url: string) => boolean
+}
+
+export interface StreamingMarkdownParser {
+  parse: (content: string, options?: { final?: boolean }) => ParsedNode[]
+  reset: () => void
+}
+
+let parserId = 0
+
+export function createStreamingMarkdownParser(
+  options: StreamingMarkdownParserOptions = {}
+): StreamingMarkdownParser {
+  parserId += 1
+  const validateLink = options.validateLink ?? ((url: string) => !isUnsafeHtmlUrl(url))
+  const markdown = getMarkdown(`varo-agent-${parserId}`, {
+    customHtmlTags: options.customHtmlTags,
+    enableMath: options.enableMath ?? true,
+    markdownItOptions: {
+      breaks: true,
+      html: false,
+      linkify: true,
+      ...options.markdownItOptions,
+      validateLink
+    }
+  })
+
+  return {
+    parse(content, parseOptions = {}) {
+      return parseMarkdownToStructure(content, markdown, {
+        customHtmlTags: options.customHtmlTags,
+        final: parseOptions.final ?? false,
+        includeSourceMap: options.includeSourceMap ?? false,
+        reuseStableTopLevelNodes: true,
+        streamParse: 'auto',
+        validateLink
+      })
+    },
+    reset() {
+      markdown.stream?.reset?.()
+    }
+  }
+}
+
+export type { ParsedNode } from 'stream-markdown-parser'

package/src/sse.ts

@@ -0,0 +1,161 @@
+import { createAgentEventChannel } from './event-channel'
+import { parseAgentStreamEvent } from './event-parser'
+import type { AgentStreamEvent } from './types'
+
+export interface AgentSseEventSource {
+  end: () => void
+  fail: (error: unknown) => void
+  feed: (chunk: string | ArrayBuffer | Uint8Array) => void
+  source: AsyncIterable<AgentStreamEvent>
+}
+
+interface Utf8ChunkDecoder {
+  decode: (chunk: Uint8Array, final?: boolean) => string
+}
+
+function createFallbackUtf8Decoder(): Utf8ChunkDecoder {
+  let carry = new Uint8Array(0)
+
+  return {
+    decode(chunk, final = false) {
+      const bytes = new Uint8Array(carry.length + chunk.length)
+      bytes.set(carry)
+      bytes.set(chunk, carry.length)
+      let cursor = 0
+      let result = ''
+
+      while (cursor < bytes.length) {
+        const first = bytes[cursor]
+        if (first < 0x80) {
+          result += String.fromCodePoint(first)
+          cursor += 1
+          continue
+        }
+
+        const size = first >= 0xf0 ? 4 : first >= 0xe0 ? 3 : first >= 0xc0 ? 2 : 1
+        if (size === 1) {
+          result += '\uFFFD'
+          cursor += 1
+          continue
+        }
+        if (cursor + size > bytes.length) break
+
+        let codePoint = first & (size === 2 ? 0x1f : size === 3 ? 0x0f : 0x07)
+        let valid = true
+        for (let index = 1; index < size; index += 1) {
+          const continuation = bytes[cursor + index]
+          if ((continuation & 0xc0) !== 0x80) {
+            valid = false
+            break
+          }
+          codePoint = (codePoint << 6) | (continuation & 0x3f)
+        }
+
+        if (!valid || codePoint > 0x10ffff) {
+          result += '\uFFFD'
+          cursor += 1
+          continue
+        }
+
+        result += String.fromCodePoint(codePoint)
+        cursor += size
+      }
+
+      carry = bytes.slice(cursor)
+      if (final && carry.length > 0) {
+        result += '\uFFFD'
+        carry = new Uint8Array(0)
+      }
+      return result
+    }
+  }
+}
+
+function createUtf8Decoder(): Utf8ChunkDecoder {
+  if (typeof TextDecoder === 'function') {
+    const decoder = new TextDecoder()
+    return {
+      decode(chunk, final = false) {
+        return decoder.decode(chunk, { stream: !final })
+      }
+    }
+  }
+  return createFallbackUtf8Decoder()
+}
+
+function toBytes(chunk: ArrayBuffer | Uint8Array) {
+  return chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk)
+}
+
+export function createAgentSseEventSource(): AgentSseEventSource {
+  const channel = createAgentEventChannel()
+  const decoder = createUtf8Decoder()
+  const dataLines: string[] = []
+  let textBuffer = ''
+  let ended = false
+
+  function dispatch() {
+    if (dataLines.length === 0 || ended) return
+    const payload = dataLines.join('\n')
+    dataLines.length = 0
+    if (payload === '[DONE]') {
+      channel.push({ type: 'done' })
+      return
+    }
+
+    try {
+      channel.push(parseAgentStreamEvent(JSON.parse(payload)))
+    } catch (error) {
+      ended = true
+      channel.fail(error)
+    }
+  }
+
+  function processLine(line: string) {
+    const normalized = line.endsWith('\r') ? line.slice(0, -1) : line
+    if (normalized.length === 0) {
+      dispatch()
+      return
+    }
+    if (normalized.startsWith(':')) return
+    if (normalized === 'data') {
+      dataLines.push('')
+      return
+    }
+    if (normalized.startsWith('data:')) {
+      const value = normalized.slice(5)
+      dataLines.push(value.startsWith(' ') ? value.slice(1) : value)
+    }
+  }
+
+  function appendText(value: string) {
+    textBuffer += value
+    let lineEnd = textBuffer.indexOf('\n')
+    while (lineEnd >= 0) {
+      processLine(textBuffer.slice(0, lineEnd))
+      textBuffer = textBuffer.slice(lineEnd + 1)
+      lineEnd = textBuffer.indexOf('\n')
+    }
+  }
+
+  return {
+    end() {
+      if (ended) return
+      appendText(decoder.decode(new Uint8Array(0), true))
+      if (textBuffer.length > 0) processLine(textBuffer)
+      dispatch()
+      ended = true
+      channel.end()
+    },
+    fail(error) {
+      if (ended) return
+      ended = true
+      channel.fail(error)
+    },
+    feed(chunk) {
+      if (ended) return
+      appendText(typeof chunk === 'string' ? chunk : decoder.decode(toBytes(chunk)))
+    },
+    source: channel.source
+  }
+}

package/src/text-stream.ts

@@ -0,0 +1,202 @@
+import { createSmoothMarkdownStream } from 'markstream-core'
+import type { TextStreamController, TextStreamOptions, TextStreamSnapshot } from './types'
+
+interface SegmenterLike {
+  segment: (value: string) => Iterable<{ segment: string }>
+}
+
+function splitGraphemes(value: string): string[] {
+  const intlRuntime: unknown = Intl
+  if (
+    typeof intlRuntime !== 'object'
+    || intlRuntime === null
+    || !('Segmenter' in intlRuntime)
+    || typeof intlRuntime.Segmenter !== 'function'
+  ) {
+    return Array.from(value)
+  }
+
+  // Runtime constructor shape is checked above; TypeScript's configured Intl lib omits Segmenter.
+  const Segmenter = intlRuntime.Segmenter as new (
+    locale?: string,
+    options?: { granularity: 'grapheme' }
+  ) => SegmenterLike
+  return Array.from(new Segmenter(undefined, { granularity: 'grapheme' }).segment(value), (item) => item.segment)
+}
+
+function clamp(value: number, min: number, max: number) {
+  return Math.min(max, Math.max(min, value))
+}
+
+function createTimerTextStream(options: TextStreamOptions = {}): TextStreamController {
+  const minCharsPerSecond = Math.max(1, options.minCharsPerSecond ?? 40)
+  const maxCharsPerSecond = Math.max(minCharsPerSecond, options.maxCharsPerSecond ?? 800)
+  const targetLatencyMs = Math.max(50, options.targetLatencyMs ?? 700)
+  const maxCommitFps = Math.max(1, Math.min(30, options.maxCommitFps ?? 20))
+  const maxCharsPerCommit = Math.max(1, options.maxCharsPerCommit ?? 64)
+  const catchUpThreshold = Math.max(1, options.catchUpThreshold ?? 320)
+  const listeners = new Set<() => void>()
+  const pending: string[] = []
+  let pendingOffset = 0
+  let source = ''
+  let visible = ''
+  let done = false
+  let paused = false
+  let destroyed = false
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let lastTick = Date.now()
+  let budget = 0
+
+  function pendingCount() {
+    return pending.length - pendingOffset
+  }
+
+  function snapshot(): TextStreamSnapshot {
+    const pendingChars = pendingCount()
+    return {
+      caughtUp: pendingChars === 0,
+      done,
+      final: done && pendingChars === 0,
+      paused,
+      pendingChars,
+      source,
+      visible
+    }
+  }
+
+  function emit() {
+    listeners.forEach((listener) => listener())
+  }
+
+  function compactPending() {
+    if (pendingOffset < 1024 || pendingOffset * 2 < pending.length) return
+    pending.splice(0, pendingOffset)
+    pendingOffset = 0
+  }
+
+  function schedule() {
+    if (destroyed || paused || timer || pendingCount() === 0) return
+    timer = setTimeout(tick, Math.ceil(1000 / maxCommitFps))
+  }
+
+  function tick() {
+    timer = undefined
+    if (destroyed || paused) return
+
+    const now = Date.now()
+    const deltaMs = Math.max(1, now - lastTick)
+    lastTick = now
+    const backlog = pendingCount()
+    if (backlog === 0) {
+      emit()
+      return
+    }
+
+    const latencyCps = (backlog * 1000) / targetLatencyMs
+    const catchUpBoost = backlog >= catchUpThreshold ? 1.8 : 1
+    const cps = clamp(latencyCps * catchUpBoost, minCharsPerSecond, maxCharsPerSecond)
+    budget += (cps * deltaMs) / 1000
+    const commitCount = Math.min(backlog, maxCharsPerCommit, Math.max(1, Math.floor(budget)))
+    budget = Math.max(0, budget - commitCount)
+    visible += pending.slice(pendingOffset, pendingOffset + commitCount).join('')
+    pendingOffset += commitCount
+    compactPending()
+    emit()
+    schedule()
+  }
+
+  function cancelTimer() {
+    clearTimeout(timer)
+    timer = undefined
+  }
+
+  return {
+    destroy() {
+      if (destroyed) return
+      destroyed = true
+      cancelTimer()
+      pending.length = 0
+      listeners.clear()
+    },
+    enqueue(chunk) {
+      if (destroyed || !chunk) return
+      if (done) done = false
+      source += chunk
+      pending.push(...splitGraphemes(chunk))
+      lastTick = Date.now()
+      emit()
+      schedule()
+    },
+    finish(finishOptions = {}) {
+      if (destroyed) return
+      done = true
+      if (finishOptions.flush) {
+        visible = source
+        pending.length = 0
+        pendingOffset = 0
+        cancelTimer()
+      }
+      emit()
+      schedule()
+    },
+    flush() {
+      if (destroyed) return
+      visible = source
+      pending.length = 0
+      pendingOffset = 0
+      budget = 0
+      cancelTimer()
+      emit()
+    },
+    getSnapshot: snapshot,
+    pause() {
+      if (destroyed || paused) return
+      paused = true
+      cancelTimer()
+      emit()
+    },
+    reset(content = '') {
+      cancelTimer()
+      source = content
+      visible = content
+      pending.length = 0
+      pendingOffset = 0
+      done = false
+      paused = false
+      budget = 0
+      lastTick = Date.now()
+      emit()
+    },
+    resume() {
+      if (destroyed || !paused) return
+      paused = false
+      lastTick = Date.now()
+      emit()
+      schedule()
+    },
+    subscribe(listener) {
+      if (destroyed) return () => {}
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    }
+  }
+}
+
+export function createTextStream(options: TextStreamOptions = {}): TextStreamController {
+  if (typeof requestAnimationFrame !== 'function' || typeof cancelAnimationFrame !== 'function') {
+    return createTimerTextStream(options)
+  }
+
+  const controller = createSmoothMarkdownStream(options)
+  return {
+    destroy: controller.destroy,
+    enqueue: controller.enqueue,
+    finish: controller.finish,
+    flush: controller.flush,
+    getSnapshot: controller.getSnapshot,
+    pause: controller.pause,
+    reset: controller.reset,
+    resume: controller.resume,
+    subscribe: controller.subscribe
+  }
+}

package/src/type-guards.ts

@@ -0,0 +1,3 @@
+export function isUnknownRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}