@shipfox/client-workflows 15.0.0 → 16.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/client-workflows",
   "license": "MIT",
-  "version": "15.0.0",
+  "version": "16.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -27,15 +27,16 @@
   "dependencies": {
     "@swc/helpers": "^0.5.17",
     "date-fns": "^4.1.0",
-    "@shipfox/api-definitions-dto": "12.0.0",
-    "@shipfox/api-workflows-dto": "12.1.0",
+    "@shipfox/annotations-dto": "12.0.0",
+    "@shipfox/api-definitions-dto": "12.2.0",
+    "@shipfox/api-workflows-dto": "12.2.0",
+    "@shipfox/client-logs": "16.0.0",
     "@shipfox/client-api": "6.0.1",
-    "@shipfox/client-logs": "14.0.1",
-    "@shipfox/client-projects": "15.0.0",
-    "@shipfox/client-shell": "14.0.1",
-    "@shipfox/client-triggers": "15.0.0",
-    "@shipfox/client-ui": "14.0.1",
-    "@shipfox/react-ui": "1.0.0"
+    "@shipfox/client-shell": "16.0.0",
+    "@shipfox/react-ui": "1.1.0",
+    "@shipfox/client-ui": "16.0.0",
+    "@shipfox/client-triggers": "16.0.0",
+    "@shipfox/client-projects": "16.0.0"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.101.0",

package/src/components/job-detail/job-detail-header.test.tsx

@@ -23,6 +23,9 @@ describe('JobDetailHeader', () => {
         job={job}
         selectedJobExecution={execution}
         onSelectedJobExecutionChange={vi.fn()}
+        workspaceSlug="acme"
+        projectSlug="project"
+        workflowRunId="run-1"
       />,
     );
 

package/src/components/job-detail/job-detail-header.tsx

@@ -4,6 +4,7 @@ import {Code, Text} from '@shipfox/react-ui/typography';
 import {formatTimestamp} from '@shipfox/react-ui/utils';
 import {getWorkflowStatusVisual} from '#components/workflow-status/status-visuals.js';
 import {WorkflowStatusIcon} from '#components/workflow-status/workflow-status-icon.js';
+import type {RunAnnotationSummary} from '#core/run-annotation.js';
 import {
   defaultJobExecution,
   deriveJobDisplayStatus,
@@ -11,6 +12,7 @@ import {
   type Job,
   type JobExecution,
 } from '#core/workflow-run.js';
+import {RunAnnotationCountChip} from '../workflow-run-tabs/index.js';
 import {JobExecutionSwitcher} from './job-execution-switcher.js';
 import {JobExecutionTimeText} from './job-execution-time-text.js';
 
@@ -18,12 +20,23 @@ export interface JobDetailHeaderProps {
   job: Job;
   selectedJobExecution: JobExecution | undefined;
   onSelectedJobExecutionChange: (jobExecutionId: string) => void;
+  workspaceSlug: string;
+  projectSlug: string;
+  workflowRunId: string;
+  runAttempt?: number | undefined;
+  /** Counts for this job only. Renders a link into the run's Annotations section, never a body. */
+  annotationSummary?: RunAnnotationSummary | undefined;
 }
 
 export function JobDetailHeader({
   job,
   selectedJobExecution,
   onSelectedJobExecutionChange,
+  workspaceSlug,
+  projectSlug,
+  workflowRunId,
+  runAttempt,
+  annotationSummary,
 }: JobDetailHeaderProps) {
   const selectedStatus = selectedExecutionStatus(job, selectedJobExecution);
   const jobStatus = getWorkflowStatusVisual(selectedStatus);
@@ -39,7 +52,7 @@ export function JobDetailHeader({
             ariaLabel={`Job status: ${jobStatus.label}`}
           />
           <Code
-            as="h1"
+            as="h2"
             variant="paragraph"
             bold
             tabIndex={-1}
@@ -50,9 +63,9 @@ export function JobDetailHeader({
           </Code>
         </div>
 
-        {selectedJobExecution ? (
+        {selectedJobExecution || annotationSummary?.total ? (
           <div className="flex min-w-0 flex-wrap items-center gap-10 text-foreground-neutral-muted">
-            {job.executionCountVisible ? (
+            {selectedJobExecution && job.executionCountVisible ? (
               <JobExecutionSwitcher
                 job={job}
                 selectedJobExecution={selectedJobExecution.id}
@@ -60,8 +73,20 @@ export function JobDetailHeader({
                 variant="title"
               />
             ) : null}
-            <JobDurationMeta execution={selectedJobExecution} kind="queue" />
-            <JobDurationMeta execution={selectedJobExecution} kind="run" />
+            {selectedJobExecution ? (
+              <>
+                <JobDurationMeta execution={selectedJobExecution} kind="queue" />
+                <JobDurationMeta execution={selectedJobExecution} kind="run" />
+              </>
+            ) : null}
+            <RunAnnotationCountChip
+              summary={annotationSummary}
+              workspaceSlug={workspaceSlug}
+              projectSlug={projectSlug}
+              workflowRunId={workflowRunId}
+              runAttempt={runAttempt}
+              jobId={job.id}
+            />
           </div>
         ) : null}
       </div>

package/src/components/job-detail/job-detail-view.stories.tsx

@@ -7,6 +7,7 @@ import type {Meta, StoryObj} from '@storybook/react';
 import {QueryClient, QueryClientProvider} from '@tanstack/react-query';
 import {type ReactNode, useState} from 'react';
 import type {Job, JobExecution, WorkflowRunDetail} from '#core/workflow-run.js';
+import {runAnnotationsQueryKeys} from '#hooks/api/run-annotations.js';
 import type {useWorkflowRunAttemptQuery} from '#hooks/api/workflow-runs.js';
 import {
   workflowJob,
@@ -170,6 +171,10 @@ function StoryQueryProvider({
       defaultOptions: {queries: {staleTime: Number.POSITIVE_INFINITY}},
     });
     if (run) {
+      client.setQueryData(runAnnotationsQueryKeys.list(run.id, run.runAttempt.attempt), {
+        pages: [{annotations: [], hasMore: false, nextCursor: null}],
+        pageParams: [undefined],
+      });
       for (const job of run.jobs) {
         for (const execution of job.jobExecutions) {
           for (const step of execution.steps) {

package/src/components/job-detail/job-detail-view.tsx

@@ -10,7 +10,9 @@ import {TimeTickerProvider} from '@shipfox/react-ui/time-ticker';
 import {Text} from '@shipfox/react-ui/typography';
 import {Link} from '@tanstack/react-router';
 import {type RefObject, useEffect, useRef} from 'react';
+import {summarizeJobAnnotations} from '#core/run-annotation.js';
 import type {Job, JobExecution} from '#core/workflow-run.js';
+import {useRunAnnotationsQuery} from '#hooks/api/run-annotations.js';
 import type {useWorkflowRunAttemptQuery} from '#hooks/api/workflow-runs.js';
 import {
   type WorkflowJobSearch,
@@ -66,6 +68,16 @@ export function JobDetailView({
   const pageScrollRef = useRef<HTMLDivElement>(null);
   const landingSelectionRef = useRef<FrozenLandingSelection | undefined>(undefined);
   const hasLoadedData = query.data !== undefined;
+  // Same query key as the run workspace, so this reads the cache instead of fetching again.
+  const annotations = useRunAnnotationsQuery({
+    workflowRunId,
+    runAttempt: query.data?.runAttempt.attempt,
+  });
+  const jobAnnotationSummary = annotations.annotations
+    ? summarizeJobAnnotations(annotations.annotations, jobId, {
+        truncated: annotations.summary?.truncated ?? false,
+      })
+    : undefined;
 
   useEffect(() => {
     if (!jobId || !hasLoadedData) return;
@@ -206,8 +218,13 @@ export function JobDetailView({
                 job={job}
                 selectedJobExecution={selectedJobExecution}
                 onSelectedJobExecutionChange={selectExecution}
+                workspaceSlug={workspaceSlug}
+                projectSlug={projectSlug}
+                workflowRunId={workflowRunId}
+                runAttempt={run.runAttempt.attempt}
+                annotationSummary={jobAnnotationSummary}
               />
-              <Text as="h2" className="sr-only">
+              <Text as="h3" className="sr-only">
                 Logs
               </Text>
               {selectedJobExecution ? (

package/src/components/workflow-run-summary/workflow-run-summary.tsx

@@ -89,7 +89,7 @@ export function WorkflowRunSummary({
 
               <Tooltip>
                 <TooltipTrigger asChild>
-                  <Header id={headingId} variant="h3" className="min-w-0 truncate">
+                  <Header as="h1" id={headingId} variant="h3" className="min-w-0 truncate">
                     <span ref={headingTextRef} className="block min-w-0 truncate">
                       {run.name}
                     </span>

package/src/components/workflow-run-tabs/index.ts

@@ -1,2 +1,5 @@
+export {RunAnnotationCountChip} from './run-annotation-count-chip.js';
+export {annotationElementId, RunAnnotationItem} from './run-annotation-item.js';
+export {RunAnnotationList, type RunAnnotationListQuery} from './run-annotation-list.js';
 export {RunAnnotationSummaryLine} from './run-annotation-summary-line.js';
 export {RunAnnotationsEmpty} from './run-annotations-empty.js';

package/src/components/workflow-run-tabs/run-annotation-count-chip.tsx

@@ -0,0 +1,63 @@
+import {Icon} from '@shipfox/react-ui/icon';
+import {cn} from '@shipfox/react-ui/utils';
+import {Link} from '@tanstack/react-router';
+import {highestRunAnnotationSeverity, type RunAnnotationSummary} from '#core/run-annotation.js';
+import {type WorkflowRunsSearch, workflowRunSearchParams} from '#routes/inputs.js';
+import {SEVERITY_CHIP_TONE, SEVERITY_ICON} from './severity-visuals.js';
+
+export interface RunAnnotationCountChipProps {
+  summary: RunAnnotationSummary | undefined;
+  workspaceSlug: string;
+  projectSlug: string;
+  workflowRunId: string;
+  runAttempt?: number | undefined;
+  /** Scopes the destination list to one job. */
+  jobId?: string | undefined;
+}
+
+/**
+ * A bounded reference into the run's Annotations section: a count, its highest severity, and one
+ * link. Never a body, so an annotation is rendered exactly once per page.
+ */
+export function RunAnnotationCountChip({
+  summary,
+  workspaceSlug,
+  projectSlug,
+  workflowRunId,
+  runAttempt,
+  jobId,
+}: RunAnnotationCountChipProps) {
+  if (!summary || summary.total === 0) return null;
+
+  const severity = highestRunAnnotationSeverity(summary);
+  const count = `${summary.total}${summary.truncated ? '+' : ''}`;
+  const label = `${count} ${summary.total === 1 && !summary.truncated ? 'annotation' : 'annotations'}`;
+  const accessibleLabel = severity
+    ? `View ${label}, highest severity ${severity}`
+    : `View ${label}`;
+  const search: WorkflowRunsSearch = {tab: 'annotations', ...(runAttempt ? {runAttempt} : {})};
+  if (jobId) search.jobId = jobId;
+
+  return (
+    <Link
+      to="/w/$workspaceSlug/p/$projectSlug/runs/$workflowRunId"
+      params={{workspaceSlug, projectSlug, workflowRunId}}
+      search={workflowRunSearchParams(search, search) as never}
+      aria-label={accessibleLabel}
+      className={cn(
+        'inline-flex h-20 shrink-0 items-center gap-4 rounded-4 border px-6 font-code text-xs leading-16 tabular-nums outline-none transition-colors hover:bg-background-neutral-hover focus-visible:shadow-border-interactive-with-active',
+        // The chip stays 20px optically so it sits level with the duration metadata beside it;
+        // the hit area grows to the 44px minimum only where the pointer is coarse.
+        '[@media(pointer:coarse)]:h-44 [@media(pointer:coarse)]:px-10',
+        severity ? SEVERITY_CHIP_TONE[severity] : 'border-border-neutral-base',
+      )}
+    >
+      <Icon
+        name={severity ? SEVERITY_ICON[severity] : 'fileTextLine'}
+        size={12}
+        aria-hidden="true"
+      />
+      <span className="text-foreground-neutral-base">{count}</span>
+    </Link>
+  );
+}

package/src/components/workflow-run-tabs/run-annotation-item.tsx

@@ -0,0 +1,123 @@
+import {AnnotationCard} from '@shipfox/client-ui';
+import {Button} from '@shipfox/react-ui/button';
+import {Icon} from '@shipfox/react-ui/icon';
+import {Text} from '@shipfox/react-ui/typography';
+import {cn} from '@shipfox/react-ui/utils';
+import {Link} from '@tanstack/react-router';
+import {useEffect, useRef} from 'react';
+import type {RunAnnotationEntry} from '#core/run-annotation.js';
+import {workflowJobSearchParams} from '#routes/inputs.js';
+
+export interface RunAnnotationItemProps {
+  entry: RunAnnotationEntry;
+  workspaceSlug?: string | undefined;
+  projectSlug?: string | undefined;
+  workflowRunId: string;
+  runAttempt?: number | undefined;
+  /** Deep-link target from `?annotation=`, which takes focus rather than only being scrolled to. */
+  selected?: boolean | undefined;
+}
+
+/**
+ * One annotation, and the only place in the product that renders an annotation body.
+ *
+ * The title is the annotation's `context`, which is what the emitting step named the block.
+ * Everything below it exists so a reader can get from a diagnostic back to its cause.
+ */
+export function RunAnnotationItem({
+  entry,
+  workspaceSlug,
+  projectSlug,
+  workflowRunId,
+  runAttempt,
+  selected = false,
+}: RunAnnotationItemProps) {
+  const {annotation, origin} = entry;
+  const canLink = Boolean(origin && workspaceSlug && projectSlug);
+  const itemRef = useRef<HTMLLIElement>(null);
+  const focusedRef = useRef(false);
+
+  useEffect(() => {
+    if (!selected) {
+      focusedRef.current = false;
+      return;
+    }
+    if (focusedRef.current) return;
+
+    // A deep link that only scrolls leaves a keyboard or screen-reader user at the document
+    // start while the page moves under them.
+    focusedRef.current = true;
+    itemRef.current?.focus({preventScroll: true});
+    itemRef.current?.scrollIntoView({block: 'nearest'});
+  }, [selected]);
+
+  return (
+    <li
+      ref={itemRef}
+      tabIndex={-1}
+      aria-current={selected ? 'true' : undefined}
+      className={cn(
+        'rounded-8 outline-none focus-visible:shadow-border-interactive-with-active',
+        selected && 'shadow-border-interactive-with-active',
+      )}
+    >
+      <AnnotationCard
+        id={annotationElementId(annotation.id)}
+        style={annotation.style}
+        title={annotation.context}
+        titleAs="h3"
+        provenance={<RunAnnotationProvenance entry={entry} />}
+        body={annotation.body}
+        action={
+          canLink && origin ? (
+            <Button
+              asChild
+              size="xs"
+              variant="transparent"
+              className="[@media(pointer:coarse)]:min-h-44"
+            >
+              <Link
+                to="/w/$workspaceSlug/p/$projectSlug/runs/$workflowRunId/jobs/$jobId"
+                params={{
+                  workspaceSlug: workspaceSlug ?? '',
+                  projectSlug: projectSlug ?? '',
+                  workflowRunId,
+                  jobId: origin.jobId,
+                }}
+                search={
+                  workflowJobSearchParams({
+                    jobExecutionId: origin.jobExecutionId,
+                    stepId: origin.stepId,
+                    stepAttemptId: origin.stepAttemptId,
+                    runAttempt,
+                  }) as never
+                }
+              >
+                Open step
+                <Icon name="arrowRightLine" size={12} aria-hidden="true" />
+              </Link>
+            </Button>
+          ) : null
+        }
+      />
+    </li>
+  );
+}
+
+/** `job · execution #2 · run tests · attempt 1`, dropping any part the run no longer resolves. */
+function RunAnnotationProvenance({entry}: {entry: RunAnnotationEntry}) {
+  const parts = [entry.jobName, entry.executionLabel, entry.stepLabel, entry.attemptLabel].filter(
+    (part): part is string => Boolean(part),
+  );
+
+  return (
+    <Text as="p" size="xs" className="min-w-0 break-words font-code text-foreground-neutral-subtle">
+      {parts.join(' · ')}
+    </Text>
+  );
+}
+
+/** Stable element id so `?annotation=<id>` can scroll to and highlight one annotation. */
+export function annotationElementId(annotationId: string): string {
+  return `run-annotation-${annotationId}`;
+}

package/src/components/workflow-run-tabs/run-annotation-list.tsx

@@ -0,0 +1,258 @@
+import {QueryLoadError, type QueryLoadErrorQuery} from '@shipfox/client-ui';
+import {Button} from '@shipfox/react-ui/button';
+import {Callout} from '@shipfox/react-ui/callout';
+import {EmptyState} from '@shipfox/react-ui/empty-state';
+import {Skeleton} from '@shipfox/react-ui/skeleton';
+import {Text} from '@shipfox/react-ui/typography';
+import {useState} from 'react';
+import type {RunAnnotationEntry} from '#core/run-annotation.js';
+import {RunAnnotationItem} from './run-annotation-item.js';
+import {RunAnnotationsEmpty} from './run-annotations-empty.js';
+
+export interface RunAnnotationListQuery extends QueryLoadErrorQuery {
+  isPending: boolean;
+  hasNextPage: boolean;
+  isFetchingNextPage: boolean;
+  fetchNextPage: () => unknown;
+}
+
+export interface RunAnnotationListProps {
+  query: RunAnnotationListQuery;
+  entries: RunAnnotationEntry[] | undefined;
+  workflowRunId: string;
+  workspaceSlug?: string | undefined;
+  projectSlug?: string | undefined;
+  runAttempt?: number | undefined;
+  /** Name of the job the list is filtered to, used only for empty-state copy. */
+  filteredJobName?: string | undefined;
+  /** Active severity filter, named in the empty state so the reader knows what to clear. */
+  filteredSeverity?: string | undefined;
+  filtered: boolean;
+  onClearFilters?: (() => void) | undefined;
+  /** Annotation id from `?annotation=`, which the matching card scrolls to and focuses. */
+  selectedAnnotationId?: string | undefined;
+}
+
+/**
+ * How many annotations render at once.
+ *
+ * A page holds up to 500 rows and each one mounts a Markdown pipeline, so the fetch budget is
+ * not a render budget. The window grows on demand and the server page only loads once the
+ * reader has actually seen everything already fetched.
+ */
+const RENDER_WINDOW = 25;
+
+/**
+ * The annotations list.
+ *
+ * Loading, empty, error, and stale are four distinct renderings on purpose: coalescing a failed
+ * fetch into an empty result tells a reader their run is clean when the truth is unknown.
+ */
+export function RunAnnotationList({
+  query,
+  entries,
+  workflowRunId,
+  workspaceSlug,
+  projectSlug,
+  runAttempt,
+  filteredJobName,
+  filteredSeverity,
+  filtered,
+  onClearFilters,
+  selectedAnnotationId,
+}: RunAnnotationListProps) {
+  const [visibleCount, setVisibleCount] = useState(RENDER_WINDOW);
+
+  // A deep-linked annotation past the window would otherwise be unreachable: it is in the data,
+  // absent from the DOM, and nothing on screen says so.
+  const selectedIndex = selectedAnnotationId
+    ? (entries?.findIndex((entry) => entry.annotation.id === selectedAnnotationId) ?? -1)
+    : -1;
+  const renderCount = Math.max(visibleCount, selectedIndex + 1);
+
+  if (query.isPending) return <RunAnnotationListSkeleton />;
+
+  if (query.isError && entries === undefined) {
+    return <QueryLoadError query={query} subject="annotations" icon="fileDamageLine" />;
+  }
+
+  if (entries === undefined) return <RunAnnotationListSkeleton />;
+
+  const visible = entries.slice(0, renderCount);
+  const hiddenCount = entries.length - visible.length;
+
+  return (
+    <div className="flex min-w-0 flex-col gap-12">
+      {query.isError ? <RunAnnotationStaleError query={query} /> : null}
+
+      {entries.length === 0 ? (
+        filtered ? (
+          <RunAnnotationsFilteredEmpty
+            jobName={filteredJobName}
+            severity={filteredSeverity}
+            incomplete={query.hasNextPage}
+            onClearFilters={onClearFilters}
+          />
+        ) : (
+          <RunAnnotationsEmpty />
+        )
+      ) : (
+        <ol className="flex min-w-0 flex-col gap-12">
+          {visible.map((entry) => (
+            <RunAnnotationItem
+              key={entry.annotation.id}
+              entry={entry}
+              workspaceSlug={workspaceSlug}
+              projectSlug={projectSlug}
+              workflowRunId={workflowRunId}
+              runAttempt={runAttempt}
+              selected={entry.annotation.id === selectedAnnotationId}
+            />
+          ))}
+        </ol>
+      )}
+
+      {hiddenCount > 0 ? (
+        <Button
+          type="button"
+          size="sm"
+          variant="secondary"
+          className="self-start [@media(pointer:coarse)]:min-h-44"
+          onClick={() => setVisibleCount((current) => current + RENDER_WINDOW)}
+        >
+          Show {Math.min(hiddenCount, RENDER_WINDOW)} more of {entries.length}
+        </Button>
+      ) : query.hasNextPage ? (
+        <Button
+          type="button"
+          size="sm"
+          variant="secondary"
+          className="self-start [@media(pointer:coarse)]:min-h-44"
+          isLoading={query.isFetchingNextPage}
+          onClick={() => {
+            void query.fetchNextPage();
+          }}
+        >
+          Load more annotations
+        </Button>
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * Names the filters that are actually active.
+ *
+ * Blaming severity for a job-only filter sends the reader to change the wrong control, which
+ * is worse than saying nothing.
+ */
+function filteredEmptyDescription({
+  jobName,
+  severity,
+  incomplete,
+}: {
+  jobName: string | undefined;
+  severity: string | undefined;
+  incomplete: boolean;
+}): string {
+  if (incomplete) {
+    if (jobName && severity) {
+      return `None of the loaded annotations are from ${jobName} at ${severity} severity. Load more annotations to continue searching.`;
+    }
+    if (jobName) {
+      return `None of the loaded annotations are from ${jobName}. Load more annotations to continue searching.`;
+    }
+    if (severity) {
+      return `None of the loaded annotations are at ${severity} severity. Load more annotations to continue searching.`;
+    }
+    return 'None of the loaded annotations match the current filters. Load more annotations to continue searching.';
+  }
+  if (jobName && severity) {
+    return `This run has annotations, but none from ${jobName} at ${severity} severity.`;
+  }
+  if (jobName) return `This run has annotations, but none from ${jobName}.`;
+  if (severity) return `This run has annotations, but none at ${severity} severity.`;
+  return 'This run has annotations, but none match the current filters.';
+}
+
+function RunAnnotationsFilteredEmpty({
+  jobName,
+  severity,
+  incomplete,
+  onClearFilters,
+}: {
+  jobName: string | undefined;
+  severity: string | undefined;
+  incomplete: boolean;
+  onClearFilters: (() => void) | undefined;
+}) {
+  return (
+    <div className="flex flex-col items-center gap-12">
+      <EmptyState
+        icon="fileDamageLine"
+        title={incomplete ? 'No matches in loaded annotations' : 'No matching annotations'}
+        description={filteredEmptyDescription({jobName, severity, incomplete})}
+      />
+      {onClearFilters ? (
+        <Button
+          type="button"
+          size="sm"
+          variant="secondary"
+          className="[@media(pointer:coarse)]:min-h-44"
+          onClick={onClearFilters}
+        >
+          Clear filters
+        </Button>
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * A failed poll keeps the annotations already on screen and marks them stale rather than
+ * clearing. Polite rather than assertive: the poll runs every 4s and a flapping API would
+ * otherwise interrupt a screen reader on every cycle.
+ */
+function RunAnnotationStaleError({query}: {query: QueryLoadErrorQuery}) {
+  return (
+    <Callout role="status" aria-live="polite" type="error">
+      <div className="flex w-full items-center justify-between gap-8">
+        <Text size="xs">Could not refresh annotations.</Text>
+        <Button
+          type="button"
+          size="2xs"
+          variant="secondary"
+          className="[@media(pointer:coarse)]:min-h-44"
+          isLoading={query.isFetching}
+          onClick={() => {
+            void query.refetch();
+          }}
+        >
+          Retry
+        </Button>
+      </div>
+    </Callout>
+  );
+}
+
+const ANNOTATION_SKELETON_ROWS = ['first', 'second', 'third'];
+
+function RunAnnotationListSkeleton() {
+  return (
+    <section aria-label="Loading annotations" className="flex flex-col gap-12">
+      {ANNOTATION_SKELETON_ROWS.map((row) => (
+        <div
+          key={row}
+          className="flex gap-12 rounded-8 border border-border-neutral-base bg-background-components-base px-12 py-8"
+        >
+          <Skeleton className="h-40 w-4 rounded-full" />
+          <div className="flex min-w-0 flex-1 flex-col gap-6">
+            <Skeleton className="h-20 w-160 rounded-4" />
+            <Skeleton className="h-16 w-240 rounded-4" />
+            <Skeleton className="h-40 w-full rounded-4" />
+          </div>
+        </div>
+      ))}
+    </section>
+  );
+}