@fuzdev/mdz 0.4.0 → 0.6.0

package/src/lib/mdz_lexer.ts

@@ -26,6 +26,9 @@ import {
 	LEFT_ANGLE,
 	RIGHT_ANGLE,
 	SLASH,
+	EQUALS,
+	APOSTROPHE,
+	DOUBLE_QUOTE,
 	PERIOD,
 	LEFT_BRACKET,
 	LEFT_PAREN,
@@ -58,7 +61,7 @@ import {
 	TEXT_SCAN_CLASS
 } from './mdz_helpers.ts';
 
-import type { MdzTableAlign } from './mdz.ts';
+import type { MdzAttribute, MdzTableAlign } from './mdz.ts';
 import { mdz_debug_work } from './mdz_debug_work.ts';
 
 //
@@ -177,12 +180,14 @@ export interface MdzTokenTagOpen extends MdzTokenBase {
 	type: 'tag_open';
 	name: string;
 	is_component: boolean;
+	attributes: Array<MdzAttribute>;
 }
 
 export interface MdzTokenTagSelfClose extends MdzTokenBase {
 	type: 'tag_self_close';
 	name: string;
 	is_component: boolean;
+	attributes: Array<MdzAttribute>;
 }
 
 export interface MdzTokenTagClose extends MdzTokenBase {
@@ -1794,9 +1799,78 @@ export class MdzLexer {
 		const first_char_code = tag_name.charCodeAt(0);
 		const is_component = first_char_code >= A_UPPER && first_char_code <= Z_UPPER;
 
-		// Skip whitespace
-		while (this.#index < this.#text.length && this.#text.charCodeAt(this.#index) === SPACE) {
-			this.#index++;
+		// Attribute loop: consume space-separated attributes until `/>` or `>`.
+		// Registry-blind — every syntactically valid attribute is parsed here;
+		// policy (allowlist filtering) happens at render/build time. The scan is
+		// a single forward pass bounded by the line: any newline (or a missing
+		// separator, bad value, or duplicate name) rejects the whole tag to
+		// literal text via the shared `#reject_tag` bailout.
+		const attributes: Array<MdzAttribute> = [];
+		const seen = new Set<string>(); // O(1) duplicate-name detection
+		for (;;) {
+			// skip a run of literal spaces only (tabs/newlines are not SPACE, so
+			// they fall through to the reject path — the single-line, space-only rule)
+			let had_space = false;
+			while (this.#index < this.#text.length && this.#text.charCodeAt(this.#index) === SPACE) {
+				this.#index++;
+				had_space = true;
+			}
+			const c = this.#index < this.#text.length ? this.#text.charCodeAt(this.#index) : -1;
+			// `/>` or `>` ends the open tag — break to the existing self-close / commit
+			if (c === SLASH || c === RIGHT_ANGLE) break;
+			// otherwise an attribute name must follow, space-separated from what
+			// precedes it (`<a x="1"y="2">` rejects — `y` abuts the closing quote)
+			if (c === -1 || !had_space || !is_letter(c)) {
+				this.#reject_tag(start, bound);
+				return;
+			}
+			// collect the attribute name (same grammar as tag names)
+			const attr_start = this.#index;
+			this.#index++; // first char already passed is_letter
+			while (
+				this.#index < this.#text.length &&
+				is_tag_name_char(this.#text.charCodeAt(this.#index))
+			) {
+				this.#index++;
+			}
+			const name = this.#text.slice(attr_start, this.#index);
+			// duplicate names are ambiguous (Svelte compile-errors) → literal tag
+			if (seen.has(name)) {
+				this.#reject_tag(start, bound);
+				return;
+			}
+			seen.add(name);
+			let value: string | true = true; // bare name is boolean `true`
+			if (this.#index < this.#text.length && this.#text.charCodeAt(this.#index) === EQUALS) {
+				this.#index++; // consume =
+				// the value must be immediately quoted — no space after `=`, no
+				// `{` brace literal, no unquoted value (this one check covers all)
+				const quote = this.#index < this.#text.length ? this.#text.charCodeAt(this.#index) : -1;
+				if (quote !== DOUBLE_QUOTE && quote !== APOSTROPHE) {
+					this.#reject_tag(start, bound);
+					return;
+				}
+				this.#index++; // consume opening quote
+				const value_start = this.#index;
+				// scan to the matching quote, bounded by newline / text end — NOT
+				// by `#max_search_index` (the open-tag scan never is); a `>` inside
+				// the value is content, consumed atomically before `>` is sought
+				while (
+					this.#index < this.#text.length &&
+					this.#text.charCodeAt(this.#index) !== quote &&
+					this.#text.charCodeAt(this.#index) !== NEWLINE
+				) {
+					this.#index++;
+				}
+				if (this.#index >= this.#text.length || this.#text.charCodeAt(this.#index) === NEWLINE) {
+					// unterminated quote (or newline inside the value) → literal tag
+					this.#reject_tag(start, bound);
+					return;
+				}
+				value = this.#text.slice(value_start, this.#index);
+				this.#index++; // consume closing quote
+			}
+			attributes.push({ name, value, start: attr_start, end: this.#index });
 		}
 
 		// Check for self-closing />
@@ -1810,6 +1884,7 @@ export class MdzLexer {
 				type: 'tag_self_close',
 				name: tag_name,
 				is_component,
+				attributes,
 				start,
 				end: this.#index
 			});
@@ -1818,9 +1893,7 @@ export class MdzLexer {
 
 		// Check for >
 		if (this.#index >= this.#text.length || this.#text.charCodeAt(this.#index) !== RIGHT_ANGLE) {
-			this.#failed_tag.add(`${start}:${bound}`);
-			this.#index = start + 1;
-			this.#emit_text('<', start);
+			this.#reject_tag(start, bound);
 			return;
 		}
 		this.#index++; // consume >
@@ -1837,21 +1910,24 @@ export class MdzLexer {
 		const search_limit = Math.min(this.#max_search_index, this.#text.length);
 		const closing_tag_pos = this.#index_of(closing_tag, this.#index);
 		if (closing_tag_pos === -1 || closing_tag_pos > search_limit) {
-			this.#failed_tag.add(`${start}:${bound}`);
-			this.#index = start + 1;
-			this.#emit_text('<', start);
+			this.#reject_tag(start, bound);
 			return;
 		}
 		if (this.#has_paragraph_break_between(this.#index, closing_tag_pos)) {
-			this.#failed_tag.add(`${start}:${bound}`);
-			this.#index = start + 1;
-			this.#emit_text('<', start);
+			this.#reject_tag(start, bound);
 			return;
 		}
 
 		// Emit tag_open
 		const open_token_index = this.#tokens.length;
-		this.#tokens.push({ type: 'tag_open', name: tag_name, is_component, start, end: this.#index });
+		this.#tokens.push({
+			type: 'tag_open',
+			name: tag_name,
+			is_component,
+			attributes,
+			start,
+			end: this.#index
+		});
 
 		// Tokenize children until the closing tag. Each iteration narrows
 		// `#max_search_index` to the next closer so a child's delimiter scan
@@ -1892,8 +1968,15 @@ export class MdzLexer {
 		// (the `#revert_tokens_from_link_open` pattern; the old fallthrough
 		// left a dangling `tag_open` whose parser fallback discarded content)
 		this.#max_search_index = saved_max;
-		this.#failed_tag.add(`${start}:${bound}`);
 		this.#tokens.splice(open_token_index);
+		this.#reject_tag(start, bound);
+	}
+
+	// a tag open at `start` that can't commit: memoizes the failure for this
+	// `bound` so re-entries bail fast, then emits the `<` as text and resumes
+	// scanning after it — the rest re-parses as ordinary content
+	#reject_tag(start: number, bound: number): void {
+		this.#failed_tag.add(`${start}:${bound}`);
 		this.#index = start + 1;
 		this.#emit_text('<', start);
 	}

package/src/lib/mdz_opcodes.ts

@@ -12,7 +12,7 @@
  * @module
  */
 
-import type { MdzTableAlign } from './mdz.ts';
+import type { MdzAttribute, MdzTableAlign } from './mdz.ts';
 
 /**
  * Unique monotonic identifier for each node created by the parser.
@@ -66,6 +66,8 @@ export interface MdzOpcodeOpen {
 	level?: 1 | 2 | 3 | 4 | 5 | 6;
 	/** Tag name. Present when `node_type` is `'Element'` or `'Component'`. */
 	name?: string;
+	/** Parsed attributes. Present (possibly empty) when `node_type` is `'Element'` or `'Component'`. */
+	attributes?: Array<MdzAttribute>;
 	/** Language hint. Present when `node_type` is `'Codeblock'`. */
 	lang?: string | null;
 	/** Whether the list is ordered. Present when `node_type` is `'List'`. */

package/src/lib/mdz_opcodes_to_nodes.ts

@@ -20,6 +20,7 @@
 import { DEV } from 'esm-env';
 
 import type {
+	MdzAttribute,
 	MdzNode,
 	MdzNodeText,
 	MdzNodeLink,
@@ -42,6 +43,7 @@ interface StackFrame {
 	// metadata from open opcode
 	level?: number;
 	name?: string;
+	attributes?: Array<MdzAttribute>;
 	lang?: string | null;
 	ordered?: boolean;
 	start_number?: number;
@@ -77,6 +79,7 @@ export const mdz_opcodes_to_nodes = (opcodes: Array<MdzOpcode>): Array<MdzNode>
 					start: op.start,
 					level: op.level,
 					name: op.name,
+					attributes: op.attributes,
 					lang: op.lang,
 					ordered: op.ordered,
 					start_number: op.start_number,
@@ -489,6 +492,7 @@ const build_node = (frame: StackFrame, frame_children: Array<MdzNode>): MdzNode
 			return {
 				type: 'Element',
 				name: frame.name ?? '',
+				attributes: frame.attributes ?? [],
 				children: mdz_merge_adjacent_text(frame_children),
 				start: frame.start,
 				end: frame.end!
@@ -498,6 +502,7 @@ const build_node = (frame: StackFrame, frame_children: Array<MdzNode>): MdzNode
 			return {
 				type: 'Component',
 				name: frame.name ?? '',
+				attributes: frame.attributes ?? [],
 				children: mdz_merge_adjacent_text(frame_children),
 				start: frame.start,
 				end: frame.end!

package/src/lib/mdz_stream_parser_link.ts

@@ -6,8 +6,12 @@
  */
 
 import type { MdzNodeTypeContainer } from './mdz_opcodes.ts';
+import type { MdzAttribute } from './mdz.ts';
 import {
 	A_UPPER,
+	APOSTROPHE,
+	DOUBLE_QUOTE,
+	EQUALS,
 	LEFT_BRACKET,
 	LEFT_PAREN,
 	MAX_INLINE_NESTING_DEPTH,
@@ -211,11 +215,77 @@ export const try_tag_open = (state: MdzStreamParserState): TryResult => {
 
 	const name = state.buffer.slice(name_start, i);
 
-	// skip whitespace
-	while (i < state.buffer.length && state.buffer.charCodeAt(i) === SPACE) {
-		i++;
+	// Attribute loop: consume space-separated attributes until `/>` or `>`.
+	// This widens the held-tag-open rescan surface (the TODO above) with the
+	// attribute/value text — still line-bounded, since a newline anywhere aborts
+	// the whole tag (`not_match`). Every buffer-end point holds (`need_more`) so
+	// the same tree is produced regardless of where feeds split. The quoted-value
+	// terminator search reuses `buffer_index_of` (memoized, append-aware) so a
+	// long streamed value doesn't rescan quadratically across held retries,
+	// matching `try_complete_link`.
+	const attributes: Array<MdzAttribute> = [];
+	const seen = new Set<string>();
+	for (;;) {
+		// skip a run of literal spaces only (tabs/newlines are not SPACE)
+		let had_space = false;
+		while (i < state.buffer.length && state.buffer.charCodeAt(i) === SPACE) {
+			i++;
+			had_space = true;
+		}
+		if (i >= state.buffer.length) return 'need_more';
+
+		const c = state.buffer.charCodeAt(i);
+		// `/>` or `>` ends the open tag — break to the existing self-close / commit
+		if (c === SLASH || c === RIGHT_ANGLE) break;
+		// otherwise an attribute name must follow, space-separated from what
+		// precedes it (`<a x="1"y="2">` — `y` abuts the closing quote — reverts)
+		if (!is_letter(c)) return 'not_match';
+		if (!had_space) return 'not_match';
+
+		// collect the attribute name (same grammar as tag names)
+		const attr_start = i;
+		i++; // first char already passed is_letter
+		while (i < state.buffer.length && is_tag_name_char(state.buffer.charCodeAt(i))) {
+			i++;
+		}
+		if (i >= state.buffer.length) return 'need_more'; // mid-name — could still grow
+		const attr_name = state.buffer.slice(attr_start, i);
+		// duplicate names are ambiguous (Svelte compile-errors) → literal tag
+		if (seen.has(attr_name)) return 'not_match';
+		seen.add(attr_name);
+
+		let value: string | true = true; // bare name is boolean `true`
+		if (state.buffer.charCodeAt(i) === EQUALS) {
+			i++; // consume =
+			if (i >= state.buffer.length) return 'need_more'; // nothing after `=` yet
+			// the value must be immediately quoted — no space, no `{`, no unquoted
+			const quote_code = state.buffer.charCodeAt(i);
+			if (quote_code !== DOUBLE_QUOTE && quote_code !== APOSTROPHE) return 'not_match';
+			i++; // consume opening quote
+			const value_start = i;
+			// find the matching quote and the next newline via the memoized,
+			// append-aware search; a `>` inside the value is content, consumed
+			// atomically here so a `</Name>`-shaped substring never reaches
+			// `try_close_tag`
+			const quote_str = quote_code === DOUBLE_QUOTE ? '"' : "'";
+			const q = buffer_index_of(state, quote_str, value_start);
+			const n = buffer_index_of(state, '\n', value_start);
+			if (q !== -1 && (n === -1 || q < n)) {
+				value = state.buffer.slice(value_start, q);
+				i = q + 1; // past the closing quote
+			} else if (n !== -1 && (q === -1 || n < q)) {
+				return 'not_match'; // newline inside the value → literal tag
+			} else {
+				return 'need_more'; // neither found yet — unterminated so far, hold
+			}
+		}
+		attributes.push({
+			name: attr_name,
+			value,
+			start: offset(state, attr_start),
+			end: offset(state, i)
+		});
 	}
-	if (i >= state.buffer.length) return 'need_more';
 
 	// check for self-closing />
 	if (state.buffer.charCodeAt(i) === SLASH && i + 1 >= state.buffer.length) {
@@ -230,7 +300,7 @@ export const try_tag_open = (state: MdzStreamParserState): TryResult => {
 		ensure_paragraph(state);
 		const id = alloc_id(state);
 		const tag_start = offset(state, start);
-		emit(state, { type: 'open', id, node_type, start: tag_start, name });
+		emit(state, { type: 'open', id, node_type, start: tag_start, name, attributes });
 		emit(state, { type: 'close', id, end: offset(state, i + 2) });
 		state.active_text_id = null;
 		state.pos = i + 2;
@@ -253,8 +323,8 @@ export const try_tag_open = (state: MdzStreamParserState): TryResult => {
 	ensure_paragraph(state);
 	const id = alloc_id(state);
 	const tag_start = offset(state, start);
-	const delimiter = state.buffer.slice(start, i); // e.g., "<Alert>"
-	emit(state, { type: 'open', id, node_type, start: tag_start, name });
+	const delimiter = state.buffer.slice(start, i); // e.g., "<Alert>" or "<Alert x="1">"
+	emit(state, { type: 'open', id, node_type, start: tag_start, name, attributes });
 	push_stack_entry(state, id, node_type, tag_start, delimiter, name);
 	state.active_text_id = null;
 	state.pos = i;

package/src/lib/mdz_stream_parser_table.ts

@@ -402,7 +402,14 @@ const emit_inline_nodes = (state: MdzStreamParserState, nodes: Array<MdzNode>):
 			case 'Component': {
 				const id = alloc_id(state);
 				const s = offset(state, node.start);
-				emit(state, { type: 'open', id, node_type: node.type, start: s, name: node.name });
+				emit(state, {
+					type: 'open',
+					id,
+					node_type: node.type,
+					start: s,
+					name: node.name,
+					attributes: node.attributes
+				});
 				push_stack_entry(state, id, node.type, s, '', node.name);
 				emit_inline_nodes(state, node.children);
 				pop_stack_entry(state);

package/src/lib/mdz_stream_state.svelte.ts

@@ -11,7 +11,7 @@
 import { DEV } from 'esm-env';
 
 import type { MdzNodeId, MdzNodeType, MdzOpcode } from './mdz_opcodes.ts';
-import type { MdzTableAlign } from './mdz.ts';
+import type { MdzAttribute, MdzTableAlign } from './mdz.ts';
 
 /**
  * A reactive node in the stream renderer tree.
@@ -27,6 +27,8 @@ export class MdzStreamNode {
 	reference?: string = $state();
 	link_type?: 'external' | 'internal' = $state();
 	name?: string;
+	/** Parsed tag attributes (Element/Component nodes); known at open, never mutated, so plain not `$state`. */
+	attributes?: Array<MdzAttribute>;
 	lang?: string | null;
 	heading_id?: string = $state();
 	ordered?: boolean;
@@ -105,6 +107,7 @@ export class MdzStreamState {
 				const node = new MdzStreamNode(opcode.id, opcode.node_type);
 				if (opcode.level !== undefined) node.level = opcode.level;
 				if (opcode.name !== undefined) node.name = opcode.name;
+				if (opcode.attributes !== undefined) node.attributes = opcode.attributes;
 				if (opcode.lang !== undefined) node.lang = opcode.lang;
 				if (opcode.ordered !== undefined) node.ordered = opcode.ordered;
 				if (opcode.start_number !== undefined) node.start_number = opcode.start_number;

package/src/lib/mdz_to_svelte.ts

@@ -13,7 +13,34 @@ import { escape_svelte_text } from '@fuzdev/fuz_util/svelte_preprocess_helpers.t
 import { escape_js_string } from '@fuzdev/fuz_util/string.ts';
 
 import type { MdzNode, MdzNodeTableRow } from './mdz.ts';
-import { mdz_is_void_element, mdz_classify_link } from './mdz_helpers.ts';
+import type { MdzComponentProps } from './mdz_contexts.ts';
+import {
+	mdz_is_void_element,
+	mdz_classify_link,
+	mdz_filter_element_attributes,
+	mdz_filter_component_attributes,
+	ALLOWED_ELEMENT_ATTRIBUTES
+} from './mdz_helpers.ts';
+
+// emits parsed attributes as Svelte markup, matching the file's `name={'...'}`
+// idiom for string attrs. Booleans emit as `name={true}`, not bare — a bare
+// attribute compiles to `name=""`, while the runtime views spread `true`, which
+// Svelte renders per attribute (`aria-hidden="true"`); the expression form
+// keeps precompiled and runtime output identical. Each entry gets a leading
+// space, so the result splices straight after the tag name.
+/**
+ * A build-time component registry entry: an import path, or an import path
+ * plus the attribute names passed as props (see `MdzComponentProps`).
+ */
+export type MdzComponentImport = string | { path: string; props?: MdzComponentProps };
+
+const format_attributes = (entries: Array<[string, string | true]>): string => {
+	let out = '';
+	for (const [name, value] of entries) {
+		out += value === true ? ` ${name}={true}` : ` ${name}={'${escape_js_string(value)}'}`;
+	}
+	return out;
+};
 
 /**
  * Result of converting `MdzNode` arrays to Svelte markup.
@@ -38,10 +65,13 @@ const component_local_name = (import_path: string): string =>
  */
 export interface MdzToSvelteOptions {
 	/**
-	 * Component name to import path mapping (e.g., `{Alert: '#lib/Alert.svelte'}`).
+	 * Component name to import mapping, mirroring the runtime `MdzComponents`
+	 * registry: a bare import path receives no attributes
+	 * (`{Note: '#lib/Note.svelte'}`), and the config form names the attributes
+	 * passed as props (`{Alert: {path: '#lib/Alert.svelte', props: ['status']}}`).
 	 * If content references a component not in this map, `has_unconfigured_tags` is set.
 	 */
-	components: Record<string, string>;
+	components: Record<string, MdzComponentImport>;
 
 	/**
 	 * Allowed HTML elements (e.g., `{aside: true, details: true}`).
@@ -53,8 +83,9 @@ export interface MdzToSvelteOptions {
 
 	/**
 	 * Base path for resolving relative links (e.g., `'/docs/usage/'`).
-	 * When provided, relative references (`./`, `../`) are resolved to absolute paths
-	 * and passed through `resolve()`. Trailing slash recommended.
+	 * When provided, relative references (`./`, `../`) are resolved against it and,
+	 * like absolute references, passed through `resolve()` in its pathname form.
+	 * Trailing slash recommended.
 	 */
 	base?: string;
 
@@ -140,7 +171,7 @@ export const mdz_to_svelte = (
 				if (link.kind === 'unsafe') return children_markup;
 				if (link.kind === 'resolve') {
 					imports.set('resolve', { path: '$app/paths', kind: 'named' });
-					return `<a href={resolve('${escape_js_string(link.href)}')}>${children_markup}</a>`;
+					return `<a href={resolve('${escape_js_string(link.path)}')}>${children_markup}</a>`;
 				}
 				if (link.kind === 'external') {
 					return `<a href={'${escape_js_string(link.href)}'} target="_blank" rel="noopener">${children_markup}</a>`;
@@ -208,25 +239,38 @@ export const mdz_to_svelte = (
 			}
 
 			case 'Element': {
-				if (elements[node.name] === undefined) {
+				if (elements[node.name] !== true) {
 					has_unconfigured_tags = true;
 					return '';
 				}
+				// filter via the SAME helper the node views use, so precompiled and
+				// runtime output stay identical (its DEV-warn fires at build time too)
+				const attrs_str = format_attributes(
+					Object.entries(
+						mdz_filter_element_attributes(node.name, node.attributes, ALLOWED_ELEMENT_ATTRIBUTES)
+					)
+				);
 				if (mdz_is_void_element(node.name)) {
 					// void elements cannot have content — any parsed children are dropped
-					return `<${node.name} />`;
+					return `<${node.name}${attrs_str} />`;
 				}
-				return `<${node.name}>${render_nodes(node.children)}</${node.name}>`;
+				return `<${node.name}${attrs_str}>${render_nodes(node.children)}</${node.name}>`;
 			}
 
 			case 'Component': {
-				const import_path = components[node.name];
-				if (!import_path) {
+				const entry = components[node.name];
+				if (!entry) {
 					has_unconfigured_tags = true;
 					return '';
 				}
-				imports.set(node.name, { path: import_path, kind: 'default' });
-				return `<${node.name}>${render_nodes(node.children)}</${node.name}>`;
+				const { path, props } =
+					typeof entry === 'string' ? { path: entry, props: undefined } : entry;
+				imports.set(node.name, { path, kind: 'default' });
+				// filter via the SAME helper the node views use
+				const attrs_str = format_attributes(
+					Object.entries(mdz_filter_component_attributes(node.name, node.attributes, props))
+				);
+				return `<${node.name}${attrs_str}>${render_nodes(node.children)}</${node.name}>`;
 			}
 
 			default:

package/src/lib/mdz_token_parser.ts

@@ -581,7 +581,14 @@ export class MdzTokenParser {
 			const t = this.#tokens[this.#index]!;
 			if (t.type === 'tag_close' && t.name === tag_name) {
 				this.#index++;
-				return { type: node_type, name: tag_name, children, start, end: t.end };
+				return {
+					type: node_type,
+					name: tag_name,
+					attributes: open_token.attributes,
+					children,
+					start,
+					end: t.end
+				};
 			}
 			const node = this.#parse_inline();
 			if (node) mdz_push_merging_text(children, node);
@@ -595,7 +602,14 @@ export class MdzTokenParser {
 		const token = this.#tokens[this.#index]! as MdzTokenTagSelfClose;
 		const node_type: 'Component' | 'Element' = token.is_component ? 'Component' : 'Element';
 		this.#index++;
-		return { type: node_type, name: token.name, children: [], start: token.start, end: token.end };
+		return {
+			type: node_type,
+			name: token.name,
+			attributes: token.attributes,
+			children: [],
+			start: token.start,
+			end: token.end
+		};
 	}
 
 	// -- Paragraph flushing --

package/src/lib/svelte_preprocess_mdz.ts

@@ -37,7 +37,7 @@ import {
 } from '@fuzdev/fuz_util/svelte_preprocess_helpers.ts';
 
 import { mdz_parse } from './mdz.ts';
-import { mdz_to_svelte, type MdzToSvelteResult } from './mdz_to_svelte.ts';
+import { mdz_to_svelte, type MdzComponentImport, type MdzToSvelteResult } from './mdz_to_svelte.ts';
 
 /**
  * An estree `ImportDeclaration` augmented with Svelte's position data.
@@ -56,12 +56,14 @@ export interface SveltePreprocessMdzOptions {
 	/**
 	 * Component import mapping for mdz content.
 	 * Key: component name as used in mdz (e.g., 'Alert').
-	 * Value: import path (e.g., '#lib/Alert.svelte').
+	 * Value: import path (e.g., '#lib/Alert.svelte'), which receives no attributes,
+	 * or `{path, props}` naming the attributes passed as props
+	 * (e.g., `{path: '#lib/Alert.svelte', props: ['status']}`, or `props: 'all'`).
 	 *
 	 * If mdz content references a component not in this map,
 	 * that `Mdz` usage is skipped (left as runtime).
 	 */
-	components?: Record<string, string>;
+	components?: Record<string, MdzComponentImport>;
 
 	/**
 	 * Allowed HTML elements in mdz content (e.g., `{aside: true, details: true}`).
@@ -235,7 +237,7 @@ interface FindMdzUsagesResult {
 }
 
 interface FindMdzUsagesContext {
-	components: Record<string, string>;
+	components: Record<string, MdzComponentImport>;
 	elements: Record<string, boolean>;
 	filename: string | undefined;
 	source: string;