@fuzdev/mdz 0.1.0 → 0.3.0

package/README.md

@@ -27,6 +27,10 @@ For more see the [docs](https://mdz.fuz.dev/docs).
 AI disclosure: almost everything here was generated by machine agents except
 for the designs and intros. mdz is the result of 5+ years of prototyping ideas.
 
+> ⚠️ This project is pre-stable: breaking changes are expected and
+> some features (like attributes) are not yet implemented.
+> Feedback is welcome!
+
 ## License
 
 [MIT](LICENSE)

package/dist/Mdz.svelte

@@ -1,7 +1,8 @@
 <script lang="ts">
 	import type {SvelteHTMLElements} from 'svelte/elements';
+	import {DEV} from 'esm-env';
 
-	import {mdz_parse} from './mdz.js';
+	import {mdz_parse, type MdzNode} from './mdz.js';
 	import MdzNodeView from './MdzNodeView.svelte';
 	import {
 		mdz_base_context,
@@ -11,12 +12,12 @@
 
 	const {
 		content,
+		nodes: nodes_prop,
 		inline = false,
 		whitespace,
 		base,
 		...rest
 	}: (SvelteHTMLElements['div'] | SvelteHTMLElements['span']) & {
-		content: string;
 		inline?: boolean;
 		/**
 		 * Sets `white-space` on the wrapper. When omitted, whitespace collapses
@@ -25,15 +26,22 @@
 		 */
 		whitespace?: MdzWhitespace;
 		base?: string;
-	} = $props();
+	} & // pass `content` to parse at render, or `nodes` to render a pre-parsed
+		// tree (e.g. build-time-parsed docs content) and skip `mdz_parse` entirely
+		(| {content: string; nodes?: undefined}
+			| {content?: undefined; nodes: Array<MdzNode>}
+		) = $props();
 
 	mdz_set_context_with_fallback(mdz_base_context, () => base);
 
-	const nodes = $derived(mdz_parse(content));
+	const nodes = $derived.by(() => {
+		if (DEV && (content === undefined) === (nodes_prop === undefined)) {
+			throw new Error('Mdz: pass exactly one of `content` or `nodes`');
+		}
+		return nodes_prop ?? mdz_parse(content ?? '');
+	});
 </script>
 
 <svelte:element this={inline ? 'span' : 'div'} {...rest} style:white-space={whitespace}>
-	{#each nodes as node (node)}
-		<MdzNodeView {node} />
-	{/each}
+	<MdzNodeView {nodes} />
 </svelte:element>

package/dist/Mdz.svelte.d.ts

@@ -1,7 +1,7 @@
 import type { SvelteHTMLElements } from 'svelte/elements';
+import { type MdzNode } from './mdz.js';
 import { type MdzWhitespace } from './mdz_contexts.js';
 type $$ComponentProps = (SvelteHTMLElements['div'] | SvelteHTMLElements['span']) & {
-    content: string;
     inline?: boolean;
     /**
      * Sets `white-space` on the wrapper. When omitted, whitespace collapses
@@ -10,7 +10,14 @@ type $$ComponentProps = (SvelteHTMLElements['div'] | SvelteHTMLElements['span'])
      */
     whitespace?: MdzWhitespace;
     base?: string;
-};
+} & // pass `content` to parse at render, or `nodes` to render a pre-parsed
+({
+    content: string;
+    nodes?: undefined;
+} | {
+    content?: undefined;
+    nodes: Array<MdzNode>;
+});
 declare const Mdz: import("svelte").Component<$$ComponentProps, {}, "">;
 type Mdz = ReturnType<typeof Mdz>;
 export default Mdz;

package/dist/Mdz.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Mdz.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/Mdz.svelte"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,iBAAiB,CAAC;AAIxD,OAAO,EAGL,KAAK,aAAa,EAClB,MAAM,mBAAmB,CAAC;AAE3B,KAAK,gBAAgB,GAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC,GAAG;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AA6BH,QAAA,MAAM,GAAG,sDAAwC,CAAC;AAClD,KAAK,GAAG,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,CAAC;AAClC,eAAe,GAAG,CAAC"}
+{"version":3,"file":"Mdz.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/Mdz.svelte"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,iBAAiB,CAAC;AAGxD,OAAO,EAAY,KAAK,OAAO,EAAC,MAAM,UAAU,CAAC;AAEjD,OAAO,EAGL,KAAK,aAAa,EAClB,MAAM,mBAAmB,CAAC;AAE3B,KAAK,gBAAgB,GAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC,GAAG;IACnF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,uEAAuE;AAE1E,CAAG;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAC,GACpC;IAAC,OAAO,CAAC,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;CAAC,CAC9C,CAAC;AAkCJ,QAAA,MAAM,GAAG,sDAAwC,CAAC;AAClD,KAAK,GAAG,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,CAAC;AAClC,eAAe,GAAG,CAAC"}

package/dist/MdzNodeView.svelte

@@ -1,13 +1,8 @@
 <script lang="ts">
 	import {resolve} from '$app/paths';
 
-	import type {MdzNode} from './mdz.js';
-	import {
-		mdz_resolve_relative_path,
-		mdz_is_safe_reference,
-		mdz_is_void_element,
-	} from './mdz_helpers.js';
-	import MdzNodeView from './MdzNodeView.svelte';
+	import type {MdzNode, MdzNodeTableRow, MdzTableAlign} from './mdz.js';
+	import {mdz_classify_link, mdz_is_void_element} from './mdz_helpers.js';
 	import {
 		mdz_components_context,
 		mdz_elements_context,
@@ -18,9 +13,10 @@
 
 	const {
 		node,
-	}: {
-		node: MdzNode;
-	} = $props();
+		nodes,
+	}: // exactly one of `node`/`nodes` — the array form renders a whole tree
+		// through this single component instance (used by `Mdz`)
+		{node: MdzNode; nodes?: undefined} | {node?: undefined; nodes: Array<MdzNode>} = $props();
 
 	const get_components = mdz_components_context.get_maybe();
 	const get_elements = mdz_elements_context.get_maybe();
@@ -29,103 +25,142 @@
 	const get_codeblock = mdz_codeblock_context.get_maybe();
 </script>
 
-{#if node.type === 'Element'}
-	{@const element_config = get_elements?.()?.get(node.name)}
-	{#if element_config !== undefined}
-		{#if mdz_is_void_element(node.name)}
-			<!-- void elements cannot have content — any parsed children are dropped -->
-			<svelte:element this={node.name} />
+<!-- The tree renders through recursive snippets rather than recursive
+component instances — one component (and one set of context reads) per
+tree instead of per node. -->
+{#if nodes}
+	{@render render_children(nodes)}
+{:else if node}
+	{@render render_node(node)}
+{/if}
+
+{#snippet render_node(node: MdzNode)}
+	{#if node.type === 'Element'}
+		{@const element_config = get_elements?.()?.get(node.name)}
+		{#if element_config !== undefined}
+			{#if mdz_is_void_element(node.name)}
+				<!-- void elements cannot have content — any parsed children are dropped -->
+				<svelte:element this={node.name} />
+			{:else}
+				<svelte:element this={node.name}>
+					{#if node.children.length > 0}
+						{@render render_children(node.children)}
+					{/if}
+				</svelte:element>
+			{/if}
 		{:else}
-			<svelte:element this={node.name}>
+			{@render render_unregistered_tag(node.name, node.children)}
+		{/if}
+	{:else if node.type === 'Component'}
+		{@const Component = get_components?.()?.get(node.name)}
+		{#if Component}
+			<Component>
 				{#if node.children.length > 0}
 					{@render render_children(node.children)}
 				{/if}
-			</svelte:element>
+			</Component>
+		{:else}
+			{@render render_unregistered_tag(node.name, node.children)}
 		{/if}
-	{:else}
-		{@render render_unregistered_tag(node.name, node.children)}
-	{/if}
-{:else if node.type === 'Component'}
-	{@const Component = get_components?.()?.get(node.name)}
-	{#if Component}
-		<Component>
-			{#if node.children.length > 0}
-				{@render render_children(node.children)}
-			{/if}
-		</Component>
-	{:else}
-		{@render render_unregistered_tag(node.name, node.children)}
-	{/if}
-{:else if node.type === 'Text'}
-	{node.content}
-{:else if node.type === 'Code'}
-	{@const Code = get_code?.()}
-	{#if Code}
-		<Code reference={node.content} />
-	{:else}
-		<code>{node.content}</code>
-	{/if}
-{:else if node.type === 'Bold'}
-	<strong>{@render render_children(node.children)}</strong>
-{:else if node.type === 'Italic'}
-	<em>{@render render_children(node.children)}</em>
-{:else if node.type === 'Strikethrough'}
-	<s>{@render render_children(node.children)}</s>
-{:else if node.type === 'Link'}
-	{@const {reference} = node}
-	{#if !mdz_is_safe_reference(reference)}
-		{@render render_children(node.children)}
-	{:else if node.link_type === 'internal'}
-		{@const skip_resolve = reference.startsWith('#') || reference.startsWith('?')}
-		{@const mdz_base = get_mdz_base?.()}
-		{#if reference.startsWith('.') && mdz_base}
-			{@const resolved = mdz_resolve_relative_path(reference, mdz_base)}
-			<a href={resolve(resolved as any)}>{@render render_children(node.children)}</a>
-		{:else if skip_resolve || reference.startsWith('.') || !reference.startsWith('/')}
-			<!-- Fragment, query, and relative links (including bare references like `foo`) skip resolve() -->
-			<!-- resolve() only accepts absolute pathnames or route IDs and throws on anything else -->
+	{:else if node.type === 'Text'}
+		{node.content}
+	{:else if node.type === 'Code'}
+		{@const Code = get_code?.()}
+		{#if Code}
+			<Code reference={node.content} />
+		{:else}
+			<code>{node.content}</code>
+		{/if}
+	{:else if node.type === 'Bold'}
+		<strong>{@render render_children(node.children)}</strong>
+	{:else if node.type === 'Italic'}
+		<em>{@render render_children(node.children)}</em>
+	{:else if node.type === 'Strikethrough'}
+		<s>{@render render_children(node.children)}</s>
+	{:else if node.type === 'Link'}
+		{@const link = mdz_classify_link(node.reference, node.link_type, get_mdz_base?.())}
+		{#if link.kind === 'unsafe'}
+			{@render render_children(node.children)}
+		{:else if link.kind === 'resolve'}
+			<a href={resolve(link.href as any)}>{@render render_children(node.children)}</a>
+		{:else if link.kind === 'external'}
 			<!-- eslint-disable-next-line svelte/no-navigation-without-resolve -->
-			<a href={reference}>{@render render_children(node.children)}</a>
+			<a href={link.href} target="_blank" rel="noopener">{@render render_children(node.children)}</a
+			>
 		{:else}
-			<a href={resolve(reference as any)}>{@render render_children(node.children)}</a>
+			<!-- fragment/query/relative/bare references skip resolve() (it accepts only absolute paths) -->
+			<!-- eslint-disable-next-line svelte/no-navigation-without-resolve -->
+			<a href={link.href}>{@render render_children(node.children)}</a>
 		{/if}
-	{:else}
-		<!-- external link -->
-		<!-- eslint-disable-next-line svelte/no-navigation-without-resolve -->
-		<a href={reference} target="_blank" rel="noopener">{@render render_children(node.children)}</a>
-	{/if}
-{:else if node.type === 'Paragraph'}
-	<p>{@render render_children(node.children)}</p>
-{:else if node.type === 'List'}
-	{#if node.ordered}
-		<ol start={node.start_number === 1 ? undefined : node.start_number}>
+	{:else if node.type === 'Paragraph'}
+		<p>{@render render_children(node.children)}</p>
+	{:else if node.type === 'List'}
+		{#if node.ordered}
+			<ol start={node.start_number === 1 ? undefined : node.start_number}>
+				{@render render_children(node.children)}
+			</ol>
+		{:else}
+			<ul>{@render render_children(node.children)}</ul>
+		{/if}
+	{:else if node.type === 'ListItem'}
+		<li>{@render render_children(node.children)}</li>
+	{:else if node.type === 'Blockquote'}
+		<blockquote>{@render render_children(node.children)}</blockquote>
+	{:else if node.type === 'Table'}
+		<!-- by grammar the header row is always first (and the only one) — read
+		it by index and skip it per-row in the body, rather than filtering
+		twice (matches the streaming view, where a filter would go O(n²)
+		across a streamed table) -->
+		{@const header_row = node.children[0]?.header ? node.children[0] : undefined}
+		<table>
+			{#if header_row}
+				<thead>
+					<tr>{@render render_cells(header_row, 'th', node.align)}</tr>
+				</thead>
+			{/if}
+			{#if node.children.length > (header_row ? 1 : 0)}
+				<tbody>
+					{#each node.children as row, i (i)}
+						{#if !row.header}
+							<tr>{@render render_cells(row, 'td', node.align)}</tr>
+						{/if}
+					{/each}
+				</tbody>
+			{/if}
+		</table>
+	{:else if node.type === 'Hr'}
+		<hr />
+	{:else if node.type === 'Heading'}
+		<svelte:element this={`h${node.level}`} id={node.id || undefined}>
 			{@render render_children(node.children)}
-		</ol>
-	{:else}
-		<ul>{@render render_children(node.children)}</ul>
-	{/if}
-{:else if node.type === 'ListItem'}
-	<li>{@render render_children(node.children)}</li>
-{:else if node.type === 'Blockquote'}
-	<blockquote>{@render render_children(node.children)}</blockquote>
-{:else if node.type === 'Hr'}
-	<hr />
-{:else if node.type === 'Heading'}
-	<svelte:element this={`h${node.level}`} id={node.id || undefined}>
-		{@render render_children(node.children)}
-	</svelte:element>
-{:else if node.type === 'Codeblock'}
-	{@const Codeblock = get_codeblock?.()}
-	{#if Codeblock}
-		<Codeblock lang={node.lang} content={node.content} />
-	{:else}
-		<pre><code>{node.content}</code></pre>
+		</svelte:element>
+	{:else if node.type === 'Codeblock'}
+		{@const Codeblock = get_codeblock?.()}
+		{#if Codeblock}
+			<Codeblock lang={node.lang} content={node.content} />
+		{:else}
+			<pre><code>{node.content}</code></pre>
+		{/if}
 	{/if}
-{/if}
+{/snippet}
 
 {#snippet render_children(nodes: Array<MdzNode>)}
-	{#each nodes as node (node)}
-		<MdzNodeView {node} />
+	<!-- index keys, not object identity: `mdz_parse` yields a fresh node graph
+	on every `content` change, so identity keys never match and Svelte rebuilds
+	the whole subtree; positional keys let it patch in place. (Sync nodes have
+	no stable id; the stream view keys by `node.id`.) -->
+	{#each nodes as node, i (i)}
+		{@render render_node(node)}
+	{/each}
+{/snippet}
+
+{#snippet render_cells(row: MdzNodeTableRow, tag: 'th' | 'td', align: Array<MdzTableAlign>)}
+	<!-- normalize to the column count: pad short rows, ignore extra cells -->
+	{#each align as a, i (i)}
+		{@const cell = row.children[i]}
+		<svelte:element this={tag} style={a ? `text-align:${a}` : undefined}>
+			{#if cell}{@render render_children(cell.children)}{/if}
+		</svelte:element>
 	{/each}
 {/snippet}
 

package/dist/MdzNodeView.svelte.d.ts

@@ -1,7 +1,11 @@
 import type { MdzNode } from './mdz.js';
-import MdzNodeView from './MdzNodeView.svelte';
-type $$ComponentProps = {
+type $$ComponentProps = // exactly one of `node`/`nodes` — the array form renders a whole tree
+{
     node: MdzNode;
+    nodes?: undefined;
+} | {
+    node?: undefined;
+    nodes: Array<MdzNode>;
 };
 declare const MdzNodeView: import("svelte").Component<$$ComponentProps, {}, "">;
 type MdzNodeView = ReturnType<typeof MdzNodeView>;

package/dist/MdzNodeView.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MdzNodeView.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/MdzNodeView.svelte"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,UAAU,CAAC;AAMtC,OAAO,WAAW,MAAM,sBAAsB,CAAC;AAS9C,KAAK,gBAAgB,GAAI;IACxB,IAAI,EAAE,OAAO,CAAC;CACd,CAAC;AAkIH,QAAA,MAAM,WAAW,sDAAwC,CAAC;AAC1D,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAClD,eAAe,WAAW,CAAC"}
+{"version":3,"file":"MdzNodeView.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/MdzNodeView.svelte"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAC,OAAO,EAAiC,MAAM,UAAU,CAAC;AAUrE,KAAK,gBAAgB,GAEpB,AAFwB,sEAAsE;AAE9F;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAC,GAAG;IAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;CAAC,CAAC;AAgKjF,QAAA,MAAM,WAAW,sDAAwC,CAAC;AAC1D,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAClD,eAAe,WAAW,CAAC"}

package/dist/MdzStream.svelte

@@ -31,7 +31,7 @@
 </script>
 
 <svelte:element this={inline ? 'span' : 'div'} {...rest} style:white-space={whitespace}>
-	{#each stream.root as node (node.id)}
-		<MdzStreamNodeView {node} />
-	{/each}
+	<!-- the array form renders the whole stream through one MdzStreamNodeView
+	instance (one set of context reads) instead of one per top-level block -->
+	<MdzStreamNodeView nodes={stream.root} />
 </svelte:element>

package/dist/MdzStream.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MdzStream.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/MdzStream.svelte"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,iBAAiB,CAAC;AAGxD,OAAO,EAGL,KAAK,aAAa,EAClB,MAAM,mBAAmB,CAAC;AAC5B,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,8BAA8B,CAAC;AAEhE,KAAK,gBAAgB,GAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC,GAAG;IACnF,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AA2BH,QAAA,MAAM,SAAS,sDAAwC,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}
+{"version":3,"file":"MdzStream.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/MdzStream.svelte"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,iBAAiB,CAAC;AAGxD,OAAO,EAGL,KAAK,aAAa,EAClB,MAAM,mBAAmB,CAAC;AAC5B,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,8BAA8B,CAAC;AAEhE,KAAK,gBAAgB,GAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC,GAAG;IACnF,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AA0BH,QAAA,MAAM,SAAS,sDAAwC,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}

package/dist/MdzStreamNodeView.svelte

@@ -1,12 +1,7 @@
 <script lang="ts">
 	import {resolve} from '$app/paths';
 
-	import {
-		mdz_resolve_relative_path,
-		mdz_is_safe_reference,
-		mdz_is_void_element,
-	} from './mdz_helpers.js';
-	import MdzStreamNodeView from './MdzStreamNodeView.svelte';
+	import {mdz_classify_link, mdz_is_void_element} from './mdz_helpers.js';
 	import {
 		mdz_components_context,
 		mdz_elements_context,
@@ -15,12 +10,15 @@
 		mdz_codeblock_context,
 	} from './mdz_contexts.js';
 	import type {MdzStreamNode} from './mdz_stream_state.svelte.js';
+	import type {MdzTableAlign} from './mdz.js';
 
 	const {
 		node,
-	}: {
-		node: MdzStreamNode;
-	} = $props();
+		nodes,
+	}: // exactly one of `node`/`nodes` — the array form renders a whole tree
+		// through this single component instance (used by `MdzStream`)
+		{node: MdzStreamNode; nodes?: undefined} | {node?: undefined; nodes: Array<MdzStreamNode>} =
+		$props();
 
 	const get_components = mdz_components_context.get_maybe();
 	const get_elements = mdz_elements_context.get_maybe();
@@ -37,105 +35,141 @@
 		n.content || n.children.map((c) => c.content).join('');
 </script>
 
-{#if node.type === 'Element'}
-	{@const element_config = get_elements?.()?.get(node.name ?? '')}
-	{#if element_config !== undefined}
-		{#if mdz_is_void_element(node.name ?? '')}
-			<!-- void elements cannot have content — any parsed children are dropped -->
-			<svelte:element this={node.name} />
+<!-- The tree renders through recursive snippets rather than recursive
+component instances — one component (and one set of context reads) per
+tree instead of per node. -->
+{#if nodes}
+	{@render render_children(nodes)}
+{:else if node}
+	{@render render_node(node)}
+{/if}
+
+{#snippet render_node(node: MdzStreamNode)}
+	{#if node.type === 'Element'}
+		{@const element_config = get_elements?.()?.get(node.name ?? '')}
+		{#if element_config !== undefined}
+			{#if mdz_is_void_element(node.name ?? '')}
+				<!-- void elements cannot have content — any parsed children are dropped -->
+				<svelte:element this={node.name} />
+			{:else}
+				<svelte:element this={node.name}>
+					{#if node.children.length > 0}
+						{@render render_children(node.children)}
+					{/if}
+				</svelte:element>
+			{/if}
 		{:else}
-			<svelte:element this={node.name}>
+			{@render render_unregistered_tag(node.name ?? '', node.children)}
+		{/if}
+	{:else if node.type === 'Component'}
+		{@const Component = get_components?.()?.get(node.name ?? '')}
+		{#if Component}
+			<Component>
 				{#if node.children.length > 0}
 					{@render render_children(node.children)}
 				{/if}
-			</svelte:element>
+			</Component>
+		{:else}
+			{@render render_unregistered_tag(node.name ?? '', node.children)}
 		{/if}
-	{:else}
-		{@render render_unregistered_tag(node.name ?? '', node.children)}
-	{/if}
-{:else if node.type === 'Component'}
-	{@const Component = get_components?.()?.get(node.name ?? '')}
-	{#if Component}
-		<Component>
-			{#if node.children.length > 0}
-				{@render render_children(node.children)}
-			{/if}
-		</Component>
-	{:else}
-		{@render render_unregistered_tag(node.name ?? '', node.children)}
-	{/if}
-{:else if node.type === 'Text'}
-	{node.content}
-{:else if node.type === 'Code'}
-	{@const Code = get_code?.()}
-	{@const code_content = streaming_content(node)}
-	{#if Code}
-		<Code reference={code_content} />
-	{:else}
-		<code>{code_content}</code>
-	{/if}
-{:else if node.type === 'Bold'}
-	<strong>{@render render_children(node.children)}</strong>
-{:else if node.type === 'Italic'}
-	<em>{@render render_children(node.children)}</em>
-{:else if node.type === 'Strikethrough'}
-	<s>{@render render_children(node.children)}</s>
-{:else if node.type === 'Link'}
-	{@const reference = node.reference ?? ''}
-	{#if !mdz_is_safe_reference(reference)}
-		{@render render_children(node.children)}
-	{:else if node.link_type === 'internal'}
-		{@const skip_resolve = reference.startsWith('#') || reference.startsWith('?')}
-		{@const mdz_base = get_mdz_base?.()}
-		{#if reference.startsWith('.') && mdz_base}
-			{@const resolved = mdz_resolve_relative_path(reference, mdz_base)}
-			<a href={resolve(resolved as any)}>{@render render_children(node.children)}</a>
-		{:else if skip_resolve || reference.startsWith('.') || !reference.startsWith('/')}
-			<!-- Fragment, query, and relative links (including bare references like `foo`) skip resolve() -->
-			<!-- resolve() only accepts absolute pathnames or route IDs and throws on anything else -->
+	{:else if node.type === 'Text'}
+		{node.content}
+	{:else if node.type === 'Code'}
+		{@const Code = get_code?.()}
+		{@const code_content = streaming_content(node)}
+		{#if Code}
+			<Code reference={code_content} />
+		{:else}
+			<code>{code_content}</code>
+		{/if}
+	{:else if node.type === 'Bold'}
+		<strong>{@render render_children(node.children)}</strong>
+	{:else if node.type === 'Italic'}
+		<em>{@render render_children(node.children)}</em>
+	{:else if node.type === 'Strikethrough'}
+		<s>{@render render_children(node.children)}</s>
+	{:else if node.type === 'Link'}
+		{@const link = mdz_classify_link(node.reference ?? '', node.link_type, get_mdz_base?.())}
+		{#if link.kind === 'unsafe'}
+			{@render render_children(node.children)}
+		{:else if link.kind === 'resolve'}
+			<a href={resolve(link.href as any)}>{@render render_children(node.children)}</a>
+		{:else if link.kind === 'external'}
 			<!-- eslint-disable-next-line svelte/no-navigation-without-resolve -->
-			<a href={reference}>{@render render_children(node.children)}</a>
+			<a href={link.href} target="_blank" rel="noopener">{@render render_children(node.children)}</a
+			>
 		{:else}
-			<a href={resolve(reference as any)}>{@render render_children(node.children)}</a>
+			<!-- fragment/query/relative/bare references skip resolve() (it accepts only absolute paths) -->
+			<!-- eslint-disable-next-line svelte/no-navigation-without-resolve -->
+			<a href={link.href}>{@render render_children(node.children)}</a>
 		{/if}
-	{:else}
-		<!-- external link -->
-		<!-- eslint-disable-next-line svelte/no-navigation-without-resolve -->
-		<a href={reference} target="_blank" rel="noopener">{@render render_children(node.children)}</a>
-	{/if}
-{:else if node.type === 'Paragraph'}
-	<p>{@render render_children(node.children)}</p>
-{:else if node.type === 'List'}
-	{#if node.ordered}
-		<ol start={node.start_number === 1 ? undefined : node.start_number}>
+	{:else if node.type === 'Paragraph'}
+		<p>{@render render_children(node.children)}</p>
+	{:else if node.type === 'List'}
+		{#if node.ordered}
+			<ol start={node.start_number === 1 ? undefined : node.start_number}>
+				{@render render_children(node.children)}
+			</ol>
+		{:else}
+			<ul>{@render render_children(node.children)}</ul>
+		{/if}
+	{:else if node.type === 'ListItem'}
+		<li>{@render render_children(node.children)}</li>
+	{:else if node.type === 'Blockquote'}
+		<blockquote>{@render render_children(node.children)}</blockquote>
+	{:else if node.type === 'Table'}
+		{@const align = node.align ?? []}
+		<!-- by grammar the header row is always first (and the only one) — read
+		it by index and skip it per-row in the body, rather than filtering: a
+		filter re-partitions every prior row on each streamed row append,
+		going O(n²) across a streamed table -->
+		{@const header_row = node.children[0]?.header ? node.children[0] : undefined}
+		<table>
+			{#if header_row}
+				<thead>
+					<tr>{@render render_cells(header_row, 'th', align)}</tr>
+				</thead>
+			{/if}
+			{#if node.children.length > (header_row ? 1 : 0)}
+				<tbody>
+					{#each node.children as row (row.id)}
+						{#if !row.header}
+							<tr>{@render render_cells(row, 'td', align)}</tr>
+						{/if}
+					{/each}
+				</tbody>
+			{/if}
+		</table>
+	{:else if node.type === 'Hr'}
+		<hr />
+	{:else if node.type === 'Heading'}
+		<svelte:element this={`h${node.level}`} id={node.heading_id || undefined}>
 			{@render render_children(node.children)}
-		</ol>
-	{:else}
-		<ul>{@render render_children(node.children)}</ul>
-	{/if}
-{:else if node.type === 'ListItem'}
-	<li>{@render render_children(node.children)}</li>
-{:else if node.type === 'Blockquote'}
-	<blockquote>{@render render_children(node.children)}</blockquote>
-{:else if node.type === 'Hr'}
-	<hr />
-{:else if node.type === 'Heading'}
-	<svelte:element this={`h${node.level}`} id={node.heading_id || undefined}>
-		{@render render_children(node.children)}
-	</svelte:element>
-{:else if node.type === 'Codeblock'}
-	{@const Codeblock = get_codeblock?.()}
-	{@const codeblock_content = streaming_content(node)}
-	{#if Codeblock}
-		<Codeblock lang={node.lang ?? null} content={codeblock_content} />
-	{:else}
-		<pre><code>{codeblock_content}</code></pre>
+		</svelte:element>
+	{:else if node.type === 'Codeblock'}
+		{@const Codeblock = get_codeblock?.()}
+		{@const codeblock_content = streaming_content(node)}
+		{#if Codeblock}
+			<Codeblock lang={node.lang ?? null} content={codeblock_content} />
+		{:else}
+			<pre><code>{codeblock_content}</code></pre>
+		{/if}
 	{/if}
-{/if}
+{/snippet}
 
 {#snippet render_children(nodes: Array<MdzStreamNode>)}
 	{#each nodes as node (node.id)}
-		<MdzStreamNodeView {node} />
+		{@render render_node(node)}
+	{/each}
+{/snippet}
+
+{#snippet render_cells(row: MdzStreamNode, tag: 'th' | 'td', align: Array<MdzTableAlign>)}
+	<!-- normalize to the column count: pad short rows, ignore extra cells -->
+	{#each align as a, i (i)}
+		{@const cell = row.children[i]}
+		<svelte:element this={tag} style={a ? `text-align:${a}` : undefined}>
+			{#if cell}{@render render_children(cell.children)}{/if}
+		</svelte:element>
 	{/each}
 {/snippet}