markstream-core

Framework-agnostic smooth streaming controller and streaming text state utilities for Markstream.

This package extracts the core pacing algorithm and streaming text resolution logic shared across all Markstream framework packages (Vue 3, Vue 2, React, Angular, Svelte).

Installation

npm install markstream-core

API

createSmoothMarkdownStream

Factory API for a framework-agnostic streaming controller with snapshot + subscribe semantics.

import { createSmoothMarkdownStream } from 'markstream-core'

const controller = createSmoothMarkdownStream({ minCharsPerSecond: 40, maxCharsPerSecond: 1000 })

const unsubscribe = controller.subscribe(() => {
  const snapshot = controller.getSnapshot()
  updateUI(snapshot.visible)
  if (snapshot.final)
    onStreamDone()
})

controller.enqueue(chunk)
controller.finish()
controller.flush()
controller.pause()
controller.resume()
controller.destroy()
controller.dispose() // alias of destroy()
unsubscribe()

SmoothMarkdownStreamController is the public controller interface type returned by createSmoothMarkdownStream.

Options (SmoothMarkdownStreamOptions)

| Option | Default | Description | |---|---|---| | minCharsPerSecond | 40 | Minimum reveal speed | | maxCharsPerSecond | 1000 | Maximum reveal speed | | targetLatencyMs | 900 | Target latency for pacing calculation | | catchUpLatencyMs | 350 | Latency threshold for catch-up mode | | catchUpThreshold | 600 | Character backlog that triggers catch-up | | maxCommitFps | 30 | Maximum commits per second | | startDelayMs | 80 | Delay before first reveal | | maxCharsPerCommit | 80 | Maximum characters per animation frame | | flushOnFinish | false | Auto-flush when finish() is called |

resolveStreamingTextState

Resolves the next streaming text state for simple append detection.

import { resolveStreamingTextState } from 'markstream-core'

const result = resolveStreamingTextState({
  nextContent: 'hello world',
  previousContent: 'hello',
  typewriterEnabled: true,
})
// result = { settledContent: 'hello', streamedDelta: ' world', appended: true }

resolveStreamingTextUpdate

Extended resolver that handles React StrictMode replay guards and stream version resets.

import { resolveStreamingTextUpdate } from 'markstream-core'

const result = resolveStreamingTextUpdate({
  nextContent: 'hello world!',
  currentState: { settledContent: 'hello', streamedDelta: ' world' },
  typewriterEnabled: true,
})

Shiki Highlighting Helpers

markstream-core exports shared helpers used by Markstream adapters to normalize Shiki language and theme options before calling stream-markdown.

import {
  getHighlightRegistrationKey,
  getRegisterHighlightOptions,
  getRuntimeShikiRegistrationConfig,
  getShikiLangs,
  getShikiRendererOptions,
  getShikiThemes,
  normalizeShikiLanguage,
  registerHighlightOnce,
} from 'markstream-core'

• getShikiLangs(langs) normalizes common Shiki language aliases, removes duplicates, and sorts the result because language preload order has no priority semantics.
• getShikiThemes(themes) keeps valid string themes, removes duplicates, and preserves caller order so theme priority is not changed.
• getRegisterHighlightOptions(themes, langs) and getShikiRendererOptions(themes, langs) return normalized options for registerHighlight() and createShikiStreamRenderer().
• getHighlightRegistrationKey(themes, langs) returns a normalized key. Language order is stable for equivalent preload sets, while theme order is preserved because renderer theme priority is order-sensitive.
• getRuntimeShikiRegistrationConfig(themes, langs, options) returns framework-neutral runtime config for adapters that may have a renderer without registerHighlight().
• registerHighlightOnce(registerHighlight, opts, key) coalesces in-flight registrations for the same registerHighlight function and key.

Framework Adapters

• Vue 3: useSmoothMarkdownStream in markstream-vue wraps the core controller with Vue reactivity.
• React / Vue 2 / Angular / Svelte: Framework packages depend on markstream-core internally. Import core APIs directly from markstream-core when needed.

License

MIT