@fuzdev/fuz_ui 0.204.0 → 0.205.0

package/dist/svelte_preprocess_mdz.js

@@ -1,529 +0,0 @@
-/**
- * Svelte preprocessor that compiles static `Mdz` content to Svelte markup at build time.
- *
- * Detects `Mdz` components with static string `content` props, parses the mdz content,
- * renders each `MdzNode` to equivalent Svelte markup via `mdz_to_svelte`, and replaces
- * the `Mdz` with `MdzPrecompiled` containing pre-rendered children.
- *
- * Also handles ternary chains (`content={a ? 'x' : b ? 'y' : 'z'}`) where all leaf
- * values are statically resolvable strings, emitting `{#if a}markup_x{:else if b}markup_y{:else}markup_z{/if}`
- * as children of a single `MdzPrecompiled`.
- *
- * Truly dynamic `content` props are left untouched.
- *
- * @module
- */
-import { parse } from 'svelte/compiler';
-import MagicString from 'magic-string';
-import { walk } from 'zimmerframe';
-import { should_exclude_path } from '@fuzdev/fuz_util/path.js';
-import { find_attribute, extract_static_string, try_extract_conditional_chain, build_static_bindings, resolve_component_names, has_identifier_in_tree, find_import_insert_position, generate_import_lines, remove_variable_declaration, remove_import_declaration, remove_import_specifier, handle_preprocess_error, } from '@fuzdev/fuz_util/svelte_preprocess_helpers.js';
-import { mdz_parse } from './mdz.js';
-import { mdz_to_svelte } from './mdz_to_svelte.js';
-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`
- */
-export const svelte_preprocess_mdz = (options = {}) => {
-    const { exclude = [], components = {}, elements: elements_array = [], component_imports = ['@fuzdev/fuz_ui/Mdz.svelte'], compiled_component_import = '@fuzdev/fuz_ui/MdzPrecompiled.svelte', on_error = process.env.CI === 'true' ? 'throw' : 'log', } = options;
-    const elements = new Set(elements_array);
-    return {
-        name: 'fuz-mdz',
-        markup: ({ content, filename }) => {
-            if (should_exclude_path(filename, exclude)) {
-                return { code: content };
-            }
-            // Quick bail: does file mention any known Mdz import source?
-            if (!component_imports.some((source) => content.includes(source))) {
-                return { code: content };
-            }
-            const ast = parse(content, { filename, modern: true });
-            // Resolve which local names map to the Mdz component
-            const mdz_names = resolve_component_names(ast, component_imports);
-            if (mdz_names.size === 0) {
-                return { code: content };
-            }
-            // Check for MdzPrecompiled name collision
-            if (has_name_collision(ast, compiled_component_import)) {
-                return { code: content };
-            }
-            const s = new MagicString(content);
-            const bindings = build_static_bindings(ast);
-            // Find and transform Mdz usages with static content
-            const { transformations, total_usages, transformed_usages } = find_mdz_usages(ast, mdz_names, {
-                components,
-                elements,
-                filename,
-                source: content,
-                bindings,
-                on_error,
-            });
-            if (transformations.length === 0) {
-                return { code: content };
-            }
-            // Apply transformations
-            for (const t of transformations) {
-                s.overwrite(t.start, t.end, t.replacement);
-            }
-            // Remove dead const bindings that were consumed by transformations
-            remove_dead_const_bindings(s, ast, transformations, content);
-            // Determine which Mdz imports can be removed
-            const removable_imports = find_removable_mdz_imports(ast, mdz_names, total_usages, transformed_usages);
-            // Add required imports and remove unused Mdz imports
-            manage_imports(s, ast, transformations, removable_imports, compiled_component_import, content);
-            return {
-                code: s.toString(),
-                map: s.generateMap({ hires: true }),
-            };
-        },
-    };
-};
-/**
- * Checks if `MdzPrecompiled` is already imported from a different source.
- * If so, the preprocessor bails to avoid name collisions.
- */
-const has_name_collision = (ast, compiled_component_import) => {
-    for (const script of [ast.instance, ast.module]) {
-        if (!script)
-            continue;
-        for (const node of script.content.body) {
-            if (node.type !== 'ImportDeclaration')
-                continue;
-            const source_path = node.source.value;
-            for (const spec of node.specifiers) {
-                if (spec.local.name === PRECOMPILED_NAME && source_path !== compiled_component_import) {
-                    return true;
-                }
-            }
-        }
-    }
-    return false;
-};
-/**
- * Collects identifiers from an expression that resolved through bindings.
- * Only collects top-level Identifier nodes that appear in the bindings map.
- *
- * TODO: support transitive dead const removal — currently only directly-consumed
- * bindings (identifiers in the expression AST) are tracked. Transitive dependencies
- * (e.g., `const a = 'x'; const b = a; content={b}` — `a` is not removed) are not
- * traced. After removing a dead const, re-check whether identifiers in its
- * initializer became dead too.
- */
-const collect_consumed_bindings = (value, bindings) => {
-    const consumed = new Set();
-    if (value === true || Array.isArray(value))
-        return consumed;
-    const collect_from_expr = (expr) => {
-        if (expr.type === 'Identifier' && bindings.has(expr.name)) {
-            consumed.add(expr.name);
-        }
-        else if (expr.type === 'BinaryExpression' && expr.operator === '+') {
-            collect_from_expr(expr.left);
-            collect_from_expr(expr.right);
-        }
-        else if (expr.type === 'TemplateLiteral') {
-            for (const e of expr.expressions) {
-                collect_from_expr(e);
-            }
-        }
-        else if (expr.type === 'ConditionalExpression') {
-            collect_from_expr(expr.consequent);
-            collect_from_expr(expr.alternate);
-        }
-    };
-    collect_from_expr(value.expression);
-    return consumed;
-};
-/**
- * Walks the AST to find `Mdz` component usages with static `content` props
- * and generates transformations to replace them with `MdzPrecompiled` children.
- */
-const find_mdz_usages = (ast, mdz_names, context) => {
-    const transformations = [];
-    const total_usages = new Map();
-    const transformed_usages = new Map();
-    // zimmerframe types visitors against {type: string}, requiring explicit annotations
-    // on the callback parameters for Svelte-specific AST types like AST.Component
-    walk(ast.fragment, null, {
-        Component(node, ctx) {
-            // Always recurse into children so nested Mdz components are found
-            ctx.next();
-            if (!mdz_names.has(node.name))
-                return;
-            // Track total usages per name
-            total_usages.set(node.name, (total_usages.get(node.name) ?? 0) + 1);
-            // Skip if spread attributes present — can't determine content statically
-            if (node.attributes.some((attr) => attr.type === 'SpreadAttribute'))
-                return;
-            const content_attr = find_attribute(node, 'content');
-            if (!content_attr)
-                return;
-            // Extract optional static base prop for relative path resolution.
-            // If base is present but dynamic, skip precompilation entirely —
-            // MdzPrecompiled doesn't resolve relative paths at runtime,
-            // so precompiling with unresolved relative links would be wrong.
-            const base_attr = find_attribute(node, 'base');
-            let base;
-            if (base_attr) {
-                const base_value = extract_static_string(base_attr.value, context.bindings);
-                if (base_value === null)
-                    return; // dynamic base — fall back to runtime
-                base = base_value;
-            }
-            // Collect attributes to exclude from precompiled output
-            const exclude_attrs = new Set([content_attr]);
-            if (base_attr)
-                exclude_attrs.add(base_attr);
-            // Extract static string value
-            const content_value = extract_static_string(content_attr.value, context.bindings);
-            if (content_value !== null) {
-                // Parse mdz content and render to Svelte markup
-                let result;
-                try {
-                    const nodes = mdz_parse(content_value);
-                    result = mdz_to_svelte(nodes, context.components, context.elements, base);
-                }
-                catch (error) {
-                    handle_preprocess_error(error, '[fuz-mdz]', context.filename, context.on_error);
-                    return;
-                }
-                // If content has unconfigured tags, skip this usage (fall back to runtime)
-                if (result.has_unconfigured_tags)
-                    return;
-                const consumed = collect_consumed_bindings(content_attr.value, context.bindings);
-                const replacement = build_replacement(node, exclude_attrs, result.markup, context.source);
-                transformed_usages.set(node.name, (transformed_usages.get(node.name) ?? 0) + 1);
-                transformations.push({
-                    start: node.start,
-                    end: node.end,
-                    replacement,
-                    required_imports: result.imports,
-                    consumed_bindings: consumed,
-                    component_node: node,
-                });
-                return;
-            }
-            // Try conditional chain (handles both simple and nested ternaries)
-            const chain = try_extract_conditional_chain(content_attr.value, context.source, context.bindings);
-            if (chain === null)
-                return;
-            // Parse and render each branch
-            const branch_results = [];
-            try {
-                for (const branch of chain) {
-                    const nodes = mdz_parse(branch.value);
-                    const result = mdz_to_svelte(nodes, context.components, context.elements, base);
-                    if (result.has_unconfigured_tags)
-                        return;
-                    branch_results.push({ markup: result.markup, imports: result.imports });
-                }
-            }
-            catch (error) {
-                handle_preprocess_error(error, '[fuz-mdz]', context.filename, context.on_error);
-                return;
-            }
-            // Build {#if}/{:else if}/{:else} markup
-            let children_markup = '';
-            for (let i = 0; i < chain.length; i++) {
-                const branch = chain[i];
-                const result = branch_results[i];
-                if (i === 0) {
-                    children_markup += `{#if ${branch.test_source}}${result.markup}`;
-                }
-                else if (branch.test_source !== null) {
-                    children_markup += `{:else if ${branch.test_source}}${result.markup}`;
-                }
-                else {
-                    children_markup += `{:else}${result.markup}`;
-                }
-            }
-            children_markup += '{/if}';
-            const replacement = build_replacement(node, exclude_attrs, children_markup, context.source);
-            // Merge imports from all branches
-            const merged_imports = new Map();
-            for (const result of branch_results) {
-                for (const [name, info] of result.imports) {
-                    merged_imports.set(name, info);
-                }
-            }
-            const consumed = collect_consumed_bindings(content_attr.value, context.bindings);
-            transformed_usages.set(node.name, (transformed_usages.get(node.name) ?? 0) + 1);
-            transformations.push({
-                start: node.start,
-                end: node.end,
-                replacement,
-                required_imports: merged_imports,
-                consumed_bindings: consumed,
-                component_node: node,
-            });
-        },
-    });
-    return { transformations, total_usages, transformed_usages };
-};
-/**
- * Removes dead `const` bindings from the instance script that were consumed
- * by transformations and are no longer referenced anywhere else in the file.
- *
- * Only handles single-declarator `const` statements. Skips `const a = 'x', b = 'y'`
- * and module script variables (which could be exported/imported by other files).
- */
-const remove_dead_const_bindings = (s, ast, transformations, source) => {
-    // Collect all consumed binding names across transformations
-    const all_consumed = new Set();
-    for (const t of transformations) {
-        for (const name of t.consumed_bindings) {
-            all_consumed.add(name);
-        }
-    }
-    if (all_consumed.size === 0)
-        return;
-    // Only remove from instance script (module script variables could be exported)
-    const instance = ast.instance;
-    if (!instance)
-        return;
-    // Build a skip set of transformed component nodes so their attribute
-    // expressions (which still contain the old identifiers) don't false-match
-    const skip = new Set();
-    for (const t of transformations) {
-        skip.add(t.component_node);
-    }
-    for (const name of all_consumed) {
-        // Find the VariableDeclaration containing this binding in instance script
-        let declaration_node = null;
-        for (const node of instance.content.body) {
-            if (node.type !== 'VariableDeclaration' || node.kind !== 'const')
-                continue;
-            for (const decl of node.declarations) {
-                if (decl.id.type === 'Identifier' && decl.id.name === name) {
-                    declaration_node = node;
-                    break;
-                }
-            }
-            if (declaration_node)
-                break;
-        }
-        if (!declaration_node)
-            continue;
-        // Only handle single-declarator statements
-        if (declaration_node.declarations.length !== 1)
-            continue;
-        // Check if the identifier is referenced anywhere else
-        const id_skip = new Set([...skip, declaration_node]);
-        // Check instance script (excluding the declaration itself)
-        if (has_identifier_in_tree(instance.content, name, id_skip))
-            continue;
-        // Check module script
-        if (ast.module?.content && has_identifier_in_tree(ast.module.content, name))
-            continue;
-        // Check template — skip transformed component nodes whose attribute expressions
-        // still contain the old identifier references in the AST
-        if (has_identifier_in_tree(ast.fragment, name, id_skip))
-            continue;
-        remove_variable_declaration(s, declaration_node, source);
-        // Add to skip set so chained dead const checks don't find references to this removed node
-        skip.add(declaration_node);
-    }
-};
-/**
- * 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.
- */
-const build_replacement = (node, exclude_attrs, children_markup, source) => {
-    // Collect source ranges of all attributes except excluded ones (content, base when resolved)
-    const other_attr_ranges = [];
-    for (const attr of node.attributes) {
-        if (exclude_attrs.has(attr))
-            continue;
-        other_attr_ranges.push({ start: attr.start, end: attr.end });
-    }
-    // Build opening tag with MdzPrecompiled name
-    let opening = `<${PRECOMPILED_NAME}`;
-    for (const range of other_attr_ranges) {
-        opening += ' ' + source.slice(range.start, range.end);
-    }
-    opening += '>';
-    return `${opening}${children_markup}</${PRECOMPILED_NAME}>`;
-};
-/**
- * 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 single-specifier imports, the entire declaration is removed.
- */
-const find_removable_mdz_imports = (ast, mdz_names, total_usages, transformed_usages) => {
-    const removable = new Map();
-    for (const [name, { import_node, specifier }] of mdz_names) {
-        const total = total_usages.get(name) ?? 0;
-        const transformed = transformed_usages.get(name) ?? 0;
-        // Only remove if ALL template usages were transformed
-        if (total === 0 || transformed < total)
-            continue;
-        // Check if identifier is referenced elsewhere in the AST
-        const skip = new Set([import_node]);
-        // Check instance script body (excluding the import itself)
-        if (ast.instance?.content && has_identifier_in_tree(ast.instance.content, name, skip)) {
-            continue;
-        }
-        // Check module script body (excluding the import itself)
-        if (ast.module?.content && has_identifier_in_tree(ast.module.content, name, skip)) {
-            continue;
-        }
-        // Check template for expression references (Component.name is a string, not Identifier)
-        if (has_identifier_in_tree(ast.fragment, name)) {
-            continue;
-        }
-        const positioned_node = import_node;
-        if (import_node.specifiers.length === 1) {
-            removable.set(name, { node: positioned_node, kind: 'full' });
-        }
-        else {
-            removable.set(name, {
-                node: positioned_node,
-                kind: 'partial',
-                specifier_to_remove: specifier,
-            });
-        }
-    }
-    return removable;
-};
-/**
- * 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.
- *
- * Handles both full removal (single-specifier imports) and partial removal
- * (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`
- * import line instead of using separate remove + appendLeft.
- */
-const manage_imports = (s, ast, transformations, removable_imports, compiled_component_import, source) => {
-    // Collect all required imports across transformations
-    const required = new Map();
-    for (const t of transformations) {
-        for (const [name, info] of t.required_imports) {
-            required.set(name, info);
-        }
-    }
-    // Always need MdzPrecompiled when transformations occur
-    required.set(PRECOMPILED_NAME, { path: compiled_component_import, kind: 'default' });
-    const script = ast.instance;
-    // Separate full removals from partial removals
-    const full_removals = new Set();
-    const partial_removals = [];
-    for (const [, action] of removable_imports) {
-        if (action.kind === 'full') {
-            full_removals.add(action.node);
-        }
-        else {
-            partial_removals.push(action);
-        }
-    }
-    if (!script) {
-        // No instance script — removable_imports won't apply (imports are in module script if any)
-        // Just add all required imports
-        const lines = generate_import_lines(required);
-        if (ast.module) {
-            s.appendLeft(ast.module.end, `\n\n<script lang="ts">\n${lines}\n</script>`);
-        }
-        else {
-            s.prepend(`<script lang="ts">\n${lines}\n</script>\n\n`);
-        }
-        // Remove Mdz imports from module script if removable
-        for (const node of full_removals) {
-            remove_import_declaration(s, node, source);
-        }
-        // Apply partial removals
-        for (const action of partial_removals) {
-            remove_import_specifier(s, action.node, action.specifier_to_remove, source);
-        }
-        return;
-    }
-    // Check existing imports to avoid duplicates — tracks both name AND source path
-    const existing = new Map();
-    for (const node of script.content.body) {
-        if (node.type === 'ImportDeclaration') {
-            const source_path = node.source.value;
-            for (const spec of node.specifiers) {
-                existing.set(spec.local.name, source_path);
-            }
-        }
-    }
-    const to_add = new Map();
-    for (const [name, info] of required) {
-        const existing_path = existing.get(name);
-        if (existing_path === undefined) {
-            to_add.set(name, info);
-        }
-    }
-    // Strategy: if we're both adding MdzPrecompiled and removing an Mdz import,
-    // overwrite one full-removable import with the MdzPrecompiled line to avoid
-    // MagicString boundary conflicts. Other imports use normal appendLeft.
-    let overwrite_target = null;
-    if (to_add.has(PRECOMPILED_NAME) && full_removals.size > 0) {
-        // Pick the first removable import to overwrite
-        overwrite_target = full_removals.values().next().value ?? null;
-    }
-    // Generate the MdzPrecompiled import line separately if using overwrite
-    if (overwrite_target) {
-        const node_start = overwrite_target.start;
-        const node_end = overwrite_target.end;
-        // Find the start of the line (consume leading whitespace)
-        let line_start = node_start;
-        while (line_start > 0 && (source[line_start - 1] === '\t' || source[line_start - 1] === ' ')) {
-            line_start--;
-        }
-        // Extract indentation from the original import line rather than hardcoding a tab.
-        // The import node's start is after any leading whitespace, so the indentation is
-        // the characters between the line start and the node start.
-        const original_indent = source.slice(line_start, node_start);
-        const precompiled_line = `${original_indent}import ${PRECOMPILED_NAME} from '${compiled_component_import}';`;
-        s.overwrite(line_start, node_end, precompiled_line);
-        to_add.delete(PRECOMPILED_NAME);
-    }
-    // When there are partial removals but no full-removal overwrite target,
-    // the appendLeft at find_import_insert_position can conflict with the
-    // partial removal's overwrite (they share the same node.end boundary).
-    // Bundle the new imports into the first partial removal's overwrite instead.
-    const insert_pos = find_import_insert_position(script);
-    let partial_carrier = null;
-    if (to_add.size > 0 && partial_removals.length > 0) {
-        for (const action of partial_removals) {
-            if (action.node.end === insert_pos) {
-                partial_carrier = action;
-                break;
-            }
-        }
-    }
-    // Add remaining imports — either bundled with a partial removal or via appendLeft
-    let carrier_lines = '';
-    if (partial_carrier && to_add.size > 0) {
-        carrier_lines = '\n' + generate_import_lines(to_add);
-        to_add.clear();
-    }
-    if (to_add.size > 0) {
-        const lines = generate_import_lines(to_add);
-        s.appendLeft(insert_pos, '\n' + lines);
-    }
-    // Remove remaining full Mdz imports (skip the overwrite target)
-    for (const node of full_removals) {
-        if (node === overwrite_target)
-            continue;
-        remove_import_declaration(s, node, source);
-    }
-    // Apply partial import removals
-    for (const action of partial_removals) {
-        remove_import_specifier(s, action.node, action.specifier_to_remove, source, action === partial_carrier ? carrier_lines : '');
-    }
-};

package/dist/tsdoc_mdz.d.ts

@@ -1,45 +0,0 @@
-/**
- * Bridge between TSDoc format and mdz for rendering.
- *
- * This module converts raw TSDoc syntax (from the analysis library) to mdz format
- * (Fuz's documentation rendering dialect). It lives in fuz_ui, not the extracted
- * analysis library, to keep that library format-agnostic.
- *
- * @module
- */
-/**
- * Convert raw TSDoc `@see` content to mdz format for rendering.
- *
- * Handles TSDoc link syntax:
- * - `{@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)
- *
- * @param content - raw `@see` tag content in TSDoc format
- * @returns mdz-formatted string ready for `Mdz` component
- *
- * @example
- * ```ts
- * tsdoc_see_to_mdz('{@link https://fuz.dev|API Docs}')
- * // → '[API Docs](https://fuz.dev)'
- *
- * tsdoc_see_to_mdz('{@link SomeType}')
- * // → '`SomeType`'
- *
- * tsdoc_see_to_mdz('https://fuz.dev')
- * // → 'https://fuz.dev'
- *
- * 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('tome.ts for the documentation system')
- * // → '`tome.ts` for the documentation system'
- * ```
- */
-export declare const tsdoc_see_to_mdz: (content: string) => string;
-//# sourceMappingURL=tsdoc_mdz.d.ts.map

package/dist/tsdoc_mdz.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tsdoc_mdz.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/tsdoc_mdz.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,MAAM,KAAG,MA+ClD,CAAC"}

package/dist/tsdoc_mdz.js

@@ -1,88 +0,0 @@
-/**
- * Bridge between TSDoc format and mdz for rendering.
- *
- * This module converts raw TSDoc syntax (from the analysis library) to mdz format
- * (Fuz's documentation rendering dialect). It lives in fuz_ui, not the extracted
- * analysis library, to keep that library format-agnostic.
- *
- * @module
- */
-import { mdz_is_url } from './mdz_helpers.js';
-/** Format a reference as mdz: URLs pass through, identifiers get backticks. */
-const format_reference = (ref) => (mdz_is_url(ref) ? ref : `\`${ref}\``);
-/**
- * Convert raw TSDoc `@see` content to mdz format for rendering.
- *
- * Handles TSDoc link syntax:
- * - `{@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)
- *
- * @param content - raw `@see` tag content in TSDoc format
- * @returns mdz-formatted string ready for `Mdz` component
- *
- * @example
- * ```ts
- * tsdoc_see_to_mdz('{@link https://fuz.dev|API Docs}')
- * // → '[API Docs](https://fuz.dev)'
- *
- * tsdoc_see_to_mdz('{@link SomeType}')
- * // → '`SomeType`'
- *
- * tsdoc_see_to_mdz('https://fuz.dev')
- * // → 'https://fuz.dev'
- *
- * 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('tome.ts for the documentation system')
- * // → '`tome.ts` for the documentation system'
- * ```
- */
-export const tsdoc_see_to_mdz = (content) => {
-    const trimmed = content.trim();
-    if (!trimmed)
-        return '';
-    // Check for {@link ...} or {@see ...} syntax
-    const link_match = /^\{@(?:link|see)\s+([^}]+)\}$/.exec(trimmed);
-    if (link_match) {
-        const inner = link_match[1].trim();
-        // Pipe separator takes precedence (TSDoc canonical form)
-        const pipe_index = inner.indexOf('|');
-        if (pipe_index !== -1) {
-            const reference = inner.slice(0, pipe_index).trim();
-            const display_text = inner.slice(pipe_index + 1).trim();
-            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) {
-        return format_reference(trimmed);
-    }
-    const reference = trimmed.slice(0, space_index);
-    const description = trimmed.slice(space_index); // preserve leading space
-    return format_reference(reference) + description;
-};