Agent Skill のコンポーネント API テーブル生成を CEM から取得へ変更

Agent Skill が出力するコンポーネント API テーブルの生成元を、HTML スクレイピングから Custom Elements Manifest (CEM) 直接参照へ置き換え、テーブル内容の情報ロスを解消します。

背景

この PR は、Agent Skill が生成するコンポーネント API テーブルの取得方法を変更し、テーブルの正確性を向上させます。

従来はビルド済みドキュメントの HTML をスクレイピングしていましたが、スクレイピングにより型情報やデフォルト値が単一セルに統合され、インライン <code> が失われるなどのデータ欠損が発生していました（#2475）。

HTML から直接抽出する手法ではなく CEM からデータを取得することで、元データの完整性を保持したままテーブルを生成できるようになります。

技術的な変更

renderComponentApiTable 関数を新規追加し、CEM のデータ構造を受け取って Markdown 形式のテーブルまたはスロット一覧を生成します。

function renderComponentApiTable(section, component) {
  const bt = s => '`' + s + '`';
  const esc = s =>
    String(s ?? '')
      .replace(/\r?\n/g, ' ')
      .replace(/\|/g, '\\|')
      .replace(/\s+/g, ' ')
      .trim();
  const codeOrDash = s => {
    const t = esc(s);
    return t ? bt(t) : '—';
  };
  const table = (headers, rows) =>
    rows.length
      ? ['| ' + headers.join(' | ') + ' |', '| ' + headers.map(() => '---').join(' | ') + ' |', ...rows].join('\n')
      : null;

  switch (section) {
    case 'Slots': {
      const slots = component.slots || [];
      if (!slots.length) return null;
      const lines = [
        'Valid slot names for this component (use exactly these — any other `slot` value is',
        'silently ignored and the element falls back to the default slot):',
        '',
      ];
      for (const s of slots) {
        const name = s.name ? bt(esc(s.name)) : '`(default)`';
        lines.push(`- ${name} — ${esc(s.description) || 'No description.'}`);
      }
      return lines.join('\n');
    }
    // Attributes, Methods, Events, CSS custom properties, Custom States, CSS parts are handled similarly
  }
}

processHtmlToMarkdown 内で API テーブル対象のセクションを検知すると、上記ヘルパーを呼び出して生成した Markdown を一時的なプレースホルダーとして保存します。後続の Turndown パスが完了した後にプレースホルダーを実際のテーブル文字列に置換するため、バックティックや角括弧がエスケープされずに出力されます。

copyAllComponentDocs 関数の呼び出しに component 引数を追加し、各コンポーネントの CEM データを渡せるよう修正しました。これにより、全コンポーネントで同一ロジックが適用されます。

これらの変更により、API テーブルは CEM から生成され、型・デフォルト・説明が完全に保持された状態で Markdown に変換されます。既存の出力形式やビルドフローは変更されません。

設計判断

CEM 直接参照を選択したのは、情報ロスの根本原因を取り除きつつ、既存のドキュメント生成パイプラインに最小限の侵入で済ませるという方針に沿ったためです。scripts/llms.js が既に CEM からデータを取得している実装を再利用することで、コードの重複を防ぎ保守性を向上させました。

テーブル生成ロジックはプレースホルダー方式を維持しているため、他の Markdown 変換ステップへの副作用はなく、既存の利用者に対する互換性が保たれます。

この設計は、データ取得元を変更するだけで機能的な振る舞いを変えず、将来的な CEM スキーマ変更にも比較的柔軟に対応できる構造となっています。

まとめ

Agent Skill はコンポーネント API テーブルを CEM から直接生成するようになり、型情報・デフォルト値・説明文が正確に保持されます。テーブル生成フローは既存と同様の出力を行うため、利用者への影響はなく、ドキュメント品質の向上が期待されます。