@openforge-app/plugin-sdk 0.1.0 → 0.2.3

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type { Component } from 'svelte';
-import type { AgentSession, FileContent, FileEntry, Project, ProjectAttention, Task, TaskWorkspaceInfo, WritableBoardStatus } from './domain';
+import type { BrowserSurfacesAPI } from './browserSurfaces';
+import type { AgentSession, CommandInfo, FileContent, FileEntry, Project, ProjectAttention, Task, TaskWorkspaceInfo, WritableBoardStatus } from './domain';
 export type SupportedOpenForgeApiVersion = 1;
 export declare const SUPPORTED_OPENFORGE_API_VERSIONS: readonly [1, ...1[]];
 export declare const OPENFORGE_PLUGIN_API_VERSION: SupportedOpenForgeApiVersion;
@@ -16,7 +17,7 @@ export interface ValidationError {
     path: string;
     message: string;
 }
-export type OpenForgePluginCapability = 'commands' | 'events' | 'views' | 'taskPane' | 'settings' | 'background' | 'backend' | 'storage' | 'context' | 'navigation' | 'tasks' | 'projects' | 'fs' | 'shell' | 'notifications' | 'attention' | 'system.openUrl' | 'config' | 'projectConfig';
+export type OpenForgePluginCapability = 'commands' | 'events' | 'views' | 'taskPane' | 'taskStart' | 'settings' | 'background' | 'backend' | 'storage' | 'context' | 'navigation' | 'tasks' | 'projects' | 'fs' | 'shell' | 'notifications' | 'attention' | 'system.openUrl' | 'system.writeClipboardText' | 'config' | 'projectConfig' | 'browserSurfaces' | 'taskLinks';
 export interface OpenForgePackageMetadata {
     id: string;
     apiVersion: SupportedOpenForgeApiVersion;
@@ -24,6 +25,7 @@ export interface OpenForgePackageMetadata {
     description: string;
     icon?: string;
     frontend?: string;
+    frontendStyles?: string[];
     backend?: string;
     requires?: OpenForgePluginCapability[];
 }
@@ -61,11 +63,23 @@ export interface OpenForgeNavigationRequest {
     viewId?: string;
     projectId?: string | null;
     taskId?: string | null;
+    /** Plugin-local Task UI tab id. Requires a non-null taskId. */
+    taskViewId?: string;
 }
 export interface NavigationAPI {
     get(): OpenForgeNavigationSnapshot;
     navigate(request: OpenForgeNavigationRequest): Promise<OpenForgeNavigationSnapshot>;
 }
+export interface TaskLinkOpenRequest {
+    taskId: string;
+    url: string;
+}
+export type TaskLinkHandlerResult = 'handled' | 'declined';
+export type TaskLinkHandler = (request: TaskLinkOpenRequest) => Promise<TaskLinkHandlerResult>;
+export interface TaskLinksAPI {
+    open(request: TaskLinkOpenRequest): Promise<void>;
+    registerHandler(handler: TaskLinkHandler): Disposable;
+}
 export interface OpenForgePluginContext {
     pluginId: string;
     apiVersion: SupportedOpenForgeApiVersion;
@@ -89,6 +103,33 @@ export type CommandShortcutMetadata = string | {
     scope?: 'global' | 'project' | 'task';
     when?: string;
 };
+export interface AgentCommandMetadata {
+    /** Concise guidance explaining when and why an agent should use this command. */
+    description: string;
+    /** Example plugin-owned JSON inputs. Task and Project context are supplied separately. */
+    examples?: JsonValue[];
+    /** Whether the command appears in the routine agent catalog. Defaults to true. */
+    discoverable?: boolean;
+}
+export type AgentCommandRuntime = 'backend' | 'frontend';
+/** Serializable agent-facing projection of a Plugin Command. Never contains its handler. */
+export interface AgentCommandDescriptor {
+    qualifiedId: string;
+    pluginId: string;
+    runtime: AgentCommandRuntime;
+    description: string;
+    examples: JsonValue[];
+    discoverable: boolean;
+    input?: JsonSchema;
+    output?: JsonSchema;
+}
+export type PluginCommandInvocationSource = 'agent-cli' | 'plugin';
+/** Host-resolved targeting information supplied separately from plugin-owned command input. */
+export interface PluginCommandInvocationContext {
+    taskId: string | null;
+    projectId: string | null;
+    source: PluginCommandInvocationSource;
+}
 export interface CommandRegistration<TInput = unknown, TOutput = unknown> {
     id: string;
     title: string;
@@ -96,9 +137,11 @@ export interface CommandRegistration<TInput = unknown, TOutput = unknown> {
     shortcut?: CommandShortcutMetadata;
     /** Whether this command should appear in user-facing discovery surfaces such as the Command Palette. Defaults to true. */
     discoverable?: boolean;
+    /** Explicitly opts this command into agent access. Omitted commands are unavailable to agents. */
+    agent?: AgentCommandMetadata;
     input?: JsonSchema;
     output?: JsonSchema;
-    handler(input: TInput): MaybePromise<TOutput>;
+    handler(input: TInput, context: PluginCommandInvocationContext): MaybePromise<TOutput>;
 }
 export interface CommandDescriptor {
     id: string;
@@ -116,7 +159,18 @@ export interface CommandRegistry {
     register<TInput = unknown, TOutput = unknown>(registration: CommandRegistration<TInput, TOutput>): Disposable;
     invoke<TOutput = unknown>(id: string, payload?: unknown): Promise<TOutput>;
     invokeGlobal<TOutput = unknown>(qualifiedId: string, payload?: unknown): Promise<TOutput>;
+    /** Plugin-registered commands (this and other enabled plugins). */
     list(): Promise<CommandDescriptor[]>;
+    /**
+     * The host's Claude skills/commands catalog for the given project (skills from
+     * `~/.claude`/`.agents`, builtin commands, and plugin-provided commands), as the
+     * app's own injectable/autocomplete surfaces see it. Omitting `projectId` (or
+     * passing null) yields only project-independent entries. Distinct from `list()`,
+     * which returns plugin-registered commands.
+     */
+    listCatalog(request?: {
+        projectId?: string | null;
+    }): Promise<CommandInfo[]>;
 }
 export type EventHandler<TPayload = unknown> = (payload: TPayload) => void;
 export interface EventRegistry {
@@ -140,14 +194,33 @@ export interface PluginTaskPaneProps extends Record<string, unknown> {
     taskId: string;
     projectId: string | null;
 }
+export interface PluginTaskUISectionProps extends PluginTaskPaneProps {
+    /** True while the host is running a task-scoped action represented by the section. */
+    taskActionPending: boolean;
+}
 export interface PluginSettingsSectionProps extends Record<string, unknown> {
     api: FrontendOpenForgeAPI;
     context: OpenForgeContextSnapshot;
 }
+/**
+ * Inline SVG geometry for a plugin view icon.
+ *
+ * The host sanitizes the markup, strips root sizing and accessibility metadata,
+ * renders it decoratively at the navigation surface's size, and uses the view
+ * title as the accessible navigation label. Plugins own the `viewBox`, paths,
+ * and paint. Use `currentColor` when the icon should follow host navigation
+ * states; literal safe colors remain plugin-owned and do not change with state.
+ */
+export interface PluginSvgIcon {
+    type: 'svg';
+    svg: string;
+}
+/** A host-registered icon name or inline SVG geometry. */
+export type PluginIcon = string | PluginSvgIcon;
 export interface PluginViewRegistration {
     id: string;
     title: string;
-    icon: string;
+    icon: PluginIcon;
     /**
      * Where the host surfaces the view's nav entry. `'rail'` (default) places it on
      * the icon rail; `'sidebar'` places it in the left projects sidebar. Either way
@@ -165,15 +238,72 @@ export interface PluginTaskPaneTabRegistration {
     order?: number;
     component: PluginComponentLoader<PluginTaskPaneProps> | PluginComponent<PluginTaskPaneProps>;
 }
+export interface PluginTaskUISectionRegistration {
+    id: string;
+    order?: number;
+    component: PluginComponentLoader<PluginTaskUISectionProps> | PluginComponent<PluginTaskUISectionProps>;
+}
+/**
+ * Where a settings section is surfaced. `'project'` (the default) renders it on the
+ * per-project settings page, scoped to the active project. `'global'` renders it
+ * inside the plugin's own card on the global settings page — for configuration that
+ * is one value for the whole app (an API key, a credential) rather than per-project.
+ */
+export type PluginSettingsSectionScope = 'project' | 'global';
 export interface PluginSettingsSectionRegistration {
     id: string;
     title: string;
     order?: number;
+    /** Defaults to `'project'` when omitted. */
+    scope?: PluginSettingsSectionScope;
     component: PluginComponentLoader<PluginSettingsSectionProps> | PluginComponent<PluginSettingsSectionProps>;
 }
 export interface FrontendViewRegistry {
     register(registration: PluginViewRegistration): Disposable;
 }
+export type InjectionPointLocation = 'createTaskPrompt' | 'agentSession' | 'backlogPrompt';
+export interface PluginInjectionPointProps extends Record<string, unknown> {
+    api: FrontendOpenForgeAPI;
+    context: OpenForgeContextSnapshot;
+    location: InjectionPointLocation;
+    projectId: string | null;
+    taskId: string | null;
+    onInsert: (text: string) => void;
+}
+export interface PluginInjectionPointRegistration {
+    id: string;
+    location: InjectionPointLocation;
+    component: PluginComponentLoader<PluginInjectionPointProps> | PluginComponent<PluginInjectionPointProps>;
+}
+export interface TaskStartPrefixContext {
+    /** The task being started, or null when the caller is authoring a new one. */
+    taskId: string | null;
+    projectId: string | null;
+}
+export interface TaskStartPrefixProviderRegistration {
+    id: string;
+    /** Menu label shown on the surface offering this provider. */
+    title: string;
+    /** Lower sorts first. Defaults to 0. */
+    order?: number;
+    /**
+     * Asks the user for a prefix. Returning null means they cancelled, and the
+     * task is not started. The host — not the provider — starts the task, so the
+     * diverged-branch gate, starting spinner and terminal handling all still run.
+     */
+    provide(context: TaskStartPrefixContext): MaybePromise<string | null>;
+}
+export interface FrontendTaskStartRegistry {
+    registerPrefixProvider(registration: TaskStartPrefixProviderRegistration): Disposable;
+}
+export interface FrontendInjectionPointRegistry {
+    register(registration: PluginInjectionPointRegistration): Disposable;
+}
+export interface FrontendTaskUIRegistry {
+    registerTab(registration: PluginTaskPaneTabRegistration): Disposable;
+    registerSection(registration: PluginTaskUISectionRegistration): Disposable;
+}
+/** @deprecated Use `FrontendTaskUIRegistry.registerTab` through `openforge.taskUI`. */
 export interface FrontendTaskPaneRegistry {
     registerTab(registration: PluginTaskPaneTabRegistration): Disposable;
 }
@@ -223,6 +353,7 @@ export interface FileSystemAPI {
         limit?: number;
     }): Promise<string[]>;
 }
+export type TerminalImageProtocol = 'iterm2';
 export interface ShellSessionRequest {
     taskId: string;
     terminalIndex: number;
@@ -231,6 +362,7 @@ export interface ShellSpawnRequest extends ShellSessionRequest {
     cwd: string;
     cols: number;
     rows: number;
+    terminalImageProtocol?: TerminalImageProtocol | null;
 }
 export interface ShellWriteRequest extends ShellSessionRequest {
     data: string;
@@ -252,10 +384,27 @@ export interface CreateTaskRequest {
     dependsOn?: string[];
     labelNames?: string[];
 }
+export interface ComposeTaskRequest {
+    projectId: string;
+    /** Seeds the dialog's prompt field; the user edits it before saving. */
+    initialPrompt: string;
+    sourceTicketUrl?: string | null;
+    title?: string | null;
+}
+export interface ComposeTaskResult {
+    task: Task;
+    /** True when the user chose Start Task rather than plain Create. */
+    started: boolean;
+}
 export interface StartPromptContribution {
+    /** Host-assigned identity of the plugin that owns this persisted contribution. */
+    readonly ownerPluginId?: string;
     id: string;
     enabled: boolean;
-    /** Prompt text injected before OpenForge's task prompt. The host substitutes {{taskId}} and {{task_id}}. */
+    /**
+     * Prompt text injected before OpenForge's task prompt.
+     * The host substitutes {{taskId}} and {{task_id}}.
+     */
     content: string;
     /** Lower values are injected first. Defaults to 0. */
     order?: number;
@@ -271,17 +420,47 @@ export interface ImplementationRun {
     sessionId: string;
     workspacePath: string;
 }
+export type TaskFollowUpDisposition = 'delivered' | 'queued';
+export interface SendTaskFollowUpRequest {
+    taskId: string;
+    message: string;
+}
+export interface TaskFollowUpReceipt {
+    taskId: string;
+    sessionId: string;
+    disposition: TaskFollowUpDisposition;
+}
+export type TaskFollowUpErrorCode = 'NO_SESSION' | 'DELIVERY_FAILED';
+export declare class TaskFollowUpError extends Error {
+    readonly code: TaskFollowUpErrorCode;
+    constructor(code: TaskFollowUpErrorCode, message: string);
+}
 export interface TasksAPI {
+    /**
+     * Lists tasks, optionally scoped to a project. By default done tasks are
+     * excluded (matching the app board's active-only view); pass
+     * `includeDone: true` to include tasks in the terminal `done` state. The
+     * unscoped listing (no `projectId`) always returns all states, so
+     * `includeDone` only affects the project-scoped path.
+     */
     list(request?: {
         projectId?: string | null;
+        includeDone?: boolean;
     }): Promise<Task[]>;
-    get(taskId: string): Promise<Task>;
+    get(taskId: string): Promise<Task | null>;
     create(request: CreateTaskRequest): Promise<Task>;
-    updateSummary(taskId: string, summary: string): Promise<void>;
+    /**
+     * Opens the host's create-task dialog pre-filled, letting the user edit the
+     * prompt — including anything contributed at that injection point —
+     * before the task exists.
+     * Resolves null if they dismiss it.
+     */
+    compose(request: ComposeTaskRequest): Promise<ComposeTaskResult | null>;
     updateStatus(taskId: string, status: WritableBoardStatus): Promise<void>;
     listStartPromptContributions(projectId: string): Promise<StartPromptContribution[]>;
     configureStartPromptContribution(request: ConfigureStartPromptContributionRequest): Promise<StartPromptContribution[]>;
     startImplementation(request: StartTaskImplementationRequest): Promise<ImplementationRun>;
+    sendFollowUp(request: SendTaskFollowUpRequest): Promise<TaskFollowUpReceipt>;
     getWorkspace(taskId: string): Promise<TaskWorkspaceInfo | null>;
     getLatestSession(taskId: string): Promise<AgentSession | null>;
 }
@@ -302,6 +481,7 @@ export interface AttentionAPI {
 }
 export interface SystemAPI {
     openUrl(url: string): Promise<void>;
+    writeClipboardText(text: string): Promise<void>;
 }
 export interface KeyValueConfigAPI {
     get<T extends JsonValue = JsonValue>(key: string, projectId?: string): Promise<T | null>;
@@ -325,11 +505,17 @@ export interface OpenForgeCommonAPI {
     projectConfig: KeyValueConfigAPI;
 }
 export interface FrontendOpenForgeAPI extends OpenForgeCommonAPI {
+    browserSurfaces: BrowserSurfacesAPI;
+    taskLinks: TaskLinksAPI;
     navigation: NavigationAPI;
     views: FrontendViewRegistry;
+    taskUI: FrontendTaskUIRegistry;
+    /** @deprecated Use `taskUI.registerTab(...)`. */
     taskPane: FrontendTaskPaneRegistry;
     settings: FrontendSettingsRegistry;
     backend: FrontendBackendBridge;
+    injectionPoints: FrontendInjectionPointRegistry;
+    taskStart: FrontendTaskStartRegistry;
 }
 export interface BackendOpenForgeAPI extends OpenForgeCommonAPI {
     backend: BackendMethodRegistry;

package/dist/types.js

@@ -10,6 +10,14 @@ export const SUPPORTED_OPENFORGE_API_VERSIONS = Object.freeze(readSupportedOpenF
 export const OPENFORGE_PLUGIN_API_VERSION = SUPPORTED_OPENFORGE_API_VERSIONS[0];
 export const MIN_SUPPORTED_API_VERSION = Math.min(...SUPPORTED_OPENFORGE_API_VERSIONS);
 export const MAX_SUPPORTED_API_VERSION = Math.max(...SUPPORTED_OPENFORGE_API_VERSIONS);
+export class TaskFollowUpError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'TaskFollowUpError';
+        this.code = code;
+    }
+}
 export function makePluginViewKey(pluginId, viewId) {
     return `plugin:${pluginId}:${viewId}`;
 }

package/dist/ui/Button.svelte

@@ -0,0 +1,49 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte'
+  import type { HTMLButtonAttributes } from 'svelte/elements'
+
+  type ButtonVariant = 'primary' | 'secondary' | 'outline' | 'ghost' | 'error'
+  type ButtonSize = 'xs' | 'sm' | 'md' | 'lg'
+
+  interface Props extends HTMLButtonAttributes {
+    children: Snippet
+    variant?: ButtonVariant
+    size?: ButtonSize
+  }
+
+  const variantClasses: Record<ButtonVariant, string> = {
+    primary: 'btn-primary',
+    secondary: 'btn-secondary',
+    outline: 'btn-outline',
+    ghost: 'btn-ghost',
+    error: 'btn-error',
+  }
+
+  const sizeClasses: Record<ButtonSize, string> = {
+    xs: 'btn-xs',
+    sm: 'btn-sm',
+    md: 'btn-md',
+    lg: 'btn-lg',
+  }
+
+  let {
+    children,
+    variant = 'primary',
+    size = 'md',
+    class: className,
+    disabled = false,
+    onclick,
+    ...attributes
+  }: Props = $props()
+</script>
+
+<button
+  {...attributes}
+  class={['btn', variantClasses[variant], sizeClasses[size], className]}
+  {disabled}
+  onclick={(event) => {
+    if (!disabled) onclick?.(event)
+  }}
+>
+  {@render children()}
+</button>

package/dist/ui/Checkbox.svelte

@@ -0,0 +1,137 @@
+<script lang="ts">
+  import type { HTMLInputAttributes } from 'svelte/elements'
+
+  type CheckboxSize = 'xs' | 'sm' | 'md'
+
+  interface Props extends Omit<HTMLInputAttributes, 'checked' | 'size' | 'type'> {
+    checked?: boolean
+    indeterminate?: boolean
+    size?: CheckboxSize
+  }
+
+  let {
+    checked = $bindable(false),
+    indeterminate = false,
+    size = 'sm',
+    class: className,
+    onchange,
+    ...attributes
+  }: Props = $props()
+
+  let input = $state<HTMLInputElement | null>(null)
+
+  $effect(() => {
+    if (input) input.indeterminate = indeterminate
+  })
+</script>
+
+<input
+  {...attributes}
+  bind:this={input}
+  bind:checked
+  type="checkbox"
+  class={["of-checkbox", className]}
+  data-size={size}
+  aria-checked={indeterminate ? 'mixed' : undefined}
+  {onchange}
+/>
+
+<style>
+  .of-checkbox {
+    width: 1.25rem;
+    height: 1.25rem;
+    flex: none;
+    appearance: none;
+    display: inline-grid;
+    place-content: center;
+    margin: 0;
+    border: 2px solid color-mix(in oklab, var(--color-base-content) 55%, transparent);
+    border-radius: 0.25rem;
+    background: var(--color-base-100);
+    color: var(--color-primary-content);
+    cursor: pointer;
+    transition:
+      background-color 150ms ease,
+      border-color 150ms ease,
+      box-shadow 150ms ease;
+  }
+
+  .of-checkbox::before {
+    width: 0.75rem;
+    height: 0.75rem;
+    background: currentColor;
+    clip-path: polygon(14% 44%, 0 59%, 40% 100%, 100% 19%, 84% 4%, 39% 73%);
+    content: '';
+    transform: scale(0);
+    transform-origin: center;
+    transition: transform 120ms ease-out;
+  }
+
+  .of-checkbox:hover:not(:disabled) {
+    border-color: var(--color-primary);
+  }
+
+  .of-checkbox:checked,
+  .of-checkbox:indeterminate {
+    border-color: var(--color-primary);
+    background: var(--color-primary);
+  }
+
+  .of-checkbox:checked::before {
+    transform: scale(1);
+  }
+
+  .of-checkbox:indeterminate::before {
+    width: 0.625rem;
+    height: 0.125rem;
+    clip-path: none;
+    transform: scale(1);
+  }
+
+  .of-checkbox:focus-visible {
+    outline: 2px solid var(--color-primary);
+    outline-offset: 2px;
+  }
+
+  .of-checkbox:disabled {
+    cursor: not-allowed;
+    opacity: 0.45;
+  }
+
+  .of-checkbox[data-size='xs'] {
+    width: 1rem;
+    height: 1rem;
+  }
+
+  .of-checkbox[data-size='xs']::before {
+    width: 0.625rem;
+    height: 0.625rem;
+  }
+
+  .of-checkbox[data-size='md'] {
+    width: 1.5rem;
+    height: 1.5rem;
+  }
+
+  .of-checkbox[data-size='md']::before {
+    width: 0.875rem;
+    height: 0.875rem;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .of-checkbox,
+    .of-checkbox::before {
+      transition: none;
+    }
+  }
+
+  @media (forced-colors: active) {
+    .of-checkbox {
+      appearance: auto;
+    }
+
+    .of-checkbox::before {
+      display: none;
+    }
+  }
+</style>

package/dist/ui/FileTypeIcon.svelte

@@ -0,0 +1,37 @@
+<script lang="ts">
+  import { getFileIconName, getFolderIconName } from '../fileIcons'
+
+  interface Props {
+    filename?: string
+    folder?: boolean
+    open?: boolean
+    class?: string
+  }
+
+  let { filename, folder = false, open = false, class: className = '' }: Props = $props()
+
+  // Curated, vendored set only (~45 files) — eager raw is fine and avoids runtime asset URLs.
+  const icons = import.meta.glob('./icons/*.svg', {
+    query: '?raw',
+    import: 'default',
+    eager: true,
+  }) as Record<string, string>
+
+  let iconName = $derived(folder ? getFolderIconName(open) : getFileIconName(filename ?? ''))
+  let svg = $derived(icons[`./icons/${iconName}.svg`] ?? icons['./icons/file.svg'] ?? '')
+</script>
+
+<span
+  class="file-type-icon inline-flex items-center justify-center shrink-0 {className}"
+  data-icon={iconName}
+  aria-hidden="true"
+>
+  {@html svg}
+</span>
+
+<style>
+  .file-type-icon :global(svg) {
+    width: 100%;
+    height: 100%;
+  }
+</style>

package/dist/ui/MarkdownContent.svelte

@@ -1,30 +1,90 @@
 <script lang="ts">
-  import { renderMarkdownHtml } from '../markdown'
+  import { onDestroy } from 'svelte'
+  import { getMarkdownRepositoryLinkSuffix, renderMarkdownHtml, resolveMarkdownRepositoryPath } from '../markdown'
 
   interface Props {
     content: string
     imageBaseUrl?: string | null
+    markdownFilePath?: string | null
+    resolveRepositoryImage?: (repositoryPath: string) => Promise<string | null>
+    onOpenRepositoryPath?: (repositoryPath: string, suffix: string) => void | Promise<void>
     onOpenUrl?: (url: string) => void | Promise<void>
   }
 
-  let { content, imageBaseUrl = null, onOpenUrl }: Props = $props()
+  let {
+    content,
+    imageBaseUrl = null,
+    markdownFilePath = null,
+    resolveRepositoryImage,
+    onOpenRepositoryPath,
+    onOpenUrl,
+  }: Props = $props()
 
-  let html = $derived(renderMarkdownHtml(content, { imageBaseUrl }))
+  let root = $state<HTMLDivElement | null>(null)
+  let imageResolutionId = 0
+  let html = $derived(renderMarkdownHtml(content, {
+    imageBaseUrl: resolveRepositoryImage ? null : imageBaseUrl,
+    markdownFilePath,
+    deferRepositoryImages: Boolean(resolveRepositoryImage),
+  }))
 
-  function handleClick(e: MouseEvent) {
-    if (!(e.target instanceof Element)) return
+  async function resolveRepositoryImages(runId: number) {
+    if (!root || !markdownFilePath || !resolveRepositoryImage) return
 
-    const anchor = e.target.closest('a')
-    if (anchor?.href) {
-      e.preventDefault()
-      if (onOpenUrl) {
-        void onOpenUrl(anchor.href)
+    const images = Array.from(root.querySelectorAll('img[data-markdown-repository-path]'))
+    await Promise.all(images.map(async (image) => {
+      const repositoryPath = image.getAttribute('data-markdown-repository-path')
+      if (!repositoryPath) return
+
+      try {
+        const resolvedSrc = await resolveRepositoryImage(repositoryPath)
+        if (runId !== imageResolutionId || !resolvedSrc) return
+        image.setAttribute('src', resolvedSrc)
+        image.removeAttribute('data-markdown-repository-path')
+      } catch {
+        // Leave the image inert when an asset is missing or cannot be previewed.
+      }
+    }))
+  }
+
+  $effect(() => {
+    const runId = ++imageResolutionId
+    void html
+    if (!root || !markdownFilePath || !resolveRepositoryImage) return
+
+    void resolveRepositoryImages(runId)
+  })
+
+  onDestroy(() => {
+    imageResolutionId++
+  })
+
+  function handleClick(event: MouseEvent) {
+    if (!(event.target instanceof Element)) return
+
+    const anchor = event.target.closest('a')
+    const href = anchor?.getAttribute('href')
+    if (!anchor || !href) return
+
+    if (markdownFilePath) {
+      const repositoryPath = resolveMarkdownRepositoryPath(href, markdownFilePath)
+      if (repositoryPath) {
+        event.preventDefault()
+        void onOpenRepositoryPath?.(repositoryPath, getMarkdownRepositoryLinkSuffix(href))
+        return
       }
     }
+
+    if (href.startsWith('#')) return
+
+    event.preventDefault()
+    if (onOpenUrl && anchor.href) {
+      void onOpenUrl(href.startsWith('//') ? `https:${href}` : anchor.href)
+    }
   }
 </script>
 
 <!-- svelte-ignore a11y_click_events_have_key_events -->
-<div role="presentation" class="markdown-body" onclick={handleClick}>
+<div bind:this={root} role="presentation" class="markdown-body" onclick={handleClick}>
   {@html html}
 </div>