HTML契約（スライド記述ルール）

ショーラボ html2pptx エンジンが「編集可能なPowerPoint」へ変換できるHTMLの書き方です。
このルールに従うほど、グラデーション・影・SVG・日本語が画像化されずネイティブOOXMLとして出力されます。

1. スライドの骨格

スライド1枚 = <section class="slide"> 1つ。幅・高さを明示し、要素は絶対配置が基本です。

<section class="slide" style="position:relative; width:1600px; height:900px;
         background:#FDFBF7; font-family:'Noto Sans JP',sans-serif; overflow:hidden;">
  <h1 data-el="title" style="position:absolute; left:80px; top:70px; ...">タイトル</h1>
  ...
  <div data-notes style="display:none;">このスライドのナレーション原稿</div>
</section>

推奨キャンバスは 1600×900px（16:9、13.333×7.5inにマップ、px→pt ≈ ×0.6）
複数の <section class="slide"> を並べるとマルチスライドのデッキになります
スライド背景は単色・linear-gradient どちらも可（グラデはネイティブ gradFill 出力）

2. データ属性リファレンス

属性	値	意味
`data-el="役割名"`	任意の文字列	変換対象要素の宣言（シェイプ名になる）。省略時は自動抽出（視覚コンテナ・テキスト葉を自動検出）
`data-slide-title`	任意の文字列	`section.slide` のPowerPointスライド識別名（可視要素は追加しない）
`data-shape`	`rect` / `roundRect`	図形種の明示（省略時は border-radius から自動判定）
`data-anchor`	`t` / `ctr` / `b`	テキストの垂直アンカー（既定 ctr）
`data-notes`	—	スピーカーノート原稿。`display:none` で不可視にする。TTSナレーション・動画化の原稿を兼ねる
`data-chart`	JSON	ネイティブグラフ（c:chart）。`{"kind":"bar\|pie\|line", "title":"...", "categories":[...], "series":[{"name":"...","values":[...]}]}`
`data-anim`	`fadeIn` / `fadeInUp` / `appear`	クリックで出現するエントランスアニメーション
`data-transition`	`fade` / `push` / `wipe` / `none`	スライドの画面切替（section に付与）

3. ネイティブ変換されるCSS（＝あとから編集できる）

HTML/CSS	PowerPoint出力
`background: linear-gradient(...)`	a:gradFill（角度・多段ストップ・透過対応）
`box-shadow`	a:outerShdw（ネイティブ影）
`border-radius` / `border`	prstGeom roundRect / a:ln（枠線。dash/dot対応）
インライン `<svg>`（path/rect/circle/line/polygon…）	a:custGeom — 図形1つ1つが独立の編集可能ベクター。fill-opacity/stroke-opacity/破線対応
`<table>`	a:tbl（ネイティブ表。結合セル・罫線・塗り対応）
`data-chart`	c:chart + 埋め込みxlsx（数値はExcel編集）
テキスト（太字/斜体/色/サイズのインラインspan、`<br>`、リスト、`::before/::after` のcontent文字列）	a:r ラン分割で忠実に再現。全ランに `lang="ja-JP"`
flexbox中央寄せ / `text-align` / `letter-spacing` / `line-height` / `opacity`（祖先含む）	algn / spc / lnSpc / a:alpha へ写像
`<img>`（png/jpeg）	p:pic（原寸埋め込み）。REST API / MCP は base64 の `data:image/png` / `data:image/jpeg` のみ。ローカルCLIはファイルパスも利用可
`transform: rotate(θ)`	a:xfrm rot（回転シェイプ）

4. 非対応（変換前に除去/置換してください）

`<script>` / `<iframe>` / `<canvas>` / `<video>` / イベント属性	REST API / MCP ではキュー投入前に 400 で拒否されます
外部URL、相対パス、`file://`、CSS `@import`	REST API / MCP では拒否。画像は base64 PNG/JPEG、SVGはインラインで記述してください
CSSアニメーション / JSによる動的レイアウト	REST API / MCP では拒否。最終状態の静的HTML/CSSへ変換してから送信してください
`radial-gradient`	現状は単色フォールバック（linear-gradient を推奨）
SVG内の `<text>` / `<image>` / `<use>` / フィルタ類	そのSVGはPNG+ベクター二層のフォールバックになります

5. フォントと日本語

日本語は Noto Sans JP を推奨（使用グリフの静的サブセットをPowerPoint互換EOTにして ppt/fonts/*.fntdata へ実埋め込み）
フォントが無いPCで開いても見た目が保たれます。全テキストランに lang="ja-JP" と ea typeface を付与
本文はみ出し時はブラウザ実測に基づく normAutofit で自動縮小

6. ナレーション付き動画（MP4）

各スライドの data-notes を原稿として、TTS音声合成＋スライド描画で MP4 を生成できます。

# REST API
POST /v1/export  { "html": "...", "format": "mp4", "tts": true, "wait": true }

# CLI（オンプレ）
npm run video -- slides.html slides.mp4 --tts

7. クレジット計算

1スライド=1クレジット。TTSナレーション +1/枚、MP4化 +3/枚。プラン一覧は GET /v1/plans。

検証のヒント: 変換結果の忠実度は付属ハーネス（SSIM+ピクセル差分率の一覧レポート）で数値確認できます。まずは 1600×900 の1枚から始めて、data-el を付けて配置を明示すると最も安定します。