Types & Exports

The text-diff API is exported from the package root. Optional syntax-highlighted code diffs use the separate @humanspeak/svelte-diff/code entry.

import SvelteDiff, {
    SvelteDiff as NamedSvelteDiff,
    computeDiff,
    type SvelteDiffComputeOptions,
    type SvelteDiffResult,
    type SvelteDiffProps,
    type SvelteDiffMode,
    type SvelteDiffTiming,
    type SvelteDiffTuple,
    type Renderers,
    type RendererClasses,
    type CaptureRange,
    type DisplayDiff,
    type PatternMatchResult
} from '@humanspeak/svelte-diff'

import SvelteDiff, {
    SvelteDiff as NamedSvelteDiff,
    computeDiff,
    type SvelteDiffComputeOptions,
    type SvelteDiffResult,
    type SvelteDiffProps,
    type SvelteDiffMode,
    type SvelteDiffTiming,
    type SvelteDiffTuple,
    type Renderers,
    type RendererClasses,
    type CaptureRange,
    type DisplayDiff,
    type PatternMatchResult
} from '@humanspeak/svelte-diff'

Components

Optional code entry

import CodeDiff, {
    CodeDiff as NamedCodeDiff,
    type CodeDiffProps
} from '@humanspeak/svelte-diff/code'

import CodeDiff, {
    CodeDiff as NamedCodeDiff,
    type CodeDiffProps
} from '@humanspeak/svelte-diff/code'

The exported CodeDiffProps type has the following shape:

import type { SvelteDiffMode } from '@humanspeak/svelte-diff'
import type { Highlighter } from '@tanstack/highlight/core'

interface CodeDiffProps {
    originalText: string
    modifiedText: string
    highlighter: Pick<Highlighter, 'tokenize'>
    language?: string
    diffMode?: SvelteDiffMode
    timeout?: number
    cleanupSemantic?: boolean
    cleanupEfficiency?: number
    class?: string
    ariaLabel?: string
    rendererClasses?: { remove?: string; insert?: string }
}

import type { SvelteDiffMode } from '@humanspeak/svelte-diff'
import type { Highlighter } from '@tanstack/highlight/core'

interface CodeDiffProps {
    originalText: string
    modifiedText: string
    highlighter: Pick<Highlighter, 'tokenize'>
    language?: string
    diffMode?: SvelteDiffMode
    timeout?: number
    cleanupSemantic?: boolean
    cleanupEfficiency?: number
    class?: string
    ariaLabel?: string
    rendererClasses?: { remove?: string; insert?: string }
}

CodeDiff defaults to word mode, plaintext, timeout 1, semantic cleanup false, and efficiency 0. ariaLabel defaults to Code differences. Source is always literal. The root does not re-export this component or load optional TanStack at runtime. See the CodeDiff API and guide.

SvelteDiffMode

type SvelteDiffMode = 'character' | 'word' | 'line'

type SvelteDiffMode = 'character' | 'word' | 'line'

SvelteDiffProps.diffMode is optional and defaults to character. Deprecated prop aliases inherit it. Sentence and JSON are not accepted. See Diff Modes.

computeDiff, SvelteDiffComputeOptions, and SvelteDiffResult

Use the helper through the Svelte-aware package root within a Svelte toolchain; the entry requires Svelte-aware module resolution and compilation. Each call owns its engine and returns synchronously without mounting a component.

interface SvelteDiffComputeOptions {
    diffMode?: SvelteDiffMode
    timeout?: number
    cleanupSemantic?: boolean
    cleanupEfficiency?: number
    expectedPatterns?: boolean
}

interface SvelteDiffResult {
    timing: SvelteDiffTiming
    diffs: SvelteDiffTuple[]
    displayDiffs: DisplayDiff[]
    captures?: Record<string, string>
}

const result: SvelteDiffResult = computeDiff(before, after, { diffMode: 'line' })

interface SvelteDiffComputeOptions {
    diffMode?: SvelteDiffMode
    timeout?: number
    cleanupSemantic?: boolean
    cleanupEfficiency?: number
    expectedPatterns?: boolean
}

interface SvelteDiffResult {
    timing: SvelteDiffTiming
    diffs: SvelteDiffTuple[]
    displayDiffs: DisplayDiff[]
    captures?: Record<string, string>
}

const result: SvelteDiffResult = computeDiff(before, after, { diffMode: 'line' })

Helper defaults are character mode, timeout 1 second, semantic cleanup false, efficiency edit cost 4, and expectedPatterns false. The component defaults expectedPatterns to true. Explicit true uses the same template resolution, mismatch placeholders, and capture tagging as the component. False bypasses parsing entirely: omitting inserts reconstructs the exact original input; omitting removals reconstructs the exact modified input. Captures are undefined and display segments have no expected tags. Semantic cleanup takes priority over efficiency in character mode; word/line skip both.

SvelteDiffTiming

type SvelteDiffTiming = {
    main: number
    cleanup: number
    total: number
}

type SvelteDiffTiming = {
    main: number
    cleanup: number
    total: number
}

All values are milliseconds. For character mode, main measures the core algorithm and cleanup measures the selected cleanup pass. For word/line, main includes tokenization, encoding, diffing, and decoding; cleanup is exactly zero. total covers the timed computation, excluding expected-pattern preprocessing and DOM rendering.

SvelteDiffTuple

Tuples always contain original text, never encoded IDs. With expected patterns, the source projection is resolved/cleaned source. Capture annotations can split displayed tokens without changing raw tuples.

An alias for Diff from diff-match-patch-ts. Each tuple is an operation and its text:

type SvelteDiffTuple = [operation: -1 | 0 | 1, text: string]

type SvelteDiffTuple = [operation: -1 | 0 | 1, text: string]

• -1 — removed
• 0 — equal
• 1 — inserted

Renderers

type Renderers = {
    remove?: Snippet<[string]>
    equal?: Snippet<[string]>
    insert?: Snippet<[string]>
    expected?: Snippet<[string, string]>
    lineBreak?: Snippet<[]>
}

type Renderers = {
    remove?: Snippet<[string]>
    equal?: Snippet<[string]>
    insert?: Snippet<[string]>
    expected?: Snippet<[string, string]>
    lineBreak?: Snippet<[]>
}

The expected renderer receives both the matched text and its named capture-group name.

RendererClasses

type RendererClasses = {
    remove?: string
    equal?: string
    insert?: string
    expected?: string
}

type RendererClasses = {
    remove?: string
    equal?: string
    insert?: string
    expected?: string
}

Classes only affect built-in fallbacks. When you replace a segment with a snippet, that snippet owns its own classes.

Expected-pattern types

CaptureRange describes a named match inside the modified string. DisplayDiff is an internal-rendering-shaped segment that may carry an expected group name. PatternMatchResult combines resolved template text, captured values, and capture ranges.

interface PatternMatchResult {
    resolvedText: string
    captures: Record<string, string>
    captureRanges: CaptureRange[]
}

interface PatternMatchResult {
    resolvedText: string
    captures: Record<string, string>
    captureRanges: CaptureRange[]
}

These are exported for integrations that want to share the component’s expected-region concepts without duplicating type definitions.