@promptbook/cli 0.114.0-0 → 0.114.0-10

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

@@ -9,6 +9,7 @@ import type { Converter as ShowdownConverter } from 'showdown';
 import showdown from 'showdown';
 import type { string_html, string_markdown } from '../../../types/string_markdown';
 import { TODO_USE } from '../../../utils/organization/TODO_USE';
+import { $provideServerDomWindow } from './$provideServerDomWindow';
 import { createCitationMarkerRegex, parseCitationMarker } from './parseCitationMarker';
 
 /**
@@ -42,6 +43,7 @@ const MARKDOWN_SANITIZER_ALLOWED_TAGS = [
     'b',
     'blockquote',
     'br',
+    'button',
     'code',
     'del',
     'details',
@@ -155,6 +157,29 @@ const MARKDOWN_SANITIZER_ALLOWED_PROTOCOLS = new Set(['http', 'https', 'mailto',
  */
 const INLINE_REFERENCE_MENU_OPTION_MARKER_ATTRIBUTE = 'data-promptbook-inline-reference-menu-option';
 
+/**
+ * Attribute marking a client action generated for an inline-reference menu.
+ *
+ * @private utility shared with `MarkdownContent`
+ */
+export const MARKDOWN_INLINE_REFERENCE_MENU_ACTION_ATTRIBUTE =
+    'data-promptbook-inline-reference-menu-action';
+
+/**
+ * Attribute identifying the inline reference which owns a client menu action.
+ *
+ * @private utility shared with `MarkdownContent`
+ */
+export const MARKDOWN_INLINE_REFERENCE_MENU_ACTION_REFERENCE_ATTRIBUTE =
+    'data-promptbook-inline-reference-menu-action-reference';
+
+/**
+ * Attribute marking a favicon rendered inside an inline-reference chip.
+ *
+ * @private utility shared with `MarkdownContent`
+ */
+export const MARKDOWN_INLINE_REFERENCE_ICON_ATTRIBUTE = 'data-promptbook-inline-reference-icon';
+
 /**
  * Internal `data-*` attributes that Promptbook injects into rendered markdown and must survive sanitization.
  *
@@ -164,6 +189,9 @@ const MARKDOWN_SANITIZER_ALLOWED_DATA_ATTRIBUTES = new Set([
     'data-citation-footnote',
     'data-chat-progress-marker',
     INLINE_REFERENCE_MENU_OPTION_MARKER_ATTRIBUTE,
+    MARKDOWN_INLINE_REFERENCE_MENU_ACTION_ATTRIBUTE,
+    MARKDOWN_INLINE_REFERENCE_MENU_ACTION_REFERENCE_ATTRIBUTE,
+    MARKDOWN_INLINE_REFERENCE_ICON_ATTRIBUTE,
 ]);
 
 /**
@@ -218,13 +246,6 @@ let browserMarkdownSanitizer: DomPurifyInstance | null = null;
  */
 let serverMarkdownSanitizer: DomPurifyInstance | null = null;
 
-/**
- * Shared JSDOM window backing the server-side DOMPurify instance.
- *
- * @private utility of `renderMarkdown`
- */
-let serverMarkdownSanitizerWindow: DomPurifyWindowLike | null = null;
-
 /**
  * Pattern matching CODE FENCE.
  */
@@ -272,6 +293,65 @@ const DETAILS_PLACEHOLDER_WRAPPED_REGEX = new RegExp(`<p>\\s*(${DETAILS_PLACEHOL
  */
 const INLINE_REFERENCE_REGEX = /\[\[([^\]\r\n]+?)\]\]/g;
 
+/**
+ * Prefix for INLINE REFERENCE PLACEHOLDER.
+ *
+ * @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 ABSOLUTE_URL_REGEX = /^[a-z][a-z0-9+.-]*:\/\/([^/?#]*)(.*)$/i;
+
 /**
  * Markdown patterns that are strong enough to identify content as markdown.
  */
@@ -329,6 +409,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.
      */
@@ -339,17 +427,49 @@ export type MarkdownInlineReference = {
      */
     readonly href: string;
 
+    /**
+     * Optional URL prefixes which also identify this reference in the authored markdown.
+     *
+     * 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>;
+
     /**
      * Optional hover title for the rendered reference.
      */
     readonly title?: string;
 
+    /**
+     * Optional favicon and text fallback rendered before the reference label.
+     */
+    readonly icon?: MarkdownInlineReferenceIcon;
+
     /**
      * Optional expandable menu shown when the reference chip is clicked.
      */
     readonly menu?: MarkdownInlineReferenceMenu;
 };
 
+/**
+ * Visual identity rendered inside one markdown inline-reference chip.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type MarkdownInlineReferenceIcon = {
+    /**
+     * Optional image URL. The fallback remains visible when the image is unavailable.
+     */
+    readonly src?: string | null;
+
+    /**
+     * Short text rendered when the image is missing or broken.
+     */
+    readonly fallbackText: string;
+};
+
 /**
  * Status displayed alongside an expandable markdown inline reference.
  *
@@ -387,6 +507,28 @@ export type MarkdownInlineReferenceMenuOption = {
      * Optional hover text for the option.
      */
     readonly title?: string;
+
+    /**
+     * Optional client action rendered as a button instead of a link.
+     */
+    readonly action?: MarkdownInlineReferenceMenuAction;
+};
+
+/**
+ * Client-side action exposed by an expandable markdown inline-reference menu.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type MarkdownInlineReferenceMenuAction = {
+    /**
+     * Stable identifier unique within the owning reference menu.
+     */
+    readonly id: string;
+
+    /**
+     * Callback invoked when the menu button is selected.
+     */
+    readonly onSelect: () => void | Promise<void>;
 };
 
 /**
@@ -414,6 +556,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.
  */
@@ -528,21 +678,6 @@ function createMarkdownSanitizer(sanitizerWindow: DomPurifyWindowLike): DomPurif
     return markdownSanitizer;
 }
 
-/**
- * Lazily creates the JSDOM window used by server-side markdown sanitization.
- *
- * @private utility of `renderMarkdown`
- */
-function getServerMarkdownSanitizerWindow(): DomPurifyWindowLike {
-    if (!serverMarkdownSanitizerWindow) {
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
-        const { JSDOM } = require('jsdom') as typeof import('jsdom');
-        serverMarkdownSanitizerWindow = new JSDOM('').window as unknown as DomPurifyWindowLike;
-    }
-
-    return serverMarkdownSanitizerWindow;
-}
-
 /**
  * Returns the shared DOMPurify instance appropriate for the current runtime.
  *
@@ -555,7 +690,7 @@ function getMarkdownSanitizer(): DomPurifyInstance {
         return browserMarkdownSanitizer;
     }
 
-    serverMarkdownSanitizer ??= createMarkdownSanitizer(getServerMarkdownSanitizerWindow());
+    serverMarkdownSanitizer ??= createMarkdownSanitizer($provideServerDomWindow());
 
     return serverMarkdownSanitizer;
 }
@@ -756,6 +891,44 @@ 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.
@@ -860,6 +1033,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.
  *
@@ -874,17 +1059,326 @@ 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;
 }
 
+/**
+ * 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 value - Literal text to match.
+ * @returns Regular-expression-safe text.
+ *
+ * @private utility of `renderMarkdown`
+ */
+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);
+            }
+        }
+    }
+
+    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),
+        );
+}
+
+/**
+ * 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');
+}
+
+/**
+ * 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 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 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 decodeURIComponent(value);
+    } catch {
+        return value;
+    }
+}
+
+/**
+ * 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.
+ *
+ * @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 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 createComparableUrlParts(url: string): ComparableUrlParts | null {
+    const trimmedUrl = url
+        .trim()
+        .replace(/^<([\s\S]*)>$/, '$1')
+        .trim();
+
+    if (trimmedUrl === '') {
+        return null;
+    }
+
+    const absoluteUrlMatch = trimmedUrl.match(ABSOLUTE_URL_REGEX);
+    if (absoluteUrlMatch) {
+        return {
+            host: absoluteUrlMatch[1]!.toLowerCase(),
+            path: normalizeUrlPathForComparison(absoluteUrlMatch[2] || ''),
+        };
+    }
+
+    if (!trimmedUrl.startsWith('/')) {
+        return null;
+    }
+
+    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}/`);
+}
+
+/**
+ * Builds matchers for references which can also be written as a markdown link or a bare URL.
+ *
+ * @param references - References available to this markdown render.
+ * @returns Matchers of references declaring at least one usable source prefix.
+ *
+ * @private utility of `renderMarkdown`
+ */
+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,
+    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;
+}
+
 /**
  * Renders one inline reference as raw HTML that is sanitized by the shared markdown sanitizer.
  *
@@ -899,12 +1393,50 @@ function renderMarkdownInlineReferenceHtml(reference: MarkdownInlineReference, c
         return renderMarkdownInlineReferenceMenuHtml(reference, className);
     }
 
-    const escapedClassName = escapeHtml(className);
+    const escapedClassName = escapeHtml(createMarkdownInlineReferenceClassName(reference, className));
     const escapedHref = escapeHtml(reference.href);
     const escapedLabel = escapeHtml(reference.label);
     const escapedTitle = escapeHtml(reference.title || reference.label);
+    const iconHtml = renderMarkdownInlineReferenceIconHtml(reference.icon);
+
+    return `<a class="${escapedClassName}" href="${escapedHref}" title="${escapedTitle}">${iconHtml}<span>${escapedLabel}</span></a>`;
+}
+
+/**
+ * Adds the icon marker class only to references which provide icon metadata.
+ *
+ * @param reference - Inline reference being rendered.
+ * @param className - Base chip class name.
+ * @returns Complete class name for the rendered chip.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function createMarkdownInlineReferenceClassName(reference: MarkdownInlineReference, className: string): string {
+    return reference.icon ? `${className} inlineReferenceChip--with-icon` : className;
+}
+
+/**
+ * Renders one inline-reference favicon with a text fallback.
+ *
+ * @param icon - Optional icon metadata.
+ * @returns Safe icon markup, or an empty string when no icon is configured.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function renderMarkdownInlineReferenceIconHtml(icon: MarkdownInlineReferenceIcon | undefined): string {
+    if (!icon) {
+        return '';
+    }
 
-    return `<a class="${escapedClassName}" href="${escapedHref}" title="${escapedTitle}">${escapedLabel}</a>`;
+    const escapedFallbackText = escapeHtml(icon.fallbackText);
+    const fallbackHtml = `<span class="inlineReferenceIconFallback">${escapedFallbackText}</span>`;
+
+    if (!icon.src) {
+        return `<span class="inlineReferenceIcon" aria-hidden="true">${fallbackHtml}</span>`;
+    }
+
+    const escapedSrc = escapeHtml(icon.src);
+    return `<span class="inlineReferenceIcon" aria-hidden="true">${fallbackHtml}<img ${MARKDOWN_INLINE_REFERENCE_ICON_ATTRIBUTE} src="${escapedSrc}" alt=""></span>`;
 }
 
 /**
@@ -923,30 +1455,44 @@ function renderMarkdownInlineReferenceMenuHtml(reference: MarkdownInlineReferenc
         return renderMarkdownInlineReferenceHtml({ ...reference, menu: undefined }, className);
     }
 
-    const escapedClassName = escapeHtml(className);
+    const escapedClassName = escapeHtml(createMarkdownInlineReferenceClassName(reference, className));
     const escapedLabel = escapeHtml(reference.label);
     const escapedTitle = escapeHtml(reference.title || reference.label);
     const escapedStatusLabel = escapeHtml(menu.status.label);
     const statusClassName = menu.status.isActive
         ? 'inlineReferenceMenuStatus inlineReferenceMenuStatus--active'
-        : 'inlineReferenceMenuStatus';
-    const optionsHtml = menu.options.map((option) => renderMarkdownInlineReferenceMenuOptionHtml(option)).join('');
+        : 'inlineReferenceMenuStatus inlineReferenceMenuStatus--inactive';
+    const iconHtml = renderMarkdownInlineReferenceIconHtml(reference.icon);
+    const optionsHtml = menu.options
+        .map((option) => renderMarkdownInlineReferenceMenuOptionHtml(reference, option))
+        .join('');
 
-    return `<details class="${escapedClassName}" title="${escapedTitle}"><summary><span>${escapedLabel}</span><span class="${statusClassName}" title="${escapedStatusLabel}"></span></summary><div><span class="${statusClassName}">${escapedStatusLabel}</span>${optionsHtml}</div></details>`;
+    return `<details class="${escapedClassName}" title="${escapedTitle}"><summary>${iconHtml}<span>${escapedLabel}</span><span class="${statusClassName}" title="${escapedStatusLabel}"></span></summary><div><span class="${statusClassName}">${escapedStatusLabel}</span>${optionsHtml}</div></details>`;
 }
 
 /**
  * Renders one option in an expandable markdown inline reference menu.
  *
+ * @param reference - Inline reference which owns the option.
  * @param option - Menu option definition.
  * @returns HTML anchor or disabled label markup.
  *
  * @private utility of `renderMarkdown`
  */
-function renderMarkdownInlineReferenceMenuOptionHtml(option: MarkdownInlineReferenceMenuOption): string {
+function renderMarkdownInlineReferenceMenuOptionHtml(
+    reference: MarkdownInlineReference,
+    option: MarkdownInlineReferenceMenuOption,
+): string {
     const escapedLabel = escapeHtml(option.label);
     const escapedTitle = escapeHtml(option.title || option.label);
 
+    if (option.action) {
+        const escapedActionId = escapeHtml(option.action.id);
+        const escapedReference = escapeHtml(reference.reference);
+
+        return `<button type="button" ${MARKDOWN_INLINE_REFERENCE_MENU_ACTION_ATTRIBUTE}="${escapedActionId}" ${MARKDOWN_INLINE_REFERENCE_MENU_ACTION_REFERENCE_ATTRIBUTE}="${escapedReference}" class="inlineReferenceMenuOption" title="${escapedTitle}">${escapedLabel}</button>`;
+    }
+
     if (option.href === null) {
         return `<span class="inlineReferenceMenuOption inlineReferenceMenuOption--disabled" title="${escapedTitle}">${escapedLabel}</span>`;
     }
@@ -956,11 +1502,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`
  */
@@ -972,16 +1620,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));
+
+        return placeholder;
+    };
+
+    const hrefMatchers = createMarkdownInlineReferenceHrefMatchers(references);
+    let referencedMarkdown = replaceMarkdownInlineReferenceTokens(markdown, references, createPlaceholder);
+
+    if (hrefMatchers.length !== 0) {
+        referencedMarkdown = replaceMarkdownInlineReferenceLinks(referencedMarkdown, hrefMatchers, createPlaceholder);
+        referencedMarkdown = replaceMarkdownInlineReferenceBareUrls(
+            referencedMarkdown,
+            hrefMatchers,
+            createPlaceholder,
+        );
     }
 
-    return markdown.replace(INLINE_REFERENCE_REGEX, (match, rawReference: string) => {
-        const reference = referenceByKey.get(normalizeMarkdownInlineReferenceKey(rawReference));
+    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);
 }
 
 /**