@fuzdev/fuz_ui 0.194.0 → 0.195.0

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/library.svelte.ts

@@ -64,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
 			: [],
 	);
 

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

@@ -1,4 +1,4 @@
-import type {ModuleJson} from '@fuzdev/fuz_util/source_json.js';
+import type {ModuleJsonInput} from 'svelte-docinfo/types.js';
 
 import {Declaration} from './declaration.svelte.js';
 import type {Library} from './library.svelte.js';
@@ -6,13 +6,30 @@ import {url_github_file} from './package_helpers.js';
 
 /**
  * Rich runtime representation of a module with computed properties.
+ *
+ * Wraps svelte-docinfo's `ModuleJson` with reactive derivations,
+ * URL generation, and `Declaration` instances.
+ *
+ * @see {@link https://github.com/ryanatkn/svelte-docinfo svelte-docinfo} for the analysis library
+ * @see `declaration.svelte.ts` for the `Declaration` wrapper class
  */
 export class Module {
 	readonly library: Library = $state.raw()!;
-	readonly module_json: ModuleJson = $state.raw()!;
+	// `library.json` is compacted (svelte-docinfo's `compactReplacer` strips empty
+	// default arrays), so the on-disk data is the `*Input` shape. Typing it as
+	// input makes TypeScript force guards on defaulted-array reads.
+	readonly module_json: ModuleJsonInput = $state.raw()!;
 
 	/**
-	 * Canonical module path (e.g., 'Alert.ts', 'helpers/foo.ts').
+	 * Canonical module path — `src/lib/`-relative, with source extension
+	 * (`.ts`, `.svelte`, etc.). Examples: `'Alert.ts'`, `'helpers/foo.ts'`,
+	 * `'actions/composables.ts'`.
+	 *
+	 * This is the key `Library.module_by_path` indexes, so it's also the
+	 * exact string TSDoc backtick references must use to auto-link to a
+	 * module via `DocsLink.svelte` (e.g., `` `actions/composables.ts` ``).
+	 * A leading `./` or a `.js` runtime extension will not match. Top-level
+	 * files match by bare filename; nested files require the full sub-path.
 	 */
 	path = $derived(this.module_json.path);
 
@@ -21,17 +38,15 @@ export class Module {
 	 */
 	path_import = $derived('./' + this.path);
 
-	module_comment = $derived(this.module_json.module_comment);
+	module_comment = $derived(this.module_json.moduleComment);
 
 	/**
 	 * Array of `Declaration` instances. Filters out default exports.
 	 */
 	declarations = $derived(
-		this.module_json.declarations
-			? this.module_json.declarations
-					.filter((declaration_json) => declaration_json.name !== 'default')
-					.map((declaration_json) => new Declaration(this, declaration_json))
-			: [],
+		(this.module_json.declarations ?? [])
+			.filter((declaration_json) => declaration_json.name !== 'default')
+			.map((declaration_json) => new Declaration(this, declaration_json)),
 	);
 
 	/**
@@ -48,23 +63,21 @@ export class Module {
 			: undefined,
 	);
 
-	has_declarations: boolean = $derived(
-		!!(this.module_json.declarations && this.module_json.declarations.length > 0),
-	);
+	has_declarations: boolean = $derived((this.module_json.declarations?.length ?? 0) > 0);
 
-	has_module_comment: boolean = $derived(!!this.module_json.module_comment);
+	has_module_comment: boolean = $derived(!!this.module_comment);
 
 	/**
 	 * Modules this imports (paths relative to src/lib).
 	 */
-	dependencies = $derived(this.module_json.dependencies);
+	dependencies = $derived(this.module_json.dependencies ?? []);
 
 	/**
 	 * Modules that import this (paths relative to src/lib).
 	 */
-	dependents = $derived(this.module_json.dependents);
+	dependents = $derived(this.module_json.dependents ?? []);
 
-	constructor(library: Library, module_json: ModuleJson) {
+	constructor(library: Library, module_json: ModuleJsonInput) {
 		this.library = library;
 		this.module_json = module_json;
 	}

package/src/lib/tsdoc_mdz.ts

@@ -17,10 +17,12 @@ const format_reference = (ref: string): string => (mdz_is_url(ref) ? ref : `\`${
  * Convert raw TSDoc `@see` content to mdz format for rendering.
  *
  * Handles TSDoc link syntax:
- * - `{@link url|text}` → `[text](url)` (markdown link)
+ * - `{@link url|text}` → `[text](url)` (markdown link, TSDoc canonical form)
+ * - `{@link url text}` → `[text](url)` (TS-lenient space-separated form)
  * - `{@link https://...}` → `https://...` (bare URL, auto-linked by mdz)
  * - `{@link identifier}` → `` `identifier` `` (code formatting)
  * - Bare URLs → returned as-is
+ * - Bare markdown links (`[text](url)` ...) → returned as-is
  * - Bare identifiers → wrapped in backticks
  * - `identifier description text` → `` `identifier` description text `` (first token is the reference)
  *
@@ -38,6 +40,9 @@ const format_reference = (ref: string): string => (mdz_is_url(ref) ? ref : `\`${
  * tsdoc_see_to_mdz('https://example.com')
  * // → 'https://example.com'
  *
+ * tsdoc_see_to_mdz('[svelte-docinfo](https://github.com/ryanatkn/svelte-docinfo) for the analysis library')
+ * // → '[svelte-docinfo](https://github.com/ryanatkn/svelte-docinfo) for the analysis library'
+ *
  * tsdoc_see_to_mdz('library_gen.ts for Gro-specific integration')
  * // → '`library_gen.ts` for Gro-specific integration'
  * ```
@@ -51,7 +56,7 @@ export const tsdoc_see_to_mdz = (content: string): string => {
 	if (link_match) {
 		const inner = link_match[1]!.trim();
 
-		// Check for pipe separator (custom display text)
+		// Pipe separator takes precedence (TSDoc canonical form)
 		const pipe_index = inner.indexOf('|');
 		if (pipe_index !== -1) {
 			const reference = inner.slice(0, pipe_index).trim();
@@ -59,9 +64,27 @@ export const tsdoc_see_to_mdz = (content: string): string => {
 			return `[${display_text}](${reference})`;
 		}
 
+		// Space-separated form: TS accepts `{@link url text}` as equivalent to `{@link url|text}`.
+		// Only treat space as a separator when the first token looks like a link target (URL),
+		// so identifier-style references like `module.function` aren't split.
+		const space_index = inner.indexOf(' ');
+		if (space_index !== -1) {
+			const reference = inner.slice(0, space_index);
+			if (mdz_is_url(reference)) {
+				const display_text = inner.slice(space_index + 1).trim();
+				return `[${display_text}](${reference})`;
+			}
+		}
+
 		return format_reference(inner);
 	}
 
+	// Pass through bare markdown links (`[text](url)` optionally followed by description)
+	// so authors can write `@see [text](url) for context` directly.
+	if (trimmed.charCodeAt(0) === 91 /* [ */ && /^\[[^\]]+\]\([^)\s]+\)/.test(trimmed)) {
+		return trimmed;
+	}
+
 	// Split at first whitespace: first token is the reference, rest is description
 	const space_index = trimmed.indexOf(' ');
 	if (space_index === -1) {