akari-video 0.1.27 → 0.1.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "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/capture-command.mjs

@@ -0,0 +1,55 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { resolveLauncherAssets } from "./repo-assets.mjs";
+
+export async function runCaptureCommand(argv, options = {}) {
+  const logError = options.error ?? options.logError ?? ((line) => console.error(line));
+  const assets = options.assets ?? resolveLauncherAssets();
+  if (!assets.captureScript || !existsSync(assets.captureScript)) {
+    logError("akari capture の実行スクリプトが見つかりません。AKARI Video を再インストールしてください。");
+    return { exitCode: 1 };
+  }
+
+  const isHelp = argv.includes("--help") || argv.includes("-h");
+  if (!isHelp && captureNeedsChrome(argv, options.platform ?? process.platform)) {
+    const browser = await resolveBrowserDiagnostics(assets, options);
+    if (!await browser.findChromePath()) {
+      logError(await browser.describeChromeNotFound());
+      return { exitCode: 1 };
+    }
+  }
+
+  const spawn = options.spawn ?? spawnSync;
+  const result = spawn(process.execPath, [assets.captureScript, ...argv], {
+    stdio: "inherit",
+    cwd: options.cwd ?? process.cwd(),
+  });
+  return { exitCode: typeof result.status === "number" ? result.status : 1 };
+}
+
+export function captureNeedsChrome(argv, platform = process.platform) {
+  let engine = "auto";
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] === "--engine" && argv[index + 1] !== undefined) engine = argv[index + 1];
+    else if (argv[index].startsWith("--engine=")) engine = argv[index].slice("--engine=".length);
+  }
+  return engine === "legacy" || (engine === "auto" && !["darwin", "win32"].includes(platform));
+}
+
+async function resolveBrowserDiagnostics(assets, options) {
+  if (options.findChromePath && options.describeChromeNotFound) {
+    return {
+      findChromePath: options.findChromePath,
+      describeChromeNotFound: options.describeChromeNotFound,
+    };
+  }
+  const modulePath = join(assets.repoRoot, "packages", "render-cut", "src", "render-cut.mjs");
+  const module = await import(pathToFileURL(modulePath).href);
+  return {
+    findChromePath: options.findChromePath ?? module.findChromePath,
+    describeChromeNotFound: options.describeChromeNotFound ?? module.describeChromeNotFound,
+  };
+}

package/src/cli.mjs

@@ -23,6 +23,8 @@ import {
 } from './update-check.mjs';
 import { applySelfUpdate, isRunningFromAppDir, rollbackSelfUpdate } from './self-update.mjs';
 import { runChromeCommand } from './chrome-command.mjs';
+import { runCaptureCommand } from './capture-command.mjs';
+import { runMediaCommand } from './media-command.mjs';
 import { resolveRuntimePaths } from './runtime-diagnostics.mjs';
 
 /**
@@ -36,6 +38,8 @@ import { resolveRuntimePaths } from './runtime-diagnostics.mjs';
  */
 export async function run(args, options = {}) {
   if (args[0] === 'chrome') return runChromeCommand(args.slice(1), options);
+  if (args[0] === 'capture') return runCaptureCommand(args.slice(1), options);
+  if (args[0] === 'media') return runMediaCommand(args.slice(1), options);
 
   const log = options.log ?? ((line) => console.log(line));
   const assets = options.assets ?? resolveLauncherAssets();

package/src/media-command.mjs

@@ -0,0 +1,17 @@
+import { spawnSync } from "node:child_process";
+
+import { resolveLauncherAssets } from "./repo-assets.mjs";
+
+export async function runMediaCommand(args, options = {}) {
+  const logError = options.logError ?? ((line) => console.error(line));
+  const assets = options.assets ?? resolveLauncherAssets();
+  const spawn = options.spawn ?? spawnSync;
+  if (!assets.mediaScript) {
+    logError("akari media の実行スクリプトが見つかりません。完全な AKARI Video を再導入してください:");
+    logError("  npm install -g akari-video");
+    return { exitCode: 1 };
+  }
+  const result = spawn(process.execPath, [assets.mediaScript, ...args], { stdio: "inherit" });
+  return { exitCode: typeof result?.status === "number" ? result.status : 1 };
+}
+

package/src/migrate-command.mjs

@@ -39,7 +39,15 @@ export async function runMigrateCommand(args, options = {}) {
     // captions.json の不在・読み取り失敗・壊れた JSON は cue なしとして移行を続ける。
   }
   const hasCaptions = migrate.captionsHaveRenderableCues(captionsRoot);
-  const proposal = migrate.planMigration(projectRoot, editPath, text, { hasCaptions, now: options.now });
+  let editVersion;
+  try {
+    editVersion = migrate.detectEditVersion(JSON.parse(text));
+  } catch {
+    // JSON error の文言は従来どおり planMigration に一元化する。
+  }
+  const proposal = editVersion === 2
+    ? migrate.planV2Normalization(projectRoot, editPath, text, { now: options.now })
+    : migrate.planMigration(projectRoot, editPath, text, { hasCaptions, now: options.now });
   if (proposal.ok === false) {
     if (parsed.json) {
       log(JSON.stringify({ ok: false, error: 'このプロジェクトは変換できません', blockers: proposal.blockers }));
@@ -49,13 +57,18 @@ export async function runMigrateCommand(args, options = {}) {
     }
     return { exitCode: 2 };
   }
+  if (proposal.noop === true) {
+    if (parsed.json) log(JSON.stringify({ ok: true, noop: true, version: proposal.version }));
+    else log('変換の必要はありません。');
+    return { exitCode: 0, proposal };
+  }
   if (parsed.json) {
     log(JSON.stringify({
       ok: true, dryRun: parsed.dryRun, version: proposal.version,
       filePath: proposal.filePath, backupPath: proposal.backupPath, changes: proposal.changes
     }));
   } else {
-    log(`変換対象: ${proposal.filePath} (version ${proposal.version} -> 2)`);
+    log(`変換対象: ${proposal.filePath} (version ${proposal.version}${proposal.version === 2 ? ' 正規化' : ' -> 2'})`);
     for (const change of proposal.changes) log(`- ${change.path}: ${change.note}`);
     log(`変換前の退避先: ${proposal.backupPath}`);
   }
@@ -78,7 +91,11 @@ export async function runMigrateCommand(args, options = {}) {
     }
   }
   await migrate.applyMigration(proposal);
-  if (!parsed.json) log(`version 2 へ変換しました。元ファイル: ${proposal.backupPath}`);
+  if (!parsed.json) {
+    log(proposal.version === 2
+      ? `version 2 を正規化しました。元ファイル: ${proposal.backupPath}`
+      : `version 2 へ変換しました。元ファイル: ${proposal.backupPath}`);
+  }
   return { exitCode: 0, proposal };
 }
 
@@ -121,7 +138,7 @@ export function migrateHelp() {
   return [
     '使い方: akari migrate [dir] [--yes] [--dry-run] [--json]',
     '',
-    'v0/v1 の edit.json を v2 へ片道変換します。',
+    'v0/v1 の edit.json を v2 へ片道変換し、v2 は正規形へ移行します。',
     '既定は変更内容を表示して y/n で確認し、変換前の全文を .akari/backup/ へ退避します。',
     '',
     '  --yes, -y   表示後の確認を省略',

package/src/repo-assets.mjs

@@ -33,6 +33,7 @@ const AUDIO_FETCH_SCRIPT_RELATIVE = path.join('packages', 'audio-library-setup',
 const ASSET_RESOLVER_CLI_RELATIVE = path.join('packages', 'asset-resolver', 'bin', 'akari-assets.mjs');
 const BEATMAP_SCRIPT_RELATIVE = path.join('packages', 'akari-tools', 'bin', 'beatmap.mjs');
 const PROBE_FRAME_SCRIPT_RELATIVE = path.join('packages', 'akari-tools', 'bin', 'probe-frame.mjs');
+const CAPTURE_SCRIPT_RELATIVE = path.join('packages', 'akari-tools', 'bin', 'capture.mjs');
 const RENDER_WHEN_IDLE_SCRIPT_RELATIVE = path.join('packages', 'akari-tools', 'bin', 'render-when-idle.sh');
 const EYE_BAR_SCRIPT_RELATIVE = path.join('packages', 'akari-tools', 'bin', 'eye-bar.mjs');
 
@@ -53,6 +54,7 @@ export function resolveRepoAssets(repoRoot = DEFAULT_REPO_ROOT_CANDIDATE) {
   const probeFrameScript = path.join(repoRoot, PROBE_FRAME_SCRIPT_RELATIVE);
   const renderWhenIdleScript = path.join(repoRoot, RENDER_WHEN_IDLE_SCRIPT_RELATIVE);
   const eyeBarScript = path.join(repoRoot, EYE_BAR_SCRIPT_RELATIVE);
+  const mediaScript = path.join(repoRoot, 'packages', 'akari-tools', 'bin', 'media.mjs');
 
   return {
     repoRoot,
@@ -66,24 +68,43 @@ export function resolveRepoAssets(repoRoot = DEFAULT_REPO_ROOT_CANDIDATE) {
     assetResolverCliPath: existsSync(assetResolverCliPath) ? assetResolverCliPath : null,
     beatmapScript: existsSync(beatmapScript) ? beatmapScript : null,
     probeFrameScript: existsSync(probeFrameScript) ? probeFrameScript : null,
+    captureScript: existsSync(path.join(repoRoot, CAPTURE_SCRIPT_RELATIVE)) ? path.join(repoRoot, CAPTURE_SCRIPT_RELATIVE) : null,
     renderWhenIdleScript: existsSync(renderWhenIdleScript) ? renderWhenIdleScript : null,
-    eyeBarScript: existsSync(eyeBarScript) ? eyeBarScript : null
+    eyeBarScript: existsSync(eyeBarScript) ? eyeBarScript : null,
+    mediaScript: existsSync(mediaScript) ? mediaScript : null
   };
 }
 
 /**
- * ランチャー実行時の同梱物解決: モノレポ checkout（開発時）→ vendor/（npm 配布時）の
- * 順で探し、最初に何かしら見つかったルートを採用する。テストからは candidateRoot /
- * vendorRoot を注入して両分岐を実ディレクトリ無しで検証できる。
+ * ランチャー実行時の同梱物解決: 資産ごとにモノレポ checkout（開発時）→ vendor/
+ * （npm 配布時）の順で探す。checkout が一部の資産しか持たないパッケージ構成でも、
+ * 欠けたフィールドだけを vendor から補完する。
  */
 export function resolveLauncherAssets({
   candidateRoot = DEFAULT_REPO_ROOT_CANDIDATE,
   vendorRoot = DEFAULT_VENDOR_ROOT
 } = {}) {
-  const checkout = resolveRepoAssets(candidateRoot);
-  const found = checkout.skillsSourceDir || checkout.templateDir || checkout.schemasSourceDir
-    || checkout.doctorScript || checkout.scaffoldModulePath || checkout.creatorRootModulePath
-    || checkout.beatmapScript || checkout.probeFrameScript || checkout.renderWhenIdleScript
-    || checkout.eyeBarScript;
-  return found ? checkout : resolveRepoAssets(vendorRoot);
+  const candidate = resolveRepoAssets(candidateRoot);
+  const vendor = resolveRepoAssets(vendorRoot);
+  const candidateHasAssets = Object.entries(candidate)
+    .some(([key, value]) => key !== 'repoRoot' && value !== null);
+
+  return {
+    repoRoot: candidateHasAssets ? candidateRoot : vendorRoot,
+    skillsSourceDir: candidate.skillsSourceDir ?? vendor.skillsSourceDir,
+    templateDir: candidate.templateDir ?? vendor.templateDir,
+    schemasSourceDir: candidate.schemasSourceDir ?? vendor.schemasSourceDir,
+    doctorScript: candidate.doctorScript ?? vendor.doctorScript,
+    scaffoldModulePath: candidate.scaffoldModulePath ?? vendor.scaffoldModulePath,
+    creatorRootModulePath: candidate.creatorRootModulePath ?? vendor.creatorRootModulePath,
+    audioFetchScriptPath: candidate.audioFetchScriptPath ?? vendor.audioFetchScriptPath,
+    assetResolverCliPath: candidate.assetResolverCliPath ?? vendor.assetResolverCliPath,
+    beatmapScript: candidate.beatmapScript ?? vendor.beatmapScript,
+    probeFrameScript: candidate.probeFrameScript ?? vendor.probeFrameScript,
+    // 既存の部分資産 fixture に capture marker が無いため、未解決時だけキー自体を省く。
+    ...(candidate.captureScript ?? vendor.captureScript ? { captureScript: candidate.captureScript ?? vendor.captureScript } : {}),
+    renderWhenIdleScript: candidate.renderWhenIdleScript ?? vendor.renderWhenIdleScript,
+    eyeBarScript: candidate.eyeBarScript ?? vendor.eyeBarScript,
+    mediaScript: candidate.mediaScript ?? vendor.mediaScript
+  };
 }

package/src/runtime-diagnostics.mjs

@@ -164,9 +164,6 @@ export async function resolveDoctorReport(options = {}) {
 
 export async function resolveGpuExportAvailability(options = {}) {
   const platform = options.platform ?? process.platform;
-  if (platform !== 'darwin') {
-    return { available: false, reason: 'GPU hardware export v0 is available on macOS only', launcher_tier: null };
-  }
   try {
     const resolver = options.resolveGpuLauncher
       ?? (await import('../../gpu-export/src/runner.mjs')).resolveGpuLauncher;

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

@@ -31,6 +31,7 @@
     "docs/contract-2026-08-03-cut-candidate-bridge-v1.md",
     "docs/contract-2026-08-03-status-integrity-v1.md",
     "docs/contract-2026-08-05-fx-v0.md",
+    "docs/contract-2026-08-09-transform-keyframes-v0.md",
     "docs/contract-2026-08-11-analysis-vision-tracks-v0.md",
     "docs/contract-2026-08-11-review-session-ui-events.md",
     "docs/contract-2026-08-12-chat-approval-v0.md",
@@ -46,9 +47,14 @@
     "docs/contract-2026-08-28-osr-export-v0.md",
     "docs/contract-2026-08-28-v2-approximation-ledger.md",
     "docs/contract-2026-08-28-v2-audio-roles-v0.md",
+    "docs/contract-2026-08-29-capture-v0.md",
+    "docs/contract-2026-08-29-media-inspect-cli-v0.md",
+    "docs/contract-2026-08-30-edit-json-v2-object-tree-v0.md",
+    "docs/contract-2026-08-30-motion-and-keyframes-v0.md",
     "packages/akari-launcher/package.json",
     "packages/akari-launcher/README.md",
     "packages/akari-tools/package.json",
+    "packages/akari-tools/README.md",
     "packages/analysis-report/package.json",
     "packages/analysis-report/README.md",
     "packages/asset-resolver/package.json",
@@ -66,6 +72,7 @@
     "packages/edit-lint/package.json",
     "packages/edit-lint/README.md",
     "packages/edit-store/package.json",
+    "packages/edit-store/README.md",
     "packages/export-nle/package.json",
     "packages/frame-engine/package.json",
     "packages/frame-engine/README.ja.md",
@@ -117,6 +124,8 @@
     "skills/compile-review-session/dev-fixtures/README.md",
     "skills/compile-review-session/SKILL.md",
     "skills/create-project/SKILL.md",
+    "skills/critique-cut/SKILL.md",
+    "skills/critique-cut/workflow.md",
     "skills/declare-audio/after-save.md",
     "skills/declare-audio/launch.md",
     "skills/declare-audio/SKILL.md",

package/vendor/docs/contract-2026-07-18-edit-json-v1-sources.md

@@ -42,6 +42,12 @@
 | `cuts[].src` | v1 では必須。`sources[].id` を参照する |
 | `cuts[].in`, `cuts[].out` | 対象ソースの秒。`0 <= in < out` を満たす |
 
+`sources[].proxy` の生成規格は [プレビュー用プロキシの規格](./contract-2026-08-02-preview-parity.md#55-プレビュー用プロキシの規格) に従う。
+
+v2 プレビューでは `sources[].proxy` は任意の最適化である。宣言されていれば既定でそれを使い、
+起動を速くする。宣言が無ければ `VideoDecoder.isConfigSupported` で器の実力を調べ、原本を直接読む。
+器が原本を扱えない場合は preview-server が同じプロキシ規格で自動生成する。
+
 参照は path ではなく安定した `id` で行う。これにより素材の差し替えや path 変更で cut や
 サイドカーの参照が壊れない。JSON Schema は将来の任意フィールドを許容する tolerant reader とし、
 既知フィールドの型、version ごとの必須形、`source` / `sources[]` の排他を検証する。
@@ -76,6 +82,7 @@ source 秒アンカー規則の対象外である。
 - `review.json` の `annotations[]` は任意フィールド `src` を持てる。値は `sources[].id` への参照で、
   `sourceT` または `sourceRange` と組にして source 座標を表す
 - `src` の省略は単一ソース互換を意味する
+- 字幕の重なり（`captions.overlap`）と並び順（`captions.order`）の判定は `src` ごとに行う
 
 analysis サイドカーは素材単位のままとし、構造は変更しない。参照時に `src` から source path を
 解決する。

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

@@ -40,7 +40,7 @@
    素の色のまま合成されて、窓の継ぎ目で肌色が食い違った。「プロジェクト全体の色」だと
    誤解しやすいため、ここに明記する。
 4. **書き出しエンジンの既定（2026-08-28 改訂）**: `--engine` 省略時は `auto`。
-   darwin では v2（OSR）、win32 / linux では legacy に解決する。従来経路へ戻す場合は
+   darwin / win32 では適格なら GPU、不適格なら OSR、linux では legacy に解決する。従来経路へ戻す場合は
    `render-cut --engine legacy` を明示する。
 
 ### 2-4. reveal 系トランジション（`reveal-down` / `reveal-up`。2026-08-14 追加）
@@ -168,3 +168,11 @@ x264、その他の環境で x264 の順に解決する。ハードウェア対
 誤判定を避けるため 256x144 で試し焼きし、`AKARI_EXPORT_FORCE_X264=1` のときは試し焼きせず
 すべて不採用とする。明示指定した Windows 向け方式が利用不能なら x264 へ暗黙移行せず停止する。
 `AKARI_EXPORT_FORCE_X264=1` のときに Windows 向け方式を明示指定した場合も、同じく停止する。
+
+## 7. v2 書き出しの cut 中間物（2026-08-29 追記）
+
+OSR / GPU の v2 書き出しでは、映像エンジンが `edit.sources` から直接描画するため、cut 段と
+tail-pad 段は音声専用中間物だけを生成する。通常は `cut-audio.mp4`、最終尺までの音声 padding が
+必要な場合は `cut-audio-tail-padded.mp4` を使用し、どちらも `-vn` で映像を処理しない。
+legacy 書き出しは従来どおり `cut.mp4` と必要時の `cut-tail-padded.mp4` を使用する。
+音声入力は cut ごとに入力側シーク（`-ss` / `-t`）し、cut 頭 0.5 s の先読みガード（AAC の overlap-add 用）を設け、cut 段の費用を素材長に依存させない。

package/vendor/docs/contract-2026-07-25-project-structure-v0.md

@@ -149,3 +149,15 @@ updated: 2026-08-26
 - スキーマ変更（`edit.json` 等の既存契約ファイル形は不変）
 - 「paths 宣言」（プロジェクトごとの置き場所カスタマイズ UI）の導入
 - ルート直下 `cache/`（レガシー）の最終的な扱いの裁定（§3・§6）
+
+## 8. 追記（2026-08-30）— `motion/` を正本ディレクトリとして登録
+
+`contract-2026-08-30-edit-json-v2-object-tree-v0.md` / `contract-2026-08-30-motion-and-keyframes-v0.md` により、
+プロジェクト直下に **`motion/`** を追加する。
+
+| 用途 | 置き場 | 作成者 | 性質 |
+|---|---|---|---|
+| キーフレーム曲線の袋（`motion/<group-id>.json`。edit.json の `keyframes: { path, count }` から参照）| `motion/` | edit-store（保存時に inline から振り分け）| **正本**（再生成不可。`.akari/cache/` ではない）|
+
+- edit.json / captions.json と同じトランザクションで保存され、同じ lint ゲートを通る
+- §2 の「ルート直下への新規ファイル作成は正本ファイルに限る」の例外ではなく、正本ファイルの追加である

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

@@ -10,6 +10,7 @@
 |---|---|---|
 | 2026-08-02 | v0 | Web UI と shell の挙動仕様を統合 |
 | 2026-08-28 | v2 | `packages/frame-engine` の意味論へ統合し、検収をゴールデンフレームへ一本化。出口を OSR と GPU 直結の 2 本に固定し、互換経路を退役節へ移動 |
+| 2026-08-31 | v2.1 | §5.2 に断片 CSS の `vw` / `vh` 系単位の出力サイズ基準化（`viewport-units.js`。プレビューがウィンドウ幅基準で解いていた実機報告の修正）を追記 |
 
 ## 1. 役割分担
 
@@ -195,6 +196,7 @@ SHA-256 一致を要求する。GPU は同一マシン一致率を診断値と
 | GPU 直結・engine 区間 | OSR decode 比較の per-frame MAD ≤ 1.0 | 超過は不合格 |
 | GPU 直結・字幕 | cue 代表 5 時刻の下半分 MAD ≤ 1.0 | 超過は不合格 |
 | GPU 直結・3D | 3D active 区間 MAD ≤ 1.0 | 超過は不合格 |
+| GPU 直結・DOM 層 | overlay 外接矩形内 MAD ≤ 1.0、t=0 を含む代表 5 時刻 | いずれかの超過または sentinel 不一致は不合格 |
 
 OSR の比較は H.264 を再 decode した画像ではなく捕捉時の raw BGRA を使う。ソフト描画の検収と GPU の
 診断値を混同しない。
@@ -241,6 +243,14 @@ legacy 合成経路は、移行中の既存利用者と Windows を支えるた
 `edit.json` のあるディレクトリからの相対ファイルパスとして解決する。`vars` は `--` で始まるキーだけを
 CSS カスタムプロパティとして overlay root へ適用し、それ以外のキーは DOM や JavaScript へ注入しない。
 
+断片 CSS の `vw` / `vh` / `vmin` / `vmax`（`dvw` 等の接頭辞付き・`vi` / `vb` 含む）は**出力サイズ基準**で
+解決する（`1vw` = `output.width / 100` px）。書き出しは出力サイズちょうどの viewport で overlay sheet を
+描くので素のままで正しいが、器のプレビューはステージを `scale()` でペインへ収めるため素の `vw` は
+ウィンドウ幅基準になってしまう。器は mount 時に `packages/overlay-runtime/src/viewport-units.js` で
+`<style>` / `style=""` の `<数値><単位>` を `calc(<数値> * var(--akari-vw, 1vw))` へ書き換え、ステージ要素に
+`--akari-vw` 等（出力サイズ / 100 px）を定義して一致させる（2026-08-31。shell / Web 共通。`@media` 等の
+プレリュード・文字列・`url()` は書き換えない）。
+
 ### 5.3 書き込み経路
 
 UI、API、RPC の別を問わず、`edit.json` / `captions.json` へのすべての書き込みは edit-lint ゲートを通す。
@@ -253,3 +263,55 @@ lint 実行系が見つからない場合は **fail-open**（2026-08-02 オー
 ペン描画の単一正本は `packages/pen-visuals` の `PEN_TUNING` と描画プリミティブである。器や overlay
 sheet が独自の補間、太さ、透明度、消去規則を持ってはならない。フェード時間は **600ms** を正とする
 （2026-08-02 オーナー裁定）。
+
+### 5.5 プレビュー用プロキシの規格
+
+frame-engine がランダムアクセスするプレビュー用プロキシは、H.264 High Profile の 8bit
+`yuv420p`、GOP 1 秒以下、B フレームなし、faststart とする。GOP はソースの実測 fps を丸めた
+フレーム数を使い、`-g <fps> -keyint_min <fps> -sc_threshold 0 -bf 0` を指定する。変換後も尺と
+コマ数はソースと一致させる。
+29.97 fps の GOP は 30 コマで 1.001 秒になるため、doctor / lint などで機械照合するときの閾値は 1.05 秒に置く。
+
+生成経路は shell の HEVC フォールバックと preview-server の HEVC プロキシの 2 系統であり、
+いずれも `packages/media-bin/src/proxy-recipe.mjs` を唯一の定義として使う。レシピ版
+`gop1s-v1` は shell のキャッシュキーと preview-server の出力名へ含め、旧規格のキャッシュを
+次回参照時に再利用しない。
+
+### 5.6 読み込み予算と原本 / proxy の選択規則
+
+frame-engine のソース読み込み予算は、`Content-Length` が得られる場合
+`max(10 秒, bytes / 8 MiB毎秒)` とする。予算を超えても受信進捗が続く間は打ち切らず、進捗が
+5 秒間止まった場合に失敗とする。同一 URL の fetch はセッションにつき 1 回に限り、再試行では
+取得済みバイトと解析済み moov / キーフレーム索引を再利用する。
+
+v2 プレビューの既定選択は次の順序とする。
+
+1. 宣言済み proxy があれば proxy を使う（`declared`）
+2. proxy が無ければ codec をプローブし、`hw || any` で扱える場合は原本を使う
+   （`hardware-ok` / `decoder-ok`）
+3. 扱えない場合は preview-server に自動プロキシを要求し、生成中は非致命の通知を表示する
+   （`auto-proxy`）
+
+Web UI の `?frameEngineSource=original`、または shell の
+`AKARI_FRAME_ENGINE_SOURCE=original` では 1 を飛ばして器の実力判定へ進む。`=proxy` では従来どおり
+proxy を無条件に優先する。
+`AKARI_FRAME_ENGINE_FORCE_SW=1` はハードウェアデコード不可を模擬するテスト用スイッチである。
+HEVC は `prefer-software` が通らないため、codec プローブが `sw=false` を返した系列について
+ClipSessionPool はソフトウェア退避を学習しない。ソフトウェア退避の学習対象は H.264 のみとする。
+
+tkhd に 90 / 180 / 270 度の回転を持つ素材は、既定でデコーダ出力を毎フレームの
+OffscreenCanvas へ焼き直さない。frame-engine は回転メタをフレームへ付帯し、compositor の
+UV 逆写像で表示回転を 1 回だけ適用する。crop、framing、keyframe、既存 transform / perspective は
+回転後の論理空間を基準とし、90 / 270 度では coded width / height を入れ替えた論理寸法を使う。
+この規則は VideoFrame の直接 upload と copyTo の両経路に共通である。
+
+デコーダエラーは window 全域イベントで飛ぶため、他クリップの失敗と区別できない。frame-engine は
+検出後 `decoderErrorGraceMs`（既定 1 秒）だけ自分の操作の成功を待ち、期限内に成功した場合はその
+エラーを無視する。prime がフレームを返さず、かつエラーを観測した場合だけ、その試行を失敗とする。
+
+### 5.7 映像ソースの読み方とパリティ
+
+frame-engine が MP4 を全体ストリームとして読むか、`ftyp` / `moov` の索引と必要な圧縮サンプルの
+Range として読むかは、完成画の意味論に影響しない。どちらの読み込み経路も同じ presentation 時刻の
+VideoFrame を §4.1 の評価点へ供給し、`elst.media_time`、B フレームの並べ替え、メディア終端を含めて
+golden の `diff 0` を満たさなければならない。ソース取得方法の変更をパリティ差の許容理由にしてはならない。

package/vendor/docs/contract-2026-08-09-transform-keyframes-v0.md

@@ -0,0 +1,35 @@
+---
+lifecycle: implemented
+created: 2026-08-09
+updated: 2026-08-30
+---
+
+# 変形キーフレーム契約 v0（`layers[].keyframes` / v2 `items[].keyframes`）— 2026-08-30 復元
+
+> **復元の注記（2026-08-30）**: 本契約は `packages/schemas/edit.schema.json`（`layerKeyframe` / `layerItem` / `keyframeV2` の `$comment`）・
+> `packages/schemas/bin/validate-edit.mjs`・`packages/render-cut/src/layer-keyframes.mjs` ほか 10 箇所から参照されていたが、
+> 実ファイルがどのブランチの履歴にも存在しなかった。スキーマの `$comment` に残っていた意味論からそのまま再構成した。
+> **後継 = `contract-2026-08-30-motion-and-keyframes-v0.md` §2**（opacity の追加・easing 語彙の拡張・`motion/` 袋への参照形）。
+> 本ファイルは v0 の意味論の記録であり、これ以上追記しない。
+
+- 日付: 2026-08-09（実装済み・`contract-2026-07-22-render-basics.md` §4-4 に要約あり）
+- 状態: implemented（v1 `layers[].keyframes`・v2 `items[].keyframes` の両方で有効）
+
+## 1. 意味論
+
+- `keyframes[]` はレイヤー / アイテムの `transform` / `crop` / `perspective` を時間で動かす共通機構
+- `t` は**ローカル時間**: v1 `layers[].keyframes[].t` はレイヤー内秒（`layerItem.t` を 0 とする。`cuts[].framing.keyframes[].t` と同じ規約）、
+  v2 `items[].keyframes[].t` は**アイテム内の整数フレーム**（`item.at` を 0 とする）
+- `transform` / `crop` / `perspective` はそれぞれ**独立の任意プロパティ**（プロパティごとの別トラックにはしない — 1 点で複数プロパティを同時に動かせる）
+- ある区間の両端点が同じプロパティを持てばその間は**線形補間**。片方の端点にしか無ければ直近の宣言値を**保持（hold）**
+- どの点にも一度も宣言されないプロパティは、レイヤー / アイテム直下の**静的値**（省略時は各 `$def` の既定値）を全区間で保持する
+- `easing` は点ごとに設定し、**その点へ入る区間**（1 つ前の点からこの点まで）の補間カーブを決める。先頭点の `easing` は無視。省略時 `linear`。語彙は `linear` / `ease-in-out`
+- 2 点以上・`t` 昇順・重複禁止（`validate-edit.mjs` で検証）。`keyframes` が無い、または使える点が 2 点未満のときは既存の静的値のみが効く（回帰なし・バイト等価）
+- render-cut は cuts 合成後のベース映像へ `t` 順に合成する。プレビューは同じ補間を CSS / WebGL で再現する（`contract-2026-08-02-preview-parity.md`）
+
+## 2. 参照元（復元時点）
+
+`packages/schemas/edit.schema.json` / `packages/schemas/bin/validate-edit.mjs` / `packages/render-cut/src/layer-keyframes.mjs` / `packages/render-cut/src/layers.mjs` /
+`packages/render-cut/test/layer-keyframes.test.mjs` / `packages/preview-server/test/layer-keyframes-visual.test.mjs` /
+`apps/shell/extensions/akari-preview/src/common/edit-summary-fields.ts` / `apps/shell/extensions/akari-preview/src/common/layer-keyframes-visual.ts` /
+`apps/shell/extensions/akari-preview/src/browser/akari-preview-open-handler.ts` とそのテスト

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

@@ -23,6 +23,12 @@ updated: 2026-08-12
   - `contract-2026-07-17-data-contract-versioning.md`（version 整数・追加のみ・寛容リーダーの三原則）
 - スコープ: `edit.json` の `cuts[]` がメイン時間軸で静止画ソース（png/jpg/jpeg/webp/bmp/gif）を
   直接読めるようにする。**新しいスキーマフィールドは作らない**（判定は拡張子のみ）
+- 2026-08-31 追記（issue #30）: frame-engine 経路（`--engine gpu` / `osr`、および v2 プレビュー）でも同じ
+  意味論で描く。runtime が拡張子で `CachedStillImageSource` として登録した素材を、`plan.ts` が
+  `kind: 'image'` の base 層（`sourceTimeUs` は常に 0・尺は `out - in`・transform / crop / keyframes は
+  動画 cut と同じ・トランジションの outgoing / incoming にもなれる）として評価し、compositor は
+  layers と同じ texture cache を base の RGBA 経路へ結ぶ。それまでは `layerFromPlacement` が
+  `decode` 持ちしか受けず `no video frame source registered` で落ちていた（legacy との受理差）
 
 ## 0. 背景
 

package/vendor/docs/contract-2026-08-23-captions-emphasis-words-v0.md

@@ -74,3 +74,4 @@
 比較できない `t_end > t_start` と、配列内の `id` 一意性は `validate-captions.mjs` が検査する。
 語と `captions[].words[]` の実測値の突き合わせは v1 契約と同じく書き手の規律であり、静的検証では
 行わない。
+edit-lint は object ルートの `emphasis_words` を受理し、同じ規則で検証する。