@fuzdev/fuz_ui 0.189.1 → 0.191.0

package/src/lib/contextmenu_state.svelte.ts

@@ -344,7 +344,7 @@ let cache_key_counter = 0;
 
 /**
  * Creates an attachment that sets up contextmenu behavior on an element.
- * @param params Contextmenu parameters or nullish to disable
+ * @param params - contextmenu parameters or nullish to disable
  */
 export const contextmenu_attachment =
 	<T extends ContextmenuParams, U extends T | Array<T>>(
@@ -380,11 +380,11 @@ export interface ContextmenuOpenOptions {
 /**
  * Opens the contextmenu, if appropriate,
  * querying the menu items from the DOM starting at the event target.
- * @param target the leaf element from which to open the contextmenu
- * @param x the page X coordinate at which to open the contextmenu, typically the mouse `pageX`
- * @param y the page Y coordinate at which to open the contextmenu, typically the mouse `pageY`
- * @param contextmenu the contextmenu store
- * @param options optional configuration for filtering entries and haptic feedback
+ * @param target - the leaf element from which to open the contextmenu
+ * @param x - the page X coordinate at which to open the contextmenu, typically the mouse `pageX`
+ * @param y - the page Y coordinate at which to open the contextmenu, typically the mouse `pageY`
+ * @param contextmenu - the contextmenu store
+ * @param options - optional configuration for filtering entries and haptic feedback
  * @returns a boolean indicating if the menu was opened or not
  */
 export const contextmenu_open = (
@@ -487,7 +487,7 @@ const non_scoped_roots: Set<symbol> = new Set();
  * Registers a contextmenu root and warns if multiple non-scoped roots are detected.
  * Only active in development mode. Automatically handles cleanup on unmount.
  *
- * @param get_scoped Getter function that returns the current scoped value
+ * @param get_scoped - getter function that returns the current scoped value
  */
 export const contextmenu_check_global_root = (get_scoped: () => boolean): void => {
 	$effect(() => {

package/src/lib/docs_helpers.svelte.ts

@@ -5,11 +5,13 @@ import {ensure_end, ensure_start} from '@fuzdev/fuz_util/string.js';
 import {create_context} from './context_helpers.js';
 
 /**
- * Convert a string to a URL-safe fragment identifier, preserving case for API declarations.
- * Only transforms spaces and special characters, keeping valid identifier characters intact.
- * Used for hash anchors in documentation.
- * @param str - The string to convert to a fragment
- * @returns A URL-safe fragment identifier
+ * Convert a string to a URL-safe fragment identifier, preserving case.
+ * Unlike `slugify` from `@fuzdev/fuz_util/path.js` which lowercases,
+ * this keeps the original casing so API declarations like `AsyncStatus`
+ * and `async_status` produce distinct fragment IDs.
+ * Used by the Tome documentation system for heading and section anchors.
+ * @param str - the string to convert to a fragment
+ * @returns a URL-safe fragment identifier with case preserved
  */
 export const docs_slugify = (str: string): string => {
 	return (

package/src/lib/intersect.svelte.ts

@@ -30,7 +30,7 @@ export type IntersectParamsOrCallback = OnIntersect | IntersectParams;
  * Creates an attachment that observes element viewport intersection.
  * Uses the lazy function pattern to optimize reactivity:
  * callbacks can update without recreating the observer, preserving state.
- * @param get_params Function that returns callback, params object, or nullish to disable
+ * @param get_params - function that returns callback, params object, or nullish to disable
  */
 export const intersect =
 	(

package/src/lib/library_analysis.ts

@@ -113,11 +113,11 @@ export interface ModuleAnalysis {
  * only re-analyze changed files. The TypeScript program should include all files
  * for accurate type resolution, but only changed files need re-analysis.
  *
- * @param source_file The source file info with content and optional dependency data
- * @param program TypeScript program (used for type checking and source file lookup)
- * @param options Module source options for path extraction
- * @param ctx Analysis context for collecting diagnostics
- * @param log Optional logger for warnings
+ * @param source_file - the source file info with content and optional dependency data
+ * @param program - TypeScript program (used for type checking and source file lookup)
+ * @param options - module source options for path extraction
+ * @param ctx - analysis context for collecting diagnostics
+ * @param log - optional logger for warnings
  * @returns Module metadata and re-exports, or undefined if source file not found in program
  */
 export const library_analyze_module = (

package/src/lib/library_gen.ts

@@ -89,9 +89,9 @@ export const source_file_from_disknode = (disknode: Disknode): SourceFileInfo =>
  * have malformed paths or missing content). The filtering uses `module_is_source` which
  * checks `source_paths` to only include files in configured source directories.
  *
- * @param disknodes Iterator of Gro disknodes from filer
- * @param options Module source options for filtering
- * @param log Optional logger for status messages
+ * @param disknodes - iterator of Gro disknodes from filer
+ * @param options - module source options for filtering
+ * @param log - optional logger for status messages
  */
 export const library_collect_source_files_from_disknodes = (
 	disknodes: Iterable<Disknode>,
@@ -146,7 +146,7 @@ export const library_collect_source_files_from_disknodes = (
  * export const gen = library_gen();
  * ```
  *
- * @param options Optional generation options
+ * @param options - optional generation options
  */
 export const library_gen = (options?: LibraryGenOptions): Gen => {
 	return {

package/src/lib/library_generate.ts

@@ -43,8 +43,8 @@ import {AnalysisContext, format_diagnostic} from './analysis_context.js';
 /**
  * Callback for handling duplicate declaration names.
  *
- * @param duplicates Map of declaration names to their occurrences across modules
- * @param log Logger for reporting
+ * @param duplicates - map of declaration names to their occurrences across modules
+ * @param log - logger for reporting
  */
 export type OnDuplicatesCallback = (
 	duplicates: Map<string, Array<DuplicateInfo>>,

package/src/lib/library_helpers.ts

@@ -17,7 +17,7 @@ import {DOCS_API_PATH, DOCS_PATH_DEFAULT} from './docs_helpers.svelte.js';
 /**
  * Build project-relative API documentation URL with hash anchor.
  *
- * @param declaration_name Name of the declaration to link to
+ * @param declaration_name - name of the declaration to link to
  * @returns URL path like '/docs/api#declaration_name'
  */
 export const url_api_declaration = (declaration_name: string): string =>
@@ -26,8 +26,8 @@ export const url_api_declaration = (declaration_name: string): string =>
 /**
  * Build full API documentation URL with domain and hash anchor.
  *
- * @param homepage Package homepage URL
- * @param declaration_name Name of the declaration to link to
+ * @param homepage - package homepage URL
+ * @param declaration_name - name of the declaration to link to
  * @returns Full URL like 'https://example.com/docs/api#declaration_name'
  */
 export const url_api_declaration_full = (homepage: string, declaration_name: string): string =>
@@ -36,7 +36,7 @@ export const url_api_declaration_full = (homepage: string, declaration_name: str
 /**
  * Build project-relative module documentation URL.
  *
- * @param module_path Module path (e.g., 'helpers.ts')
+ * @param module_path - module path (e.g., 'helpers.ts')
  * @returns URL path like '/docs/api/helpers.ts'
  */
 export const url_api_module = (module_path: string): string => `${DOCS_API_PATH}/${module_path}`;
@@ -44,8 +44,8 @@ export const url_api_module = (module_path: string): string => `${DOCS_API_PATH}
 /**
  * Build package logo URL with favicon.png fallback.
  *
- * @param homepage_url Package homepage URL, or null
- * @param logo_path Optional custom logo path (defaults to 'favicon.png')
+ * @param homepage_url - package homepage URL, or null
+ * @param logo_path - optional custom logo path (defaults to 'favicon.png')
  * @returns Full URL to the logo, or null if no homepage
  */
 export const url_package_logo = (
@@ -62,8 +62,8 @@ export const url_package_logo = (
  *
  * Uses SvelteKit's page state for the current origin by default.
  *
- * @param url Full URL to convert
- * @param origin Origin to strip (defaults to current page origin)
+ * @param url - full URL to convert
+ * @param origin - origin to strip (defaults to current page origin)
  * @returns Root-relative URL starting with '/'
  *
  * @example

package/src/lib/library_pipeline.ts

@@ -130,8 +130,8 @@ export interface CollectedReExport {
  * // - helpers.ts foo declaration gets: also_exported_from: ['index.ts']
  * // - helpers.ts bar declaration gets: also_exported_from: ['index.ts']
  *
- * @param source_json The source JSON with all modules (will be mutated)
- * @param collected_re_exports Array of re-exports collected during phase 1
+ * @param source_json - the source JSON with all modules (will be mutated)
+ * @param collected_re_exports - array of re-exports collected during phase 1
  * @mutates source_json - adds `also_exported_from` to declarations
  */
 export const library_merge_re_exports = (
@@ -180,9 +180,9 @@ export const library_merge_re_exports = (
  * File types are determined by `options.get_analyzer`. By default, `.ts`, `.js`, and `.svelte`
  * files are supported. Customize `get_analyzer` to support additional file types like `.svx`.
  *
- * @param files Iterable of source file info (from Gro filer, file system, or other source)
- * @param options Module source options for filtering
- * @param log Optional logger for status messages
+ * @param files - iterable of source file info (from Gro filer, file system, or other source)
+ * @param options - module source options for filtering
+ * @param log - optional logger for status messages
  */
 export const library_collect_source_files = (
 	files: Iterable<SourceFileInfo>,

package/src/lib/mdz.ts

@@ -62,6 +62,8 @@ import {
 	is_at_absolute_path,
 	is_at_relative_path,
 	extract_single_tag,
+	mdz_heading_id,
+	mdz_is_url,
 } from './mdz_helpers.js';
 
 // TODO design incremental parsing or some system that preserves Svelte components across re-renders when possible
@@ -141,6 +143,7 @@ export interface MdzHrNode extends MdzBaseNode {
 export interface MdzHeadingNode extends MdzBaseNode {
 	type: 'Heading';
 	level: 1 | 2 | 3 | 4 | 5 | 6;
+	id: string; // slugified heading text for fragment links
 	children: Array<MdzNode>; // inline formatting allowed
 }
 
@@ -718,107 +721,41 @@ export class MdzParser {
 	#parse_tag(): MdzElementNode | MdzComponentNode | MdzTextNode {
 		const start = this.#index;
 
-		// Save parent accumulation state to avoid polluting component children with parent's accumulated text
-		const saved_state = this.#save_accumulation_state();
-
-		// Clear accumulation state for parsing component children
-		this.#accumulated_text = '';
-		this.#nodes.length = 0;
-
-		// Consume <
-		if (!this.#match('<')) {
-			// Restore parent state before returning
-			this.#restore_accumulation_state(saved_state);
-
-			const content = this.#template[this.#index]!;
-			this.#index++;
-			return {
-				type: 'Text',
-				content,
-				start,
-				end: this.#index,
-			};
-		}
-		this.#index++;
-
-		// Parse tag name
-		const tag_name_start = this.#index;
-		let tag_name_end = this.#index;
+		// Phase 1: Validate tag structure using a local scan index.
+		// Avoids save/restore of accumulation state on the fast path
+		// (most `<` characters are not valid tags).
+		let i = start + 1; // skip <
 
 		// Tag name must start with a letter
-		if (this.#index >= this.#template.length) {
-			// Just a `<` at EOF - restore parent state
-			this.#restore_accumulation_state(saved_state);
-			return {
-				type: 'Text',
-				content: '<',
-				start,
-				end: this.#index,
-			};
-		}
-
-		const first_char = this.#template.charCodeAt(this.#index);
-		if (!is_letter(first_char)) {
-			// Not a valid tag, treat as text - restore parent state
-			this.#restore_accumulation_state(saved_state);
-			return {
-				type: 'Text',
-				content: '<',
-				start,
-				end: start + 1,
-			};
+		if (i >= this.#template.length || !is_letter(this.#template.charCodeAt(i))) {
+			this.#index = start + 1;
+			return this.#make_text_node('<', start);
 		}
 
 		// Collect tag name (letters, numbers, hyphens, underscores)
-		while (this.#index < this.#template.length) {
-			const char_code = this.#template.charCodeAt(this.#index);
-			if (is_tag_name_char(char_code)) {
-				this.#index++;
-			} else {
-				break;
-			}
-		}
-
-		tag_name_end = this.#index;
-		const tag_name = this.#template.slice(tag_name_start, tag_name_end);
-
-		if (tag_name.length === 0) {
-			// Empty tag name - restore parent state
-			this.#restore_accumulation_state(saved_state);
-			return {
-				type: 'Text',
-				content: '<',
-				start,
-				end: start + 1,
-			};
+		while (i < this.#template.length && is_tag_name_char(this.#template.charCodeAt(i))) {
+			i++;
 		}
 
-		// Determine if this is a Component (uppercase) or Element (lowercase)
+		const tag_name = this.#template.slice(start + 1, i);
 		const first_char_code = tag_name.charCodeAt(0);
-		const is_component = first_char_code >= A_UPPER && first_char_code <= Z_UPPER;
-		const node_type: 'Component' | 'Element' = is_component ? 'Component' : 'Element';
+		const node_type: 'Component' | 'Element' =
+			first_char_code >= A_UPPER && first_char_code <= Z_UPPER ? 'Component' : 'Element';
 
 		// Skip whitespace after tag name (for future attribute support)
-		while (
-			this.#index < this.#template.length &&
-			this.#template.charCodeAt(this.#index) === SPACE
-		) {
-			this.#index++;
+		while (i < this.#template.length && this.#template.charCodeAt(i) === SPACE) {
+			i++;
 		}
 
 		// TODO: Parse attributes here
 
 		// Check for self-closing />
 		if (
-			this.#index + 1 < this.#template.length &&
-			this.#template.charCodeAt(this.#index) === SLASH &&
-			this.#template.charCodeAt(this.#index + 1) === RIGHT_ANGLE
+			i + 1 < this.#template.length &&
+			this.#template.charCodeAt(i) === SLASH &&
+			this.#template.charCodeAt(i + 1) === RIGHT_ANGLE
 		) {
-			this.#index += 2;
-
-			// Restore parent state before returning
-			this.#restore_accumulation_state(saved_state);
-
+			this.#index = i + 2;
 			return {
 				type: node_type,
 				name: tag_name,
@@ -828,41 +765,44 @@ export class MdzParser {
 			};
 		}
 
-		// Check for closing >
-		if (
-			this.#index >= this.#template.length ||
-			this.#template.charCodeAt(this.#index) !== RIGHT_ANGLE
-		) {
-			// Unclosed opening tag, treat as text - restore parent state
-			this.#restore_accumulation_state(saved_state);
-
+		// Must have closing >
+		if (i >= this.#template.length || this.#template.charCodeAt(i) !== RIGHT_ANGLE) {
 			this.#index = start + 1;
-			return {
-				type: 'Text',
-				content: '<',
-				start,
-				end: this.#index,
-			};
+			return this.#make_text_node('<', start);
 		}
 
-		// Consume >
-		this.#index++;
+		const content_start = i + 1; // past >
 
-		// Parse children until closing tag
+		// Bail early if closing tag is missing, past a paragraph break,
+		// or past the search boundary (e.g. heading line end)
 		const closing_tag = `</${tag_name}>`;
+		const search_limit = Math.min(this.#max_search_index, this.#template.length);
+		const close_tag_index = this.#template.indexOf(closing_tag, content_start);
+		if (close_tag_index === -1 || close_tag_index >= search_limit) {
+			this.#index = start + 1;
+			return this.#make_text_node('<', start);
+		}
+		const para_break = this.#template.indexOf('\n\n', content_start);
+		if (para_break !== -1 && para_break < close_tag_index) {
+			this.#index = start + 1;
+			return this.#make_text_node('<', start);
+		}
+
+		// Phase 2: Tag validated — save accumulation state and parse children.
+		const saved_state = this.#save_accumulation_state();
+		this.#accumulated_text = '';
+		this.#nodes.length = 0;
+		this.#index = content_start;
+
 		const children: Array<MdzNode> = [];
 
 		while (this.#index < this.#template.length) {
-			// Check for closing tag
 			if (this.#match(closing_tag)) {
-				// Flush any accumulated text from children
 				this.#flush_text();
 				children.push(...this.#nodes);
 				this.#nodes.length = 0;
 
 				this.#index += closing_tag.length;
-
-				// Restore parent state before returning
 				this.#restore_accumulation_state(saved_state);
 
 				return {
@@ -885,17 +825,10 @@ export class MdzParser {
 			}
 		}
 
-		// Unclosed tag - reached EOF without finding closing tag
-		// Treat the opening tag as text - restore parent state
+		// Defensive: pre-check guarantees closing tag exists, but handle EOF gracefully
 		this.#restore_accumulation_state(saved_state);
-
 		this.#index = start + 1;
-		return {
-			type: 'Text',
-			content: '<',
-			start,
-			end: this.#index,
-		};
+		return this.#make_text_node('<', start);
 	}
 
 	/**
@@ -1354,31 +1287,29 @@ export class MdzParser {
 		// Consume the space after hashes (already verified to exist)
 		this.#index++;
 
-		// Parse inline content until newline
-		const content_nodes: Array<MdzNode> = [];
+		// Find end-of-line to bound nested parsers (prevents tag scanner from scanning past heading)
+		let eol = this.#template.indexOf('\n', this.#index);
+		if (eol === -1) eol = this.#template.length;
 
-		while (this.#index < this.#template.length) {
-			const char_code = this.#template.charCodeAt(this.#index);
+		const saved_max_search_index = this.#max_search_index;
+		this.#max_search_index = eol;
 
-			if (char_code === NEWLINE) {
-				break;
-			}
+		// Parse inline content until end of line
+		const content_nodes: Array<MdzNode> = [];
 
+		while (this.#index < eol) {
 			const node = this.#parse_node();
 			if (node.type === 'Text') {
-				// Check if text node includes a newline (since #parse_text doesn't stop at single newlines)
-				// If so, trim it and move index back
-				const newline_index = node.content.indexOf('\n');
-				if (newline_index !== -1) {
-					const trimmed_content = node.content.slice(0, newline_index);
+				// Trim if #parse_text overshot past the newline
+				if (node.end > eol) {
+					const trimmed_content = node.content.slice(0, eol - node.start);
 					if (trimmed_content) {
 						this.#accumulate_text(trimmed_content, node.start);
 					}
-					this.#index = node.start + newline_index;
+					this.#index = eol;
 					break;
-				} else {
-					this.#accumulate_text(node.content, node.start);
 				}
+				this.#accumulate_text(node.content, node.start);
 			} else {
 				this.#flush_text();
 				content_nodes.push(...this.#nodes);
@@ -1387,6 +1318,8 @@ export class MdzParser {
 			}
 		}
 
+		this.#max_search_index = saved_max_search_index;
+
 		this.#flush_text();
 		content_nodes.push(...this.#nodes);
 		this.#nodes.length = 0;
@@ -1396,6 +1329,7 @@ export class MdzParser {
 		return {
 			type: 'Heading',
 			level: level as 1 | 2 | 3 | 4 | 5 | 6,
+			id: mdz_heading_id(content_nodes),
 			children: content_nodes,
 			start,
 			end: this.#index,
@@ -1587,41 +1521,3 @@ export class MdzParser {
 		throw Error('Code block not properly closed');
 	}
 }
-
-/**
- * Check if a string is a URL (`https://` or `http://`).
- * Requires at least one valid character after the protocol.
- * Rejects whitespace and characters that can't start a valid hostname.
- */
-const URL_PATTERN = /^https?:\/\/[^\s)\]}<>.,:/?#!]/;
-export const mdz_is_url = (s: string): boolean => URL_PATTERN.test(s);
-
-/**
- * Resolves a relative path (`./` or `../`) against a base path.
- * The base is treated as a directory regardless of trailing slash
- * (`'/docs/mdz'` and `'/docs/mdz/'` 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.
- *
- * @param reference A relative path starting with `./` or `../`.
- * @param base An absolute base path (e.g., `'/docs/mdz/'`). Empty string is treated as root.
- * @returns An absolute resolved path (e.g., `'/docs/mdz/grammar'`).
- */
-export const resolve_relative_path = (reference: string, base: string): string => {
-	const segments = base.split('/');
-	// Remove trailing empty from split (e.g., '/docs/mdz/' → ['', 'docs', 'mdz', ''])
-	// but keep the root segment ([''] from '' base or ['', ''] from '/').
-	if (segments.length > 1 && segments.at(-1) === '') segments.pop();
-	const trailing = reference.endsWith('/');
-	for (const segment of reference.split('/')) {
-		if (segment === '.' || segment === '') continue;
-		if (segment === '..') {
-			if (segments.length > 1) segments.pop(); // clamp at root
-		} else {
-			segments.push(segment);
-		}
-	}
-	if (trailing) segments.push('');
-	return segments.join('/');
-};

package/src/lib/mdz_helpers.ts

@@ -8,6 +8,7 @@
  */
 
 import type {MdzNode, MdzComponentNode, MdzElementNode} from './mdz.js';
+import {slugify} from '@fuzdev/fuz_util/path.js';
 
 // Character codes for performance
 export const BACKTICK = 96; // `
@@ -187,7 +188,7 @@ export const trim_trailing_punctuation = (url: string): string => {
 /**
  * Check if position in text is the start of an absolute path (starts with `/`).
  * Must be preceded by whitespace or be at the start of the string.
- * Rejects `//` (comments/protocol-relative) and `/ ` (bare slash).
+ * Rejects `//` (comments/protocol-relative) and slash followed by whitespace.
  */
 export const is_at_absolute_path = (text: string, index: number): boolean => {
 	if (text.charCodeAt(index) !== SLASH) return false;
@@ -197,13 +198,13 @@ export const is_at_absolute_path = (text: string, index: number): boolean => {
 	}
 	if (index + 1 >= text.length) return false;
 	const next_char = text.charCodeAt(index + 1);
-	return next_char !== SLASH && next_char !== SPACE && next_char !== NEWLINE;
+	return next_char !== SLASH && next_char !== SPACE && next_char !== NEWLINE && next_char !== TAB;
 };
 
 /**
  * Check if position in text is the start of a relative path (`./` or `../`).
  * Must be preceded by whitespace or be at the start of the string.
- * Requires at least one path character after the prefix.
+ * Rejects prefix followed by whitespace, slash, or end of string.
  */
 export const is_at_relative_path = (text: string, index: number): boolean => {
 	if (text.charCodeAt(index) !== PERIOD) return false;
@@ -219,16 +220,70 @@ export const is_at_relative_path = (text: string, index: number): boolean => {
 		text.charCodeAt(index + 2) === SLASH
 	) {
 		const after = text.charCodeAt(index + 3);
-		return after !== SPACE && after !== NEWLINE && after !== SLASH;
+		return after !== SPACE && after !== NEWLINE && after !== TAB && after !== SLASH;
 	}
 	// Check for ./ (at least 3 chars: ./x)
 	if (remaining >= 3 && text.charCodeAt(index + 1) === SLASH) {
 		const after = text.charCodeAt(index + 2);
-		return after !== SPACE && after !== NEWLINE && after !== SLASH;
+		return after !== SPACE && after !== NEWLINE && after !== TAB && after !== SLASH;
 	}
 	return false;
 };
 
+/**
+ * Extracts plain text content from an array of mdz nodes, recursing into children.
+ */
+export const mdz_text_content = (nodes: Array<MdzNode>): string =>
+	nodes
+		.map((n) => ('children' in n ? mdz_text_content(n.children) : 'content' in n ? n.content : ''))
+		.join('');
+
+/**
+ * Generates a lowercase slug id for a heading from its child nodes.
+ * Follows standard markdown conventions (GitHub, etc.) where heading IDs are lowercased.
+ * For case-preserving IDs (e.g. API declarations), see `docs_slugify` in `docs_helpers.svelte.ts`.
+ */
+export const mdz_heading_id = (nodes: Array<MdzNode>): string =>
+	slugify(mdz_text_content(nodes), false);
+
+/**
+ * Check if a string is a URL (`https://` or `http://`).
+ * Requires at least one valid character after the protocol.
+ * Rejects whitespace and characters that can't start a valid hostname.
+ */
+const URL_PATTERN = /^https?:\/\/[^\s)\]}<>.,:/?#!]/;
+export const mdz_is_url = (s: string): boolean => URL_PATTERN.test(s);
+
+/**
+ * Resolves a relative path (`./` or `../`) against a base path.
+ * The base is treated as a directory regardless of trailing slash
+ * (`'/docs/mdz'` and `'/docs/mdz/'` 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.
+ *
+ * @param reference - a relative path starting with `./` or `../`.
+ * @param base - an absolute base path (e.g., `'/docs/mdz/'`). Empty string is treated as root.
+ * @returns An absolute resolved path (e.g., `'/docs/mdz/grammar'`).
+ */
+export const resolve_relative_path = (reference: string, base: string): string => {
+	const segments = base.split('/');
+	// Remove trailing empty from split (e.g., '/docs/mdz/' → ['', 'docs', 'mdz', ''])
+	// but keep the root segment ([''] from '' base or ['', ''] from '/').
+	if (segments.length > 1 && segments.at(-1) === '') segments.pop();
+	const trailing = reference.endsWith('/');
+	for (const segment of reference.split('/')) {
+		if (segment === '.' || segment === '') continue;
+		if (segment === '..') {
+			if (segments.length > 1) segments.pop(); // clamp at root
+		} else {
+			segments.push(segment);
+		}
+	}
+	if (trailing) segments.push('');
+	return segments.join('/');
+};
+
 export const extract_single_tag = (
 	nodes: Array<MdzNode>,
 ): MdzComponentNode | MdzElementNode | null => {