akari-video 0.1.9 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "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-08-02-preview-parity.md

@@ -539,6 +539,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. 検証

package/vendor/docs/contract-2026-08-12-still-image-cut-source-v0.md

@@ -0,0 +1,163 @@
+---
+lifecycle: draft
+created: 2026-08-12
+updated: 2026-08-12
+---
+
+# 静止画 cut ソース契約 v0
+
+- 日付: 2026-08-12
+- 状態: **ドラフト**（v0 実装と同時に確定させる。実装で判明した齟齬は追記で解消）
+- 前提:
+  - `contract-2026-07-22-render-basics.md`（cuts[] の speed/freeze/framing/transition_out の残裁定。
+    本契約はそのうち speed/freeze の適用範囲を静止画ソースへ拡張する）
+  - `contract-2026-08-10-image-layer-parity.md` 相当の司令塔裁定（`layers[].src` の拡張子判定。
+    本契約はそれを `cuts[]`（メイン時間軸）へ輸入する）
+  - `contract-2026-08-02-preview-parity.md`（render/Web UI/shell 3 面パリティの原則。本契約が
+    更新する適合状況表は同ファイル §3）
+  - `contract-2026-07-17-data-contract-versioning.md`（version 整数・追加のみ・寛容リーダーの三原則）
+- スコープ: `edit.json` の `cuts[]` がメイン時間軸で静止画ソース（png/jpg/jpeg/webp/bmp/gif）を
+  直接読めるようにする。**新しいスキーマフィールドは作らない**（判定は拡張子のみ）
+
+## 0. 背景
+
+これまで `cuts[]` は「時間軸を持つ動画」だけを前提にしていた。画像をタイムラインに置きたい場合、
+利用者は画像群を先に 1 本の動画へ連結してから `edit.json` に載せる遠回りを強いられていた
+（実機報告 2026-08-12）。旧参照実装 `akari-video-on-os` には 2026-05-09 から静止画クリップの経路
+（`isStatic` フラグ + `-loop 1 -t 尺` + `anullsrc` 無音合成）が実運用されており、新実装への
+「輸入漏れ」だった。`layers[]`（PinP・B-roll レイヤー）は 2026-08-10 の image-layer-parity で
+既に拡張子判定の静止画対応が入っている。本契約はその判定方式をメイン時間軸の `cuts[]` へ
+輸入する。
+
+## 1. 判定規則（司令塔裁定）
+
+- **判定は拡張子のみ**: v1 `sources[].path` / v0 `source.path` が
+  `/\.(png|jpe?g|webp|bmp|gif)$/i` に一致したら静止画ソースとして扱う。
+- スキーマに `isStatic` 等の新フィールドは**足さない**。`edit.schema.json` の `cutV0`/`cutV1`/
+  `sourceV0`/`sourceV1` の形は不変（`$comment` の追記のみ）
+- この正規表現は `packages/render-cut/src/layers.mjs` の `IMAGE_LAYER_SOURCE_PATTERN`
+  （画像レイヤーの先行裁定）と同一集合。判定ロジックの実体は 3 箇所で個別に持つ
+  （パッケージをまたいだ import はしない方針 — 各パッケージが単体でビルド/型チェック完結する
+  構成を崩さないため。`packages/render-cut/src/plan.mjs`/`render-cut.mjs` だけは同一パッケージ内
+  なので `layers.mjs` の `isImageLayerSource` をそのまま import する）:
+  - `packages/render-cut/src/layers.mjs`（`isImageLayerSource`。既存・本契約は変更しない）
+  - `packages/edit-lint/src/edit-lint.mjs`（`IMAGE_CUT_SOURCE_PATTERN`）
+  - `packages/preview-engine/src/clipSession.ts`（`STILL_IMAGE_SOURCE_PATTERN`）
+  - `packages/preview-server/src/edit-to-timeline.mjs` / `public/app.js`（後者は既存の
+    `IMAGE_LAYER_SRC_PATTERN`/`isImageLayerSrc` を cuts 判定にも再利用する）
+
+## 2. レンダー（render-cut）
+
+### 2.1 ffmpeg レシピ
+
+静止画ソースへの入力は `-loop 1` を付けて動画化する（旧参照実装 `akari-video-on-os` が
+2026-05 から実運用したレシピと同じ発想。`source.chroma_key.background` の画像背景が既に
+同じ `-loop 1` パターンをこのリポで使っている）。`-loop 1` は image2 デマルチプレクサを
+無限長ストリームにするだけで、実際の表示区間は既存の `trim=start=<in>:end=<out>` フィルタが
+決める（cut ごとに毎回この trim を通す設計は動画ソースと共通のため、静止画専用の別経路を
+新設する必要がなかった）。フレームレートは明示指定せず、既存の `fps=<output.fps>` 正規化フィルタ
+（動画ソースに対しても既に全経路にある）にそのまま乗せる。
+
+対象 3 経路（すべて `packages/render-cut/src/plan.mjs`）:
+- `buildCutCommand`（v0 既定の逐次連結パス）
+- `buildGapAwareCutCommand`（v0 の明示 at/track 配置パス）
+- `buildMultiSourceCutCommand`（v1。ソースごとに拡張子判定するため、動画と静止画が
+  `sources[]` に混在してよい）
+
+### 2.2 音声
+
+静止画には音声ストリームが無い。`hasAudio`/`source.hasAudio` は ffprobe が音声ストリームを
+検出しないことで自然に `false` になり、**3 経路とも既存の「無音源」分岐（`anullsrc` の無音
+stereo を合成する分岐）がそのまま発火する**。この分岐は静止画専用に新設したものではなく、
+音声トラックを持たない動画ソース（無音動画）に対して既に存在していた既定動作である。
+静止画区間の音声は無音・動画区間は元音声が残る、という裁定はこの既存分岐の副産物として
+自動的に成立する。
+
+### 2.3 duration probe の例外
+
+ffprobe は素の静止画ファイルに対して `format.duration` を報告しない（`-loop 1` を付けて
+probe しても同じ。実測確認済み）。`packages/render-cut/src/render-cut.mjs` の
+`measureCapabilities` は元々この欠落を「ffprobe が正の尺を返さなかった」エラーとして
+即座に reject していたため、静止画ソースを渡すと duration probe の時点で必ず落ちていた。
+静止画ソースだけ duration の positivity チェックを skip し、`sourceDuration`/
+`sourceInputs[].duration` は `null` のまま通す（§2.4 の理由により、この `null` が実際に
+参照される経路は存在しない）。
+
+### 2.4 v0「cuts 空 = source 全体」の不成立
+
+v0 は歴史的に `cuts` が空配列のとき「source 全体を 1 カットとして扱う」省略記法を持つ
+（`predictedDuration` が `sourceDuration` をそのまま尺として返す）。静止画には尺という概念が
+無いため、この省略記法は成立しない。**静止画ソースで `cuts` が空の場合は edit-lint がエラーで
+止める**（§3.3）。`packages/render-cut/src/plan.mjs` の `buildPlan` にも同じ条件の防御的
+バックストップを置いてある（lint を経由しない直接呼び出し向け。`buildTrackStackPlan` の
+`transition_out` バックストップと同じ姿勢）。
+
+## 3. in/out・freeze・speed の意味論（edit-lint が検証）
+
+### 3.1 in/out
+
+静止画 cut の表示尺は `out - in`。`in` は素材内の「どこから」に対応する概念が静止画には無いため
+**0 を推奨**する。0 以外を指定してもレンダーは `out - in` の尺だけを使い、`in` 自体の値は
+（trim の開始オフセットとしては使われるが、無限長ループの中のどの一点から始めても絵は同じなので）
+見た目に影響しない。0 以外は edit-lint が **警告**（`cuts.still-image-in`）を出す。
+
+### 3.2 freeze / speed
+
+- `cuts[].freeze` は静止画には視覚的な no-op（すでに静止している画に「静止」を足しても変化が
+  無い）。尺だけが `freeze.duration_sec` ぶん伸びる。動作はする（クラッシュしない）が意図が
+  紛れやすいため edit-lint が**警告**（`cuts.still-image-freeze`）を出す。同じ尺の延長を
+  得たいなら `out` を直接伸ばす方が素直、という代替案をメッセージに含める
+- `cuts[].speed` も同様に視覚効果が無い（静止画にコマ送りの概念が無い）。表示尺を
+  `(out - in) / speed` へ再スケールするだけなので動作はするが、edit-lint が**警告**
+  （`cuts.still-image-speed`）を出す
+
+### 3.3 v0 空 cuts の拒否
+
+`source.path` が静止画で `cuts` が空のとき、edit-lint は**エラー**
+（`cuts.still-image-cuts-required`）で止める（§2.4）。
+
+### 3.4 duration probe skip
+
+`source.path`（v0）が静止画のとき、edit-lint は `probeDuration` の呼び出し自体を skip する
+（§2.3 と同じ理由 — ffprobe が duration を返さないため。skip しないと edit-lint 自体が
+`ExecutionError` で落ちて PASS/FAIL の verdict を返せなくなる）。`skipped[]` に理由を記録する。
+
+## 4. スキーマ
+
+`edit.schema.json` の `sourceV0`/`sourceV1` に `$comment` を追記した（判定規則と cuts 側の
+意味論への参照）。`cutV0`/`cutV1` 自体の構造は変更なし。`packages/schemas/examples/
+edit-cuts-still-image-source-valid/` に mp4 + png 混在の v1 valid 例を追加した。
+
+## 5. プレビュー（Web UI）
+
+### 5.1 preview-engine（`packages/preview-engine`）
+
+`TimelineClip.mediaType`（既存の予約フィールド。`'video' | 'image'`）を実際に使う経路を実装した。
+`ClipSession` はコンストラクタで `src` の拡張子から静止画かどうかを判定し、静止画なら
+`MP4Clip`/WebCodecs デコーダを一切使わず `fetch` + `createImageBitmap` だけで読み込む。
+`tickExact`/`tickApprox`/`tickBackground` は毎回同じ `ImageBitmap` から `new VideoFrame(bitmap,
+{timestamp, duration})` を合成して返す。呼び出し側（`PreviewEngine.renderFrame`・
+`ThumbnailTrack`）は返る `VideoFrame` を `drawImage` して `close()` するだけなので、動画由来か
+ここで合成したものかを区別しない — 既存コードは無改修
+
+### 5.2 preview-server（Web UI 本体）
+
+`packages/preview-server/public/index.html` に `<video id="preview-video">` と同じ位置・
+サイズで重なる `<img id="preview-image">` を追加した（既定 `display: none`）。
+`app.js` は現在のセグメントが静止画のとき `<video>` を `pause()` して隠し、`<img>` の `src` を
+セグメントの画像へ合わせて表示する（`showStillImageForSegment`/`showVideoBase`）。`<video>`
+要素自体は作り直さない — `MediaElementAudioSourceNode` は生成元の要素に紐付くため、要素を
+差し替えると音声グラフが壊れる。`playedCutLocalSeconds`（`framing`/`freeze` の判定に使う
+カット内経過秒）は静止画区間では `video.currentTime` の代わりにマスタークロック
+`outputTime` から直接算出する（画像はシークしないため `video.currentTime` が更新されない）。
+
+### 5.3 apps/shell（スコープ外）
+
+Electron シェル本体（`apps/shell`）のプレビュー対応は本タスクのスコープ外。`layers[]` の
+image-layer-parity ではシェル側 webview も同時対応していたが、本タスクの司令塔裁定でシェルは
+別タスクへ切り出されている。§3 の適合状況表にシェル列は `❌`（未対応）として記録する。
+
+## 6. 適合状況の更新
+
+`contract-2026-08-02-preview-parity.md` §3 の適合状況表に `cuts[].static-image-source` 行を
+追加した（Web UI / shell 列）。