akari-video 0.1.13 → 0.1.14

package/bin/akari.mjs

@@ -11,14 +11,19 @@ import { runCapabilityCommand } from '../src/capability-command.mjs';
 import { runStoreCommand } from '../src/store-command.mjs';
 import { runAssetsCommand } from '../src/assets-command.mjs';
 import { runMigrateCommand } from '../src/migrate-command.mjs';
-import { maybeApplyPendingUpdateOnLaunch, readOwnVersion } from '../src/update-check.mjs';
-import { describeCliHelp } from '../src/messages.mjs';
+import { maybeApplyPendingUpdateOnLaunch, resolveInstalledVersionInfo } from '../src/update-check.mjs';
+import { describeCliHelp, describeInstalledVersions } from '../src/messages.mjs';
 
 // `akari --version` / `-v`: インストール済みの版を表示するだけの最小コマンド
 // （タスク契約 2026-08-11-update-u4-cli-self-update の受け入れ条件 —
 // `akari update` / `--rollback` 後にインストール先の版を観測する手段として必要）。
 async function printVersion() {
-  console.log(`v${readOwnVersion()}`);
+  const versionInfo = resolveInstalledVersionInfo({ env: process.env });
+  // 1 行目は update / rollback の既存機械観測契約として CLI 版だけを維持する。
+  console.log(`v${versionInfo.cliVersion}`);
+  for (const line of describeInstalledVersions(versionInfo)) {
+    console.log(line);
+  }
   return { exitCode: 0 };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "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/cli.mjs

@@ -6,7 +6,7 @@ import { resolveLauncherAssets } from './repo-assets.mjs';
 import { detectProjectState } from './project-state.mjs';
 import { findClaudeExecutable, findOpencodeExecutable } from './path-lookup.mjs';
 import { loadTaskLabels } from './task-labels.mjs';
-import { describeInstalledVersions, describeIntake, claudeMissingGuidance, opencodeMissingGuidance, describeUpdateCommand, describeVersionStatus, formatUpdateNotice } from './messages.mjs';
+import { describeForceReinstall, describeInstalledVersions, describeIntake, claudeMissingGuidance, opencodeMissingGuidance, describeUpdateCommand, describeVersionStatus, formatUpdateNotice } from './messages.mjs';
 import { resolveEffectiveProjectRoot } from './first-run.mjs';
 import { maybeShowAssetIntroNotice } from './sounds-setup.mjs';
 import {
@@ -14,9 +14,9 @@ import {
   compareVersions,
   isValidFeedShape,
   readCacheSync,
-  readInstalledAppVersion,
   readOwnVersion,
   recordDismissalSync,
+  refreshUpdateFeed,
   resolveCachePath,
   resolveInstalledVersionInfo,
   triggerBackgroundRefresh
@@ -188,8 +188,8 @@ function defaultSpawnOpencode(opencodePath, args, projectRoot) {
  * 自己更新を試みず、キャッシュに載っている最新版の通知を今後出さないよう記録するだけ
  * （既存挙動を維持）。`--force` は同じ版の本体も再導入し、`--rollback` は直前 1 世代
  * （`~/.akari/app-previous/`）へ戻す。
- * ネットワークに触れるのは自己更新の DL 区間のみ — フィード自体は既存キャッシュ由来
- * （最新情報は `akari` 起動時のバックグラウンド fetch で更新される）。
+ * 通常時にネットワークへ触れるのは自己更新の DL 区間のみ。`--force` だけはキャッシュが
+ * 未取得なら、復旧経路を塞がないためフィードの同期取得を 1 回試す。
  */
 export async function runUpdateCommand(args, options = {}) {
   const log = options.log ?? ((line) => console.log(line));
@@ -197,7 +197,7 @@ export async function runUpdateCommand(args, options = {}) {
   const versionInfo = resolveCommandVersionInfo(options, env);
   const currentVersion = versionInfo.currentVersion;
   const cachePath = resolveCachePath(env);
-  const cache = readCacheSync(cachePath);
+  let cache = readCacheSync(cachePath);
   const dismissRequested = args.includes('--dismiss');
   const rollbackRequested = args.includes('--rollback');
   const forceRequested = args.includes('--force');
@@ -219,10 +219,15 @@ export async function runUpdateCommand(args, options = {}) {
     return { exitCode: 0 };
   }
 
+  if (forceRequested && !cache?.feed) {
+    await (options.refreshUpdateFeed ?? refreshUpdateFeed)({ env, fetchImpl: options.fetchImpl });
+    cache = readCacheSync(cachePath);
+  }
+
   const feed = cache?.feed;
   const updateAvailable = isValidFeedShape(feed) && compareVersions(feed.product, currentVersion) > 0;
   const reinstallRequested = forceRequested && isValidFeedShape(feed) && compareVersions(feed.product, currentVersion) >= 0;
-  const hasManagedApp = !!readInstalledAppVersion(env);
+  const hasManagedApp = versionInfo.managedApp === true;
   const selfUpdateEligible = (updateAvailable || reinstallRequested)
     && !!feed.components?.app?.url
     && !!feed.components?.app?.sha256
@@ -240,7 +245,7 @@ export async function runUpdateCommand(args, options = {}) {
   }
   log(`最新バージョン: v${feed.product}`);
   if (forceRequested) {
-    log(`--force: 本体 v${currentVersion} を入れ直します。`);
+    log(describeForceReinstall(versionInfo, feed.product));
   }
 
   return (options.applySelfUpdate ?? applySelfUpdate)({

package/src/messages.mjs

@@ -90,6 +90,14 @@ export function describeVersionStatus(versionOrInfo, cache) {
 
 export function describeInstalledVersions(versionOrInfo) {
   const info = normalizeVersionInfo(versionOrInfo);
+  if (info.installRefNeedsRepair) {
+    const installRefPath = info.installRefPath ?? '~/.akari/app/.akari-install-ref';
+    return [
+      `CLI バージョン: v${info.cliVersion}`,
+      `本体版を判定できません（\`${installRefPath}\` が壊れています）。`,
+      '修復するには `akari update --force` を実行してください。'
+    ];
+  }
   if (!info.appVersion) {
     return [
       `現在のバージョン: v${info.currentVersion}`,
@@ -104,6 +112,13 @@ export function describeInstalledVersions(versionOrInfo) {
   return lines;
 }
 
+export function describeForceReinstall(versionOrInfo, targetVersion) {
+  const info = normalizeVersionInfo(versionOrInfo);
+  return info.installRefNeedsRepair
+    ? `--force: 版を判定できない本体 → v${targetVersion} を入れ直します。`
+    : `--force: 本体 v${info.currentVersion} → v${targetVersion} を入れ直します。`;
+}
+
 function normalizeVersionInfo(value) {
   if (typeof value === 'string') {
     return { cliVersion: value, appVersion: null, currentVersion: value, mismatch: false };
@@ -112,11 +127,15 @@ function normalizeVersionInfo(value) {
 }
 
 function versionRelationLabel(info) {
-  return compareVersions(info.appVersion, info.cliVersion) < 0 ? '本体が古い' : 'CLI と本体の版が不一致';
+  return compareVersions(info.appVersion, info.cliVersion) < 0 ? '本体が古い' : 'CLI が古い';
 }
 
 function formatVersionMismatch(info) {
-  return `⚠ CLI v${info.cliVersion} / 本体 v${info.appVersion} → ${versionRelationLabel(info)}。\`akari update\` で本体を更新してください。`;
+  const relation = versionRelationLabel(info);
+  const guidance = relation === '本体が古い'
+    ? '`akari update` で本体を更新してください。'
+    : '`npm i -g akari-video@latest` で CLI を更新してください。';
+  return `⚠ CLI v${info.cliVersion} / 本体 v${info.appVersion} → ${relation}。${guidance}`;
 }
 
 /**
@@ -168,6 +187,11 @@ export function describeUpdateCommand({ currentVersion, versionInfo, cache, dism
     lines.push(`リリースノート: ${feed.notes_url}`);
   }
 
+  if (info.installRefNeedsRepair) {
+    lines.push('本体版を判定できないため、更新判定を行いません。');
+    return lines;
+  }
+
   if (compareVersions(feed.product, info.currentVersion) <= 0) {
     lines.push('お使いのバージョンは最新です。');
     return lines;

package/src/update-check.mjs

@@ -65,29 +65,49 @@ export function readOwnVersion() {
   return JSON.parse(raw).version;
 }
 
+/** install-ref を「有効・未記録・破損」の 3 状態で読む内部表現。 */
+function readInstalledAppVersionInfo(env = process.env) {
+  const path = resolveInstallRefPath(env);
+  try {
+    const raw = readFileSync(path, 'utf8').trim();
+    const match = raw.match(/^v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)$/);
+    return match
+      ? { status: 'valid', version: match[1], path }
+      : { status: 'invalid', version: null, path };
+  } catch (error) {
+    return {
+      status: error?.code === 'ENOENT' ? 'missing' : 'invalid',
+      version: null,
+      path
+    };
+  }
+}
+
 /**
  * 実際に render-cut / edit-lint を実行する本体の導入版。
- * install.sh / self-update.mjs が書く `vX.Y.Z` を読み、無い・壊れている場合は null。
+ * install.sh / self-update.mjs が書く `vX.Y.Z` を読む。互換 API として版または null を返し、
+ * 未記録と破損の区別は `resolveInstalledVersionInfo()` が保持する。
  */
 export function readInstalledAppVersion(env = process.env) {
-  try {
-    const raw = readFileSync(resolveInstallRefPath(env), 'utf8').trim();
-    const match = raw.match(/^v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)$/);
-    return match?.[1] ?? null;
-  } catch {
-    return null;
-  }
+  return readInstalledAppVersionInfo(env).version;
 }
 
 /** 更新判定に使う版と、CLI / 本体のずれを一度に解決する。 */
 export function resolveInstalledVersionInfo({ env = process.env, cliVersion = readOwnVersion() } = {}) {
-  const installedAppVersion = readInstalledAppVersion(env);
+  const installRef = readInstalledAppVersionInfo(env);
+  const installedAppVersion = installRef.version;
   const currentVersion = installedAppVersion ?? cliVersion;
   return {
     cliVersion,
     appVersion: installedAppVersion,
     currentVersion,
-    source: installedAppVersion ? 'install-ref' : 'cli-fallback',
+    source: installRef.status === 'valid'
+      ? 'install-ref'
+      : installRef.status === 'invalid' ? 'invalid-install-ref' : 'cli-fallback',
+    installRefStatus: installRef.status,
+    installRefPath: installRef.path,
+    installRefNeedsRepair: installRef.status === 'invalid',
+    managedApp: installRef.status !== 'missing',
     mismatch: installedAppVersion !== null && compareVersions(cliVersion, installedAppVersion) !== 0
   };
 }
@@ -135,8 +155,18 @@ function writeCacheSync(cachePath, cache) {
 /**
  * キャッシュと現在版から、新版通知を出すべきかを判定する（同期・純粋関数・I/O なし）。
  */
-export function evaluateUpdateStatus({ currentVersion, cache, cliVersion = currentVersion, appVersion = null, source = 'cli-fallback', mismatch = false }) {
-  const versionDetails = { currentVersion, cliVersion, appVersion, source, mismatch };
+export function evaluateUpdateStatus({ currentVersion, cache, cliVersion = currentVersion, appVersion = null, source = 'cli-fallback', installRefStatus, installRefPath, installRefNeedsRepair, managedApp, mismatch = false }) {
+  const versionDetails = {
+    currentVersion,
+    cliVersion,
+    appVersion,
+    source,
+    installRefStatus,
+    installRefPath,
+    installRefNeedsRepair,
+    managedApp,
+    mismatch
+  };
   const feed = cache?.feed;
   if (!isValidFeedShape(feed)) {
     return { available: false, ...versionDetails };
@@ -215,16 +245,8 @@ export async function maybeStageInBackground({ env = process.env, feed, fetchImp
   return stageSelfUpdate({ env, feed, log: () => {}, fetchImpl, timeoutMs, extract });
 }
 
-/**
- * バックグラウンド fetch 本体。fetch 失敗・非 200・JSON パース失敗・スキーマ不明は
- * すべて沈黙して return する（何も throw しない）。`dismissed` は既存キャッシュから
- * 引き継ぐ（fetch のたびに既読状態が消えないように）。
- *
- * フィード取得・キャッシュ反映が成功した後、契約 §11 のバックグラウンド staging も
- * 同じ沈黙原則のもとで試みる（`maybeStageInBackground`）。成功したときだけ
- * キャッシュへ `staged`（版・sha256・staged_at）を追記する。
- */
-export async function runBackgroundFetch({ env = process.env, fetchImpl = globalThis.fetch, launcherRoot } = {}) {
+/** フィードを 1 回取得し、正常なら既読状態を保ったままキャッシュへ反映する。 */
+export async function refreshUpdateFeed({ env = process.env, fetchImpl = globalThis.fetch } = {}) {
   const feedUrl = resolveFeedUrl(env);
   const cachePath = resolveCachePath(env);
   try {
@@ -241,15 +263,34 @@ export async function runBackgroundFetch({ env = process.env, fetchImpl = global
     }
     const feed = await response.json();
     if (!isValidFeedShape(feed)) {
-      return;
+      return null;
     }
     const existing = readCacheSync(cachePath);
-    writeCacheSync(cachePath, {
+    const next = {
       schema: CACHE_SCHEMA,
       fetched_at: new Date().toISOString(),
       feed,
       dismissed: existing?.dismissed ?? {}
-    });
+    };
+    writeCacheSync(cachePath, next);
+    return next;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * バックグラウンド fetch 本体。フィード取得失敗は沈黙し、成功後は契約 §11 の staging を
+ * 同じ沈黙原則で試す。成功したときだけキャッシュへ `staged` を追記する。
+ */
+export async function runBackgroundFetch({ env = process.env, fetchImpl = globalThis.fetch, launcherRoot } = {}) {
+  const cachePath = resolveCachePath(env);
+  try {
+    const refreshed = await refreshUpdateFeed({ env, fetchImpl });
+    const feed = refreshed?.feed;
+    if (!feed) {
+      return;
+    }
 
     const staged = await maybeStageInBackground({ env, feed, fetchImpl, launcherRoot });
     if (staged?.ok) {

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

@@ -40,6 +40,7 @@
     "docs/contract-2026-08-13-avatar-drive-v0.md",
     "docs/contract-2026-08-14-avatar-vrm-v0.md",
     "docs/contract-2026-08-18-v1-render-parity.md",
+    "docs/contract-2026-08-23-stroke-persistence.md",
     "packages/akari-launcher/package.json",
     "packages/akari-launcher/README.md",
     "packages/akari-tools/package.json",

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

@@ -66,7 +66,7 @@
 
 ## 5. §2 追記 — sfx フェード（audio-clip-fades, 2026-08-18・オーナー裁定「クリップ主義」T2）
 
-BGM をクリップ化する裁定（内部リポ `tasks/2026-08-18-bgm-clip-placement-ruling`）に伴い、
+BGM をクリップ化する裁定（内部リポ `akari-video-internal` の該当タスク）に伴い、
 「音楽をクリップ（audio.sfx[]）として置いても BGM ベッドと同じフェード表現ができる」を
 満たすため、`sfxItem` に optional の `fade_in` / `fade_out`（秒・0 以上）を追加のみ拡張する
 （`version` 不変・`contract-2026-07-17-data-contract-versioning.md` の原則に従う）。

package/vendor/docs/contract-2026-08-23-stroke-persistence.md

@@ -0,0 +1,75 @@
+---
+lifecycle: implemented
+created: 2026-08-23
+updated: 2026-08-23
+---
+
+# 注釈ストローク永続表示契約
+
+- 日付: 2026-08-23
+- 状態: **実装済み**
+- 前提: `contract-2026-08-11-review-session-ui-events.md`、
+  `contract-2026-07-20-review-json-v1-annotation-model.md`
+- スコープ: Theia shell の出力プレビュー、review session の `strokes.json` 読み出し、
+  compile-review-session と address-review の追跡導線
+
+## 1. セッション中の表示
+
+- pen / rect は従来どおり正規化座標（プレビューフレーム左上を `(0, 0)`、右下を `(1, 1)`）で
+  記録する。表示時に現在の content rect へ写像し直すため、ウィンドウのリサイズと出力比率の
+  変更で座標は変わらない。
+- pointerup 後は従来のグロー・きらめき・600 ms フェードをそのまま再生し、その後段の静的
+  ビットマップへ同じ正規化図形を残す。新しい録音セッションの開始時に前セッションの表示を
+  クリアし、録音終了では消さない。
+- 描線 canvas は非描画モードで `pointer-events: none` とする。ペンまたは四角モードのドラッグ中
+  だけ既存どおり入力面になる。
+- 注釈パネルの「描線を表示」チェックは既定 ON。OFF は残留描線と明示的に再表示した描線を隠し、
+  データを削除しない。ON に戻すと保持した正規化座標から即時再描画する。
+
+## 2. 既存セッションの読み出しと再表示
+
+`readReviewSessionStrokes({projectRootUri, sessionId})` は
+`review/sessions/<sessionId>/strokes.json` を読み、次を返す。
+
+```jsonc
+{
+  "sessionId": "s-0001",
+  "strokes": [/* pen / rect。frame と recTStart/recTEnd を保持 */],
+  "warnings": []
+}
+```
+
+- `strokes.json` 欠落は `strokes: []` として正常終了する。
+- 配列ルート、または `version: 1` でない `{strokes:[]}` は旧形式として寛容に読む。
+- JSON 破損、未知要素、値域外要素は描線単位で除外して warning に残す。セッション一覧と他の
+  描線を巻き込んで失敗させない。
+- 注釈パネルの各録音済みセッションにある「描線」から再表示できる。表示メッセージには
+  `target.tab`（edit URI）と先頭ストロークの `target.recT` を添え、`frame.sourceT/cutIndex` で
+  プレビューを同じフレームへシークする。
+
+## 3. compile 後の原本参照
+
+review.json の data `version` は 0 のまま据え置く。compile-review-session はペアになった pen / rect
+へ、既存フィールドを変えず次の任意フィールドを追加する。
+
+```jsonc
+"strokeRefs": [{
+  "sessionId": "s-0001",
+  "strokeId": "st-0001",
+  "sessionRef": "s-0001/st-0001"
+}]
+```
+
+- `strokeRefs` は `null`、省略、または 1 件以上の配列。欠落は従来データとして正常である。
+- pen は従来どおり最大 100 点の `strokes[].points` も埋め込み、`strokeRefs` から無加工の原本へ
+  戻れる。rect は従来どおり `targetKind:"region"` + `region.box` を埋め込み、同じ `strokeRefs`
+  から `strokes.json` 内の rect 原本へ戻れる。
+- address-review の一覧は `strokeRefs` を
+  `review/sessions/<sessionId>/strokes.json#<strokeId>` として表示する。
+
+## 4. 互換性
+
+- 追加フィールドのみを使い、既存フィールドの削除・意味変更・data version bump は行わない。
+- 読み手は未知フィールドを保持し、任意フィールドの欠落を旧データとして扱い、既知より大きい
+  data version を推測変換しない。
+- `packages/preview-server` は本契約の対象外であり、WebUI の表示挙動は変更しない。

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

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "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/decision-cards/README.md

@@ -9,6 +9,7 @@
 |---|---|
 | `report-helper.mjs` | `127.0.0.1` のみにバインドするローカル HTTP ヘルパー。`report.html` の配信・`decisions.json` の read/write・commit を仲介する |
 | `report-template.html` | data 属性でカードを宣言する report.html の雛形。単選・真偽チェック・整数スライダ・配列型の複数選択に対応する。カード種別のハードコードなし。ヘルパー経由なら操作可能、`file://` 直開き等で fetch 失敗時は全操作ボタンが disabled になり案内文言を出す（安全劣化） |
+| `render-research-plan-report.mjs` | `research-plan.json` から固定 5 面の自己完結 HTML を生成する。絵コンテ面は画像 / 文字プレースホルダーのカード面と、主軸 + カットアウェイの読み取り専用 SVG 構造面を切り替えられる |
 | `examples/report.html` + `examples/report.html.decisions.json` | 動作サンプル一式（既存 4 カード + `direction`）。AI 推奨を既定値に入れた `decisions.json` 雛形付き |
 | `test/direction-card.test.mjs` | ローカル Chrome を headless 起動して、演出カードの保存と既存 4 カードの非退行を実測するテスト |
 
@@ -54,6 +55,17 @@ curl -X POST http://127.0.0.1:8791/api/commit
 npm test --workspace @akari-video/decision-cards
 ```
 
+### research-plan のビジュアル絵コンテ
+
+```sh
+node packages/decision-cards/render-research-plan-report.mjs \
+  planning/research-plan.json \
+  planning/research-plan-report.html
+node packages/decision-cards/report-helper.mjs planning/research-plan-report.html
+```
+
+画像は生成時に data URI へ埋め込むため、出力 HTML は外部依存を持たない。`image_path` が無い、または画像を読めないショットは `shot_type` + `description` のプレースホルダーへ安全に劣化する。旧形式に `sequence` / `cutaway_of` が無い場合も生成は成功し、構造面だけが「構造情報なし」になる。
+
 ## edit-plan スキルからの参照方法
 
 公開リポの `.claude/skills/edit-plan/` は本パッケージを以下のように参照する想定:

package/vendor/packages/decision-cards/package.json

@@ -2,7 +2,7 @@
   "name": "@akari-video/decision-cards",
   "version": "0.0.0",
   "private": true,
-  "description": "決定カード v0 ランタイム。report-helper（ローカル HTTP サーバ）+ report-template（カード付きレポート HTML の雛形）+ 動作サンプル。外部 npm 依存ゼロ（Node.js 組み込みモジュールのみ）。 [akari-video npm vendor: report-helper.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.]",
+  "description": "決定カード v0 ランタイム。report-helper（ローカル HTTP サーバ）+ report-template（カード付きレポート HTML の雛形）+ 動作サンプル。外部 npm 依存ゼロ（Node.js 組み込みモジュールのみ）。 [akari-video npm vendor: report-helper.mjs is reference-only; render-research-plan-report.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",
   "scripts": {
     "start": "node report-helper.mjs",
@@ -11,7 +11,8 @@
   "akariVideoVendor": {
     "execution": "reference-only",
     "omittedBin": {
-      "decision-cards-helper": "report-helper.mjs"
+      "decision-cards-helper": "report-helper.mjs",
+      "research-plan-report": "render-research-plan-report.mjs"
     },
     "guidance": "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."
   }

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

@@ -19,6 +19,8 @@ import { musicGrid } from "../../audio-library-setup/shared/beat-grid.mjs";
 import { resolveFfmpeg, resolveFfprobe } from "../../media-bin/src/index.mjs";
 
 const {
+  areCutsAdjacent,
+  findUnsupportedDeclaredTrackTransitions,
   projectLegacyEdit,
   readInternalEdit,
   resolveCaptionDisplay,
@@ -253,7 +255,7 @@ export async function lintProject(input, options = {}) {
   validateStillImageCuts(edit, findings);
   const cutTrackSegments = computeCutTrackSegments(edit.cuts);
   for (const segment of findTrackOverlaps(cutTrackSegments)) {
-    if (isDeclaredTransitionOverlap(edit.cuts, cutTrackSegments, segment)) continue;
+    if (isDeclaredTransitionOverlap(edit.cuts, cutTrackSegments, segment, edit.fps)) continue;
     addFinding(findings, {
       severity: "error",
       check: "cuts.track-overlap",
@@ -351,7 +353,11 @@ function collectAudioOnlySourceIds(edit) {
 
 function collectInternalAudioTrackRefs(internalEdit) {
   return new Set(internalEdit.tracks
-    .filter(track => track.lane === "audio" && track.items.length > 0)
+    // v2 top-level audio は読み込み層が implicit audio track へ射影するが、元データに
+    // tracks[] 宣言は無い。これを実段として数えると declaration-missing が必ず出る。
+    // validateTimelineTracks が照合する相手は projectLegacyEdit の declaredTracks なので、
+    // 実データ側も同じ declared origin に限定して投影ノイズを除く。
+    .filter(track => track.origin === "declared" && track.lane === "audio" && track.items.length > 0)
     .map(track => Number.isInteger(track.legacy.ref) ? track.legacy.ref : 0));
 }
 
@@ -878,15 +884,18 @@ function findTrackOverlaps(segments) {
 // render correctly would still fail lint. Still rejects zero/negative overlap (a genuine gap --
 // no transition is physically possible) and overlap greater than declared (an unrelated shape
 // render-cut does not auto-adjust for -- see effectiveTransitionDurations' own comment).
-function isDeclaredTransitionOverlap(cuts, segments, current) {
+function isDeclaredTransitionOverlap(cuts, segments, current, fps) {
   const previous = segments
     .filter(segment => segment.track === current.track && segment.index < current.index)
     .sort((left, right) => right.index - left.index)[0];
   if (!previous) return false;
   const duration = cuts?.[previous.index]?.transition_out?.duration;
   if (!isPositiveNumber(duration)) return false;
-  const availableOverlap = previous.end - current.start;
-  return availableOverlap > EPSILON && availableOverlap <= duration + EPSILON;
+  return areCutsAdjacent(
+    { tlEnd: previous.end, transitionOut: { duration } },
+    { tlStart: current.start },
+    fps,
+  );
 }
 
 function validateCutTrackFields(cuts, findings) {
@@ -1255,15 +1264,16 @@ function validateTimelineTracks(edit, findings, projectedAudioTracks = null) {
     const ref = item.kind === "audio" && !hasRef ? 0 : item.ref;
     if (ref === undefined) continue;
     declarations.add(`${item.kind}:${ref}`);
-    if (!actualTracks.get(item.kind)?.has(ref)) {
-      addFinding(findings, {
-        severity: "warning",
-        check: "timeline.tracks.ref-missing",
-        message: `${item.kind} timeline track ref ${ref} is not used by edit data`,
-        path: `${path}.ref`,
-      });
-    }
   }
+  // ここには以前 `timeline.tracks.ref-missing`（宣言された段の ref が実データのどこにも
+  // 現れなければ警告）があったが、2026-08-20 に撤去した。v2 では timeline.tracks[] の各段が
+  // internal-model.ts の projectLegacyEdit を通じてそのまま legacy 射影され、ref は宣言順に
+  // 毎回生成し直される連番なので、「宣言はあるが実データに現れない ref」は「段の中身が 0 個」
+  // としか等価にならない。空の段は自動 prune せず残すのが正本（10番裁定 E）なので、この
+  // チェックは空の段を持つ v2 プロジェクトのたびに必ず誤検知していた。v0/v1 は本体から既に
+  // 除かれており（9番）、「(kind, ref) の参照」という v0/v1 由来の概念自体が v2 には無いため
+  // 部分修正ではなく撤去する。撤去の証跡は edit-lint.test.mjs の
+  // "空の段を持つ v2 プロジェクトは findings 0" で固定してある。
 
   for (const [kind, tracks] of actualTracks) {
     for (const ref of tracks) {
@@ -1295,56 +1305,27 @@ function validateTimelineTracks(edit, findings, projectedAudioTracks = null) {
 // too wide a blast radius to take on speculatively, especially with no evidence anyone needs the
 // combination. Reject it instead: it fails loudly and specifically, rather than rendering a
 // broken video with a phantom black flash that's very hard to trace back to its cause.
-function validateTrackTransitionOutCompatibility(edit, findings) {
-  if (!Array.isArray(edit?.cuts)) return;
-  const tracks = edit?.timeline?.tracks;
-  if (!Array.isArray(tracks)) return; // malformed timeline.tracks is already reported by validateTimelineTracks
-  if (usesDefaultCompatibilityTrackOrder(tracks)) return;
-
-  const cutsTrackRefs = new Set(
-    tracks
-      .filter((item) => isRecord(item) && item.kind === "cuts" && Number.isInteger(item.ref) && item.ref >= 0)
-      .map((item) => item.ref),
-  );
-  for (const ref of cutsTrackRefs) {
-    const trackCuts = edit.cuts
-      .map((cut, index) => ({ cut, index }))
-      .filter(({ cut }) => isRecord(cut) && (cut.track ?? 0) === ref);
-    // The last cut on a track has no following same-track cut to blend into, so its own
-    // transition_out (if any) never renders -- mirrors buildMultiSourceCutCommand's own
-    // hasAnyTransition check (plan.mjs) and predictedDuration's overlap accounting.
-    for (const { cut, index } of trackCuts.slice(0, -1)) {
-      if (!cut.transition_out) continue;
-      addFinding(findings, {
-        severity: "error",
-        check: "cuts.track-transition-unsupported",
-        message:
-          `cuts[].transition_out is declared on track ${ref}, which timeline.tracks composites through the `
-          + `gap-aware track engine. That engine treats adjacent same-track cuts as separate, non-overlapping `
-          + `windows, so it cannot represent an xfade's intentional overlap -- the composited window and the `
-          + `actually-shrunk clip diverge, and content disappears early (verified with a real render: the base `
-          + `track's background visibly leaked through where the dissolved clip should still have been `
-          + `playing). Remove transition_out from this track's cuts, or drop the custom timeline.tracks order `
-          + `for this track so it renders through the plain sequential path instead.`,
-        path: `edit.json#cuts[${index}]`,
-      });
-    }
+export function validateTrackTransitionOutCompatibility(edit, findings) {
+  for (const { cutIndex, trackRef } of findUnsupportedDeclaredTrackTransitions(
+    edit?.cuts,
+    edit?.timeline?.tracks,
+  )) {
+    addFinding(findings, {
+      severity: "error",
+      check: "cuts.track-transition-unsupported",
+      message:
+        `cuts[].transition_out is declared on track ${trackRef}, which timeline.tracks composites through the `
+        + `gap-aware track engine. That engine treats adjacent same-track cuts as separate, non-overlapping `
+        + `windows, so it cannot represent an xfade's intentional overlap -- the composited window and the `
+        + `actually-shrunk clip diverge, and content disappears early (verified with a real render: the base `
+        + `track's background visibly leaked through where the dissolved clip should still have been `
+        + `playing). Remove transition_out from this track's cuts, or drop the custom timeline.tracks order `
+        + `for this track so it renders through the plain sequential path instead.`,
+      path: `edit.json#cuts[${cutIndex}]`,
+    });
   }
 }
 
-function usesDefaultCompatibilityTrackOrder(tracks) {
-  const rank = new Map([["cuts", 0], ["layers", 1], ["overlays", 2], ["captions", 3], ["audio", 4]]);
-  const keys = tracks.map((track, index) => ({
-    kind: track?.kind,
-    ref: Number.isInteger(track?.ref) ? track.ref : -1,
-    index,
-  }));
-  if (keys.some(key => !rank.has(key.kind))) return false;
-  const expected = [...keys].sort((left, right) =>
-    rank.get(left.kind) - rank.get(right.kind) || left.ref - right.ref || left.index - right.index);
-  return keys.every((key, index) => key.index === expected[index].index);
-}
-
 function collectActualTrackNumbers(items) {
   const tracks = new Set();
   if (!Array.isArray(items)) return tracks;

package/vendor/packages/edit-store/lib/cut-adjacency.d.ts

@@ -0,0 +1,19 @@
+/**
+ * cuts 配列順で隣り合う同一トラックの 2 クリップが、トランジション UI を持てる境界か判定する。
+ * タイムライン UI と edit-lint は必ずこの関数を使い、フレーム量子化の条件式を複製しない。
+ */
+export interface CutAdjacencyTransitionLike {
+    duration?: unknown;
+}
+export interface CutAdjacencyEarlierLike {
+    tlEnd: number;
+    transitionOut?: CutAdjacencyTransitionLike | null;
+}
+export interface CutAdjacencyLaterLike {
+    tlStart: number;
+}
+/**
+ * ギャップ 0、または earlier の宣言済み transitionOut.duration で説明できる重なりだけを
+ * 隣接とみなす。秒の誤差ではなく、出力 fps で量子化したフレーム数を比較する。
+ */
+export declare function areCutsAdjacent(earlier: CutAdjacencyEarlierLike, later: CutAdjacencyLaterLike, fps?: number): boolean;