akari-video 0.1.9 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "AKARI Video launcher CLI — start an AI-edited video project from any directory: scaffold, connection check, then hand over to Claude Code (or opencode). AKARI Video を opencode や Claude Code で、どのディレクトリからでも始めるための `akari` ランチャー CLI。接続確認（doctor）→ 未セットアップならプロジェクト雛形を作成 → AI エージェントを起動する。外部 npm 依存ゼロ（Node.js 組み込みモジュールのみ）。",
   "type": "module",
   "bin": {

package/src/capability-sources.mjs

@@ -2,7 +2,10 @@ import { execFileSync } from "node:child_process";
 import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 
-export function discoverCheckoutCapabilitySources(repoRoot, { trackedFiles = null } = {}) {
+export function discoverCheckoutCapabilitySources(repoRoot, {
+  trackedFiles = null,
+  includeBinTargets = true,
+} = {}) {
   const root = realpathSync(resolve(repoRoot));
   const tracked = trackedFiles ?? execFileSync("git", ["-C", root, "ls-files", "-z"], {
     maxBuffer: 64 * 1024 * 1024,
@@ -25,7 +28,7 @@ export function discoverCheckoutCapabilitySources(repoRoot, { trackedFiles = nul
         throw new Error(`${manifestPath} package.json#bin target is not tracked: ${canonical}`);
       }
       assertRegularContainedFile(root, canonical, `${manifestPath} package.json#bin`);
-      selected.add(canonical);
+      if (includeBinTargets) selected.add(canonical);
     }
   }
   const paths = [...selected].sort(compare);

package/src/status-command.mjs

@@ -30,10 +30,17 @@ export async function runStatusCommand(argv, options = {}) {
   const status = parsed.full
     ? await resolveFullProjectStatus(parsed.projectRoot)
     : resolveProjectStatus(parsed.projectRoot, { mode: "fast" });
-  log(parsed.json ? serializeStatus(status) : `${formatStatusSummary(status)}\n`);
+  log(parsed.json ? serializeStatus(status) : `${formatStatusOutput(status)}\n`);
   return { exitCode: status.state_health === "inconclusive" ? 1 : 0, status };
 }
 
+export function formatStatusOutput(status) {
+  const summary = formatStatusSummary(status);
+  if (status.state_health !== "inconclusive" || status.problems.length === 0) return summary;
+  const problems = status.problems.map((problem) => `  - ${problem}`).join("\n");
+  return `${summary}\nCould not determine:\n${problems}\nNext: run \`akari status --json\` for the full machine-readable report, or resolve the items above and re-run \`akari status\`.`;
+}
+
 export function parseStatusArguments(argv, cwd = process.cwd()) {
   let projectRoot = cwd;
   let pathSeen = false;

package/vendor/.akari-capability-sources.json

@@ -36,36 +36,27 @@
     "docs/contract-2026-08-12-chat-approval-v0.md",
     "docs/contract-2026-08-12-color-range-normalization-v0.md",
     "docs/contract-2026-08-12-region-filter-layer-v0.md",
-    "packages/akari-launcher/bin/akari.mjs",
+    "docs/contract-2026-08-12-still-image-cut-source-v0.md",
+    "docs/contract-2026-08-13-avatar-drive-v0.md",
+    "docs/contract-2026-08-14-avatar-vrm-v0.md",
     "packages/akari-launcher/package.json",
     "packages/akari-launcher/README.md",
     "packages/akari-tools/package.json",
     "packages/analysis-report/package.json",
     "packages/analysis-report/README.md",
-    "packages/analysis-report/render-analysis-report.mjs",
-    "packages/asset-resolver/bin/akari-assets.mjs",
     "packages/asset-resolver/package.json",
     "packages/asset-resolver/README.md",
-    "packages/audio-library-setup/bin/gallery-helper.mjs",
-    "packages/audio-library-setup/bin/generate-candidates-html.mjs",
-    "packages/audio-library-setup/bin/register-drop-folder.mjs",
     "packages/audio-library-setup/package.json",
     "packages/audio-library-setup/README.md",
-    "packages/bake-layer/bin/bake-layer.mjs",
     "packages/bake-layer/package.json",
     "packages/bake-layer/README.md",
     "packages/chat-bridge/package.json",
-    "packages/chat-bridge/src/telegram.mjs",
     "packages/creator-root/package.json",
     "packages/decision-cards/package.json",
     "packages/decision-cards/README.md",
-    "packages/decision-cards/report-helper.mjs",
-    "packages/edit-lint/bin/edit-lint.mjs",
     "packages/edit-lint/package.json",
     "packages/edit-store/package.json",
-    "packages/export-nle/bin/export-nle.mjs",
     "packages/export-nle/package.json",
-    "packages/intake-form/intake-form-helper.mjs",
     "packages/intake-form/package.json",
     "packages/intake-form/README.md",
     "packages/media-bin/package.json",
@@ -75,22 +66,15 @@
     "packages/preview-engine/package.json",
     "packages/preview-engine/README.md",
     "packages/preview-server/package.json",
-    "packages/preview-server/src/server.mjs",
     "packages/project-scaffold/package.json",
-    "packages/render-cut/bin/akari-apply-textstyle.mjs",
-    "packages/render-cut/bin/render-cut.mjs",
     "packages/render-cut/package.json",
-    "packages/schemas/bin/validate-asset.mjs",
-    "packages/schemas/bin/validate-intake.mjs",
-    "packages/schemas/bin/validate-plan.mjs",
-    "packages/schemas/bin/validate-review.mjs",
     "packages/schemas/package.json",
-    "packages/template-render/bin/akari-template-render.mjs",
     "packages/template-render/package.json",
     "packages/template-render/README.ja.md",
     "packages/template-render/README.md",
     "skills/address-review/SKILL.md",
     "skills/analyze-footage/analysis-json.md",
+    "skills/analyze-footage/bin/face-expression/vendor/tasks-vision-0.10.17/README-AKARI.md",
     "skills/analyze-footage/events-and-hooks.md",
     "skills/analyze-footage/keyframes-and-review.md",
     "skills/analyze-footage/media-and-transcript.md",

package/vendor/docs/contract-2026-07-22-render-basics.md

@@ -17,7 +17,7 @@
 |---|---|---|---|---|
 | 1 | 定速変更（クリップ単位の倍速/スロー） | `cuts[].speed`（number・既定 1.0・v0 は定速のみ、ランプは将来） | `setpts` + `atempo`（>2x/<0.5x の段組み） | 出力尺が理論値と一致（ffprobe）・音程/同期の実聴確認 1 点 |
 | 2 | クロマキー背景置換 | `source.chroma_key`: {color, similarity, blend, background(色 or 画像/動画パス)} | `chromakey`/`colorkey` + 背景入力の `overlay` | 緑背景フィクスチャで背景が置換された出力のピクセルサンプル検証 |
-| 3 | 基本トランジション | `cuts[].transition_out`: {type: dissolve/fade-black/fade-white, duration} | `xfade`（transition 指定があるカット境界のみ xfade 経路） | 境界フレームの中間ブレンド実在をフレーム抽出で確認・指定なし境界はハードカット維持 |
+| 3 | 基本トランジション | `cuts[].transition_out`: {type: dissolve/fade-black/fade-white/**reveal-down/reveal-up**, duration} | `xfade`（transition 指定があるカット境界のみ xfade 経路）。reveal 系は ffmpeg の `revealdown` / `revealup` | 境界フレームの中間ブレンド実在をフレーム抽出で確認・指定なし境界はハードカット維持。reveal 系は色が混ざらないため、遷移中間フレームの**上半分と下半分を別々に測って**前後カットが同居することを確認する |
 | 4 | 色調フィルター（LUT） | `output.look`: {lut(プリセット参照 or パス), intensity} | `lut3d`（intensity は `blend` 併用） | LUT 有無 2 出力のフレームピクセル差分・プリセット表 `presets/luts/`（初期 2〜3 本。2026-07-29 に `catalog/luts/` から移設） |
 | 5 | 音声マスター処理 | `audio.master`: {denoise(off/std/strong), loudnorm(target LUFS・既定 -14)} | `afftdn` / `loudnorm`（2 パスでなく 1 パス許容 v0） | 出力のラウドネス実測（ffmpeg ebur128）が目標 ±1LU |
 | 6 | 画角操作（静的クロップ / ズームキーフレーム / 段階縮小） | `cuts[].framing`: `{crop?: {x,y,w,h}（0..1 の出力相対・静的）, keyframes?: [{t,scale,cx?,cy?}]（t=カット内秒・線形補間。2 点でズーム、3 点以上で段階縮小・cx/cy 省略時 0.5）}` | 出力キャンバスへフィット済みの frame を `crop` で窓抜きし `scale` で再拡大（punch-in）。静的 `crop` は `w/h/x/y` とも定数。ズームは `crop` 自身の `w/h` が実機検証で init 時一度しか評価されない制約があるため、`scale` 側を `eval=frame` で `scale(t)` 倍に広げ、`crop` は固定 `w=width:h=height` のまま `x/y` だけを `t` の関数で追わせる方式（詳細 §4-1） | 静的 crop は出力フレームの画素でクロップ位置が宣言どおりであることを実測・ズームは開始/中間/終端フレームで可視要素の実測サイズから逆算したスケールが線形補間の理論値と一致（±5%）・3 点キーフレームは 2 段階の縮小がフレーム抽出で確認できる |
@@ -31,6 +31,32 @@
    edit-lint / fixtures / test を同時追随
 2. プレビュー（preview-engine）は v0 では**近似不要・無視でよい**（出力最優先。
    「プレビューは近似・書き出しが正」の哲学を全項目に適用。プレビュー追随は別契約）
+3. **`output.look`（#4 の LUT）の適用範囲は `cuts[]` の本編映像だけ**である。
+   `layers[]`（PinP / 人物マット / B-roll）と `overlays[]` には**掛からない**。
+   同じ絵の一部として重ねる素材の色を本編に合わせたいときは、`layers[].filter`
+   （`{type:"lut", id, intensity}`。正本 = `contract-2026-08-12-region-filter-layer-v0.md` §4）
+   へ**同じ `id` / `intensity` を明示的に宣言する**。
+   実害例（2026-08-14・リール制作）: 本編にだけ `cinematic` が乗り、重ねた人物切り抜きが
+   素の色のまま合成されて、窓の継ぎ目で肌色が食い違った。「プロジェクト全体の色」だと
+   誤解しやすいため、ここに明記する。
+
+### 2-4. reveal 系トランジション（`reveal-down` / `reveal-up`。2026-08-14 追加）
+
+**前カットが丸ごとその方向へ動いて画面外へ抜け、空いた側から次カットが現れる**
+（前カットは動きながら画面端でクロップされる）。ディゾルブのように混ざらないので、
+**同じ構図が続くトークシーンでも「場面が入れ替わった」ことが読める**のが採用理由
+（オーナー指定 2026-08-14「テンプレの基本トランジションとして必要」）。
+
+- `reveal-down` = 前カットが下へ降りる（画面上部から次カットが出てくる）
+- `reveal-up` = 前カットが上へ抜ける（画面下部から次カットが出てくる）
+- 実測（64x64・10fps・duration 1s・遷移中間 t=2.5s）: `reveal-down` で上半分 RGB(0,0,253)＝次カット /
+  下半分 RGB(252,0,0)＝前カット。`reveal-up` はこの上下が入れ替わる
+- **他の xfade と同じく、遷移の重なり分だけタイムラインが縮む**（境界 1 つにつき `duration` 秒）。
+  `layers[]` / `overlays[]` / `audio.sfx[]` を**タイムライン秒で手置き**しているプロジェクトでは、
+  トランジションを足すと後続の配置が全部ずれる。字幕は (`src`, source 秒) で書くのでエンジンが
+  追随するが、手置きの要素は自分で引き直す必要がある。尺を変えたくない場合は、
+  トランジションではなくオーバーレイで表現する（前カット最終フレームを焼いて動かす）という
+  逃げ道もあるが、静止画になるうえプロジェクト固有の焼き込みが要るので既定にはしない
 
 ## 3. 残裁定
 

package/vendor/docs/contract-2026-07-23-analysis-person-matte.md

@@ -121,6 +121,13 @@ HEVC alpha MOV は「Apple 系ツールへの受け渡しが要るとき」の
   がそのまま適用される。`beats` / `emphasis_words` と同じ扱いである
 - マットに `--ss` 相当のオフセットを持たせない。素材の途中区間だけを切り出したマットを
   `person_matte` に載せない（載せると時刻 0 の一致が壊れる）
+  - 一方で、**カット単位に切り出したマットを `layers[].src` へ直接置く**運用（`analysis.json` を
+    経由しない、プロジェクト固有の `assets/matte/*.mov` など）は本契約の管轄外である。
+    その場合は本節の「時刻 0 一致」が成り立たないので、**切り出しの由来（元素材 / in / out /
+    speed / fps）を素材の隣に必ず残す**こと。由来が無いと消費側は素材の頭が何の時刻かを
+    推測するしかなく、十数フレーム単位でずれたまま気づけない（2026-08-14 に実害）。
+    運用上の注意は `docs/contract-2026-08-02-preview-parity.md` §2.4 と
+    `skills/edit-plan/execution.md`「レイヤー素材の時間基準」を参照
 - 消費側は表示・書き出しのたびに `cuts[]` から timeline 秒へ射影する。射影結果を永続化しない。
   同一 source 区間が複数回現れれば、1 本のマットが複数の timeline 位置へ射影される
 - マットの尺が素材の尺より短い場合、超えた範囲は**マット無し**として扱う（エラーではない）。

package/vendor/docs/contract-2026-08-02-preview-parity.md

@@ -57,6 +57,23 @@
 ### 2.4 レイヤー（B-roll）
 - `t` 〜 `t + duration` の窓外では非表示。**初期状態も非表示**（窓に入るまで描画しない）
 - 表示中は `currentTime` を出力時刻に同期する
+- **素材内オフセット（in トリム）は無い。素材の先頭が常に `t` に対応する**。`duration` は
+  素材の先頭から何秒使うかであって、素材のどこを使うかは選べない（`cuts[].in/out` に相当する
+  ものが `layers[]` には存在しない）。素材の途中区間を重ねたいときは**素材そのものを切り出す**
+  必要がある。
+  - 切り出した素材は「何を・どこから・どの速度で切り出したか」が失われるため、
+    **由来（元素材 / in / out / speed / fps）を素材の隣に必ず残す**こと。残っていないと、
+    次に触る人（人間・AI とも）が「素材の頭が何の時刻なのか」を推測することになり、
+    十数フレーム単位でズレたまま気づけない。
+  - 実害例（2026-08-14・リール制作）: カット単位に切り出した人物マットを「先行表示分の
+    プリロールを持っているはず」と**推測**して頭をトリムしたところ、実際は切り出し済みで
+    プリロールが無く、11〜23 フレームずれた。さらに `duration` を詰めた結果、区間の末尾で
+    マットが尽きて「人物が消えて背景だけ」になった。
+  - 素材とカットの時間対応を後から実測する場合、**フレーム差分の絶対値（`blend=difference`）は
+    使わない**。色調整（`output.look` は本編にしか掛からない = §2.4 冒頭の別項）で素材と本編の
+    色が違うと、その色差が支配して指標が平坦になり誤った結論を導く。**フレーム間差分エネルギーの
+    時系列（`tblend=all_mode=difference` → `signalstats` の YAVG）を正規化して相互相関**させると、
+    色に不変で lag を特定できる。
 
 #### 2.4.1 空間クロップ（`layers[].crop`。2026-08-06 導入）
 - `crop = { x, y, w, h }`（**0..1 正規化・ソースフレーム相対・静的**）。省略時は既定
@@ -539,6 +556,7 @@ ffmpeg の `perspective` フィルタの制約（式に時刻変数を持たな
 | `layers[].perspective`（2026-08-06 実装） | ✅（§2.4.4。実ブラウザ実測済み） | ✅（§2.4.4。tsc -b + ユニット + Web 同一計算式で担保） |
 | `cuts[].fx`（2026-08-07 実装・近似あり） | 🟡（§2.4.5。5 種対応、3 種は近似バッジ付き） | ❌（未実装） |
 | `layers[].keyframes`（2026-08-09 実装） | ✅（§2.4.7。transform/crop は連続補間。perspective は blend:"normal" のみ・書き出しの段階保持とサンプル点で一致） | ✅（§2.4.7。同左） |
+| `cuts[].static-image-source`（2026-08-12 実装。正本: `contract-2026-08-12-still-image-cut-source-v0.md`） | 🟡（`<img>`/`<video>` 出し分け + preview-engine ClipSession/Timeline の image 対応を実装。framing/freeze/transform は流用。実ブラウザでの対話的スクラブ・複数区間切替の実機検証は未実施） | ❌（スコープ外・未対応） |
 
 - `cuts[].framing`（静的クロップ / ズームキーフレーム）・`cuts[].freeze`（フリーズ）は
   `contract-2026-07-22-render-basics.md` #6/#7 としてレンダ（render-cut）に加え、

package/vendor/docs/contract-2026-08-11-analysis-vision-tracks-v0.md

@@ -1,10 +1,10 @@
 ---
 lifecycle: draft
 created: 2026-08-11
-updated: 2026-08-11
+updated: 2026-08-14
 ---
 
-# 分析トラック契約 v0 — Vision ランドマーク・トラック（face-landmarks / hand-pose）と keyframes 消費
+# 分析トラック契約 v0 — Vision ランドマーク・トラック（face-landmarks / hand-pose / body-pose-3d / face-expression）と keyframes 消費
 
 - 日付: 2026-08-11
 - 状態: **ドラフト**（v0 実装と同時に確定させる。実装で判明した齟齬は追記で解消）
@@ -13,8 +13,9 @@ updated: 2026-08-11
   - `contract-2026-07-23-analysis-person-matte.md`（Swift サイドカーの流儀・analysis.json の tracks 契約・検証責務の分担）
   - `contract-2026-07-25-project-structure-v0.md`（分析サイドカーの置き場 = `.akari/sidecars/`）
   - `contract-2026-08-02-preview-parity.md`（render/Web/shell 3 面パリティの原則）
-- スコープ: 動画から抽出する**ランドマーク・トラック**（顔・手）のデータ契約、生成サイドカーの
-  入出力、消費（`layers[].keyframes` への変換）の責務分担。**新しいレンダー機構は作らない**
+- スコープ: 動画から抽出する**ランドマーク・トラック**（顔・手・3D ボディポーズ）のデータ契約、生成サイドカーの
+  入出力、消費（`layers[].keyframes` への変換）の責務分担、および MediaPipe 由来の頭部姿勢・
+  表情トラック。**新しいレンダー機構は作らない**
 
 ## 0. 設計原則
 
@@ -34,7 +35,7 @@ updated: 2026-08-11
 
 ## 1. analysis.json への追加（additive）
 
-`tracks` に **optional キー** 2 つを追加する。`tracks.required`（speakers / faces /
+`tracks` に **optional キー** 3 つを追加する。`tracks.required`（speakers / faces /
 person_matte）には**入れない**（person_matte が必須なのは既存消費者の事情であり、新トラックは
 真に任意として追加する）。
 
@@ -48,18 +49,40 @@ person_matte）には**入れない**（person_matte が必須なのは既存消
     "tool": "vision-tracks.mjs v0",
     "generated_at": "2026-08-11T12:00:00Z"
   },
-  "hand_pose": { /* 同形 */ }
+  "hand_pose": { /* 同形 */ },
+  "body_pose_3d": {             // 任意。macOS 14+ の Vision 3D ボディポーズ
+    "path": "vision/body-pose-3d.json",
+    "sample_fps": 24,
+    "provider": "apple-vision",
+    "tool": "vision-tracks.mjs v0",
+    "generated_at": "2026-08-13T12:00:00Z"
+  }
+}
+```
+
+2026-08-14 additive: 同じ optional pointer 形で `face_expression` を追加する。既存 3 キーと同様に
+`tracks.required` には入れず、未生成はキー無しで表す。
+
+```jsonc
+"face_expression": {
+  "path": "vision/face-expression.json",
+  "sample_fps": 24,
+  "provider": "mediapipe-face-landmarker",
+  "tool": "face-expression.mjs v0",
+  "generated_at": "2026-08-14T12:00:00Z",
+  "features": ["head-pose-ypr-radians", "mediapipe-blendshapes-52"]
 }
 ```
 
 ## 2. トラックファイル形式（vision-tracks v0）
 
-`path` が指す JSON ファイル。1 ファイル 1 種類（face-landmarks と hand-pose は別ファイル）。
+`path` が指す JSON ファイル。1 ファイル 1 種類（face-landmarks / hand-pose /
+body-pose-3d / face-expression は別ファイル）。
 
 ```jsonc
 {
   "version": 0,
-  "kind": "face-landmarks",      // "face-landmarks" | "hand-pose"
+  "kind": "face-landmarks",      // "face-landmarks" | "hand-pose" | "body-pose-3d"
   "source": { "path": "../..(元動画への相対)", "duration": 12.5 },
   "sample_fps": 24,
   "provider": { "name": "apple-vision", "os": "macOS 15.5" },
@@ -70,8 +93,11 @@ person_matte）には**入れない**（person_matte が必須なのは既存消
 }
 ```
 
-- **座標系（最重要規約）**: すべて **0〜1 正規化・左上原点**（動画ピクセル系と同じ向き）。
+- **画像座標系（最重要規約）**: face-landmarks / hand-pose と body-pose-3d の
+  `projection` はすべて **0〜1 正規化・左上原点**（動画ピクセル系と同じ向き）。
   Vision framework は左下原点で返すため、**y 反転はサイドカーの責務**。消費側は変換しない
+- body-pose-3d の `position` だけは画像座標ではない。Vision が返すモデル座標
+  （root/hip 相対メートル）を変換せず保存する（§2.4）
 - `samples[].t` は元動画の秒（`in`/`out` と同じ時間軸）。サンプリングは `sample_fps` の等間隔
 - 生値主義: 平滑化・補間済みの値を入れない。信頼度（`conf`）を必ず併記する
 
@@ -126,6 +152,86 @@ person_matte）には**入れない**（person_matte が必須なのは既存消
   （§2.1 の必須 6 キーが揃わない detection を出力に混ぜない）。実測（1 名がほぼ映り続ける
   26.3 秒素材）ではこの除外は 0 件だった。
 
+### 2.4 body-pose-3d の detection（additive・2026-08-13）
+
+`VNDetectHumanBodyPose3DRequest` revision 1 が返す 17 関節を保存する。API は macOS 14+
+限定である。トラックは分析の生値であり、平滑化・間引き・低信頼度除外を行わない。
+
+```jsonc
+{
+  "conf": 0.86,
+  "joints": {
+    "root": {
+      "position": [0.0, 0.0, 0.0],       // root/hip 相対メートル
+      "projection": [0.51, 0.63],        // 0〜1 正規化・左上原点
+      "conf": 0.86
+    },
+    "right_hip": { /* 同形 */ },
+    "right_knee": { /* 同形 */ },
+    "right_ankle": { /* 同形 */ },
+    "left_hip": { /* 同形 */ },
+    "left_knee": { /* 同形 */ },
+    "left_ankle": { /* 同形 */ },
+    "spine": { /* 同形 */ },
+    "center_shoulder": { /* 同形 */ },
+    "center_head": { /* 同形 */ },
+    "top_head": { /* 同形 */ },
+    "left_shoulder": { /* 同形 */ },
+    "left_elbow": { /* 同形 */ },
+    "left_wrist": { /* 同形 */ },
+    "right_shoulder": { /* 同形 */ },
+    "right_elbow": { /* 同形 */ },
+    "right_wrist": { /* 同形 */ }
+  }
+}
+```
+
+- `position`: `VNHumanBodyRecognizedPoint3D.position` の平行移動成分 `[x,y,z]`。
+  Vision のモデル座標で root/hip 相対、単位はメートル。カメラ相対座標へ変換しない
+- `projection`: `VNHumanBodyPose3DObservation.pointInImage` が返す画像投影を y 反転し、
+  `[0,1]` へクランプした `[x,y]`
+- `conf`: Vision 3D API は関節別 confidence を公開しないため、apple-vision provider の v0 は
+  `VNHumanBodyPose3DObservation.confidence` を各関節へ複製する。これは関節別推定値ではなく、
+  観測全体 confidence の由来明示である。消費者の `min-confidence` はこの値を使う
+- 17 関節のいずれかを Vision から取得できない観測は detection ごと省略する。存在しない
+  関節を補間・捏造せず、`detections: []` のフレームは時刻 `t` とともに残す
+- pose-skeleton の v0 は各フレーム先頭の 1 人（`bodyIndex=0` 固定）のみを消費し、複数人には非対応
+
+### 2.5 face-expression の detection（additive・2026-08-14）
+
+MediaPipe Face Landmarker が返す `facialTransformationMatrixes` と 52 blendshape category を、
+平滑化・補間せず保存する。1 ファイル 1 kind の `kind` は `face-expression`、analysis pointer は
+`tracks.face_expression`、既定ファイル名は `vision/face-expression.json` とする。顔が検出されない
+frame も `{ "t": ..., "detections": [] }` として残す。
+
+```jsonc
+{
+  "head": {
+    "yaw": 0.12,
+    "pitch": -0.04,
+    "roll": 0.02
+  },
+  "blendshapes": {
+    "_neutral": 0.07,
+    "eyeBlinkLeft": 0.01,
+    "mouthSmileLeft": 0.64
+    // MediaPipe 固定 category 全 52 キー。各値は 0..1 の生 score
+  },
+  "conf": 0.64
+}
+```
+
+- `head` は 4x4 row-major 同次変換の上左 3x3 を行正規化し、
+  `R = Rz(roll) * Ry(yaw) * Rx(pitch)` で分解した**ラジアン**。右手系の解釈は +X=画像右、
+  +Y=画像下、+Z=canonical face 前方で、yaw 正=画面右向き、pitch 正=上向き、
+  roll 正=時計回り。gimbal lock は `roll=0` に固定する
+- `blendshapes` は `_neutral` を含む MediaPipe の固定 52 category。キーは表現の生 score で、
+  並びだけ byte 安定のため名前順へ正規化する。値の平滑化・クランプ・感情ラベル化はしない
+- MediaPipe Web API は内部の face-presence score を結果へ公開しない。`conf` は捏造した定数ではなく、
+  同じ detection に返った 52 生 score の最大値を signal confidence として決定論的に記録する。
+  face detection confidence そのものではないため、消費者は検出有無と blendshape 個別値を主に使う
+- v0 は `numFaces=1`。複数人追跡・人物同一性の連結はしない
+
 ## 3. サイドカー（生成側）
 
 person-matte と同じ分離: **Swift ヘルパーはフレーム変換だけ、コンテナ・時刻・組み立ては
@@ -135,25 +241,73 @@ person-matte と同じ分離: **Swift ヘルパーはフレーム変換だけ、
   - `vision-tracks-helper.swift` — stdin から raw BGRA フレーム列、stdout へ **JSON Lines
     （1 フレーム 1 行の検出結果）**。`swiftc -O` オンデマンドビルド・バイナリは `.gitignore`
   - `vision-tracks.mjs` — `ffmpeg`（デコード・fps/幅統一）→ helper → トラックファイル組み立て →
-    `analysis.json` の tracks へ追記（原子的置換）。`--kinds face,hand` / `--fps` / `--check`
-    （macOS / swiftc / ffmpeg の可用性確認）
+    `analysis.json` の tracks へ追記（原子的置換）。`--kinds face,hand,body-pose-3d` /
+    `--fps` / `--check`（macOS 14+ / swiftc / ffmpeg の可用性確認。macOS 14 未満は
+    capability 不足として理由付きで拒否）
 - 手順書: `skills/analyze-footage/vision-tracks.md`（person-matte.md と同格の任意工程）。
   `SKILL.md` の実行順・ハードルールに配線する
 - 起動主体はエージェント（スキル手順に従い bash で直接叩く）。CLI サブコマンドにはしない
   （判断を伴う工程はスキル、の境界裁定に従う）
 
+### 3.1 face-expression の headless Chromium 生成器（additive・2026-08-14）
+
+`skills/analyze-footage/bin/face-expression/face-expression.mjs` は face-expression 専用の独立生成器。
+既存 Swift helper は変更せず、ffmpeg で 24 fps（`--fps` 変更可）・幅 1280 以下の PNG 列へ
+デコードし、Chrome for Testing + `puppeteer-core` のページ内で CPU/WASM 版 Face Landmarker を
+順に実行する。Chrome の探索順・起動引数・ページ処理後の結果吸い上げは avatar-vrm の既存
+headless 経路を踏襲する。
+
+JS 版を選んだ理由は、`@mediapipe/tasks-vision` がブラウザ/WASM 専用である一方、製品には既に
+headless Chromium 経路があり、Python wheel や Swift helper という新しい実行系を増やさずに済むため。
+固定 Chrome・固定 WASM・CPU delegate・固定時刻入力により、同一環境では同じ行列分解と score 列を
+得られる。Python 版は arm64 wheel という別インストール面とバージョン解決を増やすため v0 では採らない。
+
+モデルはリポジトリへ置かず、初回だけ次を取得する。`AKARI_HOME` があればそれを優先し、既定は
+`~/.akari/models/mediapipe/face-landmarker/float16-1/face_landmarker.task`。既存ファイルも毎回
+SHA-256 検査し、不一致時は再取得で隠さず即エラーにする。新規取得は `.tmp-<pid>` へ書き、検証後に
+rename する。
+
+- URL: `https://storage.googleapis.com/mediapipe-models/face_landmarker/face_landmarker/float16/1/face_landmarker.task`
+- SHA-256: `64184e229b263107bc2b804c6625db1341ff2bb731874b0bcc2fe6544e0bc9ff`
+
+ブラウザ runtime はネットワーク変動を避けるため `@mediapipe/tasks-vision@0.10.17` の必要ファイルを
+無変換で vendor した。ライセンスは Apache-2.0。
+
+| artifact | SHA-256 |
+|---|---|
+| npm tarball | `d3dd0759295f1adcf5455f22aa652c58b8c1d537c0d14c8db7df78646011d523` |
+| `vision_bundle.mjs` | `1ada13431ea2a8ed7ea449e6c3595122d43fea2a8a4788056ed7da271469b402` |
+| `vision_wasm_internal.js` | `33a4125f825b343d2d9773951a73692f40bee368c9b591af8ff652fd501af90b` |
+| `vision_wasm_internal.wasm` | `c88cf472dd5cab0a3954b071e5f442102ded3701dcccc987a7a02ee8f54aae85` |
+| `vision_wasm_nosimd_internal.js` | `4e8d07dcf8cbb55b343cd76b7fc30d4303220f049d5529d6412f6f93296726a8` |
+| `vision_wasm_nosimd_internal.wasm` | `f840f69d7229f89dedaed39c7ac7a52f0964a7cec02d6cb1ac9eff891db86dc2` |
+| `LICENSE.txt` | `b070d77bfb2c52a1dd6996de0ce5f64c49a0ca55c889b163a963ddf5cb001ee2` |
+
+> 注: `LICENSE.txt` のみ npm tarball には含まれず（tarball 展開で実測確認済み）、Apache-2.0 の定型全文を手動で添えたもの（出所は `vendor/.../README-AKARI.md` 参照）。他の行は全て tarball 由来の実ファイル。
+
+tarball は `tar -xzf` 後、上記 bundle/WASM だけをコピーし、esbuild 等の再ビルドは行っていない。
+tarball 自体の npm integrity は
+`sha512-CZWV/q6TTe8ta61cZXjfnnHsfWIdFhms03M9T7Cnd5y2mdpylJM0rF1qRq+wsQVRMLz1OYPVEBU9ph2Bx8cxrg==`。
+
 ## 4. 消費（変換器）
 
-トラック → `edit.json` への反映は**決定論の変換器**が行う。v0 の消費者は 2 つ（別契約で
+トラック → `edit.json` への反映は**決定論の変換器**が行う。v0 の消費者は 3 つ（別契約で
 実装しても本契約の §2 形式だけを入力にする）:
 
 | 消費者 | 入力 | 出力 |
 |---|---|---|
 | eye-bar（目線黒帯） | face_landmarks（両瞳） | 黒帯レイヤー + `layers[].keyframes` の transform（x/y/rotate/scale） |
 | finger-frame（指フレーム） | hand_pose（両手の thumb_tip / index_tip = 4 点） | 対象レイヤーの `layers[].keyframes` の perspective（4 隅 corner-pin）+ 発動区間 |
+| pose-skeleton | body_pose_3d（17 関節の 2D `projection`） | アルファ付きスティックフィギュアを事前ベイクした `kind: "baked"` layer |
+
+`face_expression` のアバター駆動への結線は次の消費側契約に委ねる。本契約では生成 SSOT までとし、
+既存の「あいうえお」口パクや avatar-vrm / avatar-drive を変更しない。
 
 - 平滑化（移動平均・One Euro 等）・キーフレーム間引き・欠測補間は**変換器の責務**。
   パラメータは変換器の引数で決定論に
+- pose-skeleton は欠測と cut 境界で平滑化状態をリセットし、低 confidence 関節を含む骨を
+  非表示にする。欠測区間を hold せず、別 baked clip / layer へ分割する
+- pose-skeleton の v0 は `bodyIndex=0` 固定で各フレーム先頭の 1 人だけを対象とし、複数人には非対応
 - perspective keyframes の ffmpeg 側は既存の時間窓分割フォールバック
   （`expandLayerForPerspectiveKeyframes`）に乗る。新しいレンダー経路は作らない
 - `cuts[].fx` は**使わない**（全画面ポスト効果の器。空間追跡系はレイヤー機構が正）
@@ -163,10 +317,13 @@ person-matte と同じ分離: **Swift ヘルパーはフレーム変換だけ、
 - `packages/schemas/bin/` に新しいバリデータ CLI は**作らない**（person-matte 契約 §7 の分担を
   継続）。トラックファイルの JSON Schema は `skills/analyze-footage/references/
   vision-tracks.schema.json` に置き、スキル手順の jsonschema 検証が担う
-- `analysis.schema.json` への tracks 2 キー追加は additive のみ
+- `analysis.schema.json` への tracks 4 キー追加は additive のみ
 - **`packages/analysis-report/render-analysis-report.mjs` の軽量チェックを同時に更新する**
   （person_matte が残した「消費者の追随債務」を新トラックで繰り返さない）
 - verify は L0（該当 package / skill の `node --test`）。GUI を触らないため L1/L2 は対象外
+- face-expression は schema wiring、52 キー固定、同一行列の Euler 分解一致、モデル初回配置と
+  cached/downloaded 両方の SHA-256 不一致拒否を unit test する。実素材の検出率・CPU 時間・
+  実時間比は fieldtest 12 秒窓で別途記録し、値を捏造して本契約へ先書きしない
 
 ## 6. やらないこと（v0）
 

package/vendor/docs/contract-2026-08-12-region-filter-layer-v0.md

@@ -88,7 +88,7 @@ LUT の `intensity` 省略時は `1` として描画する。
 
 ## 7. 実装対応
 
-- `packages/render-cut/src/layers.mjs`: ベース映像の split、ルック適用、白 quad mask、`maskedmerge` による region 内合成を行う。filter layer は追加の `-i` を作らない。
+- `packages/render-cut/src/filter-mask.mjs` / `layers.mjs`: corner keyframes からフレーム単位の縮小 gray8 quad mask を生成し、ベース映像の split、ルック適用、拡大したマスクとの `maskedmerge` による region 内合成を行う。filter layer ごとにマスク動画用の `-i` を 1 本追加する。
 - `packages/akari-tools/bin/finger-frame.mjs`: `--kind filter --filter invert|lut:<id>|saturation:<value>` から、既存と同じ gesture window と corner keyframes を持つ layer を生成する。
 
 ## 8. 検証