@flamingo-stack/openframe-frontend-core 0.0.744 → 0.0.746

package/src/components/ui/markdown-link-command.tsx

@@ -0,0 +1,252 @@
+'use client';
+
+import type { ICommand, TextAreaTextApi, TextRange } from '@uiw/react-md-editor';
+import { type ReactNode, useEffect, useId, useMemo, useState } from 'react';
+import {
+  type AuthoredLinkRel,
+  findMarkdownLinkAt,
+  formatMarkdownLink,
+  type MarkdownLinkFields,
+} from '../../utils/markdown-link';
+import { Button } from './button';
+import { Input } from './input';
+import { ModalV2, ModalV2Footer, ModalV2Header, ModalV2Title } from './modal-v2';
+import { TabSelector } from './tab-selector';
+
+type LinkRelChoice = 'follow' | AuthoredLinkRel;
+
+/** What each choice tells search engines, in Google's own terms (Search Central, "Qualify your outbound links"). */
+const LINK_REL_CHOICES: { id: LinkRelChoice; label: string; hint: string }[] = [
+  { id: 'follow', label: 'Follow', hint: 'Search engines follow this link. This is the default.' },
+  {
+    id: 'nofollow',
+    label: 'Nofollow',
+    hint: 'Search engines are asked not to follow this link (rel="nofollow").',
+  },
+  {
+    id: 'sponsored',
+    label: 'Sponsored',
+    hint: 'For ads, paid placements and sponsorships (rel="sponsored").',
+  },
+  { id: 'ugc', label: 'UGC', hint: 'For links in content written by users, such as comments (rel="ugc").' },
+];
+
+const LINK_REL_ITEMS = LINK_REL_CHOICES.map(({ id, label }) => ({ id, label }));
+
+/** The choice a link's `rel` shows: the most specific value it carries (sponsored, then ugc, then nofollow). */
+function choiceOf(rel: readonly AuthoredLinkRel[]): LinkRelChoice {
+  if (rel.includes('sponsored')) return 'sponsored';
+  if (rel.includes('ugc')) return 'ugc';
+  if (rel.includes('nofollow')) return 'nofollow';
+  return 'follow';
+}
+
+export interface MarkdownLinkDialogProps {
+  isOpen: boolean;
+  /** The link being edited, or the selection a new link starts from. */
+  initial: MarkdownLinkFields;
+  /** True when `initial` is a link already in the text: the dialog then offers to remove it. */
+  editing: boolean;
+  onSubmit: (link: MarkdownLinkFields) => void;
+  /** Replaces the link with its text. */
+  onRemove: () => void;
+  onClose: () => void;
+}
+
+/**
+ * The link dialog of the markdown editors: the link's text, its address, and what it tells search
+ * engines: Follow (the default), Nofollow, Sponsored or UGC. Any choice but Follow writes the link
+ * as `<a rel="…">`. A link that carries several values (`rel="ugc nofollow"`) keeps them all until
+ * the choice is changed.
+ */
+export function MarkdownLinkDialog({ isOpen, initial, editing, onSubmit, onRemove, onClose }: MarkdownLinkDialogProps) {
+  const formId = useId();
+  const [text, setText] = useState(initial.text);
+  const [url, setUrl] = useState(initial.url);
+  const [rel, setRel] = useState(initial.rel);
+
+  // Re-seed while rendering when the dialog opens on another link (the modal stays mounted).
+  const [seededWith, setSeededWith] = useState({ isOpen, initial });
+  if (seededWith.isOpen !== isOpen || seededWith.initial !== initial) {
+    setSeededWith({ isOpen, initial });
+    if (isOpen) {
+      setText(initial.text);
+      setUrl(initial.url);
+      setRel(initial.rel);
+    }
+  }
+
+  const choice = choiceOf(rel);
+  const trimmedUrl = url.trim();
+  const submit = () => {
+    if (!trimmedUrl) return;
+    onSubmit({ text: text.trim(), url: trimmedUrl, rel });
+  };
+
+  return (
+    <ModalV2 isOpen={isOpen} onClose={onClose} className="text-left md:max-w-[560px]">
+      <ModalV2Header>
+        <ModalV2Title>{editing ? 'Edit link' : 'Add link'}</ModalV2Title>
+      </ModalV2Header>
+
+      <form
+        id={formId}
+        className="flex w-full flex-col gap-[var(--spacing-system-l)]"
+        onSubmit={event => {
+          event.preventDefault();
+          submit();
+        }}
+      >
+        <Input label="Text" value={text} onChange={event => setText(event.target.value)} placeholder="Link text" />
+        <Input
+          label="URL"
+          value={url}
+          onChange={event => setUrl(event.target.value)}
+          placeholder="https://"
+          autoFocus
+          inputMode="url"
+        />
+        <div className="flex flex-col gap-[var(--spacing-system-xsf)]">
+          <TabSelector
+            label="Search engines"
+            value={choice}
+            onValueChange={value => {
+              const next = LINK_REL_CHOICES.find(option => option.id === value)?.id ?? 'follow';
+              setRel(next === 'follow' ? [] : [next]);
+            }}
+            items={LINK_REL_ITEMS}
+            variant="secondary"
+          />
+          <p className="text-ods-text-secondary text-h6">
+            {LINK_REL_CHOICES.find(option => option.id === choice)?.hint}
+          </p>
+        </div>
+      </form>
+
+      <ModalV2Footer>
+        {editing ? (
+          <Button type="button" variant="outline" onClick={onRemove} className="flex-1">
+            Remove link
+          </Button>
+        ) : (
+          <Button type="button" variant="outline" onClick={onClose} className="flex-1">
+            Cancel
+          </Button>
+        )}
+        {/* A submit button of the form (by `form`), so Enter in either field saves the link. */}
+        <Button type="submit" form={formId} variant="accent" disabled={!trimmedUrl} className="flex-1">
+          {editing ? 'Save' : 'Add link'}
+        </Button>
+      </ModalV2Footer>
+    </ModalV2>
+  );
+}
+
+interface PendingLink {
+  api: TextAreaTextApi;
+  range: TextRange;
+  initial: MarkdownLinkFields;
+  editing: boolean;
+}
+
+const EMPTY_LINK: MarkdownLinkFields = { text: '', url: '', rel: [] };
+
+const LOOKS_LIKE_URL = /^(?:https?:\/\/|www\.|mailto:|\/|#)\S*$/i;
+
+function initialFieldsFromSelection(selectedText: string): MarkdownLinkFields {
+  const selected = selectedText.trim();
+  return LOOKS_LIKE_URL.test(selected) ? { text: '', url: selected, rel: [] } : { text: selected, url: '', rel: [] };
+}
+
+export interface MarkdownLinkCommand {
+  /**
+   * The editor's toolbar: the vendor's commands with its `link` command replaced by this dialog.
+   * `undefined` until the vendor's commands have loaded (the editor then shows its own defaults).
+   */
+  commands: ICommand[] | undefined;
+  /** The dialog. Render it beside the editor. */
+  linkDialog: ReactNode;
+}
+
+/**
+ * The link command every markdown editor uses: the toolbar's link button and Ctrl/Cmd+L open
+ * {@link MarkdownLinkDialog} on the link under the caret (markdown or HTML), or on the selection
+ * for a new link, and write the result back as one undoable edit.
+ */
+export function useMarkdownLinkCommand(): MarkdownLinkCommand {
+  const [vendorCommands, setVendorCommands] = useState<ICommand[] | undefined>(undefined);
+  const [pending, setPending] = useState<PendingLink | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const mod = await import('@uiw/react-md-editor');
+        if (!cancelled && mod.commands?.getCommands) setVendorCommands(mod.commands.getCommands());
+      } catch (error) {
+        // Chunk load failure: the editor keeps its own default toolbar.
+        console.error('Failed to load markdown editor toolbar commands:', error);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const commands = useMemo(() => {
+    if (!vendorCommands) return undefined;
+    return vendorCommands.map(command => {
+      if (command.name !== 'link') return command;
+      const linkCommand: ICommand = {
+        name: 'link',
+        keyCommand: 'link',
+        shortcuts: 'ctrlcmd+l',
+        buttonProps: { 'aria-label': 'Add or edit a link (ctrl + l)', title: 'Add or edit a link (ctrl + l)' },
+        icon: command.icon,
+        execute: (state, api) => {
+          const existing = findMarkdownLinkAt(state.text, state.selection.start, state.selection.end);
+          setPending(
+            existing
+              ? {
+                  api,
+                  range: { start: existing.start, end: existing.end },
+                  initial: { text: existing.text, url: existing.url, rel: existing.rel },
+                  editing: true,
+                }
+              : {
+                  api,
+                  range: state.selection,
+                  initial: initialFieldsFromSelection(state.selectedText),
+                  editing: false,
+                },
+          );
+        },
+      };
+      return linkCommand;
+    });
+  }, [vendorCommands]);
+
+  // Writes over the link's range as ONE edit through the editor's own text API, so Undo restores it.
+  const write = (current: PendingLink, text: string) => {
+    setPending(null);
+    current.api.setSelectionRange(current.range);
+    current.api.replaceSelection(text);
+  };
+
+  const linkDialog = (
+    <MarkdownLinkDialog
+      isOpen={pending !== null}
+      initial={pending?.initial ?? EMPTY_LINK}
+      editing={pending?.editing ?? false}
+      onSubmit={link => {
+        if (pending) write(pending, formatMarkdownLink(link));
+      }}
+      onRemove={() => {
+        if (pending) write(pending, pending.initial.text);
+      }}
+      onClose={() => setPending(null)}
+    />
+  );
+
+  return { commands, linkDialog };
+}

package/src/components/unified-filter-logic.tsx

@@ -397,7 +397,7 @@ export function useUnifiedFiltering(config: FilterConfig) {
   };
 }
 
-import { formatClassification, formatPricingModel } from '../utils/format-text-stub';
+import { formatClassification, formatPricingModel } from '../utils/format';
 
 // Helper functions for filter labels
 function getFilterLabel(filterKey: string): string {

package/src/components/vendor-tag.tsx

@@ -1,13 +1,11 @@
 'use client';
 
-import { Boxes, Code, Database, DollarSign, Hand, Plug, ShieldCheck, Sparkles } from 'lucide-react';
+import { Boxes, Database, DollarSign, Hand, Plug, ShieldCheck, Sparkles } from 'lucide-react';
+import { createElement, type ReactNode } from 'react';
 import { cn } from '../utils/cn';
-import {
-  OPENFRAME_CLASSIFICATIONS,
-  isOpenFrameClassification,
-  type OpenFrameClassification,
-} from '../utils/vendor-classification';
-import { OpenframeLogoIcon } from './icons-v2-generated/logos/openframe-logo-icon';
+import { formatClassification } from '../utils/format';
+import { type VendorClassificationIconConfig, vendorClassificationCopy } from '../utils/vendor-classification';
+import { resolveIcon } from './chat/utils/icon-library';
 
 export interface VendorTagProps {
   type:
@@ -36,12 +34,69 @@ export interface VendorTagProps {
   accentColor?: string;
 }
 
-/** An OpenFrame classification: the OpenFrame mark and its one word ("Selected", "Connect"). */
-function openFrameTag(classification: OpenFrameClassification, text?: string) {
+const TONE_CLASS: Readonly<Record<VendorClassificationIconConfig['tone'], string>> = {
+  accent: 'text-ods-text-on-accent',
+  neutral: 'text-ods-text-secondary',
+  warning: 'text-ods-warning',
+};
+
+/**
+ * A classification's icon, from its config (`VENDOR_CLASSIFICATION_COPY[value].icon`): the
+ * icon is resolved by NAME through the shared resolver, never imported here. A license icon
+ * sits on a small tile (the accent tile for an `accent` tone); an OpenFrame mark and a
+ * lifecycle icon are drawn bare in their tone. A value with no icon draws nothing.
+ */
+export function VendorClassificationIcon({
+  classification,
+  accentColor,
+  className,
+}: {
+  classification: string;
+  /** The accent tile's colour, for a host that tints its hover accent (a vendor card). */
+  accentColor?: string;
+  className?: string;
+}) {
+  const copy = vendorClassificationCopy(classification);
+  if (!copy?.icon) return null;
+  // The resolver returns one component per name, loaded on demand (drawn through `createElement`, as `NamedIcon` does).
+  const icon = resolveIcon(copy.icon.name);
+  if (copy.group !== 'license') {
+    const bareClass = copy.icon.tone === 'accent' ? 'text-ods-accent' : TONE_CLASS[copy.icon.tone];
+    return createElement(icon, {
+      size: copy.group === 'openframe' ? 16 : 12,
+      className: cn('shrink-0', bareClass, className),
+    });
+  }
+  const accent = copy.icon.tone === 'accent';
+  return (
+    <div
+      className={cn(
+        'flex h-4 w-4 flex-shrink-0 items-center justify-center rounded-sm',
+        accent ? 'bg-ods-accent' : 'bg-ods-border',
+        className,
+      )}
+      style={accent && accentColor ? { backgroundColor: accentColor } : undefined}
+    >
+      {createElement(icon, { size: 10, className: TONE_CLASS[copy.icon.tone] })}
+    </div>
+  );
+}
+
+/**
+ * A classification tag, derived from the value the server sends and its config: the label
+ * (an OpenFrame value's one word), the configured icon, and the warning text colour for a
+ * lifecycle value. Any other value is its title-cased label with no icon.
+ */
+function classificationTag(
+  value: string,
+  text?: string,
+  accentColor?: string,
+): { text: string; icon: ReactNode; textColor?: string } {
+  const copy = vendorClassificationCopy(value);
   return {
-    text: text || OPENFRAME_CLASSIFICATIONS[classification].word,
-    textColor: undefined,
-    icon: <OpenframeLogoIcon secondaryColor="currentColor" color="currentColor" className="h-4 w-4 text-ods-accent" />,
+    text: text || (copy?.group === 'openframe' ? copy.word : undefined) || copy?.label || formatClassification(value),
+    textColor: copy?.group === 'lifecycle' ? 'text-ods-warning' : undefined,
+    icon: <VendorClassificationIcon classification={value} accentColor={accentColor} />,
   };
 }
 
@@ -53,7 +108,7 @@ export function VendorTag({ type, text, className = '', hidden = false, size = '
   );
 
   // Get display text and styling based on type
-  const getTagContent = () => {
+  const getTagContent = (): { text: string; icon: ReactNode; textColor?: string } => {
     switch (type) {
       case 'placeholder':
         return {
@@ -86,26 +141,9 @@ export function VendorTag({ type, text, className = '', hidden = false, size = '
           ),
         };
       case 'open-source':
-        return {
-          text: text || 'Open Source',
-          icon: (
-            <div
-              className="flex h-4 w-4 flex-shrink-0 items-center justify-center rounded-sm bg-ods-accent"
-              style={accentColor ? { backgroundColor: accentColor } : undefined}
-            >
-              <Code width={10} height={10} className="text-ods-text-on-accent" />
-            </div>
-          ),
-        };
+        return classificationTag('open_source', text, accentColor);
       case 'commercial':
-        return {
-          text: text || 'Commercial Vendor',
-          icon: (
-            <div className="flex h-4 w-4 flex-shrink-0 items-center justify-center rounded-sm bg-ods-border">
-              <DollarSign width={10} height={10} className="text-ods-text-secondary" />
-            </div>
-          ),
-        };
+        return classificationTag('commercial', text);
       // platform-capability tags — same neutral icon-box chrome as 'commercial'
       case 'api':
         return {
@@ -188,46 +226,12 @@ export function VendorTag({ type, text, className = '', hidden = false, size = '
             </div>
           ),
         };
-      case 'classification': {
-        // Handle specific classification types based on the text value
-        const classificationType = text?.toLowerCase();
-
-        if (classificationType === 'open_source') {
-          return {
-            text: 'Open Source',
-            icon: (
-              <div className="flex h-4 w-4 flex-shrink-0 items-center justify-center rounded-sm bg-ods-accent">
-                <Code width={10} height={10} className="text-ods-text-on-accent" />
-              </div>
-            ),
-          };
-        } else if (classificationType === 'commercial') {
-          return {
-            text: 'Commercial Vendor',
-            icon: (
-              <div className="flex h-4 w-4 flex-shrink-0 items-center justify-center rounded-sm bg-ods-border">
-                <DollarSign width={10} height={10} className="text-ods-text-secondary" />
-              </div>
-            ),
-          };
-        } else if (isOpenFrameClassification(classificationType)) {
-          return openFrameTag(classificationType);
-        } else {
-          // Fallback for unknown classification types
-          return {
-            text: text || 'Classification',
-            icon: (
-              <div className="flex h-4 w-4 flex-shrink-0 items-center justify-center rounded-sm bg-ods-accent">
-                <span className="text-[8px] font-bold text-ods-text-on-accent">C</span>
-              </div>
-            ),
-          };
-        }
-      }
+      case 'classification':
+        return classificationTag((text ?? '').toLowerCase(), undefined, accentColor);
       case 'openframe_selected':
       case 'openframe_connect':
       case 'openframe_shipped':
-        return openFrameTag(type, text);
+        return classificationTag(type, text);
       default:
         return {
           text: text || type,

package/src/utils/format.ts

@@ -3,7 +3,7 @@
  */
 
 import type { ProgramInstant } from './program-instant';
-import { OPENFRAME_CLASSIFICATIONS, isOpenFrameClassification } from './vendor-classification';
+import { vendorClassificationCopy } from './vendor-classification';
 
 /**
  * Format a date to a human-readable string
@@ -941,8 +941,7 @@ export function stripHtml(html: string): string {
  * curated mapping.
  */
 export function formatClassification(classification: string): string {
-  if (isOpenFrameClassification(classification)) return OPENFRAME_CLASSIFICATIONS[classification].label;
-  return formatUnderscoreText(classification);
+  return vendorClassificationCopy(classification)?.label ?? formatUnderscoreText(classification);
 }
 
 /**

package/src/utils/index.ts

@@ -21,13 +21,15 @@ export * from './ai-providers';
 export * from './model-token-rates';
 export { TRIAL_TERMS, trialLabels, trialLengthLabel } from './trial';
 export {
-  VENDOR_CLASSIFICATIONS,
-  OPENFRAME_CLASSIFICATIONS,
-  isVendorClassification,
+  VENDOR_CLASSIFICATION_COPY,
+  vendorClassificationCopy,
+  vendorClassificationGroup,
+  compareVendorClassifications,
   isOpenFrameClassification,
   type VendorClassificationValue,
-  type OpenFrameClassification,
-  type OpenFrameClassificationCopy,
+  type VendorClassificationGroup,
+  type VendorClassificationCopy,
+  type VendorClassificationIconConfig,
 } from './vendor-classification';
 // SVG path constants — re-exported here (server-safe) because icons-v2 has "use client"
 export { PLAY_ICON_PATH } from '../components/icons-v2-generated/media-playback/play-icon';
@@ -424,6 +426,7 @@ export * from './doc-path-utils';
 export * from './doc-tree-nav';
 export * from './tree-builder';
 export * from './markdown-heading-id';
+export * from './markdown-link';
 export * from './markdown-section-extractor';
 export * from './markdown-to-plain';
 export * from './embed-url-converters';

package/src/utils/markdown-link.ts

@@ -0,0 +1,148 @@
+/**
+ * One link format for the markdown editors and one `rel` rule for the renderers.
+ *
+ * A FOLLOWED link is written as markdown, `[text](url)`, exactly as the editors always wrote it.
+ * A link with an authored `rel` (nofollow, sponsored or ugc, the values Google reads) is written as
+ * an HTML anchor, `<a href="url" rel="sponsored">text</a>`: markdown has no attribute syntax, and
+ * an HTML anchor is what stored content already uses for links that carry attributes (the
+ * sanitizer keeps `rel` on `a`). Reading back accepts both forms, so a link can be switched either
+ * way. Nothing is rewritten unless an editor changes a link.
+ *
+ * Server-safe: no React, no DOM.
+ */
+
+/** The `rel` tokens an author may set on a link. Search engines read these; nothing else is kept. */
+export const AUTHORED_LINK_REL_TOKENS = ['nofollow', 'ugc', 'sponsored'] as const;
+
+export type AuthoredLinkRel = (typeof AUTHORED_LINK_REL_TOKENS)[number];
+
+/** What a renderer adds to every link that opens in a new tab. */
+const NEW_TAB_REL = 'noopener noreferrer';
+
+/** The authored SEO tokens in a `rel` value, in their canonical order. */
+export function authoredRelTokens(rel: string | readonly string[] | null | undefined): AuthoredLinkRel[] {
+  if (!rel) return [];
+  const given = new Set(
+    (typeof rel === 'string' ? rel.split(/\s+/) : rel).map(token => token.trim().toLowerCase()).filter(Boolean),
+  );
+  return AUTHORED_LINK_REL_TOKENS.filter(token => given.has(token));
+}
+
+/** Whether an authored `rel` asks search engines not to follow the link. */
+export function isNofollowRel(rel: string | readonly string[] | null | undefined): boolean {
+  return authoredRelTokens(rel).includes('nofollow');
+}
+
+/**
+ * The `rel` a renderer writes for a link: the author's SEO tokens, plus `noopener noreferrer` when
+ * the link opens in a new tab. `undefined` when there is nothing to write.
+ */
+export function renderedLinkRel(
+  authoredRel: string | readonly string[] | null | undefined,
+  opensInNewTab: boolean,
+): string | undefined {
+  const tokens: string[] = authoredRelTokens(authoredRel);
+  if (opensInNewTab) tokens.push(NEW_TAB_REL);
+  return tokens.length > 0 ? tokens.join(' ') : undefined;
+}
+
+/** A link as the editor's dialog edits it. */
+export interface MarkdownLinkFields {
+  text: string;
+  url: string;
+  /** The authored `rel` values. Empty = a followed link. */
+  rel: AuthoredLinkRel[];
+}
+
+/** A link found in the editor's text, with the range it occupies. */
+export interface MarkdownLinkMatch extends MarkdownLinkFields {
+  start: number;
+  end: number;
+}
+
+// `[text](url)` or `[text](url "title")`, never an image (`![…]`). The text may hold escaped brackets.
+const MARKDOWN_LINK_RE = /(?<!!)\[((?:\\.|[^\]\\])*)\]\(\s*<?([^\s)>]*)>?(?:\s+"[^"]*")?\s*\)/g;
+// One HTML anchor, attributes and text. Nested anchors are not valid HTML, so the first `</a>` ends it.
+const HTML_LINK_RE = /<a\s([^>]*)>([\s\S]*?)<\/a\s*>/gi;
+
+function htmlAttribute(attributes: string, name: string): string | null {
+  const match = new RegExp(`(?:^|\\s)${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s"'>]+))`, 'i').exec(attributes);
+  if (!match) return null;
+  return match[1] ?? match[2] ?? match[3] ?? '';
+}
+
+function decodeHtmlEntities(value: string): string {
+  return value
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&');
+}
+
+function escapeHtmlAttribute(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+function escapeHtmlText(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+/** Brackets end the link text and `<` would open raw HTML (CommonMark), so all three are escaped. */
+function escapeMarkdownLinkText(value: string): string {
+  return value.replace(/([\\[\]<])/g, '\\$1');
+}
+
+function unescapeMarkdownLinkText(value: string): string {
+  return value.replace(/\\([\\[\]<])/g, '$1');
+}
+
+/** A URL inside `(…)` breaks on whitespace and unbalanced parentheses; percent-encode them. */
+function encodeMarkdownUrl(url: string): string {
+  return url.replace(/\s/g, match => encodeURIComponent(match)).replace(/[()]/g, match => encodeURIComponent(match));
+}
+
+/**
+ * The link the selection `[selectionStart, selectionEnd]` is in or on, if any: a markdown link or an
+ * HTML anchor that contains the whole selection (a caret counts when it touches the link).
+ */
+export function findMarkdownLinkAt(
+  text: string,
+  selectionStart: number,
+  selectionEnd: number = selectionStart,
+): MarkdownLinkMatch | null {
+  const from = Math.min(selectionStart, selectionEnd);
+  const to = Math.max(selectionStart, selectionEnd);
+  const contains = (start: number, end: number) => start <= from && to <= end;
+
+  for (const match of text.matchAll(HTML_LINK_RE)) {
+    const start = match.index ?? 0;
+    const end = start + match[0].length;
+    if (!contains(start, end)) continue;
+    const attributes = match[1] ?? '';
+    return {
+      start,
+      end,
+      text: decodeHtmlEntities(match[2] ?? ''),
+      url: decodeHtmlEntities(htmlAttribute(attributes, 'href') ?? ''),
+      rel: authoredRelTokens(htmlAttribute(attributes, 'rel')),
+    };
+  }
+  for (const match of text.matchAll(MARKDOWN_LINK_RE)) {
+    const start = match.index ?? 0;
+    const end = start + match[0].length;
+    if (!contains(start, end)) continue;
+    return { start, end, text: unescapeMarkdownLinkText(match[1] ?? ''), url: match[2] ?? '', rel: [] };
+  }
+  return null;
+}
+
+/** The text that writes a link: markdown when followed, an HTML anchor when it carries a `rel`. */
+export function formatMarkdownLink({ text, url, rel }: MarkdownLinkFields): string {
+  const label = text.length > 0 ? text : url;
+  const tokens = authoredRelTokens(rel);
+  if (tokens.length > 0) {
+    return `<a href="${escapeHtmlAttribute(url)}" rel="${tokens.join(' ')}">${escapeHtmlText(label)}</a>`;
+  }
+  return `[${escapeMarkdownLinkText(label)}](${encodeMarkdownUrl(url)})`;
+}