akari-video 0.1.10 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "0.1.10",
+  "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/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 正規化・ソースフレーム相対・静的**）。省略時は既定

package/vendor/docs/contract-2026-08-13-avatar-drive-v0.md

@@ -256,3 +256,249 @@ track の head は yaw/pitch/roll の radian だが、`avatar-vrm` の drive 受
 
 同じ track、cuts、fps、平滑化窓から作る head/eyes/emotion は決定論的であり、壁時計や乱数を
 参照しない。
+
+## v1.1 追記（2026-08-14）: PNGTuber モーション
+
+sprite ベイクへ、呼吸・発話バウンス・発話 onset ごとの微傾きを additive に追加する。
+`--motion-intensity <0..1>` の既定値は `0.5`。`--no-motion` は intensity `0` の別名であり、
+`--motion-intensity` との同時指定は曖昧さを避けるため拒否する。intensity `0` では全 frame が
+`scaleX=scaleY=1, tx=ty=rotateDeg=0` の厳密な恒等変換となり、アフィン変換とキャンバス拡張を
+一切通らない従来の raw RGBA → ProRes 経路を使う。
+
+frame `f`、`t=f/fps`、intensity `I` とする。入力ハッシュから得た位相 `p0,p1` により、呼吸波を
+次で定める。
+
+```text
+breath(t) = (sin(2π·0.25·t+p0) + 0.20·sin(2π·0.50·t+p1)) / 1.20
+```
+
+発話中は `mouth != "closed"` と判定する。発話 envelope `E` は target `1`（発話）/ `0`（無発話）
+へ指数平滑し、時定数は attack `0.06 s`、release `0.12 s`。発話 onset frame `o` から
+`pulse=(1-cos(2π·3.0·(f-o)/fps))/2`、`talk=E·(0.35+0.65·pulse)` とする。最終変換は次のとおり。
+
+```text
+scaleX = 1
+scaleY = 1 + I·(0.008·breath + 0.028·talk)
+tx = 0
+ty = -spriteHeight·I·(0.0015·breath + 0.009·talk)
+```
+
+微傾きは closed → 発話への各 onset で入力 seed の PRNG から符号と大きさを引き、target を
+`±3.2°·U(0.55,1.0)` とする。現在角度は target へ時定数 `0.28 s` の指数平滑で近づく。
+`--expression-track` 併用時、該当 frame の `drive.head` が non-null なら手続き角度を使わず、
+`rotateDeg=I·head.roll` とする。head が null の frame だけ手続き角度へ戻る。アフィン変換は拡張
+キャンバス中心を基準に scale → rotate → translate の順で適用し、RGBA は premultiplied alpha の
+bilinear 補間後に straight alpha へ戻す。
+
+キャンバスの四辺には全 frame で同じ整数 margin `M` を加える。各 frame の
+`θ=abs(rotateDeg)·π/180`、`hx=width·scaleX/2`、`hy=height·scaleY/2` に対し、
+
+```text
+ex = abs(cos θ)·hx + abs(sin θ)·hy + abs(tx)
+ey = abs(sin θ)·hx + abs(cos θ)·hy + abs(ty)
+M = ceil(max_all_frames(ex-width/2, ey-height/2) + 2px)
+```
+
+とする。末尾の `2px` は bilinear sampling support である。出力寸法は
+`(width+2M) × (height+2M)`。layer 配置には sprite.json の元寸法ではなくこの実ベイク寸法を使い、
+明示座標用 anchor も `(M + anchor·元寸法) / 実ベイク寸法` へ写像する。
+
+モーション seed は正規化済み edit.json、sprite.json、駆動 profile と固定識別子
+`avatar-drive-motion-v1.1` を stable stringify した SHA-256 から導出する。位相、onset の傾き、
+フレーム変換、補間、margin は壁時計・OS 乱数・mtime を参照しない。同一入力、同一 CLI 値、同一
+ffmpeg 実装なら stdout と MOV は byte 単位で決定論的である。
+
+既定が motion on (`0.5`) になったため、v1.1 の既定出力は従来よりキャンバスが大きく、画素も
+アフィン補間後の値へ変わる後方非互換点がある。従来と同じ寸法・画素・ProRes 呼び出しを必要とする
+場合は `--no-motion`（または `--motion-intensity 0`）を指定する。
+
+## v2 追記（2026-08-14）: 多層パーツツリーと 2D 物理
+
+v2 は `sprite.json` を置き換えない。`--sprites <dir>` の直下に `sprite.json` があれば従来形式として
+一切同じ経路で読み、無い場合だけ `parts.json` v2 を読む。両方がある場合も `sprite.json` を優先する。
+したがって既存セットの manifest、状態列、RGBA 合成、ProRes 呼び出し、stdout は変更しない。
+
+### v2.1 parts.json
+
+```jsonc
+{
+  "version": 2,
+  "size": { "width": 160, "height": 160 },
+  "anchor": { "x": 0.5, "y": 1 },
+  "parts": [
+    {
+      "id": "body",
+      "image": "body.png",
+      "parent": null,
+      "offset": { "x": 80, "y": 150 },
+      "origin": { "x": 35, "y": 70 },
+      "z": 0,
+      "states": "always"
+    },
+    {
+      "id": "hair-left",
+      "image": "hair-left.png",
+      "parent": "head",
+      "offset": { "x": -31, "y": -29 },
+      "origin": { "x": 9, "y": 5 },
+      "z": 5,
+      "states": "always",
+      "physics": {
+        "wobble": { "x": { "amplitude": 2, "frequency": 0.48, "phase": 1.1 } },
+        "follow": { "drag": 6 },
+        "rotationalDrag": { "strength": 1.35, "minDeg": -18, "maxDeg": 18, "lerp": 0.25 }
+      }
+    },
+    {
+      "id": "mouth-a",
+      "image": "mouth-a.png",
+      "parent": "head",
+      "offset": { "x": 0, "y": 18 },
+      "origin": { "x": 15, "y": 10 },
+      "z": 4,
+      "states": { "mouth": ["a", "mid", "open"] }
+    }
+  ]
+}
+```
+
+| フィールド | 規約 |
+|---|---|
+| `version` | 整数 `2` |
+| `size`, `anchor` | v0 と同じ出力キャンバス px と正規化アンカー |
+| `parts[].id` | セット内で一意な ASCII 識別子 |
+| `image` | セット内の PNG への相対パス。パーツごとに異なる実寸を許す |
+| `parent` | 親 id。ルートは `null`。複数ルートを許すが循環・欠落親は拒否する |
+| `offset` | 親の `origin` から当該パーツの `origin` までの px。ルートではキャンバス左上基準 |
+| `origin` | 当該 PNG 左上基準の回転・拡縮原点 px |
+| `z` | 小さい値から描く。等値は `parts[]` 宣言順 |
+| `states` | `"always"`、または `mouth` / `eyes` / `emotion` ごとの許可値配列 |
+| `physics` | 省略可。下節の `wobble` / `follow` / `rotationalDrag` / `talkBounce` |
+
+`states` に複数の駆動列があれば AND、同じ配列内の値は OR とする。口は
+`closed/mid/open/a/i/u/e/o`、目は `open/closed`、emotion は v0.2 の語彙をそのまま使う。
+たとえば `{mouth:["a","mid","open"],emotion:["happy"]}` は happy かつ該当口形の frame だけ
+表示する。母音モードでは、セット全体の `states.mouth` に `closed/a/i/u/e/o` が存在することを
+開始前に検査する。
+
+変換は親先行で評価する。行列を列ベクトルへ左から適用するとき、パーツ `p` の pivot 行列は
+`Pp = Pparent · T(offset + wobble) · R(rotationalDrag)`、画像行列は
+`Ip = Pp · T(-origin)` である。ルートの `Pparent` はキャンバス中心を原点とする v1.1 motion 行列で、
+`--no-motion` 時は恒等行列とする。これにより既存の呼吸・発話バウンス・微傾きは別の全画面後処理に
+せず、ルートパーツへ一度だけ適用される。描画は全パーツを `z` 順に straight-alpha over 合成し、
+サンプリングは premultiplied-alpha bilinear とする。
+
+### v2.2 物理語彙と決定論
+
+frame `f`、`t=f/fps`、固定ステップ `dt=1/fps` とする。壁時計、可変 delta、OS 乱数を使わない。
+phase を省略した wobble だけは、正規化済み入力から得た motion seed と part id と軸名を SHA-256
+へ入れ、その先頭 32 bit を `[0,2π)` へ写像する。
+
+**wobble** は軸ごとの閉形式サイン波である。
+
+```text
+wobbleAxis(t) = amplitude · sin(2π · frequency · t + phase)
+```
+
+`amplitude` は px、`frequency` は Hz、`phase` は rad。x/y は独立で、未指定軸は 0 px とする。
+
+**follow** は親が示す現在 frame の target pivot を、パーツが保持する world 座標へ lerp する。
+`drag >= 1` で、frame 0 は target へ初期化し、以後は次式とする。`drag=1` は遅れなしである。
+
+```text
+followed[f] = followed[f-1] + (target[f] - followed[f-1]) / drag
+```
+
+**rotationalDrag** は target と followed の world x 差を角度へ変換し、角度自体を lerp する。
+
+```text
+targetDeg[f] = clamp((targetX[f] - followedX[f]) · strength, minDeg, maxDeg)
+angle[f] = angle[f-1] + (targetDeg[f] - angle[f-1]) · lerp
+```
+
+`strength` は degree/px、`minDeg/maxDeg` の既定は `-180/180`、`lerp` の既定は `0.25`。
+
+**talkBounce** は closed から発話へ変わった frame で上向き初速を入れる固定 dt の放物運動である。
+
+```text
+onset: velocityY = -velocity
+velocityY[f] = velocityY[f-1] + gravity · dt
+bounceY[f] = bounceY[f-1] + velocityY[f] · dt
+```
+
+`bounceY` が 0 を越えたら 0 にクランプして停止し、反発はしない。値の単位は `velocity=px/s`、
+`gravity=px/s²`。v1.1 の標準発話バウンスはルート motion として既に存在するため、通常の v2 セットは
+ルートへ `talkBounce` を重ねない。この語彙は Plus import が明示的に値を持つ場合、または個別パーツを
+発話 onset で跳ねさせる場合の受け口である。
+
+同じ parts.json、PNG、駆動列、fps、profile、CLI 値、ffmpeg 実装なら、物理列、RGBA frame、MOV、
+stdout は byte 単位で一致する。stdout の `stats.follow_lag_frames` は follow 対象ごとに、target と
+followed の変動が大きい軸を選んで相互相関が最大になる 0〜2 秒の非負 lag を実測した frame 数である。
+
+### v2.3 PNGTuber Plus 語彙対応
+
+PNGTuber Plus 1.4.5（Unlicense）の保存・実行コードを仕様の一次資料として読み、コードは流用せず
+次の語彙を独自実装した。
+
+| PNGTuber Plus `.save` / 挙動 | parts.json v2 | 変換 |
+|---|---|---|
+| `identification` | `id` | 文字列化しセット内一意にする |
+| `parentId` | `parent` | identification 参照を id 参照へ変換。null は維持 |
+| `pos`, `offset` | `offset`, `origin` | Plus の pivot を解決して親原点相対 px へ正規化 |
+| `zindex` | `z` | 数値を維持。等値は import 宣言順 |
+| `xAmp/xFrq`, `yAmp/yFrq` | `physics.wobble` | `amplitude=Amp`、Plus の rad/frame を `frequency=Frq·fps/(2π)` へ換算 |
+| `drag` | `physics.follow.drag` | Plus の `lerp(...,1/dragSpeed)` と同じ係数。0/無効は `drag=1` |
+| `rotDrag`, `rLimitMin/Max` | `physics.rotationalDrag` | world 追従差 → degree/px とクランプへ正規化、角度 lerp は `0.25` |
+| global `bounce`, `gravity` | `physics.talkBounce` | import 厳密再現時は Plus 固定 `dt=0.0166` の sample を出力 fps へ再サンプルする |
+| `showTalk`, `showBlink` | `states.mouth/eyes` | Plus の speaking/blink 表を AKARI の明示状態集合へ展開 |
+| `stretchAmount` | 予約 | v2 は受理しない。将来の part scale drag として追加予定 |
+| `clipped`, costume, flipbook, toggle | 予約 | import 時に黙って捨てず unsupported として報告する |
+
+### v2.4 import 予約
+
+`.save` importer 自体は本版に含めない。将来 importer は埋め込み `imageData` を優先可能な PNG として
+抽出し、`path` は入力ファイル基準かつ境界内に解決できる場合だけ使う。整数辞書順を宣言順として
+parent tree と z を移し、上表の物理値と showTalk/showBlink を変換する。未対応フィールドは
+`unsupported[]`、変換で近似した値は `approximated[]` に必ず列挙し、モデル画像の利用権はユーザーが
+持ち込んだ範囲に限定する。export、配布モデルの収集・同梱は別契約とする。
+
+### v2.5 検証追加
+
+1. parent が宣言上は子より後でも親先行で解決し、循環・欠落親を拒否する。
+2. `z` 昇順・同値宣言順を固定し、親子変換後の基準点を数値で照合する。
+3. mouth/eyes/emotion の状態ごとに表示パーツが一意に切り替わる。
+4. wobble の閉形式値と固定 dt の follow/rotational drag/talk bounce を同入力 2 回で一致させる。
+5. 12 秒 say fixture で 3 髪房すべての `follow_lag_frames > 0` を測り、MOV SHA を 2 回一致させる。
+6. 既存 sprite.json のテスト fixture と `--no-motion` 経路は従来の寸法・画素・stdout を維持する。
+
+## v2.6 追記（2026-08-14）: 口状態切替のクロスフェード遷移
+
+`--mouth-transition <frames>` は、口状態が変わる境界からクロスフェードする frame 数 `N` を指定する。
+既定値は `2`。`0` は従来どおりの瞬間切替であり、遷移計算とブレンドを一切通らない。
+
+| 値 | 口状態切替 |
+|---:|---|
+| `0` | 境界 frame から新状態を直接描画する |
+| `N > 0` | 境界 frame から `N` frame を前状態と新状態のクロスフェードにする |
+
+境界 frame からのオフセットを `p=0..N-1` とし、配列末尾を越える frame は生成しない。ブレンド係数は
+次式で固定する。遷移中に次の口状態境界が現れた場合は、後の境界を優先する。
+
+```text
+t = (p + 1) / (N + 1)
+output = previous · (1 - t) + current · t
+```
+
+これは「前状態 α=`(1-t)` + 新状態 α=`t`」の単純合成であり、RGBA の各チャンネルを直接 lerp して
+最寄りの整数へ丸める。アルファ加重の over 合成ではない。
+
+この遷移は sprite.json v1 経路と parts.json v2 経路の両方へ適用する。v1 は同じ目状態で合成した
+前後の口 variant をブレンドしてから v1.1 のアフィン変換を適用する。v2 は現在 frame の物理・行列・
+`z`・宣言順をそのまま使い、口状態に依存する visibility だけを前状態と新状態へ振り替えた 2 frame を
+描画してブレンドする。したがって口以外のパーツ、物理、モーションは遷移の影響を受けない。
+
+係数、境界走査、チャンネル補間は乱数・壁時計を使わない。同じ入力、同じ CLI 値、同じ ffmpeg 実装なら
+stdout と MOV は byte 単位で決定論的に一致する。
+
+既定が非ゼロ (`2`) になったため、v2.6 の既定出力は口状態境界の画素が従来から変わる後方非互換点が
+ある。従来と同じ瞬間切替、画素、MOV を必要とする場合は `--mouth-transition 0` を指定する。

package/vendor/packages/akari-launcher/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "0.1.10",
+  "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 組み込みモジュールのみ）。 [akari-video npm vendor: bin/akari.mjs is reference-only. These CLI entrypoints are not included in the akari-video npm package. Run them from a full AKARI Video app installation (normally ~/.akari/app) or a monorepo checkout.]",
   "type": "module",
   "files": [

package/vendor/packages/asset-resolver/src/paid-zip.mjs

@@ -86,7 +86,12 @@ export async function verifyPaidZipContents(extractedRoot, id) {
     if (!match) {
       throw new AssetResolverError(`checksums.txt の行を解釈できません: ${id}: ${trimmed}`, 'integrity');
     }
-    expected.push({ sha256: match[1], relPath: match[2] });
+    const relPath = match[2];
+    // zip-slip 防御: checksums.txt 経由で packageDir の外を参照させない（絶対パス・`..` 拒否）
+    if (path.isAbsolute(relPath) || relPath.split(/[\\/]/).includes('..')) {
+      throw new AssetResolverError(`checksums.txt に不正なパスがあります: ${id}: ${relPath}`, 'integrity');
+    }
+    expected.push({ sha256: match[1], relPath });
   }
   if (expected.length === 0) {
     throw new AssetResolverError(`checksums.txt が空です: ${id}`, 'integrity');

package/vendor/packages/asset-resolver/src/resolve.mjs

@@ -1,7 +1,7 @@
 // resolve(id): 「使った素材だけをオンデマンドで取得する」の核。
 //
 // キャッシュヒット → 即パスを返す。未取得 → 全ファイルを一時ディレクトリへ実体化 →
-// sha256 検証 → （meta.json を持つ素材は）validate-asset で契約検証 →
+// sha256 検証 → validate-asset で契約検証（無料経路は meta.json を持つ素材のみ・有料経路は必須）→
 // 全部通ってから ~/.akari/assets/<category>/<id>/ へ原子的に move する。
 // 失敗は fail-closed（一時ディレクトリを破棄し、登録先には部分状態を残さない）。
 // 有料未購入（locked）は resolve を拒否する。
@@ -198,16 +198,38 @@ async function resolvePaidZip(item, { env, fetchImpl, project, home, destDir })
     extractZip(zipPath, extractedRoot);
     const { packageDir, payloadFiles } = await verifyPaidZipContents(extractedRoot, item.id);
 
+    // ストア入稿の実形は pack 形状（zip ルートに PACK.json / docs/ を持ち、素材本体は
+    // assets/<category>/<id>/ 配下）。契約 v0 のフラット形状（zip 直下に meta.json / 本体）も
+    // 引き続き受け付ける。どちらの形でも、ライブラリへ入るのは素材ディレクトリの中身だけ
+    // （PACK.json / docs はライブラリに混ぜない — 全量が必要なら `akari store download` が zip を渡す）。
+    const nestedPrefix = `assets/${item.category}/${item.id}/`;
+    const nestedFiles = payloadFiles
+      .filter((relPath) => relPath.startsWith(nestedPrefix))
+      .map((relPath) => relPath.slice(nestedPrefix.length));
+    const payloadRoot = nestedFiles.length > 0
+      ? path.join(packageDir, 'assets', item.category, item.id)
+      : packageDir;
+    const assetFiles = nestedFiles.length > 0 ? nestedFiles : payloadFiles;
+
+    // 有料素材は meta.json 必須（契約検証を必ず通す）。形の取り違えを「meta.json の無い素材」と
+    // 誤認して検証スキップのまま通した前歴（#25）があるため fail-closed に倒す
+    if (!assetFiles.includes('meta.json')) {
+      throw new AssetResolverError(
+        `有料素材の zip に meta.json がありません（期待: assets/<category>/<id>/meta.json または zip 直下）: ${item.id}`,
+        'integrity',
+      );
+    }
+
     await mkdir(tempAssetDir, { recursive: true });
-    let hasMeta = false;
-    for (const relPath of payloadFiles) {
-      if (relPath === 'meta.json') hasMeta = true;
-      await cp(path.join(packageDir, relPath), path.join(tempAssetDir, relPath), {
+    for (const relPath of assetFiles) {
+      const destFile = path.join(tempAssetDir, relPath);
+      await mkdir(path.dirname(destFile), { recursive: true });
+      await cp(path.join(payloadRoot, relPath), destFile, {
         mode: constants.COPYFILE_FICLONE,
       });
     }
 
-    if (hasMeta) {
+    {
       const result = spawnSync(process.execPath, [VALIDATE_ASSET_SCRIPT, tempAssetDir], { encoding: 'utf8' });
       if (result.status !== 0) {
         const output = `${result.stdout ?? ''}${result.stderr ?? ''}`.trim();

package/vendor/packages/asset-resolver/test/resolve-paid-zip.test.mjs

@@ -48,8 +48,13 @@ function paidMetaBuffer(id, category) {
  * 契約 §6 の zip 構成（`<id>-v<version>/` 直下に README.md / LICENSE.md / 本体 / checksums.txt）を
  * システムの `zip` コマンドで実際に作る。`corrupt: '<name>'` を指定すると、その名前の
  * checksums.txt エントリだけ sha256 を意図的にずらす（checksums 不一致テスト用）。
+ *
+ * `layout: 'pack'` はストア入稿の実形（#25 で発覚）を作る: zip ルートに PACK.json / docs/ を持ち、
+ * 素材本体は assets/<category>/<id>/ 配下。`withoutMeta: true` は meta.json を落とした zip を作る
+ * （有料経路の meta.json 必須化テスト用）。`extraChecksumLine` は checksums.txt に任意の 1 行を
+ * 追記する（zip-slip 防御テスト用）。
  */
-function buildPaidZip(id, category, { corrupt } = {}) {
+function buildPaidZip(id, category, { corrupt, layout = 'flat', withoutMeta = false, extraChecksumLine } = {}) {
   const stage = mkdtempSync(path.join(tmpdir(), 'paid-zip-fixture-'));
   const rootName = `${id}-v1`;
   const rootDir = path.join(stage, rootName);
@@ -64,19 +69,31 @@ function buildPaidZip(id, category, { corrupt } = {}) {
     'model.glb': Buffer.from('glTF-fixture-not-a-real-binary'),
     'preview.png': MINI_PNG,
   };
+  if (withoutMeta) delete payload['meta.json'];
+
+  const payloadPrefix = layout === 'pack' ? `assets/${category}/${id}/` : '';
   const allFiles = {
     'README.md': Buffer.from('# fixture\n'),
     'LICENSE.md': Buffer.from('fixture license\n'),
-    ...payload,
   };
+  if (layout === 'pack') {
+    allFiles['PACK.json'] = Buffer.from(`${JSON.stringify({ id, version: 1 })}\n`);
+    allFiles['docs/GUIDE.md'] = Buffer.from('# pack guide fixture\n');
+  }
+  for (const [name, buffer] of Object.entries(payload)) {
+    allFiles[`${payloadPrefix}${name}`] = buffer;
+  }
   for (const [name, buffer] of Object.entries(allFiles)) {
-    writeFileSync(path.join(rootDir, name), buffer);
+    const filePath = path.join(rootDir, name);
+    mkdirSync(path.dirname(filePath), { recursive: true });
+    writeFileSync(filePath, buffer);
   }
 
   const checksumLines = Object.keys(allFiles).sort().map((name) => {
     const digest = name === corrupt ? '0'.repeat(64) : sha256(allFiles[name]);
     return `${digest}  ${name}`;
   });
+  if (extraChecksumLine) checksumLines.push(extraChecksumLine);
   writeFileSync(path.join(rootDir, 'checksums.txt'), `${checksumLines.join('\n')}\n`);
 
   const zipPath = path.join(stage, `${rootName}.zip`);
@@ -220,3 +237,76 @@ test('resolvePaidZip: ダウンロード失敗（トークン失効等）も fai
 
   assert.equal(existsSync(path.join(home, 'assets', 'scene3d', 'mini-paid-zip')), false);
 });
+
+test('resolvePaidZip: pack 形状（assets/<category>/<id>/ 配下）は素材本体へ降りて登録される（#25）', async () => {
+  const { env, home, catalog, catalogPath } = setupFixtureEnv();
+  writeCredentials(home);
+  addPaidCatalogItem(catalog, catalogPath, 'mini-paid-pack', 'scene3d', 2980);
+  const zipPath = buildPaidZip('mini-paid-pack', 'scene3d', { layout: 'pack' });
+
+  const result = await resolveAsset('mini-paid-pack', {
+    env,
+    fetchImpl: fetchImplFor('mini-paid-pack', { entitled: true, zipPath }),
+  });
+
+  // meta.json がライブラリ直下（<category>/<id>/meta.json）に来る — #25 の壊れ形の否定
+  assert.equal(result.dir, path.join(home, 'assets', 'scene3d', 'mini-paid-pack'));
+  assert.ok(existsSync(path.join(result.dir, 'meta.json')));
+  assert.ok(existsSync(path.join(result.dir, 'fragment.html')));
+  assert.ok(existsSync(path.join(result.dir, 'model.glb')));
+  // pack の梱包物（PACK.json / docs/）と入れ子の assets/ はライブラリに混ぜない
+  assert.equal(existsSync(path.join(result.dir, 'PACK.json')), false);
+  assert.equal(existsSync(path.join(result.dir, 'docs')), false);
+  assert.equal(existsSync(path.join(result.dir, 'assets')), false);
+
+  const meta = JSON.parse(readFileSync(path.join(result.dir, 'meta.json'), 'utf8'));
+  assert.equal(meta.id, 'mini-paid-pack');
+});
+
+test('resolvePaidZip: meta.json の無い有料 zip は fail-closed（無警告スキップを許さない — #25）', async () => {
+  const { env, home, catalog, catalogPath } = setupFixtureEnv();
+  writeCredentials(home);
+  addPaidCatalogItem(catalog, catalogPath, 'mini-paid-nometa', 'scene3d', 2980);
+  const zipPath = buildPaidZip('mini-paid-nometa', 'scene3d', { withoutMeta: true });
+
+  await assert.rejects(
+    () => resolveAsset('mini-paid-nometa', {
+      env,
+      fetchImpl: fetchImplFor('mini-paid-nometa', { entitled: true, zipPath }),
+    }),
+    (error) => {
+      assert.ok(error instanceof AssetResolverError);
+      assert.equal(error.code, 'integrity');
+      assert.match(error.message, /meta\.json/);
+      return true;
+    },
+  );
+
+  assert.equal(existsSync(path.join(home, 'assets', 'scene3d', 'mini-paid-nometa')), false);
+  const stray = readdirSync(home).filter((name) => name.startsWith('.tmp-resolve-'));
+  assert.deepEqual(stray, [], '一時ディレクトリが破棄されていること');
+});
+
+test('resolvePaidZip: checksums.txt の `..` パスは zip-slip として拒否される', async () => {
+  const { env, home, catalog, catalogPath } = setupFixtureEnv();
+  writeCredentials(home);
+  addPaidCatalogItem(catalog, catalogPath, 'mini-paid-slip', 'scene3d', 2980);
+  const zipPath = buildPaidZip('mini-paid-slip', 'scene3d', {
+    extraChecksumLine: `${'0'.repeat(64)}  ../outside.txt`,
+  });
+
+  await assert.rejects(
+    () => resolveAsset('mini-paid-slip', {
+      env,
+      fetchImpl: fetchImplFor('mini-paid-slip', { entitled: true, zipPath }),
+    }),
+    (error) => {
+      assert.ok(error instanceof AssetResolverError);
+      assert.equal(error.code, 'integrity');
+      assert.match(error.message, /不正なパス/);
+      return true;
+    },
+  );
+
+  assert.equal(existsSync(path.join(home, 'assets', 'scene3d', 'mini-paid-slip')), false);
+});

package/vendor/packages/edit-lint/src/cut-timeline.mjs

@@ -0,0 +1,17 @@
+// Local port of packages/render-cut/src/cut-timeline.mjs's cutSpeed/segmentDuration and
+// packages/render-cut/src/cut-freeze.mjs's freezeDurationSeconds. edit-lint is a lower-level
+// package render-cut depends on, so it cannot import back from render-cut. Keep this copy in
+// sync whenever the render-cut implementations change.
+export function cutSpeed(cut) {
+  const value = cut?.speed;
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 1;
+}
+
+export function freezeDurationSeconds(freeze) {
+  const value = freeze?.duration_sec;
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+export function segmentDuration(cut) {
+  return (cut.out - cut.in) / cutSpeed(cut) + freezeDurationSeconds(cut?.freeze);
+}

package/vendor/packages/edit-lint/src/edit-lint.mjs

@@ -14,6 +14,7 @@ import { createRequire } from "node:module";
 
 import { renderLintReport } from "./report.mjs";
 import { deriveTracks } from "./derive-tracks.mjs";
+import { segmentDuration } from "./cut-timeline.mjs";
 import { musicGrid } from "../../audio-library-setup/shared/beat-grid.mjs";
 import { resolveFfmpeg, resolveFfprobe } from "../../media-bin/src/index.mjs";
 
@@ -222,6 +223,7 @@ export async function lintProject(input, options = {}) {
     edit.version,
     structure.sourceIds,
   );
+  validateFrameGridAlignment(edit.cuts, edit?.output?.fps, findings);
   validateCutTrackFields(edit.cuts, findings);
   validateCutTransformFields(edit.cuts, findings);
   validateStillImageCuts(edit, findings);
@@ -599,8 +601,8 @@ function validateTransitionOut(value, findings, path) {
     addFinding(findings, { severity: "error", check: "cuts.transition-out.structure", message: "transition_out must be an object", path });
     return;
   }
-  if (!["dissolve", "fade-black", "fade-white"].includes(value.type)) {
-    addFinding(findings, { severity: "error", check: "cuts.transition-out.type", message: "type must be dissolve/fade-black/fade-white", path });
+  if (!["dissolve", "fade-black", "fade-white", "reveal-down", "reveal-up"].includes(value.type)) {
+    addFinding(findings, { severity: "error", check: "cuts.transition-out.type", message: "type must be dissolve/fade-black/fade-white/reveal-down/reveal-up", path });
   }
   if (!isPositiveNumber(value.duration)) {
     addFinding(findings, { severity: "error", check: "cuts.transition-out.duration", message: "duration must be a positive number", path });
@@ -1240,7 +1242,7 @@ function validateCuts(cuts, sourceDuration, findings, paths, version, sourceIds)
       });
       valid = false;
     } else {
-      timeline += cut.out - cut.in;
+      timeline += segmentDuration(cut);
     }
     if (version === 1) {
       if (!isNonEmptyString(cut.src)) {
@@ -1317,6 +1319,37 @@ function validateCuts(cuts, sourceDuration, findings, paths, version, sourceIds)
   return valid ? timeline : null;
 }
 
+function validateFrameGridAlignment(cuts, fps, findings) {
+  if (!Array.isArray(cuts) || !isPositiveNumber(fps)) return;
+  const frameDuration = 1 / fps;
+  let position = 0;
+
+  for (const [index, cut] of cuts.entries()) {
+    if (
+      !isRecord(cut) ||
+      !isFiniteNumber(cut.in) ||
+      !isFiniteNumber(cut.out) ||
+      cut.out <= cut.in
+    ) {
+      continue;
+    }
+    const duration = segmentDuration(cut);
+    position += duration;
+    const frames = position / frameDuration;
+    const nearest = Math.round(frames);
+    const errorFrames = Math.abs(frames - nearest);
+    if (errorFrames <= 0.05) continue;
+
+    const cutFrames = duration / frameDuration;
+    addFinding(findings, {
+      severity: "warning",
+      check: "cuts.frame-grid",
+      message: `cut ${index} duration ${duration.toFixed(4)}s is not frame-aligned at ${fps}fps (${cutFrames.toFixed(1)} frames) -- boundary-synced overlays/transitions may shift by one frame`,
+      path: `edit.json#cuts[${index}]`,
+    });
+  }
+}
+
 function validateDurationMaximum(outputs, timeline, findings) {
   if (outputs === undefined) return;
   if (!Array.isArray(outputs)) {

package/vendor/packages/schemas/bin/validate-edit.mjs

@@ -1052,8 +1052,8 @@ function validateTransitionOut(value, label) {
     fail(`${label} は object である必要があります`);
     return;
   }
-  if (!["dissolve", "fade-black", "fade-white"].includes(value.type)) {
-    fail(`${label}.type は dissolve/fade-black/fade-white のいずれかである必要があります`);
+  if (!["dissolve", "fade-black", "fade-white", "reveal-down", "reveal-up"].includes(value.type)) {
+    fail(`${label}.type は dissolve/fade-black/fade-white/reveal-down/reveal-up のいずれかである必要があります`);
   }
   if (!isFiniteNumber(value.duration) || value.duration <= 0) {
     fail(`${label}.duration は 0 より大きい有限数である必要があります`);

package/vendor/packages/schemas/edit.schema.json

@@ -223,10 +223,10 @@
       "additionalProperties": true,
       "required": ["type", "duration"],
       "properties": {
-        "type": { "enum": ["dissolve", "fade-black", "fade-white"] },
+        "type": { "enum": ["dissolve", "fade-black", "fade-white", "reveal-down", "reveal-up"] },
         "duration": { "$ref": "#/$defs/positiveNumber" }
       },
-      "$comment": "docs/contract-2026-07-22-render-basics.md #3。v0 は指定されたカット境界のみ xfade 経路（残裁定3）。ffmpeg xfade の transition 名へ直接対応: dissolve/fadeblack/fadewhite。"
+      "$comment": "docs/contract-2026-07-22-render-basics.md #3。v0 は指定されたカット境界のみ xfade 経路（残裁定3）。ffmpeg xfade の transition 名へ直接対応: dissolve/fadeblack/fadewhite/revealdown/revealup。reveal-down / reveal-up は前カットが丸ごとその方向へ動いて画面外へ抜け、空いた側から次カットが現れる（2026-08-14 追加）。"
     },
     "cutTransform": {
       "type": "object",

package/vendor/packages/schemas/test/validate-edit.test.mjs

@@ -197,12 +197,12 @@ test("source.chroma_key.color is required", () => {
   assert.match(executed.stderr, /source\.chroma_key\.color は空でない文字列である必要があります/);
 });
 
-test("cuts[].transition_out.type must be dissolve/fade-black/fade-white", () => {
+test("cuts[].transition_out.type must be dissolve/fade-black/fade-white/reveal-down/reveal-up", () => {
   const executed = run("edit-transition-invalid");
   assert.equal(executed.status, 1, executed.stdout);
   assert.match(
     executed.stderr,
-    /cuts\[0\]\.transition_out\.type は dissolve\/fade-black\/fade-white のいずれかである必要があります/,
+    /cuts\[0\]\.transition_out\.type は dissolve\/fade-black\/fade-white\/reveal-down\/reveal-up のいずれかである必要があります/,
   );
 });
 

package/vendor/skills/edit-plan/execution.md

@@ -45,6 +45,31 @@ BGM と SFX は [音声契約](../../docs/contract-2026-07-14-edit-json-v1-audio
 - スライドショーのように静止画を順に見せる構成も、画像 1 枚につき `layers[]` 1 項目（`track` 付き）で表す。**静止画群を ffmpeg で 1 本の動画へ連結してから source にしない** — 個々の画像の差し替え・タイミング調整の編集性が失われ、`edit.json` の SSOT が壊れる。これは上記「承認を得ずに黙って concat しない」の具体例である。
 - cuts のソース（v1 `sources[].path` / v0 `source.path`）に静止画を書く経路は**現状未対応**（レンダーが時間軸を持つ動画を前提とする）。メイン時間軸そのものを静止画で構成する必要があり `layers[]` で表せない場合は、連結動画で回避せず停止して報告する。
 
+### レイヤー素材の時間基準（2026-08-14・実害から追記）
+
+人物切り抜き・B-roll など `layers[]` に重ねる素材で、**十数フレーム単位のズレを作り込みやすい**
+3 点。正本は `docs/contract-2026-08-02-preview-parity.md` §2.4 と
+`docs/contract-2026-07-22-render-basics.md` §2-3。
+
+- **`layers[]` に in トリムは無い。素材の先頭が常に `t` に対応する**（`cuts[].in/out` に相当する
+  ものが無い）。したがって素材が既にカット単位で切り出されているなら、**そのまま
+  `t = 使い始めたい時刻` / `duration = 使いたい長さ` を書くだけ**でよい。
+  「パネルが先に出ているから素材にもプリロールがあるはず」といった**推測でのトリムをしない**。
+  推測でトリムすると素材の頭が前へずれ、さらに `duration` を詰めた分だけ末尾で素材が尽きて
+  「重ねた素材が消えて下地だけになる」瞬間が出る。
+- **素材の途中から使いたい場合は素材そのものを切り出すしかない**。切り出したら
+  **由来（元素材 / in / out / speed / fps）を素材の隣に必ず残す**。残さないと次に触る人が
+  「この素材の頭は何の時刻か」を推測することになり、同じ事故を繰り返す。
+- **`output.look` の LUT は `cuts[]` の本編にしか掛からない**。重ねた素材は素の色のまま合成される。
+  色を合わせるには `layers[].filter` に**同じ `id` / `intensity` を明示的に宣言**する
+  （`{"type":"lut","id":"cinematic","intensity":0.5}`）。
+- 時間対応を後から**実測**するときは、`blend=difference` の絶対差を使わない。上記の色差が
+  支配して指標が平坦になり、誤った結論（適当な lag が「最小」に見える）に落ちる。
+  **フレーム間差分エネルギーの時系列**（`format=gray,tblend=all_mode=difference` →
+  `signalstats` の YAVG）を素材側とカット側で取り、正規化して**相互相関**させると、
+  色に不変で lag を特定できる。カットに `speed` が掛かっている場合は、素材が
+  「速度適用済みで焼かれている」のか「素材レートのまま」なのかもこの相関で判別できる。
+
 ## 2. edit.json を作る
 
 承認値を次の形へ入れる。例の数値を既定値として流用しない。
@@ -188,6 +213,12 @@ node packages/render-cut/bin/akari-apply-textstyle.mjs <project-dir> <preset-id>
 - 按分 fallback を「区間の拡張」に使い、末尾語の推定 end を越えて次 caption まで字幕を伸ばす（§4）。
 - **切り出し・先出しクリップを見せ場スコア位置の機械窓（segment 量子化時刻）のまま切り出し、意図した発話を窓の外へ落とす／全文 1.0s 未満の読めない字幕を出す**（発話へスナップし呼吸 0.5s を残す。§2）。
 - `cuts` と overlay の時刻をどちらも source 秒で書く。
+- **`layers[]` の素材の頭を「プリロールがあるはず」と推測してトリムする**（`layers[]` に in トリムは
+  無く、素材の先頭が常に `t`。切り出し済み素材ならそのまま `t = 使い始めたい時刻` に置く。§1 レイヤー素材の時間基準）。
+- **`output.look` の LUT がレイヤーにも掛かると思い込む**（掛かるのは `cuts[]` の本編だけ。
+  重ねた素材は `layers[].filter` に同じ `id` / `intensity` を書いて揃える。§1 レイヤー素材の時間基準）。
+- 重ねた素材とカットの時間ズレを `blend=difference` の絶対差で測る（色が違うと指標が平坦になり
+  誤った結論に落ちる。フレーム間差分の相互相関で測る。§1 レイヤー素材の時間基準）。
 - 実行承認前に中間マスターや overlay を作る。
 - authoring skill がないことを理由に規約を省略する。
 - edit.json の sample 値を、承認されていない出力仕様として使う。

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

@@ -98,6 +98,8 @@ fragment は単一ルートとし、透明 canvas、任意の静的 fallback、
   確認し、白飛びを抑えるなら `exposure`、映り込み自体の強弱を変えるなら `intensity` を小幅に調整する。
   IBL 自体（既定値での環境マップ・トーンマッピング）は preview / export とも常に有効 — `environment`
   キーは既定値からの微調整用の任意 knob。
+- **金属マテリアルは environment の映り込みでしか色が出ない。** 暗い場合は
+  `environment: { "intensity": ..., "exposure": ... }` を明示する。既定 intensity 0.5 + ACES では宣言色より大きく沈む。
 - `environment.map` は**正距円筒（equirectangular）画像の相対パス**。宣言すると既定の手続き生成
   `RoomEnvironment` を差し替える。金属は環境の映り込みでしか見えないので、光源に「形」が要る
   ヒーローカットではこれが効く（既定の部屋は強度スカラーしか触れず、側面レールが黒く沈む）。
@@ -116,7 +118,7 @@ fragment は単一ルートとし、透明 canvas、任意の静的 fallback、
   `"*"` も指定できる。省略時は静的シーンを描画する。Blender の glTF 書き出しはオブジェクトごとに
   clip を分けるので、1 個のモデルに複数の動きがあるときは `"*"` で束ねる（1 本しか再生しないと
   片方しか動かない）。存在しない clip 名を書いた場合はエラーになる。
-- `materialOverrides` は `{ "<material 名>": { "texture": "<画像または動画の相対パス>" } }` の形で、名前が一致するマテリアルの `emissiveMap` を差し替える。edit.json のあるディレクトリからの相対 PNG / JPEG / WebP 等、または MP4 / MOV / WebM を指定し、URL や CDN を書かない。該当するマテリアル名がモデル内にない場合は警告して無視される。
+- `materialOverrides` は `{ "<material 名>": { "texture": "<画像または動画の相対パス>" } }` の形で、名前が一致するマテリアルの `emissiveMap` を差し替える。**差し替え先が `emissiveMap` である以上、貼り先の材質が発光しない（glTF の `emissiveFactor` が未設定 = 黒）と「0 × テクスチャ」で何も出ない**（2026-08-14 実害。詳細は後述「発光しない材質には貼れない」）。edit.json のあるディレクトリからの相対 PNG / JPEG / WebP 等、または MP4 / MOV / WebM を指定し、URL や CDN を書かない。該当するマテリアル名がモデル内にない場合は警告して無視される。
   - **パスは「edit.json のあるディレクトリ」から。断片の場所からの相対ではない。** `model` も同様。
     断片を `overlays/3d-phone/fragment.html` へ置いたなら `"overlays/3d-phone/model.glb"` と書く
     （`"model.glb"` はプロジェクト直下を探して ENOENT になる）。
@@ -560,6 +562,50 @@ container を渡しても、断片の外側からは同じ値が同じ式で読
 - 同梱クリップの尺・向きが用途に合わないことは珍しくない。合わないなら**作り直す方が速い**
   （§glb を直接編集する）
 
+### 発光しない材質には貼れない（materialOverrides の実測 2026-08-14）
+
+`materialOverrides` の差し替え先は `emissiveMap` 固定である。three は `emissive`（glTF の
+`emissiveFactor`）を掛けてから合成するので、**`emissiveFactor` が未設定＝黒の材質へ貼っても
+「0 × テクスチャ」で完全に消える**。しかもエラーにならないため、原因に辿り着きにくい。
+
+実害: アプリアイコンの glb は前面（`IconFaceMaterial`）が非発光で、`materialOverrides` を
+宣言しても**白い樹脂の面のまま**だった。同じ宣言でスマホの画面（`ScreenMaterial` =
+`emissiveFactor: [1,1,1]`）は正しく映るので、「宣言は合っているのに出ない」状態になる。
+
+- 判定: 貼る前に glb の材質を確認する。`emissiveFactor` が無ければ貼れない
+  ```sh
+  python3 -c "import json,struct;d=open('model.glb','rb').read();n=struct.unpack('<I',d[12:16])[0];j=json.loads(d[20:20+n]);print([(m['name'],m.get('emissiveFactor')) for m in j['materials']])"
+  ```
+- 対処 1（推奨）: モデル側の当該材質に `emissiveFactor: [1,1,1]` を与える。あわせて
+  `baseColorFactor` を暗く落とすと、貼った絵の発色を下地が濁さない
+- 対処 2: 発光する材質（画面用など）を対象にする
+- ランタイムは非発光の材質を対象にすると**警告を出す**（2026-08-14 追加）。ログを見ること
+
+### 動きプリセットは「正面を向く時間」を実測してから使う（2026-08-14）
+
+`animationClip` の回転系プリセットは、**表示区間の大半で裏面や側面を向いていることがある**。
+1〜2 秒しか出さないオーバーレイでは、貼ったテクスチャが一度も映らないまま終わる。
+
+実害: アプリアイコンの 3 本（`Turntable` / `PopInDrop` / `TumbleReveal`）はいずれも序盤
+約 1.5 秒がアイコン面の裏側で、1.8 秒の表示では白い面しか映らなかった。
+**`animationClip` を外した初期姿勢が正面**だったため、短い露出では回さないのが正解だった。
+
+- 短時間の露出では、まず `animationClip` 無し（初期姿勢）で焼いて向きを確かめる
+- 回したい場合は、クリップの位相を実測して「正面が映る区間」に表示窓を合わせる
+
+### 実写に重ねる小物は `--akari-3d-zoom` を 0.3〜0.5 まで落とす（2026-08-14）
+
+`--akari-3d-zoom` の既定 1.0 は**フレームいっぱいに 3D が映る**設定。実写の上へアイコンや
+端末をワンポイントで置く用途では大きすぎ、画面外へはみ出す。実測の目安はアイコン 0.30〜0.34、
+スマホ実機 0.46。位置は `--akari-3d-pan-y`（正 = 下）で送る。
+
+### 3D の確認は「最小プロジェクトを焼く」（2026-08-14）
+
+`harness/render-fragment.mjs` の単体レンダーでは 3D シーンが `status=error` になる
+（`model` / `texts[].font` がプロジェクトルート相対で解決されるため、プロジェクト文脈が要る）。
+**確認は最小の `edit.json` を作って `render-cut` で焼き、フレームを抜いて目視する**。
+断片だけを見て「貼れたはず」と判断しない。
+
 ### モデルの「既定ポーズ = 中立」と決めつけない（実測 2026-08-04）
 
 ノート PC の `lid_root` で、回転 0°（単位クォータニオン）が **「閉じ」ではなく「180° フラット

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

@@ -78,25 +78,12 @@ rAF は、外部タイムラインから既に決めた状態を再描画する
   1. 単発のループ演出（点滅など）は必ず両端を明示する（`0%, 100% { opacity: 1; } 50% { opacity: 0; }`）。片方しか書かない省略はしない
   2. 同一プロパティを複数段でつなぐ場合、後段の `0%` / `from` に**前段の着地値を明示的に複製**する（暗黙合成に任せない）
 
-### 書き出しランタイムは `animation-fill-mode` を `both` に強制する（2026-08-14 実測）
+### 書き出しランタイムは authored の `animation-fill-mode` を尊重する（2026-08-16 実測）
 
-書き出し時、render-cut のオーバーレイシートは authored の CSS animation を **paused WAAPI クローンへ変換**して駆動する。このとき timing は複製されるが **fill だけは `'both'` に固定**される（`packages/render-cut/src/rasterize.mjs` の変換部）。authored 側で `forwards` / `none` を指定しても**書き出しには一切反映されない**。
+書き出し時、render-cut は CSS animation を paused WAAPI クローンへ変換するが、`fill` は authored の宣言（`none` / `forwards` / `backwards` / `both`）をそのまま引き継ぐ。プレビューと書き出しで fill-mode の意味は一致する。
 
-- 帰結: `animation-delay` 付きの断片は、**delay 中ずっと `0%` / `from` の状態が backwards fill で表示される**。「発火して消える」過渡 FX（集中線・波紋・破片・フラッシュ等）の from を `opacity: 1` で書くと、発火前から初期姿のまま画面に写り込む
-- 実例: 集中線 12 本 + 波紋 + 破片（delay 1.73s, `from { opacity: 1; ... }`）が、オーバーレイ開始直後から中央に小さな円環として常時表示された。`forwards` へ直して再書き出ししても**出力はバイト同一**（fill が強制されているため）
-- **プレビューと書き出しで挙動が割れる**: ブラウザプレビューは authored fill-mode を尊重するため、プレビューだけ見ると `forwards` で直ったように見える
-- 直し方: **過渡 FX は `0%` キーフレーム自体を不可視（`opacity: 0`）にし、最初の数 %（〜50ms 相当）で立ち上げる**。delay 中は backwards fill が `0%` を適用するので必ず隠れる
-
-  ```css
-  @keyframes burst-ray {
-    0%   { opacity: 0; transform: rotate(var(--a)) translateX(90px) scaleX(0.3); }
-    8%   { opacity: 1; }
-    70%  { opacity: 1; }
-    100% { opacity: 0; transform: rotate(var(--a)) translateX(300px) scaleX(1); }
-  }
-  ```
-
-- 覚え方: **入場して留まる要素は from を「隠れ状態」で書くので `both` 前提と両立する。発火して消える要素は from こそ隠す**。fill-mode の書き分けで解決しようとしない（書き出しでは選べない）
+- 同一要素へ IN と遅延付き OUT を並べる場合は、`animation: intro .3s both, outro .3s 1s forwards` のように OUT へ backward fill を付けない。OUT の `0%` が delay 中の IN を上書きせず、IN → hold → OUT が順に効く
+- 遅延前から `0%` を見せたい演出だけ `backwards` / `both` を宣言する。過渡 FX を発火前に隠す場合は `forwards` / `none` を選ぶか、意図して backward fill を使うなら `0%` 自体を不可視にする
 
 ### 入場して留まる要素の base を隠れ状態にすると書き出しで消える（2026-08-14 実測）