From e6a51bc013378befc824d45a3cfa8d38b1ac3e07 Mon Sep 17 00:00:00 2001 From: Farnabaz Date: Fri, 20 Nov 2026 01:43:41 +0100 Subject: [PATCH 01/24] feat: introduce comark streaming effects --- AGENTS.md | 16 +- .../10.use-cases/2.ai-chat-streaming.md | 2 +- docs/content/3.rendering/3.vue.md | 23 +- docs/content/3.rendering/5.react.md | 23 +- docs/content/3.rendering/6.svelte.md | 23 +- docs/content/3.rendering/7.angular.md | 23 +- docs/content/5.reference/3.reference.md | 83 ++++ examples/2.vite/vue-streaming/src/App.vue | 9 + examples/4.ai/nuxt-ai-sdk/app/pages/index.vue | 1 + .../components/markdown-document.component.ts | 72 ++- .../src/components/markdown-node.component.ts | 402 ++++++++++++--- .../src/components/markdown.component.ts | 11 +- packages/comark-angular/src/define.ts | 4 + packages/comark-angular/src/utils/caret.ts | 49 -- packages/comark-angular/test/caret.test.ts | 50 -- .../test/stream-effects.test.ts | 81 +++ .../comark-react/src/components/Markdown.tsx | 14 +- .../src/components/MarkdownDocument.tsx | 62 ++- packages/comark-react/src/utils/caret.ts | 49 -- .../test/stream-effects.browser.test.tsx | 77 +++ .../src/async/MarkdownAsync.svelte | 9 +- .../src/components/Markdown.svelte | 11 +- .../src/components/MarkdownDocument.svelte | 43 +- .../src/components/MarkdownNode.svelte | 38 +- packages/comark-svelte/src/types.ts | 13 +- .../comark-svelte/test/MarkdownNode.test.ts | 3 +- .../test/stream-effects.svelte.test.ts | 35 ++ .../comark-vue/src/components/Markdown.ts | 35 +- .../src/components/MarkdownDocument.ts | 72 ++- packages/comark-vue/src/utils/caret.ts | 49 -- .../comark-vue/test/stream-effects.test.ts | 35 ++ packages/comark/package.json | 1 + packages/comark/src/internal/frontmatter.ts | 3 +- packages/comark/src/stream.ts | 462 ++++++++++++++++++ packages/comark/src/types.ts | 2 + packages/comark/src/utils/caret.ts | 47 -- packages/comark/test/stream.test.ts | 279 +++++++++++ 37 files changed, 1781 insertions(+), 430 deletions(-) delete mode 100644 packages/comark-angular/src/utils/caret.ts delete mode 100644 packages/comark-angular/test/caret.test.ts create mode 100644 packages/comark-angular/test/stream-effects.test.ts delete mode 100644 packages/comark-react/src/utils/caret.ts create mode 100644 packages/comark-react/test/stream-effects.browser.test.tsx create mode 100644 packages/comark-svelte/test/stream-effects.svelte.test.ts delete mode 100644 packages/comark-vue/src/utils/caret.ts create mode 100644 packages/comark-vue/test/stream-effects.test.ts create mode 100644 packages/comark/src/stream.ts delete mode 100644 packages/comark/src/utils/caret.ts create mode 100644 packages/comark/test/stream.test.ts diff --git a/AGENTS.md b/AGENTS.md index 7cd9c97ae..2dfc457be 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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) @@ -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 @@ -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, createStreamRenderer, resolveStreamEffects, getChildKeys } from 'comark/stream' +import type { StreamEffect, FadeOptions, CaretOptions } from 'comark/stream' import type { MarkdownDocument, Node, ElementNode, TextNode, CommentNode, NodeTransform } from 'comark' import { textContent, @@ -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 `caret`, `fade`, and `effects` and applies them through one `createStreamRenderer()` per component instance, in the order `fade`, custom `effects`, `caret` (`resolveStreamEffects`). + +- 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 `