@fuzdev/fuz_ui 0.190.0 → 0.191.0

package/src/lib/mdz_lexer.ts

@@ -7,8 +7,8 @@
  * @module
  */
 
-import {mdz_is_url} from './mdz.js';
 import {
+	mdz_is_url,
 	is_letter,
 	is_tag_name_char,
 	is_word_char,
@@ -276,14 +276,17 @@ export class MdzLexer {
 			end: this.#index, // end of "## " prefix
 		});
 
+		// Find end-of-line to bound nested tokenizers (prevents tag scanner from scanning past heading)
+		let eol = this.#text.indexOf('\n', this.#index);
+		if (eol === -1) eol = this.#text.length;
+
+		const saved_max = this.#max_search_index;
+		this.#max_search_index = eol;
+
 		// Tokenize inline content until newline or EOF
 		// tokenize_text may consume a newline as part of block-element lookahead,
 		// so we check emitted text tokens for embedded newlines and trim.
-		while (this.#index < this.#text.length) {
-			if (this.#text.charCodeAt(this.#index) === NEWLINE) {
-				break;
-			}
-
+		while (this.#index < eol) {
 			const token_count_before = this.#tokens.length;
 			this.#tokenize_inline();
 
@@ -307,6 +310,8 @@ export class MdzLexer {
 			}
 		}
 
+		this.#max_search_index = saved_max;
+
 		// Emit heading_end marker so the token parser knows where heading content stops
 		this.#tokens.push({type: 'heading_end', start: this.#index, end: this.#index});
 
@@ -798,11 +803,17 @@ export class MdzLexer {
 		}
 		this.#index++; // consume >
 
-		// Check for closing tag existence before committing
+		// Check for closing tag existence before committing —
+		// must exist within search boundary and before any paragraph break
 		const closing_tag = `</${tag_name}>`;
+		const search_limit = Math.min(this.#max_search_index, this.#text.length);
 		const closing_tag_pos = this.#text.indexOf(closing_tag, this.#index);
-		if (closing_tag_pos === -1) {
-			// No closing tag - revert
+		if (closing_tag_pos === -1 || closing_tag_pos >= search_limit) {
+			this.#index = start + 1;
+			this.#emit_text('<', start);
+			return;
+		}
+		if (this.#has_paragraph_break_between(this.#index, closing_tag_pos)) {
 			this.#index = start + 1;
 			this.#emit_text('<', start);
 			return;

package/src/lib/mdz_to_svelte.ts

@@ -12,7 +12,8 @@ import {UnreachableError} from '@fuzdev/fuz_util/error.js';
 import {escape_svelte_text} from '@fuzdev/fuz_util/svelte_preprocess_helpers.js';
 import {escape_js_string} from '@fuzdev/fuz_util/string.js';
 
-import {type MdzNode, resolve_relative_path} from './mdz.js';
+import type {MdzNode} from './mdz.js';
+import {resolve_relative_path} from './mdz_helpers.js';
 
 /**
  * Result of converting `MdzNode` arrays to Svelte markup.
@@ -34,12 +35,12 @@ export interface MdzToSvelteResult {
  * Each node type produces output matching what `MdzNodeView.svelte` renders at runtime.
  * Collects required imports and flags unconfigured component/element references.
  *
- * @param nodes Parsed mdz nodes to render.
- * @param components Component name to import path mapping (e.g., `{Alert: '$lib/Alert.svelte'}`).
+ * @param nodes - parsed mdz nodes to render.
+ * @param components - component name to import path mapping (e.g., `{Alert: '$lib/Alert.svelte'}`).
  *   If content references a component not in this map, `has_unconfigured_tags` is set.
- * @param elements Allowed HTML element names (e.g., `new Set(['aside', 'details'])`).
+ * @param elements - allowed HTML element names (e.g., `new Set(['aside', 'details'])`).
  *   If content references an element not in this set, `has_unconfigured_tags` is set.
- * @param base Base path for resolving relative links (e.g., `'/docs/mdz/'`).
+ * @param base - base path for resolving relative links (e.g., `'/docs/mdz/'`).
  *   When provided, relative references (`./`, `../`) are resolved to absolute paths
  *   and passed through `resolve()`. Trailing slash recommended.
  */

package/src/lib/mdz_token_parser.ts

@@ -18,7 +18,7 @@ import type {
 	MdzElementNode,
 	MdzComponentNode,
 } from './mdz.js';
-import {extract_single_tag} from './mdz_helpers.js';
+import {extract_single_tag, mdz_heading_id} from './mdz_helpers.js';
 import {
 	MdzLexer,
 	type MdzToken,
@@ -124,9 +124,10 @@ class MdzTokenParser {
 			if (node) children.push(node);
 		}
 
-		const end = children.length > 0 ? children[children.length - 1]!.end : start + level + 1;
+		const merged = this.#merge_adjacent_text(children);
+		const end = merged.length > 0 ? merged[merged.length - 1]!.end : start + level + 1;
 
-		return {type: 'Heading', level, children, start, end};
+		return {type: 'Heading', level, id: mdz_heading_id(merged), children: merged, start, end};
 	}
 
 	#parse_inline(): MdzNode | null {

package/src/lib/module_helpers.ts

@@ -174,8 +174,8 @@ export const MODULE_SOURCE_PARTIAL: ModuleSourcePartial = {
 /**
  * Create complete source options from project root and optional overrides.
  *
- * @param project_root Absolute path to project root (typically `process.cwd()`)
- * @param overrides Optional overrides for default options
+ * @param project_root - absolute path to project root (typically `process.cwd()`)
+ * @param overrides - optional overrides for default options
  *
  * @example
  * ```ts
@@ -348,8 +348,8 @@ export const module_get_source_root = (options: ModuleSourceOptions): string =>
  *
  * Uses proper path semantics: strips `project_root/source_root/` prefix.
  *
- * @param source_id Absolute path to the source file
- * @param options Module source options for path extraction
+ * @param source_id - absolute path to the source file
+ * @param options - module source options for path extraction
  *
  * @example
  * ```ts
@@ -430,8 +430,8 @@ export const module_is_test = (path: string): boolean => path.endsWith('.test.ts
  * `project_root/source_path/`. No heuristics needed - nested directories
  * are correctly excluded by the prefix check.
  *
- * @param path Full absolute path to check
- * @param options Module source options for filtering
+ * @param path - full absolute path to check
+ * @param options - module source options for filtering
  * @returns True if the path is an analyzable source file
  *
  * @example
@@ -465,8 +465,8 @@ export const module_is_source = (path: string, options: ModuleSourceOptions): bo
  * Filters to only include source modules (excludes external packages, node_modules, tests).
  * Returns sorted arrays of module paths (relative to source_root) for deterministic output.
  *
- * @param source_file The source file info to extract dependencies from
- * @param options Module source options for filtering and path extraction
+ * @param source_file - the source file info to extract dependencies from
+ * @param options - module source options for filtering and path extraction
  */
 export const module_extract_dependencies = (
 	source_file: SourceFileInfo,

package/src/lib/package_helpers.ts

@@ -27,9 +27,9 @@ import type {PackageJson} from '@fuzdev/fuz_util/package_json.js';
 /**
  * Build GitHub file URL for a repository.
  *
- * @param repo_url Repository URL (e.g., 'https://github.com/owner/repo')
- * @param file_path Path to the file (leading './' is stripped)
- * @param line Optional line number for deep linking
+ * @param repo_url - repository URL (e.g., 'https://github.com/owner/repo')
+ * @param file_path - path to the file (leading './' is stripped)
+ * @param line - optional line number for deep linking
  * @returns Full GitHub URL to the file on the main branch
  *
  * @example
@@ -53,8 +53,8 @@ export const url_github_file = (repo_url: string, file_path: string, line?: numb
 /**
  * Build GitHub organization URL from repo URL and repo name.
  *
- * @param repo_url Repository URL (e.g., 'https://github.com/owner/repo')
- * @param repo_name Repository name to strip from the URL
+ * @param repo_url - repository URL (e.g., 'https://github.com/owner/repo')
+ * @param repo_name - repository name to strip from the URL
  * @returns Organization URL, or null if repo_url doesn't end with repo_name
  *
  * @example
@@ -70,7 +70,7 @@ export const url_github_org = (repo_url: string, repo_name: string): string | nu
 /**
  * Extract GitHub owner/org name from repository URL.
  *
- * @param repo_url Repository URL (e.g., 'https://github.com/owner/repo')
+ * @param repo_url - repository URL (e.g., 'https://github.com/owner/repo')
  * @returns Owner name, or null if not a valid GitHub URL
  *
  * @example
@@ -95,7 +95,7 @@ export const repo_url_github_owner = (repo_url: string): string | null => {
 /**
  * Build npm package URL.
  *
- * @param package_name Package name (can be scoped like '@org/package')
+ * @param package_name - package name (can be scoped like '@org/package')
  * @returns Full npm package page URL
  *
  * @example
@@ -115,7 +115,7 @@ export const url_npm_package = (package_name: string): string =>
  * - It has exports defined
  * - Its version is not the initial '0.0.1'
  *
- * @param package_json The package.json object to check
+ * @param package_json - the package.json object to check
  * @returns True if the package appears to be published
  */
 export const package_is_published = (package_json: PackageJson): boolean => {
@@ -125,7 +125,7 @@ export const package_is_published = (package_json: PackageJson): boolean => {
 /**
  * Extract repository name without scope from package name.
  *
- * @param name Package name (can be scoped like '@org/package')
+ * @param name - package name (can be scoped like '@org/package')
  * @returns Repository name without scope
  * @throws Error if scoped package name is malformed
  *
@@ -158,7 +158,7 @@ export const repo_name_parse = (name: string): string => {
  * Handles both string format and object format with `url` property.
  * Strips common prefixes ('git+') and suffixes ('.git', '/').
  *
- * @param repository The repository field from package.json
+ * @param repository - the repository field from package.json
  * @returns Clean repository URL, or null if not provided
  *
  * @example
@@ -189,8 +189,8 @@ export const repo_url_parse = (repository: PackageJson['repository']): string |
 /**
  * Build .well-known URL for package metadata files.
  *
- * @param homepage_url Package homepage URL
- * @param filename Filename in .well-known directory
+ * @param homepage_url - package homepage URL
+ * @param filename - filename in .well-known directory
  * @returns Full URL to the .well-known file
  *
  * @example

package/src/lib/storage.ts

@@ -18,9 +18,9 @@ export const save_to_storage = (key: string, value: any, is_json = false): void
 
 /**
  * Utility function to load a value from `localStorage` with optional parsing
- * @param key The localStorage key
- * @param is_json Whether to parse the value as JSON
- * @param parse_fn Optional custom parsing function to transform the value
+ * @param key - the localStorage key
+ * @param is_json - whether to parse the value as JSON
+ * @param parse_fn - optional custom parsing function to transform the value
  * @returns The parsed value or null if not found or parsing fails
  */
 export const load_from_storage = <T>(

package/src/lib/svelte_helpers.ts

@@ -76,11 +76,11 @@ export interface SvelteFileAnalysis {
  * Returns raw analysis data matching `ModuleAnalysis` structure.
  * Consumer decides filtering policy (Svelte components are never nodocs).
  *
- * @param source_file The source file info (from Gro filer, file system, or other source)
- * @param module_path The module path (relative to source root)
- * @param checker TypeScript type checker
- * @param options Module source options for path extraction
- * @param ctx Analysis context for collecting diagnostics
+ * @param source_file - the source file info (from Gro filer, file system, or other source)
+ * @param module_path - the module path (relative to source root)
+ * @param checker - TypeScript type checker
+ * @param options - module source options for path extraction
+ * @param ctx - analysis context for collecting diagnostics
  * @returns Module analysis matching ModuleAnalysis structure
  */
 export const svelte_analyze_module = (
@@ -118,10 +118,10 @@ export const svelte_analyze_module = (
  *
  * Suitable for use in documentation generators, build tools, and analysis.
  *
- * @param source_file Source file info with path and content
- * @param module_path Module path relative to source root (e.g., 'Alert.svelte')
- * @param checker TypeScript type checker for type resolution
- * @param ctx Analysis context for collecting diagnostics
+ * @param source_file - source file info with path and content
+ * @param module_path - module path relative to source root (e.g., 'Alert.svelte')
+ * @param checker - TypeScript type checker for type resolution
+ * @param ctx - analysis context for collecting diagnostics
  * @returns Component declaration and optional module-level comment
  */
 export const svelte_analyze_file = (

package/src/lib/svelte_preprocess_mdz.ts

@@ -98,7 +98,7 @@ const PRECOMPILED_NAME = 'MdzPrecompiled';
 /**
  * Creates a Svelte preprocessor that compiles static `Mdz` content at build time.
  *
- * @param options Configuration for component/element resolution and file filtering.
+ * @param options - configuration for component/element resolution and file filtering
  * @returns A Svelte `PreprocessorGroup` for use in `svelte.config.js`.
  */
 export const svelte_preprocess_mdz = (

package/src/lib/ts_helpers.ts

@@ -63,8 +63,8 @@ export interface ModuleExportsAnalysis {
 /**
  * Create TypeScript program for analysis.
  *
- * @param options Configuration options for program creation
- * @param log Optional logger for info messages
+ * @param options - configuration options for program creation
+ * @param log - optional logger for info messages
  * @returns The program and type checker
  * @throws Error if tsconfig.json is not found
  */
@@ -100,12 +100,12 @@ export const ts_create_program = (options?: TsProgramOptions, log?: Logger): TsP
  * This is a high-level function suitable for building documentation or library metadata.
  * For lower-level analysis, use `ts_analyze_module_exports` directly.
  *
- * @param source_file_info The source file info (from Gro filer, file system, or other source)
- * @param ts_source_file TypeScript source file from the program
- * @param module_path The module path (relative to source root)
- * @param checker TypeScript type checker
- * @param options Module source options for path extraction
- * @param ctx Analysis context for collecting diagnostics
+ * @param source_file_info - the source file info (from Gro filer, file system, or other source)
+ * @param ts_source_file - TypeScript source file from the program
+ * @param module_path - the module path (relative to source root)
+ * @param checker - TypeScript type checker
+ * @param options - module source options for path extraction
+ * @param ctx - analysis context for collecting diagnostics
  * @returns Module metadata and re-export information
  */
 export const ts_analyze_module = (
@@ -151,10 +151,10 @@ export const ts_analyze_module = (
  * suitable for building documentation, API explorers, or analysis tools.
  * For standard SvelteKit library layouts, use `module_create_source_options(process.cwd())`.
  *
- * @param source_file The TypeScript source file to analyze
- * @param checker The TypeScript type checker
- * @param options Module source options for path extraction in re-exports
- * @param ctx Analysis context for collecting diagnostics
+ * @param source_file - the TypeScript source file to analyze
+ * @param checker - the TypeScript type checker
+ * @param options - module source options for path extraction in re-exports
+ * @param ctx - analysis context for collecting diagnostics
  * @returns Module comment, declarations, re-exports, and star exports
  */
 export const ts_analyze_module_exports = (
@@ -275,10 +275,10 @@ export const ts_analyze_module_exports = (
  * type analysis to produce complete declaration metadata. Suitable for use
  * in documentation generators, IDE integrations, and other tooling.
  *
- * @param symbol The TypeScript symbol to analyze
- * @param source_file The source file containing the symbol
- * @param checker The TypeScript type checker
- * @param ctx Optional analysis context for collecting diagnostics
+ * @param symbol - the TypeScript symbol to analyze
+ * @param source_file - the source file containing the symbol
+ * @param checker - the TypeScript type checker
+ * @param ctx - optional analysis context for collecting diagnostics
  * @returns Complete declaration metadata including docs, types, and parameters, plus nodocs flag
  */
 export const ts_analyze_declaration = (
@@ -431,9 +431,9 @@ export const ts_infer_declaration_kind = (symbol: ts.Symbol, node: ts.Node): Dec
  * Shared helper for extracting parameter information from both standalone functions
  * and class methods/constructors.
  *
- * @param sig The TypeScript signature to extract parameters from
- * @param checker TypeScript type checker for type resolution
- * @param tsdoc_params Map of parameter names to TSDoc descriptions (from tsdoc.params)
+ * @param sig - the TypeScript signature to extract parameters from
+ * @param checker - TypeScript type checker for type resolution
+ * @param tsdoc_params - map of parameter names to TSDoc descriptions (from tsdoc.params)
  * @returns Array of parameter info objects
  */
 export const ts_extract_signature_parameters = (

package/src/lib/tsdoc_helpers.ts

@@ -83,8 +83,8 @@ export interface TsdocParsedComment {
  * - `@since` - version information
  * - `@mutates` - mutation documentation (non-standard)
  *
- * @param node The TypeScript node to extract JSDoc from
- * @param source_file Source file (used for extracting full` @see` tag text)
+ * @param node - the TypeScript node to extract JSDoc from
+ * @param source_file - source file (used for extracting full ` @see` tag text)
  */
 export const tsdoc_parse = (
 	node: ts.Node,
@@ -186,8 +186,8 @@ export const tsdoc_parse = (
  * Consolidates the common pattern of assigning TSDoc fields to declarations,
  * with conditional assignment for array fields (only if non-empty).
  *
- * @param declaration declaration object to update
- * @param tsdoc parsed TSDoc comment (if available)
+ * @param declaration - declaration object to update
+ * @param tsdoc - parsed TSDoc comment (if available)
  * @mutates declaration - adds doc_comment, deprecated_message, examples, see_also, throws, since fields
  */
 export const tsdoc_apply_to_declaration = (
@@ -219,7 +219,7 @@ export const tsdoc_apply_to_declaration = (
  *
  * Transforms `/** ... *\/` style comments into clean text.
  *
- * @param comment_text The raw comment text including `/**` and `*\/` markers
+ * @param comment_text - the raw comment text including `/**` and `*\/` markers
  * @returns Cleaned comment text, or undefined if empty after cleaning
  */
 export const tsdoc_clean_comment = (comment_text: string): string | undefined => {

package/src/lib/tsdoc_mdz.ts

@@ -8,7 +8,7 @@
  * @module
  */
 
-import {mdz_is_url} from './mdz.js';
+import {mdz_is_url} from './mdz_helpers.js';
 
 /** Format a reference as mdz: URLs pass through, identifiers get backticks. */
 const format_reference = (ref: string): string => (mdz_is_url(ref) ? ref : `\`${ref}\``);