akari-video 0.1.0

package/vendor/skills/overlay-authoring/3d.md

@@ -0,0 +1,143 @@
+# Three.js + glTF authoring
+
+## 経路の振り分け（まずここを判定）
+
+本スキルの対象は**映像の上に重なるオーバーレイ 3D**（経路 A）だけ。3D シーンを動かして
+**映像素材（クリップ）そのもの**を作る用途（経路 B）はオーバーレイでやらない —
+Blender ヘッドレスで焼き込む。契約: `docs/contract-2026-07-14-3d-bake-recipe.md`。
+判定基準: タイムラインにクリップとして置くなら B、映像の上に重ねるなら A。
+
+## 現在の実装ゲート
+
+live preview v0 は、fragment 内の非実行 JSON 宣言を信頼済みランタイムが読み、
+ローカル `.glb` の静的シーンと内蔵 animation clip を描画できる。fragment の任意
+JavaScript は実行しない。モデルは edit.json 相対パスから preview 専用 localhost
+asset URL へ変換され、Three.js core と GLTFLoader は pinned IIFE として同梱される。
+
+export（render-cut）は同じ Three.js runtime を puppeteer-core 経路で動かし、ローカル
+`.glb` を自己完結 data URI として埋め込んで 3D overlay を焼き込む。
+
+根拠: `packages/overlay-runtime/src/overlay-runtime.js`、
+`packages/overlay-runtime/src/three-runtime.js`、[WHATWG HTML — scripting](https://html.spec.whatwg.org/dev/scripting.html)
+
+## 宣言型 fragment スキーマ（preview v0）
+
+fragment は単一ルートとし、透明 canvas、任意の静的 fallback、非実行の
+`<script type="application/json" data-akari-3d-scene>` を 1 個だけ置く。
+
+```html
+<div class="product-spin">
+  <canvas class="product-spin__canvas"></canvas>
+  <div data-akari-3d-fallback>3D を読み込み中</div>
+  <script type="application/json" data-akari-3d-scene>
+  {
+    "model": "assets/models/product.glb",
+    "camera": {
+      "position": [0, 1.2, 3],
+      "fov": 45,
+      "near": 0.1,
+      "far": 100,
+      "lookAt": [0, 0.5, 0]
+    },
+    "environment": {
+      "intensity": 1.0,
+      "exposure": 1.0
+    },
+    "lights": [
+      { "type": "ambient", "color": "#ffffff", "intensity": 0.35 },
+      {
+        "type": "directional",
+        "color": "#ffffff",
+        "position": [2, 3, 2],
+        "lookAt": [0, 0.5, 0],
+        "intensity": 1.2
+      }
+    ],
+    "materialOverrides": {
+      "ScreenMaterial": { "texture": "assets/screens/app-01.png" }
+    },
+    "animationClip": "Idle"
+  }
+  </script>
+</div>
+```
+
+- top-level key は `model` / `camera` / `environment` / `lights` / `animationClip` / `materialOverrides` だけ。
+- `model` は edit.json のあるディレクトリからの相対 `.glb` パス。URL や CDN を書かない。
+- camera は perspective camera。`position` / `lookAt` は `[x, y, z]`、`fov` / `near` / `far` は数値。
+- `environment` は手続き生成 IBL の knob。`intensity` は金属など PBR マテリアルへの環境光強度、
+  `exposure` は ACES Filmic tone mapping の露出で、どちらも 0 以上の数値を指定する。省略時は
+  `intensity` は `0.5`、`exposure` は `1.0`。外部 HDR 画像の URL は受け付けない。まず既定値で
+  確認し、白飛びを抑えるなら `exposure`、映り込み自体の強弱を変えるなら `intensity` を小幅に調整する。
+  IBL 自体（既定値での環境マップ・トーンマッピング）は preview / export とも常に有効 — `environment`
+  キーは既定値からの微調整用の任意 knob。
+  ⚠️ **既知の制限**: `environment` キーを明示宣言すると、現行の preview 側パス解決
+  （`akari-preview-open-handler.ts` の 3D シーン許可キー一覧が未対応）が拒否し model パスが
+  空になって preview 側の読み込みが失敗する（export は影響を受けない・別経路のため）。
+  fix 待ちの間は `environment` キーを省略し既定値のまま使うこと。
+- light type は `ambient` または `directional`。directional は `position` と `lookAt` を宣言できる。
+- `animationClip` は glTF 内蔵 clip の正確な名前。省略時は静的シーンを描画する。
+- `materialOverrides` は `{ "<material 名>": { "texture": "<画像の相対パス>" } }` の形で、名前が一致するマテリアルの `emissiveMap` を差し替える。画像は edit.json のあるディレクトリからの相対 PNG / JPEG / WebP 等を指定し、URL や CDN を書かない。該当するマテリアル名がモデル内にない場合は警告して無視される。
+- canvas は CSS で表示寸法を必ず与える。fallback に `data-akari-3d-fallback` を付けると load 完了時だけ隠れる。fallback は自由にスタイルしてよく、`display` を宣言しても load 完了時にランタイムが確実に隠す。
+
+## 原則
+
+- 3D は Three.js、交換形式は glTF 系に限定する。preview v0 は外部 buffer を持たない自己完結 `.glb` と、`materialOverrides` で指定したローカル画像を受け付ける。Draco/KTX2 は未対応。
+- Three.js 本体、addon、decoder、model、texture はローカルへ固定し、CDN import を使わない。export Chrome は background network を無効化する。
+- fragment は上記の宣言型スキーマに限定する。任意 script、event handler、`new Function()` 等を使わない。
+- 単一ルート内へ透明 canvas と静的 fallback を置く。canvas は透明合成を有効にし、背景を不透明に塗りつぶさない。
+- asset は visible な期間だけ load / render / decode され、区間外と unmount で geometry、material、texture、renderer が解放される。
+- camera、light、model pose、material、screen source を CSS 変数または素材 metadata の knob として宣言する。固定すべき model topology まで knob にしない。
+
+## ライセンス済み glb
+
+1. 配布元、asset ID / version、author、取得日、license、商用可否、改変可否、帰属表示を確認する。
+2. glTF 形式であることを利用許諾と取り違えない。license 不明の model は使わない。
+3. library からリンクせず、採用する project へ `.glb` と必要 texture / decoder をコピーする。
+4. project 側 provenance に元 library、version、license、attribution を残す。
+5. 相対 URL で読み込み、load error 時に空 canvas のまま成功扱いしない。
+
+素材ライブラリ利用時のコピー規律は `docs/contract-2026-07-13-asset-library.md` に従う。
+
+## 決定的な 3D アニメーション
+
+- preview v0 は overlay の local timeline 秒を `AnimationMixer.setTime(localSeconds)` に渡し、その状態だけを render する。
+- `THREE.Clock` や `mixer.update(delta)` で時間を積算しない。カメラ、shader time、particle も同じ local timeline から求める。
+- rAF は算出済みの時刻を描画するためだけに使い、rAF delta を状態へ足さない。
+- glTF clip がない動きも、local time の関数として pose を求める。再生・停止・逆シークで同じ結果になることを確認する。
+
+公式: [Three.js AnimationMixer.setTime](https://threejs.org/docs/pages/AnimationMixer.html#setTime)
+
+## VideoTexture
+
+- `VideoTexture` の source は HTMLVideoElement とし、**編集用 720p プロキシ**を与える。原本を preview 用 texture へ接続しない。
+- `source.proxy` の自動生成は現時点で未実装である。proxy がなければ先に生成し、ないまま原本へ黙って fallback しない。
+- `<video>.currentTime` を overlay local timeline へ同期してから texture を更新する。autoplay / loop の wall-clock 再生へ任せない。
+- 現行 preview / export は `<video>.currentTime` を同期しないため、動画 texture は **未対応** とする。
+- source の寸法・format を変える場合は既存 texture を dispose し、作り直す。
+
+公式: [Three.js VideoTexture](https://threejs.org/docs/pages/VideoTexture.html)
+
+## パフォーマンス
+
+- 4K 上の post-process blur、`filter: blur()`、`backdrop-filter`、過剰な shadow を使わない。
+- 毎フレームの object / material / texture 生成、shader compile、model reload を避ける。
+- preview v0 と export の renderer pixel ratio は `1` 固定。同一 scene の見え方を対象出力 profile で実測する。
+- `renderer.info` で draw calls、triangles、textures を計測する。固定の polygon / draw-call 上限は一次根拠がないため発明せず、対象 Mac と出力 profile で **要検証** とする。
+
+公式:
+
+- [Three.js GLTFLoader](https://threejs.org/docs/pages/GLTFLoader.html)
+- [Three.js — How to dispose of objects](https://threejs.org/manual/en/how-to-dispose-of-objects.html)
+
+## よくある間違い
+
+- CDN の Three.js、decoder、texture に依存する。
+- Draco / KTX2 圧縮モデルを v0 へ渡す（decoder と worker は未対応）。
+- license 不明の `.glb` を「ネットで見つけた素材」として同梱する。
+- JSON 宣言の代わりに fragment 内の `<script>` を実行させようとする。
+- export だけを見て WYSIWYG 対応済みと報告する。
+- proxy がないため原本を `VideoTexture` へ流す。
+- `Clock.getDelta()` / `mixer.update(delta)` でアニメーションする。
+- 非表示後も render loop と video decode を動かす。
+- dispose せず、素材切替のたびに GPU resource を残す。

package/vendor/skills/overlay-authoring/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: overlay-authoring
+description: AKARI Video のオーバーレイ HTML、字幕、表・グラフ、Three.js 3D、モーショングラフィックス、サムネイル、人物の後ろに文字を置く表現を設計・生成・レビューするときに発動する authoring ルーター。
+---
+
+# FORBIDDEN 級ハードルール
+
+> **Language**: Respond in the user's language — 対話・質問・承認確認・レポートはユーザーの使用言語に合わせる（例: 英語で話しかけられたら英語で応答する）。
+
+次のいずれかに違反する動画オーバーレイを作成・採用しない。詳細リーフより常に優先する。
+
+1. **調整値を直書きしない。** 位置、拡縮、文字サイズ、色、余白、内容など、人が調整しうる値を CSS 変数として公開する。`--x`、`--y`、`--scale`、`--font-size`、`--color` などを使い、`edit.json.overlays[].vars` から継承できるよう `var(--name, fallback)` で参照する。断片ルートで同名変数を再定義して上書きを遮らない。
+2. **時刻を別の仕組みに持たせない。** タイミングは `data-start` / `data-duration` とする。AKARI Video v0 では `edit.json.overlays[].start/duration` が SSOT で、ランタイムが外側コンテナの data 属性へ反映する。断片内の独立した時刻源を作らない。
+3. **layout を毎フレーム動かさない。** アニメーションは `transform` / `opacity` 中心にする。4K 映像上の `filter: blur()` と `backdrop-filter` は禁止する。
+4. **wall-clock で絵を決めない。** `Date.now()`、`performance.now()` の経過差、`setTimeout`、`setInterval`、rAF の delta 積算、未 seed の乱数に表示状態を依存させない。シーク時に WAAPI の `currentTime` を設定すれば同じ時刻の絵が再現される決定的設計にする。
+5. **3D の別方式を持ち込まない。** 3D は Three.js + glTF とし、動画テクスチャは `VideoTexture` に編集用プロキシを与える。原本をプレビュー用テクスチャへ直結しない。
+6. **トップレベルを複数にしない。** HTML 断片のルート要素は必ず 1 つにする。AKARI の外側コンテナによる translate / scale / rotate が常に効く構造を保つ。
+
+# リーフ目次
+
+必要な判断領域だけを読む。
+
+- 字幕・テロップの日本語組版、可読性、配置: [telop.md](telop.md)
+- 表・グラフの HTML/CSS 構成とアニメーション: [table.md](table.md)
+- Three.js + glTF、動画テクスチャ、3D 性能: [3d.md](3d.md)
+- 決定的モーション、イージング、compositor 制約: [motion.md](motion.md)
+- サムネイルの型、デザイン語彙、生成経路、HTML スクショ: [thumbnail.md](thumbnail.md)
+- 人物切り抜き、HEVC alpha、text-behind-person: [text-behind-person.md](text-behind-person.md)
+
+静止サムネイル用 HTML シートは動画オーバーレイではないため timing data 属性を不要とする。ただし、CSS 変数化、単一ルート、ローカル資産、決定的なスクリーンショットという考え方は維持する。

package/vendor/skills/overlay-authoring/motion.md

@@ -0,0 +1,58 @@
+# モーショングラフィックス設計
+
+## 原則
+
+表示状態を `localTime = max(0, timelineTime - start)` と公開変数から求める純粋な設計にする。同じ localTime へシークしたとき、再生経路に関係なく同じ絵を返す。
+
+- 主経路は CSS animation または WAAPI とする。ランタイムは descendant animation を pause し、`currentTime = localTime * 1000` に設定する。
+- transition は「状態を変更した瞬間」に依存するため、主タイムラインの演出には使わない。
+- animation event の発火回数や順序へ副作用を持たせない。シークはイベント区間を飛び越えうる。
+- particle や反復要素は先に DOM を確定し、index と固定 seed から値を作る。再生中に未 seed の乱数で作り直さない。
+- 外側コンテナの transform は AKARI の幾何操作用、断片内の子 transform は演出用として分離する。
+
+## イージング語彙
+
+| 意図 | CSS 語彙 | 使い方 |
+|---|---|---|
+| 等速・進捗・連続回転 | `linear` | 速度変化そのものに意味がない動き |
+| 入場・減速して止まる | `ease-out` | 画面外から定位置へ入る要素 |
+| 退場・加速して去る | `ease-in` | 定位置から画面外へ出る要素 |
+| 姿勢 A と B の往復 | `ease-in-out` | カード反転、視線移動、穏やかな遷移 |
+| 離散切替 | `steps()` | カウンタの桁、LED、コマ送り風表現 |
+
+独自 `cubic-bezier()` は named easing で意図を表せない場合だけ使い、CSS 変数化して理由を残す。標準キーワードの定義は [W3C CSS Easing Functions Level 2](https://www.w3.org/TR/css-easing-2/) を参照する。
+
+## compositor 合成の制約
+
+- 毎フレーム変えるのは原則 `transform` と `opacity` に限る。
+- `top`、`left`、`width`、`height`、margin、padding、grid track、DOM 挿抜をアニメーションしない。
+- 4K 映像上の `filter: blur()` と `backdrop-filter` を使わない。ぼかしが不可欠なら事前処理した画像を使う。
+- static な背景、border、shadow は必要最小限にする。重い paint が疑われる場合は実際の出力解像度で計測し、根拠のない性能閾値を発明しない。
+- `will-change` を全要素へ常設しない。対象と有効期間を限定する。
+
+## 決定性チェック
+
+次を含む場合は不合格にする。
+
+- `Date.now()` / wall-clock 差分
+- `performance.now()` の積算
+- `setTimeout` / `setInterval` で進む状態
+- rAF の delta を足し続ける状態
+- 未 seed の `Math.random()`
+- `AnimationMixer.update(delta)` のような経路依存の積算
+
+rAF は、外部タイムラインから既に決めた状態を再描画する用途に限る。ただし現行 fragment には汎用 JS seek hook がないため、カスタム JS 描画は **要検証** とする。WAAPI の時刻制御は [W3C Web Animations](https://www.w3.org/TR/web-animations-1/) を参照する。
+
+## 静的 fallback
+
+`scripts/render-overlays.mjs` の static Chrome fallback は CSS / WAAPI animation を無効化する。入場途中にしか内容が存在しない構成にせず、代表静止状態でも意味が通るようにする。書き出し時は採用された renderer method を確認する。
+
+## よくある間違い
+
+- CSS transition を開始してから録画時間が進む前提にする。
+- `requestAnimationFrame` のフレーム差を足して位置を決める。
+- bounce 感を出すために意味のない custom easing を乱立する。
+- outer transform と inner motion を同じ要素で競合させる。
+- `filter: blur()` を入退場へ使う。
+- static fallback では文字も結論も見えない。
+- 一般名の `@keyframes fade-in` を使い、別断片と衝突する。

package/vendor/skills/overlay-authoring/table.md

@@ -0,0 +1,41 @@
+# 表・グラフ設計
+
+## 原則
+
+- 正確な値の照合・比較が主目的なら semantic な `<table>` を使う。傾向、順位、構成比を一目で示すなら DOM のラベルと値に CSS Grid / Flex を組み合わせる。
+- データを HTML テキストとして残す。canvas のピクセルだけに値やラベルを閉じ込めない。
+- 表示する値、順序、単位、丸めは authoring 前に確定する。同じ画面で並べる値は同じ基準と単位にそろえる。
+- 色だけで系列を区別せず、ラベル、形、位置も併用する。軸、凡例、基準線を装飾より先に読める状態にする。
+- `--accent-*`、`--label-color`、`--value-color`、`--row-gap`、`--bar-scale` などを CSS 変数で公開する。
+- セレクタと `@keyframes` 名を断片固有のルート配下へ閉じる。
+
+## HTML/CSS の構成
+
+- 表は `<caption>`、`<thead>`、`<tbody>`、`<th scope>` を使い、見た目のためだけに div 表へ崩さない。
+- 棒グラフは「ラベル」「静的な数値」「track」「fill」を DOM に持つ。値を定義域から **0〜1** に正規化し、fill を `transform: scaleX(var(--ratio))` または `scaleY()` で表す。
+- 数字の桁が動く場合は `font-variant-numeric: tabular-nums` を使う。wall-clock の count-up ではなく、最終値を静的に置いて reveal する。
+- 円弧や連続曲線が本当に必要な場合も、値を読める DOM の要約を残す。外部 chart library を安易に追加しない。
+- 行数、文字サイズ、余白の一律閾値はリポ契約にない。収まらない場合は縮小せず、画面を分割する。具体値は出力プロファイルで **要検証** とする。
+
+## アニメーション
+
+- 棒は `transform-origin` を基点側へ置き、scale で伸ばす。`width` / `height` を毎フレーム変えない。
+- 行やカードは translate + opacity で段階表示する。DOM の挿入・削除でレイアウトを揺らさない。
+- 並べ替えは最終順を先に DOM へ置き、必要なら子要素の transform で見せる。再生中に table row を入れ替えない。
+- CSS animation / WAAPI を使い、可視区間 `start <= t < start + duration` のローカル時刻に決定的に対応させる。
+- 静的 Chrome fallback では animation が無効になる。静止状態だけでも値、単位、結論が伝わる構図にする。
+
+## よくある間違い
+
+- 精密な比較を 3D 円グラフや装飾だけで表す。
+- canvas/chart library を導入し、live preview で script が動くと仮定する。
+- 棒の `width`、行の `top`、grid track をアニメーションする。
+- `setInterval` で数値を加算する。
+- 系列色だけで意味を区別する。
+- 情報量が多いまま任意の「最大行数」を発明する、または文字を極端に縮める。
+- グローバルな `table` セレクタや一般名の `@keyframes grow` を使い、他断片と衝突する。
+
+## 根拠
+
+- 時刻、単一ルート、CSS 変数、compositor の契約: `CLAUDE.md` と `docs/contract-2026-07-13-m1-m4.md`
+- 静的 fallback の制約: `scripts/render-overlays.mjs`

package/vendor/skills/overlay-authoring/telop.md

@@ -0,0 +1,69 @@
+# 字幕・テロップ設計
+
+字幕は発話を読み取らせる反復 UI、テロップは要点や感情を強調する画面要素として分けて設計する。両者を同じ密度・同じ強さにしない。
+
+## 原則
+
+- `lang="ja"` を付け、日本語グリフを持つローカルフォントとフォールバックを指定する。書き出し環境に存在しないフォントへ暗黙依存しない。
+- 意味のまとまりで改行する。助詞、句読点、括弧の片側だけを行頭・行末へ孤立させず、必要なら HTML に明示改行を置く。事前に行分割を確定した字幕断片は、行内の再折返しを CSS で禁止し（`white-space: nowrap`）、生成時の改行を唯一の改行にする。
+- 全角・半角、英数字、記号の扱いを作品内で統一する。縦組みは横組みの CSS を回転しただけで済ませない。
+- 字幕は映像内テキストや顔を避け、通常は下側、衝突時は上側または左右へ移す。テロップは視線誘導の対象へ寄せるが、被写体を覆うことを「強調」と取り違えない。
+- 静的な不透明・半透明の地、縁取り、影のいずれかで背景から分離する。`filter: blur()` / `backdrop-filter` に頼らない。
+- `--font-size`、`--line-height`、`--color`、`--background`、`--max-width`、`--safe-*` を調整点として公開する。既定値は `var(--name, fallback)` に置き、外側の `vars` を遮らない。
+- セレクタと `@keyframes` 名を素材固有の接頭辞で閉じる。
+
+## 可読サイズと文字量の目安
+
+焼き込みテロップに全プラットフォーム共通の公式最小 px 値はない。したがって、根拠のない `px` 下限をハードルールにせず、`--font-size` を出力高に応じて決め、最終解像度と想定する最小端末で実読する。未実機の値は **要検証** と記す。
+
+日本語字幕の構造チェックには、Netflix の日本語 Timed Text 仕様を適用条件付きで使える。同仕様は横字幕を **全角 13 文字/行まで**、**2 行まで**とし、半角文字を 0.5 文字として数える。これは Netflix 納品仕様であり、AKARI Video や他プラットフォームへ無条件に一般化しない。長い場合は文字を縮める前に要約・分割する。
+
+AKARI Video の字幕既定は 1 行 20 全角字・句読点優先分割（オーナー裁定）。Netflix 13 字は納品仕様であり AKARI の既定ではない。
+
+出典: [Netflix Japanese Timed Text Style Guide](https://partnerhelp.netflixstudios.com/hc/en-us/articles/215767517-Japanese-Timed-Text-Style-Guide)
+
+## 配置セーフゾーン
+
+固定値を使う前に配信先、広告かオーガニックか、画角、CTA、字幕欄、LTR/RTL を確定する。同名プラットフォームでも条件が違えば数値を流用しない。
+
+| 適用条件 | 公式数値 | 運用 |
+|---|---:|---|
+| YouTube 縦型**動画広告**、1080×1920 | 上 288px、右 192px、下 672px、左 48px を避ける | 重要文字・ロゴを残りの safe area 内へ置く。オーガニック Shorts の値として使わない |
+| Instagram / Facebook **Reels 広告**、9:16 | 下 35% を空ける | 下側に重要文字・ロゴを置かず、Meta の safe-zone checker でも確認する |
+| TikTok Auction In-Feed 広告 | 固定座標なし | 画角、caption 長、追加 format、LTR/RTL に対応する公式 ZIP と Preview を使う。値は **要検証** |
+
+YouTube の safe zone も全端末保証ではない。オーガニック投稿や表にない配信先は、固定座標を書かず **要検証** とし、公開直前のプラットフォーム preview で確認する。
+
+出典:
+
+- [Google Ads Help — About video ad specs](https://support.google.com/google-ads/answer/13547298?hl=en)
+- [Google — Universal Video Ad Safe Zones](https://services.google.com/fh/files/misc/universalsafezones-youtube.pdf)
+- [Meta — The Reels ads guide](https://d3m889aznlr23d.cloudfront.net/img/events/458925814/assets/e042d2be.reels_ads_guide1.pdf)
+- [TikTok Ads Manager — TikTok Auction In-Feed Ads](https://ads.tiktok.com/help/article/tiktok-auction-in-feed-ads)
+
+## コーナーキャプション（TV 風の隅ラベル）
+
+放送の左上・右上に常駐する番組名/コーナー名ラベル。番組タイトル + 現在の章タイトルを出し、章立てに追従させる定型。**素材ライブラリに入れず、この定型から都度生成してよい**（プロジェクト固有のテキスト差し替えが本体で、再利用価値は構造にしかないため）。
+
+- **HTML/CSS で作る。画像生成にしない**: 章ごとのテキスト差し替えが必要で、画像だと章数分の生成と文字品質リスク（画像生成の日本語誤字）を抱える。HTML なら 1 断片 + 章ごとのオーバーレイエントリで済み、プレビューと書き出しが同一ソースを通る
+- **章追従の実装**: 同じ断片を章数分コピーし、章タイトルのテキストと `data-start` / `data-duration` を章の区間に合わせる（1 章 = 1 オーバーレイエントリ）。テキストは**断片 DOM に直接置く**（CSS 変数でのテキスト保持は禁止。変更は html パッチ / contenteditable 経由）
+- **構造の目安**: ルート 1 つ + プレート（番組名の行 + 章名の行、または 1 行連結）。位置は外側コンテナの transform（ランタイム所有）で決め、断片は見た目だけを持つ
+- **常駐物の抑制**: 常時表示なので主張を抑える。小さめの `--font-size`、半透明の地、画面の隅で被写体・字幕・映像内 UI と重ねない。字幕（下側）と同時表示が前提なので、下側には置かない
+- knobs の例: `--plate-bg`、`--accent`、`--font-size`、`--radius`。既定値は `var(--name, fallback)` で公開する
+- 章替わりの出入りは短い opacity / translate のみ。保持中は動かさない（アニメーション節の原則どおり）
+
+## アニメーション
+
+- 字幕の出入りは短い opacity / translate を使い、保持中は動かさない。
+- 1 文字ずつの出現は可読速度とシーク再現性を損ねやすい。必要な演出だけに限定し、文字 DOM は先に確定しておく。
+- CSS animation / WAAPI を使い、ランタイムが `currentTime = (t - start) * 1000` を設定できる形にする。
+- 位置移動の transform は断片内の子要素へ付け、AKARI が所有する外側コンテナの幾何 transform と分離する。
+
+## よくある間違い
+
+- 文字が多いまま font-size だけを下げる。
+- 日本語を画像生成モデルに描かせ、誤字や崩れを納品する。
+- 字幕と強調テロップを常時同時表示して、どちらも読めなくする。
+- 白文字だけを明るい映像へ直置きする。
+- 非公式テンプレートの safe zone 数値を、別の placement やオーガニック投稿へ転用する。
+- 断片ルートで `--font-size` などを再定義し、`edit.json.vars` の上書きを効かなくする。

package/vendor/skills/overlay-authoring/text-behind-person.md

@@ -0,0 +1,224 @@
+# Text behind person
+
+native 映像の上へ文字を置き、その上へアルファ付き人物動画を重ねる。視覚上の順序は必ず `base video < text < cutout video` にする。
+
+## 現在の制約を先に判定する
+
+edit.json v1 の `<video>` 時刻同期は未実装である。現行 preview / export は CSS / WAAPI animation の `currentTime` だけを同期し、fragment 内 `<video>.currentTime` は操作しない。`data-akari-sync` を付けても現時点では効果がない。
+
+したがって、動く人物の text-behind-person を決定的・WYSIWYG・本番対応済みと報告しない。選択肢は次のいずれかにする。
+
+- 静止した人物 alpha PNG / matte で表現する。
+- 外部で text-behind-person を precompose して映像素材にする。
+- v1 runtime の video sync 実装を待ち、preview と export の双方で検証する。
+
+根拠: `docs/notes-2026-07-13-edit-json-v1.md` §4、`ui/overlay-runtime.js`、`scripts/render-overlays.mjs`
+
+## マット参照規約
+
+人物マット（アルファ付き人物動画）を断片から参照する書き方を規約として固定する。データ契約の正本は
+[docs/contract-2026-07-23-analysis-person-matte.md](../../docs/contract-2026-07-23-analysis-person-matte.md)、
+生成手順は [skills/analyze-footage/person-matte.md](../analyze-footage/person-matte.md) にある。
+本節はその**消費側**（断片の書き方）だけを定める。
+
+### 1. 供給元と複製規律
+
+マットの供給元は `analysis.json` の `tracks.person_matte`（契約 §2）が正である。断片を書く
+エージェントは authoring 時に次を行う。
+
+1. `person_matte.path` を **analysis.json の所在ディレクトリ基準**で解決する（契約 §2 フィールド表）。
+   `null` や解決不能なら人物マット無しとして通常のテロップ構成に倒す（契約 §5 の劣化規約）。
+2. 解決した実体を**プロジェクト内へ複製**する。置き場は `assets/matte/<素材名>-person-matte.webm`
+   を既定とする。
+3. 断片からは複製先を **edit.json 相対（プロジェクト相対）パス**で参照する。
+
+analysis 側のパスへ直リンクしない。マットは素材ディレクトリ側に置かれうるため、直リンクした
+プロジェクトは移動・配布・再現でリンクが切れる（プロジェクト自己完結の原則）。プレビューの
+asset 解決（3D 宣言の `resolveAsset`・`akari-preview-open-handler.ts`）も先頭 `/` と URL スキームを
+拒否しており、絶対パスや `file:` URL を書く流儀そのものが通らない。
+
+**複製はバイト単位のコピーで行い、再エンコードしない。** ffmpeg のデコーダに通すとアルファが
+無言で落ちる（契約 §3）。切り出し（`--ss` 相当）も禁止 — 時刻 0 の一致が壊れる（契約 §4）。
+
+### 2. 断片内の参照は `data-akari-matte-src`
+
+**`<video>` の `src` を断片の HTML に直書きしない。** 外側コンテナ（ランタイムが作る
+`.akari-overlay-container` / `#overlay-stage` 直下の div）へ注入される
+**`data-akari-matte-src` 属性**を規約とし、断片はその属性の有無だけを見る。
+
+タイミングの `data-start` / `data-duration`（ハードルール 2）と同じ「**ランタイムが所有する
+data 属性**」の流儀である。理由も同じで、実 URL は経路ごとに違うものになる:
+
+| 経路 | 実際に必要な URL |
+|---|---|
+| プレビュー | `http://127.0.0.1:<port>/asset/<id>`（`createAssetStream` の払い出し。3D の `.glb` と同経路） |
+| 書き出し（render-cut） | オーバーレイシートは `<projectRoot>/.akari/render-tmp/<run>/overlay-sheet.html` に置かれる。プロジェクト相対パスをそのまま書くと 3 階層ずれて解決できない |
+
+断片が知ってよいのはプロジェクト相対パスまでで、経路ごとの実 URL 化は外側の責務である。
+
+属性が無いときは**マット層を出さない**。祖先属性ゲート付きセレクタで宣言する
+（`data-akari-active` と同じ手法。`packages/overlay-runtime/src/overlay-runtime.js` 参照）:
+
+```html
+<div class="tbp-root">
+  <style>
+    .tbp-root { position: absolute; inset: 0; isolation: isolate; }
+    .tbp-root__text {
+      position: absolute; z-index: 1;
+      left: var(--text-x, 8%); top: var(--text-y, 42%);
+      font-size: var(--font-size, 96px); color: var(--color, #fff);
+    }
+    /* マット層は既定で出さない。外側コンテナに属性が注入されたときだけ出す。 */
+    .tbp-root__matte { display: none; }
+    [data-akari-matte-src] .tbp-root__matte {
+      display: block;
+      position: absolute; inset: 0; z-index: 2;
+      width: 100%; height: 100%;
+      object-fit: var(--matte-fit, cover);
+      object-position: var(--matte-position, 50% 50%);
+      pointer-events: none;
+    }
+  </style>
+  <div class="tbp-root__text">正確な日本語テキスト</div>
+  <video class="tbp-root__matte" muted playsinline preload="auto"></video>
+</div>
+```
+
+**劣化は「文字が前に出るだけ」**にする。属性が無い・マットが読めない・再生できない、いずれでも
+テキストと素材映像は出続ける。人物マットは演出の入力であり、映像本体の成否を左右しない（契約 §5）。
+
+### 3. 標準 3 層構造（z）
+
+| 層 | 実体 | 断片に含めるか |
+|---|---|---|
+| 下 | 素材映像（プレビューの `#preview-video` / 書き出しの合成土台） | **含めない** |
+| 中 | テキスト（`z-index: 1`） | 含める |
+| 上 | マット `<video>`（`z-index: 2`・`inset: 0`・`muted`・`playsinline`・`pointer-events: none`） | 含める |
+
+- 断片ルートに `isolation: isolate` を置き、この 2 層の重なりをルート内へ閉じる（単一ルート =
+  ハードルール 6）。
+- テキストの `z-index` をマットより必ず小さくする。逆にすると通常のテロップに戻る。
+- マット `<video>` の `object-fit` / `object-position` を素材映像側の crop 契約に合わせる。ずれると
+  人物の輪郭が背後の素材とずれる。
+- 調整値（テキスト位置・文字サイズ・色・マットの fit / position）は CSS 変数で公開する
+  （ハードルール 1）。断片ルートで同名変数を再定義して外側からの上書きを遮らない。
+
+### 4. 形式は VP9 alpha WebM が第一、HEVC alpha は fallback
+
+- **第一候補（既定）**: VP9 alpha WebM（`.webm` / `alpha_mode=1` / straight alpha）。契約 §3 の確定事項。
+  容量が HEVC alpha MOV の 1/4.8 で、**GPU デコードに依存しない**。書き出し経路のヘッドレス Chrome は
+  `--disable-gpu` で起動する（`packages/render-cut/src/rasterize.mjs`）ため、HEVC を既定にすると
+  経路ごと落ちる。
+- **fallback（第 2 形式）**: HEVC alpha MOV。Apple 系ツールへの受け渡しが要るときだけの互換形式で、
+  `analysis.json` に載せる既定ではない。本リーフの「Apple Vision → HEVC with alpha」「Robust Video
+  Matting → HEVC with alpha」は、この第 2 形式を自前で作るときの手順である。
+- 断片側は形式を判別しない。`data-akari-matte-src` が指すものを再生するだけにする。形式の選択は
+  供給側（`analysis.json`）の責務であり、断片に `<source type="...">` の分岐を書かない。
+
+### 5. poster フォールバック（プレビュー制約への保険）
+
+プレビューの webview は `default-src 'none'; media-src <stream origin>; img-src <stream origin> blob: data:`
+という CSP 下にある（`akari-preview-open-handler.ts`）。`data:` の**画像**は許されるが、`media` は
+払い出されたストリームオリジンに限られる。マットを asset stream へ載せる解決経路は現時点で未実装
+であり、断片を単体で開いた場合も含めて**プレビューでマット `<video>` が再生されない場面がある**。
+
+そこで **`poster` にデータ URI の静止マット 1 枚**を置くことを任意フォールバックとして規約化する。
+
+```html
+<video class="tbp-root__matte" muted playsinline preload="auto"
+       poster="data:image/png;base64,iVBORw0KGgo…"></video>
+```
+
+- 代表フレーム（そのオーバーレイ区間の中央あたり）をアルファ付き PNG で **1 枚だけ**入れる。マット
+  生成の既定解像度は 512x384（`balanced`・person-matte.md の実測表）であり、poster もその解像度で足りる。
+  data URI は断片 HTML に丸ごと載るため、桁が大きくなるなら PNG 側の解像度を落とす。
+- CSP で `media` が落ちても poster は描画されるため、**人物とテキストの前後関係**（この演出の要）は
+  プレビューで確認できる。
+- **poster は静止画である。動きはレンダで確認する。** poster が出ていることを「マットが動いている」
+  ことの確認と読み替えない。poster だけを最終成果物の代替にしない。
+
+### 6. 決定性
+
+- マット動画の時刻は素材（`analysis.source`）の source 秒と **1:1** で対応する（契約 §4）。
+  マット側にオフセットを持たせない。
+- **断片内で独自の時刻源を作らない**（ハードルール 2 / 4 の再確認）。`autoplay` / `loop` /
+  `setTimeout` / rAF の delta 積算でマットを進めない。`<video>` の時刻を進めるのはランタイムであり、
+  断片は宣言するだけにする。
+- 現状の実測: 書き出し経路は全 `<video>` に**コンポジション秒をそのまま**代入する
+  （`rasterize.mjs` の `__akariSeek`）。`cuts[]` を介した source 秒への射影は行わない。素材の途中区間を
+  使うカットではマットが合わない。プレビューは `<video>.currentTime` を触らない。したがって
+  **動く人物のマットは今も本番品質ではない**（冒頭「現在の制約を先に判定する」と同じ結論）。静止マット
+  （poster / 単一フレーム）は現時点でも決定的に成立する。
+
+## Apple Vision → HEVC with alpha
+
+以下 2 節は**第 2 形式（HEVC alpha MOV）を自前で作る**ときの手順である。既定の生成経路は
+`analysis.json` の `tracks.person_matte`（VP9 alpha WebM）であり、手順は
+[skills/analyze-footage/person-matte.md](../analyze-footage/person-matte.md) にある。
+
+1. source を presentation order で decode し、各 frame の PTS と orientation を保持する。
+2. 同じ `VNSequenceRequestHandler` へ frame を順番に渡し、`VNGeneratePersonSegmentationRequest` で person mask を得る。offline 品質では `.accurate` を候補にできるが、速度と輪郭品質を実素材で検証する。
+3. camera 固有の orientation を hardcode せず、入力 orientation を反映して mask を source extent へ合わせる。
+4. mask を alpha として RGB と合成し、alpha-bearing pixel buffer を作る。方式に迷う場合は Apple 推奨の premultiplied alpha を使う。
+5. `AVAssetWriterInput` または `VTCompressionSession` を `AVVideoCodecType.hevcWithAlpha` で構成し、元 PTS の順に append して `.mov` を出す。alpha quality は公式に 0.0〜1.0 の範囲だが、固定値は発明せず **要検証** とする。
+6. 出力 track の `.containsAlphaChannel`、duration、fps、frame count、orientation を確認し、checkerboard 上で髪、指、motion blur、半透明境界を実見する。
+7. 新シェル（Chromium ベースの Electron）の preview と、export に使う Chrome 系レンダラーの両方で当該 asset を実機再生する。codec 名だけで互換性を保証しない。（旧 Tauri 版は WKWebView 前提だったが、新シェルは Chromium 系に統一）
+
+公式:
+
+- [Apple Vision — VNGeneratePersonSegmentationRequest](https://developer.apple.com/documentation/vision/vngeneratepersonsegmentationrequest)
+- [Apple Vision — VNSequenceRequestHandler](https://developer.apple.com/documentation/vision/vnsequencerequesthandler)
+- [Apple — Applying Matte Effects to People in Images and Video](https://developer.apple.com/documentation/vision/applying-matte-effects-to-people-in-images-and-video)
+- [Apple — HEVC Video with Alpha](https://developer.apple.com/videos/play/wwdc2019/506/)
+- [Apple — AVVideoCodecType.hevcWithAlpha](https://developer.apple.com/documentation/avfoundation/avvideocodectype/hevcwithalpha)
+- [Apple — AVMediaCharacteristic.containsAlphaChannel](https://developer.apple.com/documentation/avfoundation/avmediacharacteristic/containsalphachannel)
+
+## Robust Video Matting → HEVC with alpha
+
+1. RVM の license を先に確認する。公式 repository は GPL-3.0 であるため、コードや model を MIT の本リポへ同梱・転写しない。外部の「手」として使う場合も version、license、取得元を provenance に残す。
+2. frame 順を保ち、RVM の recurrent state を次 frame へ渡して foreground (`fgr`) と alpha (`pha`) を得る。各 frame を独立並列処理しない。
+3. 公式 converter の `output_foreground` / `output_alpha` は別出力であり、HEVC alpha 直出力ではないと理解する。
+4. premultiplied を使う場合は `RGB = fgr * pha`、`A = pha` として alpha-bearing frame を作り、元 fps / PTS と照合する。
+5. Apple Vision 経路と同じ AVFoundation HEVC-alpha encoder へ渡し、同じ検証を行う。
+
+公式: [Robust Video Matting repository](https://github.com/PeterL1n/RobustVideoMatting)、[RVM inference guide](https://github.com/PeterL1n/RobustVideoMatting/blob/master/documentation/inference.md)
+
+## DOM の z 順
+
+単一ルートの中に同じ座標系で text と cutout video を置く。以下は最小骨格であり、`src` の与え方・
+既定で隠す指定・poster フォールバックまで含めた正の書き方は上の「マット参照規約」にある。
+
+```html
+<div class="tbp-root">
+  <style>
+    .tbp-root { position: absolute; inset: 0; isolation: isolate; }
+    .tbp-root__text { position: absolute; z-index: 1; }
+    .tbp-root__matte { position: absolute; inset: 0; z-index: 2; pointer-events: none; }
+  </style>
+  <div class="tbp-root__text">正確な日本語テキスト</div>
+  <video class="tbp-root__matte" muted playsinline preload="auto"></video>
+</div>
+```
+
+- text の z-index を cutout video より小さくする。
+- `<video>` の `object-fit` / `object-position` を base video と同じ crop 契約に合わせる。
+- `--text-x`、`--text-y`、`--font-size`、`--matte-fit`、`--matte-position` などを knob にする。
+- alpha video を autoplay / loop 任せにしない。将来は `data-akari-sync` 付き video の currentTime を overlay local timeline へ設定する runtime 契約が必要になる。
+- relative video URL の live preview 解決も現状未整備なので **要検証** とする。
+
+## よくある間違い
+
+- `data-akari-sync` が既に実装済みだと書く。
+- マット `<video>` の `src` を断片へ直書きする（プレビューでも書き出しでも解決できない）。
+- `analysis.json` 側のマットへ直リンクし、プロジェクトの自己完結を壊す。
+- マットをプロジェクトへ複製するときに ffmpeg で再エンコードし、アルファを無言で落とす。
+- `data-akari-matte-src` が無いときにマット層を出したまま黒や空の矩形を人物の上に残す。
+- poster が出ていることを「マットが動いている」ことの確認と読み替える。
+- alpha video を autoplay し、映像本体と偶然合うことを期待する。
+- text を人物 layer より前へ置き、通常のテロップに戻してしまう。
+- base と cutout で crop / orientation / fps / PTS が違う。
+- Vision sample の camera orientation を全動画へ hardcode する。
+- RVM の recurrent state を捨てて frame を独立処理する。
+- RVM の foreground / alpha 出力を HEVC-alpha 完成品と思い込む。
+- GPL-3.0 の RVM コードや model を本リポへコピーする。
+- 新シェルの preview（Chromium/Electron）で見えたため、export 用のヘッドレス Chrome 系レンダラーでも同じに動くと未検証で断言する。（旧 Tauri 版は Safari / WKWebView 前提だったが、新シェルは Chromium 系に統一）