@markuplint/ml-spec 5.0.0-rc.4 → 5.0.0-rc.6

package/lib/algorithm/aria/get-non-presentational-ancestor.js

@@ -1,16 +1,8 @@
 import { isTransparentForOwnership } from './is-presentational.js';
 import { getComputedRole } from './get-computed-role.js';
 /**
- * Traverses the parent element chain to find the nearest ancestor with a
- * non-presentational role, skipping elements that are transparent for
- * ownership traversal (via `isTransparentForOwnership`).
- *
- * In ARIA 1.3, `generic` role elements are additionally transparent.
- *
- * @param el - The DOM element whose ancestors to traverse
- * @param specs - The full markup language specification
- * @param version - The ARIA specification version to use
- * @returns The nearest non-presentational ancestor's `ComputedRole`, or `{ el: null, role: null }` if none exists
+ * In ARIA 1.3, `generic` role elements are additionally transparent for
+ * ownership traversal.
  */
 export function getNonPresentationalAncestor(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types

package/lib/algorithm/aria/get-permitted-roles-spec.js

@@ -64,6 +64,7 @@ export function getPermittedRoles(specs, localName, namespace, version, matches)
     // allowed at all per ARIA in HTML — even a value matching the implicit role.
     // e.g. `<img alt="">`: implicit role is `presentation`, but "No role permitted"
     // means `role="presentation"` and `role="none"` are both disallowed.
+    // See https://github.com/markuplint/markuplint/issues/3641 for background.
     if (permittedRoles === false) {
         return permittedRoleList;
     }

package/lib/algorithm/aria/matches-context-role.d.ts

@@ -1,9 +1,8 @@
 import type { ARIAVersion, MLMLSpec } from '../../types/index.js';
 /**
- * Checks whether an element's parent hierarchy satisfies the
- * "Required Accessibility Parent Role" (called "Required Context Role" in ARIA 1.2).
- * Each condition string may describe a chain of ancestor roles separated by
- * ` > ` (e.g., `"list > group"`).
+ * Implements the ARIA "Required Accessibility Parent Role" (called "Required
+ * Context Role" in ARIA 1.2). Each condition string describes a chain of
+ * ancestor roles separated by ` > ` (e.g., `"list > group"`).
  *
  * TODO: This function only walks the DOM `parentElement` chain and does not
  * consider `aria-owns` relationships. An element referenced by `aria-owns` on
@@ -11,11 +10,5 @@ import type { ARIAVersion, MLMLSpec } from '../../types/index.js';
  * that ancestor. Implementing this requires a document-wide reverse lookup of
  * `aria-owns` attributes, which is a separate architectural concern.
  * See also: `has-required-owned-elements.ts` has a similar limitation.
- *
- * @param conditions - An array of required accessibility parent role condition strings to match against
- * @param ownedEl - The owned DOM element whose parent context is being validated
- * @param specs - The full markup language specification
- * @param version - The ARIA specification version to use
- * @returns `true` if any of the context role conditions are satisfied by the element's ancestors
  */
 export declare function matchesContextRole(conditions: readonly string[], ownedEl: Element, specs: MLMLSpec, version: ARIAVersion): boolean;

package/lib/algorithm/aria/matches-context-role.js

@@ -1,10 +1,9 @@
 import { isTransparentForOwnership } from './is-presentational.js';
 import { getComputedRole } from './get-computed-role.js';
 /**
- * Checks whether an element's parent hierarchy satisfies the
- * "Required Accessibility Parent Role" (called "Required Context Role" in ARIA 1.2).
- * Each condition string may describe a chain of ancestor roles separated by
- * ` > ` (e.g., `"list > group"`).
+ * Implements the ARIA "Required Accessibility Parent Role" (called "Required
+ * Context Role" in ARIA 1.2). Each condition string describes a chain of
+ * ancestor roles separated by ` > ` (e.g., `"list > group"`).
  *
  * TODO: This function only walks the DOM `parentElement` chain and does not
  * consider `aria-owns` relationships. An element referenced by `aria-owns` on
@@ -12,12 +11,6 @@ import { getComputedRole } from './get-computed-role.js';
  * that ancestor. Implementing this requires a document-wide reverse lookup of
  * `aria-owns` attributes, which is a separate architectural concern.
  * See also: `has-required-owned-elements.ts` has a similar limitation.
- *
- * @param conditions - An array of required accessibility parent role condition strings to match against
- * @param ownedEl - The owned DOM element whose parent context is being validated
- * @param specs - The full markup language specification
- * @param version - The ARIA specification version to use
- * @returns `true` if any of the context role conditions are satisfied by the element's ancestors
  */
 export function matchesContextRole(conditions, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types

package/lib/algorithm/html/content-model-category-to-tag-names.d.ts

@@ -5,6 +5,11 @@ import type { Category } from '../../types/permitted-structures.js';
  * frozen array of HTML/SVG tag names that belong to that category.
  * Results are cached for repeated lookups.
  *
+ * Note: entries are returned as stored in the spec's `#contentModels` map
+ * without CSS selector parsing — they are expected to be bare tag names or
+ * tag-with-attribute selectors (e.g. `a[href]`); complex selectors are not
+ * decomposed into tag names.
+ *
  * @param contentModel - The content model category identifier
  * @param def - The specification definitions containing content model mappings
  * @returns A frozen, sorted array of tag name strings belonging to the category

package/lib/algorithm/html/content-model-category-to-tag-names.js

@@ -4,6 +4,11 @@ const cache = new Map();
  * frozen array of HTML/SVG tag names that belong to that category.
  * Results are cached for repeated lookups.
  *
+ * Note: entries are returned as stored in the spec's `#contentModels` map
+ * without CSS selector parsing — they are expected to be bare tag names or
+ * tag-with-attribute selectors (e.g. `a[href]`); complex selectors are not
+ * decomposed into tag names.
+ *
  * @param contentModel - The content model category identifier
  * @param def - The specification definitions containing content model mappings
  * @returns A frozen, sorted array of tag name strings belonging to the category

package/lib/index.d.ts

@@ -1,3 +1,31 @@
+/**
+ * Specification foundation layer for markuplint.
+ *
+ * Type definitions, W3C specification algorithms (WAI-ARIA, HTML-AAM, AccName,
+ * HTML content models), and JSON schemas live together in this single package
+ * by design. Separating the "static schemas" from the "computing algorithms"
+ * was considered and rejected: the algorithms are integral parts of the
+ * specifications themselves — HTML elements define implicit ARIA roles, the
+ * ARIA algorithms reference HTML semantics, and test cases validate
+ * cross-specification behavior — so a split would create an artificial
+ * boundary with no runtime benefit.
+ *
+ * The accessible name computation (`getAccname`) is implemented in-house with
+ * no external dependency; this is intentional.
+ *
+ * Versioning policy: the schemas and spec data structures are not part of
+ * markuplint's public API surface. Changes to schemas, generated types, or
+ * algorithm behavior are released as minor versions.
+ *
+ * Several module-level caches (element spec lookup, namespace resolution,
+ * version-resolved ARIA, content-model category tables) are intentionally
+ * never invalidated: spec data is immutable after merging and a lint run uses
+ * a single configuration. Long-running embedders (e.g. language servers)
+ * should be aware that spec data is cached at first access for the process
+ * lifetime.
+ *
+ * @module @markuplint/ml-spec
+ */
 export { getAttrSpecs as getAttrSpecsByNames } from './utils/get-attr-specs-spec.js';
 export * from './utils/aria-version.js';
 export { EMBEDDED_CONTROL_ROLES, isNativeEmbeddedControl } from './const/index.js';

package/lib/index.js

@@ -1,3 +1,31 @@
+/**
+ * Specification foundation layer for markuplint.
+ *
+ * Type definitions, W3C specification algorithms (WAI-ARIA, HTML-AAM, AccName,
+ * HTML content models), and JSON schemas live together in this single package
+ * by design. Separating the "static schemas" from the "computing algorithms"
+ * was considered and rejected: the algorithms are integral parts of the
+ * specifications themselves — HTML elements define implicit ARIA roles, the
+ * ARIA algorithms reference HTML semantics, and test cases validate
+ * cross-specification behavior — so a split would create an artificial
+ * boundary with no runtime benefit.
+ *
+ * The accessible name computation (`getAccname`) is implemented in-house with
+ * no external dependency; this is intentional.
+ *
+ * Versioning policy: the schemas and spec data structures are not part of
+ * markuplint's public API surface. Changes to schemas, generated types, or
+ * algorithm behavior are released as minor versions.
+ *
+ * Several module-level caches (element spec lookup, namespace resolution,
+ * version-resolved ARIA, content-model category tables) are intentionally
+ * never invalidated: spec data is immutable after merging and a lint run uses
+ * a single configuration. Long-running embedders (e.g. language servers)
+ * should be aware that spec data is cached at first access for the process
+ * lifetime.
+ *
+ * @module @markuplint/ml-spec
+ */
 export { getAttrSpecs as getAttrSpecsByNames } from './utils/get-attr-specs-spec.js';
 export * from './utils/aria-version.js';
 // Constants

package/lib/types/index.d.ts

@@ -12,6 +12,16 @@ export interface MLMLSpec {
     readonly def: SpecDefs;
     readonly specs: readonly ElementSpec[];
     readonly directivePatterns?: readonly DirectivePattern[];
+    /**
+     * Controls how `@markuplint/ml-core`'s `MLAttr` resolves attribute names.
+     *
+     * - `'idl'`: enables IDL-to-content attribute name resolution (e.g.
+     *   `className` → `class`) and suggests the IDL name as a candidate when the
+     *   content attribute name is used (e.g. `tabindex` → "Did you mean
+     *   `tabIndex`?"). Used by React, which accepts only IDL property names.
+     * - `'both'`: enables the same resolution but accepts both content attribute
+     *   names and IDL property names without suggesting either. Used by Svelte.
+     */
     readonly acceptedAttrNames?: 'idl' | 'both';
 }
 /**
@@ -32,6 +42,10 @@ export type ExtendedSpec = {
     readonly def?: Partial<SpecDefs>;
     readonly specs?: readonly ExtendedElementSpec[];
     readonly directivePatterns?: readonly DirectivePattern[];
+    /**
+     * See {@link MLMLSpec.acceptedAttrNames}. Last-write-wins across merged
+     * specs; omitting the property does not reset a previously set value.
+     */
     readonly acceptedAttrNames?: 'idl' | 'both';
 };
 /**
@@ -41,6 +55,10 @@ export type ExtendedSpec = {
  *
  * The `pattern` is a regex string matched against the raw attribute name.
  * Capture groups can be referenced in `potentialName` using `$1`, `$2`, etc.
+ *
+ * Patterns are evaluated in order and the first match wins. Merging specs
+ * (`schemaToSpec`) concatenates pattern arrays, so spec authors should define
+ * patterns from most specific to most general.
  */
 export type DirectivePattern = {
     /**
@@ -131,21 +149,26 @@ export type ElementSpec = {
      */
     readonly description?: string;
     /**
-     * Experimental technology
+     * Experimental technology: not yet standardized (proposed or draft;
+     * subject to change or removal).
      */
     readonly experimental?: true;
     /**
-     * Obsolete or alternative elements
+     * Obsolete or alternative elements: removed from the spec entirely
+     * (browsers may no longer recognize it). Optionally points to an
+     * alternative element via `alt`.
      */
     readonly obsolete?: true | {
         readonly alt: string;
     };
     /**
-     * Deprecated
+     * Deprecated: still defined by the spec but its use is discouraged
+     * (usually still works in browsers).
      */
     readonly deprecated?: true;
     /**
-     * Non-standard
+     * Non-standard: never part of any standard (vendor-specific or
+     * proprietary).
      */
     readonly nonStandard?: true;
     /**
@@ -246,11 +269,19 @@ export type ARIARoleInSchema = Partial<ARIARole & {
 /**
  * Describes a property owned by an ARIA role, including whether it is inherited,
  * required, or deprecated.
+ *
+ * `requiredCondition` qualifies `required: true` so that the property is only
+ * required when the condition holds. The W3C ARIA source markup does not encode
+ * such conditions; values are populated by manual overrides in
+ * `@markuplint/html-spec/generator/aria.ts`. Currently the only value is
+ * `'focusable'` (applied to `separator`'s `aria-valuenow`); the `wai-aria`
+ * checker resolves this through `mayBeFocusable` from `@markuplint/ml-spec`.
  */
 export type ARIARoleOwnedProperties = {
     readonly name: string;
     readonly inherited?: true;
     readonly required?: true;
+    readonly requiredCondition?: 'focusable';
     readonly deprecated?: true;
 };
 /**

package/lib/utils/schema-to-spec.d.ts

@@ -6,6 +6,16 @@ import type { ElementSpec, ExtendedSpec, MLMLSpec } from '../types/index.js';
  *
  * Ex: `@markuplint/html-spec` + `{ specs: { "\\.vue$": "@markuplint/vue-spec" } }` in configure files.
  *
+ * The merge is an additive overlay with silent, unconditional override: later
+ * specs win, and there is deliberately no conflict detection and no provenance
+ * tracking in the merged result. Framework specs exist precisely to relax or
+ * extend base HTML constraints (e.g. React's `dangerouslySetInnerHTML`, Vue's
+ * `v-if`), so every key collision with the base spec is treated as a
+ * deliberate decision by the `ExtendedSpec` author — an extension that
+ * unintentionally weakens a base constraint is not flagged anywhere.
+ *
+ * @see https://github.com/markuplint/markuplint/issues/3893
+ *
  * @param schemas - A tuple where the first element is the base `MLMLSpec` and subsequent elements are extended specs to merge
  * @returns The merged specification combining the base spec with all extensions
  */

package/lib/utils/schema-to-spec.js

@@ -6,6 +6,16 @@ import { mergeArray } from './merge-array.js';
  *
  * Ex: `@markuplint/html-spec` + `{ specs: { "\\.vue$": "@markuplint/vue-spec" } }` in configure files.
  *
+ * The merge is an additive overlay with silent, unconditional override: later
+ * specs win, and there is deliberately no conflict detection and no provenance
+ * tracking in the merged result. Framework specs exist precisely to relax or
+ * extend base HTML constraints (e.g. React's `dangerouslySetInnerHTML`, Vue's
+ * `v-if`), so every key collision with the base spec is treated as a
+ * deliberate decision by the `ExtendedSpec` author — an extension that
+ * unintentionally weakens a base constraint is not flagged anywhere.
+ *
+ * @see https://github.com/markuplint/markuplint/issues/3893
+ *
  * @param schemas - A tuple where the first element is the base `MLMLSpec` and subsequent elements are extended specs to merge
  * @returns The merged specification combining the base spec with all extensions
  */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/ml-spec",
-	"version": "5.0.0-rc.4",
+	"version": "5.0.0-rc.6",
 	"description": "Types and schema that specs of the Markup languages for markuplint",
 	"repository": {
 		"type": "git",
@@ -10,7 +10,7 @@
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
 	"license": "MIT",
 	"engines": {
-		"node": ">=22"
+		"node": ">=24"
 	},
 	"type": "module",
 	"exports": {
@@ -36,14 +36,14 @@
 		"schema:aria": "npx json2ts ./schemas/aria.schema.json --cwd ./schemas > ./src/types/aria.ts"
 	},
 	"dependencies": {
-		"@markuplint/ml-ast": "5.0.0-rc.4",
-		"@markuplint/types": "5.0.0-rc.4",
+		"@markuplint/ml-ast": "5.0.0-rc.6",
+		"@markuplint/types": "5.0.0-rc.6",
 		"is-plain-object": "5.0.0",
 		"type-fest": "5.6.0"
 	},
 	"devDependencies": {
-		"@markuplint/test-tools": "5.0.0-rc.4",
+		"@markuplint/test-tools": "5.0.0-rc.6",
 		"json-schema-to-typescript": "15.0.4"
 	},
-	"gitHead": "97a6339bbae23f556de5d307b3ce2ef7cfd9402d"
+	"gitHead": "c02c3a0783eac6b2fb4707be2dc00b88f6219641"
 }

package/ARCHITECTURE.ja.md

@@ -1,267 +0,0 @@
-# @markuplint/ml-spec
-
-## 概要
-
-`@markuplint/ml-spec` は markuplint の仕様基盤レイヤーです。型定義、W3C 仕様アルゴリズム（ARIA/HTML）、JSON スキーマ、ランタイムユーティリティを提供し、Web 標準の生データと markuplint のリントルールを橋渡しします。
-
-`@markuplint/html-spec`（およびフレームワーク固有の仕様パッケージ）から要素仕様・ARIA ロール/プロパティ定義・コンテンツモデルデータを読み込み、ARIA ロール計算・要素仕様の解決・コンテンツモデル評価・アクセシビリティツリー包含判定のアルゴリズムを公開します。15 以上の下流パッケージが依存しています。
-
-## ディレクトリ構成
-
-```
-src/
-├── index.ts                                      # エントリーポイント。全公開 API を再エクスポート
-├── types/
-│   ├── index.ts                                  # 手書きのコア型（MLMLSpec, ElementSpec, ARIARole 等）
-│   ├── aria.ts                                   # aria.schema.json から生成（ARIA, PermittedRoles, ImplicitRole）
-│   ├── attributes.ts                             # attributes.schema.json から生成（AttributeType, GlobalAttributes）
-│   └── permitted-structures.ts                   # content-models.schema.json から生成（ContentModel, Category）
-├── algorithm/
-│   ├── aria/
-│   │   ├── accname-computation.ts                # アクセシブルネーム計算ファサード（DOM リゾルバ + 再入防止ガード）
-│   │   ├── accname/                              # AccName 純粋アルゴリズム（HTML-AAM §4.1）
-│   │   │   ├── types.ts                          # AccnameElement/AccnameResolver インターフェース
-│   │   │   ├── compute.ts                        # コアアルゴリズム: Steps 2A-2I
-│   │   │   ├── aria-steps.ts                     # Steps 2B (aria-labelledby), 2D (aria-label)
-│   │   │   ├── element-names.ts                  # Step 2E: 要素固有の名前（HTML-AAM §4.1）
-│   │   │   ├── helpers.ts                        # 共有ユーティリティ（埋め込みコントロール、name-from-content）
-│   │   │   ├── label-steps.ts                    # Step 2E: ラベル関連付け（labelable 要素）
-│   │   │   ├── svg-helpers.ts                    # SVG アクセシブル名ソース判定
-│   │   │   └── index.ts                          # 公開 API 再エクスポート
-│   │   ├── aria-specs.ts                         # バージョン別 ARIA 仕様データの取得
-│   │   ├── get-aria.ts                           # 要素レベルの ARIA 仕様解決（条件付き）
-│   │   ├── get-computed-aria-props.ts            # ARIA プロパティ解決（明示 → HTML → デフォルト）
-│   │   ├── get-computed-role.ts                  # 中核：最終ロール計算と競合解決
-│   │   ├── get-explicit-role.ts                  # role 属性からの明示ロール（著者エラー処理）
-│   │   ├── get-implicit-role.ts                  # HTML-AAM による暗黙ロール
-│   │   ├── get-implicit-role-spec.ts             # 暗黙ロール名の低レベル検索
-│   │   ├── get-non-presentational-ancestor.ts    # プレゼンテーショナルロールをスキップする祖先探索
-│   │   ├── get-permitted-roles.ts                # DOM 要素の許可ロール
-│   │   ├── get-permitted-roles-spec.ts           # タグ名/名前空間による許可ロール（低レベル）
-│   │   ├── get-role-spec.ts                      # スーパークラスチェーン付きロール仕様
-│   │   ├── has-required-owned-elements.ts        # 必須所有要素の検証
-│   │   ├── is-exposed.ts                         # アクセシビリティツリー包含/除外
-│   │   ├── is-presentational.ts                  # プレゼンテーショナルロール判定（presentation/none）
-│   │   └── matches-context-role.ts               # 必須コンテキストロールの検証
-│   └── html/
-│       ├── content-model-category-to-tag-names.ts  # カテゴリ → タグ名配列（キャッシュ付き）
-│       ├── get-content-model.ts                    # 条件付きコンテンツモデル評価
-│       ├── get-selectors-by-content-model-category.ts  # カテゴリ → CSS セレクタ配列
-│       ├── is-nothing-content-model.ts             # 「Nothing」コンテンツモデル判定
-│       ├── is-palpable-elements.ts                 # パルパブルコンテンツ検出
-│       ├── is-void-element.ts                      # ボイド要素判定（13 要素）
-│       └── may-be-focusable.ts                     # フォーカス可能性ヒューリスティック
-├── const/
-│   ├── index.ts                                  # 全定数の再エクスポート
-│   ├── dom.ts                                    # DOM 定数（ELEMENT_NODE, TEXT_NODE, 名前空間 URI）
-│   └── accname.ts                                # AccName 定数（埋め込みコントロールロール、入力型、デフォルト値）
-└── utils/
-    ├── aria-version.ts                           # ARIA バージョン定数（'1.1', '1.2', '1.3'）
-    ├── get-attr-specs.ts                         # DOM 要素の属性仕様（ラッパー）
-    ├── get-attr-specs-spec.ts                    # タグ名/名前空間による属性仕様（コア）
-    ├── get-ns.ts                                 # 名前空間 URI → 短縮名マッピング
-    ├── get-spec.ts                               # DOM 要素の要素仕様（ラッパー）
-    ├── get-spec-by-tag-name.ts                   # タグ名/名前空間による要素仕様（キャッシュ付き）
-    ├── merge-array.ts                            # 名前ベースの配列マージユーティリティ
-    ├── resolve-namespace.ts                      # 名前空間解決とプレフィックス正規化
-    ├── resolve-version.ts                        # ARIA バージョン固有プロパティの解決
-    ├── schema-to-spec.ts                         # スキーママージパイプライン（ベース + 拡張）
-    └── validate-aria-version.ts                  # ARIA バージョン文字列の型ガード
-
-schemas/
-├── element.schema.json                           # トップレベル要素仕様スキーマ（11 行）
-├── aria.schema.json                              # ARIA ロール/プロパティスキーマ（291 行）
-├── attributes.schema.json                        # 属性型スキーマ（190 行）
-├── content-models.schema.json                    # コンテンツモデルパターンスキーマ（215 行）
-└── global-attributes.schema.json                 # グローバル属性カテゴリスキーマ（787 行）
-
-gen/
-├── gen.ts                                        # global-attributes.schema.json のスキーマジェネレータ
-└── global-attribute.data.ts                      # グローバル属性カテゴリ定義
-```
-
-## アーキテクチャ図
-
-```mermaid
-flowchart TD
-    subgraph input ["入力レイヤー"]
-        htmlSpec["@markuplint/html-spec\n(MLMLSpec JSON)"]
-        fwSpec["フレームワーク仕様\n(ExtendedSpec)"]
-    end
-
-    subgraph merge ["仕様解決"]
-        schemaToSpec["schemaToSpec()"]
-        getSpec["getSpec() / getSpecByTagName()"]
-        getAttrSpecs["getAttrSpecs()"]
-        resolveNS["resolveNamespace()"]
-    end
-
-    subgraph aria ["ARIA アルゴリズム"]
-        getComputedRole["getComputedRole()"]
-        getExplicitRole["getExplicitRole()"]
-        getImplicitRole["getImplicitRole()"]
-        getPermittedRoles["getPermittedRoles()"]
-        getRoleSpec["getRoleSpec()"]
-        getARIA["getARIA()"]
-        getComputedAriaProps["getComputedAriaProps()"]
-        isExposed["isExposed()"]
-        getAccname["getAccname()"]
-    end
-
-    subgraph html ["HTML アルゴリズム"]
-        getContentModel["getContentModel()"]
-        isPalpable["isPalpableElement()"]
-        isVoid["isVoidElement()"]
-        mayBeFocusable["mayBeFocusable()"]
-    end
-
-    subgraph types ["型定義"]
-        handWritten["MLMLSpec, ElementSpec\nARIARole, ComputedRole"]
-        generated["ARIA, PermittedRoles\nContentModel, Category"]
-    end
-
-    htmlSpec --> schemaToSpec
-    fwSpec --> schemaToSpec
-    schemaToSpec --> getSpec
-    getSpec --> getAttrSpecs
-    getSpec --> getARIA
-    resolveNS --> getSpec
-
-    getARIA --> getComputedRole
-    getExplicitRole --> getComputedRole
-    getImplicitRole --> getComputedRole
-    getPermittedRoles --> getExplicitRole
-    getRoleSpec --> getImplicitRole
-    getRoleSpec --> getExplicitRole
-    getComputedRole --> getComputedAriaProps
-    getComputedRole --> isExposed
-
-    getSpec --> getContentModel
-    getSpec --> isPalpable
-```
-
-## 主要コンポーネント
-
-### 1. 型定義
-
-型システムは、マークアップ言語仕様・要素仕様・ARIA ロール・属性の構造を定義します。
-
-| ファイル                        | 役割                                                                                                                            |
-| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `types/index.ts`                | 手書き型: `MLMLSpec`, `ElementSpec`, `ExtendedSpec`, `ARIARole`, `ComputedRole` 等                                              |
-| `types/aria.ts`                 | 生成型: `ARIA`, `PermittedRoles`, `ImplicitRole`, `PermittedARIAProperties`, `ImplicitProperties`                               |
-| `types/attributes.ts`           | 生成型: `AttributeType`, `ConditionalAttributeType`, `GlobalAttributes`, `AttributeJSON`, `List`, `Enum`, `Number`, `Directive` |
-| `types/permitted-structures.ts` | 生成型: `PermittedContentPattern`, `ContentModel`, `Category`（HTML 13 + SVG 19 + MathML 3 カテゴリ）                           |
-
-### 2. ARIA アルゴリズム
-
-ARIA アルゴリズムは WAI-ARIA, HTML-AAM, SVG-AAM, MathML-AAM, AccName 1.2 仕様に基づくロール計算とアクセシビリティツリー管理を実装します。
-
-| ファイル                         | 役割                                                                            |
-| -------------------------------- | ------------------------------------------------------------------------------- |
-| `get-computed-role.ts`           | 中核アルゴリズム: Presentational Roles Conflict Resolution による最終ロール計算 |
-| `get-explicit-role.ts`           | `role` 属性からの明示ロール解決（著者エラー処理付き）                           |
-| `get-implicit-role.ts`           | HTML-AAM に基づく暗黙（ネイティブ）ARIA ロールの決定                            |
-| `get-computed-aria-props.ts`     | ARIA プロパティ解決: 明示 `aria-*` → HTML 等価属性 → 仕様デフォルト             |
-| `is-exposed.ts`                  | WAI-ARIA ルールに基づくアクセシビリティツリーの包含/除外判定                    |
-| `get-permitted-roles.ts`         | 要素の許可ロール一覧（Any/No/具体的リスト）                                     |
-| `get-role-spec.ts`               | スーパークラスロールチェーン付き完全ロール仕様の取得                            |
-| `has-required-owned-elements.ts` | 必須所有要素制約の検証                                                          |
-| `matches-context-role.ts`        | 祖先チェーンにおける必須コンテキストロール条件の検証                            |
-| `accname-computation.ts`         | アクセシブルネーム計算ファサード（DOM リゾルバ + 再入防止ガード）               |
-| `accname/compute.ts`             | 純粋 AccName アルゴリズム: HTML-AAM §4.1 の Steps 2A-2I                         |
-| `accname/element-names.ts`       | Step 2E: 要素固有の名前計算（HTML-AAM §4.1）                                    |
-| `get-aria.ts`                    | バージョンと条件の解決を含む要素レベル ARIA 仕様                                |
-| `is-presentational.ts`           | ロールが `presentation` または `none` かどうかの判定                            |
-
-### 3. HTML アルゴリズム
-
-HTML アルゴリズムは HTML Living Standard に基づくコンテンツモデル評価と要素分類を実装します。
-
-| ファイル                                     | 役割                                                                           |
-| -------------------------------------------- | ------------------------------------------------------------------------------ |
-| `get-content-model.ts`                       | 条件付きパターン評価を含むコンテンツモデルの取得                               |
-| `content-model-category-to-tag-names.ts`     | コンテンツモデルカテゴリをソート済みタグ名配列に変換                           |
-| `get-selectors-by-content-model-category.ts` | コンテンツモデルカテゴリを CSS セレクタにマッピング                            |
-| `is-palpable-elements.ts`                    | SVG/MathML/露出可能要素拡張付きパルパブルコンテンツ検出                        |
-| `is-void-element.ts`                         | ボイド要素判定（13 の HTML ボイド要素）                                        |
-| `is-nothing-content-model.ts`                | 「Nothing」コンテンツモデル判定（void + iframe + template）                    |
-| `may-be-focusable.ts`                        | フォーカス可能性ヒューリスティック（interactive + tabindex + contenteditable） |
-
-### 4. 仕様解決ユーティリティ
-
-仕様のマージ・解決・キャッシュのためのユーティリティです。
-
-| ファイル                   | 役割                                                                         |
-| -------------------------- | ---------------------------------------------------------------------------- |
-| `schema-to-spec.ts`        | ベース `MLMLSpec` と `ExtendedSpec[]` のマージ（グローバル属性, ARIA, 要素） |
-| `get-spec-by-tag-name.ts`  | タグ名 + 名前空間による要素仕様の検索（キャッシュ付き）                      |
-| `get-attr-specs-spec.ts`   | マージ済み属性仕様の取得（グローバル + 要素固有）                            |
-| `resolve-namespace.ts`     | 名前空間プレフィックスを含む要素名の正規化                                   |
-| `resolve-version.ts`       | ARIA バージョン固有のオーバーライドをフォールバック付きで解決                |
-| `merge-array.ts`           | 名前ベースの配列マージ（`name` プロパティによる追加/上書き）                 |
-| `validate-aria-version.ts` | 有効な ARIA バージョン文字列の型ガード                                       |
-
-## 外部依存パッケージ
-
-| パッケージ           | 用途                                               | 使用箇所                      |
-| -------------------- | -------------------------------------------------- | ----------------------------- |
-| `@markuplint/ml-ast` | XML 名前空間処理のための `NamespaceURI` 型         | `types/index.ts`, utils       |
-| `@markuplint/types`  | 属性値の型定義のための `Type` 共用体               | `types/attributes.ts` 経由    |
-| `is-plain-object`    | AAM 情報のプレーンオブジェクト検出                 | `get-permitted-roles-spec.ts` |
-| `type-fest`          | 深い不変性のための `ReadonlyDeep` ユーティリティ型 | 複数ファイル                  |
-
-## 他パッケージとの連携
-
-```mermaid
-flowchart LR
-    subgraph upstream ["上流パッケージ"]
-        htmlSpec["@markuplint/html-spec"]
-        vueSpec["@markuplint/vue-spec"]
-        reactSpec["@markuplint/react-spec"]
-        otherSpec["その他フレームワーク仕様"]
-    end
-
-    subgraph pkg ["@markuplint/ml-spec"]
-        types["型定義"]
-        ariaAlgo["ARIA アルゴリズム"]
-        htmlAlgo["HTML アルゴリズム"]
-        specRes["仕様解決"]
-    end
-
-    subgraph downstream ["下流パッケージ"]
-        mlCore["@markuplint/ml-core"]
-        rules["@markuplint/rules"]
-        selector["@markuplint/selector"]
-    end
-
-    htmlSpec -->|"MLMLSpec JSON"| specRes
-    vueSpec -->|"ExtendedSpec"| specRes
-    reactSpec -->|"ExtendedSpec"| specRes
-    otherSpec -->|"ExtendedSpec"| specRes
-
-    specRes --> ariaAlgo
-    specRes --> htmlAlgo
-    types --> mlCore
-    ariaAlgo -->|"ロール計算\nアクセシビリティツリー"| rules
-    htmlAlgo -->|"コンテンツモデル\n要素分類"| rules
-    types --> selector
-```
-
-### 上流
-
-`@markuplint/html-spec` は、全 HTML 要素仕様・ARIA 定義・コンテンツモデルデータを含むベース `MLMLSpec` JSON を提供します。フレームワーク固有パッケージ（`@markuplint/vue-spec`, `@markuplint/react-spec` 等）は、要素・属性・ARIA マッピングを追加またはオーバーライドする `ExtendedSpec` オブジェクトを提供します。
-
-### 下流
-
-- **`@markuplint/ml-core`** は型定義を使用して、仕様認識を持つパース済みドキュメント要素を表現します。
-- **`@markuplint/rules`** は ARIA および HTML アルゴリズムを呼び出して、リントルール（ロール検証、コンテンツモデルチェック、アクセシビリティチェック）を実装します。
-- **`@markuplint/selector`** は要素マッチングのために型定義を使用します。
-
-## ドキュメントマップ
-
-- [ARIA アルゴリズム](docs/aria-algorithms.ja.md) -- ロール計算、アクセシビリティツリー、ARIA プロパティ解決
-- [HTML アルゴリズム](docs/html-algorithms.ja.md) -- コンテンツモデル、要素分類、ボイド要素
-- [型定義](docs/type-definitions.ja.md) -- コア型、生成型、JSON スキーマ
-- [仕様解決](docs/spec-resolution.ja.md) -- スキーママージ、名前空間解決、キャッシュ
-- [メンテナンスガイド](docs/maintenance.ja.md) -- スキーマ生成、依存関係管理、レシピ、トラブルシューティング