@puredesktop/puredesktop-ui-bridge 1.0.0-beta.1 → 2.1.0

package/src/components/accessibility/accessibilityReview.ts

@@ -1,639 +1,639 @@
-export type AccessibilityIssueSeverity = 'error' | 'warning' | 'notice'
-
-export type AccessibilityIssueCategory =
-  | 'content'
-  | 'headings'
-  | 'images'
-  | 'captions'
-  | 'tables'
-  | 'links'
-  | 'media'
-  | 'structure'
-
-export interface AccessibilityIssueFix {
-  label: string
-  description: string
-  action:
-    | 'set-empty-alt'
-    | 'use-caption-as-alt'
-    | 'add-figure-caption'
-    | 'add-table-caption'
-    | 'promote-first-row-headers'
-    | 'add-video-captions-track'
-    | 'remove-empty-heading'
-}
-
-export interface AccessibilityIssue {
-  id: string
-  ruleId: string
-  category: AccessibilityIssueCategory
-  severity: AccessibilityIssueSeverity
-  title: string
-  detail: string
-  target: string
-  targetLabel: string
-  wcag: string[]
-  standard: string
-  fix?: AccessibilityIssueFix
-}
-
-export interface AccessibilityIssueDraft {
-  label: string
-  description: string
-  value: string
-  applyLabel: string
-}
-
-const ISSUE_AUTHOR = 'Pure accessibility review'
-
-function parseHtml(html: string): Document {
-  return new DOMParser().parseFromString(`<main>${html}</main>`, 'text/html')
-}
-
-function serializeHtml(document: Document): string {
-  return document.body.querySelector('main')?.innerHTML ?? ''
-}
-
-function textOf(element: Element | null | undefined): string {
-  return (element?.textContent ?? '').replace(/\s+/g, ' ').trim()
-}
-
-function elementLabel(element: Element): string {
-  const tag = element.tagName.toLowerCase()
-  if (tag === 'img') {
-    return element.getAttribute('alt')?.trim() || 'image'
-  }
-  if (tag === 'table') {
-    return textOf(element.querySelector('caption')) || 'table'
-  }
-  return textOf(element).slice(0, 80) || tag
-}
-
-function nthOfType(element: Element): number {
-  let index = 1
-  let sibling = element.previousElementSibling
-  while (sibling) {
-    if (sibling.tagName === element.tagName) index += 1
-    sibling = sibling.previousElementSibling
-  }
-  return index
-}
-
-function selectorFor(element: Element): string {
-  const parts: string[] = []
-  let current: Element | null = element
-  while (current && current.tagName.toLowerCase() !== 'main') {
-    const tag = current.tagName.toLowerCase()
-    parts.unshift(`${tag}:nth-of-type(${nthOfType(current)})`)
-    current = current.parentElement
-  }
-  return parts.join(' > ')
-}
-
-function issueId(ruleId: string, target: string): string {
-  return `${ruleId}:${target}`
-}
-
-function pushIssue(
-  issues: AccessibilityIssue[],
-  input: Omit<AccessibilityIssue, 'id' | 'standard'>,
-): void {
-  issues.push({
-    ...input,
-    id: issueId(input.ruleId, input.target),
-    standard: 'WCAG 2.2',
-  })
-}
-
-function closestCaptionText(element: Element): string {
-  const figure = element.closest('figure')
-  return textOf(figure?.querySelector('figcaption'))
-}
-
-function clipDraft(input: string, maxLength = 140): string {
-  const text = input.replace(/\s+/g, ' ').trim()
-  if (text.length <= maxLength) return text
-  return `${text.slice(0, maxLength - 1).trim()}…`
-}
-
-function humanizePathPart(value: string): string {
-  const withoutQuery = value.split(/[?#]/)[0] ?? ''
-  const lastPart = withoutQuery.split('/').filter(Boolean).pop() ?? ''
-  const withoutExtension = lastPart.replace(/\.[a-z0-9]+$/i, '')
-  return withoutExtension
-    .replace(/[-_]+/g, ' ')
-    .replace(/\s+/g, ' ')
-    .trim()
-}
-
-function readableLinkDestination(href: string): string {
-  try {
-    const url = new URL(href, 'https://example.test')
-    const pathLabel = humanizePathPart(url.pathname)
-    if (pathLabel) return clipDraft(pathLabel, 80)
-    return url.hostname.replace(/^www\./, '')
-  } catch {
-    return clipDraft(humanizePathPart(href) || href, 80)
-  }
-}
-
-function nearbySentence(element: Element): string {
-  const candidates = [
-    element.previousElementSibling,
-    element.nextElementSibling,
-    element.parentElement?.previousElementSibling,
-    element.parentElement?.nextElementSibling,
-    element.closest('p'),
-  ]
-  for (const candidate of candidates) {
-    const text = textOf(candidate)
-    if (text) return clipDraft(text)
-  }
-  return ''
-}
-
-function tableCaptionDraft(table: Element): string {
-  const headers = Array.from(table.querySelectorAll('th'))
-    .map(header => textOf(header))
-    .filter(Boolean)
-  if (headers.length > 0) {
-    return clipDraft(`Table of ${headers.slice(0, 4).join(', ')}`)
-  }
-
-  const firstRowCells = Array.from(table.querySelectorAll('tr:first-child > *'))
-    .map(cell => textOf(cell))
-    .filter(Boolean)
-  if (firstRowCells.length > 0) {
-    return clipDraft(`Table of ${firstRowCells.slice(0, 4).join(', ')}`)
-  }
-
-  return nearbySentence(table) || 'Table summary'
-}
-
-function imageAltDraft(image: Element): string {
-  const caption = closestCaptionText(image)
-  if (caption) return clipDraft(caption)
-
-  const src = image.getAttribute('src') ?? ''
-  const sourceLabel = humanizePathPart(src)
-  if (sourceLabel) return clipDraft(sourceLabel, 100)
-
-  return nearbySentence(image) || 'Image description'
-}
-
-function figureCaptionDraft(figure: Element): string {
-  const image = figure.querySelector('img')
-  const alt = image?.getAttribute('alt')?.trim()
-  if (alt) return clipDraft(alt)
-
-  const sourceLabel = image ? humanizePathPart(image.getAttribute('src') ?? '') : ''
-  if (sourceLabel) return clipDraft(sourceLabel, 100)
-
-  return nearbySentence(figure) || 'Figure summary'
-}
-
-function hasAccessibleName(element: Element): boolean {
-  return Boolean(
-    element.getAttribute('aria-label')?.trim() ||
-      element.getAttribute('aria-labelledby')?.trim() ||
-      textOf(element),
-  )
-}
-
-export function auditHtmlAccessibility(html: string): AccessibilityIssue[] {
-  const document = parseHtml(html)
-  const main = document.body.querySelector('main')
-  if (!main) return []
-
-  const issues: AccessibilityIssue[] = []
-
-  const headings = Array.from(
-    main.querySelectorAll('h1,h2,h3,h4,h5,h6'),
-  ) as HTMLElement[]
-  let previousLevel = 0
-  for (const heading of headings) {
-    const target = selectorFor(heading)
-    const level = Number(heading.tagName.slice(1))
-    if (!textOf(heading)) {
-      pushIssue(issues, {
-        ruleId: 'empty-heading',
-        category: 'headings',
-        severity: 'error',
-        title: 'Empty heading',
-        detail:
-          'Headings need visible text so readers and assistive technology can understand the structure.',
-        target,
-        targetLabel: heading.tagName.toLowerCase(),
-        wcag: ['1.3.1 Info and Relationships', '2.4.6 Headings and Labels'],
-        fix: {
-          label: 'Remove heading',
-          description: 'Remove the empty heading element.',
-          action: 'remove-empty-heading',
-        },
-      })
-    }
-    if (previousLevel > 0 && level > previousLevel + 1) {
-      pushIssue(issues, {
-        ruleId: 'heading-level-jump',
-        category: 'headings',
-        severity: 'warning',
-        title: 'Heading level jumps',
-        detail: `This heading moves from h${previousLevel} to h${level}. Check whether the outline skips a section.`,
-        target,
-        targetLabel: textOf(heading) || heading.tagName.toLowerCase(),
-        wcag: ['1.3.1 Info and Relationships', '2.4.6 Headings and Labels'],
-      })
-    }
-    if (textOf(heading)) previousLevel = level
-  }
-
-  for (const image of Array.from(main.querySelectorAll('img'))) {
-    const target = selectorFor(image)
-    const hasAlt = image.hasAttribute('alt')
-    const alt = image.getAttribute('alt')?.trim() ?? ''
-    const caption = closestCaptionText(image)
-    if (!hasAlt) {
-      pushIssue(issues, {
-        ruleId: 'image-missing-alt',
-        category: 'images',
-        severity: 'error',
-        title: 'Image needs alt text or a decorative mark',
-        detail:
-          'Images need an accessible text alternative, unless they are purely decorative.',
-        target,
-        targetLabel: elementLabel(image),
-        wcag: ['1.1.1 Non-text Content'],
-        fix: {
-          label: 'Mark decorative',
-          description:
-            'Set alt="" so assistive technology can ignore the image.',
-          action: 'set-empty-alt',
-        },
-      })
-    } else if (alt && caption && alt.toLowerCase() === caption.toLowerCase()) {
-      pushIssue(issues, {
-        ruleId: 'image-alt-duplicates-caption',
-        category: 'images',
-        severity: 'notice',
-        title: 'Alt text repeats the caption',
-        detail:
-          'If the caption already explains the figure, the alt text may need a shorter functional description.',
-        target,
-        targetLabel: alt,
-        wcag: ['1.1.1 Non-text Content'],
-      })
-    }
-  }
-
-  for (const figure of Array.from(main.querySelectorAll('figure'))) {
-    if (!figure.querySelector('img,svg,canvas,pre[data-type="mermaid"]')) {
-      continue
-    }
-    const target = selectorFor(figure)
-    if (!textOf(figure.querySelector('figcaption'))) {
-      pushIssue(issues, {
-        ruleId: 'figure-missing-caption',
-        category: 'captions',
-        severity: 'warning',
-        title: 'Figure needs a caption',
-        detail:
-          'Figures should have captions when the image contributes to the argument or instructions.',
-        target,
-        targetLabel: elementLabel(figure),
-        wcag: ['1.1.1 Non-text Content', '1.3.1 Info and Relationships'],
-      })
-    }
-  }
-
-  for (const table of Array.from(main.querySelectorAll('table'))) {
-    const target = selectorFor(table)
-    if (!textOf(table.querySelector('caption'))) {
-      pushIssue(issues, {
-        ruleId: 'table-missing-caption',
-        category: 'tables',
-        severity: 'warning',
-        title: 'Table needs a caption',
-        detail:
-          'A caption gives the table a clear accessible name and helps readers understand its purpose.',
-        target,
-        targetLabel: elementLabel(table),
-        wcag: ['1.3.1 Info and Relationships'],
-      })
-    }
-    if (!table.querySelector('th')) {
-      pushIssue(issues, {
-        ruleId: 'table-no-headers',
-        category: 'tables',
-        severity: 'error',
-        title: 'Table has no header cells',
-        detail:
-          'Tables need header cells so row and column relationships are available to assistive technology.',
-        target,
-        targetLabel: elementLabel(table),
-        wcag: ['1.3.1 Info and Relationships'],
-        fix: {
-          label: 'Use first row as headers',
-          description: 'Convert the first row cells to column headers.',
-          action: 'promote-first-row-headers',
-        },
-      })
-    }
-  }
-
-  for (const link of Array.from(main.querySelectorAll('a'))) {
-    const target = selectorFor(link)
-    const label = textOf(link)
-    if (!link.getAttribute('href')?.trim()) {
-      pushIssue(issues, {
-        ruleId: 'link-missing-target',
-        category: 'links',
-        severity: 'error',
-        title: 'Link has no destination',
-        detail: 'Links need a destination or should be plain text.',
-        target,
-        targetLabel: label || 'link',
-        wcag: ['2.4.4 Link Purpose (In Context)'],
-      })
-    }
-    if (!hasAccessibleName(link)) {
-      pushIssue(issues, {
-        ruleId: 'link-empty-label',
-        category: 'links',
-        severity: 'error',
-        title: 'Link has no readable text',
-        detail:
-          'The link needs text or an accessible label that explains where it goes.',
-        target,
-        targetLabel: 'link',
-        wcag: ['2.4.4 Link Purpose (In Context)', '4.1.2 Name, Role, Value'],
-      })
-    } else if (/^(click here|here|read more|more)$/i.test(label)) {
-      pushIssue(issues, {
-        ruleId: 'link-ambiguous-label',
-        category: 'links',
-        severity: 'warning',
-        title: 'Link text is ambiguous',
-        detail:
-          'Link text should make sense out of context, especially in screen reader link lists.',
-        target,
-        targetLabel: label,
-        wcag: ['2.4.4 Link Purpose (In Context)'],
-      })
-    }
-  }
-
-  for (const media of Array.from(main.querySelectorAll('video,audio'))) {
-    const target = selectorFor(media)
-    if (!media.querySelector('track[kind="captions"],track[kind="subtitles"]')) {
-      pushIssue(issues, {
-        ruleId: 'media-missing-captions',
-        category: 'media',
-        severity: 'warning',
-        title: 'Media needs captions or a transcript',
-        detail:
-          'Audio and video should include captions, subtitles, or a nearby transcript.',
-        target,
-        targetLabel: media.tagName.toLowerCase(),
-        wcag: ['1.2.1 Audio-only and Video-only', '1.2.2 Captions'],
-        fix:
-          media.tagName.toLowerCase() === 'video'
-            ? {
-                label: 'Add captions track placeholder',
-                description: 'Insert a captions track placeholder.',
-                action: 'add-video-captions-track',
-              }
-            : undefined,
-      })
-    }
-  }
-
-  for (const iframe of Array.from(main.querySelectorAll('iframe'))) {
-    const target = selectorFor(iframe)
-    if (!iframe.getAttribute('title')?.trim()) {
-      pushIssue(issues, {
-        ruleId: 'frame-missing-title',
-        category: 'structure',
-        severity: 'error',
-        title: 'Embedded frame needs a title',
-        detail:
-          'Frames need titles so assistive technology can identify embedded content.',
-        target,
-        targetLabel: 'iframe',
-        wcag: ['4.1.2 Name, Role, Value'],
-      })
-    }
-  }
-
-  return issues
-}
-
-function findTarget(document: Document, issue: AccessibilityIssue): Element | null {
-  const main = document.body.querySelector('main')
-  return issue.target ? main?.querySelector(issue.target) ?? null : null
-}
-
-export function applyAccessibilityIssueFix(
-  html: string,
-  issue: AccessibilityIssue,
-): string {
-  if (!issue.fix) return html
-  const document = parseHtml(html)
-  const target = findTarget(document, issue)
-  if (!target) return html
-
-  switch (issue.fix.action) {
-    case 'set-empty-alt':
-      if (target instanceof HTMLImageElement) target.alt = ''
-      else target.setAttribute('alt', '')
-      break
-    case 'use-caption-as-alt': {
-      const caption = closestCaptionText(target)
-      if (caption) target.setAttribute('alt', caption)
-      break
-    }
-    case 'add-figure-caption': {
-      if (!target.querySelector('figcaption')) {
-        const caption = document.createElement('figcaption')
-        caption.textContent = 'Describe this figure.'
-        target.append(caption)
-      }
-      break
-    }
-    case 'add-table-caption': {
-      if (!target.querySelector('caption')) {
-        const caption = document.createElement('caption')
-        caption.textContent = 'Describe this table.'
-        target.prepend(caption)
-      }
-      break
-    }
-    case 'promote-first-row-headers': {
-      const firstRow = target.querySelector('tr')
-      if (firstRow) {
-        for (const cell of Array.from(firstRow.children)) {
-          if (cell.tagName.toLowerCase() !== 'td') continue
-          const header = document.createElement('th')
-          header.setAttribute('scope', 'col')
-          header.innerHTML = cell.innerHTML
-          for (const attr of Array.from(cell.attributes)) {
-            if (attr.name !== 'scope') header.setAttribute(attr.name, attr.value)
-          }
-          cell.replaceWith(header)
-        }
-      }
-      break
-    }
-    case 'add-video-captions-track': {
-      const track = document.createElement('track')
-      track.setAttribute('kind', 'captions')
-      track.setAttribute('src', '')
-      track.setAttribute('srclang', 'en')
-      track.setAttribute('label', 'English captions')
-      target.append(track)
-      break
-    }
-    case 'remove-empty-heading':
-      target.remove()
-      break
-  }
-
-  return serializeHtml(document)
-}
-
-export function getAccessibilityIssueDraft(
-  html: string,
-  issue: AccessibilityIssue,
-): AccessibilityIssueDraft | null {
-  const document = parseHtml(html)
-  const target = findTarget(document, issue)
-  if (!target) return null
-
-  switch (issue.ruleId) {
-    case 'image-missing-alt':
-      return {
-        label: 'Alt text',
-        description:
-          'A short description for readers who cannot see the image.',
-        value: imageAltDraft(target),
-        applyLabel: 'Use alt text',
-      }
-    case 'figure-missing-caption':
-      return {
-        label: 'Caption',
-        description: 'A visible caption that explains why this figure is here.',
-        value: figureCaptionDraft(target),
-        applyLabel: 'Add caption',
-      }
-    case 'table-missing-caption':
-      return {
-        label: 'Caption',
-        description: 'A brief table title for readers and assistive technology.',
-        value: tableCaptionDraft(target),
-        applyLabel: 'Add caption',
-      }
-    case 'link-empty-label':
-    case 'link-ambiguous-label': {
-      const href = target.getAttribute('href')?.trim() ?? ''
-      return {
-        label: 'Link text',
-        description: 'Text that still makes sense when read by itself.',
-        value: readableLinkDestination(href) || nearbySentence(target),
-        applyLabel: 'Use link text',
-      }
-    }
-    case 'frame-missing-title': {
-      const src = target.getAttribute('src')?.trim() ?? ''
-      return {
-        label: 'Frame title',
-        description: 'A short name for the embedded content.',
-        value: readableLinkDestination(src) || 'Embedded content',
-        applyLabel: 'Use title',
-      }
-    }
-    default:
-      return null
-  }
-}
-
-export function applyAccessibilityIssueDraft(
-  html: string,
-  issue: AccessibilityIssue,
-  value: string,
-): string {
-  const text = value.replace(/\s+/g, ' ').trim()
-  if (!text) return html
-
-  const document = parseHtml(html)
-  const target = findTarget(document, issue)
-  if (!target) return html
-
-  switch (issue.ruleId) {
-    case 'image-missing-alt':
-      target.setAttribute('alt', text)
-      break
-    case 'figure-missing-caption': {
-      let caption = target.querySelector('figcaption')
-      if (!caption) {
-        caption = document.createElement('figcaption')
-        target.append(caption)
-      }
-      caption.textContent = text
-      break
-    }
-    case 'table-missing-caption': {
-      let caption = target.querySelector('caption')
-      if (!caption) {
-        caption = document.createElement('caption')
-        target.prepend(caption)
-      }
-      caption.textContent = text
-      break
-    }
-    case 'link-empty-label':
-    case 'link-ambiguous-label':
-      target.textContent = text
-      break
-    case 'frame-missing-title':
-      target.setAttribute('title', text)
-      break
-    default:
-      return html
-  }
-
-  return serializeHtml(document)
-}
-
-function createCommentId(): string {
-  if (typeof crypto !== 'undefined' && 'randomUUID' in crypto) {
-    return `accessibility-${crypto.randomUUID()}`
-  }
-  return `accessibility-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
-}
-
-export function annotateAccessibilityIssue(
-  html: string,
-  issue: AccessibilityIssue,
-): string {
-  const document = parseHtml(html)
-  const target = findTarget(document, issue)
-  if (!target) return html
-
-  const classes = new Set(
-    (target.getAttribute('class') ?? '').split(/\s+/).filter(Boolean),
-  )
-  classes.add('comment-mark')
-  classes.add('comment-mark--agent-review')
-  target.setAttribute('class', Array.from(classes).join(' '))
-  target.setAttribute('data-comment-id', createCommentId())
-  target.setAttribute('data-comment-type', 'agent-review')
-  target.setAttribute(
-    'data-comment-text',
-    `${issue.title}: ${issue.detail} (${issue.standard} ${issue.wcag.join(', ')})`,
-  )
-  target.setAttribute('data-comment-author', ISSUE_AUTHOR)
-  target.setAttribute('data-comment-created-at', new Date().toISOString())
-  target.setAttribute('data-comment-replies', '[]')
-  target.setAttribute('title', `${ISSUE_AUTHOR}: ${issue.title}`)
-
-  return serializeHtml(document)
-}
+export type AccessibilityIssueSeverity = 'error' | 'warning' | 'notice'
+
+export type AccessibilityIssueCategory =
+  | 'content'
+  | 'headings'
+  | 'images'
+  | 'captions'
+  | 'tables'
+  | 'links'
+  | 'media'
+  | 'structure'
+
+export interface AccessibilityIssueFix {
+  label: string
+  description: string
+  action:
+    | 'set-empty-alt'
+    | 'use-caption-as-alt'
+    | 'add-figure-caption'
+    | 'add-table-caption'
+    | 'promote-first-row-headers'
+    | 'add-video-captions-track'
+    | 'remove-empty-heading'
+}
+
+export interface AccessibilityIssue {
+  id: string
+  ruleId: string
+  category: AccessibilityIssueCategory
+  severity: AccessibilityIssueSeverity
+  title: string
+  detail: string
+  target: string
+  targetLabel: string
+  wcag: string[]
+  standard: string
+  fix?: AccessibilityIssueFix
+}
+
+export interface AccessibilityIssueDraft {
+  label: string
+  description: string
+  value: string
+  applyLabel: string
+}
+
+const ISSUE_AUTHOR = 'Pure accessibility review'
+
+function parseHtml(html: string): Document {
+  return new DOMParser().parseFromString(`<main>${html}</main>`, 'text/html')
+}
+
+function serializeHtml(document: Document): string {
+  return document.body.querySelector('main')?.innerHTML ?? ''
+}
+
+function textOf(element: Element | null | undefined): string {
+  return (element?.textContent ?? '').replace(/\s+/g, ' ').trim()
+}
+
+function elementLabel(element: Element): string {
+  const tag = element.tagName.toLowerCase()
+  if (tag === 'img') {
+    return element.getAttribute('alt')?.trim() || 'image'
+  }
+  if (tag === 'table') {
+    return textOf(element.querySelector('caption')) || 'table'
+  }
+  return textOf(element).slice(0, 80) || tag
+}
+
+function nthOfType(element: Element): number {
+  let index = 1
+  let sibling = element.previousElementSibling
+  while (sibling) {
+    if (sibling.tagName === element.tagName) index += 1
+    sibling = sibling.previousElementSibling
+  }
+  return index
+}
+
+function selectorFor(element: Element): string {
+  const parts: string[] = []
+  let current: Element | null = element
+  while (current && current.tagName.toLowerCase() !== 'main') {
+    const tag = current.tagName.toLowerCase()
+    parts.unshift(`${tag}:nth-of-type(${nthOfType(current)})`)
+    current = current.parentElement
+  }
+  return parts.join(' > ')
+}
+
+function issueId(ruleId: string, target: string): string {
+  return `${ruleId}:${target}`
+}
+
+function pushIssue(
+  issues: AccessibilityIssue[],
+  input: Omit<AccessibilityIssue, 'id' | 'standard'>,
+): void {
+  issues.push({
+    ...input,
+    id: issueId(input.ruleId, input.target),
+    standard: 'WCAG 2.2',
+  })
+}
+
+function closestCaptionText(element: Element): string {
+  const figure = element.closest('figure')
+  return textOf(figure?.querySelector('figcaption'))
+}
+
+function clipDraft(input: string, maxLength = 140): string {
+  const text = input.replace(/\s+/g, ' ').trim()
+  if (text.length <= maxLength) return text
+  return `${text.slice(0, maxLength - 1).trim()}…`
+}
+
+function humanizePathPart(value: string): string {
+  const withoutQuery = value.split(/[?#]/)[0] ?? ''
+  const lastPart = withoutQuery.split('/').filter(Boolean).pop() ?? ''
+  const withoutExtension = lastPart.replace(/\.[a-z0-9]+$/i, '')
+  return withoutExtension
+    .replace(/[-_]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+function readableLinkDestination(href: string): string {
+  try {
+    const url = new URL(href, 'https://example.test')
+    const pathLabel = humanizePathPart(url.pathname)
+    if (pathLabel) return clipDraft(pathLabel, 80)
+    return url.hostname.replace(/^www\./, '')
+  } catch {
+    return clipDraft(humanizePathPart(href) || href, 80)
+  }
+}
+
+function nearbySentence(element: Element): string {
+  const candidates = [
+    element.previousElementSibling,
+    element.nextElementSibling,
+    element.parentElement?.previousElementSibling,
+    element.parentElement?.nextElementSibling,
+    element.closest('p'),
+  ]
+  for (const candidate of candidates) {
+    const text = textOf(candidate)
+    if (text) return clipDraft(text)
+  }
+  return ''
+}
+
+function tableCaptionDraft(table: Element): string {
+  const headers = Array.from(table.querySelectorAll('th'))
+    .map(header => textOf(header))
+    .filter(Boolean)
+  if (headers.length > 0) {
+    return clipDraft(`Table of ${headers.slice(0, 4).join(', ')}`)
+  }
+
+  const firstRowCells = Array.from(table.querySelectorAll('tr:first-child > *'))
+    .map(cell => textOf(cell))
+    .filter(Boolean)
+  if (firstRowCells.length > 0) {
+    return clipDraft(`Table of ${firstRowCells.slice(0, 4).join(', ')}`)
+  }
+
+  return nearbySentence(table) || 'Table summary'
+}
+
+function imageAltDraft(image: Element): string {
+  const caption = closestCaptionText(image)
+  if (caption) return clipDraft(caption)
+
+  const src = image.getAttribute('src') ?? ''
+  const sourceLabel = humanizePathPart(src)
+  if (sourceLabel) return clipDraft(sourceLabel, 100)
+
+  return nearbySentence(image) || 'Image description'
+}
+
+function figureCaptionDraft(figure: Element): string {
+  const image = figure.querySelector('img')
+  const alt = image?.getAttribute('alt')?.trim()
+  if (alt) return clipDraft(alt)
+
+  const sourceLabel = image ? humanizePathPart(image.getAttribute('src') ?? '') : ''
+  if (sourceLabel) return clipDraft(sourceLabel, 100)
+
+  return nearbySentence(figure) || 'Figure summary'
+}
+
+function hasAccessibleName(element: Element): boolean {
+  return Boolean(
+    element.getAttribute('aria-label')?.trim() ||
+      element.getAttribute('aria-labelledby')?.trim() ||
+      textOf(element),
+  )
+}
+
+export function auditHtmlAccessibility(html: string): AccessibilityIssue[] {
+  const document = parseHtml(html)
+  const main = document.body.querySelector('main')
+  if (!main) return []
+
+  const issues: AccessibilityIssue[] = []
+
+  const headings = Array.from(
+    main.querySelectorAll('h1,h2,h3,h4,h5,h6'),
+  ) as HTMLElement[]
+  let previousLevel = 0
+  for (const heading of headings) {
+    const target = selectorFor(heading)
+    const level = Number(heading.tagName.slice(1))
+    if (!textOf(heading)) {
+      pushIssue(issues, {
+        ruleId: 'empty-heading',
+        category: 'headings',
+        severity: 'error',
+        title: 'Empty heading',
+        detail:
+          'Headings need visible text so readers and assistive technology can understand the structure.',
+        target,
+        targetLabel: heading.tagName.toLowerCase(),
+        wcag: ['1.3.1 Info and Relationships', '2.4.6 Headings and Labels'],
+        fix: {
+          label: 'Remove heading',
+          description: 'Remove the empty heading element.',
+          action: 'remove-empty-heading',
+        },
+      })
+    }
+    if (previousLevel > 0 && level > previousLevel + 1) {
+      pushIssue(issues, {
+        ruleId: 'heading-level-jump',
+        category: 'headings',
+        severity: 'warning',
+        title: 'Heading level jumps',
+        detail: `This heading moves from h${previousLevel} to h${level}. Check whether the outline skips a section.`,
+        target,
+        targetLabel: textOf(heading) || heading.tagName.toLowerCase(),
+        wcag: ['1.3.1 Info and Relationships', '2.4.6 Headings and Labels'],
+      })
+    }
+    if (textOf(heading)) previousLevel = level
+  }
+
+  for (const image of Array.from(main.querySelectorAll('img'))) {
+    const target = selectorFor(image)
+    const hasAlt = image.hasAttribute('alt')
+    const alt = image.getAttribute('alt')?.trim() ?? ''
+    const caption = closestCaptionText(image)
+    if (!hasAlt) {
+      pushIssue(issues, {
+        ruleId: 'image-missing-alt',
+        category: 'images',
+        severity: 'error',
+        title: 'Image needs alt text or a decorative mark',
+        detail:
+          'Images need an accessible text alternative, unless they are purely decorative.',
+        target,
+        targetLabel: elementLabel(image),
+        wcag: ['1.1.1 Non-text Content'],
+        fix: {
+          label: 'Mark decorative',
+          description:
+            'Set alt="" so assistive technology can ignore the image.',
+          action: 'set-empty-alt',
+        },
+      })
+    } else if (alt && caption && alt.toLowerCase() === caption.toLowerCase()) {
+      pushIssue(issues, {
+        ruleId: 'image-alt-duplicates-caption',
+        category: 'images',
+        severity: 'notice',
+        title: 'Alt text repeats the caption',
+        detail:
+          'If the caption already explains the figure, the alt text may need a shorter functional description.',
+        target,
+        targetLabel: alt,
+        wcag: ['1.1.1 Non-text Content'],
+      })
+    }
+  }
+
+  for (const figure of Array.from(main.querySelectorAll('figure'))) {
+    if (!figure.querySelector('img,svg,canvas,pre[data-type="mermaid"]')) {
+      continue
+    }
+    const target = selectorFor(figure)
+    if (!textOf(figure.querySelector('figcaption'))) {
+      pushIssue(issues, {
+        ruleId: 'figure-missing-caption',
+        category: 'captions',
+        severity: 'warning',
+        title: 'Figure needs a caption',
+        detail:
+          'Figures should have captions when the image contributes to the argument or instructions.',
+        target,
+        targetLabel: elementLabel(figure),
+        wcag: ['1.1.1 Non-text Content', '1.3.1 Info and Relationships'],
+      })
+    }
+  }
+
+  for (const table of Array.from(main.querySelectorAll('table'))) {
+    const target = selectorFor(table)
+    if (!textOf(table.querySelector('caption'))) {
+      pushIssue(issues, {
+        ruleId: 'table-missing-caption',
+        category: 'tables',
+        severity: 'warning',
+        title: 'Table needs a caption',
+        detail:
+          'A caption gives the table a clear accessible name and helps readers understand its purpose.',
+        target,
+        targetLabel: elementLabel(table),
+        wcag: ['1.3.1 Info and Relationships'],
+      })
+    }
+    if (!table.querySelector('th')) {
+      pushIssue(issues, {
+        ruleId: 'table-no-headers',
+        category: 'tables',
+        severity: 'error',
+        title: 'Table has no header cells',
+        detail:
+          'Tables need header cells so row and column relationships are available to assistive technology.',
+        target,
+        targetLabel: elementLabel(table),
+        wcag: ['1.3.1 Info and Relationships'],
+        fix: {
+          label: 'Use first row as headers',
+          description: 'Convert the first row cells to column headers.',
+          action: 'promote-first-row-headers',
+        },
+      })
+    }
+  }
+
+  for (const link of Array.from(main.querySelectorAll('a'))) {
+    const target = selectorFor(link)
+    const label = textOf(link)
+    if (!link.getAttribute('href')?.trim()) {
+      pushIssue(issues, {
+        ruleId: 'link-missing-target',
+        category: 'links',
+        severity: 'error',
+        title: 'Link has no destination',
+        detail: 'Links need a destination or should be plain text.',
+        target,
+        targetLabel: label || 'link',
+        wcag: ['2.4.4 Link Purpose (In Context)'],
+      })
+    }
+    if (!hasAccessibleName(link)) {
+      pushIssue(issues, {
+        ruleId: 'link-empty-label',
+        category: 'links',
+        severity: 'error',
+        title: 'Link has no readable text',
+        detail:
+          'The link needs text or an accessible label that explains where it goes.',
+        target,
+        targetLabel: 'link',
+        wcag: ['2.4.4 Link Purpose (In Context)', '4.1.2 Name, Role, Value'],
+      })
+    } else if (/^(click here|here|read more|more)$/i.test(label)) {
+      pushIssue(issues, {
+        ruleId: 'link-ambiguous-label',
+        category: 'links',
+        severity: 'warning',
+        title: 'Link text is ambiguous',
+        detail:
+          'Link text should make sense out of context, especially in screen reader link lists.',
+        target,
+        targetLabel: label,
+        wcag: ['2.4.4 Link Purpose (In Context)'],
+      })
+    }
+  }
+
+  for (const media of Array.from(main.querySelectorAll('video,audio'))) {
+    const target = selectorFor(media)
+    if (!media.querySelector('track[kind="captions"],track[kind="subtitles"]')) {
+      pushIssue(issues, {
+        ruleId: 'media-missing-captions',
+        category: 'media',
+        severity: 'warning',
+        title: 'Media needs captions or a transcript',
+        detail:
+          'Audio and video should include captions, subtitles, or a nearby transcript.',
+        target,
+        targetLabel: media.tagName.toLowerCase(),
+        wcag: ['1.2.1 Audio-only and Video-only', '1.2.2 Captions'],
+        fix:
+          media.tagName.toLowerCase() === 'video'
+            ? {
+                label: 'Add captions track placeholder',
+                description: 'Insert a captions track placeholder.',
+                action: 'add-video-captions-track',
+              }
+            : undefined,
+      })
+    }
+  }
+
+  for (const iframe of Array.from(main.querySelectorAll('iframe'))) {
+    const target = selectorFor(iframe)
+    if (!iframe.getAttribute('title')?.trim()) {
+      pushIssue(issues, {
+        ruleId: 'frame-missing-title',
+        category: 'structure',
+        severity: 'error',
+        title: 'Embedded frame needs a title',
+        detail:
+          'Frames need titles so assistive technology can identify embedded content.',
+        target,
+        targetLabel: 'iframe',
+        wcag: ['4.1.2 Name, Role, Value'],
+      })
+    }
+  }
+
+  return issues
+}
+
+function findTarget(document: Document, issue: AccessibilityIssue): Element | null {
+  const main = document.body.querySelector('main')
+  return issue.target ? main?.querySelector(issue.target) ?? null : null
+}
+
+export function applyAccessibilityIssueFix(
+  html: string,
+  issue: AccessibilityIssue,
+): string {
+  if (!issue.fix) return html
+  const document = parseHtml(html)
+  const target = findTarget(document, issue)
+  if (!target) return html
+
+  switch (issue.fix.action) {
+    case 'set-empty-alt':
+      if (target instanceof HTMLImageElement) target.alt = ''
+      else target.setAttribute('alt', '')
+      break
+    case 'use-caption-as-alt': {
+      const caption = closestCaptionText(target)
+      if (caption) target.setAttribute('alt', caption)
+      break
+    }
+    case 'add-figure-caption': {
+      if (!target.querySelector('figcaption')) {
+        const caption = document.createElement('figcaption')
+        caption.textContent = 'Describe this figure.'
+        target.append(caption)
+      }
+      break
+    }
+    case 'add-table-caption': {
+      if (!target.querySelector('caption')) {
+        const caption = document.createElement('caption')
+        caption.textContent = 'Describe this table.'
+        target.prepend(caption)
+      }
+      break
+    }
+    case 'promote-first-row-headers': {
+      const firstRow = target.querySelector('tr')
+      if (firstRow) {
+        for (const cell of Array.from(firstRow.children)) {
+          if (cell.tagName.toLowerCase() !== 'td') continue
+          const header = document.createElement('th')
+          header.setAttribute('scope', 'col')
+          header.innerHTML = cell.innerHTML
+          for (const attr of Array.from(cell.attributes)) {
+            if (attr.name !== 'scope') header.setAttribute(attr.name, attr.value)
+          }
+          cell.replaceWith(header)
+        }
+      }
+      break
+    }
+    case 'add-video-captions-track': {
+      const track = document.createElement('track')
+      track.setAttribute('kind', 'captions')
+      track.setAttribute('src', '')
+      track.setAttribute('srclang', 'en')
+      track.setAttribute('label', 'English captions')
+      target.append(track)
+      break
+    }
+    case 'remove-empty-heading':
+      target.remove()
+      break
+  }
+
+  return serializeHtml(document)
+}
+
+export function getAccessibilityIssueDraft(
+  html: string,
+  issue: AccessibilityIssue,
+): AccessibilityIssueDraft | null {
+  const document = parseHtml(html)
+  const target = findTarget(document, issue)
+  if (!target) return null
+
+  switch (issue.ruleId) {
+    case 'image-missing-alt':
+      return {
+        label: 'Alt text',
+        description:
+          'A short description for readers who cannot see the image.',
+        value: imageAltDraft(target),
+        applyLabel: 'Use alt text',
+      }
+    case 'figure-missing-caption':
+      return {
+        label: 'Caption',
+        description: 'A visible caption that explains why this figure is here.',
+        value: figureCaptionDraft(target),
+        applyLabel: 'Add caption',
+      }
+    case 'table-missing-caption':
+      return {
+        label: 'Caption',
+        description: 'A brief table title for readers and assistive technology.',
+        value: tableCaptionDraft(target),
+        applyLabel: 'Add caption',
+      }
+    case 'link-empty-label':
+    case 'link-ambiguous-label': {
+      const href = target.getAttribute('href')?.trim() ?? ''
+      return {
+        label: 'Link text',
+        description: 'Text that still makes sense when read by itself.',
+        value: readableLinkDestination(href) || nearbySentence(target),
+        applyLabel: 'Use link text',
+      }
+    }
+    case 'frame-missing-title': {
+      const src = target.getAttribute('src')?.trim() ?? ''
+      return {
+        label: 'Frame title',
+        description: 'A short name for the embedded content.',
+        value: readableLinkDestination(src) || 'Embedded content',
+        applyLabel: 'Use title',
+      }
+    }
+    default:
+      return null
+  }
+}
+
+export function applyAccessibilityIssueDraft(
+  html: string,
+  issue: AccessibilityIssue,
+  value: string,
+): string {
+  const text = value.replace(/\s+/g, ' ').trim()
+  if (!text) return html
+
+  const document = parseHtml(html)
+  const target = findTarget(document, issue)
+  if (!target) return html
+
+  switch (issue.ruleId) {
+    case 'image-missing-alt':
+      target.setAttribute('alt', text)
+      break
+    case 'figure-missing-caption': {
+      let caption = target.querySelector('figcaption')
+      if (!caption) {
+        caption = document.createElement('figcaption')
+        target.append(caption)
+      }
+      caption.textContent = text
+      break
+    }
+    case 'table-missing-caption': {
+      let caption = target.querySelector('caption')
+      if (!caption) {
+        caption = document.createElement('caption')
+        target.prepend(caption)
+      }
+      caption.textContent = text
+      break
+    }
+    case 'link-empty-label':
+    case 'link-ambiguous-label':
+      target.textContent = text
+      break
+    case 'frame-missing-title':
+      target.setAttribute('title', text)
+      break
+    default:
+      return html
+  }
+
+  return serializeHtml(document)
+}
+
+function createCommentId(): string {
+  if (typeof crypto !== 'undefined' && 'randomUUID' in crypto) {
+    return `accessibility-${crypto.randomUUID()}`
+  }
+  return `accessibility-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+}
+
+export function annotateAccessibilityIssue(
+  html: string,
+  issue: AccessibilityIssue,
+): string {
+  const document = parseHtml(html)
+  const target = findTarget(document, issue)
+  if (!target) return html
+
+  const classes = new Set(
+    (target.getAttribute('class') ?? '').split(/\s+/).filter(Boolean),
+  )
+  classes.add('comment-mark')
+  classes.add('comment-mark--agent-review')
+  target.setAttribute('class', Array.from(classes).join(' '))
+  target.setAttribute('data-comment-id', createCommentId())
+  target.setAttribute('data-comment-type', 'agent-review')
+  target.setAttribute(
+    'data-comment-text',
+    `${issue.title}: ${issue.detail} (${issue.standard} ${issue.wcag.join(', ')})`,
+  )
+  target.setAttribute('data-comment-author', ISSUE_AUTHOR)
+  target.setAttribute('data-comment-created-at', new Date().toISOString())
+  target.setAttribute('data-comment-replies', '[]')
+  target.setAttribute('title', `${ISSUE_AUTHOR}: ${issue.title}`)
+
+  return serializeHtml(document)
+}