akari-video 0.1.26 → 0.1.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "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,46 @@
+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) {
+    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 };
+}
+
+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/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

@@ -46,9 +46,12 @@
     "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",
     "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",

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

@@ -42,6 +42,8 @@
 | `cuts[].src` | v1 では必須。`sources[].id` を参照する |
 | `cuts[].in`, `cuts[].out` | 対象ソースの秒。`0 <= in < out` を満たす |
 
+`sources[].proxy` の生成規格は [プレビュー用プロキシの規格](./contract-2026-08-02-preview-parity.md#55-プレビュー用プロキシの規格) に従う。
+
 参照は path ではなく安定した `id` で行う。これにより素材の差し替えや path 変更で cut や
 サイドカーの参照が壊れない。JSON Schema は将来の任意フィールドを許容する tolerant reader とし、
 既知フィールドの型、version ごとの必須形、`source` / `sources[]` の排他を検証する。
@@ -76,6 +78,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-08-02-preview-parity.md

@@ -195,6 +195,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 の
 診断値を混同しない。
@@ -253,3 +254,16 @@ 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 の出力名へ含め、旧規格のキャッシュを
+次回参照時に再利用しない。

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` を受理し、同じ規則で検証する。

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

@@ -16,7 +16,7 @@
 
 | 分類 | 適格 | 意味 |
 |---|---|---|
-| `same` | はい | 静的 HTML または対応済み字幕。起動時に 1 回だけスプライト化する |
+| `same` | はい | 静的 HTML は起動時、対応済み字幕は unit の初回活性時に 1 回だけスプライト化する |
 | `three` | はい | JSON の宣言型 3D scene と描画先 canvas を持つ overlay。毎コマ Three.js canvas を更新する |
 | `degraded` | いいえ | raster 自体は可能でも live DOM と同じ時間変化を保証できない |
 | `unsupported` | いいえ | v0 の表現範囲外であり、正しい完成画を生成できない |
@@ -27,14 +27,68 @@ CSS animation/transition/keyframes、filter/mask/clip-path 等を検出する。
 `<script type="application/json" data-akari-3d-scene>` 宣言を属性順にかかわらずちょうど 1 個持ち、
 それ以外の script と video を持たない宣言型 3D は `three` とする。3D の描画先である canvas は許可する。
 
-字幕は cue ごとに 1 回 rasterize し、出現・loop・消失を解析的な opacity と中心基準 affine 変換で
-再現する。次は v0 で `unsupported` とする。
+字幕は cue ごとに rasterize し、出現・loop・消失を解析的な opacity と中心基準 affine 変換で
+再現する。v2 では `words[]` を持つ karaoke、pop、reveal、reveal-word と `emphasis_words` も
+語矩形タイルとして GPU-native に合成する。次は引き続き `unsupported` とする。
 
-- `words[]` を持つ karaoke、pop、reveal、reveal-word 等の語単位表示。
-- `emphasis_words`。
+- 同一 unit に karaoke の色補間と、pop / one-char-bang / one-char-jumble / size-pulse の幾何変形が混在するもの。
+- 語矩形タイルで再現できない縦書きの語単位字幕。
 - 未知の motion、および clip-path を使う push/typewriter/wipe/glitch。
 - `transform-origin: top center` を必要とする swing。
 
+### 2.1 語単位字幕（v2）
+
+語単位字幕の意味論は `packages/render-cut/src/captions.mjs` が生成する DOM と CSS を正本とする。
+GPU 出口はその DOM を別実装で組み直さず、同じ DOM から `getClientRects()` で各語の矩形を採寸する。
+1 語が改行をまたいで複数矩形を返す場合は全矩形を保持する。縦長出力で style 無指定かつ
+`words[]` があり複数行になる cue は、正本と同じ行分割関数で reveal へ自動昇格する。
+採寸は独立した DOM root の挿入ごとに行い、全 variant の全測定値が 2 回連続で厳密一致するまで
+測り直す。上限は 32 回とし、収束しなければ `caption-measure-unstable` を理由コードと warning に残して
+fail-closed とする。HW で max 6、soft で max 7 だった実測に対する余裕として 32 回を採る。
+許容差、平均、丸めによって走間の揺らぎを隠さない。
+
+| 対象 | 毎コマの状態 |
+|---|---|
+| karaoke | 語の start まで基本色、start〜end は語全体の色を linear 補間、end 以後は highlight 色 |
+| pop | start から 0.2 秒、語矩形中心で `translateY(0→-0.08em→0)` と `scale(1→1.12→1)` |
+| reveal-word | start から 0.01 秒で opacity 0→1 |
+| reveal | 行群を 0/12/99.99/100% の opacity・translateY keyframe で順送りし、前群は終了時に消す |
+| one-char-bang / one-char-jumble | 文字ごとに opacity 0→1、scale 1.6→1。jumble の静的変形はラスタへ保持 |
+| size-pulse | 語矩形中心で scale 1→1.25→1 |
+| 色・太さ・縁取りだけの emphasis | 静的な基本ラスタへ焼き込み、毎コマの状態評価はしない |
+
+karaoke は左から右へのワイプではない。正本の keyframes は `color` の from/to だけなので、基本色と
+highlight 色の 2 ラスタを語タイル内で時間比率により mix する。CSS timing function は keyframe 区間ごとに
+適用し、pop と size-pulse の 0〜50% / 50〜100% をそれぞれ ease してから補間する。
+
+ラスタ単位を unit と呼ぶ。通常は cue 1 個、reveal は重なった `.akari-caption__reveal-group` 1 個を
+unit 1 個とする。unit ごとのラスタは最大 2 枚で、色モードは基本色 / highlight 色、幾何モードは
+プレート背景 / 透明背景の文字、状態なしは基本 1 枚だけを持つ。2 状態 DOM の全語矩形は各成分差
+0.01 px 以下であることを起動時に検査し、超過は fail-closed とする。ラスタは unit ごとに 1 回だけ作り、毎コマは
+行ストリップと語境界でフレームを隙間なく分割した整数タイルを配列順に合成する。3 枚目や毎コマ rasterize は行わない。
+
+ラスタ SVG はフレーム全面ではなく、出力幅を維持した字幕帯だけの `viewBox` を持つ。開始時刻順の
+連続する最大 8 unit、かつ全バンド高 4096 px 以下を 1 バッチとし、各 unit の 1〜2 状態を縦方向の
+バンドとして 1 枚の SVG に積み、デコードはバッチにつき 1 回だけ行う。variant CSS は
+`data-akari-band` ごとにスコープし、埋め込みフォントの `@font-face` は SVG 内に 1 本だけ置く。
+初めて必要になった unit のバッチをまとめて登録する一方、GPU texture は活性区間の終了時に unit ごとに
+解放し、バッチのために寿命を延ばさない。upload 後の切り出し用 CPU canvas とデコード画像も破棄する。
+
+SVG の入力は data URL に固定する。Blob URL と同一オリジン HTTP URL は SVG 内フォントを含む canvas を
+汚染し、`getImageData` だけでなく `texImage2D(canvas)` も `SecurityError` になるため使用しない。
+フォント data URL は `encodeURIComponent` 済みの文字列を 1 度だけ作って再利用し、生の base64 を
+キャッシュしない。
+
+適格な cue は理由 `words-native` とし、receipt に `mode`（`sprite` / `words-native`）、style、unit 数、
+語数、ラスタ枚数、バンド数、タイル数と `captionLayoutMaxDeltaPx`、採寸試行の count / p50 / max、
+バッチ実測、字幕ラスタ合計時間を記録する。未知 style は
+`caption-style-unsupported:<value>`、色と幾何の混在は `words-native-color-and-geometry-mixed` とする。
+
+検収は style 5 種 × 各 5 時刻について GPU / OSR decode の画面下 1/4 MAD 1.0 以下、語境界の対比画像
+6 枚以内の目視、語状態評価と合成の追加コスト中央値 1 ms/コマ以下、hardware / software の指定 fixture
+2 走一致、製品経路の読み戻し 0 を要求する。性能 gate は cue ラスタ p50 500 ms 以下、karaoke 44 cue の
+akari-video-pv 18 ms/コマ以下、小 fixture（360 コマ・3 cue）の RSS peak 900 MB 以下とする。
+
 `--engine auto` は macOS で全件適格なら `gpu`、不適格なら `osr` を選ぶ。他 OS の `auto` は従来の
 選択を維持する。明示 `--engine gpu` と不適格の組み合わせは理由を全件表示して fail-closed とし、
 黙って OSR へ変更しない。GPU launcher が利用できない明示指定も fail-closed とする。
@@ -67,7 +121,8 @@ raw frame 読み戻しではない。
 
 映像は H.264 `avc1.640028`、2 秒ごとの keyframe とし、製品は hardware preference、
 `--soft` は software preference を指定する。ビットレートは render-cut の quality プリセットにある
-VideoToolbox 値を正本とし、`high = 12 Mbps`、`standard = 8 Mbps`、`light = 5 Mbps` とする。
+GPU ビットレート値（mac では VideoToolbox 用の値と共用）を正本とし、`high = 12 Mbps`、
+`standard = 8 Mbps`、`light = 5 Mbps` とする。
 `--bitrate` の明示値は quality より優先する。`master` は VideoToolbox ビットレートを宣言しないため、
 GPU 出口では `--bitrate` が無ければ理由付きで fail-closed にする。
 
@@ -108,6 +163,10 @@ GPU と OSR の decode 比較は、engine-only 区間の per-frame MAD 1.0 以
     "video_reencode": false
   },
   "gpu": {
+    "platform": "win32",
+    "chromium": "140.0.0.0",
+    "renderer": { "vendor": "NVIDIA Corporation", "renderer": "ANGLE (NVIDIA GeForce RTX)" },
+    "encoder_support": { "prefer-hardware": true, "prefer-software": false },
     "encoder": "WebCodecsH264Encoder",
     "hardware": "prefer-hardware",
     "uploadPath": "direct",
@@ -125,10 +184,151 @@ GPU と OSR の decode 比較は、engine-only 区間の per-frame MAD 1.0 以
 OSR receipt と同じ warning/hard-stop 語彙を使う。`--engine osr` と `--engine gpu` は receipt 以外の
 最終成果物パス・命名と `.akari/render.json` の置き場を共有する。
 
-## 8. v0 の限界
+`gpu.platform` と `gpu.chromium` は Electron main process の実行環境、`gpu.renderer` は renderer process
+で `WEBGL_debug_renderer_info` から取得した vendor / renderer（取得不能なら `null`）を記録する。
+`gpu.encoder_support` は製品と同じ H.264 config の `hardwareAcceleration` だけを差し替えた
+`prefer-hardware` / `prefer-software` の対応可否を記録し、取得不能なら `null` とする。WebCodecs は
+実際に使われた encoder 実装を露出しないため、「hardware encoder が使われた」という主張は
+`encoder_support` と書き出し速度を組み合わせて裏取りする。
+
+## 8. v0 / v2 の限界
 
-- karaoke、語単位 style、`emphasis_words` は GPU-native glyph/word texture 実装まで非対応。
+- 語矩形で表せない演出、色補間と幾何変形が同居する cue、縦書きの語単位字幕は glyph atlas 等の次段が必要。
 - 動的自由 HTML は OSR または事前ベイクが必要。
-- Windows の hardware H.264 encoder は v0 の提供対象外。
+- Windows / Linux は launcher tier 1 / 2 があれば `--engine gpu` 明示で利用できる。`auto` の GPU 候補は
+  macOS のみとし、Windows の既定切替は実機実測後の別契約で扱う。
 - 長尺の区間並列、複数 process 並列は非対応。
-- **インストール済みデスクトップアプリ経由（launcher tier 1）の GPU 書き出しは未配線**（v0.1.25 で判明）。shell の `--render` は OSR ランタイムしか読まず、`buildElectronArguments` は tier 2 にしか mainScript を渡さない。v0.1.26 から `resolveGpuLauncher` は tier 1 を候補から外す（fail-closed）: `auto` は OSR へ（provenance に `engine_fallback` と理由）、`--engine gpu` 明示は拒否。tier 1 の配線（shell contribution に GPU ランタイム選択を足す）は別票。
+- ~~インストール済みデスクトップアプリ経由（launcher tier 1）の GPU 書き出しは未配線~~ **2026-08-29 解消**: shell の `electron-entry.js` が `--akari-main packages/gpu-export/src/electron-main.mjs` を受け、`buildElectronArguments` が tier 1 にそれを渡す（osr 契約 §6）。`resolveGpuLauncher` の fail-closed（allowDesktop 既定 false）は v0.1.28 で解除。以下は v0.1.26〜v0.1.27 の記録: （v0.1.25 で判明）。shell の `--render` は OSR ランタイムしか読まず、`buildElectronArguments` は tier 2 にしか mainScript を渡さない。v0.1.26 から `resolveGpuLauncher` は tier 1 を候補から外す（fail-closed）: `auto` は OSR へ（provenance に `engine_fallback` と理由）、`--engine gpu` 明示は拒否。tier 1 の配線（shell contribution に GPU ランタイム選択を足す）は別票。
+
+## 8.1 プラットフォーム
+
+| platform | `--engine gpu` | `--engine auto` | launcher |
+|---|---|---|---|
+| macOS | 明示利用可 | 適格なら GPU、不適格なら OSR | tier 1 / 2（ただし tier 1 は現状未配線で fail-closed） |
+| Windows | 明示利用可 | legacy のまま | tier 1 / 2（同上） |
+| Linux | 明示利用可 | legacy のまま | tier 1 / 2（同上） |
+
+npm Electron の tier 2 は `node_modules/electron/path.txt` を必須とする。値は win32 が
+`electron.exe`、darwin が `Electron.app/Contents/MacOS/Electron`、linux が `electron` である。
+インストール済みアプリの tier 1 を配布する場合は shell の `extraResources` に
+`packages/gpu-export` が同梱されていることを前提とする。ただし現行 tier 1 は
+`GPU_DESKTOP_TIER_UNWIRED_REASON` のとおり候補から外し、誤って OSR を GPU receipt として記録しない。
+
+## 9. v1 — HTML-in-Canvas DOM 層
+
+v1 は、CSS animation、transition、`@keyframes`、Web Animations、`@property` で時間変化する自由 HTML を
+`dom` 分類として適格化する。書き出し時だけ動的に生成した `canvas[layoutsubtree]` の子へ DOM を mount し、
+エンジン時計で元の animation を pause・seek してから `drawElementImage` で透過 2D canvas へ転写する。
+その canvas は `SpriteCompositor.updateSprite` で直接 texture 化する。Three.js canvas は従来の別 texture の
+ままとし、DOM host へ入れない。
+
+GPU 出口だけに `--enable-features=CanvasDrawElement`、`--disable-gpu-vsync`、
+`--disable-frame-rate-limit` を付け、`--force-device-scale-factor=1` を維持する。DOM ランは `overlays[]` の
+宣言順で連続する項目をまとめ、静的 HTML、3D、DOM ランを元の index 順に合成したあと、字幕を最後に載せる。
+すべて LUT の外である。
+
+次の条件は fail-closed のまま `degraded` とし、receipt に overlay id、理由、検出条件を全件残す。
+
+- `iframe`、`object`、`embed` の埋め込み context。
+- `perspective`、`preserve-3d`、`rotateX/Y/3d`、`matrix3d`、`translateZ/3d` のいずれかを含む
+  CSS 3D transform。先行実験では `translateZ` 単独・`perspective` 単独は正しく転写できたため、
+  将来はこの粒度まで緩和できる余地があるが、v1 では緩和しない。
+- `requestAnimationFrame`、`setTimeout`、`setInterval`、`Date.now`、`performance.now` で自走する時計。
+- `video`、`audio`、canvas/宣言型 3D 以外の runtime、JSON 以外の script。
+- 絶対 URL と外部 font/image/background resource。
+- `drawElementImage` が利用できない実行環境、または device pixel ratio が 1 でない環境。
+
+settle は mount 時に一度だけ決める。`canvas.requestPaint` がある Chromium では rAF 2 回の後に
+`requestPaint()` と `paint` event（上限 250 ms）を待つ。API がない Chromium では computed style、
+bounding rect、host height を同期読みして layout を確定し、直ちに転写する。採用 policy、API probe、
+DOM 層の固定・待機・転写・upload の p50/p95 は receipt の `gpu.domLayer` に記録する。
+
+`--verify-frames` では各 DOM ラン左上の 8×8 sentinel を frame number から決定論的に着色し、転写後
+texture の左上 4×4 が期待 RGB の ±8 に一致するかを毎コマ検査する。CSS `mod()` の自己検査に失敗した
+環境では JS channel 指定へ切り替え、その mode も記録する。pixel read は
+`src/verify-readback.js` に隔離した検証経路だけに許可し、製品経路の読み戻しゼロ契約は変えない。
+
+DOM 層の OSR decode 比較は overlay 外接矩形内 MAD 1.0 以下を、animation 開始時刻を含む代表 5 時刻で
+要求する。sentinel は全要求 frame 一致を必須とする。既知の限界は karaoke の word texture、CSS 3D、
+自走時計、3D scene の DOM 入場 animation、OSR/legacy に残る `@property` animation の時刻不整合である。
+
+決定論には長尺時の既知の限界がある。短い書き出し（実測 450 / 678 / 900 コマ）は 2 走の全コマ SHA と
+MP4 SHA が一致した。一方、大きな文字を持つ DOM overlay を多数含む長い書き出し（実測 5400 コマ）では、
+1 つの overlay 区間に閉じた 180 コマ前後で文字の縁のアンチエイリアスが走ごとに変わり、全コマ SHA 一致が
+確率的に崩れた（MAD 0.0001〜0.0003、差分画素 11〜41 個）。sentinel は全走一致しており 1 コマ遅れではない。
+ラスタライズ関連の起動フラグでは解消しなかった。
+
+**検収裁定（2026-08-29・司令塔）**: DOM 層を含む書き出しの HW 決定論 gate は「2 走の全コマ SHA 一致」ではなく
+**「全コマの per-frame MAD ≤ 0.001 かつ sentinel 全一致」を一致とみなす**。上記の文字縁アンチエイリアス差（最大 0.0003）は
+この範囲内であり不可視・1 コマ遅れでもないため受け入れる。DOM 層を含まない書き出し（エンジン層・静的スプライト・
+語単位字幕のみ）は従来どおり SHA 一致を要求する。
+
+（2026-08-28 v1 時点の記述）字幕 cue はページ起動時に 1 枚ずつ SVG へ焼いており、30 cue の焼き込みが
+900 コマの書き出しに約 47 秒（約 52 ms/コマ相当）を上乗せした。字幕を含む短い書き出しでは GPU 出口が
+OSR より遅く、同じ題材から字幕を外した実測は GPU 19.2 ms/コマ、OSR 40.9 ms/コマだった。
+
+2026-08-29 の #120f で、土台以外のスプライトを種別ごとのインスタンス描画へまとめた。karaoke の
+`drawArrays` は字幕の本数によらず 1 コマ 2 回で一定となり、3 cue 同時と字幕なしの追加 GPU 時間は
++23.4 ms/コマから +1.65 ms/コマへ縮小した。毎コマの字幕描画費用という限界は解消し、実素材
+`akari-video-pv`（5,999 コマ）では GPU / OSR 7.2〜8.2 倍へ到達した。
+
+残る字幕差は毎コマの合成費用ではなく、cue 採寸と SVG ラスタの起動費用である。実素材 PV の字幕ありは
+150.7 秒（25.1 ms/コマ）、字幕なし対照は 88.0 秒（14.7 ms/コマ）で 1.71 倍だった。30 cue の
+`akari-project/dynamic` では字幕ラスタが約 47 秒から 9.95 秒へ短縮したが、30 秒級の短い題材では
+起動費用の比率が大きく、GPU / OSR は 1.07〜1.14 倍にとどまる。
+
+## 10. v3 — 宣言型 3D の登場曲線
+
+v3 は、宣言型 Three.js scene のルート要素にある 1 回きりの登場 CSS animation を時刻の関数へ解析し、
+3D canvas の sprite draw state として GPU-native に合成する。Three.js 自体は従来どおり engine clock の
+local seconds を `threeRuntime.render(container, t)` へ直接渡す。scene 内部の animation、動画 texture、
+ready 判定は変更しない。
+
+`three` 分類・理由 `three-scene-entrance-curve` にできるのは、次の条件をすべて満たす overlay だけである。
+
+- `<script type="application/json" data-akari-3d-scene>` が属性順にかかわらずちょうど 1 個あり、他の
+  script がない。
+- animation を持つのは HTML のルート要素 1 個だけで、selector は
+  `[data-akari-active] .root, [data-no-timeline] .root` の対である。canvas と fallback は動かさない。
+- animation は 1 本、iteration count は 1、direction は normal、delay は 0 以上、fill mode は
+  `both` または `forwards` である。timing は `linear`、`ease`、`ease-in`、`ease-out`、`ease-in-out`、
+  または妥当な `cubic-bezier(x1,y1,x2,y2)` に限る。
+- keyframe は `from` / `to` または 0% / 100% の 2 点だけで、両端に opacity と transform がある。
+  transform は `translate()` / `translateX()` / `translateY()` / `scale()` / `scaleX()` / `scaleY()`
+  だけを使う。px 平行移動と単位なし scale に加え、`var(--name, fallback)`、
+  `calc(var(--name) + Npx)`、`calc(var(--name) * N)` を受理する。
+
+transition、`@property`、複数 animation、複数の animated element、中間 keyframe、iteration count が
+1 以外、alternate / reverse、負の delay、fill mode の欠落、未知の timing、rotate / skew / 3D transform、
+filter、clip-path、解決不能な値は不可とし、`three-entrance-*` の具体的な理由で fail-closed にする。
+animation のない従来の宣言型 3D は理由 `three-scene-canvas-direct` と manifest 形を変えない。
+
+解析時は overlay の `vars` と `transform.x / y / scale` を CSS 変数へ解決する。未定義変数の既定値は
+平行移動が 0 px、scale が 1 である。manifest の `entrance` は次の additive な形を持ち、from / to は
+変数解決後の絶対値である。
+
+```json
+{
+  "durationSec": 1.1,
+  "delaySec": 0.05,
+  "timing": { "x1": 0.16, "y1": 1, "x2": 0.3, "y2": 1 },
+  "fill": "both",
+  "from": { "opacity": 0, "tx": -380, "ty": 140, "sx": 0.817, "sy": 0.817 },
+  "to": { "opacity": 1, "tx": 0, "ty": 0, "sx": 0.95, "sy": 0.95 }
+}
+```
+
+毎コマの意味論は次式を正本とする。delay 前は from、終了後は to とし、opacity / tx / ty / sx / sy の
+すべてへ同じ eased progress を線形補間で適用する。
+
+```text
+local    = seconds - overlay.start
+progress = clamp((local - delaySec) / durationSec, 0, 1)
+eased    = timing == linear ? progress : cubicBezierAt(progress, x1, y1, x2, y2)
+value    = from + (to - from) * eased
+```
+
+`cubicBezierAt` は frame-engine の既存 export を使用する。実素材 3 種を Chrome headless の
+`getComputedStyle` と delay 前・登場中 3 点・終了後の 5 時刻で突き合わせた実測差は、translate 最大
+0.00043 px、scale 最大 0.000001、opacity 0 だった。検収閾値は translate 0.5 px 以下、opacity 0.005
+以下、3D 登場区間の GPU / OSR 外接矩形内 MAD 1.0 以下とする。

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

@@ -81,7 +81,7 @@ seek → ready → invalidate → paint → verify → write
 
 第1段・第2段とも`--user-data-dir=<run 一時ディレクトリ>/electron-user-data`を渡し、本体アプリの単一インスタンスロック（userData単位）と分離する。これによりアプリ起動中でも書き出せる。子がexit 0で終了して出力を作らなかった場合は、launcherが失敗として扱う。
 
-パッケージ版のTheiaではelectron-main contributionが`--render`を捕捉する。contribution開始は初期ウィンドウ表示とbackend起動の後なので、v0ではスプラッシュが一瞬表示され得る。通常起動で`--render`が無い場合、contributionは何もしない。
+`--render`は`package.json`の`main`（`electron-entry.js`）がTheiaより前に捕捉する。backend fork・初期ウィンドウ・contribution・単一インスタンスロックを起動せず、`--akari-main`で指定したランタイム（既定はosr-export、gpu-exportも指定可能）へ直行するため、スプラッシュは表示されない。通常起動で`--render`が無い場合は従来どおりTheiaを起動する。
 
 Linux v0は第3段を使用する。将来の差し替え席として、Chrome headlessと`HeadlessExperimental.beginFrame`を使うlauncherを第1段と第2段の間へ追加できるものとする。この契約では実装しない。
 
@@ -148,6 +148,24 @@ media time に合わせて評価するため、従来の一定 2 コマ手前に
 
 v0.1.24以前はTheiaの`singleInstance`により、AKARI Videoデスクトップアプリの起動中に第1段を開始すると、子プロセスがexit 0・無出力で終了していた。launcherが出力を検査しなかったため、後続処理ではこの失敗がffmpegのENOENTに化けていた。runごとにuserDataを分離し、exit 0でも出力が無い場合を失敗として扱うことで根治した。Windowsのelectron-builder NSIS per-user既定導入先は`%LOCALAPPDATA%\Programs\@akari-videoshell`である。
 
+v0.1.25では、contribution方式がランタイムの同梱漏れに遭遇すると、起動途中の`app.exit(1)`がSIGTRAP / Windowsの`0x80000003`に化けた。同梱が揃っていても、Theiaの`window-all-closed`から始まるquitとOSRランタイムのウィンドウ生成が競合し得る構造だった。2026-08-29に`electron-entry.js`方式へ移行し、`--render`をTheia起動前に捕捉してこの競合を除去した。
+
+### 11.5 インストール済みアプリ経由の第 1 段は起動処理と競合して落ちる（2026-08-29 追記）
+
+v0.1.26 の実ビルド（署名有効・未改変）で実証: インストール済みの AKARI Video を `--render` 付きで起動すると、
+`akari-osr-export` contribution が初期ウィンドウを destroy した直後に Theia の `handleMainCommand` →
+`openDefaultWindow` が destroy 済みウィンドウへ `loadURL` して `TypeError: Object has been destroyed`（未処理 rejection）→
+V8 fatal → SIGTRAP（exit 133 / Windows `0x80000003`）となり、PROGRESS 0 行で終わる。§11.4 の単一インスタンスロック解消後も
+残る、contribution 方式の構造的な競合（`window-all-closed` → `app.quit()` とも競合し得る）。この経路（tier 1 の既定候補）は
+fieldtest / 検収に receipt が 1 件も無く、一度も動いていない。
+
+v0.1.27 からの挙動: `resolveOsrLauncher`（製品入口）はインストール済みアプリを既定で候補から外す
+（`allowInstalledDesktop: false`）。`AKARI_OSR_ELECTRON` の明示指定は従来どおり tier 1。npm Electron（tier 2）が無い
+パッケージ版では tier 3 = legacy へ警告付きで落ち、provenance に `engine_fallback` と理由が残る（`auto` / `osr` とも）。
+根本修正 = `--render` を Theia より前に捕捉する書き出し専用の Electron 入口（別票）。入口が入ったら既定を戻す。
+
+**2026-08-29 追記（根治）**: 書き出し専用の入口 `apps/shell/electron-entry.js` が合流した（§6 / §11.4）。`resolveOsrLauncher` の既定を戻し、インストール済みアプリを再び tier 1 の候補にする（v0.1.28〜）。`allowInstalledDesktop: false` は明示の opt-out として残す。
+
 ## 12. GPU 直結出口との共有境界（2026-08-28 追記）
 
 [GPU 直結書き出し v0](./contract-2026-08-28-gpu-export-v0.md) は、本契約の launcher 3 段、static

package/vendor/docs/contract-2026-08-28-v2-audio-roles-v0.md

@@ -121,3 +121,22 @@ ms へ換算し、絶対値で集計する。全 59 点の最大は 16.667 ms、
 
 これらの近似を残しても、タイムライン上の開始、trim、loop、gain、fade、ducking 対象区間は
 同じ決定論的予定表から再現できなければならない。
+
+## 6. 撮影素材の台詞と ducking 側鎖
+
+`speech` は cuts[] の撮影素材に含まれる音声を表し、各カットの trim / speed / freeze を
+出力タイムラインへ投影して Web Audio プレビューへ供給する。ただし `speech` は ducking の
+側鎖へ入れない。書き出しの `sidechaincompress` で鍵入力になるのは narration のみであり、
+土台カット音声 `[0:a]` は鍵ではないため、プレビューも同じ対象区間を維持する。
+
+## 7. 速度変更した台詞のピッチ保持サイドカー
+
+`speed` が 1 以外の撮影素材の台詞は、Web Audio の `playbackRate` による近似から外す。
+プレビュー前に対象カットの `[in, out)` を ffmpeg で切り出し、render-cut と同じ
+`atempo` チェーンを適用した 48 kHz / `pcm_s16le` WAV を一度だけ生成する。チャンネル数は
+元音声を保ち、プレビューではこの短い WAV を offset 0・`playbackRate = 1` で再生する。
+
+生成物は案件内の `.akari/cache/speech-atempo/` に置く。キーは素材の実体情報、trim、speed、
+`atempo` チェーンから決まり、同じ入力は再生成しない。生成またはデコードに失敗した項目だけは
+警告を 1 行出して従来の `playbackRate` 経路へ退避し、映像および他の音声のプレビューを止めない。
+したがって §5 の「残す近似」に速度変更した台詞のピッチ差は含めない。