akari-video 0.1.22 → 0.1.24

package/README.md

@@ -52,6 +52,20 @@ DL・sha256 検証・適用まで実行。それ以外（npm グローバル / g
 `packages/asset-resolver` の CLI への薄い委譲で、カタログ合成・entitlements 判定・
 sha256 検証・fail-closed は resolver 側の責務のまま。`src/assets-command.mjs`）。
 
+### Chrome の導入
+
+動画の書き出しに使う Chrome for Testing は、次のコマンドで導入できる。
+
+```sh
+akari chrome install
+akari chrome install --cache-dir /path/to/cache
+akari chrome install --build-id 150.0.7339.16
+```
+
+保存先の既定は `~/.cache/puppeteer`。`--cache-dir` で保存先、`--build-id` で導入する
+buildId を指定できる。実行環境から `@puppeteer/browsers` を解決できる必要があり、
+AKARI Video アプリの配布物には必要なモジュールが同梱されている。
+
 `akari` に渡した引数はそのまま `opencode` に転送する（例: `akari --continue` は
 `opencode --continue` を起動する）。
 

package/package.json

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

@@ -0,0 +1,96 @@
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const usage = [
+  '使い方: akari chrome install [options]',
+  '',
+  'オプション:',
+  '  --cache-dir <dir>  Chrome の保存先（既定: ~/.cache/puppeteer）',
+  '  --build-id <id>    導入する Chrome の buildId（既定: stable の最新版）',
+  '  -h, --help         このヘルプを表示',
+].join('\n');
+
+class PublicError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}
+
+function parseInstallArguments(argv, homeDirectory) {
+  const parsed = {
+    cacheDir: join(homeDirectory, '.cache', 'puppeteer'),
+    buildId: undefined,
+  };
+  for (let index = 1; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument !== '--cache-dir' && argument !== '--build-id') {
+      throw new PublicError(`不明な引数です: ${argument}`, 2);
+    }
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith('--')) {
+      throw new PublicError(`${argument} の値がありません`, 2);
+    }
+    index += 1;
+    if (argument === '--cache-dir') parsed.cacheDir = resolve(value);
+    else parsed.buildId = value;
+  }
+  return parsed;
+}
+
+export async function runChromeCommand(argv, options = {}) {
+  const log = options.log ?? ((line) => console.log(line));
+  const error = options.error ?? ((line) => console.error(line));
+  const loadBrowsers = options.loadBrowsers ?? (() => import('@puppeteer/browsers'));
+  const homeDirectory = options.homeDirectory ?? homedir();
+
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h'
+      || (argv[0] === 'install' && (argv.includes('--help') || argv.includes('-h')))) {
+    log(usage);
+    return { exitCode: 0 };
+  }
+  if (argv[0] !== 'install') {
+    error(`不明なサブコマンドです: ${argv[0]}\n${usage}`);
+    return { exitCode: 2 };
+  }
+
+  let parsed;
+  try {
+    parsed = parseInstallArguments(argv, homeDirectory);
+  } catch (cause) {
+    error(`${cause instanceof Error ? cause.message : String(cause)}\n${usage}`);
+    return { exitCode: cause instanceof PublicError ? cause.exitCode : 1 };
+  }
+
+  let browsers;
+  try {
+    browsers = await loadBrowsers();
+  } catch (cause) {
+    error([
+      `@puppeteer/browsers を読み込めないため Chrome を導入できません: ${cause instanceof Error ? cause.message : String(cause)}`,
+      'システムの node がある場合は `npx puppeteer browsers install chrome` でも導入できます。',
+    ].join('\n'));
+    return { exitCode: 1 };
+  }
+
+  try {
+    const platform = browsers.detectBrowserPlatform();
+    const buildId = parsed.buildId
+      ?? await browsers.resolveBuildId('chrome', platform, 'stable');
+    const installed = await browsers.install({
+      browser: 'chrome',
+      buildId,
+      cacheDir: parsed.cacheDir,
+      downloadProgressCallback: 'default',
+    });
+    if (typeof installed?.executablePath !== 'string' || installed.executablePath.length === 0) {
+      throw new Error('導入後の実行ファイルを特定できませんでした。');
+    }
+    log(`buildId: ${buildId}`);
+    log(`実行ファイル: ${resolve(installed.executablePath)}`);
+    return { exitCode: 0 };
+  } catch (cause) {
+    error(`Chrome の導入に失敗しました: ${cause instanceof Error ? cause.message : String(cause)}`);
+    return { exitCode: 1 };
+  }
+}

package/src/cli.mjs

@@ -22,6 +22,7 @@ import {
   triggerBackgroundRefresh
 } from './update-check.mjs';
 import { applySelfUpdate, isRunningFromAppDir, rollbackSelfUpdate } from './self-update.mjs';
+import { runChromeCommand } from './chrome-command.mjs';
 
 /**
  * `akari` ランチャーの本体。3 入口契約（ターミナル `akari` / セッション内 `/akari` /
@@ -33,6 +34,8 @@ import { applySelfUpdate, isRunningFromAppDir, rollbackSelfUpdate } from './self
  * options 経由で差し替え可能にしてあり、node --test から実プロセスを起動せずに分岐を検証できる。
  */
 export async function run(args, options = {}) {
+  if (args[0] === 'chrome') return runChromeCommand(args.slice(1), options);
+
   const log = options.log ?? ((line) => console.log(line));
   const assets = options.assets ?? resolveLauncherAssets();
   const scaffold = options.scaffold ?? defaultScaffold;

package/src/messages.mjs

@@ -303,6 +303,7 @@ export function describeCliHelp() {
     '  (引数なし)              プロジェクトを開いて AI エージェントを起動（未作成なら自動作成）',
     '  store connect          アカウント連携（無料の素材パックと購入済み素材が使えるようになる）',
     '  sounds                 公式音源ライブラリを一括ダウンロード（無料）',
+    '  chrome install         動画書き出しに使う Chrome をダウンロードして導入する',
     '  update [--force]       更新を確認する（--force で本体を入れ直す）',
     '  status                 接続状態を確認する',
     '  migrate [dir]          古い edit.json を退避バックアップ付きで v2 へ変換',

package/src/migrate-command.mjs

@@ -22,15 +22,24 @@ export async function runMigrateCommand(args, options = {}) {
   }
   const projectRoot = parsed.projectRoot;
   const editPath = path.join(projectRoot, 'edit.json');
+  const captionsPath = path.join(projectRoot, 'captions.json');
+  const readText = options.readFile ?? readFile;
   let text;
   try {
-    text = await (options.readFile ?? readFile)(editPath, 'utf8');
+    text = await readText(editPath, 'utf8');
   } catch (cause) {
     error(`edit.json を読めません: ${editPath} (${messageOf(cause)})`);
     return { exitCode: 2 };
   }
   const migrate = options.migrate ?? loadMigrateModule(options.assets ?? resolveLauncherAssets());
-  const proposal = migrate.planMigration(projectRoot, editPath, text, { now: options.now });
+  let captionsRoot;
+  try {
+    captionsRoot = JSON.parse(await readText(captionsPath, 'utf8'));
+  } catch {
+    // captions.json の不在・読み取り失敗・壊れた JSON は cue なしとして移行を続ける。
+  }
+  const hasCaptions = migrate.captionsHaveRenderableCues(captionsRoot);
+  const proposal = 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 }));

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

@@ -42,6 +42,8 @@
     "docs/contract-2026-08-18-v1-render-parity.md",
     "docs/contract-2026-08-23-captions-emphasis-words-v0.md",
     "docs/contract-2026-08-23-stroke-persistence.md",
+    "docs/contract-2026-08-28-osr-export-v0.md",
+    "docs/contract-2026-08-28-v2-audio-roles-v0.md",
     "packages/akari-launcher/package.json",
     "packages/akari-launcher/README.md",
     "packages/akari-tools/package.json",
@@ -57,13 +59,21 @@
     "packages/creator-root/package.json",
     "packages/decision-cards/package.json",
     "packages/decision-cards/README.md",
+    "packages/decision-log-report/package.json",
+    "packages/decision-log-report/README.md",
     "packages/edit-lint/package.json",
+    "packages/edit-lint/README.md",
     "packages/edit-store/package.json",
     "packages/export-nle/package.json",
+    "packages/frame-engine/package.json",
+    "packages/frame-engine/README.ja.md",
+    "packages/frame-engine/README.md",
     "packages/intake-form/package.json",
     "packages/intake-form/README.md",
     "packages/matte-rvm/package.json",
     "packages/media-bin/package.json",
+    "packages/osr-export/package.json",
+    "packages/osr-export/README.md",
     "packages/overlay-runtime/package.json",
     "packages/overlay-runtime/README.md",
     "packages/pen-visuals/package.json",

package/vendor/docs/contract-2026-07-20-edit-json-v1-narration.md

@@ -39,6 +39,8 @@
         "id": "n-0001",                  // 必須。^n-\d{4}$。edit.json 内で一意
         "path": "out/narration/n-0001.mp3",  // 必須。edit.json からの相対パス
         "t": 12.5,                       // 必須。タイムライン秒。0 以上
+        "in": 5.8,                       // 任意。素材秒。省略時 0
+        "out": 9.7,                      // 任意。素材秒。省略時 素材末尾
         "gain_db": 0,                    // 任意。既定 0。[-60, 12]（bgm/sfx と同一。範囲外はエラー）
         "script": "こんにちは、AKARI Videoです。",   // 任意。表示原稿（人間が読む正本）
         "reading": "こんにちわ、あかりびでおです。", // 任意。読み原稿（かな化後・生成に使った実テキスト）
@@ -63,6 +65,8 @@
 | `audio.narration[].id` | string | 必須（要素内） | — | `^n-\d{4}$`。edit.json 内で一意 |
 | `audio.narration[].path` | string | 必須（要素内） | — | edit.json からの相対（`audio.sfx[].path` と同一規約） |
 | `audio.narration[].t` | number | 必須（要素内） | — | **タイムライン秒**（`audio.sfx[].t` / `overlays[].start` と同じ座標系）。0 以上 |
+| `audio.narration[].in` | number | 否 | `0` | 素材秒。再生窓 `[in, out)` の始点。0 以上 |
+| `audio.narration[].out` | number | 否 | 素材末尾 | 素材秒。再生窓 `[in, out)` の終点。0 より大きく `out > in` |
 | `audio.narration[].gain_db` | number | 否 | `0.0` | dB。クランプ範囲 `[-60, 12]`（`audio.bgm` / `audio.sfx` と同一） |
 | `audio.narration[].script` | string | 否 | — | 表示原稿（人間が読む正本。字幕連携等の元テキスト） |
 | `audio.narration[].reading` | string | 否 | — | 読み原稿（かな化後・TTS 生成に実際に使ったテキスト） |
@@ -79,6 +83,14 @@
 （ナレーションも `t` という 1 点情報を持つシーン単位の演出であり、BGM のような
 「プロジェクト全体で 1 本」という制約は当てはまらない）。
 
+### 1.1 ナレーション素材のトリム
+
+`in` / `out` は `audio.sfx[]` と同じ素材秒の語彙を使う。再生区間は `[in, out)`、タイムライン上の
+開始は従来どおり `t` とする。`in` 省略時は 0、`out` 省略時は素材末尾まで再生する。
+`out <= in` は edit-lint が error とし、実尺との整合は render-cut が解決する。`in` が素材実尺以上なら
+0 にクランプして warning、`out` が素材実尺を超えれば素材末尾へクランプして warning、クランプ後に
+`out <= in` となる場合はその narration 要素だけを skip して warning とする。
+
 ## 2. パス解決規約
 
 `audio.narration[].path` は `audio.bgm.path` / `audio.sfx[].path` と**同一規約**:

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

@@ -144,3 +144,24 @@ perspective のレイヤー分割フォールバック — perspective は `crop
 - Chrome 不在、`.app` でない実行ファイル、`DevToolsActivePort` 待機または接続の失敗は、
   「字幕レンダ用ブラウザの起動に失敗した」ことと Chrome の確認を日本語で示し、書き出しを
   非 0 で停止する。別スタイルの簡易字幕へは切り替えない。
+
+## 6. H.264 エンコーダ選択（2026-08-28 追記）
+
+`--encoder` の語彙は `auto` / `videotoolbox` / `nvenc` / `qsv` / `amf` / `mf` / `x264` とする。
+`master` 品質は x264 専用であり、ハードウェアエンコーダを明示した場合は拒否する。
+
+| 値 | ffmpeg エンコーダ | 対応環境・品質制御 |
+|---|---|---|
+| `videotoolbox` | `h264_videotoolbox` | macOS。ビットレート制御 |
+| `nvenc` | `h264_nvenc` | Windows / NVIDIA。VBR + CQ |
+| `qsv` | `h264_qsv` | Windows / Intel。global quality |
+| `amf` | `h264_amf` | Windows / AMD。CQP |
+| `mf` | `h264_mf` | Windows Media Foundation。quality 0..100 |
+| `x264` | `libx264` | 全環境。CRF |
+
+`auto` は macOS で VideoToolbox → x264、Windows で NVENC → QSV → AMF → Media Foundation →
+x264、その他の環境で x264 の順に解決する。ハードウェア対応は `ffmpeg -encoders` の一覧だけで
+決めず、実際の1フレーム試し焼きにも成功した場合だけ採用する。Windows 向け4方式は最小解像度の
+誤判定を避けるため 256x144 で試し焼きし、`AKARI_EXPORT_FORCE_X264=1` のときは試し焼きせず
+すべて不採用とする。明示指定した Windows 向け方式が利用不能なら x264 へ暗黙移行せず停止する。
+`AKARI_EXPORT_FORCE_X264=1` のときに Windows 向け方式を明示指定した場合も、同じく停止する。

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

@@ -1,6 +1,7 @@
 # analysis.json v0 人物マット（tracks.person_matte）データ契約
 
 - 日付: 2026-07-23
+- 改訂: 2026-08-27（§8 の format 席を開き mask_path / mask_format を追加）
 - 状態: 実装ラウンドの SSOT（`tracks.person_matte` の値のみ確定）
 - 前提: `contract-2026-07-17-data-contract-versioning.md`（版必須・追加のみ進化・明示マイグレの三原則）、
   `contract-2026-07-13-m5-analysis-report.md`（`analysis.json` v0 の器と `tracks` の枠。
@@ -56,6 +57,8 @@
 
     "person_matte": {                        // null（未生成）/ string（旧形）も有効
       "path": "matte/person-matte.webm",     // 必須。VP9 alpha WebM への相対 or 絶対パス
+      "mask_path": "matte/person-matte.mask.mp4", // 任意。追加のグレースケール H.264 マスク
+      "mask_format": "gray-h264-fullrange", // 任意。mask_path の形式
       "fps": 24,                             // 必須。マット動画の fps（元素材と異なってよい）
       "quality": "balanced",                 // 任意。fast / balanced / accurate / best を例示（enum 強制はしない）
       "generated_at": "2026-07-23T01:33:30.069Z",  // 任意。ISO8601
@@ -218,6 +221,7 @@ ffmpeg / ffprobe は OS の PATH 名を直接起動せず、`packages/media-bin`
 |---|---|
 | `packages/schemas/analysis.schema.json` | `$defs/personMatteTrack` として object 形の構造（`path` / `fps` の必須・型・範囲、`additionalProperties: false`）を定義し、`tracks.person_matte` から `null` / string / object の `oneOf` として参照する |
 | 生成ヘルパー（`bin/person-matte/person-matte.mjs`） | 書き出した WebM が `codec_name = vp9` かつコンテナタグ `alpha_mode = 1` であることを ffprobe で確認してから成功を返す。アルファが落ちた出力を成功扱いにしない。タグキーの大文字小文字は書き込み経路によって変わりうるため、照合は大文字小文字非依存で行う |
+| 追加マスク（`mask_path`） | `codec_name = h264`、`color_range = pc`、幅・高さ・`r_frame_rate`・`nb_frames` が VP9 alpha WebM と一致し、`start_pts = 0` であることを ffprobe で確認する |
 | `skills/analyze-footage/analysis-json.md` の意味制約 | JSON Schema で表せない条件（`path` が解決でき実ファイルがある、マット動画の時刻 0 が素材の時刻 0 と一致する、`fps` がマット動画の実 fps と一致する）を確定前に人が検査する |
 
 **`analysis.json` 専用の検証 CLI は本契約では新設しない。** `packages/schemas/bin/` には
@@ -242,6 +246,27 @@ JSON として読めるかまでしか見ていない（`analysis.schema` チェ
 いずれも別契約で扱う。本契約は `tracks.person_matte` の器だけを確定し、これらの席が将来開く
 可能性があることを記録するに留める。
 
+### 8.1 `mask_path` / `mask_format`（2026-08-27 追加）
+
+§8 の `format` の席を、VP9 alpha WebM を置換しない追加出力として開く。`path` が指す VP9 alpha
+WebM の生成と既存消費は不変であり、`mask_path` は v2 frame-engine がハードウェアデコード可能な
+グレースケールマスクを使うための追加物である。
+
+| 項目 | 規格 |
+|---|---|
+| コンテナ / codec / profile | mp4 / H.264（`libx264`）/ High |
+| 画素 | `yuv420p`、Y = アルファ（0 = 透明、255 = 不透明）、U/V = 128 |
+| レンジ・色タグ | full range（`color_range=pc`）、BT.709 primaries / transfer / colorspace |
+| GOP・品質 | GOP 1 秒以下、`crf 6`、`preset medium`、B frame なし |
+| 時間 | 解像度・fps・尺・フレーム数はカラー元と一致し、先頭 PTS は 0 |
+| 命名 | `<VP9 alpha WebM の basename>.mask.mp4` |
+
+`mask_format` の現行値は `"gray-h264-fullrange"` とする。`mask_path` の相対パスは `path` と同じく
+**analysis.json の所在ディレクトリ**を基準に解決し、区切りは `/` を使う。
+
+`mask_path` が無い、または解決・検証できない場合、消費側は `path` の VP9 alpha WebM から一度だけ
+同規格のマスクへ取り込み変換する。それも失敗した場合は人物演出を諦め、映像本体の処理は止めない。
+
 ## 9. 既知の追随事項（本契約が作る宿題）
 
 - **`packages/analysis-report`** の軽量チェックは `tracks.person_matte` を「string か null」に
@@ -249,6 +274,7 @@ JSON として読めるかまでしか見ていない（`analysis.schema` チェ
   本タスクのファイル境界外のため未修正。object 形を実運用へ載せる前に、この読み手を
   `oneOf` へ追随させる必要がある（表示側の「人物マット: あり / なし」の判定も
   `tracks.person_matte` の真偽値で動くため、object 形でもそのまま「あり」になる）
+  - `packages/analysis-report` は object 形と `quality` / マスク併産の表示へ追随済み（2026-08-28）
 - **`<video>` の時刻同期が未実装**である（`packages/overlay-runtime`）。したがって
   「動く人物の text-behind-person」は本契約が整っても**まだ本番品質ではない**。
   マットが取れることと、それを本番の合成として出せることは別である

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

@@ -1,3 +1,9 @@
+---
+lifecycle: draft
+created: 2026-07-25
+updated: 2026-08-26
+---
+
 # project-structure-v0（生成物の置き場所）契約
 
 - 日付: 2026-07-25
@@ -60,6 +66,17 @@
   3 ファイル以外の生成物は、性質に応じて §1 の層へ振り分ける（具体例は §4）
 - 新しいトップレベル契約ファイルを追加する場合（将来の話）は、本契約の改訂を通す
 
+#### 2026-08-26 追記: ルート直下の判断記録・分析レポート
+
+- `decision-log.md` は analyze-project と edit-plan が共同追記する判断履歴の単一 SSOT であり、
+  プロジェクトルート直下の正当な契約ファイルとする（根拠:
+  `skills/edit-plan/report-guide.md` の `decision_log` 節）
+- `analysis-report.html` は analyze-project が生成し edit-plan が読む正式な分析レポートであり、
+  プロジェクトルート直下の正当な契約ファイルとする（根拠:
+  `skills/edit-plan/workflow.md` §1）
+- この追記は上記 2 ファイルを §2-1 の許可リストへ追加するものであり、その他のファイルに
+  ルート直下配置を許可しない
+
 ### 2-2. 削除安全の定義
 
 `.akari/work/` と `.akari/cache/` は**再生成可能・削除安全**と定義する。

package/vendor/docs/contract-2026-07-25-r6-audio-tracks-and-trim.md

@@ -31,6 +31,8 @@
 - `sfxItem` に optional `in` / `out` を追加（**素材秒**。`in` ≥ 0 省略時 0、
   `out` > `in` 省略時 素材末尾）。再生区間 = 素材の [in, out)、
   タイムライン上の開始は従来どおり `t`（timeline 秒）、表示尺 = out − in
+- `narrationItem` にも同じ optional `in` / `out` を追加する。再生区間・素材秒・既定値・
+  `out > in` の検証分担は sfx と同一で、タイムライン上の開始は narration の `t` とする
 - `bgm` に optional `in` を追加（BGM ファイル内の開始オフセット素材秒。ループ・全体尺
   トリムの既存意味論は不変）
 - edit-lint: `out <= in` を error。実尺越えの検知は lint では行わない
@@ -40,6 +42,12 @@
 ### 消費（render-cut + preview）
 
 - render-cut: sfx の [in, out) 切り出しを出力に反映。bgm の `in` オフセット反映
+- render-cut: narration の [in, out) 切り出しも出力に反映する。`in` が素材実尺以上なら 0 へ、
+  `out` が素材実尺を超えれば素材末尾へクランプして warning を出す。クランプ後に `out <= in` なら
+  その narration 要素だけを skip する。`in` / `out` の有無にかかわらず、各 narration 要素は
+  デコード可否の判定を兼ねて実尺を従来と同じ 1 回だけ probe し、デコードできなければ従来どおり
+  その要素だけを skip して warning を出す一方、両方省略された要素には `atrim` を前置きせず、
+  従来とバイト同一のフィルタ文字列を保つ
 - preview（previewAudio）: 同意味論で再生。実尺越え in/out は素材末尾へクランプ
 
 ### UI

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

@@ -581,3 +581,42 @@ ffmpeg の `perspective` フィルタの制約（式に時刻変数を持たな
 段階計画・差分マップの正本: 内部リポ `planning/notes-2026-08-01-webui-shell-convergence.md`。
 Phase 2 以降（共有カーネル抽出: edit-store / ペン / タイムライン写像 / overlay-runtime 一本化）は
 本契約への適合を保ったまま実装を共通化する。
+
+### 4.1 `packages/preview-engine` の処遇 — **凍結**（2026-08-27 裁定・実行済み）
+
+WebCodecs ベースの `packages/preview-engine` は、Web UI からも shell からも import されない
+死蔵コードだった（`packages/preview-server` が `public/preview-engine.bundle.js` へバンドル・
+配信していたが、`index.html` / `app.js` に読み込み口が無い）。本契約の 3 面
+（render-cut / Web UI / shell）のどれにも属さない 4 つ目の実装であり、パリティの対象外である
+ことを明記したうえで**凍結**する。
+
+- **実行済み**: preview-server の `build` から esbuild 行を削除・追跡されていた
+  `public/preview-engine.bundle.js` を削除・`test/server.spec.mjs` の配信スモークを削除。
+  以後 `npm run build` の成果物に preview-engine 由来のファイルは含まれない
+- **削除はしない**: 合成エンジンを 1 個へ統一する「エンジン v2」路線（WebCodecs +
+  GPU コンポジタ）の土台候補として資産価値を実査済みであり、再利用 / 新規の裁定は
+  エンジン v2 のゲート（Phase 0 スパイクの実測と併せて裁定）に委ねる。
+  詳細と復活手順は `packages/preview-engine/README.md` 冒頭の凍結ノートを正とする
+- **凍結中の規律**: 本パッケージへ追随改修を新たに入れない。スキーマや語彙が増えても
+  preview-engine 側の追随は不要（誰も実行しないため、追随は保守錯覚にしかならない）
+
+### 4.2 ducking（BGM の narration ダッキング）の実装本数と正本
+
+§2.5 が定める「narration 再生区間で BGM -12dB」は、**プレビュー側に 3 実装ある**:
+
+| 面 | 実装 | 位置づけ |
+|---|---|---|
+| Web UI | `packages/preview-server/public/app.js`（`hasNarration` / `duckDb`） | 稼働中 |
+| shell | `apps/shell/extensions/akari-preview/src/browser/akari-preview-open-handler.ts`（`duckGainDbAt`） | 稼働中 |
+| preview-engine | `packages/preview-engine/src/duckingGain.ts`（純関数 + `node --test`） | **凍結（§4.1）** |
+
+- **現時点で 3 者は数値的に同値**（2026-08-27 実測: 0〜10s を 10ms 刻み × `ducking` on/off の
+  2,002 点で不一致 0）。したがって本契約 §2.5 への適合は 3 面とも保たれている
+- **-12dB 固定は正（render-cut）とは挙動の違う近似である**。render-cut は
+  `sidechaincompress=threshold=0.063:ratio=8:attack=5:release=300` で、減衰量は narration の
+  実レベルに依存し attack 5ms / release 300ms の時間応答を持つ。プレビュー 3 実装は
+  「区間内なら常に -12dB・立ち上がり/戻りは瞬時」であり、**§2.4 系と同じ宣言済みの近似**として扱う
+- **正本の一本化は未了**（稼働中 2 実装の書き換えを伴うため別タスク）。一本化先は共有カーネル
+  `packages/edit-store`（`computeDuckIntervals` / `computeBgmDuckGainDb` 相当を昇格し、
+  shell は直接 import・Web UI は `edit-kernel.bundle.js` 経由で消費）。それまでは
+  **どれか 1 面の -12dB や区間規則を単独で変えないこと**（3 面同時に変えるか、一本化を先に済ませる）

package/vendor/docs/contract-2026-08-28-osr-export-v0.md

@@ -0,0 +1,119 @@
+# ページ全体 OSR 書き出し v0 契約
+
+## 1. 適用範囲
+
+この契約は `render-cut --engine osr` が生成する映像ページと、そのページを Electron オフスクリーン描画で駆動するプロトコルを定める。既定の engine は `legacy` であり、OSR は opt-in とする。
+
+## 2. ページ契約
+
+ページは出力幅 `W`、映像高 `H` に検証用1行を加えた `W × (H + 1)` で構成する。映像領域の重ね順は下から次の4層である。
+
+1. frame-engine canvas。cuts、layers、transition、matte、LUTを評価する。
+2. `captions.json` から生成したDOM字幕。
+3. `edit.json` の自由HTML。
+4. 自由HTML内のThree.js canvas。
+
+字幕、自由HTML、3Dは render-cut と同じ overlay sheet 生成器により、透明な同一オリジン iframe として canvas 上へ置く。無効なトラックは最初からDOMへ入れず、活性区間ごとのDOM再構築は行わない。
+
+ページは次のAPIを公開する。
+
+- `window.__akariReady`: フォント、画像、動画、3D、frame-engineのprime完了を表すPromise。
+- `window.__akariSeek(seconds, frameNumber)`: frame-engine評価、overlay sheetのシーク、スタンプ更新、2回の`requestAnimationFrame`待機を順に完了する。
+- `window.__akariSettle()`: 検証不一致時に2回の`requestAnimationFrame`を進める。
+
+CSS animationはpauseし、`currentTime`を合成時刻へ設定する。Three.jsは対象区間のローカル時刻で描画する。動画要素は提示フレームの確定まで待つ。`frameNumber`はmainから明示的に渡し、秒から再計算しない。
+
+## 3. スタンプ行
+
+最下1行はフレーム番号 `n mod 65536` を次で符号化する。
+
+```text
+R = n & 255
+G = (n >> 8) & 255
+B = 0x55
+A = 255
+```
+
+BGRA bitmapでは `[0x55, G, R, 255]` となる。左端、中央、右端の3画素を復号し、期待番号との全点一致を要求する。確認後、ffmpegへ渡す前に `buffer.subarray(0, W * H * 4)` で最下行を除く。
+
+`--verify stamp|hash|off` を持ち、既定は `stamp` とする。`hash` は直前の映像領域と同じSHA-256ならsettle後に再取得し、静止画で上限へ達した場合は曖昧件数を記録して受理する。`off` は比較計測用である。通常書き出しではverifyを無効にしない。
+
+## 4. 駆動プロトコル
+
+各コマは次の順で処理する。
+
+```text
+seek → ready → invalidate → paint → verify → write
+```
+
+`paint`が既定10秒以内に届かなければ失敗として記録する。bitmapは必ず `W × (H + 1)` と照合する。不一致時はsettleして再度`invalidate`し、最大8回で停止する。
+
+映像領域のBGRAは深さ3を既定とするbounded queueへ渡す。ffmpeg stdinの`write()`がfalseなら必ず`drain`を待つ。無制限のpre-bufferは禁止する。v0は先頭から末尾まで連番1 workerで評価する。
+
+`run.json` はseek、paint、toBitmap、verify、writeのp50/p95、1000コマ区切りmedian、先頭と末尾のdriftRatio、paint timeout、verify retry、verify前delta histogram、backpressure、メモリ、ffprobe結果を記録する。
+
+## 5. LUT
+
+`output.look` のLUTはframe-engine canvas内のsampler3Dで適用する。ページ全体へCSS filterを掛けない。したがって字幕、自由HTML、3DはLUTの外にあり、映像canvasだけが色変換の対象となる。
+
+## 6. Electronの器
+
+起動は次の3段で解決する。
+
+1. インストール済みAKARI VideoのElectron実行体を`--render`付きで再利用する。
+2. npm optionalDependencyの`electron`を使う。`dist`のライセンス2ファイル、version、プラットフォーム実行体が揃うことを検査する。
+3. Electronが無ければ警告を出し、現行render-cut経路へフォールバックする。
+
+第1段・第2段とも、実プロセスのコマンドラインに`--force-device-scale-factor=1`、`--force-color-profile=srgb`、background throttling無効化スイッチを渡す。npm Electronではスクリプトパスを`argv[1]`に保ち、その後へChromiumスイッチを置く。ソフト描画時は加えてGPU無効化とSwiftShaderスイッチを渡す。
+
+パッケージ版のTheiaではelectron-main contributionが`--render`を捕捉する。contribution開始は初期ウィンドウ表示とbackend起動の後なので、v0ではスプラッシュが一瞬表示され得る。通常起動で`--render`が無い場合、contributionは何もしない。
+
+Linux v0は第3段を使用する。将来の差し替え席として、Chrome headlessと`HeadlessExperimental.beginFrame`を使うlauncherを第1段と第2段の間へ追加できるものとする。この契約では実装しない。
+
+## 7. エンコード、音声、照合
+
+ffmpeg入力は `-f rawvideo -pixel_format bgra -video_size WxH -framerate fps -i -` とする。品質とエンコーダはrender-cutの`master|high|standard|light`および`auto|videotoolbox|x264`を使用する。映像は1世代だけH.264へ圧縮し、その後の音声処理とmuxでは映像をcopyする。
+
+ffprobe timeoutは `max(120000, frames × 100)` msとする。尺、フレーム数、解像度をplanと照合する。
+
+## 8. メモリと長尺
+
+- GPU描画の警戒線: 768 MiB / export、hard stop: 1,024 MiB / export。
+- ソフト描画（SwiftShader）は1080pで1.1 GiB台に達するため、警戒線1,536 MiB / hard stop 2,048 MiBの別枠を使う。
+- `AKARI_OSR_MEMORY_WARN_MIB` / `AKARI_OSR_MEMORY_HARD_STOP_MIB`で正の整数MiBへ上書きでき、適用値はwarning < hard stopを必須とする。
+- 並列予算1 worker = 1 GiBはGPU前提の値である。v0のworker数は1。
+- 10秒ごとにRSSを記録し、ウィンドウ破棄後も採る。
+- 固定Nコマごとのページ再生成は行わない。再生成を許すのはページ境界、renderer crash、watchdog回復時だけである。
+
+非連番seekは描画履歴が変わり得るため、チャンク分割・並列化はbyte再現モードと両立しない。将来導入する場合は先頭からのwarm-up履歴または完成画の別検収を必要とする。
+
+## 9. 検収
+
+CIはソフト描画の連番2走について全コマSHA-256一致を要求する。製品はGPUを既定とし、同一マシン2走の一致率、`differingPixels`、`maxDelta`を診断値として記録する。GPUのbyte-exactは合否条件にしない。差分調査はH.264を再デコードした画像ではなく、捕捉時のraw BGRAを使用する。
+
+legacyとの比較は字幕、自由HTML、3Dの各指定時刻についてMADと`differingPixels`を記録する。
+
+## 10. 使用しない中間規律
+
+OSR経路では次を使用しない。
+
+- アルファ付き中間動画。
+- PNG連番。
+- ffmpeg overlay。
+- 二重の映像エンコード。
+- 3Dの別キャプチャ。
+- 字幕の活性区間ごとのDOM再構築。
+- 静止コマの重複除去。
+- 固定Nコマごとのページ再生成。
+
+## 11. 既知の限界
+
+### 11.1 Bフレーム素材の並べ替え遅延
+
+負のDTSで始まるBフレーム素材では、エンジンのデコード経路が並べ替え遅延ぶん手前のコマを返す。`has_b_frames=2`の1920×1080 / 30fps素材では、先頭コマだけが一致し、その後は一定2コマ手前になることを実測した。同一素材を`-bf 0`で生成するとlegacyと完全に一致する。v0はこのずれを補正しない。
+
+### 11.2 legacyとの全画面画素差
+
+同じraw BGRAを比較した場合、ffmpegが未タグ素材へ既定で使うbt601換算に対してMAD 9.28 / maxDelta 155、bt709換算に対してMAD 0.886であった。残差はクロマ補間による。エンジンは`bt709-limited`で合成する。
+
+ベースを単色にしたfixtureでlegacyとOSRの最終MP4を比較すると、MAD 0.019〜0.345 / maxDelta 7〜78であった。字幕・自由HTML・3Dの描画は一致し、全画面差の主因はベース映像のYUV→RGB変換である。オーバーレイ層の突き合わせは単色ベースで行う。