api #

Context for providing a base path getter for resolving relative links in mdz content. Set to a getter (e.g., () => base) so changes to the base prop are reflected without needing an effect. When the getter returns a path like '/docs/usage/', relative paths like ./grammar resolve to /docs/usage/grammar before rendering. When not set, relative paths use raw hrefs (browser resolves them).

Context for overriding how inline `` code `` spans render, via a getter function. When not set, inline code renders as a plain <code> element.

Context for overriding how fenced code blocks render, via a getter function. When not set, code blocks render as a plain <pre><code> element.

Context for providing custom mdz components via a getter function. Set to a getter (e.g., () => components) so changes are reflected reactively.

Context for providing allowed HTML elements via a getter function. Set to a getter (e.g., () => elements) so changes are reflected reactively. By default, no HTML elements are allowed.

Extracts a single tag (component or element) if it's the only non-whitespace content.

Convert raw TSDoc @see content to mdz format for rendering.

Handles TSDoc link syntax:

• |text → [text](url) (markdown link, TSDoc canonical form)
• text → [text](url) (TS-lenient space-separated form)
• ://... → https://... (bare URL, auto-linked by mdz)
• `` → `` identifier `` (code formatting)
• Bare URLs → returned as-is
• Bare markdown links ([text](url) ...) → returned as-is
• Bare identifiers → wrapped in backticks
• identifier description text → `` identifier description text `` (first token is the reference)

Generates a lowercase slug id for a heading from its child nodes. Follows standard markdown conventions (GitHub, etc.) where heading IDs are lowercased.

Generates a lowercase slug id for a heading from plain text content. Used by the streaming parser which tracks text content directly rather than building MdzNode[] trees.

Check if an element name is an HTML void element (br, img, hr, ...). Void elements render self-closing; any parsed children are dropped.

Return a new array with adjacent Text nodes merged into single nodes. Fast path: returns the original array when no merging is needed.

Convert an array of mdz opcodes to the MdzNode[] tree. Produces output identical to mdz_parse().

Parses text to an array of MdzNode.

Two phases: MdzLexer tokenizes the input into a flat MdzToken[] stream, then MdzTokenParser builds the MdzNode[] tree from the tokens.

Push a node into a children array, coalescing with the previous Text node. Mutates prev.content and prev.end when both are Text, avoiding array growth and an extra allocation. Callers must own dest and not retain references to the prior last element across the call.

Resolves a relative path (./ or ../) against a base path. The base is treated as a directory regardless of trailing slash ('/docs/usage' and '/docs/usage/' behave identically). Handles embedded . and .. segments within the reference (e.g., './a/../b' → navigates up then down). Clamps at root — excess .. segments stop at / rather than escaping.

Set an mdz context to a getter that prefers the local value_fn and falls back to the ancestor's value when value_fn() returns undefined.

Pass value_fn as a getter (not a snapshot) so prop changes remain reactive. The ancestor lookup happens once at component init — that's intentional, it captures the surrounding scope's context at mount time.

Extracts plain text content from an array of mdz nodes, recursing into children.

Converts an array of MdzNode to a Svelte markup string.

Each node type produces output matching what MdzNodeView.svelte renders at runtime. Collects required imports and flags unconfigured component/element references.

Trim trailing punctuation from URL/path per RFC 3986 and GFM rules.

• Trims simple trailing: .,;:!?]
• Balanced logic for () only (valid in path components)

Note on ]: the mdz parsers (mdz.ts, mdz_stream_parser_url.ts, mdz_lexer.ts) scan URL/path chars through is_valid_path_char, which already rejects ] — so it can never reach this function via parser flow. The ] branch here is for external callers using this helper directly on arbitrary URL-ish input as part of the published @fuzdev/mdz surface.

Optimized to avoid O(n²) string slicing - tracks end index and slices once at the end.

Component that renders a fenced code block. Receives lang and content, matching @fuzdev/fuz_code's Code, so it can be injected directly for syntax highlighting.

Component that renders an inline `` code `` span. Receives the raw span content as reference — the prop name matches fuz_ui's DocsLink, so it can be injected directly to auto-link backticked API identifiers.

Component registry for custom Svelte components that can be used in mdz content.

For example, registering 'Alert' allows using <Alert>...</Alert> in mdz content.

The Map values are Svelte components.

Element registry for HTML elements that can be used in mdz content.

For example, registering 'div' allows using <div>...</div> in mdz content.

The Map values are boolean placeholders for future configuration options.

Tokenizes mdz input into a flat MdzToken stream for MdzTokenParser.

The lexer owns all structural decisions — block boundaries, list level stacks, blockquote prefix stripping (sub-lexing quote content as a mini-document with positions remapped to source offsets), and inline delimiter pairing bounded by #max_search_index — so the token parser only assembles the tree.

Unique monotonic identifier for each node created by the parser. IDs are never reused within a parser instance.

All node types that can appear in the mdz tree.

Node types that can be opened as containers.

Code appears here *and* in MdzNodeTypeText: inline code resolved within one chunk emits as a single text opcode, while a backtick with no closer visible yet opens an optimistic Code container whose content streams as text children (collapsed back to content by consumers at close).

Discriminant for leaf text nodes (see MdzNodeTypeContainer for Code's dual form).

Node types for self-contained leaf elements.

Discriminated union of all mdz opcodes.

Append content to an existing text node. Streaming optimization — avoids creating a new node per chunk during plain text runs.

Close a previously opened container node. Carries deferred metadata that wasn't known at open time.

Open a container node. The renderer starts a new element/wrapper. Children are subsequent opcodes until the matching close.

Undo an optimistic open. Removes the container wrapper, inserts replacement_text as literal text at the container's position, and re-parents the container's children to the grandparent.

Only inline containers revert — block structure (paragraphs, headings, codeblocks, lists, blockquotes) is decided from bounded input before opening, so block opens are never speculative.

Create a leaf text or code node. The parent is implicit — the innermost open container on the renderer's stack.

Trim count characters from the end of an existing text node. If trimming empties the node, the consumer removes it from its parent.

Used by paragraph/codeblock close to drop the trailing newline that separates inline content from the block boundary. Emitted instead of retroactively mutating the prior text/append_text opcode, so the opcode stream is append-only.

Create a self-contained leaf node (e.g., horizontal rule). Inserted as a child of the innermost open container, or at root level.

Retroactively wrap an existing text node in a container. Used for text-first auto-links: URL/path text streams as plain text, then gets wrapped in a Link when the URL boundary is found.

Specific to text-first auto-detected content — not a general retroactive-container mechanism. Delimiter-paired inlines (bold, italic, strikethrough) use optimistic open + revert instead: their opening delimiter is an explicit open event, and the delimiters are discarded rather than retained as content.

When trim_end is set, trailing characters (punctuation) are trimmed from the target text node and placed in a new sibling Text node after the Link wrapper, identified by trim_id.

A reactive node in the stream renderer tree. Fields are $state so Svelte re-renders only what changes.

Streaming opcode parser for mdz content. Feed chunks via feed(), retrieve opcodes via take_opcodes(), call finish() at end.

The opcode sequence is not deterministic across chunk boundaries — the same input fed in different chunk sizes may produce different text/append_text splits and different optimistic/revert sequences. The final tree (via mdz_opcodes_to_nodes) matches the one-shot result: optimistic opens are corrected by revert opcodes at the first failed closer, at run close (paragraph, heading, or list-item run), or at EOF, and at EOF the delimiter-paired opens (bold/italic/strikethrough) and inline-code candidates are gated on a closer scan of the complete final buffer, so held tails parse like the one-shot parse. The residual divergence classes are:

• Backtick-adjacent chunking — an inline-code candidate held across chunks can make its text-vs-code decision bounded by a wrongly-optimistic italic (opened before its failed closer was visible), where the one-shot parse greedy-rejects that italic and scans unbounded — `` ___ `` chunked at the italic stays flat text where one-shot parses the code span. Italic is the only wedge (the only delimiter whose one-shot form rejects on a failed first closer); see try_code's hold and code_search_limit.
• Optimistic inline code unclosed at EOF — a `` ` that opened optimistically consumes its tail as raw code text, so formatting inside it never forms (`` h x **b** z ` stays flat where one-shot parses the bold); the parser never re-parses, so the EOF revert can only flatten it to text.
• Link/tag opens at EOF — finish() doesn't open links or tags, so a held tail containing complete [text](url) / <Tag>…</Tag> syntax parses flat.
• Block elements interrupt optimistic inlines — at column 0 a heading/HR/fence/list/blockquote line interrupts the open paragraph even when an optimistic inline container spans it (**a\n# h\nb** parses the heading here; the one-shot parse, knowing the closer exists, swallows the line as bold text). Inherent: the swallow is only correct when a closer eventually arrives, which streaming can't know — interrupting matches the one-shot parse on the no-closer flip side (**a\n# h) and renders blocks promptly.

Lifecycle: one parser instance per stream — feed() any number of times, finish() exactly once, then a final take_opcodes(). There is no reset(); calling feed() or finish() after finish() is undefined. To restart, construct a new parser (and a new consumer — see MdzStreamState).

Reactive state manager for streaming mdz content. Apply opcodes to incrementally build and update the render tree.

Lifecycle: one state instance per stream, paired with one MdzStreamParser. Opcodes must be applied exactly once, in emission order — take_opcodes() batches can be split or concatenated freely, but never reordered, skipped, or replayed. There is no reset(); to restart a stream, construct a new parser and a new state.

Builds an MdzNode[] tree from a lexed MdzToken[] stream. Used by mdz_parse, which should be preferred for simple usage.

Options for mdz_to_svelte.

Result of converting MdzNode arrays to Svelte markup.

CSS white-space values for the whitespace prop on Mdz, MdzStream, and MdzPrecompiled. By default no style is applied, so whitespace collapses like standard markdown — single newlines are soft breaks. pre-line renders every newline as a line break (chat-style input); pre-wrap additionally preserves spaces and tabs.

Creates a Svelte preprocessor that compiles static Mdz content at build time.

Options for svelte_preprocess_mdz.