@shortlink-org/portolan 0.2.0 → 0.2.2

package/src/catalog.ts

@@ -705,12 +705,7 @@ export interface Store {
 }
 
 export type RedisOperation =
-  | "read"
-  | "write"
-  | "delete"
-  | "exists"
-  | "expire"
-  | "count";
+  "read" | "write" | "delete" | "exists" | "expire" | "count";
 
 export const REDIS_OPERATIONS: readonly RedisOperation[] = [
   "read",
@@ -730,6 +725,19 @@ export interface RedisKeyspace {
   /** Value type where a write or marshal call proves it. */
   value?: string;
   source?: string;
+  /** Aggregate or block whose value this key family holds, when provable. */
+  persists?: { aggregate?: string; block?: string };
+  /** Individual client calls, before they are folded into `operations`. */
+  accesses?: RedisAccess[];
+}
+
+export interface RedisAccess {
+  operation: RedisOperation;
+  /** Enclosing adapter method, for example `Store.Get`. */
+  method?: string;
+  ttl?: string;
+  value?: string;
+  source?: string;
 }
 
 /**
@@ -880,18 +888,37 @@ export interface Step {
   id: string;
   from: string;
   to: string; // participant ids; from === to is a self-message
-  kind: "rpc" | "event" | "call";
+  kind: "rpc" | "event" | "call" | "response";
   ref?: string; // Event.id or RpcCall.id - resolvable, or status must be unresolved
   label?: string;
   status: Status;
   note?: string;
   line?: string;
+  /** Synchronous request step this synthesized response returns from. */
+  replyTo?: string;
+  /** Proven HTTP wire contract for a response step. */
+  http?: HTTPResponse;
   /** Source function execution enters here, when an extractor can prove it. */
   continuesAt?: string;
   /** Source functions proven to execute on the path represented by this step. */
   reaches?: string[];
   /** Exact asynchronous send/receive evidence used for flow composition. */
   handoff?: FlowHandoff;
+  /** Repository call resolved to a concrete store operation after merge. */
+  storeAccess?: FlowStoreAccess;
+}
+export interface HTTPResponse {
+  status?: number;
+  contentType?: string;
+  body?: string;
+  /** RPC method whose response value is serialized into this body. */
+  bodyRef?: string;
+  encoding?: string;
+  outcome?: "success" | "error";
+  warning?: string;
+  source?: string;
+  /** Shape recovered directly from a literal response body. */
+  fields?: Field[];
 }
 export interface FlowHandoff {
   kind: "message" | "job";
@@ -900,6 +927,14 @@ export interface FlowHandoff {
   message?: string;
   direction: "send" | "receive";
 }
+export interface FlowStoreAccess {
+  store: string;
+  method?: string;
+  operation?: RedisOperation;
+  keyspace?: string;
+  /** Concrete adapter call rather than the use-case-side repository call. */
+  source?: string;
+}
 export interface Parallel {
   type: "parallel";
   id: string;
@@ -1410,6 +1445,8 @@ export interface CatalogIndex {
   tablesByAggregate: Map<string, Table[]>;
   /** aggregate id -> views naming it in `persists`, in catalog order */
   viewsByAggregate: Map<string, View[]>;
+  /** aggregate id -> Redis key families holding it, in catalog order */
+  keyspacesByAggregate: Map<string, RedisKeyspaceOwner[]>;
   /** block id -> columns whose `maps` path lands in that block */
   columnsByBlock: Map<string, ColumnOwner[]>;
   /** table id -> the columns pointing at it through a foreign key */
@@ -1444,6 +1481,11 @@ export interface InterfaceOwner {
   provided: RpcService;
 }
 
+export interface RedisKeyspaceOwner {
+  keyspace: RedisKeyspace;
+  store: Store;
+}
+
 export function buildIndex(catalog: Catalog): CatalogIndex {
   const serviceById = new Map<string, Service>();
   const serviceContext = new Map<string, BoundedContext>();
@@ -1492,6 +1534,7 @@ export function buildIndex(catalog: Catalog): CatalogIndex {
   const storesOwnedBy = new Map<string, Store[]>();
   const tablesByAggregate = new Map<string, Table[]>();
   const viewsByAggregate = new Map<string, View[]>();
+  const keyspacesByAggregate = new Map<string, RedisKeyspaceOwner[]>();
   const columnsByBlock = new Map<string, ColumnOwner[]>();
   const fkIntoTable = new Map<string, ColumnOwner[]>();
 
@@ -1587,6 +1630,14 @@ export function buildIndex(catalog: Catalog): CatalogIndex {
     owned.push(store);
     storesOwnedBy.set(store.owner, owned);
 
+    for (const keyspace of store.keyspaces ?? []) {
+      const aggregateId = keyspace.persists?.aggregate;
+      if (!aggregateId) continue;
+      const list = keyspacesByAggregate.get(aggregateId) ?? [];
+      list.push({ keyspace, store });
+      keyspacesByAggregate.set(aggregateId, list);
+    }
+
     for (const table of store.tables) {
       tableById.set(table.id, { table, store });
       // A table may name only the block it holds. That block belongs to an
@@ -1720,6 +1771,7 @@ export function buildIndex(catalog: Catalog): CatalogIndex {
     servicesUsingModule,
     tablesByAggregate,
     viewsByAggregate,
+    keyspacesByAggregate,
     columnsByBlock,
     fkIntoTable,
   };
@@ -1839,6 +1891,7 @@ export function validateCatalog(catalog: Catalog): Catalog {
 
   const eventIds = new Set<string>();
   const rpcIds = new Set<string>();
+  const storeIds = new Set(allStores(catalog).map((store) => store.id));
 
   assertUniqueSlugs(
     catalog.contexts.map((c) => c.id),
@@ -2161,6 +2214,7 @@ export function validateCatalog(catalog: Catalog): Catalog {
 
     const steps = walkSteps(flow.steps);
     const stepIds = new Set<string>();
+    const stepById = new Map<string, Step>();
     for (const step of steps) {
       if (stepIds.has(step.id)) {
         fail(
@@ -2169,6 +2223,16 @@ export function validateCatalog(catalog: Catalog): Catalog {
         );
       }
       stepIds.add(step.id);
+      stepById.set(step.id, step);
+
+      if (
+        !(["rpc", "event", "call", "response"] as const).includes(step.kind)
+      ) {
+        fail(
+          `flow "${flow.slug}" step "${step.id}" has unknown kind "${step.kind}"`,
+          `flow ${flow.id} / step ${step.id}`,
+        );
+      }
 
       if (step.reaches?.some((entrypoint) => entrypoint.length === 0)) {
         fail(
@@ -2208,6 +2272,55 @@ export function validateCatalog(catalog: Catalog): Catalog {
           );
         }
       }
+      if (step.storeAccess) {
+        if (step.kind !== "call") {
+          fail(
+            `flow "${flow.slug}" step "${step.id}" has store access metadata but is not a call`,
+            `flow ${flow.id} / step ${step.id}`,
+          );
+        }
+        if (!storeIds.has(step.storeAccess.store)) {
+          fail(
+            `flow "${flow.slug}" step "${step.id}" names unknown store "${step.storeAccess.store}"`,
+            `flow ${flow.id} / step ${step.id}`,
+          );
+        }
+        if (
+          step.storeAccess.operation !== undefined &&
+          !REDIS_OPERATIONS.includes(step.storeAccess.operation)
+        ) {
+          fail(
+            `flow "${flow.slug}" step "${step.id}" has unknown store operation "${step.storeAccess.operation}"`,
+            `flow ${flow.id} / step ${step.id}`,
+          );
+        }
+      }
+      if (step.http) {
+        if (step.kind !== "response") {
+          fail(
+            `flow "${flow.slug}" step "${step.id}" has HTTP response metadata but is not a response`,
+            `flow ${flow.id} / step ${step.id}`,
+          );
+        }
+        if (
+          step.http.status !== undefined &&
+          (step.http.status < 100 || step.http.status > 599)
+        ) {
+          fail(
+            `flow "${flow.slug}" response "${step.id}" has invalid HTTP status ${step.http.status}`,
+            `flow ${flow.id} / step ${step.id}`,
+          );
+        }
+        if (
+          step.http.outcome !== undefined &&
+          !(["success", "error"] as const).includes(step.http.outcome)
+        ) {
+          fail(
+            `flow "${flow.slug}" response "${step.id}" has unknown HTTP outcome "${step.http.outcome}"`,
+            `flow ${flow.id} / step ${step.id}`,
+          );
+        }
+      }
 
       if (!lanes.has(step.from)) {
         fail(
@@ -2231,6 +2344,37 @@ export function validateCatalog(catalog: Catalog): Catalog {
         }
       }
     }
+
+    for (const step of steps) {
+      if (step.kind !== "response") {
+        if (step.replyTo !== undefined) {
+          fail(
+            `flow "${flow.slug}" step "${step.id}" is not a response but names replyTo "${step.replyTo}"`,
+            `flow ${flow.id} / step ${step.id}`,
+          );
+        }
+        continue;
+      }
+      if (!step.replyTo) {
+        fail(
+          `flow "${flow.slug}" response "${step.id}" names no request in replyTo`,
+          `flow ${flow.id} / step ${step.id}`,
+        );
+      }
+      const request = stepById.get(step.replyTo);
+      if (!request || request.kind !== "rpc") {
+        fail(
+          `flow "${flow.slug}" response "${step.id}" replies to "${step.replyTo}", which is not an rpc request`,
+          `flow ${flow.id} / step ${step.id}`,
+        );
+      }
+      if (step.from !== request.to || step.to !== request.from) {
+        fail(
+          `flow "${flow.slug}" response "${step.id}" does not reverse request "${request.id}"`,
+          `flow ${flow.id} / step ${step.id}`,
+        );
+      }
+    }
   }
 
   validateExternals(catalog);
@@ -2511,7 +2655,10 @@ function validateStores(catalog: Catalog): void {
       }
       keyPatterns.add(keyspace.pattern);
       if (keyspace.operations.length === 0) {
-        fail(`Redis key pattern "${keyspace.pattern}" has no operations`, where);
+        fail(
+          `Redis key pattern "${keyspace.pattern}" has no operations`,
+          where,
+        );
       }
       const operations = new Set<string>();
       for (const operation of keyspace.operations) {
@@ -2529,6 +2676,41 @@ function validateStores(catalog: Catalog): void {
         }
         operations.add(operation);
       }
+      const aggregateId = keyspace.persists?.aggregate;
+      if (aggregateId && !aggregates.has(aggregateId)) {
+        fail(
+          `Redis key pattern "${keyspace.pattern}" persists unknown aggregate "${aggregateId}"`,
+          where,
+        );
+      }
+      const blockId = keyspace.persists?.block;
+      if (blockId) {
+        const blockAggregate =
+          aggregates.get(blockId.split(".").slice(0, -1).join("."));
+        const belongs = blockAggregate
+          ? aggregateBlocks(blockAggregate).some(({ block }) => block.id === blockId)
+          : false;
+        if (!belongs) {
+          fail(
+            `Redis key pattern "${keyspace.pattern}" persists unknown block "${blockId}"`,
+            where,
+          );
+        }
+      }
+      for (const access of keyspace.accesses ?? []) {
+        if (!REDIS_OPERATIONS.includes(access.operation)) {
+          fail(
+            `Redis key pattern "${keyspace.pattern}" has access operation "${access.operation}"; expected one of ${REDIS_OPERATIONS.join(", ")}`,
+            where,
+          );
+        }
+        if (!operations.has(access.operation)) {
+          fail(
+            `Redis key pattern "${keyspace.pattern}" has ${access.operation} access absent from its operations summary`,
+            where,
+          );
+        }
+      }
     }
 
     for (const table of store.tables) {

package/src/components/CatIllustration.tsx

@@ -0,0 +1,30 @@
+import type { ReactNode } from "react";
+
+type CatScene = "about" | "clear" | "unchanged" | "onboarding" | "search" | "trial";
+
+const IMAGE: Record<CatScene, string> = {
+  about: "cat-about-v1.webp",
+  clear: "cat-clear-skies-v1.webp",
+  unchanged: "cat-no-changes-v1.webp",
+  onboarding: "cat-onboarding-v1.webp",
+  search: "404-cat-v1.webp",
+  trial: "cat-trial-success-v1.webp",
+};
+
+export function CatIllustration({ scene, className = "" }: { scene: CatScene; className?: string }) {
+  return <img src={`${import.meta.env.BASE_URL}${IMAGE[scene]}`} alt="" aria-hidden draggable={false} className={`cat-illustration ${className}`} />;
+}
+
+/** A rare, positive empty state. Ordinary missing rows keep using `Empty`. */
+export function CatEmptyState({ scene, title, children, meta, className = "" }: { scene: Extract<CatScene, "clear" | "unchanged" | "onboarding">; title: string; children: ReactNode; meta?: ReactNode; className?: string }) {
+  return (
+    <div className={`cat-empty-state ${className}`}>
+      <CatIllustration scene={scene} className="cat-empty-illustration" />
+      <div className="min-w-0">
+        <h2 className="text-md font-semibold text-ink">{title}</h2>
+        <div className="mt-1 text-muted">{children}</div>
+        {meta ? <div className="mono mt-3 text-faint">{meta}</div> : null}
+      </div>
+    </div>
+  );
+}

package/src/components/CommitLink.tsx

@@ -0,0 +1,154 @@
+import { useState } from "react";
+import {
+  FloatingPortal,
+  autoUpdate,
+  flip,
+  offset,
+  shift,
+  useDismiss,
+  useFloating,
+  useFocus,
+  useHover,
+  useInteractions,
+  useRole,
+} from "@floating-ui/react";
+import { useQuery } from "@tanstack/react-query";
+import { useForgeAccess } from "../app/forge-access";
+import { buildInfo, repositoryCommitHref } from "../lib/build-info";
+import { forgeRepoFromUrl } from "../lib/github-catalog";
+import type { ForgeCommit, ForgeRepo } from "../lib/github-catalog";
+import { forgeCommitQuery } from "../lib/queries";
+import { absoluteTime, relativeTime } from "../lib/format";
+import { Ident } from "./Ident";
+
+const buildRepo = forgeRepoFromUrl(buildInfo.repoUrl, buildInfo.forge);
+
+function repoFrom(value: string): ForgeRepo | null {
+  const url = /^https?:\/\//.test(value) ? value : `https://${value}`;
+  return forgeRepoFromUrl(url);
+}
+
+function commitHref(repo: ForgeRepo, commit: string): string {
+  const route = repo.provider === "gitlab" ? "/-/commit/" : "/commit/";
+  return `${repo.webUrl.replace(/\/$/, "")}${route}${encodeURIComponent(commit)}`;
+}
+
+export function CommitLink({
+  commit,
+  repo,
+  repository,
+  href,
+  length = 7,
+  className = "",
+}: {
+  commit: string;
+  /** Pass null when the repository is known to be unavailable. */
+  repo?: ForgeRepo | null;
+  /** A repository URL or host/owner/name, used when a ForgeRepo is not already available. */
+  repository?: string;
+  href?: string | null;
+  length?: number;
+  className?: string;
+}) {
+  const parsed = repository === undefined ? undefined : repoFrom(repository);
+  const resolvedRepo = repo !== undefined ? repo : parsed !== undefined ? parsed : buildRepo;
+  const hasExplicitRepo = repo !== undefined || repository !== undefined;
+  const resolvedHref = href !== undefined
+    ? href
+    : resolvedRepo
+      ? commitHref(resolvedRepo, commit)
+      : hasExplicitRepo
+        ? null
+        : repositoryCommitHref(commit);
+  const label = commit.slice(0, length);
+
+  if (!resolvedHref) return <Ident value={commit} className={className}>{label}</Ident>;
+  if (!resolvedRepo) {
+    return <a href={resolvedHref} target="_blank" rel="noreferrer" className={`rounded-[4px] text-accent underline-offset-4 hover:underline ${className}`}>{label}</a>;
+  }
+
+  return <CommitPopover commit={commit} repo={resolvedRepo} href={resolvedHref} label={label} className={className} />;
+}
+
+function CommitPopover({ commit, repo, href, label, className }: { commit: string; repo: ForgeRepo; href: string; label: string; className: string }) {
+  const [open, setOpen] = useState(false);
+  const { refs, floatingStyles, context } = useFloating({
+    open,
+    onOpenChange: setOpen,
+    placement: "bottom-start",
+    strategy: "fixed",
+    middleware: [offset(6), flip({ padding: 8 }), shift({ padding: 8 })],
+    whileElementsMounted: autoUpdate,
+  });
+  const hover = useHover(context, { move: false, delay: { open: 100, close: 80 } });
+  const focus = useFocus(context);
+  const dismiss = useDismiss(context);
+  const role = useRole(context, { role: "tooltip" });
+  const { getReferenceProps, getFloatingProps } = useInteractions([hover, focus, dismiss, role]);
+  const access = useForgeAccess();
+  const token = access.tokenFor(repo);
+  const details = useQuery({
+    ...forgeCommitQuery(repo, token, commit),
+    enabled: open,
+  });
+
+  return (
+    <>
+      <a
+        ref={refs.setReference}
+        href={href}
+        target="_blank"
+        rel="noreferrer"
+        aria-label={`Open commit ${commit} on the forge`}
+        className={`rounded-[4px] text-accent underline-offset-4 hover:underline focus-visible:outline focus-visible:outline-1 focus-visible:outline-accent ${className}`}
+        {...getReferenceProps()}
+      >
+        {label}
+      </a>
+      {open ? (
+        <FloatingPortal>
+          <div
+            ref={refs.setFloating}
+            style={floatingStyles}
+            className="z-50"
+            {...getFloatingProps()}
+          >
+            <div className="palette-in pointer-events-none w-80 max-w-[calc(100vw-1rem)] rounded-control border bg-canvas p-3 mono text-xs normal-case border-line-strong text-muted shadow-md">
+              <div className="label">commit</div>
+              {details.isPending ? (
+                <div className="mt-2">loading commit…</div>
+              ) : details.isError ? (
+                <div className="mt-2">commit details unavailable</div>
+              ) : (
+                <CommitHoverContent commit={details.data} />
+              )}
+            </div>
+          </div>
+        </FloatingPortal>
+      ) : null}
+    </>
+  );
+}
+
+function CommitHoverContent({ commit }: { commit: ForgeCommit }) {
+  const hasStats = commit.additions !== null || commit.deletions !== null;
+  const body = commit.body.replace(/\s+/g, " ").trim();
+  const summary = body.length > 180 ? `${body.slice(0, 177).trimEnd()}…` : body;
+  return (
+    <div className="mt-2">
+      <div className="flex items-center gap-2">
+        {commit.avatarUrl ? <img src={commit.avatarUrl} alt="" className="size-7 rounded-full" /> : null}
+        <div className="min-w-0">
+          <div className="truncate text-ink">{commit.author}</div>
+          {commit.authoredAt ? <div className="text-faint" title={absoluteTime(commit.authoredAt)}>{relativeTime(commit.authoredAt)}</div> : null}
+        </div>
+      </div>
+      <div className="mt-2 font-sans font-medium text-ink">{commit.title}</div>
+      {summary ? <div className="mt-1 font-sans text-muted">{summary}</div> : null}
+      <div className="mt-2 flex items-center gap-3 border-t pt-2 border-line text-faint">
+        <span className="truncate" title={commit.sha}>{commit.sha}</span>
+        {hasStats ? <span className="ml-auto shrink-0"><span className="text-verified">+{commit.additions ?? 0}</span>{" "}<span className="text-unresolved">−{commit.deletions ?? 0}</span></span> : null}
+      </div>
+    </div>
+  );
+}

package/src/components/EditorLink.tsx

@@ -44,6 +44,18 @@ export function useWorkspace(): string | null {
     : null;
 }
 
+export function useEditorTarget(location: SourceLocation | null): {
+  href: string;
+  name: string;
+} | null {
+  const workspace = useWorkspace();
+  const editor = useEditorStore((s) => s.editor);
+  if (!workspace || !location) return null;
+  const where = editorWhere(location);
+  const href = where ? editorHref(editor, workspace, where) : null;
+  return href ? { href, name: editorName(editor) } : null;
+}
+
 export function EditorLink({
   location,
   variant = "icon",
@@ -54,14 +66,9 @@ export function EditorLink({
   variant?: "icon" | "text";
   className?: string;
 }) {
-  const workspace = useWorkspace();
-  const editor = useEditorStore((s) => s.editor);
-  if (!workspace || !location) return null;
-  const where = editorWhere(location);
-  const href = where ? editorHref(editor, workspace, where) : null;
-  if (!href) return null;
-
-  const name = editorName(editor);
+  const target = useEditorTarget(location);
+  if (!target) return null;
+  const { href, name } = target;
   // No target: a scheme URL hands off to the editor and leaves the page
   // where it is. A new tab would be a blank tab.
   return variant === "icon" ? (

package/src/components/GrpcMethodReference.tsx

@@ -0,0 +1,93 @@
+import { Check, Copy, Terminal } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
+import type { RpcMethod, RpcService } from "../catalog";
+import { catalog } from "../data";
+import { toClipboard } from "../lib/clipboard";
+import {
+  grpcRequestJson,
+  grpcurlCommand,
+} from "../lib/grpc-reference";
+
+const SHOWN_MS = 1000;
+
+function CopyButton({ value, label }: { value: string; label: string }) {
+  const [copied, setCopied] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(
+    () => () => {
+      if (timer.current) clearTimeout(timer.current);
+    },
+    [],
+  );
+
+  const copy = () => {
+    void toClipboard(value).then((ok) => {
+      setCopied(ok);
+      if (timer.current) clearTimeout(timer.current);
+      timer.current = setTimeout(() => setCopied(false), SHOWN_MS);
+    });
+  };
+
+  return (
+    <button
+      type="button"
+      onClick={copy}
+      className="row-action opacity-100"
+      aria-label={`Copy ${label}`}
+      title={`Copy ${label}`}
+    >
+      {copied ? <Check size={12} aria-hidden /> : <Copy size={12} aria-hidden />}
+      {copied ? "copied" : "copy"}
+    </button>
+  );
+}
+
+/** The executable-looking part of a protobuf reference, collapsed per method. */
+export function GrpcMethodReference({
+  provided,
+  method,
+}: {
+  provided: RpcService;
+  method: RpcMethod;
+}) {
+  const json = grpcRequestJson(provided, method, catalog.defs);
+  const command = grpcurlCommand(provided, method, catalog.defs);
+
+  return (
+    <details className="group mt-2 overflow-hidden rounded-control border border-line bg-surface">
+      <summary className="flex cursor-pointer list-none items-center gap-2 px-2.5 py-1.5 text-muted hover:text-ink">
+        <Terminal size={13} aria-hidden />
+        <span>Call locally</span>
+        <span className="chip mono">grpcurl</span>
+        <span className="ml-auto text-faint group-open:hidden">show</span>
+        <span className="ml-auto hidden text-faint group-open:inline">hide</span>
+      </summary>
+      <div className="grid gap-3 border-t border-line p-3 lg:grid-cols-2">
+        <div className="min-w-0">
+          <div className="mb-1.5 flex items-center justify-between gap-2">
+            <span className="label">ProtoJSON request</span>
+            <CopyButton value={json} label="request JSON" />
+          </div>
+          <pre className="mono max-h-64 overflow-auto whitespace-pre rounded-control border border-line bg-canvas p-3 text-muted">
+            {json}
+          </pre>
+        </div>
+        <div className="min-w-0">
+          <div className="mb-1.5 flex items-center justify-between gap-2">
+            <span className="label">Command</span>
+            <CopyButton value={command} label="grpcurl command" />
+          </div>
+          <pre className="mono max-h-64 overflow-auto whitespace-pre rounded-control border border-line bg-canvas p-3 text-muted">
+            {command}
+          </pre>
+          <p className="mt-2 text-muted">
+            Replace <span className="mono text-ink">localhost:50051</span> and
+            remove <span className="mono text-ink">-plaintext</span> when the
+            endpoint uses TLS.
+          </p>
+        </div>
+      </div>
+    </details>
+  );
+}

package/src/components/Markdown.tsx

@@ -17,6 +17,7 @@ import { headingSlug } from "../lib/derive";
 import { Mermaid } from "./Mermaid";
 import { MarkdownTable } from "./MarkdownTable";
 import { remarkTableDirective } from "../lib/table-directive";
+import { readmeAssetHref } from "../lib/readme-assets";
 
 function textOf(node: React.ReactNode): string {
   if (typeof node === "string" || typeof node === "number") return String(node);
@@ -146,9 +147,11 @@ function Pre(props: ComponentPropsWithoutRef<"pre">) {
 export function Markdown({
   children,
   mermaid = false,
+  sourceRoot,
 }: {
   children: string;
   mermaid?: boolean;
+  sourceRoot?: string;
 }) {
   return (
     <div className="prose">
@@ -164,6 +167,20 @@ export function Markdown({
           // said not to.
           table: MarkdownTable,
           ...(mermaid ? { pre: Pre } : {}),
+          ...(sourceRoot ? {
+            a: (props: ComponentPropsWithoutRef<"a">) => {
+              const href = typeof props.href === "string"
+                ? readmeAssetHref(sourceRoot, props.href, import.meta.env.BASE_URL)
+                : null;
+              return <a {...props} href={href ?? props.href} {...(href ? { target: "_blank", rel: "noreferrer" } : {})} />;
+            },
+            img: (props: ComponentPropsWithoutRef<"img">) => {
+              const src = typeof props.src === "string"
+                ? readmeAssetHref(sourceRoot, props.src, import.meta.env.BASE_URL)
+                : null;
+              return <img {...props} src={src ?? props.src} />;
+            },
+          } : {}),
         }}
       >
         {children}