@incremark/core

Framework-agnostic core parser library.

Installation

pnpm add @incremark/core

IncremarkParser

Incremental Markdown parser class.

Constructor

new IncremarkParser(options?: ParserOptions)

Methods

append(chunk)

Append content and return incremental update.

append(chunk: string): IncrementalUpdate

Parameters:

• chunk - Text fragment to append

Returns:

• IncrementalUpdate - Block information for this update

finalize()

Mark parsing as complete, process remaining pending content.

finalize(): IncrementalUpdate

reset()

Reset parser state.

reset(): void

render(content)

One-shot render complete Markdown (reset + append + finalize).

render(content: string): IncrementalUpdate

Parameters:

• content - Complete Markdown content

Returns:

• IncrementalUpdate - Parse result

getBuffer()

Get current buffer content.

getBuffer(): string

getCompletedBlocks()

Get all completed blocks.

getCompletedBlocks(): ParsedBlock[]

getAst()

Get current complete AST.

getAst(): Root

setOnChange(callback)

Set state change callback (for DevTools).

setOnChange(callback: ((state: ParserState) => void) | undefined): void

createIncremarkParser

Factory function to create parser instance.

function createIncremarkParser(options?: ParserOptions): IncremarkParser

BlockTransformer

Typewriter effect controller, acting as middleware between parser and renderer.

Constructor

new BlockTransformer(options?: TransformerOptions)

Methods

push(blocks)

Push source blocks to queue.

push(blocks: SourceBlock[]): void

update(block)

Update currently displaying block content (for growing pending blocks).

update(block: SourceBlock): void

skip()

Skip all animations, display all content immediately.

skip(): void

reset()

Reset state.

reset(): void

destroy()

Destroy transformer, clean up timers.

destroy(): void

isProcessing()

Check if currently processing.

isProcessing(): boolean

setOptions(options)

Dynamically update configuration.

setOptions(options: { charsPerTick?: number; tickInterval?: number }): void

createBlockTransformer

Factory function to create BlockTransformer instance.

function createBlockTransformer(options?: TransformerOptions): BlockTransformer

Plugin System

BlockTransformer supports plugins to handle special node types.

Built-in Plugins

Plugin	Description	Behavior
imagePlugin	Images	Display immediately (0 chars)
thematicBreakPlugin	Thematic breaks	Display immediately (0 chars)
codeBlockPlugin	Code blocks	Display as whole (1 char)
mermaidPlugin	Mermaid diagrams	Display as whole (1 char)
mathPlugin	Math formulas	Display as whole (1 char)

Plugin Collections

// Default plugins: images and breaks display immediately, others participate in typewriter
import { defaultPlugins } from '@incremark/core'

// All plugins: code blocks, mermaid, math also display as whole
import { allPlugins } from '@incremark/core'

Custom Plugins

import { createPlugin } from '@incremark/core'

const myPlugin = createPlugin(
  'my-plugin',
  (node) => node.type === 'myType',
  {
    countChars: (node) => 1,
    sliceNode: (node, displayed, total) => node
  }
)

TransformerPlugin Interface

interface TransformerPlugin {
  name: string
  match: (node: RootContent) => boolean
  countChars?: (node: RootContent) => number
  sliceNode?: (node: RootContent, displayedChars: number, totalChars: number) => RootContent | null
}

Utility Functions

countChars(node)

Count displayable characters in a node.

function countChars(node: RootContent): number

sliceAst(node, chars)

Slice node by character count.

function sliceAst(node: RootContent, chars: number): RootContent | null

cloneNode(node)

Deep clone a node.

function cloneNode<T>(node: T): T

Type Definitions

ParserOptions

interface ParserOptions {
  /** Enable GFM extension */
  gfm?: boolean
  /** Enable ::: container syntax */
  containers?: boolean | ContainerConfig
  /** Custom block boundary detection function */
  blockBoundaryDetector?: (content: string, position: number) => boolean
  /** micromark extensions */
  extensions?: Extension[]
  /** mdast extensions */
  mdastExtensions?: Extension[]
  /** State change callback */
  onChange?: (state: ParserState) => void
}

TransformerOptions

interface TransformerOptions {
  /** Characters per tick (default: 2) */
  charsPerTick?: number
  /** Tick interval in ms (default: 50) */
  tickInterval?: number
  /** Plugin list */
  plugins?: TransformerPlugin[]
  /** State change callback */
  onChange?: (blocks: DisplayBlock[]) => void
}

ParsedBlock

interface ParsedBlock {
  /** Unique block ID */
  id: string
  /** Block status */
  status: BlockStatus
  /** AST node */
  node: RootContent
  /** Raw text start offset */
  startOffset: number
  /** Raw text end offset */
  endOffset: number
  /** Raw text content */
  rawText: string
}

SourceBlock

interface SourceBlock<T = unknown> {
  id: string
  node: RootContent
  status: 'pending' | 'stable' | 'completed'
  meta?: T
}

DisplayBlock

interface DisplayBlock<T = unknown> {
  id: string
  sourceNode: RootContent
  displayNode: RootContent
  displayedChars: number
  totalChars: number
  isDisplayComplete: boolean
  meta?: T
}

BlockStatus

type BlockStatus = 'pending' | 'stable' | 'completed'

IncrementalUpdate

interface IncrementalUpdate {
  /** Newly completed blocks */
  completed: ParsedBlock[]
  /** Updated blocks */
  updated: ParsedBlock[]
  /** Pending blocks */
  pending: ParsedBlock[]
  /** Complete AST */
  ast: Root
}

Detector Functions

detectFenceStart

Detect code block start.

function detectFenceStart(line: string): { char: string; length: number; indent: number } | null

detectFenceEnd

Detect code block end.

function detectFenceEnd(line: string, fenceChar: string, fenceLength: number): boolean

isEmptyLine

Detect empty line.

function isEmptyLine(line: string): boolean

isHeading

Detect heading line.

function isHeading(line: string): boolean

isThematicBreak

Detect thematic break.

function isThematicBreak(line: string): boolean

isListItemStart

Detect list item start.

function isListItemStart(line: string): boolean

isBlockquoteStart

Detect blockquote start.

function isBlockquoteStart(line: string): boolean