@openforge-app/plugin-sdk 0.2.9 → 0.2.11

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 import type { Component } from 'svelte';
 import type { BrowserSurfacesAPI } from './browserSurfaces';
-import type { AgentSession, CommandInfo, FileContent, FileEntry, Project, ProjectAttention, ReviewPullRequest, Task, TaskWorkspaceInfo, WritableBoardStatus } from './domain';
+import type { BoardStatus, AgentSession, CommandInfo, FileContent, FileEntry, Project, ProjectAttention, ReviewPullRequest, Task, TaskWorkspaceInfo, WorktreeSource, 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;
@@ -17,7 +17,7 @@ export interface ValidationError {
     path: string;
     message: string;
 }
-declare const OPENFORGE_PLUGIN_CAPABILITY_TYPE_MEMBERS: readonly ['commands', 'events', 'views', 'injectionPoints', 'taskPane', 'taskStart', 'settings', 'background', 'backend', 'storage', 'context', 'navigation', 'tasks', 'projects', 'fs', 'shell', 'notifications', 'attention', 'system.openUrl', 'system.writeClipboardText', 'config', 'projectConfig', 'browserSurfaces', 'taskLinks', 'appEnablement', 'customSidebarNavigation', 'reviewUI'];
+declare const OPENFORGE_PLUGIN_CAPABILITY_TYPE_MEMBERS: readonly ['commands', 'events', 'views', 'injectionPoints', 'taskPane', 'taskStart', 'settings', 'background', 'backend', 'storage', 'context', 'navigation', 'tasks', 'projects', 'fs', 'shell', 'notifications', 'attention', 'system.openUrl', 'system.writeClipboardText', 'config', 'projectConfig', 'browserSurfaces', 'appEnablement', 'customSidebarNavigation', 'reviewUI'];
 export type OpenForgePluginCapability = (typeof OPENFORGE_PLUGIN_CAPABILITY_TYPE_MEMBERS)[number];
 export interface OpenForgePackageMetadata {
     id: string;
@@ -74,16 +74,6 @@ 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;
@@ -409,6 +399,9 @@ export interface UserDataFileRequest {
 export interface UserDataFileWriteRequest extends UserDataFileRequest {
     content: string;
 }
+export interface UserDataFileAppendResult {
+    sizeBytes: number;
+}
 export interface ExternalReadDirectoryRequest {
     root: string;
     path?: string | null;
@@ -417,6 +410,12 @@ export interface ExternalReadFileRequest {
     root: string;
     path: string;
 }
+export interface ExternalFileMetadata {
+    /** Stable while the same filesystem object is appended in place. */
+    identity: string;
+    sizeBytes: number;
+    modifiedAtMs: number | null;
+}
 export declare const DEFAULT_EXTERNAL_TEXT_FILE_CHUNK_SIZE_BYTES: number;
 export declare const MIN_EXTERNAL_TEXT_FILE_CHUNK_SIZE_BYTES = 4;
 export declare const MAX_EXTERNAL_TEXT_FILE_CHUNK_SIZE_BYTES: number;
@@ -425,17 +424,27 @@ export declare function resolveExternalTextFileChunkSize(chunkSizeBytes?: number
 export interface ExternalReadTextFileChunksRequest extends ExternalReadFileRequest {
     /** UTF-8 chunks contain at most this many bytes. Defaults to 64 KiB. */
     chunkSizeBytes?: number;
+    /** First byte to read. Must be a UTF-8 code point boundary. Defaults to zero. */
+    startOffsetBytes?: number;
+    /** Maximum total bytes to read. The range end must be a UTF-8 code point boundary. */
+    maxBytes?: number;
+    /** Fails the read if the file no longer has this identity. */
+    expectedIdentity?: string;
     /** Stops future reads. An in-flight host read may finish, but its result is discarded. */
     signal?: AbortSignal;
 }
 export interface UserDataFileSystemAPI {
     readDir(request?: UserDataDirectoryRequest): Promise<FileEntry[]>;
     readTextFile(request: UserDataFileRequest): Promise<string>;
+    /** Atomically replaces the file and syncs its contents before resolving. */
     writeTextFile(request: UserDataFileWriteRequest): Promise<void>;
+    /** Appends and syncs content before returning the resulting UTF-8 byte size. */
+    appendTextFile(request: UserDataFileWriteRequest): Promise<UserDataFileAppendResult>;
 }
 export interface ExternalReadFileSystemAPI {
     readDir(request: ExternalReadDirectoryRequest): Promise<FileEntry[]>;
     readTextFile(request: ExternalReadFileRequest): Promise<string>;
+    stat(request: ExternalReadFileRequest): Promise<ExternalFileMetadata>;
     /** Lazily reads a UTF-8 file without retaining a host file handle between chunks. */
     readTextFileChunks(request: ExternalReadTextFileChunksRequest): AsyncIterable<string>;
 }
@@ -457,10 +466,6 @@ export interface ShellSpawnRequest extends ShellSessionRequest {
 export interface ShellWriteRequest extends ShellSessionRequest {
     data: string;
 }
-export interface ShellTerminalQueryResponseRequest extends ShellSessionRequest {
-    ptyInstanceId: number;
-    data: string;
-}
 export interface ShellResizeRequest extends ShellSessionRequest {
     cols: number;
     rows: number;
@@ -469,9 +474,9 @@ export interface TerminalViewSnapshot {
     instanceId: number;
     watermark: number;
     data: string;
+    compatibilityData?: string;
 }
 export interface PtyBufferState {
-    authority?: 'xterm-authoritative' | 'ghostty-authoritative';
     buffer: string | null;
     snapshot?: TerminalViewSnapshot | null;
     isLive: boolean;
@@ -480,7 +485,6 @@ export interface PtyBufferState {
 export interface ShellAPI {
     spawn(request: ShellSpawnRequest): Promise<number>;
     write(request: ShellWriteRequest): Promise<void>;
-    writeTerminalQueryResponse(request: ShellTerminalQueryResponseRequest): Promise<void>;
     resize(request: ShellResizeRequest): Promise<void>;
     kill(request: ShellSessionRequest): Promise<void>;
     getBuffer(request: ShellSessionRequest): Promise<PtyBufferState>;
@@ -497,6 +501,14 @@ export interface ComposeTaskRequest {
     initialPrompt: string;
     sourceTicketUrl?: string | null;
     title?: string | null;
+    /** Seeds the dialog's worktree source instead of the project default. */
+    worktreeSource?: WorktreeSource | null;
+    /**
+     * When `worktreeSource` is `existingBranch`, seeds the branch selector.
+     * Pull-request head refs may be short names; the host maps them onto the
+     * stored selector value (`origin/<name>` when origin has the branch).
+     */
+    worktreeBranch?: string | null;
 }
 export interface ComposeTaskResult {
     task: Task;
@@ -542,6 +554,61 @@ export declare class TaskFollowUpError extends Error {
     readonly code: TaskFollowUpErrorCode;
     constructor(code: TaskFollowUpErrorCode, message: string);
 }
+export interface ListTaskSessionsRequest {
+    taskId: string;
+    /** Inclusive Unix timestamp in seconds. Omit to return the Task's full Agent Session history. */
+    createdAtOrAfter?: number;
+    /** Open-ended provider identifier such as `pi`. Omit to include every provider. */
+    provider?: string;
+}
+export declare const MAX_AGENT_SESSION_PAGE_SIZE = 250;
+export type AgentSessionCursor = string;
+export interface AgentSessionOverlap {
+    /** Inclusive lower bound as a Unix timestamp in seconds. */
+    startInclusive: number;
+    /** Exclusive upper bound as a Unix timestamp in seconds. */
+    endExclusive: number;
+}
+export interface ListAgentSessionsRequest {
+    /** Open-ended provider identifier such as `pi`. */
+    provider: string;
+    overlaps: AgentSessionOverlap;
+    /** Restrict the query to one Task without enumerating unrelated Tasks. */
+    taskId?: string;
+    /** Opaque cursor returned by the preceding page. */
+    cursor?: AgentSessionCursor;
+    /** Number of Agent Sessions to return, from 1 through 250. */
+    pageSize: number;
+}
+export interface AgentSessionTaskSummary {
+    id: string;
+    title: string;
+    status: BoardStatus;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface AgentSessionWorkspace {
+    rootPath: string;
+    kind: 'project' | 'worktree';
+}
+export interface AgentSessionSummary {
+    /** OpenForge Agent Session ID. */
+    id: string;
+    provider: string;
+    /** Provider-owned Agent Session ID, or null when the host has none. */
+    providerSessionId: string | null;
+    createdAt: number;
+    updatedAt: number;
+    task: AgentSessionTaskSummary;
+    workspace: AgentSessionWorkspace | null;
+}
+export interface AgentSessionSummaryPage {
+    items: AgentSessionSummary[];
+    nextCursor: AgentSessionCursor | null;
+}
+export interface AgentSessionsAPI {
+    list(request: ListAgentSessionsRequest): Promise<AgentSessionSummaryPage>;
+}
 export interface TasksAPI {
     /**
      * Lists tasks, optionally scoped to a project. By default done tasks are
@@ -559,7 +626,9 @@ export interface TasksAPI {
     /**
      * 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.
+     * before the task exists. Optional `worktreeSource` / `worktreeBranch` seed
+     * the environment controls the same way `title` and `sourceTicketUrl` seed
+     * their fields.
      * Resolves null if they dismiss it.
      */
     compose(request: ComposeTaskRequest): Promise<ComposeTaskResult | null>;
@@ -570,6 +639,8 @@ export interface TasksAPI {
     sendFollowUp(request: SendTaskFollowUpRequest): Promise<TaskFollowUpReceipt>;
     getWorkspace(taskId: string): Promise<TaskWorkspaceInfo | null>;
     getLatestSession(taskId: string): Promise<AgentSession | null>;
+    /** Returns matching Agent Sessions newest first. */
+    listSessions(request: ListTaskSessionsRequest): Promise<AgentSession[]>;
 }
 export interface ProjectsAPI {
     list(): Promise<Project[]>;
@@ -601,6 +672,7 @@ export interface OpenForgeCommonAPI {
     context: {
         getSnapshot(): OpenForgeContextSnapshot;
     };
+    agentSessions: AgentSessionsAPI;
     tasks: TasksAPI;
     projects: ProjectsAPI;
     fs: FileSystemAPI;
@@ -613,7 +685,6 @@ export interface OpenForgeCommonAPI {
 }
 export interface FrontendOpenForgeAPI extends OpenForgeCommonAPI {
     browserSurfaces: BrowserSurfacesAPI;
-    taskLinks: TaskLinksAPI;
     navigation: NavigationAPI;
     views: FrontendViewRegistry;
     taskUI: FrontendTaskUIRegistry;

package/dist/types.js

@@ -34,7 +34,6 @@ const OPENFORGE_PLUGIN_CAPABILITY_TYPE_MEMBERS = [
     'config',
     'projectConfig',
     'browserSurfaces',
-    'taskLinks',
     'appEnablement',
     'customSidebarNavigation',
     'reviewUI',
@@ -71,6 +70,7 @@ export class TaskFollowUpError extends Error {
         this.code = code;
     }
 }
+export const MAX_AGENT_SESSION_PAGE_SIZE = 250;
 export function makePluginViewKey(pluginId, viewId) {
     return `plugin:${pluginId}:${viewId}`;
 }

package/dist/ui/MarkdownContent.svelte

@@ -1,5 +1,7 @@
 <script lang="ts">
   import { onDestroy } from 'svelte'
+  import { getRenderedMermaidDiagram, getRenderedMermaidSvg, observeMermaidTheme, renderMermaidDiagrams, type RenderedMermaidDiagram } from '../mermaid'
+  import MermaidDiagramPreview from './MermaidDiagramPreview.svelte'
   import {
     getMarkdownRepositoryLinkSuffix,
     MARKDOWN_REMOTE_MEDIA_ATTRIBUTE,
@@ -37,7 +39,11 @@
   }: Props = $props()
 
   let root = $state<HTMLDivElement | null>(null)
+  let activeMermaidDiagram = $state<RenderedMermaidDiagram | null>(null)
   let imageResolutionId = 0
+  let mermaidRenderId = 0
+  let mermaidThemeRevision = $state(0)
+  let stopObservingMermaidTheme: (() => void) | undefined
   let html = $derived(renderMarkdownHtml(content, {
     imageBaseUrl: resolveRepositoryImage ? null : imageBaseUrl,
     markdownFilePath,
@@ -137,6 +143,31 @@
     }))
   }
 
+  function synchronizeActiveMermaidDiagram() {
+    if (!activeMermaidDiagram) return
+
+    const svg = getRenderedMermaidSvg(activeMermaidDiagram.wrapper)
+    activeMermaidDiagram = svg ? { ...activeMermaidDiagram, svg } : null
+  }
+
+  $effect(() => {
+    if (!root || stopObservingMermaidTheme) return
+    stopObservingMermaidTheme = observeMermaidTheme(root.ownerDocument, () => {
+      mermaidThemeRevision++
+    })
+  })
+
+  $effect(() => {
+    const runId = ++mermaidRenderId
+    void html
+    void mermaidThemeRevision
+    if (!root) return
+
+    void renderMermaidDiagrams(root, () => runId === mermaidRenderId).then(() => {
+      if (runId === mermaidRenderId) synchronizeActiveMermaidDiagram()
+    })
+  })
+
   $effect(() => {
     const runId = ++imageResolutionId
     void html
@@ -149,6 +180,9 @@
 
   onDestroy(() => {
     imageResolutionId++
+    mermaidRenderId++
+    activeMermaidDiagram = null
+    stopObservingMermaidTheme?.()
   })
 
   function openMarkdownLink(href: string, absoluteHref: string) {
@@ -190,6 +224,14 @@
   function handleClick(event: MouseEvent) {
     if (!(event.target instanceof Element)) return
 
+    const diagram = getRenderedMermaidDiagram(event.target)
+    if (diagram) {
+      event.preventDefault()
+      diagram.trigger.focus()
+      activeMermaidDiagram = diagram
+      return
+    }
+
     const image = findEventImage(event.target)
     if (image && onOpenImage && image.getAttribute('src')) {
       event.preventDefault()
@@ -221,3 +263,7 @@
 <div bind:this={root} role="presentation" class="markdown-body" onclick={handleClick} onkeydown={handleKeydown}>
   {@html html}
 </div>
+
+{#if activeMermaidDiagram}
+  <MermaidDiagramPreview svg={activeMermaidDiagram.svg} onClose={() => { activeMermaidDiagram = null }} />
+{/if}

package/dist/ui/MermaidDiagramPreview.svelte

@@ -0,0 +1,216 @@
+<script lang="ts">
+  import { onDestroy } from 'svelte'
+  import {
+    FIT_MERMAID_ZOOM,
+    calculateMermaidFitScale,
+    canZoomMermaidIn,
+    canZoomMermaidOut,
+    formatMermaidZoomLabel,
+    resetMermaidZoom,
+    resolveMermaidZoomScale,
+    zoomMermaidIn,
+    zoomMermaidOut,
+    type MermaidSize,
+    type MermaidZoomState,
+  } from '../mermaidZoom'
+  import Modal from './Modal.svelte'
+
+  interface Props {
+    svg: string
+    onClose: () => void
+  }
+
+  let { svg, onClose }: Props = $props()
+  let viewport = $state<HTMLDivElement | null>(null)
+  let svgHost = $state<HTMLDivElement | null>(null)
+  let closeButton = $state<HTMLButtonElement | null>(null)
+  let viewportSize = $state<MermaidSize>({ width: 0, height: 0 })
+  let zoom = $state<MermaidZoomState>(FIT_MERMAID_ZOOM)
+  let resizeObserver: ResizeObserver | undefined
+
+  function readSvgSize(markup: string): MermaidSize | null {
+    const template = document.createElement('template')
+    template.innerHTML = markup
+    const element = template.content.querySelector('svg')
+    if (!element) return null
+
+    const viewBox = element.getAttribute('viewBox')
+      ?.trim()
+      .split(/[\s,]+/)
+      .map(Number)
+    if (viewBox?.length === 4 && viewBox.every(Number.isFinite) && viewBox[2] > 0 && viewBox[3] > 0) {
+      return { width: viewBox[2], height: viewBox[3] }
+    }
+
+    const width = Number.parseFloat(element.getAttribute('width') ?? '')
+    const height = Number.parseFloat(element.getAttribute('height') ?? '')
+    return Number.isFinite(width) && Number.isFinite(height) && width > 0 && height > 0
+      ? { width, height }
+      : null
+  }
+
+  let diagramSize = $derived(readSvgSize(svg))
+  let fitScale = $derived(diagramSize
+    ? calculateMermaidFitScale(diagramSize, viewportSize)
+    : null)
+  let renderedScale = $derived(resolveMermaidZoomScale(zoom, fitScale))
+  let zoomLabel = $derived(formatMermaidZoomLabel(zoom, fitScale))
+  let renderedWidth = $derived(diagramSize ? diagramSize.width * renderedScale : null)
+  let renderedHeight = $derived(diagramSize ? diagramSize.height * renderedScale : null)
+
+  function updateViewportSize(width: number, height: number) {
+    if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return
+    viewportSize = { width, height }
+  }
+
+  $effect(() => {
+    if (!viewport || resizeObserver) return
+
+    const bounds = viewport.getBoundingClientRect()
+    updateViewportSize(bounds.width, bounds.height)
+    if (typeof ResizeObserver !== 'function') return
+
+    resizeObserver = new ResizeObserver((entries) => {
+      const entry = entries.find(candidate => candidate.target === viewport)
+      if (entry) updateViewportSize(entry.contentRect.width, entry.contentRect.height)
+    })
+    resizeObserver.observe(viewport)
+  })
+
+  $effect(() => {
+    void svg
+    if (!svgHost || renderedWidth === null || renderedHeight === null) return
+
+    const element = svgHost.querySelector('svg') as SVGSVGElement | null
+    if (!element) return
+    element.style.display = 'block'
+    element.style.width = `${renderedWidth}px`
+    element.style.height = `${renderedHeight}px`
+    element.style.maxWidth = 'none'
+  })
+
+  onDestroy(() => {
+    resizeObserver?.disconnect()
+    resizeObserver = undefined
+  })
+
+  function zoomIn() {
+    zoom = zoomMermaidIn(zoom, fitScale)
+  }
+
+  function zoomOut() {
+    zoom = zoomMermaidOut(zoom, fitScale)
+  }
+
+  function resetZoom() {
+    zoom = resetMermaidZoom()
+  }
+
+  function fitToWindow() {
+    zoom = FIT_MERMAID_ZOOM
+  }
+
+  function handleKeydown(event: KeyboardEvent): boolean | void {
+    if (event.metaKey || event.ctrlKey || event.altKey || event.defaultPrevented) return
+
+    if (event.key === '+' || event.key === '=') {
+      if (canZoomMermaidIn(zoom, fitScale)) zoomIn()
+    } else if (event.key === '-') {
+      if (canZoomMermaidOut(zoom, fitScale)) zoomOut()
+    } else if (event.key === '0') {
+      resetZoom()
+    } else if (event.key.toLowerCase() === 'f') {
+      fitToWindow()
+    } else {
+      return
+    }
+
+    event.preventDefault()
+    return true
+  }
+</script>
+
+<Modal
+  {onClose}
+  ariaLabel="Mermaid diagram preview"
+  showHeader={false}
+  maxWidth="calc(100vw - 2rem)"
+  boxClass="mermaid-diagram-preview h-[calc(100vh-2rem)] !max-h-[calc(100vh-2rem)] w-[calc(100vw-2rem)]"
+  initialFocus={() => closeButton}
+  onKeydown={handleKeydown}
+>
+  <div class="flex min-h-0 flex-1 flex-col bg-base-300/40">
+    <header class="mermaid-diagram-preview-toolbar flex min-h-14 shrink-0 items-center gap-2 border-b border-base-300 bg-base-100 px-4 py-2">
+      <h2 class="m-0 min-w-0 flex-1 truncate text-sm font-semibold text-base-content">Mermaid diagram preview</h2>
+
+      <div class="flex items-center gap-1" role="group" aria-label="Diagram zoom controls">
+        <button
+          type="button"
+          class="btn btn-ghost btn-sm h-11 min-h-11 w-11 p-0"
+          aria-label="Zoom out"
+          title="Zoom out (-)"
+          disabled={!canZoomMermaidOut(zoom, fitScale)}
+          onclick={zoomOut}
+        >
+          <svg class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true">
+            <circle cx="11" cy="11" r="8" />
+            <path d="m21 21-4.3-4.3M8 11h6" />
+          </svg>
+        </button>
+
+        <output class="min-w-20 text-center text-xs tabular-nums text-base-content/70" aria-live="polite">{zoomLabel}</output>
+
+        <button
+          type="button"
+          class="btn btn-ghost btn-sm h-11 min-h-11 w-11 p-0"
+          aria-label="Zoom in"
+          title="Zoom in (+)"
+          disabled={!canZoomMermaidIn(zoom, fitScale)}
+          onclick={zoomIn}
+        >
+          <svg class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true">
+            <circle cx="11" cy="11" r="8" />
+            <path d="m21 21-4.3-4.3M11 8v6M8 11h6" />
+          </svg>
+        </button>
+
+        <button
+          type="button"
+          class="btn btn-ghost btn-sm h-11 min-h-11 px-3"
+          aria-label="Reset zoom to 100%"
+          title="Reset zoom to 100% (0)"
+          onclick={resetZoom}
+        >100%</button>
+
+        <button
+          type="button"
+          class="btn btn-ghost btn-sm h-11 min-h-11 px-3"
+          aria-label="Fit diagram to window"
+          aria-pressed={zoom.mode === 'fit'}
+          title="Fit diagram to window (F)"
+          onclick={fitToWindow}
+        >Fit</button>
+      </div>
+
+      <button
+        bind:this={closeButton}
+        type="button"
+        class="btn btn-ghost btn-sm h-11 min-h-11 w-11 p-0"
+        aria-label="Close diagram preview"
+        onclick={onClose}
+      >
+        <svg class="size-5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true">
+          <path d="M18 6 6 18M6 6l12 12" />
+        </svg>
+      </button>
+    </header>
+
+    <div bind:this={viewport} data-testid="mermaid-preview-viewport" class="mermaid-diagram-preview-viewport min-h-0 flex-1 overflow-auto p-4">
+      <div data-testid="mermaid-preview-canvas" class="mermaid-diagram-preview-canvas flex h-max min-h-full w-max min-w-full items-center justify-center">
+        <div bind:this={svgHost} class="shrink-0">
+          {@html svg}
+        </div>
+      </div>
+    </div>
+  </div>
+</Modal>

package/dist/ui/Modal.svelte

@@ -4,12 +4,15 @@
 
   export type ModalInitialFocus = HTMLElement | string | (() => HTMLElement | null | undefined) | null | undefined
 
+  type ModalAccessibleName =
+    | { ariaLabel: string; ariaLabelledby?: never }
+    | { ariaLabel?: never; ariaLabelledby: string }
+
   interface Props {
     onClose: () => void
     maxWidth?: string
     overflowVisible?: boolean
     initialFocus?: ModalInitialFocus
-    ariaLabel?: string
     showHeader?: boolean
     closeLabel?: string
     closeDisabled?: boolean
@@ -21,7 +24,34 @@
     children: Snippet
   }
 
-  let { onClose, maxWidth = '500px', overflowVisible = false, initialFocus, ariaLabel, showHeader = true, closeLabel = 'Close dialog', closeDisabled = false, onKeydown, testId, modalClass = '', boxClass = '', header, children }: Props = $props()
+  let { onClose, maxWidth = '500px', overflowVisible = false, initialFocus, ariaLabel, ariaLabelledby, showHeader = true, closeLabel = 'Close dialog', closeDisabled = false, onKeydown, testId, modalClass = '', boxClass = '', header, children }: Props & ModalAccessibleName = $props()
+  let accessibleNameAttributes = $derived.by(() => {
+    const hasAriaLabel = Boolean(ariaLabel?.trim())
+    const hasAriaLabelledby = Boolean(ariaLabelledby?.trim())
+
+    if (hasAriaLabel === hasAriaLabelledby) {
+      throw new Error('Modal requires exactly one non-empty accessible name prop: ariaLabel or ariaLabelledby')
+    }
+
+    return {
+      ariaLabel: hasAriaLabel ? ariaLabel : undefined,
+      ariaLabelledby: hasAriaLabelledby ? ariaLabelledby : undefined,
+    }
+  })
+
+  $effect(() => {
+    const idReferences = accessibleNameAttributes.ariaLabelledby?.split(/\s+/)
+    if (!idReferences) return
+
+    const hasNamingText = idReferences.some((id) => {
+      const labelledElement = document.getElementById(id)
+      return Boolean(labelledElement?.textContent?.trim() || labelledElement?.getAttribute('aria-label')?.trim())
+    })
+
+    if (!hasNamingText) {
+      throw new Error('Modal ariaLabelledby must reference at least one element with naming text')
+    }
+  })
 
   let modalElement: HTMLDivElement | null = $state(null)
   let hasAppliedInitialFocus = false
@@ -142,14 +172,19 @@
   }
 </script>
 
-<div bind:this={modalElement} class="modal modal-open {modalClass}" data-testid={testId} onclick={handleOverlayClick} onkeydown={handleKeydown} role="dialog" aria-modal="true" aria-label={ariaLabel} tabindex="-1">
+<div bind:this={modalElement} class="modal modal-open {modalClass}" data-testid={testId} onclick={handleOverlayClick} onkeydown={handleKeydown} role="dialog" aria-modal="true" aria-label={accessibleNameAttributes.ariaLabel} aria-labelledby={accessibleNameAttributes.ariaLabelledby} tabindex="-1">
   <div class="modal-box bg-base-100 shadow-xl p-0 flex flex-col max-h-[90vh] {overflowVisible ? 'overflow-visible' : ''} {boxClass}" style="max-width: {maxWidth}">
     {#if showHeader}
       <div class="flex items-center justify-between px-5 py-4 border-b border-base-300">
         {#if header}
           {@render header()}
         {/if}
-        <button class="btn btn-ghost btn-xs shrink-0" aria-label={closeLabel} onclick={handleCloseButtonClick} type="button" disabled={closeDisabled}>✕</button>
+        <button class="btn btn-ghost h-11 min-h-11 w-11 min-w-11 shrink-0 p-0" aria-label={closeLabel} onclick={handleCloseButtonClick} type="button" disabled={closeDisabled}>
+          <svg class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">
+            <path d="M18 6 6 18" />
+            <path d="m6 6 12 12" />
+          </svg>
+        </button>
       </div>
     {/if}
     {@render children()}

package/dist/ui/PluginPageHeader.svelte

@@ -5,17 +5,24 @@
     title: string
     subtitle?: string | null
     surface?: 'default' | 'subtle'
+    headingLevel?: 'h1' | 'h2'
     actions?: Snippet
   }
 
-  let { title, subtitle = null, surface = 'subtle', actions }: Props = $props()
+  let {
+    title,
+    subtitle = null,
+    surface = 'default',
+    headingLevel = 'h1',
+    actions,
+  }: Props = $props()
 </script>
 
-<header class="flex items-center justify-between gap-4 border-b border-base-300 px-6 py-3 shrink-0 {surface === 'default' ? 'bg-base-100' : 'bg-base-200'}">
+<header class="flex min-h-13 shrink-0 flex-wrap items-center justify-between gap-x-4 gap-y-2 border-b border-base-300 px-4 py-2 sm:px-6 {surface === 'default' ? 'bg-base-100' : 'bg-base-200'}">
   <div class="min-w-0">
-    <h2 class="text-[22px] font-semibold text-base-content tracking-tight m-0 truncate">{title}</h2>
+    <svelte:element this={headingLevel} class="m-0 truncate text-base font-semibold leading-5 tracking-[-0.01em] text-base-content">{title}</svelte:element>
     {#if subtitle}
-      <p class="text-[13px] text-secondary mt-0.5 m-0 truncate">{subtitle}</p>
+      <p class="m-0 mt-0.5 truncate text-[13px] leading-5 text-base-content/60">{subtitle}</p>
     {/if}
   </div>
   {#if actions}

package/dist/ui/PluginPageShell.svelte

@@ -0,0 +1,20 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte'
+
+  interface Props {
+    header: Snippet
+    children: Snippet
+    class?: string
+  }
+
+  let { header, children, class: className = '' }: Props = $props()
+</script>
+
+<div class="flex h-full min-h-0 flex-col overflow-hidden bg-base-100 text-base-content {className}">
+  <div class="shrink-0">
+    {@render header()}
+  </div>
+  <div class="flex min-h-0 flex-1 flex-col overflow-hidden">
+    {@render children()}
+  </div>
+</div>