@fuzdev/fuz_ui 0.191.0 → 0.191.2

package/src/lib/library_generate.ts

@@ -12,9 +12,9 @@
  * - Dependency graphs
  * - Svelte component props
  *
- * For Gro integration, see `library_gen.ts` which wraps this with Gro's Gen interface.
+ * For Gro integration, see `library_gen.ts` which wraps this with Gro's `Gen` interface.
  *
- * @see @fuzdev/fuz_util/source_json.js for type definitions
+ * @see `@fuzdev/fuz_util/source_json.js` for type definitions
  * @see `library_analysis.ts` for the unified analysis entry point
  * @see `library_pipeline.ts` for pipeline helpers
  * @see `library_output.ts` for JSON/TS file generation

package/src/lib/library_helpers.ts

@@ -28,7 +28,7 @@ export const url_api_declaration = (declaration_name: string): string =>
  *
  * @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'
+ * @returns full URL like 'https://example.com/docs/api#declaration_name'
  */
 export const url_api_declaration_full = (homepage: string, declaration_name: string): string =>
 	`${homepage}${DOCS_PATH_DEFAULT}/api#${encodeURIComponent(declaration_name)}`;
@@ -46,7 +46,7 @@ export const url_api_module = (module_path: string): string => `${DOCS_API_PATH}
  *
  * @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
+ * @returns full URL to the logo, or null if no homepage
  */
 export const url_package_logo = (
 	homepage_url: string | null,
@@ -64,12 +64,14 @@ export const url_package_logo = (
  *
  * @param url - full URL to convert
  * @param origin - origin to strip (defaults to current page origin)
- * @returns Root-relative URL starting with '/'
+ * @returns root-relative URL starting with '/'
  *
  * @example
+ * ```ts
  * // Assuming page.url.origin is 'https://example.com'
  * url_to_root_relative('https://example.com/docs/api')
  * // => '/docs/api'
+ * ```
  */
 export const url_to_root_relative = (url: string, origin: string = page.url.origin): string => {
 	const origin_with_slash = ensure_end(origin, '/');

package/src/lib/library_output.ts

@@ -1,11 +1,11 @@
 /**
  * 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.
  *
- * @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_generate.ts` for the main generation entry point
+ * @see `library_pipeline.ts` for pipeline orchestration functions
+ * @see `library_gen.ts` for Gro-specific integration
  *
  * @module
  */
@@ -19,14 +19,14 @@ import {library_json_parse, type LibraryJson} from '@fuzdev/fuz_util/library_jso
  * Contains both the JSON data and the TypeScript wrapper file.
  */
 export interface LibraryOutputResult {
-	/** JSON content for library.json */
+	/** JSON content for `library.json`. */
 	json_content: string;
-	/** TypeScript wrapper content for library.ts */
+	/** TypeScript wrapper content for `library.ts`. */
 	ts_content: string;
 }
 
 /**
- * Generate the library.json and library.ts file contents.
+ * Generate the `library.json` and `library.ts` file contents.
  * Parses at generation time so runtime only needs the pre-computed result.
  *
  * Returns JSON + .ts wrapper because:

package/src/lib/library_pipeline.ts

@@ -6,15 +6,15 @@
  *
  * Pipeline stages:
  * 1. **Collection** - `library_collect_source_files` gathers and filters source files
- * 2. **Analysis** - `library_analyze_module` (in library_analysis.ts) extracts metadata
+ * 2. **Analysis** - `library_analyze_module` (in `library_analysis.ts`) extracts metadata
  * 3. **Validation** - `library_find_duplicates` checks flat namespace constraints
  * 4. **Transformation** - `library_merge_re_exports` resolves re-export relationships
  * 5. **Output** - `library_sort_modules` prepares deterministic output
  *
- * @see library_generate.ts for the main generation entry point
- * @see library_analysis.ts for module-level analysis
- * @see library_output.ts for output file generation (JSON/TS wrapper)
- * @see library_gen.ts for Gro-specific integration
+ * @see `library_generate.ts` for the main generation entry point
+ * @see `library_analysis.ts` for module-level analysis
+ * @see `library_output.ts` for output file generation (JSON/TS wrapper)
+ * @see `library_gen.ts` for Gro-specific integration
  *
  * @module
  */
@@ -48,6 +48,7 @@ export interface DuplicateInfo {
  * Callers can decide how to handle duplicates (throw, warn, ignore).
  *
  * @example
+ * ```ts
  * const duplicates = library_find_duplicates(source_json);
  * if (duplicates.size > 0) {
  *   for (const [name, occurrences] of duplicates) {
@@ -58,6 +59,7 @@ export interface DuplicateInfo {
  *   }
  *   throw new Error(`Found ${duplicates.size} duplicate declaration names`);
  * }
+ * ```
  */
 export const library_find_duplicates = (
 	source_json: SourceJson,
@@ -123,12 +125,14 @@ export interface CollectedReExport {
  * after all modules are analyzed.
  *
  * @example
+ * ```ts
  * // helpers.ts exports: foo, bar
  * // index.ts does: export {foo, bar} from './helpers.js'
  * //
  * // After processing:
  * // - 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

package/src/lib/logos.ts

@@ -63,9 +63,9 @@ export const logo_fuz = {
 	],
 } satisfies SvgData;
 
-export const logo_fuz_ui = {
-	label: 'a friendly red spider facing you',
-	fill: '#d93636',
+export const logo_fuz_app = {
+	label: 'a friendly teal spider facing you',
+	fill: '#2e9e6f',
 	paths: logo_fuz.paths,
 } satisfies SvgData;
 
@@ -76,6 +76,12 @@ export const logo_fuz_css = {
 	attrs: {style: 'transform: scaleX(-1) rotate(180deg)'},
 } satisfies SvgData;
 
+export const logo_fuz_ui = {
+	label: 'a friendly red spider facing you',
+	fill: '#d93636',
+	paths: logo_fuz.paths,
+} satisfies SvgData;
+
 export const logo_fuz_code = {
 	label: 'a friendly pink spider facing you',
 	fill: '#e55d95',
@@ -100,6 +106,12 @@ export const logo_fuz_gitops = {
 	paths: logo_fuz.paths,
 } satisfies SvgData;
 
+export const logo_fuz_docs = {
+	label: 'a friendly cyan spider facing you',
+	fill: '#1ec3d2',
+	paths: logo_fuz.paths,
+} satisfies SvgData;
+
 export const logo_fuz_template = {
 	label: 'a friendly orange pixelated spider facing you',
 	fill: '#f4672f',

package/src/lib/mdz.ts

@@ -493,9 +493,9 @@ export class MdzParser {
 	 * - Empty content (e.g., `__` or `~~`)
 	 * - Paragraph break interrupts before closing delimiter
 	 *
-	 * @param delimiter - The delimiter character (`_` for italic, `~` for strikethrough)
-	 * @param node_type - The node type to create ('Italic' or 'Strikethrough')
-	 * @returns Formatted node or text node if validation fails
+	 * @param delimiter - the delimiter character (`_` for italic, `~` for strikethrough)
+	 * @param node_type - the node type to create ('Italic' or 'Strikethrough')
+	 * @returns formatted node or text node if validation fails
 	 */
 	#parse_single_delimiter_formatting(
 		delimiter: '_',
@@ -863,7 +863,7 @@ export class MdzParser {
 	/**
 	 * Restore previously saved text accumulation state.
 	 * Used to restore parent state when exiting nested structure parsing.
-	 * @param state - State object returned from `#save_accumulation_state()`
+	 * @param state - state object returned from `#save_accumulation_state()`
 	 */
 	#restore_accumulation_state(state: {
 		accumulated_text: string;
@@ -881,9 +881,9 @@ export class MdzParser {
 	 * Word boundary = not surrounded by word characters (A-Z, a-z, 0-9).
 	 * Used to prevent intraword emphasis for underscores and tildes.
 	 *
-	 * @param index - Position to check
-	 * @param check_before - Whether to check the character before this position
-	 * @param check_after - Whether to check the character after this position
+	 * @param index - position to check
+	 * @param check_before - whether to check the character before this position
+	 * @param check_after - whether to check the character after this position
 	 */
 	#is_at_word_boundary(index: number, check_before: boolean, check_after: boolean): boolean {
 		if (check_before && index > 0) {
@@ -1106,9 +1106,9 @@ export class MdzParser {
 	 * - Paragraph break (double newline) is encountered (allows block elements to interrupt inline formatting)
 	 * - `end_index` boundary is reached
 	 *
-	 * @param delimiter - The delimiter string to stop at (e.g., '**', '_', ']')
-	 * @param end_index - Optional maximum index to parse up to (for greedy/bounded parsing)
-	 * @returns Array of parsed nodes (may be empty if delimiter found immediately)
+	 * @param delimiter - the delimiter string to stop at (e.g., '**', '_', ']')
+	 * @param end_index - optional maximum index to parse up to (for greedy/bounded parsing)
+	 * @returns array of parsed nodes (may be empty if delimiter found immediately)
 	 */
 	#parse_nodes_until(delimiter: string, end_index?: number): Array<MdzNode> {
 		const nodes: Array<MdzNode> = [];

package/src/lib/mdz_helpers.ts

@@ -262,9 +262,9 @@ export const mdz_is_url = (s: string): boolean => URL_PATTERN.test(s);
  * (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'`).
+ * @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('/');

package/src/lib/mdz_to_svelte.ts

@@ -35,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/module.svelte.ts

@@ -24,7 +24,7 @@ export class Module {
 	module_comment = $derived(this.module_json.module_comment);
 
 	/**
-	 * Array of Declaration instances. Filters out default exports.
+	 * Array of `Declaration` instances. Filters out default exports.
 	 */
 	declarations = $derived(
 		this.module_json.declarations

package/src/lib/module_helpers.ts

@@ -20,7 +20,7 @@ export type AnalyzerType = 'typescript' | 'svelte';
 /**
  * File information for source analysis.
  *
- * Can be constructed from Gro's Disknode or from plain file system access.
+ * Can be constructed from Gro's `Disknode` or from plain file system access.
  * This abstraction enables non-Gro usage while keeping Gro support via adapter.
  *
  * Note: `content` is required to keep analysis functions pure (no hidden I/O).
@@ -328,7 +328,7 @@ export const module_validate_source_options = (options: ModuleSourceOptions): vo
  *
  * Returns `source_root` if provided, otherwise returns `source_paths[0]` for single-path configs.
  *
- * @throws Error if source_root is required but not provided (multiple source_paths)
+ * @throws Error if `source_root` is required but not provided (multiple `source_paths`)
  */
 export const module_get_source_root = (options: ModuleSourceOptions): string => {
 	if (options.source_root !== undefined) {
@@ -432,7 +432,7 @@ export const module_is_test = (path: string): boolean => path.endsWith('.test.ts
  *
  * @param path - full absolute path to check
  * @param options - module source options for filtering
- * @returns True if the path is an analyzable source file
+ * @returns true if the path is an analyzable source file
  *
  * @example
  * ```ts

package/src/lib/package_helpers.ts

@@ -11,7 +11,7 @@
  * - `url_well_known` - .well-known metadata file
  *
  * Parsers:
- * - `repo_url_parse` - extract repo URL from package.json repository field
+ * - `repo_url_parse` - extract repo URL from `package.json` repository field
  * - `repo_name_parse` - extract repo name from scoped package name
  * - `repo_url_github_owner` - extract GitHub owner from repo URL
  *
@@ -30,7 +30,7 @@ import type {PackageJson} from '@fuzdev/fuz_util/package_json.js';
  * @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
+ * @returns full GitHub URL to the file on the main branch
  *
  * @example
  * ```ts
@@ -55,7 +55,7 @@ export const url_github_file = (repo_url: string, file_path: string, line?: numb
  *
  * @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
+ * @returns organization URL, or null if repo_url doesn't end with repo_name
  *
  * @example
  * ```ts
@@ -71,7 +71,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')
- * @returns Owner name, or null if not a valid GitHub URL
+ * @returns owner name, or null if not a valid GitHub URL
  *
  * @example
  * ```ts
@@ -96,7 +96,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')
- * @returns Full npm package page URL
+ * @returns full npm package page URL
  *
  * @example
  * ```ts
@@ -115,8 +115,8 @@ 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
- * @returns True if the package appears to be published
+ * @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 => {
 	return !package_json.private && !!package_json.exports && package_json.version !== '0.0.1';
@@ -126,7 +126,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')
- * @returns Repository name without scope
+ * @returns repository name without scope
  * @throws Error if scoped package name is malformed
  *
  * @example
@@ -153,13 +153,13 @@ export const repo_name_parse = (name: string): string => {
 };
 
 /**
- * Parse repository URL from package.json format.
+ * Parse repository URL from `package.json` format.
  *
  * 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
- * @returns Clean repository URL, or null if not provided
+ * @param repository - the repository field from `package.json`
+ * @returns clean repository URL, or null if not provided
  *
  * @example
  * ```ts
@@ -191,7 +191,7 @@ export const repo_url_parse = (repository: PackageJson['repository']): string |
  *
  * @param homepage_url - package homepage URL
  * @param filename - filename in .well-known directory
- * @returns Full URL to the .well-known file
+ * @returns full URL to the .well-known file
  *
  * @example
  * ```ts

package/src/lib/storage.ts

@@ -21,7 +21,7 @@ export const save_to_storage = (key: string, value: any, is_json = false): void
  * @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
+ * @returns the parsed value or null if not found or parsing fails
  */
 export const load_from_storage = <T>(
 	key: string,

package/src/lib/svelte_helpers.ts

@@ -81,7 +81,7 @@ export interface SvelteFileAnalysis {
  * @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
+ * @returns module analysis matching `ModuleAnalysis` structure
  */
 export const svelte_analyze_module = (
 	source_file: SourceFileInfo,
@@ -122,7 +122,7 @@ export const svelte_analyze_module = (
  * @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
+ * @returns component declaration and optional module-level comment
  */
 export const svelte_analyze_file = (
 	source_file: SourceFileInfo,
@@ -259,8 +259,8 @@ export const svelte_extract_script_content = (svelte_source: string): string | u
  * Requires `@module` tag to identify module comments. The tag line is stripped
  * from the output.
  *
- * @param script_content - The content of the `<script>` tag.
- * @returns The cleaned module comment text, or undefined if none found.
+ * @param script_content - the content of the `<script>` tag
+ * @returns the cleaned module comment text, or undefined if none found
  */
 export const svelte_extract_module_comment = (script_content: string): string | undefined => {
 	// Parse the script content as TypeScript and reuse the shared extraction logic

package/src/lib/svelte_preprocess_mdz.ts

@@ -59,20 +59,20 @@ export interface SveltePreprocessMdzOptions {
 	 * Value: import path (e.g., '$lib/Alert.svelte').
 	 *
 	 * If mdz content references a component not in this map,
-	 * that Mdz usage is skipped (left as runtime).
+	 * that `Mdz` usage is skipped (left as runtime).
 	 */
 	components?: Record<string, string>;
 
 	/**
 	 * Allowed HTML elements in mdz content.
 	 * If mdz content references an element not in this list,
-	 * that Mdz usage is skipped (left as runtime).
+	 * that `Mdz` usage is skipped (left as runtime).
 	 */
 	elements?: Array<string>;
 
 	/**
-	 * Import sources that resolve to the Mdz component.
-	 * Used to verify that `Mdz` in templates refers to fuz_ui's Mdz.svelte.
+	 * Import sources that resolve to the `Mdz` component.
+	 * Used to verify that `Mdz` in templates refers to fuz_ui's `Mdz.svelte`.
 	 *
 	 * @default ['@fuzdev/fuz_ui/Mdz.svelte']
 	 */
@@ -99,7 +99,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
- * @returns A Svelte `PreprocessorGroup` for use in `svelte.config.js`.
+ * @returns a Svelte `PreprocessorGroup` for use in `svelte.config.js`
  */
 export const svelte_preprocess_mdz = (
 	options: SveltePreprocessMdzOptions = {},
@@ -204,9 +204,9 @@ interface MdzTransformation {
 
 interface FindMdzUsagesResult {
 	transformations: Array<MdzTransformation>;
-	/** Total template usages per Mdz local name. */
+	/** Total template usages per `Mdz` local name. */
 	total_usages: Map<string, number>;
-	/** Successfully transformed usages per Mdz local name. */
+	/** Successfully transformed usages per `Mdz` local name. */
 	transformed_usages: Map<string, number>;
 }
 
@@ -487,7 +487,7 @@ const remove_dead_const_bindings = (
 };
 
 /**
- * Builds the replacement string for a transformed Mdz component.
+ * Builds the replacement string for a transformed `Mdz` component.
  *
  * Reconstructs the opening tag as `<MdzPrecompiled` with all attributes except `content`,
  * using source text slicing to preserve exact formatting and dynamic expressions.
@@ -515,24 +515,24 @@ const build_replacement = (
 	return `${opening}${children_markup}</${PRECOMPILED_NAME}>`;
 };
 
-/** Result of import removability analysis for a single Mdz name. */
+/** Result of import removability analysis for a single `Mdz` name. */
 interface ImportRemovalAction {
 	/** The import declaration node. */
 	node: PositionedImportDeclaration;
-	/** 'full' removes the entire declaration; 'partial' removes only the Mdz specifier. */
+	/** 'full' removes the entire declaration; 'partial' removes only the `Mdz` specifier. */
 	kind: 'full' | 'partial';
 	/** For partial removal: the specifier to remove. */
 	specifier_to_remove?: ImportDeclaration['specifiers'][number];
 }
 
 /**
- * Determines which Mdz import declarations can be safely removed or trimmed.
+ * Determines which `Mdz` import declarations can be safely removed or trimmed.
  *
  * An import is removable when:
  * 1. All template usages of that name were successfully transformed.
  * 2. The identifier is not referenced elsewhere in script or template expressions.
  *
- * For multi-specifier imports, only the Mdz specifier is removed (partial removal).
+ * For multi-specifier imports, only the `Mdz` specifier is removed (partial removal).
  * For single-specifier imports, the entire declaration is removed.
  */
 const find_removable_mdz_imports = (
@@ -587,13 +587,13 @@ const find_removable_mdz_imports = (
  * Manages import additions and removals.
  *
  * Adds the `MdzPrecompiled` import and other required imports (DocsLink, Code, resolve).
- * Removes Mdz import declarations that are no longer referenced.
+ * Removes `Mdz` import declarations that are no longer referenced.
  *
  * Handles both full removal (single-specifier imports) and partial removal
- * (multi-specifier imports where only the Mdz specifier is removed).
+ * (multi-specifier imports where only the `Mdz` specifier is removed).
  *
  * To avoid MagicString boundary conflicts when the insertion position falls inside
- * a removal range, one removable Mdz import is overwritten with the MdzPrecompiled
+ * a removal range, one removable `Mdz` import is overwritten with the `MdzPrecompiled`
  * import line instead of using separate remove + appendLeft.
  */
 const manage_imports = (

package/src/lib/tome.ts

@@ -18,7 +18,7 @@ export const Tome = z.object({
 export type Tome = z.infer<typeof Tome>;
 
 /**
- * @param hash - URL fragment to append, with or without the `#`.
+ * @param hash - URL fragment to append, with or without the `#`
  */
 export const to_tome_pathname = (
 	item: Tome | string,

package/src/lib/ts_helpers.ts

@@ -32,7 +32,7 @@ import type {DeclarationAnalysis, ReExportInfo, ModuleAnalysis} from './library_
 export interface TsProgramOptions {
 	/** Project root directory. @default './' */
 	root?: string;
-	/** Path to tsconfig.json (relative to root). @default 'tsconfig.json' */
+	/** Path to `tsconfig.json` (relative to root). @default 'tsconfig.json' */
 	tsconfig?: string;
 	/** Override compiler options. */
 	compiler_options?: ts.CompilerOptions;
@@ -54,7 +54,7 @@ export interface ModuleExportsAnalysis {
 	module_comment?: string;
 	/** All exported declarations with nodocs flags - consumer filters based on policy. */
 	declarations: Array<DeclarationAnalysis>;
-	/** Same-name re-exports (for building also_exported_from in post-processing). */
+	/** Same-name re-exports (for building `also_exported_from` in post-processing). */
 	re_exports: Array<ReExportInfo>;
 	/** Star exports (`export * from './module'`) - module paths that are fully re-exported. */
 	star_exports: Array<string>;
@@ -65,8 +65,8 @@ export interface ModuleExportsAnalysis {
  *
  * @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
+ * @returns the program and type checker
+ * @throws Error if `tsconfig.json` is not found
  */
 export const ts_create_program = (options?: TsProgramOptions, log?: Logger): TsProgram => {
 	const root = options?.root ?? './';
@@ -106,7 +106,7 @@ export const ts_create_program = (options?: TsProgramOptions, log?: Logger): TsP
  * @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
+ * @returns module metadata and re-export information
  */
 export const ts_analyze_module = (
 	source_file_info: SourceFileInfo,
@@ -155,7 +155,7 @@ export const ts_analyze_module = (
  * @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
+ * @returns module comment, declarations, re-exports, and star exports
  */
 export const ts_analyze_module_exports = (
 	source_file: ts.SourceFile,
@@ -279,7 +279,7 @@ export const ts_analyze_module_exports = (
  * @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
+ * @returns complete declaration metadata including docs, types, and parameters, plus nodocs flag
  */
 export const ts_analyze_declaration = (
 	symbol: ts.Symbol,
@@ -332,7 +332,7 @@ export const ts_analyze_declaration = (
  * Requires `@module` tag to identify module comments. The tag line is stripped
  * from the output. Supports optional module renaming: `@module custom-name`.
  *
- * @see https://typedoc.org/documents/Tags._module.html
+ * @see {@link https://typedoc.org/documents/Tags._module.html}
  */
 export const ts_extract_module_comment = (source_file: ts.SourceFile): string | undefined => {
 	const full_text = source_file.getFullText();
@@ -434,7 +434,7 @@ export const ts_infer_declaration_kind = (symbol: ts.Symbol, node: ts.Node): Dec
  * @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
+ * @returns array of parameter info objects
  */
 export const ts_extract_signature_parameters = (
 	sig: ts.Signature,

package/src/lib/tsdoc_helpers.ts

@@ -220,7 +220,7 @@ export const tsdoc_apply_to_declaration = (
  * Transforms `/** ... *\/` style comments into clean text.
  *
  * @param comment_text - the raw comment text including `/**` and `*\/` markers
- * @returns Cleaned comment text, or undefined if empty after cleaning
+ * @returns cleaned comment text, or undefined if empty after cleaning
  */
 export const tsdoc_clean_comment = (comment_text: string): string | undefined => {
 	const text = comment_text

package/src/lib/vite_plugin_library_well_known.ts

@@ -6,7 +6,7 @@ import type {LibraryJson} from '@fuzdev/fuz_util/library_json.js';
 
 export interface VitePluginLibraryWellKnownOptions {
 	/**
-	 * Path to the library.json file (relative to vite.config.ts).
+	 * Path to the `library.json` file (relative to `vite.config.ts`).
 	 * @default './src/routes/library.json'
 	 */
 	library_path?: string;
@@ -27,7 +27,7 @@ const respond_json = (res: ServerResponse, body: string): void => {
 /**
  * Vite plugin that publishes `package.json` and `library.json` to `.well-known/`.
  *
- * Requires a generated library.json file (created by `library_gen` from `gro gen`).
+ * Requires a generated `library.json` file (created by `library_gen` from `gro gen`).
  * The plugin reads this JSON file and publishes its metadata to `.well-known/` for
  * both dev and production builds.
  *