@promptbook/cli 0.114.0-5 → 0.114.0-7

package/src/book-components/Chat/utils/renderMarkdown.ts

@@ -267,14 +267,63 @@ const DETAILS_PLACEHOLDER_WRAPPED_REGEX = new RegExp(`<p>\\s*(${DETAILS_PLACEHOL
 const INLINE_REFERENCE_REGEX = /\[\[([^\]\r\n]+?)\]\]/g;
 
 /**
- * Pattern matching ordinary markdown links that can be promoted to inline reference chips.
+ * Prefix for INLINE REFERENCE PLACEHOLDER.
  *
- * Images are intentionally captured separately and left unchanged by the replacement helper.
+ * @private utility of `renderMarkdown`
+ */
+const INLINE_REFERENCE_PLACEHOLDER_PREFIX = '@@PROMPTBOOK_INLINE_REFERENCE_PLACEHOLDER__';
+
+/**
+ * Pattern matching INLINE REFERENCE PLACEHOLDER.
+ *
+ * @private utility of `renderMarkdown`
+ */
+const INLINE_REFERENCE_PLACEHOLDER_REGEX = new RegExp(`${INLINE_REFERENCE_PLACEHOLDER_PREFIX}(\\d+)__`, 'g');
+
+/**
+ * Prefix for markdown text-segment placeholders used while resolving plain-text inline-reference aliases.
+ *
+ * @private utility of `renderMarkdown`
+ */
+const MARKDOWN_REFERENCE_TEXT_MASK_PLACEHOLDER_PREFIX = '@@PROMPTBOOK_MARKDOWN_REFERENCE_TEXT_MASK_PLACEHOLDER__';
+
+/**
+ * Pattern matching markdown text-segment placeholders.
+ *
+ * @private utility of `renderMarkdown`
+ */
+const MARKDOWN_REFERENCE_TEXT_MASK_PLACEHOLDER_REGEX = new RegExp(
+    `${MARKDOWN_REFERENCE_TEXT_MASK_PLACEHOLDER_PREFIX}(\\d+)__`,
+    'g',
+);
+
+/**
+ * Pattern matching markdown links and images together with their raw target.
+ *
+ * @private utility of `renderMarkdown`
+ */
+const MARKDOWN_LINK_REGEX = /(!?)\[([^\]\r\n]*)\]\(\s*(<[^>\r\n]*>|[^()\s]+)(?:\s+(?:"[^"]*"|'[^']*'))?\s*\)/g;
+
+/**
+ * Pattern matching bare `http(s)` URLs written directly into markdown text.
+ *
+ * @private utility of `renderMarkdown`
+ */
+const BARE_URL_REGEX = /(^|\s)(https?:\/\/[^\s<>()[\]"']+)/g;
+
+/**
+ * Sentence punctuation which trails a bare URL instead of belonging to it.
+ *
+ * @private utility of `renderMarkdown`
+ */
+const BARE_URL_TRAILING_PUNCTUATION_REGEX = /[.,;:!?]+$/;
+
+/**
+ * Pattern splitting one URL into its scheme, host and remaining part.
  *
  * @private utility of `renderMarkdown`
  */
-const MARKDOWN_INLINE_REFERENCE_LINK_REGEX =
-    /(!?)\[([^\]\r\n]*)\]\(\s*(<[^>\r\n]+>|[^)\s]+)(?:\s+(?:"[^"\r\n]*"|'[^'\r\n]*'|\([^)]*\)))?\s*\)/g;
+const ABSOLUTE_URL_REGEX = /^[a-z][a-z0-9+.-]*:\/\/([^/?#]*)(.*)$/i;
 
 /**
  * Markdown patterns that are strong enough to identify content as markdown.
@@ -333,6 +382,14 @@ export type MarkdownInlineReference = {
      */
     readonly reference: string;
 
+    /**
+     * Optional text aliases which should render as this reference when an agent mentions them in markdown.
+     *
+     * They are also accepted inside a `[[reference]]` token. This lets application code use a stable
+     * technical reference while recognizing a human-facing name in older messages.
+     */
+    readonly sourceTextAliases?: ReadonlyArray<string>;
+
     /**
      * Human-readable label rendered inside the link chip.
      */
@@ -344,10 +401,12 @@ export type MarkdownInlineReference = {
     readonly href: string;
 
     /**
-     * Markdown link destination prefixes that should render as this reference as well.
+     * Optional URL prefixes which also identify this reference in the authored markdown.
      *
-     * This supports legacy links such as an Agents Server project file URL while keeping
-     * `reference` as the canonical `[[project]]` token.
+     * A markdown link or a bare URL pointing to one of these prefixes is rendered as the same chip
+     * as the `[[reference]]` token. Both absolute URLs (for example `https://project.example.com`)
+     * and application paths (for example `/agents/agent/projects/website`) are supported; a path
+     * prefix matches on any host so that both relative and absolute links are recognized.
      */
     readonly sourceHrefPrefixes?: ReadonlyArray<string>;
 
@@ -426,6 +485,14 @@ type MaskedCodeSegmentsResult = {
     restore: (value: string_markdown) => string_markdown;
 };
 
+/**
+ * Result of temporarily masked markdown links, images and bare URLs.
+ */
+type MaskedMarkdownLinkAndUrlSegmentsResult = {
+    masked: string_markdown;
+    restore: (value: string_markdown) => string_markdown;
+};
+
 /**
  * Result of masked details blocks.
  */
@@ -696,12 +763,11 @@ const CHAT_MARKDOWN_CONVERTER = createChatMarkdownConverter();
  * outer `<details>` and optional `<summary>` markup untouched.
  *
  * @param detailsBlock - Raw `<details>...</details>` HTML captured from markdown.
- * @param options - Markdown rendering options to reuse for the details body.
  * @returns `<details>` HTML whose body has been converted from markdown to HTML.
  *
  * @private utility of `renderMarkdown`
  */
-function renderDetailsBlock(detailsBlock: string, options?: RenderMarkdownOptions): string_html {
+function renderDetailsBlock(detailsBlock: string): string_html {
     const openTagMatch = detailsBlock.match(/^<details\b[^>]*>/i);
     const closeTagMatch = detailsBlock.match(/<\/details\s*>$/i);
 
@@ -715,7 +781,7 @@ function renderDetailsBlock(detailsBlock: string, options?: RenderMarkdownOption
     const summaryMatch = innerContent.match(/^(\s*<summary\b[^>]*>[\s\S]*?<\/summary\s*>)([\s\S]*)$/i);
     const summaryHtml = summaryMatch?.[1] ?? '';
     const bodyMarkdown = (summaryMatch?.[2] ?? innerContent) as string_markdown;
-    const renderedBody = renderMarkdown(bodyMarkdown, options);
+    const renderedBody = renderMarkdown(bodyMarkdown);
 
     return `${openTag}${summaryHtml}${renderedBody}${closeTag}` as string_html;
 }
@@ -754,23 +820,60 @@ function maskMarkdownCodeSegments(markdown: string_markdown): MaskedCodeSegments
     };
 }
 
+/**
+ * Masks markdown links, images and bare URLs while plain-text reference aliases are resolved.
+ *
+ * A matching display name inside an unrelated link label must keep that original link instead of
+ * producing a nested chip inside its anchor.
+ *
+ * @param markdown - Markdown without code segments.
+ * @returns Masked markdown and a restore helper.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function maskMarkdownLinksAndBareUrls(markdown: string_markdown): MaskedMarkdownLinkAndUrlSegmentsResult {
+    const segments: string[] = [];
+    const addPlaceholder = (segment: string): string => {
+        const placeholder = `${MARKDOWN_REFERENCE_TEXT_MASK_PLACEHOLDER_PREFIX}${segments.length}__`;
+        segments.push(segment);
+        return placeholder;
+    };
+
+    MARKDOWN_LINK_REGEX.lastIndex = 0;
+    let masked = markdown.replace(MARKDOWN_LINK_REGEX, (match) => addPlaceholder(match)) as string_markdown;
+
+    BARE_URL_REGEX.lastIndex = 0;
+    masked = masked.replace(BARE_URL_REGEX, (_match, leadingWhitespace: string, rawUrl: string) => {
+        return `${leadingWhitespace}${addPlaceholder(rawUrl)}`;
+    }) as string_markdown;
+
+    return {
+        masked,
+        restore(value: string_markdown): string_markdown {
+            return value.replace(
+                MARKDOWN_REFERENCE_TEXT_MASK_PLACEHOLDER_REGEX,
+                (_match, index) => segments[Number(index)] ?? '',
+            );
+        },
+    };
+}
+
 /**
  * Masks `<details>...</details>` blocks in the markdown source so that Showdown never
  * processes their content.
  *
  * @param markdown - Markdown text that may contain raw HTML `<details>` blocks.
- * @param options - Markdown rendering options to reuse for the details body.
  * @returns Masked markdown and a restore helper that returns `string_html`.
  *
  * @private utility of `renderMarkdown`
  */
-function maskDetailsBlocks(markdown: string_markdown, options?: RenderMarkdownOptions): MaskedDetailsBlocksResult {
+function maskDetailsBlocks(markdown: string_markdown): MaskedDetailsBlocksResult {
     const blocks: string_html[] = [];
 
     DETAILS_BLOCK_REGEX.lastIndex = 0;
     const masked = markdown.replace(DETAILS_BLOCK_REGEX, (match) => {
         const placeholder = `${DETAILS_PLACEHOLDER_PREFIX}${blocks.length}__`;
-        blocks.push(renderDetailsBlock(match, options));
+        blocks.push(renderDetailsBlock(match));
         return placeholder;
     }) as string_markdown;
 
@@ -859,6 +962,18 @@ function normalizeMarkdownInlineReferenceKey(value: string): string {
     return value.trim().toLowerCase();
 }
 
+/**
+ * Lists all token keys which can identify one inline reference.
+ *
+ * @param reference - Inline reference with its stable key and optional display-name aliases.
+ * @returns Keys recognized inside `[[...]]` tokens.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function listMarkdownInlineReferenceKeys(reference: MarkdownInlineReference): ReadonlyArray<string> {
+    return [reference.reference, ...(reference.sourceTextAliases || [])];
+}
+
 /**
  * Builds a lookup of inline markdown references keyed by the authored `[[reference]]` text.
  *
@@ -873,102 +988,324 @@ function createMarkdownInlineReferenceByKey(
     const referenceByKey = new Map<string, MarkdownInlineReference>();
 
     for (const reference of references) {
-        const normalizedReference = normalizeMarkdownInlineReferenceKey(reference.reference);
-        if (!normalizedReference || referenceByKey.has(normalizedReference)) {
-            continue;
-        }
+        for (const referenceKey of listMarkdownInlineReferenceKeys(reference)) {
+            const normalizedReference = normalizeMarkdownInlineReferenceKey(referenceKey);
+            if (!normalizedReference || referenceByKey.has(normalizedReference)) {
+                continue;
+            }
 
-        referenceByKey.set(normalizedReference, reference);
+            referenceByKey.set(normalizedReference, reference);
+        }
     }
 
     return referenceByKey;
 }
 
 /**
- * Returns whether a href starts with a configured source href prefix.
+ * One display-name alias and the inline reference it renders.
+ *
+ * @private utility of `renderMarkdown`
+ */
+type MarkdownInlineReferenceTextMatcher = {
+    /**
+     * Reference rendered for the alias.
+     */
+    readonly reference: MarkdownInlineReference;
+
+    /**
+     * Human-readable source text recognized in markdown.
+     */
+    readonly sourceTextAlias: string;
+};
+
+/**
+ * Escapes text before embedding it into a regular expression.
  *
- * @param href - Markdown link destination.
- * @param sourceHrefPrefix - Configured source href prefix.
- * @returns Whether the href belongs to the source prefix.
+ * @param value - Literal text to match.
+ * @returns Regular-expression-safe text.
  *
  * @private utility of `renderMarkdown`
  */
-function doesHrefStartWithSourceHrefPrefix(href: string, sourceHrefPrefix: string): boolean {
-    if (href === sourceHrefPrefix) {
-        return true;
+function escapeRegularExpression(value: string): string {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Creates non-ambiguous display-name matchers for inline references.
+ *
+ * Longer aliases are matched first so a project named `Prague Map` wins over a project named `Map`.
+ * An alias shared by more than one reference is deliberately ignored instead of linking to an arbitrary project.
+ *
+ * @param references - References available to this markdown render.
+ * @returns Plain-text matchers ordered from longest to shortest alias.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function createMarkdownInlineReferenceTextMatchers(
+    references: ReadonlyArray<MarkdownInlineReference>,
+): ReadonlyArray<MarkdownInlineReferenceTextMatcher> {
+    const matcherByNormalizedAlias = new Map<string, MarkdownInlineReferenceTextMatcher | null>();
+
+    for (const reference of references) {
+        for (const sourceTextAliasCandidate of reference.sourceTextAliases || []) {
+            const sourceTextAlias = sourceTextAliasCandidate.trim();
+            const normalizedAlias = normalizeMarkdownInlineReferenceKey(sourceTextAlias);
+            if (!normalizedAlias) {
+                continue;
+            }
+
+            const existingMatcher = matcherByNormalizedAlias.get(normalizedAlias);
+            if (existingMatcher === undefined) {
+                matcherByNormalizedAlias.set(normalizedAlias, { reference, sourceTextAlias });
+            } else if (existingMatcher !== null && existingMatcher.reference !== reference) {
+                matcherByNormalizedAlias.set(normalizedAlias, null);
+            }
+        }
     }
 
-    const normalizedSourceHrefPrefix = sourceHrefPrefix.endsWith('/') ? sourceHrefPrefix : `${sourceHrefPrefix}/`;
+    return Array.from(matcherByNormalizedAlias.values())
+        .filter((matcher): matcher is MarkdownInlineReferenceTextMatcher => matcher !== null)
+        .sort(
+            (firstMatcher, secondMatcher) =>
+                secondMatcher.sourceTextAlias.length - firstMatcher.sourceTextAlias.length ||
+                firstMatcher.sourceTextAlias.localeCompare(secondMatcher.sourceTextAlias),
+        );
+}
 
-    return href.startsWith(normalizedSourceHrefPrefix);
+/**
+ * Creates a regular expression matching one plain-text alias with optional bold markdown around it.
+ *
+ * @param sourceTextAlias - Literal display name to match.
+ * @param isMarkdownFormattingMatched - Whether matching `**alias**` and `__alias__` form.
+ * @returns Unicode-aware whole-text regular expression.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function createMarkdownInlineReferenceTextAliasRegex(
+    sourceTextAlias: string,
+    isMarkdownFormattingMatched: boolean,
+): RegExp {
+    const escapedAlias = escapeRegularExpression(sourceTextAlias);
+    const boundaryCharacterClass = '\\p{L}\\p{N}_-';
+    const boundaryPattern = `[^${boundaryCharacterClass}]`;
+    const aliasPattern = isMarkdownFormattingMatched
+        ? `(?:\\*\\*|__)${escapedAlias}(?:\\*\\*|__)`
+        : escapedAlias;
+
+    return new RegExp(`(^|${boundaryPattern})${aliasPattern}(?=$|${boundaryPattern})`, 'giu');
 }
 
 /**
- * Returns a comparable path for an absolute href when the configured source prefix is relative.
+ * Replaces known project display names in agent markdown with inline-reference placeholders.
+ *
+ * Bold aliases are replaced first so an older message such as `**Prague Murders Map**` becomes one
+ * chip rather than a chip nested inside formatting markup.
  *
- * @param href - Href to normalize.
- * @returns Absolute URL pathname or the original href when it is relative/invalid.
+ * @param markdown - Markdown with code and links already masked.
+ * @param matchers - Non-ambiguous display-name aliases available to this render.
+ * @param createPlaceholder - Renders a matched reference into a placeholder.
+ * @returns Markdown containing inline-reference placeholders.
  *
  * @private utility of `renderMarkdown`
  */
-function resolveAbsoluteHrefPath(href: string): string {
+function replaceMarkdownInlineReferenceTextAliases(
+    markdown: string_markdown,
+    matchers: ReadonlyArray<MarkdownInlineReferenceTextMatcher>,
+    createPlaceholder: CreateMarkdownInlineReferencePlaceholder,
+): string_markdown {
+    let referencedMarkdown = markdown;
+
+    for (const matcher of matchers) {
+        for (const isMarkdownFormattingMatched of [true, false]) {
+            const aliasRegex = createMarkdownInlineReferenceTextAliasRegex(
+                matcher.sourceTextAlias,
+                isMarkdownFormattingMatched,
+            );
+            referencedMarkdown = referencedMarkdown.replace(aliasRegex, (_match, leadingBoundary: string) => {
+                return `${leadingBoundary || ''}${createPlaceholder(matcher.reference)}`;
+            }) as string_markdown;
+        }
+    }
+
+    return referencedMarkdown;
+}
+
+/**
+ * Comparable parts of one URL used to recognize inline references written as links or bare URLs.
+ *
+ * @private utility of `renderMarkdown`
+ */
+type ComparableUrlParts = {
+    /**
+     * Lowercase host of an absolute URL, or an empty string for a host-independent application path.
+     */
+    readonly host: string;
+
+    /**
+     * Lowercase decoded path without query, hash and trailing slashes.
+     */
+    readonly path: string;
+};
+
+/**
+ * One inline reference together with its comparable source URL prefixes.
+ *
+ * @private utility of `renderMarkdown`
+ */
+type MarkdownInlineReferenceHrefMatcher = {
+    /**
+     * Reference rendered when one of its source prefixes matches.
+     */
+    readonly reference: MarkdownInlineReference;
+
+    /**
+     * Comparable form of the reference source URL prefixes.
+     */
+    readonly sourceHrefPrefixes: ReadonlyArray<ComparableUrlParts>;
+};
+
+/**
+ * Renders one matched reference and returns the placeholder standing for it.
+ *
+ * @private utility of `renderMarkdown`
+ */
+type CreateMarkdownInlineReferencePlaceholder = (reference: MarkdownInlineReference) => string;
+
+/**
+ * Decodes percent-encoded characters without failing on malformed input.
+ *
+ * @param value - Raw URL part.
+ * @returns Decoded value, or the original value when it cannot be decoded.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function decodeUrlPartSafely(value: string): string {
     try {
-        return new URL(href).pathname;
+        return decodeURIComponent(value);
     } catch {
-        return href;
+        return value;
     }
 }
 
 /**
- * Returns whether one markdown link destination belongs to one inline reference.
+ * Normalizes one URL path so that encoding, casing and trailing slashes do not break matching.
+ *
+ * @param path - Raw path including an optional query and hash.
+ * @returns Comparable path.
  *
- * Relative project paths also match absolute URLs on the current server, which keeps
- * server-generated relative links and model-generated absolute links consistent.
+ * @private utility of `renderMarkdown`
+ */
+function normalizeUrlPathForComparison(path: string): string {
+    const pathWithoutQuery = path.split(/[?#]/, 1)[0] || '';
+
+    return decodeUrlPartSafely(pathWithoutQuery).toLowerCase().replace(/\/+$/, '');
+}
+
+/**
+ * Splits one absolute URL or application path into its comparable parts.
  *
- * @param reference - Candidate inline reference.
- * @param href - Markdown link destination.
- * @returns Whether the href should render as the reference chip.
+ * @param url - Raw link target written in markdown.
+ * @returns Comparable URL parts, or `null` when the value cannot address a reference.
  *
  * @private utility of `renderMarkdown`
  */
-function doesMarkdownInlineReferenceMatchHref(reference: MarkdownInlineReference, href: string): boolean {
-    const normalizedHref = href.trim();
+function createComparableUrlParts(url: string): ComparableUrlParts | null {
+    const trimmedUrl = url
+        .trim()
+        .replace(/^<([\s\S]*)>$/, '$1')
+        .trim();
 
-    return (reference.sourceHrefPrefixes || []).some((sourceHrefPrefix) => {
-        const normalizedSourceHrefPrefix = sourceHrefPrefix.trim();
-        if (!normalizedSourceHrefPrefix) {
-            return false;
-        }
+    if (trimmedUrl === '') {
+        return null;
+    }
 
-        if (doesHrefStartWithSourceHrefPrefix(normalizedHref, normalizedSourceHrefPrefix)) {
-            return true;
-        }
+    const absoluteUrlMatch = trimmedUrl.match(ABSOLUTE_URL_REGEX);
+    if (absoluteUrlMatch) {
+        return {
+            host: absoluteUrlMatch[1]!.toLowerCase(),
+            path: normalizeUrlPathForComparison(absoluteUrlMatch[2] || ''),
+        };
+    }
 
-        const isRelativeSourceHrefPrefix = !/^[a-z][a-z0-9+.-]*:/i.test(normalizedSourceHrefPrefix);
-        const isAbsoluteHref = /^[a-z][a-z0-9+.-]*:/i.test(normalizedHref);
+    if (!trimmedUrl.startsWith('/')) {
+        return null;
+    }
 
-        return (
-            isRelativeSourceHrefPrefix &&
-            isAbsoluteHref &&
-            doesHrefStartWithSourceHrefPrefix(resolveAbsoluteHrefPath(normalizedHref), normalizedSourceHrefPrefix)
-        );
-    });
+    return {
+        host: '',
+        path: normalizeUrlPathForComparison(trimmedUrl),
+    };
+}
+
+/**
+ * Returns whether one URL points into one reference source prefix.
+ *
+ * @param url - Comparable parts of the link target written in markdown.
+ * @param prefix - Comparable parts of one reference source prefix.
+ * @returns `true` when the URL belongs to the reference.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function isUrlWithinReferencePrefix(url: ComparableUrlParts, prefix: ComparableUrlParts): boolean {
+    if (prefix.host !== '' && prefix.host !== url.host) {
+        return false;
+    }
+
+    if (prefix.path === '') {
+        // Note: A prefix without a path covers the whole host, a prefix without both would cover everything
+        return prefix.host !== '';
+    }
+
+    return url.path === prefix.path || url.path.startsWith(`${prefix.path}/`);
 }
 
 /**
- * Finds the inline reference represented by a markdown link destination.
+ * Builds matchers for references which can also be written as a markdown link or a bare URL.
  *
- * @param references - Inline references available to the markdown renderer.
- * @param href - Markdown link destination.
- * @returns Matching reference or `undefined` when the href is unrelated.
+ * @param references - References available to this markdown render.
+ * @returns Matchers of references declaring at least one usable source prefix.
  *
  * @private utility of `renderMarkdown`
  */
-function findMarkdownInlineReferenceByHref(
+function createMarkdownInlineReferenceHrefMatchers(
     references: ReadonlyArray<MarkdownInlineReference>,
+): ReadonlyArray<MarkdownInlineReferenceHrefMatcher> {
+    return references
+        .map((reference) => ({
+            reference,
+            sourceHrefPrefixes: (reference.sourceHrefPrefixes || [])
+                .map((sourceHrefPrefix) => createComparableUrlParts(sourceHrefPrefix))
+                .filter((sourceHrefPrefix): sourceHrefPrefix is ComparableUrlParts => sourceHrefPrefix !== null),
+        }))
+        .filter((matcher) => matcher.sourceHrefPrefixes.length !== 0);
+}
+
+/**
+ * Finds the reference which owns one link target.
+ *
+ * @param href - Raw link target written in markdown.
+ * @param matchers - Reference matchers of this markdown render.
+ * @returns Matching reference or `null`.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function findMarkdownInlineReferenceForHref(
     href: string,
-): MarkdownInlineReference | undefined {
-    return references.find((reference) => doesMarkdownInlineReferenceMatchHref(reference, href));
+    matchers: ReadonlyArray<MarkdownInlineReferenceHrefMatcher>,
+): MarkdownInlineReference | null {
+    const urlParts = createComparableUrlParts(href);
+
+    if (urlParts === null) {
+        return null;
+    }
+
+    const matcher = matchers.find((candidateMatcher) =>
+        candidateMatcher.sourceHrefPrefixes.some((sourceHrefPrefix) =>
+            isUrlWithinReferencePrefix(urlParts, sourceHrefPrefix),
+        ),
+    );
+
+    return matcher?.reference || null;
 }
 
 /**
@@ -1042,11 +1379,113 @@ function renderMarkdownInlineReferenceMenuOptionHtml(option: MarkdownInlineRefer
 }
 
 /**
- * Replaces known `[[reference]]` tokens with link chips while leaving unknown tokens unchanged.
+ * Replaces known `[[reference]]` tokens with chip placeholders while leaving unknown tokens unchanged.
+ *
+ * @param markdown - Markdown content after code masking.
+ * @param references - References available to this markdown render.
+ * @param createPlaceholder - Renders one matched reference into a placeholder.
+ * @returns Markdown with known reference tokens replaced by placeholders.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function replaceMarkdownInlineReferenceTokens(
+    markdown: string_markdown,
+    references: ReadonlyArray<MarkdownInlineReference>,
+    createPlaceholder: CreateMarkdownInlineReferencePlaceholder,
+): string_markdown {
+    const referenceByKey = createMarkdownInlineReferenceByKey(references);
+
+    if (referenceByKey.size === 0) {
+        return markdown;
+    }
+
+    return markdown.replace(INLINE_REFERENCE_REGEX, (match, rawReference: string) => {
+        const reference = referenceByKey.get(normalizeMarkdownInlineReferenceKey(rawReference));
+
+        return reference ? createPlaceholder(reference) : match;
+    }) as string_markdown;
+}
+
+/**
+ * Replaces markdown links pointing to a known reference with chip placeholders.
+ *
+ * Images keep their original markdown so that pictures served by a reference stay visible.
+ *
+ * @param markdown - Markdown content after code masking.
+ * @param matchers - Reference matchers of this markdown render.
+ * @param createPlaceholder - Renders one matched reference into a placeholder.
+ * @returns Markdown with known reference links replaced by placeholders.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function replaceMarkdownInlineReferenceLinks(
+    markdown: string_markdown,
+    matchers: ReadonlyArray<MarkdownInlineReferenceHrefMatcher>,
+    createPlaceholder: CreateMarkdownInlineReferencePlaceholder,
+): string_markdown {
+    return markdown.replace(MARKDOWN_LINK_REGEX, (match, imageMarker: string, _label: string, rawHref: string) => {
+        if (imageMarker !== '') {
+            return match;
+        }
+
+        const reference = findMarkdownInlineReferenceForHref(rawHref, matchers);
+
+        return reference ? createPlaceholder(reference) : match;
+    }) as string_markdown;
+}
+
+/**
+ * Replaces bare URLs of known references with chip placeholders.
+ *
+ * @param markdown - Markdown content after reference links were replaced.
+ * @param matchers - Reference matchers of this markdown render.
+ * @param createPlaceholder - Renders one matched reference into a placeholder.
+ * @returns Markdown with known reference URLs replaced by placeholders.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function replaceMarkdownInlineReferenceBareUrls(
+    markdown: string_markdown,
+    matchers: ReadonlyArray<MarkdownInlineReferenceHrefMatcher>,
+    createPlaceholder: CreateMarkdownInlineReferencePlaceholder,
+): string_markdown {
+    return markdown.replace(BARE_URL_REGEX, (match, leadingWhitespace: string, rawUrl: string) => {
+        const trailingPunctuation = rawUrl.match(BARE_URL_TRAILING_PUNCTUATION_REGEX)?.[0] || '';
+        const url = rawUrl.slice(0, rawUrl.length - trailingPunctuation.length);
+        const reference = findMarkdownInlineReferenceForHref(url, matchers);
+
+        return reference ? `${leadingWhitespace}${createPlaceholder(reference)}${trailingPunctuation}` : match;
+    }) as string_markdown;
+}
+
+/**
+ * Restores chips which replaced references during the reference passes.
+ *
+ * @param markdown - Markdown containing reference placeholders.
+ * @param renderedChips - Chip HTML indexed by placeholder number.
+ * @returns Markdown with inline references rendered as HTML chips.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function restoreMarkdownInlineReferenceChips(
+    markdown: string_markdown,
+    renderedChips: ReadonlyArray<string>,
+): string_markdown {
+    return markdown.replace(
+        INLINE_REFERENCE_PLACEHOLDER_REGEX,
+        (_match, index) => renderedChips[Number(index)] ?? '',
+    ) as string_markdown;
+}
+
+/**
+ * Replaces known `[[reference]]` tokens, reference links and bare reference URLs with link chips.
+ *
+ * Every matched reference is first replaced by a placeholder so that the rendered chip HTML is
+ * never processed again by a later pass.
  *
  * @param markdown - Markdown content after code masking.
  * @param options - Markdown render options.
- * @returns Markdown with known inline references rendered as HTML anchors.
+ * @returns Markdown with known inline references rendered as HTML chips.
  *
  * @private utility of `renderMarkdown`
  */
@@ -1058,33 +1497,40 @@ function applyMarkdownInlineReferences(markdown: string_markdown, options?: Rend
         return markdown;
     }
 
-    const referenceByKey = createMarkdownInlineReferenceByKey(references);
-    if (referenceByKey.size === 0) {
-        return markdown;
-    }
+    const renderedChips: Array<string> = [];
+    const createPlaceholder: CreateMarkdownInlineReferencePlaceholder = (reference) => {
+        const placeholder = `${INLINE_REFERENCE_PLACEHOLDER_PREFIX}${renderedChips.length}__`;
+        renderedChips.push(renderMarkdownInlineReferenceHtml(reference, className));
 
-    const markdownWithInlineReferenceTokens = markdown.replace(
-        INLINE_REFERENCE_REGEX,
-        (match, rawReference: string) => {
-            const reference = referenceByKey.get(normalizeMarkdownInlineReferenceKey(rawReference));
+        return placeholder;
+    };
 
-            return reference ? renderMarkdownInlineReferenceHtml(reference, className) : match;
-        },
-    );
+    const hrefMatchers = createMarkdownInlineReferenceHrefMatchers(references);
+    let referencedMarkdown = replaceMarkdownInlineReferenceTokens(markdown, references, createPlaceholder);
 
-    return markdownWithInlineReferenceTokens.replace(
-        MARKDOWN_INLINE_REFERENCE_LINK_REGEX,
-        (match, imageMarker: string, _linkLabel: string, rawHref: string) => {
-            if (imageMarker) {
-                return match;
-            }
+    if (hrefMatchers.length !== 0) {
+        referencedMarkdown = replaceMarkdownInlineReferenceLinks(referencedMarkdown, hrefMatchers, createPlaceholder);
+        referencedMarkdown = replaceMarkdownInlineReferenceBareUrls(
+            referencedMarkdown,
+            hrefMatchers,
+            createPlaceholder,
+        );
+    }
 
-            const href = rawHref.replace(/^<|>$/g, '');
-            const reference = findMarkdownInlineReferenceByHref(references, href);
+    const textMatchers = createMarkdownInlineReferenceTextMatchers(references);
+    if (textMatchers.length !== 0) {
+        const { masked: markdownWithMaskedLinksAndUrls, restore: restoreLinksAndUrls } =
+            maskMarkdownLinksAndBareUrls(referencedMarkdown);
+        referencedMarkdown = restoreLinksAndUrls(
+            replaceMarkdownInlineReferenceTextAliases(
+                markdownWithMaskedLinksAndUrls,
+                textMatchers,
+                createPlaceholder,
+            ),
+        );
+    }
 
-            return reference ? renderMarkdownInlineReferenceHtml(reference, className) : match;
-        },
-    ) as string_markdown;
+    return restoreMarkdownInlineReferenceChips(referencedMarkdown, renderedChips);
 }
 
 /**
@@ -1129,7 +1575,7 @@ export function renderMarkdown(markdown: string_markdown, options?: RenderMarkdo
 
     try {
         const normalizedMarkdown = normalizeMarkdownSublists(markdown);
-        const { masked: maskedMarkdown, restore: restoreDetails } = maskDetailsBlocks(normalizedMarkdown, options);
+        const { masked: maskedMarkdown, restore: restoreDetails } = maskDetailsBlocks(normalizedMarkdown);
         const { masked: codeMaskedMarkdown, restore: restoreCode } = maskMarkdownCodeSegments(maskedMarkdown);
         const referencedMarkdown = applyMarkdownInlineReferences(codeMaskedMarkdown, options);
         const inlineReferenceMarkdown = restoreCode(referencedMarkdown);