@miadi/reference-ui 0.0.0-stage → 0.1.0

package/src/index.ts

@@ -0,0 +1,538 @@
+/**
+ * @miadi/reference-ui — the presentation half of Miadi references.
+ *
+ * `@miadi/inquiry-weave/references` owns the ADDRESS: parse, scan, fold
+ * `{{ … }}` directives. This package owns how a reference LOOKS once a
+ * resolver has answered: a view model, an HTML renderer with no framework,
+ * and (on `./react`) React components with the same markup.
+ *
+ * The split is the Dexter reference model's: what a link points to and how it
+ * is presented are separate layers with separate interfaces. Finding the
+ * target is the host's job, because only the host knows who is reading — the
+ * Miadi app reads its catalog on disk as the viewer, a review service asks a
+ * public front. So nothing here holds a URL, a token or a chronicle root.
+ * `createRemoteResolver` takes the front as an argument.
+ *
+ * Ref: jgwill/Miadi#713. Grounding: foundations/resource-addressing-and-terminal-hypermedia/.
+ */
+
+import {
+  findTextReferences,
+  foundationRoute,
+  isFoundationUri,
+  isMiadiChronicleUri,
+  isWheelRefUri,
+  linkBareReferences,
+  parseFoundationUri,
+  parseMiadiChronicleUri,
+  parseWheelRefUri,
+  transformDirectives,
+  type ChronicleResolution,
+  type ParsedChronicleUri,
+  type ParsedFoundationUri,
+  type ParsedWheelRef,
+} from "@miadi/inquiry-weave/references"
+
+export type ReferenceScheme = "chronicle" | "foundation" | "ceremony" | "circle"
+export type ReferenceShow = "chip" | "card"
+
+interface ViewBase {
+  /** The URI as written. Rendered into `data-miadi-uri`. */
+  uri: string
+  /** The author's label (`mc.label`), when one was given. */
+  label?: string
+  /** What the reference shows when no label and no link text exist. */
+  fallback: string
+  show: ReferenceShow
+  highlight: boolean
+}
+
+export interface EpisodeReferenceView extends ViewBase {
+  kind: "episode"
+  href: string
+  /** `ep 550`, or the folder name when the episode carries no number. */
+  badge: string
+  name: string
+  title?: string
+  date?: string
+  direction?: string
+  theme?: string
+  /** Waypoints the path travelled through, `ep 092 → ep 126`. */
+  via: string[]
+}
+
+export interface FoundationReferenceView extends ViewBase {
+  kind: "foundation"
+  href: string
+  slug: string
+  file?: string
+  title?: string
+  /** The `@miadi/foundations` version the page was read from. */
+  version?: string
+  fields: string[]
+  /** Set for a packet an episode wrote itself: the episode's badge. */
+  episode?: string
+}
+
+export interface WheelReferenceView extends ViewBase {
+  kind: "wheel"
+  wheel: "ceremony" | "circle"
+  id: string
+  /** The page that asks the reader for their seat. Nothing of the record is shown. */
+  href: string
+}
+
+export interface UnresolvedReferenceView extends ViewBase {
+  kind: "unresolved"
+  scheme: ReferenceScheme
+  /** Why, for the title attribute. */
+  reason: string
+}
+
+export type ReferenceView = EpisodeReferenceView | FoundationReferenceView | WheelReferenceView | UnresolvedReferenceView
+
+/** True for the four schemes this package renders. */
+export function isReferenceUri(url: string | undefined): boolean {
+  return isMiadiChronicleUri(url) || isFoundationUri(url) || isWheelRefUri(url)
+}
+
+/**
+ * A markdown renderer's URL filter that lets the four schemes through and
+ * hands everything else to the host's own filter. react-markdown strips
+ * unknown schemes by default, which would blank every reference.
+ */
+export function referenceUrlTransform(fallback: (url: string) => string): (url: string) => string {
+  return (url) => (isReferenceUri(url) ? url : fallback(url))
+}
+
+/**
+ * The href a view may carry: a path on this host (`/x`, never `//x`), made
+ * absolute on `base` when one is given, or an http(s) URL on `base`'s own
+ * origin. Anything else — `javascript:`, `//evil.example`, another origin —
+ * is refused, and the view renders unresolved. A resolver's answer is data
+ * from the network, and the HTML renderer cannot rely on React's own
+ * `javascript:` guard (jgwill/Miadi#713 review, F1).
+ */
+export function safeHref(route: unknown, base?: string): string | null {
+  if (typeof route !== "string" || /[\u0000-\u001f\u007f\s\\]/.test(route)) return null
+  if (/^\/(?!\/)/.test(route)) return base ? `${base.replace(/\/+$/, "")}${route}` : route
+  if (!base) return null
+  try {
+    const url = new URL(route)
+    const origin = new URL(base).origin
+    return (url.protocol === "https:" || url.protocol === "http:") && url.origin === origin ? url.href : null
+  } catch {
+    return null
+  }
+}
+const showOf = (options: Record<string, string>): ReferenceShow => (options.show === "card" ? "card" : "chip")
+const pad = (n: number) => String(n).padStart(3, "0")
+
+function base(uri: string, options: Record<string, string>, fallback: string): ViewBase {
+  return {
+    uri,
+    ...(options.label ? { label: options.label } : {}),
+    fallback,
+    show: showOf(options),
+    highlight: options.highlight === "true",
+  }
+}
+
+export function unresolvedView(uri: string, scheme: ReferenceScheme, reason: string, options: Record<string, string> = {}, fallback?: string): UnresolvedReferenceView {
+  return { kind: "unresolved", scheme, reason, ...base(uri, options, fallback ?? uri.replace(/^miadi-[a-z]+:(\/\/)?/i, "")) }
+}
+
+/**
+ * The view of an episode reference, from a parse and a resolution
+ * (`resolveChronicleRef`, or the `resolution` field of `/api/chronicle/resolve`).
+ * `base` makes the room route absolute for a host on another origin.
+ */
+export function episodeReferenceView(
+  parsed: ParsedChronicleUri,
+  resolution: ChronicleResolution,
+  options: { base?: string } = {},
+): EpisodeReferenceView | UnresolvedReferenceView {
+  const target = resolution?.target
+  const waypoints = Array.isArray(resolution?.waypoints) ? resolution.waypoints : []
+  const href = target?.resolved === true && typeof target.name === "string" ? safeHref(target.route, options.base) : null
+  if (!target || !href) {
+    return unresolvedView(parsed.uri, "chronicle", `Unresolved chronicle reference: ${parsed.uri}`, parsed.options, parsed.episodePath)
+  }
+  const title = typeof target.title === "string" ? target.title : undefined
+  return {
+    kind: "episode",
+    // A bare mention or a link with no words of its own shows the title.
+    ...base(parsed.uri, parsed.options, title ?? parsed.episodePath),
+    href,
+    badge: typeof target.number === "number" ? `ep ${pad(target.number)}` : target.name!,
+    name: target.name!,
+    ...(title ? { title } : {}),
+    ...(typeof target.date === "string" ? { date: target.date } : {}),
+    ...(typeof target.direction === "string" ? { direction: target.direction } : {}),
+    ...(typeof target.theme === "string" ? { theme: target.theme } : {}),
+    via: waypoints.map((w) => (typeof w?.number === "number" ? `ep ${w.number}` : String(w?.segment ?? ""))),
+  }
+}
+
+/** What a host knows about one packet: from `@miadi/foundations`, or the `foundation` field of `/api/chronicle/resolve`. */
+export interface FoundationInfo {
+  slug: string
+  exists: boolean
+  title?: string
+  version?: string
+  fields?: string[]
+  /** Route of the packet or file page; defaults to `/foundations/<slug>[/<file>]`. */
+  route?: string
+}
+
+export function foundationReferenceView(
+  parsed: ParsedFoundationUri,
+  info: FoundationInfo | null,
+  options: { base?: string } = {},
+): FoundationReferenceView | UnresolvedReferenceView {
+  const fallback = parsed.file ? `${parsed.slug}/${parsed.file}` : parsed.slug
+  const href = info && info.exists === true ? safeHref(info.route ?? foundationRoute(parsed), options.base) : null
+  if (!info || !href) {
+    return unresolvedView(parsed.uri, "foundation", `Unresolved foundation reference: ${parsed.uri}`, parsed.options, fallback)
+  }
+  const title = typeof info.title === "string" ? info.title : undefined
+  return {
+    kind: "foundation",
+    ...base(parsed.uri, parsed.options, title && !parsed.file ? title : fallback),
+    href,
+    slug: parsed.slug,
+    ...(parsed.file ? { file: parsed.file } : {}),
+    ...(title ? { title } : {}),
+    ...(typeof info.version === "string" ? { version: info.version } : {}),
+    fields: Array.isArray(info.fields) ? info.fields.filter((f): f is string => typeof f === "string") : [],
+  }
+}
+
+/**
+ * An episode's own packet, `miadi-chronicle:<ep>/foundations/<topic>`: a
+ * foundation chip whose page is the episode room opened on the packet README.
+ */
+export function episodeFoundationView(
+  parsed: ParsedChronicleUri,
+  resolution: ChronicleResolution,
+  info: { title?: string; exists: boolean },
+  options: { base?: string } = {},
+): FoundationReferenceView | UnresolvedReferenceView {
+  const topic = parsed.artifactName ?? ""
+  const episode = episodeReferenceView(parsed, resolution, options)
+  if (episode.kind !== "episode" || !info.exists || !topic) {
+    return unresolvedView(parsed.uri, "chronicle", `Unresolved episode foundation: ${parsed.uri}`, parsed.options, topic || parsed.episodePath)
+  }
+  const title = typeof info.title === "string" ? info.title : undefined
+  return {
+    kind: "foundation",
+    ...base(parsed.uri, parsed.options, title ?? topic),
+    // The room's own `?file=` door, its query placed before any fragment.
+    href: withQuery(episode.href, `file=${encodeURIComponent(`foundations/${topic}/README.md`)}`),
+    slug: topic,
+    ...(title ? { title } : {}),
+    fields: [],
+    episode: episode.badge,
+  }
+}
+
+export function wheelReferenceView(parsed: ParsedWheelRef, route: string, options: { base?: string } = {}): WheelReferenceView | UnresolvedReferenceView {
+  const href = safeHref(route, options.base)
+  if (!href) return unresolvedView(parsed.uri, parsed.kind, `Unresolved ${parsed.kind} reference: ${parsed.uri}`, parsed.options, parsed.kind)
+  return {
+    kind: "wheel",
+    wheel: parsed.kind,
+    id: parsed.id,
+    href,
+    ...base(parsed.uri, parsed.options, parsed.kind),
+  }
+}
+
+/** Put a query before the fragment of an href. */
+export function withQuery(href: string, query: string): string {
+  const hash = href.indexOf("#")
+  const head = hash === -1 ? href : href.slice(0, hash)
+  const tail = hash === -1 ? "" : href.slice(hash)
+  return `${head}${head.includes("?") ? "&" : "?"}${query}${tail}`
+}
+
+// ── HTML ─────────────────────────────────────────────────────────────────────
+
+const ESCAPES: Record<string, string> = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }
+export function escapeHtml(text: string): string {
+  return text.replace(/[&<>"']/g, (c) => ESCAPES[c]!)
+}
+
+const DIRECTIONS = new Set(["east", "south", "west", "north"])
+
+/** Class names, shared by the HTML renderer and the React components so the markup is one. */
+export function referenceClasses(view: ReferenceView): string {
+  if (view.kind === "unresolved") return `mr-ref mr-ref--chip mr-ref--unresolved not-prose`
+  const dir = view.kind === "episode" && view.direction && DIRECTIONS.has(view.direction) ? ` mr-dir-${view.direction}` : ""
+  const highlight = view.highlight ? " mr-ref--highlight" : ""
+  return `mr-ref mr-ref--${view.show} mr-ref--${view.kind}${dir}${highlight} not-prose`
+}
+
+/** The text pieces a view shows, in order. Both renderers place these and nothing else. */
+export interface ReferenceParts {
+  badge: string
+  label: string
+  title?: string
+  meta?: string
+  note?: string
+  tooltip: string
+}
+
+/**
+ * What a view shows. `text` is the link text a markdown author wrote
+ * (`[text](uri)`), which outranks the fallback but not an explicit `mc.label`.
+ */
+export function referenceParts(view: ReferenceView, text?: string): ReferenceParts {
+  // A bare mention linked to itself has no words of its own (#713 review, F10).
+  const words = text && !isReferenceUri(text.trim()) ? text : undefined
+  const label = view.label || words || view.fallback
+  switch (view.kind) {
+    case "unresolved":
+      return { badge: view.scheme === "foundation" ? "◇" : "⟐", label, note: "(unresolved)", tooltip: view.reason }
+    case "wheel":
+      return { badge: view.wheel === "ceremony" ? "◆" : "○", label, tooltip: `${view.wheel} ${view.id}: its page asks for your seat` }
+    case "episode": {
+      const meta = [
+        view.label && view.title && view.label !== view.title ? view.title : "",
+        view.date ?? "",
+        view.theme ?? "",
+        view.via.length > 0 ? `via ${view.via.join(" → ")}` : "",
+      ].filter(Boolean).join(" · ")
+      return view.show === "card"
+        ? { badge: `⟐ ${view.badge}${view.direction ? ` · ${view.direction}` : ""}`, label, title: view.label || view.title || label, meta, tooltip: view.title ?? view.name }
+        : { badge: `⟐ ${view.badge}`, label, tooltip: `${view.title ?? view.name}${view.date ? ` (${view.date})` : ""}` }
+    }
+    case "foundation": {
+      const kind = view.episode ? `foundation · ${view.episode}` : "foundation"
+      // A package number reads `v0.1.6`; a source commit reads `at a9cf5d29b4c9`.
+      const version = view.version ? (/^\d+\.\d+/.test(view.version) ? `v${view.version}` : `at ${view.version}`) : ""
+      const meta = [view.file ?? "", view.fields.slice(0, 3).join(" · "), version].filter(Boolean).join(" · ")
+      return view.show === "card"
+        ? { badge: `◇ ${kind}`, label, title: view.label || view.title || label, meta, tooltip: view.title ?? view.slug }
+        : { badge: `◇ ${kind}`, label, tooltip: `${view.title ?? view.slug}${view.file ? ` · ${view.file}` : ""}` }
+    }
+  }
+}
+
+/** One reference as an HTML string, for hosts without React. Every text is escaped. */
+export function renderReferenceHtml(view: ReferenceView, text?: string): string {
+  const p = referenceParts(view, text)
+  const cls = referenceClasses(view)
+  const data = `data-miadi-uri="${escapeHtml(view.uri)}" data-miadi-resolved="${view.kind === "unresolved" ? "false" : "true"}"`
+  if (view.kind === "unresolved") {
+    return `<span class="${cls}" title="${escapeHtml(p.tooltip)}" ${data}><span class="mr-ref__badge">${escapeHtml(p.badge)}</span> <span class="mr-ref__label">${escapeHtml(p.label)}</span> <span class="mr-ref__note">${escapeHtml(p.note!)}</span></span>`
+  }
+  const head = `<a class="${cls}" href="${escapeHtml(view.href)}" title="${escapeHtml(p.tooltip)}" ${data}>`
+  if (view.show === "card" && view.kind !== "wheel") {
+    return `${head}<span class="mr-ref__badge">${escapeHtml(p.badge)}</span><span class="mr-ref__title">${escapeHtml(p.title!)}</span>${p.meta ? `<span class="mr-ref__meta">${escapeHtml(p.meta)}</span>` : ""}</a>`
+  }
+  return `${head}<span class="mr-ref__badge">${escapeHtml(p.badge)}</span> <span class="mr-ref__label">${escapeHtml(p.label)}</span></a>`
+}
+
+// ── Resolution over HTTP ─────────────────────────────────────────────────────
+
+/** The answer of `GET <front>/api/chronicle/resolve?uri=…`, the fields this package reads. */
+export interface ResolveAnswer {
+  ok: boolean
+  uri?: string
+  resolution?: ChronicleResolution
+  foundation?: FoundationInfo
+  /** For `<ep>/foundations/<topic>`: the episode's own packet. */
+  episodeFoundation?: { slug: string; title?: string; exists: boolean }
+  wheelRef?: { kind: "ceremony" | "circle"; id: string; route: string }
+}
+
+/** Answers one reference URI, or null when the front could not be asked. */
+export type ReferenceResolver = (uri: string) => Promise<ResolveAnswer | null>
+
+/**
+ * A resolver over a Miadi front's public resolve door. The front is an
+ * argument, never a default: `createRemoteResolver({ origin: process.env.MIADI_PUBLIC_URL })`.
+ * Only that origin is asked. A failure answers null, which renders as an
+ * unresolved chip: a broken reference is data, never a page error.
+ */
+export function createRemoteResolver(options: {
+  origin: string
+  fetch?: typeof fetch
+  timeoutMs?: number
+  /** Extra fetch options, e.g. `{ next: { revalidate: 300 } }` on Next.js. */
+  init?: RequestInit & Record<string, unknown>
+}): ReferenceResolver {
+  const origin = options.origin.replace(/\/+$/, "")
+  const doFetch = options.fetch ?? fetch
+  return async (uri) => {
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? 8_000)
+    try {
+      // A Headers instance or a tuple list survives the merge (#713 review, F11).
+      const headers = new Headers(options.init?.headers)
+      headers.set("accept", "application/json")
+      const response = await doFetch(`${origin}/api/chronicle/resolve?uri=${encodeURIComponent(uri)}`, {
+        ...options.init,
+        signal: controller.signal,
+        headers,
+      })
+      if (!response.ok) return null
+      const body: unknown = await response.json()
+      return body && typeof body === "object" ? (body as ResolveAnswer) : null
+    } catch {
+      return null
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+}
+
+const isObject = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value)
+
+/** A resolution as far as this package reads it, or undefined (#713 review, F5). */
+function resolutionOf(value: unknown): ChronicleResolution | undefined {
+  if (!isObject(value) || !isObject(value.target) || typeof value.target.resolved !== "boolean") return undefined
+  return {
+    resolved: value.resolved === true,
+    target: value.target as unknown as ChronicleResolution["target"],
+    waypoints: Array.isArray(value.waypoints) ? (value.waypoints.filter(isObject) as unknown as ChronicleResolution["waypoints"]) : [],
+  }
+}
+
+/**
+ * The view a resolver's answer makes for one URI. The answer is data from the
+ * network: a field of the wrong shape makes the reference unresolved, never a
+ * thrown page. `base` makes relative routes absolute.
+ */
+export function viewFromAnswer(uri: string, answer: ResolveAnswer | null, options: { base?: string } = {}): ReferenceView | null {
+  const a: Record<string, unknown> = isObject(answer) ? answer : {}
+  const foundation = parseFoundationUri(uri)
+  if (foundation) {
+    const info = isObject(a.foundation) && a.foundation.slug === foundation.slug ? (a.foundation as unknown as FoundationInfo) : null
+    return foundationReferenceView(foundation, info, options)
+  }
+  const wheel = parseWheelRefUri(uri)
+  if (wheel) {
+    const route = isObject(a.wheelRef) ? a.wheelRef.route : undefined
+    return typeof route === "string"
+      ? wheelReferenceView(wheel, route, options)
+      : unresolvedView(uri, wheel.kind, `Unresolved ${wheel.kind} reference: ${uri}`, wheel.options, wheel.kind)
+  }
+  const chronicle = parseMiadiChronicleUri(uri)
+  if (!chronicle) return null
+  const resolution = resolutionOf(a.resolution)
+  if (!resolution) return unresolvedView(uri, "chronicle", `Unresolved chronicle reference: ${uri}`, chronicle.options, chronicle.episodePath)
+  if (chronicle.artifact === "foundations" && chronicle.artifactName) {
+    const own = isObject(a.episodeFoundation) ? a.episodeFoundation : {}
+    return episodeFoundationView(
+      chronicle,
+      resolution,
+      { exists: own.exists === true, ...(typeof own.title === "string" ? { title: own.title } : {}) },
+      options,
+    )
+  }
+  return episodeReferenceView(chronicle, resolution, options)
+}
+
+const ENTITIES: Record<string, string> = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" }
+
+function safeDecode(s: string): string {
+  try {
+    return decodeURIComponent(s)
+  } catch {
+    return s
+  }
+}
+
+/**
+ * One key for every spelling of the same reference: the form written in the
+ * markdown source and the href a markdown parser hands the link component
+ * (backslash escapes and character references processed, destinations
+ * percent-encoded, `//` dropped, a wheel id in canonical form) all map to it.
+ * `prepareReferenceViews` keys its views by it and `lookupView` asks by it,
+ * so a view is never missed for a spelling (jgwill/Miadi#713 review, F6).
+ */
+export function referenceKey(href: string): string {
+  const text = href
+    .trim()
+    .replace(/\\([!-/:-@[-`{-~])/g, "$1")
+    .replace(/&(#x[0-9a-f]{1,6}|#[0-9]{1,7}|[a-z]{2,6});/gi, (whole, name: string) => {
+      if (name[0] === "#") {
+        const code = name[1] === "x" || name[1] === "X" ? parseInt(name.slice(2), 16) : parseInt(name.slice(1), 10)
+        return Number.isFinite(code) && code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : whole
+      }
+      return ENTITIES[name.toLowerCase()] ?? whole
+    })
+  const params = (query: Record<string, string>, options: Record<string, string>) =>
+    [...Object.entries(query).map(([k, v]) => `${k}=${v}`), ...Object.entries(options).map(([k, v]) => `mc.${k}=${v}`)].sort().join("&")
+  const foundation = parseFoundationUri(text)
+  if (foundation) {
+    return `foundation|${foundation.slug}|${foundation.file ?? ""}|${params(foundation.query, foundation.options)}|${safeDecode(foundation.fragment ?? "")}`
+  }
+  const wheel = parseWheelRefUri(text)
+  if (wheel) return `${wheel.kind}|${wheel.id}|${params(wheel.query, wheel.options)}|${safeDecode(wheel.fragment ?? "")}`
+  const chronicle = parseMiadiChronicleUri(text)
+  if (chronicle) {
+    return `chronicle|${chronicle.episodePath}|${params(chronicle.query, chronicle.options)}|${safeDecode(chronicle.fragment ?? "")}`
+  }
+  return safeDecode(text)
+}
+
+export interface PreparedReferenceViews {
+  /** The markdown to render: directives folded, bare mentions linked when asked. */
+  markdown: string
+  /** One view per reference, keyed by `referenceKey`. Ask it with `lookupView`. */
+  views: Map<string, ReferenceView>
+}
+
+/** References past this many on one page render unresolved, so one text cannot make a server ask a front without bound. */
+export const DEFAULT_MAX_REFERENCES = 100
+
+/**
+ * Prepare a markdown text for rendering: fold `{{ … }}` directives into
+ * links, optionally link bare mentions, then resolve every distinct reference
+ * once (at most `concurrency` at a time, at most `maxReferences` in all) and
+ * build its view. A renderer then finds each link's view with `lookupView`,
+ * synchronously.
+ */
+export async function prepareReferenceViews(
+  markdown: string,
+  resolver: ReferenceResolver,
+  options: { base?: string; linkBare?: boolean; concurrency?: number; maxReferences?: number } = {},
+): Promise<PreparedReferenceViews> {
+  let text = transformDirectives(markdown)
+  if (options.linkBare) text = linkBareReferences(text)
+  const byKey = new Map<string, string>()
+  for (const ref of findTextReferences(text)) {
+    if (ref.form === "bare") continue
+    const key = referenceKey(ref.uri)
+    if (!byKey.has(key)) byKey.set(key, ref.uri)
+  }
+  const views = new Map<string, ReferenceView>()
+  const limit = options.maxReferences ?? DEFAULT_MAX_REFERENCES
+  const entries = [...byKey.entries()]
+  for (const [key, uri] of entries.slice(limit)) {
+    const view = viewFromAnswer(uri, null, { base: options.base })
+    if (view) views.set(key, { ...view, ...(view.kind === "unresolved" ? { reason: `Not resolved: more than ${limit} references on this page` } : {}) })
+  }
+  const asked = entries.slice(0, limit)
+  let next = 0
+  const worker = async () => {
+    while (next < asked.length) {
+      const [key, uri] = asked[next++]!
+      let answer: ResolveAnswer | null = null
+      try {
+        answer = await resolver(uri)
+      } catch {
+        answer = null
+      }
+      const view = viewFromAnswer(uri, answer, { base: options.base })
+      if (view) views.set(key, view)
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(options.concurrency ?? 6, asked.length) }, worker))
+  return { markdown: text, views }
+}
+
+export { transformDirectives, linkBareReferences, isMiadiChronicleUri, isFoundationUri, isWheelRefUri }

package/src/react.tsx

@@ -0,0 +1,106 @@
+/**
+ * @miadi/reference-ui/react — the React host of the reference views. The
+ * markup is `renderReferenceHtml`'s, element for element (a parity test holds
+ * it there), so a page rendered on the server by React and a page rendered as
+ * a string look the same.
+ *
+ * The link element is the host's: pass `LinkComponent` (Next's `Link`) to keep
+ * client navigation; the default is a plain `<a>`.
+ */
+
+import type { ComponentType, ReactNode } from "react"
+import {
+  referenceClasses,
+  referenceKey,
+  referenceParts,
+  type ReferenceView,
+} from "./index.js"
+
+export type LinkLike = ComponentType<{
+  href: string
+  className?: string
+  title?: string
+  children?: ReactNode
+  [data: `data-${string}`]: string | undefined
+}>
+
+export interface ReferenceProps {
+  view: ReferenceView
+  /** The link text the author wrote, used when the reference carries no label. */
+  children?: ReactNode
+  LinkComponent?: LinkLike
+}
+
+function textOf(children: ReactNode): string | undefined {
+  if (typeof children === "string") return children
+  if (Array.isArray(children) && children.every((c) => typeof c === "string")) return children.join("")
+  return undefined
+}
+
+/** One reference: a chip, a card, a wheel page link, or the unresolved chip. */
+export function Reference({ view, children, LinkComponent }: ReferenceProps) {
+  const text = textOf(children)
+  const p = referenceParts(view, text)
+  // A label that is not plain text (an emphasised link text) is shown as the author wrote it.
+  const label: ReactNode = view.label || text !== undefined || children === undefined || children === null ? p.label : children
+  const className = referenceClasses(view)
+  const data = { "data-miadi-uri": view.uri, "data-miadi-resolved": view.kind === "unresolved" ? "false" : "true" }
+
+  if (view.kind === "unresolved") {
+    return (
+      <span className={className} title={p.tooltip} {...data}>
+        <span className="mr-ref__badge">{p.badge}</span> <span className="mr-ref__label">{label}</span>{" "}
+        <span className="mr-ref__note">{p.note}</span>
+      </span>
+    )
+  }
+  const Link: LinkLike = LinkComponent ?? ((props) => <a {...props} />)
+  if (view.show === "card" && view.kind !== "wheel") {
+    return (
+      <Link className={className} href={view.href} title={p.tooltip} {...data}>
+        <span className="mr-ref__badge">{p.badge}</span>
+        <span className="mr-ref__title">{p.title}</span>
+        {p.meta ? <span className="mr-ref__meta">{p.meta}</span> : null}
+      </Link>
+    )
+  }
+  return (
+    <Link className={className} href={view.href} title={p.tooltip} {...data}>
+      <span className="mr-ref__badge">{p.badge}</span> <span className="mr-ref__label">{label}</span>
+    </Link>
+  )
+}
+
+/**
+ * Find the view for an href as a markdown parser hands it over. `views` is
+ * what `prepareReferenceViews` returned, or the same entries as a plain
+ * object after crossing from a server component to a client one.
+ */
+export function lookupView(
+  views: ReadonlyMap<string, ReferenceView> | Readonly<Record<string, ReferenceView>>,
+  href: string | undefined,
+): ReferenceView | undefined {
+  if (!href) return undefined
+  const key = referenceKey(href)
+  return views instanceof Map ? views.get(key) : (views as Record<string, ReferenceView>)[key]
+}
+
+/**
+ * A link override for react-markdown (`components={{ a }}`): a reference href
+ * with a prepared view renders as a Reference; every other link renders as the
+ * plain anchor it was, its attributes intact.
+ */
+export function createReferenceLink(
+  views: ReadonlyMap<string, ReferenceView> | Readonly<Record<string, ReferenceView>>,
+  options: { LinkComponent?: LinkLike; externalLinksInNewTab?: boolean } = {},
+) {
+  return function ReferenceLink(props: { href?: string; children?: ReactNode; node?: unknown; [key: string]: unknown }) {
+    const { node: _node, ...rest } = props
+    const view = lookupView(views, props.href)
+    if (view) return <Reference view={view} LinkComponent={options.LinkComponent}>{props.children}</Reference>
+    if (options.externalLinksInNewTab && typeof props.href === "string" && /^https?:\/\//.test(props.href)) {
+      return <a {...rest} target="_blank" rel="noreferrer" />
+    }
+    return <a {...rest} />
+  }
+}