@markuplint/html-spec 4.16.1 → 5.0.0-alpha.0

package/ARCHITECTURE.ja.md

@@ -0,0 +1,285 @@
+# @markuplint/html-spec
+
+## 概要
+
+`@markuplint/html-spec` は HTML Living Standard のデータセットプロバイダです。TypeScript ソースコードを含まない純粋なデータパッケージであり、177 個の要素 JSON 仕様ファイルと 2 個の共通定義ファイルから構成されます。
+
+ビルド時に `@markuplint/spec-generator` が外部ソース（MDN、W3C ARIA 1.1/1.2/1.3、HTML Living Standard、SVG 仕様）からデータをフェッチし、手動で管理されたローカル仕様とマージして、統合された `index.json`（48,000 行以上、約 1.4MB）を生成します。手動データは常に外部データより優先され、仕様の正確性を保証します。
+
+## ディレクトリ構成
+
+```
+src/
+├── spec.a.jsonc                      # <a> 要素の仕様
+├── spec.abbr.jsonc                   # <abbr> 要素の仕様
+├── ... (計 177 個の要素仕様ファイル)
+├── spec.svg_text.jsonc               # <svg:text> 要素の仕様
+├── spec-common.attributes.jsonc      # 19 個のグローバル属性カテゴリ定義
+└── spec-common.contents.jsonc        # HTML 10 + SVG 19 のコンテンツモデルカテゴリ定義
+
+build.mjs                             # @markuplint/spec-generator を呼び出すビルドスクリプト
+index.json                            # 生成出力（48K 行以上、編集不可）
+index.js                              # CommonJS エントリーポイント
+index.d.ts                            # TypeScript 型宣言
+test/
+└── structure.spec.mjs                # スキーマ検証テスト
+```
+
+## アーキテクチャ図
+
+```mermaid
+flowchart TD
+    subgraph sources ["ソースデータ"]
+        specFiles["src/spec.*.jsonc\n(177 個の要素仕様)"]
+        commonAttrs["src/spec-common.attributes.jsonc\n(19 グローバル属性カテゴリ)"]
+        commonContents["src/spec-common.contents.jsonc\n(HTML 10 + SVG 19 コンテンツモデル)"]
+    end
+
+    subgraph build ["ビルドパイプライン"]
+        buildMjs["build.mjs"]
+        specGen["@markuplint/spec-generator\nmain()"]
+    end
+
+    subgraph external ["外部データソース"]
+        mdn["MDN Web Docs"]
+        aria["W3C ARIA\n(1.1 / 1.2 / 1.3)"]
+        htmlLs["HTML Living Standard"]
+        svg["SVG 仕様"]
+    end
+
+    subgraph output ["生成出力"]
+        indexJson["index.json\n(48K+ 行、統合データセット)"]
+    end
+
+    subgraph consumers ["利用パッケージ"]
+        mlCore["@markuplint/ml-core"]
+        rules["@markuplint/rules"]
+        mlSpec["@markuplint/ml-spec"]
+    end
+
+    specFiles --> buildMjs
+    commonAttrs --> buildMjs
+    commonContents --> buildMjs
+    buildMjs --> specGen
+
+    mdn --> specGen
+    aria --> specGen
+    htmlLs --> specGen
+    svg --> specGen
+
+    specGen -->|"手動データ優先で\n外部データとマージ"| indexJson
+
+    indexJson --> mlSpec
+    indexJson --> mlCore
+    indexJson --> rules
+```
+
+## データ構造
+
+`index.json` は 3 つのトップレベルキーで構成されます。
+
+### `cites`
+
+生成プロセス中にフェッチされた全 URL のソート済みリストです。データの出所を追跡するために使用されます。
+
+### `def`
+
+グローバル定義を格納するオブジェクトです。
+
+| キー             | 内容                                                                 |
+| ---------------- | -------------------------------------------------------------------- |
+| `#globalAttrs`   | 19 個のグローバル属性カテゴリ（`#HTMLGlobalAttrs` 等）               |
+| `#aria`          | バージョン別 ARIA 定義（1.1, 1.2, 1.3）                              |
+| `#contentModels` | コンテンツモデルカテゴリマクロ（HTML 10 カテゴリ + SVG 19 カテゴリ） |
+
+### `specs`
+
+全要素仕様の配列です。各要素は `contentModel`、`globalAttrs`、`attributes`、`aria` などのフィールドを持ちます。
+
+TypeScript 型は `index.d.ts` で以下のように宣言されます。
+
+```typescript
+import type { Cites, ElementSpec, SpecDefs } from '@markuplint/ml-spec';
+
+declare const json: {
+  cites: Cites;
+  def: SpecDefs;
+  specs: ElementSpec[];
+};
+
+export = json;
+```
+
+## 主要コンポーネント
+
+| コンポーネント | ファイル                                | 説明                                                          |
+| -------------- | --------------------------------------- | ------------------------------------------------------------- |
+| ソース仕様     | `src/spec.*.jsonc`（177 ファイル）      | 要素ごとの仕様定義（コンテンツモデル、属性、ARIA マッピング） |
+| 共通定義       | `src/spec-common.*.jsonc`（2 ファイル） | グローバル属性カテゴリとコンテンツモデルマクロの共有定義      |
+| ビルドシステム | `build.mjs`                             | `@markuplint/spec-generator` の `main()` を呼び出すエントリー |
+| 生成出力       | `index.json`                            | 統合データセット（48K 行以上、直接編集不可）                  |
+| 型宣言         | `index.d.ts`                            | `@markuplint/ml-spec` からの型を再エクスポート                |
+| スキーマ検証   | `test/structure.spec.mjs`               | Ajv ベースの JSON スキーマ検証テスト                          |
+
+## 要素仕様のフォーマット
+
+各 `src/spec.*.jsonc` ファイルは以下の構造を持ちます（例: `spec.a.jsonc`）。
+
+```jsonc
+// https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-a-element
+{
+  "contentModel": {
+    "contents": [
+      {
+        "transparent": ":not(:model(interactive), a, [tabindex])"
+      }
+    ]
+  },
+  "globalAttrs": {
+    "#HTMLGlobalAttrs": true,
+    "#GlobalEventAttrs": true,
+    "#ARIAAttrs": true,
+    "#HTMLLinkAndFetchingAttrs": ["href", "target", "download", "ping", "rel", "hreflang", "type", "referrerpolicy"]
+  },
+  "attributes": {},
+  "aria": {
+    "implicitRole": "link",
+    "permittedRoles": ["button", "checkbox", "menuitem", ...],
+    "properties": { ... },
+    "conditions": { ... }
+  }
+}
+```
+
+主要フィールドの説明:
+
+| フィールド     | 説明                                                                        |
+| -------------- | --------------------------------------------------------------------------- |
+| `contentModel` | 許可される子要素のパターン定義                                              |
+| `globalAttrs`  | 使用するグローバル属性カテゴリのマッピング（`true` で全属性、配列で選択的） |
+| `attributes`   | 要素固有の属性定義                                                          |
+| `aria`         | ARIA マッピング（暗黙ロール、許可ロール、プロパティ、条件分岐）             |
+
+## 共通定義ファイル
+
+### `spec-common.attributes.jsonc`
+
+19 個のグローバル属性カテゴリを定義します。カテゴリキーは `#` プレフィックスで参照されます。
+
+| カテゴリキー                | 内容                                               |
+| --------------------------- | -------------------------------------------------- |
+| `#HTMLGlobalAttrs`          | `accesskey`, `contenteditable`, `dir` 等の標準属性 |
+| `#GlobalEventAttrs`         | `onclick`, `onload` 等のイベントハンドラ属性       |
+| `#ARIAAttrs`                | `aria-*` 属性群                                    |
+| `#HTMLLinkAndFetchingAttrs` | `href`, `target`, `download` 等のリンク関連属性    |
+
+### `spec-common.contents.jsonc`
+
+コンテンツモデルカテゴリのマクロ定義です。
+
+- **HTML カテゴリ**（10 個）: `#metadata`, `#flow`, `#sectioning`, `#heading`, `#phrasing`, `#embedded`, `#interactive`, `#palpable`, `#scriptSupporting`, `#formAssociated`
+- **SVG カテゴリ**（19 個）: `#SVGAnimation`, `#SVGDescriptive`, `#SVGShape`, `#SVGStructural` 等
+
+## ビルドパイプライン
+
+ビルドは `build.mjs` を通じて `@markuplint/spec-generator` の `main()` 関数を呼び出します。
+
+```javascript
+import path from 'node:path';
+import { main } from '@markuplint/spec-generator';
+
+await main({
+  outputFilePath: path.resolve(import.meta.dirname, 'index.json'),
+  htmlFilePattern: path.resolve(import.meta.dirname, 'src', 'spec.*.jsonc'),
+  commonAttrsFilePath: path.resolve(import.meta.dirname, 'src', 'spec-common.attributes.jsonc'),
+  commonContentsFilePath: path.resolve(import.meta.dirname, 'src', 'spec-common.contents.jsonc'),
+});
+```
+
+ビルドプロセスの流れ:
+
+1. `src/spec.*.jsonc` と `src/spec-common.*.jsonc` を読み込む
+2. MDN、W3C ARIA（1.1/1.2/1.3）、HTML Living Standard、SVG 仕様から外部データをフェッチ
+3. 手動仕様と外部データをマージ（手動データが優先）
+4. 統合された `index.json` を出力
+
+ビルドコマンド:
+
+```bash
+# 生成 + フォーマット
+yarn gen
+
+# 生成のみ
+yarn gen:build
+
+# フォーマットのみ
+yarn gen:prettier
+```
+
+## テスト
+
+`test/structure.spec.mjs` は以下の検証を行います。
+
+1. **構造テスト**: 全要素仕様に対して `resolveNamespace()` と `getAttrSpecsByNames()` を呼び出し、属性仕様の整合性を確認
+2. **スキーマ検証**: Ajv を使用して各ソース JSON ファイルが `@markuplint/ml-spec` の JSON スキーマに適合することを検証
+   - `spec.*.jsonc` → `element.schema.json`（+ 関連スキーマ）
+   - `spec-common.attributes.jsonc` → `global-attributes.schema.json`
+
+## 外部依存パッケージ
+
+| パッケージ                   | 種別 | 用途                                         |
+| ---------------------------- | ---- | -------------------------------------------- |
+| `@markuplint/ml-spec`        | 本番 | 型定義（`Cites`, `ElementSpec`, `SpecDefs`） |
+| `@markuplint/spec-generator` | 開発 | ビルドパイプライン                           |
+| `@markuplint/test-tools`     | 開発 | テストユーティリティ（`glob` 等）            |
+
+## 他パッケージとの連携
+
+```mermaid
+flowchart LR
+    subgraph upstream ["上流パッケージ"]
+        specGen["@markuplint/spec-generator\n(ビルドパイプライン)"]
+        mlSpecTypes["@markuplint/ml-spec\n(型定義)"]
+    end
+
+    subgraph pkg ["@markuplint/html-spec"]
+        sourceData["ソース仕様\n(177 JSON + 2 共通)"]
+        buildScript["build.mjs"]
+        generatedJson["index.json"]
+    end
+
+    subgraph downstream ["下流パッケージ"]
+        mlSpec["@markuplint/ml-spec\n(アルゴリズム)"]
+        mlCore["@markuplint/ml-core"]
+        rules["@markuplint/rules"]
+        fwSpecs["フレームワーク仕様パッケージ\n(vue-spec, react-spec 等)"]
+    end
+
+    mlSpecTypes -->|"型定義\n(index.d.ts)"| pkg
+    specGen -->|"main()\n(ビルド時)"| buildScript
+    sourceData --> buildScript
+    buildScript --> generatedJson
+
+    generatedJson -->|"MLMLSpec JSON\n(ベースデータ)"| mlSpec
+    generatedJson -->|"要素仕様\nARIA 定義"| mlCore
+    generatedJson -->|"リントルール\nの参照データ"| rules
+    generatedJson -->|"拡張のベース"| fwSpecs
+```
+
+### 上流
+
+- **`@markuplint/ml-spec`** は `index.d.ts` で使用される型定義（`Cites`, `ElementSpec`, `SpecDefs`）を提供します。
+- **`@markuplint/spec-generator`** はビルド時に外部仕様のフェッチとデータ統合を担当します。
+
+### 下流
+
+- **`@markuplint/ml-spec`** は生成された `index.json` をベース `MLMLSpec` データとして読み込み、ARIA/HTML アルゴリズムに供給します。
+- **`@markuplint/ml-core`** は要素仕様と ARIA 定義を使用して、仕様認識を持つドキュメント表現を構築します。
+- **`@markuplint/rules`** は仕様データを参照してリントルール（ロール検証、コンテンツモデルチェック等）を実装します。
+- **フレームワーク仕様パッケージ**（`@markuplint/vue-spec`, `@markuplint/react-spec` 等）は `index.json` のデータをベースとして、フレームワーク固有の要素や属性を拡張します。
+
+## ドキュメントマップ
+
+- [要素仕様フォーマット](docs/element-spec-format.ja.md) -- 要素 JSON の構造、フィールド定義、条件分岐パターン
+- [ビルドパイプライン](docs/build-pipeline.ja.md) -- spec-generator の動作、外部データフェッチ、マージ戦略
+- [メンテナンスガイド](docs/maintenance.ja.md) -- 新規要素の追加、属性更新、外部仕様の変更対応

package/ARCHITECTURE.md

@@ -0,0 +1,202 @@
+# @markuplint/html-spec
+
+## Overview
+
+`@markuplint/html-spec` is the canonical HTML Living Standard dataset provider for markuplint. It is a pure data package with no TypeScript source code. It contains 177 per-element JSON specification files and 2 common definition files that are processed by `@markuplint/spec-generator` to produce a single consolidated `index.json` (48K+ lines, 1.4MB).
+
+During the build, `@markuplint/spec-generator` fetches live data from MDN, W3C ARIA specifications (1.1, 1.2, 1.3), Graphics ARIA, DPub ARIA, HTML-ARIA mappings, the HTML Living Standard, and SVG specifications, then merges that external data with the hand-authored JSON files. Manual specifications always take precedence over fetched data, ensuring stable, curated definitions while still benefiting from automated enrichment.
+
+## Directory Structure
+
+```
+src/
+├── spec.a.jsonc                      # <a> element specification
+├── spec.abbr.jsonc                   # <abbr> element specification
+├── ... (177 element specification files total)
+├── spec.svg_text.jsonc               # <svg:text> element specification
+├── spec-common.attributes.jsonc      # 19 global attribute category definitions
+└── spec-common.contents.jsonc        # 10 HTML + 19 SVG content model category definitions
+
+build.mjs                             # Build script invoking @markuplint/spec-generator
+index.json                            # Generated output (48K+ lines, DO NOT EDIT)
+index.js                              # CommonJS entry point (re-exports index.json)
+index.d.ts                            # TypeScript type declarations
+test/
+└── structure.spec.mjs                # Schema validation tests
+```
+
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+    subgraph sources ["Source Layer"]
+        elemSpecs["177 element specs\n(src/spec.*.jsonc)"]
+        commonAttrs["spec-common.attributes.jsonc\n(19 global attribute categories)"]
+        commonContents["spec-common.contents.jsonc\n(10 HTML + 19 SVG content models)"]
+    end
+
+    subgraph build ["Build Pipeline"]
+        buildScript["build.mjs"]
+        specGen["@markuplint/spec-generator\nmain()"]
+    end
+
+    subgraph external ["External Data Sources"]
+        mdn["MDN Web Docs\n(compatibility, descriptions)"]
+        aria["W3C ARIA Specs\n(1.1 / 1.2 / 1.3)"]
+        graphicsAria["Graphics ARIA"]
+        dpubAria["DPub ARIA"]
+        htmlAria["HTML-ARIA Mappings"]
+        htmlLS["HTML Living Standard\n(elements, attributes)"]
+        svg["SVG Specification\n(elements, attributes)"]
+    end
+
+    subgraph output ["Generated Output"]
+        indexJson["index.json\n(48K+ lines, 1.4MB)"]
+    end
+
+    subgraph consumers ["Downstream Consumers"]
+        mlCore["@markuplint/ml-core"]
+        rules["@markuplint/rules"]
+        fwSpecs["Framework spec packages\n(vue-spec, react-spec, etc.)"]
+    end
+
+    elemSpecs --> buildScript
+    commonAttrs --> buildScript
+    commonContents --> buildScript
+    buildScript --> specGen
+
+    mdn --> specGen
+    aria --> specGen
+    graphicsAria --> specGen
+    dpubAria --> specGen
+    htmlAria --> specGen
+    htmlLS --> specGen
+    svg --> specGen
+
+    specGen -->|"merge\n(manual takes precedence)"| indexJson
+
+    indexJson --> mlCore
+    indexJson --> rules
+    indexJson --> fwSpecs
+```
+
+## Data Structure
+
+The generated `index.json` contains three top-level keys:
+
+### `cites`
+
+A sorted list of all URLs fetched during generation. This provides traceability for every external data source that contributed to the output.
+
+### `def`
+
+Global definitions shared across all element specifications.
+
+| Key              | Description                                                                                                          |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `#globalAttrs`   | 19 global attribute categories defining attributes available on all or specific groups of elements                   |
+| `#aria`          | ARIA role and property definitions per specification version (1.1, 1.2, 1.3), plus Graphics ARIA and DPub ARIA roles |
+| `#contentModels` | Content model category macros mapping category names to their member elements                                        |
+
+**Global Attribute Categories** (`#globalAttrs`):
+
+| Category                            | Scope                                 |
+| ----------------------------------- | ------------------------------------- |
+| `#HTMLGlobalAttrs`                  | HTML global attributes                |
+| `#GlobalEventAttrs`                 | Global event handler attributes       |
+| `#ARIAAttrs`                        | ARIA state and property attributes    |
+| `#HTMLLinkAndFetchingAttrs`         | Link/fetch-related attributes         |
+| `#HTMLEmbededAndMediaContentAttrs`  | Embedded and media content attributes |
+| `#HTMLFormControlElementAttrs`      | Form control attributes               |
+| `#HTMLTableCellElementAttrs`        | Table cell attributes                 |
+| `#SVGAnimationAdditionAttrs`        | SVG animation addition attributes     |
+| `#SVGAnimationAttributeTargetAttrs` | SVG animation attribute target attrs  |
+| `#SVGAnimationEventAttrs`           | SVG animation event attributes        |
+| `#SVGAnimationTargetElementAttrs`   | SVG animation target element attrs    |
+| `#SVGAnimationTimingAttrs`          | SVG animation timing attributes       |
+| `#SVGAnimationValueAttrs`           | SVG animation value attributes        |
+| `#SVGConditionalProcessingAttrs`    | SVG conditional processing attributes |
+| `#SVGCoreAttrs`                     | SVG core attributes                   |
+| `#SVGFilterPrimitiveAttrs`          | SVG filter primitive attributes       |
+| `#SVGPresentationAttrs`             | SVG presentation attributes           |
+| `#SVGTransferFunctionAttrs`         | SVG transfer function attributes      |
+| `#XLinkAttrs`                       | XLink attributes                      |
+
+**Content Model Categories** (`#contentModels`):
+
+- **HTML (10):** `#metadata`, `#flow`, `#sectioning`, `#heading`, `#phrasing`, `#embedded`, `#interactive`, `#palpable`, `#script-supporting`, plus one empty placeholder
+- **SVG (19):** `#SVGAnimation`, `#SVGBasicShapes`, `#SVGContainer`, `#SVGDescriptive`, `#SVGFilterPrimitive`, `#SVGFont`, `#SVGGradient`, `#SVGGraphics`, `#SVGGraphicsReferencing`, `#SVGLightSource`, `#SVGNeverRendered`, `#SVGPaintServer`, `#SVGRenderable`, `#SVGShape`, `#SVGStructural`, `#SVGStructurallyExternal`, `#SVGTextContent`, `#SVGTextContentChild`, plus one empty placeholder
+
+### `specs`
+
+An array of element specifications. Each entry defines a single HTML or SVG element with its content model, permitted attributes, ARIA role mappings, and categorization.
+
+## Core Components
+
+| Component             | Files                                                        | Purpose                                                                        |
+| --------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| Source Specifications | 177 `src/spec.*.jsonc` files                                 | Per-element definitions: content models, attributes, ARIA mappings             |
+| Common Definitions    | `spec-common.attributes.jsonc`, `spec-common.contents.jsonc` | Shared global attribute categories and content model category macros           |
+| Build System          | `build.mjs`                                                  | Invokes `@markuplint/spec-generator` to merge sources with external data       |
+| Generated Output      | `index.json`                                                 | Single consolidated dataset consumed by downstream packages                    |
+| Type Declarations     | `index.d.ts`                                                 | Re-exports `Cites`, `ElementSpec`, `SpecDefs` from `@markuplint/ml-spec`       |
+| Schema Validation     | `test/structure.spec.mjs`                                    | Ajv-based validation of generated output against `@markuplint/ml-spec` schemas |
+
+## External Dependencies
+
+| Dependency                   | Type       | Purpose                                                      |
+| ---------------------------- | ---------- | ------------------------------------------------------------ |
+| `@markuplint/ml-spec`        | Production | Type definitions (`Cites`, `ElementSpec`, `SpecDefs`)        |
+| `@markuplint/spec-generator` | Dev        | Build pipeline: merges manual specs with MDN/W3C/WHATWG data |
+| `@markuplint/test-tools`     | Dev        | Test utilities (`glob` for file discovery)                   |
+
+## Integration Points
+
+```mermaid
+flowchart LR
+    subgraph upstream ["Upstream"]
+        mlSpec["@markuplint/ml-spec\n(types + schemas)"]
+        specGen["@markuplint/spec-generator\n(build tool)"]
+    end
+
+    subgraph pkg ["@markuplint/html-spec"]
+        srcData["177 element specs\n+ 2 common files"]
+        indexJson["index.json\n(generated output)"]
+    end
+
+    subgraph downstream ["Downstream"]
+        mlCore["@markuplint/ml-core"]
+        rules["@markuplint/rules"]
+        vueSpec["@markuplint/vue-spec"]
+        reactSpec["@markuplint/react-spec"]
+        otherSpec["Other framework specs"]
+    end
+
+    mlSpec -->|"types, schemas"| pkg
+    specGen -->|"build pipeline,\nexternal data fetching"| srcData
+
+    srcData -->|"build.mjs"| indexJson
+
+    indexJson -->|"MLMLSpec JSON"| mlCore
+    indexJson -->|"element specs,\nARIA definitions"| rules
+    indexJson -->|"base data\n(extended by frameworks)"| vueSpec
+    indexJson -->|"base data\n(extended by frameworks)"| reactSpec
+    indexJson -->|"base data\n(extended by frameworks)"| otherSpec
+```
+
+### Upstream
+
+- **`@markuplint/ml-spec`** provides the TypeScript type definitions (`MLMLSpec`, `ElementSpec`, `SpecDefs`) and JSON schemas used to validate the generated output. The `index.d.ts` re-exports these types.
+- **`@markuplint/spec-generator`** is the build tool invoked by `build.mjs`. It reads the source JSON files, fetches live data from MDN Web Docs, W3C ARIA specifications (versions 1.1, 1.2, 1.3), Graphics ARIA, DPub ARIA, HTML-ARIA mappings, the HTML Living Standard, and SVG specifications, then merges everything into `index.json`.
+
+### Downstream
+
+- **`@markuplint/ml-core`** loads the `MLMLSpec` JSON to build its internal representation of elements with spec awareness.
+- **`@markuplint/rules`** consumes element specifications and ARIA definitions to implement lint rules for role validation, content model checking, and accessibility auditing.
+- **Framework spec packages** (`@markuplint/vue-spec`, `@markuplint/react-spec`, etc.) extend this base dataset with framework-specific elements, attributes, and component definitions.
+
+## Documentation Map
+
+- [Element Specification Format](docs/element-spec-format.md) -- Structure and fields of per-element JSON files
+- [Build Pipeline](docs/build-pipeline.md) -- How build.mjs and spec-generator produce index.json
+- [Maintenance Guide](docs/maintenance.md) -- Adding elements, updating external sources, troubleshooting

package/CHANGELOG.md

@@ -3,13 +3,49 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [4.16.1](https://github.com/markuplint/markuplint/compare/@markuplint/html-spec@4.16.0...@markuplint/html-spec@4.16.1) (2025-11-05)
+# [5.0.0-alpha.0](https://github.com/markuplint/markuplint/compare/v4.14.1...v5.0.0-alpha.0) (2026-02-20)
 
-**Note:** Version bump only for package @markuplint/html-spec
+### Bug Fixes
+
+- **html-spec:** add aria-valuenow restrictions and missing alt fields ([b5af2b5](https://github.com/markuplint/markuplint/commit/b5af2b57238e40c4bf807fb968b4309871709046)), closes [#3214](https://github.com/markuplint/markuplint/issues/3214) [#2465](https://github.com/markuplint/markuplint/issues/2465)
+- **html-spec:** add missing dpub-aria source URL to generated spec data ([0797e83](https://github.com/markuplint/markuplint/commit/0797e832a4b1c6ce80b1dc32529228db5a3e07cb))
+- **html-spec:** fix optgroup selector and remove stale comment ([f6bcd7f](https://github.com/markuplint/markuplint/commit/f6bcd7f7036516e236117c34349085986efacfc3))
+- **html-spec:** mark input switch attribute as non-standard ([5b28f44](https://github.com/markuplint/markuplint/commit/5b28f447b31f38420b8e0cc91827f66e0fe4331d))
+- **html-spec:** update ARIA role descriptions for combobox, tab, and tabpanel ([4b8e5cc](https://github.com/markuplint/markuplint/commit/4b8e5cc69c9e2bd1c83b8dbf0a991324263a7156))
+- **html-spec:** update as attribute enum values based on WHATWG spec changes ([f10bd77](https://github.com/markuplint/markuplint/commit/f10bd77e647d37b41a0ee99b1adfe4fd0cb42831)), closes [whatwg/html#10212](https://github.com/whatwg/html/issues/10212) [whatwg/html#11981](https://github.com/whatwg/html/issues/11981) [#1987](https://github.com/markuplint/markuplint/issues/1987)
+
+### Features
+
+- **html-spec:** add 41 DPub ARIA roles to generated spec data ([a98b9e5](https://github.com/markuplint/markuplint/commit/a98b9e53b5d96b700e66291dd643534f7df5cbaf))
+- **html-spec:** require href or imagesrcset on link element ([e6a2631](https://github.com/markuplint/markuplint/commit/e6a26318ed8e4be9ba4e81884eb0b879a816efb5)), closes [#717](https://github.com/markuplint/markuplint/issues/717)
 
+# [4.17.0](https://github.com/markuplint/markuplint/compare/@markuplint/html-spec@4.16.1...@markuplint/html-spec@4.17.0) (2026-02-10)
 
+### Bug Fixes
+
+- **html-spec:** add math and meter to img permitted roles ([97c9de0](https://github.com/markuplint/markuplint/commit/97c9de0596d2b9b17f91c875e853def4e45ec36b))
+- **html-spec:** add permitted roles to button per html-aria ([1bcdf1b](https://github.com/markuplint/markuplint/commit/1bcdf1b2894908a4d05d80458cfb5ccbbc1029b8))
+- **html-spec:** correct implicit role typo for meter element ([c7dc7c9](https://github.com/markuplint/markuplint/commit/c7dc7c9174047248f9170925b22d4fea5984b49d))
+- **html-spec:** revert over-applied role description changes ([fbc8a46](https://github.com/markuplint/markuplint/commit/fbc8a46f570ccebcafda7825305285002573df31))
+- **html-spec:** update html element implicit role to generic ([862a67d](https://github.com/markuplint/markuplint/commit/862a67d9283cec6854b0ab7ef678d3fa3516f3fe)), closes [w3c/aria#2504](https://github.com/w3c/aria/issues/2504) [w3c/html-aria#550](https://github.com/w3c/html-aria/issues/550)
+- **spec-generator:** merge MDN data into spec-defined attributes ([ae4db37](https://github.com/markuplint/markuplint/commit/ae4db37b109bac3daed22d8ba0a147acf2d71787))
+
+### Features
 
+- **html-spec:** add headingoffset and headingreset attributes ([49aa8e7](https://github.com/markuplint/markuplint/commit/49aa8e72346ea61cb62db8239ef9fe99b8a4eac3)), closes [whatwg/html#11086](https://github.com/whatwg/html/issues/11086) [whatwg/html#11979](https://github.com/whatwg/html/issues/11979)
+- **html-spec:** add iframe privateToken attribute ([6d6a45d](https://github.com/markuplint/markuplint/commit/6d6a45d2615f95b964e479c26e13ed3904ecfeb8))
+- **html-spec:** add input switch attribute ([3f77351](https://github.com/markuplint/markuplint/commit/3f773515c12349b88524991ddbefc8bd7206a2c9))
+- **html-spec:** add interestfor attribute (Interest Invokers API) ([1230b8b](https://github.com/markuplint/markuplint/commit/1230b8be720a78d615c1d5ca5873e6c725e6bb92))
+- **html-spec:** add request-close to button command attribute ([46c6093](https://github.com/markuplint/markuplint/commit/46c60938ceb37f094ab58ff034d01d4489c1ffa6))
+- **html-spec:** add svg:switch requiredExtensions and systemLanguage attributes ([481a836](https://github.com/markuplint/markuplint/commit/481a83693ccfc6b7147783c9d841ea2d96fadfef))
+- **html-spec:** add template shadowrootreferencetarget attribute ([dd78b8a](https://github.com/markuplint/markuplint/commit/dd78b8a75e4a034555741b4595c95cb535370ad0))
+- **html-spec:** deprecate attributionsrc attribute ([e12cf46](https://github.com/markuplint/markuplint/commit/e12cf4625e778e9e64ba6aef08b0e7c5b18b8c29))
+- **html-spec:** deprecate browsingtopics attribute on iframe ([27f54cf](https://github.com/markuplint/markuplint/commit/27f54cf3d349089ef2a972d14a386bfd9b2909c9))
+- **html-spec:** update scrollbar aria-controls from required to inherited ([14aeec5](https://github.com/markuplint/markuplint/commit/14aeec5e4e01ef32ba147a9ff49a5d5c44558901))
 
+## [4.16.1](https://github.com/markuplint/markuplint/compare/@markuplint/html-spec@4.16.0...@markuplint/html-spec@4.16.1) (2025-11-05)
+
+**Note:** Version bump only for package @markuplint/html-spec
 
 # [4.16.0](https://github.com/markuplint/markuplint/compare/@markuplint/html-spec@4.15.0...@markuplint/html-spec@4.16.0) (2025-08-24)