Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
e6a51bc
feat: introduce comark streaming effects
farnabaz Nov 20, 2026
c5c3854
feat(stream): add pace, typewriter and fade effect updates
farnabaz Nov 20, 2026
2d2662e
feat(examples): add vite streaming example
farnabaz Nov 20, 2026
1e89a17
lint: fix
farnabaz Nov 20, 2026
bf0249c
fix(stream): address review findings in pace and reveal effects
ampagent Nov 20, 2026
587d176
fix(react): keep static MarkdownDocument server-safe and drain streams
ampagent Nov 20, 2026
71bfaac
fix(angular): address review findings in node patching
ampagent Nov 20, 2026
059bfe7
fix(svelte): keep frame scheduling active when effects return the sam…
ampagent Nov 20, 2026
aa18312
docs: document effect order, fade and pace options, first render
ampagent Nov 20, 2026
11bb4bb
fix(examples): streaming editor focus, typewriter speed and settle tr…
ampagent Nov 20, 2026
c3df4fb
test: update bundle size snapshot
ampagent Nov 20, 2026
05c6089
test: use clean-build file counts in bundle snapshot
ampagent Nov 20, 2026
de95bf8
fix(stream): keep per-chunk pace deadlines and reveal blocks added on…
ampagent Nov 20, 2026
8cf71bf
fix(angular): recreate a custom component after a failed update
ampagent Nov 20, 2026
0e638bc
docs: clarify when fade spans merge; disable pacing in misrender example
ampagent Nov 20, 2026
d7b0fa8
perf(stream): cache text lengths and skip settled blocks in pace and …
farnabaz Nov 20, 2026
2295b2a
feat(stream)!: flatten fade and typewriter options
farnabaz Nov 20, 2026
b853f62
chore: update bundle test
farnabaz Nov 20, 2026
ee12990
fix(stream): reuse cached text lengths only where the depth limit cut…
ampagent Nov 20, 2026
2d085b6
docs: clarify that paced backlog still fades after streaming ends
ampagent Nov 20, 2026
db181d3
test: update bundle size snapshot from CI
ampagent Nov 20, 2026
5d14436
fix: remove `caret` and other effects from being direct prop
farnabaz Nov 20, 2026
579b96e
test: update bundle size snapshot from CI
ampagent Nov 20, 2026
b774b5e
fix(benchmarks): keep stream effects bench within CodSpeed time limits
ampagent Nov 20, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 14 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ packages/comark/
│ ├── core.ts # Parser pipeline with no default plugins (comark/core)
│ ├── auto-close.ts # autoCloseMarkdown() (comark/auto-close)
│ ├── context.ts # Live renderer context: ComarkContext, ComarkDocument, ComarkPatch (comark/context)
│ ├── stream.ts # Render-time stream effects: caret, fade, createStreamRenderer (comark/stream)
│ ├── render/
│ │ ├── index.ts # AST to Markdown string: renderMarkdown() (comark/render)
│ │ └── html.ts # HTML-only string engine used by @comark/html (comark/render/html)
Expand Down Expand Up @@ -90,8 +91,7 @@ packages/comark/
│ ├── utils/ # Public utilities (comark/utils and comark/utils/trace)
│ │ ├── index.ts # textContent, visit, visitAsync, escapeHtml, isHtmlVoidElement, indent, applyNodeTransforms
│ │ ├── helpers.ts # defineComarkPlugin, dedupePlugins
│ │ ├── trace.ts # noopTracer, withSpan
│ │ └── caret.ts # Streaming caret helpers
│ │ └── trace.ts # noopTracer, withSpan
│ └── internal/ # Internal implementation (not exported)
│ ├── bracket-math.ts # `\( ... \)` and `\[ ... \]` delimiter scanners
│ ├── entities.ts # HTML attribute entity decoding via character-entities
Expand Down Expand Up @@ -168,6 +168,8 @@ import { parseMarkdown } from 'comark/core' // no default plugins; autoClose tak
import { autoCloseMarkdown } from 'comark/auto-close'
import { renderMarkdown } from 'comark/render'
import type { ComarkContext, ComarkDocument, ComarkPatch } from 'comark/context'
import { caret, fade, pace, typewriter, createStreamRenderer, getChildKeys } from 'comark/stream'
import type { StreamEffect, FadeOptions, CaretOptions } from 'comark/stream'
import type { MarkdownDocument, Node, ElementNode, TextNode, CommentNode, NodeTransform } from 'comark'
import {
textContent,
Expand Down Expand Up @@ -276,6 +278,16 @@ Contract: `packages/comark/SPEC/HTML/README.md`.
- `visit` and `visitAsync` stop at `TREE_WALK_MAX_DEPTH` (`50`).
- Deferred edge cases in `test/html-block.test.ts` are skipped tests; do not delete or weaken them.

### Stream effects (`comark/stream`)

Every framework renderer accepts a single `effects` prop (there are no `caret` or `fade` props; users import `caret()` and `fade()` from `comark/stream`) and applies it through one `createStreamRenderer()` per component instance, in array order. Put `pace()` first and `caret()` last.

- Effects run on the top-level nodes at render time and must never mutate them: copy only the changed path so reused streaming blocks keep their identity. Nodes an effect inserts carry `$.key`.
- `fade` diffs each top-level block's fadeable text against the previous render by common prefix, so restructuring never re-fades shown text. A block's spans merge back into text together once its last segment finishes, so spans are only appended while any is animating.
- Renderers key children with `getChildKeys()` (React, Vue, Angular), or index keys plus `{#key getStreamKey(node)}` (Svelte; changing key kinds at an index throws in Svelte's async `each`).
- Angular's `MarkdownNode` patches native subtrees in place (keyed by `getChildKeys()`) instead of rebuilding them, and skips re-creating custom components whose inputs are structurally equal.
- Effects inject their keyframes with `injectStreamStyles()` (constructable stylesheet, falling back to `<style>`); it is a no-op without a DOM.

### Render-time node transforms

Every renderer accepts `transformNode` (a function or array of functions returning `{ tag?, props? }`).
Expand Down
63 changes: 63 additions & 0 deletions benchmarks/stream-effects.bench.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
import { test } from 'vitest'
import { createMarkdownParser } from 'comark'
import type { Node } from 'comark'
import { caret, createStreamRenderer, fade, pace, typewriter } from 'comark/stream'
import type { StreamEffect } from 'comark/stream'
import { chatMarkdown, largeMarkdown, toStreamChunks } from './fixtures.ts'

const FRAME = 16
const MAX_DRAIN_FRAMES = 5000

async function snapshots(markdown: string, count: number): Promise<Node[][]> {
const parse = createMarkdownParser()
const out: Node[][] = []
for (const chunk of toStreamChunks(markdown, count)) {
out.push((await parse(chunk, { streaming: true })).nodes)
}
return out
}

const chatFrames = await snapshots(chatMarkdown, 24)
const largeFrames = await snapshots(largeMarkdown, 60)

const fadeEffects = [fade({ styles: false, speed: 400 }), caret()]
const fadeWordDelay = [fade({ styles: false, delay: 30, speed: 400 })]
const typewriterEffects = [typewriter({ styles: false, speed: 400 })]
const paceDrain = [pace({ speed: 4000 }), fade({ styles: false, pace: false }), caret()]

/** Feeds each snapshot one frame apart, then renders frames until no effect has queued work. */
function play(frames: Node[][], effects: readonly StreamEffect[]): void {
let time = 0
const stream = createStreamRenderer({ now: () => time })
for (const nodes of frames) {
stream.render(nodes, { streaming: true, effects })
time += FRAME
}
const last = frames[frames.length - 1]
stream.render(last, { streaming: false, effects })
for (let i = 0; i < MAX_DRAIN_FRAMES && stream.pending(); i++) {
time += FRAME
stream.render(last, { streaming: false, effects })
}
}

play(chatFrames, fadeEffects)
play(largeFrames, paceDrain)

// CodSpeed's CPU simulation runs these drains far slower than wall time, past Vitest's 60s default.
test('stream effects', { timeout: 300_000 }, async ({ bench }) => {
await bench.compare(
bench('fade and caret over a chat answer', () => {
play(chatFrames, fadeEffects)
}),
bench('delayed word fade over a large document', () => {
play(largeFrames, fadeWordDelay)
}),
bench('typewriter over a chat answer', () => {
play(chatFrames, typewriterEffects)
}),
bench('pace drain of a large document', () => {
play(largeFrames, paceDrain)
})
)
})
6 changes: 5 additions & 1 deletion docs/app/components/prose/LandingStreamingDemo.vue
Original file line number Diff line number Diff line change
@@ -1,4 +1,8 @@
<script setup lang="ts">
import { caret } from 'comark/stream'

const effects = [caret({ class: 'caret' })]

const POEM = `Awake! for **Morning in the Bowl of Night**
Has flung the Stone that puts the Stars to Flight:
And Lo! the \`Hunter of the East\` has caught
Expand Down Expand Up @@ -106,7 +110,7 @@ onBeforeUnmount(() => {
class="text-sm"
:value="streamedText"
:streaming="isStreaming"
:caret="{ class: 'caret' }"
:effects="effects"
/>
</div>
</template>
4 changes: 3 additions & 1 deletion docs/app/pages/stream.vue
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
<script setup lang="ts">
import { computed, nextTick, ref } from 'vue'
import { caret } from 'comark/stream'
import { useMDCStream } from '../composables/useMDCStream'
import { stringToStream } from '../composables/stringToStream'
import resolveComponent from '../utils/components-manifest'
Expand All @@ -8,6 +9,7 @@ import landingMD from '~~/content/index.md?raw'
definePageMeta({
footer: false,
})
const effects = [caret()]
const title = 'Streaming Markdown Demo'
const description =
'See Comark streaming in action. Watch markdown content parse and render in real-time as it arrives.'
Expand Down Expand Up @@ -178,7 +180,7 @@ function reset() {
:value="state.content"
:components-manifest="resolveComponent"
:streaming="Boolean(streamController)"
caret
:effects="effects"
/>
<div
v-else
Expand Down
8 changes: 6 additions & 2 deletions docs/content/10.use-cases/1.intelligent-ui.md
Original file line number Diff line number Diff line change
Expand Up @@ -163,31 +163,35 @@ Register the components, and render each text part with `streaming` set from the
```vue [Message.vue]
<script setup lang="ts">
import { Markdown } from '@comark/vue'
import { caret } from 'comark/stream'
import QuantityCalculator from './QuantityCalculator.vue'
import Timeline from './Timeline.vue'

defineProps<{ text: string, isStreaming: boolean }>()

const components = { 'quantity-calculator': QuantityCalculator, timeline: Timeline }
const effects = [caret()]
</script>

<template>
<Suspense>
<Markdown :value="text" :streaming="isStreaming" :components="components" caret />
<Markdown :value="text" :streaming="isStreaming" :components="components" :effects="effects" />
</Suspense>
</template>
```

```tsx [Message.tsx]
'use client'
import { MarkdownClient } from '@comark/react'
import { caret } from 'comark/stream'
import { QuantityCalculator } from './QuantityCalculator'
import { Timeline } from './Timeline'

const components = { 'quantity-calculator': QuantityCalculator, timeline: Timeline }
const effects = [caret()]

export function Message({ text, isStreaming }: { text: string, isStreaming: boolean }) {
return <MarkdownClient value={text} streaming={isStreaming} components={components} caret />
return <MarkdownClient value={text} streaming={isStreaming} components={components} effects={effects} />
}
```

Expand Down
30 changes: 22 additions & 8 deletions docs/content/10.use-cases/2.ai-chat-streaming.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,60 +26,71 @@ An LLM sends Markdown in small chunks. Most chunks end in the middle of a constr
- **`autoClose`** is on by default in every renderer. It closes unterminated bold, italic, inline code, links, tables, and components before each parse. An open code fence renders as a code block that grows until the fence closes. An incomplete link gets the placeholder URL `comark:incomplete-link`.
- **`streaming`** turns on incremental parsing. Comark reuses the output of completed blocks, drops a half-typed opener at the end, and keeps the previous output if a parse fails.

Set `streaming` back to `false` when the stream ends. Comark then runs a final full parse. The `caret` prop adds a blinking cursor to the last text node while `streaming` is `true`.
Set `streaming` back to `false` when the stream ends. Comark then runs a final full parse. While `streaming` is `true`, the `caret()` effect from `comark/stream` adds a blinking cursor to the last text node, and the `fade()` effect fades in each new chunk of text. Pass them through the `effects` prop. See [Stream effects](/reference/reference#stream-effects) for options and custom effects.

## Render a streaming message

Each renderer takes the same three inputs: the text, a `streaming` flag, and an optional `caret`:
Each renderer takes the same three inputs: the text, a `streaming` flag, and optional `effects` such as `caret()`:

::code-group

```vue [Vue]
<script setup lang="ts">
import { Markdown } from '@comark/vue'
import { caret } from 'comark/stream'

defineProps<{ text: string, isStreaming: boolean }>()

const effects = [caret()]
</script>

<template>
<Suspense>
<Markdown :value="text" :streaming="isStreaming" caret />
<Markdown :value="text" :streaming="isStreaming" :effects="effects" />
</Suspense>
</template>
```

```tsx [React]
'use client'
import { MarkdownClient } from '@comark/react'
import { caret } from 'comark/stream'

const effects = [caret()]

export function Message({ text, isStreaming }: { text: string, isStreaming: boolean }) {
return <MarkdownClient value={text} streaming={isStreaming} caret />
return <MarkdownClient value={text} streaming={isStreaming} effects={effects} />
}
```

```svelte [Svelte]
<script lang="ts">
import { Markdown } from '@comark/svelte'
import { caret } from 'comark/stream'

let { text, isStreaming }: { text: string, isStreaming: boolean } = $props()

const effects = [caret()]
</script>

<Markdown value={text} streaming={isStreaming} caret />
<Markdown value={text} streaming={isStreaming} {effects} />
```

```typescript [Angular]
import { Component, Input } from '@angular/core'
import { Markdown } from '@comark/angular'
import { caret } from 'comark/stream'

@Component({
selector: 'app-message',
standalone: true,
imports: [Markdown],
template: `<comark-markdown [value]="text" [streaming]="isStreaming" [caret]="true" />`,
template: `<comark-markdown [value]="text" [streaming]="isStreaming" [effects]="effects" />`,
})
export class MessageComponent {
@Input() text = ''
@Input() isStreaming = false
effects = [caret()]
}
```

Expand All @@ -96,6 +107,9 @@ The [AI SDK](https://ai-sdk.dev/docs) splits each message into `parts`. A text p
import { useState } from 'react'
import { useChat } from '@ai-sdk/react'
import { MarkdownClient } from '@comark/react'
import { caret } from 'comark/stream'

const effects = [caret()]

export default function Chat() {
const { messages, sendMessage } = useChat()
Expand All @@ -106,7 +120,7 @@ export default function Chat() {
<div key={message.id}>
{message.parts.map((part, index) =>
part.type === 'text'
? <MarkdownClient key={index} value={part.text} streaming={part.state === 'streaming'} caret />
? <MarkdownClient key={index} value={part.text} streaming={part.state === 'streaming'} effects={effects} />
: null
)}
</div>
Expand All @@ -131,7 +145,7 @@ Add the [security plugin](/plugins/built-in/security). It always strips `on*` at
import security from '@comark/react/plugins/security'

const plugins = [security({ blockedTags: ['script', 'iframe', 'embed', 'form', 'base', 'meta', 'link', 'style', 'object'] })]
// <MarkdownClient value={part.text} streaming={part.state === 'streaming'} plugins={plugins} caret />
// <MarkdownClient value={part.text} streaming={part.state === 'streaming'} plugins={plugins} effects={effects} />
```

Define `plugins` outside the component, so the reference stays stable between renders. Import the same plugin from `@comark/vue/plugins/security` or `@comark/svelte/plugins/security`, or as `{ security }` from `@comark/angular/plugins/security`. To turn off raw HTML parsing, set `registerDefaultPlugins: false` and register only the plugins you need, without `html`.
Expand Down
13 changes: 10 additions & 3 deletions docs/content/10.use-cases/3.vue-ai-chat.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,9 +70,11 @@ The server API can change between AI SDK versions. Check the [AI SDK docs](https
```vue [app/pages/index.vue]
<script setup lang="ts">
import { Chat } from '@ai-sdk/vue'
import { caret } from 'comark/stream'

const chat = new Chat({})
const input = ref('')
const effects = [caret()]

function onSubmit() {
chat.sendMessage({ text: input.value })
Expand All @@ -86,7 +88,7 @@ function onSubmit() {
<template v-if="part.type === 'text'">
<p v-if="message.role === 'user'">{{ part.text }}</p>
<Suspense v-else>
<Markdown :value="part.text" :streaming="part.state === 'streaming'" caret />
<Markdown :value="part.text" :streaming="part.state === 'streaming'" :effects="effects" />
</Suspense>
</template>
</template>
Expand All @@ -109,11 +111,14 @@ The [full example](/examples/ai/nuxt-ai-sdk) uses Nuxt UI chat components, such
```vue [app/pages/index.vue]
<script setup lang="ts">
import { isPartStreaming } from '@nuxt/ui/utils/ai'
import { caret } from 'comark/stream'

const effects = [caret()]
</script>

<template>
<Suspense>
<Markdown :value="part.text" :streaming="isPartStreaming(part)" caret />
<Markdown :value="part.text" :streaming="isPartStreaming(part)" :effects="effects" />
</Suspense>
</template>
```
Expand All @@ -128,7 +133,9 @@ Pass components and plugins to `<Markdown>`, for example to highlight code in an
<script setup lang="ts">
import shiki from '@comark/vue/plugins/shiki'
import security from '@comark/vue/plugins/security'
import { caret } from 'comark/stream'

const effects = [caret()]
const plugins = [
shiki(),
security({ blockedTags: ['script', 'iframe', 'embed', 'form', 'base', 'meta', 'link', 'style', 'object'] }),
Expand All @@ -137,7 +144,7 @@ const plugins = [

<template>
<Suspense>
<Markdown :value="part.text" :streaming="part.state === 'streaming'" :plugins="plugins" caret />
<Markdown :value="part.text" :streaming="part.state === 'streaming'" :plugins="plugins" :effects="effects" />
</Suspense>
</template>
```
Expand Down
10 changes: 7 additions & 3 deletions docs/content/10.use-cases/4.svelte-ai-chat.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ links:
variant: soft
---

Use the `Chat` class from `@ai-sdk/svelte` to receive messages, and render each text part with `<Markdown value streaming caret />` from `@comark/svelte`. Comark closes unfinished syntax on every update, and runs a full parse when `streaming` becomes `false`.
Use the `Chat` class from `@ai-sdk/svelte` to receive messages, and render each text part with `<Markdown value streaming {effects} />` from `@comark/svelte`, with a `caret()` effect from `comark/stream`. Comark closes unfinished syntax on every update, and runs a full parse when `streaming` becomes `false`.

This guide uses Svelte 5 and SvelteKit. It assumes that you have a SvelteKit app and an AI provider key.

Expand Down Expand Up @@ -63,9 +63,11 @@ Pass `part.state === 'streaming'` to the `streaming` prop. Each part then runs i
<script lang="ts">
import { Chat } from '@ai-sdk/svelte'
import { Markdown } from '@comark/svelte'
import { caret } from 'comark/stream'

let input = $state('')
const chat = new Chat({})
const effects = [caret()]

function handleSubmit(event: SubmitEvent) {
event.preventDefault()
Expand All @@ -80,7 +82,7 @@ Pass `part.state === 'streaming'` to the `streaming` prop. Each part then runs i
{#if message.role === 'user'}
<p>{part.text}</p>
{:else}
<Markdown value={part.text} streaming={part.state === 'streaming'} caret />
<Markdown value={part.text} streaming={part.state === 'streaming'} {effects} />
{/if}
{/if}
{/each}
Expand Down Expand Up @@ -128,11 +130,13 @@ Raw HTML in model output is parsed into nodes by default. Add the [security plug
```svelte
<script lang="ts">
import security from '@comark/svelte/plugins/security'
import { caret } from 'comark/stream'

const effects = [caret()]
const plugins = [security({ blockedTags: ['script', 'iframe', 'embed', 'form', 'base', 'meta', 'link', 'style', 'object'] })]
</script>

<Markdown value={part.text} streaming={part.state === 'streaming'} {plugins} caret />
<Markdown value={part.text} streaming={part.state === 'streaming'} {plugins} {effects} />
```

## FAQ
Expand Down
Loading
Loading