From b7273fb122ce34dcd02945ffe1b24d79021da966 Mon Sep 17 00:00:00 2001
From: Hiroshi Ogawa <hi.ogawa.zz@gmail.com>
Date: Wed, 22 Apr 2026 14:44:46 +0900
Subject: [PATCH 1/3] feat: export AriaRole and aria tree API jsdoc

---
 src/aria/index.ts | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/aria/index.ts b/src/aria/index.ts
index af592d1..4a95b30 100644
--- a/src/aria/index.ts
+++ b/src/aria/index.ts
@@ -12,7 +12,11 @@ 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'
 

From b79dc6d1cb3dd763452f7471b23397312bb49e71 Mon Sep 17 00:00:00 2001
From: Hiroshi Ogawa <hi.ogawa.zz@gmail.com>
Date: Wed, 22 Apr 2026 15:05:23 +0900
Subject: [PATCH 2/3] docs(aria): document public helpers

Add JSDoc to the original ARIA helper definitions so bundled declarations carry the docs downstream.

Co-authored-by: Codex <noreply@openai.com>
---
 src/aria/folk/injected/ariaSnapshot.ts | 10 ++++++++++
 src/aria/index.ts                      |  3 +++
 src/aria/match.ts                      |  6 ++++++
 src/aria/template.ts                   |  3 +++
 4 files changed, 22 insertions(+)

diff --git a/src/aria/folk/injected/ariaSnapshot.ts b/src/aria/folk/injected/ariaSnapshot.ts
index 06eb375..a477a86 100644
--- a/src/aria/folk/injected/ariaSnapshot.ts
+++ b/src/aria/folk/injected/ariaSnapshot.ts
@@ -32,6 +32,13 @@ const defaultBox: aria.AriaBox = { visible: true, inline: false }
 // capture – DOM -> AriaNode tree
 // ---------------------------------------------------------------------------
 
+// DIVERGENCE(playwright): add public JSDoc so downstream bundled declarations
+// carry descriptions for the exported ARIA helpers.
+/**
+ * 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 +317,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]
diff --git a/src/aria/index.ts b/src/aria/index.ts
index 4a95b30..9174b47 100644
--- a/src/aria/index.ts
+++ b/src/aria/index.ts
@@ -24,6 +24,9 @@ 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)
 }
diff --git a/src/aria/match.ts b/src/aria/match.ts
index 09c2bc6..ad47cdd 100644
--- a/src/aria/match.ts
+++ b/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
diff --git a/src/aria/template.ts b/src/aria/template.ts
index 353b436..972ed5e 100644
--- a/src/aria/template.ts
+++ b/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') {

From 2100e888dac11e559564f6ced2b9f6e9b597e4dc Mon Sep 17 00:00:00 2001
From: Hiroshi Ogawa <hi.ogawa.zz@gmail.com>
Date: Wed, 22 Apr 2026 15:21:03 +0900
Subject: [PATCH 3/3] deslop

---
 src/aria/folk/injected/ariaSnapshot.ts | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/aria/folk/injected/ariaSnapshot.ts b/src/aria/folk/injected/ariaSnapshot.ts
index a477a86..ce8b9f6 100644
--- a/src/aria/folk/injected/ariaSnapshot.ts
+++ b/src/aria/folk/injected/ariaSnapshot.ts
@@ -32,8 +32,6 @@ const defaultBox: aria.AriaBox = { visible: true, inline: false }
 // capture – DOM -> AriaNode tree
 // ---------------------------------------------------------------------------
 
-// DIVERGENCE(playwright): add public JSDoc so downstream bundled declarations
-// carry descriptions for the exported ARIA helpers.
 /**
  * Captures the ARIA tree for a DOM subtree.
  *