feat(parser): add YAHTML AST parser API

.github/workflows/ci.yaml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.2.2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run tests
+        run: bun run test

README.md

@@ -250,3 +250,31 @@ Converts a YAHTML array to an HTML string.
 - `TypeError`: If yahtmlContent is not an array
 - `Error`: If element structure is malformed
 
+#### `parseElementKey(key)`
+
+Parses a YAHTML element declaration key (selector + attrs) into structured metadata.
+
+**Parameters:**
+- `key` (string): Element key like `div#main.card data-id=42`
+
+**Returns:**
+- Parsed selector object with:
+  - `tag`, `id`, `classes`, `attributes`
+  - `ranges` for tag/id/class offsets within the key
+
+#### `parseYahtmlAst(yahtmlContent)`
+
+Builds an AST from YAHTML input without rendering HTML.
+
+**Parameters:**
+- `yahtmlContent` (Array): YAHTML content array
+
+**Returns:**
+- Root AST node:
+  - `{ type: "root", children: [...] }`
+- Child node kinds:
+  - `element`, `text`, `rawHtml`, `doctype`, `fragment`
+
+**Throws:**
+- `TypeError`: If `yahtmlContent` is not an array
+- `Error`: If an element declaration is malformed

index.cjs

@@ -9,7 +9,13 @@ module.exports = {
   convertToHtml: (...args) => {
     throw new Error('yahtml requires async initialization in CommonJS. Use: const yahtml = await require("yahtml")');
   },
-  SELF_CLOSING_TAGS: []
+  SELF_CLOSING_TAGS: [],
+  parseElementKey: (...args) => {
+    throw new Error('yahtml requires async initialization in CommonJS. Use: const yahtml = await require("yahtml")');
+  },
+  parseYahtmlAst: (...args) => {
+    throw new Error('yahtml requires async initialization in CommonJS. Use: const yahtml = await require("yahtml")');
+  }
 };
 
 // Async initialization for CommonJS
@@ -18,6 +24,8 @@ module.exports = (async () => {
   return {
     convertToHtml: mod.convertToHtml,
     SELF_CLOSING_TAGS: mod.SELF_CLOSING_TAGS,
+    parseElementKey: mod.parseElementKey,
+    parseYahtmlAst: mod.parseYahtmlAst,
     default: mod.convertToHtml
   };
-})();
+})();

index.d.ts

@@ -1,3 +1,3 @@
-export { convertToHtml, SELF_CLOSING_TAGS } from "./src/yahtml";
+export { convertToHtml, SELF_CLOSING_TAGS, parseElementKey, parseYahtmlAst } from "./src/yahtml";
 export default convertToHtml;
-declare const convertToHtml: typeof import("./src/yahtml").convertToHtml;
+declare const convertToHtml: typeof import("./src/yahtml").convertToHtml;

index.js

@@ -1,10 +1,10 @@
 /**
  * @module yahtml
  * @description YAHTML (YAML HTML) - Write HTML as valid YAML
- * @version 0.0.1
+ * @version 0.0.5
  * @license MIT
  */
 
-export { convertToHtml, SELF_CLOSING_TAGS } from './src/yahtml.js';
+export { convertToHtml, SELF_CLOSING_TAGS, parseElementKey, parseYahtmlAst } from './src/yahtml.js';
 import { convertToHtml } from './src/yahtml.js';
-export default convertToHtml;
+export default convertToHtml;

package.json

@@ -1,6 +1,6 @@
 {
   "name": "yahtml",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "YAHTML (YAML HTML) - Write HTML as valid YAML with clean, concise syntax",
   "keywords": [
     "html",