npm - @markuplint/html-spec - Versions diffs - 5.0.0-rc.2 → 5.0.0-rc.5 - Mend

@markuplint/html-spec 5.0.0-rc.2 → 5.0.0-rc.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/CHANGELOG.md +57 -0
package/CLAUDE.md +41 -0
package/README.md +0 -7
package/index.json +410 -180
package/package.json +6 -6
package/ARCHITECTURE.ja.md +0 -276
package/ARCHITECTURE.md +0 -206
package/SKILL.md +0 -358
package/docs/build-pipeline.ja.md +0 -154
package/docs/build-pipeline.md +0 -155
package/docs/element-spec-format.ja.md +0 -1034
package/docs/element-spec-format.md +0 -570
package/docs/maintenance.ja.md +0 -424
package/docs/maintenance.md +0 -478

package/SKILL.md DELETED Viewed

@@ -1,358 +0,0 @@
----
-description: Perform maintenance tasks for @markuplint/html-spec
----
-# html-spec-maintenance
-Perform maintenance tasks for `@markuplint/html-spec`: regenerate specification data,
-review upstream changes, update manual spec files, and ensure cross-package consistency.
-## Input
-`$ARGUMENTS` specifies the task. Supported tasks:
-| Task                                  | Description                                            |
-| ------------------------------------- | ------------------------------------------------------ |
-| `update`                              | Regenerate `index.json` and review upstream changes    |
-| `add-element <name>`                  | Add a new HTML element specification                   |
-| `add-svg-element <name>`              | Add a new SVG element specification                    |
-| `add-attribute <element> <attr>`      | Add an attribute to an element                         |
-| `remove-attribute <element> <attr>`   | Remove an attribute from an element                    |
-| `obsolete-element <name>`             | Mark an element as obsolete                            |
-| `obsolete-attribute <element> <attr>` | Mark an attribute as deprecated                        |
-| `change-flag <element> <attr> <flag>` | Change `experimental`/`deprecated`/`nonStandard` flags |
-| `check`                               | Verify cross-package consistency                       |
-If omitted, defaults to `update`.
-## Reference
-Before executing any task, read `docs/maintenance.md` (or `docs/maintenance.ja.md`)
-for the full guide. The recipes there are the source of truth for procedures.
-Also read:
-- `docs/element-spec-format.md` -- JSON spec file format reference
-- `docs/build-pipeline.md` -- Build pipeline and data precedence rules
-## Task: update
-The primary maintenance workflow. Regenerate `index.json` with the latest MDN/W3C data
-and review what has changed.
-### Step 1: Regenerate
-```bash
-yarn up:gen
-```
-This runs the generator scripts in `generator/`, which scrape live MDN data and merge it with
-the manual spec files in `src/`. The result is written to `index.json`.
-### Step 2: Review the diff
-```bash
-git diff packages/@markuplint/html-spec/index.json
-```
-Categorize each change:
-| Category                        | Examples                                                           | Action                                                                                                                    |
-| ------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
-| **Minor description rewording** | MDN refines role/element/attribute descriptions                    | Commit as-is                                                                                                              |
-| **New attributes**              | `interestfor`, `switch` added by MDN                               | Commit as-is (MDN-sourced, no manual spec change needed)                                                                  |
-| **Flag transitions**            | `experimental` → `deprecated`, `nonStandard` added/removed         | Commit as-is                                                                                                              |
-| **Significant spec changes**    | ARIA property `required` → `inherited`, content model restructured | Requires manual spec update (go to Step 3)                                                                                |
-| **ARIA 1.3 updates**            | New/revised role definitions, property requirement changes         | WAI-ARIA 1.3 is a Working Draft -- expect ongoing changes. 1.1 and 1.2 are finalized Recommendations and will not change. |
-> **Caution -- ARIA version duplication:** `index.json` contains role definitions for
-> WAI-ARIA 1.1, 1.2, and 1.3, so many strings appear three times. When editing
-> descriptions or properties, **do not use `replace_all`** -- it will modify all three
-> versions simultaneously. Always target the specific version block you intend to change.
-### Step 3: Handle significant changes (if any)
-If the diff contains substantive changes to element behavior, ARIA mappings, or
-content models:
-1. Identify the affected elements
-2. Determine which source files need updating:
-   - `src/spec.<element>.jsonc` for element-specific changes
-   - `src/spec-common.contents.jsonc` for content model category changes
-   - `src/spec-common.attributes.jsonc` for global attribute changes
-   - In rare cases, `@markuplint/ml-spec` schemas or types may need updating
-3. Make the changes, referencing the authoritative specification:
-   - HTML Living Standard: https://html.spec.whatwg.org/multipage/
-   - HTML-ARIA: https://w3c.github.io/html-aria/
-   - WAI-ARIA: https://w3c.github.io/aria/
-4. Regenerate to incorporate manual spec changes:
-   ```bash
-   yarn up:gen
-   ```
-5. Verify the final diff is correct
-### Step 3b: Idempotency verification (when spec files are modified)
-When you modify `src/spec.*.jsonc` files, verify that your changes produce stable output
-before committing. This ensures the generated `index.json` does not contain unintended
-drift:
-```bash
-# 1. Stage spec files and index.json
-git add packages/@markuplint/html-spec/src/spec.*.jsonc packages/@markuplint/html-spec/index.json
-# 2. Regenerate
-yarn up:gen
-# 3. Check that the attributes you changed are NOT in the diff (= stable output)
-git diff packages/@markuplint/html-spec/index.json | grep '"your-attr"'
-# 4. If stable, discard the regenerated file and use the staged version
-git checkout packages/@markuplint/html-spec/index.json
-# 5. Proceed to commit
-```
-If the diff shows unexpected changes for your attribute, it means the spec file and
-the generator produce different values -- investigate before committing.
-### Step 4: Test and commit
-```bash
-yarn workspace @markuplint/html-spec run test
-```
-Stage and commit `index.json` and any modified `src/` files.
-## Task: add-element
-Add a new HTML element specification. Follow recipe #1 in `docs/maintenance.md`.
-1. Read `src/spec.a.jsonc` as a reference for a typical element
-2. Create `src/spec.<name>.jsonc` with required fields:
-   - `contentModel` with `contents`
-   - `globalAttrs` (`#HTMLGlobalAttrs`, `#GlobalEventAttrs`, `#ARIAAttrs` set to `true`)
-   - `attributes` (element-specific, can be `{}`)
-   - `aria` with `implicitRole` and `permittedRoles`
-3. Add spec URL comments at the top (`//` format)
-4. **Cross-package step**: If the element belongs to content categories (flow, phrasing, etc.),
-   add it to the appropriate categories in `src/spec-common.contents.jsonc`.
-   Without this, `@markuplint/rules`' `permitted-contents` rule will flag the element
-   as invalid content in parent elements that allow those categories.
-5. Regenerate: `yarn workspace @markuplint/html-spec run gen`
-6. Verify the element appears in `index.json`
-7. Run tests: `yarn workspace @markuplint/html-spec run test`
-## Task: add-svg-element
-Add a new SVG element specification. Follow recipe #3 in `docs/maintenance.md`.
-1. Read `src/spec.svg_circle.jsonc` as a reference for a typical SVG element
-2. Create `src/spec.svg_<name>.jsonc` (the `svg_` prefix maps to namespace `svg:<name>`)
-3. Use SVG-specific global attribute categories (`#SVGCoreAttrs`, `#SVGPresentationAttrs`)
-4. For ARIA, use AAM references: `{ "core-aam": true, "graphics-aam": true }`
-5. Regenerate: `yarn workspace @markuplint/html-spec run gen`
-6. Run tests: `yarn workspace @markuplint/html-spec run test`
-## Task: add-attribute
-Add an attribute to an element. Follow recipe #2 in `docs/maintenance.md`.
-1. Open `src/spec.<element>.jsonc`
-2. Add the attribute entry to the `attributes` object. See `docs/element-spec-format.md`
-   for the full attribute definition format. Common patterns:
-   - Simple typed attribute: `"href": { "type": "URL" }`
-   - Conditional attribute: `"accept": { "type": ..., "condition": "[type='file' i]" }`
-   - Boolean attribute: `"disabled": { "type": "Boolean" }`
-3. For a **global** attribute (applies to all elements), edit
-   `src/spec-common.attributes.jsonc` instead, adding the attribute to the
-   appropriate category (e.g., `#HTMLGlobalAttrs`)
-4. Regenerate: `yarn workspace @markuplint/html-spec run gen`
-5. Verify the attribute appears in `index.json` with correct metadata
-6. Run tests: `yarn workspace @markuplint/html-spec run test`
-## Task: remove-attribute
-Remove an attribute from an element's manual specification.
-1. Open `src/spec.<element>.jsonc`
-2. Remove the attribute entry from the `attributes` object
-3. For a **global** attribute, edit `src/spec-common.attributes.jsonc` instead
-4. Regenerate: `yarn workspace @markuplint/html-spec run gen`
-5. Verify the attribute no longer appears in `index.json` for the element.
-   **Note**: If the attribute also exists in MDN data, it will still appear in
-   `index.json` from the MDN source. To fully suppress an MDN-sourced attribute,
-   you may need to override it in the manual spec rather than simply removing it.
-6. Run tests: `yarn workspace @markuplint/html-spec run test`
-## Task: obsolete-element
-Mark an element as obsolete. Follow recipe #8 in `docs/maintenance.md`.
-There are two approaches:
-- **Via generator's hardcoded list** (preferred for standard obsolete elements):
-  Add the element name to the `obsoleteList` array in
-  `packages/@markuplint/html-spec/generator/html-elements.ts`
-- **Via manual spec file**: Set `"obsolete": true` in the element's
-  `src/spec.<element>.jsonc`
-Obsolete elements automatically get:
-- `cite` pointing to the HTML spec obsolete features section
-- `contents: true` (any content allowed)
-- `permittedRoles: true`, `implicitRole: false`
-After making the change:
-1. Regenerate: `yarn up:gen`
-2. Verify the element appears in `index.json` with `"obsolete": true`
-3. Run tests: `yarn workspace @markuplint/html-spec run test`
-## Task: obsolete-attribute
-Mark an attribute as deprecated in an element's specification.
-1. Open `src/spec.<element>.jsonc`
-2. Add `"deprecated": true` to the attribute definition:
-   ```json
-   "align": {
-     "deprecated": true
-   }
-   ```
-   If the attribute already has other fields (`type`, `condition`, etc.),
-   simply add `"deprecated": true` alongside them.
-3. For a **global** attribute, edit `src/spec-common.attributes.jsonc` instead
-4. Regenerate: `yarn workspace @markuplint/html-spec run gen`
-5. Verify the attribute shows `"deprecated": true` in `index.json`
-6. Run tests: `yarn workspace @markuplint/html-spec run test`
-## Task: change-flag
-Change the `experimental`, `deprecated`, or `nonStandard` flag on an attribute.
-These boolean flags indicate the standardization status of an attribute:
-| Flag           | Meaning                                                           |
-| -------------- | ----------------------------------------------------------------- |
-| `experimental` | The attribute is part of an emerging specification not yet stable |
-| `deprecated`   | The attribute is obsolete and should not be used                  |
-| `nonStandard`  | The attribute is not part of any standard                         |
-1. Open `src/spec.<element>.jsonc` (or `src/spec-common.attributes.jsonc` for globals)
-2. Add, change, or remove the flag on the target attribute:
-   ```json
-   "attributionsrc": {
-     "deprecated": true
-   }
-   ```
-   To remove a flag, delete the property entirely.
-3. **Note**: Flags from MDN scraping also appear in `index.json`. Manual spec flags
-   take precedence, so setting a flag in the manual spec will override the MDN value.
-   However, MDN-only attributes (not defined in manual specs) can only be overridden
-   by adding an entry for that attribute in the manual spec.
-4. Regenerate: `yarn workspace @markuplint/html-spec run gen`
-5. Verify the flag change in `index.json`
-6. Run tests: `yarn workspace @markuplint/html-spec run test`
-## ARIA Version System
-### Resolution Logic
-`resolveVersion()` (`@markuplint/ml-spec/src/utils/resolve-version.ts`) checks
-`aria[version]` first, falls back to top-level `aria`. The runtime default is
-`ARIA_RECOMMENDED_VERSION = '1.2'` (`@markuplint/ml-spec/src/utils/aria-version.ts`).
-### Key Placement Rules
-| Key              | Meaning                                                   | Mutability                                   |
-| ---------------- | --------------------------------------------------------- | -------------------------------------------- |
-| Top-level `aria` | Default / latest. Fallback for versions without overrides | Mutable — update to match current W3C Rec    |
-| `"1.1"`          | ARIA 1.1 snapshot                                         | **Frozen** — never add new roles             |
-| `"1.2"`          | ARIA 1.2 snapshot (rarely needed)                         | Only create when top-level diverges from 1.2 |
-### Decision: Where to add new permittedRoles
-1. Is the role in the W3C Recommendation "ARIA in HTML" (ARIA 1.2 based, Aug 2025)?
-   → Add to **top-level only**
-2. Is the role ARIA 1.3 draft-only (not in W3C Rec)?
-   → Add to **top-level**, AND create `"1.2"` key with the current 1.2 list to freeze it
-3. Was the role in the original ARIA 1.1 spec for this element?
-   → It should already be in `"1.1"`. **Never add new roles to `"1.1"`**.
-### permittedRoles Quick Reference
-| Pattern                                  | Meaning                             |
-| ---------------------------------------- | ----------------------------------- |
-| `true`                                   | Any role allowed                    |
-| `false`                                  | No roles allowed                    |
-| `["role1", "role2"]`                     | Specific roles (alphabetical order) |
-| `[{"name": "role", "deprecated": true}]` | Deprecated role                     |
-## Task: check
-Verify cross-package consistency between `@markuplint/html-spec` and related packages.
-1. **Content model categories**: Verify that category names in `src/spec-common.contents.jsonc`
-   match the `Category` enum in `@markuplint/ml-spec/schemas/content-models.schema.json`
-2. **Element membership**: Verify that elements listed in content categories have
-   corresponding `src/spec.<element>.jsonc` files and consistent `contentModel` definitions
-3. **Attribute types**: Check that attribute type references (e.g., `"URL"`, `"<color>"`)
-   exist in `@markuplint/types`' definitions registry
-4. **Schema validation**: Run `yarn workspace @markuplint/html-spec run test` to validate
-   all source JSON files against `@markuplint/ml-spec` schemas
-Report results as:
-```
-| # | Check | Status | Notes |
-```
-## Testing Requirements for Spec Changes
-Spec data changes propagate to multiple test suites. Always run `yarn test`
-(full suite) before committing.
-### Test Matrix
-| Change type                         | Primary test file                            | Also check                                                    |
-| ----------------------------------- | -------------------------------------------- | ------------------------------------------------------------- |
-| ARIA (implicitRole, permittedRoles) | `rules/src/wai-aria/index.spec.ts`           | `ml-spec/src/algorithm/aria/get-permitted-roles-spec.spec.ts` |
-| Attributes (new/changed)            | `rules/src/invalid-attr/index.spec.ts`       | Existing tests with changed enum error messages               |
-| Content model                       | `rules/src/permitted-contents/index.spec.ts` | —                                                             |
-### Cross-Package Impact
-- **Hardcoded role arrays**: `ml-spec/.../get-permitted-roles-spec.spec.ts` has
-  hardcoded `permittedRoles` for img, button, input, form, etc. Update these
-  when changing `permittedRoles` in html-spec.
-- **Enum error messages**: Adding a value to an enum (e.g., button `command`)
-  changes the error message string in existing `invalid-attr` tests.
-### Test Conventions
-- `toStrictEqual` with exact `{ severity, line, col, message, raw }` — never `toBeGreaterThan(0)`
-- Always include both valid (empty violations) and invalid (exact violation) cases
-- ARIA version in tests: `{ rule: { options: { version: '1.1' } } }`
-- Some roles require ARIA attributes: focusable `separator` → `aria-valuenow`,
-  `meter` → `aria-valuenow`
-## Rules
-1. **`index.json` is generated -- never edit it directly.** Always modify `src/` files and regenerate.
-2. **Manual spec data takes precedence over MDN data.** Attributes defined in `src/spec.*.jsonc` override same-named MDN-sourced attributes. Use this to correct inaccurate MDN data.
-3. **Minor MDN description changes should be committed as-is.** Do not attempt to override cosmetic upstream improvements.
-4. **Content model category membership is critical.** A missing element in a category causes `permitted-contents` rule false positives in downstream linting.
-5. **Always run tests after changes.** Schema validation catches structural errors before they propagate to downstream packages.
-6. **Reference authoritative specs for significant changes.** Use WebSearch to verify against HTML Living Standard, WAI-ARIA, and HTML-ARIA before modifying manual spec files.
-7. **Use conventional commit prefixes based on the nature of the change:**
-   | Change type              | Prefix  | Example                                           |
-   | ------------------------ | ------- | ------------------------------------------------- |
-   | Description updates only | `chore` | `chore(html-spec): update role descriptions`      |
-   | Attribute/spec additions | `feat`  | `feat(html-spec): add input switch attribute`     |
-   | Spec data corrections    | `fix`   | `fix(html-spec): correct ARIA mapping for button` |
-8. **Separate spec changes into individual PRs.** Each specification change (new attribute, ARIA mapping fix, etc.) should be on its own branch and PR. Description-only updates can be batched into a single PR.
-9. **Run `yarn test` (full suite) before committing.** Spec changes affect `@markuplint/rules` and `@markuplint/ml-spec` tests.
-10. **Keep `permittedRoles` arrays in alphabetical order.**

package/docs/build-pipeline.ja.md DELETED Viewed

@@ -1,154 +0,0 @@
-# ビルドパイプライン
-ソースファイルと外部データから `index.json` がどのように生成されるかを解説します。
-## 概要
-`@markuplint/html-spec` は `generator/` のスクリプトを使用して、単一の統合 `index.json` ファイルを生成します。ビルドプロセス:
-1. `src/` から 208 個の要素 JSON 仕様ファイル（HTML、SVG、MathML）と 2 個の共通定義ファイルを読み込む
-2. MDN Web Docs、W3C ARIA 仕様、HTML Living Standard から外部データをフェッチ
-3. 手動仕様と外部データをマージ（手動データが常に優先）
-4. 統合結果を `index.json` に出力（約 48K 行、約 1.4MB）
-ビルドは外部データをライブでフェッチするため、ネットワーク依存です。クリーンな実行で数分かかります。
-## ビルドフロー図
-```mermaid
-flowchart TD
-    subgraph inputs ["ソースファイル（html-spec）"]
-        specFiles["src/spec.*.jsonc\n（208 要素ファイル）"]
-        commonAttrs["src/spec-common.attributes.jsonc\n（20 グローバル属性カテゴリ）"]
-        commonContents["src/spec-common.contents.jsonc\n（コンテンツモデルマクロ）"]
-    end
-    subgraph build ["ビルド"]
-        buildScript["build.ts"]
-        specGen["generator/"]
-    end
-    subgraph external ["外部データソース"]
-        mdn["MDN Web Docs"]
-        aria["W3C ARIA（1.1 / 1.2 / 1.3）"]
-        svg["SVG / Graphics ARIA"]
-        mathml["MathML"]
-    end
-    subgraph output ["出力"]
-        indexJson["index.json\n（48K+ 行）"]
-    end
-    specFiles --> buildScript
-    commonAttrs --> buildScript
-    commonContents --> buildScript
-    buildScript --> specGen
-    mdn --> specGen
-    aria --> specGen
-    svg --> specGen
-    mathml --> specGen
-    specGen -->|"手動データ優先で\nマージ"| indexJson
-```
-## ビルドエントリポイント
-`build.ts` が `generator/` の `main()` を呼び出します。
-## 外部データソース
-generator はビルド時に以下の外部ソースからデータをフェッチします。
-| ソース                                    | 提供データ                                                   |
-| ----------------------------------------- | ------------------------------------------------------------ |
-| MDN Web Docs（HTML）                      | 要素の説明、コンテンツカテゴリ、属性メタデータ、互換性フラグ |
-| MDN Web Docs（SVG）                       | SVG 要素の説明、非推奨要素リスト                             |
-| MDN Web Docs（MathML）                    | MathML 要素の説明、非推奨要素リスト                          |
-| WAI-ARIA 1.1（`w3.org/TR/wai-aria-1.1/`） | ロール定義、プロパティ、ステート                             |
-| WAI-ARIA 1.2（`w3.org/TR/wai-aria-1.2/`） | 更新されたロール定義                                         |
-| WAI-ARIA 1.3（`w3c.github.io/aria/`）     | 最新の Editor's Draft                                        |
-| Graphics ARIA                             | グラフィックス固有 ARIA ロール                               |
-| HTML-ARIA（`w3.org/TR/html-aria/`）       | HTML 属性から ARIA プロパティへのマッピング                  |
-generator の内部アーキテクチャ（スクレイピング、キャッシュ、モジュール構成）の詳細は `generator/` ディレクトリを参照してください。
-## データ優先順位ルール
-手動仕様と外部データが重複する場合:
-| データ         | ソース          | 優先度                     |
-| -------------- | --------------- | -------------------------- |
-| `contentModel` | 手動仕様のみ    | 最高（スクレイピングなし） |
-| `aria`         | 手動仕様のみ    | 最高（スクレイピングなし） |
-| `globalAttrs`  | 手動仕様のみ    | 最高（スクレイピングなし） |
-| `attributes`   | 手動仕様 + MDN  | 手動が優先、MDN が補完     |
-| `description`  | MDN のみ        | MDN のみ                   |
-| `categories`   | MDN のみ        | MDN のみ                   |
-| `cite`         | 手動仕様 or MDN | 手動仕様があれば優先       |
-| 互換性フラグ   | 手動仕様 + MDN  | 手動が優先、MDN が補完     |
-ポイント:
-- **手動データが常に優先** -- MDN スクレイピングデータを上書きする
-- `attributes` は、手動仕様に同名の属性がない場合のみ MDN データが追加される
-- `contentModel` と `aria` はスクレイピングされない -- `src/spec.*.jsonc` からのみ取得
-- `cite` URL はデフォルトで MDN ページだが、要素ごとにオーバーライド可能
-**属性マージの詳細動作:**
-1. **仕様ファイルに属性定義あり** -- MDN データ（description、互換性フラグ）がマージ
-   されるが、仕様ファイル側の値が優先される。例えば、仕様ファイルで `"deprecated": true`
-   を設定し、MDN が deprecated フラグを付けていない場合、仕様ファイルの値が使われる。
-2. **MDN にのみ属性あり** -- MDN のメタデータとともにそのまま追加される。
-3. **仕様ファイルにのみ属性あり** -- MDN による補完なしにそのまま使用される。
-## 生成出力構造
-`index.json` は `@markuplint/ml-spec` の `ExtendedSpec` 型に従います。
-```typescript
-{
-  cites: string[];           // フェッチされた全 URL のソート済みリスト
-  def: {
-    "#globalAttrs": { ... }, // 20 グローバル属性カテゴリ
-    "#aria": {               // バージョン別 ARIA 定義
-      "1.1": { roles, props, graphicsRoles },
-      "1.2": { roles, props, graphicsRoles },
-      "1.3": { roles, props, graphicsRoles }
-    },
-    "#contentModels": { ... } // コンテンツモデルカテゴリマクロ
-  },
-  specs: ElementSpec[]       // 要素仕様配列（アルファベット順、MathML は HTML の後、SVG はその後）
-}
-```
-- `cites` -- フェッチされた全 URL（トレーサビリティ用）
-- `def["#globalAttrs"]` -- `spec-common.attributes.jsonc` から
-- `def["#aria"]` -- W3C ARIA 仕様からスクレイピング
-- `def["#contentModels"]` -- `spec-common.contents.jsonc` から
-- `specs` -- マージ済み要素仕様の配列
-## ビルドコマンド
-| コマンド                                                | 説明                                           |
-| ------------------------------------------------------- | ---------------------------------------------- |
-| `yarn workspace @markuplint/html-spec run gen`          | フル生成（ビルド + Prettier フォーマット）     |
-| `yarn workspace @markuplint/html-spec run gen:build`    | 生成のみ                                       |
-| `yarn workspace @markuplint/html-spec run gen:prettier` | Prettier で `index.json` をフォーマット        |
-| `yarn up:gen`                                           | リポジトリルートから全 spec パッケージを再生成 |
-`gen` は `npm-run-all` を使用して `gen:build` → `gen:prettier` を順次実行します。
-## エクスポート
-パッケージは 2 通りの方法でデータをエクスポートします。
-```json
-{
-  ".": { "import": { "default": "./index.js", "types": "./index.d.ts" } },
-  "./json": "./index.json"
-}
-```
-型付きラッパーのインポート、または `./json` サブパスによる生の JSON アクセスが可能です。

package/docs/build-pipeline.md DELETED Viewed

@@ -1,155 +0,0 @@
-# Build Pipeline
-This document describes how `index.json` is generated from the source files and external data.
-## Overview
-The `@markuplint/html-spec` package uses `generator/` scripts to produce a single consolidated `index.json` file. The build process:
-1. Reads 208 per-element JSON spec files (HTML, SVG, MathML) and 2 common definition files from `src/`
-2. Fetches external data from MDN Web Docs, W3C ARIA specifications, and the HTML Living Standard
-3. Merges manual specifications with external data (manual data takes precedence)
-4. Writes the consolidated output to `index.json` (~48K lines, ~1.4MB)
-The build is network-dependent because external data is fetched live. Expect several minutes on a clean run.
-## Build Flow Diagram
-```mermaid
-flowchart TD
-    subgraph inputs ["Source Files (html-spec)"]
-        specFiles["src/spec.*.jsonc\n(208 element files)"]
-        commonAttrs["src/spec-common.attributes.jsonc\n(20 global attribute categories)"]
-        commonContents["src/spec-common.contents.jsonc\n(content model macros)"]
-    end
-    subgraph build ["Build"]
-        buildScript["build.ts"]
-        specGen["generator/"]
-    end
-    subgraph external ["External Data Sources"]
-        mdn["MDN Web Docs"]
-        aria["W3C ARIA (1.1 / 1.2 / 1.3)"]
-        svg["SVG / Graphics ARIA"]
-        mathml["MathML"]
-    end
-    subgraph output ["Output"]
-        indexJson["index.json\n(48K+ lines)"]
-    end
-    specFiles --> buildScript
-    commonAttrs --> buildScript
-    commonContents --> buildScript
-    buildScript --> specGen
-    mdn --> specGen
-    aria --> specGen
-    svg --> specGen
-    mathml --> specGen
-    specGen -->|"merge\n(manual takes precedence)"| indexJson
-```
-## Build Entry Point
-The build is triggered via `build.ts`, which calls the `main()` function from `generator/index.ts`.
-## External Data Sources
-The generator fetches live data from the following sources during the build:
-| Source                                   | Data Provided                                                                     |
-| ---------------------------------------- | --------------------------------------------------------------------------------- |
-| MDN Web Docs (HTML)                      | Element descriptions, content categories, attribute metadata, compatibility flags |
-| MDN Web Docs (SVG)                       | SVG element descriptions and deprecated element list                              |
-| MDN Web Docs (MathML)                    | MathML element descriptions and deprecated element list                           |
-| WAI-ARIA 1.1 (`w3.org/TR/wai-aria-1.1/`) | Role definitions, properties, states                                              |
-| WAI-ARIA 1.2 (`w3.org/TR/wai-aria-1.2/`) | Updated role definitions                                                          |
-| WAI-ARIA 1.3 (`w3c.github.io/aria/`)     | Latest editor's draft                                                             |
-| Graphics ARIA                            | Graphics-specific ARIA roles                                                      |
-| HTML-ARIA (`w3.org/TR/html-aria/`)       | HTML attribute to ARIA property mappings                                          |
-For details on the generator's internal architecture (scraping, caching, module structure), see the `generator/` directory.
-## Data Precedence Rules
-When manual specifications and external data overlap:
-| Data                | Source             | Precedence                  |
-| ------------------- | ------------------ | --------------------------- |
-| `contentModel`      | Manual spec only   | Highest (never scraped)     |
-| `aria`              | Manual spec only   | Highest (never scraped)     |
-| `globalAttrs`       | Manual spec only   | Highest (never scraped)     |
-| `attributes`        | Manual spec + MDN  | Manual wins; MDN fills gaps |
-| `description`       | MDN only           | MDN only                    |
-| `categories`        | MDN only           | MDN only                    |
-| `cite`              | Manual spec or MDN | Manual spec if provided     |
-| Compatibility flags | Manual spec + MDN  | Manual wins; MDN fills gaps |
-Key points:
-- **Manual data always takes precedence** over MDN-scraped data
-- For `attributes`, MDN-scraped attributes are added only when the manual spec does not define that attribute name
-- Content models and ARIA mappings are never scraped -- they come exclusively from your `src/spec.*.jsonc` files
-- The `cite` URL defaults to the MDN page but can be overridden per element
-**Attribute merge behavior in detail:**
-1. **Attribute defined in spec file** -- MDN data (description, compatibility flags) is
-   merged in, but spec-side values take precedence. For example, if the spec file sets
-   `"deprecated": true` but MDN does not flag the attribute as deprecated, the spec
-   value wins.
-2. **Attribute exists only in MDN** -- Added to the element as-is with MDN metadata.
-3. **Attribute exists only in spec file** -- Used as-is with no MDN augmentation.
-## Generated Output Structure
-The `index.json` follows the `ExtendedSpec` type from `@markuplint/ml-spec`:
-```typescript
-{
-  cites: string[];           // Sorted list of all URLs fetched during generation
-  def: {
-    "#globalAttrs": { ... }, // 20 global attribute categories
-    "#aria": {               // ARIA definitions per version
-      "1.1": { roles, props, graphicsRoles },
-      "1.2": { roles, props, graphicsRoles },
-      "1.3": { roles, props, graphicsRoles }
-    },
-    "#contentModels": { ... } // Content model category macros
-  },
-  specs: ElementSpec[]       // Element specifications, sorted alphabetically (MathML after HTML, SVG after MathML)
-}
-```
-- `cites` -- all fetched URLs, for traceability
-- `def["#globalAttrs"]` -- from `spec-common.attributes.jsonc`
-- `def["#aria"]` -- scraped from W3C ARIA specifications
-- `def["#contentModels"]` -- from `spec-common.contents.jsonc`
-- `specs` -- merged element specifications array
-## Build Commands
-| Command                                                 | Description                                       |
-| ------------------------------------------------------- | ------------------------------------------------- |
-| `yarn workspace @markuplint/html-spec run gen`          | Full generation (build + Prettier formatting)     |
-| `yarn workspace @markuplint/html-spec run gen:build`    | Generation only                                   |
-| `yarn workspace @markuplint/html-spec run gen:prettier` | Format `index.json` with Prettier                 |
-| `yarn up:gen`                                           | Regenerate all spec packages from repository root |
-The `gen` script runs `gen:build` then `gen:prettier` in sequence via `npm-run-all`.
-## Exports
-The package exports the data in two ways:
-```json
-{
-  ".": { "import": { "default": "./index.js", "types": "./index.d.ts" } },
-  "./json": "./index.json"
-}
-```
-Consumers can import the typed wrapper or access the raw JSON via the `./json` subpath.