feat: export AriaRole type and add aria tree API jsdoc

src/aria/folk/injected/ariaSnapshot.ts

@@ -32,6 +32,11 @@ const defaultBox: aria.AriaBox = { visible: true, inline: false }
 // capture – DOM -> AriaNode tree
 // ---------------------------------------------------------------------------
 
+/**
+ * Captures the ARIA tree for a DOM subtree.
+ *
+ * The returned tree is the low-level structure used by ARIA snapshot matching.
+ */
 export function generateAriaTree(rootElement: Element): aria.AriaNode {
   const visited = new Set<Node>()
 
@@ -310,6 +315,9 @@ export function renderNodeLines(
   }
 }
 
+/**
+ * Renders a captured ARIA tree to the textual snapshot format.
+ */
 export function renderAriaTree(root: aria.AriaNode): string {
   const lines: string[] = []
   const nodesToRender = root.role === 'fragment' ? root.children : [root]

src/aria/index.ts

@@ -12,14 +12,21 @@ import {
 } from './folk/isomorphic/ariaSnapshot'
 import * as yaml from './yaml'
 
-export type { AriaNode, AriaTemplateNode } from './folk/isomorphic/ariaSnapshot'
+export type {
+  AriaNode,
+  AriaTemplateNode,
+  AriaRole,
+} from './folk/isomorphic/ariaSnapshot'
 
 export { generateAriaTree, renderAriaTree } from './folk/injected/ariaSnapshot'
 
 export { renderAriaTemplate } from './template'
 
 export { matchAriaTree } from './match'
 
+/**
+ * Parses textual ARIA snapshot syntax into a template tree.
+ */
 export function parseAriaTemplate(text: string): AriaTemplateNode {
   return parseAriaSnapshotUnsafe(yaml, text)
 }

src/aria/match.ts

@@ -111,6 +111,12 @@ export interface MatchAriaResult {
   resolved: string
 }
 
+/**
+ * Matches a captured ARIA tree against a parsed template.
+ *
+ * Returns whether the match passed and the resolved output used for diffing
+ * and snapshot updates.
+ */
 export function matchAriaTree(
   root: AriaNode,
   template: AriaTemplateNode

src/aria/template.ts

@@ -25,6 +25,9 @@ export function formatNameValue(name: AriaRegex | string): string {
   return `/${name.pattern}/`
 }
 
+/**
+ * Renders an ARIA template back to its textual snapshot representation.
+ */
 export function renderAriaTemplate(template: AriaTemplateNode): string {
   const lines: string[] = []
   if (template.kind === 'text') {