@humanspeak/svelte-markdown 1.0.1 → 1.0.3

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2024-2025 Humanspeak, Inc.
+Copyright (c) 2024-2026 Humanspeak, Inc.
 
 Copyright (c) 2020-2024 Pablo Berganza
 

package/README.md

@@ -25,7 +25,7 @@ A powerful, customizable markdown renderer for Svelte with TypeScript support. B
 - ♿ WCAG 2.1 accessibility compliance
 - 🎯 GitHub-style slug generation for headers
 - 🧪 Comprehensive test coverage (vitest and playwright)
-- 🎨 Custom Marked extensions support (e.g., GitHub-style alerts)
+- 🧩 First-class marked extensions support via `extensions` prop (e.g., KaTeX math, alerts)
 - ⚡ Intelligent token caching (50-200x faster re-renders)
 - 🖼️ Smart image lazy loading with fade-in animation
 
@@ -72,7 +72,8 @@ import type {
     Renderers,
     Token,
     TokensList,
-    SvelteMarkdownOptions
+    SvelteMarkdownOptions,
+    MarkedExtension
 } from '@humanspeak/svelte-markdown'
 ```
 
@@ -352,6 +353,158 @@ You can render arbitrary (non-standard) HTML tags like `<click>`, `<tooltip>`, o
 
 Both approaches work for any tag name. Snippet overrides take precedence over component renderers when both are provided.
 
+## Marked Extensions
+
+Use third-party [marked extensions](https://marked.js.org/using_advanced#extensions) via the `extensions` prop. The component handles registering tokenizers internally — you just provide renderers for the custom token types.
+
+### KaTeX Math Rendering
+
+```bash
+npm install marked-katex-extension katex
+```
+
+**Component renderer approach:**
+
+```svelte
+<script lang="ts">
+    import SvelteMarkdown from '@humanspeak/svelte-markdown'
+    import type { RendererComponent, Renderers } from '@humanspeak/svelte-markdown'
+    import markedKatex from 'marked-katex-extension'
+    import KatexRenderer from './KatexRenderer.svelte'
+
+    interface KatexRenderers extends Renderers {
+        inlineKatex: RendererComponent
+        blockKatex: RendererComponent
+    }
+
+    const renderers: Partial<KatexRenderers> = {
+        inlineKatex: KatexRenderer,
+        blockKatex: KatexRenderer
+    }
+</script>
+
+<svelte:head>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.28/dist/katex.min.css" crossorigin="anonymous" />
+</svelte:head>
+
+<SvelteMarkdown
+    source="Euler's identity: $e^{{i\pi}} + 1 = 0$"
+    extensions={[markedKatex({ throwOnError: false })]}
+    {renderers}
+/>
+```
+
+Where `KatexRenderer.svelte` is:
+
+```svelte
+<script lang="ts">
+    import katex from 'katex'
+
+    interface Props {
+        text: string
+        displayMode?: boolean
+    }
+    const { text, displayMode = false }: Props = $props()
+
+    const html = $derived(katex.renderToString(text, { throwOnError: false, displayMode }))
+</script>
+
+{@html html}
+```
+
+**Snippet override approach** (no separate component file needed):
+
+```svelte
+<script lang="ts">
+    import SvelteMarkdown from '@humanspeak/svelte-markdown'
+    import katex from 'katex'
+    import markedKatex from 'marked-katex-extension'
+</script>
+
+<svelte:head>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.28/dist/katex.min.css" crossorigin="anonymous" />
+</svelte:head>
+
+<SvelteMarkdown
+    source="Euler's identity: $e^{{i\pi}} + 1 = 0$"
+    extensions={[markedKatex({ throwOnError: false })]}
+>
+    {#snippet inlineKatex(props)}
+        {@html katex.renderToString(props.text, { displayMode: false })}
+    {/snippet}
+    {#snippet blockKatex(props)}
+        {@html katex.renderToString(props.text, { displayMode: true })}
+    {/snippet}
+</SvelteMarkdown>
+```
+
+### Mermaid Diagrams (Async Rendering)
+
+The package includes built-in `markedMermaid` and `MermaidRenderer` helpers for Mermaid diagram support. Install mermaid as an optional peer dependency:
+
+```bash
+npm install mermaid
+```
+
+Then use the built-in helpers — no boilerplate needed:
+
+```svelte
+<script lang="ts">
+    import SvelteMarkdown from '@humanspeak/svelte-markdown'
+    import type { RendererComponent, Renderers } from '@humanspeak/svelte-markdown'
+    import { markedMermaid, MermaidRenderer } from '@humanspeak/svelte-markdown/extensions'
+
+    // markdown containing fenced mermaid code blocks
+    let { source } = $props()
+
+    interface MermaidRenderers extends Renderers {
+        mermaid: RendererComponent
+    }
+
+    const renderers: Partial<MermaidRenderers> = {
+        mermaid: MermaidRenderer
+    }
+</script>
+
+<SvelteMarkdown {source} extensions={[markedMermaid()]} {renderers} />
+```
+
+`markedMermaid()` is a zero-dependency tokenizer that converts ` ```mermaid ` code blocks into custom tokens. `MermaidRenderer` lazy-loads mermaid in the browser, renders SVG asynchronously, and automatically re-renders when dark/light mode changes.
+
+You can also use snippet overrides to wrap `MermaidRenderer` with custom markup:
+
+```svelte
+<SvelteMarkdown source={markdown} extensions={[markedMermaid()]}>
+    {#snippet mermaid(props)}
+        <div class="my-diagram-wrapper">
+            <MermaidRenderer text={props.text} />
+        </div>
+    {/snippet}
+</SvelteMarkdown>
+```
+
+Since Mermaid rendering is async, the snippet delegates to `MermaidRenderer` rather than calling `mermaid.render()` directly. This pattern works for any async extension — keep the async logic in a component and use the snippet for layout customization.
+
+### How It Works
+
+Marked extensions define custom token types with a `name` property (e.g., `inlineKatex`, `blockKatex`, `alert`). When you pass extensions via the `extensions` prop, SvelteMarkdown automatically extracts these token type names and makes them available as both **component renderer keys** and **snippet override names**.
+
+To find the token type names for any extension, check its source or documentation for the `name` field in its `extensions` array:
+
+```js
+// Example: marked-katex-extension registers tokens named "inlineKatex" and "blockKatex"
+// → use renderers={{ inlineKatex: ..., blockKatex: ... }}
+// → or {#snippet inlineKatex(props)} and {#snippet blockKatex(props)}
+
+// Example: a custom alert extension registers a token named "alert"
+// → use renderers={{ alert: AlertComponent }}
+// → or {#snippet alert(props)}
+```
+
+Each snippet/component receives the token's properties as props (e.g., `text`, `displayMode` for KaTeX; `text`, `level` for alerts).
+
+See the [full documentation](https://markdown.svelte.page/docs/advanced/marked-extensions) and [interactive demo](https://markdown.svelte.page/examples/marked-extensions).
+
 ### TypeScript
 
 All snippet prop types are exported for use in external components:
@@ -526,12 +679,13 @@ The component emits a `parsed` event when tokens are calculated:
 
 ## Props
 
-| Prop      | Type                    | Description                           |
-| --------- | ----------------------- | ------------------------------------- |
-| source    | `string \| Token[]`     | Markdown content or pre-parsed tokens |
-| renderers | `Partial<Renderers>`    | Custom component overrides            |
-| options   | `SvelteMarkdownOptions` | Marked parser configuration           |
-| isInline  | `boolean`               | Toggle inline parsing mode            |
+| Prop       | Type                    | Description                                      |
+| ---------- | ----------------------- | ------------------------------------------------ |
+| source     | `string \| Token[]`     | Markdown content or pre-parsed tokens            |
+| renderers  | `Partial<Renderers>`    | Custom component overrides                       |
+| options    | `SvelteMarkdownOptions` | Marked parser configuration                      |
+| isInline   | `boolean`               | Toggle inline parsing mode                       |
+| extensions | `MarkedExtension[]`     | Third-party marked extensions (e.g., KaTeX math) |
 
 ## Security
 

package/dist/Parser.svelte

@@ -95,7 +95,7 @@
             />
         {/each}
     {/if}
-{:else if type in renderers}
+{:else if type in renderers || type in snippetOverrides}
     {#if type === 'table'}
         {#if renderers.table && renderers.tablerow && renderers.tablecell}
             {@const tableSnippet = snippetOverrides[type]}

package/dist/SvelteMarkdown.svelte

@@ -58,8 +58,9 @@
         type Token,
         type TokensList
     } from './utils/markdown-parser.js'
-    import { parseAndCacheTokens } from './utils/parse-and-cache.js'
+    import { parseAndCacheTokens, parseAndCacheTokensAsync } from './utils/parse-and-cache.js'
     import { rendererKeysInternal } from './utils/rendererKeys.js'
+    import { Marked } from 'marked'
 
     const {
         source = [],
@@ -67,15 +68,32 @@
         options = {},
         isInline = false,
         parsed = () => {},
+        extensions = [],
         ...rest
     }: SvelteMarkdownProps & {
         [key: string]: unknown
     } = $props()
 
-    const combinedOptions = $derived({ ...defaultOptions, ...options })
+    // Extract custom token type names from the extensions array
+    const extensionTokenNames = $derived(
+        extensions.flatMap((ext) => ext.extensions?.map((e) => e.name) ?? [])
+    )
+
+    // Create a scoped Marked instance and extract its resolved defaults
+    const extensionDefaults = $derived(
+        extensions.length > 0 ? new Marked(...extensions).defaults : {}
+    )
+
+    const combinedOptions = $derived({ ...defaultOptions, ...extensionDefaults, ...options })
     const slugger = new Slugger()
 
-    const tokens = $derived.by(() => {
+    // Detect if any extension requires async processing
+    const hasAsyncExtension = $derived(extensions.some((ext) => ext.async === true))
+
+    // Synchronous token derivation (default fast path)
+    const syncTokens = $derived.by(() => {
+        if (hasAsyncExtension) return undefined
+
         // Pre-parsed tokens - skip caching and parsing
         if (Array.isArray(source)) {
             return source as Token[]
@@ -90,6 +108,47 @@
         return parseAndCacheTokens(source as string, combinedOptions, isInline)
     }) satisfies Token[] | TokensList | undefined
 
+    // Async token state (used only when extensions require async walkTokens)
+    let asyncTokens = $state<Token[] | TokensList | undefined>(undefined)
+    let asyncRequestId = 0
+
+    $effect(() => {
+        if (!hasAsyncExtension) return
+
+        // Pre-parsed tokens - skip caching and parsing
+        if (Array.isArray(source)) {
+            asyncTokens = source as Token[]
+            return
+        }
+
+        // Empty string - return empty array
+        if (source === '') {
+            asyncTokens = []
+            return
+        }
+
+        // Async parse with caching
+        const currentSource = source as string
+        const currentOptions = combinedOptions
+        const currentInline = isInline
+        const requestId = ++asyncRequestId
+        parseAndCacheTokensAsync(currentSource, currentOptions, currentInline)
+            .then((result) => {
+                if (requestId === asyncRequestId) {
+                    asyncTokens = result
+                }
+            })
+            .catch((error) => {
+                if (requestId === asyncRequestId) {
+                    console.error('[svelte-markdown] async walkTokens failed:', error)
+                    asyncTokens = []
+                }
+            })
+    })
+
+    // Unified tokens: prefer sync path, fall back to async
+    const tokens = $derived(hasAsyncExtension ? asyncTokens : syncTokens)
+
     $effect(() => {
         if (!tokens) return
         parsed(tokens)
@@ -106,10 +165,13 @@
             : defaultRenderers.html
     })
 
-    // Collect markdown snippet overrides (keys matching renderer names)
+    // All renderer keys: built-in + extension token names
+    const allRendererKeys = $derived([...rendererKeysInternal, ...extensionTokenNames])
+
+    // Collect markdown snippet overrides (keys matching renderer names or extension token names)
     const snippetOverrides = $derived(
         Object.fromEntries(
-            rendererKeysInternal
+            allRendererKeys
                 .filter((key) => key in rest && rest[key] != null)
                 .map((key) => [key, rest[key]])
         )
@@ -126,10 +188,7 @@
 
     // Passthrough: everything that isn't a known snippet override
     const snippetKeySet = $derived(
-        new Set([
-            ...rendererKeysInternal,
-            ...Object.keys(rest).filter((k) => k.startsWith('html_'))
-        ])
+        new Set([...allRendererKeys, ...Object.keys(rest).filter((k) => k.startsWith('html_'))])
     )
     const passThroughProps = $derived(
         Object.fromEntries(Object.entries(rest).filter(([key]) => !snippetKeySet.has(key)))

package/dist/extensions/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Extension helpers for `@humanspeak/svelte-markdown`.
+ *
+ * Import from `@humanspeak/svelte-markdown/extensions`:
+ *
+ * ```ts
+ * import { markedMermaid, MermaidRenderer } from '@humanspeak/svelte-markdown/extensions'
+ * ```
+ *
+ * @module @humanspeak/svelte-markdown/extensions
+ */
+export { MermaidRenderer, markedMermaid } from './mermaid/index.js';

package/dist/extensions/index.js

@@ -0,0 +1,12 @@
+/**
+ * Extension helpers for `@humanspeak/svelte-markdown`.
+ *
+ * Import from `@humanspeak/svelte-markdown/extensions`:
+ *
+ * ```ts
+ * import { markedMermaid, MermaidRenderer } from '@humanspeak/svelte-markdown/extensions'
+ * ```
+ *
+ * @module @humanspeak/svelte-markdown/extensions
+ */
+export { MermaidRenderer, markedMermaid } from './mermaid/index.js';

package/dist/extensions/mermaid/MermaidRenderer.svelte

@@ -0,0 +1,79 @@
+<script lang="ts">
+    import { onMount } from 'svelte'
+
+    interface Props {
+        text: string
+        lightTheme?: string
+        darkTheme?: string
+    }
+
+    const { text, lightTheme = 'default', darkTheme = 'dark' }: Props = $props()
+
+    let svg = $state('')
+    let error = $state('')
+    let loading = $state(true)
+    let mermaidModule: typeof import('mermaid').default | null = $state(null)
+    let renderCounter = 0
+
+    async function renderDiagram(diagramText: string) {
+        if (!mermaidModule) return
+        const current = ++renderCounter
+        try {
+            error = ''
+            const isDark = document.documentElement.classList.contains('dark')
+            const theme = isDark ? darkTheme : lightTheme
+            const themed = `%%{init: {'theme': '${theme}'}}%%\n${diagramText}`
+            const id = `mermaid-${crypto.randomUUID()}`
+            const result = await mermaidModule.render(id, themed)
+            if (current !== renderCounter) return
+            svg = result.svg
+        } catch (e) {
+            if (current !== renderCounter) return
+            error = e instanceof Error ? e.message : String(e)
+        }
+    }
+
+    $effect(() => {
+        if (mermaidModule) {
+            renderDiagram(text)
+        }
+    })
+
+    onMount(() => {
+        let observer: MutationObserver
+        ;(async () => {
+            try {
+                const mod = (await import('mermaid')).default
+                mod.initialize({ startOnLoad: false, securityLevel: 'strict' })
+                mermaidModule = mod
+            } catch (e) {
+                error = e instanceof Error ? e.message : String(e)
+            } finally {
+                loading = false
+            }
+        })()
+
+        observer = new MutationObserver((mutations) => {
+            for (const mutation of mutations) {
+                if (mutation.attributeName === 'class') {
+                    renderDiagram(text)
+                    return
+                }
+            }
+        })
+        observer.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] })
+
+        return () => observer.disconnect()
+    })
+</script>
+
+{#if loading}
+    <div class="mermaid-loading" data-testid="mermaid-loading">Loading diagram...</div>
+{:else if error}
+    <div class="mermaid-error" data-testid="mermaid-error">Diagram error: {error}</div>
+{:else}
+    <div class="mermaid-diagram" data-testid="mermaid-diagram">
+        <!-- trunk-ignore(eslint/svelte/no-at-html-tags) -->
+        {@html svg}
+    </div>
+{/if}

package/dist/extensions/mermaid/MermaidRenderer.svelte.d.ts

@@ -0,0 +1,8 @@
+interface Props {
+    text: string;
+    lightTheme?: string;
+    darkTheme?: string;
+}
+declare const MermaidRenderer: import("svelte").Component<Props, {}, "">;
+type MermaidRenderer = ReturnType<typeof MermaidRenderer>;
+export default MermaidRenderer;

package/dist/extensions/mermaid/index.d.ts

@@ -0,0 +1,2 @@
+export { markedMermaid } from './markedMermaid.js';
+export { default as MermaidRenderer } from './MermaidRenderer.svelte';

package/dist/extensions/mermaid/index.js

@@ -0,0 +1,2 @@
+export { markedMermaid } from './markedMermaid.js';
+export { default as MermaidRenderer } from './MermaidRenderer.svelte';

package/dist/extensions/mermaid/markedMermaid.d.ts

@@ -0,0 +1,28 @@
+import type { MarkedExtension } from 'marked';
+/**
+ * Creates a marked extension that tokenizes fenced ` ```mermaid ` code blocks
+ * into custom `mermaid` tokens.
+ *
+ * The extension produces block-level tokens with `{ type: 'mermaid', raw, text }`
+ * where `text` is the trimmed diagram source. It has zero runtime dependencies —
+ * pair it with `MermaidRenderer` (or your own component) to render the diagrams.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import SvelteMarkdown from '@humanspeak/svelte-markdown'
+ *   import { markedMermaid, MermaidRenderer } from '@humanspeak/svelte-markdown'
+ *
+ *   const renderers = { mermaid: MermaidRenderer }
+ * </script>
+ *
+ * <SvelteMarkdown
+ *   source={markdown}
+ *   extensions={[markedMermaid()]}
+ *   {renderers}
+ * />
+ * ```
+ *
+ * @returns A `MarkedExtension` with a single block-level `mermaid` tokenizer
+ */
+export declare function markedMermaid(): MarkedExtension;

package/dist/extensions/mermaid/markedMermaid.js

@@ -0,0 +1,49 @@
+/**
+ * Creates a marked extension that tokenizes fenced ` ```mermaid ` code blocks
+ * into custom `mermaid` tokens.
+ *
+ * The extension produces block-level tokens with `{ type: 'mermaid', raw, text }`
+ * where `text` is the trimmed diagram source. It has zero runtime dependencies —
+ * pair it with `MermaidRenderer` (or your own component) to render the diagrams.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import SvelteMarkdown from '@humanspeak/svelte-markdown'
+ *   import { markedMermaid, MermaidRenderer } from '@humanspeak/svelte-markdown'
+ *
+ *   const renderers = { mermaid: MermaidRenderer }
+ * </script>
+ *
+ * <SvelteMarkdown
+ *   source={markdown}
+ *   extensions={[markedMermaid()]}
+ *   {renderers}
+ * />
+ * ```
+ *
+ * @returns A `MarkedExtension` with a single block-level `mermaid` tokenizer
+ */
+export function markedMermaid() {
+    return {
+        extensions: [
+            {
+                name: 'mermaid',
+                level: 'block',
+                start(src) {
+                    return src.match(/```mermaid/)?.index;
+                },
+                tokenizer(src) {
+                    const match = src.match(/^```mermaid\n([\s\S]*?)```/);
+                    if (match) {
+                        return {
+                            type: 'mermaid',
+                            raw: match[0],
+                            text: match[1].trim()
+                        };
+                    }
+                }
+            }
+        ]
+    };
+}

package/dist/index.d.ts

@@ -59,5 +59,7 @@ export { htmlRendererKeysInternal as htmlRendererKeys, rendererKeysInternal as r
  */
 export { MemoryCache } from './utils/cache.js';
 export { TokenCache, tokenCache } from './utils/token-cache.js';
+/** Re-exported `MarkedExtension` type for the `extensions` prop. */
+export type { MarkedExtension } from 'marked';
 /** Re-exported types for consumer convenience. */
 export type { BlockquoteSnippetProps, BrSnippetProps, CodeSnippetProps, CodespanSnippetProps, DelSnippetProps, EmSnippetProps, EscapeSnippetProps, HeadingSnippetProps, HrSnippetProps, HtmlRenderers, HtmlSnippetOverrides, HtmlSnippetProps, ImageSnippetProps, LinkSnippetProps, ListItemSnippetProps, ListSnippetProps, ParagraphSnippetProps, RawTextSnippetProps, RendererComponent, Renderers, SnippetOverrides, StrongSnippetProps, SvelteMarkdownOptions, SvelteMarkdownProps, TableBodySnippetProps, TableCellSnippetProps, TableHeadSnippetProps, TableRowSnippetProps, TableSnippetProps, TextSnippetProps, Token, TokensList };

package/dist/types.d.ts

@@ -17,7 +17,7 @@
  *
  * @packageDocumentation
  */
-import type { Token, TokensList } from 'marked';
+import type { MarkedExtension, Token, TokensList } from 'marked';
 import type { Snippet } from 'svelte';
 import type { MarkedOptions, Renderers } from './utils/markdown-parser.js';
 import type { HtmlKey } from './utils/rendererKeys.js';
@@ -152,6 +152,29 @@ export type SvelteMarkdownProps<T extends Renderers = Renderers> = {
      * generation settings.  Merged with {@link defaultOptions}.
      */
     options?: Partial<SvelteMarkdownOptions>;
+    /**
+     * Array of marked extensions to apply when parsing.
+     *
+     * Internally creates a scoped `Marked` instance, extracts its resolved
+     * defaults, and merges them into the parser options so the lexer
+     * recognises any custom token types the extensions define.
+     *
+     * Extension token names are also used to collect snippet overrides,
+     * enabling both component-renderer and snippet-based rendering of
+     * custom tokens.
+     *
+     * @defaultValue `[]`
+     *
+     * @example
+     * ```svelte
+     * <SvelteMarkdown
+     *   source={markdown}
+     *   extensions={[markedKatex({ throwOnError: false })]}
+     *   renderers={{ inlineKatex: KatexRenderer, blockKatex: KatexRenderer }}
+     * />
+     * ```
+     */
+    extensions?: MarkedExtension[];
     /**
      * When `true`, the source is parsed with `Lexer.lexInline()` instead of
      * `Lexer.lex()`, producing only inline tokens (no block elements).

package/dist/utils/createFilterUtilities.js

@@ -45,13 +45,15 @@ export const createFilterUtilities = (keys, unsupportedComponent, defaultsMap) =
     const hasKey = (key) => keys.includes(key);
     /**
      * Builds a map where every key is set to the unsupported component.
-     * Useful for starting with a "deny all" approach.
+     * Keys whose default value is null are preserved as null so that
+     * fallback chains (e.g. orderedlistitem || listitem) still work.
      */
     const buildUnsupported = () => {
         const result = {};
         for (const key of keys) {
             ;
-            result[key] = unsupportedComponent;
+            result[key] =
+                defaultsMap[key] === null ? null : unsupportedComponent;
         }
         return result;
     };

package/dist/utils/parse-and-cache.d.ts

@@ -9,7 +9,7 @@
 import type { SvelteMarkdownOptions } from '../types.js';
 import type { Token, TokensList } from './markdown-parser.js';
 /**
- * Parses markdown source with caching.
+ * Parses markdown source with caching (synchronous path).
  * Checks cache first, parses on miss, stores result, and returns tokens.
  *
  * @param source - Raw markdown string to parse
@@ -29,3 +29,21 @@ import type { Token, TokensList } from './markdown-parser.js';
  * ```
  */
 export declare function parseAndCacheTokens(source: string, options: SvelteMarkdownOptions, isInline: boolean): Token[] | TokensList;
+/**
+ * Parses markdown source with caching (async path).
+ * Uses Marked's recursive walkTokens with Promise.all to properly
+ * handle async walkTokens callbacks (e.g. marked-code-format).
+ *
+ * @param source - Raw markdown string to parse
+ * @param options - Svelte markdown parser options
+ * @param isInline - Whether to parse as inline markdown (no block elements)
+ * @returns Promise resolving to cleaned and cached token array
+ *
+ * @example
+ * ```typescript
+ * import { parseAndCacheTokensAsync } from './parse-and-cache.js'
+ *
+ * const tokens = await parseAndCacheTokensAsync('# Hello', opts, false)
+ * ```
+ */
+export declare function parseAndCacheTokensAsync(source: string, options: SvelteMarkdownOptions, isInline: boolean): Promise<Token[] | TokensList>;

package/dist/utils/parse-and-cache.js

@@ -8,9 +8,17 @@
  */
 import { tokenCache } from './token-cache.js';
 import { shrinkHtmlTokens } from './token-cleanup.js';
-import { Lexer } from 'marked';
+import { Lexer, Marked } from 'marked';
 /**
- * Parses markdown source with caching.
+ * Lex and clean tokens from markdown source. Shared by sync and async paths.
+ */
+function lexAndClean(source, options, isInline) {
+    const lexer = new Lexer(options);
+    const parsedTokens = isInline ? lexer.inlineTokens(source) : lexer.lex(source);
+    return shrinkHtmlTokens(parsedTokens);
+}
+/**
+ * Parses markdown source with caching (synchronous path).
  * Checks cache first, parses on miss, stores result, and returns tokens.
  *
  * @param source - Raw markdown string to parse
@@ -36,9 +44,7 @@ export function parseAndCacheTokens(source, options, isInline) {
         return cached;
     }
     // Cache miss - parse and store
-    const lexer = new Lexer(options);
-    const parsedTokens = isInline ? lexer.inlineTokens(source) : lexer.lex(source);
-    const cleanedTokens = shrinkHtmlTokens(parsedTokens);
+    const cleanedTokens = lexAndClean(source, options, isInline);
     if (typeof options.walkTokens === 'function') {
         cleanedTokens.forEach(options.walkTokens);
     }
@@ -46,3 +52,41 @@ export function parseAndCacheTokens(source, options, isInline) {
     tokenCache.setTokens(source, options, cleanedTokens);
     return cleanedTokens;
 }
+/**
+ * Parses markdown source with caching (async path).
+ * Uses Marked's recursive walkTokens with Promise.all to properly
+ * handle async walkTokens callbacks (e.g. marked-code-format).
+ *
+ * @param source - Raw markdown string to parse
+ * @param options - Svelte markdown parser options
+ * @param isInline - Whether to parse as inline markdown (no block elements)
+ * @returns Promise resolving to cleaned and cached token array
+ *
+ * @example
+ * ```typescript
+ * import { parseAndCacheTokensAsync } from './parse-and-cache.js'
+ *
+ * const tokens = await parseAndCacheTokensAsync('# Hello', opts, false)
+ * ```
+ */
+export async function parseAndCacheTokensAsync(source, options, isInline) {
+    // Check cache first - avoids expensive parsing
+    const cached = tokenCache.getTokens(source, options);
+    if (cached) {
+        return cached;
+    }
+    // Cache miss - parse and store
+    const cleanedTokens = lexAndClean(source, options, isInline);
+    if (typeof options.walkTokens === 'function') {
+        // Use Marked's recursive walkTokens which handles tables, lists,
+        // nested tokens, and extension childTokens. Await all returned
+        // promises so async walkTokens callbacks complete before caching.
+        const marked = new Marked();
+        marked.defaults = { ...marked.defaults, ...options };
+        const results = marked.walkTokens(cleanedTokens, options.walkTokens);
+        await Promise.all(results);
+    }
+    // Cache the cleaned tokens for next time
+    tokenCache.setTokens(source, options, cleanedTokens);
+    return cleanedTokens;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-markdown",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Fast, customizable markdown renderer for Svelte with built-in caching, TypeScript support, and Svelte 5 runes",
   "keywords": [
     "svelte",
@@ -47,6 +47,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "svelte": "./dist/index.js"
+    },
+    "./extensions": {
+      "types": "./dist/extensions/index.d.ts",
+      "svelte": "./dist/extensions/index.js"
     }
   },
   "svelte": "./dist/index.js",
@@ -74,18 +78,18 @@
     "@playwright/cli": "^0.1.1",
     "@playwright/test": "^1.58.2",
     "@sveltejs/adapter-auto": "^7.0.1",
-    "@sveltejs/kit": "^2.52.2",
+    "@sveltejs/kit": "^2.53.3",
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/svelte": "^5.3.1",
     "@testing-library/user-event": "^14.6.1",
-    "@types/node": "^25.2.3",
-    "@typescript-eslint/eslint-plugin": "^8.56.0",
-    "@typescript-eslint/parser": "^8.56.0",
+    "@types/katex": "^0.16.8",
+    "@types/node": "^25.3.2",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
     "@vitest/coverage-v8": "^4.0.18",
-    "concurrently": "^9.2.1",
-    "eslint": "^10.0.0",
+    "eslint": "^10.0.2",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-svelte": "^3.15.0",
@@ -93,23 +97,33 @@
     "globals": "^17.3.0",
     "husky": "^9.1.7",
     "jsdom": "^28.1.0",
+    "katex": "^0.16.33",
+    "marked-katex-extension": "^5.1.7",
+    "mermaid": "^11.12.3",
+    "mprocs": "^0.8.3",
     "prettier": "^3.8.1",
     "prettier-plugin-organize-imports": "^4.3.0",
     "prettier-plugin-svelte": "^3.5.0",
     "prettier-plugin-tailwindcss": "^0.7.2",
     "publint": "^0.3.17",
-    "svelte": "^5.53.0",
-    "svelte-check": "^4.4.1",
+    "svelte": "^5.53.5",
+    "svelte-check": "^4.4.4",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.56.0",
+    "typescript-eslint": "^8.56.1",
     "vite": "^7.3.1",
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
+    "mermaid": ">=10.0.0",
     "svelte": "^5.0.0"
   },
+  "peerDependenciesMeta": {
+    "mermaid": {
+      "optional": true
+    }
+  },
   "volta": {
-    "node": "24.12.0"
+    "node": "22.16.0"
   },
   "publishConfig": {
     "access": "public"
@@ -123,7 +137,7 @@
     "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
     "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
     "dev": "vite dev",
-    "dev:all": "concurrently -k -n pkg,docs -c green,cyan \"pnpm -w -r --filter @humanspeak/svelte-motion run dev:pkg\" \"pnpm --filter docs run dev\"",
+    "dev:all": "mprocs",
     "dev:pkg": "svelte-kit sync && svelte-package --watch",
     "format": "prettier --write .",
     "lint": "prettier --check . && eslint .",