@fuzdev/fuz_ui 0.193.1 → 0.195.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_ui",
-  "version": "0.193.1",
+  "version": "0.195.0",
   "description": "Svelte UI library",
   "tagline": "friendly user zystem",
   "glyph": "🧶",
@@ -33,13 +33,13 @@
   },
   "type": "module",
   "engines": {
-    "node": ">=22.15"
+    "node": ">=24.14"
   },
   "peerDependencies": {
     "@fuzdev/fuz_code": ">=0.45.1",
     "@fuzdev/fuz_css": ">=0.53.0",
-    "@fuzdev/fuz_util": ">=0.52.0",
-    "@fuzdev/gro": ">=0.195.0",
+    "@fuzdev/fuz_util": "file:../fuz_util",
+    "@fuzdev/gro": "file:../gro",
     "@jridgewell/trace-mapping": "^0.3",
     "@sveltejs/kit": "^2.47.3",
     "@types/estree": "^1",
@@ -80,15 +80,16 @@
   },
   "devDependencies": {
     "@changesets/changelog-git": "^0.2.1",
+    "@fuzdev/blake3_wasm": "^0.1.0",
     "@fuzdev/fuz_code": "^0.45.1",
-    "@fuzdev/fuz_css": "^0.59.0",
+    "@fuzdev/fuz_css": "^0.60.0",
     "@fuzdev/fuz_util": "^0.61.1",
     "@fuzdev/gro": "^0.199.1",
     "@jridgewell/trace-mapping": "^0.3.31",
     "@ryanatkn/eslint-config": "^0.12.1",
     "@sveltejs/acorn-typescript": "^1.0.9",
     "@sveltejs/adapter-static": "^3.0.10",
-    "@sveltejs/kit": "^2.55.0",
+    "@sveltejs/kit": "^2.61.1",
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
     "@types/estree": "^1.0.8",
@@ -101,9 +102,10 @@
     "magic-string": "^0.30.21",
     "prettier": "^3.7.4",
     "prettier-plugin-svelte": "^3.5.1",
-    "svelte": "^5.55.0",
-    "svelte-check": "^4.4.5",
-    "svelte2tsx": "^0.7.52",
+    "svelte": "^5.55.10",
+    "svelte-check": "^4.4.8",
+    "svelte-docinfo": "^0.1.0",
+    "svelte2tsx": "^0.7.55",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.48.1",

package/src/lib/contextmenu_state.svelte.ts

@@ -10,6 +10,12 @@ import {Dimensions} from './dimensions.svelte.js';
 import {create_context} from './context_helpers.js';
 import {url_to_root_relative} from './library_helpers.js';
 
+export const contextmenu_context = create_context<() => ContextmenuState>();
+
+export const contextmenu_submenu_context = create_context<SubmenuState>();
+
+export const contextmenu_dimensions_context = create_context(() => new Dimensions());
+
 export type ContextmenuParams =
 	| Snippet
 	// TODO maybe this should be generic?
@@ -475,12 +481,6 @@ const contextmenu_query_params = (
 	return params;
 };
 
-export const contextmenu_context = create_context<() => ContextmenuState>();
-
-export const contextmenu_submenu_context = create_context<SubmenuState>();
-
-export const contextmenu_dimensions_context = create_context(() => new Dimensions());
-
 // Global registry of non-scoped contextmenu roots (only used in DEV)
 const non_scoped_roots: Set<symbol> = new Set();
 

package/src/lib/declaration.svelte.ts

@@ -1,20 +1,40 @@
-import {
-	type DeclarationJson,
-	declaration_generate_import,
-	declaration_get_display_name,
-} from '@fuzdev/fuz_util/source_json.js';
+import type {
+	DeclarationJson,
+	DeclarationJsonInput,
+	MemberJsonInput,
+	ParameterJsonInput,
+	ComponentPropJsonInput,
+	OverloadJsonInput,
+} from 'svelte-docinfo/types.js';
+import {generateImport, getDisplayName} from 'svelte-docinfo/declaration-helpers.js';
 
 import type {Module} from './module.svelte.js';
 import {url_github_file} from './package_helpers.js';
 
-/* eslint-disable @typescript-eslint/no-deprecated */
+// `library.json` is serialized with svelte-docinfo's `compactReplacer`, which
+// strips empty default arrays — so the on-disk data is the `*Input` shape
+// (defaulted arrays optional), not the parsed `*Json` shape. Typing it as
+// input makes TypeScript force a guard on every defaulted-array read.
+//
+// Helper to access kind-specific fields on the discriminated union.
+// At runtime the field is present or undefined; TypeScript needs the cast.
+const field = <T>(decl: DeclarationJsonInput, key: string): T | undefined =>
+	(decl as Record<string, unknown>)[key] as T | undefined;
 
 /**
  * Rich runtime representation of an exported declaration.
+ *
+ * Wraps svelte-docinfo's `DeclarationJson` discriminated union (on `kind`)
+ * with Svelte 5 reactive derivations and computed URLs.
+ * Kind-specific fields are accessed via the `field()` helper since
+ * not all fields exist on all variants.
+ *
+ * @see {@link https://github.com/ryanatkn/svelte-docinfo svelte-docinfo} for the analysis library
+ * @see `DeclarationDetail.svelte` for the rendering component
  */
 export class Declaration {
 	readonly module: Module = $state.raw()!;
-	readonly declaration_json: DeclarationJson = $state.raw()!;
+	readonly declaration_json: DeclarationJsonInput = $state.raw()!;
 
 	library = $derived(this.module.library);
 
@@ -30,11 +50,11 @@ export class Declaration {
 	 * GitHub source URL with line number.
 	 */
 	url_github = $derived(
-		this.library.repo_url && this.declaration_json.source_line
+		this.library.repo_url && this.declaration_json.sourceLine
 			? url_github_file(
 					this.library.repo_url,
 					`src/lib/${this.module_path}`,
-					this.declaration_json.source_line,
+					this.declaration_json.sourceLine,
 				)
 			: undefined,
 	);
@@ -48,8 +68,10 @@ export class Declaration {
 	 * Generated TypeScript import statement.
 	 */
 	import_statement = $derived(
-		declaration_generate_import(
-			this.declaration_json,
+		// `generateImport` reads only `name`/`kind`/path, none of the defaulted
+		// arrays, so asserting the parsed shape here is sound.
+		generateImport(
+			this.declaration_json as DeclarationJson,
 			this.module_path,
 			this.library.package_json.name,
 		),
@@ -67,37 +89,70 @@ export class Declaration {
 	/**
 	 * Display name with generic parameters.
 	 */
-	display_name = $derived(declaration_get_display_name(this.declaration_json));
-
-	type_signature = $derived(this.declaration_json.type_signature);
-	doc_comment = $derived(this.declaration_json.doc_comment);
-	deprecated_message = $derived(this.declaration_json.deprecated_message);
-	parameters = $derived(this.declaration_json.parameters);
-	props = $derived(this.declaration_json.props);
-	return_type = $derived(this.declaration_json.return_type);
-	return_description = $derived(this.declaration_json.return_description);
-	generic_params = $derived(this.declaration_json.generic_params);
-	extends = $derived(this.declaration_json.extends);
-	implements = $derived(this.declaration_json.implements);
-	throws = $derived(this.declaration_json.throws);
-	since = $derived(this.declaration_json.since);
-	examples = $derived(this.declaration_json.examples);
-	see_also = $derived(this.declaration_json.see_also);
-	members: Array<DeclarationJson> | undefined = $derived(
-		this.declaration_json.members as Array<DeclarationJson> | undefined,
-	);
-	properties: Array<DeclarationJson> | undefined = $derived(
-		this.declaration_json.properties as Array<DeclarationJson> | undefined,
+	// `getDisplayName` reads `genericParams` unguarded, so feed it the defaulted
+	// value rather than the raw (possibly-absent) input field.
+	display_name = $derived(
+		getDisplayName({
+			...this.declaration_json,
+			genericParams: this.declaration_json.genericParams ?? [],
+		} as DeclarationJson),
 	);
 
-	has_examples = $derived(!!(this.examples && this.examples.length > 0));
+	type_signature = $derived(this.declaration_json.typeSignature);
+	doc_comment = $derived(this.declaration_json.docComment);
+	deprecated_message = $derived(this.declaration_json.deprecatedMessage);
+	parameters = $derived(field<Array<ParameterJsonInput>>(this.declaration_json, 'parameters'));
+	props = $derived(field<Array<ComponentPropJsonInput>>(this.declaration_json, 'props'));
+	return_type = $derived(field<string>(this.declaration_json, 'returnType'));
+	return_description = $derived(field<string>(this.declaration_json, 'returnDescription'));
+	generic_params = $derived(this.declaration_json.genericParams ?? []);
+	extends_type = $derived(field<string | Array<string>>(this.declaration_json, 'extends'));
+	implements_types = $derived(field<Array<string>>(this.declaration_json, 'implements'));
+	throws = $derived(this.declaration_json.throws ?? []);
+	since = $derived(this.declaration_json.since);
+	examples = $derived(this.declaration_json.examples ?? []);
+	see_also = $derived(this.declaration_json.seeAlso ?? []);
+	/**
+	 * Nested members for classes, interfaces, types, and enums.
+	 */
+	members = $derived(field<Array<MemberJsonInput>>(this.declaration_json, 'members'));
+
+	/**
+	 * Intersection types whose properties are external (filtered out of props/members).
+	 * Present on `component` and `type` kinds.
+	 */
+	intersects = $derived(field<Array<string>>(this.declaration_json, 'intersects'));
+
+	/**
+	 * Whether a component accepts children via props or template usage.
+	 * Present on `component` kind only.
+	 */
+	accepts_children = $derived(field<boolean>(this.declaration_json, 'acceptsChildren'));
+
+	/**
+	 * Function overload signatures when multiple public overloads exist.
+	 * Present on `function` and `snippet` kinds, and on function/constructor members.
+	 */
+	overloads = $derived(field<Array<OverloadJsonInput>>(this.declaration_json, 'overloads'));
+
+	/**
+	 * Re-export alias info when this declaration is a renamed re-export.
+	 */
+	alias_of = $derived(this.declaration_json.aliasOf);
+
+	/**
+	 * Mutation documentation from `@mutates` tags, mapping parameter names to descriptions.
+	 */
+	mutates = $derived(this.declaration_json.mutates);
+
+	has_examples = $derived(this.examples.length > 0);
 	is_deprecated = $derived(!!this.deprecated_message);
 	has_documentation = $derived(!!this.doc_comment);
 	has_parameters = $derived(!!(this.parameters && this.parameters.length > 0));
 	has_props = $derived(!!(this.props && this.props.length > 0));
-	has_generics = $derived(!!(this.generic_params && this.generic_params.length > 0));
+	has_generics = $derived(this.generic_params.length > 0);
 
-	constructor(module: Module, declaration_json: DeclarationJson) {
+	constructor(module: Module, declaration_json: DeclarationJsonInput) {
 		this.module = module;
 		this.declaration_json = declaration_json;
 	}

package/src/lib/docs_helpers.svelte.ts

@@ -4,6 +4,8 @@ import {ensure_end, ensure_start} from '@fuzdev/fuz_util/string.js';
 
 import {create_context} from './context_helpers.js';
 
+export const docs_links_context = create_context<DocsLinks>();
+
 /**
  * Convert a string to a URL-safe fragment identifier, preserving case.
  * Unlike `slugify` from `@fuzdev/fuz_util/path.js` which lowercases,
@@ -42,8 +44,6 @@ export const to_docs_path_info = (
 	return {path, path_is_selected, path_segment};
 };
 
-export const docs_links_context = create_context<DocsLinks>();
-
 export type DocsLinkTag = 'h2' | 'h3' | 'h4';
 
 export interface DocsLinkInfo {

package/src/lib/library.svelte.ts

@@ -5,6 +5,8 @@ import {create_context} from './context_helpers.js';
 import {Declaration} from './declaration.svelte.js';
 import {Module} from './module.svelte.js';
 
+export const library_context = create_context<Library>();
+
 /**
  * Normalizes a URL prefix: ensures leading `/`, strips trailing `/`, returns `''` for falsy and non-string values.
  */
@@ -62,7 +64,7 @@ export class Library {
 	 */
 	readonly modules = $derived(
 		this.source_json.modules
-			? this.source_json.modules.map((module_json) => new Module(this, module_json))
+			? this.source_json.modules.map((module_json) => new Module(this, module_json as any)) // TODO: remove cast when fuz_util SourceJson uses svelte-docinfo types
 			: [],
 	);
 
@@ -116,8 +118,6 @@ export class Library {
 	}
 }
 
-export const library_context = create_context<Library>();
-
 /**
  * Search declarations by query string with multi-term AND logic.
  */

package/src/lib/library_gen.ts

@@ -1,15 +1,15 @@
 /**
  * Gro-specific library metadata generation.
  *
- * This module provides Gro integration for library generation. It wraps the generic
- * `library_generate` function with Gro's `Gen` interface and provides adapters for
- * converting Gro's `Disknode` to the build-tool agnostic `SourceFileInfo`.
+ * This module provides Gro integration for library generation. It uses svelte-docinfo's
+ * pure analysis (`analyze`) and wraps the results with fuz_ui's opinionated
+ * LibraryJson format (GitHub/npm metadata).
  *
- * For build-tool agnostic usage, see `library_generate.ts`.
+ * For build-tool agnostic usage, see `svelte-docinfo`.
  *
- * @see `library_generate.ts` for the generic generation entry point
- * @see `library_pipeline.ts` for pipeline helpers
- * @see `library_output.ts` for output file generation
+ * @see svelte-docinfo/analyze.js for the generic analysis entry point
+ * @see svelte-docinfo/postprocess.js for post-processing helpers
+ * @see library_output.js for output file generation
  *
  * @module
  */
@@ -17,17 +17,18 @@
 import type {Gen} from '@fuzdev/gro';
 import {package_json_load} from '@fuzdev/gro/package_json.js';
 import type {Disknode} from '@fuzdev/gro/disknode.js';
-
 import {
-	type SourceFileInfo,
+	analyze,
+	createSourceOptions,
 	type ModuleSourceOptions,
-	type ModuleSourcePartial,
-	module_create_source_options,
-	module_validate_source_options,
-	module_is_source,
-	module_get_source_root,
-} from './module_helpers.js';
-import {library_generate, type OnDuplicatesCallback} from './library_generate.js';
+	type OnDuplicatesCallback,
+	type SourceFileInfo,
+	type SourceOptionsDefaults,
+} from 'svelte-docinfo';
+import {normalizeSourceOptions, isSource, getSourceRoot} from 'svelte-docinfo/source-config.js';
+import type {SourceJson} from '@fuzdev/fuz_util/source_json.js';
+
+import {library_generate_output} from './library_output.js';
 
 /** Options for Gro library generation. */
 export interface LibraryGenOptions {
@@ -38,17 +39,17 @@ export interface LibraryGenOptions {
 	 * merged with defaults. The `project_root` is automatically set to
 	 * `process.cwd()` if not provided.
 	 */
-	source?: ModuleSourceOptions | Partial<ModuleSourcePartial>;
+	source?: ModuleSourceOptions | Partial<SourceOptionsDefaults>;
 	/**
 	 * Callback invoked when duplicate declaration names are found.
 	 *
 	 * Consumers decide how to handle duplicates: throw, warn, or ignore.
-	 * Use `library_throw_on_duplicates` for strict flat namespace enforcement.
+	 * Use `throwOnDuplicates` for strict flat namespace enforcement.
 	 *
 	 * @example
 	 * ```ts
 	 * // Throw on duplicates (strict flat namespace)
-	 * library_gen({ on_duplicates: library_throw_on_duplicates });
+	 * library_gen({ on_duplicates: throwOnDuplicates });
 	 *
 	 * // Warn but continue
 	 * library_gen({
@@ -66,7 +67,13 @@ export interface LibraryGenOptions {
 /**
  * Convert Gro's `Disknode` to the build-tool agnostic `SourceFileInfo` interface.
  *
- * Use this when you want to analyze files using Gro's filer directly.
+ * Use this when you want to analyze files using Gro's filer directly. The
+ * `dependencies` field is populated from the filer's forward-edge graph — the
+ * svelte-docinfo session honors it as pre-resolved input and skips its own
+ * lex+resolve pass for these files, avoiding duplicate work the filer already did.
+ *
+ * Reverse edges (`dependents`) are not threaded through — svelte-docinfo
+ * computes them internally from the forward edges of the owned set.
  *
  * @throws Error if disknode has no content (should be loaded by Gro filer)
  */
@@ -80,7 +87,6 @@ export const source_file_from_disknode = (disknode: Disknode): SourceFileInfo =>
 		id: disknode.id,
 		content: disknode.contents,
 		dependencies: [...disknode.dependencies.keys()],
-		dependents: [...disknode.dependents.keys()],
 	};
 };
 
@@ -88,7 +94,7 @@ export const source_file_from_disknode = (disknode: Disknode): SourceFileInfo =>
  * Collect source files from Gro disknodes, filtering BEFORE conversion to `SourceFileInfo`.
  *
  * This avoids errors from files outside source directories (like test fixtures that may
- * have malformed paths or missing content). The filtering uses `module_is_source` which
+ * have malformed paths or missing content). The filtering uses `isSource` which
  * checks `source_paths` to only include files in configured source directories.
  *
  * @param disknodes - iterator of Gro disknodes from filer
@@ -100,8 +106,10 @@ export const library_collect_source_files_from_disknodes = (
 	options: ModuleSourceOptions,
 	log?: {info: (...args: Array<unknown>) => void; warn: (...args: Array<unknown>) => void},
 ): Array<SourceFileInfo> => {
-	// Validate options early to fail fast on misconfiguration
-	module_validate_source_options(options);
+	// Normalize options (throws on invalid config) and use the normalized form
+	// for downstream `isSource` / `getSourceRoot` calls, so callers that pass
+	// raw options (not via `createSourceOptions`) get consistent path handling.
+	const normalized_options = normalizeSourceOptions(options);
 
 	const all_disknodes = Array.from(disknodes);
 	log?.info(`received ${all_disknodes.length} files total from filer`);
@@ -110,7 +118,7 @@ export const library_collect_source_files_from_disknodes = (
 	for (const disknode of all_disknodes) {
 		// Filter by source_paths BEFORE trying to convert
 		// This avoids errors from test fixtures or other non-source files
-		if (!module_is_source(disknode.id, options)) {
+		if (!isSource(disknode.id, normalized_options)) {
 			continue;
 		}
 		source_files.push(source_file_from_disknode(disknode));
@@ -119,7 +127,7 @@ export const library_collect_source_files_from_disknodes = (
 	log?.info(`found ${source_files.length} source files to analyze`);
 
 	if (source_files.length === 0) {
-		const effective_root = module_get_source_root(options);
+		const effective_root = getSourceRoot(normalized_options);
 		log?.warn(`No source files found in ${effective_root} - generating empty library metadata`);
 		return [];
 	}
@@ -135,10 +143,12 @@ export const library_collect_source_files_from_disknodes = (
  *
  * This is the Gro-specific entry point. It handles:
  * - Reading files from Gro's filer
- * - Loading `package.json` via Gro utilities
- * - Returning output in Gro's `Gen` format
+ * - Loading package.json via Gro utilities
+ * - Analyzing source with svelte-docinfo (pure analysis)
+ * - Wrapping with LibraryJson (GitHub/npm metadata)
+ * - Returning output in Gro's Gen format
  *
- * For build-tool agnostic usage, use `library_generate` directly.
+ * For build-tool agnostic usage, use `analyze` directly.
  *
  * Usage in a `.gen.ts` file:
  *
@@ -158,9 +168,9 @@ export const library_gen = (options?: LibraryGenOptions): Gen => {
 
 			// Build source options with project_root from cwd
 			const source_options: ModuleSourceOptions =
-				options?.source && 'project_root' in options.source
+				options?.source && 'projectRoot' in options.source
 					? options.source
-					: module_create_source_options(process.cwd(), options?.source);
+					: createSourceOptions(process.cwd(), options?.source);
 
 			// Ensure filer is initialized
 			await filer.init();
@@ -175,22 +185,35 @@ export const library_gen = (options?: LibraryGenOptions): Gen => {
 				log,
 			);
 
-			// Use generic library_generate for the actual work
-			const result = library_generate({
-				source_files,
-				package_json,
-				source_options,
-				on_duplicates: options?.on_duplicates,
-				log,
+			// Get pure analysis from svelte-docinfo (no package metadata).
+			const {modules} = await analyze({
+				sourceFiles: source_files,
+				sourceOptions: source_options,
+				onDuplicates: options?.on_duplicates,
+				log: log as any, // Type cast needed due to workspace dependency duplication
 			});
 
+			if (!package_json.version) {
+				throw new Error('package.json is missing required "version" field');
+			}
+			// Wrap modules with package metadata (fuz_ui's own SourceJson type)
+			const source_json: SourceJson = {
+				name: package_json.name,
+				version: package_json.version,
+				repository:
+					typeof package_json.repository === 'string'
+						? package_json.repository
+						: package_json.repository?.url,
+				modules: modules as any, // TODO: remove cast when fuz_util SourceJson uses svelte-docinfo types
+			};
+
+			// Generate output files with fuz_ui's LibraryJson wrapper
+			const {json_content, ts_content} = library_generate_output(package_json, source_json);
+
 			log.info('library metadata generation complete');
 
 			// Return array of files in Gro's expected format
-			return [
-				{content: result.ts_content},
-				{content: result.json_content, filename: 'library.json'},
-			];
+			return [{content: ts_content}, {content: json_content, filename: 'library.json'}];
 		},
 	};
 };

package/src/lib/library_output.ts

@@ -1,11 +1,12 @@
 /**
  * Library output generation.
  *
- * Generates the `library.json` and `library.ts` files from analyzed metadata.
+ * Generates the library.json and library.ts files from analyzed metadata.
+ * Uses svelte-docinfo's `compactReplacer` to strip Zod default values
+ * (empty arrays, false booleans) for compact JSON output.
  *
- * @see `library_generate.ts` for the main generation entry point
- * @see `library_pipeline.ts` for pipeline orchestration functions
- * @see `library_gen.ts` for Gro-specific integration
+ * @see `library_gen.ts` for the main generation entry point
+ * @see {@link https://github.com/ryanatkn/svelte-docinfo svelte-docinfo} for the analysis library
  *
  * @module
  */
@@ -13,6 +14,7 @@
 import type {PackageJson} from '@fuzdev/fuz_util/package_json.js';
 import type {SourceJson} from '@fuzdev/fuz_util/source_json.js';
 import {library_json_parse, type LibraryJson} from '@fuzdev/fuz_util/library_json.js';
+import {compactReplacer} from 'svelte-docinfo';
 
 /**
  * Result of generating library output files.
@@ -39,11 +41,12 @@ export const library_generate_output = (
 	package_json: PackageJson,
 	source_json: SourceJson,
 ): LibraryOutputResult => {
-	const is_this_fuz_util = package_json.name === '@fuzdev/fuz_util';
-	const fuz_util_prefix = is_this_fuz_util ? './' : '@fuzdev/fuz_util/';
+	// Compact source_json (strips Zod default values like empty arrays and false booleans)
+	// Only applied to source_json, not the outer library_json package metadata
+	const compacted_source_json = JSON.parse(JSON.stringify(source_json, compactReplacer));
 
 	// Parse at generation time, not runtime
-	const library_json: LibraryJson = library_json_parse(package_json, source_json);
+	const library_json: LibraryJson = library_json_parse(package_json, compacted_source_json);
 
 	const json_content = JSON.stringify(library_json, null, '\t') + '\n';
 
@@ -51,7 +54,7 @@ export const library_generate_output = (
 
 	const ts_content = `${banner}
 
-import type {LibraryJson} from '${fuz_util_prefix}library_json.js';
+import type {LibraryJson} from '@fuzdev/fuz_util/library_json.js';
 
 import json from './library.json' with {type: 'json'};
 

package/src/lib/mdz_components.ts

@@ -2,24 +2,6 @@ import type {Component} from 'svelte';
 
 import {create_context} from './context_helpers.js';
 
-/**
- * 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 the Svelte component constructors.
- */
-export type MdzComponents = Map<string, Component<any, any>>; // TODO support params
-
-/**
- * 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.
- */
-export type MdzElements = Map<string, boolean>;
-
 /**
  * Context for providing custom mdz components.
  * Must be set by the application using mdz.
@@ -41,3 +23,21 @@ export const mdz_elements_context = create_context<MdzElements>();
  * When not set, relative paths use raw hrefs (browser resolves them).
  */
 export const mdz_base_context = create_context<() => string | undefined>();
+
+/**
+ * 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 the Svelte component constructors.
+ */
+export type MdzComponents = Map<string, Component<any, any>>; // TODO support params
+
+/**
+ * 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.
+ */
+export type MdzElements = Map<string, boolean>;